项目案例

编排引擎 LangGraph StateGraph + 数据驱动 Agent Registry 基于 LangGraph StateGraph 搭建编排框架，定义 10 个节点（输入护栏 / 意图分类 / 记忆加载 ∥ RAG 检索 / 路由决策 / dynamic_agent / pipeline_executor / HITL / 输出护栏 / 记忆保存；其中记忆加载与 RAG 检索挂在同一 superstep 并行，避免 fan-in 重复触发）。Agent 层数据驱动：4 类内建 Agent（佣金 / 客户 / 营销 / 支持）以数据库 AgentDefinition 种子记录存在，由单一通用 Agent Runner 执行，可经管理后台（/api/admin/agents）增删改并热生效——无子图缓存层，maxSteps 等配置每次请求动态解析，后台改即时生效。OrchestrationPipeline 多 Agent 串联编排（pipeline_executor 节点，按 intent 触发，找不到 pipeline 回落 dynamic_agent）。路由决策不再依赖置信度数值：matchQuality ∈ {strong, llm} 且属于单步意图（commission.query / network.view）走单步路径（maxSteps=1，仍经 LLM 与 Skill）；否则进入多步原生 tool loop（runNativeToolMode，一次非流式调用内由 ai SDK function-calling 跑完思考→调工具→观察，maxSteps 按 AgentDefinition 配置、经 intent 收紧）；步数预算耗尽且合成兜底为空自动触发 HITL。图状态经 PostgresSaver 持久化（独立 langgraph schema），支持 HITL interrupt/resume 跨请求恢复。 意图分类 关键词规则 + LLM 兜底熔断器 10 类意图（含 commission.team-report 团队业绩报告、support.deep-research 深度多源研究）从 JSON 配置文件热加载（fs.watch 监听，无需重启）。关键词匹配置信度低于阈值时调 LLM 兜底分类（超时 2.5s）；连续失败 3 次触发进程级熔断器，冷却 60s 不再调用，回落默认意图，避免 LLM 故障级联。LLM 分类时注入最近 4 条会话上下文，准确识别跨轮追问场景。 三层记忆 Redis · PostgreSQL 分层存储 短期：Redis Session（30min TTL），sliceShortTermMessages 注入最近 8 条消息；超 8,000 tokens 触发压缩，保留 [早期摘要] + 最近 7 条，压缩结果同步写入中期记忆。中期：PostgreSQL MemberConclusion（压缩摘要，跨 Session 恢复上下文）+ ConversationLog（最近 5 条原始问答，type='hitl' 过滤不进 LLM context）。长期：PostgreSQL MemoryRecord 作真相源（save_memory 异步投递 BullMQ，Worker 调 LLM 提取稳定事实偏好、写入前语义去重，满 20 条整合一次），并在 Qdrant long_term_memories 建 dense+sparse 混合语义索引；注入时按当前问题语义召回 + rerank + 分数门控取 Top-5，检索故障降级为按时间最新 topN 并打 degraded 标记。PG↔Qdrant 双向对账。 Hybrid RAG 8 步检索管道 · 查询改写 + 稀疏 + 稠密 + 精排 + Sandwich ①②为可选前置（特性开关控制，默认关闭）：① query rewrite 语义相似度校验（改写偏移自动回退原 query，避免 query drift）；② 复杂问题子查询分解（最多 3 条，hybridSearchMulti 并行检索后跨子查询 RRF 名次融合）。常开核心检索：③ BM25 稀疏向量（FNV-1a 32-bit hash，CJK 单字 + 相邻双字组加权）；④ embedding 缓存优先（SHA-256 key → Redis，重复 query 零 API 费用）；⑤ HyDE 并行生成假设文档（MiniMax-M3，带长度门控）再次 embed；⑥ 单次 Qdrant 混合查询（dense 原始 + HyDE 先内层 RRF，再与 sparse 顶层 RRF，嵌套融合防淹没，Top-20 候选）；⑦ 交叉编码器精排（BAAI/bge-reranker-v2-m3 via SiliconFlow，Top-5）；⑧ MMR 多样性去重（λ=0.7，压制同节近重复）+ score gate 分数门控 + 父文档折叠（small-to-big 全节注入）+ Sandwich 重排（第 2 高分 chunk 移至末尾，对抗 LLM 中间遗忘）。按 intent 规则跳过 RAG（纯数据查询类不走检索）。 双模型路由 11 种角色 · Claude Opus + MiniMax-M3 + 三态熔断自动降级 定义 11 个模型角色（agent_high / agent_routine / agent_creative / intent / structured_extract / summary / proactive / hyde / vision / voice_script / eval_judge），运行时权威源为 Admin 可改的 model-routing.json。生产环境高复杂度与创意角色走 Claude Opus 4.8（处理政策推理、多路投票一致性校验），其余角色走 MiniMax-M3（成本约 1/6），双模型路由已上线运行。复杂度反应式升级：融合确定性关键词分、意图分类器语义 difficulty、工具数与 runtime 反馈得到复杂度分，超阈值即从默认角色升到 agent_high（Opus）；多路投票分歧、撞步数上限等客观失败信号触发一次升档重试（每请求至多一次）。三态熔断器（healthy → broken → half_open 半开探测），状态经 Redis 跨实例共享、全局单探针单飞恢复；Claude 熔断时非高复杂角色降级 MiniMax，agent_high 严格不降级、直接 503。每小时按 provider 记录 API 成本（另有按会员日美元成本上限第二维限流），70% 告警、90% 熔断并暂停图片 / TTS 队列。 主动触达 Heartbeat 规则引擎 + AI 个性化消息 规则引擎支持 realtime / daily / monthly 三频次调度，条件类型覆盖 always / threshold / milestone / inactive 四类，规则从 JSON 热加载。触发后读取 PostgreSQL 会员画像和历史结论，由 MiniMax-M3 生成个性化消息，经输出护栏检查后通过 WebSocket / Inbox 站内信 / Push（移动端预留，当前降级为 WS + inbox）三通道下发。Redis 去重键控制单会员单规则每日发送上限，防骚扰；Inbox 列表空时回退 HeartbeatLog 重建近 7 天消息。Heartbeat LLM 成本计入运营侧，不占会员配额。 HITL LangGraph interrupt() + PostgresSaver 跨请求暂停恢复 Agent 步数超限或会员主动请求人工时，hitlResponseNode 调用 LangGraph interrupt() 原地暂停图，状态快照通过 PostgresSaver 持久化（独立 langgraph schema，非 Prisma 管理；Postgres 不可用降级 MemorySaver，带指数退避自愈）；并写 Redis 快路径标记 hitl:pending:{sessionId} 加速中断检测。会员回复后，第二次请求命中标记、调用 Command({ resume }) 恢复执行，LLM 提取姓名和联系方式，工单置 confirmed 并写 PostgreSQL SupportTicket（四态状态机，resolved 时经站内信通知会员）；联系方式仅入工单、脱敏后写 ConversationLog（type='hitl'），不污染后续 LLM 上下文。非 HITL 请求完成后 deleteThread() 清理 checkpoint，防 Postgres 积压。 分层 Skill 确定性脚本 + 可维护 Claude Skill bundle 在 Agent 自由推理之前插入一层 Skill，分两类协同。确定性 Skill（commission-query / network-analyst，skills-config/*.skill.json + TS assembler，intent 精确匹配）：按预定义 steps 串联调用已注册 Tool，组装成结构化上下文喂给 LLM，稳定可单测、省 token，用于数字/金额输出。可维护 Skill（标准 Claude Skill bundle skills-managed/<id>/，description 驱动命中、全局能力池）：运营可在后台改 markdown 维护话术/政策，受信脚本在沙箱执行。任一类失败均返回 null 无缝回落 Agent 普通路径，不阻断主链路。 多租户隔离 OrgID 契约化 · 分公司维度数据隔离 以会员 JWT 的 orgId claim 为运行时业务上下文唯一入口：知识库检索（两段式 fallback）、奖金规则与币种、Prompt 语言、few-shot、产品价格、取数全部按分公司隔离——同一 memberId 在不同分公司返回不同数据；缺/未知 orgId 生产侧直接拒绝。Mock 写成 org-scoped 接口契约，切真实业务系统只换实现、调用方与签名不变。 质量增强 Self-Consistency 投票 + Self-Refine 自修订 佣金 Agent 在复杂查询（跨多 period / 多层团队 / 特殊奖金规则，复杂度评分 >0.7）触发 Self-Consistency：并行 3 路采样（temperature=0.7）提取数值结论多数投票，三路分歧则按反应式升级降档重试 + HITL 标记。营销 Agent 长文案走 Self-Refine 自评修订，两者全部计入本次请求 token 用量并打 Langfuse tag。 配额管控 Redis Lua 预占 → 精确扣减 · 三档配额 + 异步 Job 状态机 进入 Agent 前预检配额，输出护栏之后按实际 token 精确扣减：同步链路走 checkAndThrow → requestId → deduct 的 provisional reservation（Redis Lua 同时维护聚合预占与 request 级 key，确认时按实时用量裁剪），图片 / TTS-HD 异步任务入队前走 reserveAsyncJob，confirm/release 仅在 reserved 状态执行，保证幂等与跨日释放。三档（免费 / 基础 / 高级）分别对应锁定 429、只读降级、仅限速。 知识库治理 两阶段发布 + Eval 门禁 + 版本回滚 知识库仅接受 Markdown：新版本先写 PostgreSQL pending + Qdrant deprecated:true 暂存，经 triggerKbEval()（自检 + 外部 Recall）门禁通过后，publishDocument() 在 PG 事务内先废旧 active 再激活新版本、随后公开新向量并隐藏旧向量。同一 docId 由 Redis 分布式锁保护，PG partial unique index 保证每个文档至多一个 active 版本，支持回滚与审计。

用户痛点 实体卡牌三大核心痛点 日本卡牌玩家面临：①真假难辨——二手市场假卡泛滥，PSA 评级门槛高；②价格不透明——Yahoo 拍卖与 Mercari 成交分散，无统一估值参考；③流动性差——高价值卡牌难以快速变现，卖家需长期等待买家。三大痛点共同指向"可信确权 + 实时定价 + 即时流动性"的核心产品方向。 竞品驱动 对标 CollectorCrypt 差异化设计 深度分析竞品 CollectorCrypt（市值 1,250 万美元），提炼三项借鉴点：即时回购（85% 市价）、透明概率盲盒、社区文化建设；同时识别对方手续费机制不透明的缺陷，设计差异化的阶梯手续费体系（1.5% 普通 / 0.5% 早期用户 / VIP 折扣）。 商业创新 回购 → 透明盲盒 业务闭环 设计"平台回购 PSA10 卡牌（市价 85-90%）→ 重新组成公示概率盲盒销售"的业务闭环，既消化库存、又产生额外收入；同步完成日本《景品表示法》合规分析，确保概率公示满足监管要求。 数据驱动 实时价格抓取驱动定价与收藏估值 设计 Python 爬虫系统每日抓取 Yahoo 拍卖、Mercari 成交数据，构建卡牌历史价格库；用户收藏总价值实时联动最新市场价计算，价格数据结构预留链上价格预言机接入能力。 战略决策 Web2 先行、Web3 平滑迁移 放弃"一步到位 Web3"方案，先以 Web2 MVP（2-3 个月）快速验证市场需求、积累价格数据与用户行为，规避早期合规风险；数据结构设计完全兼容链上格式，确保后续 1:1 迁移至 Polygon。 合规研究 日本三部法律合规边界分析 系统梳理《景品表示法》（概率公示要求）、《コンプリートガチャ 禁令》（完整扭蛋禁止）、《古物営業法》（二手商品交易规范），逐条对应产品功能设计，明确卡包盲盒、回购机制各自的合规路径与禁区。

架构 三端 + 七服务微服务拆分 Mall 会员端、Org 分公司端、Hq 总部后台三端独立部署；后端按业务域拆分为 BaseServiceCenter（基础服务）、ServiceCenterMall / Hq / Org / Search / Usdt / ImgService 七大服务，各自独立迭代，互不干扰。 路由设计 自研分库路由算法 基于 CustomerID / OrderID / CustomerNO / Mobile 等多维路由键，通过数据中心编号奇偶分片，实现多数据库无感知路由，支持大规模会员数据水平扩展。 分层缓存 Redis 业务对象缓存体系 针对商品分