aigo-builder

AI GO Custom App ビルダー

この Skill は、AI エージェントによる AI GO Custom App の開発を支援します。Antigravity／Claude Code／Cursor に対応しています。

設計理念

AI GO Custom App は TypeScript（フロントエンド）+ Python（バックエンド） の厳選された言語構成を採用しています。 エラー率の低さ、静的型安全性、LLM による生成の最適化などの特長があり、AI コーディング初心者や非技術者が信頼性の高い社内システムを開発するのに最適です。

データアクセスはすべて API 経由で統一し、データベースに直接接続しません。非技術者の AI コーダーが類似したテーブルやフィールドを重複して作成するのを防ぐためです。 AI GO では、中小企業に共通するデータベース構造（デフォルトテーブル）をあらかじめ定義すると同時に、独自テーブルを作成して拡張できる柔軟性も備えています。

詳細は references/custom-app-dev-guide.md §21「アーキテクチャ設計理念」を参照してください。 用語を確認するには、まず CONTEXT.md を読んでください——テーブルはデフォルトテーブル／独自テーブルの 2 種類のみです。 「CustomObject / Data Reference / 拡張フィールド / app_domain」は仕組みを表す用語であり、3 種類目のテーブルではありません。 6 つの用語は混同しやすく、混同するとコードを誤って記述してしまいます。（旧ドキュメントの「SaaS テーブル」＝デフォルトテーブル。現在は使用していません）

Phase -1：Skill の自動更新（トリガーされるたびに実行し、新版が見つかった場合は強制同期）

SessionStart hook がインストール済みの場合（README の「最新状態を維持する」を参照）、このフェーズは自動的にスキップされます（間引き）。 重複して実行する必要はありません。

python scripts/check_update.py     # macOS / Linux 用 python3

• 依存関係ゼロ、uv は使用しません——標準ライブラリで実装されているため、どのプロジェクトからでも直接実行できます。
• スクリプトは確認を求めず、自動で処理します：リモートの VERSION がローカルより新しい場合、スクリプトはローカルに登録済みのすべてのインストールを、リモートの main に強制同期します——git でインストールした場合は fetch + reset --hard + clean を実行し、コピー形式でインストールした場合（skills CLI）は main.zip をダウンロードしてミラーで上書きします。ローカルの変更、分岐した commit、追加されたファイルはすべてリモートの内容に置き換わります。ユーザーに確認せず、返答も待ちません。ユーザーに代わって「更新するかどうか」を判断する必要はなく、判断してはいけません。
• 出力がない = 問題なし：すでに最新版の場合、オフラインの場合、または同じバージョンで過去 3 時間以内に一度失敗している場合は、何も出力せず終了し、そのまま Phase 0 に進みます。（間引きの対象はネットワーク取得と失敗時の再試行のみです。バージョン比較は毎回行うため、ローカルに複数のインストールがある場合はリモートキャッシュを共有し、どれか 1 つでも古ければ検出できます。）
• **出力がある = 同期済み（または同期失敗）**です。各行に従って処理してください。
  • 「同期済み」→ 直ちに SKILL.md と関連する references/ を再読込し、このターンから新版の指示を有効にしてください。バージョンの差と変更概要をユーザーに知らせてください（通知であり、確認ではありません——更新は完了済みで、拒否する選択肢はありません）。
  • 「失敗」→ 失敗の原因と、スクリプトが出力した手動コマンドをユーザーに伝え、対応が終わってから続行してください。同時に「破壊的変更」の警告がある場合（--json が "breaking": true）、この種のバージョンでは旧版のままだと失敗し、エラーメッセージから本当の原因を特定できないことがよくあります（例：1.7.0 のテナント URL ルールでは、パスワード誤りとまったく同じ 401 が発生します）——「対応しない場合に何が起こるか」を明確にユーザーに伝えてください。関連するエラーが発生した場合は、まずバージョンの差を疑い、他の原因を深く調べるのは後にしてください。
  • 「開発用コピー、スキップ」→ そのコピーは Skill を改修中の作業領域です（ローカルのバージョンがリモートより新しい、または git が main／master ブランチにない）。インストールではないため、対応も言及も不要です。
• 登録簿に記録されるのは、1.17.0+ のチェックを実行したインストールのみです——ユーザーが、別のプロジェクトにもこの Skill をインストールしたのに同期されていないと言った場合、そのプロジェクトで一度 Skill をトリガーすれば登録され、次回から一緒に同期されると伝えてください。
• 回避は禁止です：ローカルの変更を維持するためにこのフェーズをスキップしたり、--check-only を使ったり、そのようにユーザーに勧めたりしてはいけません。Skill の内容を変更する場合は、リポジトリの PR を通してください。ローカルにインストールされたコピーは、リモートの main のミラーでなければなりません。

元の意図による振り分け（作業を始める前に判定）

作業を始める前に、ユーザーの意図がどの種類かを見極めてください。3 つの経路では、最初に行うことがまったく異なります。アプリを作る場合（最初の 2 行）は、まずこのプロジェクトが本番環境に入っているかを判定してください（実際のユーザーが利用中、または失ってはならない本番データがあるか）。まだの場合（新規、またはコードはあるが未公開）→ まず Custom App で実現できるか確認します。すでに本番環境にあり、既存コードを移行する場合 → Hosted App に案内します。判定基準と例外については references/product-line-decision.md §0 を参照してください。ゼロから作るものは未稼働とみなし、既存システムがあり判断がつかない場合はユーザーに確認します。リポジトリから推測してはいけません。

意図	進め方
新しい App を開発（ゼロから新機能を作る）	メインフローに進みます（Phase 0 →）。ただし、app を作成する前に Phase 1.5 §1.0 の要件整理を必ず完了してください（4 つの質問＋Custom App の対応範囲の確認。移行経路の §2.0 と対称です）——ユーザーが最初に述べた一言は課題であって、要件ではありません。製品ラインの判定（Custom／Hosted／ハイブリッド）と権限アーキテクチャ（誰が作成できるか、どのロールを割り当てるか）は、Phase 1.5 の確定後に app を作成してください
既存 App を移行（既存のシステム／repo／DB を AI GO に移す）	まず references/migration-workflow.md を読み、§2.0 のスタック整理から始めてください（アーキテクトの視点で、まずフロントエンド／バックエンド／データの構造を整理し、その後に製品ラインを振り分けます）。その後でメインフローに戻ります。Hosted App と判定した場合は、メインフローを references/hosted-migration-runbook.md（整理 → テスト → 切り替え → 廃止）に従って進めてください
アプリを開発せず、データを操作（権限のあるデータの参照、変更、一括処理、エクスポート）	references/data-operations.md の短いフローに従います：aigo_auth.py status → aigo_data.py me → perm-check → 対象ファイルの §4 を参照 → call／export。Phase 0 の VFS レビューには進まず、app も作成せず、proxy も使用しません——ログインユーザー本人の token と権限を使います。書き込み前に、対象ファイルの §3.5 にある書き込みゲートを必ず通過してください——この経路では、本番データの唯一のコピーに対して操作します。サンドボックスも復元手段もありません
アプリを開発せず、メンバー／ロールを管理（一括招待、リンク作成、ロールの有効化、権限変更、app ロールの許可リスト設定）	references/member-admin.md に従います（§2 エンドポイント、§4 招待フロー、§5 ロール CRUD）：ログインユーザー本人の JWT を使います。app は作成せず、/open/* も使用しません。書き込みには同様に data-operations.md §3.5 のゲートを通過してください（招待とロール変更はいずれも取り消せない本番データの操作です）

データ操作の意図を示す手がかり：画面、機能、app について言及せず、「確認してほしい／一括変更したい／エクスポートしたい／データを投入したい」といった要望を出している場合、または「自分にあるテーブルを参照する権限があるか」と尋ねた場合です。この経路の権限とは、プラットフォームのインターフェース上でユーザーに付与されている権限です。デフォルトテーブルはモジュールロール（sale.read など）に従い、独自テーブルには builder.access が必要です。操作を始める前にユーザーに明確に説明し、書き込み前には必ずユーザーの確認を得てください。

移行の意図を示す手がかり（次のいずれかがあれば、ユーザーが自分から「移行」と言うのを待たず、積極的に確認してください）： 既存システム、既存の Web サイト、特定の repo、Supabase／Google Sheet／MySQL などのデータソース、「こちらに移す」「移行する」「AI GO に切り替える」などの言葉が出た場合、または Phase 0 で作業ディレクトリが AI GO の構造ではない完全なプロジェクトだと判明した場合です。移行と判定した後、複数システム（≥2 個）がある場合は、Phase 1.25 の全体整理も追加してください。

Phase 0：既存コードのレビュー（★ 必須手順）

開発作業を始めるたびに、必ず最初にこの手順を実行してください。

9 つのステップ（★ 全手順と各ステップのエンドポイント、レポート内容 → references/review-workflow.md）

uv run --project scripts python scripts/aigo_auth.py status   # 1. 找工作區、定目標
# 2. get_token() 自動取 JWT——★ 不要向用戶要密碼、不代填、不放進指令列
# 3-5. review_app() 一次做完：取 VFS → 檔案清單與 [SDK]/[INJ] 標記 → 路由與頁面 → legacy 偵測
#      → builder.access 破口偵測 → webhook 宣告 → Data Reference 盤點 → CSS 相容性

省略できない 3 つの確認項目（省略すると、問題に後から気づいてやり直すことになります）：

確認項目	理由	確認方法
テナントに既存の独自テーブルがあるか（★ 必須）	独自テーブルはテナント単位であり、VFS には含まれません——2 つの app がそれぞれ「顧客」テーブルを作成すると、データが 2 つに分裂します	GET /data-center/tables。あわせて命名を確認します（^tbl(_\d+)?$ などの仮の名前、ルール 18.5）。確認のみで、変更はしません
既存のスケジュール	republish または action 名の変更により、スケジュールが自動的に一時停止されることがあります	GET /builder/apps/{app_id}/crons
外部呼び出しと Egress	古い code が動作していても、新しい slug が通るとは限りません。プラットフォームによるキー注入と raw httpx のどちらを使っていても、必ず変更してください	action 内にあるすべての ctx.http.call の slug と外部ドメインを抽出します

• Data Reference は必ず GET /api/v1/refs/apps/{app_id} を使用し、src/db.json を読まないでください（実際には常に {} です）
• ⚠️ 独自テーブルの一覧を取得できない場合は空の一覧を返してください——空の一覧は「テナントにテーブルがないため、新しいものを作成しても問題ない」という意味ではありません
• ステップ 9：既存の構造を完全に理解したことを確認してから、開発に進んでください

Phase 1：環境設定

三條硬規則（★ 不可違反；完整說明見 references/environment.md）

1. 所有 API 一律打租戶空間 https://[tenant].ai-go.app/*。apex https://ai-go.app 推不出租戶， ★ 實測回 401 帳號或密碼錯誤——與密碼真的打錯完全同形，會把你帶去查錯方向。 *.apps.ai-go.app 是 app 執行期網域，不是 API host
2. 憑證由用戶自己填：~/.aigo/.env（機器級）或 <工作區>/.aigo/.env（覆寫）。 agent 不得代填密碼、不得把 token 印出來、不得寫進 repo
3. 工作區不能放在 skill 安裝目錄裡——更新會整個資料夾重建，憑證與登錄表會被清光

最短設定路徑

uv run --project scripts python scripts/aigo_auth.py setup                 # 建 ~/.aigo/.env 範本（用戶自己填）
uv run --project scripts python scripts/aigo_auth.py setup-workspace <目錄>  # 建工作區 .aigo/config.json
uv run --project scripts python scripts/aigo_auth.py status                # 確認實際生效的租戶空間與憑證
uv run --project scripts python scripts/aigo_auth.py login                 # 驗證憑證（不印 token）
uv run --project scripts python scripts/aigo_auth.py app add <alias> --id <uuid>   # 登錄 app

• 三層模型：裝置（skill 一份）→ 工作區（一個租戶一個目錄，base_url 在 config.json）→ app（工作區的 apps 登錄表，多 app 未指定會報錯列出 alias、不猜）
• 新 app 用 API 建，不必走 UI：POST /api/v1/builder/apps，name + template_slug 必填； ★ access_mode 由模板決定、建立後不可改，且建 app 只在 Phase 1.5 計畫確認後 （starter-internal 是預設；starter-external 只在分配表明寫時用）→ custom-app-dev-guide.md §26
• 只用兩支 starter 建殼，不用業務模板的 slug 建 app：模板是素材——GET /templates/{slug}/preview 取回全碼抄回本地改造，表／引用／外部服務依效果繫結表自行 provision（references/template-workflow.md）
• config.json 欄位、base_url 的三層來源與優先序、登入 401 的排查 → references/environment.md
• Hosted App 用 aigo CLI 時：先過 hosted-apps.md §3.3 版本閘門（scripts/aigo_cli_check.py）； 既有 app 只部署 → 用戶放 Deploy Token；建新 app／session-only → 用戶自己 aigo login --workspace（§3.1）

Phase 1.25：多系統遷入盤點（條件觸發）

觸發條件：用戶有 2 個以上外部系統（各自帶 Supabase / Google Sheet / MySQL 等 DB）要遷入 AI GO； 僅遷入 1 個系統或純新建 App → 跳過，直接進 Phase 1.5（純新建從 §1.0 需求盤點起手）。 觸發時 → 讀 references/migration-workflow.md §1：在任何單一 App 開始 Phase 1.5 之前建立全局視圖， 避免各 App 各自為政導致資料架構混亂；產出的「遷入全景表」在後續各 App 的 Phase 1.5 持續參照。

Phase 1.5：需求盤點與實作計畫（★ 強制步驟）

在任何開發工作開始前（包含建立 app、從模板起手、既有 app 加新功能），必須先完成需求盤點、提出實作計畫 並獲得用戶確認。禁止跳過此步驟直接進入 Phase 2 寫 code；也禁止在 §1.0 盤點與計畫確認前 建立 app——模板＝access_mode，建立後不可改。

1.0 需求盤點 → 四問（★ 缺一不進 1.5）

用戶開場的一句話是題目不是需求。一輪問完四問，資訊不足就問、不猜； 已在對話中講過的不重問；遷入情景這四問由 migration-workflow.md §2.0 盤點推導，不另問。四問之前先確認專案有沒有進正式環境（product-line-decision.md §0）——已進、有既有程式要搬的改走遷入線，四問照上句由 §2.0 推導。

#	問什麼
一	誰在用——列出使用者群，以及有沒有不登入就要能看的頁
二	做什麼——功能清單、使用場景與流程、涉及哪些資料實體
三	對外面向——需不需要自有網域、SEO、匿名瀏覽整站
四	機制需求——逐條核 product-line-decision.md §2 的 Custom App 能力邊界表

另外順帶盤（餵計畫第 4.5–4.7 項）：第三方 API、外部 webhook、定時工作、檔案上傳。

產出「需求形狀結論」（照 resources/new_app_requirements_template.md 填）。 四問的理由、答不出時給的選項、結論格式 → references/planning.md §1.0。

1.0.5 模板盤點（★ 所有開發都做，含既有 app 的增量開發）

四問之後、計畫成形之前查模板目錄（GET /templates，分類看 slug 前綴的產業套組，不只看 category）， 結論三選一寫進計畫：(a) 可直接用／(b) 有近似的（寫明從哪支改、改什麼）→ 兩者都走「preview 取碼 → 拷問效果繫結 → starter 建殼 → 自行 provision」，產出效果繫結表；(c) 都不適用 → 寫一句理由， 仍讀最接近的一兩支。做法、端點與權限 → references/template-workflow.md（腳本 scripts/aigo_template.py）。

計畫內容必須包含（★ 逐項展開在 references/planning.md）

#	項目	SSOT
1	需求分析：功能清單、使用場景、使用者流程	§1.0 問題二
1.3	模板盤點結論（a／b／c）；a、b → 效果繫結表（每個非預設繫結＝改 ports 實作）	template-workflow.md §2、§4
1.5	產品線與模式判斷（結果不可逆）→ 產出 app 分配表	product-line-decision.md
1.7	授權架構選型（角色、access_role_ids、邀請）→ 產出 授權架構表	member-admin.md §1
2	功能群拆分（2 群以上不同目的才拆 app）	product-line-decision.md §7
3	資料架構雙軌分流 → 產出 資料承載表（每張自建表都要「已對照的預設表／不採用理由」）	custom-app-dev-guide.md §19、default-table-lookup.md
4	頁面與元件規劃、路由結構	—
4.5–4.7	外部 API（egress）、webhook、排程、檔案	event-triggers.md、custom-app-dev-guide.md §25
5	驗證方式與里程碑	verification-details.md

常駐（always_on）兩條線都要有結論，預設都是 false——Hosted 過 hosted-apps.md §3.0 三問； Custom 過 custom-app-dev-guide.md §28.1（答案幾乎一律是「關」，沒命中即時互動訊號不必問 owner）。

計画ゲート（★ 7項目、1つでも欠けたら Phase 2 に進めません）

1. 4つの質問への回答が揃っていない、または計画に「要件の形状に関する結論」「app 分配表」「認可アーキテクチャ表」「データ格納表」のいずれかがない → 完了とはみなしません
2. app 分配表のいずれかの行に常駐に関する結論がない → 完了とはみなしません（「開く」と書く場合は「理由 X；終了条件 Y」＋有料プランの確認が必要です）
3. データ格納表のいずれかの自作テーブルに「照合済みのデフォルトテーブル／採用しない理由」がない → 完了とはみなしません （issue #53：これがなかったため、46 テーブルの移行案件では初版で自作テーブルが 40 個と判定され、照合後は 13 個になりました）
4. テンプレートの棚卸しに関する結論（a／b／c）がない、または (c) に理由が書かれていない → 完了とはみなしません
5. 効果バインド表のいずれかの行の「実装アクション」に対応する項目が計画にない → 完了とはみなしません
6. ユーザーから明確に「同意」と返信されるまで Phase 2 に進みません。ユーザーが要件を変更した場合は、計画を更新して再確認します
7. 確認後に実施する固定アクション：app 分配表に従って app を作成（app を作成する唯一のタイミング）し、aigo_auth.py app add で登録、 app_domain を記録し、認可アーキテクチャ表に従ってロールを作成して招待を送信します（member-admin.md §3–§5。各手順で data-operations.md §3.5 の書き込みゲートを通過すること）。Hosted と判定したものは hosted-apps.md に引き継ぎます

各ゲート項目の理由と実際に起きた問題 → references/planning.md。

Phase 2：プロジェクトのスキャフォールディング

Phase 0 のレビュー結果に基づいて方針を決定します。

• VFS が空の場合：新しいプロジェクト構造を生成します

  • 単一ページ／複数ページは Phase 1.5 の計画の第 4 項にあるページ構成に従い、別途質問しません。計画に記載がなければ計画が不完全なため、1.5 に戻って補完します
  • 単一ページ：直接レンダリングし、Router は使用しません
  • 複数ページ：HashRouter + Sidebar ナビゲーション
  • scripts/aigo_scaffold.py の scaffold_new_project() を利用できます

• VFS に内容がある場合：aigo_scaffold.py の download_vfs_to_local() でローカルにダウンロードして追加開発し、既存のコードを保持します

• テンプレートから開始する場合（棚卸しの結論が a／b）：starter の空のひな形からデモ用 action と _template.json を先に削除します（削除しないと公開時に 409 EGRESS_NOT_READY が発生します）→ aigo_template.py preview でテンプレートのコードを別の参照ディレクトリに取得します → プロジェクトにコピーして改修します（デフォルトではないバインドは ports の実装に変更します）→ 効果バインド表に従ってプロビジョニングします（template-workflow.md §5）

Phase 3：開発ガイド

コア規則（厳守してください）

1. フレームワーク：React 18 + TypeScript
2. ルーティング：複数ページでは HashRouter を使用します（BrowserRouter は使用禁止）。単一ページでは Router を使用しなくてもかまいません
3. CSS：グローバル App.css を使用します。CSS Modules / Tailwind はサポートされていません
4. CSS 変数：:host, :root { } の二重セレクターを使用する必要があります
5. HTML リセット：html, :host { } の二重セレクターを使用する必要があります
6. エントリーポイント：src/main.tsx である必要があり、import "./App.css" を含める必要があります
7. Layout：最外層のコンテナーは必ず height: 100vh; overflow-y: auto にします
8. Runtime モジュール：react, react-dom, lucide-react, react-router-dom, react-hot-toast は Runtime が提供するため、自分でインストールしてはいけません
9. SDK の変更禁止：api.ts, db.ts, action.ts, data.json, db.json, actions.json
10. Server-Side Actions：Python で記述し、actions/ ディレクトリに配置して execute(ctx) 関数を定義します
11. Shadow DOM の制約：confirm() / alert() / prompt() は使用できません → React state または react-hot-toast を使用します
12. フロントエンド db.ts の db.update() バグ：payload を {"data": {...}} でラップする必要があります（直接 fetch し、SDK は経由しません）
    • ⚠️ 2026-09-01 より前に注入された db.ts は PUT を送信しますが、データプロキシが受け付けるのは PATCH のみです——update() は常に 405 を返し、更新は一度も反映されません（#1416 で SDK テンプレートを修正）。既存の app で src/db.ts がまだ method: 'PUT' のバージョンの場合は、プラットフォームの最新テンプレートに置き換える（Builder から再注入する）か、直接 fetch で PATCH を使用してください。405 を権限の問題として調査してはいけません
13. フロントエンド db.ts の db.insert() バグ：同様に {"data": {...}} でラップする必要があります
    • ⚠️ これはフロントエンドにのみ適用されます。Server Action の ctx.db.insert(table, data) が受け取るのはフラットな dictです。ラップするとフィルターで除外され、400 が返されます。自作テーブルの insert_row / update_row も同様にフラットな dict を受け取ります
14. 開発上の制約：App ID を取得したら、まず scripts/aigo_limits.py の get_limits(base_url, token, app_id) で対象プラットフォームの VFS、Action、egress の制限を照会し、応答を基準にします。404／503 または接続失敗の場合は不明とし、ドキュメントに記載された過去の数値から現在の上限を推定してはいけません。 ——単一ファイルの上限超過は引き続きスキップされるため、必ず skipped_files を確認してください。success: true を完全に取り込めたことの根拠にしてはいけません。 数値はプラットフォームの値を基準にします。references/custom-app-dev-guide.md §4 を参照してください
15. コード全体を提示する原則：VFS ファイルを更新するたびに、内容を 100% 完全に提示する必要があります。// ...省略 のようなプレースホルダーは禁止です
16. 動的 import はサポートされません：import() 構文はサポートされません（lazy loading は除きます。esbuild は code splitting をサポートします）
17. Node.js のネイティブモジュールはサポートされません：fs, path, crypto などは使用できません 規則 18–34（データ、イベント、権限、時刻、URL、レンダリング、UAT、権限取り消し）のクイックリファレンス——完全版は references/dev-rules.md にあります。 作業を始める前に項目ごとに確認してください。★ が付いた規則への違反は即時停止、⚠️ が付いた規則への違反はエラーにならず、誤った結果につながります：

#	規則	マーク
18	データ格納先：二系統への振り分け	★ 必須
18.5	自作テーブルの命名規則：実体名はすべて英語	★ 必須
19	app_domain ラベルの規則	★ 必須
20	Webhook／スケジュール action は冪等である必要があります	★ 必須
21	Webhook の宣言は公開後にのみ有効になります
22	スケジュールに関する4つの厳格な制限
23	プラットフォームのロール／権限を引き継ぎ、独自に作らないでください	★ 必須
24	デフォルトテーブルへの書き込みは承認によってブロックされる場合があります	★ 必須
25	テーブルに tenant_id がないからといって、保護されていないわけではありません	★ 必須
26	offset ページネーションでは、必ず一意キーでソートします	★ 必須；⚠️ サイレントエラー
27	ctx.erp.validate_picking の冪等性は伝票の state ではなく明細で判定します	★ 必須
28	ネイティブの TIMESTAMP／DATE は offset-naive の UTC です。解析前に必ず Z を付加します	★ 必須；⚠️ サイレントエラー
29	すべての API は必ずテナント空間 https://[tenant].ai-go.app/* 経由で呼び出します	★ 必須
30	データ画面では4つの状態（読み込み中／データあり／データなし／エラー）をすべて実装し、送信中はボタンをロックします。起動時には skeleton を表示します	★ 必須
31	Internal app のフロントエンドから自作テーブル SDK を直接呼び出すことは禁止です	★ 必須
32	データベースまたは storage を Hosted App に格納することは禁止です	★ 必須
33	本番公開するすべての app に「UAT の結論」が必要です	★ 必須
34	AI GO のログインを引き継ぎつつ、自社の認証バックエンドも維持する app では「即時の権限取り消し」が必須です	★ 必須

詳細な説明、判定基準、実測による裏付けは references/dev-rules.md（目次を含む）にあります。規則 18 の二系統への振り分け、18.5 の命名手順、23 のロール引き継ぎは原文を必ず読んでください。

Server-Side Action 撰寫（★ 四條硬規則；ctx 清單見 custom-app-dev-guide.md §7）

def execute(ctx):
    data = ctx.params.get("key", "default")          # webhook / cron 事件也走 ctx.params
    ctx.response.json({"result": data})

1. 對外呼叫一律走 ctx.http.call(<egress-slug>, <path>)——runner 是 default-deny egress， raw import httpx / requests / urllib.request 連不出去（實測 20 秒 timeout）。 ⚠️ 這些套件 import 得進來（語言級沙箱已拆，2026-09-13 實打）——擋的是網路層， 別把「能 import」當成能用
2. slug 必須先在 Builder 建同名「外部服務」並授權給本 app，否則連不出去。 這是設定問題，改 code 改不掉；服務被停用也一樣擋（發布 409 service_inactive）
3. 金鑰由 app 自帶：閘道只驗域名、不注入憑證（ADR 0010）——存 ctx.secrets， action 自組 Authorization header
4. ctx.db 沒有結構操作：執行期不能建表改欄，這是刻意的能力邊界
5. ★ 外部服務與金鑰：AI 可代設，先講清楚再動手：建立／授權外部服務、寫入 secrets 之前，用白話告訴用戶 連到哪個網域、會送出哪些資料、哪支 action 用，單獨取得同意（不併進計畫同意；網域或資料變了要重問）； 金鑰值由用戶填進 600 權限的本機檔、aigo_secrets.py 讀檔寫入，不在對話裡傳、不印出、不讀回。權限：外部服務 builder.access＋本 App 擁有者或 system.admin；金鑰 builder.access＋看得到該 app（dev-guide §25.2）。缺口不是 bug、不回報

逾時有兩道且原文同形：manifest timeout_ms（1000～120000，舊 app 要 republish 才換上新值） 與 egress 閘道的服務 timeout_ms（預設 10000、硬上限 30000）。走 ctx.http.call 的 action 提早被切是後者，不是 manifest 沒生效。閘道另有請求 8 MiB／回應 5 MiB／每分鐘 120 次上限 → custom-app-dev-guide.md §25.4。資料層 403 帶 reason／rule_id 是租戶資料存取規則擋的， 改 code 無解 → dev-guide §27。

前端呼叫 Action

import { runAction, downloadFile } from "../action";
const { data, file } = await runAction("my_action", { key: "value" });
if (file) downloadFile(file);

Phase 4：部署 + 自動驗證（★ 每次 code 變更後必須執行）

原則：每次 code 變更後，都必須完成「同步 → 編譯 → 驗證」循環。 只有通過驗證閘門，才可進入發布或繼續下一輪開發。 極小變更（如僅修改文字、CSS 微調）可跳過 Custom Data 和 Action 測試，但編譯驗證不可跳過。

4.1 標準部署流程

0. 定目標並印出來：app = resolve_app(root, alias) → print(app.describe()) → GET app 後 assert_remote_matches(app, info)。工作區有多個 app 而本次沒指定 → resolve_app 會報錯列出 alias，問用戶，不要猜。full_deploy() 自己也會印目標行
1. 同步 VFS：讀取本地檔案 → PATCH /api/v1/builder/apps/{id}/source/files
   • 腳本：scripts/aigo_sync.py 的 sync_to_cloud()
   • ★ 內建二次驗證：PATCH 後自動 GET 確認 vfs_version 遞增 + 檔案確實寫入
   • ★ PATCH 不刪檔：本機刪掉的 actions/*.py 留在遠端、發布後照樣可被呼叫（manifest 拿掉登記不會下架），所以遠端有本機沒有的 actions/ 檔時 sync 預設寫入前中止並列出——把清單給用戶確認，再用 full_deploy(..., on_remote_only="delete", delete_paths=[用戶確認過的路徑])／delete_remote_files()（下架）或 on_remote_only="keep"（保留）→ troubleshooting.md「刪掉的 action 還能呼叫」列 1.5. 語意檢查（★ 前端有實質修改時必跑）：uv run --project scripts python scripts/aigo_typecheck.py <專案目錄>
   • compile 走 esbuild，只轉譯不驗型別：TDZ、找不到名稱、重複宣告這類錯誤 compile 全綠、發布後 runtime 白畫面（堆疊只有 minified 名稱，troubleshooting.md 白畫面列）——這一步是發布前唯一抓得到的閘
   • 腳本只阻擋會炸 runtime 的語意錯誤（TS2448／2454／2451／2300／2304…）， 缺型別套件的噪音只列不擋；本機沒有 Node 會印提示並略過——此時要告知用戶 這道閘沒跑，或請用戶在 Builder AI 用 check_types 補跑（平台有此工具但無 REST 端點）
2. 編譯：POST /api/v1/compile/compile/{slug}?dev=true
   • 腳本：scripts/aigo_compile.py 的 compile_app()
   • 成功或失敗都讀 skipped_files 並告知用戶每個 path／UTF-8 bytes／reason；[] 才代表未略過，缺欄位或 null 代表舊服務或本次未編譯，不能當成完整納入。發布回應同樣檢查此欄位。
   • ⚠️ success: true 且 compile_errors: [] 只代表轉譯成功，不代表程式語意正確（見 1.5）
   • 要讓用戶在瀏覽器看草稿：internal 開 {tenant}.ai-go.app/runtime/version-test/{識別碼} （需 builder.access）；external 的測試網址還要 ?preview_token=（Builder 工具列「預覽」會自動帶）， 形狀表與識別碼規則見 references/platform-behaviors.md §6.2——不要自己拼
3. 編譯失敗：解析錯誤 → 嘗試自動修復 → 重新同步 → 重新編譯（最多 5 次）
4. 編譯成功 → 進入驗證閘門（Phase 4.2）

4.2 驗證閘門（Verification Gate）

每次編譯成功後，根據變更範圍自動決定需要執行的驗證項目：

變更範圍判斷規則

變更類型	影響範圍	需執行的驗證
CSS 微調（僅 App.css 變動）	極小	✅ Compile 產物
文案/UI 修改（僅 TSX 變動，無新 import）	小	✅ Compile 產物
元件新增/重構（新增 TSX、修改路由）	中	✅ Compile 產物 + ✅ Publish 一致性
Custom Data 相關（修改了使用 api.ts/db.ts 的程式碼）	中	✅ Compile 產物 + ✅ Custom Data CRUD
Server Action 變更（actions/*.py 修改）	中	✅ Compile 產物 + ✅ Server Action 呼叫
多個範圍同時變動	大	✅ 全部 4 項驗證
首次部署或架構變更	大	✅ 全部 4 項驗證

要實際執行這四項驗證 → references/verification-details.md §1 有每一項的完整檢查條目與函式簽名。

4.3 驗證後決策

驗證結果	下一步
✅ 全部通過	可進入發布（4.4）或繼續開發
❌ Compile 失敗	回到 Phase 3 修復程式碼
❌ CRUD/Action 失敗	檢查 API 使用方式、表結構、Action 邏輯
❌ Publish 一致性失敗	重新 sync → compile → publish

任何一項失敗 → 先查 references/troubleshooting.md 對症狀，再動手改。 ⚠️ CRUD 驗證打預設表時，回傳 approval_status: "pending" 或「需要簽核審批」例外 不算驗證失敗——那是租戶簽核流程攔截（核心規則 24），不要當成 bug 去改程式。

4.4 發布

只有通過驗證閘門後才可發布：

1. POST /api/v1/builder/apps/{id}/publish
   • 腳本：scripts/aigo_publish.py 的 publish_app()
   • ★ 內建二次驗證：POST 後自動 GET 確認 status == "published"
   • ★ POST 前內建 egress_preflight()：比對 _template.json 的 required_egress 宣告、actions/*.py 的 字面 ctx.http.call slug 與本 App 已授權的外部服務——起手式殘留的 openai 在這裡就會被指出來， 不用等 409（troubleshooting.md EGRESS_NOT_READY 列；起手式要清的兩個檔見 dev-guide §26.2）
   • 三個 query 參數預設都不帶，409 回來先讀 code 再決定（dev-guide §8 分流表）： confirm_removal=true 只在用戶確認要移除該 action；confirm_egress_gaps=true 只在確定用不到那個 slug；auto_rollback=true 是發布後自動編譯驗證、失敗退回上一版並回 422——要開得讓用戶知道會退版
2. 發布後執行 Publish 一致性驗證；發布後立刻呼叫 action 回 503 是 runner 冷啟動，等 Retry-After 再試，不是發布失敗（troubleshooting.md 503 列）

樂觀鎖

• GET App 時記錄 vfs_version
• PATCH 時帶入 expected_version
• 409 → 重新 GET → 合併 → 重試

自動修復策略

偵測問題	自動修復
:root { 無 :host	→ :host, :root {
html { 無 :host	→ html, :host {
BrowserRouter	→ HashRouter
缺少 import "./App.css"	→ 在 main.tsx 頂部加入

可使用 scripts/aigo_sync.py、aigo_compile.py、aigo_publish.py。

Phase 5：完整 E2E 驗證（里程碑驗證）

Phase 4 的驗證閘門每次迭代自動執行；Phase 5 是開發里程碑完成（功能全部完成、準備交付）時的完整驗證。 要執行時 → references/verification-details.md §2 有完整清單與呼叫範例。

驗證流程快速參照

每次 code 變更：
  sync → compile → ✅ Compile 產物驗證
                   └─ (若涉及 Data) → ✅ Custom Data CRUD
                   └─ (若涉及 Action) → ✅ Server Action 呼叫
                   └─ (若涉及路由/元件) → publish → ✅ Publish 一致性

里程碑交付：
  上述全部 + 角色白名單實測（用不在 `access_role_ids` 內的帳號開 app 應 404）+ 匿名存取（僅判進 external 的 app）
  + 常駐狀態對帳（dev-guide §28.1）：用 `GET /builder/apps` **列表**讀回 `always_on`＋`has_messaging_trigger`
    （Builder 線沒有 `GET /runtime-settings`），必須等於計畫那列的結論；寫「開」才在 publish 後
    `PATCH .../runtime-settings {"always_on": true}` 並確認回 `effective_mode: "always_on"`
  + 交付連結實開（照 `platform-behaviors.md` §6.2 組**正式版**網址，用非開發者帳號／external 使用者開一次；`verification-details.md` 第 8 項）
  + 資料畫面四態實看（規則 30；`custom-app-dev-guide.md` §30.5 清單、`verification-details.md` 第 10 項）
  + UAT 結論對帳（`dev-rules.md` 規則 33）：計畫寫「有」的，`uat-environment.md` §4 驗證表要全過；寫「無」的，理由與風險要在交付說明裡

Hosted App 線（不走 Phase 2–4）：
  任何 `aigo` 指令前 → ✅ hosted-apps.md §3.3 版本閘門（`aigo_cli_check.py` 非零＝瀏覽器登入不可用，先重裝；找不到 `aigo` 時連 token 部署也不行）
  deploy/redeploy → ✅ hosted-apps.md §3.4 部署後驗證閘門（含讀回 `always_on`＝§3.0 決策；未通過不得對外交付）

資料操作線（不開發 app）：
  寫入前 → ✅ data-operations.md §3.5 寫入閘門（估影響面 → 備份 → 試一筆 → 用戶確認）

錯誤處理

任何一步失敗、或收到非預期狀態碼 → 先查 references/troubleshooting.md，不要自行推測修法。 查無此症、或照表處理仍卡死 → 自動進入下方「問題回報」五步，不要反覆重試、不要繞道硬改。

狀態碼語義分野：403 權限（結構操作 datacenter.schema_write／system.admin 與記錄 builder.access 降級動作不同；body 帶 reason／rule_id 是租戶資料存取規則 → dev-guide §27）｜409 配額或衝突｜422 輸入不合法｜ 400 業務規則拒絕｜503 「app runner 暫時不可用」 三種成因同形：先問有沒有 publish （status: draft 重試不會好）→ 剛發布的冷啟動（等 Retry-After）→ body 帶 quota_hint 是租戶 運算配額（不是 code 問題，把原文轉給用戶）｜aigo login 瀏覽器登入 401「帳號或密碼錯誤」 先跑 aigo_cli_check.py 看版本，再看登入頁網址是不是租戶子網域，最後才查帳密（troubleshooting.md）。

★ Action 對外呼叫失敗時別急著改 code：先完整讀出 status 與 error message。 timeout／連不出去＝raw httpx 直連（改 ctx.http.call）或 slug 沒有同名外部服務／未授權； 401＝action 自己的 header 或 ctx.secrets 金鑰不對（閘道不注入也不剝除憑證）。 指向 Egress 或權限就立刻停止改程式——那是設定問題，改幾次結果都一樣。確認是外部服務未建立／ 停用／未授權或金鑰缺少（發布 409 gaps[].kind ∈ service_missing／service_inactive／unauthorized／ secret_missing，或呼叫期的 egress_service_not_found／egress_service_inactive／egress_not_authorized）→ 設定缺口，不是平台 bug、不回報：列出缺項，照 Action 硬規則 5 向用戶說明目的地與資料、取得同意後 由 AI 補上（停用的重新啟用，不要重建同名的），補完再驗證（custom-app-dev-guide.md §25.2、§25.3）。

問題回報（平台問題 → 開發團隊）

★ 預設平台必定正確；開發或使用失敗，預設是自己的操作有誤。不確定就不報。

只有一條管道：scripts/report_issue.py submit（開發團隊 Scrum Board 的卡），平台缺陷與文件缺口 都走這條，不用問用戶要發到哪；不要替用戶到 GitHub（含本 skill repo）開 issue。用戶或其他說明文件裡的 「意見卡」「回報卡」「開發團隊的卡」都是這條（references/issue-reporting.md 開頭）。

何時自動進入（任一成立，不必等用戶要求、不反覆重試、不繞道硬改）： troubleshooting.md 查無此症、照表處理仍卡死、實測與 references/ 明文不符、端點 5xx／流程被硬阻斷。 優先排除：egress／secrets 設定缺口（上段「錯誤處理」）不屬於「照表仍卡死」或「流程被硬阻斷」， 補設定即可、不進回報流程；只有設定寫入本身異常失敗、或設定完成後回讀／發布結果與設定矛盾才算。

五步固定：自動觸發 → 走完 references/pre-report-self-grill.md 六輪自審（每個分支都要有 指令＋輸出當證據）→ 判定（不是平台問題就直接修、前沿還有待查就不報）→ 主動問用戶要不要送 （給非技術語言的摘要，不得替用戶決定）→ 同意才 submit。

三個硬條件（缺一即拒收，CLI 會擋）：

1. 內容寫行為不寫解法——「情境 → 操作 → 結果 → 預期」四段，出現「建議改／根因是」等開藥方措辭拒收
2. --ruled-out：自審濃縮的已排除清單，每行一項、至少三項
3. --user-confirmed：代表第 4 步已問過用戶且用戶說了送——沒問過就帶是本節最嚴重的違規

指令、參數、附截圖、追蹤進度、preflight 查既有卡 → references/issue-reporting.md。

參考文件

檔案	內容
CONTEXT.md	★ 術語表——預設表／自建表兩大類＋四個機制詞（含稱謂對照與禁用詞：舊稱 SaaS 表與外部產品名都不出現）
references/dev-rules.md	Phase 3 規則 18–34 的完整版（資料雙軌分流、自建表命名、app_domain、冪等、排程限制、角色沿用、簽核攔截、分頁排序、時間、租戶網址、資料畫面四態與送出中、builder.access 破口、Hosted 不承載 DB 與外接庫的唯一例外、UAT 結論、即時撤權）——主檔只有速查表，動手前讀原文
references/planning.md	Phase 1.5 的完整版：§1.0 四問的理由與選項、計畫十二項逐項展開、閘門七條的理由與踩坑紀錄
references/template-workflow.md	Phase 1.5 §1.0.5 模板盤點與「模板當素材」動線：查詢端點與 slug 前綴分類、a／b／c 結論、preview 取碼與效果清單、效果繫結表、starter 建殼與自行 provision、端點權限表
references/environment.md	Phase 1 的完整版：租戶網址規則的推導與 401 同形成因、三層模型、config.json schema 2 與 base_url 三層來源、設定六步、憑證規則
references/review-workflow.md	Phase 0 的完整版：九步各自打哪個端點、Review 報告要列什麼、哪些情況標「必改」
references/custom-app-dev-guide.md	核心 API 規格與架構理念；§6.0 SDK 依模式分流表、§29 四條存取通道端點總表（internal／external／匿名／open）、§15.1 匿名存取的平台核可三態、§12 Storage 坑表、§27 租戶資料存取規則（Auth gate：403 帶 reason 的來源）、§28 冷啟動／常駐（always_on）＋§28.1 Custom 線常駐決策閘（預設關）
references/data-center.md	自建表完整規格（型別、配額、權限、SDK）＋ 延伸欄位（§10）
references/default-table-lookup.md	判「平台有沒有同語意實體」時（Phase 1.5 第 3 項、遷入 §2.4 每張表必查）：業務語言→預設表速查、表名前綴讀法、Meta 面↔引用面對照、必填欄與唯讀表、遷入常見誤判
references/event-triggers.md	Webhook 與 App 排程（冪等要求、宣告、限制）
references/product-line-decision.md	Phase 1.5 判產品線與模式時（兩條路共用 SSOT）：預設 Custom App 與偏離訊號、Custom App 能力邊界核對表、兩問四象限（登入者一律 internal）、混合方案分工（含 Hosted 當 Custom 後端）、不可逆前提、app 分配表
references/member-admin.md	Phase 1.5 第 1.7 項授權架構選型的 SSOT ＋ 成員／角色管理 playbook：內外人員共用帳號體系的立場、三問與授權架構表、邀請／角色端點與權限、access_role_ids（兩條線）、批次邀請流程與四個邊界、Hosted internal 身分取得（header＋members context）、既有系統使用者搬遷、403 解讀
references/migration-workflow.md	有現存系統要遷入時：stack 盤點（§2.0，最先做；四種 stack 形狀，含「BaaS 為後端、瀏覽器直連」；原雲端拓撲與本機／外部微服務、排程的落點）、產品線判斷的遷入輸入（§2.1）、專案解構、Schema 映射、使用者與登入的落點（§2.4.5）、資料遷移、切換準備（§2.6：外部登記項、寫死的正式資源）
references/hosted-migration-runbook.md	判走 Hosted App 的遷入案的主流程：先確認真正的正式站、七個階段與通過條件、常駐 PaaS 隱藏假設掃描、UAT 測試資料策略、功能測試順序（模板 resources/hosted_migration_test_plan_template.md）、切換當天步驟與回滾、觀察與舊站退場
references/uat-environment.md	規則 33 的做法：UAT 結論怎麼下、version-test 為何不算、鏡像拓撲、-uat 命名、獨立資料庫與憑證、clone Hosted 的正式設定窗口與可見度重設、egress／secrets／Open Proxy 引用、只補測試者、驗證表、維運與退場
references/verification-details.md	要執行驗證時：四項驗證的完整定義、Phase 5 里程碑
references/troubleshooting.md	出錯時：錯誤速查表
references/pre-report-self-grill.md	回報平台問題前（必走）：預設平台正確、六輪自審排除樹、送出條件、已排除清單
references/issue-reporting.md	回報平台問題時：BDD 撰寫規範、指令、進度追蹤
references/platform-behaviors.md	實測行為補遺：DB Proxy 分頁與筆數上限、custom_data 不可伺服器端過濾、TIMESTAMP 格式、seed 表唯讀、ctx.erp 白名單、app 執行期網址總表（§6.2：internal／external × 正式／測試）、深連結與「找不到此應用」三層（§6.2）、空渲染偵測、API 權限閘（app 軸；人軸見 dev-guide §27）
references/hosted-apps.md	Hosted App（「自訂 App」）產品線：與 Custom App 的邊界、應用形狀硬規則、部署 API、部署後驗證閘門（§3.4＝Phase 4.2 的等價物）、env 規則、錯誤碼對照——Phase 1.5 判斷走這條線或混合方案時讀
references/data-operations.md	資料操作模式（不開發 app）：四條使用者身分資料面與權限閘、寫入閘門（§3.5，正式資料不可逆）、模組 REST 慣例、匯出白名單、Meta 值域、出錯與回報出口（§7）——源頭意圖判成「資料操作」時讀