strands-agents/docs 完整教學

Repository: https://github.com/strands-agents/docs Stars: 197 | Forks: 225 | Primary Language: MDX License: Apache-2.0 | Website: https://strandsagents.com Tags: agentic, agentic-ai, agents, ai, anthropic, autonomous-agents, genai, litellm, llm, machine-learning, mcp, multi-agent-systems, ollama, opentelemetry, python, bedrock, llama, openai, strands-agents

1. 專案概覽 (Project Overview)

1.1 這是什麼？

strands-agents/docs 是 Strands Agents SDK 的官方文件網站 (documentation site) 原始碼。它使用 Astro 靜態站點產生器 (static site generator; SSG) 搭配 Starlight 文件主題，將 Markdown / MDX 格式的技術文件編譯為部署在 https://strandsagents.com 的完整文件站。

Strands Agents 是由 AWS 開源的 AI Agent 開發框架 (framework)，強調 model-driven（模型驅動） 的設計哲學——讓 LLM 在 agentic loop 中自主決定下一步行動，而非用硬編碼 (hard-coded) 的工作流程限制 agent 行為。本 repo 就是這個框架的「知識入口」，涵蓋使用者指南 (user guide)、API 參考 (API reference)、部署範例 (deployment examples)、設計提案 (design proposals)、以及社群貢獻指引 (contributing guide)。

重要提醒：截至 2026-06-09，此 repo 已被 歸檔 (archived)。文件已合併至 strands-agents/harness-sdk monorepo 的 site/ 目錄下。所有新開發、Issue 和 PR 應前往 harness-sdk 提交。本教學仍具參考價值，因為文件架構、寫作規範和 CI/CD 流程的設計理念在遷移後保持不變。

1.2 誰做的？為什麼重要？

Strands Agents 是 AWS 內部孵化 (incubate) 後開源的專案，其文件站的品質直接影響開發者能否快速上手 SDK。本 repo 的獨特之處在於：

1. Agent-driven 文件工作流：內建 4 個 AI Agent Skills（docs-planner、docs-audit、docs-writer、docs-reviewer），讓 AI 代理直接參與文件的規劃、撰寫、審查與品質稽核
2. 五層語音堆疊 (Five-Layer Voice Stack)：一套完整的文件寫作規範，從結構、框架、語調到硬約束和真實感，確保所有文件風格一致
3. 多語言 SDK 支援：同時涵蓋 Python 和 TypeScript 兩個 SDK 的 API 文件，使用 Tab 切換展示
4. 11 份設計提案 (Design Documents)：記錄了整個 Strands Agents 生態系的架構決策歷程

1.3 在生態系中的定位

在 strands-agents 組織的 12 個 repo 中，docs 扮演知識中樞 (knowledge hub) 角色——所有其他 repo 的使用說明、API 文件、部署指南都匯集到這裡，由自動化管線生成 API 參考文件並編譯發佈。

2. 核心架構 (Core Architecture)

2.1 文件站技術堆疊

本文件站建立在以下技術堆疊 (tech stack) 之上：

2.2 整體架構圖

graph TB
    subgraph "內容來源 Content Sources"
        MD["Markdown / MDX 文件
site/src/content/docs/"]
        PY_SDK["Python SDK 原始碼
strands-agents/sdk-python"]
        TS_SDK["TypeScript SDK 原始碼
strands-agents/sdk-typescript"]
        NAV["navigation.yml
site/src/config/"]
        DESIGNS["設計提案
designs/"]
        EXAMPLES["程式碼範例
site/docs/examples/"]
    end

    subgraph "建置管線 Build Pipeline"
        CLONE["sdk:clone
複製 SDK repos"]
        GEN_PY["sdk:generate:py
pydoc-markdown"]
        GEN_TS["sdk:generate:ts
typedoc"]
        SIDEBAR["loadSidebarFromConfig
解析 navigation.yml"]
        REMARK["Remark 外掛
Snippet 嵌入 + 閱讀時間"]
        ASTRO["Astro Build
SSG 編譯"]
        LINK_CHECK["斷鏈檢查器
Broken Links Checker"]
    end

    subgraph "輸出 Output"
        SITE["strandsagents.com
靜態 HTML"]
        API_PY["Python API 參考"]
        API_TS["TypeScript API 參考"]
    end

    PY_SDK --> CLONE
    TS_SDK --> CLONE
    CLONE --> GEN_PY
    CLONE --> GEN_TS
    GEN_PY --> API_PY
    GEN_TS --> API_TS
    MD --> ASTRO
    NAV --> SIDEBAR
    SIDEBAR --> ASTRO
    REMARK --> ASTRO
    API_PY --> ASTRO
    API_TS --> ASTRO
    EXAMPLES --> ASTRO
    ASTRO --> LINK_CHECK
    LINK_CHECK --> SITE

2.3 Agent-Driven 文件工作流架構

本 repo 的一大亮點是內建 AI Agent Skills，形成完整的文件生命週期 (documentation lifecycle) 管理：

graph LR
    subgraph "規劃階段 Planning"
        PLANNER["docs-planner
優先排序待辦"]
    end

    subgraph "品質評估 Audit"
        AUDIT["docs-audit
評估已發佈頁面品質"]
    end

    subgraph "撰寫階段 Writing"
        WRITER["docs-writer
撰寫或重寫頁面"]
        VOICE["voice-guide.md
五層語音堆疊"]
        TERM["terminology.md
術語鎖定"]
        MDX_REF["mdx-authoring.md
MDX 格式指引"]
        CODE_VER["code-verification.md
程式碼驗證"]
    end

    subgraph "審查階段 Review"
        REVIEWER["docs-reviewer
語氣 / 風格簽核"]
    end

    subgraph "發佈 Publish"
        PR["Pull Request"]
        CI["CI 品質閘門
tests + format + typecheck"]
        DEPLOY["GitHub Pages 部署"]
    end

    PLANNER -->|"選定頁面"| AUDIT
    AUDIT -->|"發現問題"| WRITER
    VOICE --> WRITER
    TERM --> WRITER
    MDX_REF --> WRITER
    CODE_VER --> WRITER
    WRITER -->|"草稿完成"| REVIEWER
    REVIEWER -->|"退回修改"| WRITER
    REVIEWER -->|"Ship it"| PR
    PR --> CI
    CI --> DEPLOY

2.4 關鍵目錄結構

 1strands-agents/docs/
 2├── .agents/                    # AI Agent Skills 與參考資料
 3│   ├── skills/
 4│   │   ├── docs-writer/        # 文件撰寫 skill
 5│   │   ├── docs-reviewer/      # 文件審查 skill
 6│   │   ├── docs-audit/         # 品質稽核 skill
 7│   │   └── docs-planner/       # 待辦排序 skill
 8│   └── references/
 9│       ├── voice-guide.md      # 五層語音堆疊
10│       ├── terminology.md      # 術語鎖定表
11│       ├── mdx-authoring.md    # MDX 格式指引
12│       └── code-verification.md # 程式碼驗證流程
13├── .claude/skills/             # -> .agents/skills/ 的 symlink
14├── .kiro/skills/               # -> .agents/skills/ 的 symlink
15├── designs/                    # 設計提案文件 (11 份)
16├── site/                       # Astro 站點主目錄
17│   ├── astro.config.mjs        # Astro 主設定
18│   ├── SITE-ARCHITECTURE.md    # 站點架構說明
19│   ├── AGENTS.md               # Agent 開發指引
20│   ├── src/
21│   │   ├── components/         # 自訂 Astro 元件
22│   │   │   ├── overrides/      # Starlight 元件覆寫
23│   │   │   ├── landing/        # 首頁元件
24│   │   │   └── blog/           # 部落格元件
25│   │   ├── config/             # 站點設定
26│   │   │   ├── navigation.yml  # 導航結構定義
27│   │   │   └── tags.yml        # 標籤定義
28│   │   ├── content/            # 內容集合 (content collection)
29│   │   │   └── docs/           # 文件內容 (Markdown/MDX)
30│   │   ├── plugins/            # Remark / Rehype / Vite 外掛
31│   │   ├── styles/             # 全域樣式
32│   │   └── util/               # 工具函式
33│   ├── scripts/                # 建置腳本
34│   │   ├── clone-sdks.ts       # 複製 SDK repos
35│   │   ├── api-generation-python.py  # Python API 文件產生
36│   │   └── api-generation-typescript.ts # TS API 文件產生
37│   └── docs/examples/          # 可執行的部署範例
38│       ├── cdk/                # AWS CDK 部署範例
39│       ├── python/             # Python 程式範例
40│       └── typescript/         # TypeScript 程式範例
41└── .github/workflows/          # CI/CD 管線
42    ├── docs-ci.yml             # 建置 + 品質檢查
43    ├── docs-deploy-github-pages.yml  # 正式部署
44    ├── docs-deploy-preview.yml       # PR 預覽部署
45    └── docs-auto-strands-review.yml  # 自動審查

3. 安裝與設定 (Installation & Setup)

3.1 系統需求 (Prerequisites)

3.2 安裝步驟

Step 1：複製 repo

1# 由於 repo 已歸檔，建議直接從 harness-sdk monorepo 取得最新版
2git clone https://github.com/strands-agents/harness-sdk.git
3cd harness-sdk/site
4
5# 或者克隆歸檔版 (唯讀)
6git clone https://github.com/strands-agents/docs.git
7cd docs/site

Step 2：安裝 Node.js 依賴

1npm install

這會安裝所有依賴，包含 Astro、Starlight、Expressive Code、TypeDoc 等。

Step 3：複製 SDK 原始碼（API 文件產生用）

1# 自動複製 Python SDK 和 TypeScript SDK 到 .build/ 目錄
2npm run sdk:clone

Step 4：產生 API 參考文件

1# 同時產生 Python 和 TypeScript 的 API 文件
2npm run sdk:generate
3
4# 或分別執行
5npm run sdk:generate:py    # Python API (pydoc-markdown)
6npm run sdk:generate:ts    # TypeScript API (typedoc)

Step 5：啟動本地開發伺服器

1npm run dev
2# 開啟 http://localhost:4321/ 預覽文件站

一鍵完整建置

1# clone SDKs → generate API docs → build site
2npm run build:all

3.3 常用 npm scripts

4. 使用方式與程式碼範例 (Usage & Code Examples)

4.1 撰寫一頁新文件

所有文件以 Markdown 或 MDX 格式撰寫，放在 site/src/content/docs/ 目錄下。Astro 會自動發現並編譯這些檔案。

範例：建立一個新的使用者指南頁面

 1---
 2title: "自訂工具開發"
 3description: "學習如何為 Strands Agent 建立自訂工具，擴充 agent 的能力範圍。"
 4---
 5
 6## 什麼是自訂工具？
 7
 8你可以透過 `@tool` 裝飾器 (decorator) 定義 agent 可呼叫的函式。
 9每個工具接收結構化的輸入並回傳結果給 agent 的推理迴圈 (reasoning loop)。
10
11## 建立你的第一個工具
12
13<Tabs>
14<Tab label="Python">
15
16```python
17from strands import Agent, tool
18
19@tool
20def get_weather(city: str) -> str:
21    """取得指定城市的天氣資訊。"""
22    return f"{city} 目前天氣：晴天，25°C"
23
24agent = Agent(tools=[get_weather])
25response = agent("台北今天天氣如何？")
26# 典型輸出：agent 會呼叫 get_weather("台北") 並回傳天氣描述

 1import { Agent } from '@strands-agents/sdk';
 2
 3const getWeather = {
 4  name: 'get_weather',
 5  description: '取得指定城市的天氣資訊。',
 6  handler: async ({ city }: { city: string }) => {
 7    return `${city} 目前天氣：晴天，25°C`;
 8  },
 9};
10
11const agent = new Agent({ tools: [getWeather] });
12const response = await agent.invoke('台北今天天氣如何？');

逐行說明：

• Line 1-4: Frontmatter (前言區塊)——title 和 description 是必填欄位，description 建議 140-160 字元以利 SEO
• <Tabs> / <Tab>: Starlight 內建的多語言 Tab 切換元件，在此 repo 中已透過 AutoImport 自動匯入，不需要手動 import
• 程式碼區塊: 使用標準 Markdown 語法，Expressive Code 會自動套用語法高亮和主題切換

4.2 使用外部程式碼片段 (Snippet Inclusion)

為了讓程式碼範例可獨立測試，本 repo 支援 MkDocs 風格的程式碼片段嵌入語法。

Step 1：在來源檔案中標記片段

建立 site/docs/examples/python/weather_tool.py：

 1# --8<-- [start:basic_tool]
 2from strands import Agent, tool
 3
 4@tool
 5def get_weather(city: str) -> str:
 6    """取得指定城市的天氣資訊。
 7
 8    Args:
 9        city: 城市名稱
10
11    Returns:
12        天氣描述字串
13    """
14    # 實際應用中這裡會呼叫天氣 API
15    return f"{city} 目前天氣：晴天，25°C"
16# --8<-- [end:basic_tool]
17
18# --8<-- [start:agent_usage]
19agent = Agent(tools=[get_weather])
20response = agent("台北今天天氣如何？")
21print(response)
22# --8<-- [end:agent_usage]

逐行說明：

• # --8<-- [start:basic_tool]: 片段開始標記，basic_tool 是片段名稱
• # --8<-- [end:basic_tool]: 片段結束標記
• 標記註解本身不會出現在最終文件中，只有標記之間的程式碼會被嵌入

Step 2：在 MDX 檔案中引用片段

 1## 定義工具
 2
 3```python
 4--8<-- "docs/examples/python/weather_tool.py:basic_tool"
 5```
 6
 7## 使用工具
 8
 9```python
10--8<-- "docs/examples/python/weather_tool.py:agent_usage"
11```

運作原理： remark-mkdocs-snippets 外掛在建置時解析這些引用，從來源檔案中擷取對應片段並嵌入 MDX 頁面。這樣做的好處是程式碼範例可以獨立執行和測試，避免文件中出現無法執行的範例。

4.3 自訂 Starlight 元件覆寫

本 repo 對 Starlight 預設元件做了多處覆寫 (override)，以實現自訂行為：

site/src/components/overrides/Sidebar.astro — 側邊欄範圍限定

 1---
 2// Starlight 覆寫元件的基本結構
 3// Astro 在 --- 之間的是伺服器端程式碼 (server-side code)
 4import type { Props } from '@astrojs/starlight/props'
 5import Default from '@astrojs/starlight/components/Sidebar.astro'
 6---
 7
 8<!-- 
 9  這個覆寫讓側邊欄只顯示當前區段 (section) 的項目，
10  而非整個文件站的所有頁面。
11  實際的過濾邏輯在 route-middleware.ts 中處理。
12-->
13<Default {...Astro.props}><slot /></Default>

site/src/components/PageLink.astro — 相對連結解析

 1---
 2// 覆寫預設 <a> 元素，讓 MkDocs 風格的相對路徑連結正常運作
 3import { resolveRelativeLink, isApiShorthand, resolveApiShorthand } from '../util/links'
 4
 5interface Props {
 6  href?: string
 7  [key: string]: any
 8}
 9
10const { href: rawHref, ...rest } = Astro.props
11let href = rawHref
12
13// 處理 @api 簡寫語法
14// 例如 @api/python/strands.agent.agent → /docs/api/python/strands.agent.agent/
15if (href && isApiShorthand(href)) {
16  href = resolveApiShorthand(href, Astro.site?.pathname || '/')
17}
18// 處理相對檔案路徑
19// 例如 ../tools/custom-tools.md → /user-guide/concepts/tools/custom-tools/
20else if (href && !href.startsWith('http') && !href.startsWith('#')) {
21  href = resolveRelativeLink(href, Astro.url.pathname, Astro.site?.pathname || '/')
22}
23---
24
25<a href={href} {...rest}><slot /></a>

逐行說明：

• isApiShorthand(): 檢測 @api/python/... 或 @api/typescript/... 格式的連結
• resolveApiShorthand(): 將簡寫轉換為完整 URL 路徑
• resolveRelativeLink(): 將 ../tools/custom-tools.md 這類 MkDocs 風格的相對路徑轉換為 Astro 的 slug-based URL
• 這個覆寫透過 astro-auto-import 的 defaultComponents 設定，全域替換所有 <a> 標籤

4.4 定義導航結構

導航結構由 site/src/config/navigation.yml 驅動，不依賴 Astro 的自動發現 (auto-discovery)：

 1# navigation.yml — 定義側邊欄與頂端標籤的結構
 2navbar:
 3  - label: User Guide
 4    slug: user-guide
 5  - label: Examples
 6    slug: examples
 7  - label: API
 8    slug: api
 9  - label: Community
10    slug: community
11
12sidebar:
13  - group: User Guide
14    items:
15      - group: Getting Started
16        items:
17          - page: Quickstart
18            path: user-guide/quickstart.mdx
19          - page: Installation
20            path: user-guide/installation.mdx
21      - group: Concepts
22        collapsed: true    # 預設折疊此群組
23        items:
24          - group: Agents
25            items:
26              - page: Overview
27                path: user-guide/concepts/agents/index.mdx
28              - page: State Management
29                path: user-guide/concepts/agents/state.mdx
30          - group: Tools
31            items:
32              - page: Custom Tools
33                path: user-guide/concepts/tools/custom-tools.mdx
34              - page: MCP Tools
35                path: user-guide/concepts/tools/mcp-tools.mdx

重點說明：

• navbar 定義頂端標籤頁 (tabs)，sidebar 定義左側導航樹
• collapsed: true 讓群組預設折疊，在 route-middleware.ts 中由 applyCollapse() 處理
• Badge（如 “new”、“experimental”）來自各頁面的 frontmatter，不在 navigation.yml 中定義
• loadSidebarFromConfig() 在建置時驗證所有路徑是否對應到實際存在的內容檔案

5. 進階功能 (Advanced Features)

5.1 五層語音堆疊 (Five-Layer Voice Stack)

本 repo 定義了一套精密的文件寫作規範，確保所有內容風格一致。這五層從結構到表面呈現依序為：

Layer 2 的實際應用範例：

1<!-- 正確 — 以開發者目標開頭 -->
2你可以透過傳入工具清單到建構函式來建立具備自訂工具的 agent。
3
4<!-- 錯誤 — 以 API 能力開頭 -->
5Agent class 的建構函式接受一個 tools 參數。

Layer 4 硬約束包含：

• 禁用 em-dash (—) 破折號
• 禁用 emoji
• 禁用 AI 常見用語（如 “harness the power”、“unleash”、“seamlessly”）
• 所有程式碼範例必須可直接複製執行（imports 齊全、變數已定義）
• 術語嚴格鎖定（“Tool” 不可寫成 “function”、“Hook” 不可寫成 “callback”）

5.2 路由中介層 (Route Middleware)

site/src/route-middleware.ts 在建置時過濾側邊欄，實現區段隔離：

• 一般頁面：只顯示該頁面所屬的頂層群組 (top-level group)，避免使用者在 User Guide 時看到 Community 的導航
• Python API 頁面：動態產生基於模組名稱的巢狀側邊欄（例如 strands.agent.agent 變成 Agent > Agent）
• TypeScript API 頁面：按類別分組（Classes、Interfaces、Type Aliases、Functions）
• 分頁導航 (Pagination)：修正 Starlight 預設的 prev/next 連結，確保只在同一區段內導航

5.3 MkDocs 相容性外掛

由於本 repo 從 MkDocs 遷移至 Astro，保留了多項相容機制：

1. remark-mkdocs-snippets: 處理 --8<-- "path/to/file:section" 語法，從外部檔案嵌入程式碼片段
2. PageLink 相對路徑解析: 將 ../tools/custom-tools.md 轉換為 Astro slug URL
3. @api 簡寫: @api/python/strands.agent.agent#AgentResult 轉換為完整 API 參考連結

5.4 自動化 API 文件產生

API 參考文件不是手動撰寫的，而是從 SDK 原始碼自動產生：

1# Python: 使用 pydoc-markdown 從 docstring 產生 Markdown
2uv run scripts/api-generation-python.py
3
4# TypeScript: 使用 typedoc 從 JSDoc / TSDoc 產生 Markdown
5tsx scripts/api-generation-typescript.ts

產生的文件透過 symlink 連結到 site/src/content/docs/api/ 下：

• site/src/content/docs/api/python/_generated/ → .build/api-docs/python/
• site/src/content/docs/api/typescript/_generated/ → .build/api-docs/typescript/

5.5 自訂 Frontmatter 欄位

除了 Starlight 預設的 frontmatter 欄位，本 repo 擴充了以下自訂欄位：

5.6 設計提案系統 (Design Documents)

designs/ 目錄收錄了 11 份重要的架構設計提案，記錄 Strands Agents 生態系的設計決策：

提交新設計提案的流程：Fork repo → 使用模板建立 designs/NNNN-feature-name.md → 提交 PR → 審查 → 合併 → 實作。

6. Agent 可呼叫性分析 (Agent Callability)

6.1 CLI 介面

本 repo 的 CLI 介面透過 npm scripts 暴露，適合在 CI/CD 管線或本機開發中呼叫：

 1# 建置站點（可用於 CI 管線中的品質閘門）
 2npm run build
 3
 4# 型別檢查（可整合到 pre-commit hook）
 5npm run typecheck
 6
 7# 格式檢查
 8npm run format:check
 9
10# 執行測試
11npm test

6.2 Agent Skills（AI Agent 整合）

本 repo 提供 4 個 AI Agent Skills，可直接在 Claude Code、Kiro 等 AI 開發工具中使用：

鏈式呼叫範例（/goal 指令）：

1/goal https://github.com/strands-agents/sdk-typescript/commit/<sha>
2
31. /docs-planner: 找出受此 commit 影響的最高優先頁面
42. /docs-audit: 檢查該頁面的品質問題
53. /docs-writer: 修正問題
64. /docs-reviewer: 簽核，不通過則退回 step 3
7   （語氣/風格問題回 step 3；結構問題回 step 2 或 step 1）
8   上限 3 次重試，超過則升級處理。

6.3 GitHub Actions CI/CD

本 repo 定義了 5 條 GitHub Actions 工作流 (workflow)：

6.4 API 整合潛力

雖然本 repo 本身不暴露 REST API，但產出的靜態站點可透過以下方式被其他系統消費：

• Sitemap: 自動產生 sitemap.xml，包含基於 Git 的 <lastmod> 日期
• RSS/Atom: 透過 @astrojs/rss 支援部落格文章的 feed 訂閱
• 內容集合 (Content Collection): Astro 的內容集合 API 可用於程式化存取所有文件的 metadata

7. 與生態系的關係 (Ecosystem Relationships)

7.1 Strands Agents 組織 12 個 Repo 總覽

strands-agents/docs 是整個生態系的文件匯聚點，以下是它與其他 repo 的關係：

graph TB
    DOCS["strands-agents/docs
📚 文件站（已歸檔）
→ 合併至 harness-sdk"]

    subgraph "核心 SDK Core SDKs"
        PY["sdk-python
🐍 Python SDK"]
        TS["sdk-typescript
📘 TypeScript SDK"]
    end

    subgraph "工具與擴充 Tools & Extensions"
        TOOLS["tools
🔧 內建工具集"]
        MCP["mcp-server
🔌 MCP 伺服器"]
    end

    subgraph "開發體驗 Developer Experience"
        BUILDER["agent-builder
🏗️ 視覺化建構器"]
        SAMPLES["samples
📝 範例程式碼"]
    end

    subgraph "平台整合 Platform"
        HARNESS["harness-sdk
🏢 Monorepo（新家）"]
    end

    PY -->|"API 文件產生
pydoc-markdown"| DOCS
    TS -->|"API 文件產生
typedoc"| DOCS
    TOOLS -->|"工具使用指南"| DOCS
    MCP -->|"MCP 整合教學"| DOCS
    BUILDER -->|"建構器使用教學"| DOCS
    SAMPLES -->|"範例程式碼嵌入"| DOCS
    DOCS -->|"合併遷移"| HARNESS

7.2 具體關係說明

7.3 與 harness-sdk 的合併脈絡

設計提案 0009-mono-repository.md 記錄了將多個 repo 合併為 monorepo 的決策過程。docs repo 是最早被合併的項目之一，因為文件站的建置依賴 SDK 原始碼——放在同一個 repo 能大幅簡化 CI/CD 管線。

8. 優缺點分析 (Strengths & Limitations)

8.1 優勢 (Strengths)

8.2 限制 (Limitations)

9. 實戰應用場景 (Real-world Use Cases)

9.1 場景一：為新 SDK 功能撰寫文件

情境：SDK 團隊在 sdk-python 中加入了新的 memory 模組，需要更新文件。

操作流程：

1. 同步 SDK 原始碼

1cd docs/site
2npm run sdk:sync
3# 自動 clone 最新 SDK + 重新產生 API 文件

2. 使用 docs-planner 確認優先序

1/docs-planner
2→ 分析 SDK 變更歷史，找出 memory 模組相關的文件缺口
3→ 回傳優先排序：1. Memory Overview 頁面（新建）2. Agent State 頁面（更新）

3. 使用 docs-writer 撰寫新頁面

1/docs-writer
2Content type: tutorial
3Topic: Memory management for long-running agents
4Target file: user-guide/concepts/agents/memory.mdx

4. docs-writer 自動執行 docs-reviewer 簽核

1→ docs-reviewer 檢查五層語音堆疊合規性
2→ "Ship it" → 準備 PR
3→ 或退回 → docs-writer 修改後重新提交

5. 提交 PR 觸發 CI

1git checkout -b agent-tasks/add-memory-docs
2git add site/src/content/docs/user-guide/concepts/agents/memory.mdx
3git commit -m "docs: add memory management tutorial"
4git push -u origin agent-tasks/add-memory-docs
5# CI 自動執行：build + typecheck + format:check + 斷鏈檢查
6# PR 預覽自動部署

9.2 場景二：審查並改善現有文件品質

情境：團隊發現 Quickstart 頁面的使用者跳出率 (bounce rate) 過高，需要改善。

操作流程：

1. 使用 docs-audit 評估現有頁面

1/docs-audit site/src/content/docs/user-guide/quickstart.mdx
2→ 回傳品質報告：
3  - 結構問題：前三段落沒有說明「為什麼用 Strands」
4  - 框架問題：開頭以 API 能力而非開發者目標描述
5  - 程式碼問題：第二個範例缺少 import 語句

2. 使用 docs-writer 重寫

1/docs-writer
2Content type: tutorial
3Topic: Quickstart rewrite
4Existing content: site/src/content/docs/user-guide/quickstart.mdx
5Context: High bounce rate, audit findings

3. docs-reviewer 自動在 Step 7 簽核或退回

9.3 場景三：建立團隊內部的文件站範本

情境：另一個開源專案想要仿照 Strands Agents 的文件站架構，建立自己的技術文件。

可重用的設計模式：

1. 五層語音堆疊：直接複製 .agents/references/voice-guide.md 並調整為自己的品牌語調
2. Agent Skills 框架：複製 .agents/skills/ 結構，修改每個 SKILL.md 中的觸發條件和流程
3. 導航設定分離：採用 navigation.yml + loadSidebarFromConfig() 的模式，將導航結構與內容分離
4. MkDocs 遷移路徑：若現有文件使用 MkDocs，可直接借用 remark-mkdocs-snippets 和 PageLink 覆寫
5. CI/CD 管線：參考 .github/workflows/ 中的 5 條工作流設定

快速啟動模板：

 1# 1. 使用 Astro + Starlight 建立新專案
 2npm create astro@latest -- --template starlight
 3
 4# 2. 從 strands-agents/docs 複製自訂元件
 5cp -r strands-agents-docs/.agents/ my-docs/.agents/
 6cp -r strands-agents-docs/site/src/plugins/ my-docs/src/plugins/
 7cp -r strands-agents-docs/site/src/components/overrides/ my-docs/src/components/overrides/
 8
 9# 3. 設定 navigation.yml
10cp strands-agents-docs/site/src/config/navigation.yml my-docs/src/config/
11
12# 4. 調整 astro.config.mjs 中的外掛和覆寫設定
13# 參考本教學 §4.3 和 §4.4 的說明

附錄：快速參考卡

常用指令

內容類型對照

Agent Skills 快速觸發