dsh-harness-kit 0.1.6 → 0.2.0

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.
Files changed (31) hide show
  1. package/README.md +27 -13
  2. package/README.zh-CN.md +26 -16
  3. package/client.js +108 -11
  4. package/docs/DETAIL.en.md +29 -9
  5. package/docs/DETAIL.md +14 -4
  6. package/kernel/advance.js +3 -3
  7. package/kernel/bindings.js +11 -6
  8. package/kernel/commands.js +150 -23
  9. package/kernel/local-files.js +5 -5
  10. package/kernel/metrics.js +280 -0
  11. package/kernel/panel.js +140 -6
  12. package/kernel/paths.js +62 -1
  13. package/kernel/setup.js +5 -4
  14. package/kernel/te.js +4 -4
  15. package/kernel/worktree.js +162 -20
  16. package/package.json +1 -1
  17. package/packs/ai-coding/assets/scripts/codebase_guide_init.py +1 -1
  18. package/packs/ai-coding/assets/scripts/harness_init.py +15 -6
  19. package/packs/ai-coding/assets/scripts/te_lease.py +6 -1
  20. package/packs/ai-coding/assets/scripts/update_board.py +30 -0
  21. package/packs/ai-coding/flows/init.yml +2 -2
  22. /package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{app-CLAUDE.tmpl → app-AGENTS.tmpl} +0 -0
  23. /package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{module-CLAUDE.tmpl → module-AGENTS.tmpl} +0 -0
  24. /package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
  25. /package/packs/ai-coding/assets/templates/java/maven/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
  26. /package/packs/ai-coding/assets/templates/java/maven-multimodule/{module-CLAUDE.tmpl → module-AGENTS.tmpl} +0 -0
  27. /package/packs/ai-coding/assets/templates/java/maven-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
  28. /package/packs/ai-coding/assets/templates/javascript/mobile-app/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
  29. /package/packs/ai-coding/assets/templates/javascript/uniapp/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
  30. /package/packs/ai-coding/assets/templates/javascript/vue-multimodule/{app-CLAUDE.tmpl → app-AGENTS.tmpl} +0 -0
  31. /package/packs/ai-coding/assets/templates/javascript/vue-multimodule/{root-CLAUDE.tmpl → root-AGENTS.tmpl} +0 -0
@@ -19,6 +19,7 @@ import { discoverAll, discoverSource, readLocalFiles, writeLocalFiles, provision
19
19
  import { recordTaskSession } from './bindings.js';
20
20
  import { addSource, runInit, formatInitReport, guessRole, boardTemplate } from './setup.js';
21
21
  import { dispatchSection, describeWorkerModel } from './models.js';
22
+ import { collectTaskMetrics, writeTaskMetrics } from './metrics.js';
22
23
 
23
24
  const ok = (text) => ({ kind: 'success', text });
24
25
  const err = (text) => ({ kind: 'error', text });
@@ -594,21 +595,25 @@ async function hkApply({ agent, rawInput }) {
594
595
  }
595
596
 
596
597
  // --------------------------------------------------------------- /hk-archive
597
- async function hkArchive({ agent, rawInput }) {
598
+ async function hkArchive({ agent, rawInput, ctx }) {
598
599
  const ws = wsRoot(agent);
599
600
  const kit = readKit(ws);
600
601
  if (!kit) return err('尚未初始化:请先运行 `/hk-init`。');
601
602
  const { flags, positional } = parseArgs(rawInput);
602
603
  const task = positional[0];
603
- if (!task) return err('用法:/hk-archive <任务名> [--merge [仓:分支,…]]');
604
+ if (!task) return err('用法:/hk-archive <任务名> [--merge [仓:分支,…]] [--no-merge] [--dry-run]');
604
605
  // 合入确认(B 方案,2026-11-17):--merge = 人显式确认要把任务分支本地合入目标基线;
605
606
  // 可带 repo:branch 覆盖目标(不带则用任务创建时指定的基线)。合并只做本地提交,不推送。
606
607
  const mergeAsked = flags.merge !== undefined;
608
+ const noMerge = flags['no-merge'] === true;
609
+ const dryRun = flags['dry-run'] === true;
610
+ if (mergeAsked && noMerge) return err('`--merge` 与 `--no-merge` 不能同时使用。');
607
611
  const mergeOverrides = mergeAsked && typeof flags.merge === 'string' ? parseBaseSpec(flags.merge) : {};
608
- // 可选自动化:分支都能干净本地合入时,归档自动合入并释放 slot;冲突/目标异常仍停下转人工。
609
- // 只做本地合并,不推送;默认关闭,项目在 kit.json 显式开启。
610
- const autoMergeClean = kit.worktree?.autoMergeClean === true;
611
- const shouldMerge = mergeAsked || autoMergeClean;
612
+ // 0.2.0:autoClose 取代 autoMergeClean(旧键兼容);只做本地合并,不推送。
613
+ const autoClose = kit.worktree?.autoClose === true || kit.worktree?.autoMergeClean === true;
614
+ const targetSync = ['off', 'ff-only', 'safe'].includes(kit.worktree?.targetSync) ? kit.worktree.targetSync : 'safe';
615
+ const shouldMerge = !noMerge && (mergeAsked || autoClose);
616
+ const mergeOpts = { syncTarget: targetSync, dryRun };
612
617
 
613
618
  const taskDir = path.join(harnessDir(ws), 'deliverables', task);
614
619
  // 活跃任务归档前先清理其他已归档残留;残留收尾(taskDir 不存在)不能先清理,
@@ -620,7 +625,10 @@ async function hkArchive({ agent, rawInput }) {
620
625
  // 此时活目录已清,正常预检必然失败;这里识别为「只做工作区释放」的收尾模式。
621
626
  const wl = readWorkspaces(ws);
622
627
  if (wl.tasks?.[task]) {
623
- const mg = shouldMerge ? await mergeTaskBranches(ws, kit, task, mergeOverrides) : null;
628
+ const mg = shouldMerge ? await mergeTaskBranches(ws, kit, task, mergeOverrides, mergeOpts) : null;
629
+ if (dryRun) {
630
+ return ok(`/hk-archive ${task} 收尾预演(dry-run,未改动任何 ref):\n${(mg ? mergeLines(mg) : ['(未启用自动收尾)']).join('\n')}`);
631
+ }
624
632
  const rel = await releaseTaskWorkspaces(ws, kit, task);
625
633
  const ta = await removeTaskAnalysisWorktrees(ws, kit, task);
626
634
  clearDecision(ws, task);
@@ -631,10 +639,18 @@ async function hkArchive({ agent, rawInput }) {
631
639
  ...(ta.removed > 0 ? [`任务分析工作区已回收 ×${ta.removed}`] : []),
632
640
  ...ta.notes,
633
641
  ];
642
+ const mgFailed = mg && (mg.conflicts.length > 0 || mg.refused.length > 0);
643
+ if (mgFailed) {
644
+ return err(`任务 **${task}** 已归档,但工作区收尾被阻断:\n${lines.join('\n')}\n\n任务文档已在归档区;修复上述问题后重跑 \`/hk-archive ${task}\`(只做本地合并,推送仍由人执行)。`);
645
+ }
634
646
  if (rel.stale.length > 0) {
635
647
  const targets = [...new Set([...rel.stale.map((x) => x.source)])]
636
648
  .map((src) => `${src}→${(wl.tasks?.[task]?.repos?.[src]?.base) ?? '?'}`).join('、');
637
- return err(`任务 **${task}** 已归档,但工作区仍未释放:\n${lines.join('\n')}\n\n${autoMergeClean && !mergeAsked ? '自动本地合入未成功(冲突或目标异常),解决后运行:' : '确认要本地合入目标基线(' + targets + ')后运行:'}\n\`/hk-archive ${task} --merge\`(可用 \`--merge 仓:分支\` 覆盖目标;只做本地合并,推送仍由人执行)`);
649
+ const hint = noMerge
650
+ ? `已按 \`--no-merge\` 跳过代码收尾;确认合入目标基线(${targets})后重跑不带该旗标:`
651
+ : `确认要本地合入目标基线(${targets})后运行:`;
652
+ const command = noMerge ? `/hk-archive ${task}` : `/hk-archive ${task} --merge`;
653
+ return err(`任务 **${task}** 已归档,但工作区仍未释放:\n${lines.join('\n')}\n\n${hint}\n\`${command}\`(只做本地合并,推送仍由人执行)`);
638
654
  }
639
655
  return ok(`任务 **${task}** 已归档,残留工作区已收尾:\n${lines.join('\n') || '(无残留)'}`);
640
656
  }
@@ -686,6 +702,21 @@ async function hkArchive({ agent, rawInput }) {
686
702
  }
687
703
  }
688
704
 
705
+ // 0.2.0:收尾前置。干净可合入时先同步目标并合入;失败则任务保持活跃、文档不归档,
706
+ // 避免出现「已归档但 slot 还 stale」的中间态。--no-merge 保留旧行为(只归档文档)。
707
+ if (dryRun) {
708
+ const mgPlan = shouldMerge ? await mergeTaskBranches(ws, kit, task, mergeOverrides, mergeOpts) : null;
709
+ const planLines = mgPlan ? mergeLines(mgPlan) : ['(未启用自动收尾,将只归档文档)'];
710
+ return ok(`/hk-archive ${task} 预演(dry-run,未改动任何文件/ref):\n${planLines.join('\n')}\n\n门禁已通过;去掉 --dry-run 即执行。`);
711
+ }
712
+ let mgBefore = null;
713
+ if (shouldMerge) {
714
+ mgBefore = await mergeTaskBranches(ws, kit, task, mergeOverrides, mergeOpts);
715
+ if (mgBefore.conflicts.length > 0 || mgBefore.refused.length > 0) {
716
+ return err(`归档未执行:工作区收尾被阻断,任务 **${task}** 仍保持活跃,文档未归档。\n${mergeLines(mgBefore).join('\n')}\n\n修复后重跑 \`/hk-archive ${task}\`;若只想先归档文档,加 \`--no-merge\`。`);
717
+ }
718
+ }
719
+
689
720
  const archiveDir = path.join(harnessDir(ws), 'deliverables', '_archive', task);
690
721
  fs.mkdirSync(archiveDir, { recursive: true });
691
722
  const date = new Date().toISOString().slice(0, 10);
@@ -700,6 +731,21 @@ async function hkArchive({ agent, rawInput }) {
700
731
  }
701
732
  const tag = `R${round}`;
702
733
 
734
+ // 运行统计快照:与面板 task-insight 共用采集函数;失败不阻塞归档,写 unavailable stub。
735
+ let metricsNote = '';
736
+ try {
737
+ const metrics = await collectTaskMetrics(ws, kit, task, {
738
+ sessionQuery: ctx?.get?.('sessionQuery'),
739
+ tokenMeter: ctx?.get?.('tokenMeter'),
740
+ sessions: ctx?.get?.('sessions'),
741
+ currentSession: agent?.session,
742
+ });
743
+ const written = writeTaskMetrics(ws, task, tag, metrics);
744
+ metricsNote = `\n- 运行统计:\`_archive/${task}/metrics/${tag}.json\`(${metrics.coverage}${written.skipped ? ',已存在' : ''})`;
745
+ } catch (cause) {
746
+ metricsNote = `\n- ⚠️ 运行统计写入失败:${String(cause?.message || cause).replace(/\s+/g, ' ').slice(0, 160)}`;
747
+ }
748
+
703
749
  // append each active doc to its archive counterpart under an R<N> section
704
750
  const appended = [];
705
751
  for (const name of fs.readdirSync(taskDir)) {
@@ -722,22 +768,20 @@ async function hkArchive({ agent, rawInput }) {
722
768
  clearAdvanceMarks(ws, task);
723
769
  bindCurrentSession(ws, task, agent);
724
770
 
725
- // worktree 收尾:slot 已合入基线的 → 切回基线释放(目录保留);未合入 → stale 保留提示
726
- // 合入确认(B 方案):--merge 时先本地合入目标基线,再释放槽位
727
- const mgNormal = shouldMerge ? await mergeTaskBranches(ws, kit, task, mergeOverrides) : null;
771
+ // worktree 收尾:合入已在前置阶段完成;这里只释放槽位/切回基线并删除已合入分支。
728
772
  const wtResult = await releaseTaskWorkspaces(ws, kit, task);
729
773
  clearDecision(ws, task);
730
774
  const taCleanup = await removeTaskAnalysisWorktrees(ws, kit, task);
731
775
  const staleLines = wtResult.stale.map((s) => `⚠️ ${s.source}:${s.reason}`);
732
- const confirmHint = wtResult.stale.length > 0 && !mergeAsked
733
- ? [autoMergeClean
734
- ? `自动本地合入未成功(冲突或目标异常),解决后运行:\`/hk-archive ${task} --merge\`(只本地合并,推送由人执行)`
735
- : `确认要本地合入目标基线后运行:\`/hk-archive ${task} --merge\`(可用 \`--merge 仓:分支\` 覆盖目标;只本地合并,推送由人执行)`]
776
+ const confirmHint = wtResult.stale.length > 0
777
+ ? [noMerge
778
+ ? `已按 \`--no-merge\` 跳过代码收尾;确认合入目标基线后重跑不带该旗标:\`/hk-archive ${task}\``
779
+ : `收尾后仍有槽位未释放;确认合入目标基线后运行:\`/hk-archive ${task} --merge\`(可用 \`--merge 仓:分支\` 覆盖目标;只本地合并,推送由人执行)`]
736
780
  : [];
737
- const wtNote = wtResult.missing && taCleanup.removed === 0 && taCleanup.notes.length === 0 && !mgNormal
781
+ const wtNote = wtResult.missing && taCleanup.removed === 0 && taCleanup.notes.length === 0 && !mgBefore
738
782
  ? ''
739
783
  : [
740
- ...(mgNormal ? mergeLines(mgNormal) : []),
784
+ ...(mgBefore ? mergeLines(mgBefore) : []),
741
785
  ...wtResult.released.map((r) => `${r.placement === 'main' ? '主工作树无需处理' : `slot ${r.placement} 已释放(切回基线,目录保留)`}(${r.source})`),
742
786
  ...staleLines,
743
787
  ...confirmHint,
@@ -786,7 +830,7 @@ async function hkArchive({ agent, rawInput }) {
786
830
  ? `资产随工作区根仓库管理(\`${lay.repoRoot}\`),随根仓库 commit/push 即共享,无需 \`/hk-sync\``
787
831
  : '资产仓库为本地模式;如需团队共享,绑定远端后用 `/hk-sync` 同步';
788
832
  }
789
- return ok(`任务 **${task}** 已归档为 ${tag}:\n- 追加归档:${appended.map((f) => `\`_archive/${task}/${f}\``).join('、') || '(无)'}\n- 轮次摘要追加到 \`_archive/${task}/rounds.md\`\n- 活目录已清空${wtNote ? `\n- ${wtNote}` : ''}\n\n${mergeNote}${syncHint}。`);
833
+ return ok(`任务 **${task}** 已归档为 ${tag}:\n- 追加归档:${appended.map((f) => `\`_archive/${task}/${f}\``).join('、') || '(无)'}\n- 轮次摘要追加到 \`_archive/${task}/rounds.md\`\n- 活目录已清空${wtNote ? `\n- ${wtNote}` : ''}${metricsNote}\n\n${mergeNote}${syncHint}。`);
790
834
  }
791
835
 
792
836
  // ---------------------------------------------------------------- /hk-te
@@ -810,10 +854,17 @@ function hkTe({ agent, rawInput }) {
810
854
  return err('用法:/hk-te [acquire|release <任务名> | status]');
811
855
  }
812
856
 
813
- /** 合入结果的行化输出(--merge 用)。 */
857
+ /** 合入结果的行化输出(--merge / autoClose 用)。 */
814
858
  function mergeLines(mg) {
815
859
  const lines = [];
860
+ for (const s of mg.synced ?? []) {
861
+ lines.push(s.merged
862
+ ? `🔄 ${s.repo} → ${s.target} 已并入 origin/${s.target} ${s.from}..${s.to}(本地合并,未推送)`
863
+ : `🔄 ${s.repo} → ${s.target} 已快进 ${s.from}..${s.to}(origin,未推送)`);
864
+ }
865
+ for (const a of mg.alreadyMerged ?? []) lines.push(`✅ ${a.repo} → ${a.target} 已包含任务分支(跳过重复合并)`);
816
866
  for (const m of mg.merged) lines.push(`✅ ${m.repo} → ${m.target} 已本地合入(commit ${m.commit},未推送)`);
867
+ for (const p of mg.planned ?? []) lines.push(`📝 [dry-run] ${p.repo}:将先快进 ${p.target},再合入 ${p.branch}`);
817
868
  for (const c of mg.conflicts) lines.push(`⛔ ${c.repo} → ${c.target} 合并冲突(已中止回滚):${c.files.slice(0, 8).join('、') || '见 git status'}`);
818
869
  for (const r of mg.refused) lines.push(`⚠️ ${r.repo}:${r.reason}`);
819
870
  return lines;
@@ -825,7 +876,7 @@ const TE_NOTICE = [
825
876
  '- 测试环境(起服务/连 TDengine/jmeter)全局只有一个,TE 阶段按租约串行。',
826
877
  '- 派发 TE Worker **之前**必须先获取租约:',
827
878
  ' - 人可运行 `/hk-te acquire <任务名>`;',
828
- ' - PM/自动流程可直接运行 `python3 .harness/scripts/te_lease.py acquire <任务名>`(与 `/hk-te` 共用同一 `tasks/test-env.json`,不需要人代跑 slash command)。',
879
+ ' - PM/自动流程可直接运行 `python3 .harness/scripts/te_lease.py acquire <任务名>`(与 `/hk-te` 共用同一 `local/test-env.json`,不需要人代跑 slash command)。',
829
880
  ' - 已获授权 → 正常派发;排队中 → **暂停 TE 阶段**,向人汇报「TE 环境被谁占用、本任务已排队」,**不要派发 TE Worker、不要起服务/连测试库**(内核无法抢占运行中的 Worker,门必须在派发前)。',
830
881
  '- 租约只是串行锁,不是人工审批;获取后仍按 TE 门禁执行。',
831
882
  '- TE 完成(看板链 TE 标 ✅)后内核自动释放并通知下一个排队任务,无需手工 release。',
@@ -940,8 +991,9 @@ async function hkLocal({ agent, rawInput }) {
940
991
  }
941
992
 
942
993
  // ---------------------------------------------------------------- /hk-doctor
943
- async function hkDoctor({ agent }) {
994
+ async function hkDoctor({ agent, rawInput }) {
944
995
  const ws = wsRoot(agent);
996
+ const { flags } = parseArgs(rawInput ?? '');
945
997
  const lines = ['## Harness Kit 体检', ''];
946
998
  lines.push(`- 工作区:\`${ws}\``);
947
999
  lines.push(`- 内容包目录:\`${packDir(readKit(ws) ?? undefined)}\` ${fs.existsSync(packDir(readKit(ws) ?? undefined)) ? '✅' : '❌ 缺失'}`);
@@ -951,6 +1003,48 @@ async function hkDoctor({ agent }) {
951
1003
  lines.push('- kit.json:❌ 不存在 → 运行 `/hk-init`');
952
1004
  return ok(lines.join('\n'));
953
1005
  }
1006
+ if (flags.fix === true) {
1007
+ const fixed = [];
1008
+ try {
1009
+ const r = await runInit(ws, {});
1010
+ if (!r.ok) {
1011
+ lines.push(`- 修复:❌ 初始化物化失败:${r.error}`);
1012
+ } else {
1013
+ fixed.push(...r.created.map((x) => `物化 \`${x}\``));
1014
+ for (const w of r.warnings) fixed.push(`⚠️ ${w}`);
1015
+ }
1016
+ } catch (cause) {
1017
+ lines.push(`- 修复:❌ 初始化物化异常:${cause.message}`);
1018
+ }
1019
+ // 看板 7 列修复(唯一写入门禁)
1020
+ const ub = path.join(harnessDir(ws), 'scripts', 'update_board.py');
1021
+ if (fs.existsSync(ub)) {
1022
+ const chk = await run('python3', [ub, '--check'], { cwd: ws, timeoutMs: 15_000 });
1023
+ if (chk.code !== 0) {
1024
+ const rep = await run('python3', [ub, '--repair', '--write'], { cwd: ws, timeoutMs: 30_000 });
1025
+ fixed.push(rep.code === 0 ? '看板已按 7 列契约修复' : `看板修复失败:${(rep.stdout || rep.stderr).trim()}`);
1026
+ }
1027
+ }
1028
+ // 记忆 hot/cold 索引(存在 entries 但索引缺失时重建)
1029
+ const mem = path.join(harnessDir(ws), 'scripts', 'memory_index.py');
1030
+ if (fs.existsSync(mem) && (!fs.existsSync(path.join(harnessDir(ws), 'memory', 'index.md')) || !fs.existsSync(path.join(harnessDir(ws), 'memory', 'cold.md')))) {
1031
+ const sync = await run('python3', [mem, 'sync'], { cwd: ws, timeoutMs: 60_000 });
1032
+ fixed.push(sync.code === 0 ? '记忆 hot/cold 索引已重建' : `记忆索引重建失败:${(sync.stdout || sync.stderr).trim()}`);
1033
+ }
1034
+ // 旧模板命名:只提示,不删可能被项目裁剪过的文件
1035
+ const legacyTemplates = [];
1036
+ const walk = (dir) => {
1037
+ if (!fs.existsSync(dir)) return;
1038
+ for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
1039
+ const abs = path.join(dir, e.name);
1040
+ if (e.isDirectory()) walk(abs);
1041
+ else if (e.name.endsWith('-CLAUDE.tmpl')) legacyTemplates.push(path.relative(ws, abs));
1042
+ }
1043
+ };
1044
+ walk(path.join(harnessDir(ws), 'templates'));
1045
+ if (legacyTemplates.length > 0) fixed.push(`旧模板 ${legacyTemplates.length} 个(可人工删除,插件不覆盖):${legacyTemplates.slice(0, 4).join('、')}${legacyTemplates.length > 4 ? ' 等' : ''}`);
1046
+ lines.push(`- 自动修复:${fixed.length ? fixed.join(';') : '无确定性修复项'}`);
1047
+ }
954
1048
  const reconcile = await reconcileArchivedQuiet(ws, kit);
955
1049
  if (reconcile) {
956
1050
  const released = reconcile.released.length;
@@ -1062,8 +1156,41 @@ async function hkDoctor({ agent }) {
1062
1156
  return ok(lines.join('\n'));
1063
1157
  }
1064
1158
 
1159
+ /**
1160
+ * 统一入口(0.3.0 概念收敛):/hk init|task|close|doctor。
1161
+ * 旧 /hk-* 命令继续作为别名,内部转发到同一 handler。
1162
+ */
1163
+ async function hkUmbrella({ agent, rawInput, ctx }) {
1164
+ const text = String(rawInput ?? '').trim();
1165
+ const [sub, ...restParts] = text.split(/\s+/).filter(Boolean);
1166
+ const rest = restParts.join(' ');
1167
+ if (!sub || sub === 'help' || sub === '-h' || sub === '--help') {
1168
+ return ok([
1169
+ '## /hk 入口',
1170
+ '',
1171
+ '- `/hk init [--assets …]`:初始化 / 修复工作区骨架与资产绑定',
1172
+ '- `/hk task <描述> [--file …]`:立项;加 `--fix` 走快速修复',
1173
+ '- `/hk close <任务> [--merge|--no-merge] [--dry-run]`:归档并收尾',
1174
+ '- `/hk doctor [--fix]`:体检;`--fix` 修复确定性缺件',
1175
+ '',
1176
+ '高级命令仍可用:/hk-setup、/hk-propose、/hk-apply、/hk-archive、/hk-fix、/hk-te、/hk-local、/hk-sync。',
1177
+ ].join('\n'));
1178
+ }
1179
+ if (sub === 'init') return hkInit({ agent, rawInput: rest, ctx });
1180
+ if (sub === 'close') return hkArchive({ agent, rawInput: rest, ctx });
1181
+ if (sub === 'doctor') return hkDoctor({ agent, rawInput: rest, ctx });
1182
+ if (sub === 'task') {
1183
+ const tokens = restParts.filter((t) => t !== '--fix');
1184
+ const line = tokens.join(' ');
1185
+ if (restParts.includes('--fix')) return hkFix({ agent, rawInput: line, ctx });
1186
+ return hkNew({ agent, rawInput: line, ctx });
1187
+ }
1188
+ return err(`未知 /hk 子命令:${sub}。可用:init / task / close / doctor。`);
1189
+ }
1190
+
1065
1191
  export function registerCommands(ctx) {
1066
1192
  const defs = [
1193
+ { name: 'hk', description: 'Harness Kit 统一入口:init / task / close / doctor', hint: '[init|task|close|doctor] …', handler: hkUmbrella },
1067
1194
  { name: 'hk-setup', description: '收集代码仓库并登记 kit.json(--add <url> [--name n] [--path p] [--role r] [--branch b])', hint: '[--add <git-url> …]', handler: hkSetup },
1068
1195
  { name: 'hk-init', description: '初始化 .harness 骨架/资产仓库绑定/脚本模板物化,并编排子工程文档与 CodeGraph 索引生成(幂等)', hint: '[--assets <url|init|local>] [--branch <分支>]', handler: hkInit },
1069
1196
  { name: 'hk-fix', description: '启动轻量 fix 直通任务:脚手架 + PM 编排剧本', hint: '[任务名] <一句话描述> [--full|--light] [--auto]', handler: hkFix },
@@ -1074,14 +1201,14 @@ export function registerCommands(ctx) {
1074
1201
  { name: 'hk-te', description: 'TE 环境串行租约(测试环境全局唯一):acquire 授权/排队、release 释放/退队、status 查看', hint: '[acquire|release <任务名> | status]', handler: hkTe },
1075
1202
  { name: 'hk-local', description: '本地配置(git-ignored)发现/确认/复制:首次确认后新 slot 自动补齐', hint: '[scan|status|approve all|path... | skip path... | mode copy|symlink | apply] [--repo <仓库>]', handler: hkLocal },
1076
1203
  { name: 'hk-sync', description: '资产仓库 git 同步:自动提交 → pull --rebase → 纯追加文件自动三路合并 → push(其余冲突中止回滚转人工)', handler: hkSync },
1077
- { name: 'hk-doctor', description: '检查 harness 工作区健康度(kit/角色/红线/流程)', hint: '', handler: hkDoctor },
1204
+ { name: 'hk-doctor', description: '检查 harness 工作区健康度(kit/角色/红线/流程);--fix 修复确定性缺件', hint: '[--fix]', handler: hkDoctor },
1078
1205
  ];
1079
1206
  for (const def of defs) {
1080
1207
  ctx.commands.register({
1081
1208
  name: def.name,
1082
1209
  description: def.description,
1083
1210
  ...(def.hint ? { input: { hint: def.hint } } : {}),
1084
- handler: ({ agent, rawInput }) => def.handler({ agent, rawInput }),
1211
+ handler: ({ agent, rawInput }) => def.handler({ agent, rawInput, ctx }),
1085
1212
  });
1086
1213
  }
1087
1214
  }
@@ -2,15 +2,15 @@
2
2
  //
3
3
  // 设计(2026-11-20 与人定稿):
4
4
  // - 不从插件硬编码文件名;候选由主工作树的 ignored/untracked 文件推断;
5
- // - 首次确认后写入本机 manifest(tasks/local-files.json,不入资产 git);
5
+ // - 首次确认后写入本机 manifest(.harness/local/local-files.json,不入资产 git);
6
6
  // - 新 slot 只复制已确认项;新候选只提示,不自动复制;
7
7
  // - 支持 copy / symlink 两种模式,目标已存在时不覆盖。
8
8
  import fs from 'node:fs';
9
9
  import path from 'node:path';
10
- import { harnessDir } from './paths.js';
10
+ import { harnessDir, localStatePath } from './paths.js';
11
11
  import { runGit } from './exec.js';
12
12
 
13
- const MANIFEST = 'tasks/local-files.json';
13
+ const MANIFEST = 'local-files.json';
14
14
  const CONFIG_EXT = new Set(['.properties', '.yml', '.yaml', '.conf', '.ini', '.toml', '.json', '.xml', '.env']);
15
15
  const EXCLUDE_DIRS = new Set([
16
16
  '.git', 'target', 'build', 'dist', 'out', 'bin', 'obj', 'node_modules', '.idea', '.vscode',
@@ -21,7 +21,7 @@ const EXCLUDE_EXT = new Set([
21
21
  '.pdf', '.log', '.lock', '.map', '.min.js', '.min.css', '.woff', '.woff2', '.ttf', '.eot',
22
22
  ]);
23
23
 
24
- export const localFilesPath = (ws) => path.join(harnessDir(ws), MANIFEST);
24
+ export const localFilesPath = (ws) => localStatePath(ws, MANIFEST, 'tasks/local-files.json');
25
25
 
26
26
  export function readLocalFiles(ws) {
27
27
  try {
@@ -160,7 +160,7 @@ export async function provisionLocalFiles(ws, source, slotDir) {
160
160
  /** 把已确认配置补到所有已绑定 slot(/hk-local apply)。 */
161
161
  export async function provisionAllSlots(ws, sources) {
162
162
  let ledger = {};
163
- try { ledger = JSON.parse(fs.readFileSync(path.join(harnessDir(ws), 'tasks', 'worktrees.json'), 'utf8')); } catch { /* no ledger */ }
163
+ try { ledger = JSON.parse(fs.readFileSync(localStatePath(ws, 'worktrees.json', 'tasks/worktrees.json'), 'utf8')); } catch { /* no ledger */ }
164
164
  const notes = [];
165
165
  for (const source of sources ?? []) {
166
166
  const slots = ledger.slots?.[source.name] ?? {};
@@ -0,0 +1,280 @@
1
+ // 任务运行统计:从 DSH sessionQuery / sessions 读取会话树,汇总模型、token、耗时与失败。
2
+ // 只收元数据,不落 prompt / 消息正文 / 工具参数 / 原始 session id。
3
+ // 两个消费面共用同一采集函数:面板实时查看、归档时写 metrics/<R>.json。
4
+ import fs from 'node:fs';
5
+ import path from 'node:path';
6
+ import { harnessDir } from './paths.js';
7
+ import { readTaskSessions } from './bindings.js';
8
+
9
+ const USAGE_KEYS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'];
10
+
11
+ function emptyUsage() {
12
+ return Object.fromEntries(USAGE_KEYS.map((k) => [k, 0]));
13
+ }
14
+
15
+ function addUsage(target, usage) {
16
+ if (!usage || typeof usage !== 'object') return false;
17
+ let found = false;
18
+ for (const key of USAGE_KEYS) {
19
+ const value = Number(usage[key]);
20
+ if (Number.isFinite(value) && value >= 0) { target[key] += value; found = true; }
21
+ }
22
+ return found;
23
+ }
24
+
25
+ function sessionLabel(id, primaryId, catalog) {
26
+ if (id === primaryId) return 'PM';
27
+ return catalog.get(id) || '子会话';
28
+ }
29
+
30
+ function flattenTree(nodes, out) {
31
+ for (const node of nodes ?? []) {
32
+ if (node?.session?.header?.id) out.push(node.session.header.id);
33
+ flattenTree(node?.descendants, out);
34
+ }
35
+ }
36
+
37
+ function snapshotFromLive(session) {
38
+ if (!session) return null;
39
+ try {
40
+ const events = typeof session.snapshotEvents === 'function'
41
+ ? session.snapshotEvents()
42
+ : (typeof session.ownEvents === 'function' ? session.ownEvents() : []);
43
+ return { header: session.header ?? {}, events, inherited: Number(session.inheritedEventCount ?? 0) };
44
+ } catch { return null; }
45
+ }
46
+
47
+ /**
48
+ * 采集一个任务的运行统计。
49
+ * services: { sessionQuery?, tokenMeter?, sessions?, currentSession? }
50
+ * 返回 { schemaVersion, generatedAt, coverage, agents, totals, notes }。
51
+ */
52
+ export async function collectTaskMetrics(ws, kit, task, services = {}) {
53
+ const generatedAt = new Date().toISOString();
54
+ const notes = [];
55
+ const binding = readTaskSessions(ws)[task] ?? {};
56
+ const primaryId = typeof binding.sessionId === 'string' ? binding.sessionId : null;
57
+ const boundIds = [...new Set([
58
+ primaryId,
59
+ ...(Array.isArray(binding.sessions) ? binding.sessions.map((x) => x?.id) : []),
60
+ ].filter((x) => typeof x === 'string' && x))];
61
+
62
+ const ids = new Set(boundIds);
63
+ const { sessionQuery, tokenMeter, sessions, currentSession } = services;
64
+ const canTrace = !!sessionQuery && typeof sessionQuery.traceSession === 'function';
65
+ const canRead = !!sessionQuery && typeof sessionQuery.readSession === 'function';
66
+
67
+ if (canTrace) {
68
+ for (const id of boundIds) {
69
+ try {
70
+ const trace = await sessionQuery.traceSession(id);
71
+ const found = [];
72
+ if (trace?.target?.header?.id) found.push(trace.target.header.id);
73
+ flattenTree(trace?.descendants, found);
74
+ for (const x of found) ids.add(x);
75
+ } catch {
76
+ notes.push(`会话 ${id.slice(0, 8)} 的会话树不可读`);
77
+ }
78
+ }
79
+ }
80
+ let currentSnapshot = null;
81
+ if (ids.size === 0 && currentSession) {
82
+ currentSnapshot = snapshotFromLive(currentSession);
83
+ if (currentSnapshot) ids.add('__current__');
84
+ }
85
+
86
+ // currentSession 不在绑定表时的兜底:只统计当前会话,标记 partial。
87
+ const idList = [...ids];
88
+ if (idList.length === 0) {
89
+ return {
90
+ schemaVersion: 1, generatedAt, coverage: 'unavailable',
91
+ agents: [], totals: totalOf([]), notes: ['任务没有可读的会话绑定'],
92
+ };
93
+ }
94
+
95
+ const snapshots = new Map();
96
+ const liveSessions = new Map();
97
+ for (const id of idList) {
98
+ if (id === '__current__') { snapshots.set(id, currentSnapshot); continue; }
99
+ let snap = null;
100
+ if (canRead) {
101
+ try {
102
+ const s = await sessionQuery.readSession(id);
103
+ if (s?.events) snap = { header: s.session ?? s.header ?? {}, events: s.events, inherited: Number(s.inheritedEventCount ?? 0) };
104
+ } catch { notes.push(`会话 ${String(id).slice(0, 8)} 读取失败`); }
105
+ }
106
+ if (!snap && sessions && typeof sessions.get === 'function') {
107
+ const live = sessions.get(id);
108
+ if (live) { liveSessions.set(id, live); snap = snapshotFromLive(live); }
109
+ }
110
+ if (!snap && currentSession && primaryId && id === primaryId) snap = snapshotFromLive(currentSession);
111
+ if (snap) snapshots.set(id, snap);
112
+ }
113
+
114
+ // 子代理标签:subagent/catalog 事件(data.childId + label/name,兼容 children 数组)
115
+ const catalog = new Map();
116
+ for (const snap of snapshots.values()) {
117
+ for (const e of snap.events ?? []) {
118
+ if (e?.type !== 'subagent/catalog') continue;
119
+ const d = e.data ?? {};
120
+ const entries = Array.isArray(d.children) ? d.children : [d];
121
+ for (const c of entries) {
122
+ if (typeof c?.childId === 'string' && c.childId) {
123
+ const label = c.label || c.name || c.role;
124
+ if (typeof label === 'string' && label) catalog.set(c.childId, label);
125
+ }
126
+ }
127
+ }
128
+ }
129
+
130
+ const agents = [];
131
+ for (const [id, snap] of snapshots.entries()) {
132
+ // 子会话可能继承父会话事件;只统计自身的 seq,避免 token 重复计算。
133
+ const inherited = Number.isFinite(snap.inherited) ? snap.inherited : 0;
134
+ const events = (snap.events ?? []).filter((e) => !Number.isFinite(Number(e?.seq)) || Number(e.seq) >= inherited);
135
+ const usage = emptyUsage();
136
+ let hasUsage = false;
137
+ let provider = null;
138
+ let model = null;
139
+ let effort = null;
140
+ let turns = 0;
141
+ let steps = 0;
142
+ let toolCalls = 0;
143
+ let toolFailures = 0;
144
+ const turnStart = new Map();
145
+ let activeDurationMs = 0;
146
+ let firstTime = null;
147
+ let lastTime = null;
148
+ let contextPressure = null;
149
+
150
+ for (const e of events) {
151
+ const type = e?.type;
152
+ const time = Number(e?.time);
153
+ if (Number.isFinite(time)) {
154
+ if (firstTime == null || time < firstTime) firstTime = time;
155
+ if (lastTime == null || time > lastTime) lastTime = time;
156
+ }
157
+ if (type === 'request/header') {
158
+ const cfg = e?.data?.header?.config;
159
+ if (cfg?.provider) provider = cfg.provider;
160
+ if (cfg?.model) model = cfg.model;
161
+ if (cfg?.reasoningEffort) effort = cfg.reasoningEffort;
162
+ } else if (type === 'assistant/message') {
163
+ steps += 1;
164
+ const src = e?.data?.message?.source;
165
+ if (!provider && src?.provider) provider = src.provider;
166
+ if (!model && src?.model) model = src.model;
167
+ if (addUsage(usage, e?.data?.usage)) hasUsage = true;
168
+ } else if (type === 'turn/start') {
169
+ const turn = e?.data?.turn;
170
+ if (Number.isFinite(Number(turn)) && Number.isFinite(time)) turnStart.set(Number(turn), time);
171
+ } else if (type === 'turn/end') {
172
+ turns += 1;
173
+ const turn = Number(e?.data?.turn);
174
+ const start = turnStart.get(turn);
175
+ if (Number.isFinite(start) && Number.isFinite(time) && time >= start) activeDurationMs += time - start;
176
+ } else if (type === 'tool/call') {
177
+ toolCalls += 1;
178
+ } else if (type === 'tool/result') {
179
+ if (e?.data?.error || e?.data?.message?.isError) toolFailures += 1;
180
+ }
181
+ }
182
+ if (turns === 0 && steps > 0) turns = steps;
183
+ if (!hasUsage) notes.push(`${sessionLabel(id, primaryId, catalog)} 未返回 usage`);
184
+
185
+ const live = liveSessions.get(id);
186
+ if (tokenMeter && typeof tokenMeter.contextPressure === 'function') {
187
+ try {
188
+ const cp = live
189
+ ? tokenMeter.contextPressure(live)
190
+ : (sessionQuery && typeof sessionQuery.inspectSession === 'function'
191
+ ? await sessionQuery.inspectSession(id, (s) => tokenMeter.contextPressure(s))
192
+ : null);
193
+ const pressure = Number(cp?.pressureTokens);
194
+ const window = Number(cp?.contextWindow);
195
+ contextPressure = Number.isFinite(pressure) && Number.isFinite(window) && window > 0 ? pressure / window : null;
196
+ } catch { /* 上下文压力是可选项 */ }
197
+ }
198
+
199
+ agents.push({
200
+ label: sessionLabel(id, primaryId, catalog),
201
+ provider: provider || null,
202
+ model: model || null,
203
+ reasoningEffort: effort || null,
204
+ turns,
205
+ steps,
206
+ inputTokens: hasUsage ? usage.inputTokens : null,
207
+ outputTokens: hasUsage ? usage.outputTokens : null,
208
+ cacheReadTokens: hasUsage ? usage.cacheReadTokens : null,
209
+ cacheWriteTokens: hasUsage ? usage.cacheWriteTokens : null,
210
+ reasoningTokens: hasUsage ? usage.reasoningTokens : null,
211
+ totalTokens: hasUsage ? usage.inputTokens + usage.outputTokens : null,
212
+ toolCalls,
213
+ toolFailures,
214
+ activeDurationMs,
215
+ wallClockMs: firstTime != null && lastTime != null ? Math.max(0, lastTime - firstTime) : null,
216
+ contextPressure: typeof contextPressure === 'number' ? contextPressure : null,
217
+ });
218
+ }
219
+
220
+ agents.sort((a, b) => (a.label === 'PM' ? -1 : b.label === 'PM' ? 1 : a.label.localeCompare(b.label)));
221
+ const anyUsage = agents.some((a) => a.inputTokens != null);
222
+ const missing = idList.length - snapshots.size;
223
+ const coverage = snapshots.size === 0 ? 'unavailable' : (missing > 0 || notes.length > 0 || !anyUsage ? 'partial' : 'complete');
224
+ return {
225
+ schemaVersion: 1,
226
+ generatedAt,
227
+ coverage,
228
+ agents,
229
+ totals: totalOf(agents),
230
+ notes: [...new Set(notes)].slice(0, 12),
231
+ };
232
+ }
233
+
234
+ function totalOf(agents) {
235
+ const sum = (key) => agents.reduce((n, a) => n + (typeof a[key] === 'number' ? a[key] : 0), 0);
236
+ return {
237
+ agents: agents.length,
238
+ turns: sum('turns'),
239
+ steps: sum('steps'),
240
+ inputTokens: sum('inputTokens'),
241
+ outputTokens: sum('outputTokens'),
242
+ cacheReadTokens: sum('cacheReadTokens'),
243
+ cacheWriteTokens: sum('cacheWriteTokens'),
244
+ reasoningTokens: sum('reasoningTokens'),
245
+ totalTokens: sum('totalTokens'),
246
+ toolCalls: sum('toolCalls'),
247
+ toolFailures: sum('toolFailures'),
248
+ activeDurationMs: sum('activeDurationMs'),
249
+ wallClockMs: sum('wallClockMs'),
250
+ };
251
+ }
252
+
253
+ /** 读取任务最新一轮归档统计(历史任务在会话不可读时的兜底)。 */
254
+ export function readLatestTaskMetrics(ws, task) {
255
+ const dir = path.join(harnessDir(ws), 'deliverables', '_archive', task, 'metrics');
256
+ if (!fs.existsSync(dir)) return null;
257
+ const files = fs.readdirSync(dir)
258
+ .filter((f) => /^R\d+\.json$/.test(f))
259
+ .sort((a, b) => Number(b.match(/\d+/)[0]) - Number(a.match(/\d+/)[0]));
260
+ for (const name of files) {
261
+ try {
262
+ const data = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
263
+ if (data && typeof data === 'object') return data;
264
+ } catch { /* 跳过坏快照 */ }
265
+ }
266
+ return null;
267
+ }
268
+
269
+ /** 归档时写 metrics/<R>.json;已存在则保留(同一轮只写一次)。 */
270
+ export function writeTaskMetrics(ws, task, tag, metrics) {
271
+ const dir = path.join(harnessDir(ws), 'deliverables', '_archive', task, 'metrics');
272
+ fs.mkdirSync(dir, { recursive: true });
273
+ const file = path.join(dir, `${tag}.json`);
274
+ if (fs.existsSync(file)) return { file, skipped: true };
275
+ const payload = { ...metrics, task, round: tag };
276
+ const tmp = `${file}.tmp`;
277
+ fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
278
+ fs.renameSync(tmp, file);
279
+ return { file, skipped: false };
280
+ }