@hupan56/wlkj 3.1.32 → 3.3.0

package/templates/qoder/scripts/domain/integration/return_to_platform.py

@@ -0,0 +1,392 @@
+# -*- coding: utf-8 -*-
+"""
+integration.return_to_platform —— 引擎产出回流平台的统一通道。
+
+设计模式: Facade（封装"产出→平台"的回流细节，供命令/脚本一键调用）
+
+历史断点（已修）:
+    引擎产出 PRD/原型只写本地 workspace/members/{dev}/drafts/，永不回平台，
+    平台 AI回流 Tab 永远空。原因: 全仓 grep submit_return/create_prd/create_prototype
+    在 wlinkj-workflow 下 0 匹配 —— 引擎根本不知道有回流这回事。
+
+本模块提供两条回流路径，任一可用即回流成功:
+    1. MCP 写工具（首选）: cap.mcp.call("submit_return"|"create_prd"|"create_prototype")
+       平台 MCP 已暴露这 4 个写工具（已验证真落库，进 returns/prd/asset/prototype 表）。
+    2. HTTP return_endpoint（兜底）: 读 mcp_config.json 的 return_endpoint.url，
+       直接 POST 回流 JSON（MCP 不可用 / 工具未索引时用）。
+
+调用方: 命令脚本（.py）/ 命令文档（.md 里通过 wlkj.py return 子命令）。
+失败兜底: 全程 try/except，回流失败只记日志，绝不影响主流程产出（PRD/原型照常落地）。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _load_mcp_config() -> dict:
+    """读 wlinkj-workflow/mcp_config.json，失败返回空 dict。"""
+    import json as _json
+    from pathlib import Path
+
+    try:
+        from foundation.core.paths import get_repo_root
+        repo = get_repo_root()
+    except Exception:
+        repo = Path(__file__).resolve().parent.parent.parent.parent.parent
+    for cand in [
+        repo / "mcp_config.json",
+        repo / "wlinkj-workflow" / "mcp_config.json",
+    ]:
+        try:
+            if cand.is_file():
+                with open(cand, encoding="utf-8") as f:
+                    return _json.load(f)
+        except Exception:
+            continue
+    return {}
+
+
+def _truncate(text: str, n: int = 500) -> str:
+    """安全截断，避免超长 content_preview 塞爆 MCP/HTTP。"""
+    if not text:
+        return ""
+    return text if len(text) <= n else (text[:n] + "…")
+
+
+def _read_file_text(path: str) -> str:
+    """安全读文件全文，失败返回空串。"""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+def _project_id() -> Optional[str]:
+    """从 mcp_config.json 读 WLKJ_PROJECT_ID（平台项目 UUID）。"""
+    cfg = _load_mcp_config()
+    for srv in (cfg.get("mcpServers") or {}).values():
+        env = srv.get("env") or {}
+        if env.get("WLKJ_PROJECT_ID"):
+            return env["WLKJ_PROJECT_ID"]
+    return None
+
+
+def _via_mcp(tool: str, args: dict) -> tuple[bool, str]:
+    """通过 cap.mcp.call 走 MCP 写工具回流。
+    ★ 自动注入 project_id（平台写工具强制要，防写错项目）。
+
+    Returns:
+        (ok, message): ok=True 表示非错误返回。
+    """
+    try:
+        # 注入 project_id（写工具必需）
+        pid = _project_id()
+        if pid and "project_id" not in args:
+            args = {**args, "project_id": pid}
+        from capability import resolve
+        cap = resolve()
+        result = cap.mcp.call(tool, args)
+        ok = not getattr(result, "is_error", False)
+        msg = getattr(result, "text", "") or ("ok" if ok else "error")
+        return ok, msg[:200]
+    except Exception as e:
+        return False, "MCP回流异常: %s" % str(e)[:120]
+
+
+def _via_http(payload: dict) -> tuple[bool, str]:
+    """HTTP 兜底: 读 mcp_config.json 的 return_endpoint 直接 POST。
+    ★ 带 X-Engine-Token 头（平台项目级鉴权）。
+    """
+    import json as _json
+    import urllib.request
+    import urllib.error
+
+    cfg = _load_mcp_config()
+    ep = (cfg.get("return_endpoint") or {})
+    url = ep.get("url")
+    if not url:
+        return False, "mcp_config.json 无 return_endpoint.url"
+    method = ep.get("method", "POST")
+    data = _json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    # headers: 配置里的 + Content-Type
+    headers = {"Content-Type": "application/json"}
+    headers.update(ep.get("headers") or {})
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            body = resp.read().decode("utf-8", errors="replace")
+        return True, body[:200]
+    except Exception as e:
+        return False, "HTTP回流失败: %s" % str(e)[:120]
+
+
+def _platform_base() -> str:
+    """平台 base url（http://127.0.0.1:10010），从 mcp_config server url 推导。"""
+    from urllib.parse import urlparse
+    cfg = _load_mcp_config()
+    for srv in (cfg.get("mcpServers") or {}).values():
+        url = srv.get("url") or ""
+        if url:
+            p = urlparse(url)
+            return "%s://%s" % (p.scheme, p.netloc)
+    ep = (cfg.get("return_endpoint") or {}).get("url") or ""
+    if ep:
+        p = urlparse(ep)
+        return "%s://%s" % (p.scheme, p.netloc)
+    return "http://127.0.0.1:10010"
+
+
+def _engine_token() -> Optional[str]:
+    """X-Engine-Token（mcp_config return_endpoint.headers 优先，server token 兜底）。"""
+    cfg = _load_mcp_config()
+    for k, v in ((cfg.get("return_endpoint") or {}).get("headers") or {}).items():
+        if k.lower() in ("x-engine-token", "x-return-token"):
+            return v
+    for srv in (cfg.get("mcpServers") or {}).values():
+        if srv.get("token"):
+            return srv["token"]
+    return None
+
+
+def _post_to_platform(path: str, payload: dict, timeout: int = 15) -> tuple[bool, str]:
+    """POST JSON 到平台任意端点（带 X-Engine-Token 鉴权）。
+
+    path: 相对路径如 /api/git/commits/record；base 从 mcp_config server url 推导。
+    供 commit/spec 等"非 return_endpoint"端点回流复用。
+    """
+    import json as _json
+    import urllib.request
+    token = _engine_token()
+    if not token:
+        return False, "无 X-Engine-Token（mcp_config 未配）"
+    url = _platform_base().rstrip("/") + "/" + path.lstrip("/")
+    data = _json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers={
+        "Content-Type": "application/json", "X-Engine-Token": token,
+    }, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return True, resp.read().decode("utf-8", errors="replace")[:200]
+    except Exception as e:
+        return False, "POST %s 失败: %s" % (path, str(e)[:120])
+
+
+def submit_prd(prd_path: str, title: str, source: str = "wlkj/wl-prd",
+               platform: Optional[str] = None,
+               version_id: Optional[str] = None,
+               requirement_id: Optional[str] = None) -> dict:
+    """回流一份 PRD 到平台。
+
+    优先 create_prd（写 PRD 表），失败再 submit_return（写 returns 待审核），
+    最后 HTTP 兜底。任一成功即返回 ok=True。
+
+    Args:
+        prd_path: PRD markdown 文件路径。
+        title: PRD 标题。
+        source: 来源标识。
+        platform: 平台（web/app，可选）。
+        version_id: 引擎工作流版本ID（关联平台 PRD.version_id）。
+        requirement_id: 禅道需求ID（关联平台 PRD.requirement_id）。
+    Returns:
+        {"ok": bool, "via": "create_prd|submit_return|http|none", "message": str}
+    """
+    content_md = _read_file_text(prd_path)
+    if not content_md:
+        return {"ok": False, "via": "none", "message": "PRD 文件为空或读不到: %s" % prd_path}
+
+    # 1) MCP submit_return（回流审核队列——默认路径！引擎产出先进 AI回流 Tab，人工确认后才入库）
+    return_args = {
+        "title": title, "return_type": "prd", "source": source,
+        "content_preview": _truncate(content_md),
+        "content_full": content_md,
+        "target_location": "PRD草稿",
+    }
+    if version_id:
+        return_args["relations"] = "version_id=%s" % version_id
+    if requirement_id:
+        return_args["relations"] = (return_args.get("relations", "") + " requirement_id=%s" % requirement_id).strip()
+    ok, msg = _via_mcp("submit_return", return_args)
+    if ok:
+        return {"ok": True, "via": "submit_return", "message": "回流成功，待平台审核入库"}
+
+    # 2) create_prd 兜底（submit_return 失败才直写，标记 publish_status=published）
+    create_args = {
+        "title": title, "content_md": content_md, "status": "planning",
+        "publish_status": "published",
+    }
+    if version_id:
+        create_args["version_id"] = version_id
+    if requirement_id:
+        create_args["requirement_id"] = requirement_id
+    ok, msg = _via_mcp("create_prd", create_args)
+    if ok:
+        return {"ok": True, "via": "create_prd", "message": msg}
+
+    # 3) HTTP 兜底
+    ok, msg = _via_http({
+        "title": title, "return_type": "prd", "source": source,
+        "content_preview": _truncate(content_md), "content_full": content_md,
+    })
+    return {"ok": ok, "via": "http" if ok else "none", "message": msg}
+
+
+def submit_prototype(proto_path: str, feature: str, platform: str = "web",
+                     source: str = "wlkj/wl-design") -> dict:
+    """回流一份原型（HTML）到平台。
+
+    优先 create_prototype（写 prototype 表 + 存文件），失败 submit_return，
+    最后 HTTP 兜底。
+
+    Args:
+        proto_path: 原型 HTML 文件路径。
+        feature: 功能名。
+        platform: web/app。
+        source: 来源标识。
+    Returns:
+        {"ok": bool, "via": str, "message": str}
+    """
+    html = _read_file_text(proto_path)
+    if not html:
+        return {"ok": False, "via": "none", "message": "原型文件为空或读不到: %s" % proto_path}
+
+    # 1) MCP create_prototype（写 prototype + 存 HTML 文件，最完整）
+    ok, msg = _via_mcp("create_prototype", {
+        "feature": feature, "platform": platform, "html_content": html,
+    })
+    if ok:
+        return {"ok": True, "via": "create_prototype", "message": msg}
+
+    # 2) MCP submit_return
+    ok, msg = _via_mcp("submit_return", {
+        "title": "原型-%s-%s" % (platform, feature),
+        "return_type": "prototype", "source": source,
+        "content_preview": _truncate(html),
+        "content_full": html,
+        "relations": "platform=%s;feature=%s" % (platform, feature),
+    })
+    if ok:
+        return {"ok": True, "via": "submit_return", "message": msg}
+
+    # 3) HTTP 兜底
+    ok, msg = _via_http({
+        "title": "原型-%s-%s" % (platform, feature),
+        "return_type": "prototype", "source": source,
+        "content_preview": _truncate(html), "content_full": html,
+    })
+    return {"ok": ok, "via": "http" if ok else "none", "message": msg}
+
+
+def submit_commit(commit_hash: str, message: str, author: str = "",
+                  repo: str = "", pushed_at: str = "") -> dict:
+    """回流一次 git commit 到平台（git_commits 表 + fixes/implements 边）。
+
+    平台端点 POST /api/git/commits/record（X-Engine-Token 鉴权，token→project_id）。
+    commit→需求关联靠 message 里的 [#REQ-xxx] / [#<禅道号>] 标记，平台 commit_pipeline
+    自动解析建边 —— 故 message 必须原样带提交信息（含需求标记），不在此剥离。
+
+    Args:
+        commit_hash: git commit SHA。
+        message: 完整提交信息（含 [#REQ-xxx] 需求标记）。
+        author: 提交者。
+        repo: 仓库 remote url（可选）。
+        pushed_at: ISO 时间（可选）。
+    Returns:
+        {"ok": bool, "via": "record_commit|none", "message": str}
+    """
+    if not commit_hash or not message:
+        return {"ok": False, "via": "none", "message": "缺 commit_hash/message"}
+    # EngineCallbackIngestor 期望 {sha, message, author, repo, pushed_at}
+    payload = {
+        "sha": commit_hash, "message": message, "author": author,
+        "repo": repo, "pushed_at": pushed_at,
+    }
+    ok, msg = _post_to_platform("/api/git/commits/record", payload)
+    return {"ok": ok, "via": "record_commit" if ok else "none", "message": msg}
+
+
+def _flag_value(args: list, flag: str, default: str = "") -> str:
+    """从 argv 取 --flag value（无则 default）。"""
+    if flag in args:
+        i = args.index(flag)
+        return args[i + 1] if i + 1 < len(args) else default
+    return default
+
+
+def _git_repo_url() -> str:
+    """取当前 git 仓库 remote.origin.url（失败空串）。"""
+    import subprocess
+    try:
+        return subprocess.check_output(
+            ["git", "config", "--get", "remote.origin.url"], encoding="utf-8"
+        ).strip()
+    except Exception:
+        return ""
+
+
+def _cli_commit(rest: list) -> dict:
+    """commit 回流子命令：--last 自动取 HEAD，或显式 <hash> <message>。"""
+    if "--last" in rest:
+        import subprocess
+        try:
+            # %B = 完整 message（含 subject + body，[#REQ-xxx] 在 body 也能解析）
+            fmt = "%H%x1f%B%x1f%an%x1f%aI"
+            out = subprocess.check_output(
+                ["git", "log", "-1", "--format=" + fmt], encoding="utf-8"
+            )
+            parts = out.split("\x1f")
+            sha = parts[0].strip()
+            body = parts[1].strip()
+            author = parts[2].strip()
+            ts = parts[3].strip()
+            return submit_commit(sha, body, author=author,
+                                 repo=_git_repo_url(), pushed_at=ts)
+        except Exception as e:
+            return {"ok": False, "via": "none",
+                    "message": "取 HEAD commit 失败: %s" % str(e)[:120]}
+    if len(rest) < 2:
+        return {"ok": False, "via": "none",
+                "message": "用法: commit <hash> <message> [--author X] [--repo Y]  或  commit --last"}
+    sha, msg = rest[0], rest[1]
+    return submit_commit(sha, msg,
+                         author=_flag_value(rest, "--author"),
+                         repo=_flag_value(rest, "--repo"),
+                         pushed_at=_flag_value(rest, "--pushed-at"))
+
+
+def cli_main() -> int:
+    """命令行入口（供 wlkj.py return 子命令调用）。
+
+    用法:
+        python -m domain.integration.return_to_platform prd <path> <title> [--platform web]
+        python -m domain.integration.return_to_platform prototype <path> <feature> [--platform web]
+        python -m domain.integration.return_to_platform commit --last     # 自动回流 HEAD commit
+        python -m domain.integration.return_to_platform commit <hash> <msg> [--author X] [--repo Y]
+    退出码: 0=回流成功(含MCP/HTTP), 1=参数错误(主流程不受影响)。
+    """
+    import sys
+    args = sys.argv[1:]
+    if not args or args[0] not in ("prd", "prototype", "commit"):
+        print("[return] 用法: return <prd|prototype|commit> ...  (commit 支持 --last 自动取 HEAD)")
+        return 1
+    kind = args[0]
+
+    if kind == "commit":
+        r = _cli_commit(args[1:])
+    else:
+        if len(args) < 3:
+            print("[return] 用法: return %s <文件路径> <标题|功能名> [--platform web]" % kind)
+            return 1
+        path, name = args[1], args[2]
+        platform = _flag_value(args, "--platform", "web")
+        r = submit_prd(path, name, platform=platform) if kind == "prd" \
+            else submit_prototype(path, name, platform=platform)
+
+    tag = "✅" if r["ok"] else "⚠️"
+    print("%s [回流] via=%s %s" % (tag, r["via"], r["message"]))
+    # 回流失败返回 0 —— 主流程产出已落地，回流是增强不是阻塞
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli_main())

package/templates/qoder/scripts/domain/integration/spec_upload.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""integration.spec_upload —— 开发 SPEC 制品回流平台（引擎侧客户端）。
+
+背景: wlinkj-workspace/docs/ENGINE-SPEC-UPLOAD.md §4.2（wl-spec 第 7-9 步）
+契约: wlinkj-workspace/docs/SPEC-MCP-CONTRACT.md v1（create/confirm/update/get_spec）
+
+流程: 解析契约头 → 有platform_spec_id走update/无走create → confirm → 回写幂等锚
+传输: POST /mcp direct JSON-RPC + X-MCP-Token（同 engine/poller.py:_mcp_call）
+"""
+from __future__ import annotations
+import json, os, re, sys, urllib.request, urllib.error
+from typing import Optional, Tuple
+
+# 直接运行时把 .qoder/scripts 注入 sys.path（让 foundation.* 可 import）
+_SCRIPT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _SCRIPT_ROOT not in sys.path:
+    sys.path.insert(0, _SCRIPT_ROOT)
+
+
+def _load_mcp_config() -> dict:
+    from pathlib import Path
+    try:
+        from foundation.core.paths import get_repo_root
+        repo = get_repo_root()
+    except Exception:
+        repo = Path(__file__).resolve().parent.parent.parent.parent.parent
+    for cand in [repo / "mcp_config.json",
+                 repo / "wlinkj-workflow" / "mcp_config.json",
+                 repo / ".qoder" / "mcp_config.json"]:
+        try:
+            if cand.is_file():
+                with open(cand, encoding="utf-8") as f:
+                    return json.load(f)
+        except Exception:
+            continue
+    return {}
+
+
+def _resolve_endpoint() -> Tuple[str, str, str]:
+    """返回 (base, token, pid)。env 覆盖 > mcp_config.json。"""
+    cfg = _load_mcp_config()
+    base = os.environ.get("WLKJ_MCP_BASE")
+    if not base:
+        ep = cfg.get("return_endpoint") or {}
+        url = ep.get("url", "")
+        base = url.split("/api/")[0] if "/api/" in url else ""
+        if not base:
+            for srv in (cfg.get("mcpServers") or {}).values():
+                u = srv.get("url", "")
+                if "/mcp" in u:
+                    base = u.split("/mcp")[0]; break
+    base = (base or "http://127.0.0.1:10010").rstrip("/")
+    token = os.environ.get("WLKJ_MCP_TOKEN", "")
+    if not token:
+        for srv in (cfg.get("mcpServers") or {}).values():
+            t = srv.get("token", "")
+            if t and "WILL_BE_FILLED" not in t:
+                token = t; break
+    pid = os.environ.get("WLKJ_PROJECT_ID", "")
+    if not pid:
+        for srv in (cfg.get("mcpServers") or {}).values():
+            env = srv.get("env") or {}
+            p = env.get("WLKJ_PROJECT_ID", "")
+            if p and "WILL_BE_FILLED" not in p:
+                pid = p; break
+    return base, token, pid
+
+
+def _mcp_call(base: str, token: str, tool: str, args: dict) -> dict:
+    """POST /mcp JSON-RPC tools/call，解析 result.content[0].text。"""
+    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {"name": tool, "arguments": args}}
+    req = urllib.request.Request(base + "/mcp",
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json", "X-MCP-Token": token}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            r = json.loads(resp.read().decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        try: return {"error": "HTTP %d: %s" % (e.code, e.read().decode("utf-8","replace")[:200])}
+        except Exception: return {"error": "HTTP %d" % e.code}
+    except Exception as e:
+        return {"error": "网络异常: %s" % str(e)[:150]}
+    if r.get("error"):
+        return {"error": "JSON-RPC error: %s" % str(r["error"])[:200]}
+    text = (r.get("result", {}).get("content") or [{}])[0].get("text", "")
+    try:
+        return json.loads(text) if text else {}
+    except Exception:
+        return {"error": "结果非 JSON: %s" % text[:200]}
+
+
+_CONTRACT_RE = re.compile(r"<!--\s*@contract\s+spec[^\n]*\n(?P<body>.*?)-->", re.DOTALL)
+
+def parse_spec_contract(md: str) -> dict:
+    fields = {}
+    m = _CONTRACT_RE.search(md)
+    if m:
+        for line in m.group("body").splitlines():
+            if ":" in line:
+                k, _, v = line.partition(":")
+                fields[k.strip()] = v.strip()
+    title = ""
+    for line in md.splitlines():
+        if line.startswith("# "):
+            title = line[2:].strip(); break
+    zentao_id = fields.get("zentao_id", "")
+    if not zentao_id:
+        mt = re.search(r"story\s*=\s*(\d+)", fields.get("zentao", ""))
+        zentao_id = mt.group(1) if mt else ""
+    return {"title": title, "zentao_id": zentao_id,
+            "platform_spec_id": fields.get("platform_spec_id", ""),
+            "source_prd_id": fields.get("source_prd_id") or fields.get("source-req", ""),
+            "content_md": md}
+
+def write_back_platform_spec_id(md: str, spec_id: str) -> str:
+    m = _CONTRACT_RE.search(md)
+    if not m: return md
+    body = m.group("body")
+    if re.search(r"^\s*platform_spec_id\s*:", body, re.MULTILINE):
+        new_body = re.sub(r"(\bplatform_spec_id[ \t]*:[ \t]*)[^\n]*", r"\g<1>%s" % spec_id, body)
+    else:
+        new_body = body.rstrip() + "\nplatform_spec_id: %s\n" % spec_id
+    return md[:m.start("body")] + new_body + md[m.end("body"):]
+
+
+def upload_spec(spec_path: str, zentao_id_override: Optional[str] = None,
+                code_targets: Optional[list] = None) -> dict:
+    try:
+        with open(spec_path, encoding="utf-8", errors="replace") as f:
+            md = f.read()
+    except Exception as e:
+        return {"ok": False, "via": "none", "message": "读不到 spec: %s" % e}
+
+    c = parse_spec_contract(md)
+    title = c["title"] or os.path.splitext(os.path.basename(spec_path))[0]
+    zentao_id = zentao_id_override or c["zentao_id"]
+    if not zentao_id:
+        return {"ok": False, "via": "none",
+                "message": "缺 zentao_id（契约头无且未 --zentao-id）—— 取消（无关联键）"}
+
+    base, token, pid = _resolve_endpoint()
+    if not token:
+        return {"ok": False, "via": "none",
+                "message": "mcp_config.json 未绑定 token（先 /wl-init）或设 WLKJ_MCP_TOKEN"}
+
+    code_targets = code_targets or []
+    existing_id = c["platform_spec_id"]
+
+    # 1) create 或 update（幂等）
+    if existing_id:
+        r = _mcp_call(base, token, "update_spec",
+                      {"spec_id": existing_id, "content_md": c["content_md"]})
+        via, spec_id, version = "update_spec", existing_id, r.get("version")
+    else:
+        args = {"title": title, "zentao_id": zentao_id, "content_md": c["content_md"]}
+        if pid: args["project_id"] = pid
+        if c["source_prd_id"]: args["source_prd_id"] = c["source_prd_id"]
+        r = _mcp_call(base, token, "create_spec", args)
+        via, spec_id, version = "create_spec", r.get("id"), r.get("version")
+
+    if r.get("error") or not spec_id:
+        return {"ok": False, "via": via, "message": r.get("error", "无 spec_id 返回")}
+
+    # 2) confirm（draft→confirmed）
+    rc = _mcp_call(base, token, "confirm_spec",
+                   {"spec_id": spec_id, "code_targets": code_targets})
+    status = rc.get("status", "")
+
+    # 3) 回写幂等锚（仅 create 后）
+    if not existing_id:
+        try:
+            new_md = write_back_platform_spec_id(md, spec_id)
+            with open(spec_path, "w", encoding="utf-8") as f:
+                f.write(new_md)
+        except Exception:
+            pass
+
+    return {"ok": True, "platform_spec_id": spec_id, "via": via,
+            "status": status or r.get("status", ""), "version": version,
+            "requirement_id": r.get("requirement_id"),
+            "created_new": r.get("created_new"),
+            "message": "上传成功：%s（zentao_id=%s → requirement_id=%s）" % (
+                title, zentao_id, r.get("requirement_id"))}
+
+
+def cli_main() -> int:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        print("用法: python -m domain.integration.spec_upload <spec.md> "
+              "[--zentao-id N] [--code-targets A,B]"); return 1
+    spec_path = args[0]
+    zentao_id = None; code_targets = []
+    if "--zentao-id" in args:
+        i = args.index("--zentao-id")
+        zentao_id = args[i+1] if i+1 < len(args) else None
+    if "--code-targets" in args:
+        i = args.index("--code-targets")
+        code_targets = [x.strip() for x in args[i+1].split(",")] if i+1 < len(args) else []
+    r = upload_spec(spec_path, zentao_id_override=zentao_id, code_targets=code_targets)
+    print("%s [spec-upload] via=%s %s" % ("✅" if r["ok"] else "⚠️", r["via"], r["message"]))
+    if r["ok"]:
+        print("   platform_spec_id=%s status=%s version=%s" % (
+            r["platform_spec_id"], r["status"], r["version"]))
+    return 0  # 上传失败返回0：本地spec已落地，上传是增强不阻塞
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli_main())