Merge tag 'v0.20.3-beta'

Author: seeker-zuo

.claude/skills/cargo-check-all.md

@@ -0,0 +1,41 @@
+# cargo-check-all
+
+对整个 workspace 执行完整的 Rust 代码质量检查，依次运行编译检查、clippy 静态分析和全量测试，汇总报告结果。
+
+## 工作流程
+
+依次执行以下三个阶段，任何阶段失败时分析原因并给出修复建议：
+
+### 阶段 1：编译检查
+
+```bash
+cargo check --workspace 2>&1
+```
+
+### 阶段 2：Clippy 静态分析
+
+```bash
+cargo clippy --workspace -- -D warnings 2>&1
+```
+
+### 阶段 3：全量测试
+
+```bash
+cargo test --workspace 2>&1
+```
+
+## 结果汇总
+
+所有阶段执行完毕后，输出汇总表格：
+
+| 阶段 | 状态 | 备注 |
+|------|------|------|
+| cargo check | PASS/FAIL | 编译错误数 |
+| cargo clippy | PASS/FAIL | 警告数 |
+| cargo test | PASS/FAIL | 通过/失败/忽略数 |
+
+## 失败处理
+
+- 如果 clippy 报出警告，列出所有警告并提供逐条修复方案
+- 如果测试失败，区分是已知的 flaky test（如 test_sql_debug 并发竞争）还是真正的回归
+- 编译失败时直接展示错误并分析原因

.claude/skills/commit.md

@@ -0,0 +1,68 @@
+# commit
+
+分析当前工作区的改动，按项目规范生成 commit message 并提交。
+
+## 工作流程
+
+### 第一步：检查工作区状态
+
+```bash
+git status
+git diff --stat
+git diff --staged --stat
+```
+
+### 第二步：分析改动内容
+
+读取所有已修改的文件 diff，理解改动的目的和范围：
+
+```bash
+git diff
+git diff --staged
+```
+
+如果有未追踪的新文件，检查是否需要纳入提交（排除 .env、credentials 等敏感文件）。
+
+### 第三步：生成 commit message
+
+根据改动内容生成简洁的 commit message：
+
+**格式规范：**
+- 首行：祈使句式，概括改动目的（不超过 72 字符）
+- 空行
+- 可选的详细说明
+
+**动词选择：**
+- `Add` — 全新功能或文件
+- `Update` — 对已有功能的增强
+- `Fix` — Bug 修复
+- `Remove` — 删除代码或功能
+- `Refactor` — 重构（不改变行为）
+- `Bump` — 依赖版本升级
+
+**示例：**
+```
+Add semantic config to control NLP dictionary loading
+```
+
+### 第四步：向用户确认
+
+展示：
+1. 将要提交的文件列表
+2. 生成的 commit message
+
+等待用户确认或修改后再执行提交。
+
+### 第五步：执行提交
+
+```bash
+git add <specific-files>
+git commit -m "<message>"
+```
+
+## 注意事项
+
+- 优先使用 `git add <具体文件>` 而非 `git add -A`
+- 不要提交 .env、credentials.json 等敏感文件
+- 不自动 push，提交后告知用户结果
+- 如果工作区没有改动，告知用户无需提交

.claude/skills/release-prep.md

@@ -0,0 +1,63 @@
+# release-prep
+
+准备新版本发布：更新版本号、CHANGELOG 日期、打 git tag。
+
+## 前置条件
+
+执行前先确认：
+1. 所有代码已提交（工作区干净）
+2. 测试全部通过（建议先运行 /cargo-check-all）
+
+## 工作流程
+
+### 第一步：确认发布版本
+
+```bash
+# 查看当前版本和最近的 tag
+git log --oneline --decorate -10 | grep tag
+head -20 CHANGELOG.md
+```
+
+读取 CHANGELOG.md 顶部的 `[x.y.z Unreleased]` 确认要发布的版本号。
+如果没有 Unreleased 段落，询问用户要发布的版本号。
+
+### 第二步：询问用户确认
+
+向用户确认：
+- 版本号是否正确
+- CHANGELOG 中的改动是否完整
+- 是否需要调整任何条目
+
+### 第三步：更新 CHANGELOG 日期
+
+将 `## [x.y.z Unreleased]` 改为 `## [x.y.z] - YYYY-MM-DD`（使用今天的日期）。
+
+### 第四步：更新 Cargo.toml 版本号
+
+检查根 `Cargo.toml` 和各 crate 的 `Cargo.toml` 中的 version 字段：
+
+```bash
+grep -n '^version' Cargo.toml
+```
+
+如果版本号需要更新，逐一修改。注意只改需要变动的 crate。
+
+### 第五步：提交版本变更
+
+```bash
+git add CHANGELOG.md Cargo.toml Cargo.lock
+git commit -m "Release vx.y.z"
+```
+
+### 第六步：打 tag
+
+```bash
+git tag vx.y.z
+```
+
+## 注意事项
+
+- 每一步都需要用户确认后再继续
+- 不自动 push 到远端，留给用户决定
+- tag 格式统一为 `vx.y.z`（如 `v1.17.0`）
+- 打完 tag 后，提示用户可以运行 `git push && git push --tags`

.claude/skills/rust-add-module.md

@@ -0,0 +1,80 @@
+# rust-add-module
+
+在指定 crate 下新增模块：创建文件、注册 mod、添加基本结构和测试骨架。
+
+## 输入
+
+用户需要提供：
+1. 目标 crate 名称（如 `wf-core`、`wf-lang`）
+2. 模块名称
+3. 模块用途简述
+
+如果用户未提供，通过提问确认。
+
+## 工作流程
+
+### 第一步：确认目标位置
+
+```bash
+ls crates/<crate-name>/src/
+```
+
+了解现有模块结构，确认新模块应放在哪一层（顶层 mod 还是子模块）。
+
+### 第二步：创建模块文件
+
+根据模块复杂度决定结构：
+
+- **简单模块**：创建 `crates/<crate>/src/<module>.rs`
+- **复杂模块**：创建 `crates/<crate>/src/<module>/mod.rs`，按需拆分子文件
+
+### 第三步：注册模块
+
+在父模块（通常是 `lib.rs` 或 `main.rs`）中添加 `mod` 声明：
+
+```rust
+pub mod <module>;
+```
+
+遵循现有代码的可见性风格（`pub mod` vs `mod` vs `pub(crate) mod`）。
+
+### 第四步：添加基本结构
+
+根据模块用途创建骨架代码，通常包含：
+
+- 核心 struct / enum 定义
+- 必要的 `impl` 块
+- 必要的 trait 实现
+- 如果模块需要对外暴露，在 `lib.rs` 中添加 `pub use` re-export
+
+### 第五步：添加测试骨架
+
+在模块文件底部添加测试模块：
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_placeholder() {
+        // TODO: 根据实际功能补充测试
+    }
+}
+```
+
+### 第六步：验证编译
+
+```bash
+cargo check -p <crate-name> 2>&1
+```
+
+确保新模块能通过编译。
+
+## 注意事项
+
+- 遵循项目现有的命名风格（snake_case 模块名）
+- 查看相邻模块的 `use` 导入风格并保持一致
+- edition 2024 不需要 `mod.rs` 来声明子模块目录，但要检查项目现有风格
+- 如果 crate 间有依赖关系，可能需要在 `Cargo.toml` 中添加依赖
+- 不要过度设计——先创建最小可用的骨架，让用户在此基础上扩展

.claude/skills/rust-add-test.md

@@ -0,0 +1,130 @@
+# rust-add-test
+
+为指定函数或模块编写单元测试和集成测试。
+
+## 输入
+
+用户需要提供：
+1. 要测试的函数/模块/类型名称或文件路径
+2. 可选：需要覆盖的具体场景
+
+如果用户只给了模糊描述（如"给 parser 加测试"），先阅读代码理解后再设计测试用例。
+
+## 工作流程
+
+### 第一步：理解待测代码
+
+阅读目标代码，分析：
+- 函数签名（输入类型、返回类型、是否返回 Result）
+- 边界条件（空输入、极端值、错误路径）
+- 依赖关系（是否需要 mock 或构造复杂上下文）
+- 现有测试（避免重复）
+
+```bash
+# 查看现有测试
+cargo test -p <crate> -- --list 2>&1 | grep <module>
+```
+
+### 第二步：设计测试用例
+
+为每个函数设计测试矩阵：
+
+| 类别 | 用例 | 预期结果 |
+|------|------|----------|
+| 正常路径 | 典型输入 | 正确输出 |
+| 边界条件 | 空输入/极值 | 合理行为 |
+| 错误路径 | 非法输入 | 返回 Err 或 panic |
+
+### 第三步：编写单元测试
+
+在目标模块文件的底部添加或扩展 `#[cfg(test)]` 模块：
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_function_normal_case() {
+        let result = target_function(valid_input);
+        assert_eq!(result, expected);
+    }
+
+    #[test]
+    fn test_function_edge_case() {
+        let result = target_function(edge_input);
+        assert_eq!(result, expected);
+    }
+
+    #[test]
+    fn test_function_error_case() {
+        let result = target_function(invalid_input);
+        assert!(result.is_err());
+    }
+}
+```
+
+**命名规范：**
+- 测试函数名：`test_<函数名>_<场景>`
+- 使用描述性名称，让失败信息一目了然
+
+### 第四步：编写集成测试（如需要）
+
+如果需要跨模块或端到端测试，在 `crates/<crate>/tests/` 目录下创建测试文件：
+
+```rust
+// crates/<crate>/tests/integration_test.rs
+use <crate>::<module>::<function>;
+
+#[test]
+fn test_integration_scenario() {
+    // 构造环境
+    // 执行操作
+    // 验证结果
+}
+```
+
+### 第五步：运行测试
+
+```bash
+# 运行新增的测试
+cargo test -p <crate> <test_name> -- --nocapture 2>&1
+
+# 确认全量测试无回归
+cargo test -p <crate> 2>&1
+```
+
+### 第六步：检查覆盖情况
+
+确认测试覆盖了：
+- [ ] 正常路径（happy path）
+- [ ] 边界条件
+- [ ] 错误处理路径
+- [ ] 返回值的所有变体（如 enum 的所有 variant）
+
+## 测试工具箱
+
+### 断言宏
+- `assert_eq!(actual, expected)` — 相等比较
+- `assert_ne!(actual, unexpected)` — 不等比较
+- `assert!(condition)` — 布尔条件
+- `assert!(result.is_ok())` / `assert!(result.is_err())` — Result 检查
+- `assert!(matches!(value, Pattern))` — 模式匹配
+
+### 测试辅助
+- `#[should_panic(expected = "message")]` — 预期 panic
+- `#[ignore]` — 暂时跳过（附注释说明原因）
+- 使用 `indoc!` 宏编写多行字符串测试输入（如果项目已依赖 indoc）
+
+### 构造测试数据
+- 优先使用 builder pattern 或工厂函数构造复杂测试数据
+- 将通用的测试 fixture 提取到 `mod tests` 内的辅助函数中
+- 避免在测试中硬编码大段文本——使用 `include_str!` 加载测试 fixture 文件
+
+## 注意事项
+
+- 测试应该是确定性的，避免依赖系统时间、随机数或文件系统状态
+- 每个测试只验证一个行为点
+- 测试名称要能说明"测什么"和"预期什么"
+- 不要为了凑覆盖率写无意义的测试——每个测试应该验证一个有价值的行为
+- 遵循项目现有测试的风格和组织方式