Skip to content

README.zh.md

Latest commit

 

History

History
239 lines (172 loc) · 6.74 KB

README.zh.md

File metadata and controls

239 lines (172 loc) · 6.74 KB

Skill Flow

将散落的 AI agent skill 整合为有序工作流。

English · 日本語

Node.js Version npm Version License

Skill Flow 图标

在所有主流编码 agent 中安装、管理和共享 skill —— Claude Code、Cursor、Copilot、Trae 等。

从 skills.sh、GitHub 或本地来源搜索并导入 skill。一次部署到多个 agent。保持一切井然有序且及时更新。

Skill Flow 桌面总览

为什么要做这个

逐个安装 skill 在规模化后会崩溃：

  • 仓库包含多个相关 skill，但你分别安装它们
  • 不同 agent 期望不同的位置
  • 更新会悄悄漂移
  • 未管理的目录不断累积
  • 没人追踪实际部署了什么

skill-flow 保留了工作流分组。一个 source 始终是一个内聚单元——检查它、选择 skill、部署到多个目标、干净地更新，并始终了解你的状态。

当前能力

  • 分组化 source 管理：本地、Git、skills.sh 统一走同一套导入模型。
  • 多 agent 部署：把同一组选中的 skill 部署到 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、OpenClaw、Trae、Windsurf 等目标。
  • 交互式配置流程：基于 Ink 的 add/config/find TUI，覆盖选择、审阅和修复流程。
  • macOS 15+ 桌面应用：SwiftUI 主窗口、导入页、详情页、设置页和菜单栏快速配置。
  • 显式状态：manifest.json 记录意图，lock.json 记录实际 inventory 与 deployment。
  • Bridge 协议：通过 skill-flow bridge --json 提供机器可读入口。
  • 修复与诊断：doctor、repair-source、repair-state、repair-targets 负责处理最容易坏掉的地方。

界面预览

菜单栏 导入页
菜单栏快速配置 导入页
详情页 设置页
详情页 设置页

快速开始

安装

npm install -g skill-flow
skill-flow --help

也可以不全局安装，直接运行：

npx skill-flow --help

桌面端前置依赖

Skill Flow Desktop 目前在目标 Mac 上仍依赖少量外部命令行工具：

  • 启动内置 desktop helper 需要 node 20 或更高版本
  • 导入非 GitHub Git source 需要 git
  • 导入 skills.sh source 需要 npx

如果桌面应用检测到依赖缺失，会直接提示可执行的错误信息，并引导回本节处理。

常见使用流程

# 添加一个 source
skill-flow add garrytan/gstack

# 查看当前 workflow group
skill-flow list

# 打开交互式配置 UI
skill-flow config

# 搜索本地技能、内置目录和 skills.sh
skill-flow find browser

# 更新单个 source 或全部 source
skill-flow update garrytan-gstack
skill-flow update --all

# 诊断漂移和坏掉的部署
skill-flow doctor

机器桥接入口

桌面端和辅助工具通过版本化 JSON 协议调用 CLI：

printf '%s' '{"protocolVersion":"1.0","command":"list"}' | skill-flow bridge --json

支持的来源

skill-flow add <source> 目前支持：

  • 本地目录
  • owner/repo GitHub 简写
  • 完整 HTTPS Git URL
  • SSH Git URL
  • GitHub tree URL
  • clawhub:<slug>[@version]

示例：

skill-flow add ~/code/my-skills
skill-flow add garrytan/gstack
skill-flow add https://github.com/garrytan/gstack.git
skill-flow add git@github.com:garrytan/gstack.git
skill-flow add https://github.com/garrytan/gstack/tree/main/skills
skill-flow add clawhub:example/skill-pack
skill-flow add clawhub:example/skill-pack@1.2.3

如果仓库很大，但默认只想从某个子目录开始预选，可以加 --path <repoSubpath>。

支持的目标 Agent

当前内置目标：

  • Claude Code
  • Codex
  • Cursor
  • GitHub Copilot
  • Gemini CLI
  • OpenCode
  • OpenClaw
  • Pi
  • Trae
  • Windsurf
  • Roo Code
  • Cline
  • Amp
  • Kiro

目标路径可以通过 SKILL_FLOW_TARGET_* 环境变量覆盖。

命令总览

命令 作用
add <source> 导入 source，并选择 skill 与目标
list 查看 workflow group 和当前健康状态
find <query> / search <query> 搜索本地技能、内置 Git 目录与 skills.sh
config 打开交互式配置 UI
update [sourceId] --all 更新单个或全部已注册 source
doctor 诊断漂移、缺失路径和投影问题
repair-source [sourceId] --all 修复 source checkout 元数据
repair-state [sourceId] --all 重建 source 侧状态
repair-targets [sourceId] --all 修复目标部署内容
uninstall <sourceIds...> 移除 group 及其部署
bridge --json 执行机器协议请求

状态如何组织

skill-flow 默认把状态放在 ~/.skillflow/：

  • manifest.json：你想要什么
  • lock.json：系统实际装成了什么
  • source/local/*：本地导入或接管的外部 source
  • source/git/*：Git source 缓存
  • source/clawhub/*：skills.sh source 缓存
  • catalog/git/*：内置 Git catalog 缓存

目标目录只是部署结果，不是真正的事实源。

Monorepo 结构

  • apps/cli：对外发布的 npm CLI 包
  • apps/desktop-mac：macOS 15+ SwiftUI 桌面应用
  • packages/domain：领域模型和核心类型
  • packages/storage：manifest/lock/preferences/cache 持久化
  • packages/integration：Git、GitHub、skills.sh、路径与命名集成
  • packages/core-engine：inventory、deployment、doctor、bootstrap 等服务
  • packages/query：共享运行时与 bridge 编排
  • packages/shared-types：bridge 协议类型
  • packages/tui：Ink add/find/config UI
  • docs：架构、贡献指南、参考资料、计划与打包文档

开发

npm install
npm run build
npm test

CLI 开发调试：

npm run -w skill-flow dev -- --help

桌面端开发调试：

npm run build
cd apps/desktop-mac
swift build
swift test

让桌面端使用本地 CLI 构建产物：

export SKILL_FLOW_DESKTOP_HELPER_OVERRIDE=/absolute/path/to/apps/cli/dist/cli.js

文档入口

许可证

Apache License 2.0。见 LICENSE。