# Discord Bot MVP 项目需求文档

## 项目概述

### 核心目标
构建一个基于AI的终端控制系统，核心功能是/terminal命令，能够智能管理Docker服务器。多AI验证系统作为开发工具，用于开发和完善/terminal系统。

### 技术栈
- **不做Python版本要求**: 使用系统现有Python版本
- **部署**: Docker容器化
- **平台**: Discord
- **数据库**: SQLite (discord_bot.db)
- **通信**: 与多个项目进行通信，现阶段只与FinancialReport项目通信
- **外部数据访问**: 只读其他项目的数据库文件
- **运行模式**: 7x24小时持续运行

## 系统架构

### 核心组件
1. **3个AI Bot**: 独立的AI对话机器人
2. **tu Bot**: 中央控制的slash command机器人
3. **热更新系统**: 监听命令列表变化
4. **外部服务**: Finance Report Docker容器

### 文件结构
```
~/docker/
├── token.txt               # 全局token文件（只读访问）
├── discord_bot/
│   ├── ai_bots/
│   │   ├── ai_bot_1/
│   │   ├── ai_bot_2/
│   │   ├── ai_bot_3/
│   │   └── bot_template/
│   ├── slash_commands/
│   │   ├── terminal/
│   │   ├── terminal_fin/
│   │   ├── fin/
│   │   ├── db_operations/
│   │   └── help/
│   ├── tu_bot/
│   ├── databases/
│   │   └── discord_bot.db  # 主数据库（包含toy_balance、portfolio等表）
│   ├── backups/
│   └── SlashCommandList.txt
├── FinancialReport/
│   └── [FR项目文件]
├── docker-compose.yml
└── shared_volumes/
```

## 核心功能

### 1. 多AI验证机制

#### 3轮讨论流程
1. **第1轮**: 用户提问 → 同时发送给所有AI → 各AI回答并@其他AI
2. **第2轮**: 各AI接收其他AI的@，回应并继续@其他AI  
3. **第3轮**: 讨论结束，通过权限控制防止继续

#### 权限控制机制
- **触发条件**: 每个AI bot被其他AI @3次后自动锁定
- **锁定状态**: 不接受任何消息和@
- **解锁机制**: 只有tu bot发送空@才能解锁
- **安全性**: 防止AI无限循环对话

#### AI Bot配置
- 独立的Python文件和配置文件
- 共用模板生成，独立文件夹管理
- 字数限制等个性化配置
- 容器化部署，相互隔离

### 2. Slash Command 系统

#### tu Bot (中央控制器)
- **热更新**: 监听 `SlashCommandList.txt` 文件变化
- **文件监控**: 文件修改时立即更新命令列表
- **权限管理**: 控制AI bot的锁定/解锁状态

#### /help 命令
- 根据 `SlashCommandList.txt` 自动生成使用说明
- 类似 `--help` 格式的输出
- 实时反映当前可用命令

### 3. Terminal 系列命令

#### /terminal
- **AI引擎**: 使用预装的Claude Code CLI (集成方式待研究)
- **运行模式**: 默认plan mode
- **消息返回**: 按句返回Claude Code CLI的输出
- **工作空间**: `~/docker/*` (排除 `~/docker/gitea/*`)
- **术语系统**: `term_dic.db` 存储自定义术语和命令
- **优先级**: term_dic.db定义 > AI默认知识
- **对话管理**: 1小时内加载上文，超时开启新对话
- **记忆管理**: 重要性权重压缩策略，实时控制token消耗
  - 永久保留: 成功的Docker操作、重要配置变更
  - 压缩保留: 调试过程→结论、错误信息→解决方案
  - 立即清理: 详细的命令输出、重复的尝试过程
- **安全限制**: 
  - **禁用命令**: 不能使用 `rm -rf` (必须指定详细路径)
  - **权限控制**: /terminal AI无sudo权限
  - **工作范围**: 严格限制在~/docker/* (除gitea)
  - **保护机制**: 拒绝删除不必要文件，需要明确路径
- **开发权限**: MVP开发阶段AI可获得sudo权限 (仅限开发)

#### /terminal_fin_backtest
- **功能**: AI辅助金融策略开发
- **记忆管理**: `memory.md` 文件记录对话历史
- **智能压缩**: 重要性权重策略，控制token消耗
  - 永久保留: 成功策略、核心逻辑、重要学习记录
  - 压缩保留: 调试过程→结论、中间代码→最终版本
  - 定期清理: 纯调试过程、失败尝试细节
- **代码管理**: Python策略生成、回测、解释
- **数据源**: 缓存的日线级别金融数据

### 4. Finance 系列命令

#### /fin_portfolio  
- **功能**: 纯Python脚本，无AI参与
- **数据源**: Yahoo Finance API
- **数据库**: `portfolio`表（在discord_bot.db中）
- **计算**: 实时价格×持仓 = 当日盈亏
- **特殊处理**: 跳过 `toy_balance` 字段（无法从Yahoo获取）
- **输出**: 各账户当日盈亏 + 总盈亏

#### /fin_report
- **数据源**: FinancialReport项目的FinancialDataBaseProcessed.db (只读)
- **功能**: 传递最新的FinancialReport.pdf文件给用户
- **ALP交易确认**: 显示pending_alp_transactions表格供用户确认
- **确认界面**: 
  - 列表显示所有pending的ALP交易 (每日不超过20笔)
  - 用户可勾选"不是toy_fund"的交易
  - 默认全部不勾选（即默认都是toy_fund）
  - 用户点击确定后提交确认结果
  - 显示确认后的不可修改表格
- **数据记录**: 详细记录每笔确认的交易信息到toy_balance表
- **错误处理**: 用户点错无法撤销，需手动修改数据库
- **时序**: 显示的数据比实际晚一天（FR项目处理延迟）
- **容错设计**: /fin_report功能失效不影响其他功能

### 5. Database 系列命令

#### db_系列命令
- **独立命令集**: 每个都是独立的slash command
  - `/db_append`: 向数据库表追加数据
  - `/db_delete`: 删除数据库记录
  - `/db_query`: 查询数据库
  - `/db_add`: 添加新的数据记录
  - `/db_update`: 更新现有记录
- **功能**: 直接操作所有.db文件
- **目标**: 任何discord_bot目录下的.db文件
- **安全性**: 操作权限控制和备份机制
- **操作日志**: 所有数据库操作都记录在审计日志中

## 数据管理

### 数据库文件
- **discord_bot.db**: Discord Bot主数据库
  - `toy_balance`表: 详细的ALP交易确认记录
    ```
    CREATE TABLE toy_balance (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        transaction_id TEXT UNIQUE,
        date DATE,
        amount REAL,
        merchant TEXT,
        description TEXT,
        is_toy_fund BOOLEAN,      -- true=Ginbo, false=Family
        confirmed_by TEXT,        -- Discord用户ID
        confirmed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );
    ```
  - `portfolio`表: 投资组合数据 
  - 其他Bot相关数据表
- **term_dic.db**: 术语字典，存储自定义术语和命令
- **外部数据库访问**: 只读FinancialReport/data/processed/FinancialDataBaseProcessed.db

### SQLite跨容器访问
- **访问模式**: 使用`?mode=ro`参数确保只读
- **重试机制**: 数据库锁时自动重试，最多3次
- **超时设置**: 单次访问超时2秒
- **错误处理**: 访问失败时的降级策略

### 记忆文件
- **memory.md**: terminal_fin_backtest的对话记录
- **对话记录**: terminal系列的历史记录

### 备份策略
- **频率**: 每日自动备份
- **保留策略**: 3份日备份 + 3份周备份 + 3份月备份
- **实现**: Debian crontab任务
- **覆盖范围**: 所有.db文件和重要配置文件
- **Gitea集成**: 使用token.txt中的Gitea token自动备份到版本控制

## Docker配置

### 容器挂载
```
volumes:
  # 访问FinancialReport的数据库（只读）
  - ../FinancialReport/data/processed:/external/financial_report:ro
  # 访问全局token文件（只读）
  - ../token.txt:/app/token.txt:ro
  # 数据持久化
  - ./databases:/app/databases
  - ./backups:/app/backups
```

### 环境变量
- DB_PATH: 数据库文件路径
- FR_DB_PATH: FinancialReport数据库路径（只读）
- TOKEN_PATH: token文件路径
- DISCORD_PREFIX: Bot命令前缀

## 鲁棒性设计

### 错误处理
- **API失败**: 超时重试、降级处理
- **数据库异常**: 连接池、事务回滚、只读访问保护
- **AI服务中断**: 优雅降级、状态恢复
- **文件系统**: 权限检查、磁盘空间监控

### 安全机制
- **工作空间隔离**: /terminal AI限制在~/docker/*目录 (除gitea)
- **命令限制**: 禁用危险命令 (如不带详细路径的rm -rf)
- **权限分离**: 
  - MVP开发AI: sudo权限 (仅限开发阶段)
  - /terminal AI: 无sudo权限 (生产环境)
- **数据验证**: 输入验证、路径检查
- **审计日志**: 关键操作记录

### 监控和恢复
- **健康检查**: 定期检查各组件状态
- **自动重启**: 异常时自动恢复
- **数据一致性**: 数据完整性检查
- **回滚机制**: Gitea版本控制 + 数据库备份

### 性能优化
- **连接池**: 数据库连接管理
- **缓存策略**: 频繁查询数据缓存
- **异步处理**: 非阻塞操作
- **资源限制**: 内存和CPU使用限制

## 部署要求

### 系统环境
- **操作系统**: Debian
- **容器**: Docker + Docker Compose (位于 `~/docker/docker-compose.yml`)
- **版本控制**: Gitea (不受AI控制)
- **文件访问**: Docker共享卷挂载跨容器文件访问
- **访问控制**: 单一时间点只有一个Docker容器访问数据库文件 (访问时间<2s)

### 依赖服务
- **Discord API**: Bot权限和Token存储在 `~/docker/token.txt` 文件 (只读)
- **Claude Code CLI**: 预装的Claude Code CLI用于/terminal命令 (集成方式待研究)
- **外部项目数据库**: 通过Docker共享卷挂载，只读访问权限
- **配置文件**: 所有敏感信息从 `~/docker/token.txt` 读取，禁止硬编码

### 配置管理
- **环境变量**: 敏感信息通过环境变量管理
- **配置文件**: JSON格式，支持热更新
- **秘钥管理**: 统一的token文件，AI可访问

## 开发优先级

### MVP版本 (Phase 1): /terminal系统核心实现
1. **文件夹结构创建**: 按照架构图创建所有目录和空文件
2. **基础架构搭建**: Docker配置、基础Python框架
3. **多AI验证系统**: 用于开发/terminal的AI开发工具
   - 3个AI bot + tu bot基础框架
   - 3轮讨论机制（开发时使用）
4. **/terminal命令完整实现**: 
   - AI控制Docker服务器（核心功能）
   - term_dic.db术语系统
   - 对话记录和1小时窗口机制
   - **记忆管理系统**: 重要性权重压缩策略
   - **上下文压缩**: 防止token消耗过快
   - **对话状态管理**: 加载上文、新对话判断
5. **项目间通信**: 与FinancialReport项目的数据交换机制

### Phase 2: AI验证机制
1. 3个AI bot模板和部署
2. 3轮讨论流程实现
3. AI间@和权限控制机制
4. 多AI验证测试

### Phase 3: 扩展功能
1. finance系列命令
2. database操作命令
3. 热更新系统完善

### Phase 4: 完善和优化
1. 高级记忆管理优化
2. 监控和日志系统
3. 备份和恢复机制

## 成功标准

### 功能完整性
- [ ] 3轮AI讨论机制正常工作
- [ ] 权限控制有效防止无限循环
- [ ] 所有slash command功能实现
- [ ] 数据库操作安全可靠
- [ ] 与FinancialReport项目通信正常

### 可靠性指标
- [ ] 99%以上的命令执行成功率
- [ ] 系统异常后30秒内自动恢复
- [ ] 数据备份100%成功率
- [ ] 零数据丢失事故
- [ ] /fin_report失效时其他功能正常运行

### 安全性要求
- [ ] AI无法执行危险系统操作
- [ ] 数据库访问权限正确控制
- [ ] 敏感信息加密存储
- [ ] 审计日志完整记录
- [ ] 跨容器访问只读保护有效

### 性能指标
- [ ] 命令响应时间 < 3秒
- [ ] 数据库查询时间 < 500ms
- [ ] 内存使用 < 1GB
- [ ] CPU使用率 < 50%
- [ ] 并发处理能力 > 10个命令/秒 