物流工作台搭建

技能包 logistics-workbench · 用于 skillHub 发布与本地安装

基本信息

版本
v1.1.0
分类
-
文件数
7
包体合计
53,323 B

简介

文件清单

路径大小
SKILL.md13,077
assets/html-skeleton.html3,285
references/cloud-sync.md9,996
references/spec.md7,564
scripts/browser_storage.js5,274
scripts/cloud_sync.py4,007
scripts/scaffold.py10,120

SKILL.md 全文

下面是技能主文件的完整内容,可直接复制使用。
---
name: logistics-workbench
display_name: "物流工作台搭建"
display_name_en: "Logistics Workbench Builder"
description: 当需要搭建、调整或迁移「物流/统计/政策类个人工作台」时使用。基于「单文件 HTML + SVG 手写图表 + 资料库云同步」的标准架构,从零生成可离线运行、跨设备同步的网页版工作台,并支持按需增删改模块(数据看板、监测页、写作台、素材库、政策库等)。适用于物流统计、宏观经济、政策研究等多模块数据聚合场景。
description_zh: "物流统计工作台——单文件 HTML 零外链,模块可增删改,本地+云端双备份,一键发布网页版链接"
description_en: "Single-file HTML logistics workbench with pluggable modules, dual local+cloud backup (localStorage/IndexedDB/cloud DB/JSON), and one-click publish to library page"
category: Productivity
tags: [workbench, dashboard, logistics, statistics, single-file-html, cloud-sync, svg-chart]
version: 1.1.0
author: WorkBuddy
summary_zh: "从零搭建物流/统计类工作台:单文件 HTML 零外链、SVG 手写图表、模块可增删、四层数据备份、一键发布网页版"
summary_en: "Build a logistics/statistics workbench from scratch: single-file HTML, pluggable modules, SVG charts, 4-tier backup, one-click publish"
visibility: "public"
agent_created: true
labels:
  requires_api_key: "false"
---

# 物流工作台搭建 Skill

把「物流统计类个人工作台」的搭建经验沉淀为可复用的方法论:**配置驱动生成 → 模块可调整 → 数据四层备份 → 一键发布网页版**。

## When to Use

- 从零搭建一个物流/统计/政策类个人工作台
- 对已有工作台**增删改模块**(如把 A 模块迁到 B 分组下)
- 工作台数据需要与云端同步、跨设备使用
- 需要把本地工作台发布为网页版在线链接

## Core Capabilities

1. **单文件 HTML 交付**:CSS/JS 全内联、零外链、SVG 手写图表——长期存活不依赖任何 CDN
2. **模块可插拔**:按 `data-sub` / `id="page-xxx"` 注册模块,四步迁移(导航/页面/路由/调度)即可增删改
3. **数据四层备份**:localStorage(一级)+ IndexedDB(二级)+ 资料库云端数据库(三级)+ JSON 导出(四级)
4. **跨设备同步**:在线版自动双向同步;本地版可通过浏览器 localStorage 导出/恢复
5. **一键发布网页版**:`import_html.py` + `publish_page.py` 两步拿到 `workbuddy.link/p/<id>` 公开链接

---

## 一、标准交付架构

**必须是单文件 HTML**(CSS/JS 全内联、零外链、SVG 手写图表)——这是能长期存活的唯一形态:外链 CDN 一断,页面全废。

```
工作台.html (单文件)
├─ <style>              内联样式,OKLCH 主色 + 按模块切换强调色
├─ 侧边栏导航           分组 → section → 子项三级
├─ <section class="page" id="page-xxx">   每个模块一个独立 page
└─ <script>
   ├─ 数据层   STORAGE_KEY / getDefaultData / loadDB / saveDB
   ├─ 备份层   idbBackup / idbRestore / exportData / importData
   ├─ 云同步层 getSyncDbId / pushToCloudDB / pullFromCloudDB / initCloudSync
   ├─ 计算层   聚合、排序、统计(纯函数)
   └─ 渲染层   renderXxx(**渲染函数之间严禁互调**,统一由 renderPage 调度)
```

### 数据四层备份(本技能的核心要求)

| 层 | 位置 | 作用 | 失效场景 |
|---|---|---|---|
| 1 主存储 | `localStorage[STORAGE_KEY]` | 日常读写,最快 | 清缓存/换浏览器 |
| 2 二级备份 | IndexedDB `wb_logistics_db.data_backup` | localStorage 损坏时自动恢复 | 清站点数据 |
| 3 云端 | 资料库云端数据库(key/data/updatedAt) | 跨设备同步 | 需在线版访问 |
| 4 文件 | `导出备份 JSON`(顶栏按钮) | 人工归档/迁移 | 需手动操作 |

### 渲染函数禁止互调

**铁律**:所有渲染函数间不允许直接调用,必须由统一入口 `renderPage()` / `renderAll()` 调度——否则 `renderA()→renderB()→renderA()` 会栈溢出。

```javascript
// ✅ 正确:统一刷新入口
function renderAll() {
  renderDashboard();
  renderMonitor();
  renderPolicy();
}

// ❌ 错误:渲染函数互调(栈溢出)
function renderDashboard() {
  renderMonitor();  // 禁止!
}
```

---

## 二、快速开始

### 场景 A:从零搭建

```bash
python scripts/scaffold.py --name "物流统计工作台" \
  --modules "dashboard:我的工作台,news:资讯与数据,policy:政策与文件,writing:写作与监测,favorites:收藏与素材" \
  --sync-db-id "<YOUR_SYNC_DB_ID>" --storage-key "<YOUR_STORAGE_KEY>" \
  --out "./物流统计工作台.html"
```

生成后按需求填充各模块内容,再按「场景 C」发布。

### 场景 B:调整已有工作台(增删改模块)

调整流程**固定四步**,缺一不可:

1. **改导航**:在对应 `nav-section` 的 `nav-sub-list` 中增/删 `nav-sub-item`(`data-sub` 唯一,`onclick="navTo('分组','子项')"`)
2. **改页面**:新增/删除对应的 `<section class="page" id="page-xxx">`
3. **改路由**:`navTo`(子项 → 页面 + 子 Tab 切换)、`renderPage(page)`(页面 → 渲染入口)、`PAGE_TITLES` / `SUB_TITLES`
4. **改调度**:若模块从子 Tab 提升为独立 page,需清除原父级 Tab 列表中的该项(如 `['compare','calc','lpi']` → `['compare','calc']`)

> 迁移模块时**复用原 DOM 元素 ID**,渲染函数可零改动迁移。

### 场景 C:发布网页版 + 数据双备份

```bash
# 1) 发布到资料库(页面代码上线,绑定同步数据库)
python <library>/page/import_html.py --token-stdin "<工作台>.html" \
  --node-block-id <节点ID> --databases '[{"id":"<YOUR_SYNC_DB_ID>","name":"<YOUR_STORAGE_KEY>"}]'

# 2) 生成公开浏览链接
python <library>/page/publish_page.py --token-stdin --node-id <节点ID>
# → https://workbuddy.link/p/<节点ID>

# 3) 本地浏览器数据 → 云端(换设备/备份时用)
node scripts/browser_storage.js read <浏览器> <输出.json> <YOUR_STORAGE_KEY>
python scripts/cloud_sync.py upload <输出.json> --database-id <YOUR_SYNC_DB_ID> --key <YOUR_STORAGE_KEY>

# 4) 云端 → 本地
python scripts/cloud_sync.py download --database-id <YOUR_SYNC_DB_ID> --key <YOUR_STORAGE_KEY> --out <文件.json>
```

---

## 三、云同步机制(必须理解,否则会踩坑)

工作台内云同步代码依赖 `window.__SMART_PAGE__.database`,**只有资料库在线版页面才提供**;本地 `file://` 双击打开时该对象不存在,推送会静默失败并降级为离线模式。

| 打开方式 | 云同步 | 说明 |
|---|---|---|
| 资料库在线链接 | ✅ 自动 | 启动时拉取,改动后 0.8s 防抖推送,顶栏可手动同步 |
| 本地文件双击 | ❌ 无 | 数据只在浏览器 localStorage,需脚本备份或「导出备份」 |

**同步库结构**:字段 `key`(text) / `data`(text,存 `JSON.stringify(DB)`) / `updatedAt`(text,ISO)。
**DB_ID 优先级**:`localStorage['wb_sync_db_id']` > 代码内 `SYNC_DB_ID_DEFAULT`。
**SDK 适配注意**:`__SMART_PAGE__.database` 是 Proxy getter,对任何属性访问都返回 function(即使 SDK 还没加载)。所以 `typeof db.query === 'function'` 永远 true,**无法**用来判断 SDK 是否真的加载好了。要看 `window.__SMART_PAGE__.__queues__.database.length === 0`,或真去 `getSchema` 跑通。

---

## 四、定制调整清单

| 想改什么 | 改哪里 |
|---|---|
| 模块分组/顺序 | 侧边栏 `nav-group-label` + `nav-section` 顺序 |
| 模块强调色 | `#navSec-xxx{--nav-c:...}`(每个分组一个色) |
| 内置数据 | `getDefaultData()` 与 `provinceData` 等常量 |
| 图表 | 内联 SVG 手写函数(折线/柱状/饼图/雷达/多线) |
| 同步库 | `SYNC_DB_ID_DEFAULT` + 运行时 `localStorage['wb_sync_db_id']` |
| 备份周期 | `_doCloudSync()` 的防抖延时(默认 800ms) |

---

## 五、踩坑清单(血泪经验,务必遵守)

1. **改代码必须重新发布**:云端只同步业务数据,**不同步 HTML 代码**。本地改完必须重跑 `import_html.py`,否则在线版还是旧代码。
2. **`Edit` 的 `replace_all=true` 会替换所有匹配**:对 `</section>` 这类常见标签会导致重复插入。插入内容必须带**前后唯一上下文**。
3. **发布链接需要登录**:`workbuddy.link/p/<id>` 未登录会跳转官网首页,用户需登录同一 WorkBuddy 账号才能看到工作台。
4. **读取正在运行的浏览器 localStorage**:浏览器已运行时 `--remote-debugging-port` 无效(只对首个进程生效)。正确做法是复制其 `Local Storage/leveldb` 到临时 `--user-data-dir` 另起实例读取,**不打扰用户**。
5. **后台启动的浏览器会随命令结束被回收**:「启动→等端口→读取→关闭」必须写在**同一条命令**里。
6. **agent-browser 的 `connect` 仍要求自带 Chrome**:改用 Node 22 原生全局 `WebSocket` 直连 CDP,零依赖。
7. **资料库编辑器会注入标记**:从在线版导出的 HTML 含 `data-page-node-id`、`<!--pnid:-->`、外链 `inject.js`,落地本地前需清理(约占 36KB)。
8. **渲染函数禁止互调**(否则栈溢出):所有联动通过统一入口 `renderPage()` / `renderAll()` 调度。
9. **国内视觉规范**:增=红、降=绿(与欧美相反);货币用 ¥。
10. **时间不要手算**:用 `date` / `datetime` 现取,禁止硬编码时间戳。
11. **A 级评定标准多口径并存**:同一指标在年度通报与累计认定表里数值不同,以最近一次权威表格为准并在代码注释中注明口径来源。
12. **CDN 平台注入会污染云端 HTML**:下载比对时需剥 `data-page-node-id` / `<!--pnid:XXX-->` / `inject.js` 脚本,否则差异是噪声不是真版本差异。
13. **云端版本号不连续递增**:每次 `import_html.py` 会跳号(如 v14→v15),不要假设 v(n+1) 一定存在,必须用 CDN 枚举确认。
14. **HTML 文件名易错字**:`import_html.py` 路径里**不要写错字**,否则 `KS_IMPORT_ERR`。
15. **`ArrayBuffer` 没有 `.buffer` 属性**:只有 `Uint8Array` 等 TypedArray 才有。`new DataView(ab)` 直接接 ArrayBuffer,不要写 `ab.buffer`。
16. **SDK 记录字段映射**:API 返回 `record_id`,文档/示例可能写 `_id`,使用 `rec._id || rec.record_id || rec.id` 兼容三种命名。
17. **数据库 query 返回结果因 SDK 版本而异**:`data` 字段可能是 string 也可能是 object,解析时 `typeof d === 'string' ? JSON.parse(d) : d` 两种都试。
18. **分享链接节点只读**:链接带 `ext2=copy_link` 的节点无法 import / edit(`import_html` 报 56161、`create_page_transaction` 报 12607)。要回推云端就用自己拥有写权限的节点。
19. **新版发布系统入口不是 `index.html`**:部分节点入口是用户文件名且版本号为 `0`,CDN 枚举 `v1..vN` 全 404。改用 `list_page_publish_artifacts.py` + `download_page_artifacts.py --source publish`。
20. **跨设备「谁更新」必须做函数级 diff**:用户口头指定的"最新版"可能是分叉。用 `set(re.findall(r'function\s+(\w+)'))` 双向差集 + 关键锚点(`SYNC_DB_ID_DEFAULT` 是否有效、最新年份数据是否存在)判定,然后**并集合并**而不是覆盖。
21. **Python 写 HTML 必须 `newline='\n'`**:Windows 下默认把 LF 转成 CRLF,体积虚增且破坏行尾规范。
22. **工作区根目录的 HTML 会被平台自动注入**:写完立即被加 `data-page-node-id`(可达 20KB+)。要保留干净副本就写到 `.workbuddy/cache/` 之类的非根目录。

---

## 六、资源文件

| 路径 | 用途 |
|---|---|
| `scripts/scaffold.py` | 按模块配置生成工作台 HTML 骨架(含四层备份代码) |
| `scripts/browser_storage.js` | 通过 CDP 读取/写入指定浏览器的 localStorage |
| `scripts/cloud_sync.py` | 上传/下载工作台数据到资料库云端数据库 |
| `references/spec.md` | 详细设计规范、代码模板、校验清单 |
| `references/cloud-sync.md` | 资料库云同步机制详解 + 故障排查 |
| `assets/html-skeleton.html` | 工作台 HTML 骨架(最小可运行版本) |

---

## 七、交付标准

每次完成工作台搭建/调整后,必须交付:

1. 本地单文件 HTML(可双击打开、离线可用)
2. 网页版在线链接(`https://workbuddy.link/p/<id>`)
3. 数据双备份已验证(本地 JSON + 云端记录可查询到)
4. 修改前的文件备份(`xxx_backup_YYYYMMDD.html`)

---

## License & Visibility

`visibility: "public"` —— 允许其他用户通过 skillHub 安装复用。
</content>
</invoke>