# 2026-06-06 变更记录

## [feat][docs][chore] 扩展 Selector 类型支持并补充项目元数据与本地技能文件

### 变更内容
- 为 `Selector` 新增 `Option<T>` 与 `Result<T, E>` 相关扩展，支持从 `Option` 中 `flatten()` 到内部值，以及从 `Result` 中提取 `ok()` / `err()` 分支。
- 为字符串选择器补充 `not_starts_with`、`not_ends_with`、`not_contains` 及对应 `cond_not_*` 方法，使字符串筛选能力与数字选择器的正反向比较接口更一致。
- 统一整理核心 `Selector`、数值选择器与基础 trait 的实现格式，并在 `Cargo.toml` 中补充 crate 描述信息。
- 新增仓库内本地 agent skill 文件，补充 `git-commit`、`plan-mode` 与 `skill-creator` 相关定义、脚本和参考资源。

### 涉及文件
- `Cargo.toml` [Changed] 补充 crate 的 `description` 元数据。
- `src/error.rs` [Changed] 调整错误类型实现的格式与导入布局。
- `src/lib.rs` [Changed] 调整模块导出顺序。
- `src/selector.rs` [Changed] 注册 `option` 与 `result` 模块，并统一核心 `Selector` 方法实现格式。
- `src/selector/number.rs` [Changed] 调整数值子模块声明顺序。
- `src/selector/number/i128.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/i16.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/i32.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/i64.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/i8.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/isize.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/u128.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/u16.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/u32.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/u64.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/u8.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/number/usize.rs` [Changed] 统一数值选择器实现格式并保留完整比较与条件比较接口。
- `src/selector/option.rs` [Added] 新增 `Option<T>` 的 `AsSelector` 实现与 `flatten()` 路由能力。
- `src/selector/result.rs` [Added] 新增 `Result<T, E>` 的 `AsSelector` 实现与 `ok()` / `err()` 路由能力。
- `src/selector/string.rs` [Changed] 为 `&str` 和 `String` 选择器补充反向字符串匹配与条件反向匹配方法。
- `src/traits.rs` [Changed] 调整 trait 定义实现的格式与缩进。
- `changelogs/2026-06-06.md` [Added] 新增当天变更记录，覆盖本次源码、配置与本地技能文件改动。
- `.agents/skills/git-commit/SKILL.md` [Added] 新增本地 `git-commit` 技能说明。
- `.agents/skills/plan-mode/SKILL.md` [Added] 新增本地 `plan-mode` 技能说明。
- `.agents/skills/skill-creator/LICENSE.txt` [Added] 新增 `skill-creator` 技能许可证文件。
- `.agents/skills/skill-creator/SKILL.md` [Added] 新增 `skill-creator` 技能说明。
- `.agents/skills/skill-creator/agents/analyzer.md` [Added] 新增技能分析 agent 说明。
- `.agents/skills/skill-creator/agents/comparator.md` [Added] 新增技能比较 agent 说明。
- `.agents/skills/skill-creator/agents/grader.md` [Added] 新增技能评分 agent 说明。
- `.agents/skills/skill-creator/assets/eval_review.html` [Added] 新增评估结果查看页面资源。
- `.agents/skills/skill-creator/eval-viewer/generate_review.py` [Added] 新增评估报告生成脚本。
- `.agents/skills/skill-creator/eval-viewer/viewer.html` [Added] 新增评估查看器页面。
- `.agents/skills/skill-creator/references/schemas.md` [Added] 新增技能相关 schema 参考文档。
- `.agents/skills/skill-creator/scripts/__init__.py` [Added] 新增脚本模块初始化文件。
- `.agents/skills/skill-creator/scripts/aggregate_benchmark.py` [Added] 新增 benchmark 汇总脚本。
- `.agents/skills/skill-creator/scripts/generate_report.py` [Added] 新增报告生成脚本。
- `.agents/skills/skill-creator/scripts/improve_description.py` [Added] 新增技能描述优化脚本。
- `.agents/skills/skill-creator/scripts/package_skill.py` [Added] 新增技能打包脚本。
- `.agents/skills/skill-creator/scripts/quick_validate.py` [Added] 新增技能快速校验脚本。
- `.agents/skills/skill-creator/scripts/run_eval.py` [Added] 新增技能评估执行脚本。
- `.agents/skills/skill-creator/scripts/run_loop.py` [Added] 新增技能优化循环脚本。
- `.agents/skills/skill-creator/scripts/utils.py` [Added] 新增技能脚本公共工具函数。

### 影响
- 调用方现在可以直接对 `Option` 和 `Result` 建立选择器链，并对字符串执行与数字接口风格一致的反向条件筛选。
- 这批改动主要扩展 API 能力并整理实现形式，不引入已知破坏性接口变更；新增 `.agents/` 文件会使仓库包含本地辅助技能资源。

### 原因
- 为了让 `Selector` 在常见容器类型与字符串场景下具备更完整的一致性接口，减少调用方手写拆分逻辑。
- 同时补充包描述信息和本地技能资源，方便仓库发布说明与后续协作流程复用。

## [feat][docs] 为浮点数与字符串选择器补充更多筛选接口

### 变更内容
- 为 `Selector<f32>` 与 `Selector<f64>` 新增独立模块，并补齐 `eq`、`not_eq`、`gt`、`lt`、`ge`、`le` 及对应 `cond_*` / `cond_not_*` 比较接口。
- 在数值模块入口注册 `f32` 与 `f64` 子模块，使浮点数与现有整数选择器拥有一致的链式筛选能力。
- 为 `&str` 与 `String` 选择器补充 `eq`、`not_eq`、`empty`、`not_empty`、`contains_char` 及对应条件变体，扩展字符串精确匹配与空值判断能力。

### 涉及文件
- `src/selector/number.rs` [Changed] 注册 `f32` 与 `f64` 数值选择器子模块导出。
- `src/selector/number/f32.rs` [Added] 新增 `f32` 的 `AsSelector` 实现与完整比较、条件比较接口。
- `src/selector/number/f64.rs` [Added] 新增 `f64` 的 `AsSelector` 实现与完整比较、条件比较接口。
- `src/selector/string.rs` [Changed] 为 `&str` 和 `String` 选择器新增相等、空字符串、字符包含及条件筛选方法。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次浮点数与字符串选择器接口扩展。

### 影响
- 调用方现在可以直接对 `f32`、`f64` 使用与整数一致的选择器比较 API，也可以更细粒度地判断字符串是否相等、为空或包含指定字符。
- 本次变更为向后兼容的能力扩展，不改变既有接口的调用方式。

### 原因
- 为了统一数值类型在 `Selector` 中的能力覆盖范围，避免浮点数场景缺少同构接口。
- 同时补齐字符串选择器常用的精确匹配与空值判断方法，减少业务侧重复封装。

## [feat][refactor][docs] 提取通用比较 trait 并为有序选择器补充范围筛选

### 变更内容
- 新增 `src/selector/traits` 模块，将 `eq` / `not_eq` 与 `gt` / `lt` / `ge` / `le` 等比较逻辑抽取为基于 `PartialEq`、`PartialOrd` 的通用 `Selector` 扩展实现。
- 为通用有序选择器补充开区间、闭区间、左开右闭、左闭右开及其反向、条件变体筛选接口，减少数值类型重复实现。
- 在 `Selector` 核心类型上新增四个 `or_*` 组合方法，用于在合并两个匹配结果时显式保留不同来源的父节点。
- 精简各数值选择器和字符串选择器中的重复比较方法定义，改为复用通用 trait 模块提供的实现。

### 涉及文件
- `src/selector.rs` [Changed] 注册 `traits` 模块，并新增 `or_a_parent_a`、`or_a_parent_b`、`or_b_parent_a`、`or_b_parent_b` 四个选择器合并方法。
- `src/selector/string.rs` [Changed] 删除字符串选择器中已被通用 `PartialEq` 扩展覆盖的相等比较方法实现。
- `src/selector/traits.rs` [Added] 新增比较 trait 子模块入口。
- `src/selector/traits/eq.rs` [Added] 新增基于 `PartialEq` 的通用 `eq`、`not_eq` 与条件比较实现。
- `src/selector/traits/ord.rs` [Added] 新增基于 `PartialOrd` 的通用大小比较、范围筛选与条件变体实现。
- `src/selector/number/f32.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/f64.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/i128.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/i16.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/i32.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/i64.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/i8.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/isize.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/u128.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/u16.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/u32.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/u64.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/u8.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `src/selector/number/usize.rs` [Changed] 删除重复的比较方法实现，改为空 impl 以复用通用 trait 扩展。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次通用比较 trait 抽取与范围筛选能力扩展。

### 影响
- 选择器的相等与有序比较接口现在可由通用 trait 自动覆盖更多 `PartialEq` / `PartialOrd` 类型，减少后续新增类型时的重复代码。
- 数值与字符串选择器现有常用比较调用方式保持不变，同时新增一组通用范围筛选能力。

### 原因
- 为了降低数值与字符串选择器中重复比较逻辑的维护成本，并让 `Selector` 的比较能力更容易扩展到更多类型。
- 同时补充范围判断与结果合并能力，支撑更复杂的链式筛选与父节点回溯场景。

## [feat][docs][test][build] 新增 tynavi Selector 过程宏与枚举改写属性宏

### 变更内容
- 新增 `derive` feature，通过主 crate 可选导出 `Selector` derive 宏与 `selector` 属性宏，默认构建仍不引入宏依赖。
- 实现 `#[derive(Selector)]`，为结构体和枚举生成 `AsSelector`、类型专属 selector trait、字段 inspect/filter/extract/route 方法，以及枚举 `is_*` / `route_*` 方法。
- 实现 `#[selector]` 属性宏，将多元素元组变体和匿名结构体变体改写为生成的 payload 结构体，使这些变体也能通过 `route_*` 深入选择。
- 补充宏文档和集成测试，覆盖空类型、命名结构体、元组结构体、枚举变体、属性改名、跳过字段方法和变体筛选。

### 涉及文件
- `Cargo.toml` [Changed] 新增可选 `tynavi-macros` 依赖与 `derive` feature。
- `src/lib.rs` [Changed] 增加 crate 自引用别名，并在 `derive` feature 下重新导出宏。
- `src/selector/vec.rs` [Changed] 移除未使用的 `SelectorInstance` 导入。
- `src/traits.rs` [Changed] 清理 `()` 的 `Snapshot` 与 `Unmatch` 实现中的多余 unit 表达式。
- `macros/Cargo.toml` [Changed] 为过程宏 crate 增加 `syn`、`quote`、`proc-macro2` 依赖。
- `macros/src/lib.rs` [Changed] 注册 `Selector` derive 宏和 `selector` 属性宏入口。
- `macros/src/selector.rs` [Added] 新增 Selector 过程宏核心实现，包含属性解析、字段方法生成、枚举方法生成和 enum payload 改写逻辑。
- `macros/docs/selector.md` [Added] 新增宏使用文档，说明 feature、生成 API、属性语法、属性宏改写规则和限制。
- `tests/derive_selector.rs` [Added] 新增 derive/attribute 宏集成测试。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次 Selector 宏功能实现。

### 影响
- 调用方启用 `derive` feature 后，可以通过宏为自定义类型自动生成 tynavi 风格不可变 selector API。
- 默认 feature 不变，未启用 `derive` 时主 crate 仍不依赖 `syn`、`quote`、`proc-macro2`。
- 多字段 enum 变体需要使用 `#[selector]` 属性宏改写后才能通过 `route_*` 路由到生成的 payload 类型。

### 原因
- 为了减少调用方为业务结构手写 selector 路由、过滤、提取和枚举变体匹配方法的重复成本。
- 同时借鉴 onebot-api 的 Selector 宏体验，并适配 tynavi 当前的父节点追踪与不可变快照语义。

## [build][docs] 补充记录 Selector 宏依赖锁定文件更新

### 变更内容
- 补充记录新增 `tynavi-macros` 可选依赖后，Cargo 自动更新依赖锁定文件。

### 涉及文件
- `Cargo.lock` [Changed] 锁定 `tynavi-macros` 及其 `syn`、`quote`、`proc-macro2` 等过程宏依赖版本。
- `changelogs/2026-06-06.md` [Changed] 追加本次锁定文件更新的补充记录。

### 影响
- 构建过程可以复用确定的过程宏依赖版本；默认未启用 `derive` feature 时运行时 API 行为不变。

### 原因
- 新增可选过程宏依赖后需要同步记录锁定文件变化，保持 changelog 与 git 修改文件一致。

## [docs] 更正 Selector 宏相关文件修改类型记录

### 变更内容
- 补充说明当前 git 视角下 `macros/`、`tests/` 与 `src/selector/vec.rs` 属于新增文件路径，纠正前序条目中部分文件修改类型描述不够准确的问题。

### 涉及文件
- `macros/Cargo.toml` [Added] 作为新增过程宏 crate 的清单文件加入仓库。
- `macros/src/lib.rs` [Added] 作为新增过程宏 crate 的入口文件加入仓库。
- `macros/src/selector.rs` [Added] 作为新增 Selector 宏实现文件加入仓库。
- `macros/docs/selector.md` [Added] 作为新增宏文档文件加入仓库。
- `src/selector/vec.rs` [Added] 当前 git 视角下为新增 Vec selector 扩展文件，本次同步清理了未使用导入。
- `tests/derive_selector.rs` [Added] 作为新增宏集成测试文件加入仓库。
- `changelogs/2026-06-06.md` [Changed] 追加文件修改类型更正说明。

### 影响
- 不改变源码行为，仅让当天 changelog 中的文件状态说明与当前 git 工作区状态保持一致。

### 原因
- 提交前需要确保 changelog 覆盖并准确描述 git 中已修改或新增的文件。

## [docs] 为 Selector 宏实现补充函数级文档注释

### 变更内容
- 为 `macros/src/selector.rs` 中的每个函数补充文档注释，说明函数职责和主要执行流程。
- 注释覆盖属性解析、泛型处理、结构体字段方法生成、枚举方法生成、属性宏变体改写和宏入口等关键逻辑。

### 涉及文件
- `macros/src/selector.rs` [Changed] 为宏实现内所有函数添加详细 `///` 文档注释。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次宏代码注释补充。

### 影响
- 不改变宏生成代码和对外 API，仅提升过程宏实现的可读性和维护性。

### 原因
- Selector 宏实现涉及多层 token 生成和 enum 改写逻辑，需要通过函数级说明降低后续维护成本。

## [docs] 完善 Selector 宏使用与实现流程文档

### 变更内容
- 重写 `selector.md`，详细说明 `#[derive(Selector)]` 与 `#[selector]` 的启用方式、宏行为、可用参数、生成方法和限制。
- 为单元结构体、无字段元组结构体、命名结构体、元组结构体、字段属性、空枚举、无数据变体、单元素元组变体、多元素元组变体和匿名结构体变体补充代码示例。
- 新增 `impl.md`，面向维护者说明两个宏的属性解析、结构体生成、字段方法生成、枚举生成、属性宏改写、泛型处理、路径卫生和错误处理流程。

### 涉及文件
- `macros/docs/selector.md` [Changed] 扩展为完整的 Selector 宏使用说明与示例文档。
- `macros/docs/impl.md` [Added] 新增 Selector 宏实现流程说明文档。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次宏文档扩展。

### 影响
- 不改变源码和宏展开行为，仅增强宏使用者与维护者的文档参考。

### 原因
- Selector 宏同时包含 derive 生成和 enum 属性改写两条路径，需要更完整的使用说明和实现流程文档来降低理解成本。

## [feat][docs] 补充通用集合匹配与宏导出记录

### 变更内容
- 为基于 `PartialEq` 的通用 selector 扩展补充 `one_of`、`not_one_of` 及对应 `cond_*` 方法，支持按候选列表筛选当前游标。
- 补充记录 `derive` feature 下的宏重导出文件，确保主 crate 对外暴露过程宏入口的文件变更在 changelog 中可追踪。
- 补充说明新增 slice selector 扩展文件提供 `&[T]` 的 `AsSelector` 入口。

### 涉及文件
- `src/selector/traits/eq.rs` [Changed] 新增候选列表匹配与反向匹配的通用筛选方法。
- `src/macros.rs` [Added] 新增 `tynavi_macros` 的统一重导出入口，供 `derive` feature 下的 `src/lib.rs` 使用。
- `src/selector/vec.rs` [Added] 新增 `&[T]` 的 `AsSelector` 实现入口说明。
- `changelogs/2026-06-06.md` [Changed] 追加记录提交前发现的遗漏变更项。

### 影响
- 调用方可以在任意 `PartialEq` 游标上使用候选列表筛选能力。
- 启用 `derive` feature 后，过程宏通过主 crate 的 `macros` 模块统一导出；默认 feature 行为不变。

### 原因
- 提交前逐项核对 git 修改文件与 changelog 时发现部分新增文件和 API 扩展未被当天记录完整覆盖，需要按项目规则补齐。

## [fix][docs] 修复 derive feature 宏根导出

### 变更内容
- 在启用 `derive` feature 时，将 `src/macros.rs` 中重导出的过程宏继续从 crate root 公开导出。
- 修复集成测试中 `use tynavi::{Selector, selector}` 无法解析到 derive 宏和属性宏的问题。

### 涉及文件
- `src/lib.rs` [Changed] 在 `derive` feature 下新增 `pub use macros::*;`，暴露 `Selector` derive 宏与 `selector` 属性宏。
- `changelogs/2026-06-06.md` [Changed] 追加记录本次宏导出修复。

### 影响
- 调用方启用 `derive` feature 后可以直接从 `tynavi` crate root 使用 `Selector` 和 `selector` 宏。
- 默认 feature 行为不变。

### 原因
- `cargo test --features derive` 发现宏只通过内部模块存在，未按文档和测试预期从 crate root 公开。
