sebastiancarlos/faaah

来源：https://github.com/sebastiancarlos/faaah

🗣️ FAAAH（Filesystem As An AI Handler）

你所需的最简单的 OpenAI 兼容 LLM 代理。TM️

FAAAH 让你可以将自己的 AI Agent 订阅复用为通用的 OpenAI 兼容本地服务器。FAAAH 零依赖，以纯文本文件协议实现_（经 Unix 哲学认证）_：

1. 无需将提示词发送到云端 LLM API，而是发送到 FAAAH，它会读取 OpenAI 兼容的请求，并将其作为 .txt 文件转储到文件夹中。
2. 然后，告诉你的现有 AI 编码代理（Claude Code、opencode 等）读取这些文件，并将响应写入其他 .txt 文件。
3. FAAAH 随后将响应打包成 OpenAI 兼容的 JSON，并返回给你的应用。

为什么？

因为你已经在为 AI 编码助手付费了。别再为了周末的业余项目而花钱买 API key！faaah！

视频演示

https://github.com/user-attachments/assets/079620cb-e40d-49d0-9d70-7a8f6a6e1f07

这允许吗？

据我所知，在本地、非商业性地使用这个工具不会违反任何 AI Agent 提供商的现有服务条款。但如果有律师不同意，欢迎给我发消息。届时我会把你介绍给我的一个朋友：芭芭拉·史翠珊小姐（Miss Barbra Streisand）。

请谨慎使用 FAAAH 处理海量数据集。某些提供商（你知道是哪些）可能会对它们含糊的 ToS 做一些_卡夫卡式_的解读，并部署_奥威尔式_遥测来检测违规行为（我还没遇到过，YOLO！）

特性

• 零依赖： 使用 Python 的 http.server。仅此而已。
• 308 行代码： 你见过这类工具里其他那些臃肿的东西吗？恶心。
• Unix 哲学： 万物皆文件。做好一件事。保持 KISS，无需 YAGNI。
• 通用兼容性： 如果某个工具支持_事实上_的 OpenAI API 格式（GraphRAG、LangChain、LlamaIndex、LiteLLM、openai SDK），它就支持 FAAAH。
• 与 Agent 无关： 由于代理入口是一段提示词，它不绑定任何特定的代理提供商/版本。面向未来。
• 人在环路回退： 如果 AI 代理卡住或达到使用限制，你可以直接打开当前响应文件（比如 response-0004.txt），自己键入答案（或将请求复制粘贴到你最喜欢的网页聊天机器人），然后保存。FAAAH 会成功。

用法

0. 安装

使用 uv 安装：

# 在本仓库内
uv tool install .
# 将 `faaah` 命令安装到 PATH

或者直接从 git 仓库安装：

uv tool install git+https://github.com/sebastiancarlos/faaah

1. 启动服务器

faaah # 监听 127.0.0.1:8000，队列目录 ~/.cache/faaah/queue
faaah --port 8080 # 覆盖端口
faaah --queue /tmp/q # 覆盖队列目录

2. 将你的代理指向队列

代理提示词会在启动时打印。要重新获取它：

faaah --agent-message

把它粘贴到你的编码代理中，然后它就会启动一个 FAAAH 协调器循环：

• 调用 faaah --watch 获取下一个请求（在存在之前会阻塞）。
• 将请求委派给一个 worker 子代理（以防止上下文不断累积）。
• 重复。如果某个 worker 没有留下响应文件，faaah --watch 会再次返回相同的路径，因此协调器会重试它。

注意： FAAAH 使用子代理来防止多个请求耗尽上下文。因此，你的 AI 代理_必须支持通过提示词按需创建子代理_。

3. 发送请求

例如，你可以使用 curl：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer anything" \
  -d '{
    "model": "faaah",
    "messages": [{"role": "user", "content": "Write a haiku."}]
  }'

或者任何 OpenAI API 形状的客户端：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="anything")

response = client.chat.completions.create(
    model="faaah", # 这个字段反正会被忽略
    messages=[{"role": "user", "content": "Write a haiku."}],
    timeout=None, # 代理可能会很慢
).choices[0].message.content

print(response)

一个零依赖的示例位于 examples/chat.py。关于高级用法——完全通过 FAAAH 驱动的 GraphRAG，请参见 graphrag-faaah（https://github.com/sebastiancarlos/graphrag-faaah）。

CLI 用法

usage: faaah [-h] [--host HOST] [--port PORT] [--queue QUEUE]
             [--timeout TIMEOUT] [--agent-message] [--watch]

Filesystem As An AI Handler: an OpenAI-compatible proxy backed by an AI agent
working over text files.

options:
  -h, --help       show this help message and exit
  --host HOST      Address to bind (default: 127.0.0.1).
  --port PORT      Port to listen on (default: 8000).
  --queue QUEUE    Directory where prompt/response files live
                   (default: ~/.cache/faaah/queue).
  --timeout TIMEOUT
                   Abort each call after N seconds. 0 (default) waits
                   forever.
  --agent-message  Print ONLY the agent prompt and exit (it's also printed on
                   launch).
  --watch          Block until a pending prompt exists, print its path.

协议（“Filesystem API”）

该协议依赖于队列目录（默认是 ~/.cache/faaah/queue）中的文件。每个请求都会生成一个 prompt-<id>.txt 文件，其中第一个文件的 ID 是 00001，之后单调递增。

然后，FAAAH 期望代理（或者任何东西）生成对应的 response-<id>.txt。子代理 worker 会被提示先写入一版草稿作为 response-<id>.txt.draft，它们可以修改草稿，然后重命名为他们认为_最终_的 response-<id>.txt。

重试是自动的：没有响应文件的提示词只会被 faaah --watch 重新提供给协调器，直到出现响应文件为止。

许可证

MIT