RunTimeAdmin/domesticoracle
GitHub: RunTimeAdmin/domesticoracle
一款隐私优先的自托管 AI 家庭助手，通过内置的策略引擎、审批队列和加密审计账本，确保 AI 的每一步操作都处于用户控制之下。
Stars: 1 | Forks: 0
# 国内 Oracle
**自托管的 AI 家庭助手，内置治理层。**
Domestic Oracle 是一款开源、隐私优先的 AI 助手，您可以在自己的硬件上运行。它可以记住您的偏好、搜索网络、读写文件、通过 Home Assistant 控制您的智能家居并采取现实世界的行动，但每一个产生后果的操作都会经过一个策略引擎、一个审批队列，以及一个由您拥有和控制的、防篡改的加密审计账本。
[](LICENSE)
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](#testing)
## 为什么选择 Domestic Oracle
大多数 AI 助手只是聊天界面：它们能回答问题，但不能代表您采取行动。能够采取行动的 Agentic AI 助手引发了一个更棘手的问题：**您如何保持控制权？**
Domestic Oracle 通过在 AI 和现实世界之间设置一个强制性的同意层来解决这个问题：
- **在任何产生后果的操作执行之前**，都会评估策略规则
- **任何被策略阻止的操作**都会进入审批队列；由您批准或拒绝
- **每一个操作，无论结果如何**，都会被写入一个哈希链式的、经 Ed25519 签名的审计账本中，您可以独立验证
- **AI 永远无法伪造自己的权限**；内部参与者无法提供所有者标头，外部代理必须提供有效的加密签名
## 核心功能
| 功能 | 含义 |
|---------|--------------|
| **策略引擎** | 可配置的规则：支出限制、时间窗口、操作拒绝、收件人屏蔽 |
| **审批队列** | 任何触发规则的操作都会成为挂起状态；您可以在 Trust Center UI 中批准或拒绝它 |
| **加密审计账本** | Ed25519 签名，SHA-256 哈希链；防篡改且可独立验证 |
| **代理身份与撤销** | 每个参与者都有一个 ID 和密钥对；瞬间撤销访问权限，无需重启 |
| **持久记忆** | 跨所有对话记住您的偏好、日常事务和上下文 |
| **Home Assistant 集成** | 通过同意网关控制灯光、锁、气候以及任何 HA 实体 |
| **MCP server** | 将治理工具暴露为 Model Context Protocol 端点 |
| **密钥轮换** | 在不破坏历史链验证的情况下轮换签名密钥 |
| **来源扫描** | 所有外部内容在 AI 看到之前都会扫描是否存在 prompt 注入信号 |
| **爆炸半径断路器** | 每个参与者每小时和全局每天的操作上限可防止代理失控 |
| **AtomicMail 邮件集成** | 通过受治理的 `@atomicmail.ai` 收件箱发送、回复和阅读电子邮件；每封发送的邮件都会被挂起等待批准 |
## 架构
```
Browser (Next.js 14 + TypeScript)
│
▼
FastAPI gateway (main.py)
│
├── POST /chat → Oracle Agent (LangGraph + Claude Sonnet 4)
│ │
│ ┌──────────┴──────────────┐
│ SAFE tools GUARDED tools
│ web search, files, HA device control,
│ weather, discovery purchases, messages
│ │
│ consent.request_action()
│ ┌──────────┼──────────┐
│ policy ledger approval
│ engine append queue
│ evaluate sign hold/notify
│
└── Trust Center API
/ledger /policies /agents /approvals /keys /mcp
```
同意网关是一个单一瓶颈点：**每个受保护的操作都流经 `consent.request_action()`**，它会按顺序原子性地评估策略、追加到账本中，并决定是执行、挂起还是阻止。
### 技术栈
| 层 | 技术 |
|-------|-----------|
| Agent runtime | LangGraph + [DeerFlow](https://github.com/bytedance/deer-flow) 框架 |
| LLM | Claude Sonnet 4 (通过 Anthropic API) |
| 后端 | FastAPI + Python 3.12 |
| 前端 | Next.js 14 + TypeScript + Tailwind CSS |
| 存储 | SQLite (账本、策略、代理、审批、会话、nonce) |
| 智能家居 | Home Assistant REST API (可选) |
| 密码学 | 通过 Python `cryptography` 库实现的 Ed25519 |
| MCP | Model Context Protocol SSE server |
## 适用人群
**希望在不放弃控制权的情况下拥有强大 AI 助手的家庭用户。** 如果您有 Home Assistant 设置、运行家庭服务器或 NAS，并且希望拥有一个不仅能真正执行操作（控制设备、搜索、记忆、采取行动），而且在未经您知晓的情况下绝不擅自行动的 AI，这就是为您量身定制的。
**构建受治理 AI 系统的开发者。** 同意网关、策略引擎和审计账本都是清晰分离的模块。将它们嵌入到您自己的 Agentic 应用程序中，即可获得可审计性和人在回路控制，而无需重新实现基础设施。
**AI 安全和 AI 治理领域的研究人员和从业者。** Domestic Oracle 是 LLM 代理运行时治理的一个有效参考实现：硬性策略约束、加密问责制以及在每个决策点的人工干预。
## 独特之处
| | Domestic Oracle | 典型的 AI 助手 | 开源 Agent 框架 |
|--|--|--|--|
| **受策略限制的操作** | 是的，严格执行 | 否 | 否 |
| **加密审计追踪** | 是的，哈希链式 Ed25519 签名 | 否 | 否 |
| **人工审批队列** | 是的，内置 UI | 否 | 否 |
| **代理撤销** | 每个参与者，即时生效，无需重启 | 否 | 视情况而定 |
| **Prompt 注入防御** | 对所有外部内容进行来源扫描 | 否 | 否 |
| **自托管/私有化** | 您的硬件，您的数据 | 否 | 是 |
| **Home Assistant 集成** | 是 | 部分 | 否 |
## 前置条件
- Python 3.12+
- Node.js 18+
- [Anthropic API key](https://console.anthropic.com/)
- 在本地克隆的 [DeerFlow 框架](https://github.com/bytedance/deer-flow)
- Home Assistant (可选；如果未配置，则使用模拟家庭环境)
## 快速开始
### 1. 克隆
```
git clone https://github.com/RunTimeAdmin/domesticoracle
cd domesticoracle
```
### 2. 安装 DeerFlow 框架
DeerFlow 提供 LangGraph 代理运行时。从您的本地克隆中安装其框架包：
```
pip install -e "/path/to/deer-flow/backend/packages/harness"
```
### 3. 后端
```
cd backend
cp .env.example .env
# 编辑 .env -- 至少设置 ANTHROPIC_API_KEY
pip install -r requirements.txt
uvicorn main:app --port 8000 --reload
```
首次运行时，后端会打印您的所有者 token：
```
Owner token: 0550d752...
```
复制它；您在运行前端和进行所有者授权的 API 调用时需要用到它。
### 4. 前端
```
cd frontend
cp .env.local.example .env.local
# 将 NEXT_PUBLIC_ORA_OWNER_TOKEN 设置为上面打印的 token
npm install
npm run dev # → http://localhost:3100
```
## 配置
### 环境变量 (`backend/.env`)
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | **是** | 您的 Anthropic API key |
| `ALLOWED_ORIGINS` | 否 | 逗号分隔的 CORS 来源 (默认值: `http://localhost:3100`) |
| `ORA_HA_URL` | 否 | Home Assistant URL (例如 `http://homeassistant.local:8123`) |
| `ORA_HA_TOKEN` | 否 | Home Assistant 长期有效的访问令牌 |
| `ORA_OWNER_TOKEN` | 否 | 在多次重启中固定所有者 token |
| `ORA_MCP_ENABLED` | 否 | 设置为 `false` 以禁用 MCP server (默认值: `true`) |
| `ORA_HTTPS` | 否 | 设置为 `1` 以开启生产环境的 HTTPS cookie 标志 |
| `ORA_ATOMICMAIL_CREDENTIALS_PATH` | 否 | AtomicMail 凭据文件的路径 (默认值: `~/.atomicmail/credentials.json`) |
### 策略执行模式
通过 Trust Center UI 或 `PUT /policy/mode` 进行设置：
| 模式 | 行为 |
|------|-----------|
| `enforced` | 应用规则，根据配置挂起或拒绝操作 **(默认值)** |
| `audit_only` | 允许所有操作，但每个判定仍然会被记录 |
| `permissive` | 允许所有操作，仅进行最少的记录 |
### Agent 模型 (`backend/config.yaml`)
代理模型在 `config.yaml` 中配置。默认值：`claude-sonnet-4-6`。
## 邮件集成 (AtomicMail)
Domestic Oracle 内置了通过 [AtomicMail](https://atomicmail.ai) 进行邮件集成的功能，这是一个基于 [JMAP](https://jmap.io/) (RFC 8620/8621) 构建的、原生支持代理的邮件服务。
### 一次性设置
```
npx --package=@atomicmail/agent-skill atomicmail register --username oracle
```
这将运行工作量证明注册，并将凭据写入 `~/.atomicmail/credentials.json`。Oracle 会在下次启动时自动加载它们。
### 功能说明
| 工具 | 级别 | 功能说明 |
|------|------|-------------|
| `send_email` | GUARDED | 发送电子邮件；根据默认策略挂起等待批准 |
| `reply_to_email` | GUARDED | 根据 ID 回复邮件；挂起等待批准 |
| `read_inbox` | SAFE | 读取最近的收件箱；记录日志但不挂起 |
发出的电子邮件将经过与设备命令和购买相同的同意网关。默认种子策略会阻止所有发出的电子邮件，直到所有者在 Trust Center 中批准每封邮件。您可以通过 `POST /policies` 或 Trust Center UI 添加宽松规则来更改此设置。
### 策略示例：自动允许发送邮件到受信任的地址
```
{
"rule_type": "action_deny",
"params": { "action": "send_email" }
}
```
使用 `time_window` 或 `spend_limit` 变体替换，以允许在特定时间窗口内发送邮件。有关策略 schema，请参阅 [API 参考](#api-reference)。
## Trust Center
Trust Center（UI 右上角的抽屉）是您的实时控制面板：
| 标签页 | 显示内容 |
|-----|--------------|
| **Pending** | 挂起等待您批准的操作，支持一键批准或拒绝 |
| **Ledger** | 包含判定、风险评分、来源和时间戳的每一项操作 |
| **Devices** | 通过 Home Assistant 发现的智能家居设备 |
| **Policies** | 激活的规则；可以自然语言或结构化 JSON 添加新规则 |
| **Agents** | 已注册的参与者及其状态；可瞬间撤销或恢复访问权限 |
| **Keys** | 签名密钥状态、轮换历史记录、离线备份导出 |
## 测试
测试套件涵盖了所有主要的行为契约：
```
tests/
├── test_crypto.py Ed25519 sign/verify, nonce replay, key rotation
├── test_ledger.py Hash chain, anchor, rollback detection
├── test_policy.py Spend limits, time windows, action deny, enforcement modes
├── test_consent.py Gate verdicts, agent identity, approval lifecycle
├── test_provenance.py Injection pattern scanner (6 categories, 26 tests)
├── test_anchor.py External anchor tamper detection
├── test_agent_identity.py Signed agent requests, revocation, replay rejection
├── test_key_rotation.py Cross-rotation chain verification
├── test_sessions.py Session create/validate/revoke/prune
└── test_routes.py HTTP layer via FastAPI TestClient (auth, approvals, policies)
```
```
cd backend
pip install pytest
pytest tests/ -v
# 126 个测试，全部通过
```
## API 参考
`[owner]` 端点需要一个从 `POST /auth/login` 获取的有效 `ora_session` HttpOnly cookie。Oracle 代理无法提供此 cookie；它只能通过同意网关采取行动。
```
POST /auth/login Exchange passphrase for session cookie
POST /auth/logout Revoke session
GET /auth/session Session validity probe
GET /health Liveness + readiness check
GET /ledger Recent audit entries
GET /ledger/verify Hash-chain integrity check
GET /ledger/summary Rolling summary by category
GET /ledger/export Full chain export with keyset (offline verification)
GET /policies Active policies
POST /policies [owner] Add a policy (structured or natural language)
DELETE /policies/{id} [owner] Remove a policy
GET /policy/mode Current enforcement mode
PUT /policy/mode [owner] Change enforcement mode
POST /policy/dryrun Simulate policy evaluation (no side effects)
GET /approvals [owner] Pending held actions
POST /approvals/{id}/resolve[owner] Approve or deny
GET /agents Registered actors
POST /agents/register [owner] Register an external signed agent
POST /agents/{id}/revoke [owner] Block an actor immediately
POST /agents/{id}/restore [owner] Re-enable an actor
GET /devices Home Assistant devices
POST /devices/control [owner] Control a device through the consent gate
GET /keys/status [owner] Signing key info and rotation history
POST /keys/rotate [owner] Generate a new signing key
GET /keys/backup [owner] Export private key hex for offline backup (logged)
GET /mcp/info [owner] MCP server status, tools, and client config
GET /provenance/patterns [owner] Injection pattern registry
POST /chat Stream a reply over Server-Sent Events
GET /history/{user_id} Recent conversation thread
```
## 常见问题解答
**没有 Home Assistant 它能工作吗？**
是的。如果未设置 `ORA_HA_URL`，将使用模拟家庭模块。所有设备控制操作仍将流经同意网关并记录到账本中。
**我可以使用不同的 LLM 吗？**
代理是通过 Anthropic API 调用的 Claude Sonnet 4。DeerFlow 框架通过 `config.yaml` 支持其他模型；有关模型配置格式，请参阅 DeerFlow 的文档。
**如果在操作挂起期间撤销代理，会发生什么？**
身份验证是在网关处检查的，而不是在调度时。如果代理在提交另一个操作之前被撤销，该操作将被拒绝。在撤销之前已经提交到审批队列的操作仍可由所有者批准或拒绝。
**我的数据会发送给 Anthropic 吗？**
为了生成回复，对话内容和工具输入会发送给 Anthropic API。账本条目、策略、会话、代理密钥和审批记录本地存储在 SQLite 中，绝不会离开您的服务器。
**可以多人使用吗？**
当前的身份验证模型是单一所有者（一个密码，一个会话 cookie）。多用户家庭支持已在路线图中。
**加密审计账本是如何工作的？**
追加到账本中的每一个操作都包括：参与者 ID、操作、参数、策略决定、结果和时间戳。该条目会被计算 SHA-256 哈希值，并且该哈希值会链接到前一个条目，然后使用服务器的 Ed25519 私钥对整个条目进行签名。`GET /ledger/verify` 会遍历整个链，如果没有条目被篡改，则返回 `{"valid": true}`。锚点文件提供了一个外部引用，用于检测截断或回滚攻击。
**我可以在不运行服务器的情况下验证账本吗？**
是的。`GET /ledger/export` 返回完整的链和密钥集。`tools/verify_ledger.py` 脚本仅使用导出的 JSON 和标准 Python 库离线验证签名和哈希链接。
**这与 Open Interpreter 或类似项目有什么不同？**
Open Interpreter 和类似工具关注的是能力：赋予 LLM 运行代码和控制计算机的能力。Domestic Oracle 关注的是**受治理的能力**：相同的操作，但带有强制性的策略层、审批队列和加密审计追踪。根据设计（而非约定），每一个操作都会被记录并受策略约束。
**MCP server 的作用是什么？**
内置的 MCP (Model Context Protocol) server 将 Domestic Oracle 的治理工具（账本读取、策略查询、审批解决）作为 MCP 工具暴露出来。任何兼容 MCP 的客户端（如 Claude Desktop 等）都可以连接到它，并直接与治理层进行交互。
## 路线图
- [ ] Docker / 一键设置
- [ ] Telegram 前端
- [ ] 定周期性任务（“每天早上 8 点，总结我的电子邮件”）
- [x] 邮件集成 (AtomicMail JMAP)
- [ ] 日历集成
- [ ] 多用户家庭支持
- [ ] 已发布的 MCP 工具注册表列表
## 许可证
MIT。详见 [LICENSE](LICENSE)。
## 相关项目
- [DeerFlow](https://github.com/bytedance/deer-flow)：为 Oracle 代理提供动力的 LangGraph 代理框架
- [Home Assistant](https://www.home-assistant.io/)：集成的用于设备控制的智能家居平台
- [Model Context Protocol](https://modelcontextprotocol.io/)：内置服务器实现的 MCP 标准
*Domestic Oracle 是一个独立的开源项目。它不隶属于 Anthropic、Home Assistant 或字节跳动。*
标签：AI智能体, AV绕过, FastAPI, LangGraph, Streamlit, 审计日志, 智能家居, 策略引擎, 网络安全挑战, 访问控制, 逆向工具