meeting_memory/README.md

# Meeting Knowledge Interactive Agent

这是一个以“大模型交互式 Agent”为主体的会议知识库项目。用户在 CLI 里自然语言对话，Agent 自己决定什么时候调用工具；`导入会议转录` 和 `查询周会台账` 只是 Agent 可用的工具，不是项目主体入口。

工程结构按 `D:\github_project\my_code\my_agent` 的 Agent 骨架组织，方便后续扩展 provider、tools、skills、memory 和任务调度。

## 目录结构

```text
meeting_knowledge/
├─ agent.py                    # 顶层 Agent 装配入口
├─ main_cli.py                 # 交互式 CLI 主入口
├─ main.py                     # 兼容入口，转到 main_cli.py
├─ prompts.py                  # system prompt 组装
├─ dispatch.py                 # 任务调度扩展点
├─ core_agent/
│  ├─ config.py                # .env / 环境变量配置
│  ├─ compression.py           # 长上下文压缩
│  └─ session.py               # 多轮会话与工具调用循环
├─ providers/
│  ├─ base.py                  # Provider 抽象
│  ├─ openai_compatible.py     # OpenAI-compatible 模型适配
│  ├─ rule_based.py            # 离线规则 Provider，仅用于 --offline 演示
│  └─ prompt_loader.py
├─ tools/
│  ├─ registry.py              # 工具注册中心
│  ├─ default_tools.py         # 默认工具集合（通用工具 + 会议工具）
│  ├─ general_tools.py         # 读写文件、目录浏览、shell、Python 等基础工具
│  ├─ meeting_tools.py         # 会议导入/查询工具
│  └─ tool_trace.py            # 工具调用轨迹本地存储
├─ meeting_memory/             # 会议台账业务层
│  ├─ meeting_digest_agent.py  # 会议整理子 Agent，负责把原文整理成结构化结果
│  ├─ ledger.py                # Markdown/JSON 台账存储
│  └─ service.py               # 会议知识库业务服务
├─ prompt/zh/base.yaml         # 中文基础提示词
├─ .env.example                # 大模型配置模板
├─ .env                        # 本地大模型配置，需填写真实值
├─ webui/                      # Web 页面静态资源
├─ webui_server.py             # FastAPI Web 服务入口
└─ requirements.txt
```

## 安装依赖

```powershell
pip install -r requirements.txt
```

## 配置大模型

本项目适配 OpenAI-compatible API，也就是兼容 `/v1/chat/completions` 的接口，并要求模型支持 tools/function calling。

复制或直接编辑 `.env`：

```text
OPENAI_API_KEY=你的key
OPENAI_BASE_URL=https://你的服务地址/v1
MODEL_NAME=你的模型名

OPENAI_TIMEOUT=120
OPENAI_TEMPERATURE=0.2
CORE_AGENT_MAX_ITERATIONS=12
```

也兼容这些别名：

```text
API_KEY -> OPENAI_API_KEY
BASE_URL -> OPENAI_BASE_URL
CORE_AGENT_MODEL / MODEL -> MODEL_NAME
```

## 运行交互式 Agent

默认运行会读取 `.env` 并调用你的 OpenAI-compatible 模型：

```powershell
python .\main_cli.py
```

进入后可以直接说：

```text
导入 D:\github_project\my_code\meeting_agent\examples\huiyi.txt 知识库 合川分公司
```

然后继续问：

```text
专线护航还有哪些待办？知识库 合川分公司
```

## 运行 Web UI

当前 Web 前端源码已经收口到本项目的 `webui/frontend/` 中，构建后的静态文件统一输出到 `webui/dist/`，由 `webui_server.py` 直接托管，不再依赖单独的 `nanobot` 目录。

### 1. 安装前端依赖

```powershell
cd .\webui\frontend
npm install
```

### 2. 构建前端

```powershell
npm run build
```

构建产物会输出到：

```text
.\webui\dist
```

### 3. 启动 Web 网关

```powershell
python .\webui_server.py
```

默认地址：

```text
http://127.0.0.1:8010
```

如果只想离线演示整条链路，不调用大模型：

```powershell
python .\webui_server.py --offline
```

## 离线演示模式

只有想验证工具链、不调用大模型时，才使用：

```powershell
python .\main_cli.py --offline
```

单条离线导入测试：

```powershell
python .\main_cli.py --offline --once "导入 D:\github_project\my_code\meeting_agent\examples\huiyi.txt"
```

## Agent 工具

- `current_time`：获取当前时间。
- `list_directory`：浏览工作区目录。
- `search_files`：按文件名搜索工作区文件。
- `read_file`：读取工作区内文本文件。
- `write_file`：写入工作区内文本文件。
- `execute_shell`：执行 shell 命令做环境检查或调试。
- `run_python`：执行简短 Python 代码做快速处理。
- `tool_trace_query`：按需查询本地保存的工具调用轨迹。
- `store_meeting_memory`：把会议原文写入长期会议记忆，执行抽取、归档、状态合并与图谱索引。
- `query_meeting_memory`：查询长期会议记忆中的会议上下文、实体关系、行动项和指标信息。

LLM Agent 会在对话中自动选择这些工具。当前知识功能已经切换到图谱化的 `meeting_memory` 管线，不再维护旧版 Markdown 台账知识库。

## 多轮会话机制

当前多轮会话参考了 `D:\github_project\my_code\my_agent` 的实现思路：

- 每个会话保留最近 `20` 轮用户/助手对话并本地落盘。
- 超出窗口后，会通过 `core_agent/compression.py` 做滚动摘要压缩，而不是无限堆上下文。
- 工具调用的参数、思考、结果会单独保存到本地 `tool_trace.json`。
- 默认不会把大量工具过程长期塞回主上下文；需要时由 Agent 调用 `tool_trace_query` 再查。

CLI 默认使用会话 `cli_default`。Web 侧每个聊天会映射到独立的本地会话目录。

## 输出数据

默认写入：

```text
data/
├─ meeting_state.json
└─ raw/
```

`team_ledger.md` 是面向人和 Agent 共同读取的主文档；`state.json` 和 `meetings/*.json` 是可复用的结构化中间结果。

当前整理逻辑是：

- 每个知识库只维护一份 `team_ledger.md` 主台账。
- 每次导入只处理一份会议原文。
- 会议原文会先交给会议整理子 Agent，按“项目”抽取重要信息，再更新同一份 Markdown。
- 如果本次会议提到历史项目，就更新已有项目状态；如果出现新项目，就新增项目条目。

多轮会话和工具轨迹默认写入：

```text
agent_memory/
└─ sessions/
   └─ <session_id>/
      ├─ recent_history.json
      └─ tool_trace.json
```