# 用 AI 快速開始

Source: https://gortexa.sheng.page/ai-quickstart/

Gortexa 能讓具備 terminal 與檔案權限的 coding agent 快速建立可執行的 contract-first API prototype：proto、gRPC、HTTP/JSON、MCP、validation 與 server wiring 一起產生。若只想把框架 package 當 library 引用（不建 scaffold 專案），見[以模組使用](https://gortexa.sheng.page/quickstart/#以模組使用不走-scaffold)。

**Prototype 不等於 production**
產生的 logic 是 in-memory stub；它不會自動完成持久化、租戶隔離、authorization、secret lifecycle、真實 readiness 或部署。能啟動的服務不代表可以上線。

## 使用前提

- agent 能在你的工作機執行 shell 並讀寫專案。
- 已安裝 Go 1.21 以上（作為 bootstrap；framework 會下載 Go 1.27.0）、Git、curl、OpenSSL 與 Perl，且可連到 GitHub 與 Go module proxy。
- shell 可以使用 `GOTOOLCHAIN=auto`，讓 Go 下載 framework 所需的 toolchain。
- 從空工作目錄開始。agent 不應覆寫既有專案、push、部署或提交 secret，除非你明確授權。

## 貼給 agent：可靠建立 prototype

這段 prompt 從**同一個已驗證的 release tag**建立 toolchain、CLI 與 project layout，避免 @latest CLI 與 floating main layout 漂移。它會記錄 checkout SHA，且不會在新 project 中執行 make bootstrap；工具鏈已在 framework checkout 安裝完成。

~~~text
請幫我建立一個「可執行 prototype」，不是 production service。若我尚未提供
SERVICE_NAME、GO_MODULE、API_DOMAIN/API_VERSION、ENTITY，先只問這四項。
不要覆寫既有資料夾、不要 git push、不要部署、不要提交或顯示任何 secret。
在同一個 shell session 依序執行下列步驟並回報每一步結果。
先執行 set -euo pipefail；任何步驟失敗都停止，不要猜測或跳過。

set -euo pipefail
WORKSPACE="$HOME/src"
SERVICE_NAME="myapp"
GO_MODULE="github.com/me/myapp"
API_DOMAIN="billing"
API_VERSION="v1"
ENTITY="Invoice"
FRAMEWORK_REF="v0.28.3"  # 只在驗證過較新 release 後才變更
FRAMEWORK="$WORKSPACE/gortexa-framework"
PROJECT="$WORKSPACE/$SERVICE_NAME"

1. mkdir -p "$WORKSPACE"
   git clone --depth 1 --branch "$FRAMEWORK_REF" https://github.com/yshengliao/gortexa.git "$FRAMEWORK"
   cd "$FRAMEWORK"
   export GOTOOLCHAIN=auto
   bash install.sh
   export PATH="$(go env GOPATH)/bin:$PATH"
   mkdir -p "$FRAMEWORK/bin"
   go build -o "$FRAMEWORK/bin/gortexa" ./cmd/gortexa
   export PATH="$FRAMEWORK/bin:$PATH"
   CLI="$FRAMEWORK/bin/gortexa"
   "$CLI" doctor
   FRAMEWORK_COMMIT="$(git rev-parse HEAD)"
   printf 'framework ref=%s commit=%s\n' "$FRAMEWORK_REF" "$FRAMEWORK_COMMIT"

2. "$CLI" create "$PROJECT" --module "$GO_MODULE" --repo "file://$FRAMEWORK" --ref "$FRAMEWORK_REF"
   cd "$PROJECT"
   確認 create 保留了會拒絕啟動的 placeholder（它不再寫入任何可用 secret）：
   grep -Fq 'jwt_secret: "dev-only-insecure-secret-change-me-please"' etc/config.yaml
   完整閱讀 .skills/ 下四個技能檔後再修改程式。
   不要在這個新 project 中跑 make bootstrap；沿用上一步通過 doctor 的工具鏈。

3. "$CLI" gen "$API_DOMAIN/$API_VERSION" "$ENTITY"
   執行 go build ./... && go test -race ./... && go vet ./...
   說明 generated logic 是 in-memory prototype stub，以及 production 必須替換的檔案。

4. 只為本機 prototype 產生短期 runtime secret。為了在單一 shell 正確清理 PID，
   直接啟動已產生的 server binary（"$CLI" run 是前景開發指令）：
   export GORTEXA_AUTH__JWT_SECRET="$(openssl rand -hex 32)"
   go build -o "$PROJECT/.gortexa-prototype-server" ./cmd/server
   "$PROJECT/.gortexa-prototype-server" >"$PROJECT/gortexa-prototype.log" 2>&1 &
   SERVER_PID=$!
   cleanup() { kill -TERM "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true; rm -f "$PROJECT/.gortexa-prototype-server" "$PROJECT/gortexa-prototype.log"; }
   trap cleanup EXIT INT TERM
   for _ in $(seq 1 60); do
     if curl -fsS http://127.0.0.1:8080/healthz >/dev/null 2>&1; then break; fi
     sleep 0.5
   done
   curl -fsS http://127.0.0.1:8080/healthz
   test "$(curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/v1/resources/x)" = 401
   curl -fsS -X POST localhost:8080/mcp -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   cleanup
   trap - EXIT INT TERM

5. 停在 prototype 驗證完成處。不要 git add 或 Docker build，直到我確認
   etc/config.yaml 仍是 placeholder、secret 已外部化，且資料層與 authorization 已完成。

規則：proto 是單一事實來源；改 proto 後執行 "$CLI" regen；不要手動編輯 gen/。
文件先讀 https://gortexa.sheng.page/llms.txt，再按需要讀相關頁面。
~~~

成功條件是 doctor、build、race test、vet 都通過，healthz 回 200，HTTP gateway 的未授權請求回 401，且 MCP tools/list 能看到剛產生的 tool。這只證明**開發骨架、HTTP auth surface 與 MCP discovery 可用**；它沒有完成 live gRPC E2E、資料模型或權限模型。

## 貼給 agent：規劃 production foundation

要上線時，先用這段 prompt 取得會改變設計的需求；它不讓 agent 猜 tenant、權限或資料保留規則。

~~~text
把目前的 Gortexa prototype 推進為 production foundation，但先不要寫 code。
請先確認：actor 與 tenant model、role/permission matrix、資料庫與 migration、
transaction/idempotency/pagination、cache/MQ retry/DLQ 語意、secret rotation、
TLS ingress/trusted proxy/rate limit、SLO/observability、replica/readiness、
rollback 與 acceptance tests。

資料 ownership 必須從已驗證的 principal/tenant 推導，不能信任 request body 的 owner。
收到答案後提出分階段計畫，不要保留 generated in-memory logic 作為 production implementation。
計畫至少包含：external secret injection、persistent repositories/migrations、
tenant-aware authorization、real readiness、cross-tenant negative tests、
integration/E2E/failure tests、non-root Docker runtime 與 TLS ingress 驗證。
每一階段完成後執行測試並回報剩餘風險。
~~~

詳見[部署](https://gortexa.sheng.page/deployment/)與[安全與邊界](https://gortexa.sheng.page/examples/security/)。

## skills 與文件入口

每個 gortexa create 專案都有 .skills/：

| 技能 | 能做什麼 | 不能取代什麼 |
| --- | --- | --- |
| bootstrapping-environment | 安裝與驗證 pinned 工具鏈 | release / production readiness |
| scaffolding-projects | 建立固定 project layout | 產品需求與版本升級策略 |
| generating-apis | proto、validation、AI annotations、logic stub、server wiring | persistence、authorization、業務規則 |
| proto-regen | 重新產生 stubs、gateway、OpenAPI、MCP 程式碼 | schema/資料遷移策略 |

在上面 prompt 的同一個 shell 中，`"$CLI" skills install` 可把 skills 接到 Claude Code、Codex、Copilot 與 Antigravity；agent 在 project 內直接讀 .skills/ 就足以遵循流程。

- [/llms.txt](https://gortexa.sheng.page/llms.txt)：站點索引；先讀它再選擇需要的頁面。
- [/llms-full.txt](https://gortexa.sheng.page/llms-full.txt)：完整英文文件；只在確實需要大量 context 時使用。

## 讓 agent 呼叫本機服務

服務本身是 MCP server。/mcp 會把 proto 中有 gortexa.ai.v1 annotations 的方法暴露為 tools；tools/call 會走 auth 與 validation，但 application authorization 仍必須由你的服務實作。

~~~bash
curl -X POST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
~~~

離線匯出 tool schema：

~~~bash
"$CLI" export --format=mcp
~~~

細節見 [MCP transport](https://gortexa.sheng.page/transports/mcp/).