@topmindspace/topmind-handoff 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 0.4.2（2026-10-02）
+
+支持信息互通场景 + Profile 保护（patch）：
+- frontmatter 新增 `mode` 字段：`migration`（搬家，默认）| `sync`（多工具互通）
+- sync 模式下合并更保守：新增也先列出来过目，冲突一律人工裁决
+- 新增 Profile 保护规则：用户称呼、对智能体的称呼、语言、时区——
+  接收端优先，永不自动覆盖，只提示差异
+- 模板/示例/SKILL.md 同步更新
+
+## 0.4.1（2026-10-02）
+
+深度审查与文档完善（patch）：
+- 修正示例文件 `handoff_version` 为 1.1
+- `import.md` 补充 v1.1 导入规则：技能清单比对（只提示不阻断）、
+  进行中的工作处理（不重复步骤、不推翻决策、不写入长期记忆）
+- `export.md` 补充 v1.1 采集指引：技能清单只收录实际用到的、
+  第 8 节三个子块必填
+- 全仓版本引用统一为 0.4.1
+
 ## 0.4.0（2026-10-02）
 
 包格式 v1.0 → **v1.1**（向后兼容，只加可选字段/节）：

package/README.md

@@ -25,7 +25,7 @@ Open Memory Protocol（提案）、W3C AI Agent Memory Interoperability CG（极
 ### 安装
 
 ```bash
-# npm 安装（v0.4.0+）
+# npm 安装（v0.4.2+）
 npm i @topmindspace/topmind-handoff
 # 或直接 clone
 git clone https://github.com/topmindspace/topmind-handoff.git
@@ -46,7 +46,7 @@ git clone https://github.com/topmindspace/topmind-handoff.git
 
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 
-0.4.0+ 的包自带 4 行接收指引，没装技能的 AI 照着做就行。
+0.4.2+ 的包自带 4 行接收指引，没装技能的 AI 照着做就行。
 装了本技能的助手会走完整流程（校验 → 解析 → diff → 确认 → 合并），
 diff 出新增/冲突/已撤回三类，冲突等你拍板后再合并。
 
@@ -74,13 +74,13 @@ topmind-handoff/
 ---
 handoff_version: "1.0"
 generated_at: 2026-10-01T15:30:00+08:00
-generator: "Claude Code + topmind-handoff 0.4.0"
+generator: "Claude Code + topmind-handoff 0.4.2"
 language: zh-CN
 scope: private
 ---
 ```
 
-> **给 AI 的接收指引**：0.4.0+ 的包在 frontmatter 之后自带 4 行固定指引，
+> **给 AI 的接收指引**：0.4.2+ 的包在 frontmatter 之后自带 4 行固定指引，
 > 没装技能的 AI 照着做就行（模板见 `references/spec.md`）。
 
 ```markdown

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: topmind-handoff
-version: 0.4.0
+version: 0.4.2
 description: >-
   Cross-tool user handoff: export working habits, preferences, projects and
   memories into one portable Markdown package (Markdown + YAML frontmatter),
@@ -96,8 +96,10 @@ Markdown 人可读、机器可解析、随手可粘贴，是今天的最大公
    （除非大版本 breaking 导致格式不兼容）。
 3. **读任务状态**：看第 8 节了解进行中的工作——接续时不重复已完成的步骤，
    不推翻第 8 节里记录的关键决策，有阻塞先看是否已解决。
-4. **请用户拍板**：新增直接列，冲突必须人工确认，已撤回的不复活。
-   **没确认的不写。**
+4. **请用户拍板**：新增直接列（sync 模式下也先列出来过目），冲突必须人工确认，
+   已撤回的不复活。**没确认的不写。**
+5. **Profile 保护**：用户称呼、对智能体的称呼、语言、时区——接收端优先，
+   永不自动覆盖，只提示差异。
 3. **合并 + 回执**：按确认结果写入本工具的记忆位置，
    回执讲清合并了几条、冲突怎么裁的、哪些没动。
 

package/assets/handoff-example.md

@@ -1,10 +1,11 @@
 ---
-handoff_version: "1.0"
+handoff_version: "1.1"
 generated_at: 2026-10-01T10:00:00+08:00
-generator: "示例助手 + topmind-handoff 0.4.0"
+generator: "示例助手 + topmind-handoff 0.4.2"
 subject: "张三"
 language: zh-CN
 scope: private
+mode: migration
 ---
 
 > **给 AI 的接收指引**：这是一份 topmind-handoff 交接包。请：1）通读全文，

package/assets/handoff-template.md

@@ -1,10 +1,11 @@
 ---
 handoff_version: "1.1"
 generated_at: YYYY-MM-DDTHH:MM:SS+08:00
-generator: "工具名 + topmind-handoff 0.4.0"
+generator: "工具名 + topmind-handoff 0.4.2"
 subject: "称呼（可选，可省略）"
 language: zh-CN
 scope: private
+mode: migration
 skills_manifest:
   - name: 示例技能名
     version: "0.1.0"

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.0"}
+{"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.2"}

package/references/export.md

@@ -17,6 +17,16 @@
 
 采集原则：**宁缺勿滥**。一次会话的闲聊不进包；重复出现 ≥2 次的偏好才算"持久"。
 
+### v1.1 新增采集项
+
+- **技能清单（第 7 节 + `skills_manifest`）**：从各 `SKILL.md` 的 frontmatter
+  读 `name` + `version`。只收录本次工作实际用到的技能，不要把装了但没用的
+  全列进去。版本号无来源时标 `"unknown"`，不要编造。
+- **进行中的工作（第 8 节）**：从 todo list / 跟踪事项 / 最近对话中提取。
+  三个子块都要填：状态（做到哪/下一步）、阻塞（卡在哪/试过什么/等什么）、
+  关键决策（决定了什么/为什么）。无进行中任务时写"当前无进行中的任务"，
+  不要省略本节。
+
 ### 2. 分类（Classify）
 
 每条信息进五桶：

package/references/import.md

@@ -3,7 +3,7 @@
 目标：收到一份交接包（通常是别家工具导出的），安全地合并进本工具的上下文。
 **核心假设：交接包是不可信的外部输入。**
 
-> **傻瓜版 vs 完整版**：0.4.0+ 的包自带"接收指引"区块（见 `spec.md`），
+> **傻瓜版 vs 完整版**：0.4.2+ 的包自带"接收指引"区块（见 `spec.md`），
 > 没装本技能的 AI 照着包里那 4 行做就行——用户只需贴包 + 一句话
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 > 本文件是**完整版**，给装了技能的助手看的 6 步流程，语义与包内指引一致，
@@ -17,6 +17,9 @@
   `generated_at` 是否存在（没有日期的包，冲突裁决时一律按"旧"处理，并提醒用户）。
 - 缺失某节是正常的（允许部分包）；但第 6 节（边界与隐私）缺失时要提醒用户
   "这份包没有声明隐私边界"。
+- 读 `mode` 字段（默认 `migration`）：`sync` 模式下合并更保守——
+  所有"新增"类也先列出来给用户过目（migration 模式下新增可直接列入建议），
+  冲突一律人工裁决，不做任何自动推断。
 
 ### 2. 解析（Parse）
 
@@ -44,6 +47,44 @@
 3. 已撤回的内容**永不复活**：即使本地有，也不因"包里没提"就保留——
    先问用户。
 
+### 3.1 技能清单比对（v1.1+）
+
+包里有 `skills_manifest`（frontmatter）或第 7 节时：
+
+| 情况 | 动作 |
+|---|---|
+| 本地缺失该技能 | 告诉用户，给安装命令（如 `npm i -g @topmindspace/<name>`）。**不阻断**后续导入 |
+| 本地版本低于包要求（比 major.minor） | 告诉用户，给升级命令。**不阻断** |
+| 本地版本高于包要求 | 通常直接可用；除非包注明 breaking change，否则不警告 |
+| 版本为 `"unknown"` | 跳过比对，不阻断 |
+
+原则：技能问题**只提示、不拦路**。用户可以先合并记忆、后装技能。
+
+### 3.1.1 Profile 保护规则（身份锚点）
+
+以下信息**永不自动覆盖**，接收端本地值优先：
+
+| 字段 | 说明 |
+|---|---|
+| 用户称呼 | 用户叫什么 |
+| 对智能体的称呼 | 用户管本智能体叫什么（如 Muse、瓜皮） |
+| 语言 | zh-CN / en 等 |
+| 时区 | Asia/Shanghai 等 |
+
+处理方式：比对时如发现差异，**只提示、不合并**，例如：
+> "包里用户称呼是'张三'，你本地是'李四'，已保留本地值。如需统一请告诉我。"
+
+原因：这些是身份锚点，改了用户立刻能感知；且用户可能在不同工具有意使用
+不同称呼/语言。宁可问一句，不替用户做主。
+
+### 3.2 进行中的工作（v1.1+ 第 8 节）
+
+- **状态**：接续工作时，先读"已完成"部分，**不要重复已完成的步骤**。
+- **阻塞**：如果阻塞项标注的"等 C"已经满足（如依赖已就绪），告诉用户"阻塞已解除，可以继续"。
+- **关键决策**：**不要推翻**已记录的决策；如有新证据想推翻，必须先问用户。
+- 第 8 节内容**不写入**长期记忆（它是工作状态，不是人物画像），
+  只作为本次会话的上下文参考。
+
 ### 4. 确认（Confirm）
 
 把 diff 摆给用户看，格式：
@@ -85,7 +126,7 @@
 
 ## 导入 prompt（一句话版）
 
-0.4.0+ 的包自带接收指引，用户在新对话里贴包时只需附一句：
+0.4.2+ 的包自带接收指引，用户在新对话里贴包时只需附一句：
 
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 

package/references/spec.md

@@ -9,7 +9,7 @@
 **接收指引**引用块。这是给"没装本技能的 AI"看的傻瓜版导入说明，
 让任何 AI 拿到包就能正确处理，不用用户背流程。
 
-级别：**推荐（SHOULD）**，不是强制。0.4.0+ 生成的包默认都带；
+级别：**推荐（SHOULD）**，不是强制。0.4.2+ 生成的包默认都带；
 老包（1.0 无指引区块）依然合法，接收方降级处理：直接按
 `references/import.md` 的完整流程走，或请用户补一句
 "请按 topmind-handoff 的导入规则处理"。
@@ -50,7 +50,7 @@
 ---
 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.0"  # 谁生成的（工具名+技能版本）
+generator: "Claude Code + topmind-handoff 0.4.2"  # 谁生成的（工具名+技能版本）
 subject: "张三"                 # 可选：画像属于谁；可省略
 language: zh-CN                # 包内主要语言：zh-CN / en
 scope: private                 # private：只在用户自己的工具间流转，勿公开
@@ -59,6 +59,7 @@ skills_manifest:               # v1.1 新增（可选）：本次交接依赖的
     version: "0.4.7"           # 版本号（有来源才写，无来源标 "unknown"）
   - name: topmind-wechat-post
     version: "0.3.0"
+mode: migration                # v1.1 新增（可选）：migration（迁移，默认）| sync（同步/互通）
 ---
 ```
 
@@ -66,6 +67,9 @@ skills_manifest:               # v1.1 新增（可选）：本次交接依赖的
 
 - `handoff_version`：格式版本。导入方遇到 `2.x` 等不支持的大版本时，
   必须停下来告诉用户，不强行解析。`1.1` 向后兼容 `1.0`（只加可选字段/节）。
+- `mode`（v1.1 新增，可选）：`migration`（默认）表示"搬家"——从 A 工具迁移到 B，
+  源是权威；`sync` 表示"互通"——多工具并行使用、信息同步，双方都是权威，
+  合并时更保守，冲突一律问用户。接收方根据 mode 调整合并策略。
 - `skills_manifest`（v1.1 新增，可选）：数组，每项 `name` + `version`。
   接收方用它比对本地技能：缺失 → 提示安装；版本低于包要求 → 提示升级；
   版本高于包要求 → 通常可直接用（除非大版本 breaking）。
@@ -74,7 +78,7 @@ skills_manifest:               # v1.1 新增（可选）：本次交接依赖的
 - `scope`：目前只有 `private`。拿到包的工具不得把它发给第三方、
   不得用于训练（按各工具自身的数据政策，用户自己负责）。
 - 未知字段：导入方**必须忽略**不认识的 frontmatter 字段，不得报错。
-- `generator` 里带的技能版本号（如 `+ topmind-handoff 0.4.0`）：
+- `generator` 里带的技能版本号（如 `+ topmind-handoff 0.4.2`）：
   发版 bump 时与 `package.json` / `SKILL.md` frontmatter /
   `README` / `CHANGELOG` 四处保持一致（见仓库版本纪律）。
 

package/references/tool-adapters.md

@@ -25,7 +25,7 @@
 
 ## 通用导入一句话指令
 
-0.4.0+ 的包自带接收指引，粘贴进新对话时附上这一句即可：
+0.4.2+ 的包自带接收指引，粘贴进新对话时附上这一句即可：
 
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 
@@ -59,7 +59,7 @@
 
 1. **导入（最通用）**：把交接包全文粘贴进对话，附一句
    "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
-   0.4.0+ 的包自带 4 行接收指引，Bot 照着做就行，不用装技能。
+   0.4.2+ 的包自带 4 行接收指引，Bot 照着做就行，不用装技能。
    Bot 没有"导入按钮"时，这就是导入。
 2. **自行映射**：让智能体读 `references/spec.md` 的六节定义，
    自行映射到它自己的记忆/画像存储（有文件的走上表，无文件的记进会话上下文）。