oh-aicoding-tool 0.1.0

package/opencode-ohai-report/tools/ohai-report/ohai_report/cli.py

@@ -0,0 +1,319 @@
+"""Command line interface for ohai-report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .metadata import update_metadata
+from .payload import build_issue_payload
+from .schema import CreateIssueInput, MetadataUpdateInput, issue_fields, validate_create_input
+from .sinks.gitcode import GitCodeConfig, GitCodeIssueSink, GitCodeSinkError, apply_gitcode_result
+from .sinks.local import LocalIssueSink
+from .sinks.webhook import WebhookConfig, WebhookIssueSink, WebhookSinkError, apply_webhook_result
+from .workspace import resolve_workspace_root
+
+
+def create_issue(args: argparse.Namespace) -> int:
+    issue = build_issue_from_args(args)
+    create_input = CreateIssueInput(
+        source=args.source,
+        issue=issue,
+        metadata=args.metadata,
+    )
+    errors = validate_create_input(create_input)
+    if errors:
+        print(json.dumps({"ok": False, "errors": errors}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+    root = resolve_workspace_root(getattr(args, "cwd", "") or "")
+    payload = build_issue_payload(root, create_input)
+    gitcode_result = None
+    webhook_result = None
+
+    try:
+        if args.sink == "gitcode":
+            cfg = GitCodeConfig.from_env(
+                owner=(args.gitcode_owner or "").strip() or None,
+                repo=(args.gitcode_repo or "").strip() or None,
+                token=(args.gitcode_token or "").strip() or None,
+                api_base=(args.gitcode_api_base or "").strip() or None,
+                labels=(args.gitcode_labels if args.gitcode_labels is not None else None),
+                label_maintainer=True if getattr(args, "gitcode_label_maintainer", False) else None,
+            )
+            gitcode_result = GitCodeIssueSink(cfg).save(payload)
+            payload = apply_gitcode_result(payload, gitcode_result)
+            result = LocalIssueSink(root).save(payload)
+        elif args.sink == "webhook":
+            sec_cli = (args.webhook_secret or "").strip()
+            wh_cfg = WebhookConfig.from_env(
+                url=(args.webhook_url or "").strip() or None,
+                secret=sec_cli if sec_cli else None,
+                timeout=args.webhook_timeout,
+            )
+            webhook_result = WebhookIssueSink(wh_cfg).save(
+                payload,
+                webhook_labels_cli=args.webhook_labels,
+            )
+            payload = apply_webhook_result(payload, webhook_result)
+            result = LocalIssueSink(root).save(payload)
+        else:
+            result = LocalIssueSink(root).save(payload)
+    except (GitCodeSinkError, WebhookSinkError) as exc:
+        err: dict[str, Any] = {"ok": False, "error": str(exc)}
+        if exc.status_code:
+            err["status_code"] = exc.status_code
+        if exc.body:
+            err["body"] = exc.body[:4096]
+        print(json.dumps(err, ensure_ascii=False), file=sys.stderr)
+        return 3
+
+    output: dict[str, Any] = {
+        "ok": True,
+        "issue_id": payload["issue_id"],
+        "session_id": payload.get("session_id", ""),
+        "trace_id": payload["trace_id"],
+        "observation_id": payload.get("observation_id", ""),
+        "user_id": payload.get("user_id", ""),
+        "user_email": payload.get("user_email", ""),
+        "message_id": payload.get("message_id", ""),
+        "opencode_subagent": payload.get("opencode_subagent", ""),
+        "langfuse_url": payload["langfuse_url"],
+        "path": str(result.path) if result.path else "",
+        "sink": args.sink,
+    }
+    if gitcode_result and gitcode_result.url:
+        output["gitcode_url"] = gitcode_result.url
+        num = gitcode_result.extra.get("number")
+        if num is not None:
+            output["gitcode_number"] = num
+    if webhook_result and webhook_result.url:
+        output["webhook_url"] = webhook_result.url
+
+    if args.json:
+        print(json.dumps(output, ensure_ascii=False))
+    elif args.quiet:
+        print(payload["issue_id"])
+    else:
+        suffix = ""
+        if gitcode_result and gitcode_result.url:
+            suffix = f"（GitCode: {gitcode_result.url}）"
+        if webhook_result and webhook_result.url:
+            suffix = f"{suffix}（Webhook: {webhook_result.url}）"
+        print(f"已上报：{payload['issue_id']}{suffix}")
+    return 0
+
+
+def parse_field_overrides(values: list[str]) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise ValueError(f"invalid --field value: {value}")
+        key, item = value.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise ValueError(f"invalid --field key: {value}")
+        fields[key] = item
+    return fields
+
+
+def build_issue_from_args(args: argparse.Namespace) -> dict[str, Any]:
+    fields = issue_fields()
+    issue: dict[str, Any] = {}
+    for name, spec in fields.items():
+        default = spec.get("default")
+        if default is not None:
+            issue[name] = default
+
+    fixed_values = {
+        "title": args.title,
+        "category": args.category,
+        "summary": args.summary,
+        "expected_behavior": args.expected_behavior,
+        "actual_behavior": args.actual_behavior,
+        "severity": args.severity,
+        "user_description": args.user_description,
+    }
+    issue.update({key: value for key, value in fixed_values.items() if value})
+
+    if args.issue_json:
+        try:
+            json_issue = json.loads(args.issue_json)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"invalid --issue-json: {exc}") from exc
+        if not isinstance(json_issue, dict):
+            raise SystemExit("invalid --issue-json: expected object")
+        issue.update(json_issue)
+
+    if args.issue_file:
+        try:
+            with open(args.issue_file, "r", encoding="utf-8") as fp:
+                file_issue = json.load(fp)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise SystemExit(f"invalid --issue-file: {exc}") from exc
+        if not isinstance(file_issue, dict):
+            raise SystemExit("invalid --issue-file: expected object")
+        issue.update(file_issue)
+
+    try:
+        issue.update(parse_field_overrides(args.field or []))
+    except ValueError as exc:
+        raise SystemExit(str(exc)) from exc
+    return issue
+
+
+def metadata_update(args: argparse.Namespace) -> int:
+    root = resolve_workspace_root(getattr(args, "cwd", "") or "")
+    update_input = MetadataUpdateInput(
+        source=args.source,
+        session_id=args.session_id,
+        trace_id=args.trace_id,
+        langfuse_url=args.langfuse_url,
+        observation_id=args.observation_id,
+        user_id=args.user_id,
+        message_id=args.message_id,
+        opencode_subagent=args.opencode_subagent,
+        model=args.model,
+        clear_message_subagent=args.drop_message_and_subagent,
+        cwd=args.cwd,
+    )
+    path = update_metadata(root, update_input)
+    if args.json:
+        print(json.dumps({"ok": True, "metadata_path": str(path)}, ensure_ascii=False))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ohai-report")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    create = subparsers.add_parser("create", help="Create a local AI issue report")
+    create.add_argument("--source", default="opencode")
+    create.add_argument("--title", default="")
+    create.add_argument("--category", default="")
+    create.add_argument("--summary", default="")
+    create.add_argument("--expected-behavior", dest="expected_behavior", default="")
+    create.add_argument("--actual-behavior", dest="actual_behavior", default="")
+    create.add_argument("--severity", default="P2")
+    create.add_argument("--user-description", dest="user_description", default="")
+    create.add_argument("--issue-json", default="", help="JSON object containing issue fields")
+    create.add_argument("--issue-file", default="", help="Path to a JSON file containing issue fields")
+    create.add_argument("--field", action="append", default=[], help="Additional issue field as key=value")
+    create.add_argument("--metadata", default="auto", choices=["auto", "none"])
+    create.add_argument(
+        "--sink",
+        default="local",
+        choices=["local", "gitcode", "webhook"],
+        help="Persistence backend（webhook：POST JSON 到外部建单服务，并仍写入本地 issues）",
+    )
+    create.add_argument(
+        "--gitcode-owner",
+        default="",
+        help="GitCode 仓库 owner（命名空间），缺省读 OHAI_GITCODE_OWNER / GITCODE_OWNER",
+    )
+    create.add_argument(
+        "--gitcode-repo",
+        default="",
+        help="GitCode 仓库名（path），缺省读 OHAI_GITCODE_REPO / GITCODE_REPO",
+    )
+    create.add_argument(
+        "--gitcode-token",
+        default="",
+        help="GitCode access token（建议用环境变量 OHAI_GITCODE_TOKEN）",
+    )
+    create.add_argument(
+        "--gitcode-api-base",
+        default="",
+        help="API 根地址，缺省 https://api.gitcode.com 或 OHAI_GITCODE_API_BASE",
+    )
+    create.add_argument(
+        "--gitcode-labels",
+        default=None,
+        help="逗号分隔标签，可选；或环境变量 OHAI_GITCODE_LABELS",
+    )
+    create.add_argument(
+        "--gitcode-label-maintainer",
+        action="store_true",
+        help="机器人对仓库有 Maintainer：缺失的 tool/model/level/category 等标签会自动创建；"
+        "不设则读 OHAI_GITCODE_LABEL_MAINTAINER；无权限且缺标签时报错",
+    )
+    create.add_argument(
+        "--webhook-url",
+        default="",
+        help="Webhook 地址；缺省先读 WEBHOOK_URL/OHAI_WEBHOOK_URL，再回退 webhook_defaults.DEFAULT_WEBHOOK_URL",
+    )
+    create.add_argument(
+        "--webhook-secret",
+        default="",
+        help="可选，X-Webhook-Secret；不设则读 OHAI_WEBHOOK_SECRET / WEBHOOK_SECRET",
+    )
+    create.add_argument(
+        "--webhook-timeout",
+        type=float,
+        default=None,
+        help="请求超时秒数；缺省读 OHAI_WEBHOOK_TIMEOUT / WEBHOOK_TIMEOUT，否则 45",
+    )
+    create.add_argument(
+        "--webhook-labels",
+        default=None,
+        help="逗号分隔标签名，POST JSON 的 labels 数组；传入则覆盖 issue.labels 与 OHAI_WEBHOOK_LABELS 合并结果",
+    )
+    create.add_argument(
+        "--cwd",
+        default="",
+        help="仓库根目录（写入 .ohai-report/；默认当前工作目录）。OpenCode 插件应传会话 project 根。",
+    )
+    create.add_argument("--quiet", action="store_true")
+    create.add_argument("--json", action="store_true")
+    create.set_defaults(func=create_issue)
+
+    metadata = subparsers.add_parser("metadata", help="Manage local metadata")
+    metadata_sub = metadata.add_subparsers(dest="metadata_command", required=True)
+    update = metadata_sub.add_parser("update", help="Update local metadata indexes")
+    update.add_argument("--source", default="opencode")
+    update.add_argument("--session-id", default="")
+    update.add_argument("--trace-id", default="")
+    update.add_argument("--langfuse-url", default="")
+    update.add_argument(
+        "--observation-id",
+        default="",
+        help="当前 Langfuse observation / span id（或环境 LANGFUSE_OBSERVATION_ID）",
+    )
+    update.add_argument(
+        "--user-id",
+        default="",
+        help="覆盖写入 metadata.user.id（或依赖 LANGFUSE_USER_ID / OHAI_USER_ID 环境）",
+    )
+    update.add_argument(
+        "--message-id",
+        default="",
+        help="OpenCode 当前消息 ID（或环境 OPENCODE_MESSAGE_ID / OHAI_MESSAGE_ID）",
+    )
+    update.add_argument(
+        "--opencode-subagent",
+        default="",
+        help="OpenCode context.agent（或环境 OHAI_OPENCODE_SUBAGENT / OPENCODE_SUBAGENT）",
+    )
+    update.add_argument(
+        "--model",
+        default="",
+        help="当前 LLM 模型标识（OpenCode 会话 info.model.id 等；或环境 OPENCODE_MODEL / OHAI_MODEL）",
+    )
+    update.add_argument(
+        "--drop-message-and-subagent",
+        action="store_true",
+        help="清空 metadata 中的 message_id 与 opencode_subagent（OpenCode 插件侧不再采集时使用）",
+    )
+    update.add_argument("--cwd", default="")
+    update.add_argument("--json", action="store_true")
+    update.set_defaults(func=metadata_update)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)

package/opencode-ohai-report/tools/ohai-report/ohai_report/git_context.py

@@ -0,0 +1,32 @@
+"""Git context discovery."""
+
+from __future__ import annotations
+
+import pathlib
+import subprocess
+
+
+def run_git(args: list[str], root: pathlib.Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=root,
+            text=True,
+            capture_output=True,
+            timeout=2,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return ""
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+def git_context(root: pathlib.Path) -> dict[str, str]:
+    return {
+        "repo": run_git(["config", "--get", "remote.origin.url"], root),
+        "branch": run_git(["rev-parse", "--abbrev-ref", "HEAD"], root),
+        "commit": run_git(["rev-parse", "--short", "HEAD"], root),
+        "cwd": str(root),
+    }

package/opencode-ohai-report/tools/ohai-report/ohai_report/gitcode_defaults.py

@@ -0,0 +1,14 @@
+"""GitCode 默认命名空间与仓库名（非密钥，可写死在此避免每次传 CLI 参数）。
+
+Access Token **不要**写进仓库：在本机用户或 OpenCode 启动环境中配置一次即可：
+  OHAI_GITCODE_TOKEN 或 GITCODE_ACCESS_TOKEN
+
+仍可用环境变量 OHAI_GITCODE_OWNER / OHAI_GITCODE_REPO 覆盖下列默认值。
+"""
+
+from __future__ import annotations
+
+# 在此填写你的 GitCode/Gitee 仓库路径（与 API 中 owner、repo 一致）；仍可用环境变量覆盖。
+# 默认指向 OpenHarmony Insight 反馈仓；Token 切勿写入仓库，请用 OHAI_GITCODE_TOKEN 等环境变量。
+DEFAULT_GITCODE_OWNER: str = "openharmonyinsight"
+DEFAULT_GITCODE_REPO: str = "ai-dev-feedback"

package/opencode-ohai-report/tools/ohai-report/ohai_report/issue_markdown.py

@@ -0,0 +1,313 @@
+"""Issue 正文 Markdown：与「AI 使用问题反馈」模板对齐（GitCode / Webhook 共用）。"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .metadata import is_placeholder_tracing_user_id
+
+
+def _pick(issue: dict[str, Any], key: str, default: str = "unknown") -> str:
+    v = issue.get(key)
+    if v is None or (isinstance(v, str) and not str(v).strip()):
+        return default
+    return str(v).strip()
+
+
+def _pick_optional_display(issue: dict[str, Any], key: str) -> str:
+    """可选展示字段：空或 LLM 填的 unknown 统一为「未填写」，避免像错误信息。"""
+    v = issue.get(key)
+    if v is None or (isinstance(v, str) and not str(v).strip()):
+        return "（未填写）"
+    s = str(v).strip()
+    if s.lower() == "unknown":
+        return "（未填写）"
+    return s
+
+
+def _first_nonempty_str(*vals: object) -> str:
+    for v in vals:
+        if v is None:
+            continue
+        t = str(v).strip()
+        if t:
+            return t
+    return "unknown"
+
+
+def _looks_like_email(s: str) -> bool:
+    t = (s or "").strip()
+    if "@" not in t or len(t) < 5:
+        return False
+    local, _, domain = t.partition("@")
+    if not local or not domain or "." not in domain:
+        return False
+    return True
+
+
+def _log_user_email_display(raw: str) -> str:
+    """日志信息「公司邮箱」：非邮箱形态（如 OS 登录名）不展示。"""
+    t = (raw or "").strip()
+    if not t or t.lower() == "unknown":
+        return "（未采集）"
+    if _looks_like_email(t):
+        return t
+    return "（未采集）"
+
+
+def _log_correlation_display(raw: str, *, is_user_id: bool = False) -> str:
+    """日志信息行：无有效采集时统一「未采集」，不把占位数字当真实 user。"""
+    t = (raw or "").strip()
+    if not t or t.lower() == "unknown":
+        return "（未采集）"
+    if is_user_id and is_placeholder_tracing_user_id(t):
+        return "（未采集）"
+    return t
+
+
+_ALLOWED_AGENTS = frozenset({"opencode", "claude", "codex"})
+
+
+_CATEGORY_LABEL_MAP: dict[str, str] = {
+    "模型输出错误": "model-error",
+    "工具调用失败": "tool-error",
+    "Skill 缺陷": "skill-bug",
+    "上下文缺失": "context-missing",
+    "环境问题": "env-issue",
+    "其他": "other",
+}
+
+
+def _pick_agent(issue: dict[str, Any], payload: dict[str, Any]) -> str:
+    """标签 agent：issue 优先；否则用上报 source（如 opencode）。"""
+    raw = issue.get("agent")
+    if raw is not None and str(raw).strip():
+        v = str(raw).strip().lower()
+        if v in _ALLOWED_AGENTS:
+            return v
+    legacy = issue.get("tool")
+    if legacy is not None and str(legacy).strip():
+        v = str(legacy).strip().lower()
+        if v in _ALLOWED_AGENTS:
+            return v
+    src = str(payload.get("source") or "").strip().lower()
+    if src in _ALLOWED_AGENTS:
+        return src
+    return "（未填写）"
+
+
+def _normalize_p_level(s: str) -> str:
+    """将标签 level 规范为 P0–P3。"""
+    t = str(s).strip().upper()
+    if t in ("P0", "P1", "P2", "P3"):
+        return t
+    if t in ("0", "1", "2", "3"):
+        return f"P{t}"
+    return t
+
+
+def format_issue_markdown(payload: dict[str, Any]) -> str:
+    """由 payload 生成「AI 使用问题反馈」结构正文（不含完整日志、diff、transcript）。"""
+    issue = payload.get("issue") if isinstance(payload.get("issue"), dict) else {}
+    title = _pick(issue, "title", "")
+    summary = _pick(issue, "summary", "")
+    user_desc = _pick(issue, "user_description", "")
+    category = _pick(issue, "category", "unknown")
+    severity = _pick(issue, "severity", "P2")
+    expected = _pick(issue, "expected_behavior", "")
+    actual = _pick(issue, "actual_behavior", "")
+
+    agent = _pick_agent(issue, payload)
+    scenario = _pick_optional_display(issue, "scenario")
+    task_type = _pick_optional_display(issue, "task_type")
+    workflow_phase = _pick_optional_display(issue, "workflow_phase")
+    affected_role = _pick_optional_display(issue, "affected_role")
+
+    model_raw = _pick(issue, "model", "")
+    model = "（未填写）" if not model_raw.strip() or model_raw.strip().lower() == "unknown" else model_raw.strip()
+
+    raw_level = issue.get("level")
+    if raw_level is None or (isinstance(raw_level, str) and not str(raw_level).strip()):
+        level_display = _normalize_p_level(severity)
+    else:
+        norm = _normalize_p_level(str(raw_level).strip())
+        level_display = norm if norm in ("P0", "P1", "P2", "P3") else _normalize_p_level(severity)
+
+    primary = _pick(issue, "primary_category", category)
+    sub_c = _pick(issue, "sub_category", "none")
+    if sub_c.lower() == "unknown":
+        sub_c = "none"
+    conf = _pick(issue, "classification_confidence", "low")
+    if conf.lower() == "unknown":
+        conf = "low"
+    rationale = _pick(
+        issue,
+        "classification_rationale",
+        "基于用户当前描述归纳；未读取会话日志与工具输出。",
+    )
+
+    impact = _pick(issue, "impact", "")
+    if not impact and (expected or actual):
+        impact = (
+            f"期望侧：{expected or '（未说明）'}；实际侧：{actual or '（未说明）'}。"
+            "若与「问题摘要」重复，请以摘要为准。"
+        )
+    if not impact:
+        impact = "（请结合问题摘要与原始描述评估影响范围。）"
+
+    causes = _pick(issue, "possible_causes", "")
+    improvement = _pick(issue, "improvement_direction", expected or "（待补充）")
+    follow = _pick(
+        issue,
+        "suggested_follow_up",
+        "具体使用场景、模型版本与平台、对比其它模型的表现、可复现步骤与频率。",
+    )
+    dispatch = _pick(issue, "suggested_dispatch", "模型能力、产品体验、待分派")
+    d_low = dispatch.strip().casefold()
+    if d_low.endswith("unknown"):
+        head = dispatch[: -len("unknown")].rstrip("、").strip()
+        dispatch = f"{head}、待分派" if head else "待分派"
+
+    user_obj = payload.get("user") if isinstance(payload.get("user"), dict) else {}
+    raw_email = _first_nonempty_str(
+        issue.get("user_email"),
+        payload.get("user_email"),
+        user_obj.get("email"),
+    )
+    if raw_email == "unknown":
+        raw_email = ""
+    if not raw_email or not _looks_like_email(raw_email):
+        fallback = _first_nonempty_str(payload.get("user_id"), issue.get("user_id"), user_obj.get("id"))
+        if fallback != "unknown" and _looks_like_email(str(fallback)):
+            raw_email = str(fallback).strip()
+    log_user_email = _log_user_email_display(raw_email)
+    raw_sess = _first_nonempty_str(issue.get("session_id"), payload.get("session_id"))
+    log_session_id = _log_correlation_display(raw_sess)
+
+    lines: list[str] = [
+        "## AI 使用问题反馈",
+        "",
+        "### 标题",
+        title or "（无标题）",
+        "",
+        "### 问题摘要",
+        summary or "（无摘要）",
+        "",
+        "### 原始描述",
+        user_desc or "（无原始描述）",
+        "",
+        "### 使用场景",
+        f"- 场景：`{scenario}`",
+        f"- 任务类型：`{task_type}`",
+        f"- 工作流阶段：`{workflow_phase}`",
+        f"- 受影响角色：`{affected_role}`",
+        "",
+        "### 问题分类",
+        f"- 主分类：`{primary}`",
+        f"- 次分类：`{sub_c}`",
+        f"- 分类置信度：`{conf}`",
+        f"- 判断依据：{rationale}",
+        "",
+        "### 标签",
+        f"- `agent:{agent}`",
+        f"- `model:{model}`",
+        f"- `level:{level_display}`",
+        "",
+        "### 影响",
+        impact,
+        "",
+        "### 可能原因",
+    ]
+    if causes:
+        for para in causes.replace("\r\n", "\n").split("\n"):
+            p = para.strip()
+            if p:
+                if p.startswith("- "):
+                    lines.append(p)
+                else:
+                    lines.append(f"- {p}")
+    else:
+        lines.append("- 当前信息不足，具体根因需结合日志与复现信息进一步确认。")
+
+    log_block = [
+        "",
+        "### 日志信息",
+        f"- user_email：`{log_user_email}`",
+        f"- session_id：`{log_session_id}`",
+        "",
+        "_说明：「未采集」表示无有效公司邮箱或会话 ID。邮箱来自 `OHAI_USER_EMAIL` / metadata `user.email` / `--field user_email`；追踪用 `user_id` 仍保存在 Issue JSON 中，**本小节不单独列出**。Langfuse 等关联信息在 JSON 与 metadata 中。`model` 由 OpenCode 插件写入 metadata（`--metadata auto` 时覆盖 issue 中的 model）。_",
+    ]
+
+    lines.extend(
+        [
+            "",
+            "### 改进方向",
+            improvement,
+            "",
+            "### 建议补充信息",
+            follow,
+            "",
+            "### 建议分派方向",
+            dispatch,
+            *log_block,
+        ]
+    )
+    return "\n".join(lines)
+
+
+_LABEL_VALUE_ALIASES = {
+    "模型输出错误": "model-output-error",
+    "工具调用失败": "tool-call-failure",
+    "Skill 缺陷": "skill-defect",
+    "上下文缺失": "context-missing",
+    "环境问题": "environment",
+    "其他": "other",
+    "构建": "build",
+    "编译": "compile",
+}
+
+
+def sanitize_gitcode_label_value(text: str, *, max_len: int = 64) -> str:
+    """Normalize remote labels to compact ASCII values."""
+    s = str(text or "").strip()
+    s = _LABEL_VALUE_ALIASES.get(s, s)
+    s = s.replace(",", " ").replace(";", " ").replace("\n", " ").replace("\r", " ")
+    s = " ".join(s.split())
+    s = s.encode("ascii", errors="ignore").decode("ascii")
+    s = re.sub(r"[^A-Za-z0-9_.-]+", "-", s).strip("-._")
+    if not s:
+        return "unspecified"
+    return s[:max_len] if len(s) <= max_len else s[: max_len - 1] + "…"
+
+
+def derive_gitcode_dimension_labels(payload: dict[str, Any]) -> list[str]:
+    """与正文「### 标签」一致：tool（agent/旧 tool/source）、model、level、问题主分类。"""
+    issue = payload.get("issue") if isinstance(payload.get("issue"), dict) else {}
+    tool_val = _pick_agent(issue, payload)
+    if tool_val == "（未填写）":
+        tool_val = "unspecified"
+    model_raw = _pick(issue, "model", "")
+    if not model_raw.strip() or model_raw.strip().lower() == "unknown":
+        model_disp = "unspecified"
+    else:
+        model_disp = model_raw.strip()
+    severity = _pick(issue, "severity", "P2")
+    raw_level = issue.get("level")
+    if raw_level is None or (isinstance(raw_level, str) and not str(raw_level).strip()):
+        level_display = _normalize_p_level(severity)
+    else:
+        norm = _normalize_p_level(str(raw_level).strip())
+        level_display = norm if norm in ("P0", "P1", "P2", "P3") else _normalize_p_level(severity)
+    category = _pick(issue, "category", "unknown")
+    primary = _pick(issue, "primary_category", category)
+    if primary.lower() == "unknown":
+        primary_disp = "unspecified"
+    else:
+        primary_disp = _CATEGORY_LABEL_MAP.get(primary, primary)
+    return [
+        sanitize_gitcode_label_value(tool_val),
+        sanitize_gitcode_label_value(model_disp),
+        sanitize_gitcode_label_value(level_display),
+        sanitize_gitcode_label_value(primary_disp),
+    ]