YunShu/docs/architecture.md

云枢·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% 可靠

当前 tools

工具名	作用	实现
http-get	HTTP GET 请求	Go
skill	按需加载知识	Go
geocode	城市名 → 坐标	Go（调 wttr.in）
read-file	读取文件	Go

后续演进

云枢·Agent (三层分离+单agent)
  ↓
河虾 claw (三层分离+主-从)
  ├─ master: 意图识别+任务分发
  ├─ weather-subagent
  ├─ tts-subagent
  ├─ asr-subagent
  └─ ...更多 subagent