@fanchao8609/agent_brain_sync 0.1.0

package/src/todo.js

@@ -0,0 +1,308 @@
+// src/todo.js — todo.md 读写。CLI 的核心纯读写层（被 MCP 转接、可被 hook 直接调）。
+// 格式沿用 SKILL.md 契约：Backlog → Today / In Progress → Blocked → Done，半成品 `↳ 断点:`。
+import { promises as fs } from 'node:fs';
+import { brainPath } from './index.js';
+import { editFile, SKIP } from './lock.js';
+
+// ---------- 本地日期 ----------
+export function today() {
+  // 用本地时区取 YYYY-MM-DD（toISOString 是 UTC, 会跨天错一天）
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+// 本地日期时间 YYYY-MM-DD HH:MM（log 流水用）
+export function localStamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+// ---------- 读取 todo.md ----------
+export async function readTodo(brainRoot) {
+  const p = brainPath(brainRoot, 'todo.md');
+  let text;
+  try {
+    text = await fs.readFile(p, 'utf8');
+  } catch {
+    return ''; // 尚未创建，按空处理（不在此创建，避免读操作写文件）
+  }
+  const norm = normalizeTodo(text);
+  const grouped = groupDoneSection(norm); // 平铺旧 Done → 按日期分组（幂等）
+  if (grouped !== text) {
+    // 惰性迁移也是写：走锁，避免与并发写互相覆盖（锁内 re-read 已是权威最新内容）
+    await editFile(p, (cur) => (cur === text ? { text: grouped } : SKIP));
+    return grouped;
+  }
+  return text;
+}
+
+export async function ensureTodo(brainRoot) {
+  const p = brainPath(brainRoot, 'todo.md');
+  // 缺失才建模板；经锁写盘保证原子性（避免与并发 editFile 读到半写内容）
+  await editFile(p, (cur) => (cur === null ? { text: todoTemplate() } : SKIP));
+  return p;
+}
+
+export function todoTemplate() {
+  return [
+    '# 📋 Todo 看板',
+    '## Backlog',
+    '- [ ] 待办任务',
+    '## Today / In Progress',
+    '## Blocked',
+    '## Done（只留近期，旧的迁 log.md/快照）',
+    '',
+  ].join('\n');
+}
+
+/** 归一化 todo.md 分区：老格式（In Progress/Todo）迁移为 B4 定稿格式（Backlog→Today / In Progress→Blocked→Done）。
+ * 幂等：已是新格式则原样返回。迁移原则——老 "In Progress" 内容进 "Today / In Progress"，老 "Todo" 内容进 "Backlog"。 */
+export const TODO_SECTIONS = ['Backlog', 'Today / In Progress', 'Blocked', 'Done'];
+
+export function normalizeTodo(text) {
+  const lines = text.split('\n');
+  const has = (name) => lines.some((l) => l.trim() === `## ${name}`);
+  if (has('Backlog') || has('Today / In Progress')) return text; // 已是新格式
+  if (!has('In Progress') && !has('Todo')) return text;          // 不是老格式，不动
+  const out = ['# 📋 Todo 看板'];
+  const grab = (name) => {
+    const items = [];
+    let inSec = false;
+    for (const l of lines) {
+      if (l.startsWith('## ')) { inSec = l.trim() === `## ${name}`; continue; }
+      if (inSec && l.trim() && !isPlaceholder(l)) items.push(l);
+    }
+    return items;
+  };
+  const done = grab('Done');
+  const blocked = grab('Blocked');
+  const inprog = grab('In Progress');
+  const todo = grab('Todo');
+  out.push('## Backlog', ...todo.length ? todo : []);
+  out.push('## Today / In Progress', ...inprog.length ? inprog : []);
+  out.push('## Blocked', ...blocked.length ? blocked : []);
+  out.push('## Done（只留近期，旧的迁 log.md/快照）', ...done.length ? done : []);
+  return out.join('\n');
+}
+
+/** 从已完成任务行提取 `(完成 YYYY-MM-DD)` 日期；无则返回 ''。兼容中英文括号。 */
+export function doneDateOf(line) {
+  const m = String(line).match(/\(完成\s*(\d{4}-\d{2}-\d{2})[^)]*\)/);
+  return m ? m[1] : '';
+}
+
+/** 判断一行是否为任务行（- [x] / - [ ]，允许缩进）。 */
+function isTaskLine(l) {
+  return /^\s*- \[[ x]\]/.test(l);
+}
+/** 判断一行是否为任务附属行（↳ 开头）。 */
+function isChildLine(l) {
+  return /^\s*↳/.test(l);
+}
+
+/** 把 Done 区文本（bodyLines，不含 `## Done` 标题）解析成任务单元 [{ date, lines:[main,...children] }]。
+ * 剥 `### 日期` 分组标题与空行；任务行下紧跟的 ↳ 行并入该单元。 */
+function parseDoneUnits(bodyLines) {
+  const units = [];
+  let cur = null;
+  for (const l of bodyLines) {
+    if (/^### /.test(l.trim()) || l.trim() === '') { cur = null; continue; } // 分组标题/空行断开会话
+    if (isTaskLine(l)) {
+      cur = { date: doneDateOf(l), lines: [l] };
+      units.push(cur);
+    } else if (isChildLine(l) && cur) {
+      cur.lines.push(l); // 附属行挂到上一个任务
+    }
+  }
+  return units;
+}
+
+/** 按 (完成 date) 分组 Done 任务单元并重建文本行：新日期在前，未标日期归尾组。
+ * 同组内保持输入顺序（幂等）。返回不含 `## Done` 标题的主体行。 */
+function renderDoneGroups(units) {
+  const byDate = new Map();
+  const undated = [];
+  for (const u of units) {
+    if (!u.date) undated.push(u);
+    else {
+      if (!byDate.has(u.date)) byDate.set(u.date, []);
+      byDate.get(u.date).push(u);
+    }
+  }
+  const dates = [...byDate.keys()].sort().reverse(); // 新日期在前
+  const out = [];
+  for (const d of dates) out.push(`### ${d}`, '', ...byDate.get(d).flatMap((u) => u.lines), '');
+  if (undated.length) out.push('### （未标日期）', '', ...undated.flatMap((u) => u.lines), '');
+  return out;
+}
+
+/** 幂等：把 todo 全文里平铺的旧 Done 区按日期分组（新日期在前，未标日期归尾）。
+ * 已是分组态(### date)则原样返回——惰性迁移用，避免每次读都动文件。 */
+export function groupDoneSection(text) {
+  const lines = String(text || '').split('\n');
+  const di = lines.findIndex((l) => l.startsWith('## Done'));
+  if (di === -1) return text;
+  const body = lines.slice(di + 1);
+  const first = body.find((l) => l.trim());
+  if (first && /^### /.test(first.trim())) return text; // 已分组，幂等不动
+  const units = parseDoneUnits(body);
+  if (!units.length) return text;
+  return [...lines.slice(0, di + 1), ...renderDoneGroups(units)].join('\n').replace(/\n+$/, '\n');
+}
+
+/** 把 moved 单元（已完成任务行+附属行）放入 Done 区并整体按日期分组重建。
+ * 供 markDone 用，锁内一次完成「归位 + 分组」。无 Done 区则文件尾补建。 */
+export function insertDoneGrouped(text, movedLines) {
+  const date = doneDateOf(movedLines[0]) || today();
+  const lines = String(text || '').split('\n');
+  const di = lines.findIndex((l) => l.startsWith('## Done'));
+  const newUnit = { date, lines: movedLines };
+  if (di === -1) {
+    const header = '## Done（只留近期，旧的迁 log.md/快照）';
+    return [...lines, '', header, '', ...renderDoneGroups([newUnit])].join('\n').replace(/\n+$/, '\n');
+  }
+  const head = lines.slice(0, di + 1);
+  const body = lines.slice(di + 1);
+  // 新完成单元置前：同日期组内新在最上（renderDoneGroups 按 encounter 顺序保持，日期再倒序排）
+  const units = [newUnit, ...parseDoneUnits(body)];
+  return [...head, ...renderDoneGroups(units)].join('\n').replace(/\n+$/, '\n');
+}
+
+// 占位/空任务行（老模板的 "（无）"/"无"/纯 - [ ]）不迁移
+function isPlaceholder(line) {
+  const t = line.trim();
+  if (!/^- \[[ x]\]/.test(t)) return false; // 只判任务行
+  const body = t.replace(/^- \[[ x]\]\s*/, '').replace(/\(认领[^)]*\)/g, '').trim();
+  return !body || /^(无|（无）|None|null)$/.test(body);
+}
+/** 在指定分区段落后插入一行任务；找不到分区则在文件末尾追加回退。写前惰性迁移老格式。 */
+export async function addTask(brainRoot, { section, text }) {
+  const p = await ensureTodo(brainRoot);
+  await editFile(p, (orig) => ({ text: insertTask(orig, section, text) }));
+  return { file: p, text };
+}
+
+/** 纯函数：把任务行插到分区标题后。供 editFile mutator 复用（upsert 也用它）。 */
+function insertTask(orig, section, text) {
+  const base = normalizeTodo(orig);
+  const lines = base.split('\n');
+  const header = `## ${section}`;
+  let idx = lines.findIndex((l) => l.startsWith(header));
+  if (idx === -1) {
+    lines.push('', header, `- [ ] ${text}`);
+  } else {
+    // 在该分区标题后、下一个分区标题前插入
+    let insertAt = idx + 1;
+    while (insertAt < lines.length && !lines[insertAt].startsWith('## ')) insertAt++;
+    lines.splice(insertAt, 0, `- [ ] ${text}`);
+  }
+  return lines.join('\n');
+}
+
+/** 任务行解析：`- [ ] <id> — note (认领 date)` / 附属断点行 `↳ 断点:`。 */
+export function parseTaskLine(line) {
+  const m = line.match(/^- \[( |x)\] (.*?)(?: — (.*?))? \(?(认领|完成 \d{4}-\d{2}-\d{2}[^)]*)?\)?$/);
+  return m; // 保守解析；不匹配返回 null（附属行等）
+}
+
+/** 幂等登记：同 id 已有未完成任务行则原位更新（新 note/新认领日期），否则插入。 */
+export async function upsertTask(brainRoot, { section, text }) {
+  const p = await ensureTodo(brainRoot);
+  const id = extractId(text);
+  const note = extractNote(text);
+  const out = await editFile(p, (orig) => {
+    const base = normalizeTodo(orig);
+    const lines = base.split('\n');
+    // 在所有分区中找含该 id 的未完成任务行（Done 的已完成行不重复动）
+    const idx = lines.findIndex((l) => l.startsWith('- [ ]') && id && l.includes(id));
+    if (idx !== -1) {
+      // 原位更新：保留断点附属行，只换任务行本体
+      const oldNote = extractNote(lines[idx].replace(/^- \[ \] /, ''));
+      const merged = note && oldNote && oldNote.startsWith(note) ? `${note}${oldNote.slice(note.length)}` : note || oldNote;
+      const newLine = `- [ ] ${id}${merged ? ' — ' + merged : ''} (认领 ${today()})`;
+      lines[idx] = newLine;
+      return { text: lines.join('\n'), updated: true };
+    }
+    return { text: insertTask(base, section, text), updated: false };
+  });
+  return out.updated
+    ? { file: p, text, updated: true }
+    : { file: p, text, updated: false };
+}
+
+/** 从任务文本提取幂等键（行首 id，如 TASK-1 / T-2 / fix-hook）。 */
+export function extractId(text) {
+  const m = String(text).match(/^([A-Za-z][\w-]*)\b/);
+  return m ? m[1] : null;
+}
+
+/** 提取 " — " 后的 note 部分。 */
+export function extractNote(text) {
+  const i = String(text).indexOf(' — ');
+  return i === -1 ? '' : String(text).slice(i + 3).replace(/\s*\(认领[^)]*\)\s*$/, '');
+}
+
+/** 定位含 id 的未完成任务行下标；附属断点行（↳ 开头）不算任务行。 */
+export function findTaskLine(lines, id) {
+  if (!id) return -1;
+  return lines.findIndex((l) => l.startsWith('- [ ]') && l.includes(id));
+}
+
+/** 实时断点: 在 id 任务行下原位补/换 `↳ 断点:` 附属行（不挪任务位置）。 */
+export async function setBreakpoint(brainRoot, { id, text }) {
+  const p = await ensureTodo(brainRoot);
+  const bp = `  ↳ 断点: ${text}`;
+  const res = await editFile(p, (orig) => {
+    const lines = orig.split('\n');
+    const idx = findTaskLine(lines, id);
+    if (idx === -1) return SKIP;
+    if (lines[idx + 1] && lines[idx + 1].trimStart().startsWith('↳ 断点:')) {
+      lines[idx + 1] = bp; // 幂等: 更新原附属行
+    } else {
+      lines.splice(idx + 1, 0, bp);
+    }
+    return { text: lines.join('\n'), ok: true };
+  });
+  return res === SKIP
+    ? { ok: false, msg: `(未找到含 "${id}" 的未完成任务行)` }
+    : { ok: true, msg: `✓ 断点已落 → ${id}\n  ${bp.trim()}` };
+}
+
+/** 实时碰壁: 任务行原位勾成 blocked 语义（移入 Blocked 区 + 附原因）。 */
+export async function moveBlocked(brainRoot, { id, reason }) {
+  const p = await ensureTodo(brainRoot);
+  const res = await editFile(p, (orig) => {
+    const lines = orig.split('\n');
+    const idx = findTaskLine(lines, id);
+    if (idx === -1) return SKIP;
+    const taskLine = lines[idx];
+    const kept = [];
+    const moved = [taskLine];
+    for (let i = 0; i < lines.length; i++) {
+      if (i === idx) {
+        while (i + 1 < lines.length && lines[i + 1].trimStart().startsWith('↳')) moved.push(lines[++i]);
+        continue;
+      }
+      kept.push(lines[i]);
+    }
+    const bIdx = kept.findIndex((l) => l.startsWith('## Blocked'));
+    if (reason) moved.push(`  ↳ 卡点: ${reason}`);
+    const out = bIdx === -1
+      ? [...kept, '## Blocked', ...moved]
+      : [...kept.slice(0, bIdx + 1), ...moved, ...kept.slice(bIdx + 1)];
+    return { text: out.join('\n'), ok: true };
+  });
+  return res === SKIP
+    ? { ok: false, msg: `(未找到含 "${id}" 的未完成任务行)` }
+    : { ok: true, msg: `✓ 已标阻塞 → Blocked 区: ${id}${reason ? `\n  卡点: ${reason}` : ''}` };
+}
+
+// ---------- 看板输出 ----------
+export async function boardText(brainRoot, textOverride) {
+  const text = textOverride !== undefined ? textOverride : await readTodo(brainRoot);
+  const head = `📂 abs → 项目: ${brainRoot}`;
+  if (!text.trim()) return `${head}\n\n（todo.md 为空，先 abs task start 登记任务）`;
+  return `${head}\n\n${text.trim()}`;
+}

package/src/wrapup.js

@@ -0,0 +1,137 @@
+// src/wrapup.js — 收尾保险：把「某会话结束时 Today 仍滞留的任务」快照到 ~/.abs/log/wrapup.log。
+// 目标: 解决「任务做完了但没标 done 进 Done」的间歇性。根因是 done 判定只靠 agent 自觉,
+// Stop 若来不及/没意识到就滞留。这里不做判定(不替 agent 判断完成与否), 只做两件事:
+//   A) 机械快照(agent_end/Stop 触发 abs wrapup): 会话暂停时把当前未完成任务落盘一份结构清单;
+//   B) 开场对账(abs load 读取): 下会话 load 时把「上会话滞留、且当前仍未 done」的任务顶出来,
+//      让收尾成为开场的默认动作而非自愿的日志行。
+// wrapup.log 是全局技术日志(~/.abs/log/), 跨项目共用, 故每块带 proj=<root> 归属。
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { brainPath } from './index.js';
+import { readTodo, localStamp } from './todo.js';
+
+export function wrapupLogPath() {
+  return join(process.env.ABS_LOG_DIR || join(homedir(), '.abs', 'log'), 'wrapup.log');
+}
+
+// 同项目两次快照的最小间隔(秒)。agent_end 会逐 turn 触发, 无变化时不刷屏。
+export const WRAPUP_MIN_INTERVAL_MS = 5 * 60 * 1000;
+
+/** 从 todo 文本/快照块提取任务清单。兼容顶层(todo.md `- [ ]`)与缩进(快照 `  - [ ]`)两种行。
+ * body = 去掉 `- [ ]` 前缀、`(认领|完成 date)` 标注后的核心文本。bp 去掉 `↳ 断点|卡点: ` 前缀。
+ * Done 区（## Done 下）不采。返回 [{ body, bp }]，bp 为附属断点数组（或空）。 */
+export function extractOpenTasks(todoText) {
+  const lines = String(todoText || '').split('\n');
+  const out = [];
+  let inDone = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^##\s+Done/.test(l)) { inDone = true; continue; }
+    if (/^##\s+/.test(l)) { inDone = false; continue; }
+    if (inDone) continue;
+    const m = l.match(/^\s*- \[ \]\s*(.*)$/);
+    if (m) {
+      const taskBody = m[1]
+        .replace(/\s*\(认领[^)]*\)\s*$/, '')
+        .replace(/\s*\(完成[^)]*\)\s*$/, '')
+        .trim();
+      if (taskBody && !isPlaceholderBody(taskBody)) {
+        const bp = [];
+        while (i + 1 < lines.length && /^\s*↳/.test(lines[i + 1])) {
+          i++;
+          bp.push(lines[i].trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
+        }
+        out.push({ body: taskBody, bp });
+      }
+      continue;
+    }
+  }
+  return out;
+}
+
+/** 模板占位任务行（“待办任务”/无）不算真任务，快照/对账都排除。 */
+function isPlaceholderBody(body) {
+  return /^(待办任务|无|（无）|None|null)$/.test(body) || /^待办任务/.test(body);
+}
+
+/** 序列化一个快照块：首行时间戳+归属，后随未完成任务（主体+断点）。 */
+function blockText(root, tasks) {
+  const head = `[${localStamp()}] wrapup proj=${root}`;
+  if (!tasks.length) return head; // 无滞留，仍记一行「干净结束」
+  const rows = tasks.map((t) => {
+    const bps = t.bp.map((b) => `      ↳ 断点: ${b}`);
+    return `  - [ ] ${t.body}${bps.length ? '\n' + bps.join('\n') : ''}`;
+  });
+  return [head, ...rows].join('\n');
+}
+
+/** 从已有 wrapup.log 解析：按 proj 分组返回每个项目最近一次快照。逐行解析，鲁棒于多块/异常行。 */
+export function parseWrapup(text) {
+  const byProj = new Map(); // proj -> { stamp, proj, tasks:[{body,bp}] }
+  let cur = null;
+  let curProj = null;
+  for (const line of String(text || '').split('\n')) {
+    const h = line.match(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2})\] wrapup proj=(.+?)\s*$/);
+    if (h) {
+      curProj = h[2].trim();
+      cur = { stamp: h[1], proj: curProj, tasks: [] };
+      byProj.set(curProj, cur);
+      continue;
+    }
+    if (!cur) continue;
+    const tm = line.match(/^\s*- \[ \]\s*(.*)$/);
+    if (tm) {
+      const body = tm[1].replace(/\s*\(认领[^)]*\)\s*$/, '').trim();
+      if (body && !isPlaceholderBody(body)) {
+        cur.tasks.push({ body, bp: [] });
+      }
+      continue;
+    }
+    const bm = line.match(/^\s*↳/);
+    if (bm && cur.tasks.length) {
+      cur.tasks[cur.tasks.length - 1].bp.push(line.trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
+    }
+  }
+  return byProj;
+}
+
+/** B: 追加一次当前项目的滞留快照（幂等去重：同内容/短间隔内不重复写）。 */
+export async function appendWrapup(root) {
+  const p = wrapupLogPath();
+  await fs.mkdir(join(p, '..'), { recursive: true });
+  const todo = await readTodo(root); // readTodo 幂等迁移，拿到权威内容
+  const tasks = extractOpenTasks(todo);
+  let prev = '';
+  try { prev = await fs.readFile(p, 'utf8'); } catch { /* 尚无文件 */ }
+  const snap = parseWrapup(prev);
+  const last = snap.get(root);
+  if (last) {
+    const sameBody = JSON.stringify(last.tasks.map((t) => [t.body, ...t.bp]))
+      === JSON.stringify(tasks.map((t) => [t.body, ...t.bp]));
+    const lastMs = Date.parse(last.stamp.replace(' ', 'T'));
+    const fresh = !Number.isNaN(lastMs) && Date.now() - lastMs < WRAPUP_MIN_INTERVAL_MS;
+    if (sameBody && fresh) {
+      return `(同内容已落，跳过): ${root}`;
+    }
+  }
+  const line = blockText(root, tasks) + '\n';
+  await fs.appendFile(p, line, 'utf8');
+  return tasks.length
+    ? `✓ 滞留快照已落 wrapup.log (${tasks.length} 项未完成): ${root}`
+    : `✓ 干净结束已记 wrapup.log (无滞留): ${root}`;
+}
+
+/** A: 读 wrapup.log 里本项目的最近快照，返回其中「当前 todo 仍勾着未完成」的任务（已 done 自动消失）。
+ * 用于 load 开场展示滞留，跨 todo 交叉核对 → 无 false callout、自清理、不需 reconcile 标记。 */
+export async function strandedFor(root) {
+  const p = wrapupLogPath();
+  let text;
+  try { text = await fs.readFile(p, 'utf8'); } catch { return []; }
+  const snap = parseWrapup(text).get(root);
+  if (!snap || !snap.tasks.length) return [];
+  const todo = await readTodo(root).catch(() => '');
+  const openBodies = new Set(extractOpenTasks(todo).map((t) => t.body));
+  // 快照里那些「现在仍开着」的任务才是滞留；已 done（不在 openBodies）的自动剔除
+  return snap.tasks.filter((t) => openBodies.has(t.body));
+}