Domphy 完全指南：用纯 JavaScript 对象构建 AI 可自修复的工具型 UI

核心概念：toState、Patches、响应式

Domphy 的响应式系统基于三个核心概念：

toState —— 状态容器

toState(initialValue) 创建一个可读写的响应式状态。在组件中，状态通过 getter 函数自动订阅：

const name = toState('World')

const App = {
  div: [
    { h1: (l) => `Hello, ${name.get(l)}!` },
    { input: '', $: [{ value: name }], onInput: (e) => name.set(e.target.value) },
  ],
}

注意 (l) 这个参数——它是 Domphy 的 link 对象，调用 .get(l) 时框架自动追踪依赖关系。这种显式依赖追踪机制让响应式更新精确到最小粒度，不会出现 React 中常见的全组件重渲染问题。

Patches —— 86 个即用 UI 组件

Domphy 提供了 86 个 patches（补丁组件），涵盖按钮、卡片、对话框、动画、错误边界等常用 UI 元素。它们通过 $ 属性挂载到元素上：

import { button, card, dialog } from '@domphy/ui'

const App = {
  div: [
    { button: 'Save', $: [button({ color: 'primary', size: 'lg' })], onClick: handleSave },
    { div: 'Card content here', $: [card({ elevation: 2 })] },
  ],
}

$ 属性接收一个补丁数组，每个补丁为元素添加特定的样式和行为。和 CSS 类名不同，patches 是框架原生支持的，包含完整的设计令牌系统——颜色、间距、尺寸都是上下文感知的。

组合式的响应式原语

除了 toState，Domphy 提供了完整的响应式工具集：

• RecordState：对象级状态管理，可以按 key 单独追踪变更
• computed：派生状态，自动缓存和惰性求值
• effect / effectScope：副作用管理，类似 Vue 的 watch
• batch：批量更新优化，多次 set 合并为一次渲染
• untrack：临时暂停依赖追踪
• flushSync：同步刷新待处理的更新

这套响应式系统的设计借鉴了 Vue 3 和 SolidJS 的优点，但完全基于对象声明——不引入任何模板语法或编译器。

AI 自修复循环：@domphy/doctor

这是 Domphy 最独特的特性，也是它声称"为 AI 而生"的底气所在。

当 AI 助手生成 Domphy 代码后，运行 @domphy/doctor 的 diagnose() 函数，它会：

1. 静态分析生成的元素树
2. 输出诊断报告，指出不合规范的结构、缺失的属性、类型不匹配等问题
3. AI 读取报告后自动修正自己的代码——不需要人来 debug

import { diagnose, fix } from '@domphy/doctor'

// AI 生成的代码（可能有问题）
const aiGeneratedApp = { /* ... */ }

// 诊断
const report = diagnose(aiGeneratedApp)
console.log(report)
// => [{ level: 'error', message: 'Missing required prop "value" on input', ... }]

// 自动修复（lossless —— 不会改变代码语义）
const fixedApp = fix(aiGeneratedApp)

更强大的是，@domphy/doctor 可以通过 Domphy 的 MCP Server 暴露给 AI Agent：

{
  "mcpServers": {
    "domphy": {
      "command": "npx",
      "args": ["@domphy/mcp"]
    }
  }
}

配置后，AI Agent 可以在生成代码的同时调用 doctor 进行自检，形成一个完整的自我修正循环。这在目前的主流 UI 框架中是独一无二的——React/Vue 的 lint 工具只能检查已有代码，而 Domphy 的 doctor 能直接介入 AI 生成流程。

Domphy 还为 AI 准备了完整的"说明书"：

• AGENTS.md：跨工具的 Agent 规范文件，Cursor、Claude Code、Copilot、Codex、Aider 均自动读取
• llms.txt：精选索引，包含规则和所有文档页面的链接
• llms-full.txt：一次性转储——规则 + 快速入门 + 每个包的完整文档，自动生成，永不漂移

TanStack 生态的一比一适配

熟悉 React 生态的开发者会感到亲切：Domphy 提供了 TanStack 全家桶的字节级一比一适配。

API 和上游保持字节级一致，只是加了一层 /domphy 子路径的薄适配。这意味着 AI 助手对 TanStack 的已有训练知识可以直接复用，学习成本接近零。

实际应用场景

AI 生成 Domphy 这种嵌套对象结构的成功率远高于 JSX——对象根本没有标签闭合、className 拼接、children 传递这些常见出错点。几个典型场景：

• 浏览器插件面板：文件体积受限于 CRX 标准，Domphy 核心运行时极小巧，不需要打包整个 React
• 内部工具和后台管理：86 个 patches 覆盖按钮、表格、对话框、分页，写法简洁

const metrics = toState({ cpu: 0, memory: 0 })

const Dashboard = {
  div: [
    { h1: 'System Monitor' },
    { div: [{ h3: 'CPU' }, { div: (l) => `${metrics.get(l).cpu}%` }] },
    { div: [{ h3: 'Memory' }, { div: (l) => `${metrics.get(l).memory}%` }] },
  ],
}

AI 驱动的仪表盘生成在这种模式下效率极高——你只需要描述结构，不需要关心 hooks 和 props 的细节。

注意事项与局限性

Domphy 并非 React 的"平替"——它有明确的适用边界：

• ✅ 适合：工具面板、插件界面、仪表盘、管理后台、原型快速搭建
• ❌ 不适合：面向消费者的高交互产品、需要大量第三方 React 组件的项目、SEO 重度的内容网站
• 生态现状：项目目前只有 1 个 GitHub star（截至 2026 年 6 月），社区极其早期
• 学习曲线：开发者需要适应"UI 即对象"的心智模型，不能直接搬运 React 思维

总结

Domphy 的核心理念颇具前瞻性：与其让 AI 适应 UI 框架，不如让 UI 框架适应 AI。通过将 UI 定义为纯 JavaScript 对象、提供自动诊断和修复工具、内置完整的 AI Agent 接入规范，Domphy 在"AI 辅助 UI 开发"这条路上走了一条大胆而新颖的路。

如果你经常用 Claude Code、Cursor 或 Copilot 写前端代码，尤其是工具型应用的 UI，Domphy 值得一试。开局一个 npm create domphy，然后用自然语言描述你的界面结构，让 AI 为你生成可运行的嵌套对象——这个 workflow 比传统的"生成 JSX → 修 bug → 再生成"循环高效得多。

参考链接：

• Domphy 官网
• Domphy 文档
• GitHub 仓库
• npm 包 @domphy/core
• AI 开发指南
• @domphy/doctor 文档