Appearance
AI Agent 工程化开发（V10）
Agent 工程不是把“需求 Agent → 架构 Agent → 开发 Agent → 测试 Agent → 文档 Agent”固定串起来跑一遍。真正成熟的做法是：先判断当前任务需要哪些能力，只调用必要专家，并让每一步都有可审查证据。
1. 统一入口先做 Intent Gate
text
用户请求
↓
Read-Only？
├─ 是 → Trace → 回答 → END
└─ 否
↓
Fast / Execution / Discovery这意味着：
- 查“当前代码怎么判断”不需要需求 Agent；
- 改一个 Label 不需要 UI 设计 + 架构 + 测试全套专家；
- 用户已经给完整方案时不需要重新访谈；
- 只有业务规则还没决定时才进入 Discovery。
2. 专家是能力，不是固定流水线
| 能力 | 什么时候需要 |
|---|---|
| Requirement | 新项目、业务语义仍未决定 |
| Architecture | 新子系统、跨模块边界、难逆取舍 |
| UI Design | 新页面、复杂交互、操作流程重构 |
| Protocol / Communication | 协议、串口/TCP/UDP、超时、恢复 |
| Implementation | 目标和边界已经明确 |
| Bug Investigation | 根因未知、现场异常、近期回归 |
| Log Timeline | 多源日志、偶发故障、需要找 first anomaly |
| Performance / Long-Run | UI 卡顿、CPU、内存、队列、Stop 假死、长稳 |
| Test / Regression | 按影响补 focused 验证 |
| Hardware Safety / HITL | 真机、高压、运动、阀门、继电器等状态改变 |
| Documentation | 正式方案、总结、说明书、验收资料 |
默认由统一入口路由，不要求用户自己记住 00–15 的编号。
3. 一个真实任务可以很短
纯 UI 文案
text
Intent Gate
→ Fast / MicroPatch
→ XAML
→ Diff
→ V0/V1连续 5 次才报警
text
Intent Gate
→ Execution / BehaviorPatch
→ Behavior Contract
→ 修改状态/判断/日志
→ focused tests
→ V2/V3“昨天改完后波形不一样”
text
Intent Gate
→ RegressionFix
→ known-good
→ changed files
→ behavior delta
→ 最小修复
→ focused verification“运行 20 分钟后越来越卡”
text
Intent Gate
→ Performance / Long-Run
→ Baseline
→ narrow hotspot
→ one change
→ same-scenario re-test只有新项目、大型功能、架构重构才需要比较完整的多角色协作。
4. Rules / Context / Memory / ADR / Skill / Tool
这些东西解决的是不同问题。
| 层级 | 回答什么 |
|---|---|
| Rules | Agent 必须怎样工作？ |
CONTEXT.md | 这个系统里的稳定业务术语是什么意思？ |
.agent-memory/ | 这个项目以前发生过什么？ |
| ADR | 为什么长期做了这个不直观的取舍？ |
| Skill | 这一类任务应该怎样执行？ |
| Tool / MCP | Agent 可以读取、修改、构建或查询什么？ |
详细说明见 项目 Context、Memory 与 ADR。
5. Context Engineering：不是上下文越多越好
推荐顺序：
text
明确任务
→ 已知项目事实/相关 Memory
→ target file
→ direct owner / caller / callee
→ data sink / behavior boundary
→ 停止扩搜什么时候扩大上下文
- 新项目第一次建立系统地图；
- 跨模块设计；
- 根因证据不足；
- 发现调用链继续穿透重要边界；
- 当前事实与历史记录冲突。
什么时候应该停
已经确认：
- 谁拥有这个行为；
- 主要调用链；
- 最终数据/设备落点；
- NonGoals；
就不要继续为了“更全面”读取无关目录。
6. Decision Tree / Frontier：需求发现只问真正的决策
Discovery 里区分两类信息：
text
事实
→ Agent 自己查
决策
→ 用户决定例如：
“当前阈值写在哪里？”是事实。
“超过阈值后应该停机还是只报警？”是决策。
Agent 先构建决策依赖，当前可以回答的决策组成 Frontier。每轮只问当前阻塞实现的关键问题；Blocking Unknowns 清零后立刻进入 Execution，不为了完整继续访谈。
7. Stable Seam：测试边界尽量稳定，但不强制 TDD
测试优先通过现有公共行为边界验证：
- application/service 接口；
- protocol parser；
- workflow/state transition；
- fake/replay adapter；
- ViewModel 可观察行为。
不要为了给一个 UI MicroPatch 加测试，先新增公共接口或抽象层。
只有准备改变模块边界、增加长期公共 API 时，才值得单独讨论 seam。
8. Bug Investigation 使用 Feedback Ladder
现场设备 Bug 不一定能先写一个自动失败测试，所以 V10 使用梯度：
text
existing focused test
→ Fake / Simulation
→ Replay
→ 日志 / 时间线 / known-good diff
→ 最小 harness
→ 安全且获授权的只读真实设备验证
→ HITL 现场验证目标是尽量建立便宜、稳定、接近真实问题的反馈环，而不是要求所有现场问题都必须先自动化复现。
多源日志或现场偶发问题优先进入 日志与时间线诊断：对齐时间源、收窄时间窗、找 first anomaly，再区分 Evidence / Inference / Unknown。
通信调查还要确认 Device Session Owner：默认复用当前串口/TCP/SCPI/VISA 会话，不为了诊断偷偷打开第二个互斥 Session。验证内容按实际协议模型决定，自定义字节流、SCPI、Modbus、厂商 SDK 不共享一套固定半包/CRC 清单。
9. Temporal Regression 是单独的诊断模式
只要用户明确表达“以前正常、最近修改后异常”，第一问题不是“当前代码哪里不合理”，而是：
text
哪个版本是 known-good？
最近哪些文件变了？
真正的行为差异是什么？只有与 known-good 不同，或者有直接运行证据的代码，才能升级为回归根因候选。
回退到旧版并恢复正常时只写：
text
RolledBackToKnownGood没有识别并修复 causal behavior delta 前，不写 RegressionFixed。
10. EvidenceGrade 和 Verification State 是两个维度
EvidenceGrade：根因结论有多强
| 等级 | 含义 |
|---|---|
| A | 可重复自动验证 |
| B | 稳定模拟/回放 |
| C | 日志 + 代码 + known-good 等强证据 |
| D | 候选假设 |
D 级只能写“怀疑”“候选”，不能写“根因已确认”。
“重试后恢复”通常只能提升“瞬态状态问题”的可能性，状态应保持 SuspectedTransient，直到下一次抓到更直接的设备命令、错误队列、状态和时间戳。
Verification State：本次验证完成到什么状态
text
Verified
Unverified
EnvironmentBlocked
HardwarePending软件/构建/权限环境阻塞才是 EnvironmentBlocked；需要真实设备/HITL 但尚未执行是 HardwarePending。Fake/Replay 通过不等于现场设备通过。
11. 性能与长稳不走“凭感觉重构”
出现 UI 延迟、CPU 高、内存增长、Dispatcher/队列积压、通信延迟或 Stop/Dispose 假死时：
text
Baseline
→ narrow hotspot
→ one change
→ same-scenario re-test短场景改善只能证明短场景；未执行 24h/72h 长稳就保持 Unverified，需要真实设备时为 HardwarePending。
12. Agent 的输出对象应该可审查
一次开发任务真正值得留下的通常是：
text
任务边界
Git Diff
验证结果
EvidenceGrade（根因任务需要时）
Verification State
残余风险
必要的 Memory / ADR而不是无限增长的分析过程。
13. Architecture Hotspot Review 只显式运行
架构体检适合：
- 同一个模块频繁返工；
- 多次 Bug 都跨相同边界；
- 测试很难插入；
- Git hot spot 长期集中在少数文件；
- 职责、状态和副作用不断扩散。
它不应该在每次功能修改结束时自动运行。只有明确要求“做架构体检”“为什么这里总返工”时再启动。
14. 人和 Agent 的责任边界
Agent 擅长：
- 检索代码和资料；
- 建立调用链；
- 比较 Diff；
- 生成候选方案；
- 修改普通源码；
- 执行安全的构建、测试、Fake/Replay、模拟和静态检查；
- 整理证据。
人工必须保留：
- 业务最终决策；
- 高压、运动、气路、阀门、继电器等危险设备授权；
- 现场设备验收；
- 破坏性数据操作确认；
- 最终交付责任。
真实设备状态改变默认 HardwareAction: ForbiddenByDefault。需要现场动作但尚未执行时，应留下 HardwarePending，而不是让 Agent 为了“全绿”自动操作设备。
15. V10 Agent 工程一句话模型
text
任务先分流
→ 上下文按需加载
→ 专家按需调用
→ 实现围绕 Diff
→ 验证按风险升级
→ 结论按证据强度表达
→ 只有高价值知识才沉淀相关页面：