# 续想

一个“先保存，后理解”的私人 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)