potato: Instructions file for Claude Code

CLAUDE.md — 给 Claude Code 的厂规（本仓库的最高行为约束）

这份文件是 Claude Code 在本仓库工作时每次会话都必须先读的规则书。它的目的只有一个：让 AI agent 在高速写代码时撞不穿架构边界，从而不把这个项目写成屎山。 规则分两类：🟥 红线（任何情况下不许越；越线即视为错误，必须停下来问人）和 🟧 约定（默认遵守，确有理由偏离要先说明）。 本文件的"项目定位 / 架构边界 / 数据契约 / 安全 / 可复现"几节是锁定的，与具体功能清单无关；只有 §11 的"第一版范围"会随产品决策更新。

---

0. 一句话项目定位（先理解再动手）

本项目是一个开源的 Claude Skill（SKILL.md）+ 命令行工具（CLI），用来测量一个品牌/网站在 Claude API（开启 web_search） 的回答中被**提及（mention）和被引用（citation）**的频率与结构。

它的本质是一个 可复现的代理测量框架（reproducible proxy measurement framework）：

• 不是爬虫；是反复用一批冻结的问题去"问"AI，收集回答 + 引用 URL，再用确定性规则打分。
• 不是"AI 排名真相检测器"；只测"Claude API web_search 这个表面在某配置下的表现"。
• 输出可追溯、可审计、带不确定区间的报告。

🟥 叙事红线（写注释、文案、报告、README 时都适用）

1. 不许把本工具说成"测出了 Claude 曝光度真相 / AI 排名"。统一措辞："Claude API web-search 可见度（代理测量）"。
2. 报告/输出里凡涉及结论，必须可标注 surface_id 与"本结果仅代表此引擎"。
3. 行动层只给线索（leads），绝不生成"照做就能让 AI 提到你"的保证或建议清单。本工具是观测工具，不是 recommendation engine。

---

1. 架构层级与不可跨越的边界（🟥 核心红线）

数据严格分三类、单向流动，禁止回流、禁止跨层直读对方内部状态：

① 原始观测 (raw)        ② 核验证据 (evidence)      ③ 分析与行动 (analysis)
provider 原样返回    →   被引 URL 的核验/分类    →   指标/区间/gap/driver/报告
    [只追加]                [可重算]                   [完全派生]

核心流水线，每段职责单一、边界清晰：

probe  →  extract  →  verify  →  score  →  report
(I/O)     (纯)        (I/O)      (纯)       (渲染)

🟥 边界红线

1. 只有 probe 写原始层（raw store）。 原始层 append-only，任何其它模块不许覆盖、不许改写已写入的原始记录。
2. extract 和 score 必须是纯函数：输入数据、输出数据；禁止网络请求、文件读写、读系统时钟、未播种的随机数。它们不许 import 任何网络/HTTP/SDK 库（见 §3）。
3. 只有 verify 做被引页的抓取，结果写证据层；score 只读证据层、不自己抓页面。
4. 跨层只走契约对象（§2），不许一个模块 reach into 另一个模块的内部字典/私有属性。
5. 一个文件 / 一个模块只做一件事。新逻辑不确定该放哪一层 → 停下来问人，不要"就近塞"。

---

2. 数据契约规则（🟥 单一真相源）

所有跨模块传递的数据形状，只在 src/aivis/contracts/ 里定义一次，用 pydantic（或 dataclass）带类型。包括但不限于： RunManifest / RawResponse / Citation / BrandMention / EvidenceRecord / Metrics / FrozenConfig。

🟥 契约红线

1. 禁止在 contracts/ 之外就近发明新的数据结构（不许在 pipeline 里临时造一个"差不多但不一样"的 dict 来传数据）。
2. 需要新字段/新类型 → 先改 contracts/，再改用它的地方；改契约属于"会影响所有下游"的动作，必须先问人。
3. RunManifest 必含字段（缺一不可，用于可追溯）： provider / surface_id / model / tool_path / tool_version / locale / region / prompt_version / competitor_set_version / max_uses / budget_cap_usd / run_id / timestamp / search_count。
4. 冻结配置（FrozenConfig）来自 questions.yml + brands.yml，是显式传入的不可变对象，不许做成全局可变状态或环境隐式读取。任何配置改动 = 版本号 bump（新基线），不许静默混入既有趋势序列。