whosellm 0.1.1a4__tar.gz → 0.2.0__tar.gz

{whosellm-0.1.1a4 → whosellm-0.2.0}/.bumpversion.toml

@@ -2,7 +2,7 @@
 # 文档 / Documentation: https://callowayproject.github.io/bump-my-version/
 
 [tool.bumpversion]
-current_version = "0.1.1a4"
+current_version = "0.2.0"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.

whosellm-0.2.0/.claude/commands/interview.md

@@ -0,0 +1,11 @@
+---
+description: Interview me about the plan
+argument-hint: [plan]
+model: opus
+---
+
+Read this plan file $1 and interview me in detail using the AskUserQuestionTool about
+literally anything: technical implementation, UI & UX, concerns, tradeoffs, etc.
+but make sure the questions are not obvious.
+
+Be very in-depth and continue interviewing me continually until it’s complete, then write the spec to the file.

whosellm-0.2.0/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: code-review
+description: 对代码变更进行全面 Review，覆盖设计规范、测试完备性、DRY 原则和封装合理性。当用户提交变更或请求代码审查时使用。
+user-invocable: true
+argument-hint: [file|branch|PR-url|--staged]
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Code Review — 全面代码审查
+
+对代码变更进行系统性审查，输出结构化的审查报告。
+
+输入：$ARGUMENTS
+
+---
+
+## 核心原则
+
+1. **以项目规范为准绳** — 审查标准来自 [CLAUDE.md](../../../CLAUDE.md) 和项目现有代码模式，不套用外部通用规范
+2. **指出问题而非重写** — 报告中说明"什么有问题、为什么、建议如何改"，不直接输出大段替换代码
+3. **区分严重等级** — 阻塞发布的问题 vs 建议改进，不混为一谈
+
+---
+
+## 第一步：确定审查范围
+
+### 1.1 解析输入
+
+根据输入类型获取变更内容：
+
+| 输入类型 | 操作 |
+|---------|------|
+| `--staged` 或无参数 | `git diff --cached` 获取暂存区变更；若为空则 `git diff` 获取工作区变更 |
+| 文件路径 | 直接读取指定文件，结合 `git diff` 查看该文件的变更 |
+| 分支名 | `git diff main...{branch}` 获取分支全部变更 |
+| PR URL | `gh pr diff {number}` 获取 PR 完整变更 |
+
+### 1.2 生成变更清单
+
+列出所有变更文件，标注变更类型：
+
+```
+| 文件 | 变更类型 | 影响范围 |
+|------|---------|---------|
+| whosellm/models/families/xxx.py | 新增 | 模型配置 |
+| tests/models/families/test_xxx.py | 新增 | 测试 |
+| whosellm/models/registry.py | 修改 | 核心逻辑 |
+```
+
+---
+
+## 第二步：设计规范审查
+
+逐项检查变更是否符合项目设计规范。
+
+### 2.1 核心概念一致性
+
+对照 [CLAUDE.md](../../../CLAUDE.md) 中定义的 Family / Provider / Version / Variant 四个核心概念：
+
+- **Family 划分**：新模型的 Family 归属是否正确？判断依据是命名模式，不是供应商营销定位
+- **版本解析**：version 是否正确解析为 `(major, minor)` 元组？
+- **变体分类**：variant 属于尺寸等级还是功能特化？`variant_priority` 是否合理？
+- **比较边界**：同 Family 内可比较，跨 Family 应抛出 `ValueError`
+
+### 2.2 配置驱动模式
+
+检查变更是否遵循配置驱动的设计模式：
+
+- 新模型是否通过 `ModelFamilyConfig` / `SpecificModelConfig` 定义，而非在代码中添加 if-else 分支？
+- `patterns` 列表是否按优先级排序（更具体的在前）？
+- `specific_models` 的键是否为小写模型名？
+- 子 `patterns` 是否为父 `patterns` 的子集？
+
+### 2.3 注册表模式
+
+- 新增配置是否通过 `ModelFamilyConfig.__post_init__` 自动注册？
+- 是否需要利用 Registry Merge 机制（同一 `(family, provider)` 的多个配置自动合并）？
+- 如果新增了 `ModelFamily` 或 `Provider` 枚举值，是否通过 `add_member()` 扩展？
+
+### 2.4 宽容设计
+
+- 对未知输入是否返回 `UNKNOWN` 而非抛出异常？
+- 新功能是否向后兼容，不破坏已有的公共 API？
+
+### 2.5 代码风格
+
+- Ruff 规则：行长 120、双引号、Python 3.11 目标
+- MyPy 严格模式：类型注解完备、无隐式 Optional
+- 运行 `uv run poe check` 和 `uv run poe typecheck` 验证
+
+---
+
+## 第三步：测试覆盖审查
+
+### 3.1 功能性测试
+
+对照 `tests/` 目录中已有模式，检查新增代码是否有对应测试：
+
+**模型配置变更**必须覆盖：
+- 模式匹配测试 — `match_model_pattern("model-name")` 返回正确的 family / version / variant
+- `LLMeta` 端到端测试 — `LLMeta("model-name")` 的字段值正确
+- 带日期后缀的模式匹配 — `model-name-YYYY-MM-DD` 格式正确解析
+- 变体优先级排序 — 同版本不同变体间的比较关系正确
+
+**能力字段变更**必须覆盖：
+- 每个 `supports_*` 布尔字段的断言
+- `max_tokens` 和 `context_window` 数值断言
+- 特定模型覆盖父级默认值的场景
+
+**核心逻辑变更**必须覆盖：
+- 正向测试（正常输入 → 正确输出）
+- 边界测试（空字符串、极长名称、特殊字符等）
+- 异常测试（跨 Family 比较 → `ValueError`）
+
+### 3.2 业务数据验证
+
+检查测试中的断言值是否与配置一致：
+
+```python
+# 好 — 测试值与配置中的实际值匹配
+assert m.capabilities.context_window == 200000  # 与 anthropic.py 中的配置一致
+
+# 坏 — 测试值与配置不符，测试通过只是因为使用了错误的值
+assert m.capabilities.context_window == 128000  # 配置中实际是 200000
+```
+
+### 3.3 参数化测试
+
+对于同一家族的多个模型/变体，检查是否使用了 `@pytest.mark.parametrize` 减少重复：
+
+```python
+# 好 — 参数化覆盖多个模型
+@pytest.mark.parametrize("model_name,expected_version,expected_variant", [...])
+def test_family_version_variant(model_name, expected_version, expected_variant): ...
+
+# 坏 — 每个模型一个独立函数，逻辑完全重复
+def test_model_a_version(): ...
+def test_model_b_version(): ...
+def test_model_c_version(): ...
+```
+
+### 3.4 测试命名与标记
+
+- 测试文件位于 `tests/models/families/test_{family}.py`
+- 测试函数命名清晰描述测试意图
+- 适当使用 `@pytest.mark.unit` / `@pytest.mark.integration` 标记
+
+---
+
+## 第四步：DRY 原则与封装合理性审查
+
+### 4.1 重复代码检测
+
+在变更文件和相关文件中查找以下模式：
+
+- **同一能力配置重复声明** — 多个 `SpecificModelConfig` 定义了完全相同的 `ModelCapabilities`，应提取为共享变量或利用家族默认值
+- **同一测试逻辑重复** — 多个测试函数的断言列表完全相同，应使用参数化测试或提取辅助函数
+- **同一模式匹配逻辑重复** — 应复用 `parse_pattern` 而非自行实现匹配
+
+### 4.2 未使用已有封装
+
+检查变更是否绕过了项目已有的封装：
+
+| 应该使用 | 而非 |
+|---------|------|
+| `ModelFamilyConfig` + `SpecificModelConfig` | 直接操作 `MODEL_REGISTRY` |
+| `match_model_pattern()` | 自行编写正则匹配 |
+| `infer_variant_priority()` | 手动硬编码优先级元组 |
+| `parse_pattern()` | 直接调用 `parse.parse()` |
+| `Provider.add_member()` / `ModelFamily.add_member()` | 修改枚举类定义 |
+
+### 4.3 "半重复"封装
+
+检查是否存在以下情况：
+
+- **功能相似但接口不同的函数** — 例如两个函数都在做"从模型名解析版本"但实现路径不同
+- **部分提取的抽象** — 例如提取了一个辅助函数但只用了一半参数，另一半仍在调用处硬编码
+- **跨文件的逻辑耦合** — 例如两个文件各自维护一份相似的映射表
+
+发现后建议：统一到一处实现，或说明为何需要两套。
+
+---
+
+## 第五步：输出审查报告
+
+按以下格式输出结构化报告：
+
+```markdown
+## Code Review 报告
+
+### 审查范围
+{变更文件列表}
+
+### 阻塞项（必须修复）
+
+| # | 文件:行号 | 类别 | 问题描述 | 建议 |
+|---|----------|------|---------|------|
+| 1 | xxx.py:42 | 设计规范 | ... | ... |
+
+### 建议项（推荐改进）
+
+| # | 文件:行号 | 类别 | 问题描述 | 建议 |
+|---|----------|------|---------|------|
+| 1 | xxx.py:88 | DRY | ... | ... |
+
+### 通过项
+- 设计规范：{通过的检查项}
+- 测试覆盖：{通过的检查项}
+- DRY / 封装：{通过的检查项}
+```
+
+### 类别标签
+
+| 标签 | 含义 |
+|------|------|
+| 设计规范 | 不符合 CLAUDE.md 定义的核心概念或设计模式 |
+| 测试缺失 | 缺少必要的测试用例 |
+| 测试数据 | 测试断言值与配置不一致 |
+| DRY | 存在可消除的重复 |
+| 封装 | 未使用已有封装或存在半重复封装 |
+| 风格 | 不符合 Ruff / MyPy 规则 |
+| 兼容性 | 可能破坏现有 API 或行为 |
+
+---
+
+## 第六步：验证（可选）
+
+如果审查发现了风格或类型问题，可运行自动化工具确认：
+
+```bash
+uv run poe check      # Ruff 检查
+uv run poe typecheck  # MyPy 类型检查
+uv run poe test       # 运行测试
+```
+
+如果变更涉及特定模型家族，运行针对性测试：
+
+```bash
+uv run python -m pytest tests/models/families/test_{family}.py -v
+```

whosellm-0.2.0/.claude/skills/create-skill/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: create-skill
+description: 创建符合项目规范的新 Claude Skill。当用户需要新增技能、为 Claude Code 添加自动化工作流时使用。
+user-invocable: true
+argument-hint: <skill-name> [description]
+allowed-tools: Read, Write, Glob, Bash
+---
+
+# Create Skill — 创建新技能
+
+根据用户描述创建符合本项目规范的 Claude Skill。
+
+输入：$ARGUMENTS
+
+---
+
+## 核心原则
+
+1. **代码胜于文档** — SKILL.md 中能引用现有文件的，直接用 Markdown 链接，不要摘录代码
+2. **讲清为何，示例为何** — 先阐述模式与概念，再引用示例文件说明具体操作
+3. **无实践不成技** — 如果项目中尚无该技能涉及的实际案例或代码，说明它未经验证，拒绝创建
+4. **分步即模式** — SKILL 主体是分步执行流程，模式与最佳实践自然渗透在步骤中，而非堆砌独立章节
+
+---
+
+## 第一步：需求理解与可行性验证
+
+### 1.1 解析用户意图
+
+从 `$ARGUMENTS` 中提取：
+- **技能名称**：小写字母 + 连字符（如 `update-provider-model`）
+- **功能描述**：这个技能解决什么问题，什么场景触发
+
+### 1.2 验证项目中有无实践基础
+
+在项目中查找该技能涉及的实际文件、代码模式或已有工作流：
+
+```bash
+# 查找相关代码或文档
+# 如果找不到任何相关实践，说明该技能尚未经项目验证
+```
+
+**关键判断**：如果项目中没有该技能所需的代码示例或实际操作案例，则**拒绝创建**，并向用户说明原因——未经实践验证的技能只会产生空洞的文档。
+
+### 1.3 检查是否与现有技能重叠
+
+现有技能清单：
+
+```bash
+ls .claude/skills/*/SKILL.md
+```
+
+如果新技能与已有技能功能重叠，建议扩展现有技能而非新建。
+
+---
+
+## 第二步：确定技能结构
+
+### 2.1 选择参考模板
+
+根据技能类型选择最接近的现有技能作为参考：
+
+| 技能类型 | 参考 | 特点 |
+|---------|------|------|
+| 外部信息采集 + 代码变更 | [update-provider-model]({baseDir}/../update-provider-model/SKILL.md) | 多步骤、有子资源目录、委托 Agent |
+| 配置校验 + 可选修复 | [review-provider-model]({baseDir}/../review-provider-model/SKILL.md) | 比对报告、分级处理 |
+| 需求分析 + 方案评审 + 执行 | [evolve]({baseDir}/../evolve/SKILL.md) | 核心原则前置、必须用户确认 |
+| CI/CD 操作流 | [release]({baseDir}/../release/SKILL.md) | 参数驱动、前置检查链、状态监控 |
+
+### 2.2 确定目录布局
+
+```
+.claude/skills/{skill-name}/
+├── SKILL.md              # 必需：技能入口
+├── {resource}.md          # 可选：辅助资源（如 testing.md）
+└── {subdir}/              # 可选：按类别组织的子资源（如 providers/）
+```
+
+子资源仅在技能确实需要外部参考材料时创建，不要预设空目录。
+
+---
+
+## 第三步：编写 SKILL.md
+
+### 3.1 Frontmatter
+
+```yaml
+---
+name: {skill-name}                    # 小写 + 连字符，不超过 64 字符
+description: {中文描述，说明功能和触发场景}  # 不超过 1024 字符
+user-invocable: true
+argument-hint: {参数格式提示}
+allowed-tools: {技能需要的工具列表}
+---
+```
+
+**description 要点**：
+- 使用中文（与本项目交互语言一致）
+- 说清两件事：(1) 做什么 (2) 什么时候用
+- 参考现有技能的 description 风格
+
+### 3.2 正文结构
+
+遵循本项目已有技能的统一风格——**分步编号工作流**：
+
+```markdown
+# 技能标题
+
+一句话概括技能职责。
+
+输入：$ARGUMENTS
+
+---
+
+## 核心原则（可选，仅当技能有重要的决策边界时）
+
+## 第一步：{动作}
+### 1.1 {子步骤}
+### 1.2 {子步骤}
+
+## 第二步：{动作}
+...
+
+## 快速参考（可选）
+```
+
+### 3.3 编写要领
+
+**每一步应包含**：
+1. 这一步的目标（做什么、为什么）
+2. 具体操作（引用项目文件，或给出命令模板）
+3. 输出判断（成功 / 失败的标准，下一步的分支条件）
+
+**引用而非摘录**：
+
+```markdown
+# 好 — 链接到实际文件
+详细的测试指南见 [testing.md](testing.md)。
+
+# 坏 — 在 SKILL 中复制代码
+\```python
+# 从 testing.md 复制的 50 行测试代码...
+\```
+```
+
+**在步骤中自然体现模式**：
+
+```markdown
+## 第四步：验证
+
+运行全量 QA 确保无回归：
+
+\```bash
+uv run poe qa
+\```
+
+所有检查必须通过。如有失败，修复后重新运行。
+```
+
+而不是单独设置一个"最佳实践"章节罗列"应该跑 QA"。
+
+---
+
+## 第四步：创建文件
+
+### 4.1 写入 SKILL.md
+
+使用 Write 工具创建 `.claude/skills/{skill-name}/SKILL.md`。
+
+### 4.2 创建子资源（如需要）
+
+仅当技能确实需要辅助材料时才创建。
+
+### 4.3 验证清单
+
+创建完成后逐项检查：
+
+- [ ] SKILL.md 位于 `.claude/skills/{skill-name}/` 目录
+- [ ] Frontmatter 包含 name、description、user-invocable、argument-hint、allowed-tools
+- [ ] name 使用小写字母和连字符
+- [ ] description 使用中文，说清功能和触发场景
+- [ ] 正文是分步编号工作流，与现有技能风格一致
+- [ ] 引用了项目中实际存在的文件，而非摘录代码
+- [ ] 没有空洞的"最佳实践"堆砌，模式融入步骤中
+
+---
+
+## 命名规范
+
+```
+update-provider-model    # 动词-名词，清晰的功能描述
+review-provider-model    # 同上
+create-skill             # 同上
+release                  # 单词足够清晰时可省略
+
+# 避免
+SkillCreator             # 不要大写
+skill_creator            # 不要下划线
+my-awesome-skill         # 不要修饰词
+```
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 修正 |
+|------|------|------|
+| SKILL 内容空洞，全是抽象原则 | 没有结合项目实际操作 | 每一步引用具体文件和命令 |
+| 大段代码摘录 | 复制了源文件内容 | 改为 Markdown 链接到源文件 |
+| 与现有技能功能重叠 | 没有先检查已有技能 | 扩展现有技能，不要新建 |
+| 创建了项目中无实践基础的技能 | 跳过了可行性验证 | 先有实践，再提炼技能 |