dependency-resolver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependency Resolver Skill

Purpose

用途

This skill detects and resolves local vs CI environment mismatches BEFORE push, preventing the 20-45 minute debug cycles documented in DISCOVERIES.md ("CI Failure Resolution Process Analysis" entry).

The skill addresses a critical gap: existing tools (ci-diagnostic-workflow, pre-commit-diagnostic) fix issues AFTER they occur. This skill catches mismatches BEFORE push.

该Skill可在推送前检测并解决本地与CI环境的不匹配问题，避免DISCOVERIES.md中记录的20-45分钟调试周期（对应“CI故障解决流程分析”条目）。

此Skill填补了一个关键空白：现有工具（ci-diagnostic-workflow、pre-commit-diagnostic）都是在问题发生后才进行修复，而该Skill能在推送前就发现不匹配问题。

Problem Statement

问题陈述

From DISCOVERIES.md analysis:

Environment mismatches (Local Python 3.12 vs CI Python 3.11) cause 20-25 min investigation overhead
Version drift (local ruff 0.12.7 vs CI ruff 0.13.0) causes silent failures
45-minute complex debugging sessions traced to dependency conflicts
No automated pre-push environment comparison exists

基于DISCOVERIES.md的分析：

环境不匹配（本地Python 3.12 vs CI Python 3.11）会导致20-25分钟的调查耗时
版本漂移（本地ruff 0.12.7 vs CI ruff 0.13.0）会引发静默故障
长达45分钟的复杂调试会话根源在于依赖冲突
目前不存在自动化的预推送环境对比工具

Execution Instructions

执行说明

When activated, execute these steps autonomously:

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

Step 1: Collect Local Environment

步骤1：收集本地环境信息

bash

undefined

bash

undefined

Python version

Python版本

python --version

Installed tool versions

已安装工具版本

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

Pre-commit hook versions (if available)

Pre-commit钩子版本（若可用）

cat .pre-commit-config.yaml 2>/dev/null | grep -E "rev:|repo:"

undefined

cat .pre-commit-config.yaml 2>/dev/null | grep -E "rev:|repo:"

undefined

Step 2: Read CI Configuration

步骤2：读取CI配置

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

Extract:

CI Python version (look for
```
python-version:
```
)
Required tool versions from pyproject.toml
Pre-commit hook versions from .pre-commit-config.yaml

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钩子版本

Step 3: Compare Environments

步骤3：对比环境信息

Build comparison table:

Component	Local	CI	Status
Python	3.12.10	3.11	MISMATCH
ruff	0.12.7	0.13.0	MISMATCH
black	24.3.0	24.3.0	OK

构建对比表格：

组件	本地版本	CI版本	状态
Python	3.12.10	3.11	不匹配
ruff	0.12.7	0.13.0	不匹配
black	24.3.0	24.3.0	正常

Step 4: Generate Recommendations

步骤4：生成修复建议

For each mismatch, provide actionable fix:

Python Version Mismatch:

bash

undefined

针对每个不匹配项，提供可执行的修复方案：

Python版本不匹配：

bash

undefined

Option A: Use pyenv to match CI version

选项A：使用pyenv匹配CI版本

pyenv install 3.11 pyenv local 3.11

Option B: Update CI to match local (if local is intentional)

选项B：更新CI配置以匹配本地版本（若本地版本为有意升级）

Edit .github/workflows/ci.yml line 33

编辑.github/workflows/ci.yml第33行


**Tool Version Mismatch:**

```bash


**工具版本不匹配：**

```bash

Pin versions in pyproject.toml

在pyproject.toml中锁定版本

pip install ruff==0.13.0

Or update pre-commit hooks

或更新pre-commit钩子

pre-commit autoupdate

undefined

pre-commit autoupdate

undefined

Step 5: Auto-Fix (When Requested)

步骤5：自动修复（当用户请求时）

If user requests auto-fix:

Update .pre-commit-config.yaml with latest versions
Run
```
pre-commit autoupdate
```
Regenerate requirements.txt if applicable
Stage changes for commit

若用户请求自动修复：

使用最新版本更新.pre-commit-config.yaml
运行
```
pre-commit autoupdate
```
若适用，重新生成requirements.txt
暂存待提交的变更

Integration Points

集成点

With fix-agent

与fix-agent集成

Integrates with fix-agent templates for:

Import/dependency fixes (Template 1)
Configuration fixes (Template 2)
CI/CD fixes (Template 4)

可与fix-agent模板集成，用于：

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

With pre-commit-diagnostic

与pre-commit-diagnostic集成

Hand-off when pre-commit failures detected after version sync.

当版本同步后仍检测到pre-commit失败时，可移交至该工具处理。

With ci-diagnostic-workflow

与ci-diagnostic-workflow集成

Hand-off for post-push CI failures not caught by pre-push validation.

对于预推送验证未捕获的推送后CI故障，可移交至该工作流处理。

Common Mismatch Patterns

常见不匹配模式

Pattern 1: Python Minor Version Drift

模式1：Python小版本漂移

Symptoms:

Type errors only in CI
Import errors with newer syntax
f-string issues

Fix:

bash

undefined

症状：

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

修复方案：

bash

undefined

Check CI Python version

查看CI Python版本

grep -r "python-version" .github/workflows/

Match locally or update CI

在本地匹配CI版本或更新CI配置

undefined

undefined

Pattern 2: Linter Version Drift

模式2：Linter版本漂移

Symptoms:

"Works locally but CI fails on linting"
New rules in CI not enforced locally
Formatting differences

Fix:

bash

undefined

症状：

"本地运行正常但CI linting失败"
CI中启用了本地未强制执行的新规则
代码格式不一致

修复方案：

bash

undefined

Sync pre-commit hooks to latest

将pre-commit钩子同步至最新版本

pre-commit autoupdate

Or pin specific version

或锁定特定版本

pip install ruff==<ci-version>

undefined

pip install ruff==<ci-version>

undefined

Pattern 3: Missing Dependencies

模式3：缺失依赖

Symptoms:

ModuleNotFoundError in CI
Optional dependencies not installed

Fix:

bash

undefined

症状：

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

修复方案：

bash

undefined

Install all optional dependencies

安装所有可选依赖

pip install -e ".[dev]"

Ensure requirements.txt is up to date

确保requirements.txt是最新的

pip freeze > requirements.txt

undefined

pip freeze > requirements.txt

undefined

Output Format

输出格式

markdown

undefined

markdown

undefined