codebee 0.1.14 → 0.1.15

package/app/core/zentao.py

@@ -0,0 +1,1302 @@
+# -*- coding: utf-8 -*-
+"""禅道 Bug 自动修复对接：多产品档案 + 排查定责路由 + 转派流转。
+
+数据落盘 <data>/zentao.json（tmp + os.replace 原子写；TUTTI_DATA 环境变量感知）。
+修复走与 /api/tasks 完全相同的链路（store.create_task → store.create_run →
+jobs.enqueue，code 引擎=实现→验证→评审→修复），不自造运行器。调度挂在
+automation._tick（同 publish/auto.fire_due 模式），内部按 interval_hours 节流。
+
+禅道 REST API v1（开源版 15.x+；请求头 Token: <token>）：
+  POST {base}/api.php/v1/tokens               {account, password} → {token}
+  GET  {base}/api.php/v1/products/{pid}/bugs  分页 {bugs:[...], page, total, limit}
+  GET  {base}/api.php/v1/bugs/{id}            单查（回写前确认状态防谎报）
+  POST {base}/api.php/v1/bugs/{id}/resolve    {resolution, resolvedBuild, comment, assignedTo}
+  PUT  {base}/api.php/v1/bugs/{id}            {assignedTo, comment}（转派/失败说明）
+
+产品档案（product_profiles）：每产品一份 {指派过滤, 严重度, 我方端 our_sides,
+后端/前端仓库(workdir/git_rev/verify_command), repo_hints, 负责人 owners,
+模块路由 module_routes}。老版扁平配置（products+单仓库）load 时自动迁移。
+
+排查（_triage）：模块路由按 bug.module 精确匹配优先 → AI 兜底（triage_ai 开时
+modelhub 单次调用，bookmeta 同款配方）→ unknown。判定 side ∈
+backend | frontend | both | not_ours | unknown。
+
+流转规则（转派目标只认排查结论，与 bug 当前 assignedTo 无关——测试提错人也
+照样改派）：
+  我方端问题    → 建修复任务；成功=合并+resolve(fixed)+报告评论+指回报告人
+  双端/我方一端 → 我方端修完（合并落库）后转派另一端负责人+评论，不 resolve
+  纯对方端问题  → 不建任务，直接转派该端负责人+排查结论评论
+  非我方        → 转派报告人（或 owners.not_ours）+评论；只转派不解决
+  unknown       → 不碰 bug，need_manual + 群通知（下轮扫描 bug 仍激活则重排查）
+  修复任务失败  → 评论尝试记录 + 转派该端负责人（模块路由 account > 端负责人）
+
+出网边界（SSRF 防护，_guard_url）：请求目标来自用户自配禅道地址——内网按设计
+放行；强制 http(s)、解析主机并阻断云元数据/链路本地地址、禁跟随重定向。
+"""
+from __future__ import annotations
+
+import html as _html
+import ipaddress
+import json
+import logging
+import os
+import re
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from . import jobs, paths, settings, store, tlsctx
+
+log = logging.getLogger(__name__)
+
+_LOCK = threading.RLock()
+_FILE = paths.DATA_DIR / "zentao.json"
+_STATE = {
+    "config": {},        # 持久配置（_CFG_DEFAULTS）
+    "claims": {},        # str(bug_id) → claim dict（v2：含 triage/tasks）
+    "last_scan": "",
+    "next_scan": "",
+    "last_error": "",
+}
+_LOADED = False
+
+TOKEN_TTL = 23 * 3600
+HTTP_TIMEOUT = 15
+PAGE_LIMIT = 100
+MAX_BUGS = 500
+RESOLVE_MAX_ATTEMPTS = 3
+RETRY_DELAY_MIN = 30
+INTERVAL_MIN, INTERVAL_MAX = 1, 168
+
+SIDES = ("backend", "frontend")
+TRIAGE_SIDES = ("backend", "frontend", "both", "not_ours")   # unknown 单列
+SIDE_CN = {"backend": "后端", "frontend": "前端"}
+
+_CFG_DEFAULTS = {
+    "base_url": "",
+    "account": "",
+    "password": "",
+    "product_profiles": [],    # 产品档案列表（_norm_profile 形状）
+    "auto_resolve": True,
+    "auto_merge": True,
+    "triage_ai": True,         # 模块路由未命中时用 AI 兜底排查
+    "poll_enabled": False,
+    "interval_hours": 2,
+}
+
+_REPO_DEFAULTS = {"workdir": "", "git_rev": "", "verify_command": ""}
+
+_PROFILE_DEFAULTS = {
+    "product": 0,              # 产品 ID（必填唯一）
+    "assigned_to": "",         # 只认领指派给该账号的 bug；空=不按指派过滤
+    "severity_cap": 0,         # 严重度上限（1 最严重）；0=不限
+    "our_sides": ["backend"],  # 我方端（CodeBee 自动修）；空=纯排查转派不修
+    "repos": {"backend": dict(_REPO_DEFAULTS), "frontend": dict(_REPO_DEFAULTS)},
+    "repo_hints": {"backend": "", "frontend": ""},   # AI 排查时的一句仓库描述
+    "owners": {"backend": "", "frontend": "", "not_ours": ""},
+    "module_routes": [],       # [{module:int, side:backend|frontend|both|not_ours, account:""}]
+}
+
+_UPDATABLE = ("base_url", "account", "password", "product_profiles",
+              "auto_resolve", "auto_merge", "triage_ai",
+              "poll_enabled", "interval_hours")
+
+
+# ---------------------------------------------------------------- 出网边界（SSRF）
+
+_META_HOSTS = {"metadata.google.internal", "metadata.goog"}
+_NO_REDIRECT = None
+
+
+def _no_redirect_opener():
+    """HTTP 重定向一概不跟：目标必须就是用户配置的那台禅道。"""
+    global _NO_REDIRECT
+    if _NO_REDIRECT is None:
+        class _Stop(urllib.request.HTTPRedirectHandler):
+            def redirect_request(self, req, fp, code, msg, headers, newurl):
+                return None
+        _NO_REDIRECT = urllib.request.build_opener(
+            _Stop(), urllib.request.HTTPSHandler(context=tlsctx.context()))
+    return _NO_REDIRECT
+
+
+def _guard_url(url):
+    """出网前的边界校验：协议白名单 + 主机解析阻断云元数据/链路本地地址。
+
+    私网与环回按设计放行（禅道自建在内网是主场景，配置者即本机用户）。
+    校验失败抛 ZenError。返回原 url。
+    """
+    from urllib.parse import urlparse
+    u = urlparse(url)
+    if u.scheme not in ("http", "https"):
+        raise ZenError("禅道地址只允许 http/https 协议")
+    host = (u.hostname or "").lower()
+    if not host:
+        raise ZenError("禅道地址缺少主机名")
+    if host in _META_HOSTS:
+        raise ZenError("不允许访问云元数据地址")
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except OSError:
+        raise ZenError("禅道主机解析失败：%s" % host)
+    for info in infos:
+        ip = ipaddress.ip_address(info[4][0])
+        if ip.is_link_local or ip.is_reserved and not ip.is_private:
+            raise ZenError("不允许访问链路本地/保留地址：%s" % ip)
+        if ip.is_multicast or ip.is_unspecified:
+            raise ZenError("不允许访问多播/未指定地址：%s" % ip)
+    return url
+
+
+# ---------------------------------------------------------------- 持久化
+
+def _save_locked():
+    _FILE.parent.mkdir(parents=True, exist_ok=True)
+    tmp = _FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps({"version": 2, **_STATE},
+                              ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(str(tmp), str(_FILE))
+
+
+def _normalize_claim(d):
+    """claim 归一：v1 单任务形状（task_id/run_id）→ v2 tasks 数组。"""
+    c = dict(d) if isinstance(d, dict) else {}
+    if isinstance(c.get("tasks"), list) and c["tasks"]:
+        tasks = [dict(t) for t in c["tasks"] if isinstance(t, dict)]
+    else:
+        tasks = [{"side": "backend", "task_id": c.get("task_id") or "",
+                  "run_id": c.get("run_id") or "", "state": "fixing"}] \
+            if (c.get("task_id") or c.get("run_id")) else []
+    c["tasks"] = tasks
+    c.setdefault("triage", {"side": "", "reason": "", "by": "", "account": ""})
+    if not isinstance(c.get("triage"), dict):
+        c["triage"] = {"side": "", "reason": "", "by": "", "account": ""}
+    c.setdefault("note", "")
+    c.setdefault("attempts", 0)
+    return c
+
+
+def _migrate_legacy(cfg):
+    """老扁平配置（products+单仓库）→ product_profiles。就地改写返回。"""
+    if cfg.get("product_profiles"):
+        return cfg
+    products = cfg.get("products") or []
+    if not isinstance(products, list) or not products:
+        return cfg
+    try:
+        pids = [int(p) for p in products if str(p).strip()]
+    except (TypeError, ValueError):
+        return cfg
+    backend = dict(_REPO_DEFAULTS)
+    for k in _REPO_DEFAULTS:
+        backend[k] = str(cfg.get(k) or "")
+    our = ["backend"]
+    if not backend["workdir"]:
+        our = []          # 老配置连工作目录都没配：纯路由
+    for pid in pids:
+        cfg.setdefault("product_profiles", []).append({
+            "product": pid,
+            "assigned_to": str(cfg.get("assigned_to") or ""),
+            "severity_cap": int(cfg.get("severity_cap") or 0),
+            "our_sides": list(our),
+            "repos": {"backend": backend, "frontend": dict(_REPO_DEFAULTS)},
+            "repo_hints": {"backend": "", "frontend": ""},
+            "owners": {"backend": "", "frontend": "", "not_ours": ""},
+            "module_routes": [],
+        })
+    return cfg
+
+
+def load(force=False):
+    """从磁盘加载状态（幂等）。返回 claims 数。测试可重绑 _FILE 后 force=True。"""
+    global _LOADED
+    with _LOCK:
+        if _LOADED and not force:
+            return len(_STATE["claims"])
+        try:
+            data = json.loads(_FILE.read_text(encoding="utf-8"))
+        except Exception:
+            data = {}
+        cfg = data.get("config") if isinstance(data, dict) else None
+        merged = dict(_CFG_DEFAULTS)
+        if isinstance(cfg, dict):
+            merged.update({k: v for k, v in cfg.items() if k in _CFG_DEFAULTS})
+        merged = _migrate_legacy(merged)
+        claims = data.get("claims") if isinstance(data, dict) else None
+        _STATE["config"] = merged
+        _STATE["claims"] = {str(k): _normalize_claim(v)
+                            for k, v in (claims or {}).items()} \
+            if isinstance(claims, dict) else {}
+        _STATE["last_scan"] = str(data.get("last_scan") or "") if isinstance(data, dict) else ""
+        _STATE["next_scan"] = str(data.get("next_scan") or "") if isinstance(data, dict) else ""
+        _STATE["last_error"] = str(data.get("last_error") or "") if isinstance(data, dict) else ""
+        _LOADED = True
+        return len(_STATE["claims"])
+
+
+def _ensure_loaded():
+    if not _LOADED:
+        load()
+
+
+def _cfg():
+    cfg = dict(_CFG_DEFAULTS)
+    cfg.update({k: v for k, v in (_STATE.get("config") or {}).items()
+                if k in _CFG_DEFAULTS})
+    return cfg
+
+
+def _profiles(cfg=None):
+    out = []
+    for p in (cfg or _cfg()).get("product_profiles") or []:
+        prof = dict(_PROFILE_DEFAULTS)
+        prof.update({k: v for k, v in (p or {}).items() if k in _PROFILE_DEFAULTS})
+        repos = dict(_PROFILE_DEFAULTS["repos"])
+        for side in SIDES:
+            r = dict(_REPO_DEFAULTS)
+            r.update({k: v for k, v in ((prof.get("repos") or {}).get(side) or {}).items()
+                      if k in _REPO_DEFAULTS})
+            repos[side] = r
+        prof["repos"] = repos
+        hints = dict(_PROFILE_DEFAULTS["repo_hints"])
+        for side in SIDES:
+            hints[side] = str((prof.get("repo_hints") or {}).get(side) or "")
+        prof["repo_hints"] = hints
+        owners = dict(_PROFILE_DEFAULTS["owners"])
+        for k in owners:
+            owners[k] = str((prof.get("owners") or {}).get(k) or "").strip()
+        prof["owners"] = owners
+        prof["our_sides"] = [s for s in SIDES if s in (prof.get("our_sides") or [])]
+        prof["module_routes"] = [r for r in (prof.get("module_routes") or [])
+                                 if isinstance(r, dict)]
+        out.append(prof)
+    return out
+
+
+def _profile_for(cfg, product_id):
+    try:
+        pid = int(product_id or 0)
+    except (TypeError, ValueError):
+        return None
+    for p in _profiles(cfg):
+        if p["product"] == pid:
+            return p
+    return None
+
+
+# ---------------------------------------------------------------- 禅道客户端
+
+class ZenError(Exception):
+    """禅道接口错误（message 人话，可直接展示）。"""
+
+
+_TOKEN = {"v": "", "at": 0.0}
+
+
+def _reset_token():
+    _TOKEN["v"] = ""
+    _TOKEN["at"] = 0.0
+
+
+def _api_base(base_url):
+    b = str(base_url or "").strip().rstrip("/")
+    if not b:
+        raise ZenError("禅道地址未配置")
+    if not b.startswith(("http://", "https://")):
+        raise ZenError("禅道地址必须以 http:// 或 https:// 开头")
+    return b + "/api.php/v1"
+
+
+def _fetch_token(base_url, account, password):
+    """获取新 token 并缓存。失败抛 ZenError。"""
+    url = _guard_url(_api_base(base_url) + "/tokens")
+    body = json.dumps({"account": str(account or ""), "password": str(password or "")},
+                      ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(url, data=body, method="POST", headers={
+        "Content-Type": "application/json", "Accept": "application/json"})
+    try:
+        with _no_redirect_opener().open(req, timeout=HTTP_TIMEOUT) as r:
+            data = json.loads((r.read() or b"{}").decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        try:
+            detail = json.loads((e.read() or b"").decode("utf-8", "replace"))
+            msg = (detail.get("error") or "") if isinstance(detail, dict) else ""
+        except Exception:
+            msg = ""
+        if e.code in (401, 403):
+            raise ZenError("禅道账号或密码不对（%s）%s" % (e.code, msg))
+        raise ZenError("禅道返回 %s：%s" % (e.code, msg or "获取令牌失败"))
+    except ZenError:
+        raise
+    except Exception as e:
+        raise ZenError("连不上禅道（%s）——请检查地址与网络" % e)
+    tok = ""
+    if isinstance(data, dict):
+        tok = str(data.get("token") or "")
+        if not tok and isinstance(data.get("data"), dict):
+            tok = str(data["data"].get("token") or "")
+    if not tok:
+        raise ZenError("禅道响应里没有 token——请确认版本 ≥15 且已开启 REST API")
+    _TOKEN["v"] = tok
+    _TOKEN["at"] = time.time()
+    return tok
+
+
+def _token(cfg, force=False):
+    if force or not _TOKEN["v"] or time.time() - _TOKEN["at"] > TOKEN_TTL:
+        return _fetch_token(cfg.get("base_url"), cfg.get("account"), cfg.get("password"))
+    return _TOKEN["v"]
+
+
+def _api(method, path, cfg=None, body=None):
+    """调禅道 API。返回 dict（非 dict 响应返回 {}）。401/403 自动重取 token 重试一次。"""
+    c = cfg or _cfg()
+    for attempt in (1, 2):
+        headers = {"Accept": "application/json", "Token": _token(c, force=(attempt == 2))}
+        url = _guard_url(_api_base(c.get("base_url")) + path)
+        data = None
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with _no_redirect_opener().open(req, timeout=HTTP_TIMEOUT) as r:
+                out = json.loads((r.read() or b"{}").decode("utf-8", "replace"))
+            return out if isinstance(out, dict) else {"_list": out}
+        except urllib.error.HTTPError as e:
+            raw = ""
+            try:
+                raw = (e.read() or b"").decode("utf-8", "replace")
+            except Exception:
+                pass
+            detail = ""
+            try:
+                d = json.loads(raw)
+                if isinstance(d, dict):
+                    detail = str(d.get("error") or d.get("message") or "")
+            except Exception:
+                pass
+            if e.code in (401, 403) and attempt == 1:
+                _reset_token()
+                continue
+            raise ZenError("禅道接口 %s（%s）%s" % (path, e.code, detail or "调用失败"))
+        except ZenError:
+            raise
+        except Exception as e:
+            raise ZenError("连不上禅道（%s）" % e)
+    raise ZenError("禅道认证失败（token 两次获取后仍被拒绝，检查账号权限）")
+
+
+def _acct(v):
+    """assignedTo/openedBy 兼容：新版返回 {account,...} 用户对象，老版直接是账号串。"""
+    if isinstance(v, dict):
+        return str(v.get("account") or "").strip()
+    return str(v or "").strip()
+
+
+def _strip_html(raw):
+    """steps 字段是富文本 HTML：剥标签转纯文本。"""
+    txt = str(raw or "")
+    txt = re.sub(r"(?is)<(script|style).*?>.*?</\1>", " ", txt)
+    txt = re.sub(r"(?i)<br\s*/?>|</p>|</li>|</div>|</tr>", "\n", txt)
+    txt = re.sub(r"<[^>]+>", " ", txt)
+    txt = _html.unescape(txt)
+    txt = re.sub(r"[ \t\r]+", " ", txt)
+    txt = re.sub(r"\n\s*\n+", "\n", txt)
+    return txt.strip()
+
+
+def _severity(bug):
+    try:
+        return int(bug.get("severity") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _claimable(bug, profile):
+    """认领过滤：active + 指派 + 严重度（产品由档案本身界定）。"""
+    if str(bug.get("status") or "") != "active":
+        return False
+    assigned = str(profile.get("assigned_to") or "").strip()
+    cap = int(profile.get("severity_cap") or 0)
+    if assigned and _acct(bug.get("assignedTo")) != assigned:
+        return False
+    if cap and _severity(bug) > cap:
+        return False
+    return True
+
+
+def list_bugs(cfg, product_id):
+    """拉一个产品下的 bug（分页，总量封顶 MAX_BUGS）。返回原始 bug dict 列表。"""
+    out = []
+    for page in range(1, 6):
+        d = _api("GET", "/products/%s/bugs?page=%d&limit=%d" % (product_id, page, PAGE_LIMIT),
+                 cfg=cfg)
+        bugs = d.get("bugs") if isinstance(d, dict) else None
+        if not isinstance(bugs, list):
+            raise ZenError("禅道 bug 列表响应形状不对（预期 bugs 数组）")
+        out.extend(b for b in bugs if isinstance(b, dict))
+        total = 0
+        try:
+            total = int(d.get("total") or 0)
+        except (TypeError, ValueError):
+            pass
+        if len(out) >= MAX_BUGS or (total and len(out) >= total) or len(bugs) < PAGE_LIMIT:
+            break
+    return out[:MAX_BUGS]
+
+
+def fetch_modules(product_id):
+    """拉产品模块清单（模块路由配置辅助）。接口不存在/失败报人话，提示手填 ID。"""
+    _ensure_loaded()
+    cfg = _cfg()
+    try:
+        d = _api("GET", "/products/%s/modules" % product_id, cfg=cfg)
+    except ZenError as e:
+        return {"ok": False,
+                "error": "%s——也可能你的禅道没有该接口：请在禅道产品视图 URL 里查模块 ID 手工填写" % e}
+    items = d.get("_list") if isinstance(d.get("_list"), list) else d.get("modules")
+    out = []
+    for m in items or []:
+        if isinstance(m, dict) and m.get("id"):
+            out.append({"id": m.get("id"), "name": str(m.get("name") or "")})
+        elif isinstance(m, dict) and str(m.get("id") or "") == "" and m.get("name"):
+            continue
+    if not out:
+        return {"ok": False, "error": "模块清单为空或响应形状不认识——请手工填模块 ID"}
+    return {"ok": True, "modules": out[:200]}
+
+
+def test_connection(base_url=None, account=None, password=None):
+    """连接测试：取 token + 拉第一个产品的 bug 列表（有档案时）。返回 (ok, 人话结果)。"""
+    c = _cfg()
+    base_url = str(base_url if base_url is not None else c.get("base_url") or "").strip()
+    account = str(account if account is not None else c.get("account") or "").strip()
+    password = str(password if password is not None else c.get("password") or "").strip()
+    if not (base_url and account and password):
+        return False, "地址、账号、密码都要填全"
+    try:
+        _fetch_token(base_url, account, password)
+    except ZenError as e:
+        return False, str(e)
+    try:
+        profiles = _profiles(c)
+        if profiles:
+            bugs = list_bugs({"base_url": base_url, "account": account, "password": password},
+                             profiles[0]["product"])
+            return True, "连接成功，产品 %s 可访问（当前 %d 条 bug 在列表里）" % (
+                profiles[0]["product"], len(bugs))
+    except ZenError as e:
+        return False, "令牌拿到了，但拉 bug 列表失败：%s" % e
+    return True, "连接成功（未配产品档案，跳过列表探测）"
+
+
+# ---------------------------------------------------------------- 排查（triage）
+
+def _ai_triage(bug, profile):
+    """AI 兜底排查：单次 LLM 调用判端。不可用/解析失败返回 None（bookmeta 同款配方）。"""
+    try:
+        from . import modelhub, runner
+        orch = modelhub.resolve_orchestrator()
+        if not orch:
+            return None
+        prov, model = orch
+        repos = profile.get("repos") or {}
+        hints = profile.get("repo_hints") or {}
+
+        def _repo_desc(side):
+            hint = str(hints.get(side) or "").strip()
+            if hint:
+                return hint
+            wd = str((repos.get(side) or {}).get("workdir") or "").strip()
+            if wd:
+                return "目录 " + Path(wd).name
+            return "（未配置）"
+
+        lines = ["你是缺陷分诊员：根据缺陷描述判断问题属于哪个仓库端。", "",
+                 "【缺陷】#%s %s" % (bug.get("id"), str(bug.get("title") or ""))]
+        steps = _strip_html(bug.get("steps"))
+        if steps:
+            lines.append(steps[:3000])
+        lines.append("")
+        lines.append("【仓库背景】后端仓库：%s；前端仓库：%s" % (_repo_desc("backend"),
+                                                        _repo_desc("frontend")))
+        lines.append("")
+        lines.append('只输出 JSON（不要别的文字）：{"side": "backend|frontend|both|not_ours", '
+                     '"reason": "一句话依据"}')
+        lines.append("判定口径：backend=纯后端问题；frontend=纯前端问题；both=两端都要改；"
+                     "not_ours=与这两个仓库无关（第三方服务/环境/需求变更/数据问题等）。")
+        res = modelhub.chat(prov["id"], model, "\n".join(lines), max_tokens=500,
+                            timeout=90)
+        if not res.get("ok"):
+            log.warning("zentao: AI 排查失败：%s", res.get("error"))
+            return None
+        data = runner.extract_json(res.get("text") or "")
+        side = str((data or {}).get("side") or "").strip().lower()
+        if side not in TRIAGE_SIDES:
+            return None
+        return {"side": side, "reason": str((data or {}).get("reason") or "")[:300]}
+    except Exception:
+        log.debug("zentao: AI 排查异常", exc_info=True)
+        return None
+
+
+def _triage(bug, profile, cfg):
+    """排查定责：模块路由 > AI > unknown。返回 {side, reason, by, account}。"""
+    mid = str(bug.get("module") or "")
+    if mid:
+        for r in profile.get("module_routes") or []:
+            try:
+                if int(r.get("module") or 0) != int(mid):
+                    continue
+            except (TypeError, ValueError):
+                continue
+            side = str(r.get("side") or "")
+            if side in TRIAGE_SIDES:
+                return {"side": side, "reason": "模块 #%s 路由规则" % mid,
+                        "by": "rule", "account": str(r.get("account") or "").strip()}
+    if cfg.get("triage_ai"):
+        res = _ai_triage(bug, profile)
+        if res:
+            res["by"] = "ai"
+            res["account"] = ""
+            return res
+    return {"side": "unknown", "reason": "模块未命中路由且 AI 排查不可用", "by": "fallback",
+            "account": ""}
+
+
+# ---------------------------------------------------------------- 修复任务拉起
+
+def _repo_of(profile, side):
+    return (profile.get("repos") or {}).get(side) or dict(_REPO_DEFAULTS)
+
+
+def _goal_text(bug, side=None):
+    """bug → 修复目标提示词。side 给出时附端约束。"""
+    bid = bug.get("id")
+    lines = ["修复禅道 Bug #%s：%s" % (bid, str(bug.get("title") or "").strip())]
+    steps = _strip_html(bug.get("steps"))
+    if steps:
+        lines.append("")
+        lines.append("【重现步骤/问题描述】")
+        lines.append(steps[:4000])
+    sev, pri = _severity(bug), str(bug.get("pri") or "").strip()
+    meta = []
+    if sev:
+        meta.append("严重度 %s（1 最严重）" % sev)
+    if pri:
+        meta.append("优先级 %s" % pri)
+    if str(bug.get("module") or "").strip():
+        meta.append("模块 #%s" % bug["module"])
+    env = " / ".join(x for x in (str(bug.get("os") or "").strip(),
+                                 str(bug.get("browser") or "").strip()) if x)
+    if env:
+        meta.append("环境 " + env)
+    kw = str(bug.get("keywords") or "").strip()
+    if kw:
+        meta.append("关键字 " + kw)
+    if meta:
+        lines.append("")
+        lines.append("【元信息】" + "；".join(meta))
+    lines.append("")
+    lines.append("【要求】只修这个 bug，不做无关重构；改动最小化；修完自查不引入回归。")
+    if side in SIDES:
+        lines.append("【端约束】本任务只负责【%s】部分；%s部分由别人处理，不要越界改动。"
+                     % (SIDE_CN[side],
+                        SIDE_CN["frontend" if side == "backend" else "backend"]))
+    lines.append("完成后给出修改说明。")
+    return "\n".join(lines)
+
+
+def _launch_fix(bug, profile, side, cfg):
+    """为一个 bug 的某一端建修复任务并入队。与 automation._launch_run 同一条链。"""
+    bid = bug.get("id")
+    repo = _repo_of(profile, side)
+    wd = str(repo.get("workdir") or "").strip() or settings.default_workdir()
+    title = ("[禅道#%s][%s] %s" % (bid, SIDE_CN.get(side, side),
+                                   str(bug.get("title") or "").strip())).strip()[:60]
+    payload = {"type": "code", "title": title, "goal": _goal_text(bug, side), "workdir": wd}
+    if str(repo.get("git_rev") or "").strip():
+        payload["git_rev"] = str(repo["git_rev"]).strip()
+    if str(repo.get("verify_command") or "").strip():
+        payload["verify_command"] = str(repo["verify_command"]).strip()
+    task = store.create_task(payload)
+    run = store.create_run("orchestration", task["title"], task_id=task["id"])
+    store.update_task_status(task["id"], "queued")
+    jobs.enqueue({"kind": "orchestration", "run_id": run["id"], "task_id": task["id"]})
+    return task, run
+
+
+# ---------------------------------------------------------------- 回写文本
+
+def _diffstat(workdir, task_id):
+    """任务分支相对基线的改动统计（人话一行）。拿不到返回空串。"""
+    try:
+        from . import gitmod, runner
+        if task_id and workdir:
+            br = gitmod.branch_name(task_id)
+            r = runner.run_process(
+                argv=["git", "-C", workdir, "diff", "--shortstat", "HEAD..." + br],
+                timeout=20)
+            if r.get("ok"):
+                return (r.get("stdout") or "").strip()
+    except Exception:
+        log.debug("zentao: diffstat 失败", exc_info=True)
+    return ""
+
+
+def _fix_summary(claim, run, profile, side):
+    """我方某一端的修复摘要（转派评论与 resolve 报告共用的事实部分）。"""
+    task = store.get_task((claim.get("tasks") or [{}])[0].get("task_id") if not side
+                          else _task_of(claim, side).get("task_id"))
+    lines = []
+    git = (run or {}).get("git") or {}
+    commit = str(git.get("commit") or "").strip()
+    from_branch = str(git.get("from_branch") or "").strip()
+    tid = (_task_of(claim, side).get("task_id") if side else "") or ""
+    if commit:
+        lines.append("%s修复提交 %s%s" % ("【%s】" % SIDE_CN[side] if side else "",
+                                         commit,
+                                         "（已合并回 %s）" % from_branch if from_branch else ""))
+    stat = _diffstat(_repo_of(profile, side).get("workdir") if profile else "", tid)
+    if stat:
+        lines.append("改动统计：%s" % stat)
+    v = (run or {}).get("verdict") or {}
+    if v:
+        lines.append("验证结论：%s" % ("通过（评审达标）" if v.get("pass") or v.get("publishable")
+                                       else "完成"))
+    return lines
+
+
+def _task_of(claim, side):
+    for t in claim.get("tasks") or []:
+        if t.get("side") == side:
+            return t
+    return {}
+
+
+def _report_text(claim, run, profile, cfg):
+    """resolve 评论：确定性事实。"""
+    tri = claim.get("triage") or {}
+    lines = ["【CodeBee 自动修复报告】",
+             "Bug：#%s %s" % (claim.get("bug_id"), claim.get("title") or "")]
+    if tri.get("side"):
+        lines.append("排查结论：%s问题（%s）" % (SIDE_CN.get(tri["side"], tri["side"]),
+                                               tri.get("reason") or tri.get("by") or "按规则"))
+    lines.extend(_fix_summary(claim, run, profile, None))
+    lines.append("（本条由 CodeBee 禅道集成自动回写）")
+    return "\n".join(lines)
+
+
+def _transfer_text(claim, profile, fixed_runs, target_side):
+    """转派评论：排查结论 + 我方已做工作 + 请对方继续。"""
+    tri = claim.get("triage") or {}
+    lines = ["【CodeBee 排查转派】",
+             "Bug：#%s %s" % (claim.get("bug_id"), claim.get("title") or ""),
+             "排查结论：%s问题——%s" % (SIDE_CN.get(target_side, target_side),
+                                      tri.get("reason") or tri.get("by") or "按规则")]
+    for side, run in (fixed_runs or []):
+        lines.extend(_fix_summary(claim, run, profile, side))
+    lines.append("请%s负责人接手处理；本 bug 保持激活，处理完请按正常流程解决。"
+                 % SIDE_CN.get(target_side, target_side))
+    lines.append("（本条由 CodeBee 禅道集成自动回写）")
+    return "\n".join(lines)
+
+
+def _fail_text(claim, failed_tasks, runs):
+    tri = claim.get("triage") or {}
+    lines = ["【CodeBee 自动修复未成功】",
+             "Bug：#%s %s" % (claim.get("bug_id"), claim.get("title") or "")]
+    if tri.get("side"):
+        lines.append("排查结论：%s（%s）" % (tri.get("side"), tri.get("reason") or ""))
+    for t in failed_tasks:
+        r = runs.get(t.get("run_id")) or {}
+        why = str(r.get("error") or "").strip() or ("运行状态 " + str(r.get("status") or ""))
+        lines.append("【%s】失败：%s" % (SIDE_CN.get(t.get("side"), t.get("side")), why[:300]))
+    lines.append("CodeBee 修复任务：%s（可人工续跑或接管）；本 bug 保持待处理。"
+                 % "、".join(t.get("task_id") or "?" for t in claim.get("tasks") or []))
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------- 禅道写回动作
+
+def _bug_opened_by(cfg, bug_id):
+    try:
+        d = _api("GET", "/bugs/%s" % bug_id, cfg=cfg)
+        return _acct(d.get("openedBy"))
+    except ZenError:
+        return ""
+
+
+def _ensure_resolved(cfg, bug_id, comment, assign_to):
+    """resolve（幂等）：已是 resolved/closed 视为成功。"""
+    cur = _api("GET", "/bugs/%s" % bug_id, cfg=cfg)
+    if str(cur.get("status") or "") in ("resolved", "closed"):
+        return True
+    body = {"resolution": "fixed", "resolvedBuild": "trunk", "comment": comment}
+    if assign_to:
+        body["assignedTo"] = assign_to
+    _api("POST", "/bugs/%s/resolve" % bug_id, cfg=cfg, body=body)
+    return True
+
+
+def _transfer(cfg, bug_id, target, comment):
+    """转派：PUT assignedTo+comment（bug 保持激活）。target 空=只评论。抛 ZenError。"""
+    body = {"comment": comment}
+    if target:
+        body["assignedTo"] = target
+    _api("PUT", "/bugs/%s" % bug_id, cfg=cfg, body=body)
+
+
+def _notify(text):
+    try:
+        from . import notify
+        notify.push_text(text)
+    except Exception:
+        log.debug("zentao: 群通知失败", exc_info=True)
+
+
+def _merge_branch(workdir, task):
+    try:
+        from . import gitmod
+        return gitmod.merge_task_branch(workdir, task)
+    except Exception as e:
+        return False, "合并异常：%s" % e, None
+
+
+def _set_claim(bid, **patch):
+    with _LOCK:
+        c = _STATE["claims"].get(str(bid))
+        if c is None:
+            return
+        c.update(patch)
+        c["at"] = time.strftime("%Y-%m-%d %H:%M:%S")
+        _save_locked()
+
+
+def _route_account(profile, tri, side):
+    """转派/升级目标：模块路由 account > 端负责人。"""
+    if tri and tri.get("account"):
+        return str(tri["account"]).strip()
+    return str((profile.get("owners") or {}).get(side) or "").strip()
+
+
+# ---------------------------------------------------------------- 对账回写
+
+def _finish_ok(claim, cfg):
+    """我方任务全部 done：合并 → （需要则）转派 → 否则 resolve。"""
+    bid = str(claim.get("bug_id"))
+    profile = _profile_for(cfg, claim.get("product")) or {}
+    tri = claim.get("triage") or {}
+    tasks = claim.get("tasks") or []
+    runs = {t.get("run_id"): store.get_run(t.get("run_id") or "") for t in tasks}
+    # 1) 逐任务合并（任一失败即停：不转派不 resolve，绝不带着没落库的修复转派）
+    if cfg.get("auto_merge"):
+        for t in tasks:
+            task = store.get_task(t.get("task_id") or "")
+            if task is None or not task.get("git_rev"):
+                continue
+            ok, err, _info = _merge_branch(str(_repo_of(profile, t.get("side")).get("workdir")
+                                               or settings.default_workdir()), task)
+            if not ok:
+                _set_claim(bid, state="merge_failed",
+                           note="【%s】任务分支合并失败：%s（不转派不 resolve，留人工）"
+                                % (SIDE_CN.get(t.get("side"), t.get("side")), err))
+                _notify("🐛❌ 禅道 Bug #%s 的%s修复代码合并失败：%s\n修复任务：%s"
+                        % (bid, SIDE_CN.get(t.get("side"), ""), err, t.get("task_id") or "?"))
+                return
+    # 2) 需要转派的端 = 判定端 - 我方端（both 且我方只管一端时非空）
+    verdict_sides = ([tri["side"]] if tri.get("side") in SIDES
+                     else list(SIDES) if tri.get("side") == "both" else [])
+    other_sides = [s for s in verdict_sides if s not in (profile.get("our_sides") or [])]
+    if other_sides:
+        targets = {}
+        for s in other_sides:
+            tgt = _route_account(profile, tri, s)
+            if not tgt:
+                _set_claim(bid, state="need_manual",
+                           note="我方已修完，但未配置%s负责人，无法转派——请人工转派" % SIDE_CN[s])
+                _notify("🐛⚠️ 禅道 Bug #%s 我方部分已修完，但未配置%s负责人，请人工转派"
+                        % (bid, SIDE_CN[s]))
+                return
+            targets[s] = tgt
+        fixed_runs = [(t.get("side"), runs.get(t.get("run_id"))) for t in tasks]
+        for s in other_sides:
+            try:
+                _transfer(cfg, bid, targets[s], _transfer_text(claim, profile, fixed_runs, s))
+            except ZenError as e:
+                attempts = int(claim.get("attempts") or 0) + 1
+                if attempts >= RESOLVE_MAX_ATTEMPTS:
+                    _set_claim(bid, attempts=attempts, state="resolve_failed",
+                               note="转派连续 %d 次失败：%s" % (attempts, e))
+                    _notify("🐛⚠️ 禅道 Bug #%s 修完但转派失败：%s" % (bid, e))
+                else:
+                    _set_claim(bid, attempts=attempts, state="fixing",
+                               note="转派第 %d 次失败，下轮重试：%s" % (attempts, e))
+                return
+        _set_claim(bid, state="transferred",
+                   note="我方（%s）已修完并合并，转派给 %s"
+                        % ("/".join(SIDE_CN.get(t.get("side"), "") for t in tasks),
+                           "、".join(SIDE_CN[s] + ":" + targets[s] for s in other_sides)))
+        _notify("🐛🔁 禅道 Bug #%s 我方已修完，转派 %s\n%s"
+                % (bid, "、".join(SIDE_CN[s] + ":" + targets[s] for s in other_sides),
+                   claim.get("title") or ""))
+        return
+    # 3) 全部我方端：resolve（幂等）+ 指回报告人
+    if not cfg.get("auto_resolve"):
+        _set_claim(bid, state="done_manual",
+                   note="修复完成；auto_resolve 已关，请人工确认后到禅道解决 bug")
+        return
+    report = _report_text(claim, runs.get(tasks[0].get("run_id")), profile, cfg)
+    opened = _bug_opened_by(cfg, bid)
+    try:
+        _ensure_resolved(cfg, bid, report, opened)
+    except ZenError as e:
+        attempts = int(claim.get("attempts") or 0) + 1
+        if attempts >= RESOLVE_MAX_ATTEMPTS:
+            _set_claim(bid, attempts=attempts, state="resolve_failed",
+                       note="resolve 连续 %d 次失败：%s" % (attempts, e))
+            _notify("🐛⚠️ 禅道 Bug #%s 修复完成但回写禅道失败：%s" % (bid, e))
+        else:
+            _set_claim(bid, attempts=attempts, state="fixing",
+                       note="resolve 第 %d 次失败，下轮重试：%s" % (attempts, e))
+        return
+    _set_claim(bid, state="resolved", note="已 resolve(fixed)%s"
+               % ("，指回报告人 " + opened if opened else ""))
+    _notify("🐛✅ 禅道 Bug #%s 已修复并 resolve\n%s\n修复任务：%s"
+            % (bid, claim.get("title") or "", "、".join(t.get("task_id") or "" for t in tasks)))
+
+
+def _finish_failed(claim, cfg):
+    """我方任一任务失败：评论尝试记录 + 转派该端负责人（有配则转）。"""
+    bid = str(claim.get("bug_id"))
+    profile = _profile_for(cfg, claim.get("product")) or {}
+    tasks = claim.get("tasks") or []
+    runs = {t.get("run_id"): store.get_run(t.get("run_id") or "") for t in tasks}
+    failed = [t for t in tasks
+              if str((runs.get(t.get("run_id")) or {}).get("status") or "") not in
+              ("queued", "running", "done")]
+    text = _fail_text(claim, failed, runs)
+    # 升级目标：取第一个失败端的路由账号/负责人
+    target = ""
+    for t in failed:
+        target = _route_account(profile, claim.get("triage") or {}, t.get("side"))
+        if target:
+            break
+    try:
+        _transfer(cfg, bid, target, text)
+        note = "已评论说明%s" % ("并转派 %s" % target if target else "")
+        state = "escalated" if target else "commented"
+    except ZenError as e:
+        log.warning("zentao: bug %s 失败评论未送达（群通知兜底）：%s", bid, e)
+        note = "修复失败，评论未送达：%s" % e
+        state = "commented"
+    _set_claim(bid, state=state, note=note)
+    _notify("🐛❌ 禅道 Bug #%s 自动修复未成功%s\n%s\n修复任务：%s"
+            % (bid, ("，已转派 " + target) if target else "",
+               claim.get("title") or "", "、".join(t.get("task_id") or "" for t in tasks)))
+
+
+def _reconcile(cfg):
+    """对账：fixing 中的 claim 查各 run 终态并回写。单条异常只跳过该条。"""
+    with _LOCK:
+        fixing = [dict(c) for c in _STATE["claims"].values() if c.get("state") == "fixing"]
+    for claim in fixing:
+        bid = str(claim.get("bug_id"))
+        try:
+            tasks = claim.get("tasks") or []
+            runs = {t.get("run_id"): store.get_run(t.get("run_id") or "") for t in tasks}
+            if any(r is None for r in runs.values()):
+                _set_claim(bid, state="lost", note="运行记录不存在（可能被清理）")
+                continue
+            states = [str((r or {}).get("status") or "") for r in runs.values()]
+            if any(s in ("queued", "running") for s in states):
+                continue
+            if all(s == "done" for s in states):
+                _finish_ok(claim, cfg)
+            else:
+                _finish_failed(claim, cfg)
+        except Exception:
+            log.exception("zentao: claim %s 对账异常，跳过", bid)
+
+
+# ---------------------------------------------------------------- 扫描主流程
+
+def _sides_to_fix(profile, tri):
+    """判定端 ∩ 我方端。"""
+    tri_side = tri.get("side")
+    verdict_sides = [tri_side] if tri_side in SIDES else (list(SIDES) if tri_side == "both" else [])
+    return [s for s in verdict_sides if s in (profile.get("our_sides") or [])]
+
+
+def _route_one(bug, profile, cfg, seen):
+    """认领一个 bug：排查 → 分流（建任务/转派/留人工）。返回动作文案或 None。"""
+    bid = str(bug.get("id") or "")
+    tri = _triage(bug, profile, cfg)
+    base_claim = {
+        "bug_id": bug.get("id"), "product": profile.get("product"),
+        "title": str(bug.get("title") or "")[:120],
+        "triage": tri, "tasks": [], "state": "fixing", "note": "",
+        "attempts": 0, "claimed_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    opened = _acct(bug.get("openedBy"))
+
+    if tri["side"] == "unknown":
+        base_claim["state"] = "need_manual"
+        base_claim["note"] = tri.get("reason") or "排查失败，留人工"
+        with _LOCK:
+            _STATE["claims"][bid] = base_claim
+            _save_locked()
+        _notify("🐛❓ 禅道 Bug #%s 排查不出归属端（%s），留人工\n%s"
+                % (bid, tri.get("reason") or "", bug.get("title") or ""))
+        return "need_manual"
+
+    if tri["side"] == "not_ours":
+        target = tri.get("account") or str(profile.get("owners").get("not_ours") or "") \
+            or opened
+        text = ("【CodeBee 排查转派】\nBug：#%s %s\n排查结论：非我方两个仓库的问题——%s\n"
+                "转回 %s 核实处理。\n（本条由 CodeBee 禅道集成自动回写）"
+                % (bid, bug.get("title") or "", tri.get("reason") or "按规则",
+                   target or "报告人"))
+        try:
+            _transfer(cfg, bid, target, text)
+            note = "非我方，已转派 %s" % (target or "（未指派，仅评论）")
+        except ZenError as e:
+            base_claim.update({"state": "need_manual", "note": "非我方转派失败：%s" % e})
+            with _LOCK:
+                _STATE["claims"][bid] = base_claim
+                _save_locked()
+            _notify("🐛⚠️ 禅道 Bug #%s 判定非我方但转派失败：%s" % (bid, e))
+            return "need_manual"
+        base_claim.update({"state": "transferred", "note": note})
+        with _LOCK:
+            _STATE["claims"][bid] = base_claim
+            _save_locked()
+        _notify("🐛↩️ 禅道 Bug #%s 判定非我方，已转派 %s\n%s"
+                % (bid, target or "报告人", bug.get("title") or ""))
+        return "transferred"
+
+    sides = _sides_to_fix(profile, tri)
+    if not sides:
+        # 纯对方端问题（含测试指错到我方账号的）：直接转派正确负责人
+        other = tri["side"] if tri["side"] in SIDES else None
+        if other is None:            # both 但我方两端都没配：整单转不了，留人工
+            base_claim["state"] = "need_manual"
+            base_claim["note"] = "双端问题但产品档案未配置我方端，请人工处理"
+            with _LOCK:
+                _STATE["claims"][bid] = base_claim
+                _save_locked()
+            _notify("🐛❓ 禅道 Bug #%s 为双端问题但未配我方端，留人工" % bid)
+            return "need_manual"
+        target = _route_account(profile, tri, other)
+        if not target:
+            base_claim["state"] = "need_manual"
+            base_claim["note"] = "判定为%s问题，但未配置%s负责人，无法转派" % (
+                SIDE_CN[other], SIDE_CN[other])
+            with _LOCK:
+                _STATE["claims"][bid] = base_claim
+                _save_locked()
+            _notify("🐛⚠️ 禅道 Bug #%s 判定为%s问题但未配负责人，请人工转派"
+                    % (bid, SIDE_CN[other]))
+            return "need_manual"
+        text = _transfer_text({"bug_id": bug.get("id"), "title": bug.get("title") or "",
+                               "triage": tri, "tasks": []}, profile, [], other)
+        try:
+            _transfer(cfg, bid, target, text)
+        except ZenError as e:
+            base_claim["state"] = "need_manual"
+            base_claim["note"] = "%s转派失败：%s" % (SIDE_CN[other], e)
+            with _LOCK:
+                _STATE["claims"][bid] = base_claim
+                _save_locked()
+            _notify("🐛⚠️ 禅道 Bug #%s 判定%s问题但转派失败：%s" % (bid, SIDE_CN[other], e))
+            return "need_manual"
+        base_claim.update({"state": "transferred",
+                           "note": "%s问题（测试原指派 %s），已转派 %s"
+                                   % (SIDE_CN[other], _acct(bug.get("assignedTo")) or "?", target)})
+        with _LOCK:
+            _STATE["claims"][bid] = base_claim
+            _save_locked()
+        _notify("🐛🔁 禅道 Bug #%s 判定%s问题，已转派 %s（原指派 %s）\n%s"
+                % (bid, SIDE_CN[other], target, _acct(bug.get("assignedTo")) or "?",
+                   bug.get("title") or ""))
+        return "transferred"
+
+    # 我方端：逐端建修复任务（任一端建不起来 → 整单留人工，不做半截修复）
+    tasks = []
+    try:
+        for side in sides:
+            task, run = _launch_fix(bug, profile, side, cfg)
+            tasks.append({"side": side, "task_id": task["id"], "run_id": run["id"],
+                          "state": "fixing"})
+    except Exception as e:
+        log.warning("zentao: bug %s 建修复任务失败：%s", bid, e)
+        base_claim["state"] = "need_manual"
+        base_claim["note"] = "建修复任务失败：%s" % e
+        with _LOCK:
+            _STATE["claims"][bid] = base_claim
+            _save_locked()
+        _notify("🐛⚠️ 禅道 Bug #%s 建修复任务失败：%s" % (bid, e))
+        return "need_manual"
+    base_claim["tasks"] = tasks
+    with _LOCK:
+        _STATE["claims"][bid] = base_claim
+        _save_locked()
+    _notify("🐛🔍 认领禅道 Bug #%s（%s问题·%s）：%s\n修复任务：%s"
+            % (bid, tri["side"], "由规则" if tri.get("by") == "rule" else "AI 判定",
+               bug.get("title") or "", "、".join(t["task_id"] for t in tasks)))
+    return "fixing"
+
+
+def _scan(cfg):
+    """按产品档案逐个拉 bug：认领新 bug + 重试 need_manual 的存量。返回认领数。"""
+    claimed = 0
+    profiles = _profiles(cfg)
+    if not profiles:
+        raise ZenError("未配置产品档案——请先在设置页添加产品并配置仓库")
+    for profile in profiles:
+        bugs = list_bugs(cfg, profile["product"])
+        by_id = {str(b.get("id") or ""): b for b in bugs}
+        with _LOCK:
+            seen = set(_STATE["claims"].keys())
+            retry_ids = [k for k, c in _STATE["claims"].items()
+                         if c.get("state") == "need_manual" and k in by_id
+                         and str(by_id[k].get("status") or "") == "active"]
+        for bug in bugs:
+            bid = str(bug.get("id") or "")
+            if not bid or bid in seen or not _claimable(bug, profile):
+                continue
+            _route_one(bug, profile, cfg, seen)
+            claimed += 1
+        # need_manual 重排查（bug 仍激活才出现在列表里）
+        for bid in retry_ids:
+            with _LOCK:
+                if _STATE["claims"].get(bid, {}).get("state") != "need_manual":
+                    continue
+            _route_one(by_id[bid], profile, cfg, set())
+    return claimed
+
+
+def _poll(force=False):
+    """一次完整轮询：对账回写 + （到点/强制时）扫描认领。异常不外抛。"""
+    _ensure_loaded()
+    with _LOCK:
+        cfg = _cfg()
+    out = {"ok": True, "claimed": 0, "reconciled": True, "error": ""}
+    try:
+        _reconcile(cfg)
+    except Exception:
+        log.exception("zentao: 对账异常")
+    if not force:
+        if not cfg.get("poll_enabled"):
+            return {"ok": True, "claimed": 0, "reconciled": True, "error": "",
+                    "skipped": "poll_disabled"}
+        with _LOCK:
+            nxt = _STATE.get("next_scan") or ""
+        if nxt:
+            try:
+                if datetime.fromisoformat(nxt) > datetime.now():
+                    return {"ok": True, "claimed": 0, "reconciled": True,
+                            "error": "", "skipped": "not_due"}
+            except ValueError:
+                pass
+    err = ""
+    try:
+        out["claimed"] = _scan(cfg)
+    except ZenError as e:
+        err = str(e)
+    except Exception as e:
+        err = "扫描失败：%s" % e
+        log.warning("zentao: %s", err)
+    now = datetime.now()
+    delay = timedelta(hours=max(INTERVAL_MIN, int(cfg.get("interval_hours") or 2)))
+    if err:
+        delay = timedelta(minutes=RETRY_DELAY_MIN)
+    with _LOCK:
+        _STATE["last_scan"] = now.strftime("%Y-%m-%d %H:%M:%S")
+        _STATE["next_scan"] = (now + delay).strftime("%Y-%m-%d %H:%M:%S")
+        _STATE["last_error"] = err
+        _save_locked()
+    out["error"] = err
+    out["ok"] = not err
+    return out
+
+
+def fire_due():
+    """automation._tick 每拍调用：内部自节流，没到点/未启用时零开销返回。"""
+    _ensure_loaded()
+    with _LOCK:
+        if not (_STATE.get("config") or {}).get("poll_enabled"):
+            return None
+    return _poll(force=False)
+
+
+def scan_now():
+    """手动「立即扫描」：绕过轮询闸与节流。"""
+    return _poll(force=True)
+
+
+def start():
+    """服务启动接线：加载状态（含老配置迁移）。"""
+    n = load()
+    with _LOCK:
+        cfg = _STATE.get("config") or {}
+        if cfg.get("poll_enabled") and not _STATE.get("next_scan"):
+            _STATE["next_scan"] = time.strftime("%Y-%m-%d %H:%M:%S")
+            _save_locked()
+    return n
+
+
+# ---------------------------------------------------------------- 配置管理
+
+def _norm_profile(p, idx):
+    if not isinstance(p, dict):
+        raise ValueError("产品档案 #%d 必须是对象" % idx)
+    try:
+        pid = int(p.get("product") or 0)
+    except (TypeError, ValueError):
+        raise ValueError("产品档案 #%d 的产品 ID 必须是整数" % idx)
+    if pid <= 0:
+        raise ValueError("产品档案 #%d 缺产品 ID" % idx)
+    prof = dict(_PROFILE_DEFAULTS)
+    prof["product"] = pid
+    prof["assigned_to"] = str(p.get("assigned_to") or "").strip()
+    try:
+        prof["severity_cap"] = max(0, min(4, int(p.get("severity_cap") or 0)))
+    except (TypeError, ValueError):
+        prof["severity_cap"] = 0
+    our = [s for s in SIDES if s in (p.get("our_sides") or [])]
+    prof["our_sides"] = our
+    repos = {"backend": dict(_REPO_DEFAULTS), "frontend": dict(_REPO_DEFAULTS)}
+    raw_repos = p.get("repos") if isinstance(p.get("repos"), dict) else {}
+    for side in SIDES:
+        r = raw_repos.get(side) if isinstance(raw_repos.get(side), dict) else {}
+        wd = str(r.get("workdir") or "").strip()
+        if wd:
+            rp = Path(wd).expanduser()
+            if not rp.is_absolute():
+                raise ValueError("产品 %d 的%s工作目录必须是绝对路径" % (pid, SIDE_CN[side]))
+            wd = str(rp)
+        repos[side] = {"workdir": wd,
+                       "git_rev": str(r.get("git_rev") or "").strip(),
+                       "verify_command": str(r.get("verify_command") or "").strip()}
+        # 我方端必须配仓库（our_sides 可为空=纯路由；但配了端没配目录到扫描时才暴露，
+        # 这里只拦「配置了 our_sides 却两个仓库目录都没有」的明显失误）
+    if our and not any(repos[s]["workdir"] for s in our):
+        raise ValueError("产品 %d：我方端已勾选但没有配置任何仓库工作目录" % pid)
+    prof["repos"] = repos
+    hints = {}
+    raw_hints = p.get("repo_hints") if isinstance(p.get("repo_hints"), dict) else {}
+    for side in SIDES:
+        hints[side] = str(raw_hints.get(side) or "").strip()
+    prof["repo_hints"] = hints
+    owners = {}
+    raw_owners = p.get("owners") if isinstance(p.get("owners"), dict) else {}
+    for k in ("backend", "frontend", "not_ours"):
+        owners[k] = str(raw_owners.get(k) or "").strip()
+    prof["owners"] = owners
+    routes = []
+    for r in (p.get("module_routes") or []):
+        if not isinstance(r, dict):
+            continue
+        try:
+            mid = int(r.get("module") or 0)
+        except (TypeError, ValueError):
+            raise ValueError("产品 %d 的模块路由：模块 ID 必须是整数" % pid)
+        if mid <= 0:
+            continue
+        side = str(r.get("side") or "")
+        if side not in TRIAGE_SIDES:
+            raise ValueError("产品 %d 的模块路由 side 必须是 %s 之一"
+                             % (pid, "/".join(TRIAGE_SIDES)))
+        routes.append({"module": mid, "side": side,
+                       "account": str(r.get("account") or "").strip()})
+    prof["module_routes"] = routes
+    return prof
+
+
+def _norm_profiles(v):
+    if v is None:
+        return None
+    if not isinstance(v, list):
+        raise ValueError("product_profiles 必须是数组")
+    out, seen = [], set()
+    for i, p in enumerate(v):
+        prof = _norm_profile(p, i)
+        if prof["product"] in seen:
+            raise ValueError("产品 %d 配置重复" % prof["product"])
+        seen.add(prof["product"])
+        out.append(prof)
+    return out
+
+
+def save_config(patch):
+    """部分更新配置（password 缺省或空串=不改；product_profiles 整体替换）。
+    校验失败抛 ValueError。返回脱敏视图的 config。"""
+    _ensure_loaded()
+    patch = patch if isinstance(patch, dict) else {}
+    with _LOCK:
+        cfg = _cfg()
+        for k in _UPDATABLE:
+            if k not in patch:
+                continue
+            v = patch[k]
+            if k == "base_url":
+                v = str(v or "").strip().rstrip("/")
+                if v and not v.startswith(("http://", "https://")):
+                    raise ValueError("禅道地址必须以 http:// 或 https:// 开头")
+            elif k == "account":
+                v = str(v or "").strip()
+            elif k == "password":
+                v = str(v or "")
+                if not v:
+                    continue
+            elif k == "product_profiles":
+                v = _norm_profiles(v)
+                if v is None:
+                    continue
+            elif k == "interval_hours":
+                try:
+                    v = max(INTERVAL_MIN, min(INTERVAL_MAX, int(v)))
+                except (TypeError, ValueError):
+                    raise ValueError("interval_hours 必须是 %d-%d 的整数"
+                                     % (INTERVAL_MIN, INTERVAL_MAX))
+            elif k in ("auto_resolve", "auto_merge", "triage_ai", "poll_enabled"):
+                v = bool(v)
+            cfg[k] = v
+        _STATE["config"] = cfg
+        if cfg.get("poll_enabled"):
+            _STATE["next_scan"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        _save_locked()
+    return view()["config"]
+
+
+def view():
+    """前端视图：配置脱敏（password 只回是否已设）+ claims 列表（新在前）。"""
+    _ensure_loaded()
+    with _LOCK:
+        cfg = dict(_cfg())
+        has_pw = bool(cfg.get("password"))
+        cfg["password"] = ""
+        cfg["has_password"] = has_pw
+        claims = sorted(_STATE["claims"].values(),
+                        key=lambda c: str(c.get("claimed_at") or ""), reverse=True)
+        return {"config": cfg,
+                "claims": [dict(c) for c in claims],
+                "last_scan": _STATE.get("last_scan") or "",
+                "next_scan": _STATE.get("next_scan") or "",
+                "last_error": _STATE.get("last_error") or ""}
+
+
+def _test_reset():
+    """测试钩子：清空内存状态（配合重绑 _FILE + TUTTI_DATA 临时目录用）。"""
+    with _LOCK:
+        _STATE["config"] = dict(_CFG_DEFAULTS)
+        _STATE["claims"] = {}
+        _STATE["last_scan"] = _STATE["next_scan"] = _STATE["last_error"] = ""
+        _reset_token()
+        globals()["_LOADED"] = True