贡献指南：开发环境、规范与流程
欢迎任何规模的贡献——从修正一个错别字到添加一条新规则。这一页提供动手所需的全部实用信息；项目的价值边界（什么会被接受、什么不会）见开源总览。
先说清楚仓库结构
需要被审查的是工具——它是否真的不上传数据、不扫描网络、不解析订阅内容。所以公开的是工具：CLI、诊断规则库、各检测包与浏览器端检测代码，连同 LICENSE、SECURITY、THREAT-MODEL、RESPONSIBLE-USE 一起，在 connproof-tool 仓库，MIT 许可。
站点内容与运营配置不在公开仓库内。它们不影响工具的任何一条行为承诺，那些承诺全部由公开代码实现，可以逐行核对。
公开仓库是从主仓库导出的只读镜像——主仓库是唯一的事实来源，镜像内容由脚本生成，避免两处维护造成漂移。这带来一个直接后果：镜像仓库不接受 Pull Request，直接提交会在下次同步时被覆盖。有效的参与方式见下方提交你的改动。
环境搭建
需要 Node.js 20+ 与 pnpm 9+：
pnpm install # 安装全部 workspace 依赖
pnpm typecheck # 类型检查（同时构建各包的 dist）
pnpm test # 运行全部测试（本地 fixture，可离线）2
3
常用命令速查
公开仓库中可用：
| 命令 | 用途 |
|---|---|
pnpm lint | ESLint 检查 |
pnpm typecheck | 类型检查（同时产出各包 dist） |
pnpm test | Vitest 全量测试 |
pnpm validate:rules | 规则库完整性校验 |
pnpm build | 构建各包与 CLI |
pnpm verify | 以上全部，提交前跑一遍 |
另有几条只在主仓库有意义，因为它们校验的是站点文档：validate:docs（frontmatter 与内容规范）、validate:links（站内链接完整性）、validate:rules 的规则↔文档配对部分（公开仓库用 --skip-docs 跳过）。
代码规范
- TypeScript 严格模式，ESM，Node 内置模块优先——CLI 不引入运行时第三方依赖；
- 检测器遵循统一模式：返回
status + matchedRuleCode + evidence，无法判定时用 unsupported/inconclusive，不编造结果； - 测试用
@connproof/test-fixtures的本地服务器，禁止依赖公网； - 注释解释"为什么"，不复述"是什么"。
文档规范
- 错误页遵循统一模板（见任意现有错误页），结论前置，正文 ≥1400 中文字符且内容针对该错误定制；
- 频繁使用限定表达（"更可能是"“仍需确认"），禁用绝对化断言（"一定是"“100% 解决"）；
- 不虚构测试数据、案例与成功率；
- frontmatter 的 errorCode/severity/lastVerified 必须与规则库一致。
提交你的改动
因为公开仓库是只读镜像，改动走 Issue 而不是 PR。这不是把门关上，而是避免你的工作在下一次同步时被覆盖。
- 开一个 Issue，用仓库提供的三类模板之一：Bug Report（附脱敏报告与复现步骤）、Diagnostic Rule（新规则提案）、Documentation Correction（文档修正）；
- 说明动机与验证方式；涉及规则或文档内容的，附上依据（RFC、官方文档或可复现实验）；
- 代码改动可以直接把 diff 贴在 Issue 里，或 fork 后给出分支链接——评审在 Issue 中进行，合并在主仓库完成；
- 改动在主仓库落地并通过 CI 后，会随下一次同步出现在公开仓库，变更记录进 CHANGELOG。
不方便用 Issue 的话，也可以来信，地址见联系与友链。
任何 Issue 中禁止出现完整订阅链接、密码、Token、私钥或验证码——先用脱敏报告。
安全红线
以下改动会被直接拒绝，无论实现质量：上传任何用户数据、解析/转换/合并订阅内容、网段扫描或批量端口枚举、绕过证书验证并标记为安全、漏洞利用或认证绕过。发现安全漏洞请走私密渠道（见仓库 SECURITY.md），不要公开披露细节。
许可
项目采用 MIT 许可证。提交贡献即表示你同意你的贡献以相同许可发布。