Archify 贡献指南基于证据的 PR 流程、本地验证与可复现产物【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一个Agent 优先的绘图 Skill 仓库人描述系统由 Skill、类型化 JSON、渲染器、校验器与交付回执共同产出可复现的图表。本文以 CONTRIBUTING.md 为核心完整拆解该仓库为贡献者设计的贡献路径、按影响分级组织证据、本地验证命令以及生成产物Gallery、Guide、ZIP 包的可复现性约束并结合 archify/package.json 与 scripts 下的构建脚本说明其背后的实现依据。读完后你将掌握在该仓库提交一个可被审查、可被 CI 接受的变更所需的全部流程与命令。贡献的总原则一个行为一个切片CONTRIBUTING.md 开篇就定下了基调每次贡献应聚焦于一个用户可见的行为或一个紧密相关的交付切片one user-visible behavior or one tightly related delivery slice。维护者与负责审查 PR 或修订后 head 的 Agent 统一遵循 REVIEWING.md。这一切片化原则贯穿了后文对证据分级、影响分类和产物管理的整套要求。选择正确的入口路径贡献前先判断变更类型走对应通道渲染器、校验器、包或 Viewer 缺陷使用 bug report 表单可复现的真实图表案例使用 showcase 表单新的 schema 字段、默认值、验收规则、安装/导出契约或大范围产品行为在动手实现前必须先就价值、兼容性与非目标达成一致并链接 issue 或维护者的书面决策或复用已有的已达成共识的范围窄修复和小的文档/测试修正只要有具体复现步骤或理由即可直接推进无需单独开规划 issue安全漏洞遵循 SECURITY.md。上述 issue 模板在仓库中真实存在.github/ISSUE_TEMPLATE 下包含bug-report.yml、showcase.yml与config.yml与文档描述一一对应。此外有一条硬性红线不得在 fixtures、日志、截图、产物或包测试中包含密钥、访问令牌、凭据、私有仓库内容、个人数据或客户数据。准备一个可审查的变更标准流程分三步走从最新main出发先检查现有控制是否已能解决所报告的问题并记录比较基线base与候选头candidate head未定范围或早期实现反馈阶段使用 Draft此阶段只需提供最小复现与相关检查方案定型后再补齐大范围集成证据与生成产物请求最终审查前必须说明三件事在最新 main 上的触发条件、预期结果以及该方案为何值得长期维护被改变的行为与共享调用方、必须保持稳定的既有行为以及任何有意为之的兼容性变更适用的检查项、实际结果以及可复现的证据链接。PR 需使用 PULL_REQUEST_TEMPLATE.md。该模板当前包含五个小节Problem and value触发条件与价值、Stability impact影响类别、被保留的既有行为与兼容性变更、Tests run比较基线、命令与结果、被复用的证据及其原始 revision、Visual evidence对比条件、自动化/浏览器检查与感知评审分别报告、Generated artifacts重新生成的文件或构建证据。模板内多处直接以锚点形式引用CONTRIBUTING.md#choose-evidence-by-impact说明模板与本文档是同一契约的两面。证据组织上有一个重要细节链接已有的回执receipts或 CI 输出而不是转录冗长日志影响分类依据行为与调用方而不是文件扩展名或 diff 大小。按影响分级选择证据这是 CONTRIBUTING.md 中信息密度最高的部分。证据要求与影响面挂钩完整表格如下影响级别典型变更需要准备的证据文本或评审政策说明性文字、链接、贡献者/评审者流程内容与链接、受影响的文档检查演练被修改流程的分支。纯仓库内文字不需要跑本地渲染器套件。局部行为单条 CLI 路径、聚焦的测试修正复现或理由、受影响的测试以及相关的失败/兼容性用例。共享行为几何、文本测量、共享 Viewer、证据或交付辅助工具追踪调用方识别受影响的模式与契约在 base 与候选上用同一份代表性输入对比包括相关的历史失败。契约变更Schema、默认值、校验验收、Skill 或 authoring 指令已达成共识的范围与明确的允许/保留行为加上与实现匹配的局部/共享证据。表格之后还有两条容易忽略的边界规则Skill 指令、手写示例、构建输入与生成站点源码即使看起来像文档也是行为输入。政策类变更需要流程评审是否需要运行时证据取决于它们是否影响运行时输入。迭代期跑最窄的相关检查最终审查前凡涉及运行时、schema、打包的 Skill/authoring 行为、生成内容或共享测试基础设施的变更必须从archify/目录运行npm test。纯仓库文档与聚焦的测试修正可用定向检查加说明代替。这些本地选择不能豁免远端 CI 或分支保护要求。从 archify/package.json 可以看到npm test的实际构成test: npm run check:brand-marks npm run check:validators npm run check:release-identity node test/golden.mjs node ../scripts/run-tests.mjs也就是说一次npm test依次执行品牌图标基线检查archify/scripts/generate-brand-marks.mjs 的--check模式、校验器一致性检查、发布身份检查scripts/check-release-identity.mjs、黄金文件测试 archify/test/golden.mjs最后由 scripts/run-tests.mjs 扫描archify/test/下全部*.test.mjs并用node --test执行Node 18.19 会附加--test-concurrency2。这也解释了为何纯文档变更可以豁免npm test——它本质上是运行时与产物的完整性闸门。产品与兼容性契约CONTRIBUTING.md 明确了六条不可随意突破的契约贡献者修改相关代码时必须对照schema-v1 的类型化 JSON 持续有效除非经评审的变更显式引入破坏性规则并给出迁移路径显式的手写几何via、命名路由、channels、sides、标签位置保持权威除非契约另有说明要保留手写拓扑与意图standard档位保持宽兼容性。新的showcase失败必须指向真实、可修复的缺陷且不得拒绝必要的路由面向 Agent 的失败必须落在diagnostics[]稳定的code、精确的subject、具体的evidence、可执行的supportedFixes失败阶段要保留非零 CLI 退出码与机器可读回执表达品味的校验规则应以证据或警告起步升级为硬错误前必须核查合法障碍、共享端口、显式路由、嵌套边界与既有示例每个行为只保留一份规范契约canonical contract链接既有出处而不是复制 CLI 阶段、回执字段或错误表。第 4 条对应的失败结构与archify/references/下的交付契约文档保持一致可对照 archify/references/delivery-contract.md 理解diagnostics[]与回执的字段语义。本地环境与验证渲染器包位于 archify/ 目录其 Node 版本区间与命令由 archify/package.json 定义engines声明node 18。基础三步cd archify npm ci npm test通过公开行为测试文档强调通过公开行为进行测试例如render、validate、deliver、visual-check或最终的 SVG/HTML行为修复应附带一个能复现原始失败的回归测试私有 helper 的检查只能作为补充证据。这与仓库的测试组织方式一致archify/test/下超过百个*.test.mjs大多面向 CLI 输出、渲染结果与 XML 结构如 archify/test/golden.mjs 的黄金对比、archify/test/visual-check.test.mjs而非内部函数。几何与布局变更的对比方法对几何与布局类变更规范要求使用最小的、已脱敏的 JSON 复现、相关的已入库示例与冻结的兼容性 fixtures仓库中 archify/test/fixtures 即为此目的保留包含v1-baseline/等基线集合在相同的输入与浏览器条件下对比 base 与候选区分有意变更与意外变更并逐一排查仅更新 golden 文件本身不构成视觉或兼容性验收。视觉 PR 的证据要求视觉类 PR 必须提供足以评估预期用户价值是否达成的证据截图、录屏或可复现步骤并保持 viewport、主题、preset、图表模式、缩放与页面状态可比自动化/浏览器证据与感知评审必须分开报告。非视觉 PR 必须在 Visual evidence 小节写明Not applicable并解释原因——这一要求直接对应 PR 模板 中的 Visual evidence 一节。浏览器测试skipped 不等于 passed静态 SVG/XML 检查无法建立关于浏览器布局、字体落定font settling或交互行为的结论。当自适应阅读器或 Viewer 布局变化时需要在 Chrome 可用时运行真实浏览器测试cd archify ARCHIFY_CHROME/path/to/chrome node --test test/desktop-reader-browser.test.mjs对应测试文件为 archify/test/desktop-reader-browser.test.mjs。关键规则因 Chrome 不可用而被跳过的浏览器测试是 skipped不是 passed。视觉证据、回执与失败阶段的划分遵循 交付契约验证通过、原子交付、浏览器检查、感知评审分别建立不同的结论不能互相替代。包与生成产物字节级可复现这是 CONTRIBUTING.md 中最工程化的章节。核心要求已发布的产物必须能从受跟踪tracked内容复现。操作上使用 tracked-only、符号链接安全的 staging 路径或显式 allowlist并对未跟踪文件与外部符号链接做负向覆盖提取后的包需要在仓库外的目标宿主上实测。重新生成的命令先评审源码与聚焦测试再重新生成产物只重新生成权威输入发生变化的输出且必须从最终合并后的源码出发node scripts/build-gallery.mjs docs node scripts/build-guide.mjs docs/guide.html node scripts/build-start.mjs docs/start.html node scripts/build-readme-showcase.mjs scripts/build-zip.sh /tmp/archify-contrib.zip五个脚本在仓库中均实际存在scripts/build-gallery.mjs、scripts/build-guide.mjs、scripts/build-start.mjs、scripts/build-readme-showcase.mjs 与 scripts/build-zip.sh。对应的测试契约可参考 archify/test/gallery.test.mjs、archify/test/guide-page.test.mjs 与 archify/test/readme-showcase.test.mjs。为什么 ZIP 构建硬性要求 Node 22文档说规范 ZIP 字节需要 Node 22构建器拒绝其他主版本以避免不同的 zlib 表示。scripts/build-zip.sh 中的实现印证了这一点canonical_node_major22 node_version$(node -p process.versions.node) node_major${node_version%%.*} if [[ $node_major ! $canonical_node_major ]]; then echo canonical archify.zip builds require Node $canonical_node_major (current: $node_version) 2 exit 1 fi其设计考量在脚本注释里写得很清楚运行时消费者支持archify/package.json声明的所有 Node 版本但规范 ZIP 字节取决于 Node/zlib 工具链CI 与发布统一使用 Node 22因此在其他主版本上宁可失败也不产出不同字节。staging 与打包分别由两个脚本承担。scripts/stage-clean-skill.mjs 负责 tracked-only 选择、索引模式、冲突与符号链接拒绝、仓库内排除项及 package.json 清理ZIP 与 DeepSeek Harness tarball 共用同一 stagerscripts/write-deterministic-zip.mjs 则手写 ZIP 格式来保证确定性其实现细节包括目录项按字节序排序Buffer.compare保证条目顺序稳定write-deterministic-zip.mjsDOS 时间戳固定为 ZIP 允许的最早时间 1980-01-01DOS_DATE 0x0021不记录真实修改时间统一使用deflateRawSynclevel 9、memLevel9、Z_FIXED策略并自实现 CRC32拒绝符号链接与非普通文件触碰 ZIP64 边界即抛错先写临时文件、fsync后原子rename避免留下半成品 ZIP。这些手段共同保证相同的受跟踪内容在任何构建机上产出相同的 ZIP 字节。版本与差异纪律重新生成后要列出重新生成的文件并解释未变化的输出为何仍然新鲜生成文件冲突通过从合并后的源码重建解决无关生成产物不得进入 diff已发布版本视为不可变。常规功能 PR 不得变更版本号、tag 或分发身份除非发布工作被显式纳入范围。版本一致性由 scripts/check-release-identity.mjs 在npm test链条中把关archify/package.json 中的check:release-identity即调用它。最终集成与后续跟进合并前的最后一段流程同样以证据有效性为主线最终集成前刷新main与 PR head处理相关基线变更并解决冲突证据因刷新而失效的检查要重跑未失效的证据可以链接其原始 revision并说明复用理由但不得把它重新标注为新 head 上的运行结果确认所需远端 CI 确实在最终 head 上执行过并遵守分支保护——零检查不算绿修订后应总结自被审查 head 以来改了什么、对应解决了哪些 findings让评审者聚焦新 diff 与未决决策。Showcase 提交需要包含prompt、Agent/客户端、模型、Archify 版本、脱敏 JSON、产物、回执与诚实的视觉评审状态。维护者可以要求更小的安全复现保留署名文档特别提示showcase 的接受不等于受控的模型质量基准仓库中 benchmarks/ 目录正是为此目的单独设立的普通模型基准。自动化评审试点CodeRabbit本仓库启用了 CodeRabbit GitHub App根目录.coderabbit.yaml请求对 ready PR 及其后续 push 自动评审并以本指南、REVIEWING.md 与 PR 模板作为建议性范围与验证证据检查的依据。其定位被明确限定为建议性Draft 被排除在自动评审之外证据缺失是请求澄清不是代码缺陷的证明误报应在 PR 中解释CodeRabbit 不替代必需 CI、浏览器/感知验收也不替代维护者的合并决定两个 warning 检查分别覆盖贡献范围与验证证据内置的重复 issue 评估被禁用。触发与控制的 PR 评论命令场景PR 评论自动评审未运行时评审新提交coderabbitai review只更新了 PR 描述、证据链接或 CI 完成coderabbitai run pre-merge checks需要全量重新评审coderabbitai full review多轮快速修订进行中coderabbitai pause就绪后coderabbitai resume文档同时约定不要用空提交触发 bot命令被确认acknowledged不代表完成需查看更新后的 summaryfork CI 需要维护者审批 workflow 时作者应链接等待中的运行并继续自己能做的检查而不必也不应自行授予 CI 权限。维护者应在前 5–10 个被评审 PR 上评估有效发现、误报率、评审时间与重复证据请求再决定是否扩大试点将reviews.auto_review.enabled设为false可暂停自动评审这不影响 CI 与分支保护。许可以贡献者身份提交即同意仓库的 MIT License只提交自己创作或拥有贡献权利的作品。小结Archify 的贡献体系可以浓缩为三条主线入口分流缺陷 / showcase / 契约变更前先共识 / 安全、证据按影响分级从纯文本到 schema 契约证据要求单调递增、产物字节级可复现Node 22 的规范 ZIP、确定性打包、版本不可变。对贡献者而言最需要内化的不是命令本身而是证据与声明一一对应的纪律skipped 的浏览器测试不是通过仅刷新 golden 不是视觉验收零 CI 检查不是绿。遵循这套流程你的变更才能同时通过本地npm test、远端 CI 与 REVIEWING.md 所定义的审查标准。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考