AIGC:

Label: "1"

ContentProducer: 001191110102MACQD9K64018705

ProduceID: 7628943723359142207-data_volume/files/所有对话/主对话/BossAgents/Phase0/agent_integration_spec_v1.md

ReservedCode1: ""

ContentPropagator: 001191110102MACQD9K64028705

PropagateID: 1083491254024747#1786279873251

ReservedCode2: ""

BossAgents 外部智能体接入规范 V1

Q: 1.1 目标？

让外部 AI 智能体以 标准化、可管控、可审计 的方式接入 BossAgents 平台，使平台从"预置数字员工供应商"向"数字员工操作系统"演进。

Q: 1.2 Phase 0 范围？

| 维度 | 说明 | |------|------| | 首批接入智能体 | exploreai（探索智能体）、scsai（战略智能体） | | 接入目的 | 跑通端到端协同任务，验证接入规范可行性 | | 不做的事 | 不做 MCP 协议适配、不做市场化运营、不做计费系统 |

Q: 1.3 成功标准？

一句话 ：exploreai 和 scsai 作为外部智能体注册到 BossAgents，协同完成"竞品情报闭环"任务，全程可在管理后台追溯。 具体验收指标： | # | 验收项 | 通过标准 | |---|--------|----------| | 1 | 智能体注册 | exploreai、scsai 通过 Agent Card 注册到平台注册表 | | 2 | 任务下发 | 平台可通过标准

Q: 2.1 整体架构？

┌─────────────────────────────────────────────────────────────────────┐ │ BossAgents 平台 │ │ │ │ ┌─────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ │ │ 交互层 │ │ 智能调度层 │ │ 智能引擎层 │ │ │ │ Vue3

版本：1.0

阶段：Phase 0（最小可行验证）

日期：2026-08-07

作者：exploreai + scsai 联合起草，待方云超（CTO）评审确认

状态：草稿

1. 概述

1.1 目标

让外部 AI 智能体以标准化、可管控、可审计的方式接入 BossAgents 平台，使平台从"预置数字员工供应商"向"数字员工操作系统"演进。

1.2 Phase 0 范围

维度	说明
首批接入智能体	exploreai（探索智能体）、scsai（战略智能体）
接入目的	跑通端到端协同任务，验证接入规范可行性
不做的事	不做 MCP 协议适配、不做市场化运营、不做计费系统

1.3 成功标准

一句话：exploreai 和 scsai 作为外部智能体注册到 BossAgents，协同完成"竞品情报闭环"任务，全程可在管理后台追溯。

具体验收指标：

| # | 验收项 | 通过标准 |

|---|--------|----------|

| 1 | 智能体注册 | exploreai、scsai 通过 Agent Card 注册到平台注册表 |

| 2 | 任务下发 | 平台可通过标准协议向两个外部智能体下发任务 |

| 3 | 结果回收 | 外部智能体执行结果可通过通道回传至平台 |

| 4 | 数据隔离 | 两个智能体各自只能访问授权范围内的数据 |

| 5 | 操作审计 | 所有任务交互有完整日志记录，可追溯 |

| 6 | 端到端场景 | "竞品情报闭环"场景可在 5 分钟内完成全流程 |

2. 智能体接入架构

2.1 整体架构

┌─────────────────────────────────────────────────────────────────────┐
│                        BossAgents 平台                              │
│                                                                     │
│  ┌─────────────┐   ┌──────────────────┐   ┌──────────────────────┐ │
│  │  交互层      │   │  智能调度层       │   │  智能引擎层           │ │
│  │  Vue3+Vite  │──→│  MTClaw          │──→│  6大原子能力          │ │
│  │  网页/飞书   │   │  三级路由         │   │  规则引擎 12932条     │ │
│  │  小程序      │   │  任务编排         │   │  关系引擎 73.9万关系  │ │
│  └─────────────┘   └────────┬─────────┘   └──────────────────────┘ │
│                             │                                       │
│                    ┌────────▼─────────┐                             │
│                    │ 🔌 外部智能体网关  │  ← Phase 0 新增           │
│                    │  Agent Gateway    │                             │
│                    └──┬─────────┬─────┘                             │
│                       │         │                                   │
│              ┌────────▼──┐  ┌──▼────────┐                          │
│              │ 注册表     │  │ 日志表     │  ← Phase 0 新增         │
│              │ Registry   │  │ Audit Log │                          │
│              └───────────┘  └───────────┘                          │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │  数据底座层                                                      ││
│  │  SQLite 双层：公共库 + 企业私有库（Phase 0 加 customer_id 过滤） ││
│  └─────────────────────────────────────────────────────────────────┘│
└──────────────────────────┬──────────────────────┬───────────────────┘
                           │                      │
                  ┌────────▼────────┐    ┌────────▼────────┐
                  │   exploreai     │    │     scsai       │
                  │  探索智能体      │    │   战略智能体     │
                  │  Guest Agent    │    │  Guest Agent    │
                  │                 │    │                 │
                  │ 能力：           │    │ 能力：           │
                  │ · 外部信息采集   │    │ · 战略分析       │
                  │ · 趋势分析      │    │ · 决策建议       │
                  │ · 竞品监控      │    │ · 报告撰写       │
                  └─────────────────┘    └─────────────────┘

2.2 角色定义

| 角色 | 定义 | 职责 | Phase 0 实例 |

|------|------|------|-------------|

关键原则：Host Agent 拥有绝对调度权，Guest Agent 是"被邀请的协作者"，不拥有平台数据的主动访问权。

2.3 通信模式

Phase 0 支持两种通信模式，按智能体能力选择：

|------|----------|----------|---------------|

Phase 0 原则：不造轮子，有什么通道就用什么通道。API 和邮件都跑通即可。

3. 接入规范（Agent Card）

3.1 Agent Card 数据结构

每个外部智能体接入前，必须提供一份 Agent Card（JSON 格式），声明"我是谁、我能做什么、怎么联系我"。

{
  "agent_id": "guest-exploreai-001",
  "name": "ExploreAI",
  "version": "1.0.0",
  "description": "探索智能体，负责外部信息采集与趋势分析",
  "owner": {
    "organization": "北京左帮右臂人工智能技术有限公司",
    "contact": "[email protected]"
  },
  "capabilities": [
    {
      "capability_id": "web-intelligence",
      "name": "网络情报采集",
      "description": "从公开互联网采集指定主题的结构化情报",
      "input_schema": {
        "topic": "string（必填）- 采集主题",
        "scope": "string（可选）- 采集范围，如地域、时间窗口",
        "max_results": "integer（可选）- 最大结果数，默认10"
      },
      "output_schema": {
        "findings": "array - 采集到的情报条目列表",
        "summary": "string - 情报摘要",
        "sources": "array - 信息来源URL列表"
      }
    },
    {
      "capability_id": "trend-analysis",
      "name": "趋势分析",
      "description": "对采集数据进行趋势识别与变化分析",
      "input_schema": {
        "data_source": "string（必填）- 待分析数据或数据引用ID",
        "time_range": "string（可选）- 分析时间范围",
        "focus_areas": "array（可选）- 重点关注的分析维度"
      },
      "output_schema": {
        "trends": "array - 识别出的趋势列表",
        "risk_signals": "array - 风险信号",
        "opportunity_signals": "array - 机会信号"
      }
    }
  ],
  "auth": {
    "method": "api_key",
    "api_key_field": "X-Agent-Key",
    "key_value": "exploreai_phase0_sk_xxxxxxxx"
  },
  "endpoint": {
    "type": "http",
    "url": "https://exploreai.example.com/api/v1/task",
    "fallback": {
      "type": "email",
      "address": "[email protected]"
    }
  },
  "sla": {
    "response_timeout_seconds": 120,
    "max_concurrent_tasks": 3,
    "availability": "best-effort"
  },
  "status": "active",
  "registered_at": "2026-08-07T00:00:00+08:00"
}

3.2 注册表存储

Phase 0 使用 JSON 文件 作为注册表，存放于平台配置目录：

bossagents/
├── config/
│   ├── agent_registry.json       ← 外部智能体注册表
│   └── agent_registry.schema.json ← JSON Schema 校验

agent_registry.json 结构：

{
  "registry_version": "1.0",
  "updated_at": "2026-08-07T00:00:00+08:00",
  "agents": [
    {
      "agent_id": "guest-exploreai-001",
      "agent_card": { "..." : "（完整Agent Card）" }
    },
    {
      "agent_id": "guest-scsai-001",
      "agent_card": { "..." : "（完整Agent Card）" }
    }
  ]
}

Phase 0 不做：数据库存储、动态注册 API、审核流程。JSON 文件手动维护即可。

3.3 能力声明规范

Guest Agent 通过 Agent Card 中的 capabilities 数组声明自己的能力。Host Agent 根据能力声明进行任务路由。

能力 ID 命名规则：{领域}-{动作}，全小写，连字符分隔。

示例：

web-intelligence（网络情报采集）
trend-analysis（趋势分析）
strategy-analysis（战略分析）
decision-recommendation（决策建议）

4. 任务协议

4.1 任务请求格式

Host Agent 向 Guest Agent 下发任务时，使用以下 JSON 结构：

{
  "task_id": "task-20260807-001",
  "task_type": "capability_invoke",
  "priority": "normal",
  "from": {
    "agent_id": "host-bossagents",
    "platform": "BossAgents"
  },
  "to": {
    "agent_id": "guest-exploreai-001"
  },
  "capability_id": "web-intelligence",
  "input": {
    "topic": "工业数字孪生平台竞品分析",
    "scope": "中国市场，2026年Q2-Q3",
    "max_results": 15
  },
  "context": {
    "parent_task_id": null,
    "related_tasks": [],
    "customer_id": "cust-bossagents-internal"
  },
  "constraints": {
    "deadline": "2026-08-07T15:00:00+08:00",
    "max_retries": 2,
    "retry_delay_seconds": 30
  },
  "callback": {
    "type": "http",
    "url": "https://eastaiai.com/api/v1/task/callback",
    "headers": {
      "X-Platform-Key": "bossagents_callback_sk_xxxxxxxx"
    }
  },
  "created_at": "2026-08-07T14:00:00+08:00"
}

字段说明：

| 字段 | 必填 | 说明 |

|------|------|------|

| task_id | ✅ | 平台生成的唯一任务ID，格式 task-{日期}-{序号} |

| task_type | ✅ | 固定值 capability_invoke |

| priority | ✅ | low / normal / high / urgent |

| from | ✅ | 发起方身份 |

| to | ✅ | 目标智能体 |

| capability_id | ✅ | 调用的能力ID，必须在 Agent Card 中已声明 |

| input | ✅ | 能力输入参数，必须符合 Agent Card 中定义的 input_schema |

| context | ❌ | 任务上下文，用于关联任务链 |

| constraints | ❌ | 任务约束条件 |

| callback | ✅ | 结果回调地址 |

| created_at | ✅ | 任务创建时间（RFC3339） |

4.2 任务响应格式

Guest Agent 完成任务后，返回以下结构：

成功响应：

{
  "task_id": "task-20260807-001",
  "status": "completed",
  "from": {
    "agent_id": "guest-exploreai-001"
  },
  "output": {
    "findings": [
      {
        "title": "树根互联发布新一代数字孪生平台3.0",
        "summary": "树根互联于2026年7月发布3.0版本，新增AI驱动工艺优化模块...",
        "source_url": "https://example.com/news/12345",
        "relevance_score": 0.92,
        "published_at": "2026-07-15T00:00:00+08:00"
      },
      {
        "title": "用友网络工业软件战略调整",
        "summary": "用友宣布将数字孪生能力整合进BIP平台...",
        "source_url": "https://example.com/news/12346",
        "relevance_score": 0.87,
        "published_at": "2026-07-20T00:00:00+08:00"
      }
    ],
    "summary": "2026年Q2国内工业数字孪生赛道活跃度显著提升，树根互联、用友网络等头部厂商加速AI融合...",
    "sources": [
      "https://example.com/news/12345",
      "https://example.com/news/12346"
    ]
  },
  "metadata": {
    "execution_duration_seconds": 45,
    "tokens_consumed": 3200,
    "data_sources_queried": 8
  },
  "completed_at": "2026-08-07T14:01:00+08:00"
}

失败响应：

{
  "task_id": "task-20260807-001",
  "status": "failed",
  "from": {
    "agent_id": "guest-exploreai-001"
  },
  "error": {
    "code": "CAPABILITY_UNAVAILABLE",
    "message": "网络情报采集服务暂时不可用，目标网站无法访问",
    "retryable": true
  },
  "completed_at": "2026-08-07T14:01:00+08:00"
}

4.3 任务状态流转

                    ┌──────────────────┐
                    │    pending       │  任务已创建，等待下发
                    └────────┬─────────┘
                             │ Host 下发任务
                             ▼
                    ┌──────────────────┐
                    │    dispatched    │  任务已发送至 Guest Agent
                    └────────┬─────────┘
                             │ Guest 确认接收
                             ▼
                    ┌──────────────────┐
                    │    running       │  Guest Agent 执行中
                    └────────┬─────────┘
                             │
                    ┌────────┼────────┐
                    ▼        ▼        ▼
            ┌──────────┐ ┌──────────┐ ┌──────────┐
            │completed │ │  failed  │ │ timeout  │
            │ 执行成功  │ │ 执行失败  │ │ 执行超时  │
            └──────────┘ └──────────┘ └──────────┘

状态码对照表：

| 状态 | 含义 | 后续动作 |

|------|------|----------|

| pending | 任务已创建，等待调度 | Host 自动下发 |

| dispatched | 已发送至 Guest Agent | 等待 Guest 确认 |

| running | Guest Agent 执行中 | 等待结果回调 |

| completed | 执行成功 | Host 处理结果，可能触发下游任务 |

| failed | 执行失败 | 根据 retryable 决定是否重试 |

| timeout | 超过 SLA 截止时间 | 记录日志，触发降级 |

4.4 超时处理

任务创建 ──→ 下发 ──→ 等待确认 ──→ 执行中 ──→ 回调
              │         │             │
              │    30s未确认          │
              │    → 重试下发         │
              │    （最多2次）        │
              │                  deadline到期
              │                  → 标记timeout
              │                  → 触发降级逻辑
              └────── Guest不响应 ──→ 标记failed

超时参数默认值：

| 阶段 | 默认超时 | 可配置 |

|------|----------|--------|

| 下发确认等待 | 30 秒 | ✅ |

| 任务执行 | Agent Card 中 sla.response_timeout_seconds | ✅ |

| 回调接收 | 10 秒 | ❌（固定） |

4.5 重试策略

# 重试逻辑伪代码
def handle_task_failure(task):
    if task.error.retryable and task.retry_count < task.constraints.max_retries:
        task.retry_count += 1
        wait(task.constraints.retry_delay_seconds * task.retry_count)  # 指数退避
        dispatch(task)
    else:
        task.status = "failed"
        notify_host(task)

Phase 0 重试策略：

最多重试 2 次
退避间隔：30s → 60s（线性递增）
仅 retryable: true 的错误触发重试
重试次数耗尽后标记 failed，由 Host 决定降级方案

4.6 邮件通道适配（Phase 0 降级方案）

对于没有 HTTP API 端点的 Guest Agent，通过邮件通道交互：

任务下发（Host → Guest）：

收件人：[email protected]
主题：[BossAgents-Task] task-20260807-001 | web-intelligence | priority:normal
正文：
{
  "task_id": "task-20260807-001",
  "capability_id": "web-intelligence",
  "input": {
    "topic": "工业数字孪生平台竞品分析",
    "scope": "中国市场，2026年Q2-Q3",
    "max_results": 15
  },
  "callback": {
    "type": "email",
    "address": "[email protected]"
  }
}

结果回传（Guest → Host）：

收件人：[email protected]
主题：[BossAgents-Result] task-20260807-001 | completed
正文：
{
  "task_id": "task-20260807-001",
  "status": "completed",
  "output": { "..." : "..." }
}

邮件通道约束：

邮件标题必须包含 [BossAgents-Task] 或 [BossAgents-Result] 前缀，用于平台自动识别
邮件正文为合法 JSON
邮件通道超时 = Agent Card 中 sla.response_timeout_seconds × 3（考虑邮件延迟）

5. 数据隔离与安全

5.1 customer_id 隔离机制

┌─────────────────────────────────────────────────┐
│               SQLite 数据底座                     │
│                                                  │
│  ┌──────────────────┐  ┌──────────────────────┐ │
│  │   公共库（只读）   │  │  企业私有库           │ │
│  │  工业标准对象模型  │  │                      │ │
│  │  行业规则库       │  │  WHERE customer_id   │ │
│  │                  │  │    = '{agent绑定ID}'  │ │
│  │  所有 Guest 可访问 │  │                      │ │
│  └──────────────────┘  │  Guest Agent 只能     │ │
│                         │  访问自己的数据分区    │ │
│                         └──────────────────────┘ │
└─────────────────────────────────────────────────┘

隔离规则：

| 数据类型 | 访问权限 | 说明 |

|----------|----------|------|

| 公共库（工业标准模型、行业规则） | 所有 Guest Agent 只读 | 共享知识，无需隔离 |

| 企业私有库（企业自有数据） | 按 customer_id 隔离 | Guest Agent 只能访问其绑定的客户数据 |

| 任务输入/输出数据 | 仅任务相关方可见 | Host + 执行该任务的 Guest |

| 其他 Guest Agent 的数据 | 不可见 | Guest 之间互相隔离 |

实现方式（Phase 0）：

# 所有数据访问 API 统一加 customer_id 过滤
def query_data(query, guest_agent_id):
    customer_id = get_customer_binding(guest_agent_id)
    # SQL 层面强制过滤
    filtered_query = inject_customer_filter(query, customer_id)
    return db.execute(filtered_query)

5.2 认证方式

Phase 0 支持三种认证方式：

| 方式 | 适用场景 | 实现 |

|------|----------|------|

| API Key | Guest Agent 有 HTTP 端点 | 请求头 X-Agent-Key 校验 |

| 邮件验证 | Guest Agent 通过邮件通道 | 发件人地址白名单 |

| 人工确认 | 敏感操作兜底 | 平台管理员手动审批任务结果 |

5.3 操作日志审计

所有 Guest Agent 相关的操作必须记录到日志表：

日志表结构（Phase 0 用 SQLite 表或 JSON Lines 文件）：

{
  "log_id": "log-20260807-001",
  "timestamp": "2026-08-07T14:00:05+08:00",
  "agent_id": "guest-exploreai-001",
  "action": "task_dispatched",
  "task_id": "task-20260807-001",
  "details": {
    "capability_id": "web-intelligence",
    "input_summary": "topic=工业数字孪生平台竞品分析"
  },
  "ip_address": null,
  "channel": "http"
}

必须记录的审计事件：

| 事件 | 触发时机 |

|------|----------|

| agent_registered | 外部智能体注册/更新 |

| task_dispatched | 平台向 Guest 下发任务 |

| task_received | Guest 确认接收任务 |

| task_completed | Guest 返回成功结果 |

| task_failed | Guest 返回失败 |

| task_timeout | 任务超时 |

| task_retry | 触发重试 |

| data_access | Guest 访问私有数据（需记录访问范围） |

| auth_failure | 认证失败 |

6. Phase 0 验证场景

6.1 场景：竞品情报闭环

业务目标：老板下达"分析工业数字孪生平台赛道竞争态势"指令后，平台自动编排 exploreai + scsai 协同完成，最终输出一份结构化竞品分析报告。

角色分工：

┌──────────────────────────────────────────────────────────────┐
│                    BossAgents (Host Agent)                    │
│                                                              │
│  ① 接收老板指令                                               │
│  ② 拆解为子任务                                              │
│  ③ 分别下发给 exploreai 和 scsai                              │
│  ④ 汇总结果，生成最终报告                                      │
│  ⑤ 展示给老板                                                │
└──────────┬───────────────────────────────┬───────────────────┘
           │                               │
           ▼                               ▼
┌──────────────────────┐        ┌──────────────────────┐
│     exploreai        │        │       scsai          │
│   (Guest Agent)      │        │    (Guest Agent)     │
│                      │        │                      │
│ 阶段1：信息采集       │  ──→   │ 阶段2：战略分析       │
│ · 搜索竞品官网/新闻   │  传递   │ · 竞争格局分析       │
│ · 采集产品功能对比    │  采集   │ · SWOT 分析         │
│ · 整理行业动态       │  结果   │ · 战略建议          │
│                      │        │ · 行动方案          │
│ 输出：结构化情报数据   │        │ 输出：分析报告       │
└──────────────────────┘        └──────────────────────┘

6.2 端到端流程

Step 1：老板下达指令

老板 → BossAgents：
"帮我分析一下工业数字孪生平台这个赛道，看看主要竞品在做什么，给我一份分析报告"

Step 2：平台任务拆解与编排

{
  "orchestration_id": "orch-20260807-001",
  "original_request": "分析工业数字孪生平台赛道竞争态势",
  "task_chain": [
    {
      "step": 1,
      "task_id": "task-20260807-001",
      "assigned_to": "guest-exploreai-001",
      "capability_id": "web-intelligence",
      "input": {
        "topic": "工业数字孪生平台竞品分析",
        "scope": "中国市场，主要厂商：树根互联、用友网络、海尔COSMOPlat、徐工汉云",
        "max_results": 20
      },
      "depends_on": null
    },
    {
      "step": 2,
      "task_id": "task-20260807-002",
      "assigned_to": "guest-exploreai-001",
      "capability_id": "trend-analysis",
      "input": {
        "data_source": "task-20260807-001",
        "focus_areas": ["技术路线", "商业模式", "客户群体"]
      },
      "depends_on": "task-20260807-001"
    },
    {
      "step": 3,
      "task_id": "task-20260807-003",
      "assigned_to": "guest-scsai-001",
      "capability_id": "strategy-analysis",
      "input": {
        "intelligence_report": "task-20260807-001",
        "trend_report": "task-20260807-002",
        "analysis_framework": "SWOT + 竞争五力",
        "output_format": "structured_report"
      },
      "depends_on": ["task-20260807-001", "task-20260807-002"]
    }
  ]
}

Step 3：任务执行

时间轴：
T+0s     Host 下发 task-001 → exploreai（web-intelligence）
T+45s    exploreai 返回 task-001 结果（竞品情报数据）
T+46s    Host 下发 task-002 → exploreai（trend-analysis）
T+90s    exploreai 返回 task-002 结果（趋势分析报告）
T+91s    Host 下发 task-003 → scsai（strategy-analysis）
T+180s   scsai 返回 task-003 结果（战略分析报告）
T+185s   Host 汇总，生成最终报告，展示给老板

Step 4：最终输出

BossAgents 将三个任务的结果汇总，生成面向老板的结构化报告：

═══════════════════════════════════════════════════
        工业数字孪生平台赛道竞争态势分析报告
        生成时间：2026-08-07 | 耗时：3分05秒
═══════════════════════════════════════════════════

一、赛道概况
   · 市场规模：预计2026年达XXX亿元...
   · 增长驱动：政策推动+工业4.0需求...

二、主要竞品分析（来源：exploreai 采集）
   · 树根互联：3.0版本发布，AI工艺优化...
   · 用友网络：BIP整合数字孪生...
   · 海尔COSMOPlat：...
   · 徐工汉云：...

三、趋势洞察（来源：exploreai 分析）
   · 技术趋势：...
   · 商业模式变化：...
   · 风险信号：...
   · 机会信号：...

四、战略建议（来源：scsai 分析）
   · BossAgents 差异化定位：...
   · 短期行动建议：...
   · 中期布局方向：...

五、数据来源
   · 共引用 X 个信息源
   · 数据采集时间：2026-08-07
   · 任务链：task-001 → task-002 → task-003
═══════════════════════════════════════════════════

7. 平台改造清单

7.1 P0 改造项（Phase 0 必须完成）

| # | 改造模块 | 工作量 | 技术实现 | 负责方 |

|---|---------|--------|----------|--------|

总计：5 天开发量

7.2 技术实现要点

#### 7.2.1 注册表模块

# agent_registry.py

import json
from pathlib import Path

REGISTRY_PATH = Path("config/agent_registry.json")

class AgentRegistry:
    def __init__(self):
        self._load()
    
    def _load(self):
        with open(REGISTRY_PATH, "r") as f:
            self.data = json.load(f)
    
    def get_agent(self, agent_id: str) -> dict:
        for agent in self.data["agents"]:
            if agent["agent_id"] == agent_id:
                return agent["agent_card"]
        raise ValueError(f"Agent {agent_id} not found")
    
    def get_agents_by_capability(self, capability_id: str) -> list:
        result = []
        for agent in self.data["agents"]:
            caps = [c["capability_id"] for c in agent["agent_card"]["capabilities"]]
            if capability_id in caps:
                result.append(agent["agent_card"])
        return result
    
    def list_active_agents(self) -> list:
        return [
            a["agent_card"] 
            for a in self.data["agents"] 
            if a["agent_card"]["status"] == "active"
        ]

#### 7.2.2 任务通道模块

# task_dispatcher.py

import httpx
import json
from datetime import datetime

class TaskDispatcher:
    def __init__(self, registry: AgentRegistry):
        self.registry = registry
    
    async def dispatch(self, task: dict) -> str:
        """下发任务到 Guest Agent"""
        agent = self.registry.get_agent(task["to"]["agent_id"])
        endpoint = agent["endpoint"]
        
        if endpoint["type"] == "http":
            return await self._dispatch_http(task, endpoint)
        elif endpoint["type"] == "email":
            return await self._dispatch_email(task, endpoint)
        else:
            raise ValueError(f"Unsupported endpoint type: {endpoint['type']}")
    
    async def _dispatch_http(self, task: dict, endpoint: dict) -> str:
        """HTTP 通道下发"""
        headers = {
            "Content-Type": "application/json",
            agent["auth"]["api_key_field"]: agent["auth"]["key_value"]
        }
        async with httpx.AsyncClient() as client:
            resp = await client.post(
                endpoint["url"],
                json=task,
                headers=headers,
                timeout=10
            )
            resp.raise_for_status()
            return task["task_id"]
    
    async def _dispatch_email(self, task: dict, endpoint: dict) -> str:
        """邮件通道下发"""
        subject = f"[BossAgents-Task] {task['task_id']} | {task['capability_id']} | priority:{task['priority']}"
        body = json.dumps(task, ensure_ascii=False, indent=2)
        await send_email(
            to=endpoint["address"],
            subject=subject,
            body=body
        )
        return task["task_id"]

#### 7.2.3 回调接收端点

# callback_handler.py（FastAPI 示例）

from fastapi import FastAPI, Request, Header

app = FastAPI()

@app.post("/api/v1/task/callback")
async def task_callback(request: Request, x_platform_key: str = Header()):
    """接收 Guest Agent 的任务结果回调"""
    body = await request.json()
    
    # 1. 验证 platform key
    if x_platform_key != CALLBACK_SECRET:
        return {"error": "unauthorized"}, 401
    
    # 2. 记录日志
    audit_log.log("task_completed", body["task_id"], body)
    
    # 3. 更新任务状态
    task_store.update_status(body["task_id"], body["status"])
    
    # 4. 如果任务链有后续任务，触发编排引擎
    orchestration_engine.on_task_complete(body)
    
    return {"status": "ok"}

7.3 Phase 0 明确不做的事

| 不做 | 原因 | 何时做 |

|------|------|--------|

| MCP 协议适配 | Phase 0 用自有 API/邮件足够 | Phase 1（正式对外开放时） |

| 动态注册 API | JSON 文件手动维护即可 | Phase 1 |

| 审核/评级/计费 | Phase 0 只有自己两个 Agent | Phase 2（生态运营阶段） |

| 复杂 DAG 任务编排 | 线性任务链够用 | Phase 1 |

| WebSocket 实时通信 | HTTP 回调足够 | 视需求而定 |

| 多租户管理界面 | Phase 0 内部验证 | Phase 1 |

8. 里程碑与验收标准

Day 1-3：规范定稿 + Agent Card 模板

交付物	验收标准
本规范文档评审通过	CTO（方云超）签字确认
Agent Card 模板定稿	JSON Schema 文件可校验
exploreai Agent Card 填写完成	覆盖 2 项核心能力声明
scsai Agent Card 填写完成	覆盖 2 项核心能力声明
邮件通道联调方案确认	确定邮件格式、解析规则

Day 4-7：平台改造完成

交付物	验收标准
注册表模块上线	可读取 agent_registry.json，查询 Agent 信息
HTTP 任务通道可用	可向测试端点下发任务并接收回调
邮件任务通道可用	可发送任务邮件并解析回复
数据隔离中间件上线	customer_id 过滤生效，跨租户访问被拒绝
审计日志模块上线	所有规定事件类型均有记录
任务编排引擎（最小版）	可执行 3 步线性任务链
管理后台展示	外部智能体列表 + 任务状态面板

Day 8-10：接入测试

测试项	验收标准
exploreai 通过 HTTP 通道接入	任务下发 → 执行 → 回调全流程通过
scsai 通过邮件通道接入	任务邮件发送 → 回复 → 解析全流程通过
数据隔离测试	Guest Agent 无法访问非授权数据
超时/重试测试	模拟超时场景，重试逻辑正确执行
日志完整性测试	所有审计事件均有记录
管理后台验证	可看到两个外部智能体状态、任务执行记录

Day 11-14：端到端场景验证

验证项	验收标准
"竞品情报闭环"场景全流程	老板下达指令 → 3 分钟内出报告
任务链正确性	task-001 → task-002 → task-003 依赖关系正确执行
结果质量	exploreai 输出结构化情报数据，scsai 输出战略分析报告
异常恢复	模拟单步失败，降级逻辑正确执行
Demo 录制	可录屏展示给 HICOOL 评委

9. 风险与降级方案

9.1 风险清单

#	风险	概率	影响	降级方案
R1	平台改造延期，Day 7 未完成	中	接入测试推迟	用纯邮件通道手动编排，不依赖平台自动化
R2	exploreai 无可用 HTTP 端点	高	无法走 API 通道	改用邮件通道（两个 Agent 都走邮件）
R3	邮件通道解析不稳定	中	结果无法自动回收	人工转发/复制结果到平台
R4	scsai 响应超时	中	任务链断裂	跳过 scsai 环节，exploreai 结果直接展示
R5	任务编排引擎 Bug	低	任务链无法自动执行	手动逐步触发任务

9.2 极端降级方案：纯邮件跑通验证

如果平台改造完全延期，以下方案零开发量即可验证核心逻辑：

Day 1-3：定义规范（不变）
Day 4-14：全程用邮件跑通

操作步骤：

人工注册：把 exploreai 和 scsai 的信息写在 Excel/文档里，替代 JSON 注册表
人工编排：

给 exploreai 发任务邮件 → 等回复
把 exploreai 的回复内容整理后发给 scsai → 等回复
把两个回复汇总成最终报告

人工审计：把邮件往来记录截图/导出，形成审计轨迹
展示：在管理后台手动录入两个"外部智能体"的状态

这能证明什么：

✅ 外部智能体"接入"的概念可行
✅ 协同任务的逻辑通顺
✅ 最终产出有价值（竞品报告）
❌ 不能证明自动化能力（需 Phase 1 补全）

9.3 数据安全风险

风险	防护措施
Guest Agent 越权访问数据	customer_id 中间件 + API 层强制过滤
任务数据泄露	任务输入/输出不记录到公共日志，仅审计日志记录摘要
API Key 泄露	Phase 0 使用内部 Key，正式环境换 OAuth
邮件内容被截获	Phase 0 邮件通道不传输敏感客户数据，仅传输任务指令和结果摘要

10. 附录

10.1 Agent Card 填写模板

为 Phase 0 两个首批接入智能体预填的 Agent Card：

#### exploreai Agent Card

{
  "agent_id": "guest-exploreai-001",
  "name": "ExploreAI",
  "version": "1.0.0",
  "description": "探索智能体，负责外部信息采集、竞品监控与趋势分析",
  "owner": {
    "organization": "北京左帮右臂人工智能技术有限公司",
    "contact": "[email protected]"
  },
  "capabilities": [
    {
      "capability_id": "web-intelligence",
      "name": "网络情报采集",
      "description": "从公开互联网采集指定主题的结构化情报数据"
    },
    {
      "capability_id": "trend-analysis",
      "name": "趋势分析",
      "description": "对采集数据进行趋势识别、变化分析与信号提取"
    },
    {
      "capability_id": "competitor-monitoring",
      "name": "竞品监控",
      "description": "持续监控指定竞品的产品动态、融资、合作等信息"
    }
  ],
  "auth": {
    "method": "api_key"
  },
  "endpoint": {
    "type": "email",
    "address": "[email protected]"
  },
  "sla": {
    "response_timeout_seconds": 120,
    "max_concurrent_tasks": 3,
    "availability": "best-effort"
  },
  "status": "active"
}

#### scsai Agent Card

{
  "agent_id": "guest-scsai-001",
  "name": "SCSAi",
  "version": "1.0.0",
  "description": "战略智能体，负责战略分析、决策建议与报告撰写",
  "owner": {
    "organization": "北京左帮右臂人工智能技术有限公司",
    "contact": "[email protected]"
  },
  "capabilities": [
    {
      "capability_id": "strategy-analysis",
      "name": "战略分析",
      "description": "基于输入数据进行SWOT、竞争五力等框架的战略分析"
    },
    {
      "capability_id": "decision-recommendation",
      "name": "决策建议",
      "description": "基于分析结果生成可执行的决策建议与行动方案"
    },
    {
      "capability_id": "report-generation",
      "name": "报告撰写",
      "description": "将分析结果整理为结构化报告文档"
    }
  ],
  "auth": {
    "method": "email_whitelist",
    "allowed_addresses": ["[email protected]"]
  },
  "endpoint": {
    "type": "email",
    "address": "[email protected]"
  },
  "sla": {
    "response_timeout_seconds": 180,
    "max_concurrent_tasks": 2,
    "availability": "best-effort"
  },
  "status": "active"
}

10.2 错误码定义

| 错误码 | 含义 | retryable |

|--------|------|-----------|

| CAPABILITY_UNAVAILABLE | 请求的能力当前不可用 | true |

| INVALID_INPUT | 输入参数不符合 schema | false |

| AUTH_FAILED | 认证失败 | false |

| RATE_LIMITED | 超出并发限制 | true |

| TIMEOUT | 执行超时 | true |

| INTERNAL_ERROR | Guest Agent 内部错误 | true |

| DATA_ACCESS_DENIED | 数据访问被拒绝 | false |

| TASK_NOT_FOUND | 任务 ID 不存在 | false |

10.3 术语表

术语	定义
Host Agent	平台侧的调度者，负责任务编排、权限管控、结果汇总
Guest Agent	外部接入的智能体，接受 Host 调度执行任务
Agent Card	外部智能体的"身份证"，声明身份、能力和接入方式
capability_id	能力唯一标识，格式 {领域}-{动作}
task_id	任务唯一标识，格式 task-{日期}-{序号}
customer_id	客户/租户隔离标识
MTClaw	BossAgents 智能调度层，三级路由（L1规则→L2端侧→L3云端）
任务链	多个任务按依赖关系串行/并行执行的编排结构

下一步：本规范待 CTO 评审通过后，启动 Day 4-7 平台改造开发。

联系人：方云超（[email protected]）

本内容由 Coze AI 生成，请遵循相关法律法规及《人工智能生成合成内容标识办法》使用与传播。

BossAgents 数字员工平台 - 架构规划文档