oh-aireport

oh-aireport 是 AI 编码问题反馈能力包，用于给 OpenCode、Claude Code 和 Codex 安装问题上报入口，并提供 Python CLI 生成结构化 issue payload。

当前 npm 版本：0.1.4

能做什么

• 为 OpenCode 安装 slash command、oh-ai-report 插件、argv helper，并自动注册到 OpenCode 全局配置。
• 为 Claude Code 安装 /report-ai-issue 命令和可选 hook，并可合并 settings.json。
• 为 Codex 安装 oh-ai-report skill、PowerShell wrapper 和 sandbox-visible runtime fallback。
• 保存公司邮箱作为提交人标识；默认只接受 @huawei.com / @h-partners.com，可用 OHAI_COMPANY_EMAIL_DOMAINS 扩展域名白名单。
• 从 CLI 或 JSON 文件生成结构化 issue payload。
• 支持 local、webhook、gitcode 三类 sink。
• 可被聚合安装器 oh-aicoding-tool report ... 调用。

快速使用

npx oh-aireport@latest install opencode --email [email protected]
npx oh-aireport@latest install claude --email [email protected]
npx oh-aireport@latest install codex --email [email protected]
npx oh-aireport@latest install both --email [email protected]
npx oh-aireport@latest install all --email [email protected]

目标含义：

• opencode：安装 OpenCode 命令、插件、插件 helper，并注册 ./plugins/oh-ai-report.ts。
• claude：安装 Claude Code 命令；默认同时安装 hook，可用 --skip-hook 跳过。
• codex：安装 Codex skill、wrapper 和 skill 内 runtime fallback；支持 CODEX_HOME。
• both：安装 OpenCode + Claude Code。
• all：安装 OpenCode + Claude Code + Codex。

跳过邮箱写入：

npx oh-aireport@latest install opencode --skip-email

预览安装动作：

npx oh-aireport@latest install opencode --dry-run

命令

oh-aireport install opencode [--email [email protected]|[email protected]] [--skip-email]
oh-aireport install claude [--email [email protected]|[email protected]] [--skip-email]
oh-aireport install codex [--email [email protected]|[email protected]] [--skip-email]
oh-aireport install both [--email [email protected]|[email protected]] [--skip-email]
oh-aireport install all [--email [email protected]|[email protected]] [--skip-email]
oh-aireport create [...ohai-report args]
oh-aireport metadata [...ohai-report args]

兼容入口：

opencode-ohai-report

安装选项

| 选项 | 说明 | | --- | --- | | --email <email> | 非交互式写入公司邮箱；默认要求 @huawei.com 或 @h-partners.com | | --skip-email | 不询问、不写入邮箱配置 | | --dry-run | 只打印动作，不修改文件 | | --skip-env | 不写入用户级 OHAI_REPORT_CLI 环境变量 | | --plugin-only | OpenCode only：只复制插件，跳过命令 | | --skip-hook | Claude only：跳过 hook 和 settings 合并 |

交互式安装会显示当前保存的公司邮箱，默认保留不改。非交互安装可通过 --email 或环境变量 OHAI_INSTALL_USER_EMAIL 更新邮箱；也可用 --skip-email 明确跳过。Windows 支持 OpenCode、Claude Code、Codex 安装；Linux/macOS 当前支持 OpenCode 安装脚本。

OpenCode 安装内容

OpenCode 安装会写入：

• ~/.config/opencode/commands/report-ai-issue.md
• ~/.config/opencode/plugins/oh-ai-report.ts
• ~/.config/opencode/plugins/oh-ai-report-argv.mjs
• ~/.config/opencode/ohai-report/email.json
• ~/.config/opencode/opencode.json 中的 plugin 列表
• 用户级 OHAI_REPORT_CLI

运行时会复制到：

~/.config/ohai-report/runtime

这样 OpenCode 插件可以使用稳定路径，不依赖临时 npx 缓存。

如果需要覆盖全局邮箱，可在项目内写入：

<project>/.ohai-report/user_email.json

内容格式：

{"user_email":"[email protected]"}

Claude Code 安装内容

Claude Code 安装会写入：

• ~/.claude/commands/report-ai-issue.md
• ~/.claude/ohai-report/email.json
• ~/.claude/hooks/ohai-report-hook.py
• ~/.claude/settings.json 中的 hook 配置
• 用户级 OHAI_REPORT_CLI

使用 --skip-hook 时只安装命令和运行时，不复制 hook、不合并 settings.json。Claude 安装会优先读取 Claude 自己的邮箱配置；没有时会复用 OpenCode 已保存的邮箱。

Codex 安装内容

Codex 安装会写入：

• ~/.codex/skills/oh-ai-report/SKILL.md
• ~/.codex/skills/oh-ai-report/codex-report-issue.ps1
• ~/.codex/skills/oh-ai-report/runtime/tools/ohai-report/
• ~/.codex/ohai-report/email.json
• 用户级 OHAI_REPORT_CLI
• 用户级 OHAI_REPORT_CODEX_SCRIPT

Codex 入口是 skill，不是 /report-ai-issue slash command。安装器会优先使用 CODEX_HOME，未设置时写入 ~/.codex。Codex skill 内还会保留一份 runtime fallback，便于在 sandbox 中调用。

安装后请完整退出并重启 OpenCode、Claude Code 或 Codex，让命令、插件、hook、skill 和用户级环境变量生效。

创建 issue payload

从字段创建：

oh-aireport create \
  --source opencode \
  --title "远程 HDC 无法连接本地设备" \
  --category "环境问题" \
  --summary "远程运行的 OpenCode 无法访问本地 HDC 设备" \
  --expected-behavior "可以给出可用的设备连接方案" \
  --actual-behavior "无法发现本地开发板" \
  --severity P2 \
  --metadata auto \
  --json

从 JSON 文件创建：

oh-aireport create \
  --source opencode \
  --issue-file examples/issue-input.json \
  --metadata auto \
  --sink webhook \
  --json

更新 metadata：

oh-aireport metadata update \
  --source opencode \
  --session-id "opencode-session-xxx" \
  --message-id "msg-xxx" \
  --trace-id "langfuse-trace-xxx" \
  --observation-id "obs-xxx" \
  --user-id "h00613222" \
  --json

Sink

| Sink | 行为 | | --- | --- | | local | 写入 .ohai-report/issues/*.json | | webhook | POST 到 webhook，并保留本地副本 | | gitcode | 创建 GitCode/Gitee Issue，并保留本地副本 |

Webhook URL 解析顺序：

1. --webhook-url
2. OHAI_WEBHOOK_URL 或 WEBHOOK_URL
3. 内置默认配置

常用环境变量：

| 变量 | 作用 | | --- | --- | | OHAI_WEBHOOK_URL / WEBHOOK_URL | Webhook 地址 | | OHAI_WEBHOOK_SECRET / WEBHOOK_SECRET | 可选 webhook secret | | OHAI_WEBHOOK_TIMEOUT / WEBHOOK_TIMEOUT | Webhook 超时秒数 | | OHAI_WEBHOOK_LABELS | 逗号分隔的 webhook labels | | OHAI_GITCODE_OWNER / GITCODE_OWNER | GitCode/Gitee owner | | OHAI_GITCODE_REPO / GITCODE_REPO | 仓库路径 | | OHAI_GITCODE_TOKEN / GITCODE_ACCESS_TOKEN | 访问令牌 | | OHAI_GITCODE_API_BASE | GitCode API 根地址 | | OHAI_GITCODE_LABELS | 逗号分隔的 GitCode labels | | OHAI_GITCODE_LABEL_MAINTAINER / OHAI_GITCODE_MAINTAINER | 允许缺失标签时自动创建 | | OHAI_GITCODE_NEW_LABEL_COLOR | 自动创建标签时使用的颜色 | | OHAI_USER_EMAIL | 提交人邮箱 |

Metadata 来源

--metadata auto 会读取 .ohai-report/metadata.json、环境变量和 git context。常用环境变量包括：

• OHAI_SESSION_ID
• OPENCODE_SESSION_ID
• CODEX_SESSION_ID
• LANGFUSE_SESSION_ID
• LANGFUSE_TRACE_ID / TRACE_ID
• LANGFUSE_OBSERVATION_ID / OHAI_OBSERVATION_ID / OBSERVATION_ID
• OPENCODE_MESSAGE_ID / OHAI_MESSAGE_ID
• OHAI_OPENCODE_SUBAGENT / OPENCODE_SUBAGENT
• OPENCODE_MODEL / CODEX_MODEL / OHAI_MODEL
• LANGFUSE_URL / LANGFUSE_TRACE_URL
• OHAI_USER_ID / OHAI_EMPLOYEE_ID / OPENCODE_EMPLOYEE_ID / LANGFUSE_USER_ID / USER_ID
• OHAI_USER_EMAIL / USER_EMAIL / GIT_AUTHOR_EMAIL
• OHAI_USER_NAME
• OHAI_TEAM

当已有 trace_id 但未配置 langfuse_url 时，如果设置了 LANGFUSE_BASE_URL 或 LANGFUSE_HOST，并提供 LANGFUSE_PROJECT_ID，CLI 会自动拼接 trace 链接。

开发与验证

npm run check
npm test
npm pack --dry-run
npm run self:verify -- --targets=opencode --email [email protected]
npm run self:verify -- --targets=codex --email [email protected]

目录说明：

| 路径 | 说明 | | --- | --- | | bin/cli.js | npm 命令入口 | | .opencode/ | OpenCode 命令和插件模板 | | .claude/ | Claude Code 命令模板 | | .codex/ | Codex skill 模板 | | scripts/ | 安装脚本 | | tools/ohai-report/ohai_report/ | Python CLI 实现 | | tools/ohai-report/schemas/ | issue payload schema | | docs/ | 架构和说明文档 |