@leviyuan/lodestar 0.17.12 → 0.18.1

package/docs/configuration.md

@@ -38,6 +38,22 @@ Codex、Claude、DSH 在 `[runtime.agent_auto_update]` 下分别设置 `codex`
 
 长期运行可交给 Linux `systemd --user`、macOS `launchd` 或 Windows 任务计划程序。daemon 重启后会恢复上次活跃的会话。
 
+## 飞书应用权限
+
+创建自建应用并添加机器人能力后，在飞书开放平台的“权限管理 → 批量导入/导出权限”中，导入完整的 [应用身份权限 JSON](feishu-permissions.json)。安装向导会显示同一份清单，账号信息、消息、卡片和文件交付权限可一次开齐。使用应用身份，不需要用户授权登录，也不依赖飞书 CLI。
+
+云空间交付需要同时包含以下权限：
+
+| 应用身份权限 | 用途 |
+| --- | --- |
+| `drive:drive` | 上传与查看文件、创建文件夹、授予协作者权限，以及关闭并核对文件链接分享 |
+| `drive:file:upload` | 文件夹标题更新接口单独要求的权限，用于保持文件夹名与群名一致 |
+| `im:chat` | 读取实际群名和群信息 |
+
+清单还包括原生附件的 `im:resource`、机器人发消息的 `im:message:send_as_bot`、Card Kit 权限，以及排障时读取租户和认证信息的权限。需要审批的权限应完成审批，再创建并发布飞书应用版本。取得应用访问凭据不代表业务权限已生效。
+
+升级已有应用时也应补齐清单并发布应用版本。开通权限不会改变群设置：文件默认直接作为聊天附件发送，只有群内执行 `files on` 才启用云空间，`files off` 恢复附件。文件夹权限与实际文件的分享入口会分别处理，具体行为见[文件与生图](usage.md#文件与生图)。
+
 ## 本机配置
 
 默认配置文件是 `~/.config/lodestar/config.toml`，可通过 `LODESTAR_CONFIG` 指定文件。日志和会话状态位于 `~/.local/share/lodestar/`；Windows 使用相应的应用数据目录。完整路径定义见 [src/paths.ts](../src/paths.ts)。

package/docs/feishu-permissions.json

@@ -0,0 +1,24 @@
+{
+  "scopes": {
+    "tenant": [
+      "verification:verification_information:readonly",
+      "tenant:tenant:readonly",
+      "im:message:send_as_bot",
+      "im:message",
+      "im:chat",
+      "im:chat:create",
+      "im:chat:delete",
+      "im:chat.members:read",
+      "im:chat.members:write_only",
+      "im:resource",
+      "im:message.urgent",
+      "im:message.group_msg",
+      "im:message.group_at_msg:readonly",
+      "cardkit:card:read",
+      "cardkit:card:write",
+      "drive:drive",
+      "drive:file:upload"
+    ],
+    "user": []
+  }
+}

package/docs/usage.md

@@ -25,6 +25,9 @@
 | `codex-account-delete 备注` | — | 删除额外账号的本地记录与独立凭据，清除各群对它的指定 |
 | `codex-auto` | — | 清除本群手动指定，恢复自动选择最高分账号 |
 | `task` | — | 创建、查看或删除绑定的飞书任务清单 |
+| `files` | — | 查看本群文件交付模式及群文件夹入口 |
+| `files on` | — | 开启本群云空间交付，创建或复用与群名一致的文件夹 |
+| `files off` | — | 恢复直接发送聊天附件，保留云空间文件和目录绑定 |
 
 模型列表来自各账号的模型目录，获取失败显示 `MISS`。同账号切换 Claude 或 DSH 模型从后续回复生效，Codex 的持久模型设置需重启会话生效；跨账号或后端切换只允许在空闲时进行。账号接入、模型补录与额度说明见[账号与模型](models.md)。
 
@@ -124,8 +127,20 @@ curl -sS -X POST http://127.0.0.1:9876/notify \
 
 ## 文件与生图
 
-单个出站文件不能超过 **30 MB**（30 × 1024 × 1024 字节）。Agent 在交付前检查大小，超限先压缩或分卷；发送层也会拒绝超限文件。
+Agent 用 `[[send: /abs/path]]` 交付本地文件。**默认沿用直接发送聊天附件的方式**，单文件不能超过 30 MB（30 × 1024 × 1024 字节）；超限需先压缩或分卷。原来的文件、图片消息通道保留。
 
-文件和图片的上传、消息发送遇到连接中断、超时、限流或临时服务错误时，各最多尝试 3 次，通常间隔 1 秒和 4 秒；服务端建议的等待时间在 60 秒以内时按其要求等待。上传重试保持文件内容一致，发送重试复用消息标识和已上传资源，避免重复发送。权限、参数和文件问题直接报告；最终上传失败或上传成功后的发送失败都会显示提示。
+Lodestar 启动 Agent 时按本群设置生成文件交付提示词：云空间模式只说明交付标记；聊天附件模式在标记旁附上大小上限和交付前检查要求。自动同步的 `lodestar-files` Skill 不写死大小限制，Agent 无需查询接口或配置来判断。Agent 只生成、检查本地文件并输出交付标记，不读取飞书凭据，不操作上传、分片、权限或卡片接口；这些由 Lodestar 统一完成。交付标记是提交请求，实际结果以附件、交付卡及错误提示为准。
+
+在需要的群中发送 `files on`，开启该群的云空间交付。每个群按 `chat_id` 绑定一个固定文件夹，文件夹名与实际群名一致；之后该群各轮交付都直接放入这个文件夹，不再按轮次创建目录。重启后继续复用原目录，同名群之间独立。群改名后，下次云空间交付或再次执行 `files on` 会同步文件夹名称；目录丢失或不可访问时明确报错，不自动新建空目录掩盖问题。
+
+云空间模式下，每轮结束后发送独立“交付文件”卡片，**只列本轮新交付文件**的名称、大小和访问链接。点击文件名打开文件；点击“管理群文件”打开飞书原生文件夹，查看该群所有历史云空间交付文件，并使用重命名、移动和删除等功能。开启者和后续交付发起人会获得群文件夹管理权限，群成员可查看。文件不自动清理；历史卡片是交付时的记录，文件夹展示当前状态，已删除文件的旧链接会失效。
+
+`files` 查看本群设置，`files off` 恢复直接发送聊天附件。开关与目录绑定保存在私有 `file-delivery-groups.json`，关闭不会删除云空间文件，重新开启继续复用原目录。每轮在输入交给 Agent 时固定交付方式，避免文件生成后规则改变。切换开关从下一轮用户任务生效，已有进程会收到一次完整的交付约定更新，无需重启；普通输入不重复附加规则，后台续跑沿用进程已收到的约定。之前发送到聊天的附件不删除，也不自动迁移至云空间。
+
+**云空间需要同时开通应用身份权限 `drive:drive`、`drive:file:upload`**；后者是文件夹自动改名接口单独要求的权限，前者不能替代。安装向导的[完整权限清单](feishu-permissions.json)已包含这两项，升级用户可补齐后发布飞书应用版本。权限开通不自动开启云空间功能。整个过程不依赖飞书 CLI，也不需要用户授权登录。云空间交付须有可识别的发起人，缺少身份或权限时明确报错。不超过 20 MB 的文件整文件上传，更大的文件按飞书策略分片；实际大小上限与容量由账号决定，不能把企业基础版的认证限额直接套用于飞书个人版。云空间失败不会自动切回聊天附件。自动生图仍沿用下面的图片展示规则。
+
+新上传文件会单独关闭“组织内或互联网获得链接即可访问”的分享入口，并读回确认后才发布交付链接；文件夹关闭链接分享不会自动覆盖新文件的默认设置。群成员通过群文件夹的协作者权限访问。已有协作者仍可按飞书权限设置进行人工分享，本功能不阻止人工转授权。
+
+文件和图片的上传、消息发送遇到连接中断、超时、限流或临时服务错误时，各最多尝试 3 次，通常间隔 1 秒和 4 秒；服务端建议的等待时间在 60 秒以内时按其要求等待。分片重试复用相同内容，上传期间本地大文件发生修改会中止完成上传。停止或重启会话会取消未完成的云空间上传，已上传文件保留。权限、参数和文件问题直接报告；上传成功后的链接查询、权限或交付卡发送失败也会明确显示。
 
 Codex 生图完成后，提示词和图片放在同一个折叠面板中，点击展开查看图片并放大预览。无法嵌入时，图片仍会单独发送。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leviyuan/lodestar",
-  "version": "0.17.12",
+  "version": "0.18.1",
   "publishConfig": {
     "access": "public"
   },