164 lines
6.3 KiB
Markdown
164 lines
6.3 KiB
Markdown
---
|
||
title: "Claude 集成与使用指南"
|
||
status: summer
|
||
created: 2025-08-17
|
||
owner: Claude
|
||
review_by: "2026-02-17"
|
||
tags: ["guide", "claude", "core"]
|
||
---
|
||
|
||
# Claude 集成与使用指南
|
||
|
||
本指南介绍如何在炼妖壶项目中使用 Claude，包括运行时模型接入、GitHub 代码审查助手（可选）以及常见问题排查。此文档面向公开文档；更详细或偏内部的安装步骤请参考内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md`。
|
||
|
||
## 适用场景
|
||
|
||
- 在项目中调用 Claude 模型（通过 LiteLLM/OpenRouter/Anthropic）用于分析、辩论与推理
|
||
- 在 GitHub 的 Issue/PR 中通过评论触发 Claude 进行代码审查、调试辅助与架构讨论（可选）
|
||
|
||
## 快速开始（运行时模型）
|
||
|
||
项目推荐通过 LiteLLM 路由到不同模型供应商。你可以选择两种常见方式接入 Claude：
|
||
|
||
- 方式 A：使用 OpenRouter 免费路由（如 `anthropic/claude-3.5-sonnet:free`）
|
||
- 方式 B：直接使用 Anthropic 官方 API（需要付费 API Key）
|
||
|
||
### 环境变量
|
||
|
||
至少准备以下中的一个或多个（按你的接入方式选择）：
|
||
|
||
- OPENROUTER_API_KEY: 使用 OpenRouter 路由时需要
|
||
- ANTHROPIC_API_KEY: 直接调用 Anthropic API 时需要
|
||
|
||
建议将密钥保存到本地 `.env` 或 CI/CD 的 Secret 中，不要提交到仓库。
|
||
|
||
### LiteLLM 配置提示
|
||
|
||
仓库中 `litellm/config.yaml` 是示例配置。你可以添加 Claude 相关配置，例如：
|
||
|
||
```yaml
|
||
model_list:
|
||
- model_name: claude-free
|
||
litellm_params:
|
||
model: anthropic/claude-3.5-sonnet:free
|
||
# 如果使用 OpenRouter，请在运行环境里提供 OPENROUTER_API_KEY
|
||
|
||
- model_name: claude-sonnet
|
||
litellm_params:
|
||
model: anthropic/claude-3-5-sonnet-20240620
|
||
# 如果直接使用 Anthropic 官方，请在运行环境里提供 ANTHROPIC_API_KEY
|
||
```
|
||
|
||
> 提示：内部文档 `internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md` 与 `internal/technical/Final_Baxian_Sanqing_Model_Configuration.md` 描述了项目在三清八仙体系中对 Claude 的模型分配建议，可作为策略参考。
|
||
|
||
## GitHub 助手（可选）
|
||
|
||
如果你希望在 GitHub 的 Issue/PR 评论中 @Claude 进行协助，请按以下步骤配置。若当前仓库没有工作流文件，请根据下面示例新建。
|
||
|
||
1) 在 GitHub 仓库设置中添加 Secret（任选一种或两种）：
|
||
- ANTHROPIC_API_KEY: 你的 Anthropic API Key
|
||
- CLAUDE_CODE_OAUTH_TOKEN: Claude Code OAuth Token（Pro/Max）
|
||
|
||
2) 安装 Claude GitHub App（如果还未安装）
|
||
- 访问 https://github.com/apps/claude
|
||
- 选择安装到你的仓库并授权必要权限
|
||
|
||
3) 新建或更新工作流文件 `.github/workflows/claude.yml`
|
||
|
||
```yaml
|
||
name: Claude Assistant
|
||
|
||
on:
|
||
issue_comment:
|
||
types: [created]
|
||
pull_request_review_comment:
|
||
types: [created]
|
||
|
||
jobs:
|
||
run-claude:
|
||
if: contains(github.event.comment.body, '@claude') || contains(github.event.comment.body, '@太公') || contains(github.event.comment.body, '@八仙')
|
||
runs-on: ubuntu-latest
|
||
permissions:
|
||
contents: read
|
||
issues: write
|
||
pull-requests: write
|
||
|
||
steps:
|
||
- name: Checkout
|
||
uses: actions/checkout@v4
|
||
|
||
- name: Set up Python
|
||
uses: actions/setup-python@v5
|
||
with:
|
||
python-version: '3.11'
|
||
|
||
- name: Install deps
|
||
run: |
|
||
python -m pip install --upgrade pip
|
||
pip install litellm
|
||
|
||
- name: Run Claude reply
|
||
env:
|
||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
|
||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||
run: |
|
||
python - <<'PY'
|
||
import os, json, requests
|
||
|
||
body = os.environ.get('GITHUB_EVENT_PATH')
|
||
import sys, pathlib
|
||
event = json.load(open(os.environ['GITHUB_EVENT_PATH']))
|
||
comment_body = event['comment']['body']
|
||
issue_url = event['issue']['comments_url'] if 'issue' in event else event['pull_request']['comments_url']
|
||
|
||
if '@claude' in comment_body or '@太公' in comment_body or '@八仙' in comment_body:
|
||
prompt = comment_body.replace('@claude','').replace('@太公','').replace('@八仙','').strip()
|
||
else:
|
||
sys.exit(0)
|
||
|
||
# 调用 Claude（示例：通过 LiteLLM 统一调用，环境里准备好 API Key）
|
||
import litellm
|
||
litellm.set_verbose(False)
|
||
resp = litellm.completion(model="anthropic/claude-3.5-sonnet:free", messages=[{"role":"user","content":prompt}])
|
||
text = resp.choices[0].message.get('content') if hasattr(resp.choices[0], 'message') else resp['choices'][0]['message']['content']
|
||
|
||
headers = {"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}", "Accept": "application/vnd.github+json"}
|
||
requests.post(issue_url, headers=headers, json={"body": text})
|
||
PY
|
||
```
|
||
|
||
- 触发词默认支持：`@claude`、`@太公`、`@八仙`
|
||
- 你可以在工作流的 `if:` 条件中添加更多触发词
|
||
|
||
> 注意：内部文档 `internal/setup/CLAUDE_ACTION_SETUP.md` 提供了更完整的 Action 版配置与触发词说明。
|
||
|
||
## 使用示例
|
||
|
||
- 代码审查：
|
||
- 在 PR 评论中输入：`@claude 请审查这个MCP管理器的实现，关注安全性和性能`
|
||
- 功能实现建议：
|
||
- 在 Issue 评论中输入：`@claude 帮我实现一个新的Yahoo Finance数据获取功能`
|
||
- 架构讨论：
|
||
- 在评论中输入：`@太公 如何优化当前的金融数据分析流程？`
|
||
- 调试帮助：
|
||
- 在评论中输入：`@八仙 这个错误是什么原因：[粘贴错误信息]`
|
||
|
||
## 成本与安全
|
||
|
||
- API 成本：使用 Anthropic 直连会产生费用；OpenRouter 免费路由有速率与配额限制
|
||
- 权限：GitHub App 与工作流权限请最小化配置
|
||
- 敏感信息：不要在公开评论中包含敏感数据；密钥请使用 Secret 管理
|
||
|
||
## 常见问题排查
|
||
|
||
- 无法调用成功：确认已在运行环境设置了相应的 API Key（`OPENROUTER_API_KEY` 或 `ANTHROPIC_API_KEY`）
|
||
- 工作流未触发：确认评论中包含触发词，且仓库已启用 `Actions`；检查 `if:` 条件
|
||
- 响应为空或报错：降低请求长度，检查模型名称是否正确，或改用其他可用模型
|
||
|
||
## 参考
|
||
|
||
- 内部：`internal/setup/CLAUDE_ACTION_SETUP.md`
|
||
- 内部：`internal/technical/Final_Baxian_Sanqing_Model_Configuration.md`
|
||
- 内部：`internal/technical/Sanqing_Baxian_OpenRouter_Model_Assignment.md`
|