Agent 设计 / 伪代码 / 开发部署与使用指南
目的 ：读完能 设计 （控制面/数据面/状态/成本）、开发 （接口与伪代码落地）、部署使用 （环境、拓扑、运维与回滚）。
工业级场景索引 ：checkpoint / resume / 幂等 → 96 §4
RUN_*· 深读索引。与 Playbook 关系 ：机制、checklist、面试题、Grafana 案例见 13-Agent工程实践-生产落地Playbook；本篇是 可交付的工程设计说明（偏「怎么开工」）。
1. 文档范围与读者
| 读者 | 本篇覆盖 |
|---|---|
| 架构师 | 边界、SLO、成本、风险、Cursor SDK vs 自建 |
| 后端工程师 | API、状态存储、幂等、checkpoint、伪代码 |
| SRE / On-call | 部署拓扑、观测、降级、回滚 |
不展开：具体 Grafana/OnCall API 字段、公司内网拓扑（用占位符）。
2. 设计目标（验收口径）
- 任务可完成 ：
success_criteria可机器或人工验收。 - 可续跑 ：崩溃后从 checkpoint 继续，不重复已成功写操作。
- 可审计 ：
trace_id、tool、参数摘要、分类结论、version_pin。 - 成本有界 ：
max_steps/max_cost_usd/ token budget。 - 写操作可控：resolve 等走 policy + HITL（按严重级别）。
3. 总体架构
3.1 控制面 vs 数据面
text
[Webhook / Cron / API] → 控制面 (Policy, 幂等, 预算, HITL)
↓
数据面 (Planner / Executor / Tools / LLM)
↓
状态 (Checkpoint DB, Artifact Store)
↓
观测 (Trace, Metrics, Audit)| 平面 | 职责 | 典型组件 |
|---|---|---|
| 控制面 | 鉴权、租户、policy、幂等、限流、审批 | API Gateway、OPA、内部 BFF |
| 数据面 | plan、tool、LLM、RAG | LangGraph / 自建循环 / @cursor/sdk |
| 状态 | checkpoint、会话、artifact | PostgreSQL （checkpoint）、S3（大结果/报告）、Redis（可选） |
| 观测 | 回放、成本、告警 | Langfuse / 自研 + $/task |
3.2 状态存储（与向量库区分）
| 存储 | 用途 | 是否向量库 | 连接方式（生产） |
|---|---|---|---|
| Checkpoint | goal、plan、completed_steps、version_pin |
否 | PostgreSQL（TCP/内网） |
| Artifact | 大 tool JSON、报告 .md |
否 | S3/OSS（HTTPS） |
| 向量库 | 长期记忆、RAG、相似历史 | 是 | 向量服务 网络 |
| LLM 上下文 | 每轮请求 messages |
--- | 无状态 API：每轮带上本回合需要的 token |
详见 Playbook §3.1.1 、§9.4。
4. 核心数据模型
4.1 TaskCheckpoint（逻辑模型）
text
task_id # 业务任务 ID，如 alert_group_id + firing_generation
trace_id # 分布式追踪
goal # North Star
success_criteria[] # 可验收条件
plan[] # { id, action, deps, verify, status, risk }
completed_steps[] # 已完成 step id
artifacts{} # step_id -> uri / hash
tool_results_digest{} # 每步摘要，非全量 JSON
version_pin{} # prompt, model, tool_schema, kb_index
last_error
wall_time_spent_s
progress_pct4.2 幂等键（写操作）
text
idempotency_key = f"{business_entity}:{operation}:{generation}"
# 禁止用 trace_id 作为写 API 幂等键（重试会变 → 重复写）5. 与 LLM 的交互与成本（摘要）
- 多数 LLM API 无状态 ：每轮在请求体中带 本回合 system + 锚点 + 当前步上下文；不把「整段一小时历史」默认存到模型侧当数据库。
- Checkpoint 存在你们 DB ：resume 只拼 短上下文（goal + completed + digest + 下一步），避免全量 replay。
- Resume 仍有本轮 prefill 费用：省的是「不必为已完成历史再付全量 token」，不是零成本。
- 多 Agent ：只有 总 token ↓、小模型、少重复 system 才省钱；乱拆 + Coordinator 可能更贵。
6. 伪代码：有界 DAG + Checkpoint（通用）
pseudo
function runTask(taskInput):
ck = loadCheckpoint(taskInput.id)
if ck == null:
ck = initCheckpoint(taskInput.goal, taskInput.success_criteria, buildPlan(taskInput))
enforceBudget(ck)
while hasPending(ck.plan):
step = nextPending(ck.plan)
if step.status == DONE:
continue
if not policyAllows(step):
ck = markHitl(ck, step)
saveCheckpoint(ck)
return PAUSED_HITL
observation = executeStep(step) // tools / LLM 子调用
if not verify(step, observation):
if shouldReplan(ck, observation):
ck.plan = replanRemaining(ck) // 不清空 completed_steps
else:
step.status = FAILED
saveCheckpoint(ck)
if fatal(step): return ERROR
step.status = DONE
ck.completed_steps.append(step.id)
ck.tool_results_digest[step.id] = summarize(observation)
saveCheckpoint(ck)
return SUCCESS(finalize(ck))6.1 verify 示例
pseudo
function verify(step, obs):
if step.action == "get_order":
return obs.ok and obs.data.order_id != null
if step.action == "resolve_alert":
return obs.ok and obs.data.oncall_state == "resolved"
return false7. 场景伪代码：告警 Triage（与 Playbook §20 对齐）
pseudo
function triageAlert(alertGroupId, firingGeneration):
if alreadyProcessed(alertGroupId, firingGeneration):
return SKIPPED
ck = loadOrInitCheckpoint(alertGroupId)
meta = grafana.get_alert_group(alertGroupId)
assert verify_s1(meta)
series = grafana.query_prometheus(meta.panel_queries, meta.window)
assert verify_s2(series)
logs = grafana.query_loki(meta.window, meta.service)
assert verify_s3(logs)
cls = applyObservabilitySkill(meta, series, logs) // fp | true_incident | inconclusive
if cls == inconclusive:
oncall.acknowledge(alertGroupId, reason="insufficient_evidence")
return OK
if cls == false_positive:
if confidence(cls) < 0.85: goto inconclusive
if policy.requiresHitl(meta.severity): return PAUSED_HITL
oncall.resolve(alertGroupId, reason=cls.reason_code)
return OK
reportUri = writeArtifact(buildReport(meta, series, logs))
notify(reportUri)
return OK技能对齐 （interview 仓库）：payment-observability、mode-incident-triage。
8. Cursor SDK 使用说明（数据面一种实现）
8.1 依赖
| 项 | 说明 |
|---|---|
@cursor/sdk |
npm 依赖 |
CURSOR_API_KEY |
Dashboard Integrations 或 Team Service Account |
| 出网 | 运行环境能访问 Cursor API |
| Grafana | HTTP MCP 或网关（Cloud Agent 不可用本机 stdio 连 MCP） |
8.2 最小调用形态（概念）
typescript
// 生产需：try/finally dispose、CursorAgentError 分支、policy 前置
await using agent = await Agent.create({
apiKey: process.env.CURSOR_API_KEY!,
model: { id: "composer-2" },
local: { cwd: REPO_ROOT, settingSources: ["project"] },
mcpServers: {
grafana: {
type: "http",
url: process.env.GRAFANA_MCP_URL!,
headers: { Authorization: `Bearer ${process.env.GRAFANA_MCP_TOKEN}` },
},
},
});
const run = await agent.send(buildPromptFromCheckpoint(ck));
await run.wait();8.3 与自建 LangGraph 的分工
| 维度 | Cursor SDK | 自建 |
|---|---|---|
| 运行时 | 绑定 Cursor API | 自选 LLM |
| MCP / 规则 | 快接 IDE 生态 | 自建注册表 |
| 业务 checkpoint | 仍建议自建 Postgres | 自建 Postgres |
9. 部署设计
9.1 推荐拓扑（生产）
text
Internet → Ingress (TLS) → Triage API (K8s Deployment)
├→ PostgreSQL (checkpoint)
├→ Redis (可选：幂等、速率)
├→ S3 (artifact)
└→ Egress → Cursor API / Grafana / OnCall9.2 环境变量（示例名）
| 变量 | 用途 |
|---|---|
CURSOR_API_KEY |
Cursor SDK |
DATABASE_URL |
Postgres |
GRAFANA_MCP_URL / token |
Grafana MCP |
WEBHOOK_HMAC_SECRET |
Webhook 签名校验 |
9.3 健康与 SLO
| 指标 | 建议 |
|---|---|
false_resolve_rate |
0 |
resume_success_rate |
≥ 95% |
checkpoint_lag_s P99 |
< 5s |
$/task |
告警阈值 |
10. 开发流程（本地）
- 克隆含
.cursor/skills的 monorepo；settingSources: ["project"]加载技能。 - 本地 Postgres（Docker）+ migration（
checkpoints表）。 export CURSOR_API_KEY=...；单测 / dry-run（mock Grafana）。- Staging Webhook 小流量；盯
false_resolve_rate。
10.1 本仓库可运行脚手架
| 路径 | 说明 |
|---|---|
tools/grafana-alert-triage-sdk |
npm install + npm run triage / npm run webhook；@cursor/sdk + 内存 checkpoint + 可选 Grafana HTTP MCP |
11. 使用说明（业务 / On-call）
- 触发 ：OnCall POST 到 Triage API（
alert_group_id、firing_generation）。 - 结果 ：
false_positive→ 条件满足时 resolve；true_incident→ 报告链接；inconclusive→ 仅 ack。 - 人工 ：HITL 批准后调用
resume（带approval_id）。
12. 回滚与版本
- 四维版本：prompt、model、tool schema、KB/索引 --- Canary 后再全量。
version_pin与线上一致才可盲续；否则 migrate 或重跑受影响步。
13. 关联导航
| # | 文件 | 职责 |
|---|---|---|
| 13 | 13-Agent工程实践-生产落地Playbook | 12 域 + checklist + §19/§20 |
| 04 | 04-Agent框架 | 框架与模式 |
| 05 | 05-AI-辅助开发 | Cursor / MCP |
| 98 | 98-面试高频题满分答与Checklist.md | 考前速查 |
14. 变更记录
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-05-15 | 初版：设计 + 伪代码 + 部署使用 |
金样加厚 R8（冲480 · batch4） · Agent部署
Staff 深展
| 阶段 | 交付物 |
|---|---|
| 设计 | 工具契约+状态机 |
| 部署 | K8s+HPA+GPU 池 |
| 使用 | Playbook+审批流 |
#mermaid-svg-8uNgGKtIqcHIbsCQ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8uNgGKtIqcHIbsCQ .error-icon{fill:#552222;}#mermaid-svg-8uNgGKtIqcHIbsCQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8uNgGKtIqcHIbsCQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .marker.cross{stroke:#333333;}#mermaid-svg-8uNgGKtIqcHIbsCQ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8uNgGKtIqcHIbsCQ p{margin:0;}#mermaid-svg-8uNgGKtIqcHIbsCQ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster-label text{fill:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster-label span{color:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster-label span p{background-color:transparent;}#mermaid-svg-8uNgGKtIqcHIbsCQ .label text,#mermaid-svg-8uNgGKtIqcHIbsCQ span{fill:#333;color:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .node rect,#mermaid-svg-8uNgGKtIqcHIbsCQ .node circle,#mermaid-svg-8uNgGKtIqcHIbsCQ .node ellipse,#mermaid-svg-8uNgGKtIqcHIbsCQ .node polygon,#mermaid-svg-8uNgGKtIqcHIbsCQ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .rough-node .label text,#mermaid-svg-8uNgGKtIqcHIbsCQ .node .label text,#mermaid-svg-8uNgGKtIqcHIbsCQ .image-shape .label,#mermaid-svg-8uNgGKtIqcHIbsCQ .icon-shape .label{text-anchor:middle;}#mermaid-svg-8uNgGKtIqcHIbsCQ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .rough-node .label,#mermaid-svg-8uNgGKtIqcHIbsCQ .node .label,#mermaid-svg-8uNgGKtIqcHIbsCQ .image-shape .label,#mermaid-svg-8uNgGKtIqcHIbsCQ .icon-shape .label{text-align:center;}#mermaid-svg-8uNgGKtIqcHIbsCQ .node.clickable{cursor:pointer;}#mermaid-svg-8uNgGKtIqcHIbsCQ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .arrowheadPath{fill:#333333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8uNgGKtIqcHIbsCQ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-8uNgGKtIqcHIbsCQ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8uNgGKtIqcHIbsCQ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster text{fill:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ .cluster span{color:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-8uNgGKtIqcHIbsCQ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-8uNgGKtIqcHIbsCQ rect.text{fill:none;stroke-width:0;}#mermaid-svg-8uNgGKtIqcHIbsCQ .icon-shape,#mermaid-svg-8uNgGKtIqcHIbsCQ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8uNgGKtIqcHIbsCQ .icon-shape p,#mermaid-svg-8uNgGKtIqcHIbsCQ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-8uNgGKtIqcHIbsCQ .icon-shape .label rect,#mermaid-svg-8uNgGKtIqcHIbsCQ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8uNgGKtIqcHIbsCQ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-8uNgGKtIqcHIbsCQ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-8uNgGKtIqcHIbsCQ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 开发
Staging eval
Prod 灰度
Trace+Cost
大厂追问 C01--C08
C01 · 核心机制 60s？
见上表；先问题域再机制
C02 · AI 工程落地？
指标+门禁+可回滚
C03 · 失败模式？
见风险表 2 条
C04 · 监控？
SLI/SLO + 业务码 + 延迟
风险表
| 风险 | 信号 | 缓解 |
|---|---|---|
| 一致性 | 重复消费/丢事件 | 幂等键+Outbox+对账 |
| 组织 | 扯皮 | RACI+Runbook |
| 成本 | 账单飙升 | 预算+归因 |
STAR-M-P
| S | 大促/支付峰值事故或组织扩张 |
| T | 48h 恢复 SLO 或完成决策 |
| A | 定位→止血→复盘→制度 |
| R | 指标/成本/士气恢复 |
| M | MTTR <1h 或 ROI >X% |
| P | 模板进 wiki/CI |
45min 白板
- 0--5：NFR
- 5--20：架构图
- 20--35：关键路径
- 35--45：风险+监控
Checklist
- C01--C08 口述各 30s
- STAR 60s
官方文档与源码（一级依据）
AI Engineering · 正文机制应来自下方 官方文档（L1） 与 官方源码仓库（L2） ；
禁止用教程站/博客充当机制依据。本章 QPS/延迟/STAR 为面试示意。
L1 · 官方文档
L2 · 官方源码
L3 · 论文 / 开放规范