data-structure-protocol

data-structure-protocol 技能概览

这个技能能做什么

data-structure-protocol 技能帮助 agent 构建并导航 DSP——一种面向代码库的图谱式记忆层。它会记录模块、函数、imports、exports，以及这些链接之所以存在的原因，让模型能够回答“有什么、依赖谁、为什么依赖”，而不是只根据文件名猜测。

适合谁安装

如果你的项目已经有 .dsp/ 目录，或者你需要在仓库里从零引导 DSP，或者你希望 agent 先检查结构上下文再做更安全的代码修改，那么就应该使用 data-structure-protocol 技能。它尤其适合维护者、agentic coding 工作流，以及那些依赖边界比文档叙述更重要的仓库。

它为什么不一样

这不是一个通用的 prompt 包装器。data-structure-protocol 技能围绕具体的数据存储模型、CLI 和引导流程构建，会把真实文件转成实体图谱。相比普通的“理解这个仓库”提示，它更有决策价值，因为它会明确告诉 agent 该读什么、该验证什么，以及什么时候不该注册无效 import。

如何使用 data-structure-protocol 技能

安装并确认仓库结构

使用以下命令安装 data-structure-protocol 技能：
npx skills add k-kolomeitsev/data-structure-protocol --skill data-structure-protocol

安装后，确认仓库里包含 SKILL.md、references/ 和 scripts/dsp-cli.py。这个仓库围绕 bootstrap、operations 和 storage-format 提供了一套实用工作流，所以这些文件比在普通项目里粗略看一遍 README 更重要。

给技能一个明确任务

当你说明仓库状态和要完成的工作时，这个技能效果最好。好的输入应包括项目根目录、.dsp/ 是否已经存在，以及你准备做哪类修改。例如：“这个仓库使用 DSP，我需要新增一个模块；先识别受影响的实体，再告诉我哪些文件和 UID 需要更新。”

对于 data-structure-protocol usage，不要只说“帮我处理 DSP”这种笼统请求。你应该明确说明你需要的是引导、导航、更新还是清理。这个技能优化的是结构性决策，而不是泛泛的架构建议。

先读对文件

先看 SKILL.md，理解 agent prompt 和核心规则。然后读 references/bootstrap.md，了解 DFS 引导流程；读 references/operations.md，查看 create/update/read 命令；再读 references/storage-format.md，了解 UID 和文件夹结构。如果你打算直接使用 CLI，还要检查 scripts/dsp-cli.py，看看真实命令行为和边界情况处理。

能产出更好结果的工作流

一个可靠的 data-structure-protocol guide 流程是：先确认根入口点，再读取受影响实体，核实文件正文里实际使用的 imports，最后创建或更新 DSP 记录。向模型下达任务时，要提供足够的源代码上下文，帮助它识别入口点、导出面，以及哪些模块的关系正在变化。协议正是依赖这些信息来保持图谱准确。

data-structure-protocol 技能常见问题

这个技能只适用于已经在用 DSP 的项目吗？

不是。这个技能既适用于已有 .dsp/ 的项目，也适用于引导搭建。如果仓库里还没有图谱，data-structure-protocol 依然可以指导你如何把根文件和依赖正确映射到 DSP。

它比普通 prompt 更好吗？

通常是的，尤其在结构重要的时候。普通 prompt 可能只是总结代码，而 data-structure-protocol 的目标是保留长期结构记忆：实体、imports、exports 和原因。如果你的任务依赖准确的跨文件关系，这个技能比一次性的解释型 prompt 更合适。

初学者能用吗？

可以，只要能找到项目根目录并描述自己想改什么。主要学习成本在于理解 DSP 记录的是代码结构，而不是面向人的文档。如果你分不清哪些文件是入口点，或者哪些 imports 真正被使用了，这个技能可能还需要更多仓库上下文才能发挥作用。

什么情况下不该用它？

如果你的任务主要是文案编辑、UI 文案，或者只是一个单文件玩具脚本，而图谱记忆带来的价值很有限，那就可以跳过 data-structure-protocol。如果你没有源码访问权限、无法查看仓库树结构，或者第一轮之后也不打算维护 DSP 元数据，它也不是合适的选择。

如何改进 data-structure-protocol 技能

提供图谱真正需要的输入

最好的 data-structure-protocol skill 结果来自精确的源代码引用：入口文件、变更模块，以及新增或删除的具体符号或 import。条件允许的话，直接点名根文件和受影响路径，比如 src/app.py、lib/index.ts 或 cmd/main.go，这样 agent 才能把更新准确映射到对应实体。

注意常见失败模式

最大的失败模式，是把 DSP 当成普通文档，跳过验证。另一个常见问题，是把 import block 里存在、但文件正文根本没用到的 imports 也注册进去。data-structure-protocol 的 bootstrap 和 operations 文档已经说明，它关心的是经过验证的关系，所以你应该要求模型在记录链接之前先检查实际使用情况。

第一轮之后继续迭代

如果第一次输出范围太大，就把提示收窄到一个阶段：bootstrap、search、read 或 update。对于 data-structure-protocol for Skill Authoring 来说，通常的顺序是：先让它识别受影响实体并做边界检查，再让它给出精确的 DSP 操作或文件修改。迭代效果最好时，每一步只有一个明确的结构目标和一个仓库范围。