@hupan56/wlkj 2.6.0 → 2.7.1

package/templates/qoder/hooks/session-start.py

@@ -65,7 +65,7 @@ def _recent_hook_errors(hours=24, limit=3):
 # Injected as REAL OUTPUT below (a comment here would never reach the AI)
 CRITICAL_RULE = NL.join([
     '## CRITICAL RULE',
-    'When user asks for /wl-prd, ALWAYS ask platform FIRST:',
+    'When user asks for /wl-prd-full, ALWAYS ask platform FIRST:',
     '"这个需求是针对哪个平台？',
     ' 1. Web 管理端 (fywl-ui) - Ant Design Vue + VxeGrid 风格',
     ' 2. APP 移动端 (Carmg-H5) - Vant 风格',
@@ -142,63 +142,94 @@ def get_index_info():
     except OSError:
         pass
 
-    lines.append('## Knowledge Index')
-    lines.append('Use search script (DO NOT read large JSON files directly):')
+    lines.append('## Knowledge Graph')
+    lines.append('MCP工具 (QoderWork自动调用): search_code / get_impact / coverage_matrix / get_workflow 等11个')
     lines.append('  python .qoder/scripts/search_index.py <keyword> [--platform web|app]')
-    lines.append('  python .qoder/scripts/search_index.py --prd <keyword>   # search PRDs')
-    lines.append('  python .qoder/scripts/search_index.py --style <table|form> [--platform p]')
-    lines.append('  python .qoder/scripts/search_index.py --field <name>    # field usage')
-    lines.append('  python .qoder/scripts/search_index.py --api <keyword>   # API endpoints')
-    lines.append('  python .qoder/scripts/search_index.py --components      # UI components')
-    lines.append('  python .qoder/scripts/search_index.py --modules         # project overview')
-    lines.append('  python .qoder/scripts/search_index.py --list            # top keywords')
-
-    meta = load_json_safe(os.path.join(BASE, 'data', 'index', '.index-meta.json'))
-    if meta:
-        projects = meta.get('projects', {})
-        if isinstance(projects, dict):
-            for proj, info in projects.items():
-                if isinstance(info, dict):
-                    files = info.get('files', 0)
-                else:
-                    files = info  # new meta format: {project: file_count}
-                lines.append('  ' + str(proj) + ': ' + str(files) + ' files')
-        elif isinstance(projects, list):
-            for proj in projects:
-                lines.append('  ' + str(proj))
-        lines.append('Last sync: ' + str(meta.get('last_sync', 'unknown')))
-        # Staleness warning (审计发现: cron 从未注册, 索引可能静默过期)
-        last_sync = meta.get('last_sync')
-        if last_sync:
-            try:
-                from datetime import datetime
-                # 兼容多种格式: "2026-06-12 16:49" / ISO
-                ts = str(last_sync).replace('T', ' ').split('.')[0].strip()
-                for fmt in ('%Y-%m-%d %H:%M', '%Y-%m-%d %H:%M:%S', '%Y-%m-%dT%H:%M:%S'):
-                    try:
-                        sync_dt = datetime.strptime(ts, fmt)
-                        break
-                    except ValueError:
-                        continue
-                else:
-                    sync_dt = None
-                if sync_dt:
-                    age_days = (datetime.now() - sync_dt).days
-                    if age_days > 30:
-                        lines.append('[CRITICAL] 索引已 {} 天未更新! 搜索结果严重过期. 跑: python .qoder/scripts/git_sync.py'.format(age_days))
-                    elif age_days > 7:
-                        lines.append('[WARN] 索引已 {} 天未更新, 建议刷新: python .qoder/scripts/git_sync.py'.format(age_days))
-            except Exception:
-                pass  # 日期解析失败不阻塞
-        if meta.get('failures'):
-            lines.append('WARNING: last sync had errors - see data/index/.index-meta.json')
+    lines.append('  python .qoder/scripts/context_pack.py <keyword>   # 一次打包全部上下文')
+
+    # DuckDB 知识图谱状态检查
+    # Read role from .developer file
+    role = 'pm'
+    try:
+        dev_file = os.path.join(BASE, '.qoder', '.developer')
+        if os.path.isfile(dev_file):
+            for _line in open(dev_file, encoding='utf-8'):
+                if _line.strip().startswith('role='):
+                    role = _line.split('=', 1)[1].strip()
+    except Exception:
+        pass
+    db_path = os.path.join(BASE, 'data', 'index', 'kg.duckdb')
+
+    if os.path.isfile(db_path):
+        import time as _time
+        db_mtime = os.path.getmtime(db_path)
+        db_age_hours = (_time.time() - db_mtime) / 3600
+
+        # 检查代码是否比 DuckDB 新 (采样几个文件)
+        code_dir = os.path.join(BASE, 'data', 'code')
+        code_newer = False
+        if os.path.isdir(code_dir):
+            for root, dirs, files in os.walk(code_dir):
+                dirs[:] = [d for d in dirs if d not in ('node_modules', '.git', 'dist', '__pycache__')]
+                depth = root[len(code_dir):].count(os.sep)
+                if depth >= 3:
+                    dirs[:] = []
+                    continue
+                for fn in files:
+                    if fn.endswith(('.vue', '.java', '.ts')):
+                        try:
+                            if os.path.getmtime(os.path.join(root, fn)) > db_mtime:
+                                code_newer = True
+                                break
+                        except OSError:
+                            pass
+                if code_newer:
+                    break
+
+        lines.append('  kg.duckdb: %.0f小时前构建' % db_age_hours)
+
+        if role in ('admin', 'dev'):
+            # 管理员/开发: 能构建
+            if code_newer or db_age_hours > 168:  # 7天 = 168小时
+                lines.append('  [WARN] 知识图谱过期! 代码有新变更.')
+                lines.append('  → 管理员请运行: python .qoder/scripts/kg_build.py')
+                lines.append('  → 完成后: python .qoder/scripts/team_sync.py push (共享给团队)')
+            else:
+                lines.append('  ✓ 知识图谱最新')
+        else:
+            # 非管理员: 只拉取
+            if code_newer or db_age_hours > 168:
+                lines.append('  [WARN] 知识图谱可能过期.')
+                lines.append('  → 运行: python .qoder/scripts/team_sync.py pull (获取管理员最新构建)')
+            else:
+                lines.append('  ✓ 知识图谱最新')
+
+        # 检查是否有未标注的模块 (提示AI做语义标注)
+        try:
+            import subprocess as _sp
+            r = _sp.run([sys.executable, os.path.join(BASE, '.qoder', 'scripts', 'kg_semantic.py'), '--check'],
+                        capture_output=True, text=True, encoding='utf-8', timeout=5)
+            if r.stdout and 'semantic_labeling_needed' in r.stdout:
+                import json as _json
+                data = _json.loads(r.stdout)
+                unlabeled = len(data.get('modules', []))
+                if unlabeled > 0:
+                    lines.append('  [提示] %d个模块未标注中文名, 运行 kg_semantic.py --check 查看' % unlabeled)
+        except Exception:
+            pass
+    else:
+        lines.append('  [MISSING] kg.duckdb 不存在!')
+        if role in ('admin', 'dev'):
+            lines.append('  → 运行: python .qoder/scripts/kg_build.py')
+        else:
+            lines.append('  → 运行: python .qoder/scripts/team_sync.py pull')
 
     return NL.join(lines)
 
 
 def get_style_info():
     """Read style metadata for quick reference"""
-    meta = load_json_safe(os.path.join(BASE, 'data', 'index', 'style-meta.json'))
+    meta = load_json_safe(os.path.join(BASE, 'data', 'index', 'ui-style-meta.json'))
     if not meta:
         return None
 

package/templates/qoder/rules/wl-pipeline.md

@@ -1,105 +1,216 @@
----
-trigger: always_on
----
-
-# QODER Pipeline 工作流规则（全模式生效）
-
-> 本规则是 wl-pipeline 的核心约束，通过 .qoder/rules/ 在 Qoder IDE 对话、
-> Quest 模式中始终生效。Qoder CLI 读根目录 AGENTS.md（内容一致）。
-> 完整命令定义在 .qoder/commands/wl-*.md，技能在 .qoder/skills/。
-
-## 规则 0：自然语言 → 技能 路由表（全端通用）
-
-所有 Qoder 产品（IDE 编辑器 / Quest 模式 / QoderWork 桌面端 / CLI）都支持两种触发方式：
-1. **斜杠命令**：输入 `/wl-prd` `/wl-search` 等（commands 和 skills 都可用 `/` 触发）
-2. **自然语言**：直接说"写个需求""查一下代码"，AI 按下表自动映射到对应 skill
-
-> 注意：Quest/QoderWork 里 `/` 会同时列出 commands（如 `/wl-prd`）和 skills（如 `/prd-generator`）。
-> 两者功能等价，优先用 `/wl-*` 命令（更稳定，参数提示更全）。
-
-| 用户说什么 | 触发的 skill/command |
-|------------|---------------------|
-| "写个需求""生成PRD""做个原型""保单这块加个功能" | `/wl-prd` 或 prd-generator + prototype-generator |
-| "查一下""代码在哪""搜保险""考勤的API""字段含义" | `/wl-search` 或 wl-search |
-| "建任务""排优先级""这个任务做完了""开始做这个" | `/wl-task` 或 wl-task |
-| "项目怎么样""进度""健康度""路线图" | `/wl-status` 或 wl-status |
-| "写日报""周报""我这周干了啥""今天做了什么" | `/wl-report` 或 wl-report |
-| "用户反馈""数据怎么样""转化漏斗""留存" | `/wl-insight` 或 wl-insight |
-| "生成规格""写spec""技术方案" | `/wl-spec` 或 spec-generator |
-| "开始写代码""按规格实现""实现这个接口" | `/wl-code` 或 spec-coder |
-| "写单元测试""补测试""覆盖一下" | `/wl-test` 或 test-generator |
-| "评审PRD""PRD质量怎么样" | prd-review |
-| "提交代码""commit""推上去""保存代码" | `/wl-commit` 或 wl-commit |
-| "初始化""换开发者""环境检查""我是谁" | `/wl-init` 或 wl-init |
-
-**找不到明确匹配时：先问用户意图，不要乱跑**（"你是想写 PRD、查代码、还是建任务？"）。
-注意：用户说"同步/保存产出"通常指 team_sync（push），不是 git commit；
-用户说"提交/commit 代码"才是 wl-commit。
-
-## 规则 1：PRD/原型需求必须先问平台
-
-用户提出 PRD、原型、需求分析类请求时，第一步永远是问（绝不自动判断）：
-
-```
-这个需求是针对哪个平台？
-1. **Web 管理端** (fywl-ui) - Ant Design Vue + VxeGrid 风格
-2. **APP 移动端** (Carmg-H5) - Vant 风格
-3. **两端都要
-请选择 (1/2/3):
-```
-
-## 规则 2：查代码只用索引，不全库 grep
-
-```bash
-python .qoder/scripts/context_pack.py <业务关键词> --platform <web|app>   # 一次取全(首选)
-python .qoder/scripts/search_index.py <关键词> --platform <web|app>      # 单项搜索
-```
-context_pack 一条命令返回：相关代码文件 + 同类页面示例 + 字段规格 +
-相关 PRD + 设计 Token + 图标参考 + 模板路径。禁止对 data/code/ 全库 grep。
-
-## 规则 3：原型风格必须来自真源（含图标）
-
-- 起点永远是平台模板：.qoder/templates/prototype-web.html / prototype-app.html
-- 颜色只用真源：data/index/vben-style-reference.json（Web HSL token）、
-  chart-style-reference.json（看板/大屏两种系统内风格）、Vant 变量（APP）
-- **图标绝对禁止 emoji**：Web 用 data/index/icon-reference.json 里的
-  Ant Design 真实 SVG（内联，fill=currentColor）；APP 用 Vant 字体图标
-  （CDN: https://cdn.jsdelivr.net/npm/vant@4/lib/index.css + van-icon 类名）
-- 新功能（无现有页面）也必须锚定系统内最近似的真实页面：
-  大屏/全国地图类 → dashboard/monitor 先例；工作台卡片类 → dashboard/workbench
-- 原型头部注释必须写明风格来自哪些真实文件，写不出来源 = 风格提取没做
-
-## 规则 4：PRD 必须套团队模板 + 过 EVA 门禁
-
-- 完整需求用 .qoder/templates/prd-full-template.md，零星需求用 prd-quick-template.md
-- 发布前：`python .qoder/scripts/eval_prd.py <prd> [原型]` 必须 PASS (≥80%)
-- 发现确认采用批量方式（一个编号列表一轮确认），不要逐条问
-
-## 规则 5：用户永不接触 git
-
-- 产出保存/发布后自动执行 `python .qoder/scripts/team_sync.py push`
-- 拉取团队最新：`python .qoder/scripts/team_sync.py pull`
-- 出现 SYNC_CONFLICT 由 AI 按提示自行解决，绝不让用户跑 git 命令
-
-## 规则 6：环境问题找 doctor
-
-任何"索引不对/搜不到/环境坏了"类问题：
-`python .qoder/scripts/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
-
-## 规则 7：Repo Wiki 是补充知识源
-
-若存在 .qoder/repowiki/（Qoder IDE 生成的仓库 Wiki），写 PRD 前先查其中
-相关模块页面（架构、模块说明比索引更全面）；data/code/ 下各源码仓库若有
-自己的 repowiki 同样优先参考。索引负责"定位文件"，Wiki 负责"理解模块"。
-
-## 用户侧命令一览（用户只需要知道这些）
-
-| 命令 | 作用 |
-|------|------|
-| /wl-init [名字] [角色] | 初始化/切换开发者 + 环境体检 |
-| /wl-prd <需求描述> | 生成 PRD + 原型（最核心） |
-| /wl-search <关键词> | 查代码/PRD/字段/API |
-| /wl-task, /wl-status, /wl-report | 任务/状态/日报周报 |
-| /wl-spec, /wl-code, /wl-test, /wl-commit | 规格/编码/测试/提交（后三个需确认） |
-
-用户用自然语言表达即可，AI 负责映射到命令和脚本。
+---
+trigger: always_on
+---
+
+# QODER Pipeline 工作流规则（全模式生效）
+
+> 本规则是 wl-pipeline 的核心约束，通过 .qoder/rules/ 在 Qoder IDE 对话、
+> Quest 模式中始终生效。Qoder CLI 读根目录 AGENTS.md（内容一致）。
+> 完整命令定义在 .qoder/commands/wl-*.md，技能在 .qoder/skills/。
+
+## 规则 -1：首次使用须知（全端通用，最高优先级）
+
+**任何命令/自然语言请求执行前，AI 必须先检查工作流是否已初始化。**
+
+检查方法（一次即可，幂等）：
+```bash
+# 看 .qoder/.developer 是否存在
+test -f .qoder/.developer && echo "已初始化" || echo "未初始化"
+```
+
+**若未初始化**（`.qoder/.developer` 不存在），无论用户说什么（"写需求""查代码""建任务"…），
+都**先停下，引导初始化**，不要直接跑命令（会失败）：
+
+> 还没初始化工作流。先完成一次初始化（约 1 分钟）：
+> - **Qoder IDE / Quest / QoderWork**：说"初始化"或跑 `/wl-init`，按提示填名字和角色
+> - **命令行**：`npx @hupan56/wlkj init <名字> <角色>`
+>
+> 角色：产品(pm)/设计(design)/开发(dev)/测试(test)/管理(admin)
+> 初始化完就能正常用了。
+
+**若已初始化**，正常路由到下面的规则 0。
+
+> 为什么这条最高优先级：Quest 模式没有 `/wl-init` 的强制入口，用户可能直接说
+> "写个需求"，但身份没初始化会导致命令静默失败。50 人团队里新成员第一句话
+> 就撞这个的概率很高，必须在规则层兜住。
+
+## 规则 0：自然语言 → 技能 路由表（全端通用）
+
+所有 Qoder 产品（IDE 编辑器 / Quest 模式 / QoderWork 桌面端 / CLI）都支持两种触发方式：
+1. **斜杠命令**：输入 `/wl-prd-full` `/wl-search` 等（commands 和 skills 都可用 `/` 触发）
+2. **自然语言**：直接说"写个需求""查一下代码"，AI 按下表自动映射到对应 skill
+
+> 注意：Quest/QoderWork 里 `/` 会同时列出 commands（如 `/wl-prd-full`）和 skills（如 `/prd-generator`）。
+> 两者功能等价，优先用 `/wl-*` 命令（更稳定，参数提示更全）。
+
+| 用户说什么 | 触发的 skill/command |
+|------------|---------------------|
+| "写个需求""生成PRD""做个原型""新模块""保单这块加个功能" | `/wl-prd-full` 或 prd-generator + prototype-generator |
+| "加个字段""加个导出按钮""改下文案""小改动" | `/wl-prd-quick`（快档，零星需求）|
+| "查一下""代码在哪""搜保险""考勤的API""字段含义" | `/wl-search` 或 wl-search |
+| "建任务""排优先级""这个任务做完了""开始做这个" | `/wl-task` 或 wl-task |
+| "项目怎么样""进度""健康度""路线图" | `/wl-status` 或 wl-status |
+| "写日报""周报""我这周干了啥""今天做了什么" | `/wl-report` 或 wl-report |
+| "调研""竞品""对标""规划""路线图""接下来做什么""发现个机会""探讨需求" | `/wl-insight` 或 wl-insight（探索站：发现/调研/规划）|
+| "生成规格""写spec""技术方案" | `/wl-spec` 或 spec-generator |
+| "开始写代码""按规格实现""实现这个接口" | `/wl-code` 或 spec-coder |
+| "跑测试用例""执行测试任务""回归测试任务" | `/wl-test`（测试工作流）或 wl-test |
+| "写单元测试""补单测""生成test" | `/wl-test unit` 或 test-generator |
+| "评审PRD""PRD质量怎么样""检查需求文档" | `/wl-prd-review`（评审 PRD 质量）|
+| "提交代码""commit""推上去""保存代码" | `/wl-commit` 或 wl-commit |
+| "初始化""换开发者""环境检查""我是谁" | `/wl-init` 或 wl-init |
+| **"出个原型""画个界面""做个 mockup""改个页面"** | **`/wl-design-draw`（画界面）** |
+| **"XX 有哪些页面""XX 操作流程""系统什么风格""改XX影响什么"** | **`/wl-design-scan`（审视现状）** |
+| **"录入设计稿""评审原型""检查原型""Figma 稿""蓝湖稿""蓝湖链接""lanhu"** | **`/wl-design-spec`（设计交付，蓝湖链接优先用 `mcp__lanhu__*` 直读）** |
+| "测试覆盖""哪些功能有测试""哪些没测试""回归盲区" | `/wl-design-scan` 或 MCP `coverage_matrix()` |
+| "这个功能完整吗""XX功能画像" | `/wl-design-scan` 或 MCP `feature_overview(feature='XX')` |
+| "改XX会影响什么""改这个接口影响哪些页面" | `/wl-design-scan` 或 MCP `get_impact(endpoint='XX')` |
+| "XX函数谁调用了""XX的调用链" | MCP `context_360(symbol='XX')` |
+
+> 知识图谱 13 个能力（`kg.py`）**全系列通用**：QoderWork 环境 AI 也可直接调
+> MCP 工具（`mcp__qoder-knowledge-graph__*`），非 MCP 环境跑 kg.py，数据一致。
+> 能力清单见 `/wl-search`。
+
+**找不到明确匹配时：先问用户意图，不要乱跑**（"你是想写 PRD、查代码、还是建任务？"）。
+注意：用户说"同步/保存产出"通常指 team_sync（push），不是 git commit；
+用户说"提交/commit 代码"才是 wl-commit。
+
+**🧩 提问润色（可选增强，纯 Qoder IDE/CLI 用，QoderWork 有 MCP 不需要）**：
+非 MCP 环境下，用户输入含业务词时，可先跑 `python .qoder/scripts/enrich_prompt.py "<用户输入>"`
+做 <10ms 的极速关键词扩展，让用户确认后再走实际命令。MCP 环境下跳过（AI 直接调 MCP 工具已含扩展）。
+
+## 规则 1：PRD/原型需求必须先问平台（问了就停，不许边问边干）
+
+用户提出 PRD、原型、需求分析类请求时，第一步永远是问（绝不自动判断）：
+
+```
+这个需求是针对哪个平台？
+1. **Web 管理端** (fywl-ui) - Ant Design Vue + VxeGrid 风格
+2. **APP 移动端** (Carmg-H5) - Vant 风格
+3. **两端都要
+请选择 (1/2/3):
+```
+
+**⚠️ 铁律：问完平台必须停下，整条回复到此结束。不许在同一回合里并行做别的**
+（不许搜代码、不许读文件、不许分析、不许出方案）。等用户回答平台后再开始下一步。
+原因：平台不同，搜索范围、原型模板、设计 Token 全都不同——平台没定就开干，
+方向必然错，白白浪费一轮工具调用。"边问边干"是这条规则最常见的违规形态。
+
+## 规则 2：查代码索引优先，索引找不到才准 grep（又快又准的取数顺序）
+
+```bash
+python .qoder/scripts/kg.py context <业务关键词> --platform <web|app> [--role pm|design|dev|test]  # 一次取全(首选, 秒级)
+python .qoder/scripts/search_index.py <关键词> --platform <web|app>      # 单项搜索
+```
+kg.py context（= context_pack）一条命令返回：相关代码文件 + 同类页面示例 + 字段规格 +
+相关 PRD + 设计 Token + 图标参考 + 模板路径。kg.py 还有 12 个兄弟能力
+（impact/coverage/feature/workflow/hop/...），统一入口见 `/wl-search`。
+
+**取数顺序（强制，违反 = 慢 + 凭空写 PRD）：**
+1. **先用索引**：任何 /wl-* 命令查代码，**第一步永远是 kg.py context**（查预建图谱，秒级，不碰文件系统）。绝大多数需求一次就够。
+2. **索引够用就停**：context 列出了相关文件/字段/API → 只用 Read 读那 1-2 个 .vue，**不要再用 Grep/Glob 去文件系统扫**。
+3. **索引真找不到才 grep 兜底**：只有当 kg.py/search_index 明确返回"无匹配"或缺了某个具体点时，才回退到 Grep/Glob 直搜 —— 且**只搜 context 指向的范围**，不准对 data/code/（8973+ 文件）或整个 qoderAll 仓全库扫。
+
+**为什么这条是红线**：QoderWork 自带 Agent 默认会用 Grep/Glob 直搜文件系统，它不懂"业务源码在 data/code/ 镜像里"，会搜整个 qoderAll 仓然后报"无匹配"，被迫凭空编字段/API。**Agent 只准用来**：①读 context 列出的具体文件（Read）②**在 /wl-insight 里**做 web 调研（对标/竞品）和多视角探索脑暴。**绝不用 Agent 去"发现/搜索"代码——那是 kg.py 的活。** 注意：探索类 Agent 调研已集中到 `/wl-insight`，`/wl-prd-full` 不再派 Agent 做 web 搜索/脑暴。
+
+## 规则 3：原型风格必须来自真源（含图标）
+
+- 起点永远是平台模板：.qoder/templates/prototype-web.html / prototype-app.html
+- 颜色只用真源：data/index/vben-style-reference.json（Web HSL token）、
+  chart-style-reference.json（看板/大屏两种系统内风格）、Vant 变量（APP）
+- **图标绝对禁止 emoji**：Web 用 data/index/icon-reference.json 里的
+  Ant Design 真实 SVG（内联，fill=currentColor）；APP 用 Vant 字体图标
+  （CDN: https://cdn.jsdelivr.net/npm/vant@4/lib/index.css + van-icon 类名）
+- 新功能（无现有页面）也必须锚定系统内最近似的真实页面：
+  大屏/全国地图类 → dashboard/monitor 先例；工作台卡片类 → dashboard/workbench
+- 原型头部注释必须写明风格来自哪些真实文件，写不出来源 = 风格提取没做
+
+## 规则 3.5：UI 设计师协作（设计师 ≠ AI 对立面）
+
+设计师用 Figma/Axure 出图，但成果必须回流工作流，不能跟 AI 原型各干各的。
+
+**设计师的 3 种接入方式（QoderWork 自然语言触发）：**
+
+| 设计师说什么 | 触发 | 做什么 |
+|-------------|------|--------|
+| "录入设计稿""把这个 Figma 稿录入" | design-import | 设计稿→spec.json→存 data/style/→进知识图谱，下次 AI 优先用它 |
+| "评审原型""设计稿看一下" | design-review | 检查 AI 原型是否跟系统风格/设计师规范一致 |
+| "按这个规格出原型" | prototype-generator | 设计师只出规格（布局/配色/组件），AI 按规格生成 HTML |
+
+**铁律：设计师的 spec 优先级 > 代码风格 > PDF 规范**
+- `data/style/{需求名}-design-spec.json` 一旦存在，同需求的 prototype 必须锚定它
+- 设计师录入了 spec 后，AI 出原型前先检查有没有对应 spec，有就用
+- 这解决"AI 原型和 Figma 稿打架"——设计师的 spec 成了单一风格真源
+
+**典型协作流程：**
+```
+PM /wl-prd-full → AI 出初稿 PRD + 原型
+  → 设计师 QoderWork 说"录入设计稿" (design-import): Figma 稿→spec.json
+  → PM 说"按设计师规范修订原型" → AI 用 spec 重生成原型
+  → 设计师说"评审原型" (design-review) → 通过
+  → /wl-commit → 前端拿到 PRD + 匹配设计师规范的原型
+```
+
+## 规则 4：PRD 必须套团队模板 + 过 EVA 门禁
+
+- 完整需求用 .qoder/templates/prd-full-template.md，零星需求用 prd-quick-template.md
+- 发布前：`python .qoder/scripts/eval_prd.py <prd> [原型]` 必须 PASS (≥80%)
+- 发现确认采用批量方式（一个编号列表一轮确认），不要逐条问
+
+## 规则 5：用户永不接触 git
+
+- 产出保存/发布后自动执行 `python .qoder/scripts/team_sync.py push`
+- 拉取团队最新：`python .qoder/scripts/team_sync.py pull`
+- 出现 SYNC_CONFLICT 由 AI 按提示自行解决，绝不让用户跑 git 命令
+
+## 规则 6：环境问题找 doctor
+
+任何"索引不对/搜不到/环境坏了"类问题：
+`python .qoder/scripts/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
+
+## 规则 7：Repo Wiki 是补充知识源
+
+若存在 .qoder/repowiki/（Qoder IDE 生成的仓库 Wiki），写 PRD 前先查其中
+相关模块页面（架构、模块说明比索引更全面）；data/code/ 下各源码仓库若有
+自己的 repowiki 同样优先参考。索引负责"定位文件"，Wiki 负责"理解模块"。
+
+## 规则 8：QoderWork 只做可选增强（渐进增强，绝不强依赖）
+
+🔒 **核心约束：团队里有人用 Qoder IDE、有人用 Qoder CLI、有人用 QoderWork —— 流水线
+必须在纯 Qoder（IDE/CLI）下开箱即用、功能完整。** QoderWork 的连接器 / 专家套件 /
+定时任务只是「有则锦上添花、无则静默回退」的可选层，绝不能成为依赖。
+
+落实方式：
+1. **本地是唯一事实源**：task.json / git log / drafts / index 是真相，连接器只是它的投影
+2. **增强段统一标 `🧩 QoderWork 增强（可选）`**：wl-report（读日历补日报）、
+   wl-task（待办双向同步）、wl-status（日历校准健康度）、wl-test（浏览器自动执行测试）
+   四处已接入，每段都写明回退保证
+3. **探测而非假设**：只在运行环境真正提供「日历/待办/邮件」工具可读时才启用；
+   看不到就跳过，补一句 `[xx 未启用：非 QoderWork 或未授权连接器]`，不报错不阻塞
+4. **新增任何 QoderWork 增强都必须先保证纯 Qoder 可跑，再叠加可选层**
+
+## 用户侧命令一览（用户只需要知道这些）
+
+**7 个核心命令**（每道工序一个，带模式参数路由）：
+
+| 命令 | 工序站 | 模式参数 |
+|------|--------|---------|
+| /wl-init [名字] [角色] | 身份 | （无） |
+| /wl-prd-full <需求> | 需求落地（完整档） | 支持 `参考:<报告>` 衔接 insight |
+| /wl-prd-quick <需求> | 需求落地（小改动） | （无） |
+| /wl-design <模式> | 设计 | import/generate/review 或默认(import) |
+| /wl-task <子命令> | 任务 | create/list/start/finish |
+| /wl-code | 编码 | （按 spec 实现，需确认） |
+| /wl-test <模式> | 测试 | quick/browser/unit 或默认(quick，需确认) |
+| /wl-commit | 提交 | （需确认） |
+
+**可选命令**（按需启用）：/wl-search（代码搜索，全员工具）、/wl-spec（技术规格）、
+/wl-status（项目健康度）、/wl-report（日报周报）、
+/wl-insight（探索站：discover/research/plan，**位于 /wl-prd-full 之前**）。
+
+> 模块契约（输入/输出/校验）：见 `.qoder/contracts/`。
+> `/wl-test` 默认浏览器自动化测试（据任务 PRD 生成用例 → QoderWork 浏览器执行，
+> 纯 Qoder 降级人工核对）；说"单元测试/单测"走 `/wl-test unit`（Java 单测）。
+> 环境/域名在 config.yaml `autotest:` 配，`--url` 可临时覆盖。
+
+用户用自然语言表达即可，AI 负责映射到命令和脚本。