WorkBuddy 个人工作台搭建方法论

本技能服务于"想用 WorkBuddy 搭一个个人工作台"的创作者：一个网址进去，自己的工具、台账、后台、导览、发布页都在里面，风格统一、操作顺手。所有方法均经一个真实运营的休闲农庄工作台（多页面、统一外壳 v7、子页内嵌、双站联动）验证，重编码为通用工作流。

先看第一节那张表——它决定这件事该不该由本技能接、接哪一套。判断错了后面全白做。

> 使用前提（重要）：本技能给的是"方法 + 可直接套用的模板"，不是替你搭好。涉及具体路径、域名、页面清单，必须基于使用者自己的目录重填，禁止照搬示例里的占位值当真路径。

一、怎么激活：用户这么说时，接这一套

不需要用户点名"用那个工作台技能"——判断依据是他要做的事，不是他有没有提到技能名。
命中任意一行 ⇒ 直接用本技能，并在第一句说清你打算怎么做。

别激活的情况（激活了是给人添麻烦）：只有一个静态页（直接写 CSS）；项目用了 React / Vue 等框架（外壳会跟渲染打架）；
只问"div 怎么居中"这类单点语法；用户在弄别的东西（文案、脚本、数据表）顺口提到"页面"。

⚡ 快速开始（5 分钟）

1. 改配色：打开 assets/shell-template.html，只动 :root 里的 CSS 变量（主色 / 底色 / 分隔线），全站换肤只改这一处。
2. 先预演：python assets/build.py 你的页面目录 --dry-run —— 只看会发生什么，不写入任何文件。
3. 真注入：去掉 --dry-run 再跑一遍，批量注入 + 自动备份 + 结尾自动自检。
4. 看报告：显示"全部通过"再发布；有失败会逐条给中文原因 +「下一步怎么做」，照着改完重跑即可（幂等，不叠加）。
5. 看效果：打开 assets/workbench-preview.svg，那是注入后应该长成的样子。

> 两个脚本都纯本地运行：不联网、不上传、不读取你指定文件与补丁以外的内容。

二、核心架构：三件套

一个稳健的个人工作台由三件套构成，缺一件都会后期返工：

1. 统一外壳补丁 + 幂等注入器（assets/shell-template.html + assets/injector.py）
   一份补丁源（含 <style id="wb-shell"> 与 <script id="wb-shell-js">），一个注入脚本把补丁批量注入所有页面。注入是幂等的：先删旧块再追加，自动时间戳备份，可反复跑不堆积；备份留新清旧（默认每文件只留最近 5 份），不会越积越多。详见 references/shell-injection.md。

2. 子页内嵌脚本（assets/inline-example.js + references/inline-embed.md）
   首页用 iframe 把子页嵌进来，左侧菜单常驻、右侧换内容。关键是 isHomeShell() 判定与跨域收侧栏的坑——踩过一次"首页被误判成子页、菜单叠两层"。

3. 发布纪律（references/publish-discipline.md）
   WorkBuddy 按"目录绝对路径"认应用，不是按 appId。目录挪位置 = 新建应用 + 新域名（多一段随机后缀）。改完先同步回原路径再发，发完必须 curl 验收。这条是很多人反复踩、反复丢域名的根因。

三、工作流

1. 先定骨架：规划页面清单（首页 + N 个子页），确定哪个是"首页壳"（含左侧菜单 #snav）。
2. 配色系统先落：用 references/color-system.md 的明度分层法，把主色/底色/分隔线/正文/次要全写成 CSS 变量（:root），全站只改一处变量就换肤。
3. 写外壳补丁：基于 assets/shell-template.html 改标题栏（吸顶）、侧栏（分组+当前项高亮）、内容区（透明露底图），挂 body 下不挂 #app 里。
4. 注入外壳：不用自己写脚本——单个文件用 assets/injector.py，整个目录用 assets/build.py。两者都内置中文报错、自动备份、--dry-run 预演、备份留新清旧（--keep N），跑完还会自检块有没有重复堆积。
5. 内嵌脚本：首页引入 assets/inline-example.js，实现"首页内嵌、子页 ?embed=1 收侧栏、统一入口只首页开"。
6. 一键构建：同步内嵌脚本 → build.py 批量注入并自检（自动清掉多余旧备份）→ 处理缓存穿透戳 → 重建本地验证副本（域名本地化）。
7. 发布 + curl 验收：从固定原路径发布，发完抓线上页比对字节数、grep 改动标记、确认被删元素计数为 0。

三点五、介入的分寸（怎么接话，别抢活也别装看不见）

开口第一句说清你要干什么，用户才知道要不要拦你：

> 「这是多页工作台的事，我用统一外壳那套处理：先预演看会改哪些页 → 你确认后真写入 → 写完自动自检。」

不要做：不打招呼就批量改几十个文件（哪怕幂等、有备份，也要先给影响清单）；
用户只问"为什么"时直接动手改（他要的是解释）；把"预演通过"说成"已完成"（预演没写入任何文件）。

四、红线（搭工作台避坑）

• JS 还在引用的 DOM 元素绝不能删。要隐藏用 display:none/visibility:hidden 当状态信号源，别从 DOM 移除——否则引用它的脚本抛 null，页面其它功能跟着挂，且报错只在控制台、页面看着正常，最易漏。
• 判定首页绝不能用 .sidebar/.hgside 这类类名——外壳本身可能给首页也建了同名节点，拿它当依据会把首页误判成子页，菜单叠两层。
• 发布路径一个字符不许改。挪目录 = 新应用 = 新域名 = 你分享出去的链接全部失效（指向老域名、老域名不更新）。
• 注入顺序有铁律：先注入外壳，再注入其它脚本（如背景音乐）。反过来跨行正则会吞掉后来插的 <script>，表现为"某功能突然没了"且难复现。

用户没提、但听到这三句话必须当场拦一下（真踩过）：

1. "把目录挪个位置 / 换台电脑 / 重新整理文件夹" → 挪目录 = 新应用 = 新域名，已分享的链接全部指向老域名、且不再更新。
2. "这个元素删了吧" → 先问它是否被 JS 引用（第 1 条），删了同页其它功能会一起挂。
3. "把页面打包发给别人" → 先清 .bak-wb-*，旧版本会被一起带走。

敏感信息处理（发布 / 分享前必读）

• 本技能自身不含任何密钥、真实域名、个人绝对路径、手机号——示例里出现的都是占位值（如 xxx.app.workbuddy.host）。
• 你自己的配置别硬编码进模板：域名、路径、表名写成占位符或环境变量，别写死在 shell-template.html 里，否则分享出去等于把家底给人。
• 发布前搜一遍：在目录里查一次真实域名、手机号、个人路径、密钥——包括 .bak-wb-* 备份文件，它们同样会被打包带走。
• 备份会留新清旧，但发布前仍要确认：注入器默认每文件只留最近 5 份 .bak-wb-*（--keep N 可改），
  不会无限堆积；但交付或发布前仍看一眼汇总里的"清理旧备份"，确认没有残留旧内容混进产物。

五、references 调用指引

按用户实际问题加载对应文档（按需取用，不要一次性全读）。第一节表格的最后一列已标明每条该读哪份，照着取即可：

• references/framework-overview.md — 整体架构、目录结构示例、三件套职责与协作关系。
• references/shell-injection.md — 统一外壳注入法：补丁怎么写、注入器怎么跑、幂等/备份与留新清旧、构建脚本别用 tail 截断、注入顺序铁律、缓存穿透戳。
• references/color-system.md — 配色系统：明度分层铁律、CSS 变量方案、深浅主题适配。
• references/inline-embed.md — 子页内嵌模式：isHomeShell 判定、?embed=1 收侧栏、统一入口一层、高亮只动子项。
• references/publish-discipline.md — 发布与域名纪律：路径绑死、同步回原路径、curl 验收、生成新域名的处理。

六、assets 清单

• assets/shell-template.html — 通用化外壳补丁模板（CSS 变量配色，去私有信息，可直接改）。
• assets/injector.py — 单文件幂等注入器：中文报错 + 自动备份 + --dry-run 预演 + 备份留新清旧（--keep）。
• assets/build.py — 一键构建：扫描目录 → 批量注入 → 备份 → 留新清旧 → 自动自检（块是否唯一、备份是否齐全）。
• assets/inline-example.js — 子页内嵌判定与统一入口示例（isHomeShell + embed 收侧栏）。
• assets/workbench-preview.svg — 注入后的效果示意图（标题栏 / 侧栏 / 内容区 + 配色标注）。

来源与授权：方法提炼自一个真实运营的休闲农庄工作台实践（统一外壳 v7、子页内嵌、双站发布），经重编码为通用工作流，供 WorkBuddy 用户复用。原项目中的真实域名、绝对路径、具体页面清单均已抽离为示例占位，使用者按自身目录重填。