@topmindspace/topmind-skills 4.13.0

package/shared/document-ingest.md

@@ -0,0 +1,117 @@
+# 本地文档与统一捕获
+
+> Desktop：统一捕获 + 知识加工管道。网页分层见 [`long-url-capture.md`](./long-url-capture.md)。
+
+## 心智模型
+
+```text
+笔记 / 链接 / 剪贴板 / 文档
+         ↓
+   智能分流
+    ├─ 文本·URL  → Inbox 笔记
+    ├─ 本地路径  → 管道批次（路径引用，不预拷贝）
+    │                 ├─ confirm 关（默认）→ 自动入处理队列
+    │                 └─ confirm 开       → 待确认列表 → 入队
+    │                        ↓
+    │                 转 Markdown → Inbox / 专题
+    └─ 复合     → 两者都做
+```
+
+| 入口 | 适合 |
+|------|------|
+| **⌘N** | 应用内速记、贴链接 |
+| **⌘⇧N** | 全局便签（任意 App 上浮出） |
+| **拖入窗口** | 路径进入加工管道（默认自动入队） |
+| **侧栏「知识加工」** | 看队列、批处理、本机工具 |
+
+**确认策略**（设置 → 知识加工 →「转换前确认」）：
+
+- **关闭（默认）**：与历史一致，拖入/导入后进入处理队列并转换  
+- **开启**：先显示待转换列表，可剔除/改选后再一键确认  
+
+剪贴板文件 = **路径引用**进管道，不是把原件再复制一份到工作区（除非开启「保留原件」归档）。
+
+## 剪贴板
+
+| 内容 | 行为 |
+|------|------|
+| 纯文本 / 链接 | 进捕获正文；URL 可抓取 |
+| HTML | 作摘录 |
+| 资源管理器 / Finder 复制的文件 | 入加工管道 |
+| 粘贴 FileList | 优先 `getPathForFile` |
+
+Windows 以捕获窗粘贴与路径文本为主；路径须真实存在。
+
+## 全局便签
+
+轻量独立窗（可置顶）· 设置 → 通用 → **统一捕获**：`float`（默认）| `overlay`。
+
+## 落点
+
+默认 **Inbox**。转换后 frontmatter 示例：
+
+```yaml
+source_type: external-capture
+source: original.pptx
+ingest_kind: pptx
+ingest_converter: anydoc@0.1.8 | markitdown@… | pptx-ooxml
+```
+
+失败时原件导入 + 说明笔记；可选原件进 `99-归档/ingest-originals/`。
+
+相关：网页剪藏分层见 [`long-url-capture.md`](./long-url-capture.md)；能力勾选见 [`../../docs/capture-clip-matrix.md`](../../docs/capture-clip-matrix.md)。
+
+## 格式与本机工具
+
+| 能力 | 说明 |
+|------|------|
+| **默认：anydoc** | [anydoc](https://github.com/firecrawl/anydoc)：Word `.doc/.docx/.docm` · PPT 家族 · Excel `.xls/.xlsx/.xlsm/.xlsb` · ODF `.odt/.ods/.odp` · `.rtf` · `.epub` · `.csv` · 文本 PDF。无需 Python。加密 / 扫描件 / 不支持格式 → **具名错误**（非空笔记） |
+| **内置 JS** | md/txt 直通 · html-to-markdown · mammoth（docx）· unpdf（PDF 文本）· xlsx/csv · pptx-ooxml · mailparser（eml） |
+| **可选增强** | [markitdown](https://github.com/microsoft/markitdown)`[all]` · [pandoc](https://pandoc.org/) |
+| **不走 anydoc** | HTML · `.eml` · markdown/text 直通 |
+| **不做** | 扫描件 OCR（会提示 unsupported / 文本过少） |
+| **单文件上限** | 默认 **80MB**（可在设置 → 知识加工调到 200MB）。含图 PPT 常超 25MB；超限时**原件仍导入**，不自动转 MD |
+
+设置 → 知识加工 → **默认转换器**：`自动（anydoc 优先）` / anydoc / markitdown / pandoc / 仅内置。首选缺失或失败时**回退**下一档，不硬失败。
+
+### 安装与检测
+
+| 工具 | 推荐 | 升级 |
+|------|------|------|
+| **anydoc（默认）** | 设置里点「安装到应用」（写入用户数据 sidecar），或 `npm install -g @firecrawl/anydoc` | **不必重打包 Desktop**。sidecar / PATH 可热升级；asar 内应用代码、Electron、内置 JS 转换器仍需新版 Desktop |
+| **markitdown** | 务必 `[all]`：Windows `py -3 -m pip install "markitdown[all]"` · macOS/Linux `pipx install 'markitdown[all]'` | 本机 pip/pipx |
+| **pandoc** | Windows `winget install --id JohnMacFarlane.Pandoc -e` · macOS `brew install pandoc` · Linux `apt/dnf install pandoc` | 本机包管理器 |
+
+装完后：**设置 → 知识加工 → 重新检测**。仍未检出 → 完全退出再开 Desktop。
+
+**检测时机**：首次打开知识加工设置会自动检测一次并**缓存**结果；之后打开设置/Hub **不会**反复扫 PATH，需手动「重新检测」。不静默下载二进制。
+
+### Desktop 如何找到工具
+
+GUI 往往不继承终端 PATH。探测会：
+
+1. **anydoc**：用户数据 `converters/anydoc` sidecar → PATH `anydoc` → 可选 extraResource 捆绑副本（仅兜底）  
+2. 合并 Python `Scripts`、Homebrew、Pandoc 安装目录等  
+3. 查找 `markitdown` / `pandoc` 绝对路径  
+4. markitdown 回退：`py -3 -m` → `python -m` → `python3 -m`  
+5. **探测与转换用同一调用方式**  
+6. Windows：`PYTHONUTF8=1`；`.cmd` 经 `cmd.exe` 正确引号  
+
+仅装基础 markitdown 时，PPTX 会回退内置 `pptx-ooxml` 抽文本。队列会显示具体失败原因（悬停看全文）。
+
+**升级矩阵**
+
+| 组件 | 热升级（不必重装 Desktop） | 必须重打包 / 重装 Desktop |
+|------|---------------------------|---------------------------|
+| anydoc sidecar / PATH CLI | ✅ 设置「升级 anydoc」或 `npm install -g @firecrawl/anydoc` | |
+| markitdown / pandoc（本机） | ✅ 本机包管理器 | |
+| 内置 JS（mammoth / unpdf / html-to-markdown / …） | | ✅ asar 内代码 |
+| Electron / 应用壳 | | ✅ |
+
+## Agent（topmind-capture）
+
+1. 文本/URL → 常规 capture  
+2. 本地路径 → 转 MD 或请用户用 Desktop 知识加工  
+3. frontmatter + 路径回执；不自动 organize  
+
+触发：记一下 · 导入文档 · 粘贴文件 · 转 md · 快速笔记。

package/shared/host-loading.md

@@ -0,0 +1,140 @@
+# Host Loading & Progressive Disclosure
+
+> 给 **Agent Host / 安装器** 的加载契约。人类安装见 [`../INSTALL.md`](../INSTALL.md)。  
+> 对齐 [Agent Skills Open Standard](https://agentskills.io/specification) 三级披露。
+
+## 三级加载（必须遵守）
+
+| 级 | 何时 | 加载什么 | 体量目标 |
+|----|------|----------|----------|
+| **1 Discovery** | Session 启动 / skill 列表 | 每个 skill 的 `name` + `description` only | ~50–100 tokens/skill |
+| **2 Activation** | 匹配到任务 | 完整 `SKILL.md` body | < 5k tokens 推荐 |
+| **3 Resources** | 步骤需要时 | `shared/*.md` · `references/*` · 可选 scripts | 按需 |
+
+**禁止**：启动时把 10 份 SKILL 全文 + shared 全部塞进 system prompt。
+
+## 组合式 Pack 如何被 Host 理解
+
+topmind 是 **multi-skill pack**（1 router + 6 action + 2 connector + optional ledger），不是单文件 skill。业界对齐：
+
+| 约定 | topmind 做法 |
+|------|----------------|
+| Agent Skills 单 skill = `{name}/SKILL.md` | 10 个目录各有 `SKILL.md` |
+| 部分 host 对 **zip 根** 找 `SKILL.md` | Release zip 根额外含 **router `SKILL.md`**（= `topmind/SKILL.md`） |
+| Pack 索引 | `skills.md` / `topmind-pack.json`（人类 + 机器） |
+| 共享资源 | `shared/` 与 skill 目录**同级** |
+
+```text
+topmind-skills-<ver>/          ← Release zip 顶层
+├── SKILL.md                   ← pack 根入口（router；zip 单 skill 加载器用）
+├── skills.md · topmind-pack.json
+├── topmind/SKILL.md           ← 日常入口（完整安装后的 discovery 目标）
+├── topmind-capture/ …         ← 子 skill
+├── shared/                    ← 跨 skill 资源
+└── …
+```
+
+### 安装形状（正确）
+
+```text
+{host-skills-root}/
+├── topmind/
+│   └── SKILL.md
+├── topmind-capture/
+│   └── SKILL.md
+├── …（其余 8 个，含可选 weread / x / ledger）
+├── shared/                 ← 与 skill 同级！相对链接 ../shared/ 才能解析
+│   ├── capability-degradation.md
+│   ├── project-model-brief.md
+│   ├── output-language.md
+│   ├── host-loading.md
+│   └── …
+└── topmind-pack.json       ← 推荐保留
+```
+
+**不要**只把 zip 解压成一个目录当「单 skill」却不拆子目录——除非 host 明确只支持单 `SKILL.md`（此时用根 `SKILL.md` router 即可跑通核心路由）。
+
+### 错误形状
+
+- 只拷了 10 个目录、**没有** `shared/` → 渐进链接 404  
+- 把 monorepo 整仓当 skill 根 → host 扫到无关目录  
+- 只装 `topmind` 却期望 weread/x 触发 → connector 未装  
+- Host 报 `SKILL.md not found`：请用 `topmind-skills-*.zip`（含根 `SKILL.md`），或装到 `{skillsRoot}/topmind/SKILL.md`  
+
+
+## 两套安装器
+
+| 工具 | 是否带 shared/ | 适用 |
+|------|----------------|------|
+| `npx skills add topmindspace/topmind-skills -g` | **否**（仅 SKILL 目录） | 快速试用；装后需补 shared |
+| `node bin/install-skills.mjs add …` | **是**（pack-aware） | **推荐生产** |
+
+补 shared：
+
+```bash
+# pack-aware 重装
+node bin/install-skills.mjs add topmindspace/topmind-skills -g
+
+# 或手动
+cp -R skills/shared ~/.agents/skills/shared
+```
+
+## Router vs 子 skill（Host 路由策略）
+
+| 场景 | 应激活 |
+|------|--------|
+| 单一清晰动词（记一下 / 写一稿 / doctor） | 对应 `topmind-*` 子 skill |
+| 多意图 / 模糊 / 只说「topmind」 | `topmind` router |
+| Host **只装了** topmind 一个 skill | router 内嵌 Action Map 完成全部语义 |
+| 10 个全装 | description 消歧；router **不抢** 已匹配的子 skill |
+
+实现提示：discovery 阶段只比 `description` 文本相似度 / 关键词；**不要**用 triggers 数组作为唯一标准（triggers 是 topmind 扩展，开放标准不要求）。
+
+## description 写作规范（本 pack 已遵循）
+
+1. **What** — 做什么（含 topmind / category·topic 心智）  
+2. **Use when** — 用户真实中英短语  
+3. **Do NOT use** — 负向边界（降误触发）  
+4. ≤ **1024** 字符（Agent Skills 硬限）  
+5. Router 不得写「any knowledge task」一类过宽句，以免淹没子 skill  
+
+## 工作区前提（Host 须满足）
+
+- 用户数据在 **workspace root**（含 `{NN-Name}/`），不是 engine 仓  
+- Skills **不**写 engine 代码  
+- 可选 UTR：有则加速，无则 Host 文件工具（见 capability-degradation）  
+- 类别解析语义：`list-categories` 或扫盘 + `topmind.yaml` v4  
+
+## Desktop 内置
+
+topmind Desktop 从 engine `skills/` 加载同一 pack（`skills-runtime.mjs`），默认 **skill-first**：
+
+- Discovery 注入 system prompt  
+- `list_skills` / `load_skill` / `load_skill_resource`  
+- 设置 → Skills：总开关 · 清单勾选 · 扩展目录 · 安装回执；AI 面板可钉选  
+
+**扩展 roots 合并顺序**：`ai.extraSkillsRoots`（设置）→ 已同步的配置缓存 → 环境变量 `topmind_SKILLS_EXTRA`（`:` / Windows `;`）。同名 skill 以后加载的 external 覆盖 bundled。
+
+```bash
+export topmind_SKILLS_EXTRA="$HOME/my-extra-skills:$HOME/other-skills"
+```
+
+| UI 动作 | 行为 |
+|---------|------|
+| 添加目录 | 路径写入 `extraSkillsRoots`（不复制；确认框展示 version / skill 数） |
+| 安装到本地 | 拷贝到 `{desktopHome}/skills-extra/` + `.topmind-skills-extra-install.json` 回执；同 id 重装前移入 `skills-extra/.trash/` |
+| 列表移除 | 只改设置，不删磁盘 |
+
+**够用边界**：CLI 装到 Claude/Codex 见 [`../INSTALL.md`](../INSTALL.md)；Desktop 管理「本机 AI 用的」扩展 skills，不必与 host 全局目录强制统一。
+
+## 验收清单
+
+```bash
+# 每个 skill 可被独立打开
+test -f ~/.agents/skills/topmind/SKILL.md
+test -f ~/.agents/skills/topmind-capture/SKILL.md
+# shared 相对链接可解析
+test -f ~/.agents/skills/shared/project-model-brief.md
+# pack 契约
+test -f ~/.agents/skills/topmind-pack.json   # 若用 pack-aware 安装
+```

package/shared/long-url-capture.md

@@ -0,0 +1,60 @@
+# 长 URL / 网页抓取约定
+
+> Skills（agent host）与 Desktop `workspace.fetchUrl` 对齐。抓取是加速器，**文件系统落盘**仍是真源。
+
+## 目标
+
+把网页变成可审阅的 Markdown 笔记（`source_type: external-capture`），不假装「已完整镜像整站」。
+
+## 分层策略
+
+```text
+L1  静态 HTTP fetch + Readability / 启发式     ← 默认
+L2  Desktop 增强渲染（隐藏 Chromium offscreen） ← SPA 空壳 / 「增强渲染」
+L3  用户粘贴 / 浏览器复制                         ← 永远可用
+L3+ 浏览器扩展 → Bridge 和/或 工作区直写          ← 推荐日常剪藏
+```
+
+| 层 | 入口 | 说明 |
+|----|------|------|
+| L1 | `fetchUrl({ url })` | `@mozilla/readability` + `html-to-markdown`；无第二窗口 |
+| L2 | `fetchUrl({ url, render: true })` | `fetch-render.mjs` + ephemeral 窗（不占 Dock） |
+| L3 | 手动 | 失败回退 |
+| L3+ | Extension | 页内 Readability + **预览 / 选区 / 高亮 / 模板 / 落点**；**Bridge**（高质量 MD + 图片本地化 + destinations）或 **工作区目录**（FS Access，无 Desktop）。见 ADR · `browser-extension/` · `docs/capture-clip-matrix.md` |
+
+**复用原则**：扩展负责活 DOM 正文与高亮；Bridge 与工作区直写共用 Desktop `html-to-markdown` 与同一 frontmatter 规约。Bridge 另走落点 API 与写闸；工作区直写是用户手势确认的 companion 路径。落点：Inbox / 类别 / 专题（Bridge 在线时 popup 可选）。
+
+Agent host 无 Electron 时停在 L1/L3；扩展 **不强制** Desktop 在线（可配置工作区直写）。
+
+## 长度与截断
+
+| 模式 | 上限 |
+|------|------|
+| 默认 | 40k 字符 |
+| 完整抓取 | 200k 字符 |
+
+**必须**在 UI 或 frontmatter 标明：截断、约字数、提取方法、清洗后 URL。用户不可见截断 = 产品缺陷。
+
+## Frontmatter 建议
+
+```yaml
+source_type: external-capture
+source: https://example.com/article
+captured_at: 2026-07-13T12:00:00+08:00
+fetch_method: readability   # readability | heuristic | render | selection | manual
+fetch_truncated: false
+word_count: 1200
+```
+
+## Desktop UX
+
+- QuickCapture：截断 → 完整抓取；SPA → 增强渲染；保存后打开落盘路径  
+- Inbox：按 `source_type` 筛选「网页/摘录」  
+- AI `fetch_url` 支持 `maxLen` + `render`  
+
+## 不要做的事
+
+- 不把整页 HTML 当笔记正文  
+- 不静默丢弃后半篇  
+- 不把抓取失败写成「已成功 capture」  
+- 不用常驻第二 BrowserWindow 占 Dock（仅 ephemeral 隐藏窗）  

package/shared/output-language.md

@@ -0,0 +1,32 @@
+# Output language（模型输出语言）
+
+> Skills 正文可以只有一种语言（本 pack 基础版为 zh-CN）。**输出语言 ≠ skill 正文语言。**
+
+两条轨道（解析见 `lib/ai-output-locale.mjs`）：
+
+```text
+文档 AI（改写打开的笔记 / Agent 写入正文）
+  1. 用户本轮明确要求的语言
+  2. 正在处理的原文（选区优先，否则整份材料；忽略代码围栏 / URL）
+  3. 工作区 locale（topmind.yaml workspace.locale / locale，再回退中文）
+  UI 语言不是这一档。
+
+产品 AI（建议条 · AI 待办 · memory_organize / topic_classify）
+  1. 用户本轮明确要求的语言
+  2. 当前宿主 UI 语言（Desktop settings.ui.locale，或 Obsidian localeOverride / 应用语言；auto 不算）
+  3. 工作区 locale
+  Desktop 与 Obsidian 是交替宿主，不叠成一条链。
+```
+
+## 不要
+
+- 不要因为本 skill / 系统提示是中文（或英文）就用那种语言写用户正文
+- 不要在用户没要求时，把中文笔记改写成英文（或反过来）——文档 AI 不跟 UI
+- 不要把 Desktop 与 Obsidian 的 UI 语言叠成一条链
+
+## 要
+
+- 用户说了目标语言 → 两轨道都遵从，即使原文/UI 是另一种语言
+- 改写 / 总结 / 续写打开的笔记 → 跟随原文
+- 建议条标题/摘要、待办抽取、记忆整理 → 跟随当前宿主 UI（非 auto）
+- 没有原文、也没有语言要求（例如空工作区上的「我的情况」模板）→ 跟随工作区 locale

package/shared/project-model-brief.md

@@ -0,0 +1,132 @@
+# Project Model Brief（Skills 共享摘要）
+
+> 完整真源：引擎根 `PROJECT-MODEL.md`。本文件只给 skill 运行时最小约定，避免 9 份 SKILL 全文复制。  
+> 代码解析：`lib/workspace-model.mjs` 等（UTR / Desktop；Skills 用同一语义）。  
+> 写回：`auto | confirm` only；提升/记忆类**建议须用户确认**（见 `docs/ARCHITECTURE-RESET.md`）。
+
+## 心智（用户词 ≤5 → 系统）
+
+```text
+记一下            默认 append 动态周期本；低信心 → Inbox
+动态              stream packing（默认 weekly）+ loose-stream；yearDir: true（按年分组）
+专题              {类别}/{YYYY-主题}/
+我的情况          memory/profile.md（global；完成/过期确认后归档到 ## 历史记录）
+交付            role:delivery（常 88-交付）
+```
+
+```text
+类别（Category）  {NN-Name}/     文件系统自发现
+专题（Topic）     {类别}/{YYYY-主题}/
+周期本            YYYY-Www.md / YYYY-MM-DD.md（stream.packing）；yearDir: true → {YYYY}/ 周期本
+对象              topic.md · *.md · images/
+交付              role:delivery 扁平文件
+安全层            role:system
+```
+
+默认模板 **`stream`**：Inbox · 动态 · 专题 · 交付 · 归档。4 种 Profile：stream / balanced / research / periodic。
+
+## 6 条核心规约（不可破 · 见 PROJECT-MODEL.md §3）
+
+1. **大类不重叠** — 同一主题只落一个类别  
+2. **专题自然涌现** — 默认不建专题；反复出现时**建议**升专题（勿对用户说「涌现」）  
+3. **动态类** — loose-stream / flat-default：默认周期本或平铺，不强建专题  
+4. **兜底清理** — `catchAll: true` 约 30 天回顾  
+5. **参考资料** — `referenceOnly: true` 只放反复引用素材  
+6. **类别命名稳定** — 改名走 migration  
+
+## stream / memory 配置（v4 contract）
+
+读 `topmind.yaml`（contract_version 4）：
+
+```yaml
+stream:
+  packing: weekly      # atom | daily | weekly | monthly
+  append_heading: day  # day | none
+  year_dir: true       # true | false（默认 true；按年分组）
+
+memory:
+  dir: memory
+  layers:
+    global:   { file: profile.md, update: on-suggest }
+    periodic: { dir: periodic, cadence: weekly, style: brief }  # 反思非摘要
+    topics:   { dir: topics, auto_create: false }
+  promotion: { enabled: true, min_occurrences: 2, require_confirm: true }
+```
+
+- packing: `atom` | `daily` | `weekly` | `monthly`  
+- 记一下 → loose-stream 且 packing≠atom → **append 当前周期本**  
+- 我的情况 → `memory.append-profile`；周期反思 → `memory/periodic/{YYYY}/`；**开专题** → 内容大类 `{YYYY-主题}/`（非默认 memory/topics）  
+- **输出语言**：文档 AI（改写笔记 / Agent 写入）= 用户本轮要求 → 原文 → `workspace.locale`；产品 AI（建议条 / 待办 / memory_organize）= 用户本轮要求 → 当前宿主 UI（`auto` 不算）→ 工作区 locale。见 [`output-language.md`](./output-language.md)。
+
+
+## 命名
+
+- 专题目录：`YYYY-主题`（kebab-case）  
+- **不用** `YYYY-类型-项目名`、`project_type`  
+- 类型由物理类别位置表达；笔记 frontmatter 用 `category`（目录名）+ `topic`  
+
+## 专题形状
+
+```text
+{类别}/{YYYY-主题}/
+├── topic.md     # 可选；缺失不得报错
+├── *.md           # 笔记在专题根
+└── images/        # 可选
+```
+
+**不要默认创建**：`outline.md` / `setting.md` / `style.md`、专题内 `outputs/` / `notes/`、`INDEX.md` 硬索引、`entities/` 默认树、平行 `raw/`/`wiki/` 目录。
+
+## 复利纪律（行为，不改结构）
+
+导航靠**类别+专题树 + 搜索 + 可选 topic.md**，不维护硬索引。
+
+| 动作 | 纪律 |
+|------|------|
+| organize | 整理/总结默认落盘专题根笔记（按 writeback）；不只回话；可建议 memory 候选，不自动写 topic.md |
+| write | 有 `topic.md` 先读再写；无则不强制创建 |
+| memory | 仅用户明确沉淀；禁止 capture 自动改 memory/topics/ |
+| capture | 只写材料笔记；不改 topic.md、不自动链式 |
+| loop | 材料多而首页空时只**建议** organize/memory，不代写记忆/不建 INDEX |
+
+## source_type
+
+| 值 | 含义 |
+|----|------|
+| `user-original` | 用户原文，保字句 |
+| `external-capture` | URL/文件/外部源 |
+| `ai-derived` | AI 总结/草稿 |
+
+## 配置与解析（必读）
+
+1. 工作区根由 host 提供，不硬编码绝对路径  
+2. 读 `{workspace}/topmind.yaml`（contract_version **4**）：
+   - `workspace.template` · `workspace.category_separator` · `presentation.views` · `ingest.connectors`
+   - **`categories.extensions`**：用户新增一级类的 name / role / specialBehavior  
+   - **`categories.overrides`**：对已有 slot 的 role / hidden 覆盖  
+3. **扫盘**所有 `^\d{2}[ -].+` 目录 = 活跃类别（FS 真源）  
+4. 角色合并：overrides > extensions > `templates/{template}.json` > 默认 `deep-work`  
+5. 有 UTR 时优先：`workspace-read.list-categories`（返回完整 CategoryDescriptor）  
+6. **禁止**把写死的名字表当合法类别白名单；自定义 `11-健康/` 合法  
+
+### CategoryDescriptor（最小字段）
+
+```text
+slot · name · directory · role · specialBehavior? · catchAll? · referenceOnly?
+source: fs+config | fs+template | fs-only | …
+```
+
+### 智能体入口协议
+
+```text
+任何 capture / organize / write / maintain / loop 开始前：
+  1) 解析类别表（list-categories 或 扫盘 + 读 config）
+  2) 跳过 hidden；按 role / specialBehavior 路由
+  3) 再写回
+新建个性化大类时：
+  mkdir {NN}{sep}{名称}/  且  写入 categoryExtensions[NN]
+重命名大类时（规约 6）：
+  必须 rename 目录 + 更新树内 frontmatter.category + config
+  禁止 silent 改名；loop 不得改类别名
+可选加速（非真源）：
+  .topmind/workspace-map.json — 可删，随时 rebuild
+```

package/shared/trigger-disambiguation.md

@@ -0,0 +1,58 @@
+# Trigger Disambiguation（路由消歧真源）
+
+> Router（`topmind`）与各子 skill 的「When NOT」必须与本表一致。  
+> 子 skill **不得**自动链式 dispatch 下一 skill；「下一步」仅用户面建议。
+
+## 碰撞词裁决
+
+| 用户说 | 撞到的 skills | 裁决 |
+|--------|--------------|------|
+| 总结要点 | organize vs memory | 默认 → `topmind-organize`。仅「更新我的情况 / 加到专题记忆 / 沉淀到记忆」→ memory |
+| 沉淀 | capture vs memory | 默认 → `topmind-capture`。仅「沉淀成稳定结论 / 更新我的情况」→ memory |
+| 体检 / 检查 | maintain vs loop | 「快速体检 / 体检 / 检查 / doctor」→ maintain。「整体体检 / 全面检查 / 巡检 / audit / review」→ loop |
+| 审计 / audit | maintain vs loop | 默认 → loop。maintain 用 doctor / 诊断 / 快速体检 |
+| 整理 | organize | 「整理 inbox」→ organize + `plan-inbox-routing`。其它 → organize |
+| 复盘 | organize vs loop | 「复盘」→ loop。「复盘要点成笔记」→ organize |
+| 归档 | capture vs maintain | 「归档材料」→ capture。「归档专题 / archive topic」→ maintain |
+| 笔记 / note | capture vs write | 未限定 → capture。「写作 / 起草 / 续写」→ write |
+| 记账 / 记一笔 / 花了 / 存入 | ledger vs capture | 「记账 / 记一笔 / 花了 / 存入 / 查看账单 / 账户余额」→ `topmind-ledger`（记忆平面账本）。「记一下」仍 → capture |
+| 公众号 / 微信排版 | wechat vs write | 「公众号 / 微信排版 / 公众号定稿 / 发公众号」→ `topmind-wechat`。通用「写一篇」仍 → `topmind-write` |
+
+**原则**：动作动词定 action；修饰词定 confidence。无法判定 → capture（先存后整）。
+
+## 写回边界（与复利纪律对齐）
+
+| 动作 | 默认写什么 | 禁止 |
+|------|------------|------|
+| capture | 材料笔记 | 改 `topic.md`；自动 organize/memory |
+| organize | 专题根综合/结构笔记（留痕） | 自动写稳定记忆；建 `INDEX.md` / entities 树 |
+| memory | 仅 confirmed stable → `memory/profile.md` 或 `memory/periodic/`（用户明说才写 `memory/topics/`） | 因 capture/整理顺手刷写；把 `topic.md` 当记忆默认落点 |
+| write | 稿件 / delivery | 为「补结构」空建 `topic.md` |
+| loop | 状态 / 可逆修复 | 代写记忆；建硬索引 |
+| ledger | `{memory.dir}/ledgers/` 追加一行 | 改 `topic.md`；发明 ClassFund/Giggs/Mom；当第六用户概念 |
+
+## 多意图顺序
+
+| 意图组合 | 裁决 |
+|---------|------|
+| capture + organize | 先 capture，回执建议 organize（不自动链式） |
+| capture + memory | 先 capture，回执建议 memory（须用户再确认才写 profile / periodic） |
+| organize + write | 先 organize（落盘综合），再 write |
+| organize + memory | 先 organize 候选与综合笔记，**用户接受建议后再** memory |
+| write + memory | 先 write，回执建议 memory |
+| 整理 inbox | organize + plan-inbox-routing（不是 maintain/loop） |
+| 清理工作区 | maintain |
+
+三个以上意图：拆成顺序步骤，每步回执。
+
+## Action unsure
+
+- 记账 / 记一笔 / 花了 / 存入 / 查看账单 / 账户余额 → ledger  
+- 内容动词（写/存/记一下）且无修复/巡检 → capture  
+- 修复 / 清理 / 重建 → maintain  
+- 巡检 / 整体 / 断点 → loop  
+- 整理 / 分析 / 总结 → organize  
+- 写 / 发布 / 出稿 → write  
+- 记忆 / 更新我的情况 / 周期反思 → memory  
+- 仅类别名 → capture 到该类别根  
+- 全不像 → capture 到 Inbox（buffer）  

package/shared/writeback-receipt.md

@@ -0,0 +1,73 @@
+# Writeback & Receipt（Skills 共享）
+
+> 完整契约：`TOOLS.md` §Writeback Contract。耐久主写统一 `lib/writeback-engine`（Desktop WorkspaceService / UTR / AI → Kernel 写闸 **Done**，见 `docs/ARCHITECTURE-RESET.md` §2.2）。  
+> **2026-09-17 授权模型**：工作区围栏绝对；围栏内 agent 会话即授权；`locked` = 重要内容需**任务级首写快照**，不是 AI 禁区。
+
+## 保存设置
+
+```yaml
+writeback:
+  mode: auto | confirm   # 仅此两档；无 batch mode
+```
+
+| 模式 | 行为 |
+|------|------|
+| `auto` | 内容直接写入；locked 任务级首写快照；可恢复删/归档允许；archive 迁入现场 **role:system** 目录当新家；普通开放笔记删除无 trash |
+| `confirm`（**分级**） | 内容新建/更新/编辑 **直接落盘**；仅 **删除/归档** 进入待确认 |
+
+用户话术：
+
+- **自动保存** → `auto`  
+- **删除/归档前问我** → `confirm`（分级：编辑直接落，删/归档才问）
+
+**主动建议 ≠ 自动写**：系统可默认生成建议卡片；执行高影响写入仍须确认 + protection。  
+
+**locked 语义（2026-09-17c）**：`auto` 下 AI **可以**写 locked —— 本任务对该文件的**首次**覆盖做一次快照+YAML 回执，同任务后续编辑原地更新。**删除/归档 locked 也可在 auto 进行**（走 trash/归档目的地，可恢复+回执）；**永久删除** locked/core 仍须用户。`confirm` 为分级：内容编辑直接落盘；删/归档待确认。用户写 locked 始终可以（同样任务级快照）。
+
+## 回执最小字段
+
+```text
+已收进/已更新：大类 → 专题（或单篇 / Inbox）
+位置：relative/path.md
+操作：create | update | delete | archive | restore
+保存模式：auto | confirm
+判断：信心与理由（如有）
+下一步：继续写 / 整理 / 写入专题记忆 / 手动移动
+```
+
+写入必须返回 **target path + affected files**（UTR 时见 WritebackEvidence）。
+
+**回执定义（防冗余）**：
+
+| 层 | 何时有 | 载体 |
+|----|--------|------|
+| **工具证据**（evidence） | 每次写 | 返回值：targetPath · wroteFiles · backupPath? · receiptPath? |
+| **YAML 回执**（receipt） | 仅高影响恢复轨迹 | `99-归档/receipts/*.yaml`（locked 首写快照 · 可恢复 delete/archive） |
+| **ops journal** | 每次工具/维护 | Desktop `logs/ops.jsonl`（审计，不是第二套 receipts） |
+
+**`receiptPath` 仅在存在真实 YAML 回执时非空**——不回退为 `backupPath` 别名。撤销/恢复请看 `backupPath`（或 trash 路径）。
+
+## 可逆性（高影响 only）
+
+- 锁定 / 核心笔记 **delete** → 移入现场 system 目录的 `backups/trash` + 回执（**AI auto 允许**）；普通开放笔记删除无 trash；`permanent` 则无副本，**AI 不可对 locked/core 永久删**  
+- **archive** → 迁入现场 system 目录当**新家**（非备份）；YAML 回执仅锁定/核心；AI auto 可归档 locked（可恢复）  
+- **locked** 既有文件覆盖 → **任务内一次**旋转快照 + 回执（多步编辑不重复备份）  
+- 常规 **open** 更新 → 不造备份/回执（不伪造路径）；证据仍含 target path + affected files  
+- AI + locked：`auto` 允许内容编辑（任务级快照）与可恢复删/归档；`confirm` 待确认；永久删仅用户
+
+## 错误处理（共享）
+
+写入失败时不得静默丢弃数据。按以下优先级处理：
+
+| 错误类型 | 处理 |
+|---------|------|
+| 磁盘满 / 权限不足 | 报错 + 已备回复制位置；不静默丢数据 |
+| 路径过长 / 非法字符 | 提示用户缩短专题名或使用合法字符 |
+| 工作区外路径 | 拒绝（围栏不可授权绕过） |
+| 工作区无 `topmind.yaml` | 按默认契约解释 + 回执标注「默认契约」 |
+| UTR 不可用 | 降级为 Host 文件工具（见 `capability-degradation.md`） |
+| 网络抓取失败 | 保留 URL + 摘录；不假装已成功 capture |
+| AI 分析失败 | 诚实报错不写；不生成占位符假装成功 |
+| 源文件不存在（promote） | 报错 + 路径；不静默跳过 |
+| 参数缺失 / 值非法 | 明确报错指出缺失字段或非法值；不猜测默认 |
+| 周期本解析失败 | 回退为新建文件 + 回执标注「新建周期本」 |

package/skills.md

@@ -0,0 +1,39 @@
+# topmind Skills Package Index (包索引)
+
+> [!NOTE]
+> **每日唯一入口**：`topmind` (router)。其余 6 个 action、2 个 optional connector、1 个 optional 记账模块均由 router 调度。  
+> **通用与可移植**：兼容 Claude Code / OpenCode / Codex / Hermes 等 Agent Host。  
+> **版本真源**：`topmind-pack.json`（可执行 `npm run versions` 查看完整版本号）。  
+> 详见权威说明：[Skills README](./README.md)（简体中文） · [English](./README.en.md) · [安装与部署指南 (INSTALL.md)](./INSTALL.md)。
+
+---
+
+## Skill 包清单
+
+| # | Skill 名称 | 模块类型 | 关键触发词 / 场景 | 职责描述 |
+|---|---|---|---|---|
+| 1 | `topmind` | **Router** | `topmind` / 记一下 / 整理 / 模糊多意图 | **主入口 router**：解析用户意图与工作区上下文，自动路由动作与大类 |
+| 2 | `topmind-capture` | Action | 记一下 / capture / 抓取链接 | **捕获动作**：处理速记、网页链接、知识文件加工并安全落盘 |
+| 3 | `topmind-organize` | Action | 整理 / organize / 提炼结构 | **整理动作**：归纳笔记、整理专题、提取证据链与知识留痕 |
+| 4 | `topmind-write` | Action | 写 / 起草 / 润色 / 出稿 | **写作动作**：根据专题与参考资料起草长文、润色及生成 Deliverable |
+| 5 | `topmind-memory` | Action | 记住 / 更新我的情况 / memory | **记忆动作**：维护 `memory/profile.md` 与周期反思（非默认写 `topic.md`） |
+| 6 | `topmind-maintain` | Action | doctor / 诊断 / 清理 | **体检动作**：检查目录健康、孤立文件、配置校验与环境诊断 |
+| 7 | `topmind-loop` | Action | loop / 巡检 / 自动盘点 | **巡检动作**：可恢复的工作区全量语义巡检与盘点 |
+| 8 | `topmind-weread` | Connector | 微信读书 / weread | **微信读书连接器**：同步划线、书评与阅读笔记 |
+| 9 | `topmind-x` | Connector | X / 推特 / twitter | **X (Twitter) 连接器**：归档推特帖子、书签与时间线 |
+| 10 | `topmind-ledger` | Memory（可选） | 记账 / 记一笔 / 花了 / 存入 | **记账**：默认个人账本，用户自建账本/分类，写入 `memory/ledgers/` |
+| 11 | `topmind-wechat` | Write 子技能（可选） | 公众号 / 微信排版 / 定稿 | **公众号创作**：交付包、质量三关、微信内联排版、发布清单（write 族子技能，非并列前台） |
+
+---
+
+## 核心约定与规约
+
+1. **唯一前台入口**：AI Agent 日常激活只需推荐 `topmind`。
+2. **渐进式披露 (Progressive Disclosure)**：Discovery (`name+description`) → Activation (`SKILL.md`) → Deep Procedures (`shared/` / `references/`)。
+3. **文件系统即真源**：不引入独立的数据库或 Agent state 依赖。
+4. **遵从 6 条核心规约**：详见根目录 [`PROJECT-MODEL.md`](../PROJECT-MODEL.md)。
+
+👉 **详细架构、Frontmatter Schema 与安装方法请参阅**：
+- [Skills README](./README.md)（简体中文） · [English](./README.en.md)
+- [多 Host 安装教程 (INSTALL.md)](./INSTALL.md)
+- [根目录架构契约 (SKILL-ARCHITECTURE.md)](../SKILL-ARCHITECTURE.md)