git:20261008.a310beb to git:20261008.aae65c7

---

name: work-organizer

description: Use when 用户想整理 NAS 上的工作文件 — "帮我整理工作目录"、"根目录一堆散文件"、"文档版本太乱(最终版/final/副本)"、"找临时文件和安装包"、"几年没动的文件归档"、"办公文档按项目/年份归位"。只读扫描(scan)找出根目录散文件、版本标记混乱、同名多版本共存、副本、临时/锁定文件、安装包、过期归档候选;LLM 出 old→new 计划,用户确认后由 Agent 执行。

触发词:工作文件整理、工作目录归档、文档整理、文件版本混乱、最终版 final、副本文件清理、办公文档归档、按项目整理文件、按年份整理、临时文件清理、安装包清理、过期文件归档、work organizer、organize work files。

不适用:照片视频按日期整理(走 photo-organizer)、作品集整理(走 portfolio-organizer)、影视命名(走 media-naming)、任意类型混合目录按类型分类归档(走 file-sorter)、内容级重复文件(走 dedup-finder)。

---

# Work Organizer — 工作文件库正向合规整理

## 概述

**跨 NAS 通用**:扫描脚本跑在**本地挂载路径**上(SMB/NFS 挂载的 NAS 共享、

外置硬盘、本地同步目录都行),纯 stdlib 零依赖,不绑定任何品牌 API。

对工作文件库做**正向合规扫描**:定义合规结构(年份/项目 + 规范命名)→ 不匹配即报问题。

**写操作不在脚本里** — 扫描出问题后,LLM 生成 `old → new` 整理计划,

经用户确认后由 Agent 执行(挂载盘 `mkdir`/`mv -n`,极空间也可走 `zs` CLI / MCP tool)。

## Prerequisites

```bash

# macOS 挂载 NAS 共享(Finder → 前往 → 连接服务器)

open smb://<NAS_IP>/工作 # 极空间/群晖/威联通/绿联等均支持 SMB

# 挂载后路径形如 /Volumes/工作

python3 --version # ≥3.9 即可,无第三方依赖

```

## 快速验证

```bash

python3 work_organizer.py scan --root /Volumes/nas/工作 --sample 200

```

## 命令

| 命令 | 用途 |

|------|------|

| `scan --root PATH` | 正向合规扫描(只读) |

| `scan --root PATH --json --output F` | JSON 输出 |

| `--strict-naming` | 加查:办公文档需带日期前缀 `YYYYMMDD_` |

| `--archive-years N` | 加查:mtime 超过 N 年 → 归档候选(默认关) |

| `--max-depth N` / `--sample N` / `--top N` | 深度 / 文件数上限 / 每类显示条数 |

期望目录结构:

```

工作/

2024/ ← 年份

官网改版/ ← 项目

20240501_官网改版_需求文档_v2.docx ← 日期_项目_主题_vN

20240515_官网改版_设计稿_v1.pdf

合同/ ← 职能目录(白名单)

模板/

归档/ ← 过期文件去向

2022/…

```

## 工作流

### 场景 1:用户说"帮我整理工作目录"

**步骤**:

1. **exec** `python3 work_organizer.py scan --root <挂载路径> --output /tmp/work-issues.json`

(库很旧时加 `--archive-years 3` 一并找归档候选)

2. 读 JSON:先看 `stats`(散文件/副本/版本混乱/垃圾计数)+ `by_type` + `largest`

3. 汇报问题分布,**不做任何写操作** — 问用户从哪类开始

### 场景 2:用户说"按规范整理"

**步骤**:

1. 复用上一轮 JSON(或重新 scan)

2. 按下方「整理顺序」生成 `old → new` 映射表,**先预览给用户**

- 散文件的项目归属由 LLM 从文件名推断,拿不准的**单独列出让用户裁决**

- 版本混乱文件:给出规范新名(如 `最终版` → `_v3` 或日期后缀),逐条确认

3. 用户确认后批量执行(挂载模式):

```bash

mkdir -p "/Volumes/nas/工作/2024/官网改版"

mv -n "/Volumes/nas/工作/需求文档.docx" \

"/Volumes/nas/工作/2024/官网改版/20240501_官网改版_需求文档_v1.docx"

```

- **必须 `mv -n`**(不覆盖);同名冲突列出来交用户裁决

- 极空间用户也可不挂载,改走 zspace-nas skill 的 `zs mkdir` / `zs mv` / `zs rename`

4. 再跑一遍 `scan`,问题数下降才算完成

### 场景 3:用户说"清掉垃圾和没用的"

**步骤**:

1. scan 后过滤「临时/锁定/垃圾文件」「安装包/镜像」两类

2. 删除清单**逐类预览确认**;工作文件删除不可逆,建议先 `mv` 到 `归档/_待删/` 暂存

3. `~$xxx.docx` 是 Office 锁定文件 — 确认没有文档正被打开再删

## 整理顺序(严格)

1. 删除临时/锁定/垃圾(`~$*`、`.tmp`、`.bak`、`.DS_Store`、`._*`)

2. 副本文件 → 与原件比对大小/mtime 后建议删除或转正

3. 根目录散文件 → 按 mtime 年份 + 文件名推断项目,生成归档计划

4. 版本标记规范化:`最终/final/修改版` → 统一 `_vN` 或 `YYYYMMDD_` 前缀

5. 同名多版本组 → 保留最新,旧版移入 `归档/`

6. 安装包/镜像移出工作区(软件目录或删除)

7. 过期文件(`--archive-years`)→ 移入 `归档/YYYY/`

8. 重新 `scan` 验证

每一步都先出映射表预览,确认后再批量执行。

## 命名速查

| 对象 | 规范 | 示例 |

|------|------|------|

| 年份目录 | `YYYY` | `2024` |

| 项目目录 | 简短项目名(可带年份前缀) | `官网改版`、`2024_年度审计` |

| 办公文档 | `YYYYMMDD_项目_主题_vN.ext` | `20240501_官网改版_需求文档_v2.docx` |

| 交付快照 | `YYYYMMDD_项目_主题_已交付.pdf` | `20240601_官网改版_合同_已交付.pdf` |

| 版本 | 只用 `v1`/`v2`/`v2.1` | ❌ `最终版` ❌ `final` ❌ `真的最终版` |

| 过期文件 | `归档/YYYY/…` | `归档/2022/旧项目/…` |

- 禁止:`副本`、`(1)`、`最终版`、`打死不改`、`新建文件夹`

- 白名单职能目录(合同/财务/模板/归档/…)不强制年份结构

## 写操作通道

| 通道 | 适用 | 命令 |

|------|------|------|

| 挂载盘 shell | 任何 NAS(SMB/NFS 挂载) | `mkdir -p` + `mv -n`(同共享内移动=服务端移动) |

| `zs` CLI | 极空间(免挂载) | `zs mkdir` / `zs mv` / `zs rename` / `zs rm`(见 zspace-nas skill) |

| MCP tool | 极空间 + Agent 支持 MCP | `mkdir` / `move` / `rename` / `remove`,弹 UI 二次确认 |

## 关键约束

1. **脚本只读**:无 apply / move / rename / rm 子命令;写操作由 Agent 在用户确认后执行

2. **先预览后执行**:永远先给 `old → new` 表;`mv` 一律带 `-n`

3. **删除必须暂存**:工作文件优先 `mv` 到 `归档/_待删/`,人工确认一段时间后再真删

4. **项目归属拿不准就问**:LLM 不要强行猜项目名,单独列出让用户裁决

5. **锁定文件**:删除 `~$*`/`.~*` 前确认文档没有在别的机器上打开

6. **mtime 是弱证据**:归档判断只看 mtime,重要文件可能被动过但没改 — 归档不是删除

7. **系统/开发目录静默跳过**:`node_modules`、`.git`、`@eaDir`、`#recycle` 等不报告

## 踩坑

| 坑 | 表现 | 解决 |

|----|------|------|

| Office 临时文件洪水 | 每个目录都有 `~$xxx` | 已归垃圾类;确认无打开会话后批量删 |

| 同名多版本误合并 | `合同.docx` 在不同项目目录各有一份 | 分组键含目录,跨目录不聚合 |

| 日期前缀误报 | 文档名里带 `2024` 就算有日期 | `--strict-naming` 默认关,开启后宽松匹配全年份 |

| SMB 上 stat 慢 | 大库扫描久 | 先 `--sample 2000` 摸底;`--max-depth 3` 缩小范围 |

| 挂载断连 | 大量 `⚠️ 无法读取` | 重连 SMB 后重扫 |

## 已知 gap

- 项目归属推断靠文件名 + LLM,无语义索引;文件多的库建议分批整理

- 不做内容级去重(hash);同名多版本只按文件名分组

- 白名单职能目录名写死常见集合,公司特有目录名需改 `WHITELIST_DIRS`

- 版本组「保留最新」按文件名排序,不保证真语义最新 — 计划里带 mtime 供 LLM 判断

## 故障排查

| 现象 | 处理 |

|------|------|

| `--root 不是有效目录` | 确认 NAS 已挂载:`ls /Volumes/`;或用实际共享路径 |

| 报告里「缺日期前缀」刷屏 | 那是 `--strict-naming` 的效果;不需要就关掉该 flag |

| 归档候选太多 | 调大 `--archive-years`(如 5),或只对 `归档/` 外目录处理 |