# SmartAgent

**Repository Path**: iiowe2/smart-agent

## Basic Information

- **Project Name**: SmartAgent
- **Description**: 文档代表了一种将社会科学治理模型系统化地编译为工业级AI Agent系统的前沿实践。它不追求“大模型万能”，而是通过双轨制、培养期、集体记忆、提案机制等精巧的工程设计，让AI系统像真实组织一样可治理、可进化、可问责。对于任何正在构建企业级AI Agent平台（尤其是制造业、供应链、运维领域）的团队，这些文档提供了可直接借鉴的设计模式和代码骨架。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SmartAgent

# 面向治理的 Agent 系统设计模式

> 本文档提炼自一个制造业数字组织治理平台的实际设计与演进经验，旨在提供一套**独立于具体代码实现**的通用设计模式。  
> 适用场景：企业级 AI Agent 平台、制造业决策自动化、组织级自主系统。  
> 核心理念：**让 Agent 系统像真实组织一样可治理、可进化、可问责**。

---

## 目录

- [1. 背景：为什么 Agent 系统需要“治理”？](#1-背景为什么-agent-系统需要治理)
- [2. 治理哲学：六条宪法原则](#2-治理哲学六条宪法原则)
- [3. 核心架构概念](#3-核心架构概念)
  - [3.1 事件中枢 —— 所有决策的源头落地](#31-事件中枢--所有决策的源头落地)
  - [3.2 双轨制 —— 规则与智能的平衡](#32-双轨制--规则与智能的平衡)
  - [3.3 Agent 体系 —— 数字员工模型](#33-agent-体系--数字员工模型)
- [4. 关键治理机制](#4-关键治理机制)
  - [4.1 干部培养期 —— 从新手到专家](#41-干部培养期--从新手到专家)
  - [4.2 集体记忆库 —— 组织知识的共享与衰减](#42-集体记忆库--组织知识的共享与衰减)
  - [4.3 群众提案 —— 自下而上的改进闭环](#43-群众提案--自下而上的改进闭环)
  - [4.4 委员会复盘 —— 数据驱动的组织体检](#44-委员会复盘--数据驱动的组织体检)
  - [4.5 AB 角与轮岗 —— 组织韧性设计](#45-ab-角与轮岗--组织韧性设计)
  - [4.6 协商协议 —— 民主讨论与集中裁决](#46-协商协议--民主讨论与集中裁决)
  - [4.7 主席巡视 —— 低成本监督与自动召回](#47-主席巡视--低成本监督与自动召回)
  - [4.8 自适应推广 —— 动态阈值的试点上线](#48-自适应推广--动态阈值的试点上线)
  - [4.9 不可变审计 —— 链式哈希溯源](#49-不可变审计--链式哈希溯源)
  - [4.10 计划轨道观察 —— 让沉默决策发声](#410-计划轨道观察--让沉默决策发声)
- [5. 标准化协作协议](#5-标准化协作协议)
- [6. 生命周期管理](#6-生命周期管理)
- [7. 配置设计模式](#7-配置设计模式)
  - [7.1 配置继承与组合](#71-配置继承与组合)
  - [7.2 版本控制与回滚](#72-版本控制与回滚)
  - [7.3 热加载与安全变更分类](#73-热加载与安全变更分类)
- [8. 演进路线图（通用版）](#8-演进路线图通用版)
- [9. 总结：从“AI 系统”到“数字组织”](#9-总结从-ai-系统到数字组织)

---

## 1. 背景：为什么 Agent 系统需要“治理”？

传统 AI Agent 系统通常关注三个问题：感知准不准、推理快不快、执行对不对。但在真实的企业环境中，尤其是制造业、供应链、运维等长流程领域，**真正的挑战不是单个 Agent 有多聪明，而是一群 Agent 如何协作、如何进化、如何承担责任**。

常见痛点：

- **缺乏统一的决策记录**：无法追溯“某次排产调整是谁决定的、依据是什么”。
- **经验无法沉淀**：每个 Agent 从零开始，同样的错误在不同 Agent 上重复发生。
- **没有自下而上的改进渠道**：Agent 发现系统规则不合理，只能被动执行，无法主动反馈。
- **单点知识固化**：某个 Agent 长期处理某类问题，积累了隐性知识，一旦故障或离职，组织失忆。
- **推广风险不可控**：新算法或新策略上线，要么全量（高风险），要么永远停留在实验区。

这些问题本质上与**真实组织的治理问题**同构。因此，我们提出：**用组织治理的哲学来设计 Agent 系统**，将“民主集中制”、“双轨制”、“批评与自我批评”等原则转化为可执行的代码机制。

---

## 2. 治理哲学：六条宪法原则

| 原则 | 核心含义 | 对应的机制 |
|------|----------|-------------|
| **民主集中制** | Agent 自主决策，协商失败时由主席裁决 | 协商协议 + 集中裁决 |
| **双轨制** | 稳定场景用规则（低成本），不确定场景用 LLM（高灵活） | 计划轨道 + 市场轨道 + 智能门控 |
| **摸着石头过河** | 先试点、再验证、后推广 | 干部培养期 + 试点服务 + 自适应推广 |
| **实事求是** | 一切靠数据说话，不靠直觉 | 计划轨道观察 + 集体记忆置信度 + 能力评估框架 |
| **独立自主** | 每个 Agent 对自己的域全权负责，不越界干涉他域 | 域隔离 + AB 角（韧性） |
| **批评与自我批评** | 定期复盘、自我审视、公开经验与教训 | 委员会复盘 + 集体记忆 + 自查传感器 |

这六条原则不依赖任何特定技术栈，是**可迁移的治理框架**。

---

## 3. 核心架构概念

### 3.1 事件中枢 —— 所有决策的源头落地

**核心理念**：任何进入系统的事件（无论是来自传感器、用户录入、还是其他系统回调）**必须先持久化，再处理**。

**关键设计**：

- **事件源分类**：外部推送、轮询、消息队列、IoT、人工录入、批量导入、系统定时、联邦跨厂、仿真。
- **生命周期状态机**：已摄入 → 已验证 → 已存储 → 处理中 → 已完成/失败/忽略 → 已归档。状态流转单向或有严格限制的重试。
- **人工事件一等公民**：当所有外部系统不可用时，人工录入成为主通道，事件形态与自动事件完全一致，走同一条处理管道。
- **幂等去重**：根据源类别、事件类型、主题、时间窗口生成去重键，同一窗口内的重复事件自动忽略（人工事件除外）。
- **冷启动恢复**：系统重启时自动拉取未处理事件，从中断点继续处理。

**收益**：完整溯源链、高可用降级、合规审计。

### 3.2 双轨制 —— 规则与智能的平衡

**核心思想**：不迷信 LLM，也不排斥规则。

| 轨道 | 驱动方式 | 成本 | 适用场景 |
|------|----------|------|----------|
| **计划轨道** | 确定性规则 / 决策树 / 状态机 | 极低（零 LLM Token） | 稳定、高频、可枚举的场景（如安全库存报警） |
| **市场轨道** | LLM + 工具调用 | 较高 | 复杂、不确定、需要推理的场景（如多约束紧急插单） |

**智能门控**：根据以下条件动态选择轨道：
- 预算余额
- 事件紧急度
- 历史案例匹配度
- 规则疲劳度（同一条规则连续命中多次无偏差 → 可降级审计频率）

**关键洞察**：计划轨道不是“低级”的代名词。恰恰相反，它是系统稳定性和成本控制的基石。并且，计划轨道的执行过程也需被观察（见 §4.10）。

### 3.3 Agent 体系 —— 数字员工模型

每个 Agent（数字员工）具有以下标准化属性：

- **身份**：ID、花名、领域、头像（拟人化增强协作可接受性）
- **人格**：果断度、详细度、主动性（三维度连续值，非硬编码性格）
- **能力**：一组可调用的工具（MCP Tools）和技能（Skills），每种工具有风险等级（读/写/管理）
- **权限**：自主等级（从“必须审批”到“全自动”五级）
- **红线**：明确禁止的操作列表
- **记忆**：
  - 工作记忆（当前任务上下文）
  - 个人经验（历史决策的教训）
  - 集体记忆（从组织共享知识库自动注入）
- **日程**：定时任务（Cron 表达式 + 自然语言指令）
- **行为流**：决策治理链（优先级路由） + 执行流程（Pipeline）

Agent 不是硬编码的，而是**由配置声明、运行时动态装配**。配置与运行时分离，使得系统可以热更新大部分行为。

---

## 4. 关键治理机制

### 4.1 干部培养期 —— 从新手到专家

**问题**：新 Agent 直接拥有与老 Agent 同等的自主权，可能因“鲁莽决策”造成破坏。

**机制**：

- 每个新 Agent 进入 **培养期**（例如前 200 次决策）。
- 培养期内：
  - 所有决策强制走 **试点对比**（与主席或老 Agent 的决策并行对比）。
  - 自主等级锁定为“建议通知”（不可自动执行）。
  - 每次决策后由主席生成“改进建议”（类似师傅点评）。
  - 培养期成绩由 **试点评分**（与标准答案的匹配率）和 **连续成功次数** 决定。
- 转正条件：试点评分超过阈值（如 0.95）且连续无重大偏差达到一定次数。
- 未通过则延长培养期或淘汰。

**设计模式**：渐进式授权 + 影子对比 + 数据驱动转正。

### 4.2 集体记忆库 —— 组织知识的共享与衰减

**问题**：个人经验无法在 Agent 间共享；老 Agent 退役后其知识随之流失。

**机制**：

- 集体记忆分四类：
  - 最佳实践（经验证的有效策略）
  - 失败复盘（错误案例与教训）
  - 跨域模式（多领域同时出现的规律）
  - 组织规则（从经验提炼的制度性约束）
- **自动提炼**：每次 Agent 决策后，以小概率（如 5%）自动将其经验提交为候选最佳实践，经主席审核后入库。
- **置信度与衰减**：每条记忆有一个置信度（0-1）。若长时间未被引用，置信度每月衰减一定比例；低于阈值时自动归档（不再参与召回）。
- **新员工入职**：自动加载相关领域的集体记忆，避免从零开始。

**设计模式**：经验公开化 + 时间衰减 + 强制传承。

### 4.3 群众提案 —— 自下而上的改进闭环

**问题**：Agent 发现系统规则不合理或存在重复模式，但无渠道反馈。

**机制**：

- Agent 可以发起 **提案**，类型包括：流程改进、跨域预警、自我约束调整、资源申请。
- 提案必须附带**数据证据**（如过去 30 天某模式出现 12 次）。
- 提案进入委员会投票（或主席裁决）。通过后，系统自动执行对应的改进（如修改规则、新增工具、调整红线）。
- 每个 Agent 每月有提案配额，防止信息过载。
- 提案被否决时记录原因，Agent 下次可携带更多证据再次提案。

**设计模式**：数据驱动的自下而上改进，将“一线工人的智慧”编码到系统中。

### 4.4 委员会复盘 —— 数据驱动的组织体检

**问题**：缺乏周期性、全局性的系统健康评估。

**机制**：

- 每月自动触发一次复盘会（非人工会议，系统自动执行）。
- 收集数据：
  - 各 Agent 的 KPI 达成率、响应时间、Token 消耗
  - 跨域协作成功率、协商失败率
  - 计划轨道 vs 市场轨道比例
  - 提案通过率、集体记忆引用率
- 识别问题：
  - KPI 下降超过阈值
  - 协作失败率过高
  - Token 消耗异常
  - 决策质量持续下滑
- 自动生成决议：
  - 调整 Agent 自主等级（奖励优秀、惩罚低效）
  - 优化配置（如红线、日程、工具集）
  - 提出培训建议（需人工介入的复杂问题）
- 决议自动执行或生成任务给管理员。

**设计模式**：系统自检 + 闭环改进 + 量化决策。

### 4.5 AB 角与轮岗 —— 组织韧性设计

**问题**：核心 Agent 故障或离职导致业务中断；隐性知识固化在个别人身上。

**机制**：

- **AB 角配对**：为每个关键 Agent 指定一个备用的 B 角（通常为同领域其他 Agent 或通用 Agent）。
- **故障转移**：定期健康检查（心跳、响应时延、最近活动时间）。若 A 角不健康，自动切换到 B 角。
- **B 角行为**：B 角接管期间，加载 **集体记忆**（而非 A 角的个人记忆），确保行为符合组织规范。
- **恢复与交接**：A 角恢复后，自动切回 A 角，并将 B 角期间的决策记录交接给 A 角。
- **强制轮岗**：每季度或每半年，同领域的 Agent 交换岗位，强制知识外溢。

**设计模式**：冗余 + 健康检查 + 知识交接 + 防固化。

### 4.6 协商协议 —— 民主讨论与集中裁决

**问题**：跨域冲突时，Agent 各自决策可能死锁或产生矛盾。

**机制**：

- 当两个及以上 Agent 对同一事件有不同判断，且影响范围跨域时，触发协商。
- 协商流程：**提案 → 辩论 → 投票 → 共识/僵局**。
- 辩论有最大轮次、每轮超时、全程超时。
- 投票权重与 Agent 的历史试点评分挂钩（高绩效者权重大）。
- 若协商无法达成共识（僵局或超时），自动升级给 **主席** 做集中裁决。
- 所有协商过程记录在案，可供复盘。

**设计模式**：有限轮次讨论 + 绩效加权投票 + 最终仲裁者。

### 4.7 主席巡视 —— 低成本监督与自动召回

**问题**：主席退出日常决策后，可能遗漏个别 Agent 的持续性偏差。

**机制**：

- 主席不干预常规决策，但 **以低频率随机抽查**（例如每 100 次决策抽查 1 次）。
- 抽查方式：用相同的输入重新模拟决策，对比原 Agent 输出与主席输出的差异。
- 若连续多次（如 3 次）偏差超过容忍阈值，则 **自动召回主席模式**，即临时提高该 Agent 的监督等级或暂时将其决策权收回。
- 偏差恢复正常后，主席再次退出。

**设计模式**：统计抽样监督 + 动态干预。

### 4.8 自适应推广 —— 动态阈值的试点上线

**问题**：固定阈值（如试点评分 > 99%）可能导致过严（永远无法推广）或过松（风险上线）。

**机制**：

- 每次试点对比（新 pipeline vs 生产 pipeline）产出试点评分（加权 F1-score）。
- 推广阈值不是固定值，而是 **动态调整**：
  ```
  基础阈值 = 0.99
  调整量 = 0.01 * (历史推广成功率 - 0.5) * 2
  最终阈值 = clamp(基础阈值 + 调整量, 0.97, 0.995)
  ```
- 当试点评分超过最终阈值，且连续稳定运行一段时间（如 7 天），自动将试点 pipeline 切换为生产 pipeline。
- 历史推广成功率越高，阈值越宽松（系统信誉好）；反之则越严格（进入保守模式）。

**设计模式**：自适应阈值 + 历史反馈 + 稳定期验证。

### 4.9 不可变审计 —— 链式哈希溯源

**问题**：审计记录可能被篡改或事后抵赖。

**机制**：

- 每条审计记录除本身内容外，增加一个字段 `PreviousHash`。
- 写入新记录时，计算 `CurrentHash = SHA256(记录内容 + PreviousHash)`。
- 形成哈希链：任意一条记录的篡改会导致后续所有记录的哈希不匹配。
- 审计系统可快速验证链的完整性。
- 不需要完整的区块链共识，轻量级但足以防范内部篡改。

**设计模式**：链式完整性校验。

### 4.10 计划轨道观察 —— 让沉默决策发声

**问题**：计划轨道（规则驱动）执行后不留痕迹，导致 80% 的决策经验沉默。

**机制**：

- 每次计划轨道执行后，记录：规则 ID、命中次数、实际结果与规则预期的偏差。
- 统计指标：
  - **规则命中率**：某规则过去 N 天的使用频率。
  - **规则偏差率**：实际结果偏离预期的比例（高偏差 → 规则需更新）。
  - **规则疲劳度**：连续命中且无偏差的次数（极高疲劳 → 可降低审计频率）。
  - **规则盲区率**：事件不匹配任何规则的比例（高盲区 → 需新增规则或改走市场轨道）。
- 月度报告自动生成，并作为集体记忆或提案的数据源。

**设计模式**：规则执行可观测 + 盲区发现 + 疲劳优化。

---

## 5. 标准化协作协议

为了消除 Agent 间协作的随意性，定义一套标准消息类型与路由规则：

| 消息类型 | 语义 | 典型场景 |
|----------|------|----------|
| `REQUEST_INFO` | 请求信息 | 排产 Agent 向库存 Agent 询问物料余量 |
| `CONSULT` | 咨询建议 | 采购 Agent 咨询质检 Agent 该供应商历史质量 |
| `BROADCAST` | 广播通知 | 某产线停机，通知所有相关 Agent |
| `ESCALATE` | 升级上报 | 协商失败或高严重度事件，上报主席 |

路由规则支持条件匹配（领域、事件类型、严重度等），并配置超时与重试策略。

---

## 6. 生命周期管理

每个 Agent 拥有一个清晰的状态机，状态代表了其 **信任等级**：

```
Created → Initializing → Ready → Running → Paused → Stopped → Archived
                              ↑        ↓
                              └── Error ←┘
```

| 状态 | 含义 | 允许的转变 |
|------|------|------------|
| **Probation**（培养期） | 信任等级低，强制试点 | → Active（转正）→ Retired（淘汰） |
| **Active** | 正常运行，全自主等级 | → Standby（故障）→ Retired |
| **Standby** | 被动接管（B 角）或临时降级 | → Active（恢复）→ Retired |
| **Retired** | 已从生产环境移除，经验已归档 | 终态 |

退役时自动触发经验提炼：将个人记忆中最有价值的部分提交到集体记忆库。

---

## 7. 配置设计模式

### 7.1 配置继承与组合

**问题**：多个 Agent 的配置高度重复（人格基础值、红线、工具集）。

**方案**：支持 `extends` 字段，子配置可继承基础配置，并采用 **JSON Merge Patch** 规则覆盖差异字段。

- 基础配置定义公共属性。
- 子配置只声明需要修改或新增的字段。
- 支持多级继承（A → B → C）。
- 数组字段整体覆盖（不支持局部合并，避免歧义）。

**收益**：配置复用、统一维护、降低错误率。

### 7.2 版本控制与回滚

**问题**：配置变更后无法快速恢复，且不知道改了哪些内容。

**方案**：

- 每次修改前自动创建配置快照（保留最近 N 个版本）。
- 快照存储完整的配置 JSON，并记录变更类型（用户编辑、系统同步、提案执行、热加载等）。
- 提供版本对比（Diff），高亮显示字段级差异。
- 支持一键回滚到任意历史版本，回滚时自动创建当前版本快照（安全网）。

**收益**：配置变更可审计、可回滚、可追溯。

### 7.3 热加载与安全变更分类

**问题**：配置更新需重启整个 Agent，影响服务连续性。

**方案**：区分 **安全变更** 与 **危险变更**。

| 变更类型 | 示例 | 生效方式 |
|----------|------|----------|
| 安全变更 | 人格参数、Prompt 模板、日程 | 热加载，无需重启 |
| 危险变更 | Agent ID、领域、红线、工具集 | 需要重启 Agent 实例 |

系统监听配置文件夹或数据库变更，自动分类并采取相应动作。危险变更时在前端提示“下次唤醒时生效”。

---

## 8. 演进路线图（通用版）

以下阶段不依赖具体项目，可作为任何类似系统的参考路线。

### 阶段一：基础设施（1-2 个月）

- 事件中枢（持久化 + 人工事件 + 冷启动恢复）
- 双轨制基础（计划轨道与市场轨道的路由逻辑）
- 基础审计日志

### 阶段二：治理机制（3-6 个月）

- 干部培养期
- 集体记忆库（含自动提炼与衰减）
- 群众提案
- 委员会复盘
- AB 角与轮岗

### 阶段三：智能增强（6-12 个月）

- 自适应推广阈值
- 协商协议
- 主席巡视
- 计划轨道观察
- 不可变审计链

### 阶段四：组织进化（1-3 年）

- 联邦协商（多工厂/多租户的跨组织协作）
- Agent 能力市场（第三方发布自定义 Agent）
- 自由竞争机制（同一事件多个 Agent 竞标）
- 治理 DSL（允许以声明式语言修改治理规则）

---

## 9. 总结：从“AI 系统”到“数字组织”

设计这套系统的最大体悟是：**AI Agent 系统的复杂性问题，本质上不是技术问题，而是治理问题**。

传统做法是不断优化模型精度、增加工具调用种类、提高并发数——但这些都无法解决“Agent 之间如何协调、如何共同进步、如何承担责任”的组织性难题。

我们提供的模式，将真实组织中经过验证的治理实践（民主集中、双轨、试点推广、群众路线、批评与自我批评）编译成了可执行、可测试、可演化的代码机制。这不是把政治口号生硬地贴到系统上，而是发现：**复杂自适应系统（无论是人类社会还是多 Agent 系统）面临的许多挑战是同构的**。

希望这套设计模式能启发更多团队，在构建自主系统时，不仅关注“智能”，也关注“治理”。毕竟，一个无法治理的智能系统，最终可能比没有智能的系统更危险。

---

**文档版本**：1.0（开源抽象版）  
**许可**：CC BY-SA 4.0  
**反馈**：欢迎通过 issue 或 PR 提出改进建议