portfolio-organizer git:20260920.d4bf53aA

Immutable. This exact content never changes and is served at /api/v1/blob/f97c1d1f99fb494c.

---
name: portfolio-organizer
description: Use when 用户想整理 NAS 上的作品集 — "帮我整理作品集"、"设计项目文件太乱"、"源文件和成品混在一起"、"项目缺封面/说明"、"成品版本太多不知道哪个是最终版"、"大体积 psd/工程文件占空间"。只读扫描(scan)按项目校验:命名年份、封面、说明文件、成品/源文件分离、多版本共存、空项目、大文件;LLM 出 old→new 计划,用户确认后由 Agent 执行。
  触发词:作品集整理、设计作品归档、项目文件整理、成品源文件分离、psd 归档、工程文件整理、项目封面、作品集规范、设计师文件整理、剪辑工程整理、portfolio organizer、organize portfolio。
  不适用:照片视频按日期整理(走 photo-organizer)、办公文档整理(走 work-organizer)、影视命名(走 media-naming)。
---

# Portfolio 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 portfolio_organizer.py scan --root /Volumes/nas/作品集
```

## 命令

| 命令 | 用途 |
|------|------|
| `scan --root PATH` | 按项目合规扫描(只读) |
| `scan --root PATH --json --output F` | JSON 输出 |
| `--large-gb N` | 源文件超过 N GB 提示压缩归档(默认 2) |
| `--max-depth N` / `--sample N` / `--top N` | 深度 / 文件数上限 / 每类显示条数 |

期望目录结构(每个项目自包含,方便整体拷贝/展示/交付):

```
作品集/
  2024_品牌设计/                 ← 年份_项目名
    cover.jpg                    ← 封面(或 封面.png / preview.jpg)
    README.md                    ← 项目说明(或 说明.txt)
    成品/                        ← 只放导出交付物(jpg/png/pdf/mp4)
      logo_横版_v3.png
    源文件/                      ← 只放工程(psd/ai/fig/blend/prproj)
      logo.psd
  字体/                          ← 白名单功能目录,不做项目校验
```

## 工作流

### 场景 1:用户说"帮我整理作品集"

**步骤**:
1. **exec** `python3 portfolio_organizer.py scan --root <挂载路径> --output /tmp/pf-issues.json`
2. 读 JSON `stats`:项目数、封面/说明覆盖率、源文件与成品体积占比、最大文件
3. 按项目汇报缺口(缺封面 N 个、混放 M 个、多版本 K 组),**不做写操作** —
   问用户从哪个项目开始

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

**步骤**:
1. 复用上一轮 JSON,过滤该项目 issues
2. 生成 `old → new` 计划,**先预览**:
   - 混放文件 → `mkdir 成品/ 源文件/` + 按扩展名分拣
   - 多版本 → 保留最终版,旧版移入 `源文件/历史版本/` 或删除(用户选)
   - 缺封面 → 建议从成品里挑一张复制/改名为 `cover.jpg`(列候选让用户挑)
   - 缺说明 → LLM 按项目内容起草 README.md 给用户过目
3. 用户确认后执行(挂载模式):
   ```bash
   mkdir -p "/Volumes/nas/作品集/2024_品牌设计/成品"
   mv -n "/Volumes/nas/作品集/2024_品牌设计/logo.png" \
         "/Volumes/nas/作品集/2024_品牌设计/成品/"
   ```
   - **必须 `mv -n`**;极空间用户也可走 `zs mkdir` / `zs mv`(见 zspace-nas skill)
4. 重扫该项目目录验证

### 场景 3:用户说"哪些工程文件太占空间"

**步骤**:
1. `scan --large-gb 1`(或更小)看「大体积源文件」列表 + `stats.largest`
2. 建议:旧项目工程压缩(`zip -r` 后删原目录)或移到冷存储/外置盘
3. 压缩/删除清单逐项确认 — 工程文件不可再生,禁止自动删

## 整理顺序(严格)

1. 删除垃圾(`.DS_Store`、`._*`、`.tmp`、锁定文件)
2. 根目录散文件 → 归入对应项目(拿不准就问用户)
3. 空项目目录 → 确认后删除或补内容
4. 项目改名:补年份前缀 `YYYY_项目名`(改名前列对照表)
5. 每个项目内拆分 `成品/` 与 `源文件/`(按扩展名分拣,预览后执行)
6. 成品多版本 → 用户选定最终版,其余移入 `源文件/历史版本/`
7. 补封面(从成品挑)、补说明(LLM 起草,用户过目)
8. 大体积源文件 → 压缩或外置归档
9. 重新 `scan` 验证

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

## 命名速查

| 对象 | 规范 | 示例 |
|------|------|------|
| 项目目录 | `YYYY_项目名` | `2024_品牌设计` |
| 封面 | `cover.*` / `封面.*` / `preview.*` | `cover.jpg` |
| 说明 | `README.md` / `说明.txt` | `README.md` |
| 成品子目录 | `成品/`(或 final/export/output) | — |
| 源文件子目录 | `源文件/`(或 source/工程/素材) | — |
| 成品文件 | `项目_内容_规格_vN.ext` | `logo_横版_3000px_v3.png` |
| 禁止 | `最终版`、`(1)`、`副本`、无年份项目名 | — |

## 写操作通道

| 通道 | 适用 | 命令 |
|------|------|------|
| 挂载盘 shell | 任何 NAS(SMB/NFS 挂载) | `mkdir -p` + `mv -n`(同共享内移动=服务端移动) |
| `zs` CLI | 极空间(免挂载) | `zs mkdir` / `zs mv` / `zs rename`(见 zspace-nas skill) |
| MCP tool | 极空间 + Agent 支持 MCP | `mkdir` / `move` / `rename`,弹 UI 二次确认 |

## 关键约束

1. **脚本只读**:无 apply 子命令;写操作由 Agent 在用户确认后执行
2. **先预览后执行**:永远先给 `old → new` 表;`mv` 一律带 `-n`
3. **工程文件不可再生**:源文件(psd/blend/prproj)禁止自动删;压缩前确认已导出成品
4. **封面/说明是建议不是强制**:用户库有自己的展示习惯时,先确认约定再整理
5. **项目级判定只看一级结构**:成品/源文件目录名用白名单匹配(中英双语),
   自定义目录名需改 `FINAL_DIR_NAMES` / `SOURCE_DIR_NAMES`
6. **白名单功能目录**(字体/素材库/模板…)跳过项目校验,避免误报

## 踩坑

| 坑 | 表现 | 解决 |
|----|------|------|
| 目录名语言混用 | `成品`/`Final`/`导出` 并存 | 白名单已含中英常见名;报告仍提示统一 |
| 版本判定 | `logo_v1/v2/v3` 全报多版本 | ≥3 个同 base 才报;保留策略交用户 |
| 大文件误报 | 视频素材当源文件 | `素材` 目录在白名单功能目录/源目录名下,不做大文件提示 |
| SMB 上 stat 慢 | 大库扫描久 | `--sample 2000` 摸底;`--max-depth 3` 缩小范围 |
| 挂载断连 | 大量 `⚠️ 无法读取` | 重连 SMB 后重扫 |

## 已知 gap

- 不识别设计软件版本兼容(如 PSD 是否含分层),只做结构校验
- 「最终版」语义靠用户确认,脚本只按文件名分组
- 白名单目录名/源文件扩展名集合有限,冷门软件格式需自行扩充 `SOURCE_EXTS`
- 项目跨年改版(2023 → 2024 迭代)视为两个项目,合并策略交用户

## 故障排查

| 现象 | 处理 |
|------|------|
| `--root 不是有效目录` | 确认 NAS 已挂载:`ls /Volumes/`;或用实际共享路径 |
| 所有项目都报「缺封面」 | 用户用子目录放封面(如 `预览/`);确认约定后调整白名单或跳过该项 |
| 扫描很慢 | 缩小 `--root` 到单个项目,或 `--sample` 限量 |