louisecxqiu-glitch/html-doc-center

🎨 HTML Studio

面向 AI 时代的 HTML 编辑器与查看器。

别再一个一个地打开 HTML 文件了。HTML Studio 只需一条命令，就能把任意文件夹变成一个可浏览、可编辑、自动保存的文档中心。

License: MIT
Python 3.10+
Claude Code Plugin

为什么选择 HTML Studio？

AI 编程工具（Claude Code、Cursor、Copilot）会不断生成 HTML 产物——报告、仪表盘、封面图、演示文稿。但接下来你就卡住了：

- 得在浏览器里手动逐个打开文件
- 没有源码就无法编辑
- 没有自动保存，没有版本历史
- 文件散落在各个目录中

HTML Studio 解决了这个问题。 一条命令，所有 HTML 集中一处，即刻可编辑。

快速开始

方式一：下载可执行文件（推荐，零安装）

1. 前往 Releases
2. 下载 HTMLStudio--macos-arm64.dmg（Apple Silicon Mac）或 HTMLStudio.exe（Windows）
3. 在 Mac 上，打开已公证的 DMG 并将 HTML Studio 拖入 Applications；在 Windows 上，双击该 EXE

方式二：双击启动（从源码运行）

1. 下载项目（ZIP 或 git clone https://github.com/louisecxqiu-glitch/html-doc-center.git）
2. 双击 启动 HTMLStudio.command（Mac）或 启动 HTMLStudio.bat（Windows）
3. 浏览器自动打开 → 开始使用

首次运行会自动安装依赖（aiohttp），需要联网。

方式二：命令行

git clone https://github.com/louisecxqiu-glitch/html-doc-center.git
cd html-doc-center
pip install aiohttp
python3 server.py --open-browser
→ http://localhost:9901

或作为 Claude Code 插件使用：
/plugin install htmlstudio@claude-plugins-official

功能特性

| 功能 | 描述 |
|---------|-------------|
| 📁 目录树 | 自动发现所有 HTML/MD 文件，侧边栏可搜索 |
| ✏️ 点击即编辑 | 零配置内联编辑，自动注入工具栏 |
| 💾 智能自动保存 | 空闲 2 秒 → 生成快照；关闭 → 覆盖 / 另存为 / 丢弃 |
| 🔍 Markdown 支持 | 内置 MD 编辑器，带实时预览 |
| ⭐ 收藏与排序 | 收藏文件，按时间或名称排序 |
| 🔄 实时刷新 | 10 秒轮询配合 ETag 签名（99.99% 零流量） |
| 📂 多根目录 | 通过设置界面配置多个扫描目录 |
| 🖱️ 拖放 | 在目录之间移动文件 |
| 🔒 路径安全 | 所有写入均依据 scan_roots 白名单进行校验 |

v3.0：三模式编辑 + AI 文本编辑

v3.0 引入了专业的三模式编辑器内核、AI 辅助文本编辑以及版本历史。

三种编辑模式

打开 HTML 文件时，你会获得三种编辑模式：

| 模式 | 引擎 | 最适合 |
|------|--------|----------|
| 🎨 设计 | GrapesJS | 可视化编辑：拖拽组件、编辑属性、查看布局 |
| 📝 富文本 | ProseMirror | 以文本为中心的编辑：粗体、斜体、列表、链接、标题 |
| </> 源码 | CodeMirror 6 | 直接编辑 HTML/CSS，支持语法高亮、搜索 |

使用顶部工具栏按钮或键盘快捷键（Alt+D/R/S）切换模式。

组件库（区块）

左侧边栏有 14 个可拖拽组件：
- 基础：标题、段落、文本、按钮、链接、分割线、引用、表格
- 布局：容器、双栏
- 媒体：图片、视频
- 列表：无序列表、有序列表

属性面板

右侧边栏显示两个标签页：
- 样式：排版、布局、背景、边框、效果
- 属性：元素 ID、类名、属性

AI 文本编辑

1. 在设计或富文本模式中选择文本
2. 点击 ✨ AI 编辑 按钮（或选区附近的浮动按钮）
3. 输入你的指令（例如“让这段更简洁”“翻译成中文”）
4. 查看差异预览（新增/删除高亮）
5. 点击 接受、拒绝 或 重新生成

- AI 结果绝不会自动应用——你必须审阅并接受
- 只有你选中的文本会发送给 AI（绝不会发送完整文档）
- 每次接受 AI 都会创建一个可撤销操作（Ctrl+Z 可还原）

配置 AI 提供商

编辑 ~/.codebuddy/html-doc-center/config.json 并添加 ai 部分：

{
"ai": {
"default_provider": "openai",
"providers": {
"openai": {
"type": "openai-compatible",
"base_url": "https://api.openai.com/v1",
"model": "gpt-4o-mini",
"api_key": "sk-..."
},
"anthropic": {
"type": "anthropic",
"base_url": "https://api.anthropic.com/v1",
"model": "claude-sonnet-4-20250514",
"api_key": "sk-ant-..."
},
"ollama": {
"type": "openai-compatible",
"base_url": "http://localhost:11434/v1",
"model": "llama3.1",
"api_key": "ollama"
}
}
}
}

或使用环境变量（例如 "api_key_env": "OPENAI_API_KEY"）。

版本历史

HTML Studio 会自动创建版本快照：
- AI 编辑之前（pre-ai）
- 版本恢复之前（pre-restore）
- 当你手动保存时（pre-overwrite / manual）

每个版本都会记录内容哈希、时间戳和原因标签。通过工具栏中的“历史”按钮访问版本历史。

复杂页面保护

带有脚本、框架挂载点（React/Vue）或过多 CSS 规则的页面会被自动检测为“复杂”页面，并默认使用源码模式，以防止可视化编辑改变结构。你可以通过“仍然启用”按钮选择启用可视化编辑。

键盘快捷键

| 快捷键 | 操作 |
|----------|--------|
| Ctrl+Z / Cmd+Z | 撤销 |
| Ctrl+Y / Cmd+Shift+Z | 重做 |
| Alt+D | 切换到设计模式 |
| Alt+R | 切换到富文本模式 |
| Alt+S | 切换到源码模式 |
| Ctrl+F（源码） | 在代码中搜索 |

Claude Code 集成

HTML Studio 作为 Claude Code 插件运行，支持 MCP：

/hotpage ./report.html     # 在 HotPage 中打开文件
/hotpage serve ./outputs   # 提供目录服务

当 Claude Code 生成 HTML 时，它会自动在 HTML Studio 中打开以进行预览和编辑。

MCP 工具

| 工具 | 描述 |
|------|-------------|
| hotpage_open | 打开指定文件 |
| hotpage_status | 检查服务器是否正在运行 |
| hotpage_serve | 开始提供目录服务 |
| hotpage_list | 列出所有已发现的文件 |

架构

┌─────────────────────────────────────────┐
│  Python (aiohttp) — 单进程              │
│  ├─ /api/tree → 目录树 JSON             │
│  ├─ /api/file → 提供 HTML 并            │
│  │              注入 saver-runtime.js   │
│  ├─ /api/save → 覆盖 / 另存为           │
│  └─ /api/settings → 配置 CRUD           │
├─────────────────────────────────────────┤
│  saver-runtime.js（注入到 iframe 中）   │
│  ├─ contentEditable 工具栏              │
│  ├─ 2 秒空闲 → 自动快照                 │
│  ├─ postMessage ↔ 父框架                │
│  └─ 关闭 → 3 选项对话框                 │
├─────────────────────────────────────────┤
│  web/app.js — 侧边栏 + iframe 查看器    │
└─────────────────────────────────────────┘

零依赖，仅需 aiohttp。无需 npm，无需 webpack，无需构建步骤。

配置

配置存储在 ~/.codebuddy/html-doc-center/config.json：

{
"scan_roots": [
{"path": "/Users/me/reports", "enabled": true},
{"path": "/Users/me/outputs", "enabled": true}
]
}

或通过应用内设置面板（⚙️ 按钮）进行配置。

对比

| | HTML Studio | mcp-html-artifacts-preview | File Browser |
|---|---------|---------------------------|--------------|
| 编辑 | ✅ 内联编辑 + 工具栏 | ❌ 仅查看 | ❌ 否 |
| 自动保存 | ✅ 2 秒快照 + 3 选项 | ❌ 否 | ❌ 否 |
| 持久化 | ✅ 文件保留在磁盘上 | ❌ 仅会话 | ✅ 是 |
| 零配置 | ✅ 一条命令 | ✅ MCP 配置 | ⚠️ Docker |
| Claude Code | ✅ 插件 + MCP | ✅ 仅 MCP | ❌ 否 |
| Markdown | ✅ 内置 | ❌ 否 | ❌ 否 |

开发

Run the local development server without opening a browser automatically
python3 server.py --no-open-browser

Then open http://127.0.0.1:9901 in your browser

Run tests
python3 -m pytest tests/

构建可分发应用

python3 -m pip install -r requirements-build.txt
python3 build.py

在 Apple Silicon macOS 上，签名并公证的发布命令为：

python3 scripts/release_macos.py

有关一次性的 Apple 证书和 GitHub Secrets 设置，请参阅 docs/macos-release.md。

微信文章格式化工具

将 Markdown 教程转换成带苹果式内联样式、可直接复制到微信公众号编辑器的单文件 HTML：

python3 tools/wechat_formatter.py path/to/article.md --open

图片路径按 Markdown 文件所在目录解析；脚本会把本地图片内嵌到 HTML。需要指定输出路径时使用 --output，覆盖已有输出时使用 --force。

有关指南，请参阅 CONTRIBUTING.md。

许可证
MIT © Louis Jobs 2026