Agent.Jeffjade.Com

智能体漫游

[agent.jeffjade.com](https://agent.jeffjade.com) 是一个面向中文读者的 **AI Agent 教程站**。目标不是堆概念，而是让读者能讲清机制、完成真实任务，并知道工具边界在哪里。

本站用可复现的命令、文件路径与故障现象组织内容，重要结论尽量追溯到官方文档、本地代码或可验证步骤；证据不足时会直接说明。

项目介绍

定位

• 主题：主流 AI Agent 的入门与进阶，当前以 Claude Code 与 Hermes Agent 两条教程轨道为主。
• 读者：需要上手 Agent 工具的开发者，以及希望把 Agent 纳入日常工程流程的技术负责人。
• 写法：每章围绕一个具体问题展开，结构为场景、概念、最小路径、机制、故障模式、使用边界；同一篇文章兼顾新手能跟做、熟手能排错、进阶读者能看到系统设计层面的取舍。

内容质量约定

一篇合格教程应满足三条：

1. 有据：结论可追溯到官方文档、仓库内文件、可复现命令，或明确标注为推断。
2. 闭环：每节有问题、答案、机制与边界。
3. 可验：读者能通过命令输出、文件对比或典型报错自行核对。

正文默认使用**简体中文**与中文标点。撰写与评审约定见仓库根目录 [`CLAUDE.md`](./CLAUDE.md)。

技术栈

类别	技术	说明
框架	Astro 6.x	静态站点与页面路由
文档	@astrojs/starlight	教程章节、侧栏、全文检索
组件	Svelte 5	站点内交互组件
样式	Tailwind CSS 4	全局与落地页样式
主题	starlight-theme-rapide	Starlight 阅读体验
语言	TypeScript	配置、侧栏、集成逻辑
包管理	pnpm 10	依赖与脚本

主要依赖版本见 [`package.json`](./package.json)。

本地开发

pnpm install
pnpm dev      # 开发服务器，默认监听 0.0.0.0
pnpm check    # Astro 类型检查（改配置或组件时建议运行）
pnpm build    # 生产构建
pnpm preview  # 预览构建结果

• 仅改 Markdown 文档时，建议至少执行 pnpm build。
• 改动 astro.config.mjs、组件、类型或侧栏时，建议 pnpm check 后再 pnpm build。

仓库结构

agent.jeffjade.com/
├── astro.config.mjs              # Starlight、重定向、全局侧栏
├── CLAUDE.md                     # 撰写约定与协作说明
├── HANDOFF.md                    # Hermes 系列制作进度（维护用）
├── src/
│   ├── content/docs/
│   │   ├── claude-code/          # Claude Code 正文章节
│   │   └── hermes-agent/         # Hermes Agent 正文章节
│   ├── config/
│   │   ├── claude-code-sidebar.ts
│   │   └── hermes-agent-sidebar.ts
│   ├── pages/
│   │   ├── index.astro           # 站点首页 /
│   │   ├── claude-code/          # Claude Code 专题落地页
│   │   └── hermes-agent/         # Hermes Agent