前言¶

DeepSeek Harness（DSH）的智能体在开发过程中经常修改代码，但容易遗漏同步更新相关文档。dsh-doc-impact 插件通过确定性执行机制，将代码变更与文档更新绑定，建立声明式的影响图，确保文档与代码保持一致。

核心功能¶

该插件通过以下机制解决文档与代码脱节的问题：
* 影响分析：将代码和文档链接到声明式影响图。
* 变更检测：将工作区与基准（Git 或文件系统）进行对比。
* 规则匹配：将增量变更与项目规则进行匹配。
* 智能引导：在智能体关闭回合前，引导其审查或更新受影响的文档。
* 标准扩展：作为标准 Cordis 扩展实现，无需修改 DSH 核心。

安装与启用¶

在 Harness 中安装插件，需要使用 profile 参数。安装完成后需重启 Harness 以加载插件。

# 从本地路径安装
dsh plugin --profile web add link:/path/to/dsh-doc-impact

# 或安装已发布的版本
dsh plugin --profile web add dsh-doc-impact

配置¶

在工作区根目录创建配置文件 .dsh/doc-impact.yml。

version: 1

defaults:
  mode: remind
  scope: turn
  changeDetection: auto

rules:
  - id: auth-docs
    description: Authentication behavior documentation
    code:
      include:
        - packages/auth/**
        - packages/server/src/auth/**
      exclude:
        - "**/*.test.ts"
    docs:
      - docs/authentication.md
    direction: code-to-docs
    relation: documents
    mode: require-resolution

配置文件定义了代码与文档的映射关系。例如，packages/auth/src/session.ts 变更会触发 docs/authentication.md 的更新检查。

工作流程¶

插件在智能体的运行流程中执行以下步骤：
1. 记录基准：在回合开始时，记录 HEAD 和所有已脏文件的哈希值（Git 模式）或匹配选择器的文件（文件系统模式）。
2. 停止检查：在回合结束时，对比工作区与基准，匹配增量变更。
3. 自动解析：自动解析目标文件已被更新的影响。
4. 引导与解决：对于未解决的影响，插件会提醒智能体。在严格模式下，智能体需调用 doc_impact_resolve 命令进行确认。

命令与工具¶

插件提供了一系列命令用于查询和解决文档影响问题。

插件配置 UI¶

插件提供浏览器端的配置界面。在 Harness 的 Settings → Plugins → Plugin Configuration 中，可以找到 “Doc Impact” 卡片。
* 阶段编辑：修改不会立即保存，需点击 Save。
* 状态反馈：标题栏在存在草稿时会显示 unsaved 徽章。
* 重置功能：每个字段下方提供 Reset 按钮，可恢复到配置层设置。

重要说明¶

• 仓库状态：原仓库已存档并设为只读。开发已迁移至 xarleyn/dsh-plugins 单体仓库。
• 新包名称：旧包 dsh-doc-impact 已被 @yadsh/dsh-doc-impact 取代。
• 依赖要求：需要 Node.js 版本 >= 20。
• 许可证：MIT 许可证。

结语¶

dsh-doc-impact 通过将文档影响纳入 DSH 的自动化流程，为开发者提供了确定性更强的代码与文档同步保障。