@fanchao8609/agent_brain_sync 1.16.1 → 1.16.2

package/README.md

@@ -125,7 +125,7 @@ abs update                                # 升级到最新版并刷新四宿主
 ```
 
 > `abs todo start` 与 `abs todo add` 等价（都登记任务）。
-> 旧版 `abs task ...` / `abs board` 已改名，会报错并提示新写法。
+> 旧版 `abs task ...` / `abs board` 已废，打它们会报「未知命令」并退出码 1。
 > `abs wrapup` / `abs teardown-check` 是 hook 内部命令，无需手动调用。
 > **作者名要填真的**：`tester` / `foo` / `aaa` 这类占位名会被拒 —— 因为 `{user}` 是全局单值，
 > 填错会污染之后所有项目的 `[[作者]]` 标记（`aaa` 这类堆字也拒，但 `oo`/`ee` 这种两字母缩写放行）。

package/bin/abs.js

@@ -279,10 +279,10 @@ const subUsage = {
     '',
     '用法:',
     '  abs todo                       看板',
-    '  abs todo add <id> [--note "做什么"] [--section 讨论中|滞留中]',
+    '  abs todo add <id> [--note "做什么"] [--section 讨论中|滞留中|搁置]',
     '  abs todo rename <旧id> --note "<新id>"   改任务 id（起错名/不可读时）',
     '  abs todo note <id> --note "断点/进度"',
-    '  abs todo state <id> --note 进行中|讨论中|滞留中',
+    '  abs todo state <id> --note 进行中|讨论中|滞留中|搁置',
     '  abs todo done <id> [--as 落地|否决|仅方案] [结语文字]',
     '  abs todo archive [--keep-days N] [--dry-run]',
     '',
@@ -336,18 +336,16 @@ function rejectExtra(extra, fix) {
   throw new Error(`✗ 不认识多余参数 ${q}\n  正确用法: ${fix}`);
 }
 
-// 已改名/已废弃命令 → 新写法（报错而非静默，避免用户白跑一趟）
-const RENAMED = {
-  task: () => '命令已改名: abs task → abs todo\n  例: abs todo add <id> --note "…"  /  abs todo done <id>',
-  board: () => '命令已改名: abs board → abs todo',
-};
+// 已废弃命令 → 报错（而非静默）。曾用 RENAMED 表做"已改名"提示，
+// 2026-10-05 删掉 task/board 两条：未知命令分支本来就报错+退出码 1+打印帮助，
+// 别名不提供额外信息，只多一处要维护的文案。
 
 // task/todo 共用的子命令 → 归一化后的 action
 const TODO_ACTIONS = {
   add: 'start',
   start: 'start', // add 的别名(老习惯保留)
   note: 'note',
-  state: 'state', // 改行首状态标记：进行中|讨论中|滞留中（原地，不搬区）
+  state: 'state', // 改行首状态标记：进行中|讨论中|滞留中|搁置（原地，不搬区）
   rename: 'rename', // 改任务 id：人工起错名、或旧 id 不可读时用
   done: 'done',
 };
@@ -387,7 +385,6 @@ async function cmdConfig({ sub, value }) {
 async function main() {
   try {
     const opts = parseArgv(rest);
-    if (RENAMED[cmd]) throw new Error(RENAMED[cmd]());
     // 子命令级 --help: 有用法页的命令在此一处拦截（此前只在 install/uninstall 分支里判,
     // 其余命令的 --help 被忽略 —— 曾出现子命令 --help 直接执行动作、挂住终端）。
     if (opts.help && subUsage[cmd] && !(cmd === 'todo' && opts._.length)) {

package/bin/mcp.js

@@ -112,12 +112,12 @@ tool(
 
 tool(
   'abs_task',
-  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补断点(改到哪文件哪行) / state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。',
+  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补断点(改到哪文件哪行) / state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。必填: cwd, action, id。',
   {
     action: z.enum(['add', 'start', 'done', 'note', 'state']),
     id: z.string().describe('任务幂等键，如 TASK-xxx 或子任务名'),
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
-    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步); state=进行中|讨论中|滞留中; done=结语文字'),
+    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步); state=进行中|讨论中|滞留中|搁置（搁置=用户改方向/不做了；滞留中=还要做只是卡住）; done=结语文字'),
     as: z.enum(['落地', '否决', '仅方案']).optional().describe('仅 done：结语类型。默认 落地。做了又撤/评估后不做用 否决，只设计过用 仅方案 —— 别让假【落地】污染看板'),
   },
   async ({ action, id, cwd, note, as }) => {
@@ -131,7 +131,7 @@ tool(
 
 tool(
   'abs_resolve',
-  '按页面 id（或页面名 slug）反查文件路径。页改名后 id 不变，引用请用返回的路径/id。',
+  '按页面 id（或页面名 slug）反查文件路径。页改名后 id 不变，引用请用返回的路径/id。必填: cwd, refs（数组，一次可查多个）。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     refs: z.array(z.string()).min(1).describe('页面 id 或页面名，如 "file-write-locking"'),
@@ -151,7 +151,7 @@ tool(
 
 tool(
   'abs_supersede',
-  '标记一条经验/知识页已失效（被推翻），不删文件、保留历史。之后 abs_query 默认不再返回它。核实后发现仍有效可手动把 status 改回 active。',
+  '标记一条经验/知识页已失效（被推翻），不删文件、保留历史。之后 abs_query 默认不再返回它。核实后发现仍有效可手动把 status 改回 active。必填: cwd, refs（数组）。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     refs: z.array(z.string()).min(1).describe('页名或 id，如 "old-approach"'),
@@ -181,7 +181,7 @@ tool(
 
 tool(
   'abs_query',
-  '检索当前项目 .brain/ 知识页（多词 OR）：以前踩过什么坑、哪页记了 X。',
+  '检索当前项目 .brain/ 知识页（多词 OR）：以前踩过什么坑、哪页记了 X。必填: cwd, terms（数组，不是 query；可传多个词）。',
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）'), terms: z.array(z.string()).min(1).describe('检索词'), include_superseded: z.boolean().optional().describe('true=连已标记失效的经验一起返回（默认隐藏）') },
   async ({ cwd, terms, include_superseded }) => {
     const root = await findBrainRoot(cwd || process.cwd());
@@ -233,7 +233,7 @@ tool(
 
 tool(
   'abs_note',
-  '经验实时暂存：把刚踩的坑/技巧/结论一句话落进 sources/（防 context 断了流失）。Teardown 时再提炼进 concepts/。',
+  '经验实时暂存：把刚踩的坑/技巧/结论一句话落进 sources/（防 context 断了流失）。Teardown 时再提炼进 concepts/。必填: cwd, text。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     text: z.string().min(1).describe('经验/坑/技巧一句话'),
@@ -248,7 +248,7 @@ tool(
 
 tool(
   'abs_concept',
-  '建概念页骨架（给写入定结构：触发场景/表现/解法/验证）。只给结构不给内容 —— 值不值得留、归哪页仍靠人判断。',
+  '建概念页骨架（给写入定结构：触发场景/表现/解法/验证）。只给结构不给内容 —— 值不值得留、归哪页仍靠人判断。必填: cwd, slug。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     slug: z.string().min(1).describe('文件名/slug，如 "docker-prisma-429"（命名即链接）'),

package/hooks/abs.pi.ts

@@ -99,6 +99,31 @@ let pendingTodoTool = false
  *  只记第一次写文件，不是每次都记：断点是「记到哪」不是流水账。 */
 let autoTaskSeen = false
 
+/** 本会话动过的文件（去重，最多记 FILES_SEEN_MAX 个）。
+ *
+ * ★ 定位（用户 2026-10-05 定，别改）：这**是「摆事实」，不是「发现问题」**。
+ *   它只把我自己刚干过的事（改过哪些文件）与看板并列摆出来，
+ *   **不判断这些改动算不算任务、不提醒、不追踪、不逼登记**。
+ *   是否意识到「我干的和看板对不上」、要不要补记 —— 全部由 LLM 自己反思。
+ *
+ * 为何不挂在「改文件/一轮结束」两个时机：那两个钩子改不了 system prompt
+ *   （tool_call/agent_end 拿不到 systemPromptOptions，只有 before_agent_start 有）；
+ *   而 sendUserMessage 插话已被否决（打断用户）。故记在这里、下轮带出。
+ *
+ * 今日最大的教训：**不要用技术手段替 LLM 发现 todo 问题。**
+ *   一侧（摆事实）有效，另一侧（替它发现）十二次全败。详见 concept remind-vs-gate。 */
+const filesSeen = new Set<string>()
+const FILES_SEEN_MAX = 8
+
+/** 写类工具调用的文件路径：edit/write 直接取 input.path，bash 取命令里像路径的片段。 */
+function touchedPath(name: string, input: any): string | null {
+  const p = input?.path ?? input?.file_path ?? input?.filename
+  if (typeof p === 'string' && p.trim()) return p.trim()
+  // bash 的写入靠命令字符串抻出路径（重定向/ sed -i / tee 等）
+  const cmd = String(input?.command ?? '')
+  const m = cmd.match(/(?:>>?|tee|sed -i[^ ]*)\s+([^\s|;&<>]+)/)
+  return m ? m[1] : null
+}
 
 /** 最近一次渲染拿到的 tui 引用。hidePanel 用它请求重绘 —— 面板消失时动画
  *  定时器已停，没有别的重绘通道（见 hidePanel 的坑注解）。 */
@@ -149,8 +174,8 @@ const TODO_GUIDELINES = [
   // ④ 反例（照 rpiv-todo）：明确什么情况【不许】标完成 —— 只给正向要求时，
   //   模型倾向于把"我以为做完了"当成完成，结语失真会污染下个会话的判断。
   'Never mark a task "done" when tests are failing, the implementation is partial, or an error is unresolved — keep it in progress and add a task for the blocker instead.',
-  // ⑤ 唯一进行中（同 rpiv-todo）：看板要能回答"现在在做什么"，多的应转讨论中/滞留中。
-  'Keep exactly one task in "进行中" at a time; use action "state" with 讨论中 or 滞留中 for anything else that is open. If you finish one and another is ready, promote it explicitly.',
+  // ⑤ 唯一进行中（同 rpiv-todo）：看板要能回答"现在在做什么"，多的应转走。
+  'Keep exactly one task in "进行中" at a time; when the user switches direction or drops a task, use action "state" with 搁置 (dropped/not doing it); 滞留中 for still-wanted-but-stuck; 讨论中 for still-open. If you finish one and another is ready, promote it explicitly.',
   // ⑥ 结语要真实：三种结语各有含义，别一律写落地。
   'When completing, pick the honest conclusion via the `as` field: 落地 (built and verified) / 否决 (decided against, or built then reverted) / 仅方案 (designed only). A wrong conclusion makes the next session treat "considered" as "completed".',
 ]
@@ -173,12 +198,83 @@ async function hasBrain(cwd: string): Promise<boolean> {
   }
 }
 
-function injectTodoGuidelines(options: any): boolean {
+/** 看板快照在 guidelines 里的前缀 —— 用于每轮替换上轮快照（内容会变，不能用 includes 去重）。 */
+const BOARD_MARK = '[看板] '
+
+/** 把当前看板拼成 Guidelines 里的一段（对齐用）。
+ *
+ * 设计（用户 2026-10-05 定）：**只对齐，不多说** —— 把「现在看板上有什么」摆在
+ * 面前让 LLM 自己对照，不写「记得登记」这类劝告（那些已证明会被忽略）。
+ *
+ * ★ 铁律（2026-10-05 用户定，别改）：
+ *   - **只用对齐，不用技术手段替 LLM 发现 todo 问题。**
+ *     今天最大的收获：技术只负责「摆事实」，不负责「发现问题、提醒、追踪、逼补记」。
+ *     让 LLM 自己看到、自己反思、自己决定 —— 这是唯一活下来的方向。
+ *   - **反复对齐，不厌其烦**：不是一次性提示，是**每一轮都摆**。
+ *     用户原话：「对齐永远是反反复复的对齐，不厌其烦」。
+ *     别用节流/去重/「刚说过就不重复」去优化掉它 —— 反复就是它的工作方式。
+ *   - **尺度：只说 todo.md 本身**。不夹带判断、不写劝告、不评价好坏。
+ *     只把「看板上现在有什么」摆出来。
+ *   - **是否添加/完成/删除/转状态，全部由 LLM 自己判断** —— 不替它决定，
+ *     不自动登记、不自动完成、不写看板。
+ *   - **不做重任务**：不起进程、不 spawn、不写盘；只读一个本地文件。
+ *   理由：前 12 次尝试都失败，根因是「让不掌握判据的一方启动动作」。
+ *   判据在 LLM 手里，这里只负责保证它**每轮都看得见**。
+ *   详见 concept remind-vs-gate（对齐必做 + 门禁兜底）。
+ *
+ * 与以前删掉的两种注入的本质区别：那不调 sendUserMessage（不插话、不抢 turn），
+ * 只改 system prompt 内容 —— 和静默的 TODO_GUIDELINES 走同一个通道。
+ *
+ * 看板空或全完成时不拼（没有可对齐的东西，拼个空列表纯占位）。 */
+export function boardGuideline(md: string, who: string, touched: string[] = []): string | null {
+  const { total, rows } = parseOpenTasks(md, PANEL_MAX_ROWS, who)
+  // 看板空但动过文件：仍要输出（「改了文件却没任务」正是最该对齐的时刻）。
+  if ((!total || !rows.length) && !touched.length) return null
+  const lines = rows.map((r) => {
+    // desc 为空时不拖空破折号（MCP 登记只给 id 的常见情形）。
+    const head = `  ${r.state ? `[${r.state}] ` : ''}${r.id}${r.desc ? ` — ${r.desc}` : ''}`
+    // 断点必须带上：它就是「改到哪一步」，丢了等于对齐了也接不上。
+    return r.note ? `${head}\n    ↳ ${r.note}` : head
+  })
+  const more = total > rows.length ? `  …另 ${total - rows.length} 条` : ''
+  // 本会话动过的文件 —— 与看板并列摆出，让 LLM 自己对照（不判断算不算任务）。
+  const touchLines = touched.length
+    ? ['本会话改过:', ...touched.map((f) => `  ${f}`)]
+    : []
+  return [
+    '当前 .brain/todo.md 看板（开工前对齐：正在做的算哪条？有新任务要加吗？有该删的吗？）:',
+    ...(lines.length ? lines : ['  （空）']),
+    ...(more ? [more] : []),
+    ...touchLines,
+  ].join('\n')
+}
+
+/** 读看板拼成对齐段。失败/无图谱/看板空都返 null（静默降级，绝不阻断对话）。 */
+async function readBoardForGuide(cwd: string): Promise<string | null> {
+  try {
+    const md = await readFile(join(cwd, '.brain', 'todo.md'), 'utf8')
+    return boardGuideline(md, await currentUser(), [...filesSeen])
+  } catch {
+    return null
+  }
+}
+
+/** 注入 todo 指引。静态 6 条（行为要求） + 实时看板（对齐用）—— 两者职责不同：
+ * 静态条说「该怎么做」，看板说「现在是什么」。 */
+export function injectTodoGuidelines(options: any, board?: string | null): boolean {
   if (String(process.env.ABS_TODO_GUIDE || '') === '0') return false
   const list: string[] = options.promptGuidelines || (options.promptGuidelines = [])
   for (const g of TODO_GUIDELINES) {
     if (!list.includes(g)) list.push(g)
   }
+  // 看板内容每轮会变（任务增减/状态转换），不能用 includes 去重 —— 先删上轮的旧快照再推。
+  // ★ 必须先删：board 为 null（看板空了/全完成）时同样要删 ——
+  //   曾只在 board 非空时删，结果看板清空后旧快照残留在 prompt 里，
+  //   LLM 会继续看到已经不存在的任务（对齐撒谎）。
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (list[i].startsWith(BOARD_MARK)) list.splice(i, 1)
+  }
+  if (board) list.push(BOARD_MARK + board)
   return true
 }
 
@@ -518,7 +614,7 @@ export function renderPanelLines(
   nickname = '',
 ): string[] {
   if (data.total === 0) return []
-  const colorOf = (state: string): string => (state === '滞留中' ? 'muted' : state === '讨论中' ? 'dim' : 'accent')
+  const colorOf = (state: string): string => (state === '搁置' ? 'dim' : state === '滞留中' ? 'muted' : state === '讨论中' ? 'dim' : 'accent')
   const lines: string[] = []
   // 上描边：用 `thinkingOff` —— 跟 Pi 输入框描边**完全同一个色**。
   // 排查过程（2026-10-03 用户两轮反馈）：
@@ -620,6 +716,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
   pi.on("session_start", (event: any, ctx: any) => {
     // 新会话 = 重新登记：不重置则同进程的第二个会话永远不再落断点
     autoTaskSeen = false
+    filesSeen.clear() // 同理：新会话的文件痕迹不能带到下个会话
     resetThrottle()
     // 本会话的随机昵称 —— 在这里抽一次（不是每帧抽，否则面板会疯狂闪）。
     // 每次 session_start（startup/reload/new/resume/fork）重抽 → “每次打开 pi 都是随机的”。
@@ -663,6 +760,12 @@ export default function absPiHook(pi: ExtensionAPI): void {
       const sid = sessionIdFor(ctx)
       logHook(`tool_call first_write name=${name} sid=${sid || '-'}`).catch(() => {})
     }
+    // 记下动过的文件（去重）—— 下一轮对齐时摆给 LLM（见 filesSeen 注释）。
+    // 每轮都记（不限首次）：一轮里改多个文件都要能看到。
+    if (isWriteCall(name, input)) {
+      const p = touchedPath(name, input)
+      if (p && filesSeen.size < FILES_SEEN_MAX) filesSeen.add(p)
+    }
   })
 
   pi.on("tool_execution_end", (_event: any, ctx: any) => {
@@ -690,7 +793,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
           logHook(`before_agent_start todo_guide=off reason=no_brain`).catch(() => {})
           return
         }
-        const ok = injectTodoGuidelines(event?.systemPromptOptions)
+        const ok = injectTodoGuidelines(event?.systemPromptOptions, await readBoardForGuide(cwd))
         logHook(`before_agent_start todo_guide=${ok ? 'on' : 'off'} cwd=${cwd}`).catch(() => {})
 
         // 自动登记已整体移除（2026-10-05 用户实报两点）：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.16.1",
+  "version": "1.16.2",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",

package/src/lint.js

@@ -3,7 +3,7 @@
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { requireBrain, brainPath, BRAIN_DIR } from './index.js';
-import { readRules, idOfPage, statusOfPage, supersededByOf, clip } from './store.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';
 
 // ---------- 图谱遍历 ----------
@@ -342,9 +342,11 @@ async function checkFiles(vault, pages, indexLinks) {
     if (found && items.length > LINT_RULES_MAX) {
       issues.push(`RULES-PILED-UP: Rules 区 ${items.length} 条 > ${LINT_RULES_MAX}；把长条目提炼成概念页，这里只留一句话`);
     }
-    const longOnes = items.filter((l) => l.trim().length > 160);
+    // 单条长度：与 cmdRule 用同一个阈值（RULE_BODY_MAX）—— 写入侧和体检侧必须同标准，
+    // 否则「手工编辑绕过写入校验」的条目静默通过，而 lint 报 0 问题（假健康）。
+    const longOnes = items.filter((l) => l.trim().length > RULE_BODY_MAX);
     if (longOnes.length) {
-      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 160 字符（如 "${clip(longOnes[0].trim(), 40)}"）；展开写进概念页，这里只留一句话（不带链接）`);
+      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 ${RULE_BODY_MAX} 字（如 "${clip(longOnes[0].trim(), 40)}"，${longOnes[0].trim().length} 字）；展开写进概念页，这里只留一句话`);
     }
   }
   return issues;

package/src/store.js

@@ -523,6 +523,10 @@ async function sourcesCountSection(root) {
 /** index.md 的 `## Rules` 区名与上限。 */
 export const RULES_HEADING = '## Rules';
 export const RULES_MAX = 30; // 超过就 lint 报：它属于“被读到才有价值”的区，不能无界增长
+/** 单条上限（中文按字算）。2026-10-05 从 cmdRule 内联数字抽出：lint 也要查同一个值 ——
+ * 曾经只在「abs rule add」写入时校验，手工编辑 index.md 完全绕过，而 lint 只查条数不查长度
+ * → 89 字的条目静默通过，同一内容用 add 写反而被拒（两个口子标准不一致）。 */
+export const RULE_BODY_MAX = 42;
 
 
 /** 提取 index.md 里的 Rules 区条目（不含标题）。返回 { items:[行], body, found }。 */
@@ -575,8 +579,8 @@ export async function cmdRule({ dir, action, text }) {
   // 门槛：**纪律不是记事本**。Rules 是最前面的项目铁律，每条必须一眼扫完。
   // 2026-09-13 用户定：不带链接、不带解释、不写细节 —— 细节进概念页，Rules 只留结论。
   // 宽严：中文一字信息量大，按 40 字算（≈ 英文 80 字符的量）。实测现有 12 条最长 56 字符。
-  if (clean.length > 42) {
-    return `✗ 太长（${clean.length} > 42）—— Rules 是纪律不是记事本：\n`
+  if (clean.length > RULE_BODY_MAX) {
+    return `✗ 太长（${clean.length} > ${RULE_BODY_MAX}）—— Rules 是纪律不是记事本：\n`
       + `  每条要一眼扫完。细节/出处/例子 → 写进 concepts/ 概念页，这里只留一句话结论。`;
   }
   if (/\[\[|\]\]|https?:\/\//.test(clean)) {
@@ -855,9 +859,15 @@ export async function cmdTask({ dir, action, id, section, note, as }) {
         return SKIP;
       });
       if (others.length) {
+        // 提示要具体到「该转成哪个」：只报「已有 N 个进行中」实测不够 ——
+        // 用户改方向时，旧任务是「搁置」（不做了），与「滞留中」（还要做）不同，
+        // 选错会让下会话分不清该不该接着干。
         warning = `\n  ⚠ 已有 ${others.length} 个 [进行中]: ${others.join(', ')}\n`
           + '    同时只有一个进行中才说得清"现在在做什么"。\n'
-          + '    把不需要的转走: abs todo state <id> --note 讨论中|滞留中';
+          + `    旧任务怎么处理 ——\n`
+          + `      • 用户改方向了/不做了 → abs todo state <id> --note 搁置\n`
+          + `      • 还要做，只是卡住了   → abs todo state <id> --note 滞留中\n`
+          + `      • 还想商量            → abs todo state <id> --note 讨论中`;
       }
     }
     const r = await upsertTask(root, {

package/src/todo.js

@@ -340,8 +340,13 @@ function indexLinkSectionNeeds(section) {
 }
 
 /** 任务状态标记（行首，方括号）。替代原 Backlog/Today/Blocked 三区的区分作用。
- * 放在 id **之前**，与 Done 结语的 `【落地】` 形态区分开（那是行尾、结语用）。 */
-export const TASK_STATES = ['进行中', '讨论中', '滞留中'];
+ * 放在 id **之前**，与 Done 结语的 `【落地】` 形态区分开（那是行尾、结语用）。
+ *
+ * 「搁置」与「滞留中」的区别（2026-10-05 用户定，别合并）：
+ *   滞留中 = 还要做，只是卡住了（等外部/等信息） → 下会话该捡起来
+ *   搁置   = 不做了 / 用户改方向了           → 下会话不该捡，除非用户又提
+ * 混在一起会让下会话分不清「该不该接着干」。 */
+export const TASK_STATES = ['进行中', '讨论中', '滞留中', '搁置'];
 
 /** 结构重建（B 档）：以标准分区表为准重排整个文件。
  *