# Harness Track Feature Progress

> 从 feature_list.json 选择下一个未完成功能，更新 GLOBAL_STATE.md，触发下游技能

- Skill: `konglong87/harness-track-feature-progress` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-track-feature-progress`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-track-feature-progress/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-track-feature-progress

---


# harness-track-feature-progress

## Core Capabilities

从 `feature_list.json` 选择下一个未完成功能，更新全局状态，触发下游技能执行。

**核心职责**：
1. 读取并解析 `feature_list.json`
2. 按 priority > category > id 排序筛选未完成功能
3. 更新 `GLOBAL_STATE.md`（current_feature 字段）
4. 记录选择事件到 `EVENT_LOG.md`
5. 触发下游技能（单会话模式 → harness-goal，并行模式 → harness-schedule-parallel-agents）

## Execution Steps

### Step 1: 读取功能清单

```yaml
工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~500 tokens（10项）或 ~8000 tokens（200项）
失败处理:
  - 如果文件不存在 → 提示"请先运行 Initializer Agent 生成功能清单"
  - 如果 JSON 格式错误 → 提示"feature_list.json 格式错误"
```

### Step 2: 验证 JSON Schema

```yaml
工具: Bash
命令: python3 tools/validate_feature_list.py
Token 消耗: ~100 tokens
失败处理:
  - 如果验证失败 → 拒绝继续执行，记录错误到 EVENT_LOG.md
```

### Step 3: 解析 JSON（AI 内部处理）

```yaml
处理逻辑:
  1. 过滤 passes: false 的功能
  2. 按 priority 排序（HIGH > MEDIUM > LOW）
  3. 按 category 排序（core > api > ui > security > performance > test）
  4. 按 id 排序（FEAT-001 > FEAT-002 > ...）
  5. 选择第一个作为当前功能

Token 消耗: ~500 tokens
```

### Step 4: 更新全局状态

```yaml
工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段: current_feature: null → FEAT-001
Token 消耗: ~50 tokens
```

### Step 5: 记录事件日志

```yaml
工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳：2026-03-28T12:00:00
  - 事件类型：FEATURE_SELECT
  - 功能ID：FEAT-001
  - 功能描述：实现功能清单机制
Token 消耗: ~50 tokens
```

### Step 6: 输出功能信息

```yaml
输出格式:
  功能ID: FEAT-001
  分类: core
  优先级: HIGH
  描述: 实现功能清单机制 - feature_list.json 强约束管理
  验证步骤:
    1. 创建 feature_list.json 文件（符合 JSON Schema）
    2. 实现 JSON Schema 验证（Python jsonschema）
    3. 实现 harness-track-feature-progress 技能
    4. 测试功能选择逻辑（优先级排序）

Token 消耗: ~100 tokens
```

### Step 7: 触发下游技能

```yaml
单会话模式:
  - 触发: harness-goal（创建 SMART 目标）

并行模式:
  - 触发: harness-schedule-parallel-agents（批量生成子代理）

模式识别逻辑:
  if 项目规模 == "LARGE" OR 功能数 > 50 OR 用户显式指定:
    模式 = "并行模式"
  else:
    模式 = "单会话模式"
```

## Prerequisites

**必须满足**：
- ✅ 已执行 `harness-init`（系统初始化完成）
- ✅ `.EnjoyHarness/feature_list.json` 存在
- ✅ JSON Schema 验证通过

**如果前置条件不满足**：
- 提示用户运行 `harness-init` 或生成功能清单
- 拒绝继续执行

## Success Criteria

**成功标准**：
1. ✅ 成功读取并解析 `feature_list.json`
2. ✅ JSON Schema 验证通过
3. ✅ 成功选择下一个未完成功能（按优先级排序）
4. ✅ 成功更新 `GLOBAL_STATE.md`（current_feature 字段）
5. ✅ 成功记录事件到 `EVENT_LOG.md`
6. ✅ 输出功能信息（ID、描述、优先级、步骤）
7. ✅ 触发下游技能（单会话模式 → harness-goal，并行模式 → harness-schedule-parallel-agents）

**失败情况**：
- ❌ 功能清单文件不存在 → 提示生成功能清单
- ❌ JSON Schema 验证失败 → 拒绝执行，记录错误
- ❌ 无未完成功能 → 提示"所有功能已完成"，生成最终报告

## Failure Recovery

### 错误场景 1: 功能清单文件不存在

```yaml
检测: Read 失败
处理:
  1. 输出提示："请先运行 Initializer Agent 生成功能清单"
  2. 记录到 EVENT_LOG.md（ERROR | FEATURE_LIST_NOT_FOUND）
  3. 退出执行（不继续后续步骤）
```

### 错误场景 2: JSON Schema 验证失败

```yaml
检测: validate_feature_list.py 返回非零退出码
处理:
  1. 输出提示："feature_list.json 格式错误，请检查 JSON Schema"
  2. 记录到 EVENT_LOG.md（ERROR | JSON_SCHEMA_VALIDATION_FAILED）
  3. 退出执行（不继续后续步骤）
```

### 错误场景 3: 无未完成功能

```yaml
检测: passes: false 的功能为空
处理:
  1. 输出提示："所有功能已完成"
  2. 触发最终报告生成
  3. 记录到 EVENT_LOG.md（INFO | ALL_FEATURES_COMPLETED）
  4. 退出执行
```

### 错误场景 4: GLOBAL_STATE.md 更新失败

```yaml
检测: Edit 失败
处理:
  1. 重试一次（最多 2 次）
  2. 如果仍然失败 → 记录到 EVENT_LOG.md（ERROR | GLOBAL_STATE_UPDATE_FAILED）
  3. 触发 harness-handle-failure
```

## Relationships

### Triggers (触发下游)

```yaml
单会话模式:
  - harness-goal（创建 SMART 目标）

并行模式:
  - harness-schedule-parallel-agents（批量生成子代理）
```

### Triggered By (被谁触发)

```yaml
触发时机:
  - 主会话启动时（自动）
  - 子代理完成后（主会话选择下一个功能）
  - 功能开发完成后（标记完成，选择下一个）
  - 用户显式调用："选择下一个功能"
```

### Dependencies (前置依赖)

```yaml
必须依赖:
  - harness-init（系统初始化）
```

## Token 消耗分析

```yaml
小项目（10项）:
  - 读取 feature_list.json: ~500 tokens
  - JSON Schema 验证: ~100 tokens
  - 解析和排序: ~500 tokens
  - 更新 GLOBAL_STATE.md: ~50 tokens
  - 记录 EVENT_LOG.md: ~50 tokens
  - 输出功能信息: ~100 tokens
  总计: ~1300 tokens

大项目（200项）:
  - 读取 feature_list.json: ~8000 tokens
  - 其他步骤相同
  总计: ~8800 tokens
```

## Examples

### 示例 1: 选择第一个功能

```yaml
输入:
  feature_list.json 包含 6 个功能，全部 passes: false

处理:
  1. 读取并解析 JSON
  2. 验证 JSON Schema
  3. 过滤 passes: false（6 个功能）
  4. 排序：
     - FEAT-001 (priority: HIGH, category: core)
     - FEAT-002 (priority: HIGH, category: core)
     - FEAT-003 (priority: HIGH, category: core)
     - FEAT-004 (priority: MEDIUM, category: api)
     - FEAT-005 (priority: MEDIUM, category: api)
     - FEAT-006 (priority: LOW, category: ui)
  5. 选择 FEAT-001
  6. 更新 GLOBAL_STATE.md（current_feature: FEAT-001）
  7. 记录到 EVENT_LOG.md
  8. 输出功能信息
  9. 触发 harness-goal（单会话模式）

输出:
  功能ID: FEAT-001
  分类: core
  优先级: HIGH
  描述: 实现功能清单机制 - feature_list.json 强约束管理
```

### 示例 2: 无未完成功能

```yaml
输入:
  feature_list.json 包含 6 个功能，全部 passes: true

处理:
  1. 读取并解析 JSON
  2. 过滤 passes: false（空列表）
  3. 输出提示："所有功能已完成"

输出:
  🎉 所有功能已完成！
  总功能数：6
  已完成：6
  完成率：100%

  下一步：
  - 生成最终报告
  - 触发 harness-auto-full-execution 结束流程
```

## Implementation Notes

### 关键设计决策

1. **JSON Schema 强约束**
   - 仅允许修改 `passes` 字段
   - 禁止删除或编辑功能描述
   - 每次修改前验证 Schema

2. **优先级排序**
   - priority > category > id
   - 确保高优先级功能优先开发
   - 同优先级按分类排序（core > api > ui）

3. **模式切换**
   - 自动识别项目规模
   - 小项目 → 单会话模式（节省 Token）
   - 大项目 → 并行模式（提高吞吐）

### 性能优化

```yaml
大项目优化:
  - 使用 JSON 压缩（去掉空格和缩进）
  - Token 消耗降低 30%

状态读取优化:
  - 仅读取必要字段（id, priority, category, passes）
  - Token 消耗降低 50%
```