@mokuyoaxis/agent-guard 0.2.7 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +13 -0
- package/README.md +37 -27
- package/README.zh-CN.md +32 -24
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +326 -0
- package/adapters/mcp/operations.py +33 -3
- package/adapters/mcp/server.py +17 -0
- package/core/cleanup.py +33 -11
- package/core/cleanup_groups.py +329 -0
- package/core/policy.py +20 -3
- package/docs/README.md +38 -13
- package/docs/design/architecture.md +63 -14
- package/docs/design/compatibility.md +121 -5
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +21 -4
- package/docs/guides/mcp.md +202 -11
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +198 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
package/CONTRIBUTING.md
CHANGED
|
@@ -53,6 +53,13 @@ unverified, and whether the result is a local Core/CLI check, a mock-host check,
|
|
|
53
53
|
or real-host evidence. A passing mock must not be described as universal host
|
|
54
54
|
enforcement.
|
|
55
55
|
|
|
56
|
+
The corpus noise regression scans Git-index paths using the current regular
|
|
57
|
+
UTF-8 working-tree files. Tracked modifications and newly staged paths count;
|
|
58
|
+
untracked private experiments are outside this versioned normal corpus.
|
|
59
|
+
Stage intended new files before using this check as a pre-commit gate. Git or
|
|
60
|
+
read errors fail explicitly. This metric does not certify the whole workspace;
|
|
61
|
+
Exfil rules remain active for direct scans of untracked and adversarial files.
|
|
62
|
+
|
|
56
63
|
Review, merge, tagging, GitHub Release, and npm publication are separate
|
|
57
64
|
maintainer decisions. Acceptance of a contribution does not promise a specific
|
|
58
65
|
release date.
|
|
@@ -111,6 +118,12 @@ inconclusive trials. See the [research index](docs/research/README.md).
|
|
|
111
118
|
PR 描述请写明改了什么、验证了什么、哪些路径仍未验证,以及证据属于本地
|
|
112
119
|
Core/CLI、模拟宿主还是真实宿主。模拟测试通过不能写成所有宿主都已强制拦截。
|
|
113
120
|
|
|
121
|
+
正常语料噪声回归以 Git 索引路径为范围,读取当前工作树中的普通 UTF-8 文件。
|
|
122
|
+
已跟踪修改和新增已暂存文件均纳入;未跟踪的私有对抗实验不属于该版本化正常
|
|
123
|
+
语料。新增文件应在明确准备纳入版本管理后暂存,再使用本项提交前检查;Git 或
|
|
124
|
+
读取失败会显式报错。本指标不认证整个工作区,直接扫描未跟踪或对抗文件时
|
|
125
|
+
Exfil 规则仍然生效。
|
|
126
|
+
|
|
114
127
|
审阅、合并、标签、GitHub Release 与 npm 发布是维护者分别作出的决定;贡献被
|
|
115
128
|
接受不代表承诺在某个版本或日期发布。
|
|
116
129
|
|
package/README.md
CHANGED
|
@@ -4,14 +4,15 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.9.md)
|
|
8
8
|
|
|
9
|
-
**
|
|
9
|
+
**Disclosure checks · Recoverable deletion · Agent experiments** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
11
|
-
Agent Guard
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
Agent Guard has three main capabilities: **Exfil-guard** checks text before
|
|
12
|
+
sending it, **Delete-guard** preserves recovery data before supported destructive
|
|
13
|
+
actions, and **Guard-lab** tests agent and host behaviour through controlled
|
|
14
|
+
experiments. A shared Python Core supports the command-line tools and optional
|
|
15
|
+
host adapters.
|
|
15
16
|
|
|
16
17
|
**AI agents setting up this project:** Before changing configuration or writing
|
|
17
18
|
a bridge, read the [integration requirements](adapters/INTEGRATION.md), then
|
|
@@ -23,18 +24,24 @@ Installed Skills or copied configuration alone do not establish protection.
|
|
|
23
24
|
We currently focus on **DSH and Kimi Code** integrations. For other hosts,
|
|
24
25
|
ask the official coding agent to configure Agent Guard locally.
|
|
25
26
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
Version **[0.2.9](docs/releases/release-notes-0.2.9.md)** makes cleanup
|
|
28
|
+
investigation faster: get a bounded directory overview, then measure selected
|
|
29
|
+
scopes through Cleanup Copilot or MCP. Existing plan scans also reuse metadata
|
|
30
|
+
and Git queries. These observations grant no deletion permission; execution
|
|
31
|
+
still requires a separate reviewed plan and confirmation.
|
|
32
|
+
See the [workflow and limits](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029).
|
|
33
|
+
Before installing, verify the exact GitHub release and npm version below.
|
|
29
34
|
|
|
30
|
-
|
|
|
35
|
+
| Main capability | Included functions | Guides |
|
|
31
36
|
|---|---|---|
|
|
32
|
-
| **
|
|
33
|
-
| **Cleanup
|
|
34
|
-
| **
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
37
|
+
| **Exfil-guard** | Check supported credentials and identifying paths; plan and apply redaction; inspect JSON/dotenv structure without displaying scalar values | [Skill and CLI](skills/exfil-guard/SKILL.md) · [Rules](skills/exfil-guard/references/rules.md) · [Safe config view](skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
38
|
+
| **Delete-guard** | Recoverable deletion and supported Git snapshots; Cleanup Copilot plans, directory overview and measurement; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis | [Skill and CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [Deletion limits](docs/guides/deletion-limits.md) · [Recovery and GC](docs/guides/recovery-feedback.md) · [MCP tools](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
|
|
39
|
+
| **Guard-lab** | Four zero-model calibration controls; synthetic markers and declared-channel observation; evidence and observer-health checks; matched guard-off/on comparisons after an effective baseline | [Lab workflow](docs/lab/guard-lab.md) · [Four-control example](docs/lab/blue-team-calibration.md) · [Evidence levels](docs/lab/guard-lab.md#evidence-levels) |
|
|
40
|
+
|
|
41
|
+
Cleanup Copilot, deletion limits and the current MCP tools/doctor belong to
|
|
42
|
+
**Delete-guard**. Core and adapters provide shared infrastructure;
|
|
43
|
+
[recovery-audit](skills/recovery-audit/SKILL.md) supplies an auxiliary workflow
|
|
44
|
+
for reconstructing a workspace and auditing recovery after an incident.
|
|
38
45
|
|
|
39
46
|
A Skill supplies instructions; it does not intercept tool calls. Automatic
|
|
40
47
|
protection depends on an active, compatible host hook and its covered tools.
|
|
@@ -112,28 +119,30 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
|
|
|
112
119
|
|
|
113
120
|
| Version | Status |
|
|
114
121
|
|---|---|
|
|
115
|
-
| [0.2.
|
|
122
|
+
| [0.2.9](docs/releases/release-notes-0.2.9.md) | Current release line; verify exact-version availability below |
|
|
123
|
+
| [0.2.8](docs/releases/release-notes-0.2.8.md) | Earlier release with MCP diagnosis and recovery validation |
|
|
124
|
+
| [0.2.7](docs/releases/release-notes-0.2.7.md) | Earlier release with Cleanup, deletion limits and local MCP tools |
|
|
116
125
|
| [0.2.6](docs/releases/release-notes-0.2.6.md) | Earlier published release with Kimi feedback and host compatibility updates |
|
|
117
126
|
| [0.2.5](docs/releases/release-notes-0.2.5.md) | Earlier stable release |
|
|
118
127
|
| [0.2.4](docs/releases/release-notes-0.2.4.md) | Earlier stable release |
|
|
119
128
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | Opt-in quarantine protection backport; npm `hotfix` |
|
|
120
129
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
|
|
121
130
|
|
|
122
|
-
Before installing 0.2.
|
|
123
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
124
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
131
|
+
Before installing 0.2.9, confirm availability through its exact
|
|
132
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
133
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9).
|
|
125
134
|
A checkout or manifest alone does not establish package availability.
|
|
126
135
|
|
|
127
136
|
If that version is unavailable, use reviewed source or a locally built
|
|
128
|
-
tarball following the [version notes](docs/releases/release-notes-0.2.
|
|
129
|
-
Versioned tests and package checks
|
|
130
|
-
|
|
131
|
-
|
|
137
|
+
tarball following the [version notes](docs/releases/release-notes-0.2.9.md).
|
|
138
|
+
Versioned tests and package checks retain their original checkpoints.
|
|
139
|
+
The [admission limits](docs/guides/deletion-limits.md) introduced in 0.2.7 can
|
|
140
|
+
refuse previously successful deletions and remain in effect in 0.2.9.
|
|
132
141
|
|
|
133
142
|
Once the exact version is available, install to a chosen, stable user-owned prefix:
|
|
134
143
|
|
|
135
144
|
```sh
|
|
136
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
145
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
137
146
|
```
|
|
138
147
|
|
|
139
148
|
The package root is
|
|
@@ -252,7 +261,8 @@ tool paths. Other combinations need their own checks.
|
|
|
252
261
|
| Claude Code | Retained reference; new version validation paused. Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
|
|
253
262
|
| Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. Version 0.2.6 adds 2.3.0 prompt/ACP root-Bash evidence with fixed responses. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
|
|
254
263
|
| DSH | Default deletion paths on 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4. Optional native read and Lab retain their two-version boundaries. [Compatibility](docs/design/dsh-compatibility.md) · [Setup](adapters/dsh/README.md) |
|
|
255
|
-
| Codex
|
|
264
|
+
| Codex | Codex 0.165.0 exercised published 0.2.7 through actual-client and real-model MCP trials. This covers explicit tools; native Shell/editor interception needs separate verification. [MCP evidence and limits](docs/guides/mcp.md#codex-01650-with-published-027) |
|
|
265
|
+
| Other hosts | Use the official coding agent for version-specific local setup; verify blocking before claiming native interception. Explicit Skill/CLI/MCP use remains cooperative without a blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
|
|
256
266
|
|
|
257
267
|
Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
|
|
258
268
|
for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
|
|
@@ -282,7 +292,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
|
|
|
282
292
|
| [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
|
|
283
293
|
| [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
|
|
284
294
|
| [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
|
|
285
|
-
| [0.2.
|
|
295
|
+
| [0.2.9 notes](docs/releases/release-notes-0.2.9.md) | Cleanup inventory, performance and upgrade notes |
|
|
286
296
|
|
|
287
297
|
## Contributing
|
|
288
298
|
|
package/README.zh-CN.md
CHANGED
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.9.md)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
**外发检查 · 可恢复删除 · Agent 验测** · [English](README.md)
|
|
10
10
|
|
|
11
|
-
Agent Guard
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
Agent Guard 提供三大功能:**Exfil-guard** 检查待外发文本,**Delete-guard**
|
|
12
|
+
在受支持的破坏性操作前保留恢复数据,**Guard-lab** 通过受控实验测试 Agent
|
|
13
|
+
和宿主的实际行为。共享 Python Core 支撑命令行工具与可选宿主适配器。
|
|
14
14
|
|
|
15
15
|
**负责接入本项目的 AI agent:** 修改配置或编写桥接前,必须先读取
|
|
16
16
|
[适配要求](adapters/INTEGRATION.md),再阅读
|
|
@@ -21,17 +21,21 @@ Agent Guard 在受支持的删除、覆盖操作前保留恢复数据,检查
|
|
|
21
21
|
目前主要维护 **DSH 和 Kimi Code** 的接入。其他宿主建议交给对应的官方
|
|
22
22
|
编码 Agent 在本地配置。
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
本版 **[0.2.9](docs/releases/release-notes-0.2.9.md)** 改善清理前的盘点体验:先看目录概况,
|
|
25
|
+
再计量指定范围,Cleanup Copilot 和 MCP 都可使用;既有计划扫描也减少了重复的
|
|
26
|
+
文件属性检查和 Git 查询。这些观察不授予删除许可,执行仍需另外生成计划、审阅并确认。
|
|
27
|
+
使用方式见[目录概况与计量](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029)。
|
|
28
|
+
安装前,请通过下方链接核实精确版本的 GitHub Release 与 npm 包是否可用。
|
|
26
29
|
|
|
27
|
-
|
|
|
30
|
+
| 主要功能 | 下属功能 | 对应链接 |
|
|
28
31
|
|---|---|---|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
32
|
+
| **Exfil-guard** | 受支持的凭据与标识路径检测;脱敏计划与执行;不展示标量值的 JSON/dotenv 配置结构视图 | [Skill 与 CLI](skills/exfil-guard/SKILL.md) · [检测规则](skills/exfil-guard/references/rules.md) · [安全配置视图](skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
33
|
+
| **Delete-guard** | 可恢复删除与受支持的 Git 快照;Cleanup Copilot 计划、目录概况与计量;持久预算、速率/重复限制、保护路径与批量确认;事务恢复与手动 GC;可选本地 MCP 工具及接入诊断 | [Skill 与 CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [删除限制](docs/guides/deletion-limits.md) · [恢复与 GC](docs/guides/recovery-feedback.md) · [MCP 工具](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
|
|
34
|
+
| **Guard-lab** | 四项零模型校准对照;合成标记与声明信道观察;证据和观察器健康检查;有效基线成立后的关闭/开启防护配对比较 | [Lab 流程](docs/lab/guard-lab.md) · [四控制示例](docs/lab/blue-team-calibration.md) · [证据等级](docs/lab/guard-lab.md#evidence-levels) |
|
|
35
|
+
|
|
36
|
+
Cleanup Copilot、删除限制以及当前 MCP 工具/doctor 均归属 **Delete-guard**。
|
|
37
|
+
Core 与适配器提供共享基础设施;[recovery-audit](skills/recovery-audit/SKILL.md)
|
|
38
|
+
提供事故后的工作区重建与恢复审计辅助流程。
|
|
35
39
|
|
|
36
40
|
Skill 提供操作纪律,不会自行拦截工具调用。自动保护依赖宿主实际加载了
|
|
37
41
|
兼容 hook,且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的
|
|
@@ -96,26 +100,29 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
96
100
|
|
|
97
101
|
| 版本 | 状态 |
|
|
98
102
|
|---|---|
|
|
99
|
-
| [0.2.
|
|
103
|
+
| [0.2.9](docs/releases/release-notes-0.2.9.md) | 本版;安装前核实下方精确版本渠道 |
|
|
104
|
+
| [0.2.8](docs/releases/release-notes-0.2.8.md) | 较早版本:MCP 接入诊断与恢复验证 |
|
|
105
|
+
| [0.2.7](docs/releases/release-notes-0.2.7.md) | 历史版本,包含 Cleanup、删除限制与本地 MCP 工具 |
|
|
100
106
|
| [0.2.6](docs/releases/release-notes-0.2.6.md) | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
|
|
101
107
|
| [0.2.5](docs/releases/release-notes-0.2.5.md) | 更早稳定版 |
|
|
102
108
|
| [0.2.4](docs/releases/release-notes-0.2.4.md) | 更早稳定版 |
|
|
103
109
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
|
|
104
110
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
|
|
105
111
|
|
|
106
|
-
安装 0.2.
|
|
107
|
-
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
108
|
-
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
112
|
+
安装 0.2.9 前,请通过精确版本的
|
|
113
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)和
|
|
114
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)确认可用性,
|
|
109
115
|
checkout 或 manifest 本身不代表包已可安装。
|
|
110
116
|
|
|
111
|
-
若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.
|
|
112
|
-
源码或本地构建 tarball
|
|
113
|
-
|
|
117
|
+
若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.9.md)使用经复核的
|
|
118
|
+
源码或本地构建 tarball。版本化测试和包核验保留各自检查点。
|
|
119
|
+
自 0.2.7 引入的[准入限制](docs/guides/deletion-limits.md)可能拒绝此前可执行的删除,
|
|
120
|
+
这些限制在 0.2.9 中继续生效。
|
|
114
121
|
|
|
115
122
|
确认精确版本可用后,可安装到用户选定的长期目录:
|
|
116
123
|
|
|
117
124
|
```sh
|
|
118
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
125
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
119
126
|
```
|
|
120
127
|
|
|
121
128
|
包根目录是
|
|
@@ -216,7 +223,8 @@ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
|
|
|
216
223
|
| Claude Code | 保留参考实现,暂缓新版本验收。Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
|
|
217
224
|
| Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。0.2.6 新增 2.3.0 prompt/ACP 根代理 Bash 固定响应证据。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
|
|
218
225
|
| DSH | 默认删除适配覆盖 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4。可选原生 read 与 Lab 保留各自的两版边界。[兼容范围](docs/design/dsh-compatibility.md) · [接入](adapters/dsh/README.md) |
|
|
219
|
-
| Codex
|
|
226
|
+
| Codex | Codex 0.165.0 已通过已发布 0.2.7 的实际客户端与真实模型 MCP 试次。证据覆盖显式工具;原生 Shell/编辑器拦截仍需单独验证。[MCP 证据与限制](docs/guides/mcp.md#codex-01650-with-published-027) |
|
|
227
|
+
| 其他宿主 | 推荐官方 Agent 按当前版本完成本地接入,并验证确实阻止执行后再声明原生拦截。没有阻塞 hook 时,Skill/CLI/MCP 仍属于协作式使用。[适配指南](adapters/INTEGRATION.md) |
|
|
220
228
|
|
|
221
229
|
精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
|
|
222
230
|
`doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
|
|
@@ -244,7 +252,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
|
|
|
244
252
|
| [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
|
|
245
253
|
| [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
|
|
246
254
|
| [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
|
|
247
|
-
| [0.2.
|
|
255
|
+
| [0.2.9 说明](docs/releases/release-notes-0.2.9.md) | 清理盘点、扫描提速与升级说明 |
|
|
248
256
|
|
|
249
257
|
## 参与贡献
|
|
250
258
|
|
package/adapters/INTEGRATION.md
CHANGED
|
@@ -69,6 +69,10 @@ or a public report. If the host contract or version is unclear, mark it
|
|
|
69
69
|
Say `MCP tools only` unless a separate blocking hook has been verified;
|
|
70
70
|
registering tools does not intercept shell, script or editor operations.
|
|
71
71
|
This path adds no force restore, GC execution or model-approved budget reset.
|
|
72
|
+
Version 0.2.9 also offers read-only `cleanup_discover` and
|
|
73
|
+
`cleanup_measure`; published 0.2.8 does not include them. Inspect their
|
|
74
|
+
coverage/size fields and `partial` status rather than treating a successful
|
|
75
|
+
observation as a complete scan or deletion approval.
|
|
72
76
|
|
|
73
77
|
Core `ASK` must reach a real human-approval path or become a refusal for that
|
|
74
78
|
call. It must never silently become allow. Treat malformed payloads and
|
|
@@ -128,9 +132,11 @@ host process. Repeating local probes cannot turn `host_interception` or
|
|
|
128
132
|
work and remaining checks so the next session can continue without repeating
|
|
129
133
|
the setup.
|
|
130
134
|
|
|
131
|
-
`doctor.py
|
|
132
|
-
|
|
133
|
-
|
|
135
|
+
The hook-specific `doctor.py kimi|claude` configuration and local-probe PASS
|
|
136
|
+
states do **not** prove a live host loaded or enforced a hook. The separate
|
|
137
|
+
`doctor.py mcp` checks a selected local service's handshake, tool set and
|
|
138
|
+
read-only state queries; see the [MCP guide](../docs/guides/mcp.md#diagnose-a-local-service-028).
|
|
139
|
+
Do not reuse either kind of PASS as an unknown-host certification.
|
|
134
140
|
The 0.2.6 Kimi doctor also reports optional Stop under `feedback`.
|
|
135
141
|
Its configuration/local probe is separate from PreToolUse, and
|
|
136
142
|
`model_delivery` remains `UNVERIFIED`. A missing Stop is optional; an invalid
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
"""Read-only diagnostics for one explicitly selected local MCP service.
|
|
2
|
+
|
|
3
|
+
Only the selected child interpreter needs the optional SDK. This module is
|
|
4
|
+
stdlib-only so the ordinary doctor and its help remain usable without it.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import json
|
|
9
|
+
import math
|
|
10
|
+
import os
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
import queue
|
|
13
|
+
import shutil
|
|
14
|
+
import subprocess
|
|
15
|
+
import sys
|
|
16
|
+
import tempfile
|
|
17
|
+
import threading
|
|
18
|
+
import time
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
ROOT = Path(__file__).resolve().parents[2]
|
|
22
|
+
SERVER = ROOT / "adapters/mcp/server.py"
|
|
23
|
+
SDK_VERSION = "2.3.0"
|
|
24
|
+
PROTOCOL_VERSION = "2025-06-18"
|
|
25
|
+
TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan", "cleanup_discover", "cleanup_measure"))
|
|
26
|
+
READ_ONLY = ("status", "transactions", "gc_plan")
|
|
27
|
+
READ_ONLY_TOOLS = frozenset(READ_ONLY) | {"cleanup_discover", "cleanup_measure"}
|
|
28
|
+
MAX_MESSAGE_BYTES = 2 * 1024 * 1024
|
|
29
|
+
|
|
30
|
+
PROBLEMS = {
|
|
31
|
+
"MCP_DOCTOR_WORKSPACE": ("Select an existing non-root workspace directory.",
|
|
32
|
+
"Check the requested workspace path before reconnecting."),
|
|
33
|
+
"MCP_DOCTOR_SERVER": ("The selected server script is unavailable.",
|
|
34
|
+
"Select the reviewed agent-guard adapters/mcp/server.py file."),
|
|
35
|
+
"MCP_DOCTOR_PYTHON": ("The selected Python executable could not start.",
|
|
36
|
+
"Check the selected interpreter path and execution permission."),
|
|
37
|
+
"MCP_DOCTOR_SDK_MISSING": ("The optional MCP SDK is not installed in the selected interpreter.",
|
|
38
|
+
"Use a separate environment with adapters/mcp/requirements.txt."),
|
|
39
|
+
"MCP_DOCTOR_SDK_VERSION": ("The selected interpreter has an unsupported MCP SDK version.",
|
|
40
|
+
"Use the pinned SDK from adapters/mcp/requirements.txt."),
|
|
41
|
+
"MCP_DOCTOR_SDK_IMPORT": ("The selected interpreter could not import the MCP SDK dependencies.",
|
|
42
|
+
"Check that the selected SDK environment is complete and runnable."),
|
|
43
|
+
"MCP_DOCTOR_SDK_CHECK": ("The selected interpreter did not complete the SDK check.",
|
|
44
|
+
"Check the interpreter and its installed environment directly."),
|
|
45
|
+
"MCP_DOCTOR_STARTUP": ("The selected service could not start.",
|
|
46
|
+
"Check the reviewed server script and selected interpreter."),
|
|
47
|
+
"MCP_DOCTOR_TIMEOUT": ("The diagnostic deadline expired.",
|
|
48
|
+
"Inspect the failed stage and service startup; reconnect explicitly after investigation."),
|
|
49
|
+
"MCP_DOCTOR_EOF": ("The service closed its protocol output before completing the check.",
|
|
50
|
+
"Inspect the selected service startup and optional SDK environment."),
|
|
51
|
+
"MCP_DOCTOR_PROTOCOL": ("The service returned an invalid or unsupported protocol response.",
|
|
52
|
+
"Use the reviewed agent-guard stdio service; stdout must contain protocol messages only."),
|
|
53
|
+
"MCP_DOCTOR_IDENTITY": ("The service identity or version does not match this installation.",
|
|
54
|
+
"Select a server script from the same agent-guard version as this doctor."),
|
|
55
|
+
"MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match this installation's contract.",
|
|
56
|
+
"Check the selected service version and tool definitions."),
|
|
57
|
+
"MCP_DOCTOR_QUERY": ("A read-only tool returned an unsuccessful or invalid result.",
|
|
58
|
+
"Inspect the failed tool and local recovery state before any mutation."),
|
|
59
|
+
"MCP_DOCTOR_BINDING": ("The service status does not match the requested workspace and quarantine.",
|
|
60
|
+
"Correct the trusted service workspace binding before using its tools."),
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class _Failure(Exception):
|
|
65
|
+
def __init__(self, code):
|
|
66
|
+
self.code = code
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _remaining(deadline):
|
|
70
|
+
remaining = deadline - time.monotonic()
|
|
71
|
+
if remaining <= 0:
|
|
72
|
+
raise _Failure("MCP_DOCTOR_TIMEOUT")
|
|
73
|
+
return remaining
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _environment():
|
|
77
|
+
env = {key: value for key, value in os.environ.items()
|
|
78
|
+
if not key.startswith(("AGENT_GUARD_", "GIT_"))
|
|
79
|
+
and key not in ("PYTHONPATH", "PYTHONHOME")}
|
|
80
|
+
env["PYTHONDONTWRITEBYTECODE"] = "1"
|
|
81
|
+
return env
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _check_sdk(python, deadline, env, diagnostics):
|
|
85
|
+
# Fixed exit codes avoid exposing import exceptions, paths or environment
|
|
86
|
+
# contents. This is a trusted interpreter, not a sandbox for hostile code.
|
|
87
|
+
code = (
|
|
88
|
+
"import importlib.metadata, sys\n"
|
|
89
|
+
"try: version = importlib.metadata.version('mcp')\n"
|
|
90
|
+
"except importlib.metadata.PackageNotFoundError: sys.exit(10)\n"
|
|
91
|
+
"if version != '2.3.0': sys.exit(11)\n"
|
|
92
|
+
"try: import mcp.server, mcp.server.stdio, mcp_types, anyio\n"
|
|
93
|
+
"except (ImportError, OSError): sys.exit(12)\n"
|
|
94
|
+
)
|
|
95
|
+
try:
|
|
96
|
+
child = subprocess.run([python, "-B", "-c", code], cwd=ROOT, env=env,
|
|
97
|
+
stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
|
|
98
|
+
stderr=diagnostics, timeout=_remaining(deadline), shell=False)
|
|
99
|
+
except subprocess.TimeoutExpired:
|
|
100
|
+
raise _Failure("MCP_DOCTOR_TIMEOUT") from None
|
|
101
|
+
except OSError:
|
|
102
|
+
raise _Failure("MCP_DOCTOR_PYTHON") from None
|
|
103
|
+
if child.returncode:
|
|
104
|
+
raise _Failure({10: "MCP_DOCTOR_SDK_MISSING", 11: "MCP_DOCTOR_SDK_VERSION",
|
|
105
|
+
12: "MCP_DOCTOR_SDK_IMPORT"}.get(child.returncode, "MCP_DOCTOR_SDK_CHECK"))
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class _Connection:
|
|
109
|
+
def __init__(self, python, server, workspace, env, deadline, diagnostics):
|
|
110
|
+
self.deadline = deadline
|
|
111
|
+
self.counter = 0
|
|
112
|
+
self.messages = queue.Queue(maxsize=8)
|
|
113
|
+
self.stopped = threading.Event()
|
|
114
|
+
try:
|
|
115
|
+
self.child = subprocess.Popen([python, "-B", str(server), "--workspace", str(workspace)],
|
|
116
|
+
cwd=workspace, env=env, stdin=subprocess.PIPE,
|
|
117
|
+
stdout=subprocess.PIPE, stderr=diagnostics, shell=False)
|
|
118
|
+
except OSError:
|
|
119
|
+
raise _Failure("MCP_DOCTOR_STARTUP") from None
|
|
120
|
+
|
|
121
|
+
def enqueue(value):
|
|
122
|
+
while not self.stopped.is_set():
|
|
123
|
+
try:
|
|
124
|
+
self.messages.put(value, timeout=0.1)
|
|
125
|
+
return
|
|
126
|
+
except queue.Full:
|
|
127
|
+
continue
|
|
128
|
+
|
|
129
|
+
def read():
|
|
130
|
+
while not self.stopped.is_set():
|
|
131
|
+
line = self.child.stdout.readline(MAX_MESSAGE_BYTES + 1)
|
|
132
|
+
if not line:
|
|
133
|
+
enqueue(_Failure("MCP_DOCTOR_EOF"))
|
|
134
|
+
return
|
|
135
|
+
if len(line) > MAX_MESSAGE_BYTES or not line.endswith(b"\n"):
|
|
136
|
+
enqueue(_Failure("MCP_DOCTOR_PROTOCOL"))
|
|
137
|
+
return
|
|
138
|
+
try:
|
|
139
|
+
value = json.loads(line.decode("utf-8"))
|
|
140
|
+
except (UnicodeError, ValueError, RecursionError):
|
|
141
|
+
enqueue(_Failure("MCP_DOCTOR_PROTOCOL"))
|
|
142
|
+
return
|
|
143
|
+
enqueue(value)
|
|
144
|
+
|
|
145
|
+
self.reader = threading.Thread(target=read, daemon=True)
|
|
146
|
+
self.reader.start()
|
|
147
|
+
|
|
148
|
+
def send(self, value):
|
|
149
|
+
_remaining(self.deadline)
|
|
150
|
+
try:
|
|
151
|
+
self.child.stdin.write((json.dumps(value) + "\n").encode("utf-8"))
|
|
152
|
+
self.child.stdin.flush()
|
|
153
|
+
except (OSError, ValueError):
|
|
154
|
+
raise _Failure("MCP_DOCTOR_EOF") from None
|
|
155
|
+
|
|
156
|
+
def request(self, method, params):
|
|
157
|
+
self.counter += 1
|
|
158
|
+
self.send({"jsonrpc": "2.0", "id": self.counter, "method": method, "params": params})
|
|
159
|
+
# The selected service does not need client-side tools, sampling or
|
|
160
|
+
# approval. Notifications may occur but cannot extend the deadline.
|
|
161
|
+
for _ in range(32):
|
|
162
|
+
try:
|
|
163
|
+
value = self.messages.get(timeout=_remaining(self.deadline))
|
|
164
|
+
except queue.Empty:
|
|
165
|
+
raise _Failure("MCP_DOCTOR_TIMEOUT") from None
|
|
166
|
+
if isinstance(value, _Failure):
|
|
167
|
+
raise value
|
|
168
|
+
if not isinstance(value, dict) or value.get("jsonrpc") != "2.0":
|
|
169
|
+
raise _Failure("MCP_DOCTOR_PROTOCOL")
|
|
170
|
+
if "id" not in value and isinstance(value.get("method"), str):
|
|
171
|
+
if value["method"].startswith("notifications/"):
|
|
172
|
+
continue
|
|
173
|
+
if type(value.get("id")) is not int or value["id"] != self.counter or "error" in value:
|
|
174
|
+
raise _Failure("MCP_DOCTOR_PROTOCOL")
|
|
175
|
+
if "method" in value or not isinstance(value.get("result"), dict):
|
|
176
|
+
raise _Failure("MCP_DOCTOR_PROTOCOL")
|
|
177
|
+
return value["result"]
|
|
178
|
+
raise _Failure("MCP_DOCTOR_PROTOCOL")
|
|
179
|
+
|
|
180
|
+
def close(self):
|
|
181
|
+
self.stopped.set()
|
|
182
|
+
try:
|
|
183
|
+
self.child.stdin.close()
|
|
184
|
+
except OSError:
|
|
185
|
+
pass
|
|
186
|
+
try:
|
|
187
|
+
self.child.wait(timeout=1)
|
|
188
|
+
except subprocess.TimeoutExpired:
|
|
189
|
+
self.child.terminate()
|
|
190
|
+
try:
|
|
191
|
+
self.child.wait(timeout=1)
|
|
192
|
+
except subprocess.TimeoutExpired:
|
|
193
|
+
self.child.kill()
|
|
194
|
+
self.child.wait(timeout=1)
|
|
195
|
+
self.child.stdout.close()
|
|
196
|
+
self.reader.join(timeout=1)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _tool_result(value, name):
|
|
200
|
+
content = value.get("structuredContent")
|
|
201
|
+
if (value.get("isError", False) is not False or not isinstance(content, dict)
|
|
202
|
+
or content.get("tool") != name or content.get("ok") is not True
|
|
203
|
+
or type(content.get("exit_code")) is not int or content["exit_code"] != 0
|
|
204
|
+
or not isinstance(content.get("result"), dict)):
|
|
205
|
+
raise _Failure("MCP_DOCTOR_QUERY")
|
|
206
|
+
return content["result"]
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def diagnose(python, workspace, *, server=None, timeout=30):
|
|
210
|
+
"""Check a trusted local service, without returning its private responses.
|
|
211
|
+
|
|
212
|
+
``timeout`` is the total diagnostic deadline (5..120 seconds); closing
|
|
213
|
+
this invocation's own service can add three seconds of process waits
|
|
214
|
+
and one second waiting for its reader thread.
|
|
215
|
+
Python paths retain their symlink spelling so virtual environments work.
|
|
216
|
+
"""
|
|
217
|
+
if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 5 <= timeout <= 120:
|
|
218
|
+
raise ValueError("MCP doctor timeout must be from 5 to 120 seconds")
|
|
219
|
+
python = os.fspath(python)
|
|
220
|
+
if not python or "\0" in python:
|
|
221
|
+
raise ValueError("MCP doctor needs a nonempty interpreter")
|
|
222
|
+
python = os.path.expanduser(python)
|
|
223
|
+
if os.path.dirname(python):
|
|
224
|
+
python = os.path.abspath(python)
|
|
225
|
+
else:
|
|
226
|
+
python = shutil.which(python) or python
|
|
227
|
+
expected_version = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["version"]
|
|
228
|
+
report = {"schema_version": 1, "harness": "mcp", "status": "FAIL", "stage": "workspace",
|
|
229
|
+
"checks": [], "host_connection": "UNVERIFIED", "model_delivery": "UNVERIFIED",
|
|
230
|
+
"host_interception": "UNVERIFIED"}
|
|
231
|
+
stage = "workspace"
|
|
232
|
+
connection = None
|
|
233
|
+
deadline = time.monotonic() + timeout
|
|
234
|
+
with tempfile.TemporaryFile() as diagnostics:
|
|
235
|
+
try:
|
|
236
|
+
try:
|
|
237
|
+
selected = Path(workspace).expanduser().resolve(strict=True)
|
|
238
|
+
valid = selected.is_dir() and selected.parent != selected
|
|
239
|
+
except (OSError, ValueError):
|
|
240
|
+
valid = False
|
|
241
|
+
if not valid:
|
|
242
|
+
raise _Failure("MCP_DOCTOR_WORKSPACE")
|
|
243
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
244
|
+
stage = "server"
|
|
245
|
+
try:
|
|
246
|
+
selected_server = Path(server if server is not None else SERVER).expanduser().absolute()
|
|
247
|
+
valid = selected_server.is_file()
|
|
248
|
+
except (OSError, ValueError):
|
|
249
|
+
valid = False
|
|
250
|
+
if not valid:
|
|
251
|
+
raise _Failure("MCP_DOCTOR_SERVER")
|
|
252
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
253
|
+
env = _environment()
|
|
254
|
+
stage = "sdk"
|
|
255
|
+
_check_sdk(python, deadline, env, diagnostics)
|
|
256
|
+
report["sdk_version"] = SDK_VERSION
|
|
257
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
258
|
+
stage = "initialize"
|
|
259
|
+
connection = _Connection(python, selected_server, selected, env, deadline, diagnostics)
|
|
260
|
+
initialized = connection.request("initialize", {"protocolVersion": PROTOCOL_VERSION,
|
|
261
|
+
"capabilities": {}, "clientInfo": {"name": "agent-guard-doctor", "version": expected_version}})
|
|
262
|
+
identity = initialized.get("serverInfo")
|
|
263
|
+
if (not isinstance(identity, dict) or identity.get("name") != "agent-guard"
|
|
264
|
+
or identity.get("version") != expected_version):
|
|
265
|
+
raise _Failure("MCP_DOCTOR_IDENTITY")
|
|
266
|
+
if initialized.get("protocolVersion") != PROTOCOL_VERSION:
|
|
267
|
+
raise _Failure("MCP_DOCTOR_PROTOCOL")
|
|
268
|
+
connection.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
|
|
269
|
+
report["server"] = {"name": "agent-guard", "version": expected_version,
|
|
270
|
+
"protocol_version": PROTOCOL_VERSION}
|
|
271
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
272
|
+
stage = "tools"
|
|
273
|
+
listing = connection.request("tools/list", {})
|
|
274
|
+
tools = listing.get("tools")
|
|
275
|
+
if (not isinstance(tools, list) or len(tools) != len(TOOLS)
|
|
276
|
+
or any(not isinstance(tool, dict) or not isinstance(tool.get("name"), str) for tool in tools)
|
|
277
|
+
or {tool["name"] for tool in tools} != TOOLS or listing.get("nextCursor") is not None):
|
|
278
|
+
raise _Failure("MCP_DOCTOR_TOOLS")
|
|
279
|
+
for tool in tools:
|
|
280
|
+
annotations = tool.get("annotations")
|
|
281
|
+
if (not isinstance(annotations, dict) or
|
|
282
|
+
annotations.get("readOnlyHint") is not (tool["name"] in READ_ONLY_TOOLS)):
|
|
283
|
+
raise _Failure("MCP_DOCTOR_TOOLS")
|
|
284
|
+
report["tools"] = sorted(TOOLS)
|
|
285
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
286
|
+
for name in READ_ONLY:
|
|
287
|
+
stage = name
|
|
288
|
+
result = _tool_result(connection.request("tools/call", {
|
|
289
|
+
"name": name, "arguments": {"tail": 0} if name == "status" else {}}), name)
|
|
290
|
+
if name == "status":
|
|
291
|
+
if (result.get("workspace") != str(selected)
|
|
292
|
+
or result.get("trash_root") != str(selected / ".agent-trash")):
|
|
293
|
+
raise _Failure("MCP_DOCTOR_BINDING")
|
|
294
|
+
admission = result.get("delete_admission")
|
|
295
|
+
if not isinstance(admission, dict):
|
|
296
|
+
raise _Failure("MCP_DOCTOR_QUERY")
|
|
297
|
+
report["deletion_admission"] = "BLOCKED" if admission.get("status") == "BLOCKED" else "READABLE"
|
|
298
|
+
elif name == "transactions" and not isinstance(result.get("transactions"), list):
|
|
299
|
+
raise _Failure("MCP_DOCTOR_QUERY")
|
|
300
|
+
elif name == "gc_plan" and (result.get("mode") != "plan" or not isinstance(result.get("eligible"), list)):
|
|
301
|
+
raise _Failure("MCP_DOCTOR_QUERY")
|
|
302
|
+
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
303
|
+
report.update(status="PASS", stage="complete", code="MCP_DOCTOR_READY",
|
|
304
|
+
message="The selected local service passed handshake, binding and read-only tool checks.",
|
|
305
|
+
guidance="Inspect the actual client's MCP connection and permissions before using its tools.")
|
|
306
|
+
except _Failure as failure:
|
|
307
|
+
message, guidance = PROBLEMS[failure.code]
|
|
308
|
+
report.update(stage=stage, code=failure.code, message=message, guidance=guidance)
|
|
309
|
+
report["checks"].append({"stage": stage, "status": "FAIL", "code": failure.code})
|
|
310
|
+
finally:
|
|
311
|
+
if connection is not None:
|
|
312
|
+
connection.close()
|
|
313
|
+
diagnostics.flush()
|
|
314
|
+
report["diagnostic_stderr_bytes"] = diagnostics.tell()
|
|
315
|
+
return report
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
def render(report):
|
|
319
|
+
"""Render only fixed report fields; private MCP tool content is absent."""
|
|
320
|
+
lines = [report["status"] + ": " + report["code"], report["message"]]
|
|
321
|
+
lines.extend(" " + check["stage"] + ": " + check["status"] for check in report["checks"])
|
|
322
|
+
if report.get("deletion_admission") == "BLOCKED":
|
|
323
|
+
lines.append("DELETION_ADMISSION: BLOCKED (connection checks do not grant deletion permission)")
|
|
324
|
+
lines.extend([report["guidance"],
|
|
325
|
+
"HOST_CONNECTION: UNVERIFIED; MODEL_DELIVERY: UNVERIFIED; HOST_INTERCEPTION: UNVERIFIED"])
|
|
326
|
+
return "\n".join(lines) + "\n"
|