// 正确：包含 tenant_id 前缀
const sessionKey = `${tenantSlug}:session:${sessionId}`;
const circuitKey = `${tenantSlug}:circuit-breaker:anthropic-api`;
const rateLimitKey = `${tenantSlug}:rate-limit:${userId}`;
 
// 错误：没有 tenant_id 前缀
const sessionKey = `session:${sessionId}`;        // 迁移 Cluster 时要改代码
const circuitKey = `circuit-breaker:anthropic`;   // 多租户数据混在一起

# 启动 3 个 Temporal Worker 进程，模拟生产的多 Pod 部署
node dist/worker/temporal.js --worker-id=1 &
node dist/worker/temporal.js --worker-id=2 &
node dist/worker/temporal.js --worker-id=3 &
 
# 或用 npm 脚本并行启动
npm run worker:start -- --concurrency=3

// 错误：内存变量，两个 Pod 各自维护自己的计数
let failureCount = 0;  // Pod A 看到 3 次失败，Pod B 看到 2 次
                        // 熔断阈值 5 永远触发不了
 
// 正确：Redis 原子计数器，所有 Pod 共享状态
const key = `${tenantSlug}:circuit-breaker:anthropic-api:failures`;
const count = await redis.incr(key);
await redis.expire(key, WINDOW_SECONDS);
if (count >= FAILURE_THRESHOLD) {
  await redis.set(`${tenantSlug}:circuit-breaker:anthropic-api:state`, 'open');
}

postgres:
  image: pgvector/pgvector:pg14
  environment:
    POSTGRES_USER: agentflow
    POSTGRES_PASSWORD: agentflow_dev_password
    POSTGRES_DB: agentflow
  volumes:
    - postgres_data:/var/lib/postgresql/data
    - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

redis:
  image: redis:7-alpine
  command: >
    redis-server
    --appendonly yes
    --appendfsync everysec
    --maxmemory 512mb
    --maxmemory-policy allkeys-lru

temporal:
  image: temporalio/auto-setup:1.24
  environment:
    - DB=postgres12
    - POSTGRES_USER=agentflow
    - POSTGRES_PWD=agentflow_dev_password
    - POSTGRES_SEEDS=postgres
  ports:
    - '7233:7233'   # gRPC，Temporal SDK 连接此端口

langfuse-web:
  image: langfuse/langfuse:2
  ports:
    - '3000:3000'
  environment:
    - DATABASE_URL=postgresql://agentflow:agentflow_dev_password@postgres:5432/langfuse
    - NEXTAUTH_SECRET=langfuse_nextauth_secret_dev_only_change_in_prod
    - SALT=langfuse_salt_dev_only_change_in_prod
 
langfuse-worker:
  image: langfuse/langfuse-worker:2
  environment:
    - DATABASE_URL=postgresql://agentflow:agentflow_dev_password@postgres:5432/langfuse
    - SALT=langfuse_salt_dev_only_change_in_prod

# 启动所有服务（后台模式）
cd examples
docker compose up -d
 
# 查看服务状态，等所有服务变成 healthy/running
docker compose ps
 
# 验证 PostgreSQL：能看到 tenants 表和三条测试数据
docker exec agentflow-postgres \
  psql -U agentflow -d agentflow \
  -c 'SELECT slug, name FROM tenants;'
 
# 验证 Redis：返回 PONG
docker exec agentflow-redis redis-cli ping
 
# 验证 Temporal：返回 "temporal-system" namespace 信息
docker exec agentflow-temporal \
  temporal operator namespace describe --namespace temporal-system --address localhost:7233
 
# 验证 Langfuse：返回 {"status":"OK"}
curl -s http://localhost:3000/api/public/health

agentflow/
├── package.json              # 根 package.json，定义 workspaces
├── turbo.json                # Turborepo 构建缓存配置
├── tsconfig.base.json        # 全局 TypeScript 基础配置
│
├── packages/                 # 可复用的功能包
│   ├── shared/               # 共享类型定义、工具函数（第1章建立）
│   │   └── src/
│   │       ├── types.ts      # 核心领域类型：Tenant、Session、Message
│   │       └── errors.ts     # 统一错误类型
│   │
│   ├── agent-engine/         # Mastra + LangGraph agent 核心（第3章）
│   │   └── src/
│   │       ├── mastra.ts     # Mastra 实例初始化
│   │       ├── agents/       # 各场景 agent 定义
│   │       └── tools/        # agent 可调用的 tool 定义
│   │
│   ├── llm-gateway/          # LLM 路由、缓存、降级（第4章）
│   │   └── src/
│   │       ├── router.ts     # 多 provider 路由逻辑
│   │       ├── cache.ts      # 语义缓存（Redis + pgvector）
│   │       └── circuit.ts    # 熔断器（状态存 Redis）
│   │
│   ├── skill-system/         # Skill 注册表和 V8 沙箱（第5章）
│   │   └── src/
│   │       ├── registry.ts   # Skill 注册和发现
│   │       └── sandbox.ts    # isolated-vm 沙箱执行
│   │
│   ├── knowledge-base/       # RAG 流水线（第6章）
│   │   └── src/
│   │       ├── ingest.ts     # 文档解析和 chunk 切分
│   │       ├── embed.ts      # 向量嵌入（调用 embedding API）
│   │       └── retrieve.ts   # pgvector 相似度检索
│   │
│   ├── session/              # 会话状态机 + Temporal workflow（第7章）
│   │   └── src/
│   │       ├── workflow.ts   # Temporal workflow 定义
│   │       ├── activities.ts # Temporal activities
│   │       └── state.ts      # 会话状态类型和转换
│   │
│   └── observability/        # OpenTelemetry + Langfuse 集成（第11章）
│       └── src/
│           ├── tracer.ts     # OTel tracer 初始化
│           └── langfuse.ts   # Langfuse SDK 封装
│
└── apps/                     # 可执行的应用进程
    ├── api/                  # Fastify HTTP 服务（贯穿全书）
    │   └── src/
    │       ├── app.ts        # Fastify 实例和插件注册
    │       ├── routes/       # 路由定义
    │       └── plugins/      # 自定义插件（认证、限流等）
    │
    ├── worker/               # Temporal + BullMQ Worker 进程（第7章引入）
    │   └── src/
    │       ├── temporal.ts   # Temporal Worker 入口
    │       └── bullmq.ts     # BullMQ Worker 入口
    │
    └── sandbox/              # isolated-vm 沙箱进程（第5章引入）
        └── src/
            └── index.ts      # 沙箱进程，独立运行避免 VM 崩溃污染主进程

{
  "name": "agentflow",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev --parallel",
    "test": "turbo run test",
    "typecheck": "turbo run typecheck"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "typescript": "^5.7.0"
  }
}

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*.ts", "tsconfig.json"],
      "outputs": ["dist/**"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*.ts", "tsconfig.json"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*.ts", "tests/**/*.ts"]
    }
  }
}

// 没有 strict 时很容易写出
const intent = response.content[0].text;  // content[0] 可能是 undefined
const action = JSON.parse(intent).action; // intent 可能是 undefined
 
// strict 强制你处理每个可能的 undefined
const block = response.content[0];
if (!block || block.type !== 'text') {
  throw new AgentParseError('LLM 返回了意外的内容类型');
}
const action = JSON.parse(block.text).action as string;

interface SessionState {
  endedAt?: Date;  // 开启 exactOptionalPropertyTypes 后
                   // { endedAt: undefined } 和 {} 是不同的类型
}
 
// 以下赋值在 exactOptionalPropertyTypes 下会报错
const state: SessionState = { endedAt: undefined };
//                           ~~~~~~~ Type 'undefined' is not assignable to type 'Date'
// 正确写法：省略该字段，而不是显式写 undefined
const state2: SessionState = {};

// 遵循规则一：key 包含 tenant_id 前缀
const sessionKey = `${tenantSlug}:session:${sessionId}`;
await redis.set(sessionKey, JSON.stringify(sessionData), 'EX', 3600);
 
// 遵循规则三：circuit breaker 状态存 Redis，不存内存
const circuitKey = `${tenantSlug}:circuit-breaker:anthropic-api`;
await redis.set(circuitKey, '0', 'EX', 60);
 
// 直接调用 Anthropic SDK
const response = await anthropic.messages.create({
  model: 'claude-3-5-haiku-20241022',
  max_tokens: 256,
  messages: [{ role: 'user', content: userMessage }],
});

# 确保 Docker Compose 服务已启动
cd examples
docker compose up -d
 
# 安装依赖并运行
cd hello-agent
npm install
export ANTHROPIC_API_KEY=sk-ant-api03-...
npm run dev