管理 API

所有管理端點都需要 Authorization: Bearer <admin token>（Jenks 將它保存在 macOS 鑰匙圈中為 agent-env:JENKSGUO_ADMIN_TOKEN；工具會讀取環境變數 JENKSGUO_ADMIN_TOKEN）。 寫入會使用與建置相同的結構進行驗證，然後提交到 GitHub。CI 會將變更的條目翻譯為所有語言、重新建置並部署：main → jenksguo.xyz，dev → dev.jenksguo.xyz。

方法	路徑	工具
GET	/api/admin/whoami	—
POST	/api/admin/login · /api/admin/logout	—（主控台工作階段 Cookie）
GET	/api/admin/schema	admin_schema
GET	/api/admin/files	admin_list_files
GET	/api/admin/file	admin_read_file
POST	/api/admin/validate	admin_validate
PUT	/api/admin/file	admin_write_file
DELETE	/api/admin/file	admin_delete_file
POST	/api/admin/changes	admin_commit_changes
POST	/api/admin/ai-edit	admin_ai_edit
GET	/api/admin/deploys	admin_deploy_status
POST	/api/admin/promote	admin_promote

錯誤：401 unauthorized、403 forbidden_path（只有內容檔案可寫入）、422 invalid 搭配 errors[]、409/502 github_error、503 github_not_configured。

admin_schema — 內容結構

內容模型：條目欄位與規則、標籤、lenses、kinds、可寫入路徑、文件，以及編輯慣例。寫入前請先閱讀。

• MCP: admin_schema on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/schema (admin token)
• CLI: jenks admin schema

無參數。

curl -s "https://jenksguo.xyz/api/admin/schema" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

admin_list_files — 列出內容檔案

列出分支上的可編輯內容檔案（path、size、sha），可選擇限定於某個資料夾，例如 content/corpus/experiences。

• MCP: admin_list_files on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/files?dir=&branch= (admin token)
• CLI: jenks admin ls [dir]

參數	型別	必填	備註
dir	string	否	例如 content/corpus/projects（預設：所有內容）
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s "https://jenksguo.xyz/api/admin/files" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

admin_read_file — 讀取內容檔案

讀取內容檔案的原始 Markdown/JSON 來源（及其 sha）。傳入 path，或針對 entry、lens 或 skill 使用 slug。

• MCP: admin_read_file on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/file?path=&slug=&branch= (admin token)
• CLI: jenks admin get <slug|path>

參數	型別	必填	備註
path	string	否
slug	string	否
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s "https://jenksguo.xyz/api/admin/file" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

admin_validate — 驗證變更

在不提交的情況下，依內容結構驗證檔案內容。回傳問題清單（空清單 = 有效）。

• MCP: admin_validate on https://jenksguo.xyz/mcp/admin
• REST: POST /api/admin/validate (admin token)
• CLI: jenks admin validate <path> <file>

參數	型別	必填	備註
path	string	是
content	string	是

curl -s -X POST https://jenksguo.xyz/api/admin/validate \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>"}'

admin_write_file — 建立或更新內容檔案

驗證並提交單一內容檔案（建立或取代）。發佈會自動進行：CI 會將變更的條目重新翻譯為所有語言、重新建置並部署（main → jenksguo.xyz，dev → dev.jenksguo.xyz），需時數分鐘。

• MCP: admin_write_file on https://jenksguo.xyz/mcp/admin
• REST: PUT /api/admin/file (admin token)
• CLI: jenks admin put <path> <file> -m <message>

參數	型別	必填	備註
path	string	是
content	string	是
message	string	是	提交訊息
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s -X PUT https://jenksguo.xyz/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>","message":"<message>"}'

admin_delete_file — 刪除內容檔案

以提交訊息刪除單一內容檔案（例如移除一個條目）。Git 歷史可讓其被還原。

• MCP: admin_delete_file on https://jenksguo.xyz/mcp/admin
• REST: DELETE /api/admin/file?path=&message=&branch= (admin token)
• CLI: jenks admin rm <path> -m <message>

參數	型別	必填	備註
path	string	是
message	string	是
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s -X DELETE https://jenksguo.xyz/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","message":"<message>"}'

admin_commit_changes — 一次提交多個檔案

將多個檔案變更驗證並作為「一個提交」提交。每個變更為 {path, content} 或 {path, delete: true}。

• MCP: admin_commit_changes on https://jenksguo.xyz/mcp/admin
• REST: POST /api/admin/changes (admin token)
• CLI: jenks admin commit <changes.json> -m <message>

參數	型別	必填	備註
changes	array	是
message	string	是
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s -X POST https://jenksguo.xyz/api/admin/changes \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"changes":"<changes>","message":"<message>"}'

admin_ai_edit — 使用 AI 擬稿編輯

向網站的模型提出純英文指示，重寫單一內容檔案。回傳提案內容、差異與驗證問題。不會提交——請先審閱，再呼叫 admin_write_file。

• MCP: admin_ai_edit on https://jenksguo.xyz/mcp/admin
• REST: POST /api/admin/ai-edit (admin token)
• CLI: jenks admin ai-edit <slug|path> "<instruction>" [--apply]

參數	型別	必填	備註
path	string	否
slug	string	否
instruction	string	是
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。
content	string	否	選用的未儲存檔案文字作為擬稿來源（預設為已儲存的檔案）。

curl -s -X POST https://jenksguo.xyz/api/admin/ai-edit \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"instruction":"<instruction>"}'

admin_deploy_status — 部署狀態

近期的 CI 執行（translate → build → deploy），包含狀態、分支、提交與連結。

• MCP: admin_deploy_status on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/deploys?branch= (admin token)
• CLI: jenks admin deploys

參數	型別	必填	備註
branch	main · dev	否	main 發佈到 jenksguo.xyz；dev 在 dev.jenksguo.xyz 上預覽（預設 main）。

curl -s "https://jenksguo.xyz/api/admin/deploys" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

admin_promote — 將 dev 升級至正式環境

將 dev 分支合併到 main，將 dev.jenksguo.xyz 上預覽的一切發佈到 jenksguo.xyz。

• MCP: admin_promote on https://jenksguo.xyz/mcp/admin
• REST: POST /api/admin/promote (admin token)
• CLI: jenks admin promote

參數	型別	必填	備註
message	string	否

curl -s -X POST https://jenksguo.xyz/api/admin/promote \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'