项目代号：OCBridge · 配套仓库：Amor122/opencode_chat
# 完整项目的 github 代码仓库
git clone git@github.com:Amor122/opencode_chat.git
本项目使用 FastAPI 后端 + SQLite 数据库 + 纯前端三件套（HTML/CSS/JS），把
opencode serve封装成一个多用户、带权限、可流式聊天的网页工具。
0.1 背景与定位
opencode 是一款终端里的 AI 编程助手。它通过 opencode serve 启动一个 HTTP 服务，把"让 AI 干活"变成一套标准的 REST 接口 + 实时事件流（SSE），从而可以被任何会写 HTTP 请求的程序调用。
本项目在这之上做了一层"网关"：
浏览器（用户聊天界面）
│ REST + SSE
▼
FastAPI 后端（OCBridge） ──► SQLite（用户/项目/会话元数据）
│ REST + SSE
▼
opencode serve（AI 后端，运行在 WSL 里）
- 用户无需接触任何 opencode 配置，只面对一个网页对话框。
- 管理员配置"项目"（指向哪台 opencode、端口、可选账号密码），普通用户注册后选择项目即可开聊。
- 项目 不引入前端框架，前端为纯静态三件套，无构建步骤。
0.2 功能清单
- 登录 / 注册：注册时选择所属项目
- 聊天主界面（豆包风格）：
- 左侧历史会话列表，支持新建 / 置顶 / 删除 / 搜索
- 流式打字机效果的 AI 回复、Markdown 渲染、代码高亮、推理过程折叠、工具调用展示
- 顶部锚点侧边栏，点击跳转到任意一次用户输入的位置
- 撤回消息与恢复撤回
- 管理后台：
- 项目管理（增删改查 opencode 后端连接）
- 导航链接配置（顶部菜单按钮）
- 用户管理（封禁 / 重置密码 / 查看对话记录）
- 操作日志（对话、撤回、恢复全记录）
0.3 技术选型
| 层 | 选型 | 理由 |
|---|---|---|
| 后端框架 | FastAPI | 原生 async、SSE 流式响应、依赖注入、自动校验 |
| 数据库 | SQLite + aiosqlite | 单文件、零运维、异步驱动，本项目的量级够用 |
| 认证 | JWT（python-jose）+ bcrypt | 无状态；密码用 bcrypt 安全哈希 |
| HTTP 客户端 | httpx | 同时提供 AsyncClient 与 SSE 流式读取 |
| 前端 | 原生 HTML/CSS/JS | 无构建步骤、无框架黑盒；marked + highlight.js + DOMPurify 渲染 Markdown |
| AI 后端 | opencode serve（WSL） | 提供 REST + SSE 能力 |
0.4 架构图
┌─────────────────────────────── 浏览器 ───────────────────────────────┐
│ index.html (SPA) │
│ ├─ api.js 所有 REST 调用 + SSE 流解析 │
│ ├─ app.js 路由 (hash) 与视图切换 │
│ ├─ chat.js 聊天页：会话列表/消息渲染/流式接收/撤回/锚点 │
│ └─ admin.js 管理后台：项目/导航/用户/日志 │
└──────────────────────────────┬────────────────────────────────────────┘
│ Cookie(JWT) / REST / SSE
┌──────────────────────────────▼────────────────────────────────────────┐
│ FastAPI (app/) │
│ ├─ main.py 应用装配、路由挂载、SPA 静态托管 │
│ ├─ config.py 环境变量配置 │
│ ├─ database.py INIT_SQL 表结构 + get_db 依赖 │
│ ├─ auth.py bcrypt + JWT + require_auth / require_admin │
│ ├─ schemas.py Pydantic 请求/响应模型 │
│ ├─ helpers.py 日志 / 项目 / 会话辅助函数 │
│ ├─ opencode_client.py ── 连接 opencode 的核心（REST + SSE 并发） │
│ └─ routes/ public / auth / admin / chat / logs │
└──────────────────────────────┬────────────────────────────────────────┘
│ httpx (Basic Auth) / REST + SSE
┌──────────────────────────────▼────────────────────────────────────────┐
│ opencode serve (WSL, 默认 4096 端口) │
│ ├─ POST /session 创建会话 │
│ ├─ GET /session/{id}/message 拉取历史消息 │
│ ├─ POST /session/{id}/message 发送消息（阻塞直到回复完成） │
│ ├─ POST /session/{id}/revert 撤回 │
│ ├─ POST /session/{id}/unrevert 恢复 │
│ └─ GET /event SSE 实时事件流 │
└────────────────────────────────────────────────────────────────────────┘
0.5 数据库设计
五张表：
- projects —— opencode 后端连接配置（名称、host、port、可选账号密码）
- nav_links —— 每个项目顶部的导航按钮配置
- users —— 用户（密码哈希、管理员标记、封禁标记、所属项目）
- sessions —— 本地会话元数据，
opencode_session_id指向 opencode 里的真实会话 - operation_logs —— 全操作审计日志
关键设计：消息本体不落本地库。对话内容全部存在 opencode 侧，本地只存"会话指针"。这避免了两套消息存储的同步难题。
0.6 文档索引（链接更新至03）
| 编号 | 文档 | 内容 |
|---|---|---|
| 00 | 总体架构与设计 | 架构、选型、数据模型（本页） |
| 01 | 环境准备与 opencode serve 启动 | WSL 环境、安装 opencode、启动 serve、验证健康检查 |
| 02 | 认识 opencode API | doc.json + curl 摸清 REST 与 SSE 接口 |
| 03 | 后端骨架与配置 | FastAPI 目录结构、config、main、run.py、requirements |
| 04 | 数据库设计与初始化 | 建表、种子数据（默认管理员 + 测试项目） |
| 05 | 认证与权限 | bcrypt 密码、JWT 签发校验、Cookie、require_auth/admin |
| 06 | 项目管理与用户管理 | 管理员端：项目 CRUD、导航链接、用户封禁/重置密码、日志 |
| 07 | 认识 opencode 客户端 | httpx 封装：会话/消息/撤回/事件流 |
| 08 | SSE 流式对话 | 并发 POST + SSE、完成信号判定、messageID 坑 |
| 09 | 对话路由层 | 会话增删改查、发送、撤回接口 + StreamingResponse |
| 10 | 前端基础：SPA 与 API 封装 | index.html、hash 路由、api.js、登录注册 |
| 11 | 前端聊天界面 | 会话侧栏、消息渲染、Markdown/代码高亮 |
| 12 | 前端流式接收与交互 | 打字机、停止、撤回/恢复、锚点侧栏 |
| 13 | 管理后台前端 | 项目/导航/用户/日志面板 |
| 14 | 安全加固与生产部署 | 权限隔离、密钥管理、进程守护、常见坑 |
| 15 | 数据库迁移：SQLite 到 MongoDB/MySQL | 目标库设计、访问层改造、数据迁移 |
0.7 运行环境要求
- 一台能跑 WSL 的 Windows（或 Linux/Mac，WSL 只是本项目演示环境）
- Python 3.10+
- 已安装 opencode 命令行工具（用于
opencode serve）
详细安装步骤见 01 · 环境准备与 opencode serve 启动。
