内容
# Imprint — AI 代理审批收件箱
> 为您的 AI 代理提供审批凭证。观察者观察世界，审批收件箱在人类确认之前握住代理的手。
## 快速入门
### Docker Compose（< 5 分钟）
```bash
git clone https://gitlab.com/sekera.radim/impri.git
cd impri
docker compose up
```
在浏览器中打开 **http://localhost:8080**。
首次启动时，服务器会将引导 Admin API 密钥打印到日志中：
```
╔══════════════════════════════════════════════════════╗
║ IMPRI — 首次启动引导 ║
╠══════════════════════════════════════════════════════╣
║ 管理员 API 密钥：im_... ║
║ 项目 ID：proj_... ║
║ 安全存储此密钥 — 它不会再次显示。║
╚══════════════════════════════════════════════════════╝
```
复制密钥，粘贴到登录屏幕，即可登录。
### 开发模式（热重载）
**终端 1 — 服务器：**
```bash
cd server
npm install
npm run dev
# 服务器启动在 http://localhost:8484
```
**终端 2 — UI：**
```bash
cd ui
npm install
npm run dev
# UI 启动在 http://localhost:5173
# /v1 请求被代理到 localhost:8484
```
## API 一览
基准 URL：`http://localhost:8484/v1`
认证：`Authorization: Bearer im_<密钥>`
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| POST | `/v1/actions` | 推送新操作以审批 |
| GET | `/v1/actions` | 列出操作（`?status=pending&q=…&kind=…&since=…`） |
| GET | `/v1/actions/:id` | 获取操作详情 + 决策 |
| POST | `/v1/actions/:id/decision` | 批准或拒绝（单个） |
| POST | `/v1/actions/bulk-decision` | 批准或拒绝最多 50 个操作 |
| POST | `/v1/actions/:id/result` | 报告执行结果 |
| GET | `/v1/openapi.json` | OpenAPI 规范 |
### 推送操作（curl 示例）
```bash
curl -X POST http://localhost:8484/v1/actions \
-H "Authorization: Bearer im_..." \
-H "Content-Type: application/json" \
-d '{
"kind": "reddit.comment",
"title": "回复：为什么简历建议如此矛盾？",
"preview": {
"format": "markdown",
"body": "建议冲突是因为..."
},
"target_url": "https://reddit.com/r/jobs/comments/...",
"expires_in": 86400,
"editable": ["preview.body"]
}'
```
## MCP 服务器（Claude 代码 / 代理）
```bash
npx @impri/mcp
# 环境变量：IMPRI_API_KEY=im_... IMPRI_BASE_URL=http://localhost:8484
```
## 项目结构
```
server/ TypeScript + Fastify + SQLite — REST API（端口 8484）
mcp/ MCP 服务器（stdio）— REST API 的薄封装
ui/ Vue 3 + Vuetify — 网页收件箱（端口 5173 开发 / 8080 Docker）
docker/ Dockerfiles（server.Dockerfile）
docs/ 研究，ADRs
```
## 命令行界面
`impri` 命令行界面允许人类从终端管理收件箱 — 批准，拒绝，跟踪待处理操作，添加观察者和管理密钥 — 无需编写任何代码。
```bash
# 构建和安装（本地，预 npm）
cd sdk/typescript && npm install && npm run build
cd ../cli && npm install && npm run build
npm install -g ./cli
# 连接到您的实例
impri init --cloud --signup # 或：impri init（自托管）
# 常用命令
impri inbox # 待处理操作
impri tail # 实时跟踪新操作
impri approve act_abc123
impri watch add github-releases --param owner=fastify --param repo=fastify
```
- [命令行界面参考](docs/cli.md)
## 软件开发工具包和集成
> v0.1，预发布。自托管是完整的路径；托管云处于早期测试阶段。
| 包 | 位置 | 语言 |
|---------|----------|----------|
| 命令行界面 | `cli/` | Node 18+ |
| Python 软件开发工具包 | `sdk/python/` | Python 3.10+ |
| TypeScript 软件开发工具包 | `sdk/typescript/` | Node 18+（原生 fetch） |
| MCP 服务器 | `mcp/` / `npx @impri/mcp` | 任意 MCP 客户端 |
```bash
pip install -e sdk/python # Python 软件开发工具包（本地，预 PyPI）
npm install ./sdk/typescript # TypeScript 软件开发工具包（本地，预 npm）
npx @impri/mcp # MCP 服务器（已发布）
```
- [Python 软件开发工具包参考](docs/sdk-python.md)
- [TypeScript 软件开发工具包参考](docs/sdk-typescript.md)
- [集成](docs/integrations.md) — LangChain，OpenAI 代理，CrewAI，n8n，Make，Zapier，webhook 接收器
- [烹饪书](docs/cookbook.md) — 电子邮件审批，SQL 门控，社交帖子，幂等批次，webhook 验证，密钥轮换
## 文档
- **网页文档：** <https://impri.dev/docs>
- [命令行界面参考](docs/cli.md) — 安装，`impri init`，每个命令的示例，配置 + 环境变量优先级
- [快速入门](docs/quickstart.md) — 注册 → 在 < 5 分钟内完成第一个审批操作
- [示例代理](examples/approval-gated-agent.mjs) — 一个完整，无依赖的代理，提出操作，等待审批，然后执行并报告
- [如何为 AI 代理添加人工审批](docs/how-to-add-human-approval-to-an-ai-agent.md)
- [自托管](docs/self-hosting.md) — Docker，环境变量，备份，反向代理
- [Webhook](docs/webhooks.md) — HMAC 验证，重试，轮询回退
- [收件箱 UX 和批量 API](docs/inbox.md) — 键盘快捷键，批量批准/拒绝，搜索/筛选参数，`POST /v1/actions/bulk-decision` 参考
- [观察者预设](docs/watcher-presets.md) — 18 个预制模板（HN，Reddit，GitHub，npm，arXiv，…）；REST + 软件开发工具包 + MCP 使用
- [通知渠道](docs/notifications.md) — Slack，Discord，Telegram，ntfy，电子邮件和通用 webhook；摘要窗口，自动禁用，SSRF 保护
- [Telegram 审批机器人](docs/telegram-approval.md) — 聊天中批准 / 拒绝按钮；设置，安全模型，故障排除
- [审计日志](docs/audit-log.md) — 事件类型，查询 API（`GET /v1/audit`），导出（NDJSON/CSV），保留，安全模型
- [`llms.txt`](docs/llms.txt) — AI 助手的可机器读取索引
> **托管云（测试版）：** 一个托管实例运行在 `app.impri.dev` / `api.impri.dev`。自助注册开放：使用 [app.impri.dev](https://app.impri.dev) 上的 **创建 API 密钥** 按钮创建项目 + 管理员密钥，或 `POST /v1/signup`。这是早期测试阶段，因此自托管仍然是最完整的路径。
## 自托管说明
- SQLite 数据在 Docker 卷（`impri-data`）中持久化。
- 将 `WEBHOOK_SECRET` 环境变量设置为随机字符串以进行 HMAC webhook 签名。
- `BASE_URL` 应该与部署的公共 URL 匹配（用于 inbox_url 链接）。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。自托管完整核心免费；托管云和团队功能是付费产品（参见 `MONETIZATION.md`）。
