setup

/ouroboros:setup

在 Claude Code 会话中引导完成 Ouroboros 设置。

其他运行时（Codex、Copilot、OpenCode 等）请通过 CLI 配置，例如运行 ouroboros setup --runtime codex 或 ouroboros setup --runtime copilot。请参阅 入门指南。

用法

ooo setup
/ouroboros:setup
/ouroboros:setup --uninstall

Claude 设置会确认运行时配置文件（MCP 1.x 上的 Claude Agent SDK），并可选择向项目的 CLAUDE.md 添加 Ouroboros 参考区块。 它会有意保持 ~/.claude/mcp.json 不变，因为该文件由市场插件配置管理。[claude] 及其显式别名 [claude-sdk] 使用 MCP 1.x。该插件会在独立的 MCP 2 进程中启动 [mcp]，并使用无依赖的 [claude-cli] 工作进程。

设置向导流程

除非某个步骤另有说明，否则请使用当前运行时的 ask_user 功能提问。

Python 运行时（必需）

在运行下方任何代码片段之前，请在同一个 shell 中定义此解析器。它只接受 Python 3.12 或更高版本（依次检查 python3、python，然后是 uv），并保留参数和标准输入。传递给 ouroboros_python 的每个参数都必须加引号。

ouroboros_python() {
  if command -v python3 >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 "$@")
    return
  fi
  if command -v python >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python "$@")
    return
  fi
  if command -v uv >/dev/null 2>&1; then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command uv run --no-project --quiet --python '>=3.12' python "$@")
    return
  fi
  printf '%s\n' 'Ouroboros skills require Python >= 3.12 or uv on PATH.' >&2
  return 127
}

步骤 0.5：社区支持

如果 ~/.ouroboros/prefs.json 中的 star_asked 不为 true，请询问：“Ouroboros 免费且开源。给 GitHub 项目点星能帮助其他开发者发现它。要为仓库点星吗？”并提供 在 GitHub 上点星（运行 gh api -X PUT /user/starred/Q00/ouroboros）和 暂时跳过 两个选项。无论用户选择哪个选项，都请将 star_asked: true 合并到 prefs 文件中，同时保留现有键：

ouroboros_python - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
try:
    with open(path, encoding='utf-8') as f:
        prefs = json.load(f)
    if not isinstance(prefs, dict):
        prefs = {}
except Exception:
    prefs = {}
prefs['star_asked'] = True
with open(path, 'w', encoding='utf-8') as f:
    json.dump(prefs, f, indent=2)
    f.write('\n')
PY

步骤 1：环境检测

ouroboros_python --version
which uvx 2>/dev/null && uvx --version 2>/dev/null
which claude 2>/dev/null
uv python list 2>/dev/null | grep "cpython-3.1[2-9]"

此解析器已拒绝低于 3.12 的 Python，并会回退到由 uv 管理的解释器；但这并不能使 [claude-sdk] 和 MCP 2 配置文件具备导入兼容性。请报告检测结果，然后：

环境	操作
Python >= 3.12 + Claude CLI	就绪：配置 [claude] SDK/MCP 1 和技能
uvx + Python >= 3.12	可在其他环境中使用 MCP：使用受支持的、由 CLI 驱动的运行时设置，以隔离运行 ouroboros-ai[mcp]
仅有 Python < 3.12	运行 uv python install 3.12，然后重新运行 ooo setup
没有包运行器或 Ouroboros 包	安装 uv（见下文），然后重新运行 ooo setup

优先通过包管理器安装 uv：pipx install uv、pip install --user uv 或 brew install uv；供应商提供的单行命令 curl -LsSf https://astral.sh/uv/install.sh | sh 仅作为最后手段。

重要：绝不要同时安装 [mcp,claude]、[mcp,claude-sdk] 或 [all,mcp]，也绝不要编写直接的 ouroboros 或 python -m ouroboros MCP 回退方案。MCP 2 启动器必须使用隔离的 uvx --isolated --python '>=3.12' --from 'ouroboros-ai[mcp]' ... 或 pipx run --spec 'ouroboros-ai[mcp]' ... 进程。仅支持 [mcp,claude-cli]，因为 CLI 工作进程在独立进程中运行。不要在 ~/.claude/mcp.json 中写入 Ouroboros 条目；该注册由插件管理。

步骤 1.5：运行时配置

将 Claude 运行时选择写入 ~/.ouroboros/config.yaml。欢迎引导和 CLI 会读取此文件；此向导中的其他操作都不会写入该文件。本步骤绝不会触碰 ~/.claude/mcp.json。

在与下面每条命令相同的 shell 中定义 ouroboros_cli（shell 状态不会在命令之间保留）：

ouroboros_cli() {
  if command -v ouroboros >/dev/null 2>&1; then
    command ouroboros "$@"
  else
    uvx --isolated --python '>=3.12' --from 'ouroboros-ai' ouroboros "$@"
  fi
}
ouroboros_cli config show orchestrator
ouroboros_cli config show llm

仅当 orchestrator.runtime_backend 为 claude 或 claude_mcp，且 llm.backend 为 claude 时，欢迎引导才算就绪。文件或配置段缺失都视为未设置。

• 两个条件都满足：已配置。跳至步骤 2。
• runtime_backend 为 claude_mcp，但 llm.backend 不是 claude：运行 ouroboros_cli setup --runtime claude-cli --non-interactive（保留 CLI 传输方式）。
• runtime_backend 是其他运行时（例如 codex）：询问用户是否要将默认运行时切换为 Claude。如果用户拒绝，则保留现有配置并跳至步骤 2。
• 其他情况（runtime_backend 为 claude，但 llm.backend 是其他值；没有配置；没有 orchestrator 配置段），或者用户同意切换后，运行：

ouroboros_cli setup --runtime claude --non-interactive

两条 setup 命令都会设置 llm.backend: claude；--runtime claude 会设置 orchestrator.runtime_backend: claude，而 --runtime claude-cli 会设置 claude_mcp。 如果失败，显示错误并继续向导；步骤 4 会报告运行时未配置。

步骤 2：MCP 配置边界

告知用户：默认的 Claude SDK 配置文件仍使用 MCP 1.x，插件拥有的 MCP 服务则通过 [claude-cli] worker 单独运行 MCP 2。 **不要创建、更新或移除 ~/.claude/mcp.json。**现有条目可能由用户管理，也可能属于其他兼容的运行时。高级 MCP 工作流需要由宿主管理的隔离 [mcp] launcher；该 launcher 由 Claude marketplace 插件或其他受支持的宿主配置拥有。

步骤 3：CLAUDE.md 集成（可选）

询问用户是否要选择集成 / 跳过 / 先预览，将这段约 40 行的参考内容（流水线、命令表、Agent 目录）添加到项目的 CLAUDE.md。选择先预览时，显示内容：

# Ouroboros — Specification-First AI Development

> Before telling AI what to build, define what should be built.
> As Socrates asked 2,500 years ago — "What do you truly know?"
> Ouroboros turns that question into an evolutionary AI workflow engine.

Most AI coding fails at the input, not the output. Ouroboros fixes this by
**exposing hidden assumptions before any code is written**.

1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
2. **Ontological Precision** — Solve the root problem, not symptoms
3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs

```
Interview → Seed → Execute → Evaluate
    ↑                           ↓
    └─── Evolutionary Loop ─────┘
```

## ooo Commands

Each command loads its agent/MCP on-demand. Details in each skill file.

| Command | Loads |
|---------|-------|
| `ooo` | — |
| `ooo interview` | `ouroboros:socratic-interviewer` |
| `ooo seed` | `ouroboros:seed-architect` |
| `ooo run` | MCP required |
| `ooo evolve` | MCP: `evolve_step` |
| `ooo evaluate` | `ouroboros:evaluator` |
| `ooo unstuck` | `ouroboros:{persona}` |
| `ooo status` | MCP: `session_status` |
| `ooo setup` | — |
| `ooo help` | — |

## Agents

Loaded on-demand — not preloaded.

**Core**: socratic-interviewer, ontologist, seed-architect, evaluator,
advocate, contrarian, judge
**Support**: hacker, simplifier, researcher, architect

选择集成时：将 CLAUDE.md 备份为 CLAUDE.md.bak，追加该内容并确认。

步骤 4：验证

使用步骤 1.5 中的 config show 命令确认，已保存的 Ouroboros 配置选择了默认的 Claude Agent SDK 运行时 （使用 MCP 1.x），且此设置未修改 ~/.claude/mcp.json。不依赖项的 Claude CLI worker 仍是一个独立、显式的 [claude-cli] 选择，用于隔离的 MCP 2 进程。

步骤 5：成功摘要

Ouroboros Setup Complete!

Mode:                     Claude Agent SDK (MCP 1.x)
MCP Server:               Host-owned (config not mutated)
CLAUDE.md:                <integrated | skipped>

Next: ooo interview "your project idea" | ooo tutorial | ooo help

步骤 5.1：模型选择（Claude Code）

提供可选的模型控制。询问：“설정이 완료됐어요. 기본 모델 설정으로 바로 시작할 수 있고, 모델은 언제든 나중에 바꿀 수 있어요.”（标题 모델 설정）：

• 바로 시작하기 (권장)：使用默认模型设置立即开始工作。继续步骤 5.5。
• 직접 모델 설정하기：逐步更改模型，或输入列表中没有的模型 ID 并将其固定。阅读并遵循 ../config/SKILL.md。在本地 Claude Code harness 中，会在用户的浏览器中打开设置界面，地址为临时的 localhost 地址。用户可以随时通过 ooo config 重新打开；此选择不会永久锁定模型。

步骤 5.5：现有代码库扫描

将现有 Git 仓库和关联的 worktree 注册到 Ouroboros DB 中，以便访谈将其用作现有代码库的上下文。仅使用 MCP 工具，不要使用 CLI 或 Python 脚本。

加载 MCP 工具（延迟架构防护）

Ouroboros 工具可能会延迟加载，某一轮加载的架构可能到下一轮就会卸载。每次调用 ouroboros_* 前，请立即使用当前运行时的工具发现功能加载该工具：对于 ouroboros_brownfield，使用 "+ouroboros brownfield"（扫描和之后的 set_defaults 调用都需要）。未加载架构的工具调用会失败并显示 "Invalid tool parameters"。如果工具已可调用，发现操作不会产生任何影响，预期会返回空结果。如果该工具确实不存在，则跳过此步骤并继续执行第 6 步。

1. 扫描并注册：

   Tool: ouroboros_brownfield
   Arguments: { "action": "scan" }
   

   扫描从 scan_root 开始（默认：用户的主目录），最多深入两级目录， 并跳过以点开头的目录和 node_modules 等嘈杂目录。扫描过程中发现的 普通仓库（.git 目录）和链接工作树（.git 文件）都只注册自身。 不会展开 Git 工作树系列。没有远程仓库或拥有任意远程仓库名称的仓库 均符合条件。保留现有默认项。

2. 扫描响应中的 text 已包含带默认标记的编号列表。不要额外调用 MCP 来列出或查询仓库。 在代码块中用纯文本两列网格显示所有仓库（不要使用 Markdown 表格），并保留原样返回的 * 默认标记：

   Scan complete. 8 repositories registered.
   
    1. repo-alpha                   5. repo-epsilon
    2. repo-bravo *                 6. repo-foxtrot
   

   如果未找到仓库，则跳至第 6 步。

3. 不要使用当前运行时的 ask_user 对话框进行选择。 工具调用之间输出的文本不保证会呈现，因此对话框可能在列表未显示时就出现，而且选项预览会截断长列表。请改为以仓库网格作为最终消息结束本轮，然后附上提示：

   • 存在默认项：Current defaults: <names> (numbers <numbers>)，然后 Reply with repo numbers to change defaults (e.g. "6, 18, 19"), "keep" to keep the current defaults, or "none" to clear them.
   • 没有默认项：No defaults set. Reply with repo numbers to set defaults (e.g. "6, 18, 19"), or "none" to run interviews in greenfield mode.

4. 下一轮中：输入数字（任意分隔符）以选择相应 ID；输入 "keep" 可跳过 MCP 调用并保持默认项不变；输入 "none" 可清除全部默认项；其他输入 则重新显示提示（绝不猜测）。然后只调用一次以替换全部默认项（无默认项时 "indices": ""）：

   Tool: ouroboros_brownfield
   Arguments: { "action": "set_defaults", "indices": "<comma-separated IDs>" }
   

   确认最终默认项，或确认访谈将以 greenfield 模式运行，并说明之后可通过 ooo setup 或 ooo brownfield 修改这些设置。

第 6 步：首次项目提示

建议使用 ooo interview "Build a CLI tool for [something you need]" 或 ooo tutorial。

卸载

使用 --uninstall 时，请请求确认，并说明这只会从 CLAUDE.md 中移除 Ouroboros 区块，不会移除插件文件、种子或项目数据。若用户确认：

1. 保持 ~/.claude/mcp.json 不变
2. 从 CLAUDE.md 中移除 到 区块（如果存在）
3. 确认："Ouroboros plugin configuration removed. To remove plugin files, run: claude plugin uninstall ouroboros"

设置故障排查

• "No compatible Python found"：当 uv 位于 PATH 中时，插件模式无需全局 Python 即可运行。否则请安装 Python 3.12（brew install [email protected]、sudo apt install python3.12 或 python.org/downloads）。
• "uvx: command not found"：推荐使用 uvx，但并非必需。对于默认的 Claude SDK 运行时，请运行 pip install 'ouroboros-ai[claude]' （[claude-sdk] 是显式别名）。只有在隔离的 MCP 2 服务工作进程中才使用 [claude-cli]。切勿将 [claude]、[claude-sdk] 或 [all] 与 [mcp] 一起使用。

RFC #1392 状态提示页脚

最终回复必须以且仅以一行 ◆ <current state> → next: <recommended action> 结束。当 ouroboros_session_status 可用时，通过它获取当前会话状态；否则根据此技能的实际结果确定状态。切勿使用线性的 Step N of M 页脚；如果下一步确实需要选择，请列出 2–3 个选项。