fim-ai/fim-one · 上手攻略

仓库：fim-ai/fim-one
链接：https://github.com/fim-ai/fim-one
分类：ai / agent（自托管 Agent 平台，连接全球 SaaS 与中国信创系统）
作者：Jay
更新：2026-10-29

一、是什么

FIM One 是 FIM（ fim.ai）开源的一套「企业级 Agent 接入平台」，定位不是又一个聊天框或工作流画布，而是把企业里已经存在的 ERP / CRM / OA / HR / 财务 / 数据库 / IM 全部接进同一个 Agent 核心。官方 README 的原话是 "One brain. Every system. Global SaaS × China Stack."。

技术栈：后端 Python 3.11+ / FastAPI / SQLAlchemy / Alembic / asyncio；前端 Next.js 14 + React 18 + Tailwind + shadcn/ui + React Flow v12；RAG 用 Jina AI（嵌入与检索）+ LanceDB + 混合检索 + reranker；部署用 Docker Compose；默认 SQLite（开发）/ PostgreSQL（生产），多 worker 时用 Redis 做中断广播。

它最独特的一点是数据库连接器覆盖了国产信创库：PostgreSQL、MySQL、Oracle、SQL Server 之外，还包括达梦 DM、人大金仓 KingbaseES、南大通用 GBase、瀚高 Highgo——这是多数海外 Agent 平台触及不到的一块。它的数据库连接器会自动做 schema 自省与 AI 辅助标注，再把每个 action 注册成 Agent 工具。

仓库在 GitHub 上约 1.6k stars，Python，许可证是 FIM One Source Available License（不是 OSI 开源，见下文坑位）。开发方是两家独立公司共用的 FIM 品牌：FIM Labs Pte. Ltd.（新加坡）与北京 FIM 网络科技有限公司（2013 年成立）。

二、解决什么问题

企业做 AI 落地的真实痛点通常不是"模型不够强"，而是系统之间不互通：

数据散在十几个系统里，跨系统查询要么写 SQL 硬连，要么让 IT 手工导出。
IM 平台被割裂：飞书、企微、钉钉各自为政，Agent 的结果送不到人眼前。
Agent 拿着生产库的写权限，出了问题没人敢放行。
审批这种"必须有人点头"的环节只能靠人肉在系统间转述。

FIM One 的解法是把连接器抽象成统一桥梁：不管对面是 SAP、自研合同系统还是飞书群，Agent 侧看到的是同一套工具。配合 Hook System（在 LLM 循环之外跑的确定性代码）把"每次敏感调用必须人工审批"从"提示词里写了一句话"变成"平台层面无法绕过"。

三种交付模式也是这个定位的体现： - Standalone：通用 AI 助手（搜索、代码、知识库问答），Portal 交付。 - Copilot：以 iframe / widget 嵌入宿主系统 UI（如财务 Copilot 嵌进 ERP）。 - Hub：中心编排层，跨系统统一入口，Portal 或 API 交付。

三、快速安装

方式 A：Docker（推荐）

git clone https://github.com/fim-ai/fim-one.git
cd fim-one

cp example.env .env
# 编辑 .env：至少设置 LLM_API_KEY（可选 LLM_BASE_URL / LLM_MODEL）

docker compose up --build -d

打开 http://localhost:3000 ，首次启动会引导创建管理员账号。日常运维：

docker compose up -d     # 启动
docker compose down      # 停止
docker compose logs -f   # 看日志

数据持久化在 Docker 命名卷（fim-data、fim-uploads）中，容器重启不丢。

方式 B：本地开发（带热重载）

前置：Python 3.11+、uv、Node.js 18+、pnpm。

git clone https://github.com/fim-ai/fim-one.git && cd fim-one
cp example.env .env      # 设置 LLM_API_KEY

uv sync --all-extras
cd frontend && pnpm install && cd ..

./start.sh dev   # Python --reload + Next.js HMR

启动脚本一览：

命令	启动内容	地址
`./start.sh`	Next.js + FastAPI	:3000（UI）+ :8000（API）
`./start.sh dev`	同上，带热重载	同上
`./start.sh dev:api`	仅 API（dev）	:8000/api
`./start.sh dev:ui`	仅前端（HMR）	:3000
`./start.sh api`	仅 FastAPI（无头）	:8000/api

模型接入

任何 OpenAI 兼容端点都行，填三个变量即可：

LLM_API_KEY=sk-your-key
# LLM_BASE_URL=https://api.openai.com/v1   # 默认
# LLM_MODEL=gpt-4o                         # 默认
JINA_API_KEY=jina_...                       # 解锁 web 搜索/抓取 + 完整 RAG

官方表格给出的组合：OpenAI（gpt-4o）、DeepSeek（https://api.deepseek.com/v1 + deepseek-chat）、Anthropic（https://api.anthropic.com/v1 + claude-sonnet-4-6）、Ollama 本地（http://localhost:11434/v1 + qwen2.5:14b）。Jina 的 Key 缺失时，web 工具与 RAG 管线整体不可用。

四、核心用法

4.1 两种执行范式，别选错

Agent（Chat）：LLM 动态决定下一步，ReAct 循环或 DAG 规划。适合探索型任务（"分析这季度数据并给建议"）。
Workflow：设计期固定 DAG，可视化编辑器拖拽节点。适合流程确定的场景（"每周一拉发票→合规检查→异常转人工"）。

文档明确说明方向性：Workflow 可以在任意步骤调用 Agent，Agent 不能直接调 Workflow。如果你发现自己在给 Agent 写极其具体的分步指令，那基本说明这段流程该做成 Workflow。

4.2 动态 DAG 规划

LLM 在运行时把目标拆成依赖图，无独立依赖的步骤用 asyncio 并行执行，失败自动重规划最多 3 轮。ReAct 是原子单元，DAG 是编排层——DAG 的每个步骤内部仍是一个 ReAct Agent。

4.3 Hook System：把"必须"变成"不能绕过"

三个挂载点：SessionStart（注入动态上下文，不能阻断）、PreToolUse（工具执行前，可 allow=False 阻断、可改写 tool_args）、PostToolUse（工具返回后，可改写 observation）。同点位的多个 Hook 按 priority 顺序执行，前一个改写的参数会传递给后一个。

官方给的契约示例：

class ReadOnlyGuard(PreToolUseHook):
    name = "readonly_guard"
    priority = 5                          # 数字越小越先执行

    def should_trigger(self, ctx: HookContext) -> bool:
        return ctx.tool_name.startswith("sql_")

    async def execute(self, ctx: HookContext) -> HookResult:
        if org_is_readonly(ctx.metadata["org_id"]):
            return HookResult(
                allow=False,
                error="Org is in read-only mode — write blocked.",
                side_effects=["readonly_guard: blocked sql write"],
            )
        return HookResult()               # 默认 allow=True

首个落地实现是 FeishuGateHook：把标了 requires_confirmation=True 的工具调用变成发到飞书群的审批卡片（Approve / Reject），工具调用真正挂起（轮询每 1.5s、上限 120s），待批状态写数据库，因此后端重启不丢审批。

4.4 三种接系统的路径

导入 OpenAPI spec；
AI 对话式构建（chat builder）；
直接接 MCP server。

所有 action 自动注册为 Agent 工具并注入认证信息，配合 progressive disclosure meta-tools，README 称可使全类型工具的 token 消耗下降 "80%+"。这个数字是仓库方自述，未见第三方基准——建议自行压测后再决定是否依赖。

4.5 生产部署要点

多 worker 需要 PostgreSQL + Redis：

WORKERS=4
REDIS_URL=redis://localhost:6379/0
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/fim_one

Nginx 反代只需暴露 3000，Next.js 自动代理 /api/*。代码执行沙箱（CODE_EXEC_BACKEND=docker）需要挂载 /var/run/docker.sock。

五、典型适用场景

跨系统取数与推送：查 CRM 逾期合同 → 交叉 ERP 回款 → 飞书通知财务，Hub 模式一句话搞定。
嵌入式助手：把"财务 Copilot"塞进 ERP 页面，连接金蝶数据库查报表并出分析。
受控的写操作：采购付款这类高风险动作走 FeishuGateHook 人工点确认后才真正执行。
信创环境：达梦 / 金仓 / GBase / 瀚高库直连，混合检索 + 行内 [N] 引用做知识库问答。
多租户 SaaS：JWT 鉴权 + 组织隔离 + 管理面板用量统计，但需注意许可限制（见下）。

六、坑与注意

下列坑点按"现象 / 影响 / 修复"三段式整理，全部来自官方 README 与 docs 原文。

坑 1：License 不是开源许可。 - 现象：README 末尾写明 "FIM One Source Available License. This is not an OSI-approved open source license." - 影响：允许内部使用、修改、保留许可分发、嵌入非竞争性应用；禁止多租户 SaaS、竞争性 Agent 平台、白标（去品牌）、移除品牌标识。想做二开对外提供 SaaS 需先开 issue 谈商业授权。 - 修复：内部使用直接拿源码；对外商业化前先向 FIM 申请授权，避免踩线。

坑 2：Cloudflare Tunnel 在中国大陆不可用。 - 现象：官方 quickstart 明确警告 Cloudflare Free/Pro/Business 在中国大陆无 PoP，流量绕海外边缘（通常美西），频繁 502 且高延迟；需 Cloudflare Enterprise + 中国网络（京东云合作）。 - 影响：面向大陆用户的自托管如果图省事用 Tunnel 建站，会表现为"偶发打不开"。 - 修复：大陆用户走 Nginx + 国内云厂商 SLB/备案域名，或改用 Cloudflare Enterprise 中国网络。

坑 3：Docker 模式没有热重载。 - 现象：quickstart 注明 Docker 模式不支持热重载，代码改动必须重建镜像。 - 影响：改一行 Python 就要 docker compose up --build -d，开发迭代被拖慢。 - 修复：开发用方式 B（./start.sh dev），生产再回 Docker。

坑 4：多 worker 用 SQLite 会丢写。 - 现象：官方注明 SQLite 是单写者、不支持并发写；WORKERS>1 必须配 PostgreSQL 与 Redis。 - 影响：照抄默认配置只把 WORKERS 调大，会出现并发下的写入丢失或锁冲突。 - 修复：WORKERS>1 时三项齐配——PostgreSQL DATABASE_URL、REDIS_URL、WORKERS；WORKERS=1 时 SQLite 足够。

坑 5：JINA_API_KEY 缺失会静默降级。 - 现象：Jina 同时负责 web 搜索/抓取与 RAG 全管线（嵌入+检索+rerank），Key 缺失时这些能力不可用。 - 影响：只配 LLM_API_KEY 能起服务，但知识库问答与联网能力表现为"不好用"或直接报错，容易误判为配置错了别的地方。 - 修复：需要 RAG/联网就必须配 Jina Key；纯本地库可配 Ollama（LLM_API_KEY=ollama）+ LLM_BASE_URL=http://localhost:11434/v1。

坑 6：工作流节点类型数量文档内自相矛盾。 - 现象：README 说可视化工作流编辑器有 "12 node types"，而 docs 的 execution-modes 页写 "26 node types"，节点清单（Agent/Connector/KB/LLM/HTTP/Code/Human Approval/Sub-Workflow）也对不上。 - 影响：按 12 或 26 去规划工作流会误判能力边界。 - 修复：以你自己那一份 commit 的前端节点注册表为准（未 clone 时以 docs 页面为准并标注版本），别照抄数字。

坑 7：模型名可能随 provider 漂移。 - 现象：文档默认 LLM_MODEL=gpt-4o、Anthropic 示例写 claude-sonnet-4-6，属文档快照，实际可用模型随 provider 变化。 - 影响：照抄模型名可能报 model not found。 - 修复：以 provider 控制台当前列表为准，配置后先用最小请求验证；仓库无 GitHub Release（/releases/latest 返回 404），版本只能看 commit / docs 路线图，部署时把 commit hash 记进变更记录。

坑 8：代码沙箱需要挂 Docker socket。 - 现象：CODE_EXEC_BACKEND=docker 要求挂载 /var/run/docker.sock。 - 影响：容器内执行代码时若无此挂载，Python/shell 工具类能力直接不可用；而一旦挂载，等于把宿主机 Docker 控制权交给应用进程。 - 修复：只在可信环境开；生产环境用完关闭或替换为更强的隔离运行时，注意沙箱逃逸风险面。

七、与同类对比

维度	FIM One	Dify	Coze / 扣子	自建 LangGraph
定位	企业系统统一接入层	通用 LLM 应用开发平台	托管式 Bot/插件平台	代码框架
部署	自托管 Docker，一套 compose 起	自托管（Docker Compose）	主要是 SaaS 托管	自己搭
中国信创数据库	支持（DM/金仓/GBase/瀚高）	有限	有限	需自己写 connector
确定性拦截	Hook System（LLM 循环外，必执行）	插件/工作流节点可拦，但弱	有限	自己写
IM 闭环	飞书已落地，Slack/Teams/企微/钉钉在 v0.9 路线图	有插件生态，偏 API 侧	平台内闭环	自建
许可	Source Available，禁多租户 SaaS / 白标	Apache-2.0 + 部分商业条款	平台条款	自定

相对 Dify：FIM One 更"沉"——它假设你已有 ERP/CRM/数据库，目标是接管这些系统；Dify 更偏"从零搭应用"。相对自建 LangGraph：FIM One 给你现成的审批 Hook、连接器、多租户、IM 桥，但你被它的许可和架构绑住。相对 Coze：FIM One 可私有化部署、数据不出内网，代价是运维复杂度更高。

八、一句话推荐结论

推荐：如果你的组织正处于"系统多、国产库多、需要写操作人工放行"的状态，FIM One 是目前少见的把信创数据库、Hook 级审批、IM 闭环三件事做进同一套自托管产品的项目，值得投入 1~2 天做 POC（Docker 起一套 → 接一个只读库 → 跑一次 DAG → 试一次 FeishuGateHook 审批流）；不推荐给"要开源许可证做二开分发"或"要做多租户 SaaS"的团队，许可边界会直接卡住商业路径。

资料来源与核验状态

GitHub README（https://github.com/fim-ai/fim-one，已 fetch，2026-10-29）
官方文档 quickstart（https://docs.one.fim.ai/quickstart，已 fetch，2026-10-29；docs.fim.ai 会 302 到 docs.one.fim.ai）
官方文档 execution-modes（https://docs.one.fim.ai/concepts/execution-modes.md，已 fetch）
官方文档 hook-system（https://docs.one.fim.ai/architecture/hook-system.md，已 fetch，节选）
GitHub API /releases/latest（返回 404，无正式 Release）

不确定/待核： - progressive disclosure meta-tools "token 消耗下降 80%+" 为仓库方自述，无第三方基准。 - 工作流节点数 12（README）与 26（docs）不一致，未 clone 核对源码。 - 未标注具体 release 版本（仓库无 Release tag），功能描述对应 master 分支当前状态。 - Hook 审批轮询参数（1.5s / 120s）取自 hook-system 文档时序图描述。 - claude-sonnet-4-6 等模型名为文档快照，实际可用性未逐一验证。