@amaster.ai/pi-lark 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -56,12 +56,12 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "typebox": "1.3.7",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "typebox": "1.3.27",
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.23"
+    "@amaster.ai/pi-shared": "0.1.25"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-apps
 version: 1.0.0
-description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用协作者与协作权限设置、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用协作者/开发权限、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用协作者与协作权限设置、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda 应用（链接形如 `/app/app_xxx` 或 `/page/<token>`，运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用协作者/开发权限、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -35,7 +35,7 @@ lark-cli auth login --domain apps
 | HTML 应用 / 创意模式 — 写 HTML 页面/网站、静态页、PPT/deck、落地页、仪表盘、UI mockup、原型、线框图、视觉探索 | 加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） | [`creative-design/creative-design.md`](creative-design/creative-design.md) |
 | 旧版存量 HTML 应用（无 Git 管理）继续上传已有静态产物 | `+html-publish`（仅兼容旧链路；新建 html / 创意模式 / creative-design 产物不得使用） | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
 | 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)，含端到端流程和领域规则 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
-| 只要一份源码快照、不做本地开发；或要取**别人分享给你的**应用源码（你对其仓库无权限） | `+export`（下载 zip；不配 git 凭证、不建工作区）。要继续开发用 `+init` 而非本命令 | [`lark-apps-export.md`](references/lark-apps-export.md) |
+| 阅读 / 分析 / 总结一个妙搭应用的内容（任意应用模式，含创意模式应用的 `/page/<token>` 链接）；只要一份源码快照、不做本地开发；或要取**别人分享给你的**应用源码（你对其仓库无权限） | `+export`（下载 zip 后解压读源码；不配 git 凭证、不建工作区）。创意模式应用的 `/page/` 链接直接传 `--meta-token <token>`，不必先 `+get` 换 app_id。要继续开发用 `+init` 而非本命令 | [`lark-apps-export.md`](references/lark-apps-export.md) |
 | 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`, `+env-set`, `+env-delete` | [`lark-apps-env.md`](references/lark-apps-env.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`, `+log-get`, `+trace-list`, `+trace-get`, `+metric-list`, `+analytics-list` | [`lark-apps-observability.md`](references/lark-apps-observability.md) |
@@ -120,7 +120,7 @@ lark-cli apps +member-settings-set --app-id <app_id> --external-access disabled
 - 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（full_stack / frontend 应用）：进应用编辑/开发态、管理与继续开发应用的入口，也是 frontend 升级为 full_stack 的入口（云端会话）。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。
 - 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html / frontend / full_stack 统一走 `+release-get`）。
 - html 应用的主链路是创意模式开发方式：按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 初始化仓库、在仓库内产出 HTML 及关联文件，并通过 git commit / git push / `+release-create` / `+release-get` 发布部署。任何 git 操作（clone / pull / push）报错时，先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令。如果刷新凭证也失败，**停止并向用户报告**：原始 git 错误、凭证刷新失败原因，以及是否可能是当前环境（操作系统、沙箱）限制导致（如 macOS Keychain 在沙箱中不可用、Linux 加密文件目录不可写等）。不要改走 `+html-publish`，也不要把 `+html-publish` 当作本地开发链路的 fallback。
-- 创意模式（html）应用的链接格式为 `https://{租户域名}/page/{meta_token}`，**开发态和发布态是同一个链接**（区别于 full_stack 应用两者分开）。此链接形似飞书文档链接。`+get --app-id <meta_token>` 可获取应用信息（含 `app_id`），`+get --app-id <app_id>` 可获取 `meta_token`。看到 `/page/xxx` 链接时，它是妙搭创意模式应用，不要当成飞书文档跳过。
+- 创意模式（html）应用的链接格式为 `https://{租户域名}/page/{meta_token}`，**开发态和发布态是同一个链接**（区别于 full_stack 应用两者分开）。此链接形似飞书文档链接。`+get --app-id <meta_token>` 可获取应用信息（含 `app_id`），`+get --app-id <app_id>` 可获取 `meta_token`。看到 `/page/xxx` 链接时，它是妙搭创意模式应用，不要当成飞书文档跳过；用户要看懂 / 总结这个应用的内容时，直接 `+export --meta-token <token>` 导出源码阅读。
 
 ## 平台资源与应用源码边界
 
@@ -138,7 +138,7 @@ lark-cli apps +member-settings-set --app-id <app_id> --external-access disabled
 
 `app_id` 必须是妙搭应用 ID（`app_` 开头）。`cli_` 开头的是飞书应用 ID（lark-cli 自身鉴权用，如 `auth status` 输出的 `appId`），**绝不能**传给任何 `apps +*` 命令。
 
-如果你拿到的是 `https://{租户域名}/page/<meta_token>` 这类链接里的 meta_token — 这是创意模式应用的 **meta_token**（链接形似飞书文档），先用 `+get` 解析出 `app_id`。如果拿到的不是链接、也不是 `app_` 开头，可能是裸 meta_token，同样先用 `+get --app-id <token>` 尝试获取应用信息，能正常返回则说明是 meta_token：
+如果你拿到的是 `https://{租户域名}/page/<meta_token>` 这类链接里的 meta_token — 这是创意模式应用的 **meta_token**（链接形似飞书文档）。只为阅读 / 导出源码时不需要 `app_id`，直接 `+export --meta-token <meta_token>`；其余命令需要 `app_id` 时，先用 `+get` 解析出 `app_id`。如果拿到的不是链接、也不是 `app_` 开头，可能是裸 meta_token，同样先用 `+get --app-id <token>` 尝试获取应用信息，能正常返回则说明是 meta_token：
 
 ```bash
 lark-cli apps +get --app-id <meta_token> -q '.data.app.app_id'

package/skills/lark-apps/references/lark-apps-export.md

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-只要一份源码快照的场景：读代码、审计、归档、做静态分析、把源码喂给别的工具。
+只要一份源码快照的场景：读代码、审计、归档、做静态分析、把源码喂给别的工具。用户丢来一个妙搭应用链接要你「看看 / 分析 / 总结」时也用它：导出后解压读源码，页面文案和数据通常就在 HTML / 组件里。
 
 **跨应用是它相对 `+init` 的核心价值**：创意应用的分享链接（`/page/<token>`）指向别人的应用，你对那个仓库没有权限，`git clone` 走不通；`+export` 只要求你对该应用有下载权限。
 
@@ -56,7 +56,7 @@ lark-cli apps +export --app-id app_xxx --dry-run
 | 情况 | 怎么办 |
 |---|---|
 | 应用尚未发布（`code 40901 app not published`） | 该应用是产物托管形态（如静态 HTML 应用），导出的是「最新已发布产物」，而它还没有成功发布过版本，此刻没有可导的东西。**先发布应用再重试**——不是 app_id 写错，重试也没用 |
-| 权限不足（403） | 你需要该应用的下载权限。**持有分享 token 不等于有权限** |
+| 权限不足（HTTP 403，或 HTTP 200 + `code 40300`；两者都表现为 `permission_denied`） | 你需要该应用的下载权限。**持有分享 token、能打开页面都不等于有下载权限**。重试和换参数都没用，向用户说明需找应用所有者授权 |
 | 应用不存在（404） | 用 `+list --keyword <name>` 核对 app_id |
 | 归档过大（413） | 超出导出体积上限，改用 `+git-credential-init` + 原生 git clone |
 | 参数报错 | `--app-id` 与 `--meta-token` 只能给一个，且必须给一个；两者都要裸标识符（不是整条链接） |

package/skills/lark-base/SKILL.md

@@ -154,6 +154,7 @@ PY
 ```jsonc
 {
   "标题": "Created from shortcut", // text: string
+  "待确认": "请 <at user_id=ou_123/> 确认", // text(plain): 人员提及；实际 open_id 用 lark-contact 查询；不发送通知
   "官网": "[官网](https://example.com)", // text(url): 裸 URL 或 Markdown link
   "联系电话": "13800000000", // text(phone): 合法电话号码字符串
   "邮箱": "owner@example.com", // text(email): 合法邮箱字符串

package/skills/lark-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-doc
-description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
+description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；`/page/<token>` 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]

package/skills/lark-task/SKILL.md

@@ -24,6 +24,13 @@ metadata:
 
 shortcut 名称只能来自本 Skill 的 Shortcut 表或 `lark-cli task --help`；原生 resource/method 以逐级 help 为准，参数名、类型和嵌套结构以 method schema 为准。
 
+> **任务分组定位（必读）**：
+> - 在飞书任务/任务中心语境中，用户说“分组 / groups”时，优先对应 `sections`；任务清单对应 `tasklists`。先确定分组归属，再选择查询路径。
+> - 明确属于“我的任务”时，用 `sections.list` 的 `my_tasks` 归属和 `--as user` 查询，无需填写 `--resource-id`；明确属于某个清单时，用 `tasklist` 归属，并将该清单 GUID 传给 `--resource-id`。
+> - 归属不明时，先结合上下文判断，仍不明确再询问属于“我的任务”还是哪个清单；不要为了定位分组先遍历所有任务清单。
+> - 已知 `section_guid` 时，直接用 `sections.tasks` 查询组内任务；仅有分组名称时，先列取所属资源的分组并取得 `guid`。同名候选展示 GUID 和已知归属，不自动选择第一条。
+> - 分组操作的流程和 schema-first 示例见 [分组操作参考](references/lark-task-sections.md)。仅查询分组信息时，无需继续列取组内任务。
+
 > **任务搜索技巧**：先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**查询关键字**（例如任务名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了任务查询关键字，则目标是**任务**时优先使用 `+search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“今年以来”“已完成”“由我创建”“我关注的”），并且使用 `+search` 与 `+get-related-tasks` / `+get-my-tasks` 都能达到目的时，应优先使用列表型能力，而不是搜索型能力。其中，“与我相关 / 我关注的 / 由我创建”等优先考虑 `+get-related-tasks`；“我负责的 / 分配给我”的列表优先考虑 `+get-my-tasks`。不要把时间范围词（例如“今年以来”）本身误当成 `query` 去走搜索。
 > **任务搜索相关性提示**：`+search` 当前不会自动判断搜索结果与搜索发起人的相关性。如果用户明确要求搜索“与我相关”的任务，必须先识别具体关系，获取当前用户的 `open_id`，并显式传入对应的 `--assignee`（负责人）、`--creator`（创建人）或 `--follower`（关注人）过滤条件；不能只依赖 `query` 期待自动返回与当前用户相关的任务。
 > **任务清单搜索技巧**：任务清单也遵循同样的判断逻辑。先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**清单查询关键字**（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 `+tasklist-search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 `tasklists.list` 接口列取清单（先 `schema task.tasklists.list`，再 `lark-cli task tasklists list --as user ...`），再按 `creator`、`created_at` 等字段做本地筛选和分页控制。

package/skills/lark-task/references/lark-task-sections.md

@@ -0,0 +1,77 @@
+# task sections
+
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+
+## Scope and Operation Guide
+
+This reference organizes Task `sections` workflows by Catalog method. It currently covers locating sections and listing their tasks. See the [main Skill](../SKILL.md) for group terminology and ownership routing. The current CLI Catalog/schema is authoritative for parameters, permissions, and response fields.
+
+| User goal | Read |
+|----------|----------|
+| List sections in a resource or locate a section by name | [sections.list](#sectionslist) |
+| List tasks in a selected section | [sections.tasks](#sectionstasks) |
+
+## Shared Rules
+
+1. Follow the main Skill's discovery flow: run `lark-cli task --help` and `lark-cli task sections --help`, confirm the method, and read its schema before executing a native command.
+2. Use `--as user` when querying the current user's personal "My Tasks". For other operations, confirm identity and permissions through the shared rules and the method's help/schema.
+3. For queries that support pagination, use `--page-all --page-limit 0` when a complete listing is required. This avoids the default page limit. If the query is interrupted or partially fails, report that results are incomplete; do not conclude that a section or task does not exist.
+
+## sections.list
+
+List sections in "My Tasks" or a specific tasklist, or resolve a section name to its GUID.
+
+### Recommended Commands
+
+**List sections in "My Tasks"**
+
+```bash
+lark-cli schema task.sections.list
+lark-cli task sections list --resource-type my_tasks --as user --page-all --page-limit 0
+```
+
+**List sections in a specific tasklist**
+
+```bash
+lark-cli schema task.sections.list
+lark-cli task sections list --resource-type tasklist --resource-id "<tasklist_guid>" --as user --page-all --page-limit 0
+```
+
+### Parameters
+
+Read `lark-cli schema task.sections.list` for the full parameter structure. Choose the owning resource as follows:
+
+- "My Tasks": use `my_tasks`; no tasklist GUID or `resource_id` is needed.
+- A specific tasklist: use `tasklist` and pass its GUID through `--resource-id`.
+
+### Workflow
+
+1. Determine ownership from context; ask for the owning resource if it remains unclear. Use a known tasklist GUID directly. If only the tasklist name is available, follow the main Skill's tasklist lookup flow first. Do not use the section name as a tasklist search term.
+2. Execute the command for the owning resource.
+3. Match `name` in the returned `items`, and use the selected item's `guid` as `section_guid`. If names are duplicated, show candidate GUIDs and their known ownership so the user can select the target.
+4. Report the sections or pass the selected GUID to `sections.tasks` when the user requests their tasks. If a complete listing has no match, report that the section was not found in that resource; do not automatically scan other tasklists.
+
+## sections.tasks
+
+List tasks in a selected section.
+
+### Recommended Commands
+
+```bash
+lark-cli schema task.sections.tasks
+lark-cli task sections tasks --section-guid "<section_guid>" --as user --page-all --page-limit 0
+```
+
+### Parameters
+
+Read `lark-cli schema task.sections.tasks` for the full parameter structure. Pass the target section's GUID through `--section-guid`.
+
+### Workflow
+
+1. Use a known section GUID directly. If only the section name is available, locate it with [sections.list](#sectionslist) first. A known section GUID does not require another section or tasklist lookup.
+2. Execute the command to list the section's tasks.
+3. Present the returned tasks as requested. Report a complete result only after pagination finishes; otherwise, state that the results are incomplete.
+
+## Adding Operation Guidance
+
+For each added operation, create a `## sections.<method>` chapter using its Catalog method identifier and update the operation guide. Start with a short description, then use the Task reference convention: **Recommended Commands → Parameters → Workflow**. Keep shared rules at the start of this reference and operation-specific differences in the relevant chapter. Commands must show schema discovery before execution. Use Parameters for operation-specific choices and a schema pointer; leave complete parameter, permission, and response definitions to the schema.