oh-aicoding-tool 0.1.2 → 0.1.4

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

@@ -1,405 +0,0 @@
-# OpenCode 问题采集一阶段工作总结
-
-## 1. 阶段目标
-
-一阶段目标是先跑通 OpenCode 场景下的问题采集最小闭环：
-
-- 在 OpenCode 中提供 `/report-ai-issue` 用户入口。
-- 使用 `subtask: true` 让 subagent 进行轻量模板化，降低主上下文污染。
-- 只上传问题模板字段和元信息索引，不上传完整日志、diff、transcript、源码或工具输出。
-- 通过 `session_id`、`trace_id`、`langfuse_url` 关联 Langfuse 中的完整会话和日志。
-- 将核心能力沉淀为可维护、可升级的 `ohai-report` CLI 模块。
-
-## 2. 已完成内容
-
-### 2.1 OpenCode 命令入口
-
-已新增：
-
-```text
-.opencode/commands/report-ai-issue.md
-```
-
-能力：
-
-- 提供 `/report-ai-issue <用户问题>` 入口。
-- 配置 `subtask: true`，让模板化过程在 subagent 中执行。
-- 明确约束 subagent 只基于用户输入生成模板字段。
-- 禁止读取完整日志、diff、源码、transcript。
-- 调用 `ohai-report` CLI 完成落盘。
-- 主会话最终只返回 `已上报：<issue_id>`。
-
-### 2.2 OpenCode Plugin 薄适配器
-
-已新增：
-
-```text
-.opencode/plugins/oh-ai-report.ts
-```
-
-能力：
-
-- 监听 OpenCode session/command 事件。
-- 尝试刷新本地 metadata。
-- 提供可选 `report_ai_issue` custom tool。
-- 不采集、不上传完整日志。
-
-### 2.3 `ohai-report` CLI 模块化
-
-已将原型 CLI 拆分为模块化结构：
-
-```text
-tools/ohai-report/
-  ohai_report.py
-  README.md
-  examples/
-    issue-input.json
-  schemas/
-    report_issue.schema.json
-  ohai_report/
-    __init__.py
-    __main__.py
-    cli.py
-    schema.py
-    metadata.py
-    payload.py
-    workspace.py
-    git_context.py
-    sinks/
-      __init__.py
-      base.py
-      local.py
-      gitcode.py
-```
-
-模块职责：
-
-| 模块 | 职责 |
-| --- | --- |
-| `ohai_report.py` | 兼容入口，保持现有调用路径不变 |
-| `cli.py` | 解析命令，编排校验、metadata、payload、sink |
-| `schema.py` | 读取 schema 并执行校验 |
-| `schemas/report_issue.schema.json` | 维护问题模板字段、枚举和长度约束 |
-| `metadata.py` | 解析 session、trace、user、git context |
-| `payload.py` | 组装标准 ReportPayload |
-| `sinks/local.py` | 本地 JSON 落盘 |
-| `sinks/gitcode.py` | GitCode sink 预留扩展点 |
-
-### 2.4 问题模板 schema 外置
-
-已新增：
-
-```text
-tools/ohai-report/schemas/report_issue.schema.json
-```
-
-当前字段：
-
-```text
-title
-category
-summary
-expected_behavior
-actual_behavior
-severity
-user_description
-```
-
-当前枚举：
-
-```text
-category:
-  模型输出错误
-  工具调用失败
-  Skill 缺陷
-  上下文缺失
-  环境问题
-  其他
-
-severity:
-  P0
-  P1
-  P2
-  P3
-```
-
-维护收益：
-
-- 新增字段优先改 schema。
-- subagent prompt 与 schema 对齐即可。
-- CLI 支持 `--field key=value` 和 `--issue-file`，便于扩展字段。
-- 不需要频繁修改 sink 或 payload 逻辑。
-
-### 2.5 本地 Issue 落盘
-
-当前 issue 输出目录：
-
-```text
-.ohai-report/issues/
-.ohai-report/latest.json
-.ohai-report/metadata.json
-```
-
-`.ohai-report/` 已加入 `.gitignore`，避免运行产物误提交。
-
-当前 payload 示例结构：
-
-```json
-{
-  "issue_id": "AI-DEV-20260508144314435120",
-  "created_at": "2026-05-08T14:43:14+08:00",
-  "source": "opencode",
-  "agent": "opencode",
-  "session_id": "opencode-session-arch",
-  "trace_id": "trace-arch",
-  "langfuse_url": "https://langfuse.example.com/project/demo/traces/trace-arch",
-  "user": {
-    "id": "Geralt",
-    "name": "Geralt",
-    "team": ""
-  },
-  "issue": {
-    "title": "Schema固定参数验证",
-    "category": "其他",
-    "summary": "验证固定参数兼容",
-    "expected_behavior": "生成 payload",
-    "actual_behavior": "生成 JSON",
-    "severity": "P3",
-    "user_description": "测试固定参数路径"
-  },
-  "privacy": {
-    "uploads_logs": false,
-    "uploads_diff": false,
-    "uploads_transcript": false
-  },
-  "status": "created-local"
-}
-```
-
-## 3. 使用方式
-
-### 3.1 在 OpenCode 中使用
-
-在项目根目录启动 OpenCode：
-
-```powershell
-cd C:\Users\Geralt\Desktop\problem_collect
-opencode
-```
-
-在 OpenCode 中输入：
-
-```text
-/report-ai-issue hdc 远程服务器无法连接本地开发板
-```
-
-预期主会话只返回：
-
-```text
-已上报：AI-DEV-xxxx
-```
-
-### 3.2 命令行创建 Issue
-
-```powershell
-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
-```
-
-### 3.3 更新 metadata
-
-```powershell
-python tools/ohai-report/ohai_report.py metadata update `
-  --source opencode `
-  --session-id "opencode-session-xxx" `
-  --trace-id "langfuse-trace-xxx" `
-  --langfuse-url "https://langfuse.example.com/project/xxx/traces/xxx" `
-  --json
-```
-
-### 3.4 使用 issue 文件
-
-```powershell
-python tools/ohai-report/ohai_report.py create `
-  --source opencode `
-  --issue-file tools/ohai-report/examples/issue-input.json `
-  --metadata auto `
-  --quiet `
-  --json
-```
-
-## 4. 验证结果
-
-已完成以下验证：
-
-```text
-python -m py_compile ...
-python tools/ohai-report/ohai_report.py metadata update ...
-python tools/ohai-report/ohai_report.py create ... 固定参数
-python tools/ohai-report/ohai_report.py create ... --field scenario=HDC
-python tools/ohai-report/ohai_report.py create ... --issue-file tools/ohai-report/examples/issue-input.json
-```
-
-验证结论：
-
-- CLI 拆包后兼容原调用路径。
-- `metadata update` 可正常写入 `.ohai-report/metadata.json`。
-- `create` 可正常生成 `.ohai-report/issues/<issue_id>.json`。
-- `--field` 可支持未来扩展字段。
-- `--issue-file` 可避免 Windows shell 下 JSON 引号问题。
-- issue_id 已升级为微秒级，避免同一秒内重复创建覆盖文件。
-- payload 不包含完整日志、diff、transcript、源码或工具输出。
-
-## 5. 当前架构特点
-
-### 5.1 低上下文污染
-
-通过 OpenCode command 的 `subtask: true` 降低主上下文污染。
-
-预期主上下文只保留：
-
-```text
-用户：/report-ai-issue xxx
-助手：已上报：AI-DEV-xxx
-```
-
-### 5.2 日志链路解耦
-
-Issue 不保存日志正文，只保存：
-
-```text
-session_id
-trace_id
-langfuse_url
-```
-
-完整日志、工具调用、trace 和 session 通过 Langfuse 查询。
-
-### 5.3 Agent 与后端解耦
-
-OpenCode 只作为 adapter：
-
-```text
-OpenCode command/plugin
-  -> ohai-report CLI
-  -> sink
-```
-
-未来支持 Claude Code、Codex 或其他 Agent 时，只需新增 adapter，不需要重做上报核心。
-
-### 5.4 Sink 可替换
-
-当前使用本地 JSON sink：
-
-```text
-tools/ohai-report/ohai_report/sinks/local.py
-```
-
-后续可增加：
-
-```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
-```
-
-## 6. 一阶段产物清单
-
-| 文件 | 说明 |
-| --- | --- |
-| `.opencode/commands/report-ai-issue.md` | OpenCode `/report-ai-issue` 入口 |
-| `.opencode/plugins/oh-ai-report.ts` | OpenCode plugin 薄适配器 |
-| `tools/ohai-report/ohai_report.py` | CLI 兼容入口 |
-| `tools/ohai-report/ohai_report/cli.py` | CLI 编排 |
-| `tools/ohai-report/ohai_report/schema.py` | schema 读取与校验 |
-| `tools/ohai-report/schemas/report_issue.schema.json` | 问题模板字段定义 |
-| `tools/ohai-report/ohai_report/metadata.py` | metadata 解析 |
-| `tools/ohai-report/ohai_report/payload.py` | payload 组装 |
-| `tools/ohai-report/ohai_report/sinks/local.py` | 本地 JSON sink |
-| `tools/ohai-report/ohai_report/sinks/gitcode.py` | GitCode sink 预留 |
-| `tools/ohai-report/examples/issue-input.json` | issue-file 示例 |
-| `tools/ohai-report/README.md` | CLI 使用说明 |
-| `docs/opencode-ai-issue-collection-best-practices.md` | OpenCode 方案文档 |
-| `docs/opencode-ai-issue-collection-architecture.md` | 正式架构设计文档 |
-| `.gitignore` | 忽略运行产物 |
-
-## 7. 未完成事项
-
-一阶段尚未实现：
-
-- GitCode/Jira/DTS 真实 Issue API。
-- Langfuse API 自动查询和 trace 校验。
-- 组织级用户/团队映射。
-- 单元测试套件。
-- OpenCode plugin 在真实 OpenCode 环境中的端到端验证。
-- schema 与 command prompt 自动同步生成。
-
-## 8. 下一阶段建议
-
-### 8.1 接入真实 Issue 后端
-
-优先实现：
-
-```text
-tools/ohai-report/ohai_report/sinks/gitcode.py
-```
-
-并增加 CLI 参数：
-
-```text
---sink local
---sink gitcode
-```
-
-### 8.2 增加单元测试
-
-建议覆盖：
-
-- schema 校验
-- metadata merge
-- payload 生成
-- local sink
-- issue_id 唯一性
-- 不上传日志的 privacy 约束
-
-### 8.3 增强 Langfuse 集成
-
-建议新增：
-
-```text
-tools/ohai-report/ohai_report/observability/langfuse.py
-```
-
-用于：
-
-- 根据 session_id 生成 langfuse_url。
-- 校验 trace 是否存在。
-- 补齐 trace 元信息。
-
-### 8.4 schema 驱动 prompt
-
-后续可以由 `report_issue.schema.json` 自动生成 subagent prompt 中的字段说明，避免字段定义和 prompt 不一致。
-
-## 9. 阶段结论
-
-一阶段已经完成 OpenCode 问题采集的最小可用闭环：
-
-```text
-/report-ai-issue
-  -> subagent LLM 模板化
-  -> ohai-report CLI 校验和组装 payload
-  -> local sink 落盘
-  -> Langfuse 索引关联
-```
-
-当前实现已经具备模块化边界，后续可以按 sink、schema、metadata、adapter 独立升级，不需要重做整体链路。

package/opencode-ohai-report/examples/issue_output.json

@@ -1,4 +0,0 @@
-{
-  "title": "minmax 模型在代码生成过程中误删已有函数",
-  "content": "## AI 使用问题反馈\n\n### 标题\nminmax 模型在代码生成过程中误删已有函数\n\n### 问题摘要\n用户在使用 minmax 模型进行代码相关任务时，观察到模型会错误地删除已有的函数，导致代码丢失。\n\n### 原始描述\nminmax模型会误删函数\n\n### 使用场景\n- 工具：`minmax`\n- 场景：`coding`\n- 任务类型：`unknown`\n- 工作流阶段：`unknown`\n- 受影响角色：`developer`\n\n### 问题分类\n- 主分类：`model-capability`\n- 次分类：`none`\n- 分类置信度：`medium`\n- 判断依据：用户描述表明模型在生成或修改代码时，未能正确识别和保留已有函数，属于代码理解和输出质量控制问题。\n\n### 标签\n- `tool:minmax`\n- `category:model-capability`\n- `scenario:coding`\n- `task:unknown`\n- `issue:wrong-file-edit`\n- `issue:bad-output-quality`\n- `capability:coding`\n- `capability:context-management`\n- `severity:high`\n- `frequency:unknown`\n\n### 影响\n该问题可能导致已有功能代码被意外删除，造成代码丢失、功能回退，增加代码审查和恢复成本，并降低开发者对 AI 代码生成能力的信任。\n\n### 可能原因\n- 模型可能未充分理解代码上下文，将已有函数误判为冗余代码。\n- 模型可能在尝试修复或重构时，未遵循最小化修改原则。\n- 提示词或上下文可能未明确强调保留现有函数。\n\n### 改进方向\n- 需要增强模型在代码编辑时的上下文理解能力，确保能够区分已有功能和待修改部分。\n- 在 AI 辅助代码生成流程中增加代码变更保护机制，避免未经确认的删除操作。\n- 优化提示词模板，明确约束模型保留现有函数。\n\n### 建议补充信息\n- 具体使用的 minmax 模型版本和调用方式。\n- 被误删的函数类型和业务重要性。\n- 发生误删时的具体任务场景（如重构、补全、Bug 修复等）。\n- 该问题出现的频率（偶发还是频繁）。\n- 是否有相关的代码 diff 或复现步骤。\n\n### 建议分派方向\n模型能力、产品体验、提示词/流程设计"
-}

package/opencode-ohai-report/package.json

@@ -1,40 +0,0 @@
-{
-  "name": "opencode-ohai-report",
-  "version": "0.1.0",
-  "private": false,
-  "type": "module",
-  "description": "Install and run the oh-ai-report issue feedback plugin for OpenCode and Claude Code.",
-  "bin": {
-    "opencode-ohai-report": "bin/cli.js",
-    "ohai-report": "bin/cli.js"
-  },
-  "files": [
-    "bin",
-    ".opencode",
-    ".claude",
-    "scripts/*.py",
-    "scripts/*.ps1",
-    "scripts/*.sh",
-    "tools/ohai-report/ohai_report.py",
-    "tools/ohai-report/ohai_report/**/*.py",
-    "tools/ohai-report/schemas",
-    "tools/ohai-report/examples",
-    "tools/ohai-report/README.md",
-    "README.md",
-    "docs",
-    "examples"
-  ],
-  "scripts": {
-    "start": "node bin/cli.js",
-    "pack:check": "npm pack --dry-run",
-    "test": "cd tools/ohai-report && python -m unittest discover -s tests -p \"test_*.py\" -v"
-  },
-  "keywords": [
-    "opencode",
-    "claude-code",
-    "issue-report",
-    "ohai-report"
-  ],
-  "license": "UNLICENSED",
-  "dependencies": {}
-}

package/opencode-ohai-report/scripts/claude_report_hook.py

@@ -1,257 +0,0 @@
-#!/usr/bin/env python3
-"""Claude Code hook for /report-ai-issue.
-
-The hook reads the Claude hook event as bytes so Windows console code pages
-cannot mojibake UTF-8 prompts before JSON parsing.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import pathlib
-import subprocess
-import sys
-from typing import Any
-
-
-COMMAND_NAME = "report-ai-issue"
-AUTO_REPORT_MODES = {"auto", "submit", "legacy"}
-
-
-def emit(value: dict[str, Any]) -> int:
-    print(json.dumps(value, ensure_ascii=True, separators=(",", ":")))
-    return 0
-
-
-def passthrough() -> int:
-    return emit({})
-
-
-def hook_mode() -> str:
-    return os.environ.get("OHAI_CLAUDE_REPORT_HOOK_MODE", "prompt").strip().lower()
-
-
-def safe_text(value: str) -> str:
-    return value.encode("utf-8", errors="replace").decode("utf-8")
-
-
-def shorten(value: str, limit: int) -> str:
-    text = " ".join(safe_text(value).strip().split())
-    if len(text) <= limit:
-        return text
-    return text[: max(0, limit - 1)].rstrip() + "..."
-
-
-def default_issue_fields(description: str) -> dict[str, str]:
-    text = safe_text(description).strip() or "No description provided."
-    title = shorten(text.splitlines()[0], 80) or "AI issue report"
-    summary = shorten(text, 800)
-    return {
-        "title": title,
-        "category": "\u5176\u4ed6",
-        "summary": summary,
-        "expected_behavior": "The assistant should handle the request correctly.",
-        "actual_behavior": shorten(text, 400),
-        "severity": "P2",
-        "user_description": shorten(text, 2000),
-        "agent": "claude",
-        "level": "P2",
-    }
-
-
-def resolve_cli(cwd: pathlib.Path) -> pathlib.Path | None:
-    configured = os.environ.get("OHAI_REPORT_CLI", "").strip()
-    if configured:
-        path = pathlib.Path(configured)
-        if not path.is_absolute():
-            path = cwd / path
-        return path if path.exists() else None
-
-    fallback = cwd / "tools" / "ohai-report" / "ohai_report.py"
-    return fallback if fallback.exists() else None
-
-
-def cli_repo_root(cli: pathlib.Path) -> pathlib.Path | None:
-    marker = pathlib.Path("tools") / "ohai-report" / "ohai_report.py"
-    try:
-        if pathlib.Path(*cli.parts[-3:]) == marker:
-            return cli.parents[2]
-    except IndexError:
-        return None
-    return None
-
-
-def resolve_report_cwd(cwd: pathlib.Path, cli: pathlib.Path) -> pathlib.Path:
-    configured = os.environ.get("OHAI_REPORT_CWD", "").strip()
-    if configured:
-        return pathlib.Path(configured).expanduser().resolve()
-
-    try:
-        if cwd == pathlib.Path.home().resolve():
-            root = cli_repo_root(cli)
-            if root is not None:
-                return root
-    except OSError:
-        pass
-    return cwd
-
-
-def resolve_sink() -> str:
-    sink = os.environ.get("OHAI_REPORT_SINK", "webhook").strip().lower()
-    if sink not in {"local", "webhook", "gitcode"}:
-        return "webhook"
-    return sink
-
-
-def extract_json_line(stdout: str) -> dict[str, Any]:
-    for line in reversed(stdout.splitlines()):
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            value = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        if isinstance(value, dict):
-            return value
-    return {}
-
-
-def read_stdin_text() -> str:
-    stream = getattr(sys.stdin, "buffer", sys.stdin)
-    data = stream.read()
-    if isinstance(data, str):
-        return data
-    if not data.strip():
-        return ""
-
-    encodings = ["utf-8-sig"]
-    if sys.stdin.encoding:
-        encodings.append(sys.stdin.encoding)
-    encodings.append("gb18030")
-
-    for encoding in encodings:
-        try:
-            return data.decode(encoding)
-        except UnicodeDecodeError:
-            continue
-    return data.decode("utf-8", errors="replace")
-
-
-def emit_prompt_context(cwd: pathlib.Path, cli: pathlib.Path | None, sink: str, session_id: str) -> int:
-    cli_text = str(cli) if cli is not None else "not found; resolve OHAI_REPORT_CLI or repo-local tools/ohai-report/ohai_report.py"
-    context = "\n".join(
-        [
-            "ohai-report hook note:",
-            "- Do not let the hook submit this report automatically.",
-            "- First read and follow the expanded /report-ai-issue command instructions.",
-            "- Use the current LLM to classify the user's description and fill the required issue fields.",
-            "- Then run the ohai-report CLI yourself and parse its final JSON output before replying.",
-            f"- Resolved CLI hint: {cli_text}",
-            f"- Suggested working directory: {cwd}",
-            f"- Suggested sink: {sink}",
-            f"- Current Claude session_id: {session_id or '(not provided by hook payload)'}",
-            "- When running the ohai-report CLI, pass this session through the process environment as OHAI_SESSION_ID.",
-        ]
-    )
-    return emit(
-        {
-            "hookSpecificOutput": {
-                "hookEventName": "UserPromptExpansion",
-                "additionalContext": context,
-            }
-        }
-    )
-
-
-def configure_stdio() -> None:
-    try:
-        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-    except AttributeError:
-        pass
-
-
-def main() -> int:
-    configure_stdio()
-    raw = read_stdin_text()
-    if not raw.strip():
-        return passthrough()
-
-    try:
-        payload = json.loads(raw)
-    except json.JSONDecodeError:
-        return passthrough()
-
-    if not isinstance(payload, dict):
-        return passthrough()
-
-    if payload.get("command_name") != COMMAND_NAME:
-        return passthrough()
-
-    description = str(payload.get("command_args") or "")
-    session_id = str(payload.get("session_id") or "")
-    cwd = pathlib.Path(str(payload.get("cwd") or os.getcwd())).resolve()
-    cli = resolve_cli(cwd)
-    sink = resolve_sink()
-
-    if hook_mode() not in AUTO_REPORT_MODES:
-        report_cwd = resolve_report_cwd(cwd, cli) if cli is not None else cwd
-        return emit_prompt_context(report_cwd, cli, sink, session_id)
-
-    if cli is None:
-        return emit(
-            {
-                "decision": "block",
-                "reason": "ohai-report CLI not found. Please set OHAI_REPORT_CLI.",
-            }
-        )
-
-    report_cwd = resolve_report_cwd(cwd, cli)
-    issue = default_issue_fields(description)
-    cmd = [
-        sys.executable,
-        str(cli),
-        "create",
-        "--source",
-        "claude",
-        "--issue-json",
-        json.dumps(issue, ensure_ascii=True),
-        "--metadata",
-        "auto",
-        "--sink",
-        sink,
-        "--cwd",
-        str(report_cwd),
-        "--quiet",
-        "--json",
-    ]
-    env = os.environ.copy()
-    env["PYTHONUTF8"] = "1"
-    env["PYTHONIOENCODING"] = "utf-8"
-    if session_id:
-        env["OHAI_SESSION_ID"] = session_id
-
-    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", env=env)
-    if proc.returncode != 0:
-        reason = (proc.stderr or proc.stdout or "unknown error").strip()
-        return emit({"decision": "block", "reason": f"ohai-report failed: {reason}"})
-
-    result = extract_json_line(proc.stdout)
-    issue_id = result.get("issue_id") or "unknown"
-    url = result.get("gitcode_url") or result.get("webhook_url") or ""
-    suffix = f" {url}" if url else ""
-    return emit(
-        {
-            "decision": "block",
-            "reason": (
-                f"Issue reported: {issue_id}{suffix}. "
-                "The ohai-report CLI has handled this request."
-            ),
-        }
-    )
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())