agent-backend-standard

name	agent-backend-standard
version	1.2.0
description	生产级 agent 时代后端工程手册(hub)——建 / 评审 agent·LLM 后端、**任何碰 DB 的持久层后端**、或为任何后端建立 / 评审 repo 工程门禁时加载。覆盖:架构与控制流、上下文与 prompt 工程、工具设计(ACI)、记忆与状态、检索/RAG、韧性与幂等、人在环、安全护栏与生成操作的有界执行、评估、可观测与成本、代码/依赖生命周期与反死代码、**数据访问纪律(连接·读·写事务)**、**缓存纪律(准入·失效治理)**、**秘密接触面纪律(分离·deny·金丝雀)**、Python/Go/Java/Rust 统一 `fix/check/test` 工程接口与门禁、规范治理。本文件是目录,深度按需读 references/。可观测性/Git/A2A 对外契约是独立 skill,本 hub 交叉引用不重复。Use when building or reviewing agent/LLM backend code, ANY backend touching a database, or establishing/reviewing repository engineering gates for a backend: architecture, prompts, tools, memory, RAG, resilience, HITL, safety and bounded execution, eval, cost, code/dependency lifecycle, data access, and the Python/Go/Java/Rust fix/check/test gate interface.

Agent Backend — 后端工程手册（hub）

agent 时代后端工程规范的集中入口。本文件是目录(ToC):每章一句话 + reference 指针。深度全在 references/,按需读单章,别全量加载。

双层落地:软层 = 本手册(write-time 预防);硬层(CI 门禁 / ruleset / 清扫 bot)归 你的 IaC 仓 / IaC CTO。 粒度:同属"写·评审 agent 后端代码"这一触发的 concern 都在本 hub 作章;独立 skill 仅限触发动词不同者——埋点 → observability-standard、git → git-workflow-standard、A2A 对外契约 → A2A 对外契约规范(本 hub 交叉引用,不重复)。 TBD 章 = 已占位、待真实素材再写实(不空写通用建议)。

Book I — Foundations

• I-1 何时该建 agent —— simplicity-first;能确定性 / 工作流解决就别上 agent。TBD
• I-2 架构与控制流 —— augmented-LLM 基元、workflow 模式(chaining/routing/parallel/orchestrator-workers/evaluator)、单 vs 多 agent。TBD

Book II — Engineering Concerns

• II-3 上下文与 prompt 工程 → references/prompt-context.md —— 含 prompt 内容生命周期(写死值绑 eval、模型耦合打 REVISIT-WHEN)。
• II-4 工具 / 函数设计(ACI) —— 整合/命名空间/返回上下文/token 效率。TBD(交叉引 A2A 对外契约规范)
• II-5 记忆 / 状态 / 持久 → references/state-durability.md —— workflow 首次 runnable / 首个副作用前原子固化 immutable effective-config snapshot(snapshot_id + digest);step / resume / recovery 只读该 snapshot,缺失 / 损坏 / digest mismatch fail-closed。
• II-6 检索 / RAG / grounding —— chunking、faithfulness、向量弱点。TBD
• II-7 韧性 / 错误 / 幂等 → references/resilience.md —— 每个外部/LLM/工具调用:超时 + 有界重试 + 幂等 + 熔断 + 池/并发;事件循环不阻塞(async 运行时承重条,五层门禁:lint→测试期检测→staging 阈值→生产 lag 遥测→部署断言)。
• II-8 人在环(HITL)+ resume 安全 → references/hitl-resume-safety.md —— 可恢复 flow 的 resume 安全:六道闸防御(持久 checkpoint 校验请求 ctx、fail-closed、runtime 层)。clarify/approve 协议交叉引 A2A 对外契约规范。
• II-9 安全 · 护栏 · 生成操作的有界执行 → references/safety-bounded-execution.md —— 执行不可信生成操作(尤 SQL)的硬边界、安全分层、workflow 迭代上限。

Book III — Operations & Governance

• III-10 评估与测试 —— offline/online、LLM-as-judge、eval 驱动选型。TBD
• III-11 可观测与成本 / 时延 → references/observability-cost.md —— 薄:成本/token/时延预算;埋点本体交叉引 observability-standard,不重复。
• III-12 规范治理 → references/governance.md —— 例外/偏离、owner、手册如何演化。

附(本仓并入,非 agent 专属但同一触发)

• A 代码 / 依赖生命周期 + 反死代码 → references/code-dependency-lifecycle.md —— 引入即退役(ADR-with-sunset)、stale-but-live(EXPIRES/REVISIT-WHEN)、功能旗标生命周期(分类 + 毕业/退休 + 登记册)、死代码检测 + 盲区、反 bloat、清扫。
• B 数据访问纪律(连接·读·写) → references/data-write-discipline.md —— 读也占连接(弱事务/autocommit 用完即释放;MANAGED+closeConnection=false 无事务读 = 泄漏);记账写移出主链路 / 不跨 LLM 持锁 / 服务端增量;关键写保留原子性但同样不持锁跨 LLM/执行(短原子写 + 锁外执行)。
• C Agent-friendly engineering interface → references/engineering-interface.md §1–§6 —— Python / Go / Java / Rust 统一 repo-owned fix/check/test 接口；legacy ratchet 分 finding-aware hold gate + 单一 canonical close job，改善 durable 锁定后才放下一次集成、check 不改 baseline；另含初始化 forcing function 与失败自解释契约。边界类型规则只交叉引 observability §2,不复制。
• D 缓存纪律(准入·永不缓存·失效治理) → references/caching-discipline.md —— 四轴准入(读写比>10:1 / 陈旧红线 / 所有权 / DB 实测不够快,任一不过即不缓存)+ 金钱/占位/鉴权永不缓存、per-user 键强制 userId 命名空间 + agent 时代失效治理三件套(缓存决策表 SoT / 失效键注册 enum / 写路径配对失效机检门,任何缓存必有 TTL 兜底)+ 由外向内引入路线(升级触发即 ADR;负缓存/jitter/singleflight 随第一个缓存点同车)。
• E 秘密接触面纪律(分离·注入·deny·金丝雀) → references/secrets-discipline.md —— 值/元数据物理分离(说明文档只留名字+gotcha,值进 gitignored env 文件)+ 注入形态唯一(set -a; source; set +a,值不落 stdout/argv/transcript)+ deny 一刀切(防失手不冒充沙箱)+ 金丝雀纪律 MUST(防护面用假数据全矩阵验证,全绿才许真密文进场;settings 重启才加载,先验加载——"拿真值测防护面"本身就是事故)。

关联(独立 skill,不在本 hub 重复)

• 埋点 / telemetry → observability-standard;Git SOP → git-workflow-standard;A2A 对外契约 → A2A 对外契约规范。
• 硬层 CI 门禁 / ruleset / 清扫 bot → 你的 IaC 仓。