docs: document Dashboard plugin operations

README.md

@@ -41,20 +41,39 @@ rsync -a --delete \
 
 `rsync --delete` 只会删除目标 `dashboard/` 目录中仓库未提供的旧插件文件，不会触及其他 Hermes 插件或数据；如需保留本机额外文件，请先移出该目录或不要使用 `--delete`。
 
-安装后停止 Dashboard，使运行中的 `9119` 进程重新加载插件；已安装的夭夭 Web LaunchAgent 会在下一轮检查中自动按其配置重启它：
+安装后需显式启用夭夭插件。Dashboard 对用户目录下的插件采用默认拒绝策略：文件已复制不代表前端资源或 API 已加载。
+
+先查看当前启用列表：
+
+```bash
+hermes config get plugins.enabled
+```
+
+若输出为 `[]`，可直接启用夭夭：
+
+```bash
+hermes config set plugins.enabled '["yaoyao"]'
+```
+
+若已有其他条目，请在保留原有插件名的前提下，将 `yaoyao` 加入同一 JSON 列表后再写回。不要只依赖 `hermes plugins list` 判断夭夭是否加载：夭夭是 Dashboard 扩展，最终应以 Dashboard 的插件清单和启动日志为准。
+
+然后停止 Dashboard，使运行中的 `9119` 进程重新加载插件。已安装的夭夭 Web LaunchAgent 会在下一轮检查中自动按其配置重启它：
 
 ```bash
 hermes dashboard --stop
-hermes dashboard --no-open
 ```
 
-通过状态命令确认 Dashboard 已恢复运行：
+通过状态命令、插件清单和日志确认 Dashboard 已恢复且已加载夭夭：
 
 ```bash
 hermes dashboard --status
+curl --noproxy '*' --fail --silent http://127.0.0.1:9119/api/dashboard/plugins
+tail -n 100 ~/.hermes/logs/gui.log
 ```
 
-若 Hermes 由 LaunchAgent、服务管理器或其他外部监督器启动，请使用该监督器重启 Dashboard，而不是同时手动执行 `hermes dashboard --no-open`，以免产生重复监听进程。
+验收时，插件清单应包含 `"name":"yaoyao"`，日志应包含 `Mounted plugin API routes: /api/plugins/yaoyao/`。夭夭 API 需要 Dashboard 登录会话，匿名请求返回 `401`、插件静态资源跳转到登录页均属预期。
+
+若 Hermes 由 LaunchAgent、服务管理器或其他外部监督器启动，请使用该监督器重启 Dashboard；不要在 `hermes dashboard --stop` 后同时手动执行 `hermes dashboard --no-open`，以免产生重复监听进程。
 
 插件的归档数据与运行状态仍位于 Hermes 数据目录中，不在此仓库的 `hermes-plugins/` 中；升级插件前的备份也不应提交到 Git。
 
@@ -108,3 +127,25 @@ node bin/hermes-yaoyao.mjs service uninstall
 执行 `npm link` 后也可以直接使用 `hermes-yaoyao` 命令。
 
 运行数据默认位于 `~/.hermes-yaoyao`。卸载 LaunchAgent 不会删除运行数据。
+
+## 受管服务操作与验收
+
+`service install` 会写入并启动 `com.samien.hermes-yaoyao` LaunchAgent；它默认监督本机 `9119`。已安装服务的环境变量写入 plist，因此改变监听地址、TLS 或监督开关后需要再次执行 `service install`，仅执行 `service start` 不会刷新这些配置。
+
+| 目标 | 命令 | 预期结果 |
+| --- | --- | --- |
+| 查看服务 | `node bin/hermes-yaoyao.mjs service status` | `com.samien.hermes-yaoyao` 为 running |
+| 查看 Web | `curl --noproxy '*' --fail --silent http://127.0.0.1:8800/` | 返回夭夭 Web 页面 |
+| 查看 Dashboard | `curl --noproxy '*' --fail --silent http://127.0.0.1:9119/api/auth/providers` | 返回基础认证 provider |
+| 查看监听器 | `lsof -nP -iTCP:8800 -sTCP:LISTEN` 与 `lsof -nP -iTCP:9119 -sTCP:LISTEN` | 每个端口恰好一个监听进程 |
+| 查看受管日志 | `tail -f ~/Library/Logs/hermes-yaoyao.log` | 记录 Web 监听和 Dashboard 监督事件 |
+
+在部分 macOS 环境中，`service install` 内部的 `launchctl bootstrap` 可能返回 `Bootstrap failed: 5: Input/output error`。先验证 plist 再使用等效兼容回退，不要重复创建服务：
+
+```bash
+plutil -lint ~/Library/LaunchAgents/com.samien.hermes-yaoyao.plist
+launchctl load -w ~/Library/LaunchAgents/com.samien.hermes-yaoyao.plist
+node bin/hermes-yaoyao.mjs service status
+```
+
+手动以 `npm start` 运行时，`HERMES_YAOYAO_SUPERVISE_DASHBOARD` 默认关闭；如需让该进程监督 Dashboard，请显式设置为 `1`。生产环境优先使用上述 LaunchAgent，避免两个进程同时管理 `9119`。

docs/agent-install.md

@@ -132,7 +132,40 @@ test "$(node -e \"console.log(require(process.argv[1]).version)\" "$PLUGIN_DIR/m
 | 需要让新插件生效 | 执行 `hermes dashboard --stop`，等待 8800 监督器在 5 秒内自动启动 | 另起常驻 `hermes dashboard` 进程 |
 | 9119 未监听 | 等待 8800 监督器自动启动；检查其日志 | 手动重复启动多个 Dashboard |
 
-## 4. 验证插件和 Dashboard
+## 4. 显式启用夭夭 Dashboard 插件
+
+夭夭位于用户插件目录，Dashboard 会先发现其 `manifest.json`，但不会自动执行用户提供的 JavaScript 或 Python 代码。只有插件名同时满足 `plugins.enabled` 包含 `yaoyao` 且未出现在 `plugins.disabled` 中时，Dashboard 才会展示夭夭标签、提供静态资源并挂载 `/api/plugins/yaoyao/`。
+
+先读取当前列表：
+
+```bash
+hermes config get plugins.enabled
+```
+
+当列表为空时，设置唯一的启用项：
+
+```bash
+hermes config set plugins.enabled '["yaoyao"]'
+```
+
+如果列表已有其他插件名，必须保留它们并在同一 JSON 列表中加入 `yaoyao`；不要以该示例覆盖已有启用项。随后执行：
+
+```bash
+hermes dashboard --stop
+```
+
+8800 监督器会在下一轮检查中自动重新启动 9119。不要补充 `hermes dashboard --no-open`，否则可能与监督器竞争端口。
+
+验证时使用 Dashboard 专用清单，而不是通用 `hermes plugins list`：
+
+```bash
+curl --noproxy '*' --fail --silent http://127.0.0.1:9119/api/dashboard/plugins
+tail -n 100 ~/.hermes/logs/gui.log
+```
+
+验收条件：清单包含 `"name":"yaoyao"`，日志包含 `Mounted plugin API routes: /api/plugins/yaoyao/`。匿名请求 `/api/plugins/yaoyao/...` 返回 `401` 是认证生效的信号，不表示插件加载失败。
+
+## 5. 验证插件和 Dashboard
 
 ```bash
 hermes dashboard --status
@@ -141,7 +174,7 @@ lsof -nP -iTCP:9119 -sTCP:LISTEN
 
 验收条件：Dashboard 状态正常，且只有一个 `9119` TCP 监听器。插件路由位于 `/api/plugins/yaoyao/`，该 API 需要现有 Hermes 登录会话；不要为了探测路由而关闭认证。除非用户明确授权且已配置对应生命周期所有者，否则保持 `9119` 仅本机监听。
 
-## 5. 可选：部署夭夭 Web
+## 6. 可选：部署夭夭 Web
 
 夭夭 Web 默认监听 `8800` 并连接 Dashboard `9119`。通过 LaunchAgent 安装后，它持续监督 Dashboard `9119`，但在自身停止或卸载时不会主动停止正在运行的 Dashboard。
 
@@ -154,10 +187,27 @@ node bin/hermes-yaoyao.mjs service status
 
 若需要显式指定 Dashboard 上游，只在安装服务前设置 `HERMES_YAOYAO_UPSTREAM`。默认值为 `http://127.0.0.1:9119`。只有用户明确要求时才允许局域网：设置 `HERMES_YAOYAO_HOST=0.0.0.0` 和 `HERMES_YAOYAO_ALLOW_INSECURE_LAN=1`；受管服务会同时将 9119 绑定至 `0.0.0.0`。
 
-## 6. 失败处理
+受管服务的配置被写入 `~/Library/LaunchAgents/com.samien.hermes-yaoyao.plist`。任何监听、TLS、上游或监督配置变更后，都要再次执行 `service install`，随后确认状态、两个监听器和日志：
+
+```bash
+node bin/hermes-yaoyao.mjs service status
+lsof -nP -iTCP:8800 -sTCP:LISTEN
+lsof -nP -iTCP:9119 -sTCP:LISTEN
+tail -n 100 ~/Library/Logs/hermes-yaoyao.log
+```
+
+若 `launchctl bootstrap` 报 `Bootstrap failed: 5: Input/output error`，先验证 plist，再使用已验证的兼容回退加载同一份文件：
+
+```bash
+plutil -lint ~/Library/LaunchAgents/com.samien.hermes-yaoyao.plist
+launchctl load -w ~/Library/LaunchAgents/com.samien.hermes-yaoyao.plist
+```
+
+## 7. 失败处理
 
 1. 记录失败的命令、退出码、Dashboard 状态和 `9119` 监听信息。
 2. 若插件重载失败，使用第 2 步生成的 `$BACKUP_DIR` 恢复到 `$PLUGIN_DIR`，执行 `hermes dashboard --stop`，再由 8800 监督器重启 Dashboard。
-3. 不要通过多次执行 `hermes dashboard --no-open`、重复安装 LaunchAgent 或停止无关 Gateway 来“尝试修复”。这些操作会掩盖真正错误，或产生重复监听进程。
+3. 若插件文件存在但未显示，先检查 `plugins.enabled` 是否包含 `yaoyao`，再检查 `/api/dashboard/plugins` 和 `gui.log`；不要通过重复复制目录或禁用认证来“尝试修复”。
+4. 不要通过多次执行 `hermes dashboard --no-open`、重复安装 LaunchAgent 或停止无关 Gateway 来“尝试修复”。这些操作会掩盖真正错误，或产生重复监听进程。
 
 版本不匹配、没有可用备份或无法确认 Dashboard 所有者时，停止自动化流程并报告，而不是猜测或覆盖现有安装。