项目协作规范

本文件是本仓库唯一的 Agent 工作规范入口。开始修改配置、文档或校验脚本前先阅读本文件；具体来源导航见 docs/model-sources/README.md。用户在当前会话明确给出的要求优先，同一任务内已有提交/合并授权不因后续修正而自动失效，不将其扩展到无关任务。

工作区与子模块

建立 worktree 时务必拉取最新子模块代码。若存在子模块，先同步配置，再初始化并更新到所跟踪分支的最新提交：
```
git submodule sync --recursive
git submodule update --init --recursive --remote
```
检查并记录子模块 HEAD、目标分支和 gitlink 差异；保留与当前任务无关的改动，不默认将无关 gitlink 变化一并提交。
修改前检查 git status --short，拉取 origin/main 并确认当前工作基线。不得覆盖、reset 或顺带格式化无关文件，尤其是用户已有的 logs/、环境和缓存。
分支默认使用 work/ 前缀。未明确要求新 worktree 时优先复用合适工作区。

提交身份

项目	规则
Commit 身份	仅以用户身份提交，禁止添加 `Co-Authored-By`、AI 署名或任何 AI 辅助标记

Provider 数据向后兼容规约（强制）

schemas/provider.schema.json 是已发布客户端的兼容契约（frozen baseline），推送数据前必须理解两类变更的风险差异：

变更类型	风险	规则
已知字段扩 enum 值（如 `credentialSource` 加新值）	毒丸：老客户端把「已知字段的非法枚举值」判为结构性错误。pre-#1021（≤10.0.82）客户端会整份拒绝合并 → 停收所有预设更新；新装用户 compute.json 建不出来	必须先发布并铺开支持该值的客户端版本，再推送数据（v68/v69 事故教训，见 desirecore #1016/#1021）
新增可选字段	安全：已铺开韧性（#848/#1021）的客户端把它当未知字段（读时内存剥离、写时原样保留）	先在 desirecore 主仓 `computeProviderSchema` 声明该字段（否则新客户端也读不到），再更新本仓 schema，最后推数据

requiredClientVersion 强制规约：

新增依赖新凭据源（credentialSource 新值）或新客户端能力的 provider 时，必须声明 requiredClientVersion（取包含该能力支持的客户端发布版本号）。≥ desirecore #1038 的客户端据此把不满足版本的 provider 优雅门控为「需更新客户端」
注意它保护不了 pre-#1038 的存量客户端——enum 扩值场景仍必须遵守上表第一行的"先发版铺开"规则，二者不可互替
降低/解除版本要求时改为更小版本号（如 0.0.0）而非删除字段：客户端预设合并只遍历上游存在的字段，不回传字段删除

每次更新前必须核查

核查项	必须核查的内容
当前基线	最新 `origin/main`、当前提交、工作区改动、远端 manifest 版本；不要用过期分支或旧快照判断线上配置
更新范围	哪些原厂模型、哪个 API/订阅/套餐、哪个地域；列出受影响 Provider、ModelSpec、索引、service-map、测试与文档
官方证据	打开对应供应商 `SOURCES.md` 与单模型/接入面文件；实际读取官网正文、官方 API 或官方仓库；核对最终跳转域名、读取日期和失败/页面壳状态
精确身份	API 模型 ID、大小写、日期版本、别名、默认路由名称；检查重复 ID、归一化冲突与 exact/pattern/family 是否误吞其他代际
当前可用性	正式/预览/历史/退役状态及停止服务时间；原厂存在不代表某套餐提供，公共目录缺失不直接证明原厂退役
输入输出限制	上下文、最大输入、最大输出、默认输出、思维链预算；优先官网明文整数，K/M 简写写清换算，输入/输出独立限制不可混作总窗口
模态与工具	文本、图片、音频、视频的输入/输出能力；工具调用、结构化输出、联网搜索是否由该接入面实际支持
推理与采样	支持的 effort、默认档、能否关闭思考、adaptive/budget 形态、thinking 回放、temperature/top_p/top_k 和强制 tool_choice 限制
端点与版本	baseUrl、API 格式、媒体端点、凭据来源、所需客户端版本；不向未适配协议的 Provider 放入新型号，也不新增未被客户端读取的扩展键
计价	Provider 的币种/地域、token/图片/秒/字符/search unit/实例单位；原价/限时优惠、缓存写读、阶梯/峰谷分别核对；未知价格省略，动态占位不是免费
本仓策略	tier、routingPriority、defaultReference、Agent 可选性等本仓选择与原厂事实分开；没有依据时不扩大自动路由范围
兼容同步	Provider 副本、共享规格、套餐模型表及版本清单是否一致；Schema 是否接受，老客户端是否已支持；移除需检查 tombstones 与所有实际别名
核验边界	只将实际核实字段记为已核；不能把 ID 存在、HTTP 200、Schema/构建成功或其他平台参数说成全部参数核实或账号实测通过

修改与来源记录规则

模型目录唯一作者数据是 catalog/v2/catalog.json，退役注册在 catalog/v2/retirements.json；compute/v2/** 以及根 compute/providers、compute/coding-plans、compute/model-specs 的模型正文由 npm run catalog:compile 生成，禁止手工双写。索引、service-map、pricing 等非投影文件仍分别维护。共享规格不包含价格；接入面推理 effort、回放能力不能混入共享规格；官网没有支持的新字段先查客户端和 frozen schema。
每次目录更新先检查 FIELD-DECISIONS、SPEC-DECISIONS 和 ADAPTER-DECISIONS，精确绑定或显式例外必须保留。未知事实维持 unknown；未适配协议保持禁止调用，不能用将来的版本号替代缺失适配器。生成后运行 npm run catalog:check，核对根 V1 投影保真及 340 条实际解析对照。
候选目录 publication.state=candidate 不启用 V2。切换 published 前，必须检查正式客户端 tag、合入代码和发布产物，填写真实 requiredClientVersion；只完成代码合并或构建不能作为已经正式发布的证据。
来源使用细分目录：docs/model-sources/providers/<supplier>/SOURCES.md 保存官网证据；models/<model-id>.md 每个模型独立记录；access/<category>--<config-id>.md 每个接入面独立记录；README 只保留导航。
一个模型在原厂、订阅、套餐和聚合平台上的差异分段记录，不合并价格/窗口/可用性。同名不等于同一接入合同；文件名规范见维护指南。
基于已有文件增量编辑，保留既有证据、日期、待核实项和历史说明。批量迁移目录只能迁移记录，不能凭迁移提高核验状态或刷新核验日期。
同步单模型参数详情、字段→官网引用、核验状态和模型指纹；平台字段变化时更新单接入面文件及平台指纹。禁止只换指纹来掩盖未重新核实的数据。
partial 只核实列出的字段，pending 尚缺字段级证据，historical 仅作历史兼容。来源目录读取失败、返回壳或需要权限时如实记录，不用第三方补数。
来源缺口在 docs/source-gaps 按供应商、型号身份、API 和本仓策略分别单列；更新字段证明后运行 npm run sources:gaps。有官网入口但读取失败不称作没有官网，仅确认 ID 不称作参数已核。
修改共享规格时同步更新 compute/model-specs/_index.json 的数据批次说明；已核客户端使用该索引 mtime 失效规格缓存，仅修改单个规格文件可能不触发重读。
非模型官方 API 契约与本仓定价/默认策略分别记录在 docs/data-sources；运行时官方目录、归档摘要及 Hatch pin 记录在 docs/runtime-sources。离线来源校验只验证配置与记录一致，联网刷新和安装/账号验收分别进行。
数据变化时基于最新远端版本递增 manifest.json#presetDataVersion 并更新日期；仅文档结构/工作规范调整不改变预设数据版本。
禁止将 API Key、密码、Token、私有运行时配置写入聊天、文档、日志或源码。来源链接不含凭据，官网内容只保存必要摘要/指纹与核验结论。

提交前与发布核查

npm run validate:sources
npm run validate:data-sources
npm run validate:runtimes
npm run validate
npm test
git diff --check

来源校验必须保持完整覆盖、模型/平台指纹、参数详情、来源引用与官网域名归属检查；拆分或调整文档格式时补充对应回归，不降低原有校验。
只暂存当前任务文件并检查 git diff --cached --check。配置校验不是账号调用验收；需要且已有测试账号授权时做聚焦实测并记录限制。
有提交/合并授权时完成 PR 和远端复查：确认最新 base、精确 head、required checks 全绿、CLEAN、MERGEABLE、零未解决 review threads；使用 --match-head-commit 合并，不绕过保护。
合并后确认远端 main、manifest 与实际更改，检查合并后的 CI；说明真实完成范围、剩余待核实项与客户端后台同步边界。

9.3 KiB Raw Blame History Unescape Escape