About · Usage · Maintenance
使用说明
这一页写清四件事：本站基于什么假设做的、怎么打开与维护、设计令牌怎么改、哪些内容必须你自己核实。
01打开方式
站点是纯静态文件，不需要安装、不需要服务器、不需要联网：
- 把整个
ai-agent-learning/文件夹放在本机任意位置（不要只拷贝单个 HTML）。 - 双击
index.html，默认浏览器会以file://协议打开。 - 进度存在浏览器的 localStorage：换浏览器、清理站点数据或使用无痕模式都会丢失。
- 首页会根据上次阅读的小节和完成记录提供「继续学习」入口；完成上次小节后，会推荐后续未完成的小节。
- 少数浏览器在
file://或严格隐私模式下会禁用 localStorage：保存失败时页面会显示持续提示。当前更改仅临时有效，修复存储设置或空间问题后可点「重试保存」。 - 手机和平板可展开阅读区顶部的「本阶段目录」跳转小节；跳转后目录自动收起。
如果样式丢失：通常是把 HTML 单独移动了位置。页面引用的是 assets/style.css 相对路径，必须和 assets/ 目录保持同级。
02假设声明
以下是构建时采用的默认假设。任一条不成立，都会影响内容取舍，请按需校正：
| 输入项 | 采用的假设 | 影响 |
|---|---|---|
| 蓝本 | runoob AI Agent 教程（47 个章节） | 不增删主题；章节顺序按学习路径重排，原文链接保留 |
| 学习者水平 | 有基础编程经验、无 Agent 实战经验 | Python 章节不教语法；概念章节从零解释 |
| 章节规模与时长 | 47 节，每节 20–40 分钟，总计约 18 小时 | 动手任务控制在 15–60 分钟；不追求覆盖所有细节 |
| 运行环境 | 本地现代浏览器，离线优先 | 零外部字体/CDN/统计；双击即可打开 |
| 视觉强度 | 多巴胺风格，以「高饱和强调 + 中性底色」为上限 | 高饱和只用于标签/按钮/边饰；正文保持高对比 |
| 内容时效 | 以审计时（2026-10）能核验到的信息为准 | 无法确证的标「待核实」，不编造版本与参数 |
03设计说明与令牌
所有颜色、圆角、阴影、动效都定义在 assets/style.css 顶部的 :root 中，页面只引用变量。
对比度按 WCAG 2.1 计算，正文与次要文字均达到 AA。
| 令牌 | 值 | 用途 | 对比度（前景/背景） |
|---|---|---|---|
--ink | #191036 | 正文、边框、阴影 | 17.4:1（on #FFFBF2） |
--paper | #FFFBF2 | 页面底色（带点阵） | — |
--muted | #5B5470 | 次要文字 | 7.3:1（on #FFFBF2） |
--violet | #6D28D9 | 主强调、链接、按钮 | 7.1:1（白字）/ 6.9:1（on 纸色） |
--pink | #FF2E93 | 贴纸、强调块 | 5.19:1（墨字）；白字仅限大字（3.46:1） |
--yellow | #FFD84D | 高亮、完成态 | 13.0:1（墨字） |
--lime | #C8F169 | 动手任务、成功态 | 13.9:1（墨字） |
--cyan | #6EE7F5 | 自检、信息提示 | 12.3:1（墨字） |
--orange | #FF8A3D | 警示、阶段 5 | 7.7:1（墨字） |
字体与尺寸
- 字体：系统中文字体栈（PingFang SC / 微软雅黑 / Noto Sans SC），不加载外部字体，避免离线失败与中文 webfont 体积。
- 正文 16px / 行高 1.75；标题使用
clamp()响应式缩放；代码使用等宽字体栈。 - 间距按 4px 节奏：4 / 8 / 12 / 16 / 24 / 32 / 48 / 64；卡片圆角 16–24px。
- 阴影使用「实色偏移」而非模糊阴影（
3px 3px 0），与粗描边形成贴纸感，同时不牺牲文字对比。
组件规范
| 组件 | 形态 | 交互 / 状态 |
|---|---|---|
| 主按钮 | 46px 高、2px 墨色描边、药丸圆角、紫底白字、3px 实色偏移阴影 | 悬停上移 1px 并加深阴影；按下位移到阴影位置 |
| 次按钮 | 白底墨字，同描边与阴影 | 悬停变黄底；不做透明度渐隐 |
| 卡片 | 白底、16–24px 圆角、2px 描边、3–5px 实色阴影 | 悬停轻微上移；焦点态用 3px 紫色外框 |
| 标签 / 徽章 | 药丸形、12.5px 粗体、2px 描边 | 纯展示，不可点击；颜色只用于分类 |
| 完成态 | 按钮变青柠底 + 勾选图标，卡片加浅绿底 | 通过 aria-pressed 同步语义状态 |
| 禁用态 | 透明度 0.5 + cursor: not-allowed | 保留可读性，不使用纯灰色文字 |
| 提示条 | 2px 描边 + 4 种底色（信息/更新/警示/成功） | 图标 + 文字双编码，不依赖颜色单独传达含义 |
动效规范
- 只动
transform与opacity；时长 150–220ms；缓动cubic-bezier(.2,.8,.2,1)。 - 悬停位移不超过 3px；不做自动轮播、闪烁、无限循环动画。
prefers-reduced-motion: reduce时关闭所有位移与过渡，滚动改回即时。- 进度条与圆环只随「标记完成」变化，属于状态反馈而非装饰。
04如何新增或修改一节
- 在对应
stage-N.html中复制一个<article class="lesson">整块。 - 改三处：
id="sN-M"、lesson-badge的编号、data-done-id="sN-M"；三处必须一致。 - 补全五个字段：学习目标、前置知识、核心要点、动手任务、自检（每个至少 1 条）。
- 在左侧目录
.toc里加一条锚点；如果是原文已有章节，在contents.html对应分组里加一行并指向新锚点；本站扩展则标注「本站扩展」。 - 运行
python3 tools/link_chapters.py：重建全站章级前后篇，并自动同步STAGE_TOTAL。 - 运行
python3 tools/build_search_index.py：把新增/修改的要点纳入全文搜索。 - 刷新页面，点一次「标记完成」，确认进度条与圆环同步变化。
只改配色：编辑 style.css 的 :root 变量即可，全站生效。
若某个阶段要换主色，改对应页面的 body[data-accent] 与 .stage-card 的 --sc。
改完请重新核对前景/背景对比度，正文不低于 4.5:1。
05必须自行核实的清单
以下内容在审计时无法确证，或本身变化极快。使用前请查官方来源，不要直接引用：
| 内容 | 需要核实什么 | 去哪查 |
|---|---|---|
| 模型版本与名称 | GPT-6 Astra / DeepSeek V4 / Claude 4.6 等命名是否存在、上下文与价格 | 各厂商官方模型文档 / 发布公告 |
| 框架 API | LangChain create_agent、AutoGen autogen_agentchat 的当前签名 | 官方文档 + PyPI 版本页 |
| Python 版本支持 | 3.9/3.10 的 EOL 时间、依赖包的最低版本 | python.org 生命周期表、包元数据 |
| 产品能力与定价 | DuMate / WorkBuddy / MonkeyCode / OpenClaw 的可用地区、额度、系统要求 | 产品官网 / 官方仓库 |
| 社区统计 | Harness 章节引用的代码行数、团队规模等数字 | 原始来源（若找不到则不引用） |
| 安装命令与端口 | OpenClaw / GraphRAG / CrewAI 的安装方式与版本区间 | 官方快速开始页 |
06来源、版权与边界
- 蓝本与署名：内容框架来自 runoob.com · AI Agent（智能体）教程，版权归原作者/站点所有。本站不复制原文全文，只提供学习路径、要点提炼、动手任务与审计结论，并逐节保留原文链接。
- 使用范围：个人学习项目。公开分享请保留署名与来源链接；不复制原文全文。引用本站原创部分请注明来源与链接。
- 许可：代码采用 MIT；原创文字（学习路径、要点、任务、审计、说明）采用 CC BY-NC-SA 4.0：允许非商业分享与改编，需署名并以相同方式共享。原文与第三方内容不在本站授权范围。详见 LICENSE 与 LICENSE-CONTENT.md。
- 准确性：站内对原文的评价是「基于公开文档的时效性判断」，不是对原作者的否定；发现判断有误，以官方文档为准并修正本站。
- 无追踪：没有统计脚本、没有外部字体、没有 Cookie；学习进度只写入本机
localStorage，可用下方按钮清空。
07清空本机进度
如果你要重新走一遍，或把站点交给别人，点下面这个按钮。此操作会清空当前浏览器的完成进度和上次阅读位置；保存失败时保留原记录。