audit-rabiroute-public-docs

# 审计 RabiRoute 公共文档 把“文档里写了”验收到“目标读者从实际入口可以照做并得到结果”。同时检查本机 WebGUI、带 `/manage/<account>/<RabiGUID>/` 前缀的远端 WebGUI，以及仓库 Markdown。 ## 工作流 1. 读取受影响功能的实现、OpenAPI/Schema、双语文档和 WebGUI 入口；不要从旧页面文案反推当前契约。 2. 先运行基线审计： ```powershell node skills/audit-rabiroute-public-docs/scripts/audit-public-docs.mjs ``` 需要判断公网是否仍在运行旧文档时，再运行只读部署检查： ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File ` skills\audit-rabiroute-public-docs\scripts\Test-RabiLinkDocumentationRuntime.ps1 ``` 它只读取本机构建、SSH 远端文件、计划任务和公共健康，不上传、不覆盖、不重启。`DeploymentNeeded=true` 表示本地已准备好但线上仍旧；它不是失败。 3. 把内容按读者意图拆开：完成一件事写成 how-to；端点、字段和错误写成 reference；原理和边界写成 explanation。需要详细判断时读取 [references/quality-checklist.md](references/quality-checklist.md)。 4. 在真正拥有问题的层修复：静态文件 404 修 Relay；错误的根路径修前端；缺调用路径修用户指南；契约变化同步 OpenAPI 和开发文档。 5. 为新公开能力同时补中文与英文页，并把新页加入 `ProjectDocsPage.vue` 的顺序和分组。 6. 运行审计、相关单元测试、`npm run webgui:build` 和 `npm run check:config`。最后从本机与真实远端入口各走一次关键路径。 ## 三种入口契约 - 本机控制面根路径由已安装的 `RabiRouteHost.exe --command status --json` 在 `managerBaseUrl` 返回；端口由当前应用代际动态分配。公共概览应说明发现命令，不得写死或扫描端口。 - 远端 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 只暴露明确允许的静态目录，并使用安全子路径解析阻止目录穿越。 - 报告必须写明目标机器、采样时间和结果适用范围，不能伪装成当前客户端的实时状态。 ## 验收证据 调用 `scripts/Test-RabiLinkDocumentationRuntime.ps1` 时，显式传入当前源码根 `-ProjectRoot`，以及授权部署配置中的 `-Username` 和 `-RemoteRoot`；不使用内置账号或机器路径。没有远端验收授权时只执行本地文档检查。 交付时记录： - 审计脚本的零错误输出； - 中英页都能在 `/#/docs` 搜索和打开； - 远端报告 URL 返回 `200` 和正确 `Content-Type`； - TTS 生成非空音频，ASR 返回预期格式； - 无真实 token、账号、私有域名、消息或本机绝对路径进入公开文件。 如果没有真实公网环境，明确标为“本地契约已验证，公网待验收”，不要把构建通过写成公网可用。