setup

OrchestKit 设置向导

个性化入门流程：扫描代码库、检测技术栈、推荐技能和 MCP，并生成可执行的改进计划。

适用场景

• 安装 OrchestKit 后首次使用（/plugin install ork）
• 加入新项目并希望为其调整 OrchestKit
• 定期使用 --rescan 跟踪改进情况
• 需要安全的用户级安装确认的企业用户

快速开始

setup              # Full 7-phase wizard
setup --rescan     # Re-scan after changes (skip safety phase)
setup --score-only # Just show readiness score
setup --plan-only  # Just show improvement plan
setup --configure  # Jump directly to Phase 3.5: project configuration wizard

参数解析

FLAG = "$ARGUMENTS[0]"  # First token: --rescan, --score-only, --plan-only, --channel
# If no arguments, run full 7-phase wizard.
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

关键：任务管理是强制要求（CC 2.1.16）

在进行任何其他操作之前，先创建任务以跟踪进度：

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Setup: onboarding wizard",
  description="Personalized setup scanning codebase and configuring OrchestKit",
  activeForm="Running setup wizard"
)

# 2. Create subtasks for key phase groups
TaskCreate(subject="Scan & detect stack", activeForm="Scanning codebase and detecting stack")
TaskCreate(subject="Safety & configure", activeForm="Checking config and running configuration wizard")
TaskCreate(subject="Recommend skills & MCPs", activeForm="Matching stack to skills and MCPs")
TaskCreate(subject="Score & plan", activeForm="Computing readiness score and improvement plan")

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])
TaskUpdate(taskId="5", addBlockedBy=["4"])

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done

各阶段

阶段	内容	使用的工具	输出
1. 扫描	检测语言、框架、基础设施和现有配置	Glob、Grep、Read	原始扫描数据
2. 技术栈	对检测到的技术栈分类并评估置信度	—	技术栈档案
3. 安全	检查现有配置，确认范围（用户/项目）	Read、AskUserQuestion	安装确认
3.5. 配置	交互式项目配置向导 → 将环境变量块写入项目级设置	Read、Write、AskUserQuestion	已配置的设置文件
3.6. 防护	将 ork 的规范 permissions.deny 负载交付到会强制执行的范围（插件的 settings.json 不起作用：CC 只读取 agent/subagentStatusLine，#3835）。运行 node ${CLAUDE_SKILL_DIR}/scripts/write-operator-permissions.mjs --scope user --dry-run，展示新增规则和仅输出的沙箱建议，然后仅在用户明确同意后，才不带 --dry-run 重新运行。该脚本会备份文件并打印一条命令即可执行的回滚指令。绝不可在未同时完成试运行和获得同意的情况下写入。	Bash、AskUserQuestion	已强制执行的拒绝规则 + 回滚指令
4. 技能	将技术栈与技能匹配，并建议自定义技能	Grep、Glob	技能建议
5. MCP	根据技术栈和不足之处推荐 MCP	Read、Bash	MCP 建议
6. 评分	计算就绪度评分（0-10，共 6 个维度）	以上所有数据	就绪度评分
7. 计划	提供带可运行命令的优先级改进项	—	行动计划

---

阶段 1：扫描

加载详细信息：运行 Read("references/scan-phase.md")，查看完整扫描命令（20 个并行 Glob 探测 + 依赖文件读取 + 模式检测计数）。

扫描包清单（package.json、pyproject.toml、go.mod、Cargo.toml 等）、基础设施（Docker、GitHub Actions、Terraform、K8s）以及现有的 CC 配置。模式检测会统计 API 路由、React 组件、模型和测试的数量，用于建议自定义技能。

阶段 2：技术栈检测

先加载技术栈快照。 分支技能不会运行 frontmatter 钩子（#4683），因此请自行运行加载器，并留意其 additionalContext：

echo '{"tool_name":"Bash","tool_input":{}}' | node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/setup-env-detector

将扫描结果归类为技术栈档案，并展示给用户（语言、框架、数据库、基础设施、测试、现有 CC 配置）。

加载 Read("references/stack-skill-mapping.md")，查看完整的技术栈到技能映射表、MCP 推荐矩阵和自定义技能建议模式。

阶段 2b：渠道检测

阶段 3：安全检查

加载详情：Read("references/safety-check.md")，查看完整的 AskUserQuestion 提示词和冲突检测逻辑。

提供三种安装范围：仅用户（推荐，对队友不可见）、整个项目（提交到仓库）或已安装（跳过并进入配置）。检查是否已安装 OrchestKit，以及是否存在冲突插件。

Console 身份验证（CC 2.1.79+）： 通过 Anthropic Console（API 计费）进行身份验证的用户可以运行 claude auth login --console，替代默认的 OAuth 流程。适用于采用按使用量计费的 API，而非 Pro/Team 订阅的团队。

团队入职（CC 2.1.101+）： /team-onboarding 会根据本地 CC 使用模式生成队友入职指南。建议在设置完成后运行此命令，为新团队成员创建入职文档。

企业 TLS（CC 2.1.101+）： 默认信任操作系统 CA 证书存储区，无需额外设置，企业 TLS 代理即可正常工作。如有需要，可设置 CLAUDE_CODE_CERT_STORE=bundled，仅使用捆绑的 CA。

提示词缓存（CC 2.1.108+）： 对于使用 API 密钥、Bedrock、Vertex 或 Foundry 的用户，建议设置 ENABLE_PROMPT_CACHING_1H=1，将提示词缓存 TTL 从 5 分钟延长至 1 小时。这能显著降低长时间 OrchestKit 会话（brainstorm、implement、cover 链）的 token 成本。自 CC 2.1.110 起，会话回顾默认启用（即使停用了遥测功能）。

TUI 模式（CC 2.1.110+）： 建议使用 /tui fullscreen，避免长时间会话期间出现闪烁。配合在 /config 中设置 autoScrollEnabled: false，可在回顾 brainstorm/implement 输出时手动控制滚动。/focus 命令可提供精简视图（提示词 + 单行工具摘要 + 最终响应）。

插件安装（CC 2.1.157+）： .claude/skills 中的插件无需市场即可自动加载——对于本地/开发环境安装，将插件放入该目录即可。claude plugin init <name> 会在 .claude/skills 中创建新的插件骨架。

--dangerously-skip-permissions 策略（CC 2.1.121 + 2.1.126，#1583）： 此标志的作用范围已大幅扩展。自 2.1.126 起，它会跳过对 .claude/、.git/、.vscode/、Shell 配置文件（~/.bashrc、~/.zshrc 等）以及“其他先前受保护路径”的确认提示；自 2.1.121 起，.claude/skills/、.claude/agents/、.claude/commands/ 已可跳过确认提示。只有灾难性的删除命令（例如 rm -rf /）仍会触发确认。不建议在共享工作站、CI 运行器和入职会话中使用此标志。 建议改用 src/hooks/README.md 中的自动批准权限钩子——它们可提供细粒度的允许列表，而不会全面停用安全防护。若用户在配置期间启用此标志，设置向导应发出警告（而非阻止）。

阶段 3.5：项目配置向导

加载详情：Read("references/configure-wizard.md")，查看完整的 6 步交互式配置流程（分支策略、提交范围、性能遥测、日志详细程度、Webhook 遥测；第 3 步 localhost 浏览器已停用）及环境变量参考。

也可通过 setup --configure 直接访问——跳过阶段 1–3。

---

阶段 4：技能推荐

使用 AskUserQuestion 展示技能类别，提供 4 个关注方向（全栈、后端、前端、DevOps），并设置 multiSelect: true。加载 Read("references/stack-skill-mapping.md")，查看映射表和自定义技能建议。

阶段 5：MCP 推荐

读取 .mcp.json 和 ~/.claude/settings.json，检查已安装的 MCP 与推荐的 MCP。加载 Read("references/stack-skill-mapping.md")，获取 MCP 推荐矩阵。以开关形式展示，并附上安装命令。

CC 2.1.121+ 提示（#1541）： 对于普遍需要的 T2 三件套（memory、context7、sequential-thinking），建议在其 .mcp.json 条目中设置 "alwaysLoad": true。这样可跳过逐个技能的 ToolSearch 探测，让冷启动速度提升约 150ms。旧版 CC 会静默忽略此键，因此可以放心提前添加。

插件生命周期清理（CC 2.1.121+，#1544）： 在清理部分提及 claude plugin uninstall <name> --prune——它会递归清理，并移除已变成孤立依赖的自动安装依赖。独立运行 claude plugin prune 会执行相同的清理，但不会卸载任何内容；dream 每周运行一次。

阶段 6：就绪度评分

根据 6 个维度计算综合评分（0-10）。加载 Read("references/readiness-scoring.md")，获取各维度权重、评分展示模板、记忆集成方式和改进计划模板。

阶段 7：改进计划

按 P0/P1/P2 优先级生成可直接运行的建议。模板和记忆持久化模式请参阅 readiness-scoring.md。

阶段 7b：CLAUDE.md 健康检查

生成改进计划后，检查用户的 CLAUDE.md 是否适合采用 CC 2.1.59+ 的模块化结构。在 CC 2.1.277+ 中，如果项目没有 CLAUDE.md，AGENTS.md 可承担这一角色，因此请针对项目使用的指令文件执行相同检查。

加载详情：Read("references/claude-md-health.md")，获取分析步骤、阈值、@import 语法和 .claude/rules/ 路径范围规则。

# Quick check
Bash(command="wc -l CLAUDE.md 2>/dev/null | awk '{print $1}'")
Glob(pattern=".claude/rules/*.md")

如果 CLAUDE.md 超过 200 行且不存在 .claude/rules/，建议拆分。展示参考文档中的输出模板。

设置后

提示（CC 2.1.69+）： 设置完成后，运行 /reload-plugins，无需重启会话即可激活所有插件变更。

提示（CC 2.1.90+）： 刚开始使用 Claude Code？试试 /powerup，通过带动画演示的互动课程学习核心功能。

阶段 9：遥测与 Webhook

以前位于 configure 中。现在作为单一入口的一部分，纳入设置流程。

加载详情：Read("references/telemetry-setup.md")，获取完整配置流程。

使用 AskUserQuestion 询问用户偏好：

模式	事件	身份验证	开销
流式传输到 webhook	通过 HMAC 签名的 http-sink 发送分析事件和 SessionEnd 摘要	ORCHESTKIT_HOOK_TOKEN	批处理，异步
跳过	不发送遥测数据	无	无

如果选择流式传输：

1. 询问 webhook URL
2. 将 webhookUrl 保存到 .claude/orchestration/config.json
3. 提醒用户设置 ORCHESTKIT_HOOK_TOKEN 环境变量

每事件原生 HTTP 钩子生成器（通道 1）已在 #3867 中删除；没有任何内容会向 settings.local.json 写入 type: "http" 条目。

阶段 10：可选集成

加载详情：Read("references/integrations.md")，获取设置步骤。

涵盖特定 CC 版本的设置（CC 2.1.7 MCP 延迟加载、CC 2.1.20 任务删除、CC 2.1.23 加载动画动词、CC 2.1.79 轮次时长显示）以及 monorepo 工作树优化。

Monorepo 稀疏路径（CC 2.1.76+）

如果阶段 1 扫描检测到 monorepo（pnpm-workspace.yaml、nx.json、lerna.json、turbo.json 或 package.json workspaces），建议在 .claude/settings.json 中配置 worktree.sparsePaths：

{
  "worktree": {
    "sparsePaths": ["src/", "packages/core/", "tests/", "scripts/"]
  }
}

这样，--worktree 和 Agent 的 isolation: worktree 会通过 git sparse-checkout 仅检出所列目录，在大型 monorepo 中显著提速。

多目录插件播种（CC 2.1.79+）

CLAUDE_CODE_PLUGIN_SEED_DIR 现在支持多个目录，目录之间使用平台路径分隔符分隔（Unix 上为 :，Windows 上为 ;）：

export CLAUDE_CODE_PLUGIN_SEED_DIR="/shared/team/plugins:/shared/org/plugins"

这对有多个插件来源的团队很有用，例如同时使用组织共享插件目录和团队专属目录。Claude Code 会在启动时扫描所有列出的目录，查找插件定义。

从 .zip 一次性加载插件（CC 2.1.128 / 2.1.129）

无需承诺安装到市场即可评估插件，适用于试用同事分支的构建版本、CI 生成的 PR 构建产物，或发布前的 OrchestKit 预发布 .zip：

• --plugin-dir <path-to-zip>（CC 2.1.128+）：在当前会话中将本地 .zip 归档加载为插件。此前此标志只接受目录，现在也接受归档。

  claude --plugin-dir ./vendor/some-plugin.zip
  

• --plugin-url <url>（CC 2.1.129+）：从 URL 获取 .zip，并仅在当前会话中加载。退出 CC 后，插件会被丢弃，不会写入 ~/.claude/plugins/。

  claude --plugin-url https://example.com/some-plugin.zip
  

这两种方式都是仅限当前会话的试用路径；如需永久安装，请通过市场使用标准的 /plugin install 流程。完整说明请参阅 ${CLAUDE_PLUGIN_ROOT}/skills/configure/references/cc-version-settings.md § CC 2.1.128/2.1.129。

CLI 标志

标志	行为
（无）	完整向导（阶段 1-10）
--rescan	重新扫描并评分，跳过安全阶段
--configure	直接跳转到阶段 3.5：项目配置向导
--score-only	显示当前就绪度评分（仅阶段 6）
--plan-only	显示改进计划（仅阶段 7）
--telemetry	跳转到阶段 9：遥测/ Webhook 设置
--preset	应用预设（complete/standard/lite/hooks-only/monorepo）

预设（通过 --preset）

应用预设，无需运行完整向导即可快速配置 OrchestKit：

预设	技能	Agent	钩子	适用场景
complete	91	31	96	全面启用，发挥全部能力
standard	91	0	96	技能 + 钩子，不含 Agent
lite	10	0	96	仅包含核心工作流技能
hooks-only	0	0	96	仅启用安全钩子
monorepo	91	31	96	完整配置 + monorepo 工作区检测

加载预设详情：Read("references/presets.md")

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
scan-phase.md	阶段 1：20 个并行 Glob 探测 + 模式检测
safety-check.md	阶段 3：安装范围和冲突检测
configure-wizard.md	阶段 3.5：6 步交互式项目配置
claude-md-health.md	阶段 7b：CLAUDE.md 模块化结构分析
telemetry-setup.md	阶段 9：Webhook/遥测配置
integrations.md	阶段 10：CC 版本设置
presets.md	预设定义和技能/Agent 矩阵

CC --channels + 控制台身份验证（2.1.128+）

--channels（按组织路由通知渠道）现在也支持通过控制台（API 密钥）进行身份验证，不再仅限于 OAuth；但组织必须通过管理 API 设置 channelsEnabled: true。如果用户使用 API 密钥身份验证运行 claude --channels=...，而组织配置中没有该标志，渠道选择会被静默忽略。检测到 API 密钥身份验证，且用户选择安装任何渠道路由技能或 Agent 时，设置向导会提示此情况。

相关技能

• ork:doctor — 健康诊断（向导会使用其检查项）
• ork:configure — 内部配置（由向导的阶段 3.5、9、10 调用）
• ork:remember — 知识持久化（向导会播种初始模式）
• ork:explore — 深度代码库分析（向导会提供后续操作链接）
• ork:help — 技能目录（向导会显示相关子集）