emperor-agent

用户下旨，主智能体（"大内总管"）统筹上下文、工具、记忆与子代理；把任务拆解、执行、校验后回禀。 项目重点不是教学材料，而是一个可持续演进的个人 Agent 工程。

✨ 快速开始

1. Python 后端

python -m venv .venv
source .venv/bin/activate                 # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .                           # 提供 emperor-agent 命令

emperor-agent init                         # 终端向导配置 provider / model / WebUI 参数
# 也可以使用：python agent.py init

2. CLI 模式

emperor-agent chat
# 兼容入口：python agent.py

常用命令：

emperor-agent status
emperor-agent doctor
emperor-agent web --host 127.0.0.1 --port 8765 --open

启动时若发现热 memory/history.jsonl 中有活跃对话，会先调用模型做一次启动压缩。

3. WebUI 模式

WebUI 用 Vue 3 + Vite + Tailwind + vue-router 构建，首次使用前必须先打包前端产物：

cd webui
npm install
npm run build              # 产出 webui/dist/
cd ..
emperor-agent web --open
# 兼容入口：python webui.py
# 浏览器打开 http://127.0.0.1:8765

后端 aiohttp 服务器把 webui/dist/ 作为 SPA 静态资源托管，并代理 /api/* 与 /ws。前端开发模式可以另起 cd webui && npm run dev（Vite 5173），并配 proxy 指到 8765。

4. 可选桌宠

桌宠 companion 默认关闭。首次使用需单独安装 Electron 依赖，然后在 WebUI「配置文件」页开启，或用 CLI 管理：

cd desktop-pet
npm install
cd ..

emperor-agent pet status
emperor-agent pet start
emperor-agent pet stop
emperor-agent pet restart

桌宠窗口位置写入 memory/desktop_pet/window.json；运行时会用顶部气泡展示简短动作摘要，不显示用户原文或工具参数。若 Electron 依赖缺失，WebUI 只显示安装命令，不会影响主服务启动。

5. 质量检查

开发环境建议安装 dev 依赖：

.venv/bin/python -m pip install -r requirements-dev.txt
make check

make check 会调用 scripts/check.sh，固定执行 git diff --check、Python 编译、ruff、pytest 和 WebUI build。需要同时查看本地配置、依赖、持久化状态时可运行：

emperor-agent doctor --dev

🧧 首次启动会发生什么

memory/、templates/USER.local.md、model_config.json、emperor.local.json、webui/dist/、webui/node_modules/、desktop-pet/node_modules/ 都被 .gitignore 排除，所以新克隆的仓库是干净的。首次启动会自动从仓库内的初始化模板生成本地副本：

只要按"快速开始"两步走，引导链路就完整了，无需再手动建任何目录。

⚔️ 核心能力

• 多轮对话 — 保留当前会话工作记忆；流式 delta 与工具事件实时显示。
• 三层记忆 — 工作记忆（history）、情景记忆（memory/YYYY-MM-DD.md）、长期记忆（memory/MEMORY.local.md）协同运转。
• 自动压缩 — 上下文超过阈值时把旧对话归档为情景记忆，并刷新长期记忆与用户档案。
• 记忆版本回滚 — 长期记忆、用户档案与每日情景记忆写入前自动保存轻量快照；Memory 页和 /memory-log / /memory-restore 可查看 diff 并恢复。
• 多厂家 + 双模型路由 — DeepSeek、Anthropic、OpenAI、Azure OpenAI、AWS Bedrock、OpenRouter、DashScope（阿里云）、SiliconFlow、Ollama、vLLM、OpenAI Codex、GitHub Copilot 与自定义 OpenAI-compatible endpoint；每个 entry 同时配置主模型与次模型，简单任务自动走次模型，失败后升主模型一次。
• MCP 外部工具 — 通过 stdio 或 SSE 连接外部 MCP 服务器，自动发现工具并注册为 mcp_{server}_{tool}，与内置工具统一调度。
• 流式 WebUI — 网页聊天通过 WebSocket 接收 message_delta、tool_call、tool_result、subagent_* 等事件；活跃行为事件持久化到 memory/runtime/events.jsonl，旧事件进入 memory/runtime/archive/*.jsonl.gz，刷新或后端重启后按 seq 回放未压缩会话细节；Scheduler 主动 turn 会显示为中性的“定时任务触发”卡片，不伪装成用户消息；Chat 停止按钮与 /stop 会通过统一 active task registry 取消当前 turn / Scheduler run / Watchlist check。
• 三模式权限与 Ask / Plan 控制流 — 默认 ask_before_edit 会在危险或不确定动作前审批；auto 走最高自动权限；plan 只允许只读探索、提问和提交 PlanCard，批准或取消后恢复进入 Plan 前的模式。
• 本地 Scheduler — 持久保存 at / every / cron 任务，启动 WebUI 后后台 timer 自动恢复；支持触发本地主动 Agent turn、Team wake 与系统维护 heartbeat；Agent 可通过 scheduler 工具查看任务，创建/修改/删除/手动运行长期任务会走权限审批。
• Watchlist Heartbeat — memory/watchlist.md 记录希望系统主动留意的事项；受保护的 watchlist-check 定期用次模型判断 skip/run，只有必要时才投递完整主动 turn。
• External Bridge 基础 — agent/external/ 提供通用外部平台适配骨架、入站去重、inbox/outbox 状态和 runtime 事件；当前不内置任何具体平台实现。外部消息只会汇入唯一主线，不创建多会话、不暴露 session_id。
• Token 统计 — 按日期、provider/model、使用种类（main_agent / subagent / memory_compaction）汇总，并按“输入缓存命中 / 输入缓存未命中 / 输出 / 总 Token”展示。
• 工具调用 — 命令执行、网页抓取、文件读写、Glob/Grep 搜索、技能加载、todo 维护、子代理派遣。
• 任务规划 — 内置 todolist，未完成时自动 nudge 模型继续执行。
• 子代理派遣 — 把独立任务交给不同身份的子代理（独立 history、独立工具白名单），结果摘要回填主上下文，多个子代理可并发派遣。
• Agent Team — Lead 可召入持久队友，队友拥有 .team/ 下独立 inbox、thread、状态和 WebUI 工作台；v1 采用“按消息唤醒”，不启动后台常驻轮询。
• 技能系统 — 按需加载 skills/ 下的能力包，避免一开始塞满 system prompt。
• 桌宠 Companion — 可选 Electron 悬浮桌宠，开启后用 Clawd Tank 像素动画与顶部短气泡实时展示 Agent 思考、工具调用、子代理、Ask / Plan、完成与错误状态；默认关闭，可在 WebUI 或 CLI 启停。
• 历史保护 — runner._pair_tool_calls 保证 OpenAI 格式 history 中 assistant tool_calls 与 tool 消息严格配对，运行时异常或压缩切边都不会污染下一次请求。
• 上下文治理 — 每次 LLM 调用前自动跑两步：单条工具结果硬截断（_cap_tool_result，留头尾，默认 8KB 上限）+ 旧大体积工具消息摘要化（_shrink_old_tool_results，最近 10 条保留原文，更早的替换为 [shrunk] name → N chars omitted）。让长对话从 8-10 轮稳定到 30+ 轮不撞 token 上限。
• LLM 错误恢复 — step_async 内置两个状态机：模型偶发空响应时自动注入 nudge 重试（≤2 次）；finish_reason="length" / "max_tokens" 时自动续写并拼接（≤3 次）。前端通过既有 tool_error 事件可见 _empty_response / _length_truncation 提示。
• 中断恢复 Checkpoint — MemoryStore.write_checkpoint 在每次工具批次完成后把 history 原子写到 memory/_checkpoint.json（gitignore），关 tab / Ctrl-C / 模型超时都不丢。AgentLoop 启动时 read_checkpoint 优先于 history.jsonl 未归档段恢复 in-memory history，再 clear_checkpoint；_pair_tool_calls 兜底处理任何 orphan tool_call。turn 正常落地时自动清理。
• 对话附件 — Composer 支持点选 / 拖拽上传图片（png / jpeg / webp / gif，≤10MB）和文档（pdf / json / csv / text / markdown，≤25MB），单条消息至多 5 个。文件落盘到 memory/attachments/YYYY-MM/{hash8}-{name}.{ext}，PDF 与文本文档同步抽取 sidecar 文本（pypdf），发消息时按 OpenAI 多模态格式装配 user content：vision-capable entry 走 image_url block，否则替换为占位提示；文档总把抽出的文本内联进 prompt，并在末尾附落盘路径供 read_file 兜底读取。User 多模态消息在 cap/shrink 链上原样保留，不会被截断；WebUI 刷新恢复时只显示用户原话与附件卡片，不把模型侧提取文本 / 落盘说明塞回气泡。
• 视觉徽章 + 连通测试 — /model 编辑器内置「测试文本」「测试视觉」两个按钮：发一次最小 ping 或一张内置 2×2 红色 PNG 探测图，返回延迟、模型名、响应 sample。视觉测试通过会自动把 entry.supports_vision = true 持久化到 model_config.json，entry 列表立刻在该条目右侧显示视觉能力像素徽章；Composer 的附件按钮 tooltip 与图片上传路径都依据该徽章决定走视觉链还是占位文字。

🏯 项目结构

agent.py                        CLI 兼容入口（转发到 agent.cli）
webui.py                        WebUI 启动入口

agent/
├── loop.py                     主循环、组件装配、CLI 命令处理
├── cli.py                      Python CLI 命令入口：init / chat / web / status / doctor / pet
├── onboarding.py               Rich + Questionary 初始化向导、doctor 检查、配置构造
├── local_config.py             emperor.local.json 本地偏好读写
├── model_router.py             主/次模型路由：main_agent、memory、subagent、team 的模型选择与 fallback
├── runner.py                   单轮执行编排、tool_use 循环、并发安全工具组合、tool_call 配对保护、上下文治理（cap/shrink）、空响应+截断重试
├── runner_factory.py           子代理 / Team runner 构造入口，集中套用模型路由快照与 fallback
├── runner_model.py             ModelCaller：模型调用、流式 delta、次模型失败后升主模型一次
├── memory.py                   三层记忆存储、未归档历史载入、中断恢复 checkpoint
├── memory_versions.py          记忆快照、diff 与 restore，本地存储在 memory/versions/
├── attachments.py              附件落盘 + mime 校验 + PDF/文本抽取 + 引用反查（LRU）
├── compactor.py                历史压缩与长期记忆 / 用户档案更新
├── model_config.py             多 provider 模型配置读写
├── context.py                  system prompt 组装（SOUL.md / TOOL.md / USER.md / MEMORY / Skills）
├── control/                    Ask / Plan 会话控制：pending interaction、暂停/恢复、Ask Guard
├── permissions/                Claude Code 风格三模式权限策略：ask_before_edit / auto / plan
├── runtime/                    WebUI 行为事件冷记录、event payload、seq replay
├── scheduler/                  本地长期自动运行中枢：job store / timer service / scheduler tool
├── desktop_pet/                可选 Electron 桌宠进程管理、pid