liurenchaxin/modules/legacy-support/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修炼要求

# ✅ 正道修炼
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

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

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

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

🔐 安全修行准则

零硬编码密钥铁律：

# ✅ 正确的密钥管理
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"  # 硬编码 - 罪过

环境变量命名规范：

# ✅ 清晰明了的命名
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

📝 注释禅语

# ✅ 有智慧的注释
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

---

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

🌟 八仙角色规范

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

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

🎯 天下体系术语规范

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

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

---

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

📦 依赖管理规范

# ✅ 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  # 无注释说明用途

🧪 测试规范

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

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

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

def test_stuff():      # 让人困惑
    pass

📋 提交信息规范

# ✅ 有意义的提交信息
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"

---

🚀 启动咒语：运行之法

🔧 环境准备法则

# 标准启动咒语
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

🎯 功能测试法门

# 测试八仙论道
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
维护者: 藏经阁扫地僧 🧹