Q00/ouroboros#integrations/dsh-plugin

需要 codex 在 PATH 中，并且主机上有 uvx（插件的 MCP 描述符用它启动 server）。可用 pipx install uv、pip install --user uv 或 brew install uv 安装。

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

打开一个新的 Codex 会话，按顺序运行：

ooo setup
ooo interview "Build a task management CLI"

ooo setup 只需运行一次，用来准备运行环境。准备就绪后，它会沿用 Codex 当前的默认模型；只有在需要为某个流水线阶段固定特定模型时，才选择直接配置模型。

pipx install 'ouroboros-ai[mcp]'       # 或者：uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime kiro         # 检测 Kiro CLI、注册 MCP server，并把
                                        # OUROBOROS_RUNTIME=kiro 写入
                                        # ~/.kiro/settings/mcp.json（受信任的、由
                                        # setup 管理的位置——项目内的 .env 属于不受信任
                                        # 输入，这个键在那里会被忽略）

之后就可以在 Kiro CLI 会话中使用 ooo 命令。

gh auth login                                # 一次性 GitHub 认证（用于实时获取模型列表）
pipx install 'ouroboros-ai[mcp]'             # 或者：uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot            # 实时获取模型列表并选择默认模型，
                                             # 在 ~/.copilot/mcp-config.json 中注册 MCP server

重新启动 Copilot CLI 会话后，即可在会话中使用 ooo 命令。模型 ID 映射的覆盖范围比看上去要窄：静态映射表只覆盖 claude-opus-4-6 和 claude-sonnet-4-5；已经包含 . 的 ID 会原样通过；连字符转点号的兜底逻辑会替换每一个连字符，因此当前默认值 claude-opus-4-8 会变成 claude.opus.4.8 而匹配失败。请让各角色模型保持未设置，由 setup 写入发现到的 ID；或显式设置一个 Copilot 可用的点号格式 ID。参见 #1995 与 Copilot 运行时指南。

完整说明见 GitHub Copilot CLI 运行时指南。

仅安装 Claude Code 插件（无需安装 Python 包或全局 Python；主机唯一的 前置条件是 uv。uv 提供启动 MCP server 的 uvx，并可为插件技能配置 Python >= 3.12。兼容的全局 python3 或 python 只是可选的快速路径； 缺失或版本过旧时，技能会使用 uv 管理的解释器）：

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

然后在 Claude Code 会话里跑一次 ooo setup。

pip / uv / pipx：

pip install ouroboros-ai                # 基础
pip install 'ouroboros-ai[claude]'        # + Claude Code 依赖
pip install 'ouroboros-ai[litellm]'       # + LiteLLM 多 provider；Python 3.12-3.13
pip install 'ouroboros-ai[mcp]'           # + MCP server / client 支持
pip install 'ouroboros-ai[tui]'           # + Textual 终端 UI
pip install 'ouroboros-ai[all]'           # Claude + LiteLLM + TUI + dashboard（不含 MCP 2）；Python 3.12-3.13
ouroboros setup                         # 配置运行时

[claude] 与 [mcp] 必须保持隔离：Claude Agent SDK 使用 MCP 1.x，而协议 server 使用 MCP 2。需要 MCP 的 host 应通过 uvx --isolated --python '>=3.12' --from 'ouroboros-ai[mcp]' ... 或 pipx run --spec 'ouroboros-ai[mcp]' ... 启动独立进程，不要把两个 extra 安装到同一环境。

基础包和非 LiteLLM 安装支持 Python 3.12-3.14。包含 LiteLLM 的安装（[litellm]、[all]、source --all-extras）支持 Python 3.12-3.13；当前示例优先使用 Python 3.13。详见 Platform Support。

历史兼容：在 extras 迁移期间，ouroboros-ai[dashboard] 仍然作为兼容别名保留。

Homebrew（macOS/Linux）：

brew tap q00/tap
brew install ouroboros-ai
ouroboros setup                         # 配置运行时

自托管 tap，尚未进入 homebrew-core。安装的是与 PyPI 相同的包。

各运行时指南：Claude Code · Codex CLI · Hermes · OpenCode · Kiro CLI · Gemini CLI · GitHub Copilot CLI · Zcode · Pi JSON mode · Goose · GJC · Antigravity CLI · Grok Build CLI

ouroboros uninstall

清掉所有配置、MCP 注册和数据。详情见 UNINSTALL.md。

interview  ->  苏格拉底式提问揭示了 12 条隐藏假设
seed       ->  把回答凝结成不可变规约（Ambiguity: 0.15）
run        ->  按 Double Diamond 分解执行
evaluate   ->  三阶段验证：Mechanical -> Semantic -> Consensus

在你的 AI 编码 agent 会话里用 ooo <cmd>，或者在终端里直接用 ouroboros init start、ouroboros run seed.yaml 等命令。

衔尾蛇完成了一次循环。每一圈，它都比上一圈知道得更多。

src/ouroboros/
+-- bigbang/        Interview、模糊度打分、brownfield 探查
+-- routing/        PAL Router —— 三档成本优化（1x / 10x / 30x）
+-- execution/      Double Diamond、分层 AC 分解
+-- evaluation/     Mechanical -> Semantic -> Multi-Model Consensus
+-- evolution/      Wonder / Reflect 循环、收敛判定
+-- resilience/     四种停滞模式检测、5 个横向思维人格
+-- observability/  三要素漂移度量、自动复盘
+-- persistence/    Event sourcing（SQLAlchemy + aiosqlite）、检查点
+-- orchestrator/   运行时抽象层（Claude Code、Codex CLI、OpenCode、Hermes）
+-- core/           类型、错误、seed、本体、安全
+-- providers/      LiteLLM 适配器（100+ 模型）
+-- mcp/            MCP 客户端 / 服务端集成
+-- plugin/         插件系统（技能 / agent 自动发现）
+-- tui/            终端 UI 仪表盘
+-- cli/            基于 Typer 的 CLI

关键内部细节：

• PAL Router —— Frugal（1x）→ Standard（10x）→ Frontier（30x），失败自动升级，成功自动降级
• Drift —— Goal（50%）+ Constraint（30%）+ Ontology（20%）加权度量，阈值 ≤ 0.3
• Brownfield —— 自动识别多种语言生态的配置文件
• Evolution —— 最多 30 代，本体相似度 ≥ 0.95 时收敛
• Stagnation —— 检测打转、震荡、无漂移、收益递减四种模式
• Agent OS runtime —— 跨能力发现、策略、指令、事件日志、agent 进程的可重放执行契约
• Runtime backends —— 可插拔抽象层（orchestrator.runtime_backend 配置），原生支持 Claude Code、Codex CLI、OpenCode、Hermes；同一份工作流规约，跑在不同执行引擎上

完整设计文档见 Architecture（英文）。中文文档：

• 评估流水线指南（Evaluation Pipeline） —— 三阶段关卡的完整参考：每个阶段验什么、阈值和配置项、失败模式与排查、以及事件审计轨迹
• 隐藏清单收敛（Hidden-Checklist Convergence） —— run → 评估 → 有预算的 Ralph 链，以及为什么判分用的断言对 worker 隐藏、且没有配置项能把它打开

Wonder -> "该怎么活？" -> "'活'到底是什么？" -> 本体论 —— 苏格拉底

每一个好问题都会带出更深的问题 —— 而那个更深的问题，永远是本体论层面的：不是"我该怎么做？"，而是"这东西到底是什么？"

   Wonder                          本体论
"我想要什么？"     ->    "我想要的那个东西，到底是什么？"
"做个 task CLI"    ->    "task 是什么？priority 是什么？"
"修一下登录 bug"   ->    "这是根因，还是只是症状？"

这不是为了抽象而抽象。当你回答"task 是什么？" —— 是可删除还是可归档？单人用还是团队用？—— 你就一次性消除了一整类返工。本体论问题，恰恰是最实用的问题。

Ouroboros 通过 Double Diamond 把这套思路嵌进了架构里：

    * Wonder          * Design
   /  (发散)         /  (发散)
  /    探索          /    创造
 /                 /
* ------------ * ------------ *
 \                 \
  \    定义         \    交付
   \  (收敛)         \  (收敛)
    * 本体论          * 评估

第一颗钻石是苏格拉底式：先发散成问题，再收敛成清晰的本体。第二颗是实用层面：先发散出设计选项，再收敛到经过验证的交付物。每一颗钻石都依赖前一颗 —— 没理解清楚的东西，是设计不出来的。

Interview 不会因为你"觉得差不多了"就结束 —— 而是要等数学说差不多了才结束。Ouroboros 把模糊度量化为加权清晰度的反值：

Ambiguity = 1 - Σ(clarity_i * weight_i)

每个维度由 LLM 在 0.0–1.0 区间打分（temperature 设为 0.1 以保证可复现），然后按权重加和：

阈值：Ambiguity ≤ 0.2。 高于这个值会挡住 Seed 生成。绕过它的办法是显式传入 force，CLI 会把这个选项和继续、取消并排放在屏幕上。这道门槛是一个可以被反驳的默认值，不是锁。

示例（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 -> 可以进入 Seed

为什么是 0.2？因为在加权清晰度达到 80% 时，剩下的那点不确定性已经小到可以靠代码层面的判断来收尾。再高的话，你还在凭感觉定架构。

演化循环不会无限跑下去。当连续几代输出本体上等价的 schema 时，循环就停。相似度按 schema 字段加权比较：

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

阈值：Similarity ≥ 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

两道数学关卡，一个理念：没想清楚之前不要写（Ambiguity ≤ 0.2），没稳定之前不要停（Similarity ≥ 0.95）。