dsh-harness-kit 0.1.2 → 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 +37 -1
- package/kernel/models.js +3 -1
- package/kernel/panel.js +14 -2
- package/kernel/worktree.js +140 -32
- 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.2
|
|
|
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
|
@@ -13,7 +13,7 @@ import { activeTasks, taskIsPlanning } from './state.js';
|
|
|
13
13
|
import { assetsLayout, syncAssets } from './sync.js';
|
|
14
14
|
import { claimTask } from './panel.js';
|
|
15
15
|
import { clearAdvanceMarks } from './advance.js';
|
|
16
|
-
import { ensureTaskWorkspaces, releaseTaskWorkspaces, clearTaskWorkspaces, renderWorkspaceNotice, ensureBaselineMirrors, renderAnalysisNotice, ensureTaskAnalysisWorktrees, removeTaskAnalysisWorktrees, parseBaseSpec, describeMainWorktree, recordDecision, clearDecision, readWorkspaces, mergeTaskBranches } from './worktree.js';
|
|
16
|
+
import { ensureTaskWorkspaces, releaseTaskWorkspaces, clearTaskWorkspaces, renderWorkspaceNotice, ensureBaselineMirrors, renderAnalysisNotice, ensureTaskAnalysisWorktrees, removeTaskAnalysisWorktrees, parseBaseSpec, describeMainWorktree, recordDecision, clearDecision, readWorkspaces, mergeTaskBranches, reconcileArchivedWorktrees } from './worktree.js';
|
|
17
17
|
import { acquireTestEnv, releaseTestEnv, describeTestEnv } from './te.js';
|
|
18
18
|
import { recordTaskSession } from './bindings.js';
|
|
19
19
|
import { addSource, runInit, formatInitReport, guessRole, boardTemplate } from './setup.js';
|
|
@@ -32,6 +32,11 @@ function bindCurrentSession(ws, task, agent) {
|
|
|
32
32
|
try { recordTaskSession(ws, task, sid); } catch { /* 绑定失败不阻断命令 */ }
|
|
33
33
|
}
|
|
34
34
|
|
|
35
|
+
/** 归档台账对账失败不阻断命令;下一次命令/doctor 会再试。 */
|
|
36
|
+
async function reconcileArchivedQuiet(ws, kit) {
|
|
37
|
+
try { return await reconcileArchivedWorktrees(ws, kit); } catch { return null; }
|
|
38
|
+
}
|
|
39
|
+
|
|
35
40
|
function parseArgs(raw) {
|
|
36
41
|
const tokens = raw.trim().split(/\s+/).filter(Boolean);
|
|
37
42
|
const flags = {};
|
|
@@ -248,6 +253,7 @@ async function hkFix({ agent, rawInput }) {
|
|
|
248
253
|
const ws = wsRoot(agent);
|
|
249
254
|
const kit = readKit(ws);
|
|
250
255
|
if (!kit) return err('尚未初始化:请先运行 `/hk-init`。');
|
|
256
|
+
await reconcileArchivedQuiet(ws, kit);
|
|
251
257
|
const { flags, positional } = parseArgs(rawInput);
|
|
252
258
|
// parseArgs 会把 --auto 后首个词吞为旗标值;先还原完整词序再解构
|
|
253
259
|
const words = typeof flags.auto === 'string' ? [flags.auto, ...positional] : positional;
|
|
@@ -341,6 +347,7 @@ async function hkNew({ agent, rawInput }) {
|
|
|
341
347
|
const ws = wsRoot(agent);
|
|
342
348
|
const kit = readKit(ws);
|
|
343
349
|
if (!kit) return err('尚未初始化:请先运行 `/hk-init`。');
|
|
350
|
+
await reconcileArchivedQuiet(ws, kit);
|
|
344
351
|
const { flags, positional } = parseArgs(rawInput);
|
|
345
352
|
// parseArgs 会把 --auto 后首个词吞为旗标值;先还原完整词序再解构
|
|
346
353
|
const words = typeof flags.auto === 'string' ? [flags.auto, ...positional] : positional;
|
|
@@ -388,6 +395,16 @@ async function hkNew({ agent, rawInput }) {
|
|
|
388
395
|
.replaceAll('{{source}}', reqFile === '(无)' ? '描述' : '描述+文件')
|
|
389
396
|
.replaceAll('{{file}}', reqFile);
|
|
390
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
|
+
}
|
|
391
408
|
// --base 开发基线(同时是分析基点与归档合入目标):落盘 spec + 立即建任务专属分析工作区(propose 时幂等复用)
|
|
392
409
|
let baseNote = '';
|
|
393
410
|
if (typeof flags.base === 'string') {
|
|
@@ -494,6 +511,7 @@ async function hkApply({ agent, rawInput }) {
|
|
|
494
511
|
const ws = wsRoot(agent);
|
|
495
512
|
const kit = readKit(ws);
|
|
496
513
|
if (!kit) return err('尚未初始化:请先运行 `/hk-init`。');
|
|
514
|
+
await reconcileArchivedQuiet(ws, kit);
|
|
497
515
|
const { flags, positional } = parseArgs(rawInput);
|
|
498
516
|
const inferred = inferTask(ws, positional, '用法:/hk-apply [任务名] [反馈] [--slot](省略任务名时要求唯一活跃任务;--slot=主树有未处理改动时强制隔离到 slot 开发)');
|
|
499
517
|
if (inferred.error) return err(inferred.error);
|
|
@@ -588,6 +606,9 @@ async function hkArchive({ agent, rawInput }) {
|
|
|
588
606
|
const mergeOverrides = mergeAsked && typeof flags.merge === 'string' ? parseBaseSpec(flags.merge) : {};
|
|
589
607
|
|
|
590
608
|
const taskDir = path.join(harnessDir(ws), 'deliverables', task);
|
|
609
|
+
// 活跃任务归档前先清理其他已归档残留;残留收尾(taskDir 不存在)不能先清理,
|
|
610
|
+
// 否则 releaseTaskWorkspaces 的 ledger 入口会被提前删掉。
|
|
611
|
+
if (fs.existsSync(taskDir)) await reconcileArchivedQuiet(ws, kit);
|
|
591
612
|
if (!fs.existsSync(taskDir)) {
|
|
592
613
|
// 已归档任务的残留收尾(2026-11-17 新增):文档已归档但工作区 slot 因分支未合入而保留
|
|
593
614
|
// (stale-unmerged),注意力条提示「远端 MR 合入后重跑 /hk-archive 释放槽位」——
|
|
@@ -803,6 +824,7 @@ async function hkSync({ agent }) {
|
|
|
803
824
|
const ws = wsRoot(agent);
|
|
804
825
|
const kit = readKit(ws);
|
|
805
826
|
if (!kit) return err('尚未初始化:请先运行 `/hk-init`。');
|
|
827
|
+
await reconcileArchivedQuiet(ws, kit);
|
|
806
828
|
return syncAssets(ws, kit);
|
|
807
829
|
}
|
|
808
830
|
|
|
@@ -818,6 +840,20 @@ async function hkDoctor({ agent }) {
|
|
|
818
840
|
lines.push('- kit.json:❌ 不存在 → 运行 `/hk-init`');
|
|
819
841
|
return ok(lines.join('\n'));
|
|
820
842
|
}
|
|
843
|
+
const reconcile = await reconcileArchivedQuiet(ws, kit);
|
|
844
|
+
if (reconcile) {
|
|
845
|
+
const released = reconcile.released.length;
|
|
846
|
+
const stale = reconcile.stale.length;
|
|
847
|
+
lines.push(
|
|
848
|
+
`- 归档工作区台账:${
|
|
849
|
+
released === 0 && stale === 0
|
|
850
|
+
? '✅ 无残留'
|
|
851
|
+
: `${released > 0 ? `已释放 ${released} 项` : ''}${released > 0 && stale > 0 ? ',' : ''}${stale > 0 ? `保留 ${stale} 项待合入` : ''}`
|
|
852
|
+
}${reconcile.tasks.length > 0 ? `(任务:${reconcile.tasks.map((t) => `\`${t}\``).join('、')})` : ''}`,
|
|
853
|
+
);
|
|
854
|
+
} else {
|
|
855
|
+
lines.push('- 归档工作区台账:⚠️ 对账失败(下一次命令或重跑 /hk-doctor 再试)');
|
|
856
|
+
}
|
|
821
857
|
lines.push(`- kit.json:✅(pack: ${kit.pack ?? 'ai-coding'},sources: ${kit.sources.length} 个)`);
|
|
822
858
|
for (const s of kit.sources) {
|
|
823
859
|
lines.push(` - ${s.name} → \`${s.path}\` ${fs.existsSync(path.join(ws, s.path)) ? '✅' : '❌ 路径缺失'}`);
|
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/kernel/panel.js
CHANGED
|
@@ -225,7 +225,7 @@ export function initGaps(ws, kit) {
|
|
|
225
225
|
* 「需要你」注意力项(M4b):审批/待归档/同步阻塞·落后/初始化缺口。
|
|
226
226
|
* 返回 [{level: block|warn, kind, task?, text, line?, jump?}],block 在前。
|
|
227
227
|
*/
|
|
228
|
-
export function attentionItems(tasks, sync, gaps = [], staleSlots = [], teEnv = null, decisions = {}) {
|
|
228
|
+
export function attentionItems(tasks, sync, gaps = [], staleSlots = [], teEnv = null, decisions = {}, archivedLedger = []) {
|
|
229
229
|
const items = [];
|
|
230
230
|
for (const t of tasks) {
|
|
231
231
|
if (t.status === 'DONE') continue;
|
|
@@ -248,6 +248,14 @@ export function attentionItems(tasks, sync, gaps = [], staleSlots = [], teEnv =
|
|
|
248
248
|
items.push({ level: 'warn', kind: 'archive', task: t.task, text: `${t.task} · 已完成待归档`, line: `/hk-archive ${t.task}` });
|
|
249
249
|
}
|
|
250
250
|
}
|
|
251
|
+
for (const a of archivedLedger) {
|
|
252
|
+
const reps = a.repos?.length ? a.repos.join('、') : '无仓记录';
|
|
253
|
+
items.push({
|
|
254
|
+
level: 'warn', kind: 'worktree-archived', task: a.task,
|
|
255
|
+
text: `${a.task} · 已归档,但工作区台账仍绑定(${reps});点处理或运行 /hk-archive ${a.task} 释放`,
|
|
256
|
+
line: `/hk-archive ${a.task}`,
|
|
257
|
+
});
|
|
258
|
+
}
|
|
251
259
|
for (const t of tasks) {
|
|
252
260
|
if (t.status !== 'DONE' && t.progress?.outOfOrder) {
|
|
253
261
|
items.push({ level: 'warn', kind: 'chain-out-of-order', task: t.task, text: `${t.task} · 看板链越序:当前阶段之前还有未完成阶段(应补 ✅ 或 —)`, jump: true });
|
|
@@ -376,6 +384,10 @@ export function workspaceState(ws, { sync = null } = {}) {
|
|
|
376
384
|
const slots = Object.fromEntries(Object.entries(ledger.slots).map(([repo, m]) => [repo,
|
|
377
385
|
Object.entries(m).map(([slot, b]) => ({ slot, task: b.task, branch: b.branch, state: b.state ?? 'bound' }))]));
|
|
378
386
|
const staleSlots = Object.entries(slots).flatMap(([repo, arr]) => arr.filter((s) => s.state === 'stale-unmerged').map((s) => ({ repo, ...s })));
|
|
387
|
+
// 已归档任务仍占着主工作树台账(典型:归档后才合入并切分支;没有后续归档触发释放)
|
|
388
|
+
const archivedLedger = Object.entries(ledger.tasks ?? {})
|
|
389
|
+
.filter(([task]) => !fs.existsSync(path.join(harnessDir(ws), 'deliverables', task)))
|
|
390
|
+
.map(([task, entry]) => ({ task, repos: Object.keys(entry?.repos ?? {}) }));
|
|
379
391
|
return {
|
|
380
392
|
path: ws,
|
|
381
393
|
board,
|
|
@@ -385,7 +397,7 @@ export function workspaceState(ws, { sync = null } = {}) {
|
|
|
385
397
|
slots,
|
|
386
398
|
te: ledgerTe,
|
|
387
399
|
attention: (() => {
|
|
388
|
-
const items = attentionItems(tasks, sync, initGaps(ws, kit), staleSlots, ledgerTe, readDecisions(ws));
|
|
400
|
+
const items = attentionItems(tasks, sync, initGaps(ws, kit), staleSlots, ledgerTe, readDecisions(ws), archivedLedger);
|
|
389
401
|
// 初始化失败 → block 级常驻提示(页面重开仍可见;成功后自动消失)
|
|
390
402
|
const initJob = initProgress.get(ws);
|
|
391
403
|
if (initJob?.done && initJob.error) {
|
package/kernel/worktree.js
CHANGED
|
@@ -148,7 +148,49 @@ async function isDirty(dir) {
|
|
|
148
148
|
/** 本地合入判定。 */
|
|
149
149
|
async function mergedLocally(repoDir, branch, base) {
|
|
150
150
|
const r = await runGit(['branch', '--merged', base, '--list', branch], { cwd: repoDir });
|
|
151
|
-
|
|
151
|
+
if (r.code !== 0) return false;
|
|
152
|
+
return r.stdout
|
|
153
|
+
.split('\n')
|
|
154
|
+
.map((line) => line.replace(/^[*+ ]+/, '').trim())
|
|
155
|
+
.filter(Boolean)
|
|
156
|
+
.includes(branch);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** 本地分支是否存在(不 fetch)。 */
|
|
160
|
+
async function localBranchExists(repoDir, branch) {
|
|
161
|
+
return (await runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: repoDir })).code === 0;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** 任意 ref 是否存在(本地分支或 origin/<branch>)。 */
|
|
165
|
+
async function refExists(repoDir, ref) {
|
|
166
|
+
return (await runGit(['rev-parse', '--verify', '--quiet', ref], { cwd: repoDir })).code === 0;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** 归档对账的候选基线:任务创建时基线、当前注册基线、当前分支和常见主线。 */
|
|
170
|
+
function candidateBases(info, source, current) {
|
|
171
|
+
const seen = new Set();
|
|
172
|
+
for (const base of [info?.base, source?.branch, current, 'dev', 'test', 'main', 'master']) {
|
|
173
|
+
if (typeof base === 'string' && base.trim() && base !== 'HEAD') seen.add(base.trim());
|
|
174
|
+
}
|
|
175
|
+
return [...seen];
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* 任务分支是否已合入任一候选基线。先查本地(快),再对真正可能是远端的
|
|
180
|
+
* 基线做一次 fetch 复查(合入常发生在 GitLab MR,本地主线可能滞后)。
|
|
181
|
+
* 返回命中的基线名,未合入返回 null。
|
|
182
|
+
*/
|
|
183
|
+
async function mergedIntoAny(repoDir, branch, bases) {
|
|
184
|
+
for (const base of bases) {
|
|
185
|
+
if (await mergedLocally(repoDir, branch, base)) return base;
|
|
186
|
+
}
|
|
187
|
+
// 本地主线可能滞后:一次 fetch 后复查 origin/<base>,避免每个候选基线各 fetch 一次。
|
|
188
|
+
await runGit(['fetch', 'origin'], { cwd: repoDir, timeoutMs: 30_000 });
|
|
189
|
+
for (const base of bases) {
|
|
190
|
+
const target = base.startsWith('origin/') ? base : `origin/${base}`;
|
|
191
|
+
if (await refExists(repoDir, target) && await mergedLocally(repoDir, branch, target)) return base;
|
|
192
|
+
}
|
|
193
|
+
return null;
|
|
152
194
|
}
|
|
153
195
|
|
|
154
196
|
/**
|
|
@@ -586,48 +628,68 @@ export async function ensureTaskWorkspaces(ws, kit, task, { branchPrefix = 'feat
|
|
|
586
628
|
}
|
|
587
629
|
|
|
588
630
|
/**
|
|
589
|
-
*
|
|
590
|
-
*
|
|
631
|
+
* 释放一个任务台账条目(不写盘,由调用方统一写)。
|
|
632
|
+
* 关键:主工作树不在任务分支时,也要检查任务分支是否已合入候选基线——
|
|
633
|
+
* 人合并后切到 dev/test 是常态,不能因此把台账永久留在“占用”状态。
|
|
591
634
|
*/
|
|
592
|
-
|
|
593
|
-
const out = { released: [], stale: []
|
|
594
|
-
const ledger = readWorkspaces(ws);
|
|
595
|
-
const entry = ledger.tasks[task];
|
|
596
|
-
if (!entry) { out.missing = true; return out; }
|
|
635
|
+
async function releaseEntry(ws, kit, task, entry, ledger) {
|
|
636
|
+
const out = { released: [], stale: [] };
|
|
597
637
|
const remaining = {};
|
|
598
638
|
for (const [name, info] of Object.entries(entry.repos ?? {})) {
|
|
599
639
|
const source = (kit?.sources ?? []).find((s) => s.name === name);
|
|
600
640
|
const repoDir = source ? path.join(ws, source.path) : null;
|
|
601
641
|
if (info.placement === 'main') {
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
642
|
+
if (!info.branch) {
|
|
643
|
+
out.released.push({ source: name, placement: 'main', note: '无 git 分支记录,释放台账' });
|
|
644
|
+
continue;
|
|
645
|
+
}
|
|
646
|
+
if (!repoDir || !fs.existsSync(repoDir) || !(await isGitRepo(repoDir))) {
|
|
647
|
+
out.released.push({ source: name, placement: 'main', note: '仓不可用,释放台账' });
|
|
648
|
+
continue;
|
|
649
|
+
}
|
|
650
|
+
const cur = await currentBranch(repoDir);
|
|
651
|
+
if (!(await localBranchExists(repoDir, info.branch))) {
|
|
652
|
+
out.released.push({ source: name, placement: 'main', note: `任务分支 ${info.branch} 已不存在,释放台账` });
|
|
653
|
+
continue;
|
|
654
|
+
}
|
|
655
|
+
const bases = candidateBases(info, source, cur).filter((b) => b !== info.branch);
|
|
656
|
+
const mergedBase = await mergedIntoAny(repoDir, info.branch, bases);
|
|
657
|
+
if (!mergedBase) {
|
|
658
|
+
out.stale.push({
|
|
659
|
+
source: name,
|
|
660
|
+
reason: cur === info.branch
|
|
661
|
+
? `分支 ${info.branch} 未合入 ${info.base ?? '候选基线'}:主工作树保持占用(保护性),人确认合入后重跑 /hk-archive 释放`
|
|
662
|
+
: `主工作树当前在 ${cur || '(detached)'},任务分支 ${info.branch} 未合入候选基线:台账保留,合入后重跑 /hk-archive 释放`,
|
|
663
|
+
});
|
|
664
|
+
remaining[name] = info;
|
|
665
|
+
continue;
|
|
666
|
+
}
|
|
667
|
+
if (cur === info.branch) {
|
|
668
|
+
if (await isDirty(repoDir)) {
|
|
669
|
+
out.stale.push({ source: name, reason: `主工作树分支 ${info.branch} 已合入但有未提交改动,未切回基线(请人工处理)` });
|
|
670
|
+
remaining[name] = info;
|
|
625
671
|
continue;
|
|
626
672
|
}
|
|
673
|
+
const co = await checkoutBaseBranch(repoDir, mergedBase);
|
|
674
|
+
if (co.code !== 0) {
|
|
675
|
+
out.stale.push({ source: name, reason: `主工作树切回基线失败:${(co.stderr || '').trim().split('\n')[0]}` });
|
|
676
|
+
remaining[name] = info;
|
|
677
|
+
continue;
|
|
678
|
+
}
|
|
679
|
+
await runGit(['branch', '-d', info.branch], { cwd: repoDir });
|
|
680
|
+
out.released.push({ source: name, placement: 'main', note: `主工作树已切回 ${mergedBase} 并删已合入分支` });
|
|
681
|
+
} else {
|
|
682
|
+
// 当前在别的分支:只释放台账,不改用户当前分支,也不删分支——
|
|
683
|
+
// 分支清理交给人在确认后处理,避免自动对账产生额外副作用。
|
|
684
|
+
out.released.push({
|
|
685
|
+
source: name,
|
|
686
|
+
placement: 'main',
|
|
687
|
+
note: `主工作树当前在 ${cur || '(detached)'};任务分支已合入 ${mergedBase},仅释放台账`,
|
|
688
|
+
});
|
|
627
689
|
}
|
|
628
|
-
out.released.push({ source: name, placement: 'main', note: '主工作树(无内核动作)' });
|
|
629
690
|
continue;
|
|
630
691
|
}
|
|
692
|
+
|
|
631
693
|
const dir = path.join(worktreeRoot(ws, name), info.placement);
|
|
632
694
|
ledger.slots[name] ??= {};
|
|
633
695
|
if (!repoDir || !fs.existsSync(repoDir) || !(await isGitRepo(repoDir))) {
|
|
@@ -647,9 +709,55 @@ export async function releaseTaskWorkspaces(ws, kit, task) {
|
|
|
647
709
|
remaining[name] = info;
|
|
648
710
|
}
|
|
649
711
|
}
|
|
712
|
+
return { ...out, remaining };
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/**
|
|
716
|
+
* 归档释放:main 不在任务分支时也检查合入;slot 已合入 → 切回基线释放;
|
|
717
|
+
* 未合入 → stale 标记保留。返回 { released, stale: [{source, reason}], missing }。
|
|
718
|
+
*/
|
|
719
|
+
export async function releaseTaskWorkspaces(ws, kit, task) {
|
|
720
|
+
const ledger = readWorkspaces(ws);
|
|
721
|
+
const entry = ledger.tasks[task];
|
|
722
|
+
if (!entry) return { released: [], stale: [], missing: true };
|
|
723
|
+
const { released, stale, remaining } = await releaseEntry(ws, kit, task, entry, ledger);
|
|
650
724
|
if (Object.keys(remaining).length === 0) delete ledger.tasks[task];
|
|
651
725
|
else ledger.tasks[task] = { ...entry, repos: remaining };
|
|
652
726
|
writeWorkspaces(ws, ledger);
|
|
727
|
+
return { released, stale, missing: false };
|
|
728
|
+
}
|
|
729
|
+
|
|
730
|
+
/**
|
|
731
|
+
* 已归档任务的工作区台账对账(幂等,可反复执行)。
|
|
732
|
+
*
|
|
733
|
+
* 台账是缓存、git 是事实源:任务文档已进入 `_archive` 且活目录不存在时,
|
|
734
|
+
* 若任务分支已合入(本地或 origin)或分支已删除,就释放台账;未合入则保留
|
|
735
|
+
* 并标记 stale,等下一次命令/归档再对账。这样合并在归档之后发生也不会留下
|
|
736
|
+
* 永久占用。
|
|
737
|
+
*
|
|
738
|
+
* 返回 { tasks, released, stale }。只改本机 worktrees.json:不合并代码、不推送;
|
|
739
|
+
* 当前不在任务分支时不切换分支、不删分支;任务分支被检出时按既有释放逻辑切回基线。
|
|
740
|
+
*/
|
|
741
|
+
export async function reconcileArchivedWorktrees(ws, kit) {
|
|
742
|
+
const ledger = readWorkspaces(ws);
|
|
743
|
+
const deliverables = path.join(harnessDir(ws), 'deliverables');
|
|
744
|
+
const archiveRoot = path.join(deliverables, '_archive');
|
|
745
|
+
const out = { tasks: [], released: [], stale: [] };
|
|
746
|
+
let changed = false;
|
|
747
|
+
for (const [task, entry] of Object.entries(ledger.tasks ?? {})) {
|
|
748
|
+
// 活目录还在:任务可能已重开,不能按“已归档”清理。
|
|
749
|
+
if (fs.existsSync(path.join(deliverables, task))) continue;
|
|
750
|
+
// 没有归档记录:可能是手工删除,保留台账让人判断,不静默清理。
|
|
751
|
+
if (!fs.existsSync(path.join(archiveRoot, task))) continue;
|
|
752
|
+
const r = await releaseEntry(ws, kit, task, entry, ledger);
|
|
753
|
+
out.tasks.push(task);
|
|
754
|
+
out.released.push(...r.released.map((x) => ({ ...x, task })));
|
|
755
|
+
out.stale.push(...r.stale.map((x) => ({ ...x, task })));
|
|
756
|
+
if (Object.keys(r.remaining).length === 0) delete ledger.tasks[task];
|
|
757
|
+
else ledger.tasks[task] = { ...entry, repos: r.remaining };
|
|
758
|
+
changed = true;
|
|
759
|
+
}
|
|
760
|
+
if (changed) writeWorkspaces(ws, ledger);
|
|
653
761
|
return out;
|
|
654
762
|
}
|
|
655
763
|
|
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 路径和必要章节,不内嵌整份上游文档。
|