文档中心/项目规则
生效中v1.2 · 2026-09-04

Project Governance

Perfowl 调研与开发规则

约束从开源项目调研、方案形成、批准、开发、验证到本地提交的完整过程，确保每个结论都有证据、每个变更都有回滚点。

当前生效调研优先计算可复核本地提交v1.2 · 2026-09-04

核心规则

  1. 先分析，后开发

    外部项目先完成代码、架构、依赖、口径、风险和适配价值分析，并形成文档。只有收到明确批准后，才修改 Perfowl 产品代码。

  2. 所有成果进入文档区

    2026-09-04 起，新文档一律以 Markdown + frontmatter 写入 site/（知识库 / 开发记录），并按根目录 AGENTS.md 的注册规则登记；docs/ 冻结为只读归档，继续作为站点 /archive/ 的原文链接源。阅读页面不得依赖外部 CDN。

  3. 开发完成后本地提交

    每个批准后的开发批次完成匹配验证后，形成一个范围清晰的本地 Git 提交；除非另行要求，不自动推送远程。

  4. 结论与证据分层

    静态代码、构建结果、受控环境、真实设备分别标注。未做真机验证的能力不得描述为已可用。

  5. 小步、可逆、可追踪

    方案按独立能力拆分，优先验证最高风险链路；提交只包含本阶段文件，不混入无关变更。

  6. 口径优先于曲线

    每个性能指标明确来源、对象范围、单位、采样频率、误差、缺失和过期规则，图表不得掩盖数据口径问题。

  7. 指标计算方式必须落到文档

    每个指标在进入代码、界面或报告前，必须在 docs/ 记录原始字段、转换公式、单位换算、scope、采样窗口、聚合/差分、缺失与重置处理、取整规则、算法版本和证据来源。公式变更先更新对应 HTML，再更新代码与测试；历史 Session 只通过版本化派生层重算，原始数据保持不变。

标准流程

1 · 输入开源仓库、竞品或需求
2 · 调研固定版本，检查核心链路
3 · 文档证据、风险、建议和边界
4 · 公式字段、公式、版本和测试向量
5 · 批准确认阶段范围和验收
6 · 开发最小实现与匹配验证
7 · 提交本地 Git 提交并更新文档
批准边界
“继续分析”“把方案写细”仍属于调研；“按方案实现 / 开发 / 开始做”才进入产品代码修改。

站点与文档产出（v1.2 增补 · 2026-09-04）

官网与文档由 site/ 下的 VitePress 站点承载：知识库面向使用者（一指标一页、八要素齐全），开发记录含八阶段进度看板、未关门门禁与最新置顶时间线。要点：

规则要求
格式新文档 Markdown + frontmatter 写入 site/；docs/ 冻结只读，构建时自动同步为站点 /archive/
状态词表devlog：approved / implemented / validated / partial / blocked / superseded / paused；knowledge：published / superseded；禁止自造
注册联动knowledge 页登记 site/.vitepress/config.ts 侧栏；devlog 批次在 site/devlog/index.md 时间线顶部追加节点并同步进度看板与门禁表——漏一即视为交付未完成
双写指标口径 / 公式 / 质量语义变更时，同批修订对应知识库页（版本 +1，changelog 链回来源批次）
不变性已发布文档与验收数字不改写；修订用新版本 + supersedes，后续变化以 update 增量段追加
品牌站点复刻 PerfDog 信息结构与深色气质，但必须使用 Perfowl 自有 Token 与猫头鹰品牌（品牌规范 v1.1）
完整规则
AI 协作者必须先读根目录 AGENTS.md（含 frontmatter 模板、八要素与时间线节点格式）；本页为摘要与决策记录。

证据等级

等级含义允许的结论
E1 静态代码、配置、依赖和协议路径已检查“代码声明 / 实现了……”
E2 构建语法、单测、构建或产物检查通过“可构建 / 产物包含……”
E3 环境干净目录或受控环境运行通过“在该环境可启动 / 可完成……”
E4 真机指定 iOS 版本和设备实际采集并对照“在已测设备上指标有效，误差为……”