# keeper

**Repository Path**: code-me/keeper

## Basic Information

- **Project Name**: keeper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zones — Local Manus Agent

在本地沙箱目录中运行的通用 Agent 应用。后端 FastAPI 实现 AI Agent 运行时（OpenAI 兼容 API 工具调用循环），前端 Vite + React 提供深色三栏交互界面。更多文档见 [docs/SUMMARY.md](docs/SUMMARY.md)。

## 运行方式

1. **配置环境变量**（复制 `backend/.env.example` 为 `backend/.env`）：
  - `OPENAI_API_KEY`：调用 OpenAI 官方时必填。
  - **阿里云百炼**：可使用 `DASHSCOPE_API_KEY` 代替 `OPENAI_API_KEY`（二选一），并将 `OPENAI_BASE_URL` 设为百炼 **OpenAI 兼容模式** 地址（例如北京：`https://dashscope.aliyuncs.com/compatible-mode/v1`），`MODEL` 设为千问模型名（如 `qwen-flash`）。各地域端点见 `backend/.env.example` 注释。
  - `MODEL`：可选，默认 `gpt-4o-mini`。
  - `SANDBOX_ROOT`：可选，沙箱根目录，默认为仓库下的 `sandbox_workspace`。
  - `ZONES_AUTH_JWT_SECRET`：登录 token 签名密钥，建议使用 32 字节以上随机字符串（兼容 `KEEPER_AUTH_JWT_SECRET`）。
  - `ZONES_BOOTSTRAP_TOKEN`：首次初始化 Owner 账号时使用；初始化完成后可移除或轮换（兼容 `KEEPER_BOOTSTRAP_TOKEN`）。
  - `ZONES_TENANT_ISOLATION=1`：启用多租户数据隔离，生产/多人部署建议开启（兼容 `KEEPER_TENANT_ISOLATION`）。
2. **安装后端依赖**：
  ```bash
   cd backend && pip install -r requirements.txt
  ```
3. **启动 API**（默认 `http://127.0.0.1:8766`）：
  ```bash
   cd backend && python -m uvicorn app.main:app --host 127.0.0.1 --port 8766
  ```
4. **前端**（开发时热更新，已配置代理到 8766）：
  ```bash
   cd frontend && npm install && npm run dev
  ```
   浏览器打开 Vite 提示的地址（当前配置为 `http://localhost:5176`）。
5. **仅后端 + 内置前端**：先执行 `cd frontend && npm run build`，再启动 uvicorn，然后访问 `http://127.0.0.1:8766/`。

## 首次初始化与多账号

启动后访问前端，未登录时会进入登录页。首次部署选择「初始化」，填写：

- 租户 ID / 租户名称
- Owner 名称、邮箱、密码
- `.env` 中配置的 `ZONES_BOOTSTRAP_TOKEN`（或旧名 `KEEPER_BOOTSTRAP_TOKEN`）

初始化成功后会创建首个租户和 Owner 账号。后续账号与租户管理在「设置 → 账号与租户」中完成。角色分为：

- `Owner`：管理租户、账号、全部配置和数据。
- `Admin`：管理当前租户内账号与配置，不能管理 Owner 或跨租户。
- `Member`：创建/编辑会话、项目、沙箱文件，并运行 Agent。
- `Viewer`：只读访问会话、项目、沙箱文件和统计视图。

更多配置、接口与迁移说明见 [多租户与账号权限](docs/多租户与账号权限.md)。

## 可选：浏览器工具

无头浏览器工具基于 Playwright Chromium，可用于 Agent 导航、查看页面、提取可见文本、检查元素详情、点击、输入、清空输入框、设置勾选状态、按键、下拉选择、截图和读取 console。安装浏览器内核（体积较大）：

```bash
pip install playwright && playwright install chromium
```

安全默认：浏览器导航仅允许公网 `http/https` URL，拒绝 localhost、私网、回环、链路本地和保留地址。

## 说明

- 会话与消息默认持久化到 SQLite 文件 `.local/sessions.db`（可用环境变量 `SESSIONS_DB` 覆盖路径）；若存在旧版 `.local/sessions.json` 且数据库为空，启动时会自动导入。重启后端后可恢复。
- 开发流程检查见 [开发流程优化指南](docs/development-flow.md)，可运行 `python3 scripts/devflow_check.py plan` 按当前 git 改动生成聚焦验证命令。
- 更多文档（架构设计、功能模块、开发指南等）见 [docs/SUMMARY.md](docs/SUMMARY.md)。