init: 云枢·Agent 初始提交

docs/architecture.md

@@ -0,0 +1,70 @@
+# 云枢·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
+```