# Aither

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

---

## ✨ 為什麼選擇 Astro-Theme-Aither

URL: https://astro-theme-aither.pages.dev/zh-hant/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-hant/posts/markdown-guide/
Date: 2026-01-02
Category: Tutorial
Tags: Markdown, Guide
Description: Astro-Theme-Aither 支援的所有 Markdown 功能的完整指南

這篇文章演示了 Astro-Theme-Aither 支援的每一個 Markdown 功能。寫作時可以將它作為參考。

## 標題

使用 `##` 作為章節標題，`###` 作為子章節，`####` 作為三級子章節。避免在正文中使用 `#`——文章標題已經作為頂級標題呈現。

### 三級標題

#### 四級標題

### 標題的最佳實踐

一篇結構良好的文章通常只需要兩到三個層級的標題。過多的層級嵌套會讓讀者迷失方向。建議遵循以下原則：

- **`##` 用於主要章節**：每個主要章節代表文章的一個核心論點或主題
- **`###` 用於子章節**：在需要進一步細分時使用
- **`####` 謹慎使用**：只在確實需要第三層級時才使用，通常表示你的內容結構可能需要重新組織

## 段落與換行

普通段落文字自然流動。在段落之間留一個空行來分隔它們。

這是第二個段落。保持每個段落圍繞一個想法，以獲得最佳閱讀體驗。

寫作時，建議每個段落控制在三到五句話之間。過長的段落會形成視覺上的「文字牆」，讓讀者望而卻步。適當地將長段落拆分成幾個短段落，可以顯著提升閱讀體驗。如果你發現一個段落超過了六七行，考慮將其拆分。

## 強調

- **粗體文字** 使用 `**雙星號**`
- *斜體文字* 使用 `*單星號*`
- ***粗斜體*** 使用 `***三星號***`
- ~~刪除線~~ 使用 `~~雙波浪號~~`

強調標記應謹慎使用。如果一段文字中到處都是粗體，那粗體就失去了強調的效果。一般來說，每個段落中最多使用一到兩處粗體來突出關鍵概念即可。斜體在中文排版中不太常用，因為中文字型的斜體渲染效果通常不如西文字型理想。

## 連結

[行內連結](https://astro.build) 使用 `[文字](url)` 語法。

連結文字應該具有描述性，讓讀者不需要點擊就能知道連結指向的內容。避免使用「點擊這裡」或「連結」這樣的空洞文字。例如：

- 不佳：更多資訊請[點擊這裡](https://astro.build)
- 推薦：查看 [Astro 官方文件](https://astro.build) 了解更多

## 列表

無序列表：

- 第一項
- 第二項
  - 巢狀項
  - 另一個巢狀項
- 第三項

有序列表：

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`），啟用語法高亮
- **精簡範例**：只展示與當前討論相關的程式碼，去掉無關的匯入和設定
- **加入註解**：在關鍵行加上註解，幫助讀者理解程式碼意圖
- **前後文說明**：在程式碼區塊之前說明這段程式碼要做什麼，之後解釋關鍵細節

```python
# 使用列表推導式過濾並轉換資料
active_users = [
    user.name.upper()          # 將名字轉為大寫
    for user in all_users      # 遍歷所有使用者
    if user.is_active           # 只保留活躍使用者
]
```

## 表格

| 功能 | 狀態 | 備註 |
|---|---|---|
| 深色模式 | 支援 | 淺色 / 深色 / 跟隨系統 |
| RSS 訂閱 | 內建 | `/rss.xml` |
| 網站地圖 | 自動產生 | 透過 `@astrojs/sitemap` |
| SEO | 內建 | Open Graph + 規範連結 |

靠右對齊和置中欄位：

| 靠左 | 置中 | 靠右 |
|:---|:---:|---:|
| 文字 | 文字 | 文字 |
| 較長文字 | 較長文字 | 較長文字 |

表格適合展示結構化的比較資訊。但需要注意，Markdown 表格在行動裝置上的展示可能不理想，因此建議表格的欄位數控制在四欄以內，並保持每個儲存格的內容簡短。

## 分隔線

使用 `---` 建立分隔線：

---

分隔線後的內容。

分隔線適合用於在文章中標記主題的重大轉換。但不要過度使用——大多數時候，一個新的 `##` 標題就足以表示章節的轉換。

## 圖片

圖片使用標準 Markdown 語法：

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

本主題以排版為核心，但在需要時圖片同樣可以正常使用。

### 圖片使用建議

- **始終提供替代文字**：替代文字不僅有助於無障礙訪問，也是 SEO 的重要因素
- **最佳化圖片大小**：在上傳前壓縮圖片，推薦使用 WebP 格式以獲得更好的壓縮率
- **有意義的圖片名稱**：使用描述性的檔案名如 `astro-project-structure.png`，而非 `screenshot-001.png`

## 寫作風格總結

好的 Markdown 寫作不僅是正確使用語法，更是善用這些工具來組織和表達你的想法。記住以下原則：

1. **結構清晰**：使用標題建立明確的層次結構
2. **段落精煉**：每個段落聚焦一個概念
3. **善用列表**：將並列資訊轉化為列表
4. **程式碼配文字**：程式碼區塊前後都要有文字說明
5. **留白呼吸**：適當的空白讓內容更易閱讀

---

## 👋 你好，世界

URL: https://astro-theme-aither.pages.dev/zh-hant/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-hant/` 下建立 `.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-hant/posts/ai-agents-and-tool-use/
Date: 2026-01-09
Category: AI
Tags: AI, Agents
Description: AI 模型如何超越對話，在真實世界中執行操作

AI 智慧體是一個能夠執行操作的語言模型——不僅僅是生成文字。它能搜尋網頁、執行程式碼、呼叫 API、讀取檔案，並決定下一步做什麼。

## 從對話到行動

聊天機器人回答問題，智慧體解決問題。區別在於自主性：智慧體決定使用哪些工具、以什麼順序、如何處理錯誤。

這種轉變意義深遠。傳統的聊天機器人是被動的——使用者問一個問題，它給出一個回答，對話結束。智慧體則是主動的——你給它一個目標，它會自行規劃步驟、收集資訊、執行操作，直到目標達成。

舉一個具體的例子：你告訴智慧體「幫我修復這個 CI 失敗的問題」。它不是簡單地建議你怎麼做，而是：讀取 CI 日誌，分析錯誤原因，查看相關的程式碼檔案，編寫修復程式碼，執行測試確認修復有效，最後建立一個 Pull Request。整個過程中，它在每一步都做出判斷和決策。

## 工具使用

工具使用讓 AI 模型呼叫外部函式。模型判斷何時需要工具，生成正確的參數，並將結果整合到回答中。這把文字生成器變成了強大的助手。

### 工具的類型

常見的智慧體工具包括：

- **資訊檢索工具**：網頁搜尋、資料庫查詢、檔案讀取
- **程式碼執行工具**：在沙箱環境中執行 Python、JavaScript 等程式碼
- **API 呼叫工具**：與外部服務互動，如發送電子郵件、建立工單、部署應用
- **檔案操作工具**：建立、編輯、刪除檔案和目錄
- **瀏覽器操作工具**：打開網頁、點擊按鈕、填寫表單

### 工具定義

在技術實作上，工具通常以結構化的格式定義，包含名稱、描述和參數的 JSON Schema。模型根據工具描述來判斷何時以及如何使用每個工具。好的工具描述對智慧體的表現至關重要——模糊的描述會導致模型在錯誤的時機呼叫錯誤的工具。

```json
{
  "name": "search_documents",
  "description": "在知識庫中搜尋與查詢相關的文件片段",
  "parameters": {
    "query": { "type": "string", "description": "搜尋關鍵字或自然語言查詢" },
    "limit": { "type": "integer", "description": "回傳結果的最大數量", "default": 5 }
  }
}
```

## 智慧體循環

最強大的模式是智慧體循環：模型規劃一個步驟，執行它，觀察結果，然後決定下一步。這個循環持續到任務完成或模型判斷無法繼續。

### 循環的結構

一個典型的智慧體循環包含四個階段：

1. **觀察**：接收當前的環境狀態和最新的工具執行結果
2. **思考**：分析當前狀態，判斷是否已完成目標，決定下一步行動
3. **行動**：選擇並呼叫適當的工具
4. **更新**：將工具的執行結果加入對話歷史，回到觀察階段

這個循環的關鍵在於模型的**規劃能力**。優秀的智慧體不會盲目地一步步嘗試，而是在行動前先形成一個大致的計畫，然後在執行過程中根據實際結果動態調整。

### 錯誤處理

在真實世界中，工具呼叫經常失敗——API 可能返回錯誤、檔案可能不存在、網路可能超時。好的智慧體需要優雅地處理這些失敗：嘗試替代方案、向使用者請求澄清，或者承認當前任務無法完成。

## 實際應用

智慧體技術已經在多個領域展現出巨大價值：

- **軟體開發**：自動化程式碼審查、bug 修復、功能實作和測試撰寫
- **資料分析**：自動查詢資料庫、生成報表和視覺化圖表
- **客戶服務**：不僅回答問題，還能直接在後臺系統中執行操作，如退款、修改訂單
- **IT 運維**：監控系統狀態、自動排查問題、執行修復操作

## 風險

能執行操作的智慧體也能執行錯誤的操作。沙箱隔離、確認步驟和人工審查是任何生產級智慧體系統的必要安全措施。

### 安全設計原則

在設計智慧體系統時，應遵循以下原則：

- **最小權限**：只授予智慧體完成任務所需的最低權限，不要給予不必要的存取權
- **破壞性操作需確認**：刪除資料、發送通知等不可逆操作應要求使用者明確確認
- **沙箱執行**：程式碼執行應在隔離的沙箱環境中進行，防止對宿主系統造成損害
- **行為日誌**：記錄智慧體的每一個決策和操作，便於事後審計和問題排查
- **速率限制**：限制智慧體在單位時間內能執行的操作次數，防止失控的循環

智慧體技術仍在快速發展中。隨著模型推理能力和工具使用能力的提升，智慧體能夠承擔的任務複雜度也在持續增加。