scrolls-help

Scrolls 帮助

此技能的任务是清晰地回答问题，然后不再打扰用户——不探索用户的代码库，不检查这里是否已设置 scrolls，也不修改用户项目中的任何内容。

范围说明： 此技能在处理 /scrolls-help 请求时，绝不会写入用户代码、用户文件或其自身目录之外的任何内容。维护此技能的人员单独负责让其自身的 references/HELP.md 保持最新，这是一项无关的维护任务——请参阅 meta/MAINTAINERS.md——不会在回答用户时执行。有关完整的安全策略（文件系统范围、本地 -e/--online 服务的网络暴露和生命周期），请参阅 meta/SECURITY.md——这是参考资料，不是在回答请求时需要采取的操作。

跨平台支持

-e/--online 的启动器有两种形式：open_help.sh（bash——适用于 macOS、Linux，或装有 Git Bash/WSL 的 Windows）和 open_help.ps1（PowerShell 7+——适用于 Windows，或安装了 pwsh 的 macOS/Linux）；它们启动的实际服务 serve_help.py 无需移植——它使用纯 Python 标准库，天然支持跨平台，而且两个启动器调用它的方式相同（先解析 python3，再回退到 python，因为 Windows 通常只有后者位于 PATH 中）。根据实际可用情况选择启动器：先尝试 bash --version；如果成功，则使用 .sh；否则通过 pwsh 使用 .ps1（首选——如果未安装，可从 https://aka.ms/powershell 安装），只有在确实无法使用 pwsh 时，才使用 Windows 内置的 Windows PowerShell powershell.exe（尚未针对该旧版本进行测试；编写和验证时使用的是 pwsh）。

选项

检查调用文本中是否包含可选参数 -e / --online——除了（或在用户意图不明确时，作为补充）在聊天中回答外，还可以将 references/HELP.md 渲染为带样式的 HTML 页面并在本地提供服务。无论是否使用此标志，其他所有请求解读方式（直接调用还是提出具体问题）都完全相同；-e 只会更改输出渠道。

步骤

1. 阅读 references/HELP.md——这是维护中的规范内容。请直接呈现其中的内容，不要凭记忆重构这些技能的说明：标志的含义在不同迭代中发生过变化（例如，-r 过去表示“仓库根目录”，现在表示“递归”），而参考文件是唯一事实来源，相关变化发生时会在此更新。

2. 给定 -e/--online：运行 bash <skill-dir>/scripts/open_help.sh 或 pwsh <skill-dir>/scripts/open_help.ps1（见上文“跨平台”）。它会启动一个仅使用 Python 标准库的小型服务器（无需安装依赖），将 HELP.md 渲染为简洁、独立的 HTML 页面，并绑定到操作系统分配的 127.0.0.1 端口（绝不会绑定到所有网络接口；这是本地参考查看器，不应暴露到网络）。脚本会等待服务器确认确实已在监听，然后才打印内容；接着打印 URL 和进程的 PID。将该 URL 作为可点击链接提供给用户——此服务器会在当前技能结束后继续运行，因此链接仍可访问——并说明服务器会在空闲 30 分钟或总运行时间达到 2 小时后自动关闭（以先到者为准），也可以通过 <script> --stop <port> 提前停止（或通过 --stop --all 停止所有实例），无需手动查找并 kill PID。如果再次使用 -e 运行脚本，它会在新端口启动另一个服务器，而不是复用已有服务器；如果长时间会话中启动了多个实例，这一点值得留意；即使从未手动停止，每个实例也会自行关闭。如果脚本尝试打开浏览器，但界面上没有明显变化（例如无显示器的无头或远程环境），这是正常情况——URL 仍然有效，向用户报告该 URL 才是重点。

   页面右上角有一个小工具栏，包含两个互相独立的切换按钮：浅色/深色（默认遵循系统偏好；按钮可强制指定任一模式，设置会通过 localStorage 持久保存）和着色/纯文本（代码块默认采用一套简洁的 GitHub 语法风格配色——命令、标志和注释各有不同颜色，并分别提供浅色和深色配色，风格类似 Pygments/pymdown-extensions 主题；按钮可将其切换回纯文本，设置也会持久保存）。提供 URL 时，请一并说明这两个切换按钮的存在——单看链接无法看出它们。

3. 单独的 /scrolls-help，或开放式问题（“scrolls 命令有哪些”“这是怎么运作的”），且未使用 -e：以 Markdown 聊天内容形式呈现完整文档。这是回答，不是交付物——除非用户另行要求，否则不要将其写入文件或作为工件发布。

4. 具体问题（一个命令、一个标志、一个场景，例如“如何在 monorepo 中操作”，或单独提到某个命令名称）：先给出文档中直接相关的内容，并简洁作答；然后说明，完整内容可通过单独的 /scrolls-help 查看。无论是否同时给出 -e，都适用此规则——-e 只会改变完整文档的呈现位置，不会影响先针对具体问题作答。

5. 在呈现内容时（无论是在聊天中还是通过渲染页面），保持参考文件本身的语气和格式——内容本就简洁明了；不要加评论、填充内容，也不要重新解释已有的清楚说明。

开发

有关如何维护 references/HELP.md 以及如何运行 tests/ 回归测试，请参阅 meta/MAINTAINERS.md。处理用户的 /scrolls-help 请求时，不会读取这两者——回答请求时，不要操作 meta/MAINTAINERS.md 或 tests/。