Prompt 管理、RAG 与 agents 使用 HazelJS

Source: Dev.to

一个入门示例：类型化提示模板、实时注册表、FileStore 持久化、RAG、监督代理以及 AI 任务——全部由同一个提示系统驱动

良好地管理 LLM 提示非常困难：你需要版本控制、无需重新部署的覆盖，以及一个让 RAG、代理和普通 AI 任务都能读取的统一位置。HazelJS Prompt Starter 展示了如何实现这一点。它基于 @hazeljs/prompts、@hazeljs/rag 和 @hazeljs/agent 构建，提供了：

• 一个带有 类型化模板 的 PromptRegistry，
• FileStore 持久化，
• 一个 REST API，可在运行时检查并覆盖任意提示。

RAG 答案合成、监督代理、工作代理以及四个 AI 任务（welcome、summarize、sentiment、translate）都使用同一个注册表。在本文中，我们将逐步介绍 starter 中包含的内容以及如何使用它。

功能

一个服务器，一个注册表： 使用 PUT /api/prompts/:key 更改提示，下一次 RAG 问题、代理运行或 AI 任务将使用新模板。

快速‑开始

git clone https://github.com/hazel-js/hazeljs-prompt-starter.git
cd hazeljs-prompt-starter
cp .env.example .env   # add OPENAI_API_KEY
npm install
npm run dev

服务器运行在 http://localhost:3000。尝试列出提示：

curl http://localhost:3000/api/prompts

然后覆盖 RAG 回答提示并提问（见下方示例）。
每个提示都由一个键标识（例如 rag:answer、agent:supervisor:system、app:summarize）。REST API 让您无需修改代码即可管理它们。

Prompt Registry API

示例：覆盖 RAG 答案提示

curl -X PUT http://localhost:3000/api/prompts/rag%3Aanswer \
  -H "Content-Type: application/json" \
  -d '{
    "template": "Answer in one sentence.\nContext: {context}\nQuestion: {query}\nAnswer:",
    "metadata": { "version": "2.0.0", "description": "Concise one‑sentence answers" }
  }'

示例：使用变量预览提示

curl -X POST http://localhost:3000/api/prompts/app%3Asummarize/preview \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "text": "HazelJS is a TypeScript framework.", "maxWords": "10" } }'

RAG 流程使用注册表中的 rag:answer 提示。通过 Prompts API 覆盖它，下一次对 /api/rag/ask 的调用将使用新的模板。

RAG API

导入并提问

curl -X POST http://localhost:3000/api/rag/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "content": "HazelJS is a TypeScript backend framework built for scalability.", "source": "intro.txt" },
      { "content": "@hazeljs/prompts provides typed, overridable prompt templates.", "source": "prompts.txt" }
    ]
  }'

curl -X POST http://localhost:3000/api/rag/ask \
  -H "Content-Type: application/json" \
  -d '{ "question": "What is HazelJS?" }'

工作流程： 使用 PUT /api/prompts/rag%3Aanswer 覆盖 rag:answer，然后再次运行相同的问题 —— 答案风格将遵循新的提示。

代理 API

示例

curl -X POST http://localhost:3000/api/agent/run \
  -H "Content-Type: application/json" \
  -d '{ "task": "Research the benefits of RAG over fine‑tuning and analyse the trade‑offs." }'

响应中包含 supervisorSystemPrompt —— 用于主管的精确提示。覆盖 agent:supervisor:system 或 agent:worker:researcher 并重新运行，即可看到不同的委派和输出风格。

AI 任务 API

示例

curl -X POST http://localhost:3000/api/ai/task/welcome \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alice", "topic": "prompt engineering" }'

curl -X POST http://localhost:3000/api/ai/task/summarize \
  -H "Content-Type: application/json" \
  -d '{ "text": "HazelJS makes building TypeScript back‑ends fast and type‑safe.", "maxWords": 15 }'

curl -X POST http://localhost:3000/api/ai/task/sentiment \
  -H "Content-Type: application/json" \
  -d '{ "text": "I love how easy it is to manage prompts with HazelJS!" }'

curl -X POST http://localhost:3000/api/ai/task/translate \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello, world!", "targetLanguage": "Spanish" }'

所有四个任务都从同一个注册表中获取提示，因此您可以通过 Prompt API 在运行时更新任意任务。

回顾

• One registry → 每个提示的唯一真实来源。
• Live REST API → 在无需重新部署的情况下编辑、预览、版本化并持久化提示。
• Typed templates → 完整的 TypeScript 推断，构建更安全的提示。
• FileStore → 提示在服务器重启后仍然保留。

试一试，实时微调提示，立刻感受 RAG、代理和 AI 任务行为的瞬间变化！

API 示例

# 摘要一段文本（最多30个词）
curl -X POST http://localhost:3000/api/ai/task/summarize \
  -H "Content-Type: application/json" \
  -d '{ "text": "HazelJS is a modular TypeScript framework...", "maxWords": "30" }'

# 获取情感分析
curl -X POST http://localhost:3000/api/ai/task/sentiment \
  -H "Content-Type: application/json" \
  -d '{ "text": "I love how easy HazelJS makes dependency injection!" }'

Prompt Registry Overview

项目结构

src/
├── main.ts                     # Bootstrap + startup banner
├── app.module.ts               # Root HazelModule
├── prompts/                    # @hazeljs/prompts integration
│   ├── prompts.service.ts
│   ├── prompts.controller.ts
│   └── prompts.module.ts
├── rag/                        # @hazeljs/rag — reads rag:answer from registry
│   ├── rag.service.ts
│   ├── rag.controller.ts
│   └── rag.module.ts
├── agent/                      # @hazeljs/agent — supervisor + workers from registry
│   ├── agent.service.ts
│   ├── agent.controller.ts
│   ├── workers/researcher.agent.ts
│   ├── workers/analyst.agent.ts
│   └── agent.module.ts
├── ai/                         # AI tasks via registry prompts
│   ├── ai-task.service.ts
│   ├── ai-task.controller.ts
│   └── ai.module.ts
├── llm/                        # OpenAI LLM provider for agents
│   └── openai-llm.provider.ts
└── health/
    └── health.controller.ts   # Liveness + readiness

How It Works

• Prompt Registry – 单个全局 PromptRegistry（由 PromptTemplate 和 FileStore 支持）保存所有提示模板。
• Runtime Overrides – 可以通过 REST API 列出、预览和覆盖提示；更改会被 RAG、代理和 AI 任务即时捕获。
• Persistence – 覆盖内容会持久化到 ./data/prompts.json（或其他存储），并在重启后仍然有效。

环境变量

请参阅 starter 项目的 .env.example 和 README 以获取完整列表。

扩展存储

在生产环境中，您可以通过调整 PromptsService 中的注册表配置，将 FileStore 替换为 RedisStore（或任何其他后端）。REST API 和所有使用者保持不变。

启动项目提供的内容

1. 一个注册表 – PromptTemplate、PromptRegistry 以及可插拔的、可类型化、可覆盖的提示存储。
2. 一个 REST API – 在运行时列出、预览并覆盖任意提示。所有服务（RAG、代理、AI 任务）会即时响应更改。
3. RAG、代理和 AI 任务 – 均从同一注册表读取，实现无需代码更改的行为调优。

克隆仓库，设置 OPENAI_API_KEY，即可拥有一个演示提示管理、RAG、监督代理和 AI 任务的单一应用。

如需了解更多关于 HazelJS 和 @hazeljs/prompts 的信息，请访问 hazeljs.com 和 HazelJS GitHub 仓库。