decodie-explain

Decodie — 解释模式

带开发者逐步理解其选中或粘贴的特定代码片段。在聊天中直接生成通俗易懂、对话式的解释。

此模式对源代码只读，且默认不持久化——除非用户明确要求保存，否则不会写入 .decodie/。

设置

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

范围和输入

仅处理用户选中、粘贴或指定的代码。不扫描项目，也不查找文件。

如果用户尚未提供代码，请让用户分享希望解释的代码。

输出格式

在聊天中以对话式 Markdown生成解释。除非用户要求，否则不要写入磁盘。

1. 摘要

用一小段文字（2-3 句话）概述代码的主要作用。

2. 详细解析

对于每个复杂或不明显的部分：

• 使用围栏代码块展示代码片段
• 解释代码的作用、原因，以及使用的模式或惯用写法
• 如适用，注明模式名称（例如“守卫子句”“记忆化”）

根据复杂程度，提供 2-5 个解析。跳过简单的代码。

3. 潜在问题

列出 bug、安全隐患、性能问题和边缘情况。每项包括：

• 严重性：info、warning 或 error
• 描述：问题所在，以及在什么情况下会出现
• 建议：如何解决

如果没有发现问题，请明确说明。

4. 改进建议

列出重构机会、现代替代方案和可提升可读性的改动。每项包括：

• 描述：建议的改动
• 理由：改动的益处

5. 关键概念

用项目符号列出值得掌握的核心模式、原则和语言特性。

保存解释（仅限用户明确要求时）

只有用户明确要求时才保存。

设置

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

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

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

会话条目字段

在会话文件中写入以下内容：

• code_snippet：用户提供的所选代码。
• explanation：摘要部分。
• alternatives_considered：相关的替代方案；否则留空字符串。
• key_concepts：核心概念数组。
• breakdowns：{ code_excerpt, explanation, pattern? } 对象数组。
• issues：{ severity, description, suggestion } 对象数组。
• improvements：{ description, rationale } 对象数组。

索引条目

• id：格式为 entry-{unix-timestamp}-{random-4-hex-chars}
• decision_type："explanation"
• content_file：会话文件的相对路径，例如 sessions/explain-2026-03-27-001.json

如果代码来自可识别的文件，则添加基于内容定位的引用：

• file — 相对于项目根目录的路径
• anchor — 函数签名、类声明或具有辨识度的代码块
• anchor_hash — anchor 文本的 SHA-256 哈希值的前 8 个十六进制字符（echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8）

如果代码是直接粘贴且来源未知，references 可以为空。

会话结束

设置 timestamp_end，写入简短的 summary，并确认：“已将解释保存为会话 <session_id> 中的条目 <id>。”

数据格式

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

重要说明

• 除非用户要求，否则内容仅为临时内容。 只有在用户明确要求持久保存时，才写入 .decodie/。
• 根据代码复杂度调整分析深度。 五行的实用工具不需要五部分拆解。
• 如实说明不确定之处。 如果代码含义不明确，请说明。