@jhl548/duplicate-doc-vue 0.1.0 → 0.1.1

package/README.md

@@ -1,33 +1,8 @@
-# @jhl548/duplicate-doc-vue 集成说明
+# @jhl548/duplicate-doc-vue
 
-`@jhl548/duplicate-doc-vue` 是面�?Vue3 项目�?Word 文档重复点编辑与高亮插件。插件自身只负责单个标准化文档的渲染、编辑、重复点高亮、滚动定位和编辑快照输出；主从文档关系、重复点列表、上传分析、导出回写等业务编排应由宿主项目完成�?
+面向 Vue 3 的 Word 文档重复点编辑与高亮插件。插件只负责单个标准化文档的渲染、编辑、重复点高亮、滚动定位和编辑快照输出；主从文档编排、上传分析、导出回写、权限审批等业务流程由宿主项目处理。
 
-本文档说明两部分内容�?
-
-- 前端 Vue3 项目如何集成插件，并保证功能和样式正常使用�?
-- 后端需要如何处�?Word 格式转换、文本范围映射和重复点数据，保证插件可以准确高亮�?
-
-## 适用场景
-
-插件适合用于以下业务�?
-
-- 后端已经�?`.doc` / `.docx` 转成可编�?HTML�?
-- 后端或算法服务可以输出文档纯文本、结构块范围和重复点范围�?
-- 前端需要在 Vue3 页面中展示一个或多个富文本编辑器，并定位重复内容�?
-- 用户编辑后，前端需要把最�?HTML / plainText / Tiptap JSON 回传后端用于保存或导出�?
-
-插件不负责：
-
-- Word 文件上传�?
-- 多文档主从关系编排�?
-- 相似度算法�?
-- DOCX 导出�?
-- 后端格式转换�?
-- 业务权限、审批、版本管理等系统逻辑�?
-
-## 安装与引�?
-
-在现�?Vue3 项目中安装插件：
+## 安装
 
 ```bash
 npm install @jhl548/duplicate-doc-vue
@@ -43,7 +18,7 @@ import "@jhl548/duplicate-doc-vue/style.css";
 createApp(App).mount("#app");
 ```
 
-在业务组件中导入组件和类型：
+## 基础用法
 
 ```vue
 <script setup lang="ts">
@@ -58,9 +33,9 @@ import { computed, ref } from "vue";
 const documentModel = ref<NormalizedDocument>({
   documentId: "main-001",
   role: "main",
-  fileName: "主文�?docx",
-  html: '<h1 data-dupdoc-block="b-0">项目计划�?/h1><p data-dupdoc-block="b-1">这是一段需要高亮的重复内容�?/p>',
-  plainText: "项目计划书\n这是一段需要高亮的重复内容�?,
+  fileName: "main.docx",
+  html: '<h1 data-dupdoc-block="b-0">项目计划书</h1><p data-dupdoc-block="b-1">这是一段需要高亮的重复内容。</p>',
+  plainText: "项目计划书\n这是一段需要高亮的重复内容。",
   rangeMap: [
     {
       blockId: "b-0",
@@ -83,13 +58,13 @@ const highlights = computed<DuplicateHighlight[]>(() => [
     documentId: "main-001",
     similarity: 0.92,
     active: true,
-    label: "重复�?1",
+    label: "重复点 1",
     ranges: [{ start: 6, end: 20, blockId: "b-1" }]
   }
 ]);
 
 function handleChange(payload: EditorChangePayload) {
-  console.log("最新编辑内�?, payload);
+  console.log("editor snapshot", payload);
 }
 </script>
 
@@ -108,258 +83,30 @@ function handleChange(payload: EditorChangePayload) {
 
 ### Props
 
-`documentModel: NormalizedDocument`
-
-当前编辑器要渲染的单个标准化文档。该字段是必填项，插件会读取其中�?`html` 作为初始编辑内容，并通过 `documentId` 与高亮数据匹配�?
-
-`highlights?: DuplicateHighlight[]`
-
-当前文档需要渲染的重复点高亮。宿主页面应先根据当前文�?ID、当前重复点、主从文档关系计算出该编辑器真正需要展示的高亮数组�?
-
-`editable?: boolean`
-
-是否允许编辑，默�?`true`。设�?`false` 后，编辑器进入只读展示状态�?
-
-`autofocusHighlight?: boolean`
-
-高亮变化后是否自动滚动到当前高亮位置，默�?`true`�?
+- `documentModel: NormalizedDocument`：当前编辑器要渲染的标准化文档，必填。
+- `highlights?: DuplicateHighlight[]`：当前文档需要展示的重复点高亮，默认为空数组。
+- `editable?: boolean`：是否允许编辑，默认为 `true`。
+- `autofocusHighlight?: boolean`：高亮变化后是否自动滚动到当前高亮位置，默认为 `true`。
 
 ### Events
 
-`change(payload: EditorChangePayload)`
+- `change(payload: EditorChangePayload)`：编辑器内容变化时触发，包含 `documentId`、`html`、`plainText` 和可选 `json`。
+- `ready()`：编辑器初始化完成时触发。
 
-编辑器内容变化时触发。`payload` 包含�?
+### Ref
 
 ```ts
-interface EditorChangePayload {
-  documentId: string;
-  html: string;
-  plainText: string;
-  json?: unknown;
-}
-```
-
-`ready()`
-
-编辑器初始化完成时触发，可用于宿主页面做埋点、加载状态切换或首次定位�?
-
-### Ref 方法
-
-可以通过组件 `ref` 主动读取编辑器快照：
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { DuplicateDocumentEditor, type EditorChangePayload } from "@jhl548/duplicate-doc-vue";
-
-const editorRef = ref<{
+interface DuplicateDocumentEditorRef {
   getSnapshot: () => EditorChangePayload;
   getHTML: () => string;
   getPlainText: () => string;
   focus: () => void;
-} | null>(null);
-
-function submit() {
-  const snapshot = editorRef.value?.getSnapshot();
-  if (!snapshot) {
-    return;
-  }
-
-  console.log(snapshot.html, snapshot.plainText, snapshot.json);
 }
-</script>
-
-<template>
-  <DuplicateDocumentEditor ref="editorRef" :document-model="documentModel" />
-</template>
-```
-
-## 前端页面推荐数据结构
-
-真实业务中建议后端一次返回页面渲染所需的完整结构化数据，避免前端通过多个接口拼装页面。页面可以只保留少量交互状态，例如当前选中的重复点、当前从文档、编辑缓存�?
-
-推荐接口�?
-
-```http
-GET /api/projects/{projectId}/duplicate-doc-view
-```
-
-推荐响应外壳�?
-
-```ts
-interface ApiResponse<T> {
-  code: number;
-  message: string;
-  data: T;
-  meta?: {
-    traceId?: string;
-    timestamp?: string;
-  };
-}
-```
-
-推荐 `data` 结构�?
-
-```ts
-interface DuplicateDocViewData {
-  project: {
-    projectId: string;
-    name: string;
-    mainDocumentId: string;
-  };
-  documents: NormalizedDocument[];
-  duplicates: DuplicatePoint[];
-  activeDefaults: {
-    duplicateId?: string;
-    slaveDocumentId?: string;
-  };
-  stats: {
-    documentTotal: number;
-    duplicateTotal: number;
-    rangeMapTotal: number;
-    plainTextTotal: number;
-  };
-  capabilities: {
-    supportedFileTypes: string[];
-    supportedContentTypes: string[];
-  };
-}
-```
-
-前端收到该结构后，按当前选中�?`duplicateId` 和文�?ID 生成插件入参�?
-
-```ts
-function buildMainHighlights(duplicate: DuplicatePoint, mainDocumentId: string): DuplicateHighlight[] {
-  return [
-    {
-      duplicateId: duplicate.duplicateId,
-      documentId: mainDocumentId,
-      similarity: duplicate.similarity,
-      ranges: duplicate.main.ranges,
-      active: true,
-      label: duplicate.label,
-      reason: duplicate.reason,
-      ignored: duplicate.ignored,
-      severity: duplicate.severity,
-      semanticType: duplicate.semanticType,
-      region: duplicate.region,
-      noiseReason: duplicate.noiseReason
-    }
-  ];
-}
-
-function buildSlaveHighlights(duplicate: DuplicatePoint, slaveDocumentId: string): DuplicateHighlight[] {
-  const slave = duplicate.slaves.find((item) => item.documentId === slaveDocumentId);
-  if (!slave) {
-    return [];
-  }
-
-  return [
-    {
-      duplicateId: duplicate.duplicateId,
-      documentId: slaveDocumentId,
-      similarity: duplicate.similarity,
-      ranges: slave.ranges,
-      active: true,
-      label: duplicate.label,
-      reason: duplicate.reason,
-      ignored: duplicate.ignored,
-      severity: duplicate.severity,
-      semanticType: duplicate.semanticType,
-      region: duplicate.region,
-      noiseReason: duplicate.noiseReason
-    }
-  ];
-}
-```
-
-## 后端数据处理总览
-
-后端的核心职责是把原�?Word 文件转换成插件能稳定消费的数据结构。建议流程如下：
-
-```mermaid
-flowchart LR
-  UploadWord[Upload Word] --> ConvertHtml[Convert to HTML]
-  ConvertHtml --> NormalizeHtml[Normalize HTML Blocks]
-  NormalizeHtml --> PlainText[Build plainText]
-  NormalizeHtml --> RangeMap[Build rangeMap]
-  PlainText --> DuplicateEngine[Duplicate Engine]
-  RangeMap --> DuplicateEngine
-  DuplicateEngine --> DuplicatePoint[Build DuplicatePoint]
-  PlainText --> NormalizedDocument[Build NormalizedDocument]
-  RangeMap --> NormalizedDocument
-  NormalizedDocument --> ViewData[Build Page View Data]
-  DuplicatePoint --> ViewData
-```
-
-后端至少需要输出两类数据：
-
-- `NormalizedDocument[]`：每个可编辑文档的标准化内容�?
-- `DuplicatePoint[]`：重复点及其在主文档、从文档中的纯文本范围�?
-
-## Word �?HTML 的格式转�?
-
-### 推荐转换方式
-
-优先使用 LibreOffice headless 转换�?
-
-```bash
-soffice --headless --convert-to html --outdir ./converted ./input.docx
-```
-
-优点�?
-
-- �?`.doc` �?`.docx` 都比较友好�?
-- 能保留更�?Word 中的标题、段落、表格、列表、图片和基础样式�?
-- 适合服务端批量转换�?
-
-如果服务器没�?LibreOffice，可以对 `.docx` 使用 `python-docx` 做兜底转换，但兜底通常只能保留基础段落文本，格式损失会明显增加�?
-
-不建议后端直接把 Word 原始二进制交给前端处理。插件需要的是标准化 HTML、纯文本和范围映射，而不�?Word 文件本身�?
-
-### 转换后的 HTML 规范�?
-
-转换得到�?HTML 不能直接丢给插件使用，建议后端做一次规范化�?
-
-1. 提取正文区域，忽略无关的 Word 导出样式壳�?
-2. 按块级结构切分内容，例如 `h1`、`h2`、`h3`、`p`、`table`、`ul`、`ol`、`blockquote`、`pre`�?
-3. 为每个结构块生成稳定�?`blockId`�?
-4. �?HTML 节点补充 `data-dupdoc-block` 属性�?
-5. 生成�?HTML 同步�?`plainText`�?
-6. 生成每个块对应的 `rangeMap`�?
-
-示例 HTML�?
-
-```html
-<h1 data-dupdoc-block="b-0">项目计划�?/h1>
-<p data-dupdoc-block="b-1">投标人须提供营业执照、资质证书和类似业绩证明�?/p>
-<table data-dupdoc-block="b-2" data-dupdoc-table="table-001">
-  <tbody>
-    <tr>
-      <th>项目名称</th>
-      <th>合同金额</th>
-    </tr>
-    <tr>
-      <td>智慧园区平台</td>
-      <td>380万元</td>
-    </tr>
-  </tbody>
-</table>
 ```
 
-对应纯文本建议使用块级节点之间的 `\n` 分隔�?
-
-```text
-项目计划�?
-投标人须提供营业执照、资质证书和类似业绩证明�?
-项目名称 合同金额 智慧园区平台 380万元
-```
+## 数据结构约定
 
-这个换行规则非常重要。插件内部会按块级节点补齐换行偏移，如果后端 `plainText` 与前�?Tiptap 文档中的文本提取规则不一致，重复点会出现高亮偏移�?
-
-## NormalizedDocument 数据结构
-
-每个文档必须转换�?`NormalizedDocument`�?
+后端或宿主应用需要把 Word 文档转换为插件可消费的标准模型：
 
 ```ts
 interface NormalizedDocument {
@@ -374,303 +121,90 @@ interface NormalizedDocument {
 }
 ```
 
-字段说明�?
-
-- `documentId`：后端生成的稳定文档 ID，同一次页面数据中必须唯一�?
-- `role`：`main` 表示主文档，`slave` 表示从文档�?
-- `fileName`：原始文件名或业务文件名�?
-- `html`：可�?Tiptap 渲染和编辑的标准�?HTML�?
-- `plainText`：算法使用的纯文本，重复�?`start/end` 必须基于它计算�?
-- `rangeMap`：结构块与纯文本偏移之间的映射�?
-- `assets`：图片、字体等资源信息，可选�?
-- `meta`：转换器、原始文件名、格式损失标记等调试信息，可选�?
-
-`rangeMap` 示例�?
-
-```ts
-interface RangeMapEntry {
-  blockId: string;
-  textStart: number;
-  textEnd: number;
-  selector?: string;
-  sectionPath?: string[];
-  region?: "body" | "header" | "footer" | "table" | "caption" | "unknown";
-  listMarker?: string;
-  tableContext?: TableCellContext;
-  semanticType?: TenderSemanticType;
-}
-```
-
-注意事项�?
+关键要求：
 
-- `textStart` �?`textEnd` 是在 `plainText` 中的字符偏移�?
-- `textEnd` 建议使用左闭右开区间，即包含 `textStart`，不包含 `textEnd`�?
-- 块之间如果在 `plainText` 中插入了 `\n`，必须同步增加后续块的偏移�?
-- `selector` 建议指向 `data-dupdoc-block`，方便调试和后续扩展�?
-- 表格建议保留 `tableContext`，方便前端解释重复点所在行列和表头�?
+- `html` 应是 Tiptap 可解析的标准 HTML。
+- 建议为每个块级节点添加稳定的 `data-dupdoc-block`。
+- `plainText` 必须与算法计算重复点范围时使用的文本一致。
+- `rangeMap` 负责把结构块和纯文本偏移关联起来，便于联调和问题排查。
+- `DuplicateHighlight.ranges[].start/end` 使用基于 `plainText` 的左闭右开区间。
 
-## DuplicatePoint 数据结构
+## Word 转 HTML 建议
 
-后端查重或模�?agent 需要输�?`DuplicatePoint[]`�?
+推荐后端优先使用 LibreOffice headless 转换 Word。没有 LibreOffice 时，可以对 `.docx` 使用 `python-docx` 做基础文本兜底，但复杂样式、表格、图片可能丢失。
 
-```ts
-interface DuplicatePoint {
-  duplicateId: string;
-  groupId?: string;
-  similarity: number;
-  label?: string;
-  summary?: string;
-  reason?: string;
-  ignored?: boolean;
-  severity?: "noise" | "low" | "medium" | "high";
-  semanticType?: TenderSemanticType;
-  region?: DocumentRegion;
-  noiseReason?: string;
-  main: {
-    documentId: string;
-    ranges: TextRange[];
-  };
-  slaves: Array<{
-    documentId: string;
-    ranges: TextRange[];
-  }>;
-}
-```
+推荐转换流程：
 
-`TextRange` 示例�?
+1. 将 Word 转为 HTML。
+2. 清理 Word 导出的无关样式壳。
+3. 按 `h1`、`h2`、`p`、`table`、`ul`、`ol`、`blockquote` 等块级结构生成稳定 `blockId`。
+4. 为 HTML 节点补充 `data-dupdoc-block`。
+5. 同步生成 `plainText` 和 `rangeMap`。
+6. 将查重结果转换为 `DuplicatePoint[]` 或当前编辑器需要的 `DuplicateHighlight[]`。
 
-```ts
-interface TextRange {
-  start: number;
-  end: number;
-  blockId?: string;
-  sectionPath?: string[];
-  region?: DocumentRegion;
-  tableContext?: TableCellContext;
-  confidence?: number;
-  semanticType?: TenderSemanticType;
-}
-```
+## 高亮定位规则
 
-关键要求�?
+高亮是否准确主要取决于三件事：
 
-- `start/end` 必须基于对应文档�?`plainText`�?
-- `documentId` 必须能匹�?`documents` 中的文档�?
-- 一个重复点可以关联一个主文档范围和多个从文档范围�?
-- `similarity` 范围建议�?`0` �?`1`�?
-- `ignored` �?`noiseReason` 可用于标记项目名称、页眉页脚、日期等自然重复内容�?
-- 如果重复点落在表格中，建议带�?`tableContext`�?
+- 后端 `plainText` 的生成规则。
+- 后端 `DuplicatePoint.ranges[].start/end` 的计算规则。
+- 前端 Tiptap 文档中实际文本的顺序。
 
-## 格式转换重点
+建议统一以下规则：
 
-### 段落和标�?
+- 每个块级节点之间使用一个 `\n` 拼接。
+- 块内文本按视觉阅读顺序提取。
+- 表格按行、列顺序提取单元格文本。
+- 空块尽量不参与 `plainText`，除非业务需要保留。
+- `start/end` 使用 JavaScript 字符串下标语义，也就是 UTF-16 code unit 偏移。
 
-后端应尽量保留标题层级：
+如果后端使用 Python 计算偏移，需要注意 emoji、生僻字和组合字符可能造成 Python 字符下标与浏览器 UTF-16 下标不一致。业务文档可能包含这类字符时，建议统一使用 UTF-16 code unit 规则计算偏移，或增加前后端契约测试。
 
-- Word 标题 1 转成 `h1`�?
-- Word 标题 2 转成 `h2`�?
-- Word 标题 3 转成 `h3`�?
-- 普通正文转�?`p`�?
+## 样式和子路径
 
-同时可以根据标题生成 `sectionPath`，例如：
+插件样式通过子路径导出：
 
 ```ts
-sectionPath: ["第一�?商务部分", "资格审查"]
-```
-
-### 列表
-
-有序列表和无序列表建议保留为 `ol` / `ul` / `li`。生成纯文本时需要明确列表项之间是否加入空格或换行，并保持算法与插件一致�?
-
-建议�?
-
-- 块级列表整体作为一个结构块�?
-- `listMarker` 保留原始编号，例�?`1.`、`一、`、`（一）`�?
-- 列表项文本可以合并为该块的文本�?
-
-### 表格
-
-表格是最容易导致偏移不一致的结构，建议后端明确处理：
-
-- HTML 中保�?`table`、`tr`、`th`、`td`�?
-- 给表格生�?`data-dupdoc-table`�?
-- `plainText` 中按单元格顺序提取文本�?
-- 单元格之间建议使用空格分隔�?
-- 表格块在 `rangeMap` 中标�?`region: "table"`�?
-- 重复点落在某个单元格时，尽量补充 `tableContext`�?
-
-`tableContext` 示例�?
-
-```ts
-interface TableCellContext {
-  tableId: string;
-  rowIndex: number;
-  cellIndex: number;
-  headerText?: string;
-  rowHeaderText?: string;
-}
-```
-
-### 图片和附件资�?
-
-如果 Word 中包含图片：
-
-- 简单场景可以转�?base64 图片放在 HTML 中�?
-- 生产场景建议后端上传图片资源，HTML 中引用资�?URL�?
-- `assets` 中记录图�?ID、URL 和类型�?
-
-示例�?
-
-```ts
-assets: [
-  {
-    id: "asset-001",
-    url: "https://cdn.example.com/docs/asset-001.png",
-    type: "image"
-  }
-]
+import "@jhl548/duplicate-doc-vue/style.css";
 ```
 
-### 行内样式
-
-插件基于 Tiptap，建议保留以下常�?HTML�?
+如果宿主项目存在全局 CSS reset 或 scoped 样式覆盖，请检查 `.dupdoc-editor`、`.dupdoc-editor__toolbar`、`.dupdoc-highlight` 等 class 是否被覆盖。
 
-- `strong` / `b`：加粗�?
-- `em` / `i`：斜体�?
-- `u`：下划线�?
-- `s` / `strike`：删除线�?
-- `code`：行内代码�?
-- `mark`：高亮�?
-- `span style="color: ..."`：文字颜色�?
-- `sub` / `sup`：上下标�?
-- `a href="..."`：链接�?
+## 发布前校验
 
-后端转换时不需要保�?Word 的全部样式细节，但应保留影响业务阅读和编辑的基础语义�?
+本包发布前应在仓库根目录执行：
 
-## 偏移计算规则
-
-重复点高亮是否准确，主要取决于三件事�?
-
-1. 后端 `plainText` 的生成规则�?
-2. 后端 `DuplicatePoint.ranges[].start/end` 的计算规则�?
-3. 前端 Tiptap 文档中实际文本的顺序�?
-
-建议统一以下规则�?
-
-- 每个块级节点之间用一�?`\n` 拼接�?
-- 块内文本按视觉阅读顺序提取�?
-- 表格按行、列顺序提取单元格文本�?
-- 空块尽量不参�?`plainText`，除非业务需要保留�?
-- `start/end` 使用 JavaScript 字符串下标语义，�?UTF-16 code unit 偏移�?
-
-如果后端使用 Python 计算偏移，需要注意中文通常没有问题，但 emoji、生僻字、组合字符可能造成 Python 字符下标与浏览器 UTF-16 下标不一致。若业务文档可能包含这类字符，建议统一使用 UTF-16 code unit 规则计算偏移，或在前后端增加契约测试�?
-
-## 编辑回传与导�?
-
-用户编辑后，前端可以通过 `change` 事件或组�?`ref` 获取最新快照：
-
-```ts
-interface EditorChangePayload {
-  documentId: string;
-  html: string;
-  plainText: string;
-  json?: unknown;
-}
+```bash
+npm run verify:publish
 ```
 
-后端收到编辑快照后通常有两种处理方式：
+该命令会执行编码检查、类型检查、构建和 `npm pack --dry-run`。编码检查会拦截替换字符、常见中文错码片段和 Latin-1 错码片段，避免乱码 README 或源码被再次发布到 npm。
 
-- 保存为草稿：记录 `documentId`、`html`、`plainText`、`json`、更新时间和编辑人�?
-- 导出 DOCX：将 `html` 包装成完�?HTML 文档，再通过 LibreOffice 转成 `.docx`�?
-
-导出建议优先使用 LibreOffice�?
+发布到 npm 后再执行：
 
 ```bash
-soffice --headless --convert-to docx --outdir ./converted ./edited.html
+npm run verify:npm
 ```
 
-如果没有 LibreOffice，可以用 `python-docx` 做纯文本兜底导出，但复杂表格、图片、样式会明显丢失�?
-
-## 最小后端伪代码
-
-```py
-def build_view_data(main_file, slave_files):
-    main_document = upload_to_normalized_document(main_file, role="main")
-    slave_documents = [
-        upload_to_normalized_document(file, role="slave")
-        for file in slave_files
-    ]
-
-    documents = [main_document, *slave_documents]
-    duplicates = duplicate_engine(documents)
-
-    return {
-        "code": 0,
-        "message": "ok",
-        "data": {
-            "project": {
-                "projectId": "project-001",
-                "name": "查重项目",
-                "mainDocumentId": main_document["documentId"],
-            },
-            "documents": documents,
-            "duplicates": duplicates,
-            "activeDefaults": {
-                "duplicateId": duplicates[0]["duplicateId"] if duplicates else None,
-                "slaveDocumentId": duplicates[0]["slaves"][0]["documentId"] if duplicates and duplicates[0]["slaves"] else None,
-            },
-            "stats": {
-                "documentTotal": len(documents),
-                "duplicateTotal": len(duplicates),
-                "rangeMapTotal": sum(len(doc["rangeMap"]) for doc in documents),
-                "plainTextTotal": sum(len(doc["plainText"]) for doc in documents),
-            },
-            "capabilities": {
-                "supportedFileTypes": ["DOC", "DOCX"],
-                "supportedContentTypes": ["标题", "段落", "表格", "列表", "图片", "基础行内样式"],
-            },
-        },
-        "meta": {
-            "traceId": "trace-id",
-            "timestamp": "2026-05-14T16:00:00+08:00",
-        },
-    }
-```
+该命令会从 npm registry 拉取最新包，并让 demo 以 npm 模式完成类型检查和构建，避免 Vite alias 或 TypeScript paths 回退到本地源码。
 
-## 前后端联调检查清�?
+## 联调检查清单
 
-- 前端已导�?`@jhl548/duplicate-doc-vue/style.css`�?
-- `documentModel.documentId` �?`highlights[].documentId` 一致�?
-- `DuplicatePoint.main.documentId` 能匹配主文档�?
-- `DuplicatePoint.slaves[].documentId` 能匹配从文档�?
-- `TextRange.start/end` 不越界�?
-- `rangeMap.textStart/textEnd` �?`plainText` 对齐�?
-- 后端块级换行规则与插件映射规则一致�?
-- 表格、列表、标题、图片在 HTML 中仍�?Tiptap 可解析结构�?
-- 编辑�?`change` 事件能返回最�?HTML �?plainText�?
-- 导出 DOCX 时后端能接受前端回传�?HTML�?
+- 应用入口已导入 `@jhl548/duplicate-doc-vue/style.css`。
+- `documentModel.documentId` 与 `highlights[].documentId` 一致。
+- `TextRange.start/end` 不越界。
+- `rangeMap.textStart/textEnd` 与 `plainText` 对齐。
+- 后端块级换行规则与插件映射规则一致。
+- 表格、列表、标题、图片在 HTML 中仍是 Tiptap 可解析结构。
+- 编辑器 `change` 事件能返回最新 `html` 和 `plainText`。
+- 导出 DOCX 时后端能接受前端回传的 HTML。
 
 ## 常见问题
 
-### 高亮位置偏了怎么�?
-
-优先检查后�?`plainText` 是否和插件渲染后的文本顺序一致。常见原因是表格单元格分隔符、列表项换行、空段落、HTML 实体、Word 导出冗余节点导致偏移不一致�?
-
-### 样式没有生效怎么�?
-
-确认应用入口已经导入�?
-
-```ts
-import "@jhl548/duplicate-doc-vue/style.css";
-```
-
-如果宿主项目�?CSS reset �?scoped 样式覆盖插件样式，需要检�?`.dupdoc-editor`、`.dupdoc-editor__toolbar`、`.dupdoc-highlight` �?class 是否被覆盖�?
-
-### 能否只传 HTML，不�?plainText �?rangeMap
-
-不建议。插件可以只�?HTML 渲染编辑器，但重复点高亮依赖 `plainText` 偏移和后端算法输出。缺�?`plainText` �?`rangeMap` 会让联调和问题排查变得困难�?
+### 高亮位置偏移怎么办？
 
-### 重复点范围能否直接用 DOM selector
+优先检查后端 `plainText` 是否和插件渲染后的文本顺序一致。常见原因包括表格单元格分隔符、列表项换行、空段落、HTML 实体、Word 导出冗余节点导致偏移不一致。
 
-当前插件的高亮核心是纯文本偏移到 ProseMirror 位置的映射。`selector` 可以作为调试和扩展字段，但不建议�?DOM selector 作为唯一定位依据，因为用户编辑后 DOM 结构可能变化�?
+### 能否只传 HTML？
 
+不建议。插件可以只用 HTML 渲染编辑器，但重复点高亮依赖 `plainText` 偏移和后端算法输出。缺少 `plainText` 和 `rangeMap` 会让联调和问题排查变得困难。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhl548/duplicate-doc-vue",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,11 +22,12 @@
     "access": "public"
   },
   "scripts": {
+    "prepack": "node ../../scripts/check-encoding.mjs && npm run typecheck && npm run build",
     "build": "vite build",
     "typecheck": "vue-tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@jhl548/duplicate-doc-core": "0.1.0",
+    "@jhl548/duplicate-doc-core": "0.1.1",
     "@tiptap/extension-color": "^3.23.4",
     "@tiptap/extension-highlight": "^3.23.4",
     "@tiptap/extension-image": "^3.23.4",