# AI智能瞭望与智能问数系统 ## 1. 项目概述 本项目是一个基于 B/S 架构的 Web 应用程序，采用 Tornado MVC 组织代码，目标是构建“AI智能瞭望与智能问数系统”。当前已具备较完整的后台管理能力（RBAC 权限、模型引擎、瞭望采集与数据仓库等），并提供若干独立业务页面用于采集与测试。 ## 2. 技术栈 - **后端语言**: Python 3.11 - **Web 框架**: Tornado 6.5.5 - **数据库**: SQLite3 - **前端技术**: HTML5 + CSS3 + JavaScript - **前端UI库与组件** (已本地化部署于 `app/static/dist/` 目录): - Layui 2.13.6 - Bootstrap 5.3.8 - FontAwesome 5.15.4 - ECharts（`app/static/dist/echarts/echarts.min.js`） ## 3. 架构设计 (MVC 架构) 本项目采用了经典的 MVC（Model-View-Controller）设计模式： - **Model (模型层)**: 负责数据访问与业务逻辑。使用 `sqlite3` 与数据库交互，通过实体类（如 `UserRepository`）封装数据操作。 - **View (视图层)**: 负责用户界面的呈现。使用 Tornado 原生的模板引擎，结合 HTML/CSS/JS 渲染页面（如 `base.html`, `login.html`, `index.html`）。 - **Controller (控制层)**: 负责接收 HTTP 请求、处理业务流程，并协调 Model 和 View。在 Tornado 中，以 `RequestHandler` 的形式存在（如 `LoginHandler`, `IndexHandler`）。 ## 4. 目录结构说明 ```text cnAgentOS/ ├── app.md # 原有目录结构说明文档 ├── app.py # 项目主入口，Tornado Web 容器及路由配置 ├── test.py # 单元测试与临时测试脚本，包含数据库初始化和用户测试 ├── app/ # 核心应用程序包 │ ├── __init__.py # 标识 app 为 Python 包 │ ├── controllers/ # 控制层 (Controller) │ │ ├── __init__.py # 标识 controllers 为 Python 包 │ │ ├── auth.py # 认证相关路由 (登录、退出) │ │ ├── base.py # 基础 RequestHandler，提供公共方法（如 get_current_user） │ │ ├── home.py # 后台首页/控制台（动态菜单渲染） │ │ ├── portal.py # 用户侧（登录/注册/问数/历史对话/流式对话） │ │ ├── user.py # 用户管理（CRUD/分页/角色绑定） │ │ ├── role.py # 角色管理（CRUD/超管保护） │ │ ├── menu.py # 功能菜单管理（树形CRUD） │ │ ├── model_engine.py # 模型引擎（CRUD/默认模型/Token统计/测试对话SSE） │ │ ├── api_manage.py # 接口管理（CRUD/分页/对内代理服务/QPS限制） │ │ ├── digital_employee.py # 数字员工（CRUD/分页/@别名解析/SSE对话/普通类接口调用/记忆管理/技能路由） │ │ ├── skill_manage.py # 技能管理（全局技能库 CRUD/zip 导入/与数字员工联动） │ │ ├── chat_admin.py # 会话/对话管理（后台查看/搜索/删除） │ │ ├── spy_source.py # 瞭望采集源管理（CRUD/启用列表） │ │ ├── spy.py # 瞭望采集（SSE日志+候选数据推送+手动入库） │ │ └── data_warehouse.py # 数据仓库（列表/删除/批删/AI深度采集/详情查看） │ ├── models/ # 模型层 (Model) │ │ ├── __init__.py # 标识 models 为 Python 包 │ │ ├── db.py # 数据库连接池与初始化建表脚本 │ │ ├── user.py # 用户与用户-角色映射 │ │ ├── role.py # 角色与角色-菜单映射 │ │ ├── menu.py # 菜单树构建与按角色过滤 │ │ ├── model_engine.py # 模型服务与Token统计 │ │ ├── api_manage.py # 接口管理数据访问（api_endpoints） │ │ ├── digital_employee.py # 数字员工数据访问（digital_employees + 全局 skills/links + 记忆管理） │ │ ├── skill_manage.py # 技能管理数据访问（全局技能库 + 导入解析） │ │ ├── chat.py # 会话/对话管理（CRUD/搜索/导出/后台管理） │ │ ├── spy_source.py # 采集源管理 │ │ └── data_warehouse.py # 数据仓库（含 upsert_batch / 深采详情查询 / 会话存储） │ ├── static/ # 静态资源 (View 辅助) │ │ ├── css/base.css # 基础样式表 │ │ └── js/base.js # 基础脚本 │ └── templates/ # 模板文件 (View) │ ├── base.html # 基础母版页面 │ ├── index.html # 后台首页模板 │ ├── login.html # 登录页面模板 │ ├── dashboard.html # 控制台（ECharts 报表 + 懒加载 + 历史回放） │ ├── user/list.html # 用户管理页 │ ├── role/list.html # 角色管理页 │ ├── menu/list.html # 功能菜单管理页 │ ├── model_engine/list.html # 模型引擎页 │ ├── api_manage/list.html # 接口管理页 │ ├── digital_employee/list.html # 数字员工管理页 │ ├── skill_manage/list.html # 技能管理页（全局技能库 + zip 导入） │ ├── chat_admin/sessions.html # 会话管理页（后台查看/搜索/删除） │ ├── chat_admin/messages.html # 对话管理页（消息查看/检索） │ ├── spy/source_list.html # 瞭望数据源管理页 │ ├── spy/spy.html # 瞭望采集页（独立搜索风格） │ ├── data_warehouse/list.html # 数据仓库列表页 │ └── portal/ # 用户侧页面 │ ├── login.html # 用户登录 │ ├── register.html # 用户注册 │ └── chat.html # 智能问数（历史会话 + 流式对话 + 模型切换 + @数字员工） ├── database/ # 数据库文件存放目录 │ └── app.db # SQLite 数据库文件 (由程序自动生成) └── venv/ # Python 虚拟环境目录 ``` ## 5. 已实现功能 当前系统已完成以下核心功能： 1. **服务启动与配置**: 通过 `app.py` 启动 Tornado 服务，配置模板/静态资源路径、安全 Cookie（`cookie_secret`）以及 CSRF 防护（`xsrf_cookies`）。 2. **数据库初始化与轻量迁移**: 启动时调用 `init_db()` 自动建表，并对历史库做兼容（例如为 `spy_data` 补列、建立唯一索引）。 3. **登录态与认证**: - 安全 Cookie 会话管理（`set_secure_cookie`）。 - `BaseHandler.get_current_user()` 提供统一登录态获取；`@tornado.web.authenticated` 保护页面与接口。 - 密码存储采用 PBKDF2-HMAC-SHA256 加盐哈希。 4. **RBAC 权限体系（管理侧）**: - 用户/角色/菜单功能管理（CRUD + 分页/树形）。 - 角色与菜单授权（二级联动映射）。 - 根据用户角色动态过滤并渲染后台左侧菜单树（超级管理员默认全量菜单）。 5. **模型引擎（管理侧）**: - 模型服务配置 CRUD（OpenAI 范式：`model_name/api_key/base_url`）。 - 设置默认模型、Token 统计展示。 - 测试对话支持 SSE 流式响应。 6. **智能瞭望与数据仓库（管理侧 + 独立采集页）**: - 瞭望数据源管理（动态配置 URL 模板与请求 headers，启用/停用）。 - 采集过程 SSE 日志输出；采集结果以橱窗列表展示（不自动入库）。 - 支持批量勾选后手动入库到数据仓库（upsert：存在则更新，不存在则新增）。 - 数据仓库列表分页、单删/批删。 - AI 深度采集：对数据仓库条目进行深度抓取与 AI 解析，入库到详情表并标注深采状态；支持单条/多条，SSE 日志与统计，支持详情查看。 7. **接口管理（管理侧）**: - 接口 URL 管理（新增/修改/删除/分页）。 - 对系统其他模块提供统一代理服务接口：`/api/interface_proxy?id=`。 - QPS 默认限制（可配置）：窗口期内超过上限返回 429；携带 Token 可绕过限制。 8. **数字员工（管理侧 + 对话接口）**: - 数字员工管理（新增/修改/删除/分页），支持 AI/普通 两类。 - AI 类：默认模型 + Prompt，通过 SSE 流式输出对话内容与 Token 统计。 - 普通类：绑定接口管理 API，支持将用户输入作为指定参数名透传到外部接口。 - 增强能力： - 记忆：按用户隔离（employee_id + user_id 唯一），后台支持查看/清空；支持 LLM 自动摘要/压缩。 - 技能：AI 员工可绑定多个全局技能（SKILL.md 规范），用户侧自动识别并渲染卡片（天气/音乐等）。 - 多模型：AI 员工支持绑定多个模型，按任务/模态/推理需求选择最优模型。 9. **技能管理（独立模块）**: - 全局技能库 CRUD（skill_key 唯一约束，支持绑定接口服务）。 - 支持导入 zip 技能包，自动扫描并识别 `SKILL.md`（YAML frontmatter）入库。 - 与数字员工技能联动（同一套 `skills` 表 + `digital_employee_skill_links` 绑定关系表）。 - 数字员工支持从技能库选择并绑定技能；解绑不删除全局技能。 10. **会话/对话管理（管理侧）**: - 会话管理：列表分页/按用户筛选/按标题搜索/删除会话。 - 对话管理：查看会话内所有消息/按角色筛选/关键词检索/删除单条消息。 11. **控制台（管理侧）**: - ECharts 本地化加载（`/static/dist/echarts/echarts.min.js`）。 - 系统运行状态、模块概览、数据概览与图形报表。 - 懒加载：图表进入可视区域后初始化（IntersectionObserver + fallback）。 - 历史回放：指标快照存储 + 时间点回放。 12. **用户侧卡片与对话增强**: - 天气卡片：横向布局（max-width 520px），动态呼吸特效图标，展示温度/天气/湿度/风力/AQI/气压/能见度，无预报数据时自动隐藏预报容器。 - 音乐卡片：后端自动跟踪音乐 URL 跳转获取真实 MP3 地址；新增 `/api/audio_proxy` 音频代理接口（Base64 编码 URL），解决跨域和 Referer 限制，点击播放按钮可正常播放。 - Markdown 表格渲染：增加表格检测与解析（识别 `| 列1 | 列2 |` 格式），生成 `//` 结构，样式支持圆角边框/表头高亮/行悬停/横向滚动。 - 意图识别优化：增强模板（详细表结构说明、分类规则、SQL 示例），上下文窗口从 12 条增加到 20 条，System Prompt 动态调整（根据意图类型调整语气），LRU 缓存（200 条，5 分钟过期）。 - 记忆压缩：使用 LLM 结构化摘要（用户偏好/重要事实/最近交互），按主题聚类保留关键信息。 ## 6. 主要路由 - 用户侧：`/`、`/login`、`/register`、`/chat`、`/logout` - 用户侧 API：`/api/models`、`/api/employees`、`/api/sessions`、`/api/messages`、`/api/chat/stream`、`/api/audio_proxy` - 管理侧：`/admin`（后台框架）、`/admin/login`、`/admin/logout`、`/admin/dashboard` - 管理侧控制台 API：`/api/dashboard`（current/history_list/history_get） - 管理侧兼容：`/auth/login`、`/auth/logout`、`/dashboard` - 用户/角色/菜单：`/user/list`、`/role/list`、`/menu/list`（对应 API：`/api/user`、`/api/role`、`/api/menu`） - 模型引擎：`/model_engine/list`（API：`/api/model_engine`、`/api/model_engine/test`） - 接口管理：`/api_manage/list`（API：`/api/api_manage`、`/api/interface_proxy`） - 数字员工：`/digital_employee/list`（API：`/api/digital_employee`、`/api/digital_employee/chat`） - 技能管理：`/skill_manage/list`（API：`/api/skill_manage`） - 会话管理：`/chat_admin/sessions`（API：`/api/chat_admin/sessions`） - 对话管理：`/chat_admin/messages`（API：`/api/chat_admin/messages`） - 瞭望管理：`/spy_source/list`（API：`/api/spy_source`）、`/spy`（API：`/api/spy/run`、`/api/spy/commit`） - 数据仓库：`/data_warehouse/list`（API：`/api/data_warehouse`） ## 7. 数据库设计（SQLite） 核心表（由 `app/models/db.py:init_db()` 创建/维护）： - `users`：用户基础信息 - `roles`：角色 - `menus`：菜单/功能 - `user_roles`：用户-角色映射 - `role_menus`：角色-菜单映射 - `ai_models`：模型服务配置（含 `is_default`、`total_tokens`） - `api_endpoints`：接口管理（URL/Method/限流参数/绕过 Token/示例请求等） - `digital_employees`：数字员工（alias 唯一；AI Prompt 或绑定 api_endpoint_id） - `digital_employee_memories`：数字员工记忆（employee_id + user_id 唯一，存储结构化摘要） - `skills`：全局技能库（skill_key 唯一；spec_markdown/YAML frontmatter；绑定接口服务） - `digital_employee_skill_links`：数字员工与技能的绑定关系（employee_id + skill_id 联合主键） - `spy_sources`：瞭望采集源 - `spy_data`：数据仓库（包含 `update_at`；并对 `(source_id,url)` 建立唯一索引用于去重与 upsert；包含深采状态字段） - `spy_data_details`：深采详情（与 `spy_data.id` 关联，保存正文/摘要/关键词/要点/统计等） - `chat_sessions`：用户侧历史会话 - `chat_messages`：用户侧历史消息（流式结果最终落库） - `dashboard_snapshots`：控制台指标快照（用于历史回放） ## 8. 后续开发指南 在后续开发“AI智能瞭望与智能问数系统”时，请遵循以下规范： 1. **新增业务路由**: - 在 `app/controllers/` 目录下创建新的 `.py` 文件，继承 `app.controllers.base.BaseHandler`。 - 如果接口需要登录权限，请在请求方法（如 `get`, `post`）上添加 `@tornado.web.authenticated` 装饰器。 - 编写完成后，务必在根目录的 `app.py` 中的 `make_app()` 路由列表里注册新路由。 2. **新增数据模型**: - 在 `app/models/` 目录下创建新的业务模型文件。 - 涉及建表操作的，请在 `app/models/db.py` 的 `init_db()` 方法中追加相应的 `CREATE TABLE IF NOT EXISTS` 语句。 - 尽量将数据库的 CRUD 操作封装在 `XxxRepository` 静态方法中。 3. **前端页面开发**: - HTML 文件放在 `app/templates/` 下，建议继承 `base.html` 保持页面结构统一。 - 表单提交时，务必在 `` 标签内包含 `{% module xsrf_form_html() %}` 以通过 CSRF 校验。 - 静态资源（CSS, JS, 图片等）存放在 `app/static/` 目录下，在模板中通过 `{{ static_url('...') }}` 引用。 - 页面自定义样式请放在 `{% block style %}` 中（由 `base.html` 在 head 内输出），避免样式丢失。 4. **测试规范**: - 可以继续在 `test.py` 中编写临时的功能测试代码。