dsh-harness-kit 0.0.0-stage → 0.1.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.
- package/LICENSE +21 -0
- package/README.md +321 -2
- package/README.zh-CN.md +278 -0
- package/client.js +1272 -0
- package/cordis.patch.yml +4 -0
- package/docs/DETAIL.en.md +97 -0
- package/docs/DETAIL.md +73 -0
- package/docs/assets/ui-new-task.png +0 -0
- package/docs/assets/ui-onboarding.png +0 -0
- package/docs/assets/ui-war-room.png +0 -0
- package/icon.svg +7 -0
- package/index.js +49 -0
- package/kernel/advance.js +96 -0
- package/kernel/bindings.js +24 -0
- package/kernel/commands.js +927 -0
- package/kernel/env.js +64 -0
- package/kernel/exec.js +41 -0
- package/kernel/flows.js +89 -0
- package/kernel/guards.js +79 -0
- package/kernel/miniyaml.js +133 -0
- package/kernel/models.js +104 -0
- package/kernel/panel.js +1103 -0
- package/kernel/paths.js +53 -0
- package/kernel/roles.js +67 -0
- package/kernel/setup.js +644 -0
- package/kernel/state.js +59 -0
- package/kernel/steer.js +27 -0
- package/kernel/sync.js +140 -0
- package/kernel/te.js +122 -0
- package/kernel/worktree.js +868 -0
- package/locale/en.json +14 -0
- package/locale/zh.json +14 -0
- package/package.json +63 -4
- package/packs/ai-coding/agents/business-analyst.md +90 -0
- package/packs/ai-coding/agents/code-reviewer.md +156 -0
- package/packs/ai-coding/agents/developer.md +147 -0
- package/packs/ai-coding/agents/project-manager.md +190 -0
- package/packs/ai-coding/agents/readiness-reviewer.md +123 -0
- package/packs/ai-coding/agents/solution-architect.md +122 -0
- package/packs/ai-coding/agents/test-engineer.md +230 -0
- package/packs/ai-coding/assets/scripts/check_codegraph.py +215 -0
- package/packs/ai-coding/assets/scripts/codebase_guide_init.py +330 -0
- package/packs/ai-coding/assets/scripts/env_auto.py +612 -0
- package/packs/ai-coding/assets/scripts/harness.py +38 -0
- package/packs/ai-coding/assets/scripts/harness_init.py +193 -0
- package/packs/ai-coding/assets/scripts/lib.py +1011 -0
- package/packs/ai-coding/assets/scripts/run_field.py +295 -0
- package/packs/ai-coding/assets/scripts/spec_lint.py +247 -0
- package/packs/ai-coding/assets/scripts/update_board.py +524 -0
- package/packs/ai-coding/assets/scripts/verify.py +184 -0
- package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/CODE_STANDARDS.tmpl +44 -0
- package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/app-CLAUDE.tmpl +34 -0
- package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/build.tmpl +8 -0
- package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/module-CLAUDE.tmpl +42 -0
- package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/root-CLAUDE.tmpl +41 -0
- package/packs/ai-coding/assets/templates/java/maven/CODE_STANDARDS.tmpl +44 -0
- package/packs/ai-coding/assets/templates/java/maven/build.tmpl +9 -0
- package/packs/ai-coding/assets/templates/java/maven/root-CLAUDE.tmpl +38 -0
- package/packs/ai-coding/assets/templates/java/maven-multimodule/CODE_STANDARDS.tmpl +44 -0
- package/packs/ai-coding/assets/templates/java/maven-multimodule/build.tmpl +9 -0
- package/packs/ai-coding/assets/templates/java/maven-multimodule/module-CLAUDE.tmpl +40 -0
- package/packs/ai-coding/assets/templates/java/maven-multimodule/root-CLAUDE.tmpl +38 -0
- package/packs/ai-coding/assets/templates/javascript/mobile-app/CODE_STANDARDS.tmpl +51 -0
- package/packs/ai-coding/assets/templates/javascript/mobile-app/build.tmpl +8 -0
- package/packs/ai-coding/assets/templates/javascript/mobile-app/root-CLAUDE.tmpl +36 -0
- package/packs/ai-coding/assets/templates/javascript/uniapp/CODE_STANDARDS.tmpl +69 -0
- package/packs/ai-coding/assets/templates/javascript/uniapp/build.tmpl +8 -0
- package/packs/ai-coding/assets/templates/javascript/uniapp/root-CLAUDE.tmpl +56 -0
- package/packs/ai-coding/assets/templates/javascript/vue-multimodule/CODE_STANDARDS.tmpl +51 -0
- package/packs/ai-coding/assets/templates/javascript/vue-multimodule/app-CLAUDE.tmpl +36 -0
- package/packs/ai-coding/assets/templates/javascript/vue-multimodule/build.tmpl +8 -0
- package/packs/ai-coding/assets/templates/javascript/vue-multimodule/root-CLAUDE.tmpl +34 -0
- package/packs/ai-coding/flows/_router.yml +14 -0
- package/packs/ai-coding/flows/bugfix.yml +37 -0
- package/packs/ai-coding/flows/fix.yml +44 -0
- package/packs/ai-coding/flows/init.yml +83 -0
- package/packs/ai-coding/flows/new.yml +29 -0
- package/packs/ai-coding/flows/quick.yml +40 -0
- package/packs/ai-coding/flows/refactor.yml +50 -0
- package/packs/ai-coding/flows/standard.yml +49 -0
- package/packs/ai-coding/rules/code-standards.md +30 -0
- package/packs/ai-coding/rules/core.md +83 -0
- package/packs/ai-coding/templates/bugfix.md +29 -0
- package/packs/ai-coding/templates/memory-entry.md +46 -0
- package/packs/ai-coding/templates/proposal.md +47 -0
- package/packs/ai-coding/templates/spec-template.md +34 -0
- package/screenshots.json +5 -0
package/kernel/setup.js
ADDED
|
@@ -0,0 +1,644 @@
|
|
|
1
|
+
// 工作区初始化/子工程登记的确定性内核:/hk-setup 与 /hk-init 的文件与 git 操作层。
|
|
2
|
+
// 供 commands.js(CLI)与 panel.js(面板 HTTP 端点)共用;steer 编排留在 commands.js。
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { runGit } from './exec.js';
|
|
6
|
+
import { readKit, writeKit, defaultKit, harnessDir, packDir, kitPath } from './paths.js';
|
|
7
|
+
|
|
8
|
+
export function guessRole(name) {
|
|
9
|
+
if (/front|web|ui/i.test(name)) return 'frontend';
|
|
10
|
+
if (/app|android|ios|mobile/i.test(name)) return 'app';
|
|
11
|
+
return 'backend';
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function boardTemplate() {
|
|
15
|
+
return [
|
|
16
|
+
'# 任务看板',
|
|
17
|
+
'',
|
|
18
|
+
'> **状态机**:PENDING → IN_PROGRESS → AWAITING_ARCHIVE → DONE →(重开轮次)→ PENDING',
|
|
19
|
+
'> **Apply 子步骤**:Dev → CR → TE(记录在「Apply进度」列)',
|
|
20
|
+
'> **重开轮次**:已归档(DONE)任务因 bugfix/新需求重开时,`/hk-apply` 将状态 `DONE → PENDING` 并标注 `R<N+1>`;归档为增量',
|
|
21
|
+
'> **续接机制**:任何人读看板 + deliverables 即可接手继续',
|
|
22
|
+
'',
|
|
23
|
+
'| 任务名 | 状态 | Profile | Apply进度 | 分支 | 上次活动 | 续接提示 |',
|
|
24
|
+
'|--------|------|---------|-----------|------|---------|----------|',
|
|
25
|
+
'',
|
|
26
|
+
'> **写入纪律**:禁止直接编辑本文件,一律 `python3 .harness/scripts/update_board.py <任务> [--status …] [--apply …] [--branch …] [--hint …]`。',
|
|
27
|
+
'> 列格式契约(脚本强校验):状态=枚举;Profile=`standard/quick/bugfix/fix/fix-full/fix-light/refactor`(bugfix=全流程;fix 直通三态:',
|
|
28
|
+
'> full 走 CR→TE、light 跳过 CR/TE 标 `—`、裸 `fix`=裁决未定过渡态(裁决后 PM 改写为 fix-full/fix-light);未定档 `—`);',
|
|
29
|
+
'> Apply进度=`—|已归档|R<n>:阶段链`——链必须完整等于该 profile 固定流程(standard/quick/bugfix:`propose 审批1 Dev CR TE 审批2 验证`;',
|
|
30
|
+
'> refactor 前置 `影响面`;fix 直通:`质量门 Dev CR TE 验证`),每阶段后缀 `✅完成 ▶当前(至多一个) …待做 ⛔阻塞 —跳过`,缺省阶段不许省略;',
|
|
31
|
+
'> **顺序约束**:`▶` 之前必须全部 `✅` 或 `—`(面板会检测越序并在「需要你」提醒),⛔ 阻塞需人工裁决后改写;',
|
|
32
|
+
'> 续接提示 ≤300 字符一句话「卡在X,下一步Y」,依赖前缀 `[等 任务名]`,禁 `|`/换行;上次活动由写入方自动打分钟级时间戳。',
|
|
33
|
+
'',
|
|
34
|
+
].join('\n');
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Recursively copy pack files. Default never overwrites; managed=true refreshes differing files (pack 管理运行时). */
|
|
38
|
+
export function copyNew(srcDir, dstDir, managed = false) {
|
|
39
|
+
let added = 0;
|
|
40
|
+
let existed = 0;
|
|
41
|
+
let updated = 0;
|
|
42
|
+
for (const e of fs.readdirSync(srcDir, { withFileTypes: true })) {
|
|
43
|
+
const src = path.join(srcDir, e.name);
|
|
44
|
+
const dst = path.join(dstDir, e.name);
|
|
45
|
+
if (e.isDirectory()) {
|
|
46
|
+
const r = copyNew(src, dst, managed);
|
|
47
|
+
added += r.added;
|
|
48
|
+
existed += r.existed;
|
|
49
|
+
updated += r.updated;
|
|
50
|
+
} else if (fs.existsSync(dst)) {
|
|
51
|
+
if (managed && fs.readFileSync(src, 'utf8') !== fs.readFileSync(dst, 'utf8')) {
|
|
52
|
+
fs.copyFileSync(src, dst);
|
|
53
|
+
updated += 1;
|
|
54
|
+
} else existed += 1;
|
|
55
|
+
} else {
|
|
56
|
+
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
57
|
+
fs.copyFileSync(src, dst);
|
|
58
|
+
added += 1;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return { added, existed, updated };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* 登记/克隆一个代码仓库(/hk-setup --add 的确定性层)。
|
|
66
|
+
* @returns {Promise<{ok:true, lines:string[], source:object}|{ok:false, error:string}>}
|
|
67
|
+
*/
|
|
68
|
+
export async function addSource(ws, { url, name, path: relPath, role, branch } = {}) {
|
|
69
|
+
const kit = readKit(ws) ?? defaultKit();
|
|
70
|
+
name = name ?? path.basename(url).replace(/\.git$/, '');
|
|
71
|
+
const explicitRole = role; // 只有显式指定的 role 才触发语义目录名;自动推断保持仓名目录(CLI 行为不变)
|
|
72
|
+
role = role ?? guessRole(name);
|
|
73
|
+
// path 派生(2026-11-17 定):显式 role 在已登记 sources 中唯一 → services/<role>(语义布局,
|
|
74
|
+
// 与 iot-harness 手工约定一致);role 空/重名/跨端 → 回落 services/<仓名>。
|
|
75
|
+
// 显式传入的 path 永远优先;path 与 name 一样是"克隆后难改"字段,默认值在登记时定好。
|
|
76
|
+
relPath = relPath ?? (explicitRole && !kit.sources.some((s) => s.role === explicitRole)
|
|
77
|
+
? `services/${explicitRole}`
|
|
78
|
+
: `services/${name}`);
|
|
79
|
+
const lines = [];
|
|
80
|
+
|
|
81
|
+
// 已登记判定(2026-11-17 修复):只看 kit.json 不够——团队资产仓库的 kit.json 自带
|
|
82
|
+
// sources 登记(如 services/sie-iiot),克隆 .harness 后本地目录并不存在;此时必须补 clone,
|
|
83
|
+
// 否则"初始化完成"但 services/ 空的假象。判定 = 登记 && 目录实际存在。
|
|
84
|
+
const existing = kit.sources.find((s) => s.name === name || s.path === relPath);
|
|
85
|
+
if (existing) {
|
|
86
|
+
const existingAbs = path.join(ws, existing.path);
|
|
87
|
+
const okExisting = fs.existsSync(existingAbs)
|
|
88
|
+
&& (await runGit(['rev-parse', '--git-dir'], { cwd: existingAbs })).code === 0;
|
|
89
|
+
if (okExisting) {
|
|
90
|
+
return { ok: false, error: `仓库 ${name}(${existing.path})已登记且目录存在,无需重复添加。` };
|
|
91
|
+
}
|
|
92
|
+
// 已登记但本地无代码(资产仓库带来的登记)→ 沿用其登记坐标补 clone
|
|
93
|
+
relPath = existing.path;
|
|
94
|
+
name = existing.name;
|
|
95
|
+
role = existing.role ?? role;
|
|
96
|
+
lines.push(`登记已在资产仓库存在(${existing.path}),本地无代码 → 补 clone。`);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const abs = path.join(ws, relPath);
|
|
100
|
+
if (fs.existsSync(abs)) {
|
|
101
|
+
const isRepo = (await runGit(['rev-parse', '--git-dir'], { cwd: abs })).code === 0;
|
|
102
|
+
if (isRepo) {
|
|
103
|
+
lines.push(`路径 \`${relPath}\` 已存在且是 git 仓库,跳过 clone,直接登记。`);
|
|
104
|
+
} else if (fs.readdirSync(abs).length === 0) {
|
|
105
|
+
// 空目录(上次中断残留)→ 清掉重 clone
|
|
106
|
+
fs.rmdirSync(abs);
|
|
107
|
+
lines.push(`路径 \`${relPath}\` 是空目录(中断残留),已清理并重新 clone。`);
|
|
108
|
+
const r = await runGit(['clone', ...(branch ? ['--branch', branch] : []), url, relPath], { cwd: ws, timeoutMs: 600_000 });
|
|
109
|
+
if (r.code !== 0) return { ok: false, error: `git clone 失败(exit ${r.code}):\n${r.stderr || r.stdout}` };
|
|
110
|
+
} else {
|
|
111
|
+
// 非 git 的已有目录:按既有约定直接登记(不 clone),但要提示(可能是本地代码/中断残留)
|
|
112
|
+
lines.push(`路径 \`${relPath}\` 已存在但不是 git 仓库,跳过 clone 直接登记(如需克隆请先清理该目录)。`);
|
|
113
|
+
}
|
|
114
|
+
} else {
|
|
115
|
+
lines.push(`执行:git clone ${branch ? `--branch ${branch} ` : ''}${url} ${relPath}`);
|
|
116
|
+
const r = await runGit(['clone', ...(branch ? ['--branch', branch] : []), url, relPath], { cwd: ws, timeoutMs: 600_000 });
|
|
117
|
+
if (r.code !== 0) return { ok: false, error: `git clone 失败(exit ${r.code}):\n${r.stderr || r.stdout}` };
|
|
118
|
+
lines.push('clone 完成。');
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
let resolvedBranch = branch ?? existing?.branch;
|
|
122
|
+
if (!resolvedBranch) {
|
|
123
|
+
const b = await runGit(['branch', '--show-current'], { cwd: abs });
|
|
124
|
+
resolvedBranch = b.code === 0 && b.stdout.trim() ? b.stdout.trim() : 'master';
|
|
125
|
+
}
|
|
126
|
+
if (existing) {
|
|
127
|
+
// 补 clone 场景:刷新登记(url/role/branch 以本次为准,path/name 沿用资产登记)
|
|
128
|
+
existing.url = url;
|
|
129
|
+
existing.role = role;
|
|
130
|
+
existing.branch = resolvedBranch;
|
|
131
|
+
} else {
|
|
132
|
+
kit.sources.push({ name, url, path: relPath, role, branch: resolvedBranch });
|
|
133
|
+
}
|
|
134
|
+
writeKit(ws, kit);
|
|
135
|
+
lines.push(`已登记 **${name}** → \`${relPath}\`(role: ${role}, branch: ${resolvedBranch}),写入 .harness/kit.json。`);
|
|
136
|
+
return { ok: true, lines, source: { name, path: relPath, role, branch: resolvedBranch } };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* 初始化 .harness 骨架/资产仓库绑定/脚本模板物化(/hk-init 的确定性层,幂等)。
|
|
141
|
+
* @param {string} ws 工作区绝对路径
|
|
142
|
+
* @param {{assets?: string, branch?: string, sources?: Array<object>}} opts
|
|
143
|
+
* assets 取值与 CLI 一致:'<git-url>' | 'init' | 'local' | undefined(省略=保持现状探测);
|
|
144
|
+
* sources 为面板初始化向导登记的代码仓库(等价于逐个 /hk-setup --add,骨架物化后执行)。
|
|
145
|
+
* @returns {Promise<{ok:true, created, kept, scanned, warnings, assetsBinding, attachPending, attachPushed, kit, sourceReports}|{ok:false, error:string}>}
|
|
146
|
+
*/
|
|
147
|
+
export async function runInit(ws, { assets, branch, sources = [], onProgress } = {}) {
|
|
148
|
+
const hd = harnessDir(ws);
|
|
149
|
+
const created = [];
|
|
150
|
+
const kept = [];
|
|
151
|
+
// 进度上报(面板初始化向导的"当前动作"动态提示;错误容忍,不影响初始化本身)
|
|
152
|
+
const progress = (stage, detail = '') => {
|
|
153
|
+
try { onProgress?.({ stage, detail }); } catch { /* 忽略 */ }
|
|
154
|
+
};
|
|
155
|
+
progress('骨架物化', '准备 .harness 资产与脚本');
|
|
156
|
+
|
|
157
|
+
// 0. assets repo binding — clone must happen BEFORE the skeleton exists
|
|
158
|
+
// (git clone requires an empty/missing target dir). Three cases (§7.2):
|
|
159
|
+
// --assets <url> → clone the team assets repo as .harness/
|
|
160
|
+
// --assets init → git init + first commit (after skeleton)
|
|
161
|
+
// --assets local / omitted → local mode, no git binding
|
|
162
|
+
let assetsBinding = null;
|
|
163
|
+
let attachPending = false; // 已有资产接管空远端:待骨架/物化完成后统一 commit+push
|
|
164
|
+
if (assets && assets !== 'init' && assets !== 'local') {
|
|
165
|
+
const url = assets;
|
|
166
|
+
progress('资产仓库', `检查/克隆 ${url}`);
|
|
167
|
+
if (fs.existsSync(hd) && fs.readdirSync(hd).length > 0) {
|
|
168
|
+
// 已绑定同一远端 → 幂等跳过(重跑初始化/向导重复提交的常见场景,2026-11-17 事故:
|
|
169
|
+
// 之前这里直接报"远端已有内容需人工合并",导致已绑定工作区无法补齐子工程 clone)
|
|
170
|
+
let bound = null;
|
|
171
|
+
if (fs.existsSync(path.join(hd, '.git'))) {
|
|
172
|
+
const curRemote = await runGit(['remote', 'get-url', 'origin'], { cwd: hd });
|
|
173
|
+
if (curRemote.code === 0 && curRemote.stdout.trim() === url) {
|
|
174
|
+
const cb = await runGit(['branch', '--show-current'], { cwd: hd });
|
|
175
|
+
bound = { mode: 'clone', url, branch: cb.stdout.trim() || branch || 'master' };
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
if (bound) {
|
|
179
|
+
assetsBinding = bound;
|
|
180
|
+
progress('资产仓库', `已绑定 ${url}(跳过克隆)`);
|
|
181
|
+
} else {
|
|
182
|
+
// 本地已有资产 + 想挂远端:仅当远端是空仓库(ls-remote 无任何 ref)才可自动接管——
|
|
183
|
+
// git init + 绑定 origin,待骨架物化完成后整体首次提交并 push -u(见 step 5)。
|
|
184
|
+
// 远端非空时存在同名文件取舍,必须人工合并,保持拒绝。
|
|
185
|
+
const probe = await runGit(['ls-remote', url], { cwd: ws, timeoutMs: 60_000 });
|
|
186
|
+
if (probe.code !== 0) {
|
|
187
|
+
return { ok: false, error: `无法访问远端 \`${url}\`(exit ${probe.code}),无法确认其为空仓库:\n${(probe.stderr || probe.stdout).trim()}\n请确认 URL/凭据后重试,或按人工流程绑定。` };
|
|
188
|
+
}
|
|
189
|
+
if (probe.stdout.trim()) {
|
|
190
|
+
return {
|
|
191
|
+
ok: false,
|
|
192
|
+
error:
|
|
193
|
+
`远端 \`${url}\` 已有内容,与本地已有资产可能存在同名文件,需人工取舍,插件不自动合并(仅空仓库可自动接管)。\n` +
|
|
194
|
+
'手工执行:\n' +
|
|
195
|
+
' cd .harness && git init && git remote add origin <url> && git fetch\n' +
|
|
196
|
+
' 取舍合并后 push,再重跑 /hk-init(会自动探测回填绑定)。',
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
// 空远端 → 自动接管
|
|
200
|
+
if (!fs.existsSync(path.join(hd, '.git'))) {
|
|
201
|
+
const gi = await runGit(['init', ...(branch ? ['-b', branch] : [])], { cwd: hd });
|
|
202
|
+
if (gi.code !== 0) return { ok: false, error: `git init 失败(exit ${gi.code}):\n${(gi.stderr || gi.stdout).trim()}` };
|
|
203
|
+
}
|
|
204
|
+
const ro = await runGit(['remote', 'get-url', 'origin'], { cwd: hd });
|
|
205
|
+
if (ro.code !== 0) {
|
|
206
|
+
const ra = await runGit(['remote', 'add', 'origin', url], { cwd: hd });
|
|
207
|
+
if (ra.code !== 0) return { ok: false, error: `git remote add 失败(exit ${ra.code}):\n${(ra.stderr || ra.stdout).trim()}` };
|
|
208
|
+
} else if (ro.stdout.trim() !== url) {
|
|
209
|
+
return { ok: false, error: `.harness 已绑定另一远端 \`${ro.stdout.trim()}\`,与参数 \`${url}\` 不一致,转人工处理。` };
|
|
210
|
+
}
|
|
211
|
+
const b = await runGit(['branch', '--show-current'], { cwd: hd });
|
|
212
|
+
assetsBinding = { mode: 'clone', url, branch: b.stdout.trim() || branch || 'master' };
|
|
213
|
+
attachPending = true;
|
|
214
|
+
created.push('.harness/(已有资产接管空远端,待推送)');
|
|
215
|
+
}
|
|
216
|
+
} else {
|
|
217
|
+
const r = await runGit(['clone', ...(branch ? ['--branch', branch] : []), url, '.harness'], { cwd: ws, timeoutMs: 600_000 });
|
|
218
|
+
if (r.code !== 0) return { ok: false, error: `git clone 资产仓库失败(exit ${r.code}):\n${r.stderr || r.stdout}` };
|
|
219
|
+
const b = await runGit(['branch', '--show-current'], { cwd: hd });
|
|
220
|
+
assetsBinding = { mode: 'clone', url, branch: b.stdout.trim() || branch || 'master' };
|
|
221
|
+
created.push('.harness/(clone 自团队资产仓库)');
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
// 1. .harness skeleton (idempotent)
|
|
226
|
+
for (const dir of ['deliverables/_archive', 'specs', 'memory/entries', 'tasks', 'codebase-guide', 'agents', 'flows', 'templates', 'rules']) {
|
|
227
|
+
const abs = path.join(hd, dir);
|
|
228
|
+
if (!fs.existsSync(abs)) {
|
|
229
|
+
fs.mkdirSync(abs, { recursive: true });
|
|
230
|
+
created.push(`.harness/${dir}/`);
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
for (const [file, content] of [
|
|
234
|
+
['tasks/board.md', boardTemplate()],
|
|
235
|
+
// memory/index.md 预置骨架:命名约定 + 写/不写纪律 + 流程优先决策门(条目模板见 memory/templates/entry.md)。
|
|
236
|
+
['memory/index.md', [
|
|
237
|
+
'# 工程记忆索引',
|
|
238
|
+
'',
|
|
239
|
+
'> 可复用经验、踩坑记录。每次 `/hk-archive` 时由 PM 执行 Memory Merge 合并:条目一人一文件(`entries/`),本索引只追加。',
|
|
240
|
+
'',
|
|
241
|
+
'## 命名约定',
|
|
242
|
+
'',
|
|
243
|
+
'| 字段 | 格式 | 示例 | 约束 |',
|
|
244
|
+
'|------|------|------|------|',
|
|
245
|
+
'| 文件 | `YYYY-MM-DD_<scope>_<slug>.md` | `2026-04-22_shared_pm-heartbeat-drift.md` | 双下划线分隔;scope 小写;slug kebab-case、3-6 词 |',
|
|
246
|
+
'| id | `M-YYYYMMDD-<scope>-<slug>` | `M-20260422-shared-pm-heartbeat-drift` | 写在 frontmatter,不随文件名改 |',
|
|
247
|
+
'| scope | 六选一 | backend / frontend / mobile / tooling / infra / shared | 不许自造;跨多域优先 shared |',
|
|
248
|
+
'| slug | 描述根因/机制 | `pagination-limit-nan` | 不要描述现象(如 `list-broken`) |',
|
|
249
|
+
'| tags | YAML 数组 | `[pagination, env, NaN]` | 3-5 个关键词 |',
|
|
250
|
+
'',
|
|
251
|
+
'条目正文模板:[`templates/entry.md`](templates/entry.md)(frontmatter + 症状/根因/修复/防复发/复发检测)。',
|
|
252
|
+
'',
|
|
253
|
+
'## 何时写 / 不写',
|
|
254
|
+
'',
|
|
255
|
+
'| 写 | 不写 |',
|
|
256
|
+
'|----|------|',
|
|
257
|
+
'| CR REJECT / TE FAIL(实现层 bug) | 一次通过、0 REJECT/FAIL 的任务 |',
|
|
258
|
+
'| 开发中踩坑 ≥2 次尝试才解决 | 需求/方案本身错(应反馈到 proposal) |',
|
|
259
|
+
'| OS/依赖/配置类坑(有强复现性) | 同一任务内反复调试小细节(如 CSS 间距) |',
|
|
260
|
+
'| 编排层出现漂移(PM/Agent 契约不一致) | 没踩坑就没有经验要沉淀 |',
|
|
261
|
+
'',
|
|
262
|
+
'## 流程优先决策门(tooling / infra / shared 三类专属)',
|
|
263
|
+
'',
|
|
264
|
+
'> **改得动就改流程,改不动才记记忆。** 这三类坑多为 harness 自身没做对:',
|
|
265
|
+
'> 能改流程(脚本·门禁·模板·命令·规则)消除的,直接改流程随归档提交,不写条目;',
|
|
266
|
+
'> 只有外部依赖/第三方行为/平台固有语义改不掉的,才写条目,且正文必须含「流程优化排除」节说明理由。',
|
|
267
|
+
'',
|
|
268
|
+
'## 条目索引',
|
|
269
|
+
'',
|
|
270
|
+
'| 条目 | scope | 摘要 | 来源 | 登记日期 |',
|
|
271
|
+
'|------|-------|------|------|---------|',
|
|
272
|
+
'<!-- 每条 memory entry 归档时在此追加一行(只追加) -->',
|
|
273
|
+
'',
|
|
274
|
+
].join('\n')],
|
|
275
|
+
['codebase-guide/index.md', [
|
|
276
|
+
'# Codebase Guide 入口索引',
|
|
277
|
+
'',
|
|
278
|
+
'> **路由表**:不存代码细节,只告诉 Agent 去哪找。代码知识三层都在子工程自己维护。',
|
|
279
|
+
'',
|
|
280
|
+
'## 知识分布三层模型',
|
|
281
|
+
'',
|
|
282
|
+
'| 层 | 位置 | 性质 | 用途 |',
|
|
283
|
+
'|---|---|---|---|---|',
|
|
284
|
+
'| L1 入口 | `services/<子工程>/CLAUDE.md` | 人工编写 | 技术栈、框架模式、模块发现索引 |',
|
|
285
|
+
'| L2 规范 | `services/<子工程>/docs/CODE_STANDARDS.md` | 人工编写 | 编码规范,团队持续打磨 |',
|
|
286
|
+
'| L3 索引 | `services/<子工程>/.codegraph/` | CodeGraph 生成 | 类/方法/调用链,AI 通过 `codegraph explore` 查询 |',
|
|
287
|
+
'',
|
|
288
|
+
'## 按角色路由',
|
|
289
|
+
'',
|
|
290
|
+
'| 角色 | 必读 | 按需 |',
|
|
291
|
+
'|---|---|---|',
|
|
292
|
+
'| PM | overview.md、specs/_index.md、tasks/board.md | memory/index.md |',
|
|
293
|
+
'| BA | overview.md、specs/_index.md、对应子工程 L1 CLAUDE.md | 相关模块 L1 CLAUDE.md |',
|
|
294
|
+
'| SA | 对应子工程 L1 + L2、codegraph explore(L3) | 相关模块 L1 CLAUDE.md |',
|
|
295
|
+
'| Dev | 对应子工程 L1 + L2、对应模块 L1 CLAUDE.md | codegraph explore(调用链) |',
|
|
296
|
+
'| CR | .harness/rules/code-standards.md、子工程 L2 | codegraph explore(影响范围) |',
|
|
297
|
+
'| TE | 任务 deliverables(proposal/requirements/design) | 对应子工程 L1 |',
|
|
298
|
+
'',
|
|
299
|
+
'## 本目录文件清单',
|
|
300
|
+
'',
|
|
301
|
+
'| 文件 | 内容 |',
|
|
302
|
+
'|---|---|',
|
|
303
|
+
'| `index.md` | 本文件 — 路由表 |',
|
|
304
|
+
'| `overview.md` | 项目架构总览(技术栈、目录结构、子工程关系),由 `/hk-init` 流程据实补全 |',
|
|
305
|
+
'',
|
|
306
|
+
].join('\n')],
|
|
307
|
+
// overview.md 预置骨架:对应旧框架「框架模板预置 + 人/AI 逐步补全」约定,
|
|
308
|
+
// codebase_guide_init.py 不生成此文件;BA/SA/RR 角色均引用它,缺失会导致悬空引用。
|
|
309
|
+
['codebase-guide/overview.md', [
|
|
310
|
+
'# 项目架构总览',
|
|
311
|
+
'',
|
|
312
|
+
'> 预置骨架:`/hk-init` 物化,内容由人/AI 随任务逐步补全(技术栈、目录结构属工程事实,不得编造)。',
|
|
313
|
+
'',
|
|
314
|
+
'## 技术栈',
|
|
315
|
+
'',
|
|
316
|
+
'| 端 | 技术 | 说明 |',
|
|
317
|
+
'|---|---|---|',
|
|
318
|
+
'<!-- TODO: 按各子工程 CLAUDE.md / build.json 据实补全 -->',
|
|
319
|
+
'',
|
|
320
|
+
'## 目录结构',
|
|
321
|
+
'',
|
|
322
|
+
'<!-- TODO: 据实补全 -->',
|
|
323
|
+
'',
|
|
324
|
+
'## 核心开发流程',
|
|
325
|
+
'',
|
|
326
|
+
'1. 初始化:`/hk-setup` → `/hk-init`(探测子工程、生成三层文档 + CodeGraph 索引)',
|
|
327
|
+
'2. 提案:`/hk-propose` → PM 调度 BA→SA→RR → 人工审批 1',
|
|
328
|
+
'3. 执行:`/hk-apply` → PM 调度 Dev→CR→TE → 人工审批 2',
|
|
329
|
+
'4. 归档:`/hk-archive` → Spec Merge + Memory Merge + 归档',
|
|
330
|
+
'',
|
|
331
|
+
'## 知识定位',
|
|
332
|
+
'',
|
|
333
|
+
'| 想知道什么 | 去哪看 |',
|
|
334
|
+
'|---|---|---|',
|
|
335
|
+
'| 子工程技术细节、框架模式 | `services/<子工程>/CLAUDE.md` |',
|
|
336
|
+
'| 编码规范 | `services/<子工程>/docs/CODE_STANDARDS.md` |',
|
|
337
|
+
'| 构建/启动/测试命令 | `services/<子工程>/.harness/build.json` |',
|
|
338
|
+
'| 已有系统能力 | `.harness/specs/_index.md` |',
|
|
339
|
+
'| 代码调用关系 | `codegraph explore <符号名>`(L3) |',
|
|
340
|
+
'',
|
|
341
|
+
].join('\n')],
|
|
342
|
+
// specs/_index.md 预置骨架:归档时 Spec Merge 更新;缺失时 BA/RR 的 specs 引用悬空。
|
|
343
|
+
['specs/_index.md', [
|
|
344
|
+
'# 系统能力索引',
|
|
345
|
+
'',
|
|
346
|
+
'> **Source of Truth**。按业务域分组。每次 `/hk-archive` 时由 PM 执行 Spec Merge 更新。',
|
|
347
|
+
'',
|
|
348
|
+
'## 业务域',
|
|
349
|
+
'',
|
|
350
|
+
'| 域 | Prefix | 能力 | 对应 spec | 实体 | API 前缀 | 最后更新 |',
|
|
351
|
+
'|----|--------|------|-----------|------|----------|---------|',
|
|
352
|
+
'<!-- 首个任务归档时由 Spec Merge 填入 -->',
|
|
353
|
+
'',
|
|
354
|
+
'## 跨域约束登记表',
|
|
355
|
+
'',
|
|
356
|
+
'> 每条 CSTR 指向已登记域码的 Requirement——此处只做指针编排,不复制行为。',
|
|
357
|
+
'',
|
|
358
|
+
'| CSTR | 约束描述 | 锚定 Requirement | 注册时间 |',
|
|
359
|
+
'|------|---------|-----------------|---------|',
|
|
360
|
+
'<!-- 按需登记 -->',
|
|
361
|
+
'',
|
|
362
|
+
'## 跨域流程',
|
|
363
|
+
'',
|
|
364
|
+
'> 跨域时序/状态机沉淀到 `_flows.md`(首个跨域流程归档时创建并在此登记指针)。',
|
|
365
|
+
'',
|
|
366
|
+
'<!-- 按需登记 -->',
|
|
367
|
+
'',
|
|
368
|
+
'(spec 文档格式见 [`spec-template.md`](spec-template.md):frontmatter + Requirement/Scenario 编号,id_max 不回收。)',
|
|
369
|
+
'',
|
|
370
|
+
].join('\n')],
|
|
371
|
+
// transient logs + pack 管理运行时 stay out of the assets repo (independent-repo layout)
|
|
372
|
+
['.gitignore', '.logs/**/*\n!.logs/**/\n!.logs/**/.gitkeep\n# pack 管理运行时(/hk-init 每次刷新,勿手改、勿提交)\nscripts/\n# 本机状态(各机独立,勿提交:会话绑定/续接点火/工作区分配/决策点/环境租约)\ntasks/sessions.json\ntasks/auto-advance.json\ntasks/worktrees.json\ntasks/decisions.json\ntasks/test-env.json\n'],
|
|
373
|
+
]) {
|
|
374
|
+
const abs = path.join(hd, file);
|
|
375
|
+
if (!fs.existsSync(abs)) {
|
|
376
|
+
fs.writeFileSync(abs, content, 'utf8');
|
|
377
|
+
created.push(`.harness/${file}`);
|
|
378
|
+
} else kept.push(`.harness/${file}`);
|
|
379
|
+
}
|
|
380
|
+
// 存量 .gitignore 补 scripts/ 排除(scripts 是 pack 管理运行时,不入资产仓库,§7 资产分层)
|
|
381
|
+
const giPath = path.join(hd, '.gitignore');
|
|
382
|
+
if (fs.existsSync(giPath) && !fs.readFileSync(giPath, 'utf8').split('\n').some((l) => l.trim() === 'scripts/')) {
|
|
383
|
+
fs.appendFileSync(giPath, '# pack 管理运行时(/hk-init 每次刷新,勿手改、勿提交)\nscripts/\n', 'utf8');
|
|
384
|
+
created.push('.harness/.gitignore(追加 scripts/ 排除)');
|
|
385
|
+
}
|
|
386
|
+
// 存量迁移:本机状态文件(会话绑定/续接点火/工作区分配/决策点/环境租约)不入资产库
|
|
387
|
+
const LOCAL_STATE = ['tasks/sessions.json', 'tasks/auto-advance.json', 'tasks/worktrees.json', 'tasks/decisions.json', 'tasks/test-env.json'];
|
|
388
|
+
if (fs.existsSync(giPath)) {
|
|
389
|
+
const cur = fs.readFileSync(giPath, 'utf8');
|
|
390
|
+
const missing = LOCAL_STATE.filter((e) => !cur.split('\n').some((l) => l.trim() === e));
|
|
391
|
+
if (missing.length > 0) {
|
|
392
|
+
fs.appendFileSync(giPath, `# 本机状态(各机独立,勿提交)\n${missing.join('\n')}\n`, 'utf8');
|
|
393
|
+
created.push('.harness/.gitignore(追加本机状态排除)');
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
// 1b. 内容包模板/规则物化(spec/memory 格式契约 + 跨端编码底线;create-only)
|
|
398
|
+
for (const [file, tpl] of [
|
|
399
|
+
['memory/templates/entry.md', 'memory-entry.md'],
|
|
400
|
+
['specs/spec-template.md', 'spec-template.md'],
|
|
401
|
+
]) {
|
|
402
|
+
const abs = path.join(hd, file);
|
|
403
|
+
if (fs.existsSync(abs)) {
|
|
404
|
+
kept.push(`.harness/${file}`);
|
|
405
|
+
continue;
|
|
406
|
+
}
|
|
407
|
+
const src = path.join(packDir(readKit(ws) ?? undefined), 'templates', tpl);
|
|
408
|
+
if (!fs.existsSync(src)) continue;
|
|
409
|
+
fs.mkdirSync(path.dirname(abs), { recursive: true });
|
|
410
|
+
fs.copyFileSync(src, abs);
|
|
411
|
+
created.push(`.harness/${file}`);
|
|
412
|
+
}
|
|
413
|
+
// .harness/rules/code-standards.md:CR/Dev 契约引用的跨端底线,随包分发(create-only,工程可自行加严)
|
|
414
|
+
{
|
|
415
|
+
const abs = path.join(hd, 'rules/code-standards.md');
|
|
416
|
+
if (fs.existsSync(abs)) kept.push('.harness/rules/code-standards.md');
|
|
417
|
+
else {
|
|
418
|
+
const src = path.join(packDir(readKit(ws) ?? undefined), 'rules', 'code-standards.md');
|
|
419
|
+
if (fs.existsSync(src)) {
|
|
420
|
+
fs.mkdirSync(path.dirname(abs), { recursive: true });
|
|
421
|
+
fs.copyFileSync(src, abs);
|
|
422
|
+
created.push('.harness/rules/code-standards.md');
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
// 2. kit.json + sources auto-scan fallback (services/*/)
|
|
428
|
+
let kit = readKit(ws);
|
|
429
|
+
if (!kit) {
|
|
430
|
+
kit = defaultKit();
|
|
431
|
+
created.push('.harness/kit.json');
|
|
432
|
+
}
|
|
433
|
+
const scanned = [];
|
|
434
|
+
const servicesDir = path.join(ws, 'services');
|
|
435
|
+
if (fs.existsSync(servicesDir)) {
|
|
436
|
+
for (const e of fs.readdirSync(servicesDir, { withFileTypes: true })) {
|
|
437
|
+
if (!e.isDirectory()) continue;
|
|
438
|
+
const rel = `services/${e.name}`;
|
|
439
|
+
if (kit.sources.some((s) => s.path === rel)) continue;
|
|
440
|
+
const abs = path.join(ws, rel);
|
|
441
|
+
if (!fs.existsSync(path.join(abs, '.git'))) continue;
|
|
442
|
+
const b = await runGit(['branch', '--show-current'], { cwd: abs });
|
|
443
|
+
kit.sources.push({ name: e.name, path: rel, role: guessRole(e.name), branch: b.code === 0 && b.stdout.trim() ? b.stdout.trim() : 'master' });
|
|
444
|
+
scanned.push(rel);
|
|
445
|
+
}
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
// 2b. resolve assets binding (--assets init runs here, after the skeleton exists)
|
|
449
|
+
const gitDir = path.join(hd, '.git');
|
|
450
|
+
const warnings = [];
|
|
451
|
+
if (fs.existsSync(gitDir)) {
|
|
452
|
+
if (!assetsBinding) {
|
|
453
|
+
const remote = await runGit(['remote', 'get-url', 'origin'], { cwd: hd });
|
|
454
|
+
const b = await runGit(['branch', '--show-current'], { cwd: hd });
|
|
455
|
+
const url = remote.code === 0 && remote.stdout.trim() ? remote.stdout.trim() : undefined;
|
|
456
|
+
assetsBinding = { mode: url ? 'clone' : 'init', ...(url ? { url } : {}), branch: b.stdout.trim() || 'master' };
|
|
457
|
+
}
|
|
458
|
+
} else if (assets === 'init') {
|
|
459
|
+
const r1 = await runGit(['init'], { cwd: hd });
|
|
460
|
+
if (r1.code !== 0) {
|
|
461
|
+
warnings.push(`git init 失败(exit ${r1.code}):${r1.stderr.trim() || r1.stdout.trim()}`);
|
|
462
|
+
assetsBinding = { mode: 'local' };
|
|
463
|
+
} else {
|
|
464
|
+
await runGit(['add', '-A'], { cwd: hd });
|
|
465
|
+
const rc = await runGit(['commit', '-m', 'harness: workspace init'], { cwd: hd });
|
|
466
|
+
if (rc.code !== 0) {
|
|
467
|
+
warnings.push(`首次 commit 失败(exit ${rc.code}):${(rc.stderr || rc.stdout).trim()} —— 请检查 git user.name/user.email 配置后手工 commit`);
|
|
468
|
+
} else {
|
|
469
|
+
created.push('.harness/.git(首次 commit 完成)');
|
|
470
|
+
}
|
|
471
|
+
const b = await runGit(['branch', '--show-current'], { cwd: hd });
|
|
472
|
+
assetsBinding = { mode: 'init', branch: b.stdout.trim() || 'master' };
|
|
473
|
+
}
|
|
474
|
+
} else {
|
|
475
|
+
assetsBinding = { mode: 'local' };
|
|
476
|
+
}
|
|
477
|
+
kit.assets = { ...(kit.assets ?? {}), ...assetsBinding };
|
|
478
|
+
writeKit(ws, kit);
|
|
479
|
+
|
|
480
|
+
// 2c. 面板初始化向导登记的代码仓库(等价于逐个 /hk-setup --add;clone 失败的单项转为警告继续)
|
|
481
|
+
const sourceReports = [];
|
|
482
|
+
for (const [i, spec] of sources.entries()) {
|
|
483
|
+
progress('克隆子工程', `${spec?.name || spec?.url || '?'}(${i + 1}/${sources.length})→ ${spec?.path || 'services/…'}`);
|
|
484
|
+
const r = await addSource(ws, spec);
|
|
485
|
+
sourceReports.push(r);
|
|
486
|
+
if (!r.ok) warnings.push(`子工程 ${spec?.url ?? spec?.name ?? '?'}:${r.error}`);
|
|
487
|
+
}
|
|
488
|
+
if (sources.length > 0) kit = readKit(ws) ?? kit;
|
|
489
|
+
|
|
490
|
+
// 迁移:scripts/ 曾入库的仓库摘除追踪(本地文件保留;摘除结果随下次 /hk-sync 推送生效)
|
|
491
|
+
if (fs.existsSync(gitDir)) {
|
|
492
|
+
const tracked = await runGit(['ls-files', 'scripts'], { cwd: hd });
|
|
493
|
+
if (tracked.code === 0 && tracked.stdout.trim()) {
|
|
494
|
+
const rm = await runGit(['rm', '-r', '--cached', '-q', 'scripts'], { cwd: hd });
|
|
495
|
+
if (rm.code === 0) created.push('scripts/ 已从资产仓库摘除追踪(本地文件保留,随 /hk-sync 生效)');
|
|
496
|
+
else warnings.push(`scripts/ 摘除追踪失败(exit ${rm.code}):${(rm.stderr || rm.stdout).trim()} —— 可手工 cd .harness && git rm -r --cached scripts`);
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
// 3. host instruction files: AGENTS.md canonical + CLAUDE.md pointer (never overwrite)
|
|
501
|
+
const agentsMd = path.join(ws, 'AGENTS.md');
|
|
502
|
+
if (!fs.existsSync(agentsMd)) {
|
|
503
|
+
const sourceLines = kit.sources.map((s) => `| ${s.name} | \`${s.path}\` | ${s.role} | ${s.branch} |`).join('\n');
|
|
504
|
+
fs.writeFileSync(
|
|
505
|
+
agentsMd,
|
|
506
|
+
[
|
|
507
|
+
'# 项目指南(Harness Kit 生成)',
|
|
508
|
+
'',
|
|
509
|
+
'本工作区由 Harness Kit 管理:多子工程协作、需求/设计/交付物与经验记忆全部沉淀在 `.harness/`。深入任何子工程前先查下表资源,不要凭猜测行动。',
|
|
510
|
+
'',
|
|
511
|
+
'## 子工程地图',
|
|
512
|
+
'',
|
|
513
|
+
'| 名称 | 路径 | 角色 | 分支 |',
|
|
514
|
+
'|---|---|---|---|',
|
|
515
|
+
sourceLines || '| (待 /hk-setup 登记) | | | |',
|
|
516
|
+
'',
|
|
517
|
+
'## 工作区资源(.harness/)',
|
|
518
|
+
'',
|
|
519
|
+
'| 资源 | 位置 | 说明 |',
|
|
520
|
+
'|---|---|---|',
|
|
521
|
+
'| 协作契约 | `.harness/kit.json` | pack、资产仓库绑定、子工程清单 |',
|
|
522
|
+
'| 系统能力索引 | `.harness/specs/_index.md` | 已有需求能力(Source of Truth) |',
|
|
523
|
+
'| 架构总览 | `.harness/codebase-guide/overview.md` | 技术栈、目录结构、子工程关系 |',
|
|
524
|
+
'| 知识路由 | `.harness/codebase-guide/index.md` | L1/L2/L3 三层知识模型与角色路由 |',
|
|
525
|
+
'| 任务看板 | `.harness/tasks/board.md` | 当前任务与质量门状态 |',
|
|
526
|
+
'| 经验记忆 | `.harness/memory/index.md` | 历史坑与流程优化条目 |',
|
|
527
|
+
'| 编码底线 | `.harness/rules/code-standards.md` | 跨端编码红线 |',
|
|
528
|
+
'| 交付物 | `.harness/deliverables/<任务>/` | 提案、需求、设计、测试报告 |',
|
|
529
|
+
'',
|
|
530
|
+
'## 构建与运行',
|
|
531
|
+
'',
|
|
532
|
+
'各子工程的编译/启动/测试命令以其自身 `services/<子工程>/.harness/build.json` 为唯一权威来源,本文件不重复登记。',
|
|
533
|
+
'统一执行入口(自动解析运行时环境):`python3 .harness/scripts/harness.py run-field <子工程> compile|start|stop|test`。',
|
|
534
|
+
'',
|
|
535
|
+
'## 红线',
|
|
536
|
+
'',
|
|
537
|
+
'- 规划阶段(质量门未裁决)禁止修改 services/ 下子工程与 e2e/ 源码。',
|
|
538
|
+
'- 范围/口径/验收模糊时必须向人反问,禁止 AI 自行补全。',
|
|
539
|
+
'',
|
|
540
|
+
].join('\n'),
|
|
541
|
+
'utf8',
|
|
542
|
+
);
|
|
543
|
+
created.push('AGENTS.md');
|
|
544
|
+
} else kept.push('AGENTS.md');
|
|
545
|
+
|
|
546
|
+
const claudeMd = path.join(ws, 'CLAUDE.md');
|
|
547
|
+
if (!fs.existsSync(claudeMd)) {
|
|
548
|
+
fs.writeFileSync(claudeMd, 'See @AGENTS.md\n', 'utf8');
|
|
549
|
+
created.push('CLAUDE.md(指针薄壳)');
|
|
550
|
+
} else kept.push('CLAUDE.md(已存在,未改动)');
|
|
551
|
+
|
|
552
|
+
// 4. materialize init assets from the pack — scripts 是 pack 管理运行时(不入库,每次刷新覆盖);
|
|
553
|
+
// templates 是播种资产(项目可裁剪,create-only 不覆盖)
|
|
554
|
+
for (const [srcDir, dstDir, label, managed] of [
|
|
555
|
+
[path.join(packDir(kit), 'assets', 'scripts'), path.join(hd, 'scripts'), 'scripts', true],
|
|
556
|
+
[path.join(packDir(kit), 'assets', 'templates'), path.join(hd, 'templates'), 'templates', false],
|
|
557
|
+
]) {
|
|
558
|
+
if (!fs.existsSync(srcDir)) continue;
|
|
559
|
+
const { added, existed, updated } = copyNew(srcDir, dstDir, managed);
|
|
560
|
+
if (managed) {
|
|
561
|
+
if (added > 0 || updated > 0) created.push(`.harness/${label}/(pack 刷新:新增 ${added}、更新 ${updated}${existed ? `、未变 ${existed}` : ''})`);
|
|
562
|
+
else kept.push(`.harness/${label}/(${existed} 个文件与 pack 一致)`);
|
|
563
|
+
} else if (added > 0) created.push(`.harness/${label}/(物化 ${added} 个文件${existed ? `,保留已有 ${existed} 个` : ''})`);
|
|
564
|
+
else if (existed > 0) kept.push(`.harness/${label}/(${existed} 个文件已存在,未改动)`);
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
// 4b. 空远端接管收尾:骨架 + 物化完成后整体首次提交并 push -u
|
|
568
|
+
let attachPushed = false;
|
|
569
|
+
if (attachPending) {
|
|
570
|
+
await runGit(['add', '-A'], { cwd: hd });
|
|
571
|
+
const rc = await runGit(['commit', '-m', 'harness: 初始资产导入'], { cwd: hd });
|
|
572
|
+
if (rc.code !== 0) {
|
|
573
|
+
warnings.push(`初始提交失败(exit ${rc.code}):${(rc.stderr || rc.stdout).trim()} —— 请检查 git user.name/user.email 配置后运行 \`/hk-sync\` 完成提交与推送`);
|
|
574
|
+
} else {
|
|
575
|
+
const rp = await runGit(['push', '-u', 'origin', assetsBinding.branch], { cwd: hd, timeoutMs: 600_000 });
|
|
576
|
+
if (rp.code !== 0) {
|
|
577
|
+
warnings.push(`push 失败(exit ${rp.code}):${(rp.stderr || rp.stdout).trim()} —— 修复后运行 \`/hk-sync\` 重试推送`);
|
|
578
|
+
} else {
|
|
579
|
+
attachPushed = true;
|
|
580
|
+
created.push('.harness/ 首次提交已推送到空远端');
|
|
581
|
+
}
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
progress('完成', '骨架/子工程/脚本已就绪');
|
|
586
|
+
return { ok: true, created, kept, scanned, warnings, assetsBinding, attachPending, attachPushed, kit, sourceReports };
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
/** 将 runInit 结果格式化为 /hk-init 的完成汇报文本(CLI 与面板共用口径)。 */
|
|
590
|
+
export function formatInitReport(r, { steered = false } = {}) {
|
|
591
|
+
const { created, kept, scanned, warnings, assetsBinding, attachPending, attachPushed, kit } = r;
|
|
592
|
+
const lines = ['## /hk-init 完成', ''];
|
|
593
|
+
if (created.length) lines.push(`新建:${created.map((c) => `\`${c}\``).join('、')}`);
|
|
594
|
+
if (kept.length) lines.push(`保留(幂等):${kept.map((c) => `\`${c}\``).join('、')}`);
|
|
595
|
+
if (scanned.length) lines.push(`自动探测源码仓库:${scanned.map((s) => `\`${s}\``).join('、')}(已写入 kit.json sources)`);
|
|
596
|
+
lines.push(
|
|
597
|
+
`资产仓库:${
|
|
598
|
+
assetsBinding.mode === 'clone'
|
|
599
|
+
? attachPending
|
|
600
|
+
? attachPushed
|
|
601
|
+
? `🔗 已有资产接管空远端 \`${assetsBinding.url}\`(分支 \`${assetsBinding.branch}\`,首次提交已推送)`
|
|
602
|
+
: `🔗 已有资产接管空远端 \`${assetsBinding.url}\`(分支 \`${assetsBinding.branch}\`,⚠️ 推送未完成,见上方警告)`
|
|
603
|
+
: `🔗 已绑定远端 \`${assetsBinding.url}\`(分支 \`${assetsBinding.branch}\`)`
|
|
604
|
+
: assetsBinding.mode === 'init'
|
|
605
|
+
? `📦 本地 git 仓库(分支 \`${assetsBinding.branch}\`,尚无远端;建好远端后 \`cd .harness && git remote add origin <url> && git push -u\`)`
|
|
606
|
+
: '📁 本地模式(未绑 git);有团队资产仓库请在新工作区用 `/hk-init --assets <url>`,或新建仓库用 `/hk-init --assets init`'
|
|
607
|
+
}`,
|
|
608
|
+
);
|
|
609
|
+
for (const w of warnings) lines.push(`⚠️ ${w}`);
|
|
610
|
+
if (kit.sources.length === 0) lines.push('', '⚠️ 尚未登记任何代码仓库:先 `/hk-setup --add <url>`。');
|
|
611
|
+
else if (steered) lines.push('', '初始化剧本已提交 PM:探测子工程 → 计划展示 → ⛔人确认 → 生成文档/索引 → 校验诊断。');
|
|
612
|
+
else lines.push('', '⚠️ 未找到 init 流程定义(packs/ai-coding/flows/init.yml),跳过子工程文档生成编排。');
|
|
613
|
+
return lines.join('\n');
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/**
|
|
617
|
+
* 目录预检(打开/新建工作区向导共用):
|
|
618
|
+
* 是否存在、是否目录、是否 Harness 工作区(.harness/kit.json)、kit 摘要。
|
|
619
|
+
*/
|
|
620
|
+
export function inspectDir(wsPath) {
|
|
621
|
+
const out = { path: typeof wsPath === 'string' ? wsPath.trim() : '', exists: false, isDir: false, hasHarness: false, hasKit: false, pack: null, sourceCount: 0, assetsMode: null, kitError: null };
|
|
622
|
+
if (!out.path) return out;
|
|
623
|
+
if (!fs.existsSync(out.path)) return out;
|
|
624
|
+
out.exists = true;
|
|
625
|
+
try {
|
|
626
|
+
out.isDir = fs.statSync(out.path).isDirectory();
|
|
627
|
+
} catch {
|
|
628
|
+
return out;
|
|
629
|
+
}
|
|
630
|
+
if (!out.isDir) return out;
|
|
631
|
+
out.hasHarness = fs.existsSync(harnessDir(out.path));
|
|
632
|
+
out.hasKit = fs.existsSync(kitPath(out.path));
|
|
633
|
+
if (out.hasKit) {
|
|
634
|
+
try {
|
|
635
|
+
const kit = readKit(out.path);
|
|
636
|
+
out.pack = kit?.pack ?? null;
|
|
637
|
+
out.sourceCount = Array.isArray(kit?.sources) ? kit.sources.length : 0;
|
|
638
|
+
out.assetsMode = kit?.assets?.mode ?? 'local';
|
|
639
|
+
} catch (cause) {
|
|
640
|
+
out.kitError = cause.message;
|
|
641
|
+
}
|
|
642
|
+
}
|
|
643
|
+
return out;
|
|
644
|
+
}
|