Attest: Instructions file for Claude Code

Attest 开发规则

可信、自证的网页 agent 内核。从 SkillFlow/FlowOps 干净重写而来。 本文件是这个仓库的开发地基——只保留真正用得上的要领，砍掉重复冗杂。

一、架构红线（永不违反）

这些不变量定义了 Attest，是它区别于"抓取式 agent"的根本。任何改动都不得破坏：

1. 模型只提议，harness 校验后才执行。模型给的 ref 必须命中页面真实暴露的对象，否则返回 error、绝不执行。不许猜 selector/id/route。
2. 读写分离。读路径无写工具；写工具单独成组；高危动作永远 held（默认拒绝）。
3. Verify-or-refuse。每个写动作用"可观察变化"验证；finish 的 outcome（completed/failed/cancelled）由 Evidence Ledger 的证据算出，不信模型自述。
4. 页面契约是地基。任何实现 data-agent-object/action/control/surface 的页面，零额外代码即可被驱动。不许把某个业务页写成专用脚本作为主路径。
5. 记忆只加速，不背书。Page Memory 命中就零-LLM 重放，但 verifier 始终是唯一真相；记忆失效只回退、绝不谎报或乱动；高危动作重放时仍 held。
6. 协作式赌注。Attest 服务"实现契约的页面"，不啃任意陌生站点。别把"无契约 DOM 降级/抓取"做成主路径（如要做，必须先 brainstorm 当独立切片）。

二、开发流程（按改动大小裁剪，别一刀切）

核心原则:流程配得上改动的大小。小改直接干,别为动几行码写一堆文档——那是负担,不是严谨。

• 小改 / 局部 / 纯函数 / 修 bug:直接做。有逻辑/边界/会回归的走 TDD(红→绿→commit);改完跑 npm test 绿了就提交,不写 spec/plan。
• 只有两种情况值得先写下来:① 改核心不变量的语义(loop/verifier/ledger/memory 的判定逻辑)且方案不显然——提交前用几句话(commit body 或一小段 note)说清"为什么这么改、碰了哪条红线";② 跨多回合的大切片——才值一份简短 plan。其余一律省。
• brainstorm 只在真有分叉时用:有多条路要选、或要改架构红线的取舍时才坐下来对齐;不是每个切片的固定关卡。
• 红线不裁(§一 永远守):verify-or-refuse 不松;行为变更在声称"完成"前仍要真模型 live 验收——纯重构例外(绿的既有套件即证行为未变);诚实报告、conventional commits 照旧。
• YAGNI:赢的是做透并 ship 的一个机制,不是落不了地的宏图。能用成熟库/现成方案就用,别造轮子。

二·五、评测纪律（用户定调，2026-07-03；能力校准 2026-07-04）

• 评测只诊断、不定制。bench 的价值是暴露真实网页共性问题；任何修复必须全局性良好（对任意真实站点成立的结构理解），禁止对着某评测器的判据/词表/夹具写代码或措辞。自查题：这个修复放到一个从没见过的网站上还成立吗？不成立就不许进内核。
• 推断层新启发式必须两证齐全：合成最小例（讲清规则）+ 真实页面夹具（证明普遍性）；夹具应来自多个不同站点，防单站过拟合。
• 能力校准（重要，纠正一次真实的胆怯）：基础能力是入场券,不是赌注。让契约层稳稳驱动"实现了契约的标准页面"（多字段表单/下拉/多步流程/表单打开信号/handle 标签质量）是地基工作（红线4:任意实现契约的页面零额外代码可驱动），该主动、精致地投入,不算军备竞赛。要克制的只有两样:① 啃任意陌生/敌意站点（无契约 DOM 抓取当主路径）;② 对着评测器凑分。除此之外,"把标准页面驱动到可靠"是分内事——别再用"能力换信任/别屠榜"把地基工作也刹住。信任没有基础能力是空的（用户定调 2026-07-04）。注意区分:提能力 ≠ 松红线;§一（verify-or-refuse/held/诚实）与本节反过拟合永不为能力让路——它们保证提升是真的、可迁移的,松了则提升变空心或说谎,自我拆台。

三、测试与验收（最重要的教训）

"全绿但崩" 是这个项目最贵的一课。 85 个 FakeLlm 测试全绿时，真模型一跑暴露出：无效写拖垮 outcome、模型省略 ref 前缀、高危 held 够不到、记忆从没记录。这些确定性测试一个都没抓到。