LLM 学习工作流（九）：文档、环境变量与最终验证

这一步在做什么

前面 1 到 8 步，主要是在做代码层改造：

• 状态机
• 数据表
• payload
• Edge Function scaffold
• coach 页面
• 学习流接入
• 测验与复盘闭环

Task 9 做的是另一件非常关键的事：

把这条改造链整理成别人能看懂、能运行、能验证的工程成果。

最终涉及的文件主要是：

• README.md
• .env.example
• package.json

为什么这一步重要

很多人做项目时，代码改完就觉得"完成了"。

但真正的工程完成通常还包括：

1. 别人能不能知道怎么启动
2. 别人能不能知道需要哪些环境变量
3. 别人能不能知道哪些能力已经接上、哪些还只是 scaffold
4. 最终验证到底哪些通过了，哪些因为环境缺失还没法做

尤其是 AI 项目，比普通前端项目更需要这些说明，因为它通常同时依赖：

• 前端环境变量
• 后端 secrets
• 平台 CLI
• 模型能力

这一步具体补了什么

1. .env.example

在 .env.example 里补了：

• VITE_AI_FEATURE_ENABLED=true
• 服务端 secrets 的说明注释

这一步的意义是把：

• 前端需要什么
• 服务端需要什么

明确分开。

这对 AI 项目特别重要，因为：

• 前端环境变量会进浏览器
• 服务端 secrets 绝不能进浏览器

2. package.json

在 package.json 里补了：

"test": "node --test tests/*.test.js"

这一步很小，但作用很大。

它把之前"我们知道怎么跑测试"变成了：

• 项目自己告诉别人怎么跑测试

这就是工程可用性的一部分。

3. README.md

README 现在新增了几类内容：

AI 学习教练能力说明

明确说明当前已经打通的内容：

• AI 教练入口
• 学习画像
• AI 计划驱动学习
• AI 测验与复盘
• Edge Function scaffold

AI 本地开发步骤

补充：

• 安装依赖
• 配置 .env
• 启动前端
• 跑测试
• 跑构建

Edge Functions 说明

明确了：

• supabase/functions/learning-workflow 的职责
• 需要的服务端 secrets
• 本地 supabase functions serve 的计划命令

当前验证状态

这部分非常关键：

• 哪些验证已通过
• 哪些验证因为缺 CLI 还没法做

为什么"验证状态"要写进 README

这一步是 Task 9 里最值得学的地方之一。

很多项目的文档会写：

• "运行这个命令"

但不会写：

• "我实际上跑过没有"

这会导致文档看起来像真的，但其实没人确认过。

这次我们明确把验证结果分成两类：

已验证通过

npm run test
npm run build

计划中的完整验证，但当前环境缺工具

supabase db push
supabase functions serve learning-workflow --env-file supabase/.env.local

而且当前阻塞原因也明确记录了：

• 本机没有 supabase CLI

这说明一件事：

真正的验证报告不只是报喜，也要报阻塞。

这一步学到了什么

1. 工程交付不等于代码写完

代码完成只是其中一部分。

真正的交付还要包括：

• 启动说明
• 环境变量说明
• 服务端配置说明
• 验证结果说明

2. AI 项目比普通项目更需要前后端边界说明

因为它通常会同时出现：

• 浏览器变量
• 服务端 secrets
• 第三方模型 key
• 平台运行时

如果不在文档里说清楚，后面几乎一定会有人配错。

3. "能跑"和"我已经验证过能跑"是两回事

这一步把"理论上可以执行"分成了：

• 已执行成功
• 当前环境无法执行

这是很成熟的工程习惯。

4. 阻塞也属于验证结果

supabase db push 和 supabase functions serve 没跑起来，不代表这个阶段没完成。

关键是：

• 你知道为什么没跑起来
• 你把原因明确记录下来

这比假装"应该没问题"更专业。

这一步最终做成了什么

环境变量层

现在项目已经明确区分：

• 前端变量
• 服务端 secrets

脚本层

现在项目已经有统一测试命令：

npm run test

文档层

README 已经能说明：

• AI 学习教练功能是什么
• 本地开发怎么跑
• Edge Function 怎么理解
• 当前验证做到哪一步

这一步你可以自己复现什么

跑测试

npm run test

跑构建

npm run build

检查 CLI 阻塞

supabase db push
supabase functions serve learning-workflow --env-file supabase/.env.local

如果当前机器没装 supabase CLI，就会得到：

supabase: command not found

这正是现在需要在文档里记录下来的真实状态。

这一步你应该学会什么

• 为什么最终交付要包含文档和验证
• 为什么 AI 项目更需要环境变量边界说明
• 为什么验证结果必须区分"已通过"和"被环境阻塞"
• 为什么 README 不只是介绍项目，还要承担交付说明角色

到这里你已经完成了什么

到 Task 9 为止，这个项目已经从一个原始词典/背词应用，逐步完成了：

• AI 工作流状态
• AI 数据持久化
• AI 请求协议
• AI 服务端骨架
• AI 教练页面
• AI 学习入口
• AI 驱动学习流
• AI 测验与复盘闭环
• 文档、环境和验证整理

这意味着你现在已经走完了一条很完整的：

传统前端项目 -> AI 工作流项目

的改造路径。