dsh-completion-guard

English

面向 DeepSeek Harness（DSH）的任务保护插件。它保存任务要求，并在任务标记完成前逐项核对；会话恢复后仍使用同一份检查表，只有匹配的已保存工具结果才能作为证据。

0.9.0 要求 DSH >=0.2.0-rc.2，并支持官方 Desktop 应用。 已有安装须先停止相关写者，在更换 DSH 或 Guard 前保存旧安装包、有效模式来源及冻结会话清点，使用独立准备的候选迁移工具。随后升级安装、重建各 profile 宿主锁，并在启动宿主前完成旧会话的 adopt 和 verify。没有旧 Guard 会话的全新安装只需安装及宿主锁检查，不需旧模式 adoption。Desktop 使用 --profile desktop，以应用归档为 runtime root；安装本身不重建锁。已测试的宿主基线是 DSH 0.2.0-rc.2、Cordis 4.0.4；较新版本仍须通过身份和适配契约检查。资格及原生证据范围见兼容性指南。

官方读取器拒绝旧格式时，保留原日志和旧模式来源，按显式可读子集方案先 inventory、再由用户选择 ID 并 select，让 --selection 贯穿 inspect/adopt/verify。工具核对全库变化，只迁移用户选中的可读项；selected_complete 保留全部排除项为 pending，不代表整库完成。说明中提供真实命令、恢复步骤和可复制 AI 提示词。

快速开始

执行安装命令前，先选择对应流程：

• **全新安装，没有旧 Guard 会话：**停止宿主，升级到 DSH 0.2.0-rc.2 或更高版本，按下方安装 Guard，再重建宿主锁，最后启动。
• **已有安装：**先停止相关写者，保存旧安装包及有效模式来源，按迁移说明准备并冻结旧会话清点与收据。这一步必须在更换 DSH 或 Guard 前完成。随后按下方安装、重建宿主锁；保持宿主停止，用冻结旧收据完成 adopt 和 verify，再启动。未知来源保持 pending，不能用升级后的新缺省替代旧模式。

完成对应准备后，再把 Guard 安装到需要保护的 Profile：

dsh plugin --profile web add [email protected]

升级和执行下面的安装图检查时，保持宿主停止。 宿主锁记录 DSH 实际使用的包版本和安装目录；如果升级前就生成锁，新运行时会因包版本不匹配而拒绝它。inject 会修改 <profile>/cordis.patch.yml，请先备份该文件。

查看每条命令 JSON 输出中的 status，确认它为 supported。失败会报告具体原因并以非零退出码结束。较新兼容宿主需给三条命令都加上 --rebind-registry，先验证官方包归档，并在隔离 Node 进程中检查变化程序的兼容契约，再重建锁；步骤见升级指南。

DSH_RUNTIME_ROOT=/absolute/path/to/.dsh-runtime
DSH_PROFILE_ROOT=/absolute/path/to/.dsh/profiles/web
GUARD_HOST_LOCK="$DSH_PROFILE_ROOT/node_modules/.bin/dsh-completion-guard-host-lock"

"$GUARD_HOST_LOCK" inspect --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
"$GUARD_HOST_LOCK" inject --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT"
dsh --profile web --dump-config | "$GUARD_HOST_LOCK" verify-dump --runtime-root "$DSH_RUNTIME_ROOT" --profile-root "$DSH_PROFILE_ROOT" --dump-config -

Windows 请通过 Web 配置目录下的 node_modules\.bin\dsh-completion-guard-host-lock.cmd 运行相同的三个子命令，并使用 Windows 绝对路径。各版本的原生验收与发布证据在验收记录中按版本绑定其精确制品字节单独记录；任何版本的源码与确定性证据都不能等同于该版本已安装制品的结论。其他宿主版本和制品仍需各自的原生证据。DSH、Guard 或 profile 路径变化后需要重新检查；仅 market 普通升级不需要重新注入。如果当前包集合缺失、重复、不可信或不同于已绑定环境，Guard 会保持不可用。

Desktop 请使用应用附带的 CLI 安装，再以 --profile desktop、应用 app.asar 和实际 profile 路径建立宿主锁。它的 CLI 不提供 --dump-config，请用 Guard 的 dump-desktop 生成组合配置再回读；见Desktop 升级步骤。官方插件市场（dshmarket）现在可以在 Desktop profile 中与 Guard 共存；安装或移除市场后，请按完整四步流程重建 Desktop 锁（inspect、inject、用 dump-desktop 新生成的组合配置、以及对新配置执行的 verify-dump）。

已有安装请先按迁移说明，用冻结旧收据完成 adopt 和 verify，期间保持写者停止；宿主锁核验不执行模式 adoption。两项核验通过后（全新安装则在安装及宿主锁核验通过后），再启动 DSH Web，打开会话并查看 Guard 状态：

/context-guard status

新建根会话默认采用 always，从第一条真实用户消息开始保护。status 显示 Guard 是否开启、启动阶段（armed 表示已就绪、等待你的第一条消息）以及还有多少检查项。off 停止保护当前会话，但不删除历史。clear 关闭当前待办，同时保留禁止项。diagnose 说明完成检查为什么通过或失败；migration 报告当前会话适用哪套规则、升级与回滚分别意味着什么；release 报告显式发布契约、其覆盖范围以及仍在执行中的操作。

普通工作

照常让 DSH 修改文件或运行测试，助手通过 DSH 宿主工具执行。Guard 保存要求，观察宿主已持久化的调用与结果；要求的结果需要独立核验时，再使用只读回读。例如，宿主修改配置文件后，另一次精确文件回读可证明新内容；具名测试需要自己的真实运行结果。工具返回成功或助手自述，不能证明无关条件，也不能抹去对禁改文件的真实修改。context_guard_prepare 说明缺少什么证据，context_guard_checkpoint 只核对证据实际证明的谓词。

0.6.x 的普通 context_guard_action 与 context_guard_evidence 不再执行编辑、测试或 Git 效果，而是返回迁移说明。新建文件还需可信的写入前不存在证据。包脚本就绪观察可以选择已有测试或评估输入，不强迫再次编辑，但它不证明脚本已经运行，也不认证任意数值输出。后续观察长期收益的要求，要到其时间或审批条件满足后才成为当前工作；简短“继续”只推进有来源且已就绪的具体动作。

它保护什么

• 保存需求、验收条件、禁止项和后续修正，不覆盖旧记录。
• 只使用 DSH 已保存的工具调用和结果，并保存脱敏摘要而不是完整输出。
• 只有动作和结果对应指定命令、文件或其他目标时，证据才有效。
• 会话重建或恢复后重新检查完成状态；记录损坏时拒绝签发证书。
• 当前检查表尚未通过时，阻止 Guard 自己守卫的 Goal 完成路径。DSH 内部仍可能绕过这条路径，因此插件会报告这些情况，不声称能阻止所有写入。

状态与兼容性

0.9.0 的版本准入范围是 DSH >=0.2.0-rc.2，没有版本上限，并支持官方 Desktop 应用的独立 profile（desktop）：应用自有的 dsh-profile-desktop 按名称识别，其内置依赖图从已签名的 app.asar 原位读取，安装字节按发布 tarball 逐文件核验。Cordis 使用独立的 >=4.0.4 peer 范围，仍须通过适配器资格验证。已发布的 0.2.0-rc.2 46 包依赖图为已审查基线（rc.1 图保留为历史证据）；较新混合版本图在所消费实现具备资格后，可建立自己的 registry 来源锁。变化的 Session/API 实现须通过有限行为探针，不兼容行为会报告具体资格缺口，旧证书不能转移到新锁。最终制品的 macOS/Windows 原生验收、未来版本原生证据与 Desktop 原生验收仍须分别建立。

升级后重新检查、注入并验证 host-lock，再按需启动对应 Profile，步骤见宿主锁升级。旧会话由 DSH 迁移为 V4；Guard 保留旧 ledger 和证书，但不会重签或把旧身份升级为当前权限。Goal 为可选能力，宿主安装不代表它已启用。

宿主检查核对包身份、实现字节及实际加载它们的依赖路径。原生与模型验收绑定到每个版本的精确制品；请查看对应 Release 的附件和兼容性说明。

重启属于单独能力。当前 DSH 没有提供可独立验证的 market 已加载实例绑定，因此 Guard 的 market 重启适配器返回不可用；已有重启要求仍保持未完成。核心保护和不依赖该接口的操作继续工作。磁盘上的插件安装/应用不等于运行进程或 UI 已生效。

升级到新核心锁时，需要从实际运行时与 profile 重新生成并验证锁；旧证书不会被重新标记为新锁证据。详见升级说明和兼容性。

从 npm 选择已发布版本，并用 GitHub Release 的提交、校验和和原生 annex 核对制品。0.4.2 的历史发布面向 DSH 0.1.2-rc.1 与 market 1.41；它不包含上述解耦。源码版本号、CI、同包原生验收和公开发布是不同状态，验收范围见记录。

项目在 2026-08-29 从 dsh-context-guard 更名为 dsh-completion-guard，内部 bundle id 仍为 context-guard。迁移保留会话、激活方式和禁用设置；不要在同一 profile 同时加载新旧包。需要 Node.js >=22 和 pnpm >=11。

启用模式

Context Guard 有两种启用模式：

• always（新建根会话默认，推荐）：新建 DSH 根会话从第一条真实消息开始自动保护。首条真实输入前，Guard 不向会话追加事件；DSH 仍可能写入自身的初始化事件。你仍然可以在发送任何内容之前选择 DSH 会话模式（standard、minimal 或自定义 preset）。第一条真实消息进入执行步骤的那一刻，保护在同一步骤内、且位于该消息之前开始：第一个任务连同它的第一次文件修改都在覆盖范围内。首条消息只有图片或附件时同样开始保护，并保留待解释的资产项；纯空白消息不启动任何内容。在某个会话中执行 /context-guard off 后，该会话关闭保护，直到再次执行 on。
• opt-in（显式选择）：打开会话时不会自动保护。你需要在这个会话中执行 /context-guard on 才会启用；执行 /context-guard off 可以再次关闭。开关只影响当前会话。

0.9.0 将新会话的默认模式改为 always；旧会话通过核验后的不可覆盖绑定保留升级前有效模式。 升级前请停止相关会话写者，按inspect/adopt/verify 迁移说明准备旧模式清点与冻结收据，旧空会话也要包含。共享库存中不同 profile 的旧模式有冲突时，需要精确到会话的映射；Guard 不依据消息数量、时间戳或记录过的 on 猜测。

恢复已有绑定的会话时，profile 缺省变化不改变它的模式。显式 activation 与绑定矛盾会报告 activation_mode_conflict；缺失或损坏的绑定不能认证，并给出具名诊断。恢复不会自行创建替代绑定；核验过的迁移收据可以受控补建同一旧模式，不修改已保存日志，也不重签证书。持久化的 /context-guard off 和 on 继续有效，standard 策略及执行、发布权限保持原合同。选择另一初始模式请新建根会话；回退时保留绑定和旧收据，按迁移说明操作。

启用模式只控制 Guard 是否保护会话，不是 DSH 的会话模式（例如会话开始时所选的标准模式、极简模式）。Guard 不再在第一条消息之前写入任何内容，因此 DSH 会话模式可以在会话尚为新会话时选择。/context-guard on 和 /context-guard off 只负责开启或关闭 Guard 保护，不会改变 DSH 会话模式。

省略 activation 的 profile 新建根会话时采用 always；已有会话绑定仍具有优先权。若现有 profile 显式选择了 opt-in，请把实际 profile 的 cordis.patch.yml 中已有 context-guard 项设为 activation: always，保留已注入的宿主锁字段。下面的片段只显示要修改的字段，不用于替换整份配置：

- id: context-guard
  name: dsh-completion-guard
  config:
    activation: always

DSH 的 Web 网页、Headless 终端和 Desktop 桌面应用使用独立配置。请修改实际使用的 profile；多种方式都用时分别修改：

系统	你怎么使用 DSH	默认路径
macOS / Linux	Web	$HOME/.dsh/profiles/web/cordis.patch.yml
macOS / Linux	Headless	$HOME/.dsh/profiles/headless/cordis.patch.yml
macOS	Desktop	$HOME/.dsh/profiles/desktop/cordis.patch.yml
Windows	Desktop	%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml
Windows	Web	%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml
Windows	Headless	%USERPROFILE%\.dsh\profiles\headless\cordis.patch.yml

如果你设置过自定义 DSH_HOME，请用该目录替换路径开头的 $HOME/.dsh 或 %USERPROFILE%\.dsh。

不想手动改文件，也可以把下面这段话直接发给 DSH：

请把 dsh-completion-guard 新建根会话的默认模式设为 always，保留已有会话绑定。根据我当前使用 DSH 的方式（Web、Headless 或 Desktop），自动找到对应的 cordis.patch.yml，先备份该文件，只把 id: context-guard 这一项的 activation 设为 always，不要修改其他配置，也不要替我重启 DSH。完成后告诉我文件的绝对路径，并显示准确的修改内容。

修改完成后，重启 DSH。

如何检查完成状态

启用后，Guard 会保存用户直接给出的要求和验收条件。只有已保存的工具结果与指定命令、文件或其他目标一致时，才能作为证据。取得机器完成认证需要通过 Guard 检查；证据缺失、过期或对象不一致时，任务保持未认证。当前证据规则未覆盖的调查或解释仍可如实回答并结束，但不会取得完成证书。

只读观察与修改包、文件、服务或 Git 状态的操作保持分离。普通动作由宿主工具执行；查询成功不会自动产生变更权限。精确命令限制和平台证据见 docs/COMPATIBILITY.md。

要求一直未完成时

“更新插件并检查 GUI”可能包含 Guard 尚不能认证的部分；而“是否有更新”这类提问属于调查：Guard 会保留原文和来源，但如实说明无法机器认证——完成调查并如实回答即可。checkpoint 会逐项给出原因和一个具体的下一步。context_guard_prepare 用于诊断要求和缺失证据，不是普通宿主工作的执行配方。

只有根要求本身需要拆分时，才用 context_guard_rebind 提出完整的原文拆分方案。普通工作缺少认证支持，不构成重新绑定的理由。动作或对象不明确时，先请根用户给出包含原条款的明确澄清要求，再在提案中引用新要求的 ID。工具会返回提案 ID 和原项/替代项对照；用户把确认行 确认重绑定 <proposal ID> 作为回复的第一行即可应用，空行之后的解释请求或新任务保留各自含义，新任务照常采集。嵌在句子、引号或代码块里的确认，以及后面跟反转表述的确认，都无效。把要求拆成同样不可认证的片段会得到“无认证收益”，而不是要求一次无意义的确认。未支持的部分继续保留 pending；按结构化边界安全结束也不表示全部完成。

用 bindings: [] 调用 context_guard_checkpoint 可查询诊断。默认最多展示八个当前要求/限制和十条证据，插件 JSON 不超过 12 KiB。pagination 给出总数及各列表独立的 next_cursor，首页不代表完整合同。item_ids、evidence_ids 可按 ID 查询；evidence_scope: "history" 可查看完整证据历史，其中不可引用项会明确标记。翻页时保持查询条件不变，合同或证据快照变化后需重新查询。超长行提供 detail_id，用 detail_offset 取分片；后续分片需把首次返回的 snapshot 作为 detail_snapshot 传回。分页只改变展示，不会减少认证时检查的要求。

完成与恢复

Guard 按原始范围保留每项要求、禁止项和答复义务。宿主记录答复已交付后，问题才可关闭；文件修改、测试或回读仍需各自的真实结果。修改图片的要求要核验修改后的图片，不能只看工具是否成功。显式 proof 要求继续走 proof 契约；已采用的 Goal 完成路径仍核验必需结果。

动作来源决定其范围。未来观察、尚未满足的时间或审批条件、证据不足和已就绪的具体动作是不同状态。后来的授权不会改写更早的 Stop 判断。有来源的暂停、取消或简短恢复只影响其范围内已经存在的工作；引用文字和旧 generic 待办不会在重载后变成当前授权。旧 v5 历史保留供复核，新 v6 工作使用当前合同。

义务含糊时，context_guard_rebind 可以提出精确拆分，但只有根用户明确确认才会应用。无法支持的核验会如实报告证据不足，不授予动作，也不强迫再次编辑。用 /context-guard diagnose 和只读 checkpoint 查看缺失谓词，再通过宿主工具完成可支持的工作，并如实说明边界。

旧安装的 0.6.3 执行流程保留在对应更新日志中。当前普通 context_guard_action 与 context_guard_evidence 调用只返回迁移说明。

策略档位

三个档位决定完成时需要多少证明。它们与 opt-in / always 激活方式相互独立，安装也绝不进入 release 档。

档位	要求
standard（默认）	工作必须有持久证据支撑；普通工具不会被额外的 Guard 审批拦在后面。
strict	在 standard 之上，你明确要求的视觉或完整范围验证必须由真实回读事实兑现，而不是一次"只是成功"的工具调用。
release	显式采用的发布契约按精确候选和一次性预约核验受覆盖的发布操作。契约本身不提供用户授权或宿主权限。

在 cordis.patch.yml 的同一项里与 activation 一起设置：

- id: context-guard
  name: dsh-completion-guard
  config:
    activation: always
    policy: strict

显式发布契约

消息中的“发布”关键词、加载的 Skill 或安装都不会自动采用发布契约。用户另外授权发布后，可通过 /context-guard release adopt 显式给出所覆盖的操作、候选 ref、完整提交、版本和制品摘要。/context-guard release 随后显示覆盖范围与未结算操作。新版本不能复用历史候选身份。

采用之后，/context-guard release 报告契约、候选、逐操作覆盖范围、已消费内容和仍在执行中的操作。每个操作只消耗一次预约记录：效果前写入，效果后依据可信回读结算。错候选 SHA、错 ref、错制品摘要或版本、过期票据、已消费票据、仍在执行中的请求重试和不透明 runner 都会在任何副作用之前被拒绝。

保留的受控 npm 发布路径与已退役的普通 action/evidence 路径分开。Guard 只保护它实际路由的发布操作。git tag 与 GitHub Release 没有 Guard 自有路由；要求它们的契约会报告 release_operation_unrouted，不会假装宿主命令已受保护。复合 runner 是不透明边界，/context-guard release 会报告精确覆盖范围。发布仍需用户授权和宿主检查；插件不能控制绕过其路由的进程内调用。

边界

Context Guard 负责完成认证；Goal、Todo、Compaction、continuation、权限和工具执行仍由 DSH 管理。它不是安全沙箱、语义证明系统、token pruning 工具，也不替代这些 DSH 能力。

证据采用有界存储和脱敏处理。Guard 不保存完整 prompt、stdout、文件内容、凭证、Authorization header、URL query value、图片字节或原始 transcript。详见 docs/PRIVACY.md。

与 Codex Context Guard 的关系

本项目最初从 GreenLv/codex-context-guard v0.8.8 移植确定性行为。这个版本只是历史起点，不代表当前兼容程度。

0.4.0 明确对齐了 Codex Context Guard 0.10.0 的共享证据规则：证据必须对应仍未完成的工作，并证明用户实际要求的操作、目标和结果。这只是有边界的行为对齐，不表示两个产品拥有相同功能。

0.7.1 的共享 core/v2 源码和一致性夹具，按 tests/fixtures/conformance/core_v2/UPSTREAM_PIN.json 记录的 Codex Context Guard 精确提交进行字节镜像。这只证明所列文件的源码身份，不证明两个产品功能或运行时完全等价；宿主证据与发布仍分别核验。0.6.x 的 C01–C12 契约和 DSH 自行编写的 v2 候选属于历史阶段。当前对照和限制见 docs/SEMANTIC_COMPATIBILITY.md。

两个项目服务于不同运行时：

• codex-context-guard 是面向 Codex Hook 的 Python 实现，负责 Codex 插件缓存和 Hook 生命周期接入。
• dsh-completion-guard 是独立的 TypeScript 实现，基于 DSH 原生 Session 事件、命令、工具和 Agent 生命周期工作。

两个项目不共享运行时状态、安装器、缓存或发布历史。修复应先进入拥有对应运行时的仓库；只有同一行为确实适用于两侧时，才显式迁移。具体复用与替换边界见 docs/UPSTREAM_BASE.md 和 docs/PORTING_NOTES.md。

npm 下载量历史

累计图分别显示更名前后的 npm 包下载总量，标记 2026-08-29 的更名，并仅在项目增长曲线中合并两者。npm 下载量统计的是 registry 请求，不等于独立用户数或已确认的真实安装人数。

历史从首次公开发布 npm 的 2026-08-26 开始，保留首日真实下载数，不强行归零；纵轴从零起算。日期标签统一居中，按固定天数间隔显示，图注始终保留精确截止日。

每日工作流仅发布至少相隔 12 小时复查一致、且距离当日已有两个 UTC 日历日的数据，另行标明 API 数据可用日期。这是项目的观测规则，不代表 npm 保证数值永不修订。详见源数据。

文档

• CHANGELOG.zh-CN.md — 面向使用者的版本变化。
• docs/ARCHITECTURE.md — 所有权、持久状态和认证管线。
• docs/COMPATIBILITY.md — 支持的 DSH 版本和可认证命令子集。
• docs/LOCAL_ACCEPTANCE.md — 确定性、隔离环境、原生平台和公开包验证范围。
• docs/distribution.md — 已验证的公开分发去向与更名说明。
• docs/PRIVACY.md — 保存的事实、禁止数据和失败行为。
• docs/UPSTREAM_BASE.md — 历史起点与仓库权威边界。
• docs/SEMANTIC_COMPATIBILITY.md — 当前共享行为和已知差异。
• docs/PORTING_NOTES.md — 从 Codex 保留的行为和 DSH 专属替换。

开发

pnpm install --frozen-lockfile
pnpm --dir tests/fixtures/host-composition install --frozen-lockfile
pnpm run test:stats
pnpm run typecheck
pnpm test
pnpm run lint
pnpm run build
pnpm run pack:check

这些命令验证本地源码树与包。CI、原生平台验收、npm 发布、GitHub Release 身份和真实 DSH 环境安装仍是相互独立的证据范围。