oh-my-reasonix

English README

oh-my-reasonix（OMR）是 Reasonix 的项目级增强层：负责安装和升级、Prompt 组合、Profile 分发、Claude 配置兼容、质量门禁、成本报告和机器接口适配。

它不替代 Reasonix，也不复制 Reasonix 的 Session、Task、Hook、Todo 或权限状态机。OMR 把可复用的工作流约束和项目配置安全地安装到项目中，再由 Reasonix 负责实际执行。

如果你只想知道怎么开始：在一个已有 reasonix.toml 的项目中运行 omr init --project-dir .，然后用 Reasonix 打开这个项目即可。OMR 不会替你启动 Reasonix，也不会接管模型、Session 或权限。

适合谁

• 希望把一套可复用开发规则安装到多个 Reasonix 项目中的个人或团队；
• 需要 Explore、Research、Debug、Planner 等只读辅助 Profile 的项目；
• 需要安装可预览、升级可回滚、配置有 Hash 和备份证据的团队；
• 需要离线质量 Fixture、成本门禁和结构化报告的工程项目。

OMR 不是什么

OMR 不是新的 Agent Runtime、模型服务或桌面客户端。它不复制 Reasonix 的 Session、Task、Todo、Hook、权限、沙箱和后台任务状态机；这些能力仍由 Reasonix 原生提供。

OMR 解决什么问题

直接使用 Reasonix 时，团队通常还需要自己维护：

• 项目级 Prompt 和规则；
• Explore、Research、Debug、Planner 等专用 Profile；
• 安装、升级、备份、回滚和卸载；
• Claude 配置迁移；
• 质量 Fixture、重试/停滞/Review 证据；
• 成本、Token 和运行结果报告；
• Session、Hook、Task 和结构化事件的只读查询。

OMR 将这些能力统一成可审计、可回滚、可自动测试的项目层。

核心能力

安装与升级

• 项目级 init、upgrade、uninstall；
• dry-run、冲突检测、备份和回滚；
• Prompt、Profile、Manifest 和 SHA256 校验；
• 配置迁移和升级漂移诊断；
• 不修改全局 PATH、API Key 或 Reasonix 二进制。

基本用法：

# 预览安装计划（只读）
omr init --project-dir . --dry-run

# 安装
omr init --project-dir .

# 升级（保留已有配置）
omr upgrade --project-dir . --dry-run
omr upgrade --project-dir .

# 备份位置：.reasonix/omr/backups/<sha>/
# 回滚：恢复备份中的 reasonix.toml，重新运行 omr init

# 卸载
omr uninstall --project-dir . --dry-run
omr uninstall --project-dir .

Prompt 与 Profile

内置 Profile：

• omr-explore：只读探索代码、调用链和测试入口；
• omr-research：只读研究文档、API 和外部资料；
• omr-debug：只读定位错误根因；
• omr-planner：拆解阶段、风险和验收条件；
• omr-frontend：分析界面结构、交互和 UI 测试入口；
• omr-git：只读分析 Git 历史、差异和影响范围；
• omr-lsp：只读分析符号、引用和诊断入口。
• omr-grill-me：只读方案质询，发现目标歧义、隐含假设、边界条件和验收缺口。
• omr-grill-with-docs：确认后写入方案质询，将质询结果沉淀到 CONTEXT.md 和 ADR 文档。

支持：

• Profile 元数据、只读边界和工具声明；
• Category → Profile 路由；
• disabled、missing、project/builtin 状态；
• 模型和附加 Prompt 覆盖；
• omr profile list 人类和 JSON 输出。

Subagent 一览

安装 OMR 后，Reasonix 中通常可以看到以下 Subagent：

Subagent	来源	用途	写入边界
explore	Reasonix 内置	通用代码探索和事实收集	由 Reasonix 原生策略决定
research	Reasonix 内置	通用资料、API 和外部信息研究	由 Reasonix 原生策略决定
review	Reasonix 内置	代码 Review 和问题发现	只读
security-review	Reasonix 内置	安全风险审查	只读
omr-explore	OMR 项目级	只读探索代码路径、调用链和测试入口	只读
omr-research	OMR 项目级	只读研究文档、API 和外部上下文	只读
omr-debug	OMR 项目级	只读定位失败根因和最小修复方向	只读
omr-planner	OMR 项目级	拆解执行阶段、风险和验收条件	只读
omr-frontend	OMR 项目级	分析 UI 结构、交互和前端测试入口	只读
omr-git	OMR 项目级	分析 Git 历史、差异和影响范围	只读
omr-lsp	OMR 项目级	分析符号、引用和语言服务诊断	只读
omr-grill-me	OMR 项目级	方案质询，发现目标歧义、隐含假设、边界条件和验收缺口	只读
omr-grill-with-docs	OMR 项目级	确认后将已确认事实写入 CONTEXT.md 和 ADR	确认后写入

实际可用列表以当前 Reasonix 版本和项目配置为准，可使用以下命令查看：

reasonix subagent list
omr profile list --project-dir . --json

OMR 不会替换 Reasonix 的内置 Subagent；项目可以通过 Category routing、disabled 配置和模型覆盖来调整 OMR Subagent 的使用方式。

OMR Profile 的特色

OMR Profile 的优势不在于替代 Reasonix 的运行时，而在于提供更强的项目级工程治理：

• 工作流更具体：不仅定义角色，还规定探索顺序、证据格式、风险记录和验收输出；
• 随项目分发：Prompt、Profile、规则和配置可以一起提交到 Git，团队成员获得一致的工作方式；
• 生命周期可审计：支持 dry-run、冲突检测、Manifest、SHA256、备份、回滚和卸载；
• 证据纪律更强：要求记录文件证据、测试结果、Review 结论、失败原因和未决问题；
• 项目级路由：可以按任务类别选择 Profile，并覆盖模型、Prompt 和只读声明；
• 方案质询：omr-grill-me 在开发前暴露歧义、假设、边界和验收缺口；
• 结果可验证：通过离线 Fixture、质量基准、成本门禁和 Native/OMR 对照报告验证工作流。

因此，Reasonix 原生 Profile 更强在运行时工具、权限和状态机；OMR Profile 更强在项目规范、团队复用、证据纪律和可审计交付。

Claude 兼容层

支持只读导入：

• .claude/rules
• .claude/skills
• .claude/agents
• .claude/commands
• .claude/mcp.json
• .claude/hooks

所有导入支持 dry-run、冲突报告、敏感信息保护和失败回滚。Claude Hook 会转换为策略提示，并明确标注运行时语义无法等价保留。

质量与成本

• 离线 Fixture 和确定性 replay；
• Runtime、Native/OMR 配对报告；
• 失败分类、重试、停滞、Review 阻断和证据缺失；
• Token、成本、缓存和 readiness 指标；
• JSON Schema、快照和迁移校验；
• 预期失败 Fixture 与正常通过率分离统计。

Reasonix 机器接口

在 Reasonix 提供公开机器接口后，OMR 可只读查询：

• Session list/status/show/recovery；
• Hook list/status；
• Task list/show；
• run --events-jsonl 结构化事件流。

OMR 不读取 Reasonix 私有目录或数据库，不从人类可读 stdout 猜测 Session 状态。

快速开始

前置条件

• Go 1.23+（使用源码或 go run 安装时）；
• 已安装并完成认证的 Reasonix；
• 项目根目录存在 reasonix.toml；
• Reasonix v1.17.20 或更高版本（可用 omr version --json 检查）。

一分钟安装

已有 Reasonix 项目（含 reasonix.toml）：

# 安装 OMR
go run github.com/mchenziyi/oh-my-reasonix/cmd/omr@latest init --project-dir .

# 验证安装
go run github.com/mchenziyi/oh-my-reasonix/cmd/omr@latest doctor --project-dir .

# 查看 Profile
go run github.com/mchenziyi/oh-my-reasonix/cmd/omr@latest profile list --project-dir .

安装会在项目内生成或更新：

reasonix.toml                         # 增加 OMR Prompt 引用
.reasonix/omr/generated/              # 合并后的系统 Prompt
.reasonix/skills/                     # OMR Profile
.reasonix/omr/manifest.lock.yaml      # 资产和 Hash 清单
.reasonix/omr/backups/                 # 升级前备份

首次运行建议：

omr doctor --project-dir .
omr profile list --project-dir . --json
reasonix subagent list --dir .

然后在 Reasonix 客户端中提出普通开发任务。复杂任务可以先明确要求使用 omr-grill-me 进行方案质询，再进入规划和实现。

从源码构建：

git clone https://github.com/mchenziyi/oh-my-reasonix.git
cd oh-my-reasonix
go build -o omr ./cmd/omr
./omr init --project-dir /path/to/your/project --dry-run
./omr init --project-dir /path/to/your/project

init/upgrade/doctor/profile/run 示例

项目中已有 reasonix.toml 时：

# 预览，不写文件
go run ./cmd/omr init --project-dir . --dry-run

# 安装
go run ./cmd/omr init --project-dir .

# 验证
go run ./cmd/omr doctor --project-dir .
go run ./cmd/omr doctor --project-dir . --json

# 查看配置和 Profile
go run ./cmd/omr config validate --project-dir .
go run ./cmd/omr profile list --project-dir .
go run ./cmd/omr profile list --project-dir . --json

# 执行任务并记录结构化事件流
go run ./cmd/omr run --project-dir . --events-jsonl /tmp/events.jsonl --json "查询项目状态"

安装后，Reasonix 会读取生成的 OMR Prompt 和 Profile。OMR 不会自动启动或接管 Reasonix 客户端。

让 Reasonix 自己安装 OMR

将 INSTALL_PROMPT.md 交给正在运行的 Reasonix。它会读取安装文档，先执行 dry-run，再在确认后安装。

Raw URL：

https://raw.githubusercontent.com/mchenziyi/oh-my-reasonix/main/docs/INSTALL_PROMPT.md

完整安装说明见 docs/INSTALL.md。

人工体验与 A/B 对照

想比较“安装 OMR”和“只用原生 Reasonix”的实际差异，请按OMR 人工体验与 A/B 对照测试执行。也可以分别使用仅体验 OMR 的人工测试清单和不安装 OMR 的 Native 基线清单。

常用命令

# 注释质量检查
omr comment-check --project-dir . --json
omr comment-check --project-dir . --path internal/foo.go
omr comment-check --project-dir . --allow-tags "TODO(admin),TODO(future)"

# `--path` 相对路径按 `--project-dir` 解析；默认只允许扫描项目根目录内的文件，
# 文件和中间目录符号链接越界也会被拒绝。

# Comment Checker Hook（默认关闭）
omr hook comment-check status --project-dir . --json
omr hook comment-check enable --project-dir . --dry-run
omr hook comment-check enable --project-dir .
omr hook comment-check disable --project-dir . --dry-run
omr hook comment-check disable --project-dir .

# 配置
omr config validate --project-dir .
omr config validate --project-dir . --json
omr config schema --project-dir .

# Profile
omr profile list --project-dir . --json

# Claude 导入
omr claude import --project-dir . --dry-run
omr claude import --project-dir .
omr claude commands --project-dir . --json

# Session / Hook / Task 只读查询
omr session list --project-dir . --json
omr session status <branch-id> --project-dir . --json
omr session recovery <branch-id> --project-dir . --json
omr hook doctor --project-dir . --json
omr hook comment-check status --project-dir . --json
omr task list --project-dir . --json
omr task show <task-id> --project-dir . --json

# 结构化事件流
omr run --project-dir . --events-jsonl /tmp/reasonix-events.jsonl --json "执行指定任务"

如果 Reasonix 不在 PATH，可显式指定：

omr doctor --project-dir . --binary /Applications/Reasonix.app/Contents/MacOS/reasonix

配置示例

配置文件位于项目的 .reasonix/omr/config.toml：

[runtime]
model = "deepseek-v4-flash"
max_steps = 20
timeout = "2m"
concurrency = 1

[agent.omr-research]
model = "deepseek-v4-flash"
prompt_file = "prompts/research.md"
read_only = true

[routing]
explore = "omr-explore"
research = "omr-research"
frontend = "omr-frontend"

[profiles]
disabled = "omr-debug"

# 可选；默认 disabled。OMR 只保存环境变量名称，不保存值。
[mcp.docs]
transport = "stdio"
command = "mcp-docs"
args = ["--mode", "read-only"]
capabilities = ["docs"]
enabled = false
env = ["DOCS_API_KEY"]

配置也支持 JSONC 和 TOML → JSONC 迁移：

omr config migrate --project-dir .
omr config schema --project-dir .

项目配置发现顺序为 .reasonix/omr/config.jsonc、config.json、config.toml；找到第一个后停止，不跨文件合并。

OMR 会拒绝绝对 Prompt 路径、路径越界、未知配置字段、非法 Profile ID 和指向 disabled Profile 的路由。

可选 Web/Docs MCP

OMR 支持 stdio、Streamable HTTP（http）和 legacy SSE（sse）配置的兼容性诊断，并识别 docs、web、code-search、version-filter 能力标签；其他标签报告为 unknown。MCP 默认不启用；启用后，config validate 和 doctor 会报告命令是否在 PATH、所需环境变量名称、网络/本地进程风险以及是否需要用户确认，但不会输出命令参数、远端 URL、凭证值或不必要的绝对路径。

OMR 不启动、下载或授权 MCP Server，也不复制 Reasonix 的 MCP 运行时。要让工具真正进入会话，仍需使用 Reasonix 原生命令注册相同 Server，例如：

reasonix mcp add docs mcp-docs --mode read-only
reasonix mcp add web --http https://example.com/mcp
reasonix mcp list

Reasonix 会负责项目配置发现和首次确认。omr-research 只在运行时实际暴露对应工具且用户已确认时使用；不可用时会降级为普通只读研究并报告限制。网络访问、第三方成本和凭证管理由用户负责。

质量验证

go test ./...
go vet ./...
go build ./...
go run ./cmd/omr benchmark quality --replay --min-qualified-rate 1
# CI/A-B 测试可固定报告标识，便于重跑和对照
go run ./cmd/omr benchmark quality --replay --run-id nightly-20260730

质量 Fixture 使用 JSON（也是 YAML 1.2 的有效子集），不依赖真实 Provider。Native/OMR 对照没有配对证据时会明确标记 unavailable，不会宣称 OMR 优于 Native。

Mnemosyne 本地记忆

Mnemosyne 是 OMR 的本地长期工程记忆层。先在临时或目标项目初始化受保护的 Store，再按需启动 loopback 管理页：

omr memory init --project-dir /tmp/omr-memory-demo --scope project
omr memory web serve --project-dir /tmp/omr-memory-demo --now 2026-08-14T00:00:00Z

终端会输出仅绑定 127.0.0.1 的 URL，可在浏览器打开 /manager 查看记忆并执行 pin/unpin/freeze/archive；unfreeze 还必须填写非空 basis_refs 并二次确认。页面写操作始终复用既有治理 API，失败时不做乐观更新，成功后重新读取 FactStore。memory init 只创建 Store 目录，不伪造任何 Memory、Usage、Outcome 或 Generation Fact。

真实 Reasonix Desktop 回执、跨项目迁移和浏览器验收仍需在临时项目中单独联调；OMR 不读取 Reasonix 私有状态，也不把管理页面当作新的事实源。

安全与隐私边界

• 默认只写项目目录；
• dry-run、冲突和升级失败不会静默覆盖用户文件；
• 不读取 ~/.reasonix/projects、私有事件文件、数据库或内部锁；
• 不输出 API Key、Prompt 原文、Tool 参数/结果、绝对路径、PID 或 hostname；
• Claude MCP/Hook 导入会做兼容性和风险提示；
• 真实客户端验证需要用户明确授权。

开发

需要 Go 1.23 或更高版本：

go test ./...
go vet ./...
go build ./...
go run ./cmd/omr version

代码改动应同时运行 gofmt 和 git diff --check。测试使用临时目录，不依赖用户真实项目。

当前状态与路线

已完成 OMR-T01～T10、T11（Grill Me）、T12（Grill with Docs）、T13（Comment Checker）、T14（Comment Checker 运行时 Hook，已通过 Reasonix v1.18 桌面端验证），以及 INT-01～INT-06 全部联调。

后续本地增强（LP-01～LP-06）已全部交付：

• v2.0.4（LP-01）：Evolution 数据保留、压缩与修复——evolve doctor 只读统计、evolve prune、evolve repair，删除前带 Hash 快照且失败自动恢复，dry-run 零写入、幂等、fail closed。
• v2.0.5（LP-02）：观测报告增强——按 Proposal/TaskClass 聚合 before/after、成功率、Token、耗时与观察期进度；evolve history <id> 详细统计；报告只输出脱敏聚合，不宣称“提升/显著改善”。
• v2.0.6（LP-03）：Profile/Prompt 效果基准——benchmark profile --replay/--matrix 与 6 类离线 Fixture，指标为过程指标，明确声明“非模型质量证明”。
• v2.0.7（LP-04）：Hook 审计日志——.reasonix/omr/audit/ 脱敏日志、hook comment-check logs/--clear、条目/字节上限淘汰、日志不可用 fail closed。
• v2.0.8（LP-05）：经验包签名——Ed25519 本地签名（export --sign --key）、import --require-signature --trusted-key，篡改/密钥不匹配/未知字段 fail closed，导入保持 pending。
• v2.0.9（LP-06）：文档单一事实源——历史计划标注 Archived、能力矩阵、链接检查与命令示例 Smoke（tests/docs_check.sh）。

当前可用能力的完整划分见 当前可用能力矩阵。剩余事项只涉及 Reasonix 官方接口：

• Tmux/桌面实时面板：记录为 Reasonix 官方适配事项，OMR 不复制 UI/后台状态机；
• Subagent 父子任务树与 Desktop 映射：等待 Reasonix 提供稳定的父子关联事件和机器接口（BLOCKED，未猜测、未伪造）。

v1.17.20 机器接口兼容状态

OMR 基于 Reasonix v1.17.20 的公开机器接口设计，当前兼容状态：

omr version --json 会输出 minimum_reasonix_version 和 compatible 字段；当前最低支持版本为 Reasonix v1.17.20。

接口	状态	说明
session list	✅ 通过	只读查询 Session 列表
session status	✅ 通过	查询指定 Session 状态
session show	✅ 通过	查看 Session 详情
session recovery	✅ 通过	Session 恢复信息
session resume	✅ 通过	恢复 Session 连接
session export	✅ 通过	导出 Session 事件
hook list	✅ 通过	查询 Hook 列表
hook status	✅ 通过	查询 Hook 状态
hook doctor	✅ 通过	Hook 诊断（JSON/人类输出）
task list	✅ 通过	查询 Task 列表
task show	✅ 通过	查看 Task 详情
run --events-jsonl	✅ 通过	结构化事件流（v1 schema）
event schema v1	✅ 通过	事件格式验证
旧格式兼容	✅ 通过	向后兼容旧事件格式
非零退出事件落盘	✅ 通过	失败事件写入日志
事件脱敏	✅ 通过	敏感信息自动过滤
run_done / token 汇总	✅ 通过	运行完成和 Token 统计
INT-06 真实客户端	✅ 通过	Reasonix v1.18.0 真实 Session、Hook、Task、Recovery 和事件流验证

注意：自动化回归由 Mock 和本地 CLI 覆盖；INT-06 已额外使用 Reasonix v1.18.0 真实客户端验证。空 Task/Recovery/Hook 列表表示当前项目没有对应状态，不代表接口失败。

常见错误与排查

reasonix.toml not found

OMR init 要求项目根目录已存在 reasonix.toml。在空项目中新建该文件即可：

touch /path/to/project/reasonix.toml
omr init --project-dir /path/to/project

No OMR config found (project not yet configured)

这是正常状态，不是错误。OMR 项目配置（.reasonix/omr/config.toml）是可选的。如需自定义 Profile 路由、模型或 MCP 配置，可手动创建或使用 omr config schema 生成 JSON Schema 后填写。

OMR manifest not found

Profile 和安装追踪依赖 manifest。运行 omr init 或 omr upgrade 后 manifest 会自动生成。若已安装但仍缺失，重新运行 omr upgrade --project-dir .。

category "x" routes to disabled Profile "y"

某个路由类别指向了已被禁用的 Profile。编辑 .reasonix/omr/config.toml 中的 [profiles] disabled 或 [routing] 配置。

omr: command not found

使用 go run 方式，或 go build -o omr ./cmd/omr && sudo mv omr /usr/local/bin/。详细的安装方式见 docs/INSTALL.md。

Reasonix 二进制不在 PATH

显式指定 --binary 参数：

omr doctor --project-dir . --binary /Applications/Reasonix.app/Contents/MacOS/reasonix
omr session list --project-dir . --binary /path/to/reasonix

许可证

MIT