用途：将 GitHub 仓库中已有的 Markdown 文档目录连接到 WordPress 发布，不覆盖手工页面、不暴露凭据，并把仓库写入、GitHub 写入、WordPress 写入视为相互独立的审批边界。
主要能力：先检查仓库根目录、分支、远端与工作区状态，复用已有 docs 目录；可检测多版本 API 发布、版本注册表、版本目录或文件名后缀。支持 WordPress.com（https://public-api.wordpress.com 与全局 OAuth 令牌）和自托管 WordPress（站点 origin 作为 wordpress-url，需已支持 Bearer 令牌访问 /wp-json/wp/v2/pages）。默认配置为 mode=publish、docs-dir=docs、root-slug=docs、root-title=Docs、create-h1=false、rewrite-links=true、status=draft、delete-mode=trash、dry-run=true。版本管理需 versions-file 注册表与配套 DocsPress Blocks 插件。
使用方式：创建或修复 .github/workflows/sync-docs.yml，动作固定到已验证的完整提交 SHA；先手动触发并保持 dry-run: true，验证后再改为 false 并保持 draft，最后经批准才 publish。认证方面，WordPress.com 需在 https://developer.wordpress.com/apps/ 创建应用，redirect URI 为 http://localhost:8787/callback，并在用户本地终端运行 npx docspress@0.2.0 token 等命令设置 WP_ACCESS_TOKEN；自托管站点需已有 bearer-token 机制。可用 gh secret list --repo OWNER/REPO 仅确认密钥名。主题与插件可用 wp theme install、wp plugin install 安装。
适用场景：需要把仓库文档持续发布到 WordPress、需要多版本 API 文档路由、需要草稿预览与反向同步（mode: reconcile）的团队。
限制：不得让用户把令牌、密钥、密码粘贴到聊天中；未验证的 SHA 或浮动引用需停止并询问；未托管页面冲突是停止条件；插件/主题激活、公开发布、仓库写入均需单独批准；版本管理必须使用匹配的 DocsPress Blocks 插件。