@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/common/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 common.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 .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/developer.py

@@ -147,9 +147,10 @@ def init_developer(name: str, role: str | None = None,
         return False
 
     # 2. 创建个人工作空间 workspace/members/<name>/
+    # v3.0 M3: 个人目录 = member.json + drafts + outputs + journal + .private
     personal = repo_root / "workspace" / "members" / name
     try:
-        for sub in ("journal", "drafts", "inbox"):
+        for sub in ("journal", "drafts", "outputs", ".private", ".private/secrets"):
             (personal / sub).mkdir(parents=True, exist_ok=True)
     except (OSError, IOError) as e:
         print(f"Error: Failed to create workspace directory: {e}", file=sys.stderr)

package/templates/qoder/scripts/common/feishu.py

@@ -57,18 +57,19 @@ THEME_COLORS = {
 
 
 def _load_config():
-    """加载飞书配置 (config.yaml + 环境变量)。"""
-    # 读 config.yaml 的 feishu 段
+    """加载飞书配置 (config.yaml + 环境变量)。
+
+    v3.0: 优先用 Config 单例 (带缓存), 失败回退文本解析。
+    """
     config = {}
     try:
-        import yaml
-        from .paths import get_repo_root
-        cfg_path = os.path.join(str(get_repo_root()), '.qoder', 'config.yaml')
-        with open(cfg_path, encoding='utf-8') as f:
-            full = yaml.safe_load(f) or {}
-        config = full.get('feishu') or {}
+        # 优先: Config 单例 (mtime 缓存, 避免每次重读)
+        from .config import Config, SECTIONS
+        config = Config.load().section(SECTIONS.FEISHU, {})
     except Exception:
-        # PyYAML 不可用, 用简单解析
+        pass
+    if not config:
+        # 回退: 简单文本解析 (PyYAML 不可用时)
         try:
             from .paths import get_repo_root
             cfg_path = os.path.join(str(get_repo_root()), '.qoder', 'config.yaml')

package/templates/qoder/scripts/common/guard.py

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""
+guard.py - 角色能力边界守卫 (解耦的执行点)
+
+把角色从"标签"变成"边界"。各角色在能力边界内自治, 互不越界 = 解耦。
+
+现状: role.py 只查询角色名, config.yaml 的 permissions 声明了但从不强制。
+本次: guard.py 在"产出动作前"校验角色能否产出该契约类型, 越权则降级 (不报错)。
+
+设计原则 (与方案一致):
+  - 降级而非阻塞: 越权不报错/不崩溃, 而是降级 (转给有权限的人 / 标记待确认)
+    这与契约层的"降级不停摆"哲学一致
+  - 软边界: 默认不强制 (ensure=False), 调用方显式 ensure=True 才硬拦
+  - 可观测: 每次越权都留痕 (返回 Result + hint), 让 AI/用户知道发生了什么
+
+核心 API:
+    check_produce(contract_type, role=None, ensure=False) -> Result
+        检查当前角色能否产出某契约
+        ensure=False (默认): 越权返回 WARN (降级提示, 不阻塞)
+        ensure=True: 越权返回 FAIL (硬拦, 给破坏性操作用)
+    current_role() -> str | None
+        当前角色名 (identity.get_role 的便捷封装)
+
+Usage:
+    from common.guard import check_produce
+    r = check_produce('unit-test')
+    if not r.ok:
+        print(r.hint)   # "你的角色 pm 不能产出 unit-test, 需 dev/test 角色"
+        return          # 降级: 不执行产出
+    # ... 继续产出 unit-test
+"""
+
+import os
+import sys
+
+try:
+    from .result import Result, CODE
+    from .identity import get_role, can_produce, can_consume, get_role_config
+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 identity import get_role, can_produce, can_consume, get_role_config
+
+__all__ = [
+    "check_produce",
+    "check_consume",
+    "current_role",
+    "suggest_role_for",
+]
+
+# 角色中文名映射 (给提示文案用)
+_ROLE_CN = {
+    "pm": "产品经理",
+    "design": "设计师",
+    "dev": "开发",
+    "test": "测试",
+    "admin": "管理员",
+}
+
+
+def current_role() -> str:
+    """当前角色名。未初始化/未注册 → 回退 'pm' (软引导, 与 role.py 一致)。"""
+    return get_role() or "pm"
+
+
+def _role_cn(role: str) -> str:
+    return _ROLE_CN.get(role, role)
+
+
+def suggest_role_for(contract_type: str) -> list:
+    """建议"哪些角色能产出该契约", 给越权提示用。"""
+    # 反查 config.yaml 哪些角色的 can_produce 含此类型或 '*'
+    try:
+        from .identity import _load_roles_config
+    except ImportError:
+        from identity import _load_roles_config
+    roles_cfg = _load_roles_config()
+    out = []
+    for r, cfg in roles_cfg.items():
+        caps = list(cfg.get("can_produce", []) or [])
+        if "*" in caps or contract_type in caps:
+            out.append(r)
+    return out
+
+
+def check_produce(
+    contract_type: str,
+    role: str = None,
+    ensure: bool = False,
+) -> Result:
+    """检查角色能否产出某契约类型。
+
+    Args:
+        contract_type: 契约类型 (prd/prototype/spec/design-spec/code/unit-test/test-report)
+        role: 角色名, 不传则用当前角色
+        ensure: False=越权返回WARN(降级); True=越权返回FAIL(硬拦)
+
+    Returns:
+        Result.ok + CODE.OK:    允许产出
+        Result (WARN):          越权但降级 (ensure=False), 带 hint 提示该找谁
+        Result (FAIL):          越权且硬拦 (ensure=True)
+    """
+    role = role or current_role()
+    if can_produce(role, contract_type):
+        return Result.success(msg="✓ {} 可产出 {}".format(_role_cn(role), contract_type))
+    # 越权
+    suggest = suggest_role_for(contract_type)
+    suggest_cn = "、".join(_role_cn(r) for r in suggest) if suggest else "对应角色"
+    hint = "你的角色({})不能产出 {}, 需 {} 角色。用 /wl-init 切换或转交。".format(
+        _role_cn(role), contract_type, suggest_cn
+    )
+    if ensure:
+        return Result.failure(
+            "[越权] {} 不能产出 {}".format(_role_cn(role), contract_type),
+            code=CODE.AUTHZ,
+            hint=hint,
+        )
+    # 降级: 不阻塞, 但强烈提示
+    return Result.warning(
+        "⚠️ {} 通常不产出 {} (建议 {})".format(_role_cn(role), contract_type, suggest_cn),
+        code=CODE.AUTHZ,
+        hint=hint,
+    )
+
+
+def check_consume(
+    capability: str,
+    role: str = None,
+) -> Result:
+    """检查角色能否读取/消费某能力。越权则只读降级 (永远不阻塞)。"""
+    role = role or current_role()
+    if can_consume(role, capability):
+        return Result.success(msg="✓ {} 可消费 {}".format(_role_cn(role), capability))
+    return Result.warning(
+        "⚠️ {} 读取 {} 超出常规职责 (只读降级)".format(_role_cn(role), capability),
+        code=CODE.AUTHZ,
+        hint="这是软提示, 仍可继续 (越权只读降级, 不阻塞)",
+    )
+
+
+# ============================================================
+# CLI (供 skill 脚本诊断用)
+# ============================================================
+
+if __name__ == "__main__":
+    import json
+    role = current_role()
+    print("当前角色: {} ({})".format(role, _role_cn(role)))
+    cfg = get_role_config(role)
+    print("  can_produce: {}".format(cfg.get("can_produce", [])))
+    print("  can_consume: {}".format(cfg.get("can_consume", [])))
+    if len(sys.argv) > 1:
+        ct = sys.argv[1]
+        r = check_produce(ct)
+        print("\n能否产出 {}: {}".format(ct, "能" if r.ok and not r.is_warn else "否"))
+        if r.hint:
+            print("  -> {}".format(r.hint))

package/templates/qoder/scripts/common/identity.py

@@ -65,9 +65,16 @@ __all__ = [
     "verify_signature",
     "require_member",
     "ensure_current_member",
+    # ★ 角色能力 (v3.0 合并自 role.py) ★
+    "get_role",
+    "get_role_config",
+    "get_capabilities",
+    "get_permissions",
+    "can_produce",
+    "can_consume",
 ]
 
-# 退出码 (全脚本统一): 4 = authz_denied
+# 退出码 (与 common/result.py 的 EXIT[AUTHZ] 对齐): 4 = authz_denied
 EXIT_AUTHZ = 4
 
 # 名字合法字符: 字母/数字/中文/下划线/短横, 2-32 字符
@@ -96,7 +103,12 @@ def _member_json(name: str, repo_root: Optional[Union[str, Path]] = None) -> Pat
 
 
 def _key_file(name: str, repo_root: Optional[Union[str, Path]] = None) -> Path:
-    return _member_dir(name, repo_root) / ".signing_key"
+    """签名密钥路径 (v3.0: 收进 .private/signing_key, 向后兼容老 .signing_key)。"""
+    try:
+        from .paths import get_private_file
+        return get_private_file("signing_key", name)
+    except Exception:
+        return _member_dir(name, repo_root) / ".signing_key"
 
 
 # ============================================================
@@ -288,3 +300,110 @@ def ensure_current_member(repo_root: Optional[Union[str, Path]] = None) -> Optio
     if name and verify_member(name, repo_root):
         return name
     return None
+
+
+# ============================================================
+# 角色能力 (v3.0 合并自 role.py —— 角色从"标签"升级为"能力边界")
+#
+# config.yaml 的 roles 段升级为能力声明:
+#   roles.<role>.can_produce: [prd, prototype, ...]   允许产出的契约类型
+#   roles.<role>.can_consume: ["*", prd, ...]          允许读取的能力
+# guard.py 据此强制边界: 越权降级 (不报错), 各角色在边界内自治 = 解耦
+#
+# 向后兼容: get_role / get_permissions 保留 (老脚本可继续用)
+# ============================================================
+
+def _load_roles_config(repo_root: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
+    """读 config.yaml 的 roles 段。失败返回 {} (软降级, 不崩)。"""
+    if repo_root is None:
+        repo_root = get_repo_root()
+    cfg = Path(repo_root) / ".qoder" / "config.yaml"
+    if not cfg.is_file():
+        return {}
+    try:
+        import yaml
+        with open(cfg, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        return data.get("roles", {}) or {}
+    except Exception:
+        return {}
+
+
+def get_role(name: Optional[str] = None, repo_root: Optional[Union[str, Path]] = None) -> Optional[str]:
+    """返回成员的角色名 (pm/design/dev/test/admin)。
+
+    优先级:
+      1. .developer 里记录的 role (init 时写)
+      2. member.json 里的 role
+      3. None (未注册)
+    无角色默认回退 'pm' (软引导, 不报错) —— 与原 role.py 行为一致。
+    """
+    if not name:
+        # 从 .developer 读
+        try:
+            from paths import get_developer, get_developer_info
+        except ImportError:
+            sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+            from paths import get_developer, get_developer_info  # type: ignore
+        info = get_developer_info(repo_root) if "get_developer_info" in dir() else None
+        if isinstance(info, dict) and info.get("role"):
+            return info["role"]
+        name = get_developer(repo_root)
+    if not name:
+        return None
+    m = get_member(name, repo_root)
+    return m.get("role") if m else None
+
+
+def get_role_config(role: Optional[str], repo_root: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
+    """返回某角色的完整配置 (can_produce/can_consume/commands/permissions/name)。
+
+    角色不存在或 config 缺失 → 返回 {} (软降级)。
+    """
+    if not role:
+        return {}
+    return _load_roles_config(repo_root).get(role, {}) or {}
+
+
+def get_permissions(role: Optional[str], repo_root: Optional[Union[str, Path]] = None) -> list:
+    """遗留 API: 返回角色的 permissions 列表 (向后兼容)。空则 []。"""
+    return list(get_role_config(role, repo_root).get("permissions", []) or [])
+
+
+def get_capabilities(
+    role: Optional[str], kind: str = "produce", repo_root: Optional[Union[str, Path]] = None
+) -> list:
+    """返回角色的能力列表。
+
+    Args:
+        role: 角色名
+        kind: 'produce' (能产出哪些契约) 或 'consume' (能读哪些)
+    Returns:
+        能力列表, 含 '*' 表示无限制。未知角色返回 [] (从严, 无能力)。
+    """
+    key = "can_produce" if kind == "produce" else "can_consume"
+    caps = get_role_config(role, repo_root).get(key, [])
+    return list(caps) if caps else []
+
+
+def _has(cap_list: list, contract_type: str) -> bool:
+    """判断 contract_type 是否在能力列表内 ('*' 通配)。"""
+    if not cap_list:
+        return False
+    if "*" in cap_list:
+        return True
+    return contract_type in cap_list
+
+
+def can_produce(
+    role: Optional[str], contract_type: str, repo_root: Optional[Union[str, Path]] = None
+) -> bool:
+    """该角色能否产出指定契约类型? guard.py 的核心查询。"""
+    return _has(get_capabilities(role, "produce", repo_root), contract_type)
+
+
+def can_consume(
+    role: Optional[str], capability: str, repo_root: Optional[Union[str, Path]] = None
+) -> bool:
+    """该角色能否读取/消费指定能力? 越权则只读降级。"""
+    return _has(get_capabilities(role, "consume", repo_root), capability)