@hupan56/wlkj 3.1.25 → 3.1.26

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

@@ -1,706 +1,706 @@
-# -*- coding: utf-8 -*-
-"""
-Path management - central path config
-
-All paths managed from one place:
-- .qoder/ = engine (AI reads)
-- workspace/ = work area (humans see)
-- Strictly separated
-
-Reference: Trellis path management
-"""
-
-import os
-import sys
-from pathlib import Path
-from typing import Optional, Dict
-
-# Project root (auto-detect: find .qoder/ upward)
-def _is_real_repo_root(path: Path) -> bool:
-    """判定某目录是不是真正的 QODER 项目仓库根。
-
-    光有 ``.qoder/`` 不够 —— QoderWork 桌面端 / Qoder IDE 会在用户家目录建
-    ``~/.qoder/``（客户端配置: agents/cache/logs/plugins/...），它**没有
-    scripts/ 子目录**。只有真仓库的 ``.qoder/`` 才含 ``scripts/``（引擎）。
-    用 ``scripts/`` 作为引擎标志区分二者，避免把客户端目录误判为仓库根
-    （那会导致 get_developer() 读到错误的 .developer → QoderWork 误报
-    "身份未初始化"，即使项目里早已 /wl-init 过）。
-    """
-    return (path / ".qoder").is_dir() and (path / ".qoder" / "scripts").is_dir()
-
-
-def _find_repo_root() -> Path:
-    """Find project root by searching for .qoder/ directory.
-
-    优先看 cwd: AI/CLI 常在项目根调 `python .qoder/scripts/xxx.py`,
-    cwd 就是项目根。再用 __file__ 兜底 (脚本被 import 时 cwd 可能不对)。
-
-    ⚠️ 必须用 _is_real_repo_root 校验: 仅 .qoder/ 不够, QoderWork/Qoder
-    会在家目录建无 scripts/ 的客户端 ~/.qoder/, 会造成误判。
-    """
-    cwd = Path.cwd()
-    if _is_real_repo_root(cwd):
-        return cwd
-    current = cwd
-    for _ in range(10):
-        if _is_real_repo_root(current):
-            return current
-        parent = current.parent
-        if parent == current:
-            break
-        current = parent
-    current = Path(__file__).resolve().parent
-    for _ in range(10):
-        if _is_real_repo_root(current):
-            return current
-        parent = current.parent
-        if parent == current:
-            break
-        current = parent
-    return Path(__file__).resolve().parent.parent.parent.parent.parent
-
-PROJECT_ROOT = _find_repo_root()
-
-# =============================================================================
-# Engine paths (.qoder/)
-# =============================================================================
-
-QODER_DIR = PROJECT_ROOT / ".qoder"
-RUNTIME_DIR = QODER_DIR / ".runtime"
-SESSIONS_DIR = RUNTIME_DIR / "sessions"
-ARCHIVE_DIR = QODER_DIR / "archive"
-RULES_DIR = QODER_DIR / "rules"
-CONTEXT_DIR = QODER_DIR / "context"
-SKILLS_DIR = QODER_DIR / "skills"
-AGENTS_DIR = QODER_DIR / "agents"
-HOOKS_DIR = QODER_DIR / "hooks"
-SCRIPTS_DIR = QODER_DIR / "scripts"
-
-# =============================================================================
-# Workspace paths (workspace/)
-# =============================================================================
-
-WORKSPACE_DIR = PROJECT_ROOT / "workspace"
-SPECS_DIR = WORKSPACE_DIR / "specs"
-PRD_DIR = SPECS_DIR / "prd"
-TASKS_DIR = WORKSPACE_DIR / "tasks"
-CONSTITUTION_DIR = WORKSPACE_DIR / "constitution"
-MEMBERS_DIR = WORKSPACE_DIR / "members"
-
-# =============================================================================
-# Developer files
-# =============================================================================
-
-DEVELOPER_FILE = QODER_DIR / ".developer"
-CURRENT_TASK_FILE = QODER_DIR / ".current-task"
-
-# =============================================================================
-# Legacy compatibility constants (used by task.py, developer.py, etc.)
-# =============================================================================
-
-DIR_TASKS = "workspace/tasks"
-DIR_ARCHIVE = ".qoder/archive"
-DIR_WORKFLOW = ".qoder"
-DIR_WORKSPACE = "workspace/members"
-DIR_SPECS = "workspace/specs"
-
-FILE_TASK_JSON = "task.json"
-FILE_DEVELOPER = ".developer"
-FILE_JOURNAL_PREFIX = "journal-"
-
-
-# =============================================================================
-# Index file registry — SINGLE SOURCE OF TRUTH for data/index/ filenames
-# =============================================================================
-# Why this exists: 17 index files used to be flat-named in data/index/ with
-# 4 different naming styles, and two (module-map vs module-index) differed by
-# one word but meant totally different things. Every consumer hardcoded the
-# filename as a string literal. Now all names live here — rename = change once.
-#
-# Naming convention: <category>-<subject>.json
-#   code-   source code layer (search, APIs, stats, dependency graph)
-#   ui-     UI/style layer (page patterns, module names, design fingerprint)
-#   trace-  call-chain (button click → API → controller)
-#   prd-    product requirements
-#   wiki-   semantic module docs
-#   ref-    hand-curated static reference (NOT auto-built)
-# Dotfiles (.meta, .cache) are machine-local bookkeeping.
-
-DATA_INDEX_DIR = PROJECT_ROOT / "data" / "index"
-BUILD_CACHE_DIR = DATA_INDEX_DIR / "_build_cache"  # JSON 中间产物 (构建器写→kg_duckdb读→DuckDB)
-KG_DB_PATH = DATA_INDEX_DIR / "kg.duckdb"  # 知识图谱单文件存储 (消费层唯一查询入口)
-
-# ── Learning / quality history (data/learning/) ──
-# Why centralized: eval_prd.py writes here, status.py reads it. Past bug had
-# writer at data/learning/ but reader at .qoder/learning/ (never existed) →
-# EVA dimension in /wl-status was permanently dead. Single constant kills drift.
-DATA_LEARNING_DIR = PROJECT_ROOT / "data" / "learning"
-EVAL_HISTORY_PATH = DATA_LEARNING_DIR / "eval-history.jsonl"  # eval_prd.py 写 / status.py 读
-
-INDEX_FILES = {
-    # ── code layer (built by git_sync.py) ──
-    'code_keyword':    'code-keyword.json',      # was code-keyword.json
-    'code_api':        'code-api.json',          # was code-api.json
-    'code_stats':      'code-stats.json',        # was code-stats.json (PROJECT FILE COUNTS)
-    'code_callgraph':  'code-code-callgraph.json',    # was code-callgraph.json
-    # ── UI layer (built by build_style_index.py) ──
-    'ui_style':        'ui-style.json',          # was ui-style.json
-    'ui_style_meta':   'ui-ui-style-meta.json',     # was ui-style-meta.json
-    'ui_modules':      'ui-modules.json',        # was ui-modules.json (BUSINESS MODULE NAMES)
-    # ── call-chain (built by build_style_index.py) ──
-    'trace_chain':     'trace-chain.json',       # was trace-chain.json
-    # ── 浏览器测试锚点 (built/updated by autotest.py learn) ──
-    'test_pages':      'test-pages.json',        # 页面稳定锚点(role/name/placeholder), 团队共享
-    # ── PRD layer (built by git_sync.py) ──
-    'prd_index':       'prd-index.json',         # (name unchanged, already clear)
-    'prd_code_map':    'prd-code-map.json',      # (name unchanged)
-    # ── semantic ──
-    'wiki_index':      'wiki-index.json',        # (name unchanged)
-    # ── static reference (hand-curated, committed to git) ──
-    'ref_vben':        'ref-vben-style.json',    # was ref-vben-style.json
-    'ref_chart':       'ref-chart-style.json',   # was ref-chart-style.json
-    'ref_icon':        'ref-icon.json',          # was ref-icon.json
-    # ── meta / cache (dotfiles, machine-local) ──
-    'meta_index':      '.index-meta.json',       # (name unchanged)
-    'meta_prd_collected': '.prd-collected.json', # (name unchanged)
-    'meta_last_sync':  '.last-sync',             # (name unchanged)
-    'cache_inverted':  '.inverted-cache.json',   # (name unchanged)
-    'cache_file_keys': '.file-keys.json',        # (name unchanged)
-    'meta_req_counter': 'req-counter.json',      # (name unchanged)
-}
-
-# Legacy → new name mapping (for migration + backward-compat lookups)
-INDEX_NAME_MIGRATION = {
-    'code-keyword.json':      'code-keyword.json',
-    'code-api.json':          'code-api.json',
-    'code-stats.json':         'code-stats.json',
-    'code-callgraph.json':          'code-code-callgraph.json',
-    'ui-style.json':        'ui-style.json',
-    'ui-style-meta.json':         'ui-ui-style-meta.json',
-    'ui-modules.json':       'ui-modules.json',
-    'trace-chain.json':        'trace-chain.json',
-    'ref-vben-style.json': 'ref-vben-style.json',
-    'ref-chart-style.json': 'ref-chart-style.json',
-    'ref-icon.json':     'ref-icon.json',
-}
-
-
-def index_path(key: str) -> Path:
-    """Get the full path for an index file by its registry key.
-
-    Usage:  index_path('code_keyword')  →  data/index/code-keyword.json
-    """
-    name = INDEX_FILES.get(key)
-    if name is None:
-        raise KeyError('Unknown index key: %r (valid: %s)' % (key, sorted(INDEX_FILES)))
-    return DATA_INDEX_DIR / name
-
-
-def resolve_index_name(filename: str) -> str:
-    """Resolve a (possibly legacy) index filename to its current name.
-
-    Falls back to the input unchanged if not in the migration map.
-    Used by load helpers for backward compatibility.
-    """
-    return INDEX_NAME_MIGRATION.get(filename, filename)
-
-
-# =============================================================================
-# Script locator — SINGLE SOURCE OF TRUTH for finding .py files after subdir migration
-# =============================================================================
-# v3.0 子目录化后, 脚本从 scripts/ 根搬到了 scripts/{kg,report,mcp,...}/ 子包。
-# 但调用方 (kg_mcp_server.py / kg.py) 还在用 os.path.join(SCRIPTS_DIR, 'xxx.py')
-# 按旧扁平结构找 → FileNotFound。本函数扫所有子目录, 单一真源定位。
-
-def find_script(name: str) -> Optional[Path]:
-    """在 scripts/ 树下定位一个 .py 脚本 (跨子目录自动查找)。
-
-    先查 scripts/ 根, 再扫所有子目录 (kg/report/mcp/setup/test/...)。
-    消除调用方各写各的路径拼装导致的迁移断裂 bug。
-
-    Args:
-        name: 脚本文件名, 如 'fill_prototype.py' / 'gen_design_doc.py'
-    Returns:
-        找到的绝对路径, 或 None (脚本不存在)
-    """
-    if not name:
-        return None
-    # 1. 先查 scripts/ 根 (老扁平结构残留的脚本)
-    root_hit = SCRIPTS_DIR / name
-    if root_hit.is_file():
-        return root_hit
-    # 2. 扫一级子目录 (kg/report/mcp/setup/test/...)
-    try:
-        for child in SCRIPTS_DIR.iterdir():
-            if not child.is_dir():
-                continue
-            cand = child / name
-            if cand.is_file():
-                return cand
-    except (OSError, PermissionError):
-        pass
-    return None
-
-
-# =============================================================================
-# Core functions
-# =============================================================================
-
-def get_repo_root() -> Path:
-    """Get project root directory."""
-    return PROJECT_ROOT
-
-
-def ensure_dirs():
-    """Ensure all necessary directories exist."""
-    dirs = [
-        WORKSPACE_DIR, SPECS_DIR, PRD_DIR, TASKS_DIR,
-        CONSTITUTION_DIR, MEMBERS_DIR,
-        RUNTIME_DIR, SESSIONS_DIR, ARCHIVE_DIR,
-    ]
-    for d in dirs:
-        d.mkdir(parents=True, exist_ok=True)
-
-
-def _parse_developer_file(content: str) -> Dict[str, str]:
-    """Parse .developer content. Accepts both 'name=x' and 'name: x' formats."""
-    info = {}
-    for line in content.splitlines():
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
-        for sep in ("=", ":"):
-            if sep in line:
-                k, v = line.split(sep, 1)
-                info[k.strip()] = v.strip()
-                break
-    return info
-
-
-def get_developer(repo_root: Optional[Path] = None) -> Optional[str]:
-    """Get current developer name from .developer file."""
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    dev_file = repo_root / ".qoder" / ".developer"
-    if not dev_file.is_file():
-        return None
-    try:
-        content = dev_file.read_text(encoding="utf-8")
-    except UnicodeDecodeError:
-        try:
-            content = dev_file.read_text(encoding="gbk")
-        except (OSError, IOError, UnicodeDecodeError):
-            return None
-    except (OSError, IOError):
-        return None
-    return _parse_developer_file(content).get("name") or None
-
-
-def check_developer(repo_root: Optional[Path] = None) -> bool:
-    """Check if developer is initialized."""
-    return get_developer(repo_root) is not None
-
-
-def get_developer_info(repo_root: Optional[Path] = None) -> Optional[Dict]:
-    """Get developer info as dict."""
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    dev_file = repo_root / ".qoder" / ".developer"
-    if not dev_file.is_file():
-        return None
-    try:
-        content = dev_file.read_text(encoding="utf-8")
-    except UnicodeDecodeError:
-        try:
-            content = dev_file.read_text(encoding="gbk")
-        except (OSError, IOError, UnicodeDecodeError):
-            return None
-    except (OSError, IOError):
-        return None
-    info = _parse_developer_file(content)
-    return info if info else None
-
-
-def get_developer_dir(developer_name: str) -> Path:
-    """Get developer personal directory under workspace/members/."""
-    dev_dir = MEMBERS_DIR / developer_name
-    dev_dir.mkdir(parents=True, exist_ok=True)
-    return dev_dir
-
-
-def get_developer_journal_dir(developer_name: str) -> Path:
-    """Get developer journal directory."""
-    journal_dir = get_developer_dir(developer_name) / "journal"
-    journal_dir.mkdir(parents=True, exist_ok=True)
-    return journal_dir
-
-
-def get_developer_drafts_dir(developer_name: str) -> Path:
-    """Get developer drafts directory."""
-    drafts_dir = get_developer_dir(developer_name) / "drafts"
-    drafts_dir.mkdir(parents=True, exist_ok=True)
-    return drafts_dir
-
-
-# =============================================================================
-# 私有凭证目录 (M3: 收拢散落的敏感文件到 .private/)
-# =============================================================================
-# 现状问题: member根目录散落5个凭证文件(.signing_key/.secrets/auth-state.json/
-#   autotest-data.yaml), 和产出目录混在一起, 没层次。
-# 解法: 全收进 .private/ (个人私有, 全gitignore), 根目录只留结构化产出。
-#
-# 向后兼容: get_private_file() 先查 .private/新位置, 没有则回退老位置。
-
-PRIVATE_DIR_NAME = ".private"
-
-
-def get_private_dir(developer_name: str = None) -> Path:
-    """开发者的私有凭证目录 workspace/members/{dev}/.private/
-
-    所有敏感数据(signing_key/secrets/auth-state/autotest-data)收进这。
-    全 gitignore, 永不 push。
-    """
-    if developer_name is None:
-        developer_name = get_developer() or "unknown"
-    p = get_developer_dir(developer_name) / PRIVATE_DIR_NAME
-    p.mkdir(parents=True, exist_ok=True)
-    return p
-
-
-def get_private_file(filename: str, developer_name: str = None) -> Path:
-    """取私有文件路径 (向后兼容: 先 .private/新位置, 没有回退老位置)。
-
-    Args:
-        filename: 文件名 (如 'signing_key', 'auth-state.json', 'autotest-data.yaml')
-    Returns:
-        .private/filename 路径 (如果老位置有但新位置没有, 返回老位置)
-    """
-    if developer_name is None:
-        developer_name = get_developer() or "unknown"
-    dev_dir = get_developer_dir(developer_name)
-    new_path = get_private_dir(developer_name) / filename
-    # 向后兼容: 老位置的文件名映射
-    old_name_map = {
-        "signing_key": ".signing_key",  # 老的带点前缀
-    }
-    old_name = old_name_map.get(filename, filename)
-    old_path = dev_dir / old_name
-    # 新位置有 → 用新的; 否则老位置有 → 用老的(渐进迁移); 都没有 → 返回新位置(待创建)
-    if new_path.exists():
-        return new_path
-    if old_path.exists():
-        return old_path
-    return new_path  # 默认新位置
-
-
-def get_secrets_dir(developer_name: str = None) -> Path:
-    """开发者的 secrets 子目录 .private/secrets/ (蓝湖cookie等)。
-
-    标准路径: .private/secrets/ (v3.0 起, 收进 .private/ 统一管理)。
-    一次性迁移: 若标准路径不存在但老路径 .secrets/ 有文件, 把内容搬过来
-    (随后老路径即可删除, 消除"同一份 cookie 存两份"的冗余)。
-    """
-    if developer_name is None:
-        developer_name = get_developer() or "unknown"
-    dev_dir = get_developer_dir(developer_name)
-    new_secrets = get_private_dir(developer_name) / "secrets"
-    old_secrets = dev_dir / ".secrets"
-    new_secrets.mkdir(parents=True, exist_ok=True)
-    # 一次性迁移: 老路径有文件且新路径缺该文件 → 搬过来 (不覆盖已有的)
-    if old_secrets.is_dir():
-        import shutil as _sh
-        for f in old_secrets.iterdir():
-            if f.is_file():
-                dst = new_secrets / f.name
-                if not dst.exists():
-                    try:
-                        _sh.copy2(str(f), str(dst))
-                    except OSError:
-                        pass
-    return new_secrets
-
-
-# =============================================================================
-# M3: 时间桶 + REQ-ID 容器 (workspace 二态重构)
-# =============================================================================
-# 理念: workspace = 个人草稿台. drafts(草稿,私有) / outputs(产出,进team_sync)
-# 时间桶内建: drafts/2026/06/W4/REQ-ID/ (活区=本周桶, 历史=过去的桶, 无独立archive)
-# 一个需求的所有产出(PRD/原型/任务/规格)聚合在 REQ-ID 容器里
-
-import datetime as _dt
-
-
-def get_time_bucket(when: Optional[_dt.date] = None) -> str:
-    """返回当前(或指定)日期的时间桶相对路径: YYYY/MM/Ww
-
-    周定义: ISO 周 (周一为一周开始). W1-W53.
-    例: 2026-06-23 (周二, 第26周) → '2026/06/W26'
-    """
-    d = when or _dt.date.today()
-    iso_year, iso_week, _ = d.isocalendar()
-    # 用 iso_year (跨年时可能 != d.year), 月份用 d.month (实际月份桶)
-    return "%d/%02d/W%d" % (d.year, d.month, iso_week)
-
-
-def get_time_bucket_path(developer_name: str, area: str, when: Optional[_dt.date] = None) -> Path:
-    """某开发者某区(drafts/outputs)的某时间桶绝对路径。
-
-    Args:
-        developer_name: 开发者名
-        area: 'drafts' 或 'outputs'
-        when: 日期(默认今天), 决定哪个时间桶
-    Returns:
-        workspace/members/{dev}/{area}/{YYYY}/{MM}/{Ww}/
-    """
-    bucket = get_time_bucket(when)
-    p = get_developer_dir(developer_name) / area / bucket
-    p.mkdir(parents=True, exist_ok=True)
-    return p
-
-
-def get_req_dir(req_id: str, developer_name: str = None, area: str = "drafts",
-                when: Optional[_dt.date] = None) -> Path:
-    """某需求的容器目录 (一个需求的所有产出聚合处)。
-
-    workspace/members/{dev}/{area}/{YYYY}/{MM}/{Ww}/{REQ-ID}/
-
-    Args:
-        req_id: 需求编号 (REQ-2026-001 或 REQ-2026-001-保险OCR)
-        developer_name: 开发者名(默认当前)
-        area: 'drafts' 或 'outputs'
-        when: 日期(默认今天)
-    """
-    if developer_name is None:
-        developer_name = get_developer() or "unknown"
-    # 规范化 req_id (只取 REQ-YYYY-NNN 部分, 去掉标题后缀)
-    import re
-    m = re.match(r"(REQ-\d{4}-\d{3,})", req_id)
-    clean = m.group(1) if m else req_id
-    bucket_path = get_time_bucket_path(developer_name, area, when)
-    req_path = bucket_path / clean
-    req_path.mkdir(parents=True, exist_ok=True)
-    return req_path
-
-
-def get_outputs_dir(developer_name: str = None) -> Path:
-    """开发者的 outputs 区根目录 (产出, 进 team_sync)。"""
-    if developer_name is None:
-        developer_name = get_developer() or "unknown"
-    p = get_developer_dir(developer_name) / "outputs"
-    p.mkdir(parents=True, exist_ok=True)
-    return p
-
-
-def find_req_dirs(req_id: str, developer_name: str = None,
-                  repo_root: Optional[Path] = None) -> list:
-    """跨所有时间桶找某需求的所有容器 (drafts + outputs 都找)。
-
-    /wl-req show 的核心: 不管需求在哪个桶(drafts本周/outputs本周/历史桶),
-    全找出来。
-
-    Returns:
-        [{area, path, bucket}, ...] 列表
-    """
-    if developer_name is None:
-        developer_name = get_developer(repo_root) or "unknown"
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    import re
-    m = re.match(r"(REQ-\d{4}-\d{3,})", req_id)
-    clean = m.group(1) if m else req_id
-
-    dev_dir = MEMBERS_DIR / developer_name if (PROJECT_ROOT / "workspace" / "members").parent == PROJECT_ROOT / "workspace" else repo_root / "workspace" / "members" / developer_name
-    results = []
-    for area in ("drafts", "outputs"):
-        area_root = dev_dir / area
-        if not area_root.is_dir():
-            continue
-        # 递归找含 clean 的目录 (跨 YYYY/MM/Ww 桶)
-        for found in area_root.rglob(clean):
-            if found.is_dir():
-                # 桶 = found 相对 area_root 的父路径
-                rel = found.parent.relative_to(area_root)
-                results.append({"area": area, "path": found, "bucket": str(rel)})
-    return results
-
-
-def get_workspace_dir(repo_root: Optional[Path] = None) -> Optional[Path]:
-    """Get developer workspace directory."""
-    dev = get_developer(repo_root)
-    if not dev:
-        return None
-    return MEMBERS_DIR / dev
-
-
-def get_active_journal_file(repo_root: Optional[Path] = None) -> Optional[Path]:
-    """Get developer active journal file."""
-    ws = get_workspace_dir(repo_root)
-    if not ws:
-        return None
-    journal_dir = ws / "journal"
-    if not journal_dir.is_dir():
-        return None
-    journals = sorted(journal_dir.glob("journal-*.md"))
-    return journals[-1] if journals else None
-
-
-def get_tasks_dir(repo_root: Optional[Path] = None) -> Path:
-    """Get tasks directory (workspace/tasks/)."""
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    tasks = repo_root / "workspace" / "tasks"
-    tasks.mkdir(parents=True, exist_ok=True)
-    return tasks
-
-
-def _current_task_file(repo_root: Path, developer: Optional[str] = None) -> Path:
-    """当前任务文件路径。
-
-    零信任隔离: 按开发者命名, 避免共享机器上 A 的 current-task 被 B 覆盖。
-    developer=None 时回退到旧的全局 .current-task (向后兼容读取)。
-    """
-    repo_root = Path(repo_root)  # 容忍 str 输入
-    runtime = repo_root / ".qoder" / ".runtime"
-    if developer:
-        # 文件名只允许安全字符 (member name 已校验, 但防御性 sanitize)
-        safe = "".join(c for c in developer if c.isalnum() or c in "_-") or "anon"
-        return runtime / f"current-task.{safe}"
-    return repo_root / ".qoder" / ".current-task"
-
-
-def _read_task_file(path: Path) -> Optional[str]:
-    """读任务文件, 支持 UTF-8 和 GBK fallback (审计 H6: Notepad 默认 GBK)。"""
-    if not path.is_file():
-        return None
-    for enc in ("utf-8", "gbk", "utf-8-sig"):
-        try:
-            content = path.read_text(encoding=enc).strip()
-            return content if content else None
-        except (OSError, IOError, UnicodeDecodeError):
-            continue
-    return None
-
-
-def get_current_task(
-    repo_root: Optional[Path] = None,
-    developer: Optional[str] = None,
-) -> Optional[str]:
-    """Get current task.
-
-    优先读按开发者隔离的 .runtime/current-task.{dev};
-    若无则回退到旧的全局 .current-task (向后兼容, 会自动迁移)。
-    developer=None 时自动用 get_developer() 推断。
-    """
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    if developer is None:
-        developer = get_developer(repo_root)
-    # 1. 优先读 developer 隔离的文件
-    if developer:
-        ct = _read_task_file(_current_task_file(repo_root, developer))
-        if ct:
-            return ct
-    # 2. 回退到旧全局文件 (兼容历史)
-    legacy = _read_task_file(_current_task_file(repo_root, None))
-    return legacy
-
-
-def set_current_task(
-    task_path: Optional[str],
-    repo_root: Optional[Path] = None,
-    developer: Optional[str] = None,
-) -> None:
-    """Set current task (按开发者隔离写入)。
-
-    零信任: 写入 .runtime/current-task.{dev}, 不再写全局 .current-task。
-    若 task_path=None 则清除该开发者的指针 (不影响他人)。
-    """
-    if repo_root is None:
-        repo_root = PROJECT_ROOT
-    if developer is None:
-        developer = get_developer(repo_root)
-    ct_file = _current_task_file(repo_root, developer)
-    try:
-        ct_file.parent.mkdir(parents=True, exist_ok=True)
-        if task_path:
-            ct_file.write_text(task_path, encoding="utf-8")
-        else:
-            ct_file.unlink(missing_ok=True)
-    except (OSError, IOError) as e:
-        print(f"Warning: Failed to write current-task: {e}", file=sys.stderr)
-
-
-def get_module_spec_dir(module: Optional[str] = None) -> Path:
-    """Get module spec directory."""
-    if module:
-        spec_dir = SPECS_DIR / module
-    else:
-        spec_dir = SPECS_DIR
-    spec_dir.mkdir(parents=True, exist_ok=True)
-    return spec_dir
-
-
-def get_task_dir(slug: str) -> Path:
-    """Get task directory by slug."""
-    from datetime import datetime
-    date_prefix = datetime.now().strftime("%m-%d")
-    task_dir = TASKS_DIR / "{0}-{1}".format(date_prefix, slug)
-    task_dir.mkdir(parents=True, exist_ok=True)
-    return task_dir
-
-
-def count_lines(file_path: Path) -> int:
-    """Count lines in a file."""
-    try:
-        return sum(1 for _ in file_path.open("r", encoding="utf-8"))
-    except (OSError, IOError):
-        return 0
-
-
-# =============================================================================
-# CLI 入口: 供 skill 文档统一调用身份/活动任务/仓库根定位 (根治 QoderWork
-# 桌面端 cwd 不在仓库根导致裸相对路径读不到身份的 bug)。
-#
-# 用法 (skill 文档里统一这样写, 不再用裸 `.qoder/.developer`):
-#   R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
-#   python "$R/.qoder/scripts/common/paths.py" whoami          # 当前开发者名; 空则退出码1
-#   python "$R/.qoder/scripts/common/paths.py" current-task    # 活动任务; 空则退出码1
-#   python "$R/.qoder/scripts/common/paths.py" repo-root       # 打印仓库根绝对路径
-#   python "$R/.qoder/scripts/common/paths.py" test            # 自检 (任意 cwd 下定位)
-# =============================================================================
-
-def _cli_main(argv=None):
-    import sys
-    argv = argv if argv is not None else sys.argv[1:]
-    cmd = argv[0] if argv else "whoami"
-    if cmd == "whoami":
-        d = get_developer()
-        if d:
-            print(d)
-            return 0
-        return 1  # 空身份 → 退出码1
-    elif cmd == "current-task":
-        t = get_current_task()
-        if t:
-            print(t)
-            return 0
-        return 1
-    elif cmd in ("repo-root", "root"):
-        print(str(get_repo_root()))
-        return 0
-    elif cmd == "test":
-        # 自检: 任意 cwd 下能否正确定位仓库 + 身份
-        print("root=%s" % get_repo_root())
-        print("developer=%s" % (get_developer() or "(空)"))
-        print("current-task=%s" % (get_current_task() or "(空)"))
-        return 0
-    else:
-        import sys
-        sys.stderr.write(
-            "用法: python paths.py [whoami|current-task|repo-root|test]\n")
-        return 2
-
-
-if __name__ == "__main__":
-    import sys
+# -*- coding: utf-8 -*-
+"""
+Path management - central path config
+
+All paths managed from one place:
+- .qoder/ = engine (AI reads)
+- workspace/ = work area (humans see)
+- Strictly separated
+
+Reference: engine/data separation path management
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict
+
+# Project root (auto-detect: find .qoder/ upward)
+def _is_real_repo_root(path: Path) -> bool:
+    """判定某目录是不是真正的 QODER 项目仓库根。
+
+    光有 ``.qoder/`` 不够 —— QoderWork 桌面端 / Qoder IDE 会在用户家目录建
+    ``~/.qoder/``（客户端配置: agents/cache/logs/plugins/...），它**没有
+    scripts/ 子目录**。只有真仓库的 ``.qoder/`` 才含 ``scripts/``（引擎）。
+    用 ``scripts/`` 作为引擎标志区分二者，避免把客户端目录误判为仓库根
+    （那会导致 get_developer() 读到错误的 .developer → QoderWork 误报
+    "身份未初始化"，即使项目里早已 /wl-init 过）。
+    """
+    return (path / ".qoder").is_dir() and (path / ".qoder" / "scripts").is_dir()
+
+
+def _find_repo_root() -> Path:
+    """Find project root by searching for .qoder/ directory.
+
+    优先看 cwd: AI/CLI 常在项目根调 `python .qoder/scripts/xxx.py`,
+    cwd 就是项目根。再用 __file__ 兜底 (脚本被 import 时 cwd 可能不对)。
+
+    ⚠️ 必须用 _is_real_repo_root 校验: 仅 .qoder/ 不够, QoderWork/Qoder
+    会在家目录建无 scripts/ 的客户端 ~/.qoder/, 会造成误判。
+    """
+    cwd = Path.cwd()
+    if _is_real_repo_root(cwd):
+        return cwd
+    current = cwd
+    for _ in range(10):
+        if _is_real_repo_root(current):
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    current = Path(__file__).resolve().parent
+    for _ in range(10):
+        if _is_real_repo_root(current):
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return Path(__file__).resolve().parent.parent.parent.parent.parent
+
+PROJECT_ROOT = _find_repo_root()
+
+# =============================================================================
+# Engine paths (.qoder/)
+# =============================================================================
+
+QODER_DIR = PROJECT_ROOT / ".qoder"
+RUNTIME_DIR = QODER_DIR / ".runtime"
+SESSIONS_DIR = RUNTIME_DIR / "sessions"
+ARCHIVE_DIR = QODER_DIR / "archive"
+RULES_DIR = QODER_DIR / "rules"
+CONTEXT_DIR = QODER_DIR / "context"
+SKILLS_DIR = QODER_DIR / "skills"
+AGENTS_DIR = QODER_DIR / "agents"
+HOOKS_DIR = QODER_DIR / "hooks"
+SCRIPTS_DIR = QODER_DIR / "scripts"
+
+# =============================================================================
+# Workspace paths (workspace/)
+# =============================================================================
+
+WORKSPACE_DIR = PROJECT_ROOT / "workspace"
+SPECS_DIR = WORKSPACE_DIR / "specs"
+PRD_DIR = SPECS_DIR / "prd"
+TASKS_DIR = WORKSPACE_DIR / "tasks"
+CONSTITUTION_DIR = WORKSPACE_DIR / "constitution"
+MEMBERS_DIR = WORKSPACE_DIR / "members"
+
+# =============================================================================
+# Developer files
+# =============================================================================
+
+DEVELOPER_FILE = QODER_DIR / ".developer"
+CURRENT_TASK_FILE = QODER_DIR / ".current-task"
+
+# =============================================================================
+# Legacy compatibility constants (used by task.py, developer.py, etc.)
+# =============================================================================
+
+DIR_TASKS = "workspace/tasks"
+DIR_ARCHIVE = ".qoder/archive"
+DIR_WORKFLOW = ".qoder"
+DIR_WORKSPACE = "workspace/members"
+DIR_SPECS = "workspace/specs"
+
+FILE_TASK_JSON = "task.json"
+FILE_DEVELOPER = ".developer"
+FILE_JOURNAL_PREFIX = "journal-"
+
+
+# =============================================================================
+# Index file registry — SINGLE SOURCE OF TRUTH for data/index/ filenames
+# =============================================================================
+# Why this exists: 17 index files used to be flat-named in data/index/ with
+# 4 different naming styles, and two (module-map vs module-index) differed by
+# one word but meant totally different things. Every consumer hardcoded the
+# filename as a string literal. Now all names live here — rename = change once.
+#
+# Naming convention: <category>-<subject>.json
+#   code-   source code layer (search, APIs, stats, dependency graph)
+#   ui-     UI/style layer (page patterns, module names, design fingerprint)
+#   trace-  call-chain (button click → API → controller)
+#   prd-    product requirements
+#   wiki-   semantic module docs
+#   ref-    hand-curated static reference (NOT auto-built)
+# Dotfiles (.meta, .cache) are machine-local bookkeeping.
+
+DATA_INDEX_DIR = PROJECT_ROOT / "data" / "index"
+BUILD_CACHE_DIR = DATA_INDEX_DIR / "_build_cache"  # JSON 中间产物 (构建器写→kg_duckdb读→DuckDB)
+KG_DB_PATH = DATA_INDEX_DIR / "kg.duckdb"  # 知识图谱单文件存储 (消费层唯一查询入口)
+
+# ── Learning / quality history (data/learning/) ──
+# Why centralized: eval_prd.py writes here, status.py reads it. Past bug had
+# writer at data/learning/ but reader at .qoder/learning/ (never existed) →
+# EVA dimension in /wl-status was permanently dead. Single constant kills drift.
+DATA_LEARNING_DIR = PROJECT_ROOT / "data" / "learning"
+EVAL_HISTORY_PATH = DATA_LEARNING_DIR / "eval-history.jsonl"  # eval_prd.py 写 / status.py 读
+
+INDEX_FILES = {
+    # ── code layer (built by git_sync.py) ──
+    'code_keyword':    'code-keyword.json',      # was code-keyword.json
+    'code_api':        'code-api.json',          # was code-api.json
+    'code_stats':      'code-stats.json',        # was code-stats.json (PROJECT FILE COUNTS)
+    'code_callgraph':  'code-code-callgraph.json',    # was code-callgraph.json
+    # ── UI layer (built by build_style_index.py) ──
+    'ui_style':        'ui-style.json',          # was ui-style.json
+    'ui_style_meta':   'ui-ui-style-meta.json',     # was ui-style-meta.json
+    'ui_modules':      'ui-modules.json',        # was ui-modules.json (BUSINESS MODULE NAMES)
+    # ── call-chain (built by build_style_index.py) ──
+    'trace_chain':     'trace-chain.json',       # was trace-chain.json
+    # ── 浏览器测试锚点 (built/updated by autotest.py learn) ──
+    'test_pages':      'test-pages.json',        # 页面稳定锚点(role/name/placeholder), 团队共享
+    # ── PRD layer (built by git_sync.py) ──
+    'prd_index':       'prd-index.json',         # (name unchanged, already clear)
+    'prd_code_map':    'prd-code-map.json',      # (name unchanged)
+    # ── semantic ──
+    'wiki_index':      'wiki-index.json',        # (name unchanged)
+    # ── static reference (hand-curated, committed to git) ──
+    'ref_vben':        'ref-vben-style.json',    # was ref-vben-style.json
+    'ref_chart':       'ref-chart-style.json',   # was ref-chart-style.json
+    'ref_icon':        'ref-icon.json',          # was ref-icon.json
+    # ── meta / cache (dotfiles, machine-local) ──
+    'meta_index':      '.index-meta.json',       # (name unchanged)
+    'meta_prd_collected': '.prd-collected.json', # (name unchanged)
+    'meta_last_sync':  '.last-sync',             # (name unchanged)
+    'cache_inverted':  '.inverted-cache.json',   # (name unchanged)
+    'cache_file_keys': '.file-keys.json',        # (name unchanged)
+    'meta_req_counter': 'req-counter.json',      # (name unchanged)
+}
+
+# Legacy → new name mapping (for migration + backward-compat lookups)
+INDEX_NAME_MIGRATION = {
+    'code-keyword.json':      'code-keyword.json',
+    'code-api.json':          'code-api.json',
+    'code-stats.json':         'code-stats.json',
+    'code-callgraph.json':          'code-code-callgraph.json',
+    'ui-style.json':        'ui-style.json',
+    'ui-style-meta.json':         'ui-ui-style-meta.json',
+    'ui-modules.json':       'ui-modules.json',
+    'trace-chain.json':        'trace-chain.json',
+    'ref-vben-style.json': 'ref-vben-style.json',
+    'ref-chart-style.json': 'ref-chart-style.json',
+    'ref-icon.json':     'ref-icon.json',
+}
+
+
+def index_path(key: str) -> Path:
+    """Get the full path for an index file by its registry key.
+
+    Usage:  index_path('code_keyword')  →  data/index/code-keyword.json
+    """
+    name = INDEX_FILES.get(key)
+    if name is None:
+        raise KeyError('Unknown index key: %r (valid: %s)' % (key, sorted(INDEX_FILES)))
+    return DATA_INDEX_DIR / name
+
+
+def resolve_index_name(filename: str) -> str:
+    """Resolve a (possibly legacy) index filename to its current name.
+
+    Falls back to the input unchanged if not in the migration map.
+    Used by load helpers for backward compatibility.
+    """
+    return INDEX_NAME_MIGRATION.get(filename, filename)
+
+
+# =============================================================================
+# Script locator — SINGLE SOURCE OF TRUTH for finding .py files after subdir migration
+# =============================================================================
+# v3.0 子目录化后, 脚本从 scripts/ 根搬到了 scripts/{kg,report,mcp,...}/ 子包。
+# 但调用方 (kg_mcp_server.py / kg.py) 还在用 os.path.join(SCRIPTS_DIR, 'xxx.py')
+# 按旧扁平结构找 → FileNotFound。本函数扫所有子目录, 单一真源定位。
+
+def find_script(name: str) -> Optional[Path]:
+    """在 scripts/ 树下定位一个 .py 脚本 (跨子目录自动查找)。
+
+    先查 scripts/ 根, 再扫所有子目录 (kg/report/mcp/setup/test/...)。
+    消除调用方各写各的路径拼装导致的迁移断裂 bug。
+
+    Args:
+        name: 脚本文件名, 如 'fill_prototype.py' / 'gen_design_doc.py'
+    Returns:
+        找到的绝对路径, 或 None (脚本不存在)
+    """
+    if not name:
+        return None
+    # 1. 先查 scripts/ 根 (老扁平结构残留的脚本)
+    root_hit = SCRIPTS_DIR / name
+    if root_hit.is_file():
+        return root_hit
+    # 2. 扫一级子目录 (kg/report/mcp/setup/test/...)
+    try:
+        for child in SCRIPTS_DIR.iterdir():
+            if not child.is_dir():
+                continue
+            cand = child / name
+            if cand.is_file():
+                return cand
+    except (OSError, PermissionError):
+        pass
+    return None
+
+
+# =============================================================================
+# Core functions
+# =============================================================================
+
+def get_repo_root() -> Path:
+    """Get project root directory."""
+    return PROJECT_ROOT
+
+
+def ensure_dirs():
+    """Ensure all necessary directories exist."""
+    dirs = [
+        WORKSPACE_DIR, SPECS_DIR, PRD_DIR, TASKS_DIR,
+        CONSTITUTION_DIR, MEMBERS_DIR,
+        RUNTIME_DIR, SESSIONS_DIR, ARCHIVE_DIR,
+    ]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+
+
+def _parse_developer_file(content: str) -> Dict[str, str]:
+    """Parse .developer content. Accepts both 'name=x' and 'name: x' formats."""
+    info = {}
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        for sep in ("=", ":"):
+            if sep in line:
+                k, v = line.split(sep, 1)
+                info[k.strip()] = v.strip()
+                break
+    return info
+
+
+def get_developer(repo_root: Optional[Path] = None) -> Optional[str]:
+    """Get current developer name from .developer file."""
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    dev_file = repo_root / ".qoder" / ".developer"
+    if not dev_file.is_file():
+        return None
+    try:
+        content = dev_file.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        try:
+            content = dev_file.read_text(encoding="gbk")
+        except (OSError, IOError, UnicodeDecodeError):
+            return None
+    except (OSError, IOError):
+        return None
+    return _parse_developer_file(content).get("name") or None
+
+
+def check_developer(repo_root: Optional[Path] = None) -> bool:
+    """Check if developer is initialized."""
+    return get_developer(repo_root) is not None
+
+
+def get_developer_info(repo_root: Optional[Path] = None) -> Optional[Dict]:
+    """Get developer info as dict."""
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    dev_file = repo_root / ".qoder" / ".developer"
+    if not dev_file.is_file():
+        return None
+    try:
+        content = dev_file.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        try:
+            content = dev_file.read_text(encoding="gbk")
+        except (OSError, IOError, UnicodeDecodeError):
+            return None
+    except (OSError, IOError):
+        return None
+    info = _parse_developer_file(content)
+    return info if info else None
+
+
+def get_developer_dir(developer_name: str) -> Path:
+    """Get developer personal directory under workspace/members/."""
+    dev_dir = MEMBERS_DIR / developer_name
+    dev_dir.mkdir(parents=True, exist_ok=True)
+    return dev_dir
+
+
+def get_developer_journal_dir(developer_name: str) -> Path:
+    """Get developer journal directory."""
+    journal_dir = get_developer_dir(developer_name) / "journal"
+    journal_dir.mkdir(parents=True, exist_ok=True)
+    return journal_dir
+
+
+def get_developer_drafts_dir(developer_name: str) -> Path:
+    """Get developer drafts directory."""
+    drafts_dir = get_developer_dir(developer_name) / "drafts"
+    drafts_dir.mkdir(parents=True, exist_ok=True)
+    return drafts_dir
+
+
+# =============================================================================
+# 私有凭证目录 (M3: 收拢散落的敏感文件到 .private/)
+# =============================================================================
+# 现状问题: member根目录散落5个凭证文件(.signing_key/.secrets/auth-state.json/
+#   autotest-data.yaml), 和产出目录混在一起, 没层次。
+# 解法: 全收进 .private/ (个人私有, 全gitignore), 根目录只留结构化产出。
+#
+# 向后兼容: get_private_file() 先查 .private/新位置, 没有则回退老位置。
+
+PRIVATE_DIR_NAME = ".private"
+
+
+def get_private_dir(developer_name: str = None) -> Path:
+    """开发者的私有凭证目录 workspace/members/{dev}/.private/
+
+    所有敏感数据(signing_key/secrets/auth-state/autotest-data)收进这。
+    全 gitignore, 永不 push。
+    """
+    if developer_name is None:
+        developer_name = get_developer() or "unknown"
+    p = get_developer_dir(developer_name) / PRIVATE_DIR_NAME
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def get_private_file(filename: str, developer_name: str = None) -> Path:
+    """取私有文件路径 (向后兼容: 先 .private/新位置, 没有回退老位置)。
+
+    Args:
+        filename: 文件名 (如 'signing_key', 'auth-state.json', 'autotest-data.yaml')
+    Returns:
+        .private/filename 路径 (如果老位置有但新位置没有, 返回老位置)
+    """
+    if developer_name is None:
+        developer_name = get_developer() or "unknown"
+    dev_dir = get_developer_dir(developer_name)
+    new_path = get_private_dir(developer_name) / filename
+    # 向后兼容: 老位置的文件名映射
+    old_name_map = {
+        "signing_key": ".signing_key",  # 老的带点前缀
+    }
+    old_name = old_name_map.get(filename, filename)
+    old_path = dev_dir / old_name
+    # 新位置有 → 用新的; 否则老位置有 → 用老的(渐进迁移); 都没有 → 返回新位置(待创建)
+    if new_path.exists():
+        return new_path
+    if old_path.exists():
+        return old_path
+    return new_path  # 默认新位置
+
+
+def get_secrets_dir(developer_name: str = None) -> Path:
+    """开发者的 secrets 子目录 .private/secrets/ (蓝湖cookie等)。
+
+    标准路径: .private/secrets/ (v3.0 起, 收进 .private/ 统一管理)。
+    一次性迁移: 若标准路径不存在但老路径 .secrets/ 有文件, 把内容搬过来
+    (随后老路径即可删除, 消除"同一份 cookie 存两份"的冗余)。
+    """
+    if developer_name is None:
+        developer_name = get_developer() or "unknown"
+    dev_dir = get_developer_dir(developer_name)
+    new_secrets = get_private_dir(developer_name) / "secrets"
+    old_secrets = dev_dir / ".secrets"
+    new_secrets.mkdir(parents=True, exist_ok=True)
+    # 一次性迁移: 老路径有文件且新路径缺该文件 → 搬过来 (不覆盖已有的)
+    if old_secrets.is_dir():
+        import shutil as _sh
+        for f in old_secrets.iterdir():
+            if f.is_file():
+                dst = new_secrets / f.name
+                if not dst.exists():
+                    try:
+                        _sh.copy2(str(f), str(dst))
+                    except OSError:
+                        pass
+    return new_secrets
+
+
+# =============================================================================
+# M3: 时间桶 + REQ-ID 容器 (workspace 二态重构)
+# =============================================================================
+# 理念: workspace = 个人草稿台. drafts(草稿,私有) / outputs(产出,进team_sync)
+# 时间桶内建: drafts/2026/06/W4/REQ-ID/ (活区=本周桶, 历史=过去的桶, 无独立archive)
+# 一个需求的所有产出(PRD/原型/任务/规格)聚合在 REQ-ID 容器里
+
+import datetime as _dt
+
+
+def get_time_bucket(when: Optional[_dt.date] = None) -> str:
+    """返回当前(或指定)日期的时间桶相对路径: YYYY/MM/Ww
+
+    周定义: ISO 周 (周一为一周开始). W1-W53.
+    例: 2026-06-23 (周二, 第26周) → '2026/06/W26'
+    """
+    d = when or _dt.date.today()
+    iso_year, iso_week, _ = d.isocalendar()
+    # 用 iso_year (跨年时可能 != d.year), 月份用 d.month (实际月份桶)
+    return "%d/%02d/W%d" % (d.year, d.month, iso_week)
+
+
+def get_time_bucket_path(developer_name: str, area: str, when: Optional[_dt.date] = None) -> Path:
+    """某开发者某区(drafts/outputs)的某时间桶绝对路径。
+
+    Args:
+        developer_name: 开发者名
+        area: 'drafts' 或 'outputs'
+        when: 日期(默认今天), 决定哪个时间桶
+    Returns:
+        workspace/members/{dev}/{area}/{YYYY}/{MM}/{Ww}/
+    """
+    bucket = get_time_bucket(when)
+    p = get_developer_dir(developer_name) / area / bucket
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def get_req_dir(req_id: str, developer_name: str = None, area: str = "drafts",
+                when: Optional[_dt.date] = None) -> Path:
+    """某需求的容器目录 (一个需求的所有产出聚合处)。
+
+    workspace/members/{dev}/{area}/{YYYY}/{MM}/{Ww}/{REQ-ID}/
+
+    Args:
+        req_id: 需求编号 (REQ-2026-001 或 REQ-2026-001-保险OCR)
+        developer_name: 开发者名(默认当前)
+        area: 'drafts' 或 'outputs'
+        when: 日期(默认今天)
+    """
+    if developer_name is None:
+        developer_name = get_developer() or "unknown"
+    # 规范化 req_id (只取 REQ-YYYY-NNN 部分, 去掉标题后缀)
+    import re
+    m = re.match(r"(REQ-\d{4}-\d{3,})", req_id)
+    clean = m.group(1) if m else req_id
+    bucket_path = get_time_bucket_path(developer_name, area, when)
+    req_path = bucket_path / clean
+    req_path.mkdir(parents=True, exist_ok=True)
+    return req_path
+
+
+def get_outputs_dir(developer_name: str = None) -> Path:
+    """开发者的 outputs 区根目录 (产出, 进 team_sync)。"""
+    if developer_name is None:
+        developer_name = get_developer() or "unknown"
+    p = get_developer_dir(developer_name) / "outputs"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def find_req_dirs(req_id: str, developer_name: str = None,
+                  repo_root: Optional[Path] = None) -> list:
+    """跨所有时间桶找某需求的所有容器 (drafts + outputs 都找)。
+
+    /wl-req show 的核心: 不管需求在哪个桶(drafts本周/outputs本周/历史桶),
+    全找出来。
+
+    Returns:
+        [{area, path, bucket}, ...] 列表
+    """
+    if developer_name is None:
+        developer_name = get_developer(repo_root) or "unknown"
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    import re
+    m = re.match(r"(REQ-\d{4}-\d{3,})", req_id)
+    clean = m.group(1) if m else req_id
+
+    dev_dir = MEMBERS_DIR / developer_name if (PROJECT_ROOT / "workspace" / "members").parent == PROJECT_ROOT / "workspace" else repo_root / "workspace" / "members" / developer_name
+    results = []
+    for area in ("drafts", "outputs"):
+        area_root = dev_dir / area
+        if not area_root.is_dir():
+            continue
+        # 递归找含 clean 的目录 (跨 YYYY/MM/Ww 桶)
+        for found in area_root.rglob(clean):
+            if found.is_dir():
+                # 桶 = found 相对 area_root 的父路径
+                rel = found.parent.relative_to(area_root)
+                results.append({"area": area, "path": found, "bucket": str(rel)})
+    return results
+
+
+def get_workspace_dir(repo_root: Optional[Path] = None) -> Optional[Path]:
+    """Get developer workspace directory."""
+    dev = get_developer(repo_root)
+    if not dev:
+        return None
+    return MEMBERS_DIR / dev
+
+
+def get_active_journal_file(repo_root: Optional[Path] = None) -> Optional[Path]:
+    """Get developer active journal file."""
+    ws = get_workspace_dir(repo_root)
+    if not ws:
+        return None
+    journal_dir = ws / "journal"
+    if not journal_dir.is_dir():
+        return None
+    journals = sorted(journal_dir.glob("journal-*.md"))
+    return journals[-1] if journals else None
+
+
+def get_tasks_dir(repo_root: Optional[Path] = None) -> Path:
+    """Get tasks directory (workspace/tasks/)."""
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    tasks = repo_root / "workspace" / "tasks"
+    tasks.mkdir(parents=True, exist_ok=True)
+    return tasks
+
+
+def _current_task_file(repo_root: Path, developer: Optional[str] = None) -> Path:
+    """当前任务文件路径。
+
+    零信任隔离: 按开发者命名, 避免共享机器上 A 的 current-task 被 B 覆盖。
+    developer=None 时回退到旧的全局 .current-task (向后兼容读取)。
+    """
+    repo_root = Path(repo_root)  # 容忍 str 输入
+    runtime = repo_root / ".qoder" / ".runtime"
+    if developer:
+        # 文件名只允许安全字符 (member name 已校验, 但防御性 sanitize)
+        safe = "".join(c for c in developer if c.isalnum() or c in "_-") or "anon"
+        return runtime / f"current-task.{safe}"
+    return repo_root / ".qoder" / ".current-task"
+
+
+def _read_task_file(path: Path) -> Optional[str]:
+    """读任务文件, 支持 UTF-8 和 GBK fallback (审计 H6: Notepad 默认 GBK)。"""
+    if not path.is_file():
+        return None
+    for enc in ("utf-8", "gbk", "utf-8-sig"):
+        try:
+            content = path.read_text(encoding=enc).strip()
+            return content if content else None
+        except (OSError, IOError, UnicodeDecodeError):
+            continue
+    return None
+
+
+def get_current_task(
+    repo_root: Optional[Path] = None,
+    developer: Optional[str] = None,
+) -> Optional[str]:
+    """Get current task.
+
+    优先读按开发者隔离的 .runtime/current-task.{dev};
+    若无则回退到旧的全局 .current-task (向后兼容, 会自动迁移)。
+    developer=None 时自动用 get_developer() 推断。
+    """
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    if developer is None:
+        developer = get_developer(repo_root)
+    # 1. 优先读 developer 隔离的文件
+    if developer:
+        ct = _read_task_file(_current_task_file(repo_root, developer))
+        if ct:
+            return ct
+    # 2. 回退到旧全局文件 (兼容历史)
+    legacy = _read_task_file(_current_task_file(repo_root, None))
+    return legacy
+
+
+def set_current_task(
+    task_path: Optional[str],
+    repo_root: Optional[Path] = None,
+    developer: Optional[str] = None,
+) -> None:
+    """Set current task (按开发者隔离写入)。
+
+    零信任: 写入 .runtime/current-task.{dev}, 不再写全局 .current-task。
+    若 task_path=None 则清除该开发者的指针 (不影响他人)。
+    """
+    if repo_root is None:
+        repo_root = PROJECT_ROOT
+    if developer is None:
+        developer = get_developer(repo_root)
+    ct_file = _current_task_file(repo_root, developer)
+    try:
+        ct_file.parent.mkdir(parents=True, exist_ok=True)
+        if task_path:
+            ct_file.write_text(task_path, encoding="utf-8")
+        else:
+            ct_file.unlink(missing_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Warning: Failed to write current-task: {e}", file=sys.stderr)
+
+
+def get_module_spec_dir(module: Optional[str] = None) -> Path:
+    """Get module spec directory."""
+    if module:
+        spec_dir = SPECS_DIR / module
+    else:
+        spec_dir = SPECS_DIR
+    spec_dir.mkdir(parents=True, exist_ok=True)
+    return spec_dir
+
+
+def get_task_dir(slug: str) -> Path:
+    """Get task directory by slug."""
+    from datetime import datetime
+    date_prefix = datetime.now().strftime("%m-%d")
+    task_dir = TASKS_DIR / "{0}-{1}".format(date_prefix, slug)
+    task_dir.mkdir(parents=True, exist_ok=True)
+    return task_dir
+
+
+def count_lines(file_path: Path) -> int:
+    """Count lines in a file."""
+    try:
+        return sum(1 for _ in file_path.open("r", encoding="utf-8"))
+    except (OSError, IOError):
+        return 0
+
+
+# =============================================================================
+# CLI 入口: 供 skill 文档统一调用身份/活动任务/仓库根定位 (根治 QoderWork
+# 桌面端 cwd 不在仓库根导致裸相对路径读不到身份的 bug)。
+#
+# 用法 (skill 文档里统一这样写, 不再用裸 `.qoder/.developer`):
+#   R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+#   python "$R/.qoder/scripts/common/paths.py" whoami          # 当前开发者名; 空则退出码1
+#   python "$R/.qoder/scripts/common/paths.py" current-task    # 活动任务; 空则退出码1
+#   python "$R/.qoder/scripts/common/paths.py" repo-root       # 打印仓库根绝对路径
+#   python "$R/.qoder/scripts/common/paths.py" test            # 自检 (任意 cwd 下定位)
+# =============================================================================
+
+def _cli_main(argv=None):
+    import sys
+    argv = argv if argv is not None else sys.argv[1:]
+    cmd = argv[0] if argv else "whoami"
+    if cmd == "whoami":
+        d = get_developer()
+        if d:
+            print(d)
+            return 0
+        return 1  # 空身份 → 退出码1
+    elif cmd == "current-task":
+        t = get_current_task()
+        if t:
+            print(t)
+            return 0
+        return 1
+    elif cmd in ("repo-root", "root"):
+        print(str(get_repo_root()))
+        return 0
+    elif cmd == "test":
+        # 自检: 任意 cwd 下能否正确定位仓库 + 身份
+        print("root=%s" % get_repo_root())
+        print("developer=%s" % (get_developer() or "(空)"))
+        print("current-task=%s" % (get_current_task() or "(空)"))
+        return 0
+    else:
+        import sys
+        sys.stderr.write(
+            "用法: python paths.py [whoami|current-task|repo-root|test]\n")
+        return 2
+
+
+if __name__ == "__main__":
+    import sys
     sys.exit(_cli_main())