Ouroboros

宿主需要在 PATH 中提供 codex 和 uvx（插件的 MCP 描述符会使用它启动服务）。 可通过 pipx install uv、 pip install --user uv 或 brew install uv 安装 uv。

codex plugin marketplace add Q00/ouroboros
codex plugin add ouroboros@ouroboros

启动新的 Codex 会话，然后按顺序运行以下命令：

ooo setup
ooo interview "Build a task management CLI"

ooo setup 是一次性运行时准备步骤。准备就绪后，Ouroboros 会使用 Codex 当前的默认模型；仅当你想为某个流水线阶段固定指定模型时，才选择 直接配置模型。

pipx install 'ouroboros-ai[mcp]'       # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime kiro         # detects Kiro CLI, registers MCP server, and
                                        # writes OUROBOROS_RUNTIME=kiro into
                                        # ~/.kiro/settings/mcp.json (the trusted,
                                        # setup-managed location -- a project .env
                                        # is untrusted input and this key is ignored there)

然后在 Kiro CLI 会话中使用 ooo 命令。

gh auth login                                # one-time GitHub auth (used for live model discovery)
pipx install 'ouroboros-ai[mcp]'             # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot            # discovers models live, picks a default,
                                             # registers MCP server in ~/.copilot/mcp-config.json

重启 Copilot CLI 会话，然后在其中使用 ooo 命令。模型 ID 映射受目录限制：如果目录中存在该 ID，先前固定的直接版和 OpenRouter Opus 5 会解析为 claude-opus-5；当前 Anthropic API 固定项只会转换末尾的数字分隔符，并且仅当已发现的目录中包含完全匹配的候选项时才会转换。未知 ID 保持不变，以便 Copilot 明确报告模型不可用错误，而不是悄悄选择其他模型。将角色模型留空，设置程序会写入一个已发现的 ID；也可以显式设置有效的 Copilot ID。请参阅 Copilot 运行时指南。

完整详情请参阅 GitHub Copilot CLI 运行时指南。

仅安装 Claude Code 插件（无需安装 Python 包或全局 Python；宿主需要 uv，它同时提供用于 MCP 服务的 uvx 和技能所需的 Python >= 3.12 回退方案）：

claude plugin marketplace add Q00/ouroboros && claude plugin install ouroboros@ouroboros

然后在 Claude Code 会话中运行 ooo setup。

pip / uv / pipx：

pip install 'ouroboros-ai[mcp,tui]' && ouroboros setup --runtime claude-cli  # recommended MCP v2 default
pip install 'ouroboros-ai[claude]'      # Claude Agent SDK profile (MCP 1.x, isolated)
pip install 'ouroboros-ai[claude-cli]'  # dependency-free Claude CLI worker
pip install 'ouroboros-ai[claude-sdk]'  # explicit alias for the Claude SDK profile
pip install 'ouroboros-ai[litellm]'     # + LiteLLM multi-provider; Python 3.12-3.13
pip install 'ouroboros-ai[mcp]'         # MCP v2 server/client without the GUI
pip install 'ouroboros-ai[tui]'         # settings GUI only
pip install 'ouroboros-ai[all]'         # MCP 1.x app bundle; excludes MCP 2 by design
ouroboros setup                         # configure runtime

核心安装和非 LiteLLM 安装支持 Python 3.12-3.14。包含 LiteLLM 的安装（[litellm]、[all] 和源码 --extra all）支持 Python 3.12-3.13；当前示例请使用 Python 3.13。请参阅平台支持。

推荐的独立安装方式是先安装 ouroboros-ai[mcp,tui]，然后显式选择兼容 MCP v2 的运行时。示例使用 --runtime claude-cli；可替换为其他兼容运行时，例如 codex、opencode、hermes、gemini、goose、kiro、copilot、pi 或 gjc。仅在隔离的 MCP 1.x 环境中使用 [claude] 和 [claude-sdk]。

在已隔离的 Python 环境中嵌入 MCP 客户端/服务库时，pip install 'ouroboros-ai[mcp]' 是有效的；但注册宿主需要使用 uvx --isolated --python '>=3.12' 或 pipx。在运行 ouroboros setup --runtime <claude-cli|codex|opencode|hermes|gemini|goose|kiro|copilot|pi|gjc> 之前，请先运行 pipx install 'ouroboros-ai[mcp]' 或 uv tool install 'ouroboros-ai[mcp]'；如果这两种隔离式启动器均不可用，setup 将退出且不会更改运行时配置。

旧版兼容性：ouroboros-ai[dashboard] 仍可作为兼容别名/空操作接受；它不会安装仪表板运行时载荷。ouroboros-ai[all] 仅出于兼容性考虑包含此空操作别名。

Homebrew（macOS/Linux）：

brew tap q00/tap
brew install ouroboros-ai
ouroboros setup                         # configure runtime

这是可自托管的 tap，目前尚未收录到 homebrew-core。安装的包与发布到 PyPI 的相同。

请参阅运行时指南：Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Zcode · Pi JSON 模式 · OMP (Oh My Pi) · Goose · GJC · Antigravity CLI · Grok Build CLI

ouroboros uninstall

移除所有配置、MCP 注册和数据。详情请参阅 UNINSTALL.md。

interview  ->  Socratic questioning exposed 12 hidden assumptions
seed       ->  Crystallized answers into an immutable spec (Ambiguity: 0.15)
run        ->  Executed via Double Diamond decomposition
evaluate   ->  3-stage verification: Mechanical -> Semantic -> Consensus

在 AI 编码 Agent 会话中使用 ooo <cmd>，或在终端中运行 ouroboros init start、ouroboros run seed.yaml 等命令。

这条蛇完成了一轮循环。每循环一轮，它都比上一轮更了解情况。

src/ouroboros/
+-- bigbang/        Interview, ambiguity scoring, brownfield explorer
+-- router/         PAL Router -- 3-tier cost optimization (1x / 10x / 30x)
+-- execution/      (deprecated — logic moved to orchestrator/ and mcp/tools/)
+-- evaluation/     Mechanical -> Semantic -> Multi-Model Consensus
+-- evolution/      Wonder / Reflect cycle, convergence detection
+-- resilience/     4-pattern stagnation detection, 5 lateral personas
+-- observability/  3-component drift measurement, auto-retrospective
+-- persistence/    Event sourcing (SQLAlchemy + aiosqlite), checkpoints
+-- orchestrator/   Runtime abstraction layer (Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Pi, OMP, GJC, Goose, Antigravity, Grok, Zcode)
+-- core/           Types, errors, seed, ontology, security
+-- providers/      LiteLLM adapter (100+ models)
+-- mcp/            MCP client/server integration
+-- plugin/         Plugin system (skill/agent auto-discovery)
+-- tui/            Terminal UI dashboard
+-- cli/            Typer-based CLI

核心内部机制：

• PAL Router -- 依次使用 Frugal（1x）-> Standard（10x）-> Frontier（30x），失败时自动升级，成功时自动降级
• 漂移 -- 对目标（50%）+ 约束（30%）+ 本体（20%）进行加权测量，阈值 <= 0.3
• 既有项目 -- 自动检测多个语言生态系统中的配置文件
• 演进 -- 最多 30 代，当本体相似度 >= 0.95 时收敛
• 停滞 -- 检测循环、振荡、无漂移和收益递减等模式
• Agent OS 运行时 -- 在能力发现、策略、指令、事件日志和 Agent 进程之间提供可重放的执行契约
• 运行时后端 -- 可插拔的抽象层（orchestrator.runtime_backend 配置），一流支持 runtime_backend_choices() 返回的所有规范后端，包括 GJC、Antigravity、Grok 和 Zcode；工作流规范相同，执行引擎不同

完整设计文档请参阅架构。

惊奇 -> “我该如何生活？” -> “‘生活’究竟是什么？” -> 本体论 -- 苏格拉底

每个伟大的问题都会引出一个更深层的问题，而这个更深层的问题总是本体论问题：不是*“我该如何做这件事？”，而是“这究竟是什么？”*

   Wonder                          Ontology
"What do I want?"    ->    "What IS the thing I want?"
"Build a task CLI"   ->    "What IS a task? What IS priority?"
"Fix the auth bug"   ->    "Is this the root cause, or a symptom?"

这并非为了抽象而抽象。当你回答*“任务是什么？”*——它可以删除还是归档？由个人还是团队负责？——你就消除了一整类返工。本体论问题是最实用的问题。

Ouroboros 通过双钻模型将这一理念融入其架构：

    * Wonder          * Design
   /  (diverge)      /  (diverge)
  /    explore      /    create
 /                 /
* ------------ * ------------ *
 \                 \
  \    define       \    deliver
   \  (converge)     \  (converge)
    * Ontology        * Evaluation

第一个钻石是苏格拉底式的：发散提出问题，收敛于本体论上的清晰认知。第二个钻石是务实的：发散探索设计方案，收敛于经过验证的交付。每个钻石都以前一个为前提——你无法设计自己尚未理解的东西。

访谈不会在你觉得准备好时结束，而是在数学判定你准备好时结束。Ouroboros 将歧义量化为加权清晰度的倒数：

Ambiguity = 1 - Sum(clarity_i * weight_i)

大模型会为每个维度打 0.0-1.0 分（温度为 0.1，以确保结果可复现），然后进行加权：

阈值：模糊度 <= 0.2。 高于此值的分数会阻止 Seed 生成。显式传入 force 即可越过此限制，CLI 会在屏幕上将此选项与继续和取消并列显示。这个门槛只是一个默认值，值得商榷，并非一道锁。

Example (Greenfield):

  Goal: 0.9 * 0.4  = 0.36
  Constraint: 0.8 * 0.3  = 0.24
  Success: 0.7 * 0.3  = 0.21
                        ------
  Clarity             = 0.81
  Ambiguity = 1 - 0.81 = 0.19  <= 0.2 -> Ready for Seed

为什么是 0.2？因为加权清晰度达到 80% 时，剩余的未知因素足够少，可以通过代码层面的决策来解决。超过此阈值，你仍然是在猜测架构。

演化循环不会无限运行。当连续几代生成的 schema 在本体上完全相同时，循环就会停止。相似度通过对 schema 字段进行加权比较来衡量：

Similarity = 0.5 * name_overlap + 0.3 * type_match + 0.2 * exact_match

阈值：相似度 >= 0.95 —— 循环收敛并停止演化。

但原始相似度并不是唯一的信号。系统还会检测病态模式：

Gen 1: {Task, Priority, Status}
Gen 2: {Task, Priority, Status, DueDate}     -> similarity 0.78 -> CONTINUE
Gen 3: {Task, Priority, Status, DueDate}     -> similarity 1.00 -> CONVERGED

两道数学门槛，一种理念：在明确之前不要构建（模糊度 <= 0.2），在稳定之前不要停止演化（相似度 >= 0.95）。