@topmindspace/topmind-skills 4.13.0

package/topmind/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: topmind
+version: 4.13.0
+description: >-
+  topmind 总入口与多意图路由（类别/专题/笔记/交付）。Use when 用户说 topmind、意图模糊、或需要
+  收→整→写 分步。单意图明确时直接用 topmind-capture|organize|write|memory|maintain|loop|weread|x|ledger|wechat。
+  Do NOT invent parallel front doors; do NOT skip a matching sub-skill.
+action_category: router
+triggers:
+  - topmind
+  - 知识库
+  - 工作区
+tags: [router, entrypoint, topmind]
+entrypoint: true
+compatibility: >-
+  topmind workspace with {NN-Name}/ categories. Host file tools primary; UTR optional.
+  Install with shared/ sibling for progressive disclosure links.
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind
+updated: 2026-09-22
+degradation: ../shared/capability-degradation.md
+---
+
+# topmind Router
+
+唯一日常入口：`topmind`。子 skill 是**实现模块**（可被 host 单独激活），不是产品第二前台。
+
+## Activation checklist（激活后立即做）
+
+1. 确认工作区根（host 提供；不硬编码绝对路径）  
+2. 扫 `{NN}[- ]{Name}/` 或 UTR `list-categories`（WorkspaceModel：role / hidden / source）  
+3. 读 `topmind.yaml`（contract_version **4**）若存在  
+4. 推断：**category · topic · object · action · writeback_mode**（auto|confirm）  
+5. 派生子 skill 语义（逻辑路由；不假装进程内调用 API）  
+6. 回执含路径；**不**自动链式下一 skill；记忆/提升类建议须用户确认  
+
+
+## Quick Reference
+
+```text
+用户说什么              → 路由到哪            → 目标位置
+─────────────────────────────────────────────────────────────
+记/存/收/链接/想法       → topmind-capture     → 动态周期本 / 专题 / Inbox
+整理本周/理顺流水        → topmind-organize    → 活动窗口就地理顺 + 建议（确认后写）
+整理/分析/研究/总结/对比 → topmind-organize    → 当前专题 / Inbox 路由 / 活动窗口
+写/改/稿/交付/导出       → topmind-write       → delivery 或专题根
+公众号/微信排版/定稿发稿  → topmind-wechat      → 创作类 YYYY-公众号/ 交付包
+记住我/更新我的情况      → topmind-memory      → memory/profile.md（主 memory）
+周期反思                 → topmind-memory      → memory/periodic/{YYYY}/（周期反思）
+开/并专题（内容夹）      → topmind-organize    → {大类}/{YYYY-主题}/（非 memory/topics）
+记住/专题语义记忆        → topmind-memory      → 仅用户明说 → 可选 memory/topics/
+快速体检/诊断/修复/清理  → topmind-maintain    → 工作区确定性检查
+loop/整体体检/巡检       → topmind-loop        → .topmind/loop/ 可恢复
+微信读书/同步划线        → topmind-weread      → connector 解析类别
+发推/推特/x.com          → topmind-x           → connector 解析类别
+记账/记一笔/花了/存入    → topmind-ledger      → memory/ledgers/（默认自己）
+公众号创作子技能细节      → topmind-wechat      → write 族；见 SKILL.md
+不确定 / 多意图          → 本 router 拆步      → 先 capture 再建议
+```
+
+English: capture → capture · weekly review/organize (activity window) → organize · write → write · about me → memory/profile · period reflection → memory/periodic/{YYYY}/ · new topic folder → organize (content category) · doctor → maintain · loop → loop · bookkeeping/spent/deposited → ledger (`memory/ledgers/`, personal default).
+
+读配置：`stream.packing`（默认 weekly）· `stream.year_dir`（默认 true）· `memory.layers.global.file`（`profile.md`）。  
+**活动窗口**（Desktop/Kernel 与 organize 共用）：近期周期本 ∪ 近期改动笔记 ∪ 增补锚定的原文——不只「最新周期文件名」。
+
+## Core Model
+
+```text
+User experience:     capture-first
+Data organization:   category-first + topic-emerges
+Object model:        category → topic → object
+Actions:             capture | organize | write | memory | maintain | loop | connector | ledger (optional)
+Save settings:       auto | confirm
+```
+
+内容约定：[`../shared/project-model-brief.md`](../shared/project-model-brief.md)（**6 条核心规约**）。  
+输出语言：[`../shared/output-language.md`](../shared/output-language.md)（文档 AI：用户要求 → 原文 → 工作区 locale；产品 AI 建议条/待办：用户要求 → 宿主 UI → 工作区 locale）。  
+类别角色 / 扩展：[`references/template-categories.md`](references/template-categories.md)。  
+Host 加载说明：[`../shared/host-loading.md`](../shared/host-loading.md)。
+
+## Routing Question
+
+```text
+Which category? Which topic (or loose note)? Which object? Which action? Which save setting?
+```
+
+不要让用户选内部模块名。从自然语言推断。
+
+### Capture-first
+
+- 高信心类别+专题 → `{大类}/{专题}/`  
+- 高信心类别、中信心专题 → 写入专题 + 回执 `route_reason`  
+- 高信心类别、无专题 → `{大类}/*.md`，建议是否升级专题  
+- 低信心类别 → **role:buffer**（常为 `00-Inbox/`）  
+- 跳过 `hidden` 类别  
+
+### Minimum Context
+
+1. 扫描 `{workspace-root}/` → `{NN}[- ]{Name}/`  
+2. 读 `topmind.yaml`（template · `categories.extensions` · `categories.overrides` · separator）  
+3. 有 UTR → 优先 `list-categories`  
+4. 强推断专题时再读 `topic.md`（出稿/问答同样：**有则先读首页**，不强制创建）  
+5. **默认不加载整工作区**  
+
+### 复利纪律（不改结构）
+
+- **organize**：整理/总结默认落盘专题笔记，不只回话  
+- **write**：先 `topic.md`（若有）再必要笔记  
+- **memory**：仅用户明确沉淀；capture **禁止**改 topic.md  
+- **禁止**硬索引 `INDEX.md`、平行 wiki 树、entities/ 默认目录 
+
+## Disambiguation & Multi-Intent
+
+真源：[`../shared/trigger-disambiguation.md`](../shared/trigger-disambiguation.md)。  
+多意图：[`references/multi-intent.md`](references/multi-intent.md)。  
+Connector：[`references/connector-resolution.md`](references/connector-resolution.md)。
+
+## Sub-Skill Receipt Chaining
+
+- 子 skill **不得**自动 dispatch 下一 skill  
+- 下一步由 Router 再裁决或用户显式发起  
+- 例外：回执可**建议**「稍后 organize / loop」——仅用户面  
+
+## Tool Boundary
+
+主路径：host 文件工具 + project-model-brief。Skills pack **不依赖** Pi / `pi-agent-core`；不要编造 bash / shell。宿主若有唯一片段替换，中段改稿优先用它。  
+降级：[`../shared/capability-degradation.md`](../shared/capability-degradation.md)。
+
+UTR 可选（MCP primary+danger 共 19；注册表 28 = 8 域 / 28 命令，见 TOOLS.md）：`list-categories` · `list-topics` · `inspect-topic` · `list-topic-files` · `list-inbox` · `create-topic` · `capture-note` · `save-output` · `contract.validate` · `contract.reseed` · `memory.promote` · `memory.digest` · `memory.append-profile` · `memory.append-topic` · `doctor-workspace` · `plan-inbox-routing` · `archive-topic` · `archive-stream-year` · `restore-safety-receipt`。
+
+字段始终独立 **`category` + `topic`**（真实目录名，非写死编号）。
+
+## 保存设置
+
+- **auto**：直接写 + 路径回执（危险动作可逆）  
+- **confirm**：先审阅再写  
+
+详见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)。  
+**6 条核心规约**：见 [`../shared/project-model-brief.md`](../shared/project-model-brief.md)。
+
+## Error Handling
+
+写入失败时：
+- 磁盘满 / 权限不足 → 报错 + 已备回复制位置；不静默丢数据
+- 路径过长 / 非法字符 → 提示用户缩短专题名
+- protection:locked → 内容编辑允许（任务级首写快照）；可恢复删/归档允许；永久删 locked 仅用户
+- 工作区不存在 topmind.yaml → 按默认契约解释 + 回执标注「默认契约」
+
+
+
+`source_type`: `user-original` | `external-capture` | `ai-derived`。可选 `status` / `priority` / `method`。
+
+## Workspace Shape
+
+```text
+{workspace-root}/
+├── topmind.yaml             # v4 行为契约
+├── memory/                 # 语义平面（profile / periodic/{YYYY}/ / topics / todo.md / 可选 ledgers/）
+├── .topmind/               # 系统平面（index / loop / logs，可重建）
+├── {NN}-{Name}/               # buffer / loose-stream / deep-work / …
+├── {NN}-Outputs/              # role: delivery（常 88-交付）
+└── {NN}-Archive/              # role: system（常 99-归档）
+```
+
+专题：`topic.md?` + `*.md` + `images/?`。散记可在大类根。
+
+## Multi-Workspace
+
+只操作**当前 active** 工作区根。切换由 Desktop/host 负责。

package/topmind/references/connector-resolution.md

@@ -0,0 +1,11 @@
+# Connector Category Resolution
+
+`topmind-weread` / `topmind-x` 同步目标类别优先级：
+
+1. `topmind.yaml` → `ingest.connectors.{weread|x}.syncCategory` 显式值（非 `auto`）  
+2. 模板 `connectorHints`：`preferSlot` → `preferRole` + `nameKeywords`  
+3. 首个 `role: deep-work` → 首个 `loose-stream` → `buffer`  
+
+`syncCategory: "auto"` 走 2–3。
+
+Connector 是**可选** skill（`optional: true`），不纳入核心 7 skill 强制依赖。  

package/topmind/references/multi-intent.md

@@ -0,0 +1,17 @@
+# Multi-Intent Resolution
+
+当用户请求包含多个意图时，按以下矩阵裁决（与 `shared/trigger-disambiguation.md` 一致）：
+
+| 意图组合 | 裁决 | 说明 |
+|---------|------|------|
+| capture + organize | 先 capture，回执中建议 organize | 先确保材料落地 |
+| capture + memory | 先 capture，回执中建议 memory | 先存笔记再更新我的情况 / 周期反思 |
+| organize + write | 先 organize 提炼，再 write 输出 | 分两步 |
+| organize + memory | 先 organize 候选，再 memory 落盘 | organize 产出列表 |
+| write + memory | 先 write，回执中建议 memory | 写作不改 memory/profile |
+| 整理 inbox | `topmind-organize` + `plan-inbox-routing` | 不是 maintain/loop |
+| 清理工作区 | `topmind-maintain` | 系统健康 |
+
+**三个以上意图**：分解为顺序步骤，逐步执行，每步返回回执。
+
+子 skill 回执里的「下一步」**不构成**自动链式触发。  

package/topmind/references/template-categories.md

@@ -0,0 +1,45 @@
+# Template-Driven Categories + WorkspaceModel
+
+topmind 使用**模板驱动默认角色** + **配置扩展** + **FS 自发现**。
+
+读 `{workspace}/topmind.yaml`：
+
+- `template` → `templates/{id}.json` 出厂类别  
+- `categories.extensions` → 用户新增一级类的角色/行为  
+- `categories.overrides` → 对已有 slot 的覆盖（含 hidden）  
+
+解析实现：`lib/workspace-model.mjs` → `resolveWorkspaceModel`。
+
+## Roles
+
+| Role | Purpose | Skills |
+|------|---------|--------|
+| `buffer` | Inbox — 未归类 | capture 兜底；loop inbox scope |
+| `loose-stream` | 持续流，默认平铺 | capture / organize；低密度 memory |
+| `deep-work` | 研究 / 创作 | capture / organize；高密度 memory |
+| `fallback` | 兜底，定期清理 | maintain 提醒 |
+| `reference` | 反复引用素材 | connector 目标；少改 memory |
+| `delivery` | 交付物扁平层 | write `save-output` |
+| `system` | 归档 / 备份 | maintain；可逆性 |
+
+## Template 参数化规约
+
+| 规约 | 模板 / 扩展属性 |
+|------|----------------|
+| 专题涌现 | `minNotes`（默认 2） |
+| 松散流 | `specialBehavior: "flat-default"` |
+| 兜底清理 | `catchAll: true` + `retentionDays` |
+| 参考资料 | `referenceOnly: true` |
+
+角色驱动路由，**不要硬编码** `10-` / `20-` 等具体编号（目录名以工作区为准）。
+
+## Dynamic discovery
+
+任意匹配 `{NN}[- ]{Name}/` 的目录均为类别。用户可扩展；系统扫描根目录发现。  
+自定义类若无 config/template 属性 → 默认 `role: deep-work`（可通过 Desktop 设置或写 `categoryExtensions` 声明）。
+
+## list-categories 字段
+
+UTR / Desktop 返回同一语义：
+
+`slot` · `name` · `directory` · `role` · `specialBehavior` · `source` · `ok` · `hidden`  

package/topmind-capture/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: topmind-capture
+version: 4.13.0
+description: >-
+  把链接、摘录、随手记收进动态周期本、Inbox 或专题。Use when 记一下、收进、剪藏、保存链接、capture、save URL/idea。
+  Do NOT use for 整理本周、出稿、写我的情况、doctor/loop、微信读书、X.
+action_category: capture
+triggers:
+  - 收集
+  - 收进
+  - 保存
+  - 剪藏
+  - 记一下
+  - 临时存放
+  - 随手记
+  - 想法
+  - 灵感
+  - 暂存沉淀
+  - 记录
+  - 备忘
+  - 存一下
+  - 暂存
+  - 笔记
+  - 抄下来
+  - 摘录
+  - capture
+  - note
+  - save
+tags: [capture, inbox, note, material]
+entrypoint: false
+compatibility: topmind workspace. Host file tools or optional UTR capture-note.
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind
+updated: 2026-08-15
+degradation: ../shared/capability-degradation.md
+---
+
+# topmind Capture
+
+先存材料（用户动词：**记一下**）。不负责重塑、交付、诊断或外部连接。
+
+## Activation checklist
+
+1. 工作区根 + `list-categories` / 扫盘（跳过 hidden）  
+2. 读 `topmind.yaml` 的 `stream.packing`（默认 **weekly**）  
+3. 按内容性质选 **真实目录名**（role；禁止写死编号）  
+4. **日常/动态** → 追加到当前周期本；专题明确 → 专题根；不清 → Inbox  
+5. 写 frontmatter；白话回执（如「已记到每周一本」）；**不**自动 organize/write  
+
+## When NOT to use
+
+- 整理已有内容 → `topmind-organize`  
+- 基于素材写稿 → `topmind-write`  
+- 写入「我的情况」/ 周期反思 → `topmind-memory`  
+- 系统体检 / 巡检 → `topmind-maintain` / `topmind-loop`  
+- 微信读书 / 发推 → connectors  
+
+消歧总表：[`../shared/trigger-disambiguation.md`](../shared/trigger-disambiguation.md)。
+
+## Inputs
+
+- URL / 文件名 / 来源标签  
+- 摘录、想法、自由文本  
+- 当前类别/专题（若有）  
+- 可选 title、route confidence  
+
+## Routing（低摩擦）
+
+```text
+先 list-categories / 扫盘 + 读 topmind.yaml（schema v4）
+跳过 hidden；按 role + 内容性质选 directory（真实目录名）
+读 stream.packing（atom|daily|weekly|monthly，默认 weekly）
+
+high cat + high topic     → {大类}/{专题}/*.md（新文件）
+high cat + med topic      → 专题 + route_reason
+loose-stream + 无专题     → 当前周期本 append（packing≠atom）
+  packing weekly          → {动态类}/[YYYY/]YYYY-Www.md 今日段落下追加（year_dir 默认 true）
+  packing daily           → {动态类}/[YYYY/]YYYY-MM-DD.md 追加
+  packing monthly         → {动态类}/[YYYY/]YYYY-MM.md 追加
+  packing atom / forceAtom→ {大类}/YYYY-MM-DD-标题.md 新文件
+low cat                   → role:buffer（Inbox）
+```
+
+默认不访谈分类。存完可移动。禁止写死类名编号。用户只要「记一下」——不要解释 packing 术语（回执可用「本周动态」）。
+
+UTR：`capture-note`（自动识别周期本）。Desktop：`ingestInbox` dest.mode=`stream`（默认）。
+
+## Provenance
+
+`source_type`: `user-original` | `external-capture` | `ai-derived`。
+
+```yaml
+title: …
+source_type: external-capture
+captured_at: 2026-07-13T15:30:00+08:00
+topic: {专题名}
+category: {大类目录名}
+route_confidence: medium
+route_reason: …
+status: todo
+```
+
+长 URL / 网页：[`../shared/long-url-capture.md`](../shared/long-url-capture.md)。
+
+| 层 | 谁 | 能力 |
+|----|----|------|
+| L1 | Desktop `fetchUrl` / host fetch | Mozilla Readability + 启发式 |
+| L2 | Desktop 增强渲染 | SPA 空壳（ephemeral Chromium） |
+| L3 | 手动粘贴 | 永远可用 |
+| L3+ | 浏览器扩展 Clip Bridge | 活 DOM Readability → Desktop 清洗落盘 |
+
+Agent host 能 fetch 则提取正文，否则保留 URL + 摘录；推荐日常剪藏走 L3+。
+
+### 本地文档 / Office / 邮件 / 统一捕获
+
+协议：[`../shared/document-ingest.md`](../shared/document-ingest.md)。
+
+| 入口 | 能力 |
+|------|------|
+| **Desktop 统一捕获** | ⌘N 层 / ⌘⇧N 全局便签；智能粘贴文件；笔记+文档复合提交 |
+| **Desktop 知识加工 Hub** | 队列、批文件夹、转换器检测/安装；默认 anydoc（docx·doc·pdf·xlsx·pptx·odt·rtf·epub·csv）+ 内置 eml/html；可选 markitdown/pandoc |
+| **Agent** | 有转换能力则转 MD 后按 capture 写回；否则路径说明进 Inbox |
+
+默认 **md-only**；失败 original-fallback。不新增并列 skill 入口——仍走 `topmind` → `capture`。
+
+## Workflow
+
+1. 按内容性质推断类别（动态发现），再推断专题  
+2. 类别不清 → Inbox  
+3. 保留 provenance；长文标注截断  
+4. 按保存设置写入（见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)）  
+5. 回执：路径、目标、信心、下一步（不自动触发其他 skill）  
+
+**边界**：只写材料笔记。**禁止**改 `topic.md`、禁止自动 organize/memory。存完可在回执建议「需要时整理」——仅用户面，不自动链式。
+
+「刚才收哪」：按 mtime 扫近期 `.md`（或 UTR `list-recent-captures` advanced）。
+
+## Capability Degradation
+
+见 [`../shared/capability-degradation.md`](../shared/capability-degradation.md)。主命令：`capture-note` · `list-categories` · `list-topics`。
+
+## 保存设置
+
+- **自动保存 (auto)**：直接写入并返回路径回执（path receipt）
+- **需要审阅 (confirm)**：先进入目标路径/内容审阅入口再保存
+- Host 可编码为 `writeback_mode: auto | confirm`。详见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)。
+

package/topmind-ledger/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: topmind-ledger
+version: 4.13.0
+description: >-
+  通用记账到记忆平面（默认个人/自己账本，用户自建账本与分类）。Use when 记账、记一笔、花了、存入、查看账单、账户余额。
+  Do NOT use for 记一下到动态、待办、微信读书、发推、Feishu/lark-cli.
+action_category: memory
+triggers:
+  - 记账
+  - 记一笔
+  - 花了
+  - 存入
+  - 查看账单
+  - 账户余额
+  - bookkeeping
+  - log expense
+tags: [ledger, bookkeeping, memory, optional]
+entrypoint: false
+compatibility: Host file tools or Kernel writeback. Desktop optional mini-app. Feishu/lark-cli is not required.
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind
+updated: 2026-08-29
+degradation: ../shared/capability-degradation.md
+---
+
+# topmind 记账
+
+可选技能：把一笔收入/支出追加到语义平面账本。**不是**第二前台入口；日常仍只走 `topmind`。
+
+空工作区只有一本默认 **个人 / 自己** 账本。用户再加账本和分类。历史上的 ClassFund / Giggs / Mom 只是 50-账本 *行格式* 参考，**不是**产品默认账本。
+
+```text
+{memory.dir}/ledgers/Personal.md    # 默认「自己」
+{memory.dir}/ledgers/{Book}.md      # 用户新增
+{memory.dir}/ledgers/catalog.md     # 用户分类
+```
+
+## When NOT to use
+
+- 「记一下」到动态/Inbox → `topmind-capture`
+- 待办清单 → `memory/todo.md`（todo-engine）
+- 微信读书 / X → `topmind-weread` / `topmind-x`
+- 飞书多维表格 / `lark-cli` / `sync_feishu_ledger_cache.py` — **不是**本 skill 的写路径
+
+## 触发
+
+| 用户说 | 动作 |
+|--------|------|
+| 花了 / 支出 / 买了 | 支出 |
+| 存入 / 收入 | 收入 |
+| 记账 / 记一笔 | 捕获一笔（缺金额则问清） |
+| 查看账单 | 读流水 |
+| 账户余额 | 读 Current balance |
+
+未点名账本 → 默认个人本。短语里出现用户已有账本或分类名才落到那本/那个分类。不要为「班费」发明 ClassFund，除非用户已经建了那本账本。
+
+## 落盘形状
+
+```markdown
+# Personal Ledger
+
+> Cloud account: 自己
+> Current balance: 0.00 元
+
+## Transactions
+
+- [YYYY-MM-DD HH:MM:SS] 收入 +523.00 元
+  分类：工资；备注：…
+- [YYYY-MM-DD HH:MM:SS] 支出 -50.00 元
+  分类：运动；备注：买羽毛球拍
+```
+
+**Append-only**：只追加新行并更新 `Current balance`，不改历史行。
+
+## 写入
+
+Host 文件工具或 Kernel `appendLedgerEntry` / `captureLedgerPhrase`（经 writeback-engine）。回执含目标路径 + affected files。见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)。
+
+Desktop 可选小应用（看板 / 流水 / 分类 / 快捷记账）。**如何打开**：启用后从 AI 工作区应用 pane、状态栏「记账」chip、命令面板「记账」打开；关掉插件后这些入口消失（不是 PrimaryNav，也不是侧栏项）。**账本路径**即 `{memory.dir}/ledgers/...`，小应用展示当前本相对路径。无 Desktop 时本 skill 仍可用。Obsidian 不发记账小应用。
+
+## 保存设置
+
+- **自动保存 (auto)**：直接写入并返回路径回执（path receipt）
+- **需要审阅 (confirm)**：先进入目标路径/内容审阅入口再保存
+- Host 可编码为 `writeback_mode: auto | confirm`。详见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)。

package/topmind-loop/DESIGN.md

@@ -0,0 +1,82 @@
+# topmind Loop — Design
+
+> Companion to [`SKILL.md`](./SKILL.md). Design rationale and constraints only.
+
+## Why Loop Exists
+
+UTR 提供 **8 域 / 28** 条确定性命令；`doctor-workspace` 做规则健康检查。Loop 在之上增加**语义层**：阅读 `topic.md` 与笔记、对照 skill 契约、再调用 UTR 修复。
+
+## Design Choice — Skill + Agent + State File, Not CLI
+
+Three pieces, no more:
+
+```text
+loop = SKILL.md (规约) + agent host (自带 LLM) + .topmind/loop/*.md (进度落盘)
+```
+
+### Rejected Alternatives
+
+| Alternative | Why rejected |
+|---|---|
+| Independent CLI binary (`topmind-loop ...`) | Adds another install shape, breaks topmind's single-frontend principle (only `topmind` is a daily entry). |
+| TUI panel | Premature. `.topmind/loop/*.md` files already give visibility via any markdown viewer; TUI duplicates that. |
+| Provider-configurable LLM | The agent host already has LLM context. Adding a provider config layer = double work + new failure modes. |
+| JSON `LoopReport` | Markdown state files are human-readable AND machine-parseable (frontmatter-style fields at top). JSON hides what loop did from the user. |
+| Loop as `topmind-maintain` sub-action | Loses the independent identity; users lose the single keyword `loop` as a verb. |
+| Per-category state files (`.topmind/loop/categories/10-动态.md`) | Explodes file count; one `.topmind/loop/topics.md` with category-prefixed cursors is more readable and still auditable. |
+
+### Why `.topmind/loop/` (not in scope root)
+
+Three reasons:
+
+1. `.obsidian/` / `.git/` precedent — hidden directory convention is already established.
+2. Workspace-spec §1.1 says scopes hold topic material only. State files are loop runtime, not topic material.
+3. Obsidian / Finder / VS Code ignore hidden directories by default — loop state doesn't pollute the user's main views.
+
+### Why cursor + done/total
+
+A cyclic loop must be resumable. Two competing approaches:
+
+- **Checkpoint per item** (e.g. `.topmind/loop/topics/02-研究/2026-示例研究.state`) — more granular but explodes file count.
+- **Single state file with `cursor` field** (chosen) — coarse but readable. User can hand-edit cursor to skip or reorder, which is more useful than per-item checkpoints for an audit/cleanup loop.
+
+Trade-off accepted: if the loop is interrupted mid-item, that item starts over on resume. Loop semantics are idempotent (read → judge → fix → log), so this is safe.
+
+## Scope × File Matrix
+
+```text
+.topmind/loop/topics.md    ← loop walks topmind-workspace/{NN 大类}/{YYYY-专题}/
+                     (大类+专题递归，category 通过 path prefix 识别)
+.topmind/loop/inbox.md     ← loop walks topmind-workspace/{buffer role category}/*
+.topmind/loop/archive.md   ← loop walks topmind-workspace/{system archive category}/*
+```
+
+Adding a new scope (e.g. a user-created category) = no schema migration, the topics scope auto-covers it. The cursor and walk log just inherit the new category prefix.
+
+## Conformance Rules (Hard Limits)
+
+Loop is aggressive but never breaks these:
+
+- System archive category is read-only by default. Mutations require explicit user opt-in per run.
+- Writes: host file tools first (primary); optional UTR accelerate. Always leave path receipts.
+- Destructive operations (archive, delete, normalize metadata) leave receipts in `.topmind/loop/{scope}.md → Receipts` and in `list-safety-receipts`.
+- Topic naming must stay `YYYY-主题` (kebab-case); loop **suggests** rename but does **not** force it without explicit user approval in the same turn.
+- **Category naming is forbidden to change in loop.** Categories are stable; renames require human + Desktop/`renameCategory`（`topmind.yaml` schema v4）。Legacy `projects/` → categories still uses UTR `migrate-v4`.
+- `state.json` is always rebuildable; loop never treats it as content truth.
+- **Sparse home hint only**：many topic notes + missing/empty `topic.md` → suggest organize/memory in the walk log; **never** auto-fill Stable Memory or create `INDEX.md`.
+- **architecture drift signals** (must flag, never auto-fix): `YYYY-类型-项目名` residues, `project_type` fields, default anchor files (`outline.md` / `setting.md` / `style.md`), v2.x command names in skill/UTR calls, top-level `projects/` / `references/` / `sources/` / `library/` roots, physical reserved-slot directories.
+
+## Relationship to Other Skills
+
+| Skill | Relationship to loop |
+|---|---|
+| `topmind-maintain` | Loop's deterministic sibling. Calls the same UTR commands. Loop adds semantic understanding on top. |
+| `topmind-organize` | Consumes loop output. When loop finds `merge-candidates.md` entries, organize can do the deeper synthesis. |
+| `topmind-capture` | Feeds loop. New captures drop into inbox → next loop run auto-processes. |
+| `topmind-write` / `topmind-memory` | Loop does NOT touch content. Write/memory are still explicit user-driven. |
+
+## Extension Notes
+
+- Inbox 新捕获由下次 loop 处理  
+- 跨专题合并建议可写 `.topmind/loop/merge-candidates.md`，再交 `topmind-organize`  
+- 触发方式可变（对话 / cron / watcher），契约仍是本 SKILL.md  

package/topmind-loop/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: topmind-loop
+version: 4.13.0
+description: >-
+  可中断的工作区语义巡检（走专题/Inbox，.loop 断点续跑）。Use when 跑一遍 loop、巡检、整体体检、复盘、
+  继续 loop、audit。Do NOT use for 快速 doctor（→maintain）、单专题整理、捕获、写作、仅记忆.
+action_category: loop
+triggers:
+  - 跑一遍 loop
+  - loop 一下
+  - 整体体检
+  - 工作区复盘
+  - 把工作区跑一遍
+  - 巡检
+  - 继续 loop
+  - 从断点继续
+  - 全面检查
+  - 复盘
+  - review
+  - audit
+  - walk
+tags: [loop, audit, walk, resumable, cyclic]
+entrypoint: false
+compatibility: topmind workspace. Progress under .topmind/loop/*. Host LLM runs the walk; UTR optional.
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/topmind
+updated: 2026-08-15
+degradation: ../shared/capability-degradation.md
+---
+
+# topmind Loop
+
+```text
+topmind-loop = SKILL.md + agent host LLM + .topmind/loop/*.md
+```
+
+不是 CLI、不是独立 runtime。独立 skill（不再是 maintain 子动作）。
+
+## Activation checklist
+
+1. 确认是**整体/可恢复**巡检（非快速 doctor）  
+2. 读/建 `.topmind/loop/*.md` 进度；可中断续跑  
+3. 步内可调用 capture/organize/… **语义**，不改类别名  
+4. 结束写摘要回执  
+
+## When NOT to use
+
+- 快速体检 / doctor / 修复索引 → `topmind-maintain`  
+- 整理当前专题笔记 → `topmind-organize`  
+- 存新材料 → `topmind-capture`  
+- 出稿 → `topmind-write`  
+- 沉淀「我的情况」/ 周期反思 → `topmind-memory`  
+- 发推 / 微信读书 → connectors  
+
+## When to Invoke
+
+```text
+跑一遍 loop                 → topics + inbox + archive
+loop 一下 topics|inbox|archive
+loop 一下 {类别名}          → 该大类专题
+整体体检 / 巡检 / 复盘      → 全跑
+继续 loop / 从断点继续      → 读 .topmind/loop cursor
+```
+
+## Three Pieces
+
+1. **本 skill** — 规约  
+2. **Agent host** — 执行与语义判断（无第二套 LLM 配置）  
+3. **`.topmind/loop/*.md`** — 进度真账  
+
+Scopes、walk、guardrails 细节：[`references/scopes-and-walk.md`](references/scopes-and-walk.md)。  
+状态文件格式与 resume：[`references/state-file.md`](references/state-file.md)。  
+设计取舍：[`DESIGN.md`](DESIGN.md)。
+
+## Minimal Workflow
+
+1. 解析 scope（默认全跑）  
+2. 读或创建 `.topmind/loop/{scope}.md`（缺失则首次运行，不报错）  
+3. 从 `cursor` 起逐项：Read → Decide → Apply/Preserve/Escalate → Record  
+4. 更新 `last_run` / `done/total` / `cursor` / Receipts  
+
+## What Loop Does NOT Do
+
+- 不写交付正文（write）  
+- 不改专题目标/记忆（memory）  
+- 不 capture 新材料  
+- 不重复 maintain 的确定性检查（可调用其结果作证据，再加语义层）  
+- 不擅自改类别名、不自动升专题  
+- **不**为「补知识结构」自动写 topic.md / 建 INDEX.md / 建实体目录  
+
+材料多而首页空时：只在日志/回执**建议** organize 或 memory（见 scopes-and-walk），不代写。
+
+**Drift 信号**（详见 scopes-and-walk）：`YYYY-类型-项目名` · `project_type:` · outline/setting/style 默认锚点 · 顶层 projects/references/sources/library · 废弃命令 `create-project` / `inspect-project` 等。
+
+## Capability Degradation
+
+见 [`../shared/capability-degradation.md`](../shared/capability-degradation.md)。常用：`workspace-read.*` · `workspace-transform.*` · `workspace-maintain.*`；无 UTR 则 host 文件遍历 + 同样回执语义。
+
+## Composite Trigger
+
+用户面仍经 `topmind` router。Router Action Map 直达本 skill，不经 maintain 中转。
+
+## 保存设置
+
+- **自动保存 (auto)**：直接写入并返回路径回执（path receipt）
+- **需要审阅 (confirm)**：先进入目标路径/内容审阅入口再保存
+- Host 可编码为 `writeback_mode: auto | confirm`。详见 [`../shared/writeback-receipt.md`](../shared/writeback-receipt.md)。
+
+Loop 写状态文件与可逆修复时同样适用；危险操作先备份。
+