# wendi **Repository Path**: kwelldo/wendi ## Basic Information - **Project Name**: wendi - **Description**: 递归解释器:划词即解释,解释可再划,一层层到底。 - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-21 - **Last Updated**: 2026-10-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 问底 WenDi > **遇到不懂的词,就划它。解释里还有不懂的,继续划。一层层到底。** > *Get to the bottom of it.* 在线体验: · 开源(AGPL-3.0)· 欢迎自部署 --- ## 这是什么 一个**递归解释器**。 用 AI 学习新领域时,最大的障碍往往不是信息不够,而是**术语过载**——AI 默认你已经拿着它的术语表。传统的"追问"是线性的:问完一个词,原来的句子已经滚走了;解释里又冒出新的词,问两轮就迷路。 「问底」把这件事做成一个**可回退的空间**: - **划选**任何不懂的词 → 就地分屏给出解释(结合所处句子的语境,不是词典义);划词气泡里还能顺手写下**你的疑惑**,解释就先正面回答它 - 解释卡里的词**还能继续划**,一层层向下 - 公式(LaTeX `$…$` / `$$…$$`)在正文、解释、预览里都按排版渲染(KaTeX,已内置 `web/vendor/katex`,不依赖外网 CDN) - 每一层是一个**同构的房间**:左边是内容,右上是这一层的子解释列表,右下是下一层的预览—— **进入 / 返回**就是摄像机在层级之间移动,深浅不会把字挤小 - 一切可回退(`Esc`),可导出 Markdown,数据存在你自己的浏览器里 ## 它不做什么 这几条是产品立场,不是待办: - **不评判**——没有"这么简单都不懂",也没有"你错了"式的裁决 - **解释是材料,不是答案**——判断与检验永远在读者手里 - **允许含糊**——一个词有多种理解就并列呈现,不强行收敛成一种 - **数据主权**——记录留在本地(`localStorage`);服务端只转发请求,不落地内容 > 设计推导见 [docs/clarity-and-vagueness.md](docs/clarity-and-vagueness.md)(含糊与清晰的辩证关系——这个产品的立身之本)。 ## 快速开始 ### 在线用  (开放注册;不注册也可匿名试用) ### 自己跑(AGPL-3.0,自备模型 key) ```bash git clone wendi && cd wendi # 需要 DeepSeek API key(或任意 OpenAI 兼容端点) export WENDI_API_KEY=sk-xxxx # —— 或者不设环境变量:启动后打开 web 页面 →「设置 → 站长 → 服务端密钥」在线配置(需 WENDI_ADMIN_TOKEN;带 ?admin=1 或存过令牌才会显示「站长」区)—— export WENDI_ADMIN_TOKEN=换一个自己的管理令牌 python3 server.py # → http://127.0.0.1:8899 ``` 核心服务零依赖:只用 Python 3 标准库。**材料解析**(上传 PDF / DOCX / 等 88+ 格式)需要可选依赖 [kreuzberg](https://github.com/Goldziher/kreuzberg) 4.10.x: ```bash python3 -m venv .venv .venv/bin/pip install -r requirements.txt .venv/bin/python server.py ``` 不装也能启动,只是上传接口返回 `503 parser_unavailable`。 可配置环境变量: | 变量 | 默认 | 说明 | |---|---|---| | `WENDI_PORT` | 8899 | 监听端口(只绑 127.0.0.1) | | `WENDI_MODEL` | deepseek-flash | 模型名(可用「密钥」面板覆盖) | | `WENDI_BASE_URL` | https://api.deepseek.com | 任意 OpenAI 兼容端点(可用「密钥」面板覆盖) | | `WENDI_KEYS` | — | 多个 key(逗号分隔),401 自动轮换 | | `WENDI_ADMIN_TOKEN` | — | 管理令牌(meter 端点 + 「密钥」面板 + 建号/发码 + 站长后台);不设则拒绝 | | `WENDI_ADMIN_IPS` | — | 管理端 IP 白名单(逗号分隔;空=不限制)。走 nginx 时认 `X-Real-IP` | | `WENDI_FEEDBACK_PER_DAY` | 5 | 反馈入口:每 IP 每天最多几条 | | `WENDI_FEEDBACK_INTERVAL` | 30 | 反馈入口:同一 IP 两条之间的最小间隔(秒) | | `WENDI_FEATURE_SYNC_FREE` | 1 | 增值权益「云同步」是否对所有人免费(设 0 = 仅 Pro) | | `WENDI_FEATURE_MATERIALS_FREE` | 1 | 增值权益「材料解析」是否对所有人免费(设 0 = 仅 Pro) | | `WENDI_FEATURE_EXPORT_FREE` | 1 | 增值权益「导出与高级功能」是否对所有人免费(设 0 = 仅 Pro) | | `WENDI_EVENT_PER_MIN` | 90 | 每 IP 每分钟事件上限(超出静默丢弃) | | `WENDI_LIMIT_PER_MIN` | 8 | 每 IP 每分钟请求上限 | | `WENDI_LIMIT_PER_DAY` | 80 | 每 IP 每天上限 | | `WENDI_LIMIT_GLOBAL_DAY` | 4000 | 全局每天上限(成本闸) | | `WENDI_MAX_TOKENS` | 3000 | 划词解释/追问的单次输出上限 | | `WENDI_MAX_TOKENS_CHAT` | 8000 | 主对话的单次输出上限(长答不再截断;降级档另有上限) | | `WENDI_MATERIALS_DIR` | `~/.wendi/materials` | 材料原始文件目录(按用户分 0700 子目录) | | `WENDI_UPLOAD_MAX_MB` | 30 | 单文件上传上限(MB) | | `WENDI_MATERIALS_MAX` | 200 | 单用户材料条数上限 | | `WENDI_MATERIALS_MAX_MB` | 500 | 单用户原始文件总额(MB) | ### 部署 `deploy/` 里是完整的生产部署件(systemd unit + nginx 反代脚本 + 幂等部署脚本): ```bash WENDI_HOST=ubuntu@your-server ./deploy/deploy.sh ``` Debian 13 用 `/opt/wendi/.venv`(PEP 668);材料解析依赖优先从离线 wheel 安装, nginx 需放行 35MB 上传。完整步骤、验证与回滚见 [docs/deploy.md](docs/deploy.md)。 ## 结构 ``` server.py 薄代理:转发 LLM 调用 + 限流(防滥用/成本闸)+ 材料上传接口 materials.py 材料解析:kreuzberg 懒加载 + 全文/分块/页码规范化 db.py SQLite:账户、配额、事件、云同步、材料(materials / material_chunks) requirements.txt 唯一第三方依赖:kreuzberg(不装也能启动) kernel.py 内核:事件总线 + 服务注册 + 作用域生命周期(借鉴 cordis,MIT) prompts.py 解释器人格:划词解释 / 卡内追问 / 主对话 三个提示词 explain_output.py 流式解释的来源元数据拆分:语境说明 / 可能卡点与正文分离 web/index.html 全部前端(单文件、零构建):分形房间 + 摄像机 + 键盘导航 web/graph2d.html 当前会话的 2D 图谱:底部 = 对话轮次时间线,向上 = 解释层数;卡片详情可回看划词原文、语境和可能卡点(只读同一份 localStorage) web/vendor/katex 内置数学排版(KaTeX 0.18.9,升级步骤见该目录 README) web/about.html 关于 wendi(立场、数据主权、合规状态) web/privacy.html 隐私政策(收集什么/不收集什么、保留期、你的权利) web/terms.html 服务条款(测试期口径、兑换码、免责) web/feedback.html 反馈表单(进站长后台,匿名可发) web/messages.html 站内消息(登录用户查看开发 Agent / 站长的澄清问题) web/admin.html 站长后台(总览 / 反馈 / 用户 / 兑换码 / 成本闸 / 审计) web/meter.html 计量台(逐日账、单用户 drill-down) web/site.css 文档页共用样式(大报编辑体 token) scripts/daily_report.py 日报(重算聚合 + 写 reports/YYYY-MM-DD.md + 剪 90 天前事件) scripts/feedback_bridge.py 用户反馈 → OpenCode 免费分流 → clds fix/大改方案(本地轮询) .opencode/agents/feedback-triage.md 轻量单步、只输出 JSON 的免费模型分流 agent deploy/ 部署件(systemd / nginx / 部署脚本;含 feedback agent 用户服务与 env 示例) messages.py 站内消息的最小数据层(user_messages,按账号隔离) tests/ 测试(python3 -m unittest discover -s tests) docs/ 理论文档 + 架构图(wendi-architecture.html,可交互) docs/materials-api.md 材料上传/解析/读取接口(含 curl 示例与部署提示) docs/deploy.md 上线部署(venv / 离线 wheel / nginx / 验证 / 回滚) ``` 前端交互要点:划词气泡(可附一句自己的疑惑)、`Esc`/`Alt+←` 返回上层、`↑↓` 切换子解释、`Alt+Enter`/`Alt+→` 进入(进/退都带 Alt,避免生成过程中误触把回答顶出视野)、SSE 流式输出(边生成边显示,只原地补内容不整页重绘)。导出 / 图谱 / 示例 / 已移除 / 清空都收在顶栏「设置」里;反馈入口 = 设置面板 + 右下角常驻「反馈 / 建议」;站长那套(服务端密钥 / 站长后台 / 计量台)默认不显示,带 `?admin=1` 或存过 admin 令牌才出现。 ## 形态 ``` ┌──────────────────────────┬───────────────┐ │ │ 子解释列表 │ │ 当前层内容 │ (可滚动) │ │ (可继续划词) ├───────────────┤ │ │ 下一层预览 │ │ │ (同构缩小版) │ └──────────────────────────┴───────────────┘ ↑ 点预览或「进入 ▸」→ 视野切换(整层同构递归) ``` ## 路线图 - [x] **v0.1.0** 划词递归解释(分形房间 + 摄像机视野) - [x] **v0.2.0** 引导教程(30 秒上手)· 账户与配额 · 云同步 · 增值兑换码 - [ ] 知识图谱视图(术语卡积累成网) - [ ] 团队版 ## 匿名采集与看板 - 开放注册,无需任何码;Pro 由**增值兑换码**(`codes` 表,kind='pro')开通。 - 前端 12 个动作事件 + 服务端事件(注册/登录/反馈/系统错误)走 `POST /api/event`,落 `events` 表; **只记动作与元数据,不记正文**;IP 只存加盐哈希。 - 每请求一行 JSON 日志(stderr,journal 可查);LLM 计量补 `session_id` / `room_id`。 - `daily_metrics` 按天聚合(幂等重算),看板:`/api/admin/metrics`、`/api/admin/events`。 - 日报:`python3 daily_report.py [YYYY-MM-DD]`(服务器上由 `wendi-report.timer` 每天 23:55 跑)。 ## 用户反馈 → 开发 Agent(一期,两段式) 反馈不在生产服务器上直接调模型,而是由开发者机器上的桥接脚本分两段处理: ``` /feedback.html → feedback(status=new) → OpenCode 免费模型分流 ignore → 不调 clds ask_user → 发站内澄清问题,不调 clds fix → clds 在隔离 worktree 做最小修复,产出待审 patch + 测试结果 big_change → clds 只写方案,不改代码 → feedback 标 read,note 记方案/分支 → 需要追问且用户登录且 can_reply:/messages.html 站内消息 ``` 分工: - **OpenCode**:只做分流判断,使用免费模型 `opencode/deepseek-v4.1-flash-free`; 项目内 `.opencode/agents/feedback-triage.md` 是专用 agent(`steps: 1`,禁用 edit/bash, prompt 要求不使用工具、只输出 JSON)。已知边界:OpenCode 免费层对权限组合敏感, 没有硬禁所有读工具;clds 侧才是 restricted + 空 MCP 的强隔离。 - **clds**:只在 `fix` 或 `big_change` 时调用。 - `fix`:在独立 git worktree 里改代码,桥接统一跑测试,产出 `fix-.patch` 和报告; **不提交、不合并、不部署**。 - `big_change`:只读 plan 模式,只写方案,不改代码。 - **不做大改**:`fix` 触及 `server.py` / `db.py` / `auth.py` / 部署 / 隐私条款等禁区时, 桥接会标记“触碰禁区,需人工”,不会自动合并。 - **联系方式不进 Agent**:contact/email 字段不发送;正文中的邮箱、手机号、带标签联系方式先脱敏; 只发送 `user_id`、`can_reply` 等必要元数据。 - **不虚假许诺**:站内追问只允许带问号的澄清问题,拒绝“已修复 / 保证 / 一定 / 24小时”等话术。 安装: ```bash mkdir -p ~/.config/wendi ~/.config/systemd/user cp deploy/feedback-agent.env.example ~/.config/wendi/feedback-agent.env chmod 600 ~/.config/wendi/feedback-agent.env # 编辑 env:至少填 WENDI_ADMIN_TOKEN;确保本机 OpenCode 后台服务和 clds 可用 # 先看一轮会发给分流器的 prompt(不调模型、不标 read) python3 scripts/feedback_bridge.py --once --dry-run # 手动跑一轮 python3 scripts/feedback_bridge.py --once # 作为用户级常驻服务(路径按你的仓库位置改 deploy/wendi-feedback-agent.service) cp deploy/wendi-feedback-agent.service ~/.config/systemd/user/ systemctl --user daemon-reload systemctl --user enable --now wendi-feedback-agent.service journalctl --user -u wendi-feedback-agent.service -f ``` 桥接会校验 OpenCode 分流模型的 `/api/model` cost 是否全为 0,避免误用付费模型。 方案与 fix 报告输出到 `~/.local/state/wendi-feedback-agent/plans/`,fix worktree 默认在 `~/.local/state/wendi-feedback-agent/worktrees/`,供人工审查。 完整设计见 [`docs/plans/2026-10-18-feedback-to-dev-agent.md`](docs/plans/2026-10-18-feedback-to-dev-agent.md)。 ## 账户与配额 | 身份 | 每日额度 | 说明 | |---|---|---| | 未登录(匿名) | 20 次 | 按 IP | | 免费账号 | 40 次 | 开放注册即得 | | Pro(增值) | 300 次 | 兑换码激活 | **核心功能(划词解释)不按使用收费**;Pro 属增值服务。云同步、材料解析、导出等增值点由 `entitlements.py` 统一管理:`meter_config` 键 `feature_<名>_free`(或环境变量 `WENDI_FEATURE_<名>_FREE`)设 0 即仅 Pro 可用,默认对所有人免费。 云同步:登录后点顶栏「同步↑」把本地数据(对话 + 解释卡)备份到云端;换设备登录时会询问是否载入。 ### 部署方:生成增值兑换码 ```bash ssh your-server 'cd /opt/wendi && python3 gencode.py 10 30 launch' # 参数:数量 天数 备注 ``` ## 运维速查 ```bash # 请求日志(每请求一行 JSON:状态码/延迟/用户/会话/成本) ssh 'sudo journalctl -u wendi -n 200 -o cat | grep ^{' # 日报(重算聚合 + 写 reports/YYYY-MM-DD.md + 剪 90 天前事件) ssh 'cd /opt/wendi && python3 daily_report.py' # 或看 /opt/wendi/reports/ # 看板(浏览器,需管理令牌):总览 / 反馈 / 用户 / 指标 / 事件流 / 兑换码 / 闸门 / 审计 https://know.kwelldo.cn/admin.html ``` ## 许可 **AGPL-3.0**(GNU Affero General Public License v3.0)——见 [LICENSE](LICENSE)。 - 自由使用、修改、再分发;以 AGPL-3.0 兼容方式开源你的修改版(含网络服务场景,见许可证第 13 条)。 - 官方实例 与本仓库源码一致;增值服务(Pro/兑换码)只在官方实例提供。 - 第三方组件:KaTeX(MIT)见 `web/vendor/katex/LICENSE`;其余依赖各自的许可随代码保留。