前言¶
在 DSH 裏用智能體做 RTL，常見問題不是「模型會不會寫 Verilog」，而是流程缺位：架構與 RTL、驗證、綜合、物理實現之間的階段邊界不清晰；改動後不知道該複用哪些檢查結果；交付與技術驗收混在一起，失敗後難以恢復。手寫提示詞可以覆蓋某幾步，但很難穩定地貫穿「合同—實現—證據—資源—交付」整條鏈。
dsh-rtl-flow（維護者 wanghao815，分類：工作流）把上述能力收進一個插件：主流程寫在 docs/core-workflow.md，模型工具 rtl_guide(workflow) 與 CLI 讀同一來源；另有證據審計、設備資源預檢，以及 technical 與 delivery 分開記錄。下文按「是什麼 → 能力 → 安裝 → 用法 → 注意」介紹，事實以倉庫 README 與 package.json 爲準。
這是什麼¶
dsh-rtl-flow 是 DeepSeek Harness 上的通用 RTL 工程插件，覆蓋架構、RTL、驗證、綜合、物理實現、交付和恢復。它不替代 EDA 工具本體，而是提供工作入口、按設計特性組合的階段指導、真實文件與報告審計，以及受控運行前的資源覈對。
- 插件包名：
dsh-rtl-flow，當前版本 0.3.0 - 許可證：MIT
- 源碼與說明：GitHub wanghao815/dsh-rtl-flow
- 社區目錄：SkillHub 插件頁
運行要求：Node.js ≥24.9，宿主 API 兼容基線爲 DeepSeek Harness 0.2.2-rc.1。DSH 爲預覽版，升級後需重新驗證；插件版本與 DSH 版本彼此獨立。
五種工作入口¶
已有項目不必從頭跑完整階段鏈。work 會根據磁盤審計與顯式影響給出 reuse / invalidate / execute 計劃；執行仍須滿足技術依賴與授權。
| 入口 | 行爲 |
|---|---|
| new 新建 | 建立當前項目自己的合同與工具最小集，逐級實現 |
| adopt 接手 | 審計已有源碼、約束、測試和報告，預覽缺失管理文件，保留原文與原約定 |
| modify 修改/調試 | 顯式記錄影響類別，複用有效先決條件，選擇受影響檢查 |
| eco 物理優化 | 保留原邏輯/約束/失敗源，做適用等價、時序與物理複驗 |
| resume 恢復 | 覈對最新決定、進程與最後完整檢查點；不會自動清除 paused |
init 專用於新項目。adopt 只預覽缺失文件，不覆蓋既有文件；已有合同路徑可用 project options 的 contracts 映射，不強迫遷移原目錄。
主流程與特性專題¶
主流程與各專題共同工作。stage 負責主流程；另有 arithmetic、stream、protocol、multiclock、memory、macros、formal 七個專題。每個專題說明進入條件、輸入、處理、產物、判據和失敗診斷。例如帶反壓、跨時鐘的算術模塊需同時啓用 arithmetic / stream / multiclock；模塊名稱不能代替完整特性清單。
模塊名稱只提供可編輯的初始建議；拓撲、數制、流水、容量、頻率和工藝由當前項目需求確定。後端指導以開源 ASIC 流程爲參考，FPGA 與商業工具需在項目內單獨適配。詳細階段決策與輸出策略見倉庫內 docs/core-workflow.md、docs/output_human_final.md。
模型工具與 CLI 分工¶
插件向宿主注入五個工具 schema，詳細正文按需加載；不包含 API key，沿用宿主模型、文件/終端權限及取消機制。
| 工具 | 功能與邊界 |
|---|---|
| rtl_guide | 返回核心流程、階段或特性專題 |
| rtl_scaffold | 返回新項目文檔/配置草案，不生成通過證據，也不直接寫文件 |
| rtl_plan_work | 按入口、變更影響和審計結果選擇複用/失效/執行範圍與專題 |
| rtl_check_evidence | 結構、配置指紋、依賴及交付狀態檢查；標記 declarations-only |
| rtl_resource_check | 對 workspaceRoot 指定項目檢測內存/磁盤、已耗時、剩餘任務和預算；不啓動進程 |
RTL、testbench 和流程由宿主模型結合項目合同生成。工具側的 JSON 聲明檢查不能替代 CLI audit 對真實讀取、原生指標和文件摘要的核對。
安裝與配置¶
在插件倉庫根目錄（含 package.json）可先自檢：
npm ci --ignore-scripts
npm run check
npm test
從該目錄安裝到測試 profile：
dsh plugin --profile rtl add .
dsh --profile rtl --dump-config
dsh --profile rtl
未全局安裝 dsh 時，可用 npx --yes @deepseek-ai/dsh@0.2.2-rc.1 替代命令中的 dsh。開發 overlay 可執行 node bin/rtl-flow.js overlay 獲取絕對入口路徑，在 bundle 與 overlay 兩種方式中選一種加載。
也可從 npm 安裝 dsh-rtl-flow@0.3.0（公開版本以實際 registry 爲準）。發佈步驟見 docs/release-checklist.md。
配置字段包括：enabled、promptOrder、maxInputBytes，以及可選 workspaceRoot。要對項目做原生資源檢測時，將 workspaceRoot 設爲當前已授權項目的絕對路徑；未配置時通過宿主終端執行 CLI resources。切換項目須同步更新該字段。
典型 CLI 用法¶
在含 package.json 的插件根目錄：
node bin/rtl-flow.js plan --config examples/fifo.json
node bin/rtl-flow.js init /tmp/my-fifo --config examples/fifo.json
node bin/rtl-flow.js adopt /path/to/existing --config examples/fifo.json
node bin/rtl-flow.js work /path/to/project --entry modify --impact rtl,control
node bin/rtl-flow.js topics /path/to/project
node bin/rtl-flow.js audit /path/to/project
node bin/rtl-flow.js resources /path/to/project
node bin/rtl-flow.js run /path/to/project --task smoke
adopt 的配置須描述真實舊項目；README 中的 FIFO 示例僅演示命令形式。新建草案無執行證據時，audit 會按預期失敗；預算與剩餘任務未填寫時，resources 也會阻塞。
capture、parse、hash 等子命令用於證據採集與摘要，規範見 docs/evidence.md。退出碼：0 表示本操作指定範圍滿足；1 爲檢查/預檢未滿足或原生任務失敗；2 爲輸入/執行錯誤；130 爲中斷。評估 audit 時須查看 technical_ok、delivery_ok 與 outcome，不能只看退出碼。
OpenROAD/ORFS 環境¶
插件不攜帶 EDA/PDK 本體；npm 安裝不會自動下載環境。僅在顯式 env prepare 且完整資源預檢通過後，纔會獲取缺失的官方環境：
rtl-flow env /path/to/project --action init
rtl-flow env /path/to/project --action inspect
rtl-flow env /path/to/project --action plan
rtl-flow env /path/to/project --action prepare
rtl-flow env /path/to/project --action check
計劃應保存爲 config/backend-plan.json。步驟、鏡像鎖定與邊界見 docs/backend-setup.md。
資源預算與受控運行¶
config/resource-plan.json 列出剩餘任務、依賴、argv、重任務標記和時間/內存/磁盤估算。未知量會阻止執行。run --task 每次只跑一個前臺任務，原生 argv 不經 shell；運行器持有項目鎖並記錄退出與資源採樣，超限或監測不可用時受控結束進程組。此運行器支持 macOS/Linux；Agent 在重任務前應走預檢/受控入口，繞過 CLI 的命令不受運行器監測。
交付、暫停與項目格式¶
項目 state 爲 active / paused / archived；delivery.intent 爲 full / scoped / closeout。因此 delivery_ok=true 不必意味着 technical_ok=true。暫停不會被 resume 入口自動解除。
項目使用 schema_version=2。示例配置見 examples/fifo.json、examples/apb-registers.json、examples/dsp-mac.json、examples/memory-subsystem.json。
適用場景與注意¶
適合誰： 已在 DSH 中做 RTL/ASIC 流程、希望階段門控、證據審計和資源預檢與 Agent 協作對齊的開發者。
權限與安全： 插件以當前 DSH 進程權限運行。安裝前應閱讀源碼與 MIT 許可證，確認 workspaceRoot 與合同路徑只指向你願意授權給宿主的路徑。
驗證範圍： 單元與宿主測試結果不代表真實模型新設計、全流程 PDK 或製造籤核。實際兼容範圍見 docs/validation.md。原生報告解析僅覆蓋文檔列出的格式；摘要保證一致性，不證明日誌不可篡改。
DeepSeek Harness 生態理念是「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-rtl-flow 把 RTL 工程從「單次代碼生成」拉回到可審計、可分入口恢復、可區分技術驗收與交付意圖的工作流。需要主流程全文時，在倉庫內先讀 docs/core-workflow.md；在 DSH 中安裝後通過 rtl_guide 與 CLI plan / audit / resources 與項目合同對齊即可起步。
- 目錄頁：https://www.skillhub.cn/plugins/wanghao815/dsh-rtl-flow
- GitHub：https://github.com/wanghao815/dsh-rtl-flow
