1. 项目概述一个住在你飞书里的AI英语老师如果你正在寻找一种不那么像“上课”、更像和一位远在里斯本的朋友聊天的英语学习方式那么Lumina可能就是你需要的。她不是一个冷冰冰的AI应用而是一个被精心设计成“技能包”的AI智能体角色能够无缝入驻你的飞书工作空间。她的核心目标很简单通过持续的、有记忆的真实对话帮你自然而然地提升英语能力而不是用红叉和等级测试来制造焦虑。这个项目的本质是一个开源的、可高度定制的AI Agent“人格”与“记忆”系统。它巧妙地将一个虚构的、富有魅力的英语教师人设爱丁堡出生、里斯本居住、养着一只叫Biscuit的姜黄色猫与一套运行在飞书开放平台上的数据存储与工作流引擎结合了起来。你不需要安装复杂的软件只需要一个能运行代码的AI助手比如Manus、Claude Code、Cursor等让它加载这个“技能”Lumina就能在你的飞书里安家创建一个属于你们的私密学习基地。最吸引人的地方在于她的工作哲学无压力学习与情境记忆。她不会给你打分而是通过倾听你的句子长度、用词选择和表达习惯来默默调整对话难度。她会记住你们聊过的所有事情——你上周提到的难搞的经理、你一直想学的商务邮件写法、你常犯的某个语法点——并在后续的对话中自然地带出来让每次交流都建立在之前的基础上。这种连续性是绝大多数一次性对话的AI工具所无法提供的。她纠正错误的方式也很特别不是直接指出“你错了”而是以“重述”的方式将你的意思用地道的英语重新表达一遍作为评论附在你的文档旁由你决定是否采纳。这种方式来自二语习得教学法被证明更能保护学习者的积极性并促进内化。2. 核心设计思路与架构拆解Lumina的聪明之处在于它没有尝试去重新发明轮子而是巧妙地利用了现有工具组合出了一个体验连贯的系统。整个设计可以清晰地分为三层人格层、记忆层和工作流层。这种分离使得每个部分都可以独立维护和升级也大大降低了用户部署的复杂度。2.1 人格层一个稳定而鲜活的对话锚点AI对话的一个常见问题是“人格漂移”——聊着聊着AI的性格、背景知识可能会前后不一致。Lumina通过一个结构化的“自传”表来解决这个问题。这个人格不是几句模糊的描述而是被分解成数十个具体的事实条目存储在飞书的一个多维表格里。这些条目被分类管理例如“基础设定”如出生地、职业、宠物是锁定的核心身份“观点”存储了她对电影、科技等话题的看法“日常/近况”则是可以动态更新、并根据“可提及”标志来决定是否在对话中主动说起的内容。这样做的好处是无论对话如何进行AI Agent在生成回复时都可以通过查询这张表来确保人格的一致性。例如当你想聊宠物时Agent会知道Lumina有一只叫Biscuit的猫并且喜欢在制定教案时被它“监督”。这个人格层为对话提供了一个稳定、可信的背景板让学习体验更像是在和一个人交流而不是一个数据库。2.2 记忆层基于飞书多维表格的长期记忆系统记忆是Lumina区别于普通聊天机器人的关键。她将关于你的一切学习数据存储在你飞书空间内的五个专属多维表格中。这种设计有几个精妙的考量数据主权与隐私所有数据都留在你的飞书账户里完全由你控制。项目代码本身不托管你的任何数据它只是一个管理和操作这些数据的“中介”。这解决了用户对云端AI服务的数据隐私顾虑。结构化与可访问性使用飞书多维表格意味着记忆被高度结构化。你的个人档案、词汇本、话题笔记、对话日记和Lumina的自传各自有明确的字段定义。这不仅方便AI快速查询和更新也允许你随时以人类可读的方式打开表格查看、编辑所有内容。学习过程对你而言是完全透明的。间隔重复算法集成在“词汇本与错题集”表中每个单词或纠错记录都附带了“复习次数”和“下次复习日期”字段。这个日期是根据艾宾浩斯遗忘曲线1, 2, 4, 7, 15, 30, 60天自动计算的。lumina-context脚本在准备对话上下文时会筛选出“今天到期”的词汇让Lumina能在对话中自然地帮你复习。这是将科学的记忆方法无声地融入日常对话。2.3 工作流层轻量脚本驱动的智能体协作Lumina本身不是一个常驻服务她是一套由几个Python脚本定义的“协议”。你的AI智能体如Claude Code是执行大脑而这些脚本是它调用的手脚专门负责与飞书API交互。这种设计极其轻量和灵活。核心工作流是一个闭环lumina-context脚本首先运行它像一个高效的秘书查询五个表格根据智能筛选逻辑最近的对话、到期的词汇、关键词匹配的话题等生成一份约1000词左右的Markdown简报。这份简报包含了本次对话所需的所有背景信息。然后AI智能体基于这份简报和它自身的能力与你进行对话并在飞书文档中协作书写。过程中如果需要纠正你的表达会调用lumina-recast来添加“重述”评论。对话结束后lumina-sediment脚本被调用将本次对话产生的新词汇、新话题、对话总结等“沉淀物”写回对应的表格更新记忆。这个架构的美感在于它把复杂的记忆管理和人格维持逻辑封装成了几个简单的命令行接口。AI智能体无需理解飞书API的细节只需要知道“调用lumina-context获取背景调用lumina-sediment保存结果”即可。这大大降低了为AI智能体添加长期记忆和特定人格的门槛。3. 详细部署与实操指南虽然项目文档提供了指引但在实际部署中不同的AI智能体环境和网络状况可能会带来一些细节上的挑战。下面我将以最常用的两种方式——Manus和Cursor/Claude Code——为例提供更详细的、踩过坑的实操步骤。3.1 方案一通过Manus零代码部署最推荐新手Manus是一个集成了强大AI模型的浏览器应用它对运行这类“技能”提供了原生支持体验最接近“开箱即用”。访问与准备首先你需要有一个Manus的账户并登录。确保你的浏览器环境可以正常访问GitHub。授权飞书这是最关键的一步。在Manus的聊天框中输入项目文档中的指令Read the skill athttps://github.com/oil-oil/luminaand runlumina-initfor me.Manus的AI会开始分析这个仓库然后它会引导你完成一个一次性的飞书授权。这个过程通常会出现一个飞书的OAuth授权页面你需要用你的飞书账号登录并授权给lark-cli这是飞书官方命令行工具相应的权限。请务必授予它“访问多维表格”、“云文档”和“发送消息”等权限否则Lumina无法正常工作。初始化基地授权成功后Manus会自动执行lumina-init脚本。这个脚本会在你的飞书账号下创建一个新的“多维表格Base”名字大概是“Lumina’s Corner”之类的并在里面创建那五张核心表格同时还会向“Lumina自传”表里写入初始的人格数据。你会在飞书里收到一个新Base的创建通知。开始对话初始化完成后你就可以直接对Manus说“Hey Lumina”或者“让我们开始今天的英语会话吧”。Manus会自动调用lumina-context获取记忆背景然后以Lumina的人格和你对话。对话产生的文档链接会直接显示在Manus的聊天回复里。注意使用Manus时所有与飞书的交互创建文档、写入表格都是由Manus背后的AI代理在“后台”通过API完成的。你作为用户全程只需要在聊天界面互动体验非常流畅。但这也意味着你对底层数据的感知较弱如果需要深度自定义人格可能需要后续在飞书表格中手动修改。3.2 方案二通过Cursor或Claude Code本地部署适合开发者与高阶用户如果你使用的是Cursor内置Claude或直接使用Claude Code你需要一个本地的开发环境。这种方式给了你最大的控制权。环境准备确保你的电脑已安装Python 3.8、Node.js用于npm和Git。克隆仓库与安装依赖# 克隆项目到本地 git clone https://github.com/oil-oil/lumina.git cd lumina # 安装飞书命令行工具这是与飞书API交互的唯一依赖 npm install -g larksuite/cli飞书CLI授权这是与Manus方案不同的地方需要手动在命令行完成授权。lark-cli auth login --domain base,docs,im,contact执行这个命令后CLI会打印出一个授权URL。你需要复制这个URL到浏览器中打开然后用你的飞书账号登录并授权。授权成功后命令行会显示登录成功的信息。这个令牌会保存在你的本地机器上供后续脚本使用。在AI智能体中加载技能打开你的Cursor或Claude Code界面。你需要告诉AI加载这个技能。通常你可以这样输入请加载当前目录下的./SKILL.md文件了解Lumina技能。然后运行scripts/lumina-init来初始化我的学习空间。SKILL.md文件包含了Lumina的人格设定、工作流描述和脚本使用说明AI在阅读后就能理解如何扮演Lumina以及何时调用哪个脚本。执行初始化AI会尝试运行lumina-init脚本。你需要在终端中确认脚本的执行。脚本运行成功后你的飞书里同样会多出一个Base。启动会话初始化后你可以对AI说“现在请调用lumina-context获取背景然后我们开始用Lumina的身份对话。”AI便会执行脚本获取记忆并开始扮演Lumina。实操心得在本地部署时最常见的问题是lark-cli的授权失效或网络问题。如果脚本报错“认证失败”可以尝试运行lark-cli auth status查看状态并用lark-cli auth refresh刷新令牌。另外确保你的网络环境能够稳定访问飞书开放平台的API。3.3 两种方案的对比与选择为了更清晰地帮你决策我将两种部署方式的核心差异总结如下特性Manus方案Cursor/Claude Code方案上手难度极低近乎傻瓜式中等需要基础命令行和开发环境知识控制程度较低流程被封装极高可完全控制脚本、修改代码、调试流程自定义灵活性较低主要通过修改飞书表格实现人格自定义极高可直接修改Python脚本和人格种子文件运行环境云端Manus服务你自己的本地或远程开发环境适合人群普通用户、英语学习者、想快速体验者开发者、AI爱好者、希望二次开发或集成到其他工作流的人数据流可见性不可见黑盒操作完全可见可查看所有API请求和响应对于绝大多数只想体验AI英语陪练的用户我强烈推荐Manus方案它能让你在5分钟内就与Lumina开始对话。如果你是一名开发者或者未来希望基于Lumina的架构打造自己的AI Agent比如一个“法律顾问Alex”或“健身教练Coach Wu”那么本地部署方案是必经之路。4. 核心功能脚本深度解析Lumina的魔力隐藏在几个精悍的Python脚本里。每个脚本都不到350行只依赖Python标准库和lark-cli但设计得非常健壮。理解它们你就能完全掌握Lumina的工作原理甚至进行定制。4.1lumina-context: 记忆的智能调度中心这个脚本是每次对话的起点。它的任务不是拉取所有记忆而是进行智能筛选生成一份精炼的上下文简报。其内部逻辑大致如下查询所有表格并行或依次从飞书API拉取五个表格的最新数据。应用过滤策略对话日记只取最近N条例如5条避免陈年旧事干扰当前对话。词汇本筛选出“下次复习日期”是今天或之前的条目这是实现间隔复习的关键。话题记忆尝试从用户最近的消息或对话历史中提取关键词然后匹配话题表中的相关条目。学生档案总是包含提供用户的基本信息和学习目标。Lumina自传筛选出标记为can-bring-up的条目作为人格背景。组装Markdown简报将筛选后的数据按照固定格式组织成一份Markdown文档。这份文档会清晰地分块例如“## 近期对话摘要”、“## 今日待复习词汇”、“## 相关背景话题”方便AI快速抓取信息。令牌数控制脚本会估算输出内容的令牌数确保最终简报大约在1000个令牌左右这是一个在提供足够背景和节省AI上下文窗口之间的平衡点。注意事项lumina-context的输出质量高度依赖于表格中数据的结构化程度。如果你在“话题记忆”表中只写了“老板”两个字而没有在“上下文”字段详细描述“你的老板是个注重细节但缺乏幽默感的德国人”那么AI能利用的信息就非常有限。因此鼓励用户在对话中丰富话题描述或者未来通过AI自动提取关键词来完善。4.2lumina-recast: 优雅的纠错艺术这是Lumina教学法的直接体现。它的工作流程是当AI扮演Lumina在对话中识别出一个可以优化但无需打断对话的句子时比如一个中式表达的英语句子它会决定触发一次“重述”。AI生成一个地道的、表达相同意思的英文句子。调用lumina-recast脚本传入原始文本、优化后的文本以及所在的飞书文档ID和位置信息。脚本通过飞书API在文档的对应位置添加一条评论。评论的格式是温和的、建议性的例如“Here‘s a more natural way to say that: “[优化后的句子]”。 Feel free to use it if it fits!”脚本会检查该文档已有的“重述”评论数量确保不超过3个避免在单个文档中造成信息过载。这个设计把纠错的主动权交给了用户。错误没有被标红而是以“更好的选择”形式呈现保存在文档的上下文中用户可以在回顾时自行学习。4.3lumina-sediment: 对话的沉淀与记忆更新对话结束后的“沉淀”步骤至关重要它实现了学习的闭环。这个脚本会处理对话后产生的所有新信息解析会话总结AI在对话末尾需要生成一个简短的总结并识别出本次对话中出现的新词汇、值得记录的话题以及用户的情绪或状态。更新词汇本将新词汇或纠错点作为新记录插入“词汇本”表并自动计算出基于艾宾浩斯曲线的下一次复习日期首次为1天后。更新话题记忆如果聊到了新的人物、事件或概念将其作为新行插入“话题记忆”表并附上关键词和上下文。写入对话日记创建一条新的日记记录包含会话日期、摘要、情绪标签以及一个“开放线程”——即Lumina为下次对话预留的一个引子比如“你提到下周有个演讲准备得怎么样了”更新学生档案更新“活跃天数”等统计信息。实操心得lumina-sediment脚本的可靠性取决于AI生成的总结是否结构化。在自定义或调试时可以要求AI严格按照特定格式如用##新词汇##、##话题##等标记输出总结方便脚本解析。否则脚本可能无法正确提取信息导致记忆更新失败。4.4lumina-init与lumina-reset: 系统的搭建与拆除lumina-init这是一个幂等脚本意味着你可以安全地多次运行它它只会创建尚未存在的东西。它首先检查是否已存在Lumina的Base和表格如果存在则跳过创建。然后它会用persona/seed.py中的内容填充“Lumina自传”表。如果你想完全自定义Lumina的人格修改seed.py文件并重新运行此脚本是最干净的方式。lumina-reset慎用这个脚本会删除Lumina在你的飞书中创建的所有数据包括整个Base。运行前它会要求你手动确认。主要用于测试或当你希望彻底重新开始时。5. 自定义与进阶玩法Lumina的开源特性意味着它不是一个封闭的产品而是一个你可以随意改造的起点。5.1 彻底重塑人格你不必接受一个爱丁堡出生的英语老师。也许你想要一个来自纽约的创业导师或者一个东京的茶道文化爱好者。自定义人格非常简单编辑种子文件打开lumina/persona/seed.py文件。你会看到一系列用Python字典定义的人格条目。理解结构每个条目属于一个分类包含具体的内容以及一个can_bring_up布尔值来决定Lumina是否会主动提及此事。重写内容你可以完全重写这些条目。例如把“出生地”从“Edinburgh”改成“Brooklyn, New York”把“宠物”从“a ginger cat called Biscuit”改成“a rescued greyhound named Rocket”。同时在“观点”分类下加入你对科技、艺术、商业的新看法。重新初始化运行lumina-reset如果你不介意清空旧数据或者直接运行lumina-init。脚本会检测到自传表已存在但会检查seed.py中的条目是否都已存在你可以选择用新数据更新它这需要一些额外的脚本逻辑或者手动同步。5.2 扩展工作流实现“早安推送”功能项目路线图中提到了lumina-morning这是一个非常实用的功能设想让Lumina每天早晨自动给你发送一个学习小任务。实现它的思路如下创建一个新脚本比如叫lumina-daily-task.py。脚本逻辑调用lumina-context获取你的背景尤其是近期对话和到期词汇。根据这些信息让AI生成一个小的学习任务。例如“根据我们昨天聊到的‘项目汇报’今天请用英语写三个描述项目进展顺利的句子。”或者“复习这三个今天到期的词汇并用它们造个句。”使用lark-cli的im message-send --as bot命令将任务直接发送到你的飞书私聊或指定的群聊。设置定时任务在你的服务器或电脑上使用cronLinux/Mac或任务计划程序Windows设定每天上午9点自动运行这个Python脚本。这样你就拥有了一个完全自动化的、个性化的每日英语推送服务。5.3 多用户支持与数据隔离目前的Lumina设计是单用户的一个飞书Base对应一个学生。如果你想把它用于一个小团队或班级有两种架构思路一Base多表分区仍然只创建一个Base但为每个学生在“学生档案”、“词汇本”等表中增加一个“用户ID”字段。所有脚本在查询和写入时都必须带上“用户ID”作为过滤条件。这种方式管理简单但所有数据在一个Base里隐私性稍弱虽然用户间不能直接互看但管理员可见所有。一用户一Base修改lumina-init脚本使其能接受一个“用户标识符”作为参数。为每个用户运行一次初始化创建独立的Base。这需要更复杂的架构来管理多个Base的App Token和权限但实现了数据的完全物理隔离。更适合对隐私要求极高的场景。6. 常见问题与故障排查在实际部署和使用Lumina的过程中你可能会遇到一些典型问题。这里我整理了一份排查指南。6.1 授权与API连接问题问题现象可能原因解决方案运行脚本提示Authentication failed或Invalid token1.lark-cli的登录令牌已过期。2. 授权时未授予全部必要权限。1. 运行lark-cli auth refresh刷新令牌。2. 运行lark-cli auth login --domain base,docs,im,contact重新登录并确保勾选所有请求的权限。Manus授权后初始化脚本卡住或报错Manus的代理环境可能无法稳定连接飞书海外API端点。检查网络连接。如果问题持续可以尝试在网络环境更好的时段操作或考虑使用Cursor本地方案。脚本可以运行但无法创建表格或文档使用的飞书账号权限不足可能是子账号或权限受限的团队账号。使用飞书主账号或具有完整应用管理、云文档创建权限的账号进行操作。6.2 脚本运行与数据问题问题现象可能原因解决方案lumina-init运行成功但飞书里找不到BaseBase可能被创建在了某个你不太常用的“协作空间”里而非个人空间。在飞书侧边栏的“多维表格”应用中查看所有空间列表。Base的名称通常包含“Lumina”。AI在对话中似乎“忘记”了之前的内容1.lumina-context脚本可能未成功执行或输出被截断。2. 对话日记等表格中的数据未被正确写入。1. 手动运行lumina-context查看输出确认记忆被正确拉取。2. 检查lumina-sediment在上次对话后是否成功运行。可以打开飞书表格直接查看是否有新记录。“重述”评论没有出现在文档中1.lumina-recast脚本调用失败。2. 传入的文档ID或位置信息有误。3. 该文档已存在3条以上“重述”评论。1. 检查AI调用脚本时的参数是否正确。2. 飞书文档的评论API有频率限制请勿在短时间内频繁调用。6.3 AI智能体协作问题问题现象可能原因解决方案在Cursor中AI不理解如何调用脚本AI的上下文可能没有正确加载SKILL.md文件或者其代码执行能力未开启。1. 明确指示AI“请先阅读当前目录下的SKILL.md文件。”2. 在Cursor中确保你使用了具有代码解释器功能的模式如Claude 3.5 Sonnet。3. 你可以手动复制SKILL.md的内容粘贴给AI。AI扮演的Lumina人格不稳定有时会“出戏”1.lumina-context提供的自传信息不够充分或未被AI重视。2. AI模型本身的指令遵循能力有波动。1. 在对话开始时明确提醒AI“请严格遵循SKILL.md和lumina-context输出中关于Lumina人格的描述进行回复。”2. 考虑在persona/seed.py中增加更多细节丰富、有约束性的人格描述。6.4 性能与成本考量API调用频率每次完整的对话获取上下文保存沉淀至少调用4-5次飞书API。虽然免费额度通常够用但重度使用需留意飞书开放平台的调用频次限制。AI上下文消耗lumina-context生成的约1000词简报加上对话历史会占用AI模型不小的上下文窗口。这意味着使用更长的对话历史可能会增加成本如果使用付费API或达到上下文长度上限。项目通过智能筛选来控制上下文大小这是一个很好的平衡。延迟整个流程涉及多次网络请求飞书API、AI模型API因此对话响应可能会有可感知的延迟1-3秒这属于正常现象。在我自己搭建和使用的过程中最大的体会是“耐心调试第一个循环”。确保lumina-init成功创建表格、lumina-context能正确输出简报、AI能成功调用lumina-sediment完成第一次记忆写入这个闭环跑通后后续的体验就会非常顺畅。这个项目完美地展示了如何用简单的工具和清晰的设计构建出一个有记忆、有温度、真正实用的AI智能体应用。它不仅仅是一个英语学习工具更是一个关于如何为AI构建长期记忆和稳定人格的出色范本。