Q00/ouroboros

◯ ─────────── ◯



O U R O B O R O S

◯ ─────────── ◯

停止 Prompting。开始 Specifying。
_{一款 Claude Code 插件，在 AI 编写任何代码之前，将模糊的想法转化为经过验证的 Spec。}

快速开始 · 哲学 · 原理 · 命令 · Agent

Ouroboros 是一个**Spec-First 的 AI 开发系统**。它应用苏格拉底式提问和本体论分析来揭示你隐藏的假设——在编写任何一行代码之前。 大多数 AI 编码的失败源于**输入**，而非输出。瓶颈不在于 AI 的能力，而在于人类的清晰度。Ouroboros 修复的是人，而不是机器。 ## 从 Wonder 到 Ontology 这是 Ouroboros 背后的哲学引擎。每一个伟大的问题都会引出一个更深层的问题——而那个更深层的问题总是**本体论层面的**：不是*“我该怎么做？”*，而是*“这到底 **IS**（是）什么？”* ``` 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?" ``` 这不是为了抽象而抽象。当你回答“一个任务到底 **IS**（是）什么？”时——是可删除还是可归档？是个人还是团队？——你就消除了一整个类别的返工。**本体论问题就是最实际的问题。** Ouroboros 通过**双菱形（Double Diamond）**将这一点嵌入其架构中： ``` ◇ Wonder ◇ Design ╱ (diverge) ╱ (diverge) ╱ explore ╱ create ╱ ╱ ◆ ──────────── ◆ ──────────── ◆ ╲ ╲ ╲ define ╲ deliver ╲ (converge) ╲ (converge) ◇ Ontology ◇ Evaluation ``` 第一个菱形是**苏格拉底式的**：发散成问题，收敛成本体论的清晰度。第二个菱形是**务实的**：发散成设计方案，收敛成经过验证的交付物。每个菱形都需要前一个——你无法设计你尚未理解的东西。 ## 快速开始 **Step 1 — 安装插件**（在你的终端中）： ``` claude plugin marketplace add Q00/ouroboros claude plugin install ouroboros@ouroboros ``` **Step 2 — 运行设置**（在 Claude Code 会话内）： ``` # 启动 Claude Code，然后输入： ooo setup ``` **Step 3 — 开始构建：** ``` ooo interview "I want to build a task management CLI" ```

刚刚发生了什么？

``` ooo interview → Socratic questioning exposed 12 hidden assumptions ooo seed → Crystallized answers into an immutable spec (Ambiguity: 0.15) ooo run → Executed via Double Diamond decomposition ooo evaluate → 3-stage verification: Mechanical → Semantic → Consensus ``` Ouroboros 完成了一个循环。每一个循环，它都比上一个知道得更多。

## 循环 Ouroboros——一条吞噬自己尾巴的蛇——不仅仅是装饰。它**就是**架构本身： ``` Interview → Seed → Execute → Evaluate ↑ ↓ └──── Evolutionary Loop ────┘ ``` 每一个循环都不是简单的重复——它在**进化**。评估的输出作为下一代输入的反馈，直到系统真正知道它在构建什么。 | Phase | 发生了什么 | |:------|:-------------| | **Interview（访谈）** | 苏格拉底式提问揭示隐藏的假设 | | **Seed（种子）** | 答案结晶为不可变的 Spec | | **Execute（执行）** | 双菱形：探索 → 定义 → 设计 → 交付 | | **Evaluate（评估）** | 3 阶段门控：机械 ($0) → 语义 → 多模型共识 | | **Evolve（进化）** | Wonder *（“我们仍然不知道什么？”）* → 反思 → 下一代 | 当 Ontology 相似度 ≥ 0.95 时，即达到收敛——此时系统通过自我提问达到了清晰。 ### Ralph：永不停歇的循环 `ooo ralph` 持续运行进化循环——跨越会话边界——直到达到收敛。每一步都是**无状态**的：EventStore 重构完整的谱系，所以即使你的机器重启，Ouroboros 也会从它中断的地方继续。 ``` Ralph Cycle 1: evolve_step(lineage, seed) → Gen 1 → action=CONTINUE Ralph Cycle 2: evolve_step(lineage) → Gen 2 → action=CONTINUE Ralph Cycle 3: evolve_step(lineage) → Gen 3 → action=CONVERGED ✓ └── Ralph stops. The ontology has stabilized. ``` ### 歧义度分数：Wonder 与代码之间的门槛 Interview 并不是在你觉得准备好时结束——而是在**数学**表明你准备好时结束。Ouroboros 将歧义量化为加权清晰度的倒数： ``` Ambiguity = 1 − Σ(clarityᵢ × weightᵢ) ``` 每个维度由 LLM 评分 0.0–1.0（temperature 设为 0.1 以确保可复现性），然后加权： | 维度 | Greenfield（绿地项目） | Brownfield（棕地项目） | |:----------|:----------:|:----------:| | **目标清晰度** — *目标是否具体？* | 40% | 35% | | **约束清晰度** — *限制是否已定义？* | 30% | 25% | | **成功标准** — *结果是否可衡量？* | 30% | 25% | | **上下文清晰度** — *是否理解现有代码库？* | — | 15% | **阈值：歧义度 ≤ 0.2** —— 只有达到这个标准，才能生成 Seed。 ``` 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% 的加权清晰度下，剩下的未知项足够小，代码层面的决策可以解决它们。高于这个阈值，你仍然是在猜测架构。 ### Ontology 收敛：当 Ouroboros 停下时 进化循环不会永远运行。当连续几代产生本体论上相同的 Schema 时，它就会停止。相似度通过 Schema 字段的加权比较来衡量： ``` Similarity = 0.5 × name_overlap + 0.3 × type_match + 0.2 × exact_match ``` | 组件 | 权重 | 衡量内容 | |:----------|:------:|:-----------------| | **名称重叠** | 50% | 两代中是否存在相同的字段名称？ | | **类型匹配** | 30% | 共享字段是否具有相同类型？ | | **精确匹配** | 20% | 名称、类型和描述是否都完全相同？ | **阈值：相似度 ≥ 0.95** —— 循环收敛并停止进化。 但原始相似度并不是唯一的信号。系统还会检测病态模式： | 信号 | 条件 | 含义 | |:-------|:----------|:--------------| | **停滞** | 连续 3 代相似度 ≥ 0.95 | Ontology 已稳定 | | **振荡** | 第 N 代 ≈ 第 N-2 代（周期为 2 的循环） | 卡在两种设计之间反复跳动 | | **重复反馈** | 跨 3 代 ≥ 70% 的问题重叠 | Wonder 正在问同样的事情 | | **硬上限** | 达到 30 代 | 安全阀 | ``` 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）。** ## 命令 | 命令 | 作用 | |:--------|:-------------| | `ooo setup` | 注册 MCP server（一次性） | | `ooo interview` | 苏格拉底式提问 → 揭示隐藏假设 | | `ooo seed` | 结晶化为不可变的 Spec | | `ooo run` | 通过双菱形分解执行 | | `ooo evaluate` | 3 阶段验证门控 | | `ooo evolve` | 进化循环直到 Ontology 收敛 | | `ooo unstuck` | 5 种横向思维角色，助你摆脱困境 | | `ooo status` | 偏移检测 + 会话追踪 | | `ooo ralph` | 持续循环直到验证通过 | | `ooo tutorial` | 交互式动手学习 | | `ooo help` | 完整参考 | ## 九个心智（The Nine Minds） 九个 Agent，每种代表一种不同的思维模式。按需加载，从不预加载： | Agent | 角色 | 核心问题 | |:------|:-----|:--------------| | **Socratic Interviewer（苏格拉底式访谈者）** | 只提问。从不构建。 | *“你在假设什么？”* | | **Ontologist（本体论者）** | 寻找本质，而非症状 | *“这到底 **IS**（是）什么？”* | | **Seed Architect（种子架构师）** | 从对话中结晶出 Spec | *“这是否完整且无歧义？”* | | **Evaluator（评估者）** | 3 阶段验证 | *“我们构建的东西对吗？”* | | **Contrarian（反对者）** | 挑战每一个假设 | *“如果反面是真的会怎样？”* | | **Hacker（黑客）** | 寻找非常规路径 | *“哪些约束实际上是真实的？”* | | **Simplifier（简化者）** | 消除复杂性 | *“能用的最简单的东西是什么？”* | | **Researcher（研究者）** | 停止编码，开始调查 | *“我们实际拥有什么证据？”* | | **Architect（架构师）** | 识别结构性原因 | *“如果我们从头开始，我们会这样构建吗？”* | ## 底层原理

18 个 packages · 166 个模块 · 95 个测试文件 · Python 3.14+

``` src/ouroboros/ ├── bigbang/ Interview, ambiguity scoring, brownfield explorer ├── routing/ PAL Router — 3-tier cost optimization (1x / 10x / 30x) ├── execution/ Double Diamond, hierarchical AC decomposition ├── 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/ Claude Agent SDK integration, session management ├── core/ Types, errors, seed, ontology, security ├── providers/ LiteLLM adapter (100+ models) ├── mcp/ MCP client/server for Claude Code ├── plugin/ Claude Code plugin system ├── tui/ Terminal UI dashboard └── cli/ Typer-based CLI ``` **关键内部组件：** - **PAL Router** — 节约型 (1x) → 标准 (10x) → 前沿 (30x)，失败自动升级，成功自动降级 - **Drift（偏移）** — 目标 (50%) + 约束 (30%) + Ontology (20%) 加权测量，阈值 ≤ 0.3 - **Brownfield（棕地）** — 扫描 12+ 种语言生态系统中的 15 种配置文件类型 - **Evolution（进化）** — 最多 30 代，在 Ontology 相似度 ≥ 0.95 时收敛 - **Stagnation（停滞）** — 检测空转、振荡、无偏移和收益递减模式

## 实时监控 (TUI) Ouroboros 包含一个用于实时工作流监控的**终端仪表盘**。在单独的终端中运行它，同时执行 `ooo run` 或 `ooo evolve`： ``` # 安装并启动 uvx --from ouroboros-ai ouroboros tui monitor # 或者如果已在本地安装 uv run ouroboros tui monitor ``` | 键 | 屏幕 | 你看到的 | |:---:|:-------|:-------------| | `1` | **仪表盘** | Phase 进度、验收标准树、实时状态 | | `2` | **执行** | 时间线、Phase 输出、详细事件 | | `3` | **日志** | 可过滤的日志查看器，带基于级别的着色 | | `4` | **调试** | 状态检查器、原始事件、配置 | ## Star 历史

“始即是终，终即是始。”

Ouroboros 不重复——它进化。

MIT License

标签：AI辅助开发, Claude插件, Python, Socratic法, 代码生成前验证, 元编程, 思维链, 提示词工程, 敏捷开发, 无后门, 本体论, 策略决策点, 结构化思维, 自动化编程, 规格说明书生成, 软件架构, 逆向工具, 需求分析, 需求工程