使用 Data Structure Protocol 为 AI 构建持久化代码结构内存

解决 AI Agent 在处理大项目时因 Token 限制而频繁丢失上下文的问题：通过在 .dsp/ 目录下维护一套轻量级的持久化结构图谱，让 AI 能够快速定位依赖关系并理解代码连接的意图。

为什么需要这个技能

在大型代码库中，AI Agent 往往将大量 Token 浪费在“重新定向”上——即反复阅读文件以确认哪里定义了什么、谁依赖谁以及修改某处是否安全。

Data Structure Protocol (DSP) 不同于传统的文档或 AST dump，它将代码库建模为一个有向图。它记录的不仅是“连接”（谁导入了谁），更重要的是“理由”（为什么需要这个依赖）。通过将这种结构信息外置到 .dsp/ 目录，AI 无需将整个源码树加载到上下文窗口中，即可实现精准的导航和影响分析。

适用场景

• 超大规模项目：当项目文件多到 AI 无法一次性读取时。
• 复杂重构：需要进行影响分析，确认删除某个 API 会破坏哪些模块。
• 新成员上手：AI 需要快速引导用户理解项目模块间的逻辑关系。
• 依赖分析：在替换第三方库前，系统性地查找所有调用点及其用途。

核心工作流

1. 基础概念

• 实体 (Entity)：分为 Object（模块/类/配置）和 Function（导出的函数/方法）。
• 唯一标识 (UID)：每个实体拥有一个稳定的 UID（如 obj-a1b2c3d4），即使文件重命名或移动，UID 保持不变。
• 关系理由 (Why)：每次记录 import 时，必须附带简短的理由，说明该依赖的目的是什么。

2. 存储结构

.dsp/ 目录采用纯文本存储，每个实体拥有独立子目录：

• description：实体用途（1-3 句话）。
• imports：依赖的 UID 列表。
• shared：暴露的公共 API 列表。
• exports/：反向索引，记录谁导入了该实体及其理由。

3. 操作流程

• 初始化：使用 dsp-cli.py 脚本从入口文件开始，通过深度优先搜索 (DFS) 遍历并构建图谱。
• 同步更新：在创建新文件、新增 import 或修改公共 API 时，立即调用对应的 CLI 命令更新 .dsp/ 状态。
• 查询分析：通过 get-recipients 查看谁在使用该模块，或使用 get-path 分析两个实体间的调用链路。

关键命令示例

# 初始化项目
python dsp-cli.py --root . init

# 创建对象并定义函数
python dsp-cli.py --root . create-object "src/app.ts" "主应用入口"
python dsp-cli.py --root . create-function "src/app.ts#start" "启动 HTTP 服务器" --owner obj-a1b2c3d4

# 记录依赖关系（含理由）
python dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef "处理 HTTP 路由"

# 影响分析：查找所有依赖某个库的模块
python dsp-cli.py --root . find-by-source "lodash"
python dsp-cli.py --root . get-recipients obj-11223344

下载和安装

下载 data-structure-protocol 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐