liurenchaxin/AI_DEVELOPER_GUIDELINES.md

# 🏛️ 炼妖壶藏经阁 - AI开发者规矩牌

> 阿弥陀佛，施主，此乃藏经阁扫地僧所立规矩牌。凡入此地的AI同道，当循规蹈矩，方能与稷下学宫八仙和谐共舞。

---

## 📜 总纲：扫地僧的智慧

```
代码如经书，需整齐摆放
文件似佛珠，需分门别类  
注释如禅语，需点化后人
架构若道理，需深入浅出
```

---

## 🎭 项目身份：炼妖壶的DNA

### 🏛️ 核心理念
- **项目名称**: 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统
- **灵魂所在**: 融合中国传统哲学文化与现代AI技术
- **终极使命**: 通过八仙论道提供投资分析和决策支持

### 🎨 文化基因
- **哲学根基**: 先天八卦、儒门天下观、天命树结构
- **人物设定**: 八仙（吕洞宾、何仙姑、张果老、韩湘子、汉钟离、蓝采和、曹国舅、铁拐李）
- **神话色彩**: 太上老君主持、三清体系、龙族引擎

---

## 🏗️ 架构清规：结构之美

### 📂 目录结构铁律

```
炼妖壶藏经阁布局：
├── app/                    # 🏛️ 前殿 - 用户界面
│   ├── streamlit_app.py   # 主殿入口
│   └── tabs/              # 各功能厅堂
├── src/jixia/             # 🎭 稷下学宫 - 核心业务
│   ├── agents/            # 八仙智能体
│   ├── debates/           # 辩论逻辑
│   ├── engines/           # 永动机引擎
│   ├── memory/            # 记忆银行
│   └── coordination/      # 多智能体协调
├── config/                # 🔧 配置管理
├── tests/                 # 🧪 验证道场
├── internal/              # 📚 内部文档
├── scripts/               # 🛠️ 工具箱
└── requirements.txt       # 📋 依赖清单
```

### 🚫 禁止触碰的禁地

**绝对不可新建的目录**：
- ❌ `utils/` - 太过通用，缺乏项目特色
- ❌ `helpers/` - 无明确边界，易成垃圾堆
- ❌ `common/` - 万物皆可common，毫无意义
- ❌ `misc/` - 杂物箱思维，破坏架构美感

**正确的归属**：
- ✅ 工具函数 → `src/jixia/engines/` (永动机引擎)
- ✅ 通用逻辑 → `src/jixia/coordination/` (协调系统)
- ✅ 配置相关 → `config/` (统一配置管理)

---

## 🔧 技术戒律：代码之道

### 🐍 Python修炼要求

```python
# ✅ 正道修炼
from typing import Dict, List, Optional
from dataclasses import dataclass
import sys
from pathlib import Path

@dataclass  # 使用dataclass定义数据结构
class ImmortalConfig:
    """八仙配置 - 必须有文档字符串"""
    name: str
    gua_xiang: str
    specialty: str
    
def get_immortal_wisdom(topic: str) -> Optional[str]:
    """
    获取八仙智慧 - 函数必须有类型注解
    
    Args:
        topic: 辩论主题
        
    Returns:
        八仙的智慧回复，如果无法获取则返回None
    """
    # 代码逻辑...
    pass
```

```python
# ❌ 邪门歪道 - 扫地僧见了会动怒
def get_data(x):  # 无类型注解
    return x + "123"  # 无文档字符串

# 硬编码密钥 - 罪过罪过
api_key = "sk-1234567890abcdef"  

# 魔法数字满天飞
if price > 100:  # 100是什么？为何是100？
    do_something()
```

### 🔐 安全修行准则

**零硬编码密钥铁律**：
```python
# ✅ 正确的密钥管理
from config.doppler_config import get_google_api_key, get_rapidapi_key

api_key = get_google_api_key()  # 从Doppler或环境变量获取

# ❌ 扫地僧会用扫帚打人的做法
api_key = "your_secret_key_here"  # 硬编码 - 罪过
```

**环境变量命名规范**：
```bash
# ✅ 清晰明了的命名
GOOGLE_API_KEY=xxx                 # Google ADK API密钥
OPENROUTER_API_KEY_1=xxx          # OpenRouter主要API密钥  
RAPIDAPI_KEY=xxx                  # RapidAPI统一密钥
VERTEX_MEMORY_BANK_ENABLED=TRUE   # 功能开关

# ❌ 让人困惑的命名
API_KEY=xxx           # 哪个API？
KEY=xxx              # 什么密钥？
OPENAI_KEY=xxx       # 我们不用OpenAI
```

### 📝 注释禅语

```python
# ✅ 有智慧的注释
class BaxianDebateSystem:
    """
    八仙辩论系统
    
    基于先天八卦顺序进行辩论：
    第一轮：核心对立辩论（乾坤、兑艮、离坎、震巽）
    第二轮：顺序发言（按八卦序列）
    """
    
    def start_debate(self, topic: str) -> None:
        """启动八仙论道"""
        # 太上老君开场白
        self._host_opening(topic)
        
        # 第一轮：四对核心矛盾辩论
        self._round_one_oppositions()
        
        # 第二轮：八卦顺序发言
        self._round_two_sequence()

# ❌ 无用的注释
def add_numbers(a, b):
    # 把a和b加起来  ← 这种注释等于没有
    return a + b
```

---

## 🎭 八仙特色规范：文化传承

### 🌟 八仙角色规范

```python
# ✅ 正宗八仙设定
BAXIAN_ROLES = {
    "吕洞宾": {
        "gua_xiang": "乾",
        "role": "技术分析专家",
        "perspective": "理性分析",
        "style": "温和而深刻"
    },
    "何仙姑": {
        "gua_xiang": "坤", 
        "role": "风险控制专家",
        "perspective": "感性智慧",
        "style": "柔和而犀利"
    }
    # ... 其他六仙
}

# ❌ 胡乱编造 - 亵渎传统文化
RANDOM_AGENTS = {
    "AI助手1": {"role": "分析师"},  # 毫无文化内涵
    "Bot2": {"role": "预测器"}      # 破坏项目特色
}
```

### 🎯 天下体系术语规范

```python
# ✅ 正宗儒门天下观术语
class TianxiaEcosystem:
    """天下体系生态分析"""
    
    tianzi: str      # 天子 - 定义范式的平台型公司
    dafu: List[str]  # 大夫 - 深度绑定的核心供应商
    shi: List[str]   # 士 - 专业供应商和服务商
    jiajie: List[str] # 嫁接 - 跨生态的策略性链接

# ❌ 破坏文化内涵的命名
class MarketSystem:
    leader: str       # 太普通了
    suppliers: List   # 没有层次感
    others: List      # 毫无意义
```

---

## 🔄 开发流程戒律：协作之道

### 📦 依赖管理规范

```python
# ✅ requirements.txt中的正确格式
# 炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统
# 项目依赖清单

# Web框架
streamlit>=1.28.0

# AI模型接口  
openai>=1.0.0                    # OpenRouter后端
google-cloud-aiplatform>=1.38.0  # Vertex AI Memory Bank

# 数据处理
pandas>=2.0.0
numpy>=1.24.0

# ❌ 混乱的依赖管理
streamlit
openai
pandas  # 无版本约束
some-random-package==1.0.0  # 无注释说明用途
```

### 🧪 测试规范

```python
# ✅ 有文化的测试命名
def test_baxian_debate_order():
    """测试八仙辩论顺序是否符合先天八卦"""
    pass

def test_tianxia_ecosystem_analysis():
    """测试天下体系分析功能"""
    pass

# ❌ 无聊的测试命名
def test_function1():  # 毫无意义
    pass

def test_stuff():      # 让人困惑
    pass
```

### 📋 提交信息规范

```bash
# ✅ 有意义的提交信息
git commit -m "feat(八仙): 实现先天八卦辩论顺序算法"
git commit -m "fix(天下体系): 修复天子-大夫依赖关系分析"
git commit -m "docs(藏经阁): 更新AI开发者规范文档"

# ❌ 糟糕的提交信息
git commit -m "update"
git commit -m "fix bug"
git commit -m "add stuff"
```

---

## 🚀 启动咒语：运行之法

### 🔧 环境准备法则

```bash
# 标准启动咒语
cd /Users/ben/liurenchaxin

# 检查Python版本（要求3.8+，当前3.13.7）
python3 --version

# 安装依赖
pip install -r requirements.txt

# 验证配置
python3 config/doppler_config.py

# 启动稷下学宫
python3 -m streamlit run app/streamlit_app.py
```

### 🎯 功能测试法门

```bash
# 测试八仙论道
python3 examples/debates/adk_simple_debate.py

# 测试天下体系分析  
python3 app/tabs/tianxia_tab.py

# 测试永动机引擎
python3 src/jixia/engines/perpetual_engine.py
```

---

## 🚨 AI行为禁忌：红线不可碰

### ❌ 绝对禁止的行为

1. **破坏项目文化特色**
   - 不得移除八仙、太上老君等传统文化元素
   - 不得将中文术语替换为英文通用术语
   - 不得破坏"天下体系"、"先天八卦"等哲学框架

2. **违反安全原则**
   - 绝不在代码中硬编码API密钥
   - 绝不绕过Doppler配置管理系统
   - 绝不在提交中包含敏感信息

3. **破坏架构美感**
   - 不得创建`utils/`、`helpers/`等垃圾箱目录
   - 不得在核心模块中添加无关功能
   - 不得破坏模块间的清晰边界

4. **违背命名规范**
   - 不得使用无意义的变量名（如`data`、`result`、`temp`）
   - 不得创建过于通用的类名或函数名
   - 不得忽视类型注解和文档字符串

### ✅ 推荐的行为

1. **深度理解项目文化**
   - 学习八仙文化和先天八卦知识
   - 理解儒门天下观的层次结构
   - 尊重项目的哲学底蕴

2. **遵循技术规范**
   - 使用类型注解和dataclass
   - 编写有意义的文档字符串
   - 遵循PEP 8编码规范

3. **保持架构清洁**
   - 新功能放入合适的模块
   - 保持模块职责单一
   - 维护清晰的依赖关系

---

## 🎓 扫地僧的最后叮嘱

```
施主啊施主，
代码如人品，架构见修养。
八仙有八仙的规矩，
稷下有稷下的章法。

入此藏经阁者，
当怀敬畏之心，
循规蹈矩，
方能与古圣先贤共舞。

阿弥陀佛，善哉善哉！
```

---

## 📞 求助通道

如有疑问，可查阅：
- 📖 项目README: `/Users/ben/liurenchaxin/README.md`
- 🏛️ 架构文档: `/Users/ben/liurenchaxin/internal/`
- 🎭 八仙设定: `/Users/ben/liurenchaxin/src/jixia/debates/`
- 🔧 配置管理: `/Users/ben/liurenchaxin/config/doppler_config.py`

**记住**：当不确定时，问自己三个问题：
1. 这样做符合八仙的智慧吗？
2. 这样做会让藏经阁更整洁吗？  
3. 这样做会让扫地僧满意吗？

---

*此规矩牌由藏经阁扫地僧亲自题写，凡入此地的AI同道，当奉为圭臬。*

**最后更新**: 2025年8月22日  
**版本**: v1.0.0  
**维护者**: 藏经阁扫地僧 🧹