oh-aicoding-tool 0.1.2 → 0.1.5

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

@@ -1,313 +0,0 @@
-# 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 自动查询
-- 组织级用户映射
-- 单元测试套件