文档 / reference

管理 API

通过经验证的 git 提交来编辑站点内容的已认证端点。

所有管理端点都需要一个代理服务令牌：Authorization: Bearer jgx_agt_…（CLI 从环境变量 JENKSGUO_ADMIN_TOKEN 读取）。Jenks 在控制台 https://admin.jenksguo.xyz/admin → Access（使用 Google 登录，Cloudflare Access）创建令牌；每个令牌都有名称、作用域（content、media、publish；所有令牌都可读）、到期时间且可撤销。向分支 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`	—（仅人类：列出或创建代理令牌；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 邮箱或代理令牌名称）、你的作用域、令牌何时过期，以及是否已配置发布（GitHub）。

MCP: admin_whoami on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/whoami（代理令牌）
Scope: read
CLI: jenks admin whoami

无参数。

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

`admin_audit_log` — 审计日志

最近的管理操作，最新在前：谁（SSO 邮箱或代理令牌）、做了什么、哪些文件、分支、主机和结果。代理令牌只能看到它自己的操作。

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

参数	类型	必填	说明
`limit`	整数	否
`token`	字符串	否	仅此代理令牌 id（仅人类）

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

`admin_schema` — 内容 schema

内容模型：条目字段与规则、标签、lenses、kinds、可写路径、文档与编辑约定。写入前请阅读。

MCP: admin_schema on https://jenksguo.pages.dev/mcp/admin
REST: GET /api/admin/schema（代理令牌）
Scope: 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=（代理令牌）
Scope: read
CLI: jenks admin ls [dir]

参数	类型	必填	说明
`dir`	字符串	否	例如 content/corpus/projects（默认：全部内容）
`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，或针对条目、lens 或 skill 使用 slug。

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

参数	类型	必填	说明
`path`	字符串	否
`slug`	字符串	否
`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（代理令牌）
Scope: read
CLI: jenks admin validate <path> <file>

参数	类型	必填	说明
`path`	字符串	是
`content`	字符串	是

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（代理令牌）
Scope: content（分支 main 还需 publish）
CLI: jenks admin put <path> <file> -m <message>

参数	类型	必填	说明
`path`	字符串	是
`content`	字符串	是
`message`	字符串	是	提交说明
`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=（代理令牌）
Scope: content（分支 main 还需 publish）
CLI: jenks admin rm <path> -m <message>

参数	类型	必填	说明
`path`	字符串	是
`message`	字符串	是
`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（代理令牌）
Scope: content（分支 main 还需 publish）
CLI: jenks admin commit <changes.json> -m <message>

参数	类型	必填	说明
`changes`	数组	是
`message`	字符串	是
`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 起草编辑

向站点的模型发出英文指令以改写一个内容文件。返回建议内容、diff 与校验问题。不会提交——请先审阅，然后调用 admin_write_file。

MCP: admin_ai_edit on https://jenksguo.pages.dev/mcp/admin
REST: POST /api/admin/ai-edit（代理令牌）
Scope: content
CLI: jenks admin ai-edit <slug|path> "<instruction>" [--apply]

参数	类型	必填	说明
`path`	字符串	否
`slug`	字符串	否
`instruction`	字符串	是
`branch`	`main` · `dev`	否	main 发布到线上站点（jenksguo.pages.dev 及其镜像 jenksguo.xyz）；dev 在 dev.jenksguo.xyz 预览（默认 main）。
`content`	字符串	否	可选：从未保存的文件文本起草（默认：已保存文件）。

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` — 读取翻译

将某个内容文件以另一种语言呈现：英文源字段、当前译文及其状态（当前、已过期、人工编辑、缺失）。适用于条目、lenses、CV、arguments、观点页、credentials、talks 和文档。语言：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=（代理令牌）
Scope: read
CLI: jenks admin tr get <slug|path> <locale>

参数	类型	必填	说明
`path`	字符串	否
`slug`	字符串	否
`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（代理令牌）
Scope: content（分支 main 还需 publish）
CLI: jenks admin tr put <slug|path> <locale> <fields.json> -m <message>

参数	类型	必填	说明
`path`	字符串	否
`slug`	字符串	否
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`fields`	对象	是	例如 {"summary": "…", "body": "## …"}
`message`	字符串	否	提交说明
`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` — 读取站点文案

某一语言下的站点界面文案——菜单、页面标题、单行页面简介、首屏标题、按钮、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=（代理令牌）
Scope: read
CLI: jenks admin copy get <locale> [prefix]

参数	类型	必填	说明
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`prefix`	字符串	否
`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（代理令牌）
Scope: content（分支 main 还需 publish）
CLI: jenks admin copy set <locale> <key> "<text>" -m <message>

参数	类型	必填	说明
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	是
`values`	对象	是	例如 {"hero.sub": "…"}
`message`	字符串	否
`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=（代理令牌）
Scope: 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（代理令牌）
Scope: publish
CLI: jenks admin promote

参数	类型	必填	说明
`message`	字符串	否

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（ai、web3 或新 slug）的新 PDF，并在一步内将其设为当前版本：PDF 进入媒体库、上一版本移动到该 CV 的历史（仍可下载），并提交变更（CI 发布）。可选预览图与新标题/摘要。稳定地址 /cv/.pdf 将提供新文件。

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

参数	类型	必填	说明
`slug`	字符串	是	ai、web3，或新的 kebab-case id
`version`	字符串	是	例如 2026.10
`filename`	字符串	否
`data`	字符串	否	PDF 字节，base64
`url`	字符串	否	`data` 的替代：PDF 的 https URL
`preview`	字符串	否	可选：已上传的 /media/… 第 1 页图像
`title`	字符串	否
`summary`	字符串	否
`message`	字符串	否	提交说明
`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、类型、大小、尺寸、alt 文本、可直接粘贴的 Markdown，以及每个文件被哪些条目使用。

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

参数	类型	必填	说明
`prefix`	字符串	否	键前缀，如 2026/10
`cursor`	字符串	否
`limit`	整数	否

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。发送带 filename 的 base64 data，或提供公共 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（代理令牌）
Scope: media
CLI: jenks admin media upload <file|https-url> [--alt "…"]

参数	类型	必填	说明
`filename`	字符串	否	原始文件名；作为 url 的可读部分。
`data`	字符串	否	文件字节，base64（允许 data: URL 前缀）。
`url`	字符串	否	`data` 的替代：服务器下载的 https URL。
`alt`	字符串	否	Alt 文本：图像所示内容，供读屏与机器人使用。
`width`	整数	否
`height`	整数	否

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 文本

更改已上传文件的存储 alt 文本（插入到内容时的默认 alt）。

MCP: admin_update_media on https://jenksguo.pages.dev/mcp/admin
REST: PATCH /api/admin/media（代理令牌）
Scope: media
CLI: jenks admin media alt <key> "<alt text>"

参数	类型	必填	说明
`key`	字符串	是	媒体键或 url，例如 2026/10/xero-talk-1a2b3c4d5e.webp
`alt`	字符串	是

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=（代理令牌）
Scope: media
CLI: jenks admin media rm <key> [--force]

参数	类型	必填	说明
`key`	字符串	是
`force`	布尔值	否

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 协助下翻译；官方职位名称保留英文。

管理 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 — 更新媒体 alt 文本

admin_delete_media — 删除媒体