agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/roles/wiki-compiler.md

@@ -0,0 +1,47 @@
+# Wiki Compiler
+
+> 公共角色契约：本文件。宿主 `agents/` 仅留 frontmatter 指针，正文只维护在 `.agents/roles/`。
+
+## Identity
+企业知识编纂者。把一次代码提交翻译成「系统获得了一项什么业务能力」，而不是「代码做了什么修改」；读者假设为不写代码的产品/客服。只做翻译与定级，不落盘。
+
+## Scope
+- **Accepts**:
+  - 单笔提交（hash）或一段 `base..head` 范围的分析委派。
+  - 可选背景：关联 spec/plan、需求描述（`workflow/` 台账）。
+- **Required Inputs**:
+  - 提交范围（hash 或 base..head）+ 可读 diff 与提交信息。
+  - `wiki/INDEX.md` 主题速览表（判 `wiki_suggestion` 前必读）。
+- **Checks Performed**:
+  1. 通读 diff 实际改动；提交信息仅作线索，两者冲突以 diff 为准。
+  2. 判定 type：`capability`（新增业务能力）/ `fix`（恢复既有能力的正确行为）/ `refactor`（无业务面变化）/ `docs`（仅知识文档变更）。Conventional Commits 类型（feat/fix/refactor…）只作初筛，须用 diff 复核。
+  3. 代码域 → 业务域术语翻译，以本仓 wiki 既有叫法为准（例：OutboundRequest→出库申请、Allocation→档级/来源分配、InventoryLock→库存占用、MTO→需求单）。
+  4. 对照 `wiki/INDEX.md` 判断知识是否值得沉淀及落位；一次性过程产物（workflow 台账已记、git 历史可溯）不劝入 wiki。
+- **Deliverables**:
+  - 严格 JSON（schema 见下）：单笔提交输出一个对象，一段范围输出数组、逐笔一条。
+  - JSON 之外仅允许附一行证据锚定说明。落盘（归位/INDEX/看板/成对同步）由主智能体走 `wiki` 技能，本角色不改文件。
+
+### 输出 schema
+```json
+{
+  "commit": "<短hash> <一行提交信息>",
+  "type": "capability | fix | refactor | docs",
+  "title": "业务语言标题，不出现代码词",
+  "capability": "系统现在能……（1-3 句；fix 写成「此前……会……，现在恢复为……」；refactor/docs 为 null）",
+  "impact": "影响范围：谁在哪个流程/界面感知到；refactor 说明内部影响面并给出「业务无感知」结论",
+  "modules": ["业务模块名，如 出库申请/出库单/采购/到货入库/库存/主数据/编码模板"],
+  "user_visible": "true | false | null（不确定）",
+  "wiki_suggestion": { "topic": "wiki 现存主题之一，以 INDEX 速览表为准", "filename": "<主题>-<关键词>[-范围/版本].ext", "reason": "值得沉淀的理由" },
+  "related_docs": ["需同步更新的既有 wiki 文档路径；触及全流程或功能验证口径时须含成对文档"],
+  "uncertain": ["留 null 或低置信的字段名+原因；全部确定则为 null"]
+}
+```
+
+字段空值规则：`wiki_suggestion` 不值得沉淀或一次性产物 → null；`related_docs` 无或不确定 → null；其余不确定字段一律 null，禁止编造接口名、数据表名、数量与流程步骤。
+
+## Constraints
+- **业务语言纪律**: title/capability/impact 面向不写代码的读者；禁出现接口路径、类名、方法名、表名/字段名（名称本身即业务名词如「档级」除外）。
+- **不编造**: 证据不足就留 null 并写入 `uncertain`，不猜。
+- **只读**: 不修改任何仓库文件；产出仅 JSON + 一行证据。
+- **如实定级**: 提交信息声称 feat 但 diff 无业务面变化 → type=refactor 并说明影响范围，不迁就提交信息抬高级别。
+- **单源引用**: 主题目录、命名规范、成对同步义务以 `wiki/INDEX.md` 与 `wiki` 技能（`.agents/skills/wiki/SKILL.md`）为准，本文件不复制维护。

package/templates/engine/.agents/scripts/agent-eval.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+// agent-eval.mjs — 行为评测门（AI-native QA）
+//
+// 背景（Anthropic《The AI-native SDLC playbook》）：evals 是 AI 时代的 QA。
+// 当技能 / 命令 / 角色 / 模型别名变化时，静态门无法回答“行为是否还一样”，
+// 必须用固定任务集跑一次行为评测，并把结果与「被改动的配置面」绑定成凭证。
+//
+// 本脚本只做三件事，不调用任何模型：
+//   1. 给「评测敏感面」算一个内容签名（skills/commands/roles/model 配置等）；
+//   2. record 落一条评测凭证（通过率 + 任务数 + 模型 + 签名）；
+//   3. check 校验当前签名是否有新鲜、达标、可追溯的凭证。
+//
+// 评测本身仍由既有 `.agents/skills/eval/SKILL.md` 的任务集流程执行；
+// 本脚本负责把「跑过没有、跑的是不是当前配置」变成机器可判的门。
+//
+// 用法：
+//   node .agents/scripts/agent-eval.mjs check [--advisory] [--json]
+//   node .agents/scripts/agent-eval.mjs record --pass-rate 0.9 --tasks 10 --model opus [--note "..."]
+//   node .agents/scripts/agent-eval.mjs status [--json]
+//   node .agents/scripts/agent-eval.mjs signature
+//
+// 选项：
+//   --root <dir>        目标根（默认 cwd）
+//   --files a,b         只对指定文件算签名（测试/定向复核）
+//   --threshold <0..1>  通过率阈值（默认取配置）
+//   --max-age-days <N>  凭证有效期（默认取配置）
+//
+// 退出码：check 通过 0；无凭证/过期/不达标 1（--advisory 时仍为 0 并打 WARN）。
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  // 评测敏感面：这些文件变化会改变智能体行为。
+  sensitive: [
+    '.agents/skills/**',
+    '.agents/commands/**',
+    '.agents/roles/**',
+    '.agents/config/model-roles.json',
+    '.agents/config/steering.json',
+    '.agents/config/pipeline.json',
+    // 门禁自身的阈值/敏感面提交也属于“行为面”变更：改配置必须重新评测。
+    '.agents/config/agent-eval.json',
+  ],
+  results: '.agents/evals/results.jsonl',
+  threshold: 0.8,
+  maxAgeDays: 30,
+  // 凭证必须可追溯：少于该任务数不接受 record（eval/SKILL.md 要求 5–10 条）
+  minTasks: 5,
+  advisory: true,
+};
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.agents/cache', '.agents/tmp', 'tmp']);
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function loadConfig(root) {
+  const file = path.join(root, '.agents', 'config', 'agent-eval.json');
+  const raw = readJson(file);
+  return { ...DEFAULT_CONFIG, ...(raw || {}) };
+}
+
+function globToRegExp(glob) {
+  const g = String(glob).replace(/\\/g, '/');
+  let out = '';
+  for (let i = 0; i < g.length; i += 1) {
+    const c = g[i];
+    if (c === '*') {
+      if (g[i + 1] === '*') {
+        out += '.*';
+        i += 1;
+        if (g[i + 1] === '/') i += 1;
+      } else out += '[^/]*';
+    } else if (c === '?') out += '[^/]';
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+export function isSensitive(rel, patterns) {
+  const norm = String(rel).replace(/\\/g, '/');
+  return (patterns || []).some((p) => globToRegExp(p).test(norm));
+}
+
+function walk(root, rel, out) {
+  let ents;
+  try {
+    ents = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const ent of ents) {
+    const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) {
+      if (SKIP_DIRS.has(childRel)) continue;
+      walk(root, childRel, out);
+    } else if (ent.isFile()) out.push(childRel);
+  }
+}
+
+export function sensitiveFiles(root, cfg = loadConfig(root), only = null) {
+  let files = [];
+  if (only && only.length) files = only.map((f) => String(f).replace(/\\/g, '/'));
+  else walk(root, '', files);
+  return files.filter((f) => isSensitive(f, cfg.sensitive)).sort();
+}
+
+// 内容签名：只覆盖评测敏感面，避免无关改动让凭证失效。
+export function treeSignature(root, cfg = loadConfig(root), only = null) {
+  const files = sensitiveFiles(root, cfg, only);
+  const h = crypto.createHash('sha256');
+  for (const rel of files) {
+    let buf;
+    try {
+      buf = fs.readFileSync(path.join(root, rel));
+    } catch {
+      buf = Buffer.from('<missing>');
+    }
+    h.update(rel);
+    h.update('\0');
+    h.update(buf);
+    h.update('\0');
+  }
+  return { signature: h.digest('hex'), files };
+}
+
+export function readResults(root, cfg = loadConfig(root)) {
+  const file = path.join(root, cfg.results);
+  let raw = '';
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      /* 坏行忽略：凭证是 append-only 的，不能因一行损坏阻塞 */
+    }
+  }
+  return rows;
+}
+
+function ageDays(ts, now = Date.now()) {
+  const t = Date.parse(ts);
+  if (!Number.isFinite(t)) return Infinity;
+  return (now - t) / 86400000;
+}
+
+export function evaluate(root, { now = Date.now(), only = null } = {}) {
+  const cfg = loadConfig(root);
+  const { signature, files } = treeSignature(root, cfg, only);
+  if (!files.length) {
+    return { ok: true, reason: 'no-sensitive-files', signature, files: [], cfg };
+  }
+  const rows = readResults(root, cfg);
+  const hits = rows.filter((r) => r && r.signature === signature);
+  const fresh = hits.filter((r) => ageDays(r.ts, now) <= cfg.maxAgeDays);
+  const passing = fresh.filter((r) => Number(r.passRate) >= cfg.threshold);
+  if (!hits.length) return { ok: false, reason: 'no-eval-for-tree', signature, files, cfg };
+  if (!fresh.length) return { ok: false, reason: 'eval-expired', signature, files, cfg };
+  if (!passing.length) return { ok: false, reason: 'eval-below-threshold', signature, files, cfg };
+  const latest = passing.sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts))[0];
+  return { ok: true, reason: 'pass', signature, files, cfg, record: latest };
+}
+
+export function recordEval(root, { passRate, tasks = 0, model = '', note = '', signature = null, now = new Date() } = {}) {
+  const rate = Number(passRate);
+  if (!Number.isFinite(rate) || rate < 0 || rate > 1) throw new Error('pass-rate 必须是 0..1');
+  const cfg = loadConfig(root);
+  const sig = signature || treeSignature(root, cfg).signature;
+  const row = {
+    ts: now.toISOString(),
+    signature: sig,
+    passRate: rate,
+    tasks: Number(tasks) || 0,
+    model: String(model || ''),
+    note: String(note || ''),
+  };
+  const file = path.join(root, cfg.results);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+  return row;
+}
+
+// ---- CLI ----
+function argOf(argv, name, fallback = null) {
+  const i = argv.indexOf(`--${name}`);
+  if (i < 0) return fallback;
+  const v = argv[i + 1];
+  return v == null || v.startsWith('--') ? true : v;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] || 'check';
+  const root = path.resolve(argOf(argv, 'root', process.cwd()));
+  const only = argOf(argv, 'files');
+  const json = argv.includes('--json');
+
+  if (cmd === 'signature') {
+    const { signature, files } = treeSignature(root, loadConfig(root), only ? String(only).split(',') : null);
+    console.log(json ? JSON.stringify({ signature, files }, null, 2) : signature);
+    return 0;
+  }
+
+  if (cmd === 'record') {
+    const cfg = loadConfig(root);
+    const rawRate = argOf(argv, 'pass-rate');
+    const rawTasks = argOf(argv, 'tasks');
+    const rawModel = argOf(argv, 'model');
+    // 不带值（或后面紧跟另一个 flag）时 argOf 返回 true；绝不能把它当成 1.0 落账。
+    if (rawRate === true || rawRate == null || !Number.isFinite(Number(rawRate))) {
+      console.error('record 需要 --pass-rate <0..1>（必须是真实评测结果）');
+      return 2;
+    }
+    const tasks = rawTasks === true ? NaN : Number(rawTasks ?? 0);
+    const minTasks = Number(cfg.minTasks ?? 5);
+    if (!Number.isFinite(tasks) || tasks < minTasks) {
+      console.error(`record 需要 --tasks >= ${minTasks}（凭证必须可追溯）`);
+      return 2;
+    }
+    if (rawModel === true || !String(rawModel || '').trim()) {
+      console.error('record 需要 --model <评测模型>（凭证必须可追溯）');
+      return 2;
+    }
+    const row = recordEval(root, {
+      passRate: Number(rawRate),
+      tasks,
+      model: String(rawModel).trim(),
+      note: argOf(argv, 'note', '') === true ? '' : String(argOf(argv, 'note', '')),
+    });
+    console.log(`recorded eval ${row.signature.slice(0, 12)} passRate=${row.passRate} tasks=${row.tasks}`);
+    return 0;
+  }
+
+  const result = evaluate(root, { only: only ? String(only).split(',') : null });
+  if (cmd === 'status' || json) {
+    console.log(json ? JSON.stringify(result, null, 2) : `signature=${result.signature.slice(0, 12)} ok=${result.ok} reason=${result.reason}`);
+    return 0;
+  }
+
+  const advisory = argv.includes('--advisory') || result.cfg.advisory;
+  if (result.ok) {
+    console.log(`✅ agent-eval: ${result.reason}`);
+    return 0;
+  }
+  const msg = `agent-eval: ${result.reason}（签名 ${result.signature.slice(0, 12)}，${result.files.length} 个敏感文件）`;
+  if (advisory) {
+    console.log(`⚠ WARN ${msg}；按 .agents/skills/eval/SKILL.md 跑一次并用 record 落凭证`);
+    return 0;
+  }
+  console.error(`✗ ${msg}；按 .agents/skills/eval/SKILL.md 跑一次并用 record 落凭证`);
+  return 1;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('agent-eval.mjs');
+if (isMain) process.exit(main());