@fanchao8609/agent_brain_sync 1.7.8 → 1.8.0

package/skill/SKILL.md

@@ -20,12 +20,13 @@ abs todo                     # 看板（Done 折成计数；明细 abs todo --fu
 abs index / abs log          # 完整 index.md / log.md
 abs status                   # 当前项目 + 图谱概要
 abs query <词1> [词2 …]      # 检索 .brain/ 知识页（多词 OR）
+abs resolve <页名或id>       # 反查页面路径（改名后 id 不变）
 abs lint                     # 图谱体检（死链/悬挂/超限/堆积/未提炼/Rules 超限）
 
 # 写
 abs todo add <id> --note "做什么"              # 登记任务（start 同义）
 abs todo note <id> --note "断点/进度"           # 实时落 ↳ 断点 行
-abs todo blocked <id> --note "卡点原因"         # 移入 Blocked
+abs todo state <id> --note "进行中|讨论中|滞留中"  # 改状态标记（原地）
 abs todo done <id> [--as 落地|否决|仅方案]      # 完成（默认 落地）
 abs log "完成 X：…"                            # 记一行工作成果（无参=查看）
 abs note "经验一句话" [--tags 坑,docker]        # 经验实时暂存 → sources/
@@ -105,9 +106,9 @@ abs config [set user <名字>]                   # 使用者姓名（写操作
 | `## Concepts` `## Entities` `## Sources` `## Syntheses` `## Sessions` | 各类页的清单 | 每页一行 `- [[slug]] — 一句话`（`abs note`/建归档页会自动登记），load 里折成计数 |
 
 **`## Rules` 区**：铁律清单，`abs load` 每次都全量读（代码里明确不折它）。
-- 一句一条；有概念页就用 `[[链接]]` 指过去，**不在此展开**。
+- 一句一条，**不带链接**（链接去概念页自己的「## 关联连接」挂），不展开。
 - 只有「违反会丢数据 / 静默失效 / 白干活」级才进 —— 普通经验进 `concepts/`。
-- 读写：`abs rule` / `abs rule add "一句话"`（>120 字符被拒）；`abs lint` 超 30 条会报。
+- 读写：`abs rule` / `abs rule add "一句话"`（>42 字符被拒；也不接受 `[[链接]]`/URL）；`abs lint` 超 30 条会报。
 
 ### `log.md` —— 工作成果流水
 
@@ -116,13 +117,15 @@ load 只展示最新 5 条、每条按语义边界收口。
 
 ### `todo.md` —— 活看板（进度唯一真源）
 
+**只有两区**（2026-09-13 精简）：未完成的一切都进 `## Todo`，状态用**行首标记**表达。
+
 | 分区 | 放什么 |
 |---|---|
-| `## Backlog` | 想做但没开工 |
-| `## Today / In Progress` | 正在做 |
-| `## Blocked` | 卡住（附原因，`abs todo blocked`） |
+| `## Todo` | 未完成的一切。行首 `[进行中]` / `[讨论中]` / `[滞留中]`（`abs todo state`） |
 | `## Done` | 已完成，**必须带结语 `【落地/否决/仅方案】` + `(完成 YYYY-MM-DD)`** |
 
+行形态：`- [ ] [进行中] <id> [[name]] — 说明 (认领 YYYY-MM-DD)`
+
 `abs todo done <id>` 会勾选并归位到 Done 的日期组顶部，断点（`↳` 行）随迁；
 Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已完成」的组迁到 `sessions/<日期>-todo归档.md`
 （任一天有未完成则整天不迁）。**什么时候动它见「进行中」一节。**
@@ -168,9 +171,13 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
    - 快照里的任务现在真做完了 → `abs todo done <id>`（done 后下次 load 滞留自动消失）；
    - 还没做完 → `abs todo note <id> --note "接到哪/改到哪个文件"` 补断点（别空手续接）。
    滞留没清完就不算接上了状态——这是「任务做完没进 Done」的根治动作。
-3. **读命中页**：按关键词在 index 定位 → 读对应 concepts/entities 全文。
+3. **读命中页**：`abs query <词>` 检索（多词 OR）→ 拿到页名后读那几个文件。
+   ```bash
+   abs query <词>                  # 全文检索，只回命中几页
+   abs resolve <页名或id>          # 反查文件路径（页改过名时用 id 能找回）
+   ```
    > ⚠️ **绝不通读 `.brain/`**（29 页就约 11 万 token，全读塞满窗口）。
-   > 要状态→`abs load`；要主题→`abs query <词>`（只回命中几页）；要某页→只读那页。
+   > 要状态→`abs load`；要主题→`abs query <词>`；要完整页清单→`abs index`（或直接读 `.brain/index.md`）；要某页→`abs resolve` 拿到路径后**只读那一页**。
    > 汇总多文件时用 `ctx_execute` 类工具在沙箱里处理，**只打印结论**。
 4. **续 todo**：默认续 todo 分支 → 把顶部未完成项当当前任务开做。
 5. **登记新任务**：有明确新任务而 todo 没有 → `abs todo add <id> --note 做什么` 再动工。
@@ -179,12 +186,24 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 **todo 不是收尾仪式，是随改随写的活看板。** 每个任务边界立即更新，与 git commit 同反射。
 
-| 时机 | 动作 |
-|---|---|
-| 认领新任务 | `abs todo add <id> --note "做什么"` |
-| 子任务做完 | `abs todo done <id>` |
-| 碰壁/阻塞 | `abs todo blocked <id> --note "卡点原因"` |
-| 被打断/干到一半 | `abs todo note <id> --note "改到哪个文件/到哪步"` |
+**看板只有两区**：`## Todo`（未完成的一切）+ `## Done`（已完成）。
+未完成的状态用**行首标记**表达：`[进行中]` `[讨论中]` `[滞留中]`。
+
+| 时机 | 动作 | 落到哪 |
+|---|---|---|
+| 认领新任务 / 聊出一个话题 | `abs_task {action:start, id:"T-1", note:"做什么"}` | Todo `[进行中]` |
+| 只在讨论、还没动手 | `abs_task {action:state, id:"T-1", note:"讨论中"}` | 原地改标记 |
+| 卡住了/等人等数据 | `abs_task {action:state, id:"T-1", note:"滞留中"}` | 原地改标记 |
+| 被打断/干到一半 | `abs_task {action:note, id:"T-1", note:"改到哪个文件/到哪步"}` | 原地 ↳断点 |
+| 子任务做完 | `abs_task {action:done, id:"T-1", note:"结语"}` | Done |
+| 总结出经验/坑/规律 | `abs_note {text:"一句话", tags:"坑,docker"}` | sources/ |
+
+> **为什么只有两区**（2026-09-13 实测）：跨 4 个项目，Backlog/Today 常年 **0 条**，而 log.md
+> 有 120 条。根因是 AI 的工作方式「一口气做完」——任务从开始到完成都在同一会话内走完，
+> 中间那个「挂到进行时分区」的动作既来不及也不需要。**进行时分区是符合直觉但不符合实际
+> 工作流的抽象**，故删掉，状态改用行首标记。
+
+**核心：事件发生的那一刻就落，别攒到收尾。** 动作一变，扫一眼属于哪行，调对应工具。
 
 **经验刚冒出来就落**：`abs note "一句话经验" --tags 坑,docker` → 暂存 `sources/`（幂等去重）。宁少勿滥。
 
@@ -195,6 +214,30 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 > Op​enCode todowrite / pi `/list`）—— 那些多是会话内临时，不写 `.brain/todo.md`，
 > 下会话接不上、收尾没影。原生 todo 顶多记“本会话不跨断点的临时拆解”。
 
+## 写文件 = 任务开始（收到登记提醒就立即做）
+
+**改了项目文件，说明有任务在进行。** hook 观测到写入会就地注入一条
+`[abs 登记提醒]`（pi 在 `turn_end`、Op​enCode 在 `tool.execute.after`），**不等会话结束**。
+
+**为什么不等收尾**（实测教训）：旧设计只在会话末尾提醒 —— 而那时用户已想结束、
+AI 只想收尾不想登记。且「任务何时开始」只有写文件那一刻清楚：等收尾回忆必漏。
+
+收到登记提醒，当场判断（**三选一，不猜**）：
+
+| 情况 | 动作 |
+|---|---|
+| 属于某个任务，todo 里没有 | `abs todo add <id> --note "做什么"` |
+| 属于已在登记的任务 | `abs todo note <id> --note "改到哪/下一步"` |
+| 纯讨论/调研/只改 `.brain/` 自身 | **无需登记**，回「跳过」即可 |
+
+> **「跳过」是合法选项** —— 不逼你造任务。假条目比不登记更坏（污染看板，下会话当真）。
+>
+> **判据是「整个项目」，但排除 `.brain/` 自身**：`abs note` / `abs log` 也写文件，
+> 但那是**记录行为**不是任务 —— 不排除则每落一条经验都弹一次提醒，纯噪音。
+>
+> **提醒很频繁是故意的**：每轮写文件都提醒（同一文件改第二回也提）。嫌吵就当场登记，
+> 登记完下一轮仍有写入还会提 —— 它盯的是「有活干就有登记」，不是「提醒过一次就算了」。
+
 ## 每轮结束：收尾循环（Stop / 告一段落后必做）
 
 **每个任务边界、被 Stop/打断、告一段落时，别停半空。** 这是“开场接上状态、结束落回状态”的闭环。
@@ -208,15 +251,15 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 收到 Stop / "结束/先这样/切别的事" / 长任务告一段落，立即执行：
 
-1. **读 todo** → `abs load`，看 Today 还有哪些没完成。
+1. **读 todo** → `abs load`，看 Todo 还有哪些没完成。
 2. **判有没有做完没登记** → 实际完成了漏登记的 `abs todo done <id>`；做到一半补
-   `abs todo note <id> --note 断点`；碰壁 `abs todo blocked`。别让干完的事还停 Today。
+   `abs todo note <id> --note 断点`；卡住的 `abs todo state <id> --note 滞留中`。别让干完的事还留在 Todo。
 3. **沉淀经验（该沉淀才沉淀）** → 踩了值得记的坑/有可复用技巧/跨会话判断 → `abs note`
    暂存；值得深提炼的（规律/坑/决策）按 Teardown 走完整流程。
 4. **更新 index/log/todo** → 新页同步进 index；`log.md` 倒序记一行**工作成果**摘要
    （`abs log "完成 X：..."`，不是工具动作）；todo 对账。
    **新规律是「违反会丢数据/静默失效/白干活」级别 → 往 index 的 `## Rules` 加一行**
-   （短句 + `[[概念页]]`，不展开）。普通经验不进 Rules —— 否则会长成第二份概念库。
+   （短句，不带链接；链接去概念页挂）。普通经验不进 Rules —— 否则会长成第二份概念库。
    跑 `abs lint` 确认自洽。
 
 **完成标准**：看板反映真实状态（Done 无滞留半成品）、该沉淀已落、index/log/todo 与事实一致。
@@ -227,8 +270,11 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 1. **暂存线索**：`abs note`（或建 `sources/YYYY-MM-DD-slug.md`）记做了什么、改哪些文件、验证命令。
 2. **抽规律**：值得留的 → `concepts/<kebab-slug>.md`：触发场景/❌表现/🛠根因+解法+验证。挂双链。
+   **同时检查：旧页里有没有被本次推翻的说法？** 有 → `abs supersede <旧页> --by <新页>`
+   （别删页；删了会让下个会话重踩同一个坑、重新记一遍）。核实过的新页把 `status` 改成 `active`
+   （`abs note` 落的页默认是 `draft`）。
 3. **沉淀实体**：碰了重要未记录的事物 → `entities/<TitleCase>.md`。
-4. **对账 todo**：滞留 Today 归位（Done 标日期 / Backlog 补断点）；遗留 bug 写 Backlog/Blocked。
+4. **对账 todo**：做完的归位 Done（标结语+日期），做一半的补断点，卡住的改 `[滞留中]`。
 5. **综合(可选)**：推进了选型/取舍 → `syntheses/`。
 6. **收拢 sources**：提炼成规律的删 source，**同步清指向它的引用**（防死链）。
 7. **修 index + 记 log**：新页同步 index；**过 Rules 门槛的规律加一行到 `## Rules`**；
@@ -239,10 +285,28 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 ## 知识页格式
 
-统一 frontmatter：`tags / author / updated / status`（`status: draft`，或 `reviewed` = 冲突已裁决）。
+统一 frontmatter：`tags / author / updated / status`。
 `tags` 首标签 ∈ `entity|concept|source|synthesis|session-log`。`author` 与 `entities/<name>.md` 同名。
 
+**`status` 三个值（生命周期，别写别的）：**
+
+| 值 | 含义 | 读取侧行为 |
+|---|---|---|
+| `active` | 当前有效（**缺字段默认就是它**，存量页无需改） | 正常展示 |
+| `draft` | 待核实（`abs note` 新落的经验默认这个） | 展示但标注 `[draft 未核实]` |
+| `superseded` | **已被推翻，别再依据它** | `query` 默认隐藏（计数据告知） |
+
+**推翻一条经验**（不要删文件！）：
+```bash
+abs supersede <页名> --by <取代它的新页>   # 不写 --by 也行 = 单纯弃用，无替代
+```
+→ 把 `status` 改成 `superseded` 并写 `superseded-by`。**历史必须留**：删了会让下个会话重踩同一个坑、重新记一遍。
+→ 核实后发现仍有效：把 `status` 改回 `active`（一行，可反悔）。
+→ 拒写悬空引用：`--by` 指向不存在的页会直接拒绝。
+
 - **每页必须有 `## 关联连接`**，用 `[[页面名]]` 链相关页 —— 严禁孤岛页。
+  **链路解释写在 `—` 后面**（如 `[[hook-throttle-alignment]] — 节流判据要对齐「真收尾」`），
+  这样 AI 不点开就知道该不该跟进；只写链点不写解释，等于没链。
 - **命名即链接**：`[[Docker]]` → `entities/Docker.md`；`[[docker-prisma-429]]` → `concepts/`。不建别名层。
 - **知识冲突**：不静默覆盖，加 `## 知识冲突` 两版都留、标来源时间，交人工裁决。
 - 概念页骨架：`触发场景 / ❌表现(贴报错) / 🛠解法(根因+修复+验证命令) / 关联连接`。
@@ -251,9 +315,12 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 - `abs query <词>` 检索（多词 OR）→ 读命中页 → 答用 `[[页面名]]` 标来源。
   **代码问题（符号在哪/谁调用）不在 .brain，直接读源码**；.brain 只答"踩过什么坑/上次做到哪"。
-- `abs lint` 体检：死链/孤岛/**悬挂页**/缺 frontmatter/模板残留/超尺寸/sources 堆积/**超龄未提炼**/index 漏列/Rules 超限。
+  已被推翻的经验默认不返回（`--all` 可看）—— 但若你确实需要拿旧结论对照，记得它已被推翻。
+- `abs lint` 体检：死链/孤岛/**悬挂页**/缺 frontmatter/模板残留/超尺寸/sources 堆积/**超龄未提炼**/index 漏列/Rules 超限/**取代者悬空**/**draft 超龄**。
   - `NO-INBOUND`：有出边但无人 `[[链接]]` 到你 = 挂在图上没人接（孤岛检查只抓"零出零入"）。
   - `SOURCE-UNDISTILLED`：source 超 7 天仍未链到任何 concept = 暂存了没归位。
+  - `SUPERSEDED-DANGLING`：`superseded-by` 指向的页不存在（删页后忘同步）。
+  - `DRAFT-STALE`：concepts 等长期停在 `draft` = 既没核实也没推翻，核实/推翻后各改一行。
 
 ## 三层分工