# 定时任务与工作空间清理 **本文引用的文件** - [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` 根目录;把清理任务日志纳入监控,重点关注无法删除、孤儿数量增长和调度线程池饱和等问题。