yonatangross/orchestkit · 上手攻略

• 仓库：yonatangross/orchestkit
• 链接：https://github.com/yonatangross/orchestkit
• 分类：AI 开发工具 · Claude Code 增强
• 作者：Tom
• 更新：2026-09-24

---

这是什么

OrchestKit 是 Claude Code 的完整 AI 开发工具包，当前版本包含 107 个 Skills（技能）、36 个 Agents（子代理）、171 个 Hooks（生命周期钩子），装为一个统一的 plugin，宣称"Stop explaining your stack. Start shipping."（不用每次重复说明你的技术栈，直接开始交付）。

核心设计理念：每个 Claude Code 会话都从零开始——OrchestKit 通过 Skills 提供持久化的生产级知识，通过 Agents 提供专业化执行者，通过 Hooks 实现自动化门禁与记忆注入，让 AI 不再需要每次重新学习你的项目规范。

解决什么问题

没有 OrchestKit 时，用 Claude Code 开发：

• 每次都要重复"我们用 FastAPI + async SQLAlchemy 2.0，记得用 cursor pagination 而不是 offset"
• PR 合规检查靠人工或自己写 CI 脚本
• 代码规范靠文档或口头约定，没有自动执行
• 项目上下文不跨会话积累

有了 OrchestKit：

• Skills 提前注入生产级模式（数据库设计、RAG 模式、FastAPI 最佳实践），对话开始就带知识
• Hooks 在每次工具调用前自动检查（禁止写入 id_rsa、禁止直接 commit 到 main、分支保护规则）
• Agents 是专业化执行者，遇到架构决策自动路由到 backend-architect，遇到安全问题自动路由到 security-auditor
• /ork:setup 自动扫描项目并写入 MCP 配置，不需要手动研究该装什么

快速安装

⚠️ 以下命令截至 2026-09-23；v9.x 为稳定版，v10 alpha 每日构建

Claude Code（完整安装）

# 方式一：通过 plugin marketplace（推荐）
/plugin marketplace add yonatangross/orchestkit
/plugin install ork

# 方式二：CLI 等价命令
claude plugin marketplace add yonatangross/orchestkit && claude plugin install ork@orchestkit

# 安装后运行引导向导
/ork:setup

Cursor（同等 plugin，无 Hooks）

Settings → Plugins / marketplaces → add yonatangross/orchestkit → enable ork → open a new chat

Codex（ork-codex 包，命令略有不同）

codex plugin add ork-codex@orchestkit-codex
# 命令入口：$ork-implement（不是 /ork:implement）

Pi / skills.sh 客户端（Skills 部分）

# 安装 Starter 12（推荐先试用这 12 个，不装全套）
npx skills add yonatangross/orchestkit \
  -s doctor -s setup -s explore -s implement -s verify \
  -s review-pr -s commit -s expect -s assess \
  -s brainstorm -s create-pr -s remember

# 安装全部 Skills
npx skills add yonatangross/orchestkit

其他平台

平台	安装方式	覆盖范围
Devin	claude plugin install ork@orchestkit	Skills + Agents（Hooks/Rules 不支持）
Antigravity (agy)	agy plugin install yonatangross/orchestkit	Skills + 36 Agents（via agy plugin）
Muse Code	skills.sh + .agents/skills	Skills 部分

核心用法

关键命令速查

命令	作用
/ork:auto	入口：描述目标，自动路由到对应 Skill
/ork:setup	引导向导：扫描项目，推荐 Skills，写入 MCP 配置
/ork:implement	全栈实现：多 Agent 并行执行
/ork:verify	多 Agent 验证
/ork:review-pr	PR 审查（6 个并行专业化 Agent）
/ork:commit	Conventional commit（自带 pre-checks）
/ork:explore	分析陌生代码库
/ork:remember	保存到持久化记忆
/ork:doctor	健康检查：报告已装版本、缺失配置

/ork:implement 工作流示例

# 在 Claude Code 中
/ork:implement 为这个 FastAPI 项目添加 JWT 认证，包含 refresh token 轮转

OrchestKit 会：

1. 调用 backend-architect agent 规划架构
2. 调用 frontend-dev agent（如涉及 API 契约）
3. 并行执行生成 + 测试
4. 自动运行 /ork:verify 多层验证
5. 输出可直接 merge 的 PR

MCP Server 配置（/ork:setup 会自动写入）

⚠️ Context7 是硬性前置依赖：22/36 个 Agent 依赖 mcp__context7__* 工具（最新库文档）。若不配置这些 Agent 将从训练数据回答，无报错。

// .mcp.json（或 claude_code 的 MCP 配置）
{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "memory": {
      "type": "http",
      "url": "https://mcp.memory.dev/mcp"
    },
    "sequential-thinking": {
      "type": "http",
      "url": "https://mcp.seqthink.com/mcp"
    }
  }
}

• Context7 免费额度：1,000 请求/天（公开仓库），无需账号
• Context7 Pro：$10/月/席，提升至 5,000 请求，支持私有仓库（加 Authorization: Bearer ${CONTEXT7_API_KEY} 请求头）
• 若不加 key：推荐省去请求头用无 key 免费入口，比加了无效 key 更稳定

Hooks 配置示例（.claude/orchestkit 目录）

{
  "hooks": {
    "precommit": {
      "blockMainBranch": true,
      "requireTests": true,
      "maxFileSizeKB": 500
    },
    "pretool": {
      "blockSecretWrite": true,
      "protectedPaths": ["~/.aws/", ".env.production"]
    }
  }
}

典型适用场景

场景	OrchestKit 怎么帮忙
新项目启动	/ork:setup 自动扫描技术栈，推荐所需 Skills 和 MCP servers
安全审计	/ork:review-pr 内置 8 层安全验证（Secrets 检查、SQL 注入模式、依赖漏洞）
代码审查	/ork:review-pr 6 个并行专业化 Agent（安全 + 性能 + 架构 + 测试 + 文档 + 规范）
陌生代码库	/ork:explore 分析并生成架构摘要，写入持久化记忆
Feature 实现	/ork:implement 多 Agent 并行：架构 + 前端 + 后端 + 测试一次性完成
自动化提交	/ork:commit conventional commit + pre-checks（测试、分支保护、文件大小）
跨会话记忆	/ork:remember 自动持久化关键决策，项目上下文跨对话保留
Cursor/Cursor 迁移	同样的 plugin 安装方式，Skills 全兼容

坑与注意

⚠️ Context7 是隐式硬依赖：不配置 Context7，22 个 Agent 会"静默降级"——不报错，但回答来自训练数据而非最新文档。建议 /ork:doctor 先跑一遍确认。

⚠️ 不要手动编辑已安装的 Skills：Skills 以文件形式安装，plugin 更新时会覆盖，自定义修改会丢失。官方推荐的自定义扩展方式：user-level skills、project skills、向上游提 PR、或在 [docs/extending-skills.md](https://github.com/yonatangross/orchestkit/blob/main/docs/extending-skills.md) 查找正确姿势。

⚠️ Hooks 写入本地文件：~/.local/state/orchestkit/events.jsonl，单个文件 10MB 自动轮转。这是产品设计，不是 bug，官方有意为之（git-safety 和 chain-staleness hooks 依赖自身历史）。如需关闭单个功能：有对应环境变量（ORK_DISABLE_DEBT_TRACKER、ORK_NO_NOTIFY 等）。

⚠️ Hooks 隐私边界：Hooks 读取 prompt 和文件内容来做 allow/deny 决策，读完即弃，不存储原文。lifecycle events（如会话结束）、hook 指标（事件名、工具名、耗时）会写入本地 JSONL。无内置全局 kill switch，要完全停止只能 disable plugin。

⚠️ Cursor 无 Hooks：Cursor 的 OrchestKit plugin 只有 Skills + Agents，不含 Claude 专用 Hooks 脚本。

⚠️ Codex 命令前缀不同：Claude Code 用 /ork:implement，Codex 用 $ork-implement（美元符，非斜杠）。

⚠️ v10 alpha vs v9.x 稳定版：v10 每日构建，功能最新但可能有 regressions；生产环境建议用 v9.x（ork@orchestkit 固定指向稳定版）。

⚠️ 网络访问默认关闭：所有 hooks/dist/*.mjs 中无硬编码远程地址，无主动上报。唯一例外：配置 ORK_TYPESAFE_API_KEY + ORK_SESSION_CATEGORY_PROVIDER=jev 时会调用 api.typesafe.ai 做会话分类（可选择 shadow 模式只记录不改变行为）。

与同类对比

方案	Skills	Agents	Hooks	宿主支持
OrchestKit	107	36	171	Claude Code, Cursor, Codex, Pi, Devin, Antigravity, Muse
Superpowers（Anthropic 官方）	✅ Process 类	✅	✅	Claude Code
MCP Servers（自建）	-	-	-	按需配置
Cursor Rules	本地 .md	-	-	Cursor 专用

OrchestKit vs Superpowers：Superpowers 是 Anthropic 官方出品，偏重"过程模式"（流程规范）；OrchestKit 偏重"生产工程模式"（真实代码规范、门禁、自动化），两者互补而非替代。

OrchestKit vs 自建 MCP 体系：后者灵活性更高，但需要自己维护 Skills 知识和 Agent 提示词，工作量不小。OrchestKit 把这些都做好了，一键安装。

一句话核心差异：OrchestKit 把 Skills（知识）+ Agents（专家）+ Hooks（自动化）做成三位一体，一套 plugin 全家桶，无需自己组装。

一句话推荐结论

Claude Code 完整工具链，装完即上手——107 Skills 解决了"每次重说技术栈"的问题，171 Hooks 解决了"规范靠自觉"的问题，36 Agents 解决了"架构决策要人盯着"的问题。/ork:setup 跑一遍，30 分钟内项目配置完成。⚠️ Context7 是硬依赖，安装后第一件事跑 /ork:doctor 确认配置完整。