📦 Data Structure Protocol — 代码图谱记忆

# 数据结构协议（DSP） DSP 在 .dsp/ 目录中构建项目实体的依赖图。每个实体（模块、函数、外部依赖）获得一个 UID、描述、导入列表和导出索引。该图回答：存在什么、为什么存在、依赖什么、被谁使用。 DSP 不是给人类看的文档，也不是 AST 转储。 它捕获的是 _意义_（目的）、_边界_（导入/导出）和 _连接原因_（why）。 ## Agent 提示 在 DSP 跟踪的项目中工作时，请嵌入以下上下文： > 本项目使用 DSP（数据结构协议）。 > .dsp/ 目录是本项目的实体图：模块、函数、依赖、公共 API。它是你对代码结构的长期记忆。 > > 核心规则： > > 1. 修改代码前 —— 通过 dsp-cli search、find-by-source 或 read-toc 找到受影响的实体。阅读它们的 description 和 imports 以理解上下文。 > 2. 创建文件/模块时 —— 调用 dsp-cli create-object。为每个导出函数调用 create-function（带 --owner）。通过 create-shared 注册导出。 > 3. 添加导入时 —— 调用 dsp-cli add-import 并附简短 why。对于外部依赖 —— 若实体尚不存在，先 create-object --kind external。 > 4. 移除导入 / 导出 / 文件时 —— 分别调用 remove-import、remove-shared、remove-entity。级联清理自动完成。 > 5. 重命名/移动文件时 —— 调用 move-entity。UID 不变。 > 6. 仅内部实现变更且不影响目的或依赖时 —— 不要碰 DSP。 > 7. 引导 —— 若 .dsp/ 为空，从根入口点通过 DFS 遍历导入，记录每个文件。 > > 关键命令： > `` > dsp-cli init > dsp-cli create-object [--kind external] [--toc ROOT_UID] > dsp-cli create-function [--owner UID] [--toc ROOT_UID] > dsp-cli create-shared [ ...] > dsp-cli add-import [--exporter UID] > dsp-cli remove-import [--exporter UID] > dsp-cli remove-shared > dsp-cli remove-entity > dsp-cli move-entity > dsp-cli update-description [--source S] [--purpose P] [--kind K] > dsp-cli get-entity > dsp-cli get-children [--depth N] > dsp-cli get-parents [--depth N] > dsp-cli search > dsp-cli find-by-source > dsp-cli read-toc [--toc ROOT_UID] > dsp-cli get-stats > ` ## 使用 CLI 脚本位于本 skill 目录下的 scripts/dsp-cli.py。 ` python /scripts/dsp-cli.py [--root ] [args] ` --root 默认为当前工作目录。所有参数中的路径均为仓库相对路径。 ## 核心概念 - 代码 = 图。 节点是 Object 和 Function。边是 imports 和 shared/exports。 - 通过 UID 而非文件路径标识身份。 路径是属性；重命名/移动不改变 UID。 - “Shared” 会创建实体。 若某物变为公共（导出），它会获得自己的 UID。 - Import 同时记录“来自哪里”和“什么”。 一次代码导入可能在 DSP 中创建两条链接：到模块和到具体共享实体。 - 全覆盖导入。 每个被导入的文件/资产都必须是 .dsp 中的 Object —— 代码、图片、样式、配置，一切。 - why 位于被导入实体的 exports/ 目录中（反向索引）。 - 从根开始。 每个根入口点有自己的 TOC 文件。 - 外部依赖 —— 仅记录。 kind: external，不深入 node_modules/site-packages 等。但 exports index 有效 —— 显示谁导入了它。 ## UID 格式 - Objects: obj-<8 位 hex>（例如 obj-a1b2c3d4） - Functions: func-<8 位 hex>（例如 func-7f3a9c12） 源代码中的 UID 标记 —— 在声明前用注释 @dsp ： `js // @dsp func-7f3a9c12 export function calculateTotal(items) { ... } ` `python # @dsp obj-e5f6g7h8 class UserService: ` ## 工作流 ### 设置 DSP 1. 运行 dsp-cli init 创建 .dsp/ 目录。 2. 识别根入口点 —— package.json main、框架入口等。 3. 运行引导（从根开始的 DFS）。见 bootstrap.md。 ### 创建实体（编写新代码时） 1. 创建模块：dsp-cli create-object <路径> <目的> 2. 创建函数：dsp-cli create-function <路径>#<符号> <目的> --owner <模块-uid> 3. 注册导出：dsp-cli create-shared <模块-uid> <函数-uid> [<函数-uid> ...] 4. 注册导入：dsp-cli add-import <本实体-uid> <被导入-uid> [--exporter <模块-uid>] 5. 外部依赖：dsp-cli create-object <包名> <目的> --kind external ### 浏览图（阅读/理解代码时） - 按文件找实体：dsp-cli find-by-source <路径> - 按关键字搜索：dsp-cli search <查询> - 读 TOC：dsp-cli read-toc → 获取所有 UID，再用 get-entity 查看详情 - 向下依赖树：dsp-cli get-children --depth N - 向上依赖树：dsp-cli get-parents --depth N - 影响分析：dsp-cli get-recipients —— 谁依赖此实体 - 实体间路径：dsp-cli get-path <起点> <终点> ### 更新（修改代码时） - 目的变更：dsp-cli update-description --purpose <新目的> - 文件移动：dsp-cli move-entity <新路径> - 导入原因变更：dsp-cli update-import-why <导入方> <被导入方> <新原因> ### 删除（移除代码时） - 移除导入：dsp-cli remove-import <导入方> <被导入方> [--exporter UID] - 移除导出：dsp-cli remove-shared <导出方> <共享方> - 删除文件/模块：dsp-cli remove-entity （级联清理） ### 诊断 - dsp-cli detect-cycles —— 循环依赖 - dsp-cli get-orphans —— 未使用实体 - dsp-cli get-stats —— 项目图概览 ## 何时更新 DSP | 代码变更 | DSP 操作 | |---|---| | 新文件/模块 | create-object + create-function + create-shared + add-import | | 新增导入 | add-import（+ create-object --kind external 若新外部依赖） | | 移除导入 | remove-import | | 新增导出 | create-shared（+ create-function 若新函数） | | 移除导出 | remove-shared | | 文件重命名/移动 | move-entity | | 文件删除 | remove-entity | | 目的变更 | update-description | | 仅内部变更 | 无需更新 DSP | ## 参考资料 - 存储格式 —— .dsp/` 目录结构、文件格式、TOC - 引导过程 —— 初始项目标记（DFS 算法） - 操作参考 —— 所有操作的详细语义及导入示例