# Repo Maintainer

> 冠军级仓库维护。审计测试产物、依赖问题、CI/CD 健康状况、文档同步及 FAF 对齐情况。生成优先级排序的清理计划。当仓库需要深度清理或持续维护时使用。触发词：清理仓库、审计仓库、repo-maintainer、/maintain、仓库健康检查、依赖审计、CI/CD 检查

- Skill: `kscz0000/repo-maintainer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/repo-maintainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/repo-maintainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/repo-maintainer

---


# 仓库维护者 — 冠军级仓库卫生

**"当刹车必须完美无瑕时，我们的仓库也必须如此。"**

---

## 何时使用此技能

在以下情况激活：
- 用户输入 `/repo-maintainer` 或 `/maintain`
- 用户说"清理这个仓库"或"审计仓库"
- 开始对仓库进行维护时
- 大规模重构之后或发布之前
- 每月/每季度仓库健康检查
- 接手新代码库时

## 此技能的功能

### 🔍 **阶段一：全面审计**

系统性地检查 7 个关键领域：

#### 1. **产物检测**
```bash
# 查找测试产物
*.test.js leftovers
*.spec.ts.snap orphans
.DS_Store files
tmp/, temp/, cache/ directories
coverage/ not in .gitignore
dist/, build/ committed by accident
node_modules/ somehow in git
```

**检测策略：**
- 检查 `git status` 中的未追踪模式
- 扫描常见产物扩展名
- 与 .gitignore 对比
- 在工作目录中查找大文件（>1MB）

#### 2. **依赖健康**
```bash
# 检查包健康状况
npm outdated
npm audit
npx depcheck (find unused deps)
Check for pinned versions (inquirer@8.2.5 pattern)
Verify Dependabot config
```

**危险信号：**
- 存在安全漏洞的包
- 已终止运行的版本（Node 16、Python 3.7）
- 重复依赖（lodash + lodash.merge）
- 未使用的依赖（已安装但从未导入）

#### 3. **CI/CD 对齐**
```bash
# 工作流一致性检查
Node versions across all workflows
Test matrices (should match across ci.yml, release.yml)
Action versions (@v6 vs @v5)
Failed/skipped workflow runs
Secrets/tokens properly configured
```

**常见修复：**
- 从发布工作流中移除已终止运行的版本（如 Node 16）
- 统一所有工作流中的 Node 版本（如 18/20/22）
- 锁定在 ESM 解析下会出问题的包

#### 4. **文档同步**
```bash
# 上下文对齐检查
README.md ↔ CLAUDE.md ↔ project.faf
CHANGELOG up to date with git tags
package.json version matches latest tag
Examples in README still work
Links not broken (404 checks)
```

**FAF 专项：**
- project.faf 反映当前状态
- CLAUDE.md 双向同步已激活
- .faf-dna 没有不必要的变动

#### 5. **Git 卫生**
```bash
# .gitignore 审计
Untracked files that should be ignored
  *.config.mjs
  *.faf test artifacts
  .env.local, .env.development
Large files in git history (use git-filter-repo)
Binary files that don't belong
```

**模式识别：**
```gitignore
# Add to .gitignore based on artifacts found
*.config.mjs
*.faf.backup
.faf-dna.tmp
test-*.faf
```

#### 6. **代码质量信号**
```bash
# 快速健康指标
Dead code (unused exports via ts-prune or depcheck)
TODO/FIXME comments (track count, prioritize)
Commented code blocks (remove or document)
Console.log statements in production code
Hardcoded secrets/tokens
```

#### 7. **FAF 生态健康**

专门针对 FAF 项目：
```yaml
# Check FAF alignment
.faf score accuracy (run faf score)
Bi-sync alignment — CLAUDE.md ↔ .faf (run `faf sync`; mtime auto-direction)
MCP server compliance (if applicable)
WJTTC test coverage (for faf-cli, MCP servers)
```

针对 MCP 服务器：
```bash
# MCP-specific checks
package.json has "mcp" field
Server implements required tools
Tests cover all tool endpoints
README has MCP installation instructions
Registry listing accurate (npm + MCP registry)
```

---

### 🛠️ **阶段二：清理计划生成**

审计完成后，生成优先级排序的任务列表：

```markdown
# 🏎️ 仓库健康报告: faf-cli

**综合评分：** 85% ◇ 铜牌
**状态：** 生产就绪，需少量清理

---

## 🚨 严重（立即修复）

### 1. 安全：`open@10` 导致 CI/CD 中断
- **影响：** 发布流水线失败
- **修复：** 锁定到 `open@8.4.2` ✅ 已修复
- **工作量：** 5 分钟
- **自动修复：** 可用

---

## ⚠️  中等（本周处理）

### 3. .gitignore 缺失项
- **问题：** `*.config.mjs`、`*.faf` 测试文件未被忽略
- **修复：** 将模式添加到 .gitignore
- **工作量：** 1 分钟
- **自动修复：** 可用
  ```gitignore
  *.config.mjs
  test-*.faf
  ```

---

## ℹ️  低优先级（锦上添花）

### 6. README 链接
- **问题：** 2 个指向旧文档的失效链接
- **修复：** 更新 URL
- **工作量：** 5 分钟

### 7. 未使用的依赖
- **问题：** `depcheck` 发现了未使用的包
- **修复：** 移除或说明保留原因

---

## ✅ 优秀项

- 测试覆盖率：799/799 通过
- TypeScript strict 模式：已启用
- FAF 评分：83%（良好）
- CI/CD：所有工作流已对齐
- 安全：无严重漏洞
- 文档：CLAUDE.md 已同步

---

## 🎯 建议操作

**快速收益：** .gitignore + CHANGELOG 条目 + README 链接 + 安全的 `npm update`。
**本周：** 分类 TODO、移除未使用的依赖、升级补丁版本。
**每月：** 完整依赖审计、大文件扫描、性能基线。

---

## 🔧 自动修复可用

我可以自动修复：
- ✅ .gitignore 添加
- ✅ CHANGELOG 草稿
- ✅ 安全的依赖更新
- ✅ 工作流对齐

**运行自动修复？** (yes/no)
```

---

### 🤖 **阶段三：自动修复（可选）**

针对安全的、非破坏性的修复：

```bash
# 1. Update .gitignore
cat >> .gitignore <<EOF

# Auto-added by repo-maintainer
*.config.mjs
*.faf.backup
.faf-dna.tmp
test-*.faf
EOF

# 2. Generate CHANGELOG entry from git log
git log v4.3.3..v4.4.0 --pretty=format:"- %s (%h)" >> CHANGELOG.draft.md

# 3. Safe dependency updates (non-breaking)
npm update --save

# 4. Create cleanup branch
git checkout -b repo-maintenance/$(date +%Y-%m-%d)
git add .gitignore CHANGELOG.md package.json package-lock.json
git commit -m "chore: repo maintenance - cleanup artifacts and update deps

- Add missing .gitignore patterns
- Update CHANGELOG with v4.4.0
- Safe dependency updates (patch/minor only)

Generated by /repo-maintainer skill"
```

---

## 工作流

### 步骤一：初步评估
```bash
# Quick health check
pwd
git status
git log --oneline -5
ls -la | head -20
```

### 步骤二：系统性审计

按优先级顺序运行检查：

1. **先处理严重项** — CI/CD 故障、安全问题
2. **再处理中等项** — 依赖、文档缺失
3. **最后处理低优先级** — 代码质量信号、锦上添花项

### 步骤三：生成报告

创建结构化报告，包含：
- 综合健康评分（0-100%）
- 严重/中等/低优先级分区
- 工作量估算
- 自动修复可用性
- 建议行动计划

### 步骤四：执行（需批准）

询问用户：
- "对安全项运行自动修复？"
- "创建清理分支？"
- "为手动项创建 issue？"

未经明确批准，绝不进行任何更改。

---

## MCP 服务器维护

### 额外 MCP 检查：

```bash
# 1. MCP-specific structure
package.json has "mcp" field
Server exports via index.ts
Tools properly registered

# 2. Registry compliance
Registry listing accurate (npm + MCP registry)
README has MCP install instructions
Works with Claude Desktop config

# 3. Tool coverage
Each tool has tests
Each tool has description
Error handling implemented

# 4. Version alignment
package.json version
git tag version
MCP registry version
npm published version
```

### MCP 清理清单：

- [ ] 移除测试产物
- [ ] 更新依赖
- [ ] 对齐工作流（Node 18/20/22）
- [ ] 验证 MCP 工具仍正常工作
- [ ] 更新 README 示例
- [ ] 检查 CHANGELOG 是否最新
- [ ] 验证已发布到 npm
- [ ] 确认注册列表信息准确

---

## ✪ 分层体系（与 FAF 对齐）

**关键：所有评分使用官方 FAF 分层**

| 评分 | 层级 | 符号 | 状态 |
|-------|------|--------|--------|
| 100% | 奖杯 | ✪ | 完美 — Gold Code |
| 99% | 金牌 | ★ | 卓越 |
| 95% | 银牌 | ◆ | 顶级 |
| 85% | 铜牌 | ◇ | 生产就绪 |
| 70% | 绿色 | ● | 基础扎实 |
| 55% | 黄色 | ● | 需要改进 |
| 1% | 红色 | ○ | 需要大量工作 |
| 0% | 白色 | ♡ | 空白 |

评分是**确定性的** — 相同输入 → 相同评分，每次如此。**FAF 不会说谎。**

**注意：** 🍊 **大橙色**是一种**荣誉**，而非评分或徽章。它认可在多个标准上的持续卓越表现；绝不从单一评分计算得出。

**将此分层体系应用于：**
- 仓库综合健康评分
- 各类别评分（CI/CD、依赖等）
- 摘要报告
- 清理建议

**示例：**
```
95% Security     → ◆ 银牌
88% Overall      → ◇ 铜牌
78% Dependencies → ● 绿色
70% Git Hygiene  → ● 绿色
40% CI/CD        → ○ 红色
100% Tests       → ✪ 奖杯
```

---

## 相关技能

- `/wjttc-builder` · `/wjttc-tester` — 在发布前生成并运行冠军级测试
- `/faf-expert` — 掌握 `.faf` 格式 + 为仓库的 AI 就绪度评分

---

## 最佳实践

### 1. **定期运行**
- 大规模重构之后
- 发布之前
- 每月维护
- 新开发者入职时

### 2. **优先处理高影响项**
- 先修复阻断性问题（CI/CD、安全）
- 先理解再清理（搞清楚产物存在的原因）
- 清理后测试（确保没有破坏任何东西）

### 3. **追踪进度**
- 使用 TodoWrite 进行多步骤清理
- 为手动项创建 issue
- 在 CLAUDE.md 中记录决策

### 4. **在安全的地方自动化**
- .gitignore 添加 ✅
- CHANGELOG 草稿 ✅
- 工作流对齐 ✅
- 破坏性变更 ❌（需要审查）

---

## 示例会话

```
User: /repo-maintainer

Claude: 🏎️ 开始冠军级仓库维护审计...

[Runs git status]
[Checks workflows]
[Scans for artifacts]
[Runs npm outdated]
[Checks .gitignore]

📊 审计完成

综合健康度: 85% ◇ 铜牌
严重问题: 2
中等问题: 3
低优先级: 5

首要问题:
1. 🚨 open@10 导致 CI/CD 中断（可自动修复）
2. 🚨 工作流中存在 Node 16（已终止运行）
3. ⚠️  .gitignore 缺少 *.config.mjs
4. ⚠️  15 个过时依赖
5. ⚠️  CHANGELOG 缺少 v4.4.0

我可以自动修复第 1、2、3 项，并起草第 5 项。
是否继续？ (yes/no)

User: yes

Claude: ✅ 修复中...
[Pins open@8.4.2]
[Updates workflows to Node 20]
[Adds .gitignore patterns]
[Drafts CHANGELOG entry]

✅ 自动修复完成！

剩余手动项：
- 审查 15 个依赖更新
- 3 条 TODO 注释需要审查

创建清理分支？ (yes/no)
```

---

## 冠军承诺

> "赛车维修团队在每场比赛之间都会维护赛车。
> 你的仓库值得同样的关注。"

---

*仓库维护者 — 冠军级仓库卫生*
*"当刹车必须完美无瑕时，我们的仓库也必须如此。"*

## 局限性

- 仅当任务明确匹配其上游来源和本地项目上下文时使用此技能。
- 在应用更改之前，验证命令、生成的代码、依赖项、凭证和外部服务行为。
- 不要将示例替代针对特定环境的测试、安全审查或用户对破坏性/高成本操作的批准。