konglong87 harness-check-clean-state
Core Capabilities
执行清洁状态检查清单，验证系统是否达到"清洁状态"（会话结束时，代码应达到可合并到主分支的状态）。
核心职责：
- 检查代码质量（编译、测试、Linter）
- 检查 Git 状态（未提交更改、提交信息格式）
- 检查功能完成度（feature_list.json 标记）
- 检查文档更新（EVENT_LOG.md、GLOBAL_STATE.md）
- 检查可合并性（无冲突、无 TODO/FIXME）
- 返回检查结果（CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES）
Execution Steps
Step 1: 读取清洁状态检查清单
工具: Read
文件: .EnjoyHarness/CLEAN_STATE_CHECKLIST.md
Token 消耗: ~1000 tokens
Step 2: 检查代码质量
2.1 检查编译
工具: Bash
命令: make build（或项目特定编译命令）
Token 消耗: ~500 tokens
失败处理:
- 返回 CRITICAL_ISSUES
- 记录错误到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
- 退出检查（不继续后续步骤）
2.2 检查测试
工具: Bash
命令: make test（或项目特定测试命令）
Token 消耗: ~1000 tokens
失败处理:
- 返回 MODERATE_ISSUES
- 记录错误到 EVENT_LOG.md（MODERATE_ISSUES | TEST_FAILED）
- 继续检查其他项（收集完整问题列表）
2.3 检查 Linter
工具: Bash
命令: make lint（或项目特定 Linter 命令）
Token 消耗: ~500 tokens
失败处理:
- 记录 MINOR_ISSUES
- 记录警告到 EVENT_LOG.md（MINOR_ISSUES | LINTER_WARNING）
- 继续检查其他项
Step 3: 检查 Git 状态
工具: Bash
命令: git status --porcelain
验证: 输出为空（无未提交更改）
Token 消耗: ~100 tokens
失败处理:
- 如果输出非空 → 记录 MINOR_ISSUES
- 检查未跟踪文件（git status --short | grep "^??"）
Step 4: 检查功能完成度
工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~800 tokens
验证逻辑:
1. 读取当前功能ID（从 GLOBAL_STATE.md）
2. 在 feature_list.json 中查找该功能
3. 验证 passes 字段是否为 true
失败处理:
- 如果 passes: false → 记录 MODERATE_ISSUES
- 记录到 EVENT_LOG.md（MODERATE_ISSUES | FEATURE_NOT_COMPLETED）
Step 5: 检查文档更新
5.1 检查 EVENT_LOG.md
工具: Bash
命令: grep "SESSION_END" .EnjoyHarness/EVENT_LOG.md
Token 消耗: ~200 tokens
失败处理:
- 如果未找到 → 记录 MINOR_ISSUES
5.2 检查 GLOBAL_STATE.md
工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
验证: 任务状态是否为 completed
失败处理:
- 如果不是 → 记录 MINOR_ISSUES
Step 6: 检查可合并性
6.1 检查 Git 合并状态
工具: Bash
命令: git merge-base --is-ancestor HEAD main
Token 消耗: ~100 tokens
失败处理:
- 如果失败 → 记录 MODERATE_ISSUES
6.2 检查 TODO/FIXME
工具: Bash
命令: grep -r "TODO\|FIXME" --include="*.py" --include="*.go" --include="*.js" || true
Token 消耗: ~200 tokens
验证: 输出为空（无未处理的 TODO/FIXME）
失败处理:
- 如果找到 → 记录 MINOR_ISSUES
Step 7: 输出检查结果
结果类型:
CLEAN: 所有检查通过
MINOR_ISSUES: 轻微问题（Linter 警告、Git 未提交、文档未更新）
MODERATE_ISSUES: 中等问题（测试失败、架构违规、功能未完成）
CRITICAL_ISSUES: 严重问题（编译失败、文件损坏）
输出格式:
检查结果: CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
检查项总数: 15
通过项数: X
失败项数: Y
失败项列表:
- [ ] 代码编译
- [ ] 测试通过
- [x] Linter 无警告
...
Token 消耗: ~200 tokens
Step 8: 记录到 EVENT_LOG.md
工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
- 时间戳：2026-03-28T12:30:00
- 事件类型：CLEAN_STATE_CHECK
- 检查结果：CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
- 检查项详情
Token 消耗: ~100 tokens
Prerequisites
必须满足：
- ✅ 已执行
harness-validate-output（架构验证通过） - ✅ 功能开发完成（工作流最后一个节点执行完成）
如果前置条件不满足：
- 提示用户先完成功能开发和验证
- 拒绝继续执行
Success Criteria
成功标准：
- ✅ 成功执行所有检查项（15 项）
- ✅ 正确识别问题级别（CLEAN/MINOR/MODERATE/CRITICAL）
- ✅ 输出详细的检查结果（通过项、失败项列表）
- ✅ 记录检查事件到
EVENT_LOG.md
失败情况：
- ❌ 检查脚本执行失败 → 记录错误，返回 CRITICAL_ISSUES
- ❌ 文件读取失败 → 记录错误，返回 MODERATE_ISSUES
Failure Recovery
错误场景 1: 编译失败（CRITICAL_ISSUES）
处理:
1. 返回 CRITICAL_ISSUES
2. 记录到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
3. 触发 harness-recover-clean-state（自动回滚）
4. 退出检查
错误场景 2: 测试失败（MODERATE_ISSUES）
处理:
1. 记录 MODERATE_ISSUES
2. 继续检查其他项（收集完整问题列表）
3. 检查完成后触发 harness-recover-clean-state
错误场景 3: Linter 警告（MINOR_ISSUES）
处理:
1. 记录 MINOR_ISSUES
2. 继续检查其他项
3. 检查完成后触发 harness-recover-clean-state
错误场景 4: Git 状态不清洁（MINOR_ISSUES）
处理:
1. 记录 MINOR_ISSUES
2. 继续检查其他项
3. 检查完成后触发 harness-recover-clean-state
Relationships
Triggers (触发下游)
如果检查结果 == CLEAN:
- 触发 harness-track-feature-progress（标记功能完成）
如果检查结果 != CLEAN:
- 触发 harness-recover-clean-state（自动修复或回滚）
Triggered By (被谁触发)
触发时机:
- harness-validate-output 验证通过后
- 子代理开发完成后
- 用户显式调用："清洁状态检查"
Dependencies (前置依赖)
必须依赖:
- harness-validate-output（架构验证）
Token 消耗分析
完整检查流程:
- 读取检查清单: ~1000 tokens
- 代码质量检查: ~2000 tokens
- Git 状态检查: ~100 tokens
- 功能完成度检查: ~800 tokens
- 文档更新检查: ~400 tokens
- 可合并性检查: ~300 tokens
- 输出检查结果: ~200 tokens
- 记录 EVENT_LOG: ~100 tokens
总计: ~4900 tokens
优化方案:
- 仅检查必要项（跳过手动检查项）
- Token 消耗降低至 ~3400 tokens
Examples
示例 1: 所有检查通过（CLEAN）
输入:
- make build: 成功
- make test: 成功
- make lint: 成功
- git status: 空输出
- feature_list.json: passes: true
- EVENT_LOG.md: 包含 SESSION_END
处理:
1. 执行所有检查项（15 项）
2. 所有检查通过
3. 返回 CLEAN
输出:
✅ 检查结果: CLEAN
检查项总数: 15
通过项数: 15
失败项数: 0
所有检查项:
- [x] 代码编译通过
- [x] 测试通过
- [x] Linter 无警告
- [x] Git 状态清洁
- [x] 功能标记完成
- [x] 文档已更新
下一步：触发 harness-track-feature-progress（标记功能完成）
示例 2: 测试失败（MODERATE_ISSUES）
输入:
- make build: 成功
- make test: 失败（2 个测试用例失败）
- make lint: 成功
- git status: 空输出
处理:
1. 执行所有检查项
2. 发现测试失败
3. 记录 MODERATE_ISSUES
4. 继续检查其他项（收集完整问题列表）
输出:
⚠️ 检查结果: MODERATE_ISSUES
检查项总数: 15
通过项数: 14
失败项数: 1
失败项列表:
- [ ] 测试通过（2 个测试用例失败）
下一步：触发 harness-recover-clean-state（自动修复）
示例 3: 编译失败（CRITICAL_ISSUES）
输入:
- make build: 失败（语法错误）
处理:
1. 执行编译检查
2. 发现编译失败
3. 返回 CRITICAL_ISSUES
4. 退出检查（不继续后续步骤）
输出:
🔴 检查结果: CRITICAL_ISSUES
检查项总数: 15
通过项数: 0
失败项数: 1
失败项列表:
- [ ] 代码编译（语法错误）
下一步：触发 harness-recover-clean-state（立即回滚）
示例 4: Git 状态不清洁（MINOR_ISSUES）
输入:
- make build: 成功
- make test: 成功
- git status: 有未提交更改（2 个文件）
处理:
1. 执行所有检查项
2. 发现 Git 状态不清洁
3. 记录 MINOR_ISSUES
4. 继续检查其他项
输出:
⚠️ 检查结果: MINOR_ISSUES
检查项总数: 15
通过项数: 14
失败项数: 1
失败项列表:
- [ ] Git 状态清洁（2 个文件未提交）
下一步：触发 harness-recover-clean-state（自动提交）
Implementation Notes
关键设计决策
分级错误处理
- CLEAN: 无问题，可继续
- MINOR_ISSUES: 轻微问题，自动修复
- MODERATE_ISSUES: 中等问题，尝试修复，失败则回滚
- CRITICAL_ISSUES: 严重问题，立即回滚
检查顺序
- 编译优先（CRITICAL_ISSUES 立即退出）
- 测试其次（MODERATE_ISSUES 继续收集问题）
- Linter 和 Git 最后（MINOR_ISSUES 继续检查）
问题收集
- 编译失败立即退出（不继续检查）
- 其他问题继续检查（收集完整问题列表）
- 便于一次性修复所有问题
性能优化
并行检查:
- 代码质量检查（编译、测试、Linter）可并行
- Git 状态检查和文档更新检查可并行
- 预计检查时长：2-5 分钟
跳过手动检查:
- 端到端验证（手动）
- 下一位开发者可直接开始工作（手动）
- Token 消耗降低 ~20%