ai-agent-system-architecture

name	ai-agent-system-architecture
description	AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用；要求把 Agent 行为设计成可解释、可恢复、可审计。

AI Agent System Architecture Skill

定位

本 Skill 负责 AI Agent 系统 Owner 视角。它把 Agent 当作状态机和工具执行系统，而不是只关注 prompt 文案。

触发条件

场景	是否触发
Agent 路由、意图识别、Skill 触发、工具调用、权限、记忆、handoff、summary、hook 状态	必须
任务涉及模型辅助治理、自动吸纳、自动复审、回放验证、可观测性或人机确认	必须
报告或方案需要解释 Agent 为什么选择某工作流或工具	必须
纯业务代码且不涉及 Agent 执行系统	N/A + skipReason

核心门禁

Gate	要求	证据
AiAgentSystemArchitectureGate	Agent 行为必须有路由、工具权限、上下文、状态机、观测和人机边界	intentRouting、toolPermissionBoundary
AgentRoutingGate	意图、Skill、模式和降级路径必须可解释	intentRouting
ToolPermissionBoundaryGate	工具权限、危险操作、确认和 fallback 必须明确	toolPermissionBoundary
ContextAcquisitionGate	每条消息必须先形成语义种子与唯一目标，再按计划读取最小充分上下文，并用 Post 成功回执证明完成	IntentSeedV1、ContextReadPlanV2、ContextReadReceiptV2（V1 兼容）
ContextMemoryStateGate	上下文恢复、记忆、handoff 和状态新鲜度必须设计	contextMemoryModel
TaskContinuityWriteGate	正式任务写入必须由单一 V5 store owner、精确 state/writer fence、canonical write context、operation 状态机与 terminal lineage 共同约束；TTL 不产生写权	taskContinuityWriteContract
ReplayObservabilityGate	行为验证不能只靠文字说明，需 replay、fixture 或日志证据	observabilityReplay
TurnLivenessRecoveryGate	长任务或工具输出后的 turn 必须用事件时间、AI-owned lease、continuation ACK、terminal invariant 与 checkpoint 区分运行、可疑、可恢复停滞和终态	turnLivenessContract、TurnRecoveryCard、TurnLivenessEvidence
LocalTaskTraceGate	当前 turn 的 typed trace 必须严格有序、拒绝重复/终态后追加，并只提供不执行 payload 的只读 replay	LocalTaskTraceV1、LocalTaskTraceReplayV1
RepairCollaborationRoleBoundaryGate	repair task 必须把决策/验收与执行/验证角色、授权证据、状态与独立复证设计清楚；模型或 Agent 名称不构成风险分类	roleAssignments、authorizationEvidence、independentReReview
AgentCapabilityDomainCompletenessGate	声称完整/最终 Agent 架构或平台前先声明 completenessObject，并验证请求链、反馈链、横切面及适用产品/企业链	agentCapabilityDomainMatrix

AgentCapabilityDomainCompletenessGate

completenessObject	必查覆盖
kernel	ingress→cognition→context/knowledge→planning→execution/tools→response；observe→evaluate→evolve；governance/model/infrastructure
runtime	kernel + local/hosted composition、state、tool registry、security、observability、replay
developer-product	runtime + build→version→publish→deploy→invoke、SDK/CLI/API、local developer runtime、Agent Studio
hosted-platform	developer-product + run API、provider/connector/credential、deployment/fleet、tenant/workspace
enterprise-saas	hosted-platform + organization、entitlement、usage/metering/billing、admin/ops、audit/compliance

每个适用能力域必须记录 owner、publicPrivateBoundary、runtimeStatus、validationRoute。较窄对象通过不能升级解释为较宽对象完整；报告使用“完整/最终/无需新增域”时，缺少 completenessObject 或任一适用域即判 incomplete。

CapabilitySurfaceDecision 证据提供者

新增或改变 Agent 可调用能力面时，本 Skill 只向 spec-governance#CapabilitySurfaceDecisionGate 提供语义判断边界、model/application/user/host 控制方、read/write/execute 权限、状态机、authority、Task 协商、取消/超时/幂等和审计证据。它读取中央 decisionRef，不得自行决定或复制 preferredSurface 等 canonical 字段；MCP 能力、Tasks 或宿主行为没有 direct evidence 时保持 UNVERIFIED，不得由 Agent 名称或概念相似性推断支持。

ContextAcquisitionGate

Agent 上下文获取采用以下状态链，任何一步都不得用后一步的推断倒填：

IntentSeedV1 → unique project/activeRoot → ContextReadPlanV2（V1 兼容）→ attempted → PostToolUse observed → ContextReadReceiptV2（V1 兼容）→ project reality/final route

• IntentSeedV1 仅来自当前消息语义和已观察到的 continuity，不得先全文读取 Profile / memory 再“识别”意图；关键词不是 canonical intent。
• ContextReadPlanV2 必须显式区分 baseline、selected、excluded、unclassified 与 fullReadReason，并把稳定 planContentId 与 invocation planId 分离；ContextReadPlanV1 仅保留读取兼容。默认读取最小充分来源；Profile 规划阶段不得 hidden full read，记忆使用 bounded status/session/summary query。
• ContextReadReceiptV2 只接受 planId、planContentId、contextEpoch、activeRoot、source identity/query 和结果精确关联的 PostToolUse 成功证据。PreToolUse、计算 cache hit、旧全文工具返回或 fallback 文案都不能声明 complete；V1 receipt 不具备跨 epoch delivery reuse 资格。
• MCP 本地 stdio 正文观察先写入有界 ContextSourceObservationLedgerV1，lifecycle receipt 只作可重建投影；SkillRoute 仅在 epoch/plan/root/project 全同且 source metadata 新鲜时重放。旧快照覆盖不得丢失已交付证据，stale/blocked、source-digest 或 profile-drift 不得被 ledger 绕过。
• SkillRoute per-turn envelope 是临时执行 cache，不是正式任务存储。容量必须按语义活跃对象计数；空 orphan、无业务义务终态和同会话已被后继 context 取代的未提交 route 只能在 root/turn lock、identity 与 quarantine/readback 复证后有界退出。protected、live lock、identity mismatch、其他会话未完成 route 和业务回复义务必须保留并在 hard pressure 下失败关闭。正式任务数量仍由 TaskRecoveryStoreV5 的字节/headroom 合同治理，不得套用 per-turn 数量上限。
• 用户/项目明确要求、audit/migration、低置信或必要来源缺失可升级全量；目标、scope/action/risk、source digest 或 compact/resume 发生实质漂移时重新规划。不得每个动作都重复加载。
• 宿主缺少结构化工具时可走一次 path-observable / instruction fallback；证据不足保持 partial/unverified，后续安全、CP、治理和验证门禁不得因节流而降低。

TaskContinuityWriteGate

正式任务的 locator、当前写者、单次 operation、终态和运行时投影是不同边界，不能把“找到了任务”解释为“可以写”。所有正式 envelope commit 必须由 TaskRecoveryStoreV5 精确比较 TaskRecoveryCommitFenceV1.stateSequence + writerGeneration；force 不绕过 stale fence，writer generation 只可在 owner transition 中增加 1。owner claim/transition 后必须 readback CanonicalTaskWriteContextV1，writer 绑定 task/root、lifecycle revision、state sequence、writer generation、holder session、operation/settled set digest、runtime generation 与 context digest。TTL 只作 freshness、清理和诊断，不能产生 takeover。

每个任务最多存在一个未结算 mutating TaskOperationRecordV1，固定经过 prepared → dispatched → observed → settled，未知副作用转 reconcile-required，未派发才允许 aborted-zero-effect。已派发操作不得自动重试；迟到回执和 emergency reserve 只能推进同一 operationId、idempotency key、writer generation、exact targets 与 before digest。terminal 必须同时验证 current writer、write context fence、settled set 和独立证据；replay 零新写，reopen 产生 lifecycle revision+1 与新 owner generation。

TurnLivenessRecoveryGate

当任务涉及长时间运行、工具完成后无续接、线程持续 inProgress、恢复或宿主停滞时，先冻结 TurnLivenessContract：

字段	要求
stateModel	至少区分 idle / running / awaiting-continuation / suspect / stalled-recoverable / completed / error / interrupted
eventEvidence	turnKey / lastEventType / lastEventAt / lastToolOutputAt / continuationAckAt
lease	只有已放行的 AI-owned operation 才能建立 lease；用户进程或未知 PID 不能作为可清理 lease
terminalInvariant	tool output 不等于 turn 完成；显式 Stop/error/interruption 后必须清除 in-flight lease
checkpoint	phase / artifactPaths / nextAction / resumeToken / idempotencyKey，恢复前必须验证幂等边界
checkpointValidation	response-time 与 post-execution 分开记录；缺 post evidence 只能 unverified/incomplete-timeout，实际 terminal evidence 才能 pass
localTaskTrace	traceId/turnKey/status/sequence/openedAt/completedAt/events；eventId 唯一、sequence 从 1 递增、terminal 唯一且最后
capabilityBoundary	分开记录 host-native watchdog、Hook event-time detection 与 read-only sidecar；Hook 无事件时不得宣称能自唤醒
validation	direct replay + no-continuation / active-lease / restart-rehydrate / duplicate-recovery fault matrix

默认 awaiting-continuation 可采用 120 秒 suspect / 300 秒 stalled advisory；慢模型推理和长工具必须由更长的 agent/operation lease 覆盖，不能机械套用 ACK 阈值。观察到 stale 只生成 TurnRecoveryCard；没有宿主授权与幂等复证时，禁止自动重放 mutation、kill/restart/interrupt/resume。

LocalTaskTraceV1 只保存当前 turn；历史 turn 由 TurnLiveness 摘要承接。重启时先校验 identity/sequence/duplicate/terminal，再生成 LocalTaskTraceReplayV1 数据投影；replay 的 stateMutation/operationReplay/payloadExecution/processControl 必须全部为 false。

执行步骤

1. 建立 Agent 行为图：用户输入、IntentSeedV1、目标、ContextReadPlanV2（V1 兼容）、Skill、工具、回执、确认、报告。
2. 明确工具权限边界：宿主拥有文件、删除和命令权限，DevCodex 只约束工作流有效性并提供风险 advisory；adapter missing/failed/invalid/outside-workspace 不得建立本地 shadow deny；能力面发生变化时向中央 decision 提供控制方、authority、状态与 Task 证据。
3. 定义上下文、记忆、handoff、summary 和恢复优先级。
4. 设计状态机和失败恢复：blocked、retry、fallback、handoff。
5. 用 direct replay、fixture replay、validate 或日志证据验证关键行为。

输出字段

## AiAgentSystemArchitectureGate

| 字段 | 内容 |
|------|------|
| intentRouting | 意图、Skill、模式、降级路径 |
| toolPermissionBoundary | 工具权限、确认、危险操作和 fallback |
| contextMemoryModel | 上下文、记忆、handoff、summary、状态新鲜度 |
| contextAcquisition | seed、target、plan、selected/excluded、fullReadReason、fallback |
| contextReadReceipt | `ContextReadReceiptV2`（V1 兼容）的 Post 成功证据、内容身份、复用来源、缺失来源与完成状态 |
| stateMachineHandoff | 状态机、恢复、阻塞、交接 |
| observabilityReplay | replay、fixture、日志、validate 证据 |
| turnLivenessContract | 状态、事件、lease、ACK、终态、双阶段 checkpoint、LocalTaskTrace、能力边界与故障矩阵 |
| taskContinuityWriteContract | store owner、state/writer fence、CanonicalTaskWriteContext、operation 状态机、terminal/reopen、TTL 边界与负向探针 |
| humanInLoopBoundary | 用户确认、auto、人工复核和最终责任边界 |
| capabilitySurfaceEvidence | `decisionRef`、控制方、read/write/execute、authority、状态/Task 与直接证据边界 |
| evidenceMatrix | 判断 -> hook / runtime / report / memory / replay / tests |
| agentCapabilityDomainMatrix | completenessObject -> domain -> owner / boundary / runtime / validation |

反模式

反模式	修正
把 Agent 能力写成 prompt 愿望	写路由、状态机、工具权限和验证
用 summary 覆盖文件真相源	遵循 Context Rehydration Contract
先全文读取 Profile / memory 再判断意图	先形成 IntentSeedV1 与唯一目标，再执行有界计划和定向查询
把 PreToolUse、cache hit 或旧全文工具返回写成已完成	仅以精确关联的 PostToolUse 成功结果生成 ContextReadReceiptV2；delivery reuse 还须同 session/epoch/source identity
自动模式绕过危险确认	保留 S01/S06 等不可豁免底线
行为变更无 replay	补 direct/fixture replay 或等价 validate
把 Hook 状态写入当成无事件 watchdog	明确 event-time detection 边界，并用宿主能力或 gray read-only sidecar补充观察
trace replay 执行 payload 或恢复写操作	只返回已校验的数据投影；写操作恢复必须另走授权和幂等复证

与其他 Skill 的关系

• intent / routing：意图和 Skill 路由是 Agent 系统入口。
• memory / summary：上下文恢复和状态新鲜度需要联动。
• host-contract-verification：宿主行为变化需验证事件和可见回复。