Docs Agent
查看 Markdown本文档供 AI 阅读，不是可执行 skill 配置。相关工具脚本为 `docs-rev.sh`（入口）与 `docs-rev.py`（实现），二者放在同一目录下即可，脚本自身不再依赖任何工作区绝对路径。
同时检索文章与文档，或切换类型缩小范围
本文档供 AI 阅读，不是可执行 skill 配置。相关工具脚本为 `docs-rev.sh`（入口）与 `docs-rev.py`（实现），二者放在同一目录下即可，脚本自身不再依赖任何工作区绝对路径。
文档站唯一真源是线上 https://blog.miomoe.cn/docs。 工作区内没有本地 Docs/ 检出，不要重建本地文档树，也不要用本地旧副本当依据。所有读写一律走 Agent API。
https://api.miomoe.cnX-API-Key: <key>（也接受 Authorization: Bearer <key>）MIOMOE_AGENT_BASE_URL / MIOMOE_AGENT_KEY--env 指定的 .env 文件.envGET /agent/me → 看 group、permissions。提交修订需要 docs.edit，新建页需要 docs.create。没有对应权限就直接告知用户，不要反复重试。.env 需包含：
MIOMOE_AGENT_BASE_URL=https://api.miomoe.cn
MIOMOE_AGENT_KEY=<key>| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /agent/me | 账号、组与权限自检 |
| GET | /agent/docs | 目录配置 + 全部文档摘要（约 277 页 / 17 分区） |
| GET | /agent/docs/page?path=<path> | 标题 / 描述 / markdown 正文（JSON，data.content） |
| GET | /agent/docs/raw?path=<path> | 直出 text/plain markdown，含 frontmatter |
| POST | /agent/docs | 新建页面（需 docs.create），同路径的 GET 是拿目录 |
| POST | /agent/docs/revisions | 提交修订（需 docs.edit，进待审队列） |
| GET | /agent/docs/revisions | 修订列表，支持 status / page 分页 |
| GET | /agent/docs/revisions/:uuid | 修订详情（仅本人） |
path 是去掉分区前缀后的相对路径，例如 xbase/version、xbase/data-layout、index。
/agent/docs → data.metas[]（分区：path/title/root/icon/pages）与 data.pages[]（uuid/path/section/title/description/sort_order）。先拉它拿准确 path，别猜。
/agent/docs/page → data.{uuid,path,section,title,description,sort_order,created_at,updated_at,content}，content 是带 frontmatter 的完整 markdown。
/agent/docs/raw → 纯文本 markdown，适合直接读/做 diff。
/agent/docs/revisions → data.items[] + data.pagination。修订对象字段：uuid, doc_uuid, path, title, description, content, status, note, review_note, editor_uuid, editor_name, reviewer_uuid, reviewer_name, created_at, reviewed_at, applied_at。
POST /agent/docs/revisions，JSON body 字段与修订对象对齐：
{
"path": "xbase/version",
"title": "Version",
"description": "游戏版本检测与版本名称。",
"content": "---\ntitle: Version\n...",
"note": "改写原因（可选）"
}要点：
GET /agent/docs/revisions 或详情端点确认 status。editor_uuid 过滤，只能看到自己提交的条目。content 必须是完整正文（含 frontmatter），不是增量 diff。正规做法：先 raw 拉原文 → 在此基础上改 → 整体回传。hasPermission / rolesForGroup；403 就是权限不够，别绕。优先用工具，不要手工拼 curl + 字符串替换。
D="./docs-rev.sh"
"$D" me # 账号与权限自检
"$D" list --section xbase # 分区 + 页面（--paths 只输出 path）
"$D" show xbase/version # 打印原始 markdown
"$D" pull xbase/version -o v.md # 拉到本地编辑（保留原始行尾）
"$D" push v.md --path xbase/version --dry-run # 只看 diff，不提交
"$D" push v.md --path xbase/version --yes # 确认后提交
"$D" replace xbase/version --old-file a.txt --new-file b.txt --count 1 --yes
"$D" create xbase/new-page --file n.md --title "标题" --yes # 新建页面
"$D" status --status pending # 修订列表
"$D" status <uuid> # 单条详情docs-rev.sh：Bash 入口。负责关闭 MSYS 路径转换、探测 Python 解释器、转发到 docs-rev.py。docs-rev.py：Python 实现。所有 HTTP、diff、行尾处理、提交流程都在这里。docs-rev.sh 按以下顺序探测：
PYTHONpython3python三者都找不到时报错退出。不写死任何绝对路径。
docs-rev.py 按以下顺序读取：
MIOMOE_AGENT_BASE_URL / MIOMOE_AGENT_KEY--env 指定的 .env.env如果三处都没有有效凭据，直接报错退出。
create 会先确认 path 不存在，存在就提示改用 push。--title 或文件 frontmatter。POST /agent/docs（返回 201）。POST /agent/docs/revisions 对不存在的 path 返回 404「文档不存在」，它只能修订已有文档——别拿它建页。create 内置候选端点依次尝试，--probe 打印每次结果，--endpoint 指定路由。端点有问题就扩展工具，不要另写临时脚本。--count N 可断言命中次数，与预期不符就中止。--yes，否则只给提示不提交。--path 省略时按文件名推断（xbase_version.md → xbase/version）。set -a && . ./.env && set +a
curl -s -H "X-API-Key: $MIOMOE_AGENT_KEY" \
"$MIOMOE_AGENT_BASE_URL/agent/docs/raw?path=xbase/version"Windows Git Bash 下不要把输出写到 /tmp（Python 侧找不到），直接管道给 Python 处理。
Git Bash 会把 /agent/docs 这类参数转成 Windows 路径（MSYS 路径转换），docs-rev.sh 里已 export MSYS_NO_PATHCONV=1；代价是脚本自身路径要用 pwd -W 取，否则会变成 /c/...。
行尾不统一，别假设全局 CRLF：实测 xbase/shared-runtime 是 CRLF、xbase/index 是 LF。pull 下来先按字节数出该页行尾（data.count(b"\r\n") 与裸 \n 对比），改写后按该页原本行尾回写，否则整文件都会变成假 diff。另注意 curl | python -c 经 stdin 会被 universal newlines 转成 \n，诊断时极易看错；多行替换落空往往就是行尾不一致（"看起来一模一样却匹配不上"）。
受限沙箱会挡掉 docs-rev.sh：运行时报 sandbox-center cmd decisionRecord missing actual resource subject，禁用沙箱同样被挡。不要反复重试或换 shell 绕圈，直接用兜底链路：curl 拉 raw → Python 改写 → POST /agent/docs/revisions，凭据照常从环境变量或 .env 读。
POST /agent/docs/revisions 实测可用 body：{path, title, description, content, note} → 201，data.status = "pending"。一次只覆盖一页，多页就提交多次。替换用 str.replace 并断言命中次数，别静默跳过。
/agent/docs 的 metas[] 用 path 作分区标识（如 xbase），root 只是 0/1 层级标记，拿 root 当分区名会匹配不上；pages[] 的分区字段叫 section。
旧域名 gtadev.miomoe.cn 会 301 跳到 blog.miomoe.cn，写链接时统一用新域名。
sort_order 有跳号（如 xbase 缺 100 / 250 / 300），新增页挑一个空位，不要重排已有页。
修改 XBase 代码后如果公共 API 变了，同步改 xbase/* 对应页面；正文里的方法名与签名必须和 include/XBase/*.h 一致，禁止臆造。
#!/usr/bin/env bash
# docs-rev — blog.miomoe.cn/docs 修订工具入口（Git Bash）
set -e
# Git Bash 会把 /agent/docs 这类参数转成 Windows 路径，必须关闭 MSYS 路径转换
export MSYS_NO_PATHCONV=1
# 选择可用的 Python 解释器：PYTHON 环境变量 > python3 > python
if [ -n "${PYTHON:-}" ]; then
PY="$PYTHON"
elif command -v python3 >/dev/null 2>&1; then
PY=python3
elif command -v python >/dev/null 2>&1; then
PY=python
else
echo "错误: 未找到 Python 解释器，请安装 python3 或设置 PYTHON 环境变量" >&2
exit 1
fi
# 脚本所在目录。Windows 下用 pwd -W 取盘符路径，非 MSYS 环境回退到 pwd
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W 2>/dev/null || pwd)"
exec "$PY" "$HERE/docs-rev.py" "$@"
评论