初中编程学习小助手

扣子搭建智能体后界面太丑了，就给他挂个前端~Program-helper

初中编程学习小助手

一、为什么不是一个“万能答疑机器人”

初中生学编程，有许多困难：

有的卡在概念——循环、条件、变量到底在干什么；
有的卡在报错——IndentationError 看不懂，代码跑不通就放弃了；
有的卡在选题——想做个小游戏，但不知道从哪下手；
还有一类不卡技术，只是没人陪着一起做。

一个什么都会的AI，对前三类往往给得太快：直接甩一段能跑的代码，学生抄完就走，什么也没留下。

所以我把它拆成了四个角色，根据学生的情况会自动路由：

角色	定位	说话方式
讲解员	讲知识点	打比方、一步步拆，不直接给答案
调试伙伴	陪找 bug	先问”你觉得哪一行不对”，再引导看报错
项目教练	带做小项目	拆步骤、定里程碑，控制难度
小码	同龄学习伙伴	一起吐槽、一起试错

二、令牌安全

受到平台的要求和数据的安全，扣子（Coze）的 PAT 不能写在前端 JS 里。

index.js 里写一行 const TOKEN = "pat_xxx"，推到公开仓库，第二天额度就被别人跑光了。所以整个架构应该这样设计：浏览器永远拿不到令牌。

浏览器  ──POST /api/chat（无令牌）──▶  Vercel Edge Function
                                        │ COZE_PAT 存于环境变量
                                        ▼
                                  扣子 v3 Chat API
                                        │
                                        └─ SSE 流式 ─▶ 边收边透传给浏览器

要点只有三条：

COZE_PAT 只存在平台的 Environment Variables 里，勾成 Secret；
前端只请求同域的 /api/chat，源码、F12、抓包都搜不到 pat_；
COZE_BOT_ID 在服务端写死，别人没法拿你的代理去调别的智能体。

仓库里给了三套代理，按部署习惯挑一个：

文件	平台	说明
`api/chat.js`	Vercel Edge	和页面同域托管，最省事
`worker.js`	Cloudflare Worker	国际线路，需要绑自定义域名
`deno-proxy.ts`	Deno Deploy	国内访问相对稳
`server.js`	本地 / VPS	调试用，强制 IPv4 解析

三、国内网络

因为vercel国内打不开，只能用自己的域名dns过去，用阿里云加一条 coze-api 的 CNAME。

1 2	类型主机记录记录值 CNAME coze-api cname.vercel-dns.com（以 Vercel 页面给的为准）

四、前端页面文件

index.html 是单文件页面（无构建、无框架、无 CDN 依赖），大概 2100 行，做了这些事：

SSE 流式渲染：边收边显示，带”思考中 N 秒 / 已生成 N 秒”的计时
代码块处理：流式输出时会遇到”代码块还没闭合”的半截状态，需要先当普通文本、闭合后再渲染成代码块，并给每块加复制按钮；
历史对话：localStorage 存会话列表，切换时忽略空的助手气泡，恢复后自动滚到底部；
学号固定身份：留空自动生成匿名标识，填了学号就固定下来，方便智能体记住”这是同一个人”；
模式切换：默认走本站代理；也可以在设置里勾”使用我自己的令牌直连扣子”，消耗自己的额度；
临时换代理：不想重新部署时，在网址后面加 ?proxy=https://别的代理 就能切。

主题切换做了亮/暗两套 CSS 变量。

五、错误码速查

调试阶段的几个错误：

提示	原因	处理
错误 4015	智能体没发布到「Agent as API」	扣子 → 发布 → 渠道 → Agent as API
错误 401 / 4100	令牌无效、过期或无权限	重新生成 PAT 并更新平台 Secret
错误 404（代理模式）	`proxyBase` 没配或路径不对	先访问 `/api/health` 自检
Failed to fetch	网络不通、校园网 IPv6 拦截、`workers.dev` 被墙	换网络 / 用 vercel 或自定义域名

六、上线清单

[ ] 吊销所有写进过前端的旧令牌，重新生成；
[ ] 新令牌只进平台 Secret，不进仓库；
[ ] .gitignore 里排除含明文令牌的演示文件；
[ ] ALLOW_ORIGIN 限制成自己的页面域名；
[ ] COZE_BOT_ID 服务端锁定；
[ ] 给 /api/chat 加每 IP 限流，防止额度被刷。

七、它现在能做什么

学生打开网页就能聊，不用注册、不用装 App、不用填任何密钥；
电脑课、自习课、回家写作业都能用同一套入口；
老师不用维护服务器（Vercel 免费额度足够一个班用）；
想改提示词、改角色设定，在扣子后台改，前端不用重新部署。

代码都在 HG-dev17/Program-helper，README 里写了从发布智能体到配 DNS 的完整步骤。