harveyz-skill 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ 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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "harveyz-skill",
-  "version": "0.28.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",
@@ -13,11 +14,11 @@
   "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/",
@@ -27,7 +28,8 @@
     "skills/research/probe-session/",
     "skills/research/pdf-math-translate/",
     "skills/research/clip-url/",
-    "skills/research/sync-xtimeline/",
+    "skills/feed/sync-xtimeline/",
+    "skills/feed/sync-ytchannel/",
     "skills/creative/capture-todo/",
     "skills/creative/capture-insight/",
     "skills/coding/init-workflow/",
@@ -57,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/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()

package/skills/feed/manage-roster/tests/test_roster_locate.py

@@ -0,0 +1,24 @@
+"""roster_locate 的两种布局：仓库 checkout 内 / hskill 装机后。"""
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import roster_locate
+
+
+def test_finds_launcher_in_repo_checkout():
+    """本测试就跑在 checkout 里，dev 路径必须命中真实文件。"""
+    found = Path(roster_locate.find_roster())
+    assert found.name == "roster.sh"
+    assert found.exists()
+
+
+def test_raises_when_nothing_found(monkeypatch, tmp_path):
+    monkeypatch.setattr(roster_locate, "_dev_path", lambda: tmp_path / "nope.sh")
+    monkeypatch.setattr(roster_locate.shutil, "which", lambda _: None)
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    with pytest.raises(FileNotFoundError, match="roster"):
+        roster_locate.find_roster()