# ZfPilot 知识库总索引

> 本文件是 AI Agent 的 **必读入口**。执行任何操作前先读此文件，确定需要参考哪些子文档。

## 知识库结构

| 文件 | 用途 | 何时读取 |
|------|------|----------|
| `tcl/01_project.md` | Vivado 工程管理命令 | 创建/打开项目时 |
| `tcl/02_bd.md` | Block Design 命令 | 创建 BD / 添加 IP / 连接接口时 |
| `tcl/03_synthesis.md` | 综合、实现、导出命令 | 综合 / 实现 / 生成比特流 / 导出硬件时 |
| `tcl/04_constraints.md` | XDC 约束语法 | 编写引脚约束时 |
| `sdk/xsct.md` | 2018.3 XSCT 命令参考 | SDK 软件开发时（2018.3） |
| `sdk/vitis_python.md` | 2025.2 Vitis Python API | Vitis 软件开发时（2025.2） |
| `board/alientek_alpha.md` | 正点原子 Alpha 开发板引脚 | 编写 XDC 约束时 |

## 动态知识库

| 路径 | 说明 |
|------|------|
| `ip/cache/*.json` | 用户投喂的 IP 文档缓存（load_ip_doc 生成） |
| `cache/detected_version.json` | 检测到的 Vivado 版本信息 |
| `cache/ip_index.json` | 已缓存 IP 索引 |

## 标准工作流

```
① detect_version()                    → 确定版本
② read_knowledge("SKILL.md")          → 本文件
③ load_ip_doc(pdf, name)              → 首次使用的 IP
④ create_vivado_project()
⑤ read_knowledge("tcl/02_bd.md")      → BD 操作前必读
   create_block_design / add_zynq_ps / add_ip_core / ...
⑥ read_knowledge("board/alientek_alpha.md")
   read_knowledge("tcl/04_constraints.md")
   generate_xdc()
⑦ read_knowledge("tcl/03_synthesis.md")
   run_synthesis / run_implementation / generate_bitstream / export_hardware
⑧ read_knowledge("sdk/xsct.md") 或 ("sdk/vitis_python.md")
   create_sw_project / build_sw_project
⑨ debug_connect / download_and_run
```

## 版本差异速查

| 功能 | 2018.3 | 2025.2 |
|------|--------|--------|
| 硬件导出 | `write_hwdef` + `write_sysdef` → `.sysdef` | `write_hw_platform` → `.xsa` |
| 软件工具 | XSCT (TCL) | Vitis Python |
| 启动命令 | `xsct script.tcl` | `vitis -s script.py` |
| 创建工程 | `createhw` + `createbsp` + `createapp` | `create_platform_component` + `create_app_component` |

## AI 使用规则

1. **先读后做**: 执行任何操作前，先 `read_knowledge()` 对应文档
2. **先查后用**: 使用 IP 前，先 `read_ip_knowledge()` 确认参数
3. **版本感知**: 所有命令根据 `detect_version()` 结果自动适配
4. **一次投喂**: `load_ip_doc()` 只需调用一次，后续永久缓存
