貢献する

​

セットアップ

git clone https://github.com/fim-ai/fim-one.git && cd fim-one
cp example.env .env                        # LLM_API_KEY is optional for contributors
uv sync --all-extras                       # Python dependencies
cd frontend && pnpm install && cd ..       # frontend dependencies
bash scripts/setup-hooks.sh                # pre-commit hooks (required)

uv run pytest tests/ -x -q                # tests
uv run mypy src/fim_one/                   # type check
uv run ruff check src/                     # lint
cd frontend && pnpm build && cd ..         # frontend build

​

型安全性

• すべてのパブリック関数に型ヒントが必須です。
• # type: ignore は import-untyped（スタブのないサードパーティライブラリ）を除いて使用しないでください。
• 前方参照には 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規約

​

Pre-commit hook pipeline

​

i18n

• frontend/messages/en/{namespace}.json — UI文字列
• docs/*.mdx（ロケールサブディレクトリではなくルートレベル）— ドキュメント
• README.md — プロジェクトREADME

1. ローカルプリコミットフック — .envでLLM_API_KEYが設定されている場合に実行されます。翻訳はプッシュ前に行われるため、出力をプレビューできます。
2. CIフォールバック — ローカルフックにキーがなくスキップされた場合、.github/workflows/i18n-sync.ymlはマージ後にmasterで翻訳し、結果を自動コミットします。

​

データベースマイグレーション

• 新しい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を実行して適用してください。

​

クイックリファレンス

# Development
./start.sh dev                            # hot reload (Python + Next.js HMR)
./start.sh dev:api                        # API only, dev mode (hot reload)
./start.sh dev:ui                         # Frontend only, dev mode (HMR)
./start.sh api                            # FastAPI only (headless)

# Quality checks
uv run pytest tests/ -x -q               # tests (stop on first failure)
uv run pytest --cov=fim_one              # tests with coverage
uv run mypy src/fim_one/                  # type check
uv run ruff check src/                    # lint

# i18n
uv run scripts/translate.py --all         # force full retranslation

# Database
uv run alembic upgrade head               # apply migrations
uv run alembic revision -m "description"  # create new migration