YunShu/docs/changelog.md

云枢·Agent 版本变更日志

坐看云卷云舒，静听花开花落

[2.0.0-planning] - 2026-05-11

架构规划：会议室模式

完成从单 Agent 到"会议室架构"的完整设计，核心变更：

新增角色体系：

• type: main — 主持者（对话 Agent），唯一用户入口
• type: sub — 发言人（领域子 Agent），被 task 调才说话

新增工具（待实现）：

• task — 调度子 Agent + 缓存管理
• memory.read / memory.write — 长期记忆读写

新增 Cache 机制：

• 子 Agent Frontmatter 声明 cache.ttl + cache.keys
• task 工具机械化拼 key、查/写缓存
• 一个 Agent 一个缓存 JSON 文件，子 Agent 无感知

设计文档：

• docs/会议室架构计划书.md — 完整架构方案
• docs/architecture.md — 更新后续演进章节
• docs/AGENTS.md — 更新 Agent 定义规范（type, cache 字段）
• docs/taolun.md — 追加 2026-05-11 讨论历史

MSN 天气接口更新：

• 新增 hourlyforecast 端点文档
• 标记 weathertrends 为已失效
• 更新 skills/msn-weather-api/SKILL.md 和 agents/weather-agent.md

技术细节

• Frontmatter 新增 type 字段（main/sub）
• Frontmatter 新增 cache 字段（{ttl: int, keys: [string]}）
• 用户配置目录 ~/.config/yunshu/ 下可选覆盖 agents/
• 详见 docs/会议室架构计划书.md

[1.1.0] - 2026-05-09

发布摘要

第二版发布。核心变化：Markdown 渲染器从"一行流"重构为 AST 架构，新增终端视觉系统（标题符号 + Monet 配色），Go 版本升级至 1.25，项目结构从 src/ 扁平目录重组为根目录 + pkg/ 子包架构。

---

新增：pkg/mdprint — Markdown → ANSI 渲染引擎

从头编写的 AST 架构渲染引擎，替代原来的"一行流"字符串匹配逻辑：

块级解析（parse.go）：有限状态机逐行扫描，识别 7 种块级元素

类型	语法	解析策略
Heading	# ~ ######	前缀匹配，记录级别
CodeBlock	``` fence	状态切换，支持语言标识
Blockquote	> 前缀	前缀剥离，递归解析
List	- / * / 1.	前缀匹配，自动编号检测
Table	`	` 分隔
ThematicBreak	--- 独占一行	精确匹配
Paragraph	默认兜底	连续非空文本块合并

行内解析（inline.go）：递归下降扫描，支持 4 种行内元素嵌套

类型	语法	特性
Bold	**text**	可嵌套 Italic / Code / Link
Italic	*text*	可嵌套 Bold / Code / Link
Code	`text`	原始文本（内部不解析）
Link	[text](url)	text 可嵌套 Bold / Italic

ANSI 渲染（render.go）：type switch 按节点类型分发，标题按级别分配颜色和符号

测试覆盖：19 个单元测试，覆盖所有块级/行内类型的正常、边界和嵌套场景

---

新增：标题视觉系统

用符号 ▪ / ▫ 替代 Markdown 原生 # 前缀，视觉效果更接近"标题"而非"标记"：

级别	符号	字体	色彩（Monet 睡莲）	色值
H1	▪	加粗	雾蓝灰	#6B8E9B
H2	▪	加粗	鼠尾草绿	#89A894
H3	▪	加粗	薄荷青	#A6C0B5
H4	▫	加粗	淡紫粉	#C3B1BD
H5	▫	加粗	暖灰绿	#7B8E8A
H6	无	加粗(Dim)	浅灰	继承

排版规则：所有标题前插空行，H1 前后各插空行，--- 横线前后空行，响应与输入之间空行，输出末尾空行。

---

新增：pkg/style — 终端颜色样式库

在原有 8 色 ANSI 基础上新增 24-bit 真彩色支持：

• Fg(color) / Bg(color)：保留原有 8 色 API
• FgHex("#RRGGBB") / BgHex("#RRGGBB")：新增真彩色，输出 \033[38;2;R;G;Bm 格式
• 所有 .Render(text) 使用统一占位板 .codes []string，颜色和样式可组合
• NO_COLOR / TERM=dumb 环境变量自动禁用颜色

---

新增：pkg/termui — 终端输入组件

提供三个交互式输入函数，统一使用 bufio.NewReader(os.Stdin) + ensureLineMode() 解决 Windows 控制台输入问题：

函数	用途	特性
ReadLine()	基础行输入	去除 \r\n
TextInput()	文本输入	支持默认值、必填校验、自定义验证器
PasswordInput()	密码输入	输入后隐藏回显，用 * 遮盖
Confirm()	确认提示	支持 Y/n / y/N 默认值

---

修复

1. 行内解析器未闭合分隔符死循环：扫描 * / ` 分隔符时未处理文件末尾无闭合标记的情况，改为找到匹配闭合或到达末尾时终止
2. 代码 fence 不识语言标识：```go、```json 等带语言的 fence 被当作文本行，改为行首 ``` 后允许非空白后缀
3. Windows 控制台输入模式冲突：bufio.Scanner 在 Windows 控制台因 ENABLE_WINDOW_INPUT 标志导致 Scan() 永久阻塞。改为每轮输入前调用 GetConsoleMode + SetConsoleMode 确保模式为 ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT | ENABLE_PROCESSED_INPUT，并使用 bufio.NewReader.ReadString('\n') 替代 Scanner
4. 尝试自实现 Tab 补全未成功（后放弃）：raw mode + ReadConsoleInputW 方案遇到光标位置计算不一致问题，最终回退到简单 ReadLine()。后续如需补全功能引入第三方库

---

变更

• 项目结构重组：src/ 目录删除，全部 .go 文件移至根目录；新增 pkg/ 子包，按职责分离为 mdprint/、style/、termui/
• 模块名修改：yunshu → hub.gaomia.site/titor/YunShu
• Go 版本升级：1.21 → 1.25.0
• Completer 类型和 ReadLineWithCompletion 函数移除：completer.go 清空，相关测试删除
• .gitignore 修复：yunshu.exe → yunshu.exe*（避免调试版本遗漏）

---

技术栈

• 语言：Go 1.25.0
• 依赖：仅 gopkg.in/yaml.v3
• 默认 LLM：豆包（火山引擎）doubao-seed-2-0-pro-260215
• 数据源：MSN 天气非公开 API（assets.msn.cn）
• 运行平台：Windows 10+（基于 kernel32 控制台 API，ANSI VT 处理）
• 输入编码：UTF-8（通过 SetConsoleOutputCP(65001) 设置控制台代码页）

[1.0.0] - 2026-05-08

发布说明

第一个稳定发布版本。云枢·Agent 作为可独立运行的 Agent 系统，支持通过 LLM + 工具注册表 + 外挂 Agent 定义实现自然语言驱动的天气查询。

功能

• 三层分离架构：Agent Skill（行为）↔ 普通 Skill（知识）↔ Tool（确定性执行）
• 外挂 Agent 定义：.md 文件即 Agent，YAML frontmatter + Markdown body
• 4 个内置工具：http-get、skill、read-file、geocode
• Session 会话管理：~/.config/yunshu/session.json 持久化对话历史
• 交互模式 + 单次查询双模式运行
• onboard 交互式初始化向导
• 双路径搜索：项目目录优先，~/.config/yunshu/ 后备
• 旧配置自动迁移：~/.config/weather-cli/ → ~/.config/yunshu/
• LLM 配置：支持配置文件 + 环境变量双重配置，兼容 OpenAI Chat Completion API

技术栈

• 语言：Go 1.21
• 依赖：仅 gopkg.in/yaml.v3
• 默认 LLM：豆包（火山引擎）doubao-seed-2-0-pro-260215
• 数据源：MSN 天气非公开 API（assets.msn.cn）

[1.0.0-rc.1] - 2026-05-07

重大变更

• 项目更名：weather-cia → 云枢·Agent（英文名 YunShu / yunshu）
• 配置目录迁移：~/.config/weather-cli/ → ~/.config/yunshu/（自动迁移）
• 二进制名称改为 yunshu

[0.3.0] - 2026-05-07

新增

• geocode 工具：通过 wttr.in 查询城市坐标，支持中文和英文城市名
• skills/geocoding/SKILL.md：地理编码验证规则（同名城市检测、国家核对）
• 架构分离：agent skill 只放行为，普通 skill 只放知识，tool 负责确定性执行

变更

• agents/weather-agent.md 精简为纯行为定义（去掉所有 MSN API 内联细节，改为按需加载 skill）
• 城市定位方式：从静态 cities.json 查表 → 调用 geocode 工具实时查询
• agents/weather-agent.md tools 新增 geocode
• session 文件从项目目录移至 ~/.config/weather-cli/session.json

[0.2.0] - 2026-05-07

新增

• onboard 子命令：交互式初始化向导，引导用户配置 LLM 连接信息
• 全局配置文件 ~/.config/weather-cli/config.yaml，存储 LLM host/model/key
• 双路径搜索机制：项目目录优先，~/.config/weather-cli/ 后备
• 首次运行检测：未配置时提示用户运行 weather-cia onboard

变更

• 项目重命名为 weather-cia
• 配置加载改为：配置文件 → 环境变量（环境变量优先级更高）
• Agent/skill 搜索路径扩展：项目目录 → 全局配置目录
• onboard 自动复制默认 agents/skills/data 到全局配置目录

[0.1.0] - 2026-05-07

新增

• 项目初始化，基于 Go 实现的轻量级 agent 框架
• 核心架构：.md 文件定义 agent 行为，代码只负责加载和执行
• 工具系统：声明式注册（http-get, skill, read-file）
• Session 会话管理：session.json 记录对话历史，支持上下文追问
• 天气情报官 agent（weather-agent.md）：通过 MSN 天气 API 查询实时天气和预报
• MSN 天气 API Skill（msn-weather-api/SKILL.md）：API 知识按需加载
• 内置 42 个中国城市经纬度数据库（data/cities.json）
• 支持单次查询和交互模式两种运行方式
• 默认集成豆包（火山引擎）LLM，通过环境变量可切换

技术细节

• 语言：Go 1.21
• 依赖：仅 gopkg.in/yaml.v3（用于解析 frontmatter）
• API 兼容 OpenAI Chat Completion 格式
• 环境变量：OPENAI_API_KEY（必填）、LLM_ENDPOINT、LLM_MODEL