SkillForge

# 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 对齐