audit-rabiroute-public-docs

Files (5)

• SKILL.md
• openai.yaml · agents/
• quality-checklist.md · references/
• Test-RabiLinkDocumentationRuntime.ps1 · scripts/
• audit-public-docs.mjs · scripts/

SKILL.md (first lines)

# 审计 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、账号、私有域名、消息或本机绝对路径进入公开文件。

如果没有真实公网环境，明确标为“本地契约已验证，公网待验收”，不要把构建通过写成公网可用。

From vb2250158/RabiRoute, MIT.

More from vb2250158/RabiRoute