# @alive-game/alive-tagger 中文文档
规范地址：https://npmcn.com/package/%40alive-game/alive-tagger/
版本：0\.2\.1
npm 元数据更新时间：2026-06-16T23:01:55.939Z
中文译文更新时间：2026-11-05T20:22:42.517Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40alive-game/alive-tagger
原文对照：https://npmcn.com/package/%40alive-game/alive-tagger/?lang=original
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：92 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，vite \>=5\.0\.0
- 首次发布：2025-12-09T19:46:02.358Z
- 最新版本发布：2026-06-16T23:01:55.775Z
- 近 30 天下载量：65457（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）
## 中文简介
活工作台的元素选择和源标记
## 安装
```sh
npm install @alive-game/alive-tagger
```
也可以使用：`pnpm add @alive-game/alive-tagger`、`yarn add @alive-game/alive-tagger`、`bun add @alive-game/alive-tagger`
## README
# @ alive- game/ alive- tagger
元素选择和源标记为活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 启用点击到选择带有源文件信息的UI元素,使克洛德能够准确知道用户指的是哪个组件并归档.
## 特征
- **JSX 源代码**:在构建时将源文件信息(文件名,行号,列号)附加到每个 DOM 元素中
- **元素选择**: 点击到选择元素的客户端脚本, 有视觉反馈( 由 workbench 选择按钮激活)
- **后桥**: 将选定的元素上下文发送给克洛德集成的父框架
## 安装
```bash
# In your Vite React project
bun add @alive-game/alive-tagger
```
## 使用量
### 虚拟插件( 需要)
将插件添加到您的 `vite.config.ts`数字 :
```typescript
import { aliveTagger } from "@alive-game/alive-tagger"
export default defineConfig(({ mode }) => ({
plugins: [
react(),
mode === "development" && aliveTagger()
].filter(Boolean),
}))
```
### 客户端脚本( 可选 - 用于 Iframe 选择 UI)
客户端脚本提供点击到选择并带有视觉反馈. 导入时自动初始化 :
```typescript
// In your app entry point (only needed if in iframe)
import "@alive-game/alive-tagger/client"
```
或通过 HTML 注入 :
```html
```
## 如何运作
### 1\. 联合来文X来源标签(Vite插件)
插件拦截 React 的 `jsx-dev-runtime` 并包装 `jsxDEV` 在 DOM 节点上存储源信息的函数
```javascript
// Every DOM element gets this attached via Symbol:
element[Symbol.for("__aliveSource__")] = {
fileName: "client/pages/Index.tsx",
lineNumber: 42,
columnNumber: 8,
displayName: "Button"
}
// Global map for reverse lookups:
window.aliveSourceMap = Map>>
```
### 2\. 元素选择( Client 脚本)
在 Iframe 中运行时 :
1. **启动**: 父框架选项 `TAGGER_ACTIVATE` (工作台选择按钮); 光标变为横线
2. **缓冲**: 以绿色边框和标签突出显示源信息元素 `ComponentName · path/to/file.tsx:line`
3. **点击**: 抓取元素上下文,并通过 Message 发送到父框架
### 3\. 信后通信
选定元素上下文发送给父框架 :
```typescript
window.parent.postMessage({
type: "alive-element-selected",
context: {
fileName: "client/pages/Index.tsx",
lineNumber: 42,
columnNumber: 8,
displayName: "Button",
html: "",
tagName: "button",
className: "btn-primary",
id: "submit-btn",
parentComponents: ["Form", "Page"]
}
}, "*")
```
## API 参考
### 插件选项
```typescript
interface AliveTaggerOptions {
/** Enable source tagging (default: true in dev mode) */
enabled?: boolean
/** Enable debug logging */
debug?: boolean
}
aliveTagger({ enabled: true, debug: false })
```
### 类型
```typescript
import {
SOURCE_KEY, // Symbol.for("__aliveSource__")
ELEMENT_SELECTED_MESSAGE_TYPE, // "alive-element-selected"
type SourceInfo,
type ElementSelectedContext,
type ElementSelectedMessage,
type AliveTaggerOptions,
} from "@alive-game/alive-tagger"
```
### 工具函数
```typescript
import {
getElementSource, // Get source info from element
hasSourceInfo, // Check if element has source info
formatSourceLocation, // Format as "file.tsx:42:8"
isElementSelectedMessage, // Type guard for messages
} from "@alive-game/alive-tagger"
// Example usage
const source = getElementSource(document.querySelector("button"))
if (source) {
console.log(formatSourceLocation(source)) // "client/pages/Index.tsx:42:8"
}
```
### 客户端函数
```typescript
import { initAliveTagger } from "@alive-game/alive-tagger/client"
// Initialize selector (auto-called on import, but can be manual)
const cleanup = initAliveTagger()
// Later: cleanup()
```
## 建筑
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Alive (terminal.alive.best) │
│ ┌──────────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ Chat Interface │ │ Workbench Component │ │
│ │ │ │ - Listens for 'alive-element-selected' │ │
│ │ Shows selected │◀─┤ - Displays source info to user │ │
│ │ element context │ │ - Injects into next Claude message │ │
│ └──────────────────────┘ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
▲
│ postMessage
┌─────────────────────────────────────────────────────────────────────────┐
│ User Site (in preview iframe) │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ alive-tagger plugin (Vite) │ │
│ │ - Intercepts jsx-dev-runtime │ │
│ │ - Attaches Symbol.for('__aliveSource__') to every DOM element │ │
│ │ - Maintains window.aliveSourceMap for lookups │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ alive-tagger/client (optional) │ │
│ │ - Handles click-to-select (button-activated) │ │
│ │ - Visual highlight on hover │ │
│ │ - Posts context to parent frame │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
## 比较:活捉对反应抓取
| 特性 | 活猎手 | 反应抓取 |
| --- | --- | --- |
| **方针** | Vite 插件 + 客户端 | 运行时纤维转动 |
| **数据附件** | 通过 refs 构建时间 | 运行时间纤维检查 |
| **符号密钥** | `__aliveSource__` | `__jsxSource__` |
| **选择 UI** | 内建( 按钮激活点击) | 内建 |
| **通讯** | 邮件 | HTTP 本地主机: 4567 |
| **信封要求** | 无( dev 模式自动) | 无 |
| **设计用途** | 活着的 Iframe | 克劳德特工SDK CLI |
## 与活着的融合
活捉者与"活捉"的工作台预览集成. 当用户激活选定的按钮并单击元素时:
1. **工作室接收邮件**数字 : `Workbench.tsx` 财务报告和审定财务报表 `WorkbenchMobile.tsx` 听着 `alive-element-selected` 信件
2. **通过WorkbenchContext传播背景**: 选择通过 `useWorkbenchContext()`
3. **聊天输入自动填充**: 选定的元素格式为 `@ComponentName in src/path/file.tsx:lineNumber` 插入到聊天输入中
4. **用户可以发送到 Claude**: 参考文献帮助克洛德准确了解要修改的元素/组件
### 关键文件 :
- `apps/web/features/chat/lib/workbench-context.tsx` - 与 `setSelectedElement` 财务报告和审定财务报表 `registerElementSelectHandler`
- `apps/web/features/chat/components/workbench/Workbench.tsx` - 听后Message,电话 `setSelectedElement`
- `apps/web/app/chat/page.tsx` - 登记处理器,将选择插入聊天输入
### 凯迪配置
HMR 要在工作底盘内正常工作, 预览域 **绝对不能** 使用情况 `forward_auth`。认证检查干扰了WebSocket的连接,并导致iframe每几秒钟闪出/重装一次.
预览域 Caddy 配置必须生成而不包含 `forward_auth` 避免这个问题.
## 发展
```bash
# Build
bun run build
# Watch mode
bun run dev
# Type check
bun run type-check
# Run tests
bun run test
```
## 文件
```
packages/alive-tagger/
├── src/
│ ├── index.ts # Main exports (plugin + utilities)
│ ├── plugin.ts # Vite plugin
│ ├── client.ts # Client selection script
│ └── types.ts # TypeScript types
├── dist/ # Built output
├── package.json
├── tsconfig.json
└── tsup.config.ts
```
## 安全考虑
1. **只发展**: 来源标记只活跃于dev模式
2. **无生产影响**: 插件在生产架构中不做任何工作
3. **文件路径**: 已曝光的相对路径(不是完整的系统路径)
4. **节点已过滤**: 图书馆内部没有标记
## 许可证
麻省理工学院
## 常见问题
### @alive-game/alive-tagger 是什么？
活工作台的元素选择和源标记
### 如何安装 @alive-game/alive-tagger？
在项目目录运行 npm install @alive-game/alive-tagger，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、vite（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @alive-game/alive-tagger 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @alive-game/alive-tagger 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @alive-game/alive-tagger 可以商用吗？
@alive-game/alive-tagger 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @alive-game/alive-tagger 的下载量有多少？
根据 npm 官方下载统计，@alive-game/alive-tagger 在 2026/10/06 – 2026/11/04 这 30 天内被下载 65,457 次，日均约 2,182 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @alive-game/alive-tagger 还在维护吗？
最新版本 0\.2\.1 发布于 2026/06/17（4 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/12/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。