事件与 Transcript 记录（Event and Transcript Recording）

目标关联

该特性支撑可审计交付、专业可靠性、上下文连续性和未来群组协作。

实现的关键特性：

• Sandbox-First Work Execution
• Tool-Mediated Action System
• Quality and Governance System
• Professional Workflow Orchestration
• Learning and Capability Evolution

技术设计对齐

• durable artifacts 是 source of truth。
• records append-only 且 Phase 1 基于文件系统。
• JSONL events 机器可读。
• Markdown transcript 人类可读。
• tool calls 可观测。
• future scheduler 可使用 event streams 和 run state。

范围

Phase 1 包含 events.jsonl、transcript.md、logs/tools.jsonl、logs/errors.jsonl、基础 event types、timestamps、run status events、tool call records、deliverable validation events。

排除 centralized event store、distributed tracing、dashboard、advanced redaction、full token/cost accounting、replay engine。

概念模型

events.jsonl
  canonical machine-readable run timeline

transcript.md
  human-readable process summary

logs/tools.jsonl
  detailed tool call records

logs/errors.jsonl
  errors and recoverable failures

Event Types

Phase 1 建议包括：

run.created
run.started
run.completed
run.failed
config.loaded
prompt.rendered
skill.indexed
skill.loaded
memory.recall.started
memory.recall.completed
memory.write.requested
tool.started
tool.completed
tool.failed
file.read
file.written
file.rejected
deliverable.check.started
deliverable.check.completed
deliverable.missing
error

Event Shape

{
  "event_id": "evt_...",
  "sequence": 12,
  "run_id": "run_...",
  "session_id": "sess_...",
  "task_id": "task_...",
  "type": "tool.completed",
  "timestamp": "2026-04-26T10:00:00Z",
  "actor": "tool",
  "severity": "info",
  "correlation_id": "call_...",
  "parent_event_id": "evt_...",
  "summary": "read_file completed",
  "data": {}
}

必填字段：event_id、sequence、run_id、session_id、task_id、type、timestamp、actor、severity、summary、data。

sequence 在单个 run 内单调递增，是排序 source of truth。Timestamp 只用于 wall-clock 分析。

Transcript Shape

transcript.md 面向人类检查，建议包含：

# Run Transcript
## Metadata
## Prompt
## Effective Role Summary
## Skills Used
## Tool Activity Summary
## Work Notes
## Deliverables
## Errors and Warnings

Transcript 摘要重要动作并链接详细记录，不保存每个原始 token。

接口

class EventRecorder:
    def emit(self, event_type: str, data: dict) -> None:
        ...

class TranscriptWriter:
    def append_section(self, title: str, content: str) -> None:
        ...

运行时行为

Runtime、config loader、prompt renderer、skill registry、memory tools、tool wrappers、filesystem tools、governance 组件都通过 recorder 写入 events。Run 结束时 finalized transcript。

产物

runs/<run-id>/events.jsonl
runs/<run-id>/transcript.md
runs/<run-id>/logs/tools.jsonl
runs/<run-id>/logs/errors.jsonl

同时更新 run.json 的最终状态和时间戳。

质量和治理

• 每个 tool call 被记录。
• 被拒绝的 filesystem operation 被记录。
• 缺失 deliverables 被记录。
• errors 有足够上下文用于调试。
• records append-only。
• 敏感信息不直接写入 events。

性能和调度考虑

JSONL append 低成本；大型 outputs 默认摘要；记录 duration；events 包含 IDs 和 state transitions，支持 future scheduler 监控、恢复和 revision。

验收标准

1. 每个 run 创建 events.jsonl 和 transcript.md。
2. Tool calls 记录 start/completion/failure/duration。
3. Errors 写入 logs/errors.jsonl。
4. File operations 被记录或摘要。
5. Deliverable checks 发出 events。
6. Events 包含 IDs、单调 sequence、actor、severity、summary。
7. Event writes append-only。
8. Transcript 人类可读并指向 deliverables。