agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/scripts/warn-format.mjs

@@ -0,0 +1,57 @@
+// warn-format.mjs — check-loop 告警输出降噪（2026-10-22 门禁收敛批 2「信噪比」）
+// 职责单一、无副作用、可直接单测：把 advisory 告警（WARN/NOTE）按方括号标签折叠为
+// 「×N 条同类」单行，明细落盘；**BLOCK 一律不折**——阻断项必须逐条可读（判读与呈现分离）。
+// 动机（实测）：一次 --all 跑出 17 条 WARN + 19 条 NOTE，同类多行 + 多行告警把 actionable 项
+// 淹没——告警不精确比告警多更伤，输出一旦不可读，门禁即退化形式。折叠后逐条明细仍完整落盘
+// （供排障与事后对质），不丢信息、不降判据。
+// 落位说明：本模块独立成文件而非并入 check-loop-kit.mjs——kit 被 import 即执行（argv 解析遇
+// 未知参数即 usage() 退出），测试套件带 --shard 参数导入即死；无副作用模块才能被直接单测。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 明细落盘的相对路径（对外只报相对路径，避免把绝对路径写进门禁输出）
+export const WARN_LOG_REL = 'tmp/check-loop-warn.log';
+
+// 明细落盘（无副作用导出）：折叠与静默共用——check-loop 静默三类高频 WARN 时仍须把全量明细
+//   写入日志（数据不丢，只静默输出），故落盘从 formatWarnings 抽出（2026-11-08 引擎减重档 2-G）。
+export function writeWarnLog(list, logPath) {
+  if (!logPath) return;
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.writeFileSync(logPath, `${list.join('\n')}\n`);
+  } catch { /* 明细落盘失败不改裁决（同 recordFailure 容错口径） */ }
+}
+
+// formatWarnings(list, opts) → 折叠后的告警文本
+//   list：advisory 告警行数组（每行形如 "- [WARN 标签] 内容"）
+//   opts.enabled=false → 逐条原样返回（排障 / 夹具口径）
+//   opts.logPath      → 明细落盘路径（落盘失败不改裁决）
+//   opts.logNote      → 输出中提示的明细位置（默认相对路径）
+export function formatWarnings(list, { enabled = true, logPath = null, logNote = WARN_LOG_REL } = {}) {
+  if (!enabled) return list.join('\n');
+  if (logPath) writeWarnLog(list, logPath);
+  // 归组键 = 方括号标签全文（WARN / NOTE 同级折叠）：同类同因多条只留一行计数。
+  // **无标签条目一律不折叠**（2026-10-22 单测 S6 钉住）：原实现用「首行」作 raw 键兜底，
+  // 会把两条首行相同的无标签告警合并成「- [] ×2」——既丢了内容又造了个空标签，
+  // 比不折叠更坏（读者以为是一条）。无标签条目逐条原样输出。
+  const order = [];
+  const groups = new Map();
+  const loose = [];
+  for (const line of list) {
+    const m = /^- \[([^\]]*)\]/.exec(line);
+    if (!m) { loose.push(line); continue; }
+    const key = `tag:${m[1]}`;
+    if (!groups.has(key)) { groups.set(key, { tag: m[1], lines: [] }); order.push(key); }
+    groups.get(key).lines.push(line);
+  }
+  const out = [];
+  for (const key of order) {
+    const g = groups.get(key);
+    if (g.lines.length === 1) { out.push(g.lines[0]); continue; }
+    out.push(`- [${g.tag}] ×${g.lines.length} 条同类（明细 ${logNote}）`);
+  }
+  // 无标签条目附在末尾，保持原顺序内的相对次序（不与标签条目交错）
+  out.push(...loose);
+  return out.join('\n');
+}

package/templates/engine/.agents/scripts/wf-journal.mjs

@@ -0,0 +1,230 @@
+// wf-journal — 编排执行 run journal（orchestration-journal-human，审查改进方向 4）
+// 用途：宿主 AI 按 .agents/pipelines/_TEMPLATE.md 纪律，每个 stage 每次尝试出结果（pass/fail/blocked）
+//       记一行 JSONL；中止后重跑先看 status——已 pass 不重跑，从就绪层续（断点续跑与重试计量）。
+// 存储：.agents/cache/orchestration-runs.jsonl（本地运行态缓存，已 gitignore，可丢弃——丢失仅失去
+//       续跑记忆，不影响任何门禁；status 对空 journal 天然全量输出不误报）。
+// 行 schema：{ ts, run, wf, stage, form?, status, attempt, note? }
+//   run = <wf>@<YYYYMMDD-HHMM>；同 run 同 stage 多行按末次状态生效（重试后过 = pass），attempt 取最大。
+// 语义口径（与 _TEMPLATE.md 四形态一致；stages 表解析复用 workflows-check.mjs 的 parseStages 单源）。
+// 用法：
+//   node .agents/scripts/wf-journal.mjs add --wf <编排名> --stage <id> --status <pass|fail|blocked>
+//        [--form role|step|gate|human] [--attempt N] [--note <文本>] [--run <runId>] [--new-run]
+//        [--journal <文件>]（默认 .agents/cache/orchestration-runs.jsonl，按 cwd）
+//   node .agents/scripts/wf-journal.mjs status --wf <编排名> [--run <runId>] [--journal <文件>] [--wf-root <目录>] [--delegations <文件>]
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseStages } from './workflows-check.mjs';
+import { readDelegationsText as readDelegationsShardText } from './ledger-shards.mjs';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const DEFAULT_JOURNAL = () => path.join(process.cwd(), '.agents', 'cache', 'orchestration-runs.jsonl');
+const DEFAULT_WF_ROOT = () => path.join(process.cwd(), '.agents', 'pipelines');
+const STATUSES = ['pass', 'fail', 'blocked'];
+const FORMS = ['role', 'step', 'gate', 'human'];
+
+// 读 journal 原始行（文件不存在/空 → []；目录不存在自动可建由 add 处理）
+export function readJournalLines(journalFile) {
+  try {
+    return fs.readFileSync(journalFile, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+  } catch {
+    return [];
+  }
+}
+
+// replayRun：重放一个 run 的记录 → { state: {stage: {status, attempt, form, note, ts}}, total, bad }
+//   末次状态生效；attempt 取出现过的最大值；坏行跳过（计数返回，调用方决定告警口径）
+export function replayRun(rawLines, run) {
+  const state = {};
+  let total = 0;
+  let bad = 0;
+  for (const line of rawLines) {
+    let j;
+    try { j = JSON.parse(line); } catch { bad++; continue; }
+    if (!j || typeof j !== 'object' || j.run !== run) continue;
+    if (!j.stage || !STATUSES.includes(j.status)) { bad++; continue; }
+    total++;
+    const prev = state[j.stage];
+    state[j.stage] = {
+      status: j.status,
+      attempt: Math.max(prev?.attempt ?? 0, Number(j.attempt) || 1),
+      ...(j.form ? { form: j.form } : {}),
+      ...(j.note ? { note: j.note } : {}),
+      ts: j.ts,
+    };
+  }
+  return { state, total, bad };
+}
+
+// latestRun：journal 中该 wf 最后一条的 run id（无记录 → null）
+export function latestRun(rawLines, wf) {
+  let run = null;
+  for (const line of rawLines) {
+    try {
+      const j = JSON.parse(line);
+      if (j && j.wf === wf && j.run) run = j.run;
+    } catch { /* 坏行不参与 run 推断 */ }
+  }
+  return run;
+}
+
+// planStages：stages（parseStages 产物）× 状态 → { passed, ready, pending, blocked }
+//   passed  = 末次 pass；ready = 依赖全 pass 且自身未 pass（末次 fail 标注重试就绪）；blocked = 自身末次 blocked；pending = 其余
+export function planStages(stages, state) {
+  const passed = [];
+  const ready = [];
+  const pending = [];
+  const blocked = [];
+  const passedSet = new Set(stages.filter((s) => state[s.id]?.status === 'pass').map((s) => s.id));
+  for (const s of stages) {
+    const st = state[s.id];
+    if (st?.status === 'pass') { passed.push({ id: s.id }); continue; }
+    if (st?.status === 'blocked') { blocked.push({ id: s.id, note: st.note || '' }); continue; }
+    const deps = s.after ? s.after.split(/[,，、\s]+/).filter(Boolean) : [];
+    if (deps.every((d) => passedSet.has(d))) {
+      ready.push({ id: s.id, ...(st?.status === 'fail' ? { retry: st.attempt } : {}) });
+    } else {
+      pending.push({ id: s.id, ...(deps.some((d) => state[d] && state[d].status !== 'pass') && (state[deps.find((d) => state[d] && state[d].status !== 'pass')]?.status === 'blocked') ? { depBlocked: true } : {}) });
+    }
+  }
+  return { passed, ready, pending, blocked };
+}
+
+const pad = (n) => String(n).padStart(2, '0');
+const runIdOf = (wf, d = new Date()) =>
+  `${wf}@${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+
+function parseArgs(argv) {
+  const out = { cmd: argv[0] };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) out[a.slice(2)] = argv[++i] ?? true;
+    else fail(`未知参数：${a}（用法见文件头注释）`);
+  }
+  return out;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('wf-journal.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  const journalFile = a.journal || DEFAULT_JOURNAL();
+  if (a.cmd === 'add') {
+    if (!a.wf || !a.stage || !a.status) fail('add 必填：--wf / --stage / --status（pass|fail|blocked）');
+    if (!STATUSES.includes(a.status)) fail(`--status 须为 ${STATUSES.join('|')}（现 ${a.status}）`);
+    if (a.form && !FORMS.includes(a.form)) fail(`--form 须为 ${FORMS.join('|')}（现 ${a.form}）`);
+    const lines = readJournalLines(journalFile);
+    const run = a.run || (a['new-run'] ? runIdOf(a.wf) : latestRun(lines, a.wf) || runIdOf(a.wf));
+    const attempt = a.attempt
+      ? Number(a.attempt)
+      : lines.filter((l) => { try { const j = JSON.parse(l); return j.run === run && j.stage === a.stage; } catch { return false; } }).length + 1;
+    const row = {
+      ts: new Date().toISOString(), run, wf: a.wf, stage: a.stage,
+      status: a.status, attempt,
+      ...(a.form ? { form: a.form } : {}), ...(a.note ? { note: a.note } : {}),
+    };
+    fs.mkdirSync(path.dirname(journalFile), { recursive: true });
+    fs.appendFileSync(journalFile, JSON.stringify(row) + '\n');
+    console.log(`✅ journal += ${a.wf}/${a.stage} ${a.status}（attempt ${attempt}，run ${run}）`);
+    process.exit(0);
+  }
+  if (a.cmd === 'status') {
+    if (!a.wf) fail('status 必填：--wf（编排名）');
+    const wfRoot = a['wf-root'] || DEFAULT_WF_ROOT();
+    const wfFile = path.join(wfRoot, `${a.wf}.md`);
+    if (!fs.existsSync(wfFile)) fail(`找不到编排脚本：${wfFile}`);
+    const stages = parseStages(fs.readFileSync(wfFile, 'utf8'));
+    if (!stages) fail(`编排脚本缺 stages 表：${wfFile}`);
+    const lines = readJournalLines(journalFile);
+    const run = a.run || latestRun(lines, a.wf);
+    console.log(`▶ wf-journal status — ${a.wf}${run ? ` @ ${run}` : '（无 journal 记录，按首轮输出）'}`);
+    if (!run) {
+      const { ready, pending } = planStages(stages, {});
+      console.log(`  ▶ 就绪（第 0 层，${ready.length}）：${ready.map((s) => s.id).join('、') || '无'}`);
+      console.log(`  ⏸ 待定（${pending.length}）：${pending.map((s) => s.id).join('、') || '无'}`);
+      process.exit(0);
+    }
+    const { state, total, bad } = replayRun(lines, run);
+    if (bad) console.error(`⚠️ journal 坏行 ${bad} 条已跳过（缓存可丢弃，不影响门禁）`);
+    const plan = planStages(stages, state);
+    console.log(`  （${total} 条记录）`);
+    console.log(`  ✅ 已完成（${plan.passed.length}）：${plan.passed.map((s) => s.id).join('、') || '无'}`);
+    console.log(`  ▶ 就绪（${plan.ready.length}）：${plan.ready.map((s) => (s.retry ? `${s.id}（重试就绪×${s.retry}）` : s.id)).join('、') || '无'}`);
+    console.log(`  ⏸ 待定（${plan.pending.length}）：${plan.pending.map((s) => s.id + (s.depBlocked ? '（依赖中止）' : '')).join('、') || '无'}`);
+    console.log(`  ⛔ 中止（${plan.blocked.length}）：${plan.blocked.map((s) => `${s.id}${s.note ? `（${s.note}）` : ''}`).join('、') || '无'}`);
+    const wfLines = fs.readFileSync(wfFile, 'utf8').split(/\r?\n/);
+    const gaps = unmatchedPasses({
+      stages, state, wfLines,
+      delegationsText: readDelegationsText(typeof a.delegations === 'string' ? a.delegations : null),
+    });
+    if (gaps.length) console.log(`  委派台账未记录（${gaps.length}）：${gaps.join('、')}`);
+    process.exit(0);
+  }
+  fail(`未知命令：${a.cmd ?? ''}（add | status，用法见文件头注释）`);
+}
+function readDelegationsText(file) {
+  // 分片感知读（ledger-shard-ledgers）：单源 = ledger-shards.readDelegationsText。
+  // 原实现只读主台账 → 分片后读到 0 行（静默漏报「委派台账未记录」）。
+  return readDelegationsShardText(process.cwd(), file || null);
+}
+
+function delegationSectionRows(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  let inSec = false;
+  const rows = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      // 不 break：合并文本（主台账 ∪ 分片）里 `## 委派结果` 会出现多次，break 会漏掉后续分片的行
+      // （2026-10-13 实测踩中：分片行读不到 → 静默漏报「委派台账未记录」）。
+      inSec = /^##\s+委派结果\s*$/.test(line);
+      continue;
+    }
+    if (!inSec || !/^\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!cells.length || cells.every((c) => /^[-: ]*$/.test(c))) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(cells[0])) continue;
+    rows.push({ date: cells[0], line });
+  }
+  return rows;
+}
+
+function mdBasenames(text) {
+  const out = [];
+  const re = /[^\s|`]+?\.md/g;
+  let m;
+  while ((m = re.exec(String(text || '')))) {
+    const base = m[0].replace(/\\/g, '/').split('/').pop();
+    if (base && !out.includes(base)) out.push(base);
+  }
+  return out;
+}
+
+function idInRow(id, line) {
+  const escaped = String(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|[^A-Za-z0-9_-])${escaped}([^A-Za-z0-9_-]|$)`).test(line);
+}
+
+// unmatchedPasses：末次 pass 且 role 为 implementer 或 independent-reviewer、
+// 委派结果表没有与 pass 的 UTC 日相同、且含阶段 id 或阶段上 .md 文件名的一行。
+export function unmatchedPasses({ stages, state, wfLines, delegationsText }) {
+  const rows = delegationSectionRows(delegationsText);
+  const gaps = [];
+  for (const s of stages) {
+    if (s.role !== 'implementer' && s.role !== 'independent-reviewer') continue;
+    const st = state[s.id];
+    if (st?.status !== 'pass') continue;
+    const day = String(st.ts || '').slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) continue;
+    const raw = wfLines[(s._line || 0) - 1] || '';
+    const names = [...mdBasenames(s.files), ...mdBasenames(st.note), ...mdBasenames(raw)];
+    const hit = rows.some((r) => {
+      if (r.date !== day) return false;
+      if (idInRow(s.id, r.line)) return true;
+      return names.some((name) => r.line.includes(name));
+    });
+    if (!hit) gaps.push(s.id);
+  }
+  return gaps;
+}
+
+export default { replayRun, planStages, latestRun, readJournalLines, unmatchedPasses };