xarleyn/dsh-doc-impact

dsh-doc-impact

[!IMPORTANT]
此仓库已归档。

此插件的开发已迁移至 xarleyn/dsh-plugins monorepo，该仓库现已成为该项目的正式归属地。

请使用新仓库进行以下操作：

* 新版本发布与更新；
* 缺陷报告与功能请求；
* 拉取请求与后续开发。

此仓库出于历史目的保留为只读状态。

为 DeepSeek Harness 提供确定性的文档影响强制执行。

该插件将代码与文档链接成一个声明式的影响图。当智能体在一轮对话中更改文件时，dsh-doc-impact 会将工作区与该轮基线进行差异比较，将差异与项目规则进行匹配，并在该轮对话结束之前，引导智能体审查或更新受影响的文档。将该插件实现为标准 Cordis 扩展意味着无需对 DSH 核心进行任何更改（SPEC §14、§93）。

packages/auth/src/session.ts changed

→ docs/authentication.md
→ docs/security/session-lifecycle.md

安装

dsh plugin --profile web add link:/path/to/dsh-doc-impact   # local checkout
or, once published:
dsh plugin --profile web add dsh-doc-impact

然后重启 harness 以加载该插件。

工作区配置

在智能体所工作的项目中创建 .dsh/doc-impact.yml：

version: 1

defaults:
mode: remind            # remind | require-review | require-resolution | require-update
scope: turn             # turn | session
changeDetection: auto   # auto | git | filesystem

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     # code-to-docs | docs-to-code | bidirectional
relation: documents         # documents | specification | synchronized | related
mode: require-resolution

Concise form is also accepted:
- id: configuration-contract
code: [packages/config/*]
docs: [docs/configuration.md]
direction: bidirectional
relation: specification

个人覆盖配置应放在 .dsh/doc-impact.local.yml 中（将其添加到 .gitignore）：

disabledRules:
- legacy-docs

插件级默认值（profile 补丁）

- insert:
- id: doc-impact
name: dsh-doc-impact
config:
enabled: true
configFile: .dsh/doc-impact.yml
defaults:
mode: remind
safety:
maxReminderRounds: 2
onLimit: allow        # allow | warn | error
changeDetection:
maxSnapshotFiles: 10000
debug: false

工作原理

1. 基线 —— 在该轮对话的第一步，插件记录 HEAD 以及每个已处于脏状态文件的内容哈希（git 模式），或所有
选择器匹配的文件（文件系统回退）。因此，预先存在的用户更改永远不会归因于 agent（SPEC §16-§19）。
2. 停止检查 —— 在 agent/turn-stopping 时，插件将工作区与基线进行差异比较（包括 agent 在回合中途所做的提交），将差异与规则进行匹配，并自动解决目标已被更新的影响（SPEC §31、§88）。
3. 引导 —— 未解决的影响会产生一条分组提醒，agent 会获得另一个模型步骤来更新或审查文档。
4. 解决 —— 对于严格模式，agent 调用
doc_impact_resolve { ruleId, status, reason? }，使用 reviewed-current、
updated（根据实际文件差异进行验证）或 not-applicable
（需要非空原因）。
5. 循环保护 —— remind 对每个影响指纹引导一次；严格模式在 maxReminderRounds 后停止，并遵循 onLimit（默认失败开放，SPEC §34-§36）。

命令和工具

| 接口 | 用途 |
|---|---|
| /doc-impact | 当前待处理/已解决状态 |
| /doc-impact check | 立即重新计算影响 |
| /doc-impact explain  | 显示一条规则以及它是否被触发 |
| /doc-impact changed | 插件归因于该 agent 的文件 |
| doc_impact_resolve | 显式解决工具（严格模式） |
| doc_impact_status | 只读状态工具 |

插件配置 UI

该插件附带一个浏览器端部分（lib/client.js，exports "./client"），因此
设置 → 插件 → 插件配置 会显示一个绑定到 doc-impact 设置命名空间的“Doc Impact”卡片。它遵循第一方卡片模型：

- 暂存编辑 —— 在 保存 之前不会写入任何内容；丢弃 会丢弃草稿；
- 当草稿存在时，标题栏会带有 未保存 徽章；
- 保存 在有内容可写入之前保持禁用（并且在草稿无效或保存正在进行时也保持禁用）；
- 每个字段都会显示保存是否会留下用户层覆盖，并且当存在覆盖时，会显示一个按字段的 重置，用于恢复到组合层。

可编辑字段：enabled、configFile、默认 mode、maxReminderRounds、
onLimit、maxSnapshotFiles、debug。配置文件补丁行的 config: 在这些用户编辑之下充当组合基础；引擎会实时读取合并后的视图（切换 enabled 可在无需重启的情况下使插件静默）。

开发

npm install
npm run check   # typecheck + tests + build

核心部分（src/config、src/graph、src/changes、src/engine）独立于
DSH，并且无需测试框架即可测试；只有 src/dsh 导入
@deepseek-ai 包（SPEC §83、§92）。集成测试会运行真实的 git
仓库，包括完成定义场景（SPEC §95）。

状态

按 SPEC §80 的 MVP 范围：代码到文档 / 文档到代码 / 双向规则、
glob 包含/排除、git + 文件系统基线检测器、agent/turn-stopping
继续、提醒聚合、remind + require-resolution（以及
require-review / require-update 模式）、循环保护、命令、单元测试和集成测试。

许可证

MIT