@topmindspace/topmind-handoff 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## 0.4.11（2026-10-10）
+
+包格式仍是 1.1，`handoff/<package_id>/<package_id>.md` 布局不变；只改示例与文档，旧包和没装本技能的接收方照常可用。
+
+- 优化示例：交接示例与参考文档里的来源标识统一改为虚构的 `demo` / `example`，示例内容为通用内容
+- 优化文档：模板、示例与 `references/spec.md` 的 `generator` 版本号同步到 0.4.11
+
 ## 0.4.10（2026-10-08）
 
 包格式仍是 1.1，`handoff/<package_id>/<package_id>.md` 布局不变；新字段都是可选扩展，旧包和没装本技能的接收方照常可用。
@@ -71,7 +78,7 @@
 可选扩展（包格式仍为 1.1，不要求接收方升到 1.2）：
 
 - 接收顺序：交接技能缺失或比包内 `generator` 更旧时，告诉用户并建议 `npm i @topmindspace/topmind-handoff` 或克隆仓库，然后用包内指引继续。不等待，不阻断，不自动安装。`skills_manifest` 同样只列出缺失或更旧并给安装提示，然后继续。有技能时接收走完整清单（主张 id、墓碑、画像锚点、第 9 节 diff、云端）；没有时包内指引是正确但较薄的下限。指引不删。
-- 可选 `origin_id`：来源环境的稳定标识，形式 `工具-账号标识-范围`。记忆自动跨设备同步时范围为 `sync`，设备名只作可选 `device_note`，不进 id；本地不同步时设备名进 id，避免两台电脑互相覆盖。可选 `package_id` 每次导出唯一（`origin_id` + 日期 + 短后缀），不引入哈希库。分不清同步还是本地时问一次，记在用户自己的记忆里，不写死路径。不是密钥，但不放凭据；邮箱仅当用户要求保留。虚构例：`Muse-ding-sync`、`GrokBot-ding-MacBook-Air`。
+- 可选 `origin_id`：来源环境的稳定标识，形式 `工具-账号标识-范围`。记忆自动跨设备同步时范围为 `sync`，设备名只作可选 `device_note`，不进 id；本地不同步时设备名进 id，避免两台电脑互相覆盖。可选 `package_id` 每次导出唯一（`origin_id` + 日期 + 短后缀），不引入哈希库。分不清同步还是本地时问一次，记在用户自己的记忆里，不写死路径。不是密钥，但不放凭据；邮箱仅当用户要求保留。虚构例：`Muse-demo-sync`、`GrokBot-demo-MacBook-Air`。
 - 可选云端，仅私有 Git：`cloud_repo`（owner/name）与 `cloud_path`（缺省 `handoff/`）。「初始化 handoff / 配置云端交接」询问仓库和目录，拒绝公开仓库。不存 PAT，用已有 git/gh 凭据；没有就停下，不让用户把 token 贴进对话。未配置不静默推送。配置后「帮我做 handoff」生成包、交给用户，并推到 `cloud_path/<origin_id>/<package_id>.md`（有资料则同级）。用户可说「只本地」。「帮我接收最新 handoff」没贴文件且已配置时，按来源取最新再接收；多个来源短列后取最近生成的，除非用户点名。不编造仓库。
 - 清理：推送成功或接收之后，可以删该私有仓库里同一 `origin_id` 的旧包，只留最新一份及其资料。不删其他来源；仓库看起来公开，或路径不是已配置的 `cloud_path`，就不删。不碰项目仓库和其他路径。由模型当次用 git 执行，不是常驻程序。包内写明清理只留每个来源的最新一份。
 - 写明角色：技能只准备并校验交接包；接收与合并是模型按包内文字做的判断。不规定解析器、CRDT、数据库或自动合并代码。

package/README.md

@@ -89,7 +89,7 @@ topmind-handoff/
 ---
 handoff_version: "1.1"
 generated_at: 2026-10-01T15:30:00+08:00
-generator: "Claude Code + topmind-handoff 0.4.10"
+generator: "Claude Code + topmind-handoff 0.4.11"
 language: zh-CN
 scope: private
 ---
@@ -118,5 +118,5 @@ scope: private
 
 ## 版本
 
-当前技能版本 `0.4.10`，交接包格式 `1.1`。更新记录见 `CHANGELOG.md`。
+当前技能版本 `0.4.11`，交接包格式 `1.1`。更新记录见 `CHANGELOG.md`。
 已配置私有云端时，每次推送默认清理该来源的旧包（规则见 `references/export.md`「云端推送与清理」，删除清单会在定稿前列给你确认）。说「只本地」则不推、不删。

package/SKILL.md

@@ -19,7 +19,7 @@ compatibility: >-
   Optional private-git sync uses the user's existing git/gh credential only.
   No SDK. No token stored.
 metadata:
-  version: "0.4.10"
+  version: "0.4.11"
   author: TopMindSpace
   homepage: https://github.com/topmindspace/topmind-handoff
   updated: "2026-10-08"

package/assets/handoff-example.md

@@ -1,22 +1,22 @@
 ---
 handoff_version: "1.1"
 generated_at: 2026-10-01T10:00:00+08:00
-generator: "示例助手 + topmind-handoff 0.4.10"
+generator: "示例助手 + topmind-handoff 0.4.11"
 subject: "张三"
 language: zh-CN
 scope: private
 mode: migration
 skills_manifest:
   - name: topmind-handoff
-    version: "0.4.10"
+    version: "0.4.11"
     source: "npm:@topmindspace/topmind-handoff"
     install: npm-copy
   - name: 示例技能A
     version: "1.2.0"
     source: local
 assets_bundle: "./notes"
-origin_id: "Muse-ding-sync"
-package_id: "Muse-ding-sync-20261001-k7"
+origin_id: "Muse-demo-sync"
+package_id: "Muse-demo-sync-20261001-k7"
 device_note: "MacBook Air"
 cloud_repo: "example/private-handoff"
 cloud_path: "handoff/"
@@ -110,7 +110,7 @@ cloud_path: "handoff/"
 ## 7. 环境与技能（Environment & skills）
 
 - 环境：示例助手（账号 zhangsan，记忆随账号同步）；工作通常放在 `~/work/blog`。
-- 已装技能：topmind-handoff 0.4.10（npm 包 @topmindspace/topmind-handoff）：跨环境交接；示例技能A 1.2.0（本地自建）：用于演示技能清单格式。
+- 已装技能：topmind-handoff 0.4.11（npm 包 @topmindspace/topmind-handoff）：跨环境交接；示例技能A 1.2.0（本地自建）：用于演示技能清单格式。
 - 路径：技能目录 `~/.claude/skills`；博客草稿输出到 `~/work/blog/drafts`。
 - 连接器：GitHub（读写自己的仓库）；日历（只读）。
 
@@ -133,7 +133,7 @@ cloud_path: "handoff/"
 - 仓库：`example-blog`，分支 `main`，最近提交 `a1b2c3d`，remote `https://github.com/example/example-blog`。导出前已建议用户自行 commit 并 push（技能不代提交）。导出时工作区干净。
 - 大文件：不嵌入。演示数据集在 `https://example.com/drive/demo-dataset`，建议落点 `./data/`。
 - 小资料：与本文件同一文件夹（无密钥）。
-- 交接云端（虚构，不要拉取或删除）：`example/private-handoff` 的 `handoff/Muse-ding-sync-20261001-k7/Muse-ding-sync-20261001-k7.md`。全库最新一份是当前事实。推送时每个来源只留最新一份。这不是上面的项目仓库。
+- 交接云端（虚构，不要拉取或删除）：`example/private-handoff` 的 `handoff/Muse-demo-sync-20261001-k7/Muse-demo-sync-20261001-k7.md`。全库最新一份是当前事实。推送时每个来源只留最新一份。这不是上面的项目仓库。
 
 | 包内相对路径 | 建议相对落点 | 简述 |
 |---|---|---|

package/assets/handoff-template.md

@@ -1,7 +1,7 @@
 ---
 handoff_version: "1.1"
 generated_at: YYYY-MM-DDTHH:MM:SS+08:00
-generator: "工具名 + topmind-handoff 0.4.10"
+generator: "工具名 + topmind-handoff 0.4.11"
 subject: "称呼（可选，可省略）"
 language: zh-CN
 scope: private
@@ -11,7 +11,7 @@ skills_manifest:                           # 本环境已装的技能清单
     version: "0.1.0"
     source: "npm:@scope/包名"               # 可选：npm:<包名> | github:<owner/name> | local。不用就删掉本行
     install: npm-copy                       # 可选：安装方式，见 references/environment.md。不用就删掉本行
-origin_id: "工具-账号标识-范围"          # 可选。不用就删掉本行。例：Muse-ding-sync
+origin_id: "工具-账号标识-范围"          # 可选。不用就删掉本行。例：Muse-demo-sync
 package_id: "工具-账号标识-范围-YYYYMMDD-xx"  # 可选。每次唯一。不用就删掉本行
 device_note: "设备名"                      # 可选。仅 sync，不进 origin_id。不用就删掉本行
 cloud_repo: "owner/name"                   # 可选。仅私有。不用云端就删掉本行

package/package.json

@@ -1 +1 @@
-{"author": "TopMindSpace", "bugs": {"url": "https://github.com/topmindspace/topmind-handoff/issues"}, "description": "跨工具用户上下文交接技能：把工作习惯、偏好、项目与记忆导出为便携 Markdown 交接包，或接收别家工具的交接包并安全合并。Cross-tool user handoff skill for AI agents.", "engines": {"node": ">=18"}, "files": ["SKILL.md", "references", "assets", "README.md", "LICENSE", "CHANGELOG.md"], "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.4.10"}
+{"author": "TopMindSpace", "bugs": {"url": "https://github.com/topmindspace/topmind-handoff/issues"}, "description": "跨工具用户上下文交接技能：把工作习惯、偏好、项目与记忆导出为便携 Markdown 交接包，或接收别家工具的交接包并安全合并。Cross-tool user handoff skill for AI agents.", "engines": {"node": ">=18"}, "files": ["SKILL.md", "references", "assets", "README.md", "LICENSE", "CHANGELOG.md"], "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.4.11"}

package/references/spec.md

@@ -159,7 +159,7 @@ frontmatter 之后、正文 `#` 标题之前，放一块固定的**接收指引*
 ---
 handoff_version: "1.1"          # 包格式版本。当前仍生成 1.1（1.0 包仍兼容）
 generated_at: 2026-10-01T15:30:00+08:00   # 整包导出时间，ISO 8601，带时区
-generator: "Claude Code + topmind-handoff 0.4.10"  # 工具名 + 技能版本
+generator: "Claude Code + topmind-handoff 0.4.11"  # 工具名 + 技能版本
 subject: "张三"                 # 可选
 language: zh-CN                # zh-CN / en
 scope: private                 # 只在用户自己的工具间流转
@@ -172,8 +172,8 @@ skills_manifest:               # 可选 1.1：本环境已装的技能清单
     version: "0.3.1"
 mode: migration                # 可选 1.1：migration（默认）| sync
 assets_bundle: "./notes"  # 可选 1.1：包文件夹内、相对这份 markdown 的路径；没有就省略
-origin_id: "Muse-ding-sync"   # 可选 1.1：来源环境，跨时间稳定。不用就省略整行
-package_id: "Muse-ding-sync-20261001-k7"  # 可选 1.1：本次导出唯一。不用就省略
+origin_id: "Muse-demo-sync"   # 可选 1.1：来源环境，跨时间稳定。不用就省略整行
+package_id: "Muse-demo-sync-20261001-k7"  # 可选 1.1：本次导出唯一。不用就省略
 device_note: "MacBook Air"    # 可选 1.1：仅 sync 时的设备参考，不进 origin_id
 cloud_repo: "example/private-handoff"  # 可选 1.1：私有 GitHub owner/name。不用就省略
 cloud_path: "handoff/"         # 可选 1.1：仓库内相对目录，缺省 handoff/
@@ -199,12 +199,12 @@ cloud_path: "handoff/"         # 可选 1.1：仓库内相对目录，缺省 han
 - `assets_bundle`（可选 1.1 扩展）：该包文件夹内、相对这份 markdown 的路径。没有小资料就省略。新包不再使用同级 `-assets/`。
   不写绝对家目录；用户名用 `~`。
 - `scope`：目前只有 `private`。不得把包发给第三方。
-- `generator` 里的技能版本（如 `topmind-handoff 0.4.10`）与 `package.json`、
+- `generator` 里的技能版本（如 `topmind-handoff 0.4.11`）与 `package.json`、
   `SKILL.md` 的 `metadata.version` 一致。
   接收方用这个版本和本机技能比较；字符串里没有版本号就不要声称「更旧」。
 - `origin_id`、`package_id`、`device_note`、`cloud_repo`、`cloud_path`：都可选。
   不用就省略整行，不要留空字符串冒充已经配置。看见不认识的就忽略。规则见下两节。
-  示例里的 `example/private-handoff` 与 `ding` 都是虚构，不是要去拉取的仓库。
+  示例里的 `example/private-handoff` 与 `demo` 都是虚构，不是要去拉取的仓库。
 
 ## origin_id 与 package_id（可选，1.1 扩展）
 
@@ -224,8 +224,8 @@ cloud_path: "handoff/"         # 可选 1.1：仓库内相对目录，缺省 han
 
 虚构例子（不是真实账号）：
 
-- 自动同步：`Muse-ding-sync`。可以另写 `device_note: "MacBook Air"`，这台机器的名字不在 id 里。
-- 本地且不同步：`GrokBot-ding-MacBook-Air`。
+- 自动同步：`Muse-demo-sync`。可以另写 `device_note: "MacBook Air"`，这台机器的名字不在 id 里。
+- 本地且不同步：`GrokBot-demo-MacBook-Air`。
 
 分不清自动同步还是本地不同步：问用户一次。答案和定下来的 `origin_id` 记在**这个用户在本工具里已有的记忆**中，下次沿用。不要写死某个文件路径。换了一台不同步的电脑，才是另一个 `origin_id`；同步型工具换设备不换 id。
 
@@ -340,7 +340,7 @@ cloud_path: "handoff/"         # 可选 1.1：仓库内相对目录，缺省 han
 - 经验教训：这条任务上已经验证过的，一条一句。换工具也成立的，同时写进第 5 节
 - 参考：链接或相对路径。不是密钥。接收方不自动打开
 
-状态行标明来源，例如「GrokBot-mspd-sync：草稿未改」。
+状态行标明来源，例如「GrokBot-example-sync：草稿未改」。
 另一台环境的进度写在同一 id 下另起一行，不要互相改写。
 
 - **状态（Status）**：上面的任务条目放这里。

package/references/tool-adapters.md

@@ -108,8 +108,8 @@
 
 导出时给来源一个稳定的 `origin_id`（见 `spec.md`）：`工具-账号标识-范围`。
 
-- 记忆会在用户的手机和电脑之间自动带上（常见于 Muse 这类账号同步）：范围为 `sync`，例如 `Muse-ding-sync`。设备名只放 `device_note`，不进 id。
-- 本机安装、记忆不跟着账号走：设备名写进 id，例如 `GrokBot-ding-MacBook-Air`。两台笔记本不会被当成同一个来源。
+- 记忆会在用户的手机和电脑之间自动带上（常见于 Muse 这类账号同步）：范围为 `sync`，例如 `Muse-demo-sync`。设备名只放 `device_note`，不进 id。
+- 本机安装、记忆不跟着账号走：设备名写进 id，例如 `GrokBot-demo-MacBook-Air`。两台笔记本不会被当成同一个来源。
 - 账号标识用用户认得的 handle，不要 token；邮箱只有用户要求保留才用。
 - 云端交接只走用户已经配好的私有 Git。没有 git 凭据就说明缺少凭据并停下，不要索要 token。公开仓库不推、不拉、不删。