comment-to-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comment to Fix

Comment to Fix — point at HTML, comment, get the fix.

Use this skill when the user wants to review an HTML slide, proposal, landing page, or static site section and have you implement changes in a continuous loop.

Comment to Fix — 指向HTML元素、添加评论、获取修复方案。

当用户想要审阅HTML幻灯片、提案、着陆页或静态站点板块，并希望你持续循环实现修改时，使用此Skill。

Install (once per machine)

安装（每台机器只需一次）

bash

npx skills add ralfboltshauser/comment-to-fix

The CLI itself runs via:

bash

npx comment-to-fix [file.html] [--open]
pnpm dlx comment-to-fix [file.html] [--open]
bunx comment-to-fix [file.html] [--open]

Defaults to

./index.html

in the current working directory.

bash

npx skills add ralfboltshauser/comment-to-fix

CLI本身可通过以下方式运行：

bash

npx comment-to-fix [file.html] [--open]
pnpm dlx comment-to-fix [file.html] [--open]
bunx comment-to-fix [file.html] [--open]

默认使用当前工作目录下的

./index.html

。

When the user runs

/comment-to-fix

当用户运行/comment-to-fix命令时

Non-negotiable behavior

必须遵守的行为规则

Running this skill means opening the preview and then attaching to the Comment to Fix CLI inbox with
watch --once
. The agent must not finish the turn just because the preview opened.

After the preview starts, immediately run
```
npx comment-to-fix watch --once --inbox <inbox>
```
using the exact
```
Inbox
```
path printed by the preview.
```
watch --once
```
is expected to hang while it waits for the next sent comment. Leave it running and keep the session attached.
After every fix and
```
mark-processed
```
, immediately start a fresh
```
watch --once --inbox <inbox>
```
unless the user explicitly says stop / done / exit comment to fix.
A Comment to Fix session is only complete when the user explicitly stops it or the preview/watch process cannot be started.

运行此Skill意味着打开预览窗口然后通过
watch --once
连接到Comment to Fix CLI收件箱。Agent不能仅因为预览窗口打开就结束会话。

预览启动后，立即使用预览窗口输出的准确
```
Inbox
```
路径运行
```
npx comment-to-fix watch --once --inbox <inbox>
```
。
```
watch --once
```
会处于挂起状态以等待下一条发送的评论，需保持其运行并维持会话连接。
每次修复完成并执行
```
mark-processed
```
后，除非用户明确表示停止/完成/退出Comment to Fix，否则立即启动新的
```
watch --once --inbox <inbox>
```
。
只有当用户明确停止，或预览/监听进程无法启动时，Comment to Fix会话才会结束。

1. Resolve the HTML entry file

1. 解析HTML入口文件

Use the path the user provided, otherwise
```
./index.html
```
in the project root
If missing, stop with a clear error

使用用户提供的路径，否则使用项目根目录下的
```
./index.html
```
如果文件缺失，需停止操作并给出清晰的错误提示

2. Ensure inbox is gitignored

2. 确保收件箱被Git忽略

Add

.comment-to-fix/

.gitignore

if it is not already ignored.

如果

.comment-to-fix/

尚未被忽略，请将其添加到

.gitignore

文件中。

3. Start preview in a background terminal

3. 在后台终端启动预览

bash

npx comment-to-fix [file.html] --open

Use

pnpm dlx

bunx

only if the user explicitly prefers that package manager. Default to

npx

for compatibility.

Read the preview output before continuing. It prints three lines you must capture for this session:

Comment to Fix preview: http://127.0.0.1:5174/index.html
Port: 5174
Inbox: /abs/path/.comment-to-fix/inbox-5174.jsonl

The port auto-increments when a port is busy, so never assume 5173 — use the URL it printed.
The
```
Inbox
```
path is port-scoped so multiple Comment to Fix sessions run in parallel without colliding. Remember this exact path and pass it as
```
--inbox <inbox>
```
to every
```
watch
```
and
```
mark-processed
```
call in this session.

Tell the user:

Comment to Fix is open and ready for feedback. Point at anything and leave a comment. Use Copy (C) to copy all feedback as markdown, or Send on each comment for the agent loop. Say stop when you're done.

bash

npx comment-to-fix [file.html] --open

仅当用户明确偏好特定包管理器时，才使用

pnpm dlx

或

bunx

。为保证兼容性，默认使用

npx

。

继续操作前请读取预览输出内容。它会打印三行你必须为本次会话记录的信息：

Comment to Fix preview: http://127.0.0.1:5174/index.html
Port: 5174
Inbox: /abs/path/.comment-to-fix/inbox-5174.jsonl

端口会在被占用时自动递增，因此切勿默认使用5173——请使用输出的URL。
```
Inbox
```
路径是端口专属的，因此多个Comment to Fix会话可并行运行而互不冲突。请记住此准确路径，并在本次会话的所有
```
watch
```
和
```
mark-processed
```
调用中作为
```
--inbox <inbox>
```
参数传入。

告知用户：

Comment to Fix已开启并准备好接收反馈。指向任意元素并添加评论。使用复制（C）将所有反馈复制为Markdown格式，或对每条评论点击发送以触发Agent循环。完成后请说停止。

Overlay shortcuts

叠加层快捷键

Shortcut	Action
`Cmd/Ctrl+Shift+F`	Toggle feedback mode
`P`	Pause/resume animations
`H`	Hide/show markers
`L`	Toggle comment history
`C`	Copy all feedback
`X`	Clear all
`Esc`	Exit mode / cancel popup
`Enter`	Submit comment (in popup)

Annotation modes: click element, select text then click (or use selection chip), Cmd+Shift+click multi-select, drag area on empty space, pause animations first for motion states.

快捷键	操作
`Cmd/Ctrl+Shift+F`	切换反馈模式
`P`	暂停/恢复动画
`H`	显示/隐藏标记
`L`	切换评论历史
`C`	复制所有反馈
`X`	清空所有内容
`Esc`	退出模式/取消弹窗
`Enter`	提交评论（弹窗中）

注释模式：点击元素、选中文本后点击（或使用选择芯片）、Cmd+Shift+Click多选、在空白区域拖动选择范围、针对动态状态可先暂停动画。

Marker lifecycle (after Send)

标记生命周期（发送评论后）

When a comment is sent (not just copied), markers show async progress:

Marker	Meaning
Spinner	Agent has not marked this comment processed yet
Green eye	Agent ran `mark-processed` — fix is ready
Hidden	User dismissed the marker (still listed in history)

Green eye click reloads the page to apply deferred HTML/JS fixes (dismisses all ready markers). CSS-only fixes may already be visible via hot reload.
Dismiss (×) hides the marker without deleting it from history.
Lifecycle requires Clear after send to stay off in overlay settings.

当评论被发送（而非仅复制）时，标记会显示异步进度：

标记	含义
加载 spinner	Agent尚未标记此评论为已处理
绿色眼睛	Agent已执行 `mark-processed` ——修复已完成
隐藏	用户已关闭标记（仍会在历史记录中列出）

点击绿色眼睛会重新加载页面以应用延迟的HTML/JS修复（会关闭所有已就绪的标记）。仅CSS修复可能已通过热重载实时显示。
点击**关闭（×）**会隐藏标记，但不会从历史记录中删除。
此生命周期要求叠加层设置中的“发送后清空”保持关闭状态。

Comment history

评论历史

The toolbar History button (list icon) opens all comments for the current page. Click a row to scroll to that element and highlight it.

When implementing fixes, always run

mark-processed

after the change — that turns the marker green so the user knows the agent finished.

工具栏的历史按钮（列表图标）会打开当前页面的所有评论。点击某一行会滚动到对应元素并高亮显示。

实现修复后，务必在修改完成后执行

mark-processed

——这会将标记变为绿色，让用户知道Agent已完成修复。

4. Watch loop — do not stop after one fix

4. 监听循环——完成一次修复后请勿停止

Repeat until the user explicitly says stop / done / exit comment to fix:

Run (use the

Inbox

path from step 3):

bash

npx comment-to-fix watch --once --inbox <inbox>

Parse the JSON line printed to stdout

Implement the smallest correct fix in files under

annotation.root

using:

```
annotation.comment
```
```
annotation.selector
```
```
annotation.path
```
```
annotation.text
```
```
annotation.page
```

Run:

bash

npx comment-to-fix mark-processed --id <annotation.id> --inbox <inbox>

Reply briefly with what changed and: Waiting for your next comment…
Go back to step 1

For the default session (port 5173) the
--inbox
flag is optional — it defaults to
.comment-to-fix/inbox.jsonl
. Always pass it when running parallel sessions so each loop reads its own inbox.

Critical rules:

Starting the preview alone is incomplete — always attach to the CLI watcher with
```
watch --once
```
Never treat a single annotation as task completion
Never poll
```
.comment-to-fix/inbox.jsonl
```
manually — always use
```
watch --once
```
After each fix, immediately run
```
watch --once
```
again unless the user interrupted
Prefer grep/search using
```
selector
```
, classes, and visible text in
```
annotation.root
```

重复以下步骤，直到用户明确表示停止/完成/退出Comment to Fix：

运行（使用步骤3中的

Inbox

路径）：

bash

npx comment-to-fix watch --once --inbox <inbox>

解析标准输出打印的JSON行

使用以下信息，在

annotation.root

下的文件中实现最小且正确的修复：

```
annotation.comment
```
```
annotation.selector
```
```
annotation.path
```
```
annotation.text
```
```
annotation.page
```

运行：

bash

npx comment-to-fix mark-processed --id <annotation.id> --inbox <inbox>

简要回复修改内容，并附上：等待你的下一条评论…
返回步骤1

对于默认会话（端口5173），
--inbox
标记是可选的——它默认使用
.comment-to-fix/inbox.jsonl
。并行运行会话时务必传入此参数，确保每个循环读取自己的收件箱。

关键规则：

仅启动预览窗口是不完整的——务必通过
```
watch --once
```
连接到CLI监听器
切勿将单个注释视为任务完成
切勿手动轮询
```
.comment-to-fix/inbox.jsonl
```
——务必使用
```
watch --once
```
每次修复后，除非用户中断，否则立即重新运行
```
watch --once
```
优先使用
```
selector
```
、类名和
```
annotation.root
```
中的可见文本进行 grep/搜索

5. Teardown when the user says stop

5. 用户要求停止时的清理步骤

Kill the background preview process
Summarize what was changed in the session
Do not keep calling
```
watch --once
```

终止后台预览进程
总结本次会话中的修改内容
停止调用
```
watch --once
```

Annotation payload shape

注释负载结构

Each

watch --once

prints one JSON object like:

json

{
  "id": "ann_abc123",
  "comment": "Make the hero headline shorter",
  "page": "apps/landing/index.html",
  "root": "apps/landing",
  "selector": "h1",
  "path": "main > section.hero > h1",
  "text": "Tell your page what should change",
  "markdown": "..."
}

Use

markdown

for the human-readable brief if helpful.

每次

watch --once

会打印一个如下所示的JSON对象：

json

{
  "id": "ann_abc123",
  "comment": "Make the hero headline shorter",
  "page": "apps/landing/index.html",
  "root": "apps/landing",
  "selector": "h1",
  "path": "main > section.hero > h1",
  "text": "Tell your page what should change",
  "markdown": "..."
}

如果有帮助，可使用

markdown

字段获取人类可读的简要说明。

Live reload

实时重载

The preview server reloads when HTML/CSS/JS files change under the served root. During feedback mode, full page reloads are deferred so you don't lose scroll position or a comment in progress — CSS updates apply silently; HTML/JS changes apply when the user clicks a green eye marker or presses Esc to exit feedback mode. After you implement a fix, the user should see CSS changes immediately and structural changes after reload (via green eye or exit).

当服务根目录下的HTML/CSS/JS文件发生变化时，预览服务器会自动重载。在反馈模式下，全页面重载会被延迟，以免丢失滚动位置或正在编辑的评论——CSS更新会静默生效；HTML/JS修改会在用户点击绿色眼睛标记或按Esc退出反馈模式后生效。你完成修复后，用户应能立即看到CSS变化，而结构变化需重新加载后生效（通过绿色眼睛标记或退出反馈模式）。

Troubleshooting

故障排查

No overlay: run
```
npx comment-to-fix --help
```
and ensure the preview process is still running
Missing index.html: ask the user which HTML file to preview or create one
watch hangs: that is expected — it waits for the next comment

无叠加层：运行
```
npx comment-to-fix --help
```
并确认预览进程仍在运行
缺少index.html：询问用户要预览哪个HTML文件，或创建一个新文件
watch进程挂起：这是正常现象——它正在等待下一条评论