NexusDesk 架构与能力规划索引

平台采用 Python 模块化单体、异步 LangGraph Runtime、PostgreSQL 与 React 管理台。当前代码按四层组织：Core Platform、Extension Contracts、Business Capabilities 和 Applications。本文件描述当前架构和能力规划；目标演进见 Agent 执行平台 v2，目录重构的过程与验收证据见架构重构需求文档。

四层架构

text

agent_platform/
├── core_platform/
│   ├── agent_runtime/
│   ├── tool_gateway/
│   ├── policy_harness/
│   ├── extension_platform/
│   └── platform_services/
├── extension_contracts/
├── business_capabilities/
│   └── sample_operations/  # 示例能力实现
└── applications/

Core Platform：Runtime、Tool Gateway、Policy、插件生命周期和共享平台服务。
Extension Contracts：工具、能力、策略、事件、UI Extension 和 Runtime Binding 契约。
Business Capabilities：客服、审批、知识、记忆及其他领域能力。
Applications：API、Worker、Seed 和依赖组合入口。

规划索引

模块	名称	文档
agent_config	Agent 配置与发布	详细规划
agent_runtime	Agent Runtime	详细规划
channel	渠道接入	详细规划
conversation	会话管理	详细规划
customer_service	客服业务与流程	详细规划
human_handoff	人工客服协同	详细规划
knowledge	知识服务	详细规划
memory	客户记忆	需求与阶段文档
approval	审批与待确认动作	模块源码
tool_gateway	工具网关	详细规划
policy	策略与权限	详细规划
access_control	员工账号与访问控制	使用说明
integrations	共享集成服务	模块源码
tenant_isolation	租户隔离与上下文	模块源码
observability	运行观测与审计	详细规划
evaluation	质量评测	详细规划
model_gateway	模型网关	详细规划
open_platform	开放平台	详细说明
platform_settings	平台设置（规划中）	详细规划

每个能力或平台服务规划包含现状、功能优先级、数据归属、接口契约、依赖边界、设计约束、管理台、阶段与验收。模型网关保留详细配置层级设计。platform_settings 按当前范围仅保留配置层级与继承、工单模式与停用两节，不扩展为其他模块的配置中心。

统一契约、共享事务演进及独立交付规则见模块独立开发与扩展规范。

协作关系

mermaid

flowchart TD
    Settings[平台设置 · 规划] -. 层级与继承规则 .-> Config
    Settings -. 工单模式与停用规则 .-> Customer
    Channel[渠道接入] --> Customer[客服业务与流程]
    Channel --> Conversation[会话管理]
    Customer --> Conversation
    Customer --> Config[Agent 配置与发布]
    Customer --> Runtime[Agent Runtime]
    Customer --> Handoff[人工客服协同]
    Handoff --> Conversation
    Handoff --> Runtime
    Runtime --> Model[模型网关]
    Runtime --> Tools[受控工具端口]
    Tools --> Gateway[工具网关]
    Tools --> Knowledge[知识服务]
    Tools --> Proposal[业务动作提案端口]
    Eval[质量评测] --> Runtime
    Eval --> Mocks[模拟工具]
    Config -. 发布证据 .-> Eval

此图表示职责协作，不能理解为引擎应直接导入所有领域实现。模型及工具经组合入口注入，业务动作提案实现属于 customer_service。policy 提供授权决策，observability 消费各模块事实。评测执行时用模拟工具替换真实执行端口。

平台设置规划仅保留平台／租户／Agent 配置层级与继承规则、工单模式及停用流程。各模块继续拥有自身配置，policy 负责授权，customer_service 负责工单事实及业务执行；不另建通用配置发布中心。

状态按领域区分

领域	当前状态	扩展注意事项
Run	queued/running/completed/failed/cancelled	等待输入与检查点恢复为未来设计
会话	bot/waiting/human/closed	人工接管必须约束自动结果提交
工单	open/in_progress/resolved/closed	外部办理的结果未知需独立操作状态
待确认动作	pending/confirmed/rejected	超期目前按 expires_at 判断

会话等待人工、业务待确认和 Run 暂停不是同一状态机。当前工单确认在 Run 之外完成，不是 LangGraph 节点级暂停恢复。

建设顺序

稳定可信上下文、错误/事件契约及现有会话与运行事务边界。
模型网关在线配置、版本方案及 Agent 绑定已落地首版；继续完善供应商联调、全局额度及工具版本和执行契约。
知识索引、渠道适配、人工坐席、观测查询按各自端口独立扩展。
建立业务操作账本和幂等核查后，建设外部写入及 Runtime 检查点恢复。
完善异步评测、发布门禁、全局额度和运营能力。

先定义端口、数据所有权与假实现，不要求立即拆为微服务。普通 API 调用无需沙箱；未来代码执行应设计独立沙箱边界。Applications 只负责组合，不承载平台或领域实现。

操作说明见平台使用说明和 Runtime 文档。当前实现以代码和各模块 README 第 1 节为准，测试覆盖以 CI 实际运行结果为准；规划文档不新增可调用接口，也不改变现有数据库。

早期模块交付、实施进度和阶段验证记录见历史文档归档，不代表当前交付或测试状态。

工单目标结构见通用工单设计 v1：固定主表、JSONB 业务详情、独立过程记录；直接切换迁移已准备，现有工单读写已接入；类型设计器及自定义字段编辑仍待实现。

NexusDesk 架构与能力规划索引 ​

四层架构 ​

规划索引 ​

协作关系 ​