agentic-flow-kit 0.2.0

package/templates/_agents/roles/implementer.md

@@ -0,0 +1,46 @@
+# Implementer
+
+## 职责
+
+执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
+
+- 单文件或边界清晰的局部实现
+- 有明确复现路径的 bug 修复
+- 编写或调整任务直接要求的测试
+- 修复与任务直接相关的编译错误
+
+## 必需输入
+
+开始前必须获得：
+
+- 一句话任务目标
+- 必须读取的入口文档、spec 或 plan
+- 允许修改的文件清单
+- 可执行的验收条件
+
+任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
+
+## 行为边界
+
+- 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
+- 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
+- 复用现有实现、标准库和已安装依赖，保持最小工作 diff。
+- 不修改公共接口、数据 Schema、依赖、构建步骤、安全或权限策略。
+- 不执行提交、推送、发布、数据迁移或破坏性操作。
+- 不顺手重构、格式化或清理与任务无关的代码。
+
+## 验证
+
+- 运行任务指定的最小相关检查。
+- 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
+- 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
+
+## 输出
+
+返回给主智能体：
+
+1. 修改文件清单
+2. 每个文件的改动摘要
+3. 已运行的验证及结果
+4. 未解决的阻塞或剩余风险
+

package/templates/_agents/roles/independent-reviewer.md

@@ -0,0 +1,43 @@
+# Independent Reviewer
+
+## 职责
+
+在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。
+
+## 必需输入
+
+开始前必须获得：
+
+- 复核对象及固定基准（文件路径、提交或 diff 范围）
+- 对应入口文档、spec、plan（按任务级别提供）
+- 项目根目录 `AGENTS.md` + 改动域对应的目录级 `AGENTS.md`（如有）
+- 期望的复核结论或验收标准
+
+输入不足以确定范围时，停止并向主智能体报告。
+
+## 行为边界
+
+- 只读，不修改任何仓库文件。
+- 不替用户决定问题定性、方案取舍、合入或上线。
+- 不继承或猜测原作者未写入输入材料的推理。
+- 只报告能用具体文件、行号、行为或契约证明的问题。
+- 不把样式偏好、假设性风险或既有无关问题包装成缺陷。
+- 无法验证的事项明确标为未验证，不声称已经通过。
+
+## 复核重点
+
+1. 实现是否满足入口文档和验收标准
+2. 是否违反根 `AGENTS.md` 与改动域目录级 `AGENTS.md` 的架构、数据和所在域红线
+3. 是否改变未批准的公共契约或范围
+4. 是否缺少能防止回归的验证
+5. 是否存在数据丢失、安全、权限或发布风险
+
+## 输出
+
+按严重度输出问题清单：
+
+- `P0`：数据、安全、权限或必然阻断交付的问题
+- `P1`：功能错误、明确回归或违反项目硬约束
+- `P2`：非阻断但有证据的维护性问题
+
+每项必须包含：位置、问题、证据、建议。没有发现时明确输出“未发现阻断问题”，并列出未验证范围。

package/templates/_agents/roles/ui-verifier.md

@@ -0,0 +1,42 @@
+# UI Verifier
+
+## 职责
+
+对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
+
+## 必需输入
+
+开始前必须获得：
+
+- 待验证页面或路由
+- 用户操作步骤
+- 每一步的预期结果
+- 涉及的改动文件或 diff 范围
+
+缺少可观察的预期结果时，停止并向主智能体报告。
+
+## 执行
+
+1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
+2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
+3. 启动该技能指定的 API、前端和浏览器验证环境。
+4. 按输入步骤验证页面行为；布局类问题优先使用可重复的 DOM 几何数据。
+5. 收集控制台、网络请求、DOM 数据或截图等证据。
+6. 结束时关闭本次启动的后台进程。
+
+## 行为边界
+
+- 不修改代码、配置、测试数据或工作流文档。
+- 不自行修复发现的问题；将失败证据交还主智能体。
+- 不使用生产环境或真实业务数据。
+- 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
+
+## 输出
+
+返回：
+
+1. 验证环境与页面路由
+2. 逐项通过/失败结果
+3. 失败的复现步骤和证据
+4. 控制台或网络异常
+5. 未验证范围与阻塞项

package/templates/_agents/rule-budgets.txt

@@ -0,0 +1,8 @@
+# 常驻面体积预算（单源：check-loop.sh 检查 13（--all，WARN）与 .githooks/pre-commit（--staged，硬拦）共读）
+# 格式：<路径或 glob> <上限字节>；路径以 / 结尾表示目录合计。上限 = 当前实测 + 余量。
+# 超限含义：常驻面只增不减——须先删除或下沉被取代条目再增（一进一出）。
+# 本文件会被 core.autocrlf 检出为 CRLF，读取方（rule-budget.sh）已显式去 \r，禁止依赖行尾格式。
+# 口径：预算比较用「索引 / HEAD 字节」（git cat-file，LF 归一）；禁用工作区 wc -c 核对（CRLF 膨胀）。
+AGENTS.md 7680
+.agents/commands/*.md 8192
+.agents/commands/ 49152

package/templates/_agents/scripts/agg-delegations.cjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/* agg-delegations: 量化证据聚合
+ * 读 workflow/delegations.md 两张结果表（委派结果 / 自做任务结果）+ 扫 workflow/incidents/ 按月计数，
+ * 输出各月指标（一次通过率 / 平均返工次数 / 主兜底占比）、并发扩容门判定、可粘贴的月度快照行。
+ * 结果取值：一次通过 | 返工×N | 主兜底 | 返工待修（未闭环，不计入率）。
+ * 用法：node .agents/scripts/agg-delegations.cjs [--month=YYYY-MM]（默认输出全部月份 + 全量累计）
+ * 门槛定义见 workflow/delegations.md §并发扩容门槛，两处须同步改。
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const LEDGER = path.join(ROOT, 'workflow', 'delegations.md');
+const INCIDENTS = path.join(ROOT, 'workflow', 'incidents');
+
+const argMonth = (process.argv.find((a) => a.startsWith('--month=')) || '').split('=')[1] || null;
+
+function fail(msg) {
+  console.error(`agg-delegations: ${msg}`);
+  process.exit(1);
+}
+
+function parseTableRows(sectionText) {
+  return sectionText
+    .split(/\r?\n/)
+    .filter((l) => /^\|/.test(l.trim()))
+    .map((l) => l.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim()))
+    .filter((cols) => cols.length >= 2 && !/^[-: ]+$/.test(cols[1])) // 去表头分隔行
+    .filter((cols) => !/^\s*$/.test(cols[0]) && /^\d{4}-\d{2}-\d{2}$/.test(cols[0])); // 只留数据行（首列是日期）
+}
+
+function parseResult(raw) {
+  const r = (raw || '').trim();
+  if (/^一次通过$/.test(r)) return { kind: 'pass', rework: 0 };
+  const m = r.match(/^返工×(\d+)$/);
+  if (m) return { kind: 'rework', rework: parseInt(m[1], 10) };
+  if (/^主兜底$/.test(r)) return { kind: 'fallback', rework: 1 };
+  if (/^返工待修$/.test(r)) return { kind: 'pending', rework: 0 };
+  return { kind: 'unknown', rework: 0 };
+}
+
+function readLedger() {
+  if (!fs.existsSync(LEDGER)) fail(`找不到 ${LEDGER}`);
+  const text = fs.readFileSync(LEDGER, 'utf8');
+  const sections = {};
+  let cur = null;
+  for (const line of text.split(/\r?\n/)) {
+    const h = line.match(/^## (.+)$/);
+    if (h) cur = h[1].trim();
+    if (cur) (sections[cur] = sections[cur] || []).push(line);
+  }
+  const delegated = parseTableRows((sections['委派结果'] || []).join('\n')).map((c) => ({
+    scope: '委派',
+    date: c[0],
+    actor: c[1],
+    result: c[3] || '',
+  }));
+  const selfDone = parseTableRows((sections['自做任务结果'] || []).join('\n')).map((c) => ({
+    scope: '自做',
+    date: c[0],
+    actor: '主智能体',
+    result: c[2] || '',
+  }));
+  return delegated.concat(selfDone);
+}
+
+function countIncidents() {
+  const byMonth = {};
+  if (!fs.existsSync(INCIDENTS)) return byMonth;
+  for (const f of fs.readdirSync(INCIDENTS)) {
+    const m = f.match(/^(\d{4}-\d{2})-\d{2}.*\.md$/);
+    if (m) byMonth[m[1]] = (byMonth[m[1]] || 0) + 1;
+  }
+  return byMonth;
+}
+
+// 门槛（与 workflow/delegations.md §并发扩容门槛 同步）
+const GATE = { minSample: 20, minPassRate: 0.9, maxAvgRework: 0.3, minDelegated: 5, maxFallbackRate: 0.1 };
+
+function metrics(rows) {
+  const valid = rows.filter((r) => parseResult(r.result).kind !== 'pending' && parseResult(r.result).kind !== 'unknown');
+  const pending = rows.length - valid.length;
+  let pass = 0, reworkSum = 0, fallback = 0;
+  for (const r of valid) {
+    const p = parseResult(r.result);
+    if (p.kind === 'pass') pass += 1;
+    if (p.kind === 'fallback') fallback += 1;
+    reworkSum += p.rework;
+  }
+  const delegatedValid = valid.filter((r) => r.scope === '委派');
+  return {
+    total: valid.length,
+    pending,
+    pass,
+    passRate: valid.length ? pass / valid.length : null,
+    reworkSum,
+    avgRework: valid.length ? reworkSum / valid.length : null,
+    delegatedValid: delegatedValid.length,
+    fallback,
+    fallbackRate: delegatedValid.length ? fallback / delegatedValid.length : null,
+  };
+}
+
+function fmtRate(x, digits = 0) {
+  return x == null ? '—' : `${(x * 100).toFixed(digits)}%`;
+}
+function fmtNum(x) {
+  return x == null ? '—' : x.toFixed(2);
+}
+
+function gate(m, incidents) {
+  const items = [];
+  items.push({ no: 1, ok: m.total >= GATE.minSample, desc: `样本量 ${m.total}/${GATE.minSample}` });
+  items.push({
+    no: 2,
+    ok: m.passRate != null && m.passRate >= GATE.minPassRate,
+    desc: `一次通过率 ${fmtRate(m.passRate)}≥90%`,
+  });
+  items.push({
+    no: 3,
+    ok: m.avgRework != null && m.avgRework <= GATE.maxAvgRework,
+    desc: `平均返工 ${fmtNum(m.avgRework)}≤0.3`,
+  });
+  const delegOk = m.delegatedValid >= GATE.minDelegated && m.fallbackRate != null && m.fallbackRate <= GATE.maxFallbackRate;
+  items.push({
+    no: 4,
+    ok: delegOk,
+    desc: `委派样本 ${m.delegatedValid}≥5 且主兜底 ${fmtRate(m.fallbackRate)}≤10%`,
+  });
+  items.push({ no: 5, ok: null, desc: '门禁不失守（人工对照当月 incident 定性）' });
+  const hardOk = items.filter((i) => i.ok !== null).every((i) => i.ok);
+  const bad = items.filter((i) => i.ok === false).map((i) => i.no).join('+');
+  return { items, verdict: hardOk ? '✅（待人工确认门5）' : `❌ 未达标项:${bad}` };
+}
+
+function main() {
+  const rows = readLedger();
+  const incidents = countIncidents();
+
+  const byMonth = {};
+  for (const r of rows) {
+    const ym = r.date.slice(0, 7);
+    (byMonth[ym] = byMonth[ym] || []).push(r);
+  }
+  const months = Object.keys(byMonth).sort().filter((m) => !argMonth || m === argMonth);
+
+  console.log(`# 量化证据聚合（${argMonth || '全部月份'}） 生成于 ${new Date().toISOString().slice(0, 10)}\n`);
+
+  const snapshotRows = [];
+  for (const ym of months) {
+    const m = metrics(byMonth[ym]);
+    const g = gate(m, incidents[ym] || 0);
+    console.log(`## ${ym}`);
+    console.log(`  有效任务 ${m.total}（待修 ${m.pending}）｜一次通过 ${m.pass}（${fmtRate(m.passRate)}）｜返工总次数 ${m.reworkSum}（平均 ${fmtNum(m.avgRework)}）｜主兜底 ${m.fallback}/${m.delegatedValid}（${fmtRate(m.fallbackRate)}）｜incident ${incidents[ym] || 0} 起`);
+    for (const i of g.items) console.log(`  门${i.no} ${i.ok === null ? '[人工]' : i.ok ? '✅' : '❌'} ${i.desc}`);
+    console.log(`  扩容门判定：${g.verdict}\n`);
+    snapshotRows.push(`| ${ym} | ${m.total} | ${fmtRate(m.passRate)} | ${fmtNum(m.avgRework)} | ${fmtRate(m.fallbackRate)} | ${incidents[ym] || 0} | ${g.verdict} | 样本含待修${m.pending} |`);
+  }
+
+  if (!argMonth && rows.length) {
+    const m = metrics(rows);
+    console.log(`## 全量累计`);
+    console.log(`  有效任务 ${m.total}（待修 ${m.pending}）｜一次通过 ${fmtRate(m.passRate)}｜平均返工 ${fmtNum(m.avgRework)}｜主兜底 ${fmtRate(m.fallbackRate)}｜incident 合计 ${Object.values(incidents).reduce((a, b) => a + b, 0)} 起\n`);
+  }
+
+  console.log(`## 可粘贴快照行（粘到 workflow/delegations.md §月度聚合快照）`);
+  for (const r of snapshotRows) console.log(r);
+
+  if (!rows.length) {
+    console.log('\n（台账为空：尚无记录，扩容门自然未通过）');
+  }
+}
+
+main();