@hupan56/wlkj 2.0.0

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

@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+"""
+atomicio.py - 原子读写工具
+
+解决"写一半崩溃损坏文件"和"读损坏 JSON 静默吞错"两类问题。
+
+核心 API:
+    atomic_write_text(path, content)   # temp + os.replace, 写失败不影响原文件
+    atomic_write_json(path, data, ...) # 同上, JSON 序列化 + sorted keys
+    safe_read_json(path, ...)          # 区分"缺失"vs"损坏"; 损坏备份 .corrupt 并抛错
+    atomic_append_jsonl(path, record)  # 加锁的单行追加, 解决并发 JSONL 损坏
+
+为什么这样写:
+    - os.replace 在 Windows/POSIX 都是原子系统调用 (rename), 要么成功要么原文件不动
+    - JSON 损坏必须显式报错 + 备份, 而不是返回 {} 让上层以为"无数据"
+    - JSONL 并发追加: 同一进程内用 FileLock 串行化; 跨进程也靠 FileLock
+"""
+
+import io
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional, Union
+
+# 相对导入本模块所在 common/ 的兄弟 filelock
+try:
+    from .filelock import FileLock
+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 filelock import FileLock
+
+__all__ = [
+    "atomic_write_text",
+    "atomic_write_json",
+    "safe_read_json",
+    "atomic_append_jsonl",
+    "AtomicIOError",
+]
+
+_PathLike = Union[str, "os.PathLike[str]"]
+
+
+class AtomicIOError(Exception):
+    """原子 IO 失败的统一异常。"""
+
+
+def atomic_write_text(path: _PathLike, content: str, encoding: str = "utf-8") -> None:
+    """原子写文本。先写 .tmp 再 os.replace, 写失败原文件不变。"""
+    path = str(path)
+    parent = os.path.dirname(path) or "."
+    os.makedirs(parent, exist_ok=True)
+    tmp = path + ".tmp.%d" % os.getpid()
+    try:
+        # newline='' 防止 Windows 自动 \n->\r\n 转换跨平台读不回来
+        with io.open(tmp, "w", encoding=encoding, newline="") as f:
+            f.write(content)
+            f.flush()
+            try:
+                os.fsync(f.fileno())
+            except (OSError, AttributeError):
+                pass  # 某些文件系统/管道不支持 fsync
+        os.replace(tmp, path)
+    except Exception:
+        # 清理残留 tmp, 不要污染目录
+        try:
+            if os.path.exists(tmp):
+                os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_json(
+    path: _PathLike,
+    data: Any,
+    indent: int = 2,
+    ensure_ascii: bool = False,
+    sort_keys: bool = True,
+) -> None:
+    """原子写 JSON。sorted keys 让 diff 稳定, ensure_ascii=False 保留中文可读。"""
+    text = json.dumps(
+        data, indent=indent, ensure_ascii=ensure_ascii, sort_keys=sort_keys
+    )
+    atomic_write_text(path, text)
+
+
+def safe_read_json(
+    path: _PathLike,
+    default: Any = None,
+    required: bool = False,
+    backup_corrupt: bool = True,
+) -> Any:
+    """安全读 JSON。
+
+    Args:
+        path: 文件路径。
+        default: 文件缺失时返回的值 (required=False 时)。
+        required: True 时文件缺失也抛 FileNotFoundError。
+        backup_corrupt: True 时若 JSON 损坏, 备份为 <path>.corrupt.<ts> 再抛错。
+
+    Returns:
+        解析后的对象; 缺失且非 required 返回 default。
+
+    Raises:
+        FileNotFoundError: required=True 且文件不存在。
+        AtomicIOError: JSON 解析失败 (损坏)。已备份为 .corrupt.<ts>。
+    """
+    path = str(path)
+    if not os.path.isfile(path):
+        if required:
+            raise FileNotFoundError(path)
+        return default
+    try:
+        with io.open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (ValueError, json.JSONDecodeError) as e:
+        # 损坏 —— 备份后抛错, 绝不静默吞
+        if backup_corrupt:
+            ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+            corrupt_path = "%s.corrupt.%s" % (path, ts)
+            try:
+                os.replace(path, corrupt_path)
+            except OSError:
+                corrupt_path = path  # replace 失败就保留原位置
+        raise AtomicIOError(
+            "JSON 损坏: %s\n  错误: %s\n  已备份为 .corrupt.* (若启用)" % (path, e)
+        )
+
+
+def atomic_append_jsonl(
+    path: _PathLike,
+    record: Any,
+    timeout: float = 10.0,
+) -> None:
+    """加锁追加一行 JSON 到 .jsonl 文件。
+
+    解决多个进程/会话同时 append 导致的行交错损坏 (eval_prd 并发场景)。
+    用 FileLock 串行化追加操作。
+
+    Args:
+        path: .jsonl 文件路径。
+        record: 任意可 JSON 序列化的对象 (通常是个 dict)。
+        timeout: 获取锁超时秒数。
+
+    Raises:
+        AtomicIOError: 序列化失败。
+        (来自 FileLock 的 LockTimeoutError): 锁竞争超时。
+    """
+    path = str(path)
+    parent = os.path.dirname(path) or "."
+    os.makedirs(parent, exist_ok=True)
+    try:
+        line = json.dumps(record, ensure_ascii=False, sort_keys=True)
+    except (TypeError, ValueError) as e:
+        raise AtomicIOError("无法序列化记录: %s" % e)
+
+    lock_path = path + ".lock"
+    with FileLock(lock_path, timeout=timeout):
+        # O_APPEND 模式: 操作系统保证每次 write 追加到文件末尾, 不覆盖
+        # 单次 write(< 整行) 在 POSIX 是原子的 (< PIPE_BUF), 在 Windows 也安全
+        # 因为有 FileLock 串行化
+        with io.open(path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+            f.flush()
+            try:
+                os.fsync(f.fileno())
+            except (OSError, AttributeError):
+                pass

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

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+QODER Pipeline - 开发者管理工具
+
+提供开发者身份的初始化和管理功能:
+- init_developer: 初始化开发者身份, 创建工作空间和日志
+- ensure_developer: 确保开发者已初始化 (未初始化则退出)
+- show_developer_info: 显示开发者信息
+
+开发者身份存储在 .qoder/.developer 文件中 (gitignored)
+工作空间在 workspace/members/<developer>/ 目录下 (与 workspace_init.py 一致)
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# 将 scripts 目录加入路径以便导入 common 模块
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_DEVELOPER,
+    MEMBERS_DIR,
+    get_repo_root,
+    get_developer,
+    check_developer,
+)
+
+
+# =============================================================================
+# 开发者初始化
+# =============================================================================
+
+def write_developer_file(name: str, role: str | None = None,
+                         repo_root: Path | None = None) -> bool:
+    """写入 .qoder/.developer (规范格式: name=<name>)。"""
+    if repo_root is None:
+        repo_root = get_repo_root()
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+    lines = [f"name={name}"]
+    if role:
+        lines.append(f"role={role}")
+    lines.append(f"initialized_at={datetime.now().isoformat()}")
+    try:
+        dev_file.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return True
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create .developer file: {e}", file=sys.stderr)
+        return False
+
+
+def init_developer(name: str, role: str | None = None,
+                   repo_root: Path | None = None) -> bool:
+    """初始化开发者身份。
+
+    创建以下内容:
+        - .qoder/.developer 文件 (name= / role= / initialized_at=)
+        - workspace/members/<name>/{journal,drafts,inbox}/ 目录
+        - 初始日志文件 journal/journal-1.md
+
+    Returns:
+        成功返回 True, 失败返回 False。
+    """
+    if not name:
+        print("Error: developer name is required", file=sys.stderr)
+        return False
+
+    # 校验名称合法性 (允许字母数字、中文和部分符号)
+    if not all(c.isalnum() or c in "-_" for c in name):
+        print(f"Error: invalid developer name '{name}' (only alphanumeric, -, _ allowed)", file=sys.stderr)
+        return False
+
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    # 零信任: 切换身份时清除旧开发者的 current-task 指针
+    # (防止 B 在 A 用过的机器上看到 A 的活跃任务, 误操作)
+    try:
+        from .paths import get_developer, set_current_task
+        old_dev = get_developer(repo_root)
+        if old_dev and old_dev != name:
+            set_current_task(None, repo_root, developer=old_dev)
+            print(f"Note: 切换开发者 {old_dev} -> {name}, 已清除 {old_dev} 的活跃任务指针")
+    except Exception:
+        pass  # 清理失败不阻塞初始化
+
+    # 1. 创建 .developer 文件
+    if not write_developer_file(name, role, repo_root):
+        return False
+
+    # 2. 创建个人工作空间 workspace/members/<name>/
+    personal = repo_root / "workspace" / "members" / name
+    try:
+        for sub in ("journal", "drafts", "inbox"):
+            (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)
+        return False
+
+    # 3. 创建初始日志文件
+    journal_file = personal / "journal" / "journal-1.md"
+    if not journal_file.exists():
+        today = datetime.now().strftime("%Y-%m-%d")
+        try:
+            journal_file.write_text(
+                f"# Journal - {name}\n\n> Started: {today}\n\n---\n\n",
+                encoding="utf-8"
+            )
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create journal file: {e}", file=sys.stderr)
+            return False
+
+    print(f"Developer initialized: {name}" + (f" ({role})" if role else ""))
+    print(f"  Workspace: workspace/members/{name}/")
+    print(f"  Journal:   workspace/members/{name}/journal/journal-1.md")
+    return True
+
+
+# =============================================================================
+# 开发者校验
+# =============================================================================
+
+def ensure_developer(repo_root: Path | None = None) -> str:
+    """确保开发者已初始化, 未初始化则打印提示并退出。"""
+    developer = get_developer(repo_root)
+    if not developer:
+        print("Error: Developer not initialized.", file=sys.stderr)
+        print("Run: python .qoder/scripts/workspace_init.py <your-name>", file=sys.stderr)
+        sys.exit(1)
+    return developer
+
+
+def show_developer_info(repo_root: Path | None = None) -> None:
+    """显示当前开发者信息。"""
+    from common.paths import get_developer_info, get_workspace_dir, get_active_journal_file
+
+    info = get_developer_info(repo_root)
+    if not info:
+        print("Developer: not initialized")
+        print("Run: python .qoder/scripts/workspace_init.py <your-name>")
+        return
+
+    print(f"Developer: {info.get('name', 'unknown')}")
+    if info.get('role'):
+        print(f"Role: {info['role']}")
+    print(f"Initialized: {info.get('initialized_at', 'unknown')}")
+
+    workspace = get_workspace_dir(repo_root)
+    if workspace:
+        print(f"Workspace: {workspace}")
+
+    journal = get_active_journal_file(repo_root)
+    if journal:
+        from common.paths import count_lines
+        lines = count_lines(journal)
+        print(f"Active Journal: {journal.name} ({lines} lines)")

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

@@ -0,0 +1,144 @@
+# -*- coding: utf-8 -*-
+"""
+eval_api.py - EVA PRD 评估的程序化 API
+
+从 eval_prd.py 抽取的可复用入口, 供 team_sync 门禁和其他脚本调用。
+eval_prd.py 的 main() 也改为调用本模块。
+
+核心 API:
+    evaluate(prd_path, html_path=None) -> dict
+
+返回 dict 结构:
+    {
+        "passed": bool,        # 总分 >= 80%
+        "pct": float,          # 百分比 0-100
+        "total": int,          # 原始总分
+        "full": int,           # 满分 (70 若无原型, 100 若有)
+        "a1": int,             # 现实锚定分 (满分 40)
+        "a2": int | None,      # 风格保真分 (满分 30, 无原型则 None)
+        "a3": int,             # 模板完整分 (满分 30)
+        "r1": float, "r2": float | None, "r3": float,  # 原始比率 0-1
+        "msg1": str, "msg2": str | None, "msg3": str,
+        "misses": list[str],   # 主要问题汇总 (给门禁显示用)
+        "prd": str,            # 文件名
+    }
+"""
+
+import os
+import sys
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+_SCRIPTS_DIR = os.path.dirname(_THIS_DIR)
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+# 复用 eval_prd.py 的评分函数 (不重复实现)
+from eval_prd import (
+    score_reality, score_style, score_template, read_text,
+    FULL_SECTIONS, QUICK_SECTIONS,
+)
+
+PASS_THRESHOLD = 80.0  # 百分比
+
+
+def evaluate(prd_path, html_path=None):
+    """评估 PRD (和可选原型), 返回结构化结果 dict。
+
+    Args:
+        prd_path: PRD markdown 文件路径。
+        html_path: 可选的原型 HTML 路径。不传则 A2 跳过, 满分变 70。
+
+    Returns:
+        上述结构的 dict。不抛异常 (评估本身的错误记入 misses)。
+
+    Raises:
+        FileNotFoundError: PRD 文件不存在。
+    """
+    if not os.path.isfile(prd_path):
+        raise FileNotFoundError("PRD 不存在: %s" % prd_path)
+
+    prd_text = read_text(prd_path)
+
+    # A1 现实锚定
+    try:
+        r1, msg1, miss1 = score_reality(prd_text)
+    except Exception as e:
+        r1, msg1, miss1 = 0.0, "评估异常: %s" % e, []
+    a1 = round(r1 * 40)
+
+    # A2 风格保真 (可选)
+    a2 = None
+    r2 = None
+    msg2 = None
+    miss2 = []
+    if html_path and os.path.isfile(html_path):
+        try:
+            r2, msg2, miss2 = score_style(read_text(html_path))
+            a2 = round(r2 * 30)
+        except Exception as e:
+            r2, msg2, miss2 = 0.0, "评估异常: %s" % e, []
+            a2 = 0
+
+    # A3 模板完整
+    try:
+        r3, msg3, miss3 = score_template(prd_text)
+    except Exception as e:
+        r3, msg3, miss3 = 0.0, "评估异常: %s" % e, []
+    a3 = round(r3 * 30)
+
+    total = a1 + (a2 if a2 is not None else 0) + a3
+    full = 100 if r2 is not None else 70
+    pct = (total / full * 100) if full else 0.0
+    passed = pct >= PASS_THRESHOLD
+
+    # 汇总主要问题 (给门禁一行式显示)
+    misses = []
+    if miss1:
+        misses.append("A1 字段/API 找不到: " + ", ".join(miss1[:5]))
+    if miss2:
+        misses.append("A2 非真源颜色/emoji: " + ", ".join(miss2[:5]))
+    if miss3:
+        misses.append("A3 缺章节: " + ", ".join(miss3[:5]))
+
+    return {
+        "passed": passed,
+        "pct": round(pct, 1),
+        "total": total,
+        "full": full,
+        "a1": a1,
+        "a2": a2,
+        "a3": a3,
+        "r1": r1,
+        "r2": r2,
+        "r3": r3,
+        "msg1": msg1,
+        "msg2": msg2,
+        "msg3": msg3,
+        "misses": misses,
+        "prd": os.path.basename(prd_path),
+    }
+
+
+def format_report(result):
+    """把 evaluate() 的结果格式化成人类可读的多行报告 (eval_prd CLI 用)。"""
+    lines = ["=== EVA 评估: {} ===".format(result["prd"])]
+    lines.append("")
+    lines.append("A1 现实锚定: {}/40  ({})".format(result["a1"], result["msg1"]))
+    if result["r2"] is not None:
+        lines.append("")
+        lines.append("A2 风格保真: {}/30  ({})".format(result["a2"], result["msg2"]))
+    else:
+        lines.append("")
+        lines.append("A2 风格保真: 跳过 (未提供原型文件)")
+    lines.append("")
+    lines.append("A3 模板完整: {}/30  ({})".format(result["a3"], result["msg3"]))
+
+    # 详细 misses
+    if result.get("msg1") and "找不到" in str(result.get("msg1", "")):
+        pass  # msg 已含信息
+    lines.append("")
+    lines.append("总分: {}/{} ({:.0f}%)".format(
+        result["total"], result["full"], result["pct"]))
+    verdict = "PASS - 可以发布" if result["passed"] else "FAIL - 修复上述问题后再发布"
+    lines.append("结论: " + verdict)
+    return "\n".join(lines)