概览

Chrome MV3 扩展：在飞书 多维表格 / 电子表格 / 文档 页用自然语言操作，并把数据做成 看板 / 网站 / PPT，还能做文档质检。无后端也能用，全部以用户本人飞书身份操作。

能力一览

使用

安装与上手

下面的命令是自行构建才需要（想把 App ID 打进包、二次开发或私有化）：

1) git clone && npm i
2) npm run build            # 产物在 dist/
3) chrome://extensions → 打开「开发者模式」→「加载已解压的扩展程序」→ 选 dist/
4) 打开任意飞书多维表格/电子表格/文档页，点扩展图标开侧边栏
5) 设置 → 填 OpenAI 兼容大模型（Base URL/Key/Model）+ 用飞书账号一键授权

能做什么（侧边栏对话即可）

• 操作数据：「把 A 列按月汇总」「筛掉重复行」「给这几行建任务」——批量改一次性提交、删除走确认门、可一键撤销。
• 看板/小程序：「按分类做个销售额柱状图」→ 浮窗渲染，可导出 PDF / 生成飞书文档 / 推送到群。
• AI 建站：把当前表做成一个自包含网站。
• AI 幻灯片：文档/数据一键转可翻页 PPT。
• 文档质检：通读整篇，挑出逻辑断点、未定义术语、前后矛盾、遗留 TODO、空小节等。
• 网页剪藏：把当前网页内容剪藏进多维表格。

🧰 一键打包向导（图形化 · 给小白）

不想碰命令行 / .env？跑一条命令打开网页向导，选模式 → 改名称 / 换图标 → 填参数 → 一键打包下载，全程不用敲配置：

npm run package:ui   # 打开 http://localhost:8799（仅本机）

• 4 种模式：企业·代理（推荐）/ 个人·直连 / 商店·BYO / 私有化·内网——选哪个就只显示哪些字段，不会填错。
• 品牌定制：改扩展名称、描述；上传一张方形 PNG，自动缩成 16/32/48/128 写进 manifest（不动源文件）。
• 连接 / 能力：代理地址、App ID / 大模型是否从代理下发、统一策略、共享技能库、企业云备份，勾选即配。
• 高级：大模型域名白名单、外发脱敏、无远程代码、单次外发上限、OAuth scope、IP CIDR、剥 manifest key。
• 安全：表单只落到本机 .env.package.local（已 gitignore）；打包前临时挪开你的 .env.local 保证产物“只含这次填的”；构建结束自动还原。商店模式强制不内置任何凭据并剥 key。

打完点「下载」拿到 .zip 解压，chrome://extensions → 开发者模式 →「加载已解压」即可；也可直接加载项目里的 dist/。底层就是驱动 npm run build -- --mode <模式> + 后处理 manifest/图标，和手动构建产物一致。

部署 · 个人 / 直连

三种鉴权模式，按安全性从高到低：

# B. 生成加密 secret（按提示输入 secret + 口令）
node scripts/encrypt-secret.mjs
# 填 .env.local：VITE_FEISHU_APP_ID=cli_xxx  VITE_FEISHU_APP_SECRET_ENC=<密文>  VITE_FEISHU_APP_SECRET=（留空）
npm run build

部署 · 企业服务端套件

一个零依赖 Node 进程（node ≥ 18）就是整套服务端：docs/oauth-proxy-server.mjs 在同一端口、同一进程里挂载换 token、技能库、云备份、管理台。前面套一层 nginx 即可。

① 起代理

FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx \
ALLOW_ORIGIN=chrome-extension://<你的扩展ID> \
ALLOWED_REDIRECT_URIS=https://<扩展ID>.chromiumapp.org/ \
FEISHU_TENANT_KEY=<你企业的 tenant_key> \
node docs/oauth-proxy-server.mjs        # 默认 :8787

子服务按需打开（同进程挂载，无需另起）：

# 企业统一 LLM（员工免填 key）
LLM_BASE_URL=https://api.deepseek.com LLM_API_KEY=sk-xxx LLM_MODEL=deepseek-chat \
# 共享技能库（建议配真 embedding）
EMBED_URL=https://api.openai.com/v1/embeddings EMBED_KEY=sk-xxx EMBED_MODEL=text-embedding-3-small \
SKILLS_FILE=/var/lib/feishu/skills.json \
# 企业云备份（对象存储 S3 兼容；或本地盘 ARTIFACTS_DIR）
S3_ENDPOINT=https://s3.ap-southeast-1.amazonaws.com S3_REGION=ap-southeast-1 \
S3_BUCKET=my-feishu-artifacts S3_ACCESS_KEY=AKIA... S3_SECRET_KEY=... \
ARTIFACT_ENC_KEY=<32字节hex> \
# 运维管理台（设了密码才挂载 /admin）
ADMIN_PASSWORD=<高熵密码> ADMIN_TOKEN_SECRET=<32字节随机> \
node docs/oauth-proxy-server.mjs

② 构建企业包

# .env.enterprise.local（只填代理地址 + 想开的特性开关）
VITE_OAUTH_PROXY_URL=https://your-proxy.example.com/feishu/oauth
VITE_OAUTH_PROXY_KEY=<可选·与代理 PROXY_SHARED_KEY 一致>
VITE_APP_ID_FROM_PROXY=1     # App ID 从代理下发
VITE_LLM_FROM_PROXY=1        # LLM 从代理下发
VITE_ENTERPRISE_POLICY=1     # 统一策略
VITE_SKILLS_ENABLED=1        # 共享技能库
VITE_ARTIFACT_SYNC=1         # 企业云备份
# 三个 secret 变量全部留空！

npm run build -- --mode enterprise
# 自检：包里有代理 URL、【无】secret

③ nginx（推荐内网 + 身份网关）

location /feishu/oauth { proxy_pass http://127.0.0.1:8787/; proxy_set_header X-Forwarded-For $remote_addr; }
# 管理台建议仅内网/VPN 可达 + IP_ALLOWLIST，或单独 location 前置 SSO

部署 · 商店 / BYO 包

对外上架版：用户自带飞书应用（填 App ID + Secret），不内置任何凭据，剥掉 manifest key。

npm run build -- --mode store     # VITE_WEBSTORE=1：剥 key + 商店名/描述；不内置 secret
# 校验：dist 里无 appid、无 secret、无任何企业端点串（技能/备份/app_config 全 0）

部署 · 私有化 / 内网（Lark / 飞书私有化）

私有化只差一个域名后缀，所有 host 从它派生：

VITE_FEISHU_BASE_DOMAIN=your-private-domain.com   # open.<域> / accounts.<域> / <租户>.<域> 自动派生
# 代理侧：FEISHU_API_BASE=https://open.<域>/open-apis

详见 docs/PRIVATE_DEPLOYMENT.md。feishuFetch 会在私有化端点 404 时自动 /vN/→v(N-1) 回退。

环境变量速查

客户端（构建期 VITE_*，写在 .env.<mode>.local）

服务端（运行期，进程环境变量）

架构

① 你说一句话，数据怎么流（个人版·无后端）

② 企业服务端套件 —— 一个 Node 进程

关键约束（代码里硬编码的边界）

• 只用用户身份：auth.ts resolveToken 绝不回退 tenant。
• 文件级删除一律拒绝；内容删除走确认门（DESTRUCTIVE_TOOLS）。
• 通用 API 白名单：禁 im/通讯录/权限/所有权。
• 出站只走 feishuReq/feishuFetch；大模型走 assertSafeBaseUrl。
• 沙箱隔离：生成代码在 opaque origin + connect-src:'none'。
• secret 不进明文包；写操作不自动重试。
• 企业特性双门控：HAS_* = flag && 有代理 → 商店版死代码消除。

深结构见 docs/ARCHITECTURE.md。

安全模型

换 token 的安全流程（代理模式：secret 永不进扩展包）

出去了什么 · 信任边界

客户端

• 身份闸门：AI 始终以用户本人飞书身份操作，绝不回退应用/租户身份越权。
• 破坏性操作：文件级删除硬阻断；内容删除/通用写入走确认门（可一键撤销）。
• 出站守卫：飞书只走 feishuReq/feishuFetch；大模型 Base URL 经 assertSafeBaseUrl + 可选 host 白名单。
• 沙箱：LLM 生成的渲染代码在 opaque origin、connect-src:'none'、无 allow-same-origin。
• 商店版隔离：无代理 → 企业特性全部死代码消除，不外发任何东西。

服务端

• secret 不下发：App Secret / LLM Key / 对象存储密钥只在服务端；token 透传不解析不落盘不打印。
• 租户锁 fail-closed：FEISHU_TENANT_KEY 未设则拒绝下发一切；回调白名单未设则拒绝换 code。
• App ID 经 app_config 无 token 下发：App ID 本就是公开值（OAuth URL 里可见），格式校验后缓存，secret 仍只在服务端。
• 技能库只收脱敏数据：仅 LLM 蒸馏的一句话经验 + 工具名 + 匿名安装 id；客户端无条件 PII 脱敏，且 match 查询用去标识经验、绝不发原始任务文本。
• 云备份按 open_id 隔离：存储路径由服务端校验出的 open_id 生成、客户端不可指定；可选静态 AES。

管理台

• 设了 ADMIN_PASSWORD 才挂载；登录换 HMAC 签名会话（密钥与登录密码解耦，重启即吊销）。
• 纳入 IP 白名单（在所有子服务分发之前把关）；建议仅内网/VPN 可达。
• 防点击劫持（X-Frame-Options: DENY + CSP frame-ancestors none）；同源校验；登录限流。

运维 · 管理台

设 ADMIN_PASSWORD 启动代理后，浏览器开 https://<你的代理>/admin 登录，统一管理技能库 / 云备份 / 配置 / 审计。

登录与防护（怎么进、怎么守）

实际界面

验证 · 测试

每次改完都跑（迭代循环）：

npm run typecheck        # 必须 0 错
npm test                 # 单元测试全绿（~460 用例）
npm run build            # 必须成功
npm run test:ui          # 动了侧边栏 UI 再跑（11 项冒烟）

服务端 + 客户端能力用合成数据一键复验（无需真飞书 / 真对象存储）：

npm run validate:server  # 起假飞书 + spawn 真代理，跑 29 条端到端断言
                         #（技能去重/打分/晋级/匹配/套路、备份往返/隔离/AES、各 grant、管理台审核/审计）
# 看板/PPT/质检 的纯逻辑由 src/shared/features-validate.test.ts 用合成销售数据校验（含手算期望）

FAQ

本页为离线单文件文档（零依赖）。源与更多细节：README.md · docs/ARCHITECTURE.md · docs/SECURITY_AUDIT.md · docs/DEPLOYMENT.md。