Codebase structure protocol

何时使用

满足以下任一情况时使用：

• 项目已有 .dsp/ 目录（DSP 已搭好）。
• 用户要求搭建 DSP、bootstrap 或映射项目结构。
• 在 DSP 跟踪的项目中新建/修改/删除代码文件，需同步图谱。
• 导航项目结构、理解依赖、定位模块。
• 重构或替换某依赖前做影响分析（谁会被波及）。
• 用户提到 DSP、dsp-cli、.dsp 或"结构映射"。

不该用：仅改了内部实现而未影响实体的用途或依赖时，不要动 .dsp/。DSP 不是给人看的文档，也不是 AST 全量转储；不要为每个局部变量或私有 helper 建实体，只记文件级 Object 与公开/共享实体。

核心模型

• 代码即图：有向图。节点是实体，边是 imports 与 shared(导出)。实体两类——Object（非函数的"东西"：模块/文件/类/配置/资源/外部依赖）和 Function（导出的函数/方法/handler/pipeline）。
• 按 UID 定身份，不按路径：每个实体有稳定 UID——Object 为 obj-<8hex>，Function 为 func-<8hex>。路径是可变属性，UID 在重命名、移动、重排版后不变。文件内实体用源码注释锚点绑定 UID：

  // @dsp func-7f3a9c12
  export function calculateTotal(items) { ... }
  

• 每条连接都有"为什么"：记录 import 时存一句简短 reason，写在被导入实体的 exports/ 反向索引里。无 reason 的依赖图只告诉你"谁导入谁"，reason 才告诉你改它安全吗、谁会坏——DSP 的价值大半在此。
• 全导入覆盖：任何被引用的文件/产物（代码、图片、样式、配置、JSON、wasm…）都要在 .dsp 里有对应 Object。外部依赖记为 kind: external，加入 TOC，但绝不深入 node_modules/site-packages 分析其内部。

存储为纯文本，可 diff、可评审，无需数据库。目录结构：

.dsp/
├── TOC                  # 从根开始的全部实体 UID 有序列表
├── obj-a1b2c3d4/
│   ├── description      # 源路径、kind、用途（1-3 句）
│   ├── imports          # 依赖的 UID（每行一个）
│   ├── shared           # 公开 API / 导出实体的 UID
│   └── exports/         # 反向索引：谁导入了我、为什么
└── func-7f3a9c12/ ...

步骤

前置：依赖独立 Python CLI 脚本 dsp-cli.py（需 Python 3.10+）。若项目缺失，下载：

curl -O https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/skills/data-structure-protocol/scripts/dsp-cli.py

所有命令形如 python dsp-cli.py --root <项目根> <command>。

Bootstrap（首次映射，.dsp/ 为空时）：沿 import 从根入口做 DFS。

1. 识别根入口（package.json 的 main、框架入口、main.py 等）。
2. 记录根文件：create-object，为每个导出 create-function，再 create-shared，对所有依赖 add-import。
3. 取第一个非外部导入，完整记录它，下钻进它的 imports。
4. 无未访问的本地导入时回溯；直到所有可达文件都被记录。
5. 外部依赖：create-object --kind external 并加入 TOC，但不下钻。

改代码时的对应动作（仅在用途或依赖变化时才动 DSP）：

代码变更	DSP 动作
新建文件/模块	create-object + create-function + create-shared + add-import
新增 import	add-import（新依赖先 create-object --kind external）
移除 import	remove-import
新增导出	create-shared（新函数先 create-function）
移除导出	remove-shared
重命名/移动文件	move-entity（UID 不变）
删除文件	remove-entity（级联清理自动完成）
用途变化	update-description
仅内部实现改动	无需更新 DSP

改前必做：用 search / find-by-source / read-toc 找到受影响实体，读它们的 description 与 imports 理解上下文，再动手。

指令

关键命令分组：

• 创建：init、create-object、create-function、create-shared、add-import
• 更新：update-description、update-import-why、move-entity
• 删除：remove-import、remove-shared、remove-entity
• 导航：get-entity、get-children --depth N、get-parents --depth N、get-path、get-recipients、read-toc
• 搜索：search <query>、find-by-source <path>
• 诊断：detect-cycles、get-orphans、get-stats

示例

示例 1：搭建 DSP 并记录一个模块

python dsp-cli.py --root . init
python dsp-cli.py --root . create-object "src/app.ts" "应用主入口"
# 输出: obj-a1b2c3d4
python dsp-cli.py --root . create-function "src/app.ts#start" "启动 HTTP 服务" --owner obj-a1b2c3d4
# 输出: func-7f3a9c12
python dsp-cli.py --root . create-shared obj-a1b2c3d4 func-7f3a9c12
python dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef "HTTP 路由"

示例 2：改动前导航图谱

python dsp-cli.py --root . search "authentication"
python dsp-cli.py --root . get-entity obj-a1b2c3d4
python dsp-cli.py --root . get-children obj-a1b2c3d4 --depth 2
python dsp-cli.py --root . get-recipients obj-a1b2c3d4
python dsp-cli.py --root . get-path obj-a1b2c3d4 func-7f3a9c12

示例 3：替换某库前的影响分析

python dsp-cli.py --root . find-by-source "lodash"
# 输出: obj-11223344
python dsp-cli.py --root . get-recipients obj-11223344
# 列出所有导入 lodash 的模块及"为什么"——据此可系统化替换

注意事项

• 创建文件、新增 import、改公开 API 时立即更新 DSP，别攒着。
• 记 import 时务必写有意义的 why，这是 DSP 价值集中地。
• 第三方库一律 kind: external，不分析其内部。
• description 保持精简（1-3 句讲用途，不讲实现）。
• 把 .dsp/ 的 diff 当代码 diff 评审，保持准确。
• 重命名/移动不要改 UID，用 move-entity。
• 仅内部实现改动不要碰 .dsp/。
• 仅在任务明确落入上述范围时使用；产物不替代环境内验证、测试与专家评审；缺少必要输入、权限、安全边界或成功标准时，停下来澄清。

互见

• 上下文压缩 / 上下文优化：DSP 用定向检索替代"全量加载"，减少压缩需求，agent 只拉取最小"上下文包"。
• 架构设计：DSP 捕获的导入/导出边界即架构边界，可反哺系统设计决策。

---

采编自 sickn33/antigravity-awesome-skills（MIT），原协议出处 k-kolomeitsev/data-structure-protocol。