wuyang
141 lines
5.4 KiB
Markdown
141 lines
5.4 KiB
Markdown
# 续想
|
||
|
||
一个“先保存，后理解”的私人 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 与结构化产物；
|
||
- `POST /api/admin/runs/{run_id}/retry`：重新排队一次仍处于错误状态的分析；
|
||
- `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)
|