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
2025-08-18 16:56:04 +00:00
parent c4e8cfefc7
commit 51576ebb6f
87 changed files with 13056 additions and 1959 deletions

View File

@@ -0,0 +1,19 @@
# 八仙辩论次序指南 (Baxian Debate Order Guide)
## 核心原则
辩论次序基于“对立统一”的哲学思想,将八仙分为四组,每组代表一对核心矛盾。此规则为项目级最终版本,作为后续所有相关实现的基准。
## 分组
1. **乾坤 / 男女:** 吕洞宾 (乾/男) vs 何仙姑 (坤/女)
* **逻辑:** 阳与阴,男与女的基本对立。
2. **老少:** 张果老 vs 韩湘子
* **逻辑:** 年长与年少,经验与活力的对立。
3. **贫富:** 汉钟离 vs 蓝采和
* **逻辑:** 富贵与贫穷,物质与精神的对立。汉钟离出身将门,而蓝采和的形象通常是贫穷的歌者。
4. **贵贱:** 曹国舅 vs 铁拐李
* **逻辑:** 皇亲国戚与街头乞丐,社会地位的极端对立。

View File

@@ -0,0 +1,87 @@
# 八仙记忆银行文档 (Cloudflare AutoRAG)
每个八仙智能体都有一个专属的记忆空间用于存储其在不同辩论主题下的记忆。这些记忆通过Cloudflare Vectorize进行向量索引并利用Workers AI进行语义检索。
## 记忆类型
1. **对话记忆 (conversation)**: 智能体在特定辩论中的发言和互动记录。
2. **偏好记忆 (preference)**: 智能体的投资偏好、分析方法和决策倾向。
3. **知识记忆 (knowledge)**: 智能体掌握的金融知识、市场信息和分析模型。
4. **策略记忆 (strategy)**: 智能体在辩论中使用的论证策略和战术。
## 八仙记忆空间列表
- **铁拐李 (tieguaili)**
- 标识符: `cf_memory_tieguaili`
- 特点: 擅长技术分析和风险控制
- **汉钟离 (hanzhongli)**
- 标识符: `cf_memory_hanzhongli`
- 特点: 注重基本面分析和长期价值
- **张果老 (zhangguolao)**
- 标识符: `cf_memory_zhangguolao`
- 特点: 擅长宏观趋势分析和周期判断
- **蓝采和 (lancaihe)**
- 标识符: `cf_memory_lancaihe`
- 特点: 关注市场情绪和资金流向
- **何仙姑 (hexiangu)**
- 标识符: `cf_memory_hexiangu`
- 特点: 精于财务数据分析和估值模型
- **吕洞宾 (lvdongbin)**
- 标识符: `cf_memory_lvdongbin`
- 特点: 善于多维度综合分析和创新策略
- **韩湘子 (hanxiangzi)**
- 标识符: `cf_memory_hanxiangzi`
- 特点: 擅长行业比较和相对价值分析
- **曹国舅 (caoguojiu)**
- 标识符: `cf_memory_caoguojiu`
- 特点: 注重合规性、社会责任和ESG因素
## 使用方法
```python
from src.jixia.memory.factory import get_memory_backend
# 获取记忆后端 (自动根据环境变量选择)
memory_bank = get_memory_backend(prefer="cloudflare")
# 为吕洞宾添加偏好记忆
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
# 搜索吕洞宾关于TSLA的记忆
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
# 获取上下文
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
## Cloudflare配置说明
要使用Cloudflare AutoRAG作为记忆后端需要配置以下环境变量
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare账户ID
- `CLOUDFLARE_API_TOKEN`: Cloudflare API令牌 (需要Vectorize和Workers AI权限)
- `JIXIA_MEMORY_BACKEND`: 设置为 `cloudflare`
系统默认使用以下配置:
- Vectorize索引: `autorag-shy-cherry-f1fb`
- 嵌入模型: `@cf/baai/bge-m3`
- AutoRAG域名: `autorag.seekkey.tech`
---
*此文档由系统自动生成和维护*

163
docs/guides/CLAUDE.md Normal file
View 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 TokenPro/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`

View File

@@ -3,6 +3,7 @@
欢迎访问项目文档。以下是常用入口:
- 快速上手与指南
- [Claude 集成与使用指南](guides/CLAUDE.md)
- [快速开始:负载均衡示例](guides/README_jixia_load_balancing.md)
- [Cloudflare AutoRAG 集成](guides/CLOUDFLARE_AUTORAG_INTEGRATION.md)
- [Google ADK 迁移指南](guides/GOOGLE_ADK_MIGRATION_GUIDE.md)

160
docs/memory_bank_design.md Normal file
View File

@@ -0,0 +1,160 @@
# Memory Bank 设计与实现文档
## 概述
Memory Bank 是 稷下学宫AI辩论系统 的核心组件之一旨在为每个AI智能体八仙提供持久化的记忆能力。通过集成不同的后端实现如 Google Vertex AI Memory Bank 和 Cloudflare AutoRAG系统能够灵活地存储、检索和利用智能体在辩论过程中积累的知识和经验。
## 架构设计
### 核心抽象
系统通过 `MemoryBankProtocol` 定义了记忆银行的通用接口,确保了不同后端实现的可替换性。
```python
@runtime_checkable
class MemoryBankProtocol(Protocol):
async def create_memory_bank(self, agent_name: str, display_name: Optional[str] = None) -> str: ...
async def add_memory(
self,
agent_name: str,
content: str,
memory_type: str = "conversation",
debate_topic: str = "",
metadata: Optional[Dict[str, Any]] = None,
) -> str: ...
async def search_memories(
self,
agent_name: str,
query: str,
memory_type: Optional[str] = None,
limit: int = 10,
) -> List[Dict[str, Any]]: ...
async def get_agent_context(self, agent_name: str, debate_topic: str) -> str: ...
async def save_debate_session(
self,
debate_topic: str,
participants: List[str],
conversation_history: List[Dict[str, str]],
outcomes: Optional[Dict[str, Any]] = None,
) -> None: ...
```
### 工厂模式
通过 `get_memory_backend` 工厂函数,系统可以根据配置动态选择合适的记忆后端实现。
```python
def get_memory_backend(prefer: Optional[str] = None) -> MemoryBankProtocol:
# 根据环境变量 JIXIA_MEMORY_BACKEND 选择后端
# 支持 "vertex" 和 "cloudflare"
...
```
## 后端实现
### Vertex AI Memory Bank
基于 Google Vertex AI 的 Memory Bank 服务实现。
**特点**:
- 与 Google Cloud 生态系统深度集成
- 提供企业级的安全性和可靠性
- 支持复杂的元数据过滤和查询
**配置**:
- `GOOGLE_API_KEY`: Google API 密钥
- `GOOGLE_CLOUD_PROJECT_ID`: Google Cloud 项目ID
- `GOOGLE_CLOUD_LOCATION`: 部署区域 (默认 us-central1)
### Cloudflare AutoRAG
基于 Cloudflare Vectorize 和 Workers AI 实现的向量检索增强生成方案。
**特点**:
- 全球分布的边缘计算网络
- 成本效益高,适合中小型项目
- 易于部署和扩展
**配置**:
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare 账户ID
- `CLOUDFLARE_API_TOKEN`: 具有 Vectorize 和 Workers AI 权限的 API 令牌
## 使用指南
### 初始化记忆银行
```python
from src.jixia.memory.factory import get_memory_backend
# 根据环境变量自动选择后端
memory_bank = get_memory_backend()
# 或者显式指定后端
memory_bank = get_memory_backend(prefer="cloudflare")
```
### 为智能体创建记忆空间
```python
# 为吕洞宾创建记忆银行/空间
await memory_bank.create_memory_bank("lvdongbin")
```
### 添加记忆
```python
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
```
### 搜索记忆
```python
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
```
### 获取上下文
```python
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
## 最佳实践
1. **合理分类记忆类型**:
- `conversation`: 记录对话历史,用于上下文理解和连贯性。
- `preference`: 存储智能体的偏好和倾向,指导决策过程。
- `knowledge`: 积累专业知识和数据,提升分析深度。
- `strategy`: 总结辩论策略和战术,优化表现。
2. **定期维护记忆**:
- 实施记忆的定期清理和归档策略,避免信息过载。
- 通过 `save_debate_session` 方法系统性地保存重要辩论会话。
3. **优化搜索查询**:
- 使用具体、明确的查询词以提高搜索相关性。
- 结合 `memory_type` 过滤器缩小搜索范围。
4. **错误处理**:
- 在生产环境中,务必对所有异步操作进行适当的错误处理和重试机制。
## 未来扩展
1. **混合后端支持**: 允许同时使用多个后端,根据数据类型或访问模式进行路由。
2. **记忆压缩与摘要**: 自动对长篇记忆进行摘要,提高检索效率。
3. **情感分析**: 为记忆添加情感标签,丰富检索维度。
---
*此文档旨在为开发者提供 Memory Bank 模块的全面技术参考*

View File

@@ -0,0 +1,74 @@
# 八仙记忆银行文档 (Vertex AI)
每个八仙智能体都有一个专属的记忆银行,用于存储其在不同辩论主题下的记忆。这些记忆包括对话历史、个人偏好、知识库和策略洞察。
## 记忆类型
1. **对话记忆 (conversation)**: 智能体在特定辩论中的发言和互动记录。
2. **偏好记忆 (preference)**: 智能体的投资偏好、分析方法和决策倾向。
3. **知识记忆 (knowledge)**: 智能体掌握的金融知识、市场信息和分析模型。
4. **策略记忆 (strategy)**: 智能体在辩论中使用的论证策略和战术。
## 八仙记忆银行列表
- **铁拐李 (tieguaili)**
- ID: `memory_bank_tieguaili_{PROJECT_ID}`
- 特点: 擅长技术分析和风险控制
- **汉钟离 (hanzhongli)**
- ID: `memory_bank_hanzhongli_{PROJECT_ID}`
- 特点: 注重基本面分析和长期价值
- **张果老 (zhangguolao)**
- ID: `memory_bank_zhangguolao_{PROJECT_ID}`
- 特点: 擅长宏观趋势分析和周期判断
- **蓝采和 (lancaihe)**
- ID: `memory_bank_lancaihe_{PROJECT_ID}`
- 特点: 关注市场情绪和资金流向
- **何仙姑 (hexiangu)**
- ID: `memory_bank_hexiangu_{PROJECT_ID}`
- 特点: 精于财务数据分析和估值模型
- **吕洞宾 (lvdongbin)**
- ID: `memory_bank_lvdongbin_{PROJECT_ID}`
- 特点: 善于多维度综合分析和创新策略
- **韩湘子 (hanxiangzi)**
- ID: `memory_bank_hanxiangzi_{PROJECT_ID}`
- 特点: 擅长行业比较和相对价值分析
- **曹国舅 (caoguojiu)**
- ID: `memory_bank_caoguojiu_{PROJECT_ID}`
- 特点: 注重合规性、社会责任和ESG因素
## 使用方法
```python
from src.jixia.memory.factory import get_memory_backend
# 获取记忆后端 (自动根据环境变量选择)
memory_bank = get_memory_backend()
# 为吕洞宾添加偏好记忆
await memory_bank.add_memory(
agent_name="lvdongbin",
content="倾向于使用DCF模型评估科技股的内在价值",
memory_type="preference",
debate_topic="TSLA投资分析"
)
# 搜索吕洞宾关于TSLA的记忆
memories = await memory_bank.search_memories(
agent_name="lvdongbin",
query="TSLA",
memory_type="preference"
)
# 获取上下文
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```
---
*此文档由系统自动生成和维护*