上下文工程实战：构建可审计的任务上下文包

任务上下文包

对于非简单任务，不要附加整个 Repository，而应组装小型、可 Review 的上下文包：

task_packet/
  goal.md          # 结果、范围、验收标准
  interfaces.md    # 权威 API 和类型边界
  evidence.md      # 来源 ID、Revision 和相关摘录
  constraints.md   # 兼容性、风险、隐私和非目标
  verification.md  # 命令、Oracle 和预期证据
  state.md         # 已批准决策及有效期

上下文包是输入，不是授权。Executor 仍应从可信 Application State 派生身份、Tenant、对象所有权和副作用权限。

1. 写清目标与范围

使用带有明确非目标的契约：

Goal:
  为只读 invoice list 增加 Cursor Pagination。

In scope:
  src/invoices/list.ts 及相关 Tests。

Out of scope:
  Database Migration、定价、部署和 Access Policy 变化。

Acceptance:
  稳定排序、拒绝无效 Cursor、限制 Page Size、
  Tenant 隔离、Tests、Type Check 和可 Review Diff。

Escalate:
  外部写入、新依赖、公共 API 破坏或凭证访问需要升级。

这样可以防止模型把“顺手”的额外变更当成任务的一部分。

2. 选择证据

为每个候选项记录：

先做权限过滤，再 Ranking。Semantic Match 不能授予访问权。如果两个来源冲突，应保留双方、指出冲突并升级，不要静默选择看起来更新的文本。

3. 减少噪声但保留意义

按以下顺序减少内容：

1. 删除无关文件和重复指令；
2. 保留 Interface、Invariant 和附近 Tests；
3. 用有界摘要替代大型生成输出；
4. 保留例外、否定、版本和 Source Span；
5. 只有任务需要时才分页或继续 Retrieval。

不要使用通用 Item 数或压缩比例。一个法律例外或一行权限条件，可能比数百行普通内容更重要。

保留证据的摘要

{
  "summary_revision": "summary-8",
  "claims": [
    {
      "id": "c1",
      "text": "The endpoint accepts only same-tenant invoice reads.",
      "sources": ["schema-17@rev-4#L21-L33"]
    }
  ],
  "uncertainty": ["pagination contract is pending review"],
  "expires_at": "policy-defined"
}

如果摘要无法指出来源或表示不确定性，就不应在高影响决策中替代原文。

4. 长期决策与 Memory

已提交的决策文件或对话摘要可以减少重复解释，但需要生命周期管理：

• 写明负责人和用途；
• 记录来源、Revision、有效期和范围；
• 区分决策与提案；
• 标记被 Supersede 的决策；
• 写入需要 Review；
• 将删除传播到 Index、Cache、Backup、Export 和评估数据；
• 绝不能让 Memory 覆盖当前授权或更新 Policy。

Provider 专用文件名与优先级会变化。内容应尽量与 Provider 无关，依赖文件前核对当前 Parser。

5. 局部指令

如果 Provider 支持，目录级指令可减少无关上下文，但它仍然是模型输入。保持短小、可测试：

For files under src/api:
  复用现有 Error 类型；
  在边界校验输入；
  不记录 Token 或完整客户记录；
  每个行为变化添加相关 Test；
  报告跳过的检查和未验证依赖。

不要将 Secret、凭证、生产数据或授权决策放入指令文件。它们应由 Tool Executor 和 CI 强制执行。

6. Cache 与动态上下文

上下文有稳定前缀时 Cache 可能有帮助，但应核对：

• Cache Key 由哪些字节组成；
• 最小前缀与排序要求；
• TTL 和失效；
• User 或 Tenant 数据是否可能混合；
• Provider 价格和隐私语义；
• Model、Policy 或 Source Revision 变化后的行为。

应按照 Provider 文档的 Cache 模型放置动态数据，不要套用“动态信息永远放最后”的通用规则。测量命中率、TTFT、总延迟、成本和过时 Context 失败。

7. Coding Agent 工作流

可审计的流程是：

inspect -> propose bounded plan -> approve scope
       -> edit isolated worktree -> run checks
       -> review diff and provenance -> merge or rollback

Tool 控制应强制：

• 已认证 Principal 与 Repository/Tenant Scope；
• 默认只读；
• 命令和网络 Allowlist；
• 文件、进程、时间和输出限制；
• 取消与清理；
• Merge、Release、删除、凭证变化和外部写入审批；
• 经过脱敏的审计 Event。

Prompt 指令、Retrieval 内容、Memory 和模型拒答都不能提供这些保证。

8. 评估上下文包

同时评估内容选择和最终结果：

保留脱敏 Replay 集。改变 Retriever、摘要 Prompt、Memory Schema 或指令时，比较原始结果并分类回归，不要只依赖一个模型分数。

常见错误

实践清单

• [ ] 定义目标、范围、非目标、验收和升级。
• [ ] 记录来源、Revision、权限、敏感度、时效和证据 Span。
• [ ] 在 Ranking 或注入前过滤访问权限。
• [ ] 压缩时保留例外、不确定性和 Source Span。
• [ ] 为 Memory 记录负责人、有效期、Supersession、留存和删除路径。
• [ ] 让指令文件与 Provider 无关，并排除授权路径。
• [ ] 核对 Cache 语义、失效、隐私和计费。
• [ ] 对 Tool 使用 Sandbox，外部或破坏性动作需要审批。
• [ ] 用任务、滥用、质量、延迟和成本案例 Replay 上下文变化。
• [ ] 保存原始证据并报告跳过的检查。

总结

上下文工程实战，是构建小型、可审计的任务上下文包。按权限、权威性、时效、相关性和预算选择证据；压缩时保留来源；用生命周期 Metadata 持久化决策；评估任务结果，而不是 Prompt 大小。模型可以帮助组装和使用上下文，但可信系统必须执行访问、副作用、隐私和回滚。

一手来源

• NIST AI Risk Management Framework
• OWASP Top 10 for LLM Applications
• Model Context Protocol Specification
• W3C Trace Context