docs: 会议室架构规划 + MSN hourlyforecast 端点更新
- 新增 docs/会议室架构计划书.md 完整架构方案(主持者+子Agent+task+cache+记忆) - 更新 taolun.md 追加 2026-05-11 讨论历史 - 更新 AGENTS.md 规范(type, cache 字段) - 更新 architecture.md 后续演进章节 - 更新 changelog.md 架构规划里程碑 - 修复 MSN 天气接口文档:新增 hourlyforecast,标记 weathertrends 已失效 - 更新 skills/msn-weather-api/SKILL.md 新增 hourlyforecast 端点 - 更新 agents/weather-agent.md 支持逐小时查询
This commit is contained in:
@@ -242,3 +242,90 @@ Markdown 渲染器完成 AST 解析后,需要确定标题的终端展示风格
|
||||
### 验证
|
||||
- 19/19 单元测试通过
|
||||
- 构建成功,二进制运行正常
|
||||
|
||||
---
|
||||
|
||||
## 2026-05-11 会议室架构:从单 Agent 到主-从调度
|
||||
|
||||
### 背景
|
||||
用户发现 `weathertrends` 接口失效,逐小时数据缺失。在排查中意外发现 `hourlyforecast` 端点存在且正常工作,文档之前遗漏了。同时回顾了与天气 Agent 的对话,发现 Agent 汇报 MSN 接口"国内城市不可用"的判断有误——实际 `assets.msn.cn` 按经纬度查一直正常,Agent 用的是 `api.msn.cn` 城市名接口(其文档本就标注"北京返回了也门萨那")。
|
||||
|
||||
这暴露了单 Agent 架构的局限性:Agent 的自我判断不可靠,上下文一多就容易出偏差。
|
||||
|
||||
### 讨论历程
|
||||
|
||||
#### 从"PicoClaw 为什么崩"出发
|
||||
|
||||
| PicoClaw 痛点 | 原因 |
|
||||
|--------------|------|
|
||||
| 上下文污染 | 所有知识/工具/历史全混在同一个 system prompt |
|
||||
| Skill 污染 | skill 内联大量技术细节,退化为长 prompt |
|
||||
| 逃避执行 | LLM 倾向"自己回答"而非调工具 |
|
||||
| 扩展困难 | 加能力 = 改代码或改长 prompt |
|
||||
|
||||
用户想从 0 实现一个干净的架构,先在云枢上验证,再移植到 HxClaw(河虾Claw)。
|
||||
|
||||
#### 方案演进
|
||||
|
||||
| 轮次 | 方案 | 问题 |
|
||||
|------|------|------|
|
||||
| 1 | CLI 切换主 Agent(`--agent weather/earthquake`) | 家庭用户记不住命令,跨域查询(火山附近天气)没法做 |
|
||||
| 2 | 唯一对话入口 + task 调度子 Agent | 但担心记忆管理和上下文混乱 |
|
||||
| 3 | 命名空间隔离记忆 | 无法共享用户画像(住通州 → 查地震也要知道住通州) |
|
||||
| 4 | **会议室模式**(最终方案) | 共享黑板(记忆)+ 主持者 + 发言人,角色隔离而非数据隔离 |
|
||||
|
||||
#### 关键设计决策
|
||||
|
||||
1. **主 Agent 即对话 Agent**(`type: main`),用户唯一入口,扮演"个人助理"角色
|
||||
2. **子 Agent**(`type: sub`)是领域专家,被 `task` 工具调才说话,不直接面对用户
|
||||
3. **`task` 工具**负责:加载子 Agent → 查/写缓存 → 调子 Agent LLM → 返回文本
|
||||
4. **Cache 机制**:Frontmatter 声明 `cache.keys`,`task` 工具机械化拼 key、查/写文件
|
||||
5. **记忆管理员**(`memory` 子 Agent):负责从对话中提取用户画像,写入记忆数据库
|
||||
6. **所有子 Agent 回答经过对话 Agent 返回给用户**,保持单一入口
|
||||
|
||||
#### 最终角色定义
|
||||
|
||||
| Agent | type | 职责 | 工具 | 缓存 |
|
||||
|-------|------|------|------|------|
|
||||
| dialog | main | 入口 + 聊天 + 调度 | `task`, `memory.read/write` | 无(本身就是对话历史) |
|
||||
| weather | sub | 查天气 | `http-get`, `geocode`, `skill` | `keys: [city, forecast_type]`, ttl: 7200 |
|
||||
| earthquake | sub | 查地震 | `http-get`, `skill` | `keys: [region]`, ttl: 300 |
|
||||
| memory | sub | 管理画像/长期记忆 | 读 memory.db | 无 |
|
||||
| narrator | sub(成熟期) | 格式化回答 | `memory.read` | 无 |
|
||||
|
||||
#### Cache 设计
|
||||
|
||||
```json
|
||||
// ~/.config/yunshu/cache/weather.json
|
||||
{
|
||||
"<hash_of_keys>": {
|
||||
"created_at": "2026-05-11T06:00:00+08:00",
|
||||
"ttl": 7200,
|
||||
"data": {...}, // 原始 API 数据
|
||||
"raw": {"city": "北京", "forecast_type": "today"} // 原始参数
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 子 Agent 每次回答末尾可选带 `---CACHE---` + JSON(只在数据更新时带)
|
||||
- `task` 工具查缓存:HIT → 把 `cache.data` 作为 `cache_data` 传给子 Agent;MISS → 子 Agent 自己查 API
|
||||
- 一个 Agent 一个缓存 JSON 文件,里面一个 map,key 是 hash
|
||||
|
||||
#### 会话存储
|
||||
|
||||
| 类型 | 位置 | 内容 | 生命周期 |
|
||||
|------|------|------|---------|
|
||||
| 对话历史 | `session.json` | 只存 user <-> dialog 的消息 | 每次启动清空 |
|
||||
| 子 Agent 内部 | 临时 | tool_calls、LLM 调用 | 用完即毁 |
|
||||
| 长期记忆 | 记忆数据库 | 用户画像、偏好、异常记录 | 持久 |
|
||||
|
||||
#### 对比结论
|
||||
|
||||
| | PicoClaw | 新方案 |
|
||||
|---|---|---|
|
||||
| 架构 | 单 Agent 全能 | 1 主持 + N 领域专家 |
|
||||
| 上下文 | 全混在 system prompt | Host 只有人格+调度,Sub 只有领域 |
|
||||
| 扩展 | 改代码或改长 prompt | 加一个 `.md` 文件 |
|
||||
| 记忆 | 无 | 共享黑板,Memory Agent 管写入 |
|
||||
| 工具污染 | 所有工具混在一起 | 按角色过滤 |
|
||||
| 失败影响 | 一个坏 tool_call 可能污染全部 | 子 Agent 用完即毁 |
|
||||
|
||||
Reference in New Issue
Block a user