gwin-skill/AGENTS.md

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（替换路径与目标）：

你正在操作高云 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 环境表增加一行