oh-aicoding-tool 0.1.0

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

@@ -0,0 +1,313 @@
+# OpenCode 问题采集架构设计
+
+## 1. 背景与目标
+
+本设计用于维护 OpenCode 场景下的 AI 辅助开发问题采集能力。目标不是采集完整日志，而是将用户问题模板化，并通过 `session_id` / `trace_id` / `langfuse_url` 关联到 Langfuse 中的完整会话和日志。
+
+核心目标：
+
+- 降低 OpenCode 主上下文污染。
+- 让 subagent 使用 LLM 完成轻量模板化。
+- Issue 中不上传日志、diff、transcript、源码或工具输出。
+- 上报核心与 Agent 入口解耦，便于后续支持 Claude Code、Codex 等适配器。
+- 后端 sink 可替换，先本地 JSON，后续可升级 GitCode/Jira/DTS。
+
+## 2. 总体架构
+
+```text
+OpenCode 用户
+  /report-ai-issue <一句话问题>
+        |
+        v
+OpenCode Command Adapter
+  .opencode/commands/report-ai-issue.md
+  subtask: true
+        |
+        v
+Subagent / LLM Template Layer
+  title/category/summary/expected/actual/severity
+        |
+        v
+ohai-report CLI
+  schema validation
+  metadata auto
+  payload assembly
+  sink dispatch
+        |
+        v
+Sink
+  local JSON / GitCode / Webhook（默认 URL 见 webhook_defaults.py）
+  Jira/DTS 等可后续扩展
+        |
+        v
+Langfuse
+  linked by session_id / trace_id / langfuse_url
+```
+
+## 3. 模块分层
+
+| 层级 | 文件 | 职责 |
+| --- | --- | --- |
+| Agent Adapter | `.opencode/commands/report-ai-issue.md` | `/report-ai-issue`；默认 `--sink webhook`（`WEBHOOK_URL` 优先，否则 `webhook_defaults`） |
+| Plugin Adapter | `.opencode/plugins/oh-ai-report.ts` | 可选 metadata 刷新和 custom tool |
+| CLI Entrypoint | `tools/ohai-report/ohai_report.py` | 兼容入口，转发到 package CLI |
+| CLI Orchestration | `tools/ohai-report/ohai_report/cli.py` | 解析命令，编排 validation、metadata、payload、sink |
+| Schema File | `tools/ohai-report/schemas/report_issue.schema.json` | 问题模板字段、枚举、长度约束 |
+| Schema Runtime | `tools/ohai-report/ohai_report/schema.py` | 读取 schema 文件，执行校验 |
+| Metadata | `tools/ohai-report/ohai_report/metadata.py` | 合并本地 metadata、环境变量、git 上下文 |
+| Payload | `tools/ohai-report/ohai_report/payload.py` | 生成标准 ReportPayload |
+| Issue 正文模板 | `tools/ohai-report/ohai_report/issue_markdown.py` | 「AI 使用问题反馈」Markdown，Webhook/GitCode 共用 |
+| Sink | `tools/ohai-report/ohai_report/sinks/local.py` | 本地 JSON 落盘 |
+| GitCode Sink | `tools/ohai-report/ohai_report/sinks/gitcode.py` | GitCode Issues API 落远端并回写本地 |
+| GitCode 默认仓库 | `tools/ohai-report/ohai_report/gitcode_defaults.py` | 可选写死 owner/repo；Token 仅用环境变量 |
+| Webhook Sink | `tools/ohai-report/ohai_report/sinks/webhook.py` | JSON Webhook 建单（title + Markdown body） |
+| Webhook 默认地址 | `tools/ohai-report/ohai_report/webhook_defaults.py` | `WEBHOOK_URL` 未设时的回退地址 |
+| 快捷脚本 | `scripts/create_issue.py` | 读取 `examples/issue_output.json` 等并 POST Webhook |
+
+GitCode sink 在维护者自动建标签模式下会为新标签分配稳定颜色：agent、优先级和分类标签使用不同色系；已有标签只绑定，不主动改色。Webhook sink 目前只发送逗号分隔的 ASCII 标签字符串，颜色由 Webhook 服务端决定。
+
+## 4. 数据流
+
+### 4.1 用户上报
+
+```text
+用户输入：
+  /report-ai-issue hdc 远程服务器无法连接本地开发板
+
+OpenCode command：
+  以 subtask 执行
+  使用 LLM 生成模板字段
+
+ohai-report create：
+  校验字段
+  metadata auto 补齐 session/trace/user/context
+  生成 payload
+  写入 local sink
+
+返回：
+  已上报：AI-DEV-yyyymmddHHMMSS
+```
+
+### 4.2 Metadata 更新
+
+```text
+OpenCode plugin 或人工命令
+  -> ohai-report metadata update
+  -> .ohai-report/metadata.json
+
+create --metadata auto
+  -> 读取 metadata.json
+  -> 读取环境变量
+  -> 读取 git context
+  -> 组装最终 metadata
+```
+
+## 5. ReportPayload 协议
+
+当前 payload 结构：
+
+```json
+{
+  "issue_id": "AI-DEV-20260508120000",
+  "created_at": "2026-05-08T12:00:00+08:00",
+  "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": "",
+    "branch": "",
+    "commit": "",
+    "cwd": ""
+  },
+  "privacy": {
+    "uploads_logs": false,
+    "uploads_diff": false,
+    "uploads_transcript": false,
+    "note": "Issue only stores template fields and Langfuse/session indexes."
+  },
+  "status": "created-local"
+}
+```
+
+约束：
+
+- `issue.category` 必须来自 `schema.py` 枚举。
+- `issue.severity` 必须是 `P0/P1/P2/P3`。
+- `privacy.uploads_logs/uploads_diff/uploads_transcript` 当前必须为 `false`。
+- 完整日志只通过 Langfuse 查询。
+
+## 6. 维护与升级方式
+
+### 6.1 修改模板字段
+
+修改位置：
+
+- `.opencode/commands/report-ai-issue.md`
+- `tools/ohai-report/schemas/report_issue.schema.json`
+
+通常不需要修改 `schema.py`、`payload.py` 或 sink。新增非固定参数可通过 CLI 的 `--field key=value`、`--issue-json` 或 `--issue-file` 传入。
+
+例如新增 `scenario`：
+
+```json
+{
+  "scenario": {
+    "type": "string",
+    "required": false,
+    "enum": ["HDC/设备操作", "CI 失败分析", "代码生成", "其他"],
+    "description": "Issue scenario"
+  }
+}
+```
+
+OpenCode command 中增加：
+
+```text
+- scenario: HDC/设备操作 / CI 失败分析 / 代码生成 / 其他
+```
+
+调用 CLI 时增加：
+
+```bash
+--field scenario="<scenario>"
+```
+
+### 6.2 增加 GitCode/Jira/DTS 后端
+
+新增或完善：
+
+```text
+tools/ohai-report/ohai_report/sinks/gitcode.py
+tools/ohai-report/ohai_report/sinks/jira.py
+tools/ohai-report/ohai_report/sinks/dts.py
+```
+
+建议扩展 CLI：
+
+```bash
+ohai-report create --sink local
+ohai-report create --sink gitcode
+```
+
+Agent command 不需要知道 sink 细节。
+
+### 6.3 增加新的 Agent
+
+保持 `ohai-report` 不变，只新增适配器：
+
+```text
+.claude/commands/report-ai-issue.md
+.codex/report adapter
+other-agent adapter
+```
+
+这些适配器都生成同一套模板字段并调用同一个 CLI/API。
+
+### 6.4 接入 Langfuse API
+
+如果后续需要从 Langfuse 自动生成 URL 或校验 trace 存在，建议新增：
+
+```text
+tools/ohai-report/ohai_report/observability/langfuse.py
+```
+
+不要把 Langfuse 查询逻辑写进 command prompt 或 sink。
+
+## 7. 污染控制策略
+
+OpenCode 主上下文污染控制由三层保证：
+
+- `subtask: true`：模板化在子任务里完成。
+- command 约束：禁止读取日志、diff、源码、transcript。
+- CLI quiet 输出：只返回 JSON 或 issue id。
+
+预期主上下文只保留：
+
+```text
+用户：/report-ai-issue xxx
+助手：已上报：AI-DEV-xxx
+```
+
+## 8. 安全与隐私
+
+默认禁止进入 Issue payload 的内容：
+
+- 完整日志
+- 完整 transcript
+- 完整 diff
+- 源码片段
+- 工具 stdout/stderr
+- token、私钥、账号、设备敏感信息
+
+允许进入 Issue payload 的内容：
+
+- 用户主动描述的问题
+- LLM 模板化字段
+- session_id / trace_id / langfuse_url
+- 用户和团队元信息
+- repo / branch / commit / cwd
+
+## 9. 测试建议
+
+每次修改 CLI 后至少运行：
+
+```bash
+python -m py_compile tools/ohai-report/ohai_report.py
+python -m py_compile tools/ohai-report/ohai_report/*.py
+python tools/ohai-report/ohai_report.py metadata update --source opencode --json
+python tools/ohai-report/ohai_report.py create --source opencode --title "测试问题" --category "其他" --summary "验证上报链路" --expected-behavior "生成 payload" --actual-behavior "生成 JSON" --severity P3 --user-description "测试" --metadata auto --quiet --json
+```
+
+每次修改 schema 后，再运行：
+
+```bash
+python tools/ohai-report/ohai_report.py create --source opencode --issue-json "{\"title\":\"测试问题\",\"category\":\"其他\",\"summary\":\"验证上报链路\",\"expected_behavior\":\"生成 payload\",\"actual_behavior\":\"生成 JSON\",\"severity\":\"P3\",\"user_description\":\"测试\"}" --metadata auto --quiet --json
+```
+
+Windows/脚本环境建议优先验证 `--issue-file`，避免 shell 引号差异：
+
+```bash
+python tools/ohai-report/ohai_report.py create --source opencode --issue-file .ohai-report/issue-input.json --metadata auto --quiet --json
+```
+
+验证 `.ohai-report/latest.json` 中：
+
+- `privacy.uploads_logs` 为 `false`
+- `privacy.uploads_diff` 为 `false`
+- `privacy.uploads_transcript` 为 `false`
+- payload 中没有日志正文
+
+## 10. 当前状态
+
+已实现：
+
+- OpenCode command adapter
+- OpenCode plugin adapter
+- 模块化 `ohai-report` CLI
+- 独立问题模板 schema
+- 本地 JSON sink
+- metadata auto
+- Langfuse 索引字段
+
+未实现：
+
+- GitCode/Jira/DTS sink
+- Langfuse API 自动查询
+- 组织级用户映射
+- 单元测试套件