titor/YunShu

Fork 0

Files

titor a6025c699f init: 云枢·Agent 初始提交

2026-05-08 10:12:31 +08:00

6.6 KiB

Raw Permalink Blame History

讨论历史

2026-05-07 项目启动与架构设计

背景

用户有一个 MSN天气API探索报告.md 文档，记录了通过抓包发现的微软 MSN 天气内部 API（assets.msn.cn），该 API 国内访问速度快，数据完整（温度、湿度、风速、AQI、紫外线等），但属于非公开接口，无 SLA 保证。

目标演变

最初目标：做一个"天气情报官" agent，后期结合 TTS 和 ASR 实现语音查询播报
深化：用户想从 0 实现一个类似 opencode 主-从架构的个人 AI 助理，解决现有单 agent 框架（zeroclaw/picoclaw）的痛点：上下文污染、工具执行懒惰、skill 效果差
当前范围：先做一个最小化的 CLI 天气查询工具，验证 .md 外挂 agent 定义 + session 会话管理 + 工具注册表机制

架构决策

为什么不用现有框架（LangChain 等）

核心创新是 .md 文件即 agent 定义，与任何框架都耦合不上
自实现核心 ~500 行，无外部依赖包袱

Agent 定义格式（仿 opencode）

YAML frontmatter + Markdown body
frontmatter 字段：name, description, type, tools, permission
body 即 system prompt，定义角色行为

Session 会话机制

session.json 文件存对话历史，格式兼容 OpenAI Chat Completion API messages 数组
每次启动清空，每轮对话追加
追问时 LLM 自动判断是否需要重新调 API（数据过期/不同城市）
通用设计，后续 master-subagent 架构也可复用

LLM 提供商

用户提供豆包（火山引擎）API：https://ark.cn-beijing.volces.com/api/v3
模型：doubao-seed-2-0-pro-260215
环境变量可配置：LLM_ENDPOINT, LLM_MODEL, LLM_API_KEY

工具系统

声明式注册：tool.go 注册工具，.md 文件声明即可用
内置工具：http-get, skill, read-file
skill 工具按需加载，不预置到 system prompt

Windows 编码问题

PowerShell 输出编码为 GB2312，Go 输出 UTF-8 导致中文乱码
通过 kernel32.SetConsoleOutputCP(65001) 设置控制台 CP 为 UTF-8
在 PowerShell 中需额外执行 [Console]::OutputEncoding = [Text.Encoding]::UTF8

项目结构（最终）

weather/
├── main.go                    # CLI 入口
├── types.go                   # 核心类型
├── loader.go                  # .md 解析 + skill 加载
├── llm.go                     # LLM API 封装（默认豆包）
├── tool.go                    # 工具注册表
├── runtime.go                 # agent 循环 + session
├── agents/
│   └── weather-agent.md       # 天气情报官定义
├── skills/
│   └── msn-weather-api/SKILL.md
├── data/
│   └── cities.json            # 42 个中国城市
├── taolun.md                  # 本文件
├── changelog.md               # 版本变更
└── agents.md                  # 编码规范

验证结果

单次查询：.\weather-agent.exe "北京今天天气" → 成功返回温度、湿度、AQI 等
交互模式：启动后连续追问 → session.json 记录历史，LLM 基于上下文回答"适合穿什么"
豆包 API 工具调用正常：自动读取 cities.json → 调 MSN API → 分析输出

2026-05-07 项目重命名与配置体系

变更

项目重命名：weather-agent → weather-cia（CIA = 天气情报官）
配置体系：~/.config/weather-cli/config.yaml 统一管理 LLM 配置
初始化方式：weather-cia onboard 交互式向导，替代手动写配置文件
双路径搜索：项目目录优先 + ~/.config/weather-cli/ 后备

关键决策

用 config.yaml 而非 .env/.secret：YAML 风格与 agent 定义一致，API Key 用 0600 权限保护
配置优先级：环境变量 > 配置文件 > 默认值（init() 中依次加载）
onboard 子命令：交互式 TTY 输入，自动复制默认 agents/skills/data 到全局目录
搜索路径：SearchFile() 统一管理，开发者用项目文件，用户用全局配置

验证

weather-cia onboard 成功创建 ~/.config/weather-cli/config.yaml
weather-cia "北京今天天气" 无需环境变量，直接读取配置文件中的豆包 key 并成功返回天气数据
全局配置目录自动包含 agents/、skills/、data/ 的完整副本

2026-05-07 架构分离：Agent Skill vs 普通 Skill vs Tool

背景

参考了 picoclaw 的 weather skill 设计，对比发现：

picoclaw 的 skill 写得很完整（含验证规则、边界情况）
但我们的 weather-agent.md 之前 inline 了大量 API 细节 → 和 picoclaw 一样污染上下文

决策：三层分离

层	文件位置	加载时机	上下文影响
Agent skill	`agents/weather-agent.md`	启动即加载为 system prompt	全程
普通 skill	`skills/*/SKILL.md`	LLM 调用 `skill("name")` 时	仅该轮对话
Tool	`src/tool.go` 注册	预声明，LLM 调用时执行	仅返回结果文本

具体改造

新增 geocode tool（Go 代码）：
- 输入城市名，调 wttr.in ?format=j1 解析 JSON
- 返回 {lat, lon, name, country} 结构化数据
- 确定性执行，比 LLM 自己构造 URL 解析 JSON 更可靠
新建 skills/geocoding/SKILL.md：
- 纯知识：wttr.in 查询格式、JSON 解析路径
- 验证规则：同名城市检测、country 核对、population 排序
精简 agents/weather-agent.md：
- 去掉所有 MSN API URL、apiKey、请求头、JSON 路径等内联知识
- 改为行为描述：识别城市 → geocode → skill("msn-weather-api") → http-get → 分析
- 从 65 行缩减为 40 行，只留行为逻辑
session 移至 ~/.config/weather-cli/session.json

结果

Agent skill 保持瘦身，system prompt 不膨胀
知识按需加载，用完即走，不残留上下文
Tool 执行可靠，不依赖 LLM 的 JSON 解析能力
三种内容互不干扰，为后续主-从架构打下基础

2026-05-07 项目更名：云枢·Agent

变更

正式命名：云枢·Agent（YunShu / yunshu）
- 坐看云卷云舒，静听花开花落
配置目录迁移：~/.config/weather-cli/ → ~/.config/yunshu/（自动迁移）
二进制名称：yunshu
架构白皮书：~/Desktop/yunshu-architecture.md

设计理念

"云枢"二字呼应了项目作为 AI 助理"中枢调度"的定位——云是分布式的、流转的，枢是枢纽、核心。后续主-从架构中，master 负责调度、subagent 各司其职，恰如云卷云舒。

6.6 KiB Raw Permalink Blame History Unescape Escape