GitHub：https://github.com/SamZebrado/GrapePaper
1. 摘要
我尝试从零做了一个叫 GrapePaper 的学术编辑器原型：段落被渲染成“石板”，批注像“葡萄叶”一样从段落边缘长出来，引用像“露水”一样附着在文本附近，和批注相关的问题则以侧边聊天面板的形式展开。
这个项目主要用 TRAE / SOLO Code 协助完成，从想法整理、竞品调研、开发计划、代码实现，到测试、重构和文档收口，基本都经历了多轮迭代；遇到疑难问题时，我也会让另一个 LLM 参与复核、验收和纠偏。
项目使用 React + TypeScript + Vite 构建，当前已实现：
- 基础富文本编辑
- 批注的添加 / 编辑 / 删除
- 引用的展示与悬停预览
- Markdown / JSON 导入导出
- localStorage 持久化
- 中英文界面切换
- 60+ 测试用例
但需要提前说明：当前版本仍然是一个可运行的交互原型，而不是成熟产品。
虽然核心交互链路已经打通，但 UI 细节、视觉一致性、引用工作流、真实 AI、PDF / Zotero / docx / tex 等能力都还没有完成。包括“石板、树叶、露水”这些视觉元素，目前也只是做到了“有这个方向”，还远远没到精细打磨的程度。
2. 背景
我是一个平时需要大量读论文、写论文的博士生。虽然不是职业前端开发者，但科研工作里经常要写代码、搭工具，所以会自然地从“自己真实会不会用”这个角度去想工具。
传统论文编辑器（例如 Word、Overleaf、Google Docs）在功能上当然已经很强，但它们的视觉与交互逻辑都比较统一：白底黑字、线性文档、层层菜单。这些设计本身没有问题，但长时间面对整页规整文本时，确实会带来一种比较直接的心理压力。对我来说，这种压力不一定来自“论文”本身，也不一定能靠换个主题就解决，但如果能把写作界面做得稍微“没那么像论文”，也许能给情绪一个更平缓的台阶。
于是我想试一个方向：
如果论文编辑器不长得像论文，而更像一个花园式的写作空间，会怎么样？
GrapePaper 就是在这个问题上做的一个原型探索。
它的目标不是证明“自然隐喻一定更好”，而是先验证：这种界面风格和交互组织方式，能不能支持一个基本可用的学术写作原型。
3. 实践过程
3.1 先做竞品调研，而不是直接开写
在真正写代码之前，我先让 SOLO Code 和其他 LLM 协助做了一轮竞品调研，重点看的是与以下方向相关的产品：
- Gingko Writer
- Scrintal
- Heptabase
- LiquidText
- Curvenote
- Hypothesis
调研之后比较清楚的一点是：
- 直接竞品很少：我没有看到谁在做“葡萄藤 / 石板 / 露水”这种强自然隐喻的学术编辑器。
- 相邻竞品不少：它们分别覆盖了树状写作、视觉知识管理、跨文档批注、科学写作、社交标注等能力。
所以 GrapePaper 的定位不应该写成“功能首创”，而应该更诚实地说：
它的独特点不在于单点功能，而在于尝试把写作、批注、引用和对话整合进一个自然隐喻驱动的界面原型里。
3.2 技术选型：优先选熟悉、稳定、便于快速迭代的栈
后面定下来的技术栈大概是：
- React 18
- TypeScript 5.6
- Vite 6
- Zustand（状态管理）
- TipTap 2（富文本编辑）
- Framer Motion（动画）
- CSS Modules + CSS Variables（主题与样式）
- Vitest + Testing Library（测试）
这里有一个挺现实的点：项目最开始尝试过更新一点的构建方案，但很快在依赖和跨平台问题上踩坑，后面又退回到更稳妥的版本组合。也就是说，这个项目不是一开始就设计得很完美，而是边做边收紧、边踩坑边回退到更稳方案。
3.3 核心组件与交互原型
在原型阶段，逐步做出来的主要组件包括：
- StoneSlab：石板段落容器
- GrapeLeaf：批注叶片
- DewdropCitation：露珠式引用显示
- ChatPanel / ChatBubble：批注相关聊天面板与消息
- VineConnector：段落间的藤蔓连接装饰
- Sidebar：文档标题、段落导航、导入导出、状态区
- EditorCanvas：主编辑区域
这些名字听起来挺完整，但要诚实一点说：
“组件已经实现”不等于“视觉已经打磨成熟”。
当前版本里，更可靠的部分是交互链路和工程结构；视觉层面仍有明显的原型味道。
3.4 多轮迭代：从“能跑”到“可复现”
后面的主要工作，其实不是不停加新功能，而是反复做这些事情：
- 修构建和依赖问题
- 把导入导出逻辑从 UI 中抽成纯函数
- 给 localStorage 加恢复与校验
- 加 JSON / Markdown 导入导出
- 给批注补编辑 / 删除
- 把 alert / confirm 之类的临时交互替换成更统一的 UI 反馈
- 做 UIContext 重构
- 补测试
- 改文档
- 清理源码包和交付物
一路做下来，项目最后形成的是一个可运行、可测试、可复现的本地原型，而不是“做完一个成熟产品”。
4. 成果展示
4.1 当前已完成的内容
截至当前版本，项目已经实现：
- 基于 TipTap 的富文本段落编辑
- 批注的添加、展开、编辑、删除
- 批注相关的 mock 聊天面板
- 引用的露珠式展示与悬停预览
- Markdown / JSON 导入导出
- localStorage 本地持久化
- 中英文界面切换
- 60+ 测试用例
npm install / test / typecheck / build可通过
4.2 当前明确未完成或仅为展示的部分
这部分我想写得直接一点，因为比赛里我不想把“原型”说成“产品”：
- AI 聊天目前是 mock，没有接真实 LLM
- 引用目前是展示型功能
使用硬编码示例数据，支持悬停预览，但不支持编辑、创建、删除，也没有 Zotero 集成 - 没有 PDF 导入 / 渲染
- 没有 docx / tex 导入
- 没有深色主题
- 没有移动端响应式优化
- 视觉层仍是半成品，包括石板、树叶、露水、藤蔓等元素都还没精细打磨
4.3 截图展示（建议少放、但放关键图）
建议只放 4–6 张最有价值的图，不要堆太多：
-
总览图
左侧侧边栏 + 右侧石板段落主编辑区
【放 overview 图】 -
标题与正文编辑
展示标题输入和段落编辑
【放 title / paragraph 编辑图】 -
批注展开与编辑
展示 annotation 的展开与编辑状态
【放 annotation expanded / editing 图】 -
聊天面板
展示从批注进入的 mock chat
【放 chat panel 图】 -
导入导出或重置确认
展示文档状态管理和文件进出能力
【放 import/export 或 reset confirm 图】
如果图片数量有限，我会优先保证：
- 总览
- 批注编辑
- 聊天面板
- 导入导出 / reset
这几张。
5. 效果与总结
5.1 SOLO 在这个项目里实际扮演了什么角色？
如果用一句话概括，我会写：
SOLO 更像一个高吞吐的实现代理，而不是“自动完成项目”的黑盒工程师。
它在这个项目里最有价值的地方，是承担了大量高频、机械、容易烦、但又确实要做的工作：
- 把想法快速落成代码原型
- 反复做重构和版本收口
- 生成组件骨架、测试骨架、文档草稿
- 在明确需求后持续推进实现
- 把很多“人会嫌烦”的工程体力活前置吃掉
但它没有替代掉的事情也很清楚：
- 产品判断：做多少算够，哪些应该停
- 最终验收：源码包、版本号、文档、截图是否真的一致
- 发布把关：旧 zip、旧截图、残留文案、状态漂移
- 对外表述的诚实性
也就是说，这个项目不是“SOLO 一键做完”的，而是：
SOLO 负责大量实现和收口，LLM 负责辅助审阅与纠偏，而最终方向判断和验收边界仍然需要人来决定。
5.2 实际提效大概有多大？
这个我也想写得保守一点，不写那种明显不可信的数字。
如果由一个熟悉 React / TypeScript / 测试体系的人，纯手工把这个项目做到当前阶段——包括：
- 多组件原型
- 本地持久化
- JSON / Markdown 导入导出
- 批注 CRUD
- UIContext 重构
- 中英文切换
- 60+ 测试
- 文档与交付收口
我觉得保守估计，至少也要 2–4 周的集中开发与验证时间。
而在这个项目里：
- 如果只看代码实现和重构吞吐，SOLO 至少替我承担了 60%–80% 的机械实现工作量
- 如果把“写代码 + 验证 + 纠偏 + 发布收口”一起算，整体效率提升更接近 1.5×–2.5×
这个数字我觉得更诚实。
因为项目后半段其实花了不少时间在：
- 反复验包
- 修版本口径
- 修文档残留
- 修截图脚本
- 修展示层问题
这些工作并不会因为用了 SOLO 就自动消失。
5.3 这个项目最后说明了什么？
我觉得 GrapePaper 至少说明了一件事：
学术写作工具不一定必须长成“传统学术工具”的样子。
但当前版本还只能说明到这里。
它还不能证明：
- 这种自然隐喻一定比传统编辑器更有效
- 或者它已经是一个成熟产品
所以更准确的定位是：
GrapePaper 证明了这个方向值得做一个可运行原型，但还没有证明它已经是一套成熟可推广的产品方案。
这也是为什么我更愿意把当前版本叫做：
- 可运行的概念验证
- 交互原型
- Phase 1 半成品
而不是“完整学术编辑器”。
6. 最后
这个作品最开始只是一个有点任性的想法：
“如果论文编辑器不长得像论文，而像一个花园，会怎么样？”
做到现在，它至少已经从一句想法，变成了一个能跑、能测、能展示、也能诚实承认自己还是半成品的原型。
我觉得这就已经很值了。
如果后面还有精力，Phase 2 可能会继续做：
- 真实 AI 接入
- 更成熟的引用工作流
- PDF / Zotero
- 更细的视觉打磨
- 更完整的写作体验
但在当前这个阶段，我更愿意把它如实地放在这里：
一个由 SOLO Code 大量参与实现、经过多轮迭代后仍然保持半成品状态，但已经具备清晰方向和基本工程闭环的学术编辑器原型。
节选一段LLM监制老师对MTC回复和开发进度的评估，供相同需求的朋友们参考：
谢谢MTC
