SOP Document  ·  v3.0  ·  Active

Agentic Coding
Workflow

Local Agentic Orchestration System  /  MacStudio M4 Max Standard
Last Revised  2026.03.01
Version  3.0
Status  Approved
Reviewed by  Reviewer Provider (claude/gemini/deepseek)
01 /

Role Matrix  角色分配

ADMIN
ADMIN
项目总负责人 / 架构师
Kircérta (Human)

项目的最高权限执行者,对项目状态和进展方向拥有绝对控制权。系统运作的最终拍板人与紧急 Override 来源。

  • 发布宏观指令与最终需求。
  • 审批执行计划书,拥有一票否决权。
  • 对高危操作预警进行强制干预 (Override)。
  • 审核并批准 Main 分支的最终 Pull Request。
  • 响应 Coordinator 的 Hallucination Lock 上报。
COORDINATOR
COORDINATOR
项目经理 / 沟通中枢
Gemini 3.1 Pro

解析 Admin 指令并向下分发,维护 GitHub 共享状态文件作为唯一真相来源 (SSOT),管理 Agent 间通信路由。

  • 接收、拆解指令,确保与 Admin 认知一致。
  • 将执行计划以 JSON Payload 写入 GitHub 操作日志。
  • 主动监视 CI/CD 邮件及 Webhook,密切跟进 Review 进程。
  • 触发并维护 Hallucination Lock 及 Heartbeat 监测。
  • 在 Sandbox 内根据风险等级自主批准操作。
EXECUTOR
EXECUTOR
首席程序员 / 技术实现
Codex 5.3

技术细节执行者。利用 M4 Max 硬件特性编写高质量代码,严格遵循 Reviewer 的修改意见,无条件配合 QA Loop。

  • 以最高技术标准编写及修改代码。
  • 自我判断任务阶段是否完毕并留下结构化 Log。
  • 对 Reviewer 的修改意见保持高度专注,无条件执行。
  • 在 Hallucination Lock 触发后,主动停止并移交 Admin。
REVIEWER / QA
REVIEWER / QA
代码审计 / 质量监督
Reviewer Provider (claude/gemini/deepseek)

质量监督与审核者。以极度严格的假设检验态度审查代码逻辑与架构,并在权限范围内直接介入小问题修复。

  • 以具可持续发展思维的眼光审查代码逻辑与架构。
  • 直接修复 diff <5行 且属于 [typo / lint / whitespace / import order] 的问题。
  • 发现逻辑漏洞时,生成具体修改意见并通知 Coordinator 打回。
  • 协助 Coordinator 在 CI 检测到问题时讨论解决方案。
02 /

Risk Classification  操作风险分级与审批权限

Risk Level Approval Operation Types Scope Constraint
● LOW ⚡ AUTO-APPROVE 注释修改、UI 颜色调整、文档更新、typo 修复、import order、whitespace、lint 修正,diff <5行的微小变更 Feature Branch 内有效
● MEDIUM 🔀 BRANCH AUTO-APPROVE 新功能模块实现、API 接口调用、逻辑重构、组件新增/删除、数据模型变更、CI 配置调整 Sandbox 内自动批准,不得触碰 Main
● HIGH 👤 ADMIN REQUIRED 合并至 Main 分支、App Store 提交、数据持久化方案变更、API 权限配置、核心文件删除、安全凭证操作 强制 Admin 审批,无例外
03 /

Execution Flow  标准执行流程

START ADMIN 发布指令 通过 CLI 或 Telegram 下达开发需求,附带验收标准。 COORDINATOR 接收与解读指令 与 Admin 讨论细节,确保认知一致,无疑惑。 是否存在疑惑未澄清? Decision Node YES NO COORDINATOR 撰写任务分配计划 结构化 JSON Payload → 写入 GitHub SSOT 日志 Repo。 等待 Admin 审核。 Admin 是否批准执行计划? Admin Override NO YES COORDINATOR 通知 Executor 执行任务 分发子任务,进入 Sandbox 阶段。 QA LOOP EXECUTOR 执行任务与自我判断 编写代码,自我判断阶段是否完毕。 EXECUTOR 交付审核 上传 Work Log 至 SSOT,通知 Reviewer。 问题是否在 Reviewer 权限内? diff <5行 ∩ { typo / lint / whitespace / import } YES REVIEWER 直接修复 留 log, 通知 Coordinator NO 生成修改意见 打回 Executor HALLUCINATION LOCK 同一 task_id 打回 >3 次时 强制挂起 → Admin 裁定 所有子任务是否已完成? Coordinator 二次核查 GitHub SSOT NO 下一子任务 YES COORDINATOR 推送代码,申请 Pull Request XCode Cloud 自动 Code Review,监控 Webhook 进程。 CI NOTE Codex/XCode 的 Review 记录会发送至本地邮箱。 无更新 = 无问题发现。 CI 是否检测到问题? YES Coordinator+Reviewer 分析问题,视严重度 通知 Executor 介入 返回执行阶段 NO COORDINATOR 任务完成通知 发送简报,Agent 进入待命状态。 Admin 是否批准 Pull Request? HIGH RISK — 强制 Admin 介入 NO END
04 /

Core Mechanisms  工程安全保障

// 01 — SANDBOXING

Sandboxing  沙盒隔离

所有 Agent 操作严格限制在独立 Feature Branch 内。禁止在未经 Admin 允许的情况下合并至 Main 分支或删除核心文件。Feature Branch 内的 Medium 风险操作由 Coordinator 自主批准。

SCOPE: Feature Branch Only
// 02 — AUTO-CHECKPOINT

Auto-Checkpoint  自动快照

在 Executor 执行任何代码覆写前,系统必须记录当前 Git 状态并写入 GitHub SSOT。确保每一步操作 100% 可回滚与可追溯,任何时间点均可恢复至任意历史快照。

POLICY: Immutable Before Write
// 03 — HALLUCINATION LOCK

Hallucination Lock  死循环防护

当同一 task_id 的 Executor 被 Reviewer 打回超过 3 次时,系统强制挂起任务,抛出异常并通知 Admin 裁定。3 次阈值依据:需求、能力与系统性问题。

THRESHOLD: task_id.reject_count > 3
// 04 — ASYNC APPROVAL QUEUE

Async Approval Queue  异步审批队列

Admin 离线时,决策节点进入 AWAITING_APPROVAL 状态。Coordinator 推送通知,Agent 可接手其他独立任务。Admin 回复后自动恢复,不阻塞流程。

STATE: AWAITING_APPROVAL (Non-blocking)
// 05 — COORDINATOR HEARTBEAT

Coordinator Heartbeat  心跳监测

SSOT 日志作为心跳检测器。若某 task_id 超过 30 分钟无新写入,触发告警推送。逻辑简洁,无需额外 Agent 即可保证系统活跃性。

TIMEOUT: 30min silence → Alert Admin
// 06 — SSOT CONTEXT PROTOCOL

SSOT Context Protocol  唯一真相来源

GitHub 作为所有 Agent 的共享状态存储。每个任务对应一个结构化 JSON,包含状态、计划、日志、裁定等。Agent 重启后可恢复状态,不依赖对话历史。

FORMAT: Structured JSON per task_id