agentic-flow-kit 2.0.0 → 2.1.0

package/templates/engine/.agents/scripts/fix-task.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// fix-task.mjs — 修复任务窗口标记（配合 pre-write-check 的“测试不可弱化”层）
+//
+// 修复开始时 start，结束时 stop。窗口内修改既有测试会被写前门拒绝；
+// 新建复现测试仍然允许（先写失败用例，再修实现）。
+//
+// 用法：
+//   node .agents/scripts/fix-task.mjs start [--id <id>] [--allow path1,path2]
+//   node .agents/scripts/fix-task.mjs status
+//   node .agents/scripts/fix-task.mjs stop
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function markerFile(root) {
+  return path.join(root, '.agents', 'cache', 'fix-task.json');
+}
+
+export function startFixTask(root, { id = '', allowedTests = [], now = new Date() } = {}) {
+  const file = markerFile(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const row = {
+    active: true,
+    id: String(id || `fix-${now.toISOString().slice(0, 19).replace(/[:T]/g, '')}`),
+    startedAt: now.toISOString(),
+    allowedTests: allowedTests.map((p) => String(p).replace(/\\/g, '/')),
+  };
+  fs.writeFileSync(file, JSON.stringify(row, null, 2), 'utf8');
+  return row;
+}
+
+export function readFixTask(root) {
+  try {
+    return JSON.parse(fs.readFileSync(markerFile(root), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function stopFixTask(root) {
+  const file = markerFile(root);
+  const existed = fs.existsSync(file);
+  fs.rmSync(file, { force: true });
+  return { existed };
+}
+
+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] || 'status';
+  const root = path.resolve(argOf(argv, 'root', process.cwd()));
+  if (cmd === 'start') {
+    const allow = argOf(argv, 'allow', '');
+    const row = startFixTask(root, {
+      id: argOf(argv, 'id', ''),
+      allowedTests: allow && allow !== true ? String(allow).split(',') : [],
+    });
+    console.log(`fix-task 窗口已开启：${row.id}${row.allowedTests.length ? `（允许测试：${row.allowedTests.join(', ')}）` : ''}`);
+    return 0;
+  }
+  if (cmd === 'stop') {
+    const res = stopFixTask(root);
+    console.log(res.existed ? 'fix-task 窗口已关闭' : 'fix-task 无活动窗口');
+    return 0;
+  }
+  const row = readFixTask(root);
+  console.log(row ? `active ${row.id} since ${row.startedAt}` : 'inactive');
+  return row ? 0 : 1;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('fix-task.mjs');
+if (isMain) process.exit(main());

package/templates/engine/.agents/scripts/memory-tier.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// memory-tier.mjs — 注入层预算 + 记忆升降候选
+//
+// 背景（Anthropic《The components of agent memory》）：
+//   - 顶层记忆会被注入每个会话，必须小；Claude Code 只加载 MEMORY.md 前 200 行 / 25KB。
+//   - dreaming 的职责之一是“把细节下沉、把该上浮的规则上浮”，而不是持续变大。
+//
+// 本脚本：
+//   audit   检查注入层是否超行/字节预算（超限非零）
+//   suggest 从错题/会话经验/主张里找重复模式，输出“可考虑上浮”的候选（只读）
+//   budget  打印当前用量
+//
+// 用法：
+//   node .agents/scripts/memory-tier.mjs audit
+//   node .agents/scripts/memory-tier.mjs suggest [--days 90] [--min 3]
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  injected: { file: '.agents/notes/injected-memory.md', maxLines: 200, maxBytes: 25600 },
+  promotion: { candidates: '.agents/cache/memory-promotions.jsonl', minOccurrences: 3, outputDir: 'tmp' },
+};
+
+export function loadConfig(root) {
+  const file = path.join(root, '.agents', 'config', 'memory-tiers.json');
+  try {
+    return { ...DEFAULT_CONFIG, ...JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+export function auditBudget(root, cfg = loadConfig(root)) {
+  const rel = cfg.injected.file;
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) return { ok: false, reason: 'missing', rel, lines: 0, bytes: 0, cfg };
+  const text = fs.readFileSync(abs, 'utf8');
+  const lines = text.split(/\r?\n/).length;
+  // 字节口径与 rule-budget 一致：LF 归一，避免 CRLF 虚高。
+  const bytes = Buffer.byteLength(text.replace(/\r\n/g, '\n'), 'utf8');
+  const overLines = lines > cfg.injected.maxLines;
+  const overBytes = bytes > cfg.injected.maxBytes;
+  return {
+    ok: !overLines && !overBytes,
+    reason: overLines ? 'over-lines' : overBytes ? 'over-bytes' : 'ok',
+    rel,
+    lines,
+    bytes,
+    maxLines: cfg.injected.maxLines,
+    maxBytes: cfg.injected.maxBytes,
+    cfg,
+  };
+}
+
+function readJsonl(dir, re) {
+  const rows = [];
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => re.test(n)).sort();
+  } catch {
+    return rows;
+  }
+  for (const name of names) {
+    let raw = '';
+    try {
+      raw = fs.readFileSync(path.join(dir, name), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        rows.push(JSON.parse(line));
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows;
+}
+
+function norm(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[`"'“”‘’]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// 候选来源：会话失败/纠正、错题 tag、主张中的重复主题。
+export function suggestPromotions(root, { days = 90, min = null, now = new Date() } = {}) {
+  const cfg = loadConfig(root);
+  const floor = Number(min) || cfg.promotion.minOccurrences;
+  const cutoff = now.getTime() - days * 86400000;
+  const buckets = new Map();
+  const add = (key, source, sample) => {
+    const k = norm(key);
+    if (!k || k.length < 4) return;
+    if (!buckets.has(k)) buckets.set(k, { key: k, count: 0, sources: new Set(), samples: [] });
+    const b = buckets.get(k);
+    b.count += 1;
+    b.sources.add(source);
+    if (sample && b.samples.length < 3) b.samples.push(sample);
+  };
+
+  const sessions = readJsonl(path.join(root, '.agents', 'cache', 'session-logs'), /^\d{4}-\d{2}-\d{2}\.jsonl$/)
+    .filter((e) => ['failure', 'correction', 'refusal'].includes(e.type))
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of sessions) add(e.tag || e.text, 'session-log', e.text);
+
+  const papercuts = readJsonl(path.join(root, 'workflow', 'papercuts.d'), /\.(jsonl|json)$/)
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of papercuts) add(e.tag || e.kind || e.text, 'papercut', e.text);
+
+  const claims = readJsonl(path.join(root, 'workflow', 'claims.d'), /^\d{4}-\d{2}\.jsonl$/)
+    .filter((e) => !e.ts || Date.parse(e.ts) >= cutoff);
+  for (const e of claims) {
+    const topic = String(e.path || '').split(/[\\/]/)[0];
+    add(topic || e.claim, 'claim', e.claim);
+  }
+
+  return [...buckets.values()]
+    .filter((b) => b.count >= floor)
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+    .map((b) => ({ key: b.key, count: b.count, sources: [...b.sources].sort(), samples: b.samples }));
+}
+
+export function writeSuggestion(root, candidates, { days = 90, cfg = loadConfig(root), now = new Date() } = {}) {
+  const dir = path.join(root, cfg.promotion.outputDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `memory-tier-suggest-${now.toISOString().slice(0, 10)}.md`);
+  const lines = [
+    `# 记忆上浮候选（近 ${days} 天）`,
+    '',
+    '> 只出候选，不自动改写注入层。裁决后手工改 `.agents/notes/injected-memory.md`，',
+    '> 并保持 200 行 / 25KB 预算；下沉详情用链接。',
+    '',
+  ];
+  if (!candidates.length) lines.push('_无达到阈值的重复模式。_');
+  else {
+    lines.push('| 候选 | 次数 | 来源 | 样本 |');
+    lines.push('|---|---|---|---|');
+    for (const c of candidates) {
+      lines.push(`| ${c.key.replace(/\|/g, '\\|')} | ${c.count} | ${c.sources.join(', ')} | ${c.samples[0]?.replace(/\|/g, '\\|') || ''} |`);
+    }
+  }
+  lines.push('');
+  fs.writeFileSync(file, `${lines.join('\n')}\n`, 'utf8');
+  return file;
+}
+
+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] || 'audit';
+  const root = path.resolve(argOf(argv, 'root', process.cwd()));
+  const cfg = loadConfig(root);
+
+  if (cmd === 'audit') {
+    const res = auditBudget(root, cfg);
+    if (!res.ok) {
+      console.error(`✗ 注入层 ${res.reason}: ${res.rel} (${res.lines}/${cfg.injected.maxLines} 行, ${res.bytes}/${cfg.injected.maxBytes} 字节)`);
+      return 1;
+    }
+    console.log(`✅ 注入层预算: ${res.lines}/${cfg.injected.maxLines} 行, ${res.bytes}/${cfg.injected.maxBytes} 字节`);
+    return 0;
+  }
+
+  if (cmd === 'suggest') {
+    const days = Number(argOf(argv, 'days', 90)) || 90;
+    const min = Number(argOf(argv, 'min', 0)) || null;
+    const candidates = suggestPromotions(root, { days, min });
+    const file = writeSuggestion(root, candidates, { days, cfg });
+    console.log(`${file}（${candidates.length} 个候选）`);
+    return 0;
+  }
+
+  if (cmd === 'budget') {
+    const res = auditBudget(root, cfg);
+    console.log(`lines=${res.lines} bytes=${res.bytes} maxLines=${cfg.injected.maxLines} maxBytes=${cfg.injected.maxBytes} ok=${res.ok}`);
+    return res.ok ? 0 : 1;
+  }
+
+  console.error('用法: memory-tier.mjs audit | suggest [--days N] [--min N] | budget');
+  return 2;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('memory-tier.mjs');
+if (isMain) process.exit(main());

package/templates/engine/.agents/scripts/memory-wiki.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// memory-wiki.mjs — 把“记忆”编译成可导航的表示（wiki）
+//
+// 背景（Anthropic《The components of agent memory》）：wiki 不是文档归档，
+// 而是 dreaming 增量构建的“记忆地图”——页面 + 链接，让智能体能遍历自己知道什么；
+// 检索与 wiki 组合通常优于单独检索。
+//
+// 输入（存在即用）：
+//   workflow/claims.d/*.jsonl          主张账（未来会话可能当真的话 + 原文出处）
+//   workflow/incidents/*.md            事故复盘
+//   workflow/papercuts.d/*.md          错题/纸割登记
+//   .agents/cache/session-logs/*.jsonl 会话经验（failure/correction/refusal）
+//
+// 输出：wiki/_memory/INDEX.md + 每个主题一页（主张/事故/经验），带来源链接。
+// 语义：
+//   - 只写 wiki/_memory/**，不碰人工 wiki；
+//   - 幂等：内容未变不写；--check 发现漂移即非零；
+//   - 不自动 commit；不把 claims 的“原文还在”当成“主张为真”。
+//
+// 用法：
+//   node .agents/scripts/memory-wiki.mjs            # 生成/更新
+//   node .agents/scripts/memory-wiki.mjs --check    # 只检查是否最新
+//   node .agents/scripts/memory-wiki.mjs --dry-run  # 只打印将写文件
+import fs from 'node:fs';
+import path from 'node:path';
+import { recheckClaims } from './claims.mjs';
+
+const OUT_DIR = path.join('wiki', '_memory');
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function listFiles(dir, re) {
+  try {
+    return fs.readdirSync(dir).filter((n) => re.test(n)).sort();
+  } catch {
+    return [];
+  }
+}
+
+function slugify(s) {
+  return String(s || 'general')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w一-龥-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'general';
+}
+
+function firstHeading(text) {
+  const m = String(text).match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : '';
+}
+
+function relLink(fromRel, toRel) {
+  const rel = path.relative(path.dirname(fromRel), toRel).replace(/\\/g, '/');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function readClaims(root) {
+  const dir = path.join(root, 'workflow', 'claims.d');
+  const rows = [];
+  for (const name of listFiles(dir, /^\d{4}-\d{2}\.jsonl$/)) {
+    const raw = readText(path.join(dir, name));
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        rows.push(JSON.parse(line));
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows;
+}
+
+function readSessionLessons(root) {
+  const dir = path.join(root, '.agents', 'cache', 'session-logs');
+  const rows = [];
+  for (const name of listFiles(dir, /^\d{4}-\d{2}-\d{2}\.jsonl$/)) {
+    const raw = readText(path.join(dir, name));
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (['failure', 'correction', 'refusal'].includes(row.type)) rows.push(row);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return rows.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+}
+
+function readIncidents(root) {
+  const dir = path.join(root, 'workflow', 'incidents');
+  return listFiles(dir, /\.md$/).map((name) => {
+    const rel = `workflow/incidents/${name}`;
+    const text = readText(path.join(root, rel));
+    return { name, rel, title: firstHeading(text) || name.replace(/\.md$/, ''), text };
+  });
+}
+
+function readPapercuts(root) {
+  const dir = path.join(root, 'workflow', 'papercuts.d');
+  const out = [];
+  for (const name of listFiles(dir, /\.md$/)) {
+    const rel = `workflow/papercuts.d/${name}`;
+    const text = readText(path.join(root, rel));
+    out.push({ name, rel, title: firstHeading(text) || name, text });
+  }
+  const legacy = path.join(root, 'workflow', 'papercuts.md');
+  if (fs.existsSync(legacy)) out.push({ name: 'papercuts.md', rel: 'workflow/papercuts.md', title: 'papercuts', text: readText(legacy) });
+  return out;
+}
+
+export function buildMemoryWiki(root) {
+  const files = new Map();
+  const claims = readClaims(root);
+  const lessons = readSessionLessons(root);
+  const incidents = readIncidents(root);
+  const papercuts = readPapercuts(root);
+
+  // 主张按“出处路径的首段”聚主题；这比按时间堆叠更接近可遍历的记忆。
+  const claimTopics = new Map();
+  for (const c of claims) {
+    const topic = slugify(String(c.path || 'general').split(/[\\/]/)[0] || 'general');
+    if (!claimTopics.has(topic)) claimTopics.set(topic, []);
+    claimTopics.get(topic).push(c);
+  }
+
+  const indexRel = `${OUT_DIR.replace(/\\/g, '/')}/INDEX.md`;
+  const pages = [];
+
+  if (claimTopics.size) {
+    let recheck = { results: [] };
+    try {
+      recheck = recheckClaims(root);
+    } catch {
+      /* claims 账损坏时仍生成页面，只标 unknown */
+    }
+    const statusById = new Map((recheck.results || []).map((r) => [r.id, r.status]));
+    for (const topic of [...claimTopics.keys()].sort()) {
+      const rel = `${OUT_DIR.replace(/\\/g, '/')}/claims-${topic}.md`;
+      const rows = claimTopics.get(topic).slice().sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+      const body = [
+        '---',
+        `title: 主张 · ${topic}`,
+        'generated: true',
+        'source: workflow/claims.d',
+        '---',
+        '',
+        `# 主张 · ${topic}`,
+        '',
+        '> 主张是“未来会话可能当真的一句话”。`held` 只表示原文仍在，不表示主张为真。',
+        '',
+        ...rows.map((r) => {
+          const status = statusById.get(r.id) || 'unknown';
+          const mark = status === 'broken' ? '⚠ broken' : status;
+          return `- [${mark}] ${r.claim}\n  - 出处：\`${r.path}\` · \`${r.quote}\``;
+        }),
+        '',
+      ].join('\n');
+      files.set(rel, body);
+      pages.push({ rel, title: `主张 · ${topic}`, count: rows.length, kind: 'claims' });
+    }
+  }
+
+  if (incidents.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/incidents.md`;
+    const body = [
+      '---',
+      'title: 事故记忆',
+      'generated: true',
+      'source: workflow/incidents',
+      '---',
+      '',
+      '# 事故记忆',
+      '',
+      ...incidents.map((i) => `- [${i.title}](${relLink(rel, i.rel)}) — \`${i.rel}\``),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '事故记忆', count: incidents.length, kind: 'incidents' });
+  }
+
+  if (lessons.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/lessons.md`;
+    const body = [
+      '---',
+      'title: 会话经验',
+      'generated: true',
+      'source: .agents/cache/session-logs',
+      '---',
+      '',
+      '# 会话经验（失败 / 纠正 / 拒绝）',
+      '',
+      ...lessons.slice(-40).map((e) => {
+        const ref = e.ref ? ` · \`${e.ref}\`` : '';
+        return `- ${String(e.ts).slice(0, 10)} [${e.type}] ${e.text}${ref}`;
+      }),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '会话经验', count: lessons.length, kind: 'lessons' });
+  }
+
+  if (papercuts.length) {
+    const rel = `${OUT_DIR.replace(/\\/g, '/')}/papercuts.md`;
+    const body = [
+      '---',
+      'title: 错题与纸割',
+      'generated: true',
+      'source: workflow/papercuts.d',
+      '---',
+      '',
+      '# 错题与纸割',
+      '',
+      ...papercuts.map((p) => `- [${p.title}](${relLink(rel, p.rel)}) — \`${p.rel}\``),
+      '',
+    ].join('\n');
+    files.set(rel, body);
+    pages.push({ rel, title: '错题与纸割', count: papercuts.length, kind: 'papercuts' });
+  }
+
+  const index = [
+    '---',
+    'title: 记忆地图',
+    'generated: true',
+    'source: memory-wiki.mjs',
+    '---',
+    '',
+    '# 记忆地图（INDEX）',
+    '',
+    '> 这是 dreaming 生成的**记忆表示**，不是文档归档。页面只汇总可被后续会话依赖的事实与教训；',
+    '> 原文仍在各自的权威文件里。人工 wiki 不受影响。',
+    '',
+    pages.length ? '| 页面 | 条目 | 类型 |' : '_暂无记忆来源。先积累 claims / incidents / papercuts / session-logs。_',
+    ...(pages.length ? ['|---|---|---|', ...pages.map((p) => `| [${p.title}](${relLink(indexRel, p.rel)}) | ${p.count} | ${p.kind} |`)] : []),
+    '',
+  ].join('\n');
+  files.set(indexRel, index);
+
+  return { files, pages, counts: { claims: claims.length, incidents: incidents.length, lessons: lessons.length, papercuts: papercuts.length } };
+}
+
+export function syncMemoryWiki(root, { check = false, dryRun = false } = {}) {
+  const { files, counts } = buildMemoryWiki(root);
+  const changed = [];
+  for (const [rel, content] of files) {
+    const abs = path.join(root, rel);
+    const current = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    if (current === content) continue;
+    changed.push(rel);
+    if (!check && !dryRun) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content, 'utf8');
+    }
+  }
+  return { changed, counts, checked: check, dryRun };
+}
+
+// ---- CLI ----
+function main() {
+  const argv = process.argv.slice(2);
+  const rootIdx = argv.indexOf('--root');
+  const root = path.resolve(rootIdx >= 0 ? argv[rootIdx + 1] : process.cwd());
+  const check = argv.includes('--check');
+  const dryRun = argv.includes('--dry-run');
+  const res = syncMemoryWiki(root, { check, dryRun });
+  const summary = `claims=${res.counts.claims} incidents=${res.counts.incidents} lessons=${res.counts.lessons} papercuts=${res.counts.papercuts}`;
+  if (check) {
+    if (res.changed.length) {
+      console.error(`✗ memory-wiki 漂移：${res.changed.join(', ')}（${summary}）`);
+      return 1;
+    }
+    console.log(`✅ memory-wiki 最新（${summary}）`);
+    return 0;
+  }
+  if (dryRun) {
+    console.log(`dry-run: 将写 ${res.changed.length} 个文件（${summary}）`);
+    for (const rel of res.changed) console.log(`  ${rel}`);
+    return 0;
+  }
+  console.log(`memory-wiki: 更新 ${res.changed.length} 个文件（${summary}）`);
+  for (const rel of res.changed) console.log(`  ${rel}`);
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('memory-wiki.mjs');
+if (isMain) process.exit(main());