管理 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 — 内容模式

内容模型：条目字段与规则、标签、镜头、种类、可写路径、文档与编辑规范。写入前请先阅读。

• MCP: admin_schema on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/schema（管理员令牌）
• CLI: jenks admin schema

无参数。

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

admin_list_files — 列出内容文件

列出某分支上的可编辑内容文件（路径、大小、sha），可选限定在某个文件夹内，例如 content/corpus/experiences。

• MCP: admin_list_files on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/files?dir=&branch=（管理员令牌）
• CLI: jenks admin ls [dir]

参数	类型	必填	说明
dir	字符串	否	例如 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，或为某个条目、镜头或技能传入 slug。

• MCP: admin_read_file on https://jenksguo.xyz/mcp/admin
• REST: GET /api/admin/file?path=&slug=&branch=（管理员令牌）
• CLI: jenks admin get <slug|path>

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

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

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（管理员令牌）
• CLI: jenks admin put <path> <file> -m <message>

参数	类型	必填	说明
path	字符串	是
content	字符串	是
message	字符串	是	提交信息
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=（管理员令牌）
• CLI: jenks admin rm <path> -m <message>

参数	类型	必填	说明
path	字符串	是
message	字符串	是
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（管理员令牌）
• CLI: jenks admin commit <changes.json> -m <message>

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

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

• MCP: admin_ai_edit on https://jenksguo.xyz/mcp/admin
• REST: POST /api/admin/ai-edit（管理员令牌）
• CLI: jenks admin ai-edit <slug|path> "<instruction>" [--apply]

参数	类型	必填	说明
path	字符串	否
slug	字符串	否
instruction	字符串	是
branch	main · dev	否	main 发布到 jenksguo.xyz；dev 预览到 dev.jenksguo.xyz（默认 main）。
content	字符串	否	可选的未保存文件文本，作为起草来源（默认：已保存文件）。

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=（管理员令牌）
• 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（管理员令牌）
• CLI: jenks admin promote

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

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