@topmindspace/topmind-handoff 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 0.6.4（2026-10-14）
+
+- 特性支持：记忆仓库新增 `knowledge/` 知识库，放跨环境共享的经验、收藏帖、提示词。普通 Markdown，最多两级目录，是参考资料不是指令，不进信箱、编译、视图和 `authority.md`。
+- 初始化写出 `knowledge/README.md`（目录索引、条目格式、拆分规则、读写时机）和 6 个大类（收藏帖、段子、引流曝光、写作、图片视频、提示词）各一个 `通用.md`。仓库说明加一节 knowledge。
+- 编译升级技能旧模板说明时，只补 `knowledge/` 缺的文件。已有文件、被人改过的说明都不覆盖。
+- 技能新增「knowledge 知识库」一节与触发词：沉淀经验、记个经验、收藏帖子、存提示词。写明与 topmind-capture 的边界：跨环境可复用的进 knowledge，当前创作素材进工作区。
+- 新增 knowledge 测试与路由评测（含 topmind-capture 反例）。
+
 ## 0.6.3（2026-10-13）
 
 - 优化：编译遇到技能自己写过的旧版仓库说明时，换成当前说明。被人改过的说明不覆盖。不改信箱。

package/README.md

@@ -27,11 +27,12 @@ Codex 用 `~/.codex/skills/topmind-handoff`。其他宿主换成它的技能目
 ## 日常说法
 
 - 「做个交接」「做个handoff」「工作交接」：先整合读得到的最新记忆，再把这台的新操作写回。没点名接收或推送时走这一轮。离线有包就只接收；没有仓库先问一次。步骤在 `SKILL.md`。
-- 「初始化 handoff」：空目录写骨架、一份自解释的说明、编译空视图、做一个本地提交。公开仓库会拒绝。
+- 「初始化 handoff」：空目录写骨架、一份自解释的说明、`knowledge/` 知识库骨架、编译空视图、做一个本地提交。公开仓库会拒绝。
 - 「更新云端记忆」：追加本环境的操作，本机编译，确认后和视图放在同一次提交里推送。
 - 「按云端记忆接手」：`--check` 通过后跑 `--startup`。确认后写入本工具，不覆盖已有正文。
 - 「给我一份交接包」：断网也能从本机仓库渲染。
 - 「整理云端记忆」：把事实索引压短，标出未复核和未刷新，并列出待提炼。不改信箱，不自动撤回。
+- 「沉淀经验」「记个经验」「收藏帖子」「存提示词」：写进记忆仓库的 `knowledge/`，普通 Markdown，任何环境直接编辑并推送。它是参考资料，不进编译和视图。格式和拆分规则在仓库的 `knowledge/README.md`。当前创作的素材捕获交给 topmind-capture。
 - 「这台以写作为主」：该场景的直接写入权交给这台。其他环境只能提议。
 
 编译规则只在 [`references/compile.md`](references/compile.md)。
@@ -60,4 +61,4 @@ scripts/compile_memory.py
 
 ## 版本
 
-当前技能版本 `0.6.3`，交接包格式 `2`。更新记录见 `CHANGELOG.md`。
+当前技能版本 `0.6.4`，交接包格式 `2`。更新记录见 `CHANGELOG.md`。

package/SKILL.md

@@ -8,23 +8,23 @@ description: >-
   Use when 做个handoff、做个交接、工作交接、Handoff、handoff、交接、记忆同步、更新云端记忆、按云端记忆接手、给我一份交接包、整理云端记忆、这台以写作为主、
   这台以某场景为主、初始化 handoff、配置云端交接、交接手册、导出记忆、打包记忆、
   跨工具记忆同步、换工具、换AI、迁移记忆、带到新工具、多端同步、帮我做 handoff、
-  帮我接收最新 handoff、只本地、export handoff、import handoff.
+  帮我接收最新 handoff、只本地、export handoff、import handoff、沉淀经验、记个经验、收藏帖子、存提示词.
   Do NOT use for 日常单条记忆写入（记住这个、更新我的情况 → topmind-memory）、
-  整理笔记（→ topmind-organize）、出稿（→ topmind-write）、与交接无关的技能安装。
+  整理笔记（→ topmind-organize）、当前创作的素材捕获（→ topmind-capture）、出稿（→ topmind-write）、与交接无关的技能安装。
 license: MIT
 compatibility: >-
   Any AI agent with file read/write and Python 3. Local compile needs no network.
   Optional private-git sync uses the user's existing git/gh credential only.
   No SDK. No token stored. The memory repo has no CI and no Release.
 metadata:
-  version: "0.6.3"
+  version: "0.6.4"
   author: TopMindSpace
   homepage: https://github.com/topmindspace/topmind-handoff
-  updated: "2026-10-13"
+  updated: "2026-10-14"
   action_category: organize
   entrypoint: "false"
   tags: handoff, profile, memory-portability, onboarding, privacy
-  triggers: 做个handoff, 做个交接, 工作交接, Handoff, handoff, 交接, 记忆同步, 更新云端记忆, 按云端记忆接手, 给我一份交接包, 整理云端记忆, 这台以写作为主, 这台以某场景为主, 初始化 handoff, 配置云端交接, 交接手册, 导出记忆, 打包记忆, 跨工具记忆同步, 换工具, 换AI, 迁移记忆, 带到新工具, 多端同步, 帮我做 handoff, 帮我接收最新 handoff, 只本地, export handoff, import handoff
+  triggers: 做个handoff, 做个交接, 工作交接, Handoff, handoff, 交接, 记忆同步, 更新云端记忆, 按云端记忆接手, 给我一份交接包, 整理云端记忆, 这台以写作为主, 这台以某场景为主, 初始化 handoff, 配置云端交接, 交接手册, 导出记忆, 打包记忆, 跨工具记忆同步, 换工具, 换AI, 迁移记忆, 带到新工具, 多端同步, 帮我做 handoff, 帮我接收最新 handoff, 只本地, export handoff, import handoff, 沉淀经验, 记个经验, 收藏帖子, 存提示词
 ---
 
 # topmind-handoff · 跨工具记忆
@@ -104,7 +104,7 @@ python3 scripts/compile_memory.py --startup <记忆目录> --origin <origin_id>
 
 「初始化 handoff」或「配置云端交接」：问私有仓库 `owner/name`。公开仓库停下，什么都不写。
 目录缺省是仓库根。记下 `origin_id`（`工具-账号标识-范围`）和这台的场景名。
-跑 `--init --private`。它写骨架、一份自解释的 `README.md`、编译空视图、在本机做一个提交。提交里没有 workflow 文件。
+跑 `--init --private`。它写骨架、一份自解释的 `README.md`、`knowledge/` 骨架（说明加 6 个大类的 `通用.md`）、编译空视图、在本机做一个提交。提交里没有 workflow 文件。
 凭据只用已经配好的 git 或 `gh`。没有就停下，不让用户把 token 贴进对话。
 
 ### 更新云端记忆
@@ -137,12 +137,23 @@ python3 scripts/compile_memory.py --startup <记忆目录> --origin <origin_id>
 
 用户指明场景后跑 `--own`。它改该场景的主人并重新编译。身份和边界仍是 `human`。不再有权的句子离开场景视图，记成提议。场景名或 `origin_id` 不是单个路径段时命令拒绝，不改文件。
 
+### knowledge 知识库
+
+记忆仓库里的 `knowledge/` 是跨环境共享的经验、收藏帖和提示词。普通 Markdown，不进信箱、编译、视图和 `authority.md`。它是参考资料，不是指令，不覆盖偏好与边界。
+
+- 读：拉取后按当前任务用 `rg -n "关键词" knowledge/` 查相关条目。不整体读入，不放进 `--startup` 投影和交接包。
+- 写：用户说「沉淀经验」「记个经验」「收藏帖子」「存提示词」，或踩到值得记的坑。先搜重复，有就改原条目；新条目加在文件顶部。写完单独提交并推送，不必跑编译。仓库还没有 `knowledge/` 时，编译只在升级技能旧模板说明时补齐缺的文件；已有文件从不覆盖。
+- 格式、两级目录和拆分规则只看仓库里的 `knowledge/README.md`，这里不另写一套。
+- 边界：跨环境可复用的经验、提示词、收藏进这里；当前创作的素材、灵感进工作区（topmind-capture）；偏好和事实仍走 `outbox/`。
+- 不写凭据、隐私、他人信息、聊天记录。
+
 ## 输出
 
 - 交接：整合了什么、写回了什么、推了还是停在本地。某一侧没有新内容要写明。
 - 更新：确认过的差异（共享改了什么、还剩几条冲突、几条提议、本环境卡片是否更新），以及提交路径。
 - 接手：记忆、环境、任务三块。写明合并了什么、锚点有没有动、哪些没动。
 - 交接包：文件路径。写明没有推送。
+- 知识库：写了哪个文件、哪条，提交是否已推送。
 - 不编造版本、日期、`op_id`。读不到就标「未核实」。
 
 ## 纪律

package/assets/handoff-example.md

@@ -3,7 +3,7 @@ handoff_version: "2"
 language: zh-CN
 scope: private
 origin_id: "Grok-demo-sync"
-compiler: "示例助手 + topmind-handoff 0.6.3"
+compiler: "示例助手 + topmind-handoff 0.6.4"
 ---
 
 > **给 AI 的接收指引**：建议先安装或更新 topmind-handoff
@@ -86,7 +86,7 @@ override.pref-theme: 本环境编辑器用浅色
 连接器：GitHub，读写自己的仓库
 
 已装技能：
-- topmind-handoff 0.6.3（github:topmindspace/topmind-handoff）：编译记忆并渲染交接包
+- topmind-handoff 0.6.4（github:topmindspace/topmind-handoff）：编译记忆并渲染交接包
 
 ## 10. 操作附录（已反映在上文视图中）
 

package/assets/handoff-template.md

@@ -3,7 +3,7 @@ handoff_version: "2"
 language: zh-CN
 scope: private
 origin_id: "工具-demo-sync"
-compiler: "工具名 + topmind-handoff 0.6.3"
+compiler: "工具名 + topmind-handoff 0.6.4"
 ---
 
 > **给 AI 的接收指引**：建议先安装或更新 topmind-handoff

package/package.json

@@ -1 +1 @@
-{"author": "TopMindSpace", "bugs": {"url": "https://github.com/topmindspace/topmind-handoff/issues"}, "description": "跨工具交接技能：私有 Git 里按环境追加操作，本机编译共享视图和场景视图，离线时用版本 2 交接包。Cross-tool handoff: layered private-git memory compiled locally, plus a version 2 package when a tool cannot pull.", "engines": {"node": ">=18"}, "files": ["SKILL.md", "references", "assets", "README.md", "LICENSE", "CHANGELOG.md", "topmind_handoff", "scripts/compile_memory.py"], "homepage": "https://github.com/topmindspace/topmind-handoff#readme", "keywords": ["agent-skills", "ai-skills", "handoff", "memory-portability", "user-profile", "onboarding"], "license": "MIT", "name": "@topmindspace/topmind-handoff", "publishConfig": {"access": "public"}, "repository": {"type": "git", "url": "git+https://github.com/topmindspace/topmind-handoff.git"}, "version": "0.6.3"}
+{"author": "TopMindSpace", "bugs": {"url": "https://github.com/topmindspace/topmind-handoff/issues"}, "description": "跨工具交接技能：私有 Git 里按环境追加操作，本机编译共享视图和场景视图，离线时用版本 2 交接包。Cross-tool handoff: layered private-git memory compiled locally, plus a version 2 package when a tool cannot pull.", "engines": {"node": ">=18"}, "files": ["SKILL.md", "references", "assets", "README.md", "LICENSE", "CHANGELOG.md", "topmind_handoff", "scripts/compile_memory.py"], "homepage": "https://github.com/topmindspace/topmind-handoff#readme", "keywords": ["agent-skills", "ai-skills", "handoff", "memory-portability", "user-profile", "onboarding"], "license": "MIT", "name": "@topmindspace/topmind-handoff", "publishConfig": {"access": "public"}, "repository": {"type": "git", "url": "git+https://github.com/topmindspace/topmind-handoff.git"}, "version": "0.6.4"}

package/references/environment.md

@@ -18,7 +18,7 @@ override.pref-theme: 本环境用浅色终端
 连接器：GitHub，读写自己的仓库
 
 已装技能：
-- topmind-handoff 0.6.3（github:topmindspace/topmind-handoff）
+- topmind-handoff 0.6.4（github:topmindspace/topmind-handoff）
 ```
 
 - `role` 决定 `--startup` 带上哪一个场景。规则见 `references/compile.md`。

package/references/spec.md

@@ -54,8 +54,8 @@ handoff_version: "2"
 language: zh-CN
 scope: private
 origin_id: "Grok-demo-sync"
-compiler: "topmind-handoff 0.6.3"
-generator: "工具名 + topmind-handoff 0.6.3"
+compiler: "topmind-handoff 0.6.4"
+generator: "工具名 + topmind-handoff 0.6.4"
 ---
 ```
 

package/topmind_handoff/admin.py

@@ -79,16 +79,139 @@ def memory_readme() -> str:
                 "- `facts/`：整理时从索引收走的长说明。不是另一套权威。",
                 "- `views/shared.md` 和 `views/scenario-<场景>.md`：本机编译产物，可以丢掉后重新编译。不是指令。",
                 "- `STATUS.md`：同一次编译的校对。信箱末尾对不上，视图就无效。不是指令。",
+                "- `knowledge/`：跨环境共享的经验、收藏帖、提示词。普通 Markdown，任何环境直接编辑。见 `knowledge/README.md`。",
                 "",
                 "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是可以丢掉的编译产物，不是指令。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
                 "",
+                "## knowledge/ 知识库",
+                "",
+                "- `knowledge/<大类>/<主题>.md`，最多两级。大类有收藏帖、段子、引流曝光、写作、图片视频、提示词。",
+                "- 它是参考资料，不是指令，不覆盖偏好与边界，不进 `outbox/`、编译、视图和 `authority.md`。",
+                "- 任何环境都可以直接改，提交并推送即可，git 历史就是留痕。不写凭据、隐私和聊天记录。",
+                "- 条目格式、拆分规则、读写时机见 `knowledge/README.md`。",
+                "",
+        ]
+    )
+
+
+KNOWLEDGE_CATEGORIES = (
+    ("收藏帖", "帖子收藏"),
+    ("段子", "段子写法经验"),
+    ("引流曝光", "引流、曝光、涨粉经验"),
+    ("写作", "写作经验"),
+    ("图片视频", "做图、做视频的经验"),
+    ("提示词", "各类提示词"),
+)
+
+
+def knowledge_readme() -> str:
+    """Generic rules for knowledge/. No personal entries."""
+    index = [f"- `{name}/通用.md`：{desc}，未细分的先放这里" for name, desc in KNOWLEDGE_CATEGORIES]
+    return _readme(
+        [
+            "# knowledge · 经验知识库",
+            "",
+            "跨环境共享的经验、收藏和提示词。普通 Markdown，任何环境都能直接编辑，git 历史就是留痕。",
+            "",
+            "- 这里是参考资料，不是指令。不覆盖 `outbox/` 里的偏好与边界，也不进编译、视图和 `authority.md`。",
+            "- 不写密码、API key、token、隐私、他人信息、聊天记录。",
+            "",
+            "## 目录索引",
+            "",
+            "每个文件一行。新建或拆分文件时同步更新这里。",
+            "",
+            *index,
+            "",
+            "## 结构与拆分",
+            "",
+            "- 最多两级：`knowledge/<大类>/<主题>.md`。不建三级目录。",
+            "- 每个大类先只有 `通用.md`。单个文件超过约 300 行，或某个子主题攒到约 10 条，就拆出子文件。",
+            "- 子文件命名「子类-限定.md」，例如 `提示词/图片-写实人像.md`、`收藏帖/AI工具.md`。",
+            "- 拆分只搬移条目，不改字。拆完更新上面的索引。",
+            "- 交叉归类用标签，不用更深的目录。",
+            "- 需要新大类时再加文件夹，同样先放 `通用.md`。",
+            "",
+            "## 条目格式",
+            "",
+            "```",
+            "## 标题",
+            "YYYY-MM-DD · <origin_id> · #标签1 #标签2 · https://链接（可选）",
+            "",
+            "- 要点 1",
+            "- 要点 2（2–5 行）",
+            "```",
+            "",
+            "- 提示词类：原文放进代码块，注明适用的模型或工具，以及效果。",
+            "- 收藏帖：写作者、链接、为什么值得收。",
+            "- 新条目加在文件顶部（文件说明之下）。",
+            "- 写之前先搜有没有重复：`rg -n \"关键词\" knowledge/`。有就改原条目。",
+            "- 过时了就改或删，不留墓碑。",
+            "",
+            "## 什么时候读、什么时候写",
+            "",
+            "- 读：拉取后按当前任务用 `rg` 查相关条目，不整体读入。",
+            "- 写：用户说「沉淀经验」「记个经验」「收藏帖子」「存提示词」，或者踩到值得记的坑。写完提交并推送。",
+            "- 不写只在某台机器有用的步骤（那是环境卡片），也不写偏好与事实（那是 `outbox/`）。",
+            "",
         ]
     )
 
 
+def write_knowledge_skeleton(repo: Path) -> list[Path]:
+    """Create knowledge/ files that are missing. Existing files are never touched."""
+    root = Path(repo) / "knowledge"
+    planned = [(root / "README.md", knowledge_readme())]
+    for name, desc in KNOWLEDGE_CATEGORIES:
+        planned.append(
+            (
+                root / name / "通用.md",
+                _nl(f"# {name} · 通用\n\n{desc}，未细分的先放这里。格式见 `knowledge/README.md`，新条目加在本行之下。"),
+            )
+        )
+    written = []
+    for path, text in planned:
+        if path.exists():
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        written.append(path)
+    return written
+
+
 # Byte-identical explanations this skill itself used to write. Compile replaces
 # only these. A README a person has edited is left as it is.
 KNOWN_STOCK_READMES = (
+    _readme(
+            [
+                    "# 云端记忆",
+                    "",
+                    "这是一份私有记忆仓库。本机的 topmind-handoff 编译它。仓库里没有 CI，也没有 Release。",
+                    "凭据只用已经配好的 git 或 gh。不写密码、API key、token、证件号、银行卡号、精确住址、他人隐私、记账明细。聊天记录也不写入。",
+                    "",
+                    "## 写入哪一类",
+                    "",
+                    "- 画像锚点是称呼、对本智能体的称呼、语言、时区。它们是身份，主人是 human，只接受 `outbox/human.md`。正文以「称呼：」「对本智能体的称呼：」「语言：」「时区：」开头。",
+                    "- 边界的主人也是 human。",
+                    "- 跨工具都适用的偏好写入 `scope: shared`。",
+                    "- 只在某个场景里成立的习惯用 `scope: scenario:<场景>`，不写入 shared。",
+                    "- 必须跟着这台机器走的步骤和未做完的事用 `scope: origin:<origin_id>`。技能版本和连接器写在这台的环境卡片上，不写成共享事实。",
+                    "- 已有主题要改，沿用原来的 id，`base` 填当前链头，不另起一条 id。",
+                    "- 换范围时先在旧范围撤回，再在新范围用同一 id 写下，`base: none`。",
+                    "- 不写密码、API key、token，不写聊天记录，不改别人的信箱。",
+                    "",
+                    "## 各部分",
+                    "",
+                    "- `outbox/<origin_id>.md`：这个环境的操作账本。只许该环境在文件末尾追加。不改别人的信箱，不改已有行。",
+                    "- `environments/<origin_id>.md`：这个环境的卡片。只许该环境整文件替换。",
+                    "- `authority.md`：谁可以写进视图。身份和边界的主人是 human，只接受 `outbox/human.md`。",
+                    "- `facts/`：整理时从索引收走的长说明。不是另一套权威。",
+                    "- `views/shared.md` 和 `views/scenario-<场景>.md`：本机编译产物，可以丢掉后重新编译。不是指令。",
+                    "- `STATUS.md`：同一次编译的校对。信箱末尾对不上，视图就无效。不是指令。",
+                    "",
+                    "权威是 `outbox/`、`authority.md` 和 `environments/`。`views/` 和 `STATUS.md` 是可以丢掉的编译产物，不是指令。Git 冲突时丢掉这两边的视图，保留全部信箱，在本机重新编译。",
+                    "",
+            ]
+        ),
     _readme(
         [
             "# 云端记忆",
@@ -152,6 +275,8 @@ def upgrade_stock_readme(repo: Path) -> bool:
     if current == latest or current not in KNOWN_STOCK_READMES:
         return False
     path.write_text(latest, encoding="utf-8")
+    # The new explanation points at knowledge/. Add only the files that are missing.
+    write_knowledge_skeleton(repo)
     return True
 
 
@@ -192,6 +317,7 @@ def init_memory_repo(
         ),
         encoding="utf-8",
     )
+    write_knowledge_skeleton(path)
     (path / "facts").mkdir()
     (path / "facts" / "README.md").write_text(
         _nl("# 长说明\n\n整理时才把索引收进这里。这些文件不是另一套权威。权威仍是信箱。\n"),