dsh-gowin —— DSH 的高云 Gowin IDE 插件

把高云 Gowin 1.9 工具链（gw_sh.exe / programmer_cli.exe / gao_analyzer.exe）接进 DSH： 15 个工具 + 1 个技能（skill），让 DSH 会话里能直接探测环境、建模、静态校验、编译、烧录、在线调试、读报告， 并把它在真实闭环里踩到的坑写成机器可查的清单。

• 工具前缀统一 gowin_，全部只读优先、结论带原始证据（行号 / 语句 / 文件路径）。
• 不发明事实：所有引脚、极性、器件配置码都来自 FG202 GW1N-UV9LQ144 原理图，并已与例程 .cst 逐脚交叉验证、上板跑通。
• 尚未上板验证的项（如外部 flash 烧录）在工具说明与文档里明确标注为未验证。

---

一、安装

从 GitHub 装

cd ~/.dsh/profiles/<你的 profile>
pnpm add github:lishuo4096/dsh-gowin

再把 "@local/dsh-gowin" 追加进同目录 package.json 的 dsh.profile.bundles，新开一个会话 即可看到 gowin_* 工具与 gowin-fpga 技能。

已实测：pnpm add github:lishuo4096/dsh-gowin 装出 @local/dsh-gowin 0.1.0， dsh.bundle 指向 ./cordis.patch.yml，模块加载后注册 15 个工具 + 1 个 skill provider。 装出来的目录只有运行时需要的文件（package.json 的 files 字段把自测脚本挡在外面）。

本地开发（改代码时用 link）

plugin_manager({ action: 'install_bundle', target: 'C:/path/to/dsh-gowin' })

install_bundle 会同时把 "@local/dsh-gowin": "link:<该目录>" 写进 profile 的 dependencies 和 dsh.profile.bundles，改完代码重启会话即生效。

卸载：plugin_manager({ action: 'remove_bundle', target: '@local/dsh-gowin' })。

---

二、15 个工具

工具	干什么
gowin_env	探测安装根（多版本容忍：本机同时有 V1.9.12.02_SP2 与 V1.9.11.03 Education）、三个入口程序、License 有效性。任何高云任务的第一步
gowin_device	本板器件事实：GW1N-9C / GW1N-UV9LQ144C6/I5 / device_version C / 配置码 gw1n9c-019
gowin_board	引脚与极性速查（带 pin 可反查某脚在板上是什么）
gowin_project	读 .gprj 全貌：器件、文件表（含「登记了但磁盘上没有」的）、.cst 引脚分配、.sdc 时钟
gowin_init	生成能直接编译的工程骨架：.gprj + .cst + .sdc + 可选顶层。默认不覆盖
gowin_cst	生成 / 校验物理约束。默认只打印，write:true 才落盘
gowin_check	编译前机械校验，每条带行号与原始语句
gowin_build	调 gw_sh.exe 编译（syn / pnr / all），跑完自动汇总错误、警告、产物
gowin_program	烧录 / 扫描（sram / flash / scan）
gowin_report	结构化读产物：资源占用、I/O Bank、时钟资源、逐端口引脚表、逐路径时序裕量、cmd.do / device.cfg
gowin_artifacts	列 impl\ 全部产物（大小 / 时间 / 哪个是要烧的）
gowin_tcl	在 gw_sh 里跑任意 TCL 命令串。查权威用法的正确方式（122 个命令，任何命令加 -h）
gowin_gao	GAO 在线逻辑分析仪：读 .gao / .rao 定义，launch:true 启动采集界面
gowin_docs	文档路标 + 在已抽出的中文文档文本里做关键词搜索
gowin_help	排错剧本（build_failed / all_leds_off / gao_capture / wrong_pins / first_time）与踩坑清单

技能 gowin-fpga（skills/gowin-fpga/SKILL.md）是任务级入口：从零到上板的完整流程、 何时用哪个工具、以及必须停下来查手册的判据。references 里带三份原文 （gowin-agent-guide.md 手册全文、gao-experiment.md GAO 实验记录、closed-loop-report-notes.md 闭环报告笔记）。

---

三、典型流程

gowin_env                       # 1. 有没有工具链、License 行不行
gowin_board {peripheral:'led'}  # 2. 板子上 LED 接哪几个脚、什么极性
gowin_init  {dir:'...', demo:true}   # 3. 生成骨架（.gprj/.cst/.sdc/顶层）
gowin_check {file:'...gprj'}    # 4. 编译前机械校验 —— 省掉整轮编译时间
gowin_build {task:'all'}        # 5. 出码流
gowin_report{section:'timing'}  # 6. 时序裕量有没有违规
gowin_program {mode:'sram'}     # 7. 上板

在线调试：gowin_cst / 手写 .gao → gowin_build（码流变成 ao_0.fs）→ gowin_program {fsFile:'...ao_0.fs'} → gowin_gao {launch:true}。

---

四、设计约束（为什么这么写）

1. 成功判据是「退出码 0 且 impl 下出现 .fs」，不是「stdout 里没有 ERROR」。 gw_sh 中途失败也可能退出 0；而 stderr 里的 alog error: failed to open log file 是本机 AppData 写不进去造成的无害噪声，已被 cleanOutput 过滤，绝不能拿它判失败。
2. programmer_cli 的退出码不可靠（失败也返回 0），判据只能看控制台文本 （Finished. / Verify Success / Error）。且 operation_index 4 在本器件上 恒报假失败 Error: Verify failed of at 0，所以 SRAM 默认走 2。
3. 禁用三个入口：gw_ide.exe（加 -h 也拉 GUI 并挂住）、gao_sh.exe （argv[1] 为 -gao 时永久挂死，定向实验证明它从不连 \\.\pipe\gao1）、programmer.exe（GUI）。 commandSpec() 在调用前就把它们拦下并说明原因。
4. 不依赖宿主 asar 内的包：用同目录的 lib/define-tool.js / lib/frontmatter.js （以 link: 装载时插件目录解析不到 @deepseek-ai/dsh-tools，直接 import 会 ERR_MODULE_NOT_FOUND，整个插件行 failed to import）。
5. 技能注册失败不拖垮插件：apply() 里对 skills 单独 try/catch，只打日志。
6. .fs 不能比哈希：逐字节不完全相同（内嵌路径与时间戳，差十几字节）。 判两次构建等价要比 cmd.do / device.cfg / 资源报告。

---

五、目录结构

dsh-gowin/
├── index.js                 # cordis 插件入口：name / inject / apply
├── package.json             # dsh.bundle.patch 指向 cordis.patch.yml
├── cordis.patch.yml         # insert: [{id: gowin, name: "@local/dsh-gowin"}]
├── lib/
│   ├── define-tool.js       # 本地化 defineTool（不依赖宿主 asar）
│   ├── frontmatter.js       # SKILL.md frontmatter 解析（含 YAML 块标量）
│   ├── env.js               # 安装根发现、命令规格、License、禁用清单
│   ├── board.js             # FG202 板级事实（引脚 / 极性 / 专用脚）
│   ├── gprj.js              # .gprj / .cst / .sdc 解析与生成
│   ├── check.js             # 静态机械校验规则
│   ├── build.js             # gw_sh 调用、日志判据、产物收集
│   ├── report.js            # pnr 报告 / timing_paths / cmd.do / device.cfg 解析
│   ├── tools.js             # 15 个工具定义 + 踩坑清单 + 剧本
│   └── skills.js            # skill provider
├── skills/gowin-fpga/SKILL.md
├── references/              # 手册全文、GAO 实验记录、闭环报告笔记
└── _selftest.mjs            # 零依赖自测（345 项断言，含真编译开关）

---

六、自测

$node = 'C:\Users\lishuo\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe'
cd C:\Users\lishuo\Documents\deepseek-harness\default-workspace\dsh-gowin
& $node _selftest.mjs            # 纯函数 + 真实工程夹具解析（不开工具链）
& $node _selftest.mjs --build    # 额外真跑一次 gw_sh 全链路（约 1-2 分钟）

夹具是 gowin-build\07_LED_Flow\LED_Run\LED_Run.gprj（一份真实编译过的工程）。 --build 实测结果：gw_sh 退出码 0、verdict=ok、生成 LED_Run.fs、日志尾行 ########## BUILD SUCCESS (all)。

---

七、环境前提

项	值
安装根	C:\Gowin\Gowin_V1.9.12.02_SP2_x64（PREFERRED_ROOTS 里另列了 V1.9.11.03_Education_x64）
编译	<root>\IDE\bin\gw_sh.exe
烧录	<root>\Programmer\bin\programmer_cli.exe
在线调试	<root>\IDE\bin\gao_analyzer.exe（cwd 必须是 IDE\bin）
License	<root>\IDE\bin\gwlicense.ini → gowin_E_1413338ED23B.lic
GOWIN_HOME	每次调用都由插件显式注入（不设会直接报 Please set environment variable GOWIN_HOME）

本机没有 pwsh（只有 Windows PowerShell 5.1）、执行策略 Restricted；插件不依赖 PowerShell， 所有进程调用走 spawnSync。

---

八、已知未验证 / 受限项

• 外部 SPI Flash 烧录（operation_index 9）：示例脚本写了但未实机验证。
• GAO 导出 VCD/GWD：Qt QComboBox 在该 build 下 List rect 为空，SelectionItemPattern.Select() 报成功但读回不变，键盘 VK_DOWN 因窗口无焦点无效 → 目前只能全自动到 CSV。
• jtagserver.exe 无头旁路：协议已逆向（命名管道 gao1 + TCP 36548），但 GAO 核寄存器时序 在服务端之外，成本过高，已放弃。
• RTL 功能仿真：本机未装 ModelSim/Questa，IDE\simlib 是空壳，不可行。
• .sdc 时序约束：原厂例程都没加（故有 TA1132）；gowin_init 生成的工程会带上 create_clock -name CLK_50M -period 20。