主题
MyAgents 平台能力全景方案
1. 方案摘要
本方案定义智能体平台的能力边界：多种业务入口进入统一运行时，由 Agent 编排模型、技能、工具和扩展，最后以消息、文件或交互组件交付结果。平台的核心原则是入口协议可以变化，但任务上下文、租户隔离和结果交付必须保持一致。
2. 设计目标与非目标
设计目标
- 建立从入口到交付的统一能力模型。
- 明确平台能力与外部 Provider、业务系统、基础设施的责任边界。
- 为单进程和多副本部署提供相同的业务抽象。
非目标
- 不定义某一个模型 Provider 的内部实现。
- 不把平台能力拆成强制独立部署的微服务。
- 不在本方案中规定具体业务 Agent 的 Prompt 或工具策略。
3. 架构范围与视图
MyAgents 面向哪些入口、提供哪些平台能力，并与哪些外部系统和基础设施协作？
覆盖系统入口、核心能力、外部生态和共享基础设施，不展开组件内部实现。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| 用户与入口 | Web Chat、管理后台、嵌入式 WebChat、飞书、企微、钉钉、OpenAPI、定时任务。 |
| 智能体运行 | Agent、模型、技能、工具与 Claude Agent SDK 组成任务执行能力。 |
| 会话与任务 | Chat、Session、Memory、Schedule 和异步任务提供连续业务上下文。 |
| 文件与生成物 | 文件服务、Widget、插件页面、分享和发布页面承载交付结果。 |
| 业务扩展 | 扩展包可交付 Agent、Skill、CLI 和 Plugin。 |
| 平台治理 | 租户、身份权限、配置、审计、日志、OpenTelemetry 与 Langfuse。 |
| 外部生态 | 模型 Provider、MCP / Web 工具、ERP / 业务系统和云端扩展包平台。 |
| 基础设施 | 本地可用 SQLite 和文件系统；生产可用 MySQL、Redis 与兼容 S3 的对象存储。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- 以统一任务上下文承接 Web、IM、OpenAPI 和 Schedule。
- 以租户、Chat、Session 和 Task 作为跨入口共享的业务语义。
- 进程内对象只承载运行态，共享数据库、Redis 和对象存储承载跨副本事实。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 用户和业务系统通过 Web、IM、OpenAPI 或定时任务进入平台。
- 统一入口解析身份、租户、Agent 和会话，将任务交给运行时。
- Agent 使用模型、技能、工具和业务扩展完成任务。
- 结果通过流式消息、IM 回复、文件、Widget 或业务页面返回。
- 状态、配置、文件和可观测数据写入相应持久化设施。
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- 用户可见会话、任务状态和归档以数据库为准。
- 缓存和广播用于降低读取成本、传播变更，不作为最终事实源。
- 生成文件使用文件服务抽象，生产环境不能依赖单个副本的本地目录。
当前专题的关键约束
- 开发工具和运行时模块不作为独立线上服务部署。
- 进程内对象只承担当前副本运行态，不能作为跨副本事实源。
- 模型接入以 Claude Agent SDK 可消费的 Anthropic Messages 兼容协议为主。
8. 异常、恢复与安全边界
- 入口适配失败时在入口边界返回可识别错误，不创建半成品任务。
- 模型或工具失败由任务状态记录，并通过原入口返回可重试或可恢复结果。
- 共享基础设施不可用时禁止把进程内状态伪装成已持久化状态。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 单进程组合部署适合本地开发和小规模交付。
- 多副本部署将入口、Runtime 和共享基础设施解耦，业务语义保持不变。
- 外部模型、工具、数据库、缓存和对象存储通过可替换适配边界接入。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- Web / Embed / IM / OpenAPI / Schedule 接入
- Agent、会话、记忆、文件、扩展、插件和治理能力
规划或待完善
- K8s 交付清单与完整多副本运维流程
演进方向
- 补齐多副本交付清单、容量基线和故障演练。
- 在不改变统一任务上下文的前提下增加新的入口和交付通道。
11. 方案验收要点
- 任一入口都能追踪到租户、Agent、Chat、Task 和最终交付物。
- 副本切换后不能产生跨租户读取或旧状态覆盖。
- 新增外部 Provider 不需要改写入口和会话模型。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。