feat(pricing): add cucloud and bytedance payg importers

- Add import_cucloud_pricing.go for 联通云 payg 公开价抓取 - Add import_bytedance_pricing.go for 火山引擎/ByteDance Ark 定价导入 - Include test files and sample testdata for both importers - Update plan catalog inventory docs and seeds - Add cucloud pricing importer implementation plan - Align pipeline scripts and smoke gate tests
2026-05-22 15:28:13 +08:00
parent 5c5578a19b
commit 6fe3b484f1
17 changed files with 1362 additions and 37 deletions
--- a/docs/plans/2026-05-22-cucloud-pricing-importer-plan.md
+++ b/docs/plans/2026-05-22-cucloud-pricing-importer-plan.md
@@ -0,0 +1,335 @@
+# 联通云细颗粒度 Pricing Importer 设计计划
+
+> For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 在不伪造价格事实的前提下，把联通云从目录级 `import_cucloud_catalog.go` 升级为可验证的细颗粒度 pricing importer。
+
+**Architecture:** 采用“两层事实源”设计：第一层抓取帮助中心公开文档中已明确结构化披露的 Token Plan 模型价格与区域支持信息并真实落库；第二层对 AISP 按量计费公开文档仅做“计费模式已验证、具体 per-model payg 单价未公开”的 blocker 标注，不把未公开的销售价伪造成 `region_pricing`。实现上优先复用 `official_pricing_import_common.go`，新增 `import_cucloud_pricing.go`，并保留 `import_cucloud_catalog.go` 作为目录入口校验。
+
+**Tech Stack:** Go llm_script importer、联通云帮助中心 SSR HTML、正则/HTML 表格解析、现有 `officialPricingRecord` / `catalogVerificationRecord`。
+
+---
+
+## 已验证事实
+
+1. 目录入口仍有效：
+   - `https://www.cucloud.cn/act/CloudAI.html`
+   - 已由现有 `import_cucloud_catalog.go` 校验 AICP / AI 应用开发平台存在。
+
+2. AISP 帮助中心公开页面可直接 `GET`，无需登录，且页面源码内内嵌完整文档内容：
+   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=2973`（购买计费）
+   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=3237`（Coding Plan）
+   - `https://support.cucloud.cn/document/127/591/2357.html?id=2357&folderid=3236`（Token Plan）
+
+3. 已从公开源码中确认的结构化价格事实：
+   - Token Plan 个人版：
+     - Lite 15元/月，600万 tokens
+     - Pro 30元/月，1200万 tokens
+     - Max 45元/月，1800万 tokens
+   - Token Plan 团队版：
+     - Lite 198元/月，25,000 credits
+     - Pro 698元/月，100,000 credits
+     - Max 1398元/月，250,000 credits
+   - 团队版 credits 对三种模型公开披露了折算综合单价：
+     - `DeepSeek-V4-Pro`：9.30 元/百万tokens
+     - `DeepSeek-V4-Flash`：0.70 元/百万tokens
+     - `MiniMax-M2.5`：1.10 元/百万tokens
+
+4. 已从公开源码中确认的结构化区域支持事实：
+   - 区域列：`呼和浩特二区 / 上海二十二区 / 武汉四区 / 济南五区 / 贵阳基地二区`
+   - 可从 `Token Plan概述` 或 `AI服务平台API介绍` 表格中解析模型-区域支持矩阵。
+
+5. 已确认但不能伪造的边界：
+   - AISP `购买计费/计费项及计费方式`、`按量计费模式` 文档明确说明“按量计费”为官方公开模式，单位为 `元/千 Tokens`，且按所选模型销售价实时累加。
+   - 但当前公开帮助中心页面未披露具体每个模型的按量销售价表。
+   - 因此现阶段不能把 AISP payg 的 per-model 单价写入 `region_pricing`。
+
+## 设计决策
+
+### 决策 A：拆成“可落库价格”与“已验证 blocker”两部分
+
+1. 可直接落库到 `region_pricing` 的只有：
+   - Token Plan 团队版中公开给出的三个模型综合单价。
+2. 只能记录 blocker、不能写价格的部分：
+   - AISP 按量计费 per-model 销售价。
+
+理由：
+- 公开文档对 payg 的计费机制有描述，但没有模型价格表。
+- 用户明确要求“找不到就标 blocker，不伪造 importer”。
+- Token Plan 团队版三模型综合单价属于公开结构化价格，足够支撑一个“真实 importer v1”。
+
+### 决策 B：新增 pricing importer，不覆盖 catalog importer
+
+保留：
+- `scripts/import_cucloud_catalog.go`：继续负责 `cucloud-aicp-platform` / `cucloud-ai-app-platform` 目录存在性校验。
+
+新增：
+- `scripts/import_cucloud_pricing.go`：负责 AISP Token Plan 公开价格与模型区域支持的结构化导入。
+
+理由：
+- catalog importer 与 pricing importer 的事实层级不同。
+- 后续若官方公开 payg 模型价表，可在 `import_cucloud_pricing.go` 内扩展，不影响目录校验链路。
+
+### 决策 C：v1 只导入三个模型，价格视为 blended price
+
+v1 导入模型：
+- `DeepSeek-V4-Pro`
+- `DeepSeek-V4-Flash`
+- `MiniMax-M2.5`
+
+价格写法：
+- 因公开文档给的是“综合单价 X 元/百万tokens”，不是 input/output 分拆价；
+- v1 写入 `officialPricingRecord` 时采用：
+  - `InputPrice = blendedPrice`
+  - `OutputPrice = blendedPrice`
+- 同时在 `SourceURL` / `notes` / 文档中明确这是 `Token Plan blended price`，不是 AISP payg 的 input/output 拆分价。
+
+风险：
+- 这不适合作为严格意义上的 OpenAI-style in/out token 定价比较。
+- 但比继续停留在目录级“无细颗粒度价格”更真实，且不会伪造不可得的 input/output 拆分。
+
+### 决策 D：区域粒度以“支持矩阵交集”写入
+
+建议落库策略：
+- 仅对公开支持该模型的区域写入 region_pricing 记录。
+- 例如：
+  - `DeepSeek-V4-Pro` -> `贵阳基地二区`
+  - `DeepSeek-V4-Flash` -> `贵阳基地二区`（团队版表明确）以及个人版支持区域若文档已写明，可谨慎扩展，但 v1 优先用矩阵表而不是 prose。
+  - `MiniMax-M2.5` -> 从矩阵表取支持区域。
+
+理由：
+- 同一模型在联通云并非全区域可用。
+- 使用支持矩阵可避免写出不存在的区域价格。
+
+## 文件设计
+
+### 1. 新增 importer
+
+**Create:** `scripts/import_cucloud_pricing.go`
+
+职责：
+1. 获取公开帮助中心页面 HTML
+2. 修复页面源码中的 UTF-8 / Latin1 混杂问题
+3. 从页面源码中定位目标文档 `content` 块：
+   - `Token Plan概述`
+   - `AI服务平台API介绍` 或 `各云区域模型支持情况`
+   - `计费项及计费方式`
+   - `按量计费模式`
+4. 解析：
+   - Token Plan 团队版三模型综合单价表
+   - 模型-区域支持矩阵表
+5. 生成 `officialPricingRecord`
+6. dry-run 输出：
+   - 记录数
+   - 模型数
+   - 区域数
+   - 是否检测到 `payg_mode_confirmed=true`
+   - `payg_price_table_public=false`
+
+建议 CLI 参数：
+- `-url`：默认购买计费页或 Token Plan 页
+- `-fixture`：本地样例 HTML
+- `-dry-run`
+- `-timeout`
+
+### 2. 新增测试
+
+**Create:** `scripts/import_cucloud_pricing_test.go`
+
+测试覆盖：
+1. 能从 fixture 中解析三模型 blended 价格
+2. 能解析区域支持矩阵
+3. 仅为支持区域生成记录
+4. dry-run 摘要包含：
+   - `source=cucloud-pricing-import`
+   - `models=3`
+   - `payg_mode_confirmed=true`
+   - `payg_price_table_public=false`
+5. 若 fixture 缺少三模型价格表，测试应 fail
+
+### 3. 新增 fixture
+
+**Create:** `scripts/testdata/cucloud_pricing_sample.html`
+
+内容最少应覆盖：
+- Token Plan 团队版价格表
+- 三模型 `综合单价X元/百万tokens`
+- 区域支持矩阵表
+- `按量计费` 文本（用于 blocker 语义断言）
+
+### 4. runtime 接入
+
+**Modify:**
+- `scripts/run_intel_pipeline.sh`
+- `scripts/run_real_pipeline.sh`
+- `scripts/run_daily.sh`
+- `scripts/verify_importer_smoke.sh`
+- `scripts/importer_smoke_gate_test.sh`
+- `scripts/pipeline_runtime_alignment_test.sh`
+
+接入方式：
+- 保留 `cucloud_catalog`
+- 新增 `cucloud_pricing`
+- 失败消息区分：
+  - 目录失败：`联通云目录校验失败`
+  - 价格失败：`联通云 Token Plan 价格导入失败`
+
+### 5. seed / docs 同步
+
+**Modify:**
+- `seeds/plan_catalog_inventory_seed_cn_relays_top20plus.json`
+- `docs/PLAN_CATALOG_COVERAGE_MATRIX.md`
+- `docs/NEXT_IMPORTER_RUNTIME_PRIORITY.md`
+- `docs/PLAN_CATALOG_INVENTORY.md`
+- `scripts/import_plan_catalog_test.go`
+
+同步原则：
+- `cucloud-aicp-platform` / `cucloud-ai-app-platform` 仍指向 `import_cucloud_catalog.go`
+- 如新增联通云价格型 catalogCode，则新建 seed 项；否则仅在 docs 中注明：
+  - `目录入口已导入`
+  - `Token Plan 三模型 blended price 已导入`
+  - `AISP payg per-model price table 仍未公开`
+
+## 推荐实现顺序
+
+### Task 1: 固化 discovery 结果到 fixture 与计划文档
+
+**Objective:** 把已验证的公开证据固化为可重复测试输入。
+
+**Files:**
+- Create: `scripts/testdata/cucloud_pricing_sample.html`
+- Create: `docs/plans/2026-05-22-cucloud-pricing-importer-plan.md`
+
+**Step 1: 写 fixture**
+- 从公开页面中裁剪最小必要 HTML 片段：
+  - Token Plan 三模型价格表
+  - 区域支持矩阵表
+  - 按量计费说明段落
+
+**Step 2: 验证 fixture 可读**
+Run:
+- `python3 - <<'PY' ...` 或 importer 单测读取 fixture
+Expected:
+- 能定位三张关键表 / 段落
+
+### Task 2: 先写失败测试
+
+**Objective:** 先锁定 importer 的真实合同。
+
+**Files:**
+- Create: `scripts/import_cucloud_pricing_test.go`
+
+**Step 1: 写 failing tests**
+至少包括：
+- `TestParseCUCloudPricingBuildsBlendedRecords`
+- `TestParseCUCloudPricingBuildsRegionMatrix`
+- `TestRunCUCloudPricingImportDryRunPrintsSummary`
+
+**Step 2: 运行测试确认失败**
+Run:
+- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`
+Expected:
+- FAIL，因为 importer 尚不存在或解析逻辑未实现
+
+### Task 3: 实现最小 importer
+
+**Objective:** 只实现三模型 blended price + 区域支持矩阵。
+
+**Files:**
+- Create: `scripts/import_cucloud_pricing.go`
+
+**实现要点：**
+1. 获取 HTML
+2. `latin1 -> utf8` 修正
+3. 通过最近的 `"content":"...","createBy"` 边界提取目标内容块，而不是依赖简单 title-first regex
+4. 表格解析：
+   - Table A：团队版三模型综合单价
+   - Table B：模型区域支持矩阵
+5. 产出 `officialPricingRecord`
+   - `OperatorName`: `Unicom AISP`
+   - `OperatorNameCn`: `联通云 AI服务平台AISP`
+   - `OperatorWebsite`: `https://www.cucloud.cn`
+   - `SourceURL`: 购买计费 / Token Plan 页面
+   - `Currency`: `CNY`
+   - `InputPrice == OutputPrice == blendedPrice`
+   - `Region`: 匹配支持矩阵中的具体云区域
+6. dry-run 摘要要显式输出：
+   - `payg_mode_confirmed=true`
+   - `payg_price_table_public=false`
+
+### Task 4: 运行 focused tests
+
+**Objective:** 验证 importer 合同成立。
+
+Run:
+- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`
+Expected:
+- PASS
+
+### Task 5: 接入 smoke / pipeline
+
+**Objective:** 让新 importer 进入日跑链路，但不移除 catalog importer。
+
+**Files:**
+- Modify: `scripts/verify_importer_smoke.sh`
+- Modify: `scripts/importer_smoke_gate_test.sh`
+- Modify: `scripts/pipeline_runtime_alignment_test.sh`
+- Modify: `scripts/run_intel_pipeline.sh`
+- Modify: `scripts/run_real_pipeline.sh`
+- Modify: `scripts/run_daily.sh`
+
+**Step 1: 增加 `cucloud-pricing-fixture` / `cucloud-pricing-live` smoke**
+**Step 2: 增加 runtime source key `cucloud_pricing`**
+**Step 3: 保留 `cucloud_catalog`**
+
+### Task 6: 文档 truth-sync
+
+**Objective:** 把联通云状态从“只有目录级”升级为“目录+部分结构化价格”。
+
+**Files:**
+- Modify: `docs/PLAN_CATALOG_COVERAGE_MATRIX.md`
+- Modify: `docs/NEXT_IMPORTER_RUNTIME_PRIORITY.md`
+- Modify: `docs/PLAN_CATALOG_INVENTORY.md`
+- Modify: `seeds/plan_catalog_inventory_seed_cn_relays_top20plus.json`（如需要）
+
+**文案要求：**
+- 明确写：
+  - Token Plan 三模型 blended price 已真实导入
+  - AISP payg per-model 单价未公开，仍属 blocker
+- 禁止写成“联通云 payg 已完整打通”
+
+## 验证命令
+
+### Focused unit tests
+- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go ./scripts/import_cucloud_pricing_test.go`
+
+### Plan catalog mapping tests
+- `go test -tags llm_script ./scripts/subscription_import_common.go ./scripts/import_plan_catalog.go ./scripts/import_plan_catalog_test.go`
+
+### Shell gates
+- `bash scripts/pipeline_runtime_alignment_test.sh`
+- `bash scripts/importer_smoke_gate_test.sh`
+
+### Live dry-run
+- `go run -tags llm_script ./scripts/subscription_import_common.go ./scripts/official_pricing_import_common.go ./scripts/import_cucloud_pricing.go -dry-run`
+
+**Expected live dry-run truth:**
+- 只宣称 Token Plan 三模型 blended price 已导入
+- 同时输出 / 记录 `payg_mode_confirmed=true`
+- 同时输出 / 记录 `payg_price_table_public=false`
+
+## 非目标
+
+1. 不伪造 AISP payg per-model input/output 单价
+2. 不把 Token Plan blended price 冒充为 OpenAI 风格 input/output split price
+3. 不删除现有 `import_cucloud_catalog.go`
+4. 不在未发现公开价表前宣称“联通云细颗粒度价格已完整闭环”
+
+## 当前最短闭环路径
+
+1. 先实现 `import_cucloud_pricing.go` v1
+2. 只导入三模型 Token Plan blended price + 区域支持矩阵
+3. runtime/smoke 接入
+4. docs 标明 payg per-model price 仍是 verified blocker
+
+这条路径能把联通云从“纯目录级”提升到“部分结构化价格已真实落库”，同时保持事实边界清晰。