# AGENTS.md — 让其他 Agent 学会用 gwin-skill

本文给 **Cursor Agent / 子 Agent / 自动化脚本作者**。人类请看 `README.md`。

## 1. 何时加载本 skill

满足任一条件即应 **Read `SKILL.md` 全文** 再动手：

- 用户提到：高云、Gowin、GW5A、ACG525、FPGA 综合、下载、烧录、`.gprj`、`gw_sh`、Programmer
- 用户要求改 `proj*` 下 Verilog / `.cst` 并上板
- 用户要求 TFT / LCD / RGB 刷屏、彩条、显示驱动
- 父 Agent 把任务描述为 “按 gwin-skill 执行”

不要用通用 FPGA 经验硬套 Xilinx/Intel 命令。

## 2. 最小阅读集

| 任务 | 必读 |
|------|------|
| 任意高云任务 | `SKILL.md` |
| 新建/改 RTL 或约束 | + `design-spec.md` |
| 动到 LCD/按键/LED/时钟脚 | + `reference-pins.md` |
| 复现刷屏类 demo | + `examples.md` |
| 写脚本/子 Agent 提示词 | + 本文 |

## 3. 标准动作序列（不可跳步）

1. **定位**：确认 `tool-chain/Gowin/...` 与目标工程目录存在  
2. **设计**：按 `design-spec.md` 改 `src/*.v`、`.cst`、`.sdc`、`.gprj`  
3. **构建**：`scripts/build.ps1` 或 `type build.tcl | gw_sh.exe`  
4. **检查**：`impl/pnr/*.fs` 存在；日志无 ERROR  
5. **下载**：板子供电 → `scripts/download.ps1` 或 `programmer_cli -r 2`  
6. **汇报**：比特流路径、操作码（SRAM/Flash）、用户应看到的现象  

失败则停在当前步，贴关键日志行，禁止假装成功。

## 4. 子 Agent 提示词模板

把下面块交给子 Agent（替换路径与目标）：

```text
你正在操作高云 ACG525 (GW5A-LV25UG324C2/I1)。
必须先阅读并遵守：
  <gwin-skill>/SKILL.md
  <gwin-skill>/design-spec.md
  <gwin-skill>/reference-pins.md（若涉及 IO）

工作区：C:\Users\Administrator\Documents\fpga
工具链：tool-chain\Gowin\Gowin_V1.9.11.03_Education_x64
目标工程：<proj_dir>
任务：<一句任务>

硬性约束：
- 只用 gw_sh pipe / gwin-skill/scripts，不要开 GUI 干等
- build.tcl 无 UTF-8 BOM
- 下载前确认板子供电；programmer_cli -d GW5A-25A
- 引脚以 reference-pins.md 为准，禁止臆造 IO_LOC
完成后报告：构建结果、.fs 路径、下载结果、预期现象。
```

## 5. 禁止教给 Agent 的错误做法

- `gw_sh.exe` 无输入长时间挂起  
- `set_option -verilog_std vlg2001`  
- 只插下载线不供电就 `programmer_cli`  
- 把 DK_START 官方板引脚当成 ACG525  
- 把 2×18 TFT 当成 RGB888 全接满  

## 6. 成功判据

- `programmer_cli --scan` 见 GW5A  
- 下载 `Finished`  
- 用户可观察的外部现象与设计一致（LED / 彩条方向 / 按键切色等）

## 7. 版本与扩展

- Skill 名：`gwin-skill`（仓库名同）  
- **远程仓库**：https://git.whcself.xyz/FPGA-IQBoost/gwin-skill.git  
- 新外设：只追加 `reference-pins.md` 表格 + `examples.md` 一节  
- 新器件：新建 `reference-<board>.md`，并在 `SKILL.md` 环境表增加一行