AI Agent 驱动 Zynq-7020 开发框架（MCP + Skill）

用 AI Agent（主代理）驱动 Vivado/XSim/Vitis 做 Zynq-7020（ALINX AX7020）FPGA 开发：一个 MCP Server + 一个泛化 Skill + 一个板卡配置包，Agent 通过 MCP 原子工具完成平台/PL/PS 全流程（建 BD、综合、实现、bitstream、裸机编译、JTAG 部署），按「三域四层 + Brick」增量构建并经白盒/黑盒验收。
外部使用者只需要：mcps/（MCP Server）+ skills/（泛化 Skill）+ boards/（板卡配置包）+ 本 README。 其余目录为项目开发历史与验证资产（见下）。

迭代到什么程度（2026-09-03）

框架：B00–B09 ✅ COMPLETE/FROZEN（统一 zynq_mcp、执行账本、单通道生命周期、公开 MCP 黑盒验收）；B11 ✅ COMPLETE（泛化框架黑盒验证：零外设字样 Skill + 6-LED 考题全链路 PASS）；当前 MCP 共 109 工具（11 control + 98 domain：platform/PL/PS 域；B13 修复轮#1–#10 已合入 master，见 B13_P4_MILESTONE.md）。Execution Observation：O1–O6 FROZEN，O7 R3 PASS。
功能切片（真板）：B12 ✅ A1（DMA 环回白盒+黑盒）/ A2（AD7606C-16 8 通道实采，盲测通道/频率/幅度三方法一致）——B13 ✅ P4 完成（2026-09-05）：TCP 扫描上传模拟全链黑白盒双过（UART 指令 + TCP 25M 点整图 2.087MB/s、TPG 全速门禁、ADC 三档 2k/100k/1M ±0.5%、L2 事件计数 1:1、STOP/覆盖/溢出/重连、KAT 双向量、verify 12/12）。
验证方法论 v2：validation_methodology.md（L0 契约/L1 功能/L2 状态/L3 公共面 + 行为偏离审计 + 黑盒终审——黑白盒任务书设计的长期纪律）。
框架已知问题与加强方案：B13_exposed_framework_issues.md（9 条 MCP/Skill 级问题全部经修复轮#1–#10 关闭，状态见文档 §五/§六）。
协作纪律（长期）：subagent_communication_rules.md。

给外部使用者：最小上手

目录	说明
`mcps/zynq_mcp/`	唯一 MCP Server（105 工具；`control/` 执行账本与单通道生命周期 + `adapters/` Vivado/XSCT/JTAG/UART + `domains/` platform/PL/PS）。启动：`python -m mcps.zynq_mcp.server`（stdio JSON-RPC；客户端可用 `mcp` SDK 的 `ClientSession` 接入）
`mcps/common/`	公共契约：板卡配置包/锁/Revision/Artifact/错误模型（MCP 依赖）
`skills/zynq_dev/`	泛化开发 Skill（零项目外设字样：SKILL.md + phases 0–8 + 机制附录）
`boards/ALINX_AX7020_v1.0/`	板卡配置包（板卡唯一数据源：README/xdc/profile/ps7 preset/manifest）
`vendor/drivers/`、`tools/scripts/`	可选：USB-UART 驱动与扫描/安装脚本

测试：从仓库根运行 python -m pytest mcps（勿 cd mcps）；环境 Windows + Python 3.12 + mcp==1.28.1；Vivado/Vitis 2023.1。
平台要求：AI Agent 会话需能调用 MCP 工具（本仓库的 Server 为外部启动的 stdio 服务；无原生挂载时可用 mcp SDK 写 stdio 客户端调用，见框架问题文档）。

非核心目录（外部使用者可忽略）

目录	说明
`docs/`	冻结架构 + 全部 Brick 开发记录/测试规划/技能归档（项目过程资产，体量大）
`hello_fpga/`、`g9_hw_test/`、`embedded_projects/`、`validation_projects/`	开发期参考/验证项目（Golden + 故障注入 + 黑盒材料）
`workspaces/`、`.zynq_runtime/`、`.o6_runtime/`、`.tmp_*`	运行态/证据目录（不入库）
`PC_end_tcptest/`	B13 上位机测试程序（项目专属）
`Xilinx_Vivado_MCP/`、`Xilinx_Vitis_MCP/`、`zynq_platforms/`	legacy 旧 MCP/平台（独立 Git 仓库，已被 `mcps/zynq_mcp` 取代）

Brick 历史进度

Brick	状态	说明
B00–B03	✅ COMPLETE/FROZEN	项目整理、执行观察 O1–O6、板卡配置包、环境基线
B04	✅ COMPLETE/FROZEN	统一 `zynq_mcp`：执行账本 + 单通道生命周期 + Vivado/XSCT Adapter
B05–B09	✅ COMPLETE/FROZEN	GPIO 纵向切片全链路（白盒/阶段黑盒/公开 MCP 黑盒 PASS）
B10/B11	✅ COMPLETE	O8 冻结包；泛化框架黑盒验证（去 GPIO 化 Skill + 109 工具 + 6-LED 考题，全六阶段闭环）
B12	✅ A1/A2 COMPLETE	数据采集链路：DMA 环回白盒+黑盒；AD7606C-16 8 通道真板实采（盲测一致）
B13	✅ P4 完成（2026-09-05）	TCP 扫描上传模拟全链：P0 协议互测 → P1 TPG 全速门禁 → P2 ADC 三档实采 → P3 上位机联调 → P4 黑白盒双过（2.087MB/s 整图零错、三档 ±0.5%、verify 12/12）+ 框架升级修复轮#1–#10 合入 master

核心组件（当前）

目录	说明
`mcps/zynq_mcp/`	唯一 MCP（105 工具，详见上）；`docs/development/mcp/B10_freeze_manifest.md` 为发布清单
`skills/zynq_dev/`	泛化 Skill（B11 冻结）；旧 GPIO Skill 归档于 `docs/development/skill/archive/`
`boards/ALINX_AX7020_v1.0/`	Board Configuration Package（板卡唯一数据源）
`Xilinx_Vivado_MCP/`、`Xilinx_Vitis_MCP/`、`zynq_platforms/`	legacy/已出范围（独立 Git 历史，保留在磁盘）

开发规划与入口文档

顶层架构（冻结）：docs/architecture_ai_zynq7020.md v2.3.1
Brick 计划与进度：docs/brick_development_plan.md
冻结契约（当前）：docs/development/tests/B13_requirement_draft.md
框架问题复盘：docs/development/mcp/B13_exposed_framework_issues.md
会话纪律速查：docs/development/B12_a2_working_discipline.md