codebase-structure-protocollisted

## 何时使用 满足以下任一情况时使用： - 项目已有 `.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： ```js // @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+）。若项目缺失，下载： ```bash curl -O https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/skills/data-structure-protocol/scripts/dsp-cli.py ``` 所有命令形如