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:
@@ -24,34 +24,70 @@
|
||||
## Agent 定义规范(.md 文件)
|
||||
|
||||
- 必须包含 YAML frontmatter(以 `---` 包裹)
|
||||
- frontmatter 必需字段:`name`, `description`, `tools`
|
||||
- frontmatter 必需字段:`name`, `description`, `type`, `tools`
|
||||
- `type` 可选值:`main`(主持者/对话 Agent,唯一入口)、`sub`(领域专家,被 task 调)
|
||||
- `cache` 可选字段:`ttl`(过期秒数)、`keys`(从 args 中提取的缓存 key 字段列表)
|
||||
- tools 为数组,声明 agent 需要的工具名(在 tool.go 中注册)
|
||||
- body 为 system prompt,**只定义行为逻辑**(角色、工作流程、输出规范)
|
||||
- **关键技术细节(URL、apiKey、请求头、JSON 路径等)不要 inline 在 agent skill 中**,改为:
|
||||
- 放到 `skills/*/SKILL.md` 中,由 agent 调用 `skill("name")` 按需加载
|
||||
- 或注册为 tool(确定性操作),由 agent 声明 tools 即可调用
|
||||
- session 文件存在 `~/.config/weather-cli/session.json`,不污染项目目录
|
||||
- session 文件存在 `~/.config/yunshu/session.json`,不污染项目目录
|
||||
|
||||
### 示例
|
||||
### 主持者示例(type: main)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: weather-agent
|
||||
description: 天气情报官
|
||||
name: dialog
|
||||
type: main
|
||||
description: 个人助理,负责闲聊和调度
|
||||
tools:
|
||||
- task
|
||||
- memory.read
|
||||
- memory.write
|
||||
---
|
||||
|
||||
# 对话助理
|
||||
你是用户的私人助理...
|
||||
|
||||
你可以调度以下子 Agent:
|
||||
- weather: 天气查询
|
||||
- earthquake: 地震信息
|
||||
|
||||
用 task("agent_name", {args}) 调度。
|
||||
不自己回答领域问题。
|
||||
```
|
||||
|
||||
### 子 Agent 示例(type: sub)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: weather
|
||||
type: sub
|
||||
description: 天气查询专家
|
||||
cache:
|
||||
ttl: 7200
|
||||
keys: ["city", "forecast_type"]
|
||||
tools:
|
||||
- http-get
|
||||
- geocode
|
||||
- skill
|
||||
---
|
||||
|
||||
# 天气情报官
|
||||
你是专业的天气情报官。
|
||||
# 天气专家
|
||||
你是天气领域的专家。被调时才回答。
|
||||
|
||||
## 工作流程
|
||||
1. 识别城市 → 调用 geocode 获取坐标
|
||||
2. 调用 skill("msn-weather-api") 获取 API 参数
|
||||
3. 调用 http-get 请求天气数据
|
||||
4. 分析并输出
|
||||
被调时你会收到:
|
||||
- args: 查询参数
|
||||
- cache_data: 上次缓存的原始数据(有时)
|
||||
|
||||
有 cache_data 且未过期 → 直接回答,不调 API。
|
||||
无 cache_data → 调 http-get 获取新数据。
|
||||
|
||||
返回格式:
|
||||
你的回答文本
|
||||
---CACHE---(只有数据更新时带)
|
||||
{原始 JSON 数据}
|
||||
```
|
||||
|
||||
## Session 规范
|
||||
@@ -127,3 +163,15 @@ tools:
|
||||
2. **ANSI 光标移动需要启用输出 VT 处理**:`\033[A`(光标上移)/ `\033[J`(清屏)等输出序列需要输出句柄设置 `ENABLE_VIRTUAL_TERMINAL_PROCESSING`(0x0004)才能生效。只设置输入句柄的 mode 不够,输入输出句柄是两个独立的控制台句柄。
|
||||
|
||||
3. **ReadLineWithCompletion / Completer 类型已移除**。`completer.go` 清空,`main.go` 回到 `termui.ReadLine()`。`cmdCompleter`、`commonPrefix`、相关测试一并移除。`input.go` 中 `ReadConsoleInputW` 相关的 `keyEventRecord`/`inputRecord` 结构和 proc 也一并清理。
|
||||
|
||||
### 2026-05-11
|
||||
|
||||
1. **MSN 天气存在 `hourlyforecast` 端点**:`https://assets.msn.cn/service/weather/hourlyforecast`,返回未来 10 天逐小时预报数据,参数和 dailyforecast 一致。之前文档遗漏了该端点。`weathertrends` 端点已失效(500 Internal Server Error)。
|
||||
|
||||
2. **MSN 的 `assets.msn.cn` 国内城市接口正常**:用经纬度查询 `assets.msn.cn/service/weather/current` 对国内城市返回正确数据。之前 Agent 误报"返回也门数据"是因为用了 `api.msn.cn` 的城市名接口(该接口本就有文档标注的问题:城市名匹配不可靠)。**用 `assets.msn.cn` + 经纬度即可正常获取国内城市数据,不需要切换到 wttr.in。**
|
||||
|
||||
3. **会议室架构决策**:确定从单 Agent 升级为 1 主持(dialog, type:main)+ N 领域专家(type:sub)+ 共享黑板(memory)的架构。主持者保持极薄(只有人格 + 调度规则 + `task` + `memory` 工具),子 Agent 只做领域工作,用完即毁。详见 `docs/会议室架构计划书.md`。
|
||||
|
||||
4. **Cache 设计原则**:Frontmatter 声明 `cache.keys` 和 `cache.ttl`,`task` 工具机械化从 args 取值拼 key、查/写缓存。子 Agent 不感知缓存存在,只需在回答末尾可选带 `---CACHE---` + JSON 供 task 存储。一个 Agent 一个缓存 JSON 文件,MD5 hash 做 key。
|
||||
|
||||
5. **记忆系统规则**:共享黑板模式,所有 Agent 可读,仅 memory Agent 可写。dialog-agent 是最小写入者(只写 `dialog_context`),memory Agent 负责从对话中提取用户画像写入长期记忆。
|
||||
|
||||
Reference in New Issue
Block a user