oh-aicoding-tool 0.1.2 → 0.1.5

package/opencode-ohai-report/docs/opencode-ai-issue-collection-best-practices.md

@@ -1,476 +0,0 @@
-# OpenCode 问题采集最佳方案
-
-## 1. 文档迁移分析
-
-现有 `claude-ai-issue-collection-best-practices.md` 的核心思想可以复用，但不能原样照搬到 OpenCode。
-
-Claude Code 方案的重点是：
-
-- 用 `/report-ai-issue` 做入口。
-- 当前 LLM 只做轻量模板化。
-- 日志和完整会话交给 Langfuse。
-- Issue 中只保存 `session_id`、`trace_id`、`langfuse_url`、用户信息和问题模板。
-- 通过 `ohai-report` CLI/API 统一落库。
-
-迁移到 OpenCode 后，需要调整的点是：
-
-| 能力 | Claude Code | OpenCode |
-| --- | --- | --- |
-| 用户入口 | `.claude/commands` | `.opencode/commands` 或 `opencode.jsonc` 的 `command` |
-| 降低主上下文污染 | Hook 拦截或短事务命令 | 优先使用 `subtask: true` 或短事务命令 |
-| 自动补元信息 | Claude Hook | OpenCode Plugin 或 `ohai-report --metadata auto` |
-| 自定义工具 | Claude tool/MCP | OpenCode custom tool 或 Plugin tool |
-| 日志来源 | Langfuse | Langfuse |
-| Issue 落库 | `ohai-report` | 同一套 `ohai-report` |
-
-最终结论：
-
-> OpenCode 不需要重新开发一套问题采集系统，只需要实现 OpenCode adapter。通用核心仍然是 `ReportPayload + ohai-report + Langfuse 索引 + Issue 落库`。
-
-## 2. OpenCode 最佳架构
-
-推荐架构：
-
-```text
-开发者输入
-  /report-ai-issue <一句话问题描述>
-
-OpenCode
-  Custom Command
-    - 读取 $ARGUMENTS
-    - 当前 LLM 只做轻量模板化
-    - 不读取完整日志、diff、源码、transcript
-    - 不做长根因分析
-    - 调用 ohai-report create --metadata auto --quiet --json
-
-OpenCode Plugin，可选
-  - 监听 session / command / tool 事件
-  - 补齐 session_id / trace_id / user_id / cwd / repo
-  - 提供 report_ai_issue custom tool
-  - 不上传日志正文
-
-Langfuse
-  - 保存完整日志、trace、session、工具调用
-
-Issue 系统
-  - 保存模板化问题
-  - 保存 session_id / trace_id / langfuse_url
-  - 保存用户和环境元信息
-```
-
-一句话原则：
-
-> OpenCode 只负责把用户问题模板化并提交索引；完整日志在 Langfuse，Issue 里不搬运日志。
-
-## 3. 为什么 OpenCode 适合这样做
-
-### 3.1 Custom Commands 适合作为入口
-
-OpenCode 支持自定义 commands。可以通过 `.opencode/commands/*.md` 或 `opencode.jsonc` 的 `command` 配置创建命令。命令支持 `$ARGUMENTS`，适合实现：
-
-```text
-/report-ai-issue hdc 远程服务器无法连接本地开发板
-```
-
-这个入口足够自然，不需要用户离开 OpenCode。
-
-### 3.2 `subtask: true` 适合降低污染
-
-OpenCode command 支持 `subtask` 配置。官方说明里，`subtask: true` 可以强制以 subagent 方式执行，用于减少 primary context 污染。
-
-因此，OpenCode 侧的最低污染方案不是“命令级阻断”，而是：
-
-```text
-/report-ai-issue
-  -> subtask 执行轻量模板化
-  -> 调用 ohai-report
-  -> 主会话只收到 issue_id
-```
-
-这和 Claude Code 的 `UserPromptExpansion Hook + decision:block` 思路不同，但目标一致：减少主开发上下文污染。
-
-### 3.3 Plugin 适合补元信息，不适合承载全部业务
-
-OpenCode Plugin 可以监听 `command.executed`、`session.created`、`session.error`、`session.idle`、`tool.execute.before/after`、`tui.command.execute` 等事件，也可以提供 custom tool。
-
-但在当前需求里，日志已经由 Langfuse 采集，Issue 不上传完整日志。因此 Plugin 不需要保存大量现场，只需要做轻量 metadata：
-
-- 当前 OpenCode session 标识。
-- Langfuse trace_id 或 trace URL。
-- user_id / team。
-- cwd / repo / branch / commit。
-- source = `opencode`。
-
-## 4. 上报内容设计
-
-Issue 上报 payload 建议统一为：
-
-```json
-{
-  "source": "opencode",
-  "agent": "opencode",
-  "session_id": "opencode-session-xxx",
-  "trace_id": "langfuse-trace-xxx",
-  "langfuse_url": "https://langfuse.example.com/project/xxx/traces/xxx",
-  "user": {
-    "id": "user001",
-    "name": "zhangsan",
-    "team": "OpenHarmony AI"
-  },
-  "issue": {
-    "title": "HDC 远程服务器无法连接本地开发板",
-    "category": "环境问题",
-    "summary": "远程 OpenCode 无法访问本地 HDC 设备",
-    "expected_behavior": "能够定位本地设备访问方案或给出明确配置提示",
-    "actual_behavior": "无法发现或连接本地开发板",
-    "severity": "P2",
-    "user_description": "hdc 远程服务器无法连接本地开发板"
-  },
-  "context": {
-    "repo": "openharmony/xxx",
-    "branch": "feature/report",
-    "commit": "abcdef",
-    "cwd": "/workspace/project"
-  }
-}
-```
-
-不上传：
-
-- 完整日志
-- 完整 transcript
-- 完整 diff
-- 源码片段
-- 工具 stdout/stderr
-- token、私钥、账号信息
-
-完整排查链路通过 `session_id` / `trace_id` / `langfuse_url` 去 Langfuse 关联。
-
-## 5. OpenCode Command 方案
-
-项目级命令：
-
-```text
-.opencode/commands/report-ai-issue.md
-```
-
-推荐内容：
-
-```markdown
----
-description: 上报 AI 辅助开发问题
-agent: build
-subtask: true
----
-
-你是一个短事务问题上报入口。请把用户描述模板化后提交，不要继续参与当前开发任务。
-
-严格要求：
-1. 只基于用户输入生成字段，不读取完整日志、diff、源码、transcript。
-2. 不分析复杂根因，不展开长解释。
-3. 不追问用户。
-4. 不在当前会话中输出完整 Issue 正文。
-5. 调用 `ohai-report create --source opencode --metadata auto --quiet --json`。
-6. 最后只返回一行：`已上报：<issue_id>`。
-
-用户描述：
-$ARGUMENTS
-
-请生成以下字段：
-- title: 20 字以内
-- category: 模型输出错误 / 工具调用失败 / Skill 缺陷 / 上下文缺失 / 环境问题 / 其他
-- summary: 50 字以内
-- expected_behavior: 50 字以内
-- actual_behavior: 50 字以内
-- severity: P0 / P1 / P2 / P3
-
-然后执行：
-
-ohai-report create \
-  --source opencode \
-  --title "<title>" \
-  --category "<category>" \
-  --summary "<summary>" \
-  --expected-behavior "<expected_behavior>" \
-  --actual-behavior "<actual_behavior>" \
-  --severity "<severity>" \
-  --user-description "$ARGUMENTS" \
-  --metadata auto \
-  --quiet \
-  --json
-```
-
-说明：
-
-- `subtask: true` 用来降低对主上下文的污染。
-- 不使用 `!command` 注入日志，因为 shell output 会进入 prompt。
-- 不使用 `@file` 引用日志或源码文件。
-- `ohai-report` 必须 quiet，只返回结构化结果。
-
-## 6. opencode.jsonc 配置方案
-
-如果不想放 Markdown 文件，也可以写在 `opencode.jsonc`：
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "command": {
-    "report-ai-issue": {
-      "description": "上报 AI 辅助开发问题",
-      "agent": "build",
-      "subtask": true,
-      "template": "你是一个短事务问题上报入口。只基于用户输入模板化问题，不读取日志、diff、源码或 transcript。用户描述：$ARGUMENTS。生成 title/category/summary/expected_behavior/actual_behavior/severity，然后调用 ohai-report create --source opencode --metadata auto --quiet --json，最后只返回一行：已上报 <issue_id>。"
-    }
-  }
-}
-```
-
-项目级团队推荐使用 Markdown 文件，便于版本管理和审查。
-
-## 7. OpenCode Plugin 方案
-
-Plugin 不是第一阶段必需项，但适合做 metadata 自动补齐。
-
-项目级插件路径：
-
-```text
-.opencode/plugins/oh-ai-report.ts
-```
-
-示意：
-
-```ts
-import type { Plugin } from "@opencode-ai/plugin"
-
-export const OHAIReportPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
-  return {
-    event: async ({ event }) => {
-      if (
-        event.type === "session.created" ||
-        event.type === "session.updated" ||
-        event.type === "command.executed"
-      ) {
-        await $`ohai-report metadata update --source opencode --cwd ${directory}`
-      }
-    }
-  }
-}
-```
-
-这个插件只做：
-
-- 写入或刷新本地 metadata。
-- 关联 OpenCode session 和 Langfuse trace。
-- 不保存完整日志。
-- 不自动创建 Issue。
-
-## 8. Custom Tool 方案
-
-如果希望让 OpenCode agent 显式调用工具，可以在 Plugin 中提供 `report_ai_issue`。
-
-示意：
-
-```ts
-import type { Plugin } from "@opencode-ai/plugin"
-import { tool } from "@opencode-ai/plugin"
-
-export const OHAIReportPlugin: Plugin = async ({ $, directory }) => {
-  return {
-    tool: {
-      report_ai_issue: tool({
-        description: "Report an AI development issue. Do not include logs; logs are linked through Langfuse.",
-        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) {
-          const result = await $`ohai-report create \
-            --source opencode \
-            --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 \
-            --quiet \
-            --json`
-
-          return result.text()
-        }
-      })
-    }
-  }
-}
-```
-
-这种方式适合跨命令复用，但第一阶段可以先不做。
-
-## 9. `ohai-report` CLI 职责
-
-OpenCode adapter 不应该承担上报系统的核心逻辑。核心逻辑放在 `ohai-report`：
-
-```bash
-ohai-report create \
-  --source opencode \
-  --title "HDC 远程服务器无法连接本地开发板" \
-  --category "环境问题" \
-  --summary "远程 OpenCode 无法访问本地 HDC 设备" \
-  --expected-behavior "能够定位本地设备访问方案或给出明确配置提示" \
-  --actual-behavior "无法发现或连接本地开发板" \
-  --severity "P2" \
-  --user-description "hdc 远程服务器无法连接本地开发板" \
-  --metadata auto \
-  --quiet \
-  --json
-```
-
-`--metadata auto` 负责补齐：
-
-- `session_id`
-- `trace_id`
-- `langfuse_url`
-- `user_id`
-- `team`
-- `cwd`
-- `repo`
-- `branch`
-- `commit`
-
-CLI 输出：
-
-```json
-{
-  "issue_id": "AI-DEV-123",
-  "trace_id": "langfuse-trace-xxx",
-  "langfuse_url": "https://langfuse.example.com/project/xxx/traces/xxx"
-}
-```
-
-## 10. 污染控制
-
-OpenCode 的污染控制重点：
-
-| 控制点 | 做法 |
-| --- | --- |
-| 不搬运日志 | 不使用 `!command` 注入日志，不读取日志文件 |
-| 不搬运源码 | 不使用 `@file` 引用源码或 diff |
-| 不长分析 | command 中明确禁止根因长分析 |
-| 降低主上下文影响 | 配置 `subtask: true` |
-| 输出极简 | 只返回 `已上报：AI-DEV-123` |
-| 完整现场回溯 | 通过 Langfuse 的 `trace_id` / `session_id` |
-
-污染程度预估：
-
-```text
-低污染：
-  /report-ai-issue + subtask + quiet CLI
-
-中污染：
-  /report-ai-issue + 当前主 agent 轻量模板化
-
-高污染：
-  command 读取日志、diff、源码，并在主会话生成完整 Issue 正文
-```
-
-## 11. 落地阶段
-
-### 第一阶段：最小闭环
-
-- 创建 `.opencode/commands/report-ai-issue.md`。
-- 使用 `subtask: true`。
-- 调用 `ohai-report create --source opencode --metadata auto --quiet --json`。
-- Issue 只保存模板字段和 Langfuse 索引。
-
-### 第二阶段：metadata 自动补齐
-
-- 增加 `.opencode/plugins/oh-ai-report.ts`。
-- 监听 `session.created`、`session.updated`、`command.executed`。
-- 写入本地 metadata。
-- 让 `ohai-report --metadata auto` 自动读取。
-
-### 第三阶段：custom tool
-
-- 在 Plugin 中提供 `report_ai_issue`。
-- 让 agent 可以显式调用工具。
-- 统一复用 `ohai-report`。
-
-### 第四阶段：平台化
-
-- 接入 GitCode/Jira/DTS。
-- 接入 Langfuse trace/session 跳转。
-- 增加用户、团队、场景统计。
-- 支持 Claude Code、OpenCode、Codex 多 adapter。
-
-## 12. 与 Claude Code 方案的差异
-
-| 项目 | Claude Code | OpenCode |
-| --- | --- | --- |
-| 最低污染机制 | `UserPromptExpansion Hook + decision:block` | `subtask: true + quiet CLI` |
-| 第一阶段推荐 | 短事务 command 或 Hook 拦截 | 短事务 command |
-| 元信息补齐 | Hook | Plugin 或 `metadata auto` |
-| 自定义工具 | MCP/tool | Plugin custom tool |
-| 日志链路 | Langfuse | Langfuse |
-| 核心上报 | `ohai-report` | `ohai-report` |
-
-OpenCode 侧不建议把第一阶段做得太重。先用 command 跑通体验，再补 Plugin。
-
-## 13. 最终建议
-
-OpenCode 的最佳问题采集方案是：
-
-```text
-/report-ai-issue <用户一句话问题>
-  -> OpenCode custom command
-  -> subtask 轻量模板化
-  -> ohai-report --metadata auto --quiet
-  -> Issue 保存问题模板 + user + session_id + trace_id + langfuse_url
-  -> 完整日志从 Langfuse 查询
-```
-
-不要为 OpenCode 重新开发完整上报系统。只需要做一个薄 adapter，复用统一的：
-
-- `ReportPayload`
-- `ohai-report` CLI/API
-- Langfuse trace/session 索引
-- GitCode/Jira/DTS 落库逻辑
-
-## 14. 参考依据
-
-- OpenCode Commands: https://opencode.ai/docs/commands
-- OpenCode Plugins: https://opencode.ai/docs/plugins
-- OpenCode Custom Tools: https://opencode.ai/docs/custom-tools/
-- Claude Code 迁移源文档：[claude-ai-issue-collection-best-practices.md](../claude-ai-issue-collection-best-practices.md)
-
-## 15. 当前第一版实现
-
-本目录已按第一阶段落地了一个本地可运行版本：
-
-| 文件 | 作用 |
-| --- | --- |
-| `.opencode/commands/report-ai-issue.md` | OpenCode `/report-ai-issue` 短事务命令入口 |
-| `.opencode/plugins/oh-ai-report.ts` | 可选 OpenCode plugin，刷新 metadata 并提供 `report_ai_issue` custom tool |
-| `tools/ohai-report/ohai_report.py` | 本地 `ohai-report` CLI 原型 |
-| `tools/ohai-report/README.md` | CLI 使用说明 |
-| `.gitignore` | 忽略本地 `.ohai-report/` 运行产物 |
-
-当前版本能力：
-
-- 支持 `create` 创建本地 issue payload。
-- 支持 `metadata update` 写入本地 metadata。
-- 支持 `--metadata auto` 从 metadata、环境变量和 git 上下文补齐字段。
-- 输出 `.ohai-report/issues/<issue_id>.json`。
-- 不采集、不上传完整日志、diff、transcript、源码或工具输出。
-
-当前版本仍未接入：
-
-- GitCode/Jira/DTS 真实 Issue API。
-- Langfuse API 自动反查。
-- 组织级用户/团队映射。
-- 去重、归属推荐、质量评分。