知微 Zhiwei

见微知著 · 一纸入脑

把一段文字粘进去，几秒钟拿到三样东西：摘要、考点、思维导图。

面向复习场景做的小工具：讲义、笔记、报告、长文，丢进来就能变成可以直接背的笔记。

粘贴原文  →  摘要（一段话讲清楚）  →  考点（带重要程度，可出题）  →  思维导图（树状 + 可复制文本）

---

功能

• 摘要：150–250 字一段话，不复述原文腔调，直接说讲了什么
• 要点：3–6 条，每条不超过 40 字
• 考点：3–7 条，每条含「考点 / 具体内容 / 重要程度（高·中·低）」，按重要度排序
• 思维导图：最多 3 层的树，可切换「树状图 / 文本 / Markdown」三种视图，一键复制
• 长文自动分块：超过 4000 字先逐段压缩再汇总，避免超长请求被截断
• 没 Key 也能跑：未配置 API Key 时自动切到内置离线规则引擎，功能完整、结果可复现，方便演示和 CI
• 两种入口：网页版（粘贴即用）和命令行版（可接管道、可导出 JSON）

快速开始

git clone <repo> && cd zhiwei

python -m venv .venv
.venv\Scripts\activate           # Windows
# source .venv/bin/activate      # macOS / Linux

pip install -r requirements.txt

copy .env.example .env           # Windows，然后填 Key
# cp .env.example .env           # macOS / Linux

python app.py --open

浏览器打开 http://127.0.0.1:8765，把文字粘进左边，点「开始分析」。

不想配 Key 也可以直接跑：跳过复制 .env 这一步，程序会自动使用离线规则引擎，界面上会显示「离线规则引擎」角标。

两种运行模式

	DeepSeek 模式	离线模式
触发条件	配置了 DEEPSEEK_API_KEY	没有 Key
原理	调用 DeepSeek chat/completions，response_format=json_object	本地规则：分句、词频打分、关键词聚类
联网	需要	完全不需要
适合	真实使用	演示、跑测试、断网环境

两种模式共用同一条代码路径（都返回 JSON 字符串再解析），所以离线模式顺带把 JSON 解析逻辑也测了。

命令行

# 分析一个文件
python -m zhiwei.cli samples/sample-note.txt

# 从管道读
type note.txt | python -m zhiwei.cli

# 导出 JSON / 只要 Markdown 版导图
python -m zhiwei.cli note.txt --json > out.json
python -m zhiwei.cli note.txt --markdown

HTTP 接口

方法	路径	说明
GET	/api/health	当前模式、模型、字数上限
GET	/api/sample	内置示例文本
POST	/api/analyze	请求体 {"text": "..."}，返回结构化结果

curl -X POST http://127.0.0.1:8765/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"text":"在这里粘贴至少 30 个字的内容……"}'

返回：

{
  "ok": true,
  "data": {
    "title": "睡眠与记忆巩固",
    "summary": "……",
    "key_points": ["……"],
    "exam_points": [{ "point": "……", "detail": "……", "level": "高" }],
    "mindmap": [{ "text": "睡眠", "children": [{ "text": "……", "children": [] }] }],
    "mindmap_text": "睡眠与记忆巩固\n├─ 睡眠\n│  ├─ ……",
    "mindmap_markdown": "- 睡眠\n  - ……",
    "tags": ["睡眠", "记忆", "巩固"],
    "meta": { "provider": "deepseek", "model": "deepseek-chat", "elapsed_ms": 8321 }
  }
}

配置项

全部通过环境变量或项目根目录的 .env 读取（环境变量优先）。

变量	默认值	说明
DEEPSEEK_API_KEY	空	留空即进入离线模式
DEEPSEEK_BASE_URL	https://api.deepseek.com	兼容任何 OpenAI 协议的服务
DEEPSEEK_MODEL	deepseek-chat	模型名
DEEPSEEK_TIMEOUT	120	单次请求超时（秒）
ZHIWEI_MAX_CHARS	20000	单次分析的最大字数，超出会截断
ZHIWEI_CHUNK_CHARS	4000	超过这个长度就分块处理

目录结构

zhiwei/
├── app.py                   # Flask 入口
├── zhiwei/
│   ├── config.py            # 配置读取（自带极简 .env 解析）
│   ├── prompts.py           # 提示词，集中放便于调参
│   ├── providers.py         # DeepSeek 客户端 + 离线规则引擎
│   ├── core.py              # 编排：分块 / 调用 / 解析 / 规范化
│   ├── mindmap.py           # 导树的清洗与文本导出
│   └── cli.py               # 命令行入口
├── static/                  # 前端（原生 HTML/CSS/JS，无构建步骤）
├── samples/sample-note.txt  # 示例文本
└── tests/                   # pytest

几个实现上的取舍

一次请求拿全部结果。 摘要、考点、思维导图由同一次调用返回，用 response_format=json_object 约束成 JSON。比拆成三次请求快得多，也避免三份结果互相矛盾。

对模型的输出保持不信任。 模型偶尔会在 JSON 外面包一层代码块，或者留下尾逗号。extract_json() 会依次尝试：原始文本 → 去掉代码块 → 截取首尾大括号 → 修掉尾逗号；全部失败再让模型自己修一次，仍然失败才报错。

规范化兜底。 normalize_result() 会把缺失字段补上、把越界的重要程度拉回「中」、把超过 4 层的导树砍掉、把空节点剔掉。前端永远拿到同一个结构。

长文先分块。 split_chunks() 按空行切段落，尽量不把一句话劈开；每块先压成 120 字，再把这些摘要拼起来做最终分析。

测试

pip install -r requirements-dev.txt
pytest -q

覆盖：JSON 容错解析、结果规范化、导树深度与文本导出、分块、离线引擎端到端。

License

MIT