@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/foundation/data/contract.py

@@ -0,0 +1,317 @@
+# -*- coding: utf-8 -*-
+"""
+contract.py - 契约校验器 (解耦模块的核心)
+
+把"君子协定"变成机器可校验。每个产出 (PRD/原型/spec/design-spec/test-cases)
+带 @contract 头, 本模块解析头部 + 按 contracts/schemas/*.schema.json 校验。
+
+设计原则 (与方案一致):
+  - 解耦: 模块间只读契约产出, 不读对方实现。实现可任意替换。
+  - 降级而非阻塞: 校验 FAIL 只提示, 不让模块停摆 (符合 contract-header.md)
+  - 轻量: 不引 jsonschema 重依赖, 用 stdlib 实现核心校验 (类型/必填/枚举/正则)
+  - 兼容现有: 复用现有 @contract 头格式 (MD 的 HTML 注释 / JSON 的 _contract 字段)
+
+核心 API:
+    parse_contract(path) -> (contract_dict, source_text)
+        解析文件的契约头 (MD/JSON 两种)
+    validate_contract(path) -> Result
+        解析 + 按 schema 校验, 返回统一 Result
+    extract_contract_header(md_text) -> dict | None
+        从 Markdown 正文提取 <!-- @contract ... --> 块
+
+Usage:
+    from foundation.data.contract import validate_contract
+    r = validate_contract('workspace/.../REQ-2026-001-prd.md')
+    if r.is_warn:
+        print('警告:', r.msg)   # 软门禁: 带警告继续
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+# 相对导入
+try:
+    from .result import Result, CODE
+    from foundation.io.atomicio import safe_read_json
+except ImportError:
+    _COMMON_DIR = os.path.dirname(os.path.abspath(__file__))
+    if _COMMON_DIR not in sys.path:
+        sys.path.insert(0, _COMMON_DIR)
+    from result import Result, CODE
+    from atomicio import safe_read_json
+
+__all__ = [
+    "parse_contract",
+    "validate_contract",
+    "extract_contract_header",
+    "extract_json_contract",
+    "SCHEMAS_DIR",
+]
+
+# schemas 目录 (相对仓库根: .qoder/contracts/schemas/)
+def _find_schemas_dir() -> Path:
+    """定位 contracts/schemas/。向上找 .qoder/contracts/schemas/。"""
+    here = Path(__file__).resolve().parent
+    for _ in range(8):
+        cand = here / "contracts" / "schemas"
+        if cand.is_dir():
+            return cand
+        # common/ 在 .qoder/scripts/common/, schemas 在 .qoder/contracts/schemas/
+        cand2 = here.parent.parent / "contracts" / "schemas"
+        if cand2.is_dir():
+            return cand2
+        parent = here.parent
+        if parent == here:
+            break
+        here = parent
+    return Path(".qoder/contracts/schemas")
+
+
+SCHEMAS_DIR = _find_schemas_dir()
+
+# 契约类型 → schema 文件名映射
+_SCHEMA_FILES = {
+    "prd": "prd.schema.json",
+    "design-spec": "design-spec.schema.json",
+    "design": "design-spec.schema.json",  # 别名
+    "test-cases": "test-cases.schema.json",
+    "test": "test-cases.schema.json",  # 别名
+}
+
+
+# ============================================================
+# 1. 契约头解析
+# ============================================================
+
+# MD 契约头: <!-- @contract prd v1\n platform: web\n ... -->
+_MD_CONTRACT_RE = re.compile(
+    r"<!--\s*@contract\s+(\S+)(?:\s+v?(\d+))?\s*\n(.*?)-->",
+    re.DOTALL,
+)
+# 契约头内的 key: value 行
+_KV_RE = re.compile(r"^\s*([\w\-]+)\s*:\s*(.+?)\s*$")
+
+
+def extract_contract_header(md_text: str) -> Optional[Dict[str, Any]]:
+    """从 Markdown 正文提取 @contract 块。
+
+    格式 (见 contract-header.md):
+        <!-- @contract prd v1
+        platform: web
+        req-id: REQ-2025-0042
+        title: 保单批改功能
+        acceptance: [批改后实时生效, 批改需审批]
+        -->
+    """
+    m = _MD_CONTRACT_RE.search(md_text)
+    if not m:
+        return None
+    ctype = m.group(1).strip()
+    version = int(m.group(2)) if m.group(2) else 1
+    body = m.group(3)
+    fields: Dict[str, Any] = {"type": ctype, "version": version}
+    for line in body.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        kv = _KV_RE.match(line)
+        if kv:
+            key = kv.group(1).strip()
+            val = kv.group(2).strip()
+            # acceptance: [a, b] → 列表
+            if val.startswith("[") and val.endswith("]"):
+                inner = val[1:-1]
+                fields[key] = [x.strip() for x in inner.split(",") if x.strip()]
+            else:
+                fields[key] = val
+    return fields
+
+
+def extract_json_contract(data: dict) -> Optional[Dict[str, Any]]:
+    """从 JSON dict 提取 _contract 字段 (design-spec / test-cases 用)。"""
+    if isinstance(data, dict) and isinstance(data.get("_contract"), dict):
+        c = dict(data["_contract"])
+        # 补默认 type/version (schema 里 required, 但容错)
+        c.setdefault("type", c.get("type", "unknown"))
+        c.setdefault("version", 1)
+        return c
+    return None
+
+
+def parse_contract(path) -> Tuple[Optional[Dict[str, Any]], str]:
+    """解析任意文件的契约头。
+
+    Returns:
+        (contract_dict, source_text)
+        - contract_dict: 解析出的契约字段, 无则 None
+        - source_text: 'md' / 'json' / 'unknown'
+    """
+    path = Path(path)
+    if not path.is_file():
+        return None, "unknown"
+    name = path.name.lower()
+    try:
+        if name.endswith(".json"):
+            data = safe_read_json(path, default=None)
+            if data is None:
+                return None, "json"
+            return extract_json_contract(data), "json"
+        # 当作文本 (md 等)
+        text = path.read_text(encoding="utf-8", errors="replace")
+        hdr = extract_contract_header(text)
+        return hdr, "md"
+    except Exception:
+        return None, "unknown"
+
+
+# ============================================================
+# 2. 轻量 schema 校验 (不引 jsonschema, stdlib 实现)
+# ============================================================
+
+def _load_schema(contract_type: str) -> Optional[dict]:
+    """按契约类型加载对应 schema.json。"""
+    fname = _SCHEMA_FILES.get(contract_type)
+    if not fname:
+        return None
+    sp = SCHEMAS_DIR / fname
+    if not sp.is_file():
+        return None
+    try:
+        return json.loads(sp.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _check_field(field: str, value: Any, spec: dict, errors: list, warnings: list):
+    """校验单个字段 (类型/枚举/正则/最小长度)。"""
+    if spec.get("const") is not None and value != spec["const"]:
+        errors.append("字段 {} 必须为常量 {!r}, 实际 {!r}".format(field, spec["const"], value))
+        return
+    t = spec.get("type")
+    if t == "string" and not isinstance(value, str):
+        errors.append("字段 {} 应为 string".format(field))
+        return
+    if t == "integer" and not isinstance(value, int):
+        errors.append("字段 {} 应为 integer".format(field))
+        return
+    if t == "array" and not isinstance(value, list):
+        errors.append("字段 {} 应为 array".format(field))
+        return
+    if t == "object" and not isinstance(value, dict):
+        errors.append("字段 {} 应为 object".format(field))
+        return
+    if "enum" in spec and value not in spec["enum"]:
+        errors.append("字段 {} 值 {!r} 不在允许范围 {}".format(field, value, spec["enum"]))
+        return
+    if "pattern" in spec and isinstance(value, str):
+        pat = spec["pattern"]
+        if not re.match(pat, value):
+            errors.append("字段 {} 值 {!r} 不匹配模式 {}".format(field, value, pat))
+            return
+    if "minLength" in spec and isinstance(value, str) and len(value) < spec["minLength"]:
+        warnings.append("字段 {} 长度 {} 小于最小 {} ".format(field, len(value), spec["minLength"]))
+    if "minItems" in spec and isinstance(value, list) and len(value) < spec["minItems"]:
+        warnings.append("字段 {} 项数 {} 小于最小 {} ".format(field, len(value), spec["minItems"]))
+    if "minimum" in spec and isinstance(value, (int, float)) and value < spec["minimum"]:
+        errors.append("字段 {} 值 {} 小于最小 {}".format(field, value, spec["minimum"]))
+
+
+def _validate_against_schema(data: dict, schema: dict) -> Tuple[list, list]:
+    """按 schema 校验 data。返回 (errors, warnings)。"""
+    errors: list = []
+    warnings: list = []
+    required = schema.get("required", [])
+    props = schema.get("properties", {})
+    # required 检查
+    for f in required:
+        if f not in data:
+            errors.append("缺少必填字段: {}".format(f))
+    # 逐字段校验
+    for f, val in data.items():
+        if f in props:
+            _check_field(f, val, props[f], errors, warnings)
+    return errors, warnings
+
+
+# ============================================================
+# 3. 对外主接口
+# ============================================================
+
+def validate_contract(path) -> Result:
+    """校验一个产出文件的契约。
+
+    Returns:
+        Result:
+          - ok + CODE.OK:   合法契约, 校验通过
+          - ok + WARN:      有警告 (如字段长度不足), 但可继续 (软门禁)
+          - fail:           有错误 (缺必填/类型错/枚举越界)
+          - ok + code='no_contract': 无契约头 (降级, 不当错误, 返回 None 提示)
+
+    降级原则: 无契约头或 schema 缺失 → 不当错误 (符合 contract-header.md)
+    """
+    path = Path(path)
+    if not path.is_file():
+        return Result.failure(
+            "文件不存在: {}".format(path),
+            code=CODE.NOT_FOUND,
+            hint="检查路径",
+        )
+    contract, src = parse_contract(path)
+    if not contract:
+        # 无契约头: 降级, 不当错误
+        return Result.success(
+            msg="⚠️ {} 无 @contract 头, 已降级 (从头文件名/正文推断)".format(path.name),
+            code="no_contract",
+        )
+    ctype = contract.get("type", "")
+    schema = _load_schema(ctype)
+    if not schema:
+        return Result.warning(
+            "契约类型 {!r} 无对应 schema, 跳过校验".format(ctype),
+            code="no_schema",
+        )
+    errors, warnings = _validate_against_schema(contract, schema)
+    if errors:
+        return Result.failure(
+            "契约校验失败 ({}): {}".format(path.name, "; ".join(errors[:3])),
+            code=CODE.GENERIC,
+            hint="按 contracts/schemas/{} 修正".format(_SCHEMA_FILES.get(ctype, ctype + ".schema.json")),
+        )
+    if warnings:
+        return Result.warning(
+            "契约有警告 ({}): {}".format(path.name, "; ".join(warnings[:3])),
+            code=CODE.BELOW_THRESH,
+        )
+    return Result.success(
+        data={"type": ctype, "req-id": contract.get("req-id"), "platform": contract.get("platform")},
+        msg="✓ 契约校验通过 ({} v{})".format(ctype, contract.get("version", 1)),
+    )
+
+
+# ============================================================
+# CLI
+# ============================================================
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("用法: python contract.py <产出文件>")
+        print("  校验 PRD/原型/spec/design-spec/test-cases 的 @contract 头")
+        sys.exit(1)
+    # 简单 CLI: 复用 graceful_error 风格
+    target = sys.argv[1]
+    r = validate_contract(target)
+    if r.is_warn:
+        print("[WARN] {}".format(r.msg))
+        if r.hint:
+            print("       -> {}".format(r.hint))
+        sys.exit(0)
+    if not r.ok:
+        print("[FAIL] {}".format(r.msg))
+        if r.hint:
+            print("       -> {}".format(r.hint))
+        sys.exit(1)
+    print(r.msg)

package/templates/qoder/scripts/{common → foundation/data}/events.py

@@ -18,8 +18,8 @@
 # 新增埋点: 在这里加一行 → learn.py 计数 + learn_aggregate.py SQL 自动生效
 EVENT_TYPES = {
     # PRD 链路
-    'prd_accepted':   {'stat': 'prds_generated',  'skill': 'wl-prd-full',   'label': 'PRD 发布'},
-    'prd_rejected':   {'stat': 'rejections',      'skill': 'wl-prd-full',   'label': 'PRD 打回'},
+    'prd_accepted':   {'stat': 'prds_generated',  'skill': 'prd-generator', 'label': 'PRD 发布'},
+    'prd_rejected':   {'stat': 'rejections',      'skill': 'prd-generator', 'label': 'PRD 打回'},
     'review_done':    {'stat': 'reviews_done',    'skill': 'prd-review',    'label': 'PRD 评审'},
     # 设计链路
     'design_import':  {'stat': 'designs_imported','skill': 'design-import', 'label': '设计录入'},

package/templates/qoder/scripts/foundation/data/result.py

@@ -0,0 +1,223 @@
+# -*- coding: utf-8 -*-
+"""
+result.py - 统一结果类型 + 优雅错误处理
+
+治"容错率低"的底层基建。现状各脚本错误风格极不统一:
+  - 裸 except Exception: pass 吞异常 (build_style_index / eval_prd / team_sync)
+  - exit code 含义不一致 (eval_prd 1=不达标或文件不存在; team_sync 0/1/2/3 四档)
+  - 调用方只能 parse 中文文案, 无法程序化决策
+
+本模块引入:
+  1. Result 数据类: ok / code / msg / data, 语义化 code
+  2. graceful_error 装饰器: 把 Result/异常翻译成"人类/AI 可读文本 + 一致 exit code"
+  3. 统一 exit code 表 (替代散落各处的魔法数字)
+
+设计原则 (与方案一致):
+  - 失败不崩, 输出可读诊断 + 建议下一步
+  - 调用方能据 code 程序化决策, 不靠 parse 中文
+  - eval_prd 门禁从"硬阻塞"改"软门禁" (WARN 带警告发布)
+
+Usage:
+    from foundation.data.result import Result, OK, fail, warn, graceful_error
+
+    @graceful_error
+    def main():
+        r = do_something()
+        if not r.ok:
+            return r          # 装饰器翻译成可读输出 + exit code
+        return Result.ok(data=r.data)
+
+Exit code 约定 (全脚本统一, 替代散落魔法数字):
+    0  OK           成功
+    1  GENERIC      通用失败 (未分类)
+    2  BUSY         资源占用 (如 kg_db 被占)
+    3  CONFLICT     冲突需人工 (如 team_sync SYNC_CONFLICT)
+    4  AUTHZ        身份/权限拒绝 (与 identity.EXIT_AUTHZ 对齐)
+    5  NOT_FOUND    文件/资源不存在
+    6  INDEX_MISSING 索引缺失 (需先 init/doctor)
+    7  BELOW_THRESH  门禁未达标 (eval_prd, 软门禁可带警告继续)
+    8  NETWORK      网络/外部服务不可达
+    9  DEPS_MISSING 依赖未装 (pip 包缺失)
+"""
+
+import functools
+import sys
+import traceback
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+__all__ = [
+    "Result",
+    "OK",
+    "ResultError",
+    "ok",
+    "fail",
+    "warn",
+    "graceful_error",
+    "EXIT",
+    "code_to_exit",
+    "CODE",
+]
+
+
+# ============================================================
+# 语义化 code 常量 (调用方据此程序化决策)
+# ============================================================
+
+class CODE:
+    """结果 code 常量。小写字符串, 语义化, 跨脚本一致。"""
+    OK = "ok"
+    GENERIC = "generic"            # 通用未分类
+    BUSY = "busy"                  # 资源占用 (kg_db 锁)
+    CONFLICT = "conflict"          # 冲突需人工
+    AUTHZ = "authz"                # 身份/权限
+    NOT_FOUND = "not_found"        # 文件/资源不存在
+    INDEX_MISSING = "index_missing"  # 索引缺失
+    BELOW_THRESH = "below_thresh"  # 门禁未达标
+    NETWORK = "network"            # 网络不可达
+    DEPS_MISSING = "deps_missing"  # 依赖未装
+
+
+# ============================================================
+# code → exit code 映射 (一处定义, 全脚本统一)
+# ============================================================
+
+EXIT = {
+    CODE.OK: 0,
+    CODE.GENERIC: 1,
+    CODE.BUSY: 2,
+    CODE.CONFLICT: 3,
+    CODE.AUTHZ: 4,
+    CODE.NOT_FOUND: 5,
+    CODE.INDEX_MISSING: 6,
+    CODE.BELOW_THRESH: 7,
+    CODE.NETWORK: 8,
+    CODE.DEPS_MISSING: 9,
+}
+
+
+def code_to_exit(code: str) -> int:
+    """code → exit code, 未知 code 回退 1。"""
+    return EXIT.get(code, 1)
+
+
+# ============================================================
+# Result 数据类
+# ============================================================
+
+@dataclass
+class Result:
+    """统一结果。
+
+    Attributes:
+        ok:     是否成功
+        code:   语义化 code (见 CODE 常量), 调用方据此决策
+        msg:    人类可读消息
+        data:   成功时携带的数据 (任意)
+        hint:   失败时的"下一步建议" (可选, 输出给用户/AI)
+    """
+    ok: bool
+    code: str = CODE.GENERIC
+    msg: str = ""
+    data: Any = None
+    hint: Optional[str] = None
+
+    # ---- 工厂方法 ----
+    @classmethod
+    def success(cls, data: Any = None, msg: str = "", code: str = CODE.OK) -> "Result":
+        return cls(ok=True, code=code, msg=msg, data=data)
+
+    @classmethod
+    def failure(cls, msg: str, code: str = CODE.GENERIC,
+                hint: Optional[str] = None, data: Any = None) -> "Result":
+        return cls(ok=False, code=code, msg=msg, hint=hint, data=data)
+
+    @classmethod
+    def warning(cls, msg: str, code: str = CODE.BELOW_THRESH,
+                hint: Optional[str] = None, data: Any = None) -> "Result":
+        """WARN: 软门禁/带警告继续。ok=True (可继续), 但带警告。"""
+        return cls(ok=True, code=code, msg=msg, hint=hint, data=data)
+
+    # ---- 便捷判断 ----
+    @property
+    def is_warn(self) -> bool:
+        """是否为"成功但有警告"(如门禁 WARN 档)。"""
+        return self.ok and self.code != CODE.OK
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+# 模块级便捷别名 (常见用法)
+OK = Result.success()
+ResultError = type("ResultError", (Exception,), {})  # 预留: 未来 raise Result(r)
+
+
+def ok(data: Any = None, msg: str = "") -> Result:
+    return Result.success(data=data, msg=msg)
+
+
+def fail(msg: str, code: str = CODE.GENERIC, hint: Optional[str] = None) -> Result:
+    return Result.failure(msg=msg, code=code, hint=hint)
+
+
+def warn(msg: str, code: str = CODE.BELOW_THRESH, hint: Optional[str] = None) -> Result:
+    return Result.warning(msg=msg, code=code, hint=hint)
+
+
+# ============================================================
+# graceful_error 装饰器
+# ============================================================
+
+def _emit(r: Result, *, exit_on_fail: bool = True) -> int:
+    """把 Result 翻译成可读输出 + 返回 exit code。"""
+    if r.ok and not r.is_warn:
+        if r.msg:
+            print(r.msg)
+        return 0
+    if r.is_warn:
+        # WARN: 打印警告但不当失败
+        print("[WARN] {}".format(r.msg))
+        if r.hint:
+            print("       -> {}".format(r.hint))
+        return code_to_exit(r.code) if False else 0  # WARN 视为成功 (exit 0)
+    # FAIL
+    tag = r.code.upper() if r.code != CODE.GENERIC else "ERROR"
+    print("[{}] {}".format(tag, r.msg))
+    if r.hint:
+        print("       -> {}".format(r.hint))
+    if exit_on_fail:
+        sys.exit(code_to_exit(r.code))
+    return code_to_exit(r.code)
+
+
+def graceful_error(func):
+    """装饰 main(): 统一把返回值 (Result/None/int) 翻译成可读输出 + exit code。
+
+    - 返回 Result: 按 ok/code 翻译
+    - 返回 int:    直接当 exit code
+    - 返回 None:   视为成功 (exit 0)
+    - 抛异常:      捕获, 输出诊断 + traceback (失败不崩 → 但 main 层崩溃要可见)
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            ret = func(*args, **kwargs)
+        except SystemExit:
+            raise
+        except KeyboardInterrupt:
+            print("\n[中断] 用户取消")
+            sys.exit(130)
+        except Exception as e:
+            # 未捕获异常: 输出诊断 + 简短 traceback, 不静默吞
+            print("[ERROR] 未预期异常: {}".format(e))
+            print("       -> 这是 bug, 请反馈。traceback:")
+            traceback.print_exc()
+            sys.exit(1)
+        if isinstance(ret, Result):
+            return _emit(ret)
+        if isinstance(ret, int):
+            sys.exit(ret)
+        # None / 其他: 成功
+        return 0
+    return wrapper