设置
前置条件：Python 3.11+、uv、Node.js 18+、pnpm。LLM_API_KEY 仅在本地运行后端或在提交时预览自动翻译的区域设置输出时需要。没有密钥的贡献者仍然可以提交英文更改 — GitHub Actions 工作流在 PR 合并后在 master 上进行翻译。请参阅下面的 i18n。类型安全
mypy 严格模式已启用。整个代码库通过零错误检查，预提交钩子在每个暂存的.py 文件上运行 mypy，并进行完整的导入链检查。
规则：
- 所有公共函数都需要类型提示。
- 除了
import-untyped（没有存根的第三方库）外，不允许使用# type: ignore。 - 使用
from __future__ import annotations来处理前向引用。 - 修复实际类型——永远不要通过抑制错误来让 CI 通过。
测试
每个新模块必须有对应的测试文件。每个功能提交必须包含测试。
规则：
- 提交前所有现有测试必须通过：
uv run pytest tests/ -x -q。 - 测试不得依赖外部服务 — 使用
unittest.mock/AsyncMock模拟数据库、MCP 服务器、HTTP 端点和 LLM 调用。 - 运行带覆盖率的测试：
uv run pytest --cov=fim_one。
代码风格
- 异步优先。 对于 I/O 绑定操作使用
async def。用asyncio.to_thread()包装同步调用，而不是阻塞事件循环。 - 使用 Ruff 进行代码检查。
uv run ruff check src/— 行长度为 100 个字符。 - 最小化
__init__.py导出。 仅重新导出公共 API；保持内部符号私有。 - 包管理器。 Python 使用
uv，前端使用pnpm。永远不要使用pip或npm。
Git 约定
原子提交。 每次提交包含一个逻辑变更。即使是一起开发的无关变更也要分开提交。 提交信息格式：type: description
不要跳过钩子 使用
--no-verify。预提交管道的存在是为了在错误进入仓库之前捕获它们。
预提交钩子管道
钩子在每次提交时自动运行。它只处理与每个步骤相关的暂存文件——如果你只修改了Python文件，i18n步骤会被跳过，反之亦然。
如果任何步骤失败，提交将被中止。修复报告的错误并重试。
国际化
FIM One 支持 6 种语言环境（EN、ZH、JA、KO、DE、FR）。翻译完全自动化。 仅编辑英文源文件：frontend/messages/en/{namespace}.json— UI 字符串docs/*.mdx（根目录，不是语言环境子目录）— 文档README.md— 项目自述文件
messages/zh/、docs/zh/、README.zh.md 等）是自动生成的，预提交钩子无条件拒绝手动编辑这些文件的提交。要修复翻译错误，请编辑 scripts/translation-glossary.md——每个翻译规则的提示词注入单一信息源——然后使用 uv run scripts/translate.py --files <en-sources> --force 重新生成受影响的文件。每个词汇表修复都会永久应用于所有五种语言环境。
生成语言环境文件的两条路径：
- 本地预提交钩子 — 如果在
.env中设置了LLM_API_KEY，则运行。翻译在推送前进行，因此你可以预览输出。 - CI 备选方案 — 如果本地钩子没有密钥并跳过，
.github/workflows/i18n-sync.yml会在合并后在master上进行翻译，并自动提交结果。
messages/en/{ns}.json — 其他语言环境文件会在下次提交或合并后的 CI 上生成。
强制完全重新翻译： uv run scripts/translate.py --all（需要本地 LLM_API_KEY）。
数据库迁移
开发环境使用 SQLite，生产环境使用 PostgreSQL。一套 Alembic 迁移文件必须在两者上都能工作。 关键规则：- 每个新的 ORM 模型或列必须有一个迁移 — 永远不要依赖
metadata.create_all()。 - 所有迁移必须是幂等的 — 使用
fim_one.migrations.helpers中的辅助函数（table_exists、table_has_column、index_exists）。 - 布尔默认值：
server_default=sa.text("FALSE")/sa.text("TRUE")。永远不要使用"0"/"1"— PostgreSQL 拒绝为布尔列使用整数字面量。 - SQLite 无法执行
ALTER COLUMN— 对于列约束更改，使用op.batch_alter_table()。 - 编写迁移后，立即运行
uv run alembic upgrade head来应用它。