企业官网建设流程全解析

FIM One 是一个可自托管、支持任意 LLM 的开源 Agent 平台，通过一个 agent core 把你已有的 ERP、CRM、数据库、IM 平台等所有系统连接起来。无论你是第一次参与开源项目，还是想深入一个真实的企业级 AI Agent 平台，这份 FIM One 贡献代码指南会带你完整走一遍：Pioneer Program 创始贡献者福利、开发环境搭建、开发规范与 PR 提交流程。

🏆 Pioneer Program：前 100 名贡献者获得永久荣誉

FIM One 相信早期贡献者值得被长久铭记。项目设有Pioneer Program，奖励最早参与的前 100 位贡献者：

哪些行为算作贡献？

• 一个被合并的 PR（bug 修复、文档、翻译、代码都可以）
• 一份带有清晰复现步骤的高质量 bug 报告
• 一次负责任的漏洞报告（安全渠道）
• 一份详细的 Field Test（实地测试）报告

项目采用 all-contributors 规范。你的贡献被接受后，在对应 Issue/PR 下评论即可：

@all-contributors please add @<你的用户名> for <贡献类型>

贡献类型包括：bug、security、test、code、doc、translation、ideas、userTesting。

🎯 什么贡献方向对 FIM One 最有价值？

这是一个单人开发者项目。FIM One 的架构理念是一个 agent core 连接所有业务系统：

CONTRIBUTING.md 按优先级列出了"最需要的贡献"：

1. Bug 挖掘（影响最大）：部署 FIM One 并真实使用它，报告哪里会坏。维护者特别需要：
   • Agent 推理的边界情况（ReAct 循环卡死、错误的工具调用、意图误解）
   • DAG 规划失败（生成坏的依赖图、不必要的重规划）
   • 连接器问题（API 认证失败、响应解析错误、超时边界）
   • 前端 bug（UI 错位、交互损坏、i18n、无障碍问题）
   • 并发 bug（多用户竞态、SSE 流式问题）
2. 安全评审：见下文安全报告章节
3. 真实使用反馈（Field Testing，见下文）
4. 代码贡献：欢迎 bug 修复与新功能；构建大型功能前先开 Issue 讨论，避免方向不符白费功夫

💡 新手入门：优先关注标记为good first issue的 Issue，专为新人准备。

DAG 规划是 FIM One 的核心能力之一，也是最容易出边界问题的地方：

🚀 FIM One 开发环境快速搭建：从 clone 到本地跑通

前置要求

一键搭建

git clone https://gitcode.com/gh_mirrors/fi/fim-one cd fim-one cp example.env .env # LLM_API_KEY 可选 uv sync --all-extras # 安装 Python 依赖（--all-extras 必须加） cd frontend && pnpm install && cd .. # 安装前端依赖 bash scripts/setup-hooks.sh # 安装 pre-commit 钩子（必装）

验证环境

uv run pytest tests/ -x -q # 运行测试 uv run ruff check src/ tests/ # Lint uv run mypy src/ # 类型检查 ./start.sh dev # 启动本地开发（Python + Next.js 热重载）

本地启动后访问localhost:3000（UI）与localhost:8000（API）。只改前端的话：

cd frontend pnpm dev # 启动开发服务器（HMR） pnpm build # 生产构建，提 PR 前必须通过

⚠️贡献前端/文档不需要 LLM API Key。如果.env里配置了LLM_API_KEY，pre-commit 钩子会在本地翻译，方便你预览中文等语言输出；没配置也没关系——钩子会静默跳过，PR 合并后由 CI 自动生成全部翻译。两种路径最终结果一致。

📁 FIM One 项目结构速览：改什么去哪里找

src/fim_one/ ├── core/ │ ├── agent/ # ReAct agent（推理 + 行动循环） │ ├── model/ # LLM 抽象（与供应商无关） │ ├── planner/ # DAG planner → executor → analyzer │ ├── memory/ # 会话记忆（窗口、摘要、DB） │ └── tools/ # 工具基类 + 连接器适配器 ├── web/ # FastAPI 后端（REST API） ├── rag/ # RAG 管线（检索、grounding） ├── db/ # 数据库模型（SQLAlchemy） └── migrations/ # Alembic 数据库迁移 frontend/ # Next.js 门户（shadcn/ui） ├── src/app/ # App Router 页面 ├── src/components/ # React 组件 └── messages/ # i18n 字符串（en/ 等） tests/ # pytest 测试套件 docs/ # Mintlify 文档

• 后端核心源码：src/fim_one/core/
• 测试套件：tests/
• 文档站源码：docs/

📐 FIM One 开发规范速查

写第一行代码之前，请先读 CLAUDE.md——它是本仓库代码风格的"官方规范"：commit 范围、前端 UI 规则（禁用原生confirm、只用 shadcn、focus-ring 约定、admin 表格下拉菜单模式）、两级错误反馈、脏状态保护、i18n 工作流、Alembic 双轨迁移（SQLite/PG）、用户删除文件清理、提交后的文档同步清单。虽然它最初是写给 AI 编程助手的，但每条规则同样适用于人类贡献者。

Python（后端）

• 所有公共函数必须有类型注解；I/O 密集操作用async def（async-first）
• Lint 用 Ruff（行长 100，规则集：E、F、I、N、UP、B、SIM、RUF）
• 每个新模块都要有对应的tests/test_*.py
• __init__.py只 re-export 公共 API
• mypy strict 模式全仓零错误，禁止# type: ignore糊弄类型

TypeScript（前端）

• i18n 强制：所有 UI 文案必须走next-intl，禁止硬编码字符串，只改messages/en/
• 禁用原生对话框：用 shadcn 的AlertDialog/Dialog/ Toast
• 导航用<Link>，不要用<button onClick={router.push()}>
• 错误反馈分两级：字段级错误内联提示，系统级错误toast.error()

通用

• 一个 PR 只解决一个关注点，不要过度设计
• 优先修改现有文件而不是新建文件
• 不要给你没改过的代码加注释

Pre-commit 钩子流水线（提交时自动运行）

scripts/hooks/pre-commit 会在每次git commit时按顺序执行：

任何一步失败提交即中止。另外，改动 agent 行为文件（系统提示词、ReAct 循环、内建工具）后，pre-commit 还会要求行为评估（uv run pytest evals/ -q）通过后才放行。

🌏 i18n 多语言规则：永远不要手改翻译文件

这是新手最容易踩的坑：

• 只编辑英文源文件：frontend/messages/en/{ns}.json、docs/*.mdx（根目录）、README.md
• 其他语言文件（messages/zh/、docs/zh/等）全部由 scripts/translate.py 从英文重新生成，pre-commit 钩子无条件拒绝手改提交
• 发现翻译错了？不要改语言文件，去改词表：scripts/translation-glossary.md 是全部翻译规则的唯一事实来源（例如Channel应译为"通道"而非"频道"）。流程：

# 1. 在 scripts/translation-glossary.md 中新增/修正规则 # 2. 重新生成受影响的语言文件 uv run scripts/translate.py --files <受影响的英文源文件> --force # 3. 词表修改与重新生成的文件一起提交

这样每个修正都会变成一条永久规则，同时作用于全部五个语言，不会有静默漂移。

📝 FIM One PR 提交完整流程：从分支到合并

分支命名

fix/issue-number # Bug 修复 security/what-fixed # 安全补丁 docs/what-changed # 文档 feat/short-description # 新功能 refactor/what-changed # 重构

Commit 信息

采用 Conventional Commits：type: description

示例：

fix: resolve DAG re-planning infinite loop (#123) feat: add Slack connector with OAuth2 support

提交要原子化：一个逻辑变更一个 commit，无关改动即使一起开发也要拆开；永远不要用--no-verify跳过钩子。

PR 提交前检查清单

• uv run ruff check src/ tests/通过
• uv run pytest通过
• cd frontend && pnpm build通过（有前端改动时）
• i18n 字符串只加在messages/en/（UI 文案有改动时）
• 新功能有对应测试
• PR 描述说清楚了what（改了什么）和why（为什么改）

五步 PR 流程

1. 从master创建功能分支
2. 原子化 commit 完成改动
3. 推送到你的 fork，向master发起 PR
4. 填写 PR 模板
5. 等待评审——维护者目标48 小时内响应

🐛 非代码贡献指南：Bug 报告、实地测试与安全报告

不写代码同样能拿创始贡献者徽章。

一份合格的 Bug 报告包含：环境（OS、Python 版本、LLM 供应商）、编号的最小复现步骤、期望 vs 实际行为、日志或截图、严重程度估计（崩溃 / 数据丢失 / 结果错误 / 外观问题）。加分项：附上 agent 推理轨迹、DAG 可视化截图、使用的模型名称。

Field Testing（实地测试）：在个人、团队或企业环境部署 FIM One 并用于真实任务，然后开一个带field-test标签的 Issue，按模板写明：环境（部署方式、LLM 供应商、规模）、用例、什么好用、什么不好用、发现的边界情况、改进建议。维护者明确表示：理解真实任务与失败模式比任何功能 PR 都更有价值。

安全报告：发现漏洞不要开公开 Issue！请通过私有渠道（GitHub Security Advisories）或邮件security@fim.ai提交。响应承诺：48 小时内确认、5 个工作日内完成评估。确认的漏洞报告者将列入 Security Hall of Fame 并计入 Pioneer Program。

⚖️ 许可证与注意事项

FIM One 采用Source Available License（源码可见许可证），不是OSI 批准的开源许可证——贡献前请先阅读 LICENSE。它允许内部使用、修改、保留许可条款分发，但限制多租户 SaaS、竞品 Agent 平台、白标化等。你的贡献提交即视为同意按该许可证授权。

📌 更多开发规范的精简版速查（类型安全、测试、代码风格、快速命令参考），见官方文档源文件 docs/contributing.mdx；完整贡献指南见 CONTRIBUTING.md。

Bug 报告、安全评审、实地测试故事，与代码一样有价值。现在就从good first issue开始，争取你的 Pioneer Program 席位吧！