YunShu/docs/changelog.md

云枢·Agent 版本变更日志

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

[2.3.0] - 2026-05-16

日志系统 + 性能优化 + 安全加固

日志系统

引入 charmbracelet/log v2 作为结构化日志库，取代零散的 log.Printf / fmt.Fprintln(os.Stderr, ...)：

组件	说明
logger.go	charmbracelet/log 全局实例，输出到 stderr
log.go	log.yml 持久化（YAML 序列追加）、双写 wrapper、yunshu log 命令

日志流向：

warnLog/errorLog/infoLog
  ├─ logToStderr ? → charmbracelet/log → stderr（交互模式默认关闭，/log on 开启）
  └─ 始终写入 → appendLog → log.yml（YAML 序列，位于 ~/.config/yunshu/log.yml）

新增日志点：

[INFO] task(weather) 开始
[INFO] 子 Agent 开始  agent=weather
[INFO] LLM 调用完成  tokens=1420  duration=3.2s
[INFO] task(weather) 完成
[WARN] 解析缓存失败  agent=weather  err=...

yunshu log 子命令：

yunshu log              → 全量显示（时间倒序）
yunshu log --top N      → 只看最后 N 条
yunshu log --level warn → 过滤级别
yunshu log --clear      → 清空
yunshu log --watch      → 监听模式（2s 轮询）

流式输出

LLM 响应改为 SSE 流式输出，按 \n\n 段落边界缓冲后经 mdprint 渲染到 stdout：

组件	文件	说明
SSE 类型	llm.go	sseChunk/sseDelta/sseToolCallDelta 等
CallLLMStream	llm.go	请求加 stream: true，bufio.Reader 逐行解析
段落缓冲	llm.go	blockBuf + tryFlushBlocks：检测最后一个 \n\n，完成块过 mdprint，残段续传
流结束刷残段	llm.go	末尾 mdprint.Print(blockBuf) 兜底
重建响应	llm.go	tool_call 按 index 累积 + SSE 碎片合并

关键设计：

LLM SSE → blockBuf += content
          tryFlushBlocks:
            ├─ 有 \n\n → 之前的部分 mdprint.Print(complete)
            │            → 剩余部分留在 blockBuf
            └─ 无 \n\n → stay
流结束 → mdprint.Print(blockBuf)

Prompt 适配（agents/dialog-agent.md）：

• 新增"流式输出原则"：先调工具，不要先说话
• 调度表 回应 → task(profile) 改为 静默调 task，拿到结果后再回应

性能优化

优化	改动	效果
note-sub 一步完成	prompt 收紧：read→write→立即返回	note 保存从 ~50s 降至 ~10s
dialog 合并 obs+summary	单 Agent 查询跳过观察和摘要；综合查询合并为一轮	节省 ~30s
maxToolCalls=2	RunSubAgent 超限兜底	防止死循环

代码加固

改动	文件	说明
LLM 延迟加载	llm.go	init() → sync.Once，--help 不再读 config
路径安全检查	tool.go	safeMemoryPath()：Clean + EvalSymlinks + Rel 三段校验
静默错误 → warnLog	8 处 across runtime/tool/registry	所有 json.Unmarshal / yaml.Unmarshal 吞掉的错误改为结构化日志
对话记忆修剪	runtime.go	LoadSession 只返回最近 40 条消息
Onboard 补齐	onboard.go	ensureUserConfig() 创建 user.md/soul.md/notes/
热加载	main.go	交互模式每轮 ScanAgents()，新增 agent 即时生效

UX 改进

• 交互模式默认不显示日志（/log on 开启）
• --help 移除环境变量章节，增加 log 命令说明
• 单次查询模式保留日志显示

---

[2.2.0] - 2026-05-16

存储重组：session 目录 + .yml 统一后缀

目录结构调整

旧路径	新路径	原因
session.json	session/session.json	对话会话文件归入 session 目录
context/dialog.yaml	session/dialog.yml	context 语义模糊，与 session 合并；.yml 后缀
config.yaml	config.yml	统一后缀
log.yaml	log.yml	统一后缀
context/	已删除	文件移至 session/

所有 yaml 文件统一使用 .yml 后缀。配置文件、对话摘要、日志文件全部一致性调整。

代码改动

文件	改动
runtime.go	sessionPath() 改为 session/session.json
config.go	LoadConfig/SaveConfig 读写 config.yml
onboard.go	提示信息改为 config.yml
main.go	新增 migrateFilePaths() 处理所有旧路径迁移
tool.go	描述字符串更新 context/→session/，.yaml→.yml
agents/dialog-agent.md	所有 context/dialog.yaml→session/dialog.yml
docs/	存储树、写入策略、编码规范全部同步更新

迁移逻辑

migrateFilePaths() 在启动时自动处理：

• config.yaml → 复制到 config.yml，删除旧文件
• session.json → 复制到 session/session.json，删除旧文件
• context/dialog.yaml → 复制到 session/dialog.yml，删除旧文件及空目录
• log.yaml → 复制到 log.yml，删除旧文件

所有迁移仅在目标文件不存在时执行，支持幂等。

---

[2.1.0] - 2026-05-16

用户画像 + 备忘录系统

拆分 memory.json

旧的 memory.json 一锅烩，现在拆成按用途分文件：

旧文件	新文件	格式	维护者
memory.json["personality"]	config/soul.md	Markdown	用户手动编辑
memory.json["dialog_context"]	context/dialog.yaml	YAML	dialog 每轮写入
memory.json["agent_errors"]	log.yaml	YAML	系统追加
(不存在)	config/user.md	Markdown	profile-sub 维护
(不存在)	notes.md + notes/*.md	Markdown	note-sub 维护

迁移逻辑在 main.go:migrateMemoryJSON()，启动时自动检测并迁移，确认完成后再删除 memory.json。

新增子 Agent

Agent	文件	用途
profile-sub	agents/profile-sub.md	从对话中提取用户画像，增量合并到 config/user.md
note-sub	agents/note-sub.md	笔记管理。默认 notes.md 列表，复杂内容可存为 notes/{name}.md

memory.read/write 工具改造

从旧的 flat JSON key-value 改为路径路由：

• .md 文件 → 全文覆写（memory.write("config/user.md", markdown_str)）
• .yaml 文件 → 合并写入（memory.write("context/dialog.yaml", {topic, last_agent})）
• 目录 → 返回文件列表
• 安全检查：拦截 .. 遍历和绝对路径
• 目录自动创建

dialog-agent.md 更新

• 新增调度规则：检测用户透露个人信息 → 调 task("profile", ...) 提取画像
• 新增调度规则：检测"帮我记住" → 调 task("note", ...) 存备忘录
• 对话摘要改为写入 context/dialog.yaml，而非旧 memory.json["dialog_context"]
• 用户画像改为读取 config/user.md
• 新增观察规则：每轮回复后向 ## AI观察到 段写入语气/情绪/性格观察

heading-aware merge

memory.write 对 .md 文件由全文覆写改为按 ## 标题合并：

• memory.write("config/user.md", "## 画像\n...") 只替换 ## 画像 段，## AI观察到 段不受影响
• 同一 writer 可多次写入同一标题，每次覆盖该段内容
• 不同 writer 写不同标题，互不干扰
• 底层函数 mdMerge() 按 ## 拆分 → 标题匹配 → 重组

profile-sub.md 更新

• 改为写 ## 画像 段（不再写整篇 user.md）
• 文档规范化：给出 ## 画像 格式示例
• 强调不破坏其他段（## AI观察到 等）

---

发布会：会议室架构核心引擎就绪

架构规划：会议室模式（阶段一全部完成，超计划交付）

核心引擎

组件	文件	说明
Agent 注册中心	registry.go	ScanAgents() 按 type(main/sub) 分类，用户目录覆盖
子 Agent 隔离运行	runtime.go: RunSubAgent	隔离 LLM 循环，返回 ---RESULT---/---TEXT---
主 Agent 循环	runtime.go: RunAgent	session 持久化 + mdprint 渲染
缓存系统	runtime.go: cache 辅助	SHA256[:6] 拼 key，惰性过期
工具目录生成	catalog.go	GenerateToolsYAML、BuildSubAgentPrompt

新增工具

工具	注册方式	说明
task	NewTool[TaskInput]	调度子 Agent + 缓存管理
memory.read	NewTool[MemoryReadInput]	读 ~/.config/yunshu/memory.json
memory.write	NewTool[MemoryWriteInput]	写长期记忆，value 支持任意 JSON 类型

实际子 Agent

Agent	文件	状态
dialog-agent.md	agents/dialog-agent.md	主持者（type:main）含多步骤编排指令
weather-sub.md	agents/weather-sub.md	天气子 Agent（type:sub），Markdown 排版 + 生活建议

✨ 计划外新增

泛型 + 反射工具注册（toolschema.go）

受 Charmbracelet/Fantasy 启发，引入 NewTool[T any]() 泛型构造函数：

• 输入结构体 json/description/enum tags → 自动反射生成 JSON Schema
• 消除 ~120 行手写 Schema 模板代码（旧的 ToolParameter/ToolProperty 类型已删除）
• handler 内参数为类型安全的结构体字段，无需 args["x"].(string) 类型断言
• 支持嵌套结构体、slice、map、基础类型、interface{} 类型

多步骤编排（runtime 改造）

移除 capturedOutput 覆写机制，子 Agent 结果作为普通工具响应留在对话上下文中：

• 主 Agent 可以连续多次调 task()（weather → train → hotel）
• 每次返回后 LLM 继续推理，决定下一步
• 信息收集完毕再综合回答，不再被 capturedOutput 截断
• 单步骤查询（如纯天气）行为不变，LLM 按 prompt 指令直接输出子 Agent 结果

其他变更

• http-get.headers 从 JSON 字符串改为 map[string]string，LLM 直接传对象
• memory.write.value 从 string 改为 interface{}，直接存储任意 JSON 值
• types.go：删除旧的 ToolParameter/ToolProperty 结构体，新增 Schema(map[string]any) 类型
• catalog.go：buildToolList 适配新版 Schema
• agents/dialog-agent.md：加入多步骤编排指令 + 数据传递说明

文档更新

• docs/architecture.md：更新工具列表、核心流程、当前状态
• docs/AGENTS.md：工具注册规范更新为 NewTool[T] 方式
• docs/会议室架构计划书.md：添加实现状态标记、多步骤编排章节、泛型注册章节

---

架构规划：会议室模式

完成从单 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