@dependfix/skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaoMeiYouRen <https://github.com/CaoMeiYouRen>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @dependfix/skills
+
+dependfix 产品 Agent Skill 权威源（`dependfix-remediator`），随 npm 发布。
+
+## 这是什么
+
+`dependfix-remediator` 是面向最终用户的 Agent Skill：把 dependfix 的安全告警修复能力封装为 AI 助手可直接执行的编排指令（拉告警 → 研判 → 修复 → 报告），支持 Claude Code / GitHub Copilot / Cursor / OpenCode 等主流 agent 工具加载。
+
+## 安装方式
+
+主通道（npx skills 生态，推荐）：
+
+```bash
+npx skills add dependfix/dependfix -s dependfix-remediator -g -a claude-code -a opencode -a cursor
+```
+
+离线兜底（依赖 dependfix CLI，无 npx skills 环境）：
+
+```bash
+npx dependfix skills install
+```
+
+## 内容
+
+- `dependfix-remediator/SKILL.md` — 编排主体（能力契约 + 执行后端探测 + 决策树 + 场景编排）
+- `dependfix-remediator/REFERENCES.md` — CLI 命令参考与 MCP 双后端衔接（一致性断言清单）
+
+仓库根 `skills/dependfix-remediator/` 为 npx skills 生态分发副本，由 `scripts/sync-skills.mjs` 镜像同步（禁止直接编辑，一致性由测试保证）。
+
+## 开发
+
+```bash
+pnpm sync:skills    # 同步权威源到仓库根分发目录（scripts/sync-skills.mjs）
+pnpm test           # 一致性 / frontmatter 规范 / MCP 契约测试（packages/skills/test/）
+```

package/dependfix-remediator/REFERENCES.md

@@ -0,0 +1,142 @@
+# dependfix CLI 命令参考
+
+> 本文件是 dependfix-remediator skill 的详细参考，由 SKILL.md 按需引用。
+> 完整参数以 `npx dependfix --help` 输出为准。
+
+## 运行模式（positional）
+
+| 模式 | 说明 |
+|------|------|
+| `report-only` | 只读扫描，输出报告，不修改文件（默认） |
+| `fix` | 修复 + 本地验证，不提交不推送 |
+| `fix-and-pr` | 修复 + 创建修复分支与 PR |
+| `cleanup-branches` | 列出 / 清理已合并的 dependfix 修复分支 |
+
+## 完整参数表
+
+### 仓库与范围
+
+| 参数 | 说明 |
+|------|------|
+| `--repo, -r` | 目标仓库 `owner/repo`，逗号分隔多个 |
+| `--repos-file` | 从文件读取仓库列表（每行一个 owner/repo） |
+| `--owner` | owner / org 自动发现（逗号分隔多个或多次传入） |
+| `--repo-topics` | 发现结果 topic 白名单（逗号分隔，AND 语义） |
+| `--repo-include` | 仓库白名单 glob（如 `owner/*`、`owner/pkg-*`） |
+| `--repo-exclude` | 仓库黑名单 glob（与 include 冲突时胜出） |
+| `--repo-topics-exclude` | 发现结果 topic 黑名单 |
+
+### 凭据与数据源
+
+| 参数 | 说明 |
+|------|------|
+| `--github-token` | GitHub PAT（多仓库 / PR / Code Scanning 均可用） |
+| `--alerts-token` | Dependabot alerts 专用最小权限 PAT（缺省回退 `--github-token`） |
+| `--alerts-source` | `github-dependabot`（默认）或 `pnpm-audit`（本地无 token 回退） |
+| `--code-scanning` | 并行拉取 Code Scanning 告警（需 `security-events: read`） |
+
+环境变量：`GITHUB_TOKEN` / `DEPENDFIX_GITHUB_TOKEN`、`ALERTS_TOKEN` / `DEPENDFIX_ALERTS_TOKEN`、`DEPENDFIX_AI_API_KEY`。
+
+### 修复行为
+
+| 参数 | 说明 |
+|------|------|
+| `--severity-threshold` | critical / high / medium / all，默认 high |
+| `--dry-run` | 预演模式，不写文件 |
+| `--commit` | 修复后本地当前分支直接提交（不推送、不创建 PR） |
+| `--create-pr` | 创建 Pull Request |
+| `--allow-major-upgrade` | 跨线告警显式授权自动升级（仅 CLI；workspace 成员独占声明 / 多版本共存维持人工） |
+| `--upgrade-groups` | 显式分组，格式 `name1:pkg1,pkg2;name2:pkg3` |
+| `--max-alerts-per-repository` | 每仓库最多处理告警数，默认 20 |
+| `--commands` | 自定义验证命令（逗号分隔），覆盖默认 install/lint/build |
+| `--toolchain-pnpm-version` | lockfile 修复用的 pnpm 版本 |
+
+### 多仓库并发
+
+| 参数 | 说明 |
+|------|------|
+| `--max-concurrency` | 并发窗口 1-16，默认 1（保守串行，>1 可能触发 GitHub 限流） |
+| `--max-retries` | 限流重试次数 0-10，默认 3 |
+| `--max-backoff-ms` | 退避单次等待上限毫秒，默认 30000 |
+
+### AI breaking change 研判
+
+| 参数 | 说明 |
+|------|------|
+| `--ai` | 开启 AI 研判（默认关闭；dry-run 不触发、不产生费用） |
+| `--ai-provider` | `openai-compatible`（默认）或 `anthropic` |
+| `--ai-model` | 模型名（默认 deepseek-v4-flash） |
+| `--ai-base-url` | OpenAI 兼容端点基地址（默认 https://api.deepseek.com） |
+| `--ai-api-url` | Anthropic 兼容端点（仅 anthropic 生效） |
+| `--ai-api-key` | API Key（优先 `DEPENDFIX_AI_API_KEY` env） |
+| `--ai-trigger` | 触发范围：failure / major / both（默认 both） |
+
+### 其他
+
+| 参数 | 说明 |
+|------|------|
+| `--history` | 查询仓库历史运行摘要（读 `dependfix-reports/index.json`，不执行扫描） |
+| `--verbose` | 输出详细日志 |
+
+## 数据源说明
+
+- **github-dependabot**：从 GitHub Dependabot alerts API 拉取。需要 PAT（`Dependabot alerts: read` / `security_events`）或 GitHub App token；`GITHUB_TOKEN`（secrets 默认 token）无法读取。
+- **code-scanning**：从 GitHub Code Scanning alerts API 拉取，与 Dependabot 并行（追加 `--code-scanning`）。`GITHUB_TOKEN` 默认具备 `security-events: read`，可直接使用。
+- **pnpm-audit**：本地无 token 场景，扫描当前工作区 lockfile；repository 优先 `--repo` → git remote → 本地目录兜底。
+
+## 报告产物
+
+- 每次运行生成 Markdown 报告，落盘于 `dependfix-reports/` 目录。
+- `dependfix-reports/index.json` 维护历史摘要（供 `--history` 查询与趋势统计）。
+- 报告包含：扫描范围、告警明细、修复/未修复清单、验证结果、AI 研判用量（如开启）。
+
+## 常见问题
+
+| 现象 | 处置 |
+|------|------|
+| `Missing GitHub token` | 设置 `GITHUB_TOKEN` / `DEPENDFIX_GITHUB_TOKEN`，或改用 `--alerts-source pnpm-audit` |
+| Dependabot alerts 拉取 404 / 403 | token 缺少 `Dependabot alerts: read` / `security_events` 权限 |
+| 升级验证失败 | 自动回滚该依赖并记为未修复（人工处理） |
+| 429 / rate limit | 默认指数退避重试 3 次；可调 `--max-retries` / `--max-backoff-ms` |
+| AI 研判开启但缺 Key | 设置 `DEPENDFIX_AI_API_KEY` 或 `--ai-api-key` |
+
+## MCP 双后端衔接（后续 MCP 交付扩展点）
+
+> 本文档定义 SKILL.md"执行后端探测"的细节与双后端一致性验证基准。
+> 当前 MCP Server 未发布（规划于后续里程碑），本 skill 全部走 CLI；MCP 发布后无需改版即可双后端工作。
+
+### 探测方法明细
+
+| 环境 | 检测方式 |
+|------|---------|
+| Claude Code | `claude mcp list`；或项目根 `.mcp.json` 的 `mcpServers` 字段含 dependfix server |
+| OpenCode | `opencode.json` / `~/.config/opencode/opencode.json` 的 `mcp` 配置含 dependfix server |
+| 通用 | 当前会话工具列表中存在以下 4 个 tool 即视为 MCP 后端可用 |
+
+### MCP tool 映射明细
+
+| 能力 | MCP tool | 入参要点 | CLI 对应 |
+|------|----------|---------|---------|
+| 拉取告警 | `fetch_alerts` | `owner`、`repo`（或多仓库列表）、`severityThreshold`、`includeCodeScanning` | `dependfix report-only` |
+| 扫描并修复 | `run_scan` | `repo`、`mode`（fix / fix-and-pr）、`severityThreshold`、`dryRun` | `dependfix fix` / `fix-and-pr` |
+| 修复指定依赖 | `fix_dependency` | `repo`、`dependency`、`createPr`、`allowMajorUpgrade` | `dependfix fix`（分组指定） |
+| 查询历史报告 | `get_last_report` | `repo`（缺省取最近一次） | `dependfix --history <owner/repo>` |
+
+> 说明：MCP tool 的最终入参 schema 以 MCP Server 实际交付为准；本表为能力契约映射的基准约定，MCP 实现不得改变各能力语义。MCP Server 交付时须与本表逐项核对（tool 名与入参 schema），确保"skill 无需改版"承诺闭环。
+
+### 双后端一致性断言清单（MCP 交付验证基准）
+
+以 `@dependfix/core` 报告契约为基准（RunResult JSON；`dependfix-reports/index.json` 历史条目为 CLI archiver 的派生格式），MCP tool 输出必须与 CLI 报告同源一致：
+
+| 能力 | CLI 侧契约基准（字段） | MCP 一致性断言 |
+|------|------------------------|---------------|
+| 拉取告警 | RunResult：`summary.alertsFound` / `summary.alertsFixable` / `repositories[].alertsCount` / `alerts[]` | `fetch_alerts` 返回的告警数与严重级别分布与 CLI 报告一致；`alerts[]` 明细字段（package/severity/manifest）与 RunResult 对齐 |
+| 扫描并修复 | RunResult：`summary.alertsFixed` / `alertsFailed` / `alertsSkipped` / `actions[]`（type=dependency-upgrade） | `run_scan` 返回的 fixed/failed/skipped 计数与 CLI 报告一致；`actions[]` 的 target/fromVersion/toVersion 对齐 |
+| 修复指定依赖 | RunResult：`actions[]` + `summary`（单仓库维度） | `fix_dependency` 返回的修复结果与 CLI 对同一依赖的修复记录一致（含 PR 链接如创建） |
+| 查询历史报告 | ArchiveRunEntry：`repoStats[]`（alertsCount/fixed/failed/durationMs）+ `runId` | `get_last_report` 返回与 `dependfix-reports/index.json` 对应条目同源（字段值一致） |
+
+### 降级路径规则
+
+1. 探测不到 MCP → 直接 CLI，不提示安装。
+2. MCP tool 调用失败（不存在 / 超时 / 服务端错误）→ 改用 CLI 完成同能力调用，并向用户说明降级原因。
+3. MCP 输出与 CLI 报告不一致（怀疑 MCP 缺陷）→ 以 CLI 报告为准，记录差异供后续修复。

package/dependfix-remediator/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: dependfix-remediator
+description: 自动拉取并修复 GitHub Dependabot / Code Scanning 安全告警：扫描仓库依赖漏洞、按严重级别研判、升级有漏洞的依赖、创建修复 PR、生成可审计报告。Use when 用户提到安全告警、dependabot、依赖漏洞、依赖升级、code scanning、pnpm audit、安全扫描、自动修复安全问题时使用。
+---
+
+# dependfix-remediator
+
+自动处理 GitHub 安全告警（Dependabot alerts / Code Scanning alerts）的修复工作流：拉取告警 → 研判 → 修复 → 报告，全链路闭环。
+
+## 能力契约与执行后端
+
+本 skill 只依赖以下能力契约，不绑定具体实现：
+
+| 能力 | 当前后端（dependfix CLI） | MCP 预留位 |
+|------|--------------------------|-----------|
+| 拉取告警 | `npx dependfix report-only` | fetch_alerts |
+| 修复依赖 | `npx dependfix fix` | run_scan / fix_dependency |
+| 修复并创建 PR | `npx dependfix fix-and-pr` | fix_dependency |
+| 查询历史报告 | `npx dependfix --history <owner/repo>` | get_last_report |
+| 清理已合并分支 | `npx dependfix cleanup-branches` | — |
+
+未配置 MCP 时全部走 CLI；MCP 接入后（后续版本）探测到 MCP 工具则优先调用，两条后端输出保持一致。本 skill 当前不依赖 MCP，CLI 后端开箱即用。
+
+## 执行后端探测
+
+开始编排前先确定执行后端（只需一次）：
+
+1. **检查当前会话是否已加载 dependfix MCP 工具**：工具列表中是否存在 `fetch_alerts` / `run_scan` / `fix_dependency` / `get_last_report`（server 前缀可能为 `dependfix` 或 `@dependfix/mcp`）。不确定时用命令确认：
+   - Claude Code：`claude mcp list`（或检查项目根 `.mcp.json` 的 `mcpServers`）
+   - OpenCode：检查 `opencode.json` / `~/.config/opencode/opencode.json` 的 `mcp` 配置
+2. **决策规则**：
+   - 4 个 MCP tool 均可用 → **MCP tool 优先**（按能力契约映射表调用，详见 [REFERENCES.md](REFERENCES.md)）
+   - 未配置 MCP 或探测不到 → **CLI 后端**（本 skill 默认路径）
+   - MCP 调用失败（tool 不存在 / 超时 / 报错）→ **降级 CLI 并告知用户**，不中断流程
+3. 两条后端的输出以同一份能力契约（报告结构见 [REFERENCES.md](REFERENCES.md) 一致性断言清单）为准，MCP 与 CLI 结果应一致；发现不一致时以 CLI 报告为准并记录。
+
+## 前置条件
+
+1. Node.js >= 20（检查：`node --version`）。
+2. 工作目录为 git 仓库（检查：`git rev-parse --is-inside-work-tree`）。
+3. 凭据（按场景）：
+   - GitHub 仓库：设置 `GITHUB_TOKEN` 或 `DEPENDFIX_GITHUB_TOKEN` 环境变量。注意 Dependabot alerts 需要 PAT 且具备 `Dependabot alerts: read` / `security_events` 权限，普通 `GITHUB_TOKEN` 无法读取 Dependabot alerts（Code Scanning 可用）。
+   - 本地无 token：使用 `--alerts-source pnpm-audit` 走本地 lockfile 扫描，无需 GitHub 凭据。
+
+## 工作流编排
+
+### 决策树
+
+收到用户请求后，先判断场景：
+
+- 只看告警，不修改 → **场景 A：只读扫描**
+- 自动修复（本地验证，不推送）→ **场景 B：自动修复**
+- 修复并创建 PR → **场景 C：修复 + PR**
+- 修复整个 owner / 仓库列表 → **场景 D：多仓库**
+- 本地仓库且无 GitHub token → **场景 E：pnpm audit**
+- 查看历史运行结果 → **场景 F：历史查询**
+- 清理已合并的修复分支 → **场景 G：分支清理**
+
+### 场景 A：只读扫描（报告）
+
+```bash
+npx dependfix report-only --repo <owner/repo> --severity-threshold high
+```
+
+- 拉取 Dependabot 告警并按严重级别过滤，输出 Markdown 报告到 `dependfix-reports/`，不修改任何文件。
+- 需要同时扫 Code Scanning：追加 `--code-scanning`。
+- 汇报：告警总数、严重级别分布、修复建议摘要、报告路径。
+
+### 场景 B：自动修复（默认路径）
+
+```bash
+npx dependfix fix --repo <owner/repo> --severity-threshold high
+```
+
+- 自动升级可修复依赖 → 强制验证（install + lint + build）→ 生成报告。默认不提交不推送。
+- 需要本地提交时追加 `--commit`；需要预演时先加 `--dry-run`（只输出将要做的修改，不写文件）。
+- 汇报：修复的告警、验证结果、未修复（需人工处理）清单、报告路径。
+
+### 场景 C：修复 + 创建 PR
+
+```bash
+npx dependfix fix-and-pr --repo <owner/repo>
+```
+
+- 修复 + 自动创建修复分支与 PR（PR 去重、分组升级）。
+- 汇报：PR 链接 / 编号列表、报告路径。
+
+### 场景 D：多仓库治理
+
+```bash
+npx dependfix fix --owner <org> --severity-threshold high
+# 或从文件读取仓库列表（每行一个 owner/repo）：
+npx dependfix fix --repos-file repos.txt
+```
+
+- 自动发现 owner 下全部仓库（可用 `--repo-include` / `--repo-exclude` glob 过滤）。
+- 汇报：每个仓库的结果摘要与失败隔离情况。
+
+### 场景 E：本地无 token（pnpm audit）
+
+```bash
+npx dependfix fix --alerts-source pnpm-audit
+```
+
+- 在目标仓库内运行，基于本地 lockfile 扫描；目标仓库优先取 `--repo`，其次 git remote，最后当前目录。
+- 汇报：audit 告警数与修复结果。
+
+### 场景 F：历史报告查询
+
+```bash
+npx dependfix --history <owner/repo>
+```
+
+- 读取 `dependfix-reports/index.json` 摘要，不执行扫描。
+- 汇报：历史运行时间线及每次结果摘要。
+
+### 场景 G：清理已合并分支
+
+```bash
+npx dependfix cleanup-branches --repo <owner/repo>
+```
+
+- 列出已合并 / 已关闭的 dependfix 修复分支，交互确认后删除（非 TTY 环境默认拒绝删除）；`--dry-run` 仅列清单。
+- fix-and-pr 模式中追加 `--cleanup-branches-auto` 可在结束后非交互自动删除已合并 / 已关闭分支（CI 可用，不删有 open PR 的分支）。
+
+## 关键参数速查
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `--severity-threshold` | 严重级别阈值：critical / high / medium / all | high |
+| `--code-scanning` | 并行拉取 Code Scanning 告警 | 关闭 |
+| `--allow-major-upgrade` | 显式授权跨大版本自动升级（仅 CLI） | 关闭 |
+| `--max-alerts-per-repository` | 每个仓库最多处理告警数 | 20 |
+| `--ai` | 开启 AI breaking change 研判（需配置 API Key） | 关闭 |
+| `--dry-run` | 预演模式，不写文件不触发 AI | 关闭 |
+| `--alerts-source` | github-dependabot（默认）或 pnpm-audit | github-dependabot |
+
+完整参数与说明见 [REFERENCES.md](REFERENCES.md)。
+
+## 安全与执行纪律
+
+- Token 优先用环境变量（`GITHUB_TOKEN` / `DEPENDFIX_GITHUB_TOKEN` / `DEPENDFIX_AI_API_KEY`），避免命令行参数泄露到进程列表与 shell history。
+- 修复类操作前先确认仓库工作区干净（`git status`）；存在未提交改动时先与用户确认。
+- AI 研判默认关闭，开启会产生 API 费用，先与用户确认。
+- 跨线升级（`--allow-major-upgrade`）风险高，仅在用户明确要求时使用；升级失败会自动回滚。
+- 报告落盘在 `dependfix-reports/`，可归档、可审计，勿删除。
+
+## 完成汇报模板
+
+每次执行完向用户汇报：
+
+1. 扫描范围：仓库 / 数据源 / 严重级别阈值。
+2. 结果：修复 N 个告警，未修复 M 个（含原因与建议）。
+3. 验证状态：install / lint / build 是否通过。
+4. 产物：报告路径、PR 链接（如有）。

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dependfix/skills",
+  "version": "0.1.0",
+  "description": "dependfix 产品 Agent Skills 权威源（dependfix-remediator），随 npm 发布",
+  "author": "CaoMeiYouRen",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "skills",
+    "agent-skills",
+    "dependabot",
+    "security",
+    "dependfix"
+  ],
+  "homepage": "https://github.com/dependfix/dependfix#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dependfix/dependfix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dependfix/dependfix/issues"
+  },
+  "files": [
+    "dependfix-remediator",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}