soia-env-storage-cleanup

先只读统计 SOIA 受管目录，再生成有时效、带摘要的清理计划。删除属于不可逆高风险动作：必须把候选类别、大小、条件和风险展示给客户，等待客户针对这份计划明确授权后，才能执行并复核。

客户可读说明

这个技能可以做什么

本技能只清理 SOIA 标准受管目录，不扫描或清理整个磁盘，不删除普通下载、项目、照片、文档或其他应用数据。

客户如何使用

客户只需要用自然语言提出目标，不需要操作终端：

1. 客户说“检查 SOIA 占用”时，只执行扫描，不删除任何文件。
2. 客户说“清理缓存”时，先生成计划并展示风险；这句话只表示目标，不是最终删除授权。
3. Agent 必须停下来等待客户在看到最新计划后明确回复，例如“确认按计划 <plan_id> 删除”。
4. 只有同一份未过期计划获得授权后，Agent 才执行清理；模糊的“继续”“随便处理”不能作为授权。
5. 清理完成后重新检查，并向客户报告实际结果。

依赖与安装

本技能不保存账号或凭据。以下变量只能覆盖受管目录位置，值必须是目录而不是秘密：

SOIA_SKILLS_CONFIG_HOME
SOIA_SKILLS_STATE_HOME
SOIA_SKILLS_CACHE_HOME
SOIA_SKILLS_TEMP_HOME

使用环境变量指定自定义根目录时，必须先向客户展示目标目录并取得配置确认，再写入类别匹配的 .soia-storage-root.json；缺少标记时执行器拒绝把任意目录认领为 SOIA 存储。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

私密信息与中间数据

• 配置目录只统计、不删除；凭据仍由 provider 登录态或系统凭据库管理。
• 清理计划和回执保存在用户 state 目录，使用用户私有权限；不得提交到 Git。
• 计划内部可以保存精确路径用于防止删错，但客户回复只展示脱敏类别、数量和大小。
• 不读取文件正文，不计算内容摘要；状态清理只读取受管策略标记。
• 不把仓库、用户主目录、客户交付物或未知目录认领为可清理目录。

强制授权与风险提醒

扫描、计划和删除是三个独立阶段。初始“帮我清理”请求不能同时授权尚未生成的候选清单。

执行删除前必须向客户显示：

风险提醒：下面的删除不可撤销，可能导致缓存重新下载、审计历史缩短，
或使依赖这些中间文件的任务需要重新运行。配置、凭据和客户交付物不会删除。
请确认是否按计划 <plan_id> 删除 <候选文件数> 个文件，预计释放 <大小>。

只有客户在这条提醒之后明确确认当前 planid，才能生成 authorizationid 并调用执行命令。以下情况必须重新扫描并重新授权：

• 计划超过 30 分钟；
• 计划摘要不匹配；
• 候选文件或状态策略发生变化；
• 客户修改清理范围；
• 需要增加新的目录或数据类别。

清理范围和方式

无论客户如何授权，以下对象仍必须拒绝：

• SOIA 受管根目录之外的路径；
• 符号链接、设备、socket 和非普通文件；
• 含新鲜 .soia-active 标记的活动目录；
• .soia-active、.soia-managed-storage.json 安全标记本身；
• .soia-storage-root.json 根目录标记本身；
• 未带有效状态清理标记的 state 文件；
• 文件大小或修改时间在计划后发生变化的候选；
• 配置、凭据和客户交付物。

详细机器合同和标记格式见 [清理安全合同](references/cleanup-contract.md)。

工作流

1. 只读扫描

Agent 运行：

python3 scripts/storage_cleanup.py scan --json

扫描不得创建目录、计划或回执。把机器输出转换为下面的客户列表，不回显精确私有路径。

2. 生成清理计划

客户要求清理时运行：

python3 scripts/storage_cleanup.py plan --json

计划只能写入受管 state 目录，包含 30 分钟有效期、候选文件元数据和 plan_digest。生成计划仍不代表授权，也不删除文件。

3. 展示计划并等待客户授权

向客户展示：

然后发送强制风险提醒并结束当前执行回合。没有客户新回复，不得进入第 4 步。

4. 按授权计划清理

确认客户明确授权当前计划后，由 Agent 生成不含客户原话的随机 authorization_id，记录授权时间，并运行：

python3 scripts/storage_cleanup.py clean \
  --plan <managed-plan-path> \
  --plan-digest <plan-digest> \
  --confirmed-plan-id <plan-id-confirmed-by-customer> \
  --authorization-id <opaque-authorization-id> \
  --authorized-at <RFC3339-with-timezone> \
  --acknowledge-risk CUSTOMER_APPROVED_IRREVERSIBLE_DELETE \
  --execute --json

不得替客户预填授权，不得把 --execute 放进扫描或计划命令。--confirmed-plan-id 必须来自客户在风险提醒后的明确回复，并与计划精确匹配。执行器只删除计划中仍未变化且仍符合条件的普通文件；不确定项进入 skipped。

5. 复核

清理后运行：

python3 scripts/storage_cleanup.py verify --receipt <managed-receipt-path> --json

核对实际删除数量、删除字节数、失败/跳过项、磁盘空闲空间变化和文件是否重新出现。删除命令返回 0 不能代替复核。

客户状态列表（强制）

• 只有扫描完成时写“已扫描”；生成计划后写“等待授权”。
• 没有客户针对当前计划的明确授权时，处理结果必须写“等待客户确认”，不能写“已清理”。
• 更新时间 是最后一次扫描或删除复核完成时间，不是技能文件修改时间。

日志与完成回执

客户可见回复只报告：

• 四类受管数据的大小、文件数和候选大小；
• 当前 plan_id、有效期和是否等待授权；
• 风险提醒和禁止清理类别；
• 授权后实际删除/跳过数量、删除字节数和复核状态；
• 不显示精确私有路径、文件名、用户名、token 或文件正文。

本地机器回执保存 plandigest、authorizationid、authorizedat、checkedat、删除结果和 receipt_digest，权限尽量使用目录 0700、文件 0600。

前向测试

至少覆盖以下 fixture：配置文件永不删除；过期 cache/temp 可进入计划；新文件和活动目录不进入计划；state 缺标记时拒绝；符号链接拒绝；错误/过期摘要和缺少授权时阻断；候选在计划后变化时跳过；授权成功后只删除计划内文件并复核回执。

真实机器验收只运行 scan。删除前向测试必须在测试临时目录内完成，不能用真实客户目录验证。