SkillForge
by HaddenHunter
README.md
# SkillForge
[English Documentation](README.en.md)
> **本仓库是 SkillForge 的公开内容仓。** Web 界面的源码、构建脚本、core/registry 实现与 Rust CLI 都在私有仓 [HaddenHunter/SkillForge-Core](https://github.com/HaddenHunter/SkillForge-Core)。本仓 `main` 分支**只保留内容源文件**（技能清单、文档、镜像配置等）；可访问的静态站点由 Core 仓的 Actions 构建后，跨仓推送到本仓的 `gh-pages` 分支，由 GitHub Pages 服务。
SkillForge 是一个给 AI Coding Agent 使用的本地优先技能运行时。它把技能定义成可校验、可组合、可暴露为 MCP 的独立单元，让 Agent 能像“安装包”一样复用能力，同时通过白名单沙箱约束读写范围。
## 访问地址
- `https://skillforge.c8.fit`（GitHub Pages · 源分支：`gh-pages` / 根目录）
- 也可以直接访问 `https://HaddenHunter.github.io/SkillForge/`（CNAME 解析到前者）
## 📦 本仓里已经「编译好」的产物直接下载（公开，无权限）
本仓不存源码，但保留完整发布产物——**二进制可执行文件 + 前端打包好的静态页**，均在公开仓可见可下载：
### 1) 前端打包好的静态产物（Registry Web UI）
位置：**本仓 `gh-pages` 分支的根目录**，就是完整打包好的 Next 14 `output: export` 产物：
```
gh-pages (root)
├── index.html skills/ docs/ audit/ settings/ ← 18 页已预渲染 SSG
├── _next/ packages/-/ ← 3 个技能 tarball + sha256 直接直链
└── dist/bin/ ← 编译好的 CLI 二进制卡片页（见下）
```
在线浏览：`https://skillforge.c8.fit` ，源码打包、技能打包、CNAME 注入，全部由 Core 私仓 Actions 构建完成后跨仓推送。
### 2) 编译好的二进制可执行文件（Rust CLI · 四平台）
公开仓**同时放两份**（登录与否都能下）：
- **（推荐）Pages 静态直链**：`https://skillforge.c8.fit/dist/bin/` 打开就有卡片页，4 张卡片直接点 `tar.gz / sha256`
- **GitHub Releases**： https://github.com/HaddenHunter/SkillForge/releases （由 Core 私仓 release workflow 自动镜像）
四平台文件名：
| 平台 | 推荐场景 | 静态下载链接 |
|------|---------|-----|
| macOS Apple Silicon (arm64) | M 系列 Mac（推荐） | `skillforge-darwin-arm64-<VERSION>.tar.gz` |
| macOS Intel (x86_64) | Intel Mac | `skillforge-darwin-amd64-<VERSION>.tar.gz` |
| Linux ARM64 (aarch64) | ARM 服务器 / 树莓派 | `skillforge-linux-arm64-<VERSION>.tar.gz` |
| Linux AMD64 (x86_64) | CI / 服务器（推荐） | `skillforge-linux-amd64-<VERSION>.tar.gz` |
> 每个 tar.gz 旁边都有同名 `.sha256`，下载后强校验：
> ```bash
> curl -sSL https://skillforge.c8.fit/dist/bin/skillforge-darwin-arm64-0.1.0.tar.gz -o /tmp/sf.tar.gz
> curl -sSL https://skillforge.c8.fit/dist/bin/skillforge-darwin-arm64-0.1.0.tar.gz.sha256
> sha256sum /tmp/sf.tar.gz
> tar xzf /tmp/sf.tar.gz && sudo install skillforge-*/skillforge /usr/local/bin/skillforge
> skillforge --help
> ```
## 仓库布局（本公开仓 main 分支）
- `skills/`：技能源（`skill.yml · SKILL.md · eval.md · scripts/ · references/`），Core 仓构建静态页时会从这里打包 tarball 并生成下载索引
- `docs/`：公开文档，构建时被 Next `output: export` 固化到 Pages
- `mirrors/`：技能镜像白名单配置（可选）
- `README*`、`LICENSE`：说明文件
> 不要往 `main` 分支添加：`registry-web/`、Node 构建脚本、`pnpm/pnpm-lock`、`.github/workflows/` 里的部署 workflow。这些全部放在 `HaddenHunter/SkillForge-Core` 仓的 `web-assets/` 与 `.github/workflows/build-and-push-pages.yml`。
## 如何触发一次站点发布
在私有 Core 仓：
```bash
# 1. 准备一个可写本仓库的 Deploy Key（推荐）或 PAT：
# ssh-keygen -t ed25519 -C "sf-core->sf gh-pages" -N '' -f /tmp/sf-deploy
# 将公钥(sf-deploy.pub)添加到本仓 Settings → Deploy keys → 勾选「Allow write access」
# 将私钥(sf-deploy)添加到 SkillForge-Core 的 Secrets：SKILLFORGE_DEPLOY_KEY
# 2. 推 core main 或在 SkillForge-Core Actions → build and publish pages → Run workflow
# 3. 本仓 gh-pages 分支会收到一次新的 commit
```
本仓 Pages 配置（一次性，已在 Settings 里设置）：`Source = Deploy from branch`，Branch = `gh-pages`，Directory = `/(root)`，Custom domain = `skillforge.c8.fit`，勾「Enforce HTTPS」。
## 🔐 安全可信签名链（三层 Ed25519 + Manifest + 可复现构建）
所有发布产物（前端静态文件本身不签名；但 **技能 tarball、CLI 二进制 tarball、二者的 manifest 清单**）都使用同一可信根 Ed25519 密钥签发，任何篡改都会在校验阶段被拒绝。
```
[可信根] dist/signing/root.pub (公开 JSON，含指纹 + 公钥)
│ Ed25519 公钥 32B hex，私钥只在 Core 私仓 Secrets 里
▼
┌─────────────────────────────┐
│ 签名清单 manifests │ ── 每个 manifest 本身也被同一根签名
│ ├─ packages/manifest.json
│ ├─ packages/manifest.json.sfminisig
│ ├─ dist/bin/manifest.json
│ └─ dist/bin/manifest.json.sfminisig
└─────────────────────────────┘
│ manifest 里列 entries[]：name / rel / sha256 / blake2b512 /
│ signature.file / signature.rel / signature.keyIdHex
▼
┌──────────────────────────────────────────────────────────────────┐
│ 每个归档本体签名 .sfminisig (minisign-like untrusted/trusted comment) │
│ packages/-/fix-ci-0.1.0.tgz + .sfminisig
│ packages/-/grep-ts-0.1.0.tgz + .sfminisig
│ packages/-/doc-gen-0.1.0.tgz + .sfminisig
│ dist/bin/skillforge-darwin-arm64-<VER>.tar.gz + .sfminisig (4 平台)
└──────────────────────────────────────────────────────────────────┘
```
- **可信根指纹（当前 v1 根）**：`SF:c0d444ccdf461a76:H1H77scjvT0kZ47lhQWewtEGLt13hRlt6BDhm80RpHE`
- 带外核对：`node -e 'console.log(JSON.parse(require("fs").readFileSync("/tmp/root.pub","utf8")).fingerprint)'`，若与上串不同立即中止安装
- 未来根轮换：新增 `keyIdHex` 进 `signing.publicKeys[]`，旧根保留 180 天缓冲
- **签名格式**：`.sfminisig` 三行 = untrusted comment(timestamp/file/keyid) + Base64(`"SF"` | `ver=1` | `keyId[8]` | `Ed25519 detached sig[64]`) + trusted comment
- 哈希原语：**BLAKE2b-512**（对归档 bytes）+ **Ed25519(libcrypto.sign_detached)**
- **可复现构建保证**：每次 CI 设置 `SOURCE_DATE_EPOCH = git log -1 --format=%ct`，打包 tar 强制：
```bash
tar --sort=name --owner=0 --group=0 --numeric-owner \
--pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime \
-czf out.tar.gz source-dir/
```
所以同 commit 重复 build → tar.gz sha256 完全一致。
### 一键验签（技能包 + CLI 通用）
任何 Node 22+ 的 macOS / Linux 机器：
```bash
# (0) 准备根 + 工具：
curl -sSL https://skillforge.c8.fit/dist/signing/root.pub -o /tmp/root.pub
curl -sSL https://skillforge.c8.fit/dist/signing/verify-sfminisig.mjs -o /tmp/verify.mjs
npm install --no-save libsodium-wrappers-sumo
# (1) 选一个目标：
export VER=0.1.0
# 比如技能：
export NAME=fix-ci
export ARCHIVE=https://skillforge.c8.fit/packages/-/${NAME}-${VER}.tgz
# 或者 CLI：
# export NAME=skillforge-darwin-arm64
# export ARCHIVE=https://skillforge.c8.fit/dist/bin/${NAME}-${VER}.tar.gz
curl -sSL "$ARCHIVE" -o /tmp/x
curl -sSL "$ARCHIVE.sfminisig" -o /tmp/x.sfminisig
# (2) 带外核对指纹：
node -e 'console.log(JSON.parse(require("fs").readFileSync("/tmp/root.pub","utf8")).fingerprint)'
# → 输出应为 SF:c0d444ccdf461a76:H1H77scjvT0kZ47lhQWewtEGLt13hRlt6BDhm80RpHE
# 不一致：镜像投毒 / DNS 污染，立即中止
# (3) 清单签名（技能）或 bins 清单签名（CLI）：
# 技能清单：
curl -sSL https://skillforge.c8.fit/packages/manifest.json -o /tmp/m
curl -sSL https://skillforge.c8.fit/packages/manifest.json.sfminisig -o /tmp/m.sfminisig
# 或 CLI 清单：
# curl -sSL https://skillforge.c8.fit/dist/bin/manifest.json -o /tmp/m
# curl -sSL https://skillforge.c8.fit/dist/bin/manifest.json.sfminisig -o /tmp/m.sfminisig
node /tmp/verify.mjs --file /tmp/m --root-pub /tmp/root.pub # → [verify] OK manifest.json keyId=…
# (4) 归档本体签名：
node /tmp/verify.mjs --file /tmp/x --root-pub /tmp/root.pub # → [verify] OK <name> keyId=…
# (5) 哈希交叉核对 manifest：
grep -o '"sha256":"[a-f0-9]\{64\}"' /tmp/m # 应与 sha256sum /tmp/x 一致
# (6) 全部通过后才 install：
# 技能：skillforge install /tmp/x
# CLI: tar xzf /tmp/x && sudo install skillforge-*/skillforge /usr/local/bin/skillforge
```
### 可信密钥生成（Core 私仓 Secrets 一次性配置）
```bash
cd SkillForge-Core/web-assets
npm install --no-save libsodium-wrappers-sumo
node scripts/sign-generate-keypair.mjs ./secrets-tmp
# → 产出 SF_SIGNING_SK_HEX + SF_SIGNING_PK_HEX 两个文件
# 私钥 → Core 仓 Secrets: SF_SIGNING_SK_HEX
# 公钥 → Core 仓 Secrets: SF_SIGNING_PK_HEX
# （同时公钥 JSON 会在每次构建时被写到 gh-pages/dist/signing/root.pub，不要手动维护）
```
## 下载 CLI 与技能包
- 站点顶部导航 `Download`，或直接打开 `https://skillforge.c8.fit/dist/bin/` 下载对应平台的 CLI 二进制（Rust 多平台 Release，发布在 Core 仓的 Releases）
- 每个技能详情页提供 `tar.gz` + `sha256` + **`.sfminisig` Ed25519 签名** 三个按钮（`/packages/-/<name>-<version>.tgz`），标准完整流程见上一节「🔐 安全可信签名链 → 一键验签」。
## 为什么是 SkillForge
很多 Agent 技能方案停留在“提示词片段”或“仓库模板”层面，缺少版本、依赖、权限与运行边界。SkillForge 试图补上这些基础设施：
- 技能有结构化清单：`skill.yml`
- 技能有执行边界：`allow.read_paths` / `allow.write_paths` / `allow.net_hosts`
- 技能有可复用入口：`skillforge serve <skill>`
- 技能有评测基线：`eval.md`
- 技能能被本地 Agent 和 MCP 客户端共同消费
## 整体架构图
下面这张图展示了 SkillForge 当前仓库里已经落地的节点，以及它们之间的调用方向和关键链路（签名、鉴权、审计、缓存回填）：
```text
┌───────────────────────────────────────────────────────────┐
│ SkillForge（本仓库已全部实现） │
└───────────────────────────────────────────────────────────┘
┌──────────────────────┐ ┌───────────────────────────────┐
│ MCP 客户端 / │◀─MCP────▶│ core/ (Rust) │
│ Claude Code/Cursor │ :18080 │ serve/run/validate/eval │
└──────────────────────┘ └───────────────────────────────┘
│
│ 技能执行 + 沙箱
▼
┌─────────────────────────────────────────────────────────────┐
│ skills/<name>/ skill.yml · SKILL.md · eval.md · scripts │
└─────────────────────────────────────────────────────────────┘
│
│ publish / sync-github / 本地索引
▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ registry/ (本地 CLI + 多源聚合 + 签名链 + RBAC) │
│ ──────────────────────────────────────────────────────────────────────────────────── │
│ 配置: ~/.skillforge/registry/{config.json, credentials.json(0600)} │
│ 本地存储: <repo>/.skillforge/registry/{registry.sqlite, archives/, packages/} │
│ signer keygen / sign / verify + scope publishers/admins 白名单 │
│ search / info / versions / plan / install ── 支持 --remote --sources a,b │
└──────────────────────────────────────────────────────────────────────────────────────┘
│ │ │
│ CLI --github-repo │ CLI --remote 多源聚合 │ CLI --sign
▼ ▼ ▼
┌──────────────────────┐ ┌─────────────────────────────────┐ ┌────────────────────────┐
│ GitHub Releases │ │ registry-service/ (Fastify) │ │ signing: Ed25519 │
│ tarball + .minisig │ │ :18081 · /v1/skills/* 协议 │ │ minisig 风格文本签名 │
└──────────────────────┘ │ + Scope RBAC + Token + Audit │ │ 发布签 · 安装验 │
▲ │ SQLite + Storage(文件/S3 接口) │ └────────────────────────┘
│ sync-github └─────────────────────────────────┘
│ 元数据回写本地 SQLite │ │
│ │ │
┌───────┴─────────────────────────────────┼────────────────┼───────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
│ 归档 tar.gz + 签名 │ │ audit_log 表 │ │ Scope 白名单 │ │ API Tokens │
│ objects storage 抽象 │ │ publish/yank │ │ publishers/ │ │ read/publish │
│ FS / 未来 S3 替换 │ │ scope/token │ │ admins │ │ yank/admin │
└─────────────────────────┘ └──────────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────────────────┐
│ registry-web/ (Next.js)│
│ :18082 │
│ ┌─ 首页 Hero + KPI │
│ ├─ 技能列表（Scope 筛选）│
│ ├─ 技能详情 + 版本对比 │
│ ├─ 审计日志（可过滤） │
│ └─ 协议文档页 │
└──────────────────────────┘
▲
│ 浏览器访问 + 暗色主题切换
```
**图例速记：**
| 模块 | 入口 | 亮点 |
| --- | --- | --- |
| `core/` | `cargo run -p skillforge-core -- serve <skill>` | Agent Loop + Seatbelt 沙箱 + MCP `tools/call` |
| `registry/` | `pnpm --filter registry cli -- …` | 多源优先级 / `@scope` 路由 / Token 0600 / 签名与校验 |
| `registry-service/` | `pnpm registry-service:dev` → :18081 | `/v1/skills` 对齐、publish 签名与 scope 校验、完整审计日志 |
| `registry-web/` | `pnpm registry-web:dev` → :18082 | Shadcn 风格视觉 + 暗/亮主题切换 + 协议文档页一体化 |
| `skills/<name>/` | `skills/fix-ci/` / `grep-ts/` / `doc-gen/` | `skill.yml + SKILL.md + eval.md` 三件套 + 示例脚本 |
## 界面预览 (Web UI Gallery)
所有页面均由 `registry-web/` Next.js 14 SSR 真实数据渲染 + Tailwind；Token / Scope / Users 页面走服务端注入的 admin Bearer 鉴权。
> 💡 点击表格中的缩略图标题即可跳转到对应的页面路径。
| 页面 | 路径 | 预览 | 关键能力 |
| --- | --- | --- | --- |
| 🏠 首页 | [`/`](http://localhost:18082/) | [](.github/screenshots/01-home-page.png) | Hero + ASCII/SVG 架构图、4 项 KPI、精选技能卡片、命令行 CTA |
| 🛒 技能市场 | [`/skills`](http://localhost:18082/skills) | [](.github/screenshots/02-skills-market.png) | Scope 筛选 chip、搜索框、含撤回/已签名 chip 的卡片墙 |
| 📋 技能详情 | [`/skills/@thirdparty/code-review-agent`](http://localhost:18082/skills/@thirdparty/code-review-agent) | [](.github/screenshots/03-skill-detail.png) | 版本表、tarball/签名下载、Ed25519 签名摘要、安装命令 snippet、依赖 chip、侧边元信息（Scope/Source Kind/撤回状态）|
| 🔀 版本对比 | [`/skills/@thirdparty/code-review-agent/diff`](http://localhost:18082/skills/@thirdparty/code-review-agent/diff) | [](.github/screenshots/04-version-diff.png) | From/To 版本下拉、skill.yml + SKILL.md 双列对比、红删绿增行内高亮、服务端从 tarball 流式解包 |
| 🔑 Token 管理台 | [`/settings/tokens`](http://localhost:18082/settings/tokens) | [](.github/screenshots/05-settings-tokens.png) | 颁发 read/publish/yank/admin 4 级 scope 的 Bearer Token、显示 prefix、一键吊销、首次颁发时一次性显示明文提示"只存 hash 不可找回" |
| 🛡️ Scope RBAC 审批流 | [`/settings/scopes`](http://localhost:18082/settings/scopes) | [](.github/screenshots/06-settings-scopes.png) | 左侧 publisher 申请卡片（scope/role/requester/targetKeyId/reason）、右列待审批队列 + Approve/Reject 按钮、批准后自动合并 scope_rules、底部审批审计列表 |
| 👥 用户管理台 | [`/settings/users`](http://localhost:18082/settings/users) | [](.github/screenshots/07-settings-users.png) | userId/displayName/email upsert、roles（user/scope-admin/registry-admin）、disabled 软删除、fallback bootstrap-admin |
| 📜 审计日志 | [`/audit`](http://localhost:18082/audit) | [](.github/screenshots/08-audit-log.png) | 所有 write 操作留痕（publish/yank/token.revoke/scope.approve 等）、按时间倒序、actor+resource+detail JSON 展示 |
| 📖 HTTP API 协议文档 | [`/docs`](http://localhost:18082/docs) | [](.github/screenshots/09-api-docs.png) | `/v1/skills/*` 完整协议、multipart publish 示例、Bearer Token、Ed25519 签名校验流程 |
## 当前能力边界
为了避免文档和实现脱节，这里明确当前版本的边界（已具备完整的本地 + 远端 MVP 链路；距离"面向任意规模组织的生产级平台"的补齐项列在 Roadmap）：
- **Registry 三件套（MVP，可直接跑起来）**：
- 本地 CLI：多源聚合、Bearer Token 鉴权、Scope RBAC、Ed25519 签名发布链、安装计划与按需下载
- 远端 HTTP 服务 `registry-service/`：Fastify + SQLite + 文件系统 Storage 抽象，完整对齐 `/v1/skills` 协议，带 publish/yank/scope 鉴权与审计
- 漂亮的 Web UI `registry-web/`：Next.js 14 App Router + Tailwind（Shadcn 风格视觉），首页/技能列表/技能详情/审计日志/协议文档一站式呈现
- **分发链**：本地 publish、GitHub Release 同步、远端 registry 上传、以及三者之间的索引回写与缓存回填
- **MCP 服务**：已支持技能枚举和 `tools/call` 调用，当前仍是单技能单端点模型，后续可扩展为多技能单端口聚合
- **沙箱**：已支持逻辑白名单和 macOS Seatbelt 自动接入；若宿主环境拒绝 `sandbox-exec`，会自动回退到逻辑白名单模式。平台级沙箱主要覆盖文件工具调用，网络与更广义的进程能力仍待继续收紧
- **内置示例技能**：`fix-ci`、`grep-ts`、`doc-gen` 三个核心示例，覆盖 CI 修复、代码检索和文档生成三个典型场景；更多行业技能可按相同模板扩展
生产化仍需补齐的条目（详见 Roadmap 章节）：Postgres/S3 后端替换、TUF 风格密钥轮换机制、镜像加速与透明缓存、Prometheus 指标 + 结构化日志、Web UI 的 Token/审批流管理等。
## 仓库结构
```text
.
├── core/ # Rust：CLI、技能加载、模型调用、沙箱、MCP
├── registry/ # TypeScript：本地 + 多远端聚合 CLI、签名发布链、RBAC 配置
├── registry-service/ # TypeScript：可部署的远端 HTTP 服务 MVP（Fastify + SQLite + Storage 抽象）
├── registry-web/ # Next.js 14 + Tailwind：Registry Web UI
├── schemas/ # 预留：schema/协议相关资源
├── skills/ # 技能定义：skill.yml / SKILL.md / eval.md / references/
├── docs/ # 使用说明与技能编写文档
└── mirrors/ # 预留：镜像/同步相关目录
```
## 依赖要求
- Rust 工具链（项目当前在 `rustc 1.85` 环境下验证）
- Node.js 22+
- `pnpm` 9+
- `sqlite3` 命令行工具（Registry 测试需要）
- 可选：`ollama`，用于本地模型调用
## 快速开始
### 1. 安装依赖
```bash
pnpm install
```
### 2. 构建 Core CLI
```bash
cargo build -p skillforge-core
```
如果你想直接生成发布构建：
```bash
cargo build --release -p skillforge-core
```
### 3. 运行测试
```bash
cargo test
pnpm --filter registry test
```
### 4. 校验一个技能
```bash
cargo run -p skillforge-core -- validate fix-ci
```
这会加载 `skills/fix-ci/skill.yml`、`SKILL.md`、`eval.md`，并输出解析后的 manifest JSON。
### 5. 运行一个技能
使用 mock 响应可以在没有模型服务时快速验证流程：
```bash
SKILLFORGE_MODEL_MOCK_RESPONSE="计划已生成" \
cargo run -p skillforge-core -- run grep-ts --task "search publish" --token-budget 400
```
如果你已经启动了 Ollama，也可以直接走真实模型：
```bash
export OLLAMA_BASE_URL=http://127.0.0.1:11434
cargo run -p skillforge-core -- run fix-ci --task "修复当前仓库的 CI 配置"
```
### 6. 以 MCP 形式暴露技能
```bash
cargo run -p skillforge-core -- serve fix-ci --port 18080
```
启动后会在 `http://127.0.0.1:18080/mcp` 提供 MCP HTTP 入口。
## CLI 命令
```bash
skillforge --help
skillforge run --help
```
当前命令如下：
- `skillforge run <skill> --task <task> [--model <name>] [--token-budget <n>]`
- `skillforge serve <skill> [--port 18080]`
- `skillforge validate <skill>`
- `skillforge validate-all`
- `skillforge eval <skill>`
- `skillforge eval-all`
全局参数：
- `--repo-root <path>`：指定仓库根目录，默认当前目录
## 模型配置
`skill.yml` 中的 `model.provider` 决定调用后端：
- `ollama`
- `openai`
- `openai-compatible`
相关环境变量：
- `SKILLFORGE_MODEL_MOCK_RESPONSE`：启用 mock 返回，适合本地联调
- `OLLAMA_BASE_URL`：默认 `http://127.0.0.1:11434`
- `OPENAI_API_BASE`：默认 `https://api.openai.com/v1`
- `OPENAI_API_KEY`：使用 OpenAI-compatible 接口时必需
## Skill Manifest 概览
每个技能目录至少包含：
- `skill.yml`
- `SKILL.md`
- `eval.md`
示例：
```yaml
name: grep-ts
version: 0.1.0
description: 在 TypeScript 代码中执行受限搜索并输出结果摘要。
adapter:
kind: raw
origin:
source: local
ref_name: main
sha: workspace
model:
provider: ollama
name: qwen3:8b
max_input_tokens: 800
deps: []
tools:
- read_file
- list_dir
mcp:
exposed: true
description: 暴露 TypeScript 搜索技能给 MCP 客户端。
allow:
read_paths:
- registry
- skills
write_paths: []
net_hosts: []
eval:
fixtures:
- registry/src
```
`skill.yml` 开启了 `deny_unknown_fields`，也就是未声明字段会直接校验失败。
## 示例技能
- `fix-ci`：读取并修复 `.github/workflows/ci.yml`
- `grep-ts`：在受限目录中搜索 TypeScript 代码
- `doc-gen`：更新仓库文档摘要
这些技能既是示例，也是当前运行时能力的集成测试样本。
## Registry CLI + 远端服务 + Web UI
`registry/` 提供本地 + 多源远端聚合注册表 CLI（含显式注册、安装计划、版本列表、版本撤回、多源聚合与 Bearer Token 认证）；`registry-service/` 是一个可启动的 Fastify MVP 服务，对齐 CLI 使用的 `/v1/skills` 协议；`registry-web/` 是 Next.js + Tailwind 的漂亮 Web UI（Shadcn 风格视觉）。
能力分层：
- **CLI 多源聚合 + 认证**（[config.ts](file:///Users/apple/git/SkillForge-Official/registry/src/config.ts) + [index.ts](file:///Users/apple/git/SkillForge-Official/registry/src/index.ts) + [cli.ts](file:///Users/apple/git/SkillForge-Official/registry/src/cli.ts)）
- 源管理：`registry add / remove / list / use / login / logout / config-path`（`source` 是 `registry` 的别名）
- 查询/安装跨源：`search / info / versions / plan / install` 默认只查本地；加 `--remote` 走多源聚合（按优先级与 yanked 状态去重）；`--sources a,b` 指定白名单
- 发布/撤回：`publish`（含 `--github-repo` 可选同步）、`yank`
- 数据目录：
- 项目 `.skillforge/registry/`：`registry.sqlite` 索引、`packages/` 包快照、`archives/` tar.gz
- 用户级 `~/.skillforge/registry/`：`config.json`（公开源/scope）、`credentials.json`（Bearer Token，自动 chmod 0600 + list 检查告警）
- 签名 & 校验：`registry/src/signing.ts` 提供 Ed25519 keygen / sign / verify / minisig 读写；publish 支持 `--sign` 自动签名并生成 `.tar.gz.minisig` 伴随资产；install 支持 `--require-signature` 与 `--trust <pub>` 强制白名单校验
- Scope RBAC：`config.scopePublishers` + 服务端 `/v1/scopes/:scope` 接口；`@scope/*` 的技能只有 publishers/admins 名单内的 keyId 可发布 / 撤回
- **远端 HTTP 服务 MVP**（[registry-service/](file:///Users/apple/git/SkillForge-Official/registry-service) · Fastify + SQLite + 文件系统 Storage 抽象层）
- 对齐协议：`/v1/skills?...`、`/v1/skills/:name/{latest,versions,@:version,package.tar.gz,package.tar.gz.minisig}`
- 写操作：`POST /v1/skills`（multipart：manifest / archive / signature?）上传时可校验签名 & scope 权限；`PATCH /v1/skills/:name/:version/yank` 撤回
- 管理：`PUT/GET /v1/scopes/:scope`、`POST /v1/internal/tokens`（admin scope）
- 可观测：`/v1/audit?limit=&action=&actor=` 审计；服务启动会把 bootstrap token 写入 `data/bootstrap-tokens.json` 便于本地联调
- 启动：
```bash
pnpm --filter registry-service dev # http://localhost:18081
cat registry-service/data/bootstrap-tokens.json
```
- **漂亮的 Registry Web UI**（[registry-web/](file:///Users/apple/git/SkillForge-Official/registry-web) · Next.js 14 App Router + Tailwind + Shadcn 风格组件）
- 首页：Hero + 命令预览卡 + 总数/签名/scope/最新发布 4 张 KPI 卡 + 精选技能网格
- 技能列表：搜索框、scope 标签、撤回开关、响应式卡片网格
- 技能详情：版本表、安装命令代码块、依赖项、签名元信息、近期审计 Tab
- 审计日志：按 action / actor 过滤、跳转回对应技能详情
- 文档页：协议 + 鉴权 + 签名 + RBAC + 审计清单（一站式）
- 启动：
```bash
pnpm --filter registry-web dev # http://localhost:18082
# 如果 18081 没启动，UI 会回退到内置示例数据
```
常用命令：
```bash
pnpm --filter registry cli -- registry list
pnpm --filter registry cli -- registry add official https://registry.skillforge.dev --priority 100 --default
pnpm --filter registry cli -- registry add corp https://registry.corp.example --priority 200 --scopes corp
echo "$OFFICIAL_TOKEN" | pnpm --filter registry cli -- registry login official --token-stdin
# 签名发布链（本地 CLI 侧）
pnpm --filter registry cli -- signer keygen --alias team-a
pnpm --filter registry cli -- signer export-pub team-a > ./team-a.pub
pnpm --filter registry cli -- publish @corp/security-review --sign --scoped
pnpm --filter registry cli -- install @corp/security-review --remote --require-signature --trust ./team-a.pub
# 其它常用
pnpm --filter registry cli -- versions fix-ci --remote
pnpm --filter registry cli -- plan fix-ci --remote
pnpm --filter registry cli -- search fix --remote --sources official
pnpm --filter registry cli -- install fix-ci --target-dir ./downloaded-skills --remote --install-deps
pnpm --filter registry cli -- yank fix-ci@0.1.0 --reason "broken manifest"
```
远端 Registry HTTP 协议（现已在 `registry-service/` 实现）：
- `GET /v1/skills?q=&allVersions=&limit=&includeYanked=` → `{ total, records: SkillRecord[] }`
- `GET /v1/skills/:name/versions?includeYanked=` → `{ name, versions: SkillRecord[] }`
- `GET /v1/skills/:name/@:version?includeYanked=` / `GET /v1/skills/:name/latest` → `SkillRecord`
- `GET /v1/skills/:name/@:version/package.tar.gz` / `…package.tar.gz.minisig`：资产下载；`Authorization: Bearer <token>`（可选，对私有源必填）
- `POST /v1/skills`：写 publish（`Authorization: Bearer <token>` 需含 publish scope；multipart `manifest=JSON` + `archive` + 可选 `signature`）
- `PATCH /v1/skills/:name/@:version/yank`：`{ yanked?: boolean, reason?: string }`，需 yank scope
- `SkillRecord` 字段：`{ name, version, description, releaseTag, publishedAt, assetName, assetUrl, sourceRepo, sourceKind, yanked, deps: string[], publisherKeyId?, signature?: { keyId, algorithm, signature, timestamp, signatureAssetName?, signatureAssetUrl? } }`
- 搜索默认忽略 yanked；`includeYanked=1` 回显；读接口公开，publish/yank 强制鉴权；401 提示 `registry login`，403 提示缺少 token scope
当前 GitHub Release 分发链：
- 每个技能资产命名为 `<skill>-<version>.tar.gz`（签名伴随 `<skill>-<version>.tar.gz.minisig`）
- 默认 tag `v<version>`
- `publish --github-repo` 依赖本机 `gh`
- `sync-github` 通过公开 Releases API 拉取 release 元数据并写回本地 registry
## 开发约束
项目内约束以 [AGENTS.md](AGENTS.md) 为准，关键点包括：
- `core/` 只放 Rust 运行时与校验逻辑
- `registry/` 只放 TS 注册表逻辑
- `skills/<name>/` 目录必须包含技能清单与说明
- 模型调用必须经过 token 预算控制
- 变更 skill schema 时，需要同步 Rust 校验器与示例技能
## 文档导航
- [快速上手](docs/getting-started.md)
- [本地使用与命令别名](docs/local-usage.md)
- [团队本地开发脚本方案](docs/team-local-dev.md)
- [技能编写指南](docs/skill-authoring.md)
- [远端 Registry 服务架构设计](docs/registry-service-architecture.md)
- [English README](README.en.md)
- [English Getting Started](docs/en/getting-started.md)
- [English Local Usage](docs/en/local-usage.md)
- [English Team Local Development](docs/en/team-local-dev.md)
- [English Skill Authoring Guide](docs/en/skill-authoring.md)
## Roadmap
已完成 Roadmap 的四项落地（签名发布链 / Scope RBAC / 可部署的远端 HTTP 服务 MVP / Registry Web UI）。下一步的方向聚焦于「生产化」与「跨团队协作」：
- **签名发布链 2.0**：引入 TUF/Notary 风格的时间戳与根密钥轮换，降低单一 signer 密钥泄露的影响范围
- **存储后端 S3 化**：在现有 `StorageDriver` 接口基础上，补 S3/Azure Blob/GCS 真实实现，让 registry-service 直接用对象存储（保留文件系统回退，便于本地开发）
- **真实数据库**：SQLite MVP → Postgres 或 CockroachDB 适配，并提供 12-factor 配置化（DATABASE_URL / S3_*）
- **Web UI 增强**：版本对比（diff 前后 SKILL.md / skill.yml）、用户与 API Token 管理台、Scope RBAC 在线审批流
- **跨仓库的镜像/加速**：为多源 CLI 增加本地透明缓存 + 源镜像（cache-only / pull-through cache），支持离线环境
- **可观测性**：registry-service 接入 Prometheus 指标（请求数、失败率、publish 体积分位数）+ 结构化 JSON 日志
- **多包协议**：除 tar.gz 外，引入 OCI (distribution-spec) 兼容的镜像分发路径，便于与自建 Harbor / GHCR 对齐
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessUnresponsive