archify-tuning

Archify 调优

用户描述一个系统，由 Agent 编写图表。优化从理解源信息到交付可用产物的完整过程。优先级如下：

1. 准确：事实、关系、方向、条件、所有权和来源都与系统相符。
2. 清晰易读且美观：阅读路径清晰、连接易于区分、文字清晰可辨、构图均衡。
3. 高效：端到端交付时间短、修复失败少、重复工作少。

测试和验证器旨在实现这些结果，它们本身也可以改进。 检查通过并不能证明图表质量好；检查失败也可能暴露规则不合适。决定更改什么之前，先评估产物和编写体验。

产品要求和可调整规则

• 保护源信息中的事实和有依据的用户行为。初稿可能有误：保留原稿，并记录有来源依据的修正或补充。已删除元素的数量可提示需要进行语义审查，但不能据此判断编辑是否正确。
• 将间距、首选方向、折线数量和单屏适配视为需要结合具体情况评估的设计策略。增加折线或允许清晰地滚动浏览，可能让整张图表更好。除非双方同意的更改涵盖这些内容，否则保留明确指定的几何布局和有依据的约定。
• 修复检查失败之前，先明确该检查旨在防止对用户造成什么伤害，以及这种伤害是否确实存在。对于不合适的规则，应调整其适用范围、阈值或严重级别；更新或弃用过时的测试，并说明理由以及实际前后对比证据。保留原始失败记录。仅更改预期值并不能证明有任何改善。
• 对于衡量相同要求的早期诊断和浏览器检查，两者的结果应一致；在衡量范围不同的地方，应说明各自的范围。任何一方都不是不容置疑的权威。无法可靠评判的审美偏好，可作为建议或视觉审查内容，而不必设为硬性失败条件。

衡量指标

角色	指标	证据
结果	最终交付准确且视觉上合格	源信息审查和实际截图；将机器检查通过与视觉验收分开记录
结果	总耗时、修复失败次数和重复工作量	从任务开始到阅读、初稿、修复、查看和交付的计时记录
流程	初稿质量及首次产出可用结果所需时间	保留首次尝试、每次失败和最后一个经过验证的可用产物
回归	固定输入的通过/失败情况及输出变化	replay.mjs、受影响的测试和视觉对比；渲染通过不代表通过 finalize/浏览器验收
诊断	折线、交叉、路径长度、文字大小和 CLI 耗时	说明实际观察到的收益或权衡；这些指标都不能替代对整张图表质量的评估

分别报告已交付的结果和失败/未完成的任务。失败运行结束得更快，并不意味着速度有所提升。将合成回归与冻结的初稿分母分开；加入语料库的内容应构成有版本记录的批次。修复后的初稿绝不能替代其原始基准条目。

设置

• 调优目录：$ARCHIFY_TUNING_HOME，默认为 ~/.local/share/archify-tuning。其中存放 journal.md、bench/、rounds/ 和 replays/。该目录位于仓库之外，因为草稿包含源项目的内容，而这些项目可能是私有的：切勿提交该目录。
• 恢复工作：读取日志、可用的检查点和当前目标状态。尊重暂停状态和先前的产品决策；继续进行中的轮次，而不是重复创建。使用用户选定的图表类型；如果共享更改会影响其他类型，也要涵盖这些类型。
• 版本：刷新目标远程版本，并记录源、基线和候选版本的标识。使用独立的持久化工作树或冻结快照。记录远程版本的变化，但不要覆盖比较基线或正在运行的作者的运行环境。
• 证据选择：遵循根据影响选择证据。未发生变化的证据应沿用，并保留其原始版本和范围。
• 工具：运行 shots.mjs 需要 Node 22.13 或更高版本，以及 Chrome 或 Chromium（ARCHIFY_CHROME 可覆盖自动查找结果）。采集器接受 Devin CLI 历史记录，或来自其他 Agent 的标准化跟踪导出。它不会读取其他 Agent 的私有历史数据库。

循环

1. 界定问题。 在日志中记录一个用户可见的问题、假设、可支持或证伪该假设的证据，以及时间／尝试次数预算。按发生频率、危害、预期收益和持续复杂度确定优先级。开始新一轮生成之前，优先使用现有证据。
2. 选择实验。 对渲染器／规则更改使用固定 JSON；验证指令或完整流程的主张时，使用彼此独立且可比较的作者；发现问题或检查可迁移性时，使用新项目。对于作者运行、计时或截图比较，请阅读实验设计。发现问题并不能证明有所改进。
3. 归因。 阅读跟踪记录，并使用跟踪信号检查完整图表。记录主要原因、促成因素和不确定性。区分源文件理解错误、放置、路由、诊断、指令可用性和不合适的验收规则。归咎于路由器之前，先使用有效放置方式复现；有文档说明某条规则，并不能证明该规则有用或易于应用。
4. 仅更改责任范围内的最小部分。 修复运行时之前，优先构建最小复现。更改共享路径前，先检查其他调用方。评估路由时，应一并考量主路径布局、相互作用的模块、分支／合并空间和返回路径。将实验性放置方式保留在副本中；自动路由修复必须遵守作者设置的固定点。只有确认存在信息缺口时才添加指导，然后评估作者是否因此受益。
5. 验证主张。 选择受影响的公共行为测试和固定输入；如果现有覆盖未能捕获已证实的运行时缺陷，则添加回归测试。使用相同的视口和状态检查更改后的输出。调查每项通过／失败结果的变化，并用证据区分实际回归、已纠正的误报和预期的规则更改。未能解释的失败仍须保持未解决。局部改进必须经受完整图表和相关对照案例的检验，才能采纳。仅在权威输入发生变化时，才重新构建生成的输出。
6. 总结并整合。 记录已确认的事实、已否决的方法、尚存问题，以及以下处置之一：已确认的问题、已验证的局部修复、实验性候选方案、已否决的方法，或可供独立审查的候选方案。说明视觉效果、速度和泛化方面主张的局限。确认收益后，准备小型且易于审查的更改；将无关修复和原型分开。按照 CONTRIBUTING.md 进行集成；此技能不授予推送、PR、合并、发布或在线安装的权限。

何时停止实验

• 达到预算上限时，记录结果和剩余的不确定性。只有提出具体的新假设并开展新的限时测试，才继续实验。
• 如果尝试反复进行却没有新的因果证据、依赖项目特定的坐标搜索、改善了选定行却使整个图变差，或新增的复杂度与收益不成比例，就停止实验或转移重点。
• 将最后一个已验证的产物与未成功的实验分开保存。结束一项实验并不代表整体目标已经完成。先整合有用的修复，再开始下一批实验。

工具和报告

从仓库根目录运行；这些工具为选定的实验提供证据，但不要求每轮都按固定顺序使用。round、collect 和 replay 在不带参数时会打印用法。

需求	命令
固定输入对比	node .agents/skills/archify-tuning/scripts/replay.mjs --base <base>/archify
准备作者任务	node .agents/skills/archify-tuning/scripts/round.mjs <project-path> --types <selected-types> --archify <frozen-runtime>/archify
收集跟踪记录和内容变更信号	node .agents/skills/archify-tuning/scripts/collect.mjs <round> --dump（在 Devin 环境外添加 --trace-export <file.json>）
浅色主题的初始图像对比	node .agents/skills/archify-tuning/scripts/shots.mjs <replay-dir> --height 900

收集器无法确认语义正确性，也无法记录完整耗时；应补充源代码审查和计时记录。保留失败日志和未知结果。诊断应指出受影响的元素和已验证的修复方案，或说明未找到修复方案。作者指南应简洁易查，并纳入必读内容；避免不断累积没有实际收益的建议。