ArkorAlpha
English

プロジェクト構成

Arkor がコードを置く場所、そして .arkor/ と ~/.arkor/ に何が入っているか。

生成された Arkor プロジェクトはこんな形をしています:

my-arkor-app/
├── src/arkor/
│   ├── index.ts        # createArkor({ trainer })
│   └── trainer.ts      # createTrainer({ ... })
├── arkor.config.ts
├── AGENTS.md           # AI コーディングエージェント向けの指示（create-arkor / arkor init の --no-agents-md で無効化）
├── CLAUDE.md           # 生成時のデフォルト内容: @AGENTS.md の 1 行再エクスポート
├── .arkor/             # プロジェクトごとの状態（gitignore 済み）
└── package.json        # dev / build / start

AI エージェント向け指示の正本は AGENTS.md です。CLAUDE.md を別に置いているのは、Claude Code がプロジェクトルートの CLAUDE.md を自動的に読み込む仕様で、かつ @<path> というディレクティブで他ファイルを取り込めるためです。scaffolder が CLAUDE.md を新規生成する場合のデフォルト内容は @AGENTS.md の 1 行のみで、Claude Code が AGENTS.md の中身を自動的に context に展開してくれるため、2 ファイルを二重管理せずに済みます。プロジェクト固有の CLAUDE.md が既に存在する場合、scaffolder はそれを上書きせず、既存の内容が引き続き有効です。

ソース以外に重要なのは 2 層の状態です: .arkor/（プロジェクトごと、リポジトリ内）と ~/.arkor/（ユーザーごと、ホームディレクトリー）。

src/arkor/

Arkor は src/arkor/index.ts を見てプロジェクトを認識します。このファイルから createArkor() の結果をエクスポートしてください。CLI は次の 3 つのエクスポート形を優先順位順に受け付けます:

  1. export const arkor = createArkor({ trainer })（推奨。テンプレートが生成する形）。
  2. export const trainer = createTrainer({ ... })（パワーユーザー向けショートカット。ラッパーが不要な場合）。
  3. デフォルトエクスポート（Arkor マニフェスト or Trainer のいずれか）。
// src/arkor/index.ts（推奨形）
import { createArkor } from "arkor";
import { trainer } from "./trainer";

export const arkor = createArkor({ trainer });

トレーナー本体は慣例で兄弟ファイルに置き、index.ts を薄く保ちます:

// src/arkor/trainer.ts
import { createTrainer } from "arkor";

export const trainer = createTrainer({
  name: "support-bot-v1",
  model: "unsloth/gemma-4-E4B-it",
  dataset: { type: "huggingface", name: "arkorlab/triage-demo" },
  lora: { r: 16, alpha: 16 },
  maxSteps: 100,
});

トレーナーをさらに分割しても構いません（ヘルパー、プロンプトビルダーなど）。正規パスにあるべきなのは index.ts だけです。

将来的に複数トレーナーを登録する場合は、ファイルを増やして createArkor に渡すことになります。今のところ API は単一の trainer だけを受け付けます。deploy と eval のスロットは型上で予約されていますが未実装です。

arkor.config.ts

プロジェクト生成ツールはデフォルトで次の arkor.config.ts を生成します:

// arkor.config.ts
export default {};

現状はプレイスホルダーです。ランタイムはまだここからフィールドを読み取りません。学習のデフォルト値（maxSteps、learningRate、lora など）はすべて Trainer 自体に持たせるので、プロジェクトレベルではなくトレーナーごとにコントロールできます。削除する理由がない限り、ファイルはそのままにしておいてください。

.arkor/（プロジェクトごと、gitignore 済み）

このディレクトリーはコミットしないでください。

  • .arkor/state.json。プロジェクトのルーティング: orgSlug、projectSlug、projectId。これによってランタイムはローカルリポジトリをマネージドバックエンドのワークスペースにマップします。ファイルは ensureProjectState() が作成し、CLI や Studio がスコープを必要とする最初のアクション（学習の開始、ベースモデル推論、Studio の Endpoints ページからの初回 deployment 作成など）で走ります。純粋な read 経路（Endpoints / Jobs の一覧表示など）は意図的に初期化を起こさないので、新規チェックアウト直後に Studio を開いてもリモートにプロジェクトを副作用で作ったりせず、空一覧が表示されるだけです。匿名ワークスペースではこの初回 write 呼び出しで自動作成されます。OAuth ワークスペースの場合はランタイムがエラーを返します。今のところ arkor login も arkor init もこのファイルに値を書き込まないので、{ orgSlug, projectSlug, projectId } を手動で書いて作るのが現実的な方法です。一度作られた後は手で編集しないでください。
  • .arkor/build/index.mjs。arkor build の出力。src/arkor/index.ts を Node 22.22 ターゲットで esbuild した単一バンドルで、bare specifier は外部のままにしてあります。arkor start がこれを実行します。

~/.arkor/（ユーザーごと）

ホームディレクトリーにあり、そのユーザーのすべての Arkor プロジェクト間で共有されます。

  • ~/.arkor/credentials.json。認証状態。arkor login --oauth または対話的な arkor login のピッカーで OAuth (browser) を選んだ場合に書かれる Arkor Cloud OAuth トークンか、未ログインで初使用時に作られる匿名トークンのいずれか。ファイルは mode フィールドが "oauth" か "anon" でタグ付けされており、CLI はどのモードにいるかを把握します。arkor login はこのファイルだけを書きます。.arkor/state.json は 作成しません。
  • ~/.arkor/studio-token（一時的）。arkor dev が起動ごとに書く CSRF トークン（モード 0600）。Studio が CLI のローカルサーバーへの呼び出しを認可するのに使います。arkor dev 起動のたびにローテートされます。

arkor logout は確認後（または --force 指定時）に credentials.json を削除します。匿名認証情報が入っている場合、そのファイルを削除すると、バックアップしていない限り同じ匿名 ID には戻れません。Studio トークンはプロセス終了時にベストエフォートで削除され（arkor dev がクラッシュすると残る場合あり）、次回起動時にローテートされます。

CLI が探すもの

  • arkor dev は Studio の Web サーバーを 127.0.0.1:4000 で起動し、~/.arkor/studio-token を書きます。src/arkor/ をファイル監視はしません。Studio の /api/manifest エンドポイントは確かに runBuild を呼び、bundle の content-addressed コピー経由で再 import します（無編集の再読込は Node のモジュールキャッシュを再利用し、編集はキャッシュをバストします）が、それは Studio UI が fetch したときだけです（現状は Run training ページのマウント時）。同じページに留まったまま学習を複数回実行すると、ビルド成果物は再利用されます。編集した後は Run training ページをリロード（あるいはターミナルから arkor build）して変更を取り込んでください。arkor dev は単独で .arkor/state.json を書きません。
  • arkor build は src/arkor/index.ts（または渡したエントリー）を読んで .arkor/build/index.mjs を書きます。Studio の dev ループの外側で直接呼ぶ必要があるのは CI や、スクリプトから arkor start の直前に走らせる場合などです。
  • arkor start はランナー経由でエントリーを解決し、.arkor/build/index.mjs がない、もしくは明示的なエントリーを渡したときはリビルドして実行します（これが trainer.start() と trainer.wait() を呼びます）。Studio から学習をトリガーすると内部的に arkor start がサブプロセスとして起動されます。

状態がどこに置かれているかを把握しておくと CLI の挙動が予測しやすくなります。何かおかしいと感じたら、サポートに頼る前に .arkor/state.json と ~/.arkor/credentials.json を覗いてみてください。