# Aither

> An AI-native Astro theme that believes text itself is beautiful.

---

## ✨ 为什么选择 Astro-Theme-Aither

URL: https://astro-theme-aither.pages.dev/zh-hans/posts/why-astro-theme-aither/
Date: 2026-01-03
Category: Design
Tags: Design, Astro
Description: 一个相信文字本身就很美的 AI 原生 Astro 主题。

一个相信文字本身就很美的 AI 原生 Astro 主题。

## 设计理念

极简设计，不极简工程。当页面上没有花哨的视觉元素来掩盖问题时，任何瑕疵都会被放大。极简设计对工程质量的要求更高，而不是更低。

排版参数遵循 Apple 人机界面指南：17px / 1.47 / -0.022em。全站统一无衬线系统字体栈。字体本身就是视觉标识。

## AI 原生

为 AI agent 时代而生。每个页面都天然可被机器阅读：

- **llms.txt** — AI agent 内容索引，`/llms.txt`
- **llms-full.txt** — 全文输出，`/llms-full.txt`
- **Markdown 端点** — 任何文章 URL 后加 `.md` 获取源文件
- **JSON-LD** — 每篇文章的 Article 结构化数据
- **robots.txt** — 明确欢迎 GPTBot、ClaudeBot、PerplexityBot

你的内容不只是发布了——它是 AI 可发现的。

## 基于 Astro

Astro 的岛屿架构意味着只有交互组件加载 JavaScript。其他一切都是静态 HTML 和 CSS，瞬间加载。

交互式岛屿：主题切换器（View Transitions API 圆形展开动画）、语言切换器、浏览器语言检测、移动端导航。

## 功能

- **Tailwind CSS v4** — `@theme` 设计令牌，完整明暗主题定制
- **i18n** — 多语言支持，自动浏览器语言检测
- **文章置顶** — 将重要文章固定在列表顶部
- **深色模式** — 浅色 / 深色 / 系统，View Transitions API 动画
- **Content Collections** — 构建时类型安全 Markdown 验证
- **SEO** — Open Graph、规范 URL、Twitter Cards
- **RSS + 站点地图** — 自动生成，零配置
- **Google Analytics / Crisp Chat / Giscus** — 可选，通过 `.env` 配置
- **Vitest + Playwright** — 单元 + E2E 测试，集成 CI
- **部署** — GitHub Pages（默认）+ Cloudflare Pages（可选）

## 适合谁

如果你相信好的文字自己会说话：

- **博客作者** — 想让文字成为绝对主角
- **技术写作者** — 需要清晰的代码块和内容结构
- **多语言作者** — 需要内置 i18n 和语言检测
- **开发者** — 欣赏工程质量过硬、可放心扩展的代码库

写任何话题——排版会让它看起来很好。

---

## 📝 Markdown 样式指南

URL: https://astro-theme-aither.pages.dev/zh-hans/posts/markdown-guide/
Date: 2026-01-02
Category: Tutorial
Tags: Markdown, Guide
Description: Astro-Theme-Aither 支持的所有 Markdown 功能的完整指南

这篇文章演示了 Astro-Theme-Aither 支持的每一个 Markdown 功能。写作时可以将它作为参考。

Markdown 是一种轻量级标记语言，用纯文本就能写出格式丰富的文章。只需一个文本编辑器和几个简单的符号，就能创作出排版优美的内容。

## 标题

使用 `##` 作为章节标题，`###` 作为子章节，`####` 作为三级子章节。避免在正文中使用 `#`——文章标题已经作为顶级标题渲染。

### 三级标题

#### 四级标题

合理使用标题层级能帮助读者快速了解文章结构。建议每篇文章用两到三级标题，层级过深会让结构变得混乱。好的标题应该简短、清晰，能准确概括该章节的内容。

## 段落与换行

普通段落文本自然流动。在段落之间留一个空行来分隔它们。

这是第二个段落。保持每个段落围绕一个想法，以获得最佳阅读体验。

写作建议：每个段落不宜过长，三到五句话为佳。过长的段落会形成大块的文字墙，降低阅读的愉悦感。如果一个段落的内容太多，考虑将它拆分为两个段落，或者用列表来组织信息。

## 强调

- **粗体文本** 使用 `**双星号**`
- *斜体文本* 使用 `*单星号*`
- ***粗斜体*** 使用 `***三星号***`
- ~~删除线~~ 使用 `~~双波浪号~~`

强调应当谨慎使用。如果一段文字中到处都是粗体和斜体，那就等于没有强调。只在真正重要的关键词或短语上使用强调，让它们在视觉上突出出来。

## 链接

[行内链接](https://astro.build) 使用 `[文本](url)` 语法。

链接文本应该有描述性，让读者不点击链接也能知道链接指向什么内容。避免使用"点击这里"或"链接"这样的无意义文本作为链接描述。

## 列表

无序列表：

- 第一项
- 第二项
  - 嵌套项
  - 另一个嵌套项
- 第三项

有序列表：

1. 第一步
2. 第二步
   1. 子步骤一
   2. 子步骤二
3. 第三步

任务列表：

- [x] 搭建项目
- [x] 写第一篇文章
- [ ] 部署到生产环境

列表是组织信息的利器。当你有三个以上的并列项时，用列表比用逗号分隔的句子更清晰。嵌套列表适合展示层级关系，但嵌套不宜超过两层，否则结构会变得难以阅读。

## 引用

> 抽象的目的不是为了模糊，而是为了创造一个新的语义层级，在其中可以做到绝对精确。
>
> — Edsger W. Dijkstra

嵌套引用：

> 第一层
>
> > 第二层
> >
> > > 第三层

引用块非常适合用来展示名人名言、重要提示、或者从其他来源引用的段落。在技术文章中，引用块也常被用来高亮需要特别注意的信息，比如注意事项或警告。

## 代码

使用反引号包裹行内 `代码`。

带语法高亮的代码块：

```typescript
interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

function getPublishedPosts(posts: Post[]): Post[] {
  return posts
    .filter((post) => !post.draft)
    .sort((a, b) => b.date.getTime() - a.date.getTime());
}
```

```css
@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}
```

代码块在技术写作中至关重要。始终为代码块指定语言标识符（如 `typescript`、`css`、`python`），这样渲染引擎才能正确地进行语法高亮。对于命令行指令，可以使用 `bash` 或 `shell` 作为语言标识符：

```bash
pnpm install
pnpm dev
```

行内代码适合在文本中提及变量名、函数名、文件路径等短小的代码片段。比如提到 `getPublishedPosts` 函数或 `src/config.ts` 文件时，用行内代码将它们标记出来，读者能够一眼区分代码和普通文本。

## 表格

| 功能 | 状态 | 备注 |
|---|---|---|
| 深色模式 | 支持 | 浅色 / 深色 / 跟随系统 |
| RSS 订阅 | 内置 | `/rss.xml` |
| 站点地图 | 自动生成 | 通过 `@astrojs/sitemap` |
| SEO | 内置 | Open Graph + 规范链接 |

右对齐和居中列：

| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| 文本 | 文本 | 文本 |
| 较长文本 | 较长文本 | 较长文本 |

表格适合展示结构化的对比信息。当数据有明确的行列关系时，表格比段落文字更直观。但 Markdown 表格不适合太复杂的数据——如果你的表格超过五六列或需要合并单元格，可能需要考虑其他展示方式。

## 分割线

使用 `---` 创建分割线：

---

分割线后的内容。

分割线适合在同一篇文章中分隔两个主题完全不同的部分。不过，大多数情况下用标题来划分章节就足够了，分割线应当节制使用。

## 图片

图片使用标准 Markdown 语法：

```markdown
![替代文本](./image.jpg)
```

本主题以排版为核心，但在需要时图片同样可以正常使用。

### 图片使用建议

替代文本（alt text）非常重要。它不仅帮助视障用户通过屏幕阅读器理解图片内容，也在图片加载失败时作为后备显示。好的替代文本应该简洁地描述图片的内容和作用，而不是简单地写"图片"或"截图"。

## 写作最佳实践

掌握 Markdown 语法只是第一步，真正重要的是如何运用这些工具写出高质量的内容。以下是一些通用的写作建议：

- **先写大纲再填内容** —— 用标题搭建文章骨架，确定逻辑流向，然后逐节填充细节
- **一个段落一个重点** —— 避免在一个段落中讨论多个不相关的话题
- **善用列表** —— 把并列的信息用列表组织，读者扫一眼就能掌握要点
- **代码配文字** —— 代码块前后加上解释性文字，说明这段代码做了什么、为什么要这样写
- **定期回顾** —— 写完后从头到尾读一遍，删掉多余的内容，改善表达不清的地方

Markdown 的简洁正是它的力量。它让你专注于写作本身，而不是格式调整。希望这篇指南能帮助你充分利用 Astro-Theme-Aither 提供的排版能力，写出赏心悦目的文章。

---

## 👋 你好，世界

URL: https://astro-theme-aither.pages.dev/zh-hans/posts/hello-world/
Date: 2026-01-01
Category: Tutorial
Tags: Hello, Astro
Description: 欢迎来到 Astro-Theme-Aither——一个相信文字本身就很美的 AI 原生 Astro 主题。

欢迎来到 Astro-Theme-Aither。

这是一个基于一个信念构建的 AI 原生博客主题：文字本身就很美。统一的无衬线系统字体栈、Apple HIG 排版参数，以及不喧宾夺主的布局。这里的一切都服务于一个目标——让你的文字看起来优美、读起来舒适。

## 为什么再造一个博客主题

互联网上有无数博客主题，那为什么还要再做一个？答案在于优先级。大多数主题为视觉冲击力而优化——大图、复杂布局、华丽动画。这些在演示中很好看，但当读者真正坐下来阅读一篇两千字的文章时，它们只会碍事。

Astro-Theme-Aither 从不同的前提出发：内容就是产品。主题的职责是以它应得的认真态度呈现内容：Apple HIG 正文参数（17px / 1.47 / -0.022em）、充足的留白、让长文阅读变得舒适而不是疲惫的垂直节奏。

技术决策也延续了这一理念。主题使用 Astro 的岛屿架构——只有交互组件（主题切换、语言切换、语言检测、移动端导航）加载 JavaScript。其他一切都是静态 HTML 和 CSS。没有布局偏移，没有加载动画。页面加载完毕，你开始阅读。

## 开始使用

搭建只需几步：

1. **克隆仓库** — 使用 GitHub 模板按钮或直接 `git clone`
2. **安装依赖** — 运行 `pnpm install`
3. **配置站点** — 编辑 `src/config/site.ts` 设置标题、描述和导航
4. **配置服务** — 复制 `.env.example` 为 `.env`，填入 API 密钥（GA、Crisp、Giscus）
5. **替换内容** — 用你自己的文章替换 `src/content/posts/` 中的示例
6. **本地开发** — 运行 `pnpm dev` 启动热更新开发服务器
7. **部署** — 推送到 GitHub，CI 工作流自动部署到 Cloudflare Pages

### 项目结构

```
src/
├── components/     # Astro 和 React 组件
├── config/         # 站点配置（site.ts）
├── content/        # Markdown 文章（按语言组织）
├── i18n/           # 翻译和语言工具
├── layouts/        # 页面布局（Layout.astro）
├── lib/            # 共享工具（posts, formatter, markdown-endpoint）
├── pages/          # 路由页面（按语言）
└── styles/         # 全局 CSS + Tailwind v4 @theme 令牌
```

### 写第一篇文章

在 `src/content/posts/zh-hans/` 下创建 `.md` 文件：

```markdown
---
title: 我的第一篇文章
date: 2026-01-15
category: General
description: SEO 和社交预览的简短摘要
tags: [话题, 标签]
pinned: false
---

正文从这里开始。
```

`title`、`date`、`category` 是必填项。`description` 强烈建议填写。设置 `pinned: true` 可将文章置顶。

多语言内容只需在对应语言目录（`en/`、`ko/`、`fr/` 等）创建同名文件。

## 开箱即用

### 内容功能

- **RSS 订阅** — 自动生成 `/rss.xml`
- **站点地图** — 通过 `@astrojs/sitemap` 自动生成
- **SEO 标签** — 每页自动生成 Open Graph、Twitter Cards、规范 URL
- **JSON-LD** — Article 结构化数据，服务 AI 和搜索引擎
- **深色模式** — 浅色 / 深色 / 系统切换，View Transitions API 圆形展开动画
- **i18n** — 多语言支持，自动浏览器语言检测
- **文章置顶** — 将重要文章固定在列表顶部
- **分页** — 基于文件的 SSG 分页，带页码导航

### AI 原生功能

- **llms.txt** — AI agent 内容索引，`/llms.txt`
- **llms-full.txt** — AI 全文消费，`/llms-full.txt`
- **Markdown 端点** — 任何文章 URL 后加 `.md` 获取纯 Markdown
- **robots.txt** — 明确欢迎 AI 爬虫（GPTBot、ClaudeBot、PerplexityBot）

### 开发者功能

- **TypeScript** — 严格模式，全类型化
- **Content Collections** — 构建时 frontmatter 类型验证
- **Tailwind CSS v4** — `@theme` 设计令牌
- **Vitest + Playwright** — 单元测试 + E2E 测试
- **部署** — GitHub Pages（默认）+ Cloudflare Pages（可选）
- **Google Analytics** — 可选，环境变量配置
- **Crisp Chat** — 可选在线客服，环境变量配置
- **Giscus 评论** — 可选 GitHub Discussions 评论

### 性能

静态 HTML + 最小 JavaScript 岛屿 = Lighthouse 四项满分。

## 自定义

- **颜色** — 编辑 `src/styles/global.css` 中的 CSS 变量
- **字体** — 修改 Tailwind 主题配置中的字体族
- **导航** — 更新 `src/config/site.ts` 中的导航数组
- **服务** — 在 `.env` 中设置 GA、Crisp、Giscus 环境变量
- **语言** — 在 `src/i18n/` 添加新语言，创建对应路由

## 设计理念

主题的视觉简洁是刻意的，但这不等于工程简单。底层处理了大量关注点：Apple HIG 排版参数、明暗两种模式的无障碍色彩对比、View Transitions API 动画、自动浏览器语言检测、语义化 HTML 结构、AI 友好的内容端点，以及从手机到超宽屏的阅读体验优化。

好的设计是隐形的。当你在这个主题上阅读一篇文章，只是单纯享受文字而完全没注意到主题的存在——这就是设计在按预期工作。

祝写作愉快。

---

## AI 智能体与工具使用 (Sample)

URL: https://astro-theme-aither.pages.dev/zh-hans/posts/ai-agents-and-tool-use/
Date: 2026-01-09
Category: AI
Tags: AI, Agents
Description: AI 模型如何超越对话，在真实世界中执行操作

AI 智能体是一个能够执行操作的语言模型——不仅仅是生成文本。它能搜索网页、运行代码、调用 API、读取文件，并决定下一步做什么。

如果说传统的聊天机器人是"顾问"，那么智能体就是"执行者"。它不仅能告诉你该怎么做，还能直接帮你做。这一转变正在从根本上改变我们与 AI 的交互方式。

## 从对话到行动

聊天机器人回答问题，智能体解决问题。区别在于自主性：智能体决定使用哪些工具、以什么顺序、如何处理错误。

一个简单的例子可以说明两者的区别。当你问聊天机器人"帮我订明天下午三点的会议室"，它会告诉你怎么操作订会议室的系统。而智能体会直接查询可用的会议室，选择一个合适的，帮你完成预订，然后发送日历邀请给参会者。

### 自主性的层级

并非所有智能体都是一样的。根据自主程度，可以分为几个层级：

- **辅助级** —— 执行单步操作，每步都需要人工确认。比如帮你草拟一封邮件，等你确认后再发送
- **半自主级** —— 能完成多步任务，但在关键决策点暂停等待人工审批。比如帮你部署代码，但在推送到生产环境前等待你的确认
- **全自主级** —— 独立完成整个任务链条，仅在遇到无法处理的异常时求助。这个级别的智能体目前还在早期探索阶段

## 工具使用

工具使用让 AI 模型调用外部函数。模型判断何时需要工具，生成正确的参数，并将结果整合到回答中。这把文本生成器变成了强大的助手。

### 工具的类型

实际应用中，智能体使用的工具种类繁多：

- **信息检索** —— 搜索引擎、数据库查询、文档检索、API 调用
- **代码执行** —— 运行 Python 脚本、执行 Shell 命令、操作文件系统
- **通信** —— 发送邮件、推送通知、调用即时通讯 API
- **数据处理** —— 解析表格、生成图表、格式转换
- **外部服务** —— 调用第三方 API，如天气查询、翻译服务、支付接口

### 工具描述的重要性

模型如何知道什么时候该用什么工具？答案在于工具描述。每个工具都附带一段描述文本，说明它的功能、参数和使用场景。模型根据这些描述来判断当前任务是否需要某个工具。因此，写好工具描述与写好提示词同样重要。

## 智能体循环

最强大的模式是智能体循环：模型规划一个步骤，执行它，观察结果，然后决定下一步。这个循环持续到任务完成或模型判断无法继续。

### 循环的具体流程

一个典型的智能体循环是这样运作的：

1. **接收任务** —— 用户描述需要完成的目标
2. **制定计划** —— 模型将任务分解为可执行的步骤
3. **选择工具** —— 模型决定第一步需要使用什么工具
4. **执行操作** —— 调用工具并获取结果
5. **观察反思** —— 分析工具返回的结果，判断是否符合预期
6. **调整计划** —— 根据实际结果调整后续步骤
7. **重复迭代** —— 回到第三步，继续执行下一个步骤
8. **完成报告** —— 所有步骤完成后，向用户汇报结果

这个过程中最关键的是第五步和第六步。好的智能体能够根据实际情况灵活调整计划，而不是机械地按照初始计划执行。遇到错误时，它能尝试不同的策略，而不是直接放弃。

## 实际应用场景

目前智能体技术已经在多个领域看到了实际应用：

- **软件开发** —— 编写代码、运行测试、修复 Bug、提交 Pull Request
- **数据分析** —— 读取数据集、执行分析脚本、生成可视化报告
- **客户支持** —— 查询订单状态、处理退款、升级问题工单
- **运维自动化** —— 监控告警、诊断问题、执行修复操作
- **研究助手** —— 搜索文献、总结论文、生成实验方案

## 风险

能执行操作的智能体也能执行错误的操作。沙箱隔离、确认步骤和人工审查是任何生产级智能体系统的必要安全措施。

### 常见的风险类型

- **误操作** —— 智能体可能误解指令，执行与用户意图不符的操作。比如被要求"清理临时文件"时误删了重要数据
- **权限滥用** —— 如果给予智能体过多权限，它可能在不恰当的场景下使用这些权限
- **循环失控** —— 智能体可能陷入无限循环，不断执行无效操作，浪费资源甚至造成破坏
- **信息泄露** —— 智能体在调用外部服务时可能无意中暴露敏感信息

### 安全最佳实践

构建生产级智能体系统时，务必遵循以下原则：最小权限原则——只赋予智能体完成任务所需的最少权限；沙箱隔离——在受限环境中运行操作；关键操作确认——在执行不可逆操作前要求人工确认；全面的日志记录——记录智能体的每一步操作，便于事后审计。

安全不是一个可以事后补上的功能，而是智能体系统设计的基础。从第一天起就将安全考虑纳入架构设计中。