scrolls-help

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scrolls help

Scrolls 帮助文档

This skill's job is to answer clearly and get out of the way — not to explore the codebase, not to check whether scrolls are actually set up here, not to make any changes.
本Skill的职责是清晰解答问题后即完成任务——无需探索代码库、无需检查当前是否已配置Scrolls、也无需进行任何修改。

Cross-platform

跨平台支持

-e
/
--online
's launcher ships in two forms:
open_help.sh
(bash — macOS, Linux, or Windows with Git Bash/WSL) and
open_help.ps1
(PowerShell 7+ — Windows, or macOS/Linux with
pwsh
installed);
serve_help.py
, the actual server both of them launch, needs no porting at all — it's pure stdlib Python, already cross-platform, and both launchers call it the same way (resolving
python3
then falling back to
python
, since Windows commonly has only the latter on
PATH
). Pick the launcher by what's actually available: try
bash --version
; if that succeeds, use
.sh
; otherwise use
.ps1
via
pwsh
(preferred — install from https://aka.ms/powershell if missing) or, only if
pwsh
genuinely isn't available, the built-in Windows PowerShell
powershell.exe
(untested against that older version;
pwsh
is what this was written and verified against).
-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内置的PowerShell
powershell.exe
(未针对该旧版本测试;本工具是基于
pwsh
编写并验证的)。

Options

选项

Read the invocation text for an optional
-e
/
--online
— instead of (or in addition to, if it's ambiguous which the user wants) answering in chat, render
references/HELP.md
as a styled HTML page and serve it locally. Everything else about interpreting the request (bare invocation vs. a specific question) works exactly the same regardless of this flag;
-e
only changes the output channel.
调用命令时可选择添加**
-e
/
--online
**参数——此时将不再(或在用户需求不明确时同时)以聊天文本形式回复,而是将
references/HELP.md
渲染为带样式的HTML页面并在本地提供服务。无论是否使用该标志,对请求的其他解析逻辑(裸调用与特定问题)完全一致;
-e
仅改变输出渠道。

Steps

执行步骤

  1. Read
    references/HELP.md
    — that's the maintained, canonical content. Present it rather than reconstructing an explanation from memory of how these skills work: flag semantics here have changed across iterations (e.g.
    -r
    used to mean "repo root," now means "recurse"), and the reference file is the single source of truth that gets updated when that happens.
  2. -e
    /
    --online
    given
    : run
    bash <skill-dir>/scripts/open_help.sh
    or
    pwsh <skill-dir>/scripts/open_help.ps1
    (see "Cross-platform" above). It launches a small stdlib-only Python server (no dependencies to install) that renders
    HELP.md
    into a clean, self-contained HTML page and binds it to
    127.0.0.1
    on a port the OS assigns (never all interfaces; this is a local reference viewer, not something to expose on the network). The script waits for the server to confirm it's actually listening before printing anything, then prints the URL followed by the process's PID. Report that URL to the user as a clickable link and mention the PID so they can stop the server later if they want to (it keeps running after this skill finishes, so the link stays open) — a fresh invocation with
    -e
    starts another server on a new port rather than reusing one, which is fine but worth knowing if several accumulate over a long session. If the script's own browser-opening attempt didn't visibly do anything (e.g. a headless/remote environment with no display), that's expected — the URL is still valid and the report to the user is what matters.
    The page has a small toolbar (top-right) with two independent toggles: light/dark (follows the system preference by default; the button forces either explicitly, persisted via
    localStorage
    ) and colorize/plain (code blocks get a small GitHub-syntax-style token palette by default — commands, flags, and comments each colored distinctly, with separate light and dark values, in the spirit of a Pygments/pymdown-extensions theme; the button strips that back to plain text, also persisted). Mention both toggles are there when reporting the URL — they're not obvious from the link alone.
  3. Bare
    /scrolls-help
    , or an open-ended question
    ("what are the scrolls commands," "how does this work"), without
    -e
    : present the whole document, as markdown chat output. This is an answer, not a deliverable — don't write it to a file or publish it as an artifact unless the user separately asks for that.
  4. A specific question (one command, one flag, one scenario like "how do I do this in a monorepo," or a command name mentioned on its own): lead with the directly relevant part of the doc, answered concisely, and mention that the rest is available via a bare
    /scrolls-help
    — don't dump the whole reference regardless of what was actually asked. This applies whether or not
    -e
    was also given —
    -e
    changes where the full doc goes, not whether a targeted question still gets a targeted answer first.
  5. Keep the reference file's own tone and formatting when you present it (in chat or via the rendered page) — it's already written to be crisp; don't editorialize, pad, or re-explain what it already says clearly.
If you notice the reference has drifted from what the other four skills actually do (a flag behaves differently than documented, a new flag exists that isn't listed), fix
references/HELP.md
itself rather than just answering around the gap — this file needs to stay accurate as
scrolls-setup
/
scrolls-update
/
scrolls-hide
/
scrolls-unhide
evolve, since it's the thing users are told to trust, in chat and on the rendered page alike.
  1. 读取
    references/HELP.md
    ——这是经过维护的权威内容。直接呈现该文档,而非凭记忆重构对这些Skill的解释:标志的语义在迭代过程中可能发生变化(例如
    -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作为可点击链接告知用户,并提及PID以便用户后续可停止服务器(本Skill执行完成后服务器仍会运行,因此链接可保持可用)——再次调用带
    -e
    参数的命令会在新端口启动另一个服务器,而非复用现有端口,若长时间会话中累积多个服务器,这一点需要注意。若脚本尝试打开浏览器但未产生明显效果(例如无显示界面的无头/远程环境),这属于正常情况——URL仍然有效,告知用户即可。
    页面右上角有一个小型工具栏,包含两个独立切换按钮:明暗主题(默认跟随系统偏好;按钮可强制切换为任一主题,设置通过
    localStorage
    持久化)和彩色/纯文本(代码块默认采用类似GitHub语法的配色方案——命令、标志和注释分别使用不同颜色,明暗主题下有独立配色,风格类似Pygments/pymdown-extensions主题;按钮可切换为纯文本模式,设置同样持久化)。告知用户URL时需提及这两个切换按钮——仅通过链接无法看出这些功能。
  3. 裸调用
    /scrolls-help
    ,或开放式问题
    (如“Scrolls命令有哪些”、“这是如何工作的”)且未指定
    -e
    参数:将整个文档以Markdown格式的聊天消息形式呈现。这是对问题的解答,而非交付物——除非用户另行要求,否则无需将其写入文件或发布为制品。
  4. 特定问题(如单个命令、单个标志、“如何在单体仓库中操作”等场景,或单独提及某个命令名称):优先简明呈现文档中直接相关的部分,并告知用户其余内容可通过裸调用
    /scrolls-help
    获取——无论用户实际询问的内容是什么,都不要直接输出整个参考文档。无论是否指定
    -e
    参数,此规则均适用——
    -e
    仅改变完整文档的输出位置,不影响针对特定问题先给出针对性解答的逻辑。
  5. 呈现内容时需保留参考文档自身的语气和格式——文档本身已编写得简洁明了;无需编辑补充、冗余铺垫或重复解释文档中已清晰说明的内容。
若发现参考文档与另外四个Skill的实际行为不符(例如标志行为与文档描述不一致、存在未列出的新标志),请直接修改
references/HELP.md
,而非仅绕过差异进行解答——随着
scrolls-setup
/
scrolls-update
/
scrolls-hide
/
scrolls-unhide
的演进,该文件需保持准确性,因为无论是在聊天中还是在渲染页面上,它都是用户被引导信任的参考依据。

Development

开发说明

tests/
holds this script's Red/Green regression suite (bash + PowerShell), for maintaining
scripts/open_help.sh
/
scripts/open_help.ps1
themselves — it plays no part in carrying out a user's
/scrolls-help
request. Don't read or run it while executing this skill.
tests/
目录包含本脚本的红/绿回归测试套件(bash + PowerShell),用于维护
scripts/open_help.sh
/
scripts/open_help.ps1
本身——该套件在响应用户的
/scrolls-help
请求时不起任何作用。执行本Skill时请勿读取或运行测试套件。