# OME 工程化模式：架构、安装与验收

本文面向 DSH 管理员、插件维护者和需要复现验收的工程人员，说明 `OME 工程化模式` 如何在不改变其他 Agent 预设的前提下，把 Oh My Engine 生命周期接入 DSH Web/Desktop。

## 交付结论

- npm 包：`dsh-plugin-oh-my-engine`
- 插件版本：`0.1.6`
- Preset ID：`ome-engineer`
- DSH 显示名：`OME 工程化模式`
- OME 内核：内置来自 GitHub 固定提交 `5c6d4cc` 的可审计包（版本 `0.5.0`）
- DSH/Cordis peer 基线：`0.1.1-rc.2`
- 实机验收客户端：DSH Desktop `2.0.4`
- 首版范围：交互式 Web 与 Desktop

兼容版本明细见 [`COMPATIBILITY.md`](COMPATIBILITY.md)，npm 发布与社区投稿流程见 [`PUBLISHING.md`](PUBLISHING.md)。

## 架构边界

```text
Oh My Engine
  纯生命周期状态机、策略、阶段指导、Memory 记录
          │ public API
          ▼
dsh-plugin-oh-my-engine
  Preset + OME 工具/命令 + Session Event 重放
          │
          ▼
DSH Web/Desktop
  原生文件、Shell、权限、沙箱、取消、子 Agent、Workflow
```

OME 保持跨平台内核，不把 DSH 加入 OME 的 Agent 平台数组。插件只在选择 `ome-engineer` Preset 时注册 OME 工具、命令和 Prompt。Profile 的全局 patch 只注册 OME Session Event 类型，以便 DSH 冷启动恢复自定义事件；它不向 Standard、Code、Minimal 等其他角色注入能力。

## 生命周期与门禁

| 阶段 | 必需证据 | 门禁 |
|---|---|---|
| Define | `requirement_summary` | 缺少需求摘要时不能前进 |
| Plan | `plan_artifact` | 必须由用户执行 `/ome-approve` |
| Build | `implementation_summary` | 不能跳级 |
| Verify | `verification_command` | 必须引用当前 Session 中真实成功的非 OME 工具调用 |
| Review | `review_summary` | 必须记录审查结果或明确无发现 |
| Ship | `ship_summary` | 必须记录交付摘要 |
| Learn | `ome_finish` | Memory 成功落盘后才完成 Run |

模型不能自行批准 Plan。`ome_status` 会返回最近可作为验证证据的成功工具调用及其完整 Call ID，避免不同模型提供商隐藏协议 ID 时让模型猜测工具名称。

## 安装

使用 GitHub Release 的预构建包分别安装需要的 Profile。插件内置从 OME 原仓库已验证提交构建的包，不要求 OME 或插件发布到 npm，也不要求用户机器配置 GitHub SSH：

```powershell
dsh plugin --profile web add https://github.com/oh-my-engine/dsh-plugin-oh-my-engine/releases/download/v0.1.6/dsh-plugin-oh-my-engine-0.1.6.tgz
dsh plugin --profile desktop add https://github.com/oh-my-engine/dsh-plugin-oh-my-engine/releases/download/v0.1.6/dsh-plugin-oh-my-engine-0.1.6.tgz
dsh plugin --profile desktop exec dsh-ome preset install
```

重启对应 DSH Host，在角色选择器中选择 `OME 工程化模式`。

`dsh-ome` 安装在 Profile 自己的 `node_modules/.bin`，不会写入系统 `PATH`。请始终通过已安装插件的 Profile 执行；如果只安装 Web Profile，将示例中的 `desktop` 替换为 `web`。

### Web 端口冲突

`dsh plugin --profile ... add ...` 只负责安装依赖，不会启动 WebServer。如果启动 DSH 时出现 `EADDRINUSE 127.0.0.1:3080`，表示已有进程占用了 DSH Web 默认端口，并非 OME 插件安装失败。

```powershell
dsh plugin --profile web exec dsh-ome doctor
```

可以继续使用已运行的 `http://127.0.0.1:3080`，正常停止旧进程，或让 DSH 自动选择空闲端口：

```powershell
dsh web --port 0 --no-open
```

`dsh plugin --profile web exec dsh-ome doctor --port <port>` 可检查其他指定端口。该检查只尝试绑定并立即释放本机回环端口，不终止进程、不修改 DSH Profile。

更新 Preset：

```powershell
dsh plugin --profile desktop exec dsh-ome preset update
```

安装器只更新带有效托管标记且未被手工修改的目录，并在更新前创建完整备份。

## 使用

1. 项目未初始化时执行 `/ome-init`。
2. 让 Agent 调用 `ome_start`，完成 Define 和 Plan。
3. 检查计划后由用户执行 `/ome-approve`。
4. Agent 使用 DSH 原生工具完成 Build 和真实验证。
5. Agent 依次完成 Review、Ship、Learn，并调用 `ome_finish`。
6. 使用 `/ome-status` 查看阶段、证据、阻塞原因和下一步。

取消当前 Run：

```text
/ome-cancel acceptance stopped
```

## Session 行为

- Session Event Log 是运行期唯一事实源。
- 同项目的不同 Session 相互隔离。
- Resume 通过重放 OME 事件恢复状态。
- Fork 继承证据，在首次修改时生成新的 `runId`。
- 子 Agent 只能调用 `ome_status`，不能记录证据、推进或完成。
- 每个 Session 同时只允许一个活动 Run。

DSH `0.1.1-rc.2` 尚未提供下游事件类型的正式注册服务。插件使用独立的 `event-catalog` bootstrap，把 OME 事件加入 DSH 导出的运行时目录。升级 DSH 前必须重新验证这一兼容层。

## 验收记录

2026-09-02 在正式 DSH Desktop `2.0.4` 中完成一次真实闭环：

```text
Define → Plan → /ome-approve → Build → Verify → Review → Ship → Learn
```

验收结果：

- Plan 未批准时成功阻断进入 Build。
- 用户命令批准后成功推进。
- Verify 证据绑定真实成功的 DSH `read` 调用 ID。
- `ome_finish` 产生 `ome/run-completed`，状态为 `completed`。
- OME Memory 返回 `persisted: true`、`analyzed: true`。
- 客户端冷启动后可以恢复并展示完整会话。
- 插件测试 6/6 通过。
- OME 核心测试 115/115 通过。
- `dsh --profile desktop --dump-config` 中只有全局事件目录，没有全局 OME 工具、命令或 Prompt。

## 验证命令

插件仓库：

```powershell
npm run verify
npm pack
```

OME 核心仓库：

```powershell
npm run verify
```

桌面 Profile：

```powershell
dsh plugin --profile desktop list --depth 0
dsh --profile desktop --dump-config
```

## 升级与回滚

升级前：

1. 备份 DSH Profile 和 `ome-engineer` Preset。
2. 重新验证 Cordis patch、Tools、Commands、Session Event 和 Resume。
3. 对比 Standard、Code、Minimal 的工具、命令与 Prompt。

回滚插件包后，再显式回滚 Preset：

```powershell
dsh plugin --profile desktop add <previous-package.tgz>
dsh plugin --profile desktop exec dsh-ome preset update
```

如果需要移除：

```powershell
dsh plugin --profile desktop exec dsh-ome preset remove
dsh plugin --profile desktop remove dsh-plugin-oh-my-engine
```

从 DSH Profile 删除插件不会自动删除 Preset；删除 Preset 也不会自动卸载 Profile 插件。