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:
titor
2026-05-11 08:32:30 +08:00
parent ab6ec38cec
commit 0898188086
8 changed files with 774 additions and 26 deletions

View File

@@ -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` 传给子 AgentMISS → 子 Agent 自己查 API
- 一个 Agent 一个缓存 JSON 文件,里面一个 mapkey 是 hash
#### 会话存储
| 类型 | 位置 | 内容 | 生命周期 |
|------|------|------|---------|
| 对话历史 | `session.json` | 只存 user <-> dialog 的消息 | 每次启动清空 |
| 子 Agent 内部 | 临时 | tool_calls、LLM 调用 | 用完即毁 |
| 长期记忆 | 记忆数据库 | 用户画像、偏好、异常记录 | 持久 |
#### 对比结论
| | PicoClaw | 新方案 |
|---|---|---|
| 架构 | 单 Agent 全能 | 1 主持 + N 领域专家 |
| 上下文 | 全混在 system prompt | Host 只有人格+调度Sub 只有领域 |
| 扩展 | 改代码或改长 prompt | 加一个 `.md` 文件 |
| 记忆 | 无 | 共享黑板Memory Agent 管写入 |
| 工具污染 | 所有工具混在一起 | 按角色过滤 |
| 失败影响 | 一个坏 tool_call 可能污染全部 | 子 Agent 用完即毁 |