# 编码代理工作手册

> 状态：Harness 基线
> 读者：在本仓库中执行分析、实现、评审和修复的编码代理

## 1. 开始任务

1. 阅读 [文档地图](README.md)，再按任务类型读取专题文档。
2. 检查工作树、已有实现和测试；不要假设方案文档已经被编码。
3. 找到关联需求编号、架构边界和完成标准。
4. 把目标拆成可独立验证的小改动，明确不在范围的内容。
5. 只有必要产品选择无法从仓库确定且错误假设风险较高时，才请求用户决定。

根 `AGENTS.md` 创建后应保持为短入口，只包含仓库导航、常用命令和不可违反的不变量，并指向本手册；不要复制全部专题文档。

## 2. 事实源与检索顺序

1. 当前用户任务和已接受 ADR。
2. 对应产品需求、领域规则、AI 安全和架构文档。
3. 自动化测试与 schema。
4. 代码实现。
5. 外部官方文档。

测试、代码和文档互相矛盾时，不要随意选择最方便的一方。先判断哪一个表达了当前已接受行为；修复时同步其余事实源，并在交付说明中指出冲突。

代码发现优先使用仓库配置的知识图谱工具：`search_graph` → `trace_path` → `get_code_snippet` → `query_graph` → `get_architecture`。图工具不足，或搜索字符串、配置和非代码文件时，再使用 `rg`。

## 3. 永久不变量

任何任务都不得违反：

- AI、网络、时间、问题文本和随机数不参与起卦。
- 六爻领域顺序为 bottom-up；6/9 动，7/8 静。
- 第六轮确认后，AI 和解释层不能修改 `CastResult`。
- 核心起卦和本地内容离线可用。
- 开发者密钥不进入 APK、源码、日志和测试夹具。
- 问题原文和 AI 全文不进入遥测或崩溃日志。
- 未授权或来源不明的现代译文、字体和图像不能进入发布包。
- AI 不预测和替用户作高影响决定。
- 东方文化表达不得牺牲触控、对比度、读屏和字体缩放。

若任务显式要求违反其中一项，停止实现并请求产品确认；确认后先更新决策和规范，再改代码。

## 4. 实现工作流

### 4.1 Inspect

- 确认当前分支/工作树和用户已有改动。
- 阅读最小充分上下文，不进行无目的全仓库扫描。
- 查找已有相似模式、测试 fake、主题令牌和错误类型。
- 确认依赖版本与官方 API，而不是凭记忆猜测会变化的接口。

### 4.2 Plan

- 用需求编号描述结果，而不是只列文件。
- 标记数据迁移、隐私、安全、内容授权和 UI 无障碍风险。
- 优先扩展现有抽象；新抽象必须有两个以上清楚的使用点或隔离重要边界。

### 4.3 Implement

- 做满足验收的最小完整改动。
- 领域逻辑用封闭类型和纯函数，边界数据先解析再进入领域。
- UI 使用不可变状态和显式 action；不在 Composable 中访问数据源。
- 新颜色、字号、间距和文案进入设计/资源令牌。
- 不顺手重构与任务无关的用户代码，不覆盖脏工作树。

### 4.4 Verify

- 先运行最接近改动的测试，再运行 `verifyLocal` 或等价全量门禁。
- UI 变更至少检查正常、加载、错误、空、离线和恢复状态。
- 领域变更运行穷举/属性测试。
- AI 变更使用 fake server，不依赖实时模型作为唯一证据。
- 明确记录执行过、未执行和失败的命令；不把预期当结果。

### 4.5 Document

以下变化必须同步文档：

- 用户可见行为 → [产品规格](product-spec.md)/[UX](ux-design.md)
- 算法或模型 → [领域规则](domain-rules.md)
- 包、依赖或数据流 → [系统架构](architecture.md)
- schema、来源、隐私 → [数据与内容](data-content.md)
- 提示词/模型行为 → [AI 安全](ai-safety.md)
- 命令/门禁 → [质量门禁](quality-gates.md)
- 架构取舍 → [决策记录](decisions.md)
- 可复现失败 → [失败记忆](failure-memory.md)

## 5. 依赖政策

引入依赖前回答：

1. 现有 AndroidX/Kotlin/项目代码能否清晰完成？
2. 依赖是否维护、兼容当前工具链并有明确许可证？
3. 它增加多少 APK/构建/运行复杂度？
4. 它会不会模糊领域边界或把密钥带入客户端？
5. 测试如何替换或 fake 它？

新增大型依赖、具体 AI SDK、分析 SDK、字体包或多模块结构必须记录 ADR。

## 6. 测试纪律

- 修复缺陷先建立可失败的回归测试，再修复。
- 不删除、跳过或放宽断言来让门禁变绿，除非需求正式改变。
- 不在测试中使用 `Thread.sleep` 等不稳定等待；使用测试调度器和可控 fake。
- 不把实时日期、网络和模型输出放入确定性测试。
- screenshot golden 的更新必须人工确认差异来源。
- 数据库迁移必须从上一发布 schema 测到当前 schema。

## 7. 失败处理

命令失败时：

1. 保存准确命令、错误摘要和环境。
2. 判断是实现缺陷、环境缺失、测试脆弱还是规范冲突。
3. 修复根因并重新运行最小失败用例。
4. 再运行相关全量门禁。
5. 若相同类别可能复发，更新[失败记忆](failure-memory.md)并增加机械护栏。

不得无限重复同一失败命令，也不得用捕获异常、硬编码测试值或关闭检查掩盖失败。

## 8. 交付格式

最终交付至少说明：

```markdown
## 结果
- 完成了什么，对应哪些需求

## 关键实现
- 重要边界或决策

## 验证
- 实际运行的命令和结果
- 人工验证

## 剩余事项
- 未运行、TBD、外部阻塞或剩余风险
```

如果任务只完成文档或调查，直接说明没有构建/测试，不伪造运行证据。

## 9. 定期维护

每个里程碑执行一次轻量“熵清理”：

- 删除无引用文档、死代码和过期 TODO；
- 合并重复 helper 和重复主题令牌；
- 检查实现是否绕过层边界；
- 检查文档链接、状态和验证命令；
- 检查依赖、许可证、内容版本和数据库迁移；
- 将重复评审意见提升为自动化规则。

目标不是追求文件数量，而是让下一次代理运行能更快找到真实约束，并从环境得到准确反馈。