打包产物发布为 npm 包 @talebook/candle-reader

[talebook]

Requested by Rex · project thread

背景

talebook 目前把阅读器的打包产物直接提交到 app/public/static/candle-reader/ 。每次升级或联调同步，都会在 talebook 的 git 历史里多留一份产物。计划改成：talebook 通过 npm 锁定版本，构建时再取用产物。这个 PR 先让 candle-reader 能发布成 npm 包；talebook 那边的改动等包首次发布后另开 PR。

Before： 推送 v* tag 只会产出 GitHub Release 上的 dist.zip 。

After： 推送日期版本 tag（如 v26.10.09 ）后，除了 dist.zip ，还会把 dist/ 发布为 npm 包 @talebook/[email protected] 。

关键改动

• package.json
  • 包名由 teader 改为 @talebook/candle-reader ，版本写成 26.10.9 。
  • 加 "files": ["dist"] ，发布的包里只有构建产物。
  • 补齐 license 、repository 、main / module 、publishConfig.access=public 。provenance 要求 repository 和实际发布的仓库一致。
  • 打包时已经把全部依赖内联进产物，所以依赖都移到 devDependencies ，宿主安装时不会再拉 vue 和 vuetify。package-lock.json 只多了对应的 dev 标记，没有升级任何依赖版本。
• .github/workflows/release.yml 新增「Publish to npm」步骤：
  • 版本号映射：tag 必须是 vYY.MM.DD 格式。semver 不允许前导零，所以发布时去掉前导零，例如 v26.10.09 发布为 26.10.9 。格式不符的 tag 直接报错。
  • 已经存在的 npm 版本会跳过。手动重跑旧 tag 时，只刷新 GitHub Release 附件。
  • 发布走 npm Trusted Publishing（GitHub OIDC），不需要 npm token。为此加了 id-token: write 权限，Node 从 18 升到 22，npm 升到 11.5.1 及以上。
• README.md ：新增「发版与 npm 包」一节。

验证

• npm run build ：通过。
• npm pack --dry-run ：23 个文件，全部是 dist/ 加上 LICENSE、README、package.json；压缩后 4.1 MB。
• npm run lint ：通过。
• Playwright e2e 全量：81 passed。因为云端环境的 Chromium 版本和锁定的 Playwright 不一致，用临时配置指定了 executablePath ，用例没有改。
• 版本映射脚本本地验证：
  • v26.10.09 → 26.10.9
  • v26.01.05 → 26.1.5
  • v26.10.09.1 和 build-3 报错
• release.yml 通过 YAML 语法检查。真实发布要等打 tag 时才能验证。

合并后需要手动做的事（只需一次）

Trusted Publishing 只能在包已经存在后配置，所以首次发布要手动：

1. 在合并后的 main 上执行 npm login && npm run build && npm publish --access public ，发布 26.10.9 。
2. 在 npmjs.com 打开 @talebook/candle-reader 的 Settings → Trusted Publisher → GitHub Actions，依次填写 talebook 、candle-reader 、release.yml 。
3. 补打 tag v26.10.09 并推送。发布步骤会发现 26.10.9 已存在而跳过，只上传 GitHub Release。

风险与兼容性

• 在第 2 步完成前推 tag，npm 发布会失败，而且会挡住后面的 Release 上传。
• 同一天只能发一版。第四段（如 v26.10.09.1 ）不能映射为不比原版本小的 semver，所以直接拒绝。
• 手动触发 workflow 时沿用「构建 HEAD、用最新 tag 版本号」的原有行为。npm 上同版本已存在就跳过，不会用旧版本号发布新内容。
• trigger-candle-reader.yml 和 talebook 现有的同步流程这次不改，等 talebook 切到 npm 包后一起删除。talebook 的同步 workflow 是按 tag 名字比较版本，换成日期 tag 不受影响。

方案

本仓库没有 design/ 方案规范。整体方案在 talebook 项目的对话中讨论，正式方案文档会附在 talebook 侧的 PR 里。

🤖 Generated with Claude Code

https://claude.ai/code/session_01LmqWSvDpsfVCnBeA1tRjLx

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T12:05:28.538760Z	0d1839d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0d1839d0e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".