dsh-plugin-teamflow 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/README.en.md +162 -137
- package/README.md +168 -148
- package/lib/client.js +0 -2
- package/lib/descriptors.mjs +0 -2
- package/lib/host.mjs +11 -8
- package/lib/store.mjs +0 -2
- package/package.json +97 -70
- package/lib/client.js.map +0 -1
- package/lib/descriptors.mjs.map +0 -1
- package/lib/host.mjs.map +0 -1
- package/lib/store.mjs.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
> 本插件首次公开发布版本为 **v0.1.0**；发布前的内部迭代（v0.3~v0.13）记录于 `AGENTS.md` §5，对外统一归到 v0.1.0。
|
|
4
|
+
|
|
5
|
+
## [0.1.2] - 2026-08-26
|
|
6
|
+
|
|
7
|
+
### 变更
|
|
8
|
+
- 提示词指令层英文化（方案 A）：指令英文 + 输出契约中文（PRD 头部声明 / QA 缺陷表 / 验收结论等解析器锚点不变）；工具描述英文化
|
|
9
|
+
- backlog 卡片 / 详情抽屉跳转指定 run 的流水线视图（host `backlog` 附带 `runId` 映射）
|
|
10
|
+
- 详情抽屉长文本折叠（概览 / 需求原文默认预览几行，可展开收起）
|
|
11
|
+
- 断点重跑语义修正：阶段全 done 的 failed/cancelled 不再显示续跑按钮（host 硬拒绝兜底）；按钮/pill/chip 补 runId 全名可溯
|
|
12
|
+
- 架构蓝图提取回退任务夹 `TECHNICAL.md`（模型把蓝图写进文档而非回复输出时 M2 拆卡不再退化为整体开发）
|
|
13
|
+
- `meta.json` 改为静态标识卡（废弃终态回写，status/endedAt 权威在 journal）
|
|
14
|
+
- 开源发布元数据：keywords / homepage / bugs；`react` 移入 peerDependencies；README.en.md 与 CHANGELOG.md 显式进包
|
|
15
|
+
|
|
16
|
+
## [0.1.1] - 2026-08-26
|
|
17
|
+
|
|
18
|
+
### 修复
|
|
19
|
+
- npm 发布包 `files` 白名单收窄为 `lib` / `cordis.patch.yml` / `README.md`，不再携带 `AGENTS.md` 与 `docs/adr`（开发者文档仅保留在 GitHub 仓库）
|
|
20
|
+
|
|
21
|
+
## [0.1.0] - 2026-08-26
|
|
22
|
+
|
|
23
|
+
### 初始公开发布
|
|
24
|
+
- 一句话需求 → 多 Agent 研发流水线（PRD / 设计 / 架构 / 技术方案 / 并行开发 / QA / 验收）
|
|
25
|
+
- backlog 持久化 + 断点续跑（自研 journal，不依赖 LangGraph）
|
|
26
|
+
- 防假交付：实质校验 + token 熔断 + 产品级并发锁 + 内存裁剪
|
|
27
|
+
- 完成汇总自动汇报主线程（空闲唤醒 / 忙碌注入）
|
|
28
|
+
- token 官方口径计量（输入未命中 / 命中 / 写缓存 / 输出 + 调用数 + 缓存命中率）
|
|
29
|
+
- lite / tech / patch 模式 + 模型驱动需求分诊（`teamflow_triage`）
|
|
30
|
+
- 🏭 团队工作台 Web tab：阶段泳道 / 拖拽看板 / 成本中心 / 人工介入中心
|
|
31
|
+
- QA 打回修复有界闭环（ADR-0007，超限转 needs-human）
|
|
32
|
+
- 任务夹文档制（ADR-0008）：每需求自包含任务夹，消除双归档 / memory 堆积
|
package/README.en.md
CHANGED
|
@@ -1,137 +1,162 @@
|
|
|
1
|
-
# dsh-plugin-teamflow
|
|
2
|
-
|
|
3
|
-
[
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
→
|
|
14
|
-
→
|
|
15
|
-
→
|
|
16
|
-
→
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
- **
|
|
27
|
-
- **
|
|
28
|
-
- **
|
|
29
|
-
- **
|
|
30
|
-
- **
|
|
31
|
-
- **
|
|
32
|
-
- **
|
|
33
|
-
- **Token
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
AGENTS.md
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- **
|
|
48
|
-
- **
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
│
|
|
58
|
-
│
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
**Why
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
dsh
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
Note: `
|
|
119
|
-
|
|
120
|
-
##
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
1
|
+
# dsh-plugin-teamflow
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-plugin-teamflow) [](./LICENSE)
|
|
4
|
+
|
|
5
|
+
[中文](./README.md) | English
|
|
6
|
+
|
|
7
|
+
TeamFlow team R&D pipeline — a distributable DeepSeek Harness plugin (install via `dsh plugin --profile web add`).
|
|
8
|
+
|
|
9
|
+
Turns "one-line user requirement → real R&D team multi-agent pipeline" into a host-level capability:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
requirement → PRD (based on existing patterns / product memory, archived to prevent bloat)
|
|
13
|
+
→ (UI redesign) UI/UX design
|
|
14
|
+
→ (new project) architect plans and scaffolds + AGENTS.md
|
|
15
|
+
→ senior full-stack engineer tech spec (aligned with dispatched tasks)
|
|
16
|
+
→ parallel dev when tasks are splittable
|
|
17
|
+
→ QA functional testing (structured defects → register bugs)
|
|
18
|
+
→ product acceptance (update product memory)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Core Features
|
|
22
|
+
|
|
23
|
+
- **Anti-fake-delivery**: ① Substantive validation — outputs containing rejection phrases ("I cannot complete", etc.) or below the per-stage length floor are treated as undelivered and routed to retry / human intervention; ② Token circuit breaker — a single stage accumulating 60k budget stops retries; ③ Context-exhaustion failures are not retried (retrying the same prompt likely reproduces); ④ Product-level concurrency lock — only one active pipeline per product at a time, preventing requirement state from stepping on itself; ⑤ Full stage outputs are retained (memory + disk) for the detail drawer and checkpoint resume.
|
|
24
|
+
- **Auto completion report to main thread**: when a pipeline ends (success / failure / cancel / interrupt), it automatically delivers a summary (status / stage stats / total token / backlog / next-step guidance) to the initiating session's Agent — wakes on idle (followup), injects next-step context when busy (inject), using the same mechanism as DSH's background-task notifications (tool-jobs mode, but independently implemented and not dependent on the web-disabled tool-jobs). The user need not watch the panel; the model relays the result or continues per guidance (claim defects / transition / resume from checkpoint).
|
|
25
|
+
- **Resume from checkpoint**: every stage checkpoint persists to `$DSH_HOME/teamflow/runs/<runId>.json` (LangGraph checkpointer semantics); after a process crash / restart it is auto-marked `interrupted`, and `teamflow_resume` / the panel's "↻ resume from checkpoint" continues from the first unfinished stage (skipping completed stages, reusing full stage outputs).
|
|
26
|
+
- **Backlog persistence (workspace-isolated since v0.1.0)** under `$DSH_HOME/teamflow/<workspace>/backlog/` as `requirements.json` / `tasks.json` / `bugs.json`, surviving restarts; backlog is isolated per "workspace (project)" — one workspace is one product line, and different workspaces each see their own Team Workspace.
|
|
27
|
+
- **Single-task model **: one requirement = one rotating task card (no longer split by role); the task card records `devAssign` / `qaAssign` / acceptor, with state rotation: todo → developing → to-test → testing → to-accept → accepted | bounced | needs-human; the delivered frontend page also shows each role's **real token usage** spent on that task.
|
|
28
|
+
- **Artifact consolidation **: pipeline docs (PRD / design / architecture / tech spec / QA / memory / history) all consolidate into `docs/teamflow/`, command run logs into `logs/teamflow/<runId>/`, so the host `docs/<role>/` and project root are no longer polluted by TeamFlow; the host-side run log likewise lands in `<workspace>/logs/teamflow/<runId>.log`.
|
|
29
|
+
- **State machine + event log**: requirement (initiated → in-progress → to-accept → accepted), task (todo → developing → to-test → testing → to-accept → done | bounced | needs-human), defect (to-claim → in-progress → fixed-to-verify → closed).
|
|
30
|
+
- **Bounce-back threshold**: 2 consecutive Agent failures in a single stage auto-retry; still failing → `needs-human`, requiring human intervention.
|
|
31
|
+
- **Concurrency pool**: dev tasks run in parallel by `maxConcurrency` (default 3, max 8).
|
|
32
|
+
- **QA defect registration**: the QA report outputs in a fixed table → auto-parsed into bugs entering the backlog.
|
|
33
|
+
- **Token metering (official semantics)**: each stage records `usage` = **cache-miss input / cache-hit input / write-cache / output + call count** (accumulated per event by the sub-agent session) + **cache hit rate** (cacheRead / (input + cacheRead)). Workspace cards / task cards / completion reports all display in this basis — model-agnostic and consistent with the official bill.
|
|
34
|
+
- **lite mode **: lightweight micro-features — `teamflow_start(lite:true)` skips the standalone tech-spec doc stage (PRD is the contract) and goes straight **PRD → dev → QA → acceptance**; with `needDesign:true` it **keeps the UI/UX design stage**. Measured ~64% time / ~88% token savings vs the full 7-stage run.
|
|
35
|
+
- **Token circuit breaker**: when a stage's official total consumption (input + cacheRead + cacheWrite + output accumulated) exceeds `STAGE_TOKEN_BUDGET` (default 60k), retries stop and human intervention is required.
|
|
36
|
+
- **🏭 Team Workspace (Web tab)**: a session-header tab alongside chat / trace, containing:
|
|
37
|
+
- Pipeline graph (stage swimlanes + node cards: status / duration / token / sub-agent session, 2s live refresh)
|
|
38
|
+
- **Backlog drag-drop kanban** (requirement / task / defect three status swimlanes, cards dragged to transition, native HTML5 DnD zero-dep)
|
|
39
|
+
- Cost center (per-stage token + total + runtime)
|
|
40
|
+
- Human-intervention center (needs-human items aggregated + one-click terminal state)
|
|
41
|
+
- History run switching + product switching
|
|
42
|
+
|
|
43
|
+
## AGENTS.md minimal-invasion principle (important)
|
|
44
|
+
|
|
45
|
+
AGENTS.md is unconditionally injected into every session by the harness; it is **team assets**. TeamFlow follows separation of concerns:
|
|
46
|
+
|
|
47
|
+
- **AGENTS.md holds only the stable consensus layer**: team role flows, engineering conventions, doc index, and the `<!-- teamflow:begin/end -->` managed region (pointers only).
|
|
48
|
+
- **Product memory / todos go in a separate live doc** `docs/teamflow/memory.md` (read on demand, not injected every session → saves token).
|
|
49
|
+
- **Onboarding existing projects**: if AGENTS.md already exists → never rewrite / reorder / overwrite; only append a managed block at the end (if none); the team's original conventions are left untouched line by line.
|
|
50
|
+
- **Clean exit**: after a team stops using TeamFlow, deleting the managed block and `docs/teamflow/` fully restores it, with no ledger left in AGENTS.md.
|
|
51
|
+
|
|
52
|
+
## Architecture (stage 3)
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
web profile host composition
|
|
56
|
+
├── teamflow-host (dsh-plugin-teamflow/host) Cordis service `teamflow`
|
|
57
|
+
│ └── TeamflowService extends TypertRemoteService
|
|
58
|
+
│ ├── ctx.typert.register(strict descriptors) ← 17 Remote methods
|
|
59
|
+
│ ├── ctx.tools.register(teamflow_*) ← 11 model tools
|
|
60
|
+
│ └── node:fs → $DSH_HOME/teamflow/...
|
|
61
|
+
└── teamflow-client (dsh-plugin-teamflow/client, auto-scanned) ← package.json declares dsh.client,
|
|
62
|
+
└── ctx.remote.$mount(TEAMFLOW_REMOTE_CONTRIBUTION) no patch line needed, clientModules auto-registers
|
|
63
|
+
└── conversation.view tab "🏭 Team Workspace"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Why not the @Remote decorator**: host plugins are distributed as plain JS to avoid decorator syntax / TS compilation requirements; `ctx.typert.register` registers strict descriptors (`descriptors.js` pure data, shared by host/client, keeping endpoint and wire parameters consistent).
|
|
67
|
+
|
|
68
|
+
**Why a host-level plugin (not a dynamic plugin)**: dynamic (in-session) plugins run in a restricted sandbox whose `fs` is hard-limited to the runtime root and cannot write to `$DSH_HOME` or the session workspace (observed `file access denied under workspace-write mode`). Only a formal plugin inside the host composition has real Node `fs`, able to land backlog in `$DSH_HOME`, and the client can register an independent tab.
|
|
69
|
+
|
|
70
|
+
## Directory structure
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
dsh-plugin-teamflow/
|
|
74
|
+
package.json # dsh.bundle.patch + dsh.client declarations; exports point to lib/ build output
|
|
75
|
+
cordis.patch.yml # insert block; entry name uses package root (so clientModules can scan dsh.client)
|
|
76
|
+
tsdown.config.ts # client build (ModuleLoader bundle → lib/client.js)
|
|
77
|
+
tsdown.host.config.ts # host/store/descriptors build (ESM → lib/*.mjs)
|
|
78
|
+
descriptors.ts # Remote descriptors (pure data, shared by host/client)
|
|
79
|
+
store.ts # persistence layer: atomic write / backup / corruption self-heal + journal serialize / load (independently testable)
|
|
80
|
+
host/index.ts # TeamflowService (TS; built to lib/host.mjs for the host to load)
|
|
81
|
+
client/index.tsx # Team Workspace (TSX; built to lib/client.js)
|
|
82
|
+
test/smoke.js # dependency-free smoke test (descriptors / structure / security hardening)
|
|
83
|
+
test/journal.test.js # journal behavior test (runs store.ts source directly)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**TypeScript note**: the whole repo is TS/TSX. The host **must be built** (cannot rely on Node strip-types to run directly) — Node 22's type stripping does not apply to files under `node_modules` ("unsupported for files under node_modules"), while the host composition loads plugins from `profile/node_modules`. Consistent with the DSH ecosystem (the `@deepseek-ai/dsh-*` host packages' exports all point to lib/*.js). After changing source, run `pnpm bundle` to rebuild and sync the profile copy's `lib/`.
|
|
87
|
+
|
|
88
|
+
## Requirements
|
|
89
|
+
|
|
90
|
+
- DeepSeek Harness (dsh) host, **web profile** (the plugin ships a browser-side workspace; the client targets the web platform);
|
|
91
|
+
- Node.js ≥ 22.18;
|
|
92
|
+
- Relies on host-provided `@deepseek-ai/dsh-*` and `react` (peerDependencies, injected by the host — no separate install needed).
|
|
93
|
+
|
|
94
|
+
## Install (for users)
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
# Install from npm (after publish)
|
|
98
|
+
dsh plugin --profile web add dsh-plugin-teamflow
|
|
99
|
+
|
|
100
|
+
# Or local directory install (during development)
|
|
101
|
+
dsh plugin --profile web add file:./plugins/dsh-plugin-teamflow
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
After install, **restart** `dsh --profile web` for the host `teamflow-host` to take effect:
|
|
105
|
+
- The model side gains 11 `teamflow_*` tools: `start / triage / status / backlog / claim / update / assign / cancel / resume / pause / resume_session`;
|
|
106
|
+
- The browser session header shows the "🏭 Team Workspace" tab;
|
|
107
|
+
- Backlog is written to `$DSH_HOME/teamflow/<product>/backlog/*.json`.
|
|
108
|
+
|
|
109
|
+
> Note: `@deepseek-ai/*` are host-private packages; running requires the DeepSeek Harness (dsh) host environment; this package is neither published standalone nor runnable alone.
|
|
110
|
+
|
|
111
|
+
## Quick start
|
|
112
|
+
|
|
113
|
+
1. **Pick a team**: click the 🏭 button next to the input box and choose a team (or "no team" = chat directly, no pipeline);
|
|
114
|
+
2. **Say the requirement**: just describe it — the model calls `teamflow_start` automatically (auto-triage: patch / lite / tech / medium / full); or force a mode, e.g. "run this in medium mode";
|
|
115
|
+
3. **Watch progress**: switch to the 🏭 Team Workspace tab in the session header — the pipeline graph live-refreshes (per-stage token / duration / sub-agent session), and the backlog kanban supports drag transitions and card detail drawers;
|
|
116
|
+
4. **Get the result**: the pipeline reports back to the session automatically when done (status / stage stats / token / next steps); interrupted/failed runs can "↻ resume from checkpoint".
|
|
117
|
+
|
|
118
|
+
> Note: after `teamflow_start`, the **main thread should not modify code or run verifications itself** — implementation, QA, and reporting are done by pipeline sub-agents (avoid fighting the pipeline over the workspace).
|
|
119
|
+
|
|
120
|
+
## Uninstall (for users)
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
dsh plugin --profile web remove dsh-plugin-teamflow
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
After restarting `dsh --profile web`, the plugin is fully removed (the model-side `teamflow_*` tools and the 🏭 Team Workspace tab disappear).
|
|
127
|
+
|
|
128
|
+
Optional cleanup (NOT done automatically; run as needed):
|
|
129
|
+
- **Runtime data**: delete `$DSH_HOME/teamflow/` (backlog / run records — confirm you no longer need them first).
|
|
130
|
+
- **Project traces**: if a team used TeamFlow in a project, delete the `<!-- teamflow:begin/end -->` managed block in that project's `AGENTS.md` and the `docs/teamflow/` directory to fully restore it (the "clean exit" rule of the AGENTS.md minimal-invasion principle).
|
|
131
|
+
|
|
132
|
+
## Development & verification
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
npm test # smoke (descriptors / structure / security) + journal (resume behavior)
|
|
136
|
+
npm run typecheck # tsc --noEmit type check (same as VSCode, no drift)
|
|
137
|
+
node --check lib/host.mjs lib/client.js lib/store.mjs lib/descriptors.mjs
|
|
138
|
+
npm run bundle # build client (tsdown → lib/client.js, __ModuleLoader__.load registers)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**For plugin developers** (the local dev loop of THIS plugin): see [`AGENTS.md`](./AGENTS.md) and [`docs/adr/`](./docs/adr) in the repo — deployment sync (`node deploy.mjs` → restart `dsh --profile web`), the "running web loads the host from the profile deployment copy, building source alone does not take effect" caveat, design decision records (ADR-0001~0008) and benchmarks (`docs/benchmarks/`). All repo source is TS/TSX and must be built first (`pnpm bundle`) to run (`strip-types` does not apply under `node_modules`).
|
|
142
|
+
|
|
143
|
+
Note: `lib/` is excluded by `.gitignore` but must ship with the package (`files` whitelist includes `lib/`; `exports["./client"]` points to `./lib/client.js`).
|
|
144
|
+
|
|
145
|
+
## Contract quick reference
|
|
146
|
+
|
|
147
|
+
| Tool / Remote | Purpose |
|
|
148
|
+
|---|---|
|
|
149
|
+
| `teamflow_start` / `teamflow.start(sessionId, requirement, options)` | Start the pipeline |
|
|
150
|
+
| `teamflow_status` / `teamflow.list()` + `teamflow.snapshot(runId)` | Query run progress (stage / status / token / log / needs-human?) |
|
|
151
|
+
| `teamflow_backlog` / `teamflow.backlog(product)` | View backlog (+ persistence path) |
|
|
152
|
+
| `teamflow_claim` | Claim a task or defect |
|
|
153
|
+
| `teamflow_update` / `teamflow.backlogUpdate(kind, id, to, product, reason)` | Manually transition state (handle needs-human) |
|
|
154
|
+
| `teamflow_cancel` / `teamflow.cancel(runId)` | Cancel a run |
|
|
155
|
+
| `teamflow_resume` / `teamflow.resume(runId, sessionId)` | Resume from checkpoint (rerun from first unfinished stage) |
|
|
156
|
+
| `teamflow_triage` | Requirement triage preview (start auto-triages by default; use only to pre-assess / force a mode) |
|
|
157
|
+
| `teamflow_assign` | Assign owner of a task / defect (separate from claim: claim only changes state) |
|
|
158
|
+
| `teamflow_pause` / `teamflow_resume_session` | Pause / resume teamflow triggering for the current session (session-level, auto-reset on new session) |
|
|
159
|
+
|
|
160
|
+
## License
|
|
161
|
+
|
|
162
|
+
MIT — see [LICENSE](./LICENSE).
|