Codespaces — 信念图架构发现

Codespaces — 信念图架构发现 是做什么的？

在阅读源文件之前，先查询 .belief_map.sexp 来发现模块、边界和依赖关系。切勿盲目阅读代码——优先查询图。

脚本

本技能包含 Python 脚本。请从技能的基础目录下运行它们：

• scripts/belief_search.py —— 查询信念图
• scripts/build_belief_map.py —— 从源码生成信念图
• scripts/build_infra_topology.py —— 提取 Kustomize、Helm 和 Terraform 拓扑事实
• scripts/git_descendants.py —— 查找从 HEAD（或给定引用）出发的所有后代提交

切勿使用项目本地的脚本副本——它们可能已过时，且输出 JSON 而非 S-表达式。

前提

找到信念图。如果不存在，则构建它：

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# 构建：pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # 增量构建 ~5s
python3 scripts/build_belief_map.py --full   # 全量重建 ~30s

强制性工作流：先查询后读码

对于非平凡的代码工作，在执行 rg、find、sed、cat、nl、打开目录或阅读源文件之前，请先运行一次信念图查询。该技能只有在作为第一步定界步骤时才有帮助，而不是在源代码已被检查之后用作确认。

当任务包含明确关键字时的快速首次通过：

python3 scripts/belief_search.py quick "keyword"

quick 用于搜索第一个匹配的模块并立即运行 analyze。用它一步获取边界文件、依赖关系、反向依赖关系、架构层和违例信息。如果 quick 返回了错误的模块或没有匹配项，请使用下面明确的 search -> analyze 流程。

第 1 步 —— 查找模块 ID：

python3 scripts/belief_search.py search "keyword"
python3 scripts/belief_search.py entity EntityName

使用 search 或 entity 来定位模块 ID。模块 ID 是完整的相对路径，如 pki-service/src/modules/ca/ca.service，而不是像 ps34 那样的短代码。信念图内部可能包含短路径映射 ID，但它们会被自动解析——始终传递人类可读的路径风格字符串。切勿猜测或编造模块 ID——始终先用 search 确认。

第 2 步 —— 分析模块（立即执行此操作，非可选）：

python3 scripts/belief_search.py analyze <module-id>

analyze 是主要命令。它返回完整的上下文：边界文件、依赖关系、反向依赖关系、架构层和违例信息。在阅读任何源码之前始终运行它。

第 3 步 —— 仅读取 analyze 输出中列出的边界文件。

第 4 步 —— 不要读取整个目录。 如果边界显示 2-3 个相关文件，只读取这些文件。忽略目录中的其他所有内容。

命令参考

命令	用途	示例
search "<pattern>"	在图上进行正则表达式搜索（查找模块 ID）	search "operative.*service"
analyze <id>	完整模块分析（主要命令）	analyze drive/modules/drive/drive_schema
quick <keyword>	搜索并分析第一个匹配项（快捷方式）	quick operatives
boundary <id>	变更需要读取的文件	boundary operatives.service
boundary <id> --files-only	仅文件路径（简洁模式）	boundary operatives.service --files-only
entity <Name>	查找定义+引用	entity DrivePath
deps <id> [depth]	输出依赖树	deps operatives.service 3
rdeps <id> [depth]	影响半径（谁依赖于此）	rdeps drive_schema 2
flow <id> <fn>	跟踪调用/数据流	flow drive_api fetchFiles
module <id>	含边的单个模块	module operatives.controller
`boundaries [id	all]`	检查架构违例
`invariants [id	all]`	检查命名约定违例
layers	按层显示所有模块	layers
find_function <name>	查找函数/方法定义	find_function createOrder
find_type <name>	查找类型/类/接口/枚举定义	find_type DriveDbCommitResponse
find_callchain <src> <tgt> [depth]	查找函数间的调用路径	find_callchain createOrder processPayment
find_callers <fn> [depth]	谁调用了此函数	find_callers handleRequest 3
find_calls <fn> [depth]	此函数调用了什么	find_calls createOrder 2
grep_functions <pattern>	在源码中搜索函数体	grep_functions "validate.*input"
diff_functions [ref]	Git diff 中发生变更的函数	diff_functions HEAD~3
query '<sexp>'	可组合的 Scheme 查询	query '(count (boundary "X"))'
repl	交互式 Scheme REPL	repl

快速参考：rg 查询

当需要快速、有针对性的查找而不调用 Python 脚本时，可以直接使用 rg 查询信念图。配套的构建器写入 .belief_map.sexp；如果仓库仍在使用旧版 belief_map.sexp，请在下列命令中替换该文件名：

# 关于一个模块的所有事实
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# 谁导入了一个模块
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# 一个模块导入了什么
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# 对一个实体的所有引用
rg 'DriveDbCommitResponse' .belief_map.sexp

# 仓库中所有的类
rg '^\(cls drive/' .belief_map.sexp

# 数据流边
rg 'data-flow' .belief_map.sexp

这些单行命令对于快速检查很有用。如需结构化输出和完整分析，请使用 Python 脚本的命令。

输出符号

所有输出都是 S-表达式事实，每行一个。完整格式请参见 references/sexp-notation.md。

关键模式：

(boundary <mod> :lang py :file <path> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Name> <line> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
(result <module-or-path>)
(result-count 42)

:lang 值：py = Python（snake_case），ts = TypeScript（camelCase），tsx = TSX（PascalCase）。

Scheme 查询语言

组合查询以实现复杂分析。完整参考请参见 references/scheme-queries.md。

基本操作：

(boundary "id")                ; 目标 + 依赖 + 反向依赖（变更边界）
(entity "Name")                ; 定义实体的模块
(deps "id" depth)              ; 输出依赖
(rdeps "id" depth)             ; 反向依赖
(find-function "name")         ; 包含匹配函数定义的模块
(find-type "name")             ; 包含匹配类型定义的模块
(find-callers "fn" depth)      ; 调用某函数的模块
(find-calls "fn" depth)        ; 某函数调用的模块
(intersect A B)                ; 集合交集
(filter SET "pattern")         ; 正则表达式过滤
(files SET)                    ; 解析为文件路径
(count SET)                    ; 统计成员数
(violations)                   ; 有边界违例的模块
(layer "id")                   ; 一个模块的架构层

分析计划模式

在修改代码之前，通过查询制定计划：

; 1. 范围
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. 架构约束
(violations "operatives.service")
(layer "operatives.service")

; 3. 跨语言边界
(filter (refs-to "DrivePath") "app-service")

; 4. 缩小到可操作的文件
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. 变更后验证
(violations "operatives.service")

触发示例

在阅读源码之前，对以下情况使用本技能：

• 根因调查，涉及服务、API、任务、事件、UI 流程或失败行为。
• 跨服务或跨模块问题，包括“X 如何调用 Y？”和“此数据存储在哪里？”
• 当答案取决于代码行为时需要澄清的问题。
• 架构评审、影响分析、公开契约变更或影响半径检查。
• 对非平凡的暂存变更进行审核，当依赖方向或模块所有权很重要时。

不要强制将其用于仅提交的任务、git 日志摘要、手动演示/服务器运行、纯浏览器测试或会话日志分析。

错误恢复

如果命令返回 (error no-match ...)：

1. 不要使用相同的 ID 重试或猜测另一个 ID
2. 使用更宽的关键字运行 search 以找到正确的模块 ID
3. 如果存在 :suggestions 字段 —— 它会列出相似的模块 ID

# 错误：猜测 ID
python3 scripts/belief_search.py analyze ps34        # 失败：ps34 是短路径映射 ID
python3 scripts/belief_search.py analyze ca.service  # 失败：路径不完整

# 正确：先搜索，然后使用结果中的完整路径
python3 scripts/belief_search.py search "ca.*service"
# 输出显示：pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

反模式

• 猜测模块 ID。 模块 ID 是完整的相对路径（例如 pki-service/src/modules/ca/ca.service）。像 ps34 这样的短代码是内部路径映射 ID，不能直接使用。务必先 search。
• 只构建但不查询。 构建了信念图但从不运行 search、analyze 或 boundary，这毫无价值。
• 先读源码再查询。 首次源码读取应该是来自 analyze 输出的 boundary-file 行。
• 将 .belief_map.sexp 作为一个完整的文件来阅读。 使用 search、analyze 或 rg 来查询特定事实。
• 对跨模块任务跳过信念图。 在阅读源文件之前，始终查询图以了解边界。
• 读取目录中的所有文件。 当边界显示 2-3 个文件时，只读取这些文件。
• 使用项目本地脚本。 始终使用本技能打包的脚本。项目副本可能输出 JSON 而非 S-表达式。

重建图

python3 scripts/build_belief_map.py          # 增量构建（~5s）
python3 scripts/build_belief_map.py --full   # 全量重建（~30s）
python3 scripts/build_belief_map.py ./drive  # 单个子仓库
python3 scripts/build_belief_map.py --lsp    # 带 LSP 调用层次结构（~1-5分钟）

在结构性变更（添加/删除文件、更改导入、添加类）后重建。

基础设施拓扑

从 Kustomize、Helm 和 Terraform 文件中提取服务拓扑。此脚本需要 PyYAML（pip3 install pyyaml）。

python3 scripts/build_infra_topology.py                    # 自动检测所有 IaC
python3 scripts/build_infra_topology.py --kustomize .      # 仅 kustomize
python3 scripts/build_infra_topology.py --helm ./charts    # 仅 helm 图表
python3 scripts/build_infra_topology.py --terraform ./infra # 仅 terraform
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # 合并到图中

输出 infra-node、k8s-depends、k8s-service、helm-depends、tf-depends 和 infra-maps 边。使用以下命令查询：

rg 'infra-node' .belief_map.sexp                  # 所有服务
rg 'k8s-depends' .belief_map.sexp                 # 服务依赖
rg 'infra-node.*:component database' .belief_map.sexp  # 所有数据库
rg 'infra-maps.*app-service' .belief_map.sexp     # 基础设施 -> 源代码映射