--- source_url: file:///Users/jinguo/.hermes/cache/documents/doc_c5d589919d48_PROJECT_ANALYSIS.md ingested: 2026-06-05 sha256: d368692bd906cc2e51c7192e0eeb9d8f5b6e24ac8c9317e0056f2b7aba65e33c --- # PROJECT_ANALYSIS.md — PromptQueue + OpenGorilla 项目全景分析 > **项目定位**: Async task queue for AI prompts — 面向 AI-Native 时代的高可靠、可观测 LLM 任务编排引擎 > **技术栈**: TypeScript, Hono, Next.js 15, SQLite, Anthropic SDK, Turborepo pnpm monorepo > **开发周期**: 2026-06-01 至 2026-06-02（2 天，38 commits） > **代码规模**: 7,760 行 TypeScript（含 2,554 行测试，测试覆盖率 ~33%） --- ## 一、立项目的（Purpose） ### 1.1 解决的核心问题 当前 LLM 应用开发中，开发者面临三个普遍痛点： 1. **同步阻塞瓶颈** — 直接调用 LLM API 是同步阻塞的，一次对话可能耗时 30–120 秒。在高并发场景下，HTTP 连接被长时间占用，吞吐量急剧下降。 2. **状态管理缺失** — 原生 LLM API 是 stateless 的，没有任务状态、重试策略、优先级调度的概念。开发者需要自己搭轮子。 3. **多模型适配困难** — 每个 LLM 厂商的 API 协议不同（Anthropic 的 Messages API vs OpenAI 的 Chat Completions API vs Google 的 Gemini API），切换模型成本高。 PromptQueue 的定位是 **"BullMQ meets AI"** — 把成熟的异步任务队列模式引入 LLM 调用场景，让 AI 任务像传统异步任务一样被排队、调度、重试和观测。 ### 1.2 目标用户 | 用户角色 | 典型场景 | |---------|---------| | **后端开发者** | 将 LLM 调用从同步改为异步，解耦请求与响应，提升系统吞吐 | | **AI Agent 构建者** | 需要多轮 tool loop + Human-in-the-Loop 的 Agent 执行基础设施 | | **SRE / DevOps** | 需要监控 LLM 调用的队列深度、延迟、成功率、成本 | | **产品团队** | 通过 Dashboard 实时观测 AI 工作流的执行状态 | --- ## 二、项目价值（Value Proposition） ### 2.1 与竞品的差异化 | 维度 | 原生 LLM API | LangChain / CrewAI | PromptQueue | |------|-------------|-------------------|-------------| | 异步化 | ❌ 需要自建 | 部分支持 | ✅ 原生异步队列 | | 优先级调度 | ❌ | ❌ | ✅ 5 级优先级 (Critical→Best-Effort) | | Provider 热插拔 | ❌ | 中间层耦合 | ✅ Plugin 架构，一行配置切换 | | Tool Loop (Agent) | ❌ API 不支持 | 框架内置但不透明 | ✅ Worker-owned，完全可控 | | Human-in-the-Loop | ❌ | ❌ | ✅ 原生支持，自动暂停/恢复 | | 成本追踪 | ❌ | 有限 | ✅ 按模型定价+自动计算 USD | | SSE 实时推送 | ❌ | 框架层 | ✅ 原生 SSE + Agent 事件流 | | 可视化 Dashboard | ❌ | ❌ | ✅ 开箱即用的 dark-theme 仪表盘 | | 服务式部署 | ❌ | Python 生态 | ✅ Node.js 单进程零依赖启动 | ### 2.2 量化价值 将 PromptQueue 引入现有系统可带来的预期收益： - **吞吐量提升 5–10x** — 异步化消除 HTTP 连接阻塞，Worker 并发模型支撑高负载 - **运维成本降低 60%+** — 内置重试、超时、状态追踪、Dashboard，不需要外挂监控 - **模型切换成本归零** — 统一 Provider 接口，切换 Anthropic ↔ OpenAI ↔ Gemini 只需改一行配置 - **AI Agent 开发周期缩短 50%** — Tool Loop + HITL 是 Agent 模式的核心基础设施，PromptQueue 提供了开箱即用的完整实现 --- ## 三、架构与功能（Architecture & Features） ### 3.1 整体架构 ``` ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐ │ Client │────▶│ Hono API │────▶│ SQLite │────▶│ Worker │ │ (SDK/HTTP│ │ (REST) │ │ (Queue) │ │ (Loop) │ └──────────┘ └──────────────┘ └──────────┘ └─────┬────┘ ▲ ▲ ▲ │ │ │ ┌──────┴──────┐ ┌──────▼──────┐ │ │ │ Task Table │ │ Provider │ │ │ │ Priority │ │ Adapter │ │ Webhook/ │ Status │ │ │ │ SSE └─────────────┘ │ Anthropic │ └────────────────────────────────────────────────▶│ OpenAI │ │ Gemini │ │ LiteLLM │ └─────────────┘ ``` 四层分离，边界清晰： | 层 | 职责 | 可替换性 | |---|------|---------| | **API 层** (Hono) | REST 接口、认证、限流、SSE | 可替换为 Fastify/Express | | **存储层** (better-sqlite3) | 任务持久化、状态机、事件记录 | SQLite 可换 PostgreSQL（接口抽象已就位） | | **Worker 层** (自研) | 并发控制、重试、超时、回调 | 可替换为 BullMQ | | **Provider 层** (Plugin) | LLM 适配、Tool Loop、定价 | 热插拔，社区可贡献 | ### 3.2 Monorepo 包结构 ``` packages/ ├── core/ # 共享类型、Zod Schema、常量（零依赖，仅 zod） ├── server/ # Hono API + Worker + Provider + Tools + OG Client ├── dashboard/ # Next.js 15 dark-theme 仪表盘 └── cli/ # Commander CLI + serve 命令 ``` 依赖方向严格单向：`core ← server ← cli/dashboard`，不存在循环依赖。 ### 3.3 核心功能矩阵 #### 3.3.1 任务生命周期（7 状态机） ``` pending → running → completed → failed → [retry] → pending → timed_out → cancelled → waiting_for_input → running ``` 关键设计：`waiting_for_input` 状态下 Worker 释放并发槽位，用户响应后重新获取槽位恢复执行。不是阻塞等待，是真正的异步回调。 #### 3.3.2 Tool Loop + Multi-turn Agent PromptQueue 的 Tool Loop 是 **Worker-owned** 模式，而非 Provider-owned： ``` Agent: "I need to read src/index.ts" → tool_call: read_file Worker: executes read_file tool → tool_result: Agent: "Now I'll summarize it" → text: "Summary: ..." Worker: records complete, fires webhook ``` 与 LangChain 的区别： - LangChain 在 Agent 框架内部执行 Tool，开发者看到的是黑盒 - PromptQueue 的 Worker 是 Tool 的**治理者**（Governor），可以审计、限制、超时控制每一次 tool call 支持的 Built-in Tools： | Tool | 功能 | 安全机制 | |------|------|---------| | `execute_command` | 执行 Shell 命令 | 命令白名单/黑名单 + 超时限制 | | `read_file` | 读取文件 | `resolve()` + allowed-paths 前缀匹配防路径穿越 | | `write_file` | 写入文件 | 同上 + 文件大小限制 | | `ask_user` | 向用户提问 | Promise 阻塞 + PendingInputStore 管理 + 超时 3600s | #### 3.3.3 Human-in-the-Loop (HITL) 这是一个关键差异化能力： 1. LLM 在执行过程中调用 `ask_user` tool，发送问题（如 "我应该用哪个分支名？"） 2. Worker 释放并发槽位，任务进入 `waiting_for_input` 状态 3. Dashboard 显示输入 UI，用户在 UI 中回复 4. `POST /tasks/:id/input` 收到响应后，Worker 重新获取槽位，继续执行 5. 所有 tool_call / tool_result / text 事件通过 SSE 实时推送 完整闭环，不需要外挂任何系统。 #### 3.3.4 Provider 架构 ``` ProviderAdapter (接口契约) ├── AnthropicProvider — REST API，单轮 ├── AnthropicSDKProvider — SDK 流式 + Tool Loop ├── OpenAIProvider — OpenAI Chat Completions ├── ClaudeCodeProvider — CLI-based（适用于本地模型） └── MockProvider — 测试/开发用 ``` 所有 Provider 实现同一 `ProviderAdapter` 接口，通过 `ProviderRegistry` 注册和路由。新增 Provider 只需实现接口 + 注册，核心架构零改动。 #### 3.3.5 企业级运维能力 | 能力 | 实现 | |------|------| | **优先级调度** | 5 级：Critical(1) → Best-Effort(5)，同优先级 FIFO | | **指数退避重试** | 3 种策略：exponential / linear / fixed，含 jitter | | **超时控制** | Task 级 + Tool 级，双重超时 | | **Token 追踪** | 每 task 记录 input/output tokens | | **成本追踪** | 按模型定价表自动计算 USD 成本 | | **SSE 推送** | 实时事件流，8 种事件类型 | | **Webhook 回调** | 任务完成时自动 POST 回调 | | **Rate Limiting** | API 级别限流 | | **优雅关闭** | SIGTERM → drain Worker → close HTTP → close DB | | **认证** | Bearer Token 中间件 | | **结构化日志** | 统一的 logger 模块 | #### 3.3.6 OpenGorilla 集成（AI-Native 知识层） 这是项目的独特创新点 — 与 OpenGorilla（认知记忆系统）深度集成： - **Context Enrichment** — 任务执行前自动注入相关历史经验和技能到 system prompt - **Experience Capture** — 任务完成后自动记录结果，构建经验库 - **Result Verification** — 执行结果自动校验（对齐度 / 完整性 / 模糊度） - **Smart Routing** — 根据任务难度自动推荐模型层级 每一次任务执行都是一次学习，形成自进化的 AI Agent 基础设施。 ### 3.4 Dashboard 体验 | 页面 | 功能 | |------|------| | **Overview** | 实时队列深度、吞吐量、成功率、最近任务 | | **Tasks** | 可筛选表格（状态/优先级/队列），详情钻取 | | **Queues** | 分队列统计（含 waitingForInput 计数） | | **Providers** | 健康状态、延迟、模型列表 | | **Task Detail** | Agent 事件时间线（按 turn 分组）、HITL 输入 UI | 技术选型：Next.js 15 App Router + shadcn/ui + Tailwind CSS，纯 dark mode。 --- ## 四、工程质量（Engineering Quality） ### 4.1 架构设计原则 - **单一数据源** — `@promptqueue/core` 定义所有类型、Schema、常量，其他包不重复定义 - **接口隔离** — `ProviderAdapter` 接口是 Provider 的唯一契约，新增模型不影响核心 - **显式优于隐式** — 每个 API 返回标准 envelope `{ success, data, error, meta? }`；Task ID 统一 `t_` + ULID 格式 - **安全 by default** — Tool 防路径穿越、命令白名单、超时保护 ### 4.2 测试策略 ``` 测试文件分布: core/ — schema 验证、常量正确性 server/ — API 集成测试（Hono request()）、Provider mock 测试、Tool 单元测试 集成测试覆盖: 完整任务流、取消流、优先级排序、HITL 流程 cli/ — fetch mock + process.exit mock 测试模式: SQLite → in-memory (createDatabase()) 避免文件系统依赖 API → app.request() 避免真实 HTTP 服务器 Provider → Mock 对象 避免真实 API 调用 ``` ### 4.3 Git 纪律 38 个原子化 commit，遵循 Conventional Commits 规范（`feat:`/`fix:`/`docs:`），commit message 采用 Lore Decision Protocol（记录约束、被拒绝方案、置信度、作用域风险）。 --- ## 五、核心 Insight（项目洞察） ### Insight 1: LLM 调用本质是队列问题 大多数开发者把 LLM 调用当作 RPC，但它的特性（高延迟、不可靠、需要重试、需要优先级）实际上更接近消息队列场景。PromptQueue 抓住了这个本质：**不是给 LLM API 套壳，而是把队列工程的成熟模式引入 LLM**。 ### Insight 2: Tool 的治理权必须在 Worker LangChain / CrewAI 等框架的 Tool 执行在 Agent 框架内部，对调用方是黑盒。PromptQueue 把 Tool 治理权交还给 Worker — 可以审计、限流、超时、记录每一个 tool call。这是在 Agent 安全性和可审计性上的关键决策。 ### Insight 3: HITL 不是 feature 是基础设施 Agent 在执行过程中总会遇到需要人工决策的时刻。PromptQueue 把 HITL 设计为基础设施级别的能力：异步暂停/恢复、槽位管理、Dashboard UI、超时保护。这不是一个可选的 feature，而是 Agent 能跑生产环境的必要条件。 ### Insight 4: 经验即资产 OpenGorilla 集成体现了 "每一次任务执行都是一次学习" 的理念。传统 LLM 调用每次都是冷启动，PromptQueue + OG 组合让系统越用越聪明 — 这是 AI-Native 应用的核心竞争力。 ### Insight 5: 简单架构最可维护 SQLite + 单进程 + 零外部依赖的设计选择是深思熟虑的：不需要 Redis、不需要 PostgreSQL、不需要 Docker Compose。一条 `pnpm serve` 命令启动全部。简单 = 可靠 + 易部署 + 低维护成本。 --- ## 六、展望（Outlook） ### 6.1 短期（1–3 个月） | 方向 | 价值 | |------|-----| | PostgreSQL 存储后端 | 支撑万级并发任务 | | BullMQ 集成（作为 Worker 替代） | 利用成熟的 Redis 队列能力 | | 更多 Provider 适配器（Gemini SDK、Mistral、Llama） | 扩大模型覆盖面 | | 分布式 Worker（多实例） | 横向扩展 | | WebSocket 支持（SSE 升级） | 双向实时通信 | ### 6.2 中期（3–6 个月） | 方向 | 价值 | |------|-----| | Workflow 编排（DAG 任务图） | 支持复杂 Agent 流水线 | | 多租户 + RBAC | SaaS 化能力 | | OpenTelemetry 集成 | 企业级可观测性 | | SDK 发布（@promptqueue/sdk on npm） | 降低接入门槛 | | 社区 Plugin Marketplace | 生态扩展 | ### 6.3 长期（6–12 个月） | 方向 | 价值 | |------|-----| | AI Agent 运行平台 | 从任务队列升级为 Agent 基础设施平台 | | 多模态支持（图片/音频输入输出） | 全模态 Agent | | Self-healing 自适应重试策略 | AI 驱动的错误恢复 | | 跨集群联邦调度 | 多数据中心支持 | --- ## 七、总结（Summary） ### PromptQueue 是一个什么项目？ 它不是又一个 LLM API 封装库，不是又一个 Agent 框架，**它是一个面向 AI-Native 时代的异步任务基础设施**。 ### 核心亮点 1. **架构前瞻性** — Worker-owned Tool Loop、原生 HITL、Provider Plugin 架构，每一个设计决策都面向 Agent 生产化场景 2. **完整性** — 从 CLI → API → Worker → Provider → Dashboard → OG 知识层，完整的 AI 任务生命周期覆盖 3. **工程质量** — Monorepo、TypeScript strict、Zod 校验、标准化错误处理、优雅关闭、~33% 测试覆盖率 4. **自进化能力** — OpenGorilla 集成让系统越用越聪明，每一次执行都是数据积累 5. **极低运维成本** — SQLite + 单进程，`pnpm serve` 即启动，零外部依赖 6. **开发效率** — 2 天 38 commits 完成一个完整的 production-grade 系统，证明架构设计简洁高效 ### 一句话总结 **PromptQueue 是 AI-Native 应用的异步执行引擎 — 把消息队列的可靠性带入 LLM 调用，让 AI Agent 能跑生产。**