| name | audit-rabiroute-public-docs |
| description | 审计并修复 RabiRoute 公共文档在本机、远端 RabiLink WebGUI 和仓库浏览三种入口中的可用性。用于新增或修改 API、报告或下载文档，处理远端链接 404，补可复制的 TTS/ASR 示例，检查中英双语同步，或发布前核对源码与部署产物一致性。 |
审计 RabiRoute 公共文档
把“文档里写了”验收到“目标读者从实际入口可以照做并得到结果”。同时检查本机 WebGUI、带 /manage/<account>/<RabiGUID>/ 前缀的远端 WebGUI，以及仓库 Markdown。
工作流
-
读取受影响功能的实现、OpenAPI/Schema、双语文档和 WebGUI 入口；不要从旧页面文案反推当前契约。
-
先运行基线审计：
node skills/audit-rabiroute-public-docs/scripts/audit-public-docs.mjs
需要判断公网是否仍在运行旧文档时，再运行只读部署检查：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
skills\audit-rabiroute-public-docs\scripts\Test-RabiLinkDocumentationRuntime.ps1
它只读取本机构建、SSH 远端文件、计划任务和公共健康，不上传、不覆盖、不重启。DeploymentNeeded=true 表示本地已准备好但线上仍旧；它不是失败。
-
把内容按读者意图拆开：完成一件事写成 how-to；端点、字段和错误写成 reference；原理和边界写成 explanation。需要详细判断时读取 references/quality-checklist.md。
-
在真正拥有问题的层修复：静态文件 404 修 Relay；错误的根路径修前端；缺调用路径修用户指南；契约变化同步 OpenAPI 和开发文档。
-
为新公开能力同时补中文与英文页，并把新页加入 ProjectDocsPage.vue 的顺序和分组。
-
运行审计、相关单元测试、npm run webgui:build 和 npm run check:config。最后从本机与真实远端入口各走一次关键路径。
三种入口契约
- 本机控制面根路径通常是
http://127.0.0.1:8790/。在公共概览中把回环地址写成代码，不做成让远端读者误点的链接。
- 远端 WebGUI 根路径是
/manage/<account>/<RabiGUID>/。运行时报告、图片和下载资源必须使用相对 URL，并由 Relay 在同一前缀下安全地提供。
- 仓库 Markdown 的相对链接必须从当前文件位置计算。不要假设浏览器的
<base> 与 GitHub 的文件目录相同。
/api/* 与 /assets/* 是否重写由 Relay 实现决定；新增静态前缀时必须同时补服务器处理和回归测试。
API how-to 最低内容
每条远端 API 指南至少包含：
- 本机与公网 Base URL 的区别；
- 前置开关、目标 PC 选择和在线要求；
- 安全的 token 占位符与请求头；
- 一条可复制的发现/健康检查；
- 一条完整成功调用，以及输出文件或响应示例；
- 常见
401、409、502、504 的含义与恢复动作；
- 不能远端执行的高风险能力，例如麦克风控制、安装模型或加载代码；
- 明确的成功判据，而不是只列端点名称。
命令示例要标明 shell。不要在同一个代码块里混写 Bash 与 PowerShell 语法。占位符统一用 <RABILINK_APP_TOKEN>、<RELAY_ORIGIN> 这类可搜索形式，并说明如何替换。
报告与生成产物
- 报告真源放在源码目录，构建复制到 WebGUI 静态产物；不要直接维护被忽略的
dist/。
- 前端链接使用相对地址，例如
reports/example.html，使 <base> 能绑定本机或远端前缀。
- Relay 只暴露明确允许的静态目录，并使用安全子路径解析阻止目录穿越。
- 报告必须写明目标机器、采样时间和结果适用范围，不能伪装成当前客户端的实时状态。
验收证据
交付时记录：
- 审计脚本的零错误输出；
- 中英页都能在
/#/docs 搜索和打开；
- 远端报告 URL 返回
200 和正确 Content-Type；
- TTS 生成非空音频，ASR 返回预期格式；
- 无真实 token、账号、私有域名、消息或本机绝对路径进入公开文件。
如果没有真实公网环境，明确标为“本地契约已验证，公网待验收”，不要把构建通过写成公网可用。
