用途
structural-index 是一个用于 Drupal 项目的结构索引生成与查询技能（Skill）。它解析项目中的声明式配置（如 services.yml、routing.yml、钩子、插件和实体类型），自动生成结构化的索引文档，并支持通过 discover 命令进行查询，帮助开发者理解代码库的“是什么”和“如何连接”。
主要能力
- 生成结构索引：运行 generate-all.sh 脚本，在 docs/semantic/structural/ 目录下生成多个 Markdown 文件，包括：
- services.md：服务 ID、类、注入依赖、模块、标签
- routes.md：路由名称、路径、控制器/表单、访问权限、模块
- hooks.md：钩子实现（过程式和面向对象）
- plugins.md：Block、FieldType、Action、QueueWorker 等插件
- entities.md：内容实体和配置实体类型（含字段列）
- schemas.md：实体模式摘要（每个 bundle 的字段、引用、列表）
- base-fields.md：基础字段注册表（来自 PHP baseFieldDefinitions()）
- permissions.md：权限注册表（来自 *.permissions.yml）
- methods.md：方法索引（Service/Controller/Form 中的公共方法）
- 同时生成 docs/semantic/schemas/*.json（每个 bundle 的 JSON 模式，含字段类型、标签、基数、目标类型/ bundle、允许值）和 *.base-fields.json（每个实体的基础字段模式，含实体元数据、字段类型、设置）
- docs/semantic/DEPENDENCY_GRAPH.md：交叉引用依赖分析
- docs/semantic/FEATURE_MAP.md：功能概览及结构计数
- 检查索引是否过时：运行 check-staleness.sh 脚本，根据文件修改时间报告哪些结构文件需要重新生成。
- 查询结构数据：通过 discover 技能查询已生成的索引，支持以下前缀：
- service: 或 svc: 查找服务
- route: 或 path: 按路径查找路由
- hook: 查找钩子实现
- plugin: 查找插件（如 Block）
- entity: 查找实体类型
- schema: 显示实体 bundle 的字段模式
- perm: 查找权限
- method: 查找相关方法
- deps: 进行影响范围/依赖分析
- impact: 查看哪些模块依赖指定模块
- 输出格式：各 Markdown 文件以表格形式呈现，便于阅读和检索；JSON 模式文件按需加载。
使用方式
- 生成索引：在项目目录下运行
$SKILL_DIR/scripts/generate-all.sh [project-dir]。 - 检查过时：运行
$SKILL_DIR/scripts/check-staleness.sh [project-dir]。 - 查询：使用 discover 命令，例如
discover service:entity_type.manager、discover hook:node_presave、discover deps:AUTH等。
适用场景
- 需要快速了解 Drupal 项目的服务依赖、路由、钩子和插件结构。
- 进行变更影响分析（如修改某个服务或模块的影响范围）。
- 作为语义文档（Layer 3）和原始代码库（Layer 1）之间的中间层（Layer 2），辅助架构理解和文档生成。
- 与 discover 技能、prime.sh 和自动化代理集成，提供结构上下文。
限制
- 仅提取 YAML 配置中的可配置字段；基础字段在单独的 *.base-fields.json 文件中。
- 配置目录自动从常见位置检测（config/sync、config/default、config/staging、../config/sync），非标准路径需符号链接或调整。
- 来自父类 baseFieldDefinitions() 的字段（id、uuid、langcode）是隐式的，未枚举。
- 没有 baseFieldDefinitions() 的配置实体会被跳过。
- 来自 permission_callbacks 的动态权限无法检测。
- 需要 Drupal 项目具有标准目录结构，且存在 docs/semantic/ 目录作为输出位置。
- 无外部依赖（仅 grep/sed/awk），可选 yq 以提升 YAML 解析精度。