@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/foundation/bootstrap.py

@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+"""
+bootstrap.py - 统一 CLI 启动样板 (DRY) + 子目录化路径自举 (v3.0)
+
+治"70处 sys.path + 50处 reconfigure" + 子目录化后的路径定位。
+
+子目录化后, 脚本在 scripts/domain/kg/kg.py, 它的 dirname(__file__)=scripts/domain/kg/,
+直接 sys.path.insert(scripts/domain/kg/) 后 `from foundation.x` 会断 (foundation 在 scripts/foundation/)。
+
+本模块的 setup() 解决: 无论脚本在 scripts/ 根还是 scripts/某子包/,
+都能正确定位 scripts/ 根并注入, 让 `from foundation.x` 和跨包 import 都能用。
+
+核心: _find_scripts_root() 向上找含 'foundation/' 子目录的那个目录 = scripts/ 根。
+
+Usage (两种姿势):
+    # 姿势1: 子包脚本开头 (推荐)
+    import os, sys
+    _S = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # 子包→scripts
+    if _S not in sys.path: sys.path.insert(0, _S)
+    from bootstrap import setup; setup()
+
+    # 姿势2: scripts/ 根脚本 (老姿势仍可用)
+    from bootstrap import setup; setup()
+"""
+
+import os
+import sys
+
+__all__ = ["setup", "SCRIPTS_DIR", "REPO_ROOT", "find_scripts_root", "ensure_scripts_path"]
+
+
+def find_scripts_root(start=None):
+    """定位 .qoder/scripts/ 根目录。
+
+    策略: 从 start (默认 __file__ 的目录) 向上找, 直到某目录含 'common/' 子目录
+    且该 common/ 下有 bootstrap.py (即本文件) → 那就是 scripts/ 根。
+    兜底: 找含 '.qoder' 的目录 + '/scripts'。
+    """
+    start = start or os.path.dirname(os.path.abspath(__file__))
+    cur = start
+    for _ in range(10):
+        # scripts/ 根的标志: 含 common/bootstrap.py
+        if os.path.isfile(os.path.join(cur, "foundation", "bootstrap.py")):
+            return cur
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            break
+        cur = parent
+    # 兜底: cwd 向上找 .qoder/scripts
+    cwd = os.getcwd()
+    for _ in range(10):
+        cand = os.path.join(cwd, ".qoder", "scripts")
+        if os.path.isdir(cand):
+            return cand
+        parent = os.path.dirname(cwd)
+        if parent == cwd:
+            break
+        cwd = parent
+    return start
+
+
+def ensure_scripts_path(start=None):
+    """确保 scripts/ 根在 sys.path 最前。幂等。
+
+    子包脚本调用此函数后, `from foundation.x` 即可用。
+    """
+    root = find_scripts_root(start)
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    return root
+
+
+def _find_scripts_dir() -> str:
+    """[内部] 定位 scripts/ 根 (兼容旧名)。"""
+    return find_scripts_root()
+
+
+def ensure_utf8_stdio():
+    """UTF-8 stdio 配置 (v3.0: 从 utf8.py 并入)。
+
+    把 stdout/stderr 切到 UTF-8, 失败则忽略 (不崩溃)。
+    幂等: 多次调用无害。
+    """
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if stream is None:
+            continue
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (TypeError, ValueError, OSError, IOError):
+            try:
+                reconfigure(encoding="utf-8")
+            except Exception:
+                pass
+
+
+def setup():
+    """统一 CLI 启动初始化。幂等。
+
+    做: ① ensure_utf8_stdio ② scripts/ 根注入 sys.path ③ scripts/common/ 注入
+    Returns: (SCRIPTS_DIR, REPO_ROOT)
+    """
+    # 先确保 scripts/ 根在 path (本文件可能在 common/ 或被引用)
+    scripts_dir = ensure_scripts_root = find_scripts_root()
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    common_dir = os.path.join(scripts_dir, "foundation")
+    if os.path.isdir(common_dir) and common_dir not in sys.path:
+        sys.path.insert(0, common_dir)
+    # 注入所有子包目录 (kg/build/mcp/test/setup/carriers/task/search/report)
+    # 让跨包 import (旧式不带前缀, 如 import search_index) 仍可用
+    try:
+        for _name in os.listdir(scripts_dir):
+            _subdir = os.path.join(scripts_dir, _name)
+            if os.path.isdir(_subdir) and _subdir not in sys.path:
+                sys.path.insert(0, _subdir)
+    except OSError:
+        pass
+
+    # 1. UTF-8 stdio (v3.0: utf8.py 已并入 bootstrap, 内联实现)
+    try:
+        ensure_utf8_stdio()
+    except Exception:
+        for sname in ("stdout", "stderr"):
+            s = getattr(sys, sname, None)
+            rc = getattr(s, "reconfigure", None) if s else None
+            if rc:
+                try:
+                    rc(encoding="utf-8", errors="replace")
+                except Exception:
+                    try:
+                        rc(encoding="utf-8")
+                    except Exception:
+                        pass
+
+    repo_root = os.path.dirname(os.path.dirname(scripts_dir))
+    return scripts_dir, repo_root
+
+
+# 模块级常量
+SCRIPTS_DIR = find_scripts_root()
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(SCRIPTS_DIR))))

package/templates/qoder/scripts/foundation/core/cmd_registry.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""
+cmd_registry.py - 命令注册器 (Command Pattern, 治 argparse 样板重复)
+
+现状: task.py 14 子命令(81行样板) + autotest.py 12 子命令(105行样板),
+每个子命令都要 add_parser + add_argument×N + set_defaults(func=) 三行,
+新增命令要改 3 处 (函数定义 + add_parser + set_defaults), 容易漏。
+
+本模块引入声明式注册: 用 (name, help, args_spec, func) 元组表 + build_parser
+一次性构建 subparser, 消除样板。
+
+args_spec 格式 (简化 argparse.add_argument):
+  [
+    ('title', {...}),               # 位置参数
+    ('--slug', {'help': 'slug'}),   # 可选参数
+    ('--pri', {'choices':[1,2,3,4], 'type':int, 'default':3}),
+  ]
+
+Usage:
+    from foundation.core.cmd_registry import build_parser
+
+    COMMANDS = [
+        ('create', '建任务', [
+            ('title', {'help': '任务标题'}),
+            ('--slug', {'help': 'URL slug'}),
+        ], cmd_create),
+        ('list', '列任务', [], cmd_list),
+    ]
+    parser = build_parser('task', '任务系统', COMMANDS)
+    args = parser.parse_args()
+    args.func(args)   # set_defaults 已自动绑定
+
+收益: task/autotest 各省 ~60-80 行样板, 新增命令从改 3 处降到改 1 处元组行。
+"""
+
+import argparse
+import sys
+from typing import Any, Callable, Dict, List, Sequence, Tuple
+
+__all__ = ["build_parser", "run_command"]
+
+# 类型别名: (name, help, args_spec, handler)
+CommandSpec = Tuple[str, str, List[Tuple[str, Dict[str, Any]]], Callable]
+
+
+def _add_args(subparser: argparse.ArgumentParser, args_spec: List[Tuple[str, Dict[str, Any]]]) -> None:
+    """把 args_spec 转成 subparser.add_argument 调用。"""
+    for name, opts in args_spec:
+        # 拆出 positional vs optional 的特殊处理
+        kwargs = dict(opts) if opts else {}
+        try:
+            subparser.add_argument(name, **kwargs)
+        except (TypeError, ValueError):
+            # 容错: 个别参数键不兼容时降级
+            subparser.add_argument(name)
+
+
+def build_parser(
+    prog: str,
+    description: str,
+    commands: Sequence[CommandSpec],
+    *,
+    common_args: List[Tuple[str, Dict[str, Any]]] = None,
+) -> argparse.ArgumentParser:
+    """从命令元组表构建 argparse parser。
+
+    Args:
+        prog: 程序名 (如 'task')
+        description: 顶部描述 (如 '任务系统')
+        commands: [(name, help, args_spec, handler), ...] 命令元组表
+        common_args: 所有子命令共享的可选参数 (如 --platform)
+
+    Returns:
+        配置好的 ArgumentParser, parse_args 后 args.func 即处理函数。
+    """
+    parser = argparse.ArgumentParser(prog=prog, description=description)
+    sub = parser.add_subparsers(dest="command")
+
+    for name, help_text, args_spec, handler in commands:
+        sp = sub.add_parser(name, help=help_text, description=help_text)
+        _add_args(sp, args_spec)
+        # 共享参数
+        if common_args:
+            _add_args(sp, common_args)
+        sp.set_defaults(func=handler)
+
+    return parser
+
+
+def run_command(
+    commands: Sequence[CommandSpec],
+    argv: List[str] = None,
+    *,
+    prog: str = "",
+    description: str = "",
+    common_args: List[Tuple[str, Dict[str, Any]]] = None,
+) -> int:
+    """便捷运行: 构建 parser + parse + 调用 func。
+
+    Returns:
+        处理函数的返回值 (通常是 int exit code), 无命令时返回 0。
+    """
+    parser = build_parser(prog or "cmd", description, commands, common_args=common_args)
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    func = getattr(args, "func", None)
+    if func is None:
+        return 1
+    ret = func(args)
+    return int(ret) if isinstance(ret, int) else 0

package/templates/qoder/scripts/foundation/core/config.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""
+config.py - Config 单例 (Singleton 模式, 治"4份 load_config + 明文凭据")
+
+现状: config.yaml 被至少 4 处各自重读 (autotest/git_sync/init_doctor/feishu),
+每次都 open + yaml.safe_load, 无缓存, 且段名用裸字符串散落各处 (拼写风险)。
+
+本模块引入单例 Config:
+  - 单次 yaml.safe_load + mtime 缓存 (config 改了自动重读)
+  - 14 段名抽常量 (Config.SECTIONS), 消拼写风险
+  - 类型化访问: Config.load().feishu / .autotest / .mysql ...
+  - 凭据从代码移除: mysql/zentao 密码只在 config.yaml, 不在源码默认值
+
+Usage:
+    from foundation.core.config import Config, SECTIONS
+    cfg = Config.load()           # 单例, 全进程共享
+    feishu = cfg.section('feishu')   # {'enabled': false, ...}
+    mysql = cfg.mysql               # 类型化便捷访问
+    if not feishu.get('enabled'): ...
+
+向后兼容: load_config() / load_config_section() 旧函数保留, 转发到 Config。
+"""
+
+import os
+import sys
+import threading
+from typing import Any, Dict, Optional
+
+__all__ = ["Config", "SECTIONS", "load_config", "load_config_section"]
+
+# 相对导入
+try:
+    from .paths import get_repo_root
+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 paths import get_repo_root  # type: ignore
+
+
+# ============================================================
+# 14 个顶层段名常量 (单一真源, 消拼写风险)
+# ============================================================
+
+class SECTIONS:
+    """config.yaml 顶层段名。调用方用 SECTIONS.FEISHU 而非裸字符串 'feishu'。"""
+    ROLES = "roles"
+    PIPELINE = "pipeline"
+    MYSQL = "mysql"
+    ZENTAO = "zentao"
+    PLATFORMS = "platforms"
+    AUTOTEST = "autotest"
+    TEAM_REMOTE = "team_remote"
+    GIT_SYNC = "git_sync"
+    PRD_MODES = "prd_modes"
+    TASK = "task"
+    STATUS = "status"
+    INSIGHT = "insight"
+    FEISHU = "feishu"
+    NOTIFICATION = "notification"
+
+
+# ============================================================
+# Config 单例
+# ============================================================
+
+class _ConfigData:
+    """config.yaml 的类型化包装。由 Config.load() 返回实例。"""
+
+    def __init__(self, raw: Dict[str, Any]):
+        self._raw = raw or {}
+
+    def section(self, name: str, default: Optional[dict] = None) -> dict:
+        """取某段 (顶层 key)。不存在返回 default (默认 {})。"""
+        val = self._raw.get(name, {} if default is None else default)
+        return val if isinstance(val, dict) else ({} if default is None else default)
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """取任意顶层 key (非段, 如标量)。"""
+        return self._raw.get(name, default)
+
+    @property
+    def raw(self) -> Dict[str, Any]:
+        """原始整份 dict (兼容旧 load_config() 返回)。"""
+        return self._raw
+
+    # ---- 类型化便捷访问 (常用段) ----
+    @property
+    def roles(self) -> dict:
+        return self.section(SECTIONS.ROLES)
+
+    @property
+    def mysql(self) -> dict:
+        return self.section(SECTIONS.MYSQL)
+
+    @property
+    def zentao(self) -> dict:
+        return self.section(SECTIONS.ZENTAO)
+
+    @property
+    def autotest(self) -> dict:
+        return self.section(SECTIONS.AUTOTEST)
+
+    @property
+    def platforms(self) -> dict:
+        return self.section(SECTIONS.PLATFORMS)
+
+    @property
+    def git_sync(self) -> dict:
+        return self.section(SECTIONS.GIT_SYNC)
+
+    @property
+    def feishu(self) -> dict:
+        return self.section(SECTIONS.FEISHU)
+
+    @property
+    def team_remote(self) -> dict:
+        return self.section(SECTIONS.TEAM_REMOTE)
+
+
+class Config:
+    """config.yaml 单例加载器 (mtime 缓存)。
+
+    - 首次 load() 读文件 + yaml.safe_load, 缓存结果 + 文件 mtime
+    - 后续 load() 检查 mtime, 变了才重读 (热重载, 无需重启)
+    - config.yaml 不存在 → 返回空 ConfigData (软降级, 不崩)
+    - 线程安全 (Lock 保护首次加载)
+    """
+
+    _instance: Optional[_ConfigData] = None
+    _mtime: Optional[float] = None
+    _path: Optional[str] = None
+    _lock = threading.Lock()
+
+    @classmethod
+    def _config_path(cls) -> str:
+        if cls._path is None:
+            cls._path = str(get_repo_root() / ".qoder" / "config.yaml")
+        return cls._path
+
+    @classmethod
+    def load(cls) -> _ConfigData:
+        """加载/返回缓存的 config。mtime 变化时自动重读。"""
+        path = cls._config_path()
+        try:
+            cur_mtime = os.path.getmtime(path)
+        except OSError:
+            # 文件不存在 → 空配置 (软降级)
+            return _ConfigData({})
+        with cls._lock:
+            if cls._instance is not None and cls._mtime == cur_mtime:
+                return cls._instance
+            # (重)读
+            try:
+                import yaml
+                with open(path, encoding="utf-8") as f:
+                    raw = yaml.safe_load(f) or {}
+            except Exception:
+                raw = {}
+            cls._instance = _ConfigData(raw)
+            cls._mtime = cur_mtime
+            return cls._instance
+
+    @classmethod
+    def reload(cls) -> _ConfigData:
+        """强制重读 (忽略缓存)。测试/配置热更新用。"""
+        cls._mtime = None
+        return cls.load()
+
+
+# ============================================================
+# 向后兼容: 旧函数签名转发到 Config 单例
+# ============================================================
+
+def load_config() -> dict:
+    """[兼容] 返回整份 config dict (替代 git_sync/init_doctor 各自的 load_config)。"""
+    return Config.load().raw
+
+
+def load_config_section(section: str = SECTIONS.AUTOTEST, default: Optional[dict] = None) -> dict:
+    """[兼容] 返回某段 dict (替代 autotest/feishu 各自的 load_config_section/_load_config)。
+
+    Args:
+        section: 段名 (用 SECTIONS.XXX 常量, 不要裸字符串)
+        default: 段不存在时的返回值 (默认 {})
+    """
+    return Config.load().section(section, default if default is not None else {})