feat(agent): add agent supported features

.github/actions/build-pyinstaller-bundle/action.yml

@@ -76,6 +76,11 @@ runs:
         "$SMOKE_DIR/ecc" --help
         "$SMOKE_DIR/ecc" --version
         "$SMOKE_DIR/ecc" version --json
+        test -x "$SMOKE_DIR/ecc-agent-rpc"
+        test "$SMOKE_DIR/ecc" -ef "$SMOKE_DIR/ecc-agent-rpc"
+        payload='{"jsonrpc":"2.0","method":"rpc.hello","id":1,"params":{"version":1}}'
+        response="$(printf 'Content-Length: %s\r\n\r\n%s' "${#payload}" "$payload" | "$SMOKE_DIR/ecc-agent-rpc")"
+        grep -q 'candidate.rerun' <<<"$response"
         "$SMOKE_DIR/ecc" doc config --plain > /dev/null
         "$SMOKE_DIR/ecc" doc ug --lang cn --plain > /dev/null
         test -x "$SMOKE_DIR/_internal/torch/bin/torch_shm_manager"

.gitignore

@@ -177,6 +177,7 @@ result
 
 # Generated from uv.lock, not committed
 requirements_lock.txt
+/checklist.json
 
 chipcompiler/tools/ecc_dreamplace/dreamplace
 

agent/README.cn.md

@@ -0,0 +1,63 @@
+# `ecc-agent-rpc` 入口说明
+
+`pyproject.toml` 中的如下声明会在安装 ECC 时生成独立可执行文件：
+
+```toml
+scripts.ecc-agent-rpc = "agent.rpc_server:main"
+```
+
+它是 ECOS Agent 专用的 ECC JSON-RPC 边车进程入口。桌面端或 Agent
+运行时启动该进程，通过标准输入发送请求，并从标准输出读取结果；它不是
+供交互式使用的 `ecc` CLI，也不替代通用的 `ecc rpc serve --stdio`。
+
+## `main()` 做什么
+
+入口实现位于 [`rpc_server.py`](rpc_server.py)。`main()` 保持很小，只完成
+三个启动职责：
+
+1. 调用 `multiprocessing.freeze_support()`，使打包后的 Windows 进程可以安全
+   创建子进程；
+2. 创建 `AgentRuntimeServer`，在通用 ECC runtime 方法之上注册 Agent 方法；
+3. 将二进制 `stdin`/`stdout` 和该 server 交给
+   `chipcompiler.runtime.stdio_server.run_stdio_server()`。
+
+这样，入口不复制 transport、JSON-RPC 分发或业务执行逻辑。传输层统一处理
+请求帧、响应串行写出、`runtime.event` 通知和 `rpc.shutdown`；Agent 行为由
+`AgentRuntimeServer`、`FlowAgentRuntimeApi` 及其受控 workspace API 实现。
+
+## 协议与能力
+
+该进程使用带 `Content-Length` 头的 JSON-RPC 2.0 stdio 协议。标准输出只可写入
+协议帧，诊断和工具输出应写入标准错误或 workspace 日志，避免破坏客户端解码。
+
+`rpc.hello` 返回的 capabilities 包含通用 runtime 方法，以及 Agent 专用方法：
+
+- `agent.runtime_preflight`：检查 Agent 候选执行所需运行时；
+- `workspace.extract_foundation`：提取已完成 workspace 的 foundation 数据；
+- `candidate.export_capabilities`、`candidate.bind_input`、
+  `candidate.materialize`：查询或准备受控候选；
+- `candidate.rerun`、`candidate.resume`：启动或恢复受控候选执行。
+
+方法名、请求模型和处理函数的权威定义在 [`methods.py`](methods.py)。入口收到
+请求后会将 camelCase 字段归一化为请求模型字段；无效字段或重复字段返回
+`invalid_request`，不会转化为任意命令执行。
+
+## 运行边界
+
+`ecc-agent-rpc` 仅暴露已注册的 typed RPC 方法。它不接收自然语言计划、不选择
+优化参数，也不执行调用方提供的任意 shell 命令。候选操作仍由 Agent runtime 的
+参数校验、workspace 边界和执行回执约束。
+
+启动 `AgentRuntimeServer` 时会调用 [`runtime_env.py`](runtime_env.py) 处理可选的
+打包 Sizer 运行时路径；这只准备运行环境，不代表一次 physical-design flow 已
+执行成功。实际客户端应先使用 `rpc.hello` 协商能力，并保留 operation 事件与
+workspace 产物作为执行证据。
+
+## 维护约定
+
+- 新增 Agent RPC 方法时，同时更新 `methods.py` 的 `AGENT_RUNTIME_METHODS`、
+  请求模型、workspace API 和对应测试；`rpc_server.py` 通常无需修改。
+- 修改 stdio framing 或通用 runtime 行为时，应修改 `chipcompiler/runtime/` 并
+  评估 `ecc rpc serve --stdio` 与 `ecc-agent-rpc` 两个入口。
+- 直接调试可运行 `python -m agent.rpc_server`，但输入必须是合法的
+  `Content-Length` JSON-RPC 帧；普通命令行参数不会被解析为 RPC 请求。

agent/README.md

@@ -0,0 +1,152 @@
+# ECC Agent Runtime（`agent/`）
+
+`agent/` 是 ECC 的 **Flow Agent 运行时**：在 `chipcompiler` 标准 runtime 之上构建的
+受控、可审计的流程代理执行层。它以独立 sidecar 进程（可执行入口
+`ecc-agent-rpc`）运行，通过 JSON-RPC 2.0 over stdio 对外提供服务，供
+ECOS Studio 的 GUI 前端与 `ecos_agent` 受控优化后端驱动。
+
+它只做确定性的执行与证据记录：**决策不在这里**。`agent/` 不包含任何 LLM
+代码，不解析自由文本指令，也不直接执行 shell 命令；流程决策由上层
+`ecos_agent`（见 ECOS Studio 仓库）完成，每个动作以显式 schema 的 RPC 方法
+抵达本层，经参数校验与允许列表检查后执行，并留下可复核的产物与回执。
+
+## 职责总览
+
+- **Agent 流程适配**：为 Agent 场景定制流程引擎行为（DRC 阶段注入、观察者
+  事件流、渲染门控、内存监控、无头运行下的绘图抑制）。
+- **隔离候选执行**：为参数候选创建隔离 workspace，配置固化（materialize）、
+  上游输入绑定、独立 worker 进程重跑与断点续跑（resume），产出 hash 绑定的
+  配置/检查点回执。
+- **参数运行时观测**：对五个受控 DREAMPlace 参数与两个受控 Floorplan 参数
+  进行运行时观测，生成 hash 绑定的参数应用回执，供上层做效果归因。
+- **基础数据提取（foundation data）**：从已有 workspace 的 LEF/DEF/STA/DRC/
+  布线证据中提取带表结构契约的可审计数据表，供离线分析与建模使用。
+- **全角 STA 并行**：以隔离的原生进程并行执行全角 STA，并提供调度基准测试。
+
+## 设计原则
+
+1. **受控执行**：每个 RPC 方法都有 frozen dataclass 请求模型与显式校验；
+   客户端按方法允许列表访问；写入 workspace 的路径一律校验不得越界。
+2. **可审计**：候选配置、输入绑定、Floorplan 模式覆盖、参数回执均以
+   canonical JSON + SHA-256 摘要落盘，配置与检查点回执必须配对一致
+   （candidate contract），否则拒绝执行。
+3. **可复现**：候选 workspace 从父 workspace 克隆，重跑集合、输入绑定与
+   配置覆盖全部持久化，resume 复用原候选记录且不改变历史语义。
+4. **进程隔离**：DREAMPlace 与 sizer 存在进程全局状态（配置单例、原生日志
+   重定向），同进程并发候选会互相覆写；候选的阶段循环在独立 worker 进程
+   中执行，全角 STA 同样使用隔离原生进程。
+5. **不反向依赖**：`agent/` 依赖 `chipcompiler` 的公开 runtime 接口并继承
+   扩展，不修改其行为；除观测回执的结构化输入外，不依赖 `ecos_agent`。
+
+## 代码结构
+
+```text
+agent/
+├── rpc_server.py        # 进程入口：stdin/stdout 上启动 stdio JSON-RPC 服务
+├── server.py            # AgentRuntimeServer：扩展基础 RuntimeServer 与能力协商
+├── methods.py           # Agent RPC 方法表（RuntimeMethodSpec 声明）
+├── requests.py          # RPC 请求模型（frozen dataclass + 校验）
+├── workspace_api.py     # AgentWorkspaceRuntimeApi / FlowAgentRuntimeApi：RPC 处理层
+├── engine.py            # AgentEngineFlow：流程引擎覆盖（观察者、渲染门控、监控）
+├── tools.py             # Agent 侧步骤执行适配（固化重放、模式覆盖、STA 分发）
+├── plot.py              # 无头运行下抑制显示绘图的绘图适配
+├── runtime_env.py       # sizer 运行时预检与隔离加载环境
+├── floorplan_mode.py    # 隔离候选的 Floorplan 模式（die_util/die_size）覆盖
+├── candidate_clone.py   # 候选 workspace 克隆的忽略规则
+├── candidate_worker.py  # 隔离 worker 进程中执行候选阶段循环
+├── candidate_resume.py  # 失败候选在原 workspace 上的断点续跑
+├── sta_parallel.py      # 全角 STA 并行调度（隔离原生进程）
+├── sta_benchmark.py     # STA 调度基准测试（隔离副本上比较方案）
+└── data/                # 候选与观测的数据模型、注册表和落盘产物
+    ├── candidate_registry.py             # 受控 knob 与后端需求的静态注册表
+    ├── candidate_capabilities.py         # 稳定的候选能力元数据导出
+    ├── candidate_materialization.py      # 可重放的配置固化与回执校验
+    ├── candidate_input_binding.py        # 受控上游输入绑定（阶段间数据边）
+    ├── candidate_contract.py             # 配置/检查点回执的配对一致性检查
+    ├── candidate_artifacts.py            # canonical JSON、SHA-256、原子写盘工具
+    ├── parameter_runtime_observer.py     # DREAMPlace 五参数运行时观测
+    ├── floorplan_parameter_observer.py   # Floorplan 两参数运行时观测
+    ├── parameter_application_receipt.py  # hash 绑定的参数应用回执生成
+    ├── observed_callable.py              # 保持原属性的观测包装
+    └── foundation/                       # workspace 证据提取子包
+        ├── extractor.py                  # 提取流水线（profile: iccd_full_v1）
+        ├── schema.py                     # ExtractionResult
+        ├── parsers/                      # LEF/DEF/STA/DRC/布线日志等解析器
+        ├── grid/                         # GCell 网格规范化
+        ├── table_contract.py             # 数据表结构契约与写出
+        └── writers.py                    # JSON/JSONL 写出
+```
+
+分层关系：`rpc_server` → `server`（方法分发、错误码映射）→ `methods`/`requests`
+（schema）→ `workspace_api`（Agent RPC 处理器）→ `engine`/`tools`/`candidate_*`
+（执行基础设施）→ `data/*`（注册表、固化与回执落盘）。
+
+## RPC 方法面
+
+`AgentRuntimeServer` 继承基础 runtime 的全部方法（workspace 生命周期、配置
+读写、`flow.run`/`flow.run_step`、operation 状态与取消、快照等，完整清单见
+`chipcompiler/runtime/methods.py` 与 `docs/rpc-guide.md`），并在能力协商
+（`rpc.hello`）中追加声明以下 Agent 方法：
+
+| 方法 | 作用 |
+| --- | --- |
+| `agent.runtime_preflight` | Agent 运行时预检（如 sizer 可执行文件） |
+| `workspace.extract_foundation` | 从 workspace 证据提取 foundation 数据表 |
+| `candidate.export_capabilities` | 导出候选能力元数据（受控 knob、后端需求） |
+| `candidate.bind_input` | 绑定候选的上游输入（阶段间检查点） |
+| `candidate.materialize` | 将候选参数补丁固化为可重放配置 |
+| `candidate.rerun` | 克隆候选 workspace 并在隔离 worker 中重跑目标阶段 |
+| `candidate.resume` | 在原候选 workspace 上断点续跑失败的候选 |
+
+传输与分帧协议与基础 runtime 一致（`Content-Length` 分帧的 JSON-RPC 2.0），
+详见 `docs/rpc-guide.md`。
+
+## 候选重跑生命周期
+
+一次受控候选评估的典型调用序列：
+
+1. **预检**：`agent.runtime_preflight` 确认运行时可用。
+2. **能力导出**：`candidate.export_capabilities` 返回目标阶段允许的受控
+   knob 集合与后端需求，上层只能在该集合内提参数。
+3. **绑定与固化**：`candidate.bind_input` 固定上游输入边；
+   `candidate.materialize` 将参数补丁写入候选配置并生成回执，二者与
+   检查点回执通过 candidate contract 校验配对。
+4. **隔离重跑**：`candidate.rerun` 克隆父 workspace（按忽略规则裁剪产物），
+   在独立 worker 进程中按目标阶段重跑，事件经观察者流式回传，结果与
+   状态摘要落盘。
+5. **续跑**：失败的候选可用 `candidate.resume` 在原 workspace 上继续，
+   保留原候选记录与 Floorplan 模式，不改变历史语义。
+
+Floorplan 模式覆盖（`die_util`/`die_size`）只作用于隔离候选：随请求显式
+给出、持久化到候选 workspace 的 `analysis/floorplan_mode.v1.json`，不影响
+源 workspace 与普通 ECC 流程。
+
+## 客户端与联合契约
+
+本运行时有两个独立实现的客户端，遵守同一契约：
+
+- **Electron 前端**（GUI 流程执行）：
+  `ecos/gui/apps/desktop-electron/electron/services/eccRpc/`
+- **Agent 后端**（受控自动优化）：
+  `ecos/agent/src/ecos_agent/optimization/ecc/rpc_client.py`
+
+传输、超时、错误恢复与可执行文件解析的共同契约见 ECOS Studio 仓库的
+`ecos/agent/docs/ecc-agent-rpc.md`；修改本层的 RPC 表面或事件语义时，须
+同步该文档与两侧客户端。
+
+## 开发与测试
+
+```bash
+# 启动 stdio RPC 服务（等价于 ecc-agent-rpc 入口）
+uv run python -m agent.rpc_server
+
+# 运行本目录测试（与 chipcompiler 的 test/ 互相独立）
+uv run pytest agent/test
+
+# Lint 与格式
+uv run ruff check agent/
+uv run ruff format agent/
+```
+
+测试按被测模块就近放置于 `agent/test/`；foundation 提取器相关的基线数据
+与其表格契约测试同样位于该目录。

agent/candidate_clone.py

@@ -0,0 +1,36 @@
+import json
+from pathlib import Path
+
+from chipcompiler.runtime.workspace_api import RuntimeApiError
+
+_ARTIFACT_DIR_NAMES = frozenset({"output", "data", "feature", "analysis", "report", "log"})
+
+
+def candidate_clone_ignore(source_root: Path, target_step: str | None):
+    skipped_step_roots: set[Path] = set()
+    if target_step is not None:
+        try:
+            flow = json.loads((source_root / "home" / "flow.json").read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise RuntimeApiError("command_failed", "candidate flow state is invalid") from exc
+        if not isinstance(flow, dict) or not isinstance(flow.get("steps"), list):
+            raise RuntimeApiError("command_failed", "candidate flow state is invalid")
+        rerun = False
+        for step in flow.get("steps", []):
+            if not isinstance(step, dict):
+                continue
+            name, tool = step.get("name"), step.get("tool")
+            rerun = rerun or name == target_step
+            if rerun and isinstance(name, str) and isinstance(tool, str):
+                skipped_step_roots.add(source_root / f"{name}_{tool}")
+                skipped_step_roots.add(source_root / f"{'_'.join(name.split()).lower()}_{tool}")
+
+    def ignore(directory, names):
+        current = Path(directory).resolve()
+        if current == source_root:
+            return {".agent"}.intersection(names)
+        if current in skipped_step_roots:
+            return _ARTIFACT_DIR_NAMES.intersection(names)
+        return set()
+
+    return ignore