定时文件整理 agent 执行 SOP（FS-3）

术-流程 · 术层 skill 全文

本页是 <code>rules/skills/workflow_file_organization.md</code> 的逐字投影（仅隐私清洗，零改写）。

name: workflow_file_organization
status: live
req_id: FS-3
task_id: T-FS3
session_id: dafd2d92-ce6d-438f-b968-c8886c7d527d
created_at: 2026-06-16
requirement_anchor: adhoc_jobs/context_infra_base_tooling_buildout_20260615/kimi_orchestrator_setup_20260616/OPTIMIZATION_BACKLOG.md

定时文件整理 agent 执行 SOP（FS-3）

1. 本 agent 的职责边界

只做四件事：

1. 发现应归档的目录/文件。
2. 按规则把它们物理移动到 archive/ 或 redundant_archive/。
3. 补充缺失的必要入口文件（README.md / INDEX.md）。
4. 整理轻量记录目录（若已存在）。

绝对不做：

• 不删除任何文件或目录。
• 不修改被归档文件的内容。
• 不在归档过程中增补内容（只写台账和最小入口说明）。
• 不跨嵌套 git repo 边界移动内容。
• 不运行 rm、git clean、git reset --hard 等破坏性命令。

2. 执行入口

落地后路径：

python3 tools/file_organization/run_file_organization.py

默认行为是 dry-run：只报告会做什么，不真正移动。要实际执行必须加 --execute。

3. 整理动作一览

3.1 发现归档候选

每次运行先扫描以下区域：

发现结果写入运行报告，不自动移动。自动移动必须额外加 --allow-auto-archive。

3.2 分类：常规 archive vs 冗余 archive

按 FS-6 区分轴：如果把这份内容彻底删掉，会不会丢掉一处别处没有的信息？

判定顺序（命中即停）：

1. 别处有没有更新/合并后的权威副本？ → redundant_archive，reason = superseded_by_merge / superseded_by_newer_version，superseded_by 指向权威副本。
2. 是否从未成为正式记录（草稿 / demo / 空骨架）？ → redundant_archive，reason = never_canonical_draft / empty_skeleton。
3. 工作是否已完结，且本目录是唯一记录？ → archive，reason = project_completed / design_record_retained / run_log_retained，final_deliverable 指向最终交付物。
4. 模糊（部分独有 + 部分重复）？ → 默认拆分；拆分代价过大时按多数价值归类，并在 reason 写明依据。

脚本对自动发现的候选按启发规则预分类，最终分类需人确认或从 candidates.jsonl 读取。

冗余条目必须填 superseded_by。脚本若无法从 README/INDEX 提取该字段，会把候选标为 needs_review，执行前自动跳过。

3.3 物理移动

目标路径模板：

adhoc_jobs/archive/adhoc_jobs/<YYYY>/<source_basename>_<YYYY-MM-DD>/   # 常规
adhoc_jobs/redundant_archive/adhoc_jobs/<YYYY>/<source_basename>_<YYYY-MM-DD>/   # 冗余

• 保留原目录结构，便于溯源。
• 使用 git mv（已 tracked）或 mv（未 tracked），确保内容物理离开原位置。
• 移动后原位置应只剩空目录或最小入口说明；脚本不主动删除空目录，只报告。

3.4 更新引用（归档后引用处理，最低摩擦混合方案）

移动完成后，引用按三类处理，不重写历史（重写数千历史引用才是 git 混乱，且 reference_validator 不覆盖 adhoc_jobs、无法全量 CASCADE）：

1. 只更新活引用；redirect 桩仅在需要转发时才留：
• ```bash
• python3 tools/reference_validator.py rename <old_path> <new_path> --scope=l2-only [--redirect-stub]
• ```
• --scope=l2-only 只 CASCADE 活引用（rules/ tools/ contexts/ config/），历史区（runs/ / 日志 / daily_records/）不动。--redirect-stub 只在旧路径确有外部硬引用会断时才加（留极简转发桩让旧路径解析到新位置）；内容已合并、无实质依赖时不留桩、干净移除——绝不制造冗余指针桩冒充已处理（ARCHIVE_SOP §4.3）。
2. 历史引用不重写：runs/、日志、*.bak、旧报告里的引用保持原样，靠 redirect 桩解析。
3. 语义 fallback（给读文件的 agent）：当前路径找不到某内容时，去 archive/ + redundant_archive/ 找——原始记录不变，靠语义引导自动定位。

若跨嵌套 repo，记录为 stale，不强行修复。改名 _OBSOLETE 在内容已物理移动到 archive 后非必需（移动本身已表达过时）。

3.5 登记台账

每次移动在对应 manifest 追加一条 JSONL：

{
  "source_path": "adhoc_jobs/old_project_20260101",
  "target_path": "adhoc_jobs/archive/adhoc_jobs/2026/old_project_20260101_2026-06-16",
  "moved_at": "2026-06-16T03:00:00+02:00",
  "reason": "project_completed",
  "archive_type": "regular",
  "final_deliverable": "adhoc_jobs/archive/adhoc_jobs/2026/old_project_20260101_2026-06-16/README.md",
  "agent_session_id": "dafd2d92-ce6d-438f-b968-c8886c7d527d"
}

冗余条目必填 superseded_by，常规条目必填 final_deliverable。

4. 缺失产物补充规则

4.1 adhoc_jobs 目录入口

对每个顶层 adhoc job 目录（排除 archive、redundant_archive、嵌套 repo），检查：

只补充入口文件，不补充实质内容。

4.2 轻量记录目录整理

若 contexts/lightweight_records/ 已存在：

1. 读取 INDEX.md，与实际文件对比，修正路径和状态不一致。
2. 按 task_type 分组；同类型非 archive 记录达 3 条时，建议升级到子目录（dry-run 报告，执行需 --execute）。
3. status: completed 超过 30 天的记录物理移动到 archive/completed/ 或 archive/redundant/（按 FS-6 判定：frontmatter 含 archive_type: redundant 或 superseded_by 时进 redundant）。
4. 不删除任何记录文件。

4.3 产物 frontmatter 检查

对 2026-06-10 后新建的 .md 产物，检查 frontmatter 是否含 req_id / task_id / session_id / created_at。缺失时只记录到报告，不自动修改文件内容。

5. 运行流程（定时 agent 标准五步）

# Step 1: 发现候选（dry-run）
python3 tools/file_organization/run_file_organization.py scan --min-age-days 180 > /tmp/fs3_candidates_$(date +%Y%m%d).jsonl

# Step 2: 人工/编排者审查并确认 candidates.jsonl
# （可在此调用 Opus 做二次审查）

# Step 3: 执行归档 + 补充入口
python3 tools/file_organization/run_file_organization.py run \
  --candidates /tmp/fs3_candidates_$(date +%Y%m%d).jsonl \
  --create-stubs \
  --execute \
  --session-id <当前 session id>

# Step 4: 验证
python3 tools/reference_validator.py validate

# Step 5: 提交（本工作流是文件移动、骑 daily_digest 收集链兜底，按 git_safety §5 派发型机械 worker 例外不自己 commit）

6. 判据清单（agent 自验）

每次运行结束前逐项确认：

• [ ] 没有任何文件被删除。
• [ ] 所有归档都是物理移动，git status 显示原路径 deleted、新路径 added/renamed。
• [ ] 台账 archive_manifest.jsonl / redundant_manifest.jsonl 已追加。
• [ ] 分类字段自洽：regular 有 final_deliverable，redundant 有 superseded_by。
• [ ] 未跨嵌套 repo 边界移动。
• [ ] 缺失入口文件已补充并记录。
• [ ] reference_validator validate 无新增死链，或 stale 引用已记录。

7. 与相关条目的衔接

8. 验收信号对照

Backlog FS-3 验收信号：一份可被定时 agent 直接执行的文件整理 SOP（整理动作 + 判据 + archive 规则 + 缺失产物补充规则）。

• 整理动作：§3 发现 → 分类 → 物理移动 → 更新引用 → 登记台账。
• 判据：§3.1 归档候选判据、§3.2 分类四问、§6 自验清单。
• archive 规则：§3.3 目标路径、§3.5 台账 schema、§7 与 FS-5/FS-6 衔接。
• 缺失产物补充规则：§4 README/INDEX stub、轻量记录整理、frontmatter 检查。
• 可执行：配套 tools/file_organization/run_file_organization.py，默认 dry-run，--execute 实际运行。

9. 遗留问题

1. 自动发现中的「未活跃时间」阈值（默认 180 天）需根据实际运行数据校准。
2. candidates.jsonl 的审查责任由人还是由编排者承担，需在本 SOP 落地时明确。
3. 冗余 archive 的保留期（如 90 天后可安全删除）未在本 SOP 中硬编码，待后续审计需求明确。