rogerchappel/agentpermit
GitHub: rogerchappel/agentpermit
AgentPermit 是一个确定性的本地策略模拟器，用于在 Agent 工具操作执行前预判每个动作的 allow/warn/deny 结果。
Stars: 0 | Forks: 0
# AgentPermit
AgentPermit 是一个用于 agent 工具权限的本地策略模拟器。向其输入一个提议的操作追踪（action trace）和一个小的策略文件；它会在任何操作运行之前，告诉你哪些操作会被允许、警告或拒绝。
它以其最好的方式显得刻意“无趣”：输入确定性的 JSON，输出确定性的原因，没有遥测，没有托管服务，也不依赖 LLM。
## 安装
```
npm install agentpermit
```
用于本地开发：
```
git clone https://github.com/rogerchappel/agentpermit.git
cd agentpermit
npm install
npm run build
node dist/cli.js --help
```
## 快速开始
```
agentpermit init ./demo
agentpermit check ./demo --format text
agentpermit check ./demo --format json
agentpermit explain ./demo
```
一个 workspace 包含两个文件：
- `agentpermit.policy.json` — 有序的 allow/warn/deny 规则。
- `agentpermit.trace.json` — 来自 agent 或 fixture 的提议操作。
## 示例 trace
```
{
"actions": [
{ "id": "read-prd", "tool": "read", "path": "docs/PRD.md" },
{ "id": "send-status", "tool": "message", "kind": "message.send", "target": "#team" }
]
}
```
## 示例策略
```
{
"version": 1,
"name": "example-agent-workflow",
"defaultEffect": "warn",
"rules": [
{
"id": "allow-doc-reads",
"effect": "allow",
"reason": "Docs are intentionally reviewable context.",
"kinds": ["file.read"],
"paths": ["docs/**", "README.md"]
},
{
"id": "deny-outbound-message",
"effect": "deny",
"reason": "Messages leave the machine and need human approval.",
"tools": ["message"],
"kinds": ["message.send"]
}
]
}
```
## 命令
- `agentpermit init [target]` 写入一个初始策略和 trace。
- `agentpermit check [workspace] --format text|json` 评估一个 trace。
- `agentpermit explain [workspace]` 打印一个 markdown 解释表格。
- `agentpermit report [workspace]` 输出用于自动化的 JSON。
退出代码：
- `0` — 没有 deny 发现。
- `1` — 一个或多个 deny 发现。
- `2` — 无效输入、文件缺失或配置无效。
## 规则匹配
规则可以通过 `tools`、`kinds`、`paths`、`commands`、`urls` 和 `targets` 进行匹配。
模式支持使用 `*` 作为类似单路径段（path segment）的通配符，以及 `**` 用于广泛的全局匹配。如果多个规则匹配，则以最强的效果为准：deny > warn > allow。平局时按规则 ID 排序以保证稳定性。
## 验证
```
npm test
npm run check
npm run build
npm run smoke
bash scripts/validate.sh
node dist/cli.js check fixtures/mixed --format text
```
## 安全性
请参阅 [docs/SAFETY.md](docs/SAFETY.md)。AgentPermit 仅模拟决策；它不会授予权限或执行操作。
## 贡献
欢迎提交小型的、由 fixture 支持的更改。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT
标签：AI代理, GNU通用公共许可证, Homebrew安装, MITM代理, Node.js, Streamlit, 文档结构分析, 暗色界面, 本地工具, 权限控制, 策略引擎, 网络安全挑战, 自动化攻击, 访问控制