共同开发任务板

实名分工见团队工作计划。每项任务仍须在 Gitea Issue 中补充预计完成时间、验收记录和关联合并请求。

编号	模块	任务	负责人	状态
T01	前端	验证 Vue 页面启动、补充截图	吉海燕	进行中（生产构建及登录/角色/核心管理流程浏览器联调已通过；账户设置等剩余验收见下文）
T02	后端	验证 FastAPI `/docs`、`/api/health`	范涵宇	已完成自动化/真实 HTTP 验证；待目标 Docker 环境复核
T03	数据库	启动 PostgreSQL 并验证知识入库	范涵宇	已用隔离 PostgreSQL 完成迁移与回归；本机 Docker Compose 验收受阻
T04	文档	明确接口字段、知识来源审核规则	杨星萱	待办
T05	知识库	设计 sources/documents/chunks/version 表	范涵宇	已完成（迁移、发布快照和接口已合入；待 Docker 联调）
T06	检索	实现关键词检索基线	范涵宇	已完成（已核验知识 BM25 与检索历史已合入）
T07	向量	评估 Embedding 并实现 pgvector	范涵宇	已完成（本地模型、精确向量和 RRF 已合入；待真实领域评测）
T08	RAG	集成 LLM 与来源展示	范涵宇	Responses 协议已合入（请求/解析与旧快照兼容已完成；生成模型选型与实际调用延期）
T09	实验	构建可核验问题集及评分规范	杨星萱	待办
T10	工程	补充测试、Alembic、鉴权与部署	范涵宇（主）、全员	进行中（聊天边界修正已合入；知识编辑浏览器复核与采集时间清空修正待审，Docker/HTTPS/部署待验收）

2026-10-15 首次联调记录

已创建本机 backend/.venv（Python 3.12）并安装后端依赖；该目录由 Git 忽略。
已安装前端依赖，npm run build 通过。构建中发现并修复了问答来源 URL 可为 null 时的 TypeScript 类型不一致。
已使用临时 Uvicorn 服务（关闭数据库生命周期初始化）验证 GET /api/health 返回 200 和预期状态数据，验证后服务已关闭。
本机 Docker CLI 已安装，但 Docker Desktop 引擎无法启动，且 WSL 尚未处于可用状态。因此尚未执行 PostgreSQL 容器启动、知识条目新增/读取、默认生命周期启动和浏览器端联调。
后续操作：重启 Windows 后启动 Docker Desktop；确认 docker version 能显示 Server 信息，再在项目根目录运行 docker compose up -d db，随后继续 T02、T03 和 T01 的剩余验收。

2026-10-15 后端阶段 1–2 分支验收

分支：feat/backend-knowledge-management。以下为分支验收结果，须经既定审阅流程合入后再关闭任务；不覆盖前述其他环境的历史记录。

范围	已完成的验证	剩余事项
T02	默认生命周期真实启动 Uvicorn；HTTP `/docs`、健康检查、数据库就绪检查通过	合并请求审阅、团队环境复核
T03	真实 PostgreSQL 16 测试实例完成迁移、知识录入和读取；后端进程重启后数据仍可读取	当前主机 Docker 守护进程未运行，启动需管理员权限；Compose 容器与浏览器端联调待复核
T05（阶段 2 范围）	来源、文档、知识关联、版本、人工审核、软删除和历史快照；验证旧基础表迁移保留数据	`chunks` 和索引版本留到检索阶段；字段与前端、资料负责人共同确认
T10（部分）	Alembic 迁移、并发版本检查、PostgreSQL 自动化测试、启动说明	登录鉴权、限流、生产部署留到后续工程阶段

验证环境：Python 3.11；使用可选 pgserver 启动独立 PostgreSQL 16.2 测试实例并启用 pgvector。该方式用于验证 SQL 和接口，不等同于 Docker 容器验收。

实际命令与结果（在 backend/ 执行）：

ruff check .：通过。
ruff format --check .：通过。
pytest -q：22 passed；依赖库产生一条 TestClient 弃用提示，不影响本轮用例。
覆盖：新库迁移、已有基础表接管、重复升级、阶段 2 降级后基础正文保留、ORM 与迁移结构一致、审核前置条件、正文/来源/文档变更后重新审核、历史快照、软删除引用保护、筛选与分页、并发写入冲突、跨域预检、真实 HTTP 与服务重启持久化。

所有测试正文、来源和审核人均为占位数据，临时数据库不入库。当前问答仍是占位接口，未开展论文对照实验。Issue、合并请求和最终批准结论须补入 Gitea 后按团队规则归档。

2026-10-15 合并后续开发：关键词检索基线

阶段 2 后端功能已通过普通功能分支的 PR #4 合入 dev（合并提交 4d437ca），包含测试客户端依赖修正。旧 AGit PR #2 仍打开，不作为该批功能是否已合入的唯一判据。
从最新 dev 创建 feat/backend-keyword-retrieval，推进 T06 的独立关键词接口与检索记录。T05 的持久化切分/索引版本、T07 的模型评估和向量检索仍待后续实现。
当前主机 Docker 服务仍未运行；本轮继续使用隔离 PostgreSQL 做接口与迁移测试，不把容器或浏览器端联调标记为完成。独立任务 Issue 仍须补齐。
新增检索接口、中文分词和 BM25 基线、有效审核筛选、原文片段、来源与版本、语料指纹及检索历史；前端调用层同步类型与接口，页面接入由前端继续联调。
分支验证：ruff check .、ruff format --check .、pytest -q；本轮 42 项 PostgreSQL/单元/真实 HTTP 测试通过，覆盖手算分数、标题权重、排序复现、审核边界、来源失效、容量拒绝、迁移兼容和服务重启后的检索历史。前端 npm run build 通过，包含新增检索调用类型的检查。全部使用占位资料，不是论文实验结果。

2026-10-16 Issue #5：认证与角色权限

按继续开发的授权，在 feat/backend-auth-sessions 推进 T10 的认证部分；叠加 PR #6（8ac9dca），不等待其合并，不自行批准或合并。PR #6 与本分支分别保持可追踪记录。
实现注册、登录、退出、当前会话、本人资料修改、改密及管理员用户列表；注册拒绝角色字段，知识/来源/文档管理及检索历史均由服务端要求 admin。
新增 0004_auth_sessions，保存 Argon2id 密码哈希、会话摘要与到期/凭据版本、共享认证请求预算；不预置用户，提供本机隐藏密码输入的管理员初始化命令。迁移和回滚保留知识及检索记录。
默认 Secure/HttpOnly/SameSite Cookie；写操作校验明确 Origin 及当前会话 CSRF。改密使所有旧会话失效，退出持久化撤销；参数错误不回显密码。字段、来源、CSRF 和前端交接见认证接口契约。
实际验证：ruff check .、ruff format --check . 通过；pytest -q 70 passed，包含认证、授权、CSRF、输入越权、过期/轮换/撤销、限额、迁移及既有知识/检索回归；真实 HTTP 服务重启验证会话恢复和退出后不再有效。前端 npm run build 通过。
当前仍使用隔离 PostgreSQL 做自动化验证；Docker 容器、前端登录/角色页面及真实浏览器端流程仍待验收。远程 main 的注册原型最低密码提示需要按本契约同步到 15 字符，并接入带 Cookie/CSRF 的调用层。没有宣称已完成前端集成或生产部署。

2026-10-16 T05：持久化 chunks 与索引版本

分支 feat/backend-chunk-index-versions 叠加待审 PR #7（f9827fe），继承 #6；不等待合并继续后端阶段，同时保留各 PR 的审阅记录。
新增 0005_chunk_indexes：版本、原文切分及出处、发布状态单例、逐次发布记录。构建 ready 快照与发布分开，保留字符偏移、内容哈希、知识/来源/文档版本和语料指纹。
知识、来源、文档写入与构建/发布共用数据库行锁；目录修订与实际语料指纹一起决定当前性，旧构建/旧代数拒绝发布。构建或发布失败完整回滚，旧发布指针及历史不丢失。
管理接口统一要求 admin 与写入 CSRF；前端只同步类型和调用层，页面仍待联调。现有关键词基线行为不变，向量、ANN、RRF 与 RAG 未在本阶段实现。
实际验证：ruff check .、ruff format --check . 通过；pytest -q 91 passed（隔离 PostgreSQL 16 + pgvector），包含真实锁竞争、失败构建/发布的数据库约束回滚、迁移保留账号/知识/检索记录、原文重建与来源快照、真实 HTTP 重启后的发布指针和 chunks 持久化。修正了发布时间在 UTC 与数据库时区之间表示不一致的问题，索引接口统一 UTC 输出。前端 npm run build 通过。
完整请求/响应、切分/容量、失效策略及回滚说明见 INDEX_API.md。本阶段仍是有限语料的同步文本快照；Docker/浏览器验收、独立 T05 Issue 补建及后续 Embedding 方案选择仍有待完成。

2026-10-16 T07：合并后的 RRF 混合检索

本地模型评估和向量持久化/精确检索分别经 PR #11/#13 合入 dev；#9/#10 是被替代的旧 AGit 入口。读取已确认合并结果后，从最新 dev 创建 feat/backend-rrf-retrieval，遵循每阶段 PR 合并后才开发下一阶段。
新增公开 chunk 正文 BM25 与 RRF 接口，三种 chunk 模式限定同一文本快照及分类；原条目关键词接口保留独立口径。固定 k=60、等权、每路候选预算，记录两路完整候选排名/原始分数、贡献、模型空间、切分/BM25/分词参数与出处。前端仅同步调用与历史类型。
模型编码在发布锁外，完成后重新检查审核语料、文本/向量代数与空间；两路排序和记录保存受同一事务保护。竞争、模型或写入失败不保存部分混合结果；2000 chunks 容量与原向量阶段一致。没有新增数据库迁移。完整字段、比较口径及回滚见 HYBRID_API.md。
常规测试 pytest -q 180 passed, 1 skipped（真实模型专项须显式启用）；新增 27 项覆盖手算排序/融合、候选截断/缺席/同分、相同粒度及分类、原文、历史、权限、编码期间锁释放和版本竞争、损坏/失效快照、失败回滚与容量。ruff check、ruff format --check 和前端 npm run build 通过。真实模型专项在独立 CPU 环境另执行 1 passed：固定 BGE small 经真实 HTTP 完成向量/混合/关键词 chunk 查询，进程重启后两路候选排名、结果和历史保持一致。首次专项请求因 candidate_k 小于默认 top_k 被按契约拒绝，修正测试请求后通过；未改变该输入约束。
Issue #5 本轮复查无新评论，后端实现已合入，前端登录/CSRF/角色页面及浏览器流程仍待交接；Docker 容器、核验领域语料/问题集、正式模型冻结与领域评测同样未验收。所有新增自动化资料均为合成测试，不作为文旅事实或论文分数。下一阶段须等待本轮 PR 真正合入 dev。

2026-10-16 T08：证据与 OpenAI 兼容请求契约

RRF 经 PR #14 真正合入 dev 并核对 head/merge 祖先关系后，从最新 dev 创建唯一阶段分支 feat/backend-rag-context。用户明确“模型先不急”，随后要求“先以OpenAI通用请求格式进行开发”；本轮完成协议和证据准备，不选择生成模型或发起真实调用。
新增管理员 POST/GET /api/rag/contexts 及详情接口，写操作沿用 Cookie/Origin/CSRF；只接受服务端 chunk 检索记录，复核当前审核语料、文本/向量发布、空间、原文及出处，持久化完整证据、排除原因、提示词版本、请求体与哈希。
OpenAI 兼容 Chat Completions 请求构造支持明确的 model/messages、角色及输出预算字段；纯响应解析校验单候选、结束原因、引用编号和可选 token 用量。截断/拒绝/无引用等不作为有效答案；引用通过只表示结构候选，不表示事实已核验。
新增迁移 0007_rag_contexts，失败写入完整回滚，历史保留当时快照；回滚保留知识、账号、文本/向量发布和检索记录。当前 /api/chat 仍为原占位，准备结果固定 prepared_request/model_called=false。完整协议、字符预算与后续 token/模型边界见 RAG_CONTEXT_API.md。
实际验证：pytest -q 224 passed, 1 skipped；较上一阶段新增 43 项上下文/协议/权限/失效/预算/原文/失败回滚/真实 HTTP 重启用例，另新增 1 项上下文迁移降级保留数据验证。skip 为既有须显式启用的真实 Embedding 用例，本轮未重跑真实模型专项，不沿用旧结果冒充生成模型验证。ruff check、ruff format --check 通过。前端调用层同步，构建在补齐依赖后通过。
PR #16 已合入的认证路由引用了 vue-router，原 package.json/锁文件未声明；本轮补充匹配现有 Vue 3 的 vue-router 4 依赖及锁记录，保留其他依赖原版本和平台元数据。前端 npm run build 通过；浏览器实际 Cookie/CSRF/角色及容器验收仍待完成。
本轮所有测试为协议/合成资料或坐标 fixture，没有真实生成模型请求、质量分数或费用。生成模型选择和服务凭据保持延期，不重复索要；本阶段提交 PR 后等待实际合入，再继续下一项可独立验收的后端任务。

2026-10-16 真实浏览器联调与阶段验收收尾

上下文阶段已通过真正 merged 的替代 PR #23 合入 dev；完整 backend 树及专用 RAG 契约/API 类型与原 #17 一致，通用文档保留集成更新，已记录重放等价依据。旧 #17 打开不阻塞后续阶段。
从最新 dev 创建 test/backend-browser-acceptance，用隔离 PostgreSQL16/pgvector、默认 FastAPI 生命周期、Vite 与真实浏览器走通管理员登录/刷新会话、来源/知识/文档录入、审核、文本与真实 BGE small 向量发布、RRF 原文来源展示，以及普通用户菜单/路由限制和退出。
修正页面联调发现的采集时间缺失、审核/文档导航入口和过期功能说明；后端审核/授权不放宽，不猜测历史资料采集时间。具体路径、HTTP 与浏览器证据分工及合成截图见 BROWSER_ACCEPTANCE.md。
独立 HTTP 检查确认匿名401、普通用户八类管理资源403、缺失CSRF/错误Origin403、退出后401；目录写入使旧发布409，重新发布后恢复真实检索；准备上下文仍为 model_called=false。合成数据和本机运行环境、原始记录、凭据不入库。
该轮验收收尾了T02的真实浏览器API连接、T05知识录入/审核与文本/向量页面核心流程、Issue #5登录/Cookie/CSRF/角色的主要浏览器路径。Docker、HTTPS、多浏览器、浏览器改密及历史元数据修订页面仍待验收；生成模型和领域评测继续延期。本轮 pytest -q backend/tests 224 passed, 1 skipped，ruff check、ruff format --check 和前端 npm run build 均通过；常规 skip 为须显式启用的真实模型专项，本轮另外通过浏览器与独立 HTTP 实际运行了固定 BGE small。

2026-10-16 T07/T10：可复现历史导出

浏览器联调与录入修正经 PR #29 真正合入 dev，已核对 head/merge 都在最新 dev 祖先链；再从最新 dev 创建唯一阶段分支 feat/backend-retrieval-export。
新增管理员/Origin/CSRF 保护的 POST /api/retrieval/exports，按明确 UUID 导出 JSONL，保留四模式原保存的查询、命中、原始分数、两路候选、模型/语料/切分参数、来源和耗时；可选择关联的准备上下文。条目与 chunk 粒度分开，生成模型使用量和费用为未采集，不伪造生成调用或实验分数。
一个 SQL 语句读取历史快照，保留旧版本而不重新检索；导出前完整校验，最多100条检索/100条上下文/8MiB，不静默截断，不返回部分文件。不新增数据库迁移或环境配置。
前端仅增加下载类型与调用层，复用 Cookie/CSRF/错误处理，不新增页面；真实浏览器下载与实验展示留给后续集成。完整字段、摘要核对、复现与回滚见 RETRIEVAL_EXPORT_API.md。
专项测试 30 passed，包括真实 PostgreSQL 并发快照和 HTTP 重启导出；完整回归 254 passed, 1 skipped（skip 为须显式启用的真实 Embedding 专项），ruff check 与 ruff format --check 通过。前端会话下载契约 3 passed，类型与生产构建通过。测试使用合成资料与坐标 fixture，未重跑模型推理或调用生成模型。

2026-10-17 T05/T10：导出与采集时间浏览器复核

导出原实现及显式禁用缓存修正已通过替代 PR #34 真正合入 dev，原 #33 关闭未合并；已核对原 head、当前普通分支 head 与 merge 均包含在最新 dev。导出工作台 #36 与来源生命周期 #38 已合入，再创建唯一阶段分支 test/backend-export-acceptance。
真实浏览器完成匿名回跳/管理员登录、22条历史两页跨页选择、关联准备上下文与实际 JSONL 下载；落盘文件为2条检索/1条上下文，记录区摘要与页面一致，payload 与保存的原始快照一致。本轮没有模型推理。
发现并修正仅改文档备注时采集时间偏移8小时且截断到分钟的问题；回填使用本地时钟，未改时间保留服务端原微秒值，新建不猜测采集时间。最新合入的知识编辑页复用同一修正。文档浏览器保存与历史快照、独立API均复核通过；知识页仅共享函数测试和构建验证。
前端时区6项、会话3项测试与构建通过；后端导出/目录专项49项和ruff检查/格式检查通过。来源/文档版本、引用删除保护、软删除历史及修订后原导出字节不变均经独立HTTP核对。详见 EXPORT_BROWSER_ACCEPTANCE.md。
浏览器原生删除确认交互受工具限制仍待人工复核，不把独立HTTP删除验证当作浏览器结果；Docker/HTTPS/多浏览器/浏览器改密、领域资料与生成调用继续保留待办。

2026-10-17 T08：Responses 协议调整

从最新 dev 创建独立 feat/backend-responses-protocol，协议开发不依赖 PR #44；随后同步了已合入的采集时间/浏览器修正。新准备默认使用 Responses：固定 instructions 与 user input_text、max_output_tokens、非流式 output 解析；模型和真实服务接入继续延期。
新配置明确 protocol/provider_profile；提供 compatible、openai、deepseek、bailian 档案。DeepSeek 省略不受支持的 store，其他档案显式 store=false；百炼限制 temperature 小于2。旧 Chat Completions 参数拒绝，不自动探测、换协议或重试。档案通过离线契约验证，不代表已对真实供应商调用或通过全部模型能力验证。
解析区分 completed/incomplete/refused/failed，reasoning 不充当答案；拒绝工具、异常状态和错误引用。保存实际模型标识及可选输入/输出、缓存/推理 token 用量，不估算费用。字符预算仍不是模型 token 预算。
保留旧准备快照的完整配置、请求体、哈希与 JSONL 字节；两种协议可混合读取/导出。API路径与迁移不变，仍为0007；新请求使用 Responses，旧协议仅用于历史校验。字段、厂商差异、范围和回滚限制见 RAG_CONTEXT_API.md。
本轮 pytest -q backend/tests/test_rag.py backend/tests/test_exports.py 113 passed；完整 pytest -q backend/tests 294 passed, 1 skipped。skip 为显式启用的真实 Embedding 专项，本轮不运行模型。ruff检查/格式检查及前端类型/生产构建通过；未修改页面交互，不宣称新增浏览器验收。
PR #44 合入后同步最新 dev，保留两份阶段记录并解决本文件追加冲突。此次同步后重新执行前端时区6项、会话3项及类型/生产构建，均通过；backend树与此前294项回归时一致，本次未重复运行全量后端测试，也未新增模型调用或浏览器验收。

2026-10-17 T10：检索式聊天边界与后端验收

PR #45 的 head/merge 均已核对进入 dev，再从最新 dev 创建 fix/backend-chat-validation。新合入 PR #46 已实现 /api/chat 的检索式适配，本轮补上后端边界修正和集成验收，不重复实现检索、不接入生成模型。
已复现501字符问题返回500：外层ChatRequest允许2000字符，内层RetrievalRequest只允许500字符。现在两者共用QueryText与输入规范，问题去首尾空白后1–500字符，超长/空白/错误类型/额外字段在HTTP边界返回422，不静默截断，也不写检索历史。
补充有效审核来源筛选、资料修订后重新审核、公开聊天/私有历史权限、历史与导出持久化、容量503及写入409完整回滚验证；真实HTTP重启后检索历史保持一致。Chat仅生成固定检索状态说明，条目级记录不能传给chunk级Responses准备。完整契约见 CHAT_API.md。
专项 pytest -q backend/tests/test_chat.py backend/tests/test_retrieval.py 35 passed；完整 pytest -q backend/tests 312 passed, 1 skipped，skip为显式启用的真实Embedding专项，本轮未运行模型。ruff检查/格式检查、diff检查和最新前端类型/生产构建通过。API路径、响应字段和数据库迁移不变；README/架构文档更正已过期的聊天占位说明。无新增浏览器验收或领域分数。

2026-10-17 T05/T10：知识编辑页实际验收

PR #48 真正合入 dev，head/merge 均已核对为 dev 祖先，再创建唯一当前阶段分支 test/backend-knowledge-edit-acceptance。
真实浏览器完成知识编辑的当地时间回填、只改标题保留微秒、审核回退、空时间草稿保存、明确改时、清空时间与历史展开；独立 HTTP 核对版本、原时间与历史快照不变、旧发布409和缺时间审核422。
修正清空知识时间却静默保留旧值的问题：前端明确发送 null，后端将文档必填时间约束与知识可空时间分开；文档仍拒绝 null，审核、版本和历史保护保留。无迁移或模型调用。
后端目录/索引/导出专项 75 passed、前端时区 6 passed，ruff检查/格式检查、前端类型/生产构建与diff检查通过；没有把此前312项全量结果当作本轮重跑。可复现步骤、合成截图和浏览器/HTTP证据边界见 KNOWLEDGE_EDIT_ACCEPTANCE.md。
本阶段提交后等待真正合入，再继续剩余合理后端工作；原生确认、Docker/HTTPS/多浏览器/改密及领域资料待办保留，生成模型和凭据继续延期。

23 KiB Raw Blame History Unescape Escape