domscribe

Domscribe

Domscribe 连接运行中的 UI 与源代码。它会将每个已渲染元素映射到其精确的源代码位置，并捕获实时运行时上下文（props、state、DOM）。这支持两个方向：

• UI → Code：用户在浏览器中点击一个元素，Domscribe 会将其捕获为注释，其中包含源代码位置、运行时上下文和用户意图。你认领并实现它。
• Code → UI：你正在编辑源文件，想知道某个元素在运行时的样子。按文件和行号查询，即可获取实时 props、state 和 DOM 快照。

设置 / 初始化

如果 domscribe.status 返回 active: false，说明此工作区尚未配置 Domscribe。使用 Domscribe bundler 插件启动 dev server 后，会自动创建 .domscribe/ 目录。按以下步骤进行设置：

1. 确认未激活状态 — 调用 domscribe.status。如果 active: false，继续操作。记下响应中的 cwd。
2. 检测框架 — 读取 package.json（位于 cwd，或存在 domscribe.config.json 时位于其中的 appRoot），并根据下表匹配依赖项。
3. 检测包管理器 — 检查项目根目录中存在的锁文件。
4. 安装包 — 通过 Bash 运行相应的安装命令（例如，pnpm add -D @domscribe/next）。
5. 编辑 bundler 配置 — 读取配置文件并应用集成模式。加载 references/config-patterns.md，查看各框架对应的精确导入、转换和示例。
6. 更新 .gitignore — 如果尚未列出 .domscribe，则追加 # Domscribe artifacts 注释和 .domscribe 条目。
7. 告知用户 — 提醒他们启动（或重启）dev server。Domscribe 会在首次运行时自动激活。

框架检测

检查 package.json 中的 dependencies 和 devDependencies。按表格从上到下匹配（以第一个匹配项为准）：

依赖项	框架
next	next
nuxt	nuxt
react + vite	react-vite
react（无 vite）	react-webpack
vue + vite	vue-vite
vue（无 vite）	vue-webpack
仅 vite	other-vite
仅 webpack	other-webpack

包映射

框架	包	配置文件
next	@domscribe/next	next.config.ts
nuxt	@domscribe/nuxt	nuxt.config.ts
react-vite	@domscribe/react	vite.config.ts
react-webpack	@domscribe/react	webpack.config.js
vue-vite	@domscribe/vue	vite.config.ts
vue-webpack	@domscribe/vue	webpack.config.js
other-vite	@domscribe/transform	vite.config.ts
other-webpack	@domscribe/transform	webpack.config.js

包管理器检测

锁文件	包管理器
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lock / bun.lockb	bun
（无）	npm

安装命令格式：<pm> add -D <package>（pnpm/yarn/bun）或 npm install -D <package>。

Monorepo 项目

如果项目根目录中存在带有 appRoot 字段的 domscribe.config.json，则前端应用位于该子目录中。请相对于 appRoot 安装包并查找 bundler 配置。

如果项目看起来是 monorepo（例如，包含 apps/、packages/ 目录，或 package.json 中有 workspace 配置），但不存在 domscribe.config.json，请询问用户哪个目录包含前端应用。然后在项目根目录创建 domscribe.config.json：

{ "appRoot": "apps/web" }

设置后

如果不存在 .domscribe/ 目录，MCP 服务会以休眠模式启动。用户启动开发服务器后，打包器插件会自动创建 .domscribe/。MCP 服务需要重启，才能检测到新的工作区并切换到包含完整工具套件的活动模式。

编辑组件（代码 → UI）

为什么要查询运行时状态？ 仅凭源代码无法得知组件实际接收了哪些 props、是否渲染了条件分支、应用了哪些 CSS 类，或用户看到的文本是什么。domscribe.query.bySource 能提供浏览器中的实时情况。

适合查询的场景：

• 视觉／样式错误——“按钮颜色不对。”查询会显示实际的 className、内联样式和计算后的属性，帮助你查看最终生效的是哪条 CSS。
• 条件渲染错误——“这个部分没有显示。”查询会告知你 rendered: false，或显示控制该条件的实际 props／状态。
• 追踪 prop——“标题显示了 'undefined'。”查询会显示包含实际值的 componentProps，从而揭示传递链在哪个环节中断。
• 验证编辑是否生效——编辑后，查询同一位置，确认 DOM、props 和文本是否按预期更新（HMR 已应用你的更改）。

不需要查询的场景（省去往返调用）：

• 纯逻辑更改（工具函数、没有 DOM 输出的钩子、API 调用）
• 从头创建新文件或组件（还没有可查询的内容）
• 重构（重命名、提取、移动）
• 类型错误或构建失败（编译器已经指出问题所在）

前提条件： 运行时查询要求用户的开发服务器正在运行，并且目标组件已在打开的浏览器标签页中渲染。调用 domscribe.query.bySource 前，请确认用户已打开相关页面。如果得到 browserConnected: false 或 runtime.rendered: false，请让用户导航到会渲染该组件的页面，然后重试。

工作流：

1. 确认页面已打开——询问用户是否已在浏览器中打开包含目标组件的页面。如果没有，请先让他们导航到该页面。
2. 编辑前（如果任务符合上述场景）：调用 domscribe.query.bySource，并提供文件路径和行号。检查 runtime.componentProps、runtime.componentState 和 runtime.domSnapshot。
3. 编辑组件源代码。
4. 编辑后：再次调用 domscribe.query.bySource，验证更改是否已在实时浏览器中生效。

快捷命令（MCP 提示词）

命令	用途
process_next	处理队列中的下一条批注
check_status	检查系统健康状态和队列计数
explore_component	列出组件中的元素
find_annotations	搜索批注历史

所有工具参考

以下工具名称使用其 MCP 注册名称（例如，domscribe.query.bySource）。你的客户端可能会将这些名称映射为其他形式——请使用你的环境为 domscribe MCP 服务提供的工具名称。

源代码查询（代码 → UI）

工具	用途
domscribe.query.bySource	获取源代码位置（文件 + 行号）的运行时上下文
domscribe.manifest.query	按文件、组件或标签名称查找所有清单条目
domscribe.manifest.stats	清单覆盖率统计（条目／文件／组件数量）

元素解析（UI → 代码）

工具	用途
domscribe.resolve	获取元素 ID 对应的源代码位置
domscribe.resolve.batch	解析多个元素 ID

注释工作流

工具	用途
domscribe.annotation.process	领取下一条排队的注释（原子操作）
domscribe.annotation.respond	保存你的实现说明
domscribe.annotation.updateStatus	标记为 processed 或 failed
domscribe.annotation.list	按状态列出注释
domscribe.annotation.get	获取注释的完整详情
domscribe.annotation.search	按元素、文件或文本搜索

系统

工具	用途
domscribe.status	转发运行状况、清单和队列计数

使用 domscribe.query.bySource

在源文件中工作时，如果想了解某个元素在运行时的样子，可按文件路径和行号进行查询：

输入：

• file（必需）：清单中存储的绝对文件路径。使用 domscribe.manifest.query 查找确切路径。
• line（必需）：行号（从 1 开始）。
• tolerance（可选）：匹配目标行前后 N 行范围内的元素（默认值：0，即精确匹配）。
• column（可选）：限定到特定列（从 0 开始）。
• includeRuntime（可选）：如果只需要清单数据，则跳过浏览器查询（默认值：true）。

输出：

• sourceLocation：已确认的文件、行范围、标签名和组件名。
• runtime：来自浏览器的实时数据（如果已连接）——componentProps、componentState、domSnapshot（标签、属性、innerText）。
• browserConnected：是否有浏览器客户端通过 WebSocket 连接。

如果不知道确切行号，请先使用 domscribe.manifest.query——它会返回文件、组件或标签的所有条目，然后你可以用 domscribe.query.bySource 针对这些条目进行查询。

注释生命周期

queued → processing → processed
                   ↘ failed (with errorDetails)
       any status → archived

• queued：等待 Agent 领取
• processing：Agent 正在处理（已原子领取）
• processed：已成功实现
• failed：无法实现（包含 errorDetails）
• archived：已从活动队列中移除

注释工作流

1. 通过 domscribe.annotation.process 领取一条注释

2. 理解响应：

   • userIntent：用户的需求（例如，“将这个按钮设为红色”）
   • sourceLocation.file：源文件路径
   • sourceLocation.line：行号
   • sourceLocation.componentName：React/Vue 组件名称
   • element.innerText：可见文本（验证元素是否正确）
   • runtimeContext.componentProps：当前属性值

3. 跳转到 sourceLocation.file:sourceLocation.line

4. 根据 userIntent 实现更改

5. 通过 domscribe.query.bySource 验证——使用相同的文件和行号调用，以确认更改已反映在实时浏览器中（HMR 会更新页面）

6. 使用 domscribe.annotation.respond 保存响应，并附上注释 ID 和描述所做更改的消息

7. 使用 domscribe.annotation.updateStatus 完成注释，状态设为 processed（若失败，则设为 failed 并附上 errorDetails）

错误处理

情况	操作
found: false	无匹配项——队列为空或没有清单条目
browserConnected: false	运行时数据不可用；仍会返回清单数据
源文件缺失	标记为 failed 并提供详情
需求不明确	实现前请用户澄清
部分成功	标记为 processed，并在响应中说明限制
无法实现	标记为 failed，并通过 errorDetails 说明原因

核心原则

• 仔细阅读 userIntent——这是用户的原话
• 使用 domscribe.query.bySource 在更改前后验证运行时状态
• 使用 element.innerText 确认你修改的是正确的元素
• 使用 runtimeContext 了解当前组件状态
• 进行最小且有针对性的更改
• 通过 domscribe.annotation.respond 提供清晰的说明
• 使用 domscribe.annotation.search 搜索相关的既往工作