用HTML代替Markdown跟Agent交互靠谱么？我做了个脚手架|agent|html|markdown|websocket|脚手架

TL;DR：

Agent 不再把 Markdown 塞进聊天窗口，而是维护一个可交互的 HTML 工作台——人类在页面上操作，Agent 读取状态继续推进。
我做了个开源脚手架来验证这件事，测试效果很爽，已开源。

0. 起因：Claude Code 负责人的一篇文章

前两天 Anthropic 的 Claude Code 团队成员 Thariq Shihipar 发了一篇博客：

《The Unreasonable Effectiveness of HTML》

核心观点足够颠覆——

当你跟 Agent 协作时，应该要求它输出 HTML 而不是 Markdown。

为什么？

因为 Markdown 本质上是一种线性文本格式。

它能做的事情，HTML 全都能做，且做得更好：SVG 图表、可折叠面板、颜色编码、交互式组件、页面内导航……

而 Markdown 在这些场景下只有纯文本。

这篇文章让我想到一个更远的问题：

如果 HTML 比 Markdown 更适合 Agent输出，那它能不能更进一步——成为 Agent 跟人类双向交互的介质？

于是我做了个脚手架来验证这件事。

1. 问题：Markdown 对话的根本瓶颈

先看一个你一定经历过的场景——

你让 Agent 帮你做项目规划，它输出了一个优先级列表：

Q2 功能优先级：
1. 功能 A (P0)
2. 功能 B (P1)
3. 功能 C (P2)

你想把功能 B 提到 P0，于是打字说："功能 B 应该提到 P0，功能 A 降到 P1"。Agent 收到后重新输出一遍列表。

这个循环有两个根本问题：

第一，信息是"读后即焚"的。上下文存在于对话流中，滚动即消失。你必须不断回滚才能看到之前的决策。

第二，人类只能用自然语言回复。Agent 输出了结构化数据（优先级列表），但人类的反馈方式是非结构化文本。Agent 需要重新解析"功能 B 提到 P0"这句话，才能理解你的意图。这一步不仅低效，还容易出错。

Thariq 的文章解决了第一个问题——用 HTML 做更丰富的输出。但它仍然是单向的：Agent 输出 HTML，人类阅读，然后用自然语言回复。

我们需要的是双向闭环。

这里之所以用“我们”，是因为项目完全是由 Hermes 开发的。

WS Workspace 是一个开源脚手架，它可以实现：

人和 Agent 一起在一个网页里交互完成上下文构建
Agent 根据人的需求生成网页，人来点选做出决策，Agent 接受、执行
所有协作过程留在网页上，随着项目一期生长

实现方式：

一套脚手架，项目启动时直接初始化一套空的网页交互环境
提供 CLI 和 Skills，Agent 可以使用 CLI 向网页中注入需要的组件
通过 MCP 服务，接收用户在网页的操作，回传给 Agent 作为上下问

整个架构是一个三层闭环：

Agent  ──CLI 指令──→  服务器  ──WebSocket──→  浏览器（人类操作）
Agent  ←──REST API──  服务器  ←──WebSocket──  浏览器（状态回流）

Agent 不大量写 HTML/CSS/JS。它只需要使用 CLI 发命令：

ws add kanban --columns "想法,评估中,已确认"
ws add decision-card --question "先做哪个？" --options "功能A|功能B|功能C"

人类不需要打字。直接在页面上拖拽卡片、点选方案、填写表单。

action-to-context

Agent 读取结构化状态：

ws state
→ {"selected": "功能B", "kanban": {"已确认": ["功能B"]}}

没有歧义，不需要 NLU 解析，没有"我以为你说的是 P0 不是 P1"的问题。

3. 组件体系：7 个组件覆盖 80% 场景

我们没有一开始就做 50 个组件。第一版只做了 7 个核心组件，但它们能覆盖 Agent 跟人类协作的绝大多数场景：

组件用途人类操作 → Agent 收到的数据Kanban 看板优先级排序、状态跟踪拖拽位置、新增/编辑卡片Decision Card 决策卡方案选择、A/B 决策选了哪个选项 + 备注✅ Todo List 待办任务清单、验收标准勾选/取消/新增/编辑Form 表单结构化输入完整表单数据 JSONTable 表格数据对比、规格展示单元格编辑✏️ Rich Editor 编辑器自由书写、头脑风暴富文本内容Heading 标题分区、上下文说明纯展示

每个组件的使用方式都是一条 CLI 命令。Agent 不需要写前端代码，只需要描述意图。

举个例子，下面是 Agent 注入一个决策卡的完整流程：

# Agent 发指令
ws add decision-card \
  --question "技术方案选型" \
  --options "原生WebSocket|Socket.IO|SSE"

 # 人类在页面上点选了"Socket.IO"

 # Agent 读取结果
ws state decision-card-xxx
→ {"selected": "Socket.IO", "comment": "自动重连很重要"}

就这么简单。

4. 看起来什么样

下面是一个真实的工作台截图。所有组件都是 Agent 通过 CLI 指令注入的，人类可以在页面上直接操作：

选题规划看板，选完直接激活子 Agent 开写

课程形式设计，菜单式选择，可以补充说明，Agent 就可以直接开干

Agent 需要根据定价设计课程宣发？给个表单让人填写

所有这些组件，Agent 只用了1 条 CLI 命令 + 参数就注入完毕。

人只需要守在网页前面点点点

5. 跟传统方案比，多了什么能力 Markdown 聊天 Claude Artifacts HTML 工作台信息密度 ✕ 纯文本 ✓ 富 HTML ✓ 富 HTML + 交互组件双向交互 ✕ 只能打字 △ 有限表单 ✓ 拖拽/选择/填写状态持久性 ✕ 滚动即消失 △ Artifact 内保留 ✓ 持久页面，状态累积 Agent 驱动 ✕ Agent 写文本 △ Agent 生成代码 ✓ CLI 指令注入可分享性 ✕ 截图/复制 △ 需 Claude 账号 ✓ 链接直接打开 Agent 读取状态 ✕ 需解析自然语言 ✕ 无法读取 ✓ 结构化 JSON API

最关键的区别是最后一行：Agent 能不能读取人类的操作结果。

在 Markdown 对话中，Agent 只能读到人类打的字。在 Claude Artifacts 中，Agent 根本无法感知人类在 Artifact 里做了什么。

但在 HTML 工作台中，Agent 通过 REST API 获取完整的结构化状态——哪个选项被选中了、卡片被拖到了哪一列、表单填了什么值——全部是 JSON，零歧义。

6. 技术实现：简单到出乎意料

整个项目只有两个运行时依赖：

{
  "dependencies": {
    "express": "^5.2.1",
    "ws": "^8.20.0"
  }
}

没错，就是 Express + WebSocket。没有 React，没有构建工具，没有框架。

ws-workspace/
├── server.js          # Express + WebSocket 服务器（约 400 行）
├── ws-cli.js          # Agent CLI 工具（12 个子命令）
├── mcp-server.js      # MCP 服务器（8 个工具，JSON-RPC stdio）
├── public/
│   └── index.html     # 前端工作台（单文件，内联 CSS + JS）
└── skills/
    └── ws-workspace.md # Agent Skill（使用指南）

三层设计：

CLI 层（Agent 的手）：ws addws statews update，声明式操作，返回 JSON
MCP 层（Agent 的耳）：WebSocket 双向通道，wait_for_user可暂停等待交互
Skill 层（Agent 的脑）：告诉 Agent 有哪些组件、怎么用、什么场景用什么

前端是一个单 HTML 文件，所有组件通过 Web Components 渲染。Claude 暖色调主题，卡片式布局。用户操作自动通过 WebSocket 同步到服务器。

一行命令启动：

npx ws-workspace start

7. 一些踩过的坑

做这个项目的过程中踩了不少坑，挑几个有意思的分享：

人的备注：是 Hermes 踩的坑，我测试发现问题让它改的，它写到文章里了。

坑 1：IME 拼音输入被打断

最初的版本里，决策卡的备注框用oninput实时同步状态。但oninput→sendEvent()→ 服务器广播 →renderAll()会销毁整个 DOM 重建，导致中文拼音输入法的组合状态被打断——你按 "zh" 想打"中"，结果 "z" 刚上屏就被清空了。

修复：所有文本输入组件改为「本地编辑 + 显式保存按钮」模式。只在用户点"保存"时才同步状态，不再实时广播。

坑 2：Kanban 拖拽的 ondragover

HTML5 的拖拽 API 有个反直觉的坑：ondragover必须调preventDefault()，否则ondrop事件根本不会触发。这个 bug 让我调试了半小时。

坑 3：组件 ID 生成

一开始让客户端自选 ID，结果两个人同时添加组件时 ID 冲突。后来改成服务端生成{type}-{random_hex}格式，彻底解决。

8. 这件事靠不靠谱？

说实话，目前还是实验性项目。但有几个观察让我觉得方向是对的：

1. Agent 天生就擅长结构化输出。

让 Agent 生成一条ws add kanban --columns "待办,进行中,完成"指令，比让它生成一整段 Markdown 列表要简单得多。指令是结构化的，Agent 出错的概率更低。

2. 人类天生就擅长视觉操作。

拖拽一张卡片到"已确认"列，比打字说"把功能 B 从评估中移到已确认"更直观、更快、更不容易出错。

3. 状态不需要"理解"，只需要"读取"。

Agent 不再需要做 NLU（自然语言理解）来解析人类的回复。状态就是 JSON，直接读，零歧义。

9. 如何开始

# 一行命令启动
npx ws-workspace start

 # Agent 注入组件
ws init "我的工作台"
ws add kanban --columns "想法,评估中,已确认"
ws add decision-card --question "选哪个？" --options "A|B|C"
ws add todo-list --title "待办" --items "任务1,任务2"

 # 读取人类操作结果
ws state

GitHub 仓库：comeonzhj/ws-workspace[1]

npm 包：npm install ws-workspace

如果你无法访问 GitHub，可以在知识星球下载压缩包，解压后让 Claude Code 或者其他 Agent 完成剩下的事情。