设计原则

这些原则不是口号。每一条都来自一个容易反复出现的工程问题，也都带来明确代价。

本地优先：个人工作方式不应先依赖云端控制面

问题。 个人规则、任务历史和项目线索可能包含敏感路径或工作习惯；如果核心流程必须连接远端服务，离线、隐私和 可迁移性都会变差。

决策。 Harness、Memory、Task 与受限 audit 默认保存在本地文件系统，用 schema 和 CLI 管理。

代价。 Harnesssmith 不提供跨设备云同步、集中式团队策略或可信远程 attestation；这些能力如果需要，应由显式的 外部系统承担。

宿主中立，但不假装宿主相同

问题。 个人方法值得复用，但不同 Coding Agent 的路径、规则格式、激活机制和权限系统确实不同。

决策。 通用内容留在内嵌 Runtime，差异进入外层 Adapter；capability descriptor 明确记录 scope、activation 和 owner，而不是做最低公共分母。

代价。 新增宿主不能只复制一个目录，必须验证其官方路径契约和真实行为。

渐进披露：让入口成为地图，而不是百科全书

问题。 历史文档需要保留决策和演进记录，但把全部历史与流程常驻上下文会迅速增加成本，让关键边界淹没在过期、 弱相关或互相冲突的内容中，并增加错误召回和幻觉风险。

决策。 AGENTS.md 只保留高损失规则和发现顺序，route 先返回一个主要 playbook 与必要 topics，search 先给命中 摘要，再按需读取正文。

代价。 文档必须维护 metadata、状态、索引和清晰路由；没有入口的孤儿文档等于不存在，保留下来的历史也必须能与 当前事实区分。

Guidance 与 Enforcement 分离

问题。 自然语言规则很有用，却不能保证模型每次都遵循。把“文档写了”描述成“系统强制”会制造虚假安全感。

决策。 建议写入规则和 playbook；必须成立的约束写入 SafePath、schema、状态机、测试、CI 或宿主权限系统。

代价。 某些跨宿主行为只能声明为 advisory 或 delegated，无法靠统一 Markdown 获得强制性。

安全失败与可恢复变更

问题。 配置安装器一旦覆盖用户文件或留下半完成状态，损失远高于一次安装失败。

决策。 无法证明目标可安全接管时默认拒绝。install、restore 与 uninstall 共享 containment、路径段检查、锁、 完整预检、备份和精确回滚。

代价。 流程更保守，遇到 unmanaged 或 modified 文件会要求用户先理解差异。

状态帮助工作，但不篡位事实源

问题。 跨会话任务需要持久状态，但历史记录会过期，也可能只是当时的推断。

决策。 Memory 被定义为非权威线索；Task 是工作契约和证据账本。当前结论仍要回到代码、配置、测试、schema 与正式 文档核对。

代价。 系统不会自动把每次经验提升成长期规则；沉淀需要明确目标和复核。

声明必须绑定相称证据

问题。 “本地测试通过”“真实 Host 运行过”和“候选可以发布”回答的是不同问题。

决策。 公开能力分为 implemented、delegated 与 unsupported；验证分为确定性仓库门禁、Host Eval、记录校验和人工 复核。受限阴性结果使用 inconclusive。

代价。 发布说明必须保留未验证范围，不能用一个总的绿色徽章替代证据解释。