feat: open source multi-user AI notebook with observability
This commit is contained in:
wuyang
@@ -0,0 +1,134 @@
|
||||
# 续想
|
||||
|
||||
一个“先保存，后理解”的私人 AI 笔记本。
|
||||
|
||||
记录页只呈现用户写下的原文，输入历史像对话一样始终可回看。后台的单一策展
|
||||
Agent 使用 DeepSeek 的思考模式，按需搜索已有想法与轨迹，再给出结构化的“想法位势”
|
||||
提案。Agent 不能直接写数据库；应用只在 schema 和引用完整性校验通过后，用事务提交
|
||||
更新。
|
||||
|
||||
## 设计边界
|
||||
|
||||
- 原始片段先持久化，AI 失败不影响记录。
|
||||
- 捕获流不显示保存状态、AI 标签、关联或建议。
|
||||
- 不要求用户先建页面、取标题、选分类或填写日期。
|
||||
- 成熟度是可回退的连续位势，不是阶段、成绩或任务完成百分比。
|
||||
- 运动、张力和可能动作由模型结合上下文动态生成，不使用固定关卡。
|
||||
- 用户手动校准的位势优先展示，AI 估计仍独立保留。
|
||||
- 每个用户的记录、想法、Session 与 Agent 上下文都以 `user_id` 在 SQL 层隔离。
|
||||
- 管理员能看运行元数据；其他用户的原文与 AI 产物默认脱敏，只有用户主动开启
|
||||
“调试共享”后才可见。
|
||||
- 管理后台保存模型轮次、工具调用、耗时、token、错误和结构化决策产物，但不保存或
|
||||
暴露模型隐藏思维链。
|
||||
|
||||
## 架构
|
||||
|
||||
```text
|
||||
React/Vite ── cookie session ── FastAPI ── SQLite
|
||||
│
|
||||
└── OpenAI Agents SDK
|
||||
└── DeepSeek API
|
||||
```
|
||||
|
||||
核心数据流是：
|
||||
|
||||
1. `POST /api/fragments` 先提交原文并立即返回；
|
||||
2. 后台 Agent 读取当前用户自己的想法上下文；
|
||||
3. Agent 通过 `search_ideas`、`inspect_idea` 工具选择相关材料；
|
||||
4. 应用校验结构化结果后，以事务写入想法、轨迹和片段关联；
|
||||
5. 每次运行同时形成 `agent_runs`、`agent_events`，供管理后台聚合分析。
|
||||
|
||||
## 本地运行
|
||||
|
||||
要求 Python 3.12+、Node.js 22+。
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
cd frontend
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
AUTH_DISABLED=true COOKIE_SECURE=false .venv/bin/uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
开发模式会使用第一位配置用户；没有配置用户时使用临时的“本地开发”管理员身份。
|
||||
|
||||
### 生产身份配置
|
||||
|
||||
生产环境通过 `USERS_FILE` 指向一个只读 JSON 文件。文件只保存 Argon2 哈希，不保存
|
||||
访问密钥明文：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "稳定且唯一的 UUID",
|
||||
"label": "管理员",
|
||||
"role": "admin",
|
||||
"access_key_hash": "$argon2id$...",
|
||||
"debug_sharing": false
|
||||
},
|
||||
{
|
||||
"id": "另一个 UUID",
|
||||
"label": "用户 2",
|
||||
"role": "member",
|
||||
"access_key_hash": "$argon2id$...",
|
||||
"debug_sharing": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
可以用 Argon2 生成哈希：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -c \
|
||||
'from argon2 import PasswordHasher; import getpass; print(PasswordHasher().hash(getpass.getpass("访问密钥: ")))'
|
||||
```
|
||||
|
||||
还需要设置：
|
||||
|
||||
- `SESSION_SECRET_FILE`：Session HMAC 密钥文件；
|
||||
- `DEEPSEEK_API_KEY_FILE`：DeepSeek API 密钥文件；
|
||||
- `DATA_DIR`：SQLite 数据目录，默认 `./data`；
|
||||
- `COOKIE_SECURE=true`：生产 HTTPS 环境必须开启；
|
||||
- `DEEPSEEK_MODEL`：默认 `deepseek-v4-pro`。
|
||||
|
||||
密钥文件应在仓库和镜像之外，以只读挂载注入容器。
|
||||
|
||||
## 多用户与迁移
|
||||
|
||||
启动时会幂等创建/更新配置用户。旧版单用户数据库第一次升级时，已有片段、想法和
|
||||
Session 会归属给配置清单中的第一位管理员；不会把旧数据复制给其他用户。所有列表、
|
||||
详情、手动校准与 Agent 查询都同时带有当前 `user_id` 条件。
|
||||
|
||||
当前是小规模私人部署模型：身份清单来自只读配置文件，而不是开放注册系统。增加、
|
||||
停用或轮换身份应修改清单并重启服务。
|
||||
|
||||
## 管理与分析接口
|
||||
|
||||
以下接口要求管理员 Session：
|
||||
|
||||
- `GET /api/admin/overview`：24 小时汇总、7 日趋势、错误与审计摘要；
|
||||
- `GET /api/admin/users`：用户空间、数据量与调试共享状态；
|
||||
- `GET /api/admin/runs?limit=80`：Agent 运行列表；
|
||||
- `GET /api/admin/runs/{run_id}`：一次运行的事件、工具、token 与结构化产物；
|
||||
- `GET /api/admin/audit?limit=120`：登录、启动、记录、校准等应用审计事件。
|
||||
|
||||
普通用户可调用 `PATCH /api/account/debug-sharing` 控制自己的调试内容是否向管理员
|
||||
开放。管理员始终能看到自己的完整运行；对未开放共享的其他用户，仅返回状态、耗时、
|
||||
token、错误类型等元数据。
|
||||
|
||||
## 测试与镜像
|
||||
|
||||
```bash
|
||||
.venv/bin/pytest
|
||||
cd frontend && npm run build
|
||||
docker build -t note-zero:local .
|
||||
```
|
||||
|
||||
健康检查位于 `GET /health`。生产发布定义见
|
||||
[`deploy/docker-compose.override.yml`](deploy/docker-compose.override.yml)。
|
||||
|
||||
## 许可证
|
||||
|
||||
[MIT](LICENSE)
|
||||
Reference in New Issue
Block a user