skill-flow 1.0.2 → 1.0.3

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

@@ -1,740 +0,0 @@
-# skill-flow 定型版 PRD
-
-> 版本：v1.0  
-> 产出方式：基于三位项目人员视角的多轮讨论收敛  
-> 项目人员：Martin Fowler / Isaac Z. Schlueter / Mitchell Hashimoto  
-> 平台：macOS（MVP）
-
----
-
-# 一、三人多轮讨论纪要
-
-## 第一轮：先定边界，这到底是不是“包管理器”？
-
-### 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
-
-一个可更新的上游单位。  
-示例：git repo、ClawHub slug、未来的 well-known URL。
-
-字段建议：
-
-- `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. 文件系统布局
-
-`skill-flow` 采用“原始内容、canonical 集合、状态文件”三层结构：
-
-```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 路径
-
-落地策略：
-
-- 原样 clone 到 `source/git/<sourceId>/`
-- 默认通过 system git 做 fetch/pull
-- `simple-git` 作为 Node 包装层，不替代 git 本身
-
-### 6.2 ClawHub Source（MVP 必做）
-
-输入支持：
-
-- `clawhub:<slug>`
-- `clawhub:<slug>@<version>`
-
-MVP 实现：
-
-- 优先采用 **CLI bridge**：shell-out `clawhub install/update/list`
-- 读取或同步 `.clawhub/lock.json` 信息到 `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`  
-默认策略：**per-skill symlink**
-
-兼容说明：
-
-- 不把整个 `~/.claude/skills` 替换成 symlink
-- 只在目录内按 skill 建单独 symlink
-- `doctor` 提示必要时可切换 copy fallback
-
-### 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
-```
-
-### `add`
-
-作用：添加一个 Source，并完成初次索引。  
-流程：
-
-1. 解析 source adapter
-2. 下载/clone
-3. 扫描 skill leaf
-4. 建立 canonical 集合
-5. 写 `manifest + lock`
-
-### `search`
-
-MVP 定义：
-
-- ClawHub：正式支持
-- Git：支持显式 locator 输入；关键词搜索作为 beta 能力
-- 本地：可搜索已安装 inventory
-
-### `list`
-
-展示：
-
-- sources
-- skills
-- deployments
-- update availability
-- `--json` 输出
-
-### `config`
-
-这是核心命令，必须实现 TUI。
-
-**第一屏：Channel 选择**
-
-- 展示已探测到的 channel
-- 支持多选与 `all channels`
-
-**第二屏：Source/Skill 树选择**
-
-- 一级：source display root
-- 二级：skill leaf
-- Space：切换选中
-- Tab：展开/收起
-- Enter：确认
-- 一级节点三态：未选 / 部分 / 全选
-
-**第三屏：Apply 预览**
-
-- 将创建的 symlink 数
-- 将复制的目录数
-- 冲突项
-- 风险提示项
-
-### `update`
-
-- Git：fetch/pull，重扫索引，刷新 deployments
-- ClawHub：调用 registry update 语义
-
-### `uninstall`
-
-按 source 粒度卸载：
-
-- 移除 source 原始内容
-- 移除 canonical 集合
-- 移除 deployments
-- 更新 state
-
-### `doctor`
-
-检查项：
-
-- channel path 是否可用
-- symlink 是否断裂
-- OpenClaw realpath 风险
-- 同名冲突
-- lock 漂移
-- 可更新 source
-- 兼容性 warning
-
----
-
-## 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
-
-默认阻止，不静默覆盖。  
-用户必须：
-
-- 取消其中一个，或
-- 设置 alias（P1）
-
-### 12.2 目标路径已有非本工具管理文件
-
-默认不接管，标记 `foreign-existing`。
-
-### 12.3 Source 内同名 leaf
-
-扫描时直接判定 source inventory 非法，需要用户缩小范围或忽略。
-
-### 12.4 原子性
-
-所有 state 文件写入采用：
-
-- `tmp write`
-- `fsync`
-- `rename`
-
-所有 deployment 采用 staged apply；失败时不提交 lock 的成功状态。
-
----
-
-## 13. 安全要求
-
-第三方 skill 视为不可信输入。
-
-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**：用于 `config` 的树状交互界面
-
-### 14.4 Schema 与状态验证
-
-- **Zod**
-
-### 14.5 Git 访问
-
-- **system git** 为真相源
-- **simple-git** 为 Node 包装层
-
-### 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
-
----
-
-## 16. 最终拍板结论
-
-这一版 PRD 的硬结论只有八条：
-
-1. `skill-flow` 的本质是 **Source Resolver + Skill Indexer + Channel Projector**。
-2. **仓库不是 skill，skill 是 leaf**。
-3. **manifest + lock 必做**。
-4. **Channel 必须是 adapter，不是路径字符串**。
-5. **Claude/OpenCode/Codex/agents 默认 symlink；OpenClaw 默认 copy**。
-6. **MVP 先做 global scope；OpenClaw 因 workspace 例外保留 workspace channel**。
-7. **技术栈定为 Node 24 + TypeScript + oclif + Ink + Zod + simple-git + Vitest + pnpm**。
-8. **安全默认从严，不执行第三方脚本，不静默覆盖冲突**。
-
----
-
-# 三、补充说明
-
-这份 Markdown 文档是已经可进入研发启动会的定型版本。下一步最适合继续拆解的是：
-
-- 命令参数 spec
-- `manifest.json` / `lock.json` 的 JSON Schema
-- SourceAdapter / ChannelAdapter 接口定义
-- 错误码与诊断码
-- `config` TUI 组件树与交互状态机
-