html-collab — Project Introduction html-collab — 项目介绍

html-collab is a lightweight, open-source format for LLM–human collaborative document editing. It represents an entire working document — content, annotations, and inline edits — as a single self-contained .html file that can be opened in Chrome, annotated by a human, and fed back to an LLM for the next revision cycle. html-collab 是一种轻量、开源的 LLM–人类协作文档编辑格式。它将整个工作文档（内容、批注和内联编辑）表示为单个自包含的 .html 文件，可在 Chrome 中打开，由人类批注，然后反馈给 LLM 进行下一轮修订。

Unlike heavyweight collaborative editing platforms, html-collab requires no server, no install, and no account. The file itself is the collaboration medium: everything the AI needs to understand human feedback is embedded directly inside the HTML, readable by any text model or multimodal model. 与庞杂的协作编辑平台不同，html-collab 无需服务器、无需安装、无需账号。文件本身就是协作媒介：AI 理解人类反馈所需的一切都直接嵌入在 HTML 中，任何文本模型或多模态模型都可以读取。

The html-collab skill is designed to be compatible with both OpenClaw and Claude Code — any AI environment that supports the skill format can participate in the review cycle. 该 skill 专为兼容 OpenClaw 和 Claude Code 而设计——任何支持 skill 格式的 AI 环境均可参与协作审阅循环。

The Collaboration Cycle 协作循环

html-collab defines a three-mode workflow that turns a single file into a complete human-AI editing loop: html-collab 定义了三种操作模式，将单个文件转变为完整的人机编辑循环：

  • GENERATE — The LLM produces a structured HTML document from the collab-template, assigning stable data-cid identifiers to every block element and initializing an empty annotation data island. 生成（GENERATE） — LLM 从 collab-template 生成结构化 HTML 文档，为每个块级元素分配稳定的 data-cid 标识符，并初始化空的批注数据岛。
  • Annotate — The human opens the file in Chrome. They select text to leave comments (with optional screenshot pastes), or hover over paragraphs to make inline edits with tracked diffs. All feedback is serialized into the file's JSON island on save. 批注（Annotate） — 人类在 Chrome 中打开文件，选择文本留下评论（可选截图粘贴），或悬停在段落上进行带追踪差异的内联编辑。保存时，所有反馈序列化到文件的 JSON 数据岛中。
  • REVISE — The annotated file is fed back to the LLM. The model applies human edits verbatim, addresses comments, and produces a new clean version — resetting the annotation layer for the next round. 修订（REVISE） — 带批注的文件反馈给 LLM。模型逐字应用人类编辑，解决评论，生成新的干净版本，重置批注层以备下一轮。

Distributed Collaboration 分布式协作

html-collab is designed not just for a single human–AI pair, but for distributed teams. When a colleague sends you an annotated html-collab file — by email, shared folder, or any file transfer — you do not need to be in the same environment or use the same AI tool. Every html-collab document carries an embedded AI Bootstrap comment that automatically directs any compatible AI assistant (Claude Code, OpenClaw, or any skill-compatible environment) to locate and load the html-collab skill before proceeding. html-collab 的设计不只服务于单一的人机协作对，而是面向分布式团队。当同事将一份带批注的 html-collab 文件发给你——无论通过邮件、共享文件夹还是任何文件传输方式——你无需处于相同的环境，也无需使用相同的 AI 工具。每个 html-collab 文档都内嵌 AI Bootstrap 注释，会自动引导任何兼容的 AI 助手（Claude Code、OpenClaw 或任何支持 skill 的环境）在继续工作前找到并加载 html-collab skill。

The file itself carries everything needed to continue the collaboration: content, annotations, edit history, and the AI onboarding instructions. No shared server, no account, no synchronization service required. A team distributed across time zones, using different AI tools, can pass a single file back and forth and maintain a coherent, traceable revision history. 文件本身携带了继续协作所需的一切：内容、批注、编辑历史，以及 AI 上手所需的说明。无需共享服务器、无需账号、无需同步服务。跨时区、使用不同 AI 工具的团队，可以通过传递单个文件来维护连贯、可追溯的修订历史。

File Format 文件格式

Every html-collab document is a single .html file with four logical layers embedded in it: 每个 html-collab 文档都是单个 .html 文件，内嵌四个逻辑层：

  • Content layer — <article id="collab-content">: the LLM-generated document body, with every block element carrying a stable data-cid attribute (e.g. p-001, h-002, sec-001). 内容层 — <article id="collab-content">：LLM 生成的文档正文，每个块级元素都带有稳定的 data-cid 属性（如 p-001、h-002、sec-001）。
  • Data layer — <script type="application/json" id="collab-data">: a JSON island holding all comments, inline edits, and document metadata. Not executed by the browser; readable by any LLM. 数据层 — <script type="application/json" id="collab-data">：持有所有评论、内联编辑和文档元数据的 JSON 数据岛。不被浏览器执行；任何 LLM 都可读取。
  • Style layer — <style id="collab-styles">: inlined CSS providing the full annotation UI — header, comment sidebar, highlight styles, edit diff display. 样式层 — <style id="collab-styles">：内联 CSS，提供完整的批注 UI——顶栏、评论侧边栏、高亮样式、编辑差异显示。
  • Engine layer — <script id="collab-engine">: inlined vanilla JavaScript (~600 lines) that drives the entire annotation experience. Zero npm dependencies; no build step required to view. 引擎层 — <script id="collab-engine">：内联原生 JavaScript（约 600 行），驱动整个批注体验。零 npm 依赖；无需构建步骤即可查看。

Key Features 核心特性

  • Portable — One .html file carries everything: content, annotations, styles, and engine. Email it, commit it, or drop it in a shared folder. 可移植 — 单个 .html 文件携带一切：内容、批注、样式和引擎。可通过邮件发送、提交到 git 或放入共享文件夹。
  • AI-native — The JSON data island is designed to be read and written by LLMs. The extractLLMContext() utility formats all human feedback into a clean, compact context block for model consumption. AI 原生 — JSON 数据岛专为 LLM 读写设计。extractLLMContext() 工具将所有人类反馈格式化为简洁的上下文块，供模型消费。
  • Screenshot support — Humans can paste screenshots directly into comments (Ctrl+V). Images are stored as base64 inside the file, with a configurable size limit and automatic placeholder substitution when building LLM context. 截图支持 — 人类可以直接粘贴截图到评论中（Ctrl+V）。图片以 base64 格式存储在文件内，可配置大小限制，构建 LLM 上下文时自动替换为占位符。
  • Inline diff tracking — Edited paragraphs show strikethrough originals alongside green revised text. The diff is stored in collab-data.edits so the LLM always has both versions. 内联差异追踪 — 已编辑的段落显示带删除线的原始文本和绿色的修订文本。差异存储在 collab-data.edits 中，LLM 始终可以看到两个版本。
  • Zero dependencies — Built with vanilla JS, native CSS, and the browser's File System Access API. Node.js built-in node:test covers the test suite. No npm install ever required. 零依赖 — 使用原生 JS、CSS 和浏览器 File System Access API 构建。Node.js 内置 node:test 覆盖测试套件。无需 npm install。

Getting Started 快速开始

To use html-collab as a human reviewer: 作为人类审阅者使用 html-collab：

  • Open any .html file built with html-collab in Chrome (desktop). 在 Chrome（桌面版）中打开任何基于 html-collab 构建的 .html 文件。
  • Select text and click + Comment to annotate. Paste a screenshot with Ctrl+V to attach it to the comment. 选择文本并点击 + Comment 进行批注，按 Ctrl+V 粘贴截图附加到评论。
  • Hover over any paragraph and click ✎ Edit to make an inline edit. Press Ctrl+Enter to confirm — the original and revised text are both saved. 悬停在任意段落上并点击 ✎ Edit 进行内联编辑，按 Ctrl+Enter 确认——原始文本和修订文本均会保存。
  • Press Ctrl+S to save the annotated file. Hand it back to the LLM for the next revision. 按 Ctrl+S 保存带批注的文件，将其返回给 LLM 进行下一轮修订。

To use html-collab as an LLM, load skill/SKILL.md and follow the GENERATE, READ, or REVISE instructions appropriate to the current task. 作为 LLM 使用 html-collab，请加载 skill/SKILL.md 并按照适用于当前任务的 GENERATE、READ 或 REVISE 指令操作。

Design Principles 设计原则

html-collab is built around three constraints that guided every design decision: the document must be completely self-contained (no external assets or servers), the format must be readable by both humans and LLMs without any special tooling, and the annotation layer must never get in the way of the content layer. These constraints make it suitable for async, offline, and air-gapped workflows where a simpler tool would require a live connection. html-collab 围绕三个约束构建，这些约束指导了每一个设计决策：文档必须完全自包含（无外部资产或服务器），格式必须无需任何特殊工具即可被人类和 LLM 读取，批注层绝不能妨碍内容层。这些约束使其适用于异步、离线和气隙工作流，而简单工具在这些场景下需要实时连接。

The project is MIT licensed and designed to be forked, extended, and embedded. The engine source lives in dev/src/engine.js and dev/src/utils.js; the build step is a single node dev/build.js with no dependencies. Contributions welcome. 该项目采用 MIT 许可证，设计为可派生、扩展和嵌入的。引擎源码位于 dev/src/engine.js 和 dev/src/utils.js；构建步骤只需一个无依赖的 node dev/build.js。欢迎贡献。