FlowDex
高效令牌的LLM路由器+上下文管理器用于 n8n 并且 克劳德·科德（MCP）—可在本地部署或通过远程HTTP桥接进行部署。
目标：保持大量 *工作中的* 在不大量使用标记（token）的情况下提供上下文。用更稳健、不那么依赖标记的提示来替换那些脆弱且标记需求高的提示 差异上下文， 语义检索， 函数路由，和 严格的代币预算。
- API使用缓存、提示宏、增量上下文、路由、重试支持和健康检查的Python FastAPI。
- MCP桥一个通过HTTP暴露FlowDex MCP工具的FastAPI服务器，用于远程VS Code/Claude Code环境设置。
- n8n 节点最小自定义节点，可触发FlowDex
/infer和；与；带着 少数参数 （模型、任务、输入）。避免原生节点爆炸。 - CLI（Command Line Interface）——命令行界面检查预算、缓存，并重现运行。
- 本地栈:
docker-compose.yml（API + Redis + MCP桥接）。默认使用SQLite进行持久化。稍后在真实向量数据库中进行交换。
FlowDex存在的原因
FlowDex源于实际自动化任务的处理需求，当“仅仅在提示中添加更多代币”这种方法无法继续扩展时，FlowDex应运而生。产品团队和 操作员需要保存数周的上下文信息、工具转录记录和故障排除笔记，而无需为大量上下文付费 每当提示发生变化时，重写流程或在Windows上重新运行。FlowDex将这些经验整合成一个单一的、具有特定见解的服务，该服务：
- 保持/保存 工作记忆 在不复制完整转录文本的情况下，实现跨回合的自动化。
- 仅当大语言模型（LLM）调用能增加价值时才进行昂贵的调用，优先使用缓存结果或更经济的工具。
- 为操作员提供一条可审计的记录，显示助手看到了什么、选择了哪个工具以及为何做出这些决策。
FlowDex的功能
FlowDex的核心是一个FastAPI服务，用于追踪由大型语言模型（LLM）驱动的工作流中的每一次交互。它存储了每次交互之间的差异（diffs）， 强制执行令牌预算，记录重试次数，并确保每次运行均可复现。同一个后端还支持：
- 一个MCP桥，以便Claude Code（VS Code）可以调用生产环境中使用的精确API。
- 一个n8n节点，让低代码开发者无需自定义HTTP粘合代码即可编排FlowDex。
- 一个用于检查缓存命中、预算、清单以及在本地重现运行的命令行界面（CLI）。
FlowDex如何助您一臂之力
通过集中管理提示逻辑和运行历史，FlowDex让您能够：
- 更快发货 无论助手是在n8n、Claude Code还是自定义脚本中运行，都必须针对同一个API进行构建。
- 少花钱 – Delta上下文、语义记忆和严格的预算控制使得令牌使用可预测且保持低位。
- 自信地操作 – 持久化的运行清单、差异上下文以及重放工具使得调试变得简单直接。
- 保持灵活 – 在不重写每个工作流节点的情况下，交换模型、检索引擎或工具定义。
关键思想
- Delta上下文（补丁提示）只发送发生变化的部分。我们在每次交互之间计算内容哈希和最小的JSON补丁。
- 代币预算管理器为...设定上限（或硬性限制） 系统， 上下文， 工具， 用户 具有优雅的降级功能和日志记录。
- 语义回忆（可选）今天先用简单的词袋模型+SQLite索引；之后再插入你自己的向量。
- 函数注册表带有成本提示的强类型工具；路由器选择 *工具 > 文本* 当更便宜的时候。
- 决定论与可复现性运行清单以JSON格式保存；一键重放。
- n8n 一流服务一个紧凑的节点 → FlowDex API。无需使用原生节点，避免冗余。
- 通过MCP的Claude Code在您的编辑器中，将FlowDex作为工具集成到表面，而不是作为一个单独的聊天标签页。
逐步设置
0. 先决条件
| 组件 | 要求 | 备注 |
|---|---|---|
| Docker（可选） | docker & docker compose 推荐使用包含 Redis + MCP 桥接的组合，以实现最快路径。 | |
| Python | 3.10+ | 本地安装、命令行工具及开发所需。 |
| Redis（可选） | 7+ | Docker compose 会自动启动它。本地安装可以指向现有实例或回退到内存缓存。 |
在部署到远程环境之前，请准备好一个与Anthropic兼容的API密钥（或您配置的任何后端模型）。
1. 克隆仓库
git clone https://github.com/your-org/FlowDex.git
cd FlowDex2. 选择部署路径
选项A：Docker Compose（推荐）
- 复制示例环境文件或创建一个新文件
.env位于项目根目录的文件。 - 更新诸如……之类的秘密信息
FLOWDEX_API_KEY以及你计划调用的模型。 - 启动堆栈：
docker compose up --build- API将在以下位置可用：
http://localhost:8787以及MCP HTTP桥接器在http://localhost:8788。 - 停止堆栈（或栈）使用 Ctrl加号C 或者
docker compose down当你完成后。
选项B：本地Python环境
- 创建并激活虚拟环境：
python -m venv .venv
source .venv/bin/activate- 安装依赖项：
pip install -r server/requirements.txt- （可选）如果希望数据持久化/缓存超出进程生命周期，可以在本地启动 Redis。
- 启动API服务器：
uvicorn server.app:app --reload --port 8787- 在第二个终端中，如果需要Claude Code连接，请启动MCP HTTP桥接器：
python mcp/mcp_http_server.py3. 配置环境变量
创造 .env （或使用 Docker 环境）：
FLOWDEX_PORT=8787
FLOWDEX_MODEL=anthropic/claude-3-5-sonnet
FLOWDEX_CACHE_DIR=.flowdex_cache
FLOWDEX_MAX_TOKENS=6000
FLOWDEX_BUDGET_SYSTEM=1000
FLOWDEX_BUDGET_CONTEXT=2500
FLOWDEX_BUDGET_USER=1500
FLOWDEX_BUDGET_TOOLS=1000
FLOWDEX_API_KEY=change-me
FLOWDEX_REDIS_URL=redis://localhost:6379/0FLOWDEX_MODEL可以是您的下游大型语言模型（LLM）代理所支持的任何提供商/模型名称。FLOWDEX_REDIS_URL是可选的；省略它以在内存模式下运行（适合快速试验）。- 揭露；展示
FLOWDEX_API_KEY每当API可以从不受信任的网络访问时，MCP桥会自动转发此头部。
实际的标记计数和嵌入功能是可插拔的。已提供存根以便当前可以离线运行。
4. 验证安装
API运行后，进行健康检查：
curl http://localhost:8787/health你应该会看到一个类似的JSON响应，如 {"status": "ok"}如果 Redis 不可用，响应将指出缓存性能已降级。
5. 种子记忆（可选）
您可以预加载将在工作流中引用的持久片段：
curl -X POST http://localhost:8787/memory/put \
-H "Content-Type: application/json" \
-H "x-flowdex-api-key: $FLOWDEX_API_KEY" \
-d '{
"id": "runbook.postgres",
"title": "Postgres On-Call Runbook",
"body": "Check pg_stat_activity; restart read replicas if backlog > 500",
"tags": ["db", "incident"]
}'内存存储会保留之前的版本，因此您可以回滚或查看更新的差异。
6. 提交推理请求
curl -X POST http://localhost:8787/infer \
-H "Content-Type: application/json" \
-H "x-flowdex-api-key: $FLOWDEX_API_KEY" \
-d '{
"task": "triage",
"model": "anthropic/claude-3-5-sonnet",
"inputs": {
"user": "Summarize the last incident and draft an update.",
"context": ["runbook.postgres"],
"tool_hints": ["post_incident_report"]
}
}'该响应包含一个 run_id，令牌使用情况、工具决策以及生成的文本。存储这些 run_id 稍后重试或复现。
7. 重播或重新运行
curl -X POST http://localhost:8787/infer//retry \
-H "Content-Type: application/json" \
-H "x-flowdex-api-key: $FLOWDEX_API_KEY" \
-d '{
"error": "Tool failed: post_incident_report",
"patch": {"path": "/inputs/tool_hints", "op": "add", "value": ["post_incident_report", "status_page"]}
}'重试时会自动重用上下文差异，以保持令牌使用的最小化。
终点（或端点）
GET /health– 轻量级准备就绪 + Redis 连接检查。POST /infer– 运行一个任务，设定预算、对比上下文，并可选择检索。POST /infer/{run_id}/retry– 重新运行之前的任务，使用新的错误上下文进行自动化修复循环。POST /memory/put– 存储或更新命名上下文数据块（带版本控制）。GET /memory/get?id=...– 获取最新版本或特定版本。POST /tools/register– 声明一个带有模式和成本提示的工具。GET /runs/{id}– 查看之前的运行清单以进行复现。
克劳德·科德（MCP）
根据VS Code/Claude Code的运行位置，有两种选择：
- 本地桌面 – 运行原始的stdio桥接器：
python mcp/server.py然后配置Claude Code以生成该脚本。
- 远程/浏览器（Unraid、Codespaces 等） – 运行HTTP桥接器：
python mcp/mcp_http_server.py # or let docker compose manage it克劳德·科德要点 https://your-host/mcp （在Cloudflare等之后）。桥接代理 flowdex.infer， flowdex.infer.retry， flowdex.memory.get，以及 flowdex.health 通过HTTP，支持API密钥认证。
默认值 docker-compose.yml 现在与API一起构建并运行桥接服务，开放端口 8788。
Claude 代码配置指南（或配置过程详解）
- 在VS Code中安装Claude Code扩展。
- 打开扩展设置并添加一个新的MCP服务器。
- 对于本地设置，请选择 过程 并指出
python mcp/server.py对于远程设置，请选择 HTTP（超文本传输协议） 并提供URLhttp://:8788/mcp。 - 设置环境变量
FLOWDEX_API_KEY如果您的API需要，请在MCP配置中进行设置。 - 重新加载Claude Code扩展。现在你应该能看到FlowDex工具（
flowdex.infer，flowdex.memory.get等工具）在工具面板中可用。
n8n 节点
从（指定位置）安装 n8n-node/ 放入你的n8n自定义节点文件夹中。该节点调用 /infer 以最少的配置。
n8n 使用示例
- 复制
n8n-node/flowdex将其放入你的 n8n 自定义节点目录中，然后重启 n8n。 - 在您的工作流程中，添加 FlowDex（可译为“流量管理工具”或根据具体上下文意译为更贴切的名称，如“流量优化平台”等，但直接翻译保持原样为“FlowDex”） 节点。
- 配置节点参数：
- API基础URL： http://flowdex:8787 （如果通过docker compose运行）或 http://localhost:8787 用于本地运行。 - 任务例如。， triage 或者 summarize。 - 用户输入来自上游节点的用户提示或有效载荷。 - 系统提示在跑道前可选装护栏。 - 上下文ID逗号分隔的内存ID或上下文备注。 - 工具候选者FlowDex 应考虑使用逗号分隔的工具标识符。 - 模型如有需要，请覆盖默认模型。
- 设置
X-API-Key在全球范围内在n8n中认证或附加一个Header Auth如果您的服务器需要认证，请使用节点。 - 手动或通过Webhook触发工作流以确认集成。
命令行界面
以下CLI（命令行界面） cli/ 提供了一种轻量级的方法，用于从终端发送推理请求并尝试不同的上下文/工具组合。
安装命令行界面（CLI）
pip install -r cli/requirements.txt
python cli/flowdex_cli.py --help示例命令
- 快速推断一下：
python cli/flowdex_cli.py --task summarize --user "List recent changes"- 包含上下文ID以增强记忆：
python cli/flowdex_cli.py --task incident_review --user "Draft a customer update" --ctx runbook.postgres comms.template- 提供工具候选和自定义模型：
python cli/flowdex_cli.py --task repair --user "Regenerate with tool assistance" --tool post_incident_report status_page --model anthropic/claude-3-5-sonnet所有CLI命令均遵循相同的（规则/标准） .env API的URL和认证凭据文件。
示例目录
这个（或“该”） examples/ 该文件夹包含您可以作为模板运行的端到端场景：
examples/incident_triage.ipynb– 笔记本，阐述了内存播种、推理和重试的过程。examples/tool_router.py– Python脚本用于注册工具，并演示路由器如何选择这些工具而非自由形式的大型语言模型（LLM）输出。examples/n8n_flow.json– 可导入的n8n工作流，用于连接FlowDex到Slack和PagerDuty。
每个示例都附有用于重现运行所需的命令说明，便于您根据自己的工作流程进行调整。
贡献
对改进FlowDex感兴趣吗？请阅读 贡献指南 以下是设置说明和推荐的调试工作流程（自动化测试 ➝ Playwright 验证 ➝ 仅在不可避免时进行手动检查）。该指南还包括一个拉取请求检查清单，以确保更改已准备好发布。
______________________________________________________________________
© 2025 FlowDex。生成时间：2025-10-23T00:31:05.007257Z