# 本地改动说明（对比 origin/develop）

生成时间：2026-06-29  
本地分支：`develop`  
对比基准：`origin/develop`  
远程仓库：`https://git.lzwcai.com/ly1213/qiweimanager-master.git`

> 说明：本文只梳理当前工作区相对 Git 远程基线的本地改动，未提交 Git，也未改动远程仓库。

## 一、改动概览

本次本地改动主要围绕自动客服、素材发送、知识库重建提示和安装包资源打包四块：

1. 新增“只回复外部客户”开关，开启后企业内部成员消息会被自动忽略，不再触发 AI 回复或转人工。
2. 优化素材发送逻辑，支持按素材子文件夹命中问题场景，显式要求“全部”时才发送该匹配文件夹内全部素材。
3. 优化素材话术和发送顺序，统一使用“您”，并在发送图片/视频/动图后补充描述；发送文件时携带文件名，便于企微侧展示。
4. 命中素材时会把知识库中相关文字说明整理后一起发送，更接近真实客服“先说明、再发资料/或发完资料补描述”的场景。
5. 优化知识库重建错误提示：重建成功后清除旧的知识库错误；向量索引失败时保留明确错误和扫描统计。
6. 优化 Windows 安装包打包，把 `tools` 目录、PDF 渲染依赖 DLL、语音转码工具等运行资源纳入安装包。

## 二、功能改动明细

### 1. 只回复外部客户

- 配置结构新增 `identity.replyExternalOnly`，默认值为 `false`，保持原有行为不变。
- 前端“监听策略”区域新增开关：`只回复外部客户，忽略企业内部成员`。
- 后端处理消息时，在身份识别完成后判断：
  - 开关关闭：按原逻辑处理内部/外部/未知身份。
  - 开关开启且识别为内部成员：直接忽略消息，记录原因为 `internal_ignored_external_only`。

涉及文件：

- `config/types.go`
- `frontend/src/components/AutoReply.vue`
- `frontend/src/main.js`
- `helper/auto_reply.go`
- `helper/auto_reply_test.go`

### 2. 素材按文件夹/场景匹配发送

- 去掉了原先“全部资料”这类泛化请求直接短路的粗粒度逻辑，改为更细的判断：
  - 用户只说“全部资料/全部文件”，但没有明确具体场景、文件夹或素材关键词时，不自动群发，仍走澄清/普通回复，避免误发大量资料。
  - 用户带有明确场景或文件夹关键词，例如“0505尾部切刀的资料全部发我”，会发送匹配文件夹内的全部素材。
  - 用户明确要求某类素材，例如“全部视频/全部图片”，会按类型收集对应素材。
- “资料/文件”不再默认只理解成普通文件；只有出现 `文档、表格、手册、说明书、ppt、pdf、doc、docx、xls、xlsx` 等明确文档词时，才限制为普通文件类型。

涉及文件：

- `helper/auto_reply_materials.go`
- `helper/auto_reply_test.go`

### 3. 素材发送话术与顺序

- 默认话术从“发你”改为“发给您”，包括图片、视频、动图、文件和组合素材话术。
- AI 生成素材开场白的 prompt 增加要求：必须使用“您”。
- 命中素材后，会先从知识库命中片段中整理最多 3 条文字说明，作为“相关排查说明”发送给客户。
- 发送顺序调整：
  - 普通文件：先发说明话术，再发文件。
  - 图片/视频/动图：先发素材，再发描述文字，使描述更像跟在图片或视频下面。
- 示例素材索引里的 caption 也同步改成“发给您”。

涉及文件：

- `helper/auto_reply_material_caption.go`
- `helper/auto_reply_materials.go`
- `config/materials/materials.json`
- `helper/auto_reply_test.go`

### 4. 文件消息展示文件名

- 普通文件消息 `type=11031` 发送时，额外传入文件名字段：
  - `fileName`
  - `file_name`
- 文件名从实际路径 `filepath.Base(path)` 提取。
- `requestdata/sendVWorkFileMessage.json` 同步增加文件名占位符，便于底层请求模板使用。

涉及文件：

- `helper/auto_reply_materials.go`
- `requestdata/sendVWorkFileMessage.json`

### 5. 知识库重建提示与错误状态

- 知识库重建接口在失败时也返回已扫描到的统计信息，包括耗时、文件数、分片数和失败文件列表，方便前端展示。
- 关键词模式下不强制重建向量索引。
- 混合/向量模式下，如果 embedding 重建失败，会返回已扫描的知识库索引并保留知识库错误。
- 知识库重建成功后，会清除旧的知识库错误，避免前端一直显示历史失败信息。
- 前端 section alert 支持 `success / warn / error` 三种类型，成功提示会自动清掉对应区域旧错误。

涉及文件：

- `helper/auto_reply_http.go`
- `helper/auto_reply_knowledge.go`
- `helper/auto_reply_status.go`
- `helper/auto_reply_knowledge_test.go`
- `frontend/src/components/AutoReply.vue`

### 6. 安装包运行资源打包

- NSIS 安装脚本新增复制 `$INSTDIR\tools`，安装后会带上运行工具目录。
- 打包脚本复制 `pdftoppm.exe` 时，会同步复制同目录 DLL，避免部署环境缺 DLL 导致 PDF 解析不可用。
- 打包阶段将 `tools\pdf` 整个目录同步进 NSIS runtime。
- 当前本地已生成的新安装包中包含语音转码工具 `silkdecode.exe`。

涉及文件：

- `build/windows/installer/project.nsi`
- `scripts/package-windows.ps1`

最新本地安装包：

`build/bin/qiweimanager-amd64-installer_20260629_145726.exe`

## 三、测试与验证情况

本地新增/调整的自动化测试覆盖了以下场景：

- 开启“只回复外部客户”后，内部成员消息不会触发回复，并记录忽略原因。
- 普通场景素材请求遵守 `maxPerReply` 限制。
- 明确要求某个匹配文件夹“全部资料”时，会发送该文件夹下全部素材。
- 泛化“全部资料都发我”不会直接群发。
- 素材默认话术统一改为“发给您”。
- 命中素材时，会把知识库相关说明与素材一起发送。
- 知识库重建成功后清除旧错误；embedding 失败时保留知识库错误并返回扫描结果。

建议开发同事复核时运行：

```powershell
go test ./helper ./config
npm.cmd --prefix frontend run build
```

如果需要验证安装包资源，请重点检查安装目录下是否存在：

```text
tools/audio/silkdecode.exe
tools/pdf/pdftoppm.exe
```

## 四、注意事项

- 当前工作区还有 Wails 构建生成文件的差异痕迹，主要是 `frontend/wailsjs/runtime/runtime.d.ts` 和 `frontend/wailsjs/runtime/runtime.js`。这些看起来是 Wails CLI 版本差异造成的生成文件变化，不属于本次核心业务逻辑改动，建议提交前由开发同事确认是否需要保留。
- `go.mod`、部分 `frontend/wailsjs/go/*` 文件在 `git status` 中可能因换行符显示为修改，但当前 `git diff --name-only` 未显示实际内容差异。
- 本文档本身是新增的本地说明文件，不属于产品运行逻辑。
- 另有一份未跟踪文档 `yuanzhipeng提交内容梳理.md`，是之前梳理 yuanzhipeng 提交内容生成的说明文档。

## 五、当前实际内容差异文件

根据 `git diff --name-only`，当前有实际内容差异的文件如下：

```text
build/windows/installer/project.nsi
config/materials/materials.json
config/types.go
frontend/src/components/AutoReply.vue
frontend/src/main.js
frontend/wailsjs/runtime/runtime.d.ts
frontend/wailsjs/runtime/runtime.js
helper/auto_reply.go
helper/auto_reply_http.go
helper/auto_reply_knowledge.go
helper/auto_reply_knowledge_test.go
helper/auto_reply_material_caption.go
helper/auto_reply_materials.go
helper/auto_reply_status.go
helper/auto_reply_test.go
requestdata/sendVWorkFileMessage.json
scripts/package-windows.ps1
```