# zAgent

**Repository Path**: cpsoft13/z-agent

## Basic Information

- **Project Name**: zAgent
- **Description**: 用于系统集成的内置agent。用于数据分析和流程生成
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zAgent

**给你的业务系统装上"AI 员工"的 Go 框架**：它们能盯数据、写方案、干杂活，但花钱的事必须你点头。

> **Embeddable Go agent framework for business systems** — data analysis, workflow generation & execution,
> multi-agent, autonomous loops. English: [README_EN.md](README_EN.md) · 使用手册：[docs/manual_zh.md](docs/manual_zh.md) · Manual: [docs/manual_en.md](docs/manual_en.md)

---

## 这是什么？（30 秒版本）

想象你雇了一批 AI 员工帮你管生意：

- **采购员**每小时查一次库存，发现"茉莉奶绿只剩 2 箱"就写一张补货申请
- **参谋**接到"下月销量涨 20%"的目标，给你 3 套方案让你挑
- **分析师**你说"促销有没有用"，它查数据出报告

但他们有三条铁律：

1. **只看不花钱的事直接干**（查库存、查销量），**花钱的事必须先打请示单**（下单、调价），你批了才执行
2. **AI 只负责"想方案"，不负责"动手"** —— 方案变成一份写死的操作手册（脚本），由普通程序照着执行，每一步都留痕、可回放
3. **出事有总闸** —— 一键全停；AI 花钱有预算上限，超了直接拒绝

这就是 zAgent：上面这些能力做成一个 Go 库，`import` 进你的业务系统就能用。

## 核心思路：AI 出方案，程序来执行

普通 AI Agent 的做法是"让模型现场发挥"——每一步都问 LLM，它说什么就做什么。问题是：不可复现、没法审计、出错难查。

zAgent 反过来，把 AI 的工作压缩到**写方案**这一个环节：

```
AI（LLM）想方案 → 变成一份固定脚本（含用料清单）→ 人审批 → 普通引擎照着跑 → 每步记台账
   ↑ 便宜，错了重来                        ↑ 这一步之后没有 AI，结果每次都一样
```

为什么这么设计？三个理由：

- **可审计**：执行的脚本落盘带哈希，事后能查"当时到底跑了什么"，不是模型的一次性发挥
- **可重放**：同脚本同输入，结果必然一致（脚本里连取当前时间、随机数都不允许）
- **AI 没特权**：AI 写的脚本和人写的一视同仁，同样过审批、同样进沙箱

## 术语翻译表（读后面内容前先扫一眼）

| 文档里的词 | 大白话 |
|---|---|
| Kernel | 总开关/接线板：创建一个，全部能力就位 |
| artifact | 一份"工作说明书"：manifest（要用哪些工具）+ Lua 脚本（怎么干） |
| read / effect 工具 | 只读工具（直接执行）/ 写操作工具（先打请示单） |
| Proposal（提案） | 请示单：AI 想干一件花钱的事，人看清楚后批或不批 |
| 审批门（approval） | 处理请示单的流程：人看摘要和改动明细 → 批 / 驳回 |
| Species / Agent | 岗位类型（一份代码）/ 员工实例（按岗位雇的人，可以雇很多个） |
| 导诊台（concierge） | 编队顾问：你说模糊需求，它追问对齐、自己查数，出编组方案让你挑；挑完自动雇人 |
| 范式库 | 编组设计的套路知识：内置范式是框架资产；运行中归纳的新范式经你批准后入库生效 |
| Task / Plan | 任务清单 / 作战方案（含候选策略，人拍板选一个） |
| kill switch | 总闸：一键全停，恢复要人工确认 |
| fail-closed | 宁可不启动，也不带病运行：配置有疑点直接报错，绝不"猜着来" |
| ledger（账本） | 流水账：干过什么、谁批的，只追加不修改，事后可审计 |
| 预算熔断 | AI 花钱额度，超了直接拒绝调用（重启也不清零） |

## 我能用它做什么

| 场景 | 一句话 |
|---|---|
| **无人值守巡检** | 定时查库存/指标 → 异常自动写方案 → 人只管批 |
| **目标拆解** | 你只说目标，AI 出几套互斥方案让你挑，挑完自动拆成任务 |
| **数据分析** | 先"登记假设"再查数（防止挑数据凑结论），出带证据链的分析记录 |
| **编队顾问（导诊台）** | 说一句模糊需求 → 它追问对齐 → 自查工具目录取数（不限步数，重复动作自动熔断）→ 给 2~3 套物种编制方案让你挑 |
| **IM 接入** | 企微/钉钉里发指令 → AI 变成请示单 → 审批卡片推回群里 |
| **自主运转** | 定时器/事件叫醒 agent → 干活 → 自动验收 → 推进下一步（M1 自主循环） |

## 使用案例（全部调试通过，可直接 `go run`）

源码在 `examples/cases/`，每条命令都在仓库根目录实测跑通：

| 案例 | 一句话 | 运行 |
|---|---|---|
| **01 审批流** | 脚本查库存 → 不足 → 出补货请示单 → 人批准 → 真正下单 → 查流水账 | `go run ./examples/cases/01-approval` |
| **02 自主循环** | 三步任务自动逐级推进（干活 → 验收 → 下一步）→ 完成事件通知 → 急停演示 | `go run ./examples/cases/02-autopilot` |
| **03 自动重规划** | 原策略走不通 → 任务终结 + 重规划事件 → 换策略建新任务 → 走完全程 | `go run ./examples/cases/03-replan` |

每个案例都是独立 `package main`，零外部依赖（不需要 LLM key、不需要网络），
读完一个文件的代码就懂一个概念 —— **推荐按 01 → 02 → 03 顺序读**，正好是从
"AI 干活"到"AI 自主干活"的递进。

## 快速开始

要求 Go ≥ 1.26。

**作为库引入（业务系统嵌入）：**

```bash
go get gitee.com/cpsoft13/z-agent@v0.1.0
```

**克隆源码体验：**

```bash
git clone git@gitee.com:cpsoft13/z-agent.git && cd zAgent
go test ./...                                    # 跑测试确认环境 OK

# 零网络验证（不用 API key，30 秒）
go run ./cmd/zagent -config examples/config.json -demo \
  -validate examples/replenish/manifest.json examples/replenish/script.lua

# 浏览器完整演示（推荐首次体验）
./run-web.sh         # 打开 http://localhost:8090（根路径即闭环演示工作台）
# 对话式体验
./run-chat.sh
```

`run-web.sh` 的演示流程：点一个按钮 → "采购员"每 6 秒查一次库存 → 发现不足 → "参谋"调真实
LLM 写补货方案 → 浏览器里你点 Approve → 业务面板出现补货单 → 点"收货"库存回升。
全程可急停、可查账。LLM key 在网页顶部「大模型配置」直接填（也可选配 `.env.local`，参考 `.env.example`）。

## 嵌入到你的系统

**方式一：配置文件驱动（推荐，几乎零代码）**

```go
import "gitee.com/cpsoft13/z-agent"

cfg, _ := zagent.LoadConfig("config.json")        // 配置里声明：用哪些工具、雇哪些岗位
k, _   := zagent.NewFromConfig(cfg, zagent.Fns{}) // 创建总开关
res := k.Execute(ctx, manifest, luaSrc, inputs)   // 试跑：读操作真执行，写操作变请示单
k.Approve(ctx, res.Proposals[0].ID)               // 你点头 → 真正写到业务系统
```

工具两种接法：

- `type: "http"`：框架内置执行器，你只需在配置里写 URL（写操作审批后 POST，带防重复键）
- `type: "fn"`：你自己在 Go 代码里写实现，从 `Fns` 注入（配了没实现 → 拒绝启动）

两个工具字段建议都配上：`desc`（工具用途的人话说明）——框架会自动注册 `tool_catalog`
元工具把全部工具的 name/kind/desc 提供给导诊台，**它自己决定用什么数据**，宿主不用预配场景清单。

**方式二：代码装配** `zagent.New(Options{...})`，工具全在你进程内时用。

**多 agent + 自主循环：**

```go
sp, _ := k.Swarm()   // 多 agent 空间：注册岗位、雇人、隔离域

sp.RegisterSpecies(&swarm.Species{
    Name: "observer/tea-sale",
    Inject: []swarm.ServiceKey{swarm.SvTools},
    Apply: func(ctx *swarm.AgentCtx, cfg any) error {
        ctx.Every(time.Minute, observe)   // 每分钟巡检一次
        return nil
    },
})
sp.Spawn("observer/tea-sale", "obs-001", "tea", cfg)

// 自主循环：定时/事件叫醒 → 执行 → 验收 → 推进/重新规划
d, _ := k.Autopilot(myRunner, myEvaluator, tasks, plans)
d.Start(ctx)
```

## 目录结构（每个包一句话）

```
zAgent/
├── zagent.go        总开关：Kernel 装配（加载配置 / 创建 / 多agent / 自主循环）
├── pkg/
│   ├── agent/       AI 员工本体：角色 + 目标 + 工具 + "想方案"的生成循环
│   ├── llm/         调大模型的唯一出口（OpenAI 兼容协议，DeepSeek 等都能接）
│   ├── config/      配置层：配置里写了什么就有什么，多一个未知字段都拒绝
│   ├── engine/      Lua 引擎：死循环写不出来、随机数不存在 → 结果可重放
│   ├── artifact/    工作说明书校验：用料清单和脚本对不上就拒
│   ├── exec/        执行面：AI 写的脚本在这里的沙箱里跑，每步记台账
│   ├── approval/    请示单流程：打单 → 看明细 → 批/驳 → 执行（可设有效期、金额分级）
│   ├── guard/       护栏：总闸 / 限速 / 连续 3 次被驳回自动停职
│   ├── swarm/       多 agent 空间：岗位(插件) ↔ 员工实例 + 调度器 + 事件总线
│   ├── species/     六个参考岗位：观察员/参谋/执行员/规划师/文书/顾问（示例，可自造）
│   ├── task/        任务清单：目标→策略→步骤，按序推进 + 依赖关系
│   ├── plan/        方案留痕：候选策略互斥、人拍板才生效
│   ├── loop/        自主循环：叫醒 → 干活 → 验收 → 推进/重规划
│   ├── discovery/   数据分析治理：先登记假设，再对冻结数据副本做只读分析
│   ├── memory/      记忆：成功经验归档，下次干同类活自动翻出来参考
│   ├── cost/        AI 花钱账本：每一笔都记账，超预算直接拒绝
│   ├── channel/     IM 接入：企微/钉钉/自有 App 的桥接范式
│   ├── bus/         持久化消息总线（M8）：agent 间异步通信——落库先于投递、
│   │                at-least-once、死信可见、精确重试唤醒；SvBus 缝接入 swarm
│   ├── web/         Web 面：RPC + 事件流 + 可直接嵌前端的现成组件
│   └── biz/         演示用的假业务端（茶饮连锁 mock，不是框架能力）
├── examples/        配置示例 + 补货示例（含"恶意脚本"反例，看防线怎么拦）
└── cmd/             zagent（校验/执行 CLI）· chat（对话 REPL）
```

## 安全机制一览（为什么敢让 AI 碰生产系统）

| 机制 | 大白话 |
|---|---|
| 审批门 | 花钱的事先出请示单：人看到"要干什么、改什么、多少钱"，批了才动 |
| 防重复 | 同一单重复提交自动去重，重放等于没发生（业务端也不会重复下单） |
| 有效期 | 请示单有 TTL，放着不批自动作废 |
| 金额分级 | 超过设定金额的，强制升级人工确认 |
| 3-拒停职 | 同一方案连续 3 次被驳回 → 自动挂起，防止"换个说法再试"绕过人 |
| 总闸 | kill switch 一键全停；恢复必须人显式操作 |
| 预算熔断 | AI 每次调用记账，超额度直接拒绝，重启不清零 |
| fail-closed | 配置有疑点（未知字段、缺依赖、缺裁判）→ 拒绝启动，绝不带病运行 |

## 路线图

1. ✅ 执行/审批/护栏 · 多 agent 空间 · 调度器 · 状态落盘
2. ✅ 目标→策略→计划 · 任务依赖 · 人工选优 · 配置化岗位
3. ✅ Web 面与前端组件 · 数据发现 · 记忆 · 顾问台
4. ✅ 成本账本 · IM 渠道 · 岗位包
5. ✅ **自主循环**（叫醒/执行/验收/重规划闭环）
6. ✅ **导诊台自进化**（工具目录自发现 · 归纳范式提案 · 人审批准入库生效）
7. ✅ **持久化消息总线**（agent 间异步通信：`k.MessageBus` 一行装配 · 物种 `ctx.Post`/`ctx.OnBusMessage`）
8. 待做：断点续跑（进程重启从中间恢复）· 审批分级自治 · WebSocket 双向通道

## 文档

- **使用手册（中文，推荐从这里开始）**：[docs/manual_zh.md](docs/manual_zh.md) —— 从"跑起来"到"嵌入开发"，含配置逐字段说明和故障排查
- User Manual (English): [docs/manual_en.md](docs/manual_en.md)
- English README: [README_EN.md](README_EN.md)
- 设计文档：`docs/m4-plugin-multi-agent-design.html`（多 agent 插件式设计）

## 许可

[MIT](LICENSE) —— 可自由商用、修改、二次分发；不提供任何担保。