# 定时任务与工作空间清理
**本文引用的文件**
- [DmService.java](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java)
- [CaseDataSourceReaper.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java)
- [ChatAttachmentService.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java)
- [PathConst.java](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java)
- [WorkspaceManagerFactory.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/WorkspaceManagerFactory.java)
- [WorkspaceScaffolder.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/scaffold/WorkspaceScaffolder.java)
- [os.js](file://ai-electron/electron/service/os/os.js)
- [application.yaml](file://ai-server/src/main/resources/application.yaml)
- [chat_attachment.sql](file://sql/chat_attachment.sql)
- [knowledge_base.sql](file://sql/knowledge_base.sql)
## 目录
1. [简介](#简介)
2. [项目结构与工作空间总览](#项目结构与工作空间总览)
3. [调度策略与执行频率](#调度策略与执行频率)
4. [工作空间目录结构、生命周期与归属关系](#工作空间目录结构生命周期与归属关系)
5. [详细清理逻辑分析](#详细清理逻辑分析)
6. [依赖与失败处理](#依赖与失败处理)
7. [运维操作建议](#运维操作建议)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
## 简介
本文聚焦系统启动后用于清理以下资源的定时任务:Agent 工作空间相关数据、临时批次目录、对话附件孤儿、以及索引残留。文档说明这些任务的调度配置、执行频率、工作空间的目录结构和生命周期,并给出重试/告警策略、运维调整建议与常见故障排查方法。
需要特别说明的是:当前代码库中并未实现“下载日志表定期自动删除”的独立定时任务;知识库下载记录 `knowledge_doc_download_log` 仅作为审计字段存在。因此“下载日志清理”在现有实现中属于未覆盖项,本文会明确标注其现状与排查建议。
## 项目结构与工作空间总览
系统涉及三类与“工作空间/临时文件/索引”相关的存储位置:
| 类型 | 根路径或隔离维度 | 主要用途 | 是否由定时任务清理 |
|---|---:|---|---|
| Agent 工作空间 | `{cwd}/.agentscope/users/{userId}/workspaces/{workspaceId}/agents/{agentRowId}` | Agent 会话、技能、记忆、子智能体等运行时数据 | 无直接定时清理;受 Agent 生命周期和会话管理约束 |
| 清洗临时批次 | `{user.dir}/QingJian/tmp/{batchId}` | Excel/CSV 流式清洗过程中的中间批次目录 | 是,按修改时间超过 24 小时兜底清扫 |
| 对话附件 | `{user.dir}/QingJian/chat-attachments/{userId}/{caseId}/{sessionId}` + 向量表 | 输入框上传的文件、sidecar、RAG 向量块 | 是,按“上传后超期仍未关联消息”判定为孤儿清理 |
| DuckDB 案件数据源 | 内存注册表 + 每案 DuckDB 实例 | 案件级数据库连接与缓存 | 是,按 token 失效+无在途任务回收 |
| 知识库下载日志 | PG 表 `knowledge_doc_download_log` | 记录谁何时下载了哪个文档 | 无自动清理任务 |
```mermaid
graph TB
A["应用根目录
System.getProperty('user.dir')"] --> B["QingJian
运行目录"]
B --> C["tmp
清洗临时批次"]
B --> D["chat-attachments
对话附件"]
A --> E[".agentscope
Agent 运行时数据"]
E --> F["users/{userId}
用户级隔离"]
F --> G["workspaces/{workspaceId}
工作空间隔离"]
G --> H["agents/{agentRowId}
Agent 隔离"]
```
**图表来源**
- [PathConst.java:12-109](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java#L12-L109)
- [WorkspaceManagerFactory.java:12-79](file://ai-server/src/main/java/com/zsjz/ai/module/agent/WorkspaceManagerFactory.java#L12-L79)
**章节来源**
- [PathConst.java:12-109](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java#L12-L109)
- [WorkspaceManagerFactory.java:12-79](file://ai-server/src/main/java/com/zsjz/ai/module/agent/WorkspaceManagerFactory.java#L12-L79)
- [WorkspaceScaffolder.java:26-134](file://ai-server/src/main/java/com/zsjz/ai/module/agent/scaffold/WorkspaceScaffolder.java#L26-L134)
- [os.js:134-200](file://ai-electron/electron/service/os/os.js#L134-L200)
## 调度策略与执行频率
系统使用 Spring `@Scheduled` 实现多个清理类任务。调度线程池默认大小为 4,以避免单个批量任务拖慢 SSE 心跳等其他调度任务。
| 任务 | 触发方式 | 默认间隔 | 初始延迟 | 作用范围 | 关键配置项 |
|---|---|---|---|---|---|
| 临时批次目录清扫 | `fixedDelayString` | 21600000 ms(约 6 小时) | 600000 ms(10 分钟) | `QingJian/tmp` 下直接子目录 | `zsjz.tmp.sweep-interval-ms`、`zsjz.tmp.sweep-initial-delay-ms` |
| DuckDB 案件数据源回收 | `fixedDelayString` | 300000 ms(5 分钟) | 60000 ms(1 分钟) | 已打开但未归属有效会话的案件 | `zsjz.duckdb.reaper-interval-ms`、`zsjz.duckdb.reaper-initial-delay-ms` |
| 对话附件孤儿清理 | `fixedDelayString` | 3600000 ms(1 小时) | 600000 ms(10 分钟) | `chat_attachment` 中未关联消息且超期的附件 | `zsjz.chat-attachment.purge-interval-ms`、`zsjz.chat-attachment.purge-initial-delay-ms` |
| 知识库下载日志清理 | 未发现定时任务 | 不适用 | 不适用 | `knowledge_doc_download_log` | 无 |
调度线程池配置位于 `spring.task.scheduling.pool.size`,默认值为 4。该值影响所有 `@Scheduled` 任务并发能力,若某个清理任务耗时过长,应优先检查该任务本身,而不是盲目扩大线程池。
**章节来源**
- [application.yaml:25-32](file://ai-server/src/main/resources/application.yaml#L25-L32)
- [DmService.java:1291-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1291-L1307)
- [CaseDataSourceReaper.java:44-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L44-L125)
- [ChatAttachmentService.java:404-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L404-L432)
## 工作空间目录结构、生命周期与归属关系
### Agent 工作空间
Agent 工作空间采用三维隔离:**用户 × 工作空间 × Agent**。解析结果为:
```
{cwd}/.agentscope/users/{userId}/workspaces/{workspaceId}/agents/{agentRowId}
```
其中:
| 层级 | 含义 | 是否可被通用清理脚本删除 |
|---|---|---|
| `.agentscope` | Agent 运行时根目录 | 不应直接删除,否则丢失用户技能、记忆与会话 |
| `users/{userId}` | 用户级数据,包括技能仓库 | 仅可删除对应用户的目录,不能跨用户清理 |
| `workspaces/{workspaceId}` | 业务工作空间,通常等于 caseId | 删除前应确认该案件不再被任何会话或 Agent 引用 |
| `agents/{agentRowId}` | 具体 Agent 实例数据,包含会话、事件转录、标准槽位 | 不应由外部脚本直接删除 |
Agent 首次创建工作空间时,`WorkspaceScaffolder` 会写入 `AGENTS.md`、`tools.json`、`skills/`、`subagents/`、`memory/` 等模板内容,并保证“不存在才写入”,避免覆盖已有数据。
```mermaid
flowchart TD
Start["创建 Agent 工作空间"] --> Check["检查工作空间目录是否存在"]
Check --> Exists{"已存在?"}
Exists -->|是| Noop["跳过覆盖,保持已有数据"]
Exists -->|否| Create["创建 AGENTS.md、tools.json、skills、subagents、memory 等"]
Create --> Done["完成初始化"]
Noop --> Done
```
**图表来源**
- [WorkspaceScaffolder.java:26-134](file://ai-server/src/main/java/com/zsjz/ai/module/agent/scaffold/WorkspaceScaffolder.java#L26-L134)
**章节来源**
- [WorkspaceManagerFactory.java:12-79](file://ai-server/src/main/java/com/zsjz/ai/module/agent/WorkspaceManagerFactory.java#L12-L79)
- [WorkspaceScaffolder.java:26-134](file://ai-server/src/main/java/com/zsjz/ai/module/agent/scaffold/WorkspaceScaffolder.java#L26-L134)
### 清洗临时目录
清洗临时目录位于 `QingJian/tmp`,每个数据清洗批次以 `batchId` 命名一个子目录。正常流程会在清洗回调中删除本批次目录;但中途失败、取消或异常退出的批次可能留下残留。
该目录与 Agent 工作空间不同:它不是按用户/会话隔离的工作空间,而是清洗流水线共享的临时目录,因此清理策略基于“目录最后修改时间超过 24 小时”。
**章节来源**
- [PathConst.java:85-85](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java#L85-L85)
- [DmService.java:1270-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1270-L1307)
### 对话附件目录
对话附件落盘路径为:
```
{user.dir}/QingJian/chat-attachments/{userId}/{caseId}/{sessionId}/{雪花}_{safeName}
```
附件元数据保存在 `chat_attachment` 表中,支持三路处理:小内容内联、大表格 Python 直读、大文档 RAG 向量化。向量索引按案件分表,并在检索时强制按会话过滤。
**章节来源**
- [ChatAttachmentService.java:107-107](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L107-L107)
- [chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39)
### Electron 端 workspace 扫描
Electron 主进程提供上传清鉴数据源的能力,它会:
1. 校验选中目录最后一级必须为 `QingJian`。
2. 在 `QingJian/workspace` 下扫描下一层文件夹。
3. 读取每个子文件夹中的文件,不递归更深层。
4. 将结果通过 multipart 流式上传到后端。
这说明桌面客户端对 workspace 的使用方式是“按目录枚举上传”,而不是由 Electron 负责清理。
**章节来源**
- [os.js:134-200](file://ai-electron/electron/service/os/os.js#L134-L200)
## 详细清理逻辑分析
### 临时批次目录清扫
该任务由 `DmService.sweepStaleTmpBatches` 实现,核心逻辑如下:
```mermaid
flowchart TD
Start["定时任务开始"] --> ReadRoot["读取 QingJian/tmp 根目录"]
ReadRoot --> HasDirs{"是否有子目录?"}
HasDirs -->|否| End["结束"]
HasDirs -->|是| Iterate["遍历 tmp 下的直接子目录"]
Iterate --> CheckTime{"最后修改时间是否早于 24 小时前?"}
CheckTime -->|否| Next["跳过该目录"]
CheckTime -->|是| Delete["删除该批次目录"]
Next --> More{"还有目录?"}
Delete --> More
More -->|是| Iterate
More -->|否| End
```
**图表来源**
- [DmService.java:1270-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1270-L1307)
需要注意:
- 只删除 `tmp` 根目录下的直接子目录,不会删除 `tmp` 根目录本身。
- 判断依据是目录的“最后修改时间”,而不是数据库状态。
- 如果清洗回调没有正确删除,旧批次最多保留 24 小时。
- 若目录中存在正在使用的文件,底层删除会失败,但该异常未被显式捕获,可能中断本轮后续目录处理。
**章节来源**
- [DmService.java:1270-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1270-L1307)
### DuckDB 案件数据源回收
`CaseDataSourceReaper` 是兜底回收器,解决 sa-token Redis 会话自然过期不触发监听器的问题。它的策略非常保守:
1. 每隔 5 分钟扫描一次已打开案件。
2. 检查归属 token 是否仍然有效。
3. 若 token 失效,再检查该案件是否仍有业务模块声明的在途任务。
4. 只有两者都满足“会话失效 + 无在途任务”才关闭数据源并清理缓存。
```mermaid
sequenceDiagram
participant Scheduler as "调度器"
participant Reaper as "CaseDataSourceReaper"
participant Registry as "CaseDataSourceRegistry"
participant Token as "Sa-Token"
participant Probes as "在途任务探针"
Scheduler->>Reaper: 定时触发 reap()
Reaper->>Registry: 获取已打开案件列表
loop 每个案件
Reaper->>Registry: 查询归属 userId 与 ownerToken
alt 有 ownerToken
Reaper->>Token: 校验 token 是否有效
Token-->>Reaper: 有效/无效
else 老数据无 ownerToken
Reaper->>Token: 按用户查剩余 token
end
Reaper->>Probes: 检查案件是否在途
alt 会话仍有效 或 有在途任务
Reaper->>Reaper: 跳过回收
else 会话失效 且 无在途任务
Reaper->>Registry: 关闭案件数据源
Reaper->>Registry: 清理案件缓存
end
end
```
**图表来源**
- [CaseDataSourceReaper.java:44-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L44-L125)
该任务的关键设计原则是“宁可多留,不可误杀”。当 token 状态检查或探针异常时,它选择跳过回收,而不是释放可能仍被使用的案件数据源。
**章节来源**
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
### 对话附件孤儿清理
`ChatAttachmentService.purgeOrphans` 清理上传后超期仍未关联消息的附件。默认保留时间为 7 天(`orphanHours=168`),但实际截止时间取“当前时间减去 max(24, orphanHours)”,即至少保留 24 小时。
清理流程:
1. 查询 `link_message_id` 为空且创建时间早于截止时间的附件。
2. 对每个候选附件执行条件删除:再次确认“仍未关联消息且超期”。
3. 只有 DB 删除成功,才删除向量索引和磁盘文件。
4. 单条附件清理异常会被捕获并记录日志,不会中断其他附件清理。
```mermaid
flowchart TD
Start["孤儿附件清理任务"] --> Query["查询未关联消息且超期的附件"]
Query --> HasOrphans{"是否有孤儿?"}
HasOrphans -->|否| End["结束"]
HasOrphans -->|是| Loop["逐个孤儿附件"]
Loop --> AtomicDelete["条件删除:仍未关联消息且超期"]
AtomicDelete --> Deleted{"DB 删除成功?"}
Deleted -->|否| Next["跳过,可能刚被关联"]
Deleted -->|是| CleanIndex["删除向量索引"]
CleanIndex --> CleanFile["删除原件 sidecar 文件"]
CleanFile --> Next
Next --> More{"还有孤儿?"}
More -->|是| Loop
More -->|否| Log["记录清理数量"]
Log --> End
```
**图表来源**
- [ChatAttachmentService.java:397-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L397-L432)
**章节来源**
- [ChatAttachmentService.java:397-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L397-L432)
- [chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39)
### 索引残留清理
系统中与“索引”相关的清理主要有两类:
| 索引类型 | 清理时机 | 说明 |
|---|---|---|
| 对话附件 RAG 向量 | 附件孤儿清理、删除案件附件时 | 调用 `AttachmentDocIndexer.deleteAttachmentVectors` 删除对应向量行 |
| AI 清洗模板向量索引 | 模板变更增量更新、启动时重建、手工重建接口 | 由 aiclean 模块管理,不属于通用工作空间清理 |
| 知识库文档向量 | 删除知识库、撤销附件索引时 | 与知识库生命周期绑定 |
目前未见“周期性扫描磁盘索引目录并清理孤立索引文件”的通用任务。若出现索引残留,通常应先确认对应的数据库记录是否仍存在;若记录已删而索引未删,则属于幂等删除缺失或外部清理未覆盖。
**章节来源**
- [ChatAttachmentService.java:404-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L404-L432)
- [application.yaml:114-143](file://ai-server/src/main/resources/application.yaml#L114-L143)
## 依赖与失败处理
| 清理任务 | 失败处理策略 | 是否重试 | 风险点 |
|---|---|---|---|
| 临时批次目录清扫 | 未对单目录删除做 try/catch;删除失败可能中断后续目录 | 无 | 某个目录占用导致整轮清扫停止 |
| DuckDB 数据源回收 | token 检查失败、探针异常均按“仍在用”保守跳过 | 下次调度周期重试 | 回收变慢,但安全性高 |
| 对话附件孤儿清理 | 单条附件清理异常被捕获,继续处理下一条 | 无立即重试,靠下次调度周期 | 文件/向量删除失败会留下磁盘残留 |
| 知识库下载日志 | 无自动清理逻辑 | 不适用 | 长期积累可能增长日志表 |
### 重试机制现状
- **临时批次目录清扫**:没有逐目录重试。如果某个目录因权限或文件占用删除失败,可能抛出异常并终止本轮后续目录处理。
- **DuckDB 数据源回收**:依赖调度周期自然重试;每次扫描都会重新评估 token 与会话状态。
- **对话附件孤儿清理**:单条异常被吞掉,只记录日志;下一次调度周期会再次尝试。
- **知识库下载日志**:当前没有清理任务,因此不存在重试语义。
### 告警与监控
当前清理任务主要通过日志输出信息,例如:
- 临时批次目录清扫:打印待清扫目录名称。
- DuckDB 回收:记录归属会话存活状态、跳过原因、最终回收情况。
- 附件孤儿清理:记录清理失败详情与本轮清理总数。
仓库中未发现专门的清理任务指标上报或告警规则。运维侧建议结合应用日志、磁盘监控与数据库行数变化进行观察。
**章节来源**
- [DmService.java:1291-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1291-L1307)
- [CaseDataSourceReaper.java:44-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L44-L125)
- [ChatAttachmentService.java:404-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L404-L432)
## 运维操作建议
### 调整清理周期
可通过环境变量或配置文件调整以下参数:
| 目标 | 配置键 | 默认值 | 建议 |
|---|---|---:|---|
| 临时批次目录清扫间隔 | `zsjz.tmp.sweep-interval-ms` | 21600000 | 高频上传场景可适当缩短,但不要小于 1 小时 |
| 临时批次目录清扫初始延迟 | `zsjz.tmp.sweep-initial-delay-ms` | 600000 | 一般保持 10 分钟即可 |
| DuckDB 数据源回收间隔 | `zsjz.duckdb.reaper-interval-ms` | 300000 | 高并发长驻会话环境可缩短至 1~2 分钟,但会增加 token 校验开销 |
| DuckDB 数据源回收初始延迟 | `zsjz.duckdb.reaper-initial-delay-ms` | 60000 | 一般保持 1 分钟 |
| 附件孤儿清理间隔 | `zsjz.chat-attachment.purge-interval-ms` | 3600000 | 高频上传场景可缩短至 15~30 分钟 |
| 附件孤儿清理初始延迟 | `zsjz.chat-attachment.purge-initial-delay-ms` | 600000 | 一般保持 10 分钟 |
| 附件孤儿保留小时数 | `zsjz.chat-attachment.orphan-hours` | 168 | 不建议低于 24 小时,避免用户暂存输入框后发送被误删 |
注意:`zsjz.chat-attachment.purge-interval-ms` 控制“多久扫一次”,而 `orphan-hours` 控制“多久算孤儿”。二者要分开理解。
### 监控磁盘占用
重点监控以下目录:
| 目录 | 监控重点 |
|---|---|
| `QingJian/tmp` | 是否存在大量超过 24 小时的批次目录 |
| `QingJian/chat-attachments` | 是否堆积未关联消息的大文件、sidecar 或向量索引 |
| `.agentscope` | 是否随用户/Agent 数量线性增长 |
| PG 中 `knowledge_doc_download_log` | 下载日志是否持续快速膨胀 |
推荐指标:
- `QingJian/tmp` 目录数量与总大小。
- `chat_attachment` 表中 `link_message_id IS NULL` 的记录数。
- DuckDB 已打开案件数。
- 各清理任务最近一次执行时间与错误日志条数。
### 定位无法删除的文件
对于临时批次目录或附件文件无法删除的情况,建议按以下步骤定位:
1. 查看应用日志中对应任务的错误堆栈。
2. 确认文件是否仍被 Java 进程、Python 进程、Agent harness、浏览器或其他程序持有。
3. 在 Linux 上使用 `lsof` 或 `fuser` 查找占用文件的进程。
4. 在 Windows 上使用资源监视器或 Process Explorer 查找句柄。
5. 若文件确实属于正在运行的清洗任务或 Agent 会话,不要强制删除,应等待任务结束或恢复服务后再清理。
### 安全清理建议
- 不要直接删除 `.agentscope` 根目录。
- 不要直接删除 `QingJian/workspace`,因为它是业务 workspace 入口,可能被桌面端或 Agent 使用。
- 清理 `QingJian/tmp` 前,先确认没有正在执行的清洗任务。
- 清理 `chat-attachments` 前,先确认 `chat_attachment` 中是否仍有活跃记录。
- 如需批量清理,建议先在测试环境验证,并保留至少 24 小时观察窗口。
## 故障排查指南
### 任务未执行
可能原因:
1. Spring 调度线程池耗尽。默认大小为 4,若某个任务长时间阻塞,其他任务也可能受影响。
2. 配置文件中启用了 profile,但对应调度开关被关闭。
3. 应用启动后尚未到达初始延迟。
4. 调度注解未生效,需确认 Spring Boot 启用调度配置。
排查步骤:
- 检查 `spring.task.scheduling.pool.size` 是否过小。
- 检查最近日志中是否有调度任务启动或周期性执行记录。
- 核对环境变量是否覆盖了默认值。
- 确认应用进程处于运行状态,而非启动失败。
**章节来源**
- [application.yaml:25-32](file://ai-server/src/main/resources/application.yaml#L25-L32)
### 权限不足
典型表现:
- 临时批次目录无法删除。
- 附件文件或 sidecar 删除失败。
- 新建 workspace 子目录失败。
- Electron 上传时提示 workspace 子目录无文件。
排查步骤:
- 确认应用运行用户对 `QingJian`、`.agentscope`、`tmp`、`chat-attachments` 具有读写权限。
- 如果是容器部署,确认挂载卷权限与宿主用户一致。
- 如果是共享目录,确认网络文件系统未锁定文件。
- 在 Linux 上检查 SELinux/AppArmor 是否拦截删除。
**章节来源**
- [PathConst.java:12-109](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java#L12-L109)
- [os.js:134-200](file://ai-electron/electron/service/os/os.js#L134-L200)
### 路径不存在
典型表现:
- 临时目录不存在或为空。
- workspace 下没有子文件夹。
- chat-attachments 根目录未创建。
排查步骤:
- 确认应用启动工作目录是仓库根,使 `RUN_QINGJIAN_PATH` 指向 `QingJian`。
- 检查应用启动时是否创建 `tmp` 目录。
- 检查 Electron 上传时选择的目录最后一级是否为 `QingJian`。
- 检查 `chat-attachments` 是否在首次上传附件时被创建。
**章节来源**
- [PathConst.java:12-26](file://ai-server/src/main/java/com/zsjz/ai/common/constants/PathConst.java#L12-L26)
- [os.js:134-200](file://ai-electron/electron/service/os/os.js#L134-L200)
### 清理过于激进导致正在使用的文件丢失
当前代码对“误删”有一定防护:
- DuckDB 数据源回收仅在 token 失效且无在途任务时才关闭。
- 附件孤儿清理先做原子条件删除,防止 select 与 delete 之间用户发消息导致误删。
- 附件删除前先删向量,再删文件,单条异常不影响其他附件。
但仍需注意:
- 临时批次目录清扫没有逐目录 try/catch,删除失败可能中断后续目录处理。
- 若手动删除 `chat-attachments` 或 workspace,不会经过业务归属校验。
- 知识库下载日志没有自动清理,长期积累不会被自动删除。
建议:
- 不要在生产环境直接删除 workspace 或 `.agentscope`。
- 如需清理,优先通过业务接口或已实现的清理任务。
- 对临时目录和附件目录增加备份快照,以便回滚。
- 将清理任务纳入日志监控,关注“清理失败”“孤儿数量持续增长”等信号。
**章节来源**
- [CaseDataSourceReaper.java:44-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L44-L125)
- [ChatAttachmentService.java:397-432](file://ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java#L397-L432)
- [DmService.java:1270-1307](file://ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java#L1270-L1307)
## 结论
当前系统的清理能力集中在三个方向:
1. **临时批次目录**:按 24 小时 TTL 兜底清扫 `QingJian/tmp` 下的批次子目录,适合缓解中途失败导致的目录膨胀。
2. **DuckDB 案件数据源**:按 token 与会话状态保守回收,避免长期占用内存和 DuckDB 配额。
3. **对话附件孤儿**:按“上传后超期未关联消息”清理附件、sidecar 与向量索引,默认 7 天保留,每小时扫描一次。
Agent 工作空间本身没有独立的定时清理任务,其生命周期由 Agent 运行时、用户、工作空间和会话共同决定。知识库下载日志也没有自动清理任务。
运维上最关键的实践是:先理解每条清理规则的边界,再调整间隔和阈值;不要直接删除 workspace、`.agentscope` 或 `QingJian` 根目录;把清理任务日志纳入监控,重点关注无法删除、孤儿数量增长和调度线程池饱和等问题。