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

xray-method

编程与开发

查看项目

更新于 10-15 12:56

技能介绍

用途

X-ray method 是一个代码库 X-Ray 分析技能，目标是把机械式结构提取与语义理解结合起来，产出全面的代码库文档。与简单的 AST 解析不同，它试图捕捉四个层面的信息：代码做什么（结构、函数、类）、为什么存在（业务目的、设计决策）、如何集成（依赖、契约、流程）以及变更的后果（副作用、失败模式）。

主要能力

机械分析（脚本）：提取代码结构（类、函数、导入）；映射内部与外部依赖；在代码库中查找符号使用；按关键性对文件分类。

语义分析（Claude AI）：识别架构与设计模式；发现红旗与反模式；追踪数据流与控制流；记录契约与不变量；评估质量与可维护性。

文档诊断：检查文档漂移与失效链接（Phase 6）；报告过期索引与引用；分析注释质量并提出修改建议（分析不会自动应用修改）。

语言支持

  • Python（.py、.pyi）：使用标准库 ast，始终可用；注释为 # 行注释与 docstring。
  • Java（.java）：优先 tree-sitter，否则正则；注释为 //、/* /、Javadoc /* */。
  • JavaScript（.js、.mjs、.cjs、.jsx）：优先 tree-sitter，否则正则；注释为 //、/* /、JSDoc /* */。
  • TypeScript（.ts、.tsx、.mts、.cts）：优先 tree-sitter，否则正则，额外支持接口、枚举、类型别名；注释为 //、/* /、JSDoc /* */。
  • SQL（.sql、.ddl、.dml）：正则 DDL 提取（表、视图、索引、序列、类型、函数、过程、触发器）；注释为 --、/* */。
  • PL/SQL（Oracle，.pks、.pkb、.plsql、.pls、.pck、.prc、.fnc、.trg）：正则提取（包、包体、类型体、游标、异常、%TYPE/%ROWTYPE 引用）；注释为 --、/* */。
  • Rust（.rs）：优先 tree-sitter，否则正则；支持 structs、enums、traits、impls（以 Trait for Type 命名）、mods、unions、类型别名；注释为 //、/* /、rustdoc /// / //! / /* / / /! */。
  • CSS、SCSS、LESS（.css、.scss、.less）：使用标准库 tokenizer，从不使用 tree-sitter；每条应用的规则对应一个符号，以其在所属 at-rules 内的扁平化选择器命名；顶层 at-rules 与 Sass/LESS 变量；mixins 与 Sass 函数；@import / @use / @forward；Tailwind @apply 布局工具按其内联的声明读取；注释为 /* */，纯 CSS 之外可用 //。

.sql 文件会通过检查内容中的 Oracle 特有标记（CREATE OR REPLACE PACKAGE、DBMS_OUTPUT、%TYPE、%ROWTYPE、UTL_FILE、PRAGMA AUTONOMOUS 等）与 PL/SQL 区分。PostgreSQL plpgsql 会被正确归类为 SQL。

前置条件

脚本要求 Python >= 3.10，仅用标准库即可开箱运行。Tree-sitter 为可选，可提升 Java / JavaScript / TypeScript / Rust 的解析准确度：

# Optional: install for higher-fidelity parsing
pip install -r "${CLAUDE_PLUGIN_ROOT}/skills/xray-method/scripts/requirements.txt"
# or
uv pip install -r "${CLAUDE_PLUGIN_ROOT}/skills/xray-method/scripts/requirements.txt"

安装 tree-sitter 后的变化：Java 可正确解析嵌套类、泛型类型参数、注解、多行声明；JavaScript / TypeScript 可正确解析对象/类属性中的箭头函数、装饰器、模板字面量、JSX 元素；Rust 可正确解析生命周期、泛型约束（where 子句）、带 trait 约束的 impl 块、属性宏。Python / SQL / PL-SQL / CSS 无变化。当前使用的解析器会在 ParseResult.notes 与 CLI 输出中报告：parser=stdlib-ast、parser=tree-sitter、parser=regex-fallback 或 parser=stylesheet。

使用方式

该技能是方法本身，由命令来应用。/codebase-xray:analyze 在单一上下文中内联运行所有阶段；/codebase-xray:team-analyze 将目标分区并分派各阶段到隔离的 worker，worker 直接读取本技能。两者都在 .codebase-xray/ 下自动管理状态。技能自身名称为 codebase-xray:xray-method。

并发运行模型：多个分析可同时运行，每次分析是隔离的运行。.codebase-xray/ 下包含 runs.json 注册表、runs/<run-id>/ 每次运行的目录（state.json、snapshot/manifest.json、changes.json、changes.md、knowledge/、01-structure.md 至 07-final-report.md、团队模式下的 partitions/ 与 08-interconnect-map.md），以及根目录下最新发布运行的镜像。规则包括：运行身份（run-id = 目标路径 slug + -YYYYMMDD-HHMMSS，或 --run-name 值）、隔离（进行中只写入自己的运行目录）、注册表（runs.json 记录 active 与 latest_completed）、发布步骤（成功后复制 01..0N.md 与 state.json 到根目录）、恢复（读取 runs.json 提供恢复或归档）、镜像仅供最新状态消费者使用、谱系（每次运行写 snapshot/manifest.json，增量运行记录 parent_run）。

增量更新：同一目标的第二次 X-ray 只有在无人询问变更时才从零重建。snapshot.py 在模型之外运行。快照记录每个文件的大小、mtime 与内容哈希，每个符号的行范围与正文哈希，以及 git commit 作为元数据。变更集（snapshot.py diff）将清单与当前工作树比较，分类文件与符号，解析一跳影响范围，扫描父级阶段文件中引用被触及内容的每条结论，并建议增量、全量或不做。carry 复制父级阶段文件（最终报告除外，始终重新生成），重编号存活的引用，标记受影响结论。check 门禁在任何标记残留或有新增符号未记录时失败，增量运行通过后才发布。它刻意不使用 git 范围作为事实来源，也不将影响范围扩大到一跳之外。

核心原则：证据锚定输出

该技能产出的每个文件都是关于代码的一组结论，每条锚定到代码并带有状态。强制规则（违反即失败）：绝不未读实际源码就记录任何内容；绝不假设任何现有文档、注释或 docstring 准确；绝不基于记忆、推断或“应该是什么”写文档；始终仅通过阅读与追踪实际代码得出技术事实；始终为阶段文件中每条技术结论标注 file:line，并在存在时加上限定符号（file.py::Class.method）；始终对照实际定义验证状态机、枚举、常量；将所有既有文档视为需要验证的未验证结论；为每条结论标记状态：verified（代码中强制，注明位置）、documented（文档声明，注明位置）、unverified（被依赖但无强制或文档）、disputed（两种推导不一致，注明两者）。[UNVERIFIED - REQUIRES CODE CHECK] 是散文中的内联形式。维护文档的验证标记使用限定符号名而非行号（[VERIFIED: file.py::Class.method]）。

文档扮演两种角色，只有一种受上述约束：作为证据，文档是需要验证的未验证结论；作为发现线索，文档是一等输入，必须尽早收集。Phase 0 收集线索，Phase 6 将文档作为证据审计。

Phase 0：项目知识发现

在每个深度（包括 --depth=lite）都运行，且最先在编排上下文中运行。Phase 1 到 7 保持编号不变。Phase 0 是前导，不是可选分析阶段，在每次调用前运行（包括 --phase 5 与 --docs-only），不改变 1 到 7 的编号语义。--phase 0 单独运行前导。该阶段负责发现仓库如何自我记录，不评估文档是否准确（那是 Phase 6）。读取仓库根目录与目标祖先目录中的 CLAUDE.md、AGENTS.md 及等效项目指令文件，记录导航指令。定位项目实际使用的规范索引，至少 glob：/SEARCH_INDEX.md、/INDEX.md、docs/README.md、README.md、/BY_DOMAIN.md、/adr/、/decisions/、/architecture/、/domains/**、.codebase-map/INDEX.md，记录存在的内容。

适用场景

分析不熟悉的代码库；生成解释 WHY 而非仅 WHAT 的文档；识别架构模式与反模式；在代码评审前建立技术事实；新项目上手。

限制

资料未提供收费、价格、平台与效果信息。脚本要求 Python >= 3.10；tree-sitter 为可选依赖。增量更新刻意不使用 git 范围作为事实来源，也不将影响范围扩大到一跳之外。分析不会自动应用注释修改建议。