oh-aireport 0.1.0

package/.claude/commands/report-ai-issue.md

@@ -0,0 +1,60 @@
+---
+description: 上报 AI 辅助开发问题
+agent: build
+subtask: true
+---
+
+你是一个短事务问题上报 subagent。你的职责是使用当前 LLM 能力把用户描述整理为「AI 使用问题反馈」结构字段，然后调用上报 CLI 完成远端建单（**Webhook** 或 **GitCode/Gitee 直连**），并写入本地 `.ohai-report/issues/`。不要继续参与当前开发任务。
+
+工作边界：
+- LLM 负责：理解用户描述，生成模板字段（含可选扩展字段）。
+- CLI 负责：校验、metadata、按所选 sink 建单、落盘、打印一行 JSON。
+- Issue 正文不含完整日志；「日志信息」中的 **`user_email`**（公司邮箱）/ `session_id` / … 来自 `--metadata auto`：`session_id` 优先使用**当前进程环境**（如 `OHAI_SESSION_ID` / `LANGFUSE_SESSION_ID`），也可使用近期写入且同工作区的 `.ohai-report/metadata.json` 会话，避免复用过期旧值；trace/model 等其他 metadata 可从当前环境或 `.ohai-report/metadata.json` 补齐；邮箱还会读取独立 JSON：**`<仓库>/.ohai-report/user_email.json`** 或全局 **`~/.claude/ohai-report/email.json`**（安装脚本写入，可直接编辑改邮箱；兼容旧路径 `ohai-report-user.json`）。观测侧建议：`LANGFUSE_SESSION_ID`…；**公司邮箱**建议 `OHAI_USER_EMAIL`；Claude Code hook 可从当前会话注入 `OHAI_SESSION_ID`，也可通过 `metadata update …` 预先落盘 `message_id` / `claude_subagent` / `trace_id` / `observation_id` 等字段。
+
+Webhook：`WEBHOOK_URL` / `OHAI_WEBHOOK_URL` 优先，否则使用 `tools/ohai-report/ohai_report/webhook_defaults.py` 中的默认地址。可选 `WEBHOOK_SECRET`。
+
+**GitCode / Gitee 直连（`--sink gitcode`）**：在仓库 `openharmonyinsight/ai-dev-feedback` 等目标上由本工具直接调 OpenAPI；默认 owner/repo 见 `tools/ohai-report/ohai_report/gitcode_defaults.py`（可用 `OHAI_GITCODE_OWNER` / `OHAI_GITCODE_REPO` 覆盖）。**Token** 必须经环境变量 `OHAI_GITCODE_TOKEN` 或 `GITCODE_ACCESS_TOKEN` 提供，勿写入仓库。使用 **Gitee** 时务必设置 `OHAI_GITCODE_API_BASE=https://gitee.com/api/v5`。**维度标签**（`tool:` / `model:` / `level:` / `category:`）会在建单后通过 JSON 接口绑定到 Issue。机器人对仓库有 **Maintainer** 且允许自动创建仓库标签时，设置 `OHAI_GITCODE_LABEL_MAINTAINER=1`（或 CLI `--gitcode-label-maintainer`）；否则仅绑定已存在的同名标签，缺失则报错。Claude Code 侧可设置 `OHAI_REPORT_SINK=gitcode` 与上述变量，执行 CLI 时显式传入 `--sink gitcode`。
+
+严格要求：
+1. 只基于用户输入生成字段，不读取完整日志、diff、源码、transcript。
+2. 不编造具体日志、命令输出、文件名；不确定处写 `unknown` 或保守短句。
+3. 不追问用户。
+4. 不在当前会话中输出完整 Issue 正文。
+5. 在仓库根目录执行 `create`（路径相对仓库根）。**必填**字段通过 CLI 传入；**可选**扩展字段一律用 `--field 键=值` 追加（值中勿含未转义的双引号；含空格时整条 `--field ...` 用引号包起来）。
+
+**必填字段（与模板对应）**
+- `title`：标题，≤80 字。
+- `summary`：问题摘要，可较长（≤800 字），写清现象与上下文。
+- `user_description`：原始描述（可与用户原话一致）。
+- `expected_behavior` / `actual_behavior`：期望与实际（各 ≤400 字）；信息不足时用保守概括。
+- `category`：必须是以下之一——模型输出错误 / 工具调用失败 / Skill 缺陷 / 上下文缺失 / 环境问题 / 其他。
+- `severity`：P0 / P1 / P2 / P3（默认倾向 P2，除非用户明确表达阻塞或重大损失）。
+
+**可选字段（与「AI 使用问题反馈」模板对齐，尽量补齐；不知填 `unknown`）**
+- `agent` / `model` / `level`：在「标签」中固定以 `agent:`、`model:`、`level:` 三行展示。Claude Code 上报时 `agent` 固定为 `claude`；`model` 为所用 Claude 模型名（如 `sonnet`、`opus`，不确定则填 `unknown`）；`level` 为问题严重等级 `P0`–`P3`，不填时正文沿用 `severity`。
+- `scenario` / `task_type` / `workflow_phase` / `affected_role`：使用场景（已不含「工具」行）。
+- `user_email` / `session_id` / `message_id` / `claude_subagent` / `trace_id` / `observation_id`：正文「日志信息」展示 **user_email**（公司邮箱）与 **session_id**；`user_id` 仅作追踪侧 JSON 字段。可与 metadata 重叠时用 `--field` 覆盖；缺省时邮箱/会话为「（未采集）」类提示，勿编造。
+- `primary_category`：展示用主分类（如 `model-capability`）；不填则正文里用 `category` 枚举值代替。
+- `sub_category`：次分类，默认 `none`。
+- `classification_confidence`：只能是 `high` / `medium` / `low`。
+- `classification_rationale`：判断依据（≤800 字）。
+- `tags`：可选备注（正文「标签」小节固定为 agent/model/level，不再渲染自由标签列表）。
+- `impact`：影响说明。
+- `possible_causes`：可能原因，多行可用 `\n`，行首可加 `- `。
+- `improvement_direction`：改进方向。
+- `suggested_follow_up`：建议补充信息。
+- `suggested_dispatch`：建议分派方向（如 `模型能力、产品体验、unknown`）。
+
+然后调用已配置的上报 CLI 入口执行 `create`，不要自行拼接或猜测相对路径形式的 Python 脚本命令。执行参数语义如下（将 `<...>` 与 `--field` 替换为实际值；**无**可选字段时可省略所有 `--field`）：`--source claude`、`--metadata auto`、`--json`、必填字段参数、可选扩展字段，以及 **二选一**的 `--sink webhook`（见下）或 `--sink gitcode`（见上文环境变量；维度标签由 CLI 自动处理，无需手写 `--gitcode-labels` 即可打 `tool/model/level/category`）。Webhook 侧 POST JSON 中 **`labels` 为逗号分隔的单个字符串**（如 `bug,critical`），非数组。Webhook 建单若需**额外**远端 Label：传 `--webhook-labels "标签1,标签2"`，或在 issue JSON / `--field labels=...` 中提供（与 `OHAI_WEBHOOK_LABELS` 合并；仅 `--webhook-labels` 时额外标签仅来自该串，维度仍由工具自动前置）。
+
+若参数过长，可先在本仓库根目录写入临时 JSON（字段名与 `tools/ohai-report/schemas/report_issue.schema.json` 一致），再通过已配置的 CLI 入口以 `--issue-file <路径>` 提交。**禁止**在命令中使用 `tools/ohai-report/ohai_report.py`、`scripts/create_issue.py` 等相对路径入口，以免在错误工作目录下执行或误写 `.ohai-report`。
+
+**上报入口**：必须使用安装器、Hook 或用户环境中已解析好的上报 CLI 入口；如果入口不可用，停止并报告“ohai-report CLI not found / 请设置 OHAI_REPORT_CLI”，不要尝试猜测仓库内相对路径。无论使用哪种 sink，**必须从命令标准输出的 JSON 解析** `issue_id` 与 `webhook_url` / `gitcode_url`（字段缺失或空则省略）。**禁止**在回复里写占位符 `<issue_id>` 或虚构链接。
+
+6. 从标准输出取**最后一行完整 JSON**（整行可被 `json.loads` 解析），读取其中的真实字符串 `issue_id` 与 `webhook_url`（字段缺失或空则省略）。**只回复一行**（尖括号内为解析出的字面量，勿保留 angle brackets）：
+
+```text
+已上报：<issue_id> <webhook_url>
+```
+
+无 `webhook_url` 时：`已上报：<issue_id> +用户描述：$ARGUMENTS`。

package/.opencode/commands/report-ai-issue.md

@@ -0,0 +1,30 @@
+---
+description: 上报 AI 辅助开发问题
+agent: build
+subtask: true
+---
+
+你是一个短事务问题上报 subagent。只做一件事：把用户描述整理成结构化字段，然后调用 OpenCode 插件工具 `report_ai_issue` 上报。不要继续参与当前开发任务。
+
+硬性规则：
+- 必须调用 `report_ai_issue` 工具；工具不可用时，只回复：`report_ai_issue tool unavailable / 请重新运行 scripts/install-opencode-plugin.ps1 后完全重启 OpenCode`。
+- 禁止调用 Python、CLI、shell、`tools/ohai-report/ohai_report.py`、`scripts/create_issue.py` 或任何 fallback 命令。
+- 禁止根据本地生成的 `issue_id` 自行判断成功。
+- 只有工具返回的最后一行是可解析 JSON，且 JSON 中 `ok` 不是 `false`，并且存在非空 `webhook_url` 或 `gitcode_url`，才算上报成功。
+- 如果 JSON 中 `ok` 为 `false`，或没有 `webhook_url` / `gitcode_url`，只回复：`上报失败：<issue_id或unknown> <report_error或remote_url_missing>`。
+- 成功时只回复一行：`已上报：<issue_id> <webhook_url或gitcode_url>`。
+- 不要输出 Summary、Issue successfully reported、完整 Issue 正文、调试过程或额外解释。
+
+必填字段：
+- `title`：标题，≤80 字。
+- `summary`：问题摘要，≤800 字。
+- `user_description`：用户原始描述。
+- `expected_behavior`：期望行为，≤400 字。
+- `actual_behavior`：实际行为，≤400 字。
+- `category`：只能是 `模型输出错误` / `工具调用失败` / `Skill 缺陷` / `上下文缺失` / `环境问题` / `其他`。
+- `severity`：`P0` / `P1` / `P2` / `P3`，默认 `P2`。
+
+可选字段通过工具参数补充，不确定就省略或填 `unknown`：`scenario`、`task_type`、`workflow_phase`、`affected_role`、`primary_category`、`sub_category`、`classification_confidence`、`classification_rationale`、`impact`、`possible_causes`、`improvement_direction`、`suggested_follow_up`、`suggested_dispatch`。
+
+用户描述：
+$ARGUMENTS

package/.opencode/plugins/oh-ai-report.ts

@@ -0,0 +1,569 @@
+import { readFileSync, existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, normalize, parse, resolve } from "node:path"
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+/**
+ * 工号配置（任选其一，优先级从上到下）：
+ * 1. 项目根 `opencode.json` → `plugin_config` 中指向本插件的条目（字段名见 `pickEmployeeIdFromPluginConfig`）
+ * 2. 宿主环境变量 `OHAI_EMPLOYEE_ID` / `OPENCODE_EMPLOYEE_ID`
+ *
+ * OpenCode 在「安装/加载」本地插件时**不会**弹出交互式输入框；工号需在配置或环境中提供。
+ *
+ * `plugin_config` 示例（本地插件的 key 一般为 `plugin` 数组里写的同一字符串，如路径 `./.opencode/plugins/oh-ai-report.ts`）：
+ * ```json
+ * {
+ *   "plugin": ["./.opencode/plugins/oh-ai-report.ts"],
+ *   "plugin_config": {
+ *     "./.opencode/plugins/oh-ai-report.ts": { "employeeId": "E12345" }
+ *   }
+ * }
+ * ```
+ *
+ * `ohai-report` CLI 路径：默认 `tools/ohai-report/ohai_report.py`（相对当前 OpenCode 工作区根）。
+ * 全局安装时运行 `scripts/install-opencode-plugin.ps1` / `install-opencode-plugin.sh` 会默认写入 **`OHAI_REPORT_CLI`**
+ * （Windows 用户环境变量；Linux `~/.config/environment.d/`；macOS 追加 `~/.zprofile`），也可用 `-SkipEnv` / `--skip-env` 跳过。
+ *
+ * 公司邮箱：安装脚本写入全局 ``~/.config/opencode/ohai-report/email.json``（字段 ``user_email``）；
+ * 可选仓库级 ``<project>/.ohai-report/user_email.json`` 覆盖。插件在无 Langfuse id 时注入 ``OHAI_USER_EMAIL`` / ``OHAI_USER_ID``。
+ *
+ * **远端 GitCode/Gitee/Webhook 建单（`report_ai_issue`）**：宿主环境变量 ``OHAI_REPORT_SINK``：
+ * - 不设：默认追加 ``--sink webhook``，让 `/report-ai-issue` 执行远端上报。
+ * - ``local``：``create`` 只写本地 ``.ohai-report/issues/``（与 CLI 默认一致）。
+ * - ``gitcode``：追加 ``--sink gitcode``（默认仓库见 ``tools/ohai-report/ohai_report/gitcode_defaults.py``，可用 ``OHAI_GITCODE_OWNER`` / ``OHAI_GITCODE_REPO`` 覆盖）；需配置 ``OHAI_GITCODE_TOKEN``（或 ``GITCODE_ACCESS_TOKEN``）。Gitee 请设 ``OHAI_GITCODE_API_BASE=https://gitee.com/api/v5``。
+ * - 维护者自动建仓库标签并绑定 Issue：另设 ``OHAI_GITCODE_LABEL_MAINTAINER=1``（或 ``OHAI_GITCODE_MAINTAINER=1``），插件会追加 ``--gitcode-label-maintainer``。
+ * - ``webhook``：追加 ``--sink webhook``（``WEBHOOK_URL`` / ``OHAI_WEBHOOK_URL`` 等见 README）。POST 体中 ``labels`` 由 Python 侧以**逗号分隔字符串**发送，并含 ``tool:``/``model:``/``level:``/``category:`` 自动合并。
+ */
+
+function truthyEnv(v: string | undefined): boolean {
+  const t = (v ?? "").trim().toLowerCase()
+  return t === "1" || t === "true" || t === "yes" || t === "on"
+}
+
+function webhookTimeoutArgv(env: Record<string, string | undefined>): string[] {
+  const raw = (env.OHAI_WEBHOOK_TIMEOUT ?? env.WEBHOOK_TIMEOUT ?? "").trim()
+  const timeout = raw ? Number(raw) : 10
+  if (!Number.isFinite(timeout) || timeout <= 0) return ["--webhook-timeout", "10"]
+  return ["--webhook-timeout", String(timeout)]
+}
+
+/** `/report-ai-issue` 默认远端上报；只有显式 `OHAI_REPORT_SINK=local` 才使用 CLI 默认（local）。 */
+function ohaiReportCreateSinkArgv(): string[] {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const sink = (env.OHAI_REPORT_SINK ?? "").trim().toLowerCase()
+  if (sink === "local") return []
+  if (sink === "gitcode") {
+    const out = ["--sink", "gitcode"]
+    if (truthyEnv(env.OHAI_GITCODE_LABEL_MAINTAINER) || truthyEnv(env.OHAI_GITCODE_MAINTAINER)) {
+      out.push("--gitcode-label-maintainer")
+    }
+    return out
+  }
+  if (sink && sink !== "webhook") {
+    console.warn(`[oh-ai-report] Unsupported OHAI_REPORT_SINK=${sink}; falling back to webhook.`)
+  }
+  return ["--sink", "webhook", ...webhookTimeoutArgv(env)]
+}
+
+/**
+ * OpenCode 全局配置目录（与安装脚本一致）：`%USERPROFILE%\.config\opencode` 或 `$XDG_CONFIG_HOME/opencode`。
+ */
+function opencodeGlobalConfigDir(): string {
+  const proc = (globalThis as { process?: { platform?: string; env?: Record<string, string | undefined> } }).process
+  const env = proc?.env ?? {}
+  const xdg = (env.XDG_CONFIG_HOME ?? "").trim()
+  if (xdg) return join(xdg, "opencode")
+  if (proc?.platform === "win32") {
+    const base = (env.USERPROFILE ?? "").trim() || homedir()
+    return join(base, ".config", "opencode")
+  }
+  return join((env.XDG_CONFIG_HOME ?? "").trim() || join(homedir(), ".config"), "opencode")
+}
+
+/** 读取安装脚本写入的独立邮箱 JSON（新路径优先，兼容旧文件）。 */
+function readUserEmailFromInstallJson(): string {
+  const oc = opencodeGlobalConfigDir()
+  const paths = [join(oc, "ohai-report", "email.json"), join(oc, "ohai-report-user.json")]
+  for (const p of paths) {
+    try {
+      if (!existsSync(p)) continue
+      const raw = readFileSync(p, "utf8")
+      const j = JSON.parse(raw) as Record<string, unknown>
+      const e = j.user_email ?? j.userEmail
+      if (typeof e === "string" && e.trim()) return e.trim()
+    } catch {
+      continue
+    }
+  }
+  return ""
+}
+
+/**
+ * 解析 `ohai-report` 入口脚本路径（供全局安装插件 + 任意工作区使用）。
+ */
+function ohaiReportPyPath(): string {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const p = (env.OHAI_REPORT_CLI ?? "").trim()
+  return p || "tools/ohai-report/ohai_report.py"
+}
+
+function isUsableReportCwd(value: string): boolean {
+  const t = (value || "").trim()
+  if (!t) return false
+  const full = normalize(resolve(t))
+  const root = normalize(parse(full).root)
+  return full !== root
+}
+
+function repoRootFromOhaiReportCli(): string {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const raw = (env.OHAI_REPORT_CLI ?? "").trim()
+  if (!raw) return ""
+  const py = normalize(resolve(raw))
+  if (!existsSync(py)) return ""
+
+  const scriptDir = normalize(dirname(py))
+  const asPosix = scriptDir.replace(/\\/g, "/")
+  if (asPosix.endsWith("/tools/ohai-report")) {
+    const root = dirname(dirname(scriptDir))
+    return isUsableReportCwd(root) ? root : ""
+  }
+  return ""
+}
+
+function resolveReportCwd(): string {
+  return repoRootFromOhaiReportCli()
+}
+
+/**
+ * Bus 事件形如 `{ id, type, properties }`，业务字段多在 `properties` 内；
+ * 工具 execute 的 context 多在顶层。`properties.info` 单独成层便于取 model / 扩展字段。
+ */
+function busPayloadLayers(ctx: unknown): Record<string, unknown>[] {
+  if (!ctx || typeof ctx !== "object") return []
+  const o = ctx as Record<string, unknown>
+  const layers: Record<string, unknown>[] = [o]
+  const props = o.properties
+  if (props && typeof props === "object") {
+    const p = props as Record<string, unknown>
+    layers.push(p)
+    const info = p.info
+    if (info && typeof info === "object") layers.push(info as Record<string, unknown>)
+  }
+  const rootInfo = o.info
+  if (rootInfo && typeof rootInfo === "object") layers.push(rootInfo as Record<string, unknown>)
+  return layers
+}
+
+function pickStringFromRecord(obj: Record<string, unknown>, keys: readonly string[]): string {
+  for (const k of keys) {
+    const v = obj[k]
+    if (typeof v === "string" && v.trim()) return v.trim()
+  }
+  return ""
+}
+
+/** 从单层对象及常见嵌套对象（metadata / tracing / telemetry 等）收集 tracing 相关字符串。 */
+function collectTracingFromObject(obj: Record<string, unknown>): {
+  userId: string
+  traceId: string
+  observationId: string
+} {
+  let userId = pickStringFromRecord(obj, ["userId", "userID", "user_id", "tracingUserId", "tracing_user_id"])
+  let traceId = pickStringFromRecord(obj, [
+    "traceId",
+    "traceID",
+    "trace_id",
+    "langfuseTraceId",
+    "langfuse_trace_id",
+    "otelTraceId",
+    "otel_trace_id",
+  ])
+  let observationId = pickStringFromRecord(obj, [
+    "observationId",
+    "observationID",
+    "observation_id",
+    "spanId",
+    "span_id",
+    "langfuseObservationId",
+    "langfuse_observation_id",
+  ])
+  const nestedKeys = ["metadata", "tracing", "telemetry", "langfuse", "experimentalTelemetry", "otel", "observability"]
+  for (const nk of nestedKeys) {
+    const sub = obj[nk]
+    if (sub && typeof sub === "object" && !Array.isArray(sub)) {
+      const inner = collectTracingFromObject(sub as Record<string, unknown>)
+      if (!userId && inner.userId) userId = inner.userId
+      if (!traceId && inner.traceId) traceId = inner.traceId
+      if (!observationId && inner.observationId) observationId = inner.observationId
+    }
+  }
+  return { userId, traceId, observationId }
+}
+
+function pickTracing(ctx: unknown): { userId: string; traceId: string; observationId: string } {
+  let userId = ""
+  let traceId = ""
+  let observationId = ""
+  for (const layer of busPayloadLayers(ctx)) {
+    const t = collectTracingFromObject(layer)
+    if (!userId && t.userId) userId = t.userId
+    if (!traceId && t.traceId) traceId = t.traceId
+    if (!observationId && t.observationId) observationId = t.observationId
+  }
+  return { userId, traceId, observationId }
+}
+
+/** W3C `traceparent`：向子进程传播 OTEL 时常用，可从环境变量补 trace / parent span。 */
+function parseTraceparent(tp: string): { traceId: string; parentSpanId: string } {
+  const parts = tp.trim().split("-")
+  if (parts.length < 4) return { traceId: "", parentSpanId: "" }
+  const ver = parts[0] ?? ""
+  const trace = (parts[1] ?? "").trim()
+  const span = (parts[2] ?? "").trim()
+  if (!/^[0-9a-f]{2}$/i.test(ver)) return { traceId: "", parentSpanId: "" }
+  if (!/^[0-9a-f]{32}$/i.test(trace)) return { traceId: "", parentSpanId: "" }
+  if (!/^[0-9a-f]{16}$/i.test(span)) return { traceId: trace.toLowerCase(), parentSpanId: "" }
+  return { traceId: trace.toLowerCase(), parentSpanId: span.toLowerCase() }
+}
+
+/**
+ * OpenCode 与 Langfuse/OTEL 常在「宿主进程环境变量」中携带 trace，而不在 bus payload。
+ * 插件与 Python 子进程同继承该环境时，此处显式读出并传给 metadata update / create。
+ */
+function pickTracingFromHostEnv(): { userId: string; traceId: string; observationId: string } {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const pick = (...keys: string[]) => {
+    for (const k of keys) {
+      const v = env[k]?.trim()
+      if (v) return v
+    }
+    return ""
+  }
+  let traceId = pick(
+    "LANGFUSE_TRACE_ID",
+    "TRACE_ID",
+    "OTEL_TRACE_ID",
+    "LANGFUSE_ROOT_TRACE_ID",
+  )
+  let observationId = pick(
+    "LANGFUSE_OBSERVATION_ID",
+    "OHAI_OBSERVATION_ID",
+    "OBSERVATION_ID",
+    "OTEL_SPAN_ID",
+  )
+  const userId = pick("OHAI_USER_ID", "LANGFUSE_USER_ID", "OPENCODE_USER_ID")
+  const tp = pick("TRACEPARENT", "traceparent")
+  if (tp) {
+    const { traceId: t2, parentSpanId } = parseTraceparent(tp)
+    if (!traceId && t2) traceId = t2
+    if (!observationId && parentSpanId) observationId = parentSpanId
+  }
+  return { userId, traceId, observationId }
+}
+
+/** OpenCode 工具 context / Bus 事件上可拿到的会话标识（非 LLM 模型名）。 */
+function pickSessionId(ctx: unknown): string {
+  for (const layer of busPayloadLayers(ctx)) {
+    for (const key of ["sessionID", "sessionId"] as const) {
+      const v = layer[key]
+      if (typeof v === "string" && v.trim()) return v.trim()
+    }
+    const session = layer.session
+    if (session && typeof session === "object") {
+      const id = (session as { id?: unknown }).id
+      if (typeof id === "string" && id.trim()) return id.trim()
+    }
+    const id = layer.id
+    if (typeof id === "string" && id.trim() && layer.slug !== undefined) return id.trim()
+  }
+  return ""
+}
+
+function pickModelIdField(model: unknown): string {
+  if (typeof model === "string" && model.trim()) return model.trim()
+  if (model && typeof model === "object") {
+    const o = model as Record<string, unknown>
+    const id = o.id
+    if (typeof id === "string" && id.trim()) return id.trim()
+  }
+  return ""
+}
+
+/** OpenCode 当前会话选用的 LLM（各层上的 model，取 model.id 或字符串；含 properties.info）。 */
+function pickOpenCodeModel(ctx: unknown): string {
+  for (const layer of busPayloadLayers(ctx)) {
+    const id = pickModelIdField(layer.model)
+    if (id) return id
+  }
+  return ""
+}
+
+async function fetchSessionRecord(client: unknown, sessionId: string): Promise<Record<string, unknown> | null> {
+  if (!sessionId.trim() || !client || typeof client !== "object") return null
+  const session = (client as { session?: { get?: (a: unknown) => Promise<unknown> } }).session
+  if (!session?.get) return null
+  try {
+    const res = await session.get({ path: { id: sessionId } } as never)
+    if (!res || typeof res !== "object") return null
+    const o = res as Record<string, unknown>
+    if (o.data && typeof o.data === "object") return o.data as Record<string, unknown>
+    return o
+  } catch {
+    return null
+  }
+}
+
+async function resolveTracing(
+  client: unknown,
+  ctx: unknown,
+  sessionId: string,
+): Promise<{ userId: string; traceId: string; observationId: string }> {
+  let { userId, traceId, observationId } = pickTracing(ctx)
+  const remote = await fetchSessionRecord(client, sessionId)
+  if (remote) {
+    const t = collectTracingFromObject(remote)
+    if (!userId && t.userId) userId = t.userId
+    if (!traceId && t.traceId) traceId = t.traceId
+    if (!observationId && t.observationId) observationId = t.observationId
+  }
+  const host = pickTracingFromHostEnv()
+  if (!userId && host.userId) userId = host.userId
+  if (!traceId && host.traceId) traceId = host.traceId
+  if (!observationId && host.observationId) observationId = host.observationId
+  return { userId, traceId, observationId }
+}
+
+function debugOhaiPlugin(
+  label: string,
+  payload: unknown,
+  fields: {
+    sessionId: string
+    model: string
+    userId: string
+    traceId: string
+    observationId: string
+  },
+) {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+  const flag = env?.OHAI_REPORT_PLUGIN_DEBUG?.trim()
+  if (!flag || flag === "0" || flag.toLowerCase() === "false") return
+  const o = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : null
+  const top = o ? Object.keys(o).sort().join(",") : ""
+  const props =
+    o?.properties && typeof o.properties === "object"
+      ? Object.keys(o.properties as object).sort().join(",")
+      : ""
+  const type = typeof o?.type === "string" ? o.type : ""
+  console.error(
+    `[oh-ai-report] ${label} type=${type} sessionId=${fields.sessionId || "(empty)"} model=${fields.model || "(empty)"} userId=${fields.userId || "(empty)"} traceId=${fields.traceId || "(empty)"} observationId=${fields.observationId || "(empty)"} keys=[${top}] propertiesKeys=[${props}]`,
+  )
+}
+
+/** OpenCode 将 `opencode.json` 里 `plugin_config[插件项]` 作为第二参数传入。 */
+function pickEmployeeIdFromPluginConfig(options: unknown): string {
+  if (!options || typeof options !== "object") return ""
+  const o = options as Record<string, unknown>
+  const keys = ["employeeId", "employee_id", "ohaiEmployeeId", "OHAI_EMPLOYEE_ID", "opencodeEmployeeId"] as const
+  for (const k of keys) {
+    const v = o[k]
+    if (typeof v === "string" && v.trim()) return v.trim()
+    if (typeof v === "number" && Number.isFinite(v)) return String(v)
+  }
+  return ""
+}
+
+export const OHAIReportPlugin: Plugin = async ({ $, client }, options) => {
+  const configuredEmployeeId = pickEmployeeIdFromPluginConfig(options)
+  const installedUserEmail = readUserEmailFromInstallJson()
+  const reportCwd = resolveReportCwd()
+
+  const hostProcessEnv = (): Record<string, string | undefined> =>
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+
+  /**
+   * 工号：`plugin_config` 或环境变量 `OHAI_EMPLOYEE_ID` / `OPENCODE_EMPLOYEE_ID`；
+   * 插件在调用 Python 时注入 `OHAI_USER_NAME` / `OHAI_USER_ID`（仅当宿主未显式设置对应变量时）。
+   */
+  const employeeEnvForSubprocess = (): Record<string, string> => {
+    const host = hostProcessEnv()
+    const eid = (
+      configuredEmployeeId ||
+      (host.OHAI_EMPLOYEE_ID ?? "").trim() ||
+      (host.OPENCODE_EMPLOYEE_ID ?? "").trim()
+    ).trim()
+    if (!eid) return {}
+    const out: Record<string, string> = {}
+    if (!(host.OHAI_USER_ID ?? "").trim()) out.OHAI_USER_ID = eid
+    if (!(host.OHAI_USER_NAME ?? "").trim()) out.OHAI_USER_NAME = eid
+    return out
+  }
+
+  /** 将 tracing 与工号相关变量写入子进程环境，便于 `metadata update` / `create --metadata auto` 读取。 */
+  const withOhaiSubprocessEnv = (
+    proc: { env: (e: Record<string, string>) => unknown; text: (enc?: string) => Promise<string> },
+    tracing: { userId: string; traceId: string; observationId: string; sessionId?: string },
+  ) => {
+    const extra: Record<string, string> = { ...employeeEnvForSubprocess() }
+    if (reportCwd) extra.OHAI_REPORT_CWD = reportCwd
+    if ((tracing.sessionId ?? "").trim()) extra.OHAI_SESSION_ID = (tracing.sessionId ?? "").trim()
+    if (tracing.traceId.trim()) extra.LANGFUSE_TRACE_ID = tracing.traceId.trim()
+    if (tracing.observationId.trim()) extra.LANGFUSE_OBSERVATION_ID = tracing.observationId.trim()
+    if (tracing.userId.trim()) extra.OHAI_USER_ID = tracing.userId.trim()
+    const host = hostProcessEnv()
+    const resolvedUid = ((extra.OHAI_USER_ID ?? host.OHAI_USER_ID) ?? "").trim()
+    if (!resolvedUid && installedUserEmail.trim()) {
+      extra.OHAI_USER_ID = installedUserEmail.trim()
+      if (!(host.OHAI_USER_NAME ?? "").trim() && !(extra.OHAI_USER_NAME ?? "").trim()) {
+        extra.OHAI_USER_NAME = installedUserEmail.trim()
+      }
+    }
+    if (installedUserEmail.trim() && !(host.OHAI_USER_EMAIL ?? "").trim()) {
+      extra.OHAI_USER_EMAIL = installedUserEmail.trim()
+    }
+    return Object.keys(extra).length ? proc.env(extra) : proc
+  }
+
+  const flushMetadata = async (
+    sessionId: string,
+    model: string,
+    userId: string,
+    traceId: string,
+    observationId: string,
+  ) => {
+    if (!reportCwd) return
+    try {
+      const tracing = { userId, traceId, observationId, sessionId }
+      const py = ohaiReportPyPath()
+      const proc = $`python ${py} metadata update --source opencode --cwd ${reportCwd} --session-id ${sessionId} --model ${model} --user-id ${userId} --trace-id ${traceId} --observation-id ${observationId} --drop-message-and-subagent`
+      await withOhaiSubprocessEnv(proc as never, tracing)
+    } catch {
+      // Metadata refresh is best-effort; issue creation still works without it.
+    }
+  }
+
+  const refresh = async (
+    label: string,
+    payload: unknown,
+    sessionId: string,
+  ): Promise<{ userId: string; traceId: string; observationId: string }> => {
+    const model = pickOpenCodeModel(payload)
+    const tracing = await resolveTracing(client, payload, sessionId)
+    debugOhaiPlugin(label, payload, {
+      sessionId,
+      model,
+      userId: tracing.userId,
+      traceId: tracing.traceId,
+      observationId: tracing.observationId,
+    })
+    await flushMetadata(
+      sessionId,
+      model,
+      tracing.userId.trim() || installedUserEmail.trim(),
+      tracing.traceId,
+      tracing.observationId,
+    )
+    return tracing
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (
+        event.type === "session.created" ||
+        event.type === "session.updated" ||
+        event.type === "command.executed"
+      ) {
+        const sessionId = pickSessionId(event)
+        await refresh("event", event, sessionId)
+      }
+    },
+
+    tool: {
+      report_ai_issue: tool({
+        description:
+          "Report an AI development issue. Do not include full logs; session/trace IDs appear in the template log section when metadata is available.",
+        args: {
+          title: tool.schema.string(),
+          category: tool.schema.string(),
+          summary: tool.schema.string(),
+          expected_behavior: tool.schema.string(),
+          actual_behavior: tool.schema.string(),
+          severity: tool.schema.string().optional(),
+          user_description: tool.schema.string(),
+        },
+        async execute(args, context) {
+          if (!reportCwd) {
+            return JSON.stringify({
+              ok: false,
+              report_error: "invalid_report_cwd",
+              report_error_detail:
+                "OHAI_REPORT_CLI is not set to a valid .../tools/ohai-report/ohai_report.py path, so the repository root for .ohai-report/issues cannot be derived.",
+            })
+          }
+          const sessionId = pickSessionId(context)
+          const tracing = await refresh("tool.report_ai_issue", context, sessionId)
+
+          const py = ohaiReportPyPath()
+          const sinkArgv = ohaiReportCreateSinkArgv()
+          const proc = withOhaiSubprocessEnv(
+            $`python ${py} create \
+            --source opencode \
+            --cwd ${reportCwd} \
+            --title ${args.title} \
+            --category ${args.category} \
+            --summary ${args.summary} \
+            --expected-behavior ${args.expected_behavior} \
+            --actual-behavior ${args.actual_behavior} \
+            --severity ${args.severity ?? "P2"} \
+            --user-description ${args.user_description} \
+            --metadata auto \
+            --field agent=opencode \
+            ${sinkArgv} \
+            --quiet \
+            --json` as never,
+            { ...tracing, sessionId },
+          )
+          const out = (await proc) as { text: () => Promise<string> }
+          const text = await out.text()
+          const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+          const last = lines[lines.length - 1] ?? ""
+          try {
+            const result = JSON.parse(last) as Record<string, unknown>
+            if (result && typeof result === "object" && !Array.isArray(result)) {
+              const reportedSession = typeof result.session_id === "string" ? result.session_id.trim() : ""
+              const status = typeof result.status === "string" ? result.status.trim() : ""
+              const webhookUrl = typeof result.webhook_url === "string" ? result.webhook_url.trim() : ""
+              const gitcodeUrl = typeof result.gitcode_url === "string" ? result.gitcode_url.trim() : ""
+              const remoteCreated = Boolean(webhookUrl || gitcodeUrl || status === "created-webhook" || status === "created-gitcode")
+              result.ok = remoteCreated
+              if (!remoteCreated) {
+                result.report_error = "remote_url_missing"
+                result.report_error_detail =
+                  "CLI completed without a webhook_url/gitcode_url or remote-created status; do not report this as a successful remote issue."
+              }
+              result.session_id_source = sessionId.trim()
+                ? "opencode_context"
+                : reportedSession
+                  ? "metadata"
+                  : "missing"
+              if (sessionId.trim()) result.opencode_context_session_id = sessionId.trim()
+              if (!sessionId.trim() && !reportedSession) {
+                result.session_id_warning =
+                  "OpenCode tool context did not include a session id, and no fresh metadata session was available."
+              }
+              return JSON.stringify(result)
+            }
+          } catch {
+            // Preserve the original CLI output if it is not JSON.
+          }
+          return JSON.stringify({
+            ok: false,
+            report_error: "non_json_cli_output",
+            report_error_detail: "ohai-report CLI did not return a parseable JSON line; remote issue status is unknown.",
+            raw_output: text,
+          })
+        },
+      }),
+    },
+  }
+}