SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场decodie-analyze

decodie-analyze

编程与开发

查看项目

更新于 10-16 07:46

技能介绍

用途

Decodie — Analyze Mode 是一个代码分析伴侣，用于读取已有源代码，回溯性地识别值得记录的代码模式、设计决策、约定和概念，并生成结构化的学习条目。与实时记录决策的 observe 模式不同，本模式针对已经存在的代码，通过上下文推断其背后的理由。

本模式对源代码是只读的：只读取源代码，仅向 .decodie/ 目录写入内容。生成的条目由 VSCode 扩展、Web UI 和 GitHub 集成消费。

主要能力

  • 目标解析：提取目标路径，未提供时使用当前工作目录；支持 exhaustive（穷尽）模式，默认 selective（选择性）模式；校验目标存在且为文件或目录，并判断目标类型。
  • 初始化设置：若项目根目录不存在 .decodie/ 则创建，包括 index.json、config.json、sessions/ 目录和 rules/ 目录。
  • 规则加载：读取 ~/.decodie/rules/.md（全局）和 .decodie/rules/.md（项目），将其内容作为控制文档输出的附加指令（语气、语言、详细程度、格式、受众）。项目规则在冲突时覆盖全局规则；无规则时使用默认值。
  • 重复检测：加载索引摘要，运行 bash scripts/summarize-index.sh "$(pwd)"，不可用时直接读取 .decodie/index.json 汇总已有条目、主题和活跃标题。
  • 会话 ID 确定：在 .decodie/sessions/ 中查找当天匹配 analyze-YYYY-MM-DD-NNN 的最大 NNN 并递增。
  • 文件发现：目标为目录时递归列出文件，过滤二进制文件、依赖目录（node_modules/、vendor/、.git/）、构建输出（dist/、build/）、工具目录（.ddev/、.decodie/）、锁文件、压缩文件（.min.js、.min.css）、生成文件（source map、自动生成代码），按目录结构排序并报告数量。单文件目标跳过发现步骤。
  • 源代码注解：支持在注释中放置 @decodie- 前缀标记控制分析，包括 @decodie-include:file/class/function/start-end 和 @decodie-ignore:file/class/function/start-end。识别所有常见注释形式（//、#、/* */、<!-- -->、-- 等）。优先级：作用域重叠时 ignore 优先于 include；较窄作用域不能覆盖较宽的 ignore；:file 为最宽作用域且不可被覆盖。
  • 分析过程：逐文件完整读取，扫描注解，若发现 @decodie-ignore:file 则跳过该文件并构建注解区域映射；跨架构、语言惯用法、设计决策、错误处理、API 设计、性能、安全、配置、测试等维度分析模式；应用注解与模式规则。选择性模式（默认）每文件记录 3-5 个最重要模式，优先考虑新人最需要的内容、非显而易见的“为什么”决策、可复用模式、非平凡的框架用法；穷尽模式记录每个有意义的模式，无每文件限制，但仍跳过琐碎观察。
  • 条目写入：生成每个条目后追加到会话文件并更新 index.json，报告进度。
  • 会话收尾：设置 timestamp_end，写入包含目标路径、模式、分析文件数、生成条目数、主要主题的摘要，并报告完成情况。

使用方式

  • 激活时解析目标与模式：提取目标路径（默认当前工作目录），检查是否为穷尽模式（默认选择性模式），校验目标，判断目标类型。
  • 完成初始化设置、规则加载、索引摘要加载、会话 ID 确定。
  • 目录目标执行文件发现，单文件目标直接进入分析。
  • 逐文件分析并写入条目，最后收尾会话。

条目格式与元数据

  • 条目 ID 格式：entry-{unix-timestamp}-{random-4-hex-chars}。
  • 基于内容的锚定：通过稳定标识符引用源代码，绝不使用行号，包括 file（相对项目根的路径）、anchor（函数签名、类声明或独特代码块）、anchor_hash（锚文本 SHA-256 的前 8 位十六进制字符，计算方式：echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8）。
  • index.json 中每个索引条目包含：id、title、experience_level、topics、decision_type、session_id、timestamp、lifecycle、references、external_docs、cross_references、content_file、superseded_by。
  • experience_level：foundational | intermediate | advanced | ecosystem。
  • decision_type：explanation | rationale | pattern | warning | convention。
  • lifecycle：active（新条目）| archived | superseded。
  • content_file：会话文件相对路径，如 sessions/analyze-2026-03-27-001.json。
  • topics：小写 kebab-case 标签，合适时复用索引中已有标签。
  • index.json 条目按时间戳排序，最新在前。
  • 会话条目内容包含：code_snippet（说明概念的聚焦摘录）、explanation（强调“为什么”而非仅“是什么”的清晰解释）、alternatives_considered（其他方法与权衡）、key_concepts（核心要点数组）。

适用场景

  • 需要为已有代码库补充结构化学习文档的团队或个人。
  • 希望回溯性记录代码模式、设计决策与约定的项目。
  • 配合 VSCode 扩展、Web UI 和 GitHub 集成消费生成条目的工作流。

限制与注意事项

  • 对源代码只读，仅写入 .decodie/ 目录。
  • 由于分析的是已有代码而非编写代码，alternatives_considered 应表述为“常见替代方案”而非“曾被考虑的替代方案”，理由需从代码注释、命名约定、结构和最佳实践中推断。
  • 需诚实说明理由是推断而非已知。
  • 批量操作，完成一个文件后再处理下一个。
  • 语言无关，适配项目所用的任何语言和框架。
  • 数据自包含，.decodie/ 目录可删除而不影响项目。
  • 每个条目一个概念，多个概念拆分为多个条目并建立交叉引用。
  • 保持索引轻量，完整内容放在会话文件中，索引仅保存元数据。
  • 重复检测：创建条目前检查索引中标题相似或 topics + decision_type 组合相同的条目；近似重复时，若上下文相同则跳过，若有意义不同则创建并建立交叉引用。
  • 外部文档：当条目涉及知名 API 时，在 external_docs 数组中包含相关外部文档链接，并给出了各生态的 URL 模式（PHP、JavaScript、Python、React、Drupal、Laravel、Django、Node.js、TypeScript）。