企业官网建设流程全解析

1. 项目概述：什么是 agent-native？它不是又一个“AI Agent 框架”噱头

“agent-native”这个词最近在 GitHub Trending 和 TypeScript 社区讨论里频繁出现，但它不是某个具体开源库的名字，而是一种正在成型的系统设计范式——就像当年“cloud-native”从模糊概念演变为 Kubernetes、Service Mesh、Serverless 等一整套工程实践一样，“agent-native”正悄然定义下一代智能应用的底层结构逻辑。我从去年开始在三个实际交付项目中落地这类架构（一个金融风控决策引擎、一个工业设备远程诊断平台、一个政务知识协同助手），发现它和市面上绝大多数打着“Agent”旗号的 demo 工具链有本质区别：它不把 Agent 当作一个可插拔的“能力模块”，而是把整个系统从数据库 schema、API 协议、状态管理到错误恢复机制，全部围绕“Agent 的行为语义”重新建模。

核心关键词里，“TypeScript”不是凑数——它是整个范式得以成立的类型基石；“PostgreSQL”也不是随便选的数据库——它的 JSONB、行级安全（RLS）、物化视图、逻辑复制能力，恰好能承载 Agent 行为所需的强一致性状态与可审计动作日志；而“actions”这个词，在这里特指Temporal Logic of Actions（TLA）风格的、带明确前置条件（precondition）与后置效应（effect）声明的动作单元，不是 RESTful API 那种无状态请求，也不是简单函数调用。你能在热词里看到大量“typescript面试”“postgresql安装”“framework”混杂其中，恰恰说明这个范式正在从极客实验走向工程落地——它要求开发者同时精通类型系统建模、关系型数据库深度能力、以及形式化动作语义表达，缺一不可。

适合谁来深入？不是只想跑通 LangChain Demo 的初学者，而是已经用过 Next.js + Prisma 做过中等复杂度业务系统、对 PostgreSQL 的 CTE 递归查询或 pg_cron 定时任务有实操经验、并且被“LLM 调用链路太脆弱”“Agent 决策过程无法回溯”“多步任务失败后状态不一致”等问题反复折磨过的中级以上工程师。如果你还在纠结“该选 LlamaIndex 还是 LangChain”，那现在还不是切入 agent-native 的时机；但如果你已经开始手写 retry 逻辑、手动维护 action 执行上下文、为每个 LLM 调用加唯一 trace_id 并存入数据库，那你已经站在了这个范式的门口。

2. 设计哲学拆解：为什么必须抛弃“Agent as Service”的旧思路？

2.1 传统 Agent 架构的三大结构性缺陷

我先说结论：当前 90% 的 Agent 应用都卡在“服务化封装”这一层，导致系统像纸糊的房子——表面功能丰富，一碰就散。问题出在三个根子上：

第一，状态割裂。典型做法是：LLM 输出 JSON → 后端解析 → 调用不同微服务 → 拼装结果返回。但 Agent 的真实状态（比如“用户正在申请贷款，已提交收入证明，等待风控模型评估”）既不在 LLM 的 context 里（会丢），也不在微服务各自的数据库里（分散且无关联）。我们曾有个客户项目，用户中断操作后想继续，系统根本无法还原当时所处的决策节点，只能让用户重头开始。这不是 Bug，是架构缺陷。

第二，动作语义丢失。所谓“actions”，在多数框架里只是字符串命令（如 "send_email"、"query_db"），没有声明其前置条件（例如“send_email”要求 recipient 字段非空且格式合法、email_template_id 必须存在于模板表中）和后置效应（例如“send_email”成功后，必须将发送记录写入 audit_log 表，并更新 user 表的 last_email_sent_at 字段）。没有这些声明，你就无法做静态校验、无法生成可靠的状态迁移图、更无法实现原子性回滚——当第 3 步失败时，前两步的副作用可能已污染数据。

第三，可观测性断层。Trace ID 只能串起 HTTP 请求链路，但 Agent 的关键决策点（比如“因信用分低于阈值，拒绝触发放款流程”）发生在 LLM 的推理过程中，既不落库也不留痕。运维同学查日志时看到的是“/api/execute 返回 500”，却不知道是 prompt 写错了、还是数据库连接超时、抑或是 LLM 误判了规则。这种黑盒，让稳定性保障变成玄学。

2.2 agent-native 的破局点：以 PostgreSQL 为“行为事实中心”

agent-native 的核心反转在于：把 PostgreSQL 从“数据存储”升级为“行为事实中心（Behavioral Fact Center）”。这听起来很激进，但实操中非常自然。我们不再把数据库当作被动接收 CRUD 的仓库，而是主动设计一套围绕 Agent 动作的 schema：

• actions表：存储所有预定义动作的元信息，包括 name（唯一标识）、precondition_sql（验证前置条件的 SQL 片段）、effect_sql（执行后置效应的 SQL 片段）、timeout_ms（最大执行时间）、retry_policy（重试策略 JSON）。
• action_executions表：记录每次动作执行的完整生命周期，包含 action_name、input_params（JSONB）、status（'pending'/'running'/'success'/'failed'/'cancelled'）、output_result（JSONB）、error_message、started_at、finished_at、trace_id。
• agent_states表：按 agent_id 分区，存储 Agent 当前状态快照，使用 JSONB 存储结构化状态（如 { "step": "credit_assessment", "user_id": "u123", "context": { "income_proof_submitted": true } }），并配合 RLS 实现租户隔离。
• state_transitions表：记录状态变更日志，包含 from_state_hash、to_state_hash、triggered_by_action、transition_time，用于构建可回溯的状态机。

提示：这里的关键不是“用 PostgreSQL 存 JSONB”，而是用 PostgreSQL 的强一致性事务保证动作的原子性。比如一个“审批贷款”动作，其 effect_sql 可能包含三句 SQL：1) 更新 loan_applications 表状态；2) 插入一条 approval_record；3) 更新 users 表的 credit_score。这三句必须在一个事务里完成，否则整个动作视为失败。这是任何 NoSQL 或消息队列都无法替代的确定性保障。

2.3 TypeScript 的角色：从“类型检查器”升维为“行为契约编译器”

TypeScript 在此范式中承担的角色远超语法糖。我们定义了一套 DSL（Domain Specific Language），用 TypeScript 接口描述动作契约：

// actions/loan-approval.ts export interface LoanApprovalAction { name: 'loan-approval'; input: { application_id: string; approver_id: string; }; precondition: (ctx: ActionContext) => Promise<boolean>; // 返回 false 则拒绝执行 effect: (ctx: ActionContext, input: this['input']) => Promise<void>; // 执行核心逻辑 rollback?: (ctx: ActionContext, input: this['input']) => Promise<void>; // 可选回滚逻辑 } // 自动生成对应的 PostgreSQL schema 和 validation SQL // 例如 precondition 会被编译为： // SELECT COUNT(*) > 0 FROM loan_applications WHERE id = $1 AND status = 'submitted'

这套 DSL 编译后，会自动生成：

• actions表的插入语句（含 precondition_sql 和 effect_sql 字段）
• 对应的 Prisma Client 类型定义（确保前端调用时参数类型严格匹配）
• PostgREST 规则（自动为每个 action 生成 RLS 策略）
• OpenAPI spec 中的/actions/{name}/validate端点（供前端实时校验）

注意：这不是代码生成工具的炫技，而是把开发者的意图（“这个动作需要先检查申请状态”）直接映射为数据库层面的约束。当业务规则变更时，你改的是一行 TypeScript 接口定义，而不是去翻查分散在各处的 SQL 文件、Prisma schema、API 文档——所有下游产物自动同步。我们团队实测，规则变更平均耗时从 45 分钟缩短到 3 分钟。

3. 核心实现细节：如何用 PostgreSQL + TypeScript 构建 agent-native 基础设施

3.1 数据库 Schema 设计：超越 CRUD 的动作优先建模

我们不从“实体”（Entity）出发建模，而是从“动作”（Action）出发。以下是生产环境验证过的最小可行 schema（精简版，已移除审计字段）：

-- 动作元数据表：所有预定义动作的“宪法” CREATE TABLE actions ( id SERIAL PRIMARY KEY, name TEXT UNIQUE NOT NULL CHECK (name ~ '^[a-z0-9_-]+$'), -- 强制小写命名规范 description TEXT, precondition_sql TEXT NOT NULL, -- 验证前置条件的 SQL，返回 boolean effect_sql TEXT NOT NULL, -- 执行后置效应的 SQL，无返回值 timeout_ms INTEGER DEFAULT 30000 CHECK (timeout_ms BETWEEN 100 AND 300000), created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() ); -- 动作执行记录表：每一次动作调用的“司法档案” CREATE TABLE action_executions ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), action_name TEXT NOT NULL REFERENCES actions(name), input_params JSONB NOT NULL, status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'success', 'failed', 'cancelled')), output_result JSONB, error_message TEXT, started_at TIMESTAMPTZ, finished_at TIMESTAMPTZ, trace_id TEXT, created_at TIMESTAMPTZ DEFAULT NOW() ); -- Agent 状态表：每个 Agent 实例的“当前快照” CREATE TABLE agent_states ( agent_id TEXT PRIMARY KEY, state_data JSONB NOT NULL, version INTEGER NOT NULL DEFAULT 1, -- 乐观锁版本号 updated_at TIMESTAMPTZ DEFAULT NOW() ); -- 状态迁移日志表：记录每一次状态变更的“历史账本” CREATE TABLE state_transitions ( id SERIAL PRIMARY KEY, agent_id TEXT NOT NULL, from_state_hash TEXT, -- SHA256(state_data) to_state_hash TEXT NOT NULL, triggered_by_action TEXT NOT NULL, transition_time TIMESTAMPTZ DEFAULT NOW(), input_params JSONB );

关键设计点解析：

• precondition_sql字段的妙用：它不是普通文本，而是经过严格沙箱校验的 SQL 片段。我们在应用层注入时，会做三重过滤：1) 禁止INSERT/UPDATE/DELETE语句；2) 限制SELECT只能查询特定视图（如v_valid_applications）；3) 自动包裹为SELECT EXISTS(...)形式，确保返回布尔值。这样，前端在调用动作前，可先发POST /actions/loan-approval/validate，后端执行此 SQL 并返回true/false，用户界面据此禁用/启用按钮——把业务规则校验从客户端 JS 移到数据库，杜绝绕过风险。

• action_executions的 status 状态机：我们刻意避免使用ENUM类型，因为状态流转逻辑复杂（如failed后可能触发retry，running中可能被cancel）。实际采用字符串枚举 + 应用层状态转换函数控制。started_at和finished_at的存在，让我们能精确计算每个动作的 P95 延迟，进而优化 timeout_ms 设置——比如发现send_notification平均耗时 800ms，就把 timeout_ms 从默认 30s 改为 2s，快速失败，避免阻塞整个 Agent 流程。

• agent_states的乐观锁设计：version字段是关键。当 Agent 执行一个动作时，流程是：1)SELECT state_data, version FROM agent_states WHERE agent_id = $1; 2) 应用层计算新 state; 3)UPDATE agent_states SET state_data = $2, version = version + 1 WHERE agent_id = $1 AND version = $3。如果WHERE条件不匹配（即 version 已被其他并发动作更新），则本次更新失败，触发重试或报错。这比悲观锁（SELECT ... FOR UPDATE）更轻量，且天然支持分布式部署——多个服务实例可安全并发操作同一 Agent。

3.2 TypeScript DSL 编译器：让接口定义驱动全栈

我们开发了一个轻量级 CLI 工具agent-native-cli，它读取src/actions/*.ts文件，执行以下编译流程：

1. AST 解析：用 TypeScript Compiler API 解析每个文件，提取interface XxxAction的name、input、precondition函数体、effect函数体。
2. SQL 生成：
   • precondition函数体被重写为纯 SQL：ctx.db.query('SELECT ...')转为SELECT ...；input.application_id转为$1绑定参数；ctx.env.TENANT_ID转为current_setting('app.tenant_id')。
   • effect函数体同理，但允许包含多个INSERT/UPDATE/DELETE语句，自动包裹在BEGIN ... EXCEPTION WHEN OTHERS THEN ... END块中，确保事务性。
3. Prisma Schema 注入：生成prisma/schema.prisma的扩展片段，为每个 action 添加Model（如model LoanApprovalAction {...}），并配置@map("actions")映射到主表。
4. OpenAPI Spec 生成：为每个 action 创建/actions/{name}/validate和/actions/{name}/execute两个 endpoint，input接口自动转为 OpenAPIrequestBody。

一个真实案例：credit-score-update.ts动作

export interface CreditScoreUpdateAction { name: 'credit-score-update'; input: { user_id: string; delta: number; // 信用分增减值 }; precondition: (ctx: ActionContext) => Promise<boolean> => { return ctx.db.query( `SELECT COUNT(*) > 0 FROM users WHERE id = $1 AND status = 'active'`, [input.user_id] ); }; effect: (ctx: ActionContext, input: this['input']) => Promise<void> => { await ctx.db.query( `UPDATE users SET credit_score = credit_score + $1, updated_at = NOW() WHERE id = $2`, [input.delta, input.user_id] ); await ctx.db.query( `INSERT INTO credit_score_logs (user_id, delta, reason) VALUES ($1, $2, 'agent_action')`, [input.user_id, input.delta] ); }; }

编译后，自动生成：

• actions表插入语句（含precondition_sql和effect_sql）
• Prisma Client 中的prisma.actions.create({ data: { name: 'credit-score-update', ... } })
• OpenAPI 中的/actions/credit-score-update/validate端点，接受{"user_id":"u123","delta":10}

实操心得：我们最初尝试用 Zod 生成运行时校验，但发现性能瓶颈（每次调用都要 parse+validate JSON）。改为编译期生成 SQL 校验后，延迟从平均 12ms 降到 0.8ms。真正的性能优化，往往始于架构选择，而非代码微调。

3.3 Agent 运行时：基于 PostgreSQL LISTEN/NOTIFY 的轻量事件驱动

agent-native 不依赖 Kafka 或 RabbitMQ 这类重量级消息中间件。我们利用 PostgreSQL 原生的LISTEN/NOTIFY机制构建事件总线：

• 当action_executions表插入一条新记录（status = 'pending'）时，触发AFTER INSERT触发器：

  CREATE OR REPLACE FUNCTION notify_action_pending() RETURNS TRIGGER AS $$ BEGIN PERFORM pg_notify('action_queue', json_build_object( 'id', NEW.id, 'action_name', NEW.action_name, 'input_params', NEW.input_params )::text); RETURN NEW; END; $$ LANGUAGE plpgsql; CREATE TRIGGER trigger_action_pending AFTER INSERT ON action_executions FOR EACH ROW WHEN (NEW.status = 'pending') EXECUTE FUNCTION notify_action_pending();

• Node.js 运行时（用pg库）启动时执行LISTEN action_queue，收到通知后：

  1. UPDATE action_executions SET status = 'running' WHERE id = $1
  2. 执行对应动作的effect_sql（通过pg的query方法）
  3. 根据结果UPDATE action_executions SET status = 'success'/...

优势非常明显：

• 零外部依赖：无需部署和维护额外中间件，降低运维复杂度。
• 强一致性：通知与数据库变更在同一事务内，不会出现“通知发了但 DB 更新失败”的情况。
• 天然去重：pg_notify是异步的，但运行时消费时会先SELECT FOR UPDATE SKIP LOCKED，避免多个 worker 处理同一任务。

我们线上集群用 3 个 Node.js 进程监听同一个 channel，QPS 稳定在 1200+，CPU 占用率低于 15%。对比之前用 Redis Stream 的方案，资源消耗下降 60%，且故障率归零——因为少了一个可能挂掉的组件。

4. 实操全流程：从零搭建一个贷款审批 Agent

4.1 环境准备与依赖安装

我们假设你已具备基础 Linux 服务器（Ubuntu 22.04）和 Node.js 18+ 环境。整个搭建过程控制在 15 分钟内，所有命令均可复制粘贴：

# 1. 安装 PostgreSQL 15（官方源，非 apt 默认的 12） sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - sudo apt-get update sudo apt-get install -y postgresql-15 postgresql-client-15 postgresql-contrib-15 # 2. 初始化数据库（创建专用用户和库） sudo -u postgres psql -c "CREATE DATABASE agent_native;" sudo -u postgres psql -c "CREATE USER agent_user WITH PASSWORD 'StrongPass123!';" sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE agent_native TO agent_user;" # 3. 安装 Node.js 18（使用 nvm 更稳妥） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18 # 4. 创建项目骨架 mkdir loan-agent && cd loan-agent npm init -y npm install typescript ts-node @prisma/client pg dotenv npm install -D prisma @types/node npx prisma init

注意：PostgreSQL 15 是硬性要求，因为pg_notify的 payload 大小限制在 8KB，而 14 及以下版本对此支持不完善。不要图省事用apt install postgresql，那会装 12 版本，后续LISTEN/NOTIFY可能静默失败。

4.2 初始化 Prisma Schema 与数据库迁移

编辑prisma/schema.prisma，填入 agent-native 核心表：

generator client { provider = "prisma-client-js" } datasource db { provider = "postgresql" url = env("DATABASE_URL") } model Action { id Int @id @default(autoincrement()) name String @unique description String? precondition_sql String @db.VarChar(4000) effect_sql String @db.VarChar(4000) timeout_ms Int @default(30000) created_at DateTime @default(now()) updated_at DateTime @updatedAt } model ActionExecution { id String @id @default(cuid()) action_name String input_params Json status String @default("pending") @db.VarChar(20) output_result Json? error_message String? started_at DateTime? finished_at DateTime? trace_id String? created_at DateTime @default(now()) action Action @relation(fields: [action_name], references: [name]) } model AgentState { agent_id String @id state_data Json version Int @default(1) updated_at DateTime @updatedAt } model StateTransition { id Int @id @default(autoincrement()) agent_id String from_state_hash String? to_state_hash String triggered_by_action String transition_time DateTime @default(now()) input_params Json }

然后执行迁移：

# 设置数据库连接 URL echo "DATABASE_URL=\"postgresql://agent_user:StrongPass123!@localhost:5432/agent_native\"" > .env # 生成 Prisma Client npx prisma generate # 执行迁移（创建表） npx prisma migrate dev --name init --create-only npx prisma migrate deploy

4.3 定义第一个 Agent 动作：贷款申请提交

在src/actions/loan-application-submit.ts中编写：

import { PrismaClient } from '@prisma/client'; export interface LoanApplicationSubmitAction { name: 'loan-application-submit'; input: { user_id: string; amount: number; purpose: string; }; precondition: (ctx: ActionContext) => Promise<boolean>; effect: (ctx: ActionContext, input: this['input']) => Promise<void>; } // Precondition: 用户必须存在且状态为 active export const precondition = async (ctx: ActionContext): Promise<boolean> => { const result = await ctx.db.$queryRaw` SELECT COUNT(*) > 0 as exists FROM users WHERE id = ${ctx.input.user_id} AND status = 'active' `; return result[0].exists; }; // Effect: 创建申请记录，并初始化 Agent 状态 export const effect = async (ctx: ActionContext, input: LoanApplicationSubmitAction['input']): Promise<void> => { const prisma = ctx.db; // 1. 创建贷款申请 const application = await prisma.loanApplication.create({ data: { userId: input.user_id, amount: input.amount, purpose: input.purpose, status: 'submitted', createdAt: new Date(), } }); // 2. 初始化 Agent 状态 await prisma.agentState.upsert({ where: { agent_id: `loan-${application.id}` }, create: { agent_id: `loan-${application.id}`, state_data: { step: 'document_upload', application_id: application.id, user_id: input.user_id, context: { amount: input.amount, purpose: input.purpose } }, version: 1 }, update: { state_data: { step: 'document_upload', application_id: application.id, user_id: input.user_id, context: { amount: input.amount, purpose: input.purpose } }, version: { increment: 1 } } }); // 3. 记录状态迁移 await prisma.stateTransition.create({ data: { agent_id: `loan-${application.id}`, to_state_hash: 'sha256_of_initial_state', triggered_by_action: 'loan-application-submit', input_params: input } }); };

4.4 构建 Agent 运行时：监听、执行、反馈闭环

创建src/runtime/agent-runner.ts：

import { Client } from 'pg'; import { PrismaClient } from '@prisma/client'; const client = new Client({ connectionString: process.env.DATABASE_URL, }); let isRunning = false; // 监听 action_queue channel async function listenForActions() { await client.connect(); await client.query('LISTEN action_queue'); client.on('notification', async (msg) => { if (isRunning) return; // 防止并发 isRunning = true; try { const payload = JSON.parse(msg.payload); const executionId = payload.id; // 1. 标记为 running await client.query( `UPDATE action_executions SET status = 'running', started_at = NOW() WHERE id = $1`, [executionId] ); // 2. 获取动作定义 const action = await client.query( `SELECT * FROM actions WHERE name = $1`, [payload.action_name] ); // 3. 执行 effect_sql（此处简化，实际需参数化） await client.query(action.rows[0].effect_sql, Object.values(payload.input_params)); // 4. 标记为 success await client.query( `UPDATE action_executions SET status = 'success', finished_at = NOW(), output_result = $1 WHERE id = $2`, [JSON.stringify({ result: 'ok' }), executionId] ); } catch (error) { // 5. 标记为 failed await client.query( `UPDATE action_executions SET status = 'failed', finished_at = NOW(), error_message = $1 WHERE id = $2`, [error.message, payload.id] ); } finally { isRunning = false; } }); } // 启动监听 listenForActions(); console.log('Agent runner started, listening on action_queue...');

最后，创建一个简单的 HTTP 接口来触发动作（src/server.ts）：

import express from 'express'; import { PrismaClient } from '@prisma/client'; import { LoanApplicationSubmitAction, precondition, effect } from './actions/loan-application-submit'; const app = express(); const prisma = new PrismaClient(); app.use(express.json()); app.post('/api/submit-loan', async (req, res) => { const { user_id, amount, purpose } = req.body; // 1. 验证前置条件（调用 precondition） const isValid = await precondition({ db: prisma, input: { user_id, amount, purpose } }); if (!isValid) { return res.status(400).json({ error: 'User not found or inactive' }); } // 2. 创建执行记录 const execution = await prisma.actionExecution.create({ data: { action_name: 'loan-application-submit', input_params: { user_id, amount, purpose }, status: 'pending', trace_id: `trace_${Date.now()}` } }); // 3. 返回执行 ID，供前端轮询 res.json({ execution_id: execution.id, status: 'pending' }); }); app.listen(3000, () => { console.log('Server running on http://localhost:3000'); });

启动服务：

npx ts-node src/server.ts # 在另一个终端，启动 runner npx ts-node src/runtime/agent-runner.ts

现在，用 curl 测试：

curl -X POST http://localhost:3000/api/submit-loan \ -H "Content-Type: application/json" \ -d '{"user_id":"u123","amount":50000,"purpose":"home_renovation"}'

你会看到action_executions表中新增一条pending记录，几秒后变为success，同时agent_states表中出现loan-1的初始状态。整个流程，没有一行代码涉及 LLM 调用，但已具备 Agent 的核心骨架：状态可追踪、动作可审计、失败可回溯。

5. 常见问题排查与独家避坑指南

5.1 PostgreSQL 相关高频问题速查表

5.2 TypeScript 编译与类型安全陷阱

• 陷阱：input类型在 runtime 与 compile time 不一致
  常见于从req.body直接解构赋值，如const { user_id, amount } = req.body。TypeScript 编译时认为user_id是string，但 runtime 可能是number（前端传错类型）或undefined（字段缺失）。解决方案：永远用 Zod 或 io-ts 做 runtime 校验，哪怕只有一行：

  import { z } from 'zod'; const LoanInputSchema = z.object({ user_id: z.string(), amount: z.number() }); const parsed = LoanInputSchema.safeParse(req.body); if (!parsed.success) throw new Error('Invalid input');

• 陷阱：effect_sql中的参数绑定顺序错乱
  当effect_sql包含多个$1,$2时，若input_params是对象而非数组，pg.query(sql, obj)会按字母序绑定，导致amount绑定到$1、user_id绑定到$2，与 SQL 预期相反。解决方案：强制使用数组绑定，并在 DSL 编译器中生成[input.amount, input.user_id]形式。

• 陷阱：prisma的upsert在高并发下 version 冲突
  agent_states的乐观锁在 QPS > 200 时，冲突率飙升。解决方案：改用UPDATE ... RETURNING语句，在 SQL 层面处理 version 递增：

  UPDATE agent_states SET state_data = $1, version = version + 1 WHERE agent_id = $2 AND version = $3 RETURNING version;

  如果RETURNING为空，则说明 version 不匹配，需重试。

5.3 Agent 行为逻辑调试技巧

• 技巧一：用pg_stat_statements定位慢动作
  在 PostgreSQL 中启用扩展：CREATE EXTENSION pg_stat_statements;，然后查询：

  SELECT query, total_time, calls, mean_time FROM pg_stat_statements WHERE query LIKE '%effect_sql%' ORDER BY mean_time DESC LIMIT 5;

  这能立刻告诉你哪个动作的 SQL 最慢，比在应用层埋点高效十倍。

• 技巧二：为每个action_execution生成可追溯的trace_id
  不要用uuidv4()，而用trace_id = 'agent-' + Date.now() + '-' + Math.random().toString(36).substr(2, 9)。这样在日志中搜索agent-1717021234就能捞出整个时间窗口的所有相关记录，比随机字符串好追踪得多。

• 技巧三：state_transitions表的哈希计算
  不要真用SHA256(state_data)，因为 JSONB 的字段顺序不固定，导致相同内容哈希不同。解决方案：用md5(jsonb_sort(state_data)::text)，其中jsonb_sort是一个自定义 PostgreSQL 函数（网上可搜到），它对 JSONB 键值对排序后再转 text。

最后分享一个血泪教训：我们曾在线上环境把action_executions表的input_params字段设为JSON类型（非JSONB），结果当输入参数超过 1MB 时，PostgreSQL 的JSON类型解析耗时高达 2.3 秒，拖垮整个 Agent 流程。改成JSONB后，同样数据解析仅需 12ms。永远用 JSONB，除非你有不可抗力的理由。