@hupan56/wlkj 2.5.0 → 2.7.0

package/templates/qoder/scripts/task.py

@@ -10,7 +10,10 @@ QODER Pipeline - 任务生命周期管理
 - finish: 完成任务 (清除活跃任务)
 - archive: 归档任务 (移动到 archive/ 目录)
 - list: 列出活跃/归档任务
+- show: 查看任务详情
+- reassign: 改派任务负责人 (多角色协作, PM 建任务后转给开发)
 - add-subtask / remove-subtask: 父子任务关联
+- set-due / block / unblock / gantt: 排期与依赖
 
 参考: Trellis 的 task.py 设计
 
@@ -20,6 +23,7 @@ Usage:
     python task.py current [--source]
     python task.py finish
     python task.py archive <name>
+    python task.py reassign <name> <new_assignee>
     python task.py list [--mine] [--status <s>]
     python task.py add-subtask <parent> <child>
     python task.py remove-subtask <parent> <child>
@@ -331,6 +335,18 @@ def cmd_finish(args: argparse.Namespace) -> int:
     if task_json_path.is_file():
         run_task_hooks("after_finish", task_json_path, repo_root)
 
+    # 埋点: 任务完成反馈给 learning 引擎
+    if _finish_ctx:
+        try:
+            from learn import record_feedback
+            record_feedback('task_completed', {
+                'task': task_dir.name,
+                'assignee': _finish_ctx.get('assignee', '?'),
+                'hours': _finish_ctx.get('now_iso'),
+            })
+        except Exception:
+            pass  # 埋点失败不阻塞任务完成
+
     return 0
 
 
@@ -692,6 +708,59 @@ def cmd_set_due(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_reassign(args: argparse.Namespace) -> int:
+    """改派任务负责人。用法: task.py reassign <task> <new_assignee>
+
+    场景: PM 建任务后改派给开发(多角色协作必需)。
+    ACL: 只有 creator/admin 能改派(防恶意抢占/甩锅)。
+    保留改派历史(assignee_history), 便于追溯。
+    """
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.task, repo_root)
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    # ACL: 只有 creator/admin 能改派 (assignee 自己不能转手甩锅)
+    try:
+        assert_can_modify_task(full_path, "reassign", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    new_assignee = (args.new_assignee or "").strip()
+    if not new_assignee:
+        print("Error: new_assignee 不能为空", file=sys.stderr)
+        return 1
+
+    changed = {"from": None, "to": new_assignee}
+
+    def _reassign_mutator(data):
+        old = data.get("assignee")
+        changed["from"] = old
+        data["assignee"] = new_assignee
+        data["updated_at"] = datetime.now().isoformat()
+        # 记录改派历史 (追溯用)
+        hist = data.get("assignee_history") or []
+        hist.append({
+            "from": old,
+            "to": new_assignee,
+            "by": get_developer(repo_root),
+            "at": datetime.now().isoformat(),
+        })
+        data["assignee_history"] = hist
+
+    if not modify_task_json(full_path, _reassign_mutator):
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+
+    if changed["from"] == new_assignee:
+        print(f"Note: assignee 已是 {new_assignee}, 无变化 ({full_path.name})")
+    else:
+        print(f"Reassigned: {changed['from']} -> {new_assignee} ({full_path.name})")
+        print(f"  改派人: {get_developer(repo_root)} (已记录到 assignee_history)")
+    return 0
+
+
 def cmd_block(args: argparse.Namespace) -> int:
     """标记任务被另一任务阻塞。自动维护反向 blocks 关系。
     用法: task.py block <task> <blocked-by-task>
@@ -979,6 +1048,12 @@ def main() -> int:
     p_due.add_argument("due_date", help="Due date YYYY-MM-DD")
     p_due.set_defaults(func=cmd_set_due)
 
+    # reassign (改派任务负责人, 多角色协作必需)
+    p_reassign = subparsers.add_parser("reassign", help="Reassign task to another developer")
+    p_reassign.add_argument("task", help="Task name")
+    p_reassign.add_argument("new_assignee", help="New assignee (developer name)")
+    p_reassign.set_defaults(func=cmd_reassign)
+
     # block (B2)
     p_block = subparsers.add_parser("block", help="Mark task blocked by another")
     p_block.add_argument("task", help="Task that is blocked")

package/templates/qoder/scripts/team_sync.py

@@ -168,6 +168,41 @@ def report_conflict(stderr):
     return 3
 
 
+def _get_kg_built_at():
+    """读 kg.duckdb 的 built_at 时间戳 (版本号)。"""
+    kg_path = os.path.join(BASE, 'data', 'index', 'kg.duckdb')
+    if not os.path.isfile(kg_path):
+        return 0
+    try:
+        import duckdb
+        con = duckdb.connect(kg_path, read_only=True)
+        row = con.execute("SELECT value FROM build_meta WHERE key='built_at'").fetchone()
+        con.close()
+        return int(row[0]) if row else 0
+    except Exception:
+        # DuckDB 不可用, 用文件 mtime
+        return int(os.path.getmtime(kg_path))
+
+
+def _auto_resolve_kg_conflict():
+    """kg.duckdb 二进制冲突自动解决: 保留 built_at 更新的版本。
+
+    git pull 后如果 kg.duckdb 有冲突 (二进制不能 merge), git 会标记为 conflict。
+    这里自动选 built_at 更大的 (更新的) 版本, 用户无感。
+    """
+    kg_path = os.path.join(BASE, 'data', 'index', 'kg.duckdb')
+    if not os.path.isfile(kg_path):
+        return
+
+    # 检查是否有 kg.duckdb 的 merge conflict
+    r = git('diff', '--name-only', '--diff-filter=U')
+    if r.returncode == 0 and 'kg.duckdb' in r.stdout:
+        # 有冲突 — 我们直接接受当前的 (pull 下来的) 版本
+        # 因为 pull --rebase 会把远程版本放在工作区
+        git('add', 'data/index/kg.duckdb')
+        print('[kg-sync] kg.duckdb 冲突已自动解决 (使用远程最新版本)')
+
+
 def do_pull(quiet=False):
     """拉取团队最新。安全: autostash 保护未提交改动。"""
     if rebase_in_progress():
@@ -192,6 +227,9 @@ def do_pull(quiet=False):
         print('继续离线工作, 产出不会丢失, 下次同步会自动补推。')
         return 1
 
+    # kg.duckdb 冲突自动解决: 如果 pull 带来了更新的 kg.duckdb, 自动用它
+    _auto_resolve_kg_conflict()
+
     touch_pull_marker()
     out = (r.stdout or '').strip()
     if not quiet:
@@ -384,13 +422,22 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
     for attempt in range(1, MAX_PUSH_RETRY + 1):
         r = git('pull', '--rebase', '--autostash', 'origin', branch)
         if r.returncode != 0:
-            if 'CONFLICT' in (r.stdout + r.stderr) or rebase_in_progress():
+            # kg.duckdb 二进制冲突: 自动解决 (用户无感)
+            _auto_resolve_kg_conflict()
+            if rebase_in_progress():
+                # 冲突解决后继续 rebase
+                r2 = git('rebase', '--continue')
+                if r2.returncode == 0:
+                    pass  # 继续 push
+                elif 'CONFLICT' in (r2.stdout + r2.stderr):
+                    return report_conflict(r2.stderr or r2.stdout)
+                else:
+                    continue
+            elif 'CONFLICT' in (r.stdout + r.stderr):
                 return report_conflict(r.stderr or r.stdout)
-            # 非冲突的 pull 失败 (网络/auth/fetch 拒绝): 不往下 push (仓库可能处于
-            # 半 rebase 状态), 重试本循环
+            # 非冲突的 pull 失败
             print('Pull failed (attempt {}): {}'.format(attempt, (r.stderr or r.stdout).strip()[:150]))
             if rebase_in_progress():
-                # 兜底: 万一 pull 留下了未完成的 rebase, abort 掉防仓库损坏
                 git('rebase', '--abort')
             continue
 
@@ -407,6 +454,15 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
                 print('[sync] PRD 归档跳过 (不阻塞): ' + str(e)[:80])
             # D2: 检测 PRD 发布并推飞书通知
             _notify_prd_publications(staged_files)
+            # 埋点: 提交完成反馈给 learning 引擎
+            try:
+                from learn import record_feedback
+                record_feedback('commit_done', {
+                    'files': len(staged_files),
+                    'scope': [s for s in SYNC_SCOPES[:3]],
+                })
+            except Exception:
+                pass  # 埋点失败不阻塞同步
             return 0
         if attempt < MAX_PUSH_RETRY:
             print('Push rejected (someone pushed first?), retrying...')

package/templates/qoder/scripts/workspace_init.py

@@ -92,7 +92,7 @@ def main():
 
     name = sys.argv[1]
     if init_workspace(name):
-        print("\nNext: say 'help me generate PRD' in Codex to start pipeline")
+        print("\nNext: say 'help me generate PRD' in Qoder to start pipeline")
         sys.exit(0)
     else:
         sys.exit(1)

package/templates/qoder/skills/design-import/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: design-import
+description: "把设计师的 Figma/Axure 设计稿录入工作流，生成设计规范 spec.json 并存入知识图谱。Import designer's Figma/Axure design into the pipeline as a style spec. 用户说'录入设计稿''Figma稿录入''把这个设计录入'时触发。"
+trigger: "user says '录入设计稿', 'Figma 稿录入', '把这个设计录入', or wants to feed their design into the AI workflow"
+---
+
+
+## 🔧 仓库根定位（QoderWork 桌面端 vs Qoder IDE/CLI）
+
+**后续脚本里的 `$R` 代表仓库根**，先确定它（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
+```bash
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+```
+> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。找不到时先跑 `python .qoder/scripts/install_qoderwork.py`。
+
+# Design Import Skill（设计师专用）
+
+> 🚫 **边界铁律：蓝湖工具（`mcp__lanhu__*`）只能在本 skill（即 `/wl-design-spec 录入`）内部调用。**
+> 用户直接说"查蓝湖""读一下这个蓝湖链接"而没走录入命令时，**不要裸调蓝湖**——先确认意图，
+> 引导到 `/wl-design-spec 录入 <蓝湖链接>`。工作流是非侵入式的，所有能力必须经命令/工序站触发，
+> 不能脱离流程裸调工具（否则不可控、不可审计）。
+
+把设计师在 Figma/Axure 里出的设计稿，转成工作流能消化的**设计规范 spec.json**，
+存到 `data/style/`，进入知识图谱。从此同需求的 AI 原型优先锚定这份 spec，
+不再跟设计师的稿打架。
+
+## ⚙️ 自取上下文（QoderWork 无 hook 注入，必须自读）
+
+- `.qoder/.developer` — 当前设计师名（产出归属）
+- `.qoder/.current-task` — 若存在，spec 命名带上任务关键词
+- 平台必须明确（Web/APP/Both）；如未指定，先问
+
+**已录入清单**（设计师问"我录过哪些"时）：
+```bash
+ls "$R/data/style/"*-design-spec.json 2>/dev/null   # 列所有 spec
+```
+对每个文件读 `requirement`/`platform`/`source` 字段汇总给设计师，让他知道哪些录过、哪端录了。
+
+## Step 0: 确认平台
+
+跟 /wl-prd-full 一样，先问：Web 管理端 / APP 移动端 / 两端都要？
+**问了就停，等设计师回答。**
+
+## Step 1: 收集设计信息
+
+设计师用以下任一方式提供设计信息（按精度从高到低排）：
+
+**方式 A（最推荐）：蓝湖链接直读**
+
+设计师发蓝湖链接（`https://lanhuapp.com/web/#/item/...`），AI 用蓝湖 MCP 精确提取颜色/尺寸/字体/切图，比截图口述精确 10 倍。**走以下 4 步，每步失败就降级到方式 B（绝不报错、绝不阻塞）：**
+
+**A-1. 探测蓝湖可用性（失败就静默降级）**
+```
+调 mcp__lanhu__get_designs(url=<链接>)
+```
+- 返回设计图列表 → 继续 A-2
+- 报"连接失败"/工具不存在/418（cookie 失效）→ **立刻降级**：告诉用户"蓝湖没起/cookie 失效，改用截图口述"，然后走方式 B，**不许卡住**
+
+> 蓝湖是增强不是必需。没有蓝湖，工作流照样完整跑（方式 B/C/D 都不依赖蓝湖）。
+
+**A-2. 选设计图（图多时帮用户缩小范围）**
+```
+调 mcp__lanhu__get_designs(url=<链接>)  → 返回 {designs:[{name, width, height, ...}], sectors:[...], total_designs}
+```
+- **图少（≤15 张）**：直接列全部图名，问"录入哪张？"（**问了就停**）
+- **图多（>15 张）**：别一次倒几百张，先帮缩小：
+  1. 若有 `sectors`（分组）：先列分组名+图数，问"哪个分组？"，再列该组图
+  2. 没分组：问设计师"你要录的功能叫什么？"，按图名关键词过滤后列
+  3. 过滤掉明显占位名（如重复的"命名"），只列有意义的
+- 选定后记下图名，进 A-3。**可一次选多张**（`design_names` 支持数组）。
+
+**A-3. 读标注 + 切图**
+```
+调 mcp__lanhu__get_ai_analyze_design_result(url=<链接>, design_names=[<选中的图名>])
+  → 返回: HTML/CSS 标注 (rgba 值、width、padding、font...) + 还原指引
+调 mcp__lanhu__get_design_slices(url=<链接>, design_name=<图名>, include_metadata=true)
+  → 返回: {slices:[{name, size, download_url, svg_url, scale_urls:{1x,2x,3x}}]}
+```
+- CSS 标注 → 填 `design_tokens`/`layout`/`components`
+- **切图**：每个 slice 的 `svg_url` 是设计师切的**真实图标矢量**。挑出图标类（size 小、name 含"图标/icon/箭头"等），
+  填进 spec.json 的 `icons` 字段（见 Step 2）。这是原型图标的最佳真源（优于 ref-icon.json 通用图标）。
+返回的 CSS 标注是**设计稿的权威真值**，优先级高于代码风格、高于 PDF 规范。
+
+**A-4. AI 语义映射进 spec.json（关键：落到实处）**
+蓝湖返回的是一堆 CSS 属性，AI 读懂后**语义判断**填进 spec.json 各字段：
+
+| 蓝湖返回 | 填进 spec.json 哪里 | 怎么判断 |
+|---------|-------------------|---------|
+| 出现最多的背景色/按钮色 (如 `rgba(255,115,10,1)`) | `design_tokens["--primary-color"]` | 统计频率，按钮/导航反复用的色 = 主色 |
+| 容器 width (如 `200px`) | `design_tokens["--sidebar-width"]` | web 端左侧固定宽容器 = 侧边栏 |
+| 行高 padding font-size | `design_tokens["--table-row-height"]` 等 | 表格行的 height |
+| 布局结构 | `layout.description` / `layout.sidebar` | 看是左+右(web) 还是单列(app) |
+| 卡片/表格/表单/按钮组 | `components[]` | 按视觉块列 |
+
+**铁律：CSS 值原样填，禁止改格式。** `rgba(255,115,10,1)` 不要写成 `#FF730A`，`200px` 不要四舍五入。蓝湖给什么就填什么（这是设计稿的真值，AI 改了就不准了）。
+
+> 蓝湖 MCP 是 STDIO 模式：开 QoderWork 自动起、关自动停，**无需手动 start**。
+> cookie 按角色隔离在 `workspace/members/{当前用户}/.secrets/lanhu.env`（不进 git）——
+> wrapper（lanhu_stdio_wrapper.py）读当前 `.developer` 角色的 cookie 拉起服务，UI 角色有改稿权限、PM/开发只读。
+> 没配的话跑 `python "$R/.qoder/scripts/setup_lanhu.py"`；换角色改 `.developer` + 配新角色 cookie 后重启 QoderWork。
+
+**方式 B：截图 + 口述**
+设计师发一张 Figma/Axure 截图，口述关键设计决策：
+- "主色用 #1677ff，背景用 #f5f5f5"
+- "侧边栏宽 200px，一级菜单点击展开二级"
+- "表格行高 48px，斑马纹"
+
+**方式 C：导出标注**
+设计师从 Figma 导出 CSS / 标注 PDF / tokens JSON，AI 直接读。
+
+**方式 D：参照现有系统页面改**
+设计师说"类似 XX 页面，但侧边栏改成手风琴式"——AI 读那个页面代码，提取基础 spec，再叠加设计师的改动。
+
+## Step 2: 生成 spec.json
+
+把设计信息结构化成 spec.json，格式对齐 `data/index/vben-style-reference.json`：
+
+```json
+{
+  "source": "Figma (设计师: {designer})",
+  "imported_at": "2026-06-16",
+  "platform": "web",
+  "requirement": "{需求名}",
+  "design_tokens": {
+    "--primary-color": "#1677ff",
+    "--bg-color": "#f5f5f5",
+    "--sidebar-width": "200px",
+    "--table-row-height": "48px"
+  },
+  "layout": {
+    "description": "左侧侧边栏 + 右侧内容区；一级菜单点击展开二级手风琴",
+    "sidebar": "width: 200px, collapsible, accordion mode",
+    "content": "padding: 16px, background: #f5f5f5"
+  },
+  "components": [
+    {"name": "侧边栏菜单", "spec": "三级折叠，一级固定，二级手风琴展开"},
+    {"name": "数据表格", "spec": "VxeGrid 风格，行高 48px，斑马纹"}
+  ],
+  "notes": "设计师强调：侧边栏必须有图标，不能用纯文字",
+  "icons": [
+    {"name": "返回箭头", "svg_url": "https://lanhu-oss-.../xxx.svg", "size": "7x14", "usage": "顶部返回按钮"},
+    {"name": "提交图标", "svg_url": "https://lanhu-oss-.../yyy.svg", "size": "20x20", "usage": "提交按钮"}
+  ],
+  "lanhu_source": {
+    "url": "https://lanhuapp.com/web/#/item/project/stage?pid=...",
+    "image_names": ["问题反馈-详情"],
+    "slice_count": 12,
+    "imported_at": "2026-06-18"
+  }
+}
+```
+
+> ⚠️ **`requirement` 字段是落地关键**：fill_prototype.py 靠它匹配关键词
+> （`load_design_spec` 扫描 `data/style/*-design-spec.json`，`requirement` 包含查询词就命中）。
+> 所以 `requirement` 必须跟未来 `/wl-design-draw` 的关键词一致（如"问题反馈""营业外合同"）。
+> 蓝湖来源时填 `source: "蓝湖直读 (设计师: XX)"`，截图口述填 `source: "Figma (设计师: XX)"`，
+> 下游 fill_prototype 不管来源只认值。
+> **`lanhu_source` 可选**：仅蓝湖来源时填，记录链接/图名/切图数，可追溯设计稿出处。
+
+## Step 3: 存储到知识图谱
+
+- 存到 `data/style/{需求名}-{平台}-design-spec.json`（平台 = web/app，避免同功能多端冲突）
+  - 例：`待办-web-design-spec.json`、`待办-app-design-spec.json`
+  - 同需求同平台重新录入 → 覆盖（更新）；不同平台 → 各自独立文件
+- **优先级声明**：这份 spec 的优先级 > 代码风格 > PDF 规范
+  （因为它是最新、最明确的设计决策）
+- **`requirement` 字段填法**（解决"设计师不知道 PM 搜什么词"）：
+  用**功能名 + 同义词**，别只填图名。如图名"设置-我的待办"，requirement 填 `"待办 我的待办 设置待办"`
+  （空格分隔多个可能的关键词），这样 PM 搜"待办"或"我的待办"都能命中。
+
+> 🎯 **落地链路（已验证通）**：spec.json 落盘后，下次 `/wl-design-draw <同关键词>` 时，
+> `fill_prototype.py` 的 `load_design_spec()` 会自动命中这份 spec（靠 `requirement` 字段匹配），
+> 把 `design_tokens` **原样注入**原型 HTML 的 `:root` CSS（最高优先级，覆盖模板默认色）。
+> 即：蓝湖读到的 `rgba(255,115,10,1)` 会真实出现在原型里，不是 AI 看一眼就忘。
+> 验证方法：看输出原型 `:root` 里有没有 `/* design-import spec tokens (优先级最高) */` 注释及下面的值。
+
+## Step 3.5: 录入埋点
+
+spec.json 落盘后埋点，供 /wl-status 统计设计录入活跃度：
+```bash
+python "$R/.qoder/scripts/learn.py" record design_import "{\"requirement\": \"<需求名>\", \"platform\": \"<web|app>\", \"source\": \"<蓝湖|截图|导出>\"}"
+```
+> 失败静默忽略。
+
+## Step 4: 确认与通知
+输出给设计师：
+```
+✅ 设计规范已录入: data/style/{需求名}-design-spec.json
+   - 平台: Web 管理端
+   - 来源: 蓝湖直读 (设计师: XX)  ← 或 截图口述
+   - 主色: rgba(255,115,10,1)
+   - 布局: 左侧边栏 200px + 手风琴二级菜单
+   - 组件: 侧边栏菜单、数据表格
+
+✅ 已自动接入原型链路：下次 PM/任何人用同一关键词出原型时，
+   fill_prototype.py 会自动发现并优先用这份 spec（优先级高于代码风格），
+   主色/侧边栏宽度/布局全部按你的设计来（design_tokens 注入原型 :root）。
+
+
+设计师可以随时说"录入设计稿"更新它。
+```
+
+## 铁律
+
+- **有蓝湖 MCP 时优先用它直读**：设计师发蓝湖链接，AI 调 `mcp__lanhu__*` 提取精确参数，
+  不要让设计师截图口述（截图口述是蓝湖不可用时的降级方案）
+- **绝不编造 token**：设计师没说的值，留空或标"待确认"，不要自己猜
+- **图标必须来自真源**：即使设计师用了 emoji 示意，录入时也要替换成系统真源
+  （Web: data/index/ref-icon.json 的 Ant Design SVG）
+- **spec 一旦录入，同需求 prototype 必须锚定它**：AI 出原型前先查 data/style/ 有没有 spec
+
+## 🆕 录入前可参考知识图谱新数据
+
+设计师录入 spec 前，可以先问 AI 系统现状，让 spec 更贴合系统：
+
+- **"这个功能模块现在有哪些页面？"** → AI 调 `mcp__qoder-knowledge-graph__feature_overview(feature='资产管理')`
+  返回该模块所有页面 + API + 按钮，设计师知道改哪些、加哪些
+- **"这个模块的业务流程是什么？"** → AI 调 `mcp__qoder-knowledge-graph__get_workflow(module='资产')`
+  返回操作链（查询→新增→审批→...），spec 里的交互流程跟系统一致
+- **"系统里这个模块的按钮都叫什么？"** → 看 DESIGN.md 的 "Real Button Texts" 段
+  或 entity-registry.json，spec 里的按钮文案跟系统统一
+- **"这个模块用的是什么布局模式？"** → 看 DESIGN.md 的 layout_fingerprint
+  spec 里的侧边栏宽度/布局模式跟系统一致（如 160px / mixed-nav）
+
+> 这些数据让设计师的 spec 不是"凭空设计"，而是"基于系统现状的增量改进"——
+> 录入的 spec 天然就跟系统风格一致，AI 出原型时不会打架。

package/templates/qoder/skills/design-import/figma-workflow.md

@@ -0,0 +1,81 @@
+# Figma 协作指南（设计师专用）
+
+> 工作流出的 HTML 原型 → Figma 精修 → 录回 spec.json 闭环
+
+## 为什么这条路可行
+
+工作流用 `fill_prototype.py` 出的 HTML 原型有以下特征，**非常适合 html.to.design 插件转换**：
+
+- CSS 用标准 CSS 变量（`:root { --primary: ... }`），插件能正确解析成 Figma Variables
+- 布局用 Flexbox/Grid，转换后图层结构清晰
+- 颜色是 Vben 真实 HSL token（不是 #1890ff），导入后直接是正确配色
+- 图标是内联 SVG（Ant Design），导入后是可编辑矢量
+
+## 完整流程（4 步）
+
+### Step 1: PM 出原型（工作流侧）
+
+PM 在 QoderWork 说"出个 XX 的原型"，工作流输出：
+
+```
+workspace/members/{pm}/drafts/prototype-{需求名}-web.html
+```
+
+设计师从 PM 那拿到这个 HTML 文件。
+
+### Step 2: 导入 Figma（设计师侧）
+
+1. 打开 Figma，新建一个 Frame
+2. 菜单：**Plugins → html.to.design**（by ‹div›RIOTS）
+   - 没装的话：Figma Community 搜 "html.to.design" 安装（免费）
+3. 插件面板里选 **File** 标签（不是 URL 标签）
+4. 把 HTML 文件**拖进拖放区**（或点选文件）
+5. 点 **Import**，等几秒
+
+**结果**：HTML 变成完全可编辑的 Figma 图层——每个元素是独立的 Frame/Text/Rectangle，颜色是正确的 Vben 配色。
+
+### Step 3: 设计师精修（Figma 侧）
+
+设计师在 Figma 里做只有人能做的精修：
+
+- 调间距/对齐（AI 的间距可能不精确）
+- 优化交互细节（hover 态、动画、过渡）
+- 换更合适的图标/插图
+- 调整信息层级和视觉重点
+- 加设计师特有的"手感"
+
+**注意**：颜色 token（`--primary` 等）尽量别改——它们是系统统一的，改了前端实现时会对不上。
+
+### Step 4: 录回工作流（闭环）
+
+设计师精修完，在 QoderWork 里说：
+
+> "录入设计稿"
+
+工作流把 Figma 最终稿的关键决策（布局/配色/组件）录成 `data/style/{需求名}-design-spec.json`。
+
+从此：
+- 下次同需求出原型，工作流**优先用这份 spec**
+- 前端拿到的 HTML 原型**匹配设计师的 Figma 终稿**
+- 设计师的劳动成果**沉淀进知识图谱**，不浪费
+
+## 常见问题
+
+**Q: 导入后图层太碎怎么办？**
+A: html.to.design 会按 HTML DOM 结构生成图层。fill_prototype 出的 HTML 结构已经很干净（侧边栏/搜索栏/表格各自独立），不会太碎。如果某个区域图层太多，选中后用 Figma 的 "Flatten" 合并。
+
+**Q: 表格数据是假的怎么办？**
+A: 对的，原型里的表格行是示例数据（"XX示例1"）。这是故意的——原型验证的是布局和交互，不是数据。真实数据前端会从 API 取。
+
+**Q: 图标导入后变位图了？**
+A: 不会。工作流用的图标是内联 SVG（不是图片标签），html.to.design 会保留为矢量。如果个别图标显示异常，从 `data/index/icon-reference.json` 找原始 SVG 手动替换。
+
+**Q: APP 端原型也能导入吗？**
+A: 能。`prototype-{需求名}-app.html` 同样是标准 HTML，导入方式一样。APP 原型用的是 Vant 风格（移动端组件库）。
+
+## html.to.design 插件安装
+
+- Figma Community 搜索：`html.to.design`
+- 或直接访问：https://www.figma.com/community/plugin/1159123024924461424
+- 免费版每次导入有限制，团队版无限
+- 也有 Chrome 扩展版（适合截取在线页面）

package/templates/qoder/skills/design-review/SKILL.md

@@ -1,25 +1,82 @@
----
-name: design-review
-description: "评审设计交付物的完整性。Review design artifacts for completeness. 用户说'评审设计''设计稿看一下''检查交互稿'时触发。"
-trigger: "user invokes /review design, asks to check design, or designer submits design artifacts"
----
-
-# Design Review Skill
-
-## ⚙️ 自取上下文（Quest / QoderWork 无 hook 注入，必须自读）
-
-- `.qoder/.developer` — 当前评审人
-- 设计文件路径由用户指定，或扫 `workspace/members/{dev}/drafts/prototype-*.html`
-
-## 检查项 (Checklist)
-- [ ] 组件规格完整（components.json）
-- [ ] 交互流程覆盖所有状态（interaction-flow.md）
-- [ ] 技术约束已标注
-- [ ] 响应式/设计 Token 已定义
-- [ ] 符合 PRD 需求
-- [ ] **图标来自真源（data/index/icon-reference.json），无 emoji**（硬性）
-- [ ] 颜色来自真源（Web: vben-style-reference.json；APP: Vant 变量）
-
-## 输出
-
-报告：PASS 或 列出需修复的问题清单
+---
+name: design-review
+description: "评审设计交付物的完整性。Review design artifacts for completeness. 用户说'评审设计''设计稿看一下''检查交互稿'时触发。"
+trigger: "user invokes /review design, asks to check design, or designer submits design artifacts"
+---
+
+
+## 🔧 仓库根定位（QoderWork 桌面端 vs Qoder IDE/CLI）
+
+**后续脚本里的 `$R` 代表仓库根**，先确定它（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
+```bash
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+```
+> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。找不到时先跑 `python .qoder/scripts/install_qoderwork.py`。
+
+# Design Review Skill（设计师 + PM 都可用）
+
+> 🚫 **边界铁律：蓝湖工具（`mcp__lanhu__*`）只能在本 skill（即 `/wl-design-spec 评审`）内部调用。**
+> 用户直接说"用蓝湖对比一下"而没走评审命令时，引导到 `/wl-design-spec 评审`。非侵入式，不裸调。
+
+## ⚙️ 自取上下文（Quest / QoderWork 无 hook 注入，必须自读）
+
+- `.qoder/.developer` — 当前评审人
+- 设计文件路径由用户指定，或扫 `workspace/members/{dev}/drafts/prototype-*.html`
+- 若 `data/style/{需求名}-design-spec.json` 存在，作为评审基准（优先级最高）
+
+## 两种评审模式
+
+### 模式 A：评审 AI 原型（设计师审 AI 的活）
+
+设计师在 QoderWork 说"评审原型"，AI 拉出 `drafts/prototype-*.html`：
+
+1. 逐项检查（见下方 Checklist）
+2. **对照设计师 spec**：若 data/style/ 有 spec.json，检查原型是否匹配
+3. 输出问题清单（按严重度排序），设计师确认后 PM 说"修订原型"
+
+### 模式 B：评审设计师交付（PM 审设计师的活）
+
+PM 说"评审设计稿"，AI 检查设计师的 spec.json 或原型：
+
+1. 是否跟系统现有风格一致（对照 vben-style-reference.json / Vant 变量）
+2. 图标/颜色是否来自真源
+3. 是否覆盖 PRD 的所有界面需求
+
+## 检查项 (Checklist)
+
+- [ ] 组件规格完整（components.json 或 spec.json）
+- [ ] 交互流程覆盖所有状态（interaction-flow.md）
+- [ ] 技术约束已标注
+- [ ] 响应式/设计 Token 已定义
+- [ ] 符合 PRD 需求
+- [ ] **图标来自真源（data/index/ref-icon.json），无 emoji**（硬性）
+- [ ] 颜色来自真源（Web: ref-vben-style.json；APP: Vant 变量）
+- [ ] **若设计师 spec 存在：原型是否匹配 spec 的布局/配色/组件**（硬性）
+- [ ] 侧边栏/导航/表格/表单等关键区域是否跟系统其他页面一致
+- [ ] **🆕 按钮文案是否用了系统真实文案**（对照 DESIGN.md 的 "Real Button Texts" 段或 entity-registry，别用编的"新增/编辑"）
+- [ ] **🆕 布局是否跟同功能模块的标杆页面一致**（对照 DESIGN.md 的 "Feature Modules" 段）
+- [ ] **🆕 侧边栏宽度是否 = layout_fingerprint 的值**（fywl-ui 是 160px，不是 200px）
+- [ ] **🆕 若 spec 有 `lanhu_source`：原型配色是否忠于蓝湖原图**（调 `mcp__lanhu__get_ai_analyze_design_result` 拉蓝湖 CSS，逐项比原型 `:root` 的值是否一致；不一致=还原度问题）
+- [ ] **🆕 若 spec 有 `icons`：原型图标是否用了蓝湖切图**（别退回 emoji 或通用图标）
+
+**评审时可调 MCP 工具辅助：**
+- `mcp__qoder-knowledge-graph__feature_overview(feature='XX')` → 看这个功能模块的完整画像，对比原型是否遗漏页面/按钮
+- `mcp__qoder-knowledge-graph__get_design_system(platform='web')` → 拿到真实 token/按钮文案/模块标杆做对照
+- **`mcp__qoder-knowledge-graph__get_workflow(module='XX')`** → 查业务操作链（查询→新增→审批→...），检查原型是否覆盖了完整交互流程（而不只是静态页面）
+- **`mcp__coverage_matrix()`** → 查这个功能有没有测试覆盖，如果原型要改的页面有测试，提醒"改动后需回归测试"
+- **`mcp__lanhu__get_ai_analyze_design_result`** → spec 有 lanhu_source 时，拉蓝湖原图 CSS 做还原度比对（蓝湖不可用则跳过此项，不阻塞）
+
+## 输出
+
+报告：PASS 或 列出需修复的问题清单（按 🔴严重/🟡建议 分级）。
+
+## 埋点（评审完成后 AI 必须做）
+
+评审输出报告后，**立即调用 learning 引擎记录本次评审**（让团队学习哪些设计问题最常见）：
+
+```bash
+python "$R/.qoder/scripts/learn.py" record review_done "{\"target\":\"{被评审的原型或spec}\",\"result\":\"PASS或问题数\",\"issues\":[\"严重问题1\",\"建议1\"]}"
+```
+
+> 埋点失败不阻塞评审。数据进个人 journal，管理员聚合到 kg.duckdb 后，可统计"最常出现的设计问题"，反哺 design-import 防再犯。
+若不通过，附上修复建议和参考文件路径，PM 确认后 AI 修订原型。