# 项目说明与维护规则

本仓库记录 AI 提示词、模型实验及产物，观察编码能力变化。主题、任务正文、实验记录分别归档，未知历史信息不得猜测。详细命令与数据示例见 [维护指南](docs/maintenance.md)。

## 发布约束

- 保持现有 GitHub Pages 分支自动发布、域名与 CNB → GitHub 同步；提交到 GitHub 即自动更新。
- 未经用户明确要求，不得改为 Actions 部署、修改 Pages 发布源或引入独立 deploy 步骤。
- 仓库根目录必须是可直接静态托管的完整站点。首页、主题页、对比页、截图集页、assets/generated 与 previews 都必须提交。
- 需要独立服务的项目继续由维护者人工部署到 Vercel。除非明确授权，不修改外部部署设置；目录迁移后的 Root Directory 调整必须同步记录在 [Vercel 对照表](docs/vercel-root-directories.md)，并保留 GitHub Pages 提交即发布逻辑。

## 目录与数据

1. 新增前查询已有主题、提示词及模型，避免重复登记。`npm run new:demo` 会提示同名主题、同型号模型和同一任务正文的重复登记风险，按提示逐项确认后再继续。
2. 统一放入 `demos/{topic}/runs/{model-slug}-{effort}-rNN/`，小写 kebab-case。实验 ID 为 `{topic}--{run}`，不会因显示标题变化而改变。
3. 每条实验必须包含 run.json、prompt.md 和 Readme.md。保留完整输入、模型、档位、日期、类型、运行方式及复盘。缺失信息用 unknown/null，不补造。
4. 共用任务正文放在主题 prompts 下，按版本归档。相同正文可关联不同原始输入；完整输入指纹只统一 BOM 与换行，不删改内容。
5. 历史输入及产物不得覆盖；模型重跑、任务变更和追加迭代新增记录，记录来源和人工修改。新增提示词版本不覆盖旧版。
6. 单文件入口统一 index.html，保留浏览器直接打开能力；多页面显式登记入口。不能将依赖 CDN 的文件标为离线。
7. 按 catalog/schema.json 维护元数据。共享模型、分类和技术主题分别维护 catalog 字典，不将目录结构或标题解析作为数据来源。
   - 模型排序资料保存在 `catalog/models.json` 的 `ordering`：厂商内部按显式登记的 `generation` 代际降序，再按有官方依据的同代能力优先级降序，最后按发布日期降序；缺少日期置于厂商末尾。代际不直接等同显示版本，小版本迭代可明确归入同一代。先执行 `npm run models:pending`，仅对缺少查证记录的型号查询官方资料，保存来源、查证日期及未知原因；已记录的待确认项不反复联网查询，也不从型号、费用或实验截图推断日期与能力。维护者明确要求刷新时可以重新查证。`docs/model-ordering.md` 由 generate 生成，供维护者核对，不手改。
8. 主题的 `testingStatus: archived` 表示停止后续模型重跑，历史输入、源码与预览继续保留。执行“全部案例”等批量实验前，通过 `npm run topics:active` 获取参与主题；不得遍历全部目录重跑已归档主题。用户明确指定归档主题的一次性实验时，可用 `new:demo --allow-archived` 并记录例外；恢复常规测试用 `topic:status restore`，保留原因和状态历史。归档不免除本站目录、链接与历史预览的完整性检查。

## 不同产物的要求

后续案例导入按[维护指南的导入执行顺序](docs/maintenance.md#导入执行顺序)操作；脚本职责与[提交逻辑归纳](docs/maintenance.md#导入规则的提交依据)用于区分人工事实、自动派生和站点公共能力。普通导入复用现有生成器与展示组件，截图选图、排序、搜索及导航由公共代码处理。

新增或导入的实验记录必须支持对比页嵌入展示，入库前确认 `preview.embed: true`，并在对比页中实际打开对应入口。静态 HTML 与构建型前端须验证默认页面；全栈或外部案例须有真实可访问且允许 iframe 的 HTTPS 地址。纯提示词或没有可运行页面的案例，须先提供如实标注的嵌入式记录展示入口；功能尚不支持时暂缓导入，不得用 `kind: none`、空白页或伪造产物绕过要求。`new:demo` 等工作草稿可暂时无预览，但正式入库时必须满足此要求。历史记录按原有事实保留，不为满足此规则批量伪造预览。

新增、导入或更新截图的实验，必须执行下方“截图采集与评分”，完整操作及字段见 [案例评分规则](docs/case-scoring.md)。普通导入直接复用现有工具及当前规则，不另建一套评分方案。

- 静态 HTML：直接登记本目录入口，检查 file://、HTTP 与对比页 iframe；`preview.embed` 必须为 `true`。
- 构建型纯前端：独立 lockfile，通过 build:demo 生成 previews，源码与预览产物同步提交；检查 HTTP、对比页 iframe 和 Pages 子路径。不能将包含 TSX 源码的 HTML 当成 Pages 预览。
- 迁移已完成且可预览的实验时，必须同步迁移对应的真实桌面截图：将 PNG 放在该 run 目录并在 run.json 的 screenshot 字段登记。源分支没有截图但入口可运行时，按实际页面补拍；不得用占位图或主题缩略图代替。
- 全栈或独立部署：保留源码及运行说明；必须有已知可访问且允许 iframe 的 HTTPS 外部地址才可导入并登记 `external`、`embed: true`；地址尚未就绪时暂缓导入，不制造静态预览。
- 仅提示词：保留输入及来源；导入前须提供能在对比页中嵌入的记录展示入口，并明确标识为提示词记录、没有可运行产物。展示能力尚未实现时暂缓导入，不把阅读页或空白页冒充模型产物。
- 不为归档统一升级历史项目依赖或重写 demo。必要部署修复必须在 changes 中登记。
- 导入案例的机械字段由脚本写入，不手工计算：输入指纹、提示词指纹和首次评分指纹用 `npm run demo:sync -- <run-id>` 补写，脚本只处理 `status: "draft"` 的记录，已入库记录的输入属于历史证据，脚本拒绝改写。补写评分指纹只在指纹尚未记录时进行；指纹已存在且与当前文件不一致时说明证据变了，必须重新看图复核，不能只刷新指纹。`npm run demo:sync -- <run-id> --check` 只报告不写入，`--finalize` 在导入清单全部通过后才把 `status` 置为 `ready`。
  - `--check` 与 `--finalize` 互斥；`rated` 和 `insufficient` 的失效评分都阻止入库。已被非 draft 记录引用的任务正文不得通过同步草稿刷新指纹，正文变更新增提示词版本。相关检查见 `tests/demo-sync.test.mjs`。清单通过不等于完成浏览器验收，正式提交仍执行全部提交前检查。

## 截图采集与评分

1. **唯一现行规则**：机器定义仅维护 `catalog/scoring-rubric.json`，人工规则维护 `docs/case-scoring.md`，导入顺序维护 `docs/maintenance.md`。当前为 v3：八项任务检查各 0–5 分，共 40 分；十二项视觉检查各 0–5 分，构成构图 20、可读性 15、操作表达 10、精修 15 分。先观察再独立给分，禁止从旧总分换算。新任务按完整正文登记八项检查并绑定正文指纹，不补造缺失规格。
2. **先预览再采集**：填好 draft 输入及预览，必要时 build，并用 `demo:sync` 同步输入、正文指纹。使用只读本地服务器，通过 `node scripts/capture-screenshots.mjs --run <id> --batch <新批次> --base-url <本地地址>` 采集。桌面 1440×900、手机 390×844、DPR 1，屏蔽正式统计；外部资源失败和运行异常如实记录。批次使用 `YYYY-MM-DD-label`，不得默认复用历史日期或覆盖旧 PNG。
3. **按任务补齐状态**：通过真实控件操作和有界等待补拍结果、上传、其他登记入口、内部导航、纵向懒加载及横向页面。补拍显式指定新批次和来源清单，保留原失败尝试及来源链。不能调用内部函数改状态、伪造网络或相机输入；自动点击日志不代表完整功能验收。
4. **逐图人工复核**：新案例使用 `node scripts/review-captures.mjs --run <id> --batch <最终批次>` 查看完整证据集；已有记录默认读取其 `score.captureManifest`。逐张查看全部帧，小字和长图放大，不只看封面。保存二十项分数、五维具体观察、独立置信度、限制、复核日期及明确的 `reviewedFrames`；工具不识图、不猜分、不自动确认已审阅。
5. **证据状态与封面**：主体可辨才用 `rated`；加载态、空画布或画外主体为 `insufficient`，无真实截图为 `unavailable`，两者不计数值分；`pending` 仅供未完成草稿。明确核心环境阻塞才适用 `blocked` 的 39 分上限。封面必须选自已复核的真实帧。没有可嵌入入口的历史记录保留原状，新导入不能用无截图或无预览状态绕过入库要求。
6. **绑定完整证据**：填写 `captureManifest` 及全部人工复核字段，首次指纹用 `node scripts/demo-sync.mjs <id>` 补写。评分同时绑定输入、任务定义、全局规则、封面、完整证据集和该 run 的全部采集清单；任务、规则、截图或补充清单变化必须重新看图复核。已有指纹失效时不得仅刷新指纹。全部帧、PNG 指纹与尺寸、来源链、加总及上限由 `validate` 检查。
7. **验收入库**：通过 `demo:sync --check` 核对缺项，实际检查 HTTP、对比 iframe、Pages 子路径及 390px，再 `--finalize`。执行完整提交前检查并提交采集清单、原 PNG、元数据、源码及生成站点产物。修订评分时在 `catalog/score-reviews/` 追加旧分、新分、理由和当时规则快照，保留历史证据。
8. **清理过期说明**：替代方案并入现行规则后，可删除过期规则文档、阶段计划和一次性迁移工具；同步修复有效链接。历史评分 JSON、规则快照、输入及真实图片属于证据，不能作为过期说明一并删除。历史快照不作为新案例的现行规则；`generate` 清除不再生成的阅读页，`validate` 拒绝残留旧阅读页。

## 首页与文档

- 首页卡片、筛选、统计、主题版本和对比候选均从生成数据读取，禁止手写卡片或人工维护项目计数。
- 采集截图同时用于作品浏览：完整截图集从已登记的采集清单生成，首页预览、主题页、对比页和实验阅读页复用公共入口。截图数量由生成数据提供，不手填；截图集按需加载当前图，对比各侧独立选择取景并保留分享状态，不暗示同步操作或同一时刻。只新增浏览入口不改写评分、输入或原 PNG。实现和边界见[维护指南](docs/maintenance.md#截图浏览与复用)。
- 主题页实验记录默认按截图评分排序，这是一套独立于模型排序的顺序；模型代际排序只在用户显式选择 `sort=model` 时使用。评分排序的并列规则与无评分记录的位置见[维护指南](docs/maintenance.md#主题页浏览)。
- assets/generated/catalog.js、阅读页、截图缩略图与竖图封面、主题 Readme、根 README 的 catalog 区块和实验 README 的 archive 区块由 generate 维护，禁止手改。导入截图时只登记真实 PNG；派生图由生成器创建，细节见[维护指南](docs/maintenance.md#生成的站点资料)。
- 根 README 的开发时间线和实验复盘为人工内容，生成器不得覆盖。
- 站点样式按页面归属放置：跨页面共用的规则放 `assets/polish.css`，页面专属规则只放该页的样式表（`home.css`、`topic.css` / `topic-lifecycle.css`、`compare.css`、`screenshots.css`），共用组件放 `assets/site.css`。同一选择器不写在多个文件里，`npm run validate` 的样式重复闸门保持跨文件重复选择器与同文件完全相同声明都不增加。案例自身的样式仍归对应 run，导入案例不需要调整本站样式表。
- 新技术主题在 docs/{slug}/ 保留 Readme.md 与可运行示例，同时登记 catalog/guides.json。
- Google Analytics 统一通过公共脚本 `assets/analytics.js` 接入，测量 ID `G-8E54P1HX3G` 和初始化逻辑只在该脚本维护，不在页面复制 Google tag。后续新增或导入实验记录时，生成的实验阅读页及本仓库可维护的网页入口（静态 HTML 各页面、构建型项目入口与 previews 产物）都必须用带 `defer` 的 script 标签引用公共脚本，并按入口位置设置可用路径，兼容根路径与 Pages 子路径。阅读页由生成器统一添加引用；预览入口在源码中添加，构建型实验须重建预览。维护者追加引用须在 run.json 的 changes 登记，不修改原始输入，也不为补统计批量改写历史实验产物。仅提示词或无网页入口的记录由阅读页承载统计；外部部署继续遵循既有人工部署约束。代码和检查方式见[维护指南的访问统计要求](docs/maintenance.md#访问统计)。
- CLAUDE.md 只引用本文件，不复制第二套规则。

## Git 提交信息

- 标题使用 Conventional Commits 格式：`<type>(<scope>): <中文摘要>`；scope 使用简短模块名，没有合适范围时可省略。type 根据实际改动选择 `feat`、`fix`、`docs`、`refactor`、`style`、`test`、`build`、`ci`、`chore` 或 `revert`。
- 标题和正文以中文描述改动，技术名词、文件名、命令和必要的原文可以保留。标题说明提交带来的结果，简洁具体，不写空泛的“更新”“优化”或模型提示词式任务指令。
- 正文按实际改动填写概述；普通提交统一使用以下结构。没有实际变更的栏目可省略，不猜测缺失背景或未执行的验证。

  ```text
  <type>(<scope>): <中文摘要>

  变更说明:
  - <概括改动及其影响>
  - <必要时说明验证、来源或边界>

  文件列表:
  - <本提交涉及的路径>
  ```

- 变更说明应概括改动目的、主要行为和必要验证；涉及实验数据时注明来源、人工修改与信息边界。文件列表仅列本提交实际修改的路径，文件较多时可按目录归并，不列未改动文件。
- 合并、回滚等特殊提交应如实说明其关系或回滚对象；改写历史提交信息时保留原提交所能证实的事实，不根据当前文件状态推断历史原因。

## 提交前检查

1. 若修改构建型实验源码或构建配置，先 `npm run build:demo -- <id>`；文档修改不要求重建。
2. 执行 `npm run generate`、`npm run validate`（包括截图派生资源、阅读页标记及本站 CSS 重复闸门）、`npm test`、`node --check assets/home.js` 和 `git diff --check`。
3. 首页或对比交互变更执行 `npm run test:browser`，覆盖目录计数、筛选、搜索、排序、视图和加载更多；同输入、异输入、无预览、分享恢复、移动端与子路径。
4. 用本地静态服务器检查新增入口、原始输入、已登记的预览图和首页生成的链接；390px 移动端无页面水平溢出。单 HTML 额外验证直接打开。
5. 目录迁移核对完整性、旧目录消失及有效链接更新。迁移清单和原始历史输入中的旧路径作为证据保留，不做机械替换。
6. 确保 previews 和 assets/generated 不被忽略；无 node_modules、缓存或中间 dist 误提交。干净检出无需构建即可预览站点。
7. 新增或导入实验时，核对阅读页和可维护的网页入口均引用 `assets/analytics.js`，路径在根路径和 Pages 子路径下可用；页面不重复内联 Google tag，公共脚本使用 `G-8E54P1HX3G` 异步加载且每页仅初始化一次。统计服务不可用不能阻止页面功能或离线预览。验证脚本加载与初始化时使用拦截或模拟，避免向正式统计发送测试访问。
8. 新增或收紧规则时，同时补一条能自动判定违反的检查（`npm run validate` 的闸门或一条测试）；只有文档没有检查的规则会在下一次改动时失效。
9. 改动首页、主题页或对比页的渲染结果时，同步更新 `tests/browser/style-baseline.spec.mjs` 里的计算样式钉子；钉子值变化等于页面外观变化，要在提交信息里说明改了什么。图片槽位宽度变化时一并核对 `sizes` 声明与实际渲染宽度一致。

## 对比边界

区分原始输入一致、任务正文一致、同主题不同输入、跨主题及信息不足。注明工具、档位、人工修改和上下文缺失。默认独立操作，不暗示同步相机或公平性能评测。外部不可嵌入时保留独立打开；双开 3D 提供单侧卸载，手机只加载当前侧。