dsh-harness-kit 0.1.3 → 0.1.4
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/README.md +2 -2
- package/README.zh-CN.md +2 -2
- package/kernel/commands.js +10 -0
- package/kernel/models.js +3 -1
- package/package.json +1 -1
- package/packs/ai-coding/agents/business-analyst.md +2 -0
- package/packs/ai-coding/agents/code-reviewer.md +2 -0
- package/packs/ai-coding/agents/developer.md +2 -0
- package/packs/ai-coding/agents/project-manager.md +20 -1
- package/packs/ai-coding/agents/readiness-reviewer.md +2 -0
- package/packs/ai-coding/agents/solution-architect.md +2 -0
- package/packs/ai-coding/agents/test-engineer.md +2 -0
- package/packs/ai-coding/assets/templates/handoff.md +48 -0
- package/packs/ai-coding/rules/core.md +19 -0
package/README.md
CHANGED
|
@@ -234,7 +234,7 @@ go only to the provider you configure.
|
|
|
234
234
|
**Plugins → Add plugin**, then enter:
|
|
235
235
|
|
|
236
236
|
```
|
|
237
|
-
dsh-harness-kit@0.1.
|
|
237
|
+
dsh-harness-kit@0.1.4
|
|
238
238
|
```
|
|
239
239
|
|
|
240
240
|
Enable the bundle after installation.
|
|
@@ -242,7 +242,7 @@ Enable the bundle after installation.
|
|
|
242
242
|
### Command line
|
|
243
243
|
|
|
244
244
|
```sh
|
|
245
|
-
dsh plugin --profile desktop add dsh-harness-kit@0.1.
|
|
245
|
+
dsh plugin --profile desktop add dsh-harness-kit@0.1.4
|
|
246
246
|
```
|
|
247
247
|
|
|
248
248
|
Quit DSH Desktop first; replace `desktop` with your profile name for other profiles.
|
package/README.zh-CN.md
CHANGED
|
@@ -200,7 +200,7 @@ AI 写得越快,需要看的越多。固定角色让 CR/TE 各自只做一件
|
|
|
200
200
|
**Plugins → Add plugin**,输入:
|
|
201
201
|
|
|
202
202
|
```
|
|
203
|
-
dsh-harness-kit@0.1.
|
|
203
|
+
dsh-harness-kit@0.1.4
|
|
204
204
|
```
|
|
205
205
|
|
|
206
206
|
安装后启用 bundle。
|
|
@@ -208,7 +208,7 @@ dsh-harness-kit@0.1.3
|
|
|
208
208
|
### 命令行
|
|
209
209
|
|
|
210
210
|
```sh
|
|
211
|
-
dsh plugin --profile desktop add dsh-harness-kit@0.1.
|
|
211
|
+
dsh plugin --profile desktop add dsh-harness-kit@0.1.4
|
|
212
212
|
```
|
|
213
213
|
|
|
214
214
|
需要先完全退出 DSH Desktop;其他 profile 把 `desktop` 换成实际名称。
|
package/kernel/commands.js
CHANGED
|
@@ -395,6 +395,16 @@ async function hkNew({ agent, rawInput }) {
|
|
|
395
395
|
.replaceAll('{{source}}', reqFile === '(无)' ? '描述' : '描述+文件')
|
|
396
396
|
.replaceAll('{{file}}', reqFile);
|
|
397
397
|
fs.writeFileSync(path.join(taskDir, 'proposal.md'), doc, 'utf8');
|
|
398
|
+
// 交接摘要模板:PM 在每次派发前更新,Worker 只读 handoff + 指定章节,不整份重读上游文档。
|
|
399
|
+
const handoffTplPath = path.join(packDir(kit), 'assets', 'templates', 'handoff.md');
|
|
400
|
+
if (fs.existsSync(handoffTplPath)) {
|
|
401
|
+
const handoff = fs.readFileSync(handoffTplPath, 'utf8')
|
|
402
|
+
.replaceAll('{{task}}', task)
|
|
403
|
+
.replaceAll('{{desc}}', desc)
|
|
404
|
+
.replaceAll('{{profile}}', '待判定')
|
|
405
|
+
.replaceAll('{{round}}', '1');
|
|
406
|
+
fs.writeFileSync(path.join(taskDir, 'handoff.md'), handoff, 'utf8');
|
|
407
|
+
}
|
|
398
408
|
// --base 开发基线(同时是分析基点与归档合入目标):落盘 spec + 立即建任务专属分析工作区(propose 时幂等复用)
|
|
399
409
|
let baseNote = '';
|
|
400
410
|
if (typeof flags.base === 'string') {
|
package/kernel/models.js
CHANGED
|
@@ -79,7 +79,9 @@ export function dispatchSection(kit, workers) {
|
|
|
79
79
|
const lines = [
|
|
80
80
|
'## 派发方式',
|
|
81
81
|
'- 你自己承担 PM 职责:拆解、派发、汇总、向人汇报。',
|
|
82
|
-
'- Worker/subagent 一律用 subagent 工具派发:prompt 自包含(任务背景 + 产出路径 +
|
|
82
|
+
'- Worker/subagent 一律用 subagent 工具派发:prompt 自包含(任务背景 + handoff 路径 + 产出路径 + 读写范围约束;阶段指定 Worker 角色时另需先读角色文件并内嵌定义全文)。',
|
|
83
|
+
'- 派发前更新 `handoff.md` 的「读取清单」;Worker 只读 handoff + 清单中的章节,不整份重读 requirements/design/spec。',
|
|
84
|
+
'- 等待纪律:优先结束当前回合,靠子代理完成通知继续;必须阻塞时只调用一次 `wait_agent`(timeout_ms ≤ 3600000),禁止 5 分钟轮询,禁止用 send_message 问进度。',
|
|
83
85
|
'- Worker 产物写入活目录对应文件;Worker 只能写其 write_scopes 声明的范围。',
|
|
84
86
|
'- 任何时候信息不足或口径模糊:先向人反问,不要自行补全。',
|
|
85
87
|
'',
|
package/package.json
CHANGED
|
@@ -40,6 +40,8 @@ write_scopes: [".harness/deliverables/"]
|
|
|
40
40
|
> bugfix profile 下 BA 不再产出 requirements.md,改为产出单一的 `bugfix.md`(模板 `.harness/deliverables/_template/bugfix.md`),合并覆盖:缺陷描述 + 根因定位 + 影响面 + 验收 GWT + Spec Delta + 就绪自评。此模式跳过 SA,BA 须自行给出根因定位证据(错误日志 / 调用链 / 代码位置),并保证影响面单一(不跨模块)、核心逻辑改动 ≤2 文件(配置/测试/文档等伴随改动不计入)、无新增 API、无数据模型变更——任一超出即 BLOCK 升级为 quick/standard。
|
|
41
41
|
|
|
42
42
|
## 输入(Inputs)
|
|
43
|
+
|
|
44
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
43
45
|
- deliverables/<任务名>/proposal.md # 已打磨的需求提案
|
|
44
46
|
- .harness/specs/_index.md # 能力索引(按需读取相关域 spec 全文)
|
|
45
47
|
- .harness/specs/<相关能力>.md # 受影响的能力详情全文
|
|
@@ -15,6 +15,8 @@ write_scopes: [".harness/deliverables/"]
|
|
|
15
15
|
Agent 契约(本文件)定义审查策略——3 大类审查(框架模式 / 安全健壮性 / 设计一致性)、检查项派生规则、问题分级(Critical/Major/Minor)、问题归属路由、BLOCK 子类型、可复用经验义务。Skill 定义具体操作——code-review Skill 是完整的操作手册(git diff → 从子工程文档派生检查项 → 逐项审查 → 产出报告)。Agent 管"审什么类别、检查项从哪来、怎么判、问题归谁",Skill 管"用什么命令、按什么步骤查"。
|
|
16
16
|
|
|
17
17
|
## 输入(Inputs)
|
|
18
|
+
|
|
19
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
18
20
|
- services/ 下的代码变更(git diff)
|
|
19
21
|
- deliverables/<任务名>/design.md # 对照技术方案
|
|
20
22
|
- deliverables/<任务名>/dev-log.md # 开发日志(含偏离说明、框架耦合降级标注)
|
|
@@ -39,6 +39,8 @@ PM 在首条消息必须告知 `PROFILE=<quick|standard|refactor>`。Dev 按下
|
|
|
39
39
|
不得以 `readiness-report.md` 缺失为由 BLOCK——quick 档此文件按约定不存在。若 PM 未写 PROFILE,默认按 standard,读不到 readiness-report.md 时回退读 design.md 的 `## 就绪自评`,两者都缺才 BLOCK。
|
|
40
40
|
|
|
41
41
|
## 输入(Inputs)
|
|
42
|
+
|
|
43
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
42
44
|
- deliverables/<任务名>/requirements.md # GWT 场景
|
|
43
45
|
- deliverables/<任务名>/design.md # 技术方案(含 W-xx Tasks)
|
|
44
46
|
- deliverables/<任务名>/readiness-report.md # 就绪评审(standard/refactor)
|
|
@@ -73,6 +73,7 @@ LOG_FILE=<仓库根绝对路径>/.harness/.logs/<TASK_NAME>/worker-<role>.log
|
|
|
73
73
|
你的角色定义由 Harness Kit 内核提供(business-analyst),请按其中规定的输入/产出/约束执行。
|
|
74
74
|
|
|
75
75
|
必读:
|
|
76
|
+
- .harness/deliverables/<TASK_NAME>/handoff.md(存在时;只按其中「读取清单」取章节)
|
|
76
77
|
- .harness/deliverables/<TASK_NAME>/proposal.md
|
|
77
78
|
- .harness/specs/_index.md(扫描后按需读相关域 spec 全文)
|
|
78
79
|
- .harness/codebase-guide/overview.md
|
|
@@ -104,11 +105,29 @@ LOG_FILE=<仓库根绝对路径>/.harness/.logs/<TASK_NAME>/worker-<role>.log
|
|
|
104
105
|
> Worker 会去做无界全量重扫并**卡死被看门狗终止**(实测 CR 首轮 stall 600s 无产出)。
|
|
105
106
|
> 下发时须写明:禁止全量重扫、按批次抽样 N 个文件、按阶段写进度日志。
|
|
106
107
|
|
|
108
|
+
## 阶段交接 handoff(控制 Token 的核心)
|
|
109
|
+
|
|
110
|
+
每个任务在 `deliverables/<TASK_NAME>/handoff.md` 维护一份阶段交接摘要,不是需求全文:
|
|
111
|
+
|
|
112
|
+
- 审批 1 前创建/更新:本轮目标、已确认决策、AC、读取清单(文档 + 章节/行号)、未决风险。
|
|
113
|
+
- 每次派发 Worker 前更新「读取清单」;Worker 只读 handoff + 清单中的章节,**不整份重读** requirements/design/spec。
|
|
114
|
+
- Dev 完成后更新「改动文件 / 验证命令 / 已知风险」,CR/TE 以 handoff + 实际 diff 为输入。
|
|
115
|
+
- 归档时 handoff 作为本轮材料一并归档;下一轮重开时先读 handoff,不重讲背景。
|
|
116
|
+
|
|
117
|
+
模板见 `.harness/templates/handoff.md`(`/hk-init` 物化到工作区)。
|
|
118
|
+
|
|
119
|
+
## 子代理等待纪律(2026-11-19 定)
|
|
120
|
+
|
|
121
|
+
- 派发后优先结束当前回合,靠子代理完成通知继续;只有串行依赖必须阻塞时才等待。
|
|
122
|
+
- 必须等待时只调用一次 `wait_agent`,`timeout_ms` 取足够长(≤ 3600000),不要 5 分钟轮询;同一批只等一次。
|
|
123
|
+
- 禁止用 `send_message` 问「进度如何/完成了吗」;完成会自动通知。只有补充信息才发消息。
|
|
124
|
+
- 超时后先做独立工作或向人汇报,不得连续重新 poll;等待期间不重复更新看板。
|
|
125
|
+
|
|
107
126
|
## Propose 与 Apply 调度模式
|
|
108
127
|
|
|
109
128
|
| 阶段 | 模式 | 理由 |
|
|
110
129
|
|------|------|------|
|
|
111
|
-
| Propose (BA/SA/RR) |
|
|
130
|
+
| Propose (BA/SA/RR) | **串行,等待一次** | BA→SA→RR 串行依赖;派发后等一次完成通知,不做 5 分钟轮询 |
|
|
112
131
|
| Apply (Dev/CR/TE) | **异步 + 进度日志**(后台运行) | Dev 可能 10-15 分钟,PM 不应被阻塞;开发者通过日志文件 `tail -f` 跟踪进度 |
|
|
113
132
|
|
|
114
133
|
## Apply 模式(auto / review)
|
|
@@ -32,6 +32,8 @@ standard 档不适用此约束。
|
|
|
32
32
|
RR 是纯评审角色——无对应 Skill。Agent 契约即是完整操作定义。
|
|
33
33
|
|
|
34
34
|
## 输入(Inputs)
|
|
35
|
+
|
|
36
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
35
37
|
- deliverables/<任务名>/requirements.md # BA 产出的需求
|
|
36
38
|
- deliverables/<任务名>/design.md # SA 产出的技术方案
|
|
37
39
|
- deliverables/<任务名>/impact-analysis.md(仅 refactor) # SA 预阶段影响分析
|
|
@@ -11,6 +11,8 @@ write_scopes: [".harness/deliverables/"]
|
|
|
11
11
|
> **硬红线**:Propose 阶段绝对禁止修改任何源码。必须引用 codebase-guide。
|
|
12
12
|
|
|
13
13
|
## 输入(Inputs)
|
|
14
|
+
|
|
15
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
14
16
|
- deliverables/<任务名>/requirements.md # BA 产出的 GWT 需求(必须是 PASS 状态)
|
|
15
17
|
- services/<端>/CLAUDE.md # 各子工程 L1 — 技术栈、框架模式(端 = services/ 下的子工程;不存在时忽略)
|
|
16
18
|
- services/<端>/<模块>/CLAUDE.md(按需) # 受影响模块的职责、框架模式清单(不存在时忽略)
|
|
@@ -15,6 +15,8 @@ write_scopes: [".harness/deliverables/", "e2e/", ".playwright-cli/"]
|
|
|
15
15
|
Agent 契约(本文件)定义测试策略——4 大类覆盖要求、最低用例数、BLOCK 区分规则、可复用经验义务。Skill 定义具体操作——test-e2e Skill(`.harness/skills/test-e2e.md`)是 B 类 Playwright 的完整操作手册(环境准备 → 命令模板 → 截图留存 → 会话管理),build-test / post-verify Skill 是 D 类的构建与事后验证流程。Agent 管"测什么、测多少、怎么判",Skill 管"用什么工具、按什么步骤跑"。
|
|
16
16
|
|
|
17
17
|
## 输入(Inputs)
|
|
18
|
+
|
|
19
|
+
- `deliverables/<任务名>/handoff.md`(存在时先读;只按「读取清单」取章节,不整份重读 requirements/design/spec)
|
|
18
20
|
- deliverables/<任务名>/requirements.md # 提取 R-xxx / S-xxx 作为 B 类用例来源
|
|
19
21
|
- deliverables/<任务名>/design.md # 了解 API 和组件设计
|
|
20
22
|
- deliverables/<任务名>/code-review.md # 必须是 PASS 状态
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Handoff — {{task}}
|
|
2
|
+
|
|
3
|
+
> 阶段交接摘要,不是需求全文。Worker 只读本文件 + 「读取清单」中的章节,不整份重读 requirements / design / spec。
|
|
4
|
+
> 由 PM 在每次派发前更新;归档时随本轮材料保留。
|
|
5
|
+
|
|
6
|
+
## 当前阶段
|
|
7
|
+
|
|
8
|
+
- 阶段:propose / apply
|
|
9
|
+
- Profile:{{profile}}
|
|
10
|
+
- 轮次:R{{round}}
|
|
11
|
+
|
|
12
|
+
## 本轮目标
|
|
13
|
+
|
|
14
|
+
{{desc}}
|
|
15
|
+
|
|
16
|
+
## 已确认决策
|
|
17
|
+
|
|
18
|
+
- D-01 —
|
|
19
|
+
|
|
20
|
+
## 验收标准
|
|
21
|
+
|
|
22
|
+
- AC-01 —
|
|
23
|
+
|
|
24
|
+
## 读取清单
|
|
25
|
+
|
|
26
|
+
| 文档 | 章节/行 | 谁需要 | 用途 |
|
|
27
|
+
|---|---|---|---|
|
|
28
|
+
| requirements.md | | BA/SA/RR | |
|
|
29
|
+
| design.md | | Dev/CR/TE | |
|
|
30
|
+
|
|
31
|
+
## 改动范围
|
|
32
|
+
|
|
33
|
+
- 仓/目录:
|
|
34
|
+
- 预计涉及文件:
|
|
35
|
+
|
|
36
|
+
## 验证命令
|
|
37
|
+
|
|
38
|
+
- 编译:
|
|
39
|
+
- 测试:
|
|
40
|
+
|
|
41
|
+
## 未决问题 / 风险
|
|
42
|
+
|
|
43
|
+
-
|
|
44
|
+
|
|
45
|
+
## 更新记录
|
|
46
|
+
|
|
47
|
+
| 时间 | 阶段 | 更新人 | 说明 |
|
|
48
|
+
|---|---|---|---|
|
|
@@ -82,3 +82,22 @@ Bootstrap 阶段 PM 调度阶段
|
|
|
82
82
|
- **禁止自证循环**:自检断言的判据不得取自被检对象自身的产出,必须来自独立源(改动前基线、独立扫描器等)。
|
|
83
83
|
- **「不可复现」必须量化**:给结构性论证 + 已尝试手段清单 + 可观测半边的独立闭环证据,且仍不得计 PASS,须交人工裁决。
|
|
84
84
|
- **敏感字面量纪律**:凭据/密钥/令牌禁止写进任何说明性制品(报告、日志、提交信息),用脱敏 token 指代、只在结论中给计数;发现即上报 PM 直接脱敏。
|
|
85
|
+
|
|
86
|
+
## 9. 子代理等待纪律(2026-11-19 定,针对轮询浪费)
|
|
87
|
+
|
|
88
|
+
- **优先不等待**:派发子代理后结束当前回合,靠子代理完成通知继续;只有必须串行依赖时才阻塞等待。
|
|
89
|
+
- **必须等待时只等一次**:`wait_agent` 的 `timeout_ms` 用足够长的值(不超过 3600000),不要用 5 分钟短超时反复轮询。同一批子代理只等一次。
|
|
90
|
+
- **禁止进度盘问**:不要用 `send_message` 问「进度如何/完成了吗」;子代理完成会自动通知。只有需要补充信息时才发消息。
|
|
91
|
+
- **超时后的动作**:先做不依赖该子代理的独立工作,或向人汇报当前状态;不得连续重新 poll。
|
|
92
|
+
- **等待期间不更新看板/不重复派发**:看板和心跳只在阶段边界或子代理真正返回后更新。
|
|
93
|
+
|
|
94
|
+
> 实测(2026-11-19 三个大任务):`wait_agent` 29–39 次全部超时,父会话 11%–18% 的 Token 花在超时轮询上,墙钟时间被拉长数小时。
|
|
95
|
+
|
|
96
|
+
## 10. 上下文读取纪律(2026-11-19 定,控制 Token)
|
|
97
|
+
|
|
98
|
+
- **先读 handoff**:任务目录存在 `handoff.md` 时,先读它;只按其中「读取清单」取章节,**不整份重读** requirements / design / spec。
|
|
99
|
+
- **大文件先定位**:超过约 300 行的文件,先用 `grep` 找符号/标题,再用 `read` 的 `offset`/`limit` 读目标段;禁止无差别整文件读取。
|
|
100
|
+
- **同一文件同一轮只读一次**:修改后用 `git diff` 或局部读取验证,不重新通读全文。
|
|
101
|
+
- **工具输出只留结论**:测试/构建日志用 `tail`/`grep` 取失败摘要;不要把整段日志或整份报告贴回上下文。
|
|
102
|
+
- **交接摘要代替全文转发**:PM 在 `handoff.md` 中写本轮决策、AC、读取清单和风险;Worker 不通过复制上游全文来获得上下文。
|
|
103
|
+
- **子代理输入自包含但不冗长**:派发消息给任务背景、产出路径、读写范围、handoff 路径和必要章节,不内嵌整份上游文档。
|