# odai

> Injects Odai governance core into the specified DSH profile, overriding all agent presets; automatically chooses between using the current model, upgrading in-place, or delegating to a sub-agent based on task complexity, with built-in output style, compressed summary, skill source, and long-term memory.

## Metadata

- Author: [@orziz](https://github.com/orziz)
- Repo: <https://github.com/orziz/odai.git>
- GitHub: [orziz/odai](https://github.com/orziz/odai)
- Stars: 93
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-skills`, `agentic-workflow`, `ai-agent`, `ai-agents`, `ai-governance`, `claude-code`, `codex`, `dsh`, `dsh-plugin`, `dsh-plugins`, `github-copilot`, `odai`
- Forks: 16
- Open Issues: 0
- Last push: 2026-08-20T05:39:33.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:orziz/odai/dsh/plugin
```

## Wiki

## 一句话定位
odai-dsh-plugin 是为 DeepSeek Harness 某个 profile 提供全局治理内核的 bundle。装上之后，该 profile 下的所有 agent preset 都会自动按任务复杂度在当前模型、原地升级、外包子代理之间切换，并自带输出风格、压缩摘要、技能来源与长期记忆的本地持久化。

## 核心能力
- 在每个 agent preset 的系统提示里嵌入常驻治理 prompt，让模型在每次请求时按"事｜实｜法｜成｜界"静默判断后再动手
- 按任务复杂度、清晰度、风险与领域缺口，自动决定留在当前 controller 直接做、原地升级到同轮更高责任，或委派到独立子代理
- 维护可配置的责任模型映射（researcher / planner / executor / reviewer / frontend），用自然语言命名 provider 与 model 后即持久化到本地 JSON 并下轮生效
- 持久化输出形态（normal / 软精简 / 经济）、压缩摘要模型、技能来源（bundled / auto / user）与本地语义记忆，全部写在 `$DSH_HOME/odai/` 下，卸载包不会自动清理
- 暴露 `odai_routing_config`、`odai_route_card`、`odai_output_config`、`odai_compaction_config`、`odai_memory` 等工具，让 controller 直接读改自身治理状态而不修改宿主文件
- 提供受控的 skill 自演化叠加层，用户用一次性短语精确替换治理 markdown；每次替换都留下 base/result 代际记录与血缘关系，破坏性变更需要单独授权短语

## 技术实现
- **语言**: JavaScript (Node.js ESM `.mjs`)，无构建步骤
- **关键依赖**: `@deepseek-ai/dsh` (peerDependency，DSH 宿主；声明为 optional)、`node:crypto` `node:fs` `node:path` `node:os` `node:url` 等内置模块
- **架构模式**: 通过 DSH 的 Cordis patch bundle (`dsh/plugin/cordis.patch.yml:1-7`) 向宿主注册一个名为 `odai-governance` 的插件，注入点为 `systemPrompt / tools / subagents / sessions / llm` (`dsh/runtime/src/index.mjs:145-146`)；运行时在多个 DSH 钩子上做治理、路由、子代理边界、证据存储
- **入口文件**: `dsh/runtime/src/index.mjs` (`package.json:16` 的 main 与 exports 均指向该文件；`dsh/plugin/cordis.patch.yml` 也通过 bundle 引用)

## 适用场景
适合需要让某个 DSH profile 下所有 agent preset 都自动遵守"按复杂度区分直接做、规划、执行、验收"的治理规则，又不想为每个 preset 单独配置的团队或重度个人用户。如果只想给一个 agent preset 用 Odai，请改装 `odai-dsh-agent`，不要同时装 Plugin 与 Agent。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7 或 0.1.0-rc.8 | 0.2.5 起不再支持 rc.6 (`dsh/plugin/package.json:64`) |
| Node.js | >=22.15.0 | 历史 Zstandard 会话迁移依赖该 Node 提供的原生 API (`dsh/plugin/package.json:72`) |
| 平台 | macOS / Windows / Linux | 仅依赖 Node 内置模块，无原生扩展；测试覆盖 Windows、Linux、macOS 三平台 (`dsh/plugin/tests/package.test.mjs:35-42`) |
| 原生模块 | 无 | 仅使用 `node:crypto` `node:fs` `node:path` `node:os` `node:url` `node:zlib` 等内置能力 |

## 安装方式
```bash
dsh plugin --profile web add github:orziz/odai/dsh/plugin
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `routing.mode` | 枚举 | 路由总开关：`off` 关闭路由但保留治理；`observe` 仅记录不动模型；`auto` 按复杂度自动路由；`execute` 保留实验性委派行为 | `auto` |
| `routing.provider` | 字符串 | 委派子代理使用的 provider 名 | `spawn` |
| `routing.maxInputChars` | 整数 | 路由判定的输入文本上限，至少 256 | `12000` |
| `routing.roles.{researcher,planner,executor,reviewer,frontend}` | 对象 | 各责任角色的 provider / model / reasoningEffort / maxTokens 配置 | 未配置 |
| `routing.configPath` | 路径 | 路由配置 JSON 文件位置 | `$DSH_HOME/odai/routing.json` |
| `governance.additionalDeniedTools` | 字符串数组 | 子代理额外禁止调用的工具名 | `[]` |
| `governance.skillSource` | 枚举 | 技能来源：`bundled` 始终用包内置；`auto` 优先项目/自定义/用户级；`user` 只看用户级 | `bundled` |
| `governance.skillConfigPath` | 路径 | 技能来源配置 JSON 位置 | `$DSH_HOME/odai/source.json` |
| `governance.evolutionRoot` | 路径 | 用户受控技能自演化的存储根 | `$DSH_HOME/odai/skill-evolution` |
| `output.configPath` | 路径 | 输出风格策略 JSON 位置 | `$DSH_HOME/odai/output.json` |
| `compaction.cacheRetention` | 枚举 | 压缩缓存保留策略：`provider-default` / `short` / `long` / `none` | `provider-default` (可用 `ODAI_COMPACTION_CACHE_RETENTION` 环境变量覆盖) |
| `compaction.configPath` | 路径 | 压缩模型配置 JSON 位置 | `$DSH_HOME/odai/compaction.json` |
| `memory.mode` | 枚举 | 长期记忆开关：`auto` 自动捕获高置信条目；`off` 关闭 | `auto` |
| `memory.storePath` | 路径 | 长期记忆 JSON 文件位置 | `$DSH_HOME/odai/memory/store.json` |
| `memory.maxRetrieved` | 整数 | 每次召回的最大条目数，1 到 12 | `6` |
| `skillPath` | 字符串 | 强制使用指定路径的 skill 包；可由 `ODAI_SKILL_PATH` 环境变量覆盖 | 未设置 |

## 常见问题

**Q: 安装后必须重启 DSH 会话才生效吗？**

A: 需要。Plugin 是 profile 级 bundle，安装或升级后必须先停 DSH 进程，重启并用对应 profile 开新会话才会加载新治理；运行中的会话仍按安装前的行为运行。

**Q: 装上以后每个简单问题都会被流程拖慢吗？**

A: 不会。默认 routing.mode=auto 对结果、动作、授权都已清晰且低风险的任务直接留在当前 controller；只有复杂度、模糊度、风险或领域缺口出现时才升级到规划、执行、验收或外包子代理。

**Q: 需要手动指定规划或执行用的模型吗？**

A: 不必须。宿主默认模型足够时 Plugin 不自作主张选别处模型；用户用自然语言明确说出"规划用 provider-x/model-y，推理档 high"时由 controller 调 `odai_routing_config` 持久化到 `$DSH_HOME/odai/routing.json`，从下个用户轮生效。

**Q: 哪些状态会写入本地？**

A: 路由映射、输出风格、压缩模型、技能来源、技能自演化、长期记忆、人身安全连续性记录分别写到 `$DSH_HOME/odai/` 下的 `routing.json`、`output.json`、`compaction.json`、`source.json`、`skill-evolution/`、`memory/store.json`、`human-safety-continuity.json`。Plugin 与 Agent 共享这一目录，安装、更新、修复和卸载都不会自动清理。

**Q: 和 odai-dsh-agent 是什么关系？需要同时装吗？**

A: Plugin 是 profile 级 bundle，覆盖该 profile 下所有 agent preset；Agent 是按 session 选 Odai preset 的独立形态。常规情况下两者同装属冗余，只有需要"profile 范围 Plugin + 单独 Odai agent preset"并存时才一起装。

**Q: 升级或卸载前需要先停掉 DSH 吗？**

A: 需要。`odai-dsh-plugin repair-sessions` 子命令会主动检查 DSH 进程是否仍在运行，本地进程检查失败或发现活动 DSH 时直接拒绝写入。从老版本 (≤0.0.4) 升级时还要先运行 `npx odai-dsh-plugin repair-sessions --yes` 给历史会话里的私有 odai/* 事件补上 ignorable 标记。

**Q: 经济模式的输出上限是硬限制吗？**

A: 不是本地硬账单边界。该上限只是发给 provider 的输出 token 请求值，provider 可能把隐藏推理也算进去、超出或忽略它；要按 per-request usage 评估实际成本与合规性。

## 上手难度
进阶 — 默认装上就能用，但路由角色、压缩模型、技能来源、长期记忆、输出风格五套机制各自独立配置，想精细化调控需要分别理解其本地 JSON 与对应工具。

## 已知问题与限制
- 仅支持 DSH `0.1.0-rc.7` 和 `0.1.0-rc.8`，`0.2.5` 不再兼容 rc.6；后续 DSH rc.9+ 在没有专门发布版本前会被 fail-closed 拒绝加载 (`dsh/plugin/README.md:170`)
- 显式配置 `governance.skillConfigPath` 或环境变量 `ODAI_SKILL_PATH` 后必须重启 DSH 才生效；DSH 进程在启动时已把 bundled skill 字节加载进内存，运行时改文件不会立即生效 (`dsh/plugin/README.md:61 / 75`)
- 从 ≤0.0.4 老版本升级必须先停 DSH 并运行 `repair-sessions`，否则历史 session 里的私有 `odai/*` 事件会让新 DSH 拒绝加载；该子命令也拒绝在活动 DSH 进程存在时执行 (`dsh/plugin/README.md:45-51`)
- 经济模式 `maxTokens` 不影响子代理、压缩摘要、checkpoint 等内部预算；provider 仍可能超出该值，且若 controller 上限本就低于用户设置的值，它不会放宽 (`dsh/plugin/README.md:87-89`)
- 经济模式不发明非默认 token 数；用户没给具体值时使用 `500`，plugin 不会自动选择其他值 (`dsh/plugin/README.md:85`)
- Provider 缓存是 best-effort：即使两次请求完全相同也可能因上游写入、过期或路由而 miss；调低 controller 上限不是有效的缓存修复，反而可能让 checkpoint 不完整 (`dsh/plugin/README.md:168`)

---

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