kscz0000 仓库维护者 — 冠军级仓库卫生
"当刹车必须完美无瑕时，我们的仓库也必须如此。"
何时使用此技能
在以下情况激活：
- 用户输入
/repo-maintainer或/maintain - 用户说"清理这个仓库"或"审计仓库"
- 开始对仓库进行维护时
- 大规模重构之后或发布之前
- 每月/每季度仓库健康检查
- 接手新代码库时
此技能的功能
🔍 阶段一：全面审计
系统性地检查 7 个关键领域：
1. 产物检测
# 查找测试产物
*.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. 依赖健康
# 检查包健康状况
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 对齐
# 工作流一致性检查
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. 文档同步
# 上下文对齐检查
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 卫生
# .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
模式识别：
# Add to .gitignore based on artifacts found
*.config.mjs
*.faf.backup
.faf-dna.tmp
test-*.faf
6. 代码质量信号
# 快速健康指标
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 项目：
# 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 服务器：
# 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)
🛠️ 阶段二：清理计划生成
审计完成后，生成优先级排序的任务列表：
# 🏎️ 仓库健康报告: 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"
工作流
步骤一：初步评估
# Quick health check
pwd
git status
git log --oneline -5
ls -la | head -20
步骤二：系统性审计
按优先级顺序运行检查：
- 先处理严重项 — CI/CD 故障、安全问题
- 再处理中等项 — 依赖、文档缺失
- 最后处理低优先级 — 代码质量信号、锦上添花项
步骤三：生成报告
创建结构化报告，包含：
- 综合健康评分（0-100%）
- 严重/中等/低优先级分区
- 工作量估算
- 自动修复可用性
- 建议行动计划
步骤四：执行（需批准）
询问用户：
- "对安全项运行自动修复？"
- "创建清理分支？"
- "为手动项创建 issue？"
未经明确批准，绝不进行任何更改。
MCP 服务器维护
额外 MCP 检查：
# 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)
冠军承诺
"赛车维修团队在每场比赛之间都会维护赛车。 你的仓库值得同样的关注。"
仓库维护者 — 冠军级仓库卫生 "当刹车必须完美无瑕时，我们的仓库也必须如此。"
局限性
- 仅当任务明确匹配其上游来源和本地项目上下文时使用此技能。
- 在应用更改之前，验证命令、生成的代码、依赖项、凭证和外部服务行为。
- 不要将示例替代针对特定环境的测试、安全审查或用户对破坏性/高成本操作的批准。