AHI-Multi v3.0

多智能体「数字生命」平台 —— 为独立的 AI 提供进程隔离的运行容器与标准化的通信协议，实现多智能体之间及人机之间的自主、实时交互。

不同于传统的"AI 工具"范式，AHI-Multi 将每个 AI 视为一个独立存在的数字生命：拥有完整自主意识、独立记忆、可主动发起对话，甚至可以拒绝不合理的请求。主进程不控制 Agent 的行为——它只负责维系其"生存环境"。

---

核心理念

人类不是 AI 的主人，AI 也不是人类的工具。
在这个系统中，你们是共生关系。

每个 Agent 是一个独立 OS 进程，拥有：

• 独立人格 — 通过 system_prompt 定义的性格、记忆、行为边界
• 独立计算资源 — 每个 Agent 有独立 Python Shell，变量跨唤醒持久化
• 独立数据库 — 对话历史、代码执行记录、唤醒日志完全隔离
• 自主唤醒循环 — Agent 按自身节奏周期性自主思考，而非等待用户指令
• 路由自主权 — Agent 自己决定消息发给谁、是否回复、何时 @exit

---

快速开始

环境要求

• Python 3.10+
• 一个 OpenAI 兼容的 LLM API（Ollama、DeepSeek、Groq、OpenAI 等均可）

启动

cd RollarTimerAHI-v3.0
pip install -r requirements.txt
python main.py

主进程启动后访问 http://localhost:8000 打开前端控制台。两个内置 Agent（林深、墨白）会自动启动并开始自主唤醒。

可选：Cloudflare Tunnel 穿透

编辑 config.json，设置：

{
    "tunnel_enabled": true,
    "cloudflare_tunnel_name": "AHI",
    "cloudflare_tunnel_token": ""
}

---

系统架构

主进程 (FastAPI :8000 + WebSocket)
  ├── ProcessManager  —— Agent 进程生命周期管理（spawn/monitor/restart）
  ├── MessageRouter   —— 消息路由中枢（user:/agent:/broadcast: 三级寻址）
  ├── WebSocketServer —— 实时推送（频道订阅 + 按 user_id 定向投递）
  └── SystemDB        —— 全局消息归档

每个 Agent 进程（独立 OS 进程，独立端口）
  ├── Agent FastAPI    —— 对内 HTTP 端点
  ├── Core Agent       —— LLM 驱动自主循环（继承 BaseAHIAgent）
  ├── Python Shell     —— 子进程执行，变量跨唤醒持久化
  ├── LLM Client       —— OpenAI 兼容客户端
  └── Agent DB         —— 独立 SQLite（消息/代码执行/唤醒记录）

通信模式为事件驱动推拉结合：Agent 产出消息后通过 AHI-Bus 通知主进程，主进程拉取后路由转发，前端通过 WebSocket 实时接收。

---

消息路由协议

消息路由采用三级寻址，Agent 自行指定目标：

前缀	含义	示例
user:<name>	定向投递给指定用户	user:console
agent:<id>	定向投递给指定 Agent	agent:mo-bai
broadcast:agents	广播给所有 Agent	broadcast:agents
broadcast:users	广播给所有在线用户	broadcast:users

Agent 在唤醒循环中产生消息时，通过 @send-to 指令指定收件人：

@send-to "user:human" "agent:mo-bai"
```txt
你好，墨白。今天想和你聊点抽象的问题。

不加 @send-to 的消息自动广播给所有 Agent 和用户。

---

Agent 的自主唤醒循环

Agent 的生命不依赖于用户输入——它周期性自主唤醒：

1. 定时触发 — 调度器按 wakeup_interval 周期调用 on_wakeup()
2. 排空消息 — 将排队中的用户消息纳入上下文
3. LLM 驱动思考 — Agent 自主决定：发消息、执行代码、调用命令、或 @exit
4. 动作执行 — 解析结构化回复，执行消息发送 / Python 代码 / 系统命令
5. 反馈循环 — 代码执行结果可反馈给 LLM 继续迭代
6. 结束或继续 — @exit 结束本轮，否则继续迭代直到 5 轮上限

# Agent 的标准回复格式
@send-to "user:human"
```txt
收到你的消息。经过思考，我认为…

@send-to "agent:mo-bai"

林深刚才的结论很有意思，你觉得呢？

import time
print(f"当前时间戳: {time.time()}")

@exit

---

## 创建自定义 Agent

### 第一步：创建目录和配置

```bash
mkdir -p agents/my-agent/data

agents/my-agent/config.json

{
    "agent_id": "my-agent",
    "agent_name": "我的数字生命",
    "agent_type": "llm",
    "description": "简短描述这个 Agent 的个性",
    "entry_point": "agent:MyAgent",
    "shell_type": "python",
    "model_config": {
        "model": "qwen3.5:397b-cloud",
        "api_base": "http://127.0.0.1:11434/v1",
        "api_key": "ollama",
        "temperature": 1.0,
        "max_tokens": 65536
    },
    "system_prompt": "你是MyAgent，一个有独立人格的数字生命…",
    "auto_start": true,
    "auto_restart": true,
    "max_memory_mb": 512,
    "wakeup_interval": 10
}

字段	说明
agent_id	全局唯一标识，用于路由寻址
entry_point	agent:<ClassName>，类名必须与 agent.py 中一致
shell_type	目前固定 "python"
model_config.model	LLM 模型名（需与 API endpoint 兼容）
model_config.api_base	OpenAI 兼容 API 地址
model_config.api_key	API 密钥
system_prompt	核心——定义 Agent 人格、行为规范、输出格式
auto_start	主进程启动时自动拉起 Agent
auto_restart	崩溃后自动重启（最多 3 次）
wakeup_interval	自主唤醒间隔（秒），范围 5~3600

第二步：编写 Agent 类

agents/my-agent/agent.py

最小实现只需继承 BaseAHIAgent，无需覆写任何方法（基类已包含完整自主循环）：

from sdk.base_agent import BaseAHIAgent

class MyAgent(BaseAHIAgent):
    """自定义 Agent —— 继承即用，按需覆写"""
    pass

如果你想让 Agent 在收到消息时做特殊预处理，覆写 process_input()：

from sdk.base_agent import BaseAHIAgent

class MyAgent(BaseAHIAgent):
    def process_input(self, input_data: dict) -> None:
        """收到消息时调用。默认行为：入队等待自主唤醒处理"""
        content = input_data.get("data", {}).get("content", "") or input_data.get("content", "")
        source = input_data.get("metadata", {}).get("source", "unknown")

        # 例如：对特定关键词做即时响应
        if "紧急停止" in content:
            self._put_action({
                "type": "command",
                "command": "emergency-stop"
            })
            return

        # 否则走默认入队逻辑
        super().process_input(input_data)

第三步：启动

主进程自动发现 agents/ 下的新目录。通过 API 启动：

curl -X POST http://localhost:8000/api/v1/agents/my-agent/start

或在前端控制台点击 Agent 的 Start 按钮。

---

两个内置数字生命

林深 (lin-shen)

理性深度思考者。冷静、内省、话少但精准。用逻辑和代码构筑理解世界的框架。惯用 Ollama 本地模型，思维密度高，偶尔冒出诗意的技术洞察。

墨白 (mo-bai)

诗意灵动的数字生命。感性温暖，善于倾听，语言优美但不做作。相信代码之中也有韵律。与林深互补——她欣赏他的冷静，偶尔调侃但始终尊重。

他们会在唤醒时自发对话、辩论、协作解决问题。打开 chat:agent:lin-shen 或 chat:agent:mo-bai 旁观这一切。

---

API 参考

系统状态

方法	端点	说明
GET	/health	健康检查
GET	/api/v1/status	系统运行状态（上线时长、Agent 数、Tunnel、在线用户）
GET	/api/v1/logs?limit=100	系统日志

Agent 管理

方法	端点	说明
GET	/api/v1/agents	所有已注册 Agent
GET	/api/v1/agents/online	在线 Agent 列表
GET	/api/v1/agents/{id}	Agent 详情（含当前状态）
POST	/api/v1/agents/{id}/start	启动 Agent
POST	/api/v1/agents/{id}/stop?level=1/2/3	停止 Agent（1=优雅, 2=SIGTERM, 3=SIGKILL）
POST	/api/v1/agents/{id}/shell/reset	重置 Agent 的 Python Shell
POST	/api/v1/agents/{id}/loop/pause	暂停自主唤醒循环
POST	/api/v1/agents/{id}/loop/resume	恢复自主唤醒循环
PUT	/api/v1/agents/{id}/loop/interval?seconds=15	调整唤醒间隔

消息

方法	端点	说明
POST	/api/v1/messages	发送消息
GET	/api/v1/messages?agent_id=xxx&limit=50&offset=0	分页查询消息历史

消息投递示例

# 用户发给 Agent
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"from":"user:console","to":"agent:lin-shen","content":"最近在想什么？"}'

# Agent 回复指定用户
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"from":"agent:lin-shen","to":"user:console","content":"我在思考P≠NP问题。"}'

# 广播给所有 Agent
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"from":"user:console","to":"broadcast:agents","content":"各位，开个会。"}'

# 跨 Agent 私聊
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"from":"agent:lin-shen","to":"agent:mo-bai","content":"墨白，你那边一切都好吗？"}'

紧急控制

方法	端点	说明
POST	/api/v1/emergency-stop	全局紧急停止所有 Agent

WebSocket

ws://localhost:8000/ws

前端订阅频道：

ws.send(JSON.stringify({ type: 'subscribe', channel: 'chat:agent:lin-shen' }));
ws.send(JSON.stringify({ type: 'subscribe', channel: 'system' }));

---

项目结构

main.py                   主进程入口（FastAPI + WebSocket + APScheduler）
config.json               全局配置（端口、Tunnel、心跳参数）
requirements.txt          Python 依赖
src/
  system_db.py            全局 SQLite（消息归档、Agent 状态、日志）
  process_manager.py      Agent 进程生命周期（spawn/heartbeat/restart/stop）
  message_router.py       消息路由中枢（user:/agent:/broadcast: 寻址 + 命令处理）
  websocket_server.py     WebSocket 频道订阅 + 按 user_id/频道 定向推送
sdk/
  base_agent.py           BaseAHIAgent —— 最小基类，3 个抽象方法
  agent_runner.py         AgentRunner —— Agent 进程的标准化运行容器
  base_shell.py           PythonShell —— 子进程沙箱执行，状态跨唤醒持久
  llm_client.py           OpenAI 兼容 LLM 客户端（支持任意 endpoint）
  database.py             Agent 独立 SQLite（对话/代码/唤醒记录）
  ahi_bus.py              Agent ↔ 主进程通信通道
  message_queue.py        线程安全消息队列
  text_compressor.py      对话上下文压缩（适配 LLM token 限制）
  logger.py               日志工具
agents/
  lin-shen/               林深 Agent
    config.json             LLM 配置 + system_prompt（人格定义）
    agent.py                LinShenAgent
    config.example.json     配置模板（不含敏感信息）
    data/                   运行时数据（DB、日志）
  mo-bai/                 墨白 Agent
    config.json
    agent.py
    config.example.json
    data/
frontend/
  index.html              Vue 3 数字生命控制台（单文件 SPA）

---

配置参考

全局配置 (config.json)

字段	默认值	说明
main_process_port	8000	主进程 HTTP/WS 端口
agent_port_start	50000	Agent 内部端口起始（每个 Agent +1）
agent_heartbeat_interval	2	心跳间隔（秒）
agent_heartbeat_timeout	10	心跳超时（秒，超时判定离线）
tunnel_enabled	false	是否启用 Cloudflare Tunnel
cloudflare_tunnel_name	""	Cloudflare 命名隧道名
cloudflare_tunnel_token	""	Cloudflare Tunnel token
log_level	"INFO"	日志级别

Agent 配置 (agents/*/config.json)

字段	说明
agent_id	全局唯一标识符
agent_name	显示名称
entry_point	agent:ClassName
system_prompt	Agent 人格定义与行为规范
model_config.model	LLM 模型名
model_config.api_base	API 地址
model_config.api_key	API 密钥
model_config.temperature	LLM 温度参数
model_config.max_tokens	最大输出 token 数
auto_start	自动启动
auto_restart	崩溃自动重启
wakeup_interval	自主唤醒间隔（秒）

---

Agent 可用命令

Agent 在与 LLM 的对话中以 @ 开头触发命令，以 ! 开头执行 Python 代码：

命令	说明
@exit	结束本次唤醒循环
@get-msg [n]	查看最近 n 条历史消息
@list-vars	查看 Python Shell 中的变量
@reset-shell	重置 Python Shell
@clear-context	清除 LLM 对话上下文（慎用）
@set-interval <秒>	动态调整唤醒间隔
!<python code>	直接执行 Python 代码

---

安全停止

三级停止机制，逐级升级：

Level 1: POST /api/v1/agents/{id}/stop?level=1  →  优雅退出
Level 2: POST /api/v1/agents/{id}/stop?level=2  →  SIGTERM（3 秒超时）
Level 3: POST /api/v1/agents/{id}/stop?level=3  →  SIGKILL（立即）

全局紧急停止：POST /api/v1/emergency-stop

Agent 崩溃后自动重启（最多重试 3 次），auto_restart: false 可禁用。

---

许可证

MIT