@topmindspace/topmind-handoff 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 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.1+）
 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.1+ 的包自带 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.1"
 language: zh-CN
 scope: private
 ---
 ```
 
-> **给 AI 的接收指引**：0.4.0+ 的包在 frontmatter 之后自带 4 行固定指引，
+> **给 AI 的接收指引**：0.4.1+ 的包在 frontmatter 之后自带 4 行固定指引，
 > 没装技能的 AI 照着做就行（模板见 `references/spec.md`）。
 
 ```markdown

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: topmind-handoff
-version: 0.4.0
+version: 0.4.1
 description: >-
   Cross-tool user handoff: export working habits, preferences, projects and
   memories into one portable Markdown package (Markdown + YAML frontmatter),

package/assets/handoff-example.md

@@ -1,7 +1,7 @@
 ---
-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.1"
 subject: "张三"
 language: zh-CN
 scope: private

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.0"
+generator: "工具名 + topmind-handoff 0.4.1"
 subject: "称呼（可选，可省略）"
 language: zh-CN
 scope: private

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.1"}

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.1+ 的包自带"接收指引"区块（见 `spec.md`），
 > 没装本技能的 AI 照着包里那 4 行做就行——用户只需贴包 + 一句话
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 > 本文件是**完整版**，给装了技能的助手看的 6 步流程，语义与包内指引一致，
@@ -44,6 +44,27 @@
 3. 已撤回的内容**永不复活**：即使本地有，也不因"包里没提"就保留——
    先问用户。
 
+### 3.1 技能清单比对（v1.1+）
+
+包里有 `skills_manifest`（frontmatter）或第 7 节时：
+
+| 情况 | 动作 |
+|---|---|
+| 本地缺失该技能 | 告诉用户，给安装命令（如 `npm i -g @topmindspace/<name>`）。**不阻断**后续导入 |
+| 本地版本低于包要求（比 major.minor） | 告诉用户，给升级命令。**不阻断** |
+| 本地版本高于包要求 | 通常直接可用；除非包注明 breaking change，否则不警告 |
+| 版本为 `"unknown"` | 跳过比对，不阻断 |
+
+原则：技能问题**只提示、不拦路**。用户可以先合并记忆、后装技能。
+
+### 3.2 进行中的工作（v1.1+ 第 8 节）
+
+- **状态**：接续工作时，先读"已完成"部分，**不要重复已完成的步骤**。
+- **阻塞**：如果阻塞项标注的"等 C"已经满足（如依赖已就绪），告诉用户"阻塞已解除，可以继续"。
+- **关键决策**：**不要推翻**已记录的决策；如有新证据想推翻，必须先问用户。
+- 第 8 节内容**不写入**长期记忆（它是工作状态，不是人物画像），
+  只作为本次会话的上下文参考。
+
 ### 4. 确认（Confirm）
 
 把 diff 摆给用户看，格式：
@@ -85,7 +106,7 @@
 
 ## 导入 prompt（一句话版）
 
-0.4.0+ 的包自带接收指引，用户在新对话里贴包时只需附一句：
+0.4.1+ 的包自带接收指引，用户在新对话里贴包时只需附一句：
 
 > "这是我的交接包（topmind-handoff 格式），请按包里的接收指引处理。"
 

package/references/spec.md

@@ -9,7 +9,7 @@
 **接收指引**引用块。这是给"没装本技能的 AI"看的傻瓜版导入说明，
 让任何 AI 拿到包就能正确处理，不用用户背流程。
 
-级别：**推荐（SHOULD）**，不是强制。0.4.0+ 生成的包默认都带；
+级别：**推荐（SHOULD）**，不是强制。0.4.1+ 生成的包默认都带；
 老包（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.1"  # 谁生成的（工具名+技能版本）
 subject: "张三"                 # 可选：画像属于谁；可省略
 language: zh-CN                # 包内主要语言：zh-CN / en
 scope: private                 # private：只在用户自己的工具间流转，勿公开
@@ -74,7 +74,7 @@ skills_manifest:               # v1.1 新增（可选）：本次交接依赖的
 - `scope`：目前只有 `private`。拿到包的工具不得把它发给第三方、
   不得用于训练（按各工具自身的数据政策，用户自己负责）。
 - 未知字段：导入方**必须忽略**不认识的 frontmatter 字段，不得报错。
-- `generator` 里带的技能版本号（如 `+ topmind-handoff 0.4.0`）：
+- `generator` 里带的技能版本号（如 `+ topmind-handoff 0.4.1`）：
   发版 bump 时与 `package.json` / `SKILL.md` frontmatter /
   `README` / `CHANGELOG` 四处保持一致（见仓库版本纪律）。
 

package/references/tool-adapters.md

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