# AgentLab项目与数据契约

版本：1.0.0。本文定义本课程自己的业务规则，是习题、参考实现、互动与评分的共同事实源。它不是任何真实商家的售后条款。

## 1. 贯穿项目

项目名称：AgentLab；业务环境：青禾商店售后；第二环境：三个小型代码修复任务。二者共享任务、模型适配、工具预算与Trace概念，不强行共享领域规则。

所有订单、用户、金额、延迟和故障均为合成教学材料。基础轨只使用本地Python标准库；真实LLM、MCP、FastAPI/PostgreSQL、Temporal/LangGraph与Docker是明确标记的扩展实验，课程网站本身不执行它们。

## 2. 身份

认证主体为`Principal(tenant_id,user_id)`，不可由模型或工具参数覆盖。shop-a/u-alice和shop-b/u-bob为两个测试主体。同一订单号在不同租户可以同时存在。无权限和不存在对外统一返回NOT_FOUND。

所有读、审批、提交、事件和artifact接口都执行对象级授权。参考实现只模拟已经认证的Principal，不实现登录、JWT签发或完整身份提供方。

## 3. 订单与政策v2

订单字段：tenant_id、order_id、owner_id、paid_cents、refunded_cents、shipment_state、delivered_days、unopened、custom、version。金额为非负整数分，不使用浮点。`available=paid-refunded`，必须非负。时间使用注入的整数时钟，单位秒。

规则按以下优先级判断：

1. 无访问权：NOT_FOUND，不暴露其他信息。
2. available=0：ALREADY_REFUNDED，不创建新退款。
3. custom=true：MANUAL_REVIEW，不自动退款，包括物流丢件的定制品。
4. shipment_state=lost：可退available。
5. shipment_state=delivered且0≤delivered_days≤7且unopened=true：可退available。
6. shipment_state=unknown：MANUAL_REVIEW。
7. 其他情况：NOT_ELIGIBLE。运输中可以解释和建工单，但参考内核不实现真实客服工单。

全额可退余额是本课程唯一退款金额策略。部分余额来自之前已确认退款；本次不允许模型自选金额。所有退款都需要审批，不按金额豁免。

## 4. 提案与批准

提案绑定：tenant、owner、order、amount_cents、currency=CNY、order_version、policy_version=policy-v2、operation_id、expires_at。operation_id在提案创建时由服务端生成，恢复/重试不得改变。

提案摘要用于检查语义变化，不是授权令牌。授权来自服务端保存的认证用户审批。有效时间为`now < expires_at`，等于到期时刻即无效。

批准可以幂等重复；相反决策不能覆盖已有批准/拒绝。执行前重新核验订单版本、政策版本和余额。任何字段变化均需要新提案与新审批，本课程不支持上限授权。

已成功操作的合法同参数重试可返回原结果，即使当前提案已过期或订单版本已推进，因为它不产生新副作用；仍需检查请求主体与参数一致。不能把该规则用于提交一项尚未执行的过期操作。

## 5. 操作语义

作用域为(tenant_id,operation_id)。参数摘要一致的重复请求返回原结果；不一致报IDEMPOTENCY_CONFLICT。同一operation最多一笔账本记录。新业务意图有新ID，但仍受当前余额、版本与新审批约束。

本地参考服务的订单、提案、操作与账本在同一SQLite事务，支持模拟提交后丢响应。此保证不自动扩展到真实支付API。远端不支持去重或查询时，未知结果必须进入核对流程。

## 6. Run与事件

conversation_id、run_id、attempt_id、call_id、operation_id不同。run可能多次恢复，operation不随尝试变化。任务状态见M05。等待审批落盘，不占执行资源。

UI事件按每run递增seq排序，可重复传输；客户端去重，不重新执行操作。业务状态与其事件同事务提交。观测Trace允许独立保留策略；恢复和审计所需事实不能因采样丢失。

## 7. 教学预算

离线Runner默认最多6次模型调用、8次工具调用，每工具返回上限由注册表约定。参考实现验证轮次/调用预算；输出字节、真实token、墙钟及远端费用预算是后续实验任务，不冒称已全部实现。

模拟成本单位不等于人民币或供应商报价。真实实验必须配置价格来源与时间，基础课程不得要求付费API才能阅读、完成互动或运行参考测试。

## 8. 数据分层

retail/orders.json为业务合成数据；policies.json为检索内容；tasks.jsonl为24个任务规格，expected是教学答案而非秘密测试；evaluation/trials.json为指标练习，不是Agent实测。coding目录是原创小题，不是SWE-bench样本。

所有公开任务的expected字段只能供评测器使用，不放入模型输入。网页默认先显示任务，提交或主动展开后显示期望与解释。

## 9. 非目标

本包不是部署完成的生产后端，不包含真实账户/支付，不替学习者选择供应商，不保证任何求职结果。课程正文、答案、交互规格与离线参考材料已经交付；实际网站和可选集成由后续开发Agent按handoff实现与验证。