bigwo/PROJECT_STRUCTURE.md

# 大沃项目 — 目录结构

> 项目包含 4 个独立模块 + 若干根目录资源文件

```
bigwo/
│
├── 📄 根目录资源文件
│   ├── agents_prompts.txt          # Agent 提示词汇总（15 个角色）
│   ├── 大沃.doc                     # 原始 Word 文档
│   ├── 大沃_clean.txt               # 清洗后的纯文本
│   └── 大沃_content.txt             # 提取的完整内容
│
│
├── 📦 ai-knowledge-splitter/        # 模块一：AI 知识库文档智能分块工具
│   │                                 # Python CLI，DeepSeek API 语义分块
│   │
│   ├── main.py                      # CLI 入口（单文件/批量模式）
│   ├── splitter.py                  # 主协调器（解析→分块→输出流程）
│   ├── chunker.py                   # AI 分块器（预切分 + API 语义分块）
│   ├── api_client.py                # DeepSeek API 客户端（含重试）
│   ├── prompts.py                   # 分块提示词（文档/表格/问答/图片 4 种策略）
│   ├── writer.py                    # 输出写入器（Markdown / JSON）
│   ├── models.py                    # 数据结构（Chunk / ProcessResult）
│   ├── exceptions.py                # 自定义异常
│   ├── batch.py                     # 批量处理（递归扫描 + 容错 + 汇总）
│   ├── categorizer.py               # 分类合并器（按业务标签归类）
│   ├── batch_convert.py             # 批量 doc/docx → Markdown 转换脚本
│   ├── ai_restructure.py            # AI 整理已有 MD 文件（格式优化）
│   ├── doc_extractor.py             # .doc 二进制格式文本提取器（olefile）
│   ├── requirements.txt             # Python 依赖
│   ├── .env                         # 环境变量（DEEPSEEK_API_KEY）
│   │
│   ├── parsers/                     # 文件解析器（策略模式）
│   │   ├── base.py                  #   BaseParser 抽象基类 + ParserRegistry
│   │   ├── pdf_parser.py            #   PDF（PyMuPDF）
│   │   ├── doc_parser.py            #   Word .docx（python-docx）
│   │   ├── legacy_doc_parser.py     #   Word .doc（Word 97-2003）
│   │   ├── xlsx_parser.py           #   Excel .xlsx（openpyxl）
│   │   ├── xls_parser.py            #   Excel .xls（xlrd）
│   │   ├── csv_parser.py            #   CSV
│   │   ├── html_parser.py           #   HTML（BeautifulSoup）
│   │   ├── text_parser.py           #   TXT / Markdown
│   │   └── image_parser.py          #   图片（base64 → Vision API）
│   │
│   ├── tests/                       # 单元测试（pytest）
│   │   ├── test_main.py
│   │   ├── test_splitter.py
│   │   ├── test_chunker.py
│   │   ├── test_api_client.py
│   │   ├── test_prompts.py
│   │   ├── test_writer.py
│   │   ├── test_models.py
│   │   ├── test_exceptions.py
│   │   ├── test_parsers_base.py
│   │   ├── test_pdf_parser.py
│   │   ├── test_doc_parser.py
│   │   ├── test_xlsx_parser.py
│   │   ├── test_xls_parser.py
│   │   ├── test_csv_parser.py
│   │   ├── test_html_parser.py
│   │   ├── test_text_parser.py
│   │   └── test_image_parser.py
│   │
│   ├── test_results/                # 测试输出样本
│   │
│   └── 2026火山知识库用/             # 知识库源文档（待处理）
│       └── 2026火山知识库用/
│           ├── *.doc / *.docx / *.md   # 各类源文档
│           ├── 整理后/                  # AI 整理后的 MD 文件
│           └── 标注的图片知识库/         # 产品图片
│
│
├── 📦 coze_config/                  # 模块二：Coze Bot 配置与 Agent 提示词
│   │                                 # 15 个专业角色 Agent 的提示词定义
│   │
│   ├── README.md                    # 模块说明
│   ├── Coze平台操作指南.md           # Coze 平台操作指南
│   ├── coze_bot_config.json         # Bot 完整配置（JSON）
│   ├── orchestrator_prompt.md       # 编排器（主控 Agent）提示词
│   │
│   └── agents/                      # 15 个子 Agent 提示词
│       ├── 01_事业招商_zhaoshang.md
│       ├── 02_产品宣传_xuanchuan.md
│       ├── 03_趋势前瞻_qianzhan.md
│       ├── 04_产品互动_hudong.md
│       ├── 05_自我介绍_ziwojieshao.md
│       ├── 06_活动促销_cuxiao.md
│       ├── 07_产品文化_wenhua.md
│       ├── 08_生活感悟_ganwu.md
│       ├── 09_公司介绍_gongsijieshao.md
│       ├── 10_营养科普_kepu.md
│       ├── 11_问候_wenhou.md
│       ├── 12_误区厘清_wuquliqing.md
│       ├── 13_工作复盘_fupan.md
│       ├── 14_事业顾问_guwen.md
│       └── 15_客户成交_chengjiao.md
│
│
├── 📦 coze_api/                     # 模块三：Coze API 客户端
│   │                                 # Python，Coze v3 Chat API 调用封装
│   │
│   ├── README.md
│   ├── coze_client.py               # Coze API 客户端（创建对话/轮询/获取回复）
│   ├── test_coze_api.py             # 测试脚本
│   ├── requirements.txt             # Python 依赖
│   ├── .env                         # 环境变量（COZE_API_TOKEN / BOT_ID）
│   └── .env.example                 # 环境变量模板
│
│
└── 📦 test2/                        # 模块四：混合编排语音通话 + 文字对话系统
    │                                 # 全栈 Web App，火山 S2S + Coze Bot
    │
    ├── E2E_HYBRID_MODE_PLAN.md      # 混合编排方案详细设计文档
    ├── E2E_VOICE_MODULE.md          # 端到端语音模块技术方案
    ├── KNOWLEDGE_BASE_GUIDE.md      # 知识库配置与使用指南
    │
    ├── client/                      # 前端（React + Vite + TailwindCSS）
    │   ├── package.json
    │   ├── vite.config.js           #   Vite 配置（含 /api 代理到 :3001）
    │   ├── index.html
    │   └── src/
    │       ├── main.jsx             #   入口
    │       ├── index.css            #   全局样式
    │       ├── App.jsx              #   主组件（语音/文字模式切换）
    │       ├── components/
    │       │   ├── VoicePanel.jsx   #     语音通话面板
    │       │   ├── ChatPanel.jsx    #     文字对话面板
    │       │   ├── SubtitleDisplay.jsx  # 字幕展示
    │       │   └── SettingsPanel.jsx    # 设置面板
    │       ├── hooks/
    │       │   └── useVoiceChat.js  #     语音通话 Hook
    │       └── services/
    │           ├── rtcService.js    #     WebRTC 连接管理
    │           ├── voiceApi.js      #     语音 API 调用
    │           └── chatApi.js       #     文字对话 API 调用
    │
    └── server/                      # 后端（Express.js）
        ├── package.json
        ├── app.js                   #   Express 入口（端口 3001）
        ├── .env                     #   环境变量（火山/Coze 凭证）
        ├── .env.example             #   环境变量模板
        ├── config/
        │   ├── voiceChatConfig.js   #     StartVoiceChat 配置构建器
        │   └── tools.js             #     5 个工具定义（天气/订单/知识库/时间/计算）
        ├── routes/
        │   ├── voice.js             #     语音通话路由（start/stop/subtitle/tool-callback）
        │   └── chat.js              #     文字对话路由（start/send/send-stream）
        └── services/
            ├── volcengine.js        #     火山引擎 OpenAPI（V4 签名 + RTC Token）
            ├── arkChatService.js    #     方舟 LLM 服务（流式/工具调用循环）
            ├── cozeChatService.js   #     Coze Bot 对话服务（流式/非流式）
            └── toolExecutor.js      #     工具执行器（知识库三级 fallback）
```

## 模块关系

```
┌─────────────────────────┐
│  ai-knowledge-splitter  │  文档 → 分块 → 上传知识库
└───────────┬─────────────┘
            │ 产出知识库数据
            ▼
┌─────────────────────────┐     ┌──────────────┐
│       coze_config        │────►│   coze_api    │
│  Bot 配置 / Agent 提示词  │     │  API 客户端   │
└───────────┬─────────────┘     └──────┬───────┘
            │ 配置 Coze Bot              │ 调用 Coze API
            ▼                           ▼
┌─────────────────────────────────────────────────┐
│                    test2                          │
│  语音通话（火山 S2S）+ 文字对话（Coze Bot）          │
│  最终用户交互入口                                   │
└─────────────────────────────────────────────────┘
```