dependency-resolver

依赖解析器技能

目的

此技能会在推送前检测并解决本地与 CI 环境不一致的问题，避免 DISCOVERIES.md 中记录的 20–45 分钟调试周期（“CI Failure Resolution Process Analysis”条目）。

此技能弥补了一个关键缺口：现有工具（ci-diagnostic-workflow、pre-commit-diagnostic）会在问题发生后才进行修复。此技能则会在推送前发现不一致问题。

问题说明

根据 DISCOVERIES.md 的分析：

• 环境不一致（本地 Python 3.12 与 CI Python 3.11）会导致 20–25 分钟的排查耗时
• 版本漂移（本地 ruff 0.12.7 与 CI ruff 0.13.0）会导致静默失败
• 复杂调试会话耗时 45 分钟，最终发现根因是依赖冲突
• 尚无自动化的推送前环境比较机制

执行说明

激活后，自主执行以下步骤：

步骤 1：收集本地环境

# Python version
python --version

# Installed tool versions
pip show ruff black pyright mypy 2>/dev/null | grep -E "^(Name|Version):"

# Pre-commit hook versions (if available)
cat .pre-commit-config.yaml 2>/dev/null | grep -E "rev:|repo:"

步骤 2：读取 CI 配置

Read(file_path=".github/workflows/ci.yml")
Read(file_path="pyproject.toml")
Read(file_path=".pre-commit-config.yaml")

提取：

• CI Python 版本（查找 python-version:）
• pyproject.toml 中要求的工具版本
• .pre-commit-config.yaml 中的 pre-commit 钩子版本

步骤 3：比较环境

构建比较表：

组件	本地	CI	状态
Python	3.12.10	3.11	不一致
ruff	0.12.7	0.13.0	不一致
black	24.3.0	24.3.0	正常

步骤 4：生成建议

针对每项不一致，提供可执行的修复方案：

Python 版本不一致：

# Option A: Use pyenv to match CI version
pyenv install 3.11
pyenv local 3.11

# Option B: Update CI to match local (if local is intentional)
# Edit .github/workflows/ci.yml line 33

工具版本不一致：

# Pin versions in pyproject.toml
pip install ruff==0.13.0

# Or update pre-commit hooks
pre-commit autoupdate

步骤 5：自动修复（按需执行）

如果用户请求自动修复：

1. 使用最新版本更新 .pre-commit-config.yaml
2. 运行 pre-commit autoupdate
3. 如适用，重新生成 requirements.txt
4. 将更改暂存以供提交

集成点

与 fix-agent 集成

集成 fix-agent 模板，用于：

• 导入/依赖修复（模板 1）
• 配置修复（模板 2）
• CI/CD 修复（模板 4）

与 pre-commit-diagnostic 集成

版本同步后检测到 pre-commit 失败时移交处理。

与 ci-diagnostic-workflow 集成

移交处理推送后发生、且推送前验证未捕获的 CI 失败。

常见不一致模式

模式 1：Python 次版本漂移

症状：

• 仅在 CI 中出现类型错误
• 使用较新语法时出现导入错误
• f-string 问题

修复：

# Check CI Python version
grep -r "python-version" .github/workflows/

# Match locally or update CI

模式 2：Linter 版本漂移

症状：

• “本地运行正常，但 CI 检查失败”
• CI 中启用了本地未执行的新规则
• 格式差异

修复：

# Sync pre-commit hooks to latest
pre-commit autoupdate

# Or pin specific version
pip install ruff==<ci-version>

模式 3：缺少依赖

症状：

• CI 中出现 ModuleNotFoundError
• 未安装可选依赖

修复：

# Install all optional dependencies
pip install -e ".[dev]"

# Ensure requirements.txt is up to date
pip freeze > requirements.txt

输出格式

## Dependency Resolver Report

### Environment Comparison

| Component | Local   | CI      | Status   |
| --------- | ------- | ------- | -------- |
| Python    | 3.12.10 | 3.11    | MISMATCH |
| ruff      | 0.12.7  | 0.13.0  | MISMATCH |
| pyright   | 1.1.350 | 1.1.350 | OK       |

### Mismatches Found: 2

### Recommendations

1. **Python Version** (CRITICAL)
   - Local: 3.12.10, CI: 3.11
   - Action: Consider using pyenv to test with CI version before push
   - Risk: Type syntax differences may cause failures

2. **ruff Version** (WARNING)
   - Local: 0.12.7, CI: 0.13.0
   - Action: Run `pip install ruff==0.13.0` or `pre-commit autoupdate`
   - Risk: New rules may flag previously passing code

### Quick Fix Commands

```bash
# Sync ruff version
pip install ruff==0.13.0

# Update all pre-commit hooks
pre-commit autoupdate

# Re-run pre-commit to validate
pre-commit run --all-files
```

### Status: ACTION REQUIRED

Push may fail due to environment mismatches.
Run recommended fixes before pushing.

何时使用此技能

触发信号：

• “CI 失败了，但本地运行正常”
• “这里的 lint 检查通过了，但 CI 中没有通过”
• 长时间开发后，推送之前
• 更新本地 Python 或工具之后
• 开始参与新项目时

无需使用的情况：

• CI 已持续稳定通过
• 环境刚完成同步
• 只编辑文档

相关资源

• DISCOVERIES.md：CI Failure Resolution Process Analysis（第 836–914 行）
• fix-agent.md：用于导入/配置/CI 修复的模板
• ci-diagnostic-workflow.md：推送后的 CI 失败处理
• pre-commit-diagnostic.md：pre-commit 钩子失败
• .github/workflows/ci.yml：CI 配置的真实来源

理念契合

极致简洁

• 采用流程化方法：五个清晰步骤，不做不必要的抽象
• 直接使用 shell 命令：用户可以复制粘贴建议
• 范围明确：只检测环境不一致问题，修复工作交由现有 Agent 处理

拒绝空谈的实现方式

• 输出可执行：每条建议都包含准确命令
• 不提供理论性建议：给出具体版本号和文件路径
• 推送前预防：在 CI 周期浪费时间之前捕获问题

模块化设计

• 清晰的任务交接：与 fix-agent、pre-commit-diagnostic、ci-diagnostic-workflow 集成
• 单一职责：仅负责检测和比较；修复工作交由专用 Agent 处理
• 可重新生成：可根据此规范重新构建