storops 是做什么的？
了解存储去向。理解原因。移动重要内容。清理无用内容。
StorOps 不是磁盘扫描工具，也不是磁盘清理工具。WizTree 已经回答了“什么东西占用了空间”——而 StorOps 回答的是这些“东西”是什么，它们是否安全可触碰，并在用户同意后安全地执行清理或迁移。完整的设计理念见 docs/DESIGN.md。
本文定义了代理在使用 StorOps 时应该如何表现——不仅仅是存在哪些命令。优先遵循以下工作流，而不是临时调用命令；用户不应该需要知道命令名称。
不可协商的规则
- 分析先于行动。在提出任何建议之前，务必先扫描/检查/识别，绝不得直接跳到写入操作。
- 所有操作默认为只读。
storops scan、storops inspect、storops search、storops identify、storops cleanup plan和storops migrate plan从不修改文件系统——可以自由运行，无需事先询问。 - 绝不要仅凭路径名称猜测其内容。只有
storops identify（基于rules/*.yaml）能够确定类别/风险/可删除性。没有匹配规则的路径将返回unknown/critical——应将其视为“不可触碰”，而不是根据文件夹名称进行推理的邀请。 - 绝不要因为名称中包含“cache”或“temp”就认为可以删除。只对
storops identify/storops cleanup plan实际分类过的内容进行操作。 - 高风险路径（Windows、Program Files、未知的系统文件、用户文档）永远不提供删除或迁移选项。这已在代码中强制执行（
src/storops/core/risk.py中的assert_not_critical），而不仅仅是约定——不要试图绕过它。 - 每次写入操作（
storops cleanup execute、storops migrate execute）都需要用户事先逐项确认，CLI 本身在缺少--confirm时拒绝运行。展示计划，等待用户明确说“是”，然后传入--confirm——绝不要代表用户提前添加该参数。 - 如果某个应用程序可能正在运行，不要移动其数据。
storops migrate plan会标记RequiresAppClosed；在这种情况下，storops migrate execute拒绝运行，除非显式提供--app-closed。告诉用户关闭应用程序——不要假设它已关闭，也不要自己终止进程。 - 对于大型、可重新下载的 AI 模型/缓存数据（Hugging Face 缓存、Ollama/LM Studio 模型等），在将其纳入用户批准的方案之前，务必明确说明后果（“这将需要重新下载”）。
- 对于用户认为有价值的内容，优先迁移而非删除。删除适用于可回收/可丢弃的数据；不可丢弃的大型模型或项目数据应提供“移动”而非“删除”选项。
- 优先使用应用程序自身的基于配置的迁移方式，而非符号链接（Junction）。
storops migrate plan已经编码了这种优先级——不要仅仅因为它看起来更简单就强行改为符号链接。 - 每次迁移后都要进行验证（根据
storops migrate execute写入的结果文件运行storops verify）。如果验证失败，如实说明并停止——绝不能删除或进一步修改任何数据来“解决”验证失败。 - 不要将扫描后端（Windows 上的 WizTree，Linux/macOS 上的 gdu/du）作为推理中的硬性依赖。如果它完全缺失，CLI 会给出明确的错误提示，说明获取位置（WizTree：https://diskanalyzer.com/ 或
$env:STOROPS_WIZTREE_PATH；gdu：https://github.com/dundee/gdu 或$env:STOROPS_GDU_PATH）——请将此信息转达给用户，而不是尝试以其他方式自行解决。 - 在 Linux/macOS 上，每个读取/计划层命令（
scan/inspect/search/cleanup plan/migrate plan）的--json结果都包含Backend和BackendAdvice字段。仅当 StorOps 因未找到gdu而回退到较慢的du后端时，BackendAdvice才不为空。在每个会话中提及一次（例如“顺便说一句，安装 gdu 会使这些扫描明显更快”），但不要在每次命令中都重复，在 Windows 上或当它为null时也不要提及。
工作流：“为什么我的驱动器满了？”
storops scan C:\（或用户提到的驱动器）了解顶级消耗者和空闲空间。- 对于任何大型且未识别或模糊的条目，运行
storops inspect查看其内部实际内容。 - 将每个显著条目与
storops identify交叉引用（scan/inspect 已经附加了身份和建议操作，但用户询问单个路径时直接调用它）。 - 展示一个分层排序的摘要：它是什么、有多大、以及建议操作（KEEP / DELETE / MOVE / CHECK）及其原因和风险。
- 在此阶段绝不删除或移动任何内容——这纯粹是诊断。
工作流：“清理磁盘空间”/“删除 X”
- 确保目标已经过扫描/识别（如果尚未执行，先运行上述扫描工作流）。
- 运行
storops cleanup plan（默认--max-risk low；仅当用户明确表示接受中等/高风险项目时才提高风险等级）。这会生成一个逐项列出的 JSON 计划——尚未删除任何内容。 - 按风险层级分组展示计划：每个项目的大小、应用程序和后果（明确说明中等/高风险后果，例如“可能需要重新下载”）。显示可回收的总大小。
- 请求用户确认。如果用户只需要子集，则使用更严格的
--max-risk重新生成，或指出哪些项目应跳过——不要未经告知用户具体更改内容就手动编辑计划文件中的Approved标志。 - 只有在用户确认后，才运行
storops cleanup execute --plan-file <path> --confirm。 - 报告每个项目的结果（已删除 / 已跳过 / 失败）以及回收的总大小。
failed项目（例如文件正在使用中）仅报告，不会强制重试。
工作流：“将 X 迁移到另一个驱动器”
- 识别源路径（如果尚未从扫描中得知，则运行
storops identify）。如果它不是Migratable，如实说明并解释原因（例如关键路径，或没有已知的迁移路径），而不是自己临时编造一个。 - 运行
storops migrate plan <source> <destination>。这会决定方法（应用程序配置更改，或符号链接作为回退），并生成有序的步骤列表——尚未移动任何内容。 - 展示计划：源路径、目标路径、大小、方法以及是否需要先关闭应用程序。如果
RequiresAppClosed，明确要求用户先关闭应用程序。 - 请求用户对整个计划的确认。
- 运行
storops migrate execute --plan-file <path> --confirm（在用户确认应用程序已关闭后添加--app-closed）。这会复制数据，验证文件数量/大小与源路径一致，然后才删除原始内容——对于符号链接方法，还会重新链接旧路径。 - 如果方法是应用程序配置更改（而非符号链接），告诉用户需要进行的精确配置更改（来自计划的
MigrationHint）——StorOps 本身不会编辑任意应用程序配置文件。 - 运行
storops verify --result-file <path from migrate execute output>并报告每项检查的 PASS/FAIL。在 FAIL 时，停止并准确描述不匹配的内容——绝不要删除剩余数据来“解决”验证失败。
工作流：“删除/移动 安全吗？”
只需运行 storops identify <path>，并逐字报告类别、可删除性、可迁移性、清理风险、后果和建议操作——这是一个直接、确定性的答案；不要超出规则库实际内容的范围进行编辑，也不要为 unknown 结果猜测。
命令参考
| 层级 | 命令 | 确认方式 |
|---|---|---|
| 读取 | storops scan, storops inspect, storops search, storops identify | 无 |
| 计划 | storops cleanup plan, storops migrate plan | 无（仅生成计划文件） |
| 写入 | storops cleanup execute, storops migrate execute | 需要 --confirm（以及迁移需要时还有 --app-closed） |
| 验证 | storops verify | 无（只读重新检查） |
每个命令都支持 --json 以获得机器可读的输出。以 python -m storops <命令> ... 或 storops <命令> ... 形式调用（如果已通过 pip install 安装包）。
有关设置/要求，请参阅 README.md；有关标识背后的规则模式，请参阅 rules/README.md。