历阶 Helix · Alpha 冲刺总结随笔

目录

一、项目预期计划与现实进展

1.1 预期计划（七天冲刺）

1.2 现实进展对照

七天冲刺按「规划 → 骨架 → 模型 → 交互与记忆 → 复习 → 检索读入 → 收官联调」推进。实际节奏与计划大体对齐，部分能力出现前移或后移：

Alpha 阶段已可演示的主链路：目标输入 → 检索/读入 → AI 七步分析生成计划 → 甘特排期与打卡 → 天梯层级与阶段测试 → FSRS 复习调度 → 笔记库摘录/文档。登录/访客双模式可用；Key 仅存本机 web/.env.local，未进仓库。

与计划相比仍偏演示态的部分（留给 Beta）：共用正式库与生产部署、登录态额度服务端统一扣减、访客记忆并入正式账号、检索覆盖与正文质量评分规则化、部分健壮性边界（如非法 UUID 返回 500）等。

1.3 项目运行效果（摘自冲刺收官日）

仓库地址（华为云 CodeArts）：
历阶 Helix 代码仓

本地启动（开发环境）：配置 web/.env.local 后，在 web 目录执行 npm run dev（默认 localhost:3000）；FSRS / readers 等独立服务按仓库说明另行启动。

1.3.1 今日面板：任务概览与学习足迹

今日面板展示当天的待办任务、到期复习项和学习足迹统计，左右两栏各自独立滚动，长列表浏览体验流畅。全站日期已对齐真实当天，访客演示种子按相对偏移围绕真实日期排期，每次打开保持新鲜。

1.3.2 任务详情页：掌握状态三按钮

任务详情页提供「未标记 / 还熟 / 还糊」三个手动掌握状态按钮，点击即时切换掌握标签。标记为"还糊"后，独立 py-fsrs 服务会根据间隔重复算法计算下次复习日期，到期那天今日面板会自动展示原因句提醒复习。

1.3.3 甘特图：多计划并排展示与拖拽改期

甘特图支持"全部并排"和"单计划聚焦"两种模式切换，登录态下拖拽条形改期松开鼠标后即时生效，无需刷新页面。复习日卡片由 FSRS 服务端计算，不可拖动改期，提示文案明确。

1.3.4 AI 助手：对话与计划分析入口

AI 助手提供自由对话和新建计划分析两大功能，对话记录按身份持久化（访客用浏览器 id，登录用用户 id），切页后不丢失。导入学习计划时按钮有禁用态和完成卡片反馈，避免连点重复建计划。

1.3.5 笔记库：摘录库 + 我的文档

1.3.6 我的任务

1.3.7 历阶天梯：层级门禁

1.3.8 AI 助手：七步分析流程

1.3.9 Mem0 用户记忆

对话 / 新建计划前按当前这句话向量检索。

1.3.10 正文检索

新建计划时模型只出检索词，服务端用 Tavily 换成真实链接并做存活检查与内容分类，analyze 产出真实链接资源（linkState=ok）。

1.3.11 历史与成就

1.3.12 冲刺燃尽图（收官）

α 冲刺自规划日至 Day7 共七天，收官日剩余任务按计划归零。

二、各成员收获与心得、分工协作、Alpha 工作量比例

2.1 组员分工协作情况

团队先共同完成 Alpha 冲刺任务拆解、接口契约和领域规则确认，再按前端、后端、数据库、AI、FSRS、测试和材料整理分工推进。

• 前端与后端：围绕四个核心视图、任务详情、排期、打卡、改期、阶段核对和复习流程对接接口，统一返回格式、错误处理和状态展示。
• AI 相关工作：按「输入材料—任务—期望输出—禁止项—人工复核」开展；AI 产出经类型检查、代码检查、测试和人工评审后使用。
• FSRS / 数据库 / 阶段核对：开发成员共同核对规则与字段；测试成员按主路径、接口、异常边界和状态回退验证。
• 材料收口：林彩华汇总测试用例、结果、问题清单与评审表；汤文琪整理答辩 PPT；其他成员提供对应模块的功能、技术与测试材料，共同完成最终展示。

每日站立式会议同步「昨天做到哪、卡在哪、今天做什么」，提交前只 add 本次相关文件，rebase 后再推，避免覆盖他人改动或混入本地密钥与临时文件。

2.2 Alpha 阶段工作量比例

本表依据《代码规范、冲刺任务与计划》、Day1–Day7 冲刺内容及补充说明整理。八名成员本次贡献度均为 12.5%。

2.3 各成员冲刺阶段收获与心得

周蔚琳（152401221）

形成了「先核对提交记录，再定位问题」的排错习惯。层级测试表面上像出题逻辑异常，实际阻塞提交的是 useEffect 中同步改状态；自由对话切页丢失也不是模型没记住，而是首帧空列表盖掉了已有记录，且原先用了全局存储键导致身份串数据。图片素材不能只靠亮度去黑，否则会伤到主体细节。不足是前期把「报告里提到的」和「我这次提交带进来的」分得不够快；下一阶段要先写清可改文件与不可动规则，改完浏览器走一遍再推。

刘嘉奕（102400204）

认识到小项目也要靠站会与接口约定才能跑稳：前后端先定字段再开发，提交严格控范围。排错要从数据链路入手——测试是否通过以真实答题记录为准，种子数据不能当作用户数据；按钮点了没反应常是前端没拆开响应包装或没拿到最新快照。技术上接触了首帧渲染、登录/访客分流、FSRS 展示与甘特拖拽改期。不足是前期边界不够细、后期联调偏赶；下一阶段要把自测和联调节奏提前。

柳钰舒（102400205）

端到端链路靠「契约先行、降级优先」：先钉死 types.ts 契约，服务端、Web、落库一次对齐，后面读入与模型对接基本零返工。无 Key、读不出正文、引擎抖动时一律退回检索词、不编造链接、整体不中断。接触了独立 FastAPI 读入服务、trafilatura、PDF/Word/PPT 解析，以及「博查 → Tavily → 仅检索词」降级链。不足是检索覆盖仍不全，网络层问题应更早判断；下一阶段要把覆盖校验与正文质量评分规则化前置。

黄奕（102400203）

体会到「看起来对」和「点下去真的对」差得很远。改期不动、弹窗叠层、右栏滚不动，根因多在响应拆包、状态流转和定位方式。笔记编辑器因方案未先谈清而返工，最终改成 Word 式连续纸面。协作上每次只提交目标文件，推送前 rebase 并核对不覆盖他人。积累了 React 19 hydration、sticky、撤销栈、双模式数据合并和手搓富文本纸面等经验。下一阶段要更早确认交互边界，少堆到最后几天。

郑聪凌（102400309）

一个功能真正完成，不只是接口能返回，还要业务规则、库表、异常处理和界面一致。复习日应由服务端按结果计算，前端不可随意拖改；还熟/还糊、阶段测试、重新做题要分别处理。迁移脚本与表结构不一致、dev 合并冲突，说明初始化、部署和改动范围核对同样重要。Day7 将幂等从进程内缓存升级为 PostgreSQL 持久化。仍需改进的是提前规划联调，避免环境与异常场景挤到后期。

刘锐清（102400304）

跨前后端模块必须先对齐字段口径（复习日、掌握状态、原因句），提交只 add 相关文件。FSRS 问题表面常是标签不对，根因在类型与口径：Python Optional 与 TS nullable 不对齐会直接 500；原因句不区分还熟/还糊会返回错误文案。不足是前期边界不够细，访客本地持久化路径覆盖不全；下一阶段提交前要覆盖登录/访客、服务正常/异常几条路径。

汤文琪（102400305）

环境与第三方依赖也是开发的一部分：Windows 下 pgvector 需自行编译拷贝、包名是 mem0ai、原生模块与 Node 版本要对齐，模型与向量都要改到百炼兼容端点。排错从猜报错改为读库源码并加 [mem0] 日志，定位了 json_object 必须出现字面 "json"、以及 add() 不带 attributedTo 等问题；写入端只喂用户原话，从源头避免助手噪声进记忆。记忆只记用户偏好，计划/分数/复习日仍走系统记录。下一阶段先写清边界再动手。

林彩华（102400303）

功能可用不只是返回 200，还要契约、异常、权限与页面一致。未登录 401 是权限生效，不是故障；合法/非法输入、幂等重放、登录前后状态要分别覆盖。环境上踩过 npm 镜像、原生模块和 Vitest 版本冲突。用 Apifox 执行 5 组 22 条接口用例并回填；靠服务端日志定位 PATCH 405（路径残留查询参数）；页面登录前后对照验证权限闭环；为 http / views / fsrs 补 13 个单元测试并全部通过。不足是前期对「预期行为 vs 缺陷」判断偏慢，用例边跑边补。

三、对下阶段展望与答辩 PPT

3.1 下阶段展望（Beta）

下阶段把 α 冲刺攒下的技术债清零，让系统从演示态走向真实可用：

1. 完善登录态和数据体系
   统一计次口径，让服务端扣减并联动刷新；笔记库按账号隔离；补齐 guest 记忆并入真实用户 id 的合并逻辑。

2. 完善检索和正文读入
   检索词生成与相似词合并、同 host 去重、死链重试与降级链完善；持续保障正文质量，让学习者拿到尽量完整、可核验的资料。

3. 打磨复习闭环
   跟进 py-fsrs 协议，明确服务异常时掌握标记的兜底边界，让复习节奏真正贴合用户。

4. 部署与稳定性
   登录注册、共用数据库和正式环境部署作为 Beta 主路径；补异常日志、错误监控与性能优化，脱离演示种子后仍稳定可用。

5. 向真实用户场景演进
   功能补齐后组织一轮真实使用（覆盖不同学科目标与学习习惯），根据反馈迭代检索覆盖、复习节奏和交互细节，让历阶经得起真实使用。

3.2 答辩 PPT

答辩 PPT 链接：
阿尔法冲刺答辩PPT.pdf（华为云 CodeArts）

四、回顾 AI 技术员：表现、贡献与下一阶段用法

4.1 实际表现

冲刺中每位成员都引入了 AI 技术员，角色大致固定为三类：

共性结论：AI 适合草稿与初筛，业务拍板与真实回归必须由人完成。

4.2 主要贡献（团队汇总）

• 工程与前端：脚手架与视图组件草稿、夜幕对比度批量提亮、甘特撤销栈与拆包修复、笔记库连续纸面与双模式状态层、层级门禁与访客额度、吉祥物 next/image 接入等。
• AI / 检索 / 记忆：百炼对话与出题接入草稿；检索分类、存活、无 Key 降级与 readers 服务骨架；Mem0 接入、门控与噪声清理方案初稿。
• FSRS / 后端：py-fsrs 适配、原因句与掌握标记修复、迁移字段补齐、幂等键数据库化、HTTP 回归用例初稿。
• 测试与文档：Vitest 用例初稿与别名隔离；接口结果回填；站会正文、问题清单、提交备注整理，减少重复文书时间。

4.3 存在的不足

• 易沿用旧逻辑或凭印象生成（状态口径、还熟/还糊同套处理、跳过写成答题等），必须人工对照说明书与数据库。
• 跨文件/跨服务链路常只改一处，需人把 Python 服务、适配层、业务层、前端串起来核对。
• 会顺着测试报告改别人正在改的文件；或把工具默认校验（如 401 应 200）当成缺陷。
• 对第三方真实返回结构、网络/环境根因判断不准；生成测试文件 ≠ 测试已通过。
• 不能替代业务判断、Git 文件清单决策，也不能替代浏览器与真实链路回归。

4.4 下一阶段如何更好地利用 AI

1. 先讲清再写：接口字段、边界条件、可改文件、禁止项、期望结果写进提示；领域红线（不编造链接、复习日服务端计算、Key 不进仓库等）固定为输入约束。
2. AI 出草稿、人来复核：必跑类型检查与 lint，再浏览器/HTTP 回归；关键规则对照说明书与落库数据。
3. 跨层改动先列清单：改一个字段时先列出服务端、适配层、业务层、前端所有关联点，再分步改。
4. 重复活交给 AI：样板代码、简单单测、报错初筛、变更记录与文档整理；人把时间留给架构、联调、规则与验收。
5. 统一团队用法：共用代码规范与提示词模板；提交前按自检清单（登录/访客、服务正常/异常等）过一遍，人确认后再推。

五、小结

Alpha 冲刺七天，历阶 Helix 从规范与契约走到可演示闭环：模型起草、检索读入、排期打卡、天梯测试、FSRS 复习与笔记库均已接通，燃尽图收官归零。差距主要在「演示可用 → 生产可用」：部署、额度与记忆并入口径、检索质量规则、异常健壮性仍待 Beta 清零。八人分工协作、贡献度均等；AI 技术员显著提高了实现与自检效率，但始终服从人的规则与验收。下一阶段按展望推进，并以答辩 PPT 呈现 α 过程与结果。