# odai

> Inject governance kernel and responsibility routing into DSH, enabling agents to automatically switch between research/planning/execution/acceptance based on task complexity, preventing lightweight tasks from being

## 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-17T00:00:00.000Z

## Install

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

## Wiki

## One-Line Positioning
odai is a kernel that embeds governance (goal / fact / authorization / risk / acceptance) into task execution flows, serving as the main controller for AI agents in DSH; it automatically adjusts processing depth based on task complexity, clarity, risk, and domain gaps, and splits responsibilities between research, planning, execution, acceptance, and frontend design as needed.

## Core Capabilities
- Injects a persistent governance prompt, causing the agent to silently evaluate five criteria ("matter | fact | method | completion | boundary") before taking action on each request
- Automatically selects between three modes—direct execution, same-round escalation, or external sub-agent—based on current task complexity, clarity, risk, and domain requirements
- Maintains configurable responsibility model mapping (researcher / planner / executor / reviewer / frontend), persisting and activating in the next round after users name providers and models in natural language
- Persists output形态 (normal / soft-compacted / economy mode), compaction model, skill source (bundled / auto / user), and semantic memory, all written to corresponding JSON files under `$DSH_HOME/odai/`
- Registers tools like `odai_routing_config`, `odai_route_card`, `odai_output_config`, `odai_compaction_config`, `odai_memory`, allowing the controller to read and modify its own governance state without modifying host files
- Provides a skill self-evolution overlay layer, allowing users to replace governance markdown content without reinstalling the package; each replacement leaves base/result generational records and lineage relationships

## Technical Implementation
- **Language**: JavaScript (Node.js ESM `.mjs`), no build step
- **Key Dependencies**: `@deepseek-ai/dsh` (peerDependency, DSH Cordis host; marked optional), `node:crypto` `node:fs` `node:path` `node:os` (built-in modules), standalone `yaml` only used for Agent installer (`dsh/agent/package.json:48-50`)
- **Architecture Pattern**: Registers a plugin named `odai-governance` to the host via DSH's Cordis patch bundle (`dsh/plugin/cordis.patch.yml:1-7`), with injection points at `systemPrompt / tools / subagents / sessions` (`dsh/runtime/src/index.mjs:95-96`); runtime mounts multiple ctx.on hooks (`system-prompt/assemble`, `agent/pre-step`, `agent/request`, `agent/turn-stopping`, `session/event`, `tools/result`, `llm/stream`) to implement governance and routing
- **Entry Point**: `dsh/runtime/src/index.mjs` (mounted via `dsh/plugin/cordis.patch.yml`; `package.json:16` main and exports also point to this file)

## Use Cases
Suitable for those who want DSH agents to handle real project changes without them rushing ahead with false certainty: the vanilla host tends to act directly or go through motions when facing ambiguous, cross-capability, or high-risk tasks. odai solidifies "see the facts first, choose the shortest sufficient path, finish with evidence" into reusable governance while ensuring trivial requests aren't slowed by procedures. It works while preserving the host's default model; users don't need to pre-specify which model each responsibility uses.

## Prerequisites & Compatibility
| Dependency | Min Version | Notes |
|---|---|---|
| DeepSeek Harness (dsh) | 0.1.0-rc.6 | Both packages declare `@deepseek-ai/dsh@0.1.0-rc.6` as optional peerDependency; Agent installer directly rejects when `dsh -V` output version doesn't match this value |
| Node.js | >=22.15.0 | Both `package.json#engines.node` declare this lower bound |
| pnpm | No specific version declared | Plugin install command calls `pnpm`, requiring `pnpm` in `PATH` |
| Platform | Cross-platform | No `os` / `cpu` restrictions declared; plugin works on all DSH-supported platforms |
| Native modules | None | All dependencies are Node.js built-in modules or optional peer-provided host |

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

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `routing.mode` | String (off/observe/auto/execute) | Responsibility routing mode: off completely disables; observe only observes without executing; auto decided by routing table; execute always executes | `auto` |
| `routing.provider` | String | Provider id used when actually spawning sub-agents | `spawn` |
| `routing.maxInputChars` | Integer (≥256) | Max characters of task text captured for each routing decision | `12000` |
| `routing.configPath` | Path string | Persisted JSON path for user responsibility model mapping | `$DSH_HOME/odai/routing.json` |
| `routing.roles.{researcher,planner,executor,reviewer,frontend}` | Object | Provider/model for each role, optionally reasoningEffort/maxTokens | Written by `odai_routing_config` tool when unconfigured |
| `governance.additionalDeniedTools` | String array | Tool names to deny on top of built-in blacklist | `[]` |
| `governance.skillSource` | String (bundled/auto/user) | Skill source priority; bundled locks to package skill, auto/user switched via `odai_skill_source_config` | `bundled` |
| `governance.skillConfigPath` | Path string | Skill source persistence file | `$DSH_HOME/odai/source.json` |
| `governance.evolutionRoot` | Path string | User skill self-evolution overlay root directory | `$DSH_HOME/odai/skill-evolution` |
| `output.configPath` | Path string | Output形态 persistence JSON path | `$DSH_HOME/odai/output.json` |
| `compaction.configPath` | Path string | Compaction model persistence JSON path | `$DSH_HOME/odai/compaction.json` |
| `compaction.cacheRetention` | String (provider-default/short/long/none) | Prompt-cache retention strategy in compaction requests | `provider-default` |
| `memory.mode` | String (auto/off) | Whether semantic memory auto-activates at each controller step | `auto` |
| `memory.storePath` | Path string | Semantic memory persistence JSON path | `$DSH_HOME/odai/memory/store.json` |
| `memory.maxRetrieved` | Integer (1–12) | Max memory entries injected per turn context | `6` |
| `skillPath` | Path string | Explicitly overrides default canonical skill path; uses bundled skill when unset | Auto-resolved from `ODAI_SKILL_PATH` or package location |

Configuration options can also be written not in `cordis.patch.yml` but auto-persisted by tools like `odai_routing_config`, `odai_output_config`, `odai_compaction_config`, `odai_skill_source_config`, `odai_memory` when users make natural language requests.

## FAQ

**Q: Must restart DSH session after installation for it to take effect?**

A: Yes. Plugin is profile-level bundle; after installation you must restart current DSH process, then open new session with that profile to get governance injection; current session still runs with host default behavior.

**Q: Will every simple question be slowed down by procedures after installation?**

A: No. Runtime first does a light task gate: if result, action, path, authorization, and verification are all clear and low-risk, it executes directly; only when prerequisites are questionable, scope conflicts, cross-layer tradeoffs, or high-risk side effects appear does it expand.

**Q: Do I need to manually specify models for planning or execution?**

A: No. Both packages default to `routing.mode=auto`; tasks host default model can complete won't switch on their own; only when user explicitly specifies "planning uses provider/model, reasoning effort high" in natural language will it persist to `$DSH_HOME/odai/routing.json`, taking effect next user turn. Odai won't proactively help you choose models.

**Q: What state gets written to local?**

A: Routing mapping, output mode, compaction model, skill source, and skill self-evolution content are respectively written to `routing.json`, `output.json`, `compaction.json`, `source.json`, and `skill-evolution/` under `$DSH_HOME/odai/`; semantic memory is written to `memory/store.json`. These directories are shared by Agent and Plugin; neither package auto-cleans them when uninstalled.

**Q: After installing odai-dsh-plugin, do I still need odai-dsh-agent?**

A: Usually not. Plugin already includes canonical skill and DSH runtime, covering entire profile; Agent is an independent form that selects Odai preset per session. When both intentionally coexist, they share the same snapshot; normal simultaneous installation is redundant—only needed when user explicitly wants to combine two scopes.

**Q: Must stop DSH before upgrading or uninstalling?**

A: Yes. Plugin's `repair-sessions` subcommand and Agent's install/update/uninstall all actively confirm DSH process has stopped; local process check failure or detecting DSH still running causes direct rejection.

**Q: Does economy mode's token ceiling always take effect?**

A: Not necessarily. Runtime only passes user-specified `maxTokens` through DSH to provider, cannot force provider compliance: actual usage may include hidden reasoning, exceed requested value, or end before getting full text. Strict accounting requires using host's returned real usage data.

## Learning Curve
Advanced — requires understanding DSH's profile, Plugin and Agent concepts, and the meaning of multiple JSON files under `$DSH_HOME/odai/`; writing your own governance skills also requires familiarity with SKILL.md and six reference files under `skills/odai/`. Regular users can use default config directly via `/odai`, but adjusting routing, compaction, or skill source requires understanding configuration options and persistence paths.

## Known Issues & Limitations
- When persisted routing / output / compaction / memory config files are corrupted or fields are invalid, runtime won't forcibly recover; it only outputs warning and falls back to host default routing; if a high-impact routing is thus missing, controller is set to read-only (fail closed) rather than pretending success (`dsh/runtime/src/index.mjs:556-557`, `673-680`, `706-714`)
- When `compaction.cacheRetention` is set to `short/long/none`, it's still request-level suggestion; if upstream provider doesn't support or chooses to ignore, DSH still lands on its own default, cannot force (`dsh/README.md:55`)
- `odai/cli` is a provider-neutral standalone product, not part of this DSH integration; don't mix it with `odai-dsh-plugin` or `odai-dsh-agent` (`dsh/README.md:11`)
- Agent installer has hard match on `dsh` version, doesn't support `>=` range; currently only accepts `dsh@0.1.0-rc.6`; upgrading DSH requires syncing refresh Agent preset and both package versions (`dsh/agent/bin/odai-dsh-agent.mjs:52-63`)
- When both Plugin and Agent are installed, they share same per-agent/per-turn snapshot; prompt governance and routing role contract can't each select different skill bundle (`README.md:94`)
- User semantic memory is shared by Plugin and Agent, and Agent's install/update/uninstall and Plugin's update neither manage or delete `$DSH_HOME/odai/memory/`; back up or clear before uninstalling (`dsh/README.md:45`)
- `odai-repair-sessions` directly rejects on local process check failure or detecting DSH still running, leaves no ambiguity; must run after DSH completely stops (`dsh/plugin/README.md:25-27`)

---

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