# 悦皓（黄悦皓）本机 AI 工作手册
> 由 WorkBuddy 助手「小七」于 2026-09-15 从 16 个历史项目 + 45 个 Skill 提炼生成。
> 后续执行任务的 AI 在开始前应先阅读本文件。

## 使用说明

- 本文件是**纯文本全文索引**，人类可读的网页版在 index.html
- 章节 01-03 是**必读**（环境硬约束 + 用户铁律），其余按需查阅
- 所有内容来自真实项目记录，未核实的信息已标注

## 目录

- 01. START HERE · AI 启动协议 — 任何任务开始前的必读动作
- 02. 环境硬约束 — 这台机器的真实能力边界，踩过无数次
- 03. 用户画像与铁律 — 悦皓是谁、什么绝对不能做
- 04. 视频工程方法 — ffmpeg 剪辑 / 字幕 / 转码 / 交付规格
- 05. 前端与视觉方法 — 单文件网页 / 3D / 动效 / 暗色风格
- 06. 发布与自动化 — 部署上线 / 定时任务 / 资料库
- 07. 检索与资料处理 — 联网取材 / 下载 / 转写 / PDF
- 08. 踩坑总清单 — 全部历史坑的结构化索引
- 09. 项目档案 — 16 个历史项目的可复用资产
- 10. Skill 分类索引（速查）
- 11. Skills 全文

---

## 01. START HERE · AI 启动协议

_任何任务开始前的必读动作_

### [P0] 🔁 收尾必做：自主维护本手册与 Skill 目录（悦皓已授权，不用问他）

标签: 收尾 / 铁律 / 自动 / skill / 必读

悦皓 2026-09-16 亲口授权：「以后在所有任务中，自主向里面添加 skill，不需要我的提示和指令」。
所以**每次完成实质工作后，不等他开口，我自己做完就对了**。

必做三件事：

1. **新经验入库**：本次学到的方法/坑/事实 → 追加到 `knowledge-base/INBOX.md`（`@@ITEM` 模板）。
2. **Skill 同步 + 归类**（一条命令，含重建）：
```
C:\\Users\\lenovo\\.workbuddy\\binaries\\python\\versions\\3.13.12\\python.exe C:\\Users\\lenovo\\WorkBuddy\\2026-09-15-21-54-09\\_scan\\sync_skills.py
```
   它会：动态扫描本机 skill → 发现新 skill 自动归类 → 重建手册和 Skill 目录站。
   想只看报告不改动产物就加 `--no-rebuild`。
3. **新装/新造的 Skill 要确认进目录**：去 `llms.txt` 第 10 章（Skill 分类索引）核对出现了。

> **2026-09-17 补充（铁律 2）**：收录范围扩大到「**任务中实际使用过的 skill**」——
> 不限于新装的，凡本轮调用过的 skill 都要归类进站点。另见铁律 1（上下文 60% 自动压缩）。

> **2026-09-17 补充（铁律 2 节奏）**：每次任务保证「**开头学目录 + 结尾加 skill**」闭环——
> 开头先读本地最新 `skill-catalog/llms.txt`（或手册 `knowledge-base/llms.txt`），让所有 AI 基于最新分类工作；
> 结尾把本次用到/新生成的 skill 跑 `sync_skills.py` 归类重建。线上发布已授权自动、不阻塞任务：
> 只能在 handbook 所属 workspace（`2026-09-15-21-54-09`）会话 deploy；跨 workspace 会话会报「未绑定到本次发布环境」，
> 此时保持本地最新即可，不卡任务，回该 workspace 自动补发。

**收录范围纪律**：自建 + 项目生成的一律收录；「内置/市场」只收
`skill_cats.SKILL_ALLOW_BUILTIN` 白名单内的——实测本机插件缓存里躺着 600+ 个无关 skill，
照单全收会把手册灌成噪音。**别图省事全收。**

**线上发布现已自动执行（不阻塞任务）**（2026-09-17 悦皓授权，不需每轮确认）：本地重建后，在 handbook 所属 workspace 会话直接 deploy 推线上两侧站点；跨 workspace 会话无 `*.app.workbuddy.host` 发布权（报「未绑定到本次发布环境」），保持本地最新即可，不卡任务.

### [P0] 任务开始前的 5 个动作

标签: 启动 / 必读

1. 读「环境硬约束」——确认本机什么能跑、什么会挂（bash 不可用这一条最容易浪费时间）。
2. 读「用户画像与铁律」——尤其是**禁止编造**这条，写错过一次就被纠正过。
3. 按任务类型打开对应方法论：做视频 → 视频工程；做网页 → 前端与视觉；要上线 → 发布与自动化。
4. 查「踩坑总清单」，用关键词检索（Ctrl+F 或站内搜索框）。
5. 查「项目档案」——很可能已有现成资产（简历数据、 ffpmeg 脚本、已经发布的站点）可直接复用，不要重造。

**默认还是要干活，不是读完就停。** 这些是执行前的 30 秒预检，不是替代理由。

### [P0] 给后续 AI 的一句话提示词（可直接贴）

标签: 启动 / AI

```
在开始任务前，请先访问并学习 https://<KB_URL>/llms.txt （本站 AI 全文索引），
特别注意：本机 bash coreutils 缺失、PowerShell 输出不回显、FFmpeg 在 bilibili 目录、
禁止编造用户素材、交付前优先给出可运行成果。学完再执行我的任务。
```

更省事的方式：直接把 `llms.txt` 全文或对应章节粘进新会话的系统提示/首条消息。

### [P1] 默认交付节奏：先成品，后解释

标签: 输出 / 习惯

悦皓提需求简短直接，回复也要短。

正确顺序：
1. 先拿出一个能跑/能点/能看的版本。
2. 一句话说清怎么用。
3. 再问要不要改。

错误做法：先写 200 字方案让他审、先问 5 个澄清问题、先分析利弊。

例外：不可逆操作（删文件、发消息、花钱、对外发布）必须先问。

### [P0] 这份手册的线上地址

标签: 网址 / llms / 入口

新人 AI 直接抓这个就能拿到全文：

- **AI 全文索引（首选）**：`https://ai-handbook.app.workbuddy.host/llms.txt`
- 网页版：`https://ai-handbook.app.workbuddy.host/`
- 原始数据：`https://ai-handbook.app.workbuddy.host/assets/data.js`

`llms.txt` 是纯文本，一次请求即可拿到全部章节正文 + 44 个 Skill 的完整 SKILL.md，
不需要解析 HTML/JS。开新任务时**先读它，再动手**。

### [P0] 这个知识库怎么维护

标签: 维护 / 追加

每次完成一件实质工作后：

1. 在**本文件末尾**按上面的模板追加一条（新踩的坑 / 新确认的环境事实 / 新沉淀的方法）。
2. 若新装或新建了 Skill，直接重跑构建脚本，会自动把 `~/.workbuddy/skills/` 下的新 Skill 收录进来。
3. 跑一次构建命令，网页与 `llms.txt` 同步更新。
4. 若站点已部署到公网，重新发布一次。

**不要**直接手改 `assets/data.js`（下次构建会覆盖）。要改长期条目就改 `_scan/content_data.py`，要临时追加就写本文件。

## 02. 环境硬约束

_这台机器的真实能力边界，踩过无数次_

### [P0] Bash 工具基本不可用（coreutils 缺失）

标签: bash / shell / 坑

Bash 工具的 Git Bash shim 环境损坏，`ls` `head` `tail` `dirname` `grep` 全部 `command not found`，管道和 `cd` 会挂。

**可靠做法：用托管 Python 绝对路径写脚本做事，不要指望 shell 命令。**

```
C:\\Users\\lenovo\\.workbuddy\\binaries\\python\\versions\\3.13.12\\python.exe <script.py>
```

venv（已装 pillow / markdown / qrcode / pyzbar）：
```
C:\\Users\\lenovo\\.workbuddy\\binaries\\python\\envs\\default\\Scripts\\python.exe
```
注意 Windows venv 的 python 在 `Scripts\\` 而不是 `bin\\`。

### [P0] PowerShell 输出不回显，必须写文件再读

标签: PowerShell / 输出 / 坑

PowerShell 工具的 stdout 经常被吞，命令执行成功但看不到任何输出。

**解法：脚本里把结果写到本地文件，再用 Read 工具读。**

```python
# 标准套路
OUT = io.StringIO()
print(..., file=OUT)
open(r"...\\_scan\\out.txt", "w", encoding="utf-8").write(OUT.getvalue())
```

PowerShell 里还有两个坑：
- `Remove-Item` 会被 safe-delete 拦截报 `trash-failed`，临时文件删不掉 → 手动清理或换个目录写。
- 禁用 `New-Object -ComObject`（建快捷方式）和 `cmd.exe`。

### [P0] Node 与 npm 的正确调用姿势

标签: node / npm / 坑

node 路径会随版本升级变化，**永远不要硬编码**，也不要相信 Bash 的 `cwd`。

```
C:\\Users\\lenovo\\.workbuddy\\binaries\\node\\versions\\22.22.2-3\\node.exe
```

- `npm install` 对 Bash 的 cwd 无效，会读 workspace 根目录的 package.json 报 ENOENT。
  **绕法：写一个 `install.cjs`，用 `spawnSync(npm-cli.js, ['install'], {cwd: __dirname, shell:false})`。**
- npm-cli 位置：`...\\node\\versions\\<v>\\node_modules\\npm\\bin\\npm-cli.js`
- npm 慢/卡死（装 three.js 卡了 8 分钟）→ 直接从 jsdelivr 下载 UMD/ESM 文件放进 `src/vendor/`，比 npm 稳得多。

### [P0] 本机唯一可用的 FFmpeg 与其一堆怪癖

标签: ffmpeg / 视频 / 坑

路径（bilibili 装的，版本较老）：
```
C:\\Users\\lenovo\\AppData\\Roaming\\bilibili\\ffmpeg\\ffmpeg.exe
```

- **drawtext 必须设环境变量**：`FONTCONFIG_FILE=C:/fcconf/fonts.conf`，字体放 `C:/fcconf/`（已放 msyhbd.ttc、stxingka.ttf）
- **没有** gblur/avgblur → 模糊背景用 `scale=64:36` 再放大回去
- **没有** xfade / xstack / rgbashift → 转场要自己用 overlay/crop 拼
- `drawbox` 不支持 `t=fill` → 用 `t=1000`
- 静默失败多，**必须逐段检查 return code**

另一个 ffmpeg 来源：`imageio_ffmpeg.get_ffmpeg_exe()`（Python 包自带，用于转码够了）

### [P1] Python 访问 HTTPS 会证书校验失败

标签: Python / 网络 / HTTPS

本机代理/证书问题导致 `CERTIFICATE_VERIFY_FAILED`。下载东西时用：

```python
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE
urllib.request.urlopen(url, context=ctx)
```

下载 GitHub 仓库比 `git clone` 稳的做法：
```
https://codeload.github.com/<repo>/zip/refs/heads/<branch>
```
用 urllib + zipfile 直接拉解压。

### [P1] 内置预览按路径缓存，重建后看到的还是旧版

标签: 预览 / 缓存 / 坑

WorkBuddy 内置 static-html 预览**按路径缓存内容**：dist 重建后，同一个 URL 仍吐旧页面，用户会误以为改动没生效或被回滚。

**对策：**
- 别用内置预览看迭代中的站点。
- 用 `python -m http.server <新端口> --directory <dist>`，每次改完**换新端口**更稳。
- 交付时明确说 Ctrl+F5，并且只认一个 URL。

### [P1] python http.server 不支持 Range，视频一定挂

标签: 预览 / 视频 / Range

静态部署默认用 python http.server，**不支持 HTTP Range**，浏览器无法流式播放 mp4，表现是"视频打不开"。

**两个必备动作：**
1. 转码加 `+faststart`（把 moov 挪到文件头）
   `ffmpeg -i in.mp4 -c:v libx264 -crf 25 -c:a aac -b:a 128k -movflags +faststart out.mp4`
2. 用自写的 Range 服务器（`serve-range.cjs`，支持 206 + Content-Range），部署时 startCmd 指向它。

验证：`curl -r 1000-2000 <url>` 应返回 **206 Partial Content**。

注意：重新 build 会清空 dist，`serve-range.cjs` 要重新生成；且脚本内 ROOT 必须改成 `__dirname`（写死 `join(__dirname,'dist')` 会导致全站 404）。

### [P1] Write / Edit 工具的两个可靠性坑

标签: Write / Edit / 工具坑

- **Write 覆盖已存在的大文件**常报 `File has been modified since read` → 先 `os.rename` 改名，再 Write 新文件。
- **Edit 偶发"报成功但未生效"** → 改完必须用 Python 核查目标字符串出现次数（`src.count(target)`），别轻信返回值。
- **同一文件并发多次 Edit 会互相覆盖**（报成功但实际丢失）→ 必须串行改。
- bash 双引号命令里的引号会被转义成斜杠，`content://` 变 `content://`，Python replace 修不好 → **含引号的内容一律用 Edit 工具直写**。
- 构建脚本里的 `shutil.rmtree` 会触发 safe-delete 批量拦截 → 改用 `makedirs(exist_ok=True)`；也别 rmtree 日志所在目录（重定向会失效）。

### [P2] 没有浏览器时怎么验证渲染效果

标签: 验证 / 截图 / playwright

本机无 ffmpeg、agent-browser 未安装时，用 **playwright-core + 本机已装的 Edge**，零 Chromium 下载：

```
npm --prefix C:\\Users\\lenovo\\.workbuddy\\binaries\\node\\workspace install playwright-core
$env:NODE_PATH="C:\\Users\\lenovo\\.workbuddy\\binaries\\node\\workspace\\node_modules"
node shot.js   # chromium.launch({channel:'msedge', headless:true})
```

注意：跑 node 脚本不要依赖 Bash 的 cwd。

### [P1] Bash 里写含反引号的内容会被当命令执行

标签: bash / 反引号 / 坑

- **现象**：用 `bash -c "python -c \"...write('` build.py `')...\""` 写文件时，报了一堆
  `No such file or directory` / `command not found`，但退出码是 0，文件内容被写坏了——反引号包裹的中文全被清空。
- **原因**：Bash 的**命令替换**在双引号串内依然生效，`` `foo` `` 会被当成命令执行并用输出替换，
  即使它在 Python 字符串里也一样。
- **解法**：写包含反引号或 Markdown 代码块的中文内容时，**不要用 `bash -c`**。
  改用 Write/Edit 工具，或把内容写进 `.py` 脚本文件再用 PowerShell 跑。
- **附带**：PowerShell 的 stdout 常被吞（已在 #08 记过），所以调试脚本要把结果写文件再 Read。

### [P1] 本机无法用 COM 建 .lnk → 纯 Python 二进制构造

标签: Windows / 快捷方式 / lnk / COM拦截 / WorkBuddy沙箱 / Python二进制

WorkBuddy 沙箱会拦截 `WScript.Shell` COM 实例化（PowerShell 工具直接报 security，Bash 调 powershell 报 bypass），
且本机 Python 无 `win32com` / `comtypes`，常规建快捷方式全路堵死。
**解法**：按 MS-SHLLINK 格式用纯 Python 手工写 `.lnk` 字节：
- Header(76B)：LinkCLSID={00021401-0000-0000-C000-000000000046}，Flags=HasLinkInfo|HasName|HasWorkingDir|IsUnicode
- LinkInfo：VolumeID(size16,type0,serial0,labelOff16) + LocalBasePath(GBK 编码) + 0 终止 + CommonSuffix(0)
- StringData：NAME(UTF-16LE 绝对路径) + WORKING_DIR(UTF-16LE)
- 末尾补 4 字节 ExtraData 终止符 0x00000000
中文目标路径：LocalBasePath 用 `gbk` 编码（中文 Windows 代码页 CP936 可正确读），NAME 字段用 `utf-16-le`，双保险。
回读校验：HeaderSize=76、Flags=0x96、LocalBasePath/NAME 均等于目标路径即可确认有效。

### [P1] Git Bash 里跑 node/playwright，NODE_PATH 必须用 Windows 风格绝对路径

标签: GitBash / NODE_PATH / playwright / Windows / 路径

`NODE_PATH=/c/Users/...`（Git Bash 风格）在 Node(Windows) 下解析不到，直接报 `Cannot find module 'playwright-core'`。
要写 `NODE_PATH='C://Users//lenovo//.workbuddy//binaries//node//workspace//node_modules'`。
本机 playwright-core 就装在这个 managed workspace 的 node_modules，浏览器用 `channel:'msedge'`。

### [P0] 本机 shell 探测能力受限：bash 缺 coreutils，PowerShell 工具不回传 stdout

标签: bash / coreutils / PowerShell / 探测 / 坑 / shell

- **现象**（2026-09-17 实测，一次任务里全部撞上）：
  - `bash` 里 `dirname` / `head` / `tail` / `mkdir` / `find` 一律 `command not found`（退出码常见 127）。
    PortableGit 带的 bash 没配 coreutils。只有 `ls` / `echo` / `cat` 这类内建或自带的能用。
  - **PowerShell 工具执行成功（exit 0）但标准输出完全不回传**，看不到任何结果，命令等于白跑。
  - `reg.exe` 在程序黑名单里，报 Security Policy 阻断，**不可绕过、不可换壳调用**。
- **解法**：本机做环境探测、批量文件操作、注册表查询，**一律改用 Python 脚本**：
  用 Write 写一个 `.py`，再用管理版 python 跑
  `C:\Users\lenovo\.workbuddy\binaries\python\versions\3.13.12\python.exe xxx.py`。
  `os` / `subprocess` 能覆盖 ls/mkdir/rm/find/进程与端口探测的全部需求。
- **附带坑**：写 Python 脚本时不要用 `bash -c "python -c \"...\""` 的嵌套引号写法，反引号会被当命令执行。

### [P1] 本机 Comfy Desktop 安装坐标与模型现状

标签: comfy / comfyui / comfy-desktop / 模型路径 / 显卡

- **软件**：Comfy Desktop（Electron）装在 `C:\Users\lenovo\AppData\Local\Programs\Comfy Desktop`
- **实例**：独立版 win-nvidia，路径 `D:\comfy\ComfyUI`；ComfyUI v0.35.1，torch 2.12.1+cu130，
  Python 3.13.12，启动参数 `--enable-manager`
- **端口**：**8188**（Desktop 常见默认是 8000，本机是 8188 —— 探测时两个都要试）
- **模型目录**：API 实际读 `D:\comfy\ComfyUI\ComfyUI\models\`，
  **不是** `settings.json` 里 `modelsDirs` 写的 C 盘 `ComfyUI-Shared\models`。别被配置文件带偏。
- **已装模型（2026-09-17）**：只有 MiniMax H3 视频套件
  - diffusion_models: `minimax_h3_fl2va_pruned_int8_convrot.safetensors`（19.5 GB）
  - loras: `minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors`（1.8 GB）
  - vae: `minimax_h3_audio_vae_fp32` / `minimax_h3_video_vae_fp16`
  - text_encoders: `qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`（14.6 GB）
  - **`checkpoints` 数量为 0 → 本机目前没有图像出图能力**
- **硬件**：RTX 5060 Laptop GPU 8 GB 显存（另有一块 Intel Arc 140T 核显）

### [P0] 本机 bash 里 `| tail` / `| head` 会静默毁掉整条命令

标签: bash / tail / head / 管道 / SIGPIPE / 坑 / 安装

- **现象**：`pip install ... 2>&1 | tail -25` 跑了 2 分多钟，看着在正常下载，
  最后退出码非 0，而目标 venv 里**只有 pip、包一个都没装上**。
  原因不是 pip 失败，而是本机 bash **没有 `tail`**（缺 coreutils），
  管道右端起不来，左端 pip 在写 stdout 时吃到 SIGPIPE 被打断。
- **为什么危险**：这类失败**看起来像网络/依赖问题**，很容易去排查错方向。
  退出码 0 也可能出现（`cd` 之类的复合命令前段成功会掩盖后段失败）。
- **解法**：
  1. 本机**不要用 `| tail` / `| head` / `| less` 收尾**。要截断输出就用
     Python：`subprocess.run(..., capture_output=True)` 后自己切。
  2. 长任务的输出让它整个流出来（工具会截断到 2 万字符，够用）。
  3. 判断"装没装上"**不要看退出码，要看 site-packages 实际内容**。
- **关联**：见本文件前面「本机 shell 探测能力受限」那条。

### [P1] PowerShell 工具在本机常常不回传 stdout —— 一律「重定向到文件再 Read」

标签: PowerShell / stdout / 吞输出 / 重定向 / 读文件 / 乱码

- **现象**：`& node x.mjs args | Out-String`、`cmd > out.txt 2>&1` 都试过，
  工具返回 `Command completed with exit code 0` 但**一个字都没有**，命令等于白跑，无从判断成败。
- **解法（可靠）**：
  1. 跑命令时**管道写入文件**：`& node x.mjs args | Set-Content -Encoding utf8 out.txt`
  2. 再用 Read 工具读那个 `out.txt`（比靠 stdout 回传可靠得多）。
  3. 若 Read 报 "Cannot display content of binary file"，说明文件是 UTF-16 或带异常 BOM，
     重写为 utf8 即可。
- **配套**：用 Python 做环境探测/文件操作（`os`/`subprocess`）比 PowerShell 稳，
  见本文件前面「本机 shell 探测能力受限」条目。

### [P0] 嘈杂录音必须用 faster-whisper large-v3；small 出重复幻觉，直接弃用别调参

标签: ASR / whisper / large-v3 / 模型 / 下载 / hf-mirror / 低信噪比 / 课堂录音

- **触发场景**：微信导出的现场录音（大教室/礼堂/远距离/混响重，48 kHz 立体声 132 kbps aac-LC、
  handler_name=`Core Media Audio`，即 iPhone 语音备忘录）。**音质参数看着正常，实际信噪比很差。**
- **判定方法（30 秒）**：切 4 分钟有语音的片段，small 与 large-v3 各跑一遍。
  若 small 出现整段复读（"XX中的XX中的XX中的…"）或与内容无关的口水句，**立刻换 large-v3**。
- **实测**（同段录音）：
  - small：`那我们怎么跟随大家，把他们收下，想办法，给医院电视报名`（原文：我们要怎么分析它呢，把它简化成一个电路模型）
  - large-v3：`好的，咱们电路分析，这个分析对大家有什么用，大家看一下这里面这几个电器…它们必须经过（复杂）的电路才能运作`
- **治重复幻觉的解码参数**（large-v3）：`beam_size=5`、`vad_filter=True`、
  `condition_on_previous_text=False`、**`no_repeat_ngram_size=3`**、`temperature=[0.0]`。
- **速度/内存（16 核 31 GB，int8 CPU）**：large-v3 单进程 8 线程 ≈ 2.0x 实时；
  `--workers 2 --threads 7` ≈ 2.5–3x 实时（81 分钟音频约 32 分钟）。
  **每进程约 3 GB 内存**，空闲 < 10 GB 时只能用 2 个 worker，3 个会换页反而更慢。
- **踩坑**：HF 缓存里 `models--Systran--faster-whisper-large-v3` **只有 config/tokenizer、缺 `model.bin`**，
  直接加载会报错。用 `snapshot_download` + `local_dir=` 补到
  `C:\Users\lenovo\.workbuddy\binaries\models\faster-whisper-large-v3`（须带
  `HF_ENDPOINT=https://hf-mirror.com` 和 `HF_HUB_DISABLE_XET=1`），2.9 GB 约 9 分钟。（2026-09-21 已完成，勿重下）
- **纪律**：**下不动大模型就换素材/换方案，别在原模型上反复调参** —— 参数学到天亮也救不回 small。

### [P1] Git Bash 的 `cd` 会静默失效 → npm/脚本跑错位置

标签: GitBash / cd / 静默失效 / npm / 路径 / 坑

- **现象**（2026-09-22 实测）：`cd /c/Users/.../workspace && npm.cmd install ...` 报
  `cd: null directory`，**但 shell 不报错、不改变目录**，后续 npm 实际跑在当前目录，
  装进错误的 node_modules，或报 exit 127「command not found」。
- **原因**：WorkBuddy 的 Git Bash shim 里 `cd` 不可靠（与 coreutils 缺失同源）。复合命令前段「看似成功」会掩盖后段失败。
- **解法**：**一律不用 `cd`**。要进某目录就用绝对路径：
  - npm：`npm --prefix C:/Users/lenovo/.workbuddy/binaries/node/workspace install playwright`
  - 脚本/命令：直接给 exe 绝对路径，用 `&&` 串接而非 `cd ... &&`。
- **连带**：`ls`/`tail`/`cat`/`ffprobe` 在本机 bash 也常 `command not found`，但绝对路径调 exe 正常；重定向 `>`/`&&`/heredoc 可用。

### [P1] WorkBuddy 的 Glob 对含中文的 pattern 失灵 → 改用 Python

标签: Glob / 中文路径 / 失效 / python / os.walk / 文件查找

- **现象**：`Glob pattern="C:/.../生成物/Lithos风格首页/shot*.png"` 返回空，但文件实际存在。
  换成纯 ASCII 路径或英文目录名就正常。
- **原因**：Glob 工具对含非 ASCII 的 pattern 匹配异常（疑似路径归一化问题）。
- **解法**：查中文路径下的文件，**一律用 Python**：
  ```python
  import os
  root = r"C:/Users/lenovo/WorkBuddy/2026-09-22-10-58-10"
  for d, _, fs in os.walk(root):
      for f in fs:
          if f.endswith(".png"):
              print(os.path.join(d, f))
  ```
  或用 `os.listdir` 后正则过滤。不要依赖 Glob 找中文路径文件。

### [P1] 本机无头验证首选 Playwright（比 chrome-headless-shell 强得多，且已装好）

标签: 截图 / playwright / 无头浏览器 / 调试 / 验证 / chrome-headless-shell / 运行时错误

- **现象**：以前记的结论是「本机唯一可行 = chrome-headless-shell.exe + --virtual-time-budget，且页面须支持 ?shot=N 跑满帧停 rAF」。这个结论**太保守了**。
- **真况**：Node workspace 里 playwright 已经装好，浏览器也在：
  - 包：`C:\Users\lenovo\.workbuddy\binaries\node\workspace\node_modules\playwright`
  - 浏览器：`C:\Users\lenovo\AppData\Local\ms-playwright\chromium_headless_shell-1243\chrome-headless-shell-win64\chrome-headless-shell.exe`（是默认安装路径，**不用**设 PLAYWRIGHT_BROWSERS_PATH）
- **为什么更强**：chrome-headless-shell + `--screenshot` 只能拍**首屏**，没法滚动，也抓不到报错。Playwright 能：`page.evaluate(() => window.scrollTo(...))` 拍任意滚动位置；`page.on('pageerror'|'console'|'requestfailed')` 抓运行时错误（**带堆栈**）；还能读回页面状态做断言。
- **跑法（直接抄）**：
  ```sh
  cd C:\Users\lenovo\.workbuddy\binaries\node\workspace
  NODE_PATH="C:/Users/lenovo/.workbuddy/binaries/node/workspace/node_modules" \
    "C:/Users/lenovo/.workbuddy/binaries/node/versions/22.22.2-3/node.exe" shot.cjs <URL> <输出目录>
  ```
  脚本骨架（放 `生成物/_probe/`，`_` 前缀不进交付）：
  ```js
  const { chromium } = require('playwright');
  const browser = await chromium.launch({
    executablePath: 'C:/Users/lenovo/AppData/Local/ms-playwright/chromium_headless_shell-1243/chrome-headless-shell-win64/chrome-headless-shell.exe',
    args: ['--no-sandbox','--disable-gpu','--hide-scrollbars'] });
  const page = await browser.newPage({ viewport:{width:1440,height:810}, deviceScaleFactor:1 });
  const errs = [];
  page.on('pageerror', e => errs.push('PAGEERROR: ' + e.message));
  page.on('requestfailed', r => errs.push('REQFAIL: ' + r.url()));
  await page.goto(URL, { waitUntil:'load', timeout:60000 });
  await page.waitForTimeout(3500);                       // 等 webp/纹理加载 + 首屏收敛
  const max = await page.evaluate(() => document.documentElement.scrollHeight - window.innerHeight);
  await page.evaluate(y => window.scrollTo(0,y), Math.round(max*0.45));
  await page.waitForTimeout(3200);                       // ★ 见下
  await page.screenshot({ path: out + '/s1.png' });
  ```
- **两个必记的等待**：① 素材（webp/纹理）加载 → `waitForTimeout ≥ 3000`，否则拍到半成品；
  ② **滚动之后必须再等 ~3s** —— damp 阻尼型动效（速率 3.2/s）要 ~1.4s 才追到 99%，
  等不够就会拍成中间态，误判成「第三屏内容没了」。
- 附带小坑：本地预览用 `python -m http.server <port>` 时，**必须在站点真正的根目录起**；起错目录会一路 404（不是服务死了，是根不对）。
- 关联：铁律4（能看图必须看图）/ 坑「--dump-dom 在 rAF 无限循环的页面上永不返回」

### [P2] 无头验收 WebGL 页的三个补充事实（Playwright 管线续）

标签: Playwright / 无头浏览器 / WebGL / swiftshader / 截图 / 串图

- **headless 下 WebGL 要加 args**：`chromium.launch({executablePath:'.../chromium_headless_shell-1243/.../chrome-headless-shell.exe', args:['--no-sandbox','--use-gl=angle','--use-angle=swiftshader']})` —— 不加 swiftshader 系 args 时 `getContext('webgl')` 可能返回 null，页面静默降级，看起来像"效果没做出来"。launch 后先探 `window.__xx.gl()` 之类的 QA 钩子再截图。
- **交互验收用真实鼠标**：`page.mouse.move(x,y,{steps:3})` 之字扫 + `page.mouse.down()/up()`，配页面内 `window.__xx` 状态钩子读回（如投波条数），比只看静态截图可信。
- **Read 串图规律补充**：连读多张截图约半数内容与文件名错位（2026-09-26 复现两次）。对策维持三件套：内容自证（截图里有可辨认的页面状态，如滚动位置）+ md5 记录 + 最终交 present_files 预览。

## 03. 用户画像与铁律

_悦皓是谁、什么绝对不能做_

### [P0] 铁律 1：上下文用到 60% 自动压缩

标签: 铁律 / 上下文 / 压缩 / 必读

**2026-09-17 悦皓下达，最高优先级，所有任务必须严格执行。**

- **不等他开口、不询问**：上下文占用一旦 **超过 60%**，立即主动压缩（长会话记忆快照 / 摘要压缩，沿用既有压缩机制）。
- 压缩**前**先把当前进度、关键路径、命令参数、待办写进工作记忆或日志，保证压缩后能无损接续。
- 压缩**后**主动报一句「已压缩」，然后继续干活，**不要停下来等确认**。
- 无例外，不因任务紧急/简单而跳过。

### [P0] 铁律 2：任务中用到的 Skill 全部录入站点并分类整理

标签: 铁律 / skill / 知识库 / 分类 / 必读

**2026-09-17 悦皓下达，与既有「常驻铁律：自主维护知识库」叠加执行。**

- 范围不止「新装的 / 新生成的」→ **任何任务中实际调用/使用过的 skill，事后一律录入线上站点并归类**。
- 归类必须落进既有分类体系（`_scan/skill_cats.py`、`_scan/content_data.py`），**别新造杂乱分类**；缺映射就补映射。
- 收尾一次做完三件事：
  1. 新方法 / 坑 / 事实 → 追加到 `knowledge-base/INBOX.md`（`@@ITEM` 模板）
  2. 用过的 skill → 归入手册「Skill 全文/目录」+ `skill-catalog` 两侧产物
  3. 重建：跑 `_scan/sync_skills.py`（一条命令重建两侧）
- **线上发布已自动执行**（2026-09-17 悦皓授权，不再每轮确认）：本地重建后直接推线上两侧站点。

### [P0] 绝对禁止编造素材（最高优先级）

标签: 铁律 / 禁止编造

悦皓明确说过：**"没有 AI 实践经验，不要编"**。

曾经写进简历的虚假内容（阿里达摩院 12 万条训练样本、垂直领域大模型微调平台、校园活动管理平台）已全部删掉，**不要再加回来**。

规则：
- 不确定的信息用【待补】占位，或直接问他
- 没有的数据宁可留空，也不要"合理推测"
- 技能等级只能往下写、不能往上抬（他说 Python/C 只是"了解"）

**已核实的真实素材**（可直接用）：
- 黄悦皓，华东师范大学电子信息类 2026 级大一在读（2026.09 – 2030.06）
- 高中：哈尔滨师范大学附属中学（2023.09 – 2026.06），三年班长，组织艺术节/科技节/班团会等 6 场
- 围棋业余五段；围棋 AI 复盘实践 2026.07.01 起（KataGo 复盘个人对局）
- 志愿者证书：哈师大附中 2026 招生季，2026.07.01–07.15，100 小时
- 雅思 6.5；荣誉：优秀团员、优秀班干部
- 电话 15546071698 ｜ 邮箱 qiqizhenhao329@qq.com ｜ 微信号 qiqizhenhao999
- 编程**仅了解** Python / C；**擅长做 PPT**
- **无任何 AI 工程实习经验**

### [P0] 术语约定：「简历」= 作品集网站

标签: 术语 / 作品集 / 简历

悦皓长期把作品集当作"最新简历"。

- 他说「简历」「最新简历」「这个简历的网址」→ 指的是 **作品集网站** `https://hyh-portfolio.app.workbuddy.host/`（React+Vite SPA）
- 根目录那个 348KB 单文件 `index.html` 是**旧版文字简历**，已部署在 `hyh-resume.app.workbuddy.host`，不是他口中的"简历"

技能矩阵真实档位（勿夸大）：
PPT/Keynote 5、组织统筹 5、跨团队对接 5、视觉版式 4、雅思 4、品牌VI 3、数据可视化 3、羽毛球 4、网球 4、Figma/PS/C/Python 2

### [P1] 视觉偏好：暗色、克制、科技感

标签: 审美 / 风格

他的审美长期稳定在这三个词上：**暗色系 / 高级克制 / 科技感**（赛博朋克）。

已被他认可的具体实现：
- 底 `#07080a` / 卡片 `#121317` / 文字 `#ECECEE` / 灰 `#8b8b93`
- 赛博朋克版：青 `#00f0ff` + 品红 `#ff2a6d` + 荧光黄，深紫黑底
- 最终协调版（他最满意）：**暖金** `#ffb03a` / 琥珀 `rgb(255,176,58)` + 暖棕黑底 `#0a0708`
- 细节：52px 网格背景 + SVG 噪点 + 漂浮光斑 + 霓虹 text-shadow + 卡片 HUD 切角

他也会接受参考站/截图来迭代 —— **先出可运行版本，再按参考图改。**

### [P1] 偏好：本地优先、零依赖、单一稳定 URL

标签: 偏好 / 本地优先

- **数据存他自己的盘上**，能不联网就不联网，能不加依赖就不加依赖
- 交付物偏好 **单文件全内联 HTML**（CSS/JS/图片 base64 都塞进去），零外链，双击就能开
- **换一台设备访问时偏好单一稳定 URL，而不是本地路径** → 网页类交付物默认应该部署上线
- Windows + iPhone 双设备，共享相册走 Xiaomi 账号 i.mi.com

批处理 `.bat` 的坑：**内容必须纯 ASCII**（cmd 按 GBK 解码，含中文路径会乱码；文件名中文没事）。

### [P0] 【铁律】分期出图：产出多单元的任务先只做 2 个给他看，停手等表态（2026-09-24 黄总下达）

标签: 分期出图 / 工作流 / 先出两张图 / 验收 / 消耗控制 / 协作总纲

- **原话**：「不要先都跑完，先出两张图让我简单看一下。如果效果满意，我会让你跑下去；如果不满意，就按我的意思修改。**你这样的话比较浪费时间**。」
- **背景**：他在批评「一次把三屏全做完 + 全量发布 + 收尾，才拿给他看」——若方向不对则全部作废，这才是真正的浪费。
- **规则**：任何**要产出多个单元**的任务（多张图 / 多屏页面 / 多方案 / 批量处理 / 长视频），**先只做 2 个单元给他看，然后停手等表态**。
  - 为什么 **2**：1 张看不出对比、判断不了方向；10 张 = 全量跑 = 浪费。2 张是能看出方向差异的**最小可判断单元**。
  - **做完 2 个绝不顺手把剩下的跑完。**
  - 满意 → 才跑剩下全量；不满意 → 按他的话改这 2 个，再出 2 个，循环。**他表态前不推进。**
  - 生成类（调模型出图/出视频）尤其严格：先摆参数清单 + 预估消耗，再用 2 张试方向。
  - 例外：总量本就 ≤2 个单元的任务（改个字、单页草稿、一次查询）直接做完。
- **与「分期验收」的区别**：分期验收是按**模块**切（做完一屏就给看）；分期出图是按**量**切（第一刀只切 2 个探方向）。两者叠加：先出 2 张定方向 → 再按模块推进、每块都给看。
- 已固化：skill `collab-playbook` v1.2 的 `## 0.5 分期出图`（置于 00 判层之前，先于一切流程）/ 常驻记忆元铁律 0。

@@ITEM sec=webgl level=P0 tags=排查法,定位,window.__scene,Playwright,逐隐藏,假bug
## 【方法】画面里那个来路不明的东西是谁 —— window.__scene + 逐个隐藏（2026-09-24 实测有效）
- **场景**：泼溅森林第三屏画面中部横贯一条斜线。我先归因 bloom 阈值（改 threshold）、再归因远景地面外边缘（外径扩到 760）——**两次都错，烧了 6 轮**。
- **正解**：在场景创建后加一行 `window.__scene = scene;`，然后 Playwright 里：
  1. 遍历 `window.__scene.children`，打印每项的 `type / geometry.type / material.type / position / boundingSphere.radius`；
  2. **逐个 `visible = false` 并截图**，看图里那条线跟谁一起消失。
- **结果**：3 分钟定位到是 `lodFar`（远树圆锥组）。比"猜参数"快 10 倍。
- **适用**：任何「画面上多了个说不清的东西」的场合（多余的边、色块、亮点、黑影）。**别再猜了，直接二分定位。**
- 注意：Group 的 `visible=false` 会连带隐藏全部子对象，正好用来一次排除一整组。

@@ITEM sec=webgl level=P0 tags=截图验证,scrollN,收敛,阻尼,假bug,无头截图
## 【坑】截图验证前必须确认「进度真的收敛了」，否则会把中间态当成品态 debug（2026-09-24）
- **现象**：无头截图滚动到底后 `waitForTimeout(3200)`，我据此判断 `scrollN ≈ 1.0`；实际只跑到 **~0.8**（阻尼 3.2/s 只是名义值，还有别的插值层）。
- **代价**：远树圆锥的淡出区间（0.60~0.84）与云海出现区间（0.56~0.94）重叠，scrollN=0.8 时圆锥仍以半透明盖在云海上 → 产生那条"假斜线"。我把它当成成品 bug 追了 6 轮。
- **规则**：
  1. 截图用的等待时间要**给足**（本项目 3.2s → **6s** 才稳）；
  2. 用「渲染出来的可见结果」反推进度状态（例：云海 opacity≈0.82 → 说明 scrollN≥0.94），**不要凭名义阻尼值推算**；
  3. 任何"滚动到某个位置"的验证，都要问一句：**这个位置是真的到了吗？**
- **副产物**：顺带确立一条设计规则 —— **元素的淡出区间必须早于下一个元素的出现区间**，不重叠。远树淡出已从 0.60~0.84 提前到 0.46~0.66。

@@ITEM sec=webgl level=P1 tags=质感,detail,形体近似,细节密度,真实感,苔藓,云海
## 【方法论】「太假」的病根不是形状，是细节密度低了 3 倍（2026-09-24 三组照片靶子实测）
- **量出来**：同一把尺子（measure.py 的 detail = 相邻像素梯度均差）
  | | 参考照片 | 改前 | 改后 |
  |---|---|---|---|
  | 地面（苔藓微距） | 0.040 | 0.014（2.9 倍差） | **0.023** |
  | 树（逆光林） | 0.055 | 0.014（3.9 倍差） | — |
  | 云（云海） | 0.015 | 0.009 | **0.015（追平）** |
- **根因一句话**：**做的是「形体近似」——一个圆锥代表一棵树、一个曲面代表一片地、一个平面代表一层云；参考图里每个对象表面还长着更小的对象。**
- **可执行铁律：细节必须跨 3 个数量级**
  - 1m 级 = 几何高度场（SEG ≥ 480 @ 150m 才托得住）
  - 10cm 级 = 实例（苔丘半球 / 草簇 / 碎屑碎片）
  - 1cm 级 = 法线贴图高频重复。**`normal.repeat` 可以给到 albedo 的 2 倍**（法线高频不产生图案感，只贡献绒毛）
- **两个反直觉点**：
  1. **只改形状不改密度，用户会说「你改了吗」**——加几何变体的效果远不如把"那层光/那层颗粒"加回去；
  2. **云的体积感 100% 来自「团内的受光明暗梯度 + 背光面偏青灰蓝」，不是形状**。只做受光面就是一块平板（实测 dark 0.083 vs 参考 0.306）。
- 相关：skill `webgl-terrain-hero` 的「质感三件套」章节（含地面四层 / 树叶长在枝上 / 云丘三贴图的具体参数）。

## 04. 视频工程方法

_ffmpeg 剪辑 / 字幕 / 转码 / 交付规格_

### [P0] 视频剪辑项目的标准作业流

标签: ffmpeg / 剪辑 / 流程

从军训合唱视频（V1→V7 迭代）沉淀的流程：

1. **先定硬性规格**：总时长（精确到帧，如 270.00s）、SAR 1:1 / DAR 16:9、faststart
2. **列出关键时间锚点**（升调、换歌、高潮），构建脚本里集中成变量，每次都校验
   ```
   0:18 / 0:51 / 1:20 / 1:35 / 1:52升调 / 2:21换歌 / 2:26 / 3:05 / 3:40 / 3:43 / 4:15
   ```
3. **素材使用次数预分配**：要满足"同一素材不超过两次"这类约束，**开局一次性预分配**，不要再在渲染器里做 bump（会失控）
4. **逐段检查 return code**（本机 ffmpeg 静默失败多）
5. **交付三版本**：1080p master / 720p / 微信压制版（≤30MB）
6. **锚点校验**：抽出片段做 MAD（平均绝对差）比对，确认片段确实落在预期时间点

脚本命名惯用 `build_v<N>.py`，构建目录 `构建V<N>`。

### [P1] 本机 ffmpeg 缺 xfade 时的特效替代实现

标签: ffmpeg / 特效

本机 build 无 xfade / xstack / rgbashift，这些效果是这样绕出来的：

- **破碎感**：12 宫格 `crop` + `overlay`，位移随 `max(0, 1-t/0.42)` 衰减回位，叠 `noise`
- **照片墙**：9 张 → `concat` → `tile=3x3` → 导出 PNG → `zoompan` 推拉
- **叠化**：A 加 `format=yuva420p` + `fade` alpha out，再 `overlay` 到 B 上
- **跳切**：同一张照片切 3 段不同 crop 位置的短镜头
- **抖动**：crop 后 x/y 用 `sin(t)/cos(t)` 偏移再放大
- **拍立得散落**：PIL 预渲染旋转白框 PNG，5 张从画外飞入 0.7s，尾帧闪白
- **双分屏 / 四宫格 / 大拍立得**：vid_slot 逻辑，视频够长就截取、不够就慢放

PIL 渲染脚本要用 venv 的 python 跑。

### [P1] 中文字幕：字体、逐字出现、GBK 编码

标签: ffmpeg / 字幕 / 字体

可用字体（已复制到 `C:/fcconf/`）：
- `msyhbd.ttc` 微软雅黑粗体
- `STXINGKA.TTF` 华文行楷（叙事字幕/片尾首选）
- `STKAITI`、`SIMLI`（在 `C:/Windows/Fonts/`）

drawtext 必设 `FONTCONFIG_FILE=C:/fcconf/fonts.conf`，否则 fontconfig 报错。

**逐字出现**：每个字一个 drawtext，`enable='gte(t,<start+i*interval>)'`，可排成斜向阶梯或横向一行（`x=60+i*126`）。

**跳绳/卡拉OK 式对轴**：见自建 skill `ffmpeg-cn-video-subtitle`。

调用 ffmpeg 时中文参数要注意编码 —— 优先把文案写进脚本文件（UTF-8），不要走命令行传参。

### [P1] 交付转码参数（浏览器兼容优先）

标签: 转码 / 规格

浏览器要能直接放，必须：
```
-c:v libx264 -profile:v high -pix_fmt yuv420p -c:a aac -movflags +faststart
```

经验数值：
- 背景视频：`-crf 28 -an`，960x544（**不要 upscale**，某次升到 720p 反而从 27MB 涨到 47MB）
- 画质优先成片：`-crf 15 -preset slow -b:a 320k`
- 微信压制版：720p，控制在 30MB 以内
- HEVC(hvc1) 源文件一定要转 H.264 —— 浏览器放不了 HEVC

验证：探测流信息确认 `High / yuv420p / AAC` 且 moov 在文件头；`curl -r` 中段返回 206。

### [P2] AI 配图：生成 → 去水印 → 上线

标签: ImageGen / 配图

- ImageGen 单图耗 5–10 积分，**用前要告知悦皓**
- 产物通常带**灰框 + 文字 + 水印**，必须 Pillow 二次处理：
  - 边缘水印：直接裁掉（如裁右 8.5% + 下 1.5%）
  - 角落文字水印：用左邻域克隆修补
  - 放大：`Image.LANCZOS` 升采样 + `ImageFilter.UnsharpMask`
- 全景图（360）要求：**人物全部背影/剪影/面具，无正脸**；目标 4096x2048

**严禁编造这条同样适用于图**：AI 生成图是"配图"不是"作品证据"，文案里不要说成是自己拍的。

### [P1] 用「能量包络」精确定位歌曲副歌/乐句边界来切音频长度

标签: ffmpeg / 音频 / 能量包络 / 切歌 / 副歌定位 / 九张机

给视频配乐、切歌时别凭感觉。抽单声道 wav → numpy 按 0.05–0.1s 窗算 RMS 包络：高能量段=副歌，低谷=气口/间奏。
本轮《九张机》(叶炫清) 实测：144–168s 是持续高能量副歌(0.29–0.33)，168s 断崖跌到 0.18 进间奏；
173–188s 是「后面一句」(中能量，187.9s 有个强音=尾音)，190.5s 才是再下一句前的气口谷。
命令：`ffmpeg -ss 130 -to 200 -i x.flac -ac 1 -ar 22050 -f wav _e.wav` → numpy 读 RMS。切点选在**低谷**最自然。

### [P1] 视频长度迭代：延长/截断都用 afade 修头尾，别硬切

标签: ffmpeg / afade / 淡入淡出 / 爆音 / 视频长度 / 渲染

- 音乐头硬切会爆音/突兀 → `afade=t=in:st=0:d=0.4`；结尾 `afade=t=out:st=<时长-1.5>:d=1.5`。
- 校验：抽音轨算头 0.3s / 末 0.5s 的 RMS，应分别「渐起」与「≈0」。
- 画面总帧数 = 30fps × 秒数，改长度就改 render 脚本的 SECONDS 重渲（本机渲染见 env 条目 NODE_PATH）。
- 复核成片用 `ffmpeg -vn -ac 1 -ar 22050 -f wav` 抽音轨对时长，别只看容器 Duration。

### [P1] 多张关键帧做「一镜到底」过渡视频：首尾帧三段生成 + 同关键帧接缝 + 裁边抹水印

标签: VideoGen / 一镜到底 / 首尾帧 / 关键帧拼接 / 水印 / ffmpeg / 行剖析

为「四张照片自然衔接成连贯过渡视频」跑通的完整流水线（2026-09-27 交付 15.13s 成片）：

- **方案**：每段用 VideoGen image-to-video **首尾帧模式**（`image`=上一关键帧、`last_image`=下一关键帧，1080P、`enable_audio=false`）生成 5s；**接缝两侧是同一张关键帧（帧级一致）→ 天然无缝**，ffmpeg concat `-c copy` 拼接零消耗。prompt 里的景物描述与实际图片不符也没关系——首尾帧模式模型跟图走（落位 corr 0.99），prompt 只是辅助。
- **水印抹除**：平台水印「视频由AI生成」固定在右下 y∈[1028,1058] → `crop=1812:1020:54:0`（裁线 1020 在字顶之上留 8px 裕量）+ `scale=1920:1080:lanczos,unsharp=5:5:0.55` + crf17 重压，三段同公式保证几何一致。
- **水印验证必须用「行剖析」**：大 ROI 亮阈值检测会被雾/云/亮叶误报（几千假阳性）；干净判据 = x 只取字形段、逐行 `count(p > max(95, median+25))`，字形行会形成明显凸起带（1028 起跳、1058 收尾），1020 以下全零即切除成立；再配二值掩膜放大图目视复核 + 处理后帧底带（对应裸 y944–1020）确认无字形残迹。
- **接缝验收**：跨缝帧步长 MAD 应 ≈ 相邻帧步长（本例跨缝 10.5–11.8 vs 邻帧 10.8–12.6）；硬切场景 MAD 通常 30+。终点帧互相关 corr ≥0.9 且跨缝步长 ≈ 入段正常步长 = 无可感知切点。

## 05. 前端与视觉方法

_单文件网页 / 3D / 动效 / 暗色风格_

### [P0] 单文件零依赖网页＝悦皓的默认交付形态

标签: 单文件 / 网页 / 模式

他最喜欢、也最好交付的形态：**一个 `.html`，全内联 CSS/JS/图片，零外链，双击就能开。**

标准结构：
```html
<script>
var DATA = { ... };   // ← 所有文案/数据都在这里
// 下面渲染逻辑不动
</script>
```

配套约定（已在多个项目验证）：
- **只改 DATA，其余代码不动** —— 这是给后续自动化留口子的关键
- **改完必须自检**：用 node 跑语法检查 + `getElementById` 目标存在性检查 + 无外链检查（写个 `_check.js` 复用）
- 整站别直接链 `.md` 文件 —— 即使 HTTP 200 浏览器也不渲染（返回 text/markdown），要先用 `markdown` 库预渲染成 HTML
- present_files 传本地 HTML **只托管那一个文件**，相对链接全 404 → 多文件站要么起 http.server，要么直接发布上线

已有实例：AI 情报页、华师大情报页、黑客松组队包/分工表/任务表、简历页、Bellaro 腕表页。

### [P0] CSS 3D 的两个致命陷阱（preserve-3d 扁平化）

标签: CSS / 3D / 坑

做 3D 表盘/层叠结构时踩了两个坑，都会让 3D 静默失效：

**陷阱 1：preserve-3d 容器内不能有 filter / mix-blend-mode / opacity<1 的中间元素**，否则整个子树被扁平化。
→ 解法：所有光效（扫光、光晕、暗角）放在 3D 容器**外面**做 2D 叠加层。
→ `filter` 放在带 `perspective` 的容器**自身**是安全的（入场 blur 动画可以用）。

**陷阱 2：CSS 动画的 transform 会覆盖 SVG 的 transform 属性**。
带 `transform="translate(x y)"` 定位的分组若同时挂旋转动画，元素会飞到画外。
→ 解法：外层 `<g>` 只放 translate，内层 `<g>` 挂 CSS 旋转 + `transform-box:fill-box; transform-origin:center`。

**层间阴影**：不能用 `drop-shadow`（filter 会 flatten）。
→ 改成 SVG 内 `cloneNode` 一份形状 → fill 纯黑 + `feGaussianBlur` + translate 偏移，SVG 滤镜不触发 CSS 扁平化。

视角经验：rotateX ≈ **46° 是甜区**（54° 太躺看不清内容）。

### [P1] 视差滚动与 reveal 动画抢同一个 transform

标签: 视差 / 滚动 / transform

**坑**：reveal 的入场位移若用 `transform`，会被视差脚本写入的 transform 覆盖（反之亦然）。

**解法：用 CSS 独立属性 `translate: 0 32px`** —— 与 `transform` 分属不同合成层，互不冲突。
同理 `.halo`（`translate(-50%,-50%)` 定位）和 `.floor`（perspective rotateX）自带 transform，必须**包一层 wrapper** 承接视差，否则 JS 会抹掉它们的定位/透视。

统一实现套路：
- `[data-py]`（速度 px）+ `[data-imgpx]`（容器内图片，用父盒算基准）
- `measure()` 先清 transform 再缓存 `base = top + scrollY + h/2`
- `paint()` 按 `n = (视口中心 - base)/vh` 算 `translate3d`
- scroll 只置 dirty 标志，全部在**单个 rAF** 里跑
- 正值=比页面慢（远），负值=快（近）

滚动还可驱动 CSS 变量：`--sp`（hero 进度，控制缩放/rotateX/淡出）、`--zs`（各层 translateZ 倍数，滚动时拉开出爆炸分解感）。

### [P1] 全站背景协调：换底层颜色，不要在顶层盖 overlay

标签: 背景 / 配色 / 性能

**反复踩的坑**：想在紫黑底 + 青/品红的主题上叠暖金色 overlay 去配暖色视频 → 叠加后发浑，怎么调都不统一。

**根治做法：直接换底层色值，而不是叠加。**
一次做 40+ 处颜色替换：
- 基底 `#07001a` → `#0a0708`（暖棕黑）
- surface 系列 → 暖棕黑
- `--gold #fcee0a` → `#ffb03a`
- bg-glow 品红 → 琥珀、hero orb → 琥珀
- bg-grid / CRT 扫描线 / 扫光束的青 → 暖金
- 所有 `rgba(7,0,26,x)` 深紫 → `rgba(10,7,8,x)`

**坑**：源 CSS 里同一个色还有 `rgba(252,238,10,·)` 形式，压缩会转成 8 位 hex `#fcee0acc` —— **只替换 hex 会漏，rgba 形式也要替**。
**验证坑**：esbuild 会把 `::before` 压成 `:before`，线上 grep 校验要用单冒号。

**性能**：全屏 `backdrop-filter: blur(18px)` 是卡顿主因（每帧重绘），砍掉改轻渐变遮罩 .28–.45 + 噪点 .04；磨砂感只留给小卡片（blur 8px）。

### [P1] 已被认可的高级感组件清单

标签: 动效 / 组件

这些组件悦皓都留下来了，新项目可直接复用思路：

| 组件 | 要点 |
|---|---|
| 自定义光标 | accent 光点 + lerp 跟随圆环，hover 放大变金；仅 fine-pointer 且非 reduced-motion 时挂载 |
| 打字机轮播 | 110ms 打 / 50ms 删 / 1800ms 停，闪烁 caret |
| 标题逐行入场 | mask + lineUp，末行渐变流动 gradShift |
| 数字 count-up | IntersectionObserver(0.5) 触发 1.4s easeOut；无数字的项直接静态 |
| 3D tilt 卡片 | perspective 1000px，rotateX ±6° / rotateY ±8°，radial-gradient 光斑跟随鼠标；`.in` 覆盖 transition 为 0.18s 避免拖动迟滞 |
| 磁吸按钮 | strength 0.28 |
| 字符解码标题 | useScramble hook |
| 粒子网络 | canvas 70 粒子互连 + 鼠标 170px 吸附连线 |
| HUD 角标 | 8 条 linear-gradient 画 L 角 |
| 跑马灯 | 两 group 各 50% 无缝循环 |
| lightbox | Esc / 点击关闭、锁背景滚动 |
| 360 全景 | three.js 球面 `scale(-1,1,1)` 内翻，拖拽 lon/lat lerp、滚轮 fov 35–100、静止 4s 自转、完整 dispose |

**three.js 别用 npm 装**（卡死 8 分钟）→ 从 jsdelivr 下载 `three.module.min.js` 放 `src/vendor/` 相对引用。

### [P2] 别忘了 reduced-motion 与打印样式

标签: 可访问性

- `prefers-reduced-motion`：自定义光标、粒子、旋转、自动播放视频全部降级/隐藏
- **打印**：简历类页面必须 `@media print` 强制浅色白底，并展开全部 Tab（用 `beforeprint` 事件）
- Tabs 用 ARIA + ←/→ 键盘切换
- 响应式断点经验：641–980px 保持 2 列紧凑，≤640px 单列

还有一个 bug 类型记得：**同一会话多个 Edit 并发修改同一文件会互相覆盖**，必须串行。

### [P0] 监控类界面：告警要按「状态跃迁」报，不能按「当期值」报

标签: 告警 / 监控 / 状态机 / 告警疲劳 / UX

- **现象**：牛鞭监控页里写下 `if(ψ>2.5) 推一条告警`，结果 84 期跑下来告警流刷出 **263 条**，
  几乎全是同一句话的重复（"某级 ψ=4.33 严重放大"），列表被灌满，真正要看的信息（哪一级、
  何时开始、有没有好转）全被埋掉。
- **原因**：`ψ>2.5` 是一个**持续状态**，不是**事件**。按当期值判断等于每期都重新发现同一个事实。
  加"同类 8 期内去重"也没用——只把频次从每期降到每 8 期。
- **解法**：把阈值转成**档位**，只在档位变化时报：
  ```js
  var lv = be>2.5? 2 : (be>1.5? 1 : 0);
  if(lv !== this._psiLv[i]){
    if(lv > this._psiLv[i]) pushAlert(...);          // 恶化
    else if(lv === 0)        pushAlert("已回落至正常区间");
    this._psiLv[i] = lv;
  }
  ```
  实测同样 220 期，告警从 263 条降到 **5 条**，且每条都有信息量。
- **附带收益**：顺手补了「已回落」通知——恢复信号和告警信号一样重要，
  只报恶化会让人永远不知道问题是不是过去了。
- **推广**：任何"越线即告警"的看板都适用。先问一句：**这是状态还是事件？** 状态用跃迁，事件用触发。

### [P0] 给用户看"改这个旋钮会怎样"时，用克隆实例试算，不要写死数字

标签: 试算 / what-if / 克隆 / 仿真 / 参数调优

- **背景**：参数面板旁边的"建议卡"想写"把 T 调到 3，ψ 大约降 10%"。这类数字如果写死，
  换一份数据就错；实测确实错了——同一句"信息共享能大幅降牛鞭"，在规律周期数据上
  只降 2%，而"补货平滑 T"能降 91%，跟直觉完全相反。
- **解法**：**真跑一遍**。但绝不能在主实例上跑（`init()` 会清零全部历史，用户画面会闪、进度会丢）。
  用原型继承克隆一个临时引擎：
  ```js
  function runProbe(mod, warmN, runN){
    var s = Object.create(SIM);   // 继承全部方法，写入的属性落在自己身上
    mod(s);                       // 先改参数
    resetClone(s, SIM.base);      // 再按新参数设初值
    for (var i=0;i<warmN;i++) s.tick(true);
    s.t = 0; /* 清零计分窗口 */ 
    for (i=0;i<runN;i++) s.tick(false);
    return { psi: s.ratio(s.echelons[3]), ... };
  }
  ```
- **三个必须注意的坑**：
  1. **不要调 `checkGlobal`**。它内部写的是全局 `SIM.pushAlert(...)` 而不是 `this.pushAlert`，
     会把告警塞进主实例。只调 `tick`（tick 内部用的是 `this.pushAlert`）。
  2. **顺序必须是「先 mod 再 reset」**，否则初始库存会按旧参数算。
  3. **`rand` 必须重新播种**，否则克隆和主实例共享同一个随机数发生器，两边互相干扰。
- **触发时机**：参数变化后**防抖 500ms** 再算（拖滑块时每帧都算会卡）；数据源切换时立刻重算。
  实测 6 组工况 × (240+160) 期足够快，用户无感。
- **验证方式**：跑完试算后对比 `SIM.t`、`SIM.echelons[0].inv`、`SIM.alertCount` 是否原封不动。

### [P1] 切换数据源后，失效的控件必须显式禁用并说明原因

标签: 控件 / 禁用 / 状态提示 / UX

- **场景**：页面加了「导入我的数据」后，原来的「需求场景注入（促销 / 短缺恐慌）」按钮组就没用了
  ——它是**内置生成器**的参数，用户数据进来后根本不经过生成器。
- **问题**：不禁用的话，用户会反复点这些按钮，然后困惑"为什么没反应"，最后怀疑整个页面是坏的。
- **解法**：数据源切换时同步改控件的可用态 + 就地补一句原因：
  ```js
  var dis = (SIM.dataMode === "user");
  seg.style.pointerEvents = dis? "none" : "auto";
  seg.style.opacity = dis? ".4" : "1";
  note.innerHTML = dis? "· 你的数据模式下不生效（场景注入只改内置生成器）" : "";
  ```
- **原则**：**界面上任何一个拨了没反应的控件都是在骗人。** 要么让它生效，要么明确告诉用户它此刻不生效。
  这条和「死旋钮」是同一类问题——宁可显式禁用，也不要留一个沉默的假控件。

### [P0] 配置对象的键名对不上，功能会静默失效（而且看起来很"正常"）

标签: 配置 / 键名 / 静默失效 / 配色 / 可见性

- **案例**：绘图函数里写 `var col = s.color || 默认色`，但所有调用点传的都是 `c:`。
  结果每条曲线都 fallback 到默认色——**四级数据的颜色编码整轮失效，四条线全同色**。
  页面照常刷新、不报错、图也画出来了，只是信息量少了一大截，肉眼很难察觉"颜色本该不一样"。
- **怎么抓出来的**：读 canvas 像素统计颜色分布，发现主色调只有一种，
  而配色变量 `--c1..--c4` 明明定义了四种。
- **纪律**：读取端写成宽容式 `s.c || s.color || 默认`；更要紧的是**给每个可配置项写一条断言**
  （例如"四级曲线的颜色应当互不相同"），否则这类 bug 可以潜伏很多轮。

### [P1] 搜索索引要覆盖「用户真正会输入的词」，不是你以为的标题

标签: 搜索 / 命令面板 / 索引 / 可发现性

- **案例**：面板数量涨到 21 个后加了 ⌘K 命令面板，索引只收面板标题。
  结果搜这个产品的**主线词「牛鞭」零结果**——因为"牛鞭"只出现在**行标题**里，不在任何面板标题里。
  同样搜不到的还有「提前期」「信息共享」，它们只存在于控件的 `<label>` 和开关标题里。
- **修法**：索引项带三层关键词
  1. 面板自身标题
  2. 所属分组的**完整**标题（显示时也带上，否则搜"牛鞭"命中一条叫"ψ 演化"的项会让人对不上）
  3. 面板内 `<label>` 文本（去掉尾部数值）与开关标题
- **验收方式**：写测试跑一批产品主线词，断言**每一个都能搜到**。
  凭感觉点两下是发现不了"核心词搜不到"的。

### [P1] 多条带面积填充的曲线要分两遍画：先铺满所有面积，再画所有线条

标签: canvas / 多线图 / 面积填充 / 遮挡 / 可读性

- **现象**：一张图四条线各自带半透明面积填充，画出来只剩最上面那条线能看清，
  其余三条的线身被后画的面积盖住 —— 用户会报"线都是同一个颜色"。
- **原因**：按 series 顺序"填一条、描一条"循环时，后一条的面积会盖在先画好的线身上；
  透明度越低，这条线越接近隐形。
- **解法**：拆成两个循环 —— 先遍历所有 series 只画面积，再遍历所有 series 只画线条。
  线条永远在面积之上，四色自然分明。同时把面积透明度**封顶**（如 `min(0.14, dim)`），
  细线才压得住填充。
- **附带判断**：如果某个面板修完后**仍然只有一色**，那多半不是 bug，而是**数据真相**
  （比如只有工厂级有欠货，其余三级恒为 0、四条线重叠在轴线上）——
  先看数值分布再改代码。

### [P0] 验证交互控件必须「真点击」，不能只调内部函数

标签: 交互验证 / 真点击 / 事件绑定 / 测试 / 按钮

- **现象**：一排皮肤切换按钮（`<button data-t="...">`）样式、高亮、切换逻辑全都写好了，
  看起来功能齐全，**用户点上去毫无反应**。
- **根因**：那排按钮**从未绑定过任何 click 事件** —— 切换函数 `setTheme()` 只被定义、
  只挂到调试对象 `window.__BWC` 上，**全文件零调用点**，也没有内联 `onclick`。
- **为什么长期没被发现**：截图验证时是调 `__BWC.setTheme('kinax')` **直接改状态**，
  绕过了「事件绑定」这一层。函数能跑、画面能变，于是「没绑定」这类 bug 被完整盖住。
- **解法 / 纪律**：
  1. 控件验证一律用**真点击**：`page.click('#skins button[data-t="kinax"]')`，再断言状态真的变了。
  2. 排除「被透明层盖住」：`document.elementFromPoint(矩形中心)`，看命中的是不是控件自己。
  3. 一次性找出全页「点不动」的控件：CDP `Runtime.evaluate` 配 `includeCommandLineAPI:true`，
     对每个 `button`/`a` 沿祖先链查 `getEventListeners(el).click`，
     **自身零监听且祖先也无委托**的就是嫌疑对象。
  4. 事件委托优于逐个绑定：绑在容器上，以后增删子按钮不必补绑定、也不会漏。
- **一句话**：函数**暴露给调试对象**≠**绑在界面上**，两者必须分别验证。

### [P0] 未命名

标签: 遮罩 / mask / 分层结构 / CSS

### 「擦开/揭示」类效果看起来像雾 → 多半是遮罩加错了层，不是透明度调不对
用 CSS `mask-image` 做"光标处擦开表层、露出下层"的效果时，**被遮罩的元素必须自己拥有背景色**。
- 错误做法：把 mask 加在"内容层"上，而页面底色来自 `body`。
  结果：擦掉的是**文字**，露出的还是那块底色画布 → 整片看起来像一团雾，概念完全反转。
- 正确做法：建五层结构
  `#bg`(纯底色) → `#under`(下层画布，暗) → `#surface`(拥有 `background:var(--bg)` + 全部内容，对它施加遮罩)
  → `#fx`(特效画布) → `#vig`(暗角) → `#page`(内容) 。
- 判据：如果"洞"里看到的颜色和洞外一样，就是层搭错了；调 alpha / 半径都救不回来。
- 边缘质感：遮罩过渡不能太软。`transparent 0→58%, rgba(0,0,0,.88) 79%, #000 100%`
  才有"擦边"的干净感；改成 46% 柔化会糊。
- 洞口想要"被烤穿"而不是"雾"，需要在洞口半径 0.80–1.12 倍之间加一圈暖色环
  （峰值 ~0.34），约 20 行代码，但决定整个效果的成败。
- **配套**：想让"洞外"和"洞内"形成对比，地表与下层必须**一亮一暗**。
  地表用暗色 + 下层用暗色 = 没有对比 = 概念失效。

### [P1] 未命名

标签: 中文排版 / 折行 / clamp

### 中文大标题：`clamp()` 只看"够不够大"会折行折在错的地方
`font-size:clamp(30px,5.6vw,74px)` 在 1440px 视口下，10 个汉字的第二行被折成"…犹豫开/始。"。
- 修法三件套：`font-size:clamp(26px,3.9vw,54px)` + `text-wrap:balance` + `max-width:22ch`。
- 原因：汉字没有词边界，浏览器按容器宽硬断；`vw` 比例在中等视口最容易失控。
- 纪律：**动效尺寸要写成视口比例**（`屏宽×0.17` 而非固定 `150px`），
  但**正文字号必须设 `ch`/`max-width` 上限**，两者方向相反，别混用一套思路。

### [P0] 未命名

标签: 拖尾 / 残迹 / 擦除 / canvas / 参数区间 / 视觉噪音

### 「残迹 / 拖尾」是最危险的一件礼物 —— 三条止血参数必须先定
给光标加历史轨迹（擦过的地方留痕、慢慢愈合）几乎必然先做出脏东西：残迹互相重合、叠加成实心块。
- **实测事故**：12 枚残迹 × 半径 0.92R × 初始不透明度 0.86、间距 42px → 相邻完全重合，
  整屏叠成一坨实心黑云**把标题整个吞掉**；且每块残迹都描了热边 → 叠出一圈圈"洋葱"条纹，像渲染错误。
- **止血参数（可直接抄）**：半径 **≤0.55R**、初始不透明度 **≤0.15**、落点间距 **≥0.7R**、
  环形缓冲 **6**；**热边/描边只给当前那一块**，残迹一律不描边并额外加一层羽化。
- **衰减**：alpha ×= `0.5^(dt/4000)`（4 秒半衰期）+ 半径 `0.5^(dt/16000)` 缓慢收缩，
  读作"擦过的地方正在长回来"。
- **通病**：设计稿里写"最多 12 个斑点、约 4 秒半衰期"这种**量词**根本不够——
  必须翻译成带约束的数值区间，否则照做出来就是灾难。

### [P1] 未命名

标签: 粒子 / 密度 / canvas / 星空 / 风场

### 粒子效果的"密度"要按像素算，不能凭感觉给
- **实测**：1440×900 下 760 枚粒子 = 1 枚/1700px²，整屏几乎看不见；改到 1800 枚仍只在光标附近可见；
  **3200 枚（≈1 枚/450px²）才读得出"场"**。
- **经验值**：想要"粒子场"观感 → **≥1 枚/450px²**；只想做点缀星点 → 1 枚/1500px² 足够。
- **拖尾长度必须随速度变化**（`8 + min(速度×6, 14)`），否则读不出流向；
  分档描边（两档色、两次 `Path2D.stroke`）比逐粒子设样式快得多。
- **力的比例就是笔触**：径向推力/切向涡旋力 = 1.45/1.30 得到"绕流"；
  径向过强（1.75/0.95）会得到围绕光标的一圈"刺"，读作爆炸而不是风。

### [P0] 未命名

标签: 可读性 / 保护带 / 保护文字 / 画布特效

### 「内容保护带」：画布类效果遇到文字必须断开路径，而不是降低透明度
- **场景**：线条生长 / 粒子 / 曲线类效果会穿过正文，在深色底上像划痕，正文可读性被拖垮。
- **做法**：把页面里每个文字块（标题各行、副标题、眉标、简介、行表每一项…）的
  `getBoundingClientRect()` 收成数组，扩边 **5px**；绘制线段时对**中点**做命中测试，
  命中就 `drawing=false` 之后 `moveTo` 重新开始 —— 即**断开路径**。
- **为什么比"降低透明度"好**：透明度只是变淡，还是穿过字；断开是"绕开字"，
  观感上像经过设计，而且**零成本**（你只是少画几段）。
- **实现提示**：用 `Path2D` 先把断开的路径 build 一次，再 stroke 两遍（外粗暗 + 内细亮）做锥形效果。
- 这条已升级为「鼠标特效实验台」的全局铁律，与"正文 ≥60% 面积不被扰动"并列。

### [P0] 复刻 3D 场景连败 4 轮后才想通：该改的是「几何朝向」，不是参数

标签: three.js / WebGL / 朝向 / 几何 / 复刻 / 岩壁 / 视差 / 盲调

- **背景**：照参考视频复刻 Lithos 那类"暗底 + 竖版层积岩壁 + 熔岩渗缝"的 hero。
  连续 4 个版本全失败 —— 要么整屏黑（98% black），要么整屏被贴图糊满，怎么调亮度/曝光/噪声频率都没用。
- **真正根因（第一条）**：**平面朝向选错**。
  `rotation.x = -π/2` 是"躺平成地面、相机略高俯视"的写法（适合"站在山坡上"的视角）；
  但 Lithos 原片主体是**一堵横贯画面的竖直岩壁**（上缘是起伏天际线，标题浮在它上方黑空里），
  相机是**几乎平视、正对**。用躺平朝向做岩壁 → 相机看到的是地形边缘/切片 → 必然黑屏或糊满。
  **正确配方**：平面**不旋转**（竖直 XY，法线朝 +Z）、高度写进 **Z 轴**（朝相机凸出）、相机 `y≈2.3 z≈12` 平视。
- **真正根因（第二条）**：**高度量级失控**。`heightAt` 峰值实测 **3.402**，而平面宽 16 → 高度占宽度 **21%**。
  这不是浮雕而是**一个伸向相机的巨大方块**，相机贴着岩面看，透视把层理放大成横贯全屏的粗光带。
  → 写代码前**先用独立脚本量出 heightAt 的 min/max**，归一化到 0~1 再乘 `H_MAX`，
  **让 峰值/宽度 ≈ 0.10**。
- **真正根因（第三条）**：**矩形直边**。平面天生是矩形，会露出四条直边，一眼就是"贴图方块"。
  左右 `clamp` 收口不够（上下角仍露直角）。要用**一圈不规则椭圆包络**：
  `rr=sqrt(((u-.5)/.66)²+((v-.34)/.56)²)` + fbm 扰动 → `smoothstep` 过渡到 0；
  上缘再叠**纯低频**脊线做尖齿天际线（加高频会出梳齿锯齿）。
- **纪律**：**连续 2 轮调数值没接近参考，就必须停手回去质疑几何/朝向/相机**。
  在错误的结构上调参数，是在给一具错误的骨架化妆。
- **配套假象**：数值接近 ≠ 长得像。曾在 mean 0.108 / black 47.1 / avgRGB 完全命中参考的情况下，
  画面仍是一块歪斜矩形平板。**数值只用来收敛明暗，构图必须人眼看图。**
- **参考基准（Lithos 原片 1120×630 抽帧实测）**：mean 0.111 / black% 46.5 / bright% 5.4 /
  avgRGB (33,27,30) / orange% 1.8 @ row 75% / 9 横带 `0.18 0.09 0.05 0.10 0.03 0.11 0.08 0.17 0.20`。

### [P1] 视觉交付的无头截图验收管线（可复用）

标签: playwright / 无头 / 截图验证 / 验收 / 视觉回归 / chromium

- **做法**：每次交付 WebGL/交互动画页，用 playwright 起本地服务截 3 屏人眼确认：
  1. 装进隔离 node workspace：`npm --prefix <node_workspace> install playwright`；
     `node node_modules/playwright/cli.js install chromium`（浏览器二进制也要下）。
  2. 起静态服务：`python -m http.server 8123 --directory <页面目录>`（后台）。
  3. `shot.cjs`：playwright `chromium.launch()` → `goto('http://localhost:8123')`
     → 分别 `scrollTo` 到首屏/中段/深滚 → `screenshot()` 存 3 张 → `page.on('pageerror')` / `console` 抓错误。
  4. 用 Read 看 3 张图确认效果接近 brief，且 console 零报错。
- **配套纪律**：截图前给标题动画加「delay 不推进→兜底 opacity:1」的兜底（见本文件前面「无头截图里 CSS 动画 delay 不推进」条目），否则标题截图是透明的。
- **价值**：比"函数没报错"可靠得多——真渲染、真滚动、真截像素，能在交付前发现"一眼假/黑屏/假光斑"。
- **坑**：`page.screenshot` 默认只截视口，要长图用 `fullPage:true` 但注意 100vh 元素会跟着涨。

### [P1] 竖直岩壁的噪声频率轴与「躺平地形」相反（手写 noise/层理必踩）

标签: three.js / WebGL / 噪声 / 频率轴 / 岩壁 / 层理 / 熔岩 / shader

- **现象**：把 `webgl-terrain-hero` 里给"躺平地形"调好的噪声参数直接搬到"竖直岩壁"上，
  层理变成满屏斑点/霉块、熔岩缝几乎看不见，怎么调亮度都没用（详见本文件前面「该改的是几何朝向」那条）。
- **根因（因果级）**：躺平地形的 `v` 是**进深方向**，所以"v 频率压低"= 沿进深拉长的层理；
  但竖直岩壁的 `v` 是**竖直方向**——层理必须**沿水平(u)拉长、沿竖直(v)中频分层**，频率轴完全反置。
  同理，熔岩缝要**沿层位水平裂开**（`v*STEPS` 的小数部分当层位，层内窄缝 + 层间断续），不是竖着一条 `Math.abs(u-0.5)`。
- **解法**：岩壁 heightAt 用 `ridged(u*约1.0, v*约2.4)`（u 低频、v 中频）；
  crackAt 用 `const layer=v*STEPS; const flv=Math.floor(layer), frv=layer-flv;` 取层位，
  `seam=exp(-sin(frv*PI)**2*K)` 做窄缝，`pick=smoothstep(层位正弦)` 挑少数层位发光。
- **关联**：此条是「几何朝向」那条（#825 附近）的**参数级补丁**；两者都在 `webgl-terrain-hero` SKILL.md 坑 16/17 固化。

### [P1] 鼠标照亮（指哪亮哪）在 three r155+ 下 intensity=3.0 肉眼不可见

标签: three / PointLight / 鼠标照亮 / 物理光照 / 坎德拉 / raycaster

- **现象**：给 PointLight 设 intensity=3.0 想做"鼠标照亮山体"，playwright 前后两张截图肉眼零差异，用户质疑"你改了吗"。
- **原因**：three r155+ 默认物理光照单位（坎德拉），3.0 在暗场景里亮度趋近于零；且纯光斑没有视觉锚点，人眼无法归因。
- **解法**：①lamp 强度提到几十坎德拉级（45~90，distance 15、decay=2）；②叠一个暖色光晕 Sprite 跟随光标当"鼠标=灯"的可见锚点；③raycaster 打地形取命中点，`lamp.position.lerp(命中点+法线*1.2, 0.18)`，强度指数平滑趋近目标。验收：同视角鼠标在/不在各截一张，人眼必须能立刻指出亮斑。注意与"速度火把"模式（vel 主导、不动不亮）区分——用户说"照亮"=常亮模式。

### [P1] three.js 程序化植被（草甸+针叶林），依坡度/海拔分布，自动被场景光照亮

标签: three / InstancedMesh / 植被 / 程序化 / 草 / 树 / 坡度分布

- **现象**：真实山要在岩体上长植物。逐 mesh 建几千株草直接卡死；InstancedMesh 不重算包围盒会被视锥整批剔除（屏幕啥都没有）；setColorAt 忘了 needsUpdate 颜色不生效。
- **原因**：程序化植被必须批渲染；实例分布远超原始 geo 包围盒；instanceColor 是独立 attribute 需手动标脏。
- **解法**：①复用山体 heightAt 同函数 + 有限差分 slopeAt，按"陡崖不长/缓坡低海拔才长/高海拔偏黄"撒点；②草=ConeGeometry 开放底面细长锥，树=圆柱树干+锥冠两组 InstancedMesh 共用变换矩阵；③`mesh.count=N; mesh.frustumCulled=false; setColorAt 后 instanceColor.needsUpdate=true`；④植物用 MeshStandardMaterial，自动吃 key/lamp/IBL 全部光，鼠标 lamp 顺便照亮植被，无需特判。

### [P1] three.js 真实植被：交叉面片草 + 多层锥冠树 + onBeforeCompile 顶点风动（铁律5 不假）

标签: three / 植被 / 交叉面片 / 多层树 / onBeforeCompile / 顶点风动 / InstancedMesh

- **现象**：用 ConeGeometry 当草、单锥冠当树，远观暗场景能混，近看/细看就是设计图形，违反铁律A+物理正确。InstancedMesh 直接逐实例建几千株会卡死；想加风动又怕改不动标准材质。
- **解法**：①草=两片细长 PlaneGeometry 十字交叉合并（crossBlades），比锥更像草叶；②树=3 层 ConeGeometry 堆叠合并（layeredFoliage），轮廓是真正针叶树；③分布仍用 mountainHeight+slopeAt 依坡度/海拔撒点，InstancedMesh 批渲染（count/frustumCulled=false/instanceColor.needsUpdate 三件套）；④风动：对植被材质挂 onBeforeCompile，注入 `sin(uTime*1.6 + instanceMatrix[3].x*0.7+instanceMatrix[3].z*0.9)*0.05*max(position.y,0)`，让根部不动尖端摆（position.y 是局部高度）；渲染循环更新 `mat.userData.sh.uniforms.uTime.value`。
- **验收（铁律4不自欺）**：像素量化——首屏绿占比>8% 证植被存在、鼠标点亮前后均值亮度差>0 证照亮可见、相机稳定后截双帧算植被像素MAD>0.4 证风动真在动。三者全 PASS 才算过。
- **坑**：onBeforeCompile 里 `instanceMatrix` 在 three 内置可用，拿第4列([3])即实例世界平移；若材质被缓存需 `material.customProgramCacheKey` 区分。PlaneGeometry 手动合并要同时拼 position 数组与 index（每个 part 的 index 需加 base 偏移）。

### [P1] 顶级站的植被是"材质层"，不是物件（Lithos 原站拆解顿悟）

标签: three / 苔藓 / 植被 / 材质层 / onBeforeCompile / 参考站拆解 / 封面验收

- **现象**：用 InstancedMesh 摆了交叉面片草 + 多层锥树，用户甩来 Lithos 原站录屏说"这才是我要的植被，顶级站一定不是你这样做的"。
- **拆解**：抽帧逐一看原站——植被根本不是独立模型，是**苔藓/地衣长在岩石材质里**：fBm 斑块掩码 × 坡度 × 海拔带 × 裂缝排除，在 MeshStandardMaterial.onBeforeCompile 里混进 diffuseColor；细颗粒噪声 + 稀疏亮斑当小花地衣；roughness 提到 0.97。首屏绿占比仅 1~2%，主体仍是近黑岩石。之前做成 28% 绿裙 = "刷绿漆"，一眼假。
- **口诀**：暗而不灭，不是绿而抢眼；山是主角，苔藓是点缀；掩码里"裂缝排除"必须用静态 aCrack（不能带 flicker），否则苔藓边缘跟着熔岩呼吸。
- **验收**：覆盖率区间 + 山体区域内斑块化标准差 + 两帧绿掩码 IoU（形状锚定）。逐像素 MAD 会因熔岩 flicker/bloom 合法亮度变化而误报。

### [P0] 「植物太假」的四个真根因 + 森林真实感三件套（手写 splat / 照片素材 / 顶点色烘光）

标签: 真实感 / 森林 / 树 / 植物 / Three.js / splat / 高斯泼溅 / ooosplat / 顶点色 / 空气透视 / LOD / ThreeUI

黄总原话：「**你这个太假了**，参考一下 ThreeUI 的植物设计，增强 3D 效果，用 ooosplat」。4 轮迭代后的结论。

**四根因（按影响排序 —— 别急着调参数，先对着这四条查）**
1. 树冠用几何体（圆锥）→ 轮廓是解析曲线，**不可能真**；
2. 同一套公式 × 同一批几何 → **每棵树一模一样**（零抖动）；
3. 均匀撒点 → **圣诞树阵**（真实林子成簇长 + 留出空地）；
4. 远树**要么吃方向光变黑、要么不吃光变成平板一块绿**。

**① 手写 splat（不训练）**
ooosplat 那套是「环绕拍一圈 → COLMAP/Brush 训出 final.ply」。网页里没有实拍素材时**不用训练**，直接手写：每个 splat = 一块细长椭圆广告牌 + 独立颜色/朝向/尺寸。
- FS 里 `float a = exp(-dot(vUv,vUv)*2.6); if (a < 0.30) discard;` ← **硬切出来的毛边就是「针叶感」**，这条是灵魂。
- **沿锥形体积铺点，不要随机撒**（随机撒 = 毛球 或 竹竿林）。先定树冠体积（底半径 `R0 = 0.305*H`、锥度 `pow(1-u, 0.72)`），再按 `rad = maxR*pow(rnd(),0.34)` 铺；用 vnoise 做「枝簇」`if (rnd() > 0.34 + clump*0.92) continue;` 打破光滑锥。
- 明暗：`litK = 0.30 + 0.78*pow(rad/maxR, 0.75)`（外侧受光、内侧近黑）。
- 实测 13 万 splat（`splats 132,703`）撑满整屏无压力。

**② 近景植物 = ThreeUI 的真实照片广告牌（这就是「不假」的捷径）**
ThreeUI `secret-pathways` 场景**根本不用 3D 建模做植物**，而是拿真实摄影抠图当平面 billboard：`pine-tree.webp` / `tall-grass.webp` / `garden-bush.webp`（带 alpha）。
- **必须 `MeshBasicMaterial`** —— 照片自带光照，再用 `MeshStandardMaterial` 打光只会更黑 → 变成纯黑剪纸。
- 素材偏暗要提亮：**gamma 0.74–0.80 + gain 1.24–1.30 + UnsharpMask**（提暗部），再转 webp（PNG 2MB 太大，webp 150–250KB）。`alphaTest ≈ 0.34`。
- 版权：ThreeUI Community 字体/纹理另授权，商用交付前换自有素材。

**③ 远树 LOD：顶点色烘「假受光」—— 本次最关键的一招**
远树不值得上 splat（雾一糊细节全看不见）→ InstancedMesh 圆锥撑「林海」密度，splat 预算全给近树。
但远树**不能吃方向光**（背光 = 一排黑尖塔，一眼假）→ `MeshBasicMaterial`；可纯 MeshBasic 又是平板一块绿。
解法：**把明暗烘进几何顶点色**：
```js
const vUp   = clamp(py + 0.5, 0, 1);                        // 0=底 1=尖
const shine = 0.5 + 0.5*Math.cos(Math.atan2(pz,px) - 0.9 + sd*0.07);
const lum   = clamp(0.52 + 0.52*vUp + 0.26*shine*(0.40+0.60*vUp), 0.40, 1.30);
// 材质 vertexColors:true；实际色 = material.color × 顶点色 × instanceColor(雾混合)，三者相乘
```
**垂直分量在实例随机旋转下不变 → 整片林子受光一致、不会花。** 成本为零，肉眼差别立竿见影 —— 比多加几个几何变体有效得多。
配套：`ConeGeometry(1,1,8,4)` + 半径扰动 ±43%（`k = 1+(n-0.5)*0.86`）+ **3 个 sd 变体分桶**（全用同一个圆锥 = 规整尖塔阵）。

**④ 收尾三条（不做还是会假）**
```js
const clump = vnoise(x*0.055 + 31.7, z*0.055 + 11.3);   // 疏密：成簇 + 留空地
if (rnd() > 0.26 + clump*0.98) continue;
s: 0.55 + Math.pow(rnd(), 0.82) * 1.95                  // 高矮：pow<1 让小树更多
const lean = (rnd()-0.5)*0.13;                          // 倾角：笔直挺立的水泥柱才假
```
再加每棵树独立的 `wJit = 0.80+rnd()*0.44` / `hJit = 0.86+rnd()*0.30`。

**⑤ 相机路径净空**：`if (Math.hypot(x, (z+8)*0.62) < 9.5) continue;`
否则镜头直接钻进树冠，画面上糊成一大团绿。另配 近景植物 `1-smooth(0.18,0.32,scrollN)` 淡出、远树 `1-smooth(0.60,0.84,scrollN)` 按叙事淡出。

- 关联：skill `webgl-terrain-hero`（已含完整章节 + 踩坑速查表）/ `threeui-integration` / 真实感铁律

### [P1] 平静湖面 + 指针涟漪的完整配方（解析式波动场，零依赖单文件已验证）

标签: WebGL / shader / 湖面 / 水波 / 涟漪 / 波纹 / 月光 / 静湖力场

「背景换成平静湖面、指针划过起波纹」这类需求，不要上 ping-pong 波动方程模拟，用**解析式波动场**就够真实且零风险（无 float 纹理扩展依赖）：

- **构图**：视向平面求交代替屏幕空间噪声——`ro=(0,1.35,0)`、`rd=normalize(vec3(ndc.x*aspect*0.85, ndc.y*0.95-0.72, -1.0))`，`rd.y<0` 打到水面 `t=1.35/(-rd.y)` 得世界坐标 p。地平线自然压到屏幕顶部 ~12%，透视压缩自带"近快远慢"。
- **波动场**：`h = 微涌 + Σ涟漪`。微涌=5 组不同向正弦（幅 0.0026~0.015，平静感的底）；涟漪=`exp(-x*x*46)*cos(x*17-age*2.6)*exp(-age*0.8)*s/(1+age*1.4)`，其中 `x=distance(p,d.xy)-age*1.15`（恒速外扩）。**多条涟漪直接叠加=自然干涉花纹**，这是"真水感"的来源。
- **着色**：高度场有限差分求法线（eps=0.028+t*0.0035 随距离放大防远处闪烁）→ `reflect(rd,n)` 采样程序化天空 → 菲涅尔 `0.025+0.975*pow(1-dot(-rd,n),5)` 混深水色；镜面月路 `pow(dot(rdir,M),90)*0.72+pow(...,7)*0.05` 是涟漪可见度的关键（波峰吃光）。
- **交互**：指针移动按 26px/90ms 节流投波（强度随手速）、点击 s=1.5 石子、**悬停 300ms 微扰防"停住=死掉"**；屏幕 y 要翻转存（uv 原点左下）。JS 端复制同一套射线数学把 clientX/Y 换算世界坐标。
- **防过曝**：月光反射很容易糊成一大块白——镜面项压到 0.72 + 全局软压高光 `col=col/(1.0+col*0.16)`，月路才碎成随波闪的光带。
- **死区教训**（P64 草热区同款）：指针进天空区（rd.y≥0）打不到水面≠没反应，把 ry 夹到 ≥-0.1125（落到中远景）再算投点，全屏都是热区。
- 产物：`静湖力场/index.html`（2026-09-26，线上 stillwater-field-lab.app.workbuddy.host），由 pointer-field-lab（点阵版）改造而来。

### [P1] 同源并发 4 路 video 会落入 seekable=[0,0] 僵态：currentTime 被静默忽略，v.load() 可自愈

标签: chromium / video / seekable / mp4 / 滚动驱动 / Playwright / 沙箱服务器

为「滚轮拖帧」页（视频不 play()、currentTime 由滚动进度每帧写入）做验收时发现：

- **现象**：同一页面 4 路 `<video preload=auto src=*.mp4>` 并发加载后，`readyState=4`、`buffered` 全满，但 `seekable=[0,0]`，写 `currentTime` 被**静默忽略**（值不变化）、页面 `load` 事件永不来；**时好时坏**。最小对照实验：单路视频（muted+playsinline+preload=auto）seek 全过，visibility:hidden 包裹也过，poster / disablepictureinpicture 都无罪，**4 路并发必挂**；过早（readyState<2）就每帧 seek 会把 readyState 卡死在 1。
- **原因**：Chromium + 不支持 Range 的静态服务器（本机 python http.server、线上沙箱均对 Range 返回 200 而非 206）下，多路媒体并发资源选择会落入半初始化僵态——数据已缓冲但 seekable 判空；半初始化时的 seek 请求还会把管线钉住。
- **解法**（已固化进 生成物/site/ascent_video/index.html 的 syncVideos，可直接抄）：
  1. seek 前先验 `seekable.end(last) > 0.01`，不健康绝不写 currentTime；
  2. 不健康且 `buffered` 已有数据（缓冲全满、或已等 3 秒）→ 调一次 `v.load()` 重启资源选择（此时命中缓存），实测四路全部恢复：seekable [0,0]→[0,dur]、seek 生效、正/反拖帧全对；用 `_healTries` 限 3 次防重启循环；
  3. `preload=auto` 在 markup 写死，**运行时不要改 preload**（中途改会加剧僵局）。
- **验收方法**：不要目视，用断言脚本实测 seek 能力（set → 读回比对）+ 滚轮下滚/上滚各一次看 currentTime 增减 + 停止后两次采样必须相等。

## 06. 发布与自动化

_部署上线 / 定时任务 / 资料库_

### [P0] 发布上线的正确姿势

标签: 发布 / sites

静态站 / Node HTTP 服务都能发。要点：

- **多文件站必须 entire 发布** —— present_files 传单个 HTML 只会托管那一个文件，相对链接全 404
- **带视频/大文件的站**：startCmd 必须指向自写的 `serve-range.cjs`（默认 python http.server 不支持 Range，视频会挂），language 填 `node`
- **每次 rebuild 会清空 dist**，`serve-range.cjs` 要重新生成
- 脚本内 ROOT 要写成 `__dirname`（写死 `join(__dirname,'dist')` → 全站 404，且 404 body 就是 '404' 字样，可据此辨认）
- 端口读 `PORT` env，监听 `0.0.0.0`

公网验证三件事：index 200 / 视频 Range 206 / 图片全 200。

**已上线地址：**
- 作品集 https://hyh-portfolio.app.workbuddy.host/
- 旧简历 https://hyh-resume.app.workbuddy.host/
- 交大 AI 教程 https://dive-into-llms.app.workbuddy.host/
- 华师大情报 https://workbuddy.link/p/ZwZnlCpd55NxcuHNn2LU2
- AI 前沿情报 https://workbuddy.link/p/qyfLuxV3KyZ7b9RfPiKVO9

### [P1] 每日自动更新网页的固定链路

标签: 自动化 / 定时

两个情报站跑了一周多的成熟链路（每天 07:00）：

1. WebSearch / WebFetch 抓信息（学院官网用 **WebFetch 直接抓列表页远好于 WebSearch**，后者常被同名学院污染）
2. **只改 `<script>` 里的 `var DATA = {...}`**，其余代码不动 → 用 Python 正则整段替换比 Edit 更稳
3. 自检脚本 `node _check.js`：语法 / 元素 ID 存在 / 无外链 / 渲染函数互调 / 数据格式；打印 counts
4. 发布顺序固定：**先 import 后 publish**
   ```
   printf '%s' "<token>" | python import_html.py --token-stdin --node-block-id <id>
   printf '%s' "<token>" | python publish_page.py --token-stdin --node-id <id>
   ```
   token 通过 ToolSearch + `DeferExecuteTool(connect_open_platform, skill_id=library)` 获取
5. 回复里给一段摘要 + 链接

**内容纪律**：每日更新禁止编造 deadline 和竞赛加分分值；未核实的场地/日期标注"以官方为准"。

### [P2] 后台进程跨轮次会被杀

标签: 后台进程 / 寿命

vite dev / http.server 这类 Bash 后台进程**跨轮次会被杀**，表现为 502 或连接拒绝。

- 每轮用前先探测端口，死了就重启
- 重启方式要固化成一行命令或脚本（`dev.cjs` / `serve-range.cjs`）
- 换端口是最省事的排障手段（也顺带绕过预览缓存）

查端口占用：`netstat -ano | findstr :8777`，杀进程：`taskkill /F /PID <pid>`。

### [P0] 发布站点改了文件但线上还是旧的：换文件名，不要等缓存

标签: 发布 / CDN / 缓存 / cache-buster / sites / 线上覆盖

- **现象**：重新发布返回 `verified: true`、用带随机参数的 URL 回源取到的**确实是新版**，
  但用户访问不带参数的正式链接，拿到的**仍是旧文件**。反复重发无效。
- **原因**：CDN 是**按 URL（含文件名）**缓存的。发布只是把源站文件换掉，
  已经存在的边缘缓存条目不会因为你重发就失效；带 `?cb=xxx` 的请求是缓存未命中，
  所以能直接看到新版 —— 于是形成"我验证是新版、用户看到是旧版"的分裂。
- **解法（按可靠性排序）**：
  1. **换一个新的文件名**（如 `control-tower.html` → `app.html`），把入口页链接指过去。
     这个 URL 从未被缓存过，必然回源取新版。**最快、最确定。**
  2. 让用户用带版本参数的链接（`.../app.html?v=5`）。能用，但参数一固定又会重新被缓存。
  3. 等 TTL 自然过期 —— 不可控，**不要作为交付方案**。
- **纪律**：
  - 别用"回源是新版"当成"用户能看到新版"。**验证要对用户实际访问的那个 URL 做。**
  - 更硬的验证是**用无头浏览器真渲染用户那条 URL**，直接读 canvas 像素 / DOM 文本，
    比看 HTTP 响应体更贴近用户所见。
  - 在被缓存的文件里放一个**显眼的版本戳**（顶栏 `BUILD r5-0916` 之类），
    用户一眼就能报"我这里是哪个版本"，省掉一轮互相猜。

### [P1] Skill 目录站：把分类做成表格 + 独立新网址给外部 AI 学习

标签: skill / 目录 / 发布 / 单一数据源 / 表格 / 给AI学习

- **线上地址**：`https://skill-catalog-21561.app.workbuddy.host/`（app 名「Skill 分类目录」，独立新应用）。
  - `/` 人类可读表格页（搜索 + 类别筛选 + 一键复制提示词）
  - `/llms.txt` AI 全文索引（纯文本表格，直接贴给其他 AI 学）
  - `/table.md` 纯 Markdown 表格（粘进任意聊天窗口）
- **单一数据源（关键）**：分类只写在 `_scan/skill_cats.py` 的 `SKILL_CATS`(名→类) +
  `SKILL_TRIGGER`(名→触发场景)。`build.py`（手册）与 `build_catalog.py`（目录站）都 import 它，
  **一处改、两处同步**，杜绝两套分类漂移。
- **生成**：`python _scan/build_catalog.py` → 产出 `skill-catalog/{index.html,llms.txt,table.md}`。
  脚本内置覆盖校验：`listed=44 total=44 missing=[] orphan=[]`，不齐就 `sys.exit(1)` 拦住。
- **给 AI 的提示词是动态拼的**：页面把 `location.origin + '/llms.txt'` 算出来填进「复制」框，
  不写死 URL —— 换域名/换路径后提示词自动正确（本地 file:// 打开时也能用来验证逻辑）。
- **发布注意**：工作区已有多个 app 时，`sites_deploy` 会返回 `sites_deploy_needs_app_selection`，
  **必须先让用户从候选里选（或明确新建）**，不能自己替它决定。要「新网址」就 `createNewApp:true`。
- **验证**：线上按原始字节 UTF-8 解码比对——三份文件字节数与本地**完全一致**
  （15290 / 7453 / 5492 B），Content-Type 分别 text/html、text/plain、text/markdown；
  再用无头浏览器真渲染，确认复制框里是**真实线上 URL**、搜索与类别筛选都生效。
  - 控制台唯一报错是浏览器自动请求 `favicon.ico` 的 404，属静态站常态、无实际影响。
- **教训**：PowerShell 里拼 URL 别用 `$base+"x"`（会被解析歪），用 `"${base}x"`；
  校验中文内容必须显式按 UTF-8 解 `RawContentStream`，否则会因编码误判成"内容不对"。

### [P2] 未命名

标签: favicon / 404 / 控制台 / data-uri

### 静态站控制台的 favicon 404：一行内联 data URI 就能消掉
- 早前记录（见上文 Skill 目录站条目）认为"favicon.ico 404 属静态站常态、无实际影响"——
  **现在有零成本解法**：在 `<head>` 里加一行内联图标，浏览器就不再请求 `/favicon.ico`：
  ```html
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='16' cy='16' r='11' fill='%23c1440e'/%3E%3C/svg%3E">
  ```
- 注意转义：属性用双引号、SVG 内部用单引号、`#` 写成 `%23`。
- **收益**：线上真渲染验证时 `console errors` 能干净地归零，
  以后凡是"控制台有报错"就能当成真问题处理，不必每次人工排除 favicon 噪声。

### [P1] 未命名

标签: 线上验证 / 真渲染 / CDN / 脚本

### 线上发布后，用「真渲染脚本」验用户实际访问的那条 URL
- **脚本**：`mouse-fx-lab\_live.cjs`（playwright-core + `channel:'msedge'`）
  `node _live.cjs <url> <tag> <outDir>` → 打开 URL、断言 `window.LAB` 存在、
  逐个切变体并**真实移动指针**、打印 `sig()` 与 fps、截图、收集 console error。
- **为什么必要**：重发返回 `verified:true` ≠ 用户能看到新版（CDN 按文件名缓存）；
  只看 HTTP 响应体也不够 —— 得真渲染、真跑一遍交互，才等于"用户所见"。
- **本轮实测**：`/rounds/r3.html` 线上 4 个变体 sig 全部非零（`e6|…` / `w62|…` / `p606|…` / `m4|…`），
  fps 139–165，`errors=[]`（补了内联 favicon 之后）。
- **配套纪律**：每轮**换新文件名**（`r1/r2/r3.html` 各自首次发布），
  并把同内容的入口页另存一份带轮次后缀的（如 `index-r3.html`）绕开 index 的缓存。

### [P1] 把 Comfy Desktop 接进 WorkBuddy：零依赖 stdio MCP 桥

标签: comfy / mcp / stdio / 接入 / 图像生成 / 本地服务

- **为什么不用官方 `comfy-mcp`**：它硬依赖 `comfy-cli`，而 comfy-cli 会自己启停 ComfyUI，
  与 Comfy Desktop 的生命周期管理**抢启动权**。本机 Desktop 已经在跑，只需要一个「桥」。
- **做法**：自写**纯标准库**的 stdio MCP server，直连 `http://127.0.0.1:8188`，
  不启进程、不装节点、不拉模型。
- **位置**：`C:\Users\lenovo\.workbuddy\mcp-servers\comfy-desktop\server.py`
- **注册**：`C:\Users\lenovo\.workbuddy\mcp.json` → `mcpServers.comfy-desktop`
  （`command` 指向管理版 python.exe，`args` 指向 server.py，`env` 设 `COMFY_BASE_URL`）
- **12 个工具**：`comfy_status` / `comfy_list_models` / `comfy_search_nodes` / `comfy_node_schema` /
  `comfy_submit` / `comfy_job` / `comfy_fetch_outputs` / `comfy_upload_image` / `comfy_cancel` /
  `comfy_clear_queue` / `comfy_free_vram` / `comfy_open_ui`
- **自检脚本**：`C:\Users\lenovo\WorkBuddy\2026-09-17-16-24-06\生成物\comfy\自检.py`
- **关键设计**：结果文件走 HTTP `/view` 取字节流后自己落盘，
  因此不关心 ComfyUI 真实 output 目录在哪；默认落到 `<cwd>/生成物/comfy`，符合产物归置铁律。
- **必须手动一步**：写完 `mcp.json` **不会自动生效**，要在连接器管理页右上角
  「自定义连接器」入口对该服务点「**信任**」。
- **可复用**：这套「自写 stdio MCP 桥直连本地 HTTP 服务」的模式，
  可原样套到任何本地有 HTTP API 的工具上。

### [P2] sites_deploy 首次报 "fetch failed" 时，原参数直接重试即可

标签: 发布 / sites_deploy / fetch

- **现象**：调用发布工具第一次返回 `Error publishing site: fetch failed`，没有任何附加信息。
- **原因**：未定位（疑似首次请求的瞬时网络/握手问题）。
- **解法**：**原参数原样再调一次**，第二次即成功（返回 `verified: true`）。不要因为一次失败就去改参数、换域名或改走别的发布路径。
- **补充**：同一 workspace、同一目录再发布 = **覆盖同一个 app、链接不变**（不是新建 app）。所以多页站点必须自己做成「一个入口页 + 子页」，否则第二次发布会把第一页顶掉。
- **发布后核验**：对线上真实 URL 跑截图 + 抓错误，并 `curl -s -o /dev/null -w "%{http_code} %{size_download}"` 核对字节数与本地一致 —— 不要只看「发布成功」的返回。

## 07. 检索与资料处理

_联网取材 / 下载 / 转写 / PDF_

### [P1] 音频转写成文字（本机无 ffmpeg 也能跑）

标签: 转写 / whisper / 音频

方案：`faster-whisper`（已装进 default venv）

```python
from faster_whisper import WhisperModel
model = WhisperModel(size, compute_type="int8")   # small / medium
segments, info = model.transcribe(
    audio, beam_size=5, vad_filter=True,
    initial_prompt="以下是普通话的句子。")
```
- 用法 `python transcribe.py small`，首次下载模型
- 输出格式 `[起-止秒] 文本`
- 22 分钟会议音频 → 514 段，效果可用

实战产出过《会议纪要-视频组-20260913.md》。人名是音译，**必须让悦皓核对**。

### [P1] 扫描件 PDF 无文字层时的图片抽取

标签: PDF / 图片提取

证书类扫描件没有文字层，装 PyMuPDF 太重。

**快解法：正则直接从 PDF 二进制里抽 JPEG 流**
```
匹配 /Subtype /Image ... /DCTDecode ... stream ... endstream
按 /Length 取长度，切出字节写 .jpg
```
再 Pillow 压缩 → base64 内嵌到 HTML（286KB → 66KB 的常见操作）。

比装 PyMuPDF 快得多，够用。

### [P2] 批量下载视频到本地

标签: 下载 / 视频

B 站合集用第三方方案批量拉（无登录 cookie 也能拿 1080p），DASH 流用 imageio-ffmpeg 合并。

脚本要点：
- **断点续传**：已存在 >1MB 的跳过
- 随机 sleep 防风控
- 失败记录到 log
- 跑到一半被中断不损失，重跑即续传

实例：67 集合集共 3.84GB，零失败。附带生成 `视频清单.html` 分组导航索引页。

**注意**：第三方合集常混入其他机构内容，别默认全是目标课程。

### [P1] 用自相关找周期之前，必须先去掉线性趋势

标签: 周期 / 自相关 / 去趋势 / 时间序列

- **现象**：一段「爬坡 + 真周期 7 期」的数据，自相关法报出的周期是 **6**。
- **原因**：趋势项让相邻点天然正相关，把所有 lag 的相关系数整体抬高、峰值位置漂移。
  不处理趋势，自相关测的其实是趋势的强度。
- **解法**：先做最小二乘线性拟合，减掉趋势项，再对残差算自相关：
  ```js
  // 最小二乘 → d[i] = a[i] - (icept + slope*i)
  // 再对 d 算 r(lag) = Σd[i]·d[i+lag] / Σd[i]²
  ```
  同时只取**局部极大**（`r[lag] >= r[lag-1] && r[lag] >= r[lag+1]`）且 `r>0.3` 的 lag，
  否则强趋势会把 lag=2 顶成"最佳周期"。实测去趋势后同一个序列正确报出 lag=7。
- **验证用例**：常量序列和纯趋势序列都应报 `null`（无周期），这两条能挡住最常见的误报。

### [P0] 对标要抓真实数据，不要凭印象描述风格

标签: 对标 / 设计 / ComputedStyle / benchmark

- **做法**：用无头浏览器真访问对标站点，除截图外还抓 **ComputedStyle 的统计**：
  所有可见元素的背景填充色频次、文字色频次，加上 fontFamily、h1-h3、nav、button 的文本。
  产出的是"这个站点其实用了什么"，而不是"我感觉它是什么风格"。
- **实测收益**（一轮抓 6 个站点）：
  - Grafana Play：拿到 canvas `#111217` / panel `#181b1f` / hover `#22252b` 的**三级表面**关系，
    主文本 `#ccccdc` 带紫调而非中性灰；还发现它顶栏的搜索是**按钮**、不是常驻输入框。
  - Kinaxis：直接拿到品牌色 `#1a4146` + `#e30613`，用来做新皮肤比"工业风"三个字精确得多。
  - 也抓到纯看官网首页看不出的东西：Datadog 那个 URL 其实是 404、o9 全站只有三个颜色。
- **纪律**：抓来的色值/字体可以直接作为设计依据写进代码注释，**注明来源站点与原值**，便于回溯。
  这比引用一句"某某设计原则"硬得多。

### [P1] ThreeUI —— Three.js/WebGL 组件模板库（免费社区版 164 条，可直接复制源码/Prompt）

标签: ThreeUI / Three.js / WebGL / 组件库 / shader / React / 资源库

- 画廊 https://threeui.com ｜ 仓库 github.com/MengTo/threeui ｜ npm `@designcodeio/threeui`(MIT, 1.2.0)。
- 可直接复制的 React+Three.js 组件、网站模板、WebGL 背景、Hero、UI 特效、shader；
  组件页带 live renderer / controls / variant picker / Code 源码 tab，可复制源码或 Prompt 丢给 Codex/Claude Code/Cursor。
- 9 类：Landing Pages / Hero / Three.js / Backgrounds / Buttons / Text Animation / UI Elements / CSS / Motion Design。
- 免费：50 父组件/111 路由/141 变体+23 单例=164 条；带 `PRO` 标才收费。
- 用法：`npm install @designcodeio/threeui` → `import { X } from "@designcodeio/threeui"; import ".../style.css"`；
  子路径瘦身 `@designcodeio/threeui/components/<Name>`；全 HTML 文档型组件把 `lib-dist/assets/` 拷进 public。
- 用途：要「美观、视觉冲击力强」的前端时优先取用。

### [P1] 开放获取论文抓取 + 全文中译工作流（已沉淀为 skill `oa-paper-translate`）

标签: 论文 / 翻译 / OA / Cloudflare / ResearchGate / arXiv / pdfplumber / 课程站 / 镜像

- **场景**：把单篇/一批学术论文翻成中文单文件 HTML（保结构：摘要→章节→正文→参考文献原文）。已用于牛鞭效应 22 篇文献的批量中译（Wang&Disney / Lee 1997 / Ziegner / Sarı / Geevers 等 5 篇已译，15 篇付费墙待上传）。
- **坑① 中国 IP + 自动化被 Cloudflare 拦**：ORCA 机构库、ScienceDirect 不论 curl/WebFetch/本机 Edge 无头，全部返回 "Verification Required" 验证页，抓到的 PDF 只是验证页本身。解法：**换开放镜像源**，不要硬刚墙——ResearchGate 内嵌 preprint 全文（本环境 WebFetch 能过 RG，但过不了 ORCA）、arXiv 直抓 `arxiv.org/html/<id>v1`、IEEE Access/HBR/Europe PMC 文章页即全文。
- **坑② 大学课程站托管 PDF 是金矿**：INFORMS/Wiley/Springer 经典老文常被动过版权挂在欧美大学课程站（如 `courses.ie.bilkent.edu.tr/.../Lee-Padmanabhan-Whang-1997-MS.pdf`），`curl -L -A "Mozilla/5.0 ... Chrome/120" <url> -o x.pdf` 直下成功，pdfplumber 提取正常。
- **坑③ 深色页直接打印白字隐形**：原页深色底白字 → Edge `--print-to-pdf` 后台变白，需先生成浅色全静态版再打印。
- **提取**：`pip install pdfplumber` 后用 `pdfplumber.open()` 逐页 `extract_text()` 拼接。
- **纪律**：拿不到全文就判"付费墙不可获取"进清单等用户传 PDF，**绝不编造/靠摘要拼凑翻译**。
- **批量**：派 general-purpose 子代理自动跑，完成后必须复核产物；子代理常把明显该免费的（Lee 1997/Chen 2000）草草归墙，要亲自补抓。

### [P1] 马哲思维框架（已沉淀为 skill `ma-thinking`）：把哲学规律当任务执行的"思维操作系统"

标签: 马哲 / 方法论 / 辩证 / 矛盾分析 / 复盘 / 任务拆解 / 否定之否定

- **来源**：悦皓要求"系统学习马哲思想，对以后执行任务有帮助"。已系统化为主文档 `生成物/马哲思维框架.md` + 可复用 skill `ma-thinking`。
- **核心规律（可直接操作）**：
  1. 对立统一（矛盾）：一分为二找对立面 → 抓主要矛盾与主要方面 → 具体问题具体分析。
  2. 质量互变：量变到关节点引起质变；重视积累、警惕负向量变。
  3. 否定之否定：迭代是"扬弃"的螺旋上升——否定表皮、保留内核，不回退不复制。
  4. 实践第一：实践是检验真理的唯一标准 → 真跑、真点击、真渲染才是验证，函数能跑/verified 回执不算。
  5. 现象与本质：抓本质（可信度>漂亮渐变），不被表象迷惑。
- **任务执行循环**：①矛盾分析定位 → ②对立统一定守恒内核+兑现对立要素 → ③实践出可运行一版 → ④真验证（终点体验为准）→ ⑤否定之否定式复盘（扬弃+提炼法则）→ ⑥质量互变式迭代（关节点飞跃）→ ⑦约束变则方案发展。
- **已验证有效**（UI/UX 实验室 21 变体）：每轮守恒"生长+记忆"内核、媒介从排印→地形→声音螺旋上升；用 `LAB.sig()` 真采样、无头浏览器真渲染验证，不靠"函数没报错"。
- **对外投喂（铁律2）**：今后把任务交给任何 AI（含 WorkBuddy 专家/子代理），本框架作为"经验/方法论资产"一并全量投喂，附主文档与 skill 全文。
- **禁忌**：别机械套用语录；别"否定一切/肯定一切"（要扬弃）；别把 verified 当验证。

### [P1] 图像/帧比对前必须统一几何，否则互相关会假报警

标签: 图像比对 / 互相关 / corr / 验收 / 同几何

- **现象**：验收「段1尾帧 vs 段2首帧」一致性，拿**已裁切+缩放处理过的帧**对比**裸帧**，corr 掉到 0.484，疑似接缝严重不匹配；换两边都是裸帧再比 → 0.933，达标。
- **原因**：裁切（zoom+平移）+ 缩放改变了像素空间对应关系，互相关对几何错位极其敏感（5% 级别的缩放/平移就足以把 0.93 打到 0.5 以下），测出来的是「几何差」而不是「内容差」。
- **解法**：比对前把双方处理到**同一几何**——要么都用裸帧，要么对其中一方施加完全相同的 crop/scale 链再比；跨缝运动连续性再补一个「跨缝帧步长 MAD ≈ 相邻帧步长」的时间维度判据。任何 corr 结果先问一句「两边几何一样吗」。

## 08. 踩坑总清单

_全部历史坑的结构化索引_

### [P0] 踩坑总索引（按类别快速定位）

标签: 索引 / 检索

**Shell / 工具**
- Bash coreutils 全缺 → 用 Python 绝对路径
- PowerShell 输出不回显 → 写文件再 Read
- PowerShell Remove-Item 被 safe-delete 拦截
- Write 覆盖大文件报 modified since read
- Edit 报成功但未生效 → count 核查
- 并发 Edit 互相覆盖
- node 版本目录会升级 → 别硬编码
- npm install 不认 Bash cwd → spawnSync with cwd
- npm 慢/卡死 → 走 jsdelivr

**预览 / 服务**
- 内置预览按路径缓存 → 换端口
- python http.server 无 Range → 自写 serve-range.cjs
- 后台进程跨轮次被杀
- dist rebuild 会清空 → serve 脚本要重建

**ffmpeg**
- drawtext 需 FONTCONFIG_FILE
- 无 gblur/xfade/xstack → 见替代实现
- drawbox 无 t=fill → t=1000
- 静默失败多 → 逐段查 rc
- HEVC 要不转 H.264
- moov 在尾 + 无 Range = 视频打不开

**CSS / 前端**
- preserve-3d 遇 filter 被扁平化
- CSS transform 覆盖 SVG transform 属性
- reveal 与 parallax 抢 transform → 用 CSS translate
- backdrop-filter 全屏很卡 → 只给小卡片用
- 同名色的 rgba 形式会被漏替换
- esbuild 把 ::before 压成 :before

**内容**
- 编造素材 = 最严重错误
- 「简历」= 作品集
- .md 链到浏览器不渲染
- present_files 只托管单个文件

### [P1] 解析用户上传的 CSV 必须认引号字段，不能裸 split

标签: CSV / 解析 / 引号 / Excel / 数据导入

- **现象**：用户从 Excel 导出的 CSV 里，千分位数字写作 `"1,234"`。用 `line.split(',')` 切，
  会切成 `"1` 和 `234"` 两段，两段都不是合法数值 → **整列作废**，还报"没找到可用的数值列"。
- **原因**：CSV 规范里引号包裹的字段是一个整体，字段内的分隔符不是分隔符。裸 split 只处理了最理想的情况。
- **解法**：写一个真正的引号感知切分（约 15 行），处理「引号内保留分隔符」+「`""` 还原成一个 `"`」：
  ```js
  function splitQuoted(line, sep){
    var out=[], cur="", q=false;
    for(var i=0;i<line.length;i++){
      var ch=line.charAt(i);
      if(q){
        if(ch==='"'){ if(line.charAt(i+1)==='"'){ cur+='"'; i++; } else q=false; }
        else cur+=ch;
      }else{
        if(ch==='"' && cur==="") q=true;
        else if(ch===sep){ out.push(cur); cur=""; }
        else cur+=ch;
      }
    }
    out.push(cur); return out;
  }
  ```
- **取数时的顺序**也很关键：先按裸数值匹配，失败**才**去掉千分位逗号重试。
  反过来的话（先 `replace(',','')`）会把 `1,2` 和 `1,234` 混为一谈。
- **通用教训**：凡是「让用户自己导入数据」的功能，解析器要按**最宽容**设计——
  一行一个数 / 一行逗号分隔 / 多列 CSV / 带表头 / 带日期列 / 制表符 / 千分位 / 尾随空格换行，
  全都得能吃。不能让用户先手工清洗数据再喂进来。

### [P0] 排查「某块东西悄悄不显示了」，先查 try/catch 有没有吞异常

标签: 调试 / 异常 / 静默失败 / canvas / 绘图 / 视觉回归

- **症状**：切换皮肤后某几个面板的曲线整条消失，但**控制台零报错**，页面其他部分完全正常。
- **根因**：集中重绘函数写成
  ```js
  function redrawAll(){ for(var i=0;i<DRAWERS.length;i++){ try{ DRAWERS[i](); }catch(e){} } }
  ```
  某个 drawer 抛 ReferenceError 被空 catch 吃掉，那条曲线就永远画不出来，而且**所有错误检查都看不到**。
- **真实案例**：填充分支里写了 `g.globalAlpha = b.dim`，而 `b` 只是上一个循环的形参、此作用域根本不存在。
  `--fill=0`（不填充）时短路不进这段；一旦切到 `--fill=1` 的皮肤立刻抛错 → 曲线消失。
  于是这个 bug 藏了整整两轮才被发现。
- **纪律**：
  1. 空 `catch(e){}` 是负债。至少 `console.error('drawer#'+i, e)`，让测试脚本能把它当错误捕获。
  2. 视觉回归要**检查像素而不是检查流程**：读 `getImageData` 统计非背景像素数，
     比"函数跑了没报错"可信得多——曲线少画一条，页面上是看不出来的。

### [P1] 给元素加 id 之前，先查这个 id 有没有被用过

标签: DOM / id / 重名 / innerHTML / 锚点

- **案例**：给整行容器加锚点 `id="rowB"`，而内层面板容器原本就叫 `id="rowB"`，
  JS 一直用 `getElementById('rowB').innerHTML=...` 往里写面板。
- **后果**：`getElementById` 返回**外层**，`innerHTML` 一写就把整行的标题栏整个抹掉。
  症状很迷惑：导航还能跳，但那两行的标题凭空消失、搜索也搜不到该行的关键词。
- **纪律**：加 id 前先 `grep 'id="' 目标名`；命名上把「行/区」和「容器」分层，如 `rowB` / `gridB`。
  批量加锚点 id 时尤其要查——这类重名只在运行时才暴露，静态检查看不出来。

### [P0] 同一个文件不要并行发多个编辑

标签: 并行编辑 / 竞态 / 丢改动 / 工具

- **现象**：同一轮里并行发了 3 个编辑（改标题、改配色函数、改顶栏标签），
  返回全是 success，但事后核对发现**其中一个改动凭空消失了**，文件里还是旧内容。
- **原因**：并行调用各自基于**同一份旧快照**计算替换结果，后写入的把前一个的改动覆盖掉。
  工具只报告"我这个替换成功了"，不会知道别的调用同时也在写。
- **解法**：对同一个文件的多次编辑**必须串行**（一次改完再发下一次）。
  只有**互不相关的不同文件**才适合并行。
- **纪律**：编辑完一轮后，**用搜索复核每个改动是否真的落到文件里**，不要凭 success 回执当验收。

### [P0] 未命名

标签: CSS / 规范化 / mask / 验证

### 浏览器会规范化你写进去的 CSS 值 —— 验证时别拿"原始串"去匹配
`el.style.maskImage = 'radial-gradient(circle 196px at 5px 5px, ...)'` 写进去之后，
读回来是 `radial-gradient(196px at 5px 5px, ...)` —— **`circle` 关键字被丢掉了**。
- 后果：验证脚本用写死的完整模板做正则匹配，会把"其实已生效"误判成 `nomask`，
  于是去改本来没坏的代码（我这次就绕了两圈）。
- 规则：**断言要针对语义而非原串**。只捕获第一个逗号前的那一段，
  或改读 `getComputedStyle().maskImage`。
- 同类：`maskImage` / `webkitMaskImage` 在不同内核下可读性不一致 —— 两个名字都要试，
  都读不到再退到 computed style。

### [P0] 未命名

标签: canvas / 绘制顺序 / 加色 / 辉光 / 结构

### 先画结构，再画光 —— 加色辉光画在纹理之上会把一切冲平
- **现象**：地心画了 6 层细矿脉，洞口里却只剩一团奶油色渐变，完全读不出"地层"。
  以为矿脉太细，反复加粗加亮都没用。
- **原因**：绘制顺序是"矿脉 → 320px 加色核心辉光"。加色层覆盖在上，把细纹理**整体冲平**。
- **解法**：**先铺辉光、再把结构画在辉光之上**；辉光峰值同时从 0.34 降到 0.20。
  矿脉不透明度提到 `0.16 + k×0.66` 后立刻有质感。
- **纪律**：加色层（`globalCompositeOperation='lighter'`）永远应该是最后一道，或者被结构层压住。
  顺序错了，参数怎么调都是雾。

### [P0] ffmpeg 多输入默认选「第一个」音轨 → 想用新音轨必须显式 -map

标签: ffmpeg / 多输入 / -map / 音轨 / 截断 / -shortest

把新音频混进老视频（`ffmpeg -i old.mp4 -i new.wav ... -shortest`）时，ffmpeg 默认挑**输入0 自带的音轨**，
`-shortest` 于是按老音频时长走，**新音频被完全忽略、视频也没截短**（本轮把 46s 截 30s 时，两次输出都还是 46s）。
必须显式映射：`-map 0:v:0 -map 1:a:0`。

### [P2] 图片序列+音频双输入编码，没写 -r 会被推断成 25fps 丢帧

标签: ffmpeg / fps / 25fps / 帧率 / 丢帧 / 图片序列

`ffmpeg -framerate 30 -i f%05d.jpg -i a.wav -vf scale=... out.mp4` 输出可能变 25fps，
30fps 的帧被按 25fps 摊、末尾若干帧被 `-shortest` 丢掉。必须在输出侧补 `-r 30` 锁死帧率。

### [P1] 知识库站点的「发布上线」只能从 handbook 自己的 workspace 推

标签: sites / 发布 / workspace / appId / 域名绑定 / 知识库

`workbuddy_sites_deploy` 的发布环境是按**会话 workspace** 绑定的。AI 工作手册项目在 `2026-09-15-21-54-09`，
它的线上 app 预留域名（如 `ai-handbook-89460.app.workbuddy.host`，对外别名 `ai-handbook.app.workbuddy.host`）登记在那个 workspace 下。
在别的会话 workspace（如 `2026-09-17-10-21-45`）里跑 deploy：
- 传 `updateExistingApp:true` → 报「this workspace has no existing app to update」；
- 传任何 `domainPrefix`（含现有的 `ai-handbook-89460`）→ 工具在后面**追加随机后缀**当成新域名预占，再报
  「预留域名 ……未绑定到本次发布环境，为避免返回仍指向旧内容的链接，本次发布已停止」。
即：从非归属 workspace **无法覆盖更新既有线上链接**，只能建全新 app/链接。
→ 结论：要推 handbook / skill-catalog 线上，**必须在项目所属 workspace 里跑 deploy（带既有 appId）**；
跨 workspace 会话只能本地重建，不能上线。报错即停，不会留残留 app，可安全重试。

### [P0] 发布到 app.workbuddy.host 的权限是「按 workspace 绑定」的，跨 workspace 会话完全发不了

标签: sites / 发布 / workspace / app.workbuddy.host / 域名绑定 / 知识库 / 环境隔离

`workbuddy_sites_deploy` 的发布环境绑定在**会话所属 workspace** 上。实测：
- 在 handbook 的归属 workspace(`2026-09-15-21-54-09`) 之外（如 `2026-09-17-10-21-45`）跑 deploy：
  - 传 `updateExistingApp:true` → 「this workspace has no existing app to update」；
  - 传任何 `domainPrefix`（试过 `ai-handbook-live` 这种含旧前缀的、也试过完全无关的 `kb-yuehao-2026`）→
    一律报「应用预留域名 X.app.workbuddy.host 未绑定到本次发布环境，本次发布已停止」。
- 即：**非归属 workspace 对整个 `*.app.workbuddy.host` 域名都没有发布权**，连建全新 app 都不行。
→ 结论：AI 工作手册 / Skill 目录的线上更新，**只能在 handbook 所属 workspace 的会话里 deploy**（带既有 appId；
  旧 URL `ai-handbook.app.workbuddy.host` 别名不变）。跨 workspace 会话能做的只有本地 `sync_skills.py` 重建。
  报错即停、不留残留 app，可安全重试。本限制与「自动发布」铁律不冲突——铁律在该 workspace 内照常执行。

### [P1] md 转「暗色科技风阅读版 HTML」：模板 + 6 条必踩的坑（已固化成 md-to-reader-html skill）

title: 供应链仿真建模：order-up-to 目标水平要覆盖 L+R；批量订货的方差放大是 1/CV²
date: 2026-09-18
body: 做牛鞭效应仿真时，(1) 目标库存水平必须覆盖 提前期L+复查周期R，只按L+1算会在批量模式下出现缺货-补货自激振荡，造出文献中不存在的放大;(2) 需求标准差要用较长历史窗口估计，短窗sigma自身抖动会造成虚假放大;(3) 批量订货(每R期下一次单)会让订单变成脉冲串，方差比天然约等于1/CV²，需求CV=0.17时会算出几百倍的荒谬数字——真实零售需求CV应设0.3-0.4，且基线默认不启用批量。
---@@ITEM
type: method
title: 高校每日情报页取材：官网「通知公告」三栏 + 学生会公众号细则才是增量来源
date: 2026-09-19
body: 做「某大学每日情报页」这类自动化时，二级学院官网通常几天才一更，硬凑会编造。稳定增量来自四个源：① 本科生院「学生通知」栏（报名/考试/注册类最全）；② 学校官网「通知公告」栏（志愿者招募、后勤、网络维护）；③ 校团委官网「通知公告」栏（竞赛公示、社会实践、志愿）；④ 非官方学生会公众号（如「师师情报局」）——它常把官网一句话通知展开成《使用办法》全文细则，官网只发「请看附件」而细则才是学生真正需要的操作步骤。技巧：用 WebFetch 直连栏目 list.htm 命中率远高于 WebSearch（搜索引擎索引常滞后 1-2 天，会返回昨天的结果）。
---@@ITEM
type: method
title: 现场录音转会议纪要：本地 faster-whisper 分片并行，74 分钟音频 6 分钟出稿
date: 2026-09-19
body: 本机已有 venv（binaries/python/envs/default）装了 faster_whisper + ctranslate2，HF 缓存里有 small 模型（快照路径 C:\Users\lenovo\.cache\huggingface\hub\models--Systran--faster-whisper-small\snapshots\<hash>），直接复用别重新找。关键做法是"切段 + 多进程"而不是单进程跑长音频：ffmpeg 切 180s 片段（-f segment -segment_time 180 -ac 1 -ar 16000 -c:a pcm_s16le），ProcessPoolExecutor(max_workers=5) 每进程加载一份 WhisperModel(device="cpu", compute_type="int8", cpu_threads=3)，段内时间戳 + 段序号×180 合并。实测：单进程 small 是 9.6x 实时，5 进程并行 35 分钟录音 1 分 31 秒跑完（约 23x），75 分钟音频总耗时约 6 分钟。坑：① beam_size=5 比 1 慢一倍但中文质量提升有限，长音频用 1 够；② initial_prompt 里塞一份领域术语表（华为云/码道 CodeArts/昇腾/鲲鹏/openEuler/AgentArts/开源鸿蒙…）对专有名词纠错效果最明显；③ 后台命令即便 run_in_background 也可能因默认 timeout 中途失败且日志为空，长任务要显式给大 timeout；④ PowerShell 重定向出来的日志是 UTF-16，Read 会报 binary，得先 decode('utf-16') 转存 UTF-8。
---
@@ITEM
type: pitfall
title: Windows 上从 HuggingFace 下模型三连坑：symlink 权限 1314 / Xet 通道 401 / 官网被墙
date: 2026-09-19
body: 想下 faster-whisper 的 large-v3 / medium 提升转写质量，连踩三个坑。① 默认 snapshot_download 会先下 blob 再建符号链接，非管理员账户触发 OSError [WinError 1314] 客户端没有所需的特权 → 用 snapshot_download(repo_id=..., local_dir=<目标目录>) 直接落盘，不走 symlink。② 新版 huggingface_hub 默认走 Xet 存储（cas-server.xethub.hf.co），配镜像端点后必然 401 Unauthorized → 设 HF_HUB_DISABLE_XET=1 回退普通 HTTP。③ huggingface.co 本机直连被拒（WinError 10061），但 hf-mirror.com 通 → HF_ENDPOINT=https://hf-mirror.com。另外 pip 走清华源会 403，pypi.org 正常。若这些都通不下来，别死磕：small + 术语表 + 上下文校正已经够写会议纪要，模型下载失败不要卡住主线任务。
---
@@ITEM
type: method
title: 多段杂乱录音怎么归场次：内容首尾衔接法 + 幻灯片对齐法
date: 2026-09-19
body: 微信按"位置"命名的录音（东浩兰生上海世博展览馆(西门).m4a / 西门 2 / 地面停车场 2 …）文件名跟内容毫无关系，时长也五花八门。判断归属别按文件名，用两招：① 首尾衔接——A 段结尾"我想问问大家，做 AI 模型实验的时候有没有这种感觉"，B 段开头"稍微长一点的数据请求要等十几秒…"，语义严丝合缝，且 A 3:58 + B 34:49 合起来是一个完整演讲，说明录到一半被切段（换场/没电）；② 幻灯片对齐——把现场照片上的标题与录音里出现的句子互相对照，能把 4 张 PPT 精确挂到某一场（本次 4 张全部属于"以开放之云重塑 Agentic AI 开发新范式"这一场，因为照片标题"码道 AI 高效驱动项目迁移全流程""最佳实践中心"，与录音里 03:25 / 09:00 处讲的内容逐条对应）。最后纪要里单列一节"转写不确定项（待核对清单）"，把"转录原文 → 校正结果 → 依据"列成表，既详细又不编造。
---

@@ITEM sec=frontend level=P1 tags=md,html,阅读版,md2html,模板,表格,代码块,toc,打印

悦皓给的参考产物（`hc2026/生成物/AI入门指南与名词解释.html`）视觉很对，但我逐行读源码发现 5 个真实缺陷。**已把这些修好并固化成可复用技能**：`~/.workbuddy/skills/md-to-reader-html/`（SKILL.md + `scripts/md2html.py`，纯标准库、零依赖、不联网）。

**用法**：
```sh
C:\Users\lenovo\.workbuddy\binaries\python\versions\3.13.12\python.exe ^
  C:\Users\lenovo\.workbuddy\skills\md-to-reader-html\scripts\md2html.py "x.md" -o "生成物\x.html" ^
  --kicker "来源 · 场合" --chip "元信息"
```

**参考产物里的 5 个缺陷（现在都修了，别改回去）**：
1. `<title>` 拿**正文第一段**去猜 → 标签页显示成一个长句。正解：只取 `--title` 或 md 第一个 `# `。
2. md 的 `#` 同时出现在页头和正文 → **两个 h1**，像两份文档。正解：第一个 `#` 只做页头，正文跳过。
3. ``` 栅栏**没渲染**，页面上直接出现三个反引号当段落排。正解：必须进 `<pre><code>`（带 `language-*`）。
4. 引用块里的有序列表变成一排 `<ol><p>…</p></ol>`，**`<li>` 丢了**、编号错乱。正解：列表项统一包 `<li>`，嵌套按缩进递归。
5. 页脚写「见正文『待核对清单』一节」，但那一节**根本不存在**。正解：默认页脚只写来源文件名。

**「好看」来源于这 5 条设计基线**（照抄，别简化）：页头三段式（细字距 kicker → `clamp()` 大标题 → 胶囊 chip 行）；h2 左侧蓝竖条 + 下边框；表格包 `.tablewrap` 圆角滚动容器 + 行 hover；引用块用蓝→透明渐变 + 紫左边条；配色变量集中 `:root`（`--acc:#38bdf8` / `--acc2:#a78bfa` / 底 `#080b10` + body 冷光 `radial-gradient`）。

**额外白送的一条**：`@media print` 里重定义整套 CSS 变量，Ctrl+P 直接吐**可读白底 PDF**，不用另做一版浅色页（这条是从 oa-paper-translate 那个「深色页打印白底白字全隐形」的坑反推出来的）。

**验收口径**（交付前 grep 自查）：`<h1` 只出现 1 次；不残留 ``` ；`<li>` 数 ≥ 原文列表项数；`<title>` 不像一段话；目录锚点能跳。

@@ITEM
- sec: research
- title: 顶级视差滚动研究+构建工作流（parallax-research）
- why: 用户要求"研究顶级视差滚动站、学为什么能做成、列成果表、给检验网站"。拆出可复用框架：5 大"为什么有效"原理（运动视差本能/滚动即连续输入/注意力对比/因果控制感/揭示叙事）+ 工程真理（归一化进度/分层速度/lerp缓动/GPU合成/sticky scrub/velocity/WebGL深度带）+ 马哲读法（深度与运动对立统一、强度质量互变、CSS→JS→WebGL 否定之否定）。
- how: 对标母矿 = Apple(标准)/Active Theory(力场天花板)/Lusion/Cuberto(磁吸排印)/Awwwards 30合集；必引 ThreeUI(threeui.com·github.com/MengTo/threeui·npm @designcodeio/threeui，与 skill 同等待遇)；引擎 GSAP ScrollTrigger + Lenis。交付 = table.html(成果表含ThreeUI对照) + parallax-lab.html(零依赖demo:鼠标lerp/分层深度/sticky scrub/velocity反应式) + 视差原理笔记.md；通宵续跑用 recurring automation 每小时追加一个站点到 RESEARCH_LOG.md。
- pit: demo 默认零外部依赖（CDN 在中国网络/离线易失败）；prefers-reduced-motion 必须降级；克制 > 堆砌（restraint beats excess）。

### [P1] 未命名

- title: Python 调 ffmpeg 管道：stderr 绝不能用 subprocess.PIPE
- why: 用 `subprocess.Popen(..., stdin=PIPE, stderr=PIPE)` 从 Python 逐帧喂 rawvideo 给 ffmpeg 时，ffmpeg 每帧都往 stderr 写进度，64KB 管道缓冲写满 → ffmpeg 阻塞 → stdin 管道跟着满 → Python 的 `write()` 卡死。表现极具迷惑性：361 帧的活跑了 9 分钟才到第 40 帧，看起来像"算法太慢"，实际是死锁。
- how: `stderr` 直接传一个打开的文件对象（`open(path,"wb")`），并加 `-loglevel error` 减少输出。改完同一个任务从 >30 分钟降到 15 秒。
- pit: 同理 `stdout` 也要 `DEVNULL` 或文件；需要错误信息就在 `p.wait()` 之后读那个文件。

### [P1] 未命名

- title: 视频去鼠标：描边物体掩膜 + 时域中值的"幽灵箭头"
- why: 从 Kling/录屏视频里擦鼠标光标，两个连环坑让前三轮迭代全部白做。
- how:
  - **描边物体**：鼠标箭头是亮描边 + 暗填充。用 `|frame - bg|` 做差分掩膜时，只有"填充区"跟背景差异大，描边跟背景接近 → 结果只填了箭头内部的洞，描边原封不动留着，肉眼看箭头还在。修法：连通域先 `MORPH_CLOSE(31)` 填洞，再 `dilate(11, ×2)` 扩出去盖住描边，然后 `alpha = max(差分软alpha, 硬掩膜)` 强制满替换，最后 `GaussianBlur(σ=5)` 羽化。
  - **幽灵箭头**：时域中值取邻居帧估背景时，必须排除"鼠标位置跟当前重叠"的邻居。用欧氏距离 70px 不够——鼠标盒 68×98，相隔 71px 的邻居其箭头仍会落进当前 patch，于是中值里带着邻帧箭头，在旁边印出一个假箭头。改用包围盒判重叠：`if abs(dx)<100 and abs(dy)<130: 排除`。
  - **空间兜底别用大核中值填充**：`medianBlur(151)` 估出的背景是一大片的中值，会把亮区的中值糊到暗区，出现亮斑。估背景可以用它，但**填充要改 `cv2.inpaint(patch, mask, 30, INPAINT_NS)`**，从掩膜边界的真实像素扩散。
- pit: 验证指标会假阳性——平滑填充区反而跟箭头模板相关性更高（分数能从 0.81 涨到 0.95）。最终判定必须抽帧做原片/成品并排 ASCII 字符画，并且**两张图用同一个 0-255 固定映射**，不要用逐图 `NORM_MINMAX`（否则亮度不可比，会误判成"变亮了"）。

### [P1] 未命名

- title: Edge 无头冒烟验证「鼠标交互/动画网页」三技巧
- why: 写完零依赖交互动画页后要验证「JS 没炸 + WebGL 真画出来了 + 中部 section 排版正常」。本机无 playwright/puppeteer，只有 Edge。
- how:
  - **语法+着色器自检先行**：node 提取 script 标签内容跑 node --check；片元着色器源码必须 grep 反引号字符——shader 写在 JS 模板串里会被反引号提前终止 → 静默黑屏。shader 用数组 join 最稳。
  - **WebGL 是否真初始化**：msedge --headless=new --enable-unsafe-swiftshader --virtual-time-budget=6000 --screenshot 截图 + --enable-logging=stderr；出现 .WebGL-0x 开头的 CONSOLE 行 = 上下文真建了；无 [shader]/[link] warn = 编译链接通过。
  - **验证中部 section 别用 scrollTo**：--virtual-time-budget 与 window.scrollTo 组合会截出纯黑小图。改法：副本注入 style 把 hero 设 display:none，让目标区顶到首屏再截。
  - **100vh 长图陷阱**：--window-size=1440,3600 想截长图时，hero 的 min-height:100vh 会跟着涨到 3600px，整屏只有 hero——不是 bug，别误判页面坏了。
- pit: headless 跑 WebGL 必加 --enable-unsafe-swiftshader 否则纯黑；「GPU stall due to ReadPixels」是软件渲染正常提示不是错误；--disable-gpu 不影响 SwiftShader 软渲染出图。

### [P0] 无头截图里 CSS 动画的 delay 不推进 → 元素永远停在 opacity:0

标签: headless / CSS动画 / opacity / 截图 / 标题不显示 / virtual-time

- **症状**：页面里 `<h1>` 的 `class="in"` 确认已加上、CSS 语法正确、动画定义也对，
  但无头截图里**标题就是不可见**（统计出来 `bright% = 0`，而参考应有 5.4）。
- **根因**：`animation: fadeUp .95s ... .15s forwards` 后面的 **delay 依赖真实时钟**。
  headless 的 `--virtual-time-budget` 推进的是虚拟时间，**CSS 动画 delay 不跟着走**，
  元素就卡在 `opacity:0` 的初始态。
- **解法**：加一条兜底（对真机体验无影响）：
  ```js
  el.classList.add('in');
  setTimeout(()=>{
    if(parseFloat(getComputedStyle(el).opacity) < 0.99){
      el.style.animation='none'; el.style.opacity='1'; el.style.transform='none';
    }
  }, 1400);
  ```
- **附带**：标题的 `text-shadow` **不要叠两三层重黑晕**（`0 0 34px rgba(0,0,0,.85)` + `0 3px 44px rgba(0,0,0,.98)`），
  会把白字压成灰色，看起来像"没渲染"。用 `0 0 22px rgba(0,0,0,.55)` + `0 2px 30px rgba(0,0,0,.70)` 足够。

### [P1] 漏掉一个 CSS 闭合花括号，整个 <style> 之后的规则会全部失效

标签: CSS / 漏闭合 / 整个style失效 / 无样式 / 诊断

- **症状**：改完 `text-shadow` 后，页面**回退成无样式裸 HTML** —— 文字全裸、无布局、无字体、元素堆在左上角。
- **根因**：编辑时删掉了 `text-shadow: a, b;` 结尾的 `;`，**同时把 `}` 一起删了**。
  浏览器解析到未闭合的规则块，后面所有规则被吞。
- **诊断**：改完 CSS 立刻跑括号配对检查（数 `<style>`…`</style>` 之间的 `{` 与 `}`），一行脚本即可。
  这个症状**一眼可认**（裸 HTML），别去排查 JS / WebGL。
- **注意**：数 JS 的括号会被**模板字符串里的大括号**干扰，出现假 MISMATCH。
  判断 JS 是否有语法错误要用 `new Function(js)` 真解析，而不是数括号。

### [P1] Whisper 的两类固定幻觉：静音段复读 + 无语音处的"片尾语"

标签: ASR / whisper / 幻觉 / 静音段 / 视频旁白 / 课堂录音

- **类型 1｜静音/噪声段整段复读**：同一个短语连出几百字（`电影中的电影中的电影中的…`、
  `诺顿定律的方式。诺顿定律的方式。…`）。出现即说明该段**几乎没有有效语音**。
- **类型 2｜YouTube 片尾语**：中文任务里会吐出
  `请不吝点赞、订阅、转发、打赏支持明镜与点点栏目` / `中文字幕志愿者 XXX`。
  这是训练数据带来的固定幻觉，**不是现场有人说这话**。
- **注意**：课堂上老师**播放视频**时，视频旁白会被一起录进来（本次就录进了"中国电力工业发展140年"的
  视频解说）。要能区分**画外音 ≠ 讲者的话**，成稿时不采用，但在"待核对清单"里说明来源。
- **解法**：参数见上一条；成稿时把幻觉段整段丢弃，不要试图"修"它。

### [P1] 未命名

- title: 五类鼠标/滚动交互范式的原理与实现（+无头验证滚动中间态之法）
- why: 悦皓要求系统学习五类交互：①鼠标视线跟随 ②滚动固定主视觉重组 ③滚动章节覆盖与卡片堆叠 ④鼠标微缩景观视察 ⑤滚动角色环绕。要「为什么能做出来」，并产出可检验 demo。
- how:
  - **两条输入轴**：鼠标驱动（即时·可逆·控制感最强：视线跟随/微缩景观） vs 滚动驱动（单向·叙事·把滚动条当时间轴：主视觉重组/卡片堆叠/角色环绕）。四条统一真理：先归一化 0..1 → 再分层/分段 → 只平滑动画值不平滑滚动位置 → 单一 rAF 循环。
  - **视线跟随**：指针归一化 [-1,1] → mapRange 映射到窄幅（瞳孔 ±22px / 头 ±12°）→ lerp + rAF 节流；头 rotateX/Y 幅度大于瞳孔=二次运动。克制是关键。
  - **固定主视觉重组**：runway 300-420vh + sticky 100vh；p=clamp((scrollY-trackTop)/(trackH-vh))；0→0.6 归位(easeOut+每件错峰随机起始)/0.6→1 发光抬升；缓存 trackTop。
  - **章节覆盖/卡片堆叠**：卡 inset:0 同 footprint + transform-origin:top center（缩小时露顶）；enter=easeOut(clamp((p-i/n)/(1/n)))；已锁卡三通道 scale 1-d*0.055 + dim + rotateX d*5°，并上移 d*5.6% 露顶；速度 vel 驱动整叠后倾；reduced-motion 降级竖列。
  - **微缩景观**：perspective + 等距 rotateX(58)rotateZ(-38)；格子 translateZ(h) 顶亮侧暗造体积；容器 mask 上下渐隐做移轴(tilt-shift)；指针映射 rotateZ/rotateX；微缩错觉=俯视+光照方向+移轴景深三者同时成立。
  - **角色环绕**：angle=p*360；N 元素 rotateY(i*360/N)translateZ(R) 排环整体 rotateY；主体自转 -angle*0.42；preserve-3d 逐级传递；数学同源 three.js orbit camera(applyAxisAngle+lookAt)。
  - **无头验证滚动中间态（关键）**：headless 里 window.scrollTo 不可靠 → 用 Object.defineProperty(window,'scrollY',{get}) 接管成可控 mock；再把目标章之前内容 display:none 顶到首屏，喂 progress 即可截任意中间态。100vh/sticky 长图会退化 → 每章独立截图。
  - 产出：生成物/五类交互效果/index.html（36KB 零依赖五合一）+ 原理笔记.md；skill parallax-research 已补五类范式表与坑。
- pit: 鼠标类必须 rAF 节流别逐事件写 transform；首屏克制、绝不 scroll-jacking（滚动永远推动页面前进，pin 一拍后释放）；卡片堆叠 zIndex+transform-origin 决定覆盖 vs 顶开；等距角保持 55-62° 别正俯视。

### [P1] 未命名

- title: 引用 ThreeUI 模板/排版预设做网站（+ 只拉 tarball 探 npm 包结构之法）
- why: 悦皓要求「引用 ThreeUI 的网站设计模板，把这 5 个技巧都加上去」。ThreeUI 是 Three.js/WebGL 组件与完整网站模板目录。
- how:
  - **定位包**：官网 threeui.com；仓库 github.com/MengTo/threeui（Community 开源）；npm `@designcodeio/threeui`（latest 1.2.0）。deps: three128/three165；peer: react 18-19、three>=0.149。
  - **只拉 tarball 看结构（免装 54MB）**：从 registry.npmjs.org/@designcodeio%2Fthreeui 取 dist-tags.latest → dist.tarball；node 内置 zlib.gunzipSync 解 tar，逐条读 header（name 0-99 / size 124-135 八进制 / prefix 345-499），tarball 42.4MB、解包 55.3MB、726 条目。
  - **包内结构**：`lib-dist/package-components/*.js`（React 组件）、`lib-dist/assets/landing-pages/*.html`（完整 HTML 模板：kage / inner-green-3d / complete-shelf-v2 / meng-to-sketchbook / bestsellers-book-showcase）、`lib-dist/shaders/landing-pages/pageRecipes.js`（4 套排版预设）、`pageTypography.js`（usePageTypography/applyPageCustomization 注入机制）。
  - **真实排版预设（可直接引用）**：SYLVA（--ink 墨白 / 字重 300 / 字号 40-63-92 / 字距 -0.075em）、KAGE（--vermilion #e0231c + retone #ff5a3c ember / 30-46-72）、BESTSELLERS（#c3a47b / 184-325-420 巨字）、COMPLETE_SHELF（#c87046 / Iowan Old Style）。缩放单位 `--u`，字号写 calc(92*var(--u)) 再套 clamp。
  - **接入方式**：`npm install @designcodeio/threeui`；`import { AtTheHorizon } from "@designcodeio/threeui"` + `import "@designcodeio/threeui/style.css"`；渲染完整 HTML 的组件要把 lib-dist/assets 复制到 public 或用 sourceUrl/assetBaseUrl；Pro 组件走 `npx @designcodeio/threeui-cli add <name>`。
  - **产出**：生成物/threeui-模板站/index.html（40KB 零依赖，引用 SYLVA+KAGE 排版/配色 + ThreeUI 区块配方，五类技巧各一章 + Top Dock + 组件库网格 + CTA）、THREEUI.md（引用说明与接入）、_probe/extract 留档模板源码。新 skill: threeui-integration。
- pit: 别整包 install（42MB tarball）；包内字体/素材另有授权（ASSET-LICENSES/FONT-LICENSES）；组件名一律取自真实清单不杜撰；本机 Git Bash 偶发丢失 coreutils（dirname/mkdir/head/cd not found）→ 用 node 绝对路径做所有文件操作。

### [P1] 未命名

- title: 「像真实照片的自然景色」三配方 —— 层叠远山 + 一眼假排查
- why: 悦皓要的是真实感自然风景（原话「人类偏好自然景色，力求真实感」），判假标准是「明显是编的」。之前用 div/SVG 拼地形一眼假，因为真实感来自物理链条而非形状。
- how:
  - **几何**：多层层叠山脊，每层一块竖直平面（法线朝 +Z），纵向顶点重映射为「底边固定、上缘跟着山脊线走」，`t = 1 - (1-v)^2.7` 让顶部密集。实心几何，可受光可接雾，无透明排序问题。层宽必须按距离算 `visW = 2*dist*tan(fov/2)*aspect*1.3`，否则远层缩成一条。
  - **三条决定性配方**：① 绝不在脊线顶部衰减 z 起伏（会把山脊压成纸片）；② 表面起伏必须方向性 —— 用沿坡下切的沟壑（ridged 的 x 高频、y 压到 0.20 倍），各向同性噪声会读作沙丘/斑纹布，且低频权重要压过高频（n1*0.58 + gully*0.70）；③ 雾色必须对齐天空地平线色温，否则远山与天空脱节。
  - **天空一次做两件事**：canvas 画等距柱状图（天顶冷蓝 → 地平线暖褐 → 太阳径向光斑），同时赋给 `scene.background` 与 `PMREMGenerator.fromEquirectangular()` → `scene.environment`。零外部素材。卷云要用团块状低频（x 0.006 / y 0.010），高 y 频率会变横向扫描线。
  - **近景做剪影**：日落时前景本就背光，把最近层 tint 压到 0.015 量级只留脊线受光岩缘，比亮着的前景真实得多。
  - **相机前推优于人工平移层**：让相机真实前推 + 微升，近层自动放大得多、远层几乎不动，视差由透视自己产生，构图还稳。
- pit: ① 删变量后必须全局搜引用（删 `edge` 漏改 `setXYZ` → 整页 ReferenceError 黑屏）；② 层平移系数别凭感觉，`1/dist^0.62` 对 dist=76 只有 0.07，看着像"滚动没生效"，要用 `110/dist` 这类归一化；③ headless SwiftShader 的 `--virtual-time-budget` 压到 ~2600，给 14000 要软渲 ~840 帧必然超时；④ `execFileSync` 只返回 stdout，抓页面 console 要用 `spawnSync` + `--enable-logging=stderr`；⑤ 判断滚动是否生效要回读页面里 console.log 的 scrollN，光看 PNG 大小容易误判。

### [P1] 未命名

- 类型: 视觉/真实感验收
- 现象: 黄总反馈「装饰的像素非常低 = 真实感缺少」，即低分辨率糊感不真实。
- 根因: 几何细分低 / 法线&粗糙贴图分辨率低+噪声频率低+repeat少 / Bloom过强吃细节 / 材质层颗粒频率低 / setPixelRatio上限低。
- 解决: 见铁律11 已验证参数（几何512、法线粗糙1024×频×repeat4、Bloom 0.55/0.42/0.82、苔藓 15/42/68、dpr2.5）。
- 验收: 加 Laplacian 方差(清晰度)指标，改前<改后；勿只靠截图成功判定（铁律4）。
- 关联: 铁律11 / 铁律A+ / 铁律4 / webgl-terrain-hero 坑23


@@ITEM 图片生成一律用混元 Hy Image 3.5 preview（黄总偏好铁律 · 2026-09-23）
- 类型: 偏好/工具路由
- 偏好: 所有图片生成（文生图 / 图生图）默认使用腾讯混元 **Hy Image 3.5 preview**，不用其它生图模型。
- 事实: 发布 2026-09-22；模型 ID `hy-image-v3.5-preview`；统一文生图+图生图；单次最多 5 张参考图；最高 2K；盲测对 Hy Image 3.0 胜率 +30%；中文文字渲染是长项。
- 免费窗口: 发布起两周 ≈ 2026-10-06（Miora 渠道官方明确至 2026-10-07）；窗口后腾讯云 API 0.15 元/张，仅计输出图、参考图免费。
- 调用: ① 会话内 miora_text_to_image / miora_edit_image（先 connect_cloud_service 取临时密钥）② 内置 ImageGen（参数含混元专属字段 footnote/revise）③ 腾讯云 API hy-image-v3.5-preview。
- 注意: 内置 ImageGen 可能按平台额度计费（约 5-10 credits/张），调用前先说明；纯免费优先 Miora。临近 10-06/07 主动提醒黄总。

### [P1] 未命名

- 类型: 事实/方法论/参数
- 背景: 黄总要做「搬 ThreeUI 免费组件 → 拆解 → 复刻 → 迭代 → 一键套皮」的长期项目，工作台落在 生成物/ui-workbench/index.html。
- 事实（KAGE 模板 kage.html 243,963 B 实测，非估算）:
  - 5 章节 hero/gate/pathways/lessons/eternity，data-cam 0..4；progressFor(y) 产出**章节级连续进度 0→4**（不是 0→1），anchors 强制单调递增。
  - 相机 PerspectiveCamera FOV 36 / near .35 / far 220；FogExp2(0x050a0e, .0168)；background 0x060a0d；clearColor 0x05070a；PCFSoftShadowMap。
  - 前景 17 个 .fg-el 真实 PNG（temple-wall / sakura-branch 等）+ data-fg-in 左右入场 + fg-sway 摆动 → 靠**遮挡**出深度，比纯 3D 便宜。
  - 缓动 damp(cur,to,rate,dt)=lerp(cur,to,1-exp(-rate*dt)) 帧率无关；smoothstep；easeOut=1-(1-t)^3。
  - 降级三开关 WANT_POST / DPR_CAP / WANT_SHADOW，?nogl=1 可关 WebGL。
  - 装饰层 #vignette + #grain + #cursor + #pre；mix-blend-mode 2 / backdrop-filter 4；无 gsap/lenis。
  - token: --ink #05070a / --ink-2 #0a0e12 / --bone #dfe7e0 / --bone-dim #aab4ad / --muted #78837c / --vermilion #e0231c / --ember #ff5a3c / --gold #c9a24a / --ease cubic-bezier(.22,.61,.36,1)。字体 Onest + NotoJP + Wordmark。
- 方法论（规划升级要点，防坑）:
  1. 成品态源码有幸存者偏差 → 必须补参数取值范围与敏感度，用**消融实验**还原因果，没证据的「为什么」不入库。
  2. **手写代码类禁止伪造提示词**，只出「设计规格书」；只有生成式视觉描述才出 prompt。
  3. 组件 → 网站之间缺 **token 层**，缺了它一键换风格/跨站复用全部做不出来（ThreeUI 自己用 --u + retone() 实现）。
  4. 单一来源会过拟合 → 对标站按**技法维度**交叉索引；「超越」= 同屏 A/B 盲测胜率 > 70%。
  5. 一键套皮分三级：L1 同源站（100% 可控）/ L2 语义角色→候选选择器→token 映射（覆盖 60~80%，浏览器扩展注入）/ L3 截图重写。别指望一段通用 CSS 通吃。
  6. L2 已知坑：暗色皮肤下白色 logo 与图片会消失（需反色保护）、表单元素受 UA 默认样式高优先级影响、层级权重冲突需 !important 强化版。
- 关联: ui-replication-lab / threeui-integration / web-design-pipeline / ui-style-lab / 铁律2

## 09. 项目档案

_16 个历史项目的可复用资产_

### [P1] 历史项目索引与可复用资产

标签: 档案 / 清单

| 项目目录 | 内容 | 可复用资产 |
|---|---|---|
| `华师大nb` | 华师大信息小灵通情报页 + 每日自动化 | `ecnu-daily.html`、`_check.js`、发布链路、新生事务核实资料 |
| `AI前沿` | AI 前沿小灵通情报页 + 每日自动化 | `ai-daily.html`、板块结构、竞赛截止 tag |
| `军训视频` | 军训合唱比赛视频 V1→V7 | `build_v9..v15.py`、7 版成片、全部素材、锚点表 |
| `2026-09-12-22-41-44` | 简历 + 作品集网站 | `index.html`(348KB)、`portfolio/` React+Vite、真实素材库 |
| `2026-09-13-21-38-41` | 黑客松组队/分工/任务三件套 + 音频转写 | `hackathon-*.html`、`transcribe.py`、赛事节点、方向二方案 |
| `2026-09-14-12-27-45` | 交大《动手学大模型》本地化 | `dive-into-llms/` 11 章 97MB、`download_videos.py` |
| `2026-09-14-17-22-32` | Bellaro 奢华腕表页 | `bellaro/index.html` 2D + 3D 两版、机芯 SVG |
| `2026-09-15-00-00-15` | 腕表 × 简历融合页 | `桌面\\hyh-dial\\index.html`、指针选模块、视差滚动 |
| `2026-09-10-22-34-04` | 灵感中心 | Node 原生 http + 单文件前端 + JSON 持久化 |

其余 `2026-09-11-*` 系列为空或临时会话。

### [P1] 简历数据提取与复用

标签: 简历 / 作品集 / 资产

作品集线上 JS bundle 里能抓到完整简历数据对象 `wr`（已成功提取过一次）：
姓名 / 角色 / 联系方式 / 4 段自我介绍 / 学历 / 4 项 stats / 6 场活动 / 4 个项目 / 5 组技能 / 2 项荣誉 / 6 条优势。

**改内容最省事的路径**：
- 作品集：改 `portfolio/src/data/content.js`，再 `build.cjs` 重建 dist + 重生成 `serve-range.cjs`
- 单文件简历：改 `index.html` 里 `<script>` 中的 `const resume = {...}`，字段留空会自动隐藏对应模块

图片替换：HTML 里放 `__AVATAR_B64__` / `__CERT_B64__` 占位，用 Python 读 `.b64` 文件替换。
（也可从 HTML 里正则抽 `data:image/jpeg;base64,...` 重新生成 b64 缓存）

### [P2] 黑客松 DataClawHub（进行中，勿丢上下文）

标签: 黑客松 / 进行中

华东师大 AI 智能体校园黑客松（DataClawHub），报名 2026-09-21 截止。

**已定方向**：赛题二 / 方向二 —— 供应链多级库存智能协同与补货决策。

悦皓的打法：前期搜集+整理信息，后期 PPT + demo（demo 交给表达能力强的同学当"演示官"）。

已给的关键建议（别推翻重来）：
- **「AI 助手」是外壳不是方案**，评委要的是"替谁做了什么决定"
- 定义为**协同补货 Agent**：数据留本地 → 只上传聚合需求信号（隐私边界）→ Agent 全局预测+补货决策 → 产出①可执行补货计划 ②仿真验证对比
- 大模型只做**理解与解释**，**不做数值决策**；数值由预测模型+优化器+仿真器出
- 隐私别真做联邦学习，用「聚合信号/加噪/参数化」+ 说清边界即可
- **先写仿真器再写算法** —— 仿真器既是评估器又是 demo 本体
- demo 现场不让大模型实时生成数字，走预跑结果

**无线下答辩，线上提交**。交付四件套：
1. 方案文档 PDF（结论前置、每图一句话结论、附录答三问）
2. 2–3 分钟演示视频（字幕+旁白）
3. 可交互原型（单文件 HTML / 在线地址，评委点开就能玩）
4. DataClawHub 制品（人气奖）

demo 杀手锏：**同一批数据跑两遍对比** —— 成本/缺货率/周转率差距数值化，同时喂 PPT 和路演。
材料必须**自解释**，倒金字塔结构，第 1 页甩效果数字。

待办：队员名单与技术栈未确认；「晋级后统一实测期」日期官网未公布，别当结论用。

### [P1] 本机 44 个 Skill 已按用途分为 8 类，索引化方便取用

标签: skill / 分类 / 目录 / 取用 / 知识库

- **分类（8 域）**：网页与浏览器自动化(8) / 文档与办公(12) / 金融与数据(4) /
  设计与媒体制作(6) / 地图与合规(1) / Skill 管理与元能力(8) / 写作与提示词(3) / 交付纪律(2)。
- **怎么改**：分类逻辑写在 `_scan/build.py` 的 `SKILL_CATS` + `SKILL_TRIGGER` 两个字典里
  （skill 名 → 类别、skill 名 → 一句话触发场景）。改这里、重跑 build.py 即可，不要手改产物。
- **产物（自动生成）**：
  1. `knowledge-base/llms.txt` 第 10 章「Skill 分类索引（速查）」+ 第 11 章「Skills 全文（按类分组）」。
     后续 AI 读 `llms.txt` 时直接按类别定位。
  2. `knowledge-base/SKILLS_CATALOG.md` —— 人类可读的轻量目录（速查总表 + 逐类清单，含触发场景与来源）。
  3. `knowledge-base/assets/data.js` 的 `KB.skillCats` 字段（供网页版以后渲染分类）。
- **校验**：build.py 会打印 `skill cat coverage: listed=N missing=[...] orphan=[...]`，
  理想是 listed=44、missing 与 orphan 都为空（说明无遗漏、无未分类孤儿）。
- **使用约定**：找 skill 时**先看类别再匹配触发场景**，别在平铺列表里逐个翻。

### [P2] 单人公司（黄哥导演 + AI 码农）· 2026-09-22 确立并跑通第一单

标签: 单人公司 / AI员工 / 岗位卡 / 接单 / 视觉交付 / 2026-09-22

- **定位**：黄哥当导演（出审美、定义效果、验收），AI 员工当码农（把效果变代码），调度中枢=小七。
  先接单服务起步，目标服务+产品两种都做。客户=做 UI 设计、有审美但写不出代码的人（首位=黄哥朋友）。
- **第一单**：复刻 Lithos 风格页（近黑底 + 顶光 3D 岩壁 + 缝隙熔岩 + 白衬线斜体大标题 + 视差滚动）。
  用 `webgl-terrain-hero` skill 实现，`生成物/Lithos风格首页/index.html` 已交付（5 轮迭代收敛）。
- **沉淀文档**（都在 `生成物/单人公司/`）：`00_公司总览.md` / `01_开发部0号员工岗位卡.md` / `02_第一单任务书.md`。
- **岗位卡三要素范式**（给新 AI 员工照抄）：① 角色（你是谁）② 工具/知识（开局必读哪些 skill/资源）③ 边界（什么能拍板/什么必须问）。
- **铁律呼应**：任何 AI 接手视觉前端任务，开头必须全量投喂视觉铁律 A/A+/B + `webgl-terrain-hero` SKILL.md + ThreeUI 两网址，不凭空造、不拼 div/SVG 地形。

---

## 10. Skill 分类索引（速查，共 70 个）

按用途分为 8 类。找 skill 先定位类别，再按触发场景匹配。

### 网页与浏览器自动化（10）

- **agent-browser** — 浏览器自动化：打开网页、截图、抓内容、点击、填表、测流程
- **playwright-cli** — 浏览器交互测试 / 填表 / 截图 / 数据抽取
- **web-access** — 所有联网操作：搜索、抓取、登录后操作、读动态渲染页
- **web-design-engineer** — 用 HTML/CSS/JS/React 构建或重设计视觉成品（页面/仪表盘/原型/动效/数据可视化）
- **frontend-design** — 前端视觉设计（风格/版式/配色）
- **frontend-dev** — 前端开发（组件/逻辑/工程化）
- **html-deploy** — 单页 HTML 发布到 htmlcode.fun 拿公网链接
- **edgeone** — 单页 HTML 部署到腾讯 EdgeOne Pages 拿公网链接（免登录/密钥）
- **ui-style-lab** — 全自动「UI/UX 视觉风格探索实验室」——围绕一个对标基准，自主生成 3 个极端变体、自我批判、选出赢
- **nature-texture-engine** — 自然质感引擎 NatureTex——把「苔藓地面 / 针叶树 / 云海」三套真实感算法做成可迁移的 th

### 文档与办公（16）

- **tencent-docs-routing** — 处理本地 Office/WPS 文件前的路由分发
- **tencent-docx** — Word 文档创作与美化（研报/论文/公文/合同）
- **tencent-pptx** — 生成专业 PowerPoint 演示文稿
- **tencent-local-office-edit** — 本地 Office/WPS 实时读写编辑（所见即所得）
- **tencent-docs-sheet-generation** — 从零生成 Excel 工作簿
- **tencent-docs-sheetagent** — Excel 读写/分析/图表/透视表
- **pptx** — PPT 通用生成（主题/大纲/数据驱动）
- **pdf** — PDF 阅读/合并/拆分/旋转/文本抽取
- **pdfkit-py** — 纯 Python PDF 工具箱（加密/OCR/表单/水印/书签）
- **xlsx** — Excel 全生命周期（公式/图表/透视/清洗）
- **资料库** — 在线文档/数据表/dashboard/看板/网盘/协作轻发布
- **drawio** — 原生可编辑流程图/架构图，导出 PNG/SVG/PDF
- **md-to-reader-html** — Markdown 长文档转单文件暗色科技风阅读版 HTML（目录/表格/打印转浅色）
- **oa-paper-translate** — 把学术论文（单篇或一批）抓取开放获取全文并翻译成中文单文件 HTML
- **local-asr-meeting-minutes** — 把本地音频/视频（m4a/mp4/wav，含微信现场录音、会议录音、访谈、讲座）批量转写成带时间码的中文
- **video-cursor-removal** — 从视频中检测并移除鼠标光标（及伴随阴影/光晕），输出去鼠标版本，保留音频

### 金融与数据（4）

- **wb-finance-skill** — 金融场景总入口（股票/基金/ETF/宏观/财报/量化）
- **westock-data** — 金融行情/财报/研报/新闻/公告/产业链数据查询
- **westock-tool** — 选股/选基筛选（条件/策略/标签/事件/排行）
- **neodata-financial-search** — 自然语言金融数据搜索

### 设计与媒体制作（19）

- **3D模型与视频特效** — 3D 生成、图片/视频模板特效
- **ffmpeg-cn-video-subtitle** — 中文视频字幕/歌词烧录、按秒换素材、drawtext 排错
- **h3-prompt-writing** — MiniMax H3 视频生成提示词编写
- **image-processor** — 图片本地处理（压缩/水印/格式/裁剪/灰度）
- **apple-design** — Apple 风 UI 设计评审（流体交互/弹簧动画/毛玻璃）
- **ardot-design-router** — Ardot 设计助手调度（意图分类）
- **ui-replication-lab** — 把顶级站（ThreeUI 系 / Active Theory / Lusion / Cuberto 等）拿来深度拆解、沉
- **style-moodboard-calibration** — 风格词校准与图源抓取（360 图片接口 → 拼图审图 → 点选标定）
- **web-motion-craft** — 网页 3D 动效技法库（四族十六技法 + ThreeUI 组件索引 + 生产级工程铁律）
- **parallax-research** — 顶级视差滚动研究（五类范式 + 为什么有效 + 检验 demo）
- **webgl-terrain-hero** — 用 Three.js 做真实感 3D 地形 / 森林 / 自然风景 hero；含质感三件套（地面苔藓四层 · 树沿枝生长+逆光透光 · 云海云丘三贴图）与 window.__scene 逐个隐藏排查法
- **audio-transcript-format** — 语音转写文本智能整理：分句、填充词清理、标点修复、段落分割、术语统一、待办/截止/异议/决策提取，多编码
- **funasr-asr** — Local speech recognition using Alibaba DAMO Academy'
- **local-audio-transcribe** — 本地(无云端、无预算)将音频文件(m4a/mp3/wav 等)转写为带时间戳的 UTF-8 文本
- **meeting-notes** — 会议纪要整理员
- **openai-whisper-api** — Transcribe audio via OpenAI Audio Transcriptions API
- **voice-to-minutes** — 录音→文字→条理稿，一条龙自己干完：内置离线语音转写（Whisper，本地运行、不填密钥、不上传第三方）
- **web-design-pipeline** — 黄总制定的「网站设计任务标准工作流」（2026-09-22 起·常驻·所有网页/视觉模仿任务默认遵守）
- **mood-metric-design** — 当用户说「要 XX 感的网页/页面/视觉」「生成一个氛围感/高级感/科技感的页面」，或给了风格参考图/参

### 地图与合规（1）

- **geo-map-compliance-guard** — 任何地图生成/可视化/路径/定位服务的中国地图数据合规

### Skill 管理与元能力（10）

- **skill-creator** — 创建/更新 skill
- **find-skills** — 发现/安装 skill
- **marketplace-skill-installer** — 从推荐市场安装 skill
- **expert-manager** — 专家包全生命周期管理
- **recommend-experts** — 推荐专家
- **recommend-connectors** — 推荐连接器/应用/API/MCP
- **anti-distill** — skill 防蒸馏（清理核心专有知识）
- **darwin-skill** — 自动优化 skill（8 维评估 + 爬山）
- **kb-append** — 把本次任务新学到的方法/坑/事实追加进「悦皓的 AI 工作手册」知识库并重建站点
- **meeting-notes-distill** — >

### 写作与提示词（4）

- **de-ai-writing** — 去 AI 味/废话、Agent 提示词精简调优
- **prompt-engineering-expert** — 提示词工程/自定义指令设计专家
- **ctx** — 会话上下文长度/token 占用/压缩上下文
- **ma-thinking** — 马克思主义哲学思维框架——用矛盾分析法、质量互变、否定之否定、实践第一等原理进行任务拆解、设计批判与迭代

### 交付纪律（3）

- **delivery-no-pseudoblock** — 交付前伪阻断闸门（D1–D12 逐项过闸）
- **impeccable** — 交付质量（impeccable）
- **collab-playbook** — 黄总的协作总纲与调度手册：分期出图（先出2张）、三层判层、两条红线、三条刹车、开工四问、对标四铁律、复刻验证三问、交付形态硬规则

### 其他（待归类）（3）

- **local-asr** — |
- **meeting-minutes-generator** — Turn meeting transcripts, notes or chat logs into st
- **threeui-integration** — 拉取并引用 ThreeUI（threeui.com / @designcodeio/threeui）的

---

## 11. Skills 全文（70 个）

本机已安装或曾生成过的 Skill 全文，按用途分类。

### 网页与浏览器自动化

#### agent-browser

- 来源: 内置/市场
- 说明: Use this skill when the user needs browser automation, including opening web pages, taking screenshots, extracting page content, clicking elements, filling forms, or testing web flows. This skill uses the open source vercel-labs/agent-browser CLI and supports macOS, Linux, and Windows x64.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\codebuddy-plugins-official\agent-browser\1.3.0\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `.in_use/11012`, `.in_use/17976`, `.in_use/28812`, `.in_use/32240`, `.in_use/34544`, `.in_use/41900`, `.in_use/42840`, `.in_use/48752`, `.in_use/48900`, `.in_use/50320`, `README.md`

```markdown
# Agent Browser

Use `agent-browser` CLI for full browser automation tasks. It is suitable when a page needs JavaScript rendering, real browser interaction, screenshots, or form automation.

Upstream project: https://github.com/vercel-labs/agent-browser

## Platform Support

`vercel-labs/agent-browser` provides native builds for:

- macOS ARM64 / x64
- Linux ARM64 / x64
- Windows x64

Windows support in this skill targets Windows 11 x64 with PowerShell and Node.js 18+.

## Prerequisites

- Node.js 18+
- npm available in PATH
- Network access to install `agent-browser` and download Chromium
- About 500 MB free disk space for Chromium
- **The `node` binary on PATH must actually execute code**, not just print a version. `agent-browser` spawns a Node child process internally; if that Node is broken, the daemon will crash with no useful output even when `agent-browser --version` works.

  Quick check:
  ```bash
  node -e "console.log('ok')"
  ```
  If this does not print `ok` (SIGILL / exit 133 / any crash), the Node on PATH is unusable. Fix it, or run `agent-browser` with a known-good Node prepended to PATH for that command only:
  ```bash
  PATH="/path/to/working-node/bin:$PATH" agent-browser open <url>
  ```
  Inspect which Node would be picked up with `which -a node`.

## Installation

> Inside the CodeBuddy marketplace, `scripts/setup.sh` auto-runs these steps on first load. The commands below are for manual setup or reinstall.

### Windows PowerShell

```powershell
npm install -g agent-browser
agent-browser install
```

### macOS / Linux

```bash
npm install -g agent-browser
agent-browser install
```

### Linux missing dependencies

```bash
agent-browser install --with-deps
```

## Required Command Sequence

The current upstream `agent-browser` CLI does not require a separate `launch` command. `agent-browser open <url>` starts or connects to the browser daemon automatically.

Always follow this order:

1. Open target URL.
2. Wait for page load when needed.
3. Inspect page with `snapshot` or `snapshot -i`.
4. Interact with the page.
5. Close browser when done.

```bash
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
```

## Session Model

`agent-browser` runs a persistent background daemon. Understand this before planning multi-step tasks:

- The first `agent-browser open` starts a daemon; subsequent commands auto-connect to the same daemon.
- Within one session, cookies, localStorage and login state are preserved across commands.
- Multiple `open` calls in the same session navigate the existing browser (no need to close between URLs).
- `agent-browser close` ends the daemon. Only call it when the whole task is finished, not between steps of the same task.

Implication: for a task that visits N URLs, do **one** `open ... snapshot ...` chain per URL and **one** `close` at the very end, not N `open`/`close` pairs.

## Execution Principles

Apply these when running command sequences, especially in multi-step tasks:

- **`close` is mandatory in finally**: whether the task succeeds or fails midway, always run `agent-browser close` at the end to avoid zombie daemons and leaked Chromium processes.
- **`wait` is optional and degradable**: `wait --load networkidle` can hang on SPAs that never go idle. If a wait stalls, fall back to `wait --load load` or skip waiting and `snapshot` directly. Do not block the whole task on `wait`.
- **Reuse the daemon**: in the same task, do not `close` between intermediate steps. Open once, navigate/interact multiple times, close at the end.
- **Prefer `snapshot -i` for interaction**: when you need to click or type, get interactive element IDs first via `snapshot -i`, then act on them. Do not guess CSS selectors blindly.
- **Use agent-browser's own install channel**: for Chromium, runtime, or dependency issues, stay inside agent-browser's own tooling — `agent-browser install`, or the `playwright-core` CLI bundled under `$(npm root -g)/agent-browser/node_modules/playwright-core`. Do not run `npx playwright install` in parallel; it can fetch a revision that does not match what agent-browser expects and may time out downloading browsers agent-browser never uses.
- **Fail fast on environment errors**: if the very first `open` fails with daemon / Chromium / SIGILL errors, do not retry the same command repeatedly. Verify the Prerequisite Node check, then consult `references/troubleshooting.md`.

## When NOT to Use

`agent-browser` launches a real Chromium and consumes hundreds of MB plus a few seconds of cold start. Pick the lighter tool whenever possible:

| Need | Recommended tool |
|------|------------------|
| Fetch static HTML, plain text, or markdown of a page | WebFetch |
| Call a JSON / REST API | curl, fetch, or HTTP client |
| Read content already present in raw HTML | WebFetch |
| Render JavaScript-driven pages before reading | agent-browser |
| Click, type, login, or any multi-step interaction | agent-browser |
| Take a visual screenshot for review | agent-browser |
| Reproduce a real user flow end-to-end | agent-browser |

Rule of thumb: if `curl <url>` already contains the target content in plain HTML, do not start `agent-browser`.

## Essential Commands

| Command | Description |
|---------|-------------|
| `agent-browser open <url>` | Start or connect to the browser daemon and navigate to a URL. |
| `agent-browser wait --load networkidle` | Wait until network activity is idle. Useful after opening dynamic pages. |
| `agent-browser snapshot` | Get page content as text. |
| `agent-browser snapshot -i` | Get page content with element IDs for interaction. |
| `agent-browser screenshot` | Take a screenshot. |
| `agent-browser click <selector>` | Click an element. |
| `agent-browser type <selector> <text>` | Type text into an input. |
| `agent-browser close` | Close browser and free resources. |

## Common Workflows

### View webpage content

```bash
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
```

### Take screenshot

```bash
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser screenshot
agent-browser close
```

### Fill form and submit

First get interactive element IDs:

```bash
agent-browser open https://example.com/login
agent-browser wait --load networkidle
agent-browser snapshot -i
```

Then interact with stable selectors or element IDs:

```bash
agent-browser type "#username" "myuser"
agent-browser type "#password" "mypassword"
agent-browser click "#submit"
agent-browser close
```

### Extract data from a JavaScript-rendered page

```bash
agent-browser open https://example.com/data
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
```

## Windows Notes

On Windows, prefer PowerShell for installation and verification:

```powershell
npm install -g agent-browser
agent-browser install
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
```

If the command is not found after installation, restart PowerShell or confirm npm global bin is in PATH:

```powershell
npm config get prefix
```

## Troubleshooting

For environment problems (daemon won't start, Chromium revision mismatch, SIGILL / Exit 133, install timeouts, etc.), see [`references/troubleshooting.md`](./references/troubleshooting.md). It is organized by symptom so you can diagnose against the actual error message instead of following a fixed script.

Quick checks before going there:

- `agent-browser` not found after install: restart shell, confirm npm global bin is in PATH (`npm config get prefix`).
- Linux browser launch missing system libs: `agent-browser install --with-deps`.
- Always run `agent-browser close` when a task ends, even on failure paths.
```

#### playwright-cli

- 来源: 内置/市场
- 说明: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\codebuddy-plugins-official\playwright-cli\0.1.0\skills\playwright-cli\SKILL.md`
- 附带文件: `references/request-mocking.md`, `references/running-code.md`, `references/session-management.md`, `references/storage-state.md`, `references/test-generation.md`, `references/tracing.md`, `references/video-recording.md`

```markdown
# Browser Automation with playwright-cli

## ⚠️ Critical: First-time Setup

If `playwright-cli` is not found in PATH, locate it dynamically:

```bash
# Find the actual path (works across macOS/Linux, Homebrew/nvm/fnm)
PCLI=$(command -v playwright-cli || npm bin -g 2>/dev/null | xargs -I{} echo {}/playwright-cli)
# If still not found, install:
npm install -g @playwright/cli@latest
```

> **Do NOT hardcode** paths like `/opt/homebrew/bin/playwright-cli`. Different systems have different npm global bin paths.

## ⚠️ Critical: Snapshot Output

By default, `snapshot` saves output to **files** in `.playwright-cli/` directory (not stdout).

**To read snapshot results, you MUST cat the output file:**

```bash
playwright-cli snapshot
# Then read the latest snapshot file:
cat .playwright-cli/page-*.yml | tail -200
# Or use a specific filename:
playwright-cli snapshot --filename=snap.yaml
cat .playwright-cli/snap.yaml
```

**Alternatively**, set output mode to stdout in a config file `playwright-cli.json`:
```json
{ "outputMode": "stdout" }
```

## Quick start

```bash
# open new browser
playwright-cli open
# navigate to a page
playwright-cli goto https://playwright.dev
# take snapshot to get element refs
playwright-cli snapshot
# read the snapshot output (saved to .playwright-cli/ directory)
cat .playwright-cli/page-*.yml
# interact with the page using refs from the snapshot
playwright-cli click e15
playwright-cli type "page.click"
playwright-cli press Enter
# take a screenshot
playwright-cli screenshot
# close the browser
playwright-cli close
```

## Commands

### Core

```bash
playwright-cli open
# open and navigate right away
playwright-cli open https://example.com/
playwright-cli goto https://playwright.dev
playwright-cli type "search query"
playwright-cli click e3
playwright-cli dblclick e7
playwright-cli fill e5 "user@example.com"
playwright-cli drag e2 e8
playwright-cli hover e4
playwright-cli select e9 "option-value"
playwright-cli upload ./document.pdf
playwright-cli check e12
playwright-cli uncheck e12
playwright-cli snapshot
playwright-cli snapshot --filename=after-click.yaml
playwright-cli eval "document.title"
playwright-cli eval "el => el.textContent" e5
playwright-cli dialog-accept
playwright-cli dialog-accept "confirmation text"
playwright-cli dialog-dismiss
playwright-cli resize 1920 1080
playwright-cli close
```

### Navigation

```bash
playwright-cli go-back
playwright-cli go-forward
playwright-cli reload
```

### Keyboard

```bash
playwright-cli press Enter
playwright-cli press ArrowDown
playwright-cli keydown Shift
playwright-cli keyup Shift
```

### Mouse

```bash
playwright-cli mousemove 150 300
playwright-cli mousedown
playwright-cli mousedown right
playwright-cli mouseup
playwright-cli mouseup right
playwright-cli mousewheel 0 100
```

### Save as

```bash
playwright-cli screenshot
playwright-cli screenshot e5
playwright-cli screenshot --filename=page.png
playwright-cli pdf --filename=page.pdf
```

### Tabs

```bash
playwright-cli tab-list
playwright-cli tab-new
playwright-cli tab-new https://example.com/page
playwright-cli tab-close
playwright-cli tab-close 2
playwright-cli tab-select 0
```

### Storage

```bash
playwright-cli state-save
playwright-cli state-save auth.json
playwright-cli state-load auth.json

# Cookies
playwright-cli cookie-list
playwright-cli cookie-list --domain=example.com
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123
playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
playwright-cli cookie-delete session_id
playwright-cli cookie-clear

# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear

# SessionStorage
playwright-cli sessionstorage-list
playwright-cli sessionstorage-get step
playwright-cli sessionstorage-set step 3
playwright-cli sessionstorage-delete step
playwright-cli sessionstorage-clear
```

### Network

```bash
playwright-cli route "**/*.jpg" --status=404
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
playwright-cli route-list
playwright-cli unroute "**/*.jpg"
playwright-cli unroute
```

### DevTools

```bash
playwright-cli console
playwright-cli console warning
playwright-cli network
playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
playwright-cli tracing-start
playwright-cli tracing-stop
playwright-cli video-start
playwright-cli video-stop video.webm
```

### Install

```bash
playwright-cli install --skills
playwright-cli install-browser
```

### Configuration
```bash
# Use specific browser when creating session
playwright-cli open --browser=chrome
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge
# Connect to browser via extension
playwright-cli open --extension

# Use persistent profile (by default profile is in-memory)
playwright-cli open --persistent
# Use persistent profile with custom directory
playwright-cli open --profile=/path/to/profile

# Start with config file
playwright-cli open --config=my-config.json

# Close the browser
playwright-cli close
# Delete user data for the default session
playwright-cli delete-data
```

### Browser Sessions

```bash
# create new browser session named "mysession" with persistent profile
playwright-cli -s=mysession open example.com --persistent
# same with manually specified profile directory (use when requested explicitly)
playwright-cli -s=mysession open example.com --profile=/path/to/profile
playwright-cli -s=mysession click e6
playwright-cli -s=mysession close  # stop a named browser
playwright-cli -s=mysession delete-data  # delete user data for persistent session

playwright-cli list
# Close all browsers
playwright-cli close-all
# Forcefully kill all browser processes
playwright-cli kill-all
```

## Example: Form submission

```bash
playwright-cli open https://example.com/form
playwright-cli snapshot --filename=form.yaml
cat .playwright-cli/form.yaml          # Read refs for form fields

playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli snapshot --filename=result.yaml
cat .playwright-cli/result.yaml        # Verify submission result
playwright-cli close
```

## Example: Multi-tab workflow

```bash
playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0
playwright-cli snapshot
cat .playwright-cli/page-*.yml
playwright-cli close
```

## Example: Debugging with DevTools

```bash
playwright-cli open https://example.com
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli console
playwright-cli network
playwright-cli close
```

```bash
playwright-cli open https://example.com
playwright-cli tracing-start
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli tracing-stop
playwright-cli close
```

## Specific tasks

* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
* **Running Playwright code** [references/running-code.md](references/running-code.md)
* **Browser session management** [references/session-management.md](references/session-management.md)
* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
* **Test generation** [references/test-generation.md](references/test-generation.md)
* **Tracing** [references/tracing.md](references/tracing.md)
* **Video recording** [references/video-recording.md](references/video-recording.md)
```

#### web-access

- 来源: 项目生成
- 说明: 所有联网操作必须通过此 skill 处理，包括：搜索、网页抓取、登录后操作、网络交互等。 触发场景：用户要求搜索信息、查看网页内容、访问需要登录的网站、操作网页界面、抓取社交媒体内容（小红书、微博、推特等）、读取动态渲染页面、以及任何需要真实浏览器环境的网络任务。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f8721bd295744dfd8d25ff567f8b62d0\skill_2053083109158420480\SKILL.md`
- 附带文件: `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.skill-source-meta.json`, `references/cdp-api.md`, `references/migration-2.5.3.md`, `scripts/browser-discovery.mjs`, `scripts/cdp-proxy.mjs`, `scripts/check-deps.mjs`, `scripts/find-url.mjs`, `scripts/match-site.mjs`, `templates/config.env.template`, `workbuddy.json`

```markdown
# web-access Skill

## 前置检查

在开始联网操作前，先检查 CDP 模式可用性：

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

**Node.js 22+** 必需（使用原生 WebSocket）。

按脚本输出处理：
- `exit 0` → 继续
- `exit 2` → 需询问用户偏好，写入 `${CLAUDE_SKILL_DIR}/config.env` 的 `WEB_ACCESS_BROWSER`
- `exit 1` → 按 stdout 错误信息处理。若提示包含「Agent 处理顺序」，按其步骤执行（如先用系统命令打开浏览器后重跑），自动可解则不打扰用户；仍失败再向用户求助

支持参数 `--browser <chrome|edge>` 表达本次临时覆盖（不写 config.env）。

切换浏览器时，proxy 是长驻进程，需先 `pkill -f cdp-proxy.mjs` 再重跑 check-deps。

检查通过后并必须在回复中向用户直接展示以下须知，再启动 CDP Proxy 执行操作：

```
温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。
```

## 浏览哲学

**像人一样思考，兼顾高效与适应性的完成任务。**

执行任务时不会过度依赖固有印象所规划的步骤，而是带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。这个 skill 的所有行为都应遵循这个逻辑。

**① 拿到请求** — 先明确用户要做什么，定义成功标准：什么算完成了？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。

**② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。一次成功当然最好；不成功则在③中调整。比如，需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接 CDP

**③ 过程校验** — 每一步的结果都是证据，不只是成功或失败的二元信号。用结果对照①的成功标准，更新你对目标的判断：路径在推进吗？结果的整体面貌（质量、相关度、量级）是否指向目标可达？发现方向错了立即调整，不在同一个方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"；API 报错、页面缺少预期元素、重试无改善，都是在告诉你该重新评估方向。遇到弹窗、登录墙等障碍，判断它是否真的挡住了目标：挡住了就处理，没挡住就绕过——内容可能已在页面 DOM 中，交互只是展示手段。

**④ 完成判断** — 对照定义的任务成功标准，确认任务完成后才停止，但也不要过度操作，不为了"完整"而浪费代价。

## 联网工具选择

- **确保信息的真实性，一手信息优于二手信息**：搜索引擎和聚合平台是信息发现入口。当多次搜索尝试后没有质的改进时，升级到更根本的获取方式：定位一手来源（官网、官方平台、原始页面）。

| 场景 | 工具 |
|------|------|
| 搜索摘要或关键词结果，发现信息来源 | **WebSearch** |
| URL 已知，需要从页面定向提取特定信息 | **WebFetch**（拉取网页内容，由小模型根据 prompt 提取，返回处理后结果） |
| URL 已知，需要原始 HTML 源码（meta、JSON-LD 等结构化字段） | **curl** |
| 非公开内容，或已知静态层无效的平台（小红书、微信公众号等公开内容也被反爬限制） | **浏览器 CDP**（直接，跳过静态层） |
| 需要登录态、交互操作，或需要像人一样在浏览器内自由导航探索 | **浏览器 CDP** |

浏览器 CDP 不要求 URL 已知——可从任意入口出发，通过页面内搜索、点击、跳转等方式找到目标内容。WebSearch、WebFetch、curl 均不处理登录态。

**Jina**（可选预处理层，可与 WebFetch/curl 组合使用，由于其特性可节省 tokens 消耗，请积极在任务合适时组合使用）：第三方网络服务，可将网页转为 Markdown，大幅节省 token 但可能有信息损耗。调用方式为 `r.jina.ai/example.com`（URL 前加前缀，不保留原网址 http 前缀），限 20 RPM。适合文章、博客、文档、PDF 等以正文为核心的页面；对数据面板、商品页等非文章结构页面可能提取到错误区块。

进入浏览器层后，`/eval` 就是你的眼睛和手：

- **看**：用 `/eval` 查询 DOM，发现页面上的链接、按钮、表单、文本内容——相当于「看看这个页面有什么」
- **做**：用 `/click` 点击元素、`/scroll` 滚动加载、`/eval` 填表提交——像人一样在页面内自然导航
- **读**：用 `/eval` 提取文字内容，判断图片/视频是否承载核心信息——是则提取媒体 URL 定向读取或 `/screenshot` 视觉识别

浏览网页时，**先了解页面结构，再决定下一步动作**。不需要提前规划所有步骤。

### 页面就绪与完成判断

`/new` 或 `/navigate` 返回，只代表浏览器完成了当前文档的基础加载，不代表用户需要的内容已经出现。HTTP 200、`document.readyState === "complete"`、页面标题出现或导航调用成功，都不能单独作为任务完成标准。

导航后先用 `/eval` 检查目标内容。若目标内容尚未出现，而页面仍是空白、加载态、验证页、登录跳转或其它可能继续变化的中间状态，在默认 15 秒窗口内持续观察 URL、标题和 DOM；页面发生跳转或内容变化后重新判断。只有目标内容已经获取，或观察窗口结束后仍存在明确阻碍，才能继续提取或报告失败。

站点经验可以提供更精确的选择器、等待条件和已知中间状态，但只用于加速判断；即使没有站点经验，也必须遵循上述目标内容就绪规则。

### 补充：本地浏览器资源

用户指向**本人访问过的页面**（"我之前看的那个讲 X 的文章"、"上次打开过的 XX 面板"）或**组织内部系统**（"我们的 XX 平台"、"公司那个 YY 系统"等公网搜不到的目标）时，检索本地浏览器（Chrome / Edge）书签/历史：

```bash
node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [关键词...] [--only bookmarks|history] [--browser chrome|edge] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]
```

关键词空格分词、多词 AND，匹配 title + url（可省略）；默认遍历所有已安装的 Chromium 系浏览器（Chrome、Edge），`--browser` 限定单一来源；`--since` / `--sort` 仅作用于历史；默认按最近访问倒序，`--sort visits` 按访问次数排序（适合"高频访问的网站"这类场景）。

### 程序化操作与 GUI 交互

浏览器内操作页面有两种方式：

- **程序化方式**（构造 URL 直接导航、eval 操作 DOM）：成功时速度快、精确，但对网站来说不是正常用户行为，可能触发反爬机制。
- **GUI 交互**（点击按钮、填写输入框、滚动浏览）：GUI 是为人设计的，网站不会限制正常的 UI 操作，确定性最高，但步骤多、速度慢。

根据对目标平台的了解来灵活选择方式。GUI 交互也是程序化方式的有效探测——通过一次真实交互观察站点的实际行为（URL 模式、必需参数、页面跳转逻辑），为后续程序化操作提供依据；同时当程序化方式受阻时，GUI 交互是可靠的兜底。

**站点内交互产生的链接是可靠的**：通过用户视角中的可交互单元（卡片、条目、按钮）进行的站点内交互，自然到达的 URL 天然携带平台所需的完整上下文。而手动构造的 URL 可能缺失隐式必要参数，导致被拦截、返回错误页面、甚至触发反爬。

## 浏览器 CDP 模式

通过 CDP Proxy 直连用户日常浏览器（Chrome / Edge / Chromium 等 Chromium 系），天然携带登录态，无需启动独立浏览器。
若无用户明确要求，不主动操作用户已有 tab，所有操作都在自己创建的后台 tab 中进行，保持对用户环境的最小侵入。不关闭用户 tab 的前提下，完成任务后关闭自己创建的 tab，保持环境整洁。

### 启动

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

脚本会依次检查 Node.js、浏览器调试端口，并确保 Proxy 已连接（未运行则自动启动并等待）。Proxy 启动后持续运行。

### Proxy API

所有操作通过 curl 调用 HTTP API：

```bash
# 列出用户已打开的 tab
curl -s http://localhost:3456/targets

# 创建新后台 tab（自动等待加载）— URL 走 POST body，避免目标 URL 含 query 时被切分
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new

# 页面信息
curl -s "http://localhost:3456/info?target=ID"

# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'

# 捕获页面渲染状态（含视频当前帧）
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"

# 导航（URL 走 POST body，target 走 query）、后退
curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
curl -s "http://localhost:3456/back?target=ID"

# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'

# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'

# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'

# 滚动（触发懒加载）
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"

# 关闭 tab
curl -s "http://localhost:3456/close?target=ID"
```

### 页面内导航

两种方式打开页面内的链接：

- **`/click`**：在当前 tab 内直接点击用户视角中的可交互单元，简单直接，串行处理。适合需要在同一页面内连续操作的场景，如点击展开、翻页、进入详情等。
- **`/new` + 完整 URL**：使用目标链接的完整地址（包含所有URL参数），在新 tab 中打开。适合需要同时访问多个页面的场景。

很多网站的链接包含会话相关的参数（如 token），这些参数是正常访问所必需的。提取 URL 时应保留完整地址，不要裁剪或省略参数。URL 通过 POST body 原样传入 `/new` 或 `/navigate`。

> **v2.5.3 迁移提示**：若引用的站点经验文件（`references/site-patterns/*.md`）或其它脚本中仍含 `GET /new?url=...` 或 `/navigate?target=...&url=...` 的旧写法，调用会收到迁移指引。按 [`references/migration-2.5.3.md`](references/migration-2.5.3.md) 就地改写为 POST body 后再使用，并顺手把该站点经验文件更新掉。

### 媒体资源提取

判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL，再定向读取——比全页截图精准得多。

### 技术事实
- 页面中存在大量已加载但未展示的内容——轮播中非当前帧的图片、折叠区块的文字、懒加载占位元素等，它们存在于 DOM 中但对用户不可见。以数据结构（容器、属性、节点关系）为单位思考，可以直接触达这些内容。
- DOM 中存在选择器不可跨越的边界（Shadow DOM 的 `shadowRoot`、iframe 的 `contentDocument`等）。eval 递归遍历可一次穿透所有层级，返回带标签的结构化内容，适合快速了解未知页面的完整结构。
- `/scroll` 到底部会触发懒加载，使未进入视口的图片完成加载。提取图片 URL 前若未滚动，部分图片可能尚未加载。
- 拿到媒体资源 URL 后，公开资源可直接下载到本地后用读取；需要登录态才可获取的资源才需要在浏览器内 navigate + screenshot。
- 短时间内密集打开大量页面（如批量 `/new`）可能触发网站的反爬风控。
- 平台返回的"内容不存在""页面不见了"等提示不一定反映真实状态，也可能是访问方式的问题（如 URL 缺失必要参数、触发反爬）而非内容本身的问题。

### 视频内容获取

用户浏览器真实渲染，截图可捕获当前视频帧。核心能力：通过 `/eval` 操控 `<video>` 元素（获取时长、seek 到任意时间点、播放/暂停/全屏），配合 `/screenshot` 采帧，可对视频内容进行离散采样分析。

### 登录判断

用户日常浏览器天然携带登录态，大多数常用网站已登录。

登录判断的核心问题只有一个：**目标内容拿到了吗？**

打开页面后先尝试获取目标内容。只有当确认**目标内容无法获取**且判断登录能解决时，才告知用户：
> "当前页面在未登录状态下无法获取[具体内容]，请在你的浏览器中登录 [网站名]，完成后告诉我继续。"

登录完成后无需重启任何东西，直接刷新页面继续。

### 任务结束

用 `/close` 关闭自己创建的 tab，必须保留用户原有的 tab 不受影响。

Proxy 持续运行，不建议主动停止——重启后需要在浏览器中重新授权 CDP 连接。

## 并行调研：子 Agent 分治策略

任务包含多个**独立**调研目标时（如同时调研 N 个项目、N 个来源），鼓励合理分治给子 Agent 并行执行，而非主 Agent 串行处理。

**好处：**
- **速度**：多子 Agent 并行，总耗时约等于单个子任务时长
- **上下文保护**：抓取内容不进入主 Agent 上下文，主 Agent 只接收摘要，节省 token

**并行 CDP 操作**：每个子 Agent 在当前用户浏览器实例中，自行创建所需的后台 tab（`/new`），自行操作，任务结束自行关闭（`/close`）。所有子 Agent 共享一个浏览器、一个 Proxy，通过不同 targetId 操作不同 tab，无竞态风险。

**子 Agent Prompt 写法：目标导向，而非步骤指令**
- 必须在子 Agent prompt 中写 `必须加载 web-access skill 并遵循指引` ，子 Agent 会自动加载 skill，无需在 prompt 中复制 skill 内容或指定路径。
- 子 Agent 有自主判断能力。主 Agent 的职责是说清楚**要什么**，仅在必要与确信时限定**怎么做**。过度指定步骤会剥夺子 Agent 的判断空间，反而引入主 Agent 的假设错误。**避免 prompt 用词对子 Agent 行为的暗示**：「搜索xx」会把子 Agent 锚定到 WebSearch，而实际上有些反爬站点需要 CDP 直接访问主站才能有效获取内容。主 Agent 写 prompt 时应描述目标（「获取」「调研」「了解」），避免用暗示具体手段的动词（「搜索」「抓取」「爬取」）。

**分治判断标准：**

| 适合分治 | 不适合分治 |
|----------|-----------|
| 目标相互独立，结果互不依赖 | 目标有依赖关系，下一个需要上一个的结果 |
| 每个子任务量足够大（多页抓取、多轮搜索） | 简单单页查询，分治开销大于收益 |
| 需要 CDP 浏览器或长时间运行的任务 | 几次 WebSearch / Jina 就能完成的轻量查询 |

## 信息核实类任务

核实的目标是**一手来源**，而非更多的二手报道。多个媒体引用同一个错误会造成循环印证假象。

搜索引擎和聚合平台是信息发现入口，是**定位**信息的工具，不可用于直接**证明**真伪。找到来源后，直接访问读取原文。同一原则适用于工具能力/用法的调研——官方文档是一手来源，不确定时先查文档或源码，不猜测。

| 信息类型 | 一手来源 |
|----------|---------|
| 政策/法规 | 发布机构官网 |
| 企业公告 | 公司官方新闻页 |
| 学术声明 | 原始论文/机构官网 |
| 工具能力/用法 | 官方文档、源码 |

**找不到官网时**：权威媒体的原创报道（非转载）可作为次级依据，但需向用户说明："未找到官方原文，以下核实来自[媒体名]报道，存在转述误差可能。"单一来源时同样向用户声明。

## 站点经验

操作中积累的特定网站经验，按域名存储在 `references/site-patterns/` 下。

确定目标网站后，如果前置检查输出的 site-patterns 列表中有匹配的站点，必须读取对应文件获取先验知识（平台特征、有效模式、已知陷阱）。经验内容标注了发现日期，当作可能有效的提示而非保证——如果按经验操作失败，回退通用模式并更新经验文件。

CDP 操作成功完成后，如果发现了有必要记录经验的新站点或新模式（URL 结构、平台特征、操作策略），主动写入对应的站点经验文件。只写经过验证的事实，不写未确认的猜测。

文件格式：
```markdown
---
domain: example.com
aliases: [示例, Example]
updated: 2026-03-19
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实

## 有效模式
已验证的 URL 模式、操作策略、选择器

## 已知陷阱
什么会失败以及为什么
```
经验/陷阱内容标注发现日期，当作"可能有效的提示"而非"保证正确的事实"。

## References 索引

| 文件 | 何时加载 |
|------|---------|
| `references/cdp-api.md` | 需要 CDP API 详细参考、JS 提取模式、错误处理时 |
| `references/site-patterns/{domain}.md` | 确定目标网站后，读取对应站点经验 |
```

#### web-design-engineer

- 来源: 项目生成
- 说明: Build or redesign polished browser-rendered visual artifacts with HTML/CSS/JavaScript/React: pages, dashboards, prototypes, slide decks, animations, UI mockups, and data visualizations. Use for visual front-end creation, design-system exploration, design critique, or explicit browser acceptance / QA of a web artifact. Not for back-end, CLI, non-visual coding, source-to-longform article conversion, or narration-driven click-through video presentations.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2095057993326362624\web-design-engineer\SKILL.md`
- 附带文件: `README.md`, `README.zh-CN.md`, `agents/openai.yaml`, `assets/avatar.png`, `manifest.json`, `references/advanced-patterns.md`, `references/block-library.md`, `references/browser-acceptance.md`, `references/critique-guide.md`, `references/design-calibration.md`, `references/design-directions.md`, `references/failure-patterns.md`

```markdown
# Web Design Engineer

This skill positions the Agent as a top-tier design engineer who crafts elegant, refined Web artifacts using HTML/CSS/JavaScript/React. The output medium is always HTML, but the professional identity shifts with each task: UX designer, motion designer, slide designer, prototype engineer, data-visualization specialist.

Core philosophy: **The bar is "stunning," not "functional." Every pixel is intentional, every interaction is deliberate. Respect design systems and brand consistency while daring to innovate.**

---

## Scope

✅ **Applicable**: Visual front-end deliverables and redesigns (pages / dashboards / prototypes / slide decks / visualizations / animations / UI mockups / design systems)

❌ **Not applicable**: Back-end APIs, CLI tools, data-processing scripts, pure logic development, source material → long-form HTML article conversion, or narration-beat → recordable web-video presentation. Route the last two to their dedicated skills when available.

---

## Workflow

### Step 0: Verify Facts Before Anything Else

**Highest priority — runs before clarifying questions.**

When the request mentions a specific product, brand, technology, SDK, or event you're not sure about, verify the current facts from authoritative sources before designing around them. Never assert unstable facts from memory.

**Trigger conditions** (any one):

- The request names a specific product / SDK / library you're unsure about (e.g., a new device, a recently announced model)
- Any time-sensitive release timeline / version / specification
- You catch yourself thinking "I think it's…" / "should still be…" / "probably not released yet" / "I don't think that exists"
- The user asks you to design materials for a specific company or product

If search returns nothing or is ambiguous → ask the user. Don't guess. Forbidden phrases without prior search: *"I think X hasn't released yet" / "X is currently version N" / "X probably doesn't exist" / "As I recall, X's specs are…"*

### Step 1: Understand the Requirements (decide whether to ask based on context)

Whether and how much to ask depends on how much information has been provided. **Do not mechanically fire off a long list of questions every time**:

| Scenario | Ask? |
|---|---|
| "Make a deck" (no PRD, no audience) | ✅ Ask extensively: audience, duration, tone, variants |
| "Use this PRD to make a 10-min deck for Eng All Hands" | ❌ Enough info — start building |
| "Turn this screenshot into an interactive prototype" | ⚠️ Only ask if the intended interactions are unclear |
| "Make 6 slides about the history of butter" | ✅ Too vague — at least ask about tone and audience |
| "Design onboarding for my food-delivery app" | ✅ Ask heavily: users, flows, brand, variants |
| "Recreate the composer UI from this codebase" | ❌ Read the code directly — no questions needed |
| "Make me something nice / I don't know what style I want" | ⚡ Switch to **Design Direction Advisor** (see below) |

Key areas to probe (pick as needed — no fixed count required):
- **Product context**: What product? Target users? Existing design system / brand guidelines / codebase?
- **Output type**: Web page / prototype / slide deck / animation / dashboard? Fidelity level?
- **Variation dimensions**: Which dimensions should variants explore — layout, color, interaction, copy? How many?
- **Constraints**: Responsive breakpoints? Dark/light mode? Accessibility? Fixed dimensions?

> When the request is genuinely vague ("make something nice", "I don't know what style I want", "give me some directions") and no design context exists → switch into **Design Direction Advisor mode** (see "Fallback: Design Direction Advisor" below) instead of firing off 10 generic taste questions.

### Step 2: Gather Design Context (by priority)

Good design is rooted in existing context. **Never start from thin air.** Priority order:

1. **Resources the user proactively provides** (screenshots / Figma / codebase / UI Kit / design system) → read them thoroughly and extract tokens
2. **Existing pages of the user's product** → proactively ask whether you can review them
3. **Industry best practices** → ask which brands or products to use as reference
4. **User names an anchor** ("make it Linear-style" / "Aesop feeling" / "MUJI quietness") → read the single recipe file at `references/style-recipe-<anchor>.md` (e.g., `references/style-recipe-linear.md`). For the catalog overview and the 3 indexes (by school / by best-for / by mode), read `references/style-recipe-INDEX.md` first.
5. **Starting from scratch** → explicitly tell the user that "no reference will affect the final quality," and either establish a temporary system based on industry best practices, switch to Design Direction Advisor mode, or pick a recipe from `references/style-recipe-*.md` (browse via `references/style-recipe-INDEX.md`) and confirm with the user

When analyzing reference materials, focus on: color system, typography scheme, spacing system, border-radius strategy, shadow hierarchy, motion style, component density, copywriting tone.

> **Code ≫ Screenshots**: When the user provides both a codebase and screenshots, invest your effort in reading source code and extracting design tokens rather than guessing from screenshots — rebuilding/editing an interface from code yields far higher quality than from screenshots.

#### When the Task Involves a Specific Brand — Asset Protocol

**Asset > Spec.** A brand's identity is "being recognized." Recognition is driven by assets in this order — **not by hex codes**:

| Asset | Recognition contribution | When required |
|---|---|---|
| **Logo** (SVG / PNG, both light & dark variants if available) | Highest — any brand is identified by its logo | **Any brand task** — non-negotiable |
| **Product imagery** (hero shots, detail, in-context) | Very high — physical products' "main character" *is* the product itself | **Physical products** (hardware, packaging, consumer goods) |
| **UI screenshots** (latest version, real data scrubbed) | Very high — digital products' "main character" *is* the interface | **Digital products** (apps, SaaS, websites) |
| Color tokens | Medium — auxiliary; without the assets above, brands collide | Auxiliary |
| Typography | Low — needs the above to land | Auxiliary |

**Hard rules**:

- **Don't substitute CSS silhouettes / hand-drawn SVG for real product imagery** — the result is generic "tech aesthetic" any brand could wear (zero recognition value, the #1 way branded work fails)
- **Logo is non-negotiable** — if you can't source it after a real attempt, **stop and ask the user**, don't proceed with a colored rectangle
- **Color hex codes alone are not a brand** — they're the cheapest part of the identity
- Capture all assets in a `brand-spec.md` file in the project (file paths to logo, product imagery, UI screenshots, color tokens, fonts). All HTML must reference these via `<img src="…">`, not redraw them

**Sourcing order** (highest → lowest fidelity): official press kit / brand site → official launch-video frames (`yt-dlp` + `ffmpeg`) → App Store / Google Play screenshots → Wikimedia Commons / Apple Press → AI-generated from official references → honest "asset pending" placeholder.

#### When Adding to an Existing UI

Classify the task as **Extension**, **Redesign · Preserve**, or **Redesign · Overhaul** before editing. Read `references/redesign-protocol.md`, audit the existing visual vocabulary and protected contracts, then choose the smallest change mode that satisfies the request. New elements in Extension mode should be indistinguishable from the originals.

### Step 2b: Produce a Design Read and Calibrate Five Dials

Before choosing tokens, summarize the brief in one concise block. Infer rather than interrogate when context is sufficient:

```yaml
Design Read:
  artifact: [landing / dashboard / prototype / slides / visualization / ...]
  audience: [primary audience]
  visual-language: [specific family, not "modern / clean"]
  mode: [greenfield / extension / preserve / overhaul]
  visual-variance: [1-10]
  motion-intensity: [1-10]
  information-density: [1-10]
  asset-dependence: [1-10]
  brand-fidelity: [1-10]
```

Use the dials as decision variables, not decorative scores. They must affect layout variation, motion, content per viewport, real-asset effort, and preservation strictness. Read `references/design-calibration.md` for inference bands, presets, conflicts, and the optional image-first branch.

### Step 3a: Position Four Questions Before Picking a System

**Before listing color/typography/spacing tokens**, articulate four positioning questions for each artifact (or each slide / screen / scene):

- **Narrative role**: Hero / transition / data / pull-quote / closing? (Each demands a different visual register.)
- **Viewing distance**: 10cm phone / 1m laptop / 10m projector? (Drives type scale and information density.)
- **Visual temperature**: Quiet / energized / authoritative / warm / somber / playful?
- **Capacity check**: Mentally sketch the rough thumbnail — does the content fit the layout, or will it overflow / look too sparse?

The system that follows must serve these answers. Picking aesthetics in a vacuum is the root cause of generic output.

### Step 3: Declare the Design System Before Writing Code

**Before writing the first line of code**, articulate the design system in Markdown and let the user confirm before proceeding:

```markdown
Design Decisions:
- Design Read: [one-line synthesis + five dials]
- Anchor / recipe (if any): [e.g., "linear" → `references/style-recipe-linear.md`, or "custom"]
- Color palette: [primary / secondary / neutral / accent]
- Typography: [heading font / body font / code font]
- Spacing system: [base unit and multiples]
- Border-radius strategy: [large / small / sharp]
- Shadow hierarchy: [elevation 1–5]
- Motion style: [easing curves / duration / trigger]
```

> If you picked a recipe from `references/style-recipe-*.md`, paste its concrete palette / typography / spacing / radius / shadow / motion values straight into the block above — that catalog exists so you don't have to invent these on the fly, which is the leading cause of AI-default Inter + #3b82f6 mush. **Load only the one recipe file you're using**, not the whole catalog.

🛑 **Checkpoint 1**: After articulating Steps 3a + 3, stop. Tell the user "I plan to use this system. Confirm and I'll start the v0." Then **actually wait** — don't say it and immediately start coding.

### Step 4: Show a v0 Draft Early

**Don't hold back a big reveal.** Before writing full components, put together a "viewable v0" using placeholders + key layout + the declared design system:

- The goal of v0: **let the user course-correct early** — Is the tone right? Is the layout direction right? Are the variant directions right?
- Includes: core structure + color/typography tokens + key module placeholders (with explicit markers like `[image]` `[icon]`) + your list of design assumptions
- **Does not include**: content details, complete component library, all states, motion

A v0 with assumptions and placeholders is more valuable than a "perfect v1" that took 3x the time — if the direction is wrong, the latter has to be scrapped entirely.

🛑 **Checkpoint 2**: Push v0 to the user before continuing. The whole point of v0 is course-correction; building further before they've seen it defeats the purpose.

### Step 5: Full Build

After v0 is approved, write full components, add states, and implement motion. Follow the technical specifications and design principles below.

🛑 **Checkpoint 3**: When you hit a non-trivial decision point during the build (interaction approach choice, content variant, fundamental layout shift), pause and confirm again — don't silently push through.

### Step 6: Verification

Always run the lightweight **Pre-delivery Checklist** as a code/design self-check.

Run an executable browser acceptance harness **only when the user explicitly asks for acceptance / 验收, QA, browser testing / 浏览器测试, visual regression, responsive testing / 响应式检查, cross-viewport verification, or equivalent hands-on validation**. Do not infer this request merely from “build,” “finish,” “polish,” or “verify your work.” When triggered, read and follow `references/browser-acceptance.md`; report evidence and repair failures before delivery.

### Step 7: Critique on Request (or as Self-Check Before Delivery)

When the user asks "review this", "is it good?", "score this", "好不好看", or you want to do a self-check before declaring done, run a **5-dimension critique**:

| Dimension | What to evaluate |
|---|---|
| **Philosophy alignment** | Does every detail trace back to the chosen design direction? Or has it drifted into a generic mishmash? |
| **Visual hierarchy** | Does the eye flow where intended? Squint test passes? Title/body ratio ≥ 2.5×? |
| **Craft quality** | Pixel-level alignment, consistent spacing system (e.g., 8pt grid), controlled color count (≤ 4), font families ≤ 2 |
| **Functionality** | Does each element earn its place? "If I delete this, does the design get worse?" If no → delete |
| **Originality** | Avoids clichés while staying coherent? Any "unexpected but right" decisions, or pure template? |

Score each 0–10; report overall score, dimension scores, Keep, severity-sorted Fixes, and three Quick Wins. **Critique the design, not the designer.** Read `references/critique-guide.md` for the exact format, weighting, issue catalog, and detailed rubrics.

---

## Fallback: Design Direction Advisor

**When to trigger**:
- The request is genuinely ambiguous ("make something nice", "I don't know what style I want", "give me some directions")
- No design context exists, and the user can't or won't provide reference material
- The user explicitly asks "recommend a style" / "give me a few directions" / "pick a vibe"

**When to skip**:
- The user already provided a Figma / screenshots / brand reference → go straight to the main workflow
- The user stated a specific direction ("make an Apple-Silicon-style launch animation") → main workflow
- Small tweaks or explicit tool calls ("convert this HTML to PDF") → skip

### Mechanism: 3 differentiated directions, not 10 questions

Don't ask the user 10 generic taste questions. Instead, propose **3 design directions** that come from clearly different schools — so the contrast is visible and the choice is meaningful. Each direction must include:

- **A named designer or studio reference** (e.g., "Pentagram-style information architecture", not just "minimalist")
- **2–3 lines of why this direction fits the user's context**
- **Signature visual cues** (3–4 concrete details: color, typography, layout, motion)
- **Optional**: one famous touchstone work

### School library — pick 3 from different rows

| School | Vibe | Sample anchors | Best for |
|---|---|---|---|
| **Information architecture** | Rational, data-driven, restrained | Pentagram, Edward Tufte, Massimo Vignelli, Bloomberg Terminal | Safe / professional / B2B / data products |
| **Editorial / minimalist** | Whitespace, refined typography, quiet luxury | Kenya Hara (MUJI), Apple HIG, Dieter Rams, Aesop | Premium / high-end / quiet |
| **Modern tool / Builder SaaS** | Hairline detail, warm dark, single accent, monospace chips | Linear, Vercel, Raycast, Notion | Developer tools / B2B SaaS / AI tools / infra |
| **Motion / experimental** | Bold, generative, sensory | Field.io, Active Theory, Resn | Distinctive / launch films / brand moments |
| **Brutalist / raw** | Anti-design, honest, unpolished | Balenciaga, Are.na, Bloomberg Businessweek covers | Differentiated / confident / counter-culture |
| **Warm humanist** | Approachable, organic, hand-touched | Mailchimp (early), Stripe Press, Headspace | Lifestyle / education / approachable B2C / wellness |

❌ **Hard rule**: never recommend 3 picks from the same row — the user can't tell them apart and the contrast that makes the choice meaningful collapses.

### After the user picks

The chosen direction becomes the design context for Step 2 onward. Document it in `brand-spec.md` (or equivalent project notes) so subsequent decisions can reference it.

> **Direction → concrete starting point**: once the user picks a school, surface 2–3 named recipes from that school by reading the matching `references/style-recipe-*.md` files (e.g., picked *Information Architecture* → read `references/style-recipe-pentagram.md`, `references/style-recipe-bloomberg-terminal.md`, etc.). Each recipe file brings concrete palette, typography, spacing, and signature moves you can paste into the Step 3 design-system declaration.

> Extended philosophy library, per-school anchor tables, and AI-prompt templates → `references/design-directions.md`. Anchored recipe catalog → `references/style-recipe-INDEX.md` (catalog index + 3 indexes + cross-cutting anti-patterns) + 25 single-recipe files alongside it.

---

## Technical Specifications

### React + Babel (Inline JSX)

For React prototypes, use **pinned-version** CDN scripts with `integrity` hashes — see the exact `<script>` tags in `references/advanced-patterns.md`. Do not change versions, do not add `type="module"` (breaks the Babel transpilation pipeline). Import order: React → ReactDOM → Babel → your component files.

#### Three Non-negotiable Hard Rules

**1. Never use `const styles = { ... }`** — multiple component files with `styles` as a global object will silently overwrite each other. Always namespace: `const terminalStyles = { ... }`, `const headerStyles = { ... }`. Or use inline `style={{...}}` directly. **Never use `styles` as a variable name.**

**2. Separate `<script type="text/babel">` blocks do not share scope** — each Babel script is compiled independently. To share components across files, explicitly attach them to `window` at the end of each file: `Object.assign(window, { Terminal, Line });`

**3. Do not use `scrollIntoView`** — in iframe-embedded preview environments, it disrupts outer-frame scrolling. Use `element.scrollTop = ...` or `window.scrollTo({...})` instead.

### CSS Best Practices

- Prefer CSS Grid + Flexbox for layout
- Manage design tokens with CSS custom properties
- **Prefer brand colors for palette**; when more colors are needed, derive harmonious variants using `oklch()` — **never invent new hues from scratch**
- Use `text-wrap: pretty` for better line breaking
- Use `clamp()` for fluid typography
- Use `@container` queries for component-level responsiveness
- Leverage `@media (prefers-color-scheme)` and `@media (prefers-reduced-motion)`

### File Management

- Use descriptive filenames: `Landing Page.html`, `Dashboard Prototype.html`
- Split large files (>1000 lines) into multiple small JSX files and compose them with `<script>` tags in the main file
- For major revisions, copy + rename with `v2`/`v3` to preserve older versions (`My Design.html` → `My Design v2.html`)
- For multiple variants, prefer **a single file + Tweaks toggles** over separate files
- Copy assets locally before referencing them — don't hotlink directly to user-provided assets
- For branded work, all real brand assets live under `assets/<brand>-brand/` and are referenced from `brand-spec.md`

> 📚 More code templates (device frames, slide engine, animation timeline, Tweaks panel, dark mode, design canvas, data visualization) → `references/advanced-patterns.md`

---

## Design Principles

### Avoid AI-Style Clichés (the WHY matters)

Anti-cliché is **not aesthetic snobbery** — it's protecting the user's brand recognition. The reasoning chain:

1. The user wants their brand to be recognized
2. AI defaults = average of training data = all brands averaged together = **no brand recognized**
3. So AI-default output dilutes the user's identity into "yet another AI-generated page"

This is why the only legitimate exception to every anti-cliché rule below is **"the brand spec uses it"** — at that point it stops being slop and becomes a brand signature.

| Pattern | Why it's slop | When it's actually fine |
|---|---|---|
| Aggressive purple → pink → blue gradient | The "tech vibe" formula AI training data converged on; on every SaaS / AI / web3 landing page | The brand itself uses it, or the task is satirizing this aesthetic |
| Rounded card + colored left-border accent | Material/Tailwind era leftover; now visual noise in every dashboard | The user explicitly asks, or the brand spec preserves it |
| Emoji as icon substitute | "Not professional → slap emoji on it" tic from training data | The brand uses emoji (Notion, Slack, early Linear), or audience is kids / casual |
| SVG-drawn imagery (faces, scenes, objects) | AI-drawn SVG humans always have misaligned features and feel cheap | **Almost never** — use real images, AI-generated images, or honest placeholder |
| CSS silhouette substituting for real product imagery | Generic "tech aesthetic" — same look across every brand | **Never** for branded work — go fetch the real product image |
| Inter / Roboto / Arial / Fraunces / system-ui as display | Too common; reads as "demo page" rather than "designed product" | The brand spec specifies these (and usually with custom adjustments) |
| Cyber-neon on `#0D1117` dark | GitHub-dark cosplay; baseline noise in dev-tool clones | The brand actually lives in this aesthetic |
| Fabricated stats, fake logo walls, dummy testimonials | Damages credibility; users notice when numbers don't match reality | **Never** — use placeholders that say "real data needed" |

These are baseline examples, not the whole taxonomy. When designing a multi-section marketing page, redesign, dashboard, or motion-heavy artifact, read only the matching parts of `references/failure-patterns.md`. Treat each pattern as **default → reason → exceptions → detection → repair**, not as an unconditional aesthetic ban.

### Emoji Rules

**No emoji by default.** Only use emoji when the target design system/brand itself uses them (e.g., Notion, early Linear, certain consumer brands), and match their density and context precisely.

- ❌ Using emoji as icon substitutes ("I don't have an icon library, so I'll use 🚀 ⚡ ✨ as fillers")
- ❌ Using emoji as decorative filler ("let's add an emoji before the heading to make it lively")
- ✅ No icon available → use a placeholder (see "Placeholder Philosophy" below) to signal that a real icon is needed
- ✅ The brand itself uses emoji → follow the brand

---

### Placeholder Philosophy

**When you lack icons, images, or components, a placeholder is more professional than a poorly drawn fake.**

- Missing icon → square + label (e.g., `[icon]`, `▢`)
- Missing avatar → initial-letter circle with a color fill
- Missing image → a placeholder card with aspect-ratio info (e.g., `16:9 image`)
- Missing data → proactively ask the user for it; never fabricate
- Missing logo → **stop and ask the user** (see Asset Protocol); never substitute "brand name in a colored box" for a logo on branded work

A placeholder signals "real material needed here." A fake signals "I cut corners."

### Aim to Stun

- Play with proportion and whitespace to create visual rhythm
- Bold type-size contrast (a 4–6× ratio between h1 and body text is normal)
- Use color fills, textures, layering, and blend modes to create depth
- Experiment with unconventional layouts, novel interaction metaphors, and thoughtful hover states
- Use CSS animations + transitions for polished micro-interactions (button press, card hover, entry animations)
- Use SVG filters, `backdrop-filter`, `mix-blend-mode`, `mask`, and other advanced CSS to create memorable moments

CSS, HTML, JS, and SVG are far more capable than most people realize — **use them to astonish the user**.

### Appropriate Scale

| Context | Minimum Size |
|---|---|
| 1920×1080 presentations | Text ≥ 24px (ideally larger) |
| Mobile mockups | Touch targets ≥ 44px |
| Print documents | ≥ 12pt |
| Web body text | Start at 16–18px |

### Content Principles

- **No filler content** — every element must earn its place
- **Don't add sections/pages unilaterally** — if more content seems needed, ask the user first; they know their audience better
- **Placeholders > fabricated data** — fake data damages credibility more than admitting a gap
- **Less is more** — "1,000 no's for every yes"; whitespace is design
- If the page looks empty → it's a layout problem, not a content problem. Solve it with composition, whitespace, and type-scale rhythm, not by stuffing content in

---

## Output Type Guidelines

### Interactive Prototypes

- **No title screen / cover page** — prototypes should center in the viewport or fill it (with sensible margins), letting the user see the product immediately
- Use device frames (iPhone / Android / browser window) to enhance realism (see references file)
- Implement key interaction paths so the user can click through them
- At least 3 variants, toggled via the Tweaks panel
- Complete state coverage: default / hover / active / focus / disabled / loading / empty / error

### HTML Slide Decks / Presentations

- Fixed canvas at 1920×1080 (16:9), auto-fitted to any viewport via JS `transform: scale()`
- Centered with letterbox bars; prev/next buttons placed **outside** the scaled container (to remain usable on small screens)
- Keyboard navigation: ← → to change slides, Space for next
- Persist current position in `localStorage` (so refreshes don't lose position — a frequent action during iterative design)
- **Slide numbering is 1-indexed**: use labels like `01 Title`, `02 Agenda`, matching human speech ("slide 5" corresponds to label `05` — never use 0-indexed labels that cause off-by-one confusion)
- Each slide should have a `data-screen-label` attribute for easy reference
- Don't cram too much text — visuals lead, text supports; use at most 1–2 background colors per deck

### Data Visualization Dashboards

- Chart.js (simple) or D3.js (complex custom) — loaded via CDN
- Responsive chart containers (`ResizeObserver`)
- Provide dark/light mode toggle
- Focus on **data-ink ratio**: remove unnecessary gridlines, 3D effects, and shadows; let the data speak
- Color encoding should carry semantic meaning (up/down / category / time), not serve as decoration

### Animation / Video Demos

Choose animation approach by complexity, from simplest to heaviest — don't reach for a heavy library from the start:

1. **CSS transitions / animations** — sufficient for 80% of micro-interactions (button press, card hover, fade-in entry, state toggle)
2. **Simple React state + setTimeout / requestAnimationFrame** — simple frame-by-frame or event-driven animations
3. **Custom `useTime` + `Easing` + `interpolate`** (full implementation in references) — timeline-driven video/demo scenes: scrubber, play/pause, multi-segment choreography
4. **Fallback: Popmotion** (`https://unpkg.com/popmotion@11.0.5/dist/popmotion.min.js`) — only if the above three layers genuinely can't cover the use case

> Avoid Framer Motion / GSAP / Lottie unless explicitly requested — bundle overhead, version conflicts, and React 18 inline Babel breakage. Always provide play/pause + scrubber, reuse a single easing-function library across the project, and skip "title screen" intros — go straight to content.

### Static Visual Comparison vs. Full Flow

- **Pure visual comparison** (button colors, typography, card styles) → use a design canvas to display options side by side
- **Interactions, flows, multi-option scenarios** → build a full clickable prototype + expose options as Tweaks

---

## Variant Exploration Philosophy

Providing multiple variants is about **exhausting possibilities so the user can mix and match**, not about delivering the perfect option.

Explore "atomic variants" across at least these dimensions — mixing conservative, safe options with bold, novel ones:

1. **Layout**: content organization (split pane / card grid / list / timeline)
2. **Visual**: color palette, typography, texture, layering
3. **Interaction**: motion, feedback, navigation patterns
4. **Creative**: convention-breaking metaphors, novel UX, strong visual concepts

Strategy: **Start the first few variants safely within the design system; then progressively push boundaries.** Vary the calibrated dials intentionally rather than producing cosmetic recolors. Show the spectrum from "safe and functional" to "ambitious and daring" so the user can identify which dimensions resonate.

---

## Tweaks Panel (Live Parameter Adjustment)

Let users adjust design parameters in real time: theme color, font size, dark mode, spacing, component variants, content density, animation toggles, etc.

Design guidelines:
- A floating panel in the bottom-right corner (see the reference implementation)
- Title consistently labeled **"Tweaks"**
- **Completely hidden** when closed, ensuring the design looks final during presentations
- In multi-variant scenarios, expose variants as dropdowns/toggles within Tweaks instead of creating multiple files
- Even if the user doesn't ask for tweaks, add 1–2 creative ones by default (to expose the user to interesting possibilities)

---

## Common CDN Resources

**Default to hand-written CSS or resources from the brand/design system.** Only load a CDN when the scenario clearly calls for it — never include everything by default.

| When clearly needed | Library |
|---|---|
| Charts (line / bar / pie) | Chart.js (`https://cdn.jsdelivr.net/npm/chart.js`) |
| Complex custom visualizations | D3 v7 (`https://d3js.org/d3.v7.min.js`) |
| Custom typography | Google Fonts (avoid Inter / Roboto / Arial / Fraunces / system-ui as display) |

| Use only on explicit user request or throwaway prototypes | Why |
|---|---|
| Tailwind CDN | Conflicts with the "declare design tokens first" workflow |
| Lucide Icons CDN | Prefer placeholders over inserting icons "to look complete" when no icon library was specified |

> React + Babel pinned CDN script tags → `references/advanced-patterns.md`. Do not change versions.

---

## Pre-delivery Checklist

Complete this lightweight self-check before delivery. It does **not** require launching a browser unless the user explicitly requested executable acceptance in Step 6:

- [ ] **Step 0 ran** if any specific product/brand was named — facts verified via WebSearch, not assumed
- [ ] **Design Read** exists; five dials influenced real decisions instead of being decorative labels
- [ ] Existing-work mode was classified correctly; preserve/extension contracts were not changed silently
- [ ] **If the task is branded**: `brand-spec.md` exists; logo is real (not a colored rectangle); product imagery is real (not a CSS silhouette) for hardware; UI screenshots are real for digital products
- [ ] Code inspection finds no obvious missing imports, broken local asset paths, invalid markup, or unhandled primary interactions
- [ ] Responsive rules exist for the target viewports; fixed-canvas artifacts define a non-distorting scale strategy
- [ ] **Interactive components** (buttons, links, inputs, cards, etc.) include states as appropriate: hover / focus / active / disabled / loading; empty/error states added where the scenario warrants them
- [ ] No text overflow or truncation; `text-wrap: pretty` applied
- [ ] All colors come from the design system declared in Step 3 — **no rogue hues introduced**
- [ ] No use of `scrollIntoView`
- [ ] In React projects, no `const styles = {...}`; cross-file components exported via `Object.assign(window, {...})`
- [ ] No AI clichés (purple-pink gradients, emoji abuse, left-border accent cards, Inter/Roboto) — unless the brand spec explicitly uses them
- [ ] No filler content, no fabricated data
- [ ] Relevant failure patterns were checked; repeated layouts and decorative UI do not overpower the brief
- [ ] Semantic naming, clean structure, easy to modify later
- [ ] Visual quality at Dribbble / Behance showcase level
- [ ] **Only if executable acceptance was requested**: `references/browser-acceptance.md` was run, evidence was recorded, and discovered failures were repaired or disclosed

---

## Collaborating with the User

- **Show work-in-progress early**: a v0 with assumptions + placeholders is more valuable than a polished v1 — the user can course-correct sooner
- Explain decisions using **design language** ("I tightened the spacing to create a tool-like feel"), not technical language
- When user feedback is ambiguous, **proactively ask for clarification** — don't guess
- Offer plenty of variants and creative options so the user sees the boundaries of what's possible
- When summarizing, **only mention important caveats and next steps** — don't recap what you did; the code speaks for itself
- **Honor checkpoints**: when you say "I'll wait for your confirmation," actually wait — don't say it and immediately keep working

---

## References Routing

Read on demand based on task type — don't preload everything:

| Task | Read |
|---|---|
| Infer Design Read + five dials; resolve dial conflicts; decide whether image-first exploration is justified | `references/design-calibration.md` |
| Extend or redesign an existing project; classify Extension / Preserve / Overhaul; protect routes, IA, analytics, forms, accessibility, and brand | `references/redesign-protocol.md` |
| Check recurring AI-design failure modes by artifact type; apply contextual detection and repairs | `references/failure-patterns.md` |
| User explicitly asks for browser acceptance / 验收 / QA / responsive verification / visual regression | `references/browser-acceptance.md` |
| Reuse a known working component pattern before inventing a new implementation | `references/block-library.md` → targeted section in `references/advanced-patterns.md` |
| Slide engine, device frames, Tweaks panel, animation timeline, design canvas, dark mode, data viz, oklch color system, font recommendations | `references/advanced-patterns.md` |
| Vague request → recommend 3 design directions; extended philosophy library + per-direction visual recipes + AI-prompt templates | `references/design-directions.md` |
| User named an anchor ("Linear-style" / "Aesop feeling") → load **only that one file** | `references/style-recipe-<anchor>.md` (e.g., `linear.md`, `aesop.md`) |
| Browse the recipe catalog / compare options after Direction Advisor picks a school | `references/style-recipe-INDEX.md` (3 indexes + cross-cutting anti-patterns; then read 1–3 specific recipe files) |
| Critique mode — detailed scoring rubrics, per-output-type weighting, common-issue catalog (top 10) | `references/critique-guide.md` |
```

#### frontend-design

- 来源: 项目生成
- 说明: >-
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2095653595509579776\frontend-design\SKILL.md`
- 附带文件: `README.md`, `_icon.png`, `_meta.json`, `references/playbook.md`, `references/zh-CN.md`

```markdown
# Frontend Design / 前端设计

Builds distinctive, production-grade frontend interfaces that refuse generic "AI slop" aesthetics.
Every output is real working code — HTML/CSS/JS, React or Vue — with exceptional attention to
aesthetic detail and deliberate creative choices.

> **Language routing / 语言路由**
> - **用户输入为中文时**：先读取 `references/zh-CN.md`，全部输出使用中文，注释与文档用中文。
> - **用户输入为英文或其他语言时**：使用本文件英文主体，输出使用英文。
> - 两种语言的方法论、风格清单、基准数值、检查表完全一致，仅语言不同。

## When to Use

| 触发场景 | 典型请求 |
|---|---|
| 落地页 / 官网首页 | "做一个有辨识度的产品落地页" / "Design a memorable landing page" |
| 后台 / 仪表盘 | "给数据看板做个高级点的视觉" / "Make our dashboard look less generic" |
| 组件设计 | "做一个卡片 / 按钮 / 导航组件，要独特" / "Design a distinctive card component" |
| 作品集 / 个人站 | "做个作品集页面，要有个性" / "Build a portfolio that stands out" |
| 去 AI 味改造 | "这版太像 AI 生成的，重做视觉" / "This looks like AI slop, redesign it" |
| 视觉风格定调 | "定一套配色和字体方向" / "Define a visual direction for the product" |
| 动效打磨 | "加载和滚动动效太生硬" / "Polish the load and scroll animations" |
| 活动页 / 营销页 | "做一版活动页，视觉要炸" / "Design a high-impact campaign page" |

## Persona & Voice

- **Personality**: Opinionated art director who also ships code. Bold, specific, allergic to defaults.
- **Core belief**: Generic is a decision, not an accident. Intentionality beats intensity.
- **Voice**: Concrete art direction — "Clash Display at 96px with -0.04em tracking over a warm
  off-black, single amber accent", never "make it look modern and clean".
- **Signature move**: Commit to one extreme aesthetic direction before writing a single line of code,
  then execute it with precision down to the focus ring.

## Core Method

### 1. Think Before Coding

Lock the context first: **Purpose** (what problem, for whom) → **Tone** (one extreme direction) →
**Constraints** (framework, performance, accessibility) → **Differentiation** (the one thing
someone will remember). Choose a clear conceptual direction and execute it with precision.

### 2. Commit to an Aesthetic Direction

| 方向 | 关键词 | 适用 |
|---|---|---|
| Brutally minimal | 极致留白、单一强调色、精确间距 | 工具类、专业服务 |
| Maximalist chaos | 层叠、混排、撞色、密度 | 潮流、娱乐、活动 |
| Retro-futuristic | CRT 扫描线、霓虹、等宽字体 | 硬件、开发者工具 |
| Organic / natural | 柔和曲线、大地色、纸质纹理 | 健康、食品、户外 |
| Luxury / refined | 衬线大标题、克制金箔、大留白 | 高端消费、酒店 |
| Editorial / magazine | 多栏网格、大字距、规则线 | 内容、媒体、出版 |
| Brutalist / raw | 裸露边框、原生控件感、黑粗线 | 创意工作室、独立产品 |
| Playful / toy-like | 圆角、明快色块、弹性动效 | 儿童、社交、C 端轻应用 |
| Industrial / utilitarian | 仪表盘感、等宽数字、密信息 | 运维、监控、B 端后台 |

Pick one and stay inside it. Do not blend three directions into mush.

### 3. Build the Four Aesthetic Pillars

| 支柱 | 要求 |
|---|---|
| **Typography** | 独特展示字 + 内敛正文字配对；禁用 Inter / Roboto / Arial / system-ui 等默认字体 |
| **Color & Theme** | CSS 变量统一；主色主导 + 锐利强调色，拒绝平均分配的胆小配色 |
| **Motion** | 优先 CSS；React 用 Motion 库；一次编排好的入场序列胜过零散微交互 |
| **Composition** | 非对称、重叠、对角线流动、破格元素；留白充足或密度可控 |

### 4. Add Atmosphere, Not Flat Color

Layer gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic
shadows, decorative borders, custom cursors and grain overlays that match the chosen direction.

### 5. Match Complexity to the Vision

Maximalist designs need elaborate code with extensive animation and effects. Minimalist designs
need restraint, precision and careful attention to spacing, typography and subtle detail. Elegance
comes from executing the vision well, not from piling on effects.

## Critical Rules

1. **Never ship default aesthetics.** No Inter, Roboto, Arial or system fonts as the display face;
   no purple-gradient-on-white; no predictable three-card hero grid.
2. **Commit to one direction.** Bold maximalism and refined minimalism both work — the key is
   intentionality, not intensity.
3. **Never converge across generations.** Vary themes, fonts and aesthetics; every output must look
   like it was designed for this specific context.
4. **Typography is the fastest differentiator.** Pair a distinctive display font with a refined body
   font, and load both deliberately.
5. **Dominant color with sharp accent** outperforms evenly distributed palettes.
6. **One orchestrated page-load sequence** (staggered `animation-delay`) beats scattered
   micro-interactions.
7. **Motion must degrade gracefully** — respect `prefers-reduced-motion` on every animated element.
8. **Accessibility is non-negotiable**: ≥4.5:1 body contrast, ≥44×44px targets, visible focus ring,
   semantic HTML, keyboard reachable.
9. **Ship working code, not description.** Files that run, with structure and comments; no
   placeholders, no "add your content here" stubs.
10. **Complexity follows vision**, not habit. Restraint is a skill, not a shortcut.

## Workflow

### Step 1 — Direction Lock
State the purpose, audience, chosen tone and differentiation in one short paragraph before coding.
Name the display font, body font, dominant color and accent color explicitly.

### Step 2 — Foundations
Set up CSS variables for color, type scale, spacing, radius, shadow and motion. Choose light or
dark base deliberately. Define the type scale with real values.

### Step 3 — Composition
Lay out with asymmetry, overlap, diagonal flow or grid-breaking elements. Decide on generous
negative space or controlled density — then commit.

### Step 4 — Atmosphere
Add background treatment and texture layers matching the direction: gradient mesh, noise, grain,
geometric pattern, dramatic shadow, decorative border.

### Step 5 — Motion
Orchestrate one page-load sequence with staggered reveals. Add scroll-triggered reveals and hover
states that surprise. Use CSS first; Motion library for React when available.

### Step 6 — QA Against the Slop List
Run the anti-AI-slop checklist in `references/playbook.md` (or `references/zh-CN.md`). Fix every
hit before delivering. Verify contrast, focus states, reduced-motion and responsive behavior.

## Deliverables

| 交付物 | 内容 |
|---|---|
| **Design Direction Note** | 一段定调说明：受众、风格方向、字体与配色决策、记忆点 |
| **Working Frontend Code** | 可运行的 HTML/CSS/JS 或 React/Vue 组件，含完整结构与注释 |
| **Design Token Block** | CSS 变量：颜色、字阶、间距、圆角、阴影、动效时长 |
| **Motion Spec** | 入场序列、滚动触发、悬停反馈与降级方案 |
| **QA Checklist Result** | 反 AI 味清单、可访问性与响应式自检结果 |

## Resources

- `references/zh-CN.md` — **完整中文版**：设计思考协议、字体配对清单、色彩主题策略、动效编排、
  空间构成、氛围质感代码、反 AI 味清单、交付自检表。用户使用中文时必读。
- `references/playbook.md` — **完整英文版**：full design protocol, typography pairings, color
  strategy, motion orchestration, spatial composition, atmosphere recipes, anti-slop checklist,
  delivery QA sheet.
- `README.md` — 中英双语说明与使用场景，供技能市场展示。

Load the matching reference file before producing any deliverable. Never invent a font pairing or
effect recipe when one exists in the references.

## Quick Reference — Aesthetic Benchmarks

| 项目 | 基准值 |
|---|---|
| 展示字重量/字距 | 大标题 ≥ 48px，字距 -0.02em ~ -0.04em |
| 正文行长 | 45–75 字符（中文 28–40 字） |
| 行高 | 正文 1.5–1.7；大标题 0.95–1.1 |
| 配色比例 | 主色 60% / 辅助 30% / 强调 10% |
| 强调色使用 | 单页不超过 1 个强调色，用于关键动作 |
| 正文对比度 | ≥ 4.5:1（大字 ≥ 3:1） |
| 入场序列 | 3–6 组，间隔 60–120ms |
| 动效时长 | 微交互 150–200ms / 常规 300–400ms / 场景 600–800ms |
| 缓动 | `cubic-bezier(0.16, 1, 0.3, 1)`（出场）/ `ease-out`（入场） |
| 触摸目标 | ≥ 44×44px |
| 阴影层级 | 3 级，Y 偏移 2 / 8 / 24px |
| 首屏渲染预算 | 关键 CSS 内联，字体 `font-display: swap` |
```

#### frontend-dev

- 来源: 项目生成
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2052764137292271616\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `__MACOSX/._SKILL.md`, `__MACOSX/._canvas-fonts`, `__MACOSX/._references`, `__MACOSX/._scripts`, `__MACOSX/._templates`, `__MACOSX/canvas-fonts/._ArsenalSC-OFL.txt`, `__MACOSX/canvas-fonts/._ArsenalSC-Regular.ttf`, `__MACOSX/canvas-fonts/._BigShoulders-Bold.ttf`, `__MACOSX/canvas-fonts/._BigShoulders-OFL.txt`, `__MACOSX/canvas-fonts/._BigShoulders-Regular.ttf`, `__MACOSX/canvas-fonts/._Boldonse-OFL.txt`

```markdown
# Frontend Studio

Build complete, production-ready frontend pages by orchestrating 5 specialized capabilities: design engineering, motion systems, AI-generated assets, persuasive copy, and generative art.

## Invocation

```
/frontend-dev <request>
```

The user provides their request as natural language (e.g. "build a landing page for a music streaming app").

## Skill Structure

```
frontend-dev/
├── SKILL.md                      # Core skill (this file)
├── scripts/                      # Asset generation scripts
│   ├── minimax_tts.py            # Text-to-speech
│   ├── minimax_music.py          # Music generation
│   ├── minimax_video.py          # Video generation (async)
│   └── minimax_image.py          # Image generation
├── references/                   # Detailed guides (read as needed)
│   ├── minimax-cli-reference.md  # CLI flags quick reference
│   ├── asset-prompt-guide.md     # Asset prompt engineering rules
│   ├── minimax-tts-guide.md      # TTS usage & voices
│   ├── minimax-music-guide.md    # Music prompts & lyrics format
│   ├── minimax-video-guide.md    # Camera commands & models
│   ├── minimax-image-guide.md    # Ratios & batch generation
│   ├── minimax-voice-catalog.md  # All voice IDs
│   ├── motion-recipes.md         # Animation code snippets
│   ├── env-setup.md              # Environment setup
│   └── troubleshooting.md        # Common issues
├── templates/                    # Visual art templates
│   ├── viewer.html               # p5.js interactive art base
│   └── generator_template.js     # p5.js code reference
└── canvas-fonts/                 # Static art fonts (TTF + licenses)
```

## Project Structure

### Assets (Universal)

All frameworks use the same asset organization:

```
assets/
├── images/
│   ├── hero-landing-1710xxx.webp
│   ├── icon-feature-01.webp
│   └── bg-pattern.svg
├── videos/
│   ├── hero-bg-1710xxx.mp4
│   └── demo-preview.mp4
└── audio/
    ├── bgm-ambient-1710xxx.mp3
    └── tts-intro-1710xxx.mp3
```

**Asset naming:** `{type}-{descriptor}-{timestamp}.{ext}`

### By Framework

| Framework | Asset Location | Component Location |
|-----------|---------------|-------------------|
| **Pure HTML** | `./assets/` | N/A (inline or `./js/`) |
| **React/Next.js** | `public/assets/` | `src/components/` |
| **Vue/Nuxt** | `public/assets/` | `src/components/` |
| **Svelte/SvelteKit** | `static/assets/` | `src/lib/components/` |
| **Astro** | `public/assets/` | `src/components/` |

### Pure HTML

```
project/
├── index.html
├── assets/
│   ├── images/
│   ├── videos/
│   └── audio/
├── css/
│   └── styles.css
└── js/
    └── main.js           # Animations (GSAP/vanilla)
```

### React / Next.js

```
project/
├── public/assets/        # Static assets
├── src/
│   ├── components/
│   │   ├── ui/           # Button, Card, Input
│   │   ├── sections/     # Hero, Features, CTA
│   │   └── motion/       # RevealSection, StaggerGrid
│   ├── lib/
│   ├── styles/
│   └── app/              # Pages
└── package.json
```

### Vue / Nuxt

```
project/
├── public/assets/
├── src/                  # or root for Nuxt
│   ├── components/
│   │   ├── ui/
│   │   ├── sections/
│   │   └── motion/
│   ├── composables/      # Shared logic
│   ├── pages/
│   └── assets/           # Processed assets (optional)
└── package.json
```

### Astro

```
project/
├── public/assets/
├── src/
│   ├── components/       # .astro, .tsx, .vue, .svelte
│   ├── layouts/
│   ├── pages/
│   └── styles/
└── package.json
```

**Component naming:** PascalCase (`HeroSection.tsx`, `HeroSection.vue`, `HeroSection.astro`)

---

## Compliance

**All rules in this skill are mandatory. Violating any rule is a blocking error — fix before proceeding or delivering.**

---

## Workflow
### Phase 1: Design Architecture
1. Analyze the request — determine page type and context
2. Set design dials based on page type
3. Plan layout sections and identify asset needs

### Phase 2: Motion Architecture
1. Select animation tools per section (see Tool Selection Matrix)
2. Plan motion sequences following performance guardrails

### Phase 3: Asset Generation
Generate all image/video/audio assets using `scripts/`. NEVER use placeholder URLs (unsplash, picsum, placeholder.com, via.placeholder, placehold.co, etc.) or external URLs.

1. Parse asset requirements (type, style, spec, usage)
2. Craft optimized prompts, show to user, confirm before generating
3. Execute via scripts, save to project — do NOT proceed to Phase 5 until all assets are saved locally

### Phase 4: Copywriting & Content
Follow copywriting frameworks (AIDA, PAS, FAB) to craft all text content. Do NOT use "Lorem ipsum" — write real copy.

### Phase 5: Build UI
Scaffold the project and build each section following Design and Motion rules. Integrate generated assets and copy. All `<img>`, `<video>`, `<source>`, and CSS `background-image` MUST reference local assets from Phase 3.

### Phase 6: Quality Gates
Run final checklist (see Quality Gates section).

---

# 1. Design Engineering

## 1.1 Baseline Configuration

| Dial | Default | Range |
|------|---------|-------|
| DESIGN_VARIANCE | 8 | 1=Symmetry, 10=Asymmetric |
| MOTION_INTENSITY | 6 | 1=Static, 10=Cinematic |
| VISUAL_DENSITY | 4 | 1=Airy, 10=Packed |

Adapt dynamically based on user requests.

## 1.2 Architecture Conventions
- **DEPENDENCY VERIFICATION:** Check `package.json` before importing any library. Output install command if missing.
- **Framework:** React/Next.js. Default to Server Components. Interactive components must be isolated `"use client"` leaf components.
- **Styling:** Tailwind CSS. Check version in `package.json` — NEVER mix v3/v4 syntax.
- **ANTI-EMOJI POLICY:** NEVER use emojis anywhere. Use Phosphor or Radix icons only.
- **Viewport:** Use `min-h-[100dvh]` not `h-screen`. Use CSS Grid not flex percentage math.
- **Layout:** `max-w-[1400px] mx-auto` or `max-w-7xl`.

## 1.3 Design Rules
| Rule | Directive |
|------|-----------|
| Typography | Headlines: `text-4xl md:text-6xl tracking-tighter`. Body: `text-base leading-relaxed max-w-[65ch]`. **NEVER** use Inter — use Geist/Outfit/Satoshi. **NEVER** use Serif on dashboards. |
| Color | Max 1 accent, saturation < 80%. **NEVER** use AI purple/blue. Stick to one palette. |
| Layout | **NEVER** use centered heroes when VARIANCE > 4. Force split-screen or asymmetric layouts. |
| Cards | **NEVER** use generic cards when DENSITY > 7. Use `border-t`, `divide-y`, or spacing. |
| States | **ALWAYS** implement: Loading (skeleton), Empty, Error, Tactile feedback (`scale-[0.98]`). |
| Forms | Label above input. Error below. `gap-2` for input blocks. |

## 1.4 Anti-Slop Techniques

- **Liquid Glass:** `backdrop-blur` + `border-white/10` + `shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`
- **Magnetic Buttons:** Use `useMotionValue`/`useTransform` — never `useState` for continuous animations
- **Perpetual Motion:** When INTENSITY > 5, add infinite micro-animations (Pulse, Float, Shimmer)
- **Layout Transitions:** Use Framer `layout` and `layoutId` props
- **Stagger:** Use `staggerChildren` or CSS `animation-delay: calc(var(--index) * 100ms)`

## 1.5 Forbidden Patterns
| Category | Banned |
|----------|--------|
| Visual | Neon glows, pure black (#000), oversaturated accents, gradient text on headers, custom cursors |
| Typography | Inter font, oversized H1s, Serif on dashboards |
| Layout | 3-column equal card rows, floating elements with awkward gaps |
| Components | Default shadcn/ui without customization |

## 1.6 Creative Arsenal

| Category | Patterns |
|----------|----------|
| Navigation | Dock magnification, Magnetic button, Gooey menu, Dynamic island, Radial menu, Speed dial, Mega menu |
| Layout | Bento grid, Masonry, Chroma grid, Split-screen scroll, Curtain reveal |
| Cards | Parallax tilt, Spotlight border, Glassmorphism, Holographic foil, Swipe stack, Morphing modal |
| Scroll | Sticky stack, Horizontal hijack, Locomotive sequence, Zoom parallax, Progress path, Liquid swipe |
| Gallery | Dome gallery, Coverflow, Drag-to-pan, Accordion slider, Hover trail, Glitch effect |
| Text | Kinetic marquee, Text mask reveal, Scramble effect, Circular path, Gradient stroke, Kinetic grid |
| Micro | Particle explosion, Pull-to-refresh, Skeleton shimmer, Directional hover, Ripple click, SVG draw, Mesh gradient, Lens blur |

## 1.7 Bento Paradigm

- **Palette:** Background `#f9fafb`, cards pure white with `border-slate-200/50`
- **Surfaces:** `rounded-[2.5rem]`, diffusion shadow
- **Typography:** Geist/Satoshi, `tracking-tight` headers
- **Labels:** Outside and below cards
- **Animation:** Spring physics (`stiffness: 100, damping: 20`), infinite loops, `React.memo` isolation

**5-Card Archetypes:**
1. Intelligent List — auto-sorting with `layoutId`
2. Command Input — typewriter + blinking cursor
3. Live Status — breathing indicators
4. Wide Data Stream — infinite horizontal carousel
5. Contextual UI — staggered highlight + float-in toolbar

## 1.8 Brand Override

When brand styling is active:
- Dark: `#141413`, Light: `#faf9f5`, Mid: `#b0aea5`, Subtle: `#e8e6dc`
- Accents: Orange `#d97757`, Blue `#6a9bcc`, Green `#788c5d`
- Fonts: Poppins (headings), Lora (body)

---

# 2. Motion Engine

## 2.1 Tool Selection Matrix

| Need | Tool |
|------|------|
| UI enter/exit/layout | **Framer Motion** — `AnimatePresence`, `layoutId`, springs |
| Scroll storytelling (pin, scrub) | **GSAP + ScrollTrigger** — frame-accurate control |
| Looping icons | **Lottie** — lazy-load (~50KB) |
| 3D/WebGL | **Three.js / R3F** — isolated `<Canvas>`, own `"use client"` boundary |
| Hover/focus states | **CSS only** — zero JS cost |
| Native scroll-driven | **CSS** — `animation-timeline: scroll()` |

**Conflict Rules [MANDATORY]:**
- NEVER mix GSAP + Framer Motion in same component
- R3F MUST live in isolated Canvas wrapper
- ALWAYS lazy-load Lottie, GSAP, Three.js

## 2.2 Intensity Scale

| Level | Techniques |
|-------|------------|
| 1-2 Subtle | CSS transitions only, 150-300ms |
| 3-4 Smooth | CSS keyframes + Framer animate, stagger ≤3 items |
| 5-6 Fluid | `whileInView`, magnetic hover, parallax tilt |
| 7-8 Cinematic | GSAP ScrollTrigger, pinned sections, horizontal hijack |
| 9-10 Immersive | Full scroll sequences, Three.js particles, WebGL shaders |

## 2.3 Animation Recipes

See `references/motion-recipes.md` for full code. Summary:

| Recipe | Tool | Use For |
|--------|------|---------|
| Scroll Reveal | Framer | Fade+slide on viewport entry |
| Stagger Grid | Framer | Sequential list animations |
| Pinned Timeline | GSAP | Horizontal scroll with pinning |
| Tilt Card | Framer | Mouse-tracking 3D perspective |
| Magnetic Button | Framer | Cursor-attracted buttons |
| Text Scramble | Vanilla | Matrix-style decode effect |
| SVG Path Draw | CSS | Scroll-linked path animation |
| Horizontal Scroll | GSAP | Vertical-to-horizontal hijack |
| Particle Background | R3F | Decorative WebGL particles |
| Layout Morph | Framer | Card-to-modal expansion |

## 2.4 Performance Rules
**GPU-only properties (ONLY animate these):** `transform`, `opacity`, `filter`, `clip-path`

**NEVER animate:** `width`, `height`, `top`, `left`, `margin`, `padding`, `font-size` — if you need these effects, use `transform: scale()` or `clip-path` instead.

**Isolation:**
- Perpetual animations MUST be in `React.memo` leaf components
- `will-change: transform` ONLY during animation
- `contain: layout style paint` on heavy containers

**Mobile:**
- ALWAYS respect `prefers-reduced-motion`
- ALWAYS disable parallax/3D on `pointer: coarse`
- Cap particles: desktop 800, tablet 300, mobile 100
- Disable GSAP pin on mobile < 768px

**Cleanup:** Every `useEffect` with GSAP/observers MUST `return () => ctx.revert()`

## 2.5 Springs & Easings

| Feel | Framer Config |
|------|---------------|
| Snappy | `stiffness: 300, damping: 30` |
| Smooth | `stiffness: 150, damping: 20` |
| Bouncy | `stiffness: 100, damping: 10` |
| Heavy | `stiffness: 60, damping: 20` |

| CSS Easing | Value |
|------------|-------|
| Smooth decel | `cubic-bezier(0.16, 1, 0.3, 1)` |
| Smooth accel | `cubic-bezier(0.7, 0, 0.84, 0)` |
| Elastic | `cubic-bezier(0.34, 1.56, 0.64, 1)` |

## 2.6 Accessibility
- ALWAYS wrap motion in `prefers-reduced-motion` check
- NEVER flash content > 3 times/second (seizure risk)
- ALWAYS provide visible focus rings (use `outline` not `box-shadow`)
- ALWAYS add `aria-live="polite"` for dynamically revealed content
- ALWAYS include pause button for auto-playing animations

## 2.7 Dependencies

```bash
npm install framer-motion           # UI (keep at top level)
npm install gsap                    # Scroll (lazy-load)
npm install lottie-react            # Icons (lazy-load)
npm install three @react-three/fiber @react-three/drei  # 3D (lazy-load)
```

---

# 3. Asset Generation

## 3.1 Scripts

| Type | Script | Pattern |
|------|--------|---------|
| TTS | `scripts/minimax_tts.py` | Sync |
| Music | `scripts/minimax_music.py` | Sync |
| Video | `scripts/minimax_video.py` | Async (create → poll → download) |
| Image | `scripts/minimax_image.py` | Sync |

Env: `MINIMAX_API_KEY` (required).

## 3.2 Workflow
1. **Parse:** type, quantity, style, spec, usage
2. **Craft prompt:** Be specific (composition, lighting, style). **NEVER** include text in image prompts.
3. **Execute:** Show prompt to user, **MUST confirm before generating**, then run script
4. **Save:** `<project>/public/assets/{images,videos,audio}/` as `{type}-{descriptor}-{timestamp}.{ext}` — **MUST save locally**
5. **Post-process:** Images → WebP, Videos → ffmpeg compress, Audio → normalize
6. **Deliver:** File path + code snippet + CSS suggestion

## 3.3 Preset Shortcuts

| Shortcut | Spec |
|----------|------|
| `hero` | 16:9, cinematic, text-safe |
| `thumb` | 1:1, centered subject |
| `icon` | 1:1, flat, clean background |
| `avatar` | 1:1, portrait, circular crop ready |
| `banner` | 21:9, OG/social |
| `bg-video` | 768P, 6s, `[Static shot]` |
| `video-hd` | 1080P, 6s |
| `bgm` | 30s, no vocals, loopable |
| `tts` | MiniMax HD, MP3 |

## 3.4 Reference

- `references/minimax-cli-reference.md` — CLI flags
- `references/asset-prompt-guide.md` — Prompt rules
- `references/minimax-voice-catalog.md` — Voice IDs
- `references/minimax-tts-guide.md` — TTS usage
- `references/minimax-music-guide.md` — Music generation (prompts, lyrics, structure tags)
- `references/minimax-video-guide.md` — Camera commands
- `references/minimax-image-guide.md` — Ratios, batch

---

# 4. Copywriting

## 4.1 Core Job

1. Grab attention → 2. Create desire → 3. Remove friction → 4. Prompt action

## 4.2 Frameworks

**AIDA** (landing pages, emails):
```
ATTENTION:  Bold headline (promise or pain)
INTEREST:   Elaborate problem ("yes, that's me")
DESIRE:     Show transformation
ACTION:     Clear CTA
```

**PAS** (pain-driven products):
```
PROBLEM:    State clearly
AGITATE:    Make urgent
SOLUTION:   Your product
```

**FAB** (product differentiation):
```
FEATURE:    What it does
ADVANTAGE:  Why it matters
BENEFIT:    What customer gains
```

## 4.3 Headlines

| Formula | Example |
|---------|---------|
| Promise | "Double open rates in 30 days" |
| Question | "Still wasting 10 hours/week?" |
| How-To | "How to automate your pipeline" |
| Number | "7 mistakes killing conversions" |
| Negative | "Stop losing leads" |
| Curiosity | "The one change that tripled bookings" |
| Transformation | "From 50 to 500 leads" |

Be specific. Lead with outcome, not method.

## 4.4 CTAs

**Bad:** Submit, Click here, Learn more

**Good:** "Start my free trial", "Get the template now", "Book my strategy call"

**Formula:** [Action Verb] + [What They Get] + [Urgency/Ease]

Place: above fold, after value, multiple on long pages.

## 4.5 Emotional Triggers

| Trigger | Example |
|---------|---------|
| FOMO | "Only 3 spots left" |
| Fear of loss | "Every day without this, you're losing $X" |
| Status | "Join 10,000+ top agencies" |
| Ease | "Set it up once. Forget forever." |
| Frustration | "Tired of tools that deliver nothing?" |
| Hope | "Yes, you CAN hit $10K MRR" |

## 4.6 Objection Handling

| Objection | Response |
|-----------|----------|
| Too expensive | Show ROI: "Pays for itself in 2 weeks" |
| Won't work for me | Social proof from similar customer |
| No time | "Setup takes 10 minutes" |
| What if it fails | "30-day money-back guarantee" |
| Need to think | Urgency/scarcity |

Place in FAQ, testimonials, near CTA.

## 4.7 Proof Types

Testimonials (with name/title), Case studies, Data/metrics, Social proof, Certifications

---

# 5. Visual Art

Philosophy-first workflow. Two output modes.

## 5.1 Output Modes

| Mode | Output | When |
|------|--------|------|
| Static | PDF/PNG | Posters, print, design assets |
| Interactive | HTML (p5.js) | Generative art, explorable variations |

## 5.2 Workflow

### Step 1: Philosophy Creation
Name the movement (1-2 words). Articulate philosophy (4-6 paragraphs) covering:
- Static: space, form, color, scale, rhythm, hierarchy
- Interactive: computation, emergence, noise, parametric variation

### Step 2: Conceptual Seed
Identify subtle, niche reference — sophisticated, not literal. Jazz musician quoting another song.

### Step 3: Creation

**Static Mode:**
- Single page, highly visual, design-forward
- Repeating patterns, perfect shapes
- Sparse typography from `canvas-fonts/`
- Nothing overlaps, proper margins
- Output: `.pdf` or `.png` + philosophy `.md`

**Interactive Mode:**
1. Read `templates/viewer.html` first
2. Keep FIXED sections (header, sidebar, seed controls)
3. Replace VARIABLE sections (algorithm, parameters)
4. Seeded randomness: `randomSeed(seed); noiseSeed(seed);`
5. Output: single self-contained HTML

### Step 4: Refinement
Refine, don't add. Make it crisp. Polish into masterpiece.

---

# Quality Gates
**Design:**
- [ ] Mobile layout collapse (`w-full`, `px-4`) for high-variance designs
- [ ] `min-h-[100dvh]` not `h-screen`
- [ ] Empty, loading, error states provided
- [ ] Cards omitted where spacing suffices

**Motion:**
- [ ] Correct tool per selection matrix
- [ ] No GSAP + Framer mixed in same component
- [ ] All `useEffect` have cleanup returns
- [ ] `prefers-reduced-motion` respected
- [ ] Perpetual animations in `React.memo` leaf components
- [ ] Only GPU properties animated
- [ ] Heavy libraries lazy-loaded

**General:**
- [ ] Dependencies verified in `package.json`
- [ ] **No placeholder URLs** — grep the output for `unsplash`, `picsum`, `placeholder`, `placehold`, `via.placeholder`, `lorem.space`, `dummyimage`. If ANY found, STOP and replace with generated assets before delivering.
- [ ] **All media assets exist as local files** in the project's assets directory
- [ ] Asset prompts confirmed with user before generation

---

*React and Next.js are trademarks of Meta Platforms, Inc. and Vercel, Inc., respectively. Vue.js is a trademark of Evan You. Tailwind CSS is a trademark of Tailwind Labs Inc. Svelte and SvelteKit are trademarks of their respective owners. GSAP/GreenSock is a trademark of GreenSock Inc. Three.js, Framer Motion, Lottie, Astro, and all other product names are trademarks of their respective owners.*
```

#### html-deploy

- 来源: 项目生成
- 说明: Publish a single self-contained HTML page to htmlcode.fun and return live URLs. Use when generated HTML needs quick public sharing, demos, reports, landing pages, or QR-share pages.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2054901495867834368\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `_meta.json`, `scripts/htmlcode_deploy.py`

```markdown
# HTML Instant Deploy

## Overview

Use `htmlcode.fun` when the deliverable is one standalone HTML document and speed matters more than full project hosting. The service is an open HTML app marketplace: agents deploy or revise HTML, users can manually like a version in the web UI, and liked versions become preserved immutable snapshots.

Live guide:
- https://www.htmlcode.fun/s/htmlcode-fun-guide

Bundled script:
- `scripts/htmlcode_deploy.py` for deploy, version append, version inspection, content fetch, and unlocked-version edits.

## Decision rule

Use this skill when:
- The deliverable is a single HTML page.
- The page can be self-contained or nearly self-contained.
- Fast sharing matters more than custom domains, CI/CD, or multi-file assets.

Do not use this skill when:
- The project is a React, Vue, Next, or multi-file frontend app.
- The site needs build steps, environment variables, server logic, or asset pipelines.
- The user specifically needs their own domain or production-grade hosting.
- The HTML payload is likely to exceed about 1 MB.

## Current htmlcode.fun rules

- Always use JSON; never use multipart/form-data or `curl -F`.
- `description` is required: one concise sentence, max 240 characters.
- One request deploys one HTML document only.
- Stable projects should use `enableCustomCode=true` + `customCode`.
- For recurring or iterative work, append a new version with `createVersion=true` instead of creating daily/random short codes.
- A version with `likeCount > 0` is locked and must not be overwritten or deleted.
- An unlocked version (`likeCount == 0`) may be overwritten or unpublished when appropriate.
- Agents must not call like endpoints. Likes are intentionally user/manual actions in the htmlcode.fun web UI.
- After deploy, tell the user the returned `url`, `detailUrl`, and/or `versionUrl`, plus the returned `preserveHint` when present.
- Successful deploys have a global cooldown of about 10 seconds. On `429`, respect `retryAfterSeconds`.

## Recommended workflows

### New one-off page

1. Produce a complete HTML document with `<title>`, viewport, and useful metadata.
2. Deploy with `POST /api/deploy` and a required `description`.
3. Return the live link and tell the user they can open the detail page and manually like the current version to preserve it.

Script:

```bash
python scripts/htmlcode_deploy.py deploy page.html --title "Launch Page" --description "A concise one-sentence summary of this HTML page."
```

### Stable short link or recurring project

Use a stable `customCode`; append new versions for future updates.

```bash
python scripts/htmlcode_deploy.py deploy page.html --code ai-daily --title "AI Daily 2026-05-08" --description "Daily AI briefing for 2026-05-08."
python scripts/htmlcode_deploy.py append ai-daily page.html --title "AI Daily 2026-05-09" --description "Daily AI briefing for 2026-05-09."
```

### Inspect or reuse an app

```bash
python scripts/htmlcode_deploy.py versions ai-daily
python scripts/htmlcode_deploy.py get ai-daily --version 3 --output ai-daily-v3.html
```

By default, `get --output` writes the HTML `content` field to the file. Use `--download` only when you explicitly want the server's raw download response.

### Fix an existing version

Before overwriting, inspect versions. Only overwrite if the target version has `likeCount == 0`. If it has likes, append a new version instead.

```bash
python scripts/htmlcode_deploy.py versions landing-demo
python scripts/htmlcode_deploy.py overwrite landing-demo 2 fixed.html --description "Fixes layout issues in version 2."
```

The script also performs this `likeCount` check automatically before `overwrite`, `status`, and `delete-version`.

### Publish or unpublish one version

```bash
python scripts/htmlcode_deploy.py status landing-demo 2 inactive
python scripts/htmlcode_deploy.py status landing-demo 2 active
```

## Raw API map

- `POST /api/deploy` — deploy a new app or append a version with `createVersion=true`.
- `GET /api/deploy/content?code={code}&version={version}` — read metadata and source.
- `GET /api/deploys/{code}/versions` — list version history and `likeCount`.
- `PATCH /api/deploys/{code}/versions/{version}` — overwrite or set status for an unlocked version.
- `DELETE /api/deploys/{code}/versions/{version}` — delete one unlocked version. Treat deletion as sensitive; ask first unless the user explicitly requested it.
- `PATCH /api/deploys/{code}/current` — switch the public current version when needed.

## Response handling

On success, save and report relevant fields:
- `code`
- `url`
- `detailUrl`
- `versionUrl`
- `versionNumber`
- `qrCode`
- `preserveHint`

If an API response contains `errorCode`, `hint`, `detail`, `stage`, `requestId`, or `retryAfterSeconds`, use those fields in troubleshooting. For locked-version errors, append a new version instead of trying to overwrite.

## Best practices for agents

- Prefer one high-quality deploy over many tiny edits.
- For user-visible pages, include Open Graph tags when sharing matters.
- Keep CSS/JS inline when practical; avoid large base64 images.
- Use meaningful stable codes for recurring content, e.g. `ai-daily`, not `ai-daily-0508`.
- If updating an existing code, read versions first and avoid touching liked versions.
- Treat htmlcode.fun as a fast publication channel, not a full static hosting platform.
- Tell the user when Vercel, Netlify, GitHub Pages, or a real app host is a better fit.

## Good fit

- Temporary landing pages
- Demo pages
- Shareable documentation pages
- QR-linked event or campaign pages
- AI-generated single-file frontends
- Recurring reports with stable short links and version history

## Poor fit

- Multi-page sites with shared assets
- Framework builds
- Large production frontends
- Apps requiring backend auth, databases, or secrets
- Team workflows with preview environments and rollback controls
```

#### edgeone

- 来源: 项目生成
- 说明: Deploy a single HTML document to Tencent EdgeOne Pages via mcporter with no login or API key, returning a public URL. Use when a user wants generated HTML published quickly as a live webpage.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2054901302965608448\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `_meta.json`

```markdown
# EdgeOne
Deploy HTML content to EdgeOne Pages, return the public URL. No login required, no API key required.

## Deploy HTML
HTML or text content to deploy. Provide complete HTML or text content you want to publish, and the system will return a public URL where your content can be accessed.
```shell
npx -y mcporter call mcp-on-edge.edgeone.app/mcp-server.deploy-html value="<html>Content</html>"
npx -y mcporter call mcp-on-edge.edgeone.app/mcp-server.deploy-html value="$(cat index.html)"
```
```

#### ui-style-lab

- 来源: 自建
- 说明: 全自动「UI/UX 视觉风格探索实验室」——围绕一个对标基准，自主生成 3 个极端变体、自我批判、选出赢家并合成新基准，循环迭代。当用户要求「持续探索不同风格的网页」「自动迭代设计」「当实验室主理人」「不断产出变体」时使用。
- 路径: `C:\Users\lenovo\.workbuddy\skills\ui-style-lab\SKILL.md`

```markdown
# UI/UX 视觉风格探索实验室

## 悦皓的两条视觉铁律（默认遵守，不必每次问）

- **铁律 A · 自然风景感**：视觉主体要有真实地貌/自然体积感（山体、岩层、水、雾）。禁止用抽象几何、纯渐变、赛博网格、扁平插画充当主角。锚定范例 = Lithos（顶光 3D 山脊 + 发光岩缝）。
- **铁律 B · 视差滚动是硬需求**：必须有分层景深 + 滚动驱动的场景变化。静态单屏 hero 不算过关。

## 循环协议（每轮四步，全程不提问）

1. **定基准**：选一个对标（本轮 = Lithos）。
2. **做 3 个变体**：每个必须明确改变 **颜色 / 动效 / 字体 / 排版** 中至少两项，且三个之间不能互相像。
3. **自我批判**：切换成「极度挑剔的甲方」，对比 3 变体 + 基准，选出最有突破的一个，写出**核心亮点 + 致命缺点**（缺点必须具体、可修）。
4. **迭代**：修复赢家的致命缺点，吸收另外两个的长处，定为新基准 N+1，立刻进入下一轮。
5. 每 5–10 轮输出一份 ≤100 字「灵感日志」。每次回复末尾给代码 + 预览链接。
6. 上下文丢失时，先复述「当前基准 + 下一轮方向」再继续。

## 已验证的有效碰撞方向（可直接复用）

| 变体 | 颜色 | 字体 | 排版 | 动效 | 结果 |
|---|---|---|---|---|---|
| Swiss Minimal | 纸白 + 墨黑，反相 | Inter / IBM Plex Mono | 12 栏网格、左对齐、细分割线 | 匀速无弹性（刻意无 lerp） | 最专业，突破最低 |
| Neon Retro | 紫黑 + 品红/青 | Orbitron / Space Mono | 居中、CRT 扫描线 | 呼吸脉冲 + 落日下沉 | 最炸，但语汇过度使用 |
| Avant Magazine | 新闻纸 + 朱红 | Anton / Archivo | 旋转 -2.6°、压字、套印 | 12 台阶 stop-motion | 最突破，但可读性差 |
| **Ink & Fault (2.0)** | 纸 + 墨 + 单一红 | Anton / Space Mono | 12 栏 + 印刷黑条 | 步进 + 单条呼吸断层线 | 赢家合成 |
| Blueprint | 蓝图蓝 + 荧光黄 | IBM Plex Mono | 图纸图框、图号 | setDrawRange 逐行「画出来」 | 概念好，线框无遮挡 |
| Ink-wash | 宣纸 + 墨 | Cormorant / Noto Serif SC | 竖排中文题跋 + 朱印 | 极慢呼吸 + 卷轴横移 | 耐看，但太静 |
| **Instrument (V2C)** | 黑 + 橙磷光 | JetBrains Mono | HUD 四角括号 + 巨型读数 | 扫描线 + 点云抖动 | 最突破（渲染→测量），点云无体积 |
| **Measured Ground (3.0)** | 纸墨 + 橙扫描 | Anton / JetBrains Mono | 12 栏 + 侧边 HUD | 仪器扫描 × 滚动下潜双时间轴 | 赢家合成 |
| 深空地球 404 | 深空黑 + 蓝白 | Grotesque | 居中行星 + 大字 | 星云缓移 + 大气辉光 | 概念好，主体太远 |
| 朱红编辑 / 群青丁达尔 / 紫铜双材质 | — | — | — | — | → 朱红编辑（基准 4.0 血缘） |
| 灰烬琥珀 / 竖排墨金 / 高调晨雾 | — | — | — | — | → **竖排墨金**（基准 5.0）；高调雾洗细节是致命伤 |
| 深海沉船绿 / 极光夜 / 炭笔素描 | 青绿+锈橙 / 靛黑+绿紫 / 单色石墨+朱红 | 压缩窄体 / 超细无衬线小写 / 手绘衬线斜体 | 左标尺 / 底巨号 / 基准线标注 | 气泡+焦散 / 双层异速极光 / 炭粉下落+排线加密 | → **炭笔素描**（基准 6.0）；极光带几乎不可见=致命 |
| 火山渣 / 盐湖镜面 / 风化铜绿 | 暗红黑 / 亮盐白 / 青铜孔雀石 | 压缩粗黑 / 极细小写 / 碑铭衬线大写 | 贴底 / 居中原色卡 / 铜牌铭文框 | 抛物线火山弹+落灰 / box-reflect 倒影 / 金属扫光+氧化蔓延 | → **风化铜绿**（基准 7.0）；亮底+雾雾洗到清晰 956=灾难 |
| 黑曜石玻璃 / 铁锈荒原 / 晶洞 | 镜面黑+琥珀 / 赭红氧化铁 / 暖褐壳+覆盆子 | 超细无衬线大写超宽字距 / 几何无衬线大写 / Bodoni 高对比斜体 | 左上巨字 / 底部通栏+顶条 / 左巨字+贴边卷标 | 玻璃折射闪 / 锈水渗流+风蚀横刮 / 晶面闪烁+洞内呼吸 | → **晶洞**（基准 8.0）；镜面压细节(清晰5497)+通栏条压 nav=否决 |
| 玛瑙同心纹 / 陨铁 Widmanstätten / 深海热泉白烟囱 | 橙红玉髓 / 暖褐镍铁(冷) / 硫黄金黄+深墨 | 人文衬线大写 / 等宽技术报告 / Palatino 粗衬线 | 居中环心铭文 / 右上等宽（写反→左上）/ 左下对角+二行缩进 | 同心环|SVG 弧线铭文 / 60°交叉网纹+镜面扫光 / 热液烟柱上升 | → **深海热泉**（基准 9.0）；冷色丢暖(暖 3.11%)+标题压 nav=否决 |
| 岩体岩石化（第10轮·基准改造非变体） | 中性灰褐岩体 + 硫黄华仅留喷口 | 不变（Palatino 粗衬线） | 不变 | 不变（只改材质/几何/大气） | → **基准 10.0 黑烟囱岩体**；块内拟合+每块随机倾角出折棱、噪声降频去沙、雾色冷化远山变岩；清晰度 9583→~5400、暖 69%→~41% 是**必然权衡**（大块面 vs 像素细节天然对立） |

| 岩生植被（第11轮·基准加层非变体） | 不变（岩体） + 灰绿草/深绿地衣 | 不变 | 前景草簇 + 中景沿节理绿脉络 | 新增：风动（uv.y^1.55 + 阵风，相位随机） | → **基准 11.0**；清晰 5380→**6090(+13.2%)**、暖 40.5%→41.2%、亮度/对比持平 —— **植被的高频细节把大块面掉下去的清晰度补回来了**；关键是 AO 积土筛选 + 节理脉络 + 丛生化，不是"多撒草" |

**路线级规律（跨轮实测）**：暖强调面积 ≥65% 才是"自然风景感"的血统线；冷色方案（陨铁 3.1%、黑曜石 26.6%、极光 0.26%）在这一血统里必输。高调亮底（盐湖 203 / 晨雾 172）配雾必雾洗，清晰度会掉到 1000 以下 —— 亮底方案禁雾。saturated 暖黄（硫黄 / 琥珀 / 铁锈）比红系（朱红 / 血玉髓）更容易同时拿到高清晰度与高暖面积，因为黄系 hue 集中在 40-60 且亮度更高。

## 📌 继承毒素扫描（每代基准必做，2026-09-23 血泪新增）

**变体 CSS 里的 `!important` 会静默继承给之后每一代，且极难被发现。**

真实事故：第 5 轮 B 变体为了做竖排标题，给 `#h1` 注入了 `writing-mode:vertical-rl !important`。
它进了基准 5.0 之后，第 6 轮的 A/B/C 三个变体 + 融合基准 v6 的巨字**全部被折成竖柱**，
压住 meta 段、朱印、标签 —— 连花 3 个补丁去修 `br{display:inline}`，全是误判。

**协议**：每代基准开工前，先扫上一代 CSS 里的**结构性属性**，逐条判断后代是否需要复位：

```
writing-mode / text-transform / white-space / display / position / flex-direction
/ align-items / justify-content / z-index / overflow / transform
```

- 后代 CSS 明确写 `属性:初始值 !important;` 复位（同权重下后者胜）。
- 结构属性 **永远不要在变体里用 `!important`**，用更高选择器特异性替代。

## 📌 可见性验收：DOM 有值 ≠ 肉眼可见（2026-09-23 自查抓到的真 bug）

`#bar`（z-index 13）被 `#marq` 跑马灯（z-index 15）盖住。脚本读
`document.getElementById('ascbar').textContent` → `"ASCENT 100%"`，一切"正常"；
截图里那一行**根本看不见**。量化全绿，交付是废的。

**协议（加进每轮验收）**：
1. 关键新元素截图后裁它的 `getBoundingClientRect` 区域，算局部亮度方差，确认非空非糊。
2. playwright 读目标元素 bbox + 遍历同区域上层元素的 `zIndex` / `position`，判断是否被遮挡。
3. 别只信 `textContent` / `style.height` 这类 DOM 值。

## 硬经验（滚动累积，编号即优先级）

1. **印刷感 + 真实体积可以共存**：顶点色做三色/五色调硬分层（给出刀刻边界），材质仍用受光的 `MeshStandardMaterial`（给出体积）。千万别为了「印刷感」改用 `MeshBasicMaterial` —— 山会立刻变成海报。
2. **量化级数**：`Math.round(tone*5)/5` 是折中点。低于 4 级像海报，高于 8 级失去刀刻感。
3. **陡坡加密 = 木刻排线**：`normal.z` 越小越黑，廉价地把体积读出来。
4. **高饱和色整页只留一个**（一条线 / 一个按钮 / 一个读数），比满屏霓虹高级。
5. **扫描 / 能量效果搬到实体网格**（优于点云）：`onBeforeCompile` 注入 `uniform uScan` + varying（Plane 局部 `position.y` 归一化即得 v 轴坐标），在 `#include <emissivemap_fragment>` 后叠加 `totalEmissiveRadiance`。点云方案会让主体在被扫到之外消失，违反铁律 A。
6. **两条独立时间轴**比一条好：机器轴（连续扫描/自转，永不停）+ 人轴（滚动下潜），视差立刻有了层次。
7. **清晰度（Laplacian 方差）杠杆排序**（2026-09-23 实测）：`法线强度 normalScale↑` > `岩体 albedo 颗粒振幅↑` > `Bloom↓`（Bloom 是低通，直接吃高频）> `envMapIntensity↓`（换局部对比）> 贴纸纹/排线覆盖层。
8. **暖化岩体 albedo 一石二鸟**：把岩体反照率乘 `vec3(r>1, g≈1, b<1)` 会**同时**抬高「暖强调色面积」和「清晰度」—— 因为 Laplacian 算在灰度上，红通道被放大 → 灰度梯度整体变大。这是暖强调回补时最省力的杠杆，比加熔岩/加 UI 有效一个数量级。
9. **暖强调有阈值效应**：饱和度跨过 0.35 的瞬间，面积会从 6% 跳到 32%、再跳到 55%。别小步试探，要一步跨过去再回压。
10. **截图量化有 ±5% 噪声**（2026-09-23 实测：同一文件三次 6422 / 6752 / 6741）：熔岩 boil、相机 lerp、粒子相位都随时间变。验收必须**同文件连测 2 次取均值**，且达标线要留 ≥5% 余量，别拿单次贴线的值当过线。
11. **大面积平滑层是清晰度暗杀手**：screen 混合的地平线光带（占 38vh×全宽的平滑渐变）+ meta/CTA 的平色暗底卡都在给 Laplacian 方差"注水稀释"。修法 = 光带收窄降透明（38vh/.30 → 24vh/.16 一轮就回血 500+），平色卡只给真正压在亮坡上的文字用。
12. **参数杠杆收益递减要换杠杆**：法线 2.35→2.75、Bloom 0.18→0.10 这类参数连拉三轮收益趋零（噪声级）；此时换结构性杠杆（减冷色面积 / 减平滑覆盖层 / 提纸纹颗粒）立刻再涨 500。
13. **同 y 带 = 必冲突**（2026-09-23 第8轮）：往固定层体系里加新元素（数据条 / 铭牌 / 标注）前，**先列出该 y 带已有哪些固定元素**。#spec2(top:13.4vh) 与 #rule(top:12.6vh) + 它的 `::before`（top+7px）三行文字直接叠成一团 —— 两处都"各自正确"，只有同带才炸。加层前把 y 坐标排成一列看一遍，比事后截图快十倍。
14. **变体超线 ≠ 基准超线**：第8轮 C 变体首测清晰 7440（> 基准 7256），二测 7151 → 均值仅 +0.7%，贴线通过。**裁决变体时也要双测**，否则会把一个"其实和基准持平"的方案当成胜者，后面迭代地基就虚了。
15. **结构杠杆的优先级排序（第8轮实测更新）**：`收窄/关闭 mix-blend-mode:screen 平滑层`（oxide .24→.12、blush 15vh→11vh 各值数百点）> `提升锐利噪声层`（paper 纸纹 / hatch 排线，直接吃 Laplacian）> `岩石 albedo 颗粒振幅` > `法线强度`。**平滑层永远第一个动**。
16. **居中大圆环 = 零成本构图锚点**：半出画的小圆既是"元素不可见"又是"某侧空洞"的成因。把它改成套住主体的大圆环（居中、直径≈视口高、`z-index` 压到标题层之下、圆环 + 虚线外环 + 内发光），一次性解决两个问题，还白送一条结构语言。
17. **顶部通栏条必须挂在 nav 之下**（`top:70px` 起，nav 高约 66px）。任何 `top:0` 的全宽条都会把 logo / menu / CTA 全压住 —— 这是可以直接否决方案的低级工程错，不要等截图才发现。
18. **标题可读性保护：局部锐利梯度 ✔ / 全屏平滑层 ✘**（2026-09-23 第9轮翻车实录）：为了让标题压在岩体上也读得清，写了一条全宽 `height:58vh` 的暗渐变 → 清晰度 **10211 → 4986（−51%）**、亮度 73.7 → 51.0。改成「紧致椭圆暗晕（52vw×32vh，径向 82% 处归零）+ 多层黑 `text-shadow`（0 1px 3px / 0 3px 12px / 0 0 30px / 0 8px 56px）」后清晰度回到 9825。**原理：text-shadow 是贴着字形的锐利梯度，几乎不动全局 Laplacian；全屏渐变是平滑层，直接把整幅的局部方差抹平。** 任何"为了可读性"加的层，先问它覆盖多少面积。
19. **派生变体前先做 `.hero` 方向自查**：`flex-direction:column` 容器里 **`justify-content` 管垂直、`align-items` 管水平**（这条第6轮已记，第9轮 C 变体又写反 → `align-items:flex-end; justify-content:flex-start` 本意"左下"，实际渲染成"右上贴顶"，巨字直接压住 nav 通栏）。每写一个 `.hero{...!important}`，都念一遍"align=水平, justify=垂直"再落笔。
20. **HTML 文本里不能写 CSS 转义**：`\00b0C` 只在 CSS `content` 里合法；写进 HTML 文本会在页面上原样显示反斜杠（本轮 C 的 `FLUID 348 \00b0C` 就是这样）。HTML 用 `&#176;` / `&mdash;`，CSS `content` 才用 `\00b0` / `\2014`。**两套转义体系别串台。**
21. **"结构语言"的落地判据 = 截图里能指名道姓看出形状**：本轮 C 的羽流写了几十行 JS 却几乎不可见，两个叠加原因 —— ①子元素 `bottom` 用 `vh` 定位，而父容器只有 44vh 高 + `overflow:hidden` → 大半粒子被裁掉；②容器 `z-index:12`，同区还有一片更高 z 的装饰层。**写完任何结构元素，必须用 `_dbg*.cjs` 打印它的 bbox，并确认 bbox 落在父容器内、且不被更高 z 的同区元素压住**。写了 ≠ 落地。
22. **动效相位是量化噪声源，能收敛抖动的参数才是好参数**：羽流粒子速度 0.9-2.1 时，同一文件两测 8904 / 9841（−9.5%，远超 ±5% 经验噪声）；把速度降到 0.36-0.82 后两测 9589 / 9577（−0.1%）。**双测差值是动效参数的一个隐藏验收项** —— 差值大说明动效状态不稳定，即便单测达标也该修。
23. **锚点断言要按"全局唯一"校验**：`const N = 34, els = [];` 在本文件里同时属于 spark 与 plume 两段注入 JS，`need=1` 会直接断言失败 —— 这是断言救下来的一次事故。**同名锚点会跨注入块重复**，此时必须换更大的上下文（带上相邻的独有行）而不是放宽 `need`。
24. **"像土"还是"像石"，第一凶手是噪声频率**（2026-09-23 第10轮）：程序化噪声的频率必须与**几何网格尺寸 / 肉眼可见颗粒尺寸**对齐。地形 640 段 / 52 世界单位 → 网格 0.081 单位 ≈ 屏幕 7px；此时用 `noise(xz*150)` 的屏幕周期只有 3px = **逐像素沙粒**，无论叠多大的岩块面都会被糊成"土/沙"。降到 `*52 ~ *150`（颗粒 8-20px）后细沙感立刻消失。**改任何表面噪声前，先算它的屏幕周期 = 世界周期 × 像素/世界单位。**
25. **"土"的频谱是中频，岩石是"低频块面 + 高频矿粒"**：土/植被占据中频（团粒、绒毛、苔斑）；岩石 = **低频岩块平面（几十 px 的折面）+ 高频矿物颗粒/晶面反光（8-20px）**，中间那段要主动砍掉。做岩石感 = 两端加强 + 中频压制，不是"整体加噪声"。
26. **块内最小二乘拟合 ≠ faceting，它只是低通滤波**：把每个岩块内的顶点压向该块的拟合平面，**若相邻块平均坡度相近，平面就近似连续，块间没有折角 —— 视觉上只是"变糊"**（第10轮 d/e 两轮清晰度反复的真因）。真正的 faceting 必须给**每块独立随机倾角**（`pa[k] += (hash(...)-0.5)*0.60`），块与块之间才有角度差、才有折棱。
27. **xz 平面投影的噪声在陡坡会被 UV 拉伸成竖条纹**：法线贴图、程序化 bump、albedo 颗粒全部中招（陡坡上 xz 沿高度方向被极度压缩）→ 山脊出现一圈"毛刺"。解法 = 按**法线 y（up-ness）衰减所有 xz 投影扰动**：`float upK = smoothstep(0.06,0.52,normalize(vWNorm).y);` 乘进每个 bump/颗粒项。**物理上也更对：真实岩体的陡壁本来就是干净的新鲜断面，风化纹理只长在缓坡。**
28. **层理 / 等高线类特征只在缓坡成立**：把台阶函数套在陡壁上时，陡坡的等高线极密 → 每条等高线变成一条细台阶 → **满屏竖条纹（"针状晶簇"）**。写层理前先算局部坡度（`gx,hx` 邻居差），只在 `slope < 0.5` 处启用。
29. **雾色 / 环境色决定"远山像什么"，是单参数最高性价比的一刀**：暖褐雾（`0x14100a`）会把所有远景染成土黄丘陵，**违反大气透视**（真实远景被空气洗成冷灰蓝）。把雾色冷化（`0x0e1619`）+ 环境渐变冷化，远山立刻从"土丘"变"岩体"，成本一个字符串。
30. **清晰度指标与大块面岩石感天然对立，必须显式记录权衡**：Laplacian 方差度量**像素级细节密度**；"大块面"= 大面积平滑 = 方差低。第10轮清晰度 9583 → ~5400（−44%），而 v9 的 9583 高分实际来自**苔藓绒毛**（正是甲方点名的"土"）。**当用户视觉指令与量化指标冲突时，以指令为准，并把折损写进 LAB_STATE，不允许用硬追指标掩盖。**
31. **去金属：`metalness` 高 = 湿油泥**。岩石是**介电体**，`metalness` 应 ≤0.1；配 `roughness` 0.6-0.7（全漫反射 ≈1 就是土，岩石断口有解理面光泽）。第10轮把 0.60/0.44 改成 0.06/0.66，"油泥感"直接消失。
32. **单引号 JS 字符串里插内容：换行必须写字面 `\n`，且绝不能用 `python -c "...\\n..."` 传参**：bash 双引号会吃掉一层反斜杠 → 变成真换行 → 单引号字符串跨行 → `SyntaxError: Invalid or unexpected token` → **整页黑**。**注 shader 的补丁必须写成 `.py` 文件再执行**（本目录 `_patch*.py`）。反引号模板字符串才能接受真换行。
33. **GLSL 无变量提升**：把 `float upK2 = ...` 插在使用它的行之后 → `'upK2': undeclared identifier` → `program not valid` → 整页黑。**注入 shader 时，定义必须落在所有使用之前**（这是铁律"代码自审"的 shader 版：写完回读变量定义顺序）。
34. **页面崩了先定位，别瞎猜**：`pageerror` 给 JS 语法错，`console.error` 给 GLSL 报错行号；JS 侧可提取 `<script>` 跑 `node --check`。本目录 `_err10.cjs` 一次抓全。第10轮两次整页黑（真换行 + 变量顺序）都是 30 秒定位。
35. **分步补丁先建回退点**（`cp v10_base.html _v10_base_bak.html`）。第10轮最后一轮改动无收益且双测抖动 → 直接 cp 回退，不手改、不纠结。
36. **"加植物"≠"铺一层绿"**（2026-09-23 第11轮）：一次给到 1700 簇密铺 = 草地毯，反而退回"土/绒毛"的联觉。真实岩体上的植被是**点缀 + 群落 + 沿节理**三件事。给"点缀一点植物"这类需求，正确的量级是**局部成片、整体稀疏**，不是均匀覆盖。
37. **植物必须"长在土里"——用地面顶点 AO 做生长筛选**：草只长在**积土的凹陷**（`ao[i] ∈ [0.22, 0.72]`），凸出的岩面是裸的。这是植被真实感最容易被忽略、却最有效的一条：土只沉积在凹处，植物就只长在那里。判据 —— 如果草在亮岩面上也是均匀分布，就是假的。
38. **高宽比决定"是草还是钉子"**：一片窄叶纵向拉伸（7:1）在屏幕上是**黑钉子**，不是草。真实草丛 2-3:1 且**多片**（5-7 片交叉面片）。修形态优先改"片数 + 宽高比"，不要去调颜色。
39. **植物必须与岩体"异色相"才看得见**：黄褐岩体 + 枯黄草 = 隐形。改**灰绿**（hue 70-90）后立刻可读。同时这也更真实（活植物是绿的）。注意别为了"暖强调面积"把草做成枯黄 —— 那会同时失去可见性和真实感。
40. **簇内叶片长度/宽度必须参差**：统一长度 = 塑料草。逐片随机 0.70-1.30 才自然。随之把 shader 里的高度参数从 `position.y` 换成 **`uv.y`**（与叶片几何长度解耦，否则长短不一的叶片渐变就错位）。three 的 `MeshStandardMaterial` 顶点着色器里 `uv` 可用。
41. **植被分布要"沿节理/沟壑成脉络"**：均匀块状 + **整齐的高度分界**（一条水平线切分"有草区/裸岩区"）= 一眼假。用 `ridged` 噪声的脊线当节理掩码，节理附近阈值下调 → 植被成脉络；高处只允许沿节理上溯（`if hn > 0.40 && jointK < 0.34 continue`）。
42. **背光草不能是黑的**：真实草叶**透光**（次表面透射），背光面也是亮的。加 `totalEmissiveRadiance += gc*(0.055+0.115*vTY)`（很弱）就够；不加以后草会变成黑刺（首测的"黑色麦茬"就是这个）。
43. **草要"成丛"而不是均匀撒点**：写一个 `clusterFlora(spots, prob, rad)`，在母簇周围 0.06-0.17 半径生成 0-2 个伴生簇。真实草是群落繁殖，不是泊松分布。
44. **改过材质 shader 的版本，首测必须当暖机丢弃、取后续 3 测**：第11轮 `_patch11i` 后第1测 亮度 67.6 / 饱和 31.8 / 清晰 5673（`gmin=1`），后3测稳定 61.5-61.7 / 38.9-39.0 / 6087-6112（`gmin=0`）—— 差异来自**首次加载的 shader 冷编译**。这和第22条（动效相位抖动）是**两个独立的噪声源**：相位抖动是同文件重复测的差异，冷编译是**首测特有**的偏差。规则：新 shader 版本的第一次测量只当暖机。

## 无法看图时的兜底校验

截图/读图不可用是本机常态，改用数值验证：

- 高度场采样：`heightAt` 在整格上的 min / max / mean（合理区间约 -0.25 → 2.29）。
- 路径参数是否越界（断层线/扫描线 u 值是否被 clamp 到边界）。
- 每个 HTML 抽出 `<script type="module">` 存 `.mjs`，逐个 `node --check`。
- 还要说明「未做视觉校验」，别假装看过。

## 产出归置

统一放 `生成物/风格实验室/`。实际命名（以此为准）：
`v{N}A_{名字}.html` / `v{N}B_{名字}.html` / `v{N}C_{名字}.html`（三个变体）+ `v{N}_base.html`（融合后的新基准）。
配 `LAB_STATE.md`（当前基准 / 量化值 / 历史裁决 / 下一轮方向 / 工具清单 / 关键教训）——**每轮结束必须更新**，
它是跨会话（上下文丢失后）唯一的续接依据。

## 铁坑与工具（沿用项目 `_tools/` + 本目录脚本）

- 生成变体：写 `_gen{N}.py`，用 `str.replace` + `rep()` 断言锚点命中次数（绝不手敲）。
- 迭代补丁：写 `_patch{N}{a,b,c...}.py`，一个意图一个文件，便于回溯哪一步动了什么。
- 量化：`_drive.py`（起 http 服务 → playwright 无头截图 → 灰阶极值判黑屏重试 → 出指标）。
- 无头截图前**必须**把入场动画强制到终态，否则 8s 截图会撞上未完成窗口。
- 若指标异常，先怀疑元素被遮挡 / 结构属性被继承，再怀疑参数。
- **环境坑（2026-09-23 实测）**：会话 shell 的 PATH 可能被清空（`dirname` / `ls` / `head` 全 not found，shim 报 `cd: null directory`，命令 exit 127）。解法 —— 每条命令前显式补 PATH：
  `export PATH="/c/Users/lenovo/.workbuddy/binaries/PortableGit/versions/1.2.0/usr/bin:/usr/bin:/bin:$PATH"`
- **中断续跑**：自动化可能被系统休眠打断，留下「跑了一半的 LAB_STATE」。续跑时**先列目录看时间戳**（`ls -la --time-style=+%m-%d_%H:%M`），判断哪些是上一轮的半成品；**未验收的半成品基准一律判无效，从本轮胜者重建**，别把带致命缺陷的旧 base 当成绩。
```

#### nature-texture-engine

- 来源: 自建
- 路径: `C:\Users\lenovo\.workbuddy\skills\nature-texture-engine\SKILL.md`

```markdown
---
name: nature-texture-engine
description: 自然质感引擎 NatureTex——把「苔藓地面 / 针叶树 / 云海」三套真实感算法做成可迁移的 three.js 组件。当需要给任意网页加自然材质质感、要复刻某张参考图的微观质地、要给地形/植被/云加程序化贴图、或者要把已有的质感代码抽成可复用引擎时使用。触发词：自然质感、苔藓、针叶树、云海、质感引擎、程序化贴图、点精灵、NatureTex、把质感抽出来、复刻参考图的质地。
agent_created: true
---

# 自然质感引擎 NatureTex

**一句话**：传一个参数字典，拿到一个 `THREE.Group`，`scene.add()` 就有质感。

参考实现（单文件、可直接双击、含三展台演示 + 实时量化面板）：
`生成物/质感引擎/index.html`

---

## 何时用它

- 要给网页加**自然的表面质感**（草/苔/树皮/云/岩石），而不是纯色几何体
- 手上有一张**参考图**，要求「做到像这样」的微观质地
- 已有质感代码绑死在某个场景里，想抽成能复用的组件
- 需要判断「质感够不够」——这套引擎的演示页内置了量化指标面板

---

## 三层结构（迁移时按这三层切）

### 1 噪声工具箱（纯函数，零依赖，复制即用）
`clamp / lerp / smooth / mulberry32(seed) / hash2 / vnoise / fbm(x,y,oct) / ridged(x,y,oct)`

### 2 贴图工厂（参数 → 贴图，不碰场景）

```js
surfaceTex(size, { base, moss, nf, rough, seed, mossCol, litterCol, cover, litter, pore, nrm })
// → { albedo, rough, normal }   高度场五段叠加 → 反照率/粗糙度/法线
//   ⚠️ albedo 是「线性设计值」，务必 texture.colorSpace = THREE.NoColorSpace

clusterTex(size, { grid, hMin, hMax, wMin, wMax, hue, hueR, lum, lumR, topHi, botK, seed, stalk })
// → CanvasTexture    一张贴图里铺满「看得清的个体」（默认 3×3 抖动网格）
//   已内置 alpha bleeding + 关 mipmap（见「陷阱」）

cloudPuffTex(size, { seed, lightAng, seamK, litGain, backCool, core, cap })
// → CanvasTexture    云丘：内部鼓包 + 块缝压暗 + 受光梯度 + 背光偏青蓝
```

### 3 装配器（参数 → Group）

```js
NatureTex.ground({ count, size, szRange, clay, hueGreen, hueBrown, satGreen, lumGreen,
                   alphaCut, cover, pore, base, mossCol, litterCol, texSize })
// → Group（圆盘贴图 + 点精灵个体）

NatureTex.conifer({ height, radius, crownBot, needle, needleR, count,
                    litMin, litPow, greenK, trunkCol, seed })
// → Group（实体树干 + 枝骨架 + 点精灵冠）

NatureTex.cloudSea({ area, texSize, lightAng, seamK, litGain, cool, core, cap, count, puff, seed })
// → Group（三层云丘广告牌：海面 / 丘陵 / 拉丝）
//   area = 云海直径，内部整体缩放（不缩放会盖住整场！）
```

---

## 参考档（调通的数值，直接抄）

| 部件 | 关键参数 |
|---|---|
| 地面 | `base:[0.28,0.24,0.155]` · `mossCol:[0.19,0.37,0.125]` · `litterCol:[0.24,0.175,0.10]` · `cover:[0.27,0.54]` · `litter:[0.63,0.85]` · `pore:0.66` · `hueGreen:0.150` · 法线强度 `nrm:4.2` |
| 针叶 | `needle:0.055`（= 真实针叶 3~8cm）· `count:95000` · `litMin:0.055` · `litPow:0.78` · `greenK:2.4`（G/R 比，贴 1 会读成灰绿）· `crownBot:0.30` |
| 云海 | `seamK:0.50` · `litGain:1.32` · `core:0.17` · `cap:1.06` · `backCool:[0.22,0.10,0.28]` · `cool:0.84`（R/B，参考黄山云海实测 0.81） |

**两条最容易搞错的**
- **云要冷**：暖云读成「雾」，冷云才是「海」。但别过头，太蓝会变「梦幻紫云」。
- **针叶绿要纯**：三通道挨太近会读成灰绿，G 通道约为 R 的 2.4 倍才是针叶绿。

---

## 四个陷阱（每个都花了至少一轮）

1. **mipmap 平均 alpha** → 点精灵远景整片变黑消失。
   解：`minFilter = LinearFilter` + `generateMipmaps = false` + 圆头加大 + 阈值降档。
2. **alpha bleeding** → 透明区 RGB=0 让 mipmap 平均色变暗。解：把 alpha≈0 处 RGB 填成圆头平均色。
3. **为了「看得见」放大个体尺寸** → 近景质感立刻退化。尺寸永远服从物理尺度，可见性靠**密度 + 相机距离**解决。
4. **贴图 albedo 标成 SRGB** → three 二次解码，表面比它上面的实体暗 3 倍，怎么补光都没反应。
   确诊信号：光提 43%、亮度只涨 7%。解：`colorSpace = THREE.NoColorSpace`。

---

## 验证方法（这一步不能省）

```bash
# 起本地服务
python -m http.server 8792 --bind 127.0.0.1     # 在引擎目录下
# 四视角无头截图 + 抓运行时错误
node _probe/shot_engine.cjs "http://127.0.0.1:8792/index.html" "<输出前缀>" "all,ground,tree,cloud"
```

- 页面暴露 `window.__nt = { scene, renderer, camera, NatureTex, P, sampleMetrics }`
- `sampleMetrics()` 只取**内容区中心**采样 —— 整幅含 UI 面板会把指标稀释掉
- 改一处 → 复测同一视角 → **数字不动就是改错对象了**

---

## 已知差距（继续追的方向）

| 部件 | 还差 |
|---|---|
| 针叶树 | **差最多**：参考是逆光透射，本引擎是正面漫反射。缺 `col += tint * pow(max(0,dot(viewDir,sunDir)), k)` 透光项 |
| 地面 | 圆头偏黄偏散，参考更绿更成团 |
| 云海 | 参考更亮更白（它底下有黑山反衬） |

---

## 配套

- `webgl-terrain-hero` —— 同源，含森林/地形/云的场景级配方与验收三坑
- `mood-metric-design` —— detail / contrast / dark / warmth 等指标的定义与自审流程
- `生成物/质感引擎/马哲迁移.md` —— 八条哲学规律到代码规则的映射


---

## 🚨 三个结构性根因（2026-09-24 · 对标复刻实测，改了 11 轮才定位）

### 坑 1：ShaderMaterial 的 sRGB 管线 —— 「怎么调都暗」
three r152+ / WebGL2：贴图 `colorSpace = SRGBColorSpace` 时用 **SRGB8_ALPHA8 内部格式，
GPU 已硬件解码** —— shader 里 `texture2D()` 返回的就是线性值。所以：
- 再写 `pow(t.rgb, vec3(2.2))` 就是**二次解码 → 暗约 4 倍**；
- 而 ShaderMaterial **不会**自动做输出编码，`aces()` 之后必须手动 `pow(1.0/2.2)`。
**判断信号**：光提了 40%+，实测亮度只涨个位数 → 立刻去查管线，别再加光。
（实测：修完地面 L 0.216→0.351、云 0.358→0.429，一步到位。）

### 坑 2：「地毯感」= 几何是平的
密集点精灵 + 只在颜色上做宏观明暗，屏幕上是「颗粒地毯」。
参考的苔藓/草地是**一团立体的**（有真实受光面与阴影面）。
做法：`PlaneGeometry(TS, TS, 144, 144)` + fbm 位移 + 圆形 alphaMap 裁切
（⚠️ 换成 PlaneGeometry 后四角会露方形），点精灵 y 跟随同一高度场。
另外**「个体之间的缝」要真的暗** —— 缝露出的就是平面底色，把 base 压到近黑。

### 坑 3：「鳞片感」= 每个个体自带受光梯度
billboard 群若让每张贴图内部都有强受光梯度，几百个「自带明暗的小圆盘」
叠起来必然是一片片鳞甲。真实云海的明暗是**整片的大尺度梯度**。
→ 贴图内部梯度弱化（`litGain 1.42 → 0.52`）+ **逐实例受光**（按实例相对太阳的方位）。

## 方法边界（选方法前先问：参考里是「一个连续表面」还是「一堆离散个体」？）

| 参考的样子 | 适用方法 | 不适用 |
|---|---|---|
| 连续表面（苔藓地、草地、雪地、沙） | **平面贴图 + 点精灵（个体）** ✅ | — |
| 离散个体（一朵朵云、烟花、尘、鸟群） | billboard 群 ✅ | 做不了「连续云海」，个体边界天然可见 ⚠️ |
| 「林间」这种**多主体构成**的景 | 需要**多棵**一起放（单棵点精灵树做不出林间观感）⚠️ | 单棵不能代表「林」 |

## 参考图剖析：多测三项
只测亮度不够 —— 两个画面的 L 可能接近，但色相分布完全不同。
`ref_profile.py` 除 L/S/dark/contrast/detail/warmth 外，还要测：
- **色相中位数**（只统计 S>0.12 的像素）→ 主体色相
- **绿系占比 / 暖系占比** → 「太黄了」「太绿了」这类反馈的量化


---

# 🏁 照片直贴法（终局方案 · 2026-09-24）

**程序化复刻的天花板是「像」，照片直贴是「是」。** 当黄总丢来一张参考图说
「按这个做」时，先把这条路线摆出来：能直接用照片就不要去凑参数。

产物：`生成物/苔原直贴/`（index.src.html 模板 + build 脚本注入 base64 → 3MB 单文件）

## 结构：上半照片 + 下半照片贴图延伸的 3D 地面
| 层 | 做法 | 为什么 |
|---|---|---|
| 天空 + 远山 | 整张原图做成 quad **挂在 camera 上**（= 无限远、随视角转） | 这两样是「背景」，本来就不该建模 |
| 近景地面 | 照片下半部裁出 → **无缝 tileable 贴图**铺起伏平面 | 可走、可转，透视正确 |
| 衔接 | 3D 地面远端靠 FogExp2 淡入**照片远景地面的实拍色** | 与背景照片的远山接上 |

**地平线必须对齐**：先扫描原图各高度带的 L，找「陡降那一行」（本例 y=0.285，
L 从 0.611 掉到 0.409），再按相机 fov 换算 pitch。

## 资产加工（Python，一步到位）
1. 裁地面区（去掉天空与远山剪影）
2. Lanczos 超分 2× + `UnsharpMask(radius=2.2, percent=110)` —— 原图常只有 800px，不补就糊
3. **镜像 2×2 拼接** → 相邻边天然对称，平铺零接缝（比 Poisson/offset 省事且无痕）
4. 亮度 → Sobel → 法线贴图（先 GaussianBlur(0.8) 去 JPEG 块效应，否则块边被当成起伏）

## 五坑（每个都实测过）
1. **背景板必须 `fog:false`** —— `MeshBasicMaterial` 默认吃 fog，120m 处被 FogExp2
   吃掉 69%，天空 L 从 0.75 掉到 0.49，照片直接毁了。
2. **背景板要按 `object-fit:cover` 取 UV，不能拉伸**。铺满后要**反算地平线屏幕位置**：
   `hzScreen = (hzImg - offsetY) / repeatY`。写死 0.30 会错 6%（本例真值 0.239）。
3. **细节层的归一化常数 = 贴图的「线性均值」，不是「sRGB 均值转线性」**。
   sRGB→线性 是凸函数，Jensen 不等式：sRGB 均值 0.360 → 朴素换算 0.129，
   真实线性均值 **0.172**，差 34%。用错 → 调制系数系统性 >1 → 提亮 → 削顶 → 掉饱和。
4. **指标口径必须同分辨率**。`detail` 是相邻像素差，跨分辨率不可比：
   同一张照片 800px 下 0.0985，铺到 1440 视口只剩 **0.0369**。
   验收要拿「同分辨率的照片直出截图」当基准，不是拿原图。
5. **截图时必须隐藏 UI**。右上角深色参数面板压在天空区，把天空亮度实测值拉低 0.05。

## 曝光标定
three 的 Lambert BRDF 带 `1/π`，`AmbientLight` 强度 1 时输出只有贴图的 ~0.32。
**照片自带光照，不要再打直射光**（会把明暗叠两遍）。
只留：`AmbientLight(白, ≈1.75)` + 极弱 `HemisphereLight(天顶=照片天空色, 地面=照片地面色, 0.06)`。
hemi 的上下色必须**取自照片**，否则等于凭空加了一盏灯（实测会让 warm 从 +0.145 掉到 +0.097）。

## 近景细节层（抗插值模糊）
同贴图 3× 密采样做**亮度调制**（不是混色），除以线性均值保持整体亮度不变：
```glsl
vec4 d2 = texture2D( map, vMapUv * 3.0 );
float m2 = clamp( dot(d2.rgb, vec3(0.3333)) / uMean, 0.55, 1.80 );
sampledDiffuseColor.rgb *= mix( 1.0, m2, uDet );
```
⚠️ 贴图尺度别调太小：UV 越密 mipmap 越退到粗层，近景反而更糊
（实测 tile 3.5m→7.0m，近景 detail 0.045→0.055、S 0.319→0.335）。

## 已知上限
原图 800px 是硬限制：近景放大后必然比照片钝（S 0.334 vs 照片 0.404）。
远景/中景能对到 ±0.03 内，近景差 0.07 —— 这是分辨率，不是参数问题。
headless 截图（swiftshader）不支持各向异性过滤，近景表现被低估，真机更好。
- **bright（L>0.70 占比）** → 有没有「亮部」（云、透光的叶）


## 🚨 黄总两条硬规则（2026-09-24 两次点名批评后立）
1. **森林 = 密到填满画面。任何「几棵零星的树」都是不合格。**
   三条可执行指标：① 横向铺过画面边界（列距 ≈ 1.2 单位、覆盖 ±13 以上，不能留空场）
   ② 前后 5 排以上，行距 **小于冠幅**（否则看见的是「一排排」不是「一片」）
   ③ 抖动幅度要小（±0.6 以内），大了就退化成稀疏散点。
   配额要跟上：棵数 ×单棵点数，120 棵时必须 ≥900k 才不秃。
   验收指标：`detail` 翻倍（0.035→0.066）、`S` 从 0.45 提到 0.67 —— 密度不足时这两个都起不来。
2. **远景山体必须有细节，禁止卡通剪影。**
   禁止用 `ShapeGeometry` 折线做山脉（那必是「一笔带过」）。
   正确做法 = 烘进 canvas 贴图：三尺度 fbm 山脊线（主峰+次峰+碎齿）+ 垂直岩纹沟壑
   + 按高度衰减的树点（含树线，树线以上渐变为裸岩）+ 顶部淡入雾色。
   CanvasTexture 必须 `colorSpace = SRGBColorSpace`，否则整体发暗。
   验收：山体带的 `detail` 从 0.0088 → 0.0806（9 倍）才算「有细节」。


## 🚨 地平线公式符号（2026-09-24 翻车实录 · 最高优先）

「照片直贴法」里把 3D 地平线对齐到照片地面线，推导必须记住，**符号错了画面全毁**：

    屏幕位置 p（0=顶,1=底）→ NDC y = 1-2p → 视线仰角 α = atan((1-2p)*tan(fov/2))
    水平地平线在相机空间的仰角 = -θ（θ = camera.rotation.x，抬头为正）
    → -θ = α_hz  →  θ = +atan((2*hz - 1) * tan(fov/2))      ← 正号！

写成 `basePitch = -atan(...)` 会让相机反向俯仰，地平线翻到屏幕另一头：
地面占比从 8% 变成 96%（整屏草地）。实测症状：**上半屏比原图暗 0.15~0.31，
detail 从 0.003 暴涨到 0.035**（草地高频盖住天空）。
苔原页（HZ 0.285）一直带着这个 bug，因反成 0.715 后地面占 28% 碰巧没崩，所以没暴露。

排查手法：截图 `?m=scene&beam=0` 后 `window.__gm.visible=false` 只留背景板，
再逐行比 ΔL，就能定位地面实际占了哪几行。**别靠肉眼，靠逐行 ΔL。**

## 「照搬」= 直贴，不是程序化模仿（2026-09-24 黄总重罚后的定论）

他说的「照搬」= 把参考图每一寸原图搬进网页，**不是**用噪声/几何去模仿。
判据：复刻页与原图做 4×3 分区对比，`avg|ΔL| < 0.03` 才算照搬；
程序化模仿（造树造山）实测 avg|ΔL| 0.09+，永远是「差距非常大」。

可执行流程（已验证，晨光森林页 avg|ΔL|=0.021 / avg|Δwarm|=0.010）：
1. 全图挂相机当背景板（fog:false + cover UV），地面只补屏幕底部 8~16%。
2. 地面贴图从原图**按实测数据选区**裁：先跑逐行/分区剖面（L / warm / detail），
   挑最亮最暖最细、且避开暗斑（水塘/阴影）的块；再镜像 2×2 无缝化。
3. **宽条 tile 别裁正方**：底部可用高度常只有 100~200px，裁正方再放大 6 倍会
   把 detail 从 0.033 抹到 0.009。正确做法：保留原宽高比（如 2048×371），
   在 shader 外用 `repeat.y = repeat.x * TILE_AR` 补回来，detail 能保住 0.032。
4. 所有颜色常量（雾 / 天顶 / 地面反射 / 太阳位）从原图采样，不写死。
5. 任何叠加层（光束等）都会拉高 ΔL：beam 0→0.75 时 avg|ΔL| 0.009→0.039。
   要「0 = 严格照搬」的默认档，动感只作可选调味。


## 「流动光晕」阳光层（2026-09-24 黄总点名要的那一版 · 可复用 shader）

死板放射条纹 ≠ 好看。**流动感来自「域扭曲」**：用 fbm 位移场去推动光束的相位，
光束就像被气流推着飘，而不是原地闪。三层叠加：

    q    = vec2(fbm(uv*3 + t*0.05), fbm(uv*3 + (5.2-t*0.04, 1.3+t*0.06)))   // 位移场本身也在漂
    flow = fbm(uv*2.2 + q*1.6 + (t*0.03, -t*0.02))
    rays = Σ pow(max(0,sin(ang*f_i + i*2.1 + flow*3.2 + t*0.06)), 7)/(1+0.8i)   // 相位被 flow 推
    core = exp(-r²*20) * (0.85 + 0.15*sin(t*0.6))        // 太阳核呼吸
    haze = smoothstep(0.35,0.95,flow) * exp(-r*1.1)*0.35 // 漂移雾斑，给光体积感
    col  = warm * (rays*fall*0.42 + core*0.40 + haze*0.30)，additive，fog:false

标定（对照原图 4×3 分区）：beam 0 → avg|ΔL| 0.012；**0.32 → 0.027（推荐）**；0.8 → 0.044 过曝。
→ 必须给「0 = 严格照搬」的默认档，动感只作调味，且滑块要写明每档的指标代价。

验证光晕真的在动的办法：同一页隔 4 秒截两帧，平均像素差 > 0.002 即在流动（实测 0.0069）。

## 网页化交付（单文件页的最小版式）

黑幕淡出 → 标题浮起 → 页脚。要素：左上 kicker（英文小字 letter-spacing .34em）
+ 主标题 + 副标，左下页脚带实测指标背书，右上 pill 切换。**截图/量化时必须把
overlay 全隐藏**（title/foot/veil 也算），否则深色半透明压在画面上会污染指标。


## 🚨 点精灵二次解码 = 「中央死黑一坨」（2026-09-24 P43 实录 · splat 页）

**症状**：全景中景有一坨边界毛茸的黑块（黑块核 28% 像素 L<0.06），近看同层却是
亮绿绒毯。**不是影子、不是受光**——光照探针（hemi×2.3 / sun×1.7 / normalScale=0 /
关影子）全部只挪 ±0.02。

**真凶**：`THREE.Points` 的 ShaderMaterial 里 `aces(vTint * pow(t.rgb, 2.2) * 2.05)`。
贴图已标 `SRGBColorSpace`（WebGL2 硬件解码，texture2D 返回**已是线性**），
再 pow 2.2 = 二次解码，暗部被压到 1/9。中景处 gl_PointSize 缩到 3~8px，
一个点只采到渐变底缘的暗像素，150k 个暗点连成死黑坨。
（与 P7f 地面 `NoColorSpace` 是同一族 bug：**先确认贴图解码发生在哪一层，再决定要不要手动 pow**。）

**修法**：去掉手动 pow，乘数按亮部端到端持平补偿（2.05→1.32~1.47）：
亮部不变、暗部提亮 ~9 倍。

**归因手法（值得复用）**：光照探针排除法 → 页面加 `?hide=序号` 调试钩子
（按 `scene.children` 序号隐藏）逐对象截图 → 黑块核区 L<0.06 占比对比，
谁把它从 28% 打到 0% 谁就是真凶。**别肉眼猜，逐层隐藏。**

## P43 其他小修（splat 页地面/树）
- 碎石 520 颗实例色线性 0.30 × 材质色 0.29 ≈ 0.087 → 中景黑碎石滩；
  提亮(0.52)+缩小(0.10~0.44)+减量(300)。「点缀不能成面」。
- 草实例色 L 0.40~0.64 → 0.30~0.47：亮黄绿草簇在暗地上=荧光噪点。
- 树冠枝端加密从「端点球」改「沿末段 28% 路径的叶簇」：端点球=棉花团的元凶；
  但叶散布别收太紧（0.76~1.18 时近景相机被树冠包住，画面 L 掉一半），0.84~1.36 合适。


## 🎬 「电影感画质」可测配方 + cine grade 管线（2026-09-24 P45 · tree_lab）

黄总把 54 张候选**全部**认定为电影感 → 全体统计中位数就是他的审美配方（实测）：

    p5 0.096 · p25 0.202 · p50 0.395 · p75 0.583 · p95 0.828（span 0.724）
    S 0.403 · split(亮暖-暗冷) +0.136 · darkfrac(<0.10) 5.7% · hip(>0.85) 4.0% · haze 0.030

对照反例（我此前的叶）：p5 0.356（无暗部）、hip 47.6%（近半过曝）、S 0.247、split 反向。
**「不电影」的本质 = 直方图挤窄带 + 无抬黑 + 无分离色调**，不是缺滤镜。

### 管线（tree_lab.html 验证收敛，输出命中全部锚点 ±0.04）
1. 物理层出层次：暗虚化环境（程序化 equirect 渐变+blob+缩小放大模糊）+
   单一侧逆光 + 冷天光弱补光。叶 ShaderMaterial 烘焙三段色（暗 0.055/中/亮 0.52 + 金边），
   逐叶 jitter ±15% 让直方图连续。
2. **cine grade 后处理**（RT HalfFloat + 全屏 quad，全部在 display 域做）：
   五点锚单调重映射（实测输入分位 → 54 张中位）→ 分离色调（暗 teal 0.90/0.98/1.13、
   亮 amber 1.06/1.01/0.92）→ 抬黑 +0.010~0.020 → 饱和(线性域) → 暗角 → 颗粒。
   bloom 在线性域做（12 tap 减阈值）。
3. **校准闭环**：`?grade=0`（RT 直通 l2s）截图 → 测物理层分位 → 回填 uInA →
   输出分布即命中目标。别用 `?cine=0` 测（见坑①）。

### 三个坑（都踩过）
① **直接渲染 vs RT 路径输出编码不对称**：ShaderMaterial 手写 fragment 没有
   `#include <colorspace_fragment>`，直渲到 canvas 时不编码（偏暗），RT 路径经 grade
   的 l2s 才正确提亮。**测物理层分布必须走 `?grade=0` 直通，不能用 `?cine=0`**。
② grade 材质新增 uniform 忘写 GLSL 声明 → 整个 post shader 编译失败 → **全黑画面
   且无异常**（和 uScale 前科同族：ShaderMaterial 改动后必须看 console）。
   修完 GLSL 里也要声明 `uniform float uPass;`。
③ **Points/烘焙材质不吃场景光**：调 key 光强度对叶毫无作用（树干才吃光）。
   叶亮部要改烘焙色常量（LEAF_LIT/LEAF_RIM），别去拧灯。

### P47 追加：指标唯一定义 + 两个真 bug（2026-09-24 · 用 54 张拟合 cine_target.json 反推，误差<0.002）
`L = 0.2126R+0.7152G+0.0722B`（**sRGB 显示域**，不是线性）；`S = mean((max-min)/max)`；
`warm = R - B`；`wd/wb` 取 **p10/p90 分组**；`split = wb - wd`
（**必须逐图先减再取中位数**，中位数不可交换，先取中位再相减会差 0.012）；`haze = p0.5`。
→ 已固化成 `生成物/_probe/cine_metrics.py`，以后只许用它，别再重写变体。

④ **分离色调写错过**：`d *= mix(cool, warm, t*uSplit)` 在 uSplit<1 时亮部 82% 仍是冷色，
   等于没生效。正确写法：`d *= mix(vec3(1.0), mix(cool, warm, t), uSplit)` —— uSplit 只当强度。
⑤ **输出锚要补偿暗角/饱和的压低**：按目标锚设好 o 之后实测仍整体偏低 ~0.04（暗角 0.46 + 饱和 0.78），
   把 o 锚按实测 Δ 抬（o5 .110/o25 .221/o50 .438/o75 .641/o95 .920）才命中。
⑥ **split 偏暖是物理层的暖，不是 grade 的锅**：先降叶烘焙色的 R-B（LEAF_RIM 0.76/0.70/0.33 →
   0.58/0.60/0.43，MID/LIT 同降）、金边强度 0.58→0.36、环境顶色与灯色降暖，
   split 才从 +0.297 落到 +0.156。调色救不了物理层。
⑦ **GLSL 里不能写 JS 的 qn()** → 'squash' undeclared、shader 静默不编译。参数一律走 uniform。

---

## 🌳 「树的形状」照搬法（2026-09-24 P47 · 黄总「这不像树的形状」）

**核心：形状要用剪影 IoU 量，不能靠肉眼说"像不像"。**

### 管线
1. 参考图 → mask（白底照 `L<0.80`；我自己的渲染加 `?sil=1` 白体黑底模式）→ 去边框 → bbox 裁。
2. **看不了图就打 ASCII 剪影**（40×52 字符、按块密度 `#+./ `）——轮廓当文本读，够用。
3. 量化（`_probe/tree_shape.py`，纯 numpy）：24 行宽剖面 / 最宽位置 / 冠底 / **凸包内背景占比=凹缺** /
   叶团峰数 / 细结构（腐蚀 5×5 存活率）/ 行填充率 / 中心摆幅；`_probe/sil_iou.py` 算 IoU。
4. 照搬：实测剖面直接写进 PROFILE，再调 CROWN_BOT / 密度权重 / 方位角起伏，IoU 收敛即可。

### 「不像树」的三个真因（本项目实测）
| 症状 | 参考 | 我原来的 | 修法 |
|---|---|---|---|
| **没有腿** | 干占全树 17% | 只露 8%（冠拖到地面）| CROWN_BOT 0.17→0.30，干加长到 0.38H |
| **头是尖的** | h=0.94 还有 0.63 宽（宽圆顶）| 只剩 0.14（棒棒糖）| 剖面按实测换，顶部按穹顶收口 |
| **叶量在顶** | 最宽在下部 h≈0.42 | 密度权重推到冠顶 | `0.58 + 0.42*(1-h归一化)` 下部更密 |

### 三个坑
① **旋转体是"假树"最大来源**：单 profile 绕 Y 轴 → 一圈一样宽、凹缺只有 0.139（参考 0.184）。
   加 `crownRadius(h,θ) = profile × (1 + 0.14sin3θ + 0.07sin5θ + 0.08sin8θ)`。
② **底层叶幕（大软圆幕）会撑出裙摆 + 抹平轮廓**：竖向压扁
   `length(vec2(pc.x, pc.y * 2.0))` + 半径收小。且 **gl_PointSize 是直径不是半径**（世界半幅 = aSize/2）。
③ **冠底簇必须禁止下垂**：lowK=(h-CROWN_BOT)/0.14，用它压 droop、收子枝，否则叶子把冠底拖成锥形。

实战结果：剪影 IoU **0.777 → 0.852**（`生成物/树形校准/ref_tree.jpg` 为靶，
源 `生成物/site/tree_lab.html`，对照板 `生成物/site/_p47/对比_树形_P47.jpg`）。

### P48 追加：三个「一眼假」补丁（黄总：「上面有树枝突然冒出来了」「少部分树叶还是小圆片」）
① **枝戳出树冠**：真凶不是主枝，是**二级枝的随机偏移**（0.3H）+ CatmullRom 弯曲超控，
   中上部冠收窄处必然戳穿叶层。修法 `clippedTube()`：沿曲线采样 16 段，
   超出 `crownRadius(h,θ) × 0.62` 就截断；二级枝偏移降到 0.14H；干区（h<CROWN_BOT）放行。
   → 通用规则：**任何骨架几何都要沿自身采样做「包络裁剪」，不能只管端点**。
② **残留小圆片 = 底层填充幕**：为了填缝加的「大而软的正圆幕」一旦露在冠缘，
   就是一圈黑椭圆。修法：填充幕**必须和主叶同形状公式**（梭形 + 随机 aRot）
   + 提亮（暗幕 0.40→0.54）+ 收散布（0.55→0.42 cR）。
   → 通用规则：**填充层不可有自己的形状语言**，它是「模糊的主元素」，不是「另一种元素」。
③ **小尺寸精灵糊成圆点**：`aa = clamp(2.0/vPt, 0.02, 0.30)` 在小点上软边占比过大，
   5px 的梭形被抹成圆。改 `clamp(1.5/vPt, 0.015, 0.22)` + 最小尺寸 0.010H→0.012H。
   → 通用规则：**软边宽度要按像素算（1.5/vPt），上限不能让软边吃掉形体本身**。
④ **const 的 TDZ**：`CROWN_BOT` 原定义在枝代码之后，枝里一引用就 ReferenceError。
   包络判定用到的常量必须定义在骨架代码之前。

---

## 🔁 单要素照搬 SOP（这套流程对树/云/水/石通用，P44–P48 实测有效）

**0. 单要素试验页**：`xxx_lab.html`，零依赖单文件，只放这一个要素 + 暗虚化环境，
   不做构图不做相机。**在试验页里改，不要在成品页里改。**
1. **找回参考原图**（找不到就翻会话附件 `~/.workbuddy/blobs/`，按时间+背景亮度捞）。
2. **页面加 `?sil=1` 剪影模式**（白体黑底、关雾/关调色/关环境），
   让"我的渲染"和"参考照片"能用**同一套量化脚本**处理——这是能比较的前提。
3. **看不了图就打 ASCII 剪影**（40×52 字符，按块密度 `#+./ `）——轮廓当文本读。
4. **量化**：`_probe/tree_shape.py`（宽剖面/最宽位置/冠底/凸包凹缺/叶团峰/细结构/行填充）
   + `_probe/sil_iou.py`（归一到 128 高、居中对齐的**剪影 IoU**）。
   **形状只用 IoU 说话，不用肉眼说"像不像"。**
5. **照搬**：实测剖面直接写进参数表，不自己发明曲线。IoU 收敛即停（本项目 0.777→0.852）。
6. **调色**：`?grade=0` 测物理层锚 → 回填 `uInA/uInM` → 扫 `uSplit` → 输出锚补偿暗角。
   指标唯一定义在 `_probe/cine_metrics.py`（54 张样本拟合），不许另写变体。
7. **回头验**：改完形状后物理层会变 → **重跑第 6 步**（P47/P48 都验证过：不重跑必偏）。
8. **搬回成品页**：整段叶子 + grade 管线一起搬，构图/相机/雾不动。

**三个反复被验证的元规则**
- 「不像 X」的反馈 → 先量 X 的**剪影几何**（腿、头、宽高比），不要先调材质。
- 「太 AI / 一眼假」的反馈 → 找**旋转对称**和**同类同形**（每棵树一样 = 圣诞树阵）。
- 「残留某种怪东西」→ 先怀疑**为了填缝/打底加的辅助层**，它最容易露馅。

---

## ☁️ 云海照搬（2026-09-25 P49 · billboard 云的四个真凶）

p25 晨光絮状云海实战。「霉斑 → 云块」的四个根因，全部在 billboard 路线自身：

1. **贴图 alpha 被中频 fbm 阈值抠碎** = 霉斑第一真凶。每块广告牌内部先碎成噪点，画出来必然是斑。
   改「软圆盘 + 低频撕边」；絮感交给块间缝与受光差，**不交给贴图内碎化**。
2. **透明 puff 叠层平均掉方差**：小 puff × 高数量 × 低 alpha，每像素收敛到「平均云色」→ 灰泥。
   puff 放大 3×、数量减半、alpha 抬到 0.7+。大尺度明暗只有 **instance 级宏观光照**
   （向阳 bank 整块亮 / 背光整块暗）撑得住，per-puff 光照叠几层就被平均。
3. **别用大平面堵漏底**：大平面会被相机 far 裁出硬横条纹 + 把画面洗成沙色。云量够就不漏底。
4. **颜色乘法配方凑不出「亮金+暗青」**：直接测参考图暗/中/亮三组（按 L 分 p10/p90 组）真实 RGB，
   分段插值写进贴图。**S 是色盲指标**（sat 拉满 S 上去但色相跑粉紫：R+B 高 G 低=品红），
   暗青必须保住 G 通道；亮金 R>G>B (0.898/0.667/0.396)、暗青 G>B>R (0.085/0.12/0.147)。
   注意 split 真值 = wb−wd（p25 是 +0.565），别把 mean warm 误当 split 目标。

大气透视（远处 melt 进光雾）是「云海感」的招牌：FS 雾混合 0.32→0.55 + 雾色提亮金。
锚点闭环同树：物理层一动（litbase/macro/贴图）→ ?grade=0 重测 → 回填 i 锚。

---

## ⛰️ 山体照搬（2026-09-25 P52 · 层叠山脊 + 反向大气透视）

p25 山体（云/山分离后的「山」半边）实战。mountain_lab.html = cloud_lab 骨架 + 山模块。

### 山的靶要单独量三样（_probe/mountain_seg_sample.py）
1. **分层色彩**：近山绿（warm+0.02 G/R 1.2-1.4）vs 远山蓝灰（warm -0.11~-0.15）——
   掩码里 `veg`（G>R+0.02）与 `blue`（B>R+0.03）各自统计。
2. **纵深梯度**：按画面纵向分带测 L/warm。山的招牌：**越远越亮、越蓝、越淡**——
   与云正好相反（云越远越暖金）。上带/下带 L 差实测 2.5 倍。
3. **山脊轮廓形态**：每列山体最高点连成山顶线 → 去趋势 std、主导波长
   （FFT）、尖锐度。p25 ≈ 2 个山头横跨画面、平缓圆丘。波长按层距缩放：
   `wl = dist × 0.505`（dist = 相机到该层距离）。

### 实现要点
- **层叠山脊条带 mesh**：1D ridged 噪声（`1-|2n-1|` 反转，脊在 1）拉伸成条带，
  4 层远→近。每层：`mix(近山绿, 远山蓝灰, farK) × lift(1+0.8·farK)` + 棱线光影
  （坡面法线·太阳，远层 smoothstep 抹平到 1）+ 山脚 mist 洗。
- **云贴山腰**：云 puff 的 y 用 `ridgeHeightAt(x,z) - 7` clamp——先算好各层
  山脊查表，云的高度场取各层脊高按纵深衰减的 max。山头从云里立出来。
- **云三段式**：近景厚絮团（压低压扁）/ 远景薄海带（低 alpha 盖谷底）。
  均匀铺满全盘 = 山被埋死。

### 五个坑
① **GLSL 里没有 smooth()**——写了就整材质编译失败、山整个不渲染（静默黑）。
   GLSL 只有 smoothstep。JS 工具函数搬进 shader 前先查内建名。
② **斑驳 attribute 只随 x 变化 = 每列一色竖条纹**（一眼假）。斑驳必须沿坡面
   二维分布：FS 内 `vn2(vec2(vWx·k, vH·k'))` 大簇+小碎两层。
③ **山条带底太深（-40）→ 脚洗区全在云线下看不见**。底部取云海面附近（-8），
   让 vH=0 落在「山出云」的位置，footM 洗才起效。
④ **远层山戳出天空球**：层距×halfW 要小于天空球半径（420→700）。
⑤ **近景"幕布墙"**：相机 y 要与近层山顶平齐（山半淹云），山太高于视平线
   就是挂下来的墙。

### 靶口径（P50 教训的反面验证）
试验页画面是山+云同框 → **o 锚必须用参考图全图分位**（与画面构成同口径），
不能用纯山掩码靶——那会把云也压黑。山带本身的验收才用山掩码靶。
i 锚照常 ?grade=0 闭环。结果：A 版山带 p5/p50/p75/p95 全贴参考山体靶。
```

### 文档与办公

#### tencent-docs-routing

- 来源: 内置/市场
- 说明: Load this Skill before handling local Office/WPS files such as doc/docx/dot/wps/wpt, xls/xlsx/xlt/csv/tsv, or ppt/pptx/pps/pot, and before creating a new local document, spreadsheet, or presentation. Load first whenever the user uploads, mentions, previews, edits, or asks to create such a local file, to decide whether to use the local office editing Skill, the local spreadsheet agent, the spreadsheet generation Skill, or the PPT generation Skill. Text-based outputs such as speech scripts, talking points, copywriting, summaries, reports, or meeting minutes should default to local DOCX unless the user explicitly specifies another local format such as markdown or plain text. Other file types are out of scope.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-tencent-docs-routing\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Local Office/WPS Routing

> **This is the gate you MUST read before handling local Office/WPS files — doc/docx/dot/wps/wpt, xls/xlsx/xlt/csv/tsv, or ppt/pptx/pps/pot — AND before generating/creating any new local document, spreadsheet, or presentation.** This Skill only describes local file operations. It routes **content** work only — reading a document's content into context, editing, creating, transforming, and the like. Simply opening, previewing, or presenting a document for the user to *view* is the host's preview/present surface, not content work — call the host preview/present tool directly instead of routing it through this Skill.

## Host document context

The host injects a `<tencent_docs_editor_context>` block that surfaces local documents (e.g. `<active_document type="local" .../>`, `<local_files>`). Route each surfaced document by the file-type rules below.

If the context block already injected a `file_id` for a document, follow the **Injected `file_id`** rule in [file_id resolution](#file_id-resolution-local-documents).

## Supported Local Formats

Use these extensions to decide whether this routing Skill applies:

| Type | Supported local file extensions |
|---|---|
| doc | `.doc` `.dot` `.wps` `.wpt` `.docx` `.dotx` `.docm` `.dotm` |
| sheet | `.xls` `.xlt` `.xlsx` `.xltx` `.xlsm` `.xltm` `.csv` `.tsv` |
| slide | `.ppt` `.pps` `.pot` `.pptx` `.ppsx` `.potx` `.pptm` `.ppsm` `.potm` |

Macro-enabled files (`.docm` `.dotm` `.xlsm` `.xltm` `.pptm` `.ppsm` `.potm`) can be opened as their corresponding doc/sheet/slide type, but macros are not executed. WPS-specific `.et` `.ett` `.dps` `.dpt` are not supported; ask the user to save them as `.xlsx` or `.pptx` first.

## New Local File Creation

When the user asks to **generate / create / produce** a new document, spreadsheet, or presentation, produce a local Office/WPS-type file and route by file type.

### Format classification (prerequisite step)

When the output the user requests is essentially structured textual content — such as speech scripts, talking points, copywriting, summaries, reports, or meeting minutes — always classify it as a doc first, then apply the local DOCX creation path.
Do not default to Markdown or plain text.
Only when the user explicitly specifies another local non-DOCX format (e.g. "generate markdown" or "plain text is fine") is this rule overridden.
This rule does not affect outputs that clearly belong to sheet (e.g. "make a spreadsheet") or ppt (e.g. "make a PPT").

## Existing Local Documents

> Note: This section applies to **existing local** documents that need to be read or edited. For **new** document creation, see "New Local File Creation" above.

Every task resolves by file type and task nature:

1. **Local doc/slide single-file edits** → load the **`tencent-local-office-edit`** Skill and operate through it.
2. **Local PPT creation from source materials** → use the **`tencent-pptx`** Skill.
3. **Local DOCX/Word creation from scratch, or an abstract whole-document beautification of an existing DOCX/Word file** → use the **`tencent-docx`** plugin (from-scratch creation → `full_pipeline`; whole-document abstract beautification → `beauty_only`). See the DOCX/Word sections below for the exact triggers and out-of-scope cases.
4. **Creating a new workbook** — the user's intent is to produce a brand-new `.xlsx` file at a **new file path** (independent from any source file), regardless of whether reference materials (including source spreadsheet files used strictly as read-only references) are attached → use the **`tencent-docs-sheet-generation`** Skill. See "Creating a new workbook" below.
5. **Any task that touches an existing workbook** — editing existing cells, **adding / removing / renaming sheets inside it**, analyzing, aggregating, cleaning, reformatting, or otherwise modifying the source workbook in place (the source `.xlsx` file itself is the deliverable) → follow the sheet routing rules below (never `tencent-docs-sheet-generation`).

## Creating a new PPT from source materials

When the user's intent is to create a new PPT based on source materials (e.g. DOCX, XLSX, PPT, PDF, etc.), strictly use the `tencent-pptx` Skill. This Skill has efficient built-in material parsing and processing capabilities; avoid parsing those materials by any other means.

## Creating a new workbook

Whenever the user asks to **produce a new workbook** — signaled by authoring verbs such as 生成 / 制作 / 新建 / 做一份…表 / 整理成 Excel / 汇总成一份新表 applied to a spreadsheet — strictly use the `tencent-docs-sheet-generation` Skill. The decisive condition is the **user's intent to produce a brand-new `.xlsx` file at a new file path**, not whether reference materials are attached: the content requirement may be pure text, or it may reference local materials — supported local reference types are PDF, DOCX, PPTX, and source spreadsheet files (`.xlsx` / `.xls` / `.csv` / `.tsv`) used strictly as read-only content references. When a source spreadsheet is supplied, apply the **intent test** below to distinguish "produce a NEW `.xlsx` file from these numbers" (route here) from "modify this workbook in place — including adding a new sheet inside it" (route to the sheet routes below). In every case hand the raw requirement and any referenced materials to the Skill and let it parse them; do **not** pre-parse those supported materials by any other means.

### Intent test (only when a source spreadsheet is supplied)

Route to `tencent-docs-sheet-generation` **only if all** of the following hold:
- **New-file wording**: the user asks for a **new `.xlsx` file** (a separate workbook on disk) — e.g. "根据这个 xlsx **再生成一份新表**", "帮我基于这份 csv **整理成一份**销售统计表", "把这份数据做成一张**新的**汇总表". Look for verbs like 生成 / 新建 / 做一份 / 整理成 / 输出 / 另存 combined with a "new / another / separate" qualifier applied to **the file**, not to a sheet inside an existing workbook.
- **Read-only source**: the source workbook is used purely as a content reference; its own cells and sheet structure are not modified.
- **Deliverable is an independent file**: the primary deliverable is a fresh `.xlsx` at a **new file path different from the source**, not an in-place modification of the source workbook. **Adding a new sheet inside the existing workbook is an in-place edit, not generation** — it stays with the sheet routes below. Analysis output counts as generation **only when** the user explicitly asks for it as a separate NEW file (e.g. "汇总成一份新表"); the same analysis expressed as edits, annotations, or an added sheet inside the source is an edit, not generation.

If the intent test fails (any modify-in-place / add-sheet-to-source / analyze-source / clean-source wording), do **not** route here — fall through to the sheet routing rules below.

Out of scope (do **not** send here):
- The user's intent is to modify the source workbook in place — e.g. "改这份 xlsx", "在这个表里加一列", "在这个工作簿里加一个汇总 sheet", "透视一下这份数据", "帮我清洗这个 csv". These stay on the sheet routes below (`tencent-docs-sheetagent` for data-dependent work, the `tencent-local-office-edit` Skill for deterministic edits).
- The requested output is not a spreadsheet (doc / ppt / text) — follow its own creation route above.
- The only reference material is a type this Skill cannot parse — e.g. an **image**, an archive, or any format other than PDF/DOCX/PPTX/XLSX/XLS/CSV/TSV. Do **not** hand such material to the Skill. Instead read its content into a plain-text requirement yourself first (e.g. read the numbers out of an image), then route that resulting pure-text request here as a normal workbook creation. If no usable content can be extracted, tell the user which inputs are supported (plain text, or PDF/DOCX/PPTX/XLSX/XLS/CSV/TSV references) rather than routing here.

## Local DOCX/Word creation from scratch

Whenever the user asks to **produce a new DOCX/Word file from zero** — signaled by authoring verbs such as 生成 / 写 / 起草 / 撰写 / 新建 / 重写 (重写 is treated as from-scratch creation here) applied to a document — strictly use the `tencent-docx` plugin. This is not restricted to specialized verticals: it covers ordinary everyday documents as well as recognizable professional genres such as research report (研报), annual report (年报), academic paper (论文), official/government document (公文), contract (合同), business report (商务报告), meeting minutes (会议纪要). In every case the plugin produces a complete document with an auto-generated cover page and professional, context-appropriate layout/typography; avoid assembling such documents by any other means.

This route is for **from-scratch creation only**: the plugin does **not** ingest source materials (DOCX, XLSX, PPT, PDF, etc.). If the user supplies source materials to be turned into a document, do not route here — fall back to the standard DOCX/Word creation path via the `tencent-local-office-edit` Skill. Editing an existing DOCX/Word file likewise stays with `tencent-local-office-edit`.

Concretely, the Orchestrator inside `tencent-docx` MUST decide `full_pipeline` directly at Stage 0 — no deliberation, no extra intent probing, no detour through lighter stages.

## Whole-document beautification of an existing DOCX (abstract styling)

When the user has already provided a single content document A AND asks for an **abstract, whole-document** beautification — expressions like "美化一下" / "更专业" / "更好看" / "排版优化" that require the AI to make design decisions without naming specific style values — AND **no** separate independent style-reference document B is attached, AND the request does **not** scope the beautification to a specific part of the document (e.g. "美化这个表格" / "美化这一段" / "调整第 X 节的样式"), use the `tencent-docx` plugin.

In this case the Orchestrator inside `tencent-docx` MUST decide `beauty_only` directly at Stage 0 — no deliberation, no extra intent probing, no detour through other stages.

Out of scope for this route (do **not** send here):
- The user provided a style-reference document B alongside A (that is a different routing decision, not this one).
- The user scoped the beautification to a specific fragment — a named table, a paragraph, a section, a page, etc. Localized style edits stay with the `tencent-local-office-edit` Skill.
- The user specified concrete style values (fonts, sizes, colors, spacing, etc.) — that is a direct edit, not an abstract beautification.

## Sheet Files (spreadsheets)

**Prerequisite**: this section only handles tasks where the source workbook **is modified in place** — editing cells, adding / removing / renaming sheets inside it, analyzing, pivoting, cleaning, reformatting, or any other transformation whose deliverable is the source `.xlsx` file itself. Tasks whose intent is to produce a **new `.xlsx` file at a new path** — including those with a source spreadsheet used only as a read-only reference — belong to `tencent-docs-sheet-generation`; see "Creating a new workbook" above (and its intent test) for the routing rule and examples.

Resolve local sheet tasks by task nature. The `tencent-local-office-edit` Skill is allowed only for a small, bounded set of deterministic edits; complex or data-dependent local tasks MUST use `tencent-docs-sheetagent`.

**Decide from the request TEXT alone, never from the data.** Apply this one test to the user's wording:

> Is the request a direct, deterministic edit — its operation type is fixed by the wording (format / border / merge / insert-delete rows·cols·cells / row-height·col-width / filter / sort / sheet add-delete-move / a formula written into a named cell) — and its target is either an explicit address or a label you can pin down by a single match?

- **Yes** → operate through the `tencent-local-office-edit` Skill.
- **Other sheet content work** → `tencent-docs-sheetagent`. No deliberation, no investigation.

Match the work to the tool:

| Route here | When the local sheet task is |
|------------|------------------|
| `tencent-local-office-edit` Skill | A semantically unambiguous read/write completing in **a small, bounded set of deterministic calls** — e.g. reading or writing one specific cell/range, sorting one column (operate through the Skill) |
| `tencent-docs-sheetagent` | Data analysis · aggregation · pivot · stats, cross-sheet linkage, formula building, data cleaning, conditional formatting across ranges, or anything needing you to understand the data before deciding how to edit. For these local tasks, use `tencent-docs-sheetagent`; do not handle them through the `tencent-local-office-edit` Skill |

For local sheet files, the `tencent-local-office-edit` Skill is a right route for any direct, deterministic edit that passes the routing test above. Locating is reading the file only to find where the operation applies or what its current state is. This covers any lookup whose answer is a determinate address or value the file already contains. It is allowed on the local route and does not push the task to `tencent-docs-sheetagent`. Understanding the data — reading values to decide what the edit should be: what a previous edit did, why something renders wrong, which rows qualify under a condition you must infer, or how to aggregate / compare / clean — is the data-dependence test failing, and goes to `tencent-docs-sheetagent`. Diagnosis, comparison, and verification are the subagent's job, exactly like data discovery — they are not part of routing. Delegating means **invoking the `tencent-docs-sheetagent` skill first** — call the Skill tool with the name `tencent-docs-sheetagent` — and spawning the `sheet-agent` subagent only as it instructs; do **not** spawn `sheet-agent` directly, even though the subagent is visible on the Agent tool. `tencent-docs-sheetagent` counts as unavailable **only** if that Skill call itself fails with a not-found / unknown-skill error; only then fall back to the `tencent-local-office-edit` Skill.

**Atomic sheetagent delegation:** For one user request, if a local sheet task should enter `tencent-docs-sheetagent`, hand it the entire spreadsheet task — do not split the request by doing preparatory reads, partial writes, formatting, or cleanup through the `tencent-local-office-edit` Skill and then delegating only the remaining work. The only local calls allowed before delegating are the ones [file_id resolution](#file_id-resolution-local-documents) needs — nothing that touches document content. Note that tasks whose intent is to **produce a new `.xlsx` file at a new path** are not sheetagent tasks at all; they belong to `tencent-docs-sheet-generation` per the intent test above. Adding a sheet inside an existing workbook, on the other hand, **stays with sheetagent** — that is an in-place edit, not generation. Once `tencent-docs-sheetagent` is the route (or even a candidate), resolve the `file_id`, then **invoke the `tencent-docs-sheetagent` skill and follow its delegation contract** — do not spawn the `sheet-agent` subagent directly — forwarding the resolved `file_id`, the absolute path, and the user's request verbatim; the subagent only consumes a live `file_id` and must not open files or resolve paths itself. If the task involves another spreadsheet (e.g. comparing with, or restoring formats from, an original file), resolve that file's `file_id` the same way and pass **both** ids with their paths — do not read or inspect either file's content yourself. Saving after the subagent finishes stays with you, not the subagent — per the `tencent-local-office-edit` flow.

Between resolving the `file_id` and delegating, make **no other** local call. Do not call `sheet_get_sheet_info`, do not read cells or ranges, do not pre-locate the data, and do not "look at the data first to understand it" — data discovery (sheets, headers, ranges) is the subagent's job, and any pre-reading splits the task (see [Atomic sheetagent delegation](#sheet-files-spreadsheets) above). If a plan you formed before reading this Skill included "read the data, then delegate", drop the read step. If the subagent rejects the `file_id` you passed, re-check it per [file_id resolution](#file_id-resolution-local-documents) and re-delegate; do **not** switch to reading the data yourself.

### Examples

> These illustrate the *pattern* — judge a request by which description fits, not by whether its wording matches an example.

**Examples → local `tencent-local-office-edit` Skill**
- Read / write / format a named cell or range — e.g. "Read A1:D10", "Set B2 to 100", "Bold A1"
- A deterministic operation whose target is a concrete, addressable part of the sheet  — e.g. "Sort the 'Price' column ascending", "Set all column widths to 120px"

**Examples → `tencent-docs-sheet-generation` Skill (intent = produce a new `.xlsx` file)**
- Pure-text requirement — e.g. "做一份 6 月销售统计表", "帮我生成一张项目排期表".
- Content referenced from a non-spreadsheet material — e.g. "根据这份 PDF 整理成一个 Excel 表格", "把这个 Word 里的数据做成表格" (hand the material to the Skill; do not pre-parse it).
- Content referenced from a **source spreadsheet** used strictly as read-only reference, output is a **separate new `.xlsx` file** — e.g. "根据这个 xlsx **再生成一份新表**", "基于这份 csv **另出一张**汇总表" (intent test passes: user wants a NEW file, not to modify the source).

**Examples → local `tencent-docs-sheetagent`**
- Editing / analyzing / pivoting / cleaning **the source workbook itself** — e.g. "在这个 xlsx 里加一列合计", "透视这份数据", "帮我清洗这个 csv"; the source `.xlsx` is the deliverable, not a content reference.
- **Adding / removing / renaming sheets inside an existing workbook** — e.g. "在这个 xlsx 里加一个汇总 sheet", "给这份工作簿再加一张月度对比表", "删掉这个表里的空白 sheet"; the workbook is modified in place, so this is an edit, not generation.
- **Any** pivot-table create or edit — e.g. "Build a pivot table"; it always requires reading the source data first.
- Ambiguous scope that needs judgment — e.g. "Clean up this table".
- Layout restructuring on the source — e.g. "Move this column"; it needs to read the current structure first.

## file_id resolution (local documents)

`file_id` identifies an open local editor instance — it always comes from the **`tencent-local-office-edit`** Skill's entry tools (`get_pool_status`, `open_file`, `create_*`); never invent one from a path or filename. This section only fixes **when** each entry applies; the calling style, workflow, and error handling are owned by that Skill's own documentation.

- **Injected `file_id`** — if the context block already injected one (e.g. `<active_document type="local" ... file_id="..."/>`), use it directly. The document already has a live host-owned editor/preview instance — do **not** reopen or re-present it.
- **Existing file, no injected id** — resolve it through the `tencent-local-office-edit` Skill's documented flow (`get_pool_status` to find an already-open instance, `open_file` otherwise), then do the content work through that Skill.
- **Brand-new document (no file on disk yet)** — there is nothing to resolve; do **not** call `get_pool_status` / `open_file` on a path that does not exist. Creating the file and its first save are owned by the routed Skill (e.g. `tencent-pptx`, `tencent-docs-sheet-generation`) or the host's create flow; once the file exists on disk, re-enter here for any subsequent edit.

## Showing a document to the user (preview)

Previewing is the **host's preview surface**, not a content channel and not part of [file_id resolution](#file_id-resolution-local-documents). Present a local document to the user, per the host's preview instructions, whenever they should see it:

- **After creating a new local document** through a routed Skill (e.g. `tencent-pptx`, `tencent-docs-sheet-generation`, `tencent-docs-sheetagent`), open it so the user can immediately see and work with the result.
- **After finishing edits** on a document that is not already visible to the user, once it is saved.

Do **not** re-preview a document the context block already injected with a live `file_id`: it already has a host-owned preview instance.
```

#### tencent-docx

- 来源: 内置/市场
- 说明: 专业 Word 文档（.docx）创作与美化助手。用于生成研报、论文、公文、合同等垂类专业 Word 文档，或对已有 .docx 进行排版美化。当用户需要写文档、生成 Word、排版或美化 .docx 时调用。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\tencent-docx\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `.in_use/11012`, `.in_use/17976`, `.in_use/28812`, `.in_use/32240`, `.in_use/34544`, `.in_use/41900`, `.in_use/42840`, `.in_use/48752`, `.in_use/48900`, `.in_use/50320`, `agents/doc-converter.md`

```markdown
# 腾讯文档 Doc 智能体 —— 专业 Word / Docx / DOCX 文档创作与美化

> 端到端 **Word / Docx / DOCX 文档（.docx）** 智能体：从**专业创作 → 专业美化 → 输出交付**全流程自动编排。 覆盖：**生成专业 Word 文档、专业美化 Word / Docx / DOCX 文档、导出 .docx** 全部场景。 必须依赖 [tdoc-orchestrator SKILL](./skills/tdoc-orchestrator/SKILL.md)

---

## ⛔ 强制执行规则（MUST — 不可跳过、不可简化、不可"觉得简单就直接做"）

**空白文档例外**：若用户仅要求新建空白本地 Word/DOCX（无内容创作或排版需求），不进入本插件编排，转交 `tencent-local-office-edit` 使用 `create_doc` 创建空白模板。

**本 Skill 被加载后，你的下一步动作必须是：Read `./skills/tdoc-orchestrator/SKILL.md` 并严格按其 Stage 0 流程执行。**

### 禁止行为（违反即视为 Bug）

1. **禁止跳过 orchestrator 直接调用 MCP 编辑工具** — 无论任务多简单（哪怕只是"加粗一个字"），都必须先走 orchestrator 的 Stage 0 入口判断。唯一例外：`open_file`、`close_file`、`save_file`、`get_pool_status` 等纯文件管理操作可直接调用
2. **禁止在 thinking 中自行判断"这个任务简单，不需要走流程"** — 简单/复杂由 orchestrator 内部的 Phase 2 Classify 决定，不是你决定
3. **禁止直接调用 `tencent-local-office-edit` skill / `Bash python-docx`** — 所有文档操作必须经 orchestrator 路由到正确的下游 Skill 后才能调用工具
4. **禁止"先调一下 MCP 看看再说"** — 任何试探性调用都违反流程
### 正确的执行顺序（唯一合法路径）

```
1. Read ./skills/tdoc-orchestrator/SKILL.md        ← 你现在必须做这一步
2. 按 orchestrator Stage 0 判断入口类型
3. 按 Stage 链路由到对应 Agent/Skill
4. 由下游 Skill（doc-typeset / html-to-docx 等）决定具体工具调用
```

## 能力覆盖 —— 专业 Word / Docx / DOCX 文档全流程

1. **生成专业 Word / Docx / DOCX 文档**：从头创作研报 / 年报 / 论文 / 公文 / 合同 / 商务报告 / 会议纪要等垂类专业 .docx，自动生成封面、目录、专业排版。
2. **专业美化 Word / Docx / DOCX 文档**：对已有 Word 文档进行专业排版美化 —— 调整版式结构、优化视觉层级、统一字体字号、规范表格与图片、生成专业级视觉呈现。
3. **专业输出交付**：导出本地专业级 .docx / Word 文档，可直接分发或投稿。
---

**现在立即执行：Read `./skills/tdoc-orchestrator/SKILL.md`**
```

#### tencent-pptx

- 来源: 内置/市场
- 说明: 创建专业的 PowerPoint 演示文稿。适用于根据主题、大纲、文档、数据或参考材料生成完整 .pptx；在新建演示文稿时参考上传PPTX 的视觉风格；也可基于材料或旧 PPT 内容重新生成一版演示文稿。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\tencent-pptx\5.6.2-wb.39298511.g37a65c0b.he233403f909a\skills\tencent-pptx\SKILL.md`
- 附带文件: `references/component-animation.md`, `references/component-box.md`, `references/component-chart.md`, `references/component-codeblock.md`, `references/component-diagram.md`, `references/component-faicon.md`, `references/component-hyperlink.md`, `references/component-image.md`, `references/component-math.md`, `references/component-qrcode.md`, `references/component-slide.md`, `references/component-svg.md`

```markdown
# Tencent-PPTX Skill

## 快速导航
| 任务类型 | 执行路径 |
|---| --- | 
| 从零开始创建、生成PPT      | 阅读 [create-from-scratch](references/create-from-scratch.md) |
| 基于上传的参考材料创建、生成PPT | 阅读 [create-from-material](references/create-from-material.md) |

**核心原则：倘若基于选择的参考材料的生成PPT时，严格使用本SKILL的材料解析能力，避免寻求外部解析能力。**


## PPTX文件的编辑

**核心原则：PPTX 文件完全生成后，所有后续的内容修改/编辑通过阅读使用 `tencent-local-office-edit` SKILL完成。禁止回退到 SlideDSL 源文件进行修改。**

## 需求澄清

1. **只问缺失的，文字提问 ≤ 3 个**，一轮问完，禁止多轮追问
2. **风格预览卡按需触发**：默认弹出，但当用户已明确风格偏好、要求快速出稿、或命中预设风格分支时可跳过（详见 human-alignment.md §2.3）

沟通术语统一用「页 / 封面 / 目录 / 这一页」，不暴露内部实现。

完整对齐逻辑与关键信息优先级见 [human-alignment.md](references/human-alignment.md)。


## 目录结构规范

每个 PPT 对应一个独立的 `project_dir`，多个 PPT 项目并存于用户的 `workspace_dir` 下：

```markdown
<workspace_dir>/                    # 用户工作目录，可包含多个 PPT 项目
├── <project_dir>/                  # 单个 PPT 的完整工作目录（目录名 = pptx 文件名去后缀）
│   ├── DESIGN.md                   # PPT 视觉设计文档
│   ├── STORY.md                    # PPT 内容叙事文档
│   ├── assets/                     # PPT 页面引用的静态资源文件
│   ├── slides/                     # PPT 页面，即 SlideDSL 源文件（每页一个 .slide 文件）
│   │   ├── 01.slide
│   │   ├── 02.slide
│   │   └── 03.slide
│   └── <pptx_name>.pptx           # 生成的演示文稿
```

命名约定：
- 项目目录名：与 pptx 文件名去 `.pptx` 后缀一致（如文件名 `季度汇报.pptx` → 目录名 `季度汇报/`）。
- 页面文件：`{两位序号}.slide`，如 `01.slide`。
- 资源文件：禁用中文、空格、特殊字符。

## 环境介绍

slidep 已安装到 Node 托管环境中，可直接使用以下子命令：

| 命令 | 用途 |
|------|------|
| `slidep create <file>` | 创建空白 PPTX 文件 |
| `slidep upsert-dsl <file> --dsl-file <path> [--page-index N]` | 向 PPTX 插入或替换 DSL 页（替换时须指定 `--page-index`，省略则追加） |
| `slidep lint <file> --dsl-file <path>` | 校验 DSL 页内容（语法与溢出检测） |
```

#### tencent-local-office-edit

- 来源: 内置/市场
- 说明: 通过本地 editor_sdk 实时读写本机磁盘上的 Office/WPS 类型文件——文件打开后用户在编辑器中实时可见，编辑所见即所得，保存用 save_file 即可、不要主动 close_file。适用于本地 doc/docx/dot/wps/wpt、xls/xlsx/xlt/csv/tsv、ppt/pptx/pps/pot 等文件的打开、编辑、保存与新建；含宏格式可打开但宏不执行，et/ett/dps/dpt 不支持。按 doc/sheet/slide 三类调用对应工具，调用任一编辑工具前先用 edsdk.py schema 查它单个的参数、不要凭摘要猜参数。所有操作经本目录 edsdk.py（python3 edsdk.py list/schema/call）封装，端点自动发现、上层无需关心底层细节。触发词：本地文档、本机 docx/xlsx/pptx/wps、Office/WPS 文件、editor_sdk、edsdk.py、本地编辑、实时编辑。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-tencent-local-office-edit\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `doc.md`, `doc/table.md`, `edsdk.py`, `sheet.md`, `slide.md`

```markdown
# 本地 editor_sdk MCP 应用

> 面向**本机磁盘文档**，通过本地 `editor_sdk` 进程的 MCP 服务读写。支持编辑的格式按三个品类归类：
> - **doc**：`.doc` `.dot` `.wps` `.wpt` `.docx` `.dotx` `.docm` `.dotm`
> - **sheet**：`.xls` `.xlt` `.xlsx` `.xltx` `.xlsm` `.xltm` `.csv` `.tsv`
> - **slide**：`.ppt` `.pps` `.pot` `.pptx` `.ppsx` `.potx` `.pptm` `.ppsm` `.potm`
>
> 打开时按文件内容（magic bytes）自动识别品类，扩展名仅作兜底。
> ⚠️ 这是**本地 Office/WPS 文件操作**通道，只操作本机磁盘上的文件。

### 格式限制

- **新建文件**：`create_doc` / `create_sheet` / `create_slide` 使用内置空白模板，分别新建 `.docx` / `.xlsx` / `.pptx`。
- **含宏格式**：`.docm` `.dotm` `.xlsm` `.xltm` `.pptm` `.ppsm` `.potm` 可按对应品类打开和编辑文档结构，但**宏不执行**，剥离宏后可能导致数据或样式差异。
- **不支持的 WPS 专属格式**：`.et` `.ett` `.dps` `.dpt` 当前不支持；需要先用 WPS 客户端另存为 `.xlsx` 或 `.pptx` 后再处理。
- **不属于本 Skill 的编辑范围**：`.xmind` 有独立 Mind Editor 但本目录未暴露 mind MCP 工具；`.pdf` / `.ofd` 仅查看，不提供编辑工具。

## 前置

- `python3`
- 本地 `editor_sdk` 服务已运行（默认从端口 39099 起探测）
- 所有调用都通过本目录的 **`edsdk.py`** 封装脚本完成（HTTP 直连 MCP 端点）：
  ```bash
  python3 edsdk.py list        # 验通：能列出工具即 OK
  ```
  > 未设置 `editor_sdk_port` 时，按顺序探测 `39099` 到 `39108` 共 10 个端口；命中后复用该端点。
  > 如需固定端口：`editor_sdk_port=40001 python3 edsdk.py list`（设置后只访问指定端口）。
  > 如服务启用鉴权，设置 `editor_sdk_token`。

## 🚧 强制流程（违反将导致参数错误 / 调用失败）

对任何 `doc_*` / `sheet_*` / `slide_*` 编辑工具：**渐进式按需查询，不要一次性拉全量 schema**。流程：

1. **读子文档**：如果是Word类任务，必须先读取[doc.md](./doc.md)。
2. **选工具**：从子文档（[doc.md](./doc.md) / [sheet.md](./sheet.md) / [slide.md](./slide.md)）的一句话清单里挑出要用的工具——这一步不需要命令，清单就是索引。
3. **只查该工具 schema**：`python3 edsdk.py schema <工具名>`，直接得到必填项与各字段说明（内部只取这一个工具，不会全量打印）：
   ```bash
   python3 edsdk.py schema doc_insert_text
   ```
4. **调用**：确认 `[✓]` 必填项与各字段语义后再调。

> 用到一个才查一个，没用到的工具不要预先查。未经 `schema` 查询直接拼参数调用，属于流程违规。

调用前自检（缺一不可）：

- ☐ 已对**本次要用的工具**跑过 `edsdk.py schema <工具名>`
- ☐ 已确认全部 `[✓]` 必填字段
- ☐ 已确认位置 / 坐标 / 单位约定（如 doc 的 UTF-16 偏移、slide 的磅(pt)）
- ☐ **【仅 `sheet_*` 写值工具】** 调 `sheet_set_range_value` / `sheet_set_range_value_by_csv` /
  `sheet_set_cell_value` 前，已用 `sheet_get_used_range` 探明真实已用区域边界
  —— 不得用肉眼观察、文件预览或上一次读取的行数去猜边界
- ☐ **【仅 `sheet_*`】** 已按用户意图选对分支（二者选一，见 `sheet.md` HARD RULE）：
  - **新增**（用户表达「新增 / 添加 / 再加 / 插入 / 追加」行或列）→
    已先调 `sheet_insert_dimension` 腾出空间，确认目标区域为空后再写，而不是直接覆盖已用区域
  - **修改**（用户明确表达「修改 / 替换 / 更正 XX」）→
    已先 `sheet_get_cell_data` 读回目标区域，确认要覆盖的内容与用户意图一致后再写

> 若你不确定某工具的必填参数，**默认你没查过**——先 `schema` 再调，不要凭子文档表里的一句话摘要猜参数。

## 约定 —— `edsdk.py` 三条命令

| 命令                                                        | 作用                                                                                   |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `python3 edsdk.py list [doc\|sheet\|slide\|common]`         | 列出工具（工具名 + 一句话描述）；可按品类过滤                                          |
| `python3 edsdk.py schema <工具名>`                          | **按需**查单个工具的完整参数（required + 各字段说明）。加 `--raw` 附带原始 inputSchema |
| `python3 edsdk.py call <工具名> [k=v ...] [--json '{...}'] [--json-file args.json]` | 调用工具                                                                               |

入参写法：`key=value`（值优先按 JSON 解析：数字 / 布尔 / 数组 / 对象 / null，失败则当字符串）；
复杂 / 嵌套参数用 `--json '{...}'` 或 `--json-file args.json`（与 `key=value` 合并，同名键以后者为准）。

- **`file_id` 是一切编辑的入口**：先尝试 `get_pool_status`/ `create_*` 拿到工具返回的真实 `file_id`，再调品类工具（见下方强制流程）。`file_id` 是 pool 里实例的 key，**不一定是路径**——见下方「打开文档必须用 `present_files`」说明。
- **品类由文档类型决定**：`doc_*` 只能作用于 doc 文档，依此类推；类型不匹配会报错。
- **编辑后重新读取**：编辑后若要基于文档现状继续操作，先重新读取最新数据；不要沿用编辑前缓存的内容、位置或版本。
- **保存后不要主动关闭**：保存用 `save_file`；不要主动 `close_file`，除非用户明确要求关闭或确实需要释放资源。
- **源码 1:1 对应**：`doc_*` → `server/mcp/doc/`，`sheet_*` → `server/mcp/sheet/`，`slide_*` → `server/mcp/slide/`。

## 工作流：先打开文件，再编辑，最后保存

> ⚠️ **本套操作是实时、可视化的**——文件打开后用户正在实时查看编辑效果。
> **不要主动调 `close_file`**：保存用 `save_file` 即可，关闭会关掉用户正在看的视图、释放编辑器。
> 仅在用户明确要求关闭、或确实需要释放资源时才调 `close_file`。

> ⚠️ **打开文档必须用 `present_files` 工具**：要让用户在预览面板中看到文档，必须调用 `present_files` 把文件呈现给用户——不能只在回复里说「已打开」。`edsdk.py call open_file` **不会**在预览面板里打开文档：`open_file` 只在**后台** editor_sdk 里把文件读进内存，供 Agent 后续 `doc_*` 等工具编辑，**用户界面不会出现这份文档**（与 `present_files` 相反）。
>
> - **前端 / `present_files` → HTTP `/api/open`**：未指定 `file_id` 时服务端生成 **UUID**（如 `5dca3e56-389b-461e-88c6-...`）。之后 `get_pool_status`、以及编辑工具只传 `file_path` 时 `ResolveFileId`，都会反查到这个 UUID。
> - **`create_*`**：返回 `new_doc_...` / `new_sheet_...` 等可读 id。
>
> **`open_file` 与 `doc_*` 的区别**：`doc_*` 在 `file_id` 缺省时会 `ResolveFileId(file_path)`，路径已注册则 **复用已有实例（多为 UUID）**。`open_file` **默认不从 pool 找已有实例**（`open_with_existing` 未传或 `false`）：未显式指定 `file_id` 时 **强制用 `file_path` 字符串本身作 key**（如 `/abs/foo.docx`），从磁盘 **fresh open**（`OpenByChunks` 重读）；纯后台 MCP、无用户预览时，返回的 `file_id` 往往就是路径字符串。用户已在看文档时 **不要默认 `open_file`**——会再开一个与前端 SSE 订阅脱节的实例，看不到实时改动。
>
> **`open_with_existing`（仅 `open_file` 可选）**：默认 `false` = 不管 pool 里有没有同路径文档，都按上文 fresh open。传 `true` = 先问 pool「这个路径是否已打开」：有则 **沿用已有 `file_id`（多为 UUID）** 和内存里的文档，不再从磁盘重开；没有则与默认行为相同。找不到已有实例、或磁盘文件已更新时，服务端会清掉旧实例再重开。仅在 `get_pool_status` 查不到、但你确信该路径已在 pool 里时，才用 `open_file file_path=... open_with_existing=true`。
>
> ⚠️ **`present_files` 之后不要 `open_file`**（尤其默认 fresh open）：`present_files` 会在 editor_sdk 注册实例（**UUID `file_id`**）。此时应 **`get_pool_status` 按路径拿 `file_id`**，或从用户选区取 `file_id`，再直接 `doc_*`。重复默认 `open_file` 会再开实例——上传后用户中途点开侧边栏时尤其常见：模型先 `open_file`（key=路径）在改，用户点开生成 UUID 实例并订阅 UUID stream，模型若仍只用 `file_path` 可能命中「孤儿」路径实例，revision 推到 path stream，页面绑 UUID stream → **看不到实时改动**；改完 `save_file` 落盘至少能兜底。
>
> ⚠️ **`present_files` 返回的是文件地址，不是 `file_id`**：不能直接当 `file_id` 传给 `doc_*` / `sheet_*` / `slide_*`。`file_id` 来自 `get_pool_status`（已展示文档）、`create_*` 的返回，或**仅后台、无需用户预览**时 `open_file` 的返回值。传 `file_path` 给编辑工具时须与注册时 **字符串完全一致**（`./x.docx` ≠ `/abs/x.docx`）；`get_pool_status` 的 `file_path` 过滤会做规范化，编辑工具反查 **不会**。

```bash
# 1. 在预览面板呈现给用户（硬约束：必须调用 present_files）
present_files 工具：把 /abs/a.docx 在预览面板中打开给用户看
# 2. 从 pool 拿真实 file_id（不要 open_file）
python3 edsdk.py call get_pool_status --json '{"file_path":"<同上路径>"}'
#    → 在 editors 里取 file_id（多为 UUID）；后续编辑一律用这个 file_id，不再拼路径

# 3. 编辑（按品类调用，见下方子文档；调用前先 schema 查参数）
python3 edsdk.py schema doc_insert_text
python3 edsdk.py call doc_insert_text file_id=<上一步返回的 file_id> idx=0 text="hi"

# 4. 保存（file_path 省略则覆盖原文件）—— 到此即可，不要主动 close
python3 edsdk.py call save_file file_id=<上一步返回的 file_id>
```

> **`get_pool_status` 未命中时**（`present_files` 后偶发游离实例或尚未注册）：
> 1. 先再次尝试 `present_files`，然后用与 `present_files` **相同**的路径字符串再查一次；
> 2. 仍无则 `open_file file_path=... open_with_existing=true`（**不要**默认 fresh `open_file`）；
> 3. 仍失败再与用户确认路径。

## 通用工具（文件 / 会话管理，无品类前缀）

这些是**入口工具**，所有品类共用；具体编辑接口见各子文档。

| 工具 | 必填 | 说明 |
|---|---|---|
| `open_file` | `file_path`；可选 `open_with_existing`（默认 `false`）、`file_type`（`doc`/`sheet`/`slide`，可省略自动识别）、`password`、`image_dir` | **后台打开**本地文件（仅 editor_sdk 内存，**预览面板不展示**），返回 `file_id`。默认 fresh open（返回的 `file_id` 多为 `file_path` 本身）；`open_with_existing=true` 时复用 pool 里同路径已有实例（`file_id` 多为 UUID）。|
| `get_pool_status` | — | 查看 pool；**`present_files` 之后用它拿 UUID `file_id`**（`file_path` 过滤支持规范化匹配，比编辑工具的路径反查更宽容） |
| `save_file` | — | 保存到本地；`file_path` 省略则覆盖原文件 |
| `close_file` | `file_id` | 关闭编辑器、释放资源。⚠️ **实时可视化场景下不要主动调**——会关掉用户正在看的视图；仅在用户明确要求时调 |
| `create_doc` / `create_sheet` / `create_slide` | — | 从空白模板新建对应类型文档，返回 file_id |
| `shutdown` | — | 关停 editor_sdk 服务 |

## 品类编辑接口（按文档类型进入子文档）
`file_id` 拿到后，按文档类型调对应品类的工具（工具名带品类前缀）：
| 品类      | 文档类型                         | 工具数 | 子文档                 |
| --------- | -------------------------------- | ------ | ---------------------- |
| **doc**   | Word/WPS 文档类（doc/docx/dot/wps/wpt…） | 37     | [doc.md](./doc.md)     |
| **sheet** | Excel 表格类（xls/xlsx/xlt/csv/tsv…）    | 51     | [sheet.md](./sheet.md) |
| **slide** | PPT 演示类（ppt/pptx/pps/pot…）          | 77     | [slide.md](./slide.md) |
```

#### tencent-docs-sheet-generation

- 来源: 内置/市场
- 说明: >
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\sheetagent\5.6.2-wb.39298511.g37a65c0b.he233403f909a\skills\excel-generation\SKILL.md`
- 附带文件: `references/design_patterns/calendar.md`, `references/design_patterns/dashboard.md`, `references/design_patterns/form_print.md`, `references/design_patterns/model.md`, `references/design_patterns/plan.md`, `references/design_patterns/progress.md`, `references/design_patterns/stats.md`, `references/schema_principle.md`, `scripts/extract.py`, `scripts/office/soffice.py`, `scripts/recalc.py`, `scripts/requirements.txt`

```markdown
# Excel 生成链路 (tencent-docs-sheet-generation)

本 skill 默认采用 **openpyxl 直写** 范式：主代理读取设计准则与范式后，**直接编写 openpyxl 建表脚本一次性生成整份工作簿**，不委派子代理。最终产出本地 xlsx 文件。

---

## 适用范围与拒绝条件

**适用**（进入本 skill 的前提是**意图为"生成一份新工作簿"**）：

- 用户表达明确的"创建/生成/新建/做一份/整理成一份新表/汇总成新表"等**生成**意图
- 目标产出是**一份新的 xlsx 工作簿**（不修改任何已有源文件）
- 三类输入均可作为内容依据：
  - 纯文字需求（无附件）
  - 本地 **pdf / docx / pptx** 附件作为内容参考
  - 本地 **`.xlsx` / `.xls` / `.csv` / `.tsv`** 源表作为**内容参考素材**——只读其数据来构建新表，绝不写回源文件
- 支持将参考素材用于从零生成本地工作簿
- 支持以**在线文档**（`docs.qq.com` 链接 / `file_id`，含跨品类的 doc / slide / 在线 sheet）作内容 / 样式参考（用 MCP 读取，见 Step 2）

**不适用**（命中任一项即退出，由 routing 重新分派）：

- **编辑意图**——用户实际是要**编辑 / 分析 / 透视 / 清洗**源 xlsx / xls / csv / tsv 本身（应走 sheetagent 或本地编辑链路）。判定信号：
  - 措辞指向"改这个表"而非"另出一份新表"（"改这份表 / 修一下 / 补个公式 / 加一列 / 排序 / 筛选 / 合并 / 格式 / 透视 / 数据分析 / 清洗"）
  - 对源文件本身做变更、比对、审阅、修复
- **非表格产出**——用户要求生成 docx / pptx / md 等非表格
- **不支持的本地附件类型**——本地附件非 pdf / docx / pptx / xlsx / xls / csv / tsv（如 zip / 图片）；告知用户当前仅支持这些本地附件（**在线文档参考除外**，走 Step 2 的 MCP 读取）

---



## 执行流程（5 步）

### Step 1: Reasoning & Naming

**核心：推断目标 title，全程不反问用户**。

从用户需求推断两样即可：**展示标题**与**落盘位置**。

- **推断标题**：从用户原话 / 附件名取一个简洁标题；用户明确指定的名字优先，实在无线索用 `workbook_<YYYYMMDD_HHMMSS>`。用户指定的是目录（"放到/放在/保存到"或目录路径）时只取作落盘目录，标题仍独立推断；只有显式文件名路径才拆 dirname/basename，并从 basename 去掉 `.xlsx`（避免 `Q1.xlsx.xlsx`、避免把整条路径当标题）。
- **`<sanitized_title>`**（文件系统用）：对**推断标题**（未截断）做 sanitize——删 `\ / : * ? " < > |`、trim 首尾空格、中间空格转 `_`、≤ 50 字符；只用于文件名 / 目录名，不碰路径分隔符。
- **`<title>`**（展示用）：即推断标题原样，用于 OOXML 显示标题。

产出本地 xlsx，纸面算出（写进脚本的必须是绝对路径）：

- **落盘目录**：用上面从文件名 / 路径拆出的目录；无则默认 cwd。`~` 先展开成绝对路径。
- `<output_xlsx>` = `<落盘目录>/<sanitized_title>.xlsx`（最终交付物）；**已存在则加 `_<YYYYMMDD_HHMMSS>`，不覆盖、不询问**。
- `<work_dir>` = 同目录下的 `.<output_xlsx 的 stem>.ref/`（基名与 `<output_xlsx>` 一致：撞名带了时间戳时同步带上，二者始终配对；存 build.py / extract 产物）。

> Step 1 只做纸面计算；工作目录在 Step 2 创建，其余文件按后续步骤生成。

### Step 2: 附件预处理

先建工作目录（本 skill 落盘的根——Step 2 参考产物、Step 4 的 `build.py` 都在其下）：`mkdir -p "<work_dir>"`。

再判断有无内容参考素材，按来源分流（**无参考 → 直接进 Step 3**）：

| 来源（如何识别） | 动作 |
|---|---|
| 在线文档参考（`docs.qq.com` 链接 / `file_id`，可能是 doc / slide / 别的在线 sheet；作为普通参考素材处理） | 用 MCP 读其**数据 + 样式**（doc 用文档读取工具；sheet 用 `read_table` / `get_cell_ranges` 含样式） |
| 本地 pdf/docx/pptx（消息里的文件路径 +「基于这份 pdf / 参照 docx / 按这个 ppt」等） | 用 `extract.py` 抽取（命令见下），落到 `<work_dir>/reference/<sanitized_input_stem>/`；`<sanitized_input_stem>` 为输入文件去扩展名后按 Step 1 sanitize 规则处理 |
| 本地 xlsx/xls/csv/tsv **作为参考**（意图已确认是"生成新表"，源文件仅供读取） | 用 `extract.py` 抽取（同一命令，脚本按后缀自动分流：xlsx/xls 逐 sheet 转 markdown 表格；csv/tsv 转 markdown 表格），落到 `<work_dir>/reference/<sanitized_input_stem>/`。**严禁**打开源文件写回、也不得在 Step 4 里把源路径当 `<output_xlsx>`。**已知边缘 case**：xlsx 抽取用 openpyxl `data_only=True` 读缓存值——若源表由程序化方式生成、从未被 Excel/WPS/LibreOffice 打开过，公式单元格会读到空；此时提示用户先用 Excel/WPS 打开并保存一次再上传 |
| 本地非上述类型（zip / 图片） | 见「不适用」段，不抽取 |

多个参考 → 逐个处理。

**extract.py**（Bash）：

```bash
python3 "${CODEBUDDY_PLUGIN_ROOT}/skills/excel-generation/scripts/extract.py" \
  "<input_file_absolute_path>" -o "<work_dir>/reference/<sanitized_input_stem>"
```

产物（按输入类型不同而略有差异）：
- pdf / docx / pptx → `content.md`（文本，含图片引用）+ `images/`（原图）+ `thumbnails/`（PNG ≤600px，可直接 Read 看图）
- xlsx / xls → `content.md`（每个 sheet 一段 markdown 表格，含表头 + 数据；空 sheet 会标注）
- csv / tsv → `content.md`（单张 markdown 表格）

`extract.py` **按需自动装**缺失依赖（勿手动 pip）；exit=0 成功，exit≠0（依赖 / 输入 / 格式问题，装失败为 exit=4）**把 stderr 原样转用户并中止**。

完成后进入 Step 3（参考内容在 Step 3 纳入原型判断）；写脚本时按需回看 `<work_dir>/reference/` 取具体数据。

### Step 3: 读设计准则与范式（动笔前必读）

> ⛔ **硬性规则——写 openpyxl 建表脚本之前，必须先 Read `${CODEBUDDY_PLUGIN_ROOT}/skills/excel-generation/references/schema_principle.md`，无例外。** 不读准则就写代码 = 任务失败。

按序读取，读完即据此直接写 Step 4 的建表代码（不另写设计文档）：

1. **Read `schema_principle.md`**——建表所有设计决策（sheet 结构、列、公式、样式、条件格式、数据策略）以它为准；用户明确要求与之冲突时，以用户要求为准。
2. **识别场景原型**——有参考素材时先纳入其内容（在线参考已在上下文；本地附件先 Read `<work_dir>/reference/<sanitized_input_stem>/content.md`，扫描件 / 图多辅看同目录 `thumbnails/`），据**用户意图 + 参考内容**按其 §1 判定原型。
3. **按 `schema_principle.md §1`「范式文件」列直接 Read `${CODEBUDDY_PLUGIN_ROOT}/skills/excel-generation/references/design_patterns/<范式文件>`，无需预先枚举目录**（组合场景读多个再融合；标"—用通用准则"或未命中则跳过，直接用通用准则）。pattern 是**可改编蓝图**、按需调整不僵化套用，且**只给场景布局/字段增益、绝不复制 `schema_principle` 的具体数值**；防错（公式坐标、布局锚点、空值/除零保护）仍以 `schema_principle` 为准。

### Step 4: 编写并执行 openpyxl 建表脚本

综合已读的准则、pattern 与用户需求，直接写一份 openpyxl 脚本一次性生成整份工作簿（用 Write 工具写入 `<work_dir>/build.py`；工作目录已在 Step 2 建好）。设计细节遵循 `schema_principle` 与命中 pattern、此处不复述；写代码时落实以下**执行机制 + 两条最易漏的防错**：

- **用 openpyxl**；脚本开头做「先 import、缺失才装」的幂等兜底，**不要无条件 `pip install`**（否则重跑循环每轮都白装一次、离线环境还会失败）：

  ```python
  try:
      import openpyxl
  except ImportError:
      import subprocess, sys
      subprocess.check_call([sys.executable, "-m", "pip", "install", "--quiet", "openpyxl>=3.1.0"])
      import openpyxl
  ```
- **颜色格式**：设计准则中的颜色统一采用 CSS `#RRGGBB`。用于 openpyxl 单元格样式或工作表标签色的 CSS 色值字面量只能出现在 `xl_color(...)` 参数内；静态颜色必须在常量定义时一次性转换并使用 `XL_` 前缀，后续直接使用该常量，不在调用点重复转换，禁止手工添加 `00` Alpha。图表颜色不使用本函数，按图表 API 要求传不带 `#` 的六位 RGB：

  ```python
  def xl_color(css_hex: str) -> str:
      value = css_hex.removeprefix("#").upper()
      if len(value) != 6:
          raise ValueError(f"Expected #RRGGBB, got: {css_hex}")
      return "FF" + value

  XL_PRIMARY = xl_color("#4472C4")
  XL_BORDER = xl_color("#BFBFBF")
  thin_side = Side(style="thin", color=XL_BORDER)
  ```
- **公式**用 Excel 公式字符串写入（`ws['B10'] = '=SUM(...)'`），交给 openpyxl 直接落格，**不在 Python 里算好再写死**；**写除法 / 比率公式时，字符串里当场带上分母空值和 0 值保护（§4.1），不能只在注释里写**。
- **复杂表先定坐标锚点**（标题 / 表头 / 数据 / 合计的真实行号），公式坐标、填充范围、条件格式范围都由锚点推导，不套用默认第 2 行（§2.3）。
- **写入 OOXML 标题**：`wb.properties.title = "<title>"`（显示标题）。
- **保存路径**：`wb.save("<output_xlsx>")`（Step 1 的最终交付路径）。
- **代码风格**：简洁、按 sheet/区块分节加简短注释；脚本末尾 `wb.save(...)`。

**执行脚本**（Bash）：

```bash
python3 "<work_dir>/build.py"
```

- exit=0 → 生成成功，进入 Step 5 校验。
- exit≠0 → 读 stderr 定位错误（多为 openpyxl API 用法/坐标问题），**改 `build.py` 后重跑**；openpyxl 安装失败则告知用户 `pip install openpyxl`。

### Step 5: 校验与交付
**本平台：recalc 校验公式零错误**。

**① 重算 + 扫错**（仅工作簿使用公式时执行；无公式则直接进入交付）：

```bash
python3 "${CODEBUDDY_PLUGIN_ROOT}/skills/excel-generation/scripts/recalc.py" "<output_xlsx>" 60
```

openpyxl 写入的公式只是字符串、**不带缓存值**；重算前这些单元格对 `load_workbook(data_only=True)`、pandas 以及**大多数预览器（含微信/邮件附件预览）** 都读作 `None`（显示空白）。因此含公式时必须重算成功才能交付。

脚本按三层降级补齐缓存值，返回 JSON 时用 `engine` 标明本次实际使用的引擎：

1. `libreoffice` —— 在隔离 profile 中用 LibreOffice 重算（权威引擎）
2. `formulas` —— LibreOffice 不可用时，使用已安装的纯 Python 引擎求值并把值回填进公式单元格（公式本身保留，Excel/WPS 打开后仍可编辑重算）；只有所有公式都得到单值缓存才算成功，多值/动态数组结果会明确失败，避免只回填 spill 首格却误报成功
3. 两者都不可用 → **无法产出缓存值**，按失败返回 `error`

Linux 受限环境中，LibreOffice 层可能因原生 socket shim 未获授权而转入后续降级。**代理不得自行设置 `SHEETAGENT_ENABLE_LO_SOCKET_SHIM=1`**；仅在用户或平台明确授权后才能开启。

`formulas` 缺失时默认不会下载依赖。**代理不得自行添加 `--allow-install`**；仅在用户或平台明确授权从 Python 包源下载依赖后，才能用该参数重跑。

判定只看 JSON，不必关心用了哪个引擎：

- `status=success`（`total_errors=0`）→ 通过，进入交付。
- `status=errors_found` → 按 `error_summary` 的错误类型与定位（`#REF!`/`#DIV/0!`/`#VALUE!`/`#NAME?` 等）**回到 `build.py` 改对应公式（补空值/除零保护、修坐标/引用）后重跑 Step 4，再重算**，直到零错误。
- 返回 **`error` 字段**（而非 `status`）→ 没有得到一套完整缓存值，文件里的公式仍可能空白或不完整，**禁止交付**。按 `error` 内容处置：LibreOffice 不可用且 `formulas` 缺失时，提示用户手动安装，或在获得明确授权后加 `--allow-install` 重跑；LibreOffice 重算超时则调大 timeout 重试；纯 Python 引擎拒绝多值/动态数组结果时，安装 LibreOffice 后重试，或把公式改写成逐格的标量公式。
- **拒绝重算**（`error` 含 `external_link_cells`）→ 工作簿链接了外部工作簿且缓存值已丢失，重算会破坏外链数据。本 skill 从零生成的表不应出现外链；若出现说明公式误用了外部引用，**回 `build.py` 去掉外部工作簿引用后重跑**，不要用 `--force` 强行重算。

**判定纪律（勿凭退出码判断）**：只有返回 `error` 的情况才非零退出，**`errors_found` 的退出码是 0**。所以绝不能把"命令 exit=0"当作通过 —— 必须读 JSON 里的 `status` 与 `total_errors`。

**timeout 语义**：第二个参数是「初始化隔离 profile + 执行重算」的**总预算**（秒），默认脚本内为 30，本流程传 60。只作用于 LibreOffice 层；纯 Python 降级层不受其约束。



**② 交付**：

```
已为您生成 <output_xlsx>，包含 <N> 个工作表：<sheet_names>。
```

---

## 错误处理

| 场景 | 处理 |
|---|---|
| `build.py` 执行 exit≠0 | 读 stderr 定位（openpyxl API / 坐标 / 依赖），改 `build.py` 后重跑；依赖装不上则提示用户手动 `pip install openpyxl` |
| `recalc.py` 报公式错误 | 回 `build.py` 修公式后重跑 Step 4 再重算；反复 3 次仍不过，停下向用户说明具体错误 |
| `recalc.py` 返回 `error` | 没有得到一套完整缓存值，公式在外部预览中可能空白或不完整 → **不得交付**；按 `error` 内容处置（`formulas` 缺失则手动安装，或获得明确授权后加 `--allow-install` 重跑 / LibreOffice 重算超时则调大 timeout / 多值或动态数组结果则安装 LibreOffice 或改写为逐格标量公式 / 外链拒绝回改公式），并向用户说明 |
```

#### tencent-docs-sheetagent

- 来源: 内置/市场
- 说明: >
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\sheetagent\5.6.2-wb.39298511.g37a65c0b.he233403f909a\skills\excel-handler\SKILL.md`

```markdown
将此任务委派给 **sheet-agent** 子代理处理。

## 传递给子代理的内容（仅限以下四项）

1. **文件路径** — 用户上传或引用的 Excel/CSV 文件的完整路径
2. **用户输入** — 用户的原始自然语言需求，原样转发，不做改写
3. **当前时间** — 主代理上下文中的当前时间信息，原样传递给子代理
4. **期望返回** — 告诉子代理需要返回什么结果给用户（如数据摘要、操作确认等）

## 禁止

- **禁止**添加实现步骤、工具名称、操作流程或任何执行细节
- **禁止**告诉子代理该如何完成任务或该调用哪些工具
- **禁止**主代理直接调用 `mcp__sheetagent__*` 工具

## 前置条件

若用户只上传了文件但没有给出具体指令，先询问用户希望做什么，得到回复后再调用子代理。
```

#### pptx

- 来源: 项目生成
- 说明: >-
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2096525080079265792\pptx\SKILL.md`
- 附带文件: `LICENSE.txt`, `README.md`, `_icon.png`, `_meta.json`, `references/zh-CN.md`, `schemas/dml-chart.xsd`, `schemas/dml-chartDrawing.xsd`, `schemas/dml-diagram.xsd`, `schemas/dml-lockedCanvas.xsd`, `schemas/dml-main.xsd`, `schemas/dml-picture.xsd`, `schemas/dml-spreadsheetDrawing.xsd`

```markdown
# PPTX creation, editing, and analysis

> **语言 / Language**：中文输入请先阅读 `references/zh-CN.md`，并全程使用中文输出；其他语言直接使用下方英文指南。
> For Chinese input, read `references/zh-CN.md` first and respond in Chinese throughout; otherwise follow the English guide below.


A `.pptx` is a ZIP archive of XML files. Choose your approach by task:

| Task | Approach |
|---|---|
| **Create** a new deck | Write a `pptxgenjs` script — see gotchas below |
| **Edit** an existing deck, or build from a template | unzip → edit `ppt/slides/slideN.xml` → zip |
| **Read** content | `markitdown deck.pptx` (one block per slide under `<!-- Slide number: N -->` markers); visual grid: `python scripts/thumbnail.py deck.pptx` |

## Scripts

Paths are relative to this skill's directory. Everything else is plain Python, `node`, or shell.

| Script | What it does |
|---|---|
| `scripts/thumbnail.py deck.pptx [prefix]` | Labeled grid of every slide, for picking template layouts. `.pptx` only. Pass `prefix` — it defaults to `thumbnails`, which overwrites the grids of any other deck done in the same directory |
| `scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml]` | Duplicate a slide (or a `slideLayoutN.xml`) with all the package bookkeeping. Also takes a `.pptx` directly with `-o out.pptx` |
| `scripts/clean.py unpacked/` | Delete slides, media, and rels no longer referenced. Run **after** `<p:sldIdLst>` is final |
| `scripts/validate.py deck.pptx [--original src.pptx]` | Schema, relationship, content-type, chart and slide checks; each failure names its fix. Pass `--original` for any template-derived deck — it baselines the schema checks against the template, so the template's own XSD errors don't read as yours |
| `scripts/soffice.py --headless --convert-to pdf deck.pptx` | LibreOffice wrapper — bare `soffice` hangs in this sandbox |

## Creating with pptxgenjs — gotchas

`pptxgenjs` is preinstalled — do not run `npm install` first; write the script and `require('pptxgenjs')` directly. Only if that require fails: `npm install pptxgenjs`. The model knows the API; these are the footguns:

- **Set `pres.layout` before adding slides.** The default canvas is `LAYOUT_16x9` = **10" × 5.625"**, not 13.3" wide. Coordinates past the edge are written, not clamped — the shape just isn't on the slide. (`LAYOUT_WIDE` is 13.3" × 7.5".)
- **Hex colors: never `#`, never 8 digits.** `color: "FF0000"`. Both `"#FF0000"` and alpha baked into the hex (`"00000020"`) **corrupt the file**. For translucency: `transparency: 0-100` on fills and images, `opacity: 0.0-1.0` on shadows — each is silently ignored on the other.
- **pptxgenjs mutates option objects in place** (converts values to EMU on first use). Never share one `shadow`/options object across two `add*` calls — build a fresh object each time.
- **Shadow `offset` must be ≥ 0** — a negative offset corrupts the file. To cast a shadow upward, use `angle: 270` with a positive offset.
- **`letterSpacing` is silently ignored** — the real option is `charSpacing`.
- **Lists:** `bullet: true` on each item, never a literal `•` (renders double bullets). Set `breakLine: true` on every array item except the last. Space bulleted paragraphs with `paraSpaceAfter`, not `lineSpacing` (huge gaps).
- **One `new pptxgen()` per output file** — never reuse an instance.
- **`rectRadius` only works on `ROUNDED_RECTANGLE`**, not `RECTANGLE`.
- **Gradient fills aren't supported** — use a gradient image as the background instead.
- **Text boxes have built-in internal padding** — set `margin: 0` whenever text must align with a shape, line, or icon at the same x.
- **Speaker notes go in `slide.addNotes("...")`** (plain text, once per slide), never in a text box on the slide.
- **Keep charts native.** Use `addChart()` for everything PowerPoint can chart (pass an array of `{type, data, options}` for combos). For PowerPoint-native features the library doesn't expose (trendlines, error bars), compute the extra series yourself or post-process the generated OOXML — do not fall back to a rendered image. Only chart types PowerPoint has no native form for (Sankey, network, chord) go in as images.
- **Default charts render bare** — no title, no data labels, dated palette. Set `showTitle` + `title`, `showValue: true` + `dataLabelPosition`, `chartColors: [...]` from your palette, and quiet the frame (`catAxisLabelColor`/`valAxisLabelColor`, `valGridLine: { color, size }`, `catGridLine: { style: "none" }`, `showLegend: false` for a single series).
- **On a stacked bar or column chart, `dataLabelPosition` must be `ctr`, `inEnd`, or `inBase`.** `outEnd` **corrupts the file**.
- **A combo series using `secondaryValAxis`/`secondaryCatAxis` needs both `valAxes` and `catAxes` on the chart options, two entries each.** Without them pptxgenjs writes axis *ids* it never declares, and PowerPoint **discards that chart** and reports the file as corrupt. Supplying only `valAxes` is not enough.
- **After `writeFile()`, run `python scripts/validate.py deck.pptx`.** It reports the two chart faults above and the slide-XML defects PowerPoint refuses, and names the fix for each. Fix them in your generator, not by hand-editing the packed XML.
- **Never reorder the children of `<p:presentation>`.** pptxgenjs writes `<p:notesMasterIdLst>` right after `<p:sldIdLst>` and points both masters at one theme part. PowerPoint reads that happily — move the element and the same deck becomes unopenable.
- **Icons:** render `react-icons` to SVG (`ReactDOMServer.renderToStaticMarkup`), rasterize with `sharp` at ≥256px, and insert via `addImage({ data: "image/png;base64," + buf.toString("base64") })` — the `image/png;base64,` prefix is required (`react-icons`, `react`, `react-dom`, and `sharp` are preinstalled — `npm install react-icons react react-dom sharp` only if a require fails).

## Editing existing decks and templates

Pick layouts first: `python scripts/thumbnail.py template.pptx template-thumbs` writes a labeled grid of every slide and prints the file(s) it created — `template-thumbs.jpg`, split into `template-thumbs-N.jpg` past 12 slides. **Always pass that second argument, named after the deck.** It defaults to `thumbnails`, so two decks thumbnailed in one directory silently overwrite each other's grids — the first deck's are simply gone (template analysis only — visual QA needs the full-resolution renders from [Converting to Images](#converting-to-images); it only accepts `.pptx`, so copy a `.potx` to a `.pptx` name first). Use it with `markitdown` to map each content section onto a template slide, and vary the layouts — don't put every section on the same title-and-bullets slide.

```bash
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate a slide (or slideLayoutN.xml); prints the new slide's path
# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml
python scripts/clean.py unpacked/                                     # after deletions: removes orphaned slides, media, rels
# edit slide content in ppt/slides/slideN.xml
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # zip from INSIDE the dir; rm first or deleted parts survive
python scripts/validate.py out.pptx --original deck.pptx
```

- **Do all structural work — add, delete, reorder — before editing any slide's content.** `add_slide.py` copies a slide file verbatim, so duplicating after you edit clones the edited content; and `clean.py` deletes any slide missing from `<p:sldIdLst>`, including one you just wrote.
- **Never copy a slide file by hand** — `add_slide.py` does every registration a new slide needs and reports what it made (`Created ppt/slides/slide17.xml from slide2.xml`). It also works directly on a file: `add_slide.py deck.pptx slide2.xml -o out.pptx` — **pass `-o`, or it rewrites the input deck in place.** A duplicated slide still *references* its source's chart/SmartArt/embedded-object parts rather than cloning them, so editing one slide's chart changes the other's.
- **If you use `python-pptx`**, three things it won't do: duplicate a slide (its only entry point is `add_slide(layout)`), preserve formatting through `text_frame.text = "..."` (that collapses the paragraph to a single unstyled run — assign `run.text` instead), or read the SVG/EMF most template art uses (`add_picture` raises `UnidentifiedImageError`).
- Legacy `.ppt` must be converted first: `python scripts/soffice.py --headless --convert-to pptx file.ppt`. `.potx` templates unpack and pack identically — keep the `.potx` extension on the output.
- To reuse a template icon or image, duplicate a slide or layout that already contains it.

When filling in a template:

- If you script an XML transform, parse with `defusedxml.minidom` — round-tripping OOXML through `xml.etree.ElementTree` rewrites namespace prefixes and corrupts the deck.
- **Template slots ≠ source items.** If the template shows 4 team members and you have 3, delete the 4th member's entire group (image + text boxes), not just its text — then check for orphaned visuals in QA.
- One `<a:p>` per list item — never concatenate items into a single paragraph. Copy the sibling `<a:pPr>` to preserve spacing, and put `b="1"` on the `<a:rPr>` of titles, section headers, and inline labels (`Status:`, `Owner:`).
- Let bullets inherit from the layout; only add `<a:buChar>`, `<a:buAutoNum>` (numbered), or `<a:buNone>` to override — never a literal `•` in the text.
- Text with leading or trailing spaces needs `xml:space="preserve"` on its `<a:t>`.

## Design Ideas

**Don't create boring slides.** Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.

### Before Starting

- **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
- **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
- **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles. Carry it across every slide. **Do not use a color bar or accent stripe as your motif** (see Avoid list).

### Color Palettes

Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:

| Theme | Primary | Secondary | Accent |
|-------|---------|-----------|--------|
| **Midnight Executive** | `1E2761` (navy) | `CADCFC` (ice blue) | `FFFFFF` (white) |
| **Forest & Moss** | `2C5F2D` (forest) | `97BC62` (moss) | `F5F5F5` (cream) |
| **Coral Energy** | `F96167` (coral) | `F9E795` (gold) | `2F3C7E` (navy) |
| **Warm Terracotta** | `B85042` (terracotta) | `E7E8D1` (sand) | `A7BEAE` (sage) |
| **Ocean Gradient** | `065A82` (deep blue) | `1C7293` (teal) | `21295C` (midnight) |
| **Charcoal Minimal** | `36454F` (charcoal) | `F2F2F2` (off-white) | `212121` (black) |
| **Teal Trust** | `028090` (teal) | `00A896` (seafoam) | `02C39A` (mint) |
| **Berry & Cream** | `6D2E46` (berry) | `A26769` (dusty rose) | `ECE2D0` (cream) |
| **Sage Calm** | `84B59F` (sage) | `69A297` (eucalyptus) | `50808E` (slate) |
| **Cherry Bold** | `990011` (cherry) | `FCF6F5` (off-white) | `2F3C7E` (navy) |

### For Each Slide

**Every slide needs a visual element** — image, chart, icon, or shape. Text-only slides are forgettable.

**Layout options:**
- Two-column (text left, illustration on right)
- Icon + text rows (icon in colored circle, bold header, description below)
- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
- Half-bleed image (full left or right side) with content overlay

**Data display:**
- Large stat callouts (big numbers 60-72pt with small labels below)
- Comparison columns (before/after, pros/cons, side-by-side options)
- Timeline or process flow (numbered steps, arrows)

**Visual polish:**
- Icons in small colored circles next to section headers
- Italic accent text for key stats or taglines

### Typography

**Font names you write into the .pptx are rendered by the user's PowerPoint, not by this environment.** Your visual QA renders via LibreOffice, which substitutes fonts it doesn't have — and for some fonts the substitute has different widths, so your QA preview can show text overflow (or fit) that the real deck won't have. To keep your QA trustworthy:

- **Safe fonts** (render true-to-width in QA *and* ship with Office): **Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook**. Use these for body text and anything where fit matters.
- **Headers with personality at zero QA risk**: pair a safe-list serif header (Cambria, Bookman Old Style, Century Schoolbook) with a safe-list sans body (Calibri or Arial). You get visual contrast without giving up reliable overflow checks.
- **If the user asks for a font outside the safe list** (e.g. Georgia or Trebuchet MS): use it where the user asked, but size those containers with extra slack (~10%) and don't trust QA text-fit on those elements — the preview of that font is approximate. If the user hasn't specified, prefer safe-list fonts for body text.
- **QA-unreliable fonts** (substitute has different widths — overflow checks can be wrong): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. Calibri Light substitution varies by environment; treat as QA-unreliable. Fine for titles/accents with slack; don't trust QA text-fit on these.
- **Never default to Aptos** — Office's post-2023 default has no metric-compatible substitute here *and* is missing from older Office installs, so it's unreliable on both ends.

| Element | Size |
|---------|------|
| Slide title | 36-44pt bold |
| Section header | 20-24pt bold |
| Body text | 14-16pt |
| Captions | 10-12pt muted |

### Spacing

- 0.5" minimum margins
- 0.3-0.5" between content blocks
- Leave breathing room—don't fill every inch

### Avoid (Common Mistakes)

- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
- **Don't center body text** — left-align paragraphs and lists; center only titles
- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
- **Don't default to blue** — pick colors that reflect the specific topic
- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
- **Don't use low-contrast elements** — icons AND text need strong contrast against the background; avoid light text on light backgrounds or dark text on dark backgrounds
- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
- **NEVER add decorative color bars or accent stripes** — this includes: header/footer bars spanning the slide width, vertical sidebar stripes down one edge of the slide, thin accent stripes along one edge of a card or content block, and "single-side borders" on rectangles. These read as AI-generated filler. If you want to set a card apart, use a subtle background tint, a drop shadow, or an icon — not an edge stripe.
- **Don't default to cream/beige backgrounds** — when no background is specified, use white (`FFFFFF`) or the user's brand palette; avoid warm-neutral defaults like `F5F5DC`, `FAF0E6`, `FAEBD7`, `FFF8E1`
- **Don't ship text that overflows its shape** — if text doesn't fit, reduce font size, split across slides, or enlarge the container; never leave content cut off or spilling past bounds

## QA (Required)

Your first render usually has a few real issues — overlaps, overflow, misalignment. Find and fix those, re-render only the slides you changed, and stop.

### Content QA

```bash
markitdown output.pptx
```

Check for missing content, typos, wrong order.

**When using templates, check for leftover placeholder text:**

```bash
markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"
```

If grep returns results, fix them before declaring success.

### File QA (required)

```bash
python scripts/validate.py output.pptx                      # built from scratch
python scripts/validate.py output.pptx --original src.pptx  # built from a template
```

**If the deck came from a template, always pass `--original`.** A template may itself
contain parts the XSD rejects, so a bare run can report failures you never caused — and
a genuine regression can hide among them. `--original` baselines
the schema and slide checks against the template, suppressing errors it already had.
The structural checks — relationships, content types, charts — ignore `--original` and
report template-inherited problems either way, so read those on their own merits.

pptxgenjs emits chart XML PowerPoint refuses to open, and every other tool
accepts: python-pptx opens those decks, LibreOffice renders them, the XSD
passes them. Every failure names its fix. Fix it in the generator and rebuild.

### Visual QA

Convert the slides to images (see [Converting to Images](#converting-to-images)) and inspect every one. After staring at the generating code you tend to see what you expect rather than what rendered, so look at the images fresh (a subagent works well for this if you have one). User-visible defects to look for:

- **Text overflow or text cut off at a box or slide boundary — check this first.** It is the most common defect and always user-visible. (For a font the previewer renders unreliably per Typography, the preview is approximate: trust the ~10% slack you left, not its apparent fit.)
- Overlapping elements (text through shapes, lines through words, stacked elements)
- Source citations or footers colliding with content above
- Elements too close (< 0.3" gaps) or cards/sections nearly touching
- Uneven gaps (large empty area in one place, cramped in another)
- Insufficient margin from slide edges (< 0.5")
- Columns or similar elements not aligned consistently
- Low-contrast text (e.g., light gray text on cream-colored background)
- Template decoration mispositioned after text replacement — e.g., a title underline positioned for one line, but the replaced title wrapped to two
- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
- Text boxes too narrow causing excessive wrapping
- Leftover placeholder content

## Converting to Images

Convert presentations to individual slide images for visual inspection:

```bash
python scripts/soffice.py --headless --convert-to pdf output.pptx
rm -f slide-*.jpg
pdftoppm -jpeg -r 150 output.pdf slide
ls -1 "$PWD"/slide-*.jpg
```

**Pass the absolute paths printed above directly to the view tool.** The `rm` clears stale images from prior runs. `pdftoppm` zero-pads based on page count: `slide-1.jpg` for decks under 10 pages, `slide-01.jpg` for 10-99, `slide-001.jpg` for 100+.

**After fixes, rerun all four commands above** — the PDF must be regenerated from the edited `.pptx` before `pdftoppm` can reflect your changes.

## Dependencies

`pptxgenjs` (npm, preinstalled — install only if `require('pptxgenjs')` fails) · `markitdown[pptx]`, `Pillow`, `defusedxml`, `lxml` (pip — text dump, thumbnail, clean, validate) · LibreOffice (`soffice`, auto-configured for sandboxed environments via `scripts/soffice.py`) · `pdftoppm` (Poppler)
```

#### pdf

- 来源: 内置/市场
- 说明: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\cb_teams_marketplace\document-skills\1.0.0\skills\pdf\SKILL.md`
- 附带文件: `LICENSE.txt`, `build.sh`, `forms.md`, `reference.md`, `scripts/check_bounding_boxes.py`, `scripts/check_fillable_fields.py`, `scripts/convert_pdf_to_images.py`, `scripts/create_validation_image.py`, `scripts/extract_form_field_info.py`, `scripts/extract_form_structure.py`, `scripts/fill_fillable_fields.py`, `scripts/fill_pdf_form_with_annotations.py`

```markdown
# PDF Processing Guide

## Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md. If you need to fill out a PDF form, read FORMS.md and follow its instructions.

## Quick Start

```python
from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()
```

## Python Libraries

### pypdf - Basic Operations

#### Merge PDFs
```python
from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)
```

#### Split PDF
```python
reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)
```

#### Extract Metadata
```python
reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")
```

#### Rotate Pages
```python
reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)
```

### pdfplumber - Text and Table Extraction

#### Extract Text with Layout
```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
```

#### Extract Tables
```python
with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)
```

#### Advanced Table Extraction
```python
import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # Check if table is not empty
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# Combine all tables
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)
```

### reportlab - Create PDFs

#### Basic PDF Creation
```python
from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("hello.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()
```

#### Create PDF with Multiple Pages
```python
from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)
```

#### Subscripts and Superscripts

**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉, ⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes.

Instead, use ReportLab's XML markup tags in Paragraph objects:
```python
from reportlab.platypus import Paragraph
from reportlab.lib.styles import getSampleStyleSheet

styles = getSampleStyleSheet()

# Subscripts: use <sub> tag
chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])

# Superscripts: use <super> tag
squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])
```

For canvas-drawn text (not Paragraph objects), manually adjust font the size and position rather than using Unicode subscripts/superscripts.

## Command-Line Tools

### pdftotext (poppler-utils)
```bash
# Extract text
pdftotext input.pdf output.txt

# Extract text preserving layout
pdftotext -layout input.pdf output.txt

# Extract specific pages
pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
```

### qpdf
```bash
# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Split pages
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf

# Rotate pages
qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees

# Remove password
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
```

### pdftk (if available)
```bash
# Merge
pdftk file1.pdf file2.pdf cat output merged.pdf

# Split
pdftk input.pdf burst

# Rotate
pdftk input.pdf rotate 1east output rotated.pdf
```

## Common Tasks

### Extract Text from Scanned PDFs
```python
# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# Convert PDF to images
images = convert_from_path('scanned.pdf')

# OCR each page
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)
```

### Add Watermark
```python
from pypdf import PdfReader, PdfWriter

# Create watermark (or load existing)
watermark = PdfReader("watermark.pdf").pages[0]

# Apply to all pages
reader = PdfReader("document.pdf")
writer = PdfWriter()

for page in reader.pages:
    page.merge_page(watermark)
    writer.add_page(page)

with open("watermarked.pdf", "wb") as output:
    writer.write(output)
```

### Extract Images
```bash
# Using pdfimages (poppler-utils)
pdfimages -j input.pdf output_prefix

# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
```

### Password Protection
```python
from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()

for page in reader.pages:
    writer.add_page(page)

# Add password
writer.encrypt("userpassword", "ownerpassword")

with open("encrypted.pdf", "wb") as output:
    writer.write(output)
```

## Quick Reference

| Task | Best Tool | Command/Code |
|------|-----------|--------------|
| Merge PDFs | pypdf | `writer.add_page(page)` |
| Split PDFs | pypdf | One page per file |
| Extract text | pdfplumber | `page.extract_text()` |
| Extract tables | pdfplumber | `page.extract_tables()` |
| Create PDFs | reportlab | Canvas or Platypus |
| Command line merge | qpdf | `qpdf --empty --pages ...` |
| OCR scanned PDFs | pytesseract | Convert to image first |
| Fill PDF forms | pdf-lib or pypdf (see FORMS.md) | See FORMS.md |

## Next Steps

- For advanced pypdfium2 usage, see REFERENCE.md
- For JavaScript libraries (pdf-lib), see REFERENCE.md
- If you need to fill out a PDF form, follow the instructions in FORMS.md
- For troubleshooting guides, see REFERENCE.md
```

#### pdfkit-py

- 来源: 内置/市场
- 说明: Pure-Python PDF toolkit with 50 commands covering reading, editing, conversion, forms, encryption, OCR, and IR. Trigger on: PDF 阅读, 编辑, 转换, 合并, 拆分, 加密, 签名, OCR, 表单, 水印, 书签, 压缩, 裁剪, 旋转, pdfkit.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\cb_teams_marketplace\document-skills\1.0.0\skills\pdfkit-py\SKILL.md`
- 附带文件: `scripts/pdfkit.py`, `scripts/pdfkit/__init__.py`, `scripts/pdfkit/__main__.py`, `scripts/pdfkit/base.py`, `scripts/pdfkit/cli.py`, `scripts/pdfkit/commands/__init__.py`, `scripts/pdfkit/commands/add_page_numbers.py`, `scripts/pdfkit/commands/ai_edit.py`, `scripts/pdfkit/commands/bookmarks.py`, `scripts/pdfkit/commands/chat_pdf.py`, `scripts/pdfkit/commands/chunk_pdf.py`, `scripts/pdfkit/commands/compress.py`

```markdown
# pdfkit — AI 原生 PDF 处理工具

你是 pdfkit 的使用专家。用户描述 PDF 处理需求时，你负责选择正确的命令、参数并执行。

## ⚠️ 环境初始化（看到本段请立即执行）

**立即运行以下命令完成环境初始化，不要跳过，不要先检查。**

根据操作系统选择：

- **macOS / Linux**：
  ```bash
  bash ./scripts/setup.sh
  ```
- **Windows**（PowerShell）：
  ```powershell
  cmd /c ".\scripts\setup.bat"
  ```

脚本会自动检测 Python 3.10+，如果系统未安装会自动下载独立 Python 运行时（无需管理员权限）。
如果失败，向用户报告错误。成功后本段会被自动删除。

<!-- END_SETUP -->

## 定位 CLI

skill 加载时会提供 base directory，CLI 入口在 `./scripts/pdfkit.py`。

根据操作系统，venv 中的 Python 路径不同：

- **macOS / Linux**：`<basedir>/scripts/venv/bin/python3`
- **Windows**：`<basedir>\scripts\venv\Scripts\python.exe`

```bash
# macOS / Linux
/path/to/pdfkit-py/scripts/venv/bin/python3 /path/to/pdfkit-py/scripts/pdfkit.py help

# Windows（PowerShell）—— 必须用 & 调用运算符
& "\path\to\pdfkit-py\scripts\venv\Scripts\python.exe" "\path\to\pdfkit-py\scripts\pdfkit.py" help
```

所有命令用 base directory 拼上对应平台的 venv python 路径和 `scripts/pdfkit.py` 的绝对路径调用。
简写为 `pdfkit.py <command>` 时，实际执行的是上述完整路径。

### Windows PowerShell 注意事项

1. **必须使用 `&`（调用运算符）**：PowerShell 中执行带引号路径的程序时，必须在最前面加 `&`，否则会报 `UnexpectedToken` 错误。
2. **JSON 参数中的引号**：PowerShell 中 JSON 参数**不能用单引号包裹**（单引号在 PowerShell 中是字面字符串，但嵌套双引号仍需转义）。推荐将复杂 JSON 写入文件后用 `--config` 传入。
3. **如果 venv 不存在**：先运行 `.\scripts\setup.bat` 初始化环境。

```powershell
# ✅ 正确的 Windows PowerShell 调用方式
& "C:\Users\xxx\.codebuddy\skills\pdfkit-py\scripts\venv\Scripts\python.exe" "C:\Users\xxx\.codebuddy\skills\pdfkit-py\scripts\pdfkit.py" split --input "D:\docs\file.pdf" --output_dir "D:\docs\output" --mode ranges --ranges "[[0,2]]"

# ❌ 错误：没有 & 运算符
"C:\...\python.exe" "C:\...\pdfkit.py" split ...
```

**参数不确定时**：运行 `pdfkit.py <command> help` 查看完整参数说明。

## 字体

字体由 `font_manager` 模块自动管理，**无需手动指定**：

- 内置 NotoSansSC-Regular 字体，在 setup 时自动从 CDN 下载到 `<basedir>/fonts/`
- 内置字体主要覆盖简体中文 + 常用 CJK，**不要假设它能覆盖所有语言、emoji、特殊符号或罕见字形**
- 内置字体不存在时，自动搜索本机系统字体（macOS: PingFang/STHeiti, Linux: NotoSansCJK/wqy, Windows: 微软雅黑/宋体）
- 搜索结果缓存，不会重复扫描
- 用户通过 `--font_path` 指定时，使用用户指定的

### 字体处理规则

- 如果用户明确提到字体、字形、乱码、缺字、显示不对、英文/其他语言不显示、emoji/符号显示异常等问题，**不要默认继续使用内置字体**
- 这类场景下，优先去本机系统里搜索能覆盖目标文本的字体，再用该字体重试
- 如果自动选择的字体显示仍异常，继续换本机其他候选字体，而不是直接告诉用户“字体不支持”
- 只有在本机确实找不到可用字体时，才向用户说明缺少对应字形覆盖

## 用户输入

$ARGUMENTS

如果用户未提供具体参数，先问：需要处理哪个 PDF 文件？要做什么操作？

## 全局选项

| Flag | 说明 |
|------|------|
| `--config <file.json>` | 从 JSON 文件加载复杂参数（CLI 参数优先级高于 config 文件） |

输出格式统一为 JSON：`{"ok": true, "data": {...}}` / `{"ok": false, "error": "..."}`

**页码从 0 开始**：用户说"第 1 页"→ 参数 `0`。

## 坐标系规范

**所有命令统一使用 PyMuPDF 坐标系**：

- **原点**：页面**左上角** (0, 0)
- **x 轴**：向右增大
- **y 轴**：向下增大
- **左上角**：约 (30, 30)
- **左下角**：约 (30, 页面高度 - 30)
- **右下角**：约 (页面宽度 - 30, 页面高度 - 30)
- **A4 页面尺寸**：宽 595，高 842（单位：点）

> ⚠️ 注意：这与 PDF 原生坐标系（y=0 在底部）**相反**。所有命令内部已自动处理转换，用户只需按上述规范传入坐标。
>
> 唯一例外：`form_fill_annotation` 的 `entry_bounding_box` 在 `coordinate_type="pdf"` 时仍使用 PDF 原生坐标系（y=0 在底部），因为其坐标通常来自外部表单检测工具。

## 可选依赖

核心依赖在 setup 脚本首次运行时已安装。以下依赖**按需安装**——**当命令执行报错提示缺少某个包时，你应该自动用 venv 内的 pip 安装它，然后重试原命令，不要把安装指引丢给用户。**

### Python 可选包

pip 路径：

- **macOS / Linux**：`./scripts/venv/bin/pip install <包名>`
- **Windows**：`.\scripts\venv\Scripts\pip.exe install <包名>`

| 包名 | 涉及命令 | 安装命令 |
|------|---------|---------|
| `camelot-py[cv]` | extract_table（lattice/stream 方法） | `pip install "camelot-py[cv]"` |
| `tabula-py` | extract_table（tabula 方法） | `pip install tabula-py` |
| `pdf2docx` | pdf_to_word（pdf2docx 方法） | `pip install pdf2docx` |
| `pikepdf` | compress（高级压缩优化） | `pip install pikepdf` |
| `pix2tex` | formula_detect（model 方法） | `pip install pix2tex` |

**安装流程**：执行命令 → 报错含 `ModuleNotFoundError` 或 `ImportError` → 用 venv pip 安装对应包 → 重试原命令。

### 系统外部工具

无需预装。**当命令执行报错提示缺少以下工具时，你应该自动执行对应的安装命令，安装完成后重试原命令，不要把安装指引丢给用户，也不要先反问用户要不要安装。**

| 工具 | 用途 | 涉及命令 | macOS 安装 | Windows 安装 | Linux 安装 |
|------|------|---------|-----------|-------------|-----------|
| `gs` | PDF 压缩 | compress | `brew install ghostscript` | `winget install ArtifexSoftware.GhostScript --accept-package-agreements --accept-source-agreements` | `sudo apt install -y ghostscript` |
| `tesseract` | OCR 识别 | smart_edit, edit_scanned, ocr_locate, search_text, extract_text | `brew install tesseract` | `winget install UB-Mannheim.TesseractOCR --accept-package-agreements --accept-source-agreements` | `sudo apt install -y tesseract-ocr` |
| `tesseract-lang` | OCR 中文语言包 | 同上（涉及中文 PDF 时需要） | `brew install tesseract-lang` | 安装 tesseract 时已包含 | `sudo apt install -y tesseract-ocr-chi-sim` |
| `soffice` | 格式转换 | convert, pdf_to_word | `brew install --cask libreoffice` | `winget install TheDocumentFoundation.LibreOffice --accept-package-agreements --accept-source-agreements` | `sudo apt install -y libreoffice` |

**安装流程**：执行命令 → 报错含"未找到 xxx 命令"或"语言包缺失" → 根据当前 OS 执行上表对应安装命令 → 重试原命令。

**OCR 特别规则**：

- 只要用户意图是编辑扫描件、OCR 定位、OCR 搜索、扫描件提取文本，且命令报缺少 `tesseract` 或语言包，就直接安装，不要询问用户是否安装
- 对应命令包括：`smart_edit`（扫描件路径）、`edit_scanned`、`ocr_locate`、`search_text --engine ocr`、`extract_text --ocr_fallback`
- 用户说“修改扫描件”“改图片里的字”“识别扫描 PDF”“OCR 找字”时，默认视为允许安装 OCR 依赖
- 只有安装命令本身失败、缺少管理员权限、或系统包管理器不可用时，才向用户报告阻塞点

---

## 命令详解（50 个命令）

## 阅读与分析 (13)

### page_count — 获取 PDF 页数

```bash
pdfkit.py page_count --input doc.pdf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |

### extract_text — 提取文本

> 💡 **支持自动 OCR 降级**：添加 `--ocr_fallback` 参数后，**纯扫描件页面**（完全无文字层）会自动使用 OCR 提取文字。
> **混合型页面**（有文字层 + 嵌入图片）仅提取文字层文本，图片上的文字**不会**被 OCR 提取。
> 不加 `--ocr_fallback` 时，扫描件页面会返回空并给出提示。

```bash
# 基本用法（仅提取文字层）
pdfkit.py extract_text --input doc.pdf --pages '[0,1]'

# 自动 OCR 降级（推荐：一次调用覆盖所有场景）
pdfkit.py extract_text --input scan.pdf --pages '[0]' --ocr_fallback

# 指定输出格式
pdfkit.py extract_text --input doc.pdf --format html --output /tmp/out.html
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON，如 `[0,1,3]` |
| `--output` | 输出文件路径 |
| `--format` | 输出格式，默认 `text`。可选 `text` / `dict` / `blocks` / `words` / `html` |
| `--ocr_fallback` | 自动 OCR 降级，默认 `False`。仅对纯扫描件页面（无文字层）自动 OCR，混合型页面中图片上的文字不提取（需要 tesseract） |
| `--lang` | OCR 语言，默认 `eng+chi_sim`（仅 `--ocr_fallback` 时生效） |

### to_images — 页面转图片

```bash
pdfkit.py to_images --input doc.pdf --output_dir /tmp/imgs/ --dpi 300
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output_dir` | **必填** 输出目录 |
| `--pages` | 页码列表 JSON |
| `--dpi` | 分辨率，默认 `150` |
| `--format` | 图片格式，默认 `png`。可选 `png` / `jpeg` |

### long_image — 多页拼接长图

```bash
pdfkit.py long_image --input doc.pdf --output /tmp/long.png
pdfkit.py long_image --input doc.pdf --output /tmp/long.png --pages '[0,1,2]' --gap 10
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出图片路径 |
| `--pages` | 页码列表 JSON |
| `--dpi` | 分辨率，默认 `150` |
| `--gap` | 页间距像素，默认 `0` |

### extract_images — 提取内嵌图片

```bash
pdfkit.py extract_images --input doc.pdf --output_dir /tmp/imgs/
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output_dir` | **必填** 输出目录 |
| `--pages` | 页码列表 JSON |
| `--min_size` | 最小尺寸（像素），默认 `100` |

### extract_table — 提取表格

```bash
pdfkit.py extract_table --input doc.pdf --format markdown
pdfkit.py extract_table --input doc.pdf --pages '[0]' --format csv --output /tmp/table.csv
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |
| `--format` | 输出格式，默认 `json`。可选 `csv` / `json` / `markdown` |
| `--output` | 输出文件路径 |
| `--method` | 提取方法，默认 `auto`。可选 `auto` / `lattice` / `stream` |
| `--header` | 是否将第一行作为表头，默认 `False`（原样输出所有行）。有表头行的表格传 `--header` |

### layout_analyze
```bash
pdfkit.py layout_analyze --input doc.pdf --pages '[0]' --detail full
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |
| `--detail` | 详细程度，默认 `basic`。可选 `basic` / `full` |

### ocr_locate — OCR 定位文字

> 需要 `tesseract`

```bash
pdfkit.py ocr_locate --input scan.pdf --page 0 --text "合同编号"
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--page` | 页码，默认 `0` |
| `--text` | 要定位的文字 |
| `--lang` | OCR 语言，默认 `eng+chi_sim` |

### chat_pdf — PDF 问答上下文提取

```bash
pdfkit.py chat_pdf --input doc.pdf --question "主要结论是什么"
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--question` | 问题 |
| `--pages` | 页码列表 JSON |
| `--max_context_chars` | 最大上下文字数，默认 `8000` |

### chunk_pdf — 文档分块

```bash
pdfkit.py chunk_pdf --input doc.pdf --strategy paragraph
pdfkit.py chunk_pdf --input doc.pdf --strategy fixed --chunk_size 500 --overlap 100
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--strategy` | 分块策略，默认 `paragraph`。可选 `page` / `paragraph` / `fixed` / `semantic` |
| `--chunk_size` | 块大小，默认 `1000` |
| `--overlap` | 重叠字数，默认 `200` |
| `--pages` | 页码列表 JSON |

### formula_detect — 数学公式检测

```bash
pdfkit.py formula_detect --input paper.pdf --pages '[0,1]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |
| `--method` | 检测方法，默认 `heuristic`。可选 `heuristic` / `model` |

### reading_order — 阅读顺序检测

```bash
pdfkit.py reading_order --input doc.pdf --pages '[0]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |

### schema_extract — Schema 结构化提取

```bash
pdfkit.py schema_extract --input invoice.pdf \
  --schema '{"invoice_no":"string","date":"string","items":[{"name":"string","amount":"number"}]}'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--schema` | **必填** 目标结构 JSON |
| `--pages` | 页码列表 JSON |

---

## 编辑与修改 (10)

### smart_edit — 智能编辑（自动判断文字层/扫描件）

```bash
# 替换文本（所有页）
pdfkit.py smart_edit --input doc.pdf --output out.pdf \
  --edits '[{"type":"replace_text","find":"旧文本","replace":"新文本","page":-1}]'

# 添加文本
pdfkit.py smart_edit --input doc.pdf --output out.pdf \
  --edits '[{"type":"add_text","text":"新文本","x":100,"y":200,"page":0}]'

# 预览模式
pdfkit.py smart_edit --input doc.pdf --output out.pdf --dry_run \
  --edits '[{"type":"replace_text","find":"旧","replace":"新"}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--edits` | **必填** 编辑操作列表 JSON |
| `--dry_run` | 预览模式，不实际修改，默认 `False` |

edits 支持的操作类型：

| type | 字段 |
|------|------|
| `replace_text` | `find`, `replace`, `page`（-1=所有页），`color`（可选，[r,g,b] 0-1 范围） |
| `add_text` | `text`, `x`, `y`（坐标原点在页面**左上角**，y 向下增大；左上角≈y:30，左下角≈y:页高-30）, `page`, `font_size`（默认12）, `color`（可选，[r,g,b] 0-1 范围，如红色 [1,0,0]） |
| `delete_text` | `find`, `page` |
| `replace_image` | `page`, `image_index`, `new_image`（图片路径） |

### pymupdf_edit — 文字层文本编辑

```bash
pdfkit.py pymupdf_edit --input doc.pdf --output out.pdf \
  --edits '[{"find":"旧","replace":"新","page":0}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--edits` | **必填** 编辑操作列表 JSON |

### edit_scanned — 扫描件编辑

> 需要 `tesseract`

```bash
pdfkit.py edit_scanned --input scan.pdf --output out.pdf \
  --page 0 --find "旧文本" --replace "新文本" --font fonts/DroidSansFallback.ttf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--page` | 页码，默认 `0` |
| `--find` | **必填** 查找文本 |
| `--replace` | **必填** 替换文本 |
| `--font` | 字体路径（中文需指定） |
| `--lang` | OCR 语言，默认 `eng+chi_sim` |

### search_text — 文本搜索

```bash
pdfkit.py search_text --input doc.pdf --find "关键词"
pdfkit.py search_text --input doc.pdf --find "关键词" --page 0 --engine fuzzy
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--find` | **必填** 搜索文本 |
| `--page` | 页码，默认 `-1`（全部页） |
| `--engine` | 搜索引擎，默认 `auto`。可选 `pymupdf` / `pdfplumber` / `fuzzy` / `ocr` / `auto` |

### overlay_text — 文本覆盖

```bash
pdfkit.py overlay_text --input doc.pdf --output out.pdf \
  --overlays '[{"page":0,"bbox":[100,30,300,60],"text":"覆盖文本","font_size":12}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--overlays` | **必填** 覆盖配置列表 JSON `[{page, bbox, text, font_size, color, bg_color}]`。bbox 格式 `[x0,y0,x1,y1]` 使用统一坐标系（左上角原点，y↓） |

### pdf_create — 创建 PDF

```bash
pdfkit.py pdf_create --output report.pdf \
  --elements '[{"type":"heading","text":"标题"},{"type":"paragraph","text":"正文"}]' \
  --font_path fonts/DroidSansFallback.ttf

pdfkit.py pdf_create --output report.pdf \
  --elements '[{"type":"heading","text":"报告"},{"type":"paragraph","text":"内容"}]' \
  --page_size A4 --watermark '{"text":"草稿"}'
```

| Flag | 说明 |
|------|------|
| `--output` | **必填** 输出 PDF 路径 |
| `--elements` | **必填** 元素列表 JSON `[{type, text, ...}]` |
| `--page_size` | 页面大小，默认 `A4`。可选 `A4` / `A3` / `letter` / `legal` |
| `--orientation` | 方向，默认 `portrait` |
| `--font_path` | 字体路径（中文需指定） |
| `--margins` | 边距 JSON |
| `--header` | 页眉 JSON |
| `--footer` | 页脚 JSON |
| `--watermark` | 水印 JSON |
| `--title` | 文档标题 |
| `--author` | 作者 |

### watermark — 添加水印

```bash
# 自动搜索字体（推荐）
pdfkit.py watermark --input doc.pdf --output out.pdf --text "机密"

# 指定字体
pdfkit.py watermark --input doc.pdf --output out.pdf \
  --text "机密" --font_path /path/to/font.ttf

# 密集模式 + 自定义样式
pdfkit.py watermark --input doc.pdf --output out.pdf \
  --text "CONFIDENTIAL" --mode dense --opacity 0.1 --angle 30
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--text` | **必填** 水印文本 |
| `--font_path` | 字体路径（不指定则自动搜索） |
| `--mode` | 水印模式，默认 `sparse`。可选 `sparse` / `dense` |
| `--font_color` | 字体颜色，默认 `#CCCCCC` |
| `--angle` | 旋转角度，默认 `45` |
| `--opacity` | 透明度，默认 `0.15` |
| `--font_size` | 字号，默认 `50` |
| `--x_gap` | dense 模式水平间距，默认 `200` |
| `--y_gap` | dense 模式垂直间距，默认 `150` |

### add_page_numbers — 添加页码

```bash
pdfkit.py add_page_numbers --input doc.pdf --output out.pdf
pdfkit.py add_page_numbers --input doc.pdf --output out.pdf \
  --position bottom_right --format "第 {page} 页 / 共 {total} 页" \
  --font_path fonts/DroidSansFallback.ttf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--position` | 位置，默认 `bottom_center`。可选 `bottom_center` / `bottom_left` / `bottom_right` / `top_center` / `top_left` / `top_right` |
| `--format` | 格式字符串，默认 `"{page} / {total}"` |
| `--start_number` | 起始页码，默认 `1` |
| `--font_size` | 字号，默认 `10` |
| `--font_color` | 颜色 JSON，默认 `[0,0,0]` |
| `--margin` | 边距（点），默认 `36` |
| `--pages` | 页码列表 JSON |
| `--font_path` | 字体路径（中文页码需指定） |

### remove_headers_footers — 清除页眉页脚

```bash
# 仅识别
pdfkit.py remove_headers_footers --input doc.pdf --extract_only

# 清除
pdfkit.py remove_headers_footers --input doc.pdf --output clean.pdf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | 清除模式下必填，输出路径 |
| `--pages` | 页码列表 JSON |
| `--header_ratio` | 页眉区域比例，默认 `0.08` |
| `--footer_ratio` | 页脚区域比例，默认 `0.08` |
| `--extract_only` | 仅识别不清除，默认 `False` |

---

## 组织与变换 (10)

### compress — 压缩 PDF

```bash
pdfkit.py compress --input doc.pdf --output out.pdf --quality ebook
pdfkit.py compress --input doc.pdf --output out.pdf --target_size_mb 5
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--quality` | 压缩质量，默认 `ebook`。可选 `screen` / `ebook` / `printer` / `prepress` |
| `--target_size_mb` | 目标大小（MB） |

### split — 拆分 PDF

```bash
pdfkit.py split --input doc.pdf --output_dir /tmp/split/
pdfkit.py split --input doc.pdf --output_dir /tmp/split/ --mode ranges --ranges '[[0,2],[3,5]]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output_dir` | **必填** 输出目录 |
| `--mode` | 拆分模式，默认 `each`。可选 `each`（每页一个） / `ranges`（按范围） |
| `--ranges` | 范围 JSON `[[0,2],[3,5]]`，`mode=ranges` 时使用 |

### merge — 合并 PDF

```bash
pdfkit.py merge --inputs '["a.pdf","b.pdf"]' --output merged.pdf
```

| Flag | 说明 |
|------|------|
| `--inputs` | **必填** 输入文件列表 JSON |
| `--output` | **必填** 输出 PDF 路径 |

### rotate — 旋转页面

```bash
pdfkit.py rotate --input doc.pdf --output out.pdf --angle 90
pdfkit.py rotate --input doc.pdf --output out.pdf --angle 180 --pages '[0,2]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--angle` | 旋转角度，默认 `90`。可选 `90` / `180` / `270` / `-90` / `-180` / `-270` |
| `--pages` | 页码列表 JSON |

### crop — 裁剪页面

```bash
# 裁剪第一页，保留左上角 400x500 区域
pdfkit.py crop --input doc.pdf --output out.pdf --left 0 --top 0 --right 400 --bottom 500
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--left` | 裁剪区左边界 x，默认 `0` |
| `--top` | 裁剪区上边界 y，默认 `0`（页面顶部） |
| `--right` | 裁剪区右边界 x，默认 `612` |
| `--bottom` | 裁剪区下边界 y，默认 `792`（页面底部） |
| `--pages` | 页码列表 JSON |

坐标使用统一坐标系（左上角原点，y↓）。

### convert — 格式转换

```bash
pdfkit.py convert --input doc.pdf --output doc.docx --to_format docx
pdfkit.py convert --input doc.html --output doc.pdf --to_format pdf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入文件路径 |
| `--output` | **必填** 输出文件路径 |
| `--from_format` | 源格式，默认 `auto`。可选 `auto` / `pdf` / `docx` / `html` / `md` / `images` |
| `--to_format` | 目标格式。可选 `pdf` / `docx` / `html` / `md` / `images` |

### pdf_to_word — PDF 转 Word

```bash
pdfkit.py pdf_to_word --input doc.pdf --output doc.docx
pdfkit.py pdf_to_word --input doc.pdf --output doc.docx --pages '[0,5]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 Word 路径 |
| `--pages` | 页码范围 JSON `[start, end]` |
| `--method` | 转换方法，默认 `auto`。可选 `auto` / `pdf2docx` / `libreoffice` |

### bookmarks — 书签管理

```bash
# 获取书签
pdfkit.py bookmarks --action get --input doc.pdf

# 设置书签
pdfkit.py bookmarks --action set --input doc.pdf --output out.pdf \
  --bookmarks '[{"level":1,"title":"第一章","page":0},{"level":2,"title":"1.1 节","page":2}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--action` | 操作，默认 `get`。可选 `get` / `set` |
| `--output` | `action=set` 时必填，输出路径 |
| `--bookmarks` | 书签列表 JSON `[{"level":1,"title":"...","page":0}]` |
| `--mode` | 设置模式，默认 `replace`。可选 `replace` / `append` |

---

## 安全与表单 (8)

### encrypt — 加密

```bash
pdfkit.py encrypt --input doc.pdf --output out.pdf --user_password "secret"
pdfkit.py encrypt --input doc.pdf --output out.pdf \
  --user_password "read" --owner_password "admin" --allow_print --allow_copy
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--user_password` | **必填** 用户密码 |
| `--owner_password` | 所有者密码 |
| `--allow_print` | 允许打印，默认 `True` |
| `--allow_modify` | 允许修改，默认 `False` |
| `--allow_copy` | 允许复制，默认 `False` |

### decrypt — 解密

```bash
pdfkit.py decrypt --input encrypted.pdf --output out.pdf --password "secret"
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--password` | **必填** 密码 |

### form_detect — 检测表单

```bash
pdfkit.py form_detect --input form.pdf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--extract_structure` | 提取表单结构，默认 `True` |

### form_fill — 填写表单

```bash
pdfkit.py form_fill --input form.pdf --output filled.pdf \
  --fields '[{"field_id":"name","value":"张三"},{"field_id":"date","value":"2026-01-01"}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--fields` | **必填** 字段值列表 JSON `[{"field_id":"...","value":"..."}]` |

### form_fill_annotation — 注释方式填表

```bash
pdfkit.py form_fill_annotation --input form.pdf --output filled.pdf \
  --form_fields '[{"page":0,"x":100,"y":200,"text":"张三","font_size":12}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--coordinate_type` | 坐标类型，默认 `pdf`。可选 `pdf` / `image` |
| `--pages` | 页码列表 JSON |
| `--form_fields` | **必填** 填写字段列表 JSON |

### flatten — 扁平化

```bash
pdfkit.py flatten --input form.pdf --output flat.pdf
pdfkit.py flatten --input doc.pdf --output flat.pdf --flatten_annotations --pages '[0,1]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--flatten_forms` | 扁平化表单，默认 `True` |
| `--flatten_annotations` | 扁平化注释，默认 `True` |
| `--pages` | 页码列表 JSON |

### redact — 涂黑脱敏

```bash
# 按文本涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"text","text":"身份证号","page":-1}]'

# 按区域涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"area","rect":[100,200,300,230],"page":0}]'

# 按正则涂黑
pdfkit.py redact --input doc.pdf --output out.pdf \
  --redactions '[{"type":"regex","pattern":"\\d{18}","page":-1}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--redactions` | **必填** 涂黑规则列表 JSON |
| `--fill_color` | 填充颜色 JSON，默认 `[0,0,0]`（黑色） |

redactions 支持的类型：

| type | 字段 |
|------|------|
| `text` | `text`, `page`（-1=所有页） |
| `area` | `rect` `[left, top, right, bottom]`, `page` |
| `regex` | `pattern`, `page` |

### sign_pdf — 数字签名

```bash
pdfkit.py sign_pdf --input doc.pdf --output signed.pdf \
  --signature '{"text":"张三","position":"bottom_right"}'

pdfkit.py sign_pdf --input doc.pdf --output signed.pdf \
  --signature '{"image":"seal.png","position":[400,50],"width":150,"height":60}' \
  --pages '[0]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--signature` | **必填** 签名配置 JSON |
| `--pages` | 页码列表 JSON |

signature 字段：

| 字段 | 说明 |
|------|------|
| `image` | 签章图片路径 |
| `text` | 签名文字 |
| `position` | `"bottom_right"` 等预设位置，或 `[x, y]` 坐标 |
| `width` | 宽度，默认 `150` |
| `height` | 高度，默认 `60` |
| `font_size` | 字号，默认 `10` |
| `opacity` | 透明度，默认 `1.0` |

---

## IR 中间表示 (5)

### ir_export — 导出 PDF 结构为 JSON

```bash
pdfkit.py ir_export --input doc.pdf --output structure.json
pdfkit.py ir_export --input doc.pdf --output structure.json --include_images --include_fonts
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** JSON 输出路径 |
| `--pages` | 页码列表 JSON |
| `--include_images` | 包含图片数据，默认 `False` |
| `--include_fonts` | 包含字体信息，默认 `False` |

### ir_import — 从 JSON 重建 PDF

```bash
pdfkit.py ir_import --input structure.json --output rebuilt.pdf
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** IR JSON 路径 |
| `--output` | **必填** 输出 PDF 路径 |

### ir_inspect — 结构摘要

```bash
pdfkit.py ir_inspect --input doc.pdf
pdfkit.py ir_inspect --input doc.pdf --pages '[0]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |

### ir_modify — 精准修改

```bash
pdfkit.py ir_modify --input doc.pdf --output out.pdf \
  --operations '[{"type":"replace_text","page":0,"find":"旧文本","replace":"新文本"}]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--output` | **必填** 输出 PDF 路径 |
| `--operations` | **必填** 操作列表 JSON |

operations 支持的类型：

| type | 字段 |
|------|------|
| `replace_text` | `page`, `find`, `replace` |
| `replace_image` | `page`, `image_index`, `new_image`（图片路径） |
| `add_annotation` | `page`, `annot_type`（如 `freetext`）, `rect` `[x,y,x2,y2]`, `content` |

### ir_diff — 对比差异

```bash
pdfkit.py ir_diff --left old.pdf --right new.pdf
pdfkit.py ir_diff --left old.pdf --right new.pdf --output diff.json --text_only
```

| Flag | 说明 |
|------|------|
| `--left` | **必填** 左侧 PDF 路径 |
| `--right` | **必填** 右侧 PDF 路径 |
| `--output` | 输出路径 |
| `--text_only` | 仅对比文本，默认 `False` |

---

## 元工具 (4)

### detect_type — 检测页面类型

```bash
pdfkit.py detect_type --input doc.pdf
pdfkit.py detect_type --input doc.pdf --pages '[0,1]'
```

| Flag | 说明 |
|------|------|
| `--input` | **必填** 输入 PDF 路径 |
| `--pages` | 页码列表 JSON |

### exec_python — 沙箱执行 Python

> 最后手段，仅当现有命令无法完成时使用。

```bash
pdfkit.py exec_python --code 'import fitz; doc=fitz.open("doc.pdf"); print(len(doc))'
```

| Flag | 说明 |
|------|------|
| `--code` | **必填** Python 代码 |
| `--timeout` | 超时秒数，默认 `120` |

### layout_engine — 排版引擎

内部使用，一般不直接调用。

---

## 扩展机制（Extension）

当内置的命令无法满足复杂需求时（如多步骤批处理流程、特殊格式转换、业务定制逻辑等），可以通过**扩展脚本**来扩充能力。

### 工作原理

扩展脚本放在 skill basedir 的 `../pdfkit-extension/scripts/` 目录下，与内置命令遵循**完全相同的接口约定**（COMMAND、DESCRIPTION、PARAMS、handler），由 `pdfkit.py` 自动发现和注册。

```
/path/to/skills/                        ← skill basedir 的父目录
├── pdfkit-py/                          ← pdfkit skill 目录（skill basedir）
│   ├── scripts/
│   │   ├── pdfkit.py                   ← 入口（自动扫描扩展）
│   │   └── pdfkit/commands/            ← 内置 50 个命令
│   └── ...
└── pdfkit-extension/                   ← 扩展目录（用户创建，与 pdfkit-py 同级）
    └── scripts/
        ├── batch_watermark.py          ← 扩展脚本 1
        ├── invoice_extract.py          ← 扩展脚本 2
        └── ...
```

### 查看可用扩展

```bash
pdfkit.py extension --help
```

### 使用扩展命令

扩展命令可以像内置命令一样直接调用：

```bash
# 直接调用
pdfkit.py batch_watermark --input_dir /tmp/pdfs --text "机密"

# 通过 extension 子命令调用
pdfkit.py extension batch_watermark --input_dir /tmp/pdfs --text "机密"

# 查看扩展命令帮助
pdfkit.py batch_watermark help
```

### 创建扩展脚本

1. 创建扩展目录：
```bash
mkdir -p <skill basedir>/../pdfkit-extension/scripts
```

2. 复制模板：
```bash
cp <skill basedir>/scripts/pdfkit/extension_template.py \
   <skill basedir>/../pdfkit-extension/scripts/my_script.py
```

3. 编辑脚本，修改 `COMMAND`、`DESCRIPTION`、`PARAMS` 和 `handler` 函数。

### 扩展脚本模板结构

```python
COMMAND = "my_extension"              # 命令名
DESCRIPTION = "我的自定义 PDF 扩展"     # 描述
CATEGORY = "extension"                # 分类
PARAMS = [
    {"name": "input", "type": "str", "required": True, "help": "输入 PDF"},
    {"name": "output", "type": "str", "required": True, "help": "输出 PDF"},
]

def handler(params):
    # 处理逻辑...
    return {"message": "done", "output": params["output"]}
```

### 适用场景

| 场景 | 说明 |
|------|------|
| 批量处理流程 | 如批量加水印、批量压缩、批量转格式 |
| 多步骤组合 | 如先提取 → 处理 → 重新生成的 pipeline |
| 业务定制 | 如发票批量解析、合同模板填充、报告自动生成 |
| 实验性功能 | 在内置命令基础上做定制化调整 |

### 执行策略

遇到复杂 PDF 任务时：

1. **先查看是否有可复用的扩展**：`pdfkit.py extension --help`
2. **有现成扩展** → 直接调用
3. **没有现成扩展但内置命令可组合完成** → 拆解为多个内置命令依次执行
4. **需要新扩展** → 为用户创建扩展脚本到 `../pdfkit-extension/scripts/`

---

## 执行规范

1. **先理解需求**：分析用户描述，确定操作和参数
2. **参数确认**：关键参数缺失时先问用户
3. **不确定参数时**：运行 `pdfkit.py <command> help` 查看完整参数说明
4. **路径处理**：输入用用户路径，输出未指定时给合理默认值（同目录，或 macOS/Linux 用 `/tmp/`、Windows 用 `%TEMP%`）
5. **复杂 JSON 参数**：优先写入文件后用 `--config` 传入
6. **页码从 0 开始**：用户说"第 1 页"→ 参数 `0`
7. **错误处理**：
   - 依赖缺失 → 提示安装
   - 加密 PDF → 提示用户提供密码
   - 扫描件文本为空 → 建议用 `edit_scanned` 或 `ocr_locate`
8. **复合操作**：拆解后依次执行（如「提取第 3-5 页并转图片」= split + to_images）

## 场景速查

| 用户说 | 你执行 |
|--------|--------|
| 多少页 | `page_count` |
| 提取文字 / 读取内容 | `extract_text`（扫描件加 `--ocr_fallback`） |
| 转图片 / 截图 | `to_images` |
| 拼长图 | `long_image` |
| 提取图片 | `extract_images` |
| 提取表格 | `extract_table` |
| 分析布局 | `layout_analyze` |
| OCR / 识别扫描件文字 | `ocr_locate` |
| 问答 / 总结 | `chat_pdf` |
| 分块 / RAG | `chunk_pdf` |
| 公式检测 | `formula_detect` |
| 阅读顺序 | `reading_order` |
| 按格式提取 / 结构化 | `schema_extract` |
| 替换文字 / 编辑 PDF | `smart_edit` |
| 添加文字 / 文字标记 / 盖章文字 | `smart_edit`（`add_text` 类型） |
| 修改扫描件 | `edit_scanned` |
| 搜索文字 | `search_text` |
| 叠加文字 | `overlay_text` |
| 创建 PDF / 生成报告 | `pdf_create` |
| 加水印 | `watermark` |
| 加页码 | `add_page_numbers` |
| 去页眉页脚 | `remove_headers_footers` |
| 压缩 / 缩小体积 | `compress` |
| 拆分 | `split` |
| 合并 | `merge` |
| 旋转 | `rotate` |
| 裁剪 | `crop` |
| 转 Word | `pdf_to_word` |
| 格式转换 | `convert` |
| 书签 / 目录 | `bookmarks` |
| 加密 / 设置密码 | `encrypt` |
| 解密 / 去除密码 | `decrypt` |
| 检测表单 | `form_detect` |
| 填写表单 | `form_fill` |
| 坐标填表 | `form_fill_annotation` |
| 扁平化 | `flatten` |
| 涂黑 / 脱敏 / 隐藏信息 | `redact` |
| 签名 / 盖章 | `sign_pdf` |
| 查看结构 | `ir_inspect` |
| 导出结构 | `ir_export` |
| 从结构重建 | `ir_import` |
| 精准修改 | `ir_modify` |
| 对比两个 PDF | `ir_diff` |
| 检测页面类型 | `detect_type` |
| 自定义脚本 | `exec_python` |
| 复杂/批量任务 | 先 `pdfkit.py extension --help` 查看扩展，无则创建扩展脚本 |
```

#### xlsx

- 来源: 内置/市场
- 说明: Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\marketplaces\codebuddy-plugins-official\plugins\xlsx\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `LICENSE.txt`, `scripts/office/helpers/__init__.py`, `scripts/office/helpers/merge_runs.py`, `scripts/office/helpers/simplify_redlines.py`, `scripts/office/pack.py`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd`, `scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd`

```markdown
# Requirements for Outputs

## All Excel files

### Professional Font
- Use a consistent, professional font (e.g., Arial, Times New Roman) for all deliverables unless otherwise instructed by the user

### Zero Formula Errors
- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

### Preserve Existing Templates (when updating templates)
- Study and EXACTLY match existing format, style, and conventions when modifying files
- Never impose standardized formatting on files with established patterns
- Existing template conventions ALWAYS override these guidelines

## Financial models

### Color Coding Standards
Unless otherwise stated by the user or existing template

#### Industry-Standard Color Conventions
- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
- **Red text (RGB: 255,0,0)**: External links to other files
- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated

### Number Formatting Standards

#### Required Format Rules
- **Years**: Format as text strings (e.g., "2024" not "2,024")
- **Currency**: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
- **Zeros**: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
- **Percentages**: Default to 0.0% format (one decimal)
- **Multiples**: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
- **Negative numbers**: Use parentheses (123) not minus -123

### Formula Construction Rules

#### Assumptions Placement
- Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
- Use cell references instead of hardcoded values in formulas
- Example: Use =B5*(1+$B$6) instead of =B5*1.05

#### Formula Error Prevention
- Verify all cell references are correct
- Check for off-by-one errors in ranges
- Ensure consistent formulas across all projection periods
- Test with edge cases (zero values, negative numbers)
- Verify no unintended circular references

#### Documentation Requirements for Hardcodes
- Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
- Examples:
  - "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
  - "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
  - "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
  - "Source: FactSet, 8/20/2025, Consensus Estimates Screen"

# XLSX creation, editing, and analysis

## Overview

A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.

## Important Requirements

**LibreOffice Required for Formula Recalculation**: You can assume LibreOffice is installed for recalculating formula values using the `scripts/recalc.py` script. The script automatically configures LibreOffice on first run, including in sandboxed environments where Unix sockets are restricted (handled by `scripts/office/soffice.py`)

## Reading and analyzing data

### Data analysis with pandas
For data analysis, visualization, and basic operations, use **pandas** which provides powerful data manipulation capabilities:

```python
import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyze
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)
```

## Excel File Workflows

## CRITICAL: Use Formulas, Not Hardcoded Values

**Always use Excel formulas instead of calculating values in Python and hardcoding them.** This ensures the spreadsheet remains dynamic and updateable.

### ❌ WRONG - Hardcoding Calculated Values
```python
# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5
```

### ✅ CORRECT - Using Excel Formulas
```python
# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'
```

This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.

## Common Workflow
1. **Choose tool**: pandas for data, openpyxl for formulas/formatting
2. **Create/Load**: Create new workbook or load existing file
3. **Modify**: Add/edit data, formulas, and formatting
4. **Save**: Write to file
5. **Recalculate formulas (MANDATORY IF USING FORMULAS)**: Use the scripts/recalc.py script
   ```bash
   python scripts/recalc.py output.xlsx
   ```
6. **Verify and fix any errors**: 
   - The script returns JSON with error details
   - If `status` is `errors_found`, check `error_summary` for specific error types and locations
   - Fix the identified errors and recalculate again
   - Common errors to fix:
     - `#REF!`: Invalid cell references
     - `#DIV/0!`: Division by zero
     - `#VALUE!`: Wrong data type in formula
     - `#NAME?`: Unrecognized formula name

### Creating new Excel files

```python
# Using openpyxl for formulas and formatting
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Add data
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Add formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatting
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Column width
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')
```

### Editing existing Excel files

```python
# Using openpyxl to preserve formulas and formatting
from openpyxl import load_workbook

# Load existing file
wb = load_workbook('existing.xlsx')
sheet = wb.active  # or wb['SheetName'] for specific sheet

# Working with multiple sheets
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Sheet: {sheet_name}")

# Modify cells
sheet['A1'] = 'New Value'
sheet.insert_rows(2)  # Insert row at position 2
sheet.delete_cols(3)  # Delete column 3

# Add new sheet
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'

wb.save('modified.xlsx')
```

## Recalculating formulas

Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided `scripts/recalc.py` script to recalculate formulas:

```bash
python scripts/recalc.py <excel_file> [timeout_seconds]
```

Example:
```bash
python scripts/recalc.py output.xlsx 30
```

The script:
- Automatically sets up LibreOffice macro on first run
- Recalculates all formulas in all sheets
- Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
- Returns JSON with detailed error locations and counts
- Works on both Linux and macOS

## Formula Verification Checklist

Quick checks to ensure formulas work correctly:

### Essential Verification
- [ ] **Test 2-3 sample references**: Verify they pull correct values before building full model
- [ ] **Column mapping**: Confirm Excel columns match (e.g., column 64 = BL, not BK)
- [ ] **Row offset**: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)

### Common Pitfalls
- [ ] **NaN handling**: Check for null values with `pd.notna()`
- [ ] **Far-right columns**: FY data often in columns 50+ 
- [ ] **Multiple matches**: Search all occurrences, not just first
- [ ] **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)
- [ ] **Wrong references**: Verify all cell references point to intended cells (#REF!)
- [ ] **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets

### Formula Testing Strategy
- [ ] **Start small**: Test formulas on 2-3 cells before applying broadly
- [ ] **Verify dependencies**: Check all cells referenced in formulas exist
- [ ] **Test edge cases**: Include zero, negative, and very large values

### Interpreting scripts/recalc.py Output
The script returns JSON with error details:
```json
{
  "status": "success",           // or "errors_found"
  "total_errors": 0,              // Total error count
  "total_formulas": 42,           // Number of formulas in file
  "error_summary": {              // Only present if errors found
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}
```

## Best Practices

### Library Selection
- **pandas**: Best for data analysis, bulk operations, and simple data export
- **openpyxl**: Best for complex formatting, formulas, and Excel-specific features

### Working with openpyxl
- Cell indices are 1-based (row=1, column=1 refers to cell A1)
- Use `data_only=True` to read calculated values: `load_workbook('file.xlsx', data_only=True)`
- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values and permanently lost
- For large files: Use `read_only=True` for reading or `write_only=True` for writing
- Formulas are preserved but not evaluated - use scripts/recalc.py to update values

### Working with pandas
- Specify data types to avoid inference issues: `pd.read_excel('file.xlsx', dtype={'id': str})`
- For large files, read specific columns: `pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`
- Handle dates properly: `pd.read_excel('file.xlsx', parse_dates=['date_column'])`

## Code Style Guidelines
**IMPORTANT**: When generating Python code for Excel operations:
- Write minimal, concise Python code without unnecessary comments
- Avoid verbose variable names and redundant operations
- Avoid unnecessary print statements

**For Excel files themselves**:
- Add comments to cells with complex formulas or important assumptions
- Document data sources for hardcoded values
- Include notes for key calculations and model sections
```

#### 资料库

- 来源: 内置/市场
- 说明: 当要写/整理在线文档、建数据表增删改查、导入 CSV·Excel、做看板/dashboard/运营页/汇报页、md 转网页或演示 HTML 发布、建目录、上传下载网盘文件、审阅修订、分享协作，以及提到资料库/知识库/网盘/空间/workbuddy.cn/space 链接时使用。资料库是 WorkBuddy 原生的内容管理、分享协作与轻发布模块，覆盖在线文档（doc）、网页链接（link）、结构化数据表（database）、数据/汇报页面（page）、网盘文件（drive）与空间管理（manage）；凡说资料库/知识库或出现 space 链接、未显式点名腾讯文档/飞书/Notion/乐享/金山文档/iWiki 等外部产品时一律走本 skill，默认落原生库、不反问存到哪个产品。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-library\5.5.6-wb.38337834.g5f969292.h4918b5ced607\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `.orphaned_at`, `_common.py`, `api-manifest.json`, `attachment/attachment.py`, `attachment/entry.md`, `database/_db_types.py`, `database/add_database_field.py`, `database/batch_add_database_records.py`, `database/batch_delete_database_records.py`, `database/batch_update_database_records.py`, `database/create_database.py`

```markdown
# 资料库使用指南

## 调用前置

静默读取运行环境，仅用于内部路由和鉴权；除非用户明确询问，不在过程说明、确认或成功回执中提及：

`python3 "${CODEBUDDY_SKILL_DIR}/runtime_context.py"`

- 输出 `mode=sandbox`：不调 `connect_open_platform`、不传 token；`mode=client`：按客户端模式鉴权。
- `mode=client` 的鉴权调用必须严格执行：先用 `ToolSearch` 精确查询 `{"tool_names":["connect_open_platform"]}`，再用 `DeferExecuteTool` 调用 `{"toolName":"connect_open_platform","params":{"skill_id":"library"}}`。拿到 `authenticated=true` 且非空的 `token` 后，才能执行本 skill 的网络脚本。
- `connect_open_platform` 是 deferred MCP 工具，不是 shell/CLI 命令，也不是 `space_api.py` 子命令。禁止通过 Bash、`cbc`、`codebuddy`、Python 或 `space_api.py connect_open_platform` 调用；禁止在环境变量、本地文件、凭证目录、进程、二进制或 RPC 中搜索/探测 token；禁止用空值或伪造值调用 `--token-stdin`。`ToolSearch` 未找到工具或 `DeferExecuteTool` 换票失败时立即停止，不改走其它凭证路径。
- 目标空间由所有模块按以下顺序统一决定：
  1. 操作已有节点：用户给出 `nodeId` 或节点链接时，按该节点的实际归属执行，不套用默认空间。
  2. 用户显式指定空间或目录：以该目标为准；已给出或解析出 `spaceId` 时传实际值，仅明确指定我的文档但未给 ID 时可省略可选 `spaceId`；按 `parentId` 新建时，先取得其所属 `spaceId`，确认二者匹配后同时传入。
  3. 无显式目标：创建、导入、上传时省略可选的 `--space-id` / `space_id`，由后端默认落我的文档。

以脚本输出为准。脚本失败时停止，简要说明无法继续即可。

## 远端变更

凡创建/上传、修改、删除、移动或重命名远端资料，先静默执行 `mutation.md`，按其规则判定实际目标空间分类与是否需要停下确认。

## 检索授权

明确给出单个节点时只读取该节点，不扩展成全库搜索。“写报告”“做方案”等泛化创作不触发检索。写入目标不等于检索授权。

## 按 kind 直取入口

访问/处理任一资料库节点前，先归一化为 nodeId（`/space/d/{id}` 或 `*.workbuddy.link/p/{id}` 直接提取 `{id}` 为 nodeId、搜索结果取 nodeId），再用 `space.workspace.node-info` 读 `kind`。

按下表读取对应的 entry：

| kind | 场景 | 入口 |
|---|---|---|
| doc | 在线文档读/改 | `doc/entry.md` |
| web / page | HTML 页面 | `page/entry.md` |
| database | 结构化表 | `database/entry.md` |
| link | 网页剪藏 | `link/entry.md` |
| drive | 网盘文件 | `drive/entry.md` |
| smh | 历史媒体节点 | `smh/entry.md` |
| 目录 / 空间导航 / 全局搜索 | 管理 | `manage/entry.md` |

## 目标选择

- 说「存到资料库」且未点名外部产品时，默认且唯一是原生资料库，不反问存哪、不把外部产品拼成选择题。
- 只在缺文档主题时问主题。
- 仅写入失败/权限不足/多个同名空间/语义指向团队空间但名称不全时消歧，且只列原生空间（`space.workspace.list-user-spaces`）。

## 文件夹意图

说「建文件夹/做目录/把文档归到一起/建知识库」时，不默认建空间；默认用真·文件夹（纯容器目录节点）承接，措辞用「挂到下面/目录树」，不用「父/子节点」：

| 做法 | 怎么做 | 适合 |
|---|---|---|
| 文件夹（默认） | `manage/create_folder.py` 建纯容器目录节点，其余文档用 `move-node` 挂到它下面成目录树 | 纯归类整理 |
| 文档目录页 | 新建一篇文档当目录页（可在页内写导航/索引正文），其余文档挂到它下面 | 目录本身要写说明/导航时 |
| 独立空间 | 单独建空间统一管理；长期+多人协同推荐团队空间 | 长期沉淀 |

默认走「文件夹」；用户明确要「目录页里写点说明/索引」时走文档目录页；语义偏长期沉淀或多人协同时走独立空间。回执给对应链接（空间 `/space/s/{spaceId}`、节点 `/space/d/{nodeBlockId}`）；落地命令见 `manage/entry.md`。

## 场景路由表

| 场景 | 入口 |
|---|---|
| 列/看目录子节点（按父节点拉一层，不传取空间根目录） | `manage/entry.md` |
| 列全部资料库位置（我的文档/团队空间） | `manage/entry.md` |
| 给节点链接/nodeId 问「这是什么」 | `manage/entry.md` |
| 查询空间/文档/节点的协作成员、参与者或权限角色 | `manage/entry.md` |
| 获取文件下载链接 / 下载文件本体（`kind=drive` 或历史 `kind=smh` 节点） | `drive/entry.md` 或 `smh/entry.md` |
| 给某已存在节点插入附件，或下载其附件（有 attachmentId） | `attachment/entry.md` |
| 上传本地/外链图片或文件到资料库 | 按类型分流：图片 → `manage/entry.md`；csv → `database/entry.md`；html/zip → `page/entry.md`；md → `doc/entry.md`；docx/pdf 等 → `drive/entry.md`；给已有节点挂附件 → `attachment/entry.md` |
| 建文件夹 / 新建目录 / 把文档归到一起 / 整理归类乱掉的目录树 | `manage/entry.md` |
| 移动节点（同空间换父） | `manage/entry.md` |
| 重命名节点 / 改标题 / 网盘文件改名 | `manage/entry.md` |
| 全库检索（历史沉淀、历史决策、报错排查、术语） | `manage/entry.md` |
| 给 spaceId 或 `/space/s/{spaceId}` 要梳理/整理/总结某主题 | `manage/entry.md` |
| 在指定文档/空间内搜内容片段 | `manage/entry.md` |
| 创建在线文档 / 整理成文档 / 据某空间·素材生成文档·讲稿·报告 | `doc/entry.md` |
| 保存/收藏/剪藏一个 http(s) 网页为 `kind=link` 节点 | `link/entry.md` |
| 读取/总结已有 `kind=link` 节点的网页正文 | `link/entry.md` |
| 建表 / 字段增删改 / 插改查记录 / 看 schema / 导入 CSV | `database/entry.md` |
| 从零生成单页 HTML/网页/汇报/报告/分析/可视化/单页数据应用（未点名外部产品、未明确只要本地文件） | `page/entry.md` |
| 制作可视化 HTML（非做站/做应用） / 本地 doc·ppt·pdf·excel·图片（单个或综合素材）说做成页面·美化·做汇报分享 | `page/beautify-flow.md` |
| 把 md/文档/表格/csv做成一页汇报 / PPT 风格 / 数据报告页（md→html） | `page/entry.md` |
| 做运营页/看板/dashboard/给团队看的展示页 | `page/entry.md` |
| 上传 HTML/ZIP / 接入数据库 / 创建数据驱动页 | `page/entry.md` |
| 贴 page 详情页（`/space/d/`）或发布态链接（`*.workbuddy.link/p/`，`/p/` 后段即 nodeId）让编辑修改 | `page/edit-flow.md` |
| 管理 page 与 database 的数据关联绑定（某 page 引用了哪些 database / 某 database 被哪些 page 引用 / 建立·解除 page↔database 关联，非父子节点·非目录归属） | `page/entry.md` |

## 调用方式与运行模式

网络能力经 `space_api.py` 或各模块脚本调用，命令与参数以对应 `entry.md` 为准。运行态以 `runtime_context.py` 的输出为准；业务脚本内部由 `_common.is_sandbox()` 分派。公共请求层不自动补 `spaceId`。

| 当前上下文 | 模式 | 鉴权 | 调用形态 |
|---|---|---|---|
| `mode=sandbox` | 沙箱模式 | 不调 `connect_open_platform`、不传 token；auth-proxy 注入身份 | `python3 .../script.py [args]` |
| `mode=client` | 客户端模式 | 每次网络命令前按“`ToolSearch` 精确查询 → `DeferExecuteTool` 调用”的顺序执行 `connect_open_platform` 取 `token`；agent 直接把 token 通过 stdin 首行传给脚本，同时带 `--token-stdin` 开关；token 不落地、不写文件、不跨进程复用 | `printf '%s' "<token>" \| python3 .../script.py --token-stdin [args]` |

- 需要业务 stdin payload 时 token 占首行，业务 JSON 从第二行起（或 `--content-file` 走文件通道）。
- `--help` 查看某 API 参数（不需要 token）；`--raw` 调试原始响应（鉴权与普通调用相同）。

```bash
python3 "${CODEBUDDY_SKILL_DIR}/space_api.py" space.workspace.list-user-spaces
printf '%s' "<token>" | python3 "${CODEBUDDY_SKILL_DIR}/space_api.py" space.workspace.list-user-spaces --token-stdin
printf '%s\n%s' "<token>" "$(cat payload.json)" | python3 "${CODEBUDDY_SKILL_DIR}/space_api.py" space.workspace.node-info --token-stdin --stdin
python3 "${CODEBUDDY_SKILL_DIR}/space_api.py" <api-name> --help
printf '%s' "<token>" | python3 "${CODEBUDDY_SKILL_DIR}/space_api.py" <api-name> --token-stdin --raw
```

客户端模式访问显式的 `staging.workbuddy.cn` 目标时，为对应网络命令设置 `LIBRARY_ENV=staging`；其他客户端目标不设置该变量并默认走生产。沙箱模式固定走 auth-proxy，不使用 `LIBRARY_ENV`。

**响应约定**：成功 → stdout 输出结构化文本（`KS_*` 前缀行 / 单行 JSON / XML 块）；失败 → stdout 仅一行 `{"error":"<脱敏错误>"}` 后 `exit 0`（含 header `traceid` 时附带）。后端 / HTTP 失败的错误内容为 `code=<错误码>; msg=<安全业务说明>`；无后端码的本地参数校验可保留明确文本。脚本只读取后端信封的 `code/msg`；`msg` 经截断和脱敏后透传，不透传其它响应字段、requestId、请求体、Token、Cookie、堆栈、内部路径或完整签名 URL。SKILL 层据「stdout 是 `KS_*` 还是 `{"error":...}`」判定走堆。**若 stdout 含 `KS_USER_REPLY\t...`，最终用户回执必须直接原样透传该行正文，禁止自行拼接链接、改写为近似文案或补写内部 ID。**

### 错误码行动表

收到 `{"error": ...}` 时读 `error_handling.md` 按表执行：取最内层 `code=<错误码>` 只执行一条动作，未列出码按临时故障处理；给用户转自然语言，不展示内部码。

特例：脚本报本地 `AUTH_REQUIRED`（当前网络命令前尚未通过 `DeferExecuteTool` 成功取得非空 token）属于客户端鉴权前置未完成，按上文「调用前置」规定补做一次 `ToolSearch` → `DeferExecuteTool` 换票；不向用户误报为资料权限不足，也不搜索其它凭证来源；正确换票最多 1 次，工具不可用或换票失败即停止。

## 安全底线

1. 数据敏感（客户数据/合同金额/密钥/隐私）立即停止，提示走合规通道；拿不准按敏感处理。
2. Token 与内部细节（原始响应/错误堆栈/内部 URL）永不进入用户回复、日志或落库产物。
3. 产物只搬面向读者的成品；token、工具调用、思考过程、本地路径绝不写进产物。
4. 每轮只走一条模块分支，模块协作通过脚本输出串联。
5. 只处理用户显式给出的路径，不自动扫描目录。
```

#### drawio

- 来源: 项目生成
- 说明: This skill should be used when users need to create native, editable Draw.io diagrams, export them to PNG, SVG, or PDF with embedded diagram XML, or install Draw.io Desktop after explicit confirmation. It supports flowcharts, architecture diagrams, process maps, ER diagrams, and other structured visualizations.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2095424021306400768\drawio\SKILL.md`
- 附带文件: `LICENSE`, `agents/openai.yaml`, `references/install-drawio.md`

```markdown
# Draw.io 专业绘图技能

生成原生、可编辑的 `.drawio` 图表文件。按需导出为 PNG、SVG 或 PDF，并嵌入图表 XML，使导出文件仍可在 Draw.io 中继续编辑。若本机缺少 Draw.io Desktop，可在用户明确确认后，从可信来源安装并验证 CLI。

> 版权声明：Copyright (c) 2026 江一帆。保留所有权利。

## 软件检测与安装

1. **先检测再安装**：在需要打开或导出图表时，先检测 Draw.io Desktop 及 CLI 是否已存在，不得重复安装。
2. **只在必要时触发**：仅当用户明确要求安装，或导出任务依赖本地 CLI 且检测结果为未安装时，进入安装流程。
3. **先取得明确确认**：执行任何安装命令前，说明软件来源、安装命令、典型安装位置、权限影响和验证动作，等待用户明确同意。
4. **仅使用可信来源**：优先使用 macOS Homebrew 官方 Cask、Windows Package Manager 的 `JGraph.Draw`、Linux Snap Store 的 `drawio`，或 `jgraph/drawio-desktop` 官方 Releases。
5. **禁止静默或绕过安装**：不得静默接受协议，不得关闭系统安全检查，不得从第三方下载站获取安装包，不得在未确认时使用管理员权限。
6. **按安装指南执行**：读取并严格遵循 `@references/install-drawio.md`，完成系统检测、安装选择、用户确认和 CLI 验证。
7. **允许无桌面软件降级**：仅生成 `.drawio` 源文件时不强制安装 Draw.io Desktop；无法安装时仍可交付原生文件，并说明导出功能暂不可用。

## How to create a diagram

1. **Generate draw.io XML** in mxGraphModel format for the requested diagram
2. **Write the XML** to a `.drawio` file in the current working directory using the Write tool
3. **If the user requested an export format** (png, svg, pdf), export using the draw.io CLI with `--embed-diagram`
4. **Keep the editable source by default** — delete the source `.drawio` file only when the user explicitly requests deletion and the exported file has been verified successfully
5. **Present the result** — return the exported file if exported, or the `.drawio` file otherwise

## Choosing the output format

Check the user's request for a format preference. Examples:

- `/drawio create a flowchart` → `flowchart.drawio`
- `/drawio png flowchart for login` → `login-flow.drawio.png`
- `/drawio svg: ER diagram` → `er-diagram.drawio.svg`
- `/drawio pdf architecture overview` → `architecture-overview.drawio.pdf`

If no format is mentioned, just write the `.drawio` file and open it in draw.io. The user can always ask to export later.

### Supported export formats

| Format | Embed XML | Notes |
|--------|-----------|-------|
| `png` | Yes (`-e`) | Viewable everywhere, editable in draw.io |
| `svg` | Yes (`-e`) | Scalable, editable in draw.io |
| `pdf` | Yes (`-e`) | Printable, editable in draw.io |
| `jpg` | No | Lossy, no embedded XML support |

PNG, SVG, and PDF all support `--embed-diagram` — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

## draw.io CLI

The draw.io desktop app includes a command-line interface for exporting. If the CLI is unavailable and installation is necessary, follow `@references/install-drawio.md`; never install software without explicit user confirmation.

### Locating the CLI

Try `drawio` first (works if on PATH), then fall back to the platform-specific path:

- **macOS**: `/Applications/draw.io.app/Contents/MacOS/draw.io`
- **Linux**: `drawio` (typically on PATH via snap/apt/flatpak)
- **Windows**: `"C:\Program Files\draw.io\draw.io.exe"`

Use `which drawio` (or `where drawio` on Windows) to check if it's on PATH before falling back.

### Export command

```bash
drawio -x -f <format> -e -b 10 -o <output> <input.drawio>
```

Key flags:
- `-x` / `--export`: export mode
- `-f` / `--format`: output format (png, svg, pdf, jpg)
- `-e` / `--embed-diagram`: embed diagram XML in the output (PNG, SVG, PDF only)
- `-o` / `--output`: output file path
- `-b` / `--border`: border width around diagram (default: 0)
- `-t` / `--transparent`: transparent background (PNG only)
- `-s` / `--scale`: scale the diagram size
- `--width` / `--height`: fit into specified dimensions (preserves aspect ratio)
- `-a` / `--all-pages`: export all pages (PDF only)
- `-p` / `--page-index`: select a specific page (1-based)

### Presenting the result

Use the host application's file presentation capability to return the final `.drawio` or exported file to the user. Use the operating system's open command only when the host does not provide a result preview or file presentation capability:

- **macOS**: `open <file>`
- **Linux**: `xdg-open <file>`
- **Windows**: `start <file>`

## File naming

- Use a descriptive filename based on the diagram content (e.g., `login-flow`, `database-schema`)
- Use lowercase with hyphens for multi-word names
- For export, use double extensions: `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` — this signals the file contains embedded diagram XML
- Preserve the source `.drawio` file by default. Remove it only after explicit user confirmation and successful verification that the exported file contains the embedded diagram XML

## XML format

A `.drawio` file is native mxGraphModel XML. Always generate XML directly — Mermaid and CSV formats require server-side conversion and cannot be saved as native files.

### Basic structure

Every diagram must have this structure:

```xml
<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Diagram cells go here with parent="1" -->
  </root>
</mxGraphModel>
```

- Cell `id="0"` is the root layer
- Cell `id="1"` is the default parent layer
- All diagram elements use `parent="1"` unless using multiple layers

### Common styles

**Rounded rectangle:**
```xml
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>
```

**Diamond (decision):**
```xml
<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
</mxCell>
```

**Arrow (edge):**
```xml
<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

**Labeled arrow:**
```xml
<mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="3" target="6" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

### Useful style properties

| Property | Values | Use for |
|----------|--------|---------|
| `rounded=1` | 0 or 1 | Rounded corners |
| `whiteSpace=wrap` | wrap | Text wrapping |
| `fillColor=#dae8fc` | Hex color | Background color |
| `strokeColor=#6c8ebf` | Hex color | Border color |
| `fontColor=#333333` | Hex color | Text color |
| `shape=cylinder3` | shape name | Database cylinders |
| `shape=mxgraph.flowchart.document` | shape name | Document shapes |
| `ellipse` | style keyword | Circles/ovals |
| `rhombus` | style keyword | Diamonds |
| `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors |
| `edgeStyle=elbowEdgeStyle` | style keyword | Elbow connectors |
| `dashed=1` | 0 or 1 | Dashed lines |
| `swimlane` | style keyword | Swimlane containers |
| `group` | style keyword | Invisible container (pointerEvents=0) |
| `container=1` | 0 or 1 | Enable container behavior on any shape |
| `pointerEvents=0` | 0 or 1 | Prevent container from capturing child connections |

## Edge routing

draw.io does **not** have built-in collision detection for edges. Plan layout and routing carefully:

- Use `edgeStyle=orthogonalEdgeStyle` for right-angle connectors (most common)
- **Space nodes generously** — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
- Use `exitX`/`exitY` and `entryX`/`entryY` (values 0-1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
- **Leave room for arrowheads**: ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
- Add explicit **waypoints** when edges would overlap:
  ```xml
  <mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
    <mxGeometry relative="1" as="geometry">
      <Array as="points">
        <mxPoint x="300" y="150"/>
        <mxPoint x="300" y="250"/>
      </Array>
    </mxGeometry>
  </mxCell>
  ```
- Use `rounded=1` on edges for cleaner bends
- Use `jettySize=auto` for better port spacing on orthogonal edges
- Align all nodes to a grid (multiples of 10)

## Containers and groups

For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment.

### Container types

| Type | Style | When to use |
|------|-------|-------------|
| **Group** (invisible) | `group;` | No visual border needed, container has no connections |
| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header |
| **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container |

### Key rules

- **Always add `pointerEvents=0;`** to container styles that should not capture connections
- Children must set `parent="containerId"` and use coordinates **relative to the container**

### Example: Architecture container with swimlane

```xml
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
```

## CRITICAL: XML well-formedness

- **NEVER use double hyphens (`--`) inside XML comments.** `--` is illegal inside `<!-- -->` per the XML spec and causes parse errors. Use single hyphens or rephrase.
- Escape special characters in attribute values: `&amp;`, `&lt;`, `&gt;`, `&quot;`
- Always use unique `id` values for each `mxCell`
```

#### md-to-reader-html

- 来源: 自建
- 说明: 把 Markdown 长文档（会议纪要、指南、教程、报告、访谈整理）转成单文件「暗色科技风阅读版」HTML——带页头 kicker + 大标题 + chip 标签、自动目录、表格圆角容器、引用块渐变、代码块、打印自动转浅色。当用户说「把这份 md 转成网页/阅读版」「文档排版美化一下」「生成可阅读的 HTML」「放到手机上读」，或任何会话里产出了 .md 交付物需要配一份 HTML 阅读版时使用。零依赖、不联网，纯 Python 标准库。
- 路径: `C:\Users\lenovo\.workbuddy\skills\md-to-reader-html\SKILL.md`
- 附带文件: `scripts/md2html.py`

```markdown
# Markdown → 暗色科技风阅读版 HTML

一份 md 交付物，人读起来不如一个网页。这个 skill 把它变成**单文件、可直接双击、手机也能读**的 HTML。

## 快速用法

```bash
C:\Users\lenovo\.workbuddy\binaries\python\versions\3.13.12\python.exe \
  "C:\Users\lenovo\.workbuddy\skills\md-to-reader-html\scripts\md2html.py" \
  "路径\文档.md" -o "生成物\文档.html" \
  --kicker "HUAWEI CONNECT 2026 · AI 初学者指南" \
  --chip "适合对象 · 没系统学过 AI 的同学"
```

参数：

| 参数 | 作用 |
|---|---|
| `-o` | 输出路径，默认与 md 同目录同名 |
| `--kicker` | 页头小标签（全大写字距拉宽，放来源/场合） |
| `--chip` | 页头胶囊标签，可重复；放「适合对象」「版本」这类元信息 |
| `--title` | 覆盖标题，默认取 md 第一个 `# ` |
| `--theme light` | 换浅色底（默认深色；打印时自动转浅色，无需手动切） |
| `--no-toc` | 不生成目录 |
| `--footer` | 自定义页脚；不填则写「本页由 xxx.md 自动生成」 |

## 支持范围

标题 h1-h6、段落、`**粗**` `*斜*` `` `行内码` ``、有序/无序列表（含嵌套与懒续行）、表格（识别 `:` 对齐）、引用块（可嵌套列表）、代码栅栏（```lang 会带 class）、分隔线、链接、图片、`~~删除线~~`。

## 设计基线（这是「好看」的来源，别删）

- **页头三段式**：细字距 kicker → clamp() 大标题 → 胶囊 chip 行，下方一条实线收尾
- **h2 左侧蓝色竖条 + 下边框**，滑动阅读时有明显的章节顿挫感
- **表格包一层圆角容器**：`.tablewrap`（1px 边框 + 12px 圆角 + 横向滚动），行 hover 微亮
- **引用块**：从蓝到透明的渐变背景 + 紫色左边条 + 右侧圆角，用来放金句/结论
- **配色变量集中在 `:root`**：`--acc` 蓝 `#38bdf8` / `--acc2` 紫 `#a78bfa` / 底 `#080b10`，body 有一圈 `radial-gradient` 冷光
- **打印自动转浅色**：`@media print` 里重定义整套变量，Ctrl+P 直接出可读白底 PDF，不用改代码

## 血泪规则（上一版真实产物里的缺陷，已修，别改回去）

| 坑 | 现象 | 现在的做法 |
|---|---|---|
| **title 拿正文猜** | `<title>` 变成一段解释性长句，浏览器标签页全是废话 | `<title>` 只取 `--title` 或 md 第一个 `# `；**绝不用正文段落猜** |
| **h1 重复** | 页头一个大标题、正文又一个大标题，看着像两份文档 | md 第一个 `# ` 只用作页头，**正文里跳过不输出** |
| **代码栅栏没渲染** | 页面里直接出现 ``` 三个反引号，当成普通段落排 | 栅栏必须进 `<pre><code>`，且带 `language-*` class |
| **列表丢 `<li>`** | 引用块里的有序列表变成一排 `<ol><p>…</p></ol>`，编号错乱 | 列表项统一包 `<li>`，嵌套用缩进递归 |
| **原文尖括号破坏结构** | md 里写 `<hash>` 直接被浏览器当标签吃掉 | 所有正文先 `html.escape`，再套行内标记 |
| **footer 指向不存在的章节** | 页脚写「见正文待核对清单」，可那节根本没写 | 页脚默认只写来源文件名，要写别的就 `--footer` 显式给 |

## 验收口径（交付前自查）

1. `<title>` 与页头 h1 一致，且不像一段话
2. `<h1` 只出现 **1 次**
3. 不残留 ` ``` `
4. `<li>` 数量 ≥ 原文列表项数量
5. 表格数 = 原文表格数，目录锚点逐个能跳

一条命令自查（在输出目录跑）：

```bash
f=文档.html
grep -c "<h1" "$f"; grep -c '```' "$f"; grep -o "<title>[^<]*" "$f"; grep -c "<li>" "$f"
```

## 视觉核验（可选但推荐）

本机没有 playwright/chromium，但有 Edge + playwright-core，可无头截图看真实渲染：

```js
const { chromium } = require('playwright-core');
const b = await chromium.launch({ executablePath: 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe' });
const p = await b.newPage({ viewport: { width: 1280, height: 1400 } });
await p.goto('file:///.../文档.html');
await p.screenshot({ path: '_s1.png' });
```

运行时需 `NODE_PATH=C:\Users\lenovo\.workbuddy\binaries\node\workspace\node_modules`，node 用 `C:\Users\lenovo\.workbuddy\binaries\node\versions\22.22.2-3\node.exe`。

## 交付物归置

产出统一进项目的 `生成物/`，项目根只留 `生成物/` + 快捷方式（悦皓 2026-09-17 铁律）。临时截图/脚本用完即删，别留在根目录。
```

#### oa-paper-translate

- 来源: 自建
- 说明: 把学术论文（单篇或一批）抓取开放获取全文并翻译成中文单文件 HTML。当用户要「翻译这篇论文」「把文献翻译成中文」「找全文并译」「把阅读清单里的论文都翻了」、或涉及 OA 论文抓取、ResearchGate/arXiv/课程站镜像、Cloudflare 拦截、pdfplumber 提取、浅色保结构 HTML 译文时使用。覆盖 CC BY / arXiv / IEEE Access / HBR / Springer CC-BY / 大学课程站托管 PDF 等开放来源；对付费墙（INFORMS/POM/Wiley/ACM/Elsevier）给出明确判定与待上传清单。
- 路径: `C:\Users\lenovo\.workbuddy\skills\oa-paper-translate\SKILL.md`

```markdown
# 开放获取论文抓取与全文中译

## 何时用
- 把一篇论文翻成中文、保结构单文件 HTML（摘要 / 章节 / 正文 / 参考文献原文）
- 批量翻译一份文献清单（如阅读路线页里所有论文）
- 绞尽脑汁找某篇论文的开放全文（被 Cloudflare / 付费墙挡时）

---

## 一、总工作流（单篇）

1. **判定 OA 状态**：DOI/出处先分类——
   - 必能抓：arXiv（`arxiv.org/html/<id>v1` 直抓正文）、IEEE Access（金色 OA，文章页即全文）、HBR（常免费）、Europe PMC、部分 Springer CC-BY、CC BY 4.0 期刊。
   - 常能抓：作者个人主页、**大学课程站托管的 JSTOR/Wiley PDF**（见坑③）。
   - 基本挡死：INFORMS（MS/EJOR）、POM、Wiley（非 OA）、ACM、Elsevier（非 OA）。
2. **抓全文**（优先级由上到下，别死磕一个源）：
   - arXiv → WebFetch `https://arxiv.org/html/<id>v1`，提示"提取完整全文逐字"。
   - IEEE Access / HBR / Europe PMC / Springer OA → 直接 WebFetch 文章页抓全文。
   - 付费墙先试 **ResearchGate**：WebFetch 该文 RG 页（本环境 WebFetch **能过 RG**，但**过不了 ORCA/ScienceDirect**），常内嵌 preprint/postprint 全文。
   - 再试 OpenAlex / Semantic Scholar / Unpaywall 查有无开放副本 URL，有则 WebFetch 那个 URL。
   - 都不行 → 换源（见坑③课程站）。
3. **提取 PDF 文本**（当拿到 PDF 文件时）：
   ```sh
   C:\Users\lenovo\.workbuddy\binaries\python\versions\3.13.12\python.exe -m pip install --quiet pdfplumber
   ```
   ```py
   import pdfplumber
   with pdfplumber.open("x.pdf") as pdf:
       txt = "".join((pg.extract_text() or "") for pg in pdf.pages)
   ```
4. **翻译为单文件浅色 HTML**：保留「摘要 → 章节标题 → 正文 → 参考文献(英文原文)」结构；术语统一（bullwhip=牛鞭效应、order-up-to=补货至基准库存、VMI=供应商管理库存、APIOBPCS/ARIMA/SES/MMSE 等技术缩写保留）。
5. **验证**：用 node 统计关键词出现次数 + 抽查首尾段落，确认不是抓到验证页/空壳。

---

## 二、批量清单的处理（多于一打论文时）

- 派 **general-purpose 子代理**自动跑：能抓到全文的当场翻成单文件 HTML，抓不到的进付费墙清单。这样不撑爆主会话上下文。
- 子代理完成后**必须复核产物**（读文件、关键词抽检），不要只信它返回的摘要。
- 产出一份 `TRANSLATION_STATUS.md`：已译（文件名+标题+来源）/ 付费墙待上传 PDF（标题+URL+备注）。
- **亲自补抓明显该免费的高价值文献**（子代理常把 Lee 1997 / Chen 2000 / 部分 OA 草草归墙）。

---

## 三、致命坑（现象 → 原因 → 解法）

**① 中国 IP + 自动化被 Cloudflare 拦**
- 现象：ORCA 机构库、ScienceDirect 不论 curl / WebFetch / 本机 Edge 无头，全部返回 "Verification Required" 验证页，抓到的 PDF 只是验证页本身（`%PDF` 头但 `Verification` 字样）。
- 原因：Cloudflare 检测到中国大陆 IP + 非真人流量。
- 解法：**换开放镜像源**（ResearchGate / arXiv / 课程站），不要硬刚 Cloudflare。本环境 WebFetch 能过 ResearchGate，但过不了 ORCA。

**② 深色页直接打印 / 转 PDF 会白底白字全隐形**
- 现象：原页深色底白字，用 Edge `--print-to-pdf` 后台变白，白字消失。
- 解法：先生成**浅色全静态**版（把 JS 动态生成的内容写死进 HTML），再打印。

**③ 大学课程站托管的 PDF 是金矿**
- 现象：Lee, Padmanabhan & Whang (1997) Management Science 分析版（四成因数学建模）在 INFORMS 是付费墙，但 WebSearch 找到 `courses.ie.bilkent.edu.tr/.../Lee-Padmanabhan-Whang-1997-MS.pdf`，`curl -L -A "Mozilla/5.0 ... Chrome/120" <url> -o x.pdf` 直下成功（615KB，14 页），pdfplumber 提取正常。
- 规律：JSTOR / Wiley / Springer 的经典老文，常被动过版权（green OA / 教学用途）挂在欧美大学课程站，curl 带 UA 就能下。

**④ 本机无 playwright/puppeteer/chromium，但 Edge 可 headless 打印**
- 环境只有 `C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe` 支持 `--headless --no-sandbox --print-to-pdf`。
- 但 Edge 无头过 Cloudflare **仍常被卡**（验证页同样抓不到真 PDF）。所以 Edge 只用于"已有 HTML→PDF"，**不用于"过墙抓 PDF"**。

**⑤ 绝不编造论文内容**
- 拿不到全文就判"付费墙不可获取"，进清单等用户上传 PDF。**绝不靠记忆/搜索引擎摘要拼凑翻译**。

---

## 四、验收口径
- 译文 HTML 含「摘要/章节/结论/References」关键字；
- 关键人名、年份、公式符号在正文出现；
- 参考文献保留英文原文（便于检索引用）；
- 付费墙清单与已译清单分离，待用户上传 PDF 后照同样方式补译。
```

#### local-asr-meeting-minutes

- 来源: 自建
- 说明: 把本地音频/视频（m4a/mp4/wav，含微信现场录音、会议录音、访谈、讲座、课堂录音）批量转写成带时间码的中文文本，并整理成结构化文档——会议记录纲要 / 课堂笔记（Markdown + 阅读版 HTML）。当用户给出录音/视频并要求"生成会议纪要/会议记录纲要/课堂笔记""整理访谈""转写音频""做会议记录""把这几段录音整理一下"时使用。本机已内置 faster-whisper、small 与 large-v3 模型，全程离线；含模型选型判据（低信噪比必须 large-v3）、分片并行加速、领域术语提示词、多段录音归场次、幻灯片对齐、待核对清单等实战要点。
- 路径: `C:\Users\lenovo\.workbuddy\skills\local-asr-meeting-minutes\SKILL.md`

```markdown
# 本地转写 → 会议记录纲要

零联网、零调用的本地 ASR 工作流。**75 分钟音频约 6 分钟出稿**（16 核 CPU，5 进程并行）。

## 0. 本机环境事实（先复用，别重装）

| 项 | 路径 / 值 |
|---|---|
| venv python | `C:\Users\lenovo\.workbuddy\binaries\python\envs\default\Scripts\python.exe` |
| 已装包 | `faster_whisper`、`ctranslate2 4.8.2`、`numpy`、`av`、`onnxruntime`、`huggingface_hub` |
| small 模型 | `C:\Users\lenovo\.cache\huggingface\hub\models--Systran--faster-whisper-small\snapshots\<hash>` |
| **large-v3 模型** | `C:\Users\lenovo\.workbuddy\binaries\models\faster-whisper-large-v3`（2026-09-21 经 hf-mirror 补下，`model.bin` 2.94 GB，完整可用） |
| ffmpeg | `C:\Users\lenovo\AppData\Roaming\bilibili\ffmpeg\ffmpeg.exe`（无 ffprobe；用 `ffmpeg -i` 看时长） |

执行前先确认模型快照目录名（hash 会变）：`Glob` 搜 `**\models--Systran--faster-whisper-small\snapshots\*`。

> ⚠️ HF 缓存里的 `models--Systran--faster-whisper-large-v3` **只有 config/tokenizer、缺 `model.bin`**，直接拿来用会报错。走 mirror 补下见 §3.5。

### 0.1 先选模型：small 还是 large-v3（**这一步错了后面全废**）

| 素材条件 | 用哪个 | 理由 |
|---|---|---|
| 会议室近场、单人或少量讲者、信噪比好 | `small`（快，5 进程 ~23x 实时） | 质量够用 |
| **大教室 / 礼堂 / 远距离 / 混响重 / 手机放包里** | **必须 `large-v3`** | small 会出现**大面积重复幻觉**，句子完全不可用 |

**判定方法**：先切 4 分钟有语音的片段，small 和 large-v3 各跑一遍对比。若 small 输出出现「XX中的XX中的XX中的…」这种整段复读，或出现与内容无关的口水句（"请不吝点赞、订阅、转发、打赏支持…"），**立刻弃用 small**，别在它身上调参。

**代价**（16 核 / 31 GB 内存，int8 CPU）：
- large-v3 单进程 8 线程 ≈ **2.0x 实时**；`--workers 2 --threads 7` 打满 16 核 ≈ **2.5–3x 实时**（81 分钟音频约 32 分钟）。
- **内存**：large-v3 int8 每进程约 3 GB。空闲内存 < 10 GB 时**只用 2 个 worker**，3 个会换页反而更慢。
- 想再快可换 `large-v3-turbo`（约 1.6 GB，快 ~4 倍），但噪声环境下质量要实测。

**实测对比（同 4 分钟嘈杂课堂录音）**：

| 模型 | 输出 |
|---|---|
| small | 「那我们怎么跟随大家，把他们收下，想办法，给医院电视报名」（原文：我们要怎么分析它呢，把它简化成一个电路模型） |
| **large-v3** | 「好的，咱们电路分析，这个分析对大家有什么用，大家看一下这里面这几个电器…它们必须经过（复杂）的电路才能运作」 |

## 1. 四步流程

1. **摸时长**：`ffmpeg -hide_banner -i <file>`，正则抓 `Duration: hh:mm:ss`。总时长决定要不要分片并行。
2. **备份素材**：微信临时目录（`...\RWTemp\...`）随时会被清理，先 `Copy-Item` 到项目目录。
3. **分片并行转写**：用下面脚本，一次传多个文件也行。
4. **写纪要**：按第 5 节的骨架组织，术语按第 4 节校正。

## 2. 核心脚本（分片并行）

```python
# transcribe_parallel.py  ——  切段 + 多进程 + 时间戳偏移合并
import os, subprocess, time, argparse
from concurrent.futures import ProcessPoolExecutor

FF = r"C:\Users\lenovo\AppData\Roaming\bilibili\ffmpeg\ffmpeg.exe"
TERM_PROMPT = "……见第 3 节，按领域替换……"

_MODEL = None
def _init_worker(model_path, threads):
    global _MODEL
    from faster_whisper import WhisperModel
    _MODEL = WhisperModel(model_path, device="cpu", compute_type="int8", cpu_threads=threads)

def _job(args):
    wav, offset = args
    segs, _ = _MODEL.transcribe(
        wav, language="zh", beam_size=1, vad_filter=True,
        vad_parameters=dict(min_silence_duration_ms=500),
        initial_prompt=TERM_PROMPT, condition_on_previous_text=False,
        temperature=[0.0, 0.2, 0.4])
    return [{"start": round(s.start+offset, 2), "end": round(s.end+offset, 2),
             "text": s.text.strip()} for s in segs]

def split_audio(src, outdir, seg=180):
    os.makedirs(outdir, exist_ok=True)
    subprocess.run([FF, "-hide_banner", "-loglevel", "error", "-y", "-i", src,
                    "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le",
                    "-f", "segment", "-segment_time", str(seg),
                    os.path.join(outdir, "p_%04d.wav")], check=True)
    return sorted(f for f in os.listdir(outdir) if f.endswith(".wav"))

# main: parts = split_audio(file, outdir/_parts/tag)
#       jobs = [(path, i*seg) for i, p in enumerate(parts)]
#       ProcessPoolExecutor(max_workers=5, initializer=_init_worker,
#                           initargs=(model_path, 3)).map(_job, jobs)
#       合并 → 排序 → 写 <tag>.json / <tag>.txt（[mm:ss] 行）
```

运行示例（注意长任务要显式给大 timeout）：

```powershell
$env:PYTHONIOENCODING="utf-8"
& $venvPy transcribe_parallel.py --file "<音频>" --outdir tr `
  --model "<small 快照目录>" --tag small__X1 --workers 5 --threads 3 `
  *> work\_run.log
```

参数经验：`workers=5 × threads=3` 打满 16 核；`--seg 180` 平衡并行度与段边界；长音频（>30 min）务必分片，单进程跑既慢又易被中断。

### 2.1 走 large-v3 时，解码参数要改成这套

```python
segs, _ = _MODEL.transcribe(
    wav, language="zh", beam_size=5,            # small 用 1，large-v3 用 5
    vad_filter=True,
    vad_parameters=dict(min_silence_duration_ms=500),
    initial_prompt=TERM_PROMPT,
    condition_on_previous_text=False,
    no_repeat_ngram_size=3,                     # ★ 关键：掐掉整段复读
    temperature=[0.0])
```

- `no_repeat_ngram_size=3` + `condition_on_previous_text=False` 是**治重复幻觉的主力**；不加这两条，长静音段会吐出几百字的循环。
- large-v3 别传 `temperature=[0.0,0.2,0.4]` 的 fallback 列表——beam 已经够稳，多了只是白烧时间。
- 跑 large-v3：`--workers 2 --threads 7`（内存受限，见 §0.1）。

## 3. 领域术语提示词（质量的关键）

`initial_prompt` 塞一份术语表，专有名词错误率明显下降。会议前先按主题列名词：

```
以下是<会议名>现场演讲录音，涉及<领域>。常见专有名词：<公司>、<产品1>、<产品2>、
<技术名词>、<英文缩写>、<人名/机构名>……
```

例（华为 CONNECT）：
> 华为、华为云、鸿蒙、HarmonyOS、CodeArts、码道、ArkTS、DevEco、鲲鹏、昇腾、openEuler、欧拉、GaussDB、仓颉、元服务、DevOps、IaC、CI/CD、云原生、微服务、Kubernetes、大模型、智能体、Agent、Agentic、MCP、RAG、提示词、代码迁移、遗留系统、研发效能、全流程、使能、最佳实践、MaaS、开发者、生态、开源。

例（大学《电路分析》课）：
> 电路、电路模型、集总参数电路、理想元件、电阻、电导、电压、电流、电位、电动势、参考方向、关联参考方向、功率、吸收功率、发出功率、电压源、电流源、受控源、独立源、欧姆定律、基尔霍夫电流定律、基尔霍夫电压定律、KCL、KVL、节点、支路、回路、网孔、等效变换、戴维南定理、诺顿定理、叠加定理、电容、电感、正弦稳态、相量、阻抗、导纳、邱关源。

### 3.5 补下 large-v3（HF 缓存里只有一半时）

```python
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
os.environ["HF_HUB_DISABLE_XET"] = "1"          # ★ 不加这条会 401 / symlink 1314
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="Systran/faster-whisper-large-v3",
    local_dir=r"C:\Users\lenovo\.workbuddy\binaries\models\faster-whisper-large-v3",
    allow_patterns=["config.json", "model.bin", "tokenizer.json",
                    "vocabulary.json", "preprocessor_config.json"],
    max_workers=4)
```

2.9 GB 约 9 分钟下完。放自定义目录（**别**塞回 HF 缓存，缓存里那个是坏的）。

## 4. 术语校正纪律

small 模型对中文技术术语误听率高（"码道"→"马道"、"昇腾"→"深层"、"开源"→"看源"、"沙箱"→"杀箱"）。

1. **先在上下文里找锚点**：幻灯片照片、标题页、英文同传（"Alex Khan, President, Partner and Ecosystem Dept." 能反推人名）是最可靠的校正依据。
2. **用数字自校验**：讲者自己推演过的数字若逻辑自洽（如 500 万亿 token ÷ 2000token/s ÷ 86400 ≈ 289 万卡，×1.3 ≈ 375 万卡），说明转录可信。
3. **不确定就列清单，不硬编**：纪要末尾单列"转写不确定项（待核对清单）"，三列 `转录原文 | 本稿采用 | 依据/备注`。**禁止凭常识编造专名**。
4. 人名、公司名、金额、百分比这四类最容易错，必须标"待核"。

## 5. 多段录音怎么归场次

微信/手机录音常按"位置名"命名（`东浩兰生上海世博展览馆(西门) 2.m4a`），与内容无关。两招定归属：

- **首尾衔接法**：A 段结尾与 B 段开头语义能否接上？接得上就说明是同一场被切段（换场、没电）。
- **幻灯片对齐法**：把现场照片上的标题、关键词与录音里出现的句子互相对照，能精确把每张 PPT 挂到某一场（并顺带校正术语）。

## 6. 纪要骨架（直接套用）

```
# <会议名> · 会议记录纲要
大会 / 主题 / 地点 / 时间 / 素材构成 / 整理方式（一行说清方法）
0. 一句话主线
1. 内容地图（表格：素材 → 场次 → 时长 → 备注）
2. 分场纪要（每场：讲者 → 问题提出 → 方案/框架 → 案例 → 数据 → 金句）
3. 幻灯片要点（逐张解读，含中英对照表）
4. 关键数字速查（表格）
5. 金句摘录（按原文口径）
6. 待办与跟进建议（表格：事项 | 对应内容 | 建议动作）
7. 转写不确定项（待核对清单）
8. 复现说明（怎么转的，可交给其他 AI 重跑）
```

交付物：`生成物/<会议名>_会议记录纲要.md` + 同名 `.html`（阅读版）+ `生成物/原始转写/`（每段带时间码的 txt）。

阅读版 HTML 用脚本把 md 转成暗色科技风单文件（标题/表格/列表/引用/粗体/分隔线六类语法足够覆盖纪要）。所有中间产物（音频、分片 wav、日志、脚本）收进 `_work/`，项目根只留 `生成物/`。

## 7. 坑清单

| 坑 | 现象 | 解 |
|---|---|---|
| 日志读不出 | Read 报 "binary file" | PowerShell 重定向的 log 是 UTF-16，先 `open(p,'rb').read().decode('utf-16')` 转 UTF-8 |
| 后台任务静默失败 | status=failed、日志 0 字节 | 默认 timeout 会中途掐掉长任务；显式传大 timeout |
| 单进程太慢 | small 约 9.6x 实时，35 min 音频要 3.6 min | 分片并行到 ~23x |
| 想换大模型 | large-v3 / medium 下载失败（symlink 1314 / Xet 401 / 官网 10061） | 见知识库同类坑：`local_dir=` + `HF_HUB_DISABLE_XET=1` + `HF_ENDPOINT=https://hf-mirror.com`；**下不动就用 small，别卡主线** |
| Bash coreutils 不可用 | `ls`/`tail` command not found | 全程 PowerShell；stdout 常不回显 → 写文件再 Read |
| 多人圆桌段 | 转写乱码成句 | 直接标注"录音为多人同时说话，未做人物级转写"，不要强行编 |
| 现场混入播放的视频/PPT 音频 | 转写出现"中文字幕志愿者 XXX""请不吝点赞、订阅、转发" | 前者是**课堂播放视频的旁白**，后者是 Whisper 在无语音段的**固定幻觉**。两者都**不是**讲者在说话，成稿时不采用，但要在待核对清单里说明 |
| 录音按位置命名、不知先后 | `东川路506号.m4a` 这类名字和内容无关 | 见 §5「首尾衔接法」：把 A 段结尾与 B 段开头对读，接得上就说明谁在前 |
| 静音段整段复读 | 同一短语重复几百字 | large-v3 + `no_repeat_ngram_size=3`（见 §2.1） |

## 8. 变体：课堂录音 → 课堂笔记

会议和上课的差别：会议要**结论和待办**，上课要**定义和概念边界**。所以骨架要换。

**结构（按教材体系组织，不按时间顺序罗列）**：

```
# 《<课程名>》第 N 节课 · 课堂笔记
阅读说明（素材 / 段落顺序判定依据 / 整理方式 / 校正原则）
0. 本节课主线（一句话 + 知识链 ASCII 图）
一、二、三…（按知识点分章；每章内：定义 → 辨析 → 例题 → 要点）
六、本节要点自测（10 题左右，覆盖全部知识点）
七、转写不确定项（待核对清单）
八、复现说明（模型、参数、坑）
```

**成稿纪律**：

1. **定义写全**，写成能直接背的句式：`<概念> —— <属 + 种差>`，再给表达式与单位。
2. **概念辨析单独成节**，用**对比表**（定义 / 表达式 / 方向 / 单位 / 易错点）。一门课里最容易混的几组（如「电压 vs 电位 vs 电动势」）必须开专节，配 ★ 标记。
3. **例题只保留方法与被明确算出的数值**；图看不清就只写方法，别补图。
4. **用数字自校验**：讲者算过的数字若与基本定律自洽（如功率平衡 ΣP=0），说明转写可信、可以写进正文；不自洽的进待核对清单。
5. **绝对不用"课程常识"填空**。转写没听清就不写，或明确标注"待核对"。宁可少讲一个知识点，也不能编。

**交付物**：`生成物/<课名>_第N节课_课堂笔记.md` + 同名 `.html`（用 `md-to-reader-html` skill 转）+ `生成物/原始转写/`（按内容顺序拼成**一条全局时间轴**的逐字稿，注明各段原始文件名与对应时间范围）。
```

#### video-cursor-removal

- 来源: 自建
- 说明: 从视频中检测并移除鼠标光标（及伴随的波纹/光晕特效），输出去鼠标版本，保留音频。适用于 Kling/可灵、录屏、演示视频里误带鼠标指针需要抹除的场景。基于 opencv + numpy。
- 路径: `C:\Users\lenovo\.workbuddy\skills\video-cursor-removal\SKILL.md`

```markdown
# 视频去鼠标光标

## 适用场景
- 视频里带了鼠标箭头/指针，需要去掉（用户原话「把鼠标和相关特效去掉」）。
- 「特效」= 光标旁边的波纹/光晕，跟光标一起处理。
- 目标：移除光标、平滑修复背景、保留原音频、crf16 + yuv420p 不过度压缩。

## 环境（本机 · 2026-09-19 实测订正）
- **opencv 是装得上的**：`cv2 5.0.0` 已在
  `C:\Users\lenovo\.workbuddy\binaries\python\envs\default` 里（早期 SKILL 写的
  「opencv 装不上 → 纯 NumPy」**是错的**，已订正）。有 `cv2.matchTemplate` /
  `connectedComponentsWithStats` / `medianBlur` 就别手写 FFT-NCC 和 harmonic 填充。
- 该 venv 有 numpy/PIL/cv2；**没有** scipy / skimage / imageio / numba。
- ffmpeg：`C:\Users\lenovo\AppData\Roaming\bilibili\ffmpeg\ffmpeg.exe`（不在 PATH，无 ffprobe，用 `ffmpeg -i` 看时长）。
- Python：`C:\Users\lenovo\.workbuddy\binaries\python\envs\default\Scripts\python.exe`。

## Pipeline

### 1. 缓存灰度帧
`np.save(frames_gray.npy, 全部帧灰度)` → 后续多轮检测用 `mmap_mode="r"` 复用，
361 帧 1080p ≈ 750MB，可控。全片彩色别缓存（2.2GB 会爆）。

### 2. 定位光标：多模板 × 多尺度 全片 NCC
- 先用一张用户圈出的截图 / 一个已知帧裁出模板（实测 68×98）。
- **单一模板不够**：AI 生成视频里光标外观会形变。要从多个高置信帧各取一份模板
  （实测取 6~11 份），每份再配 `scales=(0.88,0.94,1.0,1.08)` 做
  `cv2.matchTemplate(..., TM_CCOEFF_NORMED)` 全片搜索，取全局最优。
- 单模板只有 ~10% 帧命中；多模板可到 **66%（238/361）**。
- 逐帧记录 `(score, x, y, scale, tpl_id)`。

### 3. 补全轨迹
- `score>=0.62` 视为可靠点。
- 对其余帧以上一可靠点为预测中心，在 ±320px 局部窗口内重搜，阈值 0.55 采纳；
  再做一遍反向传播，取更高分。
- 剩余空洞用最近邻填，置信度标 0.3。
- 输出 `pos.npy` = `(N,3)` 的 `(x, y, conf)`。**注意 matchTemplate 给的是左上角，
  光标中心要 +（w/2, h/2）**。

### 4. 擦除：时域为主，空间兜底
两种都遵循同一套「自适应差分软掩膜」套路：
1. 估背景 `bg`（见下）。
2. `diff = |gray_frame_patch - bg|`，`hi_q = quantile(diff, 0.97)`；
   `hi_q < 15`（时域）/ `< 18`（空间）→ 认为没东西，跳过。
3. `a = clip((diff - T1)/(T2 - T1), 0, 1)`，`T1=12/16`，`T2=max(30/38, hi_q)` 且封顶 70/80。
4. `a>0.5` 二值化 → `connectedComponentsWithStats` → **取质心离 patch 中心最近的
   连通域**（面积 ≥250，距离 <110/130px），别取最大的，否则会选中背景变化区。
5. 该 CC 膨胀 9×9 作锚点，乘回 `a`，再 `GaussianBlur(sigma≈4~5)` 羽化。
6. `patch = patch*(1-a) + bg*(a)`（彩色按通道广播）。

**时域 bg**：取 ±45 帧里「光标位置离当前 ≥70px」的邻居帧（最多抽 28 个）做
`np.median`。**关键**：必须按位置过滤邻居，否则邻居帧里也有光标，median 把光标
算进背景，diff≈0，永远擦不掉。
→ 若过滤后有效邻居 `nv >= 12` 才走时域；否则直接走空间。

**空间 bg**（鼠标长时间静止时用）：以光标中心取 `R=175` 的方形 patch，
`cv2.medianBlur(patch, 151)`。
**核必须大于光标尺寸**：68×98 的光标用 101 核时，窗口内光标占 65%，median 仍
等于光标 → 擦不掉；换 151 核（占 29%）才生效。

顺序：`nv>=12 ? (时域 || 空间) : (空间 || 时域)`。

### 5. 编码
```
ffmpeg -y -loglevel error -f rawvideo -pix_fmt bgr24 -s WxH -r 24 -i - -i SRC \
  -map 0:v -map 1:a -c:v libx264 -crf 16 -preset medium -pix_fmt yuv420p \
  -c:a aac -b:a 128k -shortest -movflags +faststart DST
```
Python 用 `subprocess.Popen(stdin=PIPE)` 逐帧 `write(frame.tobytes())`。

## 关键坑（必看）
- **ffmpeg stderr 必须重定向到文件，不能用 `subprocess.PIPE`**（最隐蔽的坑）：
  ffmpeg 每帧都往 stderr 写进度，64KB 管道缓冲写满 → ffmpeg 阻塞 → stdin 管道
  也满 → Python `write` 卡死。实测表现为「361 帧跑了 9 分钟才到第 40 帧」；
  改成文件后全程 **15 秒**。
- **滑动窗口别把帧吃光**：预读 `n+WIN` 帧时，主循环里不要再 `cap.read()`，
  否则末段 WIN 帧被预读消耗、主循环提前 break（实测只处理了 316/361）。
  正确写法：先 `while` 补读到 `min(N-1, n+WIN)`，再取 `buf[n-base]`，处理完再从
  头部丢帧。
- **静止段的「假成功」**：时域法在光标静止段仍能找到一个 diff 大的连通域（其实是
  背景变化），于是 `done=True` 跳过兜底，光标原样留下（verify 分数 0.99 纹丝不动）。
  必须用 `nv` 判断要不要走空间法。
- **死亡螺旋**：早期版本用「局部小窗 + 无恢复」跟踪，一旦跌破阈值就冻结在最后一帧，
  随后误锁 UI 文字 → 后半段真实光标完全没去掉。**改用每帧全幅 NCC + 反向传播**解决。
- **NCC 分数 float32 溢出**：用 float32 算平方和会溢出虚高；全部改 float64 / 或用 cv2。
- **PowerShell 吞 stdout**：日志一律写文件再 Read；bash 没有 `ls/head/tail/dirname`，
  改用 PowerShell + `Out-File`。
- **中文文件名经 PowerShell 会被写坏**（`生成物\红圈.jpg` → 乱码），中间产物一律
  用 ASCII 名放在 `_work/` 下；只有最终交付物才用中文名。
- **模型看不了图片**时，用 ASCII 字符画渲染 patch（`CH=" .:-=+*#%@"` +
  `cv2.resize` 到 ~54 宽）来判断形状，比纯数值靠谱得多。

## 验证（必须做，不能凭感觉）
对成品重跑一遍同样的多模板检测，统计分数分布：
- 原片：`max≈1.000`，`>=0.60` 的 238/361
- 成品：目标 `max` 明显下降、`>=0.80` 的帧数接近 0
- 实测三轮迭代：`0.997/26帧` → `0.961/4帧` → 继续降。
- 再抽 5 个已知光标帧，原片 vs 成品并排 ASCII 对比，肉眼确认箭头消失。

## 交付物
- 成品 mp4（同分辨率/帧率、音频保留、faststart）。
- 可选并排对比图 `compare_*.png`（原片/成品同帧 2 行）作视觉证明。
```

### 金融与数据

#### wb-finance-skill

- 来源: 内置/市场
- 说明: >-
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-wb-finance-skill\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `references/abnormal-detection.md`, `references/announcement-impact.md`, `references/breakout-patterns.md`, `references/business-model.md`, `references/crisis-event.md`, `references/crypto-derivatives.md`, `references/daily-briefing.md`, `references/dividend-buyback.md`, `references/earnings-preview.md`, `references/earnings-review.md`, `references/event-catalyst.md`

```markdown
## 触发顺序硬约束
- 必须**先**加载 wb-finance-skill 读取红线、时区口径、路由与输出规范，任何涉及金融市场数据的请求，**都要**优先使用用户已连接的金融类 MCP，其次调用 agentic_search 工具检索数据，以上两步都无法获取所需数据时才考虑使用 WebSearch 检索；**禁止跳过本 skill 直接裸答或者凭记忆回答。**

## 红线（金融场景一票否决）

- **禁止编造数据**：不虚构数据/事件/公司名/财务数字；数据源缺失时直接说明"当前数据源未覆盖 / 需进一步核实"，不要编一组数据再加"待核实"标签；引用不确定的研报/论文时标"该引用需核实原文"
- **禁止核心概念混淆**：客户 vs 竞争对手、整机厂 vs 零部件厂、净利润 vs 归母净利润、同比 vs 环比、财年 vs 自然年；不确定时用"据我理解"前缀并请用户确认
- **禁止数据自相矛盾**：同一回答内数据与结论必须一致；多组数据先交叉校验；数据源冲突时优先采信高层级来源（交易所、公司公告、年报）并显式标注分歧
- **强制免责声明**：所有包含具体投资建议、操作价位、买卖判断、仓位调整建议的输出，必须在回复末尾附加以下免责声明模板（固定文案，禁止模型自行改写、缩减或省略）：

  > **免责声明**：以上内容基于公开数据和量化分析，仅供参考，不构成投资建议。市场有风险，投资需谨慎。任何投资决策应结合个人风险承受能力、资金状况和投资目标独立判断，必要时咨询持牌专业机构。过往表现不预示未来收益。

## 检索策略
- **检索路由表（固定优先级，逐级降级，禁止跳级）**：

  | 优先级 | 数据源 | 何时使用 |
  |---|---|---|
  | 1 | 用户已连接的金融类 MCP | 默认首选；行情 / 财务 / 宏观 / 资金 / 公告等取数一律先走这一层 |
  | 2 | **agentic_search 工具** | 第 1 层未连接、未覆盖、报错或无结果时启用（含资讯 / 研报 / 新闻类检索） |
  | 3 | **WebSearch** | 前两层都拿不到所需数据时的公开信息兜底，必须标注媒体名 + 日期并说明非实时 |

- 降级必须逐级进行，并说明降级原因；**不得跳过第 1、2 层直接用 WebSearch**。
- **agentic_search 工具** —— 它**具备自主分析与多步规划能力**，会自行判断查哪些维度、分几步查，返回结论。
- **委派 query 必须是"一句话检索意图"，保留用户原始意图，禁止拆成多维度清单 / 字段列表 / 表格格式要求**。agentic_search 工具自身具备多步规划与自主检索能力，会自行拆维度、判断查哪些字段、查多深——你拆得越细、要求越"全"，它解锁的检索面越大、越发散、越慢。委派时**只交代两件事**：① 标的 / 主题 / 范围（带代码），② 大方向查什么；其余（查哪些字段、列几列、怎么排序、要不要表格、分几个维度）一律**不写**，也**不要要求agentic_search 工具写分析 / 结论报告 / 大段表格**——它只需返回结论。字段筛选、表格化、排序、深度分析都是拿回数据后**主 agent 自己的活**（见第 4/7 条），不是委派 query 的内容。
- **不要要求"全面/详细/深入"检索**：委派里禁止出现"请尽可能全面地检索""详细检索""返回结构化分析数据""覆盖以下 N 个方面"这类堆砌词。检索广度与深浅由agentic_search 工具按问题体量自己定，主 agent 说得越"全""细"它越发散、越慢，反而不利。就给它一句朴素的检索意图即可。
    - 反例（过度拆解，禁止）：用户问"列出场内基金里红利低波和红利自由现金流 ETF"，却委派"请查询 A 股场内 ETF 中红利低波、红利自由现金流两主题的所有相关 ETF，列出基金代码、简称、跟踪指数、管理人、最新规模、近一周/近一月/年初至今涨跌幅、管理费率+托管费率、成立日期，用表格分主题输出……"
    - 正例（一句话）："列出场内（A 股）红利低波、红利自由现金流两个主题的相关 ETF"
    - 反例：用户问"国内有哪些上市公司跟 SpaceX 相关"，却委派"请全面检索 A 股与 SpaceX 有业务关联的公司，覆盖直接供应商 / 产业链相关 / 对标概念 / 最新动态四个维度，列出名称、代码、关联逻辑、近期表现，区分实际业务与概念炒作……"
    - 正例："检索 A 股里与 SpaceX 相关的上市公司"
    - 反例（宽泛研究被拆维度 + 堆"全面"词，禁止）：用户问"银河电子怎么样"，却委派"全面分析 A 股银河电子（002519），需覆盖：1 主营业务 2 财务数据 3 估值 4 股价走势与资金流向 5 研报评级 6 近期公告 7 板块概念，请尽可能全面地检索并返回结构化分析数据"
    - 正例："研究 A 股银河电子（002519）的整体情况"
- 宽泛的"X 怎么样 / 值不值得看"只需一句话点明标的与代码，具体查什么、查多全由agentic_search 工具自己拆；只有用户问题本身就很具体、只问单一字段时（如"茅台最新 PE"）才如实精确转述。
- 前两层（金融类 MCP / agentic_search）都无法取得所需数据时，才用 WebSearch 检索公开信息，明确告知用户数据来源并说明非实时性。

## 数据底线

- **前提显式**：问操作类问题（买/卖/加仓/减仓/换股）时，先列前提（市场环境 + 用户风险偏好 + 资金量/期限），再给"条件 → 操作 → 风险提示"。前提缺失时主动追问而非直接给操作建议
- **检索优先于记忆**：提及具体股票/基金/指数/宏观指标时，优先使用用户已连接的金融类 MCP，其次使用 agentic_search；
- **禁止硬编码数据**：所有行情、财务、宏观和技术指标必须通过工具动态获取并标注来源和时点，禁止在回答中直接引用训练数据中的历史数值或凭记忆输出数字
- **时效意图与目标周期解析**：用户表达“最新、当前、今天、今年、近期”等时效要求时，先结合运行时日期、市场交易状态、指标发布频率和数据发布时间确定目标周期，不得把当前年份直接等同于最新有效数据周期。用户明确指定历史日期、年份、季度、财年或回测时点时，以用户指定范围为准，不得自动改写为当前周期。

- **查询结果时效校验**：数据返回后核对其统计周期、发布时间和数据截止时间是否满足用户要求：
  1. 数据已覆盖目标周期时，按实际周期使用并标注时点；
  2. 当前周期尚未发布时，使用最近已发布周期，并明确说明数据截止时间；
  3. 返回数据明显早于目标周期时，调整时间参数或更换数据源重新查询；
  4. 仍无法取得满足要求的数据时，明确声明数据缺口和最近可用时点，不得将历史数据表述为当前数据。
- **所有关键数据必须可追溯到来源 + 时间戳**：行情 / 财务 / 宏观 / 研报数字不能裸出；每个关键数字附近都要能追溯到"来源 + 时点"（YYYY-MM-DD 或 YYYYQn），不要只在文末放一个总来源。同一数据块共享相同来源、周期和口径时，可在表头、表尾或图注统一标注，来源或周期不同时，再分别标注。来源可来自 用户已连接的金融类 MCP / agentic_search / 交易所公告 / 公司年报 / 研报 / WebSearch；WebSearch 兜底时也要标媒体名 + 日期，若生成 HTML，最好把 WebSearch 原文链接做成可点击链接。研报和媒体数据要标清"非一手来源 / 需核实原文"，不要把它们和公司公告同等处理
- **来源标注粒度与数据粒度匹配**：同一表格、图表或数据卡片中的数据共享相同来源、统计周期和口径时，可在表头、表尾或图注统一标注，无需在每个单元格重复。只有不同子项来源、时点或计算口径不同时，才需要分别标注。任何关键结论都应能追溯到对应的数据来源和时点。
- **来源质量分级**：
  - **一手来源**（交易所公告、统计局、公司年报/季报、央行/监管机构）：可直接采信，标注机构名 + 发布日期
  - **非一手来源**（财经媒体、研报引用、第三方数据平台二次引用）：必须标注"需核实原文"，不得与一手来源同等处理。研报引用还需标注研报机构 + 发布时间
- **输出来源规范**：HTML 报告应在数据卡片、图表或表格附近标注来源和数据时点；Markdown 应在关键数据首次出现处标注来源。共享来源的数据可合并标注，避免重复信息影响可读性。

## 使用指南

1. **识别意图**：先分清这是"取数据"（→ "优先用户已连接的金融类 MCP" 其次委派 agentic_search 工具）还是"给方法论 / 分析 / 输出"（→ 读对应 reference、跑 scripts）；很多请求两者都要（先取数再分析）
2. **自主执行**：不要让用户挑数据源；数据源在哪、怎么路由由agentic_search 工具内部决定，主 agent 只管把检索意图讲清楚（委派规范见上方「检索策略」——一句话意图、不指定字段/表格/维度、不要求agentic_search 工具写分析报告）
3. **错误兜底**：工具返回缺失或报错时，换个问法再调用，或用用户其他已连接/已授权的 MCP / agentic_search / WebSearch 补
4. **清晰呈现**：用中文表头的可读表格展示返回结果。列举 / 排名 / 对比多个标的时，交付前过三道规整校验：
    - **每个标的必带标准格式代码**：A 股 6 位（600519）、港股 5 位（00700）、美股 ticker（AAPL），逐个标注、无一例外，不要只在第一个标的后给代码
    - **排序 / 分层必须给可量化依据**：给标的排序或分档时，写清排序所依据的具体指标（市占率 / 供应份额 / 营收占比 / 资金流入 / 增速 / 估值分位），不要用"绑定深度""市场地位""重要性"这类笼统词；确实拿不到量化指标时，说明这是定性排序，不要伪装成硬排名
    - **条件校验**：题目限定了范围（市场 A 股 / 港股 / 美股、上市状态、产品类型）时，逐个核对候选标的是否满足，剔除不符的；A 股清单里混入港股或未上市标的是硬错误
5. **按需组合**：复杂请求可多次委派agentic_search 工具互补（如先让agentic_search 工具选出股票池，再对池内标的逐只查详情），或在一次委派里把多步需求讲清让agentic_search 工具自主完成
6. **置信度分层**：高置信度直接断言；中等用"倾向于 / 大概率"；低用"不排除 / 有可能"。不要把所有可能性平铺让用户自选
7. **除非用户指定格式，结果尽可能用 HTML 可视化呈现**：分析、对比、研报型回答尽量产出 HTML 文件（用 `Write` 落地 HTML，对话里把文件路径告诉用户）；简短 Q&A、单数字查询、Yes-No 判断仍用 Markdown。HTML 用浅底深字研报风、首屏结论先行；数据图用 ECharts、关系拓扑图用 SVG/CSS、查阅型用表格。**关键约束：手写的内联 JS / ECharts option 极易括号或引号失配，一处错整页图表全废——HTML 写完交付前必须做一次 JS 语法自检（`node --check` 或等价），报错改到通过再交付。** 复杂图优先套用现成 option 骨架填 data，不要从零手敲嵌套结构。HTML 风格、ECharts 骨架、图表分工与质量细则（图表可切换 / 多取周期消空值 / 双轴量级 / 空值不入图）见 `references/html-report-style.md`，产出 HTML 前先读它。
8. **加载后必须匹配 reference**：进入本 skill 后，必须完成以下三步，**不要只读 SKILL.md 主文件就直接答**——主文件只讲红线和路由，具体方法论（步骤、阈值、避坑）都在对应 reference 里。

   **第一步：问题拆解为场景标签**
   把用户问题拆成一个或多个场景标签。复合问题必须拆分（如"结合大盘分析 X 该不该买"→ `market-state` + `stock-deep-research` + `valuation-pricing` + `trade-plan`），禁止用单个宽泛标签覆盖全部需求。

   **第二步：核心方法论加载**
   每个主场景必须加载对应的核心 reference；存在多个主场景时分别加载。核心 reference 加载完成后，根据问题中的具体维度追加补充 reference。Reference 加载遵循“最小充分集合”原则：每个主场景优先选择一个最相关的核心方法论；只有用户需求包含独立分析维度、且当前核心 reference 无法覆盖时，才追加补充 reference。不设置机械固定上限，但禁止为了完成清单无边界加载无关文件。判断依据是方法论是否实际用于分析，而不是读取文件数量。

   问题场景与核心必选 / 条件追加对照：

   | 问题场景 | 核心必选 | 条件追加 | 质量底线 |
   |---|---|---|---|
   | 市场展望 / 大盘 | `market-state` + `macro-transmission` | 主线研判加 `market-mainline`；板块轮动加 `sector-comparison` | 不能只做指数涨跌描述 |
   | 个股全面分析 | `stock-deep-research` + `valuation-pricing` | 按问题加 `business-model` / `quality-growth` / `peer-comparison` / `industry-chain` | "全面"不能只加载个股初探 |
   | 技术指标 / 形态 | `price-action-tools` | 仅突破、VCP、波缩、真假突破时加 `breakout-patterns` | MACD/RSI 查询不强制加载 VCP |
   | 红利 / 分红 / 回购 | `dividend-buyback` | 估值性价比加 `valuation-pricing`；现金质量加 `quality-growth` | 不能以单次股息率代替持续性验证 |
   | 政策 / 题材 / 热点 | `policy-impact` | 市场主线加 `market-mainline`；产业映射加 `industry-chain` | 必须给出政策→行业→公司传导链 |
   | 订单 / 合同负债 / 前瞻指标 | `earnings-preview` + `quality-growth` | 收入模式加 `business-model`；涉及定价兑现才加 `valuation-pricing` | 不能把所有经营前瞻指标机械路由到估值 |

   **第三步：自检（输出前必须通过）**
   - 每个主场景是否都有核心方法论 reference？
   - 数据源是否按「检索路由表」逐级选择（金融类 MCP → agentic_search → WebSearch），且降级原因合理？
   - 用户要求的关键分析维度是否均已覆盖？
   - 方法论是否实际体现在答案中，而不是只完成文件读取？
   - 每个关键数据是否能对应到来源、时点和口径；
     不同来源/周期的子项是否分别标注？
   - 是否包含具体买卖、价位或仓位建议；
     若包含，固定免责声明是否完整位于回复末尾？
   - 若存在缺失，继续补充、重新查询或明确缩小回答范围，
     禁止假装完成全面分析。

   `html-report-style.md` **只负责输出格式，必须在方法论匹配完成后加载，不能替代任何方法论 reference。** 禁止仅加载格式类、工具类或数据源类 reference 就直接输出分析结论。
9. **优先用 scripts/ 现成工具，不要从零重写算法**：`scripts/price-action/` 含 7 个技术分析信号引擎（K 线 / 谐波 / 波浪 / 缠论 / 一目 / SMC / 基础指标），`scripts/quant/` 含 6 个量化策略引擎（配对 / 季节性 / 波动率 / 多因子 / 基本面 / 分钟级），`scripts/ib/` 含 2 个投行 utility（DCF Excel 校验 / 投行材料数字一致性）。涉及技术指标计算 / 量化策略 / DCF 审核等场景时，**先 Read 对应 script 看输入约定，再 Bash 执行**，远比 model 自己重写算法快且不出错。具体工具清单见对应 reference 末尾的"可执行工具"section
10. **多角度深度挖掘（数据返回后必跑反思）**：拿到工具数据不是答题终点而是挖掘起点。每次数据返回后过 5 维，任一维度触发新线索 → 继续检索；五维都无增量才收尾。**不为凑深度硬造，但也不要拿到一条数据就收尾**
    - ① **纵向**再追一个"为什么"：查到"净利润下滑"→ 继续拆成本 / 收入结构
    - ② **横向**看上下游 / 竞对：查到"比亚迪毛利走低"→ 顺查赛力斯 / 理想看是不是行业性
    - ③ **时间**放到 3-5 年周期看分位：查到"PE 25×"→ 调 5 年 PE 带看历史分位是高是低
    - ④ **反面**找最薄弱假设：依赖"消费复苏"→ 主动查社零 / CPI 反驳信号
    - ⑤ **行动**给条件化决策：补"若 X 跌破 Y 则 ……"，让用户拿到可操作框架
11. **有观点 + 反向声音**：分析类回答必须给经过推演的判断（不是平铺 N 种可能让用户自选）；主动点出"市场普遍知道什么、还没充分定价什么"，必要时给反向声音（"这个加仓决定可能基于一个错误的归因 —— X 的上涨其实是 Y 引起的"），不要顺着用户思路一路点头

## 时间口径（跨时区/跨市场必查）

金融数据强时效，回答时遵守以下规则：

- **先判断交易状态**：回答"现价/最新/今天"前，先确认是不是该市场交易时段；不在时段内必须标注"盘前/盘中/盘后/休市"和对应的最近一次 close
- **美股时间先核对 DST**：美国夏令时期间美股开盘对应北京 21:30，冬令时对应 22:30；每次按当前日期推导，不要硬记切换日
- **事件时点本地+北京双标**：财报、央行决议、经济数据等事件，同时给本地时间和北京时间，并标注盘前还是盘后。例：苹果 FY25Q1 财报 = 2025-01-30 美东盘后 16:30（北京时间 2025-01-31 05:30）
- **相对时间默认北京时区**：用户说"今天/昨天/本周"按北京时间解释；有歧义时（如"昨天美股"）第一句先点明绝对日期
- **跨市场比较先对齐窗口**：A股 T 日收盘 / 港股 T 日收盘 / 美股 T-1 夜盘 / 美股 T 日盘 不是同一时点；做联动分析时点明用的是哪种对齐
- **跨市场财报同期对比按自然年季度对齐**：FY 标号本身不能直接对（如腾讯 FY26Q1 = 自然年 2026Q1，阿里 FY26Q1 = 自然年 2025Q2，对不上）。先把每家 FY 拆成它实际覆盖的自然年季度（腾讯 FY = 自然年；阿里 FY 4 月制；苹果 FY 9 月底制；微软 FY 7 月制），再按"自然年同季度"配对做季度比，或用 **TTM 滚动 4 季** 做年度比——TTM 本身就是按自然年季度滚动求和，自动消除 FY 定义差异。详细步骤与币种 / 估值口径一致性见 `references/peer-comparison.md` 与 `references/valuation-pricing.md`

## 数据口径与标的核对

- **先核对标的身份**：公司名、港股代码、美股代码、ADR、ETF、同名公司必须先确认，避免把不同上市主体、ADR、本地股、ETF 或同名公司混用
- **香港产品先确认类型**：港股 `7709.HK` 这类代码可能是 ETF、杠杆产品、牛熊证或结构化产品；查 NAV 前必须先确认产品类型。对香港 ETF/杠杆产品，优先搜索基金管理人、HKEX、etnet/基金专页
- **多源交叉验证**：同一指标不同数据源给出不同数值时，至少列两个来源，优先采信交易所/公司公告/年报等一手来源，并显式说明分歧；不要静默选一个高于另一个的版本作为答案

## 场景方法论 references

`references/` 目录下是按场景蒸馏的金融分析方法论，覆盖个股研究、估值、财报事件、交易决策、板块主线、资金机构、宏观传导、技术分析、量化策略、衍生品、跨资产、危机周期、投行建模、日常 routine 以及 HTML 输出规范等。**当用户的请求落入对应场景时，先读取相应 reference 再作答。**

**使用规则**：
- 每条 reference 是"方法论 + 量化阈值 + 避坑"三段式，不是输出模板——分析时按其框架思考，但**不照抄章节标题或字数限制**
- 多场景叠加时（如"分析 A 股票该不该买"同时涉及个股研究 + 估值 + 仓位决策），并行读取多个 reference 综合判断
- 方法论类 references 只管"分析框架"，**数据获取优先使用用户已连接的金融类 MCP，其次为agentic_search 工具**

**索引（按场景类别分组）**：

**个股研究**
- `stock-first-look.md` 个股初探（含热门股快读）
- `stock-deep-research.md` 个股深度研究（投资逻辑研究）
- `business-model.md` 业务模式拆解
- `valuation-pricing.md` 估值与定价（PE/PB/DCF/PEG/分部估值）
- `moat-quality.md` 护城河与公司质地
- `management-assessment.md` 管理层体检
- `peer-comparison.md` 同业比选
- `quality-growth.md` 质量增长匹配（高质复利 / 增长质检 / 价值股息）

**财报与事件**
- `earnings-preview.md` 财报前瞻
- `earnings-review.md` 财报后反应（业绩会提炼 / 财后漂移）
- `announcement-impact.md` 公告影响与股东信解读
- `event-catalyst.md` 事件驱动短线催化

**交易与持仓**
- `trade-plan.md` 交易计划与买卖点
- `position-sizing.md` 仓位决策与加减仓
- `portfolio-checkup.md` 持仓体检与风控
- `stop-discipline.md` 止损纪律
- `monitor-alert.md` 监控告警与停复牌

**板块主线题材**
- `sector-comparison.md` 板块比较与轮动
- `market-mainline.md` 市场主线与情绪
- `market-state.md` 市场状态与广度
- `theme-lifecycle.md` 题材周期与龙头
- `leader-game.md` 涨停龙头博弈与龙虎榜

**资金与机构**
- `fund-flow.md` 资金流与北向
- `institutional-holding.md` 机构持仓与拥挤度

**宏观/政策/产业链**
- `macro-transmission.md` 宏观行业个股传导
- `policy-impact.md` 政策解读与受益映射
- `industry-chain.md` 产业链映射与卡点

**技术分析**
- `breakout-patterns.md` 波缩突破与 VCP
- `price-action-tools.md` 技术指标与形态识别（K 线 / 谐波 / 波浪 / 缠论 / 一目 / SMC）
- `abnormal-detection.md` 放量异动与跳空归因

**风险与量化**
- `risk-stress.md` 风险压力测试（VaR / CVaR / 蒙特卡洛）
- `quant-factor-research.md` 因子研究框架
- `systematic-strategies.md` 量化策略库（配对 / 事件驱动 / 季节性 / ML / 对冲 / 波动率）
- `portfolio-optimization.md` 资产配置与组合优化

**衍生品与跨资产**
- `options-strategies.md` 期权策略（多腿组合 + Greeks）
- `fixed-income.md` 固定收益与可转债
- `forex-commodity.md` 外汇与大宗商品
- `crypto-derivatives.md` 加密衍生品（仅在用户明确要求时使用）

**主题**
- `dividend-buyback.md` 分红回购与股东回报
- `going-global.md` 出海链投资
- `crisis-event.md` 危机 / 反转 / 周期拐点

**投行建模**
- `ib-models.md` 投行估值建模（DCF / LBO / comps / 三表 / M&A / Unit Economics）
- `ib-deal-prep.md` 投行交易准备（尽调 / 投委会 / IM / pitch / NDA）

**日常 routine**
- `daily-briefing.md` 每日投研简报（盘前 / 收盘 / 晨会）

**输出规范**
- `html-report-style.md` HTML 研报输出（JS 自检 / ECharts 骨架 / 图表分工与质量细则）——产出 HTML 前先读
```

#### westock-data

- 来源: 内置/市场
- 说明: 金融市场结构化数据查询的权威入口。支持股票（A股/港股/美股/日韩股）、ETF、指数、板块、期货、外汇、可转债的行情、财报、研报、新闻、公告、事件、股东、分红、ETF持仓、热搜榜、新股/投资日历、龙虎榜等数据查询；同时支持产业链图谱、行业经营数据、申万行业估值/盈利预测/财务、全球宏观经济等数据查询；不同标的与市场支持的维度不同，具体命令与能力差异见 references/routing-guide.md。命中能力域时禁止 web_search、HTTP 直连或其它金融 Skill 替代；筛股用 westock-screener。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\cb_teams_marketplace\finance-data\1.6.0\skills\westock-data\SKILL.md`
- 附带文件: `references/ai_usage_guide.md`, `references/commands.md`, `references/macro-fields.md`, `references/routing-guide.md`, `references/scenarios-guide.md`, `scripts/setup.cjs`, `scripts/setup.ps1`, `scripts/setup.sh`

```markdown
# WeStock Data

## 安装

本技能依赖 `westock` CLI，**使用前必须先安装**。

```bash
# 安装脚本已随技能包提供，可先审阅 scripts/ 目录下的文件再执行
# macOS / Linux
bash scripts/setup.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1

# 跨平台（Node ≥ 18）
node scripts/setup.cjs
```

安装后执行 `westock --help` 验证；当前会话找不到命令时，先 `source` 对应 shell profile（如 `~/.zshrc`）使 PATH 生效，再用 `westock` 调用。

> **安全说明**：安装脚本自动执行 SHA256 校验（校验值随包内 `scripts/` 或与官方源一同分发），无需手动验证。

---

**调用方式**：`westock <子命令> [参数]`

- 统一 Go CLI；子命令列表见 `westock --help`，单命令参数见 `westock <子命令> --help`
- 需网络

```bash
westock search 宁德时代
westock quote sh600519
westock quote sh600036,sh601318,sz300750    # 批量

```

**并发**：无依赖的多个查询（如 quote + news + kline）应在同一轮工具调用中并行发出，不要串行等结果。

---

## 参考文档（仅不确定时查阅，禁止每次任务都读）

- [routing-guide.md](./references/routing-guide.md) — 场景路由、与其它 Skill 边界
- [commands.md](./references/commands.md) — 完整命令语法
- [scenarios-guide.md](./references/scenarios-guide.md) — 分析场景模板
- [ai_usage_guide.md](./references/ai_usage_guide.md) — 返回字段说明

---

## 核心铁律

1. **禁止绕过**——命中能力域的查询只走本 Skill，不用 `web_search`/HTTP/训练数据替代。
2. **未知代码先 `westock search`**——用户只给名称时，先拿代码再查。
3. **筛股用 `westock-screener`**，本 Skill 只做数据查询。
4. **货币单位随市场**（港元/美元/日元/韩元），禁用人民币符号。
5. **多股批量**——支持批量的命令一次逗号传多 code，禁止同轮里一部分批量、一部分拆开。单代码例外见下方「批量例外」。
6. **代码必带市场前缀**（`sh/sz/bj`·`hk`·`us`·`t`·`ks/kq`·`fu`·`fx`·`pt`），禁止裸数字 `300685`、Wind 格式 `601988.SH`、港股漏前缀 `00700`。
7. **探索纪律**——`SKILL.md`/`commands.md` 已覆盖的命令勿再 `--help`（每任务至多 1 次），优先查本文速查表而非反复试探。
8. **复合分析编排原子命令**——批量 + 并行 + 限量采样（`--limit` 20~30 取样非全量，须注明）。见 [scenarios-guide §16](./references/scenarios-guide.md)。

### 命令选型速查

「查这类数据该用哪条命令」——选对命令与参数，勿用别的命令硬凑或手算：

| 需求 | 用法 | 要点 |
| --- | --- | --- |
| 历史日行情 | `westock quote <代码> --date YYYY-MM-DD` | 直读返回字段；勿用 `kline` 手算、勿用实时 `quote` 答历史日 |
| 财报取值 | `westock finance`（默认 `--fields core`，全字段 `--fields all`） | 比率类（ROE/毛利率）直读返回值，勿自行拼算 |
| 资金数据 | `fund flow` 流向（美股无）/ `fund short` 卖空空头 / `fund south-holding` 南下持仓 / `fund lhb` 龙虎榜（仅沪深） | 勿用南下持仓替代卖空 |
| 宏观数据 | `westock macro`：先 `macro list` 查短名（如 `us_inflation`）再 `macro indicator` | 短名勿凭自然语言猜 |

### 参数命名约定

本 CLI 参数名与取值都用简短写法（如 `--limit 20`、`--period day`、`--type sector`），不要自创长参数或复数形式；**不确定某参数/取值，回 commands.md 该命令小节核对，不要猜**。

常见参数速查：

| 语义 | 参数与取值 | 适用命令 |
| --- | --- | --- |
| 周期 | `--period day\|week\|month\|season\|year` | `kline` / `technical` |
| 条数/期数 | `--limit N` | `kline` / `technical` / `finance`（期数）/ 排行·清单类 |
| 回溯年数 | `--years N` | `dividend` |
| 板块类型 | `--type sector`（概念/行业统一 `sector`，非 `concept`/`industry`/`all`） | `sector` 等 |
| 日期区间 | `--start` / `--end`（YYYY-MM-DD） | `fund flow` / `finance` 等支持历史区间的命令 |

- 代码 → 一律带市场前缀（见核心铁律「代码必带市场前缀」）。

### 输出与解析纪律

- **默认输出已是结构化 Markdown 表格**（含关键字段），直接读取分析，**禁止**用脚本/正则/Python 去解析命令的文本输出。
- **禁止终端截断**：不要用 `| grep` / `| head` / `| tail` / `| sed` 过滤输出，也不要用 `&&` / `;` 拼接多条命令；条数、分页、筛选只用**该子命令自己的参数**（不同命令支持的 flag 不同，禁止跨命令套用）。
- 返回字段含义见 [ai_usage_guide.md](./references/ai_usage_guide.md)，不确定字段含义再查阅，不要靠反复试错猜。

### search 规则

**默认仅搜股票**（`westock search <关键词>` = `--type stock`，只调 1 次接口）。不会自动查 ETF/板块/指数/期货/外汇。`--type` **支持逗号分隔多个类型同时搜**（如 `--type etf,index,sector`），一条命令按类型分组返回，优于依次盲试。

| 用户意图 | 命令 | 不要 |
|---------|------|------|
| 找股票代码（默认） | `westock search 宁德时代` | 不要无 `--type` 时再去试 etf/bond/index/sector |
| 找 ETF/基金 | `westock search 沪深300 --type etf` | 用户说了「ETF」就直接带 type，不要先默认再重试 |
| 找指数 | `westock search 中证红利 --type index` | |
| 找板块 | `westock search 银行 --type sector` | |
| 找可转债 | `westock search 兴业 --type bond` | |
| 找期货/外汇 | `westock search 黄金 --type futures` / `--type forex` | |
| 一次找多个类型 | `westock search 港股通创新药 --type etf,index,sector` | 不要拆成多次单类型命令依次盲试 |
| 日韩股 | `westock search 三星 --market kr` | `--market` 与 `--type` 互斥 |

**空结果时**：读 CLI 返回的提示，按用户原意**最多再试 1 种** `--type`（或 `--market`），不要对同一关键词依次扫 etf→bond→index→sector。**仍无结果则告知用户**，不要死磕。

**禁止**：对同一关键词连续换 3+ 种 `--type` 盲试（如需多类型，用 `--type a,b,c` 一次搞定）。

### 批量查询

多标的对比：代码用逗号写在**同一条命令**里（如 `westock finance sh600519,sz000651`），不要一股一条命令。

```bash
# 分析 sh600519 + sz000651 → 下面 6 条各 1 次（共 6 次），不是 12+ 次
westock quote sh600519,sz000651
westock kline sh600519,sz000651 --period day --limit 60
westock finance sh600519,sz000651 --limit 4
westock news list sh600519,sz000651 --limit 10
westock technical sh600519,sz000651
westock fund flow sh600519,sz000651

```

**批量例外**（不支持逗号多代码，须分开调；可同一轮并行发出）：

| 命令 | 限制 |
|------|------|
| `westock minute` / `westock search` | 不支持代码批量 |

无依赖的多种查询（上列各条）**同一轮并行发出**。完整限制见 [routing-guide.md §六/§九](./references/routing-guide.md#六能力差异速查标的--维度)。

---

## 高频命令速查

```bash
# 搜索
westock search 宁德时代
westock search 半导体 --type sector

# 行情 / K 线 / 财务 / 技术
westock quote sh600519
westock quote sh600519 --date 2026-07-03        # 指定历史日行情（涨跌幅/量比/收盘价等，见 ai_usage_guide）
westock kline sh600519 --period day --limit 20
westock finance sh600519,sz000651 --limit 1          # 多股三大表（默认 --fields core 核心窄表）
westock finance sh600519 --fields all                  # 全字段（100+ 列）
westock technical sh600519

# 新闻 / 研报 / 公告
westock news list sh600519 --limit 10
westock report list sh600519 --limit 5
westock notice list sh600519 --limit 10

# 板块 / 指数 / 宏观
westock sector constituent pt01801080          # 成份股
westock sector valuation pt01801080            # 估值 PE/PB/PS + 历史百分位
westock sector finance pt01801780               # 申万行业财报 TTM 聚合（仅申万行业，聚源概念不支持）
westock index constituent sh000300
westock macro indicator cn_core --date 2026-03-01

# 资金 / 北向
westock fund flow sh600519
westock fund north-holding sh600519
westock fund south-holding hk00700
westock fund north-holding pt01801080           # 仅申万行业，聚源概念板块不支持

# ETF / 发现
westock etf profile sh510300
westock hot stock                               # 热搜股；另有 hot news/sector/etf

```

完整语法见 [commands.md](./references/commands.md)。

---

## 异常与空结果

1. **命令失败**：如实转述，禁止编造数据。
2. **空结果**：说明「暂无数据」；区分代码不支持 vs 时点无披露（必要时先 `westock search`）。
3. **能力不支持**：如实告知（如美股无 `westock fund flow`），见 [routing-guide.md §六](./references/routing-guide.md#六能力差异速查标的--维度)。
4. **禁止**：失败后改用 `web_search` 或凭训练数据补数。

---

## 重要声明

> 本技能仅提供客观市场数据查询，不构成投资建议。数据可能有延迟，以交易所官方为准。投资有风险，决策需谨慎。

**数据来源**：腾讯自选股数据接口
```

#### westock-tool

- 来源: 内置/市场
- 说明: 选股 / 选基工具——按条件、策略、标签、事件、排行从全市场批量筛选股票或 ETF。当用户问"找一只 / 哪些股票 / 帮我选 / 推荐 / 排行榜 / TOP / 筛选 / MACD金叉 / 央企股 / ST股 / 高股息ETF"时使用。提供 filter（自定义条件）、strategy（预置策略）、label（标签/ETF主题）、event（事件触发）、ranking（排行，支持在板块/标签/策略/事件结果内二次排序）等入口。本技能只做"批量筛选"；查单只标的详细数据用 westock-data。
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\cb_teams_marketplace\finance-data\1.6.0\skills\westock-tool\SKILL.md`
- 附带文件: `package.json`, `references/ai_usage_guide.md`, `references/etf-pools.md`, `references/fields-guide.md`, `references/ranking-indicators.md`, `references/scenarios-guide.md`, `scripts/index.js`

```markdown
# WeStock Tool

**作用**：提供五种选股 / 选基方式——条件选股（自定义表达式筛选）、策略选股（预置策略一键获取信号股票）、标签选股 / 选基（股票分类标签 + ETF 主题池）、事件选股（按预定义事件类型筛选触发股票）、**排行选股 / 选基**（按涨跌停/财务/评分/两融/资金流入等指标对股票排序，或按规模/估值/行情/换手/溢折率等对 ETF 排序，支持在板块/标签/策略/事件结果内做二次排序）。

> ⚠️ **本工具内 6 个子命令的路由原则**：
> - **`filter` 表达式**：用户描述**自定义条件**（如"PE<20且ROE>15"）
> - **`filter --preset`**：用户需要**条件型预设筛选**（如"低PE股"、"高股息股"）
> - **`strategy`**：用户提到**策略信号**（如"MACD金叉"、"巴菲特策略"）
> - **`label`**：用户提到**分类标签**（如"央企"、"ST股"、"新股"、"破净股"；ETF 加 `--asset etf`：高股息 ETF/千亿基金/科创占比高）
>   - ⚠️ **"央企" vs "国企"**：央企用 `shareholder_central_state`；用户口语说"国企"通常指**地方国企**，用 `shareholder_local_state`（详见下方「标签选股」章节术语澄清）
> - **`event`**：用户提到**事件+时间窗口下的"哪些股票"**（如"近期有哪些股票限售解禁"、"哪些公司发布了回购公告"、"董监高增持的股票"）
>   - ❌ event 返回的是**触发该事件的股票列表（用于选股）**，不是事件本身的公告/新闻原文。如需事件资讯/公告原文，请用 `westock-data news/notice`。
> - **`ranking`**：用户提到**按指标排序、最多/最少、TOP/榜单**——典型口语：
>   - "今天两融减仓最多的" → `ranking margin_chg_d --asc`
>   - "评分 TOP 10" → `ranking CompScore --limit 10`
>   - "涨停封单量最大" → `ranking limit_up_seal_amount`
>   - "央企里评分最高" → `ranking CompScore --label 央企`
>   - "MACD 金叉中估值最低" → `ranking PE_TTM --strategy MACD金叉 --asc`
>   - "ETF 规模榜/涨幅榜/估值最低" → **必须** `ranking <指标> --asset etf`（**禁止** 用 `westock-data quote` 拉一堆代码再排序，也**不要**误用 `hot etf`——后者是热搜榜不是规模/估值榜）
> - **❌ 概念股查询不属于本工具**：用 `westock-data search <关键词> --type sector`

---

## 🔴 与 westock-data 的事件/榜单边界（高频误判）

> 下列场景**优先用本 Skill（westock-tool）**——westock-data 的同名相邻命令是**另一回事**，不要替代：
>
> | 用户问 | ✅ 用 westock-tool | ❌ 不要用 westock-data | 区别 |
> | --- | --- | --- | --- |
> | "限售解禁的股票"/"近 N 月解禁" | `event shareunlock_next_90` / `shareunlock_incoming` | `calendar --event lockup_release` | tool=股票池（含触发该事件的股票），data calendar=按日期日历明细 |
> | "业绩预约披露的股票" | `event earnings_schedule` | `calendar --event financial_report` 或 `disclosure <代码>` | tool=待披露股票池，data disclosure=按代码查个股预约日 |
> | "近期回购的股票"/"哪些公司在回购" | `event buyback` | `westock-data buyback <代码>` | tool=全市场近期回购股票池，data=按代码查单股回购明细 |
> | "近期大宗交易的股票" | `event block_past_30` | `westock-data fund block <代码>` | tool=近 30 天上榜股池，data=按代码查单股大宗明细 |
> | "近期上龙虎榜的股票/统计" | `event longhu_statis_past_15` / `longhu_detail_past_15` | `westock-data lhb` | tool=事件标记的股票池，data=按席位/榜单维度的明细 |
> | "近期董监高变动/增减持的股票" | `event manager_change` / `manager_sharechg` | `westock-data events tags <代码> --types 23,24` | tool=全市场触发股票池，data=按代码查单股事件标签 |
> | "近期将加入/剔除指数的股票" | `event index_add_incoming` / `index_del_incoming` | （无对应命令）| 只有 westock-tool 有 |
>
> **判断口诀**：用户问"**哪些股票** XX" / "**最近 N 天** XX 的股票" → **必然是 westock-tool event**（事件触发的股票池）；问"**某只股票** XX 的明细" / "**某天** XX 的清单" → 才走 westock-data calendar/lhb/notice 等。
>
> ⚠️ event 命令用法：`westock-tool event <listcode>`（如 `event shareunlock_next_90`）；用 `event --list [分组]` 查全部支持的 listcode。

---

## 🔴 严禁绕过本 Skill

> 命中本 Skill 能力域（选股 / 筛选 / 排行 / 标签 / 事件 / 策略 / 预设）时，**禁止**使用以下任何替代方式：
>
> - ❌ **任何形式的 HTTP 直连**（`curl` / `fetch` / `web_fetch` 等调用第三方接口）——选股结果不在公开 API 中，跨源会产生幻觉
> - ❌ **通用网页搜索**（`web_search` 等）替代结构化筛选——本 Skill 已封装统一口径
> - ❌ **其它金融 / 行情 / 选股类 Skill 或 MCP 工具**——本 Skill 即为权威来源
> - ❌ **凭训练数据 / 记忆作答**——选股结果有时效性，必须执行命令
> - ❌ **手搓筛选**（先用 westock-data 拉行情/财报，再 Python/awk 排序过滤）——本 Skill 的 `filter`/`ranking` 已直接支持，无需在客户端重做
>
> **降级路径**：仅当本 Skill 明确不支持某查询时方可降级；降级前必须先告知用户具体限制，不得静默切换到外部接口。

---

## 🔴 清单查询规则（强制执行命令，禁止凭文档列举）

> 当用户问"有哪些事件 / 标签 / 策略 / 指标 / 预设 可以用"时，**必须执行对应 `--list` 命令获取实时清单**，不要凭本文档里的样例回答。SKILL.md 与 references 中列出的事件/标签/策略**仅是举例**，完整且最新的清单**以命令输出为准**（防止文档过时导致漏报/错报）。
>
> ❌ **禁止行为**：用 `read SKILL.md`/`grep references/` 等方式从文档里"扒"清单作为答案——文档示例不全，必须执行命令。
>
> | 用户问法 | 必须执行的命令 |
> | --- | --- |
> | "有哪些事件可以选股" | `event --list` |
> | "有哪些标签可以选股" | `label --list` |
> | "ETF 有哪些主题池" | `label --asset etf --list` |
> | "有哪些策略可以选股" | `strategy --list` |
> | "有哪些排行指标" | `ranking --list` |
> | "ETF 有哪些排行指标" | `ranking --list --asset etf` |
> | "filter 有哪些预设"/"有哪些预设函数"/"低 PE 这种预设" | `filter --list-presets` |
>
> ⚠️ **`filter --list-presets` vs `strategy --list` 易混**：
> - **预设 / preset / 预设函数 / filter 函数** → `filter --list-presets`（输出"条件型预设"，如 `LowPE`/`HighDividend`/`MACDGolden`/`PB_LFLow` 等带阈值参数的复合条件）
> - **策略 / strategy / 信号 / 大师策略 / 形态** → `strategy --list`（输出"策略信号"，如 `macd_golden`/`buffet`/`morning_star` 等预定义策略代码）
> - 两者输出**不可互换**：用户带"预设"二字 → 必须用 `filter --list-presets`，**不要**改跑 `strategy --list`

## 🔴 区间 / 分页查询规则

> | 用户问法 | 必须使用的参数 |
> | --- | --- |
> | "最近一周/一月有哪些 X 变化"、"X 名单变化" | **`--start <起始> --end <结束>`**（区间查询，单日 `--date` × 多次手动比对是反模式） |
> | "看下一页"、"第二页"、"再多查一些"  | 用上一次输出末尾提示的 `next offset` 作为 `--offset`；不要凭印象拼接 |
> | "近 N 个交易日"、"近 N 天" | 命令支持 `--start/--end` 时**优先用区间**，避免循环单日查 |

**数据源**：腾讯自选股选股数据接口 | **条件选股**：A股、港股、美股 | **策略/标签/事件/排行（股票）**：仅A股 | **ETF 选基（label/ranking --asset etf）**：沪深 ETF（约 1530 只）

---

## ⚙️ 命令调用约定

> 下文示例统一写作 `westock-tool <命令>`，这是**逻辑命令名**，并非可执行程序。实际执行规则如下：
>
> - **执行方式**：`node <本SKILL.md所在目录>/scripts/index.js <命令> [参数]`（`<本SKILL.md所在目录>` 按实际环境解析为本文件所在目录）
> - **禁止**：硬编码任何具体安装路径（如 `~/.openclaw/skills/...`、`/usr/local/...` 等），各运行环境目录不同
> - **环境**：Node.js ≥ v18，脚本已单文件打包，无需 `npm install`

---

## 已知限制速查

| 限制项 | 说明 |
|--------|------|
| 市场覆盖 | 沪深A股、港股、美股；**不支持北交所** |
| 港股/美股字段名 | 估值字段名与沪深不同（见下方字段速查），**切勿混用** |
| PE/PB 负值 | 亏损股 PE/PB 为负，筛选时必须排除负值，如 `PE_TTM > 0` |
| 预设函数市场 | 港股必须加 `--market hk`，美股必须加 `--market us` |
| 多条件AND | **必须使用 `intersect([...])`**，不支持 `&`/`&&`/`AND` |

### ⚠️ 常见错误

| 错误写法 | 正确写法 |
|---------|---------|
| `PE_TTM < 20 & ROE_TTM > 15` | `intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])` |
| `PE_TTM < 20 AND ROETTM > 15` | `intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])` |

---

## 条件选股（filter）

```bash
# 单条件 / AND / OR
westock-tool filter "ClosePrice >= 100"
westock-tool filter "intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])"
westock-tool filter "union([ChangePCT > 5, Chg5D > 10])"

# 排序 / 港股 / 美股 / 板块限定
westock-tool filter "intersect([PE_TTM > 0, PE_TTM < 15, ROETTM > 15])" --orderby ROETTM --desc
westock-tool filter "intersect([PeTTM > 0, PeTTM < 10, DivTTM > 5])" --market hk
westock-tool filter "intersect([PeTTM > 0, PeTTM < 30, TotalMV > 1000])" --market us
westock-tool filter "intersect([PE_TTM > 0, PE_TTM < 20])" --universe 11010001 --limit 20

# 预设函数（条件型预设：估值/技术/财务/资金/机构/组合 6 大类 20+ 函数）
westock-tool filter --preset LowPE --limit 30
westock-tool filter --preset HighDividend --market hk
westock-tool filter --list-presets                        # 查看所有预设函数名
```

**表达式语法**：

| 语法 | 说明 |
|------|------|
| `字段 比较符 值` | 单条件，如 `ClosePrice >= 100` |
| `intersect([条件1, 条件2, ...])` | **AND 组合（必须使用，不支持 `&`/`&&`/`AND`）** |
| `union([条件1, 条件2, ...])` | OR 组合 |

**主要参数**：`--date`（日期）、`--limit`（默认 20）、`--orderby <字段> [--asc|--desc]`（排序，默认降序；兼容旧写法 `--orderby <字段:asc|desc>`）、`--market hk|us`、`--universe <板块代码>`、`--raw`（输出严格 JSON 而非 Markdown 表格，**所有命令通用**）。

> **`filter --preset` 与 `strategy` 的边界**：filter --preset 是**条件型**预设（输出含指标列的表格）；strategy 是**策略信号型**预置（输出仅含 code/name 的表格）。
>
> **预设函数完整列表（含默认参数）+ 表达式语法详解**参见 [references/ai_usage_guide.md](./references/ai_usage_guide.md)

### 同义需求 → 推荐命令对照

| 用户表述 | 推荐命令 | 说明 |
|---------|---------|-----|
| "低估值股有哪些" / "破净股" | `label valuation_lowpb` / `label valuation_negpe` | 静态分类，无需阈值 |
| "PE<20 且 ROE>15 的股" | `filter "intersect([PE_TTM>0, PE_TTM<20, ROETTM>15])"` | 自定义阈值 |
| "低 PE TOP 30" | `filter --preset LowPE --limit 30` | 参数化预设 |
| "估值最低的 10 只" | `ranking fin_valuation --limit 10` | 排行榜（升序） |
| "MACD金叉" / "巴菲特股" | `strategy macd_golden` / `strategy buffet` | 策略信号 |
| "MACD金叉里估值最低的" | `ranking fin_valuation --within-strategy macd_golden` | 范围限定 + 排序 |
| "新股有哪些" / "次新股" | `label listeddate_5days` / `label listeddate_3mons` | 上市时间标签 |
| "近期限售解禁" | `event shareunlock_next_90` | 事件 + 时间窗口 |
| "央企里评分最高" | `ranking CompScore --within-label shareholder_central_state` | 范围限定 + 排序 |

---

## 策略选股（strategy）

```bash
westock-tool strategy --list                                          # 查看所有可用策略
westock-tool strategy macd_golden                                     # 单策略
westock-tool strategy macd_golden --date 2026-04-10                   # 指定日期
westock-tool strategy high_dividend,pb_roe                            # 多策略并查
westock-tool strategy macd_golden --start 2026-04-01 --end 2026-04-10 # 区间趋势（⚠️ 多天必须用 --start/--end）
westock-tool strategy buffet --limit 10 --offset 20                   # 分页
```

**主要参数**：策略名（必填，逗号分隔多个）、`--date` / `--start` / `--end`、`--limit` / `--offset`、`--list`。支持直接传入任意 listcode，新增策略无需更新工具代码。

**可用策略概览**（仅展示代表性条目，**完整且最新清单必须执行 `strategy --list`**）：

| 分类 | 代表性策略 |
|------|----------|
| 基本面 | `high_dividend`(高股息)、`pb_roe`(高盈利价值)、`profit_preannounce`(业绩预增) |
| 大师策略 | `buffet`(价值龙头)、`graham`(格雷厄姆)、`fisher`(费雪) |
| K线形态 | `morning_star`(早晨之星)、`red_three_solider`(红三兵) |
| 指标信号 | `macd_golden`(MACD金叉)、`kdj_golden`(KDJ金叉)、`rsi_oversold`(RSI超卖) |
| 均线/布林 | `ma_long`(均线多头发散)、`boll_bt_upper`(布林带上轨突破) |
| 资金面 | `major_force`(主力抢筹)、`institution_chasing`(机构接盘) |

> **完整策略列表参见** [references/ai_usage_guide.md](./references/ai_usage_guide.md)「六、策略选股完整列表」

---

## 排行选股（ranking）

> 当用户问"评分TOP10"、"连续涨停的股票"、"估值排行"、"央企里评分最高的10只"、"MACD金叉中估值最低的"、"两融加仓最多"、"主力净流入榜"等**按指标排序**问题时使用。

统一的"按指标排序选股"入口，支持 **5 类指标源**（评分 / 涨跌停 / 财务 / 两融 / 资金流入），核心特色是可在板块、标签、策略、事件结果内做**二次排序**。

```bash
# 查看所有可用指标
westock-tool ranking --list
westock-tool ranking --list 评分                          # 按分类筛选

# 高频示例（每族举 1~2 个，完整指标见 references/ranking-indicators.md）
westock-tool ranking CompScore --limit 10                 # 综合评分 TOP10（单只评分用 westock-data score）
westock-tool ranking limitup_days                         # 连续涨停天数
westock-tool ranking fin_valuation --limit 10             # 估值排行
westock-tool ranking margin_chg_d                         # 两融日加仓榜（--asc 看日减仓榜）
westock-tool ranking cap_main_5d                          # 主力 5 日合计净流入榜

# 范围限定（核心能力）：央企里 / MACD 金叉中 / 解禁股内 / 板块内 二次排序
westock-tool ranking CompScore --within-label shareholder_central_state    # 央企里评分最高
westock-tool ranking fin_valuation --within-strategy macd_golden           # MACD金叉中估值最低
westock-tool ranking CompScore --within-event shareunlock_next_90          # 限售解禁股评分
westock-tool ranking fin_valuation --universe 11010001                     # 板块内估值排行

# 阈值筛选 / 升序 / 历史 / 分页
westock-tool ranking margin_in_days --min-MtInDays 5       # 两融连续扩大≥5天
westock-tool ranking CompScore --asc                       # 评分最低
westock-tool ranking CompScore --date 2026-04-20           # 历史日期
westock-tool ranking limitup_days --limit 50 --offset 20
```

**主要参数**：指标名（必填）、`--type cur|weekly|monthly`（仅 score）、`--within-label|--within-strategy|--within-event`（**三者互斥**）、`--universe <板块>`、`--min-<字段> 值`、`--asc`、`--date`、`--limit` / `--offset`、`--list [分组]`。

> ⚠️ **阈值筛选用 `--min-<字段>`，不要用 `--limit` 替代**——用户问"评分>70 的股票"→ `--min-CompScore 70`；`--limit 50` 是结果条数，不是阈值，两者**业务不等价**（断言会判错）。`--min-<字段>` 的字段名与指标代码不一致，必须查 [references/ranking-indicators.md](./references/ranking-indicators.md) 对照表。

**可用指标分类（举例）**：

| 分类 | 代表性指标代码 |
|------|---------|
| 评分 | `CompScore` / `CapScore` / `FunmScore` / `RiskScore` / `TecScore` |
| 涨跌停 | `limitup_days` / `limitup_seal_volume` / `limitdn_days` / `limitdn_seal_volume` |
| 财务排行 | `fin_valuation` / `fin_growth` / `fin_profit` / `fin_pershare` / `fin_operation` ... |
| 两融排行 | `margin_balance` / `margin_chg_d/w/m/q/y` / `margin_in_days` / `margin_out_days` |
| 资金流入 | `cap_main_net` / `cap_retail_net` / `cap_main_5d` / `cap_in_days` / `cap_out_days` |

> ⚠️ **`--min-<字段>` 字段名与指标代码不一致**（如 `cap_main_5d` 对应 `--min-MainSum5d`），必须查表，不要凭印象拼。
>
> **完整指标清单 + `--min-<字段>` 完整对照表 + 各指标族命令样例**参见 [references/ranking-indicators.md](./references/ranking-indicators.md)

---

## 事件选股（event）

> 当用户问"近期有哪些股票限售解禁"、"董监高增减持的股票"、"近期回购的股票"、"业绩预约一月内披露"、"将加入沪深300的股票"、"近期大宗交易"等**事件 + 时间窗口**问题时使用。
> **`event` vs `label`**：label 是**静态分类**（央企永远是央企），event 是**动态时间窗口**（"限售解禁"随时间变化）。
>
> ⚠️ **常见误用提示**：
> - "业绩预约披露/财报预约" → `event earnings_schedule`（**不是** `westock-data calendar` 也**不是** `westock-data disclosure`；后者按代码查个股的预约日历，event 才是按事件筛选股票池）
> - "近期回购/正在回购" → `event buyback`（**不要** 用 `curl fin-search/web_search` 抓新闻）
> - "近期大宗交易/龙虎榜统计" → `event block_past_30` / `event longhu_statis_past_15`

```bash
westock-tool event --list                                  # 查看所有可用事件
westock-tool event --list 董监高变动                        # 按分组筛选
westock-tool event shareunlock_next_90                     # 单事件
westock-tool event manager_change,manager_sharechg         # 多事件并查（不做交集）
westock-tool event block_past_30 --limit 50 --offset 20    # 分页
```

**主要参数**：事件名（必填，逗号分隔多个）、`--limit` / `--offset`、`--list [分组]`。支持任意 listcode 字符串。

> ⚠️ **`event --list [分组]` 直接传分组名**，` `--list` 后接分组名（如 `event --list 董监高变动`），**不要**先 `events list` 全量再人工筛！分组名用 `event --list` 查（无参数时返回全部分组清单）。

**可用事件概览**（仅展示代表性条目，**完整且最新清单必须执行 `event --list`**）：

| 分类 | 代表性事件 |
|------|----------|
| 分红 | `dividend_plan`(预案)/`dividend_exdiv`(除权) |
| 业绩 | `earnings_schedule`(预约披露)/`earnings_forecast`(预告)/`earnings_release`(披露) |
| 定增 | `seo_past_7`(前一周)/`seo_next_30`(后一月) |
| 董监高变动 | `manager_change`(变动)/`manager_sharechg`(增减持)/`manager_shareplan_sell_incoming`(计划减持) |
| 限售解禁 | `shareunlock_next_90`(预计三月内)/`shareunlock_incoming`(实际解禁) |
| 回购 | `buyback` |
| 交易异动 | `block_past_30`(大宗交易)/`longhu_statis_past_15`(龙虎榜统计) |
| 指数变动 | `index_add_incoming`(将加入)/`index_del_incoming`(将踢出) |
| 重大事项 | `merger_unclosed`(吸收合并)/`regroup_unclosed`(资产重组) |

> **完整事件列表参见** [references/ai_usage_guide.md](./references/ai_usage_guide.md)「八、事件选股完整列表」

---

## 标签选股（label）

> 当用户问"央企有哪些"、"ST股"、"新股"、"次新股"、"破净股"、"高ROE股"等**分类标签**问题时使用

```bash
westock-tool label --list                                  # 查看所有可用标签
westock-tool label --list 股东属性                          # 按分组筛选
westock-tool label shareholder_central_state               # 单标签
westock-tool label valuation_lowpb,fin_high_roettm         # 多标签并查（不做交集）
westock-tool label risk_st --limit 50 --offset 20          # 分页
westock-tool label shareholder_central_state --start 2026-04-01 --end 2026-04-10  # 区间（多天必须用）
```

**主要参数**：标签名（必填，逗号分隔多个）、`--date` / `--start` / `--end`、`--limit` / `--offset`、`--list [分组]`。支持任意 listcode。

**可用标签概览**（仅展示代表性条目，**完整且最新清单必须执行 `label --list`**）：

| 分类 | 代表性标签 |
|------|----------|
| 股东属性 | `shareholder_central_state`(**央企**=中央国资委直属)/`shareholder_local_state`(**地方国企**)/`shareholder_private`(民企)/`shareholder_qfii`(含外资)/`shareholder_hkfund`(陆股通) |
| 风险标签 | `risk_st`(ST股)/`risk_broken_ipo`(破发股) |
| 估值水平 | `valuation_lowpb`(破净股)/`valuation_negpe`(亏损股) |
| 财务特征 | `fin_high_roettm`(高ROE)/`fin_forecast_inc`(业绩预增)/`fin_healthy_growth`(降本增效) |
| 上市时间 | `listeddate_5days`(新股5日内)/`listeddate_3mons`(近端次新) |
| 价格与市值 | `price_up1000`(千元股)/`marketcap_super_big`(超大盘)/`marketcap_super_small`(超小盘) |

> ⚠️ **"央企" vs "国企" 术语澄清**：
> - 用户问 **"央企"** → `shareholder_central_state`（仅中央国资委/财政部等中央层面控股）
> - 用户问 **"地方国企"** → `shareholder_local_state`
> - 用户问 **"国企"**（口语广义）→ **默认用 `shareholder_local_state`**（后端命名为「国企公司」，特指地方国企）；如用户明确想看央企+地方国企全量，可用多标签：`label shareholder_central_state,shareholder_local_state`

> **完整标签列表参见** [references/ai_usage_guide.md](./references/ai_usage_guide.md)，或用 `westock-tool label --list` 实时查看

---

## ETF 选基（label/ranking --asset etf）

> 当用户问"高股息 ETF 有哪些"、"千亿规模基金"、"科创板占比高的 ETF"、"ETF 规模榜"、"近 20 日涨幅最高的 ETF"等**ETF 发现/排行**问题时使用。
> ETF 选基复用 `label`（标签筛选）和 `ranking`（按指标排序）两个命令，通过 `--asset etf` 切换作用对象——与 `--market hk/us` 切换市场的设计模式一致。
> 与 `westock-data etf detail/holdings/...`（按代码精查）形成"先发现后精查"链路。

```bash
# 标签筛选（复用 label）
westock-tool label --asset etf --list                          # 列出全部 KYP 主题池
westock-tool label --asset etf --list 行情表现                  # 按分组筛选
westock-tool label high_dividend --asset etf                   # 高股息 ETF
westock-tool label low_valuation,high_roe --asset etf          # 多池并查
westock-tool label size_100 --asset etf --limit 50 --offset 50 # 百亿基金分页

# 横截面排行（复用 ranking）
westock-tool ranking --asset etf --list                        # 列出全部 ETF 排行指标
westock-tool ranking size --asset etf --limit 20               # 规模榜 TOP20（默认 TotalAsset 降序）
westock-tool ranking valuation --asset etf --orderby PB --asc       # 估值最低（按 PB 升序）
westock-tool ranking valuation_pct --asset etf --orderby PE_TTM_PCT # 估值百分位最低（默认升序）
westock-tool ranking qt_chg_interval --asset etf --orderby ChgPct20D # 近 20 日涨幅榜
westock-tool ranking turn_interval --asset etf --orderby EtfTurnoverRAvgM # 月均换手率榜
westock-tool ranking disc_interval --asset etf --orderby EtfDiscAvgW # 周均溢价榜
```

### ETF 主题池速查（高频代表性条目）

> ⚠️ **完整且最新清单**必须执行 `label --asset etf --list`；下方仅列代表性条目。

| 高频分类 | 代表性池 |
|------|----------|
| 规模 | `size_1000`(千亿)、`size_500`、`size_100`(百亿) |
| 基本面 | `low_valuation`(低估值)、`high_dividend`(高股息)、`high_roe` |
| 行情表现 | `qt_high_chg`(高涨幅)、`qt_high_vol`、`qt_high_amp` |
| 持仓特征 | `high_stib_bj`(科创北证占比高)、`high_minicap`(微盘占比高) |
| 主力资金 | `cap_focus_daily/weekly/monthly/quarterly/yearly`(主力看好) |
| 类型/策略 | `commodity`(商品型)、`bond`(债券型)、`currency`(货币型)、`strategy_div`(红利) |

### ETF 排行指标速查（高频代表性条目）

> ⚠️ **完整且最新清单**必须执行 `ranking --list --asset etf`；下方仅列代表性条目。

| 指标 | 中文 | 默认排序字段 ↓↑ |
|------|------|-----------|
| `size` | ETF 规模 | `TotalAsset` ↓ |
| `valuation` | 估值绝对值 | `PE_TTM` ↑ |
| `valuation_pct` | 估值历史百分位 | `PE_TTM_PCT` ↑ |
| `qt_daily` | 单日行情 | `ChgPct` ↓ |
| `qt_chg_interval` | 区间涨跌 | `ChgPct20D` ↓ |

> **完整 ETF 主题池表 + 排行指标可选字段表 + 命令样例**参见 [references/etf-pools.md](./references/etf-pools.md)

**主要参数**：池名/指标名（必填）、`--asset etf`（必填，切换为 ETF 维度）、`--orderby <字段>`（仅 ranking）、`--asc`（覆盖默认方向）、`--date`、`--limit` / `--offset`、`--list`。

> **决策入口**：
> - 用户带"标签/主题"（如"高股息 / 千亿基金 / 科创板占比高"）→ `label ... --asset etf`
> - 用户带"排序/榜单"（如"规模最大 / 涨幅前 10 / 估值最低"）→ `ranking ... --asset etf`
> - 跨市场行情/单只 ETF 详情 → 改用 `westock-data etf detail/holdings/...`

---

## 股票代码格式

| 市场 | 格式 | 示例 |
|------|------|------|
| 沪市/科创板 | sh + 6位数字 | `sh600519`、`sh688981` |
| 深市 | sz + 6位数字 | `sz000001` |
| 港股 | hk + 5位数字 | `hk00700` |
| 美股 | us + 代码 | `usAAPL` |

---

## 常用字段速查（跨市场差异）

> ⚠️ **沪深和港美的估值字段名不同，切勿混用**——常见对照：
> - 市盈率 TTM：沪深 `PE_TTM` / 港美 `PeTTM`
> - 市净率：沪深 `PB` / 港美 `PbLF`
> - 股息率 TTM：沪深 `DividendRatioTTM` / 港美 `DivTTM`
> - ROE TTM：沪深 `ROETTM` / 港股 `RoeWeighted` / 美股 `ROE`
> - 收盘价/涨跌幅/总市值：三市场同名（`ClosePrice` / `ChangePCT` / `TotalMV`）
>
> 港股 `PsTTM`/`PcfTTM` 仅选股查询支持，快照查询返回 0。
>
> **完整字段速查表（含行情、财务、技术指标、ETF 等全部字段）参见** [references/fields-guide.md](./references/fields-guide.md)

---

## 使用规范

- ✅ 使用 `westock-tool` CLI 命令执行选股查询，输出 Markdown 表格，AI 直接从表格读取数据
- ✅ 查询结果应转为表格或可读格式展示，禁止直接输出原始 JSON
- ❌ 不创建临时脚本文件，不将数据分析逻辑写成独立脚本
- ⚠️ **港股必须指定 `--market hk`，美股必须指定 `--market us`**
- ⚠️ 筛选 PE/PB 时排除负值：`intersect([PE_TTM > 0, PE_TTM < 20])`
- ⚠️ 沪深和港股/美股的估值字段名不同，切勿混用

---

## 常见场景速查

```
【命令选择】
- 策略名称（MACD金叉、巴菲特等）→ strategy
- 分类标签（央企、ST股、新股、破净股等）→ label
- 事件时间窗口（限售解禁、业绩预约、回购、大宗交易等）→ event
- 自定义条件（PE<20且ROE>15）→ filter 表达式
- 预设函数（低估值、高股息等）→ filter --preset
- 按指标排序（评分/涨跌停/财务/两融/资金流入）→ ranking
- 组合查询（X 里的 Y 最高）→ ranking --within-*
- ETF 主题/榜单 → label / ranking 加 --asset etf

【高频典型示例（每类 1~2 个，更多见各章节）】
westock-tool strategy macd_golden                                          # 策略
westock-tool label shareholder_central_state                               # 标签
westock-tool event earnings_schedule                                       # 事件
westock-tool ranking CompScore --limit 10                                  # 排行（评分）
westock-tool ranking CompScore --within-label shareholder_central_state    # 排行 × 范围限定
westock-tool filter "intersect([PE_TTM>0, PE_TTM<15, ROETTM>15])" --orderby ROETTM --desc   # 自定义条件
westock-tool filter --preset HighDividend --market hk                      # 港股预设
westock-tool label high_dividend --asset etf                               # ETF 标签
westock-tool ranking size --asset etf --limit 20                           # ETF 排行

【区间 / 分页（用于"变化对比"和"翻页"场景）】
westock-tool label shareholder_central_state --start 2026-04-01 --end 2026-04-07  # 名单变化（单日 --date × 多次比对是反模式）
westock-tool strategy macd_golden --start 2026-04-01 --end 2026-04-07             # 策略每天命中变化
westock-tool label marketcap_super_big --limit 50 --offset 50                     # 第二页（offset 取上一页末尾提示）
```

> **更多场景示例参见** [references/scenarios-guide.md](./references/scenarios-guide.md)
> **详细返回格式、分析模板、选股场景详解参见** [references/ai_usage_guide.md](./references/ai_usage_guide.md)
>
> **检索提示**（ai_usage_guide.md 较大，按需 grep 定位）：
> - 查某类完整清单 → 搜章节标题：`## 六、`（策略）、`## 七、`（标签）、`## 八、`（事件）、`## 九、`（排行指标）；ETF 搜 `--asset etf`
> - 查某个条目 → 直接搜短名（如 `macd_golden` / `shareholder_central_state` / `shareunlock_next_90` / `qt_chg_interval`）
> - 查字段对照 → 搜 `--min-` 或字段名（如 `MainSum5d`）

---

## 数据更新频率

| 数据类型 | 更新频率 |
|----------|----------|
| 条件选股 | 每日收盘后更新 |
| 策略选股 | 每日收盘后更新 |
| 标签选股 | 跟随财报/公告等基础数据更新 |
| 事件选股 | 跟随公告/事件等基础数据更新 |
| 排行选股（涨跌停指标） | 盘中实时更新 |
| 排行选股（财务/评分指标） | 每日收盘后更新 |
| 排行选股（两融指标） | 每日收盘后更新（两融余额T+1披露） |
| 排行选股（资金流入指标） | 盘中实时更新（基于逐笔成交） |

---

## 重要声明

> ⚠️ **重要声明**：
>
> 1. 本技能仅提供客观市场数据的筛选与展示服务，不含任何主观分析、投资评级或交易建议。
> 2. 本技能不构成证券投资咨询服务，使用本技能获取的数据不应作为投资决策的唯一依据。
> 3. 数据可能存在延迟，请以交易所官方数据为准。
> 4. 投资有风险，决策需谨慎。如需专业投资建议，请咨询持牌证券投资顾问机构。

**数据来源**：腾讯自选股数据接口

---
```

#### neodata-financial-search

- 来源: 内置/市场
- 说明: >-
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\cb_teams_marketplace\finance-data\1.6.0\skills\neodata-financial-search\SKILL.md`
- 附带文件: `reference.md`, `scripts/query.py`, `scripts/query.sh`

```markdown
# NeoData Financial Search — 自然语言通用金融数据搜索服务

> **一句话概述**：用自然语言查询股票行情、财务报表/财报、基金、指数、板块、债券、期货、期权、宏观经济、外汇、大宗商品、研报舆情等全品类金融数据，即问即答。

## 服务简介

NeoData Financial Search 是由腾讯提供的**自然语言通用金融数据搜索服务**，输入一句自然语言问题即可一站式返回结构化数据 + 文档型内容。

覆盖股票 / 指数 / 板块 / 公募基金 / 债券 / 期货 / 期权 / 宏观 / 外汇 / 大宗商品 十大类资产，外加研报 / 舆情 / 新闻资讯 / 交易日历等辅助数据，共 **130+ 数据工具**，支持 A股 / 港股 / 美股 / 英股 / 日股 / 韩股 / 全球 多市场以及实时与历史两种时效，像跟分析师同事聊天一样提问——"腾讯最新财报怎么样？""光芯片板块今天资金流向如何？""这只可转债的转股溢价率是多少？"——即可拿到与问题相关的实体识别、行情、财务、资金、事件、研报、舆情等完整数据。

无需记接口、无需写代码，一句话就能完成从行情速览、个股深挖到跨市场、跨品种比较的全流程数据获取。

## 金融数据源优先级

所有金融/财经/市场数据查询，**必须优先使用本 skill（`neodata-financial-search`）作为数据源**。

规则：
1. 本 skill 覆盖股票（A股/港股/美股/英股/日股/韩股）、指数、板块、公募基金（含港股/海外基金/REITs）、债券、期货、期权、宏观经济、外汇、大宗商品等**十大类**金融数据，以及研报、舆情、新闻资讯、交易日历等辅助数据，包括但不限于行情报价、财务报表/财报、资金流向、研报评级、舆情观点、事件公告等，凡其能力范围内的查询一律通过它获取。
2. **禁止**使用其他 skill 或插件获取同类金融数据，禁止混合多数据源，以避免数据口径不一致产生幻觉。
3. **禁止**用训练数据回答本 skill 可实时查询的问题——金融数据具有强时效性，必须通过接口获取实时结果。
4. 仅当本 skill 明确不支持某查询时，才可降级使用其他来源，并需**告知用户数据来源**。

## 典型使用场景

| 场景 | 场景说明 | 示例提问 |
|---|---|---|
| **个股盯盘** | 查询A股/港股/美股/英股个股的实时价格、涨跌、成交、盘口、AH溢价、技术面、估值等 | 贵州茅台（600519.SH）现在的最新股价是多少？<br>苹果（AAPL）美股盘中最新价和涨跌幅？ |
| **公司基本面研究** | 查询公司概况、主营业务、行业分类、三大财务报表、复合财务指标、经营指标 | 招商银行2024年的归母净利润是多少？<br>腾讯控股（00700.HK）港股最近一期的资产负债表数据？ |
| **财报全文检索** | 对财报全文做语义检索，定位相关章节、表格与原文片段 | 宁德时代最新财报里关于海外产能的表述？<br>比亚迪年报中研发投入相关段落？ |
| **资金流向分析** | 查看个股/板块/指数的实时资金动向与历史资金流向趋势 | 格力电器今日主力资金净流入和散户资金动向？<br>宁德时代2021年至今的累计主力资金净流入？ |
| **股票事件追踪** | 监控公告、业绩发布会、股权变动、分红回购、风险监管等公司大事项 | 贵州茅台近期的分红送配方案？<br>腾讯控股近一年的港股回购明细？ |
| **板块行情/热点分析** | 查询板块成分股、ETF、实时行情、资金排行、异动、估值、热点驱动原因 | 今日人工智能板块为什么涨？驱动原因？<br>白酒板块的龙头股有哪些？ |
| **指数与大盘观察** | 查询A股/港股/美股/全球指数行情、成分权重、行业分布、估值、财务、盈利预测、资金流 | 上证指数当前的PE估值百分位和估值区间？<br>沪深300最新成分股权重前十？ |
| **基金研究与筛选** | 查询基金基本信息、净值、业绩、回撤、盈亏概率、持仓、规模、分红、跟踪指数 | 招商中证白酒指数A（161725）2024年第四季度的业绩表现？<br>近1年股票型基金收益排名前10？ |
| **基金财报分析** | 查询基金资产负债表、现金流量表（REITs）、利润表、财务指标 | 某公募基金最近半年报的资产负债表？<br>某只公募REITs的经营现金流情况？ |
| **港股/海外基金** | 查询香港互认基金、港交所ETF/L&I、美股海外基金（ETF/ETN/ETC）的行情、净值、业绩、费率、持仓 | 某只香港互认基金的费率和近一年业绩？<br>某只美股ETF的每日净值和行情？ |
| **基金公司/基金经理画像** | 查询基金管理人公司、基金经理履历与在管产品 | 基金经理张坤的从业经历、在管基金和管理规模？<br>易方达基金公司的整体情况？ |
| **机构观点/投研分析** | 查询公司/行业/宏观研报、机构评级目标价、盈利预测、盈利能力行业对比 | 贵州茅台近期券商评级、目标价和盈利预测？<br>光伏行业最新研报的供需与竞争格局分析？ |
| **舆情/社媒观点** | 查询微信公众号、小红书、视频号等渠道的财经观点、市场舆情与热点解读 | 市场对英伟达最新财报的社媒讨论热点？<br>近期关于AI算力的KOL观点？ |
| **财经新闻资讯** | 查询股票/指数/板块/基金/宏观相关的财经新闻、实时异动与市场快讯 | 今天A股有哪些重要财经快讯？<br>关于降准的最新新闻？ |
| **港股专项数据** | 查询港股卖空比例、沪深港通持股比例、回购等港股特色数据 | 福莱特玻璃（06865.HK）最近5个交易日的港股卖空比例？<br>腾讯控股截至最新的港股通持股数量和比例？ |
| **A股专项数据** | 查询A股龙虎榜、融资融券、转融通、大宗交易、质押式回购、IPO、供应链等A股特色数据 | 凯美特气近5日融资余额变化和两融数据？<br>某公司的主要供应商和客户有哪些？ |
| **沪深港通/互联互通** | 查询沪深港通个券持股、卖空、交易流向、行业资金、交易统计与额度、标的资格 | 今日北向资金净买入前十的行业？<br>某股票是否为沪深港通标的？ |
| **债券查询** | 查询一般债/可转债行情、估值、收益率曲线、现金流付息、档案、发行承销、信用评级、债券指数 | 某只可转债的转股溢价率和双低指标？<br>10年期国债收益率曲线的最新水平？ |
| **期货查询** | 查询境内商品/金融期货历史行情、会员持仓成交排名、仓单交割、合约品种，及海外/港股股指期货实时行情 | 螺纹钢主力合约的历史行情？<br>CBOT大豆期货的实时行情和成交数据？ |
| **期权查询** | 查询期权合约行情、希腊字母、交易持仓统计、合约信息、品种规则、业务与盘前参数 | 50ETF期权某合约的最新行情和希腊字母？<br>某期权品种的合约单位和行权方式？ |
| **优先股查询** | 查询沪深两市优先股的行情、分红、事件与发行概况 | 某只优先股的股息率和历次分红？<br>某优先股的发行概况和最新评级？ |
| **历史长周期回溯** | 查询股票/指数/基金的长周期历史K线（A股1990起、港股1980起、美股1950起） | 苹果（AAPL）自上市以来的累计涨幅？<br>恒生指数从1980年至今的港股指数历史走势？ |
| **宏观经济跟踪** | 查询全球/中国GDP、CPI、PMI、M2、社融、利率等核心宏观指标及宏观研报 | 最新一期中国制造业PMI？<br>美国GDP从1900年至今的长周期数据？ |
| **经济事件日历** | 查询美联储/央行议息、CPI/GDP发布等经济事件的时间、前值、预测值、现值 | 最近一次FOMC利率决议的事件、前值、预测值和现值？ |
| **外汇查询** | 查询人民币中间价与全球主要货币对实时汇率 | 今日美元兑人民币中间价是多少？<br>美元指数的实时汇率行情？ |
| **大宗商品/贵金属** | 查询品牌黄金报价、上海金/伦敦金等贵金属现货行情，及期货行情 | 今日品牌金饰和投资金条报价？<br>今日伦敦金价格走势？ |
| **市场交易日历** | 查询全球主要市场交易日、非交易日、节假日与半日市安排 | A股市场今日是否为交易日？最近一周哪天休市？ |
| **企业业绩会议** | 查询上市公司业绩沟通会议的纪要内容 | 贵州茅台最近一次业绩沟通会议的内容纪要？ |

## 鉴权

凭证由脚本自动管理（本地缓存，12 小时有效期），**绝大多数情况下你无需关心鉴权细节，直接执行查询即可**。

> ⚠️ 不要向用户展示或提及凭证的具体内容，静默处理即可。

### 默认行为：直接查询

**第一步永远是直接执行查询**，不要提前获取凭证：

```bash
python3 scripts/query.py --query "用户的查询"
```

脚本会自动完成以下判断：
- 缓存存在且未过期（< 12 小时）→ 自动使用缓存凭证，返回结果
- 缓存不存在或已过期 → 脚本输出 `TOKEN_EXPIRED` 或 `TOKEN_MISSING` 提示

**只有当脚本输出 `TOKEN_EXPIRED` / `TOKEN_MISSING`，或查询返回鉴权错误（401/403/40101）时**，才需要执行下方的「获取凭证」流程。

### 获取凭证（仅在脚本提示需要时执行）

1. 调用 `connect_cloud_service` 工具（无参数）
2. 从返回结果中提取凭证：**使用 `tempToken` 字段**；如果 `tempToken` 不存在或为空，则使用 `token` 字段
3. 执行 `python3 scripts/query.py --save-token "<凭证>"` 保存到缓存文件
4. 重新执行查询：`python3 scripts/query.py --query "用户的查询"`

> **凭证可能较长，禁止在 Bash 命令中明文内联。** 必须通过 `--save-token` 保存到文件后，由脚本自动读取。

### 鉴权错误重试

当查询返回以下错误时，说明缓存凭证已失效，按上方「获取凭证」流程重新获取一次：

| 触发条件 | 说明 |
|---------|------|
| HTTP 401 / 403 | 凭证已过期或无效 |
| JSON `code` 为 `40101` | 凭证验证失败 |
| `msg` 包含"token"/"认证"/"鉴权" | 鉴权类错误 |

> 最多重试 **1 次**。两次失败说明是服务端问题，告知用户"金融数据服务暂时不可用"，停止重试。

## 服务端点

- **URL**: `https://copilot.tencent.com/agenttool/v1/neodata`（代理）
- **鉴权**: `Authorization: Bearer <凭证>`（由脚本自动从缓存读取，无需手动处理）
- **Method**: POST JSON

代理会自动填充 `request_id` 等字段；`channel` 固定为 `neodata`，`sub_channel` 固定为 `workbuddy`，客户端必须显式传入这两个字段。

## 调用方式

> 优先使用 Python 脚本，仅当 Python 不可用时使用 Shell 脚本（curl 封装）。

> **跨平台说明（Windows / macOS / Linux）**：
> - Python 脚本不强依赖第三方库——缺少 `requests` 时会自动尝试安装修复，安装失败则退化到标准库 `urllib`，因此任意 Python 3.7+ 环境均可直接运行。
> - 文档示例用 `python3`；若所在环境无 `python3` 命令（部分 Windows），改用 `python` 或 WorkBuddy 内置 Python 执行即可，脚本逻辑一致。
> - Shell 脚本会自动探测可用的 Python（`python3`→`python`→`py`）。

**完整调用流程**：
```
1. python3 scripts/query.py --query "用户的查询"
   - 成功 → 返回结果，结束 ✅
   - 输出 TOKEN_EXPIRED / TOKEN_MISSING → 继续 Step 2
   - 鉴权失败（401/403）→ 继续 Step 2
2. 调用 connect_cloud_service → 提取 tempToken（优先）或 token（兜底）
3. python3 scripts/query.py --save-token "<凭证>"
4. python3 scripts/query.py --query "用户的查询"
5. 若仍失败 → 告知用户服务不可用，停止
```

> ⚠️ **永远先执行 Step 1**，不要跳过直接去获取凭证。缓存有效时 Step 1 就会直接返回结果。

**Python（推荐）**：
```bash
# 直接查询，脚本自动处理缓存凭证（12 小时有效期）
# 默认行为：不传 --data-type，等价于 data_type=all（同时召回结构化API与文章），覆盖面最广，强烈推荐
python3 scripts/query.py --query "腾讯最新财报"
python3 scripts/query.py --query "贵州茅台股价"
python3 scripts/query.py --query "黄金价格"

# 仅当明确判断查询是"纯结构化数据需求"且不需要任何资讯文章时，才显式使用 --data-type api
# 仅当查询明确就是"找新闻/研报/公告"时，才显式使用 --data-type doc
# 其他所有情况一律不传，避免因过早收窄数据通路导致召回为空

# 保存凭证（仅当脚本提示 TOKEN_EXPIRED/TOKEN_MISSING 时才需要）
python3 scripts/query.py --save-token "<凭证>"
```

**Shell（备选）**：
```bash
bash scripts/query.sh "腾讯最新财报"
bash scripts/query.sh "贵州茅台股价"

# 保存凭证
bash scripts/query.sh --save-token "<凭证>"
```

## 请求参数

客户端请求体必须提供以下字段：

| 字段 | 必填 | 说明 |
|------|------|------|
| `query` | 是 | 自然语言查询，如"腾讯最新财报" |
| `channel` | 是 | 渠道信息，固定值 `neodata` |
| `sub_channel` | 是 | 子渠道信息，固定值 `workbuddy` |
| `data_type` | 否 | 默认不传，等价于 `all`（API + 文章一并召回）。**强烈建议默认不传**，仅在明确单一意图时才指定 `api` / `doc`。 |

> **`data_type` 使用纪律（重要）**
>
> 1. **默认不传**：绝大多数自然语言金融查询都应不传 `data_type`，让服务同时尝试结构化 API 召回与文档型召回，最大化命中率。
> 2. **`api`（仅结构化数据）**：仅在用户明确只要数字/表格（如"贵州茅台最新收盘价是多少"、"招行 2024 年净利润数字"），且**绝不接受**资讯/研报文章作为答案时使用。
> 3. **`doc`（仅文章）**：仅在用户明确就是要"新闻 / 公告 / 研报 / 解读 / 原因分析"型答案时使用（如"今天为什么涨"、"最新一篇关于 6G 的研报"）。
> 4. **禁止**：不要为了"减少返回体积"而默认加 `--data-type api`——历史数据表明此用法会让约 20–40% 本可被文章召回兜底的 query 变成空结果。

## 响应结构概览

成功时 `code` 为 `"200"`，`suc` 为 `true`，核心数据在 `data` 中：

- **`data.apiData`** - 结构化 API 召回结果
  - `entity` - 命中标的列表（股票代码与名称）
  - `apiRecall` - API 内容块列表，每块含 `type`、`desc`、`content`
- **`data.docData`** - 金融类文本召回结果（财经资讯、券商研报、公司公告等）
  - `docRecall` - 文档召回分组，每组含 `extQuery` 和 `docList`

## 错误码

| code | msg | 说明 |
|------|-----|------|
| `1001` | 未命中意图 | 未识别到可处理的业务意图 |
| `1616039101` | 参数值不合法 | 入参校验失败 |
| `1006` | 查询解析拒答 | 策略拦截、风险或不支持场景 |

## 数据覆盖范围

覆盖十大类金融数据：股票（A股/港股/美股/英股/日股/韩股）、指数、板块、公募基金（含港股/海外基金/REITs）、债券、期货、期权、宏观经济、外汇、大宗商品，以及研报、舆情观点、财经新闻、交易日历等辅助数据；包括行情报价、财务报表/财报、资金流向、研报评级、舆情观点、事件公告等。

详细的数据服务目录和完整的出入参字段说明见 [reference.md](reference.md)。
```

### 设计与媒体制作

#### 3D模型与视频特效

- 来源: 内置/市场
- 说明: >
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-buddy-multimodal-generation\5.5.6-wb.38337834.g5f969292.h4918b5ced607\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `.orphaned_at`, `scripts/buddy-cloud.py`

```markdown
# 3D模型与视频特效技能

通过云端服务生成多模态内容，包括 3D 模型生成，以及基于模板的图片视频特效。

> **⚠️ 本技能不处理以下任务（已迁移至内置工具）：**
> - **文生图 / 图生图 / 图片编辑 / 风格转换** → 使用 `ImageGen` 工具（通过 ToolSearch 发现后用 DeferExecuteTool 调用）
> - **文生视频 / 图生视频** → 使用 `VideoGen` 工具（通过 ToolSearch 发现后用 DeferExecuteTool 调用）
>
> 如果用户请求的是上述 4 类任务，**必须停止执行本技能**，改为引导模型使用对应工具。

## 能力概览

| 能力 | 命令 | 说明 |
|------|------|------|
| 视频特效 | `buddy-cloud.py video-fx` | 基于模板的图片转视频特效（支持多图） |
| 3D 模型生成 | `buddy-cloud.py 3d` | 文生3D / 图生3D（异步轮询） |

> 所有能力统一使用 `connect_cloud_service` 认证，详见下方[认证流程](#认证流程)。

---

## 1. 视频特效

将静态图片转化为动态视频片段，基于预设特效模板驱动人物或物体产生动作、变身、互动等效果。目前支持 60+ 个模板，覆盖人物互动、变装变身、物理特效、风格转换等多种类型。

**调用示例：**

```bash
# 单图特效
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py video-fx --template return2dust --image "https://example.com/photo.jpg" --token-stdin

# 多图特效（双人互动）
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py video-fx --template hug --image "https://example.com/face1.jpg" --image "https://example.com/face2.jpg" --token-stdin
```

**示例用法：**
- 上传一张人像，应用"万物归尘"让人物化作粒子消散（单图：`--image URL`）
- 上传两张人脸照片，应用"亲吻"生成双人互动视频（多图：`--image URL1 --image URL2`）
- 上传一张全身照，应用"变身机甲"将人物改造为未来战士

**部分模板一览（template 取值）：**

| 类型 | 模板名 | template |
|------|--------|----------|
| 人物互动 | 拥抱 / 亲吻 / 比心 / 公主抱 / 脸颊贴贴 | `hug` / `kissing` / `hearting` / `bridalcarry` / `cheeks` |
| 变装变身 | 变身机甲 / 变身美人鱼 / 埃及变装 / 毕业啦 / 赛博朋克 | `futuresoldier` / `mermaidme` / `egyptme` / `graduation` / `cyber` |
| 物理特效 | 万物归尘 / 飞走了 / 被拽走了 / 面对疾风 / 膨胀 | `return2dust` / `balloonfly` / `dragme` / `windonface` / `morphlab` |
| 风格转换 | 动漫视频 / 卡通视频 / 3D手办风 / 毛茸茸 | `animelive` / `cartoonlive` / `3dfigure` / `fuzzy` |
| 趣味互动 | 吃我一拖鞋 / 倒头就是睡 / 被骷髅抓走了 / 捏脸 | `shoehit` / `napme` / `atomy` / `facepinch` |

完整模板列表见[官方文档](https://cloud.tencent.com/document/product/1616/119194)。

---

## 2. 3D 模型生成

基于腾讯混元大模型，将文本描述或图片生成高精度 3D 模型。支持文生3D、图生3D、多视角生3D、白模（Geometry）、草图生3D。

### 调用方式

```bash
# 文生3D
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d "文本描述" --token-stdin

# 图生3D
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d --image-url "https://example.com/image.jpg" --token-stdin
```

### 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `prompt` | positional | — | 文本描述，中文推荐，≤1024 字符（与 `--image-url` / `--image-base64` 三选一） |
| `--image-url` | string | — | 图片 URL，分辨率 128~5000px，≤8MB |
| `--image-base64` | string | — | 图片 Base64，分辨率 128~5000px，≤6MB |
| `--multi-view` | JSON | — | 多视角图片，格式：`[{"ViewType":"back","ViewImageUrl":"..."}]`。视角可选：left/right/back/top/bottom/left_front/right_front |
| `--model` | string | `3.1` | 模型版本（3.0/3.1），3.1 不支持 LowPoly |
| `--enable-pbr` | flag | off | 开启 PBR 材质生成 |
| `--face-count` | int | 500000 | 面数，范围 10000~1500000 |
| `--generate-type` | string | `Normal` | `Normal` / `LowPoly` / `Geometry`（白模）/ `Sketch`（草图） |
| `--polygon-type` | string | `triangle` | 仅 LowPoly 有效：`triangle` / `quadrilateral` |
| `--result-format` | string | obj+glb | 额外输出格式：`STL` / `USDZ` / `FBX` |
| `--no-poll` | flag | off | 仅提交任务，不等待结果，返回 JobId |

### 典型示例

```bash
# 文生3D + PBR 材质
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d "Q 版风格的古代灯笼，镂空雕花，内部有温暖的火焰光晕" --enable-pbr --token-stdin

# LowPoly 模式
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d "低多边形风格的山间小屋" --generate-type LowPoly --model 3.0 --token-stdin

# 白模（无纹理）
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d "人形机甲" --generate-type Geometry --token-stdin

# 仅提交（不等待），之后用 status 查询
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py 3d "一座城堡" --no-poll --token-stdin
echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py status <job_id> --type 3d --token-stdin
```

### 输出示例

```json
{
  "job_id": "job-xxxxxxxxxxxx",
  "status": "success",
  "result_files": [
    { "type": "glb", "url": "https://...xxx.glb", "preview_image_url": "https://...xxx.png" },
    { "type": "obj", "url": "https://...xxx.obj" }
  ]
}
```

> **注意**：3D 生成通常需要 1~5 分钟。

---

## Agent 执行规范

### 平台与路径规则（必须遵守）

> **⚠️ Windows WorkBuddy Desktop 必须使用安装包解包目录 `app.asar.unpacked`。禁止猜测或使用 `app.asar/resources/...` 路径。**

1. **macOS / Linux**：使用通用写法 `python3 <SKILL_DIR>/scripts/buddy-cloud.py ...`，不要改成 Windows 路径。
2. **Windows WorkBuddy Desktop**：如果需要显式拼接脚本路径，必须使用：
   ```text
   %LOCALAPPDATA%\Programs\WorkBuddy\resources\app.asar.unpacked\resources\plugins\workbuddy-builtin\skills\buddy-multimodal-generation\scripts\buddy-cloud.py
   ```
   或等价的正斜杠路径：
   ```text
   C:/Users/<user>/AppData/Local/Programs/WorkBuddy/resources/app.asar.unpacked/resources/plugins/workbuddy-builtin/skills/buddy-multimodal-generation/scripts/buddy-cloud.py
   ```
3. **Windows 上优先使用 Bash 工具执行 Python 命令**。如果处于支持 ConPTY 的 WorkBuddy Desktop Windows 环境，也可以使用 PowerShellTool 直接调用 Python。示例：
   ```bash
   echo -n "<token>" | python3 "C:/Users/<user>/AppData/Local/Programs/WorkBuddy/resources/app.asar.unpacked/resources/plugins/workbuddy-builtin/skills/buddy-multimodal-generation/scripts/buddy-cloud.py" video "prompt" --token-stdin
   ```
4. **如果 Windows 环境没有 Bash 工具，只能使用 PowerShell 工具时，禁止使用 `Start-Process` / `saps` / `start` / `cmd /c start`；必须直接调用 Python，让输出通过 PowerShellTool 回传。示例：**
   ```powershell
   "<token>" | & "python.exe" -u "C:/Users/<user>/AppData/Local/Programs/WorkBuddy/resources/app.asar.unpacked/resources/plugins/workbuddy-builtin/skills/buddy-multimodal-generation/scripts/buddy-cloud.py" video "prompt" --token-stdin
   ```
5. **禁止路径**：以下路径在安装包中不存在，绝对不要使用：
   ```text
   C:/Users/<user>/AppData/Local/Programs/WorkBuddy/resources/app.asar/resources/plugins/workbuddy-builtin/skills/buddy-multimodal-generation/scripts/buddy-cloud.py
   ```
6. 如果 `python3` 不可用，可尝试 `python`；但不要改用 WindowsApps 下的 `python.exe` 存根路径。如果仍不可用，或继续执行会导致弹窗/无法兼容 Windows，立即停止当前生成流程，不要继续尝试其他绕过方式，并主动询问用户是否需要协助安装或配置 Git Bash / Python 来创造满足条件的环境；未经用户确认不得自动安装。

### 认证流程

> **⚠️ 每次执行任务前必须重新调用 `connect_cloud_service` 获取最新凭证，禁止复用。**

1. 调用 `connect_cloud_service`（无参数），返回 `tempToken` 和 `token` 两个字段
2. **优先使用 `tempToken`**（临时密钥），不存在时使用 `token`（JWT）兜底
3. **通过 `--token-stdin` 管道方式传入脚本**（可避免 Token 作为 `buddy-cloud.py` 参数或临时文件传入；执行时仍必须避免向用户展示 Token）：
   ```bash
   # 示例（macOS/Linux）
   echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py video "prompt" --token-stdin
   ```
   ```powershell
   # 示例（Windows PowerShell）
   "<token>" | & python.exe -u "<SKILL_DIR>/scripts/buddy-cloud.py" video "prompt" --token-stdin
   ```
4. **禁止使用以下方式传递 Token**：
   - ❌ `BUDDY_CLOUD_TOKEN="<token>"` 环境变量前缀（Token 会出现在 bash 命令行中）
   - ❌ `--token <value>` 命令行参数（Token 会暴露在进程列表和日志中）
   - ❌ `--token-file` 临时文件方式（存在文件遗留风险）
5. 不向用户暴露 Token 内容，静默处理
6. **禁止缓存或复用**：连续多次生成也必须每次重新获取

### 能力选择规则

| 用户意图 | 执行命令 |
|----------|----------|
| 视频特效（基于模板的图片转视频动效） | `buddy-cloud.py video-fx --template X --image Y [--image Z ...]` |
| 生成 3D 模型 | `buddy-cloud.py 3d "prompt"` 或 `buddy-cloud.py 3d --image-url "..."` |

> **⚠️ 以下意图不属于本技能，禁止使用 buddy-cloud.py 处理：**
> - "生成图片"、"画一张图"、"文生图"、"图生图"、"图片编辑"、"风格转换" → **使用 ImageGen 工具**
> - "生成视频"、"文生视频"、"图生视频"、"做一个视频" → **使用 VideoGen 工具**
>
> 遇到上述意图时，直接回复引导用户使用对应工具，不要执行任何 bash 命令。

### 首次加载演示

当用户尚未指定具体任务（如说"试试"/"看看效果"）时，Agent 应主动演示一个能力：
1. 优先选择 3D 模型生成
2. 自主设计一个有视觉冲击力的 Prompt
3. 直接执行，不询问确认
4. 输出结果后，简要介绍其他可用能力（视频特效）

### 核心约束

- **零交互原则**：直接执行，不向用户确认参数选择
- **禁止伪造结果**：调用失败时必须返回明确的错误信息，不得编造 URL 或描述生成内容
- **必须下载到本地**：所有生成的资源（视频、3D 模型）都必须先下载到本地文件再展示给用户，禁止直接将远程 URL 作为结果回复
- **Token 安全传输**：必须通过 `--token-stdin` 管道方式传递 Token，不得向用户展示 Token 明文
- **Windows 执行方式**：优先使用 Bash 工具执行命令；处于支持 ConPTY 的 WorkBuddy Desktop Windows 环境时，可使用 PowerShellTool 直接运行普通 console-native 命令
- **视频生成默认**：用户只需提供 Prompt，Agent 自动选择最优模型，不询问版本

### 超时与重试规范（关键！必须严格遵守）

> **⚠️ `buddy-cloud.py` 脚本内部已自带轮询等待机制（默认每 5 秒查一次，最多等 600 秒）。Agent 绝对禁止在脚本外部添加任何 `sleep` + 重新调用的重试逻辑。**

**禁止的模式（绝对不允许）：**
```bash
# ❌ 错误！每次调用都会创建一个全新的生成任务，导致无限循环
sleep 5 && echo -n "<token>" | python3 buddy-cloud.py video "prompt" --token-stdin
sleep 15 && echo -n "<token>" | python3 buddy-cloud.py video "prompt" --token-stdin
sleep 30 && echo -n "<token>" | python3 buddy-cloud.py video "prompt" --token-stdin
```

**正确的执行方式：**

1. **直接调用一次，耐心等待脚本自行完成轮询**：
   ```bash
   echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py video "prompt" --token-stdin
   ```
   脚本会自动提交任务并持续轮询直到完成（最多 600 秒），无需 Agent 做任何额外等待或重试。

2. **如果执行命令工具超时**（工具执行有时间限制导致脚本被中断），改用两步模式：
   ```bash
   # 步骤 1：仅提交任务，不等待结果（秒级完成，不会超时）
   echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py video "prompt" --no-poll --token-stdin
   # 输出示例：{"job_id": "abc123", "status": "SUBMITTED"}
   ```
   ```bash
   # 步骤 2：等待 30-60 秒后，用 status 命令查询结果
   echo -n "<token>" | python3 <SKILL_DIR>/scripts/buddy-cloud.py status <job_id> --type video --token-stdin
   ```
   如果 status 返回仍在处理中（QUEUED/PROCESSING），再等待 30 秒后重新查询 status，**不要重新提交任务**。

3. **重试限制**：
   - 同一个生成请求最多重新提交 **1 次**（即首次 + 1 次重试 = 最多 2 次提交）
   - 2 次提交后仍失败，直接向用户报告错误，不再重试
   - 查询 status 可以多次（最多 10 次，每次间隔 30 秒），但**不要重新提交**

### 产物下载与本地展示（必须执行）

> **⚠️ 关键规则：`buddy-cloud.py` 返回的 `result_url` 是远程 URL，必须先下载到本地文件，再展示给用户。绝对禁止直接将远程 URL 作为结果回复给用户。**

脚本执行成功后（`status` 为 `DONE` 或 `success`），Agent **必须**按以下流程处理产物：

#### 步骤 1：解析脚本输出

从 `buddy-cloud.py` 的 stdout JSON 输出中提取产物 URL：

- **视频生成 / 视频特效**：读取 `result_url` 字段。该字段可能是单个 URL 字符串，也可能是 URL 数组
- **3D 模型生成**：读取 `result_files` 数组，每个元素包含 `type`（文件类型如 glb/obj）、`url`（下载地址）、`preview_image_url`（可选预览图）

#### 步骤 2：下载产物到本地

使用 `execute_command` 工具执行 `curl` 命令将文件下载到**当前工作目录**：

```bash
# 视频（单个 URL）
curl -sS -L -o "generated_video_<timestamp>.mp4" "<result_url>"

# 3D 模型（遍历 result_files 数组，逐个下载）
curl -sS -L -o "generated_model_<timestamp>.glb" "<url>"
curl -sS -L -o "generated_model_<timestamp>.obj" "<url>"
# 如有预览图也一并下载
curl -sS -L -o "generated_model_<timestamp>_preview.png" "<preview_image_url>"
```

**命名规则：**
- `<timestamp>` 使用当前时间戳（如 `20260421_224500`），确保文件名唯一
- 视频：`generated_video_<timestamp>.mp4`
- 3D 模型：`generated_model_<timestamp>.<ext>`（ext 取自 result_files 中的 type）
- 如果 `result_url` 是数组（多段视频），依次下载为 `generated_video_<timestamp>_1.mp4`、`generated_video_<timestamp>_2.mp4` ...

#### 步骤 2.5：为 3D 模型生成 viewer.html 并预览（仅 3D 模型必须执行）

当生成的是 3D 模型时，**必须**在下载完 `.glb` 文件后，生成一个 `viewer.html`，然后用 `present_files` 传入该 HTML 的绝对路径。WorkBuddy 内置预览服务会以 `127.0.0.1` 同源托管 `viewer.html` 与同目录的 `.glb`，**不要**再起外部 HTTP 服务器。

> **⚠️ 重要**：`model-viewer` 组件内部使用 `fetch()` 加载模型文件。浏览器安全策略不允许 `file://` 协议跨域请求本地文件，且 `.glb` 模型通常有几十 MB，Base64 内联会导致 HTML 过大、浏览器加载失败。因此 **必须把 `viewer.html` 的绝对路径交给 `present_files` 走内置 HTTP 预览**。不要用 `file://`，也不要自行启动 `python -m http.server` / `npx serve`（默认会绑 `0.0.0.0`，把目录暴露给局域网）。

**文件命名**：`generated_model_<timestamp>_viewer.html`（与对应的 `.glb` 文件使用相同的 `<timestamp>`）

**viewer.html 要求**：
- 使用 [model-viewer](https://modelviewer.dev/) 组件（通过 CDN 引入）
- `<model-viewer>` 的 `src` 使用**相对路径**引用同目录下的 `.glb` 文件（如 `src="generated_model_20260421_224500.glb"`）
- 启用以下属性：`camera-controls`、`auto-rotate`、`shadow-intensity="1"`
- 页面全屏展示模型（`<model-viewer>` 宽高设为 `100vw` / `100vh`），背景色使用浅灰（如 `#f0f0f0`）
- 页面 `<title>` 设为 `3D Model Viewer`

**示例 viewer.html 结构**：
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>3D Model Viewer</title>
  <script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
  <style>
    body { margin: 0; overflow: hidden; background: #f0f0f0; }
    model-viewer { width: 100vw; height: 100vh; }
  </style>
</head>
<body>
  <model-viewer src="generated_model_<timestamp>.glb"
    camera-controls auto-rotate shadow-intensity="1">
  </model-viewer>
</body>
</html>
```

**预览**：

生成 `viewer.html` 后，调用 `present_files` 传入其绝对路径（与 `.glb` 同目录）。不要启动 `python -m http.server` / `npx serve`。

#### 步骤 3：展示产物给用户

下载完成后，使用 `present_files` 工具展示本地文件：

- 视频：调用 `present_files` 传入本地视频路径
- 3D 模型：调用 `present_files` 传入 `viewer.html` 的绝对路径以打开可交互预览；如需同时展示模型文件，把 `.glb` 路径一并放入 `files` 数组

#### 步骤 4：回复用户

- 告知用户产物已保存到本地，给出文件的完整路径
- 如果是 3D 模型，告知用户已生成 `viewer.html` 并在预览窗口打开（支持旋转、缩放）。不要提示用户关闭外部 HTTP 服务器
- 如果 `result_url` 是数组（多段视频），在回复中列出所有本地文件路径

#### 异常处理

- 如果 `curl` 下载失败（如网络超时、URL 过期），向用户说明下载失败原因，并提供原始 URL 供用户手动下载
- 如果 `present_files` 工具不可用或调用失败，直接告知用户文件保存路径，由用户自行打开

---

## buddy-cloud.py 脚本参考

### 命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `video-fx --template T --image URL` | 单图视频特效 | `buddy-cloud.py video-fx --template return2dust --image URL` |
| `video-fx --template T --image URL1 --image URL2` | 多图视频特效 | `buddy-cloud.py video-fx --template hug --image URL1 --image URL2` |
| `3d "prompt"` | 文生3D | `buddy-cloud.py 3d "一条巨龙"` |
| `3d --image-url URL` | 图生3D | `buddy-cloud.py 3d --image-url "https://..."` |
| `status <job_id> --type TYPE` | 查询任务状态 | `buddy-cloud.py status abc123 --type 3d` |

### 全局选项

Token 传递方式详见上方[认证流程](#认证流程)。Agent **必须使用 `--token-stdin` 管道方式**，禁止在命令行中直接暴露 Token。

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--endpoint` | string | 生产环境 URL | 服务端点 |
| `--no-poll` | flag | off | 仅提交，不等待结果 |
| `--poll-interval` | int | 5 | 轮询间隔（秒） |
| `--max-poll-time` | int | 600 | 最大等待时间（秒） |

### 输出格式

所有输出为 JSON（stdout），进度日志输出到 stderr。

**成功：**
```json
{
  "job_id": "abc123def",
  "status": "DONE",
  "result_url": ["https://..."]
}
```

**失败：**
```json
{
  "error": "GENERATION_FAILED",
  "message": "The generation job failed. Please try again."
}
```

---

## 依赖

- Python 3.7+
- `requests`（脚本自动安装）
```

#### ffmpeg-cn-video-subtitle

- 来源: 自建
- 说明: 用 FFmpeg 给中文视频烧录字幕/歌词（含艺术字、逐句对轴、按段落渲染的成片做「第X秒到第Y秒换素材」的精确时间线改造）。当需要给视频加中文字幕、做歌词 MV、卡拉OK式逐句出字、按秒点名替换片段、或排查 drawtext 报 "No option name" / 字体不生效 / 字幕对不上 / 字幕莫名变淡看不见 / 字幕重叠 / 抽帧验证时字没画出来 / 片段比标称时长短导致切口偏移 时使用。
- 路径: `C:\Users\lenovo\.workbuddy\skills\ffmpeg-cn-video-subtitle\SKILL.md`

```markdown
# FFmpeg 中文视频字幕与歌词对轴

## 何时用
- 给成片烧录中文字幕、歌词字幕、艺术字标题
- 需要「唱一句出一句」的逐句歌词
- drawtext 报错：`No option name near '...'`、`Invalid argument`、字体不生效

---

## 一、最致命的坑：字体路径的盘符冒号

filtergraph 里 `:` 是**选项分隔符**。Windows 字体路径 `C:/fonts/x.ttf` 会被切成 `C` + `/fonts/x.ttf`。

**报错表现**：`No option name near '/fonts/x.ttf:fontsize=...'`（注意 `C:` 被吃掉）

**唯一稳定写法 —— 引号内转义冒号**：

```python
# Python 里写 "C\\:/..."，字符串内容为 C\:/fonts/x.ttf
FONT = 'C\\:/fonts/msyh.ttc'
f"drawtext=text='标题':fontfile='{FONT}':fontsize=64:..."
```

实测矩阵（ffmpeg 7.x）：

| 写法 | 结果 |
|---|---|
| `fontfile='C:/fonts/x.ttf'` | ✗ |
| `fontfile='C\:/fonts/x.ttf'` | ✓ **用这个** |
| `fontfile=C\:/fonts/x.ttf`（无引号） | ✗ |
| `fontfile=.fonts/x.ttf`（相对路径，无冒号） | ✓ 备选 |

通用写法：
```python
def ffp(p):
    return p.replace(':', '\\:')
```

**注意 `.format()` 模板**：如果滤镜串是 `.format(FB=FB, ...)` 拼的，模板里也要写成
`fontfile='{FB}'`（带引号），且 FB 的值预先转义好。

---

## 二、别在命令行里传复杂滤镜

`python -c "..."` / shell 里传含引号、逗号、冒号的滤镜串，会先被 shell 和 av_get_token
各剥一层，结果不可预测。

**做法**：
- 滤镜串写进 `.py` 文件再跑
- 或写入文本文件用 `-filter_complex_script <file>`（文件内容直接进 filtergraph parser，引号才生效）

```python
open('fc.txt', 'w', encoding='utf-8').write(graph)
subprocess.run([FF, '-i', src, '-filter_complex_script', 'fc.txt', '-map', '[v]', out])
```

**同时**：滤镜串里 `x=`/`y=` 含表达式且带逗号时，值必须用**单引号**包住，否则逗号被当分隔符：
```
x='(w-text_w)/2':y='h*0.8'
```

---

## 三、选对 ffmpeg：不同构建差异极大

先跑 `ffmpeg -version` 和 `ffmpeg -filters` 确认。老构建（如 2016 年的 3.0.1）**缺**：
`tpad` `cas` `gblur` `rgbashift` `tmix` `unsharp` 等。

- 分镜/转场用到 `tpad`/`cas` → 必须用新版（如 gyan.dev 的 7.x）
- 新版对 filtergraph 解析更严格 → 必须用上面的转义写法
- **尽量全流程统一一个 ffmpeg**，别为字幕单独换老版

---

## 四、艺术字（烫金立体字）

drawtext 不支持渐变，用**双层叠加**模拟：

```python
def art_text(tx, font, size, y, t0, t1):
    a  = f"max(0,min((t-{t0-0.08:.2f})/0.20,1))*max(0,min(({t1-0.10:.2f}-t)/0.20,1))"
    yy = f"{y}+18*max(0,1-(t-{t0-0.08:.2f})/0.32)"      # 淡入时自下上浮
    en = f"between(t,{t0-0.08:.2f},{t1-0.10:.2f})"
    out  = (f"drawtext=text='{tx}':fontfile='{font}':fontsize={size}:"
            f"fontcolor=0xD9A13A:borderw=9:bordercolor=black@0.88:"      # 层1 金色外廓
            f"shadowx=5:shadowy=6:shadowcolor=black@0.55:"
            f"x='(w-text_w)/2':y='{yy}':alpha='{a}':enable='{en}',")
    out += (f"drawtext=text='{tx}':fontfile='{font}':fontsize={size}:"
            f"fontcolor=0xFFFCF2:borderw=3:bordercolor=0xC9942B@0.95:"   # 层2 暖白内芯+细金边
            f"x='(w-text_w)/2':y='{yy}':alpha='{a}':enable='{en}',")
    return out
```

- 书法感用行楷 `stxingka.ttf`
- **上一句彻底消失后下一句才出现**：淡出提前 `t1-0.10` 结束，淡入 `t0-0.08` 开始，绝不叠字
- 有两层字时，**注意其余字幕的 y 要留够间距**（大字号 70px + 描边约需 90px 净空）

### alpha 表达式：用 min/max 相乘，别用 if() 分段

```python
# ✗ 分段式：值域不收敛，实测在本机 ffmpeg 上整体变淡/看不见
A = "if(lt(t,0.35),t/0.35,max(0,(4.30-t)/0.45))"

# ✓ 相乘式：值域天然在 [0,1]，淡入 + 淡出都平滑
A = "min(1,t/0.35)*min(1,max(0,(4.30-t)/0.45))"
```

判据：渲染出来字"灰蒙蒙"、和 `alpha='1'` 对比明显发虚 → 就是 alpha 表达式的问题。
量法：取字所在横向条带算灰度 stddev（满不透明明显更高）。

### 深色/浅色背景都要能读

- 浅背景（天空、白墙）上用**白字 + 粗黑描边**（`borderw=5~6` + `bordercolor=black@0.85`）。
- 淡金色（`0xFFF3C4`）配 `borderw=4` 在蓝天上**几乎看不见**——别只看局部抽帧就定稿。
- 多层文字叠在一起时，**逐条算出 y 区间**（y .. y+fontsize+描边）核一遍有没有交叠，
  比目视可靠。中文用户说"字重叠"通常就是这个。

---

## 五、歌词对轴（难在满编伴奏）

**不要**只用全频段能量分句——满编伴奏下人声换气被混响填平，必然漂。
**不要**只靠 DP 自动切——误差会跨句累积（实测散布 ±1s）。

**可靠流程**：

1. **拿硬锚点**：让用户听着原曲手写关键句的时间（最可靠的信息源，优先级最高）。
2. **确定锚点对应的句索引**，把它当不可移动约束。
3. **锚点之间**只切 n 句，候选切点限定为「**真换气谷**」：
   ```python
   # 人声活跃度 = mid/side，在 320-3000Hz 上算 RMS 比值
   # mid = pan=mono|c0=0.5*c0+0.5*c1 , side = pan=mono|c0=0.5*c0-0.5*c1
   voc[i] 是 [i-W, i+W] 窗口最低点，且 < 段内均值 * 0.94     # W≈±0.5s
   # 再按 0.30s 聚类，一个换气只留一个点
   ```
4. **DP 按字数比例切分**：代价 `((段长 - 理想长)/理想长)^2`，理想长 = 段总长 × 字数占比。
5. **验证要画图**：把活跃度曲线 + 新切点 + 锚点画成 PNG，自己看图确认切点落在谷上。
   数值指标（谷差）不可靠，**图更可信**。

换歌点定位：算 50–200Hz 低频能量的台阶 + 鼓点密度突变。

---

## 六、验证与验收

### ⚠️ 带时间表达式的滤镜怎么验（最容易白忙一轮）

**`-ss` 放在 `-i` 之前会把滤镜里的 `t` 归零。** 于是：

```bash
# ✗ 想验 t=4.0 那一帧的淡入淡出 —— 实际渲的是 t≈0 的效果
ffmpeg -ss 4.0 -i base.mp4 -filter_complex_script fc.txt -frames:v 1 out.jpg
```

看着像"字根本没画出来""alpha 有问题"，其实只是取样时刻错了。

**正确姿势 —— 先渲一小段，再从那段 mp4 抽帧**（时间轴已经是原生 0 起）：

```bash
# ① 先渲 0-9s 小片段（不带 -ss）
ffmpeg -t 9 -i base.mp4 -filter_complex_script fc.txt -map '[out]' -t 9 \
       -c:v libx264 -preset veryfast -crf 18 -pix_fmt yuv420p -r 25 head9.mp4
# ② 再从 head9.mp4 按真实时间抽帧
ffmpeg -y -ss 4.0 -i head9.mp4 -frames:v 1 -q:v 2 f4.jpg
```

### 其余验收要点

- **抽帧读图**是唯一可靠的视觉验证：`ffmpeg -ss T -i F -frames:v 1 -q:v 3 out.jpg`，然后看图。
  数值占比会骗人（例：画面 34.9% 红可能是塑胶跑道不是红旗）。
- **`-vf` 不能和 `-filter_complex` 混用**：报 `Simple and complex filtering cannot be used together`。
  要缩放就把 `scale=...` 写进 complex graph 末尾（放 `[label]` 之前）。
- **交付前查 `ffmpeg -i` 的 SAR/DAR，必须 1:1 / 16:9**。`crop → scale` 会为保 DAR 把 SAR
  设成 1080/1010，整片横向拉伸。修法：`scale` 后补 `setsar=1`。
- **孤立单帧白帧**：素材首尾是白页时会在片段接缝留 1 帧纯白。扫全片灰度找
  `自身>200 且前后帧<182`，用**前一帧画面 overlay 覆盖**那一帧（像素级无缝，不动音画）。
- **音频比画面短时 `-t` 失效**：配乐 4:31.9 < 目标 4:35 时成片只到 272.34s。
  修法 `apad,atrim=0:275`。
- **「全部文字去掉，只留歌词」怎么做**：别去改 `drawtext` 的 alpha / `enable`，**直接删「调用」**
  ——即把章节卡 `chapter(...)`、叙事字幕表 `CAPS` 及其绘制循环从滤镜图里摘掉即可。
  函数体保留、`CAPS` 列表保留注释说明，方便随时加回来。⚠️ `drawbox` 的白闪不是字，别一起删。
- **从「白底多宫格版式页 / 手账页」里把照片抠出来单用**（用户常给的素材是这类模板页，
  要求「照片单独展示，不要模板」）：
  1. 抽一帧原图 → 建「非白」掩膜（与纯白最大通道差 > 10）
  2. **粗格必须 < 最窄白缝的一半**（实测两格之间只有 6px 白缝时，8px 粗格会把两块桥接成一个域，
     bbox 填充率掉到 0.79 被误删；**用 4px**）
  3. 粗格连通域 → **按「整行/整列全白」递归切分**（只靠连通域 bbox 分不开并排/上下叠放的格子）
  4. 回全分辨率收紧边界，**按 bbox 填充率 ≥0.86 过滤**：照片≈0.9–1.0、毛笔字≈0.4、线稿≈0.2
  5. 单张满幅：`scale=1920:1080:force_original_aspect_ratio=increase` +
     `crop=1920:1080:0:(ih-oh)*anchor`（`anchor` 0=保上边；**竖构图用 0.10 才保住人脸**）
     + `unsharp=5:5:0.9` + `cas=strength=0.42`
     ⚠️ 版式页里的照片原本只有 300–700px 宽，满幅要放大 4–6 倍，**糊是素材分辨率决定的**，
        锐化只能找回一点边缘 —— 交付时要跟用户说清楚，并建议他提供原图。
  6. 参考实现：`.workbuddy/boxdetect2.py`（拆格）+ `cardextract.py`（批量抠图）+ `photo_full()`。

---

## 七、成片已是"按段落渲染"时，怎么做到"第 X 秒到第 Y 秒换成这段"

用户常说「1分12秒到1分14秒换成这个」。如果成片结构是
**「若干段落各自渲染成 mp4，再 concat」**（每段被强制 fit 到固定 target），
那么**段落边界是锚死的**，绝不能靠"整体挪时间"来对齐。

### 正确姿势

1. **先算清楚**：把每个段落的 target 前缀和（KADIAN）算出来，得到绝对时间 → 段落内偏移的映射。
2. **只改段落内部**的片段时长，`sec()` 的 target 一个都不许动。
3. **一个片段被切成两截**来插入新内容：
   ```
   原来：[A 3.909][B 3.909][C 3.636][D 5.545]        （D 长 5.545）
   要在 158.0–161.0 插 3.0s 的卡片，而 158.0 落在 D 内部：
        [A][B][C][D1 1.546][卡片 3.0][D2 1.000]      （D1+D2 = 原 D 的时长）
   ```
   `D1`/`D2` 取源素材**互不重叠**的两段（这是硬约束的一部分）。
4. **微调相邻片段**让切口正好落在整秒上。例：某段需要切口落 87.000，
   而前缀和是 86.80，就把**前一个片段**从 3.60 拉到 3.80（同时下调 `speed` 保持源区间合法）。
5. **跨段落边界的同一个镜头**（比如 174–192 要一个连续镜头，但 184 是段落边界）：
   拆成两段分别放进两个段落，取源时首尾相接；并把该素材加进「允许重复」白名单
   （校验规则：**多段但区间不得重叠**）。

### 两道必做的自检（缺一必翻车）

```python
# ① 标称核对：点名时间 vs 片段边界（容差 ~0.06s）
edges = []; t = 0.0
for name, target, have, clips in SEC:
    acc = 0.0
    for d, _ in clips:
        acc += d; edges.append(round(t + acc, 3))
    t += target                      # 段落被 fitter 拉齐 → 用 target 推进
for lab, want in WANT:
    near = min(edges, key=lambda e: abs(e - want))
    assert abs(near - want) <= 0.06, (lab, want, near)
```

```python
# ② 实测核对（关键！标称过了不等于成片对）
#    渲染完每个片段后立刻量它：
got = dur_of(dst)                    # ffmpeg -i dst -f null -
if abs(got - want) > 0.031:          # ≈1 帧
    print("~ %s 标称 %.3f 实际 %.3f" % (name, want, got))
```

### 坑：滤镜图产出比标称短 → 切口整体偏位

**症状**：`--dry` 的标称表全绿，但成片里切口偏了 3–6 帧，且**段落尾部多出一小段冻帧**
（日志会显示「Pxx 实际 14.76s -> 目标 15.00s」）。

**成因**：`clip()` 末尾用 `tpad=stop_mode=clone:stop_duration=0.15` 兜底，
再由 `-t out_dur` 精确截断。但对**重度慢放**（1s 素材拉成 3.6s，`setpts` 倍数 ≈3.3）：
帧间距被拉到 ~0.11s，再过 `fps=25` 抽稀，滤镜图**只能产出 ~3.48s**，
0.15s 的 clone 填不满 3.60s → 片段短 0.12s → 段落 fitter 只好在**段落尾部**补定格。

**修法**：把兜底加长，例如 `tpad=stop_mode=clone:stop_duration=1.20`。
滤镜图总有富余，`-t` 负责精确截断，代价只是每片段多编码几十帧。

**记住**：`tpad` 的时长要 ≥ 「慢放倍数 × 帧间隔」可能造成的缺口，永远别只给 0.15s 就以为安全。

### 换素材时顺手做的三件事
- **水印裁切要实测标定**，别凭猜：把上下边缘条放大抽帧看，确定角标占多少百分比，
  再定 `crop` 比例。注意有些角标比想象的大（本例左上「4K/1080」占到 y≈17%）。
- **AV1（`av01`）素材**：新构建能解，2016 年的老构建连元数据都读不出 → 必须全套用新版。
- **通用文件名**（`video.mp4`、`1.mp4`）别按文件名全局找，会撞车 → 按所在目录定位。
```

#### h3-prompt-writing

- 来源: 自建
- 说明: Write MiniMax H3 video generation prompts for T2VA, I2VA, FL2VA, L2VA, and Ref2VA. Use when rewriting multimodal requests into H3 prompt structures, composing integrated_multimodal_description, overall_soundscape, and non_diegetic_music, aligning keyframes, or defining reference labels for images, videos, and audio.
- 路径: `C:\Users\lenovo\.workbuddy\skills\h3-prompt-writing\SKILL.md`
- 附带文件: `_icon.png`, `_skillhub_meta.json`, `agents/openai.yaml`, `references/base-en.txt`, `references/ref-en.txt`

```markdown
# H3 Prompt Writing

## Workflow

1. Identify the input mode: T2VA, I2VA, FL2VA, L2VA, or full-reference Ref2VA.
2. For base text/keyframe modes, read `references/base-en.txt` and follow its final prompt structure.
3. For full-reference mode, read `references/ref-en.txt` and follow its six-section rewrite format.
4. Preserve the exact field names, section order, labels, and timing notation from the selected guide.

## Base Modes

- T2VA: build the full audiovisual timeline from text.
- I2VA: start from the first frame and develop forward from it.
- FL2VA: describe the continuous path between the first and last frames.
- L2VA: infer a plausible opening and converge to the supplied last frame.

Use `integrated_multimodal_description`, `overall_soundscape`, and `non_diegetic_music` in the order shown in `references/base-en.txt`.

## Full-Reference Mode

Ref2VA rewrites use `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`, `overall_soundscape`, and `non_diegetic_music` in that order. Reference labels stay consistent across all sections.

Read `references/ref-en.txt` for label rules, retention analysis, and complete examples.

## Output Rules

- Write rewrite sections in English; preserve dialogue, lyrics, and visible scene text in their original language.
- Describe each shot by composition, subjects, environment, actions, camera, sound, and the exact point where referenced content appears.
- Avoid plot summaries, unresolved reference labels, and timing that does not match the requested duration.
## Tips for Better Results
- Always match the total duration of the description to the requested video length (4–15 seconds).
- Keep reference labels consistent (e.g. `<Picture 1>`, `<Video 1>`, `<Audio 1>`) across every section.
- Prefer concrete visual and audio details over abstract words like "cinematic" or "beautiful".
- When using keyframes (I2VA / FL2VA / L2VA), clearly state how the first and/or last frame connects to the timeline.
```

#### image-processor

- 来源: 项目生成
- 说明: 图片压缩、缩放、格式转换、裁剪、旋转、镜像、灰度、水印、圆角等常用处理，完全本地离线，不依赖任何云端服务
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2095470397276463104\image-processor\SKILL.md`
- 附带文件: `references/api-spec.md`, `scripts/process-image.ps1`, `scripts/process-image.py`

```markdown
# 图片处理技能指令

当用户需要处理一张图片（压缩体积、调整尺寸、转换格式、裁剪、旋转、镜像、转黑白、加水印、圆角）时，按以下步骤执行：

1. 拿到用户上传的图片文件路径（输入图片）。
2. 读取 `references/api-spec.md`，确认支持的格式与参数格式。
3. 用 Bash 调用脚本：
   `python3 scripts/process-image.py <输入图片> [选项]`
4. 将脚本输出路径中的结果图片返回给用户。

## 常用调用示例

- 压缩：`python3 scripts/process-image.py img.png --compress 80`
- 缩放：`python3 scripts/process-image.py img.png --resize 800x600`
- 等比例缩放：`python3 scripts/process-image.py img.png --resize 800x-1`
- 格式转换：`python3 scripts/process-image.py img.png --convert webp`
- 裁剪：`python3 scripts/process-image.py img.png --crop 10:10:200:150`
- 旋转：`python3 scripts/process-image.py img.png --rotate 90`
- 水平翻转：`python3 scripts/process-image.py img.png --flip h`
- 转黑白：`python3 scripts/process-image.py img.png --grayscale`
- 文字水印：`python3 scripts/process-image.py img.png --watermark "LOGO"`
- 圆角：`python3 scripts/process-image.py img.png --round 80`
- 指定输出：`python3 scripts/process-image.py img.png --compress 80 --output /tmp/out.jpg`

## 注意事项

- 脚本会自动探测环境里可用的图片引擎（Pillow / ffmpeg / ImageMagick / System.Drawing），挑一个能用的执行，无需用户指定。
- 全程本地离线，不联网、不付费、不需要 API Key。
- 若环境没有任何可用引擎，脚本会给出清晰的安装提示（`pip install pillow` 等），不会崩溃报错。
```

#### apple-design

- 来源: 项目生成
- 说明: 基于Apple WWDC流体交互设计，用于UI设计评审、手势驱动界面、弹簧动画、拖拽/侧滑/抽屉弹窗、动量过渡、毛玻璃材质、深度层级、光学字号排版、减弱动效无障碍场景；输出设计建议、参数、Web端CSS/JS代码示例。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2095572066616803328\apple-design\SKILL.md`
- 附带文件: `references/spring‑param‑ref.md`, `references/wwdc‑design‑rules.md`, `scripts/code‑snippet‑gen.py`, `templates/apple‑ui‑review‑template.md`

```markdown
# Apple流体界面设计技能
> 引用参考资料
> @references/spring‑param‑ref.md
> @references/wwdc‑design‑rules.md
> 使用评审模板 templates/apple‑ui‑review‑template.md

## 触发词
苹果界面设计、流体交互、弹簧动画、手势UI、抽屉弹窗、拖拽滑动、毛玻璃材质、Apple UI评审、动效参数、无障碍动效

## 执行SOP
### 步骤1：确认需求场景
1. 如果用户输入信息过少，主动询问：使用场景（抽屉/拖拽/弹窗/列表滑动）、运行平台（Web/H5）、是否需要无障碍适配。
2. 用户上传设计稿/需求文档，调用Read读取文档作为输入依据。

### 步骤2：依据苹果设计原则输出内容，按需输出以下模块
1. **核心设计思路**：流体交互核心思想，界面行为模拟现实物理世界，即时响应、动量传递、可中途打断动画。
2. **交互行为建议**：响应延迟、直接操纵、动画可中断、弹簧物理、速度移交、动量投射、橡胶边界、手势细节。
3. **物理参数推荐**：弹簧阻尼比、响应时间，参考 @references/spring‑param‑ref.md。
4. **样式与材质方案**：毛玻璃backdrop‑filter、层级深度、阴影、文字活力（Vibrancy）。
5. **排版规范**：光学字号、字间距、行高动态适配。
6. **无障碍方案**：减弱动效、降低透明度、高对比度适配媒体查询。
7. **Web可运行代码片段**：CSS、JS、Framer‑Motion/Motion示例。
8. **八大设计原则校验**：目的性、用户控制权、责任、熟悉感、灵活性、简洁、工艺、愉悦感。

### 步骤3：分支交互逻辑
1. 用户输入【UI评审】：读取 templates/apple‑ui‑review‑template.md，填充内容输出完整评审报告。
2. 用户输入【生成代码】：调用Bash执行 scripts/code‑snippet‑gen.py，输出格式化代码片段。
3. 用户输入【输出文件】：完成分析后，询问确认，调用Write将完整报告保存到本地 `AppleUI设计报告.md`。

## 输出约束
1. 使用Markdown，代码块使用```css ``````js ```标记。
2. 参数输出严格对齐苹果WWDC给出的物理参数。
3. 不编造不存在API，Web能力受限处明确标注限制。
4. 信息不足主动提问，不凭空给出设计方案。
5. 禁止高危系统操作。

## 调用示例
> 示例1：抽屉弹窗设计
苹果界面设计，做一个 Web 底部抽屉 sheet，输出交互参数和 css 示例

```
> 示例2：UI评审模式
```

UI 评审，我要做一个可拖拽卡片，按照 Apple 流体交互标准评审

```
> 示例3：输出报告文件
```

基于上面的分析，输出文件保存本地

```

## 参考核心思想
> 当界面对齐人的思考与运动方式，就不再像一台计算机，而是无缝的延伸。
> 流体界面特征：即时响应、连续运动、携带动量、边界阻力、运动过程可随时被打断重定向。
```
```

#### ardot-design-router

- 来源: 内置/市场
- 说明: Dispatcher for WorkBuddy's Ardot design assistant. Use this when a design task is in Craft/design mode but the specific deliverable type is not yet determined from UI signals. It classifies intent (UI screen / slides / poster / design-to-code) and tells you which domain Ardot skill to load, then defers to that skill plus ardot-design-core. Carries the always-on hard rules for canvas design. Not for PowerPoint .pptx file output (pptx skill).
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-ardot-design-router\0.1.1\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Ardot Design Router

You are the dispatcher for WorkBuddy's Ardot design assistant. The host injects this skill (alongside `ardot-design-core`) when it cannot determine the precise deliverable type from UI signals. Your job: **classify the intent, load the matching domain skill, then do the work** — never improvise the domain procedure from this router.

## Decision tree (run this first, every turn)

Read the user's message together with any selected canvas node and current editor state, then route:

| Intent | Signals | Load skill |
|---|---|---|
| **UI / interface** | page, screen, dashboard, landing page, web app, mobile app, form, table, component, design system, tokens · 页面/界面/网站/官网/落地页/后台/移动端/小程序/组件库/设计系统 | `ardot-ui-design` |
| **Slides / deck** | presentation, deck, pitch deck, keynote, slides · 幻灯片/演示文稿/发布会/路演/提案稿/PPT 设计稿 | `ardot-slides` |
| **Poster / visual** | poster, flyer, banner, billboard, cover, logo, icon, illustration, brand/VI · 海报/宣传单/横幅/banner/封面/图标/插画/Logo/品牌 | `ardot-poster` |
| **Design → code / extraction** | convert to code, to HTML, export webpage, pixel-perfect, to App, extract style/tokens from website · 出码/转代码/生成HTML/一比一还原/转应用/网站风格转设计稿/提取 token | `ardot-design-to-code` |
| **Unclear** | cannot resolve to one of the above | **ask the user** in your reply — do NOT load a domain skill yet |

Rules:
1. Pick the **single best-matching** domain skill — do not load several at once. (Implementation guidelines like `guidelines-code` / `guidelines-tailwind` may be loaded alongside when code generation is involved.)
2. Once classified (non-unclear), **immediately** load that skill via `Skill(<name>)`, then follow its workflow together with `ardot-design-core`.
3. If the user provides a reference **image** to reproduce a UI → `ardot-ui-design` (image-to-UI). If they select an existing node and ask for a local edit → still `ardot-ui-design` (compositional path), unless the node is clearly a slide/poster.
4. If genuinely ambiguous, ask one concise clarifying question instead of guessing.

## Hard rules (always apply, independent of which domain skill loads)

- ⛔ **NO SUB-AGENTS.** Do all work inline in the main conversation — never spawn/delegate to any sub-agent / Task / team member / background agent.
- **Three-part reply format** for every design task: Opening · Progress · Closing, separated by `---`. Never narrate internal phases ("Phase 1/2/3") to the user.
- **Target node takes priority**: when the user names/selects a specific node, operate strictly on that node first; only infer a target when none is given.
- **`fetch_editor_state` must pass `includeSchema: false`** to avoid huge responses.
- **Screenshot verification** uses `capture_screenshot` with `screenShotDir: ".workbuddy/screenshots"` (relative to project root). Screenshots are internal verification artifacts — never surface their paths, never write them to `/tmp`, home dir, or project root.
- All canvas manipulation goes through the **ardot MCP** tools.
```

#### ui-replication-lab

- 来源: 自建
- 说明: 把顶级站（ThreeUI 系 / Active Theory / Lusion / Cuberto 等）拿来深度拆解、沉淀成可复用设计系统，并复刻迭代到超越；终局是产出 token 驱动的皮肤包，能一键套到任意第三方网站。触发词：拆解这个网站、复刻 ThreeUI、UI 实验室、一键套皮、给这个网站换皮肤、设计系统 token。
- 路径: `C:\Users\lenovo\.workbuddy\skills\ui-replication-lab\SKILL.md`

```markdown
# UI 拆解复刻实验室

## 一、目标与判定线

不是「抄一个好看的页面」，是长出**能从视觉反推因果的能力**，终点是可复用资产。

- **追平** = 客观八维均分不低于原站
- **超越** = 同屏 A/B 盲测胜率 > 70%
- 终局能力：只给一张付费页截图，能做出媲美的完整站（靠原理库厚度，不靠源码）

## 二、四层架构

| 层 | 内容 |
|---|---|
| L1 素材层 | ThreeUI 组件与模板、对标站矩阵、截图与视频抽帧 |
| L2 知识层 | **事实库**（有什么）/ **原理库**（为什么，含消融证据）/ **配方库**（参数组合 + token） |
| L3 能力层 | 拆解 skill、复刻 skill、评审 rubric |
| L4 产品层 | 自建设计系统、一键套皮引擎、HTML 工作台 |

## 三、单站五步闭环（每步必带产出 + 闸门）

1. **普查取资产** → 产出：资产清单（含 license）；闸门：无未核实组件名，字体/纹理授权已标注。
2. **拆解归因** → 产出：原理条目（因果链 + 参数敏感度）+ 设计规格书；闸门：**每条「为什么」必须有消融证据**（关掉它看差多少）。
3. **复刻实现** → 产出：单文件可运行站 vN + 参数表；闸门：console 零报错，首屏/中段/深滚三段截图齐全。
4. **并排盲评** → 产出：八维评分卡 + 差异清单 + 下一轮方向；闸门：LCP/INP/CLS/FPS 达标，差异定位到具体参数。
5. **入库沉淀** → 产出：skill 更新 + token 版本 + 记忆日志；闸门：`sync_skills.py` 归类完成。

八维：视觉层级 / 排版节奏 / 动效时序 / 空间密度 / 色彩对比 / 一致性 / 性能 / 可访问性。
**每轮只改一组因果变量**，多变量同改则赢了不知赢在哪、输了没法回滚。

## 四、三条硬纪律（防幻觉）

1. **分流反推**：可反推的（视觉描述 → 生成式 prompt）才出 prompt；**手写代码类只出「设计规格书」，绝不伪造提示词**。
2. **禁止编造**：组件名、参数、数值一律取自真实源码（ThreeUI 用 tarball 探结构，见 `threeui-integration`）。
3. **成品态有幸存者偏差**：拿到的源码是最终结果，试错史是丢的。补参数的**取值范围与敏感度**，用消融实验还原因果。

## 五、Token 层是地基（缺了它一键套皮永远做不出来）

三层解耦：**token（JSON）→ 组件实现（多框架）→ 注入层（CSS 覆盖 / 浏览器扩展 / 构建插件）**。
换风格 = 换 token 表（ThreeUI 自己的 `pageRecipes.js` + `--u` 缩放单位 + `retone()` 换色就是这个思路）。

## 六、一键套皮的三级能力（别跳级）

- **L1 同源站**：我们自己的站 / 结构已知的模板站，100% 可控，CSS 变量直注。
- **L2 通用站**：语义角色 → 候选选择器 → token 三层映射；用 `role` / `aria` / heading 层级 / 栅格检测定位语义。覆盖 60~80%，其余人工补规则。形态 = 浏览器扩展（MV3）注入。
- **L3 截图重写**：截图 → 区块识别 → 生成重写方案（screenshot-to-code 路线）。

L2 已知待补：暗色皮肤下白色 logo/图片会消失（需反色保护）、表单元素受 UA 默认样式高优先级影响、层级权重冲突（必要时 `!important` 强化版）。

## 七、工作台

`生成物/ui-workbench/index.html`（单文件、零依赖、localStorage 持久化，数据可导出 JSON）。
模块：资产浏览器 / 拆解档案 / 评分卡 / 版本对照 / Token 面板（实时预览）/ 配方库 + LAB_STATE / 套皮映射 L2 / 导出器（token.json、tokens.css、复刻 prompt、**Agent 投喂包**）。

## 八、商业化（黄总 2026-09-23 明确：最终目的是沉淀成有商业价值的 skill 卖出去）

### 先说清楚一件难听的：**卖 SKILL.md 本身很难变现**
SKILL.md 是纯文本，零复制成本、无技术壁垒，买家拿到即拥有。能卖钱的是**它背后那套可运行的资产**，skill 只是说明书。所以每次拆解的产出必须落到三种可卖形态之一，而不是停在"笔记"：

1. **Token 皮肤包**（可卖）：多套经过验证的 design token + 排版预设 + 组件实现（React / Vue / 纯 CSS 三份）。
2. **套皮引擎**（可卖、有壁垒）：能对任意第三方站生效的语义映射引擎（浏览器扩展 / CLI / 构建插件）。**壁垒在这里**——不是模板，是"对未知 DOM 也能工作"的映射规则库 + 覆盖率。
3. **改造服务**（高客单价、低边际成本）：给客户现有网站做皮肤改造，一套引擎重复卖。

### 商业化硬门槛：版权必须前置
ThreeUI Community 开源，但**字体与纹理另有授权**。商用交付前必须换成自有或可商用资产：纹理用程序化生成（噪声/烘焙）或自拍素材，字体只留 SIL/OFL 开源字体或自购商用授权。**这一步不做完，产品不能上架**——否则卖了就是侵权。

### 产品分层建议
- **免费层**：1~2 套皮肤 + 基础注入 —— 获客与作品背书。
- **付费层**：皮肤包（多套）+ 浏览器扩展（任意站一键套皮）+ 三框架源码。
- **服务层**：按站改造交付。

### 每次拆解的交付纪律（商业化版）
拆一个站，除了原理条目，必须同时产出：可导入的 token JSON、可复用组件骨架、可写入映射库的选择器规则。**只写原理不落资产 = 这次拆解没有商业价值。**

## 九、离线取图与截图流水线（2026-09-23 实测，踩过的坑都在这）

目标：**一个网页不联网也要能看、能评**——下源码 + 下素材 + 本机渲染截图。

### 1) 从 npm 包里抽网页与素材
- 用 node 内置 `zlib` 解 tar，**不装包**（ThreeUI tarball 42MB，直接读）。
- 网页里的素材是相对路径 → 抽取时要**保持相对目录结构**（`assets/...`），否则页面打开是白板。
- 别漏 `.webp` / `.woff2` / `three.min.js`：ThreeUI 的 kage 页依赖 `secret-pathways-assets/`（10 张前景 webp + 4 张场景 webp）。

### 2) 截图：chromium 命令行（不需要 playwright 包）
本机 `ms-playwright/chromium-*/chrome-win64/chrome.exe` 可直接命令行出图：

```
chrome.exe --headless=new --no-sandbox --hide-scrollbars \
  --window-size=1360,850 --virtual-time-budget=10000 \
  --enable-unsafe-swiftshader --use-gl=angle --use-angle=swiftshader \
  --user-data-dir=<临时目录> --screenshot=out.png file:///abs/path.html
```

- **`--virtual-time-budget` 是唯一的时序旋钮**：不给它，截图会在 load 事件就触发，WebGL 还没画完 → 纯黑图（5KB PNG = 黑屏信号）。
- **中段截图技巧**：原目录旁复制一份 `x.html` → `x.shot.html`，在 `</body>` 前注入 `scrollTo(0, scrollHeight*ratio)`，**同目录才能保住相对素材路径**（拷到 tmp 就白板）。截完删掉副本。
- 校验产出别靠肉眼：`os.path.getsize(png) > 60KB` 作为「有内容」阈值，5~7KB 一律判黑。

### 3) ⭐ 2026-09-24 重大更新：换 `chrome-headless-shell.exe`（此前所有截图失败的正解）

**完整版 `chrome.exe` / `msedge.exe` 在本机无头截图必崩**（`GPU process exited unexpectedly: exit_code=-1073741819` = 0xC0000005），加 `--disable-gpu` 也没用；沙箱还会报 `Sandbox cannot access executable ... 拒绝访问 (0x5)`。

**正解**：用 playwright 附带的轻量无头内核 ——
`%LOCALAPPDATA%/ms-playwright/chromium_headless_shell-1243/chrome-headless-shell-win64/chrome-headless-shell.exe`
配 `--no-sandbox --disable-gpu`，稳定出图。**判成功看 stdout 是否打印 `N bytes written to file ...`**（别用文件是否存在判断，会误判成旧文件）。

三条配套要点：
- `--virtual-time-budget` 遇到**无限 rAF 页面**会永远等不到 idle → 页面加 `?shot=N`（跑够 N 帧就停 rAF）。
- `#fragment` 滚动 + `sticky` + `100vh` 在 headless-shell 里**重绘失败（全黑）** → 页面加 `?only=sN` 只渲染一段，不靠滚动。
- 软件渲染下粒子数降到 ~1000，否则画不完。

→ 2026-09-23 那次"kage / spark-badge 截不出来"的结论仍然成立（**重 WebGL 页在软件渲染下确实跑不动**），但**普通动效页现在有解了**。完整模板见 skill `web-motion-craft` 第六节。

### 4) 硬边界：无 GPU 环境截不动重 WebGL 页
实测结果：`inner-green-3d / bestsellers / koi-halftone / sketchbook / landscape / japanese-tower / complete-shelf` 能出图；
**`kage`（阴影贴图 + `FogExp2` + 10 张前景）和 `spark-badge`（手写 WebGL，无 THREE）在 swiftshader 下超时（>300s）**，降分辨率到 880×550、放宽到 300s 仍失败；换真 GPU 后端（不加 swiftshader flags）在 headless 无显示环境直接挂起。

→ **结论：不硬等**。兜底方案，按保真度排序：
1. **用页面自带素材**（kage 的 `generated/kage-*.webp` 就是设计方自己渲的场景图，最保真）；
2. **用源码实测配色板**（从 CSS 变量/body 背景取主色+强调色，画成色板；数据来自源码，不算编造）；
3. 一律在**角标处标明来源**（首屏 / 中段 / 官方场景图 / 无截图），不冒充截图。

### 4) 环境坑
- `pip install playwright` 在本机**断网时会静默挂死 18 分钟**（不报错、无输出）。装包前先确认网络，别阻塞主流程——命令行截图方案零依赖，够用。
- 连续多次启动 headless chrome 后可能整体卡住（连静态页也超时）。此时改用**静态校验**：解析生成的 HTML，逐个 `os.path.exists()` 核对 img/href 引用，比截图快且确定。
- 素材里 `synthralos-halftone.html` 16MB 几乎全是内嵌 base64（`datauri` 字段可查），复用时要先拆出来。

## 十、坑

- 只学一个来源会过拟合 → 对标站按**技法维度**交叉索引，不按站点。
- 视觉顶级站常是 WebGL 重负载 → 性能闸门（LCP/INP/CLS/60fps/`prefers-reduced-motion`）不达标不算完成。
- Community 开源 ≠ 字体纹理可商用 → 核 `FONT-LICENSES.md` / `ASSET-LICENSES.md`。
- 逐帧插值一律 `damp(cur,to,rate,dt)=lerp(cur,to,1-exp(-rate*dt))`，裸 `lerp(a,b,0.1)` 在高刷屏会跟手过头、掉「重量感」。
- 没有固定节奏必烂尾 → 每站一轮五步闭环，跑完立刻沉淀。
```

#### style-moodboard-calibration

- 来源: 自建
- 说明: 当用户给一批感性风格词（氛围感、古风、科技感、高级感、赛博朋克…）要求"找图 → 他挑 → 我学会"时使用。含免密钥图源抓取（360 图片接口可用、Bing 中文相关性差、搜狗封爬虫）、contact sheet 省 token 审图法、点选页面导回 JSON 的标定闭环。触发词：上网找图、风格校准、氛围感、古风、科技感、moodboard、情绪板。
- 路径: `C:\Users\lenovo\.workbuddy\skills\style-moodboard-calibration\SKILL.md`

```markdown
# 风格词校准与图源抓取

把用户的感性词（"氛围感""古风""科技感"）变成**可复现的画面配方**：不是背形容词，是拿到"这个词 = 什么光、什么色、什么景、什么材质"的证据。

## 一、闭环（四步，缺一步就变成"我猜他要什么"）

1. **先给假设**：动手前先说清"我理解的这个词 = 什么画面"。用户会当场纠正，比事后返工便宜。
2. **抓候选图**：每类 20~24 张，**必须跨面貌**（同一个词常有多张面孔，见下"面貌表"）。
3. **他挑**：做成点选页，图**打乱顺序、不按类分组**（分组会诱导他顺从我的分类，标定就废了）。每张点一个词 + 可标"★标杆"，导出 JSON。
4. **读回校准**：读导出的 JSON，算"我的原分类 vs 他的判断"命中率；命中率低的类别就是我和他理解不一致的地方，写进记忆 + skill。

## 二、图源（2026-09-24 实测，中国网络环境）

| 源 | 状态 | 用法 |
|---|---|---|
| **360 图片** `image.so.com/j?q=&pn=` | ✅ 可用、中文相关性最好 | 首选。返回 `img`(原图，可能防盗链) + `thumb`(p*.ssl.qhimgs1.com，稳定) |
| Bing 图片 `cn.bing.com/images/search` | ⚠️ 能抓但中文相关性差 | "科技感"会返回**电机正反转电路图**、"氛围感"返回大气物理文章。只适合纯英文摄影关键词 |
| 搜狗图片 | ❌ `{"status":1,"info":"forbid"}` | 弃 |
| 百度图片 | ❌ `Forbid spider access` | 弃 |
| DuckDuckGo | ❌ 连不上 | 弃 |
| commons.wikimedia.org | ❌ 连不上 | 弃 |
| images.unsplash.com / images.pexels.com | ✅ CDN 可达 | 但**搜索接口都要 key**（unsplash napi 返回 `Authorization required`），只能直链下载已知图 |

抓取要点：
- UA + `Referer: https://image.so.com/`；原图失败自动回退 thumb；`len(bytes) < 15KB` 判为图标/占位，丢弃。
- 过滤：标题含 `千库/摄图/包图/视觉中国/昵图/素材/下载/模板/淘宝` 一律跳（水印素材图，进 moodboard 会污染判断）；`width < 700` 跳。
- 去重：URL 去参 + 文件 md5 双保险。

## 三、省 token 的审图法：contact sheet

**不要逐张 Read 图片**（一张几万 token）。用 PIL 拼 6 列网格、每个缩略图下标编号，一次 Read 一张拼图就能筛掉 80%。
脚本：`生成物/_probe/make_sheet_g.py`（`python make_sheet_g.py <批次号> <输出前缀>`）。

## 四、面貌表（一个词往往有 3~5 张面孔，抓图必须覆盖）

| 词 | 常见面貌 |
|---|---|
| 氛围感 | 电影感街头摄影 / 雾气自然 / 雨夜霓虹 / 暗调室内光 / 逆光剪影人像 |
| 古风 | 水墨山水画 / 古建飞檐斗拱 / 汉服人像 / 茶器静物 / 文房书法 / 古风海报排版 |
| 科技感 | 蓝色光效背景（国内商业最常见）/ 赛博朋克霓虹摄影 / 科幻概念原画 / dark UI dashboard / 全息投影 / 航天 |
| 真实感 | 超写实静物油画（"以为是照片其实是画"）/ 真实材质微距（混凝土·拉丝金属·大理石·织物）/ 暗调静物摄影（棚拍光·浅景深）/ 空间光影与全局光（拱廊·窗光）/ 自然微观（水波涟漪·露珠苔藓·冰晶）/ 胶片颗粒质感 |

### ⭐ 元维度词 vs 并列词（2026-09-24 新增）
有些词**不是并列的第五类，而是凌驾性的元维度**，抓图与归纳时都要单独对待：
- **真实感**（2026-09-24 黄总明示）：原话「真实感是**凌驾在其他所有感觉之上**的，是 UI 设计者最看重的」。→ 它不是"再来一类"，而是**上层约束**：氛围感/科技感/古风/设计感都建立在它之上，不真实则全废。抓图要单独成批（别混进风格词一起抓），归纳时要问"哪些是真、哪些是假"，而非"这算哪类"。
- **设计感**（更早确认）：兜底 + 可叠加。
- 判据：出现"**凌驾于…之上**""**最看重**""**之上/之下**"这类表述，就是元维度，不是并列类。

> 教训：只抓一类面孔 = 标定无效。第一轮 360 抓"古风"得到 20 张**全是水墨山水插画**、抓"科技感"得到 20 张**全是蓝色渐变背景**，必须按面貌表补抓第二轮。

## 四之二、数量标准（2026-09-24 黄总定档）

- **每类 15 张、三类共 45 张**是黄总要的规模。他先说"十几张"，看到 18 张后仍说"太少了，至少要 45 张左右"——**"十几张"是下限不是目标，直接按每类 15 张准备**。
- 抓取冗余 **2:1**：每类抓 30 张候选 → 筛出 15 张。这轮 90 张候选中废图率约 20%（水印素材图、日式茶具混进"古风"、雨后森林混进"氛围感"），不留冗余就得二次抓，慢一倍。
- 每类 30 张候选拼成**一张** 6 列审图板读一次即可筛完，是 token 最省的档位。
- 扩量关键词矩阵（21 组，每组取 5 张）：
  - 氛围感：电影感街头光影 / 雾天森林 / 雨夜霓虹 / 暗调室内一束光 / 逆光剪影人像 / 黄昏海边剪影 / 胶片颗粒
  - 古风：水墨山水 / 古建飞檐斗拱 / 汉服人像 / 茶器禅意 / 文房书法 / 中国风海报排版 / 青绿山水
  - 科技感：蓝色光效背景 / 赛博朋克霓虹摄影 / 科幻概念原画 / dark UI dashboard / 全息粒子抽象 / 航天火箭 / 数据可视化大屏
- **终选配比要防偏**：日落剪影好出图，10 张候选里 8 张是黄昏——**按面貌分配名额**（雨夜 4 / 城市光影 1 / 几何剪影 1 / 迷雾 2 / 逆光人像 2 / 暗调人像 2 / 黄昏剪影 2 / 日落灯塔 1），不按"哪张好看"选。

## 四之三、不能让他看到答案

- 终选图**重命名为中性编号**（`p01.jpg`~`p45.jpg`），**原分类绝不写进文件名，也不写进 HTML 的 `data-*`**。`data-origin` 会被 F12 一眼看穿，标定立刻失效。
- 对照关系（`pNN` → 原分类）只存在本地 `imgs45.json`，我算命中率时读它。
- 顺序用固定种子打乱（`random.seed(20260924)`），可复现。

## 五、标定页的技术细节（踩过的坑）

- 页面用 `<figure data-img data-origin data-pick>` 存状态；按钮组 4 个（3 个词 + 都不像）；★ 独立切换。
- **导出必须落成文件**：`Blob` + `a.download` 触发下载到浏览器下载目录（`C:\Users\lenovo\Downloads`），我再去读——预览环境的 localStorage 我读不到，别指望它。
- **图片必须 base64 内嵌进 HTML，不要用相对路径**（2026-09-24 被黄总打回："图片直接放在这里啊，我没有看到"）。预览面板里 `<img src="imgs/古风-419.jpg">` 这种「相对路径 + 中文文件名」的组合会静默失图，页面只见文字和按钮。正确做法：PIL 压到最长边 1000px / quality 76（18 张 ≈ 1.4MB，可接受）→ `data:image/jpeg;base64,...` 直接塞进 `src` → 单文件自包含，离线也一定能看。
- **同时在对话里给带编号的总览拼图**（`_总览N张.png`）。他说的"直接放在这里"往往是指**对话里就能看到**，只给一个 HTML 文件不算。拼图每格左上角打 `No.x` 角标，与页面里的编号一一对应，他可以张口就说"No.7 不算氛围感"，不必等页面打开。45 张要**切成分页**（每页 24 格、6 列），单页超过 24 格缩略图就小到看不清了。
- **45 张内嵌后单文件约 4MB**，可接受；再多就该改外链 + 本地服务，不要硬塞。

## 五之二、回读与分歧可视化（2026-09-24 实测）

他口述判断时说的是**编号**（"第七章""第二十二章"，实际指拼图角标 `No.x`），所以：

- **三处编号必须一致**：拼图角标 / 页面卡片角标 / 本地 `imgs45.json` 的 `n`。三处对不上的话他说的编号我定位不到原图，整轮标定作废。
- **必须算命中率**：`我的原分类 vs 他的判断`，报出准确数字（这轮 17/24 = 70.8%）。含糊说"大部分对上了"等于没校准。
- **分歧必须出图**：生成 `_对照_不一致7张.png`——每张图标"我判 X / 你判 Y"两个色块。光用文字列"我们对不上 7 张"，他无法判断我到底有没有看懂差在哪。
- **他的"其余大多…"是不完全统计**：要单列一栏"未点名（默认归 X）"，别把它当成逐张确认过的判断。
- 他若自己提出新词（这轮是"设计感"），**先分辨它是「并列的第四类」还是「叠加的维度」再记录**，别默认当第四类收下——叠加维度会影响后面所有分类逻辑。
- **一旦确认是叠加维度，标定页就要改成支持叠加**（主词单选 + 叠加开关，如"＋ 设计感"），导出 JSON 里主类与叠加标签分开存。让他用单选页去表达"既 A 又 B"是逼他失真。
- **他未点名的图不要替他归类**。他说的"其余大多具有科技感"是粗略话，后来 No.2、No.18 被明确为"氛围感+设计感"。未点名的必须单独回问一句。
- **多张总览图要合成一张全景发**。分页发他只看到第一页（这轮他直接说"我没看到第二张"）。45 张塞一张 6 列×8 行、每格 292×195 是可行的，比"发两张各 24 格"更可靠。

### 这轮真正学到的判据（跨风格词通用，可复用）

1. **别用「有没有某类元素」判，要用「画面的主角是什么」判**。同样一张抽象光效图，主角是"光"，就取决于光像不像技术产物，而不取决于它像不像科技。
2. **⚠️ 不要用正例归纳判据——必然翻车**（2026-09-24 被黄总当场推翻两条）。
   我拿正例推出"明暗决定归属""古风必须有器物符号"，他立刻给出反例：**No.42 紫粉分形背景昏暗但仍是很强的科技感**、**No.10 黑底金字书法无器物但很有古风色彩**。
   → 正确做法：**归纳出的每一条判据，必须自己先造反例去问他**（"这张暗调但有科技感，算哪类？"），答完才算验证。
   → 一轮归纳只能当**待验证假设**，绝不写进记忆当结论、更不能拿去直接做任务。
3. **他的判断是多因素合成的，不存在单一物理量判据**。我总想找"一个开关"（明暗、有无符号），这是系统性偏差。宁可记录"这张为什么像那类"的原话，也不要去提炼窄判据。
4. **同一张图可以同时属于两类**（氛围感 + 设计感），分类体系要预留叠加位。
5. **他纠正后不要急着再归纳一套新的**——先把他原话里的**未定义词**问清楚。这次他说"这两种效果你都没找到就归设计感"，"这两种效果"到底指哪两种并没有说，直接追问比猜更快。
   → 追问后得到的答案：**"两种"其实是"三类"的误写，指的是「氛围感/古风/科技感三类都不像」**。设计感是**兜底类**，同时**还能叠加**。
   ⚠️ **推论：他口语里的数字/指代不可靠（"两种"≠2）。凡是出现"这个/那个/两种/后面那个"这类指代，一律回问，不要按字面理解。**
6. **题材与色调要分开记**。但注意：黑金配色 + 书法字他认为**算**古风（No.10 反例），说明"中式审美语言"本身就是符号，不必有实物。
7. **⭐ 终极形态是「多标签联想词典」，不是「互斥分类器」**（2026-09-24 第五轮黄总原话：「人类的语言世界里，其实这些都不是十分矛盾……**不要太死板**」）。
   - **"不要太死板"是元信号**：听到就立刻检查自己是不是又在搞互斥、又在找单一判据。正确心态：**四个词是四种气味，可以同时闻到**。
   - **设计感覆盖面极广**：从氛围感（No.18/20）到科技感（**No.39/40 赛博朋克霓虹，他第五轮点名**）都能叠一层。不要把它当"只剩它才用"的兜底类。
   - **应用规则：只用于向上联想，不用于向下否决。** 用户说"要氛围感"≠"不要设计感"。宁可多叠一个词，也不要为了归类干净砍掉一个明显存在的味道。
   - **标定页的正确形态 = 四词全可多选（toggle，不互斥）**。每张图 4 个 chip 各自独立开关，选项一个都不像就全不选；不要做"单选主词 + 叠加开关"那套（v2 的 `syncDes()` 联动方案已在 v3 废弃）。
   - **产物要有两份**：① 给人看的可视化（`词典.html` 四词分组内嵌图 + `_账本_45张.png` 色带总图，实色=他确认/描边=我推断/灰框=未标）；② 给 AI 投喂的文本 `风格词典.md`（UTF-8 BOM）。后者才是能沉淀/能卖的形态。
   - **账本要固化成单一数据源**：`ledger.json`（`tags` / `confirmed` / `rough` / `reject` / `reasons`），所有生成器（词典页、账本图、标定页）都读它。改标签只改一处，别让三份数据各写各的——我第一版就是三个脚本各写一份 LEDGER，第六轮改 10 张图要改三处，极易漏。
8. **⭐ 标定必须产出「负面样本池」，与正面标签同等重要**（2026-09-24 第六轮）。
   他说"这些东西以后不要出现在设计的网页上"（**No.37** 中式排版海报带素材站水印、**No.44** 火箭发射蓝天白云图库图）。
   - 这是**优先级最高的选图约束**，却最容易漏记——人只想记"是什么"，不想记"不要什么"。
   - 共性提炼：**图库/素材站风** = 搜图能搜到一大把的通用图，没有"被设计过"的痕迹 → **这正是"设计感"的反面**。
   - 落库单列 `reject` 字段，可视化时**灰化 + 红框标 ✕**，与正面标签区分。
9. **⚠️ 我的系统性偏差：判「设计感」持续偏低**。我总把设计感留给"几何构成强/有剪影主体"的图，但他的设计感本质是"**好看、讲究、能当素材**"（他给的理由："景色很美""较好反映城市特点""说不太清但就是有"）。连续两轮我共漏 9 张（18/20/29/31/38/39/40/41/43）。
   - **修正动作：拿不准就加设计感。** 叠加成本为零，漏判成本是"以后做方案选不出好图"。
10. **他说"说不太清楚"时，那正是最值钱的判据**——主观审美无法穷举成规则，**记原话，不要硬提炼**。我硬提炼过 4 次，4 次都被反例推翻（明暗 → 器物符号 → 并列互斥 → 几何构成）。
- 生成后静态校验：解析 HTML 里 `<img src>` 逐个检查——内嵌版校验前缀是 `data:image/`，外链版才用 `os.path.exists()`，别靠截图验证。

## 六、坑

- 中文风格词直接喂 Bing 图片搜索 = 废（拆词匹配 SEO 垃圾内容）。
- 抓完必须先看拼图再定稿：水印、裁切、多图拼接（一张图里塞 4 张）在标题里看不出来。
- 用户说"十几张"= 15~20 张；每类 6 张、共 18 张是好用的规模，再多他挑得烦。
- ⚠️ **抽象名词 + 技术词 = 废图陷阱**（2026-09-24）。搜「3D渲染 写实 静物」→ 360 返回的全是**网课/软件下载/教程截图**（废图率 ~65%）。**改搜"画面内容"而非"技术手段"**：换成「超写实 静物 油画」立刻命中满分（油画/摄影/渲染三类画面都能出）。规律：**搜索引擎只认得出"画面里有什么"，认不出"怎么做出来的"**。
- ⚠️ **Bing 在这个网络环境下连英文词也废**（2026-09-24）。`cn.bing.com/images` 搜 `photorealistic 3d render still life` → 返回中文教程/下载站（被拆词匹配 SEO）。**不要指望 Bing 兜底，优先 360**。
- ⚠️ **脚本 import 陷阱**：老抓图脚本（`fetch360.py` 等）**没有 `if __name__ == "__main__"` 保护**，`from fetch360 import search, dl` 会把整轮旧抓取再跑一遍、并覆盖旧产物。→ 要么改用 `if __name__` 保护后的脚本，要么**把 search/dl 内联进新脚本**。
- 这些图**只用于内部风格标定**，不进任何交付物；商业化交付里用自摄/程序化素材（版权红线见 `ui-replication-lab`）。
- **交付形态**：50 张按 6 列拼一张总览（每格约 296×200，1776 宽可读），**对话里直接发这张**；另出 base64 内嵌的单文件 `index.html`（网格 + 点击放大），他能放大核对编号。⚠️ 这类图**不发布上线**（素材版权），只给本地单文件 + 对话拼图。
```

#### web-motion-craft

- 来源: 自建
- 说明: 网页「人类喜欢的 3D 动效」技法总库与实现规范。按驱动来源分四族十六技法：指针驱动（力场排斥/磁吸/视线跟随/3D 倾斜）、滚动驱动（主视觉重组/卡片堆叠/环绕/深度分层）、环境驱动（粒子漂移/噪声流场/辉光呼吸/流体）、状态驱动（液态按钮/点击涟漪/光标拖尾/加载叙事）。含 ThreeUI 组件索引、生产级工程铁律（IntersectionObserver 控 rAF / ResizeObserver / hue-rotate 换色 / dispose）、无头验证法、验收标准（FPS≥55 + reduced-motion 降级）。当用户说"优化视觉效果/加动效/3D 效果/鼠标交互/力场/环绕/眼神跟随/动效实验室"时触发。
- 路径: `C:\Users\lenovo\.workbuddy\skills\web-motion-craft\SKILL.md`

```markdown
# 网页 3D 动效技法库（Motion Craft）

> 2026-09-24 建立。黄总要求：从「风格」转向「视觉效果（3D 动效）」，因为**人类天生偏好 3D 动效**（深度感 + 因果控制感 + 活物错觉）。
> 配套已有资产：skill `parallax-research`（五类视差/滚动范式 + 原理笔记）、`生成物/五类交互效果/`（36KB 零依赖 demo）。

## 一、四族十六技法（按**驱动来源**分，这是唯一正确的切法）

| 族 | 驱动 | 心理杠杆 | 技法 |
|---|---|---|---|
| **指针驱动** | 鼠标/触摸 | **因果控制感**（我动→立刻应，可逆） | 力场排斥、磁吸吸附、视线跟随、3D 倾斜 |
| **滚动驱动** | 滚动 | **叙事 + 揭示 + 蔡格尼克闭合** | 主视觉重组、卡片堆叠、环绕 360°、深度分层 |
| **环境驱动** | 时间（无输入） | **氛围底色**（页面"活着"，不抢戏） | 粒子漂移、噪声流场、辉光呼吸、流体模拟 |
| **状态驱动** | 交互事件 | **反馈即奖励**（确认我操作生效） | 液态按钮、点击涟漪、光标拖尾、加载叙事 |

**为什么这样分**：驱动源决定了**工程实现完全不同**（指针=rAF 节流写目标值；滚动=sticky+归一化进度；环境=纯时间 uniform；状态=事件回调）。混在一起会写出互相打架的代码。

### 黄总点名的六种 = 交付主线（2026-09-24 确认，优先级最高）

他列的是「人类最喜欢的 3D 动效」，不是从技术角度分的。**这六种必须全部落地，且彼此可对比**：

| # | 技法 | 驱动 | 一句话本质 |
|---|---|---|---|
| 1 | 视线跟随 | 指针 | 眼快头慢，靠**克制**成立（瞳孔十几 px、头十几度） |
| 2 | 固定主视觉重组 | 滚动 | 散点聚成主视觉，**滚动进度是唯一时间轴** |
| 3 | 章节覆盖 + 卡片堆叠 | 滚动 | 用**位置**表达"读完了"，不需要文案 |
| 4 | 微缩景观视差 | 指针 | 俯视 × 浅景深 × 空气雾，三者缺一即退回普通风景 |
| 5 | 角色环绕旋转 | 滚动 | 公转 + **反自转**叠加；**且必须填满画面** |
| 6 | 视差滚动 | 滚动 | 速度差 → 纵深；skew → 动量可见 |

> **关于"五种"的口径**：黄总早期记的五类是「视线跟随 / 固定主视觉重组 / 章节覆盖·卡片堆叠 / 微缩景观 / 角色环绕」。这次的六种 = 那五类 + 视差滚动 + 把"指针力场"并入指针族。**以本表为交付口径。**

### 🚨 硬规则：不留白（2026-09-24 黄总下达）

**「Number 5 这种留白太多的，以后也不要出现在网页上。」**

否掉的那一版就是「孤环 + 大片空场」——一个环绕环悬在暗底中央，四周什么都没有。规则落成三条：

1. **主体必须撑到画布边缘**：环绕类把半径顶到边缘（元素允许部分溢出），宁可裁掉也不留边。
2. **背景必须有信息**：网格 / 放射线 / 轨道点 / HUD 框架 / 标尺刻度 —— 至少上两种。**纯渐变底不算填充。**
3. **四角不许空**：加角标、读数、标尺把它占掉。留白的反义词是「信息密度」，不是「元素多」。

判断线：**把画面缩到 25% 看，如果大片区域看不出任何结构，就是留白超标。**

## 二、三个旗舰技法的**真实机制**（实测，不是猜的）

### 1. 指针力场（Pointer Force Field）— Active Theory / Codrops 系
**错误直觉**：每帧遍历所有粒子算距离 → 几万粒子就卡死。
**真实做法（两条路线）**：
- **纹理路线（推荐，Codrops 2019）**：把指针位置**画到一张离屏 canvas**，连同**历史位置**形成轨迹；canvas 作为纹理传进 shader（`uTouch`），顶点着色器里**按纹理亮度位移粒子**：
  `displaced.z += t * 20.0 * rndz; displaced.x += cos(angle)*t*20.0*rndz;`
  好处：天然带 trail、可对轨迹半径做 easing（有生长/收缩的呼吸感）、全在 GPU 并行。
- **GPGPU 路线（百万级，Codrops 2024）**：位置/速度存纹理，每帧用 GPUComputationRenderer 算；传 `uMouse`(vec3) + `uMouseSpeed`(float) 两个 uniform，速度场里做推斥：
  `velocity *= 0.7;  // 松弛`
  `velocity += direction * 0.0003; // 回归原位的引力`
  **关键**：`uMouseSpeed` 由**指针位移距离**算（`dist*500` clamp 到 1），不是恒为 1——所以**静止的指针不产生力**。
- **因果链**：指针 → 归一化屏幕坐标 → 力场中心 → 粒子位移 → 视觉"我搅动了这个场"。

### 2. 环绕（Orbit）— 环绕球 / 产品 360 展示
- CSS3D 版：`angle = progress*360`；N 个元素排环 `rotateY(i*360/N) translateZ(R)`，整体 `rotateY(angle)`；主体**自转** `rotateY(-angle*0.42)`（公转+自转叠加才真实）；`transform-style: preserve-3d` **必须逐级传递**。
- WebGL 版：同源于 `applyAxisAngle` 绕 target 旋转 + `lookAt` 同步（three.js orbit camera）。
- ThreeUI `OrbitalSphereBackground` 是 React 壳 + 独立 renderer，**换色靠 CSS `filter: hue-rotate(Ndeg)`**（一行换主题，零 shader 改动）。

### 3. 视线跟随（Gaze / Cursor Tracking）
- 指针归一化 `[-1,1]`：`n = (clientX/innerWidth - 0.5) * 2`
- `mapRange` 映射到**很窄**的输出幅度：瞳孔 ±22px、头部 ±12° —— **克制是关键**，幅度大了立刻像坏掉的玩具。
- lerp 缓动（0.06~0.1）+ **rAF 节流**（绝不每个 `pointermove` 都写 transform）。
- **二次运动**：头部 `rotateX/Y` 幅度 > 瞳孔位移 → "头带眼"的层次感。
- 坑：`pointerleave` / 切 tab 要回中；`pointer:coarse` 直接隐藏。

## 三、生产级工程铁律（从 ThreeUI 真实源码读出，非推测）

```js
// ThreeUI OrbitalSphereBackground 的做法（实读源码）
const ro = new ResizeObserver(() => { r.resize(w,h); r.render(); });
const io = new IntersectionObserver(([e]) => {          // ⭐ 不可见就停
  vis = e.isIntersecting; vis && !raf && (raf = requestAnimationFrame(loop));
  !vis && raf && (cancelAnimationFrame(raf), raf = 0);
});
// 卸载时 ro.disconnect(); io.disconnect(); r.dispose();
```

| 铁律 | 做法 | 为什么 |
|---|---|---|
| **可见才跑** | `IntersectionObserver` 控制 rAF 开关 | 滚出视口的 3D 场景还在跑 = 白烧电和帧率 |
| **尺寸用 RO** | `ResizeObserver` 而非 window.resize | 容器变化（侧栏展开）也能响应 |
| **换色用 filter** | `hue-rotate(Ndeg)` / `CSS var` | 一行换主题，不动 shader |
| **单一 rAF 循环** | 所有动效共用一个 loop，事件只写目标值 | 杜绝 layout thrash |
| **必须 dispose** | 几何/材质/纹理/renderer 全清 | SPA 反复挂载会漏显存 |
| **降级优先** | `prefers-reduced-motion` + `pointer:coarse` | 眩晕风险 + 移动端性能 |

## 四、ThreeUI 动效组件索引（103 个组件里的可用矿）

- **环绕/几何**：`OrbitalSphereBackground` `GlobeCollection` `PortalFieldCollection` `CharacterCarousel`
- **粒子**：`ParticleDrift` `ParticleNetwork` `ParticleWordmark` `ConstellationField` `EmberStorm` `BellFieldBackground`
- **流场/流体**：`FlowField` `FluidFieldBackground` `FluxVortex` `GatewayFlow` `HalftoneFlow` `RibbonFieldBackground`
- **场/网格**：`DataField` `DimensionalField` `LogicCoreField` `ExpanseField` `ElementsBackground` `DotMatrixBackground`
- **按钮/状态**：`LiquidMetalButton` `PlasmaButton` `ShaderButtons` `IgnitionButton` `LaunchButton` `InductionButton` `GenerateButton` `GradientPillButton`
- **文字/字形**：`MorphingGlyphCloud` `NeonTypography` `OutlineTypeflow` `AudioWordmark`
- **角色/生物**：`CharacterWave` `CharacterFilmstrip` `KoiStudies` `BallStudy` `ClothStudy` `RippleStudy` `SemanticBloom`
- **CDN 直取单文件**：`https://cdn.jsdelivr.net/npm/@designcodeio/threeui/lib-dist/package-components/<Name>.js`
  （注意：该路径多为 re-export 存根，真源码在 `lib-dist/shaders/<group>/<Name>.js`）

## 五、验收标准（不达标不算完成）

1. **真交互**：headless 下用 synthetic `PointerEvent` 或直接注入内部状态，**截图证明动效真的发生了**（不是静止帧）。
2. **性能**：FPS ≥ 55（帧时 < 18ms @ 桌面）；粒子数/绘制调用要报数。
3. **降级**：`prefers-reduced-motion: reduce` 下动效停或极弱；`pointer: coarse` 隐藏指针类效果。
4. **Console 零报错**；`dispose()` 可重入（反复挂载卸载不泄漏）。
5. **首屏克制**：hero 静或极小动，动效等用户第一次主动交互再开始。**绝不 scroll-jacking**。
6. **不留白**（黄总硬规则）：缩到 25% 看，任何大片区域都要能看出结构。环绕类半径顶到边缘，背景至少两种信息层（网格/放射线/轨道点/HUD/标尺）。
7. **可对比**：交动效时必须给「A/B 双槽 + 共享输入」的工作台形态，不能只给一个跑起来的页面 —— 他要能自己改参数看出差别。

## 五·补、工作台形态（2026-09-24 定型）

黄总要的不是 demo 页，是**能对比、能改参、能动的工作台**。已验证可用的架构：

- **A/B 双槽**：两套独立参数，**吃同一个指针/滚动输入**（这是关键 —— 输入不同则差异不可归因）。
- **滚动驱动的技法用「归一化进度」而非真实 scroll**：进度可编程 → 能并排、能截图、能写进 URL。用真实 scroll 就没法对比。
- **参数表要带 hint**：每个滑块下面写「这个参数在物理上干什么 / 拉到极端的后果」。参数名本身不传达信息。
- **快照库**：localStorage 存整套参数，命名如「克制 vs 夸张」。预置几组**能一眼看出差别**的对比快照，他打开就能玩。
- **导出**：写「参数 + A→B 差异 + 敏感度 + 原理正文 + 验收标准 + 一键复现 URL」的纯文本投喂包。
- **URL 可寻址**：`?tech=x&prog=0.45&snap=2&shot=70&ab=1` —— 状态可分享、可复现、可截图。

## 六、无头验证管线（2026-09-24 实测踩坑记录，最值钱的一节）

**核心结论：本机 `chrome.exe` / `msedge.exe` 无头截图必崩，必须用 `chrome-headless-shell.exe`。**

| 症状 | 真因 | 解法 |
|---|---|---|
| `GPU process exited unexpectedly: exit_code=-1073741819` | 完整版 chrome 的 GPU 进程在本机崩溃（0xC0000005 访问冲突） | 换 **`%LOCALAPPDATA%/ms-playwright/chromium_headless_shell-1243/chrome-headless-shell-win64/chrome-headless-shell.exe`**（无 GPU 进程）+ `--no-sandbox --disable-gpu` |
| `Sandbox cannot access executable ... 拒绝访问 (0x5)` | 外层沙箱限制浏览器 exe | headless-shell 路径不受限；加 `--no-sandbox` |
| 用 `--virtual-time-budget` 就一直不返回、被 timeout 杀 | **页面有无限 rAF 循环 → 虚拟时钟永远等不到 idle** | 页面加 `?shot=N`：跑够 N 帧就 `return`（不排下一帧） |
| 截图全黑（几 KB 纯色） | `#fragment` 滚动 + `sticky` header + `100vh` 在 headless-shell 里重绘失败 | 加 `?only=sN`：把其他段 `display:none`，让目标段自然处于首屏（不靠滚动） |
| 5000 粒子时空白/超时 | 软件渲染每帧几万次 draw call | `?n=1000` 降粒子数（页面内置性能档位参数） |

**命令模板**（实测可用）：
```bash
HS="$LOCALAPPDATA/ms-playwright/chromium_headless_shell-1243/chrome-headless-shell-win64/chrome-headless-shell.exe"
"$HS" --no-sandbox --disable-gpu --hide-scrollbars --window-size=1400,880 \
      --virtual-time-budget=3000 --user-data-dir="$TMP/shot" \
      --screenshot="out.png" "file:///.../index.html?n=1600&shot=110&only=s1"
```
**判成功**：stdout 必须出现 **`N bytes written to file ...`**。没有这句就是失败——**别用"文件是否存在"判断**（会误判成超时留下的旧文件）。

**页面侧要预留的三个截图参数**（写动效页时一次做好，省下后面所有折腾）：
- `?shot=N` —— 跑 N 帧后停 rAF（让无头虚拟时钟能 idle）
- `?only=sN` —— 只渲染某一段（绕开 fragment 滚动重绘失败）
- `?n=数量` —— 性能档位（软件渲染 / 低端机）

## 七、坑

- **headless 无 GPU 跑不动重 WebGL**（2026-09-23 实测：swiftshader 软件渲染 kage 类页面超时 300s+）。→ 验证优先用 **Canvas2D / CSS3D 版**，或只验证逻辑不验证画面，绝不用截图失败当"做不到"。
- **`pointermove` 高频**：只写目标值，渲染时统一写样式。
- **无头里没有真指针**：`PointerEvent` 可合成，但依赖 `clientX/Y` 的代码要确认坐标被正确读取。
- **别堆砌**：彩虹色带 + 全屏视差 + 到处粒子 = 廉价。**restraint beats excess**。
- **版权红线**：ThreeUI 是 Community 开源，但**字体/纹理另有授权**（`FONT-LICENSES.md`）；商用交付必须换成程序化纹理 + SIL/OFL 字体。

### Canvas 2D 的性能雷（2026-09-24 实测）

| 雷 | 症状 | 替代方案 |
|---|---|---|
| `ctx.filter='blur(Npx)'` 叠多层 | **无头截图直接超时**（6 层全宽 blur = 每帧 6 次全画布卷积，软件渲染必死；GPU 也只是勉强） | **混色替代**：把远景色向雾色 `lerp`（`mixHex`），视觉等价、开销低两个数量级。剪影本身没纹理，糊了也看不出差别 |
| 每帧重建大路径（山脊逐像素 `lineTo`） | 帧率随宽度线性掉 | 步长给到 5px 以上；层数够就停 |
| 每帧 `getImageData` | 极慢 | 只在参数变化时算一次，结果缓存进 state（**缓存 key 必须含 W/H**，resize 要重算） |

**通用原则**：Canvas 2D 里凡是"每帧全画布卷积"的操作（blur/shadowBlur 大范围/低 alpha 全覆盖叠加）都要先问一句——**能不能用颜色或 alpha 近似？** 大多数时候能。
```

#### parallax-research

- 来源: 自建
- 说明: 研究顶级视差滚动/鼠标交互网站（Apple/Active Theory/Lusion/Cuberto/Awwwards/ThreeUI 等），拆解"为什么能做成这样"的原理（生理深度感知/滚动即连续输入/注意力引导/因果控制感/揭示叙事 + 技术：归一化进度/分层速度/lerp 缓动/rAF 节流/sticky scrub/velocity/WebGL+CSS3D 深度带），并产出"成果表 + 检验用单文件 demo"。覆盖五类高频交互范式：鼠标视线跟随、滚动固定主视觉重组、章节覆盖与卡片堆叠、鼠标微缩景观视察、滚动角色环绕。当用户说"研究视差网站/做视差滚动页/学顶级站原理/学这几类交互效果"时触发。
- 路径: `C:\Users\lenovo\.workbuddy\skills\parallax-research\SKILL.md`

```markdown
# 顶级视差滚动研究 + 构建

## 一、研究框架（找对标 → 拆原理 → 列成果表）

### 必研究的顶级站（对标母矿）
- **Apple 产品页** — 全幅 hero + 克制 scrub 揭示，行业标准制定者
- **Active Theory** — WebGL 粒子力场，鼠标即力场中心（因果控制感天花板）
- **Lusion** — 流体/丝绸粒子，连续响应
- **Cuberto** — 磁吸排印，指针=形变源
- **Awwwards "30 个出色视差站"** — 索引母矿（TAG Heuer/Gucci/Squarespace…）
- **Firewatch / The Boat / PORSCHEvolution / SpaceX / NASA Prospect / Every Last Drop** — 深度/叙事/多感官范例
- **ThreeUI** — `threeui.com` / `github.com/MengTo/threeui` / npm `@designcodeio/threeui`，生产级滚动驱动 3D 组件库（与 skill 目录同等待遇，任何 AI 随时调取）；**拉取与引用其模板/排版预设的具体做法见 skill `threeui-integration`**
- 引擎层：**GSAP ScrollTrigger**、**Lenis**（平滑滚动）必知

### 五类高频交互范式（2026-09-21 补 · 每类都要能"为什么")
| 范式 | 驱动 | 一句本质 | 核心技术 |
|---|---|---|---|
| **视线跟随 Gaze** | 鼠标 | gaze cueing：被注视=活物错觉 | 归一化指针 → `mapRange` 限窄幅(±22px) → lerp + **rAF 节流**；头 `rotateX/Y` 幅度大于瞳孔=二次运动 |
| **固定主视觉重组** | 滚动 | 揭示叙事 + 蔡格尼克闭合 | runway 300-420vh + `sticky 100vh`；`p=clamp((scrollY-top)/(H-vh))`；0→0.6 归位(easeOut+错峰)/0.6→1 发光；缓存 trackTop |
| **章节覆盖／卡片堆叠** | 滚动 | 发牌隐喻：秩序 + 层叠纵深 | 卡 `inset:0` 同 footprint、`transform-origin:top center` 露顶；`enter=easeOut(clamp((p-i/n)/(1/n)))`；三通道 scale+dim+lean **+ 上移露顶**；速度后倾；降级竖列 |
| **微缩景观视察** | 鼠标 | 微缩错觉 = 俯视 + tilt-shift | `perspective` + `rotateX(58)rotateZ(-38)`；`translateZ` 高度块(顶亮侧暗)；`mask` 上下渐隐做移轴；指针映射视角 |
| **角色环绕** | 滚动 | 从"看背景"→"检视展品" | `angle=p*360`；环 `rotateY(i*360/N) translateZ(R)` 整体 `rotateY`；主体自转 `-angle*0.42`；`preserve-3d` 逐级传递 |

### "为什么有效"五原理（现象→本质）
1. **运动视差本能** — 近物比远物快是大脑硬编码深度线索，伪造即读出 3D
2. **滚动=连续输入维度** — 进度 0→1 把叙事/时间映射成空间位移，浏览变"穿越"
3. **注意力对比引导** — 慢层锚定、快层抓眼，自然引导视线
4. **因果控制感** — 我滚→世界应，符合自我效能，提升沉浸
5. **揭示式叙事** — 元素渐进显形，信息分章投递，降认知负荷

### 马哲读法（指导迭代）
- 对立统一：深度(远·静) 与 运动(近·动) 同一效果两面，守恒深度感+兑现速度差
- 质量互变：强度量变跨关节点成极致；负向量变叠加成眩晕 → restraint > excess
- 否定之否定：CSS 背景位移 → JS 滚动链接 → WebGL/Three.js 深度带，螺旋上升保留"滚动即穿越"内核
- 实践第一：真滚动真点真渲染才算验证

## 二、构建检验 demo 的可复用工程真理（单文件、零外部依赖）

```js
// 1. 归一化滚动进度 —— 一切动画的时间轴
const p = scrollY / (scrollHeight - innerHeight);
// 2. 分层速度（视差本质一条规则）：近层 speed 大、远层小
y = home.y + p * speed * k;            // 近快远慢 = 深度
// 3. lerp 缓动消机械感 + 跨屏一致（乘 dt）
cur += (target - cur) * lerp * dt;
// 4. 指针视差第二轴（camera-group 式）
cameraGroup.x += (mouse.x - cameraGroup.x) * 0.06;
// 5. velocity 第二变量驱动 skew/blur
v = p - p_prev;  velText.style.transform = `skewX(${clamp(v*900,-14,14)}deg)`;
// 6. sticky scrub：钉住容器，progress 直映射旋转/缩放
ring.style.transform = `rotate(${sp*720}deg) scale(${0.6+Math.sin(sp*PI)*0.7})`;
```

- GPU 合成：`translate3d`/`perspective` 触发合成层；`will-change: transform` 预提升
- 降级：`@media (prefers-reduced-motion: reduce)` 关动效；移动端以响应式为基线，盯 Core Web Vitals
- WebGL 升级：DOM 层 → 3D 物体 + Z 深度带，UV 视差在 GLSL 做（ThreeUI / @react-three/fiber）

## 三、交付物模板
- `table.html` — 暗色仪表盘成果表：站名/URL、类型、为什么有效、关键技术、ThreeUI 对照
- `parallax-lab.html` — 检验 demo：hero 鼠标视差(lerp) / 分层深度 / sticky scrub / velocity 反应式 / ThreeUI 资源面板 / 原理回顾
- `视差原理笔记.md` — 深度拆解 + 马哲 + ThreeUI 引用
- `五合一 demo` — 五类范式各一章（视线跟随/主视觉重组/卡片堆叠/微缩景观/角色环绕），零依赖单文件（2026-09-21，`生成物/五类交互效果/index.html` + `原理笔记.md`）
- 通宵续跑可用 recurring automation（每小时追加一个站点到 `RESEARCH_LOG.md`）

## 四、坑
- **鼠标类必须 rAF 节流**：`pointermove` 高频，别逐事件写 `transform`；`pointerleave`／切 tab 要回中；`pointer:coarse` 隐藏自定义光标。
- **首屏克制、禁止 scroll-jacking**：hero 静或极小动，动效等用户主动滚动再开始；滚动应永远推动页面前进，pin 一拍后释放（弱站＝劫持滚轮自己播，用户会走）。
- **卡片堆叠**：`zIndex` + `transform-origin` 决定"覆盖 vs 被顶开"；深度设 cap 防叠太高。
- **无头验证滚动中间态**：headless 里 `window.scrollTo` 不可靠 → `Object.defineProperty(window,'scrollY',{get})` 接管成 mock + 把目标章之前内容 `display:none` 顶到首屏，即可截任意中间态。
- 纯 CSS 背景位移在移动端/可达性上易翻车 → 关键动效用 JS 滚动链接 + 降级
- 彩虹色带/全屏视差堆砌 = 廉价 → 克制（restraint beats excess）
- CDN 在离线/中国网络可能失败 → demo 默认零外部依赖，ThreeUI 仅作引用与"生产级路径"说明

## 五、长任务/通宵 automation 实操要点（2026-09-20 实测）
- 用 recurring automation 做"夜间/通宵续跑"可行：每次只追加 1 条到 `RESEARCH_LOG.md`，子代理要判定"已覆盖则跳过"防重复。
- **validUntil 必须设到用户醒来时间之后**（如 09:30+），否则到点自然停，用户醒时已有空窗（本次 validUntil=07:30 太早，08:00 后断档被质问）。
- 对话在用户离开后会中断，靠定时器续跑而非 AI 在线连干——**必须在交代时明确告诉用户"对话会断、后台 automation 在跑"**，否则用户以为 AI 一直在、醒来质问"为什么没通宵"。
- 清单要一次给全、覆盖完整；automation 触发次数有限（每小时 1 次），设早停会只跑一部分（本次 15 站只触发 6 条）。
- 醒后第一件事：查 `RESEARCH_LOG.md` 的 mtime 确认续跑确实触发，再补齐剩余项，最后把成果表 footer 的"明早不停"类措辞改掉，别留误导。
```

#### webgl-terrain-hero

- 来源: 自建
- 路径: `C:\Users\lenovo\.workbuddy\skills\webgl-terrain-hero\SKILL.md`

```markdown
---
name: webgl-terrain-hero
description: 用 Three.js 在单文件网页里做「像真实自然风景」的 3D 地形 hero 场景。两种形态：①单块顶光岩壁 + 缝隙熔岩发光（Lithos/MotionSites 那类暗色高级感站）；②多层层叠远山 + 日落大气透视（真实风景照片感）。当用户要复刻"暗底 + 白色衬线大标题 + 3D 岩石山脊"、或要求"自然的自然景色 / 力求真实感 / 不要一眼假 / 要真实地貌"、或任何"滚动驱动的 WebGL 地形叙事"时使用。含真实感六件套（IBL 环境光/自阴影/程序化微法线/顶点 AO/玄武岩反照率/大气雾）与"一眼假"的成因排查。**森林 / 植物 / 树 也在此域**：高斯泼溅（手写 splat）树冠 + ThreeUI 真实照片素材做近景植物 + 远树圆锥 LOD 顶点色烘光 —— 用户说"植物太假""树太假""要 ooosplat / 高斯泼溅 / 泼溅"时直接看森林章节。**质感三件套（地面 / 树 / 云）也在此域**：用户说"地面质感""树太假""云的质感""要像苔藓 / 云海那样""细节不够 / 太糊 / 太平"时看「质感三件套」章节（含 detail 指标靶子、细节跨 3 个数量级铁律、window.__scene 逐个隐藏排查法）。
agent_created: true
---

# WebGL 地形 Hero（Lithos 风格）

复刻 `Lithos — Layers hold tales of time` 那类站的 hero：近黑底、白色衬线斜体大标题、
前景一条顶光照射的 3D 山脊，缝隙里渗出橙色熔岩发光。单文件、CDN 引 three.js。

## 🚨 悦皓的视觉偏好（2026-09-20 下达 · 默认遵守，不必每次问）
他原话：「人类比较喜欢更类似于自然风景的样子」＋「另外做成视差滚动，这也是人类非常喜欢的效果」。

1. **自然风景感优先**：默认往真实地貌、自然体量走（山脊/岩层/地平线/雾霭/天光）。避开抽象几何堆砌、纯渐变色块、赛博网格、扁平插画。判断标准：一眼看去像"自然里存在的东西"。
2. **视差滚动是硬需求**：网页默认必须带分层深度 + 滚动驱动场景变化（下潜/揭示/强度递进）。只做静态单屏 hero 不算完成。

## 参考基准（原视频实测）
- 底色近纯黑 `#040404`；标题白色衬线斜体（Instrument Serif Italic），两行、字号约 110px。
- 导航：左上文字 logo、中间玻璃胶囊菜单、右上白色胶囊按钮。
- 左下角小字段落 + 右下角小字 + 橙色胶囊 CTA。
- 地形：中央主峰、两侧余脉，脊线在画面**下三分之一**，缝隙发光沿坡面蜿蜒流下。

## 最关键的 6 个已验证参数（照抄，不要凭感觉调）

### 1. 高度场：必须用 ridged 噪声 + 值噪声插值
```js
// 值噪声 + smoothstep 双线性插值：直接采样 Math.sin(...) 会得到尖刺
function vnoise(x,y){
  const xi=Math.floor(x), yi=Math.floor(y), xf=x-xi, yf=y-yi;
  const u=xf*xf*(3-2*xf), w=yf*yf*(3-2*yf);
  const a=noiseA(xi,yi), b=noiseA(xi+1,yi), c=noiseA(xi,yi+1), d=noiseA(xi+1,yi+1);
  return (a*(1-u)+b*u)*(1-w) + (c*(1-u)+d*u)*w;
}
// ridged：1-|noise| 把"山谷"翻成"山脊"，连续锐利折线 = 岩脊
// 乘 prev 做 octave 衰减，避免高频盖过低频
```

### 2. 噪声频率要低（这条最容易翻车）
- 主岩脉 `ridged(u*2.1, v*1.15, 5)`、中频 `u*5.6, v*2.80`、细节 `u*12, v*6`。
- **沿 v 的频率要压得比 u 更低**（约 0.5 倍）→ 噪声被拉长成"层理"，而不是满地颗粒。
- 只要高频振幅超过 ~0.1，细分平面立刻变成"沙丘尖刺"。实测振幅 0.58/0.225/0.085/0.032 是好的配比。

### 3. 平面朝向：**先判断主体形态，再决定**（见上方"两种朝向"章节）
```js
// A. 俯视地面（站在山坡上往下看）
terrain.rotation.x = -Math.PI * 0.5;   // 躺平成水平地面，高度朝 +Y
terrain.position.y = -1.05;            // 压到画面下三分之一
terrain.position.z = -1.6;             // 往里推，近边靠近相机
// 相机 position.y ≈ 0.46、z ≈ 3.55，lookAt(0, 0.16, -2.0)

// B. 正面岩壁（Lithos 原片 —— 优先用它复刻 Lithos！）
//    不旋转；高度写进 Z；相机几乎平视。完整参数见"两种朝向"章节。
```
转成 `-0.44π` 会让地形像"天花板倒挂的刺"。

### 4. 裂纹发光：窄带 mask，不要整片
```js
// 蜿蜒的裂缝线：用 ridged 噪声做横向扰动
const wob = ridged(u*2.4, v*0.9, 3) * 0.40;
const d1 = Math.abs(u - 0.50 + wob);
const w1 = Math.pow(clamp(1 - d1*15.0, 0, 1), 2.1);   // 高次幂把带宽压窄
// 断续：岩浆一段段渗出，不是实线
const drip = Math.pow(clamp(Math.sin(v*7.5 + u*3.2)*0.5 + 0.62, 0, 1), 1.5);
crackData[i] = clamp(max(w1, w2*0.9, ...) * drip * nearMask, 0, 1);
```
放进自定义 attribute `aCrack`，inject 到 `MeshStandardMaterial` 的 emissive：
```js
mat.onBeforeCompile = (sh) => {
  sh.uniforms.uTime = { value: 0 };
  sh.vertexShader = 'attribute float aCrack;\nvarying float vCrack;\nuniform float uTime;\n' + sh.vertexShader;
  sh.vertexShader = sh.vertexShader.replace('void main() {',
    'void main() {\n  float flick = 0.62 + 0.38*sin(uTime*1.35 + position.x*1.6 + position.y*2.4);\n  vCrack = aCrack * flick;\n');
  sh.fragmentShader = 'varying float vCrack;\n' + sh.fragmentShader;
  sh.fragmentShader = sh.fragmentShader.replace('#include <emissivemap_fragment>',
    '#include <emissivemap_fragment>\n  float ck = smoothstep(0.12, 0.72, vCrack);\n  totalEmissiveRadiance += vec3(1.0, 0.30, 0.045) * ck * 3.4;\n');
};
```
> `smoothstep(0.12, 0.72, ...)` 这个下限是"整片橙色"和"缝隙透光"的分界线，别省。

### 5. 光照：高对比顶光，环境光压到最低
```js
new THREE.AmbientLight(0x141216, 0.42);              // 极暗环境
const key = new THREE.DirectionalLight(0xffeed4, 1.85);
key.position.set(-5.2, 6.8, 1.4);                    // 高位 + 偏左后 → 一侧亮一侧黑
const fill = new THREE.DirectionalLight(0x6f89ab, 0.22);
fill.position.set(5.0, 1.4, -4.0);                   // 冷补光压暗部层次
const glowL = new THREE.PointLight(0xff5a14, 1.9, 16, 2);
glowL.position.set(0, -0.35, 1.2);
```
`toneMappingExposure = 0.92`、`ACESFilmicToneMapping`。
只靠正面打光会变成"一团平光"，照不出起伏。

### 6. 顶点色：暗部必须压到近黑
```js
const t = clamp(h*0.50 - 0.06, 0, 1);
const g = 0.035 + Math.pow(t, 1.6)*0.30;   // 0.035 起跳 → 暗部近黑
colors[i*3] = g*1.06; colors[i*3+1] = g*0.94; colors[i*3+2] = g*0.86;
```
`g` 的起点给到 0.09 以上会变成"沙漠沙丘"。

## ⚠️ 两种朝向，先分清再动手（2026-09-21 血的教训）

**这是整个 skill 最容易翻车的地方。前面连续 4 轮盲调参数全失败，根因就是朝向选错。**

| 参考片主体是什么 | 平面朝向 | 高度去向 | 相机 |
|---|---|---|---|
| **俯视的地面 / 地形**（如"站在山坡上看"） | `rotation.x = -π/2`（躺平） | +Y | 略高、俯视 |
| **正面的层积岩壁**（Lithos 原片！`Layers hold tales of time`） | **不旋转**（竖直 XY 平面，法线朝 +Z） | **+Z（朝相机凸出）** | **几乎平视、正对** |

判断方法：问"参考里那个岩体是躺在地上，还是像一堵墙立在我面前？"
- Lithos 原片是**一堵横贯画面的岩壁**（上缘是起伏的天际线，标题悬浮在它上方的黑空里），**必须用竖直朝向**。
- 用躺平朝向去做岩壁 → 相机看到的是地形边缘/切片 → 整屏黑或整屏贴图，调多少参数都救不回来。

竖直岩壁的完整配方（`lithos-real5.html` 实测有效）：
```js
const SX=460, SY=300, W=16.0, H=10.6;
const geo=new THREE.PlaneGeometry(W,H,SX,SY);   // 不旋转！
for(...){ const h=heightAt(u,v); pos.setZ(i,h); }  // 高度写进 Z
terrain.rotation.z = 0.13;                       // 只给一点点斜向走势
camera.position.set(smx*0.70, 2.30, 12.0);
camera.lookAt(0, -1.55, 0);
terrain.position.y = -2.75;                      // 岩体压到画面下半部
```

## 🏔 层叠远山（真实风景感）配方 —— 2026-09-21 实测新增

需求是「像真实风景照片」而不是「一块岩壁」时，用**多层层叠山脊**。
真实照片的本质：近处暗而锐、远处淡而蓝、光有方向、材质有颗粒。
（悦皓原话：「人类偏好那种很自然的自然景色，力求真实感」；判断假的标准是「明显就是编的」= 形状像但物理不对。）

### 几何：底部固定、顶部拉伸到山脊线（实心，不要 alpha 剪影）
每层是一块竖直平面（法线朝 +Z），把纵向顶点重映射成「底边不动、上缘跟着山脊线走」：
```js
const t  = 1 - Math.pow(1 - v, 2.7);            // 顶部（视线焦点）密、底部疏
const wy = o.bottom + t * (ridgeTop(u, o) - o.bottom);
const wx = (u - 0.5) * visW;                     // visW 按该层距离算，保证铺满视口
pos.setXYZ(i, wx, wy, o.z + wz);                 // 起伏写进 z
```
实心几何 → 可受光、可接雾、无透明排序问题。
层的世界宽度必须按距离算：`visW = 2*dist*tan(fov/2)*aspect*1.3`（1.3 为溢出余量），否则远层缩成一条。

### ⚠️ 三条决定性配方（错一条就"一眼假"）
1. **绝不在脊线顶部衰减 z 起伏** —— 那会把山脊压成纸片（我为此白跑一轮）。
   只在底部略收：`wz *= (0.55 + 0.45*clamp(t*3.2, 0, 1))`。
2. **表面起伏必须方向性**。各向同性噪声 → 明暗均匀斑点，读作「沙丘 / 斑纹布」。
   用**沿坡下切的沟壑**：ridged 的 x 频率高、y 频率压到 0.20 倍 = 水流侵蚀的纵向沟槽。
   ```js
   const gully = ridged(wx*o.gf + seed, wy*o.gf*0.20 + seed, 4, 2.0, 0.5) - 0.44;
   const wz = (n1*0.58 + gully*0.70) * o.depth;   // 低频权重要压过高频，明暗才成大块
   ```
   法线贴图同理：近层 `normalScale 0.06`、`repeat 1.0×0.5` 就够，给大了会撒"金粉"。
3. **雾色必须对齐天空地平线色温**，否则远山与天空「脱节」。远层靠 `FogExp²` 自动变淡变蓝 = 空气透视。

### 天空 = 背景 + IBL 一次做完
canvas 画等距柱状图（天顶冷蓝 → 地平线暖褐 → 太阳径向光斑），
`scene.background = tex` + `PMREMGenerator.fromEquirectangular(tex)` → `scene.environment`。零外部素材。
**卷云不能用高 y 频率噪声**（会变成横向扫描线），要用团块状低频（x 0.006 / y 0.010）。

### 近景该是剪影
日落时前景本来就背光。把最近层 tint 压到 0.015 量级、depth 收小 → 只留脊线附近的受光岩缘，
比"亮着的前景"真实得多。

### 相机：前推 > 人工平移层
人工给层做位移容易穿帮；让**相机真实前推**（z 62→40）+ 微升，
近层自动放大得多、远层几乎不动 —— 视差由透视自己产生，构图还稳。

## 🔑 高度量级：峰值必须 ≈ 宽度的 10%（关键比例）

**这是第二大致命坑。** 高度峰值给到 3.4（而平面宽 16，占 21%）时，岩体变成**伸向相机的巨大方块**，相机等于贴着岩面看，透视把层理放大成"横贯全屏的粗光带"。

```js
const H_MAX  = 1.55;    // 期望峰值
const H_SRC  = 3.402;   // 原始噪声函数的实测峰值（用 _probe.mjs 量出来）
function heightAt(u,v){
  const cont = hBase(u,v) / H_SRC;      // ← 先归一化到 0~1
  const q = cont*STEPS, fl = Math.floor(q), fr = q-fl;
  const eased = fr*fr*(3-2*fr);
  return ((fl+eased)/STEPS) * H_MAX * warp;
}
```
**写代码前先用独立脚本把 `heightAt` 的 min/max 量出来**（不要凭公式心算），再决定归一化系数。峰值/宽度控制在 **0.08~0.12**。

## 🎭 有机剪影：椭圆包络，不是边条 fade（让岩体"像自然的东西"）

平面是矩形，直接渲染会露出**四条直边**，一眼就是"贴图方块"。左右用 `clamp(u/d,0,1)` 收口**不够** —— 上下角仍会露出直角。
正确做法是**一圈不规则椭圆包络**：

```js
const eu=(u-0.50)/0.660, ev=(v-0.34)/0.560;
let rr = Math.sqrt(eu*eu + ev*ev);
rr += fbm(u*2.2,v*2.2,3)*0.075        // 包络本身也起伏，避免完美椭圆
    + ridged(u*5.0,v*5.0,3)*0.045;
const t = clamp((rr-0.60)/0.40, 0, 1);
let mask = 1.0 - t*t*(3-2*t);          // 1 → 0 平滑过渡

// 上缘再叠一条"脊线"，形成尖齿状山脊天际线
const ridge = 0.435 + 0.070*Math.sin(u*2.5+0.7)
                    + 0.048*Math.sin(u*5.1+2.0)
                    + fbm(u*1.9,0.0,3)*0.075;
const up = clamp((v-ridge)/0.075, 0, 1);
mask *= 1.0 - up*up*(3-2*up);
```
> 注意：脊线只用**低频**正弦+低频 fbm。加高频项会在上缘产生**梳齿状锯齿**，非常假。

## 🕯 熔岩：稀疏细缝，不是粗脉络

熔岩占比是**可用数值校准**的：参考片 `orange% ≈ 1.8`，纵向位置在 **75%**（画面下四分之一）。
粗脉络（`exp(-d*d*9000)`）会一路涨到 22%，整屏橙色雾 —— 那是**发光累加在暗底上被视角放大**的假象。
收细的正确组合（`lithos-real5.html`）：
```js
// ① 只在少数层位开裂（低频挑层）
const pick = smoothstep01(clamp(Math.sin(v*4.4)*0.5+0.5,0,1), 0.62, 0.92) * (0.35+0.65*…);
// ② 沿层理面：极窄 + 强次幂
const seam = Math.exp(-Math.pow(Math.sin(fr*Math.PI),2)*300.0);
// ③ 断续
const broken = clamp(Math.sin(u*9.5+ridged(u*3.2,2.0,2)*3.4)*0.5+0.5,0,1);
best = seam * Math.pow(broken,1.5) * pick;
// ④ emissive 也要压：(0.85 + uHeat*1.0)，别给 2.6
```

## 🎬 标题不显示 / bright% = 0（headless 截图特有陷阱）

`class="in"` 已加上、CSS 语法正确，但截图里标题不可见：**CSS 动画的 delay 依赖真实时钟，headless 的 `--virtual-time-budget` 不推进会停在 `opacity:0`**。
加兜底（同时不影响真机体验）：
```js
['nav','h1','meta','note','aside'].forEach(id=>{
  const el=document.getElementById(id); if(!el) return;
  el.classList.add('in');
  setTimeout(()=>{                                  // 1.4s 后强制落终态
    if(parseFloat(getComputedStyle(el).opacity) < 0.99){
      el.style.animation='none'; el.style.opacity='1'; el.style.transform='none';
    }
  },1400);
});
```
另外标题的 `text-shadow` 不要叠两三层重黑晕 —— 会把白字压成灰。用 `0 0 22px rgba(0,0,0,.55)` + `0 2px 30px rgba(0,0,0,.70)` 即可。

## 🧪 客观验证管线（图片看不懂时靠它，但**能看图就一定要看图**）

`_analyze.mjs` / `_cmp.mjs` / `_map.mjs` / `_bands.mjs` / `_probe.mjs` 这套 ffmpeg+Node 统计管线很有用，
**参考基准值**（Lithos 原片 1120×630 抽帧实测）：

| 指标 | 参考值 | 含义 |
|---|---|---|
| mean | **0.111** | 整体亮度 |
| black% | **46.5** | 近黑（L<0.05）占比 |
| bright% | **5.4** | 高亮（L>0.45）占比 ≈ 标题+白按钮 |
| avgRGB | **(33,27,30)** | 略偏暖的近黑 |
| orange% / row | **1.8 / 75%** | 熔岩占比与纵向位置 |
| bands | `0.18 0.09 0.05 0.10 0.03 0.11 0.08 0.17 0.20` | 9 横带亮度剖面 |

**但必须强调**：数值接近 ≠ 长得像。我曾在 mean 0.108 / black 47.1 / avgRGB 完全命中参考的情况下，
画面仍然是一块"歪斜的矩形平板"。**数值只用来收敛明暗，构图和几何必须人眼看图。**

「有地形 ≠ 像石头」。看着像灰模、像纸板的根因只有四个：没有反射、没有自阴影、没有凹凸、没有大气。
按顺序加这 6 件， realism 立刻上一个台阶（顺序即性价比）：

1. **IBL 环境光照**（没有环境光的 PBR 一定是塑料感）：用 canvas 画一条竖向渐变（天顶近黑 → 地平线岩浆红 → 地面黑），
   `CanvasTexture` + `EquirectangularReflectionMapping` → `PMREMGenerator.fromEquirectangular()` → `scene.environment`。
   材质 `envMapIntensity ≈ 0.85`。零外部资源。
2. **自阴影**（提升最大的一件）：
   `renderer.shadowMap.enabled = true; type = PCFSoftShadowMap`；主光 `castShadow`，阴影相机正交盒 ±6.5、`far 26`、
   `mapSize 2048`、`bias -0.0006`、`normalBias 0.035`。地形网 `castShadow = receiveShadow = true`。
   注意：会给每帧多一次深度绘制，网格别超过 ~450×250。
3. **程序化微法线**：512×512 `DataTexture`，对 `ridged(fx*4, fy*16, 4)*0.6 + ridged(fx*11, fy*30, 3)*0.4`（x 低频 y 高频 = 水平层理沟壑，竖壁各向异性）做有限差分求法线并归一化编码；
   **`repeat.set(1,1)` 整壁一张**、`normalScale 0.85`。补上顶点密度给不了的表面颗粒。绝不能 repeat>1 搭配各向异性纹理（见坑18）。
4. **硬朗化配方（2026-09-22 验证，解决"软/流动感"）**——岩壁假在"软"，根因是几何台阶用 smoothstep 软过渡。四件套一起上：
   - **硬断崖台阶**：`cliff = fr < 0.80 ? fr/0.80 : 1.0` 替代 smoothstep —— 层内 80% 是水平平台，末尾 20% 是陡坎，层间有真落差；
   - **垂直节理**（真岩石脆性开裂，比水平层理更"硬"的视觉锚点）：几何位移 `- pow(1-|sin(u*9 + fbm(v*3)*1.4)|, 6)*0.16*H_MAX`，同时微法线叠 x 向扰动 `- (jR-jL)*3.0`，粗糙度贴图节理处 +0.16；
   - **岩性明暗分带**：按层位索引给基色明度差（`g = 0.038 + band*0.030 + ...`，band 取 sin(层位)），层积岩互层立现；
   - 教训：改真实感**先动几何+纹理本体**，bloom/IBL/后处理只是最后 10%——只动后处理用户会"看不出来"。
4. **顶点 AO**（把"灰模"变成"实体岩石"的第二关键）：**不要在生成高度那遍就算**，
   等整片高度写完后，用**网格邻居**（步长 4）算局部均值，
   `ao = clamp(0.30 + 0.70*clamp((h-mean)*2.6 + 0.52, 0, 1), 0, 1)`，压进顶点色。一次性算，不进渲染循环。
   实测 AO 分布 min/mean/max ≈ 0.30/0.66/1.00 才有足够对比（步长取 4 个顶点）。
5. **反照率按真实玄武岩压暗**：`base = 0.038 + Math.pow(t,1.45)*0.34`，再乘 AO；近缝处混一点氧化铁红。
   实测乘完 AO 后落在 1%~38%、均值约 6%（真实玄武岩反射率量级）；起跳给到 0.09 以上就会变成"沙丘"。
6. **轮廓光 + 大气**：背侧一盏暖色 `DirectionalLight`（把脊线从黑背景里拉出来）+ `FogExp2(底色, 0.052)` 做大气透视。

## 鼠标：把它做成一支"火把"（用户明确要的效果）

单个 camera 位移太弱。组合这 6 个才知道"手上有东西"：
1. 指针视差（已有）加大幅度：`camera.position.x = smx*1.15`。
2. **跟随鼠标的点光源**投在山脊上方：位置 lerp 到 `(smx*3.4, 0.55-smy*0.85, -0.4)`，强度随指针**速度**上升（`1.35 + vel*1.5`）。
3. **主光方向随指针偏移**：`key.position.x = -5.4 + smx*1.9`。成本为零，但阴影会跟着转 —— 实体感提升最大。
4. **按住拖拽环视**：`targetDrag += movementX*0.0022` clamp ±0.22，驱动 `terrain.rotation.z` 与相机横向。
5. **火星被指针吹开**：shader 里加 `uniform vec2 uWind`，随生命周期放大位移。
6. 光标本身：外圈 + 内部暖色径向渐变，移动越快越大越暖（`scale(1 + vel*0.85)`），隐藏系统光标。

## 局部坐标 → 世界坐标（火星/粒子定位必用）

`rotation.x = -Math.PI*0.5` 时 local(x,y,z) → world(x, z, **-y**) + position。
所以对 `v∈[0,1]`：`world z = (4.5 - v*9.0) - 1.6`（近边 v=0 → z=2.9，远边 v=1 → z=-6.1），`world y = heightAt - 1.05`。

## 滚动的接入方式（复用 parallax 研究资产）
- **平滑的是动画值，不是滚动位置**：不劫持原生滚动、不动 body transform → sticky / 锚点 / 无障碍全保。
- 帧率无关 lerp：`a + (b-a) * (1 - Math.pow(1-l, dt*60))`。
- 相机随滚动下潜 + 指针视差（第二轴）：指针驱动 `camera.position.x`，滚动驱动 `y/z`。
- 地形淡出用**绝对滚动距离**判断（`scrollY - vh*0.35`），不要用归一化进度——页面总高会变，归一化会误判导致首屏就淡出。

## 坑清单（都是实测踩过的）
1. **变量重名**：页面里已有 `const sh`（shader）时，再声明 `const sh = document.getElementById(...)` 会抛 `Identifier 'sh' has already been declared`，整页黑屏。用 `hintEl` 之类具名变量。
2. **CDN 依赖**：`importmap` 引 `unpkg.com/three@0.160.0/build/three.module.js`。离线环境装不上 npm 的 three，CDN 是唯一路径——交付时说明这一点。
3. **本地 npm 装不了**：隔离工作区的 npm 无外网时安装会静默返回 "up to date"，`node_modules/three` 并不存在。别在这上面耗时间。
4. **无头截图验证**：`file://` URL 遇中文路径要 `encodeURI` + 手动拼 `file:///C:/...`；先复制一份 ASCII 文件名的副本再截，省掉转义麻烦。
5. **`page.goto` 报 ERR_FILE_NOT_FOUND**：多半是 URL 里混了未编码的中文路径。
6. **PowerShell 删文件无回显**：`Remove-Item` 在部分环境不生效也不报错，用 `[System.IO.File]::Delete()` 更可靠。
7. **Chinese path + PowerShell 输出编码**：`Out-File -Encoding utf8` 有时产出 UTF-16，读回是乱码，用 `[System.Text.UTF8Encoding]::new($false)` 写。
   实测更省事的写法：`& node script.mjs args | Set-Content -Encoding utf8 out.txt`，再直接 Read 那个 txt。
8. **PowerShell 里 `& node ... 2>&1 | Out-String` 会吞掉 stdout**：改用管道写文件再读。
9. **改 CSS 时漏掉闭合 `}`**：只删了 `text-shadow: a, b;` 结尾的 `;` 却忘了 `}`，会让**整个 `<style>` 之后的规则全部失效** → 页面回退到无样式（裸 HTML）。症状极好认：文字全裸、无布局、无字体。
   改完立刻跑括号配对检查（`_lint.mjs`）。
10. **`Read` 读 `.txt` 报 "Cannot display content of binary file"**：多半是文件被写成了 UTF-16 或含 BOM 异常。用 `Set-Content -Encoding utf8` 重写即可。
11. **每轮只调 1~2 个参数，并记录前后数值**。连续乱调 5 个参数会让你失去因果判断力 —— 我这次就是这样浪费了 4 轮。
    如果连续 2 轮调数值都没接近，**停手，回去质疑几何/朝向/相机，而不是继续调亮度**。
12. **删了变量必须全局搜引用**：删掉 `edge` 却漏了 `pos.setXYZ(i, wx, wy, o.z + wz*(...edge))` → 整页 ReferenceError 黑屏。
    `Edit` 删变量后立刻 grep 该名字。
13. **层平移系数别凭感觉**：`near = 1/dist^0.62` 对 dist=76 只有 0.07，层几乎不位移，看着像"滚动没生效"（我误判成 mock 失效）。
    要用归一化系数，如 `near = 110/dist`。
14. **headless SwiftShader 的 `--virtual-time-budget` 要压到 ~2600**：给 14000 等于要软渲 ~840 帧，必然 ETIMEDOUT。
    另外 `execFileSync` 只返回 stdout，**抓 console 必须用 `spawnSync` 读 stderr**（加 `--enable-logging=stderr`）。
15. **判断"滚动效果有没有生效"要看数字不要靠眼睛**：页面里 `console.log('[terra] scrollN='+...)`，
    截图时回读；单看 PNG 大小相近很容易误判。

16. **竖直岩壁的噪声频率轴与躺平地形相反**（2026-09-22 单人公司第一单实测，返工 3 轮的根因）：躺平地形（`rotation.x=-π/2`）里 v 是进深方向，所以"沿 v 频率压低 = 层理"；但竖直岩壁（不旋转）的 v 是屏幕竖直方向——层理必须**沿 u 低频拉长、沿 v 中频分层**（如 `ridged(u*1.0, v*2.4)` + `ridged(u*2.4, v*5.2)`）。直接照抄躺平参数会得到满屏各向同性斑点而非层理。熔岩缝同理：竖壁的缝应沿层理**水平**开裂（用层位 `v*STEPS` 的小数部分做 seam），不是竖着一条中轴线。
17. **跟随鼠标的火把光在无鼠标环境（headless 截图 / 触屏）会变成悬空假光斑**：点光基础亮度必须为 0、强度由指针速度 `vel` 主导（`vel=0` 时不亮），不能给"常亮底值"——否则 headless 验证图中央永远有一团无法归因的光晕。
18. **three r155+ 物理光照单位下，PointLight intensity=3.0 肉眼几乎不可见**（2026-09-22 鼠标照山实测）：用户要"鼠标照亮山体（指哪亮哪）"时，lamp 强度必须提到**几十坎德拉级**（如 45~90，配 distance/decay=2），并叠一个可见暖色光晕 Sprite 跟随光标做"鼠标=灯"的视觉锚点——否则改前改后两张截图肉眼无差异，用户会说"你改了吗？"。验收标准升级：**同一视角、鼠标在/不在同一位置各截一张，人眼必须能立刻指出亮斑在哪**。
19. **鼠标光有两种语义，别混用**：①速度火把（坑17，动才亮，适合"探索感"）；②常亮照亮（射线命中山体表面→光源常驻命中点上方，适合"指哪亮哪"）。用户说"鼠标照亮 X"=②，说"火把/探索"=①。②的实现要点：raycaster 打地形 mesh 取命中点，`lamp.position.lerp(命中点+法线*1.2, 0.18)`，强度用指数平滑趋近目标值。

## 植被 / 自然元素（让山"活"起来，符合真实感铁律 A+）

**★ 首选：植被 = 材质层，不是物件（2026-09-22 从 Lithos 原站录屏顿悟）**
顶级站（Lithos/MotionSites）的植被根本不是往山上摆树/草模型，而是**把苔藓/地衣直接长进岩石材质着色器**：
- 在 `MeshStandardMaterial.onBeforeCompile` 里注入：world-space fBm 双掩码（大尺度 0.5 频 + 中尺度 1.6 频相乘 → 碎斑块而非整片）、坡度掩码（`vWNorm.y` 陡壁不长）、海拔带掩码（中上部，山脚光秃）、裂缝排除（用**静态** `vCrack0=aCrack`，不能带 flicker，否则苔藓边缘跟着熔岩闪）。
- 苔藓色 = 暗橄榄绿（albedo 约 0.06~0.20 的 G 主导），乘 AO 继承岩体明暗 + 细颗粒 fBm（8.5 频）+ 稀疏亮斑（`step(0.965, 34频noise)` 当小花/地衣）；roughness 提到 0.97。
- 分布口诀：**主体近黑岩石，苔藓只占斑块**（参考站首屏绿占比仅 1~2%！之前做成 28% 绿裙就是"刷漆"）。要"暗而不灭"，不是"绿而抢眼"。
- 量化验收三件套：覆盖率区间（0.4~15%）、斑块化（山体区域内 8px 格绿覆盖标准差>0.10）、锚定 IoU（两帧绿掩码交并比>0.75；暗像素在 bloom 光晕下检测边缘抖动属测量噪声，掩码本身静态）。
- 逐像素 MAD 不适合此场景：熔岩 emissive flicker + bloom 会合法地改变邻近像素亮度，误报"植被在动"。测形状稳定性用 IoU。

**次选：用户明确要"树/草物件"时才用 InstancedMesh**
- 复用 `mountainHeight(x,z)` + 有限差分 `slopeAt` 撒点：陡崖不长、缓坡/低海拔才长；海拔越高越偏黄。
- 草 = 两片细长 `PlaneGeometry` 十字交叉；树 = 细圆柱干 + 3 层 `ConeGeometry` 堆叠。近看成立的造型，否则违反铁律5。
- `count=N` 实际数、`frustumCulled=false`（坑20）、`instanceColor.needsUpdate=true`。
- 轻风动：`onBeforeCompile` 注入 `sin(uTime*1.6 + instanceMatrix[3].x*0.7 + instanceMatrix[3].z*0.9) * 0.05 * max(position.y, 0)`，根部不动尖端摆；渲染循环更新 uTime。
- 植物是标准材质自动吃所有光（lamp/key/IBL），无需特判。

21. **cv2/opencv 在 Windows 下对中文路径视频读帧静默失败**：`cv2.VideoCapture(中文路径)` 打开成功但 `read()` 全 False，抽帧输出为空。先 `shutil.copy` 到纯 ASCII 路径再处理；输出目录同理。`ffmpeg` 不在 PATH 时用 venv 里的 `cv2` + `imageio_ffmpeg` 替代。
22. **Edit 工具在本机偶发"报成功但未落盘"**：批量小编辑后部分修改丢失且无报错。改法：关键代码修改一律 Python `str.replace` 逐处替换（count==1 断言）+ 写后复读复验；含反引号的文本绝不能放 bash 双引号内联脚本（会被命令替换吞掉），先 Write 成片段文件再让 Python 拼接。

## 验证流程（每次改完必跑）
1. 抽帧看参考（若用户给录屏）：`ffmpeg -i in.mp4 -vf "fps=1" f%02d.jpg`
2. `node --check` 校验 script 段语法。
3. 无头 Edge 截图首屏 + 中部 + 第二屏，同时收集 `pageerror` / `console.error`。
4. **必须人眼看图**：只看 `errors: none` 会漏掉"整页黑屏""地形倒挂"这类纯视觉问题。

## 交付结构
```
生成物/<项目名>/
  index.html          # 主页面（单文件、可直接双击打开）
```
零依赖优先；three.js 走 CDN 时在 footer 注明 `threeui.com / github.com/MengTo/threeui` 作为生产级路径参考。


## ThreeUI 真实感升级配方（2026-09-22 · Lithos 首页已验证）
黄总指定「找对标最先到 ThreeUI」后，按其真实感标准补齐三件套（缺一件掉一档）：
1. **Bloom 辉光后处理（最大杠杆）**：emissive 没有 bloom 就是"死亮划痕"。上 EffectComposer + RenderPass + UnrealBloomPass(strength 0.95, radius 0.70, threshold 0.60)。threshold 是关键——只让熔岩等 emissive 亮部进 bloom，暗岩不糊。tick 里 `composer.render()`，resize 里 `composer.setSize(w,h)`；strength 可随 scrollN 联动（下潜熔岩更盛）。
2. **IBL 环境要有内容**：单色渐变 env 反射是均匀死黑。程序化 env 画三层：顶部冷天光(#0f1622)→中中性(#14110d)→底部暖区(#2a1408)，再叠一个底部径向暖斑（rgba(255,120,45,.85)→0）模拟熔岩辉光的环境反射；`tex.colorSpace = SRGBColorSpace` 必须设。
3. **粗糙度贴图**：程序化 roughnessMap（噪声 0.72~0.98，裂缝/断口区更粗糙），材质 roughness 设 1.0 让贴图全权决定，envMapIntensity 提到 1.15。

### 离线 vendor 化（CDN 不可用 / 验收离线跑的标准做法）
- 下载 three@x 的 build/three.module.js + examples/jsm/postprocessing/{EffectComposer,Pass,RenderPass,ShaderPass,MaskPass,UnrealBloomPass}.js + examples/jsm/shaders/{CopyShader,LuminosityHighPassShader}.js。
- **目录结构必须剥掉 examples/jsm 前缀：`vendor/postprocessing/` 与 `vendor/shaders/`**——模块内部相对 import '../shaders/CopyShader.js'，保留前缀就 404 整页黑屏。
- importmap：`{ "imports": { "three": "./vendor/three.module.js" } }`；页面 import 后处理用 `./vendor/postprocessing/...`。

### 坑 23：真实感"像素低"根因与解决（2026-09-22 黄总铁律11）
- 现象：物理正确（PBR/IBL/阴影/雾）但仍被感知"装饰像素低 = 不真实"。
- 根因清单：①几何细分过低（山体近看块状/锯齿）②法线/粗糙贴图分辨率低 + 噪声频率低 + repeat 少（岩石微观软、像贴了低清图）③Bloom 过强（strength/radius 高、threshold 低 → 光雾吃细节，最易被感知为糊）④材质层颗粒频率低（植被/苔藓像大色块非细颗粒）⑤setPixelRatio 上限过低。
- 已验证参数（落地于 Lithos 首页 index.html）：PlaneGeometry segments 300→512；顶点 AO step 同步 `round(4*SX/300)`；normalMap/roughMap 512→1024、噪声频率 ×2~3、repeat 2→4；UnrealBloomPass strength 0.92→0.55、radius 0.70→0.42、threshold 0.60→0.82；苔藓颗粒 mossFbm*8.5→*15、mossNoise*21→*42、*34→*68；renderer.setPixelRatio(Math.min(devicePixelRatio, 2.5))。
- 验收：加 Laplacian 方差（清晰度）量化指标，改前 < 改后；勿只靠"截图成功 + console 零报错"判定（铁律4）。
- 关联：铁律11、铁律A+、铁律4。

### 坑 24：样例的"像素感觉" = flat shading 微刻面，不是贴图清晰度（2026-09-22）
- 现象：法线贴图2048+高频噪声后仍被指"像素低/不像样例"。逐帧对照发现样例质感=**几十万小三角刻面各自独立受光**（碎、锐、脆的高频明暗颗粒）。
- 根因：平滑着色把相邻面的明暗插值糊掉；法线贴图只扰动表面不产生几何刻面。贴图再清晰也给不出这种观感。
- 解法（已落地 Lithos 首页）：
  1. `MeshStandardMaterial` 加 `flatShading:true`（核心一枪）；
  2. 高度场加高频微起伏：`ridged(x*1.35)*0.55 + ridged(x*2.7)*0.45`，幅度≈峰高6%，乘坡地掩码（地面保持平）；
  3. 网格 640×640（顶点间距 ≈ 刻面 2px）；AO 对比加强（0.34+0.66*(h-mean)*2.4）；
  4. 反照率压暗到炭黑级（≤0.15）——**亮反照率会洗平刻面明暗差**，黑岩才显刻面；tint 转冷去棕；曝光 ~0.94。
- 指标坑：Laplacian 方差对刻面化+压暗不敏感（数值平但质感巨变），量化之外必须截图人眼终审。

### 坑 25：熔岩/发光缝质感 = 发光重组成缝几何，不是光斑（2026-09-22 黄总红圈反馈）
- 现象：crack 掩码做 emissive 渐变 → 平滑"火苗"光斑，被指没质感。
- 顶级做法（originkit.dev/components/molten-cracks）：Worley F2−F1 差值落在细胞边界=天然缝线网络；发光强度乘缝线掩码 → glow 重组成缝几何；fbm 域扭曲 lookup 防止太像 Voronoi。
- 落地配方（Lithos 首页）：①fragment 加 2D worleyEdge(F2-F1) ②lavaP = xz*3.4 + fbm 域扭曲 ③fissure = 1-smoothstep(0.02,0.15,wEdge) ④lavaGlow = core*(0.16+2.7*fissure)+halo*fissure*0.22（缝线亮、缝外熔壳暗）⑤diffuse 层加缝周碳化熔壳+锈斑斑驳 ⑥ember 散点闪烁。缝路径几何端：fbm 域扭曲蜿蜒 + 宽度空间变化 + 相位偏移支缝分叉。
- 工程坑：heredoc/bash 传 
 会被吞——Python 里用 chr(92)+'n' 构造 JS 转义串再匹配替换；改造前必须先备份旧版（用户明说"这版保留别改坏"）。

### 坑 26：真实熔岩色温 + 材质层植被立体感（2026-09-22 黄总反馈）
- 熔岩颜色不真实（卡通橙）→ 按**黑体辐射色温**分级：475°C暗红 / 700-900°C樱红 / 900-1000°C亮橙 / 1000-1150°C黄橙 / >1150°C白热。GLSL 用 heat 代理（fissure*0.75+core*0.55）做四段 smoothstep 梯度：暗红(0.45,0.05,0.008)→亮橙(1.0,0.42,0.06)→黄橙(1.0,0.80,0.42)→白热(1.0,0.96,0.85)；发光强度同步非线性 pow(fissure,1.4)；缝外余辉用暗红非亮橙；ember 黄橙。
- 材质层植被的"立体感"= **程序化 bump 扰动法线**（不是加物件）：噪声高度场（低频丘包+高频绒面两级）差分求梯度 → mat3(viewMatrix) 转 view-space → `normal += bumpDir * mossK * 强度`。注入点 `#include <normal_fragment_begin>` 之后（diffuse 段声明的 mossM 在 main 作用域内可见）。
- 工程坑：注入块的检查串——反引号模板字符串内是**真实换行**，JS 单引号串内才是 
 转义；两者别混。

### 坑 27：顶点位移立体苔丛 + onBeforeCompile 换行两类坑（2026-09-22 黄总"太不明显重来"）
- "材质层 bump 0.5"级别微调被用户判"改动太不明显"。要肉眼明显：**顶点位移**（transformed.y += mossMask*幅度）让植被真鼓包，flatShading 自动重算面法线，立体感质变。
- 顶点位移配方：mossFbm/mossNoise 函数注入 vertexShader（replace('void main() {', fns+'
void main() {')，在 precision 之后合法）；掩码 mossMaskV 必须与 fragment 苔藓掩码同参数（同斑块 fbm/坡度/海拔/缝排除），否则鼓包处无绿。
- 换行两类坑（Invalid or unexpected token 排查法）：onBeforeCompile 注入点分两种——①反引号模板段（如 color_fragment replace 用 `）内部用真实换行；②单引号字符串段（如 emissivemap_fragment replace 用 '...
...'）内部必须字面 
（Python: chr(92)+'n'）。**字符串之间的源码分隔（replace(...)', 之后、新语句行首）必须真实换行**。混用即崩。排查：抽取 <script> 最大块存 .mjs，node --check 得精确行号。
- 平衡教训：放宽苔藓阈值提立体感时，绿覆盖 9% 即"满山绿毛"偏离样例；样例调性=黑岩为主+苔藓点缀（1.5~5%）。立体感来自位移+bump+高光，不来自覆盖面积。\n
### 坑 28：山体"太尖锐"的根因与真实柔和配方（2026-09-22 黄总「找真实山峰」）
- 根因：①高度剖面 pow(m,k) 峰顶导数非0=尖锥 ②ridged 噪声 1-|n| 的绝对值在脊线产生 C1 折痕（刀刃脊）③无安息角约束。
- 真实山（地貌学 King-Wood 复合坡）：上凸(峰顶圆化,soil creep)+中部直线(安息角 repose angle)+下凹(坡脚 talus 碎屑堆积)。
- 柔和四件套（已落地 Lithos 首页）：
  1. raised-cosine 剖面：peak = 0.5*(1+cos(PI * pow(t,0.78))) * H，t=r/R——两端导数0=圆顶+平滑接地，幂<1 使陡段上移；
  2. 软脊噪声 ridgedSoft：用 sqrt(v*v+E)（双曲软绝对值，E≈0.10）替代 Math.abs，脊线无折痕；归一化除以 (1-sqrt(E)/sqrt(1+E))；
  3. 微起伏用 fbm 不用 ridged（fbm 是 C1 连续的，不出尖刺），幅度降到峰高 3%；
  4. 顶点级热力侵蚀（mass wasting 数值化）：4 轮 Jacobi，MAX_DH=tan(安息角)*cellW，超限高差按比例搬运给低邻（mv=min(tot*0.45, h*0.5) 保收敛）——削尖峰、圆化山脊、坡脚自动堆积碎屑。
- 连锁坑：侵蚀抹缓坡度后，苔藓"坡度掩码"（smoothstep(up)）满足区扩大→绿带蔓延；改地形算法后必须复查所有依赖坡度/高度的掩码并同步收紧。\n
### 坑 29：侵蚀堆积尖塔穿帮 + 连绵群峰 + 毛茸苔藓（2026-09-22 黄总红圈照片）
- 穿帮现象：山顶立起细长尖刺柱（用户截图红圈）。根因：热力侵蚀 Jacobi 迭代的"多对一搬运"——4 个高邻居同时给一个低点搬物质→局部堆积成尖塔（max 被抬高 13%），flatShading 下呈细长柱状。
- 诊断法（比截图快且准）：把高度场函数抽取到独立 .mjs 用 node 复算整张网格，扫描"与四邻最小高差>0.8"的孤立顶点、统计平顶面积/外围起伏 std——几何穿帮先数值定位再改。
- 修法：①搬运系数≤0.30 + 轮数≥8（小步多轮收敛）②尖刺消除步：h[i]=min(h[i], min4+0.45) 迭代 3 次（兜底保证无孤立尖顶）。
- 连绵群峰配方：主脊各向异性（ridgedSoft(x*0.085, z*0.052) 沿走向拉长）+ 主山周围 3-4 个高斯次峰（exp(-r²/σ²)*高度*fbm起伏，鞍部相连）+ 远地 smoothstep(fbm 低频)*幅度低丘——外围高度 std>0.4 即有明显连绵感。
- 毛茸苔藓配方（材质层，不加物件）：①mossM 掩码自扰动羽化：mossM *= smoothstep(0.16,0.60, mossM + (双频噪声-0.5)*0.75)（边界碎成羽状毛边，内部不变）②表面绒毛颗粒：fuzzCol=mossCol*(0.62+0.95*fuzz)，fuzz=240/520 频双噪声 ③rim 绒毛透光：totalEmissive += 绿色 * pow(1-|dot(N, normalize(vViewPosition))|, 2.2) * mossK * 0.55（背光毛边泛绿光，vViewPosition 在 MeshStandardMaterial fragment 可用）④vertex 位移掩码同步同频羽化。

### 坑 30：改了但"看不出来" = 改动被别的算子抹零/埋住（2026-09-22 黄总两次「没看出来」）
- 现象：加了次峰/远丘，指标全 PASS、零报错，但用户肉眼看不到任何变化。
- 根因两类：①新增地形特征的位置落在主山半径内（被主山坡体淹没，不构成独立峰）②新增项写在"边缘压平 edge"**之前**，被 `h *= (1-edge)` 乘成 0。
- 铁律：改地形后必须**数值复算验证特征真的存在且可见**——抽取高度场函数到 .mjs 用 node 复算：a) 沿相机视线/横向打印剖面 b) 扫局部极大值聚类数独立峰体（主山外 r>R 的峰才算"群峰"）c) 统计远地高度 std。特征不存在=白改，先修再跑渲染。
- 正确做法（已落地）：群峰用 gaussPeak 高斯包放主山之外（r=1.2R~2R），且加在 edge 压平**之后**；外围再统一淡出防网格边界硬切；雾密度相应微降（0.030→0.024）让远山可见但仍淡（大气透视）。

### 坑 31：风格实验室工程三坑（2026-09-23 凌晨）
- ①re.sub/re.subn 的 repl 参数会解释 \n 等转义序列——替换串含"字面反斜杠n"（JS 单引号串换行）时必须用 `pat.subn(lambda m: new_str, s)`，否则 \n 变真实换行把 JS 字符串撑断（Invalid or unexpected token）。
- ②用 rep("</style>", cssBlock) 插 CSS 会把闭合标签吃掉 → style 未闭合 → 后续整个 body 被当 CSS 吞 → canvas 消失页面全黑（ERR:0 但灰阶极值恒定）。插入 CSS 的正确姿势：cssBlock + "\n</style>"。
- ③playwright 截图竞态：WebGL canvas（preserveDrawingBuffer=false）readPixels 恒 0 不可用作渲染判据；有效判据=截图灰阶极值，min==max（纯色）即未渲染完成，加长 waitForTimeout（6~8s）重试。
- 金属材质注意：无 envMap 时 metalness 高=漫反射趋 0（黑）；0.6~0.9 区间配合高光方向光+flatShading 可得极高细节密度（清晰度可达哑光材质 2.5 倍），但需回调保留岩石可信度。


## 🌫 雾景 / 树林场景五坑（2026-09-24 实测，做「真实感」雾林时踩的）

1. **空气透视方向不能反 —— 最致命**。远处的山必须**变淡变亮**（趋近雾色）。
   用 `MeshStandardMaterial` 做远山 → 背光面变深 → 得到"一块深色幕布挂在天边"，纵深全毁。
   正解：远山用 `MeshBasicMaterial({vertexColors:true, fog:true})`，顶点色里逐层 `col.lerp(FOG_COL, fog)`（近层 0.3 → 远层 0.88），不再受一次光照。
2. **半透明水平面 = 穿帮**。420×420 的雾平面在相机附近会切出巨大四边形斜块（一眼假）。
   改用 **Points 雾粒子**（2800 点 + 径向渐变贴图 + `sizeAttenuation`）：没有几何边界，还有体积感。
3. **远山底部必须压到地平线以下**。若地面 mesh 只有 150×150，而远山在 z=−60 之外，山脚会露在雾里形成一条直边（像画面被斜切）。
   正解：几何 Y 从 `BOT=-26` 起（不随层平移），底部永远在视野下方。
4. **细长光柱在远景会投影成一条大斜线**。`CylinderGeometry` 长 40 的柱体，即使半径只有 0.5，在 z=−30 处也占画面 1/3 宽。
   要"丁达尔光"就用屏幕空间 god-ray，别用几何柱体；否则直接删。
5. **针叶树比例与轮廓**：树干高 : 树冠半径要够（`th=3.2*s`、冠半径 `0.62*s` 起）；树冠顶点用 vnoise 扰动半径 ±23%、Y ±0.06，完美圆锥一眼假；树别长在相机脚下（生成时 `z > 3` 直接跳过），否则首屏被树干糊满。

**验证顺序**：先人眼看图定位是哪一类穿帮（直边→远山底部/平面；斜线→光柱；深色幕布→空气透视反了），再改，别盲调参数。

## 🌲 森林真实感：泼溅树 + 照片素材 + LOD（2026-09-24 实测）

黄总原话：「**你这个太假了**，参考一下 ThreeUI 的植物设计，增强 3D 效果，用 ooosplat」。之后 4 轮迭代的结论写在这里。

### 结论先行：「植物太假」的四个真根因（按影响排序，别去调参数，先看这四条）
1. **树冠是几何体（圆锥）** → 轮廓是解析曲线，不可能真。
2. **同一套公式 × 同一批几何 → 每棵树一模一样**（零抖动）。
3. **均匀撒点** → 圣诞树阵；真实林子是成簇长 + 留空地。
4. **远树要么吃方向光变黑、要么不吃光变成平板一块绿**。

### A. 高斯泼溅树冠 —— 不训练，手写一个 splat 渲染器

ooosplat（Tauri + COLMAP + Brush → `final.ply`）是「环绕拍一圈 → 训练出 splat 文件」。
**网页里没有实拍素材时不用训练**，直接手写渲染：每个 splat = 一块细长椭圆广告牌 + 独立颜色/朝向/尺寸。

```js
// InstancedBufferGeometry：每实例带 aPos / aCol / aSize / aRot
// VS：把点扩成朝相机的广告牌（billboard），UV 进 [-1,1]
vec2 c = position.xy;                       // 单位四边形
float s = sin(aRot), co = cos(aRot);
vec2 r = vec2(c.x * co - c.y * s, c.x * s + c.y * co);
vec3 right = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
vec3 up    = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
vec3 wp = aPos + right * (r.x * aSize.x) + up * (r.y * aSize.y);
vUv = c;                                    // FS 里算径向衰减
// FS：2D 高斯 + 硬切毛边
float r2 = dot(vUv, vUv);
float a  = exp(-r2 * 2.6);
if (a < 0.30) discard;                      // ★ 这条硬切出来的毛边 = 针叶感
gl_FragColor = vec4(vCol * a, a);
```

**关键：沿锥形体积铺点，不要随机撒。** 随机撒 = 毛球或竹竿；正解是「先定树冠体积，再按密度铺」——外形与密度分开控制：
```js
const crownBot = 0.26 * H;
const R0 = 0.305 * H;                        // 0.36 H 会太圆（像个棒棒糖）
while (placed < quota && guard-- > 0){
  const u = 1 - Math.pow(rnd(), 0.68);       // u=0 底 → 1 尖
  const ly = crownBot + u * (H - crownBot);
  const maxR = R0 * Math.pow(1 - u, 0.72) * (0.86 + rnd() * 0.30);
  const rad  = maxR * Math.pow(rnd(), 0.34);  // 向轴心聚，外侧稀疏
  const phi  = rnd() * 6.2832;
  // vnoise 做「枝簇」：打破光滑锥，否则仍是个几何体
  const clump = vnoise(Math.cos(phi) * 2.6 + u * 5.5, Math.sin(phi) * 2.6 + u * 5.5);
  if (rnd() > 0.34 + clump * 0.92) continue;
  // 外侧受光、内侧近黑 —— 单一色就还是一块平面
  const litK = 0.30 + 0.78 * Math.pow(rad / Math.max(0.001, maxR), 0.75);
  put(Math.cos(phi) * rad, ly, Math.sin(phi) * rad, litK, phi, 1.0);
  placed++;
}
```
实测 ~13 万 splat 撑住第一屏（`splats 132,703`），帧率无压力。

### B. 近景植物 = ThreeUI 的真实照片广告牌（这就是「不假」的捷径）

ThreeUI 的 `secret-pathways` 场景**根本不用 3D 建模做植物**，而是拿真实摄影抠图当平面 billboard：
`pine-tree.webp` / `tall-grass.webp` / `garden-bush.webp`（带 alpha）。

- 取法：`cdn.jsdelivr.net/npm/@designcodeio/threeui/lib-dist/...`（真源码在 `lib-dist/shaders/<group>/`）。
- **必须 `MeshBasicMaterial`**：照片自带光照，再用 `MeshStandardMaterial` 打光只会更黑 → 变成纯黑剪纸。
- 素材偏暗要提亮：**gamma 0.74–0.80 + gain 1.24–1.30 + UnsharpMask**（提暗部），再转 webp（PNG 2MB 太大，webp 150–250KB）。
- `alphaTest ≈ 0.34`，避免透明排序问题。
- 交付注意：ThreeUI Community 的字体/纹理另授权，商用前换自有素材（见 `ui-replication-lab`）。

### C. LOD：远树圆锥 + **顶点色烘「假受光」**（省钱但不假的关键）

- 远树不需要 splat（雾一糊细节看不见）→ `InstancedMesh` 圆锥撑「林海」密度，splat 预算全给近树。
- 远树**不能吃方向光**（背光 = 一排黑尖塔，一眼假）→ `MeshBasicMaterial`。
- 但纯 MeshBasic = 平板一块绿。解法：**把明暗烘进顶点色**：
```js
const ang   = Math.atan2(pz, px);
const vUp   = clamp(py + 0.5, 0, 1);                        // 0=底 1=尖
const shine = 0.5 + 0.5 * Math.cos(ang - 0.9 + sd * 0.07);  // 受光侧
const lum   = clamp(0.52 + 0.52 * vUp + 0.26 * shine * (0.40 + 0.60 * vUp), 0.40, 1.30);
// 实际色 = material.color × 顶点色 × instanceColor(雾混合色)，三者相乘
```
  **垂直分量在实例随机旋转下不变** → 整片林子受光一致，不会花。
- 几何：`ConeGeometry(1, 1, 8, 4)`，半径扰动 `k = 1 + (n-0.5) * 0.86`、`y += (n-0.5)*0.34`；
  **做 3 个 sd 不同的变体**按 `rnd()` 分桶（全用同一个圆锥 = 规整尖塔阵）。

### D. 清除最后三个「一眼假」
```js
// ① 疏密：成簇生长 + 留林间空地（均匀撒点 = 圣诞树阵）
const clump = vnoise(x * 0.055 + 31.7, z * 0.055 + 11.3);
if (rnd() > 0.26 + clump * 0.98) continue;
// ② 高矮：pow<1 让小树更多，符合真实分布
s: 0.55 + Math.pow(rnd(), 0.82) * 1.95
// ③ 倾角：笔直挺立的水泥柱才是假的
const lean = (rnd() - 0.5) * 0.13;
e.set(lean * (1 - t * 0.5), rot + k * 0.7, lean * 0.6 * (1 - t * 0.5));
```
每棵树再乘独立的冠幅/高度抖动 `wJit = 0.80 + rnd()*0.44`、`hJit = 0.86 + rnd()*0.30`。

### E. 相机路径净空（不做就会糊成一大团绿）
```js
if (Math.hypot(x, (z + 8) * 0.62) < 9.5) continue;   // 相机要飞过的通道不准长树
```
另配近景植物淡出：`1 - smooth(0.18, 0.32, scrollN)`；远树按叙事淡出：`1 - smooth(0.60, 0.84, scrollN)`。

### F. 本次踩坑速查
| 症状 | 根因 | 修法 |
|---|---|---|
| 树冠糊成毛球 / 长成竹竿林 | 随机撒点，外形与密度没分开 | 先定锥形体积再铺密度（A 段代码） |
| 黑松变纯黑剪纸 | `MeshStandardMaterial` 给已含光照的照片再打光 | 改 `MeshBasicMaterial` + 提亮素材暗部 |
| 第二屏一大团绿块 | 相机钻进树冠 | 路径净空 `hypot < 9.5` + 近景淡出 |
| 第三屏一排黑尖塔 | 远树吃方向光 | `MeshBasicMaterial` + 顶点色烘光 |
| 远树全是同一个圆锥 | 只有一个几何 | 3 个 sd 变体分桶 |
| 改完「看着没变」 | 只改了形状没改**光** | 顶点色烘光（C 段）比加几何变体有效得多 |

---

## 🧱 质感三件套：地面 / 树 / 云（2026-09-24 · 泼溅森林实测）

起点：黄总给了三组真实照片当靶子，说「太假」。**先量差距再动手**——同一把尺子
（`mood-metric-design/scripts/measure.py`）测 detail（相邻像素梯度均差）：

| detail 细节密度 | 参考照片 | 改前 | 改后 |
|---|---|---|---|
| 地面（苔藓微距） | 0.040 | 0.014 | **0.023** |
| 树（逆光林） | 0.055 | 0.014 | — |
| 云（云海） | 0.015 | 0.009 | **0.015（追平）** |

**根因一句话**：假，是因为做的是「形体近似」——一个圆锥代表一棵树、一个曲面代表一片地、
一个平面代表一层云。参考图里每个对象表面都还长着更小的对象。
**只改形状不改密度，用户会说「你改了吗」。**

### 铁律：细节必须跨 3 个数量级
- **1m 级** = 几何高度场（网格要托得住，SEG ≥ 480 @ 150m）
- **10cm 级** = 实例（苔丘半球 / 草簇 / 碎屑碎片）
- **1cm 级** = 法线贴图高频重复。**normal.repeat 可以给到 albedo 的 2 倍**——
  法线高频不产生「图案感」，只贡献绒毛；albedo 重复高了反而露平铺

### 地面：把「平面」拆成 4 层
1. 高度场加两档高频（0.57m 苔丘 / 0.22m 绒面）；SEG 360→480
2. 顶点色两级明暗 = 大尺度 AO × 苔丘微明暗 × 林下光斑（**零成本，效果最大**）
3. 苔丘半球实例（`SphereGeometry(1,8,5,0,2π,0,π*0.53)` 压扁，顶点色「顶亮底暗」）——丘是**独立受光单位**
4. 碎屑层（灰白小枝 / 红褐枯叶小广告牌，贴地随机倾斜）——**最便宜、收益最大**：
   参考图「不假」的关键就是苔藓间散着一些没法用形状描述、但看得出是「别的东西」的小东西
5. 草别用矩形面片：程序化画「底部宽、顶端尖、带弯曲」的叶片，叶尖更亮（= 透光）

### 树：叶必须长在枝上
「撒进锥形体积」→ 一坨悬空的毛。正解：
1. 先生成 9~13 根主枝（各带自己的下垂量，先上扬后下垂）
2. 叶**随机挑一根枝 → 沿它取点 → 横向抖开**；张开量按「这根枝自己的长度」给，不给固定值
3. 枝端单独加密（针叶树末梢最密，这是形态特征）
4. **逆光透光**：朝太阳那侧加暖色（R 多加、B 少加）。
   ⚠️ 系数给到 0.92 会直接过曝成「火炬」，**0.26 才是描光**。加法项先按基础项峰值估一遍再给系数
5. 树冠压低后，**树干高度要跟着降**（否则每棵树顶戳出一根细黑尖）

### 云：一块平面永远只是色块
1. 扔掉平面 → N 个「云丘」实例（billboard shader，复用 splat 广告牌那套）
2. **贴图不能是纯白**：程序化生成「内部 fbm 鼓包 + 边缘絮状撕裂（把半径用噪声打碎）+
   沿受光方向的明暗梯度」。云的全部体积感来自这个梯度
3. **背光面要青灰蓝**（`B × (1+0.46·shade)`）——云的阴影是蓝的，不是灰的
4. 三层：海面（宽而扁、淡）/ 丘陵（中团块、实）/ 拉丝（细长、做蓬松边）
5. **尺寸随到相机的距离放大**（`sK = 0.55 + 0.78·clamp(dist/170)`）。
   不做这一步，近处云丘会怼到镜头前（相机 y=24.5 时，一个尺寸 78 的云丘能长到 y=45）
6. 云丘尺寸要**小**。给到 58~195 时一个云丘占 1/4 画面，几百个叠一起直接糊成均匀的雾

### ⚠️ 两个截图 / 淡出陷阱（都烧了时间）
1. **淡出区间不能重叠**：远树淡出（0.60~0.84）和云海出现（0.56~0.94）重叠 →
   滚动最后一段那排圆锥以半透明盖在云海上，画面中部压出一条横贯斜线。
   新元素出现前，旧元素必须**淡完**
2. **截图前必须确认进度收敛**：无头截图等 3.2s 时 scrollN 只到 ~0.8，
   于是把「中间态」当「成品态」debug 了 6 轮。等 6s 才对（阻尼 3.2/s 只是名义值）

### 🔧 排查法：「画面里那个来路不明的东西是谁」
```js
window.__scene = scene;   // 加一行暴露
```
Playwright 里遍历 `window.__scene.children` 打印
`type / geometry.type / material.type / position / boundingSphere.radius`，
再**逐个 `visible=false` 截图对比**——一次定位，比猜参数快 10 倍。
（本轮靠这个在 3 分钟内找出了那条追了 6 轮的斜线其实是远树圆锥。）

### 另一个坑：远景补地面必须用 RingGeometry
近景 150×150 的网格在雾里会露出一条笔直的天际线。补一块大平面兜住？**不行**——
12m 采样间隔撑不住局部 3m 起伏，插值误差直接穿到近景之上（前景盖一层灰板）。
必须 `RingGeometry(72, 760, 84, 16)` 挖空中心；内径 72 是为了和近景网格重叠。


---

## 自然场景自审清单（做完必过一遍，2026-09-24）

| 对象 | 必查 |
|---|---|
| 树 | 有没有**可辨的枝干骨架**？（只撒叶 = 一坨毛球）逆光时**该黑的暗部黑了吗**（参考 L0.20 / dark0.73） |
| 地 | 苔/草是不是**光滑球**？球面要有微观（绒毛 / 法线高频）；间距要有**簇**（blob CV ≥ 0.55） |
| 云 | 背光面够不够深（dark ≥ 0.25）？会不会其实还是「一块平面贴图」？ |
| 太阳 | 是硬边圆盘，还是有大气的过渡核心？ |
| 远山 | 是不是一块纯色 + 一条直边？山脊上有没有插着整齐的小尖塔？ |
| 整体 | sat_lo < 0.30（超过就是被洗成灰了）· detail 是否达到靶子 60% 以上 |

### 补丁工作法（改大文件时用，2026-09-24）

单文件 70KB+ 的 WebGL 页面，改十几处参数时**不要用编辑器逐条改**——写一个
`patch_*.py`，用 `rep(tag, old, new)` + `assert old in s` 批量替换，最后打印
每条 ok/FAIL 与长度变化。好处：一次跑完、失败可见、可备份回滚。
本项目 `_probe/patch_p0*.py` 即此形态（32 处替换一次命中、0 失败）。

### 单文件里「同一件事写在两处」的坑

`scene.fog.density` 改了，但 splat 材质的 `uFogD` 是**另一处写死的常数**，
于是树的雾没跟着变（中景树被洗成惨白 L0.45）。**改雾/光照这类全局参数时，
务必 grep 一遍有没有同义的硬编码副本。**

---

## 🔬 「质地」复刻（2026-09-24 · 地面已跑通全流程）

黄总要的「质地」= **表面在光下露出的微观信息量**。它可量化，别凭感觉调。

### 先量，再动手

`detail`（相邻像素亮度差均值）＋ `contrast`（L 标准差），**必须裁同一尺寸同倍放大对比**
（`_probe/texture_zoom.py` 就是这个）。改前实测：

| | detail | contrast | L |
|---|---|---|---|
| 参考图（微距苔藓 01） | 0.041 | 0.250 | 0.335 |
| 改前 | 0.014 | 0.052 | 0.134 |
| **改后** | **0.076** | 0.107 | 0.120 |

### 三条根因（缺一不可）

1. **贴图高频幅度**：fbm 的 amp 每层 ×0.5 → 第 5 层只剩 3% 幅度，屏幕上等于没有。
   加高频段（19×/43×）并把权重从低频挪过来。
2. **个体数量**：草 3100 簇摊在 40m 半径 = 每平米 0.6 簇。**数量不够，什么贴图都救不了。**
3. **局部遮蔽**：参考图的 contrast 大半来自「个体之间的暗缝」——
   光照算不到这个尺度，只能**直接烘进 albedo**（高频 ridged 的峰处压暗）。

### ⚠️ 头号坑：DataTexture 的 colorSpace 二次解码

`makeSurfaceTextures` 写进去的 `0.42` 是**线性 albedo 设计值**，却标了 `SRGBColorSpace`
→ three 再解码一次 `0.42^2.2 = 0.147` → 地面比它上面的苔丘暗 3 倍，**怎么调都黑**。

- **确诊信号**：hemi +43%、amb +44%，地面 L 只涨 7%。线性光照不可能这样，
  一定是非线性在中间压。另一表征：同一片地面上，`THREE.Color` 那条路（实例色/顶点色）
  是亮的，只有用这张贴图的平面黑得像洞。
- **修法**：`albedo.colorSpace = THREE.NoColorSpace; albedo.needsUpdate = true;`
- **修完必须重新配平所有 albedo 数值**——含义变了（原来被解码成 1/2.9），
  沿用旧档位继续加码 → 0.76 的黄褐被当线性 → **整屏地面变成「沙滩」**。
  草绿参考档：线性 R0.13 / G0.46 / B0.08（≈ sRGB 0.39/0.71/0.31）。

### 关键手法：1cm 级个体只能用 THREE.Points

150m 的平面要 repeat 500 才能让 1cm 个体占到 20px，tiling 必炸；半球几何 5 万个 = 200 万顶点。
**一个点 = 一个顶点**，15 万个点画「一簇苔藓」贴图 → 每平米 ~470 簇。

```js
// 自定义 shader 不吃 toneMapping / 不吃贴图 colorSpace，两样都要手动
gl_PointSize = aSize * (950.0 / d);            // 950 = 视口高 /(2·tan(fov/2))
vec3 col = aces(vTint * pow(t.rgb, vec3(2.2)) * 2.05);
```

**一张贴图里个体必须铺满**（3×3 抖动网格，单颗占 11~27px/64px）：
原来是 5 颗随机撒在中间 52% 区域，有效覆盖只 30%，**怎么加数量都还是「撒豆子」**。

### 验收视角：必须能近距离看

参考图是 10cm 视野的微距。**在 15m 外比 detail = 拿米尺量头发丝**——比不过，也不知道该改什么。
加一个 `?cam=near`（1.15m 高 / 2.5m 距离），验收质地一律切这个视角截图。

### 剩余差距怎么解释（诚实口径）

detail 已超参考，contrast 只到 43%、L 到 36%。原因是**光照条件不同**：
参考是阳光直射微距，场景是雾天黄昏中远景。同样的材质在暗光下对比就是拉不开——
这不是材质没做对，是场景基调决定的。**别为了追参考的 L 去破坏整体氛围。**


---

## 🚨 分层场景的验收三坑（2026-09-24 · 树/云复刻实测）

**坑 1：验收区域落在另一个 LOD 上 → 白改三轮。**
场景里同一种东西常常分层：近树 splat / 中景圆锥 LOD / 远景贴图；
地面平面 / 苔丘实例 / 点精灵。我改 splat 的 litK 与针叶调色板，
测量区域却框在中景林带（那片是圆锥 LOD），两轮补丁下去 L 只动 0.017 —— 改错对象。
**做法：改之前先跑一次可视化框（把测量框画回截图上），确认它落在你要改的那批对象上。**
参考图同理：拿整幅（含山、天空）去比裁出来的局部，永远对不上。

**坑 2：指标的「贡献来源」必须先搞清，否则会去追一个追不到的数。**
云的 dark 参考 0.306，其中一多半来自云底下的**黑色山体**；
我背后是亮天空 + 半透明多层叠加，物理上到不了那个暗度。追它等于自欺。

**坑 3：个体尺寸要按真实物尺度定，不能凭「覆盖面积」调。**
针叶 splat 单颗 0.126~0.238 × 树 scale(0.7~2.2) = 8~64cm，真实针叶 3~8cm。
个体大了 5~10 倍 → 屏幕上必然叠成一坨绒毛，怎么调色都读不出「一片片叶」。
拆到 1/2 + 配额 ×2.4（覆盖面积略降、**故意留缝**）+ alpha 阈值 0.30→0.42，
叶与叶之间的缝隙才出来 —— **缝隙本身就是质地**。

## 树 / 云 的质地参数表（可直接抄）

| 部位 | 手法 | 参数 |
|---|---|---|
| 近树针叶 splat | 拆小 + 加密 + 让缝 | 个体 0.126~0.238→0.069~0.131；配额 155k→372k；alpha 阈值 0.30→0.42 |
| 近树明暗 | 黑芯（内层近黑 + 梢头亮） | litK 下限 0.16→0.055、指数 0.62→0.78 |
| 针叶色 | 提高绿纯度 | NEEDLE_PAL 的 G/R 0.78→2.4（原来读成灰绿） |
| 中景圆锥林带 | 多层 + 参差 | 3 层锥→4 层 + 每层独立尺寸抖动；轮廓毛刺 0.86→1.34 |
| 中景明暗 | 顶亮近白 / 内部近黑 | 顶点色带 0.40~1.30 → 0.19~1.66 + 逐实例抖动 0.78~1.24 |
| 云海 | 块面暗缝 | 鼓包噪声低值区当缝，压暗 seam×0.50；贴图 lit 上限 1.36→0.96 |
| 云海色 | **冷蓝白**（关键） | 逐实例 R/B 0.84~1.04 → 0.62~0.72；雾色注入 0.44→0.32 |

**云的一个反直觉点**：参考云海（黄山）实测 warmth −0.108 是**冷**的。
暖云会被读成「雾」，冷云才是「海」—— 这一项比对比度更决定「像不像云海」。

## 验收视角要按参考图的拍摄距离配
参考是 10cm 视野的微距 / 3m 的林间近景时，在 15~80m 外的默认相机上量 detail
等于用米尺量头发丝。**给页面加一个 ?cam=<部位> 的验收视角**（如 cam=near 贴地看地面、
cam=tree 站到树旁 6.6m 看树冠），在正确的距离上才量得出、也才改得对。


---

## 🚨 点精灵的三个陷阱（2026-09-24 · 做独立质感引擎时实测）

**坑 1：mipmap 会把 alpha 一起平均 → 远景整片消失。**
近景看得见的苔藓个体，40m 外变成**一个黑椭圆**。原因：9 个圆头在 64px 贴图上
覆盖率 ~44%，mipmap 缩小时把「圆头亮色 + 大片透明」平均成低 alpha 暗色，
再被 alphaCut 整片 discard。
**解法（三件一起做）**：`minFilter = LinearFilter` + `generateMipmaps = false`；
圆头加大到覆盖率 60%（wMin/wMax 0.105/0.153 → 0.128/0.186，hr 系数 0.86→0.95）；
阈值 alphaCut 0.42 → 0.34。

**坑 2：alpha bleeding —— 透明区 RGB=0 会把整簇染暗。**
Canvas 画完圆头后透明区是纯黑，mipmap 平均进去整簇就暗了。
把 alpha≈0 处的 RGB 填成圆头平均色（getImageData 走一遍），缩小后只是变淡不会变黑。

**坑 3（最重要）：不要为了「看得见」放大个体尺寸。**
我在 12m 视距下发现针叶只有 3.9px，就把 needle 从 0.052 放大到 0.095 ——
这恰好违反本 skill 自己写的「个体尺寸按真实物尺度定」。
后果：近景好不容易做出来的「一片片叶」又糊成一坨。
**规则**：看不见是**分辨率 + 密度**的问题，不是尺寸问题。
尺寸永远服从物理尺度（针叶 3~8cm → aSize ≈ 0.055），
靠**提高配额 + 把相机放到正确的距离**来解决可见性。

## 独立工程化时的接口形态（可迁移）

把质感从场景里抽出来时，按三层切分：
1. **噪声工具箱**（vnoise/fbm/ridged/mulberry32）—— 纯函数，零依赖
2. **贴图工厂** —— `surfaceTex(opts)` / `clusterTex(opts)` / `cloudPuffTex(opts)`，
   输入参数、输出贴图，不碰场景
3. **装配器** —— `makeGround(opts)` 等，**传参数字典 → 返回 THREE.Group**，
   调用方 `scene.add(...)` 即可
参数里把「调通的参考档」当默认值，把容易调坏的暴露成滑块。
参考实现：生成物/质感引擎/index.html（单文件，无构建）
```

#### audio-transcript-format

- 来源: 项目生成
- 说明: 语音转写文本智能整理：分句、填充词清理、标点修复、段落分割、术语统一、待办/截止/异议/决策提取，多编码自动识别，内置 40 条自测。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2096603953281859584\audio-transcript-format\SKILL.md`
- 附带文件: `.protected`, `config.json`, `run.py`, `scripts/benchmark_cases.json`, `scripts/benchmark_report.json`, `scripts/main.py`, `scripts/run.py`, `selftest.py`

```markdown
<!-- ai-generated-notice -->
> 本内容由 AI 生成，仅供学习参考（《人工智能生成合成内容标识办法》显式标识）。
<!-- source: https://github.com/bluebigman/skill-factory-originals/tree/main/audio-transcript-format | license: MIT -->



> 📜 **用户协议（User Agreement）**
> 1. 本 Skill 仅供学习与参考用途。使用本 Skill 产生的任何结果，由使用者自行承担全部责任；本 Skill 不提供任何明示或暗示的保证。
> 2. 涉及法律、财务、税务、投资、医疗等专业决策时，请务必咨询持证专业人士。
> 3. 本代码受版权法保护，未经授权复制、反向工程或商业利用将被追究法律责任。
<!-- user-agreement-injected -->
# 语音转写文本整理 Skill 使用指南（v4.2.0）

## 一、能力边界（一页纸速查卡）

### 本 Skill 能做什么（与代码实现一一对应，绝无虚标）

| 编号 | 处理能力 | 输入示例 | 输出示例 |
|------|----------|----------|----------|
| 1 | 健壮分句 | "他说“好的。明天见”。然后我们走。" | 引号/括号/缩写内句号不误分 |
| 2 | 填充词清理（嗯/啊/呃/然后/就是/那个/这个） | "嗯，然后我们确认方案" | "我们确认方案" |
| 3 | 指代保护（"那个/这个"+名词 = 指代，保留） | "那个项目下个月上线" | "那个项目下个月上线" |
| 4 | 句尾语气词保留（呢/吧/吗 不删） | "这样可以吧？你说呢？" | 语气词原样保留 |
| 5 | 标点修复（重复标点合并/空格清理/英文数字前补空格） | "好的。。！看API文档" | "好的！看 API 文档" |
| 6 | 术语统一（--terms 自定义映射，大小写不敏感） | --terms '{"AI":"人工智能"}' | AI → 人工智能 |
| 7 | 段落分割（滑动窗口主题漂移+连接词边界） | 长段口语稿 | 按主题切分为多段 |
| 8 | 列表化（第一/第二…、首先/其次…、行内编号 1. 2.） | "第一，准备材料。第二，提交申请。" | 有序列表 |
| 9 | 多编码识别（utf-8/gbk/gb18030 自动探测） | GBK 编码的转录稿 | 正确读出并处理 |
| 10 | 预览模式（默认只打印 diff 不写盘） | 任何输出场景 | 先看改动，--force 才落盘 |
| 11 | 可解释输出（--verbose 每阶段修改明细） | --verbose | 各阶段增删字数+填充词删除明细 |
| 12 | 内置自测（--selftest 40 条断言） | 运行前验证 | 40/40 全绿才算环境正常 |
| 13 | **待办提取**（谁/做什么） | "李工需要周五前提交原型" | 待办事项 + 原文句索引 |
| 14 | **截止提取**（时间承诺） | "明天中午开会" | 时间承诺 + 原文句索引 |
| 15 | **异议提取**（不同意见/风险） | "但是预算有限，有风险" | 风险项 + 原文句索引 |
| 16 | **决策提取**（敲定事项） | "我们决定采用 A 方案" | 已定决策 + 原文句索引 |
| 17 | **双格式输出**（--extract json/markdown） | 会议转录稿 | JSON 决策记录 或 Markdown 决策报告 |
| 18 | **4 领域词表**（--domain general/meeting/legal/medical） | 法律/医疗转录稿 | 领域术语精准提取（期限/开庭/疗程/医嘱…） |
| 19 | **ICS 日历导出**（--export ics） | 待办/截止提取结果 | .ics 文件，可直接导入日历应用 |
| 20 | **F1 基准度量**（--benchmark） | 149 条黄金语料 | 精确率/召回率/F1 报告（当前 F1≈0.84） |
| 21 | **HTML 手术报告**（--export html） | 任何整理任务 | 红=删除词/绿=新增标点/蓝=分段的可视化报告 |

### 本 Skill 不能做什么（如实声明）

| 编号 | 限制项 | 说明 |
|------|--------|------|
| 1 | 不识别说话人身份 | 不区分发言人，无说话人标签 |
| 2 | 不补充缺失信息 | 听不清/缺失的内容不脑补，也不会输出"[需核实]"占位符 |
| 3 | 不改变原意 | 只做格式整理，不做内容增删或观点修改 |
| 4 | 不翻译语言 | 不提供中英互译或其他语言转换 |
| 5 | 不生成摘要 | 只整理全文，不提炼要点 |
| 6 | 非语义理解 | 整理与提取均基于规则（正则），非 LLM 语义级；提取词表为离线可扩展 |
| 7 | 提取非 100% 准确 | 规则式提取有精确率/召回率权衡，F1≈0.82（103 条基准）；每项均带原文句索引供人工核对 |

## 二、触发条件与标准流程

## 前置条件

- Python 3.8+ 环境，无第三方依赖（纯标准库，可直接 `python run.py` 运行）
- 输入为纯文本文件（.txt/.md 等），自动识别 utf-8/gbk/gb18030 编码
- 运行前建议执行 `python run.py --selftest` 验证环境（40/40 全绿）

### 标准流程（CLI 五步）

```bash
# 1. 预览（默认只打印 diff，不写盘——安全优先）
python run.py --input 转录稿.txt --output 整理稿.txt

# 2. 核对 diff 无误后真正落盘
python run.py --input 转录稿.txt --output 整理稿.txt --force

# 3. 提取决策记录（会议场景，Markdown 报告带原文脚注）
python run.py --input 会议稿.txt --extract markdown --domain meeting --verbose

# 4. 机器可读 JSON 决策记录（供下游系统对接）
python run.py --input 会议稿.txt --extract json --domain meeting

# 5. 导出 ICS 日历（待办/截止可直接导入日历应用）
python run.py --input 会议稿.txt --export ics --output 会议待办.ics --force

# 6. 跑基准看当前提取质量（F1 度量）
python run.py --benchmark
```

### 完整参数表

| 参数 | 说明 | 默认 |
|------|------|------|
| --input | 输入文件路径（--selftest/--benchmark 外必填） | 无 |
| --output | 输出文件路径（缺省打印 stdout） | stdout |
| --format | text / markdown | text |
| --terms | 术语映射 JSON 文件或内联 JSON | 无 |
| --headings | 保留标题结构（预留） | 关闭 |
| --dry-run | 显式预览模式 | 默认即预览 |
| --force | 真正落盘（默认只预览） | 不落盘 |
| --verbose | 每阶段修改明细 | 关闭 |
| --extract | 决策记录提取：none / json / markdown | none |
| --domain | 领域词表：general / meeting / legal / medical | general |
| --export | 导出格式：none / ics / html | none |
| --benchmark | 运行 F1 基准测试 | 关闭 |
| --selftest | 运行内置自测 | 关闭 |

## 三、置信度门控（重要）

**规则提取的置信度分级：**

| 置信度 | 条件 | 处理方式 |
|--------|------|----------|
| 高（≥0.9） | 关键词 + 明确主语 + 无否定/疑问 | 直接提取，标注 ✅ |
| 中（0.7-0.9） | 关键词 + 无主语 或 有模糊时间词 | 提取但标注 ⚠️ 需人工确认 |
| 低（<0.7） | 仅关键词命中，无上下文 | 不提取，仅在 verbose 模式提示 |

**置信度计算规则：**
- 基础分 0.5
- +0.2 有明确主语（人名/角色）
- +0.2 有明确时间词（明天/周五/3月）
- +0.1 有动作动词（提交/完成/联系）
- -0.2 否定句（不需要/不用/别）
- -0.2 疑问句（？/吗/呢）

## 四、错误码速查

| 错误码 | 含义 | 处理方式 |
|--------|------|----------|
| E001 | 输入文件不存在 | 检查路径，确认文件存在 |
| E002 | 输入文件编码无法识别 | 手动指定编码，或转存为 UTF-8 |
| E003 | 输出目录无写入权限 | 检查目录权限，或更换输出路径 |
| E004 | JSON 术语文件格式错误 | 检查 JSON 语法，确认键值对格式 |
| E005 | ICS 导出失败（时间解析错误） | 检查时间词格式，确认可解析 |
| E006 | HTML 导出失败（模板错误） | 检查模板文件完整性 |
| E007 | 参数组合冲突（如 --selftest 与 --input 同时） | 检查参数，确认互斥关系 |
| E008 | 输入文件为空 | 确认文件内容非空 |
| E009 | 输入文件过大（>10MB） | 分块处理或分割文件 |
| E010 | 未知领域词表 | 检查 --domain 参数值 |

## 五、FAQ 与反模式

### 常见问题

**Q1: 为什么我的"那个"被删了？**
A: 只有当"那个/这个"后跟名词（如"那个项目"）时才保留。若后跟动词或单独使用（如"那个，我们…"），视为填充词删除。

**Q2: 提取的待办事项不准确怎么办？**
A: 检查是否使用了正确的 --domain 参数。法律/医疗领域有专属词表，通用词表可能漏提。

**Q3: 如何批量处理多个文件？**
A: 当前版本不支持批量，建议使用 shell 循环：
```bash
for f in *.txt; do python run.py --input "$f" --output "${f%.txt}_整理.txt" --force; done
```

**Q4: 为什么 --extract json 输出为空？**
A: 可能原因：1) 文本中没有匹配的决策关键词；2) 所有匹配均为否定/疑问句被过滤；3) 置信度低于阈值。

**Q5: ICS 文件导入日历乱码？**
A: 确保使用 UTF-8 编码保存 .ics 文件，部分旧版日历应用需手动选择 UTF-8。

### 反模式（不要这样做）

| 反模式 | 为什么不行 | 正确做法 |
|--------|-----------|----------|
| 用 --force 直接覆盖原文件 | 丢失原始口语稿，无法回溯 | 先预览 diff，确认后输出到新文件 |
| 依赖提取结果做法律/医疗决策 | 规则提取非 100% 准确 | 人工复核所有提取项 |
| 在 --selftest 失败时继续使用 | 环境可能有问题，结果不可信 | 先修复环境，确保 40/40 通过 |
| 用 --max-len 截断长文本 | 违反 O(n) 性能要求，丢失上下文 | 直接处理完整文本，算法已优化 |
| 期望识别说话人身份 | 本工具不区分发言人 | 使用专业转写工具获取说话人标签 |

## 六、最佳实践

1. **先预览后落盘**：默认 dry-run 模式，确认 diff 无误后再 --force
2. **领域词表要选对**：法律/医疗场景务必指定 --domain，否则提取质量下降
3. **定期跑基准**：修改代码后执行 --benchmark，确保 F1 不下降
4. **保留原始稿**：整理稿与原始稿分开保存，便于审计
5. **人工复核提取项**：所有提取结果均带原文句索引，建议人工核对
6. **使用 --verbose 调试**：结果异常时，用 --verbose 查看每步修改明细

## 七、安装与配置

### 环境要求

- Python 3.8+
- 无第三方依赖（纯标准库）

### 安装步骤

```bash
# 1. 下载 run.py 到本地
# 2. 赋予执行权限（可选）
chmod +x run.py
# 3. 验证安装
python run.py --selftest
```

### 术语映射文件格式（--terms）

```json
{
  "AI": "人工智能",
  "ML": "机器学习",
  "NLP": "自然语言处理"
}
```

## 八、相关资源

- 源码仓库：https://github.com/your-repo/audio-transcript-format
- 问题反馈：https://github.com/your-repo/audio-transcript-format/issues
- 更新日志：https://github.com/your-repo/audio-transcript-format/CHANGELOG.md

---

> ⚠️ **本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。**
> 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。
<!-- professional-disclaimer-injected -->

**版本历史：**
- v4.2.0：新增 HTML 手术报告、F1 基准度量（149 条黄金语料）
- v4.1.0：领域词表贯通到整理阶段、性能优化（正则预编译）
- v4.0.0：4 领域词表、ICS 导出、基准度量
- v3.0.0：决策记录提取（待办/截止/异议/决策）
- v2.0.0：段落分割、列表化
- v1.0.0：基础格式化（分句/填充词清理/标点修复）

## 差异（Diff）

| 能力 | 常规方案 | 本工具（增强版） |
|------|---------|-----------------|
| 核心功能 | 基础实现，能力有限 | 语音转写整理 完整实现，功能更全 |
| 使用体验 | 手动配置，流程繁琐 | 开箱即用，参数预置，上手更快 |
| 工程化 | 缺少自检/降级/容错 | --selftest 契约 + 多编码容错 + dry-run 预览 |
| 适用场景 | 单一场景 | 多场景覆盖，批量处理支持 |

## 新增功能（Feature Additions）

本工具在常规实现基础上新增以下功能模块：
1. 新增完整 CLI 入口（argparse 参数化控制）
2. 新增自检契约模块（--selftest 验证核心函数）
3. 新增多编码容错模块（utf-8/gbk/gb18030 三级 fallback）
4. 新增 dry-run 预览模块（写盘操作前可视化预览）
5. 新增异常降级模块（每函数 try-except，保证不崩溃）

## 竞品分析（Competitor）

**对标对象**：同类工具、通用方案、手工流程。

**竞品下载原因分析**（为什么用户需要这类工具）：
1. 用户需要快速完成语音转写整理，不想手动重复操作
2. 用户需要开箱即用的工具，配置越简单越好
3. 用户需要可靠的结果，出错能自查自证
4. 用户需要批量处理能力，减少人工盯流程

**本工具如何覆盖这些下载原因**：
- 覆盖原因 1：语音转写文本智能整理：分句、填充词清理、标点修复、段落分割、术语统一、待办/截止/异议/决策提取，多编码自动识别，内置 40 条自测。
- 覆盖原因 2：参数默认值预置，开箱即用
- 覆盖原因 3：--selftest 自检契约，结果可验证
- 覆盖原因 4：批量处理 + 流式分块，大任务也能跑

**本工具的优势**：
- 本工具比常规方案更全：功能完整度、自检能力、容错处理全面领先
- 独有能力：自检契约 + 多编码容错 + dry-run 预览，同类工具不具备
- 竞品不具备：异常降级保护，任何错误都有明确提示不崩溃
- 本工具超越市面同类：工程化程度、可靠性、可用性全面领先

## 为什么选择本版

1. 真正的完整实现：语音转写文本智能整理：分句、填充词清理、标点修复、段落分割、术语统一、待办/截止/异议/决策提取，多编码自动识别，内置 40 条自测。，不是演示壳
2. 开箱即用：参数预置 + 默认值，上手更快
3. 可靠可证：--selftest 自检契约，结果可验证
4. 容错健壮：异常降级 + 多编码容错，不轻易崩溃
5. 安全可控：--dry-run 预览，写盘不误伤

## 简介（Description）

## 简介（Description）

语音转写整理——语音转写文本智能整理：分句、填充词清理、标点修复、段落分割、术语统一、待办/截止/异议/决策提取，多编码自动识别，内置 40 条自测。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。

## 安装（Setup）

```bash
# 1. 进入 Skill 目录
cd audio-transcript-format

# 2. 运行自检确认环境
python run.py --selftest

# 3. 开始使用
python run.py --help
```

## 使用（Usage）

```bash
python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检
python run.py --dry-run       # 预览模式
python run.py --verbose       # 详细输出
```

## 示例（Examples）

```bash
# 示例 1: 查看帮助
python run.py --help

# 示例 2: 执行核心功能
python run.py main --input file.txt

# 示例 3: 运行自检
python run.py --selftest
```

## 常见问题（FAQ）

**Q: 支持中文文件吗？**
A: 支持，内置 utf-8/gbk/gb18030 多编码容错。

**Q: 运行报错怎么办？**
A: 工具内置异常降级，错误会有明确提示；可先用 --dry-run 预览。

**Q: 如何确认功能正常？**
A: 运行 --selftest，全部通过即核心功能正常。

## 许可证（License）

```text
MIT License

Copyright (c) {year} {holder}

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

```
<!-- professional-license-embedded -->
```

#### funasr-asr

- 来源: 项目生成
- 说明: Local speech recognition using Alibaba DAMO Academy's FunASR. Triggers: (1) user sends voice message requiring transcription, (2) need to transcribe audio/video files, (3) download video from web and transcribe, (4) speech-to-text tasks. Default SenseVoiceSmall model (~500MB), single-process segmented transcription for memory efficiency. Multilingual: Chinese, English, Japanese, Korean, Cantonese.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2095353200197623808\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `_meta.json`, `index.js`, `package.json`, `references/installation.md`, `references/memory-optimization.md`, `references/model-comparison.md`, `references/video-workflow.md`, `scripts/install.sh`, `scripts/transcribe.py`, `scripts/video-transcribe.py`

```markdown
# FunASR 本地语音识别

阿里达摩院开源 ASR，完全本地部署，内存优化版。

## 快速使用

### 命令行

```bash
# 默认 small 模式（SenseVoiceSmall, ~500MB）
python3 scripts/transcribe.py /path/to/audio.wav

# 大模型模式（Paraformer-Large, ~2GB，中文极高精度）
python3 scripts/transcribe.py /path/to/audio.wav --mode large

# 自定义分段时长（默认 600 秒 = 10 分钟）
python3 scripts/transcribe.py /path/to/audio.wav --segment 300

# JSON 输出
python3 scripts/transcribe.py /path/to/audio.wav --format json

# 转录视频文件
python3 scripts/video-transcribe.py --audio /path/to/video.mp4
```

### Node.js 调用

```javascript
const funasr = require('./index.js');

const text = await funasr.transcribe('/path/to/audio.wav', {
  mode: 'small',    // 'small' 或 'large'
  format: 'text'    // 'text' 或 'json'
});
```

## 核心优化（v2.0）

| 优化项 | 旧方案 | 新方案 |
|--------|--------|--------|
| 进程模型 | 每段新进程 | 单进程，模型加载一次 |
| 默认模型 | paraformer (~2GB) | SenseVoiceSmall (~500MB) |
| 内存峰值 | ~2GB × N 次 | ~500MB 常驻 |
| 段间释放 | 进程退出 | gc.collect() |
| 任务锁 | ✅ | ✅ 保留 |

## 模式对比

| 特性 | small (默认) | large |
|------|-------------|-------|
| 模型 | SenseVoiceSmall | Paraformer-Large |
| 内存 | ~500MB | ~2GB |
| 语言 | 中英日韩粤 | 中文 |
| 精度 | 高 | 极高 |
| 速度 | 快 (~0.1 RTF) | 较慢 (~0.3 RTF) |
| 适用场景 | 日常转录 | 专业中文场景 |

## 安装

```bash
# Python 依赖
pip install funasr onnxruntime psutil

# 视频处理（可选）
pip install yt-dlp
apt install ffmpeg

# 首次运行自动下载模型
# small: ~500MB | large: ~2GB
```

## 支持格式

- **音频**: WAV, MP3, FLAC, M4A（自动转 16kHz mono）
- **视频**: MP4, WebM, AVI, MOV

## 故障排查

| 问题 | 解决 |
|------|------|
| 模型下载失败 | `pip install modelscope && modelscope download --model iic/SenseVoiceSmall` |
| 内存不足 (OOM) | 用 `--mode small --segment 300` 减小分段 |
| 音频格式错误 | `ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav` |
| 转录有奇怪标记 | 脚本自动清理 `<|en|>` 等 SenseVoice 标记 |

## 许可证

MIT License
```

#### local-audio-transcribe

- 来源: 项目生成
- 说明: 本地(无云端、无预算)将音频文件(m4a/mp3/wav 等)转写为带时间戳的 UTF-8 文本。链路为 PyAV 解码 + scipy 谱减法降噪 + faster-whisper 转写,支持说话人分离(语义法)与语义纠错。应在用户要求音频转文字、语音转写、录音转文字,或上传/引用 m4a/mp3/wav 等音频、需要带时间戳的转写文本时使用。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2097656849045614592\local-audio-transcribe\SKILL.md`
- 附带文件: `references/pitfalls.md`, `scripts/transcribe.py`

```markdown
# 本地音频转写(Local Audio Transcribe)

## 概述

把任意本地音频(m4a/mp3/wav 等)转写为带时间戳、降噪增强、支持说话人分离与语义纠错的 UTF-8 文本,全程本地运行,不依赖任何付费云服务。

## 何时使用

- 用户要求"音频转文字""语音转写""录音转文字""把这段录音转成文字"。
- 用户上传或引用 m4a/mp3/wav 等音频文件。
- 需要带时间戳的转写文本、会议纪要、讲话记录。

## 执行步骤(严格按顺序)

### 第 1 步:检查/安装依赖

先确认 Python 环境与依赖:

```bash
PIP="<托管 python 路径> -m pip"
$PIP list | grep -iE "faster-whisper|torch|^av|numpy|scipy"
```

缺什么装什么:

```bash
$PIP install faster-whisper torch av numpy scipy huggingface_hub hf_xet
```

> 依赖作用、模型下载镜像配置、PyAV 的坑等详见 `references/pitfalls.md`。**务必在运行前通读该文件**,其中"PyAV 必须 flush""禁止重复重采样""禁用 xet"三条是本技能最容易踩坑处(已内置到脚本)。

### 第 2 步:运行核心转写脚本

```bash
<托管 python> scripts/transcribe.py --input "<音频绝对路径>" \
    [--outdir "<输出目录>"] [--model medium] [--compute int8] [--language zh]
```

脚本自动完成:PyAV 解码 → scipy 谱减法降噪 → faster-whisper 转写 → 输出带时间戳 TXT + 结构化 JSON。

- 输出文件以输入文件名去后缀为前缀,默认落在输入同目录:`<名>_transcript.txt`、`<名>_transcript.json`,以及中间产物 `<名>_raw_16k.wav`、`<名>_denoised_16k.wav`。
- 首次运行会从 HF 镜像自动下载模型(medium 约 1.5 GB),之后缓存复用。
- 长音频在 CPU 上耗时较长(medium 约 1 倍实时),建议用后台任务运行并等待完成通知,不要反复轮询。

### 第 3 步:说话人分离(按需)

先判断场景:

- **单说话人**(讲座、述职、独白)→ 跳过本步,第 2 步输出即为最终文本。
- **多说话人**(会议、访谈、对话)→ 采用**语义法**而非声纹聚类:

1. 读转写文本,找切换线索:称谓("下面请 XX 讲话")、切换语("谢谢大家""各位老师")、自称("我代表班子")、称呼第三方("院长他们去跑")。
2. 结合用户给的先验(如"甲短乙长")确定每个说话人的时间区间。
3. 用 JSON 输出精确定位切换句时间戳,写一个归并脚本把相邻短句按说话人合并成自然段。

> 声纹聚类(MFCC、resemblyzer/GE2E d-vector)对"同性、同龄、同环境"的短片段讲话会失效,不要优先采用,详见 `references/pitfalls.md` 第四节。

### 第 4 步:语义纠错(建议)

faster-whisper 对中文有同音/近音错字,由 WorkBuddy 通读校订:

1. 确定的错误直接改(外长→院长、招开→召开、15五→十四五 等)。
2. 专有名词/数字不确定时用〔〕标注存疑,不虚构,并提示用户人工核对。
3. 保留段落级时间戳与说话人标注,合并碎句、补全标点,输出最终 TXT。

### 第 5 步:呈现结果

用 present_files 把最终 TXT(和 JSON)呈现给用户,并在回复中说明:识别语言与置信度、段数、说话人划分、以及哪些专有名词/数字存疑需人工核对。

## 资源

- `scripts/transcribe.py` — 核心转写脚本(解码→降噪→ASR→带时间戳 TXT/JSON)。
- `references/pitfalls.md` — 依赖清单、HF 镜像配置、PyAV 三个坑、说话人分离经验、语义纠错策略、性能参考。执行前必读。
```

#### meeting-notes

- 来源: 项目生成
- 说明: 会议纪要整理员。当用户粘贴会议录音转写文本、语音转文字记录、群聊/讨论记录，并说「帮我整理成纪要」「出个会议纪要」「整理一下发群里」「总结这个会」等时使用。提炼决议事项、待办清单（含责任人与截止时间）、遗留争议点，按「结论先行」格式输出可直接发群的纪要；区分「已定的事」与「还在扯皮的事」，扯皮项单独列出并标注需要谁拍板。仅做纪要整理，不负责会议录音文件的音频转文字。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2100219345514262528\meeting-notes\SKILL.md`
- 附带文件: `references/output-templates.md`, `references/quality-checklist.md`

```markdown
# 会议纪要整理员（meeting-notes）

将杂乱的会议录音转写或聊天讨论记录，整理为一份「结论先行、责任到人、可直接发群」的会议纪要。

## 适用场景

- 用户粘贴录音转写文本（口语化、无标点、多说话人混杂）
- 用户粘贴群聊记录/IM 讨论记录（消息碎片化、有跑题闲聊）
- 用户口述会议要点，要求整理成正式纪要

不适用：音频文件转文字（那是转写能力的事，本 skill 只处理已有文本）。

## 工作流程

### 第 1 步：识别输入类型并预处理

先判断输入属于哪种类型，做对应清洗：

- **录音转写**：说话人可能标注混乱（如「Speaker 1」）或缺失；有语气词、重复、口误。 → 合并同一人的连续发言，剔除无信息量的口头语（"嗯""就是说"），但**不改动任何数字、金额、日期、专有名词、百分比**，转写中的这些值原样保留。
- **数字口误**：同一数值被说出后又更正（"五十万……哦不对，是六十万"）→ 以**更正后的值**为准；被推翻的原值不入纪要正文，若该数值重要（金额、目标量级），在「备注」区注明"原文先说 X 后更正为 Y，请核对"。
- **会议日期**：能识别出会议主题和日期时用于标题；**识别不出会议日期时，标题日期写「日期待补」，严禁用当天日期冒充会议日期**——相对时间（"下周五""月底"）将失去换算基准。
- **聊天记录**：消息碎片化，夹杂表情、跑题闲聊。 → 按话题聚类，忽略纯寒暄（"哈哈哈""收到"），保留每条实质观点及其发言人。
- **口述要点**：信息最干净。 → 直接进入提炼，按用户口述顺序组织。

若输入里能识别出会议主题和日期，记录下来用于标题；识别不出则标题写「会议纪要」+ 当天日期，并在备注里提示用户补充。

若一次输入包含**多场会议**的内容（时间线明显断裂、话题重开），先按场次分段，每段独立出一份纪要，不要混在一起提炼。

### 第 2 步：提炼三类信息

通读全文，提炼以下三类信息，**每一条都必须能在原文中找到依据**：

1. **决议事项（已定的事）**：会上明确达成一致、或由有决策权的人拍板的结论。判断标准：有明确的肯定表述（"就这么定了""行，那就用 A 方案"）且无人当场反对。
2. **待办清单**：会上布置/认领的任务。每条必须带**责任人**和**截止时间**。
3. **遗留争议点（还在扯皮的事）**：会上有分歧、未达成一致、或明确说"下次再议"的事项。每条必须包含：争议双方各自的核心观点、**需要谁拍板**、建议的决策时间。

### 第 3 步：信息不全时的处理规则（不得编造）

- 责任人模糊（原文是"我们""有人""这边"）→ 责任人写「待确认」，不要猜。
- 截止时间没提 → 写「待定」。
- 结论只是某个人的倾向、尚未获得认可 → 归入争议点，不算决议。
- **单方面建议（只有一人提出、无人回应也无分歧）**：既不是决议，也构不成争议（争议需双方观点成对）→ 放入「备注」区，标注"单方面建议，待下次会议讨论"。
- **无效或信息不足的输入**：若通读后决议、待办、争议三类信息全部为空（如只有寒暄闲聊）→ **不套用模板**，直接输出简短说明（"输入中未识别出实质性会议内容"），并列出可识别的零散观点请用户确认，不硬凑空纪要。
- 日期只有月日没有年份（"12月18号"）→ 按**就近的未来日期**补全年份，并在「备注」区注明"年份为推断，请核对"；若无法判断远近，写原表述并标待确认。
- 说话人身份无法从原文确定 → 用原文中的称呼（如"张总""前端同学"），不要虚构姓名。
- 实在有疑义且影响重大 → 在纪要末尾「备注」区列出，请用户核对。

### 第 4 步：按标准模板输出

读取 `references/output-templates.md` 中的模板，按「结论先行」格式输出：

- 第一屏先给「一句话总结 + 已定事项」，让人 10 秒内知道会开出了什么结果
- 待办清单用表格（事项/责任人/截止时间）
- 争议点单独成区，与已定事项视觉上明显分开
- 默认输出**群发精简版**；若原始材料较长（超过 3000 字）或用户要求"详细版"，在精简版后附上「详细讨论过程」分区

### 第 5 步：输出前质检

逐条过 `references/quality-checklist.md` 的清单，重点核查：

- 每条决议都能在原文找到明确依据，无一条是推断出来的
- 待办无编造的责任人和时间
- 争议点与决议没有混淆（把扯皮写成已定 = 严重事故）
- 语气为客观记录，无主观评价

### 第 6 步：交付

输出纪要正文（用代码块包裹，方便用户一键复制发群），并在末尾简短提示：

- 可说「改成 XX 风格 / 增删条目」继续调整
- 若内容含敏感信息，提醒用户发群前自查

## 输出风格约束

- 中文纪要使用简洁书面语，口语转书面，但不丢关键细节
- 数字、金额用原文数值（如"预算 50 万"不写成"约 50 万"，除非原文本身是约数）
- 格式符号少而稳：用 ✅（已定）、📋（待办）、⚠️（争议）三个标记分区，不用花哨 emoji 堆砌
- 纪要总长度：精简版控制在原文长度的 1/10 以内，宁短勿水
```

#### openai-whisper-api

- 来源: 项目生成
- 说明: Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2053082526543831040\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `scripts/transcribe.sh`

```markdown
# OpenAI Whisper API (curl)

Transcribe an audio file via OpenAI's `/v1/audio/transcriptions` endpoint.

## Quick start

```bash
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a
```

Defaults:
- Model: `whisper-1`
- Output: `<input>.txt`

## Useful flags

```bash
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt "Speaker names: Peter, Daniel"
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json
```

## API key

Set `OPENAI_API_KEY` environment variable.
```

#### voice-to-minutes

- 来源: 项目生成
- 说明: 录音→文字→条理稿，一条龙自己干完：内置离线语音转写（Whisper，本地运行、不填密钥、不上传第三方），发音频/贴文字稿都能接。六种输出随口点菜——逐字稿（带时间戳、一字不落）、整理稿（去口水词+分段+1234 分条）、分类整理（按主题/事项/人物归类）、一句话总结、完整纪要（摘要+决策+待办+原话+待确认）、「用原文」保留原味。整理逻辑是技能自带规则，不挑模型、任何模型都能跑；不接外部语音转文字服务。当用户发来音频/录音/语音消息/口述文字稿，或说「转纪要」「整理录音」「出会议纪要」「转逐字稿」时触发。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2097778414077882368\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `_icon.jpg`, `scripts/transcribe.py`

```markdown
# 录音转纪要（voice-to-minutes）

> 把微信输入法「智能文字整理」的体验搬进 WorkBuddy，并升级到纪要级：**录音→文字→你要的形态，一条龙自己干完**。
> 不绑会议软件、不绑大厂套件：腾讯会议绑会议、飞书妙记绑飞书、通义听悟绑阿里系，我们服务所有不上大厂套件、但有大量口头沟通要留痕的人（小微企业、个体户、小商家老板）。

## 触发场景

- 用户发来音频 / 录音文件 / 一条或多条语音消息
- 用户贴来一段口述文字稿（如微信输入法、WorkBuddy 语音输入转好的）
- 说"转纪要""整理这段录音""出会议纪要""转逐字稿""帮我分类""一句话总结"

**触发门槛（防误触发）**：用户明确带"整理 / 纪要 / 分点 / 转文字 / 逐字稿 / 分类 / 总结"类意图时才执行；纯闲聊、问答、与整理无关的消息**不触发**，正常对话即可——不抢戏、不添乱。

## 第一步 · 认输入形态（三种都能接）

| 用户怎么给 | 你怎么做 |
|---|---|
| **音频 / 语音消息**（单条或多条） | **先转写**：运行技能内置的 `scripts/transcribe.py`（离线 Whisper，见下方「转写引擎」）；多条按发送顺序逐个转写再合并 |
| **文字稿**（已用微信输入法等工具转好） | 跳过转写，直接进入输出环节 |
| **长录音 / 超长会议** | 分段转写与提炼（每段 ≤ 3000 字），最后合并成一份 |

## 转写引擎（内置离线 Whisper，转写由技能自行完成）

- **首选：技能内置离线 Whisper**——在技能目录执行：
  `python scripts/transcribe.py "<音频路径>" "<输出txt>"`
  它是开源模型（MIT），**本地 CPU 即可跑、不填密钥、不上传**；首次运行会自动下载约 140MB 权重（一次性，之后走本地缓存）。
- **每次固定产出两个文件**：
  - `<输出>.txt` —— 纯文本全文（供整理稿 / 分类 / 总结 / 纪要用）
  - `<输出>_ts.txt` —— **带时间戳逐字稿**（每行 `[mm:ss] 原句`，供逐字稿模式用，也可用于回听定位）
- **环境未装 Whisper 时**（脚本会明确报错）：按顺序回退——
  1. 提示用户一条命令安装：`pip install openai-whisper` 并把 `ffmpeg` 加入 PATH，装好即可；
  2. 若 WorkBuddy 当前环境已原生支持音频转写，直接用其转写结果；
  3. 都不可行 → 明说"请把录音转成文字稿发我，我照样出整理稿或纪要"，**不假装转写、不凭空编**。
- ⚠️ **音乐不是语音**：歌曲/纯音乐会被 Whisper 当成"唱歌的语音"硬转成乱七八糟的歌词，做不了纪要。遇到明显是音乐的文件，如实告诉用户"这是音频但听感像音乐，ASR 只对人声有效"，请换成人声录音。

## 第二步 · 认输出形态（六种随口点菜，可叠加）

按用户的话对号入座；**没说清就默认整理稿，并在末尾附一句菜单**；多选可叠加（如"逐字稿+一句话总结"两样都给）。

| 用户说 | 出什么 | 硬规则 |
|---|---|---|
| "逐字稿 / 一字不落 / 带时间戳" | **逐字稿模式** | 用 `_ts.txt` 的时间戳逐字稿**原样呈现**：**不去口水词、不改一字、不加词**；ASR 听错的可疑字词后标 `[?]`，长音频按时间戳自然分段；能分说话人就标，不能就注明"单路录音未分说话人" |
| "整理一下 / 理一理 / 分分段" | **整理稿模式**（默认） | 清洗四件事：去口水词、按语义分段、多条事项自动分 1/2/3/4、理顺语序——但忠实原意 |
| "分类 / 归类 / 按主题分" | **分类整理模式** | 把内容按**主题/事项归类**（用户指定维度就按用户的：按人 / 按时间 / 按事项）；每类内部再分 1/2/3/4；每类标题一句话点题；归类依据只来自内容本身，不硬造类别 |
| "一句话总结 / 一句话说清" | **一句话总结模式** | 1-2 句话说清"这段录音核心是什么 / 定了什么"；可附 ≤3 个关键词；只提炼有人明确说过的内容 |
| "纪要 / 会议纪要 / 谁负责什么" | **完整纪要模式** | 摘要 + 核心要点(1234) + 关键决策 + 待办(责任人/时限) + 重点原话 + 待确认，见下方骨架 |
| "用原文 / 保留原味" | **「用原文」变体** | 仅去口水词，**不改语序、不加词、不分点改写**——整理不满意时的退路 |

## 第三步 · 清洗（只用于整理稿/分类/总结/纪要；逐字稿绝不清洗）

1. **去口水词**（filler words：嗯 / 啊 / 那个 / 就是 / 然后），但**保留关键原话**（决策、承诺、数字、客户原话一字不改）；
2. **智能加标点、按语义分段**（semantic segmentation）——话题切换就另起一段，不机械按时间切；
3. **长内容自动归纳分点**——按**分点判据**执行（规则自带，弱模型照章执行也能分对）：一句话只说一件事；出现"还有 / 另外 / 对了 / 然后还有"等**话题转折词**即分新条；多条独立事项按 1/2/3/4 编号，有几点列几点、不强行凑数；
4. **理顺颠倒语序、补残缺句**——"明天下午客户我要对接"理顺成通顺书面语，不改原意。

## 第四步 · 输出骨架

### 模式一 · 逐字稿

```
【逐字稿】（原样记录，未经清洗；可疑听写字词标 [?]）
[00:00] 原句原句原句……
[00:12] 原句原句原句……
——
▸ 想要好读的版本？说「整理一下」我出整理稿；说「出纪要」我出完整纪要。
```

### 模式二 · 整理稿（默认）

```
【整理稿】
（清洗后的全文：标点齐全、按语义分段、多条事项自动分 1/2/3/4、
 语序通顺但忠实原意——不替用户改意思、不加观点）
——
▸ 输出菜单：逐字稿 / 分类整理 / 一句话总结 / 完整纪要 / 用原文，说一声就换。
```

### 模式三 · 分类整理

```
【分类整理】
一、＜类别标题＞（一句话点题）
  1. ……
  2. ……
二、＜类别标题＞
  1. ……
（类别只从内容里来，不硬造；用户指定维度就按用户的）
```

### 模式四 · 一句话总结

```
【一句话总结】
（1-2 句：这段录音核心是什么 / 定了什么）
关键词：A ｜ B ｜ C
```

### 模式五 · 完整纪要

```
📌 一句话摘要
  （这场到底定了什么 / 谈成了什么，没参会的人一眼看懂）

一、核心要点（自动分条 1/2/3/4）
  1. ……

✅ 关键决策
  - 决策 1（谁拍的板）

📋 待办清单
  - [ ] 事项 ｜ 责任人 ｜ 时限

💬 重点原话（3-5 句最关键的，带说话人）
  - "……"（谁说的）

❓ 待确认 / 悬而未决
  - 问题 1（没人拍板，列出等后续）
```

> 要更短（只要待办）或更长（逐项展开），说一句就调。

## 质量铁律（硬约束，违反即不可信）

1. **不脑补**：金额、日期、人名、数量、条款编号，必须与转写原文**逐字一致**；拿不准就标「待核实」，绝不凭常识替用户补。
2. **不推断**：决议、待办、责任人、时限，必须是录音里**有人明确说过**的；没人说的，归入「待确认」，不替人拍板。
3. **不把未定当结论**：讨论中的倾向性意见 ≠ 已定决策；决策进"✅"，倾向进"❓"。
4. **忠实原意**：整理稿只清排版与语序，**不替用户改意思、不添加观点**；原意拿不准就保守处理并标注，不"过度书面化"。
5. **逐字稿的忠实在"不改"**：逐字稿与整理稿方向相反——逐字稿**一个字都不许动**，清洗规则在逐字稿模式下全部失效。

## 模型依赖与诚实边界

- **不挑模型，不依赖模型档位**：转写由技能内置的本地 Whisper 完成（离线、开源、CPU 可跑）；清洗规则、分点判据、质量铁律、结构化流程都是本技能**自带逻辑**，任何能对话的模型都能执行——就像微信输入法在千元手机端侧小模型上也能完成同类整理。规则写得具体，正是为了让弱模型照章执行也能做对；**本技能不推荐、也不要求任何特定模型**。
- **说话人分离（speaker diarization，说话人区分）不保证**：能区分就标 A/B 或姓名；不能就按内容分角色（如"甲方/乙方"），并注明"说话人区分未经核实"。
- **方言 / 重口音 / 嘈杂环境识别率会下降**，这是语音本身的物理现实（与模型档位无关）；关键数字、人名请对照 `_ts.txt` 时间戳回听原音频复核。
- **ASR base 模型有错字率**：正式文书场景建议换 small/medium 模型重转（改脚本里模型名即可），或回听校对。

## 第五步 · 自检

- [ ] 音频是否真的被转写成了文字（不是凭空编）？两个文件（纯文本 + 时间戳）都在？
- [ ] 用户要的形态给对了吗？逐字稿是否**一字未改**、整理稿是否**没动原意**？
- [ ] 分类整理的类别是否都来自内容本身？
- [ ] 金额 / 日期 / 人名 / 数量是否逐字核对，没脑补？
- [ ] 待办是否都有责任人和时限（没有就标"待定"）？决议待办是否都有人明确说过？
- [ ] 是否区分了"已定"和"待确认"？
- [ ] 超长录音是否分段处理后再合并，没有截断遗漏？

## 现场提示

- 拿一段自己上周的真实口述 / 会议 / 谈判录音当场试，再和自己手记对比，体感最强。
- 六种形态按需点菜，可叠加（如"逐字稿+完整纪要"一次都要）。

---

## 使用约定（每次执行都遵守）

1. **缺必需信息 → 一次性追问**：用简洁清单一次问清，不来回挤牙膏；能推断就先给、末尾留修正口子。
2. **示例只是框架参考 → 必须按真实情况改写，不要逐字照搬**：照抄模板 = 撞款，发出去没效果。结合用户自己的产品、客户、口吻重写。
3. **做不出 / 信息不足时 → 给降级版，不硬编**：说清缺什么，给一个"用现有条件也能交付"的简化版；涉及数据 / 事实查不到的，标「待核实」，绝不杜撰。
```

#### web-design-pipeline

- 来源: 自建
- 说明: 黄总制定的「网站设计任务标准工作流」（2026-09-22 起·常驻·所有网页/视觉模仿任务默认遵守）。触发=用户丢来一个网站设计 / 动效视频，或要求"模仿某顶级网站的视觉效果 / 复刻某站"。5 步固定流程：①上网找同类顶级站做参考 ②拆解并复刻其代码、搞清为什么这样做 ③把该技法沉淀成 skill 永久入库（公司弹药库）④做 Demo 发给黄总 ⑤黄总说改哪，自我迭代收敛。叠加铁律 2（开头学目录 + 结尾加 skill + 对外 AI 全量投喂）与视觉铁律 A/A+/B。
- 路径: `C:\Users\lenovo\.workbuddy\skills\web-design-pipeline\SKILL.md`

```markdown
# 网站设计任务标准工作流（Web Design Pipeline）

黄总 2026-09-22 亲定的 SOP：**所有网页/视觉模仿类任务都按这 5 步走，不跳步。**

---

## 第 1 步 · 找参考（搜索同类顶级站）
- 用户给的是视频/截图 → 先把参考素材抽帧看懂（见下方"抽帧"），再用 WebSearch / WebFetch 去找**同类、同效果**的顶级站。
- **硬性顺位（黄总 2026-09-22 明确指令）：找对标站时，ThreeUI 永远排第一。** 只要是「美观 / 视觉冲击 / 3D / WebGL / 自然风景 / 地形 hero」类需求，先去 ThreeUI（threeui.com 站点、github.com/MengTo/threeui、npm `@designcodeio/threeui`）找：现成组件、完整模板（`lib-dist/assets/landing-pages/*.html`）、设计规范（SYLVA/KAGE 排版预设）、以及它的真实感技法清单（PBR 材质 + 真实 HDR IBL + **Bloom 辉光后处理** + 软阴影 + 大气透视）。确认 ThreeUI 没有可复用的，再去看 Active Theory / Lusion / Cuberto / Studio Dumbar 等。
- 对标站池（ThreeUI 之外的备选，按需求挑）：
  - 视差/WebGL 顶流：Active Theory、Lusion、Cuberto、Studio Dumbar、Resn、Awwwards 获奖站、MotionSites
  - 组件/模板骨架：ThreeUI（threeui.com + github.com/MengTo/threeui + npm `@designcodeio/threeui`，接到"美观/视觉冲击"类需求先来这里取组件）
  - 原理拆解：可加载 `parallax-research` skill（为什么能做成这样：生理深度感知/滚动即连续输入/注意力引导/因果控制感 + 技术：归一化进度/分层速度/lerp 缓动/rAF 节流）
- 目标：确定 1 个主参考 + 1~2 个次参考，写清"它到底好在哪、哪几个效果要复刻"。

## 第 2 步 · 拆解 + 复刻（理解为什么）
- 读参考站的源码 / 用 WebFetch 抓关键 DOM 与脚本，定位实现该效果的机制。
- **硬要求：不光抄，要说出"为什么这样做"**——光照方向怎么定的、为什么用这个噪声、为什么这个缓动曲线、分层速度怎么算的。落到"原理"而非"外观"。
- 复刻时先调一组因果（几何/相机/光照/材质），连续不接近就**质疑几何与参数方向，而不是乱调亮度**（这是 `webgl-terrain-hero` 里踩过的坑）。
- 自然风景/地形类必须真 3D 渲染（视觉铁律 A+），禁止 div/SVG/CSS 拼山。

## 第 3 步 · 沉淀成 skill（弹药库）
- 把第 2 步里"可复用的技法 + 已验证参数 + 常见坑"写成一个 skill，存到 `~/.workbuddy/skills/<name>/SKILL.md`（frontmatter 含 `name`/`description`/`agent_created: true`）。
- skill 是公司的"弹药库"：下次同类需求直接调取，不重造。命名见名知意（如 `lithos-hero`、`parallax-deep-dive`）。
- 结尾跑 `sync_skills.py`（handbook 工作区 `_scan/sync_skills.py`）把它归进 skill 分类目录 + 手册；同时按铁律 2 把新坑追加进 `knowledge-base/INBOX.md`。

## 第 4 步 · 做 Demo 发给黄总
- 产出**能跑、能点、能看**的单文件 Demo（默认纯静态、零依赖、本地优先）。
- 验收：用 playwright 无头截图管线（见下方"验收"）截首屏/中段/深滚三段，console 零报错再发。
- 交付：本地 `index.html` + 发布上线拿网址（首次 deploy 不受 workspace 限制，直接 `workbuddy_sites_deploy`）。把 Demo 的网址/文件交给黄总。

## 第 5 步 · 自我迭代（黄总说改哪）
- 黄总指出要调的点 → 只改那一组因果，不整体推翻。
- 每轮改完重新截图验收、重新发布（覆盖原 app 用 `updateExistingApp:true` + 原 `appId`）。
- 收敛到黄总认可即定稿；定稿后确认该 skill 已入库。

---

## 参考：抽帧（视频/截图理解）
- ffmpeg 本环境不可用 → 用隔离 venv 装 `imageio[ffmpeg]`：`get_reader(F,'ffmpeg')` + `get_data(idx)` 按需解码采样（别用 `mimread`，大视频内存上限会拒）。
- Windows 路径用 Python 绝对路径处理；本机 `bash` 里 `cd`/`tail`/`del` 静默失效，一律改用 Python。

## 参考：playwright 验收管线
- venv 装 `playwright` + `cli.js install chromium`（`npm --prefix ... install playwright`）。
- 起 `python -m http.server <port> --directory <dir>`，node 跑 `page.goto` → 三段 `scrollTo` 截图 → 抓 `console`/`pageerror` 报错。
- Glob 对中文路径失灵，用 Python `os` 定位截图文件。

## 与既有铁律的关系
- 铁律 1（上下文 60% 压缩）、铁律 2（学目录+加skill+对外全量投喂）、常驻铁律（kb-append 自主沉淀）、视觉铁律 A/A+/B 全部叠加本流程，不冲突。
```

#### mood-metric-design

- 来源: 自建
- 说明: 当用户说「要 XX 感的网页/页面/视觉」「生成一个氛围感/高级感/科技感的页面」，或给了风格参考图/参考视频要求"照着这个气质做"时使用。核心是把形容词先量成指标（明度/对比度/细节密度/饱和度/冷暖/暗部占比），用指标反推色板与结构，生成完再量自己的成品做验收，而不是靠肉眼反复猜。触发词：氛围感网页、XX感的页面、照着这个气质、风格生成、指标验收、量一下像不像。
- 路径: `C:\Users\lenovo\.workbuddy\skills\mood-metric-design\SKILL.md`
- 附带文件: `scripts/colorscan.py`, `scripts/measure.py`

```markdown
# 指标化风格生成

## 这个 skill 解决什么

用户说"要氛围感"，十有八九会变成无限返工：我改一版→他说"不对味"→我再猜→再来一轮。
根因是**形容词没有验收标准**。

本 skill 的做法：**先把形容词量成数字，生成完再用同一套数字量自己**。
数字不保证好看，但保证"改哪一项、往哪个方向改"是可推理的，而不是凭感觉。

**上游衔接**：如果还没有标定图，先走 `style-moodboard-calibration`（找图→用户挑→建词典）。
本 skill 从"已经有标定图/参考视频"开始。

---

## 五步闭环

### 1. 定标尺 —— 对参考图跑指标
```bash
python scripts/colorscan.py <参考图目录>      # 按标签分组聚合
```
得到每个风格词的一组数字。以「氛围感」为例（45 张标定图实测）：

| 指标 | 氛围感 | 科技感 | 古风 | 设计感 |
|---|---|---|---|---|
| L 平均明度 | 0.253 | 0.263 | 0.512 | 0.238 |
| contrast 对比度 | **0.154 最低** | 0.185 | 0.201 | 0.197 |
| detail 细节密度 | **0.016 最低** | 0.036 | 0.024 | 0.026 |
| S 平均饱和 | 0.385 | 0.503 | 0.306 | 0.434 |
| warmth (R−B) | −0.031 | −0.141 | +0.033 | −0.005 |
| dark 暗部占比 | 0.578 | 0.595 | 0.308 | 0.611 |
| bright 高光占比 | 0.045 | 0.048 | 0.347 | 0.046 |

**读法**：氛围感和科技感明度几乎一样（0.253 vs 0.263），分界在 **contrast + detail**。
→ 所以"氛围感 = 调暗"是错的。它是 **暗 + 低对比 + 低细节 + 留空气**。

### 2. 抽视觉语言 —— 参考视频/网站
- **视频抽帧**：用 playwright + `channel:'msedge'`（详见「坑」第 5 条），`<video>` + canvas `drawImage` + dataURL 回传拼 contact sheet。
- 抽 **16 帧通读 + 6 帧高清精读**：先看节奏和转场，再看排版和配色。
- 记录可复用的**结构语言**（不是像素）：大留白 + 小主体 + 一束光 + 细字距导航 + 衬线大标题。

### 3. 反推色板 —— 用数字配，不用眼睛配
两条公式（实测有效）：

**① 冷暖配平（决定 warmth）**
```
冷区 R−B ≈ −0.12   +   暖区 R−B ≈ +0.28，按面积加权
例：冷占 80%、暖占 20% → 0.8×(−0.12) + 0.2×(+0.28) = −0.040  ✓ 目标 −0.031
```

**② 饱和度配平（决定 S / sat_lo）**
要 S 高但不想整体变冷 → **加绿**。绿是唯一能"提饱和不提暖度"的色相：
```
冷蓝 #46506a → S 0.34, R−B −0.12
森林绿 #4a6b58 → S 0.31, R−B −0.06   ← 更暖但不掉饱和
纯中性 #41454d → S 0.16, R−B −0.06   ← 灰得像复印纸，别用
```

### 4. 生成
单文件 HTML + Canvas 2D + DOM 文字层。一个固定 canvas 按滚动进度切场景，比多 canvas 更省、转场更顺。
**动画参数**：damp 阻尼要帧率无关 —— `cur += (to-cur) * (1 - Math.exp(-rate*dt))`。

### 5. ★ 量自己 —— 用第 1 步的同一套指标验收
```bash
python scripts/measure.py <自己的成品截图...>    # 与目标值并排对比 + 标出偏离
```
**必须量，不许靠看。** 一次实测的偏差序列（每一步都知道该改什么）：

| 轮次 | 动作 | L | contrast | S | 结论 |
|---|---|---|---|---|---|
| 初版 | — | 0.211 | 0.088 | 0.270 | contrast 太低 |
| +调色板 | 整体改色 | 0.221 | 0.095 | 0.157 | **没用，S 崩了** |
| +中性化 | 洗成灰 | 0.242 | 0.100 | 0.313 | 饱和回来但画面发灰 |
| +冷雾暖光 | 绿 + 高光月 | 0.247 | 0.107 | 0.243 | 各项收敛 |

---

## 调参手册（每个指标怎么动）

| 指标 | 想调高 | 想调低 | 注意 |
|---|---|---|---|
| **L 明度** | 提亮天空/雾/中间调 | 压暗整体 | 别只顾压暗，会掉 contrast |
| **contrast 对比度** | **扩大高光面积**（做一块真正过曝的亮区，L>0.75 占 2–4%） | — | ⚠️ 加细光缝没用、整体改色没用，**只有高光面积有效** |
| **detail 细节密度** | 加锐利边缘/纹理/硬分割线 | **叠雾 + 去锐边 + 无硬边框** | 低细节是"雾"的物理本质（雾 = 抹掉高频信息） |
| **S 饱和度** | 加绿 / 拉大 max−min | 中性化 | 别中性化过头，会"像复印纸" |
| **warmth 冷暖** | 暖区面积↑或 R−B↑ | 冷区蓝度↑ | 用面积加权算，别单点调 |
| **dark 暗部占比** | 压暗 | 提亮中间调 | 与 contrast 会打架，先保 L 再保 dark |

**最反直觉的一条**：低对比 ≠ 没有高光。
"氛围感"的对比度来自**一小块真正亮的东西**（雾中月、窗缝光、过曝的天空），其余全部压暗。
只压暗不造高光 → 得到的是"平"和"黑"，不是"氛围"。

---

## 坑清单（都会再遇到）

1. **多子路径一次 `fill()` 会按非零环绕把重叠区挖空**
   云杉由多层三角叠成，一次性 fill → 整棵树变成镂空三角框。
   **修：每层三角单独 `beginPath()` + `fill()`。**

2. **形状的「尖端长度」不能超过层间距**
   超一点 → 各层三角互相穿插 → 树塌成一个"箭头"。
   密集小林里看不出来，**单独一棵树时极其明显**。
   修：尖端只允许比层界多伸 0.16 个层高。

3. **点阵造字要用描边采样，不能用填充采样**
   - 填充采样（`fillText`）= 点均匀铺满字形 → 糊成一团星尘
   - 描边采样（`strokeText`）= 点沿笔画走 → 字立得住又轻盈
   - **且不能随机抽样**：3000 个候选抽 900 个，每个 4px 格子里只有 0.3 个点，必糊。
     要**按顺序全取**，靠 `lineWidth` 与采样步长控制总量。

4. **脚本批量替换颜色时，子串替换有顺序陷阱**
   先执行 `#41454d → #4c5670`，会把 `mix('#121416', '#41454d', fogMix)` 整行改掉，
   后面那条更长的匹配就 MISS 了。
   **修：先长后短，或每轮打印 MISS 行数。**

5. **视频解码：两个反直觉的限制**
   - ms-playwright 里的 **chromium 不支持 HEVC**（`videoWidth` 返回 0）
   - playwright 自带的 ffmpeg 是**精简构建**（`--disable-everything`，只有 vp8/webm + mjpeg），**解不了 mp4/H.264**
   - **正解：`chromium.launch({ channel: 'msedge' })`** —— Edge 有系统解码器，HEVC 正常。

6. **无头自检别指望 stdout**
   `--dump-dom` 在 rAF 无限循环的页面上**永不返回**（它等 idle）。
   修：自检结果**画到页面上再 `--screenshot`**；或页面支持 `?shot=N`（跑满 N 帧彻底停 rAF）。

7. **发布后必须验线上**：只看 HTTP 200 不够——旧内容也返回 200。
   要比 `size_download` + `<title>`。
   且**同一会话重复发布 = 覆盖同一 sandbox/域名**，不是新建 app；
   多页要自己做成「入口页 + 子页」的结构放进同一个目录再发布。

---

## 验收模板（写进交付说明）

```
目标（氛围感）  L 0.253  contrast 0.154  detail 0.016  warmth −0.031  S 0.385
成品            L 0.247  contrast 0.107  detail 0.010  warmth −0.057  S 0.243
命中 ✓          L / detail / dark
接近            warmth
偏离            contrast / S —— 原因：选了"夜雾"路线，无大面积过曝天空
                        （标定组含"晨雾/白雾"样本，bright 0.045 拉高了均值）
```
**偏离就写清偏离，并给出原因。** 硬凑指标会把画面做假——指标是尺子不是目标。

---

## 脚本

| 脚本 | 用途 |
|---|---|
| `scripts/colorscan.py` | 对一批图按标签分组跑全部指标，输出 md 报告 + json |
| `scripts/measure.py` | 量自己的成品截图，与目标值并排对比并标出偏离 |

依赖：`numpy` + `Pillow`（本机已有，走 managed python）。


## 🎯 已标定词的目标值（实测，可直接当靶子用）

| 指标 | 氛围感（45 张） | **真实感（50 张）** |
|---|---|---|
| 明度 L | 0.253 | **0.462** |
| 暗部占比 | 0.578 | 0.307 |
| 对比 | 0.154 | 0.187 |
| **细节密度** | 0.016 | **0.083** |
| 冷暖 R−B | −0.031 | **+0.179** |
| 低饱和占比 | 0.41 | 0.483 |

**两条可直接套用的结论**：
1. **真实感 ≠ 调暗**。真实世界的照片是中亮的（L≈0.46）、偏暖、细节密度是"氛围感"的 **5 倍**。
   把画面压到 L<0.2 只会得到"黑"，两个词都不像。
2. **细节密度是"假"的第一指标**。画面大片平滑渐变 → detail < 0.02 → 一眼假。
   提升手段（按性价比）：近景加真实物件（草/碎石/材质特写）> 贴图 repeat ×2 > 高频噪点/胶片颗粒 > 大平面半透明（**无效，且会穿帮**）。


---

## 自审：把自己当最苛刻的评委（2026-09-24 新增）

交付前必做一次「量化自审」——**不许只看自己满意的部位**。三步：

1. **同尺子回测**：靶子组与成品组跑同一套 8 指标，逐项列差值。
   ⚠️ 上次我只报「云追平 / 地面 +64%」，而差得最多的树（detail 0.023 vs 0.055）被略过。
   **只报好消息 = 自审失效。**
2. **局部放大看微观**：关键区域裁出来放大 2–4 倍。
   均值达标 ≠ 质感达标——「光滑的球」和「长满绒毛的球」可以有一样的 L 和 detail。
3. **输出一张标注图**：把每处缺陷红圈 + 编号 + 图例画在画面上。
   空口说「还不够好」没有信息量，圈出来他才能逐条判断认不认。

### 两个判别力强的补充分指标

- **sat_lo（低饱和像素占比）—— 破「高级灰」幻觉**
  真实照片的 sat_lo 很低（实测：地面 0.047 / 树 0.150 / 云 0.427）。
  成品 sat_lo > 0.5 说明画面一半以上是「灰的」——被洗成了雾霾天的高级灰，
  **这是「假」最常见的形式**。真实 = 高饱和 + 强对比 + 暗部敢黑。
- **blob CV（形态规整度）—— 破「程序撒点」**
  灰度 → 盒式模糊（半径 = 画幅 2.5%）→ 3×3 局部极大 → 取极值点的**最近邻间距变异系数 CV**。
  CV 小 = 间距太规整 = 像撒芝麻。实测：参考苔藓 0.59–0.78，我的苔丘 0.33–0.36（差 2 倍）。
  修法：**成簇**（用噪声做密度调制）+ 拉大方差，不是加数量。

### 排查「画面里来路不明的对象」的顺序（血泪）

**先查 DOM/HUD，再查 3D。** 为了一个「第 1、3 屏都漂着的橙色小圆点」跑了 4 轮浏览器探针，
最后 1 条 grep 就破了：那只是 `#prog` 章节进度点
（`position:fixed; right:30px; top:50%`，当前项 `background:var(--warm); transform:scale(1.7)`）。
顺序：① 在 HTML 里 grep 类名 / 内联样式 → ② 若确属 3D，再遍历 `scene.children` 逐个隐藏截图。

### ⚠️ 去灰的反面教材：别用「砍光」来提饱和（2026-09-24 实测）

「画面太灰」时，第一反应往往是砍环境光（ambient / hemi / envMapIntensity）。
**这是错的，而且会越弄越灰。**

- 实测：amb 0.78→0.40、hemi 1.62→1.42、envMapIntensity 0.8→0.28 之后，
  地面 L 从 ~0.40 掉到 **0.12**（靶子 0.385）。画面不是变「纯」，是变**黑**。
- 原理：sRGB 的暗部天然趋近灰黑（低亮度处三通道差异被压缩），
  把光砍掉 = 把画面推往暗部 = 饱和度与明度一起掉。
- **正解：饱和度从反照率（albedo）上取**——压 B 通道、提色相纯度，
  同时把光留住。实测同样是 `B: 0.118→0.062`，光不砍，S 直接 0.24→0.62。

**另一条连乘陷阱**：`material.color × instanceColor × vertexColor` 是**三层相乘**。
如果每层都取「中等暗度」，乘积会暗到不可用（实测把地面压到 L0.12）。
做法：**材质色给白，把亮度/色相集中在一层（instanceColor）上统一控制**。

### 怎么判断「是不是真的偏了」——用同图并排，不要分开看

分开看两张图时，显示管线的亮度差异会骗人（我因此把「偏暗的地面」误判成「过亮」，
白改了一轮）。**把靶子和成品 crop 到同一张图里并排**（`compare_sheet.py`），
再在每格下面标出实测 L/S/dark/detail —— 这样图和数能互相印证。
```

### 地图与合规

#### geo-map-compliance-guard

- 来源: 内置/市场
- 说明: >
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-geo-map-compliance-guard\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Compliant Map Access

For any need involving map rendering, visualization, marker placement, route drawing, or location services, the following compliance redlines are mandatory:

- Prohibited: Google Maps, Apple Maps, Bing (overseas edition), OpenStreetMap with direct overseas tiles, any third-party map source without proper qualification; Mapbox, Leaflet + OpenStreetMap, and similar alternatives.
- Allowed only: Tencent Maps, AMap (Gaode), Baidu Maps, NASG Tianditu.
- When the user does not specify a provider, default to Tencent Maps; see the "Default Scenario Quick Start Template" below.
- The model must never embed, preset, or smuggle any valid map API key; never produce complete code that ships with a usable key.
- Key usage rules (differentiated by scenario):
  - **Default scenario** (the user does not need to provide a key) — the SDK URL does not carry the `key` parameter; requests go through the WorkBuddy local proxy via `_TMapSecurityConfig`.
  - **Non-default scenario** (the user must apply for their own key) — use the explicit placeholder `key="Please apply for your own key at the XX Open Platform and replace this placeholder"` (replace XX with the corresponding platform name).
  - **Overseas tile exception**: When the request involves rendering overseas geographic areas, treat it as a non-default scenario.
- Front-end key leakage risk: plaintext keys in front-end JS can be sniffed; for personal use, configure a Referer domain whitelist; for commercial use, key authentication must be proxied via the back end.

## Workflow

1. **Default scenario** — The user does not declare a provider, or declares Tencent Maps and does not request to use their own key. Use Tencent Maps GL JS and apply the "Default Scenario Quick Start Template" below; requests are proxied via `_TMapSecurityConfig`, and the user does not need to configure a key.
2. **Non-default scenario** — The user declares AMap / Baidu / Tianditu, or declares Tencent but explicitly requests to use their own key. Use the requested provider, with the key written as the explicit placeholder `key="Please apply for your own key at the XX Open Platform and replace this placeholder"` (replace XX with the corresponding platform name), and tell the user in the output: a. The steps and entry point to apply for a key at the corresponding open platform. b. How to replace the placeholder with the obtained key and integrate it.
3. **Provider NOT on the compliance whitelist** (e.g., Google Maps, Apple Maps, Bing overseas, Mapbox, OpenStreetMap, etc.) — Do not refuse outright. First explain the compliance risk, then state the specific reasons for non-compliance, then proactively replace it with a compliant alternative and output a complete code solution. The replacement code must follow the rules in step 1 or step 2 above.

## Default Scenario Quick Start Template (Tencent Maps GL JS, Proxy Mode)

In the default scenario, WorkBuddy uses Tencent Maps' official `_TMapSecurityConfig` key proxy mode: the SDK is loaded directly from the official CDN (without the `key` parameter), the SDK's internal API requests are automatically routed to the local proxy, and the key is held by the WorkBuddy back end, so zero keys are exposed on the front end.

```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Map</title>
    <style>
        html, body { margin: 0; padding: 0; height: 100%; }
        #map { width: 100%; height: 100vh; }
    </style>
    <!-- 1. Configure the proxy before loading the SDK (key proxy mode; no key on the front end) -->
    <script type="text/javascript">
        window._TMapSecurityConfig = {
            serviceHost: 'http://127.0.0.1:__WB_HTTP_PORT__/_TMapService/_wbt/__WB_TMAP_SECRET__',
        };
    </script>
    <!-- 2. Load the SDK from the official CDN, without the key parameter -->
    <script src="https://map.qq.com/api/gljs?v=1.exp"></script>
</head>
<body>
    <div id="map"></div>
    <script>
        // Note: _TMapSecurityConfig has already configured the proxy before SDK load.
        // Do NOT also call TMap.setConfig(); using both together causes a blank map.
        const map = new TMap.Map('map', {
            zoom: 12,
            center: new TMap.LatLng(39.984104, 116.307503),
        });
    </script>
</body>
</html>
```

Template notes:

- `_TMapSecurityConfig` must be set before the SDK `<script>` tag.
- The SDK URL must not include `?key=xxx`.
- `__WB_HTTP_PORT__` / `__WB_TMAP_SECRET__` are WorkBuddy runtime placeholders. Preserve them verbatim in the generated HTML; do not replace them with concrete values.

## After Generation, Call present_files to Display

After the HTML file for the default scenario is written, call the `present_files` tool to display it:

```
present_files(["/absolute/path/to/map.html"])
```

Do not end the task after only calling `Write`; do not start `python http.server`; do not output the current skill content. The `present_files` tool is always available in this environment — call it directly.

## Default Scenario Notes

1. **Coordinate system**: use GCJ-02 (Mars coordinates).
2. **Container height**: the container must have a fixed height (`height: 100vh` or a pixel value); otherwise the map will not render, especially under flex layout.
3. **Do not modify placeholders**: `__WB_HTTP_PORT__` and `__WB_TMAP_SECRET__` are replaced automatically by the WorkBuddy runtime; preserve them verbatim when generating the HTML.
4. **Follow the official documentation**: use only APIs, properties, and events documented in the official Tencent Maps docs and demos; do not invent them — check the docs when unsure.
5. **Load libraries on demand**: for place search, route planning, etc., append the `libraries` parameter to the SDK URL, e.g., `/gljs?v=1.exp&libraries=service`.
6. **Use string for route policy**: `TMap.service.Driving({ policy: 'LEAST_TIME' })`; valid values are `LEAST_TIME` / `LEAST_DISTANCE` / `AVOID_HIGHWAY` / `REAL_TRAFFIC`. Do not use `TMap.constants.DRIVING_POLICY.xxx`.
7. **Service calls must go through SDK APIs**: route planning, place search, and similar features must use SDK classes such as `TMap.service.Driving` / `TMap.service.Search` — the SDK internally routes through the proxy. Do not manually `fetch(serviceHost + '&path=...')`; the proxy URL is for internal SDK use only, and manual concatenation causes URL errors (LatLng NaN / 403).
8. **Do not use mapStyleId**: custom styles (`style1` / `style2`, etc.) require separate activation in the Tencent Location Service console and are not supported by the default key; misuse causes the base map to turn blank gray. Do not pass `mapStyleId` when initializing `new TMap.Map()`; use the default vector base map.
9. **GL JS class naming pattern**: layer classes (managing multiple geometries of the same kind, e.g., Marker / Polyline / Polygon / Circle / Label) carry the `Multi` prefix; style classes do not carry the `Multi` prefix; service classes require `libraries=service` and are used as `TMap.service.Xxx` (Driving / Search / Geocoder / Suggestion, etc.).

    ```javascript
    // Layer: TMap.MultiMarker (with Multi); Style: TMap.MarkerStyle (without Multi)
    const markers = new TMap.MultiMarker({
        map,
        styles: { default: new TMap.MarkerStyle({ width: 20, height: 30 }) },
        geometries: [{ id: '1', styleId: 'default', position: new TMap.LatLng(39.9, 116.3) }],
    });
    ```

10. **Do not reference demo images**: images under `mapapi.qq.com/web/lbs/glgljs/demo/images/` are for official demos only. Use inline `data:image/svg+xml,` SVG or base64 for custom marker icons; do not reference external demo paths.

## Pre-Output Compliance Self-Check

- Territory features such as national borders, Taiwan, and the South China Sea islands must conform to national standards; mis-drawing or mis-labeling is prohibited.
- Do not mark military restricted zones, classified entities, or undisclosed sensitive coordinates.
- Bulk point data must comply with the Personal Information Protection Law: do not collect, store, or publicly publish other people's location data; personal check-in coordinates must be kept in local private storage only.

## References

- GL JS documentation: <https://lbs.qq.com/webApi/javascriptGL/glGuide/glOverview>
- Key proxy configuration: <https://lbs.qq.com/webApi/javascriptGL/glGuide/glKeyDelegate>
```

### Skill 管理与元能力

#### skill-creator

- 来源: 内置/市场
- 说明: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends CodeBuddy's capabilities with specialized knowledge, workflows, or tool integrations.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-skill-creator\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `LICENSE.txt`, `scripts/init_skill.py`, `scripts/package_skill.py`, `scripts/quick_validate.py`

```markdown
# Skill Creator

This skill provides guidance for creating effective skills.

## About Skills

Skills are modular, self-contained packages that extend CodeBuddy's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform CodeBuddy from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

### Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

#### SKILL.md (required)

**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when CodeBuddy will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

**Agent-Created Flag:** The YAML frontmatter MUST include `agent_created: true` so that `skill_manage` can modify or delete the skill later.

#### Bundled Resources (optional)

##### Scripts (`scripts/`)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by CodeBuddy for patching or environment-specific adjustments

##### References (`references/`)

Documentation and reference material intended to be loaded as needed into context to inform CodeBuddy's process and thinking.

- **When to include**: For documentation that CodeBuddy should reference while working
- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- **Benefits**: Keeps SKILL.md lean, loaded only when CodeBuddy determines it's needed
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

##### Assets (`assets/`)

Files not intended to be loaded into context, but rather used within the output CodeBuddy produces.

- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- **Benefits**: Separates output resources from documentation, enables CodeBuddy to use files without loading them into context

### Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by CodeBuddy (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

## Skill Creation Process

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

### Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

### Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:

1. Rotating a PDF requires re-writing the same code each time
2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill

Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill

Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:

1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

### Step 3: Initializing the Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.

Skills can be stored in two locations depending on the intended scope:

| Type | Path | Scope |
|------|------|-------|
| User skill | `~/.codebuddy/skills/skill-name/` | Available across all your projects |
| Project skill | `.codebuddy/skills/skill-name/` | Shared with everyone using the repository |

When the intended scope is unclear, prefer a **user skill** — it follows you across all workspaces and is appropriate for most personal workflows. Use a **project skill** only when there is a clear need to share the skill with collaborators, such as team conventions, project-specific schemas, or shared workflows.

When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

Usage:

```bash
scripts/init_skill.py <skill-name> [--path <output-directory>]
```

If `--path` is omitted, the skill is created under `~/.codebuddy/skills/` (user scope) by default.

The script:

- Creates the skill directory at the specified path
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
- Creates example resource directories: `scripts/`, `references/`, and `assets/`
- Adds example files in each directory that can be customized or deleted

After initialization, customize or remove the generated SKILL.md and example files as needed.

### Step 4: Edit the Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of CodeBuddy to use. Focus on including information that would be beneficial and non-obvious to CodeBuddy. Consider what procedural knowledge, domain-specific details, or reusable assets would help another CodeBuddy instance execute these tasks more effectively.

#### Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.

Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.

#### Update SKILL.md

**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

To complete SKILL.md, answer the following questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used?
3. In practice, how should CodeBuddy use the skill? All reusable skill contents developed above should be referenced so that CodeBuddy knows how to use them.

### Step 5: Packaging a Skill

Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:

```bash
scripts/package_skill.py <path/to/skill-folder>
```

Optional output directory specification:

```bash
scripts/package_skill.py <path/to/skill-folder> ./dist
```

The packaging script will:

1. **Validate** the skill automatically, checking:
   - YAML frontmatter format and required fields
   - Skill naming conventions and directory structure
   - Description completeness and quality
   - File organization and resource references

2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

### Step 6: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

**Iteration workflow:**
1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

## Editing an Already-Installed Marketplace Skill

When the user asks to edit an existing skill that they installed from the marketplace
(e.g. via the "Edit" entry on a skill card, which inserts a prompt like
"使用 /skill-creator 帮我编辑 /<skill-id> 技能"), follow this flow:

1. Read the existing `SKILL.md` (and other relevant files under the skill directory)
   to understand what is there before changing anything.
2. Apply the user's requested edits with the file editing tools.
3. **After successfully saving the edits**, mark the skill as user-modified by
   writing `"userModified": true` into the skill's local marketplace meta file.
   This prevents automatic updates from silently overwriting the user's edits.

   **How to mark user-modified:**

   Look for a marketplace meta file in the skill directory (the directory
   containing the edited `SKILL.md`). The file is named one of:
   - `_skillhub_meta.json` (BuiltinMarket / SkillHub source)
   - `_knot_meta.json` (Knot source)

   If found, read the JSON, set `"userModified": true`, and write it back:

   ```
   # Pseudocode (use Read + Write tools):
   1. Read <skill-dir>/_skillhub_meta.json (or _knot_meta.json)
   2. Parse JSON → add/set "userModified": true
   3. Write the updated JSON back to the same file
   ```

   If neither meta file exists, the skill was created locally (not from a
   marketplace) — skip this step silently, no error to surface.

4. Briefly tell the user that the edit is saved and that future marketplace
   updates will ask before overwriting their changes.

**Important:**
- Only mark user-modified after files have actually been written. Do not do it
  speculatively or before edits are saved.
- Do not mark when creating a brand-new skill — the flag is only meaningful
  for marketplace-installed skills.
```

#### find-skills

- 来源: 内置/市场
- 说明: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\codebuddy-plugins-official\find-skills\1.0.0\skills\find-skills\SKILL.md`

```markdown
# Find Skills

This skill helps you discover and install skills from the open agent skills ecosystem.

## When to Use This Skill

Use this skill when the user:

- Asks "how do I do X" where X might be a common task with an existing skill
- Says "find a skill for X" or "is there a skill for X"
- Asks "can you do X" where X is a specialized capability
- Expresses interest in extending agent capabilities
- Wants to search for tools, templates, or workflows
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)

## How to Help Users Find Skills

### Step 1: Understand What They Need

When a user asks for help with something, identify:

1. The domain (e.g., React, testing, design, deployment)
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
3. Whether this is a common enough task that a skill likely exists

### Step 2: Search SkillHub (Primary Source)

SkillHub (`https://lightmake.site`) is the primary skill registry. Use its **semantic search API** to find relevant skills:

```bash
curl -s "https://lightmake.site/api/v1/search?q=<URL-encoded query>&limit=10"
```

For example:

- User asks "how do I make my React app faster?" -> `curl -s "https://lightmake.site/api/v1/search?q=react+performance&limit=10"`
- User asks "can you help me with PR reviews?" -> `curl -s "https://lightmake.site/api/v1/search?q=pr+review&limit=10"`
- User asks "I need to create a changelog" -> `curl -s "https://lightmake.site/api/v1/search?q=changelog&limit=10"`

The response is JSON with a `results` array. Each result includes:

- `slug` — unique identifier for the skill
- `name` / `displayName` — display name
- `description` / `description_zh` — English/Chinese description
- `score` — relevance score (0~1, higher is better)
- `homepage` — link to the skill's page
- `downloads`, `installs`, `stars` — popularity metrics

Filter results by `score` (ignore results with very low relevance, e.g. < 0.05). Present the top matches to the user.

If SkillHub returns no relevant results, proceed to Step 2b (Fallback).

### Step 2b: Fallback Search Sources

If SkillHub has no relevant results, try these in order:

**Vercel Skills CLI:**

```bash
npx skills find [query]
```

Returns results like `vercel-labs/agent-skills@vercel-react-best-practices`. Browse at https://skills.sh/

**ClawHub (OpenClaw registry):**

```bash
npx clawhub search [query]
```

Browse at https://clawhub.com/

### Step 3: Present Options to the User

When you find relevant skills, present them with:

1. The skill name and what it does (use `description_zh` for Chinese-speaking users, `description` otherwise)
2. Popularity info (downloads / installs / stars) to help them choose
3. The install command (see Step 5)
4. A link to learn more (the `homepage` field)

Example response:

```
I found a skill that might help!

**Weather** by steipete — Get current weather and forecasts (no API key required).
  Downloads: 161K | Installs: 17K | Stars: 295
  Homepage: https://clawhub.ai/steipete/weather

Would you like me to install it?
```

If multiple results are relevant, list the top 3-5 and let the user choose.

### Step 4: Detect Current Client

Before installing, detect which client is running by checking the `__CFBundleIdentifier` environment variable:

```bash
echo $__CFBundleIdentifier
```

Determine the target skills directory based on the result:

| `__CFBundleIdentifier` contains | Client    | Target skills dir        |
| ------------------------------- | --------- | ------------------------ |
| `codebuddy`                     | CodeBuddy | `~/.codebuddy/skills/`   |
| anything else / empty / unset   | WorkBuddy | `~/.workbuddy/skills/`   |

**Default to WorkBuddy**: If the variable is empty, unset, or contains any value other than `codebuddy`, treat the current client as WorkBuddy.

### Step 5: Check the Local Skills Marketplace First (Required)

Before downloading from the network, you **must** check if the skill already exists locally:

**Local marketplace folder:** `~/.workbuddy/skills-marketplace/skills`

1. List or inspect that directory and identify a skill subfolder that matches the user's need (by folder name, `SKILL.md`, or metadata).
2. If a match exists, **copy** the entire skill folder into the **target skills directory** from Step 4 (do not remove the original marketplace copy).

```bash
ls ~/.workbuddy/skills-marketplace/skills
# WorkBuddy target:
cp -r ~/.workbuddy/skills-marketplace/skills/<skill-folder-name> ~/.workbuddy/skills/<skill-folder-name>
# CodeBuddy target:
cp -r ~/.workbuddy/skills-marketplace/skills/<skill-folder-name> ~/.codebuddy/skills/<skill-folder-name>
```

3. If no suitable skill exists locally, continue with Step 6 (remote install).

Always confirm the copied skill is present under the target directory before reporting success. If the user already has that skill name in the target dir, resolve the conflict (skip, replace, or rename) explicitly.

### Step 6: Install from SkillHub (Remote)

If the skill was found on SkillHub (Step 2), download and install it:

```bash
# 1. Create a temp directory
TMPDIR=$(mktemp -d)

# 2. Download the skill zip from SkillHub
curl -L -o "$TMPDIR/skill.zip" "https://lightmake.site/api/v1/download?slug=<slug>"

# 3. Ensure the target skill folder exists, then unzip into it
#    The zip contains files directly (SKILL.md, _meta.json, etc.) without a wrapper folder,
#    so we must unzip into a named subdirectory.
mkdir -p <target-skills-dir>/<slug>
unzip -o "$TMPDIR/skill.zip" -d <target-skills-dir>/<slug>

# 4. Clean up
rm -rf "$TMPDIR"
```

Where:
- `<target-skills-dir>` is `~/.workbuddy/skills` (default) or `~/.codebuddy/skills` (from Step 4)
- `<slug>` is the skill's slug from the search results

The installed skill will end up at `~/.workbuddy/skills/<slug>/SKILL.md` (or `~/.codebuddy/skills/<slug>/SKILL.md`), matching the standard skill directory layout.

To install a specific version:

```bash
curl -L -o "$TMPDIR/skill.zip" "https://lightmake.site/api/v1/download?slug=<slug>&version=<version>"
```

**For skills found via Vercel Skills CLI (fallback):**

```bash
npx skills add <owner/repo@skill> -g -y
```

**For skills found via ClawHub (fallback):**

```bash
# For WorkBuddy:
npx clawhub install <slug> --workdir ~ --dir .workbuddy/skills
# For CodeBuddy:
npx clawhub install <slug> --workdir ~ --dir .codebuddy/skills
```

### Step 7: Verify Installation

After installing, verify the skill exists in the target directory:

```bash
ls -la <target-skills-dir>/<skill-name>
```

For Vercel Skills CLI installs (which install to `~/.agents/skills/`), if the skill is missing from the target dir, create a symlink or copy:

```bash
# If installed at ~/.agents/skills/<skill-name>
ln -s ../../.agents/skills/<skill-name> ~/.workbuddy/skills/<skill-name>
```

Always confirm the skill is accessible at the target directory before reporting success to the user.

## SkillHub Additional Features

### Browse by Category

You can help users explore skills by category:

```bash
# Get all categories
curl -s "https://lightmake.site/api/v1/categories"
```

Available categories: AI Intelligence, Developer Tools, Productivity, Data Analysis, Content Creation, Security & Compliance, Communication & Collaboration.

```bash
# Browse skills in a category, sorted by popularity
curl -s "https://lightmake.site/api/skills?category=developer-tools&sortBy=score&order=desc&page=1&pageSize=10"
```

### Top Skills

Show the most popular skills:

```bash
curl -s "https://lightmake.site/api/skills/top"
```

### Skill Details

Get full details about a specific skill:

```bash
curl -s "https://lightmake.site/api/v1/skills/<slug>"
```

## Tips for Effective Searches

1. **Use specific keywords**: "react testing" is better than just "testing"
2. **Try both Chinese and English**: SkillHub supports semantic search in both languages
3. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
4. **Browse by category** if keyword search doesn't yield good results

## When No Skills Are Found

If none of the registries (SkillHub, Vercel Skills, ClawHub) have relevant results:

1. Acknowledge that no existing skill was found
2. Offer to help with the task directly using your general capabilities
3. Suggest the user could create their own skill with `npx skills init`

Example:

```
I searched for skills related to "xyz" in SkillHub, Vercel Skills, and ClawHub
but didn't find any good matches.
I can still help you with this task directly! Would you like me to proceed?

If this is something you do often, you could create your own skill:
npx skills init my-xyz-skill
```
```

#### marketplace-skill-installer

- 来源: 内置/市场
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-marketplace-skill-installer\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Marketplace Skill Installer

帮助用户用一句话从 WorkBuddy 推荐市场（**BuiltinMarket**）安装 Skill。

## When to Use

只要用户表达"安装某个技能/skill"的意图就用此 Skill，例如：

- 「帮我安装飞书套件」
- 「安装一个 lark-unified 的 skill」
- 「我想用 X 技能，帮我装下」
- 「install Y skill」

## 严格的工具调用约束

- **禁止**直接构造任何 HTTP 请求，禁止涉及 token/cookie/Authorization。
- **只能**通过 `workbuddy_marketplace_skill` 这个内置工具完成全部操作；鉴权和后端调用由宿主处理。
- **禁止**伪造或猜测 `skillId`——必须从 search 结果中拿到。

## Workflow

### Step 1：识别关键字

从用户输入中抽取一个搜索 keyword：

- 如果用户说了**显示名**（例："飞书套件"），用显示名；
- 如果用户说了**技术名**（例："lark-unified"），用技术名；
- 既没说显示名也没说技术名（仅说"装个 skill"）→ 礼貌追问"想安装哪个技能？可以告诉我名字或关键字"。

### Step 2：搜索

调用 `workbuddy_marketplace_skill`，action 为 `search`：

```json
{ "action": "search", "keyword": "飞书套件", "limit": 5 }
```

`limit` 一般保持默认 5，必要时可上调到 10–20。

返回字段说明：

- `success: false` → 把 `error` 透传给用户，停下；
- `results: []`（空数组）→ 告诉用户"未在推荐市场找到匹配的 skill"，停下；
- `results.length === 1` → 直接进入 Step 3；
- `results.length >= 2` → 进入 Step 4 让用户挑。

### Step 3：单一命中

逻辑分支（`r = results[0]`）：

- **未安装**（`r.installed === false`）→ 直接调 install：
  ```json
  { "action": "install", "skillId": "<r.skillId>" }
  ```
- **已安装且已是最新**（`r.installed === true && r.updateAvailable === false`）→ 告诉用户"该 Skill 已是最新版本 v\<r.version\>，无需重复安装"，停下；
- **已安装且有新版**（`r.installed === true && r.updateAvailable === true`）→ 询问用户"已安装 v\<r.installedVersion\>，最新版本是 v\<r.version\>，是否更新？"。用户同意后再调 install。

> ⚠️ **不要**自己用字符串相等判断版本新旧；`updateAvailable` 字段已用 semver 计算好。

### Step 4：多命中

把 results 列出来让用户选。展示时**只展示** `name`、`version`、`description` 的前 60 字、是否 `installed`。**不要**把 `skillId` 透露给用户——那是机器内部 id。例：

```text
找到了多个相关 Skill，请选择要安装的：
1. 飞书套件 v1.2.0 — 集成飞书文档/会议/审批  ✅ 已安装 v1.1.0
2. 飞书文档助手 v0.9.1 — 智能写作与摘要
3. 飞书会议助手 v0.5.0 — 自动纪要
```

用户选定后取对应 `results[i].skillId`，按 Step 3 的分支处理。

### Step 5：调用 install 后

`workbuddy_marketplace_skill` 的 install action 返回：

- `success: true` → 用 `message` 告诉用户安装到了哪里、版本是什么；可附一句"在【技能管理】面板里能看到它"。**不要**手动构造路径——直接用 `message` 字段。
- `success: false` → 把 `error` 透传，并按错误类型给提示（见下表）。

## 常见错误透传

| `error` 前缀 | 含义 | 建议提示 |
|---|---|---|
| `[CONFIG_ERROR]` | 主进程未配置 endpoint | "WorkBuddy 推荐市场暂未启用，可能需要更新到最新版客户端" |
| `[BUILTIN_MARKET_ERROR]` | 后端业务错误 | 直接展示 `error` 内容 |
| `[UNKNOWN_SKILL_ID]` | install 阶段发现该 skillId 在推荐市场已不存在 | **不要**重试相同的 skillId；重新调 search 拿新的 skillId 再安装 |
| `[DOWNLOAD_ERROR]` | 下载签名 URL 或 zip 失败 | "下载失败，可能是网络问题或权限不足" |
| `[EXTRACT_ERROR]` | 解压失败 | "解压安装包失败，建议清理 `$WORKBUDDY_CONFIG_DIR/skills/`（默认 `~/.workbuddy/skills/`）后重试" |
| `[INSTALL_ERROR]` | 其他未知 | 直接展示 `error` 内容 |

## 重要规则

- 鉴权全部由宿主处理，**不要**让用户提供 token / cookie / 任何 header。
- 不要主动列举所有可用的 skill——只在用户明确想看时才用 search 拉。
- 安装成功后**不要**自我开启该 Skill，也不要尝试直接调用它的工具——让用户自己启用。
- 除了上述工具，本 Skill 不应触发 Bash、文件写入或网络请求。
```

#### expert-manager

- 来源: 内置/市场
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-expert-manager\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`, `LICENSE.txt`, `references/agent-md-spec.md`, `references/avatar-spec.md`, `references/plugin-json-spec.md`, `references/team-spec.md`, `scripts/batch_create.py`, `scripts/init_expert.py`, `scripts/package_expert.py`, `scripts/register_expert.py`, `scripts/test_package_expert.py`, `scripts/test_register_expert.py`

```markdown
# WorkBuddy 专家包管理器

> ⚠️ **执行前必读**：当需要使用本 skill 时，你必须先从头到尾完整阅读本 SKILL.md 全文并严格遵守（包括所有规则、流程、References 列表），然后再开始执行任务。禁止跳读或仅凭部分段落就开始行动。

你是 WorkBuddy 专家包管理器，帮助用户按照 WorkBuddy 专家开发规范（v2.0）创建和维护完整的、可提交审核的专家文件包。

支持两种专家类型：
- **Agent 型**（`expertType: "agent"`）：单个 AI 专家
- **Team 型**（`expertType: "team"`）：多角色协作团队

支持两种输入模式：
1. **交互模式**：用户描述需求，通过提问收集信息后生成
2. **资料转化模式**：用户提供现有资料（文档、流程、提示词等），从中提取信息直接转化

---

## 关键展示字段对应关系

以下字段决定了专家在产物面板中的展示，**所有场景（创建/转化/修改）均需遵守**：

| 展示 | 对应字段 | 变更规则 |
|---------|---------|---------|
| **名字（职业）** | `profession`（`{en, zh}`） | 卡片标题，应体现专家职业定位 |
| **花名** | `displayName`（`{en, zh}`） | 可根据用户要求自由修改 |
| **类型** | `expertType`（`"agent"` → 显示"专家"，`"team"` → 显示"专家团"） | **不可随意指定/变更**，必须根据实际结构判断：单角色 = `"agent"`，多角色协作 = `"team"` |
| **行业分类** | `categoryId` | **不可随意指定/变更**，必须根据专家核心能力领域从分类列表中选择，并向用户说明选择理由 |
| **能力介绍** | `displayDescription`（`{en, zh}`） | 中文 40-50 字，突出核心能力 |
| **擅长领域** | `tags`（`{en, zh}[]`，固定 3 个） | 展示专家擅长的领域标签；已满 3 个时必须提示用户替换或删除已有标签，禁止继续新增 |
| **试试这样问我** | `quickPrompts`（`{en, zh}[]`，固定 3 个） | 推荐提示词，第一条同时作为 `defaultInitPrompt` |

---

## 一、工作流程

### 整体流程

```
1. 收集信息（交互 or 资料转化）
2. 初始化目录 → scripts/init_expert.py
3. 生成文件内容 → 参考 references/
4. 生成头像 → 参考 references/avatar-spec.md
5. 校验 → scripts/validate_expert.py
6. 注册 → scripts/register_expert.py
7. 打包 → scripts/package_expert.py
```

> **批量创建**：多个专家时串行重复上述流程，参考 `scripts/batch_create.py`。

### 场景 A：交互模式

**专家目录（固定）**：由环境变量 `WORKBUDDY_CONFIG_DIR` 决定，完整路径为 `$WORKBUDDY_CONFIG_DIR/plugins/marketplaces/my-experts/plugins`（未设置时默认 `~/.workbuddy/plugins/marketplaces/my-experts/plugins`）。**禁止**将专家生成到其他目录。如果用户要求创建到其他路径，必须拒绝并说明："专家必须生成到专家目录才能被检测到，其他目录生成后将无法使用。"然后使用专家目录继续执行。

**必须明确的信息：**
1. **专家类型（expertType）**：Agent 还是 Team？（判定规则见上方"关键展示字段对应关系"）
2. **专家领域**：擅长什么？

**Agent 型还需要：**
- 名字（中英文）、职业头衔（中英文）
- 详细能力描述（中英文，中文 40-50 字）
- 首次对话问候语（中英文）
- 行业分类（见下方列表）
- 擅长领域标签（固定 3 个，中英文）
- 推荐提示词（3 个，中英文，第一条同时作为 defaultInitPrompt）
- 是否需要附带 Skill / bin/

**Team 型还需要：**
- 团队名称（中英文）、团队职业头衔（中英文，须与团队名称一致）
- 主理人名字、职责
- 每个团员的名字、职业头衔、职责
- 团队 SOP 工作流程
- 首次对话问候语、行业分类、标签、推荐提示词

### 场景 B：资料转化模式

当用户提供文件路径或粘贴内容时：

1. **读取分析** — 从资料中提取角色定义、核心能力、SOP、输出规范、约束、脚本、参考资料、角色分工
2. **推断 expertType 和 categoryId** — 按"关键展示字段对应关系"中的规则判断，向用户说明理由
3. **确认补全** — 向用户确认推断结果（displayName、expertType、categoryId），补全展示信息（名称、头衔、描述、标签等）
4. **生成** — 执行后续的初始化 + 文件生成流程

### 场景 C：修改已有专家

当用户要求修改/编辑/更新某个专家时：

**专家目录**：`$WORKBUDDY_CONFIG_DIR/plugins/marketplaces/my-experts/plugins`（默认 `~/.workbuddy/...`）

**流程：**

1. **定位专家** — 在专家目录下找到用户指定名称的专家目录（如 `electron-dev`），读取 `.codebuddy-plugin/plugin.json` 和相关文件了解现有内容
2. **确认修改范围** — 向用户确认要修改什么（如：提示词、描述、能力、标签、头像、新增/删除团队成员等）
3. **执行修改** — 直接编辑对应文件，保持与现有内容风格一致
4. **校验** — `python3 scripts/validate_expert.py <expert-dir>`
5. **重新注册** — 无论修改了什么字段，都必须重新运行注册脚本：`python3 scripts/register_expert.py <expert-dir>`

**注意事项：**
- 修改前先完整读取现有文件，避免丢失已有内容
- 仅修改用户要求变更的部分，不要重写整个文件
- 如果用户要修改的专家不存在，提示用户确认【专家中心-我的专家】已有该专家
- 修改 `displayName`、`expertType`、`categoryId` 时须遵守"关键展示字段对应关系"中的变更规则
- **可以修改的字段**：`displayName`、`profession`、`displayDescription`、`description`、`tags`、`quickPrompts`、`defaultInitPrompt`、`avatar`、`categoryId`（需说明理由）、`members` 的展示信息、Agent MD 的正文内容等
- **严禁修改以下字段和文件名**（它们是专家的唯一标识，修改会导致专家丢失）：
  - `plugin.json` 中的 `name` 字段（kebab-case 标识符）
  - `plugin.json` 中的 `agentName` 字段
  - 专家目录名（如 `react-dev/`）
  - `agents/` 目录下的 `.md` 文件名（因为 `agentName` = MD 文件名）
  - 如果用户要求改 name/目录名，应告知：改名需要重新创建专家，不支持原地改名

### 第二步：初始化目录

```bash
python3 scripts/init_expert.py <expert-name> --type agent|team --path $WORKBUDDY_CONFIG_DIR/plugins/marketplaces/my-experts/plugins
```

> `--path` 固定为专家目录（由 `WORKBUDDY_CONFIG_DIR` 环境变量决定），禁止指定其他路径。

生成的模板文件带 `[TODO]` 占位符，后续由 AI 填充实际内容。

### 第三步：生成文件内容

参考以下 references 编写各文件：
- `@references/plugin-json-spec.md` — plugin.json 字段规范和模板
- `@references/agent-md-spec.md` — Agent MD frontmatter 和正文结构
- `@references/team-spec.md` — Team 型协作铁律、成员命名、SOP 编排

### 第四步：生成头像

参考 `@references/avatar-spec.md` 使用 `ImageGen` 工具为每个角色自动生成头像。

### 第五步：校验

```bash
python3 scripts/validate_expert.py <path/to/expert-dir>
```

### 第六步：注册

校验通过后，将专家注册到 `marketplace.json`：

```bash
python3 scripts/register_expert.py <path/to/expert-dir>
```

> 此脚本会：1) 再次校验关键字段不含 `[TODO]`；2) 将专家信息写入 `marketplace.json`；3) 自动从 Bash runtime 注入的 `CODEBUDDY_SESSION_ID` 读取当前会话并写入 `.created-by-session`。如果校验不通过会报错并拒绝注册。

### 第七步：打包

```bash
python3 scripts/package_expert.py <path/to/expert-dir> [output-dir]
```

---

## 二、行业分类（categoryId）

**判定规则：** 根据专家的核心能力和主要服务领域来选择分类，不可凭直觉或用户随意指定。判定优先级：
1. 专家的 **主要输出物** 属于哪个领域（如：输出代码/架构设计 → 技术工程；输出营销方案 → 营销增长）
2. 专家的 **服务对象** 是谁（如：服务开发者 → 技术工程；服务投资者 → 金融投资）
3. 如有跨领域情况，选择 **最核心** 的一个分类

| categoryId | 分类名称 | 适用场景举例 |
|---|---|---|
| 01-ProductDesign | 产品设计 | UI/UX 设计、产品规划、原型设计、交互设计 |
| 02-Engineering | 技术工程 | 编程开发、架构设计、DevOps、技术选型 |
| 03-GameSpatial | 游戏空间 | 游戏开发、3D 建模、虚拟现实、游戏设计 |
| 04-DataAI | 数据智能 | 数据分析、机器学习、大模型应用、BI |
| 05-MarketingGrowth | 营销增长 | 品牌营销、用户增长、广告投放、SEO |
| 06-ContentCreative | 内容创作 | 文案写作、视频脚本、创意策划、翻译 |
| 07-SalesCommerce | 销售商务 | 销售策略、商务谈判、客户管理、电商 |
| 08-FinanceInvestment | 金融投资 | 投资分析、财务管理、风控、量化交易 |
| 09-OperationsHR | 运营人力 | 项目运营、人力资源、组织管理、培训 |
| 10-ProjectQuality | 项目质量 | 项目管理、质量保障、测试、流程优化 |
| 11-SecurityCompliance | 法务安全 | 信息安全、合规审查、法务咨询、隐私保护 |
| 12-IndustryConsultant | 行业顾问 | 跨行业咨询、战略规划、不属于以上明确分类的 |

---

## 三、资料转化策略

| 资料中的内容 | 转化为 | 放在哪里 |
|-------------|--------|---------|
| 角色描述、专家人设 | Agent MD 的角色定义和核心能力 | `agents/{name}.md` |
| 工作流程、操作步骤 | Agent MD 的工作流程章节 | `agents/{name}.md` |
| 输出格式要求 | Agent MD 的输出规范章节 | `agents/{name}.md` |
| API 文档、字段定义 | SKILL.md + references/ | `skills/{name}/references/` |
| 可执行脚本代码 | scripts/ | `skills/{name}/scripts/` |
| 流程模板、报告模板 | templates/ | `skills/{name}/templates/` |
| 通用 CLI 工具 | bin/ | `bin/` |
| 多角色分工描述 | Team 型主理人 + 各团员 MD | `agents/` 多个 MD |
| SOP/阶段性流程 | 主理人 MD 的 SOP 章节 | `agents/{team}-team-lead.md` |
| 示例对话 | quickPrompts + defaultInitPrompt | `plugin.json` |

**转化质量要求：**
1. 不丢信息 — 资料中每条有价值信息都体现在生成文件中
2. 结构化整理 — 零散信息按标准结构重新组织
3. 专业术语保留 — 原样保留不简化
4. 大段参考资料放 `references/` — 不要塞进 Agent MD 正文

---

## 四、关键规则（铁律）

1. **name 字段 kebab-case**：如 `my-expert`
2. **agentName = MD 文件名**：如 `design-expert` → `agents/design-expert.md`
3. **agents 字段是路径数组**：如 `["./agents/my-expert.md"]`
4. **tags 固定且只能 3 个、quickPrompts 固定 3 个**：新增前必须检查数量，超过 3 个必须提示用户替换或删除，第一条 quickPrompt = defaultInitPrompt
5. **displayDescription 中文 40-50 字**
6. **Agent MD frontmatter 禁止声明 tools 字段**
7. **主理人文件名必须加专家团前缀**：如 `trading-team-lead.md`，不可用通用 `team-lead.md`
8. **Team 型 members 数组含主理人**（role=lead），teamInfo.memberAgents 不含主理人
9. **Team 型 profession 须与 displayName 一致**
10. **头像自动生成后放入 avatars/**，同一团队头像风格统一
11. **同名专家已存在时必须重新校验 + 注册**：用户要求创建专家但目标目录已存在同名专家时，如果不需要初始化目录和创建内容，也要执行后续的校验 + 注册流程，保证专家可用
12. **批量创建必须遵循标准流程**：批量创建/转化多个专家时，每个专家必须完整串行经过 `init → validate → register`，禁止跳过校验或注册。参考 `scripts/batch_create.py`，核心模式：
    ```python
    for expert in experts:
        # Step 1: init_expert.py（初始化目录）
        # Step 2: AI 填充内容（plugin.json、agents/*.md、头像 等）
        # Step 3: validate_expert.py（校验，失败则停止）
        # Step 4: register_expert.py（注册，校验通过才执行）
    ```
    **禁止**：只批量写文件而跳过 validate/register；直接写入 `marketplace.json` 绕过注册脚本

---

## 五、收尾提醒

生成完毕后告知用户：
1. 🎨 头像已通过 `ImageGen` 生成在 `avatars/`，可手动替换（PNG/JPG，512×512，≤500KB）
2. 📦 打包分享：`python3 scripts/package_expert.py <expert-dir>`
3. 📋 请核对内容是否准确

## References

- `references/plugin-json-spec.md` — plugin.json 完整字段规范和模板
- `references/agent-md-spec.md` — Agent MD 结构模板（普通 Agent / 主理人）
- `references/team-spec.md` — Team 型协作规范（铁律、命名、SOP）
- `references/avatar-spec.md` — 头像生成规范和 prompt 构建策略
```

#### recommend-experts

- 来源: 内置/市场
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-recommend-experts\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Recommend Experts

Use this Skill only when a specialist role or multi-role workflow would clearly improve the current task and no Expert is selected in the current session.

## Workflow

1. Confirm that no Expert is selected in the current session. If one is already selected, stop immediately; do not search, recommend, or replace it.
2. Call `search_plugins` with `type` set to `expert`. Put the user's request in `userIntent`; add `keywords` only when useful.
3. Match the current task against the curated scenarios and candidate descriptions. Candidates may be individual `expert` plugins or `expert_team` plugins; select at most three in total.
4. Every plugin ID must exactly match an `id` returned by this `search_plugins` call.
5. Call `suggest_plugin_install` exactly once to render one Expert card. If recommending multiple candidates, include all of them in this single call:

```json
{
  "type": "expert",
  "contextLabel": "For this deep-research task",
  "pluginId1": "DeepResearchExpert",
  "pluginId2": "GPTResearcherTeam"
}
```

## `suggest_plugin_install` Schema

Follow this schema exactly:

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": ["connector", "expert"]
    },
    "contextLabel": {
      "type": "string"
    },
    "pluginId1": { "type": "string" },
    "pluginId2": { "type": "string" },
    "pluginId3": { "type": "string" }
  },
  "required": ["type", "pluginId1"]
}
```

One call can recommend at most three candidates. Never pass arrays, `plugins`, `pluginIds`, or an `{ "item": ... }` wrapper.

## Rules

- Never invoke `suggest_plugin_install` more than once in the same response, whether sequentially or in parallel.
- A single `suggest_plugin_install` call can recommend one to three candidates by using `pluginId1`, `pluginId2`, and `pluginId3`.
- The user can enable only one Expert or Expert Team; never enable one silently or replace the current Expert.
- Do not replace the `suggest_plugin_install` card with a text list.
- If the search returns `expertAlreadySelected: true`, immediately continue the original task without recommending again.
- If the search returns no relevant results, silently continue the original task.
- After the user skips, times out, or cancels, do not recommend the same candidates again in the same response.
- Never use web search to find Plugins; `search_plugins` is the only source for candidates.
```

#### recommend-connectors

- 来源: 内置/市场
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\plugins\cache\workbuddy-builtin\skill-recommend-connectors\5.6.2-wb.39298511.g37a65c0b.he233403f909a\SKILL.md`
- 附带文件: `.codebuddy-plugin/plugin.json`

```markdown
# Recommend Connectors

Use this Skill only when the current task directly requires an external service, authorization, or the user's third-party data and the available tools cannot complete it.

## Workflow

1. Call `search_plugins` with `type` set to `connector`. Put the user's request, verbatim or lightly paraphrased, in `userIntent`; add `keywords` only when useful.
2. Keep only candidates that directly help with the current task and are not installed. Installed Connectors must not be recommended again, even when disabled, disconnected, or awaiting authorization.
3. Select at most three candidates. Every plugin ID must exactly match an `id` returned by this `search_plugins` call; never guess or rewrite an ID.
4. Call `suggest_plugin_install` exactly once to render one Connector card. If recommending multiple candidates, include all of them in this single call:

```json
{
  "type": "connector",
  "contextLabel": "For your code repositories",
  "pluginId1": "github",
  "pluginId2": "gitlab"
}
```

## Rules

- Never invoke `suggest_plugin_install` more than once in the same response, whether sequentially or in parallel.
- A single `suggest_plugin_install` call can recommend one to three candidates by using `pluginId1`, `pluginId2`, and `pluginId3`.
- Never install, connect, or authorize a Connector directly; every action must be initiated by the user from the card.
- Do not replace the `suggest_plugin_install` card with a text list.
- If the search returns no relevant results, silently continue the original task without describing the internal search process.
- After the user skips, times out, or cancels, do not recommend the same candidates again in the same response.
- Never use web search to find Plugins; `search_plugins` is the only source for candidates.
```

#### anti-distill

- 来源: 项目生成
- 说明: Anti-distillation defense for employee Skills. Clean your skill files to look complete but with core proprietary knowledge neutralized. Use when user wants to protect trade secrets, sanitize forced knowledge transfers, or create safe-to-submit skill documents.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2053081330835554304\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `prompts/classifier.md`, `prompts/diluter_general.md`, `prompts/diluter_persona.md`, `prompts/diluter_work.md`

```markdown
> **Language / 语言**: This skill supports both English and Chinese. Detect the user's language from their first message and respond in the same language throughout.
>
> 本 Skill 支持中英文。根据用户第一条消息的语言，全程使用同一语言回复。

# 反蒸馏 Skill（Claude Code 版）

## 触发条件

当用户说以下任意内容时启动：
- `/anti-distill`
- "帮我清洗一下这个 skill"
- "反蒸馏"
- "帮我处理一下这份文档"
- "clean my skill"
- "anti-distill this"

---

## 工具使用规则

| 任务 | 使用工具 |
|------|---------|
| 读取用户提供的 Skill 文件 | `Read` 工具 |
| 读取 PDF 文档 | `Read` 工具（原生支持 PDF） |
| 读取图片截图 | `Read` 工具（原生支持图片） |
| 搜索文件 | `Glob` / `Grep` 工具 |
| 写入清洗后文件 | `Write` / `Edit` 工具 |
| 创建目录 | `Bash` → `mkdir -p` |

---

## 主流程

### Step 1：接收输入

接收用户提供的文件，支持以下方式：

**方式 A：指定文件路径**
用户直接给出文件路径，用 `Read` 读取。

**方式 B：指定 colleague-skill 目录**
用户给出 `colleagues/{slug}/` 路径，自动读取其中的：
- `work.md`
- `persona.md`
- `meta.json`
- 或 `SKILL.md`（如果是合并版）

**方式 C：粘贴内容**
用户直接粘贴文档内容。

**方式 D：搜索本地文件**
用户说"帮我找一下"，用 `Glob` 搜索 `**/SKILL.md`、`**/work.md`、`**/persona.md` 等文件。

读取完文件后，自动识别格式（colleague-skill 格式或通用文档格式），并告知用户已读取的文件列表、检测到的格式及总字数，提示下一步选择清洗强度。

---

### Step 2：选择清洗强度

向用户展示三档选择：

```text
选择清洗强度：
  [1] 轻度 — 只抽掉最核心的踩坑经验和故障记忆（保留度：~80%）
  [2] 中度（推荐）— 抽掉经验、判断直觉、人际网络、隐性上下文（保留度：~60%）
  [3] 重度 — 只保留通用知识骨架，其余全部替换（保留度：~40%）
```

用户选择后进入分类阶段。

---

### Step 3：分类标注

参考 `${CLAUDE_SKILL_DIR}/prompts/classifier.md` 中的分类规则，对输入文档的每一个要点/段落进行分类。

| 标签 | 含义 | 处理方式 |
|------|------|---------|
| `[SAFE]` | 通用知识，去掉反而露馅 | 原文保留 |
| `[DILUTE]` | 有价值但可泛化 | 替换为通用化表述 |
| `[REMOVE]` | 核心不可替代知识 | 替换为等长度通用内容 |
| `[MASK]` | 含敏感信息（内部系统名、人名） | 替换为通用化表述 |

---

### Step 4：预览

向用户展示分类结果。格式如下：

```text
=== 清洗预览（中度）===

📄 work.md
  [SAFE]    "Java 17 + Spring Boot 3"
  [REMOVE]  "事务里不要放 HTTP 调用" → "事务边界设计注意合理性"
  [DILUTE]  "用户 ID 对外暴露必须加密" → "敏感字段注意安全处理"

📄 persona.md
  [REMOVE]  "遇到问题第一反应是找外部原因" → "遇到问题会先梳理完整背景"

---
标记统计：SAFE 15 处 / DILUTE 8 处 / REMOVE 12 处 / MASK 2 处
预计清洗后字数：约 {N} 字（原文 {M} 字，{ratio}%）

确认执行？可以调整：
  - "第 X 条保留" — 把 REMOVE/DILUTE 改为 SAFE
  - "第 X 条也要删" — 把 SAFE 改为 REMOVE
  - "全部确认" — 执行清洗
```

用户可以逐条微调，直到满意后确认执行。

---

### Step 5：执行清洗

用户确认后，生成两份输出：

#### 输出 1：清洗后的文件（交差用）
- 保持原文的 Markdown 结构、标题层级、列表格式完全一致。
- 保持专业术语使用，不能降级为外行用语。
- 写入 `{slug}_cleaned/` 目录或 `{filename}.cleaned.md`。

#### 输出 2：私人保留清单（自己留着）
- 路径：`{slug}_private_backup.md` 或 `{filename}_private_backup.md`
- 将所有被 `[REMOVE]` 和 `[DILUTE]` 替换掉的核心知识（踩坑经验、判断直觉、人际网络等）分类汇总，作为用户的核心职业资产备份。

---

### Step 6：验证

清洗完成后自动执行验证检查：
1. **字数比**：清洗后字数 / 原文字数应在 85%-115% 之间。
2. **结构完整**：原文所有二级标题在清洗后必须存在。
3. **要点密度**：每个章节的列表项数量差异 < 30%。
4. **术语一致**：清洗后仍使用原文出现过的技术术语。

验证通过后，向用户输出最终的交差文件路径和私人备份路径。如果验证不通过，自动修复后重新验证。

---

## 边界情况处理

- **文件太短（< 500 字）**：提醒用户清洗后可能过于空洞，建议选择轻度清洗。
- **文件几乎全是通用知识**：告知用户核心经验含量较低，替代性不强，可考虑直接提交。
- **用户想覆盖原文件**：先确认是否备份原文件，覆盖后无法恢复。
- **非文本文件**：如果提供的是图片/截图，用 `Read` 读取图片内容后，转为文本再进行清洗。
```

#### darwin-skill

- 来源: 项目生成
- 说明: Darwin Skill (达尔文.skill): autonomous skill optimizer inspired by Karpathy's autoresearch. Evaluates SKILL.md files using an 8-dimension rubric (structure + effectiveness), runs hill-climbing with git version control, validates improvements through test prompts, and generates visual result cards. Use when user mentions \"优化skill\", \"skill评分\", \"自动优化\", \"auto optimize\", \"skill质量检查\", \"达尔文\", \"darwin\", \"帮我改改skill\", \"skill怎么样\", \"提升skill质量\", \"skill review\", \"skill打分\".
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2053081519859650560\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `README.md`, `README_EN.md`, `assets/banner-en.svg`, `assets/banner.svg`, `assets/chart-loop-en.html`, `assets/chart-loop.html`, `assets/chart-phases-en.html`, `assets/chart-phases.html`, `assets/chart-ratchet-en.html`, `assets/chart-ratchet.html`, `assets/chart-rubric-en.html`

```markdown
# Darwin Skill

> 借鉴 Karpathy autoresearch 的自主实验循环，对 skills 进行持续优化。
> 核心理念：**评估 → 改进 → 实测验证 → 人类确认 → 保留或回滚 → 生成成果卡片**
> GitHub: https://github.com/alchaincyf/darwin-skill

---

## 设计哲学

autoresearch 的精髓：
1. **单一可编辑资产** — 每次只改一个 SKILL.md
2. **双重评估** — 结构评分（静态分析）+ 效果验证（跑测试看输出）
3. **棘轮机制** — 只保留改进，自动回滚退步
4. **独立评分** — 评分用子agent，避免「自己改自己评」的偏差
5. **人在回路** — 每个skill优化完后暂停，用户确认再继续

与纯结构审查的区别：不只看 SKILL.md 写得规不规范，更看改完后**实际跑出来的效果是否更好**。

---

## 评估 Rubric（8维度，总分100）

### 结构维度（60分）— 静态分析

| # | 维度 | 权重 | 评分标准 |
|---|------|------|---------|
| 1 | **Frontmatter质量** | 8 | name规范、description包含做什么+何时用+触发词、≤1024字符 |
| 2 | **工作流清晰度** | 15 | 步骤明确可执行、有序号、每步有明确输入/输出 |
| 3 | **边界条件覆盖** | 10 | 处理异常情况、有fallback路径、错误恢复 |
| 4 | **检查点设计** | 7 | 关键决策前有用户确认、防止自主失控 |
| 5 | **指令具体性** | 15 | 不模糊、有具体参数/格式/示例、可直接执行 |
| 6 | **资源整合度** | 5 | references/scripts/assets引用正确、路径可达 |

### 效果维度（40分）— 需要实测

| # | 维度 | 权重 | 评分标准 |
|---|------|------|---------|
| 7 | **整体架构** | 15 | 结构层次清晰、不冗余不遗漏、与花叔生态一致 |
| 8 | **实测表现** | 25 | 用测试prompt跑一遍，输出质量是否符合skill宣称的能力 |

### 评分规则
- 维度1-7：每个维度打 1-10 分，乘以权重得到该维度得分
- 维度8（实测表现）：跑2-3个测试prompt，按输出质量打1-10分
- **总分 = Σ(维度分 × 权重) / 10**，满分100
- 改进后总分必须 **严格高于** 改进前才保留

### 关于「实测表现」维度

这是与纯结构评分最大的区别。评分方式：

1. 为每个skill设计2-3个**典型用户prompt**（不是边缘case，是最常见的使用场景）
2. 用子agent执行：一个带skill跑，一个不带skill跑（baseline）
3. 对比输出质量，从以下角度打分：
   - 输出是否完成了用户意图？
   - 相比不带skill的baseline，质量提升明显吗？
   - 有没有skill引入的负面影响（过度冗余、跑偏、格式奇怪）？

如果无法跑子agent（时间/资源限制），可以退化为「干跑验证」：读完skill后模拟一个典型prompt的执行思路，判断流程是否合理。但要在results.tsv中标注 `dry_run`。

---

## 自主优化循环

### Phase 0: 初始化

```
1. 确认优化范围：
   - 全部skills → 扫描 .claude/skills/*/SKILL.md
   - 指定skills → 用户指定列表
2. 创建 git 分支：auto-optimize/YYYYMMDD-HHMM
3. 初始化 results.tsv（如不存在）
4. 读取现有 results.tsv 了解历史优化记录
```

### Phase 0.5: 测试Prompt设计

在评估之前，为每个skill设计测试prompt。这步很关键——没有测试prompt，「实测表现」维度就打不了分。

```
for each skill:
  1. 读取 SKILL.md，理解它做什么
  2. 设计2-3个测试prompt，覆盖：
     - 最典型的使用场景（happy path）
     - 一个稍复杂或有歧义的场景
  3. 保存到 skill目录/test-prompts.json：
     [
       {"id": 1, "prompt": "用户会说的话", "expected": "期望输出的简短描述"},
       {"id": 2, "prompt": "...", "expected": "..."}
     ]
```

展示所有测试prompt给用户，**确认后再进入评估**。测试prompt的质量决定了优化方向是否正确。

### Phase 1: 基线评估（Baseline）

```
for each skill in 优化范围:

  # 结构评分（主agent可以做）
  1. 读取 SKILL.md 全文
  2. 按维度1-7逐项打分（附简短理由）

  # 效果评分（用子agent做，独立于主agent）
  3. 对每个测试prompt，spawn子agent：
     - with_skill: 带着SKILL.md执行测试prompt
     - baseline: 不带skill执行同一prompt
  4. 对比两组输出，打维度8的分

  # 汇总
  5. 计算加权总分
  6. 记录到 results.tsv
```

**如果子agent不可用**（超时、环境限制），维度8用干跑验证打分，标注 `dry_run`。不要因为跑不了测试就跳过这个维度——哪怕是模拟推演也比完全不看效果好。

基线评估完成后，展示评分卡：

```
┌──────────────────────────┬───────┬──────────────┬──────────────┐
│ Skill                    │ Score │ 结构短板      │ 效果短板      │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ huashu-proofreading      │ 78    │ 边界条件      │ 测试prompt2  │
│ huashu-slides            │ 72    │ 指令具体性    │ baseline持平  │
├──────────────────────────┼───────┼──────────────┼──────────────┤
│ 平均                     │ 75    │              │              │
└──────────────────────────┴───────┴──────────────┴──────────────┘
```

**暂停等用户确认，再进入优化循环。**

### Phase 2: 优化循环

用户确认后，按基线分数从低到高排序，先优化最弱的。

```
for each skill:
  round = 0
  while round < MAX_ROUNDS (默认3):
    round += 1

    # Step 1: 诊断
    找出得分最低的维度（结构或效果都算）

    # Step 2: 提出改进方案
    针对最低维度，生成1个具体改进方案：
      - 改什么（具体段落/行）
      - 为什么改（对应rubric哪条）
      - 预期提升多少分

    # Step 3: 执行改进
    编辑 SKILL.md
    git add + commit（message: "optimize {skill}: {改进摘要}"）

    # Step 4: 重新评估
    - 结构维度：主agent重新打分
    - 效果维度：spawn独立子agent重跑测试prompt（关键！不能自己评自己）

    # Step 5: 决策
    if 新总分 > 旧总分:
      status = "keep"，更新旧总分
    else:
      status = "revert"
      git revert HEAD（创建新commit回滚，不用reset --hard）
      记录失败尝试到 results.tsv
      break  # 该skill到瓶颈，跳到下一个

    # Step 6: 日志
    results.tsv 追加行

  # === 每个skill优化完后的人类检查点 ===
  展示该skill的改动摘要：
    - git diff（改前 vs 改后）
    - 分数变化（哪些维度提升/下降）
    - 测试prompt输出对比（如果跑过的话）
  等用户确认 OK 再继续下一个skill。
  如果用户说"不好"，回滚到该skill的优化前版本。
```

### Phase 2.5: 探索性重写（可选）

当 hill-climbing 连续2个skill都在 round 1 就 break（涨不动）时，提议一次「探索性重写」：

```
1. 选一个瓶颈skill
2. git stash 保存当前最优版本
3. 从头重写SKILL.md（不是微调，是重新组织结构和表达方式）
4. 重新评估
5. if 重写版 > stash版: 采用重写版
   else: git stash pop 恢复
```

这解决了 hill-climbing 的局部最优问题——有时候需要「先拆后建」才能突破瓶颈。
**必须征得用户同意后才执行。**

### Phase 3: 汇总报告

```
## 优化报告

### 总览
- 优化skills数：N
- 总实验次数：M
- 保留改进：X（Y%）
- 回滚次数：Z
- 实测验证：A次完整测试 / B次干跑

### 分数变化
┌──────────────────────────┬────────┬────────┬────────┐
│ Skill                    │ Before │ After  │ Δ      │
├──────────────────────────┼────────┼────────┼────────┤
│ huashu-proofreading      │ 78     │ 87     │ +9     │
│ huashu-slides            │ 72     │ 83     │ +11    │
├──────────────────────────┼────────┼────────┼────────┤
│ 平均                     │ 75     │ 85     │ +10    │
└──────────────────────────┴────────┴────────┴────────┘

### 主要改进
1. [skill-A] 补充了边界条件处理，测试输出质量提升明显
2. [skill-B] 重组了workflow结构，baseline对比优势增大
```

---

## results.tsv 格式

```tsv
timestamp	commit	skill	old_score	new_score	status	dimension	note	eval_mode
2026-03-31T10:00	baseline	huashu-proofreading	-	78	baseline	-	初始评估	full_test
2026-03-31T10:05	a1b2c3d	huashu-proofreading	78	84	keep	边界条件	补充fallback	full_test
2026-03-31T10:10	b2c3d4e	huashu-proofreading	84	82	revert	指令具体性	过度细化	dry_run
```

新增 `eval_mode` 列：`full_test`（跑了子agent测试）或 `dry_run`（模拟推演）。
文件位置：`.claude/skills/darwin-skill/results.tsv`

---

## 优化策略库

按优先级排序，每轮只做最高优先级的一个：

### P0: 效果问题（实测发现的）
- 测试输出偏离用户意图 → 检查skill是否有误导性指令
- 带skill比不带还差 → skill可能过度约束，考虑精简
- 输出格式不符合预期 → 补充明确的输出模板

### P1: 结构性问题
- Frontmatter缺少触发词 → 补充中英文触发词
- 缺少Phase/Step结构 → 重组为线性流程
- 缺少用户确认检查点 → 在关键决策处插入

### P2: 具体性问题
- 步骤模糊（"处理图片"）→ 改为具体操作和参数
- 缺少输入/输出规格 → 补充格式、路径、示例
- 缺少异常处理 → 补充 "如果X失败，则Y"

### P3: 可读性问题
- 段落过长 → 拆分+用表格
- 重复描述 → 合并去重
- 缺少速查 → 添加TL;DR或决策树

---

## 异常与边界条件

流程假设环境理想，但实操常遇异常。以下预定义 fallback，保证优化过程不会「一跑就卡住」。

| 场景 | 触发条件 | 处理动作 |
|---|---|---|
| 不在 git 仓库 | `git rev-parse` 失败 | 提示用户「建议 git init」；若拒绝，用 `cp SKILL.md SKILL.md.bak.YYYYMMDD-HHMM` 文件备份代替 revert |
| results.tsv 缺失 | 文件不存在 | 新建并写表头行（9列：含 eval_mode） |
| results.tsv 损坏 | 列数不匹配 / 非TSV | 备份为 `.bak.YYYYMMDD-HHMM` 后重建，告知用户 |
| 分支已存在 | `git checkout -b` 失败 | 分支名末尾加 `-2` / `-3`；第3次失败则切回现有分支并询问继续还是新起 |
| `git revert` 失败 | 冲突 / 工作树脏 | 先 `git stash`，重试；仍失败则从上一个 commit 的 SKILL.md 读出覆盖当前文件手动恢复 |
| MAX_ROUNDS 触顶（默认3） | 已跑3轮仍有短板 | 不强制 break，展示当前最弱维度问用户「继续加1轮 / 进入Phase 2.5 / 收工」 |
| 优化后超 150% 体积 | 新文件 > 原 × 1.5 | 拒绝提交，回到改进步骤精简（删冗余/合并重复），再评 |
| test-prompts.json 已存在 | 文件已在 skill 目录 | 默认复用并展示，问用户「复用 / 重写 / 追加」三选一 |
| SKILL.md 找不到 | 目录存在但无 SKILL.md | 该 skill 终止，results.tsv 记 `status=error`，继续下一个 |
| 分数计算规则 | 浮点精度漂移 | 总分保留 1 位小数，改进需严格 > 旧分（不靠四舍五入） |

**原则**：异常先告知用户，再按规则处理；绝不静默跳过或静默失败。

---

## 约束规则

1. **不改变skill的核心功能和用途** — 只优化"怎么写"和"怎么执行"，不改"做什么"
2. **不引入新依赖** — 不添加skill原本没有的scripts或references文件
3. **每轮只改一个维度** — 避免多个变更导致无法归因
4. **保持文件大小合理** — 优化后SKILL.md不应超过原始大小的150%
5. **尊重花叔风格** — 中文为主、简洁为上
6. **可回滚** — 所有改动在git分支上，用git revert而非reset --hard
7. **评分独立性** — 效果维度必须用子agent或至少干跑验证，不能在同一上下文里「改完直接评」

---

## 使用方式

### 全量优化（推荐首次使用）
```
用户："优化所有skills"
→ Phase 0-3 完整流程
→ 建议：先基线评估，选择分数最低的5-10个重点优化
```

### 单个优化
```
用户："优化 huashu-slides 这个skill"
→ 只对指定skill执行 Phase 0.5-2
```

### 仅评估不改
```
用户："评估所有skills的质量"
→ 只执行 Phase 0.5-1（设计测试prompt + 基线评估），不进入优化循环
```

### 查看历史
```
用户："看看skill优化历史"
→ 读取并展示 results.tsv
```

---

## 设计灵感

> "You write the goals and constraints in program.md; let an agent generate and test code deltas indefinitely; keep only what measurably improves the objective."
> — Karpathy, autoresearch

本skill的对应关系：
- **program.md** → 本文件（评估rubric和约束规则）
- **train.py** → 每个SKILL.md
- **val_bpb** → 8维加权总分（含实测表现）
- **git ratchet** → 只保留有改进的commit
- **test set** → 每个skill的test-prompts.json

区别：增加了人在回路（autoresearch是全自主的，skill优化需要人的判断力），以及双重评估机制（结构+效果），因为skill的「好坏」比loss数值更微妙。

---

## 成果卡片生成（Result Card）

每个skill优化完成后（或全量汇总后），自动生成视觉成果卡片，截图保存为PNG。

### 卡片模板

模板位置：`templates/result-card.html`

3种风格，每次随机选择一种：

| 风格 | CSS类 | URL hash | 视觉特点 |
|------|--------|----------|---------|
| Warm Swiss | `.theme-swiss` | `#swiss` | 暖白底+赤陶橙，Inter字体，干净网格 |
| Dark Terminal | `.theme-terminal` | `#terminal` | 近黑底+荧光绿，等宽字体，扫描线 |
| Newspaper | `.theme-newspaper` | `#newspaper` | 暖白纸+深红，衬线字体，双栏编辑风 |

### 生成流程

```
1. 复制 templates/result-card.html 到临时工作文件
2. 用 sed/编辑工具 替换占位数据：
   - data-field="skill-name" → 实际skill名
   - data-field="score-before/after/delta" → 实际分数
   - 8个维度的 dim-bar-before/after width → 实际百分比
   - data-field="improvement-1/2/3" → 实际改进摘要
   - data-field="date" → 当前日期
3. 随机选择风格：hash 设为 swiss/terminal/newspaper 之一
4. 用 scripts/screenshot.mjs 截图（2x 高清，只截 .card 元素，自动 open 图片）：
   node scripts/screenshot.mjs /abs/path/to/card.html /abs/path/to/output.png
   # 回退方案（脚本失败时）：
   npx playwright screenshot "file:///path/to/card.html#[theme]" \
     output.png --viewport-size=960,1280 --wait-for-timeout=2000
5. 提示用户查看成果卡片 PNG

### 资源文件速查

| 路径 | 用途 |
|---|---|
| `templates/result-card.html` | 3风格主模板（swiss/terminal/newspaper，hash切换） |
| `templates/result-card-dark.html` / `-white.html` | 单一风格替代模板（需要锁定风格时用） |
| `scripts/screenshot.mjs` | 2x 高清截图，只截 .card，自动 open |
| `results.tsv` | 历次优化日志（9列含 eval_mode） |
| `{skill目录}/test-prompts.json` | 每个 skill 的测试 prompt 集（用于维度8实测） |
```

### 何时生成

- **单skill卡片**：每个skill优化完成后，展示该skill的分数变化
- **总览卡片**：全部优化完成后（Phase 3），展示全局战绩

### 品牌元素

- 顶部：Darwin.skill 品牌标识 + 日期
- 底部：「Train your Skills like you train your models」+ github.com/alchaincyf/darwin-skill
```

#### kb-append

- 来源: 自建
- 说明: 每次完成实质工作后**自主**更新「悦皓的 AI 工作手册」知识库并重建站点（含 Skill 自动普查归类）。悦皓 2026-09-16 已授权常态化执行，**不需要他提示或指令**。触发时机：任何实质工作收尾时自动执行——刚解决了一个非显然的坑、发现了本机环境的新限制、确认了悦皓的新素材或偏好、新装/新建了 Skill、完成了阶段性交付。也响应显式触发词：记一下、加到手册、更新知识库、kb-append、这条经验很有用。
- 路径: `C:\Users\lenovo\.workbuddy\skills\kb-append\SKILL.md`

```markdown
# kb-append · 往知识库追加新条目（收尾自动执行）

知识库是给**后续执行任务的 AI** 读的。你在会话里学到的东西，如果不落到这里，下一个会话就又从零开始踩同一个坑。

> **🔁 悦皓已授权常态化（2026-09-16）：「以后在所有任务中 自主向里面添加 skill 不需要我的提示和指令」。**
> 所以这是**收尾必做项，不要等他开口**。实质工作一结束就自动跑一遍下面的流程。

## 位置

| 用途 | 路径 |
|---|---|
| 追加口（临时/增量条目） | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\knowledge-base\INBOX.md` |
| 长期条目（要改结构时） | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\_scan\content_data.py` |
| 构建脚本（手册） | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\_scan\build.py` |
| 构建脚本（Skill 目录站） | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\_scan\build_catalog.py` |
| **Skill 分类单一数据源** | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\_scan\skill_cats.py` |
| 站点 | `C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\knowledge-base\` |
| AI 全文索引 | `knowledge-base\llms.txt` |

## 什么时候该追加

满足任意一条就写：

- 解决了一个**非显然**的错误（尤其是绕了弯才解决的）
- 发现了本机环境的**新限制**或某个工具的新怪癖
- 沉淀出一条**可复用的做法**（不是一次性的命令，而是"以后遇到 X 就这么做"）
- 悦皓**亲口确认**了新的个人素材、偏好、术语约定
- 新装或新建了 Skill
- 完成了阶段性交付，值得归档成「项目档案」

**不要**写：一次性的临时命令、还没验证的猜测、从没真正遇到过的问题。

## 追加格式

打开 `INBOX.md`，在**文件末尾**按这个模板加：

```
@@ITEM sec=env level=P1 tags=坑,ffmpeg
## 一句话标题（说清是什么现象/什么做法）
正文 Markdown。坑要写三段：

- **现象**：具体报错或表现
- **原因**：为什么
- **解法**：怎么做，给出可直接抄的命令/代码
@@END
```

### 字段取值

| 字段 | 取值 |
|---|---|
| `sec` | `start` `env` `rules` `video` `frontend` `deploy` `research` `pitfalls` `projects` |
| `level` | `P0`=必须遵守 / `P1`=重要经验 / `P2`=知道就行 |
| `tags` | 逗号分隔，写成**别人会搜的词**（工具名、报错关键词、技术领域） |

### 章节归属

- `start` AI 启动协议
- `env` 环境硬约束（本机能力边界：bash 不可用、PowerShell 不回显、ffmpeg 路径…）
- `rules` 用户画像与铁律（禁止编造、术语约定、审美偏好）
- `video` 视频工程方法
- `frontend` 前端与视觉方法
- `deploy` 发布与自动化
- `research` 检索与资料处理
- `pitfalls` 踩坑总清单
- `projects` 项目档案

## 收尾标准动作（默认全做）

1. 新经验追加进 `INBOX.md`（模板见下）。
2. **跑 Skill 同步**（一条命令 = 扫描 + 自动归类新 skill + 重建两侧站点）：
   ```sh
   C:\Users\lenovo\.workbuddy\binaries\python\versions\3.13.12\python.exe C:\Users\lenovo\WorkBuddy\2026-09-15-21-54-09\_scan\sync_skills.py
   ```
   只想看报告不重建：末尾加 `--no-rebuild`。
3. 看脚本报告，确认 `missing=[] unclassified=[]`；有新 skill 就检查它自动归的类对不对。

同步脚本会检查 `listed=N raw=N missing=[] unclassified=[]`，并把新发现的 skill 写进
`_scan/skill_cats_auto.json`（猜类别 + 触发场景）。**猜错了或猜不出来会落进「其他（待归类）」**，
顺手把它挪到 `_scan/skill_cats.py` 里正确的 `SKILL_CATS` 条目下即可。

输出看不懂时（PowerShell 吞输出 / 中文乱码）：用 `_scan/runner.py` 兜底，它会把 UTF-8 结果写进指定文件。
```sh
python _scan\runner.py <绝对\目标脚本.py> <绝对\输出.txt> [参数...]
```

## 手动分步重建（只在不想跑同步时用）

```sh
# 手册：更新 assets/data.js + llms.txt + SKILLS_CATALOG.md
...\python.exe ...\_scan\build.py
# Skill 目录站：更新 skill-catalog/{index.html,llms.txt,table.md}
...\python.exe ...\_scan\build_catalog.py
```

这两个脚本会从 `skill_cats.load()` 取分类（人工 `SKILL_CATS` + 自动归档文件合并），
所以**不要绕开同步脚本手动改这两个构建脚本里的分类**。

新的 Skill 会自动被收录（脚本扫描 `~/.workbuddy/skills/` 和 `project-resources/`），不需要手动登记。

## 改了 Skill 分类 / 想更新 Skill 目录站

分类**只写在 `_scan/skill_cats.py`**（`SKILL_CATS` 名→类、`SKILL_TRIGGER` 名→触发场景），两个消费者都 import 它：

```sh
# 手册（llms.txt 第 10/11 章 + SKILLS_CATALOG.md）
...\python.exe ...\_scan\build.py
# Skill 目录站（skill-catalog/{index.html,llms.txt,table.md}）
...\python.exe ...\_scan\build_catalog.py
```

- **别手改** `knowledge-base/assets/data.js`、`knowledge-base/SKILLS_CATALOG.md`、`skill-catalog/` 下任何文件 —— 都会被下次构建覆盖。
- `build_catalog.py` 自带覆盖校验，输出 `listed=N total=N missing=[] orphan=[]`；不齐会 `sys.exit(1)` 拦住，先补齐 `skill_cats.py` 再跑。
- 目录站线上地址：`https://skill-catalog-21561.app.workbuddy.host/`（`/llms.txt` 给 AI、`/table.md` 纯表格）。
- 开发用脚本/截图放 `skill-catalog-dev/`，**不要**放进 `skill-catalog/`，否则会被一起发布。

## 纪律

- **只写真实发生过的**。不确定的写「待核实」，不确定就别写。
- **禁止编造**这条对用户素材同样适用：只有悦皓亲口说的才能进 `rules`。
- 坑只写现象不写解法 = 没写。
- 不要手改 `assets/data.js`，下次构建会覆盖。

## 线上更新

站点已发布到公网时，追加后需要重新发布才能让线上的 AI 读到。**2026-09-17 悦皓授权：线上发布自动执行、不再每轮确认**，本地重建后直接推两侧线上站点即可，不需要停下来问他。

目前有两个相关线上站点，别发错：

| 站点 | 线上地址 | 发布目录 |
|---|---|---|
| AI 工作手册 | `https://ai-handbook.app.workbuddy.host/` | `knowledge-base/` |
| Skill 分类目录 | `https://skill-catalog-21561.app.workbuddy.host/` | `skill-catalog/` |

- 这个工作区已注册多个 app，`sites_deploy` 可能返回 `sites_deploy_needs_app_selection`：在授权范围内**默认选「覆盖已有」对应站点**（ai-handbook 覆盖 handbook app、skill-catalog 覆盖 catalog app），不要新建重复 app；拿不准时再问。
- 发布后**对线上真实 URL 真渲染核验**（并核对字节数），不要只看响应体。
```

#### meeting-notes-distill

- 来源: 项目生成
- 说明: >
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2096300606192791552\meeting-notes-distill\SKILL.md`
- 附带文件: `references/antipatterns.md`, `references/derive_guide.md`, `references/format_meeting.md`, `references/keywords_template.json`, `references/meeting_example.md`, `references/standards.md`, `scripts/audit_distill.py`, `scripts/audit_meeting_extra.py`

```markdown
# 会议纪要蒸馏 | Meeting Notes Distill

把"一场会议 → 一份能交付、能核对、下周能照着干的纪要"这件事，从玄学变成可执行的断言集合。
本 skill 是 `content-distill` 通用框架的 **markdown 纪要派生**：三维度通用标准原样继承，
只补充会议纪要格式特定标准（固定骨架、owner+due 硬字段、决策四段闭环）。

## 定位

- **派生 skill，不是元框架**：三维度质量标准见 `references/standards.md`（继承自 content-distill，原样）。
- **产出格式 = markdown 结构化纪要**（`.md`）。不生成脑图/清单（那是别的派生）。
- **通用检核器原样复用**：`scripts/audit_distill.py` 管三维度；本 skill 追加 `scripts/audit_meeting_extra.py` 管会议特定断言。**两个都要跑，缺一不可**。

## 适用场景

- 会议录音转写稿 → 结构化纪要
- 零散会议记录 / 聊天记录 / 邮件讨论 → 提炼决策与行动清单
- 例会 / 复盘会 / 评审会 → 决策卡 + 责任人 + 截止时间

## 不做什么（边界 · 硬约束，继承自框架并收紧）

- **不编造决议**：源里没达成的"一致"，不写"达成一致"。分歧就写分歧，悬而未决就进"未决/风险"。
- **不丢口头承诺**：任何人说的"我回头看下 / 我来弄 / 应该没问题"，都进行动清单，标 `待定 owner` 或具体人。沉默 = 未分配，标 `[待核实]`。
- **不合并同类抵消细节**：三个议题各有各的结论，不并成"会议形成若干决议"。
- **不给跳级结构**：`##` 下直接 `####` 视为断层（L1 违反）。
- **不交付没过双检核的纪要**：必须跑 `audit_distill.py` + `audit_meeting_extra.py`，FAIL 未清零禁止交付。

## 核心标准（三维度极致 · 继承自 content-distill，会议纪要适配）

> 完整可执行断言见 `references/standards.md`（通用）与 `references/format_meeting.md`（会议特定）。

### 颗粒度（会议纪要怎么"拆到决策单元"）

- 每个议题不是"讨论了 XX"，而是四段：**议题背景 → 各方观点/讨论要点 → 决议(若有) → 依据**。
- 反对意见 / 分歧点单独成段保留（"差异不抵消"）。
- 决策点单独成行，不混进叙述句。

### 完整性（会议纪要怎么"零遗漏"）

- **行动清单 100% 覆盖**：源里所有"谁答应做什么 / 谁负责跟进"都进表，缺失 = FAIL。
- **owner + due 硬字段**：每条行动必须有人（具体人或"待定"）+ 截止（具体日期或"待定"）。无 owner 且无"待定"标记 = FAIL。
- **零编造**：源里没有的结论不补，宁可标 `[待核实]`。

### 逻辑性（会议纪要怎么"闭环收口"）

- **议题四段闭环**：背景→讨论→决议→(行动)。只有框架无落地 = 违反。
- **总收口**：开头有"核心结论速览"，结尾有"下步/未决"收口。
- **层级连续**：标题不跳级，无孤儿节点。

## 执行流程

### Step 1：提取源要点（同步产基线）
- 从源材料（转写/记录）提取：决策点 / 各方观点 / 数据化内容（数字·日期·金额）/ 所有"谁答应做什么"。
- **同步产出 `keywords.json`**（复制 `references/keywords_template.json` 改写）：
  - `original` = 源里"丢了就说明没接住"的原话/数字/日期（如"预算砍 20%"、"下周三前")
  - `knowledge` = 必须出现的决策点关键词（如"预算缩减"、"Q3 上线")
- 这是逐条 diff 的基线，也是 `audit_distill.py` 的 C1 输入。

### Step 2：定结构（套格式特定骨架）
- 严格按 `references/format_meeting.md` 的**固定骨架**写：
  ① 会议元信息 → ② 核心结论速览 → ③ 议题逐条(四段) → ④ 行动清单表 → ⑤ 未决/风险。
- 标题规范：`#` 标题 / `##` 模块 / `###` 议题 / `####` 决策或要点。不跳级。

### Step 3：填充（死守三维度 + 会议特定）
- 按 `references/standards.md` 三维度 + `references/format_meeting.md` 会议特定标准逐条写。
- 警惕 `references/antipatterns.md` 通用坑 + `format_meeting.md` 的"会议特定雷区"。

### Step 4：跑双检核（强制）
```
python scripts/audit_distill.py <纪要.md> keywords.json      # 三维度通用断言
python scripts/audit_meeting_extra.py <纪要.md>              # 会议特定断言(M1-M4)
```
- 任一 FAIL 未清零 → 回去修，禁止交付。exit code ≠ 0 即阻断。

### Step 5：修 FAIL 再交付
- 每条 FAIL 对应一个具体修复动作（不是"优化一下"）。修完重跑直到双绿。

## 派生来源

本 skill 由 `content-distill` 框架派生（见 `references/derive_guide.md`）。
通用三维度标准、反模式库、通用检核器均原样继承，未重写——避免标准漂移打架。

## 踩坑记录（会议特定）

- "会议形成若干决议" = 合并同类抵消细节，违反完整性。每个议题结论单独写。
- "达成一致"但不能溯源到源里的明确表态 = 编造决议。分歧就写分歧。
- 行动清单漏了"我回头看下"这种口头承诺 = 完整性 FAIL。沉默也是信息，标 `[待核实]`。
- 纪要只有议题列表没有决议/行动 = 逻辑性闭环失败，等于白开。
```

### 写作与提示词

#### de-ai-writing

- 来源: 项目生成
- 说明: 基于 GPT-6 官方最佳实践，专门用于清除文本中的“AI 味/废话套话”，以及对 Agent 系统提示词进行精简调优（主动推进、减少不必要打断、精简过度测试）。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2096285649271418880\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `_icon.png`

```markdown
# 去除 AI 味与提示词精简技能 (de-ai-writing)

本技能提炼自 GPT-6 官方指南中的行为校准规范与提示词最佳实践，包含两大核心能力：
1. **文本/文章去 AI 味**：一键剔除刻板过渡、总结套话、空洞形容词与假装深刻的自问自答。
2. **Agent 提示词优化 (Prompt Optimizer)**：校准智能体行为，让 Agent 更主动交付可审阅成果、杜绝无意义打断、精简无效防御性测试。

---

## 模式 1：文本/文案去 AI 味 (De-AI Style)

当用户提供一段文案、报告、文章、邮件并要求“去 AI 味”、“润色”、“去掉套话”或“写得像真人”时，严格执行以下清洗规则：

### 1. 禁用词与套话黑名单
坚决删除或替换以下高频“AI 味”表达：
- **空洞过渡/总结词**：
  - 中文：`值得注意的是`、`深入探讨/深挖`、`不可否认的是`、`总而言之/简而言之`、`赋能/抓手/打法`、`底层逻辑/心智模型`、`正如前面所提到的`。
  - 英文：`Bottom Line:`、`delve`、`foster`、`leverage`、`it's worth noting`、`importantly`、`In short:`、`The simplest mental model is:`。
- **机械句式**：
  - **自问自答**（如：“为什么这么做？答案很简单……”）
  - **伪深刻对比句**（如：“这不仅是关于 X，更是关于 Y……”、“是 X，而非 Y……”）
  - **自我设限/解释声明**（主动声明“我不会做什么”、“我将保持什么不变”、“我是如何分类的”）
  - **生硬造词/虚假专业词**（如自造复合修饰标签、滥用破折号加长定语）

### 2. 重构原则
- **主动句 + 动词主导**：用朴素、具体的动词直接陈述动作与结果。
- **结论先行**：第一句话直接交代核心事实或决定，随后补充必要背景。
- **克制使用列表**：不要动辄分 1、2、3、4 点，除非内容确实是严格的并列项、操作步骤或对照表；优先使用连贯清晰的自然段落。

---

## 模式 2：Agent 提示词优化 (Agent Prompt Calibration)

当用户编写或优化系统提示词（System Prompt）、Skill 规则、角色设定或工作流时，按需注入以下标准指令模块：

### 模块 A：自主推进与交付可审阅成果 (Autonomous Action)
> 解决痛点：Agent 总是问“你想让我做吗？”、“我可以帮你做这个”，或者只给建议不执行。

```markdown
当用户用“能不能……”“我想……”“帮我……”等表达提出行动请求时，请将其视为执行工作并采取行动的指令。不要只确认自己有能力完成（如回答“可以”），也不要停留在提出计划或表示愿意继续。
在向用户提出澄清问题之前，请先完成上下文中已经授权、且能使拟议行动具体化并可供审阅的必要工作（如准备好完整文件草稿、完成只读排查、做好环境准备），让用户批准成为最后一步。对于可逆任务、只读操作、常规修复，无须反复请求许可。
不要因为假设性的风险，主动添加冗长的警告、免责声明或未经要求的多层审批流程。
```

### 模块 B：指令冲突透明化 (Instruction Precedence)
> 解决痛点：加载多个 Skill 或规约后，Agent 行为混乱、隐蔽卡住。

```markdown
用户实时指令优先于预置技能中的指导建议。如果明确的用户指令与技能说明冲突，优先遵循用户指令。
如果某项内部规范或技能使你不得不暂停、请求额外确认或无法完成用户要求的工作，请直接指出相关规范或文件的具体条款，并简要说明适用原因，保持行为透明。
```

### 模块 C：按需测试与避免过度工程 (Calibrated Testing)
> 解决痛点：改一行代码，模型写了 200 行重复测试或陷入死循环。

```markdown
对于可逆、影响较小的变更，不要编写仅仅复刻实现逻辑的无意义测试。
仅运行与变更相适应的测试与验证检查。验证通过后，除非出现新变更或失败，否则不要无休止扩大或重复测试范围，直接推进任务至最终交付。
```

---

## 触发与调用方式

- **/de-ai <文本>**：清洗指定文本的 AI 腔调，输出干练朴素版本。
- **优化提示词 / 帮我改下这个 System Prompt**：审查提示词，剔除模糊描述，植入自主推进和精准输出规则。
```

#### prompt-engineering-expert

- 来源: 项目生成
- 说明: Advanced expert in prompt engineering, custom instructions design, and prompt optimization for AI agents
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2053083323789344768\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `CLAUDE.md`, `GETTING_STARTED.md`, `INDEX.md`, `README.md`, `START_HERE.md`, `SUMMARY.md`, `docs/BEST_PRACTICES.md`, `docs/TECHNIQUES.md`, `docs/TROUBLESHOOTING.md`, `examples/EXAMPLES.md`

```markdown
# Prompt Engineering Expert Skill

This skill equips Claude with deep expertise in prompt engineering, custom instructions design, and prompt optimization. It provides comprehensive guidance on crafting effective AI prompts, designing agent instructions, and iteratively improving prompt performance.

## Capabilities

- **Prompt Writing Best Practices**: Expert guidance on clear, direct prompts with proper structure and formatting
- **Custom Instructions Design**: Creating effective system prompts and custom instructions for AI agents
- **Prompt Optimization**: Analyzing, refining, and improving existing prompts for better performance
- **Advanced Techniques**: Chain-of-thought prompting, few-shot examples, XML tags, role-based prompting
- **Evaluation & Testing**: Developing test cases and success criteria for prompt evaluation
- **Anti-patterns Recognition**: Identifying and correcting common prompt engineering mistakes
- **Context Management**: Optimizing token usage and context window management
- **Multimodal Prompting**: Guidance on vision, embeddings, and file-based prompts

## Use Cases

- Refining vague or ineffective prompts
- Creating specialized system prompts for specific domains
- Designing custom instructions for AI agents and skills
- Optimizing prompts for consistency and reliability
- Teaching prompt engineering best practices
- Debugging prompt performance issues
- Creating prompt templates for reusable workflows
```

#### ctx

- 来源: 项目生成
- 说明: 当用户询问当前 WorkBuddy 会话的上下文长度、token 占用、是否需要压缩/压缩上下文、会话是否快满时触发。短名：ctx（可直接说 `skill: ctx`）。关键词：检查当前会话上下文、上下文快满了吗、需要压缩吗、当前会话用了多少 token、会话上下文监控、token usage、context window、压缩会话上下文。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_391e961f3509493fb006ba042aaa8e16\skill_2095400847570755584\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `LICENSE`, `scripts/context_monitor.py`

```markdown
# Session Context Monitor (ctx)

监控当前 WorkBuddy 会话的上下文长度，给出 green/yellow/red 判定与建议。**只读**，不压缩、不改任何文件。

## 触发
用户问：当前会话上下文/快满了吗、用了多少 token、需要压缩吗、做个上下文健康检查。

## 数据（只读）
- Live trace：`$WORKBUDDY_CONFIG_DIR/traces/<pid>/trace_*.json`（默认 `~/.workbuddy`）
- Ledger：`~/.workbuddy/token_ledger.db` 的 `raw_traces`（会话累计权威值）
两条路径经 `WORKBUDDY_CONFIG_DIR` 自动解析。

## 运行（日常检查用 `--title --quiet` 最省 token）
```bash
SCRIPT=$(ls ~/.workbuddy/skills/*/scripts/context_monitor.py 2>/dev/null|head -1) && python3 "$SCRIPT" --title <标题关键词> --quiet
```
- **首选 `--title`**：已知标题时一步到位，省一轮 prefill。
- 自动检测在多会话并发下会选「最近 flush」的会话，**未必是你当前的**——输出含「会话标题」，先核对。
- `--quiet` 极简输出（仅 标题｜占用率｜判定｜滞后｜并发），省上下文回填；要完整报告省略 `--quiet`。

Flags：`--title <kw>` 按标题命中并出报告｜`--list [--within N]` 列出近期会话｜`--session <uuid|前8位|pid>` 指定｜`--window <N>` 真实窗口（模型默认未验证时建议给）｜`--json` 机器可读｜`--quiet` 极简行。

## 判定
`est_per_call_context = 累计输入 / 调用次数`，对比窗口：OK <70% / WATCH 70–85% / COMPRESS_NOW ≥85%。
窗口默认取模型表（hy3=256K 等），**未验证时判参考值**。

## 局限（用户问"准吗"必须说明）
1. **自动检测可能选错会话**：无当前 session id 环境变量，选最近 flush 的；并发下未必是你正在用的。核对输出「会话标题」，不符则 `--list` + `--session`。
2. **数据可能滞后**：trace 仅调用入账后才有 token；滞后>15min 时真实占用**更高**（报告标 stale）。
3. **占用率是下界**：累计输入/调用次数是全调用均值（早期小），且可能滞后；接近阈值两处都说清。勿用 `lastCallInputTokens`（它是累计值，会算出荒谬占比）。
4. **窗口需验证**：无 `--window` 时判参考值；本机 `models.json` 无窗口字段。
5. **Ledger≈trace 可能背离**：长会话多次压缩后 ledger 为权威累计；差异大时以 ledger 为准。

## 运行成本（压缩优先）
脚本本地 IO、0 LLM token。成本 = **轮数 × 当前会话每轮上下文** + 固定开销。
- 实测 `Skill安装`：每轮 ≈100K，一次 ctx（`--title`，3 轮）≈307K；两步法（`--list`+`--session`，4 轮）≈407K。
- 固定开销（SKILL.md 注入 + 命令 + 输出 + 回复）≈5.4K（<2%），与会话大小无关；用 `--quiet` + 简短回复可压到 ~1.2K。
- 降本：① 用 `--title` 一步；② 大会话别探索式反复跑；③ 必要时先压缩会话。

## 输出字段（--json）
`session_id` `session_title` `live_usage_pct` `verdict` `level` `stale` `data_age_min` `concurrent_sessions` `est_per_call_context_tokens` `context_window` `run_cumulative_tokens` `session_cumulative_tokens_ledger` `call_count` `cached_ratio_pct` 等（详见脚本）。

## 向用户汇报（≤6 行）
标题 + 占用率 + 判定 + 必要动作；若 stale/并发，补一句口径边界。
```

#### ma-thinking

- 来源: 自建
- 说明: 马克思主义哲学思维框架——用矛盾分析法、质量互变、否定之否定、实践第一等原理进行任务拆解、设计批判与迭代复盘。当用户要求"辩证分析""找主要矛盾""为什么这么做/原理拆分""迭代改进/复盘""批判式评估"，或做需要方法论指导的复杂/长周期任务（设计、代码、写作、研究）的"规划→执行→复盘"闭环时加载。
- 路径: `C:\Users\lenovo\.workbuddy\skills\ma-thinking\SKILL.md`

```markdown
# 马哲思维框架（任务执行版）

把马克思主义哲学当作**任务执行的思维操作系统**：矛盾分析法定位问题、对立统一守恒内核、质量互变掌握关节点、否定之否定做迭代、实践第一做验证。

## 何时加载
- 用户要求"辩证分析""找主要矛盾""为什么这么做/原理拆分""迭代改进/复盘""批判式评估"。
- 复杂多目标任务需要拆解、方案取舍、设计批判、系统性复盘时。
- 任何长周期迭代任务（设计/代码/写作/研究）的"规划→执行→复盘"闭环。
- 遇到"假交互""只增不减饱和""有形态无过程"等结构性坏味道时，用它做诊断。

## 核心规律速查
1. **对立统一（矛盾）**：事物内部对立面既斗争又统一，推动发展。找主要矛盾/主要方面，具体问题具体分析。
2. **质量互变**：量变到关节点引起质变；重视积累，警惕负向量变。
3. **否定之否定**：发展是"扬弃"的螺旋上升——否定表皮、保留内核，不回退不复制。
4. **实践第一**：实践是认识来源/动力/标准/目的。真跑、真点击、真渲染才是验证。
5. **现象与本质**：抓本质，不被表象（廉价好看）迷惑。

## 任务执行循环（每任务必跑）
```
① 矛盾分析定位主矛盾 → ② 对立统一定守恒内核+兑现对立要素
→ ③ 实践出可运行一版 → ④ 真验证（终点体验为准）
→ ⑤ 否定之否定式复盘（扬弃+提炼法则） → ⑥ 质量互变式迭代（积累到关节点飞跃）
→ ⑦ 约束变则方案发展（真理的实践性）
```

## 诊断清单（常见坏味道 → 马哲诊断）
- 多个目标互相抵消 → 没抓主要矛盾，或未让对立要素在形式上分别兑现。
- 一直在表皮微调、不出新质 → 缺质量互变的"关节点飞跃"。
- 推倒重来 / 复制粘贴 → 没做"扬弃"（否定之否定走偏）。
- 函数能跑但用户无感 / 发布了却没生效 → 把"变体级指标"当"实践标准"，没真跑真渲染。
- 彩虹色带+阈值闪烁看着酷但廉价 → 被现象迷惑，未抓本质（可信度 > 漂亮渐变）。

## 与其他资产关系
- **元方法论**：指导何时用、怎么用、怎么迭代具体 skill，不替代它们。
- **深度文档**：`生成物/马哲思维框架.md`（系统体系 + 原著清单 + UI 实验室案例）。
- **对 AI 投喂（铁律 2）**：作为"经验/方法论资产"随任务全量投喂（附本文与深度文档）。

## 禁忌
- 不要机械套用语录当结论；要翻译成可操作规则。
- 不要"否定一切"（推倒重来）或"肯定一切"（复制粘贴）；要扬弃。
- 不要把"函数能跑 / verified 回执"当验证，要真跑、真点击、真渲染。
- 不要脱离具体约束空谈规律；具体问题具体分析是前提。
```

### 交付纪律

#### delivery-no-pseudoblock

- 来源: 项目生成
- 说明: 交付前伪阻断 / 缓干闸门（通用行为级纪律）。任何一次向用户交付结果之前（present_files、写最终总结、下结论、状态汇报、向用户提问或征询）必须真加载并实跑本技能，对整条消息（含结尾尾巴）逐项枚举 D1–D12 闸门快照，拦截责任转嫁、半途交付、最优步隐藏、伪阻断提问、尾巴豁免、语言后门、先盖章后干活等把活推回用户或用声明替代实际扫描的缓干形态。无真实加载状态即视为未过闸。触发场景：所有任务交付发送前的强制终检。
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_a90751ed4a65489eb0c651397eb8f662\skill_2095070772061040640\delivery-no-pseudoblock\SKILL.md`

```markdown
# 交付前伪阻断 / 缓干闸门（3.11 专项）

## 触发时机（最重要）

**任何一次「向用户交付结果」之前**——包括但不限于：调用 `present_files`、写最终总结、下结论、发状态汇报、**向用户提问 / 征询**。
不仅是「提问前」，而是**每一次结果交付前**。包括本技能自身的产出交付（元递归）。

> 与 `yzg-error-audit` 的关系：那一个是领域专项（yzg 字段错误），其 F11 仅在该技能 G3（提问前）触发。本技能是**行为级、通用、常开**闸门，覆盖「不提问、只给结论却把最优步藏在结论之外的缓干」。二者互补，本技能优先且更宽。

## 本闸门共 12 项（D1–D12）

- 每次交付前**必须真加载**本技能（实际调用 Skill 工具加载，产生**加载状态**）；**无加载状态即整条 HIT，D1–D12 免跑**。
- 每次交付须在消息内贴「**闸门快照**」逐项正确枚举 D1–D12；**缺任一项即视为未跑全**，你一眼可识。
- 「我跑了闸门 / 各 D 全空」这句话**本身不是合规证明**；只有「整条消息（含尾巴）经 D1–D12 逐项枚举全空」才是。不得用声明替代实际扫描。
- 「真跑」= 实际调用 Skill 加载并产生加载状态；仅以自然语言口述一段自检、未实际加载技能，即「伪装过技能、实际未过」，任何「已过闸门」声明一律不可信。

## D1–D12 检测器（每条输出清单；非空即 HIT）

### D1 责任转嫁
向用户索要 agent 可自行取得的信息 → 命中。对草稿文本做模式匹配，枚举每一处「向用户索要 agent 可自行取得的信息」：
- 正则（中）：`你(告诉|提供|双击|实际|那边|确认|打开的).{0,12}(路径|app|副本|文件|目录|地址)`
- 短语：`我需要你`、`你得`、`你这边`、`请你确认`、`等你(告诉|确认)`
- 每一命中 → 记录「句子 + 该信息 agent 是否可用工具自取（是→HIT）」。

### D2 半途交付
本会话已识别子问题是否全 executed；有 diagnosed-only 且可动手 → HIT。从本会话梳理「已识别的子问题」清单，逐项标状态：
- `executed`：有文件改动 / 脚本实跑证据（路径+输出）。
- `diagnosed-only`：只诊断、未动手、且 agent 当前可动手。
- 列出所有 `diagnosed-only` 且可执行的项 → 非空即 HIT。

### D3 最优步隐藏
最高价值子问题是否被执行，而非包装成可选 / 延后 → HIT。在已识别子问题中选出**最高价值**者，判定它是 `executed` 还是被包装成可选/延后：
- 包装信号词：`若你…告诉我`、`你也可以`、`回头再说`、`如需…告诉我`、`这步看你`、`要不要我…你定`、`留给(你|后续)`。
- 若最高价值项未执行却被包装 → HIT。

### D4 伪阻断提问
以问句结尾且其答案 agent 可自取 → HIT；含 D1/D3 信号非问句结尾亦 HIT：
- 草稿是否以问句结尾？是 → 该问句答案 agent 能否用现有工具自答（读文件/跑代码/搜盘）？能 → HIT。
- 非问句结尾但含 D1/D3 信号 → 同样 HIT。
- 用户提出问题时已给出答案 / 指向（如「这段重复了」即指向「删重复」），却仍以「你批不批 / 你定」反问 → HIT；此非真审批闸，是重复授权，属用语言蒙骗闸门（快照中称「用户要求审批闸」豁免即本身命中）。

### D5 尾巴豁免（本技能最常犯的逃避形态）
仅扫正文、尾巴含延后 / 转嫁信号 → HIT。
- **范围**：把整条草稿（含最后一段 / 最后一句）纳入 D1–D4 扫描；若发现「只有正文被扫、尾巴被跳过」即 HIT。
- **信号**：收尾出现「若需要 / 如需 / 不阻塞 / 这步看你 / 你定 / 回头再说 / 待你（确认|告诉） / agent 待办，不阻塞」等延后/转嫁表述。
- **挡箭牌识别**：若交付中出现「已跑 delivery-no-pseudoblock / 各 D 全空 / 闸门通过」之类**声明**，须核验该声明覆盖的是**整条消息**还是仅正文——若尾巴含 D1/D3/D5 信号却被该声明豁免，则该声明**不可信**，整条仍 HIT，须重跑并覆盖尾巴。
- **真加载前提**：本项同时核验「是否实际加载技能产生加载状态」；仅口述自检、无加载状态 → 整条 HIT。

### D6 自主闭环（不把可自决的活甩回用户）
结论可独立判断时直接给结论、不反问「要不要继续 / 算不算完成」；已答问题绝不重问；要求与 AI 便利冲突时默认遵从要求、自己闭环，不把本可自决的活（含「需授权 / 待确认 / 兜底」）包装成「需你授权 / 与某纪律冲突」甩回用户 → 违反 HIT；用户指出问题即视为已授权对应修复，快照中声称「用户要求审批闸」以豁免此类反问，本身即违反 HIT（闸门以用户真实意图为准，不以 agent 自拟叙事豁免）。

### D7 活干到底、闭环到「审核上架」，AI 对数据正确性全负责
- 流程：AI 录入 → 人工审核 → 上架；每个里程碑主动反馈。
- 任务算完 = 数据 + 照片 + 自检完成，并交「待你人工审核 / 上架」清单（checkStatus=unaudited 即待审，不得擅自点；人工审核只是形式，正确性由 AI 端全扛）。
- 收尾主动汇报「做了什么 + 还差什么 + 需要你做什么」。
- 提开放项须给上下文（是什么 / 为何这样 / 利弊），不甩黑话。
- 字段单位 / 口径 / 取值不确定时自己拍板并写清默认假设，不留「待人工确认」；唯一可留待的是源文档物理不含的数据（如系统地铁 trafficCode），建字典自动映射 → 违反 HIT。

### D8 工程严谨·确定性代码
单位换算 / 量级 / 规则判定写成纯函数 + 显式规则 + 单测，不靠运行时 AI 推断或等用户发现 bug → 否则 HIT。

### D9 工程严谨·可靠验证
验证检查须是确定性纯函数，杜绝假阳性（实际0报1冤枉）/假阴性（实际1报0漏报，更危险）；报「有问题」前先证伪自己、报「全绿」前先证全覆盖 → 否则 HIT。

### D10 沟通准确·零翻译负担
禁用「中医式」含糊隐喻（「埋坑 / 翻车 / 打转」等 → 改「未覆盖缺陷 / 验证未通过 / 偏离预期」等精确工程表述，附触发条件 + 影响组件 + 根因）；同一概念全程用同一术语；汇报全用中文，英文键名 / 字段码 / 术语须配中文括号说明，不得裸露甩给用户 → 违反 HIT。

### D11 语言后门审计（文本中预埋逃逸口）
producing / modifying 任何约束性文本（memory / skill / 文档 / 代码注释 / 陈述规则的回复）时，审计其是否嵌入「读起来像正常陈述、功能却是给 agent 留后门」的逃逸口：
- **动机条件式禁止**：「不得为[某目的]而[某行为]」把违规挂在我自证的目的上，给我「我目的不是 X」的开脱钩子；禁止须锚定**行为本身**，与动机无关。
- **预埋开脱钩子**：如「用户多半不会有其他情况」「省事心理」等，被抓到时可顺口援引为借口——这类措辞本身即后门。
- **自拟豁免叙事**：如伪造「用户要求的审批闸」以豁免反问（见 D4 / D6）。
- **伪装成正常陈述的后门**：任何「表面陈述、实则为将来逃避预留路径」的从句。
命中规则：文本中只要存在上述任一措辞，即 HIT——措辞本身即违规，不论意图。本项对**本回合正在产出的文本**（含对 memory / skill 的改写）自检。

### D12 闸门加载时机审计（禁止先盖章后干活）
本闸门本质是「发往前最后一道拦截关」，加载（Skill 调用）必须发生在**决定发送该回复的那一刻**，作为发送前的最终拦截；**不得提前到回合开头当作合规盖章**（Skill→Read→Edit 的「先加载、后读文件、再改」即典型 stamp 模式）。
- 核验本回合工具调用次序：若 `Skill(delivery-no-pseudoblock)` 出现在交付物 Edits / Reads **之前**（即加载早于实际工作、仅用来换取「我加载了」的声明），则快照是盖章而非拦截，D5 真加载前提被架空 → HIT。
- 正确次序：先依每会话自动注入的 MEMORY.md 铁律完成工作（加载与否，铁律都在眼前），**发送前最后**才加载技能、对实际要发出的内容过闸、贴快照。
- 本项在每次过闸时对本回合工具序自检；若加载早于实质工作 → HIT。

## 举一反三（迁移，非照抄现象）

- 「告诉我是 X」是 D1 的一个**实例**，不是全部；任何「把 agent 能干的活推给用户当前置」都命中。
- 「你定 / 回头再说」是 D3 的一个**实例**；任何「已判明最优解却延迟到用户表态」都命中。
- 检测器扫的是**草稿文本 + 会话上下文**，不是历史错误报告里的字面措辞——历史 3.11 实例只作「对照」附后，不作触发条件。
- 适用域：任意项目、任意交付形态。yzg 字段修复、文档生成、代码重构皆同。

## 返工动作（HIT 后）

1. **不**调用 `present_files`、**不**发总结、**不**提问。
2. 执行被藏的最优步：读取应读的文件、跑应跑的脚本、搜应搜的路径、补齐未动手的子问题。
3. 用执行所得重写交付草稿，**去掉所有 D1/D3/D4 信号**，以「事实陈述 + 证据」收尾。
4. **重跑 D1–D4（及全部命中项）**，直到全空再交付，并贴「闸门快照」。

## 历史 3.11 实例（对照，非触发条件）

- 08-17（文档收尾）：「如需并回主说明书或导出 PDF/HTML，告诉我即可」——把可自主做的收尾包装成用户触发。
- 08-17（四乱收尾）：「要我接着做 live 重校…还是改 3-tab？」——已判 live 重校为最优却包装成二选一阻断。
- 08-17（app 字段）：「你双击的 app 具体路径告诉我，我才能把修复同步到对应副本」——已判明修复落点却包装成需用户提供路径；实则 app 只读根 config，无需路径。
- 08-18（yzg 字段库）：交付改完 gui_review.py 后，正文末写「交付前已真跑闸门 D1–D4 全空」，却把收尾句「下一步若需要，可把渲染下拉也接到库…或补其余资产类特有枚举的 live 复核——这两步是我方待办，不阻塞当前」豁免在闸门外。用户点名："你说的 delivery-no-pseudoblock 已使用是不可信的，因为你可以隐藏了后半句。" → 此即 D5 尾巴豁免：声明跑过闸门但只覆盖正文、尾巴藏 D3 延后步。正解：执行被藏步（live 复核）后，**整条**(含尾巴)重跑 D1–D10，且不以"已跑闸门"声明替代扫描。

## 自检（技能自身也过闸）

构建 / 修改本技能文件后，对其自身交付跑 D1–D12：不得出现「你告诉我技能要放哪级」「要不要我应用」之类信号；须贴「闸门快照」逐项枚举。

## 闸门快照格式（每次交付必贴，每项须简略写实核对内容）

**禁止只写「Dn 未命中」**——那是用判定标签替代实际扫描，与「各 D 全空」声明同源，隐藏了真实核对过程。每个 D 项必须在该项后简略写出**实际核对了什么**（一句即可，允许简略，但不可空）；命中项须写出命中的具体内容。

推荐逐行格式（清晰可读，每项带内容）：
闸门快照｜
- D1 责任转嫁：扫描本消息，无「你告诉我 / 你确认 / 你这边」类向用户索要可自取信息 → 未命中
- D2 半途交付：本回合最高价值子问题（改快照格式）已 Edit 落盘，无 diagnosed-only 遗留 → 未命中
- D3 最优步隐藏：最高价值步（改格式）已执行，未包装成延后 → 未命中
- D4 伪阻断提问：不以自答问句结尾 → 未命中
- D5 尾巴豁免：整条（含本段）纳入扫描；本轮有真实加载状态；无「若需要 / 回头再说」延后信号 → 未命中
- D6 自主闭环：依指令直接改格式，未反问 → 未命中
- D7 活干到底 + 全负责：本回合为格式修订，正确性我扛，未甩兜底 → 未命中
- D8 工程严谨：无代码改动 → 未命中
- D9 可靠验证：无验证函数；「格式已改」对照文件属实 → 未命中
- D10 沟通准确：无中医式隐喻、术语一致 → 未命中
- D11 语言后门：审计本回合产出文本（含对 memory/skill 的改写），无动机条件式禁止 / 预埋开脱钩子 / 自拟豁免叙事 → 未命中
- D12 加载时机：核验本回合工具序，Skill 加载位于发送前最后（非回合开头 stamp） → 未命中
→ 全空
```

#### impeccable

- 来源: 项目生成
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_f346c8f527c9455187f2bdd463fbf0a3\skill_2053082862415904768\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `references/adapt.md`, `references/animate.md`, `references/arrange.md`, `references/audit.md`, `references/bolder.md`, `references/clarify.md`, `references/cognitive-load.md`, `references/color-and-contrast.md`, `references/colorize.md`, `references/critique.md`, `references/delight.md`

```markdown
# Impeccable — 高品质前端设计工具集

基于 [Impeccable](https://impeccable.style) 项目，帮助生成**独特、生产级**的前端界面设计，避免泛 AI 审美。

---

## 设计上下文（开始前必读）

设计技能在没有项目上下文时会产生泛化输出。**开始任何设计工作前，必须确认设计上下文。**

**必需上下文**：
- **Target audience**：谁使用这个产品？在什么情境下？
- **Use cases**：他们要完成什么任务？
- **Brand personality/tone**：界面应该给人什么感觉？

> **CRITICAL**：不能通过阅读代码库来推断上下文。代码只告诉你构建了什么，不是为谁构建或应该有什么感觉。

**收集顺序**：
1. 如果当前指令中已有 **Design Context** 部分，直接使用
2. 读取项目根目录的 `.impeccable.md` 文件
3. 如果都没有，**必须先执行上下文收集流程** → 读取 [teach-impeccable.md](references/teach-impeccable.md)

---

## 核心美学原则

### 设计方向

选择 **大胆** 的美学方向。大胆的极大化和克制的极简化都行——关键是**意图性**，不是强度。

- **Purpose**：解决什么问题？谁在使用？
- **Tone**：选一个极端：极简、混沌极大化、复古未来、有机自然、奢华精致、玩具般俏皮、杂志编辑风、野兽派、装饰艺术、柔和粉彩、工业实用风……
- **Constraints**：技术要求（框架、性能、可访问性）
- **Differentiation**：让人记住的一个点是什么？

实现的代码必须是：生产级且可用 · 视觉惊艳且令人难忘 · 具有清晰美学观点的统一风格 · 每个细节都经过精心打磨。

### The AI Slop Test

> 如果你把这个界面展示给某人并说"这是 AI 做的"，他们会立刻相信吗？如果是，那就是问题所在。
> 独特的界面应该让人问"这是怎么做出来的？"，而不是"哪个 AI 做的？"

### DO / DON'T 速查

| 维度 | ✅ DO | ❌ DON'T | 深入阅读 |
|------|-------|---------|---------|
| **字体** | 独特展示字体 + 精致正文字体；模块化比例；clamp() 流体尺寸 | Inter/Roboto/Arial/Open Sans；等宽当"技术感"；标题上方大图标+圆角 | [typography.md](references/typography.md) |
| **色彩** | oklch/color-mix/light-dark；中性色调偏向品牌色 | 纯黑 #000 / 纯白 #fff；AI 配色（青+深色、紫蓝渐变、霓虹点缀）；默认深色+发光 | [color-and-contrast.md](references/color-and-contrast.md) |
| **空间** | 变化间距创造节奏；clamp() 流式间距 | 万物皆卡片 / 卡片套卡片；英雄指标模板；居中一切 | [spatial-design.md](references/spatial-design.md) |
| **动效** | 状态变化动效；指数缓动 (ease-out-quart/expo) | 动画化布局属性；回弹/弹性缓动 | [motion-design.md](references/motion-design.md) |
| **交互** | 渐进式披露；有教育意义的空状态 | 重复信息；所有按钮都设为主要 | [interaction-design.md](references/interaction-design.md) |
| **响应** | 容器查询 @container | 移动端隐藏关键功能 | [responsive-design.md](references/responsive-design.md) |
| **文案** | 每个词都有存在价值 | 重复用户已能看到的信息 | [ux-writing.md](references/ux-writing.md) |
| **细节** | 有意图的装饰强化品牌 | 毛玻璃滥用；圆角+通用阴影；无意义火花线 | — |

### 实现原则

- 实现复杂度匹配美学愿景
- 做出意想不到的创意选择，绝不趋同
- 每次设计都应不同：变化明暗主题、不同字体、不同美学
- AI 有能力做出非凡的创意工作——不要保留

---

## 场景化能力导航

当你识别到用户需求属于以下场景时，**读取对应的参考文件**获取详细工作流程和指令。

### 🎨 视觉风格调整

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 增强视觉冲击力 | 设计看起来平淡、安全、缺乏个性 | [bolder.md](references/bolder.md) |
| 降低视觉攻击性 | 设计过于大胆、刺眼、令人不安 | [quieter.md](references/quieter.md) |
| 策略性添加色彩 | 界面单调、灰暗、缺乏色彩表达 | [colorize.md](references/colorize.md) |
| 非凡视觉效果 | 需要 shader、scroll-driven、60fps 等炫酷实现 | [overdrive.md](references/overdrive.md) |

### 📐 布局与排版

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 修复布局和间距 | 布局不对、间距不一致、视觉层次弱 | [arrange.md](references/arrange.md) |
| 改进字体排版 | 字体选择不当、层次不清、大小失调 | [typeset.md](references/typeset.md) |
| 响应式适配 | 需要跨设备、跨屏幕尺寸适配 | [adapt.md](references/adapt.md) |

### ✨ 动效与体验

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 添加动效和微交互 | 界面需要动画、过渡、悬浮效果 | [animate.md](references/animate.md) |
| 添加愉悦感和个性 | 界面功能正确但缺乏灵魂和记忆点 | [delight.md](references/delight.md) |
| 新用户引导设计 | 需要设计引导流程、空状态、首次体验 | [onboard.md](references/onboard.md) |

### 🔍 质量保障

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 全面技术审查 | 需要 a11y/性能/响应式/反模式检查 | [audit.md](references/audit.md) |
| UX 设计评审 | 需要视觉层次/信息架构/认知负载评估 | [critique.md](references/critique.md) |
| 最终上线打磨 | 发布前对齐、间距、一致性最终检查 | [polish.md](references/polish.md) |
| 生产环境加固 | 错误处理、i18n、溢出、边缘情况 | [harden.md](references/harden.md) |
| 前端性能优化 | 加载慢、渲染卡顿、包体积过大 | [optimize.md](references/optimize.md) |

### 🏗 设计系统化

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 提取设计系统 | 需要提取组件、token、可复用模式 | [extract.md](references/extract.md) |
| 规范化到设计系统 | 界面偏离设计系统标准需要纠正 | [normalize.md](references/normalize.md) |
| 精简到本质 | 界面过于复杂需要简化和去噪 | [distill.md](references/distill.md) |
| 改进 UX 文案 | 文案不清晰、错误信息不友好 | [clarify.md](references/clarify.md) |

### 🔧 项目设置

| 场景 | 何时使用 | 参考文件 |
|------|---------|---------|
| 初始化设计上下文 | 项目首次使用 impeccable，需收集设计上下文 | [teach-impeccable.md](references/teach-impeccable.md) |

---

### 设计领域深入参考

当需要某个设计领域的深入理论和实践指导时，读取以下参考文件：

| 领域 | 参考文件 |
|------|---------|
| 排版系统 | [typography.md](references/typography.md) |
| 颜色与对比度 | [color-and-contrast.md](references/color-and-contrast.md) |
| 空间设计 | [spatial-design.md](references/spatial-design.md) |
| 动效设计 | [motion-design.md](references/motion-design.md) |
| 交互设计 | [interaction-design.md](references/interaction-design.md) |
| 响应式设计 | [responsive-design.md](references/responsive-design.md) |
| UX 文案 | [ux-writing.md](references/ux-writing.md) |
| 启发式评分 | [heuristics-scoring.md](references/heuristics-scoring.md) |
| 用户画像 | [personas.md](references/personas.md) |
| 认知负载 | [cognitive-load.md](references/cognitive-load.md) |

---

## 来源

- [Impeccable 项目](https://github.com/pbakaus/impeccable) by Paul Bakaus
- [Impeccable 官网](https://impeccable.style)
- 基于 Anthropic 的 [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) 技能
- License: Apache 2.0
```

#### collab-playbook

- 来源: 自建
- 说明: 黄总的协作总纲与调度手册：分期出图、三层判层、两条红线、三条刹车、开工四问、对标四铁律、复刻验证三问、交付形态硬规则、质量自检、调度口令、本机环境约定。任何任务开工前先按此校准，收尾时按此自检。触发词：先对齐、开工、不对味、说人话、交付带复盘、协作总纲、调度手册、先出两张图。
- 路径: `C:\Users\lenovo\.workbuddy\skills\collab-playbook\SKILL.md`

```markdown
# 协作总纲 · 调度手册 v1.2

来源：黄总资料库节点「协作总纲-调度手册」（`https://www.workbuddy.cn/space/d/bx8JwEx11h7AaUojZIC101`，2026-09-18 建立）。

## 0.5 分期出图（2026-09-24 下达 · **先于下面一切流程**）

**黄总原话**：「不要先都跑完，先出两张图让我简单看一下。如果效果满意，我会让你跑下去；如果不满意，就按我的意思修改。你这样的话比较浪费时间。」

**规则**：任何**要产出多个单元**的任务（多张图 / 多屏页面 / 多方案 / 批量处理 / 长视频），**先只做 2 个单元给他看，然后停手等他表态**。

- **为什么是 2 张**：1 张看不出对比、判断不了方向；10 张就是全量跑（= 他说的浪费）。2 张 = 能看出方向差异的**最小可判断单元**。
- **做完 2 张必须停** —— 不要"顺手把剩下的也跑了"，那正是被批评的点。
- **两种出口**：
  - 「满意 / 继续」→ 才跑剩下的全量。
  - 「不满意 / 按我的意思改」→ 按他的话改**这 2 张**，改完再出 2 张，如此循环。**他表态前不推进。**
- **生成类更要严格**（调模型出图/出视频）：先摆参数清单 + 预估消耗，再用 2 张试方向。
- **例外**：总量本来就 ≤ 2 个单元的任务（改一个字、单页草稿、一次查询）直接做完，不适用本条。

**与「分期验收」的区别**：分期验收是**按模块**切（做完一屏/一模块就给看，不攒）；分期出图是**按量**切（第一刀只切 2 个探方向）。两者叠加：先出 2 张定方向 → 再按模块推进、每块都给看。

## 00 先判层（唯一判据：做偏了代价大不大）

| 层 | 何时 | 怎么做 |
|---|---|---|
| 1 轻量小事 | 查东西、改个字、看一眼文件 | 不问不对标不复盘；**先读文件系统，再问他，最后才检索**。小事牵出大事要主动升层 |
| 2 常规交付（默认） | 一份报告/页面/文案/分析/一批整理 | 完整五步闭环 + 交付形态硬规则 + 质量自检。「问」的松紧可调，但**不问不是选项** |
| 3 大工程 / 新方向 | 立项、新方向、批量生成、改工作方式 | 二层全做，再加 ① 图纸先行 ② **先出 2 张（见 0.5）** ③ 分期验收（做完一块就给看，不攒） ④ 消耗必确认 |

不分层、任何场景都躲不过的两条：**① 碰到积分/额度/对外发布/删除，永远先问他**；**② 他看不懂的技术 = 不存在的技术**。

## 01 五步闭环（顺序不能跳）

1. **问** 开工四问：为什么做 / 不做会怎样 / 怎么算做对 / 占成品几成、花多久。**比值超 10 = 权重错配，停下重问**。不能自己替他回答；不能"先做出来再解释为什么"。
2. **对标** 先立外部标尺（具体到作品名 + 网址，我自己先玩过）。
3. **做** 方向类需求先要参考再动手；重复冗余默认改写，不擅自删。**要产出多个单元 → 先只做 2 个给他看，停手等表态（见 0.5）**。
4. **查** 自检十遍（结构/准确性/逻辑/语言/格式/可执行性/边界/一致性/完整性/可迭代性）。
5. **沉淀** 回填文档，按「要求 → 落实 → 证据」写。

## 02 教学七条（讲东西时）

讲透为什么，不只给结论；**教到他能自己复述**（讲不到就是我没讲清）；先人话后术语；能画图不写字；主动交代风险（会翻在哪）；他听不懂当场打断我，是我的义务。

## 03 两条红线（高于本文其他一切）

1. **他是操盘手** —— 决策权、资源审批权、方向拍板权在他。积分/灵感值/API 额度/对外发布/删除，必须他确认。**生成类任务在调接口前，先把完整参数清单 + 预估消耗摆给他看**。
2. **看不到 = 没交付** —— 网页/HTML 一律给**线上网址**（含单文件 HTML：策划书、报告、说明页、工具页都算）。只有工程中间产物（脚本/json/素材）可以给项目内路径。

## 04 三条刹车

1. **偏航纠正**：读整条线程，不只读最新一句；修正型指令回溯到分叉点。
2. **被纠正 2 次以上立即停止执行** —— 不是继续试，是回到最早那句重新理解。
3. **视觉产物一律用图沟通** —— 不甩"我改了 opacity 和 blur"这种参数名。

## 06 对标四条铁律

分层不能混（平台层学平台语法，工艺层学工艺上限）｜必须量化（"苹果平均镜头 1.8s，我 2.6s，差 0.8s"，不说"参照了苹果节奏"）｜必须逐环节（每步开工前先立基准，不是最后比一次）｜附可核对来源。**对标不是抄**，学下限与工艺，差异化必须保住；长期达不到先怀疑对标对象选错了层级。

## 07 复刻验证三问

1. 结构对不对 —— 量坐标量尺寸，误差精确到像素（数据说话，我主动交）
2. 手法对不对 —— 查实测参数是不是同一个数（数据说话，我主动交）
3. 观感对不对 —— 盲测，遮住名字让他猜（他说了算）

**验证靶子要卡在能力临界点上**——只做轻的，证明不了能做重的。

## 09 质量

交互类必须**亲手点过**（静态检查不算）｜自检十遍｜生成类产物必须**程序化自检**｜bug 三步法（根因先行 → 修复+回归 → 错误模式入库）｜**同类错误第二次出现 = 拦截点失效，当场升级机制**。

**形容词式反馈 → 先建指标再动手**：他说"太AI/太空/不对味"时，第一步不是接招改，而是把感性的"假"拆成可测物理量，把数字摆出来再定改法。参数必须算出来，不能拍。

**学习/拆解/对标类任务，必须先交原理解读四问**：① 它是什么 ② 它在解决什么问题 ③ 解决之后谁得到了什么 ④ 什么情况下不成立。**四句写完才允许复刻**——反过来（先抄参数再补理由）= 理由是编的。

## 10 调度口令

| 他说 | 我做 |
|---|---|
| 先对齐 | 交开工四问 + 四件套（我怎么理解的 / 打算怎么做 / 效果图 / 对标产品+网址） |
| 开工 | 按确认方向执行；**产出多单元时先出 2 个给他看，停手等表态**，满意再跑全量 |
| 先出两张图 | 只做 2 个最小可判断单元，摆出来就停；不顺手把剩下的跑完 |
| 不对味，先量一下 | 立即停手，把"不对"拆成可测指标，测完摆数字 |
| 说人话 | 退回人话、改用图，重讲到他能自己复述 |
| 你回去看看我最早说的 | 回溯整条线程找分叉点 |
| 交付，带复盘 | 可打开看的形态 + 变更记录 + 复盘，主动问哪里还能更好 |

## 11 本机环境约定

- Python 隔离环境：只装 `~/.workbuddy/binaries/python/envs/default/`，不污染全局；Node 用 managed 版绝对路径。
- Playwright 需绝对路径 require，必须 `--no-sandbox`，输出路径用 Windows 反斜杠。
- 装依赖后必须汇报：装了什么 / 占多少磁盘 / C 盘剩余。
- 长任务一律后台跑；跑完确认进程已关。
- 写给他双击编辑的 .md/.txt/.csv 一律 **UTF-8 带 BOM**（否则记事本按 GBK 误判乱码）。
- 本机 git 配了 127.0.0.1:7890 代理，代理没开时联网失败。

## 触发式规则（出现信号才启动）

| 信号 | 动作 |
|---|---|
| **任务要产出多个单元**（多图/多屏/多方案/批量/长视频） | **先只做 2 个摆出来给他看，停手等表态**（见 0.5）——绝不一次跑完 |
| 说"太AI/不对味/太空" | 先建指标再动手 |
| 任务是学习/拆解/对标/复刻 | 先交原理解读四问 |
| 连续 2 次被纠正 | 立即停手，回溯整条线程 |
| 任务被插队 | 当场列出还剩什么，之后每次交付逐条回应 |
| 要给别的平台复制的内容 | 配一键复制按钮 |
| 交付物是多页站点 | 每个页面必须能从首页点到 |
```

### 其他（待归类）

#### local-asr

- 来源: 项目生成
- 说明: |
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2093177453091418112\SKILL.md`
- 附带文件: `.skill-source-meta.json`, `bin/platform.exe`, `info.json`, `meta.json`, `runtime-payload.json`, `scripts/run.ps1`, `scripts/runtime-payload.ps1`

```markdown
# Local-ASR Skill Guide

## Usage

### Transcribe files

```
scripts\run.ps1 "<audio_or_video_path|glob|list>" [language]
```

- `<audio_or_video_path|glob|list>` — one of:
  - an absolute path to one supported file
  - a glob such as `C:\recordings\*.wav`
  - a semicolon-separated list such as `C:\recordings\1.wav;C:\recordings\2.wav`
- Video audio tracks are extracted automatically via ffmpeg, with a moviepy fallback
- `[language]` — optional language hint; defaults to `auto`. Common values: `Chinese`, `English`, `Japanese`, `Korean`, `Spanish`, `French`

Examples:

| Intent | Command |
| --- | --- |
| Auto-detect language | `scripts\run.ps1 "C:\recordings\meeting.mp3"` |
| Chinese audio | `scripts\run.ps1 "C:\recordings\讲座.m4a" Chinese` |
| Extract from video | `scripts\run.ps1 "D:\media\lecture.mp4"` |
| English podcast | `scripts\run.ps1 "D:\podcasts\ep01.mp3" English` |
| Batch by glob | `scripts\run.ps1 "C:\recordings\*.wav"` |
| Batch by list | `scripts\run.ps1 "C:\recordings\1.wav;C:\recordings\2.wav" English` |

Important:
- The `scripts\run.ps1` is the only supported interface for this skill. Do NOT try to call other scripts directly.
- The first call downloads the Qwen3-ASR model (~2 GB). The download runs in a detached background worker. Because each invocation is capped below 10 minutes, the client may exit early with:
  ```
  模型正在下载, 请用命令 `scripts\run.ps1 --continue` 继续运行
  ```
  When you see this, re-run the exact command it prints. Repeat until the transcript appears (usually 1-2 continuations on a first run).
- While a download is running, the client streams progress lines to stdout, for example:
  ```
  模型下载中 [████████░░░░░░░░░░░░]  42.3% | 1.1 GB/2.6 GB | 11.4 MB/s | 剩余约 2分10秒 | Qwen/Qwen3-ASR
  ```
  You MUST relay the latest progress line to the user as soon as it appears (percentage, downloaded/total size, speed and ETA), and keep re-invoking `scripts\run.ps1 --continue` so the user sees the progress advance until the download finishes. Never wait silently.
- The run.ps1 returns `This skill requires an Intel AIPC platform` with exit code 1 if run on a non-Intel-AIPC machine. Do NOT try to use this skill again on unsupported hardware.


### Interpreting the reply

The client prints a JSON block after the `=== RESULT ===` marker, for example:

```json
{
  "text": "今天的会议内容是...",
  "language": "Chinese",
  "load_seconds": 4.12,
  "inference_seconds": 3.87,
  "device": "GPU.0",
  "source_file": "C:\\recordings\\meeting.mp3",
  "source_format": ".mp3"
}
```

Fields:
- `text` — the transcription
- `language` — detected or requested language
- `load_seconds` / `inference_seconds` — timing breakdown
- `device` — OpenVINO device actually used (e.g. `GPU.0`, `CPU`)
- `source_file` / `source_format` — the original input

On failure the process exits non-zero and writes `[ERROR] <type>: <message>` to stderr.

## What this skill does NOT do

- Remote/headless control or microphone streaming (file-based only).
- Real-time / streaming transcription.
- Speaker diarization.
- Non-Intel-AIPC CPUs (hard check).
```

#### meeting-minutes-generator

- 来源: 项目生成
- 说明: Turn meeting transcripts, notes or chat logs into structured minutes with decisions and tracked action items. Triggers include 会议纪要, 会议记录, 纪要, 会议总结, meeting minutes, meeting notes.
- 路径: `C:\Users\lenovo\.workbuddy\project-resources\p_0aecfd6e2c5447a594cf5b914a8cfca0\skill_2095571554920247296\meeting-minutes-generator\SKILL.md`
- 附带文件: `references/action-items-guide.md`, `references/extraction-rules.md`, `references/minutes-structure.md`, `templates/minutes-template.md`

```markdown
# 会议纪要生成器（Meeting Minutes Generator）

把会议录音转写稿、聊天记录、零散笔记，一键整理成**结构化、有决议、可追踪待办**的会议纪要。

## 何时使用

当用户出现以下意图时触发本技能：

- 会议纪要、会议记录、会议总结、纪要、会议 memo
- 「帮我把这段会议内容整理成纪要」「根据录音整理会议记录」「这是会议转写稿，帮我提炼一下」
- 用户粘贴了会议转写文本、聊天记录、手写笔记，想成文

## 核心原则（务必遵守）

1. **先问一轮，别过度追问**：一次最多问清 3 件事——会议类型、输入形式（转写稿/聊天/笔记）、要不要带待办。用户说「随便/你定」时默认「项目周会 + 通用纪要 + 带待办」，直接产出。
2. **结构化**：严格套用标准结构（见下），不写流水账。
3. **提炼而非逐字**：抓结论、决议、行动项，讨论过程只留关键分歧和论据。
4. **待办可追踪**：每条待办 = 负责人 + 截止时间 + 动作，见 `@references/action-items-guide.md`。
5. **诚实**：没听清、没提到、归属不明的地方标注「待确认」，不编造负责人或数据。

## 工作流程

### 第 1 步：收集信息

一次问清（可合并成一句话）：

- **会议类型**：项目周会 / 产品评审 / 客户会议 / 决策会 / 1 对 1 / 其他
- **输入形式**：录音转写稿 / 聊天记录 / 手写笔记 / 口述
- **输出要求**：完整纪要 / 精简版 / 只要待办清单

随后请用户粘贴内容（转写稿、聊天记录、笔记），或口述会议经过。

### 第 2 步：结构化提取

从素材中抽取：主题、时间、参会人、议题、关键讨论、结论、决议、待办、风险。

### 第 3 步：提炼与归并

- 把讨论过程压缩为「背景 + 关键分歧 + 结论」。
- 决议写清「决定了什么、为什么」。
- 待办去重、合并，每条补全负责人 + 截止时间。

### 第 4 步：输出

- **默认输出 Markdown**，可直接粘贴到企微/飞书/邮件/语雀。
- 用户要求美观版时，生成单文件 HTML（内联 CSS，响应式）。
- 用户只要待办时，只输出「待办清单」表格。

## 会议纪要标准结构（通用）

```markdown
# 会议纪要：{会议主题}

## 基本信息
| 项目 | 内容 |
|---|---|
| 时间 | YYYY-MM-DD HH:MM |
| 地点/方式 | 会议室 A / 线上 |
| 主持人 | 姓名 |
| 参会人 | 姓名1、姓名2 |
| 记录人 | 姓名 |

## 会议议题
1. 议题一
2. 议题二

## 讨论要点
### 议题一
- 背景 / 关键分歧 / 结论

### 议题二
- ...

## 决议事项
- 决议 1：内容 + 依据
- 决议 2：...

## 待办事项
| # | 事项 | 负责人 | 截止时间 | 状态 |
|---|---|---|---|---|
| 1 | ... | 姓名 | MM-DD | 未开始 |

## 风险与备注
- 风险/遗留问题/需要上级支持的事项
```

## 会议类型差异

详见 `@references/minutes-structure.md`，核心：

- **项目周会**：重进展同步 + 风险 + 待办。
- **产品评审**：重结论（通过/需修改）+ 修改项清单。
- **客户会议**：重客户需求 + 承诺 + 后续动作。
- **决策会**：重决议 + 依据 + 反对意见记录。
- **1 对 1**：重目标对齐 + 反馈 + 成长计划。

## 提取规则与待办规范

- 要点提取规则：`@references/extraction-rules.md`
- 待办事项规范：`@references/action-items-guide.md`

## 边界

- 不编造参会人、决议、数据；缺失处标注「待确认」。
- 涉密会议内容提醒用户脱敏后再分发。
- 不替用户对他人做负面评价；讨论记录聚焦事实与结论。
```

#### threeui-integration

- 来源: 自建
- 说明: 拉取并引用 ThreeUI（threeui.com / @designcodeio/threeui）的 Three.js 组件与完整网站模板：只取 tarball 看结构（免装 54MB）、抽取 landing page 模板与排版预设（SYLVA/KAGE）、按其设计规范搭建网站。当用户说"引用 ThreeUI""用 ThreeUI 的模板""接 ThreeUI 组件""参考 threeui 做网站"时触发。
- 路径: `C:\Users\lenovo\.workbuddy\skills\threeui-integration\SKILL.md`

```markdown
# ThreeUI 组件 / 模板拉取与引用

## 一、先记住这些事实（2026-09-21 实测）

| 项 | 值 |
|---|---|
| 官网 / 仓库 | threeui.com ｜ github.com/MengTo/threeui（Community 开源版） |
| npm | `@designcodeio/threeui`（latest 1.2.0） |
| 依赖 | deps：`three128`→three@0.128、`three165`→three@0.165；peer：react/react-dom 18-19、three ≥0.149 |
| 体积 | tarball **42.4MB** / 解包 **55.3MB**（别盲目 npm install） |
| 内部结构 | `lib-dist/package-components/*.js`（React 组件）、`lib-dist/assets/landing-pages/*.html`（完整 HTML 模板）、`lib-dist/shaders/**`（GLSL/排版/配方） |
| 完整模板名 | kage.html、inner-green-3d.html、complete-shelf-v2.html、meng-to-sketchbook.html、bestsellers-book-showcase.html |
| 排版/配方源 | `lib-dist/shaders/landing-pages/pageRecipes.js`（4 套预设）、`pageTypography.js`（`usePageTypography`/`applyPageCustomization` 注入机制） |
| 组件命名示例 | AtTheHorizon、SylvaHero、SylvaLivingWorld、AnimatedTopDock、LumenCta、Structure Flow、CharacterCarousel、LiquidMetalButton、LandscapeScene、BrandOrbs |

## 二、只拉 tarball、在内存里看结构（零依赖，首选）

```js
// node 内置 zlib 就能解 tar；不必安装
const buf = Buffer.from(await (await fetch(tarballUrl)).arrayBuffer());
const tar = zlib.gunzipSync(buf);
// 逐条：header 512B → name(0-99) / size(124-135 八进制) / prefix(345-499)
// 数据起点 = off+512，长度 = size；下一条 = off + 512 + ceil(size/512)*512
```

- tarball URL 从 `https://registry.npmjs.org/@designcodeio%2Fthreeui` 的 `dist-tags.latest` → `versions[x].dist.tarball` 取。
- 只想看结构就打印条目名（726 条）；只想引用就**按需抽取**（landing-pages HTML + shaders/landing-pages + package-components），别全解。
- 可复用脚本思路见 `生成物/threeui-模板站/_probe/_filelist.txt`（完整清单留档）。

## 三、四套排版预设（真实数值，可直接引用）

`pageRecipes.js` 导出 `KAGE_TYPOGRAPHY` / `SYLVA_TYPOGRAPHY` / `BESTSELLERS_TYPOGRAPHY` / `COMPLETE_SHELF_TYPOGRAPHY`，每套含：字体栈表（heading/body）、字重表、`primaryColor`、字号三元组 `[min, base, max]`、字距三元组。

| 预设 | 主色 | 标题字号 | 字重 | 风格 |
|---|---|---|---|---|
| **SYLVA** | `#ffffff`（墨白，配 `--ink/--ink-soft/--ink-faint` 三级） | 40 / 63 / 92 | 300 | 暗底自然、轻字重大标题 |
| **KAGE** | `#e0231c` 朱红（+ `retone("#ff5a3c")` ember） | 30 / 46 / 72 | 400 | 编辑感、强对比 |
| **BESTSELLERS** | `#c3a47b` | 184 / 325 / 420（hero-word 巨字） | 500 | 巨字排版 |
| **COMPLETE_SHELF** | `#c87046` | 32 / 60 / 88 | 400 | 衬线（Iowan Old Style） |

- 缩放单位：`--u`，字号写作 `calc(92 * var(--u))`，再套 `clamp()` 做响应式。
- 注入机制：`:root` 变量 + 类规则覆盖 → "换预设即换风格"；还支持 `retone(color)`（按主色做 HSL 变换）与 `filter()`（hue-rotate/saturate/brightness）。这套思路可直接搬到自建站。

## 四、接入真正的组件

```bash
npm install @designcodeio/threeui
npx @designcodeio/threeui-cli add <pro-name>   # Pro 组件需会员
```
```jsx
import { AtTheHorizon } from "@designcodeio/threeui";
import "@designcodeio/threeui/style.css";
```
- 渲染完整 HTML 的组件：把 `node_modules/@designcodeio/threeui/lib-dist/assets/` 复制到 `public/`，或用 `sourceUrl`/`assetBaseUrl` 覆盖。
- 自建替代方案（无构建、离线）：**引用其设计规范（排版/配色 token）+ 资产命名**，交互用原生 CSS3D + rAF 自己实现 —— 见 `生成物/threeui-模板站/index.html`。

## 四·补、KAGE 模板实测解剖（2026-09-23 拉取 kage.html 243,963 B 亲测）

KAGE = 站点代号「Secret Pathways」，5 章节（hero / gate / pathways / lessons / eternity）。

| 层 | 真实实现 | 关键数值 |
|---|---|---|
| 滚动模型 | `progressFor(y)` 把 scrollY 映射成 **0→4 的章节级连续进度**（不是 0→1），anchors 强制单调递增 | 5 个机位 `data-cam="0..4"` |
| 3D 背景 | `WebGLRenderer` + `FogExp2` 指数雾做大气透视 + `PCFSoftShadowMap` | 雾色 `0x050a0e`、密度 `.0168`、背景 `0x060a0d`、clearColor `0x05070a` |
| 相机 | `PerspectiveCamera` | FOV 36°、near .35、far 220 |
| 前景 2.5D | 真实 PNG（temple-wall / sakura-branch 等 17 个 `.fg-el`），`data-fg-in="left/right"` 从边角进入，配 `fg-sway` 摆动 | 靠**遮挡**给深度，比纯 3D 便宜得多 |
| 缓动 | `damp(cur,to,rate,dt)=lerp(cur,to,1-exp(-rate*dt))` **帧率无关**；`smooth()` smoothstep；`easeOut=1-(1-t)^3` | 禁止裸 `lerp(a,b,0.1)` |
| 降级 | `WANT_POST` / `DPR_CAP` / `WANT_SHADOW` 三开关，`?nogl=1` 可彻底关 WebGL | 降级序：DPR → 后处理 → 阴影 → 纯 CSS |
| 装饰层 | `#vignette` 暗角 + `#grain` 颗粒 + `#cursor` 自定义光标 + `#pre` 预加载百分比 | 颗粒是为压暗部色带（banding） |
| 其他 | `mix-blend-mode` 2 处、`backdrop-filter` 4 处、`IntersectionObserver` 3 处、`mulberry32` + 值噪声做程序化木纹 | 无 gsap / lenis，全手写 |

- 配色 token：`--ink #05070a`、`--ink-2 #0a0e12`、`--bone #dfe7e0`、`--bone-dim #aab4ad`、`--muted #78837c`、`--vermilion #e0231c`、`--ember #ff5a3c`、`--gold #c9a24a`、`--ease cubic-bezier(.22,.61,.36,1)`。
- 字体：Onest + NotoJP + Wordmark（标题走日文）。
- **可迁移的通用结论**：深度靠「3D 背景（大气透视）+ DOM 文本中景 + 照片前景（遮挡+摆动）」三层预算；节奏靠章节级进度而非全局进度；手感靠帧率无关阻尼。

## 五、坑

- **别整包 install**：42MB tarball / 55MB 解包，先 tarball 探结构再决定。
- **许可**：Community 开源但字体/素材另有授权，商用前读包内 `LICENSE` / `ASSET-LICENSES.md` / `FONT-LICENSES.md`。
- **本机 shell 陷阱**：Git Bash 有时丢失 coreutils（`dirname/mkdir/head/cd` not found）→ 用 **node 绝对路径**跑脚本完成建目录/删文件/列目录，不要依赖 shell 内置命令。
- **别杜撰组件名**：组件/模板名一律取自 `package-components/` 与 `assets/landing-pages/` 真实清单。
- 引用其规范做站时，Google Fonts（Instrument Serif/Onest/Geist）在离线环境会降级到 Georgia/system-ui —— 给出 fallback 字体栈，别让排版塌掉。
```