# Sensa Basic 发布与更新备忘录

这份文档给下一次维护 `Sensa_basic` 的 Codex 或开发者使用。

目标：

- 更新插件代码后，重新生成可下载的 ZIP
- 更新宣传页面的下载包和文案
- 更新飞书使用手册
- 避免遗漏版本号、链接、资源文件这些细节

## 1. 关键目录

- 插件仓库：`/Users/ruska/projects/chrome 插件/Sensa_basic`
- 打包产物目录：`dist/`
- 宣传页源码：`site/`
- 宣传页下载目录：`site/downloads/`
- 发布脚本：`scripts/package-release.mjs`
- 宣传页部署脚本：`scripts/deploy-site.mjs`
- 飞书手册源文件：`tmp/sensa-usage-manual.md`

## 2. 先看哪些文件

每次准备发布前，先检查这些文件：

- `manifest.json`
  - 插件版本号在这里
- `scripts/package-release.mjs`
  - ZIP 文件名按 `manifest.version` 生成
- `scripts/deploy-site.mjs`
  - 这里目前写死了 ZIP 文件名
- `site/index.html`
  - 页面里的下载链接和安装说明里也写死了 ZIP 文件名
- `tmp/sensa-usage-manual.md`
  - 飞书使用手册的本地 Markdown 源

## 3. 标准发布流程

### 第一步：确认版本号

如果这次是一个新的发布版本，先修改：

- `manifest.json` 中的 `version`

注意：

- 当前 `scripts/deploy-site.mjs` 和 `site/index.html` 里有 `Sensa_basic_v1.0.0.zip` 这种硬编码
- 如果版本号升级，比如改成 `1.0.1`，必须同步修改这些地方

建议检查：

```bash
rg -n "Sensa_basic_v|1\\.0\\.0|LXPSdz0FeoWkr7xXT4qcAnrMn1b" manifest.json scripts site tmp
```

## 4. 重新打包 ZIP

在仓库根目录执行：

```bash
node scripts/package-release.mjs
```

这个脚本会自动做几件事：

1. 运行检查脚本 `node scripts/check.mjs`
2. 读取 `manifest.json` 里的版本号
3. 生成发布摘要到 `dist/release-summary-v<version>.md`
4. 生成 ZIP 到 `dist/Sensa_basic_v<version>.zip`

发布完成后，重点确认：

- `dist/Sensa_basic_v<version>.zip` 存在
- 测试没有报错

## 5. 更新并发布宣传页

如果只是重新上传同版本 ZIP，也要执行一次站点部署，让 `site/downloads/` 同步最新压缩包。

执行：

```bash
node scripts/deploy-site.mjs
```

这个脚本当前会：

1. 把 `dist/Sensa_basic_v1.0.0.zip` 复制到 `site/downloads/Sensa_basic_v1.0.0.zip`
2. 用 Wrangler 发布 `site/` 到 Cloudflare Pages

当前 Pages 项目名：

- `sensa-basic`

已知线上地址：

- 主地址：`https://sensa-basic.pages.dev`
- 统计看板：`https://sensa-basic.pages.dev/stats/`
- 原始统计接口：`https://sensa-basic.pages.dev/api/stats`

部署成功后，Wrangler 还会返回一个本次部署的预览地址。

如果这次改动涉及统计能力，还要一起检查：

- `wrangler.jsonc`
- `functions/`
- `site/analytics.js`
- `site/stats/index.html`

## 6. 更新宣传页文案时改哪里

常改文件：

- `site/index.html`
- `site/styles.css`

当前页面里比较关键的内容：

- ZIP 下载链接
- 飞书手册链接
- 统计看板入口
- 安装说明
- 联系方式和二维码

如果你更新了二维码或图片资源，还要同步检查：

- `assets/`
- `site/assets/`

## 7. 更新飞书手册

本地 Markdown 源文件：

```bash
tmp/sensa-usage-manual.md
```

先修改这个文件，再用 `lark-cli` 覆盖飞书文档。

当前已知飞书文档 token：

- `LXPSdz0FeoWkr7xXT4qcAnrMn1b`

覆盖更新命令：

```bash
lark-cli docs +update --as user --api-version v2 --doc 'LXPSdz0FeoWkr7xXT4qcAnrMn1b' --command overwrite --doc-format markdown --content '@./tmp/sensa-usage-manual.md' --json
```

如果以后要新建一个新的飞书文档，可以用：

```bash
lark-cli docs +create --as user --api-version v2 --parent-position my_library --doc-format markdown --content '@./tmp/sensa-usage-manual.md' --json
```

更新后建议人工确认两件事：

1. 飞书页面是否成功覆盖
2. 宣传页里的手册链接是否还是当前有效链接

## 8. 一次完整更新的推荐顺序

推荐按这个顺序执行：

1. 改代码或文案
2. 如果需要，更新 `manifest.json` 版本号
3. 如果版本号变了，更新：
   - `scripts/deploy-site.mjs`
   - `site/index.html`
   - `tmp/sensa-usage-manual.md` 里的安装包名
4. 执行：

```bash
node scripts/package-release.mjs
```

5. 如需更新飞书手册，执行：

```bash
lark-cli docs +update --as user --api-version v2 --doc 'LXPSdz0FeoWkr7xXT4qcAnrMn1b' --command overwrite --doc-format markdown --content '@./tmp/sensa-usage-manual.md' --json
```

6. 发布宣传页：

```bash
node scripts/deploy-site.mjs
```

7. 最后检查：
   - `dist/` 里的 ZIP 是否正确
   - `https://sensa-basic.pages.dev` 下载是否正常
   - `https://sensa-basic.pages.dev/stats/` 是否能打开
   - `https://sensa-basic.pages.dev/api/stats` 是否返回 JSON
   - 飞书手册是否已更新
   - 插件本地加载是否正常

## 9.1 站点统计怎么查看

现在有两种查看方式：

1. Cloudflare 官方面板
   - 适合看 Pages / Web Analytics 里的站点访问趋势
   - 主要看站点访问，不看自定义下载点击逻辑

2. Sensa 自己的统计看板
   - 看板地址：`https://sensa-basic.pages.dev/stats/`
   - 原始接口：`https://sensa-basic.pages.dev/api/stats`
   - 这里可以看：
     - 累计 PV
     - 累计近似 UV
     - 累计下载点击
     - 累计近似下载用户
     - 今日数据
     - 最近 30 天逐日趋势

说明：

- 这里的 UV / 下载用户是基于浏览器和 IP 指纹的近似值，适合看趋势，不等同于严格实名去重
- 下载统计不是靠 Cloudflare Web Analytics，而是靠 Pages Functions + KV 实现的

## 9. 发布前检查清单

- `git status --short`
  - 确认没有不想带上的临时文件
- `node scripts/check.mjs`
  - 确认测试和语法检查正常
- `manifest.json`
  - 版本号是否正确
- `site/index.html`
  - 下载链接是否正确
- `scripts/deploy-site.mjs`
  - ZIP 文件名是否和当前版本一致
- `tmp/sensa-usage-manual.md`
  - 是否需要同步更新手册说明

## 10. 当前已知坑

### 1. ZIP 文件名有硬编码

这两个地方不是自动跟随 `manifest.json` 的：

- `scripts/deploy-site.mjs`
- `site/index.html`

所以版本升级时很容易漏改。

### 2. 飞书链接也是固定值

宣传页里的飞书手册链接现在是固定的，如果换了文档，需要同步更新：

- `site/index.html`

### 3. 站点发布依赖本机环境

需要本机能正常使用：

- `node`
- `npx`
- `wrangler`
- `lark-cli`（仅飞书更新时）

## 11. 下一步可以继续优化的地方

如果以后要减少手工步骤，优先优化这两个点：

1. 让 `scripts/deploy-site.mjs` 自动读取 `manifest.json` 版本号，而不是写死 `1.0.0`
2. 让 `site/index.html` 的下载链接由构建脚本自动注入，而不是手改

这样下次发布就更稳，也更适合交给 Codex 直接自动完成。
