DOMagic 插件使用说明

1. 插件定位

domagic-vite-plugin 是一个开发态 Vite 插件，核心能力有两类：

1. 在 React / Vue 模板中的原生 DOM 节点上注入源码定位信息
2. 在浏览器页面中直接对目标节点发起“AI 修改样式”，并把修改写回源码文件

它主要用于提升“页面节点 -> 源码位置 -> 样式调整”这一条链路的开发效率。

2. 推荐接入方式

推荐直接在业务项目的 vite.config.ts 中配置插件。

不推荐再通过业务项目 package.json 中的脚本注入大量 DOMAGIC_* 环境变量。

2.1 安装

npm install -D domagic-vite-plugin

或使用其他包管理器安装到开发依赖。

2.2 最小接入示例

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { domagic } from 'domagic-vite-plugin'

export default defineConfig({
  plugins: [
    domagic({
      pathMode: 'relative',
    }),
    react(),
  ],
})

这时插件会：

• 在 vite dev 阶段自动注入 data-domagic-file / data-domagic-line
• 在页面中注入“AI修改样式”浮层按钮
• 在 Vite dev server 上挂载本地接口

3. agent 配置方式

如果你希望插件接入本机 CLI agent，建议直接写在 domagic({...}) 配置中。

3.1 Codex 示例

domagic({
  pathMode: 'relative',
  agent: {
    provider: 'codex',
    cwd: process.cwd(),
    command: '/absolute/path/to/codex',
  },
})

3.2 Claude Code 示例

domagic({
  agent: {
    provider: 'claude-code',
    cwd: process.cwd(),
    command: '/absolute/path/to/claude',
    args: ['--some-flag'],
  },
})

3.3 Gemini 示例

domagic({
  agent: {
    provider: 'gemini',
    cwd: process.cwd(),
    command: '/absolute/path/to/gemini',
    args: ['--some-flag'],
  },
})

3.4 generic-cli 示例

domagic({
  agent: {
    provider: 'generic-cli',
    cwd: process.cwd(),
    command: 'node',
    args: ['./scripts/mock-agent.mjs'],
  },
})

4. 自动探测与优先级

如果不显式指定 provider，插件会按优先级自动探测本机可用 CLI：

codex -> claude-code -> gemini -> generic-cli

你也可以在 vite.config.ts 里显式配置优先级：

domagic({
  agent: {
    priority: ['claude-code', 'codex', 'gemini', 'generic-cli'],
  },
})

5. 完整配置项说明

5.1 domagic(options)

type DomagicOptions = {
  pathMode?: 'absolute' | 'relative'
  root?: string
  fileFormatter?: (id: string, root: string) => string
  agent?: DomagicAgentOptions
}

5.2 agent

type DomagicAgentOptions = {
  provider?: 'codex' | 'claude-code' | 'gemini' | 'generic-cli'
  priority?: Array<'codex' | 'claude-code' | 'gemini' | 'generic-cli'>
  cwd?: string
  command?: string
  args?: string[]
}

6. 配置 CLI 到 PATH

agent.command 是可选项。如果没有显式配置 command，插件会从当前 Node 进程的 PATH 中查找 provider 对应的 CLI：

codex       -> codex
claude-code -> claude / claude-code
gemini      -> gemini / gemini-cli

只要用户在终端里可以直接运行对应命令，DOMagic 一般就能自动识别到。若 CLI 没有加入 PATH，可以按下面步骤配置。

6.1 macOS

确认 CLI 所在目录。注意加入 PATH 的是可执行文件所在目录，不是可执行文件本身。

例如可执行文件路径是：

/Users/you/tools/codex/bin/codex

则需要把这个目录加入 PATH：

echo 'export PATH="/Users/you/tools/codex/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证是否生效：

which codex
codex --version

如果使用 bash，把 ~/.zshrc 换成 ~/.bashrc 或 ~/.bash_profile。

6.2 Windows

确认 CLI 所在目录。例如可执行文件路径是：

C:\Users\you\tools\codex\bin\codex.exe

则需要把下面这个目录加入系统或用户环境变量 Path：

C:\Users\you\tools\codex\bin

操作步骤：

1. 打开“系统属性” -> “高级” -> “环境变量”
2. 在“用户变量”或“系统变量”中找到 Path
3. 点击“编辑” -> “新建”
4. 填入 CLI 所在目录
5. 保存后重新打开终端或 IDE

验证是否生效：

where codex
codex --version

如果 IDE 启动的 dev server 没有继承终端里的 PATH，可以改为在 vite.config.ts 中显式配置：

domagic({
  agent: {
    provider: 'codex',
    command: '/absolute/path/to/codex',
  },
})

或使用对应环境变量启动：

DOMAGIC_CODEX_CMD=/absolute/path/to/codex npm run dev

7. 环境变量策略

当前插件已经改成：

• 优先使用 vite.config.ts 中的插件配置
• 环境变量只作为兜底兼容方案

也就是说，如果你在 domagic({...}) 里写了：

agent: {
  provider: 'codex',
  command: '/abs/path/to/codex',
}

那么它会优先用这里的配置，而不是环境变量。

环境变量仍然兼容这些字段：

• DOMAGIC_AGENT_PROVIDER
• DOMAGIC_AGENT_PRIORITY
• DOMAGIC_CODEX_CMD
• DOMAGIC_CLAUDE_CODE_CMD
• DOMAGIC_GEMINI_CMD
• DOMAGIC_AGENT_CMD
• DOMAGIC_AGENT_ARGS
• DOMAGIC_AGENT_CWD

但现在不推荐把它们作为主配置方式。

8. 使用流程

完整页面侧使用说明见：

• docs/domagic-user-guide.md

8.1 开发阶段

在项目根目录运行：

npm run plugin:watch
npm run dev

说明：

• plugin:watch 负责把插件源码实时编译到 dist
• dev 负责启动真实业务项目

8.2 页面侧操作

启动后：

1. 页面中的原生 DOM 元素会带上 data-domagic-file 和 data-domagic-line
2. 点击目标元素后，会出现“AI修改样式”按钮
3. 输入提示词后，插件会把 { file, line, prompt } 发给本地 dev server
4. 后端生成编辑计划并回写源码
5. 业务项目通过 HMR 或刷新看到样式变化

9. 当前推荐实践

推荐

• 在 vite.config.ts 中集中配置 DOMagic
• pathMode 使用 relative
• 优先让本机 CLI 加入 PATH，必要时再通过 agent.command 显式配置路径
• 开发时常驻 plugin:watch

不推荐

• 在业务项目 package.json 中维护大量 DOMAGIC_* 启动脚本
• 把 agent 路径只放在 shell 环境里，导致团队成员接入方式不统一

10. 调试建议

如果插件没有命中真实 agent，可以先看业务项目 dev 终端日志：

• default runner
• active runner
• cli agent spawn

如果页面上的“AI处理中...”状态变化滞后，优先确认：

1. 是否已使用最新插件产物
2. 是否正在运行 npm run plugin:watch
3. 当前是否走到了本地快路径还是外部 CLI agent

11. 文件参考

核心入口：

• plugins/domagic-vite-plugin/src/index.ts

源码注入：

• plugins/domagic-vite-plugin/src/react-transform.ts
• plugins/domagic-vite-plugin/src/vue-transform.ts

页面 runtime：

• plugins/domagic-vite-plugin/src/runtime.ts

服务端中间件：

• plugins/domagic-vite-plugin/src/server.ts

执行引擎：

• plugins/domagic-vite-plugin/src/engine/orchestrator.ts
• plugins/domagic-vite-plugin/src/engine/context.ts
• plugins/domagic-vite-plugin/src/engine/local-style-runner.ts
• plugins/domagic-vite-plugin/src/engine/agent-runner.ts
• plugins/domagic-vite-plugin/src/engine/provider-selection.ts