init README

README.md

@@ -0,0 +1,199 @@
+# AI智能瞭望与智能问数系统
+
+# 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=<endpoint_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 |` 格式），生成 `<table>/<thead>/<tbody>` 结构，样式支持圆角边框/表头高亮/行悬停/横向滚动。
+   - 意图识别优化：增强模板（详细表结构说明、分类规则、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` 保持页面结构统一。
+   - 表单提交时，务必在 `<form>` 标签内包含 `{% module xsrf_form_html() %}` 以通过 CSRF 校验。
+   - 静态资源（CSS, JS, 图片等）存放在 `app/static/` 目录下，在模板中通过 `{{ static_url('...') }}` 引用。
+   - 页面自定义样式请放在 `{% block style %}` 中（由 `base.html` 在 head 内输出），避免样式丢失。
+4. **测试规范**:
+   - 可以继续在 `test.py` 中编写临时的功能测试代码。