@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/foundation/identity/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 foundation.identity.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 foundation.data.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 → foundation/identity}/identity.py

@@ -41,8 +41,8 @@ from typing import Optional, Dict, Any, Union
 
 # 相对导入兄弟模块
 try:
-    from .atomicio import atomic_write_json, safe_read_json
-    from .paths import get_repo_root, MEMBERS_DIR
+    from foundation.io.atomicio import atomic_write_json, safe_read_json
+    from foundation.core.paths import get_repo_root, MEMBERS_DIR
 except ImportError:
     _COMMON_DIR = os.path.dirname(os.path.abspath(__file__))
     if _COMMON_DIR not in sys.path:
@@ -52,7 +52,7 @@ except ImportError:
     _SCRIPTS_DIR = os.path.dirname(_COMMON_DIR)
     if _SCRIPTS_DIR not in sys.path:
         sys.path.insert(0, _SCRIPTS_DIR)
-    from common.paths import get_repo_root, MEMBERS_DIR
+    from foundation.core.paths import get_repo_root, MEMBERS_DIR
 
 __all__ = [
     "IdentityError",
@@ -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 foundation.core.paths import get_private_file
+        return get_private_file("signing_key", name)
+    except Exception:
+        return _member_dir(name, repo_root) / ".signing_key"
 
 
 # ============================================================
@@ -192,6 +204,10 @@ def register_member(
             or "%s <unknown@local>" % name
         ),
         "joined_at": joined_at,
+        # 禅道账号映射 (v3.1.3): 本地 developer 名(如 hupan56) ↔ 禅道 account(如 hupan)
+        # 不一致时, zentao_sync 靠此过滤归属 (见 contracts/isolation.md「禅道同步」)。
+        # 首次注册留空 (None), 成员后续填; 已注册的保留原值不覆盖。
+        "zentao_account": (existing.get("zentao_account") if existing else None),
     }
     atomic_write_json(mj, record)
     return record
@@ -260,11 +276,11 @@ def require_member(name: Optional[str] = None, repo_root: Optional[Union[str, Pa
     """
     if name is None:
         try:
-            from .developer_paths import get_developer
+            from foundation.core.paths import get_developer
         except ImportError:
             _this = os.path.dirname(os.path.abspath(__file__))
             sys.path.insert(0, _this)
-            from paths import get_developer  # type: ignore
+            from foundation.core.paths import get_developer  # type: ignore
         name = get_developer(repo_root)
     if not name:
         sys.stderr.write("[authz] 拒绝: 未设置开发者身份。先跑 /wl-init 注册。\n")
@@ -280,11 +296,118 @@ def require_member(name: Optional[str] = None, repo_root: Optional[Union[str, Pa
 def ensure_current_member(repo_root: Optional[Union[str, Path]] = None) -> Optional[str]:
     """软检查: 返回当前已验证的成员名, 或 None (不 exit)。给非破坏性命令用。"""
     try:
-        from paths import get_developer
+        from foundation.core.paths import get_developer
     except ImportError:
         sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-        from paths import get_developer  # type: ignore
+        from foundation.core.paths import get_developer  # type: ignore
     name = get_developer(repo_root)
     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 foundation.core.paths import get_developer, get_developer_info
+        except ImportError:
+            sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+            from foundation.core.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)

package/templates/qoder/scripts/foundation/identity/roles.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+"""
+roles.py - 角色章节过滤 (单一真源, 消除 kg.py↔kg_mcp_server.py 逐字重复)
+
+现状: ROLE_SECTIONS 字典 + _filter_by_role 函数在 kg.py(:645-672) 和
+kg_mcp_server.py(:249-276) 逐字重复。改一处忘改另一处 → CLI 和 MCP 行为分叉。
+
+本模块作为单一真源, kg.py 和 kg_mcp_server.py 都从这里 import。
+
+过滤规则: 按角色裁剪 context_pack 输出的章节 (## 1. / ## 2. / ## 2b. 等),
+让不同角色只看到与其职责相关的段落, 减少噪音。
+
+Usage:
+    from foundation.identity.roles import filter_by_role, ROLE_SECTIONS
+    text = filter_by_role(context_pack_output, role='pm')
+"""
+
+import re
+
+__all__ = ["ROLE_SECTIONS", "filter_by_role"]
+
+# 各角色可见的 context_pack 章节号
+# (与 kg.py ROLE_SECTIONS / kg_mcp_server.py ROLE_SECTIONS 对齐, 此处为唯一真源)
+ROLE_SECTIONS = {
+    'pm':     {'1', '2', '2b', '3', '4', '5', '7'},  # PM: 字段+PRD+API，无代码噪音
+    'design': {'2', '2b', '3', '6'},                  # 设计: 页面+布局+字段+风格
+    'dev':    {'1', '3', '5', '7'},                   # 开发: 代码+字段+API+wiki
+    'test':   {'1', '4', '5'},                        # 测试: 代码+PRD+API
+    'admin':  {'4', '5'},                             # 管理: PRD+API 概览
+}
+
+
+def filter_by_role(text, role):
+    """按角色过滤 context_pack 输出的章节。
+
+    Args:
+        text: context_pack 的多段输出 (## 1. xxx / ## 2. xxx ...)
+        role: 角色名 (pm/design/dev/test/admin), 未知角色不过滤
+
+    Returns:
+        过滤后的文本 (只保留该角色可见章节)
+    """
+    visible = ROLE_SECTIONS.get((role or '').lower())
+    if not visible:
+        return text  # 未知角色不过滤
+    # 按 "## 数字." 切段 (含 2b 这种带字母的)
+    sections = re.split(r'(\n## \d+[ab]?\.)', text)
+    result = sections[0]
+    i = 1
+    while i < len(sections):
+        header = sections[i]
+        num_m = re.match(r'\n## (\d+[ab]?)\.', header)
+        if num_m and num_m.group(1) in visible:
+            result += header
+            if i + 1 < len(sections):
+                result += sections[i + 1]
+            i += 2
+        else:
+            i += 2
+    return result.strip()

package/templates/qoder/scripts/{common → foundation/integrations}/active_task.py

@@ -28,15 +28,30 @@ from pathlib import Path
 from typing import Any
 
 # 支持的 AI 平台及其会话环境变量
-_ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
-    ("qoder", ("QODER_SESSION_ID",)),
-    ("codex", ("CODEX_SESSION_ID", "CODEX_THREAD_ID")),
-    ("claude", ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")),
-    ("cursor", ("CURSOR_SESSION_ID",)),
-    ("opencode", ("OPENCODE_SESSION_ID", "OPENCODE_RUN_ID")),
-    ("gemini", ("GEMINI_SESSION_ID",)),
-    ("copilot", ("COPILOT_SESSION_ID",)),
-)
+# -----------------------------------------------------------------------------
+# 单一事实源: nexus.registry.HOST_TABLE（宿主能力抽象层）。
+# 本表从 HOST_TABLE 派生，保持 tuple[tuple[str, tuple[str, ...]]] 格式兼容。
+# 新增宿主只需改 nexus.HOST_TABLE 一处，active_task 自动跟随。
+# nexus 不可用时回退到内联定义（向后兼容，零破坏）。
+# -----------------------------------------------------------------------------
+try:
+    from capability.registry import HOST_TABLE as _HOST_TABLE
+
+    _ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = tuple(
+        (name, tuple(info.get("detect", ())))
+        for name, info in _HOST_TABLE.items()
+        if name != "cli" and info.get("detect")
+    )
+except ImportError:
+    _ENV_SESSION_KEYS = (
+        ("qoderwork", ("QODER_SESSION_ID",)),
+        ("codex", ("CODEX_SESSION_ID", "CODEX_THREAD_ID")),
+        ("claude", ("CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")),
+        ("cursor", ("CURSOR_SESSION_ID",)),
+        ("opencode", ("OPENCODE_SESSION_ID", "OPENCODE_RUN_ID")),
+        ("gemini", ("GEMINI_SESSION_ID",)),
+        ("copilot", ("COPILOT_SESSION_ID",)),
+    )
 
 
 @dataclass(frozen=True)
@@ -127,7 +142,7 @@ def resolve_active_task(repo_root: Path | None = None) -> ActiveTask:
         ActiveTask 对象。
     """
     if repo_root is None:
-        from common.paths import get_repo_root
+        from foundation.core.paths import get_repo_root
         repo_root = get_repo_root()
 
     # 1. 尝试会话级
@@ -147,7 +162,7 @@ def resolve_active_task(repo_root: Path | None = None) -> ActiveTask:
                 pass
 
     # 2. 后备: 全局文件
-    from common.paths import get_current_task
+    from foundation.core.paths import get_current_task
     global_task = get_current_task(repo_root)
     if global_task:
         return ActiveTask(
@@ -170,13 +185,13 @@ def set_active_task(task_path: str, repo_root: Path | None = None) -> ActiveTask
         ActiveTask 对象, 无会话身份则返回 None。
     """
     if repo_root is None:
-        from common.paths import get_repo_root
+        from foundation.core.paths import get_repo_root
         repo_root = get_repo_root()
 
     session_key = resolve_context_key()
     if not session_key:
         # 无会话身份, 使用全局后备
-        from common.paths import set_current_task
+        from foundation.core.paths import set_current_task
         set_current_task(task_path, repo_root)
         return ActiveTask(
             task_path=task_path,
@@ -208,7 +223,7 @@ def clear_active_task(repo_root: Path | None = None) -> ActiveTask:
         清除前的 ActiveTask 状态。
     """
     if repo_root is None:
-        from common.paths import get_repo_root
+        from foundation.core.paths import get_repo_root
         repo_root = get_repo_root()
 
     # 获取清除前的状态
@@ -224,7 +239,7 @@ def clear_active_task(repo_root: Path | None = None) -> ActiveTask:
             pass
 
     # 也清除全局后备
-    from common.paths import set_current_task
+    from foundation.core.paths import set_current_task
     set_current_task(None, repo_root)
 
     return active

package/templates/qoder/scripts/{common → foundation/integrations}/feishu.py

@@ -57,20 +57,21 @@ 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 foundation.core.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
+            from foundation.core.paths import get_repo_root
             cfg_path = os.path.join(str(get_repo_root()), '.qoder', 'config.yaml')
             in_feishu = False
             with open(cfg_path, encoding='utf-8') as f:

package/templates/qoder/scripts/{common → foundation/integrations}/terms.py

@@ -12,7 +12,7 @@ of these maps in other scripts - import from here.
 # 性能优化 A6: 从 40 词扩展到 ~120 词, 覆盖库存/采购/供应商/客户/财务/工单等通用业务域
 CN_MAP = {
     # 考勤/人事
-    '考勤': 'attendance clock', '打卡': 'clock', '签到': 'sign',
+    '考勤': 'attendance', '打卡': 'clock', '签到': 'sign',
     '薪资': 'salary', '工资': 'salary', '请假': 'leave', '休假': 'leave',
     '加班': 'overtime', '员工': 'employee staff', '用户': 'user',
     '组织': 'org department', '部门': 'department', '岗位': 'position role',
@@ -108,8 +108,8 @@ CN_MAP = {
 # so building and querying use the same semantics.
 BUSINESS_PATH_MAP = {
     '保险': ['insurance', 'Insurance', 'ins-', '/ins/', 'vehlife/insurance'],
-    '考勤': ['attendance', 'Attendance', 'clock', 'Clock', 'time/clock', 'TimeClock'],
-    '打卡': ['clock', 'Clock', 'photoClock', 'PhotoClock'],
+    '考勤': ['attendance', 'Attendance', 'Attend', 'timeManage', 'TimeWork'],
+    '打卡': ['clock', 'Clock', 'photoClock', 'PhotoClock', 'time/clock', 'TimeClock'],
     '车辆': ['vehicle', 'Vehicle', 'veh', 'vehlife', '/veh/'],
     '品质': ['quality', 'Quality', 'QualityInspection', 'patrol', 'Patrol'],
     '巡查': ['inspection', 'Inspection', 'patrol', 'Patrol'],