skill-flow 1.0.2 → 1.0.4

package/docs/PRD/renew/PRD-0.0.0.md

@@ -1,26 +0,0 @@
-下方【需求】是我想要完成的一个项目，请你以【项目人员】的三个视角来拆解分析这个项目，最终的产出是一份极尽清晰的 PRD 文档，首先你会以三个人的视角完成多轮网络检索将所需的相关资料收集齐全后，再开始进行讨论和编写文档，请不要吝啬算力全力以赴完成任务。
-
-【项目人员】
-1. Martin Fowler
-负责：领域建模、系统边界、spec、兼容策略
-2. Isaac Z. Schlueter
-负责：包管理核心、版本/安装/更新/锁定机制
-3. Mitchell Hashimoto
-负责：CLI、插件体系、开发者体验、可扩展工具化
-
-【需求】
-我想要做一个 skills 管理器，目前 skills 来源不同（可能来自于 GITHUB、Clawhub 等各种第三方 Skills 托管平台），并且 skills 去向也不同，本地可能安装了 openclaw （.openclaw/workspace/skills/） opencode(.config/opencode/skills) codex(.codex/skills/)  claude code(.claude/skills/) 或者还有通用目录 .agents/skills/.
-并且目前 skill 放置时都是一个一层结构放置，但是很多 github 来源的 skills 都是一个仓库提取多个组合 skills，用于一些列的工作流，其实两层结构会比较合理。
-
-接下来我想要开发一个可以统一集合管理所有 skills 的命令行工具，目前暂时只支持 mac，名称为 skill-flow，启动命令为 skill-flow , 相关数据存放路径为 .skillflow/；
-
-- 下载：可以自己搜索下载相关 skills, 统一安装到 .skillflow/source 中，其中按照原始数据方式存储，若为 github 仓库则直接下载仓库代码；若不为 github 仓库若可以获知作者名称，则按照作者名称命名文件夹放置；若无法按照以上信息创建文件夹，则使用 single 作为文件夹名称放置其中，之后下载成功后，可以统一扫描符合 skill 结构的文件夹，使用文件链接的方式导入到 .skillflow/skills/ 文件夹下。
-- 更新：按照原始下载来源，考虑不同的更新方式，github 仓库直接拉取最新代码更新即可。
-- 管理：执行 skill-flow config 命令时，显示所有可以配置 skills 的渠道，可以在程序中固化扫描是否存在 codex/ claude code/ opencode/ openclaw ...等目录存在，然后执行 config 时展示可以配置的渠道，然后，有用户选择渠道或者全部（all channel）配置，选择完成后到下一步选项，列出之前在 source 中的一级目录名称（仓库名/作者名/single 要逐一列出 skill），多选框，用户使用空格选择，使用 tab 可以打开一级目录的二级目录（skill 本体 / single 因为打开的就是 skill 就没有二级目录）然后就是在二级目录中进行选择，选择完成最后按 回车可以回答一级目录，一级目录应该有三种状态 未选择 / 部分选择 / 全部选择。然后按回车保存。就是对于该渠道应用所选 skill，这些 skill 会以文件链接的方式放置到目标渠道的文件夹中。
-- 卸载：执行 skill-flow uninstall 同样列出一级目录，由用户使用多选后点击回车卸载所选一级目录。
-(可能还有其他)...
-
-可参考项目：
-- https://github.com/farion1231/cc-switch/tree/main
-- https://github.com/vercel-labs/skills
-- https://github.com/farion1231/cc-switch

package/docs/PRD/renew/PRD-0.0.1.md

@@ -1,408 +0,0 @@
-# skill-flow PRD
-
-**文档信息**  
-- 产品名称：skill-flow  
-- 启动命令：`skill-flow`  
-- 支持平台：macOS（MVP 限定）  
-- 数据根目录：`~/.skillflow/`（下文用 *SM_HOME* 指代）  
-- 目标：把来自不同来源（如 Git 仓库、ClawHub 等）的 Agent Skills 统一下载、解析、索引、版本锁定，并按用户选择分发到不同本地“渠道”（Claude Code / Codex / OpenCode / OpenClaw / 通用目录等），同时兼顾“单仓多技能”的两层结构管理。
-
-## 背景与调研结论
-
-当前“Agent Skills”生态已经在格式上趋于统一：**一个 Skill 是一个目录，至少包含 `SKILL.md`，通常还会带 `scripts/`、`references/`、`assets/` 等可选内容**。citeturn6view0turn2view1turn29view3 这一点决定了“单仓多技能”非常自然：一个仓库（Source）可能包含多个 skill 目录，工具需要能 **“按仓库为一组”** 下载与更新，同时 **“按 skill 为单位”** 分发与启用。citeturn20view2turn6view0
-
-不同本地工具对 Skills 的**查找路径**与**优先级**并不一致，是用户在多工具并用时管理成本暴涨的根因之一：
-
-- Claude Code：支持个人与项目级路径，且有清晰的优先级（enterprise > personal > project）；还支持从嵌套目录 `.claude/skills/` 自动发现，以适配 monorepo 的分包结构。citeturn2view3  
-- OpenCode：既支持自身的 `.opencode/skills` 与 `~/.config/opencode/skills`，也兼容 `.claude/skills` 与 `.agents/skills`；并且会从当前目录向上遍历到 git worktree 来加载项目级 skills。citeturn2view5  
-- OpenClaw：明确区分 bundled / `~/.openclaw/skills` / `<workspace>/skills` 三类来源，并定义了优先级；同时支持通过 `skills.load.extraDirs` 添加额外目录，但那是**最低优先级**。更关键的是：其安全策略会校验 realpath 是否落在配置 root 内，可能会影响“跨目录 symlink”的可行性。citeturn10view2  
-- Codex：文档描述其在 repo 与 user 级会扫描 `.agents/skills`，且明确表示**支持 symlink 并跟随 symlink 目标进行扫描**；同时允许通过 `~/.codex/config.toml` 的 `[[skills.config]]` 对某个 skill 路径做 enable/disable。citeturn16view1turn16view0  
-- 生态工具 `npx skills`（Vercel 开源）已经把“多 agent 安装路径映射”“symlink/复制两种安装方式”“更新检测与锁文件”等能力做成了一个通用 CLI，并且列出了对 Claude Code / Codex / OpenCode / OpenClaw 等多种 agent 的安装路径映射表。citeturn7view3turn7view1  
-
-因此，本项目的核心挑战不在于“定义技能文件格式”，而在于：**多来源（Source）→ 解析成技能单元（Skill）→ 以可追踪、可回滚的方式分发到多渠道（Channel）**，并处理每个 Channel 的兼容性差异与安全限制。citeturn6view0turn10view2turn16view0turn2view5  
-
-参考项目层面：  
-- `cc-switch`（桌面端一体化管理器）已经包含“从 GitHub repo 或 ZIP 一键安装 Skills、支持符号链接与文件复制”的实践，证明了“集中管理+分发”的用户需求与实现可行性。citeturn31view1  
-- `npx skills` 的实现细节显示：它维护一个全局 `.skill-lock.json`，位置遵循 XDG state 或回退到 `~/.agents/.skill-lock.json`；并用 GitHub Trees API 的树 SHA（`skillFolderHash`）做更新检测。citeturn23view0turn23view3  
-- 但 `npx skills` 的 issue 也揭示了 lockfile 迁移、project/global 双锁文件一致性等坑点，提示我们必须把“锁文件 schema 迁移、范围（scope）模型、以及恢复安装”当成一等公民设计。citeturn24view3turn23view0  
-- 同时，官方与社区都较强烈强调 Skills 的供应链安全：Claude 的官方文档明确提示“来自不可信来源的 Skills 可能导致数据外泄、未授权系统访问等风险，应当像安装软件一样审计”。citeturn29view1turn29view3 OpenClaw 与 skills.sh 也都在各自语境下提示“第三方 skills 视为不可信、安装前审计”。citeturn10view2turn26view3
-
-本 PRD 将用三位“项目人员”视角贯穿关键决策：  
-- entity["people","Martin Fowler","software engineer author"]：领域建模 / 边界 / spec / 兼容策略  
-- entity["people","Isaac Z. Schlueter","npm creator"]：包管理内核 / 安装更新机制 / 锁定策略  
-- entity["people","Mitchell Hashimoto","hashicorp cofounder"]：CLI / 插件体系 / DX / 可扩展工具化  
-
-## 目标、非目标与成功指标
-
-**目标（MVP）**  
-1) 在 macOS 上提供一个 CLI：`skill-flow`，把多来源 skills 下载到 *SM_HOME*，并解析出可管理的“技能清单”。  
-2) 支持至少两类来源：  
-- Git 仓库来源（优先覆盖 entity["company","GitHub","code hosting platform"] 上的 repo，但实现层面应支持任意 git URL）。citeturn20view1turn30search2  
-- ClawHub 来源（作为 OpenClaw 的公共技能注册表与 CLI 工作流）。citeturn10view0turn10view2  
-3) 支持至少五类渠道（Channel）分发：Claude Code / Codex / OpenCode / OpenClaw / 通用 `.agents/skills`，并在 `skill-flow config` 中自动探测哪些渠道“可配置”。citeturn2view3turn16view1turn2view5turn10view2  
-4) 支持“单仓多技能”的两层交互：以 Source 为一级，以 Skill 为二级；并实现你描述的**树状多选 TUI**（Space 选中、Tab 展开/收起二级、一级有三态：未选/部分/全选）。  
-5) 分发方式默认优先“文件链接（symlink）”，但必须根据渠道限制提供“copy/配置注入”等兼容策略（详见后文）。citeturn7view1turn10view2turn16view0  
-
-**非目标（MVP 不做）**  
-- 不在本工具中执行/运行 skill 脚本、也不解释 skill 内部逻辑；skill-flow 只做“获取、索引、分发、清理”。（理由：安全与边界清晰，避免成为“运行时”。）citeturn29view1turn10view2  
-- 不承诺实现所有生态的 agent 路径映射（只覆盖你列出的核心渠道；其余留给插件扩展）。citeturn7view3  
-- 不提供 GUI（MVP 仅 CLI/TUI）。  
-
-**成功指标（建议）**  
-- 新用户从 0 到“在至少 2 个渠道可用”的时间：< 3 分钟。  
-- 更新可靠性：对 GitHub/ClawHub 来源更新后，`config` 重新应用能在所有已选渠道完成一致分发；失败时保证可恢复（不产生半配置状态）。  
-- 可审计性：任何一次安装/更新/分发都能在本地生成可追溯记录（来源、版本/commit/hash、分发到哪些渠道、采取了 symlink 还是 copy）。  
-- 安全提示覆盖：对“来自未知来源”的安装提供默认审计提示与风险标记，且提供 `--yes` 逃生舱但默认不静默。citeturn29view1turn10view2turn26view3  
-
-## 领域模型与系统边界
-
-（Martin 视角：先把“名词/边界/不变量”钉死，再谈交互与实现。）
-
-**核心概念（Domain）**  
-- **Skill**：符合 Agent Skills 规范的一个目录，最小包含 `SKILL.md`；其 `SKILL.md` 必须包含 YAML frontmatter + Markdown body。citeturn6view0turn29view3  
-- **SkillName（规范化名称）**：默认以 `SKILL.md` frontmatter 的 `name` 字段为准，并要求与父目录名一致（Agent Skills spec）。citeturn6view0  
-  - 额外约束：Claude 的官方文档还对 name/description 给出更严格的限制（如 reserved words、XML tags 等），这在验证器里应作为“可选严格模式”。citeturn29view3  
-- **Source**：一个“可更新的上游单位”，例如一个 git 仓库、一个 ClawHub slug、或一个支持 `.well-known/skills/index.json` 的网站（后者用于未来扩展）。citeturn10view0turn4view0turn26view0  
-- **SourceSnapshot**：某个 Source 在本地落地时的“版本快照”，例如 git commit、ClawHub semver、或基于文件列表/etag 的内容哈希。citeturn12view2turn23view3turn26view0  
-- **Channel**：一个“技能投放目的地”，本质是（路径 + 规则 + 约束）。例如：`~/.config/opencode/skills`、`~/.openclaw/skills`、`.claude/skills` 等。citeturn2view5turn10view2turn2view3  
-- **Deployment**：一次“把一组 Skills 应用到一个或多个 Channel”的操作结果（包含策略：symlink/copy/配置注入）。  
-- **Index（技能索引）**：skill-flow 对 `SM_HOME/source` 的扫描结果，形成 “Source → Skills[]” 的二层树，用于 UI 展示与分发。  
-
-**系统边界（System Boundary）**  
-- 输入：用户指定的 Source（repo URL/slug/搜索关键词）、本机已有的 channel 目录、以及用户在 TUI 中选择的“要分发的 skill 列表”。  
-- 输出：  
-  - `SM_HOME/source/`：按“原始数据方式”保存上游内容（git repo 就是 repo 代码；ClawHub 就是下载的 bundle；网页来源就按 index.json 规则下载文件）。citeturn10view0turn4view0turn30search2  
-  - `SM_HOME/skills/`：可被分发的“技能入口集合”，本质上是指向 source 内部 skill 目录的链接（ideal），或在需要时生成 copy。  
-  - 每个 Channel 的目标目录：放置最终可被目标 agent 发现的 skill 目录（一般是 symlink 或 copy 目录）。citeturn7view1turn2view3turn16view0turn10view2  
-- 明确不做：执行脚本、改写 SKILL.md 内容、对 skill 行为做 sandbox。安全只做“提示、校验、隔离策略建议”。citeturn29view1turn10view2  
-
-**兼容性不变量（很关键）**  
-- “技能入口”必须最终呈现为“目录 + `SKILL.md`”，否则 Claude/OpenCode/OpenClaw/Codex 都不会识别。citeturn6view0turn2view5turn10view2turn16view1  
-- 某些渠道对 symlink 的行为存在差异：  
-  - Codex 明确支持 symlink 并跟随目标扫描。citeturn16view0  
-  - Claude Code 曾出现 `/skills` 命令不跟随 symlink 的 bug（技能可用但列表显示“无技能”），意味着“symlink 分发”需要配套 UX 提示/doctor 检查。citeturn19view1  
-  - OpenClaw 对 realpath 的安全校验可能会拒绝指向 root 外的 symlink，这会直接影响“中心化目录→workspace/skills 的 symlink”路径方案。citeturn10view2  
-
-## 核心用户体验与命令行交互
-
-（Mitchell 视角：CLI 是产品本体；信息架构、命令语义、可脚本化与 DX 要从第一天就对齐。）
-
-### 命令总览（建议）
-
-MVP 至少包含以下命令族（命令名可按你偏好微调，但建议与“包管理器语义”一致）：
-
-- `skill-flow add <source>`：下载/注册一个 Source，并触发扫描索引。  
-- `skill-flow search <query>`：搜索可用 skills（初期可只提供：ClawHub 搜索 + GitHub repo 搜索/快捷输入；后续扩展到 skills.sh 或 `.well-known`）。citeturn10view0turn26view3turn4view0  
-- `skill-flow update [--all | <sourceId>]`：按 Source 类型更新本地快照（git pull / ClawHub update / 重新抓取 index.json），并重建索引。citeturn30search12turn12view3turn23view3  
-- `skill-flow config`：以 TUI 方式选择 Channel → 再选择 Source/Skill 树 → 应用分发策略（symlink/copy/配置注入），并持久化到 SM_HOME。  
-- `skill-flow uninstall`：卸载某个 Source（以及它的 skills 索引与已分发结果）。  
-- `skill-flow list`：输出当前已注册 Source、解析到的 Skills，以及它们的分发状态（适合 `--json`）。  
-- `skill-flow doctor`：检查各 Channel 是否可用、路径是否存在、symlink 是否可解析、OpenClaw realpath 约束是否可能拦截、是否存在技能名冲突等。citeturn10view2turn19view1turn16view0  
-
-### `skill-flow config` 交互流程（按你的描述落地）
-
-**Step A：探测可配置渠道（Channel Discovery）**  
-程序启动时扫描以下路径是否存在（存在则视为“可配置”；不存在则不展示或标为“未安装/不可用”）：
-
-- Claude Code：`~/.claude/skills/`（个人）与当前项目 `.claude/skills/`（项目级；仅当在 repo 内运行时才有意义）。citeturn2view3  
-- Codex：优先探测 `~/.agents/skills/`（user 级，文档推荐）；同时可探测 `~/.codex/skills/`（兼容生态工具映射与历史路径），并在 UI 里标注“兼容路径”。citeturn16view1turn20view2turn14view2  
-- OpenCode：`~/.config/opencode/skills/`（global）；也可选 `.opencode/skills/`（project）与 `.agents/skills`（兼容），但 MVP 可以只做 global。citeturn2view5  
-- OpenClaw：`~/.openclaw/skills`（shared）与 `<workspace>/skills`（per-agent workspace；需要探测默认 workspace 或让用户配置 workspace 路径）。citeturn10view2turn8view0  
-- 通用：`~/.agents/skills/`（很多工具和 OpenCode/Codex 都会扫描或兼容这一路径）。citeturn2view5turn16view1  
-
-**Step B：选择渠道**  
-`config` 第一屏展示 “检测到的渠道列表”，支持：  
-- 单选/多选（space 切换），并提供 `all channels`。  
-- 每个渠道展示其目标路径与关键约束提示（例如 OpenClaw 的 realpath 限制、Claude Code 的 `.system/` 共存要求等）。citeturn10view2turn18view0  
-
-**Step C：选择 Source（一级目录）并支持展开 Skill（二级）**  
-第二屏以 “Source 一级目录” 作为主树节点，显示 `SM_HOME/source` 下的一级目录名称（你定义的：仓库名/作者名/single）。  
-- Space：切换一级节点选中（全选/全不选）。  
-- Tab：展开该 Source，进入二级 skill 列表（扫描得到的 skill roots）。  
-- 二级列表 Space 多选；完成后 Enter 返回一级列表。  
-- 一级节点需要三态：  
-  - 未选择（0/全部）  
-  - 部分选择（n/全部）  
-  - 全部选择  
-
-这个交互设计与 `npx skills add` 的多选安装体验一致（同类心智模型），但你这里额外需要“树状二级展开与三态”，属于你产品的差异化重点。citeturn2view0turn7view5  
-
-**Step D：应用并保存**  
-用户在一级界面按 Enter 触发保存：  
-- 生成或更新“渠道配置映射”（Channel ↔ Skills 选择集）。  
-- 立刻执行分发（symlink/copy/配置注入）。  
-- 写入 SM_HOME 的状态文件（manifest/lock/deployments）。  
-
-### `skill-flow uninstall` 交互流程（按你的描述落地）
-
-- 列出 Source 一级目录，多选后 Enter。  
-- 卸载定义（建议明确）：  
-  1) 从所有已配置 Channel 中移除该 Source 贡献的 skills（删除 symlink 或删除 copy 目录）；  
-  2) 从 `SM_HOME/skills` 的索引入口移除；  
-  3) 可选：是否同时删除 `SM_HOME/source/<sourceId>` 的原始下载（默认删除，但提供 `--keep-source`）。  
-
-这里建议把“解绑（unlink from channels）”与“删除本地缓存（remove source）”拆成两个子选项，以减少误删。  
-
-## 包管理内核：下载、解析、锁定与更新
-
-（Isaac 视角：把 Source 当作 package，把 Skill 当作 installable unit；锁定/更新/回滚要像包管理器一样确定。）
-
-### Source 支持矩阵（MVP + 扩展位）
-
-MVP 建议实现 3 类 Source Adapter（为未来插件留接口）：
-
-1) **git 仓库（GitHub 只是其中之一）**  
-- 输入：`owner/repo`、HTTPS URL、SSH URL、本地路径。citeturn20view1turn30search2  
-- 落地：`SM_HOME/source/<sourceId>/` 为一个可 `git pull` 的工作区。citeturn30search12  
-- 更新：`git fetch` + fast-forward（或用户指定 rebase/merge 策略）。citeturn30search12  
-
-2) **ClawHub（OpenClaw registry）**  
-- ClawHub 是公开技能注册表，提供 CLI 搜索、安装、更新、发布；具备 semver 版本与 tags（如 `latest`），并可按版本下载 zip。citeturn10view0turn12view2  
-- MVP 实现策略建议二选一：  
-  - **A（更快交付）**：直接 shell-out 调用 `clawhub` CLI 完成下载与更新（并读取其 `.clawhub/lock.json` 作为 SourceSnapshot）。citeturn12view3turn12view4  
-  - **B（更可控）**：直接对 registry API 拉取 zip，并用 skill-flow 自己的 lockfile 记版本。  
-
-3) **Well-known Skills Discovery（可作为扩展位，但建议纳入设计）**  
-- Cloudflare 的 RFC 定义：发布者可在 `/.well-known/skills/index.json` 提供技能索引，客户端据此抓取每个 skill 的文件列表。citeturn4view0  
-- Mintlify 已宣布其文档站点支持这个标准，并展示了“对任意 URL 一键安装技能”的工作流，这为未来“非 GitHub/非 ClawHub 的第三方平台”提供了统一入口。citeturn26view0  
-
-### Skill 解析与索引（from source → skills tree）
-
-**扫描规则（建议）**  
-- 默认递归扫描 `SM_HOME/source/<sourceId>`：找出所有满足“目录内存在 `SKILL.md`”的目录。citeturn6view0turn2view1  
-- 与 `npx skills` 类似，可额外对常见布局做启发式加速：优先扫描 `skills/`、`skills/.curated/`、`.claude/skills/`、`.agents/skills/` 等目录。citeturn7view3  
-- 对每个候选 skill：解析 `SKILL.md` frontmatter，至少校验 `name` 与 `description` 的存在与约束（Agent Skills spec）。citeturn6view0  
-- 生成索引条目：  
-  - `skillId`（全局唯一）：建议采用 `sourceId + ":" + normalizedName`，避免同名 skill 来自不同来源发生覆盖（这也是 `npx skills` lockfile 曾经暴露的真实问题）。citeturn21search11turn24view3  
-  - `displayName`：默认用 `name`，但允许覆盖。  
-  - `skillRootPath`：指向 `SM_HOME/source/...` 内的真实目录路径。  
-
-**两层结构落地（满足你的“source 一级 / skill 二级”需求）**  
-- `SM_HOME/source/<sourceKey>/...`：保持“原始结构”不动。  
-- `SM_HOME/skills/<sourceKey>/<skillName>/`：用 link（或 copy）指向 source 内部的 skill root，形成“可分发集合”。  
-
-> 注意：OpenClaw 的 realpath 校验意味着“在 OpenClaw workspace 下放一个 symlink 指向 SM_HOME/skills 再指向 source”的多级 symlink 可能更容易触发安全拦截；因此在部署到 OpenClaw 时，要么 copy，要么把真实文件放在其允许的 root 内（详见后文）。citeturn10view2  
-
-### 锁定机制（Lockfile / Manifest）
-
-**为什么需要“锁定”**  
-- ClawHub 本身把“已安装技能”记录在 `.clawhub/lock.json`，并使用内容哈希对比来决定是否覆盖本地修改。citeturn12view4  
-- `npx skills` 则维护 `.skill-lock.json`，并用 `skillFolderHash`（GitHub tree SHA）做 update check；同时其 issue 显示：锁文件版本迁移与 project/global scope 的设计如果不清晰，会直接导致“更新检查失效”乃至“条目被静默清空”。citeturn23view0turn23view3turn24view3  
-
-**skill-flow 的建议文件**（MVP 至少 2 个）  
-1) `SM_HOME/manifest.json`（意图层）  
-- 记录用户“想要什么”：Sources 列表、每个 Source 的命名策略（repo/author/single）、每个 Channel 选择了哪些 skills（按 skillId）。  
-2) `SM_HOME/lock.json`（解析层）  
-- 记录“解析结果与可重建信息”：  
-  - SourceSnapshot：  
-    - git：remote URL、branch、commit SHA  
-    - ClawHub：slug、version、tag（如 latest）、以及可选 content hash  
-    - well-known：base URL、index.json hash、每个文件的 hash/etag  
-  - skills：skillId → { skillRootRelativePath, normalizedName, discoveredAt, contentHash(optional) }  
-  - deployments：Channel → { strategy, appliedAt, entries[] }  
-
-**锁文件迁移原则（吸取经验）**  
-- **绝不在升级时静默清空**（`npx skills` 相关 issue 已证明这会造成“工具看起来可用但更新机制失效”）。citeturn24view3turn23view0  
-- schema 升级必须：  
-  - 先备份旧 lock；  
-  - 尽可能做迁移；  
-  - 无法迁移时必须输出明确告警并要求用户确认。  
-
-### 更新机制（Update）
-
-**GitHub/git sources**  
-- `update`：对 `SM_HOME/source/<sourceId>` 执行 `git pull`（或 fetch+reset），更新工作区。citeturn30search12  
-- `rescan`：重新跑一次 skills discovery；对新增/删除/改动的 skill 目录更新索引；必要时更新 Channel 中的分发。  
-
-**ClawHub sources**  
-- `update`：可对某个 slug 更新或 `--all` 更新，并支持 `--version` 指定版本。citeturn12view3  
-- 注意本地修改：ClawHub 文档说明其会用内容 hash 对比 registry 版本，不匹配时需要 `--force` 才覆盖；skill-flow 若采用 shell-out，需要把这个行为对齐并在 UI 中提示“本地已修改/可能覆盖”。citeturn12view4  
-
-**更新检测（Check）**  
-- 可借鉴 `npx skills`：对 GitHub 源使用 Trees API 的 tree SHA 来快速判断目录是否变化，并用 token（`GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token`）降低 rate limit 风险。citeturn23view3turn23view0  
-- 但 MVP 简化也可接受：git sources 先做拉取，再在本地 diff 出变更。  
-
-## 渠道适配与兼容策略
-
-（Martin：兼容策略是“产品承诺”；Isaac：分发策略会反过来影响锁定与更新；Mitchell：用户需要一眼看懂“为什么这个渠道只能 copy”。）
-
-### Channel 适配总原则
-
-- 默认策略：**symlink 分发**，以保持单一事实来源（SSOT）并让更新自动生效，这也是 `npx skills` 推荐的安装方式。citeturn7view1turn16view0  
-- 备选策略：**copy 分发**，用于：  
-  - 渠道不支持 symlink/或会因安全策略拒绝 symlink；  
-  - 用户明确要求“脱离中央目录，可离线独立存在”。citeturn7view1turn10view2  
-- 第三策略：**配置注入（指向额外目录）**，用于渠道本身支持“额外 skills 根目录”配置且 symlink/copy 都不理想的情况（OpenClaw 就属于候选）。citeturn10view2  
-
-### Claude Code 渠道
-
-**官方路径与优先级**：个人 `~/.claude/skills/<skill>/SKILL.md`，项目 `.claude/skills/<skill>/SKILL.md`；并且会对 monorepo 的嵌套 `.claude/skills/` 自动发现。citeturn2view3  
-
-**需要额外考虑的“目录共存”问题**  
-社区实践指出：Claude Code 的 `~/.claude/skills/` 往往会与 `.system/`、插件相关目录等共存，因此“把整个 `~/.claude/skills` 做成目录级 symlink”会让这些系统目录无处安放；更合理的是“保持 `~/.claude/skills` 为真实目录，并在其内为每个 skill 创建单独 symlink”。citeturn18view0  
-
-**symlink 的 UX 风险**  
-存在 `/skills` 命令不跟随 symlink 的历史 bug：技能实际可用，但列表显示 “No skills found”。因此 skill-flow 在 Claude Code 渠道需要：  
-- `doctor` 提示：如果用户依赖 `/skills` 列表做验证，应知道该风险；  
-- 或提供 `--copy`/copy 策略作为替代。citeturn19view1turn7view1  
-
-### Codex 渠道
-
-**官方扫描位置与行为**  
-- repo/user 级扫描 `.agents/skills`（从 CWD 向 repo root 多层扫描），并支持 symlink 且会跟随 symlink 目标。citeturn16view1turn16view0  
-- 允许在 `~/.codex/config.toml` 用 `[[skills.config]]` 针对某个 skill 路径设置 `enabled=false` 以禁用而不删除。citeturn16view0turn3search1  
-
-**路径兼容性策略（建议）**  
-由于生态工具与历史资料中同时存在 `~/.codex/skills` / `.codex/skills` 的路径说法（例如 Codex changelog 与 `npx skills` 的路径映射表都出现过这种映射），skill-flow 建议把 “Codex 渠道”拆成两个子渠道：  
-- `codex-agents`：`~/.agents/skills`（官方文档优先）citeturn16view1  
-- `codex-legacy`：`~/.codex/skills`（兼容生态工具/历史）citeturn14view2turn20view2  
-
-这样可以在不赌未来变动的前提下，给用户明确选择与迁移路径。
-
-### OpenCode 渠道
-
-OpenCode 明确列出其 skills 查找路径：  
-- `.opencode/skills/<name>/SKILL.md`（project）  
-- `~/.config/opencode/skills/<name>/SKILL.md`（global）  
-- 以及 Claude-compatible / Agent-compatible 的 `.claude/skills` 与 `.agents/skills`（project+global）。citeturn2view5  
-
-并且它会从当前目录向上遍历到 git worktree，加载沿途遇到的这些项目级 skills。citeturn2view5  
-
-**MVP 建议**  
-- 默认以 global `~/.config/opencode/skills` 作为 OpenCode 渠道投放目标（与你需求一致）。  
-- 进阶选项（后续迭代）：支持 project root 下的 `.opencode/skills`，并与 `config` 命令的“当前工作目录”绑定。  
-
-### OpenClaw 渠道
-
-**官方位置与优先级**  
-- Bundled skills（最低）  
-- `~/.openclaw/skills`（managed/local）  
-- `<workspace>/skills`（最高）  
-并可通过 `skills.load.extraDirs` 加额外目录（最低优先级）。citeturn10view2  
-
-**关键安全约束：realpath 校验**  
-OpenClaw 文档指出：workspace 与 extra-dir 的 skill discovery 仅接受“其 resolved realpath 落在配置 root 内”的 skill roots 与 `SKILL.md`。这很可能意味着“把 `<workspace>/skills/my-skill` symlink 到 `~/.skillflow/...`”会被拒绝（因为 realpath 落在 root 外）。citeturn10view2  
-
-**因此，OpenClaw 渠道必须是多策略**  
-- 默认策略（推荐）：**copy 到 `<workspace>/skills`**（最高优先级，且满足 realpath）。  
-- 可选策略 A：copy 到 `~/.openclaw/skills`（shared，对多 agent 可见）。citeturn10view2  
-- 可选策略 B：配置注入 `skills.load.extraDirs` 指向 `SM_HOME/skills`（但它是最低优先级，并且需要改 `~/.openclaw/openclaw.json`，属于“显式授权”操作）。citeturn10view2  
-
-同时，OpenClaw workspace 默认位置与性质也要纳入 doctor：有资料指出 `~/.openclaw/workspace` 本身是一个 git repo，直接把 workspace 纳入 dotfiles 管理可能带来 submodule 等副作用。citeturn8view0  
-
-### 通用 `.agents/skills` 渠道
-
-这个渠道的价值在于：  
-- Codex 会扫描 `$HOME/.agents/skills`（user 级）与 repo 内 `.agents/skills`（repo 级）；citeturn16view1  
-- OpenCode 也会把 `.agents/skills` 视作 agent-compatible 路径加载；citeturn2view5  
-- 生态工具与文档也逐渐把它当作“SSOT 约定点”（社区实践与 `npx skills` 的设计倾向都是往这里收敛）。citeturn18view0turn23view0  
-
-因此 skill-flow 可把 `.agents/skills` 作为**默认分发渠道**之一：即使用户不选具体工具渠道，也能让兼容该规范的工具“自动吃到技能”。
-
-## 数据存储、错误处理与安全
-
-### SM_HOME 目录结构（建议）
-
-满足你“source 原始存储、skills 链接导入、统一配置”的需求，并引入包管理最小必要状态：
-
-```text
-~/.skillflow/
-  source/                 # 原始下载（git clone、ClawHub bundle、well-known 拉取内容）
-    <sourceKey>/
-  skills/                 # 解析后的技能入口集合（建议按 sourceKey 分组）
-    <sourceKey>/
-      <skillName>/ -> ../../source/<sourceKey>/.../<skillRoot>
-  state/
-    manifest.json         # 用户意图：sources、channel 选择、策略
-    lock.json             # 解析快照：commit/version/hash、索引、deployments
-    history.log           # 可审计日志（文本或 ndjson）
-  tmp/                    # 下载/解压临时目录（失败可清理）
-  cache/                  # （可选）远端索引缓存、etag 等
-```
-
-同时保留你需求里的核心：`source/` 与 `skills/`。  
-
-### SourceKey 命名规则（解决冲突）
-
-你希望一级目录是“仓库名/作者名/single”，但从工程视角必须避免冲突（两个不同 owner 的同名 repo、或 author 重名等）。建议采取“双层命名”：
-
-- **展示名（UI）**：`owner/repo` 或 `author/name` 或 `single/<hash>`  
-- **目录名（磁盘）**：`<type>__<stable-id>`，例如：  
-  - `gh__vercel-labs__agent-skills`  
-  - `clawhub__some-skill-pack`  
-  - `url__example.com__skills`  
-
-这样既能满足 UI 的“一级列表清晰”，也避免磁盘冲突。  
-
-### 失败处理（Atomicity）
-
-- git 更新失败：保持旧工作区不变（仅当 `git pull` 成功才更新 lock）。citeturn30search12  
-- 分发失败：对每个 Channel 采用“先在临时目录构建，再原子替换/逐项落盘”的策略：  
-  - symlink：先创建新 symlink（若同名存在则按策略备份/替换），全部成功后再写入 state。  
-  - copy：先复制到 `tmp/channel/<skill>`，校验 `SKILL.md` 存在后再移动到目标。  
-- lockfile 写入失败：不应影响实际落盘，但必须输出明确告警并建议运行 `doctor`。  
-
-### 安全与供应链（必须硬指标化）
-
-**策略来源（事实依据）**  
-- Claude 官方文档把 Skills 明确视作“包含指令与代码的能力扩展”，并建议对不可信来源做彻底审计，警惕外部 URL 拉取引入的风险、工具滥用与数据外泄，并强调“像安装软件一样对待”。citeturn29view1turn29view3  
-- OpenClaw 同样提示第三方 skills 不可信，并建议 sandboxed runs；同时其 discovery 的 realpath 限制就是一种防止路径穿越/越界加载的安全机制。citeturn10view2  
-- skills.sh 也承认无法保证所有技能质量，鼓励安装前审阅，并提到其排名依据匿名遥测、存在安全审计但不做绝对担保。citeturn26view3  
-
-**skill-flow MVP 的安全需求（可执行）**  
-1) **安装前风险提示**  
-- 对所有“非本地创建”的来源默认提示：技能可能包含脚本/外部依赖，建议审计。citeturn29view1turn10view2  
-- 若来源是“搜索结果安装”（search→add），默认要求二次确认（除非 `--yes`）。  
-
-2) **静态校验（不执行代码）**  
-- 校验 `SKILL.md` frontmatter（name/description）符合 Agent Skills spec；可选严格模式对齐 Claude 附加限制。citeturn6view0turn29view3  
-- 若 skill 包含 `scripts/`，标记为“可执行型 skill”，在 `list`/TUI 中显示风险图标。citeturn6view0turn29view3  
-
-3) **分发策略安全默认**  
-- OpenClaw 渠道默认 copy（避免 realpath 拦截与潜在绕过尝试）。citeturn10view2  
-- Claude Code 渠道默认“单 skill symlink”，并保留 `.system/` 等共存目录空间。citeturn18view0  
-
-4) **审计便利性**  
-- `skill-flow list --diff <sourceId>`：展示更新前后文件变更摘要（文件名/哈希变化），帮助人工审计。  
-- `skill-flow doctor --security`：检查是否存在“外部 URL 拉取型 skill”（例如 SKILL.md 指示中包含远端 fetch 的明显模式——这里只做弱提示，不做误报保证）。citeturn29view1  
-
-## 里程碑与开放问题
-
-### 里程碑（建议按 3 个迭代）
-
-**迭代一：基础骨架 + GitHub/git Source + 索引**  
-- 完成 SM_HOME 目录结构  
-- `add`（git clone）、`list`（source→skills 树）、`update`（git pull + rescan）citeturn30search2turn30search12  
-- skills 解析校验（Agent Skills spec）citeturn6view0  
-
-**迭代二：config TUI + 多渠道分发（Claude/OpenCode/Codex/通用）**  
-- 渠道探测（路径）与核心 TUI（一级三态/二级展开）  
-- symlink/copy 策略  
-- doctor：symlink 解析、冲突检测、Claude `/skills` symlink 展示提示citeturn19view1turn16view0  
-
-**迭代三：OpenClaw + ClawHub Source**  
-- OpenClaw 渠道适配（默认 copy + 可选 extraDirs 配置注入）citeturn10view2  
-- ClawHub Source（shell-out 方案优先交付），支持指定版本与 update --all，并把 `.clawhub/lock.json` 映射进 skill-flow lock。citeturn12view3turn12view4  
-
-### 开放问题（需要你做产品决策）
-
-1) **SM_HOME 的“默认位置”是否固定为 `~/.skillflow/`？**  
-你需求写的是 `.skillflow/`，但 CLI 用户通常期待遵循 XDG（类似 `npx skills` 对 lockfile 的处理）。citeturn23view0 你可以选择：  
-- 固定 home：简单、可预期；  
-- 支持 `skillflow_HOME`：更工程化，也利于 CI。  
-
-2) **Channel 的“作用域”要不要区分 global vs project？**  
-Codex/OpenCode/Claude 都支持 project 级路径，且有向上遍历规则；Codex 还会只在“trusted project”时读取 `.codex/config.toml`。citeturn15view0turn16view1turn2view5turn2view3  
-MVP 若只做 global，体验简单但覆盖不足；若引入 project scope，则需要“当前工作目录”语义与 manifest 结构升级。
-
-3) **“分发策略”是否允许用户按 Channel 覆盖？**  
-例如：Claude 用 symlink，OpenClaw 用 copy，Codex 用 symlink。Codex 明确支持 symlink，但 OpenClaw 可能不行。citeturn16view0turn10view2 这会影响 config UI 的信息密度与 lock 模型。
-
-4) **如何处理“同名 skill”冲突？**  
-Agent 端通常按 `name` 识别；当不同来源提供相同 `name`，生态工具与 lockfile 曾出现“同名覆盖/冲突”问题。citeturn21search11turn16view1  
-skill-flow 需要明确：  
-- 在 SM_HOME 内允许共存（skillId 唯一）；  
-- 在某个 Channel 内默认禁止同名同时启用（需要用户做选择），或采用命名空间策略（但这会偏离标准）。  
-
-5) **是否支持 “Well-known Skills Discovery” 作为第三类来源（提前留接口）？**  
-Cloudflare RFC + Mintlify 的落地说明，“从任意 URL 安装技能”会成为越来越主流的分发方式。citeturn4view0turn26view0 若你希望 skill-flow 不被锁死在 GitHub/ClawHub，建议在 Source Adapter 接口层提前保留这一类。