@skrillex1224/chrome-media-publish-extension 0.1.1

package/README.md

@@ -0,0 +1,490 @@
+# chrome-media-publish-extension
+
+`@skrillex1224/chrome-media-publish-extension` 是 Chrome extension 场景下的媒体发布业务内核。它不是正式插件 UI，而是给第三方 Chrome 插件使用的 npm 包。
+
+当前版本提供干净的包框架、公开 API、协议校验、状态码、adapter 目录、本地测试夹具，以及 Douyin 图文/视频、Bilibili 图文/视频 adapter。
+
+旧工程只作为平台行为和历史 E2E 经验参考，不作为代码复用来源：
+
+```text
+/Users/galedekarios/Documents/Codex/2026-07-01/wechatsync-wechatsync-https-github-com-wechatsync/work/Wechatsync/article-publish-extension
+```
+
+## 安装
+
+```bash
+npm install @skrillex1224/chrome-media-publish-extension @skrillex1224/extension-toolkit
+```
+
+Chrome extension 不能直接在浏览器里裸 import npm 包，宿主插件需要用 Vite、esbuild、Webpack、Rollup 等 bundler 将业务代码打包进 extension。
+
+`@skrillex1224/extension-toolkit` 是 peer dependency。发布本包前，需要先发布对应版本的 toolkit；本仓库本地开发使用 `file:../extension-toolkit` 作为 dev dependency。
+
+## 测试插件 UI
+
+本仓库自带一个 debug-first 的 Chrome 测试插件，用来真实验证 npm 包和 adapter。它不是正式产品插件，也不会进入 npm 发布包。
+
+目录：
+
+```text
+tests/extension/app      # React/Vite 测试 UI 源码
+tests/extension/dist     # npm run test:pack 后的可安装插件
+```
+
+打包：
+
+```bash
+npm run test:pack
+```
+
+安装：
+
+1. 打开 Chrome Extensions。
+2. 选择 Load unpacked。
+3. 选择 `tests/extension/dist`。
+
+入口：
+
+- 点击插件图标会打开 Chrome side panel。
+- side panel 用于选择平台、检测登录态、选择媒体并创建单平台发布任务。
+- `app/index.html` 是完整 debug console，包含媒体库、新建媒体、批量导入、发布任务详情和运行日志。
+- `e2e.html` 保留 `window.__mediaPublishE2E` 兼容入口，便于 CDP/控制台直接调用。
+
+测试 UI 的核心规则：
+
+- 平台单选，未登录平台不能发布。
+- 同一平台同一时间只允许一个发布任务。
+- 发布前会再次 `checkAuth`，避免账号状态和 UI 缓存不一致。
+- 每个任务项按 `checkAuth -> publish -> getStatus` 执行。
+- 成功、审核中、公开链接同步都算任务项完成，不会卡在“发布中”。
+- 只有 `state === 50000` 的失败可重试项允许重试。
+- 每次 API 调用都会截取 `Logger.exportLogs()` 增量并写入任务项，任务详情页可导出 JSON 排障。
+
+发布边界检查：
+
+```bash
+npm pack --dry-run
+```
+
+预期 tarball 只包含 `README.md`、`dist/index.js`、`dist/index.js.map`、`index.d.ts`、`package.json`。测试 UI、React、Ant Design 和打包产物都不应出现在 npm tarball 中。
+
+## Runtime 原则
+
+详细决策记录见：
+
+```text
+../docs/superpowers/specs/2026-07-16-media-publish-runtime-decisions.md
+```
+
+核心原则：
+
+- 不点击平台发布 UI。
+- 能通过公开前端 API 完成的，就用 API。
+- 能不开 tab 的，不开 tab。
+- 必须使用页面 runtime 时，才通过 `Runtime.tabs.createManagedTab()` 打开受管 tab。
+- 所有受管 tab 必须进入 tab group，用完关闭。
+- 验证码、二次验证、扫码确认、账号风控不能绕过，统一映射为 `SecurityCheckRequired`。
+
+当前没有为了 Douyin/Bilibili 而必须补到 toolkit 的能力缺口。`withDouyinHeaderRules()`、`withBilibiliHeaderRules()`、`withCreatorTab()` 和 `withBilibiliPage()` 暂时保留在平台目录内；它们是业务包内部组合 helper，不是新的 toolkit primitive。
+
+## 快速接入
+
+```js
+import { useMediaPublishExtension } from '@skrillex1224/chrome-media-publish-extension';
+
+const {
+    publish,
+    checkAuth,
+    getStatus,
+    Constants,
+} = useMediaPublishExtension();
+
+const auth = await checkAuth({
+    platform: 'douyin',
+});
+
+const result = await publish({
+    platform: 'douyin',
+    media: {
+        type: 'album',
+        title: '人为什么会饿',
+        intro: '饥饿是一套由大脑、胃肠、血糖、激素和习惯共同参与的提醒系统。',
+        cover: 'https://example.test/cover.jpg',
+        tags: ['健康', '科普'],
+        content: [
+            { url: 'https://example.test/1.jpg' },
+            { url: 'https://example.test/2.jpg' },
+        ],
+    },
+});
+
+if (result.code === Constants.StatusCode.Success && result.data.statusRef) {
+    const status = await getStatus({
+        platform: 'douyin',
+        statusRef: result.data.statusRef,
+    });
+    console.log(status);
+}
+```
+
+## 公开 API
+
+包只公开一个入口：
+
+```js
+import { useMediaPublishExtension } from '@skrillex1224/chrome-media-publish-extension';
+```
+
+`useMediaPublishExtension()` 返回：
+
+```ts
+{
+  publish(input): Promise<ApiResult<PublishData>>
+  checkAuth(input): Promise<ApiResult<CheckAuthData>>
+  getStatus(input): Promise<ApiResult<GetStatusData>>
+  Constants
+}
+```
+
+不公开 toolkit、runtime、logger、adapter registry，也不公开 `createMediaPublishApi()`。
+
+### `checkAuth(input)`
+
+检查指定平台是否已登录。
+
+```ts
+type CheckAuthInput = {
+  platform: string
+  timeoutMs?: number
+}
+
+type CheckAuthData = {
+  isAuthenticated: boolean
+  platform: string
+  accountId?: string
+  username?: string
+  avatar?: string
+  reason?: string
+}
+```
+
+### `publish(input)`
+
+发布内容到指定平台。
+
+```ts
+type PublishInput = {
+  platform: string
+  media: Media
+  timeoutMs?: number
+}
+
+type PublishData = {
+  platform: string
+  statusRef?: PublishStatusRef
+  reason?: string
+}
+```
+
+`publish()` 成功只代表平台接受了提交，并返回可以轮询的 `statusRef`，不代表内容一定已经公开。发布阶段不返回顶层 `postUrl`；如果 adapter 在发布时拿到了候选链接，应写入 `statusRef.url`。真正公开链接以 `getStatus().data.postUrl` 为准。
+
+### `getStatus(input)`
+
+查询发布状态。
+
+```ts
+type GetStatusInput = {
+  platform: string
+  statusRef: PublishStatusRef
+  timeoutMs?: number
+}
+
+type GetStatusData = {
+  platform: string
+  statusRef: PublishStatusRef
+  postUrl?: string
+  rawStatus?: string | number
+  checkedAt?: number
+  reason?: string
+}
+```
+
+`reviewing`、`rejected`、`published` 都表示查询动作本身完成。宿主插件应根据 `code` 和 `state` 决定是否继续轮询、重试或提示用户处理。
+
+## Media 协议
+
+Media 协议使用 `type + content`。包只消费当前协议字段；如果调用方额外带了旧字段或业务自定义字段，核心校验会忽略它们，不做兼容映射。
+
+### Markdown 文章
+
+```js
+{
+    type: 'article',
+    title: '人为什么会饿',
+    intro: '摘要或简介',
+    cover: 'https://example.test/cover.jpg',
+    tags: ['健康', '科普'],
+    content: '# 人为什么会饿\n\n正文 markdown'
+}
+```
+
+### 图集/图文
+
+```js
+{
+    type: 'album',
+    title: '人为什么会饿',
+    intro: '图文描述',
+    cover: 'https://example.test/cover.jpg',
+    tags: ['健康', '科普'],
+    content: [
+        { url: 'https://example.test/1.jpg' },
+        { url: 'https://example.test/2.jpg' }
+    ]
+}
+```
+
+### 视频
+
+```js
+{
+    type: 'video',
+    title: '人为什么会饿',
+    intro: '视频描述',
+    cover: 'https://example.test/cover.jpg',
+    tags: ['健康', '科普'],
+    content: 'https://example.test/video.mp4'
+}
+```
+
+## PublishStatusRef
+
+`PublishStatusRef` 是 `publish()` 返回、`getStatus()` 消费的持久引用。
+
+```ts
+type PublishStatusRef = {
+  platform: string
+  type: 'article' | 'album' | 'video'
+  id: string
+  url?: string
+  accountId?: string
+  meta?: Record<string, string | number | boolean | null>
+}
+```
+
+`url` 是已知或可推导的公开链接候选，不是状态权威来源。是否真正公开必须看 `getStatus()`。
+
+## 支持平台
+
+### Douyin
+
+`platform: 'douyin'` 当前支持：
+
+| 能力 | 支持情况 | 说明 |
+|---|---|---|
+| `checkAuth` | 支持 | 静默请求创作者中心用户接口，不打开 UI |
+| `publish` 图文 | 支持 | `media.type: 'album'`，`content` 是图片 URL 数组 |
+| `publish` 视频 | 支持 | `media.type: 'video'`，`content` 是视频 URL |
+| `getStatus` | 支持 | 查询创作者中心详情接口，必要时兜底 mget |
+| markdown 文章 | 不支持 | Douyin adapter 不支持 `type: 'article'` |
+| `onEvent` | 不支持 | 遇到验证码/风控直接返回 `SecurityCheckRequired` |
+
+字段映射：
+
+| Media 字段 | Douyin 图文 | Douyin 视频 |
+|---|---|---|
+| `title` | 图文标题段 | `item_title`，同时作为文案第一行 |
+| `intro` | 图文文案主体，不截断 | `caption` 文案主体，不截断 |
+| `tags` | 解析为 Douyin 话题，写入 `text_extra/challenges` | 解析为 Douyin 话题，写入 `text_extra/challenges` |
+| `cover` | 当前使用第一张图作为封面 | 可选自定义封面，上传到 ImageX |
+| `content` | `Array<{ url: string }>` 图片 URL 列表 | 视频 URL 字符串 |
+
+Douyin `publish()` 成功返回的 `statusRef.url` 是可推导候选：
+
+- 图文：`https://www.douyin.com/note/<id>`
+- 视频：`https://www.douyin.com/video/<id>`
+
+是否真正公开必须以后续 `getStatus()` 返回为准。`spd authorization rejected` 会被视为状态接口临时不可读，adapter 会短延迟复查一次；仍失败时返回 `PublicUrlSyncing`，并在 `data.reason` 保留原始原因。
+
+### Bilibili
+
+`platform: 'bilibili'` 当前支持：
+
+| 能力 | 支持情况 | 说明 |
+|---|---|---|
+| `checkAuth` | 支持 | 请求 B 站 nav 接口并读取 `bili_jct` cookie |
+| `publish` 图文 | 支持 | `media.type: 'article'`，`content` 是 markdown 字符串 |
+| `publish` 视频 | 支持 | `media.type: 'video'`，`content` 是视频 URL |
+| `getStatus` 图文 | 支持 | 查询空间动态流和动态详情 |
+| `getStatus` 视频 | 支持 | 查询创作中心稿件状态 |
+| 图集/图片集 | 不支持 | Bilibili adapter 不支持 `type: 'album'` |
+| `onEvent` | 不支持 | 遇到验证码/风控直接返回 `SecurityCheckRequired` |
+
+字段映射：
+
+| Media 字段 | Bilibili 图文 | Bilibili 视频 |
+|---|---|---|
+| `title` | opus 标题 | 视频标题和分 P 标题 |
+| `intro` | 当前不单独提交 | 视频 `desc`，不截断 |
+| `tags` | 写入图文业务 tags | 逗号拼接为投稿 `tag`，最多取前 10 个 |
+| `cover` | 上传为图文封面 | 上传为视频封面 |
+| `content` | markdown 转 B 站 opus paragraphs | 视频 URL 字符串，下载后 multipart 上传 |
+
+Bilibili 图文 markdown 转换会尽量保留标题、段落、粗体、斜体、删除线、下划线 HTML、inline code、链接、图片、引用、列表、任务列表、代码块、表格和分割线。B 站接口没有原生支持的格式会转换为可读文本。
+
+Bilibili `publish()` 成功返回的 `statusRef.url` 是候选公开链接：
+
+- 图文：`https://www.bilibili.com/read/cv<cvid>` 或 `https://t.bilibili.com/<dynamic_id>`
+- 视频：`https://www.bilibili.com/video/<bvid>`
+
+是否真正公开必须以后续 `getStatus()` 返回为准。B 站图文状态查询优先使用空间动态流；视频状态查询使用创作中心稿件详情接口。
+
+## Result 协议
+
+三个方法都返回：
+
+```ts
+type ApiResult<TData extends object> = {
+  code: number
+  state: number
+  text: string
+  data: TData
+}
+```
+
+没有顶层 `message`。平台细节、错误原因、审核原因放在 `data.reason`。
+
+### State
+
+| state | 含义 | 宿主插件建议 |
+|---:|---|---|
+| `0` | 成功 | 继续下一步 |
+| `10000` | 审核中或公开链接同步中 | 稍后继续轮询 |
+| `50000` | 可重试失败 | 宿主按业务策略重试 |
+| `60000` | 终态失败 | 修改输入、登录、账号状态、平台状态或代码 |
+
+### Status Code
+
+| code | text | state |
+|---:|---|---:|
+| `0` | 成功 | `0` |
+| `10001` | 审核中 | `10000` |
+| `10002` | 公开链接同步中 | `10000` |
+| `50004` | 操作超时 | `50000` |
+| `50005` | 网络请求失败 | `50000` |
+| `60001` | 请求参数无效 | `60000` |
+| `60002` | 平台暂不支持 | `60000` |
+| `60003` | 未登录或登录态失效 | `60000` |
+| `60004` | 发布状态引用无效 | `60000` |
+| `60005` | 发布状态引用平台不匹配 | `60000` |
+| `60006` | 需要验证码或安全校验 | `60000` |
+| `61003` | 内容审核未通过 | `60000` |
+| `66001` | 平台适配器协议错误 | `60000` |
+| `69001` | 未知错误 | `60000` |
+
+`Unknown` 只是兜底。真实 adapter 应尽量把已知平台状态映射到明确 code。
+
+## Timeout 和 Retry
+
+本包不定义业务级默认超时对象。不传 `timeoutMs` 时，步骤执行完全使用 `@skrillex1224/extension-toolkit` 的默认 timeout。每个公开方法仍可以传 `timeoutMs` 覆盖本次调用。
+
+Phase 1 不在公开方法层做自动 retry。宿主插件负责业务级 retry，例如发布失败后重试 3 次、状态查询定时轮询等。adapter 内部只有在明确幂等且安全的局部步骤，才可以使用 `extension-toolkit` 的显式 retry。
+
+## 安全校验和 onEvent
+
+Phase 1 不支持 `onEvent`，也不支持验证码、二维码、扫码确认、账号风控的暂停和恢复。
+
+如果平台要求人工操作，adapter 应返回或抛出可映射为 `SecurityCheckRequired` 的结果。宿主插件收到后应终止当前任务并提示用户处理。
+
+## 本地开发
+
+```bash
+cd chrome-media-publish-extension
+npm install
+npm run check
+```
+
+`npm run check` 会执行：
+
+- 构建 `dist/index.js`
+- 公开入口 smoke test
+- 未支持平台测试
+- 协议校验测试
+- fake adapter 编排测试
+- Douyin adapter、auth、payload、tag、status、AWS4、album、video 单测
+- Bilibili adapter、auth、markdown、opus、status、video 单测
+
+打包最小 Chrome extension 测试夹具：
+
+```bash
+npm run test:pack
+```
+
+产物目录：
+
+```text
+chrome-media-publish-extension/tests/extension/dist
+```
+
+在 Chrome 扩展管理页选择 “Load unpacked” 并加载该目录。它只用于验证 npm 包能在 Chrome extension popup 中被 bundler 打包和调用，不是正式插件 UI。
+
+## npm 发布
+
+```bash
+npm run publish:npm
+```
+
+发布前会先执行 `npm run check`。正式发布顺序应先发布 `@skrillex1224/extension-toolkit`，再发布本包。
+
+## Adapter 开发规范
+
+真实平台 adapter 放在：
+
+```text
+src/adapters/<platform>/
+```
+
+推荐结构：
+
+```text
+src/adapters/<platform>/
+  index.js          # 平台 adapter 对象，对外只暴露 checkAuth/publish/getStatus
+  auth.js           # checkAuth 请求与响应解析
+  article.js        # 仅平台支持 markdown 文章时存在
+  album.js          # 仅平台支持图文/图片集时存在
+  video.js          # 仅平台支持视频时存在
+  get-status.js     # getStatus 请求与状态映射
+  parts/            # 平台内部请求、payload、签名、上传、状态映射等实现
+  README.md         # 字段映射、已知行为、E2E 记录、statusRef meta key
+```
+
+不是每个平台都必须有全部文件。拆分原则是职责清晰，而不是机械凑目录。
+
+adapter 对象协议：
+
+```ts
+type PlatformAdapter = {
+  platform: string
+  checkAuth(ctx, input): Promise<{ isAuthenticated: boolean; reason?: string }>
+  publish(ctx, media, input): Promise<{ statusRef: PublishStatusRef; reason?: string }>
+  getStatus(ctx, statusRef, input): Promise<{ status: 'published' | 'reviewing' | 'public_url_syncing' | 'rejected'; postUrl?: string; rawStatus?: string | number; reason?: string }>
+}
+```
+
+要求：
+
+- 使用函数和普通对象，不使用 adapter base class 或继承体系。
+- `index.js` 只做编排，并在平台目录内按 `media.type` 分流。
+- 请求构造、响应解析、上传算法、签名、状态映射、平台常量拆到 `parts/`。
+- 每个有意义的平台步骤都用 `ctx.Kit.runStep()` 包裹。
+- 通用 Chrome 能力优先补到 `@skrillex1224/extension-toolkit`，不要在业务包里重复造 runtime。
+
+## 当前限制
+
+- 当前只注册 Douyin 和 Bilibili adapter；其它平台返回 `UnsupportedPlatform`。
+- Douyin 真实发布依赖 Chrome extension 环境和已登录创作者中心。
+- Douyin 视频发布依赖创作者中心页面内官方 uploader；如果平台前端改版，可能需要重新 E2E 校准。
+- Bilibili 真实发布依赖 Chrome extension 环境和已登录 B 站创作中心。
+- Bilibili 图文发布依赖 read-editor 页面上下文；视频发布依赖 videoup 页面上下文。如果平台前端改版，可能需要重新 E2E 校准。
+- 不支持验证码、二维码、扫码确认、账号风控的暂停和恢复。
+- 不做旧字段映射；额外字段会被忽略。