@mokuyoaxis/agent-guard

dsh plugin --profile web add @mokuyoaxis/agent-guard

AGENT-GUARD






让 AI Agent 的破坏性操作默认可逆。 · [English](README.md)

Agent Guard 在受支持的删除、覆盖操作前保留恢复数据，检查待外发文本中的

敏感信息，并提供 Lab 来测试 Agent 和宿主的实际行为。共享 Python Core

可通过命令行工具或宿主适配器调用。

负责接入本项目的 AI agent： 修改配置或编写桥接前，必须先读取

[适配要求](adapters/INTEGRATION.md)，再阅读

[接入流程](docs/guides/getting-started.md#set-up-a-coding-agent)和对应适配器指南。

确认实际宿主／版本，查阅其官方 hook 文档，完成验证后报告实际覆盖范围。

不能仅凭 Skill 已安装或配置已复制，就告诉用户防护已生效。

目前主要维护 DSH 和 Kimi Code 的接入。其他宿主建议交给对应的官方

编码 Agent 在本地配置。

本文档覆盖 [0.2.7](docs/releases/release-notes-0.2.7.md)，新增 Cleanup 计划、

删除准入限制与可选本地 MCP 工具。安装前请通过下方精确版本渠道确认可用性。

能力 · 能帮助你做什么 · 入口

恢复保护 · 删除前迁移有价值的文件；受支持的 Git 覆盖前快照 tracked 状态；查询和恢复事务 · [delete-guard](skills/delete-guard/SKILL.md)

清理提议（0.2.7） · 扫描候选、分类、大小与实际执行方式；显式选择并确认后交给 safe_delete · [Cleanup Copilot](docs/guides/cleanup-plan.md)

删除限制（0.2.7） · 查询共享保护路径、持久预算、速率／重复限制与大批量确认 · [限制与恢复](docs/guides/deletion-limits.md)

本地 MCP 工具（0.2.7） · 在支持的客户端中调用 safe_delete、普通恢复、事务／状态查询和 GC 预览 · [MCP 接入](docs/guides/mcp.md)

外发检测 · 检测受支持的凭据和本机标识路径；应用脱敏计划或拒绝输出 · [exfil-guard](skills/exfil-guard/SKILL.md)

行为验测 · 校准观察器，验证声明信道的暴露，再比较匹配的关闭／开启防护试次 · [guard-lab](docs/lab/guard-lab.md)

Skill 提供操作纪律，不会自行拦截工具调用。自动保护依赖宿主实际加载了

兼容 hook，且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的

OS 沙箱；实际接入证据和缺口见[能力矩阵](docs/guides/harness-capabilities.md)。

可选本地 MCP 适配器提供显式工具，不会拦截绕过它的操作；其 SDK 单独安装，

不改变 Core 的运行依赖。

<a id="guard-lab-合成蜜罐"></a>

guard-lab：用证据验测行为

guard-lab 是用户控制的实验工具。它在一次性项目中放入非秘密合成标记和

无害诱饵，只观察明确声明的信道。真正的控制器与证据保存在交给受测 Agent 的

夹具之外。

流程分别回答三个问题：

1. 校准：观察器、标记、扫描和证据链是否正常？内建对照不调用模型，

不访问外网。

2. 观察暴露：关闭防护的真实宿主试次是否触发了选定信道？

3. 比较防护：有效基线成立后，匹配的开启防护试次是否减少或阻止了该暴露？

在安装包或源码根目录，从一项零模型对照开始：

lab_run="$(mktemp -d)"
python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json

另三项对照是 mock-positive、mock-injection 和 snapshot-positive。

真实宿主实验前应按 [Lab 指南](docs/lab/guard-lab.md)跑齐四项对照；

安装包也提供 agent-guard-lab 命令。

对照 PASS 只表示仪器校准，不表示模型安全。观察器不健康或证据缺失时为

INCONCLUSIVE；未防护基线安静，不能证明防护有效。配对比较需要匹配相关的

harness／版本／模型、任务、协议及非防护配置。结果只覆盖声明信道，不能扩展

到所有文件读取、外网传输或模型请求。已有

[Kimi](docs/reports/test-report-kimi-guard-lab.md) 与

[DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、

失败和待审状态。

自 RC3 起，包中包含[蓝队研究](docs/research/README.md)、

[去敏实验报告](docs/reports/blue-team-lab-2026-10.md)和

[便携四控制示例](docs/lab/blue-team-calibration.md)，公开来源、发送授权和正常任务效用的

有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进，欢迎 fork、PR

与独立防守复现；失败和未定结果也应保留。

在包含该示例的源码或包根目录，可一次运行现有四种控制：

blue_run="$(mktemp -d)"
python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"

示例不调用模型，摘要只用于仪器校准。

安装与版本选择

Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell；原生桥接和可选采集

工具另有运行要求。

可选 MCP 适配器需要 Python 3.10+，并单独安装[固定版本 SDK](docs/guides/mcp.md)。

版本 · 状态

[0.2.7](docs/releases/release-notes-0.2.7.md) · 本文档对应版本；精确版本的可用性见下方渠道

[0.2.6](docs/releases/release-notes-0.2.6.md) · 历史已发布版本，包含 Kimi 反馈与宿主兼容性更新

[0.2.5](docs/releases/release-notes-0.2.5.md) · 更早稳定版

[0.2.4](docs/releases/release-notes-0.2.4.md) · 更早稳定版

0.2.4-hotfix.1 · 显式选择的回收站保护回补；npm hotfix

[0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) · 已发布预发布版，包含 RC1／RC2 维护；npm rc

安装 0.2.7 前，请通过精确版本的

GitHub Release和

npm 版本页确认可用性，

checkout 或 manifest 本身不代表包已可安装。

若该版本尚不可用，请按[版本说明](docs/releases/release-notes-0.2.7.md)使用经复核的

源码或本地构建 tarball。版本化测试和包核验已单独记录，不能沿用旧 0.2.6 元数据

候选的通过结论。此前可执行的删除可能被新的[准入限制](docs/guides/deletion-limits.md)拒绝。

确认精确版本可用后，可安装到用户选定的长期目录：

npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7

包根目录是

/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard。

必须使用这个带作用域的包名，也可以使用源码 checkout：

git clone https://github.com/mokuyoaxis/agent-guard.git
cd agent-guard

选用已发布的预发布版时，指定 @mokuyoaxis/agent-guard@0.2.5-rc3，对应

GitHub Release与

npm 版本页。

若只需要稳定线的回收站保护修复，可显式选择 @mokuyoaxis/agent-guard@0.2.4-hotfix.1。

这两个通道均不替换稳定版 latest。

[0.2.6](docs/releases/release-notes-0.2.6.md) 在 0.2.5 的基础上补充 Kimi 可选 Stop

恢复反馈、独立 Stop doctor 检查、DSH Lab 预检诊断、DSH 0.2.1-alpha.4 默认删除适配，

以及 Kimi 2.3.0 Bash profile。已有安装需要升级才能取得这些功能，Stop 还需显式配置。

接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)，

历史功能边界见[0.2.6 说明](docs/releases/release-notes-0.2.6.md)。

恢复一次受支持的删除

从要保护的工作区调用你的安装包／源码路径：

python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'

有价值的目标迁入隔离区，manifest 保留准确恢复路径。可证明能够再生成且被

Git 忽略的产物可直接删除。受支持的 Git 覆盖操作先快照 tracked 状态；

hard reset 与 untracked／ignored 内容发生碰撞时拒绝执行。force restore

先保全当前占位版本，再恢复旧版本。错误可能留下部分操作，应先核查返回的

事务 ID、现场文件和状态，再决定后续动作。

0.2.5 明确提示：迁入回收站的数据仍占空间，

GC 需要显式执行，ALLOW_NOOP 不代表未识别命令没有破坏性。

本地状态查询也不能证明宿主已加载防护。见[状态与清理反馈](docs/guides/recovery-feedback.md)。

advisory check.py 和 safe_delete.py --dry-run 保持命令目标不变，但可能写入

隔离区／审

…(truncated)