AGENTS.md

Repository Guidelines

Meterleaf 是独立 AI 用量账本，只读采集上游用量并在本地计价与展示。产品入口见 README，账务口径见计价说明和使用与报表，部署与发布分别见部署指南和版本与发布。

恢复工作时，读取当前任务实际引用的记录及必要设计、证据。没有记录时依据当前上下文继续；新的恢复记录可保存到 .workbench/records/。

src/connectors 解释上游字段；src/collector 是 macOS 本机采集器，只读解析 Claude Code 本地记录并推送到服务端；src/domain 定义用量和计价规则；src/storage 负责持久化与汇总索引。
src/server 提供 API 和同步服务；src/shared 定义共享契约；src/web 实现 React 界面；public 存放静态资源。
tests 存放测试，prices 管理版本化费率 JSON，docs 存放中文文档。
领域模型与报表不得依赖 Sub2API SQL 或列名。用量与额度快照是独立能力；未知值不得补零，缓存与推理 Tokens 不得重复累计，网关扣费与独立估值必须区分。
普通输入、缓存读取、缓存写入、输出是互斥计量桶；推理 Tokens 是输出子集。上游金额、网关扣费、订阅等价 USD、标准 API USD 和 Credits 保留各自依据，不能互相冒充账单或按固定比例换算。估值绑定价格表修订、有效时间与实际来源；缺少字段或费率保留未计价。
累计用量、筛选时段和订阅周期分别计算。API 接入类型不能推断上游是否有订阅额度；额度窗口按有效快照判断，过期或未知不能沿用旧值。

使用 Bun 1.4.4 或更新版本，依赖变更提交 bun.lock。

使用 TypeScript、两空格缩进、双引号和分号；沿用附近代码结构。React 组件使用 PascalCase，函数与变量使用 camelCase。
使用 Prettier 检查或格式化所改文件，例如 bunx prettier --check src/web/components/LedgerTable.tsx；不顺带重排无关文件。
注释解释业务含义、边界条件、兼容策略及异步顺序，不复述语法。跨模块契约和非显然规则应有简短说明；自解释的局部代码不强加注释。
禁止“本次新增”“之前改为”等修改过程叙述；修改代码时同步清理失效注释。项目文档使用中文，标识符与第三方许可证原文不翻译。

用自然、直接的中文回答“这是什么、怎么用、出问题怎么办”。少用术语、抽象名词和生硬缩写；必要术语第一次出现时解释。不要把代码实现翻译成说明书，也不要用空话凑篇幅。
按读者任务组织内容，描述当前用法，不按开发时间逐条追加功能、修复经过或验证记录。
README 只保留产品定位、核心能力、截图、快速开始和文档入口；使用指南解释操作及结果；部署指南聚焦配置、安装、升级、备份与排障。
内部线程、队列、缓存算法等实现细节，除非直接影响操作决策，否则不进入用户文档。确需维护的架构约束单独说明，不把实现复述成产品介绍。
改动时重写或合并相关段落，删除重复和过时内容；每条信息保持一个主要出处，用链接引用，不复制多份费率表或配置说明。
文档完成后检查命令、默认值、相对链接与截图；截图不包含域名、地址栏、凭据或未经授权的数据。

单元与集成测试使用 Bun，命名为 tests/*.test.ts；浏览器测试使用 Playwright，专项脚本通常命名为 *.browser.ts。
修复问题时覆盖对应回归场景；计价、迁移和同步变更需验证未知值、幂等与失败恢复，不以虚构覆盖率作为门槛。
界面改动检查桌面、移动端和减少动态效果模式；bun run test:browser 通过 METERLEAF_CDP_URL 连接任务浏览器。截图放入已忽略的 test-results，视觉验收由维护者确认。
浏览器测试使用独立任务标签；修改 localStorage 时与维护者预览页隔离 origin。CDP 连接放在有 finally 清理的脚本内，结束时撤销模拟并断开连接，不在长期 REPL 中遗留 Playwright 客户端；系统主题须在清理后再次刷新验证。
高保真参考与维护者已认可版本是视觉依据，修复前保留其可恢复位置和已知缺陷。代理预审按当前任务要求校对参考、导航和受影响状态，明确偏差先处理；预审通过与维护者最终接受分别记录。维护者接管验收时交出可访问版本和已知限制。
纯文档改动核对对应事实、相对链接、所改 Markdown 的 Prettier 检查与 git diff --check，不触发产品完整测试。

每次提交必须使用 type(scope): summary，type 和 scope 均不可省略。
type 使用 feat、fix、refactor、style、test、docs、build、chore 等；scope 指明模块，例如 fix(sync): preserve cursor after failed batch。
PR 说明用户可见变化、相关问题和验证结果；界面变更附截图，未验证项说明原因。

当前按 .env.example 通过环境变量配置来源，可连接一个 Sub2API 实例、通过 METERLEAF_INGEST_KEYS 接收本机采集器推送，两者至少一项；可选的 GitHub 登录按允许名单放行账号；来源管理和用户角色系统不在当前产品范围。
项目采用 Apache-2.0。凭据、真实账户数据、运行数据库、机器路径及构建产物不得进入公开交付内容；真实数据失败不得静默替换为演示数据。
工作台� 2DBE ��属于产品交付内容。排查报表或同步失败先区分读取和采集阶段；清库、修改同步设置不作为默认恢复动作。