文件 / reference

Admin API

已驗證的端點，透過經過驗證的 git 提交來編輯網站內容。

所有管理端點都需要一個「代理服務 Token」：Authorization: Bearer jgx_agt_…（CLI 會讀取環境變數 JENKSGUO_ADMIN_TOKEN）。Jenks 透過主控台 https://admin.jenksguo.xyz/admin 建立 Token → 使用 Google 登入（Cloudflare Access）後的 Access；每個 Token 具備名稱、作用範圍（content、media、publish；每個 Token 皆可讀取）、到期時間，且可撤銷。對 main 分支寫入也需要 publish。每次寫入與每次被拒的嘗試都會記錄在稽核日志。見 Give an AI agent access。寫入會用與建置相同的 Schema 驗證，之後提交至 GitHub。CI 會將變更的項目翻譯為所有語言、重新建置並部署：main → jenksguo.pages.dev 與 jenksguo.xyz，dev → dev.jenksguo.xyz。

方法	路徑	工具
GET · POST	`/api/admin/tokens`	—（僅人員：列出或建立代理 Token；SSO）
DELETE	`/api/admin/tokens/{id}`	—（僅人員：撤銷；SSO）
POST	`/api/admin/login` · `/api/admin/logout`	—（僅本機開發）
GET	`/api/admin/whoami`	`admin_whoami`
GET	`/api/admin/audit`	`admin_audit_log`
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/translation`	`admin_read_translation`
PUT	`/api/admin/translation`	`admin_write_translation`
GET	`/api/admin/copy`	`admin_read_copy`
PUT	`/api/admin/copy`	`admin_write_copy`
GET	`/api/admin/deploys`	`admin_deploy_status`
POST	`/api/admin/promote`	`admin_promote`
POST	`/api/admin/cv`	`admin_publish_cv`
GET	`/api/admin/media`	`admin_list_media`
POST	`/api/admin/media`	`admin_upload_media`
PATCH	`/api/admin/media`	`admin_update_media`
DELETE	`/api/admin/media`	`admin_delete_media`

錯誤：401 unauthorized · unknown_token · token_expired · token_revoked，403 missing_scope（含 needs[]）· sso_required · forbidden_path（只能寫入內容檔案），422 invalid（含 errors[]），409/502 github_error，503 github_not_configured。

`admin_whoami` — 我是誰

檢查你的憑證：你是誰（SSO 電子郵件或代理 Token 名稱）、你的作用範圍、Token 何時到期，以及是否已設定發佈（GitHub）。

MCP: admin_whoami on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/whoami（代理 Token）
作用範圍: read
CLI: jenks admin whoami

無參數。

curl -s "https://jenksguo.pages.dev/api/admin/whoami" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_audit_log` — 稽核日志

最近的管理動作，新的在前：誰（SSO 電子郵件或代理 Token）、做了什麼、哪些檔案、分支、主機與結果。代理 Token 只能看見自己的動作。

MCP: admin_audit_log on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/audit?limit=&token=（代理 Token）
作用範圍: read
CLI: jenks admin audit [--limit 50]

參數	型別	必填	說明
`limit`	integer	否
`token`	string	否	僅此代理 Token id（僅人員）

curl -s "https://jenksguo.pages.dev/api/admin/audit" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_schema` — 內容 Schema

內容模型：項目欄位與規則、標籤、鏡頭、種類、可寫入路徑、文件與編輯慣例。寫入前請先閱讀。

MCP: admin_schema on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/schema（代理 Token）
作用範圍: read
CLI: jenks admin schema

無參數。

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

`admin_list_files` — 列出內容檔案

列出某分支上可編輯的內容檔案（路徑、大小、sha），可選擇性地僅列出某資料夾，例如 content/corpus/experiences。

MCP: admin_list_files on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/files?dir=&branch=（代理 Token）
作用範圍: read
CLI: jenks admin ls [dir]

參數	型別	必填	說明
`dir`	string	否	例如 content/corpus/projects（預設：所有 content）
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

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

`admin_read_file` — 讀取內容檔案

讀取內容檔案的原始 Markdown/JSON 來源（含其 sha）。傳入 path，或針對項目、鏡頭或技能使用 slug。

MCP: admin_read_file on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/file?path=&slug=&branch=（代理 Token）
作用範圍: read
CLI: jenks admin get <slug|path>

參數	型別	必填	說明
`path`	string	否
`slug`	string	否
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

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

`admin_validate` — 驗證變更

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

MCP: admin_validate on https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/validate（代理 Token）
作用範圍: read
CLI: jenks admin validate <path> <file>

參數	型別	必填	說明
`path`	string	是
`content`	string	是

curl -s -X POST https://jenksguo.pages.dev/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.pages.dev 與 jenksguo.xyz，dev → dev.jenksguo.xyz），需數分鐘。

MCP: admin_write_file on https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/file（代理 Token）
作用範圍: content（main 分支另需 publish）
CLI: jenks admin put <path> <file> -m <message>

參數	型別	必填	說明
`path`	string	是
`content`	string	是
`message`	string	是	提交訊息
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X PUT https://jenksguo.pages.dev/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.pages.dev/mcp/admin
REST: DELETE /api/admin/file?path=&message=&branch=（代理 Token）
作用範圍: content（main 分支另需 publish）
CLI: jenks admin rm <path> -m <message>

參數	型別	必填	說明
`path`	string	是
`message`	string	是
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X DELETE https://jenksguo.pages.dev/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.pages.dev/mcp/admin
REST: POST /api/admin/changes（代理 Token）
作用範圍: content（main 分支另需 publish）
CLI: jenks admin commit <changes.json> -m <message>

參數	型別	必填	說明
`changes`	array	是
`message`	string	是
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X POST https://jenksguo.pages.dev/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.pages.dev/mcp/admin
REST: POST /api/admin/ai-edit（代理 Token）
作用範圍: content
CLI: jenks admin ai-edit <slug|path> "<instruction>" [--apply]

參數	型別	必填	說明
`path`	string	否
`slug`	string	否
`instruction`	string	是
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。
`content`	string	否	可選的未儲存檔案文字用以擬稿（預設：已儲存檔案）。

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

`admin_read_translation` — 讀取翻譯

以另一種語言讀取單一內容檔案：英文來源欄位、當前翻譯及其狀態（最新、過期、人工編修、缺失）。適用於 entries、lenses、CVs、arguments、point-of-view pages、credentials、talks 與 docs。語言：zh、zh-hant、ja、fr、es、eo。

MCP: admin_read_translation on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/translation?path=&slug=&locale=&branch=（代理 Token）
作用範圍: read
CLI: jenks admin tr get <slug|path> <locale>

參數	型別	必填	說明
`path`	string	否
`slug`	string	否
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s "https://jenksguo.pages.dev/api/admin/translation" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_translation` — 編輯翻譯

以另一種語言（zh、zh-hant、ja、fr、es、eo）撰寫單一內容檔案的文字——例如更好的中文摘要。僅提供要變更的欄位；請先用 admin_read_translation 讀取欄位名稱。Markdown 必須保留英文標題、程式碼區塊與連結。此編輯會被保留，直到英文變更；之後該語言會再次自動翻譯。英文為來源：請用 admin_write_file 變更英文。

MCP: admin_write_translation on https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/translation（代理 Token）
作用範圍: content（main 分支另需 publish）
CLI: jenks admin tr put <slug|path> <locale> <fields.json> -m <message>

參數	型別	必填	說明
`path`	string	否
`slug`	string	否
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`fields`	object	是	例如 {"summary": "…", "body": "## …"}
`message`	string	否	提交訊息
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X PUT https://jenksguo.pages.dev/api/admin/translation \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","fields":"<fields>"}'

`admin_read_copy` — 讀取站台介面文案

站台介面文字（單一語言）——選單、頁面標題、單行頁面介紹、Hero 標題、按鈕、SEO 描述——以 key → text 呈現，並附上英文（以及 zh-hant 時的中文）。可用前綴過濾，例如 hero 或 career。

MCP: admin_read_copy on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/copy?locale=&prefix=&branch=（代理 Token）
作用範圍: read
CLI: jenks admin copy get <locale> [prefix]

參數	型別	必填	說明
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`prefix`	string	否
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s "https://jenksguo.pages.dev/api/admin/copy" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_copy` — 編輯站台介面文案

變更單一語言的介面文字：values 為 key → text（"" 會移除你的編輯）。en 與 zh 是手寫來源：英文變更會自動翻譯成 ja、fr、es 與 eo——也請同時設定 zh。其他語言的編輯會被保留，直到其來源文字變更。請原封不動保留 {placeholders}。

MCP: admin_write_copy on https://jenksguo.pages.dev/mcp/admin
REST: PUT /api/admin/copy（代理 Token）
作用範圍: content（main 分支另需 publish）
CLI: jenks admin copy set <locale> <key> "<text>" -m <message>

參數	型別	必填	說明
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`values`	object	是	例如 {"hero.sub": "…"}
`message`	string	否
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X PUT https://jenksguo.pages.dev/api/admin/copy \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","values":"<values>"}'

`admin_deploy_status` — 部署狀態

最近的 CI 執行（翻譯 → 建置 → 部署），包含狀態、分支、提交與連結。

MCP: admin_deploy_status on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/deploys?branch=（代理 Token）
作用範圍: read
CLI: jenks admin deploys

參數	型別	必填	說明
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

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

`admin_promote` — 將 dev 升至正式環境

將 dev 分支合併到 main，將 dev.jenksguo.xyz 上預覽的所有內容發佈到正式站（jenksguo.pages.dev 與 jenksguo.xyz）。

MCP: admin_promote on https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/promote（代理 Token）
作用範圍: publish
CLI: jenks admin promote

參數	型別	必填	說明
`message`	string	否

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

`admin_publish_cv` — 發佈新的 CV 版本

上傳新的 CV PDF（ai、web3 或新 slug），並在一步內將其設為目前版本：PDF 會進入媒體庫，先前版本移至 CV 的歷史（仍可下載），且變更會被提交（CI 會發佈）。可選封面預覽圖片與新的標題／摘要。穩定網址 /cv/.pdf 之後會提供新檔案。

MCP: admin_publish_cv on https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/cv（代理 Token）
作用範圍: content + media（main 分支另需 publish）
CLI: jenks admin cv publish <slug> <file.pdf> --cv-version 2026.10 [--preview /media/…]

參數	型別	必填	說明
`slug`	string	是	ai、web3，或新的 kebab-case ID
`version`	string	是	例如 2026.10
`filename`	string	否
`data`	string	否	PDF 位元組，base64
`url`	string	否	`data` 的替代：PDF 的 https URL
`preview`	string	否	可選：已上傳的 /media/… 第 1 頁圖片
`title`	string	否
`summary`	string	否
`message`	string	否	提交訊息
`branch`	`main` · `dev`	否	main 發佈到正式站（jenksguo.pages.dev 與其鏡像 jenksguo.xyz）；dev 預覽於 dev.jenksguo.xyz（預設 main）。

curl -s -X POST https://jenksguo.pages.dev/api/admin/cv \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"slug":"<slug>","version":"<version>"}'

`admin_list_media` — 列出媒體

列出已上傳的圖片、影片與 PDF（新的在前）：url、型別、大小、尺寸、替代文字、可直接貼上的 Markdown，以及每個檔案被哪些項目使用。

MCP: admin_list_media on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/media?prefix=&cursor=&limit=（代理 Token）
作用範圍: read
CLI: jenks admin media ls [prefix]

參數	型別	必填	說明
`prefix`	string	否	Key 前綴，如 2026/10
`cursor`	string	否
`limit`	integer	否

curl -s "https://jenksguo.pages.dev/api/admin/media" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_upload_media` — 上傳媒體

將圖片（webp、jpg、png、gif、avif、svg）、影片（mp4、webm）或 PDF（最大 25 MB）儲存到 Cloudflare R2，並取得公開的 /media/… URL 與 Markdown。以 base64 data 搭配 filename 傳送，或提供公開的 https url 以匯入。檔案一經上傳即可透過 URL 公開；請用 admin_write_file 從內容參照它們。REST 端點也接受 multipart/form-data（欄位 file）。

MCP: admin_upload_media on https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/media（代理 Token）
作用範圍: media
CLI: jenks admin media upload <file|https-url> [--alt "…"]

參數	型別	必填	說明
`filename`	string	否	原始檔名；會成為 URL 的可讀部分。
`data`	string	否	檔案位元組，base64（允許 data: URL 前綴）。
`url`	string	否	`data` 的替代：伺服器下載的 https URL。
`alt`	string	否	替代文字：描述圖片內容，供螢幕閱讀器與機器人使用。
`width`	integer	否
`height`	integer	否

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

`admin_update_media` — 更新媒體替代文字

變更已上傳檔案所儲存的替代文字（做為插入內容時的預設 alt）。

MCP: admin_update_media on https://jenksguo.pages.dev/mcp/admin
REST: PATCH /api/admin/media（代理 Token）
作用範圍: media
CLI: jenks admin media alt <key> "<alt text>"

參數	型別	必填	說明
`key`	string	是	媒體 key 或 URL，例如 2026/10/xero-talk-1a2b3c4d5e.webp
`alt`	string	是

curl -s -X PATCH https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>","alt":"<alt>"}'

`admin_delete_media` — 刪除媒體

永久刪除已上傳檔案。若仍被已發佈內容使用則會被拒，除非 force 為 true。無法復原——與內容檔案不同，媒體沒有 git 歷史。

MCP: admin_delete_media on https://jenksguo.pages.dev/mcp/admin
REST: DELETE /api/admin/media?key=&force=（代理 Token）
作用範圍: media
CLI: jenks admin media rm <key> [--force]

參數	型別	必填	說明
`key`	string	是
`force`	boolean	否

curl -s -X DELETE https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>"}'

.md本頁內容在 AI 協助下翻譯；官方職稱保留英文。

Admin API

admin_whoami — 我是誰

admin_audit_log — 稽核日志

admin_schema — 內容 Schema

admin_list_files — 列出內容檔案

admin_read_file — 讀取內容檔案

admin_validate — 驗證變更

admin_write_file — 建立或更新內容檔案

admin_delete_file — 刪除內容檔案

admin_commit_changes — 一次提交多個檔案

admin_ai_edit — 使用 AI 擬稿編輯

admin_read_translation — 讀取翻譯

admin_write_translation — 編輯翻譯

admin_read_copy — 讀取站台介面文案

admin_write_copy — 編輯站台介面文案

admin_deploy_status — 部署狀態

admin_promote — 將 dev 升至正式環境

admin_publish_cv — 發佈新的 CV 版本

admin_list_media — 列出媒體

admin_upload_media — 上傳媒體

admin_update_media — 更新媒體替代文字

admin_delete_media — 刪除媒體