@rowansenne/workflow-run 0.26.1 → 0.27.0

package/workflow/lib/project.mjs

@@ -0,0 +1,218 @@
+// 项目布局与配置；不依赖需求写入或任何命令入口。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const INSTALL_BASES = ['.agents/skills', '.claude/skills', '.qwen/skills', '.codebuddy/skills'];
+const git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const toPosix = (p) => p.split(path.sep).join('/');
+const relOf = (root, abs) => toPosix(path.relative(root, abs));
+
+// 本工具在项目里的唯一目录
+export const HOME = 'workflow-run';
+export const REQ_DIR = `${HOME}/docs/requirements`;
+export const TEMPLATES_DIR = `${HOME}/templates`;
+export const TMP_DIR = `${HOME}/tmp`;
+export const IGNORE_LINE = `${HOME}/docs/`;
+export const homeDir = (root) => path.join(root, HOME);
+// workflow-run/ 自己是 git 仓库（团队文档仓库克隆到这里）= 独立文档仓库模式
+export const homeIsRepo = (root) => fs.existsSync(path.join(root, HOME, '.git'));
+// 产物种类 → 需求目录里的文件名（只放最新版 <base>.md；版本号在 meta.json 的 versions，旧版归档为 <base>_v<N>.md）
+// 需求名 / 项目名 → 目录名：保留中文，去掉路径与文件系统不允许的字符，空白换成 -
+export function dirName(name) {
+  const s = String(name).normalize('NFC').trim()
+    .replace(/[\\/:*?"<>|#%{}^~[\]`'$&@!=+,;]+/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '');
+  return [...s].slice(0, 60).join('') || 'unnamed';
+}
+
+// ------------------------------------------------------------------ 配置与布局
+// 画像所在目录：本脚本所在的 skills 目录；从安装包调用时（安装器）到项目里已安装的 skills 目录找
+export function profileDir(root) {
+  const own = path.join(SKILLS_DIR, 'workflow');
+  if (fs.existsSync(path.join(own, 'profile.json')) || fs.existsSync(path.join(own, 'profile.local.json'))) return own;
+  for (const b of INSTALL_BASES) { const d = path.join(root, b, 'workflow'); if (fs.existsSync(path.join(d, 'profile.json'))) return d; }
+  return own;
+}
+
+// workflow/profile.json 的 artifacts，profile.local.json（个人设置，不提交）覆盖其上
+export function artifactsConfig(root) {
+  const dir = profileDir(root);
+  const team = readJson(path.join(dir, 'profile.json'))?.artifacts ?? {};
+  const mine = readJson(path.join(dir, 'profile.local.json'))?.artifacts ?? {};
+  const c = { ...team, ...mine };
+  return { project: c.project ? String(c.project) : '', commit_prompt: c.commit_prompt !== false, profile_dir: dir };
+}
+
+// 产物位置：两种模式都是 workflow-run/docs/requirements/<需求>/<项目>/。
+// mode 只决定谁来提交（project = 随代码提交，repo = workflow-run/ 是独立的文档仓库）、引用怎么写、项目名能不能自动取
+export function layout(root, cfg = artifactsConfig(root)) {
+  const home = homeDir(root);
+  const base = path.join(root, REQ_DIR);
+  if (!homeIsRepo(root)) {
+    const project = cfg.project ? dirName(cfg.project) : suggestProject(root);
+    return { mode: 'project', ok: true, base, home, repo: null, project, project_configured: !!cfg.project, commit_prompt: cfg.commit_prompt, reqDir: (slug) => path.join(base, slug, project), ref: (abs) => relOf(root, abs) };
+  }
+  const repoName = remoteName(home);
+  const L = { mode: 'repo', base, home, repo: home, repo_rel: HOME, repo_name: repoName, project: cfg.project ? dirName(cfg.project) : null, project_configured: !!cfg.project, commit_prompt: cfg.commit_prompt };
+  L.reqDir = (slug) => path.join(base, slug, L.project ?? '_');
+  // 文档里引用产物用「文档仓库名:仓库内路径」，各服务、各人的克隆里都一样
+  L.ref = (abs) => `${repoName}:${toPosix(path.relative(home, abs))}`;
+  if (!L.project) return { ...L, ok: false, need_project: true, suggested_project: suggestProject(root), hint: '文档仓库模式需要项目名（产物放在 workflow-run/docs/requirements/<需求名>/<项目名>/），只需配置一次：问用户这个项目在文档仓库里叫什么（默认 suggested_project），然后运行 config --project <项目名>' };
+  return { ...L, ok: true };
+}
+
+// 文档仓库名：它的 git 远端仓库名，没有远端时用 workflow-run
+const remoteNames = new Map();
+function remoteName(home) {
+  if (!remoteNames.has(home)) {
+    const url = git(home, ['remote', 'get-url', 'origin']).stdout?.trim();
+    remoteNames.set(home, url ? url.replace(/[/\\]+$/, '').replace(/\.git$/, '').split(/[/\\:]/).pop() || HOME : HOME);
+  }
+  return remoteNames.get(home);
+}
+
+// 项目名建议：git 远端仓库名，取不到用项目目录名
+export function suggestProject(root) {
+  const url = git(root, ['remote', 'get-url', 'origin']).stdout?.trim();
+  const name = url ? url.replace(/[/\\]+$/, '').replace(/\.git$/, '').split(/[/\\:]/).pop() : path.basename(path.resolve(root));
+  return dirName(name);
+}
+
+export function setConfig(root, patch, { local = false } = {}) {
+  const dir = profileDir(root);
+  const f = path.join(dir, local ? 'profile.local.json' : 'profile.json');
+  const cur = readJson(f) ?? {};
+  const a = { ...(cur.artifacts ?? {}) };
+  if (patch.project !== undefined) a.project = dirName(patch.project);
+  if (patch.commit_prompt !== undefined) a.commit_prompt = patch.commit_prompt;
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(f, `${JSON.stringify({ ...cur, artifacts: a }, null, 2)}\n`);
+  const L = layout(root);
+  return { file: relOf(root, f), artifacts: a, effective: { mode: L.mode, repo: L.repo_rel ?? null, project: L.project, commit_prompt: L.commit_prompt, ok: L.ok, hint: L.ok ? null : L.hint } };
+}
+
+// .ignore 里加上需求目录（ripgrep 与 agent 的搜索跳过它；git 不受影响）。返回是否改动
+export function ensureIgnore(root) {
+  const f = path.join(root, '.ignore');
+  const text = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
+  const norm = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
+  if (text.split(/\r?\n/).some((l) => norm(l) === norm(IGNORE_LINE))) return false;
+  const add = `# workflow-run：需求产物（方案、交付说明、审查报告、技术 / 上线方案）不参与代码搜索，检索交给 DocNexus\n${IGNORE_LINE}\n`;
+  fs.writeFileSync(f, text ? `${text.replace(/\s*$/, '')}\n\n${add}` : add);
+  return true;
+}
+
+
+const PROFILE_FIELDS = ['main_branch', 'build', 'test', 'test_single', 'lint', 'config_center', 'deploy.platform', 'deploy.regions', 'job_annotation'];
+const PROFILE_REQUIRED = ['main_branch', 'build', 'test'];
+
+const OS_NAMES = { win32: 'windows', darwin: 'macos', linux: 'linux' };
+export function detectEnv() {
+  const os = OS_NAMES[process.platform] ?? process.platform;
+  let shell;
+  if (process.platform === 'win32') {
+    shell = spawnSync('pwsh', ['-NoProfile', '-NonInteractive', '-Command', 'exit 0'], { stdio: 'ignore', timeout: 15000 }).status === 0 ? 'pwsh' : 'powershell';
+  } else shell = path.basename(process.env.SHELL || 'sh');
+  return { os, shell };
+}
+// 终端的写法提示：PowerShell 5.1 没有 && / ||，pwsh 7 有
+export const SHELL_NOTES = {
+  powershell: 'Windows PowerShell 5.1：没有 && 和 ||，多条命令用 ; 分开；不要用 2>/dev/null、grep、head 等 Unix 命令',
+  pwsh: 'PowerShell 7：支持 &&；不要用 2>/dev/null、grep、head 等 Unix 命令',
+};
+export function readEnv() {
+  const rec = readJson(path.join(SKILLS_DIR, 'workflow', 'profile.local.json'))?.env;
+  const env = rec?.os ? { os: rec.os, shell: rec.shell ?? null, source: 'install' } : { os: OS_NAMES[process.platform] ?? process.platform, shell: null, source: 'runtime' };
+  const note = SHELL_NOTES[env.shell];
+  return { ...env, ...(note ? { note } : {}) };
+}
+
+// 开发环境配置（toolchain）：画像里的路径可能写 $JAVA_HOME / ${VAR} / %VAR% / ~，用 env_vars 与进程环境展开。
+// env_vars 优先（画像里显式声明的是对的），缺失的键回退到本机进程环境（HOME、USERPROFILE 这类）。
+// 展开后为空 = 变量确实没配（不是「留空」，要报出来）；路径里有空格照常，不做 shell 求值。
+const VAR_RE = /\$\{(\w+)\}|\$(\w+)|%(\w+)%/g;
+export function expandPath(v, vars = {}, env = process.env) {
+  if (typeof v !== 'string' || !v) return { raw: v ?? '', resolved: '', missing: [] };
+  const look = (n) => (vars[n] !== undefined && vars[n] !== '' ? vars[n] : (env[n] ?? ''));
+  const home = look('HOME') || look('USERPROFILE') || '';
+  let s = v;
+  if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = home ? home + s.slice(1) : s;
+  const missing = [];
+  for (const m of v.matchAll(VAR_RE)) { const n = m[1] ?? m[2] ?? m[3]; if (!look(n)) missing.push(n); }
+  const resolved = s.replace(VAR_RE, (m, a, b, c) => look(a ?? b ?? c)).replace(/[\\/]+$/, '');
+  return { raw: v, resolved, missing };
+}
+
+// 画像里的 toolchain（profile.json）与个人覆盖（profile.local.json），逐个子字段合并，后者优先。
+// 「没声明」和「显式写空」是两回事：本机写 "" 表示**不使用**团队那个值（用工具自己的默认配置），
+// 所以要按 null / "" 区分来源，不能只看值真不真。
+export function readToolchain(root) {
+  const dir = path.join(SKILLS_DIR, 'workflow');
+  const team = readJson(path.join(dir, 'profile.json')) ?? {};
+  const mine = readJson(path.join(dir, 'profile.local.json')) ?? {};
+  const declared = (o) => typeof o === 'string';
+  // 个人声明过（含 ""）就以个人为准；否则用团队值。cleared 表示被个人显式留空
+  const merge = (t, m) => {
+    if (declared(m)) return m === '' ? { value: '', source: 'local', cleared: true } : { value: m, source: 'local' };
+    if (declared(t) && t !== '') return { value: t, source: 'team' };
+    return { value: '', source: null };
+  };
+  const vars = { ...(team.env_vars ?? {}), ...(mine.env_vars ?? {}) };
+  const fields = {
+    java_home: merge(team.toolchain?.java_home, mine.toolchain?.java_home),
+    'maven.settings': merge(team.toolchain?.maven?.settings, mine.toolchain?.maven?.settings),
+    'maven.repository': merge(team.toolchain?.maven?.repository, mine.toolchain?.maven?.repository),
+    gradle_user_home: merge(team.toolchain?.gradle_user_home, mine.toolchain?.gradle_user_home),
+    node: merge(team.toolchain?.node, mine.toolchain?.node),
+  };
+  const out = {};
+  const cleared = [];
+  for (const [k, { value, source, cleared: c }] of Object.entries(fields)) {
+    if (c) { cleared.push(k); continue; } // 个人明确不用这个字段：不展开、不校验、也不报缺失
+    if (value) out[k] = { ...expandPath(value, vars), source };
+  }
+  // toolchain 为空时也给出 env_vars，便于 agent 知道该用什么变量写路径
+  return { fields: out, env_vars: vars, cleared, configured: Object.keys(out).length > 0 };
+}
+
+// 每个字段的路径在本机是否存在（写入画像前、构建跑不起来时核对用）。
+// 只判断存在性，不判断版本对不对；current 是本机当前进程的值，便于和画像对照
+export function checkToolchain(root, { env = process.env } = {}) {
+  const tc = readToolchain(root);
+  const check = (f) => {
+    // 变量没配时展开结果可能是别处真存在的路径（$MISSING/bin 展开成 /bin），必须按「没配」算不通过
+    let exists = false;
+    try { exists = !f.missing.length && !!f.resolved && fs.existsSync(f.resolved); } catch { exists = false; }
+    const kind = exists ? (() => { try { return fs.statSync(f.resolved).isDirectory() ? 'dir' : 'file'; } catch { return 'other'; } })() : null;
+    return { ...f, exists, kind, ...(f.missing.length ? { unset_vars: f.missing } : {}), ...(f.raw !== f.resolved ? { expanded: true } : {}) };
+  };
+  const fields = Object.fromEntries(Object.entries(tc.fields).map(([k, f]) => [k, check(f)]));
+  const bad = Object.entries(fields).filter(([, f]) => !f.exists).map(([k]) => k);
+  return {
+    fields, configured: tc.configured, env_vars: tc.env_vars, ok: bad.length === 0,
+    missing: bad,
+    // 个人在 profile.local.json 里显式留空、表示不用团队那个值的字段（用工具默认配置）
+    ...(tc.cleared.length ? { cleared: tc.cleared } : {}),
+    // 本机当前值：和画像对不上时，多半是画像抄的是别人的机器
+    current: { JAVA_HOME: env.JAVA_HOME ?? null, MAVEN_HOME: env.MAVEN_HOME ?? null, GRADLE_USER_HOME: env.GRADLE_USER_HOME ?? null, node: path.dirname(process.execPath) },
+    how: tc.configured ? (bad.length ? `核对 toolchain 里不存在或变量没配的字段：${bad.join('、')}（本机值见 current）；改本机的那份用 profile.local.json，见 workflow/references/profile.md` : null) : '还没有配置开发环境：运行 /workflow profile 由脚本推断后确认，见 workflow/references/profile.md',
+  };
+}
+
+export function readProfile(root) {
+  const f = path.join(SKILLS_DIR, 'workflow', 'profile.json');
+  const profile = readJson(f);
+  const get = (k) => k.split('.').reduce((o, p) => (o == null ? undefined : o[p]), profile);
+  const isEmpty = (v) => v == null || v === '' || (Array.isArray(v) && !v.length);
+  const empty = profile ? PROFILE_FIELDS.filter((k) => isEmpty(get(k))) : PROFILE_FIELDS;
+  return {
+    path: relOf(root, f), exists: !!profile, profile: profile ?? {}, empty, env: readEnv(), toolchain: readToolchain(root),
+    complete: !!profile && PROFILE_REQUIRED.every((k) => !empty.includes(k)),
+  };
+}

package/workflow/lib/requirement-read.mjs

@@ -0,0 +1,68 @@
+// 需求目录读取与查询；不写索引或运行状态。
+import fs from 'node:fs';
+import path from 'node:path';
+import { layout } from './project.mjs';
+import { FILES, parseFile } from './artifact-model.mjs';
+import { readMeta } from './meta-store.mjs';
+
+const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
+const directories = (dir) => fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('.'));
+
+export function readRequirementDirectories(root, L = layout(root), { allProjects = false, diagnostics = [] } = {}) {
+  if ((!allProjects && !L.ok && L.mode === 'repo') || !fs.existsSync(L.base)) return [];
+  const out = [];
+  for (const req of directories(L.base)) {
+    for (const project of directories(path.join(L.base, req.name))) {
+      if (!allProjects && project.name !== L.project) continue;
+      const abs = path.join(L.base, req.name, project.name);
+      const file = path.join(abs, 'meta.json');
+      let meta = {}; let valid = true;
+      try {
+        meta = readMeta(file);
+        if ((meta.branches !== undefined && (!Array.isArray(meta.branches) || meta.branches.some((b) => typeof b !== 'string')))
+          || (meta.runs !== undefined && (!meta.runs || typeof meta.runs !== 'object' || Array.isArray(meta.runs)))) throw new Error(`无效的需求绑定或运行记录：${file}`);
+      } catch (e) {
+        diagnostics.push({ code: 'invalid_meta', path: relative(root, file), message: e.message });
+        meta = {}; valid = false;
+      }
+      out.push({ abs, dir: relative(root, abs), slug: req.name, project: project.name, name: meta.name ?? req.name,
+        branches: meta.branches ?? [], updated: meta.updated ?? null, meta, valid });
+    }
+  }
+  return out;
+}
+
+export function requirements(root, L = layout(root)) {
+  return readRequirementDirectories(root, L).map(({ dir, abs, slug, name, branches, updated, meta }) => ({ dir, abs, slug, name, branches, updated, meta }));
+}
+
+export function groupRequirements(dirs) {
+  const groups = new Map();
+  for (const d of dirs) {
+    if (!groups.has(d.slug)) groups.set(d.slug, []);
+    groups.get(d.slug).push(d);
+  }
+  return [...groups].map(([slug, rows]) => ({ slug, name: rows.map((d) => d.meta.name).find(Boolean) ?? slug,
+    updated: rows.map((d) => d.updated ?? '').sort().at(-1) || null,
+    projects: rows.map(({ project, abs, dir, meta }) => ({ project, abs, dir, meta })) }));
+}
+
+export function repoRequirements(root, L = layout(root)) {
+  return groupRequirements(readRequirementDirectories(root, L, { allProjects: true }));
+}
+
+export function artifactFiles(root, { allProjects = false } = {}) {
+  const L = layout(root);
+  return readRequirementDirectories(root, L, { allProjects }).flatMap((d) => fs.readdirSync(d.abs).flatMap((name) => {
+    const p = parseFile(name);
+    if (!p) return [];
+    const abs = path.join(d.abs, name);
+    return [{ abs, rel: relative(root, abs), cite: L.ref(abs), slug: d.slug, project: d.project, ...p,
+      ...(name === `${FILES[p.kind]}.md` ? { version: d.meta.versions?.[p.kind] ?? 1 } : {}) }];
+  }));
+}
+
+export function find(root, branch, L = layout(root)) {
+  return requirements(root, L).filter((r) => r.branches.includes(branch))
+    .sort((a, b) => String(b.updated).localeCompare(String(a.updated)))[0] ?? null;
+}

package/workflow/lib/requirements.mjs

@@ -0,0 +1,219 @@
+// 需求绑定、产物版本与索引写入；调用只读查询和底层原子存储。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { updateMeta } from './meta-store.mjs';
+import { FILES, LABELS, parseFile, parseBranch, parseWiki, parseDocnexus, headerDate } from './artifact-model.mjs';
+import { HOME, REQ_DIR, TMP_DIR, dirName, profileDir, layout, setConfig } from './project.mjs';
+import { requirements, repoRequirements, find } from './requirement-read.mjs';
+import { loadWorkspace } from './workspace-read.mjs';
+const git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const relOf = (root, abs) => path.relative(root, abs).split(path.sep).join('/');
+const toPosix = (p) => p.split(path.sep).join('/');
+const now = () => new Date().toISOString();
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const skipDir = (d) => !d.isDirectory() || d.name.startsWith('.');
+
+// 同种产物只留最新版，文件名固定（review.md、tech-doc.md …），文档里的引用不会失效。版本号记在 meta.json 的 versions。
+// path 时把当前版复制到 workflow-run/tmp/old-artifacts/<需求目录（相对 requirements/）>/<种类>_v<N>.md（不提交），
+// 写完 sync <path> 时新版内容和这份副本不同才算新版本（versions 加一）；没写就放弃的话版本号不变
+export const OLD_DIR = `${TMP_DIR}/old-artifacts`;
+const archivePath = (root, dirAbs, kind, v) => path.join(root, OLD_DIR, path.relative(path.join(root, REQ_DIR), dirAbs), `${FILES[kind]}_v${v}.md`);
+const versionsOf = (dirAbs) => readJson(path.join(dirAbs, 'meta.json'))?.versions ?? {};
+
+// 按目录里的文件重建 meta.json（保留需求名、分支、创建时间）
+// bump：写完新版后（sync <path>）确认新版本——和 path 时归档的上一版副本内容不同就把版本号加一，返回归档了哪些
+export function sync(root, dirRel, { bump = false } = {}) {
+  const dir = path.resolve(root, dirRel);
+  const f = path.join(dir, 'meta.json');
+  const archived = [];
+  const result = updateMeta(f, (old) => {
+    const versions = { ...(old.versions ?? {}) };
+    if (bump) {
+      for (const kind of Object.keys(FILES)) {
+        const cur = path.join(dir, `${FILES[kind]}.md`);
+        const v = versions[kind] ?? 1;
+        const arc = archivePath(root, dir, kind, v);
+        if (!fs.existsSync(cur) || !fs.existsSync(arc) || fs.readFileSync(arc).equals(fs.readFileSync(cur))) continue;
+        versions[kind] = v + 1;
+        archived.push({ kind, version: v, file: relOf(root, arc) });
+      }
+    }
+    const artifacts = fs.readdirSync(dir).map((name) => {
+      const p = parseFile(name);
+      if (!p) return null;
+      const text = fs.readFileSync(path.join(dir, name), 'utf8');
+      return { kind: p.kind, version: name === `${FILES[p.kind]}.md` ? versions[p.kind] ?? 1 : p.version, file: name, branch: parseBranch(text), date: headerDate(text), wiki: parseWiki(text), docnexus: parseDocnexus(text) };
+    }).filter(Boolean).sort((a, b) => Object.keys(FILES).indexOf(a.kind) - Object.keys(FILES).indexOf(b.kind) || a.version - b.version);
+    const branches = old.branches ?? []; // 绑定只由 bind 更新；文档头不隐式修改需求归属。
+    const latest = Object.fromEntries(Object.keys(FILES).map((k) => [k, artifacts.filter((a) => a.kind === k).at(-1)?.file ?? null]));
+    // 内容没变就不写（meta.json 随需求目录提交，避免无谓的改动）；产物有变化才更新 updated
+    const changed = JSON.stringify(old.artifacts ?? null) !== JSON.stringify(artifacts) || JSON.stringify(old.branches ?? null) !== JSON.stringify(branches);
+    const meta = {
+      ...old,
+      name: old.name ?? path.basename(dir), named_by: old.named_by ?? 'user', ...(old.project ? { project: old.project } : {}), branches, base: old.base ?? null,
+      created: old.created ?? now(), updated: changed || !old.updated ? now() : old.updated, latest, ...(Object.keys(versions).length ? { versions } : {}), artifacts,
+    };
+    return meta;
+  }, { root });
+  return bump ? { ...result, archived } : result;
+}
+
+const notReady = (L) => ({ ok: false, mode: L.mode, ...(L.need_project ? { need_project: true, suggested_project: L.suggested_project } : {}), hint: L.hint });
+
+export function which(root, branch) {
+  const L = layout(root);
+  if (!L.ok) return notReady(L);
+  const r = find(root, branch, L);
+  const where = L.mode === 'repo' ? { mode: 'repo', repo: L.repo_rel, project: L.project } : { mode: 'project', project: L.project };
+  if (r) return { bound: true, ...where, branch, name: r.name, dir: r.dir, meta: sync(root, r.dir) };
+  const recent = requirements(root, L).sort((a, b) => String(b.updated).localeCompare(String(a.updated))).slice(0, 5).map(({ name, dir, branches, updated }) => ({ name, dir, branches, updated }));
+  // 其他项目已有的需求（跨服务需求，本项目可以用同一个名字加入）；文档仓库里常见，随代码提交时一般没有
+  const mine = new Set(requirements(root, L).map((x) => x.slug));
+  const others = repoRequirements(root, L).filter((x) => !mine.has(x.slug)).sort((a, b) => String(b.updated).localeCompare(String(a.updated))).slice(0, 10).map((x) => ({ name: x.name, projects: x.projects.map((p) => p.project), updated: x.updated }));
+  return {
+    bound: false, ...where, branch, suggested_name: branch ? dirName(branch.replace(/\//g, '-')) : null, recent, ...(others.length || L.mode === 'repo' ? { other_projects: others } : {}),
+    hint: `当前分支还没有绑定需求：问用户这个需求叫什么（给出 suggested_name 作为默认；也可以选 recent 里已有的需求继续${others.length || L.mode === 'repo' ? '，或加入 other_projects 里其他服务已有的需求' : ''}），然后运行 bind --name <需求名>；用户不给就运行 bind（按分支名生成）。`,
+  };
+}
+
+export function bind(root, { name = null, branch, base = null }) {
+  const L = layout(root);
+  if (!L.ok) return notReady(L);
+  if (!branch) return { ok: false, error: '无法确定当前分支（detached HEAD？），请用 --branch 指定' };
+  const named = name != null && String(name).trim() !== '';
+  const display = named ? String(name).trim() : branch.replace(/\//g, '-');
+  // 同名需求沿用（按所有项目找，跨服务的需求共用一个目录）；目录名被别的需求占了就加 -2、-3
+  const pool = repoRequirements(root, L).map((r) => ({ slug: r.slug, name: r.name }));
+  const target = pool.find((r) => r.name === display) ?? null;
+  let slug = target?.slug;
+  if (!slug) {
+    slug = dirName(display);
+    for (let i = 2; pool.some((r) => r.slug === slug) || isDir(L.reqDir(slug)); i++) slug = `${dirName(display)}-${i}`;
+  }
+  // 随代码提交时项目名是自动取的：第一次落盘时写进 profile.json 固定下来，之后改了 git 远端名也不会换目录
+  // （只在项目里装过 skills、有 profile.json 时写；直接从安装包运行脚本时不写）
+  if (!L.project_configured && fs.existsSync(path.join(profileDir(root), 'profile.json'))) setConfig(root, { project: L.project });
+  const dir = L.reqDir(slug);
+  const existedHere = isDir(dir);
+  fs.mkdirSync(dir, { recursive: true });
+  const f = path.join(dir, 'meta.json');
+  const meta = updateMeta(f, (old) => {
+    const value = Object.keys(old).length ? old : { name: target?.name ?? display, named_by: named ? 'user' : 'branch', project: L.project, branches: [], base, created: now() };
+    if (!value.branches.includes(branch)) value.branches.push(branch);
+    if (base && !value.base) value.base = base;
+    value.updated = now();
+    return value;
+  }, { root });
+  const rel = relOf(root, dir);
+  return { ok: true, mode: L.mode, created: !existedHere, joined: !!target && !existedHere, name: meta.name, named_by: meta.named_by, dir: rel, project: L.project, branches: sync(root, rel).branches };
+}
+
+// 本次落盘路径：文件名固定（review.md …），已有时先把当前版复制到 tmp/old-artifacts/<种类>_v<N>.md（previous，复审对照用），
+// 并带上它第一行的 wiki 发布记录；新版直接写到 path（覆盖当前版），写完 sync <path> 确认版本号
+export function nextPath(root, kind, branch) {
+  if (!FILES[kind]) return { code: 1, out: { ok: false, error: `未知产物种类「${kind}」：${Object.keys(FILES).join(' / ')}` } };
+  const L = layout(root);
+  if (!L.ok) return { code: 2, out: notReady(L) };
+  const r = find(root, branch, L);
+  if (!r) return { code: 2, out: { ok: false, ...which(root, branch) } };
+  const abs = path.join(r.abs, `${FILES[kind]}.md`);
+  let v = 1; let previous = null; let record = null;
+  if (fs.existsSync(abs)) {
+    const cur = versionsOf(r.abs)[kind] ?? 1;
+    const arc = archivePath(root, r.abs, kind, cur);
+    fs.mkdirSync(path.dirname(arc), { recursive: true });
+    fs.copyFileSync(abs, arc);
+    v = cur + 1; previous = relOf(root, arc);
+    record = /^<!-- md-to-wiki: [^\n]*-->/.exec(fs.readFileSync(abs, 'utf8'))?.[0] ?? null;
+  }
+  return { code: 0, out: { ok: true, mode: L.mode, name: r.name, dir: r.dir, path: relOf(root, abs), cite: L.ref(abs), version: v, previous, wiki_record: record } };
+}
+
+export function list(root) {
+  const workspace = loadWorkspace(root);
+  return workspace.requirements.map((r) => {
+    const artifacts = workspace.artifacts.filter((a) => a.requirement === r.slug && a.project === r.project).sort((a, b) => a.version - b.version);
+    const latest = Object.fromEntries(Object.keys(FILES).map((kind) => [kind, artifacts.filter((a) => a.kind === kind).at(-1)?.path.split('/').at(-1) ?? null]));
+    return { name: r.name, dir: r.dir, branches: r.branches, named_by: r.meta.named_by, created: r.meta.created, artifacts: artifacts.length, latest,
+      ...(!r.valid ? { diagnostics: workspace.diagnostics.filter((d) => d.path.startsWith(r.dir + '/')) } : {}) };
+  }).sort((a, b) => String(b.created).localeCompare(String(a.created)));
+}
+
+// ------------------------------------------------------------------ 文档仓库的提交提示
+// 当前需求（或给定目录）在文档仓库里未提交的改动；项目模式下产物随代码提交，不单独提示
+export function pending(root, branch, dirRel = null) {
+  const L = layout(root);
+  if (L.mode === 'project') return { mode: 'project', commit_prompt: false, note: `产物在项目仓库的 ${HOME}/ 里，随代码一起提交` };
+  if (!L.ok) return notReady(L);
+  const abs = dirRel ? path.resolve(root, dirRel) : find(root, branch, L)?.abs;
+  if (!abs) return { ok: false, mode: 'repo', error: '当前分支没有绑定需求' };
+  const inRepo = toPosix(path.relative(L.repo, abs));
+  const top = git(L.repo, ['rev-parse', '--show-toplevel']);
+  if (top.status !== 0) return { ok: true, mode: 'repo', repo: L.repo_rel, is_git: false, files: [], commit_prompt: L.commit_prompt, note: '文档仓库还不是 git 仓库，产物只保存在本地' };
+  const st = git(L.repo, ['-c', 'core.quotePath=false', 'status', '--porcelain', '--untracked-files=all', '--', inRepo]);
+  const files = st.stdout.split('\n').filter(Boolean).map((l) => l.slice(3));
+  const meta = readJson(path.join(abs, 'meta.json')) ?? {};
+  const kinds = [...new Set(files.map((f) => parseFile(path.basename(f))?.kind).filter(Boolean))].map((k) => LABELS[k]);
+  const message = `docs(${meta.name ?? path.basename(path.dirname(abs))}): ${L.project}${kinds.length ? ` ${kinds.join('、')}` : ' 更新产物'}`;
+  // DocNexus 也在这个文档仓库里（workflow-run/docnexus/）：知识库的改动单独列出，单独提交，提交信息写沉淀了什么
+  const kn = isDir(path.join(L.repo, 'docnexus', 'library'))
+    ? git(L.repo, ['-c', 'core.quotePath=false', 'status', '--porcelain', '--untracked-files=all', '--', 'docnexus']).stdout.split('\n').filter(Boolean).map((l) => l.slice(3))
+    : [];
+  return {
+    ok: true, mode: 'repo', repo: L.repo_rel, is_git: true, project: L.project, dir: relOf(root, abs), files, commit_prompt: L.commit_prompt,
+    suggested_message: files.length ? message : null,
+    commands: files.length ? [`git -C ${JSON.stringify(L.repo_rel)} add -- ${JSON.stringify(inRepo)}`, `git -C ${JSON.stringify(L.repo_rel)} commit -m ${JSON.stringify(message)}`] : [],
+    ...(kn.length ? { knowledge_files: kn, knowledge_commands: [`git -C ${JSON.stringify(L.repo_rel)} add -- docnexus`, `git -C ${JSON.stringify(L.repo_rel)} commit -m "knowledge: <沉淀了什么>"`] } : {}),
+  };
+}
+
+// ------------------------------------------------------------------ 旧结构迁移
+// 旧版本随代码提交时没有 <项目名>/ 这一层：文件直接放在 docs/requirements/<需求>/ 下。
+// 列出这样的需求目录（目录里直接有文件的；隐藏文件不算）
+export function legacyRequirements(root) {
+  const base = path.join(root, REQ_DIR);
+  if (!isDir(base)) return [];
+  return fs.readdirSync(base, { withFileTypes: true }).filter((d) => !skipDir(d)).map((d) => d.name)
+    .filter((slug) => fs.readdirSync(path.join(base, slug), { withFileTypes: true }).some((e) => e.isFile() && !e.name.startsWith('.')));
+}
+
+// 把旧结构的需求目录挪到 <需求>/<项目名>/：被 git 跟踪的用 git mv（保留历史），其余直接移动；
+// tmp/old-artifacts/<需求>/ 下归档的上一版也一起挪，复审对照还能找到。
+// 目标里已有同名文件时这个需求整个跳过，留给用户处理。项目名没配置时按 layout 自动取的写进 profile.json。
+// 返回 { project, moved: [{ from, to }], skipped: [{ dir, reason }] }
+export function migrateLayout(root) {
+  const L = layout(root);
+  const slugs = legacyRequirements(root);
+  if (!slugs.length) return { project: L.project, moved: [], skipped: [] };
+  if (!L.project) return { project: null, moved: [], skipped: slugs.map((s) => ({ dir: `${REQ_DIR}/${s}`, reason: '还没配置项目名' })) };
+  const repoOf = (abs) => (L.mode === 'repo' ? L.repo : root);
+  const tracked = (abs) => git(repoOf(abs), ['ls-files', '--error-unmatch', '--', path.relative(repoOf(abs), abs)]).status === 0;
+  const moved = []; const skipped = [];
+  const move = (from, to, useGit) => {
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    const cwd = repoOf(from);
+    if (useGit && tracked(from) && git(cwd, ['mv', '--', path.relative(cwd, from), path.relative(cwd, to)]).status === 0) return;
+    fs.renameSync(from, to);
+  };
+  for (const slug of slugs) {
+    const dir = path.join(L.base, slug);
+    const files = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && !e.name.startsWith('.')).map((e) => e.name);
+    const target = path.join(dir, L.project);
+    const clash = files.filter((f) => fs.existsSync(path.join(target, f)));
+    if (clash.length) { skipped.push({ dir: relOf(root, dir), reason: `${relOf(root, target)} 里已有 ${clash.join('、')}` }); continue; }
+    for (const f of files) {
+      move(path.join(dir, f), path.join(target, f), true);
+      moved.push({ from: relOf(root, path.join(dir, f)), to: relOf(root, path.join(target, f)) });
+    }
+    const m = readJson(path.join(target, 'meta.json'));
+    if (m && m.project !== L.project) fs.writeFileSync(path.join(target, 'meta.json'), `${JSON.stringify({ ...m, project: L.project }, null, 2)}\n`);
+    const old = path.join(root, OLD_DIR, slug);
+    if (isDir(old)) {
+      for (const e of fs.readdirSync(old, { withFileTypes: true })) if (e.isFile()) move(path.join(old, e.name), path.join(old, L.project, e.name), false);
+    }
+  }
+  if (moved.length && !L.project_configured && fs.existsSync(path.join(profileDir(root), 'profile.json'))) setConfig(root, { project: L.project });
+  return { project: L.project, moved, skipped };
+}