@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/wlkj.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+wlkj.py - 工作流顶层调度器 (统一入口, 兼容旧调用)
+
+v3.0 引入: 把分散的脚本调用收敛到一个入口, 提供"逻辑分组"体验,
+而不需要物理分子目录 (避免 170+ 处路径改写 + 40 处 sys.path 风险)。
+
+用法 (与旧 python .qoder/scripts/xxx.py 等价):
+    python .qoder/scripts/wlkj.py kg search 保险 --platform web
+    python .qoder/scripts/wlkj.py task list
+    python .qoder/scripts/wlkj.py doctor --fix
+    python .qoder/scripts/wlkj.py search 考勤
+    python .qoder/scripts/wlkj.py status
+
+分组 (逻辑导航, 非物理目录):
+    kg/*      知识图谱 (kg.py 的子命令直接透传)
+    task      任务系统
+    search    代码搜索
+    doctor    环境体检
+    status    项目状态
+    sync      团队同步
+    ...
+
+设计:
+  - 透明转发: 不改变任何子脚本的行为, 只是把 argv 转过去
+  - 兼容: 旧的 `python .qoder/scripts/kg.py` 仍可用 (脚本都还在原位)
+  - 零维护: 加新命令只需在 DISPATCH 表加一行
+"""
+
+import os
+import subprocess
+import sys
+
+# 命令 → 脚本 映射 (加新命令只需在此加一行)
+# v3.0: 脚本已分子目录, 路径更新为 子包/脚本
+DISPATCH = {
+    'kg': 'kg/kg.py',
+    'task': 'task/task.py',
+    'sync': 'task/team_sync.py',
+    'team-sync': 'task/team_sync.py',
+    'git-sync': 'task/git_sync.py',
+    'search': 'kg/search_index.py',
+    'context': 'kg/context_pack.py',
+    'prefetch': 'kg/prefetch.py',
+    'status': 'report/status.py',
+    'report': 'report/report.py',
+    'doctor': 'setup/init_doctor.py',
+    'init': 'setup/setup.py',
+    'test': 'test/autotest.py',
+    'autotest': 'test/autotest.py',
+    'eval': 'report/eval_prd.py',
+    'eva': 'report/eval_prd.py',
+    'export': 'report/export.py',
+    'style': 'kg/build_style_index.py',
+    'role': 'report/role.py',
+}
+
+
+def _usage():
+    lines = [
+        'wlkj.py — 工作流顶层调度器',
+        '',
+        '用法: python .qoder/scripts/wlkj.py <命令> [参数...]',
+        '',
+        '命令分组 (转发到对应脚本):',
+        '  知识图谱:  kg <子命令>          (kg.py, 13+ 能力)',
+        '  任务:      task <子命令>        (task.py, create/list/start/finish)',
+        '  同步:      sync pull|push       (team_sync.py)',
+        '  搜索:      search <词>          (search_index.py)',
+        '  上下文:    context <词>         (context_pack.py)',
+        '  体检:      doctor [--fix]       (init_doctor.py)',
+        '  状态:      status               (status.py)',
+        '  报告:      report daily|weekly  (report.py)',
+        '  测试:      test <子命令>        (autotest.py)',
+        '  评估:      eval <prd.md>        (eval_prd.py)',
+        '  导出:      export <格式>        (export.py)',
+        '',
+        '示例:',
+        '  wlkj.py kg search 保险 --platform web',
+        '  wlkj.py task create "登录优化"',
+        '  wlkj.py doctor --fix',
+        '',
+        '注: 旧的 python .qoder/scripts/kg.py 形式仍可用 (脚本在原位)。',
+    ]
+    return '\n'.join(lines)
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ('-h', '--help', 'help'):
+        print(_usage())
+        return 0
+
+    cmd = argv[0]
+    rest = argv[1:]
+
+    script = DISPATCH.get(cmd)
+    if not script:
+        # 未知命令: 提示 + 退出
+        sys.stderr.write('未知命令: %s\n' % cmd)
+        sys.stderr.write('可用命令: %s\n' % ', '.join(sorted(DISPATCH.keys())))
+        return 1
+
+    script_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), script)
+    if not os.path.isfile(script_path):
+        sys.stderr.write('脚本不存在: %s\n' % script_path)
+        return 1
+
+    # 透明转发: 用当前 python 跑目标脚本, 透传所有参数和 exit code
+    r = subprocess.run([sys.executable, script_path] + rest)
+    return r.returncode
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/templates/qoder/settings.json

@@ -39,15 +39,6 @@
           }
         ]
       }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "command": "python .qoder/hooks/inject-workflow-state.py || python3 .qoder/hooks/inject-workflow-state.py"
-          }
-        ]
-      }
     ]
   }
-}
+}

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

@@ -1,226 +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 出原型时不会打架。
+---
+name: design-import
+description: "把设计师的 Figma/Axure 设计稿录入工作流，生成设计规范 spec.json 并存入知识图谱。Import designer's Figma/Axure design into the pipeline as a style spec. "
+trigger: "user invokes /wl-* command explicitly"
+---
+
+
+## 🔧 仓库根定位（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/setup/install_qoderwork.py`。
+
+# Design Import Skill（设计师专用）
+
+> 🚫 **边界铁律：蓝湖工具（`mcp__lanhu__*`）只能在本 skill（即 `/wl-design 预览`）内部调用。**
+> 用户直接说"查蓝湖""读一下这个蓝湖链接"而没走录入命令时，**不要裸调蓝湖**——先确认意图，
+> 引导到 `/wl-design 预览 <蓝湖链接>`。工作流是非侵入式的，所有能力必须经命令/工序站触发，
+> 不能脱离流程裸调工具（否则不可控、不可审计）。
+
+把设计师在 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/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 预览` 的关键词一致（如"问题反馈""营业外合同"）。
+> 蓝湖来源时填 `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 预览 <同关键词>` 时，
+> `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/report/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 出原型时不会打架。