把项目文件夹丢进去就OK了。
高强度使用 AI 写代码时，最稀缺的不是生成能力，而是对项目本身的理解：
- 整体架构长什么样？
- 这段代码的运行路径是什么？
- 这个模块到底负责啥？
- 这个奇怪的语法又是干嘛的？
用 Claude / ChatGPT 当然能问出来，但 chat 范式有几个绕不开的痛点：
- 🧩 碎片化 —— 每次都从零开始喂上下文，问 10 次浪费 9 次
- 👀 混乱的视觉 —— 代码、解释、追问、回答全混在一条时间线
- 📚 难以沉淀 —— 关掉对话就什么都没了，下次还得再问一遍
CoReader 把"理解一个项目"这件事从对话流里解放出来：上传代码 → 自动生成结构化文档 + 智能问答 + 自测题，三种方式各取所需。
上传项目后，后台会跑一条完整的分析管线：AST 拆解 → 模块识别 → 分层目录 → LLM 撰写。最终产出一套层级化的 wiki 文档：
项目概览
├─ 分类（Category）
│ └─ 章节（Chapter）
│ └─ 主题（Topic）
│ └─ 模块详情（Module Page）
每页都带可点击的源码引用（点击直接打开侧边代码窗口），不是空中楼阁式的解读。
- 快速模式：单次 LLM 调用 + 预先拼好的项目上下文，秒回。适合"这个变量啥意思"。
- 深度模式：基于 Agent Loop，LLM 可以自主调用 7 个工具（查摘要、查符号、查调用关系、读文件、全文搜索…）在 SQLite 化的项目结构里"现场调研"，再综合回答。适合"这段流程是怎么走的"。
整个 Agent 思考过程在前端实时流式可视化：工具调用、参数、返回结果一一展开，不再是黑盒。多轮对话有完整记忆 + 自动压缩，长会话也不爆上下文。
基于已生成的 wiki 自动出选择题，校验你对项目的掌握度。给自己用、给团队新人用、给面试候选人用都行。每题都附带代码依据（文件:行号），可点击直接定位源码。
| AST 优先，不是 LLM 盲猜 | tree-sitter 多语言解析（Python / Rust / Java）→ 函数符号 / 调用边 / 入口点抽取 → SQLite 持久化。LLM 通过工具查这个结构化数据，而不是把整个项目塞进 prompt——这让大项目也能精准回答，不受上下文窗口限制 |
| 统一的 Agent Loop + Skill 系统 | 一套带 7 个工具的 Agent 循环（get_modules / get_summaries / get_symbols / get_call_edges / search_code / search_symbols / get_file_content + spawn_agent）同时驱动 Wiki / QA / Quiz 三个能力；复杂任务（如"按业务职责拆模块"）封装成 Skill 复用，包含独立 system prompt + 工具子集 |
| 两档 QA：快回答 vs 深探索 | 快速模式：单次 LLM 调用 + 预拼项目上下文，秒回适合"这变量啥意思"。深度模式：完整 Agent Loop + 7 个工具 + 自动压缩 + 最多 30 轮迭代，适合"这流程怎么走"。两种成本档让用户按需选，便宜问题不浪费 token，难问题不偷工减料 |
| OpenAI 协议兼容 + 模型分层 | 接 Qwen / Kimi / MiniMax / 任何 OpenAI 兼容网关，换模型只改一个环境变量。摘要类轻量任务走 QWEN_FAST_MODEL，Agent 主循环走强模型，整套 wiki 生成成本压低近 3 倍 |
| 流式优先，过程透明 | SSE 实时推送 token / 工具调用 / 工具结果 / 压缩事件 / 完成事件，前端工具时间线把 Agent 思考过程逐步展开。每个工具调用看得到参数和返回结果摘要——不是干等黑盒，用户能看到当前 LLM 正在做啥、跑到哪了 |
| 生产级容错（踩过坑的那种） | LLM 网关每次 90s 主动 kill + 退避重试；工具返回超 30KB 自动截断（防止 get_call_edges 误返回全图把上下文撑爆）；长会话 token 接近 budget 自动压缩历史；Wiki 任务后台异步 + task_id 持久化，浏览器刷新也能继续看进度而不是从头再来 |
| 代码即引用，点击就跳转 | Wiki 每段叙述都带源码引用 <code_ref:文件:行号:函数>，点击弹出侧边代码窗口高亮目标行。引用由 Agent 在生成时自己挑（"这段话依据哪几行代码"），不是事后正则瞎匹配——保证了引用和叙述的真实对应 |
| 现代前端栈，体验细抠 | React 19 + TypeScript + Vite 8 + Tailwind 4 + Zustand。多 store 按域拆分（Wiki/QA/Quiz/Layout），整页 ErrorBoundary 拦截任何渲染异常，Wiki/QA/Quiz 可拖拽并排同屏，localStorage 持久化导航宽度、主题、深度模式开关等所有用户偏好 |
后端：FastAPI · SQLite · tree-sitter · OpenAI 兼容 LLM（默认 Qwen / MiniMax） 前端：React 19 · TypeScript · Vite 8 · Tailwind CSS 4 · Zustand · react-markdown · highlight.js · Mermaid
复制环境变量模板：
cp .env.example .env编辑 .env，至少填一个能用的 OpenAI 兼容网关：
QWEN_API_KEY=sk-xxxxxxxx
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen3.6-plus变量名沿用
QWEN_前缀只是历史原因 —— 实际走的是 OpenAI 协议，DashScope / sub2api / 自建 vLLM / 任何兼容端都行。.env.example里有 MiniMax 的备选配置。
pip install -r backend/requirements.txt
PYTHONPATH=. uvicorn backend.main:app --reload --port 8000
⚠️ PYTHONPATH=.是必须的，后端用绝对导入。
cd frontend
npm install
npm run dev浏览器打开 Vite 输出的本地地址（默认 http://localhost:5173）即可。
CoReader/
├─ backend/
│ ├─ controllers/ # FastAPI 路由（file / wiki / qa / quiz）
│ ├─ services/
│ │ ├─ agent/ # 核心 Agent Loop + 7 个工具 + Skill 系统
│ │ ├─ wiki/ # Wiki 生成管线
│ │ ├─ qa/ # 问答（fast / deep 双模式）
│ │ ├─ quiz/ # 题目生成
│ │ └─ llm/ # OpenAI 兼容客户端 + Prompt 模板
│ ├─ dao/ # SQLite 持久化
│ ├─ models/ # Pydantic 数据模型
│ └─ utils/analysis/ # AST 分析管线（多语言）
└─ frontend/
└─ src/
├─ components/ # Wiki / QA / Quiz / Upload / CodeDrawer
├─ store/ # Zustand stores
├─ services/ # 后端 API 封装（含 SSE 解析）
├─ contexts/ # 主题 + 国际化
└─ i18n/ # 中英文文案
- 单个文件 ≤ 1MB，整个项目 ≤ 10MB / 200 个文件（防止 LLM 调用失控）
- AST 分析目前覆盖 Python / Rust / Java，其他语言上传后只做文本摘要
- 长任务（Wiki 全量生成）走后台异步 + 状态轮询，需要保持后端进程存活
- 目前未做用户隔离，仅适合本地或单租户场景使用
Made with ☕ and 🤖 in 2026