前言¶
在 DeepSeek Harness（DSH）裏讓智能體改一批文件，常見結局是對話裏一句「已完成」。隨後你要自己覈對：到底動了哪些文件、有沒有漏項、有沒有越界修改；一旦結果不對，往往只能靠手工 git 回退，且很難和「當時打算做什麼」對齊。對話 transcript 能記錄敘述，卻不能像 diff 那樣給出可執行的計劃與完成證據。
CodeFlow Canvas（dsh-codeflow-canvas）是 DSH 側欄裏的工作流畫布插件：界面借鑑 ComfyUI 的節點連線方式，每個節點對應智能體可在工作區執行的一條編碼任務，連線表示數據流依賴。維護者爲 TheLiudawei；當前版本 1.4.2，MIT 許可證，面向 DSH 桌面端（platform: DSH desktop），運行時 npm 依賴爲 0，無需單獨構建。插件由 ZCode 的 codeflow-canvas v0.2.2 移植而來，畫布編輯器保留，會話、工具協議、持久化、交付與撤銷等宿主對接在 DSH 上重寫。
這是什麼¶
一句話定位：把倉庫掃描結果與人工編排的任務，變成雙視圖節點圖（任務流水線 + 模塊結構），並在運行時有可追溯狀態與按次撤銷。
DSH 生態強調「一切皆插件」；社區目錄 SkillHub 是獨立站點，與 DeepSeek / 幻方無官方從屬關係，安裝前仍應自行閱讀源碼與許可證。
與「只在對話裏做計劃」的差異¶
README 用表格對比「在 transcript 裏規劃」與畫布模式，核心差異包括：
| 維度 | 對話裏規劃 | CodeFlow 畫布 |
|---|---|---|
| 計劃來源 | 每次嘗試由模型重新生成 | 本地掃描樹：語言檢測、符號、TODO/FIXME 等，不調用模型、不消耗 prompt token |
| 失敗信息 | 從對話重建 | 落在節點卡片上，節點停止 spinning |
| 「說完成了」 | 往往只能信任表述 | 回合結束若無進展，宿主 reconciled 爲 failed |
| 撤銷 | 手工 git，易過度回退 | 每次運行前快照；一條命令同時恢復文件與節點狀態 |
| 交付物 | 散落在聊天裏 | 原生 present 卡片與 docs/DELIVERY.md |
作者提供的基準測試（npm run bench，固定 60 模塊 fixture）測得：冷/熱導入約 90 ms / 70 ms 量級，導入階段 agent 喚醒與 prompt token 均爲 0；兩次獨立導入在分析字段上 48/48 一致；撤銷相關檢查 4/4 通過。絕對耗時會因機器而異，零 token 與一致性計數在 CI 中由同一腳本約束。
核心功能¶
無模型導入倉庫¶
/flow-import 與導入對話框在本地掃描目錄，秒級生成任務流水線圖與模塊結構圖。同一 commit 上兩次掃描在任務、文件與評分上應一致，因爲結果來自確定性分析（實現見 lib/importer.js、lib/analyst.js、lib/duo.js），而非模型臆造。
雙視圖與實時過程¶
- 任務視圖：節點爲可執行的編碼任務，依賴由連線表達。
- 模塊視圖：展示模塊級結構關係。
- 運行過程中可通過
GET /codeflow/api/activity等接口查看思考流、步驟、進度與文件編輯（過程數據在內存環形緩衝，不落盤、不進日誌）。
界面跟隨 DSH 語言與主題，提供深色與淺色配色並隨宿主切換。
節點狀態有嚴格語義¶
節點在 prompt 入隊時進入 running，僅在智能體回報進度後變爲 done。若回合結束仍無進展，宿主標記爲 failed（例如「agent did not execute this node」），並可一鍵重試；狀態不依據模型口頭表述推斷（相關邏輯在 lib/gestures.js、lib/index.js、lib/activity.js）。
按次撤銷（Undo run）¶
每次 RUN_NODE / RUN_ALL 前對項目樹做快照（排除 node_modules、dist、.git 等）。「撤銷運行」按 LIFO 同時恢復文件與節點狀態，DSH 重啓後仍可用；恢復前會備份當前狀態，避免覆蓋丟失（lib/undo.js）。
其他已文檔化能力¶
- 16 種節點類型，端口類型校驗（
text/json/code/report/file/any）。 - 智能體通過
codeflow_canvas工具回填圖狀態；技能codeflow-canvas定義編排契約，/flow*會自動帶上。 - 零構建：宿主半側爲 ESM，瀏覽器半側爲手寫 bundle。
安裝與啓用¶
官方 README（簡體中文）給出的安裝方式爲從本地目錄鏈接安裝，不需要構建：
# 從本地目錄安裝 —— 不需要構建
dsh plugin --profile desktop add link:<本目錄的絕對路徑>
也可以在 DSH「設置 → 插件」中選擇安裝本地目錄。安裝後需重啓 DSH（宿主半側不支持熱重載），並刷新頁面。
SkillHub 目錄頁 提供面向 Harness 的安裝話術（例如讓 DSH 安裝 TheLiudawei/dsh-codeflow-canvas 並先讀取插件說明）；具體以你使用的 DSH 版本支持的插件安裝方式爲準，勿在未覈對文檔的情況下自行拼接未出現的 CLI 形式。
確認插件是否加載：
curl -i http://127.0.0.1:<端口>/codeflow/canvas # 期望 200 + HTML
若返回 404，且對應 profile 下找不到 codeflow 相關條目，需重新執行安裝並重啓。
前提： DSH 桌面端需提供 sessionController 才能運行節點。缺少時畫布仍可編輯、導入、保存，但運行會給出明確錯誤，而不是隨意綁定會話。
典型用法¶
下面入口來自官方用法表，可按需組合。
| 入口 | 作用 |
|---|---|
/flow |
打開畫布（載入最近項目）；帶參數時可按需求建項目 |
/flow-new [需求] |
新建項目 |
/flow-import <路徑> |
導入項目：宿主掃描併產出兩張圖，不經過 agent；支持 @ 選擇、~、引號與 file:// |
codeflow_canvas 工具 |
agent 回填：load / render / read / save / progress；view: "tasks" \| "modules" |
node lib/importer.js <路徑> |
命令行獨立導入，無需 DSH 進程 |
導入再運行的一條路徑：
- 在 DSH 中對目標源碼目錄執行
/flow-import <路徑>（或走導入對話框），得到任務圖與模塊圖。 - 在畫布中檢查節點與依賴；必要時編輯參數（改參數會重置下游，見端口類型規則）。
- 右鍵節點選擇「運行」，或使用工具欄「運行全部」。宿主先快照，再向項目專用會話投遞
[CodeFlow:RUN_NODE]/[CodeFlow:RUN_ALL]，節點立即顯示running。 - 智能體通過
codeflow_canvas回報進度；完成後節點爲done，失敗則留在卡片上的原因並可重試。 - 若整次運行不滿意，使用「撤銷運行」恢復至快照前的文件與節點狀態。
項目數據默認落在 <工作區>/CodeFlow/flow-projects/<項目名>/（含 workflow.json、workflow.modules.json 等）。工作區須由用戶在 DSH 已登記列表中選擇，插件不會自行創建工作區根目錄。
適用場景與注意¶
適合： 需要在 DSH 桌面端把多步編碼任務結構化、希望計劃來自本地掃描而非反覆讓模型「重寫計劃」、且要在單次運行粒度上審計與回滾的團隊或個人。
注意：
- 插件以當前 DSH 進程的權限讀寫工作區與快照目錄；安裝前應通讀 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的安全策略。
- 導入需要能解析出圖文件落點的工作區；全新安裝且尚未綁定工作區時，導入流程會說明如何綁定，而不是猜測路徑。
- 改
lib/*.js需重啓 DSH；改lib/client.js刷新頁面即可。 - 日誌：
codeflow.log記錄插件生命週期與 UI 動作等，不記錄提示詞與源碼；可通過CODEFLOW_LOG=off關閉。
結尾¶
CodeFlow Canvas 把「智能體編碼」從不可 diff 的對話計劃，換成可本地掃描生成、可雙視圖編輯、以節點狀態爲證據、以快照爲撤銷邊界的工作流。查閱版本說明與截圖見 GitHub README；在社區目錄檢索見 SkillHub：dsh-codeflow-canvas 與 TheLiudawei/dsh-codeflow-canvas。
