Claude-Code-Workflow/.codex/skills/codex-issue-plan-execute/phases/state-schema.md

State Schema Definition

状态结构定义和验证规则。

初始状态

{
  "status": "pending",
  "phase": "init",
  "work_dir": "",
  "issues": {},
  "queue": [],
  "completed_actions": [],
  "context": {
    "total_issues": 0,
    "completed_count": 0,
    "failed_count": 0
  },
  "errors": [],
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601"
}

状态转移

pending
  ↓
init (Action-Init)
  ↓
running
  ├→ list (Action-List) → Display issues
  ├→ plan (Action-Plan) → Plan issues
  ├→ execute (Action-Execute) → Execute solutions
  ├→ back to list/plan/execute loop
  │
  └→ complete (Action-Complete) → Finalize
       ↓
completed

字段说明

字段	类型	说明
status	string	"pending"|"running"|"completed" - 全局状态
phase	string	"init"|"listing"|"planning"|"executing"|"complete" - 当前阶段
work_dir	string	工作目录路径
issues	object	Issue 状态映射 {issue_id: IssueState}
queue	array	待执行队列
completed_actions	array	已执行动作 ID 列表
context	object	执行上下文信息
errors	array	错误日志

Issue 状态

{
  "id": "ISS-xxx",
  "title": "Issue title",
  "status": "registered|planning|planned|executing|completed|failed",
  "solution_id": "SOL-xxx-1",
  "planned_at": "ISO-8601",
  "executed_at": "ISO-8601",
  "error": null
}

Queue Item

{
  "item_id": "S-1",
  "issue_id": "ISS-xxx",
  "solution_id": "SOL-xxx-1",
  "status": "pending|executing|completed|failed"
}

验证函数

function validateState(state) {
  // Required fields
  if (!state.status) throw new Error("Missing: status");
  if (!state.phase) throw new Error("Missing: phase");
  if (!state.work_dir) throw new Error("Missing: work_dir");

  // Valid status values
  const validStatus = ["pending", "running", "completed"];
  if (!validStatus.includes(state.status)) {
    throw new Error(`Invalid status: ${state.status}`);
  }

  // Issues structure
  if (typeof state.issues !== "object") {
    throw new Error("issues must be object");
  }

  // Queue is array
  if (!Array.isArray(state.queue)) {
    throw new Error("queue must be array");
  }

  return true;
}

状态持久化

// 保存状态
function saveState(state) {
  const statePath = `${state.work_dir}/state.json`;
  Write(statePath, JSON.stringify(state, null, 2));

  // 保存历史
  const historyPath = `${state.work_dir}/state-history.json`;
  const history = Read(historyPath).then(JSON.parse).catch(() => []);
  history.push({
    timestamp: new Date().toISOString(),
    phase: state.phase,
    completed_actions: state.completed_actions.length,
    issues_count: Object.keys(state.issues).length
  });
  Write(historyPath, JSON.stringify(history, null, 2));
}

// 加载状态
function loadState(workDir) {
  const statePath = `${workDir}/state.json`;
  return JSON.parse(Read(statePath));
}