企业官网建设流程全解析

Qwen Code Session Workflow 座舱实战：基于 todo_write 与 daemon 任务快照的 Web Shell 工作流检查器

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

导读

本文围绕 qwen-code 仓库中 session-workflow-cockpit-demo.md 展开，讲解如何把「协作座舱（collaboration-cockpit）」参考设计落地为 Web Shell 原生的工作流检查器（Workflow inspector）与依赖画布（dependency canvas），并且不引入任何新的工作流引擎。读完本文，你将掌握：如何用todo_write的blockedBy依赖建立稳定 Todo 计划、如何通过todo_id将 Agent 调用与步骤绑定、如何在 Web Shell 中启用并直接访问?view=cockpit依赖图，以及该能力刻意划出的职责边界。

一、设计意图：从参考设计到原生检查器

该分支（文档称之为 "This branch"）的核心思路是：把 collaboration-cockpit 参考设计转化为 Web Shell 原生的工作流检查器与依赖画布。关键约束是不新增工作流引擎——两个展示面（检查器与画布）都从**已持久化的会话转录（persisted session transcript）与 daemon 任务快照（daemon task snapshot）**投影而来。

这意味着工作流的"真相来源"仍然是会话自身的转录与 daemon 运行期快照，而非一套独立的编排状态机。前端只是把它们投影成可交互的视图，这为后续的演示、恢复、直接寻址提供了统一基础。

二、数据与控制流：谁提供数据，谁决定执行

原文档用 9 条要点定义了完整的数据与控制流，逐条拆解如下：

1. Todo 计划快照是唯一数据源：在启用的 Plan/revision 上下文中，todo_write快照提供稳定的 Todo ID、状态、内容以及blockedBy依赖。普通（非 Plan 上下文）的 Todo 快照会被 Workflow 忽略。
2. Agent 调用通过todo_id与 Todo 绑定：daemon 任务快照提供实时状态、活动（activity）、用量（usage）以及持久化的转录/输出路径。
3. exit_plan_mode仍是执行闸门：当实验性 Session Workflow 设置开启后，其 revision 绑定的审批（revision-bound approval）仍保留在现有 Chat 审批流中。
4. 审批复用现有权限 API：Workflow 自身不调度、不暂停、不持久化任务。
5. 入口：浮动 Todo 摘要（floating Todo summary）与 Session 头部在现有右侧面板中打开 Workflow 标签页，Chat 保持可见可用。
6. 检查器内容：展示摘要、需关注项（items needing attention）、有序步骤、选中步骤的依赖、Agent 活动与交付物（deliverables）。Agent 与交付物的操作在现有面板中打开兄弟标签页。
7. 依赖画布：「Expand dependency graph」打开专属画布，画布选中项与检查器选中步骤保持同步。
8. 直接寻址：?view=cockpit让依赖画布可被 URL 直接定位，浏览器导航返回 Chat。
9. 会话恢复：已完成的 Session 在正常打开时，从其标记的 Todo 快照恢复 Workflow 入口。

这 9 条可以归纳为三个层次：数据投影层（Todo 快照 + daemon 任务快照）、执行闸门层（exit_plan_mode+ 现有审批 API）、展示层（检查器 + 画布 + 直接寻址）。三层各司其职，避免把编排逻辑塞进 UI。

三、源码印证：todo_write 如何承载依赖语义

Workflow 的数据基础是todo_write工具，其 schema 与校验逻辑位于 packages/core/src/tools/todoWrite.ts。从源码可以确认以下事实：

3.1 参数结构与依赖字段

TodoWriteParams由todos（TodoItem[]）组成，每个TodoItem包含：

blockedBy的 schema 描述明确指出："Todo IDs that must be completed before this item. Active-plan updates preserve omitted dependencies for existing IDs; use[]to remove them."

3.2 校验规则与环检测

validateTodos（todoWrite.ts）完整实现了计划数据模型的合法性校验：

• 每个 Todo 必须有非空id与content，status必须合法；
• 列表内id必须唯一；
• blockedBy不得包含自身、不得重复引用、不得引用未知 ID（否则报references unknown dependency）；
• 最后用拓扑排序做环检测：若队列长度不等于 Todo 总数，则返回Todo dependencies must not contain a cycle.。

值得注意的实现细节：源码注释明确说明blockedBy的校验不依赖isSessionWorkflowEnabled()——"依赖是计划数据模型的语义，不是展示语义。把它挂在可视化开关上，会让同一次todo_write调用因是否有人在看图而存储不同的计划。"这意味着即使 Workflow 可视化关闭，依赖数据依然被持久化，为后续开启可视化后的恢复留好了底。

3.3 planId 与 Workflow 上下文标记

每次写入会读取/生成planId（新计划生成randomUUID()），并以<sessionId>.json存于 runtime 目录的todos子目录（getTodoFilePath）。当处于已批准的 Workflow 修订且 Session Workflow 上下文激活时，返回给 UI 的显示对象会附带sessionWorkflow: true标记，供前端渲染为 Workflow 视图（见 todoWrite.ts 中workflowContextActive的逻辑）。

3.4 配置开关

该功能是实验性设置，默认关闭。定义位于 packages/cli/src/config/settingsSchema.ts#L3986-L3995：

sessionWorkflow: { type: 'boolean', label: 'Session Workflow Plan & Review', category: 'Experimental', requiresRestart: false, default: false, description: 'Enable the daemon Web Shell Session Workflow DAG and present Plan mode as Plan & Review. Disabled by default; Workflow markers, approval gates, and visualization stay off until enabled. Todo updates preserve omitted active dependencies in every mode.', showInDialog: true, }

在 CLI 配置加载处（packages/cli/src/config/config.ts#L2329）通过sessionWorkflowEnabled: settings.experimental?.sessionWorkflow ?? false注入运行时配置。showInDialog: true意味着它会出现在Experimental → Session Workflow Plan & Review对话框中，与文档演示步骤一致。

3.5 前端检查器组件

前端投影逻辑位于 packages/web-shell/client/components/workflow/SessionWorkflowInspector.tsx。其输入是四路数据：todos（TodoItem）、tools（ACPToolCall）、tasks（DaemonSessionTaskStatus）、artifacts（DaemonSessionArtifact），经buildSessionWorkflowProjection合并成统一投影，并支持：

• selectedTodoId/onSelectedTodoIdChange：检查器与画布双向同步选中步骤；
• onExpandGraph：打开依赖画布；
• onOpenSubagent：在兄弟标签页打开 Agent 的持久化转录；
• canvasMode：区分检查器模式与全屏画布模式。

测试覆盖集中在 packages/web-shell/client/App.test.tsx（含?view=cockpit路由断言）与SessionWorkflowInspector.test.tsx。

四、端到端演示：从启动到打开依赖画布

原文档给出了完整的本地演示流程，可在仓库根目录直接复现。核心是起两个终端：一个跑 daemon（serve），一个跑 Web Shell，二者通过QWEN_DAEMON_URL相连。

4.1 终端 1：启动 daemon 并生成令牌

export QWEN_SERVER_TOKEN="$(openssl rand -hex 32)" printf 'Demo token: %s\n' "$QWEN_SERVER_TOKEN" npm run dev -- serve --port 4293 --workspace "$PWD" --no-web

要点：

• 用openssl rand -hex 32生成 32 字节随机令牌作为QWEN_SERVER_TOKEN，浏览器 URL 中需要携带它；
• serve --port 4293在 4293 端口启动 daemon，--workspace "$PWD"指定工作区，--no-web表示 daemon 自身不渲染 Web 界面；
• 记得把打印出的 token 复制下来，供第 4.3 节 URL 使用。

4.2 终端 2：启动 Web Shell

QWEN_DAEMON_URL=http://127.0.0.1:4293 npm run dev --workspace @qwen-code/web-shell -- --host 127.0.0.1 --port 5294

要点：

• 通过环境变量QWEN_DAEMON_URL指向终端 1 的 daemon 地址；
• 在@qwen-code/web-shellworkspace 下启动开发服务器，监听127.0.0.1:5294。

4.3 启用实验性设置并构造计划

在 Web Shell 中开启Experimental → Session Workflow Plan & Review，进入 Plan & Review 模式，然后发送如下提示词（原文档原样保留，包含精确的 todo 结构与依赖 ID）：

Prepare a five-bullet repository orientation. Before doing any inspection, call todo_write with exactly these pending steps and dependency IDs: inspect-readme; inspect-package; compare-findings blocked by inspect-readme and inspect-package; write-summary blocked by compare-findings. Immediately call exit_plan_mode. After approval, launch exactly two Explore subagents in parallel: one reads only README.md and returns at most three bullets; the other reads only package.json and returns at most three bullets. Pass todo_id inspect-readme and inspect-package to the matching Agent calls. Do not run shell commands or edit files. Update the Todo statuses as each phase completes and return at most five bullets.

这段提示词示范了该能力的关键约定：

• 先规划后执行：先todo_write声明 4 个步骤，其中compare-findings显式blocked by inspect-readme and inspect-package，write-summary blocked by compare-findings；
• 审批闸门：随后立即调用exit_plan_mode，将控制权交给现有审批流；
• 绑定关系：todo_id inspect-readme/inspect-package分别传给对应的 Explore subagent 调用；
• 纪律约束：明确禁止 shell 命令与文件编辑，只做只读探查。

4.4 会话存在后的直接寻址

Session 创建后，依赖画布可通过以下 URL 直接访问（token 替换为终端 1 打印的值）：

http://127.0.0.1:5294/session/<session-id>?token=<copied-token>&view=cockpit

其中<session-id>为真实会话 ID，view=cockpit是路由参数——前端 App.tsx 支持'cockpit'视图模式，浏览器导航（前进/后退）可自然返回 Chat。

4.5 预期流程

1. 待处理的exit_plan_mode请求在 Chat 中显示现有的流内计划审批（in-flow plan approval）；
2. 审批通过后开始执行；点击 Todo 摘要即可在不打断对话的情况下打开 Workflow 检查器；
3. 选中某个步骤，显示其依赖与绑定的 Agent；点击 Agent 在右侧面板的兄弟标签页中打开其持久化转录；
4. 点击Expand dependency graph打开完整画布，选中画布节点会反向更新检查器详情；
5. 返回 Chat 后检查器仍可用；Session 头或 Todo 摘要稍后可重新打开已完成的工作流，?view=cockpit则直接打开依赖图。

五、刻意边界：不越权、不虚构数据

原文档专门用一节说明该能力刻意不做什么，这是理解它架构定位的关键：

• 不复刻参考设计中的：组织级队列（organization-wide queues）、策略引擎（policy engine）、调度器（scheduler）、Skill 版本目录（Skill version catalog）与持久化决策账本（durable decision ledger）——这些属于协作座舱参考设计的重组件，本能力全部不实现；
• "待我处理"（待我处理）的语义：该视图中的待处理项从真实失败/取消的 Agent 任务推导，而不是维护一套虚拟队列；
• 权限请求留在 Chat：页面不会声称提供 daemon 并未提供的数据——"the page does not claim data the daemon does not provide"。

这一边界与源码实现互相印证：前端SessionWorkflowInspector的输入就是todos、tools、tasks、artifacts四类已存在的数据，全部来自会话转录与 daemon 任务快照的投影，没有任何额外的编排状态。展示层只是 daemon 事实的忠实读者。

六、小结

Qwen Code 的 Session Workflow 座舱演示了"不引入新引擎的工作流可视化"这一思路：以todo_write的blockedBy依赖作为计划数据模型（packages/core/src/tools/todoWrite.ts），以 daemon 任务快照补充运行期状态，以现有exit_plan_mode与权限 API 作为执行闸门，最终在 Web Shell 右侧面板投影出检查器与依赖画布两个视图。实验性开关experimental.sessionWorkflow（packages/cli/src/config/settingsSchema.ts#L3986-L3995）默认关闭，开启后即可按本文第四节步骤复现从规划、审批、执行到?view=cockpit直接寻址的完整链路。

对于希望在自己的项目里做同类"轻量工作流视图"的开发者，本设计最有参考价值的三点是：把依赖语义放进持久化数据模型而非可视化开关、用已有会话数据投影而非另建状态机、以及明确划定"展示层不虚构 daemon 未提供的数据"的边界。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code