Claude Opus 4.5 教程：构建 GitHub Wiki 代理

许多现代 GitHub 仓库缺乏清晰、结构化的文档，尤其是 wiki。

手动创建这些页面常常需要花费数小时阅读代码、理解架构并组织内容。

GitHub Wiki AI 代理可以解决这个问题。

在本教程中，我将带您构建一个全自动的 GitHub Wiki AI 代理——一个使用 Claude Opus 4.5 和 Claude Agent SDK 的命令行工具，只需一条指令即可生成完整的 GitHub 仓库 wiki。

该工具无需您手动撰写文档，会自动分析您的代码库、理解其结构，并产出干净、规范的多页面 wiki 内容，随后自动提交并发布到您的仓库。

一切都通过一个交互式 CLI 应用运行，体验快速、智能且对开发者友好。

在本指南中，我们将按照三个简单步骤来配置环境、构建 GitHub Wiki AI 代理，并在真实仓库上进行测试：

1. 环境配置： 安装依赖，安装并登录 Claude Code，配置 GitHub 令牌，并启用 Wiki 功能。
2. 构建应用： 创建 CLI 工具、配置 Claude Agent、集成 MCP GitHub 工具、添加成本跟踪，并实现 wiki 生成逻辑（首页、快速开始、架构与工具）。
3. 测试代理： 在真实仓库（ECom-Intel 和 Issue-Analyzer）上运行，验证克隆、分析、wiki 创建和自动推送。

如果您刚接触 AI 代理并想进一步了解，建议查看 AI Agent Fundamentals 技能路径。您还应阅读我们的Claude Cowork 教程以及关于全新 Claude Opus 4.6 的指南。

为 Claude Opus 4.5 GitHub Wiki 教程配置您的环境

在构建 基于 Opus 4.5 的 GitHub Wiki 代理 之前，请确保您的环境已正确配置。本节将带您完成所有前置条件与设置步骤。

1. 运行 Claude Opus 4.5 Wiki 代理的前置条件

• Python 3.11 或更高版本（Python Claude Agent SDK 要求）。
• Node.js 和 npm（安装 Claude Code 所需），这是我们应用的基础，提供代理、工具以及 MCP 服务器的集成。

2. 安装并认证 Claude Code

打开终端（命令提示符、PowerShell 或 macOS Terminal），运行以下命令安装 Claude Code CLI：

npm install -g @anthropic-ai/claude-code技术支持

在终端中输入 claude 启动 Claude Code。然后在 Claude 聊天中输入 /login 进行认证，以访问 Opus 4.5 模型和工具，如下所示。

您可以在我们的实操教程中进一步了解 Claude Code。

3. 生成精细化 GitHub 个人访问令牌

要生成精细化 GitHub 个人访问令牌，请前往 GitHub 并导航至：

Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens。

创建新令牌，并在 Repository 部分选择您将使用的仓库。随后配置权限。出于安全考虑，建议将令牌设置为较短的过期时间。

然后，将个人访问令牌设置为环境变量：

export GITHUB_PAT="your-github-personal-access-token"技术支持

4. 初始化您的 GitHub Wiki

GitHub 目前不支持先在本地创建 Wiki。

因此，您必须手动初始化 wiki，步骤如下：

1. 在 GitHub 上打开您的仓库
2. 点击 Wiki 选项卡
3. 点击 “Create the first page”
4. 保存页面（任意标题均可）

5. 安装 Claude Agent SDK

我们将安装 Claude 代理框架，它负责从使用 MCP 到调用工具、创建文件以及将更改推送到远程的一切工作。

pip install claude-agent-sdk技术支持

使用 Claude Opus 4.5 构建自动 Wiki 代理

我们将创建一个名为 gh_wiki_cli.py 的 Python CLI 应用。该文件将包含配置、代理、工具、MCP 客户端、系统提示、CLI 应用本身以及辅助函数。

这些组件将确保用户提供仓库链接后，代理能够正确处理并发布 GitHub wiki。

1. 导入

此部分引入 Python 标准库模块、类型辅助工具和 Claude Agent SDK。

• asyncio 用于异步 I/O（聊天与流式传输）。
• os、sys 用于环境变量与退出。
• dataclass 用于追踪统计数据。
• Claude Agent SDK 导入用于与代理和 MCP 工具交互。

import asyncio
import os
import sys
from dataclasses import dataclass
from typing import Dict

# --- SDK Imports ---
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    McpSdkServerConfig,
    ResultMessage,
    TextBlock,
    ToolResultBlock,
    ToolUseBlock,
)技术支持

2. 系统提示（System prompt）

这是代理的“脑子”。我们将指导 Opus 4.5 模型如何表现以及如何使用工具。

SYSTEM_PROMPT = """
        You are an expert Technical Writer and GitHub Wiki specialist.

        TOOLS
        - Read, Write, Glob, Grep:
        - Use these to inspect files and folders in the project directory (e.g. /tmp/Issue-Analyzer) and in wiki_clone/.
        - Use them to list files, read contents, and search for patterns.
        - Write:
        - Use this ONLY to write or update three wiki pages inside wiki_clone/:
            - wiki_clone/Home.md
            - wiki_clone/Getting-Started.md
            - wiki_clone/Architecture-and-Tools.md
        - Bash:
        - Bash is ONLY allowed for git commands, never for inspection or editing.
        - Allowed commands (with cd wiki_clone/ when needed):
            - git clone <repo>.wiki.git wiki_clone  (if wiki_clone does not already exist)
            - git status
            - git add .
            - git commit -m "Update wiki"
            - git push
        - Do NOT use Bash for ls, cat, grep, find, python, or any other way of reading/writing files.

        WORKFLOW
        1. When the user gives a GitHub repo URL:
        - Use Bash to clone the wiki if wiki_clone/ does not already exist:
            git clone <repo>.wiki.git wiki_clone
        2. Use Read/Glob/Grep (and any GitHub MCP tools) to explore the project:
        - Read important files in the project folder (e.g. README, docs/, src/).
        - Use that information to generate documentation.
        3. Use Write to create or update ONLY:
        - wiki_clone/Home.md
        - wiki_clone/Getting-Started.md
        - wiki_clone/Architecture-and-Tools.md
        4. When the wiki pages are ready:
        - Use Bash from wiki_clone/ to:
            git add .
            git commit -m "Update wiki"
            git push

        RULES
        - You may READ from the whole project directory and wiki_clone/.
        - You may WRITE only to the three wiki pages inside wiki_clone/.
        - Never use Bash to inspect or edit files; only use it for git commands.
        - Keep documentation clear, concise, and in GitHub Wiki style.
        """技术支持

3. CLI 的颜色处理

这会让 CLI 输出更美观，但即使未安装 colorama 也能正常运行。

• 尝试使用 colorama 显示彩色文本。
• 回退为 MockColors，以便脚本仍可运行（无颜色但不会崩溃）。

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

    class MockColors:
        def __getattr__(self, name):
            return ""

    Fore = Style = MockColors()技术支持

4. 会话统计追踪

一个小型 dataclass，用于记录成本、轮次和时长。

• total_cost：Claude SDK 返回的美元成本之和。
• total_turns：您发送了多少个用户查询。
• duration_ms：累计时长（毫秒）。

@dataclass
class SessionStats:
    total_cost: float = 0.0
    total_turns: int = 0
    duration_ms: int = 0技术支持

5. 创建代理选项

接下来，我们将创建 ClaudeAgentOptions 对象并连接 MCP 服务器。以下函数会验证所需环境变量、在可用时配置 GitHub MCP 服务器，并限制代理可使用的工具。

我们特意限制 allowed_tools，使 Opus 4.5 可以：使用 Bash 进行 Git 操作，调用 GitHub MCP 服务器检查仓库内容，并使用 Read/Write（配合 Glob 和 Grep）来处理和校验本地 Markdown 文件。

def create_agent_options() -> ClaudeAgentOptions:
    """Validates env vars and configures the agent options."""
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
    github_pat = os.getenv("GITHUB_PAT")

    if not anthropic_key:
        print(
            f"{Fore.RED}Error: ANTHROPIC_API_KEY environment variable is required.{Style.RESET_ALL}"
        )
        sys.exit(1)

    # Configure MCP servers
    mcp_servers: Dict[str, McpSdkServerConfig] = {}
    if github_pat:
        mcp_servers["github"] = {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": f"Bearer {github_pat}"},
        }

    return ClaudeAgentOptions(
        model="claude-opus-4-5",
        system_prompt=SYSTEM_PROMPT,
        mcp_servers=mcp_servers,
        permission_mode="bypassPermissions",
        allowed_tools=[
            "Read",
            "Write",
            "Glob",
            "Grep",
            "Bash",
            "mcp__github__*",
        ],
    )技术支持

6. 处理流式响应

该函数监听流，并打印文本、工具使用与工具输出。

• 将 client.receive_response() 作为异步流使用。
• 实时打印助手输出文本。
• 调用 工具时 → 打印 [Tool Use: ...]。
• 返回输出 的工具 → 进行截断并打印单行预览。
• 当收到 ResultMessage → 用成本与时长更新 SessionStats。

async def process_response_stream(client: ClaudeSDKClient, stats: SessionStats):
    """Handles the stream of messages from the agent."""
    async for message in client.receive_response():
        # 1. Handle Assistant Content (Text & Tool Requests)
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="", flush=True)
                elif isinstance(block, ToolUseBlock):
                    print(f"\n{Fore.CYAN}[Tool Use: {block.name}]{Style.RESET_ALL}")

        # 2. Handle Tool Results (Outputs)
        if hasattr(message, "content") and isinstance(message.content, list):
            for block in message.content:
                if isinstance(block, ToolResultBlock):
                    # Truncate output for cleaner CLI
                    raw_output = str(block.content)
                    clean_output = raw_output.replace("\n", " ")
                    short_output = (
                        clean_output[:200] + "..."
                        if len(clean_output) > 200
                        else clean_output
                    )
                    print(
                        f"{Fore.YELLOW}  -> [Output]: {short_output}{Style.RESET_ALL}"
                    )

        # 3. Handle Result Metrics (Cost & Usage)
        if isinstance(message, ResultMessage):
            if message.total_cost_usd:
                stats.total_cost += message.total_cost_usd
            if message.duration_ms:
                stats.duration_ms += message.duration_ms技术支持

7. 结束时打印摘要

为 CLI 应用提供良好的会话结束统计，显示轮次、时长与美元成本。

• 将 duration_ms 转换为秒。
• 以 4 位小数显示总成本。

def print_summary(stats: SessionStats):
    """Prints the final session statistics."""
    print(f"\n\n{Fore.GREEN}=== Session Summary ==={Style.RESET_ALL}")
    print(f"Total Turns:   {stats.total_turns}")
    print(f"Duration:      {stats.duration_ms / 1000:.2f}s")
    print(f"Total Cost:    ${stats.total_cost:.4f}")
    print(f"{Fore.GREEN}======================={Style.RESET_ALL}")技术支持

8. 主异步函数

这是应用的核心控制流：负责设置、连接服务、读取用户输入并发送查询。该函数调用 create_agent_options() 并初始化统计信息。它会打印引导横幅并显示启用的 MCP 服务器。还会通过异步上下文创建 ClaudeSDKClient。

该应用运行一个简单的 REPL（读取-求值-打印循环）：

1. 输入 'exit' 或 'quit' 可退出应用。
2. stats.total_turns 每收到一个有效查询加 1。
3. await client.query(user_input) 发送用户消息。
4. await process_response_stream(...) 打印流式结果。
5. 任何异常都会被捕获，并以红色显示错误消息。
6. 最后总会调用 print_summary(stats)。

async def main():
    options = create_agent_options()
    stats = SessionStats()

    # Welcome message
    print(f"{Fore.GREEN}=== GitHub Wiki AI Agent (Auto-Mode) ==={Style.RESET_ALL}")
    print(
        f"MCP Servers: {', '.join(options.mcp_servers.keys()) if options.mcp_servers else 'None'}"
    )
    print("Ask me to help with a GitHub wiki by mentioning the repository URL!")
    print("Type 'exit' to quit.\n")

    async with ClaudeSDKClient(options=options) as client:
        try:
            await client.connect()

            while True:
                try:
                    user_input = input(f"\n{Fore.BLUE}>> {Style.RESET_ALL}").strip()
                except EOFError:
                    break

                if not user_input:
                    continue

                if user_input.lower() in ["exit", "quit"]:
                    break

                stats.total_turns += 1

                # Send query
                await client.query(user_input)
                print()  # Spacer

                # Process response stream using helper function
                await process_response_stream(client, stats)

        except Exception as e:
            print(f"\n{Fore.RED}Session Error: {e}{Style.RESET_ALL}")
        finally:
            print_summary(stats)技术支持

9. 脚本入口点

最后，我们定义脚本的入口点，以便在直接执行文件时运行 CLI。以下代码块启动主异步循环，并实现优雅退出：

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nSession interrupted.")
        sys.exit(0)技术支持

测试自动 Wiki 代理

安装完成后，启动 CLI 聊天应用，确认您的 Claude Code CLI 应用正常工作：

python gh_wiki_cli.py技术支持

您现在可以像在聊天界面中一样与代理交互。 可以提出一般性问题，或直接让它为您的仓库构建 wiki：

create the github wiki for https://github.com/kingabzpro/ECom-Intel技术支持

当用户请求创建 wiki 时，代理会自动执行：

1. Wiki 克隆： 创建或复用 wiki_clone/ 文件夹并拉取最新 wiki 内容。
2. 仓库检查： 使用 MCP 工具读取 GitHub 仓库中的关键文件。
3. 页面生成： 自动起草并写入如下页面：
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. 提交与推送： 代理对新页面进行暂存、提交，并将更新推送至：<your-repo>.wiki.git
5. 成功输出示例： 完成后，您会看到简洁的确认信息。 Wiki 将上线于：https://github.com/kingabzpro/ECom-Intel/wiki

让我印象深刻的是，代理能够很好地收集演示图片、图表和其他关键信息，并据此组装出结构清晰的 wiki 首页。

该 wiki 现已包含合适的目录、对助手与工具的说明，以及清晰的“快速开始”指引。

在本次运行结束时，会话摘要显示本次会话成本接近 1 美元，这对于生成三页 wiki 来说相对较高。如果仓库更大、例如需要一个 12 页的 wiki，成本会显著上升。

=== Session Summary ===
Total Turns:   1
Duration:      282.99s
Total Cost:    $0.9047
=======================技术支持

在第二次测试中，我让代理为另一个仓库创建 wiki：

create the github wiki for https://github.com/kingabzpro/Issue-Analyzer技术支持

结果更为出色。生成的 wiki（可在 https://github.com/kingabzpro/Issue-Analyzer/wiki 查看）现已包含规范的文档，说明了项目的作用及如何上手。

其中包括结构良好的表格、架构图，以及其他核心部分，让您大约用五分钟即可理解整个项目，而无需花费数天阅读代码。

结语

当我第一次听说 Opus 4.5 被誉为全球最强的编码与代理模型时，我确实很兴奋，尤其是它的定价与 Sonnet 系列相近。

然而，当我意识到仅仅为了试验并构建一个小型应用竟然花费了约 15 美元的 API 用量时，我的热情有所下降。

Opus 4.5 功能强大但成本较高。我也尝试用 Haiku 和 Sonnet 复现相同流程，但对于这类以代理与文档为主的任务，体验明显不如。

二者常常回退到使用 Bash 工具，即便我明确要求使用 MCP 工具读取 GitHub 文件。此外，它们往往采取更长、更迂回的路径解决问题。

如果您更看重准确性、可靠性以及高质量的代码与文档生成，Opus 4.5 的确值得考虑。

但如果您的场景并非关键，或对成本非常敏感，或许可以继续使用 Sonnet，甚至更便宜的开源模型。对于跨大型仓库的多步骤代理工作流，Opus 4.5 的成本会很快攀升。

如果您对该项目有兴趣，可在此找到完整源代码，克隆后即可在本地运行：kingabzpro/GitHub-Wiki-Agent。

如果您还想继续构建 AI 代理，推荐查看 Multi-Agent Systems with LangGraph 课程。