菜单
AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用；要求把 Agent 行为设计成可解释、可恢复、可审计。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/devcodex-labs/devcodex --skill ai-agent-system-architecture命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | ai-agent-system-architecture |
| description | AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用；要求把 Agent 行为设计成可解释、可恢复、可审计。 |
本 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 |
| 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。
新增或改变 Agent 可调用能力面时，本 Skill 只向 spec-governance#CapabilitySurfaceDecisionGate 提供语义判断边界、model/application/user/host 控制方、read/write/execute 权限、状态机、authority、Task 协商、取消/超时/幂等和审计证据。它读取中央 decisionRef，不得自行决定或复制 preferredSurface 等 canonical 字段；MCP 能力、Tasks 或宿主行为没有 direct evidence 时保持 UNVERIFIED，不得由 Agent 名称或概念相似性推断支持。
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 资格。ContextSourceObservationLedgerV1，lifecycle receipt 只作可重建投影；SkillRoute 仅在 epoch/plan/root/project 全同且 source metadata 新鲜时重放。旧快照覆盖不得丢失已交付证据，stale/blocked、source-digest 或 profile-drift 不得被 ledger 绕过。partial/unverified，后续安全、CP、治理和验证门禁不得因节流而降低。正式任务的 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。
当任务涉及长时间运行、工具完成后无续接、线程持续 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。
IntentSeedV1、目标、ContextReadPlanV2（V1 兼容）、Skill、工具、回执、确认、报告。## 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 或恢复写操作 | 只返回已校验的数据投影；写操作恢复必须另走授权和幂等复证 |
intent / routing：意图和 Skill 路由是 Agent 系统入口。memory / summary：上下文恢复和状态新鲜度需要联动。host-contract-verification：宿主行为变化需验证事件和可见回复。