@orion-agents/orion-code 0.1.8 → 0.2.0

package/README.zh-CN.md

@@ -1,636 +1,194 @@
 # Orion Code
 
-> **Orion Code — 通用 Agent 驾驭框架**
-> 一个 CLI 驱动的编码 Agent，具备安全边界、工具编排、记忆系统和上下文管理。
->
-> v0.1.8 — 仓库治理、经审计的 issue 修复与可操作的运行时恢复
+面向终端的目标驱动 Coding Agent。
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0-green.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/typescript-5.0-blue.svg)](https://www.typescriptlang.org)
-[![npm](https://img.shields.io/npm/v/%40orion-agents%2Forion-code.svg)](https://www.npmjs.com/package/@orion-agents/orion-code)
+> v0.2.0 发布候选：单一 Agent Loop、精确能力选择、按需 Skill/MCP、证据驱动 Goal 完成与崩溃可恢复。
 
----
+[English](README.md) · [架构主计划](docs/plan/v0.2.0-dsh-harness-redesign-plan.md) ·
+[迁移指南](docs/migration/v0.1.9-to-v0.2.0.md) ·
+[准出清单](docs/plan/v0.2.0-release-checklist.md)
 
-**🌍 语言**: [English](README.md) | 简体中文
+## v0.2.0 带来了什么
 
----
+Orion 现在只有一条产品执行主干：
 
-## 概览
-
-**Orion Code** 是一个终端编码 Agent，它将 LLM API 封装在安全检查、工具编排、会话管理和上下文感知的驾驭层中。
-
-### 核心理念
-
-| 维度                | 说明                                    |
-| ------------------- | --------------------------------------- |
-| **AI 如马**         | 强大的模型需要引导和约束                |
-| **Orion Code 如缰** | 精准控制方向，防止跑偏失控              |
-| **Harness 系统**    | 安全边界、任务约束、结果验证            |
-| **工具调用**        | LLM 自动调用工具完成任务                |
-| **记忆系统**        | 分层记忆：工作 / 短期 / 长期 / 语义搜索 |
-| **MCP 协议**        | 支持连接外部 MCP Server                 |
-
----
+```text
+Thread → Turn → Step → Item
+                    │
+                    ├─ 冻结的 prompt/model/capability 快照
+                    └─ Capability → Policy → Approval → Sandbox → Execute → durable receipt
+```
 
-## 核心特性
+- **默认更轻。** 普通 coding 首步只暴露 7 个精确 core tools，不再把全部 built-in schema
+  重复发送给模型。Git、LSP、Web、Skill、MCP、batch 和 subagent 按任务选择。
+- **执行路径唯一。** root turn 与 child agent 共用同一种 Agent Loop 和 ToolGateway；模型看到的 schema
+  与实际 dispatch 由同一个 Step Snapshot 绑定。
+- **扩展真正按需。** Skill catalog 只含有界描述，选中后才读取定义和资源；MCP server 在精确选择前
+  不连接、不起进程、不打开 socket，空闲后释放 lease。
+- **完成状态可证明。** history、TaskContext evidence、Goal、StopDecision、Capability 与 Plan receipts
+  在同一个 TurnCommit 中提交。持续有进展的 Goal 可以运行 20+ turns，只在 completion audit 通过后
+  自动退出。
+- **崩溃后可恢复。** append-only runtime facts 是权威源；UI projection、Compact、旧 Session 迁移和
+  resume 都进行 digest 校验，半提交或冲突状态 fail closed。
+- **交互一致。** TUI、terminal、print、Plan、Goal、Compact 与 subagent 使用同一版本化协议。
 
-| 特性            | 说明                                                                       |
-| --------------- | -------------------------------------------------------------------------- |
-| **工具编排**    | 29 个内置工具：文件读写、Shell、网页、记忆、Git、LSP、Goal 和计划          |
-| **多模型支持**  | OpenAI、Claude、DashScope（GLM/Qwen/Kimi）、自定义端点                     |
-| **上下文感知**  | 每个模型独立的上下文窗口，95% 自动压缩                                     |
-| **动态发现**    | 启动时自动通过 `/models` 端点发现模型信息                                  |
-| **MCP 协议**    | 完整 MCP 支持，心跳检测 + 指数退避重连                                     |
-| **记忆系统**    | 用户 / 项目 / 会话记忆，支持语义搜索                                       |
-| **会话管理**    | 会话持久化、历史恢复、摘要生成                                             |
-| **持久 Goal**   | typed 多轮 continuation、安全 restart/resume、逐项证据审计                 |
-| **安全边界**    | Bash 安全检查、审计日志、权限模式                                          |
-| **流式输出**    | 实时 LLM 响应，Markdown 渲染                                               |
-| **TUI**         | 默认且面向公众的主产品界面；支持 transcript、inspector、CJK 输入和工具输出 |
-| **terminal-ui** | 仅用于 runtime 验证、诊断、兼容性排查和必要回退的技术版本                  |
-| **Ink**         | 已废弃，不再承接新功能，计划在 v0.2.0 删除                                 |
-| **Print Mode**  | 实验性 `-p/--print` 一次性入口，用于后续自动化/remote UI 验证              |
-| **状态栏**      | 实时显示 Token 用量、成本、模型、上下文百分比                              |
-| **模型配置**    | `providers + models` profile，可显式绑定端点、协议和上下文能力             |
+架构借鉴 DeepSeek Harness 的 scope/resource lifecycle 和 Codex 的不可变执行契约，同时保留 Orion
+自己的 Goal/Evidence 完成模型。Orion **不是**插件市场或任意 JavaScript 插件宿主；Model、Skills、
+MCP 仍是用户可见的扩展边界。
 
----
+## 安装
 
-## 快速开始
+支持 Node.js 20、22、24。
 
-### 环境要求
+当 npm 已存在不可变的 `0.2.0` 发布凭据后：
 
-- Node.js 20、22 或 24 LTS
-- npm >= 9.0
+```bash
+npm install -g @orion-agents/orion-code@0.2.0
+orion --version
+orion doctor
+```
 
-### 安装运行
+从源码运行：
 
 ```bash
-# 克隆
 git clone https://github.com/orion-agents/orion-code.git
 cd orion-code
-
-# 安装依赖
 npm install
-
-# 构建
 npm run build
-
-# 配置 API Key（任选一种）
-# 方式 1: 环境变量
-export ORION_CODE_API_KEY=your-api-key
-
-# 方式 2: .env 文件
-cp .env.example .env
-
-# 方式 3: ~/.orion-code/orion.json（推荐）
-# 首次运行时自动创建
-
-# 启动默认公众产品 TUI
-npm start
-
-# 显式启动 TUI
-npm start -- --ui tui
-
-# 技术诊断/兼容回退
-npm start -- --ui terminal
-
-# 已废弃的兼容 renderer（v0.2.0 删除）
-npm start -- --ui ink
-
-# 尝试早期实验性的非交互入口
-npm start -- --print "review the current git diff"
-```
-
-### 全局安装
-
-固定安装该精确发布版本：
-
-```bash
-npm install -g @orion-agents/orion-code@0.1.8
-# 安装当前预发布渠道：
-npm install -g @orion-agents/orion-code@next
-# 任意目录运行
-orion
+npm run start
 ```
 
-也可以在源码工作树中使用 `npm ci && npm run build && npm start`。
-
-> **发布状态**：`0.1.8` 已通过 npm `next` dist-tag 发布，并由 `v0.1.8` tag 标识。
-> 稳定版 `latest` 仍为 `0.1.4`；稳定版提升是独立决策。
-
-公众体验、交互优化和新增工作流优先落在 TUI。`terminal-ui` 不作为与
-TUI 并行发展的公众产品；Ink 只保留迁移期兼容，不再增加产品能力。
-
-### 持久 Goal 安全契约
-
-`/target <目标>` 在当前 session 创建唯一 Active Goal。自动 continuation 是结构化 runtime
-请求，不会伪装成用户输入，也不会写入 transcript。进程重启或 `/resume` 后，原 Active Goal
-会以可见的 paused 恢复态加载；用户必须显式执行 `/target resume` 才会继续。
-
-模型只能请求 `complete` 或 `blocked`，不能直接写入终态。Orion 会记录真实工具/runtime
-证据并逐项审计 success criterion；缺失、失败、未映射、类型不匹配、过期或 stale 证据都会让 Goal 保持未完成。
-需要人工验收的 criterion 只能由用户执行 `/target confirm <criterion-id>` 生成可信的 `user`
-evidence，模型工具不能伪造该确认。
-v0.1.2 只覆盖单 Session、单 Active Goal，不承诺多 Goal 调度或无人值守后台执行。
+## 配置模型
 
-完成审计通过后，Orion 会自动清除 session 的 Active Goal 绑定，回到当前
-BUILD/PLAN/AUTO 基础模式，并保留 terminal Goal sidecar 作为可审计的完成凭据。若要在完成前
-放弃 Goal，使用 `/goal exit`：它会中止当前 turn、拒绝待确认工具并删除持久 Goal。明确的自然语言请求（如
-`退出 goal 模式`）会走同一个确定性 runtime 边界，不再依赖模型自行判断。完成请求被拒绝后，
-同一 turn 没有新增 runtime 证据就不能重复提交；自动 continuation 的模型/工具预算也低于新的
-用户 turn。v0.1.6 明确不再支持旧 `/goal clear --yes` 与 `/target clear --yes` 语法。
+Orion 读取 `~/.orion-code/orion.json`。可从
+[`docs/orion.example.json`](docs/orion.example.json) 开始。Provider key 可使用本地值或
+`$HUOSHAN_API_KEY` 这样的环境变量引用；不要提交密钥。
 
----
-
-## 配置
-
-### 用户配置 (`~/.orion-code/orion.json`)
-
-当前推荐使用 `providers + models` 格式。旧的
-`apiKey/apiBaseUrl/defaultModel/fallbackModel` 四字段格式仍可兼容读取，但启动时会提示迁移：
+最小 OpenAI-compatible 示例：
 
 ```json
 {
+  "schemaVersion": 1,
   "providers": [
     {
       "id": "my-provider",
-      "baseUrl": "https://api.example.com/v1",
-      "apiKey": "$MY_API_KEY",
+      "displayName": "My Provider",
+      "baseUrl": "https://example.invalid/v1",
+      "apiKey": "$MY_PROVIDER_API_KEY",
       "protocol": "openai-completions"
     }
   ],
   "models": [
     {
       "id": "my-model",
+      "displayName": "My Model",
       "provider": "my-provider",
       "model": "model-name",
       "contextWindow": 200000,
-      "maxOutputTokens": 64000
+      "maxOutputTokens": 8192
     }
   ],
   "defaultModel": "my-model",
-  "toolConfirmation": "deny",
-  "subagents": { "mode": "auto", "maxParallel": 3 }
+  "toolConfirmation": "allow"
 }
 ```
 
-`provider.apiKey` 支持 `$ENV_VAR` 引用；模型上下文和最大输出应按实际 Provider
-能力填写。renderer 不从配置文件持久化读取：直接运行 `orion` 使用默认 TUI，
-`--ui terminal` 只用于技术诊断和兼容回退。
+配置后运行 `orion doctor`。诊断不需要输出密钥本身。
 
-### 配置优先级
-
-```
-CLI 参数 > ~/.orion-code/orion.json > 环境变量 > 内部默认
-```
-
-### 项目级工具规则（`allowedTools`）
-
-权限规则写在 `projects["<项目绝对路径>"].allowedTools`，只作用于该仓库。规则叠加在
-工具自身的权限策略之上：**只能收紧，不能放宽**。
-
-```json
-{
-  "projects": {
-    "/Users/me/work/api": {
-      "allowedTools": [
-        "exec_command(git status*)",
-        "exec_command(npm test*)",
-        "ask:exec_command(git push*)",
-        "deny:read_file(*.env)"
-      ]
-    }
-  }
-}
-```
-
-- 语法：`[allow|ask|deny:]工具名[(参数通配)]`；`*` 匹配任意字符串，`?` 匹配单个字符，
-  工具名写 `*` 表示匹配所有工具。
-- 参数通配匹配的是调用参数中的 `command` / `file_path` / `path` / `url` / `pattern` /
-  `query`（按此顺序取第一个非空字符串）。
-- 冲突时按“最严格优先”解析：`deny` > `ask` > `allow`，与书写顺序无关。
-- `allow` 仅用于免去交互确认，**不会**覆盖工具自身的 `deny`、**不会**突破 plan 模式的
-  只读约束，也**不会**自动放行破坏性调用。
-- 无法解析的条目会被忽略而不是静默放行，可通过 `/config` 查看解析结果与非法条目。
-
-### 命令执行沙箱（`sandbox`）
-
-`exec_command` 可在操作系统级沙箱内执行。这是**安全 POC**：后端在运行
-时实测探测，已配置但不可用的沙箱会**fail closed**（拒绝执行），而不会静默降级为
-无沙箱执行。
-
-```json
-{
-  "sandbox": {
-    "profile": "none",
-    "backend": "auto",
-    "allowNetwork": false,
-    "writableRoots": [],
-    "image": "alpine:latest"
-  }
-}
-```
-
-- **归属** — `sandbox` 位于全局配置（`~/.orion-code/orion.json`），并可在项目级
-  `projects["<项目绝对路径>"].sandbox` 覆盖。项目级按 key 单独覆盖，缺省 key 继承全局。
-- **`profile`** — `none`（默认，不隔离，等价于旧版 `sh -c`）、`read-only`（任何位置不可写、无网络）、
-  `workspace-write`（写权限限定在工作区与临时目录，除非 `allowNetwork: true` 否则仍禁网）。
-  未知取值（如新版 Orion 写入的更严格值）一律硬失败，绝不降级为 `none`。
-- **`backend`** — `auto`（默认，自动选首个可用后端）、`seatbelt`（macOS `sandbox-exec`）、
-  `bubblewrap`（Linux `bwrap`）或 `docker`。每个后端都用真实执行探针校验，从不靠 `which` 推断。
-- **`image`** — 仅 `docker` 需要，指定运行所用的容器镜像。
-- **`writableRoots`** — `workspace-write` 可写入的额外宿主根目录（除工作区与临时目录外）。
-  非字符串 / 空项会被丢弃。
-- **迁移 / 回滚** — 新增 `sandbox` 完全向后兼容：默认 `profile: "none"` 与旧行为完全一致。
-  删除该 key（或回退到沙箱前的版本）是安全回滚；旧版 Orion 会忽略该未知字段。不涉及任何敏感信息，无需脱敏。
-- **已知限制** — `seatbelt` 不能嵌套在另一沙箱内（例如 Orion 自身运行在应用沙箱中时）；
-  `docker` 在独立进程树中运行命令，只约束被 bind-mount 的部分（镜像根文件系统已通过 `--read-only` 设为只读）；
-  各后端均不限制 CPU / 内存。
-
-### 环境变量
-
-| 变量                            | 默认值        | 说明                            |
-| ------------------------------- | ------------- | ------------------------------- |
-| `ORION_CODE_API_KEY`            | -             | LLM API 密钥                    |
-| `ORION_CODE_API_BASE_URL`       | -             | API 基础 URL                    |
-| `ORION_CODE_MODEL`              | `gpt-4o`      | 默认模型                        |
-| `ORION_CODE_MODE`               | `development` | 运行模式                        |
-| `ORION_CODE_LOG_LEVEL`          | `info`        | 日志级别                        |
-| `ORION_CODE_EMBEDDING_PROVIDER` | -             | Embedding 服务（ollama/openai） |
-
-运行 `/config` 可查看当前生效配置，`orion --help` 可查看 CLI 级覆盖方式。
-
----
-
-## 支持的模型
-
-### 模型家族
-
-| 服务商           | 模型                                               | 端点             |
-| ---------------- | -------------------------------------------------- | ---------------- |
-| **GLM（智谱）**  | `glm-5`, `glm-4`                                   | DashScope coding |
-| **Qwen（通义）** | `qwen-turbo`, `qwen-plus`, `qwen-max`, `qwen-long` | DashScope coding |
-| **OpenAI**       | `gpt-4o`, `gpt-4o-mini`, `gpt-4`                   | OpenAI API       |
-| **Claude**       | `claude-sonnet-4-6`, `claude-opus-4-8`             | Anthropic API    |
-| **DeepSeek**     | `deepseek-chat`, `deepseek-reasoner`               | DeepSeek API     |
-
-### 上下文窗口
-
-Orion Code 跟踪每个模型的上下文窗口，在 **95% 用量时自动压缩**：
-
-| 模型                | 上下文    | 最大输出 |
-| ------------------- | --------- | -------- |
-| `glm-5`             | 202,752   | 8,192    |
-| `qwen-long`         | 1,000,000 | 8,192    |
-| `qwen-plus`         | 131,072   | 8,192    |
-| `gpt-4o`            | 128,000   | 16,384   |
-| `claude-sonnet-4-6` | 200,000   | 16,000   |
-| `claude-opus-4-8`   | 200,000   | 32,000   |
-
-未知模型默认使用 **128,000** 上下文。
-
-### 动态发现
-
-启动时 Orion Code 会查询 `/models` 端点获取上下文数据。若端点不支持（如 DashScope coding 返回 404），则静默回退到内置数据库。
-
-### 模型命令
+## 使用 Orion
 
 ```bash
-/model               # 显示当前模型
-/model list          # 列出所有可用模型
-/model glm-5         # 切换到 GLM-5
-```
-
----
-
-## 工具列表
-
-### 文件操作
-
-| 工具         | 说明               |
-| ------------ | ------------------ |
-| `read_file`  | 读取文件内容       |
-| `write_file` | 写入文件           |
-| `edit_file`  | 编辑文件（行替换） |
-| `list_files` | 列出目录内容       |
-| `glob`       | Glob 模式搜索文件  |
-| `grep`       | 正则搜索文件内容   |
-
-### Shell 执行
-
-| 工具           | 说明                          |
-| -------------- | ----------------------------- |
-| `exec_command` | 执行 Shell 命令（带安全检查） |
-
-### 网络工具
-
-| 工具         | 说明         |
-| ------------ | ------------ |
-| `web_fetch`  | 抓取网页内容 |
-| `web_search` | 网络搜索     |
-
-### 记忆系统
-
-| 工具            | 说明     |
-| --------------- | -------- |
-| `memory_save`   | 保存记忆 |
-| `memory_recall` | 搜索记忆 |
-| `memory_forget` | 删除记忆 |
-
-### 任务管理
-
-| 工具             | 说明                                       |
-| ---------------- | ------------------------------------------ |
-| `todo_write`     | 创建/更新任务列表                          |
-| `exit_plan_mode` | 提交计划并自动退出计划模式（模型内部工具） |
-
----
-
-## 上下文管理
-
-### 自动压缩 (Auto-Compact)
-
-当上下文使用量达到 **95%** 时，Orion Code 自动压缩对话历史：
-
-1. **生成摘要** — 通过 LLM 对早期消息生成摘要
-2. **替换旧消息** — 用 `[Context Summary]` 块替代
-3. **保留关键信息** — 保留系统消息和最近消息
-4. **状态栏通知** — 显示压缩信息
-
-```
-Compact: 30 → 8 messages | Context: 45% → 12%
-```
-
-### 基于 Token 的阈值
-
-与基于消息数量的方案不同，Orion Code 使用 API 返回的 **实际 Token 数** 进行精确的上下文感知：
-
-```
-ctxPercent = (promptTokens / 模型上下文窗口) × 100
+orion                         # 默认产品 TUI
+orion --ui terminal           # 技术诊断 terminal fallback
+orion -p "解释这个仓库"       # 实验性的非交互模式
+orion -p --output-format json "运行 focused tests"
+orion diff
+orion commit
 ```
 
-仅当 `ctxPercent >= 95%` 时触发压缩，不基于消息数量。
+`orion -p` 是早期实验性的非交互入口；需要确认弹层或实时 steering 的任务应使用 TUI。
 
-### 30 秒间隔
+### BUILD、PLAN、AUTO
 
-为避免过度压缩，自动压缩最多每 30 秒执行一次。手动 `/compact` 命令可绕过此限制。
+按 `Shift+Tab` 循环 `BUILD → PLAN → AUTO`。状态栏和输入框边框会显示当前模式。Mode 决定工作流，
+Authority、approval、路径边界和 sandbox policy 是独立状态轴。
 
----
+- **BUILD**：正常协作开发。
+- **PLAN**：使用同一套可用工具完成探索；将 decision-complete plan 写入 durable PlanReceipt；自动退出
+  Plan、恢复 BUILD/AUTO，并在新的 logical turn 中执行。
+- **AUTO**：在已配置 Authority 内取消交互确认；hard policy 与 sandbox 边界仍然 fail closed。
 
-## MCP 协议
+任务式进入：
 
-完整支持 MCP (Model Context Protocol) 服务器：
-
-### 配置 MCP Server
-
-创建 `~/.orion-code/mcp.json`：
-
-```json
-{
-  "servers": {
-    "telegram": {
-      "command": "node",
-      "args": ["path/to/plugin-telegram/dist/index.js"],
-      "env": {}
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@anthropic/mcp-server-filesystem", "/allowed/dir"]
-    }
-  }
-}
+```text
+/plan 重构 storage boundary 并验证 crash recovery
 ```
 
-### MCP 命令
-
-```bash
-/mcp                # 显示 MCP Server 连接状态
-```
+不存在 `exit_plan_mode` 工具，也没有 `/mode` 命令。
 
-启动时自动连接，支持心跳检测和指数退避重连。
-
----
-
-## 常用交互命令
-
-| 命令                   | 说明                                                |
-| ---------------------- | --------------------------------------------------- |
-| `/help`                | 显示当前 renderer 可用的完整命令列表                |
-| `/goal`                | 创建、查看、暂停、恢复、替换、预算或退出持久 Goal   |
-| `/plan [任务]`         | 先只读规划，再自动进入独立执行阶段                  |
-| `/status`              | 系统状态总览                                        |
-| `/model`               | 查看或切换模型                                      |
-| `/config`              | 显示当前生效配置                                    |
-| `/usage`               | 显示详细 Token 用量和成本                           |
-| `/compact`             | 手动触发上下文压缩                                  |
-| `/session list`        | 列出或搜索最近会话                                  |
-| `/resume`              | 恢复已有会话                                        |
-| `/memory`              | 记忆状态、引用漂移校验与语义索引重建                |
-| `/skills`              | 列出已加载技能                                      |
-| `/tools`               | 列出内置和 MCP 工具                                 |
-| `/mcp`                 | 查看 MCP Server 状态                                |
-| `/doctor`              | 运行配置、工具、MCP、Skill、Session 和 Harness 诊断 |
-| `/diff`                | 只读汇总当前 Git 工作区改动                         |
-| `/commit-plan`         | 生成只读 commit 计划和建议消息                      |
-| `/context clear --yes` | 清除当前内存中的模型上下文，保留已保存 session      |
-| `/clear`               | 只清理当前视图，不删除 session 数据                 |
-| `/exit`                | 安全关闭并退出                                      |
-
-Agent mode 是 TUI 交互状态：使用 `Shift+Tab` 循环 `BUILD → PLAN → AUTO`；`/mode` 与 `/perm`
-不再注册。其余旧拼写保留到 v0.3.0 兼容窗口结束：`/target` → `/goal`、`/commit` →
-`/commit-plan`、`/sessions` → `/session list`、`/session-rename` → `/session rename`、
-`/context-clear` 与 `/clear-history` → `/context clear`、`/models` → `/model`、
-`/loop-stats` → `/usage loop`、`/checkpoint` → `/rewind`、`/cost` → `/usage`、`/agents` →
-`/subagents`、`/task` → `/goal`，以及 `/run`、`/chat` → 直接输入自然语言。
-
-完整列表及 renderer 范围以 `/help` 为准；deprecated/compatibility 命令不属于公开主工作流。
-
----
-
-### 任务级 Plan 模式
-
-执行 `/plan` 后，下一条消息进入计划任务；也可以用 `/plan <任务>` 立即开始，或使用
-`Shift+Tab` 在 `BUILD → PLAN → AUTO → BUILD` 间循环并保留输入草稿。Plan 模式先只读探索，
-禁止文件修改、变更命令和外部操作；计划完整后，模型只调用一次 `exit_plan_mode`，Orion
-保存计划并在独立 logical request 中自动开始执行。Build 是普通协作模式；Auto 不弹权限或
-澄清问题，但仍执行 hard deny、沙箱、危险命令和用户明确边界。基础模式只通过 `Shift+Tab`
-切换；已移除的 `/mode` 与 `/perm` 不保留兼容入口。
-
-详见 [Plan 模式生命周期契约](docs/plan/plan-mode-contract.md)。
-
----
-
-## 项目结构
+### Durable Goal
 
+```text
+/goal 修复开放问题，运行准出门禁，仅在证据完整后停止
+/goal status
+/goal pause
+/goal resume
+/goal clear
 ```
-orion-code/
-├── bin/
-│   └── orion                     # npm 全局命令入口
-├── src/
-│   ├── cli.ts                    # CLI 入口和 renderer 选择
-│   ├── commands/                 # 斜杠命令注册表与处理器
-│   ├── core/                     # Agent 核心状态
-│   ├── framework/                # Query 与 Tool 抽象
-│   ├── runtime/                  # Shared runtime、Goal、事件与 Subagent
-│   ├── services/                 # 配置、LLM、Session、Storage、MCP
-│   ├── tools/                    # 内置工具
-│   ├── tui-ui/                   # 默认公众 TUI
-│   ├── terminal-ui/              # 技术诊断 renderer
-│   ├── print-ui/                 # 实验性 Print/Text 与 Print/JSON
-│   └── skills/                   # 内置 Skill
-├── tests/                        # Jest 测试套件
-├── scripts/smoke/                # 真实终端与 PTY smoke 脚本
-├── docs/
-│   ├── goals/                    # 项目 Goal、证据与恢复说明
-│   ├── mvp/                      # 版本计划与发布说明
-│   └── plan/                     # 执行计划与准出报告
-├── package.json
-└── tsconfig.json
-```
-
----
-
-## 版本历史
-
-### v0.1.8（当前版本，已发布至 next）
-
-- 收敛 npm 发布白名单与包体积门禁，归档历史计划并删除已证明无引用的旧资产、脚本和 UI 实验目录；
-- 完成 33 个 open issues 的逐项账本，补齐数值型工具参数边界、budget-stop 恢复提示、renderer scope 与 AUTO 网络授权可见性；
-- 真实验证 BUILD/PLAN/AUTO、Goal 自动退出、TUI/Terminal/Print/Research 以及旧 Ink 兼容入口；
-- 已合并、创建 `v0.1.8` tag，并通过 npm `next` 发布；未移动稳定版 `latest`。
-
-### v0.1.7（已发布至 next）
-
-- 引入原创 Orion Pixel 与“星际小猎人”，并为 classic、NO_COLOR、窄终端提供安全降级；
-- 使用类型化 Chrome 统一 Goal、权限、模型、上下文、队列与 Active Work 状态层级；
-- Enter 继续 steering，Tab 加入有界 FIFO follow-up 队列，Shift+Tab 循环 BUILD/PLAN/AUTO；
-- 已合并、创建 `v0.1.7` tag 和 GitHub prerelease，并通过 npm `next` 发布；未移动稳定版
-  `latest`。
-
-### v0.1.6（已发布至 next）
 
-- Goal 创建需要显式用户授权，自动 continuation 有界，`/goal exit` 提供确定退出路径；
-- 修复 native migration、测试确定性、seatbelt/exec cwd 与 terminal control-sequence 安全问题；
-- 已合并、创建 `v0.1.6` tag 和 GitHub Release，并通过 npm `next` 发布；未移动稳定版 `latest`。
+`/goal <objective>` 创建 Goal。有进展的 Goal 没有固定 turn-count 上限；资源预算、连续无进展、阻塞、
+provider/persistence 错误和用户中断仍产生明确 StopDecision。证据审计通过后，Goal 提交完成并自动退出。
 
-### v0.1.5（已发布至 next）
+v0.2.0 breaking cut 已删除 `/target`、`/goal exit`、`edit`、`replace`、`confirm`、`budget` 和
+`clear --yes`，不会把旧命令静默解释为新目标。
 
-- 统一类型化命令描述、TUI 命令控制面与 Provider-aware Effort；
-- 修复 Goal/TUI 展示与授权边界，并加强跨进程持久化、安全和发布门禁；
-- 以 npm `next` dist-tag 发布，不移动稳定版 `latest`。
+### 常用命令
 
-### v0.1.4-2（已发布至 next）
+- `/help`、`/status`、`/doctor`、`/harness explain`
+- `/tools`、`/skills`、`/skill <name>`、`/mcp`
+- `/context`、`/memory`、`/usage`、`/trace`、`/last-tool`
+- `/model`、`/effort`、`/permissions`、`/config`
+- `/compact`、`/resume`、`/session`
+- `/diff`、`/commit-plan`、`/review`、`/research`、`/security`、`/test-gen`
 
-- 汇总 v0.1.4 后续的安全、持久化、Goal/runtime、Research、依赖与发布门禁修复；
-- 以 npm `next` dist-tag 发布，不移动稳定版 `latest`。
+安装版本中的 `/help` 是命令清单的权威来源。
 
-### v0.1.4（已发布）
+## Runtime 保证
 
-- 版本元数据对齐：`package.json` / `package-lock.json` 升至 `0.1.4`，`orion --version`、
-  出站 `User-Agent` 与崩溃/遥测上报不再误报 `0.1.3`；
-- 类型安全推进：外部边界（LLM provider、MCP wire、工具返回）由 `any` 收窄为 `unknown` +
-  类型守卫，顺带修复被 `any` 掩盖的真实缺陷；
-- 可靠性：持久化与鉴权路径不再静默吞掉异常，ESLint 启用 `no-empty` 门禁。
+- 每个 Thread 最多一个 active turn；steer、follow-up、interrupt、overload 和 maintenance 都返回 typed
+  admission outcome。
+- 每个已开始的 tool Item 恰好一个 durable terminal outcome。嵌套 batch child 保留 parent/child
+  invocation lineage，并重新进入 ToolGateway。
+- 慢 renderer 可以合并 ephemeral delta，但 durable events 不会静默丢失且可以 replay。
+- Compact 只有在 source history、TaskContext、projection 与 pointer CAS 都通过后才提交。
+- v0.1.9 Session 采用 side-by-side materialization；event replay 与 projection digest 验证后才切 active
+  index。
+- public exports 只提供产品 runtime/protocol 与 Model/Skill/MCP 配置边界，不暴露内部 service locator
+  或插件 SDK。
 
-### v0.1.3（已发布）
-
-- `/model` 与 `/models` 拆分：`/model` 只显示当前模型信息，`/models` 承接交互式切换；
-- `modelRegistry` 成为模型展示与切换的唯一事实源，静态 catalog 退为 legacy fallback；
-- 内置 catalog 补全（火山方舟 / xf-yun / deepseek 等），未配置上下文时正确回退；
-- 命令沙箱 POC、只读 Git 工具与工具 allowlist 的安全基线。
-
-> 完整变更与交付状态（已发布 / 已合并 / 候选）以 `CHANGELOG.md` 为准。
-
-### v0.1.2（已发布）
-
-- 单 Session、单 Active Goal 的 typed continuation；
-- restart/resume 后安全暂停，必须显式恢复；
-- runtime evidence ledger、逐 criterion completion audit 与精确 stop reason；
-- TUI 主产品体验和 terminal-ui/Print 事件语义一致。
-
-### v0.1.1（已发布）
-
-- 命令契约、TUI 默认路径、OpenHorse 迁移和数据安全收敛；
-- terminal-ui 定位为技术诊断版本，Ink 正式废弃。
-
-### v0.1.0（已发布）
-
-- Orion Code 首个公开基线版本。
-
-详见 `docs/mvp/` 和 `docs/plan/`。
-
----
-
-## Research-to-Evidence（v0.1.4，实验性）
-
-> **状态标记：experimental（实验性）。** 把只读 `research` 子 agent 的结果转化为**可追踪、可恢复**的研究→证据闭环。
-
-核心保证（违反任一即 No-Go，绝不发布）：
-
-- **只接专用 WebSearch / WebFetch**，不暴露通用 MCP、不授予 write/exec。
-- **SSRF / DNS 重解析 / 重定向 / 响应大小 / 超时** 全部走既有守卫：选择期做 lexical SSRF 预检，逐跳防护委托给真实 WebFetch 工具。
-- **claim 必须有 source 绑定**才能进入 `observed`；无独立验证的 claim 永远停在 `partial`/`unmet`，绝不被算作已验证/完成。
-- **安全闸门失败 → `blocked`/`failed` + 结构化原因**，绝不伪装成命中；provider fallback 只换 provider，不降级 source status，也不把失败写成成功。
-- 研究证据（web）与执行验证证据（file / 测试 / 构建 / 文件事实）**明确区分**，web 摘要不能替代执行验证。
-- 包与源元数据**原子 CAS 保存**，project / session / Goal 作用域隔离；恢复只推导状态、不重放外部副作用；旧 schema 版本 fail-closed。
-
-模块：`src/runtime/subagents/{research-types,research-contract,research-citation,web-research-adapter,research-renderer,research-artifact,research-quality}.ts`。
-
-> 真实终端（PTY）与外部状态证据在 CI 中标记为 `not_run`；本地测试不视为发布完成。
-
----
-
-## 开发
+## 开发与验证
 
 ```bash
-# 安装依赖
-npm install
-
-# 开发模式（热重载）
-npm run dev
-
-# 构建
-npm run build
-
-# 运行测试
-npm test
-
-# 代码检查
 npm run lint
-
-# 格式化
-npm run format
-
-# 发布前只读检查（不会 tag / push / publish）
-npm run release:check
+npm run build
+npm test -- --runInBand
+npm run test:coverage -- --runInBand
+npm run test:harness-confluence
+npm run bench:harness:baseline
+npm run bench:harness
+npm run bench:harness:compare -- <baseline.json> <candidate.json>
+npm run prepublishOnly
 ```
 
----
-
-## Roadmap
-
-| 版本   | 目标                                                |
-| ------ | --------------------------------------------------- |
-| v0.1.2 | Goal 连续性、证据审计、恢复与发布可信度             |
-| v0.2.0 | 在项目级 Goal 约束下评估多目标等非 patch 兼容性能力 |
-
-详见[项目级目标](https://github.com/orion-agents/orion-code/blob/main/docs/goals/orion-code-项目级目标.md)。
-
----
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
----
-
-## 许可
+正式准出还会只构建一次 exact tarball，并在 Node 20/22/24 安装同一个 hash，验证 package identity、
+native SQLite、TUI、terminal、print、Goal、subagent、Skill、MCP、Compact 与 resume。详见
+[`v0.2.0 准出清单`](docs/plan/v0.2.0-release-checklist.md)。
 
-MIT License — 详见 [LICENSE](LICENSE)
+## 安全
 
----
+不要提交 `.env`、`~/.orion-code`、本地数据库或凭据。文件访问受 project boundary 限制，symlink 和
+non-regular path escape 会 fail closed，所有副作用通过同一 Authority/Policy/Approval/Sandbox 链。
 
-**Orion Code — Universal Agent Harness Framework.**
+## License
 
-_"AI 如马，Orion Code 如缰。"_
+MIT，见 [LICENSE](LICENSE)。