decodie-overview

Decodie — 概览模式

生成文件、目录或项目的高层概览，回答“这是什么，以及它是如何组织的”，而非逐行解释。每个目标生成一条摘要，作为入门起点。

此模式默认会持久保存——概览将保存为学习条目。对同一目标重新运行时，会覆盖现有概览，而不是累积多个版本。

此模式不会修改源代码。你只需读取源文件，并写入 .decodie/ 目录。

激活与参数解析

1. 提取目标路径。 如果未提供，则使用项目根目录。
2. 验证目标。 确认目标存在，且为文件或目录。
3. 确定目标范围：
   • 文件 — 可省略 entry_points 和 dependencies。
   • 目录 — entry_points 和 dependencies 通常有意义。
   • 项目根目录 — 四个概览字段均适用。
4. 规范化目标路径，以便查找要重新生成的条目：
   • 文件：相对路径（例如，src/utils/helpers.ts）
   • 目录或项目根目录：末尾带斜杠的相对路径（例如，src/auth/、./）

设置

1. 检查项目根目录中是否存在 .decodie/。如果不存在，则创建：

   • .decodie/index.json，内容为 { "version": "1.0", "project": "<directory-name>", "entries": [] }
   • .decodie/config.json，包含默认偏好设置
   • .decodie/sessions/ 目录
   • .decodie/rules/ 目录

2. 加载规则。 检查 ~/.decodie/rules/*.md（全局规则）和 .decodie/rules/*.md（项目规则）。读取找到的所有 .md 文件。将其内容视为控制文档输出的附加指令，包括语气、语言、详略程度、格式和受众。发生冲突时，项目规则优先于全局规则。如果不存在规则，则使用默认设置。

3. 加载索引摘要。运行：

   bash scripts/summarize-index.sh "$(pwd)"
   

   如果无法执行，则直接读取 .decodie/index.json。

4. 确定会话 ID。在 .decodie/sessions/ 中查找今天匹配 overview-YYYY-MM-DD-NNN 的最高 NNN，然后递增。

重新生成与新建条目

生成之前，检查是否已有概览：

1. 读取 .decodie/index.json。
2. 查找满足 decision_type === "overview" 且 sources 为 [<canonicalized-target-path>] 的条目。
3. 如果找到（重新生成）：沿用现有 id，生成新内容，并原位更新索引条目。上一个会话文件会保留在磁盘上，但不再被引用。
4. 如果未找到：使用新的 ID 生成条目。

生成流程

1. 读取目标：

   • 文件：完整读取。
   • 目录：列出顶层条目，读取结构性文件（package.json、composer.json、pyproject.toml、README.md 等），并抽样读取有代表性的源文件。
   • 项目根目录：还需检查入口点清单和依赖清单。

2. 识别四个概览维度：

   • purpose（必填）— 用 2-4 句话描述这段代码的用途。开篇说明目的，而非实现方式。
   • structure（必填）— 描述代码的组织方式（各部分、模块、关键目录及其作用）。
   • entry_points（可选）— 可调用入口：导出的函数、CLI 命令、HTTP 路由、框架钩子。如果没有意义，则省略。
   • dependencies（可选）— 值得关注的内部或外部依赖，以及它们提供的功能。省略无关细节。

3. 使用平实的文字。 避免使用术语密集的项目符号列表；目标是帮助读者快速上手。根据范围调整篇幅。

条目生成

索引条目元数据

• id：重新生成时复用现有值；否则生成新值。格式：entry-{unix-timestamp}-{random-4-hex-chars}
• title：例如，“概览：src/auth/ — 令牌签发与验证”
• experience_level："foundational"（概览是新手引导入口）。
• decision_type："overview"
• topics：小写 kebab-case 标签。复用现有标签。
• lifecycle："active"
• sources：恰好包含一个条目的数组，即规范化后的目标路径。
• references：对于单文件概览，添加一个指向该文件的引用；对于目录或项目，使用空数组。
• content_file：会话文件的相对路径，例如 sessions/overview-2026-03-27-001.json

会话条目内容（概览格式）

使用概览格式，与标准条目不同：

• decision_type："overview"
• purpose（必填）——目标代码的用途
• structure（必填）——目标的组织方式
• entry_points（可选）——可调用接口
• dependencies（可选）——重要依赖项

会话结束

1. 设置 timestamp_end。
2. 编写 summary，说明目标以及这是新建还是重新生成。
3. 确认：
   • 新建：“已为 <target> 生成概览，作为会话 <session_id> 中的条目 <id>。”
   • 重新生成：“已重新生成 <target> 的概览（条目 <id>）。”

数据格式

有关完整的 .decodie/ 数据格式，请参阅 references/schema.md。

重要说明

• 始终保持最新，而非只追加。 重新运行会覆盖索引条目。
• 每个目标仅对应一个条目。 不要拆分为每文件条目——这是分析模式的工作。
• 如实说明不确定性。 如果目标用途不明确，请明确说明。
• 语言无关。 根据项目使用的语言和框架进行调整。
• 数据独立。 删除 .decodie/ 目录不会影响项目。