前言¶
DeepSeek Harness (DSH) 插件生态旨在通过模块化扩展智能体能力。在长期项目协作中，智能体会话往往面临上下文窗口限制与认知碎片化的问题，即“任务做完即忘，新会话从头学起”。为了解决这一痛点，project-ai-docs 提供了一套通用协议，旨在将项目认知沉淀在文档而非会话记忆中。
插件简介¶
project-ai-docs 是一个通用项目 AI 文档协议 skill。其核心逻辑是为每个项目维护一份独立的 docs/.ai/ 认知库。智能体在执行任务前，会先读取该库的索引，再针对性读取相关文档；任务完成后，改动会自动回写到文档中。这种方式旨在防止上下文涣散，并保持项目认知的精细度。
核心功能¶
该插件通过以下协议与机制保证文档体系的有效性：
- 地图先行：
index.md作为唯一入口，构建全文档的路由表。 - 分层预算：将文档划分为 core/modules/config/best-practices 四层，显式控制 token 开销。
- 红线前置：硬约束（禁止项）置于
index.md顶部，优先于技术细节。 - 点读代替全读：按任务需求只读取相关切片，避免冗余信息干扰。
- 写回闭环：任务结束即视为文档更新，知识沉淀在文档系统。
- 增量感知：通过
changelog台账记录变更，新会话读取尾部即可掌握项目现状。 - 人机分离：
README.md面向用户，docs/.ai面向智能体。 - 事实可验：文档内容仅包含实测路径、版本与命令，杜绝猜测。
安装与启用¶
DSH 官方安装（推荐）¶
使用插件命令安装，随 profile 管理：
dsh plugin --profile web add project-ai-docs
安装完成后重启 DSH 进程即可生效。
本地验证安装¶
若需在未发布到 npm 的本地代码上测试：
dsh plugin --profile web add file:D:\Desktop\project-ai-docs
工作原理¶
B 路安装利用包内的 dsh.bundle.patch 配置，将其指向 cordis.patch.yml，进而加载 extensions/dsh/index.js。该适配器会将 skills/ 目录下的内容注册为 DSH 的技术源。
其他宿主¶
对于 Claude Code、Codex 等非 DSH 宿主，直接复制 skills/project-ai-docs/ 目录至其对应的 skills 路径即可使用。
使用方式¶
插件定义了三个标准阶段，按顺序执行：
1. 新会话开始¶
智能体启动时，先读取 index.md 和 changelog，根据任务需求点读相关分层文档，建立上下文。
2. 初始化项目文档¶
触发命令为 /init。执行 Init 协议：
* 扫描项目结构
* 建立文档骨架
* 实测填充内容
3. 任务完成后¶
执行清理与回写流程：
* 清理冗余信息
* 回写对应文档
* 在 changelog 中记账
生态与依赖¶
- 依赖：该插件依赖
@deepseek-ai/dsh-skill-filesystem作为 peer dependency（可选）。 - 许可证：MIT。
- 目录结构：
skills/project-ai-docs/：运行时技能单元。extensions/dsh/index.js：DSH bundle 适配器。cordis.patch.yml：bundle 注册配置。
结语¶
project-ai-docs 提供了一套结构化的文档管理方案，帮助开发者与智能体在 DSH 环境下建立持久、可验证的项目认知体系。更多细节与源码，请参考其 GitHub 仓库。
