yuque-cookie-plugin 0.1.0

package/docs/npm-release.md

@@ -0,0 +1,91 @@
+# npm 发布指南
+
+本项目正式分发建议走 npm，GitHub tarball 只作为临时备用安装方式。
+
+## 安装方式
+
+发布后用户只需要：
+
+```bash
+npm install -g yuque-cookie-plugin
+yuque-local auth login
+yuque-local doctor --json
+yuque-local skill install --json
+```
+
+无头环境使用：
+
+```bash
+yuque-local auth login --manual
+```
+
+## 发布前检查
+
+```bash
+npm run release:check
+```
+
+这个命令会执行类型检查、测试、构建、敏感信息扫描、npm 包名检查、`npm pack` 和临时 prefix 安装验证。
+
+确认 tarball 至少包含：
+
+- `bin/yuque-local.mjs`
+- `dist/`
+- `skills/yuque-cookie-plugin/`
+- `vendor/lake-editor/`
+- `README.md`
+- `docs/usage-zh.md`
+
+## 本地包安装预演
+
+不要直接污染全局环境，可使用临时 prefix：
+
+```bash
+tmp_prefix=$(mktemp -d /tmp/yuque-npm-prefix-XXXXXX)
+npm pack
+npm install -g --prefix "$tmp_prefix" ./yuque-cookie-plugin-0.1.0.tgz
+"$tmp_prefix/bin/yuque-local" --help
+"$tmp_prefix/bin/yuque-local" doctor --json
+```
+
+验证后删除本地 `.tgz`。
+
+## 正式发布
+
+首次发布前需要登录 npm：
+
+```bash
+npm login
+```
+
+注意：浏览器/邮箱里的登录 OTP 只能完成 CLI 登录，不一定能用于发布。npm 现在要求发布包时满足以下任一条件：
+
+- 账号已开启 2FA，并在发布时提供认证器或安全密钥生成的 OTP。
+- 使用创建时启用了 bypass 2FA 的 granular access token。
+
+发布：
+
+```bash
+npm publish
+```
+
+如果发布时报：
+
+```text
+Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.
+```
+
+说明当前账号只是登录了 npm CLI，但还没有满足发布级别的 2FA 要求。需要在 npm 账号安全设置中开启 2FA，或创建可发布本包的 granular access token。
+
+如果以后改成 scoped 包，例如 `@c-sunc6/yuque-cookie-plugin`，首次公开发布需要：
+
+```bash
+npm publish --access public
+```
+
+## 注意事项
+
+- 不要把真实 `_yuque_session` 或 `yuque_ctoken` 写入仓库。
+- 不要把 `~/.config/yuque-cookie-plugin/config.json` 打进包。
+- 发布前确认 `package.json` 的 `files` 字段包含运行时必需文件。
+- 当前 license 为 `UNLICENSED`，如果要开源给外部用户正式复用，发布前应决定是否改为 MIT、Apache-2.0 或其他许可证。

package/docs/real-acceptance.md

@@ -0,0 +1,146 @@
+# 真实语雀验收流程
+
+## 目的
+
+`real:acceptance` 用于手动验证真实语雀 Web Session 链路。它替代 `yuque-dl/test/realRequest.test.ts` 的思路，但不会进入默认 `npm test`。
+
+上线前最终验收必须使用真实语雀 URL、真实文档、真实图片/附件/音视频资源。Mock 数据只用于开发阶段单元测试，不能作为上线验收依据。
+
+原因：
+
+- 真实验收依赖网络、登录态和私有知识库权限。
+- 默认测试不能依赖真实 `_yuque_session` 或 `yuque_ctoken`。
+- 验收报告要能长期保存，便于回溯真实环境表现。
+
+## 前置条件
+
+先完成登录：
+
+```bash
+npm run yuque-local -- login
+```
+
+登录后先检查登录态：
+
+```bash
+npm run yuque-local -- auth-status https://www.yuque.com/<your-login>/<your-book>
+```
+
+`auth-status` 会记录最近保存、最近成功验证、最近失败验证时间。若返回 `valid: false`，需要重新运行 `login` 并由用户手动填写新的 Cookie。
+
+或使用环境变量：
+
+```bash
+export YUQUE_SESSION='your _yuque_session'
+export YUQUE_CTOKEN='your yuque_ctoken'
+export YUQUE_HOME_URL='https://www.yuque.com/your-login/'
+```
+
+不要把真实 Cookie 写入项目文件。
+
+## 整库验收
+
+```bash
+npm run real:acceptance -- \
+  --book-url https://www.yuque.com/<your-login>/<your-book> \
+  --dist-dir /tmp/yuque-real-acceptance
+```
+
+脚本会执行：
+
+- `inspect` 真实知识库。
+- 第一次 `download-book --incremental --quiet`。
+- 第二次 `download-book --incremental --quiet`，验证未变化文档跳过。
+- 检查 `index.md` 和 `progress.json` 是否生成。
+- 检查 `resources.files` 中的本地图片和附件是否存在。
+- 输出并保存 JSON 报告到 `reports/real-acceptance-*.json`。
+
+## 单篇或多篇验收
+
+```bash
+npm run real:acceptance -- \
+  --doc-url https://www.yuque.com/user/book/doc1 \
+  --doc-url https://www.yuque.com/user/book/doc2 \
+  --dist-dir /tmp/yuque-real-docs
+```
+
+报告会额外检查每个下载出的 Markdown 文件：
+
+- `download-doc.ok`
+- `download-doc.files`
+- `download-doc-file-1.ok`
+- `download-doc-file-1.size`
+- `download-doc-file-1.preview`
+- `download-doc.resources`
+- `download-doc-resource-1.ok`
+
+如果有多个 `--doc-url`，会按下载结果依次生成 `download-doc-file-N` 检查项。
+
+## 音视频和资源验收
+
+建议选择包含图片、附件、音频或视频卡片的真实文档单独跑：
+
+```bash
+npm run real:acceptance -- \
+  --doc-url https://www.yuque.com/user/book/doc-with-media \
+  --dist-dir /tmp/yuque-real-media
+```
+
+重点看报告里的：
+
+- `download-doc.warning_summary.total`
+- `download-doc.warning_summary.by_type`
+- `download-doc.warning_summary.retryable_resources`
+- `download-doc.resources.total`
+- `download-doc.resources.by_type`
+- `download-doc.resources.files`
+- `download-doc.retry`
+
+判断方式：
+
+- `warning_summary.total = 0`：主文档和资源都没有发现下载告警。
+- `warning_summary.by_type.media > 0`：音频或视频资源有下载失败，需要检查 `retryable_resources`。
+- `warning_summary.by_type.image > 0`：图片资源有下载失败。
+- `warning_summary.by_type.attachment > 0`：附件资源有下载失败。
+- `retryable_resources` 中的 `url` 是后续人工排查或单独补下载的依据。
+- `resources.files` 是已经成功落盘的资源清单，脚本会追加 `download-doc-resource-N` 或 `download-book-resource-N` 文件检查项。
+
+注意：`download-doc.retry` 只针对失败文档 URL；资源级失败目前通过 `warning_summary.retryable_resources` 汇总，还没有独立的资源重试命令。
+
+## 额外 Cookie
+
+如果需要企业私有语雀、公开密码或特殊访问 Cookie：
+
+```bash
+npm run real:acceptance -- \
+  --book-url https://www.yuque.com/user/book \
+  --cookie-key verified_books \
+  --cookie-value '<cookie-value>'
+```
+
+## 通过标准
+
+报告中的 `ok` 应为 `true`。
+
+整库验收至少应看到：
+
+- `inspect-book.ok: true`
+- `download-book-first.ok: true`
+- `download-book-incremental.ok: true`
+- `book-index.ok: true`
+- `book-progress.ok: true`
+
+如果 `warnings` 非空，说明主流程成功，但有图片、附件或音视频资源下载失败，需要人工评估是否接受。
+
+单篇资源验收至少应看到：
+
+- `download-doc.ok: true`
+- `download-doc-file-1.ok: true`
+- `download-doc.warning_summary.total: 0`，或能解释每一条资源告警
+
+## 注意
+
+- 这个脚本是手动验收，不属于默认自动化测试。
+- 它不会写入语雀线上文档，只读取并下载。
+- 输出目录如果未指定，会使用系统临时目录。
+- 报告里不会保存 Cookie 值。