内容
# AgentOps Guardian MCP
## 项目总结
赛道：商务智能代理
问题：AI 编码代理可能会做出有风险的本地更改，而不进行回滚。
解决方案：MCP 安全代理，审查操作，创建检查点，并恢复工作流状态。
演示：`guardian_run_workflow` 阻止不安全的写入，创建检查点，`guardian_restore_workflow` 恢复文件。
课程概念：MCP、代理循环、技能/规则、安全防护栏。
按需安全代理，用于 AI 编码工作流。
AgentOps Guardian MCP 是一个本地优先的模型上下文协议服务器，帮助开发人员检查 AI 代理工作空间，审查有风险的操作，创建回滚检查点，并在 AI 编码工作流出现问题时恢复文件。
该项目是为 **商务智能代理** 赛道设计的：它降低了在实际开发团队中使用 AI 编码代理的运营成本。
---
## 主要功能
- **一键代理工作流：** `guardian_run_workflow` 计划、检查、评分、审查提议的操作，创建检查点，持久化紧凑的工作流状态，并返回紧凑的决策。
- **工作流回滚：** `guardian_restore_workflow` 恢复由保存的 Guardian 工作流检查的所有文件。
- **备份优先：** `safe_checkpoint`、`restore_latest` 和 `prepare_safe_edit` 在进行风险编辑之前保留直接恢复工具。
- **代理/MCP 检查：** `inspect_agent_environment_components` 报告本地代理、MCP 服务器、技能、插件、钩子、模型提供商和应用程序集成。
- **默认廉价：** 紧凑的输出、短内存检查器缓存、无后台守护进程、无持续日志记录和无自动令牌密集型摘要。
- **安全审查：** 确定性检查标记 shell 执行、无批准的文件写入、破坏性命令、发布命令和类似机密的操作。
---
## 架构
主要循环是：
```text
提议的操作
-> guardian_run_workflow
-> 计划
-> 检查代理/MCP 环境
-> 评分和分类风险
-> 审查提议的操作
-> 创建检查点
-> 持久化工作流状态
-> 返回决策和下一步操作
```
如果结果错误：
```text
guardian_restore_workflow(workflowId)
-> 读取 .agentops/workflows/<workflowId>.json
-> 恢复所有成功的检查点
```
查看 [docs/architecture.md](docs/architecture.md) 获取详细信息。
---
## 设置
安装依赖并构建：
```bash
npm install
npm run build
```
运行检查：
```bash
npm run check
npm test
```
启动 MCP 服务器：
```bash
npm start
```
---
## MCP 配置示例
使用内置的 JavaScript 入口点：
```json
{
"mcpServers": {
"agentops-guardian": {
"command": "node",
"args": ["C:/absolute/path/to/agentops-guardian-mcp/dist/index.js"]
}
}
}
```
在 Windows 上，请使用绝对路径，并在 MCP 主机需要 JSON 转义时转义反斜杠。
---
## 主要工具
- `guardian_run_workflow` — 顶级代理工作流。
- `guardian_restore_workflow` — 从工作流中恢复所有检查点文件。
- `safe_checkpoint` — 快速备份一个文件。
- `restore_latest` — 恢复一个文件的最新检查点。
- `prepare_safe_edit` — 审查编辑并检查目标文件。
- `inspect_agent_environment_components` — 检查本地代理/MCP 组件。
- `score_agent_surface` — 本地代理表面的紧凑风险评分。
- `triage_guardian_findings` — 将发现结果分组为必须修复、审查、信息和忽略的桶。
- `review_agent_action_plan` — 提议操作的确定性安全审查。
---
## 演示
运行确定性工作流演示：
```bash
npm run build
npm run demo:workflow
```
演示创建一个测试文件，提议一个有风险的 shell 操作，运行 Guardian 工作流，创建检查点，持久化工作流状态，并返回 `needs_user_approval` 而不是执行命令。
有关实时 MCP 测试证据，请参阅 [docs/live-mcp-test.md](docs/live-mcp-test.md)。
---
## 项目材料
- [视频脚本](docs/video-script.md)
- [实时 MCP 测试](docs/live-mcp-test.md)
- [架构](docs/architecture.md)
- [工具审计](docs/tool-audit.md)
- [草稿](WRITEUP_DRAFT.md)
- [提交检查清单](TODO_CAPSTONE.md)
- [截图检查清单](docs/screenshots/README.md)
---
## 代理说明
要使另一个 AI 助手一致地使用 Guardian 工作流，请将相关规则从 [AGENTS.md.example](AGENTS.md.example) 复制到该助手的项目规则文件中。
推荐默认值：
```text
在进行风险文件编辑之前，调用 guardian_run_workflow。
仅在工作流决策就绪时继续。
如果编辑出错，请使用 workflowId 调用 guardian_restore_workflow。
```
---
## 设计原则
- 本地优先。
- 仅按需。
- 在 LLM 解释之前进行确定性检查。
- 默认紧凑输出。
- 无后台监控。
- 无持续事件日志记录。
- 在进行风险操作之前回滚。
---
## 许可证
MIT。查看 [LICENSE](LICENSE)。
