能力独立开发与平台扩展规范
适用于 backend/src/agent_platform/business_capabilities 下的业务能力、backend/src/agent_platform/core_platform 下的平台服务及其前端页面，详细规划见架构索引。本规范是目标约定，不代表现有代码已经完成全部解耦。
1. 开发单位与分层
独立开发的单位是有业务边界、可替换依赖及独立验收用例的业务能力或平台服务，初期仍部署为模块化单体。
| 层次 | 职责 |
|---|---|
| API / 页面 | 输入校验、认证上下文、协议转换和呈现 |
| 领域服务 | 状态转换、业务不变量和用例编排 |
| 端口与契约 | Protocol、DTO、错误和事件，不暴露对方数据库行结构 |
| 仓储 / 适配器 | PostgreSQL、HTTP、模型或渠道的具体实现 |
| 组合入口 | 依赖注入、配置解析和生命周期 |
按复杂度逐步拆出 contracts.py、ports.py、repository.py、adapters/，不要求为简单能力创建空层。当前由 applications/customer_service/platform_services.py 与 Runtime composition 承担组合职责。
2. 可信执行上下文
规划 ExecutionContext 包含 tenant_id、actor_id/actor_type、roles/scopes、trace_id/request_id、可选 conversation_id/run_id、deadline/cancellation。身份及租户由服务端认证或部署配置解析，模型不得指定；关联资源必须验证归属。
上下文不保存明文密钥、渠道令牌或任意客户端自报权限。后台 Worker 使用受限服务身份，显示名称不等于认证主体。取消信号和截止时间分别映射到进程内请求与持久化任务。
3. 数据所有权与事务
各 README 声明数据所有者。目标为通过能力命令修改数据、通过查询端口读取数据，不跨能力直接更新表。观测使用约定的只读投影，投影不能反向改变业务状态。
当前共享事务例外：Runtime 仓储、会话、客服业务和人工转接共同维护会话表及相关状态；渠道去重与业务受理也共享事务。这些尚不是完全独立的数据域。
演进时先用端口封装原事务，再将消息和模式转换收敛到 conversation，保持应用工作单元的原子性。仅在拆分独立服务时，才用 Outbox/Inbox、幂等命令和补偿替代跨库事务，不能为形式上的解耦破坏原子操作。
并发继续依靠唯一约束、乐观版本及统一锁顺序。当前有 admission lock 的提交路径先锁 admission 再锁会话；结果提交和人工接管先锁会话再处理运行。禁止在持有会话锁时引入反向 admission lock。
数据库扩展采用新增 Alembic 迁移；归属调整明确回填、兼容期、读写切换及回退方案，不能修改已应用历史迁移。规划实体不等于现有表。
4. 命令、查询、事件与错误
- 命令携带输入 DTO、资源 ID、版本条件及必要幂等键；同键同内容返回原结果，同键不同内容明确冲突。
- 查询带可信资源范围和稳定游标。公开 DTO 不直接绑定数据库列结构，破坏性变更需契约版本。
- 规划事件信封：event_id、event_type、schema_version、tenant_id、aggregate_id、occurred_at、trace_id、payload；需要顺序时提供资源内序号。
- 关键状态和事件同事务落库，提交后发布；消费者去重，采用至少一次交付，不默认跨资源全局有序。当前没有因此新增消息总线。
- 错误区分校验、认证、授权、不存在、版本冲突、容量、上游故障、超时及结果未知；返回稳定错误码，不返回内部堆栈。retryable 不等于允许无条件重试。
Runtime SSE 游标仍由 Runtime 管理；各 README 中的目标方法和事件不能当作当前可调用接口。
5. 跨模块职责分配
| 关注点 | 所有者 | 协作方 |
|---|---|---|
| 配置层级与继承规则、工单模式及停用流程 | platform_settings（仅规划这两项） | 各模块保留配置所有权；policy 授权，customer_service 执行工单业务 |
| 认证身份 | core_platform/platform_services/identity | API、Worker 和领域服务 |
| 授权决策 | core_platform/policy_harness | 各服务执行数据范围及附加约束 |
| Agent 发布 | agent_config | Runtime 捕获版本，evaluation 提供证据 |
| 模型方案、调用和用量 | model_gateway | Runtime 调用，observability 展示 |
| Run 总预算与生命周期 | agent_runtime | 模型和工具服从剩余预算 |
| 工具定义与调用操作 | tool_gateway | Runtime 编排，业务提供确认凭证 |
| 业务确认与工单 | customer_service | 工具执行，会话记录结果 |
| 消息与会话模式 | conversation | Runtime、客服及人工模块协作 |
| 转接与分配 | human_handoff | 会话保存归属，Runtime 取消运行 |
| 文档及引用 | knowledge | Agent 消费授权检索结果 |
| 收件与投递 | channel | 客服处理标准化消息 |
| 观测投影及审计查询 | observability | 各模块提交事实 |
| 测试集与报告 | evaluation | agent_config 判断是否发布 |
policy 声明配额条件，执行模块维护原子计数。模型网关负责供应商限额，工具网关负责工具限额，Runtime 负责整体预算，避免重复计数。
重试同样分层：模型网关重试模型请求，工具网关按操作语义重试，渠道重试投递；Runtime 不通过重跑整个流程隐式重复副作用。
6. 独立交付流程
- 明确本次范围、依赖、不变量及最小 DTO/Protocol。
- 提供假适配器、错误样例和契约测试，不依赖真实模型密钥或第三方账号。
- 完成领域规则、持久化、适配器，再接 API 和前端。
- 在组合层验证兼容性；真实外部系统使用专用测试环境。
- 更新模块现状、配置说明、测试位置与运行手册。
模型适配、知识管线、渠道协议、观测查询和评测数据集可按冻结端口独立推进。Agent→模型方案、业务确认→写工具、会话→人工接管→Run 终态、评测报告→发布门禁须先协调契约。
7. 验收要求
- 领域规则覆盖正常、拒绝、冲突、取消及失败路径。
- 消费者/提供者验证 DTO、错误和版本兼容。
- 涉及事务和并发时使用真实 PostgreSQL 验证唯一约束、锁及租户隔离。
- 外部适配使用模拟服务覆盖限流、断连、超时、重复及未知结果。
- 有页面改动时验证权限、错误提示和关键业务闭环。
- 涉及性能目标时明确硬件、模型、负载、P95、错误率和预算，不凭单元测试声明生产容量。
按实际变更选择验证范围；文档变更无需重复全部业务测试。规划验收条件与已通过测试分别记录。
8. 公共基础设施
core_platform/platform_services/identity、secrets、persistence、messaging、storage 提供身份、密钥、工作单元、可靠消息和文件存储端口，不计入业务能力目录。避免各业务能力重复建设这些能力，具体实现按实际接入需要扩展。
P0 稳定核心闭环和接口，P1 扩展规模与治理。具体供应商、容量和时限在开发任务启动时确定，本文不预先承诺工期或生产 SLA。