Agent 设计 / 伪代码 / 开发部署与使用指南

贺国亚2026-06-02 15:43

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. 设计目标（验收口径）

  1. 任务可完成 ：success_criteria 可机器或人工验收。
  2. 可续跑 ：崩溃后从 checkpoint 继续，不重复已成功写操作。
  3. 可审计 ：trace_id、tool、参数摘要、分类结论、version_pin。
  4. 成本有界 ：max_steps / max_cost_usd / token budget。
  5. 写操作可控：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_pct

4.2 幂等键（写操作）

text 复制代码 
idempotency_key = f"{business_entity}:{operation}:{generation}"
# 禁止用 trace_id 作为写 API 幂等键（重试会变 → 重复写）

5. 与 LLM 的交互与成本（摘要）

  1. 多数 LLM API 无状态 ：每轮在请求体中带 本回合 system + 锚点 + 当前步上下文；不把「整段一小时历史」默认存到模型侧当数据库。
  2. Checkpoint 存在你们 DB ：resume 只拼 短上下文（goal + completed + digest + 下一步），避免全量 replay。
  3. Resume 仍有本轮 prefill 费用：省的是「不必为已完成历史再付全量 token」，不是零成本。
  4. 多 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 false

7. 场景伪代码：告警 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 / OnCall

9.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. 开发流程（本地）

  1. 克隆含 .cursor/skills 的 monorepo；settingSources: ["project"] 加载技能。
  2. 本地 Postgres（Docker）+ migration（checkpoints 表）。
  3. export CURSOR_API_KEY=...；单测 / dry-run（mock Grafana）。
  4. 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）

  1. 触发 ：OnCall POST 到 Triage API（alert_group_id、firing_generation）。
  2. 结果 ：false_positive → 条件满足时 resolve；true_incident → 报告链接；inconclusive → 仅 ack。
  3. 人工 ：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 为面试示意。

写作规范：docs/official-sources-registry.md §0

L1 · 官方文档

L2 · 官方源码

L3 · 论文 / 开放规范

相关推荐
码农小白AI1 小时前
AI报告审核与IACheck：自动化检测全面铺开后，为什么报告审核反而成了新的效率瓶颈？
大数据·人工智能·自动化
土拨鼠烧电路1 小时前
第7章：新主宰——世界坍缩为对话框
人工智能
数智顾问1 小时前
（133页PPT）数据中心基础设施规划设计（附下载方式）
大数据·数据库·人工智能
2601_957190901 小时前
原厂稳交付，玻璃剧场打造文旅长效增收新业态
大数据·人工智能
学术头条1 小时前
手机上跑MoE？Meta提出MobileMoE，iPhone 16 Pro提速3.8倍
人工智能·科技·机器学习·ai·智能手机·agi
aihuangwu1 小时前
AI导出鸭｜ChatGPT与Gemini生成Word文档技术实操
人工智能·ai·chatgpt·word·deepseek·ai导出鸭
lauo1 小时前
AI PC革命浪潮之巅，ibbot手机：握在掌中的未来“超脑节点”
人工智能·智能手机
winlife_1 小时前
让 AI 跑通“调跳跃手感“的完整闭环：funplay-unity-mcp 实战案例
人工智能·unity·游戏引擎·ai编程·mcp·游戏手感
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03【AI】2026 年具身智能模型和世界模型总结04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05Codex 下载安装指南：Windows 和 macOS 官方版下载06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07CC-Switch & Claude 基于 Linux 服务器安装使用指南08Codex 接入 DeepSeek API 完整配置文档09几个好用的ip纯净度检测网站10CC-Switch 下载、安装与使用配置指南【2026.5.29】