# ouroboros

> Launch the Ouroboros Python engine via uvx to provide DSH with specification-driven AI workflows as MCP tools (Interview→Seed→Execute→Evaluate→Evolution loop), requiring no installation or additional code.

## Metadata

- Author: [@Q00](https://github.com/Q00)
- Repo: <https://github.com/Q00/ouroboros.git>
- GitHub: [Q00/ouroboros](https://github.com/Q00/ouroboros)
- Stars: 5,588
- Language: Python
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://ouroboros.page/>
- Topics: `agent-os`, `agentic-ai`, `ai-agent`, `ai-coding-agent`, `claude-code`, `cli`, `codex`, `coding-agent`, `deepseek`, `deepseek-harness`, `developer-tools`, `dsh`, `dsh-plugin`, `github-copilot`, `llm-evaluation`, `llm-orchestration`, `loop-engineering`, `mcp`, `opencode`
- Forks: 559
- Open Issues: 59
- Last push: 2026-08-20T09:59:49.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:Q00/ouroboros/integrations/dsh-plugin
```

## Wiki

## 一句话定位
这个 bundle 把 Ouroboros——一套"先把需求问清楚再动代码"的 Python AI 工作流引擎——以 MCP 工具的形式挂进 DeepSeek Harness,让你在 dsh 对话框里说 `ooo interview`、`ooo auto`、`ooo qa` 时不用手动切换窗口。

## 核心能力
- 在 dsh 对话里直接调用 30 多个 Ouroboros 工具(采访、Seed、执行、评估、进化、QA、撤销、回滚等),模型根据工具描述自动选择
- 运行完整的 `采访 → Seed → 执行 → 评估` 闭环(auto 工具一次跑完同步返回,30 分钟超时)
- 在既有 dsh 项目里用 Socratic 采访压低需求模糊度,达到阈值才允许生成 Seed 规范
- 用进化循环(演化、回滚、世代追踪)反复打磨 Seed,直到评估器放行
- 提供异常分支工具:取消执行、取消后台任务、查询任务状态、查询投影事件、查询仪表盘
- 软失败启动:本机若没装 `uv` 或 Ouroboros 还没配置,dsh 仍能正常起来,只是 Ouroboros 工具不显示,其它插件不受影响

## 技术实现
- **语言**: 整个 bundle 是纯配置(YAML + JSON),没有任何自定义插件代码;背后的 Ouroboros 是 Python
- **关键依赖**: `@deepseek-ai/dsh-mcp-client`(MCP stdio 客户端)、`uvx`(随用随取的 Python 运行时)、`ouroboros-ai[mcp]`(MCP 2.0 协议的服务端包)
- **架构模式**: 通过 Cordis 补丁(`dsh.bundle.patch`)插入一行 `mcp-ouroboros`,由 dsh 的 MCP 客户端用 stdio 协议拉起 `ouroboros mcp serve`,子进程再把 30 多个工具暴露给上层 agent
- **入口文件**: `integrations/dsh-plugin/cordis.patch.yml`(逻辑入口),`integrations/dsh-plugin/package.json`(声明 `dsh.bundle.patch` 路径)

## 适用场景
想让 DSH 不再"上来就写代码"的人:在用 dsh 做正经需求时,先让 Ouroboros 把模糊想法拆成可验收的 Seed,再交给执行器,最后让评估器打分迭代。也适合需要在 dsh 里同时跑调研、设计、评审多道工序、又不想离开 dsh 窗口的开发者。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Python | >= 3.12 | 由 `uvx` 在隔离环境里自动拉取,无需手动 `pip install` |
| uv (uvx) | 最新稳定版 | 需在 `PATH` 上;首次启动时它会自己下载 Ouroboros 及其依赖 |
| dsh | 未声明具体版本 | bundle 自身不约束;父仓库通过 dsh-mcp-client 加载 |
| Node.js | >= 22 | 仅在你想用 `OUROBOROS_LLM_BACKEND=dsh` 并从源码构建 dsh 时需要 |
| Agent runtime | 可执行一个 CLI 运行时 | `claude-cli`、`codex`、`opencode` 任一;告诉 Ouroboros 由谁执行 `ooo auto` |
| 操作系统 | 跨平台 | 无原生模块,不强绑 Linux/macOS/Windows |

## 安装方式
```bash
dsh plugin --profile web add github:Q00/ouroboros/integrations/dsh-plugin
```

## 配置项
本 bundle 没有 DSHP 风格的"配置页",所有可选参数都通过环境变量注入,dsh 子进程只允许这几项透传:

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `OUROBOROS_AGENT_RUNTIME` | 环境变量 | 指定哪个 CLI 跑 `ooo auto` 的执行步骤(`claude-cli`、`codex`、`opencode` 等) | 不设,继承 `ouroboros setup` 的默认 |
| `OUROBOROS_LLM_BACKEND` | 环境变量 | 采访/Seed/QA 用什么 LLM;设为 `dsh` 时改走 DeepSeek Harness(需配合下面两项) | 不设,继承 `ouroboros setup` 的默认 |
| `OUROBOROS_DSH_CONFIG_PATH` | 环境变量 | 当 `OUROBOROS_LLM_BACKEND=dsh` 时必填,绝对路径,指向 dsh 的 Cordis 组合配置 | 不设 |
| `OUROBOROS_DSH_CLI_PATH` | 环境变量 | `dsh-acp-demo` 二进制不在 `PATH` 时给它指路 | 走 `PATH` |
| `ANTHROPIC_API_KEY` | 环境变量 | 透传给 Ouroboros 默认 LLM 后端 | 不设即空 |
| `DEEPSEEK_API_KEY` | 环境变量 | `dsh` 后端的回环凭证 | 不设即空 |
| `toolCallTimeoutMs` | patch 参数 | `ouroboros_auto` 同步入参,30 分钟(1800000 毫秒) | 已写在补丁里 |

其余非凭证类变量(`PATH`、`HOME`、`OUROBOROS_*` 选择器)dsh 会自动透传,无需在这里声明。

## 常见问题

**Q: 必须装 Python 吗?**

A: 系统级 Python 不需要。bundle 用 `uvx` 在隔离环境里下载并运行 Python 3.12+ 与 Ouroboros,只要机器上有 `uv`(从 https://astral.sh/uv 一行安装命令搞定)即可。

**Q: 安装后看不到 `mcp__ouroboros__*` 工具怎么办?**

A: 先确认 `uv --version` 能跑;再确认你是否设过 `OUROBOROS_AGENT_RUNTIME`,或者跑过 `ouroboros setup`。记住启动失败是软失败(`failOnStartupError: false`),dsh 不会因为这个插件崩,只是工具列表里少了它。

**Q: 跟单独装 Ouroboros 比,这个 bundle 缺了什么?**

A: 没有 SKU 上的差异——bundle 本质就是一行 `cordis.patch.yml`,真正的 Ouroboros 包还是从 PyPI 用 `uvx` 拉。换句话说,你既可以在 dsh 里聊,也可以在终端单独跑 `ooo`,两边共享同一份配置。

**Q: 如何把 OpenAI/Google 的 key 也传进去?**

A: 在自家 profile 的 `cordis.patch.yml` 里复制 `mcp-ouroboros` 整段 config,在 `env` 里追加 `OPENAI_API_KEY` (或 `GOOGLE_API_KEY` 等);注意 dsh 后来的 layer 是覆盖整段而非深合并,所以不要只 patch 一行,得带 `config` 块一起重写。

**Q: 网络断了/uv 抽风了,工具列表还在,调用却一直失败?**

A: 这是预期行为:该 bundle 没有自动重连逻辑(reconnect loop 只在 dsh 主仓库 `main` 分支里),你需要修复根因后手动重启 dsh 或重载插件。

## 上手难度
进阶 — 不需要写代码,但要把 `uv`、环境变量、Ouroboros 的 agent runtime 选择这层概念搞明白才能顺畅启用,普通用户需要看一遍 README 才能用上。

## 已知问题与限制
- `OUROBOROS_LLM_BACKEND=dsh` 不是单变量切换:必须从源码构建 dsh(`pnpm install && pnpm run build`,Node.js >= 22),发布版 `@deepseek-ai/dsh-acp-demo` 在 `dsh-tool-bash` peer 依赖链上仍冲突;还必须提供绝对路径的 Cordis 组合文件(`OUROBOROS_DSH_CONFIG_PATH`),相对路径会被拒绝
- MCP 子进程不能托管 in-process 的 Claude SDK,所以 `OUROBOROS_AGENT_RUNTIME` 必须是一个可执行 CLI(不能填 `claude` 这种 SDK 名),除非你想 `ouroboros auto` 那步调用就报错
- 子进程环境做了凭证剥离:只有 `ANTHROPIC_API_KEY` 和 `DEEPSEEK_API_KEY` 在白名单,其它 `*_KEY` 都不会自动透传给 Ouroboros
- 重连不是默认行为:已发布的 dsh 0.0.1-rc.1 没有 reconnect 循环,只有最新的 `main` 分支有带指数退避和重试上限的版本;安装完若崩溃,需手动重载插件或重启 dsh
- bundle 不发布独立版本号或 release,跟着父 Ouroboros 仓库的 `main` 分支走,意味着用 `dsh plugin add` 时拿到的始终是上游 `main` 头

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [ouroboros](https://deepseek-plugin.org/plugins/Q00/ouroboros/integrations/dsh-plugin)
Wiki generated by AI (model: `MiniMax-M3`)