方法论Methodology

数据来源优先级、unknown 处理、冲突解决、汇率与 Token 成本计算、时间戳规则。README 只做入口，方法细节都在这里。Source priority, handling of unknowns, conflict resolution, exchange-rate and token-cost math, timestamp rules. The README is just the entry point; the method lives here.

1. 数据来源优先级1. Source priority

1. Official（最高）：官方价格页、产品文档、API 文档、服务条款、隐私政策、模型文档、FAQ、公告、官方 GitHub。Official (highest): pricing pages, product docs, API docs, terms of service, privacy policy, model docs, FAQ, announcements, official GitHub.
2. Measured：PlanScope 自己的实测（TTFT、TPS、Decode TPS、Latency、429、Error rate、Token 消耗、真实额度行为），必须与官方声明分开记录。Measured: PlanScope's own measurements (TTFT, TPS, decode TPS, latency, 429s, error rate, token usage, real quota behaviour), always recorded separately from vendor claims.
3. Community（辅助）：GitHub Issues、Reddit、Discord、Telegram、论坛、博客、用户实际报告 —— Community reports are signals, not authoritative facts。Community (supporting): GitHub Issues, Reddit, Discord, Telegram, forums, blogs, user reports — community reports are signals, not authoritative facts.

厂商营销口径不作为唯一事实依据。Vendor marketing copy is never treated as the sole factual basis.

2. Unknown 如何处理2. How unknowns are handled

• 未查证 → value: null 或 status: unknown，绝不编造。Not verified → value: null or status: unknown. Nothing is ever invented.
• 厂商模糊表述（Unlimited / High Usage / Fair Use / Reasonable Usage）原样记录，并设 actual_limit_known: false。Vague vendor wording (Unlimited / High Usage / Fair Use / Reasonable Usage) is recorded verbatim with actual_limit_known: false.
• 校验器只拒绝错误结构与非法格式，不会因为信息缺失而失败。The validator rejects only broken structures and illegal formats — missing information never fails it.

3. 冲突来源如何处理3. Conflicting sources

• 官方文档 > 官方公告 > 实测 > 社区。Official docs > official announcements > measurements > community.
• 冲突时保留双方记录与各自 checked_at，以更高优先级来源作为事实值，不静默覆盖历史。Both sides of a conflict are kept with their own checked_at; the higher-priority source becomes the factual value and history is never silently overwritten.
• 无法判定时字段保持 unknown，并在 note 中记录冲突。When it cannot be resolved, the field stays unknown and the conflict is recorded in the note.

4. 汇率计算方法4. Exchange-rate method

• planscope fetch-rate 计算 D-7 ~ D-1（Asia/Shanghai，最近 7 个完整自然日）的有效 USD/CNY 日值均值：planscope fetch-rate averages the valid USD/CNY daily values over D-7 ~ D-1 (Asia/Shanghai, the last 7 complete calendar days):

weekly_average = sum(valid observations) / number of valid observations

• 只使用数据源在窗口内实际提供的有效日值：不补周末、不插值、不取当天、无 fallback、无 retry；当日无有效值 → CI 失败，等待第二天。Only daily values the source actually published inside the window are used: no weekend backfill, no interpolation, no same-day value, no fallback, no retry; if today has no valid value the CI fails and waits for the next day.
• 结果写入 config/exchange_rate.yaml，文件只含 usd_cny 一个键。The result is written to config/exchange_rate.yaml, which holds only the single key usd_cny.
• 该文件是全项目 USD → CNY 的唯一配置来源：代码不硬编码、不在多处定义、不实时联网取汇率。That file is the single USD → CNY source for the whole project: nothing is hardcoded, defined twice, or fetched from the network at runtime.
• 这是用于横向比较的近似值，不是实时支付金额、财务结算、银行或信用卡汇率。It is an approximation for cross-plan comparison, not a live payment, financial settlement, bank or card rate.
• 当前初始值：usd_cny = 6.70154。Current value: usd_cny = 6.70154.

5. 人民币成本如何计算5. How CNY cost is computed

CNY price = original price × usd_cny（仅当原始币种为 USD；CNY 直接使用；其他币种不强行换算） (only when the original currency is USD; CNY is used as-is; other currencies are never force-converted)

• 原始价格与币种永远保留；CNY 是派生值，只在展示层生成。Original price and currency are always kept; CNY is derived and exists only in the presentation layer.
• 促销价单独记录，绝不覆盖标准价。Promotional prices are recorded separately and never overwrite the standard price.

6. Token Cost 如何计算6. How token cost is computed

• 先保存原始事实：原始价格、币种、Token 额度、模型倍率。Source facts are stored first: original price, currency, token quota, model multipliers.
• 再计算：Effective RMB / 1M input tokens、/ 1M output tokens、/ 1M weighted tokens。Then compute: Effective RMB / 1M input tokens, / 1M output tokens, / 1M weighted tokens.
• 额度或倍率不明确时标记 not directly comparable，不强行估算。When quota or multipliers are unclear, mark not directly comparable instead of force-estimating.
• 不输出主观“最好”评分；所有排序均为客观字段。No subjective “best” score is ever emitted; every sort is on an objective field.

7. Community Report 如何处理7. How community reports are handled

• 写入 data/providers/<provider>/community/，必须标注 source_type 与 confidence（high / medium / low）。Written to data/providers/<provider>/community/, and must carry source_type and confidence (high / medium / low).
• 不能直接进入 privacy / plan / model 的事实字段。They never enter the factual fields of privacy / plan / model records.

8. Benchmark 数据如何分类8. How benchmark data is classified

official / measured / community_reported / estimated —— 每条记录独立标注，绝不混合成一个数字。 — every record is labelled individually and never blended into a single number.

9. 时间戳与历史规则9. Timestamps and history rules

• 统一 ISO 8601：2026-09-23T10:30:00+08:00；每条动态记录至少有 checked_at 字段。ISO 8601 throughout: 2026-09-23T10:30:00+08:00. Every dynamic record carries at least checked_at.
• 变更用 effective_from / effective_until 表达，历史不静默覆盖。Changes are expressed with effective_from / effective_until; history is never silently overwritten.
• 下线套餐设 status: deprecated/discontinued 并保留文件，只有错误录入才删除。Retired plans get status: deprecated/discontinued and keep their file; only mistaken entries are deleted.
• 审计记录 = Git history；变更展示 = data/changes/（结构化数据，不解析 commit message）。Audit trail = Git history; change display = data/changes/ (structured data; commit messages are not parsed).

10. 架构原则10. Architecture principles