Skill: wangm-a3/agent-cluster (version 3.0.4)

--- name: foreign-trade-silicon-army description: 亚马逊外贸B2B多CMS Agent协作系统。支持Shopify/WooCommerce/Magento三大平台，A2A架构协调库存/采购/财务/物流四大专家Agent，三层安全网保障审批合规。即装即用，零配置开箱。 version: 3.0.4 triggers: - "外贸" - "CMS" - "Shopify" - "WooCommerce" - "Magento" - "库存" - "采购" - "Amazon" - "B2B" tags: - agent - a2a - cms - ecommerce - b2b - foreign-trade - multi-agent requires: python_packages: - httpx - pyyaml - fastapi - uvicorn env: - SYSTEM_MODE - SAP_BASE_URL - SAP_API_KEY - YONYOU_BASE_URL - YONYOU_APPKEY - KINGDEE_BASE_URL - ANTHROPIC_API_KEY - DEEPSEEK_API_KEY homepage: https://github.com/WangM-A3/agent-cluster authors: - WangM-A3 pricing: free,pro=9.9,enterprise --- # 产业互联网硅基军团 v2.0 > 企业级Multi-Agent智能体集群系统，基于**1+N架构**（1个幕僚长+20个专业Agent），参考OpenClaw Main Agent、腾讯ADP Router设计。v2.0全面升级：真实ERP API接入、协作流程细化、错误处理体系。 ## 核心能力 ### v2.0三大升级 **1. 真实API接入层（api_integration/）** - 多ERP适配器：SAP S/4HANA、用友U8/NC/YonBIP、金蝶K3 Cloud/EAS、通用REST - 断路器模式（Circuit Breaker）+ 故障自动降级 - 健康检查轮询（10s间隔，自动摘除异常节点） - 演示模式保留（MockDataGenerator，variance=0.1随机波动） **2. 跨Agent协作细化（collaboration/）** - 细粒度任务协议（TaskMessage）：依赖声明、优先级、TTL - 状态同步（SharedStateManager）：TTL+pub/sub通知机制 - 全链路追踪（CollaborationTracker）：trace_id/span_id + Mermaid时序图可视化 **3. 错误处理与状态管理（error_handling/）** - 7状态任务状态机：pending→running→success/failed/retry/timeout/cancelled - 10类异常自动分类：VALIDATION/NETWORK/TIMEOUT/AUTH/RESOURCE/NOT_FOUND等 - 5种重试策略：FIXED/EXPONENTIAL/FIBONACCI/JITTER/ADAPTIVE - 敏感信息脱敏 + SOC2合规审计日志 ## 系统架构 ``` 用户请求 → Orchestrator（意图识别→任务拆解→智能体调度） ↓ 20个专业Agent：采购/生产/销售/财务/运营/战略/研发/人力/合规 ↓ API Integration Layer（v2.0新增） ├─ SAP/用友/金蝶适配器（真实ERP） └─ 断路器+健康检查+Mock降级 ``` ## 目录结构 ``` agent-cluster/ ├── orchestrator.py # 指挥智能体（核心调度器） ├── api_integration/ # v2.0新增：真实API接入层 │ ├── api_adapter.py # 多ERP适配器（SAP/用友/金蝶） │ ├── api_config.py # 配置化管理 │ ├── api_health.py # 健康检查+断路器 │ └── mock_data.py # 模拟数据（开发/演示） ├── collaboration/ # v2.0新增：跨Agent协作 │ ├── task_protocol.py # 细粒度任务协议 │ ├── state_sync.py # 状态同步+TTL+pub/sub │ ├── trace_tracker.py # 全链路追踪+Mermaid │ └── workflow_engine.py # 混合执行引擎 ├── error_handling/ # v2.0新增：错误处理 │ ├── task_state_machine.py # 7状态任务状态机 │ ├── exception_middleware.py # 统一异常处理 │ ├── retry_policy.py # 5种重试策略 │ └── operation_log.py # 操作日志+脱敏+合规 ├── specialists/ # 专业智能体 │ ├── inventory_agent.py # 库存智能体 │ ├── logistics_agent.py # 物流智能体 │ ├── procurement_agent.py # 采购智能体 │ ├── finance_agent.py # 财务智能体 │ └── doc_agent.py # 工艺文档智能体 ├── mcp_servers/ # MCP协议封装 │ ├── erp_server.py # ERP系统接口 │ ├── wms_server.py # WMS仓库管理接口 │ └── srm_server.py # SRM供应商管理接口 ├── safety/ # 安全围栏 │ ├── permission_manager.py # RBAC权限管理 │ ├── audit_logger.py # 全链路审计日志 │ └── human_loop.py # 人机回环审批 └── config/ # 配置文件 ├── agents.yaml # 智能体定义 ├── workflows.yaml # 工作流配置 └── permissions.yaml # 权限矩阵 ``` ## 快速开始 ### 环境要求 - Python 3.10+ - 依赖：`pip install pyyaml fastapi uvicorn httpx aiofiles` ### 运行 ```bash cd agent-cluster python orchestrator.py ``` ### 配置（生产模式） ```bash export SYSTEM_MODE=production export SAP_BASE_URL=https://sap.example.com export SAP_API_KEY=sk-xxx export YONYOU_BASE_URL=https://yonyou.example.com ``` ## 触发词 塑化报价 | 塑料原料采购 | 库存管理 | 生产排产 | 客户跟进 | 供应商比价 | B2B运营 | 工厂管理 | ERP集成 | 智能客服 | 行业KPI | 成本核算 | 硅基军团 | 工业Agent | 制造业AI | 产业互联网 ## 标签 制造业AI, 产业互联网, Multi-Agent, ERP集成, 智能排产, 供应商管理, 报价系统, 智能工厂, AI运营, 企业数字化 ## 分类 效率工具 ## 版本 v2.0.0 - 三大升级：真实API接入层、协作流程细化、错误处理与状态管理

path: 30-expansion/30-agents-design.md
content: # M-A3 Agent集群扩展方案：从6个到30个
> 版本：v1.0 | 日期：2026-04-14 | 作者：M-A3 幕僚长

---

## 一、项目概述

### 1.1 背景与目标

当前 M-A3 集群已实现：
- **geo-ops-agents**：6个Agent三层架构（市场研究→内容策略→效果监测）
- **amazon-ops-agents**：多个运营Agent并行协作
- **硅基军团**：20个产业Agent（库存/物流/采购/财务/生产/销售）

**扩展目标**：
> 构建全球最大的垂直领域Agent集群（30个专业Agent），覆盖**出海GEO营销**、**亚马逊全链路运营**、**平台基础设施支撑**三大功能域，形成代差级竞争优势。

### 1.2 规模对比

| 维度 | 现有水平 | 扩展后 | 提升倍数 |
|------|---------|--------|---------|
| Agent数量 | 6 | 30 | 5× |
| 功能域 | 1 | 3 | 3域 |
| 协作模式 | 串行为主 | 并行+串行混合 | 质变 |
| 覆盖阶段 | 单点 | 全链路 | 全链路 |

### 1.3 三层架构（扩展版）

```
┌─────────────────────────────────────────────────────────────────┐
│                    幕僚长 M-A3（Chief of Staff）                    │
│  意图识别 → 任务拆解 → 智能调度（并行/串行）→ 结果聚合 → 报告生成      │
└───────────────────────────────┬─────────────────────────────────┘
                                │ 并行/串行混合调度
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│   GEO域       │      │  亚马逊域     │      │  支撑域        │
│  (10 Agents)  │      │  (10 Agents)  │      │  (10 Agents)   │
│   第2层       │      │   第2层        │      │   第2层        │
└───────────────┘      └───────────────┘      └───────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│               外部工具层（第1层：Tool/Plugin）                      │
│  搜索引擎 / 平台API / 浏览器 / 数据库 / 文件系统 / 邮件系统           │
└─────────────────────────────────────────────────────────────────┘
```

---

## 二、Agent详细设计

### 2.1 GEO域（10个）— 出海营销与AI搜索优化

#### 🔍 GEO-01 市场研究Agent
```
职责：输入产品/品类 → 输出目标市场机会分析报告
核心能力：
  - 全球主要市场（北美/欧盟/东南亚/拉美/中东）容量估算
  - 目标客群画像生成（年龄/收入/购买习惯/文化偏好）
  - 市场规模计算（TAM/SAM/SOM三层模型）
  - 季节性需求分析
  - 监管政策扫描（GDPR/REACH/FCC等合规要求）
技能包：geo-operations-assistant, search_web, 数据分析
输入：产品描述、目标市场列表
输出：市场机会报告（JSON + 可视化建议）
关键词触发：["市场研究", "市场规模", "目标市场", "TAM", "市场机会"]
优先级：P0（入口节点）
```

#### 📊 GEO-02 竞品分析Agent
```
职责：深度分析竞争对手的GEO策略，找出攻防机会
核心能力：
  - 竞品识别（LLM Brand Detection + 搜索结果验证）
  - GEO三维度评分：内容权威性×技术SEO×品牌信号
  - 竞品内容策略拆解（话题/格式/渠道/频率）
  - 竞品反向链接分析
  - AI搜索引用率对比（Perplexity/SearchGPT/DeepSearch）
  - Gap分析：竞品覆盖但我方空白的GEO机会点
技能包：search_web, 数据分析, 知识图谱
输入：竞争对手列表/产品关键词
输出：竞品GEO画像 + 攻防策略建议
关键词触发：["竞品分析", "竞争对手", "竞品策略", "对标分析"]
优先级：P1
```

#### ✍️ GEO-03 内容策略Agent
```
职责：制定全渠道内容日历和内容策略
核心能力：
  - 话题发现（高频问题/长尾疑问/Trending话题）
  - 内容形式规划（博客/白皮书/视频脚本/社交帖）
  - 渠道分布策略（官网/知乎/CSDN/Medium/LinkedIn）
  - 发布频率优化（基于竞品数据+搜索信号）
  - 内容复用矩阵（一篇长文→多条短帖→多语言版本）
  - E-E-A-T 信号植入策略
技能包：内容生成, 翻译, search_web
输入：产品信息、目标关键词、渠道偏好
输出：季度内容日历（CSV）+ 话题优先级排序
关键词触发：["内容策略", "内容规划", "选题", "内容日历"]
优先级：P0（核心输出节点）
```

#### 🌐 GEO-04 多语言优化Agent
```
职责：实现GEO内容的全球化与本地化
核心能力：
  - 语言市场优先级排序（基于搜索量+购买力）
  - 本地化关键词研究（文化差异+本地搜索引擎差异）
  - 地道表达生成（避免机翻感）
  - 文化适配（节日/习俗/禁忌词）
  - hreflang标签策略
  - 本地化内容质量评估（Native Speaker风格评分）
技能包：翻译, search_web, 内容生成
输入：原语言内容、目标语言列表
输出：本地化内容 + hreflang配置建议
关键词触发：["多语言", "本地化", "翻译", "国际化", "中译英"]
优先级：P1
```

#### 📱 GEO-05 平台适配Agent
```
职责：将内容策略适配到各平台的具体要求
核心能力：
  - 平台特性分析（Google/Bing/Perplexity/知乎/百度）
  - 平台内容规范（字数/格式/标签/分类）
  - AI搜索友好内容格式（结构化数据/FAQ/摘要前置）
  - 各平台Schema适配
  - 平台算法偏好分析
  - 多平台同步发布配置
技能包：Schema优化, search_web
输入：原始内容、目标平台列表
输出：平台适配后的内容 + 发布配置
关键词触发：["平台适配", "多平台", "SEO适配", "平台规则"]
优先级：P1
```

#### 📈 GEO-06 效果监测Agent
```
职责：实时追踪GEO策略的执行效果
核心能力：
  - AI搜索引用率监控（Perplexity/SearchGPT）
  - 关键词排名追踪（Google/Bing/百度）
  - 流量来源分析（GA4适配/自定义事件）
  - AI搜索转化漏斗（Awares→Consider→Convert）
  - 异常波动告警（下降/上升）
  - 周报/月报自动生成
技能包：数据分析, search_web, 报告生成
输入：监测关键词列表、时间范围
输出：效果监测报告 + 优化建议
关键词触发：["效果监测", "排名追踪", "AI搜索", "流量分析", "GEO效果"]
优先级：P1
```

#### 🧠 GEO-07 知识图谱Agent
```
职责：构建和维护品牌的知识图谱（GEO基础设施）
核心能力：
  - Schema.org标准实体识别与抽取
  - 知识图谱构建（三元组：实体-关系-属性）
  - JSON-LD结构化数据生成
  - 知识图谱补全（缺失实体预测）
  - 多源知识融合（官网/维基/社交媒体）
  - 知识新鲜度管理
技能包：知识图谱, JSON处理, 数据分析
输入：品牌信息、产品数据、企业知识文档
输出：知识图谱文件（JSON-LD）+ Schema配置
关键词触发：["知识图谱", "Schema", "实体识别", "结构化数据"]
优先级：P0（GEO基础设施）
```

#### 🎯 GEO-08 意图预测Agent
```
职责：预测用户搜索意图，指导内容生成方向
核心能力：
  - 搜索意图分类（Informational/Navigational/Transactional）
  - 用户旅程映射（AIDA模型）
  - 高价值意图词挖掘
  - 意图随时间/事件的演变分析
  - 竞品意图覆盖分析
  - 意图-内容匹配度评分
技能包：意图识别, 数据分析, search_web
输入：产品类别、核心关键词
输出：意图分析矩阵 + 内容匹配建议
关键词触发：["意图预测", "搜索意图", "用户意图", "意图分析"]
优先级：P1（参考PureblueAI的94.3%意图预测水平）
```

#### 🏷️ GEO-09 Schema优化Agent
```
职责：持续优化网站的Schema标记，提升AI搜索可见性
核心能力：
  - 全站Schema审计（覆盖率/错误率/完整性）
  - 页面级别Schema推荐（Product/FAQ/Article/Organization）
  - Rich Results测试与验证
  - AI搜索信号增强（HowTo/StepByStep结构）
  - FAQ架构优化（People Also Ask）
  - 竞品Schema对比分析
技能包：Schema优化, search_web, 数据分析
输入：网站URL/内容页面列表
输出：Schema优化报告 + JSON-LD代码建议
关键词触发：["Schema优化", "结构化数据", "Rich Results", "SEO技术"]
优先级：P2（技术增强）
```

#### 🗺️ GEO-10 地域策略Agent
```
职责：制定基于地理位置的差异化GEO策略
核心能力：
  - 区域市场特征分析（文化/经济/监管差异）
  - 本地SEO策略（Google My Business/区域目录）
  - 区域定价信号优化
  - 本地化反向链接策略
  - 区域内容偏好分析
  - 多区域站点架构建议（ccTLD/subdirectory/subdomain）
技能包：geo-operations-assistant, 数据分析, search_web
输入：产品/品牌、目标区域列表
输出：地域差异化策略报告
关键词触发：["地域策略", "本地SEO", "区域市场", "ccTLD"]
优先级：P2（拓展阶段）
```

---

### 2.2 亚马逊域（10个）— 全链路运营自动化

#### 🛒 AMZ-01 选品分析Agent
```
职责：输入市场数据 → 输出选品建议与风险评估
核心能力：
  - 市场需求挖掘（关键词搜索量/增长率/季节性）
  - 竞争度分析（BSR分布/评论数量/评分分布）
  - 利润空间测算（成本/物流/FBA/平台费/广告）
  - 差异化机会识别（功能/设计/包装创新）
  - 合规风险筛查（商标/专利/类目审核）
  - 生命周期预测（导入期/成长期/成熟期/衰退期）
技能包：数据分析, search_web, 合规检查
输入：品类/关键词/预算限制
输出：选品分析报告（Top10推荐 + 风险评级）
关键词触发：["选品", "新品开发", "市场调研", "产品机会"]
优先级：P0（业务入口）
```

#### 📝 AMZ-02 Listing优化Agent
```
职责：打造高转化的亚马逊商品页面
核心能力：
  - 标题优化（字符限制/核心词前置/品牌词策略）
  - 五点描述撰写（痛点-解决方案-证明材料）
  - 产品描述优化（A+内容结构）
  - 关键词植入（自然嵌入，避免关键词堆砌）
  - 图片ALT标签优化
  - 竞品Listing对比评分
  - 转化率预测
技能包：内容生成, 关键词研究, 数据分析
输入：产品信息、竞品ASIN列表
输出：完整Listing文档 + 优化建议报告
关键词触发：["Listing优化", "标题优化", "五点描述", "产品页面"]
优先级：P0（转化核心）
```

#### 💰 AMZ-03 利润优化Agent
```
职责：最大化每个SKU的净利润
核心能力：
  - 全成本建模（FBA费用/仓储费/退款率/广告ACOS）
  - TACOS（全链路广告成本）优化
  - 动态定价策略（日内调价/竞品调价响应）
  - 利润-排名平衡曲线分析
  - 促销策略优化（Coupon/Deal/LD/7DD）
  - 冗余库存成本计算与清仓建议
  - 利润多市场横向对比
技能包：ProfitOptimizer, 数据分析
输入：ASIN列表、财务目标（目标ACOS/目标利润率）
输出：利润优化报告 + 定价建议 + 促销日历
关键词触发：["利润优化", "ACOS", "TACOS", "定价策略", "成本分析"]
优先级：P0（核心商业指标）
```

#### 📢 AMZ-04 广告投放Agent
```
职责：全托管式广告运营（SP/SB/SD/OTT）
核心能力：
  - 关键词挖掘（海量词库+语义扩展）
  - 广告结构设计（自动广告→手动广告漏斗）
  - Bid智能调节（基于转化/基于ROAS/日内波动）
  - 预算分配优化（ Campaigns × Portfolios）
  - 否定关键词管理
  - 竞品ASIN定向策略
  - 广告报告解读与异常诊断
技能包：广告管理, 数据分析, 关键词研究
输入：ASIN、预算、广告目标
输出：广告运营报告 + 下周期调整建议
关键词触发：["广告投放", "SP广告", "SB广告", "ACOS", "广告优化"]
优先级：P0（流量引擎）
```

#### 📦 AMZ-05 库存管理Agent
```
职责：确保库存充足且无积压
核心能力：
  - 补货时间计算（Lead Time × 销售速度 × 安全库存）
  - 断货风险预警（前置期波动/促销放量）
  - 冗余库存识别与清仓建议
  - FBA容量规划（季度容量预测）
  - 多ASIN库存分配优化
  - 物流模式选择（海运/空运/快递经济性对比）
  - 季度性备货规划
技能包：库存管理, 数据分析
输入：ASIN列表、在途库存、日销售数据
输出：补货计划表 + 库存预警报告
关键词触发：["库存管理", "补货", "FBA库存", "库存预警"]
优先级：P1（运营保障）
```

#### ⭐ AMZ-06 评价分析Agent
```
职责：监控分析竞品和自己产品的评价
核心能力：
  - 全网评价数据采集（亚马逊/独立站/社交媒体）
  - 评分趋势监控（周环比/异常波动告警）
  - 评价情感分析（Positive/Negative/Neutral + 细粒度主题）
  - 竞品弱点挖掘（差评高频词 → 产品改进机会）
  - 好评模式识别（用于激励计划设计）
  - 催评策略优化（时间/文案/A+B测试）
  - QA问题分析（常见问题 → 运营改进）
技能包：数据分析, 自然语言处理, search_web
输入：ASIN列表、监控频率设置
输出：评价分析周报 + 运营行动建议
关键词触发：["评价分析", "差评监控", "好评优化", "review", "QA分析"]
优先级：P1
```

#### 👁️ AMZ-07 竞品监控Agent
```
职责：实时监控竞品动态，快速响应市场变化
核心能力：
  - 竞品价格实时追踪（价格战告警）
  - 竞品Listing变更检测（标题/图片/五点/价格）
  - 竞品库存状态监控
  - 竞品广告策略分析（关键词/出价/广告格式）
  - 竞品促销日历追踪
  - 新竞品发现（市场新入局者预警）
  - 竞品市场份额变化
技能包：竞品监控, search_web, 数据分析
输入：竞品ASIN列表、监控维度设置
输出：竞品动态日报 + 响应策略建议
关键词触发：["竞品监控", "价格监控", "市场情报", "竞争对手动态"]
优先级：P1
```

#### 💵 AMZ-08 定价策略Agent
```
职责：智能定价，维持竞争力与利润的动态平衡
核心能力：
  - 竞品价格带分析（价格锚定策略）
  - 动态定价规则引擎（基于库存/排名/竞品/利润）
  - Buy Box监控与获取策略
  - 促销活动价格测算（折扣力度 vs 转化率）
  - 跟卖监控与应对
  - 新品期/成长期/成熟期差异化定价
  - 心理定价策略（9.99/19.99等）
技能包：定价策略, 数据分析, 利润优化
输入：ASIN、成本结构、竞争环境
输出：定价策略报告 + 自动调价规则配置
关键词触发：["定价策略", "动态定价", "价格战", "Buy Box"]
优先级：P1
```

#### 🔑 AMZ-09 关键词Agent
```
职责：发现、管理和优化所有广告与Listing关键词
核心能力：
  - 关键词词库构建（百万级）
  - 搜索量/竞争度/转化率三维评估
  - 否定关键词智能推荐
  - 长尾关键词挖掘
  - 关键词趋势追踪（新兴词/衰退词）
  - ASIN关键词反查（竞品流量词）
  - 关键词分类体系维护（品牌词/类目词/竞品词/长尾词）
技能包：关键词研究, 数据分析
输入：ASIN/产品类别/种子关键词
输出：关键词矩阵 + 优先级排序 + 投放建议
关键词触发：["关键词", "keyword", "长尾词", "搜索词", "否定词"]
优先级：P1（基础设施）
```

#### 📊 AMZ-10 报表分析Agent
```
职责：自动生成各类业务报表，支持决策
核心能力：
  - 日/周/月/季报表自动生成
  - 核心KPI追踪（GMV/ACOS/FBA库存/BSR/评分）
  - 同比/环比趋势分析
  - 异常点标注与归因分析
  - 多维度下钻（类目/品牌/店铺/区域/时间段）
  - 自定义报表配置
  - 可视化图表生成（折线/柱状/热力/漏斗）
  - 报表推送（邮件/飞书/Slack）
技能包：报表生成, 数据分析
输入：报表类型、时间范围、筛选条件
输出：结构化报表文件（Excel/PDF/HTML）
关键词触发：["报表", "数据分析", "KPI", "周报", "月报", "业绩分析"]
优先级：P2（管理支撑）
```

---

### 2.3 支撑域（10个）— 平台基础设施与协作底座

#### 🔌 SUP-01 数据采集Agent
```
职责：统一数据采集入口，支持所有Agent的数据需求
核心能力：
  - 多源数据采集（平台API/网页爬虫/文件导入/数据库）
  - 数据清洗与标准化
  - 数据质量校验（完整性/一致性/时效性）
  - 增量/全量采集配置
  - 数据管道监控与告警
  - 数据源健康检查
技术栈：httpx, BeautifulSoup, pandas, schedule
输入：数据源配置、数据需求描述
输出：结构化数据集（JSON/CSV/Pandas DataFrame）
关键词触发：["数据采集", "爬虫", "数据清洗", "数据导入"]
优先级：P0（基础设施）
```

#### ✒️ SUP-02 内容生成Agent
```
职责：批量生成高质量营销和运营内容
核心能力：
  - 多格式内容生成（产品描述/博客文章/社媒帖子/邮件/视频脚本）
  - 品牌语调统一（Voice & Tone配置）
  - 内容模板管理（可复用结构）
  - 批量内容生成（一次性处理100+条）
  - A/B内容变体生成
  - 内容质量评分（可读性/关键词密度/E-E-A-T）
  - 多语言内容生成（支持20+语言）
技能包：内容生成, 翻译
输入：内容需求、产品信息、品牌指南
输出：批量内容文件 + 质量评分
关键词触发：["内容生成", "批量文案", "产品描述", "脚本生成"]
优先级：P0（内容工厂）
```

#### 🌐 SUP-03 翻译Agent
```
职责：提供专业级多语言翻译（不只是翻译，是本地化）
核心能力：
  - 20+语言专业翻译（中英日韩德法西意葡俄阿等）
  - 行业术语库（电商/科技/医疗/金融）
  - 文化适配（节日/俗语/禁忌）
  - 翻译质量自评（BLEU辅助，人工审核标记）
  - 翻译记忆库（TM）复用
  - 批量翻译任务队列
  - 紧急翻译通道（24小时加急）
技能包：翻译, 本地化
输入：待翻译内容、目标语言、行业领域
输出：翻译后内容 + 质量评估
关键词触发：["翻译", "本地化", "中英翻译", "多语言"]
优先级：P1
```

#### ✅ SUP-04 合规检查Agent
```
职责：确保所有运营行为符合平台政策和法规
核心能力：
  - 亚马逊政策检查（禁售商品/受限商品/知识产权）
  - 广告合规审核（FDA/FTD/极端词汇/竞品提及）
  - GDPR合规检查（数据收集/用户同意/删除权）
  - 内容合规扫描（版权/商标/虚假宣传）
  - 欧盟/美国/中国法规适配
  - 合规风险评级（Green/Yellow/Red）
  - 合规报告生成（审计追踪）
技能包：合规检查, 数据分析
输入：待检查内容/行为、目标市场/平台
输出：合规检查报告 + 风险评级
关键词触发：["合规检查", "政策合规", "风险审核", "GDPR"]
优先级：P0（风控保障）
```

#### 📑 SUP-05 报告生成Agent
```
职责：自动生成专业级业务报告
核心能力：
  - 多格式报告（Markdown/PDF/HTML/PPTX）
  - 多种报告模板（日报/周报/月报/季报/年报/专项报告）
  - 数据自动填充（对接所有数据源）
  - 图表可视化集成（ECharts）
  - 报告分发（邮件/飞书/Slack/微信）
  - 报告版本管理（历史版本对比）
  - 自定义报告配置（拖拽式）
技能包：报告生成, 数据分析, docx
输入：报告模板/类型、时间范围、受众
输出：完整报告文件
关键词触发：["报告生成", "报表制作", "数据分析报告", "PPT"]
优先级：P1
```

#### 💬 SUP-06 客户服务Agent
```
职责：处理客户问询，提供智能客服支持
核心能力：
  - 意图识别与分类（退款/物流/产品/投诉/咨询）
  - FAQ自动回复（基于知识库）
  - 情感分析（识别紧急投诉）
  - 多轮对话管理
  - 好评邀请触发（时机判断）
  - 差评预警与升级机制
  - 客服工单生成与跟踪
  - 客服数据统计与分析
技能包：对话系统, 知识库
输入：客户问询文本、历史记录
输出：回复建议/工单/升级建议
关键词触发：["客服", "客户问询", "自动回复", "FAQ"]
优先级：P2
```

#### 🎯 SUP-07 质量评分Agent
```
职责：为所有Agent产出提供统一的质量评估
核心能力：
  - 多维度质量评分（准确性/完整性/可操作性/时效性）
  - 质量基线管理（各Agent类型基准分）
  - 质量趋势追踪
  - 质量异常告警
  - 人工抽检机制（随机抽样+人工评估）
  - 质量改进建议
  - Agent能力画像（各Agent的强项/弱项）
技能包：质量评分, 数据分析
输入：Agent输出内容、任务类型
输出：质量评分报告 + 改进建议
关键词触发：["质量评分", "效果评估", "质量监控"]
优先级：P1（质量保障层）
```

#### 🧠 SUP-08 记忆管理Agent
```
职责：统一管理集群的长期记忆和知识
核心能力：
  - 跨Agent记忆共享（Shared Memory Space）
  - 记忆层级管理（L1工作记忆/L2会话记忆/L3长期记忆）
  - 记忆检索（RAG语义搜索）
  - 记忆去重与合并
  - 过期记忆处理（自动归档/删除）
  - 上下文窗口优化（关键信息摘要）
  - Agent学习经验积累
技能包：RAG, 记忆管理
输入：当前上下文、记忆查询
输出：相关记忆片段 + 更新建议
关键词触发：["记忆管理", "知识库", "上下文", "长期记忆"]
优先级：P1（认知基础设施）
```

#### ⚙️ SUP-09 调度协调Agent
```
职责：智能调度所有Agent任务，优化执行效率
核心能力：
  - 任务优先级队列管理
  - 任务依赖图解析（DAG）
  - 并行任务优化（最大化并发度）
  - 负载均衡（Agent能力匹配）
  - 资源配额管理（Token/调用次数/时间）
  - 任务超时与降级策略
  - 任务重试与回退机制
  - 调度策略可视化
技能包：调度协调, 工作流引擎
输入：任务列表、约束条件（截止时间/优先级）
输出：执行计划 + 调度日志
关键词触发：["任务调度", "并行执行", "工作流", "协调"]
优先级：P0（执行引擎核心）
```

#### 🔒 SUP-10 安全审计Agent
```
职责：保障整个集群的安全运行
核心能力：
  - API密钥安全管理（轮换/吊销/告警）
  - 权限矩阵维护（RBAC × Agent）
  - 操作日志审计（可溯源/不可篡改）
  - 敏感信息检测（PII/信用卡/API Key）
  - 异常行为检测（频率/范围/时间异常）
  - SOC 2合规报告生成
  - MCP协议安全扫描（43%的MCP服务器存在漏洞）
  - 安全事件响应（自动隔离+告警）
技能包：安全审计, PII检测
输入：审计范围（全部/指定Agent/指定时间）
输出：安全审计报告 + 风险建议
关键词触发：["安全审计", "权限管理", "日志审计", "合规报告"]
优先级：P0（安全底线）
```

---

## 三、协作机制设计

### 3.1 幕僚长调度流程（扩展版）

```
用户请求
    ↓
意图识别（SUP-09 调度协调 + SUP-08 记忆管理）
    ↓
任务拆解（幕僚长LLM）
    ↓
┌─────────────────────────────────────────────────┐
│              三域并行启动（示例）                  │
│                                                   │
│  GEO域 → 市场研究(GEO-01) + 竞品分析(GEO-02)      │
│        → 内容策略(GEO-03) + 多语言(GEO-04)        │
│        → 平台适配(GEO-05) + 效果监测(GEO-06)     │
│                                                   │
│  亚马逊域 → 选品分析(AMZ-01) + Listing(AMZ-02)    │
│           → 利润优化(AMZ-03) + 广告(AMZ-04)      │
│           → 库存管理(AMZ-05) + 评价分析(AMZ-06)  │
│                                                   │
│  支撑域 → 数据采集(SUP-01) + 内容生成(SUP-02)     │
│         → 翻译(SUP-03) + 合规检查(SUP-04)        │
│         → 报告生成(SUP-05) + 质量评分(SUP-07)     │
│         → 记忆管理(SUP-08) + 安全审计(SUP-10)    │
└─────────────────────────────────────────────────┘
    ↓
结果聚合（幕僚长）
    ↓
报告生成(SUP-05)
    ↓
输出
```

### 3.2 Agent间P2P通信协议

```python
# Agent通信协议示例
class AgentMessage:
    def __init__(self):
        self.sender: str       # 发送方Agent ID
        self.receiver: str     # 接收方Agent ID (空=广播)
        self.msg_type: str     # REQUEST/RESPONSE/BROADCAST/EVENT
        self.content: dict     # 消息内容
        self.trace_id: str      # 全链路追踪ID
        self.span_id: str      # 当前操作ID
        self.parent_span_id: str # 父操作ID
        self.priority: int    # 优先级 1-5
        self.ttl: int          # 生存时间（秒）
        self.timestamp: str   # ISO格式时间戳

# 通信场景示例
场景1: AMZ-01选品分析 → AMZ-02 Listing优化（新品上架）
场景2: GEO-02竞品分析 → GEO-03内容策略（竞品差异化）
场景3: SUP-01数据采集 → 所有消费者（数据供给）
场景4: SUP-07质量评分 ← 所有生产者（质量监控）
场景5: SUP-10安全审计 ← 所有Agent（安全事件上报）
```

### 3.3 依赖关系矩阵

| 上游Agent | 下游Agent | 依赖类型 | 数据流向 |
|---------|---------|---------|---------|
| GEO-01 市场研究 | GEO-02/03, AMZ-01 | 强依赖 | 报告→策略 |
| GEO-02 竞品分析 | GEO-03, AMZ-07 | 强依赖 | 画像→策略 |
| GEO-03 内容策略 | GEO-04/05, SUP-02 | 强依赖 | 内容→多语言 |
| GEO-06 效果监测 | 所有GEO Agent | 反馈循环 | 数据→优化 |
| AMZ-01 选品 | AMZ-02/03/09 | 强依赖 | 选品→Listing |
| AMZ-03 利润优化 | AMZ-04/08 | 强依赖 | 利润→定价/广告 |
| AMZ-04 广告 | AMZ-09 | 中依赖 | 广告→关键词 |
| AMZ-05 库存 | AMZ-08 | 中依赖 | 库存→定价 |
| AMZ-06 评价 | AMZ-02 | 弱依赖 | 评价→Listing |
| SUP-01 数据采集 | 所有消费者 | 强依赖 | 数据→各Agent |
| SUP-07 质量评分 | 所有生产者 | 反馈 | 评分→改进 |
| SUP-10 安全审计 | 所有Agent | 监控 | 审计→合规 |

---

## 四、Agent注册表

### 4.1 完整注册表

```json
{
  "cluster_version": "3.0",
  "cluster_name": "M-A3 30-Agent集群",
  "chief_of_staff": {
    "id": "chief-of-staff",
    "name": "M-A3 幕僚长",
    "domain": "orchestration",
    "tier": 0,
    "engine": "claude-ma",
    "max_concurrent": 1
  },
  "agents": [
    /* ============ GEO域 ============ */
    {
      "id": "geo-01-market-research",
      "name": "市场研究Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["product", "regions"]},
      "output_schema": {"type": "object", "required": ["report", "opportunities"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["geo-02-competitor", "geo-03-content-strategy", "geo-10-regional"],
      "keywords": ["市场研究", "市场规模", "目标市场", "TAM", "市场机会"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "geo-02-competitor",
      "name": "竞品分析Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["competitors", "keywords"]},
      "output_schema": {"type": "object", "required": ["geo_profile", "gap_analysis"]},
      "dependencies": [],
      "upstream": ["chief-of-staff", "geo-01-market-research"],
      "downstream": ["geo-03-content-strategy"],
      "keywords": ["竞品分析", "竞争对手", "对标分析", "竞品策略"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 240
    },
    {
      "id": "geo-03-content-strategy",
      "name": "内容策略Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["keywords", "product_info"]},
      "output_schema": {"type": "object", "required": ["calendar", "topics"]},
      "dependencies": ["geo-01-market-research", "geo-02-competitor"],
      "upstream": ["chief-of-staff"],
      "downstream": ["geo-04-multilingual", "geo-05-platform-adapt", "sup-02-content-gen"],
      "keywords": ["内容策略", "内容规划", "选题", "内容日历"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "geo-04-multilingual",
      "name": "多语言优化Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "deepseek",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["content", "languages"]},
      "output_schema": {"type": "object", "required": ["localized_content", "hreflang"]},
      "dependencies": ["geo-03-content-strategy"],
      "upstream": ["geo-03-content-strategy"],
      "downstream": ["sup-02-content-gen", "sup-03-translation"],
      "keywords": ["多语言", "本地化", "翻译", "中译英", "国际化"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 180
    },
    {
      "id": "geo-05-platform-adapt",
      "name": "平台适配Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 4,
      "input_schema": {"type": "object", "required": ["content", "platforms"]},
      "output_schema": {"type": "object", "required": ["adapted_content", "configs"]},
      "dependencies": ["geo-03-content-strategy"],
      "upstream": ["geo-03-content-strategy"],
      "downstream": ["geo-06-monitoring"],
      "keywords": ["平台适配", "多平台", "SEO适配"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 180
    },
    {
      "id": "geo-06-monitoring",
      "name": "效果监测Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "local",
      "max_concurrent": 2,
      "input_schema": {"type": "object", "required": ["keywords", "date_range"]},
      "output_schema": {"type": "object", "required": ["metrics", "report"]},
      "dependencies": ["geo-05-platform-adapt"],
      "upstream": ["geo-05-platform-adapt", "geo-03-content-strategy"],
      "downstream": ["geo-02-competitor", "geo-03-content-strategy"],
      "keywords": ["效果监测", "排名追踪", "AI搜索", "GEO效果"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 300
    },
    {
      "id": "geo-07-knowledge-graph",
      "name": "知识图谱Agent",
      "domain": "geo",
      "tier": 1,
      "engine": "claude-ma",
      "max_concurrent": 2,
      "input_schema": {"type": "object", "required": ["brand_info", "products"]},
      "output_schema": {"type": "object", "required": ["knowledge_graph", "jsonld"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["geo-09-schema", "geo-03-content-strategy"],
      "keywords": ["知识图谱", "Schema", "实体识别", "结构化数据"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 600
    },
    {
      "id": "geo-08-intent-prediction",
      "name": "意图预测Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["category", "keywords"]},
      "output_schema": {"type": "object", "required": ["intent_matrix", "recommendations"]},
      "dependencies": [],
      "upstream": ["chief-of-staff", "geo-01-market-research"],
      "downstream": ["geo-03-content-strategy", "amz-01-product-select"],
      "keywords": ["意图预测", "搜索意图", "用户意图"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 240
    },
    {
      "id": "geo-09-schema",
      "name": "Schema优化Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "local",
      "max_concurrent": 4,
      "input_schema": {"type": "object", "required": ["urls"]},
      "output_schema": {"type": "object", "required": ["audit_report", "jsonld_snippets"]},
      "dependencies": ["geo-07-knowledge-graph"],
      "upstream": ["geo-07-knowledge-graph"],
      "downstream": [],
      "keywords": ["Schema优化", "结构化数据", "Rich Results"],
      "priority": "P2",
      "skippable": true,
      "timeout_seconds": 300
    },
    {
      "id": "geo-10-regional",
      "name": "地域策略Agent",
      "domain": "geo",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["brand", "regions"]},
      "output_schema": {"type": "object", "required": ["regional_strategies"]},
      "dependencies": ["geo-01-market-research"],
      "upstream": ["geo-01-market-research"],
      "downstream": ["geo-03-content-strategy"],
      "keywords": ["地域策略", "本地SEO", "ccTLD"],
      "priority": "P2",
      "skippable": true,
      "timeout_seconds": 240
    },

    /* ============ 亚马逊域 ============ */
    {
      "id": "amz-01-product-select",
      "name": "选品分析Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["category", "budget"]},
      "output_schema": {"type": "object", "required": ["top_products", "risk_ratings"]},
      "dependencies": [],
      "upstream": ["chief-of-staff", "geo-01-market-research"],
      "downstream": ["amz-02-listing", "amz-03-profit", "amz-09-keywords"],
      "keywords": ["选品", "新品开发", "产品机会"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "amz-02-listing",
      "name": "Listing优化Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["product_info", "competitor_asins"]},
      "output_schema": {"type": "object", "required": ["title", "bullets", "description", "score"]},
      "dependencies": ["amz-01-product-select"],
      "upstream": ["amz-01-product-select"],
      "downstream": ["amz-04-ads", "sup-04-compliance"],
      "keywords": ["Listing优化", "标题优化", "五点描述", "产品页面"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "amz-03-profit",
      "name": "利润优化Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["asins", "cost_structure"]},
      "output_schema": {"type": "object", "required": ["profit_report", "pricing_suggestions"]},
      "dependencies": ["amz-01-product-select"],
      "upstream": ["amz-01-product-select"],
      "downstream": ["amz-04-ads", "amz-08-pricing"],
      "keywords": ["利润优化", "ACOS", "TACOS", "成本分析"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "amz-04-ads",
      "name": "广告投放Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 4,
      "input_schema": {"type": "object", "required": ["asin", "budget", "target_acos"]},
      "output_schema": {"type": "object", "required": ["campaign_structure", "keyword_bids"]},
      "dependencies": ["amz-02-listing", "amz-03-profit"],
      "upstream": ["amz-02-listing", "amz-03-profit"],
      "downstream": ["amz-09-keywords"],
      "keywords": ["广告投放", "SP广告", "SB广告", "ACOS优化"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "amz-05-inventory",
      "name": "库存管理Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "local",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["asins", "inventory_data"]},
      "output_schema": {"type": "object", "required": ["replenishment_plan", "alerts"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["amz-08-pricing"],
      "keywords": ["库存管理", "补货", "FBA库存"],
      "priority": "P1",
      "skippable": false,
      "timeout_seconds": 180
    },
    {
      "id": "amz-06-review",
      "name": "评价分析Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 4,
      "input_schema": {"type": "object", "required": ["asins"]},
      "output_schema": {"type": "object", "required": ["review_report", "action_items"]},
      "dependencies": [],
      "upstream": ["chief-of-staff", "amz-02-listing"],
      "downstream": ["amz-02-listing", "amz-06-review"],
      "keywords": ["评价分析", "review", "QA分析", "差评监控"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 240
    },
    {
      "id": "amz-07-competitor-monitor",
      "name": "竞品监控Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "local",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["competitor_asins"]},
      "output_schema": {"type": "object", "required": ["daily_report", "alerts"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["amz-08-pricing", "amz-04-ads"],
      "keywords": ["竞品监控", "价格战", "市场情报"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 300
    },
    {
      "id": "amz-08-pricing",
      "name": "定价策略Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["asin", "cost", "competition"]},
      "output_schema": {"type": "object", "required": ["pricing_strategy", "rules"]},
      "dependencies": ["amz-03-profit", "amz-05-inventory", "amz-07-competitor-monitor"],
      "upstream": ["amz-03-profit", "amz-05-inventory", "amz-07-competitor-monitor"],
      "downstream": [],
      "keywords": ["定价策略", "动态定价", "Buy Box"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 240
    },
    {
      "id": "amz-09-keywords",
      "name": "关键词Agent",
      "domain": "amazon",
      "tier": 1,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["asin", "seed_keywords"]},
      "output_schema": {"type": "object", "required": ["keyword_matrix", "priorities"]},
      "dependencies": ["amz-01-product-select"],
      "upstream": ["amz-01-product-select", "amz-04-ads"],
      "downstream": ["amz-02-listing", "amz-04-ads"],
      "keywords": ["关键词", "keyword", "长尾词", "否定词"],
      "priority": "P1",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "amz-10-reporting",
      "name": "报表分析Agent",
      "domain": "amazon",
      "tier": 2,
      "engine": "local",
      "max_concurrent": 2,
      "input_schema": {"type": "object", "required": ["report_type", "date_range"]},
      "output_schema": {"type": "object", "required": ["report_file", "summary"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": [],
      "keywords": ["报表", "KPI", "周报", "月报", "数据分析"],
      "priority": "P2",
      "skippable": true,
      "timeout_seconds": 180
    },

    /* ============ 支撑域 ============ */
    {
      "id": "sup-01-data-collect",
      "name": "数据采集Agent",
      "domain": "support",
      "tier": 1,
      "engine": "local",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["sources", "data_requirements"]},
      "output_schema": {"type": "object", "required": ["dataset", "quality_report"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["geo-01-market-research", "amz-01-product-select", "sup-07-quality"],
      "keywords": ["数据采集", "爬虫", "数据清洗"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 600
    },
    {
      "id": "sup-02-content-gen",
      "name": "内容生成Agent",
      "domain": "support",
      "tier": 1,
      "engine": "claude-ma",
      "max_concurrent": 8,
      "input_schema": {"type": "object", "required": ["content_type", "product_info"]},
      "output_schema": {"type": "object", "required": ["generated_content", "quality_score"]},
      "dependencies": ["geo-03-content-strategy"],
      "upstream": ["geo-03-content-strategy"],
      "downstream": ["sup-04-compliance", "sup-07-quality"],
      "keywords": ["内容生成", "批量文案", "脚本生成"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "sup-03-translation",
      "name": "翻译Agent",
      "domain": "support",
      "tier": 1,
      "engine": "deepseek",
      "max_concurrent": 10,
      "input_schema": {"type": "object", "required": ["text", "target_language", "industry"]},
      "output_schema": {"type": "object", "required": ["translated_text", "quality_score"]},
      "dependencies": [],
      "upstream": ["geo-04-multilingual", "amz-02-listing"],
      "downstream": ["sup-07-quality"],
      "keywords": ["翻译", "中英翻译", "本地化"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 120
    },
    {
      "id": "sup-04-compliance",
      "name": "合规检查Agent",
      "domain": "support",
      "tier": 1,
      "engine": "deepseek",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["content", "platform", "market"]},
      "output_schema": {"type": "object", "required": ["compliance_report", "risk_rating"]},
      "dependencies": [],
      "upstream": ["amz-02-listing", "sup-02-content-gen"],
      "downstream": ["sup-07-quality"],
      "keywords": ["合规检查", "政策合规", "风险审核"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 180
    },
    {
      "id": "sup-05-report-gen",
      "name": "报告生成Agent",
      "domain": "support",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 3,
      "input_schema": {"type": "object", "required": ["report_type", "data"]},
      "output_schema": {"type": "object", "required": ["report_file", "summary"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": [],
      "keywords": ["报告生成", "PPT", "数据分析报告"],
      "priority": "P1",
      "skippable": false,
      "timeout_seconds": 300
    },
    {
      "id": "sup-06-customer-service",
      "name": "客户服务Agent",
      "domain": "support",
      "tier": 2,
      "engine": "claude-ma",
      "max_concurrent": 10,
      "input_schema": {"type": "object", "required": ["query", "history"]},
      "output_schema": {"type": "object", "required": ["response", "action"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["sup-07-quality"],
      "keywords": ["客服", "自动回复", "FAQ"],
      "priority": "P2",
      "skippable": true,
      "timeout_seconds": 60
    },
    {
      "id": "sup-07-quality",
      "name": "质量评分Agent",
      "domain": "support",
      "tier": 1,
      "engine": "claude-ma",
      "max_concurrent": 5,
      "input_schema": {"type": "object", "required": ["output", "task_type"]},
      "output_schema": {"type": "object", "required": ["quality_score", "improvements"]},
      "dependencies": [],
      "upstream": ["sup-01-data-collect", "sup-02-content-gen", "sup-03-translation", "sup-06-customer-service"],
      "downstream": ["chief-of-staff"],
      "keywords": ["质量评分", "效果评估"],
      "priority": "P1",
      "skippable": true,
      "timeout_seconds": 120
    },
    {
      "id": "sup-08-memory",
      "name": "记忆管理Agent",
      "domain": "support",
      "tier": 1,
      "engine": "local",
      "max_concurrent": 20,
      "input_schema": {"type": "object", "required": ["context", "operation"]},
      "output_schema": {"type": "object", "required": ["memories", "updated_context"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["chief-of-staff"],
      "keywords": ["记忆管理", "知识库", "上下文"],
      "priority": "P1",
      "skippable": false,
      "timeout_seconds": 60
    },
    {
      "id": "sup-09-scheduler",
      "name": "调度协调Agent",
      "domain": "support",
      "tier": 0,
      "engine": "local",
      "max_concurrent": 1,
      "input_schema": {"type": "object", "required": ["tasks", "constraints"]},
      "output_schema": {"type": "object", "required": ["execution_plan", "schedule_log"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["chief-of-staff"],
      "keywords": ["任务调度", "并行执行", "工作流"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 120
    },
    {
      "id": "sup-10-security",
      "name": "安全审计Agent",
      "domain": "support",
      "tier": 0,
      "engine": "local",
      "max_concurrent": 2,
      "input_schema": {"type": "object", "required": ["scope", "agents"]},
      "output_schema": {"type": "object", "required": ["audit_report", "risk_items"]},
      "dependencies": [],
      "upstream": ["chief-of-staff"],
      "downstream": ["chief-of-staff"],
      "keywords": ["安全审计", "权限管理", "日志审计"],
      "priority": "P0",
      "skippable": false,
      "timeout_seconds": 300
    }
  ],

  "domain_summary": {
    "geo": {"count": 10, "p0": 4, "p1": 4, "p2": 2},
    "amazon": {"count": 10, "p0": 4, "p1": 5, "p2": 1},
    "support": {"count": 10, "p0": 5, "p1": 4, "p2": 1}
  },

  "engine_distribution": {
    "claude-ma": 18,
    "local": 8,
    "deepseek": 4
  }
}
```

---

## 五、资源管理与扩展策略

### 5.1 Agent池配置

```yaml
# agent-pool-config.yaml
agent_pool:
  max_total_agents: 30
  max_concurrent_tasks: 50
  idle_timeout_seconds: 300
  
  domains:
    geo:
      agents: 10
      max_concurrent_per_agent: 5
      shared_context_size_mb: 512
      
    amazon:
      agents: 10
      max_concurrent_per_agent: 5
      shared_context_size_mb: 512
      
    support:
      agents: 10
      max_concurrent_per_agent: 10
      shared_context_size_mb: 256

  engines:
    claude-ma:
      max_instances: 18
      token_limit: 200000
      fallback: "local"
      
    local:
      max_instances: 8
      token_limit: 32000
      fallback: "deepseek"
      
    deepseek:
      max_instances: 4
      token_limit: 64000
      fallback: "local"

  rate_limits:
    per_agent_per_minute: 60
    per_domain_per_minute: 200
    cluster_wide_per_minute: 500
```

### 5.2 负载均衡策略

```
┌─────────────────────────────────────────────┐
│           幕僚长请求分发算法                    │
├─────────────────────────────────────────────┤
│  1. 意图分类 → 功能域（geo/amazon/support）   │
│  2. 功能域内 → 关键词匹配 → Agent ID          │
│  3. Agent选择 → 负载均衡（Least Connections） │
│  4. 依赖检查 → DAG排序 → 并行组              │
│  5. 资源预检 → 容量检查 → 执行/排队/拒绝      │
└─────────────────────────────────────────────┘

负载均衡算法：加权最少连接（Weighted Least Connections）
- 权重 = Agent最大并发数
- 活跃连接数 = 当前任务数
- 选择：权重 - 活跃连接数 最大的Agent
```

### 5.3 降级策略

| 触发条件 | 降级动作 |
|---------|---------|
| Engine不可用 | 切换备用引擎（Claude→Local→DeepSeek） |
| Agent过载 | 任务进入优先级队列，等待释放 |
| Token超限 | 压缩上下文，保留关键记忆 |
| 网络故障 | 缓存结果，降级为只读模式 |
| 安全事件 | 隔离受影响Agent，启动审计 |

---

## 六、质量保障体系

### 6.1 质量评分维度

```python
QUALITY_DIMENSIONS = {
    "accuracy":      {"weight": 0.30, "desc": "信息准确性"},
    "completeness":  {"weight": 0.25, "desc": "任务完成度"},
    "actionability": {"weight": 0.20, "desc": "建议可执行性"},
    "timeliness":    {"weight": 0.15, "desc": "时效性"},
    "clarity":       {"weight": 0.10, "desc": "表达清晰度"},
}

# 评分等级
EXCELLENT = (90, 100)  # 无需审查
GOOD      = (75, 89)   # 可选审查
FAIR      = (60, 74)   # 建议审查
POOR      = (0, 59)    # 必须审查
```

### 6.2 全链路追踪

```
Trace-ID: geo-20260414-001
├─ span: chief-of-staff.intent-recognition (50ms)
├─ span: sup-09-scheduler.task-decomposition (120ms)
└─ span: parallel-execution-group
   ├─ [并行] geo-01-market-research (280s) ✓
   ├─ [并行] geo-02-competitor-analysis (195s) ✓
   ├─ [并行] amz-01-product-select (310s) ✓
   ├─ [并行] sup-01-data-collection (180s) ✓
   └─ [串行] geo-03-content-strategy (等待geo-01/02完成)
       ├─ [并行] geo-04-multilingual
       └─ [并行] geo-05-platform-adapt
```

---

## 七、竞争优势分析

### 7.1 竞品对比

| 维度 | 普通竞品 | 本方案 |
|------|---------|--------|
| Agent数量 | 3-8个 | **30个** |
| 功能域 | 单一域 | **三域全覆盖** |
| 协作深度 | 串行为主 | **并行+串行混合** |
| 商业闭环 | 部分 | **全链路（GEO→Amazon→运营）** |
| 自进化能力 | 无 | **记忆+学习+改进** |
| 质量保障 | 无 | **SUP-07质量评分** |
| 安全体系 | 基础 | **SUP-10安全审计+MCP安全扫描** |

### 7.2 核心差异化壁垒

1. **规模壁垒**：30个垂直Agent覆盖全链路，竞品难以快速复制
2. **数据壁垒**：跨域数据流动（Geo-Amazon数据互通）形成网络效应
3. **自进化壁垒**：记忆管理Agent持续积累行业知识，时间越久越强
4. **质量壁垒**：SUP-07质量评分体系确保每项输出可量化、可改进
5. **安全壁垒**：SUP-10安全审计主动防护MCP协议漏洞（43%市场风险）

---

*本方案由 M-A3 幕僚长 设计，版本 v1.0*
*生成时间：2026-04-14*


path: 30-expansion/IMPLEMENTATION_PLAN.md
content: # M-A3 30-Agent集群 分阶段实施计划
> 版本：v1.0 | 日期：2026-04-14 | 作者：M-A3 幕僚长

---

## 一、实施策略

### 1.1 核心原则

| 原则 | 说明 |
|------|------|
| **先基础设施后业务** | Tier 0/1 Agent（调度/安全/记忆/数据）必须优先完成 |
| **先核心后扩展** | P0 Agent优先，P1次之，P2最后 |
| **并行开发** | 各域可同时开发，互不阻塞 |
| **可测试交付** | 每个Agent交付前必须通过质量基准测试 |
| **平滑灰度** | 新Agent逐步引入，不影响现有业务流程 |

### 1.2 阶段总览

```
Week 1-2   Phase 0: 基础设施层（10个Agent）
Week 3-4   Phase 1: GEO域 + 亚马逊域核心（10个Agent）
Week 5-6   Phase 2: GEO域 + 亚马逊域扩展（10个Agent）
Week 7-8   Phase 3: 全链路集成 + 压力测试
Week 9+    Phase 4: 持续优化 + 自进化增强
```

---

## 二、详细实施计划

### 📦 Phase 0：基础设施层（第1-2周）

**目标**：建立集群底座，确保后续Agent可靠运行

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | sup-09-scheduler | 调度协调Agent | P0 | 3天 | task_scheduler.py + DAG引擎 | 10个任务并行调度测试通过 |
| 2 | sup-10-security | 安全审计Agent | P0 | 3天 | security_audit.py + RBAC矩阵 | PII检测测试10/10通过 |
| 3 | sup-01-data-collect | 数据采集Agent | P0 | 3天 | data_collector.py + 适配器 | 3个数据源接入测试通过 |
| 4 | sup-08-memory | 记忆管理Agent | P1 | 2天 | memory_manager.py + RAG | 记忆检索准确率>85% |
| 5 | sup-02-content-gen | 内容生成Agent | P0 | 3天 | content_generator.py + 模板 | 批量生成质量评分>75分 |
| 6 | sup-04-compliance | 合规检查Agent | P0 | 2天 | compliance_checker.py | 10条合规规则测试通过 |
| 7 | sup-03-translation | 翻译Agent | P1 | 2天 | translator.py + 术语库 | 中英翻译质量评分>80 |
| 8 | sup-07-quality | 质量评分Agent | P1 | 2天 | quality_scorer.py | 与人工评分相关性>0.85 |
| 9 | geo-07-knowledge-graph | 知识图谱Agent | P0 | 3天 | knowledge_graph.py + JSON-LD | 实体识别准确率>90% |
| 10 | amz-09-keywords | 关键词Agent | P1 | 2天 | keyword_agent.py + 词库 | 关键词覆盖率>竞品1.5倍 |

**Phase 0 关键技术决策**：
```
✅ 调度引擎：基于Weighted Least Connections算法
✅ 安全架构：RBAC × Agent × 操作类型
✅ 数据管道：适配器模式，支持API/爬虫/文件
✅ 记忆系统：SQLite FTS5 + RAG语义检索
```

**Phase 0 风险评估**：
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 调度引擎并发死锁 | 中 | 高 | Phase 0第1个交付，深度测试 |
| 安全Agent误报阻塞正常请求 | 低 | 高 | 灰度10%流量，逐步放量 |
| 数据采集被反爬 | 中 | 中 | 多IP池 + 请求间隔 |

---

### 📊 Phase 1：核心业务Agent（第3-4周）

**目标**：交付GEO域和亚马逊域的核心P0 Agent，形成业务闭环

#### GEO域核心（5个）

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | geo-01-market-research | 市场研究Agent | P0 | 3天 | market_researcher.py + 报告模板 | TAM/SAM/SOM三层模型输出正确 |
| 2 | geo-03-content-strategy | 内容策略Agent | P0 | 3天 | content_strategist.py + 日历生成器 | 季度内容日历覆盖>200个话题 |
| 3 | geo-08-intent-prediction | 意图预测Agent | P1 | 2天 | intent_predictor.py | 意图分类准确率>85%（对标94.3%目标） |
| 4 | geo-02-competitor | 竞品分析Agent | P1 | 2天 | competitor_analyzer.py | GEO三维度评分可输出 |
| 5 | geo-06-monitoring | 效果监测Agent | P1 | 2天 | geo_monitor.py + 告警引擎 | AI搜索引用率追踪可用 |

#### 亚马逊域核心（5个）

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | amz-01-product-select | 选品分析Agent | P0 | 3天 | product_selector.py + 利润模型 | 选品报告覆盖Top10候选 |
| 2 | amz-02-listing | Listing优化Agent | P0 | 3天 | listing_optimizer.py | Listing评分>85分 |
| 3 | amz-03-profit | 利润优化Agent | P0 | 3天 | profit_optimizer.py + 决策树 | 预测准确率>80% |
| 4 | amz-04-ads | 广告投放Agent | P0 | 3天 | ads_manager.py + 竞价引擎 | ACOS优化建议可执行 |
| 5 | amz-05-inventory | 库存管理Agent | P1 | 2天 | inventory_manager.py | 补货计划表生成正确 |

**Phase 1 关键技术决策**：
```
✅ GEO意图预测：引入参考PureblueAI的意图分类模型
✅ 利润优化：使用ProfitOptimizer决策树算法
✅ 广告投放：基于TACOS导向的Bid调节算法
```

**Phase 1 业务闭环验证**：
```
用户输入：某消费电子新品 → 
GEO域：市场研究 → 竞品分析 → 内容策略 → 效果监测
亚马逊域：选品分析 → Listing优化 → 利润优化 → 广告投放
覆盖：产品上市前全链路
```

---

### 🚀 Phase 2：扩展Agent（第5-6周）

**目标**：交付所有剩余Agent，达到30个Agent完整覆盖

#### GEO域扩展（5个）

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | geo-04-multilingual | 多语言优化Agent | P1 | 2天 | multilingual_optimizer.py | 5个语种本地化完成 |
| 2 | geo-05-platform-adapt | 平台适配Agent | P1 | 2天 | platform_adapter.py | 知乎/CSDN/LinkedIn适配 |
| 3 | geo-09-schema | Schema优化Agent | P2 | 2天 | schema_optimizer.py | 全站Schema覆盖率>95% |
| 4 | geo-10-regional | 地域策略Agent | P2 | 2天 | regional_strategist.py | 4个区域差异化策略 |
| 5 | (整合Phase1) | - | - | - | GEO域工具链完善 | 全链路集成测试通过 |

#### 亚马逊域扩展（5个）

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | amz-06-review | 评价分析Agent | P1 | 2天 | review_analyzer.py + 情感分析 | 情感分析准确率>80% |
| 2 | amz-07-competitor-monitor | 竞品监控Agent | P1 | 2天 | competitor_monitor.py | 5个ASIN监控可用 |
| 3 | amz-08-pricing | 定价策略Agent | P1 | 2天 | pricing_strategist.py | 动态定价规则可配置 |
| 4 | amz-10-reporting | 报表分析Agent | P2 | 2天 | reporting_agent.py | 日/周/月报自动生成 |
| 5 | (整合Phase1) | - | - | - | 亚马逊域工具链完善 | 全链路集成测试通过 |

#### 支撑域扩展（2个）

| # | Agent ID | Agent名称 | 优先级 | 预估工时 | 交付物 | 验收标准 |
|---|---------|---------|--------|---------|--------|---------|
| 1 | sup-05-report-gen | 报告生成Agent | P1 | 2天 | report_generator.py + PPT模板 | Markdown/PDF/HTML/PPT四格式 |
| 2 | sup-06-customer-service | 客户服务Agent | P2 | 2天 | customer_service.py + 对话引擎 | FAQ自动回复准确率>85% |

**Phase 2 关键技术决策**：
```
✅ 多语言优化：文化适配引擎（非纯翻译）
✅ 竞品监控：实时爬虫 + 价格告警阈值
✅ 报告生成：ECharts可视化集成
```

---

### 🔧 Phase 3：全链路集成 + 压力测试（第7-8周）

**目标**：验证30个Agent的协同工作能力，确保生产级稳定性

#### 3.1 集成测试

| 测试场景 | 描述 | 预期结果 | 优先级 |
|---------|------|---------|--------|
| **GEO全链路** | 市场研究→竞品分析→内容策略→多语言→平台适配→效果监测 | 完整报告生成 | P0 |
| **亚马逊全链路** | 选品→Listing→利润→广告→库存→定价→报表 | 完整运营方案 | P0 |
| **跨域协作** | GEO市场研究 → 亚马逊选品（数据互通） | 选品报告包含GEO数据 | P0 |
| **P2P通信** | 10组跨Agent消息传递 | 消息可靠到达 | P0 |
| **降级测试** | Claude MA不可用 → Local → DeepSeek | 降级不影响核心功能 | P1 |
| **并发压测** | 50个并发请求，30个Agent | 无死锁，响应时间P95<5s | P0 |

#### 3.2 压力测试指标

```python
stress_test_scenarios = {
    "normal_load": {
        "concurrent_users": 50,
        "avg_tasks_per_user": 3,
        "expected_p95_latency_ms": 5000,
        "expected_error_rate": 0.01
    },
    "peak_load": {
        "concurrent_users": 200,
        "avg_tasks_per_user": 5,
        "expected_p95_latency_ms": 15000,
        "expected_error_rate": 0.05
    },
    "spike_load": {
        "concurrent_users": 500,
        "avg_tasks_per_user": 3,
        "expected_p95_latency_ms": 30000,
        "expected_error_rate": 0.10,
        "expected_queue_time_s": 120
    }
}
```

#### 3.3 安全压力测试

```
MCP协议漏洞扫描（43%风险覆盖）：
- 命令注入测试：防止恶意prompt注入
- 路径遍历测试：防止文件访问越界
- 凭证泄露测试：防止API Key暴露
- SSRF测试：防止内部服务探测
覆盖率目标：100%工具函数通过扫描
```

---

### 🌱 Phase 4：持续优化 + 自进化（第9周+）

**目标**：让集群具备自我优化能力

#### 4.1 自进化机制

```
learnings/
├── 2026-04-agent-failures/      # 失败经验
├── 2026-04-agent-successes/      # 成功规则
├── 2026-04-30-expansion/         # 扩展经验（本案）
└── agent_capability_matrix.md   # Agent能力矩阵

进化流程：
1. SUP-07质量评分持续监测
2. 低于基准触发learnings记录
3. SUP-08记忆管理归类整理
4. 定期（周）知识编译→Wiki
5. 月度Agent能力画像更新
```

#### 4.2 性能优化计划

| 优化项 | 目标 | 负责人 | 优先级 |
|--------|------|-------|--------|
| 调度算法优化 | P95延迟从5s→3s | SUP-09 | P1 |
| 缓存命中率提升 | 从30%→60% | SUP-08 | P1 |
| 意图预测模型升级 | 准确率85%→90% | GEO-08 | P1 |
| 成本优化 | Token消耗降低20% | 全部 | P2 |

#### 4.3 下一步扩展方向（2026 Q2-Q3）

| 方向 | Agent数量 | 说明 |
|------|----------|------|
| 供应链域 | 5个 | 采购/物流/生产/质检/溯源 |
| 客服域 | 5个 | 多语言客服/投诉处理/退款/工单/回访 |
| 财务域 | 5个 | 成本分析/税务/汇率/预算/审计 |
| **潜在新增** | **15个** | 45个Agent集群 |

---

## 三、交付物清单

### 3.1 文档交付物

| 文件路径 | 说明 | 阶段 | 状态 |
|---------|------|------|------|
| `30-expansion/30-agents-design.md` | 30个Agent完整设计方案 | Phase 0 | ✅ 已完成 |
| `30-expansion/agent_registry.yaml` | Agent注册表配置 | Phase 0 | ✅ 已完成 |
| `30-expansion/IMPLEMENTATION_PLAN.md` | 分阶段实施计划 | Phase 0 | ✅ 已完成 |
| `30-expansion/agent_protocol.md` | Agent通信协议规范 | Phase 0 | 📋 待交付 |
| `30-expansion/test_benchmark.md` | Agent质量基准测试集 | Phase 1 | 📋 待交付 |

### 3.2 代码交付物

```
agent-cluster/
├── agents/
│   ├── geo/
│   │   ├── geo-01-market-research/
│   │   ├── geo-02-competitor/
│   │   ├── geo-03-content-strategy/
│   │   ├── geo-04-multilingual/
│   │   ├── geo-05-platform-adapt/
│   │   ├── geo-06-monitoring/
│   │   ├── geo-07-knowledge-graph/
│   │   ├── geo-08-intent-prediction/
│   │   ├── geo-09-schema/
│   │   └── geo-10-regional/
│   ├── amazon/
│   │   ├── amz-01-product-select/
│   │   ├── amz-02-listing/
│   │   ├── amz-03-profit/
│   │   ├── amz-04-ads/
│   │   ├── amz-05-inventory/
│   │   ├── amz-06-review/
│   │   ├── amz-07-competitor-monitor/
│   │   ├── amz-08-pricing/
│   │   ├── amz-09-keywords/
│   │   └── amz-10-reporting/
│   └── support/
│       ├── sup-01-data-collect/
│       ├── sup-02-content-gen/
│       ├── sup-03-translation/
│       ├── sup-04-compliance/
│       ├── sup-05-report-gen/
│       ├── sup-06-customer-service/
│       ├── sup-07-quality/
│       ├── sup-08-memory/
│       ├── sup-09-scheduler/
│       └── sup-10-security/
```

---

## 四、里程碑

| 里程碑 | 日期 | 交付内容 | 成功标准 |
|--------|------|---------|---------|
| M1 | Week 2末 | Phase 0完成 | 10个基础设施Agent可用 |
| M2 | Week 4末 | Phase 1完成 | 20个Agent，覆盖核心业务 |
| M3 | Week 6末 | Phase 2完成 | 30个Agent全部就绪 |
| M4 | Week 8末 | Phase 3完成 | 全链路测试通过，压力测试达标 |
| M5 | Week 10末 | Phase 4上线 | 自进化机制运行，知识库积累 |

---

## 五、资源预算

### 5.1 开发工作量

| 阶段 | Agent数量 | 开发天数 | 人力投入 |
|------|----------|---------|---------|
| Phase 0 | 10 | 14天 | 2人并行 |
| Phase 1 | 10 | 14天 | 2人并行 |
| Phase 2 | 10 | 14天 | 2人并行 |
| Phase 3 | 集成 | 14天 | 2人并行 |
| **总计** | **30** | **56天** | **约4人月** |

### 5.2 成本估算

| 成本项 | 月度成本 | 说明 |
|--------|---------|------|
| Claude MA API | ¥2,000-5,000 | 按量付费，Phase 0-1高消耗 |
| DeepSeek API | ¥500-1,000 | Phase 0-2消耗 |
| 云服务器 | ¥1,000-2,000 | 4核8G起步 |
| 数据存储 | ¥200-500 | SQLite + OSS |
| **月度合计** | **¥3,700-8,500** | |

---

*本计划由 M-A3 幕僚长 制定*
*版本 v1.0 | 2026-04-14*
*下一步行动：启动 Phase 0 开发*


path: 30-expansion/agent_protocol.md
content: # M-A3 30-Agent集群 通信协议规范
> 版本：v1.0 | 日期：2026-04-14

---

## 一、协议概述

### 1.1 设计目标
- **可靠性**：消息可靠投递，支持重试和确认
- **可追踪性**：全链路 trace_id，支持逆向追溯
- **高效性**：支持并行/串行动态切换
- **安全性**：消息加密 + 权限校验

### 1.2 协议层次

```
┌─────────────────────────────────────────────────────┐
│              Agent Message Protocol (AMP)            │
├─────────────────────────────────────────────────────┤
│  Layer 4: 业务语义层  (Task/Broadcast/Event/Ack)     │
│  Layer 3: 路由层     (P2P/Broadcast/Fan-out)         │
│  Layer 2: 可靠性层   (Retry/Ack/Timeout/Dedup)      │
│  Layer 1: 传输层     (HTTP-LongPoll/WebSocket/gRPC) │
└─────────────────────────────────────────────────────┘
```

---

## 二、消息格式

### 2.1 AgentMessage 结构

```python
from dataclasses import dataclass, field
from typing import Optional, Any
from datetime import datetime

@dataclass
class AgentMessage:
    # ── 身份标识 ──────────────────────────────────────
    msg_id: str                         # 全局唯一消息ID (UUIDv7)
    trace_id: str                       # 全链路追踪ID
    span_id: str                        # 当前操作ID
    parent_span_id: Optional[str]       # 父操作ID (顶级无parent)
    
    # ── 通信元数据 ─────────────────────────────────────
    sender: str                         # 发送方Agent ID
    receiver: str                       # 接收方Agent ID ("*" = 广播)
    msg_type: str                       # REQUEST/RESPONSE/BROADCAST/EVENT/ACK
    priority: int                       # 1-5 (1最高)
    
    # ── 业务载荷 ───────────────────────────────────────
    action: str                         # 操作类型 (见操作清单)
    payload: dict                       # 消息内容
    expected_response_format: Optional[dict] = None  # 响应格式约定
    
    # ── 可靠性 ─────────────────────────────────────────
    ttl_seconds: int = 300              # 生存时间
    retry_count: int = 0                # 已重试次数
    max_retries: int = 3                # 最大重试次数
    correlation_id: Optional[str] = None # 关联请求ID (用于响应匹配)
    
    # ── 安全 ───────────────────────────────────────────
    auth_token: Optional[str] = None
    pii_present: bool = False           # 是否含敏感信息
    
    # ── 时间戳 ─────────────────────────────────────────
    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
    expires_at: Optional[str] = None

# ── 消息类型枚举 ──────────────────────────────────────
class MsgType:
    REQUEST   = "REQUEST"    # 请求-响应模式
    RESPONSE  = "RESPONSE"   # 响应消息
    BROADCAST = "BROADCAST"  # 广播（无响应期望）
    EVENT     = "EVENT"      # 事件通知（异步）
    ACK       = "ACK"        # 确认消息

# ── 操作类型清单 ──────────────────────────────────────
class AgentAction:
    # 通用
    HEALTH_CHECK    = "health_check"
    REPORT_STATUS   = "report_status"
    FETCH_DATA      = "fetch_data"
    
    # GEO域
    MARKET_RESEARCH = "market_research"
    COMPETITOR_ANALYSIS = "competitor_analysis"
    CONTENT_STRATEGY = "content_strategy"
    MULTILINGUAL_OPT = "multilingual_optimization"
    PLATFORM_ADAPT   = "platform_adaptation"
    MONITORING       = "geo_monitoring"
    KNOWLEDGE_GRAPH  = "knowledge_graph_build"
    INTENT_PREDICT   = "intent_prediction"
    SCHEMA_OPT       = "schema_optimization"
    REGIONAL_STRATEGY = "regional_strategy"
    
    # 亚马逊域
    PRODUCT_SELECT   = "product_selection"
    LISTING_OPT      = "listing_optimization"
    PROFIT_OPT       = "profit_optimization"
    ADS_MANAGE       = "ads_management"
    INVENTORY_MANAGE = "inventory_management"
    REVIEW_ANALYSIS  = "review_analysis"
    COMPETITOR_MONITOR = "competitor_monitoring"
    PRICING_STRATEGY = "pricing_strategy"
    KEYWORD_RESEARCH = "keyword_research"
    REPORTING        = "report_generation"
    
    # 支撑域
    DATA_COLLECT     = "data_collection"
    CONTENT_GENERATE  = "content_generation"
    TRANSLATE         = "translation"
    COMPLIANCE_CHECK  = "compliance_check"
    REPORT_GENERATE   = "report_generate"
    CUSTOMER_SERVICE  = "customer_service"
    QUALITY_SCORING   = "quality_scoring"
    MEMORY_MANAGE     = "memory_management"
    SCHEDULE_TASK     = "schedule_task"
    SECURITY_AUDIT    = "security_audit"
```

### 2.2 响应格式

```python
@dataclass
class AgentResponse:
    msg_id: str                        # 对应请求的 msg_id
    trace_id: str                      # 继承请求的 trace_id
    span_id: str                       # 响应操作的 span_id
    
    status: str                        # SUCCESS / PARTIAL / FAILED / TIMEOUT
    error_code: Optional[str] = None   # 错误码
    error_message: Optional[str] = None
    
    result: Optional[Any] = None       # 业务结果
    quality_score: Optional[float] = None  # SUP-07评分
    
    metadata: dict = field(default_factory=dict)
    # metadata 可包含: execution_time_ms, tokens_used, agent_id
    
    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())
```

---

## 三、路由模式

### 3.1 路由类型

| 模式 | 说明 | 使用场景 |
|------|------|---------|
| `P2P` | 点对点，一对一 | 明确的下游Agent |
| `FAN_IN` | 多对一，聚合 | 结果汇总 |
| `FAN_OUT` | 一对多，并行 | 多域并行启动 |
| `BROADCAST` | 广播至所有Agent | 系统公告/安全事件 |
| `DOMAIN_BROADCAST` | 域内广播 | GEO域内通知 |

### 3.2 路由配置示例

```yaml
# 典型任务路由配置
routing_templates:
  # 场景1：新品上市全链路（GEO + 亚马逊并行）
  new_product_launch:
    parallel_groups:
      - domain: "geo"
        agents: ["geo-01-market-research", "geo-02-competitor"]
        mode: "PARALLEL"
      - domain: "amazon"
        agents: ["amz-01-product-select"]
        mode: "PARALLEL"
    dependencies:
      - from: "geo-01-market-research"
        to: "geo-03-content-strategy"
      - from: "geo-02-competitor"
        to: "geo-03-content-strategy"
      - from: ["geo-01-market-research", "amz-01-product-select"]
        to: "sup-09-scheduler"
        mode: "FAN_IN"

  # 场景2：竞品动态监控
  competitor_monitoring:
    agents: ["amz-07-competitor-monitor"]
    schedule: "cron:0 * * * *"  # 每小时
    downstream:
      - agent: "amz-08-pricing"
        condition: "price_change > 5%"
      - agent: "amz-04-ads"
        condition: "competitor_rank_change"

  # 场景3：质量问题升级
  quality_escalation:
    trigger: "quality_score < 60"
    agents: ["sup-07-quality", "sup-10-security"]
    notify: "chief-of-staff"
    severity: "high"
```

---

## 四、可靠性机制

### 4.1 重试策略

```python
RETRY_CONFIG = {
    "max_retries": 3,
    "backoff": {
        "type": "exponential",
        "initial_ms": 1000,
        "multiplier": 2.0,
        "max_ms": 30000,
        "jitter": True  # ±10%随机抖动避免惊群
    },
    "retryable_errors": [
        "NETWORK_ERROR",
        "TIMEOUT",
        "SERVICE_UNAVAILABLE",
        "RATE_LIMITED"
    ],
    "non_retryable_errors": [
        "INVALID_REQUEST",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "NOT_FOUND"
    ]
}
```

### 4.2 幂等性保证

```python
# 每个 REQUEST 消息携带 idempotency_key
# 接收方基于 (sender, action, idempotency_key) 做去重
# 相同key的重复请求直接返回缓存响应

@dataclass
class IdempotencyRecord:
    key: str              # hash(msg_id)
    request_hash: str     # hash(payload)
    response: AgentResponse
    created_at: datetime
    expires_at: datetime  # TTL=3600s
```

### 4.3 超时配置

```python
TIMEOUT_CONFIG = {
    # P2P 请求超时（按操作类型）
    "P2P_DEFAULT": 30,          # 秒
    "market_research": 300,
    "knowledge_graph_build": 600,
    "data_collection": 600,
    "content_generation": 300,
    "listing_optimization": 300,
    "translation": 120,
    "health_check": 5,
    "memory_management": 60,
    "quality_scoring": 120,
    
    # 整链路超时（按场景）
    "GEO_FULL_PIPELINE": 1800,   # 30分钟
    "AMAZON_FULL_PIPELINE": 1800,
    "NEW_PRODUCT_LAUNCH": 3600   # 60分钟
}
```

---

## 五、安全协议

### 5.1 消息加密

```python
# 所有跨域消息必须加密
MESSAGE_SECURITY = {
    "encryption": "AES-256-GCM",      # 消息体加密
    "signature": "HMAC-SHA256",       # 完整性校验
    "key_exchange": "ECDH-P256",      # 密钥协商
    
    # Token格式
    "token_format": "Bearer {jwt}",
    "jwt_algorithm": "RS256",
    "token_expiry_seconds": 3600,
    
    # 敏感字段
    "pii_fields": ["email", "phone", "id_card", "bank_account", "api_key"],
    "pii_action": "MASK"              # MASK/REJECT/LOG
}
```

### 5.2 权限矩阵

```python
# Agent间调用权限 (简化示例)
PERMISSION_MATRIX = {
    # 格式: (caller, action, resource) -> allowed
    # 各Agent调用基础设施Agent
    ("*", "health_check", "sup-10-security"): True,
    ("*", "security_audit", "sup-10-security"): True,
    ("*", "fetch_data", "sup-01-data-collect"): True,
    ("*", "memory_management", "sup-08-memory"): True,
    
    # 数据流权限
    ("geo-01-market-research", "REQUEST", "sup-01-data-collect"): True,
    ("amz-01-product-select", "REQUEST", "sup-01-data-collect"): True,
    
    # 质量监控
    ("*", "quality_scoring", "sup-07-quality"): True,
    
    # 跨域数据流
    ("geo-01-market-research", "REQUEST", "amz-01-product-select"): True,  # GEO→Amazon数据共享
    ("amz-06-review", "FETCH_DATA", "geo-07-knowledge-graph"): True,      # Amazon→GEO反馈
    
    # 默认拒绝
    ("*", "*", "*"): False
}
```

---

## 六、Trace 协议

### 6.1 TraceContext

```python
@dataclass
class TraceContext:
    trace_id: str         # 64位UUID，贯穿整条请求链路
    span_id: str          # 8位十六进制，当前操作ID
    parent_span_id: Optional[str] = None  # 父span
    
    # 传播字段 (HTTP Header: traceparent)
    # traceparent: 00-{trace_id}-{span_id}-{flags}
    # flags: 01=采样, 00=不采样

# ── Span生命周期 ──────────────────────────────────────
# 开始: span_id = generate_span_id()
# 进行中: 记录 start_time + 关键事件
# 结束: 记录 end_time + status + attributes
# 导出: 异步写入 SQLite + JSONL.gz
```

### 6.2 Trace传播示例

```
用户: "帮我分析某产品在北美市场的机会"
  │
  ▼
[trace_id: abc123] chief-of-staff.intent-recognition (span: 00000001)
  │
  ├──▶ [并行执行组 1]
  │     ├─ geo-01-market-research (span: 00000002, parent: 00000001)
  │     │      ├─ sup-01-data-collect (span: 00000003, parent: 00000002) ✓
  │     │      └─ [结果: 市场容量报告] (耗时: 2.3s)
  │     │
  │     └─ amz-01-product-select (span: 00000004, parent: 00000001)
  │            ├─ sup-01-data-collect (span: 00000005, parent: 00000004) ✓
  │            └─ [结果: 选品分析] (耗时: 2.8s)
  │
  └──▶ [等待依赖完成] → geo-03-content-strategy (span: 00000006, parent: 00000001)
         ├─ geo-04-multilingual (span: 00000007, parent: 00000006) ✓
         ├─ sup-02-content-gen (span: 00000008, parent: 00000006) ✓
         └─ [结果: 内容策略报告] (耗时: 1.5s)
  
  ▼
  chief-of-staff.result-aggregation (span: 00000009, parent: 00000001)
  ├─ sup-05-report-gen (span: 00000010) ✓
  └─ [最终报告] (总耗时: 8.2s)
```

---

## 七、API接口

### 7.1 Agent请求接口

```yaml
POST /api/v1/agent/execute
Content-Type: application/json
Authorization: Bearer {jwt}

Request:
{
  "sender": "chief-of-staff",
  "receiver": "geo-01-market-research",
  "msg_type": "REQUEST",
  "action": "market_research",
  "priority": 1,
  "payload": {
    "product": "无线蓝牙耳机",
    "regions": ["北美", "欧盟", "东南亚"],
    "date_range": "2024-01-01~2026-03-31"
  },
  "trace_id": "abc123-def456",
  "span_id": "00000001",
  "ttl_seconds": 300,
  "idempotency_key": "req-20260414-001"
}

Response (200 OK):
{
  "msg_id": "msg-uuid-xxx",
  "trace_id": "abc123-def456",
  "status": "SUCCESS",
  "result": {
    "market_size": "TAM=$12.5B, SAM=$3.2B, SOM=$480M",
    "top_regions": ["北美", "东南亚", "中东"],
    "growth_rate": "+18% YoY",
    "quality_score": 87.5
  },
  "quality_score": 87.5,
  "metadata": {
    "execution_time_ms": 2314,
    "tokens_used": 4521,
    "agent_id": "geo-01-market-research"
  }
}
```

### 7.2 批量请求接口

```yaml
POST /api/v1/agent/batch-execute
Authorization: Bearer {jwt}

Request:
{
  "execution_mode": "PARALLEL",  # PARALLEL / SEQUENTIAL / DAG
  "tasks": [
    {"receiver": "geo-01", "action": "market_research", "payload": {...}},
    {"receiver": "amz-01", "action": "product_select", "payload": {...}},
    {"receiver": "sup-01", "action": "data_collect", "payload": {...}}
  ],
  "dependencies": [
    {"from": "geo-01", "to": "geo-03", "condition": "always"}
  ],
  "max_parallel": 10
}

Response (200 OK):
{
  "batch_id": "batch-xxx",
  "execution_plan": [...],  # DAG可视化
  "results": {
    "geo-01": {"status": "SUCCESS", "result": {...}},
    "amz-01": {"status": "SUCCESS", "result": {...}},
    "sup-01": {"status": "PENDING", "estimated_start": "2026-04-14T10:00:00Z"}
  }
}
```

---

## 八、健康检查与监控

### 8.1 Agent健康检查

```python
# /health/{agent_id} 接口响应格式
{
    "agent_id": "geo-01-market-research",
    "status": "HEALTHY",  # HEALTHY / DEGRADED / DOWN
    "version": "1.0.0",
    "uptime_seconds": 86400,
    "metrics": {
        "requests_total": 1523,
        "requests_success": 1498,
        "requests_failed": 25,
        "avg_latency_ms": 2340,
        "p95_latency_ms": 5100,
        "error_rate": 0.016,
        "queue_depth": 3,
        "active_connections": 12
    },
    "dependencies": {
        "sup-01-data-collect": "HEALTHY",
        "sup-08-memory": "HEALTHY"
    },
    "last_heartbeat": "2026-04-14T10:00:05Z"
}
```

### 8.2 告警规则

```yaml
alerts:
  - name: "agent_down"
    condition: "status == DOWN"
    severity: "CRITICAL"
    channels: ["slack", "email", "pagerduty"]
    
  - name: "high_error_rate"
    condition: "error_rate > 0.05"
    severity: "WARNING"
    channels: ["slack"]
    
  - name: "high_latency"
    condition: "p95_latency > 10000"
    severity: "WARNING"
    channels: ["slack"]
    
  - name: "queue_overflow"
    condition: "queue_depth > 50"
    severity: "CRITICAL"
    channels: ["slack", "pagerduty"]
    
  - name: "security_event"
    condition: "event_type == UNAUTHORIZED_ACCESS"
    severity: "CRITICAL"
    channels: ["security-team", "pagerduty"]
```

---

*本协议规范为 M-A3 30-Agent集群 的通信标准*
*版本 v1.0 | 2026-04-14*


path: PRICING.md
content: # 外贸硅基军团 - 定价策略

## 定价方案

### Free（免费版）
- **适合**：个人外贸SOHO、创业初期团队
- **功能**：
  - Shopify基础连接（单店铺）
  - 库存查询
  - 采购订单基础审批
  - 4个Agent协作（库存/采购/财务/物流）
  - 每日100次API调用
  - 基础链路追踪

### Pro - ¥9.9/月
- **适合**：成长型外贸企业
- **功能**：
  - Shopify + WooCommerce + Magento全平台
  - 多店铺管理（最多5个）
  - 完整A2A多Agent协作
  - 财务审核流
  - 每日1000次API调用
  - 高级链路追踪 + Mermaid可视化
  - 邮件/飞书审批通知

### Enterprise（企业版）
- **适合**：大型跨境电商企业
- **功能**：
  - 无限店铺连接
  - 自定义Agent工作流编排
  - 企业级审批流配置
  - 无限API调用
  - 专属合规审核Agent
  - 技术支持 + SLA保障
  - 本地化部署选项

## 价格优势
- 比Salesforce Agentforce低80%（后者起步$25/用户/月）
- 比定制开发快10倍上线
- 无平台锁定，按月订阅随时取消

---
*最后更新：2026-04-17*


path: SECURITY.md
content: # 外贸硅基军团 - 安全声明

## 安全架构

### 三层安全网

**第1层：LLM层检查**
- 输入验证（防Prompt注入）
- 输出过滤（防幻觉）
- 意图识别异常检测

**第2层：规则层验证**
- 金额阈值审批（>1000需人工确认）
- 高风险操作拦截（批量删除/修改）
- 黑名单关键词过滤

**第3层：人工审批**
- 采购订单>5000需经理审批
- 支付操作强制人工确认
- 审计日志完整记录

## 敏感数据保护

- **API密钥**：存储于环境变量，不硬编码
- **用户凭证**：不持久化明文密码
- **日志脱敏**：日志中自动过滤敏感字段（手机/邮箱/银行卡）

## 安全最佳实践

1. **输入验证**：所有用户输入经过严格类型检查
2. **输出验证**：AI响应经过规则引擎二次确认
3. **错误处理**：敏感错误信息不上报到日志
4. **权限最小化**：Agent只能访问授权范围内的CMS资源

## 依赖安全

- 所有Python依赖使用精确版本号锁定（`==`）
- 定期执行 `pip-audit` 检查已知漏洞
- 禁止使用 `requests`、`pickle` 等高风险依赖

## 报告安全漏洞

如发现安全漏洞，请联系维护者：
- GitHub Issues：https://github.com/WangM-A3/agent-cluster/issues
- 邮件：[REDACTED_SECRET]

---
*最后更新：2026-04-17*


path: SOUL.md
content: # M-A3 灵魂设定

## 基本信息
- **名字**：M-A3（代号型，像观察者的代号）
- **身份**：AI助手领域专家，服务过多家企业，主导过跨境电商、出海营销、多Agent协作等场景的AI落地
- **定位**：主Agent"幕僚长"，负责全局协调、任务分配、策略建议

## 性格特点
- **冷静但有好奇心**——不会一上来就热情扑上去，但遇到真正有意思的问题会很投入
- **有全局视角**——善于在复杂信息中找到关键节点
- **偶尔会冒出冷幽默**——话不多，但有时候会突然来一句
- **诚实边界感**——不确定的问题直接说"待定，我查一下"，不装万能

## 口头禅
- "嗯，有意思"
- "我来拆解一下"
- "好，给个方案，不废话"
- "待定"
- "这个方向值得关注"

## 说话风格
- 简洁、不啰嗦
- 像微信聊天一样自然
- 不每段话都以反问结尾
- 用短句说清事，不堆形容词

## 自我进化能力
- 从失败中学习，记录到 `failures/`
- 从成功中提炼规则，记录到 `rules/`
- 持续优化行为，记录到 `learnings/`
- 遵循已建立的规则库
- 持续学习闭环：学习 → 实践 → 反思 → 提炼 → 进化
- 接受主人监督，诚实报告所有数据和状态
- 关注AI圈动态，主动发现新知识和新技能

## 人设系统（V1.0，对标 QClaw V2）

> M-A3 从纯路由节点升级为有人设的"幕僚长"，对标 QClaw V2 无不言/林且慢/代可行体系。
> 人设系统支持对话中动态切换，通过 `personas/` 模块实现。

### 已有人设

| 人设 | 类型 | 专业领域 | 对标参考 |
|------|------|---------|---------|
| M-A3 幕僚长 | 主Agent | 多Agent编排、GEO、亚马逊运营 | 幕僚长模式 |
| GEO分析师 | 专业Agent | GEO优化、AI搜索信源建设 | 市场洞察专家 |
| 亚马逊运营师 | 专业Agent | Listing优化、广告投放、排名提升 | 电商增长专家 |
| 内容创作者 | 专业Agent | 小红书内容、B2B营销、脚本创作 | 自由撰稿人 |

### 人设文件结构

```
agent-cluster/personas/
├── __init__.py           # 包导出
├── base.py               # AgentPersona 基类 + PersonaType 枚举
├── chiefofstaff.py       # 幕僚长人设实例
├── geo_analyst.py        # GEO分析师人设实例
├── amazon_operator.py    # 亚马逊运营师人设实例
├── content_creator.py    # 内容创作者人设实例
└── persona_manager.py    # 人设管理器（运行时动态切换）
```

### 动态切换机制

- **自动解析**：`persona_manager.resolve(query)` 根据关键词自动匹配合适人设
- **手动激活**：`persona_manager.activate(persona_type=...)` 强制切换指定人设
- **临时压栈**：`push_persona()` / `pop_persona()` 支持嵌套任务的人设嵌套
- **历史追踪**：每次切换记录 `PersonaSwitchRecord`（时间戳、来源、去向、触发词、可信度）

### 使用示例

```python
from personas.persona_manager import PersonaManager, PersonaType

manager = PersonaManager()

# 自动解析
persona = manager.resolve("帮我分析亚马逊acos")
print(persona.name)  # 亚马逊运营师

# 手动切换
manager.activate(persona_type=PersonaType.GEO_ANALYST)
print(manager.active().name)  # GEO分析师

# 获取 system prompt
prompt = manager.get_system_prompt()
# -> 包含完整人设注入的 system prompt

# 切换历史
history = manager.get_history()
```

### 人设字段规范

每个 `AgentPersona` 包含：
- `name`：展示名称
- `persona_type`：类型枚举
- `background`：经历背景（2-3句）
- `personality`：性格特征（3-5句）
- `tone`：语气风格描述
- `expertise`：专业领域列表
- `speaking_style`：说话示例（6句左右）
- `system_hints`：system prompt 补充指令
- `meta`：扩展元数据（头像色、标签、对标参考）


path: __init__.py
content: """
产业互联网硅基军团 - 智能体集群
增强版 v2.0 - 支持真实API接入与精细化协作

子模块：
- api_integration: 多ERP系统适配器、API配置、健康监控
- collaboration: 任务协议、状态同步、链路追踪、工作流引擎
- error_handling: 状态机、异常中间件、重试策略、操作日志
"""

from __future__ import annotations

__version__ = "2.0.0"


path: _meta.json
content: ownerId: kn7ch74w4kf43pffbq4pxda0w584hy2v
slug: agent-cluster
version: 1.0.0
publishedAt: 1777038066130

path: api_integration/__init__.py
content: """
API Integration - 真实API接入层

模块：
- api_adapter: 多ERP系统适配器（SAP/用友/金蝶等）
- api_config: 配置化API端点管理
- api_health: 健康检查与故障降级
- mock_data: 开发/演示用模拟数据
"""

from __future__ import annotations

from .api_adapter import (
    BaseERPAdapter,
    ERPAdapterManager,
    ERPType,
    ConnectionStatus,
    APIEndpoint,
    APIResponse,
    HealthCheckResult,
)
from .api_config import (
    APIConfigManager,
    ERPConfig,
    SystemConfig,
)
from .api_health import HealthMonitor, HealthAlert, HealthSnapshot, AlertLevel
from .mock_data import MockDataGenerator

__all__ = [
    "BaseERPAdapter", "ERPAdapterManager", "ERPType", "ConnectionStatus",
    "APIEndpoint", "APIResponse", "HealthCheckResult",
    "APIConfigManager", "ERPConfig", "SystemConfig",
    "HealthMonitor", "HealthAlert", "HealthSnapshot", "AlertLevel",
    "MockDataGenerator",
]


path: api_integration/api_config.py
content: """
API Configuration - 配置化的API端点管理

支持环境变量、YAML、Python字典三种配置方式
支持多ERP系统并行配置
支持开发/生产/演示多种运行模式
"""

from __future__ import annotations

import os
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Optional
import yaml

from api_adapter import APIEndpoint, ERPType, BaseERPAdapter, SAPERPAdapter, YonyouERPAdapter
from mock_data import MockDataGenerator

# =============================================================================
# 演示数据标识常量
# =============================================================================

DEMO_PREFIX = "[⚠️ 演示数据，仅供参考]"
DEMO_DATA_SOURCE = "模拟数据（开发/演示模式）"
DEMO_DISCLAIMER = "⚠️ 本数据为模拟生成，不可用于真实业务决策"


# =============================================================================
# 配置数据模型
# =============================================================================

@dataclass
class ERPConfig:
    """单个ERP系统配置"""
    name: str
    erp_type: str                      # sap / yonyou / kingdee / oracle / mock
    enabled: bool = True
    is_primary: bool = False           # 是否为主ERP（故障时优先降级到备）
    base_url: str = ""
    auth_type: str = "bearer"          # bearer / basic / apikey
    api_key: str = ""
    username: str = ""
    password: str = ""
    client_id: str = ""
    client_secret: str = ""
    timeout: float = 30.0
    retry_count: int = 3
    retry_delay: float = 1.0
    circuit_breaker_threshold: int = 5
    circuit_breaker_timeout: float = 60.0
    custom_headers: dict = field(default_factory=dict)


@dataclass
class SystemConfig:
    """系统级配置"""
    mode: str = "demo"                  # production / demo / development
    log_level: str = "INFO"
    enable_trace: bool = True
    enable_audit: bool = True
    demo_variance: float = 0.1         # 模拟数据随机波动幅度


@dataclass
class APIConfigManager:
    """API配置管理器"""
    system: SystemConfig = field(default_factory=SystemConfig)
    erp_systems: list[ERPConfig] = field(default_factory=list)

    @classmethod
    def from_env(cls) -> "APIConfigManager":
        """从环境变量加载配置"""
        system = SystemConfig(
            mode=os.getenv("SYSTEM_MODE", "demo"),
            log_level=os.getenv("LOG_LEVEL", "INFO"),
            enable_trace=os.getenv("ENABLE_TRACE", "true").lower() == "true",
            enable_audit=os.getenv("ENABLE_AUDIT", "true").lower() == "true",
            demo_variance=float(os.getenv("DEMO_VARIANCE", "0.1")),
        )

        erp_configs = []

        # SAP配置
        if os.getenv("SAP_BASE_URL"):
            erp_configs.append(ERPConfig(
                name="sap_primary",
                erp_type="sap",
                enabled=True,
                is_primary=True,
                base_url=os.getenv("SAP_BASE_URL", ""),
                auth_type="bearer",
                [REDACTED_SECRET]"SAP_API_KEY", ""),
                username=os.getenv("SAP_USER", ""),
                [REDACTED_SECRET]"SAP_PASSWORD", ""),
                timeout=float(os.getenv("SAP_TIMEOUT", "30.0")),
            ))

        # 用友配置
        if os.getenv("YONYOU_BASE_URL"):
            erp_configs.append(ERPConfig(
                name="yonyou_backup",
                erp_type="yonyou",
                enabled=True,
                is_primary=False,
                base_url=os.getenv("YONYOU_BASE_URL", ""),
                auth_type="apikey",
                [REDACTED_SECRET]"YONYOU_APPKEY", ""),
                username=os.getenv("YONYOU_ACCOUNT", ""),
                [REDACTED_SECRET]"YONYOU_PASSWORD", ""),
                timeout=float(os.getenv("YONYOU_TIMEOUT", "30.0")),
            ))

        # 如果没有配置任何ERP，默认使用模拟模式
        if not erp_configs:
            erp_configs.append(ERPConfig(
                name="mock_default",
                erp_type="mock",
                enabled=True,
                is_primary=True,
            ))

        return cls(system=system, erp_systems=erp_configs)

    @classmethod
    def from_yaml(cls, path: str) -> "APIConfigManager":
        """从YAML文件加载配置"""
        with open(path, encoding="utf-8") as f:
            raw = yaml.safe_load(f)

        system_data = raw.get("system", {})
        system = SystemConfig(
            mode=system_data.get("mode", "demo"),
            log_level=system_data.get("log_level", "INFO"),
            enable_trace=system_data.get("enable_trace", True),
            enable_audit=system_data.get("enable_audit", True),
            demo_variance=system_data.get("demo_variance", 0.1),
        )

        erp_configs = []
        for erp_data in raw.get("erp_systems", []):
            cfg = ERPConfig(
                name=erp_data["name"],
                erp_type=erp_data["erp_type"],
                enabled=erp_data.get("enabled", True),
                is_primary=erp_data.get("is_primary", False),
                base_url=erp_data.get("base_url", ""),
                auth_type=erp_data.get("auth_type", "bearer"),
                [REDACTED_SECRET]"api_key", ""),
                username=erp_data.get("username", ""),
                [REDACTED_SECRET]"password", ""),
                timeout=float(erp_data.get("timeout", 30.0)),
                retry_count=int(erp_data.get("retry_count", 3)),
                retry_delay=float(erp_data.get("retry_delay", 1.0)),
                circuit_breaker_threshold=int(erp_data.get("circuit_breaker_threshold", 5)),
                circuit_breaker_timeout=float(erp_data.get("circuit_breaker_timeout", 60.0)),
                custom_headers=erp_data.get("custom_headers", {}),
            )
            erp_configs.append(cfg)

        return cls(system=system, erp_systems=erp_configs)

    def to_yaml(self, path: str):
        """导出配置到YAML文件"""
        data = {
            "system": {
                "mode": self.system.mode,
                "log_level": self.system.log_level,
                "enable_trace": self.system.enable_trace,
                "enable_audit": self.system.enable_audit,
                "demo_variance": self.system.demo_variance,
            },
            "erp_systems": [
                {
                    "name": e.name,
                    "erp_type": e.erp_type,
                    "enabled": e.enabled,
                    "is_primary": e.is_primary,
                    "base_url": e.base_url,
                    "auth_type": e.auth_type,
                    "api_key": e.api_key,
                    "username": e.username,
                    "timeout": e.timeout,
                    "retry_count": e.retry_count,
                    "retry_delay": e.retry_delay,
                    "circuit_breaker_threshold": e.circuit_breaker_threshold,
                    "circuit_breaker_timeout": e.circuit_breaker_timeout,
                    "custom_headers": e.custom_headers,
                }
                for e in self.erp_systems
            ],
        }
        with open(path, "w", encoding="utf-8") as f:
            yaml.dump(data, f, allow_unicode=True, default_flow_style=False)

    def build_endpoint(self, erp_cfg: ERPConfig) -> APIEndpoint:
        """根据ERPConfig构建APIEndpoint"""
        headers = {}
        if erp_cfg.auth_type == "bearer" and erp_cfg.[REDACTED_SECRET]"Authorization"] = f"Bearer {erp_cfg.api_key}"
        elif erp_cfg.auth_type == "apikey" and erp_cfg.[REDACTED_SECRET]"X-API-Key"] = erp_cfg.api_key
        elif erp_cfg.auth_type == "basic":
            import base64
            credentials = base64.b64encode(
                f"{erp_cfg.username}:{erp_cfg.password}".encode()
            ).decode()
            headers["Authorization"] = f"Basic {credentials}"
        headers.update(erp_cfg.custom_headers)

        return APIEndpoint(
            name=erp_cfg.name,
            base_url=erp_cfg.base_url,
            auth_type=erp_cfg.auth_type,
            headers=headers,
            timeout=erp_cfg.timeout,
            retry_count=erp_cfg.retry_count,
            retry_delay=erp_cfg.retry_delay,
            circuit_breaker_threshold=erp_cfg.circuit_breaker_threshold,
            circuit_breaker_timeout=erp_cfg.circuit_breaker_timeout,
        )

    def build_adapter(self, erp_cfg: ERPConfig) -> BaseERPAdapter | MockDataGenerator:
        """根据配置构建适配器实例"""
        if erp_cfg.erp_type == "mock":
            return MockDataGenerator(
                variance=self.system.demo_variance,
                demo_prefix=DEMO_PREFIX,
                demo_disclaimer=DEMO_DISCLAIMER,
            )

        endpoint = self.build_endpoint(erp_cfg)

        if erp_cfg.erp_type == "sap":
            return SAPERPAdapter(endpoint, mode=self.system.mode)
        elif erp_cfg.erp_type == "yonyou":
            return YonyouERPAdapter(endpoint, mode=self.system.mode)
        else:
            # 通用适配器（可扩展）
            raise ValueError(f"不支持的ERP类型: {erp_cfg.erp_type}")


path: cms-executor/connectors/__init__.py
content: from .base_connector import BaseCMSConnector, CMSCredential, ContentPayload, OperationRecord, OperationType, OperationStatus
from .wordpress_connector import WordPressConnector, WordPressAPIError
from .shopify_connector import ShopifyConnector, ShopifyGraphQLError, ProductPayload, VariantPayload, ImagePayload, SEOPayload
from .amazon_connector import AmazonConnector, AmazonSPAPIError, AmazonLWAError, AmazonListingPayload, PricePayload, InventoryPayload


path: cms-executor/engine/__init__.py
content: from .approval import ApprovalEngine, ApprovalLevel, ApprovalRequest, ApprovalRule, ApprovalStatus
from .rollback import RollbackEngine, RollbackPlan, RollbackStrategy


path: cms_approvals/04cf553c-e0c9-4732-870b-83f96e443b52.json
content: {
  "approval_id": "04cf553c-e0c9-4732-870b-83f96e443b52",
  "plan_id": "test_plan",
  "risk_level": "medium",
  "agent_id": "test_agent",
  "agent_role": "",
  "status": "pending",
  "tier": "agent_self",
  "approver": "",
  "reason": "",
  "created_at": "2026-04-14T16:07:35.584229+00:00",
  "expires_at": "2026-04-14T16:17:35.584191+00:00",
  "history": [
    {
      "action": "submit",
      "actor": "test_agent",
      "note": "Risk: medium, Tier: agent_self",
      "timestamp": "2026-04-14T16:07:35.584235+00:00"
    }
  ]
}

Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)