dsh-plugin-teamflow

dsh plugin --profile web add dsh-plugin-teamflow

dsh-plugin-teamflow

 

中文 | [English](./README.en.md)

TeamFlow 团队研发流水线 —— DeepSeek Harness 可分发插件（dsh plugin --profile web add 安装）。

把「用户一句话需求 → 真实研发团队多 Agent 流水线」做成宿主级能力：

需求 → PRD（基于既有模式/产品记忆，文档归档防臃肿）
     → （UI 改造时）UI/UX 设计
     → （新项目时）架构师规划并落地脚手架 + AGENTS.md
     → 高级全栈工程师技术方案（与派发任务对齐）
     → 可拆分任务时按并发并行开发
     → QA 功能测试（结构化缺陷 → 登记 Bug）
     → 产品验收（更新产品记忆）

界面预览

1. 全局面板——左侧边栏「🏭 团队工作台」图标（跨会话 / 产品线视角：产品线列表 + run 列表 + Backlog 标签页 + 覆盖式详情浮层）

2. 流水线视图——阶段蛇形泳道 + 节点卡片（状态/耗时/token/子代理会话）

3. 阶段详情抽屉——阶段性产物全文 + token 明细 +「🎬 跳转子代理会话」

4. Backlog 看板——需求/任务/缺陷拖拽泳道

5. 看板任务详情——任务卡抽屉（需求原文/分配/事件时间线/子卡/缺陷/token）

6. 团队选择——🏭 按钮 + 团队下拉

核心特性

• 一句话需求 → 可验收的交付：从需求到 PRD / 技术方案 / 并行开发 / QA / 验收全链路自动编排，每个阶段有任务卡、有产物、有结论；机械小改动可用 patch / lite 档裁剪阶段集，不必为一行改动跑完整瀑布。
• 多 Agent 团队 + 并行开发：按架构蓝图把需求拆成可并行任务（默认 3 路并发，上限 8），产品 / 架构 / 开发 / QA 各自独立上下文，互不污染。
• 防假交付：交付看证据不看措辞——阶段必须给出「命令 + 退出码 + 断言数」的验证证据，QA 有独立对抗探针，验收只认显式结论行（缺失即停线转人工）。
• QA 打回闭环：P0–P2 缺陷自动打回修复 → 复验（≤2 轮），每条缺陷都带「检测命令 + 通过判据」；超限转人工，不会伪装成「已完成」。
• 断点续跑 + 完成汇报：进程崩溃 / 重启后从第一个未完成阶段继续（已完成阶段复用产物）；流水线结束时自动把汇总（状态 / 阶段 / token / 后续指引）投递回发起会话。
• 你的仓库保持干净：流水线文档收口在 docs/teamflow/ 任务夹，插件自己的运行日志在 run 结束时归档出项目，收口提交只带代码 + 任务夹（一个 run 一个 commit，不需要你预先配置 .gitignore）。若历史提交里已经混进过 logs/teamflow/，在目标仓库执行 git rm -r --cached logs/teamflow 移出即可（本地文件保留）。
• 🏭 团队工作台（Web 双入口）：会话内 tab（流水线图 + 拖拽看板 + 成本中心 + 人工介入中心）与应用级主面板（产品线视角，跨会话可用）；点开 run 看阶段、token、验证证据与产物。界面中英双语，跟随宿主语言实时切换；host 侧的回复、流水线日志与产物文档同样跟随语言（run 起跑时定一次，同一条 run 内一致）。
• token 有账可查：按官方口径记录每个阶段的输入（未命中 / 命中）/ 写缓存 / 输出与调用数，并给出缓存命中率，汇报与看板同口径；机械阶段自动降档推理强度，重试时回升。

AGENTS.md 最小侵入原则（重要）

AGENTS.md 会被 harness 无条件注入每个会话，是团队资产。TeamFlow 遵循职责分离：

• AGENTS.md 只放稳定共识层：团队角色流程、工程约定、文档索引、<!-- teamflow:begin/end --> 托管区（仅指针）。
• 产品记忆/待办放独立活文档 docs/teamflow/memory.md（按需读取，不注入每次会话 → 省 token）。
• 已有项目接入：检测到 AGENTS.md 已存在 → 绝不重写/重排/覆盖，仅在文末追加托管块（若没有）；团队原有约定一行不动。
• 退出干净：团队停用 TeamFlow 后，删除托管块与 docs/teamflow/ 即完全复原，AGENTS.md 无残留账本。

架构（阶段 3）

web profile 宿主组合
├── teamflow-host   (host/)     Cordis service `teamflow`
│     ├── ctx.typert.register(strict descriptors)   ← Remote 方法（descriptors.ts 纯数据，host / client 共用）
│     ├── ctx.tools.register(teamflow_*)            ← 模型工具
│     └── node:fs → $DSH_HOME/teamflow/…            ← backlog / journal / 归档日志
└── teamflow-client (client/)   ← package.json 声明 dsh.client，宿主组合自动扫描注册
      ├── conversation.view「🏭 团队工作台」（会话内 tab）
      ├── sidebar.panellist + main/teamflow（全局产品线面板）
      └── sidebarRightTabs「teamflow-run」（右栏 run 详情）

两条硬约束决定了这个形态（详见 AGENTS.md §3）：不用 @Remote 装饰器（插件以纯 JS 分发，Remote 走 ctx.typert.register 的严格描述符）；必须是宿主级插件（动态插件的 fs 被沙箱限制在运行时根，写不了 $DSH_HOME）。

目录结构

dsh-plugin-teamflow/
  package.json          # dsh.bundle.patch + dsh.client 声明；exports 指向 lib/ 构建产物
  cordis.patch.yml      # 插件挂载 patch（insert 块，entry 用包根）
  tsdown*.config.ts     # 构建：client → lib/client.js；host/store/descriptors → lib/*.mjs
  host/                 # TeamflowService + core/*（流水线 / backlog / runner / guard / triage / state…）
  client/               # Web 工作台（会话内 tab + 全局面板 + 右栏 run 详情）
  store.ts              # 持久化层（原子写 / 备份 / 损坏自愈 + journal 序列化）
  descriptors.ts        # Remote 描述符（纯数据，host / client 共用）
  test/                 # 无依赖测试（node test/*.js，14 套件）
  docs/                 # ADR / 开发日志 / 评测语料 / release notes

全仓 TS/TSX：host 必须构建（Node 的 type stripping 对 node_modules 下的文件不生效，而宿主从 profile 的 node_modules 加载插件），改源码后跑 pnpm bundle 重建并同步 profile 副本的 lib/。逐文件说明与开发环境见 CONTRIBUTING.md。

环境要求

• DeepSeek Harness（dsh）宿主，web profile（插件含浏览器端工作台，client 面向 web 平台）；
• Node.js ≥ 22.18；
• 依赖宿主提供的 @deepseek-ai/dsh-* 与 react（peerDependencies，宿主注入，无需单独安装）。

版本锚定（dsh 宿主兼容性）

基线 dsh v0.2.1-rc.5（发布线最新 rc），下限 v0.2.1-rc.5，上界 <0.3.0。

⚠️ 订正（2026-10-15，issue #20）—— 下限由 v0.1.7-alpha.1 抬到 v0.2.1-alpha.2，不再向下兼容。

宿主在 alpha.2 把扁平入口 subagents.start(name, request) 整体删除（提交 3d852a1cea，首个含它的

tag 即 dsh-v0.2.1-alpha.2；官方迁移指南 docs/upgrade-guide/v0.2.1-alpha.1/subagent-activations/），

唯一入口改为 startActivation(spec)，且回执不再携带活 Agent 句柄（localAgent）。旧宿主上的症状是

「起得来、第一个阶段就 TypeError」——所以从本版起要求 dsh ≥ 0.2.1-alpha.2。

⚠️ 再抬（2026-11-01）—— 下限由 v0.2.1-alpha.2 抬到 v0.2.1-rc.5。 发布线已推进到 v0.2.1-rc.5；

本插件在 rc.5 及之后的 0.2.x（含实测运行的 0.2.2-alpha.2）上逐项验证通过。

engines.dsh 声明为单区间 ">=0.2.1-rc.5 <0.3.0"。此前下限为 0.2.1-alpha.2；下限与当前宿主同一 tuple，单区间即可（预发布只能匹配同 tuple 的比较器，而 0.2.1-rc 与 0.2.2-alpha 同属 0.2 tuple，includePrerelease 下均匹配）。semver 实测矩阵：

宿主版本 · >=0.2.1-rc.5 <0.3.0

0.2.1-rc.4 · ✗ false

0.2.1-rc.5 · ✓ true

0.2.1 · ✓ true

0.2.2-alpha.2 · ✓ true

0.3.0 · ✗ false

⚠️ 订正（2026-10-15，同上）：本 README 此前写「宿主不校验 engines.dsh」是错的。

宿主 @deepseek-ai/dsh-app-boot 装载 profile 时会校验它（packages/boot/app-boot/src/profile.ts

的 evaluatePluginCompatibility）：不满足的 bundle 被跳过并记入 skippedBundles（原因随诊断输出），

也可用 dsh plugin allow-version 按「精确插件版本 × 精确宿主版本」豁免。这个字段现在是真正的门禁，

不再只是兼容声明 —— 旧宿主上装本版插件会被宿主挡在装载阶段并说明原因，而不是跑起来才炸。

0.2.0 逐项核对：未发现破坏（tsc 对着已装的 0.2.0-rc.2 编译 0 错；实际 import 的 4 个宿主包导出 0 缺失；inject 语义、manifest schema、patch 的 insert: 均未变；新增的可选 external 本插件用不上）。⚠ 这是静态核对，运行时仍以重启实测为准。

可能受益：0.2.0 的 Windows ACL 修复（可重测「E: 盘 fresh 目录 grantWrite 必败 Win32 5」）；user-questions 的定时等待与迟到回复（澄清闸

…(truncated)