AI Agent System Architecture

AI Agent System Architecture Skill

定位

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

模型表达是非确定性输入，质量诊断与工具事实分别处理：内部标题、模板、阅读回执和短期入口元数据应能重建，不能成为整项任务硬门禁。恢复需保留原任务身份、实际宿主身份、精确目标与 operation 派发/效果记录；同一操作可读回后结算，未知副作用不得盲目重放。验证采用公共入口、表达变体、故障恢复和真实文件结果，不把固定文案断言当成原意遵守的证明。

触发条件

核心门禁

AgentCapabilityDomainCompletenessGate

每个适用能力域必须记录 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。