@hupan56/wlkj 2.7.12 → 3.0.0

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

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+"""
+kg_capabilities.py - 知识图谱共享查询能力 (Strategy 模式, 消除 CLI↔MCP 重复)
+
+v3.0 f3: kg.py (CLI) 和 kg_mcp_server.py (MCP) 有近字重复的查询逻辑
+(workflow/hop/wiki/design_system 等)。本模块提取共享查询, 两边都调它,
+消除重复, 且保证 CLI 和 MCP 行为完全一致。
+
+核心 API (都接收已打开的 duckdb con, 由调用方管理连接):
+    workflow_query(con, q) -> str    业务流程链查询
+    # hop_query / wiki_query / design_system_query 后续添加
+
+设计: 查询逻辑 (数据清洗/SQL/格式化) 在此单一真源;
+      kg.py 和 kg_mcp_server 只负责"开连接 + 调本模块 + 返回"。
+"""
+
+__all__ = ["workflow_query", "hop_query", "wiki_query"]
+
+
+def workflow_query(con, q):
+    """workflows 表查询 + 脏数据清洗 + 中文兜底。
+
+    Args:
+        con: 已打开的 duckdb 连接 (read_only)
+        q: 模块名 (英文 assets/cost/hr 或中文触发兜底)
+
+    Returns:
+        格式化的业务流程链文本
+    """
+    q = (q or '').strip()
+    # 1) 精确 + 模糊匹配 workflows.module（英文）
+    hits = con.execute(
+        "SELECT DISTINCT module FROM workflows WHERE module = ? OR module LIKE '%' || ? || '%' ORDER BY module",
+        [q.lower(), q.lower()]
+    ).fetchall()
+    if not hits:
+        # 2) 中文兜底: 查 entities.cn 返回英文候选
+        cn_hits = con.execute(
+            "SELECT canonical, cn FROM entities WHERE type IN ('FEATURE','MODULE') AND cn <> '' AND (cn LIKE '%' || ? OR cn LIKE '%' || ? || '%')",
+            [q, q]
+        ).fetchall()
+        if cn_hits:
+            cands = ', '.join('%s(%s)' % (c[0], c[1]) for c in cn_hits[:8])
+            return "未在 workflows 表找到模块 '%s'。但 entities 表有相近中文名，可换这些英文模块名重试:\n  %s" % (q, cands)
+        all_mods = [r[0] for r in con.execute("SELECT DISTINCT module FROM workflows ORDER BY module").fetchall()]
+        return "未找到模块 '%s'。现有模块: %s" % (q, ', '.join(all_mods))
+
+    out = []
+    for (mod,) in hits:
+        # 清洗: 过滤空端点和模板泄漏按钮
+        rows = con.execute("""
+            SELECT state, seq, button, endpoint FROM workflows
+            WHERE module = ?
+              AND endpoint <> 'None' AND endpoint <> ''
+              AND button NOT LIKE '{{%'
+            ORDER BY seq, state
+        """, [mod]).fetchall()
+        if not rows:
+            continue
+        out.append('=== %s (%d 步, 已清洗脏数据) ===' % (mod, len(rows)))
+        cur_seq = -1
+        for st, sq, btn, ep in rows:
+            if sq != cur_seq:
+                out.append('  [%d] %s' % (sq, st))
+                cur_seq = sq
+            out.append('        %-16s -> %s' % (btn, ep))
+        out.append('')
+    return '\n'.join(out).strip() or "模块 '%s' 清洗后无有效操作链" % q
+
+
+def hop_query(con, symbol, depth, multi_hop_fn=None):
+    """多跳遍历: 别名解析(三级兜底) + 递归CTE + 按depth分组展示。
+
+    Args:
+        con: duckdb 连接
+        symbol: 起始符号 (中文/端点/函数名, 自动别名解析)
+        depth: 最大跳数 1-5
+        multi_hop_fn: kg_duckdb.multi_hop 函数 (避免硬依赖)
+    Returns:
+        格式化的多跳遍历文本
+    """
+    # 1) 别名解析（三级兜底）
+    start_id = symbol
+    resolved = con.execute(
+        "SELECT entity_id FROM aliases WHERE alias = ?", [symbol.lower()]
+    ).fetchone()
+    if resolved:
+        start_id = resolved[0]
+    else:
+        fuzzy = con.execute(
+            "SELECT id FROM entities WHERE id = ? OR id LIKE '%' || ? || '%' LIMIT 1",
+            [symbol, symbol]
+        ).fetchone()
+        if fuzzy:
+            start_id = fuzzy[0]
+        else:
+            edge_hit = con.execute(
+                "SELECT from_id FROM edges WHERE from_id LIKE '%' || ? || '%' LIMIT 1",
+                [symbol]
+            ).fetchone()
+            if edge_hit:
+                start_id = edge_hit[0]
+
+    # 2) 递归 CTE 遍历
+    if multi_hop_fn is None:
+        import kg_duckdb as K
+        multi_hop_fn = K.multi_hop
+    try:
+        hops = multi_hop_fn(con, start_id, max_depth=depth)
+    except Exception as e:
+        return "遍历出错 (起点=%s): %s" % (start_id, str(e))
+
+    if not hops or (len(hops) == 1 and hops[0][1] == 0):
+        return "从 '%s' (解析为 %s) 出发无可达节点。可能该符号不在图谱中，或无出边。" % (symbol, start_id)
+
+    # 3) 按 depth 分组展示
+    from collections import defaultdict
+    by_depth = defaultdict(list)
+    for eid, d in hops:
+        by_depth[d].append(eid)
+
+    out = ['=== 多跳遍历: %s (解析为 %s) ===' % (symbol, start_id)]
+    out.append('可达 %d 个实体, 最大 %d 跳:' % (len(hops), max(by_depth.keys())))
+    out.append('')
+    for d in sorted(by_depth.keys()):
+        eids = by_depth[d]
+        out.append('[第 %d 跳] %d 个实体:' % (d, len(eids)))
+        shown = 0
+        for eid in eids:
+            if shown >= 12:
+                out.append('  ... 还有 %d 个' % (len(eids) - 12))
+                break
+            info = con.execute(
+                "SELECT type, canonical, cn FROM entities WHERE id = ?", [eid]
+            ).fetchone()
+            if info:
+                t, c, cn = info
+                label = '%s / %s' % (c, cn) if cn and cn != c else c
+                out.append('  %-14s %-12s %s' % ('[%s]' % t, eid[:40], label))
+            else:
+                out.append('  %-14s %s' % ('[edge]', eid[:60]))
+            shown += 1
+        out.append('')
+    return '\n'.join(out).strip()
+
+def wiki_query(kw):
+    """Repo Wiki 搜索 + 格式化 (CLI/MCP 共用)。
+
+    Args:
+        kw: 搜索关键词
+    Returns:
+        格式化的 wiki 匹配结果文本
+    """
+    import os
+    from common.paths import DATA_INDEX_DIR as _idx, PROJECT_ROOT as _base
+    wiki_path = os.path.join(str(_idx), 'wiki-index.json')
+    if not os.path.isfile(wiki_path):
+        return ("wiki-index.json 不存在。请手动构建(一次性):\n"
+                "  python .qoder/scripts/search_index.py wiki")
+    try:
+        from common.repowiki import search_wiki
+        from common.terms import get_cn_map_with_auto
+    except ImportError as e:
+        return "Wiki 搜索模块缺失: %s" % str(e)
+    code_dir = os.path.join(_base, 'data', 'code')
+    try:
+        cn_map = get_cn_map_with_auto()
+        results = search_wiki(kw, str(_idx), code_dir, cn_map)
+    except Exception as e:
+        return "Wiki 搜索出错: %s" % str(e)
+    if not results:
+        return "No wiki pages match: %s" % kw
+    out = ['Wiki pages matching: %s (%d found)' % (kw, len(results)), '']
+    for i, r in enumerate(results, 1):
+        out.append('  %d. [%s] %s' % (i, r.get('project', '?'), r.get('title', '')))
+        deps = r.get('dependent_files') or []
+        if deps:
+            out.append('     依赖: %s%s' % (', '.join(deps[:2]),
+                      (' (共 %d 个文件)' % len(deps)) if len(deps) > 2 else ''))
+        if r.get('md_path'):
+            out.append('     文档: %s' % r['md_path'])
+    return '\n'.join(out)

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

@@ -0,0 +1,268 @@
+# -*- coding: utf-8 -*-
+"""
+mcp_base.py - MCP Server 基类 (Template Method 模式)
+
+治"3个MCP server协议层逐行复制~255行"。三者(kg/mysql/zentao)的:
+  - _send (JSON-RPC写)
+  - main (readline循环 + 每请求新event_loop)
+  - _handle 五分支骨架 (initialize/notifications/initialized/tools·list/tools·call/ping/error)
+  - stdout重定向 (stdout→stderr, 避免污染stdio协议)
+全部逐字一致, 仅差异点:
+  - serverInfo.name/version
+  - initialize 是否调 check_intranet 塞 warning
+  - tools/call 的异常分类 (mysql 多 ValueError→只读拒绝)
+  - error 分支文案
+
+本基类把骨架固化为 final 方法, 子类填钩子:
+  - SERVER_NAME / SERVER_VERSION: 类属性
+  - TOOLS: 工具元数据列表
+  - handle_tool(name, args) -> str: 工具执行 (Strategy 钩子)
+  - on_initialize_hook(info) -> None: 塞 warning 等 (默认空)
+  - on_tool_error(e) -> (text, is_error): 自定义异常分类 (默认通用)
+
+Usage (子类示例):
+    from common.mcp_base import BaseMCPServer
+
+    class ZentaoMCPServer(BaseMCPServer):
+        SERVER_NAME = "qoder-zentao"
+        SERVER_VERSION = "1.0.0"
+        TOOLS = [...]   # 工具元数据
+        def handle_tool(self, name, args):
+            if name == 'list_stories': return self._list_stories(args)
+            return '未知工具: %s' % name
+        def on_initialize_hook(self, info):
+            ok, msg = check_intranet()
+            if not ok: info['warning'] = msg
+
+    if __name__ == '__main__':
+        ZentaoMCPServer().run()
+
+收益: 加第4个MCP server从复制~255行降到写~30行(只填tools+handle_tool)。
+
+v3.0+ 增强: ToolRegistry + @tool 装饰器 (Command Registry 模式)。
+消除子类 _execute_tool 的长 if-elif 链 + TOOLS 元数据两处维护的漂移。
+用法见底部示例。
+"""
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+__all__ = ["BaseMCPServer", "tool", "ToolRegistry"]
+
+
+# ============================================================
+# ToolRegistry: @tool 装饰器收集工具定义 (Command Registry 模式)
+# ============================================================
+
+def tool(name: str, description: str = "", input_schema: Optional[Dict] = None):
+    """装饰器: 把一个方法注册为 MCP 工具。
+
+    替代旧式的 "TOOLS 列表 + _execute_tool if 链 两处维护"。
+    装饰后, BaseMCPServer.TOOLS 自动收集, handle_tool 自动分发。
+
+    Usage (子类内):
+        @tool("search_code", "搜代码", {"type":"object","properties":{...}})
+        def search_code(self, args):
+            return "结果文本"
+    """
+    def decorator(method):
+        method._tool_meta = {
+            "name": name,
+            "description": description or method.__doc__ or "",
+            "inputSchema": input_schema or {"type": "object", "properties": {}},
+        }
+        return method
+    return decorator
+
+
+class _ToolRegistryMeta(type):
+    """元类: 子类定义完成后, 扫描 @tool 装饰的方法, 自动填充 TOOLS + _tool_map。
+
+    这样子类只需用 @tool 装饰, 不用再手写 TOOLS 列表和 handle_tool if 链。
+    """
+    def __new__(mcs, name, bases, namespace):
+        cls = super().__new__(mcs, name, bases, namespace)
+        # 收集本类 + 父类的 @tool 方法
+        tool_map = {}
+        # 先继承父类的
+        for base in bases:
+            if hasattr(base, "_tool_map"):
+                tool_map.update(base._tool_map)
+        # 再收集本类的
+        for attr_name, attr_val in namespace.items():
+            meta = getattr(attr_val, "_tool_meta", None)
+            if meta:
+                tool_map[meta["name"]] = {
+                    "meta": meta,
+                    "handler": attr_name,  # 方法名, 运行时 getattr 取
+                }
+        cls._tool_map = tool_map
+        # 如果子类没显式定义 TOOLS (用装饰器模式), 自动生成
+        if tool_map and not namespace.get("TOOLS"):
+            cls.TOOLS = [v["meta"] for v in tool_map.values()]
+        return cls
+
+
+class BaseMCPServer(metaclass=_ToolRegistryMeta):
+    """MCP stdio server 基类 (Template Method + ToolRegistry)。
+
+    两种用法 (二选一):
+    A) 装饰器模式 (推荐, 消除 if 链):
+        class MyServer(BaseMCPServer):
+            SERVER_NAME = "my"
+            @tool("foo", "做foo", {...})
+            def foo(self, args): return "结果"
+        # TOOLS 自动收集, handle_tool 自动分发, 无需覆写
+    B) 传统模式 (兼容旧代码):
+        class MyServer(BaseMCPServer):
+            SERVER_NAME = "my"
+            TOOLS = [...]   # 手写
+            def handle_tool(self, name, args): ...  # 手写 if 链
+    """
+
+    # ---- 子类必填类属性 ----
+    SERVER_NAME: str = "qoder-mcp"
+    SERVER_VERSION: str = "0.1.0"
+    TOOLS: List[Dict[str, Any]] = []
+    _tool_map: Dict[str, Dict] = {}  # 由元类自动填充
+
+    # ---- 协议常量 (可覆写) ----
+    PROTOCOL_VERSION: str = "2024-11-05"
+
+    # ============================================================
+    # 内部: stdout 重定向 (MCP 用 stdout 传 JSON-RPC, 不能被 print 污染)
+    # ============================================================
+    _real_stdout = None
+
+    @classmethod
+    def _setup_streams(cls):
+        """把 sys.stdout 存起来, 重定向 sys.stdout→stderr (子进程的 print 进 stderr)。"""
+        if cls._real_stdout is None:
+            cls._real_stdout = sys.stdout
+            sys.stdout = sys.stderr
+
+    # ============================================================
+    # final: 协议发送
+    # ============================================================
+    @classmethod
+    def _send(cls, msg: Dict[str, Any]) -> None:
+        """发送 JSON-RPC 消息到真实 stdout (跨3个server逐字一致)。"""
+        cls._real_stdout.write(json.dumps(msg, ensure_ascii=False) + "\n")
+        cls._real_stdout.flush()
+
+    # ============================================================
+    # 默认 handle_tool: 从 _tool_map 自动分发 (装饰器模式)
+    # ============================================================
+    def handle_tool(self, name: str, args: Dict[str, Any]) -> str:
+        """[默认实现] 从 ToolRegistry 取 handler 执行。
+
+        - 若用了 @tool 装饰器: 自动分发, 子类不覆写
+        - 若传统模式 (子类覆写了 handle_tool): 走子类的 if 链
+        """
+        entry = self._tool_map.get(name)
+        if entry:
+            handler = getattr(self, entry["handler"])
+            return handler(args)
+        return "未知工具: %s" % name
+
+    def on_initialize_hook(self, info: Dict[str, Any]) -> None:
+        """[可选覆写] initialize 时往 serverInfo 塞额外信息 (如 warning)。
+
+        默认空。mysql/zentao 在此调 check_intranet 塞 warning。
+        """
+        pass
+
+    def on_tool_error(self, e: Exception) -> Tuple[str, bool]:
+        """[可选覆写] tools/call 抛异常时的分类。
+
+        Returns:
+            (text, is_error): 返回给客户端的文本 + 是否标记为错误
+        默认: 通用异常 → "[error] xxx" + is_error=True。
+        mysql 覆写此方法把 ValueError(只读拒绝)单独分类。
+        """
+        return ("[error] %s" % str(e)[:200], True)
+
+    # ============================================================
+    # final: 请求处理骨架 (Template Method)
+    # ============================================================
+    async def _handle(self, req: Dict[str, Any]) -> None:
+        """处理一个 JSON-RPC 请求 (五分支骨架, 子类不覆写)。"""
+        method = req.get("method", "")
+        req_id = req.get("id")
+        params = req.get("params", {}) or {}
+
+        if method == "initialize":
+            info = {"name": self.SERVER_NAME, "version": self.SERVER_VERSION}
+            self.on_initialize_hook(info)  # 钩子: 子类塞 warning
+            self._send({
+                "jsonrpc": "2.0", "id": req_id,
+                "result": {
+                    "protocolVersion": self.PROTOCOL_VERSION,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": info,
+                },
+            })
+        elif method == "notifications/initialized":
+            pass
+        elif method == "tools/list":
+            self._send({"jsonrpc": "2.0", "id": req_id, "result": {"tools": self.TOOLS}})
+        elif method == "tools/call":
+            tool_name = params.get("name", "")
+            arguments = params.get("arguments", {}) or {}
+            try:
+                result_text = await asyncio.get_event_loop().run_in_executor(
+                    None, self.handle_tool, tool_name, arguments
+                )
+                self._send({
+                    "jsonrpc": "2.0", "id": req_id,
+                    "result": {
+                        "content": [{"type": "text", "text": result_text}],
+                        "isError": False,
+                    },
+                })
+            except Exception as e:
+                text, is_error = self.on_tool_error(e)
+                self._send({
+                    "jsonrpc": "2.0", "id": req_id,
+                    "result": {
+                        "content": [{"type": "text", "text": text}],
+                        "isError": is_error,
+                    },
+                })
+        elif method == "ping":
+            self._send({"jsonrpc": "2.0", "id": req_id, "result": {}})
+        elif req_id is not None:
+            self._send({
+                "jsonrpc": "2.0", "id": req_id,
+                "error": {"code": -32601, "message": "Method not found: %s" % method},
+            })
+
+    # ============================================================
+    # final: 主循环
+    # ============================================================
+    def run(self) -> None:
+        """启动 stdio 主循环 (readline → 解析 → _handle)。子类不覆写。"""
+        self._setup_streams()
+        tag = "[%s]" % self.SERVER_NAME
+        while True:
+            try:
+                line = sys.stdin.buffer.readline()
+            except (EOFError, OSError):
+                break
+            if not line:
+                break
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                req = json.loads(line.decode("utf-8"))
+                loop = asyncio.new_event_loop()
+                loop.run_until_complete(self._handle(req))
+                loop.close()
+            except json.JSONDecodeError:
+                pass
+            except Exception as e:
+                print("%s error: %s" % (tag, str(e)[:80]), file=sys.stderr)

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

@@ -17,7 +17,22 @@ from typing import Optional, Dict
 
 # Project root (auto-detect: find .qoder/ upward)
 def _find_repo_root() -> Path:
-    """Find project root by searching for .qoder/ directory."""
+    """Find project root by searching for .qoder/ directory.
+
+    优先看 cwd: AI/CLI 常在项目根调 `python .qoder/scripts/xxx.py`,
+    cwd 就是项目根。再用 __file__ 兜底 (脚本被 import 时 cwd 可能不对)。
+    """
+    cwd = Path.cwd()
+    if (cwd / ".qoder").is_dir():
+        return cwd
+    current = cwd
+    for _ in range(10):
+        if (current / ".qoder").is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
     current = Path(__file__).resolve().parent
     for _ in range(10):
         if (current / ".qoder").is_dir():
@@ -267,6 +282,177 @@ def get_developer_drafts_dir(developer_name: str) -> Path:
     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等)。
+
+    向后兼容: 老的 .secrets/ 有则用它, 否则用 .private/secrets/。
+    """
+    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"
+    if old_secrets.exists() and not new_secrets.exists():
+        return old_secrets  # 渐进迁移: 老的还在先用老的
+    new_secrets.mkdir(parents=True, exist_ok=True)
+    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)