0898188086
- 新增 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 支持逐小时查询
116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 云枢·Agent 架构参考
|
||
|
||
> 详细架构白皮书见 `~/Desktop/yunshu-architecture.md`
|
||
>
|
||
> 本文档为项目内部精简参考
|
||
|
||
## 项目命名
|
||
|
||
- **中文名**：云枢·Agent（坐看云卷云舒，静听花开花落）
|
||
- **英文名**：YunShu / yunshu
|
||
- **配置目录**：`~/.config/yunshu/`
|
||
|
||
## 三层分离架构
|
||
|
||
```
|
||
Agent Skill (agents/*.md) → 纯行为（~40行，全程在 system prompt）
|
||
普通 Skill (skills/*/SKILL.md) → 纯知识（按需加载，用完即走）
|
||
Tool (src/tool.go 注册) → 确定性执行（Go 代码，仅返回结果）
|
||
```
|
||
|
||
## 四种能力对比
|
||
|
||
| 维度 | Agent Skill | 普通 Skill | Tool | MCP |
|
||
|------|------------|-----------|------|-----|
|
||
| 本质 | 角色定义("我是谁") | 知识手册("怎么用") | 确定性执行("帮我做") | 外部服务("远程调用") |
|
||
| 加载方式 | 启动即加载 | `skill("name")` | 声明即注册 | 外部进程协议 |
|
||
| 上下文影响 | 全程 | 仅该轮 | 仅结果文本 | 同 tool |
|
||
| 实现形式 | .md frontmatter+body | .md body | Go 函数 | 外部 server |
|
||
|
||
## 判断准则
|
||
|
||
```
|
||
"做什么" → Agent Skill
|
||
"怎么做" → 继续问
|
||
"知识" → 普通 Skill
|
||
"操作" → 继续问
|
||
"本地操作" → Tool
|
||
"远程服务" → MCP
|
||
```
|
||
|
||
## 和 picoclaw 的关键区别
|
||
|
||
| | picoclaw | 云枢·Agent |
|
||
|---|---|---|
|
||
| 上下文 | 行为+知识+工具全堆在一起 | 三层分离，各司其职 |
|
||
| 角色 | 一个 prompt 塞 N 个角色 | 一个 agent = 一个角色 |
|
||
| 知识加载 | 预置或直接塞入 | 按需加载，仅该轮存在 |
|
||
| 工具执行 | 依赖 LLM 构造 URL 解析 JSON | Tool 用 Go 代码，100% 可靠 |
|
||
|
||
## 包结构
|
||
|
||
```
|
||
pkg/
|
||
├── mdprint/ Markdown → ANSI 终端渲染（AST 架构）
|
||
│ ├── mdprint.go Node 类型定义 + Print() 入口
|
||
│ ├── parse.go 块级解析器（状态机）
|
||
│ ├── inline.go 行内解析器（递归）
|
||
│ └── render.go ANSI 渲染器（type switch）
|
||
├── style/ 终端颜色样式库（8 色 ANSI + 24-bit 真彩色）
|
||
└── termui/ 终端交互（行输入、模式设置）
|
||
```
|
||
|
||
## 当前 tools
|
||
|
||
| 工具名 | 作用 | 实现 |
|
||
|--------|------|------|
|
||
| http-get | HTTP GET 请求 | Go |
|
||
| skill | 按需加载知识 | Go |
|
||
| geocode | 城市名 → 坐标 | Go（调 wttr.in） |
|
||
| read-file | 读取文件 | Go |
|
||
|
||
## 当前 tools
|
||
|
||
| 工具名 | 作用 | 实现 |
|
||
|--------|------|------|
|
||
| http-get | HTTP GET 请求 | Go |
|
||
| skill | 按需加载知识 | Go |
|
||
| geocode | 城市名 → 坐标 | Go（调 wttr.in） |
|
||
| read-file | 读取文件 | Go |
|
||
| task | 调度子 Agent（含缓存管理） | Go（阶段一新增） |
|
||
| memory.read | 读长期记忆 | Go（阶段一新增） |
|
||
| memory.write | 写长期记忆 | Go（阶段一新增） |
|
||
|
||
## 后续演进
|
||
|
||
### 当前（单 Agent）
|
||
```
|
||
yunshu (三层分离+单agent)
|
||
└─ weather-agent.md (type: main，既是入口也是天气专家)
|
||
```
|
||
|
||
### 阶段一（会议室架构基础）
|
||
```
|
||
yunshu (会议室架构)
|
||
├── dialog-agent.md (type: main，入口+调度)
|
||
├── weather-sub.md (type: sub，天气领域)
|
||
├── memory-sub.md (type: sub，记忆管理)
|
||
└── narrator-sub.md (type: sub，汇报员，成熟期)
|
||
```
|
||
|
||
### 阶段二（多领域扩展）→ 河虾 Claw
|
||
```
|
||
yunshu / hxclaw (多领域主-从)
|
||
├── dialog-agent.md (type: main，入口+调度)
|
||
├── weather-sub.md (type: sub，天气)
|
||
├── earthquake-sub.md (type: sub，地震)
|
||
├── volcano-sub.md (type: sub，火山)
|
||
├── nuclear-sub.md (type: sub，核电监测)
|
||
├── memory-sub.md (type: sub，记忆)
|
||
└── narrator-sub.md (type: sub，汇报)
|
||
```
|
||
|
||
## 架构文档
|
||
|
||
详细架构计划见 `docs/会议室架构计划书.md`。
|