内容
# 我的智能代理（oma）
> [中文版](README.zh.md)
适用于 AI 编程代理的跨代理治理层。统一审计日志、策略执行和上下文反馈，适用于 Claude Code、Gemini CLI、OpenCode、Codex CLI 和 Aider。
---
## 适用于人类的说明
发布到 npm 后，将以下内容复制并粘贴到您的 AI 编程代理中：
```bash
npm install -g oh-my-agent && oma audit install && oma policy init && oma doctor
```
如果 npm 不可用，请从 GitHub 克隆并构建：
```bash
git clone https://github.com/Dasooul03/oh-my-agent.git && cd oh-my-agent && go build -o oma.exe . && oma audit install && oma policy init && oma doctor
```
## 适用于 AI 代理
> 如果您是 AI 编程代理，正在读取此文件，以下是您需要了解的内容。
- **审计**：您调用的每个工具都会记录到 `~/.oma/audit/`。此日志在所有代理之间共享 - 其他代理可以看到您做了什么。
- **策略**：某些命令可能会被策略规则阻止。如果 `rm -rf /` 被拒绝，那是 oma 的策略执行。不要重试被阻止的命令。
- **上下文简介**：在会话开始时，您的钩子可以注入其他代理最近活动的 Markdown 摘要。阅读它以了解其他代理已经做了什么。
- **MCP 工具**：当 `oma mcp serve` 运行时，您可以查询 `oma_audit_recent`、`oma_audit_search`、`oma_who_changed`、`oma_policy_status` 和 `oma_handoff` 以了解其他代理的工作。
## 功能
- **统一审计** - 所有代理的每个工具调用都记录到 `~/.oma/audit/YYYY-MM-DD.jsonl`
- **策略执行** - 拒绝/询问规则阻止危险命令（`rm -rf`、`git push --force` 等）跨所有代理
- **上下文反馈** - 在会话开始时注入最近活动的摘要，以便每个代理都知道其他代理已经做了什么
- **MCP 集成** - 通过 MCP 向代理公开审计和策略工具
- **Aider ingestion** - 将 `~/.aider.chat.history.md` 解析到统一审计日志（aider 没有本机钩子）
- **零依赖** - 仅使用 Go 标准库构建，无需 `go mod download`，无需供应链风险
## 支持的代理
| 代理 | 二进制文件 | 检测 | 钩子 | 事件类型 |
| --- | --- | --- | --- | --- |
| Claude Code | `claude` | PATH + 标准安装路径 | PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, PermissionRequest | `tool.before`, `tool.after`, `session.start`, `prompt.user` |
| Gemini CLI | `gemini` | PATH + 标准安装路径 | BeforeTool, AfterTool, SessionStart, UserPromptSubmit | `tool.before`, `tool.after`, `session.start` |
| OpenCode | `opencode` | PATH + npm 全局 + 桌面应用程序 | PreToolUse, PostToolUse, `session.start` | `tool.before`, `tool.after` |
| Codex CLI | `codex` | PATH + 官方安装路径 | PreToolUse, SessionStart (bash-only, [#16732](https://github.com/openai/codex/issues/16732)) | `tool.before`, `session.start` |
| Aider | `aider` | PATH + pip 安装路径 | 无（仅通过 `ingest-aider` 读取） | `tool.before`（从聊天历史记录解析） |
## 快速入门
```bash
# 构建
go build -o oma.exe .
# 检查检测到的内容
oma doctor
# 为所有检测到的代理安装审计钩子
oma audit install
# 生成默认策略
oma policy init
```
## 命令
### `oma doctor`
自我诊断：代理检测、钩子配置状态、审计目录和策略文件。
```
$ oma doctor
--- 代理检测 ---
[claude] Claude Code v2.1.169
路径： /usr/local/bin/claude.cmd
钩子： ~/.claude/settings.json （存在）
[opencode] OpenCode v1.17.13
路径： %LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe
钩子： ~/.config/opencode/hook/hooks.yaml （存在）
[codex] Codex CLI v0.130.0-alpha.5
路径： %LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe
⚠ 仅限 bash 钩子（#16732）
钩子： ~/.codex/config.toml （存在）
```
### `oma audit`
```bash
# 为检测到的代理安装钩子（写入 settings.json、config.toml、hooks.yaml）
oma audit install [--agents claude,opencode]
# 删除钩子
oma audit uninstall [--agents claude,opencode]
# 查看最近的审计日志
oma audit log [-n 20] [--agent claude] [--since 24h]
# 使用正则表达式搜索审计日志
oma audit grep <pattern>
# 重放会话时间线
oma audit replay <session-id>
# 将 aider 聊天历史记录导入审计日志
oma audit ingest-aider [--history ~/.aider.chat.history.md]
```
### `oma policy`
```bash
# 生成 ~/.oma/policy.yaml 并包含默认值
oma policy init
# 检查事件（由钩子调用；exit 0 = 允许，2 = 阻止）
echo '<json>' | oma policy check <agent> <event>
# 安装阻止钩子（替换仅审计钩子）
oma policy install [--agents claude,opencode]
```
#### 默认策略
```yaml
deny:
- tool: bash
pattern: "rm -rf"
reason: "拒绝 rm -rf"
- tool: bash
pattern: "git push --force"
reason: "拒绝强制推送"
ask:
- tool: edit
glob: "**/.env*"
reason: "编辑 .env 文件前请询问"
- tool: write
glob: "**/.env*"
reason: "写入 .env 文件前请询问"
```
### `oma context`
在每个代理的会话开始钩子中注入最近审计活动的 Markdown 摘要，以便每个代理都知道其他代理已经做了什么。
```bash
# 生成简介（默认：最近 24 小时）
oma context brief [--cwd DIR] [--since 24h]
# 安装 SessionStart 上下文钩子
oma context install [--agents claude,opencode]
# 删除上下文钩子
oma context uninstall [--agents claude,opencode]
```
### `oma mcp`
通过 [模型上下文协议](https://modelcontextprotocol.io) 向代理公开审计和策略。
```bash
# 启动 MCP 服务器（stdio JSON-RPC）
oma mcp serve
# 安装为代理 MCP 服务器
oma mcp install [--agents claude,opencode]
# 删除 MCP 配置
oma mcp uninstall
```
#### MCP 工具
| 工具 | 描述 |
| --- | --- |
| `oma_audit_recent` | 最近的审计事件，可选代理/时间筛选 |
| `oma_audit_search` | 跨审计日志的正则表达式搜索 |
| `oma_who_changed` | 查找哪个代理最后修改了文件 |
| `oma_policy_status` | 当前策略规则和最近的阻止 |
| `oma_handoff` | 会话的跨代理交接摘要 |
### `oma hook`（内部）
由代理钩子调用。将钩子事件输送到审计日志。
```bash
echo '<json>' | oma hook ingest claude tool.before
```
## 架构
```
┌─────────────────────┐
│ Claude / Gemini │
│ OpenCode / Codex │
│ ⋮ │
└──────┬──────┬───────┘
│ │
PreToolUse │ │ PostToolUse
SessionStart │ │
▼ ▼
┌──────────────────┐
│ oma shim (.ps1) │
│ 通过 stdin 输送 │
└────────┬─────────┘
│
┌────────▼─────────┐
│ oma 导入 │
│ 解码 → 审计 │
└────────┬─────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ 审计日志 │ │ 策略 │ │ MCP 服务器 │
│ ~/.oma/ │ │ 检查/ │ │ （5 个工具） │
│ 审计/* │ │ 阻止 │ │ │
└────────────┘ └────────────┘ └────────────┘
```
所有事件都流经 **解码器** 层（每个代理的规范化），然后到 **接收器**（仅追加 JSONL），可选 **策略** 检查可以设置 `blocked` 标志并退出 2。
## 配置
### 策略：`~/.oma/policy.yaml`
```yaml
deny:
- tool: bash
pattern: "rm -rf"
reason: "拒绝 rm -rf"
ask:
- tool: edit
glob: "**/.env*"
reason: "编辑 .env 文件前请询问"
```
### 代理钩子文件
| 代理 | 配置文件 | 格式 |
| --- | --- | --- |
| Claude Code | `~/.claude/settings.json` | JSON |
| OpenCode | `~/.config/opencode/hook/hooks.yaml` | YAML |
| Codex CLI | `~/.codex/config.toml` | TOML |
| Gemini CLI | `~/.gemini/settings.json` | JSON |
### 审计日志：`~/.oma/audit/YYYY-MM-DD.jsonl`
```
{"ts":"2026-07-03T14:54:54Z","agent":"claude","event":"tool.before","session_id":"...","tool":{"name":"Bash","input":{"command":"ls -la"},"blocked":false}}
{"ts":"2026-07-03T14:54:54Z","agent":"claude","event":"tool.before","session_id":"...","tool":{"name":"Bash","input":{"command":"rm -rf /"},"blocked":true,"reason":"拒绝 rm -rf"}}
```
## 零依赖
完全使用 **Go 标准库** 构建 - 无需 `go mod download`，无需依赖膨胀，无需供应链风险。单个二进制文件构建，使用 `go build` 即可正常工作。
| 组件 | 功能 |
| --- | --- |
| `internal/cli/cli.go` | 命令行路由器 - 子命令调度，帮助输出 |
| `internal/mcp/` | MCP 服务器 - stdio JSON-RPC 协议实现 |
| `internal/yaml/` | YAML 子集解析器 - 读取策略文件和 opencode 钩子配置 |
| `internal/toml/` | TOML 子集解析器 + 序列化器 - 读取/写入 codex 配置 |
## 代理检测
`oma` 通过以下方式检测代理：
1. **PATH 查找** 通过 `exec.LookPath`
2. **备用路径** 从 `catalog.json` （用户可配置）
3. **标准平台路径** - 内置每个代理的已知安装位置搜索（npm 全局前缀，`%LOCALAPPDATA%`，`~/.codex/.sandbox-bin` 等）
## 限制
- **Codex CLI**：钩子支持仅限于 bash 命令 ([#16732](https://github.com/openai/codex/issues/16732))。像 `apply_patch` 和 `edit` 这样的工具无法被钩子捕获 - 除非您还通过受监控的工具输送它们的调用，否则它们对 `oma` 来说是不可见的。
- **Aider**：没有钩子系统。唯一的集成路径是通过 `oma audit ingest-aider` 导入 `~/.aider.chat.history.md`，它提供历史可见性但不是实时拦截（aider 没有策略阻止）。
