skill-flow 1.0.2 → 1.0.4

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

@@ -1,1494 +0,0 @@
-# skill-flow PRD + 工程实施文档
-
-> 版本：v1.1  
-> 文档性质：定型版 PRD + 工程实施规范  
-> 产出方式：基于 Martin Fowler / Isaac Z. Schlueter / Mitchell Hashimoto 三人视角多轮讨论后收敛  
-> 平台：macOS（MVP）  
-> 启动命令：`skill-flow`  
-> 数据目录：`~/.skillflow/`
-
----
-
-# 一、三人多轮讨论纪要
-
-## 第一轮：先定边界，这到底是不是“包管理器”？
-
-### Martin Fowler
-“它不是一个下载器。下载只是入口。真正的产品边界应该是：`Source → SkillLeaf → Channel → Deployment`。只要这个边界不清，后面 `config`、`update`、`uninstall` 都会混成文件搬运。”
-
-### Isaac Z. Schlueter
-“如果没有锁定层，它就不是 manager，只是 installer。你一旦要支持多来源、多技能仓库、多渠道分发，就必须记录用户意图和解析结果，否则更新、回滚、恢复安装都不可靠。”
-
-### Mitchell Hashimoto
-“CLI 不是把能力堆成命令。真正的主流程只有一个：`add source -> inspect inventory -> choose channels -> apply deployments`。用户不该理解内部状态文件，但状态文件必须非常强。”
-
-### 本轮结论
-
-1. 产品正式定义为：**一个面向 Agent Skills 生态的 CLI 包管理器与渠道投影器**。
-2. 系统边界只负责：**获取、扫描、校验、索引、锁定、分发、更新、卸载、诊断**。
-3. 系统明确**不负责执行 skill**，也不对 skill 脚本做运行时沙箱承诺。
-4. 数据模型固定为：`Source / SourceSnapshot / SkillLeaf / Channel / Deployment / Manifest / Lock`。
-
----
-
-## 第二轮：Source 怎么建模，仓库和 skill 的关系是什么？
-
-### Martin Fowler
-“仓库不是 skill。仓库是 source root，skill 才是 leaf。否则你没法表达一个仓库里多个技能，也没法做你要的一级/二级树选择。”
-
-### Isaac Z. Schlueter
-“更新也必须以 source 为单位，而不是 skill 为单位。因为上游版本边界属于 source。你可以按 skill 选择是否部署，但不能按 skill 伪造上游版本。”
-
-### Mitchell Hashimoto
-“UI 上可以把 source 展示成一级目录，把 skill 展示成二级节点；但内部一定要有稳定的 `sourceId` 和 `skillId`，不能依赖展示名。”
-
-### 本轮结论
-
-1. **Source 是上游单位**：Git 仓库、ClawHub slug、未来的 well-known URL。
-2. **SkillLeaf 是可安装单位**：一个合法 skill root。
-3. **Source 与 SkillLeaf 是一对多关系**。
-4. “两层结构”正式进入领域模型，而不是只作为 UI 细节。
-5. internal id 与 display label 分离：
-   - internal：稳定、不可读也没关系
-   - display：仓库名 / 作者名 / `single`
-
----
-
-## 第三轮：Channel 不是路径字符串，而是适配器
-
-### Martin Fowler
-“Channel 必须是 adapter，不是 path。因为 Claude、OpenCode、Codex、OpenClaw 的发现规则、优先级、兼容路径、以及对 symlink 的容忍度都不一样。”
-
-### Isaac Z. Schlueter
-“同一个 leaf 投影到不同 channel，可以是不同 strategy。manager 的任务不是追求实现统一，而是追求状态统一。”
-
-### Mitchell Hashimoto
-“用户界面里可以看到都是‘一个目标’，但产品内部必须知道：Claude 默认是 per-skill symlink，OpenClaw 默认要 copy。”
-
-### 本轮结论
-
-正式把 Channel 定义为：
-
-- 一个**目标目录解析器**
-- 一个**发现规则集合**
-- 一个**分发策略集合**
-- 一个**诊断器**
-
-而不是一个简单路径。
-
----
-
-## 第四轮：锁文件要不要做成“一等公民”？
-
-### Isaac Z. Schlueter
-“必须，而且不是一个文件，而是两个层级：manifest 记录用户意图，lock 记录解析结果。否则用户选了哪些 channel、哪些 skill，是‘期望状态’；上游实际解析到的 commit/version/hash，是‘已解析状态’。这两个不能混。”
-
-### Martin Fowler
-“同意。manifest 是 policy，lock 是 materialized view。”
-
-### Mitchell Hashimoto
-“从 CLI 体验上，这意味着 `config` 改的是 manifest，`apply/update` 刷的是 lock。这样 `doctor` 才能告诉用户：你的意图没变，但当前部署漂移了。”
-
-### 本轮结论
-
-MVP 固定采用双文件状态：
-
-- `manifest.json`：用户意图
-- `lock.json`：解析结果与部署状态
-
----
-
-## 第五轮：MVP 里到底支持哪些 Source？
-
-### Martin Fowler
-“从建模上要预留 `SourceAdapter`，但 MVP 不要把来源铺太大。”
-
-### Isaac Z. Schlueter
-“Git 一定要是第一优先级，因为它天然有 snapshot。ClawHub 可以做第二优先级，因为它已经有 version/store/lock 语义。”
-
-### Mitchell Hashimoto
-“`search` 的体验不能太弱，但 GitHub 关键词搜索的结果质量不一定稳定。MVP 里要区分：`add` 支持显式 locator，`search` 则优先做有结构化结果的来源。”
-
-### 本轮结论
-
-MVP Source 范围定为：
-
-1. **Git Source**
-   - 必做
-   - 支持 GitHub repo / 任意 git URL / 本地 git 路径
-2. **ClawHub Source**
-   - 必做
-   - 作为注册表来源
-3. **Well-known Skills Discovery**
-   - 只预留接口，P1 再做
-
----
-
-## 第六轮：分发策略拍板
-
-### Martin Fowler
-“要遵循渠道现实，不要为了‘统一’牺牲兼容。”
-
-### Isaac Z. Schlueter
-“中心化 canonical store 没问题，但投影策略必须 per-channel。”
-
-### Mitchell Hashimoto
-“用户应该默认感知不到复杂性，所以策略要自动选，只在 `doctor` 和 advanced config 里解释。”
-
-### 本轮结论
-
-- Claude Code：**per-skill symlink** 默认，copy 兜底
-- OpenCode：**symlink** 默认
-- Codex：**symlink** 默认
-- 通用 `.agents/skills`：**symlink** 默认
-- OpenClaw：**copy** 默认，不走跨根 symlink
-
----
-
-## 第七轮：技术栈正式定型
-
-### Mitchell Hashimoto
-“既然 `config` 是树状 TUI，终端 UI 就不是附属品，而是主界面。Ink 很合适。”
-
-### Isaac Z. Schlueter
-“如果你选 Node，就选当前 LTS 主线，不要用已进入 maintenance 的版本。”
-
-### Martin Fowler
-“技术栈要服务模型稳定和 schema 演进，所以 Zod、atomic writes、fixture-based tests 都该是正式要求，不是实现偏好。”
-
-### 本轮结论
-
-正式技术栈：
-
-- Runtime：**Node.js 24 LTS**
-- Language：**TypeScript 5.x**
-- Package manager：**pnpm**
-- CLI framework：**oclif**
-- TUI：**Ink**
-- Schema validation：**Zod**
-- Git wrapper：**system git + simple-git**
-- Test：**Vitest**
-- Distribution：**npm first，Homebrew tap in P1**
-
----
-
-# 二、skill-flow 定型版 PRD
-
-## 1. 产品定义
-
-`skill-flow` 是一个面向 Agent Skills 生态的 macOS CLI。它统一管理多来源 skills，把上游内容下载到 `~/.skillflow/source/`，扫描出合法的 `SkillLeaf`，在 `~/.skillflow/skills/` 建立 canonical skill 集合，再将用户选中的 skill 以适配渠道的方式分发到 Claude Code、OpenCode、Codex、OpenClaw 与通用 `.agents/skills`。其核心职责是**索引与投影**，不是执行 skill。
-
-## 2. 目标与非目标
-
-### 2.1 目标
-
-MVP 要完成六件事：
-
-1. 支持 Git Source 与 ClawHub Source 的添加、扫描、更新、卸载。
-2. 支持“单 source 多 skill”的两层树状模型。
-3. 支持 `skill-flow config` 的树形多选 TUI。
-4. 支持按 channel 投影：Claude Code、OpenCode、Codex、OpenClaw、`.agents/skills`。
-5. 支持 `manifest.json + lock.json` 双层状态。
-6. 支持 `doctor` 做冲突、漂移、路径和兼容性检查。
-
-### 2.2 非目标
-
-MVP 不做以下事情：
-
-1. 不执行 skill 中的脚本。
-2. 不修改上游 `SKILL.md`。
-3. 不做 GUI。
-4. 不做通用 project-scope 管理；只有 OpenClaw 因官方工作区模型原因，保留 workspace 渠道。
-
-## 3. 用户与典型场景
-
-目标用户是同时使用多个 AI coding agent 的开发者。他们的高频动作是：
-
-- 从 GitHub 或 ClawHub 获取 skills
-- 统一查看一个 source 里有哪些 skill
-- 把其中部分 skill 应用到某个或全部渠道
-- 后续更新 source，并同步刷新多个渠道
-- 卸载整个 source，或仅取消某个 channel 的启用状态
-
-## 4. 领域模型
-
-### 4.1 Source
-
-一个可更新的上游单位。
-
-字段建议：
-
-- `sourceId`
-- `sourceType`
-- `locator`
-- `displayName`
-- `storageRoot`
-- `updateStrategy`
-
-### 4.2 SourceSnapshot
-
-Source 在某一时刻的解析快照。
-
-- git：`remote + branch + commit SHA`
-- clawhub：`slug + version + contentHash`
-- future well-known：`baseUrl + indexHash/etag`
-
-### 4.3 SkillLeaf
-
-真正可安装的 skill 单元。满足条件：
-
-- 存在 `SKILL.md`
-- frontmatter 可解析
-- `name`
-- `description`
-
-字段建议：
-
-- `skillId`
-- `sourceId`
-- `name`
-- `description`
-- `relativeRoot`
-- `contentHash`
-- `hasScripts`
-- `hasReferences`
-- `hasAssets`
-- `riskFlags[]`
-
-### 4.4 Channel
-
-一个目标适配器，而不是路径。
-
-字段建议：
-
-- `channelId`
-- `displayName`
-- `resolvedPath`
-- `strategy`
-- `pathSource`
-- `healthStatus`
-
-### 4.5 Deployment
-
-SkillLeaf 到 Channel 的一次投影关系。
-
-字段建议：
-
-- `deploymentId`
-- `skillId`
-- `channelId`
-- `strategy`
-- `targetPath`
-- `status`
-- `lastAppliedAt`
-
-## 5. 文件系统布局
-
-```text
-~/.skillflow/
-  source/
-    git/
-      <sourceId>/
-    clawhub/
-      <sourceId>/
-  skills/
-    <sourceId>/
-      <skillName>/ -> ../../source/...
-  state/
-    manifest.json
-    lock.json
-    channels.json
-    history.ndjson
-  cache/
-  tmp/
-  logs/
-```
-
-## 6. Source 策略
-
-### 6.1 Git Source（MVP 必做）
-
-输入支持：
-
-- GitHub `owner/repo`
-- 任意 git URL
-- 本地 git 路径
-
-### 6.2 ClawHub Source（MVP 必做）
-
-输入支持：
-
-- `clawhub:<slug>`
-- `clawhub:<slug>@<version>`
-
-MVP 实现：
-
-- 优先采用 **CLI bridge**：shell-out `clawhub install/update/list`
-- 将版本与来源信息同步到 `skill-flow lock`
-
-### 6.3 Well-known Skills Discovery（P1）
-
-只做接口预留，不进 MVP。
-
-## 7. Source 命名与展示规则
-
-### 外显 display 规则
-
-- Git 仓库：显示仓库名
-- 非 Git 且可识别作者：显示作者名
-- 无法识别：显示 `single`
-
-### 内部 storage 规则
-
-- Git：`<host>__<owner>__<repo>`
-- ClawHub：`clawhub__<slug>`
-- Generic single：`single__<hash>`
-
-## 8. Skill 扫描与索引规则
-
-扫描逻辑：
-
-1. 递归搜索包含 `SKILL.md` 的目录
-2. 跳过 `.git`、`node_modules`、构建产物
-3. 解析 frontmatter
-4. 生成 `SkillLeaf` 索引项
-5. 建立 `skills/<sourceId>/<skillName>` canonical 入口
-
-校验等级：
-
-### 标准校验
-
-- `SKILL.md` 存在
-- YAML 可解析
-- `name`
-- `description`
-
-### 严格校验
-
-- `name` 与目录名匹配
-- 命名合法
-- `description` 长度合理
-- 相对路径引用可达
-
-## 9. Channel 适配与默认策略
-
-### 9.1 Claude Code
-
-- 默认路径：`~/.claude/skills`
-- 默认策略：`symlink`
-- 兜底策略：`copy`
-
-### 9.2 OpenCode
-
-- 默认路径：`~/.config/opencode/skills`
-- 默认策略：`symlink`
-
-### 9.3 Codex
-
-- 默认路径：`~/.agents/skills`
-- 默认策略：`symlink`
-
-### 9.4 OpenClaw
-
-- 默认路径：`<workspace>/skills`，备选 `~/.openclaw/skills`
-- 默认策略：`copy`
-
-### 9.5 通用 `.agents/skills`
-
-- 默认路径：`~/.agents/skills`
-- 默认策略：`symlink`
-
-## 10. 命令设计
-
-正式命令集：
-
-```bash
-skill-flow add <source>
-skill-flow search <query>
-skill-flow list
-skill-flow config
-skill-flow update [--all | <sourceId>]
-skill-flow uninstall [<sourceId>...]
-skill-flow doctor
-```
-
-## 11. 状态文件设计
-
-### `manifest.json`
-
-记录用户意图：
-
-- sources
-- naming policy
-- selected skills by channel
-- user overrides
-
-### `lock.json`
-
-记录解析结果：
-
-- source snapshots
-- skill leaf inventory
-- deployments
-- content hashes
-- timestamps
-- schemaVersion
-
-### `channels.json`
-
-记录本机探测与 path override：
-
-- detected channels
-- resolved path
-- available strategies
-- health flags
-
-### `history.ndjson`
-
-记录审计事件：
-
-- add
-- update
-- config-apply
-- uninstall
-- doctor-warning
-
-## 12. 冲突与一致性规则
-
-### 12.1 同 channel 同名 skill
-
-默认阻止，不静默覆盖。
-
-### 12.2 目标路径已有非本工具管理文件
-
-默认不接管，标记 `foreign-existing`。
-
-### 12.3 Source 内同名 leaf
-
-扫描时直接判定 source inventory 非法，需要用户缩小范围或忽略。
-
-### 12.4 原子性
-
-所有 state 文件写入采用：
-
-- `tmp write`
-- `fsync`
-- `rename`
-
-所有 deployment 采用 staged apply；失败时不提交 lock 的成功状态。
-
-## 13. 安全要求
-
-MVP 安全要求：
-
-1. 永不执行 skill 脚本
-2. 扫描时做 frontmatter 与路径校验
-3. 拒绝 root 外 realpath 投影
-4. 风险标记：
-   - `has-scripts`
-   - `invalid-frontmatter`
-   - `name-dir-mismatch`
-   - `external-symlink`
-   - `foreign-existing`
-   - `openclaw-root-risk`
-5. 默认提示审计，`--yes` 才跳过确认
-
-## 14. 技术栈
-
-### 14.1 运行时与语言
-
-- **Node.js 24 LTS**
-- **TypeScript 5.x**
-
-### 14.2 包管理与构建
-
-- **pnpm**
-- 发布到 **npm**
-
-### 14.3 CLI 与 TUI
-
-- **oclif**
-- **Ink**
-
-### 14.4 Schema 与状态验证
-
-- **Zod**
-
-### 14.5 Git 访问
-
-- **system git**
-- **simple-git**
-
-### 14.6 测试
-
-- **Vitest**
-- fixture-based filesystem integration tests
-
-### 14.7 建议工程结构
-
-```text
-src/
-  commands/
-  tui/
-  domain/
-  adapters/
-    source/
-    channel/
-  services/
-    scan/
-    deploy/
-    update/
-    doctor/
-  state/
-  utils/
-```
-
-## 15. 里程碑
-
-### Milestone 1
-- Git Source
-- 扫描器
-- manifest/lock
-- list/add/update
-
-### Milestone 2
-- config TUI
-- Claude/OpenCode/Codex/agents 投影
-- doctor
-
-### Milestone 3
-- OpenClaw copy deployment
-- ClawHub adapter
-- uninstall
-
-### Milestone 4
-- search
-- diff
-- schema migration
-- alias conflict handling
-
-### Milestone 5（P1）
-- well-known discovery
-- project-scope support
-- Homebrew tap
-- advanced channel overrides
-- external plugin SDK
-
----
-
-# 三、工程实施文档
-
-## 1. 实施目标
-
-这一部分不是再讨论“做什么”，而是明确“怎么落地”。目标是让工程团队在没有额外口头补充的情况下，直接进入：
-
-1. 仓库初始化
-2. 核心模块搭建
-3. 命令实现
-4. 端到端测试
-5. 首个可发布 MVP
-
----
-
-## 2. MVP 工程范围切片
-
-### 2.1 必须在首发版本完成
-
-- Git Source Adapter
-- ClawHub Source Adapter（CLI bridge 方案）
-- Skill Scanner
-- Manifest/Lock/Channels 三类状态文件
-- Claude/OpenCode/Codex/Agents 四个 symlink channel
-- OpenClaw copy channel
-- `add / list / config / update / uninstall / doctor`
-- TUI 树状多选界面
-- 冲突检测、路径校验、原子写入、日志落盘
-
-### 2.2 可以延后到 P1
-
-- well-known registry adapter
-- alias 命名策略
-- Homebrew tap 自动发布
-- project-scope 管理
-- 自定义 channel adapter SDK
-- 远程 diff 预览
-
----
-
-## 3. 工程仓库建议结构
-
-```text
-skill-flow/
-  package.json
-  pnpm-lock.yaml
-  tsconfig.json
-  vitest.config.ts
-  README.md
-  src/
-    index.ts
-    cli.ts
-    commands/
-      add.ts
-      search.ts
-      list.ts
-      config.ts
-      update.ts
-      uninstall.ts
-      doctor.ts
-    tui/
-      app.tsx
-      screens/
-        channel-select.tsx
-        skill-tree.tsx
-        apply-preview.tsx
-      components/
-        tree-node.tsx
-        checkbox.tsx
-        footer-hints.tsx
-        status-pill.tsx
-    domain/
-      source.ts
-      snapshot.ts
-      skill.ts
-      channel.ts
-      deployment.ts
-      errors.ts
-    adapters/
-      source/
-        git.ts
-        clawhub.ts
-        registry.ts
-      channel/
-        claude.ts
-        opencode.ts
-        codex.ts
-        openclaw.ts
-        agents.ts
-    services/
-      detect/
-        channels.ts
-      scan/
-        scanner.ts
-        parser.ts
-        validators.ts
-      state/
-        manifest.ts
-        lock.ts
-        channels.ts
-        migrations.ts
-      deploy/
-        planner.ts
-        symlink.ts
-        copy.ts
-        applier.ts
-      source/
-        resolve.ts
-        fetch.ts
-        update.ts
-      doctor/
-        checks.ts
-      logging/
-        history.ts
-        logger.ts
-    utils/
-      fs.ts
-      hash.ts
-      path.ts
-      prompt.ts
-      time.ts
-      ids.ts
-  fixtures/
-    repos/
-    channels/
-    snapshots/
-  tests/
-    unit/
-    integration/
-    e2e/
-```
-
-设计原则：
-
-- `commands/` 只做参数解析与 orchestration
-- `domain/` 只放模型和不依赖 IO 的规则
-- `adapters/` 隔离第三方系统差异
-- `services/` 承担业务编排
-- `tui/` 不直接触碰磁盘；通过 service 层读写
-
----
-
-## 4. 命令参数规范
-
-## 4.1 `skill-flow add`
-
-```bash
-skill-flow add <source>
-  [--name <displayName>]
-  [--branch <branch>]
-  [--ref <ref>]
-  [--channel <channel...>]
-  [--yes]
-  [--json]
-```
-
-### 行为定义
-
-- `<source>` 支持：
-  - `owner/repo`
-  - `https://...git`
-  - `git@...`
-  - 本地路径
-  - `clawhub:<slug>`
-  - `clawhub:<slug>@<version>`
-- 若指定 `--channel`，则在 `add` 后直接触发一次 apply
-- 若指定 `--ref`，优先锁定对应 tag/commit
-- `--yes` 跳过来源确认与风险确认
-
-## 4.2 `skill-flow search`
-
-```bash
-skill-flow search <query>
-  [--source git|clawhub|all]
-  [--limit <n>]
-  [--json]
-```
-
-### 行为定义
-
-- `--source clawhub`：正式支持
-- `--source git`：MVP 仅做 repo 级搜索或 locator 解析辅助
-- `--source all`：按 adapter 聚合结果
-
-## 4.3 `skill-flow list`
-
-```bash
-skill-flow list
-  [--sources]
-  [--skills]
-  [--deployments]
-  [--channel <channel>]
-  [--source-id <id>]
-  [--json]
-```
-
-### 行为定义
-
-- 默认输出 `sources + skills + deployment summary`
-- `--skills` 展示 skill leaf 明细
-- `--deployments` 展示按 channel 的启用状态
-
-## 4.4 `skill-flow config`
-
-```bash
-skill-flow config
-  [--channel <channel...>]
-  [--source-id <id>]
-  [--non-interactive]
-  [--json]
-```
-
-### 行为定义
-
-- 默认进入 TUI
-- `--non-interactive` 预留给脚本模式，MVP 可只支持有限 flag 驱动
-- 未传 `--channel` 时先展示 channel 多选
-
-## 4.5 `skill-flow update`
-
-```bash
-skill-flow update
-  [--all]
-  [--source-id <id>...]
-  [--apply]
-  [--dry-run]
-  [--json]
-```
-
-### 行为定义
-
-- `--all` 更新所有 source
-- `--apply` 更新完成后重新部署受影响 channel
-- `--dry-run` 仅展示可更新项和变更摘要
-
-## 4.6 `skill-flow uninstall`
-
-```bash
-skill-flow uninstall <sourceId...>
-  [--yes]
-  [--json]
-```
-
-### 行为定义
-
-- 卸载 source 及其 canonical skills 与所有 deployments
-- 不删除其他来源产生的同名 skill
-
-## 4.7 `skill-flow doctor`
-
-```bash
-skill-flow doctor
-  [--channel <channel...>]
-  [--source-id <id>...]
-  [--fix]
-  [--json]
-```
-
-### 行为定义
-
-- 默认只检查不修改
-- `--fix` 仅修复确定性问题：断链重建、缺失 state 目录、历史文件 rotate
-- 冲突覆盖不属于自动修复范围
-
----
-
-## 5. 状态文件 Schema
-
-## 5.1 `manifest.json`
-
-作用：记录用户意图。
-
-```json
-{
-  "$schema": "https://skill-flow.dev/schema/manifest-v1.json",
-  "schemaVersion": 1,
-  "sources": [
-    {
-      "sourceId": "github__vercel-labs__skills",
-      "sourceType": "git",
-      "locator": "vercel-labs/skills",
-      "displayName": "skills",
-      "options": {
-        "ref": null,
-        "branch": "main"
-      }
-    }
-  ],
-  "bindings": [
-    {
-      "channelId": "claude",
-      "skillSelections": [
-        {
-          "sourceId": "github__vercel-labs__skills",
-          "skillIds": ["frontend-design", "skill-creator"]
-        }
-      ]
-    }
-  ],
-  "overrides": {
-    "channels": {
-      "openclaw": {
-        "path": null,
-        "strategy": "copy"
-      }
-    }
-  }
-}
-```
-
-### 约束
-
-- `schemaVersion` 必填
-- `bindings` 只描述“期望启用哪些 skill 到哪些 channel”
-- 不记录部署是否成功；那是 lock 的职责
-
-## 5.2 `lock.json`
-
-作用：记录解析结果与当前落地状态。
-
-```json
-{
-  "$schema": "https://skill-flow.dev/schema/lock-v1.json",
-  "schemaVersion": 1,
-  "generatedAt": "2026-03-21T12:00:00.000Z",
-  "sources": [
-    {
-      "sourceId": "github__vercel-labs__skills",
-      "sourceType": "git",
-      "snapshot": {
-        "remote": "https://github.com/vercel-labs/skills.git",
-        "branch": "main",
-        "commit": "abc123"
-      },
-      "contentHash": "sha256:..."
-    }
-  ],
-  "skills": [
-    {
-      "skillId": "frontend-design",
-      "sourceId": "github__vercel-labs__skills",
-      "name": "frontend-design",
-      "description": "...",
-      "relativeRoot": "skills/frontend-design",
-      "canonicalPath": "~/.skillflow/skills/github__vercel-labs__skills/frontend-design",
-      "contentHash": "sha256:...",
-      "riskFlags": []
-    }
-  ],
-  "deployments": [
-    {
-      "deploymentId": "dep_001",
-      "skillId": "frontend-design",
-      "channelId": "claude",
-      "strategy": "symlink",
-      "targetPath": "~/.claude/skills/frontend-design",
-      "status": "applied",
-      "lastAppliedAt": "2026-03-21T12:00:00.000Z"
-    }
-  ]
-}
-```
-
-### 约束
-
-- lock 必须可重建本地部署视图
-- `deployments.status` 允许：`planned | applied | stale | broken | removed`
-- `contentHash` 用于 update 后判断是否需要重投影
-
-## 5.3 `channels.json`
-
-作用：记录本机探测结果与 override。
-
-```json
-{
-  "$schema": "https://skill-flow.dev/schema/channels-v1.json",
-  "schemaVersion": 1,
-  "detected": [
-    {
-      "channelId": "claude",
-      "path": "/Users/alice/.claude/skills",
-      "pathSource": "default",
-      "available": true,
-      "preferredStrategy": "symlink"
-    },
-    {
-      "channelId": "openclaw",
-      "path": "/Users/alice/.openclaw/workspace/skills",
-      "pathSource": "detected-workspace",
-      "available": true,
-      "preferredStrategy": "copy"
-    }
-  ]
-}
-```
-
-## 5.4 `history.ndjson`
-
-每行一个事件，方便审计与排障。
-
-```json
-{"ts":"2026-03-21T12:00:00.000Z","event":"add","sourceId":"github__vercel-labs__skills"}
-{"ts":"2026-03-21T12:01:00.000Z","event":"config-apply","channelId":"claude","count":2}
-```
-
----
-
-## 6. Domain Model TypeScript Interface
-
-```ts
-export type SourceType = "git" | "clawhub" | "registry";
-export type ChannelId = "claude" | "opencode" | "codex" | "openclaw" | "agents";
-export type DeployStrategy = "symlink" | "copy";
-export type DeploymentStatus = "planned" | "applied" | "stale" | "broken" | "removed";
-
-export interface Source {
-  sourceId: string;
-  sourceType: SourceType;
-  locator: string;
-  displayName: string;
-  storageRoot: string;
-  updateStrategy: "git-pull" | "registry-sync" | "custom";
-}
-
-export interface SourceSnapshot {
-  sourceId: string;
-  versionRef: string;
-  contentHash: string;
-  metadata: Record<string, unknown>;
-}
-
-export interface SkillLeaf {
-  skillId: string;
-  sourceId: string;
-  name: string;
-  description: string;
-  relativeRoot: string;
-  canonicalPath: string;
-  contentHash: string;
-  riskFlags: string[];
-}
-
-export interface Channel {
-  channelId: ChannelId;
-  displayName: string;
-  resolvedPath: string;
-  preferredStrategy: DeployStrategy;
-  available: boolean;
-}
-
-export interface Deployment {
-  deploymentId: string;
-  skillId: string;
-  channelId: ChannelId;
-  strategy: DeployStrategy;
-  targetPath: string;
-  status: DeploymentStatus;
-  lastAppliedAt?: string;
-}
-```
-
----
-
-## 7. Adapter 接口规范
-
-## 7.1 Source Adapter
-
-```ts
-export interface ResolvedSource {
-  sourceType: "git" | "clawhub" | "registry";
-  locator: string;
-  normalizedId: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface FetchResult {
-  source: Source;
-  snapshot: SourceSnapshot;
-  storageRoot: string;
-}
-
-export interface DiscoveredSkill {
-  name: string;
-  description: string;
-  relativeRoot: string;
-  contentHash: string;
-  riskFlags: string[];
-}
-
-export interface SourceAdapter {
-  kind: "git" | "clawhub" | "registry";
-  probe(input: string): boolean;
-  resolve(input: string): Promise<ResolvedSource>;
-  fetch(source: ResolvedSource): Promise<FetchResult>;
-  update(source: Source, snapshot: SourceSnapshot): Promise<FetchResult>;
-  scan(storageRoot: string): Promise<DiscoveredSkill[]>;
-}
-```
-
-### Git Adapter 额外职责
-
-- 支持 branch/ref/commit
-- 提供远程变化检查
-- 在公开 GitHub 来源下可使用 API 预览树结构，但正式下载仍以 git 为准
-
-### ClawHub Adapter 额外职责
-
-- shell-out 调用 `clawhub`
-- 读取安装结果与 lock 信息
-- 将 registry version 映射为 `versionRef`
-
-## 7.2 Channel Adapter
-
-```ts
-export interface DeploymentPlanItem {
-  skillId: string;
-  channelId: ChannelId;
-  strategy: DeployStrategy;
-  canonicalPath: string;
-  targetPath: string;
-  action: "create" | "replace" | "remove" | "skip";
-  reason?: string;
-}
-
-export interface DeploymentPlan {
-  channelId: ChannelId;
-  items: DeploymentPlanItem[];
-  warnings: string[];
-}
-
-export interface DoctorFinding {
-  code: string;
-  severity: "info" | "warn" | "error";
-  message: string;
-  target?: string;
-}
-
-export interface ChannelAdapter {
-  kind: ChannelId;
-  detect(): Promise<Channel | null>;
-  plan(skills: SkillLeaf[], channel: Channel): Promise<DeploymentPlan>;
-  apply(plan: DeploymentPlan): Promise<Deployment[]>;
-  diagnose(channel: Channel): Promise<DoctorFinding[]>;
-}
-```
-
----
-
-## 8. 关键算法规范
-
-## 8.1 Skill Scanner 算法
-
-### 输入
-
-- `sourceRoot`
-- `scanOptions`
-
-### 伪代码
-
-```text
-walk(sourceRoot)
-  ignore directories: .git, node_modules, dist, build, .next, target
-  if currentDir contains SKILL.md:
-     parse frontmatter
-     validate required fields
-     emit SkillLeaf candidate
-     do not recurse into nested skill roots unless explicit nested mode enabled
-```
-
-### 规则
-
-- 默认不允许“skill 中嵌 skill”自动递归安装
-- 若一个目录命中 `SKILL.md`，把它视为 leaf 边界
-- 生成 `contentHash` 时应基于 leaf root 下所有受管文件
-
-## 8.2 Deployment Planner 算法
-
-### 输入
-
-- 目标 channel
-- manifest 中该 channel 的选中 skill 列表
-- 当前 lock 中已存在的 deployments
-- 磁盘实际状态
-
-### 输出
-
-- `DeploymentPlan`
-
-### 规则
-
-1. 先构建 desired set
-2. 再读取 current set
-3. 求 diff：
-   - desired - current => create
-   - current - desired => remove
-   - desired ∩ current 且 hash 变化 => replace
-   - desired ∩ current 且一致 => skip
-4. 若遇到 foreign-existing，计划项变为 `skip` 并附 reason
-
-## 8.3 Copy Deploy 算法（OpenClaw）
-
-```text
-for each plan item:
-  stage copy into SM_HOME/tmp/<deploymentId>
-  verify realpath(target parent) within configured root
-  rename staged dir -> final target
-  fsync parent dir
-```
-
-## 8.4 Symlink Deploy 算法
-
-```text
-for each plan item:
-  ensure target parent exists
-  if target exists and managed-by-us -> remove/replace
-  if target exists and foreign -> skip with warning
-  ln -s canonicalPath targetPath
-```
-
-## 8.5 Update 算法
-
-```text
-resolve sources to update
-for each source:
-  fetch/update snapshot
-  rescan skills
-  rebuild canonical entries for changed skills only
-  recompute deployments for affected channels
-  if --apply then apply plans
-  commit new lock atomically
-```
-
----
-
-## 9. TUI 详细交互规范
-
-## 9.1 页面流转
-
-```text
-Start
-  -> ChannelSelectScreen
-  -> SkillTreeScreen
-  -> ApplyPreviewScreen
-  -> ApplyResultScreen
-  -> Exit
-```
-
-## 9.2 `ChannelSelectScreen`
-
-### 展示字段
-
-- channel 名称
-- 是否检测到
-- 目标路径
-- 默认策略
-- 健康状态
-
-### 操作键
-
-- `↑ / ↓`：移动
-- `Space`：切换选中
-- `a`：全选 / 全不选
-- `Enter`：进入下一屏
-- `Esc`：退出
-
-## 9.3 `SkillTreeScreen`
-
-### 展示结构
-
-- 一级：source display root
-- 二级：skill leaf
-
-### 状态
-
-- `[ ]`：未选
-- `[-]`：部分选中
-- `[x]`：全部选中
-
-### 操作键
-
-- `↑ / ↓`：移动
-- `Space`：选中/取消
-- `Tab`：展开/收起一级节点
-- `Enter`：进入预览
-- `Backspace`：返回上一屏
-
-## 9.4 `ApplyPreviewScreen`
-
-### 展示字段
-
-- channels 数量
-- skills 数量
-- create / replace / remove / skip 计数
-- warnings 列表
-- conflicts 列表
-
-### 操作键
-
-- `Enter`：确认应用
-- `Backspace`：返回树选择
-- `q`：取消
-
----
-
-## 10. 错误码规范
-
-错误码统一形式：`SM_<DOMAIN>_<CODE>`
-
-### 10.1 Source 相关
-
-- `SM_SOURCE_UNSUPPORTED`：无法识别来源
-- `SM_SOURCE_RESOLVE_FAILED`：来源解析失败
-- `SM_SOURCE_FETCH_FAILED`：下载或拉取失败
-- `SM_SOURCE_UPDATE_CONFLICT`：更新过程中发现本地 source 被手工修改
-
-### 10.2 Scan 相关
-
-- `SM_SCAN_SKILL_MD_MISSING`：未发现合法 `SKILL.md`
-- `SM_SCAN_FRONTMATTER_INVALID`：frontmatter 无法解析
-- `SM_SCAN_NAME_DIR_MISMATCH`：name 与目录名不一致
-- `SM_SCAN_DUPLICATE_SKILL`：同一 source 内发现重名 skill
-
-### 10.3 Deployment 相关
-
-- `SM_DEPLOY_TARGET_EXISTS_FOREIGN`：目标路径已存在非受管文件
-- `SM_DEPLOY_BROKEN_SYMLINK`：存在断链
-- `SM_DEPLOY_COPY_OUTSIDE_ROOT`：copy 目标越出受允根目录
-- `SM_DEPLOY_STRATEGY_UNSUPPORTED`：channel 不支持该分发策略
-
-### 10.4 State 相关
-
-- `SM_STATE_SCHEMA_UNKNOWN`：schemaVersion 不识别
-- `SM_STATE_MIGRATION_FAILED`：状态迁移失败
-- `SM_STATE_LOCK_WRITE_FAILED`：lock 原子写入失败
-
-### 10.5 Doctor 相关
-
-- `SM_DOCTOR_CHANNEL_UNAVAILABLE`：渠道不可用
-- `SM_DOCTOR_REALPATH_RISK`：realpath 风险
-- `SM_DOCTOR_DRIFT_DETECTED`：manifest/lock/磁盘三者漂移
-
----
-
-## 11. 日志与可观测性
-
-### 11.1 控制台日志级别
-
-- `info`
-- `warn`
-- `error`
-- `debug`
-
-### 11.2 日志文件
-
-建议：
-
-```text
-~/.skillflow/logs/
-  current.log
-  previous.log
-```
-
-### 11.3 审计事件
-
-`history.ndjson` 必须可回答这些问题：
-
-- 某个 source 何时被添加
-- 某个 skill 何时被应用到某个 channel
-- 某次 update 改了哪些 snapshot
-- 某次 doctor 发现了什么问题
-
----
-
-## 12. 安全与防御式实现要求
-
-1. **默认不执行第三方脚本**
-2. **所有路径操作先做 `realpath` 校验**
-3. **受管 symlink 通过 sidecar 元数据或 lock 映射识别**
-4. **删除操作只删除受管目标**
-5. **copy 部署使用临时目录，完成后 rename 提交**
-6. **风险 flag 在 UI 和 JSON 输出中都必须可见**
-7. **外部 CLI bridge（如 ClawHub）必须收集 exit code、stdout、stderr**
-
----
-
-## 13. 测试计划
-
-## 13.1 单元测试
-
-覆盖：
-
-- source parser
-- id normalizer
-- frontmatter parser
-- manifest/lock validator
-- planner diff 逻辑
-- 错误码映射
-
-## 13.2 集成测试
-
-### 用例 A：Git 单仓多 skill
-
-1. add git repo
-2. scan 出 3 个 leaf
-3. config 到 Claude + Codex
-4. 验证 symlink 数量与 lock deployments
-
-### 用例 B：OpenClaw copy
-
-1. 检测 workspace
-2. apply 到 openclaw
-3. 验证复制后的 skill realpath 在 workspace root 内
-
-### 用例 C：更新后重投影
-
-1. 初始安装 skill A
-2. 上游变更 skill A 内容
-3. update --apply
-4. lock 中 hash 更新，deployment 状态回到 `applied`
-
-### 用例 D：foreign-existing
-
-1. 在目标目录预先创建同名非受管文件夹
-2. apply
-3. 返回 `SM_DEPLOY_TARGET_EXISTS_FOREIGN`
-
-### 用例 E：卸载
-
-1. 安装 source X
-2. 投影到多个 channel
-3. uninstall X
-4. 验证 source、canonical、deployments 被清理
-
-## 13.3 E2E 测试
-
-- 在临时 HOME 下运行完整 CLI
-- 验证 state 文件与磁盘结构一致
-- 验证 JSON 模式输出可供脚本消费
-
----
-
-## 14. 发布流程建议
-
-## 14.1 首发发布
-
-- npm package：`skill-flow`
-- 可执行入口：`bin/skill-flow`
-- README 包含 quickstart 与 channel caveats
-
-## 14.2 CI 流程
-
-- install
-- lint
-- test
-- build
-- package smoke test
-- draft release
-
-## 14.3 P1 发布补充
-
-- Homebrew tap
-- shell completion
-- upgrade notice
-
----
-
-## 15. 首个 Sprint 建议拆解
-
-### Sprint 1（基础骨架）
-
-- 初始化 oclif + TypeScript + pnpm + Vitest
-- 建立 domain model
-- state 文件读写与 schema 验证
-- Git adapter 最小实现
-
-### Sprint 2（扫描与列表）
-
-- scanner
-- parser
-- list
-- canonical skill 构建
-
-### Sprint 3（分发与 TUI）
-
-- Channel adapters
-- planner / applier
-- config TUI
-- doctor 初版
-
-### Sprint 4（更新与卸载）
-
-- update
-- uninstall
-- drift detection
-- e2e 测试
-
-### Sprint 5（ClawHub 与打磨）
-
-- ClawHub adapter
-- JSON 输出模式
-- 文档与发布流程
-
----
-
-## 16. 最终实施结论
-
-这份文档的最终工程结论如下：
-
-1. **先做全局级 manager，再做项目级 manager**。
-2. **先做 Git + ClawHub 两类 source，再做 registry discovery**。
-3. **先做 per-channel strategy 自动化，再开放高级 override**。
-4. **坚持 manifest/lock 双层状态，不做无状态运行**。
-5. **坚持 OpenClaw 默认 copy，其他主渠道默认 symlink**。
-6. **坚持状态原子写入、部署 staged apply、删除只删受管内容**。
-7. **坚持 TUI 作为主配置界面，而不是靠长 flag 拼装体验**。
-
-这已经足够作为研发启动、任务拆解和首轮工程评审的直接输入文档。