上下文工程：让 AI 看到真实情况

提示词把订单导出的任务说清楚，但提示词本身不能替代项目事实。模型要实现导出功能，需要知道当前订单列表怎么查数据、权限在哪里判断、已有接口如何组织、测试怎么写、构建怎么跑。

上下文工程就是把这些真实材料组织成一个轻量、相关、可验证的资料包。它的目标不是把整个仓库都塞给模型，而是让模型刚好看到完成当前任务所需的证据。

为什么只写提示词不够

假设提示词写着：

为订单列表增加 CSV 导出，导出范围与当前筛选条件一致。

模型仍然不知道很多关键事实：

• 当前筛选条件是在前端组装，还是由后端保存。
• 订单金额字段是分为 payAmount 和 discountAmount，还是统一存在 amount。
• 权限系统用角色、权限码还是菜单资源控制。
• 订单列表已有分页限制，导出是否需要绕过分页。
• 项目里是否已经有通用 CSV 工具。
• 测试框架、命名风格、mock 写法是什么。

这些内容如果不提供，模型就会猜。猜出来的代码也许能编译，但很可能和项目真实结构冲突。

上下文包应该包含什么

订单导出的上下文包可以按任务关系组织，而不是按文件随意堆放。

类别	内容	用途
页面入口	订单列表页面、筛选组件、批量操作区	确认导出按钮放在哪里
数据查询	订单查询接口、请求参数、分页规则	确认导出范围如何与筛选条件一致
字段定义	订单字段说明、金额单位、状态枚举	避免字段含义和格式错误
权限规则	权限点、角色配置、无权限处理	避免越权导出
文件能力	项目已有 CSV/Excel 工具、下载工具	复用已有实现
测试样例	订单列表测试、权限测试、接口测试	保持测试风格一致
运行命令	类型检查、单元测试、构建命令	完成后验证
已知限制	大数据量策略、敏感字段禁区	避免引入风险

这个结构比“这里是几个文件，你看一下”更容易让模型建立任务地图。

给足关键材料，不给无关噪声

上下文太少会导致猜测，上下文太多会稀释重点。订单导出的资料包应优先给完整的改动入口和摘要后的依赖信息。

例如，订单列表页面如果就是本次要改的文件，应该提供完整内容；权限系统如果只需要知道如何判断权限，可以提供关键函数和用法示例；历史导出模块如果代码很长，可以先给目录、核心函数说明和一个最接近的实现片段。

更合适的组织方式是：

【本次必读】
- src/pages/orders/OrderList.vue：订单列表页面，包含筛选条件和批量操作区。
- src/api/orders.ts：订单查询 API，导出需要复用筛选参数结构。
- src/auth/permissions.ts：权限判断工具，使用 hasPermission('order:export')。

【参考即可】
- src/utils/csv.ts：已有 CSV 生成和转义方法。
- tests/orders/order-list.test.ts：页面测试风格。
- tests/auth/permission.test.ts：权限测试写法。

【约束】
- 不导出手机号、详细地址、用户备注。
- 不修改订单查询接口现有响应结构。
- 导出失败要保留当前筛选条件。

【验证】
- npm run test -- order-export
- npm run build

这份资料包已经足够模型开始工作，也便于人类 review。

用业务线串起上下文

只给文件列表还不够。模型需要理解这些文件之间的关系。订单导出的数据流可以这样描述：

1. 用户在订单列表选择时间范围和状态筛选。
2. 页面把筛选条件转换成查询参数。
3. 导出入口复用同一组查询参数，但不复用分页参数。
4. 后端根据权限点 order:export 判断是否允许导出。
5. 导出服务按字段白名单生成 CSV。
6. 页面收到文件后触发下载，失败时显示可重试提示。

这条业务线能帮助模型判断“当前筛选条件一致”到底意味着什么，也能发现潜在矛盾：列表分页和导出范围不同，权限不是页面隐藏就够，字段必须走白名单。

上下文中的决策记录

很多工程事实不是代码本身能看出来的。例如“不导出手机号”可能是安全决策，“先不支持 Excel”可能是产品取舍，“超过 1 万行异步导出”可能来自性能压测。

这些决策应该进入上下文，而不是让模型从代码里猜原因：

决策记录：
- CSV 作为第一版格式，因为运营当前使用表格软件处理对账，不需要保留复杂样式。
- 手机号和详细地址不进入导出字段，因为导出文件会在财务和运营之间流转。
- 当前版本只做同步导出，限制 1 万行以内；超过限制时提示用户缩小筛选范围。
- 后续如接入异步导出，需要新增导出任务表和导出历史页。

决策记录能减少不必要的“优化”。例如模型看到没有 Excel 支持时，不会自作主张新增依赖。

常见上下文错误

错误	在订单导出中的后果	改法
只给需求不给代码	实现的 API 名称、字段、权限都可能不匹配	提供页面、接口、权限和测试入口
给整个仓库	模型难以判断哪些文件相关	按业务线筛出必读和参考材料
只给成功路径	失败、空结果、无权限场景缺失	补充边界和失败处理要求
给过期文档	实现沿用旧字段或旧权限	提供当前分支代码和最近变更摘要
混合多种任务	导出、重构、权限改造纠缠在一起	拆成独立任务和独立上下文包

上下文复用

订单导出做完后，其中一部分上下文可以沉淀为团队资产。比如订单字段说明、权限点说明、CSV 转义规则、导出测试样例，都可以进入项目文档或规格库。下次做“用户导出”“退款导出”时，不需要重新整理一遍。

可复用上下文不应太大。它应该回答稳定问题：订单字段是什么意思，哪些字段敏感，导出类功能必须走哪些权限和审计规则，验证命令是什么。具体页面路径和当前 bug 日志则适合留在单次任务上下文里。

总结

上下文工程的价值是让模型基于项目事实行动。订单导出能否实现正确，不只取决于提示词是否清楚，还取决于模型是否看到了页面入口、数据流、字段边界、权限规则和验证方式。

好的上下文包会减少猜测，也会让后续 Agent 的行动更可控。下一步是把这些资料交给能读文件、改代码、跑命令的 Agent，形成可验证的执行闭环。

→ 下一步：工具与 Agent 工程