oh-aireport

oh-aireport 是 AI Coding 问题上报功能包。它负责安装 /report-ai-issue 相关命令和插件，采集结构化问题字段，合并本地 metadata，并将报告写入本地文件、 Webhook 或 GitCode/Gitee 兼容的 Issue API。

项目定位

本仓是 AI Coding 工具链中的问题上报能力包，包含：

• OpenCode 插件和命令文件，可在 OpenCode 会话内触发问题上报；
• Claude Code 命令和 hook 集成；
• Python ohai-report CLI，用于创建 payload 和更新 metadata；
• local、webhook、gitcode 三类 sink；
• 架构文档、示例和单元测试。

本包既可以独立使用，也会被聚合安装器 oh-aicoding-tool 调用。

迁移期内，npm 包仍保留旧命令别名 opencode-ohai-report。

npm 包

npm 包名：oh-aireport

主命令：oh-aireport

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

oh-aicoding-tool 的 report 子命令会转发到本包。

目录结构

| 路径 | 说明 | | --- | --- | | .opencode/commands/report-ai-issue.md | OpenCode slash command | | .opencode/plugins/oh-ai-report.ts | OpenCode 插件和 report_ai_issue tool | | .claude/commands/report-ai-issue.md | Claude Code 命令 | | scripts/install-opencode-plugin.ps1 | Windows OpenCode 安装脚本 | | scripts/install-claude-plugin.ps1 | Windows Claude Code 安装脚本 | | scripts/install-opencode-plugin.sh | Unix-like OpenCode 安装脚本 | | scripts/claude_report_hook.py | Claude Code hook helper | | tools/ohai-report/ohai_report.py | Python CLI 兼容入口 | | tools/ohai-report/ohai_report/ | Python 包实现 | | tools/ohai-report/schemas/ | Issue payload schema | | tools/ohai-report/tests/ | 单元测试 | | examples/ | 示例输入和输出 | | docs/ | 架构和阶段文档 |

运行期数据默认写入 .ohai-report/，该目录已被 git 忽略。

安装插件

Windows

通过 npm 命令安装：

oh-aireport install opencode
oh-aireport install claude
oh-aireport install both

常用选项：

oh-aireport install opencode --dry-run
oh-aireport install opencode --skip-email
oh-aireport install opencode --email [email protected]
oh-aireport install claude --skip-hook

OpenCode 安装器会将插件和命令写入 %USERPROFILE%\.config\opencode\，可写入用户级 OHAI_REPORT_CLI，并可把公司邮箱保存到 %USERPROFILE%\.config\opencode\ohai-report\email.json。

Claude Code 安装器会将命令和 hook 写入 %USERPROFILE%\.claude\，可写入用户级 OHAI_REPORT_CLI，并可把公司邮箱保存到 %USERPROFILE%\.claude\ohai-report\email.json。

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

OpenCode sink 选择

OpenCode 插件默认走 Webhook 上报。可通过 OHAI_REPORT_SINK 调整行为：

| 值 | 行为 | | --- | --- | | 未设置或 webhook | 发送到 Webhook，并保留本地副本 | | local | 仅写入 .ohai-report/issues/ 本地 JSON | | gitcode | 创建 GitCode/Gitee Issue，并保留本地副本 |

Python CLI

从字段创建问题：

python tools/ohai-report/ohai_report.py create \
  --source opencode \
  --title "远程 HDC 无法连接本地设备" \
  --category "环境问题" \
  --summary "远程运行的 OpenCode 无法访问本地 HDC 设备" \
  --expected-behavior "能够给出可用的设备连接方案" \
  --actual-behavior "无法发现本地开发板" \
  --severity P2 \
  --user-description "HDC 远程服务器无法连接本地开发板" \
  --metadata auto \
  --quiet \
  --json

从 JSON 文件创建问题：

python tools/ohai-report/ohai_report.py create \
  --source opencode \
  --issue-file examples/issue-input.json \
  --metadata auto \
  --sink webhook \
  --json

更新 metadata，供后续 --metadata auto 使用：

python tools/ohai-report/ohai_report.py metadata update \
  --source opencode \
  --session-id "opencode-session-xxx" \
  --message-id "msg-xxx" \
  --opencode-subagent "build" \
  --trace-id "langfuse-trace-xxx" \
  --observation-id "obs-xxx" \
  --user-id "alice" \
  --json

当 tools/ohai-report 位于 PYTHONPATH 中时，也可以用包入口运行：

python -m ohai_report create --issue-file examples/issue-input.json --metadata auto --json

Sink

| Sink | 命令 | 输出 | | --- | --- | --- | | local | --sink local | 写入 .ohai-report/issues/*.json | | webhook | --sink webhook | POST 到 Webhook，并写入本地副本 | | gitcode | --sink gitcode | 创建 GitCode/Gitee Issue，并写入本地副本 |

Webhook URL 解析顺序：

1. --webhook-url
2. OHAI_WEBHOOK_URL 或 WEBHOOK_URL
3. tools/ohai-report/ohai_report/webhook_defaults.py

GitCode/Gitee 配置可通过 CLI 参数或环境变量提供。访问令牌建议只放在环境变量中。

| 变量 | 作用 | | --- | --- | | OHAI_GITCODE_OWNER / GITCODE_OWNER | 仓库 owner 或 namespace | | OHAI_GITCODE_REPO / GITCODE_REPO | 仓库路径 | | OHAI_GITCODE_TOKEN / GITCODE_ACCESS_TOKEN | 访问令牌 | | OHAI_GITCODE_API_BASE | API 地址，例如 https://gitee.com/api/v5 | | OHAI_GITCODE_LABELS | 逗号分隔标签 | | OHAI_WEBHOOK_URL / WEBHOOK_URL | Webhook 地址 | | OHAI_WEBHOOK_SECRET / WEBHOOK_SECRET | 可选的 X-Webhook-Secret | | OHAI_WEBHOOK_TIMEOUT / WEBHOOK_TIMEOUT | 请求超时秒数 | | OHAI_WEBHOOK_LABELS | 逗号分隔标签 |

Metadata

--metadata auto 会合并 .ohai-report/metadata.json、进程环境变量和 git 上下文。 支持的环境变量包括：

• OHAI_SESSION_ID、OPENCODE_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
• LANGFUSE_URL、LANGFUSE_TRACE_URL
• OHAI_USER_ID、LANGFUSE_USER_ID、USER_ID、USERNAME、USER
• OHAI_USER_EMAIL
• OHAI_USER_NAME
• OHAI_TEAM

OpenCode 插件会从 session event 和 tool context 中尽力刷新 metadata，使问题报告能带上 session、message、trace、observation、model 和 user 信息，同时避免把完整日志、diff 或对话内容写入 Issue 正文。

测试

在工具目录下运行 Python 单元测试：

cd tools/ohai-report
python -m unittest discover -s tests -p "test_*.py" -v

发布前建议运行：

npm run check
npm pack --dry-run

维护说明

• 新增或调整问题字段：修改 tools/ohai-report/schemas/report_issue.schema.json。
• 调整 payload：修改 tools/ohai-report/ohai_report/payload.py。
• 新增投递后端：参考 tools/ohai-report/ohai_report/sinks/ 的 sink 模式。
• OpenCode / Claude Code 特定行为应放在 .opencode/、.claude/ 或安装脚本中，避免散落到通用 Python sink 层。