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`