refactor(project): 重构项目文档并优化代码结构
- 移除旧的文档结构和内容，清理 root 目录下的 markdown 文件 - 删除 GitHub Pages 部署配置和相关文件 - 移除 .env.example 文件，使用 Doppler 进行环境变量管理 - 更新 README.md，增加对 OpenBB 数据的支持 - 重构 streamlit_app.py，移除 Swarm 模式相关代码 - 更新 Doppler 配置管理模块，增加对 .env 文件的支持 - 删除 Memory Bank 实验和测试脚本 - 清理内部文档和开发计划
This commit is contained in:
ben
163
docs/guides/CLAUDE.md
Normal file
163
docs/guides/CLAUDE.md
Normal file
@@ -0,0 +1,163 @@
|
||||
---
|
||||
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`
|
||||
Reference in New Issue
Block a user