dsh-plugin-teamflow

dsh-plugin-teamflow

中文 | English

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

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

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

界面预览

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

  

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

  

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

  

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

  

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

  

• 团队选择——🏭 按钮 + 团队下拉

  

核心特性

• 一句话需求 → 可验收的交付：从需求到 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.1.7-alpha.1（session 格式 v4）。这也是「能跑流水线」的宿主下限：插件注入的每条 message 必须带 producer-owned 的 source.kind（plugin:dsh-plugin-teamflow），而 v3 宿主把 source.kind 校验为封闭词表（SOURCE_KINDS 不含 plugin:*）——旧写法 {kind:'plugin', plugin:…} 在 v4 宿主当场被拒，新写法在 v3 宿主同样非法，两种形态互不兼容，故不再声称可回退到 v0.1.5-rc.2 运行。Remote 描述符仍同时提供 schema 与 create() 两个字段（供不同代际的宿主读取），见下「typert 描述符契约」。package.json 的 engines.dsh: ">=0.1.7-alpha.1 <0.2.0"（已随本次下限收窄，见下条实测）与 dsh.manifestVersion: 1 是作者声明性元数据（宿主不读取/校验）。

⚠️ 预发布 tuple 规则与本次区间的实测关系（2026-09-23 用 semver 7.7.4 的 satisfies 实测）：受「预发布版本只匹配同 [major,minor,patch] tuple 的区间」规则约束——>=0.1.7-alpha.1 <0.2.0 对 0.1.7-alpha.1 / 0.1.7-alpha.2 / 0.1.7 / 0.1.8 / 0.1.9 判 PASS，对 0.1.6-alpha.2 / 0.1.6 / 0.2.0-rc.1 / 0.2.0 判 fail（与上条 v4 下限恰好一致）。注意旧区间 >=0.1.5-rc.2 <0.2.0 在同一 rule 下连当时正在用的 0.1.6-alpha.2 都判 false，所以这类字段只表达对正式版的兼容声明；宿主既不校验它，日常应以 next 为准——latest 常滞后于 next，不要用 latest 判断发布线。

v0.1.7-alpha.1 的 breaking 面（本次核对）：session 事件格式升到 v4——宿主在事件被 Session 采纳前校验每条 message 的 source.kind，拒绝 v3 退役的 plugin wrapper（{kind:'plugin', plugin:…} → 抛 format v4 message requires a producer-owned source kind），要求 kind:'plugin:<name>'。插件原先四处注入（团队上下文 ×2 / 完成汇报 / 护栏提醒）写的都是旧 wrapper → 新 run 在写入阶段即失败（journal 都落不了盘）。现已全部改为 plugin:dsh-plugin-teamflow。全量核对其余面（typert 严格描述符仍要 create()、subagents.start/SubagentRun、tokenUsage 四桶 + sessionStats.steps、agent.inject/followup/steer、settings.locale 只读端口、remote.$mount、sessions.openSubagent、sidebarRight.openResource）均无破坏。

v0.1.6-alpha.2 的 breaking 面（上次核对）：typert strict codec 由 { mode, typeSymbol, schema } 变为 { mode, typeSymbol, create: () => Schema }（懒物化，materializeSchema 里 record.value ??= record.create()）；validateCodec 对缺 create() 的 strict codec 注册即抛 "strict codec has no create() factory"。叠加 dsh-app-boot 的策略（required 插件 activate 失败 → 整个 profile startup failed），表现为插件一挂就是「dsh 起不来」（web boot: N entries did not activate）。全量 diff 其余面（client-modules / subagent / agent runtime / manifest / tools 的 llm 投影）对本插件无破坏，三个 UI slot 包的 src/index.ts 零变更 → slot 名安全。

升级 dsh 后若行为异常，先核对两处：① 插件注入的 session 事件（tool-workflow/agent-start、user/message + source.kind='plugin:dsh-plugin-teamflow'）必须落在宿主事件词表内——v4 宿主只收 producer-owned 的 source kind（plugin 这个 v3 wrapper 已退役），而 v3 宿主的封闭词表也不收 plugin:*（因此下限是 v4 宿主）；tool-workflow/agent-start 不带 message/source 槽位，不在该校验范围内。新增自定义事件类型要带 ignorable: true、已知类型不要加词表外的键；② 计量读的是宿主投影 key（tokenUsage / sessionStats），宿主改 key 或 state 版本时需同步 host/core/metering.ts。历次兼容核对结论与待跟进项见 CHANGELOG.md（0.1.6–0.1.9 段）与 docs/TODO.md（例如复读检测仍读已弃用的事件读取器）。

安装（对使用者）

# 从 npm 安装（发布后）
dsh plugin --profile web add dsh-plugin-teamflow

# 或本地目录安装（开发时）
dsh plugin --profile web add file:./plugins/dsh-plugin-teamflow

安装后重启 dsh --profile web，宿主行 teamflow-host 生效：

• 模型侧出现 12 个 teamflow_* 工具：start / triage / status / backlog / claim / update / assign / cancel / resume / pause / resume_session / merge；
• 浏览器侧：会话头部「🏭 团队工作台」tab（会话内）+ 左侧边栏「团队工作台」图标（全局面板，产品线视角）；
• backlog 写入 $DSH_HOME/teamflow/<product>/backlog/*.json。

注意：@deepseek-ai/* 为宿主私有包，运行需 DeepSeek Harness（dsh）宿主环境；本包不发布也无法独立运行。

快速上手

• 选团队：会话输入框旁点「🏭」按钮，选择团队（或选「无团队」= 不走流水线，直接对话）；
• 发需求：直接说需求，模型会自动调用 teamflow_start（自动分诊模式：patch / lite / tech / medium / full）——也可以用「直接跑 medium 模式做这个」等指定档位；
• 看进展：会话头部切到「🏭 团队工作台」tab——流水线图实时刷新（每阶段 token / 耗时 / 子代理会话），Backlog 看板可拖拽流转、点卡片看详情；点「⇥ 右栏打开」把该 run 详情放到右侧栏（与任务夹产物并排）。想看跨会话/全局的情况，点左侧边栏「团队工作台」图标（产品线视角：产品线 → run 列表 + backlog）；
• 收结果：流水线完成后自动向当前会话汇报（状态 / 阶段统计 / token / 后续指引）；中断/失败的运行可「↻ 从断点重跑」。

使用规则提醒：teamflow_start 调用后主线程不要自行改代码或跑验证——实现、QA、汇报由流水线各阶段子代理完成（避免与流水线抢活）。

卸载（对使用者）

dsh plugin --profile web remove dsh-plugin-teamflow

重启 dsh --profile web 后插件完全移除（模型侧 teamflow_* 工具与「🏭 团队工作台」tab 消失）。

可选清理（卸载不会自动清，按需执行）：

• 运行数据：删除 $DSH_HOME/teamflow/（backlog / 运行记录，删除前确认不再需要）。
• 项目痕迹：若某项目用过 TeamFlow，删除该项目 AGENTS.md 中的 <!-- teamflow:begin/end --> 托管块与 docs/teamflow/ 目录，即可完全复原（AGENTS.md 最小侵入原则的"退出干净"）。

开发与验证

pnpm test               # smoke（描述符/结构/安全）+ journal（断点续跑行为）
pnpm run typecheck      # tsc --noEmit 类型检查（需本机 dsh profile 提供 @deepseek-ai/* 类型）
node --check lib/host.mjs lib/client.js lib/store.mjs lib/descriptors.mjs
pnpm run bundle         # 构建 client（tsdown → lib/client.js，__ModuleLoader__.load 注册）

插件开发者（本插件的本地开发链路）见仓库内 AGENTS.md 与 docs/adr/——含部署同步（node deploy.mjs → 重启 dsh --profile web）、生效前提（运行中 web 从 profile 部署副本加载 host，只构建源码不生效）、设计决策记录（ADR-0001~0009）与基准对比（docs/benchmarks/）。本仓库其余源码均为 TS/TSX，需先 pnpm bundle 构建后再运行（node_modules 下 strip-types 不生效）。

注意：lib/ 被 .gitignore 排除，但发布必须带上构建产物（files 白名单已含 lib/；exports["./client"] 指向 ./lib/client.js）。

契约速览

工具 / Remote	作用
teamflow_start / teamflow.start(sessionId, requirement, options)	启动流水线
teamflow_status / teamflow.list() + teamflow.snapshot(runId)	查询运行进度（阶段/状态/token/日志/是否需人工）
teamflow_backlog / teamflow.backlog(product)	查看 backlog（+ persistence 落盘路径）
teamflow_claim	认领任务或缺陷
teamflow_update / teamflow.backlogUpdate(kind, id, to, product, reason)	人工流转状态（处理 needs-human）
teamflow_cancel / teamflow.cancel(runId)	取消运行（工作台 / 全局面板 run 行 / run 详情三处按钮，两段式确认；仅对正在跑的 run 生效）
teamflow_resume / teamflow.resume(runId, sessionId)	断点续跑（从第一个未完成阶段重跑）
teamflow_triage	需求分诊预览（默认 start 自动分诊，仅在想预评估/强制 mode 时使用）
teamflow_assign	指定任务/缺陷的负责人（与 claim 分离：claim 只改状态）
teamflow_pause / teamflow_resume_session	当前会话暂停/恢复 teamflow 触发（会话级，新会话自动重置）

License

MIT —— 详见 LICENSE。