工作流过程日志规范

本规范定义了 Swiss Army Knife 插件所有工作流的日志格式和写入模式。

日志级别

日志事件类型

会话事件

Phase 事件

Agent 事件（Coordinator 级）

Agent 内部事件（Phase Agent 级）

决策事件

Review 事件

警告和错误

JSONL 格式规范

每行一条完整的 JSON 记录，字段定义：

通用字段

{
  "ts": "YYYY-MM-DDTHH:MM:SS.000Z",  // ISO 8601 时间戳（必填）
  "level": "I",                       // 日志级别（必填）
  "type": "PHASE_START",              // 事件类型（必填）
  "session_id": "a1b2c3d4"            // 会话 ID（必填）
}

注意：以下示例中的时间戳仅为演示，实际使用时应替换为当前时间。

SESSION_START

{
  "ts": "2024-12-06T14:30:52.123Z",
  "level": "I",
  "type": "SESSION_START",
  "session_id": "a1b2c3d4",
  "workflow": "bugfix",
  "stack": "frontend",
  "command": "/swiss-army-knife:fix-frontend --log",
  "args": {
    "phase": "all",
    "dry_run": false,
    "log": true,
    "verbose": false
  },
  "env": {
    "project_root": "/path/to/project",
    "plugin_version": "1.0.0",
    "git_branch": "feature/login"
  }
}

SESSION_END

{
  "ts": "2024-12-06T14:40:00.000Z",
  "level": "I",
  "type": "SESSION_END",
  "session_id": "a1b2c3d4",
  "status": "success",
  "total_duration_ms": 548000,
  "phases_completed": ["phase_0", "phase_1", "phase_2", "phase_3", "phase_4", "phase_5"],
  "summary": {
    "errors_fixed": 3,
    "files_changed": 2,
    "review_issues_fixed": 4,
    "user_interactions": 2
  }
}

PHASE_START / PHASE_END

{
  "ts": "2024-12-06T14:30:53.456Z",
  "level": "I",
  "type": "PHASE_START",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "phase_name": "问题收集与分类",
  "agents": ["frontend-init-collector", "frontend-error-analyzer"]
}

{
  "ts": "2024-12-06T14:31:05.789Z",
  "level": "I",
  "type": "PHASE_END",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "status": "success",
  "duration_ms": 12333,
  "summary": {
    "errors_found": 3,
    "test_status": "test_failed"
  }
}

AGENT_CALL / AGENT_RESULT

{
  "ts": "2024-12-06T14:30:53.500Z",
  "level": "I",
  "type": "AGENT_CALL",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "model": "sonnet",
  "input_summary": "加载配置和收集测试输出"
}

{
  "ts": "2024-12-06T14:30:58.200Z",
  "level": "I",
  "type": "AGENT_RESULT",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "status": "success",
  "duration_ms": 4700,
  "output_summary": {
    "config_loaded": true,
    "test_output_lines": 150,
    "warnings_count": 1
  }
}

STEP_START / STEP_END（Agent 内部）

{
  "ts": "2024-12-06T14:30:54.000Z",
  "level": "I",
  "type": "STEP_START",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "step": "config_loading",
  "step_name": "加载配置",
  "step_index": 1,
  "total_steps": 3
}

{
  "ts": "2024-12-06T14:30:55.500Z",
  "level": "I",
  "type": "STEP_END",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "step": "config_loading",
  "status": "success",
  "duration_ms": 1500,
  "result_summary": {
    "default_config": true,
    "project_config": true,
    "merged": true
  }
}

TOOL_USE（Agent 内部）

{
  "ts": "2024-12-06T14:30:54.200Z",
  "level": "D",
  "type": "TOOL_USE",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "step": "config_loading",
  "tool": "Read",
  "target": "config/defaults.yaml",
  "status": "success"
}

DATA_COLLECTED（Agent 内部）

{
  "ts": "2024-12-06T14:30:56.000Z",
  "level": "I",
  "type": "DATA_COLLECTED",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "data_type": "test_output",
  "summary": {
    "lines": 150,
    "exit_code": 1,
    "status": "test_failed",
    "source": "auto_run"
  }
}

ANALYSIS_RESULT（Agent 内部）

{
  "ts": "2024-12-06T14:31:02.000Z",
  "level": "I",
  "type": "ANALYSIS_RESULT",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-error-analyzer",
  "analysis_type": "error_classification",
  "result": {
    "errors_found": 3,
    "categories": {
      "mock_conflict": 2,
      "async_timing": 1
    },
    "files_affected": ["Button.test.tsx", "Form.test.tsx"]
  }
}

CONFIDENCE_DECISION

{
  "ts": "2024-12-06T14:31:15.100Z",
  "level": "X",
  "type": "CONFIDENCE_DECISION",
  "session_id": "a1b2c3d4",
  "phase": "phase_1",
  "confidence_score": 65,
  "threshold": {
    "auto_continue": 60,
    "ask_user": 40,
    "stop": 0
  },
  "decision": "auto_continue",
  "factors": {
    "clarity": 70,
    "specificity": 60,
    "context": 65,
    "reproducibility": 55
  }
}

USER_INTERACTION

{
  "ts": "2024-12-06T14:32:00.000Z",
  "level": "X",
  "type": "USER_INTERACTION",
  "session_id": "a1b2c3d4",
  "phase": "phase_3",
  "interaction_type": "AskUserQuestion",
  "question": "Bugfix 方案已生成，请查看 docs/bugfix/xxx.md。确认后开始实施。",
  "options": ["确认执行", "调整方案", "取消"],
  "user_response": "确认执行",
  "wait_duration_ms": 15000
}

REVIEW_PARALLEL_START / REVIEW_PARALLEL_END

{
  "ts": "2024-12-06T14:35:00.000Z",
  "level": "I",
  "type": "REVIEW_PARALLEL_START",
  "session_id": "a1b2c3d4",
  "phase": "phase_5",
  "agents": [
    "review-code-reviewer",
    "review-silent-failure-hunter",
    "review-code-simplifier",
    "review-test-analyzer",
    "review-comment-analyzer",
    "review-type-design-analyzer"
  ]
}

{
  "ts": "2024-12-06T14:35:30.000Z",
  "level": "I",
  "type": "REVIEW_PARALLEL_END",
  "session_id": "a1b2c3d4",
  "phase": "phase_5",
  "duration_ms": 30000,
  "results": [
    {"agent": "review-code-reviewer", "status": "success", "issues": 2},
    {"agent": "review-silent-failure-hunter", "status": "success", "issues": 1},
    {"agent": "review-code-simplifier", "status": "success", "issues": 0},
    {"agent": "review-test-analyzer", "status": "success", "issues": 1},
    {"agent": "review-comment-analyzer", "status": "failed", "error": "timeout"},
    {"agent": "review-type-design-analyzer", "status": "success", "issues": 0}
  ],
  "total_issues": 4,
  "fixable_issues": 3
}

REVIEW_FIX_ITERATION

{
  "ts": "2024-12-06T14:36:00.000Z",
  "level": "I",
  "type": "REVIEW_FIX_ITERATION",
  "session_id": "a1b2c3d4",
  "phase": "phase_5",
  "iteration": 1,
  "issues_before": 4,
  "issues_after": 1,
  "fixed_count": 3,
  "termination_reason": null
}

WARNING / ERROR

{
  "ts": "2024-12-06T14:31:10.500Z",
  "level": "W",
  "type": "WARNING",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "code": "GIT_UNAVAILABLE",
  "message": "Git 信息收集失败：not a git repository",
  "impact": "根因分析将缺少版本控制上下文"
}

{
  "ts": "2024-12-06T14:33:00.000Z",
  "level": "E",
  "type": "ERROR",
  "session_id": "a1b2c3d4",
  "phase": "phase_1",
  "code": "CONFIDENCE_TOO_LOW",
  "message": "根因分析置信度 35% 低于阈值 40%",
  "agent": "frontend-root-cause",
  "recoverable": false
}

DEBUG: AGENT_IO（仅 –verbose）

{
  "ts": "2024-12-06T14:30:53.500Z",
  "level": "D",
  "type": "AGENT_IO",
  "session_id": "a1b2c3d4",
  "phase": "phase_0",
  "agent": "frontend-init-collector",
  "direction": "input",
  "content": "... 完整的 agent 输入 ..."
}

文本格式规范

人类可读的时间线格式，每行一条记录：

[{timestamp}] {LEVEL} | {TYPE} | {message}

格式示例

[2024-12-06 14:30:52.123] INFO | SESSION_START | Bugfix Frontend (a1b2c3d4)
[2024-12-06 14:30:52.123] INFO | ENV          | project=/path/to/project branch=feature/login
[2024-12-06 14:30:53.456] INFO | PHASE_START  | Phase 0: 问题收集与分类
[2024-12-06 14:30:53.500] INFO | AGENT_CALL   | frontend-init-collector (sonnet)
[2024-12-06 14:30:58.200] INFO | AGENT_RESULT | frontend-init-collector | success | 4700ms
[2024-12-06 14:31:05.789] INFO | PHASE_END    | Phase 0 | success | 12333ms | errors_found=3
[2024-12-06 14:31:06.000] INFO | PHASE_START  | Phase 1: 诊断分析
[2024-12-06 14:31:15.100] DECN | CONFIDENCE   | score=65 | decision=auto_continue | threshold=60
[2024-12-06 14:31:20.000] INFO | PHASE_END    | Phase 1 | success | 14000ms
[2024-12-06 14:32:00.000] DECN | USER_ASK     | "确认后开始实施" | options=[确认执行,调整方案,取消]
[2024-12-06 14:32:15.000] DECN | USER_ANSWER  | "确认执行" | wait=15000ms
[2024-12-06 14:35:00.000] INFO | REVIEW_START | 6 agents: code-reviewer,silent-failure-hunter,...
[2024-12-06 14:35:30.000] INFO | REVIEW_END   | 30000ms | issues=4 | fixable=3
[2024-12-06 14:36:00.000] INFO | REVIEW_FIX   | iteration=1 | before=4 | after=1 | fixed=3
[2024-12-06 14:40:00.000] INFO | SESSION_END  | success | 548000ms | files=2 | issues_fixed=4

级别对齐

INFO  - 正常信息（4 字符 + 空格）
DEBUG - 调试信息（5 字符）
WARN  - 警告（4 字符 + 空格）
ERROR - 错误（5 字符）
DECN  - 决策（4 字符 + 空格）

日志写入方法

使用 Bash 追加写入

由于 Write 工具会覆盖文件，必须使用 Bash 追加：

# JSONL 格式
echo '{"ts":"2024-12-06T14:30:52.123Z","level":"I","type":"PHASE_START",...}' >> "${jsonl_file}"

# 文本格式
echo '[2024-12-06 14:30:52.123] INFO | PHASE_START  | Phase 0: 问题收集与分类' >> "${log_file}"

JSON 转义注意事项

JSON 字符串中的特殊字符需要正确转义：

• 双引号 " → \"
• 反斜杠 \ → \\
• 换行符 → \n

时间戳格式

• JSONL: ISO 8601 格式 2024-12-06T14:30:52.123Z
• 文本: 人类可读 [2024-12-06 14:30:52.123]

获取当前时间戳：

# ISO 8601 格式（用于 JSONL）
date -u +"%Y-%m-%dT%H:%M:%S.000Z"

# 人类可读格式（用于文本）
date +"%Y-%m-%d %H:%M:%S.000"

日志上下文传递

层级 1: 命令层 → Master Coordinator

命令层传递给 coordinator 的 logging 上下文：

{
  "logging": {
    "enabled": true,
    "level": "info",
    "session_id": "a1b2c3d4"
  }
}

层级 2: Master Coordinator → Phase Agent

Master Coordinator 初始化日志文件后，传递给每个 Phase Agent：

{
  "logging": {
    "enabled": true,
    "level": "info",
    "session_id": "a1b2c3d4",
    "phase": "phase_0",
    "log_files": {
      "jsonl": ".claude/logs/swiss-army-knife/bugfix/2024-12-06_143052_frontend_a1b2c3d4.jsonl",
      "text": ".claude/logs/swiss-army-knife/bugfix/2024-12-06_143052_frontend_a1b2c3d4.log"
    }
  }
}

Phase Agent 日志记录模式

Phase Agent 收到 logging 上下文后，在每个主要步骤记录日志：

## 日志记录

如果 `logging.enabled` 为 `true`，在每个步骤记录日志：

### 步骤开始

\`\`\`bash
# JSONL
echo '{"ts":"'$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")'","level":"I","type":"STEP_START","session_id":"${session_id}","phase":"${phase}","agent":"${agent_name}","step":"config_loading","step_name":"加载配置","step_index":1,"total_steps":3}' >> "${jsonl_file}"

# 文本
echo "[$(date +"%Y-%m-%d %H:%M:%S.000")] INFO | STEP_START  | ${agent_name} | 步骤 1/3: 加载配置" >> "${log_file}"
\`\`\`

### 步骤结束

\`\`\`bash
# JSONL
echo '{"ts":"'$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")'","level":"I","type":"STEP_END","session_id":"${session_id}","phase":"${phase}","agent":"${agent_name}","step":"config_loading","status":"success","duration_ms":1500}' >> "${jsonl_file}"

# 文本
echo "[$(date +"%Y-%m-%d %H:%M:%S.000")] INFO | STEP_END    | ${agent_name} | 步骤 1/3 完成 | 1500ms" >> "${log_file}"
\`\`\`

Coordinator 内部维护

Coordinator 初始化后计算日志文件路径：

log_dir = ".claude/logs/swiss-army-knife/{workflow}"
timestamp = "2024-12-06_143052"
session_id = input.logging.session_id

jsonl_file = f"{log_dir}/{timestamp}_{identifier}_{session_id}.jsonl"
log_file = f"{log_dir}/{timestamp}_{identifier}_{session_id}.log"

传递给子 Coordinator（如 review-coordinator）

{
  "logging": {
    "enabled": true,
    "level": "info",
    "session_id": "a1b2c3d4",
    "log_files": {
      "jsonl": ".claude/logs/swiss-army-knife/bugfix/xxx.jsonl",
      "text": ".claude/logs/swiss-army-knife/bugfix/xxx.log"
    }
  }
}

日志查询示例

使用 jq 查询 JSONL

# 查看会话摘要
jq 'select(.type == "SESSION_START" or .type == "SESSION_END")' xxx.jsonl

# 查看所有错误
jq 'select(.level == "E")' xxx.jsonl

# 查看 Phase 耗时
jq 'select(.type == "PHASE_END") | {phase, duration_ms, status}' xxx.jsonl

# 查看置信度决策
jq 'select(.type == "CONFIDENCE_DECISION")' xxx.jsonl

# 查看用户交互
jq 'select(.type == "USER_INTERACTION")' xxx.jsonl

# 按时间排序
jq -s 'sort_by(.ts)' xxx.jsonl

# 计算总耗时
jq 'select(.type == "SESSION_END") | .total_duration_ms / 1000 | "\(.) 秒"' xxx.jsonl

使用 grep 查询文本日志

# 查看所有错误
grep "ERROR" xxx.log

# 查看 Phase 耗时
grep "PHASE_END" xxx.log

# 查看决策点
grep "DECN" xxx.log

# 查看特定 agent
grep "frontend-root-cause" xxx.log