@fanchao8609/agent_brain_sync 1.18.0 → 1.19.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanchao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -108,7 +108,9 @@ abs load                       # 开机读状态（Rules + 图谱计数 + 看板
 abs todo                       # 看板 Todo / Done（行首带状态标记）
 
 abs todo add     TASK-1 --note "要做什么"
-abs todo note    TASK-1 --note "改到 X 文件 L40"   # 实时断点（一句话，上看板）
+abs todo note    TASK-1 --note "改到 X 文件 L40"   # 追加一条子项（标准 md 嵌套列表，可多条）
+abs todo bp-done TASK-1 [--n 2]                  # 勾子项（n=第几条，缺省最后一条）
+abs todo bp-undone TASK-1 [--n 2]                # 取消勾（勾错了退回）
 abs todo memo    TASK-1 "随手记一段（可多句，不上看板）"   # 任务笔记 → sessions/；无参=查看
 abs todo state   TASK-1 --note "进行中|讨论中|滞留中"   # 改行首状态标记
 abs todo done    TASK-1
@@ -129,6 +131,9 @@ abs update                                # 升级到最新版并刷新四宿主
 ```
 
 > `abs todo start` 与 `abs todo add` 等价（都登记任务）。
+> **子项就是标准 Markdown 嵌套列表**：任务下缩进 2 空格的 `- [ ] …`，可多条、可各自勾选；
+> 面板按缩进画树线，归档时原样保留缩进。旧格式 `↳ 断点:` 仍能读（存量不坏）。
+> 任务 id 不能含空格（用连字符），含空格会被明确拒掉。
 > 旧版 `abs task ...` / `abs board` 已废，打它们会报「未知命令」并退出码 1。
 > `abs wrapup` / `abs teardown-check` 是 hook 内部命令，无需手动调用。
 > **作者名要填真的**：`tester` / `foo` / `aaa` 这类占位名会被拒 —— 因为 `{user}` 是全局单值，

package/bin/abs.js

@@ -116,6 +116,8 @@ const FLAG_SPEC = {
   'title': { type: 'string' },
   'desc': { type: 'string' },
   'state': { type: 'string' },
+  // 勾子项用：第几条（1-based，缺省=最后一条）
+  'n': { type: 'string' },
   // log 流水类型：note|dev|concept|ingest（cmdLog 会校枚举，非枚举直接报错）。
   // ★ 漏声明就是真 bug（2026-10-05 本机实测）：不在 FLAG_SPEC 的选项会被静默丢掉，
   //   于是 `abs log "x" --kind note` 全写成默认的 dev，而 cmdLog 的枚举校验看不见它。
@@ -310,6 +312,8 @@ const subUsage = {
     '  abs todo add <id> [--note "做什么"] [--section 讨论中|滞留中|搁置]',
     '  abs todo rename <旧id> --note "<新id>"   改任务 id（起错名/不可读时）',
     '  abs todo note <id> --note "断点/进度"',
+    '  abs todo bp-done <id>            勾断点 → `↳ [x] 断点:`（做完落一句）',
+    '  abs todo bp-undone <id>          取消勾（勾错了退回）',
     '  abs todo memo <id> "随手记（可多句）"  任务笔记 → sessions/，不上看板；无文字=查看',
     '  abs todo state <id> --note 进行中|讨论中|滞留中|搁置',
     '  abs todo done <id> [--as 落地|否决|仅方案] [结语文字]',
@@ -374,6 +378,8 @@ const TODO_ACTIONS = {
   add: 'start',
   start: 'start', // add 的别名(老习惯保留)
   note: 'note',
+  'bp-done': 'bp-done', // 勾断点：`↳ [ ] 断点:` → `↳ [x] 断点:`
+  'bp-undone': 'bp-undone', // 取消勾断点（勾错了退回）
   memo: 'memo', // 任务随手记：多句/追加/不占看板（无文字时=查看）
   state: 'state', // 改行首状态标记：进行中|讨论中|滞留中|搁置（原地，不搬区）
   rename: 'rename', // 改任务 id：人工起错名、或旧 id 不可读时用
@@ -469,7 +475,7 @@ async function main() {
         if (!action) {
           throw new Error(
             `✗ 未知子命令 "${sub}"\n` +
-            `  可用: add / start / note / memo / state / done / archive\n` +
+            `  可用: add / start / note / bp-done / bp-undone / memo / state / done / archive\n` +
             `  看板: abs todo（不带参数）\n` +
             `  登记任务: abs todo add <id> --note "做什么"`,
           );
@@ -492,6 +498,15 @@ async function main() {
           console.log(await cmdTask({ dir: opts.dir, action, id, note, session: opts.session }));
           break;
         }
+        // 勾/取消勾子项：只收 <id>（子项位置 = 「某任务的第 N 条」，没有自己的 id）
+        if (action === 'bp-done' || action === 'bp-undone') {
+          rejectExtra(rest2, `abs todo ${sub} <id> [--n N]`);
+          if (!id) throw new Error(`✗ 缺 <id>\n  用法: abs todo ${sub} <id> [--n N]`);
+          const n = opts.n ? Number(opts.n) : undefined;
+          if (opts.n && (!Number.isInteger(n) || n < 1)) throw new Error(`✗ --n 要是正整数（收到 "${opts.n}"）`);
+          console.log(await cmdTask({ dir: opts.dir, action, id, n }));
+          break;
+        }
         rejectExtra(rest2, usage);
         if (!id) throw new Error(`✗ 缺 <id>\n  用法: ${usage}`);
         console.log(await cmdTask({ dir: opts.dir, action, id, section: opts.section, note: opts.note, as: opts.as, session: opts.session }));

package/bin/mcp.js

@@ -112,12 +112,12 @@ tool(
 
 tool(
   'abs_task',
-  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补断点(改到哪文件哪行) / memo 任务随手记（多句/追加/不上看板）/ state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。必填: cwd, action, id。多会话并行时，start/add 带上 session（值见 system prompt 的 [会话] 段）以标记「这条任务谁在做」。',
+  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补子项（**追加**，标准 md 嵌套列表，`abs todo note`）/ bp_done、bp_undone 勾/取消勾子项（n=第几条，缺省最后一条）/ memo 任务随手记（多句/追加/不上看板）/ state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。必填: cwd, action, id。多会话并行时，start/add 带上 session（值见 system prompt 的 [会话] 段）以标记「这条任务谁在做」。',
   {
-    action: z.enum(['add', 'start', 'done', 'note', 'memo', 'state']),
+    action: z.enum(['add', 'start', 'done', 'note', 'bp_done', 'bp_undone', 'memo', 'state']),
     id: z.string().describe('任务幂等键，如 TASK-xxx 或子任务名'),
-    cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
-    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步，一句话); memo=随手记（可多句、不定长，追加式；不传=查看已有笔记）; state=进行中|讨论中|滞留中|搁置（搁置=用户改方向/不做了；滞留中=还要做只是卡住）; done=结语文字'),
+    n: z.number().int().positive().optional().describe('bp_done/bp_undone 用：第几条子项（1-based，缺省=最后一条）'),
+    cwd: z.string().describe('项目根目录（.brain/ 所在处）'),    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步，一句话); memo=随手记（可多句、不定长，追加式；不传=查看已有笔记）; state=进行中|讨论中|滞留中|搁置（搁置=用户改方向/不做了；滞留中=还要做只是卡住）; done=结语文字'),
     as: z.enum(['落地', '否决', '仅方案']).optional().describe('仅 done：结语类型。默认 落地。做了又撤/评估后不做用 否决，只设计过用 仅方案 —— 别让假【落地】污染看板'),
     // 会话 id：多会话并行时标记「这条任务是谁在做」。
     // 值取自 system prompt 里的 `[会话] 本会话 id = xxx`（hook 注入），由模型原样回传。
@@ -125,12 +125,14 @@ tool(
     //   （协议没有，PI_* 环境变量也没有）；模型本来就知道自己的 sid，直接收下最省。
     session: z.string().optional().describe('仅 start/add：本会话 id（取自 system prompt 的 [会话] 段）。多会话并行时用来标记「这条任务谁在做」'),
   },
-  async ({ action, id, cwd, note, as, session }) => {
+  async ({ action, id, cwd, note, as, session, n }) => {
     const root = await findBrainRoot(cwd || process.cwd());
     if (!root) return errNoBrain(cwd || process.cwd());
     // add 是 start 的别名（与 CLI `abs todo add` 对齐）
     const act = action === 'add' ? 'start' : action;
-    return { content: [{ type: 'text', text: await cmdTask({ dir: root, action: act, id, note, as, session }) }] };
+    // bp_done → bp-done（MCP 参数名不用连字符，内部 action 用）
+    const act2 = act === 'bp_done' ? 'bp-done' : act === 'bp_undone' ? 'bp-undone' : act;
+    return { content: [{ type: 'text', text: await cmdTask({ dir: root, action: act2, id, note, as, session, n }) }] };
   }
 );
 

package/hooks/abs.omp.ts

@@ -230,7 +230,9 @@ export function boardGuideline(md: string, who: string, touched: string[] = [],
     let tag = ''
     if (r.sid) tag = r.sid === mySid ? '[本会话] ' : `[会话 ${r.sid}] `
     const head = `  ${tag}${r.state ? `[${r.state}] ` : ''}${r.id}${r.desc ? ` — ${r.desc}` : ''}`
-    return r.note ? `${head}\n    ↳ ${r.note}` : head
+    // 子项带上（与面板同形），丢了等于对齐了也接不上
+    if (!r.kids || !r.kids.length) return head
+    return [head, ...r.kids.map((k) => `    - ${k.done ? '[x]' : '[ ]'} ${k.text}`)].join('\n')
   })
   const more = total > rows.length ? `  …另 ${total - rows.length} 条` : ''
   const touchLines = touched.length
@@ -349,12 +351,12 @@ export function pickNickname(rnd: () => number = Math.random): string {
  * （老任务/手写的没标，漏掉比多显示更糟）。标了别人的则不收。 */
 export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
   total: number
-  rows: { state: string; id: string; desc: string; note: string; sid: string }[]
+  rows: { state: string; id: string; desc: string; kids: { done: boolean; text: string }[]; sid: string }[]
   hidden: number
 } {
   // 两阶段：先无过滤地按序解析（断点归属需要「上一条」是原文里真正的前一条），
   // 再按作者过滤。若边解析边过滤，被滤掉的条目下方的断点会挂到它上面那一条。
-  type Row = { state: string; id: string; desc: string; note: string; authors: string[]; sid: string }
+  type Row = { state: string; id: string; desc: string; kids: { done: boolean; text: string }[]; authors: string[]; sid: string }
   const parsed: Row[] = []
   let inTodo = false
   for (const raw of String(md || '').split('\n')) {
@@ -362,11 +364,11 @@ export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
     if (/^##\s+Todo\s*$/.test(line)) { inTodo = true; continue }
     if (/^##\s+/.test(line)) { inTodo = false; continue }
     if (!inTodo) continue
-    // 断点行：`  ↳ 断点: …`（缩进）→ 挂到上一条任务
-    const note = line.match(/^\s+↳\s*断点:\s*(.*)$/)
-    if (note) {
+    // 子项行（标准 md：缩进的 `- [ ]`；旧格式 `↳ 断点:` 继续认）→ 挂到上一条任务
+    const kid = parseChildLine(line)
+    if (kid && kid.indent > 0) {
       const last = parsed[parsed.length - 1]
-      if (last && !last.note) last.note = note[1].trim()
+      if (last) last.kids.push(kid)
       continue
     }
     // `- [ ] [状态] <id> …`；状态标记可能缺省。
@@ -386,12 +388,12 @@ export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
       .replace(/^\s*—\s*/, '')
       .replace(/\s*\(认领[^)]*\)\s*$/, '')
       .trim()
-    parsed.push({ state, id, desc, note: '', authors, sid })
+    parsed.push({ state, id, desc, kids: [], authors, sid })
   }
   const mine = who
     ? parsed.filter((r) => r.authors.length === 0 || r.authors.includes(who))
     : parsed
-  const rows = mine.map(({ state, id, desc, note, sid }) => ({ state, id, desc, note, sid }))
+  const rows = mine.map(({ state, id, desc, kids, sid }) => ({ state, id, desc, kids, sid }))
   return { total: rows.length, rows: rows.slice(0, max), hidden: Math.max(0, rows.length - max) }
 }
 
@@ -413,6 +415,19 @@ async function currentUser(): Promise<string> {
 /** 按显示宽度截断（自己实现，不 import 宿主 tui 包）。
  *  依赖宿主内部 alias 太脆 —— pi 版实测在测试环境会 ERR_MODULE_NOT_FOUND。
  *  宽度规则：CJK/全角记 2 列，其余记 1 列。 */
+/** 解析子项行（与 src/todo/common.js 的 parseChild 同规则，双份实现 —— 见 pi 版说明）。 */
+function parseChildLine(l: string): { done: boolean; text: string; indent: number } | null {
+  const s = String(l || '')
+  const old = s.match(/^(\s*)↳\s*(?:\[[ x]\]\s*)?(?:断点[:：]\s*)?(.*)$/)
+  if (old) {
+    if (!old[2].trim()) return null
+    return { done: /^\s*↳\s*\[x\]/.test(s), text: old[2].trim(), indent: old[1].length }
+  }
+  const m = s.match(/^(\s+)-\s*\[([ x])\]\s*(.*)$/)
+  if (!m) return null
+  return { done: m[2] === 'x', text: m[3].trim(), indent: m[1].length }
+}
+
 function dispWidth(s: string): number {
   let w = 0
   let i = 0
@@ -493,7 +508,7 @@ export function todoAnimFrame(phase: number): string {
 }
 
 export function renderPanelLines(
-  data: { total: number; rows: { state: string; id: string; desc: string; note: string }[]; hidden: number },
+  data: { total: number; rows: { state: string; id: string; desc: string; kids?: { done: boolean; text: string }[] }[]; hidden: number },
   who: string,
   width: number,
   fg: (color: string, s: string) => string,
@@ -521,12 +536,21 @@ export function renderPanelLines(
     const isLast = i === lastIdx
     const branch = isLast ? '└─' : '├─'
     const anim = t.state === '进行中' && animPhase >= 0 ? ' ' + fg('accent', todoAnimFrame(animPhase)) : ''
-    const head = `${fg('dim', branch)} ${fg(colorOf(t.state), `[${t.state}]`)} ${fg('text', t.id)}${anim}`
+    // 复选框 `[ ]`：面板是 todo.md 的只读视图，就该长成 todo 原貌。
+    const box = fg('dim', '[ ]')
+    const head = `${fg('dim', branch)} ${box} ${fg(colorOf(t.state), `[${t.state}]`)} ${fg('text', t.id)}${anim}`
     const desc = t.desc ? ` ${fg('dim', '—')} ${fg('muted', t.desc)}` : ''
     lines.push(clipToWidth(head + desc, width))
-    if (t.note) {
-      const cont = isLast ? '  ' : fg('dim', '│ ')
-      lines.push(clipToWidth(`${cont} ${fg('dim', '↳ ' + t.note)}`, width))
+    if (t.kids && t.kids.length) {
+      // 子项：标准 md 嵌套列表 → 画成树
+      const stem = isLast ? '  ' : fg('dim', '│ ')
+      const n = t.kids.length
+      t.kids.forEach((k, ki) => {
+        const kb = ki === n - 1 ? '└─' : '├─'
+        const kbox = fg('dim', k.done ? '[x]' : '[ ]')
+        const ktext = fg(k.done ? 'dim' : 'muted', k.text)
+        lines.push(clipToWidth(`${stem} ${fg('dim', kb)} ${kbox} ${ktext}`, width))
+      })
     }
   })
 

package/hooks/abs.pi.ts

@@ -336,8 +336,11 @@ export function boardGuideline(md: string, who: string, touched: string[] = [],
     let tag = ''
     if (r.sid) tag = r.sid === mySid ? '[本会话] ' : `[会话 ${r.sid}] `
     const head = `  ${tag}${r.state ? `[${r.state}] ` : ''}${r.id}${r.desc ? ` — ${r.desc}` : ''}`
-    // 断点必须带上：它就是「改到哪一步」，丢了等于对齐了也接不上。
-    return r.note ? `${head}\n    ↳ ${r.note}` : head
+    // 子项必须带上：它就是「改到哪一步」，丢了等于对齐了也接不上（2026-10-05 实测）。
+    // 与面板同形（`- [ ]` 缩进），让 LLM 看到的就是文件里的结构。
+    if (!r.kids || !r.kids.length) return head
+    const kidLines = r.kids.map((k) => `    - ${k.done ? '[x]' : '[ ]'} ${k.text}`)
+    return [head, ...kidLines].join('\n')
   })
   const more = total > rows.length ? `  …另 ${total - rows.length} 条` : ''
   // 本会话动过的文件 —— 与看板并列摆出，让 LLM 自己对照（不判断算不算任务）。
@@ -717,13 +720,13 @@ export function pickNickname(rnd: () => number = Math.random): string {
  * 断点行（缩进的 ↳）归属到它上一条任务，不单独成条。 */
 export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
   total: number
-  rows: { state: string; id: string; desc: string; note: string; sid: string }[]
+  rows: { state: string; id: string; desc: string; kids: { done: boolean; text: string }[]; sid: string }[]
   hidden: number
 } {
   // 两阶段：先无过滤地按序解析（断点归属需要“上一条”是原文里真正的前一条），
   // 再按作者过滤。若边解析边过滤，被滤掉的条目下方的断点会挂到它上面那一条
   // —— 实测：别人任务的断点会显示在我的任务下面（2026-10-03 审查发现）。
-  type Row = { state: string; id: string; desc: string; note: string; authors: string[]; sid: string }
+  type Row = { state: string; id: string; desc: string; kids: { done: boolean; text: string }[]; authors: string[]; sid: string }
   const parsed: Row[] = []
   let inTodo = false
   for (const raw of String(md || '').split('\n')) {
@@ -731,11 +734,12 @@ export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
     if (/^##\s+Todo\s*$/.test(line)) { inTodo = true; continue }
     if (/^##\s+/.test(line)) { inTodo = false; continue }
     if (!inTodo) continue
-    // 断点行：`  ↳ 断点: …`（缩进）→ 挂到上一条任务
-    const note = line.match(/^\s+↳\s*断点:\s*(.*)$/)
-    if (note) {
+    // 子项行（标准 md：缩进的 `- [ ]`；旧格式 `↳ 断点:` 继续认）→ 挂到上一条任务。
+    // 子项可多条、可各自勾选（2026-10-16 用户定）。
+    const kid = parseChildLine(line)
+    if (kid && kid.indent > 0) {
       const last = parsed[parsed.length - 1]
-      if (last && !last.note) last.note = note[1].trim()
+      if (last) last.kids.push(kid)
       continue
     }
     // `- [ ] [状态] <id> …`；状态标记可能缺省。
@@ -760,12 +764,12 @@ export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
       .replace(/^\s*—\s*/, '')
       .replace(/\s*\(认领[^)]*\)\s*$/, '')
       .trim()
-    parsed.push({ state, id, desc, note: '', authors, sid })
+    parsed.push({ state, id, desc, kids: [], authors, sid })
   }
   const mine = who
     ? parsed.filter((r) => r.authors.length === 0 || r.authors.includes(who))
     : parsed
-  const rows = mine.map(({ state, id, desc, note, sid }) => ({ state, id, desc, note, sid }))
+  const rows = mine.map(({ state, id, desc, kids, sid }) => ({ state, id, desc, kids, sid }))
   return { total: rows.length, rows: rows.slice(0, max), hidden: Math.max(0, rows.length - max) }
 }
 
@@ -792,6 +796,23 @@ async function currentUser(): Promise<string> {
  *
  * 宽度规则：CJK/全角记 2 列，其余记 1 列。足够让面板不溢出（不能处理 emoji ZWJ 序列，
  * 但面板里没有—— todo 内容是任务名与说明）。 */
+/** 解析子项行（与 src/todo/common.js 的 parseChild 同规则，双份实现）。
+ *
+ * 为何不 import src：面板是宿主扩展，单独装到 ~/.pi/extensions/，与包内 src/ 不同目录
+ * （装完就断了）。故两端各一份 —— 规则简单（两步正则），且两边测试都盖。
+ * 标准 md：缩进的 `- [ ] 内容`；旧格式 `↳ [ ] 断点: 内容` / `↳ 断点: 内容` 继续认。 */
+function parseChildLine(l: string): { done: boolean; text: string; indent: number } | null {
+  const s = String(l || '')
+  const old = s.match(/^(\s*)↳\s*(?:\[[ x]\]\s*)?(?:断点[:：]\s*)?(.*)$/)
+  if (old) {
+    if (!old[2].trim()) return null
+    return { done: /^\s*↳\s*\[x\]/.test(s), text: old[2].trim(), indent: old[1].length }
+  }
+  const m = s.match(/^(\s+)-\s*\[([ x])\]\s*(.*)$/)
+  if (!m) return null
+  return { done: m[2] === 'x', text: m[3].trim(), indent: m[1].length }
+}
+
 function dispWidth(s: string): number {
   let w = 0
   let i = 0
@@ -887,7 +908,7 @@ export function todoAnimFrame(phase: number): string {
 }
 
 export function renderPanelLines(
-  data: { total: number; rows: { state: string; id: string; desc: string; note: string }[]; hidden: number },
+  data: { total: number; rows: { state: string; id: string; desc: string; kids?: { done: boolean; text: string }[] }[]; hidden: number },
   who: string,
   width: number,
   fg: (color: string, s: string) => string,
@@ -931,13 +952,26 @@ export function renderPanelLines(
     const branch = isLast ? '└─' : '├─'
     // 进行中的行带一个小动画（其余行不加，避免满屏都在跳）
     const anim = t.state === '进行中' && animPhase >= 0 ? ' ' + fg('accent', todoAnimFrame(animPhase)) : ''
-    const head = `${fg('dim', branch)} ${fg(colorOf(t.state), `[${t.state}]`)} ${fg('text', t.id)}${anim}`
+    // 复选框 `[ ]`（2026-10-16 用户要求）：面板是 todo.md 的只读视图，
+    // 就该长成 todo 原貌 —— 摆成与文件里 `- [ ]` 同形，读到就认得出对应哪一行。
+    const box = fg('dim', '[ ]')
+    const head = `${fg('dim', branch)} ${box} ${fg(colorOf(t.state), `[${t.state}]`)} ${fg('text', t.id)}${anim}`
     const desc = t.desc ? ` ${fg('dim', '—')} ${fg('muted', t.desc)}` : ''
     lines.push(clipToWidth(head + desc, width))
-    if (t.note) {
-      // 断点行：挂在父任务下。末条时用空格对齐（└─ 下方无续）；否则用 │ 延伸。
-      const cont = isLast ? '  ' : fg('dim', '│ ')
-      lines.push(clipToWidth(`${cont} ${fg('dim', '↳ ' + t.note)}`, width))
+    if (t.kids && t.kids.length) {
+      // 子项：标准 md 嵌套列表 → 画成树
+      //   ├─ [ ] 子项一
+      //   └─ [x] 子项二
+      // 树线前缀 = 父任务的 │（非末条）或空格（末条），与父任务分支对齐。
+      // 勾过的用 dim 压暗（一眼看出哪些已完成），未勾用正常色。
+      const stem = isLast ? '  ' : fg('dim', '│ ')
+      const n = t.kids.length
+      t.kids.forEach((k, ki) => {
+        const kb = ki === n - 1 ? '└─' : '├─'
+        const kbox = fg('dim', k.done ? '[x]' : '[ ]')
+        const ktext = fg(k.done ? 'dim' : 'muted', k.text)
+        lines.push(clipToWidth(`${stem} ${fg('dim', kb)} ${kbox} ${ktext}`, width))
+      })
     }
   })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "abs": "node bin/abs.js",
     "mcp": "node bin/mcp.js",
     "test": "node --test 'test/*.test.js' 'skill/**/*.test.js'",
+    "fuzz": "node scripts/fuzz.mjs 800",
     "lint": "eslint .",
     "check": "node --experimental-vm-modules --no-warnings scripts/check-syntax.mjs && eslint .",
     "prepack": "node -e \"require('fs').chmodSync('bin/abs.js',0o755);require('fs').chmodSync('bin/mcp.js',0o755)\"",

package/src/lint.js

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { requireBrain, brainPath, BRAIN_DIR } from './index.js';
 import { readRules, idOfPage, statusOfPage, supersededByOf, clip, RULE_BODY_MAX } from './store.js';
 import { doneKindOf, doneDateOf, checkFileShape, TODO_MAX_LINES, LOG_MAX_LINES, INDEX_MAX_LINES } from './todo.js';
-import { isAllowedTodoLine, todoSectionOf } from './todo/common.js';
+import { isAllowedTodoLine, todoSectionOf, parseChild } from './todo/common.js';
 
 // ---------- 图谱遍历 ----------
 
@@ -143,8 +143,10 @@ async function checkRootFiles(vault) {
           `总结/报告/清单请分流：流水 → abs log，经验 → abs note，长设计 → sources/)`,
         );
       }
-      if (!l.trimStart().startsWith('↳ 断点:')) continue;
-      const bp = l.trimStart().slice('↳ 断点:'.length).trim();
+      // 断点行（新旧格式同一个解析器 —— 不再自己切前缀）
+      const bpLine = parseChild(l);
+      if (!bpLine) continue;
+      const bp = bpLine.text;
       if (bp.length > LINT_BREAKPOINT_MAX) {
         issues.push(
           `TODO-BREAKPOINT-BLOAT: ${BRAIN_DIR}/${file}:${i + 1} (断点 ${bp.length} 字 > ${LINT_BREAKPOINT_MAX}；` +
@@ -329,8 +331,12 @@ async function checkFiles(vault, pages, indexLinks) {
     if (doneLines > DONE_MAX) {
       issues.push(`DONE-PILED-UP: Done 区 ${doneLines} 行 > ${DONE_MAX}; 跑 \`abs todo archive\` 迁出旧日期组`);
     }
+    // ★ 只数**顶格**任务行（缩进 0）—— 子项也是 `- [x]`，带 \s* 会把子项一起算进来，
+    //   于是「父任务有结语有日期、子项没有」也被报成缺结语（实测 DONE-NO-KIND 误报
+    //   一条子项 `- [x] 不急，等下次碰这块再拆`）。与 archive.js 数任务时的判据保持一致。
+    const isTopDone = (l) => /^- \[x\]/.test(l);
     const doneBody = todoTxt.split('\n').slice(di + 1);
-    const noKind = doneBody.filter((l) => /^\s*- \[x\]/.test(l) && !doneKindOf(l));
+    const noKind = doneBody.filter((l) => isTopDone(l) && !doneKindOf(l));
     if (noKind.length) {
       const sample = (noKind[0].match(/- \[x\] (\S+)/) || [, '?'])[1];
       issues.push(
@@ -338,7 +344,7 @@ async function checkFiles(vault, pages, indexLinks) {
         `逐条补 \`--as 落地|否决|仅方案\`（新条目：abs todo done <id> --as …）`,
       );
     }
-    const noDate = doneBody.filter((l) => /^\s*- \[x\]/.test(l) && !doneDateOf(l));
+    const noDate = doneBody.filter((l) => isTopDone(l) && !doneDateOf(l));
     if (noDate.length) {
       const sample = (noDate[0].match(/- \[x\] (\S+)/) || [, '?'])[1];
       issues.push(

package/src/lock.js

@@ -14,6 +14,24 @@ export class LockTimeout extends Error {}
  * 返回 null = 该文件不归闸门管；否则返回整理后的 text。 */
 let formatGate = null;
 export function setFormatGate(fn) { formatGate = fn; }
+
+/** 三个受管文件名 —— 它们存在就是为了当“数据库表”，格式必须恒定。 */
+const MANAGED = new Set(['index.md', 'log.md', 'todo.md']);
+
+/** 懒加载闸门：**漏了 setFormatGate 就等于没闸门**，而注册是 import 副作用，
+ *  谁少 import 一次 store.js 就静默裂开（2026-10-18 实测：只 import lock.js 时
+ *  裸散文直接写进了 index.md）。故这里不信任外部注册，缺失时自己补上。
+ *
+ * 补不上（= store.js 没调 setFormatGate）就对受管文件硬拒：宁可写失败也不要格崩坏
+ * ——写不进去能重试，写脏了没人知道。 */
+async function gateFor(file) {
+  if (!formatGate) await import('./store.js'); // 它的模块顶层会调 setFormatGate
+  if (formatGate) return formatGate;
+  if (MANAGED.has(basename(file))) {
+    throw new Error(`✗ ${basename(file)} 是受管文件，但格式闸门未注册 —— 拒绝写入（防止格崩坏）`);
+  }
+  return null;
+}
 const LOCK_WAIT_BASE_MS = 15;  // 指数退避起始重试间隔
 const LOCK_WAIT_MAX_MS = 150;  // 指数退避上限
 // 抢锁总预算：排队等锁的进程须依次排完。多进程高并发(CLI/MCP/hook 同刻抢一文件)下,
@@ -76,7 +94,14 @@ export async function editFile(file, mutator) {
     let write = typeof res === 'string' ? res : res && typeof res.text === 'string' ? res.text : null;
     // 格式闸门：所有写 index/todo/log 的路径（CLI/MCP/hook 共 ~15 处）都在此收口，
     // 不必逐个改调用点 —— 破坏格式的写入在这里被整理回标准形态（见 todo.js）。
-    if (write && formatGate) write = formatGate(file, write, current) ?? write;
+    //
+    // ★ 对三个受管文件，闸门**必须存在**：它们不是自由文本，是数据库表。
+    //   闸门缺失时以前会静默跳过（直写盘），现在改为自己补加载；补不上就硬拒，
+    //   宁可写失败也不要格崩坏——写不进去能重试，写脏了没人知道。
+    if (write) {
+      const gate = await gateFor(file);
+      if (gate) write = gate(file, write, current) ?? write;
+    }
     if (write && write !== current) {
       await fs.writeFile(file, write, 'utf8');
     }

package/src/store.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { requireBrain, brainPath, absLogDir } from './index.js';
 import { requireUser, atTag, getUser, placeholderWarn } from './userconfig.js';
-import { stripStateMark, checkTaskBox, ensureStateMark, stateOfTaskLine, TODO_MAX_LINES, upsertTask, boardText, readTodo, todoTemplate, today, localStamp, setBreakpoint, setMemo, readMemo, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, upsertArchiveSection, DONE_KINDS, withDoneKind, collapseDone, SEC, rebuildStructure, enforceBrainFormat, sessionOf } from './todo.js';
+import { stripStateMark, checkTaskBox, ensureStateMark, stateOfTaskLine, TODO_MAX_LINES, upsertTask, boardText, readTodo, todoTemplate, today, localStamp, setBreakpoint, setBreakpointDone, setMemo, readMemo, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, upsertArchiveSection, DONE_KINDS, withDoneKind, collapseDone, SEC, rebuildStructure, enforceBrainFormat, sessionOf, parseChild } from './todo.js';
 import { setFormatGate, editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
 import { keywords, recentFiles, topicStrength } from './relevant.js';
@@ -56,9 +56,11 @@ export async function cmdInit({ dir }) {
 
 async function createSkeleton(root, brain) {
   for (const d of BRAIN_DIRS) await fs.mkdir(join(brain, d), { recursive: true });
-  await fs.writeFile(join(brain, 'index.md'), indexTemplate(), 'utf8');
-  await fs.writeFile(join(brain, 'log.md'), logTemplate(), 'utf8');
-  await fs.writeFile(join(brain, 'todo.md'), todoTemplate(), 'utf8');
+  // 走 editFile 而不是 fs.writeFile：三个文件是受管表，写入必须过同一道闸门
+  // （2026-10-18：原来直写盘，是个绕过口）。模板本身合法，闸门只做归一。
+  for (const [f, tpl] of [['index.md', indexTemplate], ['log.md', logTemplate], ['todo.md', todoTemplate]]) {
+    await editFile(join(brain, f), (cur) => (cur === null ? { text: tpl() } : SKIP));
+  }
   // 建完就提示设姓名 —— 否则用户一路到第一次 todo add 才撞墙，
   // 中间 init/load 都不提，根本不知道该设。
   const who = await getUser();
@@ -116,7 +118,8 @@ export async function cmdRepair({ dir }) {
     try {
       await fs.access(join(brain, f));
     } catch {
-      await fs.writeFile(join(brain, f), tpl(), 'utf8');
+      // 同 createSkeleton：补齐也走 editFile 的口子（已存在则 cur 非 null，不覆盖）
+      await editFile(join(brain, f), (cur) => (cur === null ? { text: tpl() } : SKIP));
       fixed.push(f);
     }
   }
@@ -350,7 +353,7 @@ export async function cmdLoad({ dir }) {
   );
   if (stranded.length) {
     const rows = stranded.map((t) => {
-      const bp = t.bp.length ? `\n    ${t.bp.map((b) => `↳ 断点: ${b}`).join('\n    ')}` : '';
+      const bp = t.bp.length ? `\n    ${t.bp.map((b) => (b.startsWith('[') ? `↳ ${b}` : `↳ 断点: ${b}`)).join('\n    ')}` : '';
       return `  - ${t.body}${bp}`;
     });
     // 插在项目行之后、其它内容之前
@@ -807,7 +810,18 @@ function recentLogLines(text, n) {
 // ---------- task: 登记/推进（幂等键 = 行首 id；hook 也调这个） ----------
 // 纪律: task 过程动作(start/done/note/blocked)只改 todo.md, 不写 log.md。
 // log.md 是「工作成果沉淀摘要」(用户/AI 主动 abs log "..." 记), 不收工具动作流水。
-export async function cmdTask({ dir, action, id, section, note, as, session }) {
+export async function cmdTask({ dir, action, id, section, note, as, session, n }) {
+  // ★ id 校验（2026-10-16 模糊测试找出来的真 bug）：id 不能含空白/方括号。
+  //   不校就是**静默丢信息**：id="带 空格" 写进文件时被 extractId 截成 "带"，
+  //   后面的 "空格" 与描述一起消失，不报错（实测：`abs todo start "带 空格"` 落成 `- [ ] 带`）。
+  //   宁可明确拒掉，也不替人猜哪个词算 id。
+  const idStr = id === undefined || id === null ? '' : String(id);
+  if (idStr && (idStr.includes(' ') || idStr.includes('\t'))) {
+    throw new Error(
+      `✗ 任务 id 不能含空格（收到 "${idStr}"）—— id 是一个词，空白会被当分隔符。\n` +
+      `  想要带空格的名字：用连字符或下划线；完整名称写进 --note。`,
+    );
+  }
   const root = await requireBrain(dir || process.cwd());
   // 写操作守卫：无姓名不落盘（hook 调的 wrapup/teardown-check 不经过这里，不受影响）
   const who = await requireUser();
@@ -929,6 +943,12 @@ export async function cmdTask({ dir, action, id, section, note, as, session }) {
     const r = await setBreakpoint(root, { id, text: note });
     return r.msg;
   }
+  // 勾/取消勾断点：断点是待办，做完要勾（2026-10-16）。
+  // 单独两个子命令而不是 `--done true/false` —— 勾与取消是两件事，各自一个动词更顺手。
+  if (action === 'bp-done' || action === 'bp-undone') {
+    const r = await setBreakpointDone(root, { id, n, done: action === 'bp-done' });
+    return r.msg;
+  }
   if (action === 'memo') {
     // 任务随手记：多句/不定长/可追加，不占看板。无 note 时 = 查看已有笔记。
     if (!id) return '用法: abs todo memo <id> "随手记（可多句）"  |  abs todo memo <id>（查看）';
@@ -966,6 +986,7 @@ async function markDone(file, id, kind = '落地', conclusion, bySid = '') {
     let changed = false;
     let moved = null;
     const kept = [];
+    const leftBehind = [];
     const wantId = String(id).replace(/\u200b/g, '');
     for (let i = 0; i < lines.length; i++) {
       const l = lines[i];
@@ -990,19 +1011,65 @@ async function markDone(file, id, kind = '落地', conclusion, bySid = '') {
         parts.push(`(完成 ${today()}${doneSid ? ' ' + doneSid : ''})`);
         const head = withDoneKind(`${base}${tail} ${parts.join(' ')}`, kind);
         const bp = [];
-        while (i + 1 < lines.length && lines[i + 1].trimStart().startsWith('↳')) bp.push(lines[++i]);
+        const leftover = [];
+        // 子项搬运：已勾选的随任务进 Done；**未勾选的不搬**，留在 Todo 区。
+        //
+        // 为何（2026-10-18 实测）：Done 区被 collapseDone 折叠成计数，搬进去即「看板里
+        // 消失」。实测 factory-docs-slim 就带着「待做六链」的 `- [ ]` 落地，那条待办
+        // 此后无处可寻，同时父任务盖着【落地】——看板与事实矛盾。
+        //
+        // 为何不是硬拦（A 方案被否）：`abs todo note` 写的子项与断点记录**同形**（都是
+        // `  - [ ] …`），无法从字段上区分「待办」与「过程记录」；硬拦会把所有带断点的
+        // 任务一起拦住（实测弄挂两条既有测试）。改为「不搬 + 点名」，信息不丢且不误伤。
+        while (i + 1 < lines.length) {
+          const nx = lines[i + 1];
+          if (!nx.trim()) break;
+          const kid = parseChild(nx);
+          if (kid && kid.indent > 0) {
+            // 无论勾没勾都要 i++（否则原地打转 —— 2026-10-18 实测 OOM）
+            const ch = lines[++i];
+            if (kid.done) bp.push(ch);
+            else leftover.push(kid.text);
+            continue;
+          }
+          if (nx.trimStart().startsWith('↳')) {
+            const ch = lines[++i];
+            if (/^\s*↳\s*\[ \]/.test(ch)) leftover.push(ch.trim().replace(/^\s*↳\s*\[ \]\s*/, ''));
+            else bp.push(ch);
+            continue;
+          }
+          break;
+        }
         moved = [head, ...bp];
+        // 未勾子项升为独立任务留在 Todo 区：原地留着不行 —— 子项行一旦失去父任务，
+        // 重建分区时就是无主杂行（实测被清掉，待办静默消失）。
+        //
+        // ★ 2026-10-18 补：升格的行必须有**合法 id** 与**父任务线索**。
+        //   原来直接写 `- [ ] ${txt}`，实测 idOfTaskLine 会把正文开头的几个字当成 id
+        //   （`- [ ] [进行中] 子任务带 id ABC-1` → id="子任务带"），后续 `abs todo done`
+        //   靠 id 全等定位，于是变成靠句子前几个字匹配 —— 换个措辞就断，两条子项
+        //   开头相同时互相误命中。作者标记沿用父任务的，不另取名（拿不到就留空）。
+        const author = (l.match(/\[\[([^\]]+)\]\]/) || [])[1];
+        leftover.forEach((txt, k) => {
+          const restId = `${wantId}-rest${k + 1}`;
+          kept.push(`- [ ] [进行中] ${restId}${author ? ` [[${author}]]` : ''} — ${txt}（原 ${wantId} 遗留）`);
+        });
+        leftBehind.push(...leftover);
         continue;
       }
       kept.push(l);
     }
     if (!changed || !moved) return SKIP;
     // 归位 + 按日期分组：insertDoneGrouped 一次重建 Done 区（新日期在前，未标日期归尾）
-    return { text: insertDoneGrouped(kept.join('\n'), moved) };
+    return { text: insertDoneGrouped(kept.join('\n'), moved), leftBehind };
   });
   return res === SKIP
     ? `[NO_MATCH] 未找到含 "${id}" 的未完成任务行`
-    : `✓ 已完成并归位 Done: ${id} 【${kind}】`;
+    : `✓ 已完成并归位 Done: ${id} 【${kind}】` +
+        (res.leftBehind?.length
+          ? `\n  ⚠ ${res.leftBehind.length} 条未勾子项留在 Todo 区（未跟入 Done，仍可在看板看到）：\n` +
+            res.leftBehind.map((p) => `    - [ ] ${p}`).join('\n')
+          : '');
 }
 
 // ---------- show: 查看 index/todo/log（只读面） ----------

package/src/todo/archive.js

@@ -41,11 +41,13 @@ function parseDoneUnits(bodyLines) {
   let cur = null;
   for (const l of bodyLines) {
     if (/^### /.test(l.trim()) || l.trim() === '') { cur = null; continue; } // 分组标题/空行断开会话
-    if (isTaskLine(l)) {
+    // 先判子项再判任务：缩进的 `- [ ]` 两个判据都为真，而它应挂到父任务。
+    // （标准 md 嵌套下子项本身就是任务行 —— 靠缩进区分层级，不靠形态。）
+    if (cur && isChildLine(l)) {
+      cur.lines.push(l);
+    } else if (isTaskLine(l)) {
       cur = { date: doneDateOf(l), lines: [l] };
       units.push(cur);
-    } else if (isChildLine(l) && cur) {
-      cur.lines.push(l); // 附属行挂到上一个任务
     }
   }
   return units;
@@ -222,7 +224,10 @@ export function archiveDoneInText(text, { keepDays = 3, from = today(), maxLines
       date,
       lines: gLines,
       slug: slugFor(date),
-      count: gLines.filter((l) => /^\s*- \[x\]/.test(l)).length,
+      // 只数顶层任务（缩进 0）—— 子项也是 `- [x]`，用 /^\s*- \[x\]/
+      // 会把子项一起计数（实测：1 任务 + 1 子项 → 报 "完成任务 2 条"）。
+      // 归档标记的语义是「完成了多少条任务」，子项不算。
+      count: gLines.filter((l) => /^- \[x\]/.test(l)).length,
     });
   }
 

package/src/todo/common.js

@@ -98,22 +98,61 @@ export function sentenceCount(s) {
  *  现在直接报错，让写入方自己写对。
  *  允许的位置：H1 与首个标签之间、标签与首条目之间、区与区之间（排版需要）。 */
 
-/** 任务行：`- [ ] …` / `- [x] …`（允许缩进），以及**断点任务** `↳ [ ] …`。
+/** 任务行：`- [ ] …` / `- [x] …`。
  *
- * 为何把 `↳ [ ]` 也算任务行（2026-10-16 用户报）：
- *   原先 `↳` 只被当作「附属断点行」（`↳ 断点: 一句话`），于是 `  ↳ [ ] xxxxx`
- *   落进**静默死区** —— 写入闸门放行（isChildLine 认 `↳`）、lint 不报，
- *   但任何按 id 的操作（done/note/state）都找不到它，面板也不显示。
- *   即「写得进去、看不见、完不成」。
- *   现在 `↳ [ ]` 是**一等任务**：可显示、可 done、可 note。
- *   注意：`↳ 断点: …`（冒号形态）**不变**，仍是附属行、不算任务（用户 2026-10-16 明确保留）。 */
+ * 顶层任务：顶格（缩进 0）的 `- [ ]` 行。
+ * 子任务：缩进的 `- [ ]` 行（标准 Markdown 嵌套列表，2 空格一层）。
+ * 两者**都是任务行**（子任务可各自勾选）；层级的区分看缩进，不在本函数。
+ *
+ * 为何也收 `↳ [ ]`：2026-10-16 早上刚把断点任务升级成一等任务（存量数据里有），
+ * 现在改用标准 md 嵌套列表，旧形态继续认（存量不能变“看不见”）。 */
 export function isTaskLine(l) {
+  // 先排旧式断点行：`↳ [ ] 断点: x` 形似任务行，但它带 `断点:` ⇒ 是子项文本，不是任务。
+  if (/^\s*↳\s*\[[ x]\]\s*断点[:：]/.test(l)) return false;
   return /^\s*(?:-\s*\[[ x]\]|↳\s*\[[ x]\])/.test(l);
 }
-/** 判断一行是否为任务附属行（↳ 开头，且**不是**断点任务 —— `↳ [ ]` 已是任务行）。 */
 
+/** 一行是否任务附属行（子项）：缩进的 `- [ ]`，或旧的 `↳ …` 形态。
+ *
+ * 标准 md 下子项就是缩进的列表项 —— 它本身也是任务行（isTaskLine 为真），
+ * 但**不单独成条**：它挂在父任务下，不占顶层 id、不参与 `abs todo done`。
+ * 故 isChild 的判据是「有缩进」，不是「形态不同」。 */
 export function isChildLine(l) {
-  return /^\s*↳/.test(l) && !/^\s*↳\s*\[[ x]\]/.test(l);
+  if (/^\s*↳/.test(l)) return true;          // 旧形态（含 `↳ [ ]` 断点任务）
+  return /^\s+-\s*\[[ x]\]/.test(l);         // 缩进的 `- [ ]`（新形态）
+}
+
+// ---------- 子项行（标准 md 嵌套列表：缩进 2 空格 + `- [ ]`） ----------
+/** 子项 = 挂在任务下的可勾条目（旧的「断点」就是一条子项）。
+ *
+ * 格式（2026-10-16 用户定）：标准 Markdown 嵌套列表，不搞自定义前缀。
+ *   - [ ] [进行中] 主任务
+ *     - [x] 已完成的子项
+ *     - [ ] 还没做的子项
+ * 旧格式 `↳ 断点: 内容` **继续承认**（存量数据不能坏），新写入一律用标准 md。 */
+export const CHILD_INDENT = '  ';
+
+/** 解析子项行 → { done, text, indent }；不是子项返回 null。
+ * 两种形态都收：新的 `  - [ ] 内容` 与旧的 `  ↳ [ ] 断点: 内容` / `  ↳ 断点: 内容`。 */
+export function parseChild(l) {
+  const s = String(l || '');
+  // 旧形态（↳ 开头）：剥掉 ↳ 与可选复选框及可选的 `断点:` 标签
+  const old = s.match(/^(\s*)↳\s*(\[[ x]\])?\s*(?:断点[:：]\s*)?(.*)$/);
+  if (old) {
+    // 勾选看 ↳ 后的那个复选框；旧格式无勾 ⇒ false
+    if (!old[3].trim()) return null;  // `↳ [ ]` 后面没内容 = 不是子项（是旧一等任务的空壳）
+    return { done: old[2] === '[x]', text: old[3].trim(), indent: old[1].length };
+  }
+  // 新形态（缩进的 `- [ ]`）—— 必须缩进，否则那是顶层任务
+  const m = s.match(/^(\s+)-\s*\[([ x])\]\s*(.*)$/);
+  if (!m) return null;
+  return { done: m[2] === 'x', text: m[3].trim(), indent: m[1].length };
+}
+
+/** 生成子项行（标准 md，统一入口 —— 格式只有这一个真源）。
+ * indent 默认 2（挂在顶层任务下）；多层嵌套时传更深的值。 */
+export function renderChild(text, { done = false, indent = CHILD_INDENT } = {}) {
+  return `${indent}- ${done ? '[x]' : '[ ]'} ${text}`;
 }
 
 /** Todo 分区里「合法行」以外的东西 = 裸文本（总结/报告/清单）。
@@ -157,9 +196,16 @@ export function isPlaceholder(line) {
 
 export function extractId(text) {
   // 先剥行首状态标记（`[进行中] <id>`），否则 id 会取成 "[进行中]"（2026-09-13 实测）。
-  const t = String(text).replace(/^\[[^\]]+\]\s+/, '');
-  const m = t.match(/^([A-Za-z][\w-]*)\b/);
-  return m ? m[1] : null;
+  // 再剥具体的 `- [ ] ` / `↳ [ ] ` 前缀（CLI 传完整行时）。
+  const t = String(text)
+    .replace(/^\s*(?:-\s*\[[ x]\]|↳\s*\[[ x]\])\s*/, '')
+    .replace(/^\[[^\]]+\]\s+/, '');
+  // id = 到第一个空白 / `[` 为止的连续字符（id 不允许含空格或方括号）。
+  // ★ 必须支持**中文 id**（2026-10-16 实测）：原正则 `^[A-Za-z][\w-]*` 要求英文开头，
+  //   中文 id 一律返回 null → findTaskLine 永远找不到 → 同 id 重复 start 每次都新建
+  //   （幂等静默失效，实测同一 id 落了两行）。中文写作里拿短语当 id 很自然，不能只收 ASCII。
+  const m = t.match(/^([^\s[\]]+)/);
+  return m ? m[1].replace(/\u200b/g, '') : null;
 }
 
 /** 提取 " — " 后的 note 部分（剥掉紧跟在 id 后的 `@author` 标记及尾部 `(认领 ...)`）。

package/src/todo/spec.js

@@ -70,11 +70,28 @@ export const ENTRY_SHAPES = {
   'index.md': [
     {
       name: 'INDEX-ENTRY',
-      // 条目行：`- [[页名]] — 一句话`（是 6 个链接区里的一行）
+      // 条目行：`- [[页名]] — 一句话`（是 5 个链接区里的一行）
+      //
+      // ★ 2026-10-18 补的白名单另一半：原规则只检查 `- ` 开头的行，**不以 `- ` 开头的
+      //   散文全部原样放行**。于是 Sources 区被塞进 `场景：…` 段落、裸编号列表项、
+      //   `## 标题` 前缀也都存下来了（实测真库被污染 5 条，index 从 69 行膨到 88 行）。
+      //   链接区里只应有两种行：`- [[…]]` 条目、空行。其余一律拒。
       test: (l) => {
-        if (!/^-\s/.test(l)) return null; // 非条目行（规则短句/说明）由分区规则另判
+        if (!l.trim()) return null; // 空行由 STRAY-BLANK 规则另判
+        if (!/^-\s/.test(l)) return '链接区只能放 `- [[页名]] — 一句话`（正文段落/编号列表/代码块都不行）';
         if (!/^-\s*\[\[[^\]]+\]\]/.test(l)) return '应以 `- [[页名]] …` 开头';
         if (!/^-\s*\[\[[^\]]+\]\]\s*[—-]\s*\S/.test(l)) return '`[[页名]]` 后要跟 `— 一句话` 描述';
+        // 摘要里不许带 Markdown 结构符（实测污染就是摘要取了页面正文开头）
+        if (/^\s*-\s*\[\[[^\]]+\]\]\s*[—-]\s*#+\s/.test(l)) return '摘要不能带 `## ` 标题前缀（取页面首行标题了）';
+        // ★ 2026-10-18 补：摘要正文本身必须是**纯文本一句话**。
+        //   原规则只拦了 `## ` 前缀，实测下列全放行：摘要写成 `- 列表项`（变成嵌套列
+        //   表）、```js（开代码围栏，把后面所有条目吞进去）、`| a | b |`（表格）。
+        //   index 是表，摘要是一列纯文本，不能携带任何块级结构。
+        const desc = l.replace(/^\s*-\s*\[\[[^\]]+\]\]\s*[—-]\s*/, '');
+        if (/^(?:[-*+]\s|```|~~~|\||>\s|#{1,6}\s)/.test(desc)) {
+          return '摘要必须以文字开头（不能是列表项/代码围栏/表格/引用/标题）';
+        }
+        if (desc.includes('```')) return '摘要不能含代码围栏 ```（会吞掉后续所有条目）';
         return null;
       },
     },
@@ -83,7 +100,15 @@ export const ENTRY_SHAPES = {
     {
       name: 'LOG-ENTRY',
       test: (l) => {
-        if (!/^##\s/.test(l)) return null; // 非 `## ` 行（H1/注释）不管
+        // ★ 2026-10-18 补的白名单：原来只检查 `## ` 开头的行，**其余行全放行**，
+        //   于是裸散文/报告能直接写进 log（实测能落盘）。log 只应有四种行：
+        //   H1、`## Log` 分区标题、`## [时间]` 条目、HTML 注释。
+        if (!l.trim()) return null;                        // 空行另由 STRAY-BLANK 判
+        if (/^#\s/.test(l)) return null;                   // H1
+        if (/^<!--/.test(l.trim())) return null;           // 模板提示注释
+        if (/^##\s+Log\s*$/.test(l)) return null;          // 唯一分区标题
+        if (!/^##\s/.test(l)) return 'log 里只能有 `## [时间] [[作者]] kind | 正文` 条目行（散文/报告请开一条条目）';
+        // 以下只对 `## ` 行判形状
         // ★ log 没有分区概念：`## ` 开头的只能是条目。
         //   否则 `## 2026-10-05 随便写点`（缺方括号/作者/竖线）会被当成「分区标题」滑过去 ——
         //   而 log.md 的标签白名单是 null（不校验），这就是一个漏网口（实测）。
@@ -95,6 +120,9 @@ export const ENTRY_SHAPES = {
         const m = l.match(/^##\s*\[(\d{4}-\d{2}-\d{2}(?:\s+\d{2}:\d{2})?)\]\s*\[\[([^\]]+)\]\]\s*([A-Za-z]+)\s*\|\s*(\S.*)$/);
         if (!m) return '应为 `## [YYYY-MM-DD HH:MM] [[作者]] kind | 正文`（log 只能有这种行）';
         if (!LOG_KINDS.includes(m[3])) return `kind 只能是 ${LOG_KINDS.join('/')}（收到 \`${m[3]}\`）`;
+        // ★ 2026-10-18：正文不能含代码围栏。一条 log 正文里出现 ``` 会把它之后的
+        //   所有条目都吞进代码块（渲染与 grep 双输），而这里本来就是单行条目。
+        if (m[4].includes('```')) return 'log 正文不能含 ``` —— 条目是单行摘要，代码请贴文件路径或拆成 source 页';
         // 「正文只有个任务 id」不在这里拒（见下 lintOnly 规则）：它是**内容质量**
         // 问题不是**结构格式**问题，当写入闸门会把存量脏库锁死（实测：真库仅一条
         // 就让所有 abs log 失败）。留在此处只会误伤正常短标题（如 `log-0`）。
@@ -140,8 +168,8 @@ export const ENTRY_SHAPES = {
         if (m[1] === ' ' && !/^\[[^\]]+\]\s*\S/.test(rest)) {
           return '未完成任务应为 `- [ ] [状态] …`（状态：进行中/讨论中/滞留中）';
         }
-        // 断点附属行不能挤在同一行（应另起 `  ↳ 断点: `）
-        if (/↳\s*断点:/.test(rest)) return '断点要另起一行写 `  ↳ 断点: …`';
+        // 断点附属行不能挤在同一行（应另起 `  ↳ [ ] 断点: `）
+        if (/↳\s*(?:\[[ x]\]\s*)?断点[:：]/.test(rest)) return '断点要另起一行写 `  ↳ [ ] 断点: …`';
         return null;
       },
     },

package/src/todo/tasks.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { brainPath } from '../index.js';
 import { editFile, SKIP } from '../lock.js';
-import { today, localStamp, extractId, extractNote, extractAuthor, isLegacyAuthorTag, claimOf } from './common.js';
+import { today, localStamp, extractId, extractNote, extractAuthor, isLegacyAuthorTag, claimOf, parseChild, renderChild } from './common.js';
 import { todoTemplate, normalizeTodo, stateOfTaskLine, stripStateMark } from './structure.js';
 import { TASK_STATES } from './spec.js';
 import { collapseDone, groupDoneSection } from './archive.js';
@@ -69,9 +69,13 @@ function insertTask(orig, section, text) {
   if (idx === -1) {
     lines.push('', header, `- [ ] ${text}`);
   } else {
-    // 在该分区标题后、下一个分区标题前插入
+    // 在该分区标题后、下一个分区标题前插入。
+    // ★ 插入点要**跳过尾部空行**：分区末尾本来就有个排版空行（`## Done` 前的那个），
+    //   若插到它后面，新任务与前面的内容之间就隔了个空行 —— 每建一条多一个空行，
+    //   而闸门明写「条目之间不允许空行」（实测：建 4 条就有 3 个空行）。
     let insertAt = idx + 1;
     while (insertAt < lines.length && !lines[insertAt].startsWith('## ')) insertAt++;
+    while (insertAt > idx + 1 && !lines[insertAt - 1].trim()) insertAt--;
     lines.splice(insertAt, 0, `- [ ] ${text}`);
   }
   return lines.join('\n');
@@ -138,25 +142,73 @@ export function findTaskLine(lines, id) {
   return lines.findIndex((l) => idOfTaskLine(l) === want);
 }
 
-/** 实时断点: 在 id 任务行下原位补/换 `↳ 断点:` 附属行（不挪任务位置）。 */
+/** 子项行解析：从 `idx+1` 起扫连续的缩进行（子项），返回它们的下标。
+ * 遇到非子项（下一个顶层任务 / 空行 / 分区标题）就停。 */
+function childRange(lines, idx) {
+  const out = [];
+  for (let i = idx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) break;              // 空行 = 子项块结束
+    const child = parseChild(line);
+    if (child && child.indent > 0) { out.push(i); continue; }
+    break;                                 // 另一个顶层任务行 / 标题
+  }
+  return out;
+}
 
+/** 追加/更新一条子项（标准 md：缩进 2 空格 + `- [ ]`）。
+ *
+ * 语义（2026-10-16 用户定）：子项就是 todo 的嵌套子任务 —— 可多条、可各自勾选。
+ * `abs todo note <id> "…"` **追加**一条（不再覆盖）—— 用户原话「不限，写多少算多少」。
+ * 仍保留幂等：与最后一条完全同文就不重复追加（防手滑重复调）。
+ * 旧的 `↳ 断点:` 存量行不动（parseChild 认得，继续显示）；新写一律用标准 md。 */
 export async function setBreakpoint(brainRoot, { id, text }) {
   const p = await ensureTodo(brainRoot);
-  const bp = `  ↳ 断点: ${text}`;
+  let added = false;
   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);
-    }
+    const kids = childRange(lines, idx);
+    const last = kids.length ? parseChild(lines[kids[kids.length - 1]]) : null;
+    if (last && last.text === String(text).trim()) return SKIP; // 幂等：同文不重复追加
+    lines.splice(idx + 1 + kids.length, 0, renderChild(text));
+    added = true;
+    return { text: lines.join('\n'), ok: true };
+  });
+  if (res === SKIP) {
+    return added
+      ? { ok: true, msg: `✓ 子项已追加 → ${id}` }
+      : { ok: false, msg: `[NO_MATCH] 未找到含 "${id}" 的未完成任务行（或子项已存在）` };
+  }
+  return { ok: true, msg: `✓ 子项已追加 → ${id}\n  ${renderChild(text)}` };
+}
+
+/** 勾/取消勾子项：`- [ ] …` ↔ `- [x] …`。
+ *
+ * 定位：子项没有自己的 id（身份 = 「某任务的第 N 条子项」），故按 n 定位（1-based）。
+ * n 缺省 = 勾最后一条（最常用的「刚写的这条做完了」）。
+ * 旧格式 `↳ 断点:` 也能勾 —— 勾一下就地升级成标准 md 形态。 */
+export async function setBreakpointDone(brainRoot, { id, n, done = true }) {
+  const p = await ensureTodo(brainRoot);
+  let picked = null;
+  const res = await editFile(p, (orig) => {
+    const lines = orig.split('\n');
+    const idx = findTaskLine(lines, id);
+    if (idx === -1) return SKIP;
+    const kids = childRange(lines, idx);
+    if (!kids.length) return SKIP;
+    const target = n ? kids[n - 1] : kids[kids.length - 1];
+    if (target === undefined) return SKIP;
+    const child = parseChild(lines[target]);
+    picked = child;
+    lines[target] = renderChild(child.text, { done });
     return { text: lines.join('\n'), ok: true };
   });
-  return res === SKIP
-    ? { ok: false, msg: `[NO_MATCH] 未找到含 "${id}" 的未完成任务行` }
-    : { ok: true, msg: `✓ 断点已落 → ${id}\n  ${bp.trim()}` };
+  if (res === SKIP || !picked) {
+    return { ok: false, msg: `[NO_MATCH] "${id}" 下没有第 ${n || '(最后)'} 条子项（或任务不存在）` };
+  }
+  return { ok: true, msg: `✓ 子项 ${done ? '已勾' : '已取消勾'} → ${id}\n  ${renderChild(picked.text, { done })}` };
 }
 
 // ---------- 任务随手记（memo）----------

package/src/todo/validate.js

@@ -1,7 +1,7 @@
 // src/todo/validate.js — 条目级闸门：形状校验、长度限制、空行检查。
 
 import { TODO_SECTIONS, isAllowedTodoSub, INDEX_SECTIONS, ENTRY_SHAPES, indexLinkSectionNeeds, BREAKPOINT_MAX, TASK_LINE_MAX } from './spec.js';
-import { sigOfLine, REPORT_MARKERS, sentenceCount, isTaskLine, isAllowedTodoLine, todoSectionOf } from './common.js';
+import { sigOfLine, REPORT_MARKERS, sentenceCount, isTaskLine, isAllowedTodoLine, todoSectionOf, parseChild } from './common.js';
 
 export function checkFileShape(file, text, { lintMode = false } = {}) {
   const issues = [];
@@ -162,6 +162,29 @@ export function assertTodoContent(text, prevSig = null) {
     const l = lines[i];
     const lineNo = i + 1;
     if (l.startsWith('## ')) continue;
+    // 子项行要比任务行先判：标准 md 下子项（缩进的 `- [ ]`）**也是任务行**，
+    // 若让任务行分支先 continue，子项就只受 TASK_LINE_MAX(400) 管，
+    // BREAKPOINT_MAX(200) 的闸门永远走不到（实测：300 字子项静默写入）。
+    const kidEarly = parseChild(l);
+    if (kidEarly && kidEarly.indent > 0) {
+      if (isLegacy(l)) continue; // 存量：不阻写入（lint 报）
+      const kbody = kidEarly.text;
+      if (kbody.length > BREAKPOINT_MAX) {
+        throw new Error(
+          `✗ 子项太长（第 ${lineNo} 行 ${kbody.length} 字 > ${BREAKPOINT_MAX}）—— 子项只写「改到哪个文件哪一步」。\n` +
+          `  写不下的内容请分流：实施报告/验证数据 → abs log；经验与坑 → abs note；长设计 → .brain/sources/ 页。\n` +
+          `  原文开头: ${kbody.slice(0, 60)}...`,
+        );
+      }
+      if (REPORT_MARKERS.some((re) => re.test(kbody)) || sentenceCount(kbody) > 2) {
+        throw new Error(
+          `✗ 子项里像是塞了报告/清单（第 ${lineNo} 行）—— 子项是一句话（最多两句），不是文档。\n` +
+          `  todo 只能加 todo：要做的拆成任务，做完的写 abs log，经验写 abs note。\n` +
+          `  原文开头: ${kbody.slice(0, 60)}...`,
+        );
+      }
+      continue;
+    }
     // 任务行
     if (isTaskLine(l)) {
       if (l.length > TASK_LINE_MAX && !isLegacy(l)) {
@@ -173,10 +196,11 @@ export function assertTodoContent(text, prevSig = null) {
       }
       continue;
     }
-    // 断点附属行
-    if (l.trimStart().startsWith('↳ 断点:')) {
+    // 断点附属行（新旧格式用同一个解析器 —— 格式知识只有 common.js 一个真源）
+    const bp = parseChild(l);
+    if (bp) {
       if (isLegacy(l)) continue; // 存量超长断点：不阻写入（lint 报）
-      const body = l.trimStart().slice('↳ 断点:'.length).trim();
+      const body = bp.text;
       if (body.length > BREAKPOINT_MAX) {
         throw new Error(
           `✗ 断点太长（第 ${lineNo} 行 ${body.length} 字 > ${BREAKPOINT_MAX}）—— 断点只写「改到哪个文件哪一步」。\n` +

package/src/todo.js

@@ -2,9 +2,9 @@
 // 保留这一层是为了对外接口稳定：store.js / lint.js / note.js / wrapup.js / 测试的
 // import 路径与名字都不用改。
 
-export { TODO_MAX_LINES, LOG_MAX_LINES, INDEX_MAX_LINES, today, localStamp, SEC, extractId, extractNote, extractAuthor, isLegacyAuthorTag, claimOf, sessionOf } from './todo/common.js';
+export { TODO_MAX_LINES, LOG_MAX_LINES, INDEX_MAX_LINES, today, localStamp, SEC, extractId, extractNote, extractAuthor, isLegacyAuthorTag, claimOf, sessionOf, parseChild, renderChild } from './todo/common.js';
 export { LEGACY_SECTION_RENAMES, TODO_SECTIONS, TODO_SUBSECTIONS, isAllowedTodoSub, INDEX_SECTIONS, INDEX_LINK_SECTIONS, LOG_KINDS, H1_TO_FILE, ENTRY_SHAPES, TASK_STATES, RETIRED_SECTIONS, BREAKPOINT_MAX, TASK_LINE_MAX, DONE_KINDS, ARCHIVE_SECTION } from './todo/spec.js';
 export { todoTemplate, rebuildStructure, dropRetiredSections, enforceBrainFormat, normalizeTodo, ensureStateMark, stateOfTaskLine, stripStateMark, checkTaskBox } from './todo/structure.js';
 export { checkFileShape, violationSignatures, assertNoStrayBlank, assertTodoContent } from './todo/validate.js';
 export { doneDateOf, doneKindOf, withDoneKind, collapseDone, archiveDoneInText, renderArchiveBody, upsertArchiveSection, groupDoneSection, insertDoneGrouped } from './todo/archive.js';
-export { readTodo, ensureTodo, setStateMark, addTask, upsertTask, idOfTaskLine, findTaskLine, setBreakpoint, setMemo, readMemo, boardText } from './todo/tasks.js';
+export { readTodo, ensureTodo, setStateMark, addTask, upsertTask, idOfTaskLine, findTaskLine, setBreakpoint, setBreakpointDone, setMemo, readMemo, boardText } from './todo/tasks.js';

package/src/wrapup.js

@@ -8,7 +8,7 @@
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { absLogDir } from './index.js';
-import { readTodo, localStamp } from './todo.js';
+import { readTodo, localStamp, parseChild } from './todo.js';
 
 export function wrapupLogPath() {
   return join(absLogDir(), 'wrapup.log');
@@ -62,7 +62,15 @@ export function extractOpenTasks(todoText) {
         const bp = [];
         while (i + 1 < lines.length && /^\s*↳/.test(lines[i + 1])) {
           i++;
-          bp.push(lines[i].trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
+          // 断点快照带上勾选标记（`[ ] 内容` / `[x] 内容`）—— 快照是给人看的，
+          // 不保留勾选就分不清「当时已完成」与「还没做」（2026-10-16 断点可勾后必需）。
+          const parsed = parseChild(lines[i]);
+          if (parsed) {
+            bp.push(`${parsed.done ? '[x]' : '[ ]'} ${parsed.text}`);
+          } else {
+            // 非断点的 ↳ 行（如 `↳ [ ] 子任务`）仍照旧剥前缀
+            bp.push(lines[i].trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
+          }
         }
         out.push({ body: taskBody, bp });
       }
@@ -77,12 +85,13 @@ function isPlaceholderBody(body) {
   return /^(待办任务|无|（无）|None|null)$/.test(body) || /^待办任务/.test(body);
 }
 
-/** 序列化一个快照块：首行时间戳+归属，后随未完成任务（主体+断点）。 */
+/** 序列化一个快照块：首行时间戳+归属，后随未完成任务（主体+断点）。
+ * 断点 bp 元素已自带勾选前缀（`[ ] 内容` / `[x] 内容`，见 extractOpenTasks）。 */
 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}`);
+    const bps = t.bp.map((b) => (b.startsWith('[') ? `      ↳ ${b}` : `      ↳ 断点: ${b}`));
     return `  - [ ] ${t.body}${bps.length ? '\n' + bps.join('\n') : ''}`;
   });
   return [head, ...rows].join('\n');
@@ -112,7 +121,11 @@ export function parseWrapup(text) {
     }
     const bm = line.match(/^\s*↳/);
     if (bm && cur.tasks.length) {
-      cur.tasks[cur.tasks.length - 1].bp.push(line.trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
+      // 回读时统一成 `[ ] 内容` / `[x] 内容` 形态（新写的就是这个；旧快照无勾 → 当未勾）
+      const parsed = parseChild(line);
+      cur.tasks[cur.tasks.length - 1].bp.push(parsed
+        ? `${parsed.done ? '[x]' : '[ ]'} ${parsed.text}`
+        : line.trim().replace(/^↳\s*(断点|卡点)?[:：]?\s*/, ''));
     }
   }
   return byProj;