# 2026-05-31 变更记录

## 移除 anyhow，全面使用 thiserror 自定义错误

### 变更内容
- 移除了主 crate `Cargo.toml` 中的 `anyhow` 依赖（`macros/` 与测试中的 `anyhow` 保留）。
- 在 `src/error.rs` 中扩展 `ServiceRuntimeError` 与 `ServiceStartError` 枚举，新增以下变体：
  - `ServiceRuntimeError::ChannelClosed` — 内部 channel 关闭
  - `ServiceRuntimeError::SerializeError(#[from] serde_json::Error)` — 序列化/反序列化失败
  - `ServiceRuntimeError::WebSocketClosedByPeer` — WebSocket 被对端关闭
  - `ServiceRuntimeError::WebSocketError` — WebSocket 错误
  - `ServiceRuntimeError::WebSocketStreamEnded` — WebSocket 流结束
  - `ServiceRuntimeError::EventSourceEnded` — SSE EventSource 结束
  - `ServiceRuntimeError::UrlCannotBeBase` — URL 无法添加 path segment
  - `ServiceRuntimeError::ReqwestError(#[from] reqwest::Error)` — HTTP 请求错误
  - `ServiceStartError::InvalidSecretLength(#[from] hmac::digest::InvalidLength)` — HMAC secret 长度非法
- 将 `src/communication/` 下各模块的 `anyhow::Result` 统一替换为 `ServiceRuntimeResult` 或 `ServiceStartResult`：
  - `src/communication/utils.rs`
  - `src/communication/ws_reverse.rs`
  - `src/communication/http.rs`
  - `src/communication/http_post.rs`
  - `src/communication/sse.rs`
  - `src/communication/combiner.rs`

### 影响
- 生产代码不再依赖 `anyhow`，错误类型更加明确，便于调用方做针对性处理。
- 保留 `macros/` 与示例中的 `anyhow`，不影响编译期宏和测试代码。

### 涉及文件
- `src/error.rs`
- `src/communication/utils.rs`
- `src/communication/ws_reverse.rs`
- `src/communication/http.rs`
- `src/communication/http_post.rs`
- `src/communication/sse.rs`
- `src/communication/combiner.rs`
- `Cargo.toml`
- `changelogs/2026-05-31.md`

## [docs] 规范化 Changelog rule 并新增会话隔离规则

### 变更内容
- 全面重写 `AGENTS.md` 中的 `Changelog rule` 章节，将其升级为正式规范
- 新增文件命名规则、文件结构模板、标题层级规范
- 定义统一的变更类型体系（基于 git commit message type），支持多类型复用
- 定义文件修改类型体系（[Added] / [Changed] / [Removed] / [Moved]）
- 新增**会话隔离规则**：禁止修改已存在的历史 changelog 条目，当前会话只能向当天文件追加新条目
- 新增完整示例，展示规范格式

### 涉及文件
- `AGENTS.md` [Changed] 将 Changelog rule 从简单的 4 步流程扩展为完整的规范化文档，包含结构模板、类型定义、格式要求、会话隔离规则和示例
- `changelogs/2026-05-31.md` [Changed] 追加本次变更记录

### 影响
- 此后所有变更记录必须严格遵循新规范格式
- 历史已有的 changelog 条目保持不变，不受新规范约束
- 多会话协作时，各会话只能追加当天的记录，不能回溯修改历史条目

### 原因
- 原有 Changelog rule 过于简略（仅 4 步流程），未对格式、结构、分类做任何约束
- 实际产生的 changelog 存在格式不统一、分类缺失、文件引用混乱等问题
- 需要明确的规范确保 changelog 的可读性和一致性
- 会话隔离规则防止多会话协作时对历史记录的误修改或冲突覆盖

## [docs] 将 AGENTS.md 中的英文章节翻译为中文

### 变更内容
- 翻译以下英文章节为中文，保持技术术语和代码不变：
  - `Project overview` → `项目概述`
  - `Build / check / test` → `构建 / 检查 / 测试`
  - `Formatting` → `代码格式`
  - `Architecture` → `架构`
  - `Release` → `发布`
  - `Key conventions` → `关键约定`
  - `Macros documentation rule` → `宏文档规则`
- 所有英文注释、bash 命令提示、代码块保持原样

### 涉及文件
- `AGENTS.md` [Changed] 将 7 个英文章节的标题和正文翻译为中文
- `changelogs/2026-05-31.md` [Changed] 追加本次变更记录

### 影响
- 无功能性影响，纯文档语言统一
- 与已有中文内容（如 Changelog rule）保持一致

### 原因
- AGENTS.md 之前为英汉混排，上半部分全英文、下半部分全中文
- 统一为中文可提升团队成员阅读效率，符合项目内部中文为主的约定

## [docs][fix] 补充 API 模块文档注释并修正 get_group_honor_info 返回类型

### 变更内容
- 为 `src/api.rs` 中 `APISender` trait 及其全部 37 个方法添加详细的文档注释，包含功能说明、参数释义、返回值说明及 OneBot V11 官方文档链接。
- 为 `src/api/arg_type.rs` 中的 `MessageType` 枚举及其变体添加文档注释。
- 为 `src/api/return_type.rs` 中的全部 16 个结构体和枚举添加文档注释，包含字段说明及使用注意事项。
- 修正 `get_group_honor_info` 方法的返回类型：由错误的 `GetGroupMemberInfoResponse` 更正为 `GetGroupHonorInfoResponse`。

### 涉及文件
- `src/api.rs` [Changed] 为 `APISender` trait 及 37 个异步方法添加文档注释；修正 `get_group_honor_info` 返回类型为 `GetGroupHonorInfoResponse`
- `src/api/arg_type.rs` [Changed] 为 `MessageType` 枚举及 `Private`、`Group` 变体添加文档注释
- `src/api/return_type.rs` [Changed] 为 `GetMsgResponse`、`Sender`、`GetLoginInfoResponse`、`GetForwardMsgResponse`、`GetStrangerInfoResponse`、`GetFriendListResponse`、`GetGroupInfoResponse`、`GetGroupMemberInfoResponse`、`SendMsgResponse`、`CanSendResponse`、`GetGroupHonorInfoResponse`、`CurrentTalkative`、`HonorInfoListData`、`GetCookiesResponse`、`GetCsrfTokenResponse`、`GetCredentialsResponse`、`GetDataResponse`、`GetStatusResponse`、`GetVersionInfoResponse` 添加文档注释
- `changelogs/2026-05-31.md` [Added] 新增当日变更记录

### 影响
- 对调用方行为无影响，仅为文档增强。
- `get_group_honor_info` 返回类型修正为 BREAKING FIX：此前若调用方已按错误类型处理返回值，需更新为 `GetGroupHonorInfoResponse`。

### 原因
- API 模块长期缺乏文档，导致使用者难以快速理解各方法的用途和参数含义。
- `get_group_honor_info` 的返回类型与 OneBot V11 官方协议及 `return_type.rs` 中已定义的 `GetGroupHonorInfoResponse` 不匹配，属于历史遗留错误。

## [docs] 补充 Changelog rule 的具体记录流程

### 变更内容
- 在 `AGENTS.md` 的 `Changelog rule` 章节中新增 `### 记录流程` 小节
- 明确记录步骤：
  1. 在 `changelogs/` 下搜索以今天日期命名的 `YYYY-MM-DD.md` 文件
  2. 若文件不存在：创建文件并写入一级标题 `# YYYY-MM-DD 变更记录`，再按规范写入完整条目
  3. 若文件已存在：在文件末尾追加新条目，禁止修改已有历史条目
  4. 条目必须严格按照二级标题、三级标题、列表格式书写
- 强调会话隔离规则：禁止修改已存在的历史 changelog 条目

### 涉及文件
- `AGENTS.md` [Changed] 在 Changelog rule 中新增记录流程小节，明确创建/追加文件的具体操作步骤
- `changelogs/2026-05-31.md` [Changed] 追加本次变更记录

### 影响
- 此后所有变更记录的操作流程更加明确，减少因步骤不清导致的格式错误
- 与已有的会话隔离规则形成合力，确保 changelog 的不可变历史

### 原因
- 之前的规范虽然定义了格式，但缺少具体的操作步骤说明（如何创建文件、如何追加）
- 需要明确的流程指导，确保不同会话在执行记录时步骤一致

## [docs] 强化 Changelog 记录流程中的防覆盖检查

### 变更内容
- 在 `AGENTS.md` 的 `Changelog rule` → `### 记录流程` 中，对步骤 3（文件已存在的情况）增加防覆盖要求：
  - 追加前必须**重新读取文件完整内容**，确认未被其他会话修改
  - 明确说明此举是为了防止历史记录被覆盖

### 涉及文件
- `AGENTS.md` [Changed] 在记录流程步骤 3 中增加「重新读取文件」检查要求
- `changelogs/2026-05-31.md` [Changed] 追加本次变更记录

### 影响
- 多 agents 协作时，强制要求每次追加前确认文件状态，降低并发修改导致历史记录丢失的风险
- 与已有的会话隔离规则共同构成完整的 changelog 安全写入机制

### 原因
- 在多 agents 环境下，同一日期的 changelog 文件可能被不同 agent 先后修改
- 若不重新确认文件内容，后写入的 agent 可能在不知情的情况下覆盖其他 agent 已追加的条目
- 需要在流程层面强制加入检查步骤，而非仅靠约定约束

## [ci] 修改发布脚本以支持 macros 先发布并等待索引同步

### 变更内容
- 新增 `readManifest` 辅助函数，用于读取指定路径的 `Cargo.toml`。
- 新增 `checkCrateVersionExists` 函数，调用 crates.io API 确认指定 crate 版本是否已存在（处理 404 未发布的情况）。
- 新增 `waitForCrateIndex` 函数，轮询等待 crates.io 索引同步，最大等待 5 分钟，间隔 10 秒。
- 重构 `main` 函数发布逻辑：
  1. 先检查主 crate 版本是否已存在于 crates.io，若存在则直接跳过；
  2. 读取 `macros/Cargo.toml`，检查 macros 版本是否已存在，若不存在则先发布 macros；
  3. 发布 macros 后等待索引同步，确保主 crate 能正确解析依赖；
  4. 创建 GitHub release（使用主 crate 版本作为 tag）；
  5. 发布主 crate。

### 涉及文件
- `scripts/publish-release.ts` [Changed] 重构发布逻辑，增加 macros 预发布、crates.io 版本检查和索引同步等待机制
- `changelogs/2026-05-31.md` [Changed] 追加本次变更记录

### 影响
- CI 发布时自动处理 macros 与主 crate 的发布顺序，避免主 crate 因依赖的 macros 版本尚未同步到 crates.io 索引而发布失败。
- 若 macros 版本已存在于 crates.io，则跳过 macros 发布，直接创建 release 并发布主 crate。
- 不改变 `Cargo.toml` 中 `path` + `version` 的本地依赖写法，完全依赖 `cargo publish` 的原生行为（发布时自动忽略 `path`）。

### 原因
- 主 crate 通过 `{ version = "...", path = "macros" }` 依赖 macros，发布主 crate 前必须确保 crates.io 上已有对应版本的 macros。
- 原有 `publish-release.ts` 仅发布主 crate，未处理 macros 的先行发布，导致 macros 版本更新后主 crate 发布会因依赖解析失败而中断。
