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 而不是 sexp。

前置条件

定位信念图。如果不存在，则构建它：

ls .belief_map.sexp belief_map.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absolute/path/to/project && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --full

Python 索引无需外部解析器依赖项。对于检测到的其他语言，如果解析器缺失或版本不正确，首次构建会在发布前失败，并打印需要运行的确切语言专属命令，例如：

python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"

只安装构建器指定的需求文件，然后重新运行。requirements.txt 专用于基础设施拓扑依赖项。

强制工作流：先查询，再看代码

对于非简单的代码任务，先查询信念图，再运行 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 会自动解析——始终传入人类可读的类路径字符串。切勿猜测或编造模块 ID——务必先用 search 确认。

步骤 2——分析模块（立即执行，不可跳过）：

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

analyze 是主要命令。它会返回完整上下文：边界文件、依赖项、反向依赖项、架构层级和违规项。阅读任何源代码前，务必先运行它。

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

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

命令参考

命令	用途	示例
search "<pattern>"	在图谱中安全地搜索字面值或 .*	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]	检查架构违规	boundaries all
invariants [id|all]	检查命名约定违规	invariants 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_functions HEAD~3
query '<sexp>'	可组合的 Scheme 查询	query '(count (boundary "X"))'
repl	交互式 Scheme REPL	repl

快速参考：rg 查询

如果需要快速、定向地查找内容，而不调用 Python 脚本，可以直接用 rg 查询信念映射。随附的构建器会写入 .belief_map.sexp；如果仓库仍使用旧版 belief_map.sexp，请在下方命令中替换为该文件名：

# All facts about a module
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Who imports a module
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# What does a module import
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# All references to an entity
rg 'DriveDbCommitResponse' .belief_map.sexp

# All classes in a repo
rg '^\(cls drive/' .belief_map.sexp

# Data flow edges
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），rs = Rust（snake_case），cs = C#， java = Java，go = Go，rb = Ruby/Rails。

Scheme 查询语言

组合查询以进行复杂分析。完整参考请参阅 references/scheme-queries.md。

基础用法：

(boundary "id")                ; target + deps + rdeps (change boundary)
(entity "Name")                ; modules defining entity
(deps "id" depth)              ; outgoing dependencies
(rdeps "id" depth)             ; reverse dependencies
(find-function "name")         ; modules with matching function defs
(find-type "name")             ; modules with matching type defs
(find-callers "fn" depth)      ; modules calling a function
(find-calls "fn" depth)        ; modules a function calls
(intersect A B)                ; set intersection
(filter SET "pattern")         ; safe literal/.* filter
(files SET)                    ; resolve to file paths
(count SET)                    ; count members
(violations)                   ; modules with boundary violations
(layer "id")                   ; architecture layer of a module

分析计划模式

修改代码前，请根据查询制定计划：

; 1. Scope
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Architecture constraints
(violations "operatives.service")
(layer "operatives.service")

; 3. Cross-language boundaries
(filter (refs-to "DrivePath") "app-service")

; 4. Narrow to actionable files
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. After changes: verify
(violations "operatives.service")

触发示例

在阅读源代码前，以下情况请使用此技能：

• 涉及服务、API、任务、事件、UI 流程或故障行为的根因调查。
• 跨服务或跨模块问题，包括“X 如何调用 Y？”和“此内容存储在哪里？”
• 答案取决于代码行为的 Redmine 澄清。
• 架构审查、影响分析、公共契约变更或影响范围检查。
• 依赖方向或模块归属很重要的非简单暂存变更审查。

提交专属任务、git 日志摘要、手动演示／服务运行、纯浏览器测试或会话日志分析时，不要强行使用此技能。

错误恢复

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

1. 不要使用相同的 ID 重试，也不要猜测其他 ID
2. 使用更宽泛的关键词运行 search，以查找正确的模块 ID
3. 如果存在 :suggestions 字段，请使用它；该字段会列出相似的模块 ID

# Wrong: guessing IDs
python3 scripts/belief_search.py analyze ps34        # fails: ps34 is a short path-map ID
python3 scripts/belief_search.py analyze ca.service  # fails: incomplete path

# Right: search first, then use the full path from results
python3 scripts/belief_search.py search "ca.*service"
# Output shows: 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，而不是 sexp。

重建图

python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --full
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --lsp
python3 "$SKILL_ROOT/scripts/build_belief_map.py" \
  --root "$TARGET_ROOT" --output "$TARGET_ROOT/custom-map.sexp"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" \
  --root "$TARGET_ROOT" --exclude-dir review-bundles

对于受版本控制的快照、生成的测试夹具或其他形状类似源代码但不属于当前产品的目录，请重复使用 --exclude-dir NAME 选项。每个值都是目录基本名称，适用于任意深度。更改排除项会使增量缓存失效，因此排除的文件不会从先前的构建中泄漏出来。

Git 工作树中的目标也会使用 Git 仓库的忽略规则。同一套解析后的策略会筛选源文件、TypeScript 别名和包、Go 与 Rust 包清单、Ruby 项目配置，以及 LSP 项目发现。调用 Git 时会禁用索引检查，因此与 .gitignore 匹配的受版本控制快照路径仍会从信念图中排除。

结构发生变化后（添加/删除文件、更改导入、添加类），请重建。搜索模式支持字面值、.*、边界锚点 ^/$ 和反斜杠转义。其他正则表达式运算符不受支持。

TypeScript AST 契约涵盖 TS/TSX 导入和重新导出、字面量 import()/require()、import = require()、字面量模板导入、生成的 .js/.jsx 说明符、项目范围内的路径别名，以及约定俗成的精确自导入。但不保证支持继承的 tsconfig 别名、仅由 baseUrl 决定的解析、包的 source/exports，或自包导出子路径。

C# 索引会追踪命名空间和引用的本地类型；Java 索引会追踪包、显式导入和引用的通配符类型。未使用的命名空间或通配符导入不会产生推测边。Go 索引会将本地模块导入解析为构成被导入包的源文件。标准 .NET bin/obj 输出和 Go vendor 依赖会被排除。

Ruby 索引会发现 .rb 和 .rake 文件，并解析显式 require、本地常量、Rails 应用根目录、静态配置的自动加载根目录、项目缩写词、concerns、关联、回调、任务、邮件程序和 spec 引用。它绝不会启动 Rails。重新打开的常量或其他存在歧义的常量，以及多态关联，会保持未链接状态，而不会生成推测边。Rails 关系标记会在生成的映射中保留为 :association、:concern、:callback、:job、:mailer 或 :spec。

Pascal 索引会发现 .pas、.pp、.lpr 和 .inc 文件。它会提取单元、程序、uses/contains/requires 子句、包含指令、类、记录、接口、继承、方法和例程。单元名称和路径会以不区分大小写的方式解析；显式的 UnitName in 'path.pas' 路径优先，其次是在导入文件所在目录中唯一匹配的单元。其他存在歧义的单元名称会保持未链接状态。条件编译分支会以保守方式建立索引。Pascal 目前尚无 LSP 增强功能。常见 Lazarus backup/ 目录中的 Pascal 文件会被排除；目录名称相同的目录中其他受支持的语言仍可建立索引。

基础设施拓扑

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

python3 scripts/build_infra_topology.py                    # auto-detect all IaC
python3 scripts/build_infra_topology.py --kustomize .      # kustomize only
python3 scripts/build_infra_topology.py --helm ./charts    # helm charts only
python3 scripts/build_infra_topology.py --terraform ./infra # terraform only
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # merge into graph

会生成 infra-node、k8s-depends、k8s-service、helm-depends、tf-depends 和 infra-maps 边。查询方式：

rg 'infra-node' .belief_map.sexp                  # all services
rg 'k8s-depends' .belief_map.sexp                 # service dependencies
rg 'infra-node.*:component database' .belief_map.sexp  # all databases
rg 'infra-maps.*app-service' .belief_map.sexp     # infra -> source code mapping