# Native EDA Agent

面向本机 Vivado / FPGA 开发的 Agent 工程：通过 Codex、Pi 或 CLI 检索设计知识、读取 SOP、组织仿真与实现任务，并核验和恢复执行证据。模拟电路侧提供 LTspice 批处理与测量验收。

当前重点是 **可追溯的知识指导、固定验收、可靠执行和结果复核**。模型提供商 API 默认关闭；下列本地工具和离线检查不需要模型 API key。

[核心机制](docs/mechanisms.md) · [RAG 与 SOP](docs/knowledge-and-sops.md) · [功能成绩](docs/results.md) · [工作流](docs/workflows.md) · [全部文档](docs/README.md)

## 项目亮点

- **知识直接进入任务**：36 条规则带来源、版本、适用条件与所需证据；中英文检索有排名；4 个 SOP 同时支持 Pi 发现和 MCP 读取。workflow 固定所选知识与 SOP 的文件哈希。
- **验收条件可执行**：任务声明输入、前序结果引用、逐步 checks 和预算。工具完成、功能通过、时序通过、CDC/DRC 和上板分别判断。
- **任务可追踪和恢复**：每次调用保留输入快照、进程、失败、终态与因果 trace。恢复前核验所有者、输入、代码和产物；在新目录从已提交边界继续。
- **EDA 执行受资源约束**：原生工具与社区 MCP 代理共享资源租约，支持队列、超时与取消。物理优化器另有候选准入、最佳结果保留、停滞停止和最终复测。
- **成绩可以复核**：保留原测试协议、失败和公开证据哈希。不同题集、watchdog 和计分单位不合并成总分。

## 按功能看能力与证据

| 功能 | 已有能力与证据 | 验收范围 |
|---|---|---|
| RTL 功能验证 | XSim 固定 checker、参数/种子/背压/复位；24 题原协议 20/24，延长 watchdog 的同一批 RTL 为 23/24 | 可见测试；两种协议分开，非盲测 pass@1 |
| 系统工程集成 | FFT 1024 点、16 帧；SoC/DMA/UDP/AES 4/4；AXI 3×3、三时钟 Ethernet、RV32IM AES DMA 3/3 | 功能与 OOC 实现；Ethernet 保留 34 条 CDC warning |
| 综合、实现与诊断 | 显式 RTL/XDC/DCP 输入，setup/hold、约束、routing、CDC、网表对象查询；原生集成检查 12/12 | 报告诊断；缺失字段保留 unknown；无板级签核 |
| 工程、IP、Block Design | 社区 Workbench 13 类操作，33/33 工具检查 | 工具集成检查，非 33 个新 FPGA 项目 |
| 物理优化 | 7 个本地策略、准入与复测；历史 AXI 运行 2 个候选，实测 WNS 收益 0 ns | 仅其中 2 类 reroute 有实跑；未复现竞赛排名 |
| 模拟电路 | LTspice RC AC/瞬态、独立解析解校验；历史四项测量误差均低于固定 0.2% 阈值 | RC 基础案例；新代理版本未重跑商业工具 |
| 知识与 SOP | 36 规则 / 21 来源 / 4 SOP；24 条可见检索回归 Hit@5 为 24/24 | 检索相关性；不是回答正确率或设计通过率 |
| Agent 工程机制 | 输入/知识冻结、预算、恢复、MCP、资源并发、trace、真实 Pi 资源加载等离线检查 | 假 EDA、本机进程与协议验收；当前回执见 release/validation.json 和 CI |

详细协议、失败、资源和证据索引见 [功能成绩](docs/results.md)。历史 FPGA 成绩没有在本轮重跑；新 AXI workflow 仅完成静态计划。接口数量单列在 [工具合同](docs/reference/tools.md)：54 个原生入口，其中 28 个为共享执行器的细粒度合同；可选社区后端另有 45 个工具与 11 个 prompts。

## 架构

```mermaid
flowchart LR
  A[Codex / Pi / CLI] --> K[知识检索 + SOP]
  K --> W[任务规格 + 固定 checks]
  A --> W
  W --> R[共享工具注册表]
  R --> Q[trace + 资源队列]
  Q --> E[XSim / Vivado / LTspice]
  Q --> M[社区 MCP 代理]
  E --> V[功能与报告验收]
  M --> V
  V --> T[结果 / checkpoint / 证据]
  T --> A
```

知识检索由工具调用触发，SOP 提供工程指导；代码强制执行的是显式参数、预算、检查与恢复条件。当前没有向量索引、自动答案引用核验、强沙箱或完整模型会话恢复。具体实现和缺口见 [机制检查](docs/mechanisms.md)。

## 本地启动

当前支持 Windows，EDA 实跑基线为 Vivado/XSim 2020.2。使用 Node.js 24 与 Python 3.13。Vivado、LTspice 和许可证由本机提供。

```powershell
npm ci --ignore-scripts
pwsh scripts/bootstrap-python.ps1
npm run setup:local
npm run validate:agent
```

Setup 生成当前目录的 Codex/Pi MCP 配置；已有配置默认保留，`--replace` 会先备份。重连 MCP 后使用新工具。真实 EDA 执行前将 `EDA_VIVADO_BIN` 指向安装目录的 bin；当前回退路径为 `E:\Xilinx\Vivado\2020.2\bin`。

```powershell
npm run knowledge -- "跨时钟总线一致性"
npm run sop -- fpga-timing-triage
npm run workflow -- plan examples/workflows/offline-review.json
npm run workflow -- run examples/workflows/offline-review.json
node scripts/results.mjs verify hard-projects-3
```

上述例子只使用本地知识、前检与历史证据。`workflow run/resume` 按规格决定是否启动 EDA；`eda_vivado_optimize` 的 plan 也会启动 Vivado。真实工程可从 [counter](examples/workflows/counter-simulation.json) 或 [AXI fabric](examples/workflows/axi-fabric-ooc.json) 开始，先按 [工程索引](projects/README.md) 获取固定 RTL 依赖并核对验收范围。

## 仓库导航

| 目录 | 内容 |
|---|---|
| [src](src) | Agent 入口、知识/SOP、工作流、执行器、验收、调度与 trace |
| [knowledge](knowledge/README.md) / [.pi/skills](.pi/skills) | 来源、规则、SOP 索引、检索回归与操作步骤 |
| [examples/workflows](examples/workflows) / [projects](projects/README.md) | 可执行任务规格与 FPGA 示例工程 |
| [results](results/catalog.json) | 11 组历史成绩及公开脱敏证据；不含大型原始产物 |
| [tests](tests) / [.github/workflows](.github/workflows) | 软件故障检查与 Windows CI |
| [docs](docs/README.md) / [release](release/README.md) | 当前指南、历史报告、发布清单与验收回执 |

安装环境、会话、凭据、波形和 DCP 保留在本机。Ross 技能、官方 Ross MCP 与 LTspice bridge 为可选依赖；公开包不保证其已安装或已连接。Synopsys 是独立项目，商业执行需要现成授权。

原生框架采用 [MIT](LICENSE)；依赖和 IP 见 [第三方说明](THIRD_PARTY_NOTICES.md)。维护入口：[贡献规范](CONTRIBUTING.md)、[版本记录](CHANGELOG.md)、[历史协作与 trace 文档](docs/agent-framework-and-traces.md)。