Harness Engineering 架构：实现无人值守的周期性治理巡检

当 AI 帮你写了越来越多的代码，谁来确保这些代码没有悄悄腐化？本文分享我们团队如何基于 Harness Engineering 四层文档体系 + QoderWork 定时任务，实现从"人工巡检"到"无人值守自动治理"的完整实践。

一、背景：AI Coding 时代的"代码熵增"问题

1.1 问题描述

自从引入 AI Agent 辅助编码后，我们团队的代码产出效率提升了 3-5 倍。但随之而来的是一个隐性问题------代码熵增：

现象	具体表现
文档过期	设计文档 `last_updated` 停留在 3 个月前，代码早已面目全非
代码-文档漂移	源码改了 5 个版本，对应的设计文档还是初版
规范退化	新代码悄悄引入了 `@Autowired` 字段注入、`System.out.println`
技术栈偏移	pom.xml 升级了依赖版本，但 AGENTS.md 基线文档未同步

这些问题不会导致编译失败，但会像慢性毒药一样侵蚀项目质量。传统做法是安排人定期 Review，但人会忘、会懒、会忙。

1.2 我们的目标

让项目自己"体检"，自己"开药方"，人只需要"吃药"。

具体拆解为：

定时采集：每周自动运行构建/测试/Linter，产出客观数据
自动检测：基于数据检测文档过期、代码漂移、规则失效
智能修复：简单问题自动修，复杂问题生成建议清单
主动通知：评分低于阈值时推送告警到 IM 群

二、Harness Engineering 架构概览

2.1 四层文档体系

我们的项目采用 Harness Engineering（驾驭式工程化） 方法论，核心思想是：AI 生成，人类驾驭。通过分层文档体系为 AI 提供充分上下文和硬性约束：

复制代码

┌─────────────────────────────────────────────────────────┐
│                    AGENTS.md                             │
│           项目入口 · 技术栈基线 · 快速导航                 │
├──────────────┬───────────────┬──────────────────────────┤
│  Rules 层     │  Skills 层     │  Wiki 层 (docs/)         │
│  硬性约束     │  操作手册       │  知识库                  │
│  .qoder/      │  .qoder/       │  docs/                   │
│  rules/       │  skills/       │                          │
├──────────────┴───────────────┴──────────────────────────┤
│            Changes 层 (docs/changes/)                     │
│       变更管理 · 影响分析 · PR 自检                       │
├──────────────────────────────────────────────────────────┤
│            自动化层 (build/)                               │
│    Linter 规则 · 治理脚本 · 客观数据采集                   │
└──────────────────────────────────────────────────────────┘

2.2 自动化层定位

自动化层是整个体系的第五层（底层基础设施），负责：

客观侧性采集：让 AI Agent 能"看到"构建日志/测试结果/Linter 报告
自动衰减检测：文档/规则/约束的可信度随时间下降检测
持续治理报告：质量趋势 + 技术债追踪 + 漂移告警

核心理念是 Sidecar 数据模式（伴车数据）：构建/测试/Linter 的结果作为结构化 JSON 独立存在，Agent 不需要亲自跑 Maven，只需读取伴车数据就能做客观决策。

三、自动化层脚本体系

3.1 脚本全景

复制代码

build/automation/
├── scripts/
│   ├── collect-sidecar.ps1      # 客观侧性数据采集（编译/测试/PMD/Checkstyle）
│   ├── decay-detector.ps1       # 四维度衰减检测
│   ├── governance-report.ps1    # 治理报告生成（Markdown）
│   ├── index-sync-check.ps1     # 文档全景索引一致性检测
│   ├── pre-check.ps1            # 环境前置检查
│   └── worktree-manager.ps1     # Git Worktree 生命周期管理
└── sidecar/                     # 采集的结构化数据（.gitignore 排除）
    ├── build-status.json
    ├── test-results.json
    ├── linter-violations.json
    ├── checkstyle-violations.json
    ├── sidecar-summary.json
    ├── decay-report.json
    └── index-sync-report.json

3.2 核心脚本说明

collect-sidecar.ps1 --- 客观数据采集

4 步采集流程：

复制代码

[1/4] 编译检查 → build-status.json
[2/4] 测试采集 → test-results.json（可用 -SkipTests 跳过）
[3/4] PMD 采集 → linter-violations.json
[4/4] Checkstyle 采集 → checkstyle-violations.json
     → 汇总生成 sidecar-summary.json

decay-detector.ps1 --- 四维度衰减检测

维度	检测内容	阈值
文档新鲜度	`last_updated` 超过 90 天的 .md 文件	>90天=过期
代码-文档对齐	源码变更但设计文档未同步	drift>30天=漂移
规则覆盖率	Linter 规则从未被触发	<50%=覆盖不足
技术栈对齐	AGENTS.md 与 pom.xml 版本是否一致	0 mismatch=健康

生成decay-report.json-衰减检测报告

四维度加权计算整体评分（0-100），低于 60 分触发告警。

governance-report.ps1 --- 治理报告生成

汇总所有 sidecar JSON 数据，生成结构化 Markdown 报告，包含：执行摘要、衰减详情、Linter 违规明细、测试失败详情、行动项清单。

四、创建 qoderwork-scheduler.md 定时调度Skill

4.1 为什么需要这个 Skill

auto-governance.md Skill 已经定义了完整的 5 步治理流程，但它只能在 Qoder IDE 中手动触发 （执行 /auto-governance）。我们需要：

定时触发：每周一早上自动跑一遍，不需要人记得去执行
无人值守：电脑开着就行，不需要人盯着
主动通知：出了问题推送到微信/飞书/钉钉等 IM 群，而不是等人去看报告

Qoder IDE 本身不支持定时触发，但 QoderWork （独立桌面客户端）支持。于是我们创建了定时调度Skill qoderwork-scheduler.md ，作为Qoder IDE 与 QoderWork 之间的桥梁。

4.2 Skill 文件结构

在 .qoder/skills/ 目录下创建 qoderwork-scheduler.md：

markdown 复制代码

---
last_updated: 2026-07-20
status: active
owner: @zhangsan
---

# Skill: qoderwork-scheduler

## 描述

将 Harness 自动化层脚本接入 QoderWork 定时任务，
实现无人值守的周期性治理巡检。

## 触发条件

- 用户执行 /qoderwork-scheduler
- 用户提到"定时治理"、"自动巡检"等关键词
- auto-governance 执行完毕后建议配置定时任务

## 执行流程（3 步）

### Step 1：确认用户需求（频率/时间/范围/通知）

### Step 2：生成 QoderWork 定时任务配置（4 个模板）

### Step 3：指导用户在 QoderWork 中创建任务

实例

markdown 复制代码

---
last_updated: 2026-07-20
status: active
owner: @zhangsan
---

# Skill: qoderwork-scheduler

## 描述

将 Harness 自动化层脚本（collect-sidecar / decay-detector / governance-report）接入 QoderWork 定时任务，
实现无人值守的周期性治理巡检。本 Skill 指导 Agent 帮助用户在 QoderWork 中配置定时任务，
并在 Qoder IDE 内读取 QoderWork 产出的 sidecar 数据进行智能修复。

## 触发条件

- 用户执行 `/qoderwork-scheduler`
- 用户在对话中提到"定时治理"、"自动巡检"、"QoderWork 定时任务"等关键词
- `auto-governance` 执行完毕后，建议用户配置定时任务以保持持续治理

## 前置条件

| 条件            | 说明                                                                                           |
|---------------|----------------------------------------------------------------------------------------------|
| QoderWork 已安装 | 从 https://qoder.com.cn/qoderwork 下载 Windows 版本                                               |
| Qoder 账号已登录   | QoderWork 与 Qoder IDE 使用同一账号                                                                 |
| 自动化脚本已就位      | `build/automation/scripts/` 下存在 collect-sidecar.ps1、decay-detector.ps1、governance-report.ps1 |

## 执行流程（3 步）

### Step 1：确认用户需求

向用户确认以下信息：

1. **巡检频率**：每天 / 每周 / 每月（推荐每周一次）
2. **巡检时间**：具体时间点（推荐工作日早上 09:00）
3. **巡检范围**：全量（含测试）/ 快速（跳过测试）
4. **IM 通知**：是否需要将治理报告推送到钉钉/飞书/微信群

### Step 2：生成 QoderWork 定时任务配置

根据用户需求，生成对应的 QoderWork 自然语言任务描述。用户直接复制到 QoderWork 的「定时任务」创建框中即可。

#### 模板 A：每周全量治理巡检（推荐）

\```
每周一上午 9:00，在工作目录 C:\workspace\app-exchange-port 下执行以下操作：

1. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/collect-sidecar.ps1 -SkipTests
2. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/decay-detector.ps1
3. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/governance-report.ps1
4. 读取 build/automation/sidecar/sidecar-summary.json 和 decay-report.json
5. 根据衰减报告中的过期文档列表，自动更新文档的 last_updated 日期（仅当文档内容未变更时）
6. 根据 checkstyle-violations.json 中的 UnusedImports 违规，删除未使用的 import 语句
7. 将治理报告和行动项清单保存到 docs/changes/ 目录
\```

#### 模板 B：每日轻量级健康检查

\```
每天下午 6:00，在工作目录 C:\workspace\app-exchange-port 下执行以下操作：

1. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/decay-detector.ps1
2. 读取 build/automation/sidecar/decay-report.json
3. 如果整体评分（overallScore）低于 60 分，生成告警摘要并通知
4. 如果评分正常，仅记录日志，不做其他操作
\```

#### 模板 C：每月深度治理（含全量测试）

\```
每月 1 号上午 10:00，在工作目录 C:\workspace\app-exchange-port 下执行以下操作：

1. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/collect-sidecar.ps1
   注意：这次不跳过测试，全量采集（耗时约 3-5 分钟）
2. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/decay-detector.ps1
3. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/governance-report.ps1
4. 读取所有 sidecar JSON 数据，生成完整的月度治理报告
5. 对比上月报告（docs/changes/ 目录下上一个 governance-report），分析评分趋势
6. 自动修复简单问题：过期文档日期更新、未使用 import 清理、简单 PMD 违规修复
7. 将月度治理报告保存到 docs/changes/ 目录
\```

#### 模板 D：IM 频道告警推送（可选附加）

\```
当治理巡检完成后，如果整体评分低于 60 分，通过 {IM平台} 发送以下消息：

🚨 项目治理告警
整体评分: {score}/100
编译状态: {build_status}
测试通过率: {test_pass_rate}
过期文档: {stale_count} 个
代码-文档漂移: {drift_count} 处
请及时处理，执行 /auto-governance 查看详情
\```

> 将 `{IM平台}` 替换为用户配置的 IM 频道名称（钉钉/飞书/微信/企业微信/Lark）。

### Step 3：指导用户在 QoderWork 中创建任务

向用户输出以下操作步骤：

\```
## QoderWork 定时任务创建步骤

1. 打开 QoderWork 桌面客户端
2. 点击左侧菜单「定时任务」
3. 点击「新建任务」或直接在对话框中用自然语言描述任务
4. 将上面的任务模板内容粘贴到对话框
5. 确认工作目录为：C:\workspace\app-exchange-port
6. 确认触发频率和时间
7. 点击「创建」完成

### 验证任务
- 创建后，点击任务卡片右上角的「立即执行」按钮进行测试
- 检查 build/automation/sidecar/ 目录下是否生成了 JSON 文件
- 检查 docs/changes/ 目录下是否生成了治理报告

### （可选）配置 IM 频道
1. 在 QoderWork 左侧菜单点击「IM 频道」
2. 选择平台（钉钉/飞书/微信），点击「配置」
3. 扫码授权完成绑定
4. 绑定后，定时任务的告警消息可自动推送到 IM 群
\```

## QoderWork + Qoder IDE 协作模型

QoderWork 负责**定时采集**，Qoder IDE 负责**智能修复**，两者通过 sidecar JSON 文件协作：

\```
┌─────────────────────────────────────────────────────────────────┐
│                    QoderWork（定时任务）                          │
│                                                                 │
│  定时触发 → collect-sidecar.ps1 → decay-detector.ps1            │
│           → governance-report.ps1                               │
│                                                                 │
│  产出：                                                          │
│  - build/automation/sidecar/*.json  （客观侧性数据）              │
│  - docs/changes/governance-report-*.md （治理报告）               │
└──────────────────────────┬──────────────────────────────────────┘
                           │ 共享 sidecar JSON 文件
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Qoder IDE（智能修复）                          │
│                                                                 │
│  /auto-governance 或 /run-governance                            │
│                                                                 │
│  读取 sidecar JSON → 客观决策 → 自动修复简单问题                  │
│  - 过期文档日期更新                                               │
│  - 未使用 import 清理                                            │
│  - 简单 PMD 违规修复（LoggerFactory/System.out/printStackTrace） │
│  - 技术栈基线对齐                                                │
│                                                                 │
│  输出：修复后的代码 + 修复建议清单                                 │
└─────────────────────────────────────────────────────────────────┘
\```

### 分工说明

| 能力               | QoderWork  | Qoder IDE  |
|------------------|------------|------------|
| 定时触发脚本           | ✅ 支持 6 种频率 | ❌ 不支持定时    |
| 运行 PowerShell 脚本 | ✅          | ✅ 手动触发     |
| 读取 sidecar JSON  | ✅ 可读取      | ✅ 完整解析     |
| 代码级智能修复          | ❌ 能力有限     | ✅ 直接编辑代码文件 |
| 治理报告生成           | ✅ 脚本生成     | ✅ 脚本生成     |
| IM 告警推送          | ✅ 钉钉/飞书/微信 | ❌          |
| 修复-重检循环          | ❌          | ✅ 最多 3 轮   |

## 注意事项

- QoderWork 定时任务需要**设备保持唤醒状态**，电脑休眠时任务不会执行
- QoderWork 工作目录必须设置为项目根目录，否则脚本无法找到 Git 仓库
- sidecar JSON 文件已被 `.gitignore` 排除，不会提交到 Git 仓库
- 治理报告（governance-report-*.md）会提交到 Git，作为项目健康状态历史记录
- 如果 QoderWork 和 Qoder IDE 同时运行，注意避免同时修改同一文件
- 推荐节奏：QoderWork 每周一定时采集 → 开发者工作日手动在 Qoder IDE 执行 `/auto-governance` 修复

## 与其他 Skill 的关系

| Skill           | 关系                                                                        |
|-----------------|---------------------------------------------------------------------------|
| auto-governance | qoderwork-scheduler 负责定时采集，auto-governance 负责智能修复；两者通过 sidecar JSON 协作    |
| doc-gardening   | QoderWork 定时检测到过期文档后，可在 Qoder IDE 中执行 `/doc-gardening` 做详细文档健康检查          |
| prd-to-code     | prd-to-code Step 7 的 auto-governance 可复用 QoderWork 已采集的 sidecar 数据，无需重复采集 |

## 输出示例

Agent 执行本 Skill 后的输出：

\```
[QODERWORK-SCHEDULER] 正在配置 QoderWork 定时治理任务...

📋 推荐方案：每周全量治理巡检

请在 QoderWork 中创建以下定时任务：
────────────────────────────────────────
任务名称：每周治理巡检
触发频率：每周一 09:00
工作目录：C:\workspace\app-exchange-port

任务描述：
每周一上午 9:00，在工作目录 C:\workspace\app-exchange-port 下执行以下操作：
1. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/collect-sidecar.ps1 -SkipTests
2. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/decay-detector.ps1
3. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/governance-report.ps1
4. 读取 sidecar JSON 数据，自动修复简单问题（过期文档日期、未使用 import）
5. 将治理报告保存到 docs/changes/ 目录
────────────────────────────────────────

📌 创建步骤：
1. 打开 QoderWork → 左侧「定时任务」→「新建任务」
2. 粘贴上面的任务描述
3. 确认工作目录和触发频率
4. 点击「创建」→ 「立即执行」测试

💡 提示：配置 IM 频道后，评分低于 60 分时自动推送告警到钉钉/飞书群
\```

说明：示例中的""是转义符，使用时直接删除""转义符即可

4.3 四个任务模板

模板	频率	适用场景
A：每周全量治理巡检	每周一 09:00	推荐，平衡频率和深度
B：每日轻量级健康检查	每天 18:00	仅跑衰减检测，快速发现评分骤降
C：每月深度治理	每月 1 号 10:00	含全量测试，生成月度趋势对比
D：IM 频道告警推送	附加	评分<60 时推送到钉钉/飞书/微信

4.4 协作模型

复制代码

┌─────────────────────────────────────────────────────────────────┐
│                    QoderWork（定时任务）                          │
│                                                                 │
│  定时触发 → collect-sidecar.ps1 → decay-detector.ps1            │
│           → governance-report.ps1                               │
│                                                                 │
│  产出：                                                          │
│  - build/automation/sidecar/*.json  （客观侧性数据）              │
│  - docs/changes/governance-report-*.md （治理报告）               │
└──────────────────────────┬──────────────────────────────────────┘
                           │ 共享 sidecar JSON 文件
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Qoder IDE（智能修复）                          │
│                                                                 │
│  /auto-governance                                               │
│                                                                 │
│  读取 sidecar JSON → 客观决策 → 自动修复简单问题                  │
│  - 过期文档日期更新                                               │
│  - 未使用 import 清理                                            │
│  - 简单 PMD 违规修复                                             │
│  - 技术栈基线对齐                                                │
│                                                                 │
│  输出：修复后的代码 + 修复建议清单                                 │
└─────────────────────────────────────────────────────────────────┘

分工原则 ：QoderWork 负责"体检 "（定时采集），Qoder IDE 负责"治疗"（智能修复）。

4.5 注册到 AGENTS.md

在 AGENTS.md 快速导航表的 Skills 层区块添加一行：

markdown 复制代码

| 配置 QoderWork 定时治理巡检 | .qoder/skills/qoderwork-scheduler.md |

这样 AI Agent 在用户提到"定时治理"时就能自动定位到这个 Skill。

五、实操：在 QoderWork 上配置定时任务

5.1 前置准备

条件	状态
QoderWork 已安装（Windows 版）	✅
Qoder 账号已登录（与 IDE 同账号）	✅
自动化脚本已就位	✅ `build/automation/scripts/` 下 6 个 .ps1
项目为 Git 仓库	✅

5.2 创建定时任务（模板 A：每周全量治理巡检）

操作步骤：

打开 QoderWork 桌面客户端
点击左侧菜单「定时任务」
点击「新建任务」
在对话框中粘贴以下自然语言任务描述：

每周一上午 9:00，在工作目录 C:\workspace\app-exchange-port 下执行以下操作：
1. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/collect-sidecar.ps1 -SkipTests
2. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/decay-detector.ps1
3. 运行 PowerShell 脚本：powershell -ExecutionPolicy Bypass -File build/automation/scripts/governance-report.ps1
4. 读取 build/automation/sidecar/sidecar-summary.json 和 decay-report.json
5. 根据衰减报告中的过期文档列表，自动更新文档的 last_updated 日期（仅当文档内容未变更时）
6. 根据 checkstyle-violations.json 中的 UnusedImports 违规，删除未使用的 import 语句
7. 将治理报告和行动项清单保存到 docs/changes/ 目录
确认工作目录为：C:\workspace\app-exchange-port
确认触发频率：每周一 09:00
点击「创建」完成

5.3 配置 IM 频道通知（微信）

在 QoderWork 左侧菜单点击「IM 频道」
选择「微信」平台，点击「配置」
使用微信扫码授权完成绑定
绑定后，在定时任务中追加告警推送规则：

当治理巡检完成后，如果整体评分低于 60 分，通过微信发送以下消息：

🚨 项目治理告警
整体评分: {score}/100
编译状态: {build_status}
测试通过率: {test_pass_rate}
过期文档: {stale_count} 个
代码-文档漂移: {drift_count} 处
请及时处理，执行 /auto-governance 查看详情

5.4 验证任务

创建完成后，点击任务卡片右上角的「立即执行」按钮进行测试运行：

复制代码

[SIDECAR] 开始采集客观数据...
[SIDECAR] [1/4] 编译检查... PASS
[SIDECAR] [2/4] 测试采集... SKIPPED
[SIDECAR] [3/4] PMD 采集... 3 violations
[SIDECAR] [4/4] Checkstyle 采集... 1 violation

[SIDECAR] 采集完成，数据已写入:
  build\automation\sidecar\build-status.json
  build\automation\sidecar\test-results.json
  build\automation\sidecar\linter-violations.json
  build\automation\sidecar\checkstyle-violations.json
  build\automation\sidecar\sidecar-summary.json

[DECAY] [1/4] 文档过期检测...
  过期文档: 2 个
[DECAY] [2/4] 代码-文档漂移检测...
  代码-文档漂移: 1 处
[DECAY] [3/4] Linter 规则命中率检测...
  命中规则: 12/35 (覆盖率=34.3%)
[DECAY] [4/4] 技术栈基线对齐检测...
  技术栈基线一致

[DECAY] 衰减检测完成
  整体评分: 72 / 100
  文档新鲜度:   80 (2 个过期)
  代码-文档对齐: 85 (1 处漂移)
  规则覆盖率:   34 (12/35 命中)
  技术栈对齐:   100 (0 个不一致)
[DECAY] 报告已写入: build\automation\sidecar\decay-report.json

[INDEX-SYNC] [1/3] 收集磁盘实际文件...
  磁盘文件数: 44 个
[INDEX-SYNC] [2/3] 解析 ai-coding-guide.md §5 文档全景索引...
  索引文件数: 44 个
[INDEX-SYNC] [3/3] 比对差异...
  ✅ 索引与磁盘文件完全一致
[INDEX-SYNC] 检测完成
  报告路径: build\automation\sidecar\index-sync-report.json

[REPORT] 治理报告已生成: docs\changes\governance-report-2026-07-14.md
[REPORT] 整体评分: 72 / 100

验证检查点：

✅ build/automation/sidecar/ 目录下生成了 7 个 JSON 文件（5 个来自 collect-sidecar + 1 个来自 decay-detector + 1 个来自 index-sync-check）
✅ docs/changes/ 目录下生成了 governance-report-2026-07-14.md
✅ 微信收到了治理报告通知

六、巡检报告解读

6.1 报告结构

生成的 docs/changes/governance-report-2026-07-14.md 包含以下章节：

markdown 复制代码

# 治理报告 2026-07-14

## 执行摘要

| 指标 | 值 | 状态 |
|------|-----|------|
| 整体评分 | 72 / 100 | 关注 (上周: 68, ↑ +4) |
| 编译状态 | PASS | 正常 |
| 测试通过率 | N/A (跳过) | --- |
| PMD 违规 | 3 | 需修复 |
| Checkstyle 违规 | 1 | 需修复 |
| 过期文档 | 2 | 需更新 |
| 代码-文档漂移 | 1 | 需同步 |

## 衰减检测

| 维度 | 评分 | 详情 |
|------|------|------|
| 文档新鲜度 | 80 | 2 个过期 |
| 代码-文档对齐 | 85 | 1 处漂移 |
| 规则覆盖率 | 34 | 12/35 命中 |
| 技术栈对齐 | 100 | 一致 |

## 行动项

1. **[高]** 修复 PMD 违规（3 个）--- 参见 docs/conventions/linter-rules.md
2. **[高]** 修复 Checkstyle 违规（1 个）--- 参见 docs/conventions/linter-rules.md
3. **[中]** 更新过期文档（2 个）--- 执行 /doc-gardening
4. **[中]** 同步代码-文档漂移（1 处）--- 源码已变更但文档未更新

6.2 评分趋势追踪

治理报告会对比上周评分，形成趋势：

复制代码

第 1 周: 68 分（首次巡检，发现较多问题）
第 2 周: 72 分（↑ +4，修复了部分 PMD 违规）
第 3 周: 78 分（↑ +6，更新了过期文档）
第 4 周: 82 分（↑ +4，进入"健康"区间）

6.3 实际巡检结果

报告实例

在docs/changes目录下生成文件governance-report-2026-07-20.md，实际内容如下：

markdown 复制代码

---
last_updated: 2026-07-20
status: active
owner: @auto-governance
---

# 治理报告 2026-07-20

> 本报告由每周治理巡检自动生成，基于客观数据（构建/测试/Linter/衰减检测）。

## 执行摘要

| 指标 | 值 | 状态 |
|------|-----|------|
| 整体评分 | 31 / 100 | 风险 |
| 编译状态 | FAIL (15 errors) | 异常 |
| 测试通过率 | N/A（本次跳过测试执行） | - |
| PMD 违规 | 0 | 正常 |
| Checkstyle 违规 | 0 | 正常 |
| 过期文档 | 12 | 已处理（10个刷新日期，2个有实质变更跳过） |
| 代码-文档漂移 | 5 | 需同步 |

## 衰减检测

| 维度 | 评分 | 详情 |
|------|------|------|
| 文档新鲜度 | 0 | 12 个过期（>90天） |
| 代码-文档对齐 | 25 | 5 处漂移 |
| 规则覆盖率 | 0 | 0/35 命中 |
| 技术栈对齐 | 100 | 一致 |

### 过期文档（>90 天）

| 文档 | 最后更新 | 过期天数 | 处理 |
|------|---------|---------|------|
| docs/architecture/boundaries.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/architecture/data-flow.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/architecture/overview.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/changes/impact-analysis.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/conventions/testing.md | 2026-03-28 | 115d | 跳过（有实质变更） |
| docs/design/feature-async-batch-sharding.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/design/feature-rate-limiting.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/design/feature-scheduler-framework.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/design/feature-sync-single-request.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/design/feature-trace-propagation.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/design/feature-vendor-adapter.md | 2026-03-28 | 115d | 已刷新日期 |
| docs/reference/error-codes.md | 2026-03-28 | 115d | 跳过（有实质变更） |

### 代码-文档漂移

| 源码文件 | 代码最后提交 | 关联文档 | 文档最后更新 | 漂移天数 |
|---------|------------|---------|------------|---------|
| exchange-soa-service/.../QueryRateLimitDelegate.java | 2026-06-25 | docs/design/feature-rate-limiting.md | 2026-03-28 | 90d |

> 注：衰减检测报告显示 5 处漂移，上表为详细记录的首条。

### 零命中 Linter 规则（需观察是否过时）

- ExchangeNoLoggerFactory
- ExchangeNoSystemOut
- ExchangeNoPrintStackTrace
- ExchangeNoLogStringConcat
- ExchangeNoFieldAutowired
- ExchangeNoConstructorAutowired
- ExchangeNoNewOkHttpClient
- ExchangeNoTransactional
- ExchangeNoThreadPoolExecutor
- ExchangeNoForkJoinPool
- EmptyCatchBlock
- ExchangeNoAllArgsConstructor
- ExchangeNoRunWith
- ExchangeNoThreadSleep
- ExchangeNoMapperFieldInjection
- ExchangeNoSystemExit
- IllegalImport
- FileLength
- UnusedImports
- CustomImportOrder

## 编译错误详情

编译失败原因：exchange-ext-youmeng 模块引入了被禁止的依赖 `com.fasterxml.jackson.core:jackson-databind:2.13.4.2`，违反 maven-enforcer-plugin 规则 EXCHANGE-DEP-001/002（禁止引入 Jackson 或 Gson）。

修复方案：
1. 删除 exchange-ext-youmeng/pom.xml 中的 jackson-databind 依赖
2. 将代码中的 ObjectMapper 替换为 com.alibaba.fastjson.JSON
3. 参考 .qoder/rules/always-on.md 第1节技术栈锁定

## 本次巡检已执行的操作

1. 采集构建客观数据（collect-sidecar.ps1 -SkipTests）
2. 运行衰减检测（decay-detector.ps1）
3. 刷新 10 个过期文档的 last_updated 日期为 2026-07-20
4. 检查 Checkstyle UnusedImports 违规（本次为 0，无需修复）
5. 生成本治理报告及行动项清单

---
*生成时间: 2026-07-20 | 数据来源: build/automation/sidecar/*

行动项清单

基于2026-07-20治理巡检结果，按照优先级排序生成治理行动项清单，清单如下：

markdown 复制代码

---
last_updated: 2026-07-20
status: active
owner: @auto-governance
---

# 行动项清单 2026-07-20

> 基于 2026-07-20 治理巡检结果，按优先级排列。

## 紧急

1. **[紧急]** 修复编译错误（15 个）--- exchange-ext-youmeng 模块引入被禁止的 jackson-databind 依赖，需删除并替换为 FastJSON

## 高优先级

2. **[高]** 同步代码-文档漂移（5 处）--- 源码已变更但关联设计文档未更新，重点：QueryRateLimitDelegate.java → docs/design/feature-rate-limiting.md

## 中优先级

3. **[中]** 提升 Linter 规则覆盖率（当前 0/35）--- 确认自定义 PMD/Checkstyle 规则是否正确配置到构建流程中
4. **[中]** 更新 docs/conventions/testing.md 的 last_updated 日期 --- 内容有变更但日期未同步（commit 60213fb5）
5. **[中]** 更新 docs/reference/error-codes.md 的 last_updated 日期 --- 内容有变更但日期未同步（commit bbb29da9）

## 低优先级

6. **[低]** 评估 20 条零命中 Linter 规则 --- 确认规则是否过时或构建配置是否正确

## 已完成（本次巡检）

- [x] 刷新 10 个过期文档的 last_updated 日期
- [x] 检查 Checkstyle UnusedImports（无违规）
- [x] 采集构建/测试/Linter 客观数据
- [x] 运行衰减检测

---
*生成时间: 2026-07-20 | 关联报告: governance-report-2026-07-20.md*

七、Qoder IDE 智能修复（闭环）

7.1 推荐工作节奏

复制代码

周一 09:00  QoderWork 定时采集 → 生成报告 → 微信通知
     ↓
周一~周五   开发者在 Qoder IDE 中执行 /auto-governance
     ↓
            Agent 读取 sidecar JSON → 自动修复简单问题 → 生成建议清单
     ↓
            开发者处理复杂问题（需人工判断的 PMD 违规、文档内容更新）

7.2 自动修复能力

在 Qoder IDE 中执行 /auto-governance，Agent 会自动修复：

问题类型	修复方式	是否自动
过期文档日期（内容未变）	更新 `last_updated` 为当天	✅ 自动
未使用 import	删除 import 语句	✅ 自动
LoggerFactory 声明	改为 `@Slf4j` + 删除 Logger 字段	✅ 自动
System.out.println	替换为 `log.info()`	✅ 自动
printStackTrace	替换为 `log.error("xxx", e)`	✅ 自动
字符串拼接日志	替换为占位符 `log.info("x={}", val)`	✅ 自动
字段 @Autowired	改为 @Resource 或构造器注入	⚠️ 需人工
代码-文档漂移	审查文档内容是否需要更新	⚠️ 需人工

7.3 修复-重检循环

自动治理采用最多 3 轮的修复-重检循环：

轮次	动作
第 1 轮	全量采集 + 衰减检测 + 自动修复简单问题
第 2 轮	重采 sidecar + 重检衰减 + 修复剩余简单问题
第 3 轮	重采 sidecar + 重检衰减（不再修复，仅验证）
超过 3 轮	暂停，输出未解决问题清单，转人工处理

八、关键设计决策

8.1 为什么用 Sidecar 数据模式？

方案	优点	缺点
Agent 亲自跑 Maven	实时	耗时 3-5 分钟，每次对话都要等
Sidecar JSON（采用）	读取毫秒级，可复用	需要定时刷新
CI/CD 流水线	最规范	搭建成本高，小团队不划算

Sidecar 模式是唯一同时满足"首次可用 + 重复快速 + 不膨胀仓库"的方案。

8.2 为什么 QoderWork 和 Qoder IDE 分工？

能力	QoderWork	Qoder IDE
定时触发	✅ 支持 6 种频率	❌ 不支持
运行脚本	✅	✅ 手动
代码级修复	❌ 能力有限	✅ 直接编辑文件
IM 告警	✅ 微信/钉钉/飞书	❌
修复-重检循环	❌	✅ 最多 3 轮

结论：QoderWork 做"体检中心"，Qoder IDE 做"主治医生"。

8.3 为什么衰减阈值设为 90 天？

太短（30 天）：误报率高，正常迭代周期内的文档也会被标记
太长（180 天）：发现太晚，文档可能已经严重失真
90 天：约一个季度，平衡了"给足更新时间"和"及时发现腐化"

九、注意事项与踩坑记录

9.1 环境要求

QoderWork 定时任务需要设备保持唤醒状态，电脑休眠时任务不会执行
工作目录必须设置为项目根目录（Git 仓库根），否则脚本无法定位
PowerShell 执行策略需要 Bypass（脚本命令中已包含 -ExecutionPolicy Bypass）

9.2 文件冲突

sidecar JSON 文件已被 .gitignore 排除，不会提交到 Git
治理报告（governance-report-*.md）会提交到 Git，作为健康状态历史记录
如果 QoderWork 和 Qoder IDE 同时运行，注意避免同时修改同一文件

9.3 推荐节奏

复制代码

QoderWork 每周一定时采集（无人值守）
    → 开发者工作日在 Qoder IDE 执行 /auto-governance 修复（有人参与）
    → 每月 1 号 QoderWork 跑一次全量含测试的深度治理（月度复盘）

十、总结

10.1 实施效果

指标	实施前	实施后
巡检频率	不固定（想起来才看）	每周一次（雷打不动）
发现方式	人工 Review 偶然发现	自动检测 + 微信推送
简单问题修复	手动改	Agent 自动修复
治理报告	无	每周自动生成，可追溯趋势
团队感知	无感知	微信收到评分，有紧迫感

10.2 整体架构回顾

复制代码

┌────────────────────────────────────────────────────────────┐
│                  Harness Engineering                        │
│                                                            │
│  Rules 层 ──→ 定义"什么是正确的"（13 条硬约束）              │
│  Skills 层 ──→ 定义"怎么做"（auto-governance 5 步流程）     │
│  Wiki 层 ──→ 提供"详细参考"（linter-rules / conventions）   │
│  自动化层 ──→ 提供"客观数据"（sidecar JSON）                │
│                                                            │
│  QoderWork ──→ 定时触发（每周一 09:00）                     │
│  Qoder IDE ──→ 智能修复（/auto-governance）                 │
│  IM 频道 ──→ 主动通知（微信告警）                           │
└────────────────────────────────────────────────────────────┘

10.3 可复制性

本方案的脚本与项目耦合度低，迁移到其他 Java 项目只需：

复制 build/automation/scripts/ 下 6 个 .ps1 脚本
修改 decay-detector.ps1 中的文档映射规则（源码→设计文档对应关系）
修改技术栈版本检查项（匹配你的 pom.xml）
在 QoderWork 中创建定时任务，指向新项目目录

附录：完整文件清单

文件	作用
`.qoder/skills/qoderwork-scheduler.md`	QoderWork 定时任务配置 Skill
`.qoder/skills/auto-governance.md`	自动治理巡检 Skill（5 步流程）
`build/automation/scripts/collect-sidecar.ps1`	客观侧性数据采集
`build/automation/scripts/decay-detector.ps1`	四维度衰减检测
`build/automation/scripts/governance-report.ps1`	治理报告生成
`build/automation/scripts/index-sync-check.ps1`	文档索引一致性检测
`docs/design/feature-automation-layer.md`	自动化层设计文档
`docs/changes/governance-report-*.md`	历史治理报告（自动生成）