跳到內容
Gortexa

用 AI 快速開始

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

使用前提

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

貼給 agent：可靠建立 prototype

Section titled “貼給 agent：可靠建立 prototype”

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

請幫我建立一個「可執行 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.27.0"  # 只在驗證過較新 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 寫入的 JWT secret 還原成會拒絕啟動的 placeholder：
   perl -0pi -e 's/(jwt_secret:\s*")[^"]*(")/${1}dev-only-insecure-secret-change-me-please${2}/' etc/config.yaml
   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

Section titled “貼給 agent：規劃 production foundation”

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

把目前的 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 驗證。
每一階段完成後執行測試並回報剩餘風險。

詳見部署與安全與邊界。

skills 與文件入口

Section titled “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：站點索引；先讀它再選擇需要的頁面。
  • /llms-full.txt：完整英文文件；只在確實需要大量 context 時使用。

讓 agent 呼叫本機服務

Section titled “讓 agent 呼叫本機服務”

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

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

離線匯出 tool schema：

Terminal window
"$CLI" export --format=mcp

細節見 MCP transport.