---
name: "structured-execution-recording"
version: "1.0.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "stable"
description: "结构化执行录制协议。为每个切片的执行过程建立可解析的结构化记录（元数据、Agent 动作轨迹、关键决策日志），为执行后分析和 Skill 质量评估提供数据基础。借鉴 OpenSpace Recording Layer 机制。"
trigger_phases: ["all"]
applicable_agents: ["Copilot Orchestrator"]
priority: 5
---

# Structured Execution Recording — 结构化执行录制

> **来源**：OpenSpace `recording/` 子系统（action_recorder + conversation_formatter + trajectory logger）。
> **实现方式**：基于 agentLog 文件系统的结构化录制，无运行时状态依赖。

## 何时触发

| 触发条件 | 说明 |
|---|---|
| 切片开始时（Orchestrator 路由第一个 Agent） | 初始化录制目录和 metadata |
| 每个 Agent 完成一轮工作后 | 追加动作轨迹条目 |
| 阶段切换时 | 追加阶段转换记录和决策日志 |
| 切片关闭时（P8） | 归档录制产物，触发后续分析 |

## 谁来调用

| Agent | 职责 |
|---|---|
| **Copilot Orchestrator** | 初始化/归档录制，记录路由决策和阶段转换 |
| **所有实施/验证类 Agent** | 在工作完成后上报动作摘要 |

---

## §1 录制目录结构

每个切片创建独立的录制目录：

```
.github/agentLog/recordings/{sliceId}/
  ├── metadata.md          # 切片元数据（一次创建，closure 时终态更新）
  ├── trajectory.md        # Agent 动作轨迹（追加式写入）
  ├── decisions.md         # 关键决策日志（追加式写入）
  └── skill-usage.md       # Skill 使用汇总（阶段切换时更新）
```

---

## §2 录制内容规范

### 2.1 元数据（metadata.md）

切片开始时由 Orchestrator 创建，closure 时更新终态字段。

```markdown
# Recording Metadata — {sliceId}

## 切片信息
- **Slice ID**: {sliceId}
- **模块**: {module name}
- **描述**: {one-line description}
- **执行模式**: Full / Sprint / Micro
- **复杂度**: Low / Medium / High

## 时间线
- **开始时间**: {ISO timestamp}
- **结束时间**: {ISO timestamp | RUNNING}
- **总耗时**: {duration | RUNNING}

## 参与 Agent
| Agent | 阶段 | 进入时间 | 退出时间 | Verdict |
|---|---|---|---|---|
| {agent name} | {phase} | {timestamp} | {timestamp} | {PASS/FAIL/BLOCKED/N-A} |

## Skills 选择
| Skill ID | 被引用次数 | 被应用次数 | 备注 |
|---|---|---|---|
| {skill} | {n} | {n} | {note} |

## 阶段轨迹
| 阶段 | 进入时间 | 退出时间 | 门禁状态 |
|---|---|---|---|
| discovery | {timestamp} | {timestamp} | PASS |
| architecture | {timestamp} | {timestamp} | PASS |
| implementation | {timestamp} | {timestamp} | PASS |

## 最终结果
- **Status**: CLOSED / BLOCKED / ABANDONED
- **产出文件数**: {N}
- **返工次数**: {N}
- **Blockers 遇到**: {N}
```

### 2.2 Agent 动作轨迹（trajectory.md）

追加式记录每个 Agent 的实质性动作。

```markdown
# Execution Trajectory — {sliceId}

## 动作记录

### Step {N} — {ISO timestamp}
- **Agent**: {agent name}
- **Phase**: {current phase}
- **Action Type**: file_read | file_write | file_create | search | terminal | analysis | routing | gate_check
- **Target**: {file path or command or description}
- **Result**: success | error | skipped | blocked
- **Skill Reference**: {skill ID that guided this action, or "none"}
- **Duration Estimate**: fast (<5s) | medium (5-30s) | slow (>30s)
- **Note**: {brief description of what was accomplished}

---

### Step {N+1} — {ISO timestamp}
...
```

**动作类型分类**：

| Action Type | 说明 | 示例 |
|---|---|---|
| `file_read` | 读取文件获取上下文 | 读取 Entity、设计文档 |
| `file_write` | 修改现有文件 | 编辑 Controller、Vue 组件 |
| `file_create` | 创建新文件 | 新建 VO、API 文件 |
| `search` | 搜索代码或文件 | grep_search、semantic_search |
| `terminal` | 执行终端命令 | 编译、运行测试 |
| `analysis` | 分析/审查产出 | Schema Guardian 报告、Code Review |
| `routing` | Orchestrator 路由决策 | 路由到 Implementation |
| `gate_check` | 门禁检查 | PRE-02 钩子检查 |

### 2.3 关键决策日志（decisions.md）

记录切片执行中的重要决策点。

```markdown
# Decision Log — {sliceId}

## Decision {N} — {ISO timestamp}
- **决策者**: {agent name}
- **阶段**: {phase}
- **决策类型**: routing | architecture | tradeoff | rollback | escalation | gate_override
- **上下文**: {what prompted this decision}
- **选项**:
  1. {option A} — {pros/cons}
  2. {option B} — {pros/cons}
- **最终选择**: {chosen option}
- **理由**: {rationale}
- **影响**: {downstream impact}

---
```

**决策类型分类**：

| Decision Type | 说明 | 典型场景 |
|---|---|---|
| `routing` | Agent 路由选择 | Orchestrator 选择 Implementation vs Code Gen |
| `architecture` | 技术架构选择 | Entity 继承策略、API 设计 |
| `tradeoff` | 权衡取舍 | 性能 vs 简洁度 |
| `rollback` | 阶段回退 | Review 发现问题回退到 Implementation |
| `escalation` | 权限升级 | Agent 请求超出边界的操作 |
| `gate_override` | 门禁豁免 | 特殊情况下跳过某门禁 |

### 2.4 Skill 使用汇总（skill-usage.md）

在每次阶段切换时更新。

```markdown
# Skill Usage Summary — {sliceId}

## 最后更新: {ISO timestamp}

## Skill 引用详情

### {Skill ID}
- **总引用次数**: {N}
- **应用事件**:
  | 时间 | Agent | 事件 | 备注 |
  |---|---|---|---|
  | {timestamp} | {agent} | REFERENCED / APPLIED / EFFECTIVE / FALLBACK | {note} |
- **当前判定**: APPLIED / PARTIALLY_APPLIED / FALLBACK / NOT_APPLICABLE

### {Next Skill ID}
...
```

---

## §3 录制协议

### 3.1 初始化协议（切片开始时）

Orchestrator 在接到切片任务后、路由第一个 Agent 前执行：

1. 创建录制目录：`.github/agentLog/recordings/{sliceId}/`
2. 创建 `metadata.md`（填充切片信息和时间线起点）
3. 创建空的 `trajectory.md`、`decisions.md`、`skill-usage.md`
4. 在路由指令中附带：`Recording: ACTIVE, Path: .github/agentLog/recordings/{sliceId}/`

### 3.2 Agent 动作上报协议

每个 Agent 在完成一轮实质性工作后，在输出末尾追加录制摘要：

```markdown
### Recording — Trajectory Append
- Step: {auto-increment}
- Agent: {self}
- Phase: {current phase}
- Actions:
  - {action_type}: {target} → {result} [Skill: {skill_id or none}]
  - {action_type}: {target} → {result} [Skill: {skill_id or none}]
- Skills Referenced: [{skill_ids}]
- Skills Applied: [{skill_ids with APPLIED status}]
```

Orchestrator 负责将上报内容追加到 `trajectory.md`。

### 3.3 决策记录协议

Orchestrator 在以下时刻记录决策：

| 时刻 | 记录内容 |
|---|---|
| Agent 路由选择 | 为何选择此 Agent、备选方案、阶段上下文 |
| 阶段切换 | 门禁状态、切换原因、是否有回退 |
| Blocker 出现/解除 | Blocker 原因、影响范围、解除方式 |
| 用户干预 | 用户修改了什么、对执行路径的影响 |
| 权限升级 | 哪个 Agent 请求什么操作、是否批准 |

### 3.4 归档协议（切片关闭时）

Orchestrator 在 closure 阶段执行：

1. 更新 `metadata.md` 的终态字段（结束时间、最终结果、产出文件数）
2. 确认 `trajectory.md` 和 `decisions.md` 完整
3. 汇总 `skill-usage.md` → 触发 `skill-effectiveness-tracker` 指标更新
4. 录制目录保持在 `.github/agentLog/recordings/{sliceId}/` 不移动

---

## §4 录制产物消费方

| 消费者 | 用途 | 消费内容 |
|---|---|---|
| `post-execution-analysis` | 执行后结构化分析 | metadata + trajectory + decisions + skill-usage |
| `skill-effectiveness-tracker` | 指标采集更新 | skill-usage |
| `skill-evolution-protocol` | 演进决策的上下文输入 | trajectory（识别 Skill 失败模式） |
| Copilot Test Retrospective | 测试稳定性分析 | trajectory（测试相关动作） |
| Orchestrator | 跨会话恢复 | metadata（切片状态） |
| 用户 | 执行过程审计 | 全部录制产物 |

---

## §5 轻量模式

对于 Micro 执行模式（1-5 文件变更的小任务），可启用轻量录制：

| 维度 | 完整模式 | 轻量模式 |
|---|---|---|
| metadata.md | 完整 | 仅基础字段（切片 ID、时间、结果） |
| trajectory.md | 每步记录 | 仅关键动作（file_write、gate_check） |
| decisions.md | 所有决策 | 仅 routing 和 rollback |
| skill-usage.md | 完整追踪 | 省略，由 POST hook 直接上报 |

Orchestrator 根据执行模式（Full/Sprint/Micro）自动选择录制深度。

---

## §6 与其他 Skill 的集成关系

| 关联 Skill | 集成方式 |
|---|---|
| `skill-effectiveness-tracker` | skill-usage.md 作为指标采集的原始数据源 |
| `post-execution-analysis` | 全部录制产物作为分析输入 |
| `agent-hook-lifecycle` | POST hooks 是 Agent 上报动作的通道 |
| `agent-execution-governance` | 录制不改变任何 Agent 的权限边界 |
| `skill-evolution-protocol` | trajectory 中的 Skill 失败模式供演进决策参考 |

---

## §7 变更记录

| 日期 | 版本 | 变更 |
|---|---|---|
| 2026-04-17 | 1.0.0 | 初始版本：录制目录结构、4 类录制内容、录制协议、归档协议、轻量模式 |