By name: zcode-patrol
description: "定期对代码库进行自动化巡检，发现常见代码问题（风格漂移、架构腐化、安全漏洞、性能陷阱、重复代码等），生成结构化报告并推动修复，阻止代码熵增。"
argument-hint: "[--paths ...] [--scope full|delta|staged|targeted] [--format markdown|json] [--max-files 500] [--output-dir .zcode-patrol] [--min-severity P0|P1|P2|P3] [--baseline ]"
allowed-tools:
- Read
- Write
- Edit
- Bash
- Agent
zcode-patrol
代码熵巡检技能。对代码库执行自动化静态分析，发现质量退化问题，生成结构化报告。
1. 目标与非目标
1.1 目标
- 对代码库执行定期自动化静态分析，持续发现质量退化问题
- 聚合多维度代码问题（风格、架构、安全、性能、重复、文档、依赖、测试），生成结构化报告
- 通过基线对比追踪问题增量，阻止代码熵增
- 为人工审查和修复提供可验证的、带证据链的数据支撑
1.2 非目标
- 不替代 ESLint、Pylint、SonarQube（定位为补充/聚合层）
- 不做运行时分析或测试执行（纯静态分析）
- 不修改源文件（只读巡检）
- 不做 gate 决策（仅产出证据，不替人判断）
2. 输入/输出
2.1 输入
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--paths |
array | ["."] |
扫描的目录或文件路径 |
--scope |
enum | full |
扫描范围：full | delta | staged | targeted |
--format |
enum | markdown |
输出格式：markdown | json |
--max-files |
int | 500 | 最大扫描文件数 |
--output-dir |
string | .zcode-patrol |
输出目录 |
--min-severity |
enum | P3 |
最低严重级别：P0 | P1 | P2 | P3 |
--baseline |
string | null | 基线报告路径（用于对比） |
2.2 输出
| 产物 | Schema | 说明 |
|---|---|---|
report.json |
patrol-report.schema.json |
巡检报告 |
patrol-state.json |
patrol-state.schema.json |
执行状态 |
issues[] |
issue.schema.json |
问题列表 |
hotspots.json |
hotspots.schema.json |
问题热点聚合 |
baseline-diff.json |
baseline-diff.schema.json |
基线对比差异（仅当提供 --baseline） |
2.3 退出码
| 退出码 | 含义 |
|---|---|
| 0 | 巡检成功完成，未发现 issues 或所有 issues 低于 --min-severity |
| 1 | 巡检成功完成，但发现至少一个 issue 达到或高于 --min-severity |
3. 执行步骤
执行流程分为 5 个阶段：
- Initialize — 解析参数，生成
patrol_id，创建输出目录结构 - Discovery — 按
--scope展开文件列表，应用排除规则，写入manifest.json - Scan (L1 + L3) — L1 模式匹配 + L3 统计聚合，写入原始结果
- Aggregation & Enrichment — 去重合并、补充 git 元数据、计算质量分数、基线对比
- Reporting — 生成报告文件、热点分析、基线差异、最终状态
详细协议见下方 ## Execution Protocol。
Execution Model
本技能采用协作式执行架构：
| 组件 | 职责 |
|---|---|
| 外层 AI Agent | 完整流程编排：参数解析、文件发现、模式匹配、聚合、报告生成 |
| agents/*.md | Agent 角色定义（渐进式披露，按需加载） |
| evidence/*.json | 输出产物的 JSON Schema 契约 |
| validate.py | 输出产物的契约验证（可选） |
注意：本技能是纯 SKILL.md 实现，所有流程逻辑由外层 AI Agent 执行。
validate.py仅用于验证输出产物是否符合 JSON Schema 契约。
Parameters
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--paths |
array | ["."] |
扫描的目录或文件路径 |
--scope |
enum | full |
扫描范围：full | delta | staged | targeted |
--format |
enum | markdown |
输出格式：markdown | json |
--max-files |
int | 500 | 最大扫描文件数 |
--output-dir |
string | .zcode-patrol |
输出目录 |
--min-severity |
enum | P3 |
最低严重级别：P0 | P1 | P2 | P3 |
--baseline |
string | null | 基线报告路径（用于对比） |
Output Schema
所有输出产物必须符合以下 JSON Schema：
| 产物 | Schema | 说明 |
|---|---|---|
report.json |
patrol-report.schema.json |
巡检报告 |
patrol-state.json |
patrol-state.schema.json |
执行状态 |
issues[] |
issue.schema.json |
问题列表 |
Issue Schema（每条问题）
{
"id": "{patrol_id}-{rule_id}-{seq:04d}",
"rule_id": "如 D01-001",
"dimension": "D01 | D02 | D03 | D04 | D05 | D06 | D07 | D08",
"severity": "P0 | P1 | P2 | P3",
"file": "相对文件路径",
"line_start": 10,
"message": "问题描述",
"found_by": "L1-pattern-matching | L3-statistical-aggregation",
"confidence": 0.85
}
Patrol Dimensions
| ID | Name | Severity |
|---|---|---|
| D01 | Style Consistency | P2-P3 |
| D02 | Architecture Compliance | P0-P1 |
| D03 | Security Patterns | P0-P1 |
| D04 | Performance Anti-patterns | P1-P2 |
| D05 | Duplication & Dead Code | P2-P3 |
| D06 | Documentation Sync | P2-P3 |
| D07 | Dependency Health | P1-P2 |
| D08 | Test Coverage Drift | P1-P2 |
Execution Protocol
Initialize
- 解析参数，生成
patrol_id - 创建输出目录结构
- 解析参数，生成
Discovery
- 按
--scope展开文件列表 - 应用排除规则（.gitignore, node_modules 等）
- 写入
manifest.json
- 按
Scan (L1 + L3)
- L1 Pattern Matching: 应用规则集的正则/AST 规则
- L3 Statistical Aggregation: 运行外部工具（jscpd, vulture, pip-audit）
- 写入
raw/L1-results.json,raw/L3-results.json
Aggregation & Enrichment
- 去重合并跨层发现
- 补充 git 元数据（git blame）
- 计算质量分数
- 基线对比（如提供）
Reporting
- 生成
report.json+report.md - 生成
hotspots.json,baseline-diff.json - 写入最终
patrol-state.json
- 生成
Artifact Directory Structure
{output_dir}/{patrol_id}/
├── patrol-state.json
├── manifest.json
├── report.json
├── report.md
├── hotspots.json
├── baseline-diff.json (if baseline)
├── suggested-fixes.json (if fix_mode)
└── raw/
├── L1-results.json
└── L3-results.json
Validation
使用 validate.py 验证输出产物是否符合 Schema 契约：
# 验证整个巡检结果
python validate.py .zcode-patrol/20260527-120000-abc123def456
# 安装依赖
pip install jsonschema
Non-Negotiable Rules
- 不修改源文件（read-only）
- 不执行测试或运行时分析
- 不做 gate 决策（仅产出证据）
- 不捏造统计数据（计数必须匹配原始证据）
- 工具不可用时优雅跳过，不崩溃
Pitfalls / 常见坑与规避
| 坑 | 影响 | 规避 |
|---|---|---|
| max-files 超限截断 | 大仓库中 --max-files 500 默认截断导致遗漏关键文件，产生虚假"无问题"结论 |
首次扫描前用 find 估算文件量，按需调高；或按模块分批扫描 |
| baseline 路径漂移 | 基线文件被移动/删除后 --baseline 指向失效，对比逻辑静默跳过 |
在 CI 中将基线路径写入环境变量或缓存元数据；失效时主动报错而非跳过 |
| L3 工具未安装 | jscpd / vulture / pip-audit 等缺失时该维度空跑，漏报重复代码/死代码/依赖漏洞 | 在 Initialize 阶段检测工具可用性，缺失时写入 patrol-state.json 的 warnings 并提示安装 |
| severity 过滤过宽 | --min-severity P3 默认放行所有级别，高优先级 P0/P1 被淹没 |
在 CI 场景中将 --min-severity P1 作为默认；定期人工审查 P2/P3 趋势 |
| git blame 在 shallow clone 中失效 | 浅克隆仓库缺少完整历史，git blame 返回空或错误，影响责任人归因 |
检测 .git/shallow 存在时跳过 blame enrichment，或提示 git fetch --unshallow |
Usage
在 Claude Code 中调用：
# 全量扫描，输出到默认目录
/zcode-patrol --paths src/ --scope full
# 预期产物：.zcode-patrol/{patrol_id}/report.json, report.md, hotspots.json, patrol-state.json
# 增量扫描，对比基线
/zcode-patrol --paths src/ --scope delta --baseline .zcode-patrol/20260527-120000-xxx/report.json
# 预期产物：上述文件 + baseline-diff.json
# 限制扫描范围与输出格式
/zcode-patrol --paths src/ tests/ --scope targeted --max-files 200 --format json
# 预期产物：.zcode-patrol/{patrol_id}/report.json（无 report.md）
# 仅关注高严重级别问题
/zcode-patrol --paths src/ --min-severity P1 --output-dir ./reports/patrol
# 预期产物：./reports/patrol/{patrol_id}/report.json, hotspots.json, patrol-state.json