Skip to content

Commit 976f7ba

Browse files
FinleyGeFinleyGe
committed
feat(docDiff): new tool doc diff
1 parent b93acad commit 976f7ba

File tree

10 files changed

+1412
-1
lines changed

10 files changed

+1412
-1
lines changed

‎.claude/CLAUDE.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,15 +180,22 @@ bun run install:plugins
180180
bun run build:pkg
181181
```
182182

183-
### 3. 生产部署
183+
### 3. 测试和部署
184184
```bash
185+
# 运行测试
186+
bun run test
187+
185188
# 构建生产版本
186189
bun run build:runtime
187190

188191
# 启动生产服务
189192
bun run start
190193
```
191194

195+
**⚠️ 重要**:
196+
- 测试命令使用 `bun run test` 而不是 `bun test`
197+
- 测试环境使用 Vitest 运行器，支持 mock 和覆盖率
198+
192199
## 快速适配指南
193200

194201
### 1. 工具适配步骤

‎modules/tool/packages/docDiff/DESIGN.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# DocDiff 系统工具
2+
3+
输入：两个 markdown 格式的纯文本内容
4+
输出：一个 html 文件
5+
6+
提供一个 html 模版文件, 对两个文本内容进行对比，逐段对比，分析其中的差异，高亮显示差异。
7+
8+
描述工具集名称，以及子工具，子工具需要包含 ID,名字，哪些输入输出，例如：
9+
10+
---
11+
12+
下面由 AI 生成完整的设计文档

‎modules/tool/packages/docDiff/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# DocDiff 文档对比工具
2+
3+
一个用于对比两个 Markdown 文档差异的 FastGPT 工具，生成可视化的 HTML 对比报告。
4+
5+
## 功能特性
6+
7+
- 📝 **段落级对比**: 逐段分析文档差异
8+
- 🎨 **可视化报告**: 生成美观的 HTML 对比报告
9+
- 📊 **统计信息**: 显示新增、删除、修改、未修改的段落数量
10+
- 🔒 **安全防护**: 自动转义 HTML 字符，防止 XSS 攻击
11+
- 📱 **响应式设计**: 支持移动端浏览
12+
- ⚡ **高性能**: 基于相似度算法的智能对比
13+
14+
## 使用方法
15+
16+
### 输入参数
17+
18+
- **originalText** (必需): 原始的 Markdown 文档内容
19+
- **modifiedText** (必需): 修改后的 Markdown 文档内容
20+
- **title** (可选): 对比报告的标题，默认为"文档对比报告"
21+
22+
### 输出
23+
24+
返回一个完整的 HTML 文件，包含：
25+
- 文档标题和生成时间
26+
- 变更统计信息
27+
- 逐段对比详情
28+
- 美观的样式设计
29+
30+
## 对比算法
31+
32+
工具使用智能的相似度算法来识别文档变化：
33+
34+
1. **段落分割**: 将文档按空行分割为段落
35+
2. **相似度计算**: 基于字符级别的相似度匹配
36+
3. **变更分类**:
37+
- 未修改 (>80% 相似度)
38+
- 修改 (30%-80% 相似度)
39+
- 新增 (仅在修改后文档中存在)
40+
- 删除 (仅在原始文档中存在)
41+
4. **最佳匹配**: 寻找最相似的段落配对
42+
43+
## 使用示例
44+
45+
```typescript
46+
const result = await tool({
47+
originalText: `# 项目文档
48+
49+
## 功能介绍
50+
这是一个测试功能。
51+
52+
## 安装步骤
53+
1. 下载代码
54+
2. 运行安装命令`,
55+
56+
modifiedText: `# 项目文档
57+
58+
## 功能介绍
59+
这是一个更新的测试功能。
60+
61+
## 安装步骤
62+
1. 下载代码
63+
2. 运行安装命令
64+
3. 配置环境变量`,
65+
66+
title: "项目文档变更记录"
67+
});
68+
69+
console.log(result.html); // 输出 HTML 对比报告
70+
```
71+
72+
## HTML 报告特性
73+
74+
- 🎨 **现代化设计**: 渐变背景、卡片布局、阴影效果
75+
- 📈 **统计仪表板**: 直观显示各类变更数量
76+
- 🏷️ **状态标签**: 不同颜色标识变更类型
77+
- 📝 **代码高亮**: 使用等宽字体显示内容
78+
- 🔄 **对比视图**: 并排显示原始和修改内容
79+
80+
## 技术实现
81+
82+
- **TypeScript**: 类型安全的实现
83+
- **Zod 验证**: 输入参数验证
84+
- **纯函数设计**: 无副作用的处理逻辑
85+
- **HTML 安全**: 自动转义特殊字符
86+
87+
## 适用场景
88+
89+
- 📄 **文档版本对比**: 比较文档的不同版本
90+
- 📝 **内容审核**: 查看内容修改记录
91+
- 🔄 **变更追踪**: 跟踪文档变化
92+
- 📊 **差异分析**: 分析文档变更模式
93+
94+
## 开发和测试
95+
96+
```bash
97+
# 安装依赖
98+
bun install
99+
100+
# 运行测试
101+
bun test
102+
103+
# 类型检查
104+
bun run tsc --noEmit
105+
106+
# 构建
107+
bun run build
108+
```
109+
110+
## 测试覆盖
111+
112+
- ✅ 输入验证测试
113+
- ✅ 文档对比逻辑测试
114+
- ✅ HTML 输出质量测试
115+
- ✅ 边界情况测试
116+
- ✅ 安全性测试
117+
118+
## 版本信息
119+
120+
- **当前版本**: 1.0.0
121+
- **FastGPT 兼容性**: 完全兼容
122+
- **依赖**: 仅依赖 Zod，无外部 API 调用

‎modules/tool/packages/docDiff/bun.lock‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"lockfileVersion": 1,
3+
"workspaces": {
4+
"": {
5+
"name": "@fastgpt-plugins/tool-doc-diff",
6+
"dependencies": {
7+
"zod": "^3.25.76",
8+
},
9+
"devDependencies": {
10+
"@types/bun": "latest",
11+
},
12+
"peerDependencies": {
13+
"typescript": "^5.0.0",
14+
},
15+
},
16+
},
17+
"packages": {
18+
"@types/bun": ["@types/bun@1.3.1", "", { "dependencies": { "bun-types": "1.3.1" } }, "sha512-4jNMk2/K9YJtfqwoAa28c8wK+T7nvJFOjxI4h/7sORWcypRNxBpr+TPNaCfVWq70tLCJsqoFwcf0oI0JU/fvMQ=="],
19+
20+
"@types/node": ["@types/node@24.10.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-qzQZRBqkFsYyaSWXuEHc2WR9c0a0CXwiE5FWUvn7ZM+vdy1uZLfCunD38UzhuB7YN/J11ndbDBcTmOdxJo9Q7A=="],
21+
22+
"@types/react": ["@types/react@19.2.2", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA=="],
23+
24+
"bun-types": ["bun-types@1.3.1", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],
25+
26+
"csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
27+
28+
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
29+
30+
"undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
31+
32+
"zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
33+
}
34+
}

‎modules/tool/packages/docDiff/config.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import { defineTool } from '@tool/type';
2+
import { FlowNodeInputTypeEnum, WorkflowIOValueTypeEnum } from '@tool/type/fastgpt';
3+
import { ToolTagEnum } from '@tool/type/tags';
4+
5+
export default defineTool({
6+
name: {
7+
'zh-CN': '文档对比工具',
8+
en: 'DocDiff'
9+
},
10+
tags: [ToolTagEnum.enum.tools],
11+
description: {
12+
'zh-CN': '对比两个 Markdown 文档的差异，生成可视化的 HTML 对比报告',
13+
en: 'Compare differences between two Markdown documents and generate visual HTML comparison report'
14+
},
15+
toolDescription:
16+
'A tool that compares two markdown documents and generates a visual HTML diff report showing differences section by section',
17+
18+
versionList: [
19+
{
20+
value: '1.0.0',
21+
description: 'Initial version',
22+
inputs: [
23+
{
24+
key: 'originalText',
25+
label: '原始文档',
26+
description: '原始的 Markdown 格式文档内容',
27+
required: true,
28+
valueType: WorkflowIOValueTypeEnum.string,
29+
renderTypeList: [FlowNodeInputTypeEnum.textarea, FlowNodeInputTypeEnum.reference],
30+
toolDescription: 'The original markdown document content to compare'
31+
},
32+
{
33+
key: 'modifiedText',
34+
label: '修改后文档',
35+
description: '修改后的 Markdown 格式文档内容',
36+
required: true,
37+
valueType: WorkflowIOValueTypeEnum.string,
38+
renderTypeList: [FlowNodeInputTypeEnum.textarea, FlowNodeInputTypeEnum.reference],
39+
toolDescription: 'The modified markdown document content to compare'
40+
},
41+
{
42+
key: 'title',
43+
label: '对比报告标题',
44+
description: '生成的 HTML 对比报告的标题',
45+
required: false,
46+
valueType: WorkflowIOValueTypeEnum.string,
47+
renderTypeList: [FlowNodeInputTypeEnum.input],
48+
defaultValue: '文档对比报告'
49+
}
50+
],
51+
outputs: [
52+
{
53+
valueType: WorkflowIOValueTypeEnum.string,
54+
key: 'htmlUrl',
55+
label: 'HTML 对比报告连接',
56+
description: '生成的 HTML 对比报告的访问连接'
57+
}
58+
]
59+
}
60+
]
61+
});

‎modules/tool/packages/docDiff/index.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import config from './config';
2+
import { InputType, OutputType, tool as toolCb } from './src';
3+
import { exportTool } from '@tool/utils/tool';
4+
5+
export default exportTool({
6+
toolCb,
7+
InputType,
8+
OutputType,
9+
config
10+
});

‎modules/tool/packages/docDiff/logo.svg‎

Lines changed: 20 additions & 0 deletions
Loading

‎modules/tool/packages/docDiff/package.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "@fastgpt-plugins/tool-doc-diff",
3+
"module": "index.ts",
4+
"type": "module",
5+
"scripts": {
6+
"build": "bun ../../../../scripts/build.ts"
7+
},
8+
"devDependencies": {
9+
"@types/bun": "latest"
10+
},
11+
"peerDependencies": {
12+
"typescript": "^5.0.0"
13+
},
14+
"dependencies": {
15+
"zod": "^3.25.76"
16+
}
17+
}

0 commit comments

Comments
 (0)