飞书原生的 AI 海外运营总监,以 npx 包形式装进宿主 agent(v1 = OpenClaw)。 单品牌 / 单工作区一套安装,人触发即一个运营循环,任何对外动作都过硬审批门。

状态:v0.1,已在 OpenClaw 上跑通。 已上线:lumi init(Base + 文档 + 运营群 + 人格 + 频道)、互动闭环(拉评论 → triage → 回复门 → 线索)、内容脚手架(定位/品牌库/ 选题审核/素材库/对标账号库)、视频发布(上传 → 审批卡 → 批准发布)、LumiPath 自动化 任务审核(每日待审推送 + confirm/cancel/retry)、本地化任务追踪、首次品牌 onboarding。 已在真实 OpenClaw + 飞书 + LumiPath 环境验证。

这是什么

lumi 是一个确定性引擎 —— CLI 里没有 LLM。它只做:

• 调 LumiPath 公共 API(平台执行 + live 数据:发布、评论、insights、自动化、本地化)
• 读写飞书 Base / 文档(关系型状态库)
• 发飞书消息 / 审批卡片
• 审批队列(门)
• 循环脚手架

宿主 agent 才是大脑,经飞书触达。技能(SKILL.md)告诉 agent 何时调 lumi、哪里用判断。

三个平面

| 平面 | 负责 | |---|---| | 飞书 | 对话 + 审批(交互卡片)+ 状态(一个 Base〔8 表〕+ 品牌库/定位/周复盘文档) | | LumiPath API | 平台执行 + live 数据(发布、评论、insights、automation 策略、本地化) | | Agent(v1 = OpenClaw) | 大脑 —— 判断、策略、起草。经飞书触达。 |

安装

开源(MIT),发布在公共 npm。npx @lumipath/lumi-cli 直接用,或全局安装。

前置条件

• Node ≥ 22 + npm;python3(bundled 执行型技能的 handler 用)。
• 宿主 agent:OpenClaw(v1)。
• 一个飞书自建应用(见下「飞书应用接入」,扫码注册或手动)。
• 一个 LumiPath API key(lumi_…)—— LumiPath 是 Lumi 执行平台动作(发布、评论、数据洞察)的后端。 去 lumipath.cn 注册账号,在控制台生成 API Key,lumi init 时填入(只存本地 ~/.lumi/lumi.config.json)。 注册和这些基础功能(账号连接、发布、评论、数据洞察)都是免费的。
• 可选:TikHub key(对标/选题/收益)、ElevenLabs / Gemini key(视频技能;lumi init 会问,写进 ~/.codex/.env);视频技能另需 ffmpeg。

安装 CLI

# 直接用 npx(无需全局安装)
npx @lumipath/lumi-cli init

# 或全局安装
npm i -g @lumipath/lumi-cli
lumi --version

# 本地开发(本仓库):构建一次,link 全局 lumi
npm install && npm run build && npm link

装好后跑 lumi init 完成飞书应用接入、Base/文档/运营群创建,然后 lumi install --target openclaw 把技能装进宿主 agent。

飞书应用接入

两种方式;推荐扫码,省掉开发者后台的全部手工配置。

方式 A：扫码注册（推荐，免后台 / 免发版）

lumi init 第一步选「扫码自动创建 + 授权」(或单独跑 lumi feishu-register): 终端出二维码 → 飞书扫码 → 自动创建应用(已有应用用 lumi feishu-register --app-id cli_xxx 更新), 并预填好下面全部权限 + 事件 + 卡片回调,扫码即授权生效(无需手动勾选、无需「发布版本」); App ID / App Secret 自动写入 ~/.lumi/lumi.config.json。

• 代理机器(如 WSL):lumi 会自动绕过会挡住 feishu.cn 的代理;若你的环境必须经代理访问飞书,设 LUMI_KEEP_PROXY=1。

方式 B：手动自建应用（兜底）

在 飞书开放平台 建企业自建应用,按下面配置,然后**【创建并发布版本】才生效**。 lumi feishu-scopes --app-id cli_xxx 会打印一个预勾选全部 scope 的一键授权链接,点开添加即可。lumi init 选「手动」填 App ID / Secret。

两种方式都会用到的能力 / 权限 / 事件

能力:机器人 · 事件订阅(长连接) · 卡片回调(长连接)。

权限 scopes:

| Scope | 用途 | |---|---| | im:chat | 创建/管理运营群、加成员、转群主 | | im:message:send_as_bot | 以应用身份发消息 / 审批卡片 | | im:message:readonly | 读取/下载群里发来的视频·图片·文件素材(发视频、上传素材用) | | bitable:app | 创建并读写运营 Base(8 表)+ lumi state | | drive:drive | 自动创建文档文件夹、在其中建/写品牌库·定位·周复盘文档 | | contact:user.id:readonly | 用邮箱/手机号解析运营人 open_id,把他加进运营群 |

事件与回调(都走长连接):im.message.receive_v1(接收群消息)+ 卡片交互回调(审批卡按钮)。

凭证(App ID / Secret)只存在 ~/.lumi/lumi.config.json(gitignore,绝不进仓库)。扫码方式自动写入;手动方式 lumi init 时填。运营人加群在 lumi init 时填邮箱/手机号即可。

lumi init 做什么

lumi init

一条交互命令搞定:校验飞书/LumiPath 凭证 → 建 Base(8 表) + 文档文件夹 + 品牌库/周复盘 文档 + 运营群 → 写 ~/.lumi/lumi.config.json → (确认后)装进 OpenClaw:拷技能 + _shared、 注入海外运营总监人格、部署 kb/、写 channels.feishu、装 @openclaw/feishu 插件。 可重复跑、幂等(留空保留已填值)。

首次会触发 onboarding:一问一答收集品牌知识 → 写进 agent 上下文(BRAND.md,每 session 自动注入,所有技能都带着它)+ 回填飞书品牌知识库。

(可选)每日自动推送待审任务

openclaw cron add --cron "0 10 * * *" --tz Asia/Shanghai \
  --command "lumi tasks digest --send" --no-deliver --name "Lumi 待审任务每日推送"

装完在运营群对 Lumi 说话即可 —— lumi init 会生成一份飞书内的**「架构 & 触发手册」**文档, 列明各项能力怎么触发。

关键命令

agent 按技能自动经 bash 调用,你一般不用手敲。

| 命令 | 作用 | |---|---| | lumi init | 一键引导:凭证 + Base(8 表)+ 文档 + 运营群 +(OpenClaw)技能/人格/频道/插件。交互、幂等。 | | lumi install --target openclaw | (重新)部署技能 + _shared + kb + 人格 + 频道配置(init 也会做) | | lumi links | 打印本安装的真实飞书链接(Base + 各文档) | | lumi connect-accounts | 经 LumiPath 连接平台账号,回填 账号 表 | | lumi state get\|set <表> | 读写 Base 行(accounts/topics/contents/schedule/ledger/leads/benchmarks/materials) | | lumi doc positioning\|brand | 建/填 账号定位 / 品牌知识库 文档(brand --file 注入 BRAND.md 上下文) | | lumi sync comments\|insights | 从 LumiPath 拉 live 数据(只读) | | lumi upload-video、lumi publish-video | 托管视频 → 拼 social-posts body → 入审批队列 | | lumi card --id <id> --send | 把审批卡发到运营群 | | lumi publish\|reply --approved | 门的执行端 —— 只发已人工批准的项 | | lumi tasks list\|digest\|review\|confirm\|cancel\|retry | LumiPath 自动化任务审核(每日推送 + confirm 门) | | lumi localization list | 追踪 LumiPath 本地化(AI 翻译)任务 |

审批门

约定式强制:CLI 持有 LumiPath key,只有 --approved 子命令才会真正调对外动作。产生对外动作 (发布 / 回复 / 外联 / 确认自动化任务)的技能一律入队 + 停;人在飞书点审批卡;之后才由 lumi <publish|reply> --approved(或 lumi tasks confirm)真正发出。门在人手里,不点不发。

状态 & 幂等

运营事实(排期/审批/线索)的真相源是飞书 Base,每轮 live 读,不信压缩的聊天记忆。评论与 insights 不入库,每轮 live 读;评论去重靠每账号「处理游标」+ live 的「已回复」信号 + 线索池行。

目录

• src/ —— CLI(commands/ lumipath/ feishu/ approval/)
• skills/openclaw/ —— SKILL.md 技能集 + bundled 执行型技能(*.skill/ + _shared/)
• kb/ —— 知识库(平台最佳实践 + 框架)
• templates/ —— base-schema.json(Base 定义)+ agent/(人格)+ docs/(定位/品牌/周复盘)

产品文档

完整架构与 22 决策日志见 docs/DESIGN.md(仓库内)。