Agent-Path

面向 AI Agent 开发学习的个人学习站：把学习路线、项目实践、每日打卡和面试题库放在同一个 Web 应用中。

功能

• 学习路线、每日计划、任务验收清单和项目拆解。
• 学习打卡、年度热力图、投入时间统计和学习备份导入导出。
• 累计打卡排行榜、个人排名和超过学习者占比，展示账户昵称并支持同分并列。
• Agent、数据库、中间件、Java 等方向的题库，支持全文搜索、目录、文章收藏、章节复习标记和最近阅读。
• 重点题附大白话理解、例子和易错点；Mermaid 流程图与时序图按需绘制，支持主题切换、源码查看和局部放大。
• 账号登录与 PostgreSQL 持久化；公共资料与个人题库隔离。
• 账户安全：凭当前密码修改密码、验证绑定邮箱，以及通过一次性邮件链接找回密码；改密后退出所有设备，保留学习记录。
• 直接新建个人专题、面经合集和题目；支持 Excel/JSON 批量导入，先预览再确认。
• 多主题、全屏查看与移动端布局；可选的小程序 Bearer API 复用账号及数据。

技术栈

Node.js 22.12+、Express 5、PostgreSQL，以及原生 JavaScript、HTML 和 CSS。生产部署使用 Docker 与 Caddy 提供 HTTPS。

本地运行

先准备可用的 PostgreSQL 数据库和应用账号，再执行：

npm ci
cp .env.example .env

在 .env 中填写自己的 PGHOST、PGDATABASE、PGUSER 和 PGPASSWORD（或执行 npm run setup:db 自动创建应用库与角色并写入 .env），然后启动：

npm start

访问 本地应用。服务仅监听回环地址；启动时会执行已有的幂等数据库迁移。需要单独执行迁移时使用 npm run migrate。

空库需要公共题库时，先查看待导入内容，再显式导入：

npm run import:interviews-db -- --dry-run
npm run import:interviews-db

已有题库补充首批 9 道理解讲解和 10 张图时，先预览，再执行：

npm run enrich:interviews -- --dry-run
npm run enrich:interviews -- --apply

此操作只追加到答案和标题仍与默认种子一致的公共题目；个人题目、已编辑内容与已删除内容会跳过。写入前将涉及的题目和专题备份到 backups/interview-understanding-*.json，并在事务内按版本更新、回读核对；重复运行会跳过已补充的答案。新增理解内容维护在 content/interview-understanding.json。管理页面或个人导入的 Markdown 答案也可使用标准 mermaid 代码块，网页会自动绘图；小程序仍按文本代码块展示。

INTERVIEW_ADMIN_USER_IDS 配置本环境公共题库管理员的用户 ID，留空时关闭公共资料写入。小程序接口由 ENABLE_MINIPROGRAM_API 控制，默认关闭。完整配置项见 .env.example。

密码长度为 6–128 位，注册、登录、修改密码和邮件重置使用相同限制。账户安全中的修改密码无需邮件服务。邮箱验证和邮件找回使用 Resend HTTPS API，不再使用私人 SMTP。在 Resend 中验证自有发信域名后，在私密 .env 配置 RESEND_ENABLED=true、RESEND_API_KEY、RESEND_FROM（已验证域名下的裸邮箱地址，如 noreply@mail.example.com）。API Key 不提交到仓库；生产配置放服务器 secrets。后端使用 Node 原生 fetch，无需额外邮件 SDK。

已有账号需先登录，在顶部“账户安全”中验证绑定邮箱，才能从登录页“忘记密码”收取重置链接。邮件链接 30 分钟内有效且只能使用一次，发信间隔至少一分钟。打开邮件只显示确认表单，提交后才生效；Resend API 接受不等于收件箱已送达，可凭日志中的邮件 ID 查询控制台状态。APP_ORIGIN 决定邮件返回地址，生产必须为站点 HTTPS origin。Resend 未启用或配置不完整时，邮件入口关闭，普通登录与凭原密码改密仍可使用。域名 DNS 记录按 Resend 控制台实际给出的值配置；测试域名 resend.dev 不能用于给任意站点用户找回密码。

项目目录

目录或文件	用途
public/	Web 页面、样式、浏览器逻辑和公共题库种子
server/	登录、学习状态、题库、导入及数据库访问
content/	题库生成使用的分类清单与回答源
scripts/	内容构建、导入及文档导出工具
deploy/	Docker、Caddy、备份与服务配置
tests/	项目已有的检查代码
interview-sources.json	资料来源索引

部分资料采集脚本依赖自己的外部博客目录；日常启动直接使用仓库内 public/ 的内容，不需要执行这些采集脚本。Excel 填写说明见 导入指南。

部署

参考 部署说明。真实 .env、数据库、备份、原始本机验收记录及历史独立 sites/ 工程均不纳入本仓库。微信原生客户端位于单独的 Agent-learn-wx 工程。

发布记录

• 2026-10-18：7 项修复、UI 优化、部署与线上完整验收：包含版本记录、验证结果、日期补修、数据清理与回退注意事项。