# RepoKey AI Vitis / Vivado Stack

这是 RepoKey Vivado AI 客户包内的本地工具栈。工具提供证据，AI 做工程判断，
人授权设计意图变更。路径中的 `<REPOKEY_HOME>` 指安装包根目录。

## 组件

| 组件 | 职责 | 入口（全部由 repokey-client.cmd 提供，无需 Python） |
|---|---|---|
| `vitis_mcp` | PS/Vitis/XSCT 运行时证据、PS 静态上下文、ILA CSV 分析分派、常驻 ILA 捕获服务 | `repokey-client.cmd vitis` |
| `pl_qor_mcp` | PL 时序/利用率/QoR 证据采集、决策记录、对比 | `repokey-client.cmd pl-qor` |
| `pl_ps_handoff` | PL→PS 控制交付（control_handoff.* / ps_delivery.xlsx / evidence.md / ai_reading_guide.md） | `repokey-client.cmd handoff pl2ps ...` |
| `pl_optimizer_compat` | QoR 版本适配与基线采集（已内置进 repokey.exe，不单独分发脚本） | 内置 |
| `vivado_debug_mcp` | 硬件调试证据层：ILA/VIO 清单、触发模板、捕获摘要/对比、live 捕获、XSCT 寄存器探针 | `repokey-client.cmd debug serve` |
| `vivado_context_mcp` | 低 token 工程上下文索引（xpr/RTL/XDC/BD/IP、相关文件、token 估算、handoff 事实） | `repokey-client.cmd context serve` |

## 先读

- `AI_TOOL_ROUTING.md`：按证据域选择工具的规则。
- 栈健康检查：`repokey-client.cmd mcp-selfcheck`（开发源码目录另有 `scripts\smoke_test_mcp_stack.py`，客户包不附带）。

## MCP 注册

- `MCP_REGISTRATION_TEMPLATE.json`：可选 MCP server 注册模板（vitis / pl-qor / vivado-debug / vivado-context）。
- 主 RepoKey Vivado MCP 由 `install\register_mcp.ps1` 管理；`vivado-debug` 可选注册见 `install\register_debug_mcp.ps1`。
- 全部栈 MCP 已内置到 repokey.exe，注册脚本不再需要 pip install 或 PYTHONPATH。

## 证据路径约定

项目内统一使用：

```text
.vivado_ai_mcp\
  context\     Vivado Context MCP 索引
  qor\         PL QoR 基线/对比
  ps_context\  Vitis MCP PS 静态上下文
  debug\       vivado_debug_mcp 会话与证据
```

## 边界

- 不自动执行 PL 优化实验，不自动改 RTL/XDC/BD，不加时序例外。
- AMD Doc MCP 只提供官方语义，不提供本地项目证据。
