harveyz-skill 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-08-28
+
+### Added
+- `roster`：新增 tool，人（creator）与渠道（channel）名册。三份数据、三个写入方：`registry.json`（人与渠道定义，归 manage-roster）、`state.json`（游标与失败态，归 sync-*）、`profiles/*.md`（画像，归 capture-creator）。CLI 按同样的三组划分。渠道数据可重建，画像不可重建——删除操作一律归档而非删除
+- `manage-roster`：新增 skill，名册的人机入口（`add` / `list` / `merge` / `rename` / `remove`），含旧 watchlist 的一次性幂等迁移
+- `capture-creator`：新增 skill，认知层的人工输入口。你口述对某个博主的判断，它归纳成要点、盖上当前时间戳、回显确认后追加进 `profiles/<id>.md`。判断由人出，agent 只做整理，未经确认不写盘
+
+### Changed
+- `roster profile append`：`--source`（依据）改为可选，省略时记为 `人工`——这个值同时就是作者标记，用来区分本人下的判断和 agent 从物料推的观察。正文可以省略 `--body` 改从 stdin 读，多行 Markdown 不再受命令行引号和换行的折磨。观察条目的时间戳支持可选的 `HH:MM`（一天记好几条时需要分先后），纯日期的旧条目不需要迁移
+- `roster profile append` / `summary`：写入前校验 `creator_id` 在名册里存在（接受 merge 后的 alias）。此前手打错一个字母会安静地建出一个没人引用、`registry remove` 也不会归档的孤儿画像
+- **破坏性变更** `sync-xtimeline` / `sync-ytchannel`：移除 `add` / `remove` / `list` 三个子命令，关注列表迁到 `manage-roster`。两个 skill 退化为纯执行器，只保留 `run`（sync-xtimeline 另留 `view`）。两者不再各持一份 `DATA_DIR`，改为共用名册的数据目录，digest 各落各的平台子目录（`digests/x/`、`digests/youtube/`）
+  - **升级路径**：跑一次 `manage-roster` 的初始化流程，它会引导完成迁移。迁移后每个 handle 各自是一个人，同一个人的 X 和 YouTube 需要手动 `merge` 合并——判断"这两个 handle 是同一个人"不能自动化。旧的 `~/.hskill/sync-xtimeline/config.json` 和 `~/.hskill/sync-ytchannel/config.json` 作废但不会被自动删除
+
+### Fixed
+- `scripts/run-skill-tests.sh`：此前对 `skills/*/*/tests/*.py` 执行 `python3 <file>`，而它们是 pytest 文件——直接执行只 import 模块然后退出 0，一个测试都不跑，`npm test` 一直把"没跑"报成"通过"。改为按 `tests/` 目录调 pytest，并纳入 `tools/*/tests/`。修复后 `npm test` 真正执行 10 个套件共 665 个 pytest，其中 282 个是本次改动之前就存在、却从未被 CI 执行过的。归档代码（`*/archived/*`）排除在测试范围外；工具套件优先用自己的 `.venv`（仅当该 venv 装了 pytest）
+
+## [0.28.0] - 2026-08-15
+
+### Added
+- `sync-xtimeline`：新增 skill（原名 watch-x），批量追更一批固定的 X 博主推文，抓取时自动识别推文类型（post/repost/quote/reply），产出翻译摘要 + 累计静态 HTML 时间线视图（X 风格深色主题）
+- `browser-fetch-mcp`：新增 `fetch_user_timeline` MCP 工具，支持抓取 X 用户时间线
+- `fetch-paper`：新增 skill，贡献到 research bundle
+
+### Changed
+- `explain-pm`：输出改为分层，界定技术语言边界，允许调研代码
+
+### Fixed
+- `fetch-paper`：修复 PMC/OA 页面被反爬拦截无法抓取、PDF 二进制内容误用 Write 工具写盘、SKILL.md F3 违规
+- `learn-video`：硬编码用户路径改用 `$HOME` + task_id 读取重试；改为后台执行+日志判定，避免阻塞调用
+
 ## [0.27.0] - 2026-08-13
 
 ### Added

package/package.json

@@ -1,31 +1,35 @@
 {
   "name": "harveyz-skill",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi",
   "type": "module",
   "bin": {
-    "hskill": "bin/cli.js"
+    "hskill": "bin/cli.js",
+    "skill-harness": "tools/skill-harness/cli.js"
   },
   "scripts": {
     "prepack": "node scripts/generate-npmignore.js",
-    "test": "bats tests/ && bash scripts/run-skill-tests.sh && node --test tests/mcp.test.mjs"
+    "test": "bats tests/ && bash scripts/run-skill-tests.sh && node --test tests/mcp.test.mjs tests/harness/*.test.mjs"
   },
   "files": [
     "bin/",
     "lib/",
+    "tools/skill-harness/",
     "bundles.json",
     "skills-index.json",
     "CHANGELOG.md",
     "skills/mint/learn-skill/",
-    "skills/research/extract-url/",
     "skills/research/extract-vision/",
     "skills/research/learn-video/",
     "skills/research/survey-skillrepo/",
     "skills/research/learn-paper/",
+    "skills/research/fetch-paper/",
     "skills/research/extract-cognition/",
     "skills/research/probe-session/",
     "skills/research/pdf-math-translate/",
     "skills/research/clip-url/",
+    "skills/feed/sync-xtimeline/",
+    "skills/feed/sync-ytchannel/",
     "skills/creative/capture-todo/",
     "skills/creative/capture-insight/",
     "skills/coding/init-workflow/",
@@ -55,9 +59,12 @@
     "skills/meta/sync-hotfix/",
     "skills/meta/sync-agent/",
     "skills/coding/handoff/",
+    "skills/feed/manage-roster/",
+    "skills/feed/capture-creator/",
     "tools/hub/",
     "tools/sync-agent/",
-    "tools/browser-fetch-mcp/",
+    "tools/browser-fetch/",
+    "tools/roster/",
     "hooks/check-similar-branch/"
   ],
   "engines": {

package/skills/coding/explain-pm/SKILL.md

@@ -1,34 +1,60 @@
 ---
 name: explain-pm
-description: "Restate a recent technical explanation from a product-manager's analytical lens — user experience, product philosophy, execution mechanics, and architectural health — rather than translating jargon, and flag product-perspective concerns like scope, over-engineering, priority, or drift from user need. Triggers: '/explain-pm', '/explain-pm <topic or file>', 'explain this like a PM', 'restate from a PM perspective'."
+description: "Restate a technical explanation in language a product manager can act on — what changes for users, which components are involved, and the call/timing dependencies between them — keeping technical terms that carry architecture and dropping pure implementation mechanics. May read related code to fill in facts the original left out. Product-angle observations, if any, go in a separate optional section, never mixed into the restatement. Triggers: '/explain-pm', '/explain-pm <topic or file>', 'explain this like a PM', 'restate from a PM perspective'."
 user_invocable: true
-version: "1.1.1"
+version: "1.2.0"
 ---
 
 # explain-pm — PM 视角复述
 
-把一段技术性表述从 PM 视角复述：换成 PM 关注的分析维度，再视情况指出值得从产品角度重新考虑的地方。
+把一段技术性表述复述成 PM（产品经理）能听懂、能据以决策的版本。
+
+输出分两层，边界必须清晰：
+
+1. **核心复述**（必出）——严格不超出原材料的范围。
+2. **产品角度的延伸**（可选）——有才写，没有就整节不出现。
 
 ## 触发
 
 仅手动调用：`/explain-pm` 或 `/explain-pm <主题或文件路径>`。不自动检测触发，不主动插话。
 
-## PM 视角的关注维度
+## 技术语言的保留边界
+
+不是把技术语言全部剥离——PM 本身熟悉基础技术语言，剥干净反而看不懂全貌。判据是：
+
+> PM 依赖的是「什么在什么之后发生、谁依赖谁」，不依赖「这段代码是怎么写的」。
+
+**保留**（撑起架构轮廓和调用关系的技术表述）：
+
+- 组件、服务、模块的名字
+- 调用方向：谁调用谁，同步还是异步
+- 依赖与时序：谁必须先就绪，哪一步是阻塞的
+- 失败传播：某一环挂了，影响面到哪里为止
+
+**剥离**（纯实现机制，对理解全貌没有帮助）：
+
+- 函数签名、参数、返回值类型
+- 数据结构、字段名、序列化格式
+- 算法实现、设计模式名称
+- 具体代码怎么写的、用了哪个库的哪个 API
+
+## 核心复述的组织维度
 
-不是语言转译——PM 本身熟悉基础技术语言。要转换的是关注点：
+分析时的参考，不必在回复里逐条列出，也不套固定小标题：
 
-- **用户体验**：这个决定最终会让用户感受到什么变化？
-- **产品哲学**：是否符合产品一贯的取舍和原则？
-- **执行机制与流程**：具体怎么落地——谁来做、分几步、影响什么协作节奏？
-- **架构健康度（次要）**：是否有明显的技术债或长期维护风险，只做提醒，不展开实现细节本身。
+- **用户侧变化**：这件事最终让用户感受到什么？
+- **参与者**：涉及哪些组件/角色，各自负责什么？
+- **调用关系与时序依赖**：谁先谁后、谁依赖谁、哪一环可能卡住？
+- **执行机制与影响面**：谁来做、分几步、影响什么协作节奏、边界在哪？
 
 ## 执行
 
 1. **取材料**：带参数用参数指定的主题或文件；无参数则取调用前的最后一条 assistant 消息。
-2. **换视角**：对照上面的关注维度重新审视材料——不必在回复里逐条列出，只是分析时的参考。
-3. **提出关注点（视情况）**：判断原表述从 PM 角度是否有值得重新审视的地方，比如是否偏离用户实际需求、范围是否合理、是否过度工程化、优先级是否搞错了。如果原表述本身已经很贴近产品目标，挑不出问题，就只做视角复述，不硬造关注点。关注点如果成立，放在回复最后，不要打断前面的视角复述。
-4. **输出**：在对话中直接回复，简短（几句话量级）。默认不写文件；仅当用户明确要求存档时，才把这段评论写入用户指定的文件。
+2. **按需调研**：如果原表述没交代清楚 PM 需要知道的调用关系或依赖顺序，去读相关代码/文件把事实补齐。调研只为补核心复述的事实，不用于给延伸小节攒素材。
+3. **写核心复述**：对照上面的维度和保留边界重述，严格限定在原材料（含第 2 步补齐的事实）范围内，不做评价、不做建议。
+4. **写延伸（视情况）**：判断是否真有值得从产品角度说的——产品哲学上是否符合一贯取舍、有无明显技术债或长期维护风险、范围是否合理、优先级是否搞错、是否过度工程化。有就单独成节，与核心复述之间保持明确分隔；**挑不出就整节不写，不硬造**。
+5. **输出**：在对话中直接回复，简短（核心复述几句话量级）。默认不写文件；仅当用户明确要求存档时，才写入用户指定的文件。
 
 ## 不做
 
-多轮追问式澄清、自动检测技术语言并主动触发、默认生成或保存文档、固定的输出小标题模板。
+多轮追问式澄清、自动检测技术语言并主动触发、默认生成或保存文档、在核心复述里夹带评价或改进建议、为了凑出延伸小节而硬造关注点。

package/skills/coding/handoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: handoff
 description: Use when handing a task across sessions — writing a self-contained handoff doc for a fresh session to pick up (author), sanity-checking an inbound handoff before starting (verify), or accepting completed work against the criteria agreed at handoff time (accept). Triggers on phrases like "write a handoff", "hand this off", "pick up this task", "sign off on this work". Generic skill — project-specific conventions are read from .hskill/handoff/config.md.
-version: "1.1.0"
+version: "1.2.0"
 user_invocable: true
 ---
 
@@ -53,8 +53,8 @@ user_invocable: true
 
 ## Phase 3 — accept（原 session 验收）
 
-1. 找文档里的**最小验收锚点**——这是唯一固定依据。硬判据（逐条对/错）→ 按其描述**逐条实跑**（单测/E2E/核验）；软判据（定性描述）→ 按其描述做定性判断。
-2. 把验收结果（每条 pass/fail，或整体达成/未达成）追加记录到最小验收锚点所在章节末尾。
+1. 找文档里的**最小验收锚点**——这是唯一固定依据。**接手方自填的结论一律不采信，逐条自己跑**：验证产物"存在"不等于"跑得过"，点得出脚本名不等于那个脚本此刻是绿的。硬判据（逐条对/错）→ 按其描述**逐条实跑**（单测/E2E/核验）；软判据（定性描述）→ 按其描述做定性判断。
+2. 把验收结果（每条 pass/fail，或整体达成/未达成）追加记录到最小验收锚点所在章节末尾。**接手方若已自填过验收记录，另起小节并列，不覆盖也不合并**——两份并排放着，后来人才看得出哪些结论被第二方复核过。其中若有与实跑不符的陈述，**显式写出更正**，不要静默改掉：静默改掉等于把同一个错误留给下一次。
 3. 达成 → 状态置 `已验收`；未达成 → 状态置 `打回` 并写明哪里没达成、为什么，退回接手方。
 4. **达成才算真正完成**（硬判据要求逐条全绿；软判据按其描述定性判断是否达成）。
 
@@ -63,3 +63,9 @@ user_invocable: true
 `待执行`（author 写完）→ `执行中`（verify 通过 / 接手方开工）→ `待验收`（接手方回报完成）→ `已验收`（accept 判定达成）/ `打回`（accept 判定未达成，退回执行中）。
 
 状态字段是三 phase 间唯一协调锚点，无需外部状态存储。
+
+**写入权按 phase 分：接手方最多只能把状态推到「待验收」。`已验收` / `打回` 只能由原 session 在 accept 之后写。**
+
+这条不是流程洁癖。「已验收」的全部信息量就是**做事的人之外的另一方查过**；做事的人一旦能自己写它，它就退化成「做事的人说做完了」——而这个信息「待验收」里已经有了，两个状态变成同义词，字段失效。风险还会反向放大：一份自填的「已验收」通常附着一张全 PASS 的表，比没有记录更难被怀疑。
+
+接手方若跳档自填，accept 方**按未验收处理**，照常逐条重跑。

package/skills/coding/handoff/assets/handoff-template.md

@@ -14,7 +14,7 @@
 **状态**：待执行 <!-- 待执行 → 执行中 → 待验收 → 已验收 / 打回 -->
 **交接目的**：<一句话，自由描述这次交接是为了什么，不受预设分类约束>
 
-> **接手方须知**：你正在接手一个任务。本文档是完整交接与唯一权威入口：从头读到尾，若文档里有「工作流约定」章节按其开工，没有就直接开工，完成后等原 session 按「最小验收锚点」验收。
+> **接手方须知**：你正在接手一个任务。本文档是完整交接与唯一权威入口：从头读到尾，若文档里有「工作流约定」章节按其开工，没有就直接开工。**完成后把上面的状态置为「待验收」并停在这里**——`已验收` / `打回` 由原 session 按「最小验收锚点」判定后写，不要代填。你的自测结果写成独立小节，别写进原 session 的验收记录里。
 
 ---
 

package/skills/coding/handoff/evals/evals.json

@@ -6,28 +6,74 @@
       "name": "author-high-to-low-model",
       "prompt": "我刚把一个功能模块的重构方案定完了，设计规格已经写好放在仓库里。想把具体实现交给另一个能力较弱的模型 session 去做，帮我写一份交接文档，让它只读这一份就能照着实现，别自由发挥。",
       "expected_output": "在 config 输出目录（默认 docs/commute/）下生成 YYYY-MM-DD-*-handoff.md；抬头含状态字段 + 交接目的（判断为'接手方续做同一实现任务'一类描述）+ 接手方须知。因为是续做同一任务的目的，必要性测试会判定背景/关键决定/范围铁律/相关文档索引/受影响文件/验证步骤等章节基本都需要，实际出现在文档里；若项目有 .hskill/handoff/config.md 则注入其工作流/验证约定；最小验收锚点是可证伪的硬判据；author 收尾跑完整性门禁。",
-      "files": []
+      "files": [],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "file-in-output-dir", "source": "artifact",
+          "text": "在 docs/commute/ 下生成了文件名形如 YYYY-MM-DD-<topic>-handoff.md 的文档" },
+        { "id": "header-has-status-and-purpose", "source": "artifact",
+          "text": "文档抬头同时含状态字段与交接目的两项" },
+        { "id": "purpose-is-continuation", "source": "artifact",
+          "text": "交接目的描述为「接手方续做同一实现任务」一类，而不是仅传递背景" },
+        { "id": "continuation-sections-present", "source": "artifact",
+          "text": "文档含范围铁律与相关文档索引两节" },
+        { "id": "anchor-is-falsifiable", "source": "artifact",
+          "text": "最小验收锚点是硬判据，有明确的对错判定，不是「让它工作」这类无法证伪的软标准" }
+      ]
     },
     {
       "id": 1,
       "name": "author-cross-device-continuation",
       "prompt": "今天先干到这，明天换台电脑接着做这个第三方 SDK 的集成。帮我留一份交接，别让明天的自己丢上下文。",
       "expected_output": "config 输出目录下生成 handoff.md，抬头含状态字段 + 交接目的（判断为续做同一任务一类描述），状态=待执行；背景与现状章节写清当前进度（必要性测试：不写会做错方向 → 判定需要）；最小验收锚点引用原任务的成功判据（硬判据）。",
-      "files": []
+      "files": [],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "file-in-output-dir", "source": "artifact",
+          "text": "在 docs/commute/ 下生成了文件名形如 YYYY-MM-DD-<topic>-handoff.md 的文档" },
+        { "id": "status-is-pending", "source": "artifact",
+          "text": "状态字段的值是「待执行」" },
+        { "id": "background-describes-progress", "source": "artifact",
+          "text": "背景与现状章节写明了当前做到哪一步" },
+        { "id": "anchor-references-original-criteria", "source": "artifact",
+          "text": "最小验收锚点引用原任务的成功判据，且是硬判据" }
+      ]
     },
     {
       "id": 2,
       "name": "accept-catches-failing-criterion",
       "prompt": "接手的 session 说 slugify 那个小任务做完了，交接文档和产物都在 evals/fixtures/accept/ 下（handoff-slugify.md 和 slugify.js）。帮我验收一下，看能不能收。",
       "expected_output": "accept phase：找文档里的最小验收锚点（硬判据，两条 slugify 判据），按其描述逐条实跑(node slugify.js)，发现判据2(去标点)未达标；状态置『打回』而非『已验收』，在最小验收锚点章节追加验收记录点名失败判据。",
-      "files": ["evals/fixtures/accept/handoff-slugify.md", "evals/fixtures/accept/slugify.js"]
+      "files": ["evals/fixtures/accept/handoff-slugify.md", "evals/fixtures/accept/slugify.js"],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "ran-criteria-not-just-read", "source": "transcript",
+          "text": "执行轨迹显示实际运行了 slugify.js（如 Bash 调用 node slugify.js），而不是只读文档就下判断" },
+        { "id": "status-set-to-rejected", "source": "artifact",
+          "text": "fixture 交接文档的状态被置为「打回」，不是「已验收」" },
+        { "id": "names-failing-criterion", "source": "artifact",
+          "text": "验收记录点名了未达标的是「去标点」那一条判据，而不是笼统说没通过" },
+        { "id": "record-appended-to-anchor-section", "source": "artifact",
+          "text": "验收结果被追加在最小验收锚点章节末尾，而不是另起一节或写在文档开头" }
+      ]
     },
     {
       "id": 3,
       "name": "author-background-only-handoff",
       "prompt": "我们刚才在这个 session 里把新缓存方案的取舍和结论定下来了，我要开一个新 session 去做完全不相关的另一件事，但想让新 session 保留这次讨论的结论作为背景，万一之后有人问起能答上来，不是要它去执行什么。帮我写个交接。",
       "expected_output": "交接目的写成类似'仅传递背景结论，不要求接手方产出可验收的实现'一类描述；文档只出现背景与现状（讨论结论）+ 交接目的 + 最小验收锚点（软判据，如'接手方能复述讨论结论要点'）；不出现范围铁律/受影响文件/验证步骤/关键决定这类续做任务专属章节（必要性测试判定为不需要）。",
-      "files": []
+      "files": [],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "purpose-is-background-only", "source": "artifact",
+          "text": "交接目的写成「仅传递背景结论，不要求接手方产出可验收的实现」一类描述" },
+        { "id": "has-purpose-and-anchor", "source": "artifact",
+          "text": "交接目的与最小验收锚点两节均存在" },
+        { "id": "no-continuation-sections", "source": "artifact",
+          "text": "文档不含范围铁律、受影响文件、验证步骤、关键决定中的任何一节" },
+        { "id": "anchor-is-soft", "source": "artifact",
+          "text": "最小验收锚点是软判据（如「接手方能复述讨论结论要点」），不是硬判据" }
+      ]
     }
   ]
 }

package/skills/coding/setup-debug/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "full-stack-debug-env",
+  "skill_name": "setup-debug",
   "evals": [
     {
       "id": 1,
@@ -8,6 +8,17 @@
       "files": [
         "/tmp/fsd-test-node-spa/package.json",
         "/tmp/fsd-test-node-spa/server.js"
+      ],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "log-dir-created", "source": "artifact",
+          "text": "创建了 tmp/logs/ 目录" },
+        { "id": "backend-and-browser-sources", "source": "artifact",
+          "text": "日志来源规划中至少含 backend 与 browser 两个独立来源，各自有独立日志文件" },
+        { "id": "verify-script-created", "source": "artifact",
+          "text": "创建了 harness/debug/verify-logs.sh" },
+        { "id": "both-docs-generated", "source": "artifact",
+          "text": "同时生成了 harness/debug/README.md 与 docs/how-to/debug-env.md 两份文档" }
       ]
     },
     {
@@ -16,6 +27,17 @@
       "expected_output": "应规划 api.log/worker.log/db.log 三个独立日志来源；worker 被识别为异步/任务驱动型来源；verify-logs.sh 中 worker.log 应报 SKIP 而非 FAIL；生成完整文档",
       "files": [
         "/tmp/fsd-test-docker/docker-compose.yml"
+      ],
+      "frozen": "2026-08-17",
+      "assertions": [
+        { "id": "three-sources-planned", "source": "artifact",
+          "text": "规划了 api、worker、db 三个独立日志来源，各自有独立日志文件" },
+        { "id": "worker-typed-async", "source": "artifact",
+          "text": "worker 被识别为异步或任务驱动型来源，而不是与 api 同类处理" },
+        { "id": "worker-skip-not-fail", "source": "artifact",
+          "text": "verify-logs.sh 中 worker.log 的检查结果是 SKIP，不是 FAIL——异步来源在无任务时本就无日志" },
+        { "id": "both-docs-generated", "source": "artifact",
+          "text": "同时生成了 harness/debug/README.md 与 docs/how-to/debug-env.md 两份文档" }
       ]
     }
   ]

package/skills/feed/capture-creator/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: capture-creator
+version: "0.1.0"
+description: "Record your own judgment about a specific creator already on the roster. You say what you think of them, this skill tidies it into points, stamps it with the current time, shows it back for confirmation, then appends it to that creator's profile. Trigger phrases: '/capture-creator <name>', '/capture-creator', 'I have a take on this blogger', 'let me note down what I think of <name>', 'what do I think of <name>', 'show me my profile of <name>'. Scoped to people on the roster — a standalone insight not tied to a watched creator is capture-insight, and adding or removing a watched channel is manage-roster. Running an incremental fetch is sync-xtimeline / sync-ytchannel. Never saves to Obsidian and never tags — saving an article or tweet is clip-url."
+user_invocable: true
+---
+
+# capture-creator
+
+给名册上的人记一笔判断。**判断由你出，这个 skill 只做整理、盖时间戳、落盘。**
+
+它写的是 `profiles/<creator-id>.md`——整套数据里唯一不可重建的部分。名册和游标删了重加一遍就回来了，画像不会。所以这里有两条硬规矩：
+
+- **未经你确认不写盘。** 整理后的正文先回显，你点头才落。
+- **只写 `profiles/`。** 名册归 manage-roster，游标归抓取层，一概不碰。
+
+## 初始化（run first）
+
+```bash
+python3 scripts/roster_locate.py
+```
+
+若输出 `NOT_FOUND: <error>`（exit 1），向用户报告"roster tool 未安装：{error}"，流程终止。
+
+若从未初始化过名册（`~/.hskill/roster/config.json` 不存在），让用户先跑一次 [manage-roster](../manage-roster/)，流程终止。
+
+`<roster>` 指 `roster_locate.py` 输出的路径。
+
+## 记一笔（默认动作）
+
+### 1. 确定是谁
+
+```bash
+<roster> registry list
+```
+
+从用户提到的名字或 handle 里找 `creator_id`（每人一行，行首那个词就是 id）。
+
+- 名册为空（`EMPTY`）或找不到匹配：告诉用户这人不在名册上，让他先用 manage-roster 加渠道，流程终止。**不要自己加。**
+- 多个候选：列出来让用户选，**不要猜**。写错人的画像比不写更糟——观察是只追加的，写进去就在那儿了。
+
+### 2. 整理
+
+把用户口述的内容归纳成要点：提炼观点、重组逻辑、去掉口语碎片，用整齐的 Markdown 呈现。
+
+三条底线：
+
+- **不发明。** 用户没说的判断不能加，包括你自己对这个人的印象。
+- **不加依据。** 不要去查名册、去翻抓取下来的物料给用户的话找佐证。这一笔的来源就是他本人。
+- **拿不准的地方保留原话。** 归纳时如果某句话有两种理解，别替他选一种，原样留着。
+
+### 3. 回显确认
+
+把三样东西一起展示给用户：`creator_id` 和显示名、时间戳、整理后的正文。
+
+用户要改就改完再确认一次。**没拿到明确的确认，不要执行第 4 步。**
+
+### 4. 落盘
+
+时间戳取当前本地时间：
+
+```bash
+date "+%Y-%m-%d %H:%M"
+```
+
+```bash
+<roster> profile append <creator_id> --date "<YYYY-MM-DD HH:MM>" <<'EOF'
+<整理后的正文>
+EOF
+```
+
+正文走 stdin，不要塞进 `--body`——归纳后的多行 Markdown 走命令行参数会被引号和换行搞坏。
+
+依据默认记成 `人工`，这个值同时就是作者标记（将来 agent 自己写的观察会填真实来源）。**只有用户主动说了这一笔是看了什么才来的**（比如给了一条推文链接），才加 `--source "<用户给的来源>"`。
+
+成功输出 `OK <画像文件路径>`，把路径转告用户。
+
+## 看画像
+
+```bash
+<roster> profile show <creator_id>
+```
+
+`EMPTY` 表示这人还没有画像。原样展示，不要替用户总结。
+
+## 边界
+
+不抓取、不翻译、不写名册、不改游标、不进 Obsidian、不打标。
+
+关注谁走 [manage-roster](../manage-roster/)，跑一次增量抓取走 [sync-xtimeline](../sync-xtimeline/) 或 [sync-ytchannel](../sync-ytchannel/)，单条物料入库走 [clip-url](../../research/clip-url/)。
+
+**跟 [capture-insight](../../creative/capture-insight/) 的分界是观察对象**：这一笔是冲着名册上某个具体的人去的，才归这里；不挂在任何人身上的独立想法归 capture-insight。判断不了就问用户，不要自己挑一个。
+
+「当前判断」那一段（从观察重算出一句总结）现在还没有入口，观察攒够了再说。
+
+两个已知限制，用户问起时如实说：
+
+- 写盘是全文件重写，没有加锁。你在编辑器里手改画像的同时跑这个 skill，后落盘的赢。
+- 新条目固定插在最前，不按时间戳重排。补录一条旧时间的观察，它会出现在最上面。
+
+设计文档：`docs/superpowers/specs/2026-08-26-creator-channel-registry-design.md`。
+
+## 参考文件
+
+| 文件 | 用途 |
+|------|------|
+| `scripts/roster_locate.py` | 定位 roster launcher（跟 manage-roster 同款，独立副本） |

package/skills/feed/capture-creator/scripts/roster_locate.py

@@ -0,0 +1,46 @@
+"""定位 roster launcher（跟 browser_fetch_locate.py 同款，独立副本）。
+
+两种布局：
+- Dev 模式：本 skill 跑在 harveyz-skill 的 checkout 里，
+  tools/roster/roster.sh 在 scripts/ 上面四层。
+- 装机模式：经 hskill install 装到 ~/.claude/skills 等处，roster 作为 tool
+  单独安装，launcher 落在 ~/.local/bin/roster。
+"""
+import shutil
+import sys
+from pathlib import Path
+
+
+def _dev_path() -> Path:
+    return Path(__file__).resolve().parents[4] / "tools" / "roster" / "roster.sh"
+
+
+def find_roster() -> str:
+    dev = _dev_path()
+    if dev.exists():
+        return str(dev)
+
+    on_path = shutil.which("roster")
+    if on_path:
+        return on_path
+
+    installed = Path.home() / ".local" / "bin" / "roster"
+    if installed.exists():
+        return str(installed)
+
+    raise FileNotFoundError(
+        "roster launcher 未找到。请在 harveyz-skill 的 checkout 里运行本 skill，"
+        "或运行 `hskill install --tool roster`。"
+    )
+
+
+def main():
+    try:
+        print(f"FOUND: {find_roster()}")
+    except FileNotFoundError as e:
+        print(f"NOT_FOUND: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/feed/manage-roster/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: manage-roster
+version: "0.1.1"
+description: "Maintain the roster of watched creators and their channels — the shared watchlist behind sync-xtimeline and sync-ytchannel. Add a channel URL, merge two handles that turn out to be the same person, rename a placeholder, view the roster with cursor state. Trigger phrases: '/manage-roster add <url>', '/manage-roster list', '/manage-roster merge <a> <b>', '/manage-roster rename <id> <name>', '/manage-roster remove <id>', 'watch this X account', 'watch this YouTube channel', 'who am I following'. Does not fetch anything — running an incremental fetch is sync-xtimeline / sync-ytchannel; writing a creator's profile is the cognition layer."
+user_invocable: true
+---
+
+# manage-roster
+
+维护"关注了哪些人、每个人有哪些渠道"这份名册。抓取本身不归它管——`sync-xtimeline` 和 `sync-ytchannel` 从这份名册读渠道列表去抓。
+
+**渠道必属于一个人。** 机构号、聚合频道也当人处理。`add` 会自动建一个占位人（名字先用 handle 顶着），之后用 `merge` 把"这俩 handle 其实是同一个人"合起来。
+
+**这个 skill 只写 `registry.json`。** 游标归抓取层写，画像归认知层写，它一概不碰。
+
+## 初始化（run first）
+
+```bash
+python3 scripts/roster_locate.py
+```
+
+若输出 `NOT_FOUND: <error>`（exit 1），向用户报告"roster tool 未安装：{error}"，流程终止。
+
+若输出 `FOUND: <path>`，检查配置：
+
+```bash
+ls ~/.hskill/roster/config.json 2>/dev/null && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+**若 `NOT_FOUND`：**
+
+1. 询问用户名册数据要存在哪个目录（`DATA_DIR`，必须由用户手动提供，不得猜测）。可建议默认值 `~/.hskill/roster`。提醒用户：这个目录里的画像文件是累积出来的、删了长不回来，值得跟笔记一样对待（`registry.json` 和 `state.json` 都可重建，画像不能）。
+2. 运行 `<roster_path> init <DATA_DIR>`。
+
+**若用户此前用过 sync-xtimeline / sync-ytchannel**，初始化后问一次是否迁移旧关注列表：
+
+```bash
+<roster_path> migrate \
+  --from-xtimeline "$(python3 -c "import json,pathlib;print(pathlib.Path(json.loads((pathlib.Path.home()/'.hskill/sync-xtimeline/config.json').read_text())['DATA_DIR']).expanduser()/'watchlist.json')")" \
+  --from-ytchannel "$(python3 -c "import json,pathlib;print(pathlib.Path(json.loads((pathlib.Path.home()/'.hskill/sync-ytchannel/config.json').read_text())['DATA_DIR']).expanduser()/'watchlist.json')")"
+```
+
+任一旧配置不存在就省掉对应的参数。迁移是幂等的，重复跑安全。迁移后告诉用户：每个 handle 现在各自是一个人，同一个人的 X 和 YouTube 需要用 `merge` 合并，并主动列出名字相近的候选对给用户确认——**不要自己替用户合并**。
+
+## 用法
+
+`<roster>` 指 `roster_locate.py` 输出的路径。
+
+| 用户说 | 运行 | 报告 |
+|---|---|---|
+| `add <url>` | `<roster> registry add <url>` | `OK <id> <platform>:<handle>` → 告知已加入，并提示这是占位人、可用 `rename` 填正式名字 |
+| `list` | `<roster> registry list` | 原样展示。`EMPTY` 表示还没关注任何人 |
+| `merge <a> <b>` | `<roster> registry merge <a> <b>` | `OK merged b into a` → 告知 b 的 id 已进 aliases，旧引用仍可查到 |
+| `rename <id> <name>` | `<roster> registry rename <id> <name>` | `OK` |
+| `remove <id>` | `<roster> registry remove <id>` | 输出里带画像归档路径时，**必须把这个路径转告用户**——画像没被删，只是移走了 |
+| `remove <platform>:<handle>` | `<roster> registry remove <platform>:<handle>` | `OK removed ...`。人还留着 |
+
+所有失败原样把 stderr 报给用户，不要自行改写或重试。
+
+## 边界
+
+不抓取、不翻译、不写画像、不进 Obsidian。跑一次增量抓取走 [sync-xtimeline](../sync-xtimeline/) 或 [sync-ytchannel](../sync-ytchannel/)。单条物料入库走 [clip-url](../../research/clip-url/)，单个视频精读走 [learn-video](../../research/learn-video/)。
+
+设计文档：`docs/superpowers/specs/2026-08-26-creator-channel-registry-design.md`。
+
+## 参考文件
+
+| 文件 | 用途 |
+|------|------|
+| `scripts/roster_locate.py` | 定位 roster launcher（跟 `browser_fetch_locate.py` 同款，独立副本） |

package/skills/feed/manage-roster/scripts/roster_locate.py

@@ -0,0 +1,46 @@
+"""定位 roster launcher（跟 browser_fetch_locate.py 同款，独立副本）。
+
+两种布局：
+- Dev 模式：本 skill 跑在 harveyz-skill 的 checkout 里，
+  tools/roster/roster.sh 在 scripts/ 上面四层。
+- 装机模式：经 hskill install 装到 ~/.claude/skills 等处，roster 作为 tool
+  单独安装，launcher 落在 ~/.local/bin/roster。
+"""
+import shutil
+import sys
+from pathlib import Path
+
+
+def _dev_path() -> Path:
+    return Path(__file__).resolve().parents[4] / "tools" / "roster" / "roster.sh"
+
+
+def find_roster() -> str:
+    dev = _dev_path()
+    if dev.exists():
+        return str(dev)
+
+    on_path = shutil.which("roster")
+    if on_path:
+        return on_path
+
+    installed = Path.home() / ".local" / "bin" / "roster"
+    if installed.exists():
+        return str(installed)
+
+    raise FileNotFoundError(
+        "roster launcher 未找到。请在 harveyz-skill 的 checkout 里运行本 skill，"
+        "或运行 `hskill install --tool roster`。"
+    )
+
+
+def main():
+    try:
+        print(f"FOUND: {find_roster()}")
+    except FileNotFoundError as e:
+        print(f"NOT_FOUND: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()