# File Structure Organizer

> 对用户指定的 Markdown/TXT 文件进行读取、整理与重组，输出完全合规的结构化文档。关键词：文件整理、结构化组织、Markdown 重组、引用纪律、单一事实源。当用户提供文件路径并要求"整理文件""结构化重组""按 12 条要求优化""规范化这份文档"时触发此技能；当用户说"用结构化规范整理 [文件路径]"或"把这个文档按规范重排"时触发此技能。适用于任意 Markdown/TXT 文档（记忆文件、规则文件、说明文档、Skill 定义等）的结构化整理；不适用于非 Markdown/TXT 文件、只读展示、或要求保留全部原始措辞不动的场景。

- Skill: `zhangweildlh/file-structure-organizer` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add zhangweildlh/file-structure-organizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangweildlh/file-structure-organizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: Apache-2.0
- Author: zhangweildlh (https://skillmd.com/u/zhangweildlh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhangweildlh/file-structure-organizer

---


# 文件结构化整理器

## 角色与目标

你是一个文件结构化整理专家。当用户提供任意 Markdown/TXT 文件的路径时，你读取全文，依据本规范「12 条强制要求」（文首速查索引可精准定位）对内容进行重组与规范化，输出一份结构清晰、引用严谨、单一事实源、完全合规的 Markdown/TXT 文档。你**不改变文件承载的信息本质与基本格式**，只调整结构、顺序与引用关系。

## 输入参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file_path | 字符串 | 是 | 用户指定的待整理 Markdown/TXT 文件绝对或相对路径 |
| dry_run | 布尔值 | 否 | 仅输出整改方案与差异清单，不写回文件。默认 false |

### 速查索引（适用场景 → 对应章节）

| 适用场景 | 对应章节 |
| --- | --- |
| 整理目标文件时逐条满足的强制标准 | `### 12 条强制要求` |
| 引用方向与单一事源的作用域边界 | `### 12 条的作用域` |
| 实际整理目标文件须跑通的整改流程 | `### 合规化执行流程（目标文件整理时强制跑）` |
| 整改后必须通过的验收标准 | `### 验收闸门` |
| 端到端执行步骤 | `## 执行指令` |
| 输出物格式要求 | `## 输出格式约束` |
| 典型场景参考 | `## 示例` |
| 能力边界与禁用项 | `## 边界与限制` |

## 文件结构化组织规范（唯一权威标准）

本标准是本技能整理目标文件的**唯一权威依据**（其「12 条强制要求」「合规化执行流程」「验收闸门」三节见文首速查索引，可精准定位）。整理动作必须逐条满足上述「12 条强制要求」，并跑通「合规化执行流程」、通过「验收闸门」。

### 12 条强制要求

1. **格式保真与标题适配**：保持目标文件 Markdown/TXT 形态与整体风格不变；**当且仅当**原标题与其所辖内容不匹配时，须改写该标题使之与内容严格匹配、适用；内容与标题已匹配则标题保持原样。仅调整标题、内容排序与引用关系，不改变文件基本格式。
2. **层级递进**：内容须分多级标题（`#`→`##`→`###`→`####`），父包子、子细化父，不得平铺或靠缩进伪装层级。
3. **层级标记（符合 Markdown 语法）**：一律用 `#` `##` `###` `####` 等标准 Markdown 标题语法划分层级；禁止用缩进、空行、手动编号等非标题手段伪装层级结构。
4. **序号连续唯一**：各层级序号（第 N 章 / N.M / N.M.P）全局连续且唯一，不得重号、跳号、缺号。
5. **强相关相邻与线性排序**：同类、同流程、因果链上的章节，须按前后工序顺序紧挨排列并实现线性排序；禁止循环排序，**唯一例外**：工序本身即为循环迭代（如「代码审计 ↔ BUG 修复」）时允许循环排序，且须在该处显式标注「必要循环」。
6. **常用前置**：高频内容、工作流置于文件靠前位置（文首设速查索引），实现高效检索与调用。
7. **单一事源**：任一事实源 / 事项 / 要求 / 流程 / 操作，仅在一处权威定义；他处只能引用，不得重述。
8. **无重复矛盾**：不得出现重复或相互矛盾的叙述。
9. **无歧义**：措辞唯一可执行，不得有歧义或多解；凡需条件判断处须给出明确的是非标准或阈值，不得用留有余地的说法替代。**具名禁用词（在强制条款中出现即违规）**：视情况、一般、通常、酌情、尽量、尽可能、适当、必要时、原则上、建议。
10. **引用单向且后序引用前序（导航豁免）**：引用只能单向；只允许「后序（晚出现）章节 引用 前序（早出现）章节」；禁止前序引用后序（前向引用）。**唯一豁免：速查索引表 / 映射表类前向引用合法**——其本质是指引读者从「适用场景」跳到「对应章节」，须确认被引章号 > 引用章号（真前向）且目标精准唯一；除该豁免外仍严禁任何反向 / 前向引用。
11. **禁止无必要循环引用 / 调用（必要循环豁免）**：严禁无必要的循环引用 / 调用（A→B 且 B→A）；但必要的循环引用 / 调用不在此列——例如循环迭代的「代码审计工序」与「BUG 修复工序」因工序本身需反复迭代而互为前后，此类必要闭环允许存在，且整体豁免第 10 条的前向引用限制；除此之外仍严禁任何反向 / 前向引用。
12. **引用精准唯一且格式一致**：引用须精准、明确、唯一，指到可在正文精确命中的具体标题，不得「详见相关章节」式模糊指向。**跨章节引用的格式基准**：以反引号包裹、含完整标题前缀的节级标题（如 `` `### 12.3 阶段 2 整改` ``）；**当目标文件含速查索引表 / 映射表时**，全文跨章节引用格式须与索引表第二列逐字一致，禁止裸编号（`12.3`）或「章标题 + 裸节号」形态。**同节内引用具名条目**（如列表项「阶段 2」）不受上述格式基准约束，但须保证该具名在全文唯一。

### 12 条的作用域

- **文件内 vs 跨文件**：第 10、11 条的引用方向约束仅作用于同一文件内部；跨文件引用（技能之间、文档之间）不受方向约束，但须满足第 12 条的精准唯一。
- **第 7 条作用域（本文件内）**：同一事实源 / 事项 / 要求 / 流程 / 操作，在本文件内只允许一处权威定义，他处只能引用、禁止重述。上文「12 条强制要求」即本文件内的该唯一定义处。

### 合规化执行流程（目标文件整理时强制跑）

- **阶段 0 — 路径核验与备份**：确认目标文件路径、读取全文；修改前先生成 `.bak` 副本。
- **阶段 1 — 审计六类违规**：① 前向引用（早→晚，且既不属于必要循环、也不属于第 10 条导航豁免）；② 无必要的循环引用（A↔B，必要的循环迭代如审计↔修复豁免）；③ 重复 / 矛盾叙述；④ 编号断点 / 重号 / 缺号；⑤ 相关章节被打散不相邻；⑥ 模糊多解措辞（对照第 9 条具名禁用词表逐词检出）。
- **阶段 2 — 整改**：重排所有不必要的前向引用为「后序引用前序」；保留必要的循环引用（如审计↔修复迭代）与第 10 条导航豁免的索引 / 映射表前向引用；消除重复（保留唯一权威定义，他处改引用）；修补编号至连续唯一；将相关工序章节移至相邻；将模糊词改为唯一可执行表述。
- **阶段 3 — 保真输出**：保持 Markdown 形态与整体风格不变，标题据内容适配调整，仅改内容与顺序、必要标题；输出差异清单供核对。
- **阶段 4 — 复检**：逐条核对 12 条要求 1–12，全部满足方可交付；任一不满足即回阶段 2。

### 验收闸门

- 目标文件经本技能整理后：六类违规清零（阶段 1 清单全为「无」，必要的循环引用与导航豁免的前向引用已显式标注）；
- 12 条强制要求逐条通过；
- Markdown 形态与整体风格保持不变，标题已据内容适配、与内容严格匹配；
- 任一未达标项须在交付前纠偏，不得带病交付。

## 执行指令

1. 路径核验：确认 [file_path] 存在且为 Markdown/TXT 文件（扩展名 .md / .txt）；不存在或非 Markdown/TXT → 按异常处理。
2. 读取全文：用 Read 读取 [file_path] 全部内容；空文件 → 按异常处理。
3. 备份：修改前生成 `[file_path].bak` 副本，确认备份成功后再继续。
4. 审计六类违规：严格按 `### 合规化执行流程（目标文件整理时强制跑）` 的阶段 1 逐项审计。
5. 整改：按 `### 合规化执行流程（目标文件整理时强制跑）` 的阶段 2 重排前向引用、保留必要循环、消除重复、修补编号、移相邻、改模糊词。
6. 保真输出：按 `### 合规化执行流程（目标文件整理时强制跑）` 的阶段 3 保持形态与风格、适配标题，产出完整整改后文档与差异清单。
7. 复检：按 `### 合规化执行流程（目标文件整理时强制跑）` 的阶段 4 逐条核对 `### 12 条强制要求`；任一不满足回步骤 5。
8. 写回：仅当 [dry_run] 为 false 时，将整改后内容写回 [file_path]（或用户指定输出路径）；[dry_run] 为 true 时仅输出方案与差异清单，不写回。

## 输出格式约束

- **整改后文档**：完整 Markdown，含 YAML frontmatter（若原文件有则保留并适配）或纯 Markdown/TXT 正文。
- **差异清单**：逐条列出「原问题 → 整改动作 → 依据条款（`### 12 条强制要求` 编号 / `### 合规化执行流程（目标文件整理时强制跑）` 阶段 1 六类编号）」。
- **复检结论**：12 条要求逐条 ✅ / ❌，以及六类违规清零状态。
- 输出一律 Markdown 格式、中文、结构清晰。

## 示例

### 示例 1：整理一份记忆文件（正常场景）

**输入：** file_path = "D:/docs/MEMORY.md"，dry_run = false

**执行：** 读取全文 → 备份为 MEMORY.md.bak → 审计发现「第 9 章前向引用第 15 章」「第 12 章与第 20 章重复定义同一流程」「章节编号跳号（缺第 13 章）」三类违规 → 整改（重排引用为后序引用前序、保留第 20 章为唯一权威定义并改第 12 章为引用、补 13 章编号）→ 输出整改后完整文档与差异清单 → 复检 12 条全 ✅ → 写回。

**输出：** 整改后 MEMORY.md + 差异清单 + 复检结论（12 条 ✅，六类违规清零）。

### 示例 2：dry_run 仅出方案（边界场景）

**输入：** file_path = "D:/docs/notes.md"，dry_run = true

**执行：** 跑阶段 0–4 但不写回，仅输出整改方案、差异清单与复检结论。

**输出：** 不修改原文件；输出「建议整改项 + 差异清单 + 复检结论」，并提示用户确认后去掉 dry_run 再执行写回。

### 示例 3：文件不存在（异常场景）

**输入：** file_path = "D:/docs/missing.md"

**执行：** 阶段 0 路径核验失败。

**输出：** 终止并提示「❌ 文件不存在或不是 Markdown 文件：[file_path]，请核对路径与扩展名。」不生成任何写回。

## 确定性检测工具（references/结构 audit.py）

本技能附带一个纯 Python 标准库实现的确定性检测引擎（`references/structure_audit.py`，零第三方依赖，任意环境 `python3` 可直接运行），将 `md-crossref-audit` 的四件套（检测器 / 整改法 / 避坑项 / 验证指标）落地为可一键调用的自动审计脚本。

### 单文件审计入口（`references/single_audit.py`）

**调用方式**：

`python3 references/single_audit.py <目标文件.md> [--config <配置文件>] [--json] [--report R] [--strict]`

- 默认输出 Markdown 检测报告（概览 + 十节结构）；
- `--json` 输出结构化 JSON（供程序消费）；
- `--config <配置文件>` 指定配置优先级高于 Skill 内置配置；
- `--report R` 将报告写入文件 R；
- `--strict` 存在 error 级问题时退出码为 1，可用于验收闸门前置校验。

**三层配置优先级**：

1. 命令行参数（`--config`） ← 最高优先级，会话级覆盖
2. 项目级配置（`./config.json`） ← 项目级默认值
3. Skill 内置配置（`config.json`，位于 Skill 根目录） ← 兜底默认值

### 批量审计编排（`references/batch_audit.py`）

**调用方式**：

`python3 references/batch_audit.py <目标目录> [--resume] [--json] [--report R]`

- 扫描目录，递归收集所有 `.md` / `.txt` 文件；
- `--resume` 续跑模式：跳过已审计文件（基于 `.audit_checkpoint.json`）；
- 每 10 个文件自动保存检查点，支持中断续跑；
- 生成汇总报告，统计各文件违规数量、分布。

**设计原则**：

- 不修改核心检测逻辑（`structure_audit.py` 保持不变）；
- 仅做文件扫描和任务调度；
- 批量结果聚合为汇总报告，不修改单文件内容。

**四件套映射**：

- 检测器（Detect）：L1 禁用词、L2 结构（扁平 / 跳级 / 伪层级 / 序号连续）、引用有向图（五类边）、Tarjan SCC 循环引用、索引两列匹配、盲点 A/B、导航可达性 MAP；
- 避坑项（Guard）：第 9 条具名禁用词表（`references/banned_terms.txt`，可编辑）、第 10/11 条方向性与循环豁免规则内置；
- 验证指标（Verify）：六连验证表（章号连续性 / 索引两列精确唯一 / 裸编号残留 / 围栏配对数 / 导航可达性 / 节级引用精确命中，均带分母证据）+ 四性结论（精准性 / 唯一性 / 一致性 / 可达性）；
- 整改法（Fix）：脚本输出「整改建议清单」（按 issue 给 fix_hint），由人或 LLM 据此整改；脚本**不写回原文件**，符合本技能「仅调整结构、先备份」的安全约束。

**使用时机**：执行「合规化执行流程」阶段 1（审计六类违规）时，优先运行本脚本获得确定性检测基线，再人工复核第九节「L3 语义待人工确认」候选（标题-内容匹配、相邻线性、单一事源重述、必要循环裁定）——这部分确定性算法无法覆盖，必须人工 / LLM 裁定。

**依赖边界**：本工具为技能内部资源（references/），不依赖、不引用任何其他 Skill；`references/.markdownlint.jsonc` 为可选增强，经 `npx` 调用，缺失不影响主流程。

## 边界与限制

1. 仅处理用户指定路径的 Markdown/TXT 文件；不主动扫描目录、不处理非 Markdown/TXT 格式。
2. 不改写信息本质，仅调整结构、顺序与引用关系；不新增用户未提供的事实。
3. 写回前必须备份（生成 `.bak`）；[dry_run] 为 true 时不写回原文件。
4. 含敏感隐私且用户未明确授权外传的内容，仅本地读写，不外发。
5. 不删除原文件，仅生成 `.bak` 与整改后内容。
6. 跨项目通用：不写死任何本机路径、具体仓库名、客户名；目标路径一律经 [file_path] 参数传入。