@amaster.ai/pi-lark 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "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",
+    "@earendil-works/pi-coding-agent": "1.0.4",
     "typebox": "1.3.7",
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.23"
+    "@amaster.ai/pi-shared": "0.1.24"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

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.