Model + Harness = Agent。这是一个开源的 Agent Harness 客户端 / 桌面交互前端： 用一套真正的执行框架（循环 / 规划 / 工具 / 权限 / 记忆 / 状态 / 轨迹）把模型组织起来， 让模型从「聊天」变成「交付」，同时用桌宠形态把执行过程"表演"给用户看。 可作为 DeepSeek Harness 生态的客户端交互层。
「布诺」是中国石油大学（北京）克拉玛依校区红山湖里的蓝精灵——本体是三亿年前古海里活下来的蓝细菌，一部分族人变成了石油，另一部分漂进红山湖，一直活到今天。她不再只是"会聊天的玩具"——遇到复杂任务，她会拆计划、逐步执行、失败了自己反思重试、危险操作先问你再动手，并把每一步都记进执行轨迹。
| Harness 职责 | 本仓库的实现 | 状态 |
|---|---|---|
| 任务流程 | 轻量 Planner 拆多步计划，逐步执行、可中途修正 | ✅ 已实现 |
| 实时任务树 | 计划即数据：结构化任务树持久化，用户可中途修改，下个决策点生效 | ✅ 已实现 |
| 执行循环 | 思考→行动→观察→再思考；失败反思重试（限次防死循环） | ✅ 已实现 |
| 工具 | 可插拔注册表 + 标准 MCP 客户端 + 内置工具 | ✅ 已实现 |
| 权限 | 危险操作（写文件/开网页/网络）默认先询问用户 | ✅ 已实现 |
| 上下文 | 短期 / 长期（SQLite）/ 工作区三层记忆；超窗摘要压缩 | ✅ 已实现 |
| 状态 | 任务生命周期 created→running→waiting→done/failed/cancelled，可中断、可恢复 | ✅ 已实现 |
| 日志/校验 | 完整执行轨迹 trace（think/tool/retry/approval），JSON 导出 | ✅ 已实现 |
| 人机交接 | 审批弹窗挂起任务，等待用户决定 | ✅ 已实现 |
| 主动行为 | 定时任务到点主动开口干活（proactive） | ✅ 已实现 |
| 人格 | 可插拔人格（JSON），不只语气、还影响行为偏好 | ✅ 已实现 |
| 可视化 | 桌宠状态机（思考💭/干活🔧/等待❓/失败😿）+ 过程表演 | ✅ 已实现 |
执行层
- Agentic loop：工具调用循环，模型自主决策并基于真实结果回复
- 轻量 Planner：复杂请求拆成多步计划，逐步执行，步骤间累计上下文
- 失败反思重试：工具出错时把错误回填模型，调整策略重试（默认最多 2 次）
- 任务可中断（
/cancel）、可恢复（/resume <id>，重启后继续）
Web 前端（可视化）
webui.py纯标准库 HTTP 服务 + 免构建页面：聊天、实时任务树（含「跳过」按钮）、 trace 时间线、工具清单、审批横幅、记忆查看/清空python webui.py --mock浏览器打开 http://127.0.0.1:8765 即可体验，无需 API Key
实时任务树（树即计划）
- Planner 输出结构化任务树并随任务持久化（
tasks/<id>.json）， 不再是 LLM 上下文里的一段文字——树就是计划本身 - agentic loop 每一步从树读取「当前节点」执行：
pending → in_progress → done / failed / cancelled - 用户中途修改：
/plan/skip <id>/reorder <id1> before <id2>/edit <id> <新描述>/cancel <id>（从该步截断剩余执行路径） - 修改先暂存，在下一个决策点（当前工具调用返回后）应用到树， 并把「修改后的整棵树 + 修改说明」重新注入 LLM 上下文——改树 = 改数据， agent 下一步就按新树走
- 节点失败超过重试上限 → 标记
failed→ 自动触发 replan（revise_plan， 限 3 次防止死循环） - 每次节点状态变更 / 用户修改都写入 trace（
node_status/user_edit事件） - 桌宠只显示「当前面包屑」（根 → 当前节点路径），如 🔄 正在做「扫描文件夹」
工具层
- 标准 MCP（Model Context Protocol）stdio 客户端，支持多服务器
- 工具白名单 + 审批门：
safe / ask / deny三级权限，危险操作先问用户 - 统一超时（默认 30s）、错误捕获、结果截断（默认 1500 字符）
- 可插拔注册表：一行注册新工具；内置时间/计算/工作区记忆/失败演示工具
记忆与上下文
- 三层记忆：短期（会话消息）/ 长期（SQLite 偏好+事实）/ 工作区（任务中间产物）
- 上下文窗口管理：超窗时对早期内容做 LLM 摘要压缩（失败降级为截断）
- 记忆可查看/添加/清空（CLI
/memory，桌宠可对话感知）
状态与可观测
- 任务状态机 + JSON 持久化（
tasks/），中途状态全部落盘 - 定时/触发式任务（
/schedule add HH:MM 描述，桌宠到点主动开口） - 执行轨迹 trace：think / tool_call / retry / approval / step 全记录，JSON 导出
人格与桌宠
- 人格独立为
personas/*.json，可热切换（自带 布诺/傲娇/温柔 三个示例） - traits 影响行为：
tool_likeness（爱不爱用工具）、caution（谨慎度） - 状态指示灯 + 失败汗颜表情 + 审批弹窗 + 定时任务主动汇报
- OpenAI / Anthropic Provider（
LLMProvider接口已预留） - MCP HTTP / SSE 传输（当前仅 stdio）
- 记忆向量检索与自动摘要归档（当前为 SQLite + 关键词注入）
- 可视化拖拽式任务树编辑器（v2；当前为 CLI 命令
/skip /reorder /edit /cancel） - Ren'Py 叙事联动（
agent_core为纯 Python、无 UI 依赖，便于对接） - 语音输入 / trace 可视化看板
需要 Python 3.10+（MCP 官方 SDK 要求；3.9 可跑纯聊天，MCP 降级禁用）。
python -m pip install -r requirements.txt
copy config.example.json config.json # Windows；macOS/Linux 用 cp编辑 config.json 填入 DeepSeek API Key（或用环境变量 DEEPSEEK_API_KEY /
旧版 api_key.txt）。配置自带一个本地示例 MCP 服务器（文件/备忘录/日历/天气）。
python demo_agent.py --mock # 无 Key：演示 规划/失败重试/审批/工作区 全链路
python demo_agent.py # 真实 DeepSeek + MCP + 记忆 + trace
python oc.py # 桌面桌宠（或双击 run.bat）
python webui.py --mock # Web 前端：聊天 + 实时任务树 + trace（浏览器打开 http://127.0.0.1:8765）运行内置测试（零依赖，覆盖任务树与 Harness 核心链路）：
python -m unittest discover tests -vCLI 命令：/tools /memory /tasks /resume <id> /cancel /trace <id>
/export <id> /schedule add|list|rm /persona list|switch <id> /help
任务树命令：/plan /skip <id> /reorder <id1> before <id2>
/edit <id> <新描述> /cancel <id>（裸 /cancel 仍是取消整个任务）
.
├── oc.py # 桌宠 UI：状态机表演/审批弹窗/人格切换/主动开口
├── demo_agent.py # CLI demo：任务管理/调度/人格/审批队列
├── webui.py # Web 前端：聊天/实时任务树/trace/审批/记忆
├── web/ # Web 前端静态页面（HTML/CSS/JS，无构建步骤）
├── agent_core/ # Agent Harness 核心库（与 UI 解耦）
│ ├── config.py # 配置加载
│ ├── core/ # 执行层
│ │ ├── harness.py # Harness 门面（chat/resume/cancel/trace/调度）
│ │ ├── loop.py # agentic loop（思考→行动→观察→反思重试）
│ │ ├── planner.py # 轻量 Planner（输出任务树 / 失败重规划）
│ │ ├── tree.py # 实时任务树（树即计划：状态机/编辑/渲染）
│ │ ├── context.py # 分层记忆 + 上下文摘要压缩
│ │ ├── state.py # 任务状态机 + JSON 持久化/恢复
│ │ ├── scheduler.py # 定时任务
│ │ └── trace.py # 执行轨迹 + JSON 导出
│ ├── tools/ # 工具层
│ │ ├── registry.py # 可插拔注册表（超时/截断/错误捕获）
│ │ ├── permissions.py # 白名单 + 审批门
│ │ ├── mcp.py # 标准 MCP stdio 客户端
│ │ └── builtin.py # 内置工具（含工作区记忆）
│ ├── memory/store.py # SQLite 长期记忆
│ ├── persona/ # 人格系统（manager + prompt）
│ ├── llm/ # Provider 接口 + DeepSeek
│ └── ...
├── personas/ # 人格配置（buno / tsundere / gentle）
├── examples/mcp_servers/ # 示例 MCP 服务器（FastMCP）
├── config.example.json
├── requirements.txt
├── ARCHITECTURE.md # 模块协作说明
└── readme.md # 桌宠应用内帮助
用户 ──> UI（桌宠/CLI）──> Harness.chat
│
┌─────────────────────┼──────────────────────┐
▼ ▼ ▼
Planner（拆计划） AgentLoop（循环） Context（记忆+压缩）
│ │ │
└───────── 逐步执行 ──┼── 工具层 ──> MCP 服务器 / 内置工具
│ └─ 审批门（human-in-the-loop）
│
任务树（树即计划）
│ 每步读当前节点 / 用户修改下个决策点生效
▼
trace（轨迹）──> JSON 导出
task 状态 ──> tasks/ 持久化 ──> resume 恢复
小石子> please plan a task with two steps
💭 布诺思考中… → ⚙️ get_datetime → ⚙️ save_memo → 最终回答
（Planner 拆出 3 步并逐步执行）
小石子> flaky retry test
😿 工具失败了 → 🔄 布诺反思后重试 → 成功
（失败反思重试链路）
小石子> write a file please
[审批] 工具「write_file」需要你的批准 → y/N
（human-in-the-loop：批准才执行）
### 实时任务树 · 中途修改（--mock 即可复现）
```text
小石子> please plan a long task with five steps and execute them
💭 布诺思考中… → ⚙️ slow_step（扫描文件夹）…… ← 1.5s 耗时步骤，留出修改窗口
小石子> /skip n2 → [已暂存] 将在下一个决策点生效
小石子> /reorder n4 before n3 → [已暂存] ...
小石子> /plan
任务树
✓ n1 扫描文件夹
⊘ n2 读取报告草稿 ← 已被跳过
▶ n4 生成总结报告 ← 当前执行到这里（顺序已调整）
○ n3 整理要点
○ n5 发送通知
布诺> （步骤完成）已按新树继续…… ← 修改生效：新树已注入 LLM 上下文
布诺> （演示）最终回答：任务完成！已按修改后的新任务树执行～
## 致谢与说明
- 「布诺」为原创角色，出自作者制作的校园宣传 Galgame《石克郎的夏天》
（[GitHub](https://github.com/Zhishulo/ShiKeLangSummer)），人设与世界观版权归作者所有。
- 仓库内立绘素材为本地个人素材（当前作为占位使用，尚未随角色一并替换）；
如需公开发布或商用，请自行确认素材版权。