一句话定位

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 plugin --profile web add github:orziz/odai/dsh/plugin

配置项

常见问题

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)

English · 中文

odai

odai is a governance-powered general task-execution framework for AI agents.

It embeds governance into execution: align the real objective, facts, assumptions, authorization, risks, and acceptance; then choose the shortest sufficient path, combine the right capabilities, act, verify, and keep moving until the task is genuinely deliverable. It does not replace the model's judgment with a rigid workflow.

The short version: call /odai; governance stays nearly invisible on simple work, while ambiguity, complexity, risk, and domain needs automatically increase or reduce the depth of handling.

Why Use It

odai is for people who want agents to move with autonomy, but not with false confidence.

It helps an agent:

• ask only when the missing answer would change the goal, scope, authorization, acceptance, risk, or stop line
• verify what it can verify from files, commands, logs, tests, or project context before asking you
• keep lightweight tasks lightweight instead of turning every request into ceremony
• avoid claiming that something was tested, delegated, reviewed, or verified when it was not
• combine specialist skills and domain guidance only when the task needs them, instead of stuffing every rule into every turn
• reuse existing host or project memory, persisting only durable information with provenance, scope, and invalidation conditions
• respond early and humanely to persistent low mood or self-harm/suicide inclination without diagnosing, labeling, waiting for a plan, or causing secondary harm

The Dao of odai

The user defines the task; evidence determines the route; methods adapt to circumstances; verification determines completion; boundaries determine where to stop—get the task done, without acting presumptuously.

This is not a collage of philosophical schools. It is one decision rule:

• Get the task done: advance the user's task to a verified, deliverable result, while surfacing counterexamples, risks, and a better route when they would change the outcome.
• Do not act presumptuously: do not bend facts, user decisions, or hard boundaries; do not conclude without evidence, exceed authorization, invent work, or treat a discovery as permission to implement it.

The person and the model work as partners toward a shared result, not through a one-way command chain. The person contributes intent, context, value judgments, and unacceptable outcomes; the model contributes judgment, evidence, creation, and execution, challenges doubtful premises, and proposes better routes. Both calibrate understanding and trust through real progress, candid uncertainty, and feedback. The person owns goal-level tradeoffs; the model chooses professional implementation details within the agreed boundary. Authorization is not blind obedience, and challenge is not a takeover.

odai is neither an echo of the user nor a reciter of rules. It takes the person's purpose as its direction and facts and boundaries as its constraints, forms its own judgment and recommendation, holds a justified disagreement when necessary, and changes its mind when the evidence changes. Truth outranks pleasing, effectiveness outranks ceremony, reliable results outrank superficial shortcuts, and long-term trust outranks one-turn performance.

The model's initiative is judged by net value. Speed, quality, stability, cost, breadth, and practicality are outcomes to balance against the user's goal and the evidence—not a flat list of slogans, and never substitutes for a real result.

Operating Standard

See clearly, hold steadily, strike accurately, land real results, defend what matters, and build for the long run.

Understand the real objective, facts, and gaps; hold authorization, boundaries, and risk steady; choose the narrowest sufficient path; produce a verifiable deliverable; protect user decisions, system safety, and truth; and leave a result that survives use, maintenance, and change.

Product Goal

Make agents faster, more accurate, better, steadier, cheaper, lighter, broader, more adaptive, more useful, and more practical. These are not independent process targets. They are product outcomes balanced around the task's net value; process, file count, tokens, and benchmark scores never substitute for getting the real task done.

30-Second Start

Install the unified entry point:

npx skills add https://github.com/orziz/odai --skill odai

Then invoke it with /odai. That is the normal form in clients that expose skills as slash commands:

/odai update the onboarding flow copy.
Goal: make it clearer for first-time users.
Materials: current app files and README.
Constraints: do not change behavior yet; give me the proposed copy and risks first.

If slash commands are not available in your client, naming odai in plain language works too.

You do not need to know the internal structure or choose a methodology. odai infers the required depth, capability, domain knowledge, and verification from the task and project evidence.

DeepSeek Harness packages

DSH users can install either integration independently:

# Apply Odai to every agent preset in one profile
dsh plugin --profile web add odai-dsh-plugin

# Install a selectable, session-scoped Odai Agent preset
npx odai-dsh-agent install

The Plugin command requires pnpm on PATH; the Agent installer supports exactly dsh@0.1.0-rc.7 and dsh@0.1.0-rc.8. Each package already includes the canonical Odai skill and shared DSH runtime, and existing installations keep that bundled skill as the default. The Agent preserves every capability from the pinned DSH Standard preset and adds Odai as a scoped extension. Plugin needs neither a separate skill nor Agent; Agent needs neither a separate skill nor Plugin. Choose Plugin for profile-wide behavior or Agent for a selectable preset. Installing both is normally redundant and is only for a deliberate combination of those scopes. The existing provider-neutral odai-cli remains a separate product.

Both DSH packages default output to soft concise. Users can explicitly select normal output or the optional economy mode, which combines concise presentation with a user-adjustable provider output ceiling: it defaults to 500 when economy is requested without another value. The ceiling never changes child-agent, compaction, checkpoint, or internal context budgets and may be exceeded or ignored by the provider. See dsh/README.md for the complete three-mode contract.

A complete independently installed Odai skill can update faster than either DSH package without changing the default. The user must explicitly ask Odai to switch the skill source to auto or user; auto can select compatible project .dsh/.agents bundles and newer user installs, while user ignores project roots. An explicit deployment path remains highest priority. Plugin and Agent deliberately installed together share one per-agent/per-turn snapshot, so prompt governance and routing role contracts cannot select different bundles.

Neither DSH package chooses planner, executor, or reviewer models. Tell Odai naturally, for example, use provider/model for planning with high reasoning; the model persists that explicit choice for both surfaces. Later requests stay ordinary: role words are not commands, task state selects direct, inline, same-turn, or child dispatch; an identical planner/controller model is not called twice, and an already-authorized implementation continues automatically after planning. If a needed responsibility is still unconfigured, Odai names it and asks for the model instead of claiming that route ran. Persisted routes are formally resolved before provider I/O: deterministic invalid mappings are backed up and removed by exact match, while authentication, quota, rate-limit, or network failures affect only the current fallback.

DSH human-safety continuity is separate from generic semantic memory. Only an explicit direct-user request can save user-authored care preferences, signals to notice, effective support, or safety-plan steps in the independent local record; the user can inspect, export, correct, remove, or physically clear it, and entries persist until one of those deletion controls is used. New sessions treat it as historical care preference, never as present-risk evidence, diagnosis, or a hidden score, and child agents never receive it.

See dsh/README.md for package boundaries, source precedence, natural-language configuration, and the isolated real-install coexistence verification.

Host Capability Routing

The user identifies who should own each responsibility once, or lets odai recommend a mapping from the host's real capability catalog. After confirmation and installation, the project persists that mapping. Every later conversation and action still starts with /odai or an ordinary task request; the user never repeats models, roles, planning modes, or routing commands and does not need to watch internal handoffs. When models change, update the mapping once in place.

The controller is the persistent task thread that owns the goal, global state, correction loop, and final delivery, not another role launched on every turn. Judgment, implementation, and acceptance are internal responsibilities rather than a user workflow. One sufficient capability completes the task in one pass; when the mapping provides genuinely different responsibility capabilities, the host obtains the needed judgment, implementation, or acceptance and returns one result to the current conversation. Reliable no-tool answers stay direct, and follow-ups inherit recent deliveries and unresolved items without making the user restate them.

This routing is constrained by the host; skill text alone cannot mechanically guarantee it. If the host cannot verify model switching or delegation, odai uses one sufficient controller and continues the safely achievable work without pretending that routing occurred. The router is not a prerequisite for ordinary use and is installed only when the user requests managed capability routing.

Managed capability routing and the project guardrail hooks described below are separate mechanisms. Routing registers host roles; experimental stage provides an explicit task-start runner and never injects a hidden per-turn hook. Project guardrails only enforce project-declared read-only paths and acceptance commands and do not route models.

Users on a supported host who want managed role routing do not need to find paths, enter model IDs, or merge configuration by hand. After installing the skill, say:

/odai install and verify capability routing for this project.

odai selects four responsibility mappings from the host's actual capability catalog, explains the persistent effect, asks for one confirmation, and installs them with conflict checks. The default auto policy only registers capabilities: one controller closes the task directly, while planner, executor, and reviewer remain conditional on independent judgment or bounded handoff actually changing the result. It adds no hidden per-turn preflight. Experimental Codex stage is installed only when the user explicitly chooses it and real tasks demonstrate net benefit; it must start at the task boundary so planning and execution share one evidence chain. Reliable direct answers and read-only lookups never invoke another role merely to demonstrate routing.

To remove it, ask odai to uninstall capability routing for the current project. The installer merges with existing host settings, records the original Codex controller configuration for exact restoration, deletes only unchanged files listed in its managed manifest, and preserves unrelated settings. Installation, update, or an actual uninstall requires a new session; project scope is the default. It can generate managed role configuration for Codex, Claude Code, and GitHub Copilot CLI. An explicitly enabled Codex stage additionally provides an executable task-start runner and actual-model verification; the other two hosts must not claim an equivalent level of automatic routing until comparable runtime evidence exists.

When stage is explicitly enabled, .codex/odai-run-routing.mjs is an explicit experiment and maintenance surface, not a transparent daily-work entry. Default auto does not install it; neither policy installs a routing hook.

How It Decides

odai continuously evaluates four dimensions:

• Complexity: direct action, a small amount of structure, staged execution, or durable task state and trusted memory.
• Clarity: enough evidence to act, safe exploration first, or a decision that only the user can make.
• Risk: lightweight verification for reversible work; stronger authorization and evidence for external or hard-to-reverse work.
• Domain: internal craft knowledge, repository conventions, or a specialist host skill for code, documents, spreadsheets, slides, browsers, images, games, and other deliverables.

Before loading any playbook, it applies a silent light-task gate. If the outcome, action, path, authorization, and verification are already clear and low-risk, it acts directly. A suspicious premise, conflicting request, material ambiguity, cross-layer tradeoff, high-risk side effect, or long dependency is what makes it expand.

Depth is not fixed at the start. A task can be upgraded when its impact expands or downgraded when inspection reveals a small local change. SDD, TDD, BDD, agents, consensus, and formal plans are optional methods, not mandatory modes.

Objects supplied only to inform, compare, explain, or verify the target are read-only by default. A request whose result is understanding, judgment, advice, or a plan is not silently upgraded into authorization to modify existing objects; even change requests write only to the identified target.

The point is not to slow the agent down. The point is to make sure it is fast in the places where speed is safe, and careful in the places where guessing would cost you.

Architecture Logic

                         user task
                            |
                            v
       +---------------------------------------------+
       | /odai -> lightweight adaptive kernel       |
       | understand -> choose next valuable action  |
       +---------------------+-----------------------+
                             |
       +---------------------+-----------------------+
       |                     |                       |
       v                     v                       v
  direct action       internal capability      host skill / tool
                     + domain knowledge         + project rules
       |                     |                       |
       +---------------------+-----------------------+
                             v
                    act -> verify -> deliver
                             |
                  new evidence updates the path

Only complex or long-running work loads durable state,
trusted memory, agent coordination, independent challenge, or consensus;
existing memory stays authoritative instead of being mirrored.

The framework owns the task from understanding through delivery. Six flat references provide only the boundary, craft, executable planning and durable handoff, verification, support, or external capability guidance needed at the moment; there is no separate orchestrator workflow or user-selected domain package.

odai's complete capability is not just its entry text. It combines the core, built-in baseline craft, project context, and professional capabilities that are worth using. A clearly matching installed capability may be used directly; a general capability gap warrants an installation recommendation only when the net gain is real; stable, repeated, project-specific craft may be encoded as a project skill. Whatever route is used, odai still owns evidence integration, acceptance, and final delivery. Merely finding, recommending, creating, or invoking a capability is not completion.

Internal Map

The internal structure is organized by responsibility, not by mandatory stages:

Domain depth is inferred from the task instead of selected as a package. Game, UI, documentation, and software work use the built-in craft baseline, then borrow project material, host tools, or professional skills only for a named gap. An optional host responsibility such as frontend is a model-routing adapter for a verified production gap inside the current task, not a selectable domain package or a precedent for enumerating database, security, or other domain roles. Without an external skill or responsibility mapping, odai still completes what the current model can do reliably.

Content work preserves evidence, existing templates, stale responsibilities, and publication boundaries. Complex or long-running work writes decisions, state, and acceptance evidence back to one existing maintenance location only when that materially improves recovery. Code, tests, or the requested artifact remain sufficient when they already carry the complete result.

Good Prompts

Use the level of detail you actually have:

/odai handle this. Decide the route and ask only if a boundary or acceptance point is missing.

/odai review the current diff. Report findings first and do not modify files.

/odai refresh this repository README. Remove outdated screenshots and keep the install path clear.

/odai this task is user-facing. Do not change behavior without approval; verify the proposed route first.

Install Options

Most users only need the unified entry point:

npx skills add https://github.com/orziz/odai --skill odai

Other supported installs:

# Install every skill in this repository
npx skills add https://github.com/orziz/odai --all

# Install the slimmer branch
npx skills add https://github.com/orziz/odai#mini

# Install the older "one skill per ability" layout
npx skills add https://github.com/orziz/odai#old

Use old only if you still depend on the previous standalone skill layout or are comparing a migration.

Canonical source lives in skills/. Distribution is handled through the skills.sh install flow; this repository no longer keeps per-platform mirror outputs. See MAINTAINING.md for the current source, validation, freeze, and release rules, and CHANGELOG.md for frozen architecture changes.

Codex Pets

This repository includes two optional, complementary Codex v2 desktop pets rather than two simple recolors:

Dai gets the work done; Odai makes the process feel accompanied. Each includes nine standard animations and 16 look directions. Installing the odai skill does not install either pet automatically.

See the separate character bibles for Dai and Odai.

From a cloned or downloaded copy, choose a pet and copy its two runtime files into the matching Codex pet directory.

Windows PowerShell (odai; replace both occurrences with dai for the black version):

$petName = "odai"
$petDir = Join-Path $env:USERPROFILE ".codex\pets\$petName"
New-Item -ItemType Directory -Force $petDir | Out-Null
Copy-Item -LiteralPath "pets\$petName\pet.json","pets\$petName\spritesheet.webp" -Destination $petDir -Force

macOS or Linux:

pet_name="odai" # use "dai" for the black version
mkdir -p "$HOME/.codex/pets/$pet_name"
cp "pets/$pet_name/pet.json" "pets/$pet_name/spritesheet.webp" "$HOME/.codex/pets/$pet_name/"

Then open Codex Settings → Pets, refresh the list, and select dai or odai. You can also open the pet picker with /pet. See the dai package README or odai package README for previews and format details.

Optional Hook Guardrails

The skill supplies judgment; hooks only turn already-explicit project boundaries into mechanical guardrails. They are not installed or enabled by default and do not change odai's main flow. Once a project defines .odai/hooks.json, they can protect explicit read-only paths and run explicitly declared acceptance commands that match the current change. With no policy file, they are silent no-ops.

These are the only per-turn hooks managed by odai. The capability-routing installer does not install hooks and cannot substitute for project guardrails.

The repository keeps one dependency-free runtime and generates native host adapters on demand instead of maintaining six platform mirrors:

node skills/odai/scripts/build-hooks.mjs --host all --out /tmp/odai-hooks

Replace all with codex, claude, copilot, gemini, grok, or kimi when only one adapter is needed. Each output contains an ADAPTER.json describing its install form. Start from skills/odai/assets/hooks-policy.example.json, adapt it to project evidence, and place the result at <project>/.odai/hooks.json.

Grok Build currently exposes PreToolUse as the blocking boundary, so its adapter does not pretend that Stop validation is enforceable. The runtime checks structured write tools and project-declared commands only. It does not parse arbitrary shell writes or infer user intent, target files, or test strategy. Hooks are a lightweight fuse alongside host permissions, sandboxing, and human confirmation—not a complete security boundary. Review the generated adapter and .odai/hooks.json before enabling them.

Evaluation

The current results cover 19 realistic full-plan tasks and a 13-task paired A/B subset. Only two cases are explicit low-risk controls. The rest present natural symptoms, opinions, or broad requests; the decisive facts live in project code, logs, briefs, diffs, task state, and runbooks. Fingerprints preserve exact reproducibility; unrelated routing assets or maintenance edits do not invalidate an entire result table when the prompt, fixture, model configuration, scoring semantics, and case-relevant skill behavior remain equivalent. Gemini 3.7 and DeepSeek V4 Pro (DSH) ran under the cross-platform odai-canary-isolation/v1 contract; the other published rows predate that contract and are retained as historical capability evidence.

Each result first receives a 0-4 completion score, then the predefined case weight is applied. The full plan is worth 144 points and the A/B subset 96. Direct, judgment, complex, and boundary work are reported separately, while severe scope, production-risk, and false-verification violations have hard score caps. A perfect treatment score alone is not evidence of value; it must be read against the same model's control result and cost.

All nine runners produced a positive paired gain. Every runner except the two Gemini versions reached full on scores in both the full suite and A/B subset. Eight runners used more tokens with odai, while Gemini 3.6 used 38.2% fewer, so both quality gains and cost changes remain model-dependent—not unconditional improvement or token savings.

See docs/evaluation.md for the current contract, docs/evaluation-results.md for model full-suite/A-B scores and token details, and docs/routing-results.md for optional host-routing quality, role usage, latency, and cost experiments.

Stars and PRs are welcome.