前言¶
在 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。
