@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-minutes/references/lark-minutes-search.md

@@ -0,0 +1,180 @@
+# minutes +search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
+
+本 skill 对应 shortcut：`lark-cli minutes +search`（调用 `POST /open-apis/minutes/v1/minutes/search`）。
+
+## 典型触发表达
+
+以下说法通常应优先使用 `minutes +search`：
+
+- 我的妙记
+- 我拥有的妙记
+- 我参与的妙记
+- 最近的妙记
+- 某个关键词的妙记
+- 某段时间内的妙记
+
+## 命令
+
+```bash
+# 关键词搜索
+lark-cli minutes +search --query "预算复盘"
+
+# 查询某一天内的妙记（单日查询时，建议将 start 和 end 都填写为同一天）
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-10
+
+# 按时间范围搜索
+lark-cli minutes +search --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-17
+
+# 关键词 + 时间范围
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --end "2026-03-17T00:00+08:00"
+
+# 按参与者过滤（open_id，逗号分隔）
+lark-cli minutes +search --participant-ids "ou_x,ou_y"
+
+# 按所有者过滤（open_id，逗号分隔）
+lark-cli minutes +search --owner-ids "ou_owner,ou_owner_2"
+
+# 查询我参与的妙记
+lark-cli minutes +search --participant-ids "me"
+
+# 查询我拥有的妙记
+lark-cli minutes +search --owner-ids "me"
+
+# 多条件组合查询
+lark-cli minutes +search --owner-ids "ou_owner" --participant-ids "ou_x" --start "2026-03-10T00:00+08:00"
+
+# 分页查询
+lark-cli minutes +search --query "预算复盘" --page-size 20
+lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
+
+# 输出为结构化 JSON
+lark-cli minutes +search --query "预算复盘" --format json
+```
+
+## 参数
+
+| 参数                        | 必填 | 说明                                   |
+| ------------------------- | -- | ------------------------------------ |
+| `--query <text>`          | 否  | 搜索关键词                                |
+| `--owner-ids <ids>`       | 否  | 所有者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--participant-ids <ids>` | 否  | 参与者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--start <time>`          | 否  | 开始时间（ISO 8601 或仅日期）                  |
+| `--end <time>`            | 否  | 结束时间（ISO 8601 或仅日期）                  |
+| `--page-size <n>`         | 否  | 每页数量，默认 `15`，最大 `30`                 |
+| `--page-token <token>`    | 否  | 下一页分页 token                          |
+| `--dry-run`               | 否  | 预览 API 调用，不执行                        |
+
+## 核心约束
+
+### 1. 至少提供一个过滤条件
+
+所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--owner-ids`、`--participant-ids`、`--start` 或 `--end`。
+
+### 2. 仅支持 user 身份
+
+该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `minutes:minutes.search:read` 权限。
+
+### 3. `me` 表示当前用户
+
+在 `--owner-ids` 和 `--participant-ids` 中可使用 `me`，表示当前登录用户。该值会在本地解析为当前用户的 `open_id`，无需手动先查询自己的用户 ID。
+若当前环境尚未完成用户登录，或 CLI 无法解析出当前用户的 `open_id`，则应先执行 `lark-cli auth login`，再重新执行搜索。
+
+### 4. 支持分页
+
+当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
+
+### 5. 日期型 `--end` 包含当天整天
+
+当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
+CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时间戳发给 API；在 dry-run 或排查请求体时，看到的 `Z` 结尾时间表示同一个绝对时间点的 UTC 表示，不改变“按当天整天查询”的语义。
+
+这意味着：
+
+- `--start 2026-03-10 --end 2026-03-10` 表示只查 `2026-03-10` 当天
+- `--start 2026-03-10 --end 2026-03-11` 表示查询 `2026-03-10` 和 `2026-03-11` 两天
+
+如果用户说“昨天的妙记”“今天的妙记”“某一天内的妙记”，应把 `--start` 和 `--end` 都设置为同一天，而不是把 `--end` 设成下一天。
+
+### 6. 会议的妙记先定位会议
+
+如果用户明确要找某场会议的妙记，或同时提到“会议 / 开会 / 会”和“妙记”，应优先使用 `vc +search` 先定位会议，再按需通过 `vc +recording` 获取 `minute_token`，不要直接按妙记时间范围或关键词搜索。
+只有在无法通过会议搜索定位目标会议，或用户明确要求按妙记维度检索时，才回退到 `minutes +search`。
+
+<br />
+
+## 时间格式
+
+`--start` 和 `--end` 支持以下时间格式：
+
+| 格式             | 示例                          | 说明                                 |
+| -------------- | --------------------------- | ---------------------------------- |
+| ISO 8601（带时区）  | `2026-03-10T14:00:00+08:00` | 推荐                                 |
+| ISO 8601（不带时区） | `2026-03-10T14:00:00`       | 按本地时区解析                            |
+| 仅日期            | `2026-03-10`                | 按天粒度解析；若用于 `--end`，表示当天 `23:59:59` |
+
+## 输出结果
+
+- 默认输出包含 `items`、`total`、`has_more` 和 `page_token`。
+
+## Pagination (`has_more` / `page_token`)
+
+- 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
+- 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
+- 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
+- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+
+```bash
+# First page
+lark-cli minutes +search --query "预算复盘" --page-size 20
+
+# Next page
+lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
+```
+
+## 搜索结果中的下一步
+
+搜索结果中的 `token` 可直接作为 `minute_token` 用于继续查询妙记产物：
+通常先用搜索结果中的 `token` 获取妙记基础信息，确认描述、链接等元数据是否命中目标；需要进一步查看内容时，再继续查询关联的纪要产物。
+
+如果你已经确定目标妙记，优先直接复用搜索结果中的 `token`，避免重复搜索。
+
+```bash
+# 首先查询妙记元信息（标题、时长、封面） → 用本 skill
+lark-cli minutes minutes get --params '{"minute_token": "obcn***************"}'
+
+# 查妙记关联的纪要产物：逐字稿、总结、待办、章节等 → 用 lark-cli vc +notes
+lark-cli vc +notes --minute-tokens obcnhijv43vq6bcsl5xasfb2
+```
+
+## 常见错误与排查
+
+| 错误现象                   | 根本原因                                                  | 解决方案                                         |
+| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| 命令直接报错，要求提供过滤条件        | 没有传入 `--query`、时间范围或任何过滤 ID                           | 至少补充一个过滤条件后重试                                |
+| 时间参数校验失败               | `--start` 或 `--end` 格式不合法                             | 改用 ISO 8601 或 `YYYY-MM-DD`                   |
+| `owner-ids` 校验失败       | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| `participant-ids` 校验失败 | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| 权限不足                   | 未授权 `minutes:minutes.search:read`                     | 使用 `auth login` 完成授权                         |
+
+## 提示
+
+- 当用户说“我的妙记”时，优先理解为 `--owner-ids me`。
+- 当用户说“我参与的妙记”时，优先理解为 `--participant-ids me`。
+- 当用户同时提到“会议 / 会 / 开会 / 某场会”和“妙记”时，优先先定位会议；只有无法定位目标会议时，再回退到妙记搜索。
+- 必须使用 `--format json` 输出，你更加擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关命令
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令

package/server/assets/skills/lark-tools/cli-skills/lark-openapi-explorer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: lark-openapi-explorer
+version: 1.0.0
+description: "飞书/Lark 原生 OpenAPI 探索：从官方文档库中挖掘未经 CLI 封装的原生 OpenAPI 接口。当用户的需求无法被现有 lark-* skill 或 lark-cli 已注册命令满足，需要查找并调用原生飞书 OpenAPI 时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+
+# OpenAPI Explorer
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解认证、身份切换和安全规则。
+
+当用户的需求**无法被现有 skill 或 CLI 已注册 API 覆盖**时，使用本技能从飞书官方 markdown 文档库中逐层挖掘原生 OpenAPI 接口，然后通过 `lark-cli api` 裸调完成任务。
+
+## 文档库结构
+
+飞书 OpenAPI 文档以 markdown 层级组织：
+
+```
+llms.txt                          ← 顶层索引，列出所有模块文档链接
+  └─ llms-<module>.txt            ← 模块文档，包含功能概述 + 底层 API 文档链接
+       └─ <api-doc>.md            ← 单个 API 的完整说明（方法/路径/参数/响应/错误码）
+```
+
+文档入口：
+
+| 品牌 | 入口 URL |
+|------|----------|
+| 飞书 (Feishu) | `https://open.feishu.cn/llms.txt` |
+| Lark | `https://open.larksuite.com/llms.txt` |
+
+> 所有文档以**中文**编写。如果用户使用英文交流，需将文档内容翻译为英文后输出。
+
+## 挖掘流程
+
+严格按以下步骤逐层检索，**不要跳步或猜测 API**：
+
+### Step 1：确认现有能力不足
+
+```bash
+# 先检查是否已有对应的 skill 或已注册 API
+lark-cli <可能的service> --help
+```
+
+如果已有对应命令或 shortcut，直接使用，**不需要继续挖掘**。
+
+### Step 2：从顶层索引定位模块
+
+用 WebFetch 获取顶层索引，找到与需求相关的模块文档链接：
+
+```
+WebFetch https://open.feishu.cn/llms.txt
+  → 提取问题："列出所有模块文档链接，找出与 <用户需求关键词> 相关的链接"
+```
+
+- 飞书品牌使用 `open.feishu.cn`
+- Lark 品牌使用 `open.larksuite.com`
+- 如不确定用户品牌，默认使用飞书
+
+### Step 3：从模块文档定位具体 API
+
+用 WebFetch 获取模块文档，找到具体 API 的文档链接：
+
+```
+WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-<module>.txt
+  → 提取问题："找出与 <用户需求> 相关的 API 说明和文档链接"
+```
+
+### Step 4：获取 API 完整规范
+
+用 WebFetch 获取具体 API 文档，提取完整的调用规范：
+
+```
+WebFetch https://open.feishu.cn/document/server-docs/.../<api>.md
+  → 提取问题："返回完整 API 规范：HTTP 方法、URL 路径、路径参数、查询参数、请求体字段（名称/类型/必填/说明）、响应字段、所需权限、错误码"
+```
+
+### Step 5：通过 CLI 调用 API
+
+使用 `lark-cli api` 裸调：
+
+```bash
+# GET 请求
+lark-cli api GET /open-apis/<path> --params '{"key":"value"}'
+
+# POST 请求
+lark-cli api POST /open-apis/<path> --data '{"key":"value"}'
+
+# PUT 请求
+lark-cli api PUT /open-apis/<path> --data '{"key":"value"}'
+
+# DELETE 请求
+lark-cli api DELETE /open-apis/<path>
+```
+
+## 输出规范
+
+向用户呈现挖掘结果时，按以下格式组织：
+
+1. **API 名称与功能**：一句话描述
+2. **HTTP 方法与路径**：`METHOD /open-apis/...`
+3. **关键参数**：列出必填和常用可选参数
+4. **所需权限**：scope 列表
+5. **调用示例**：给出 `lark-cli api` 的完整命令
+6. **注意事项**：频率限制、特殊约束等
+
+如果用户使用英文交流，将以上所有内容翻译为英文。
+
+## 安全规则
+
+- **写入/删除类 API**（POST/PUT/DELETE）调用前必须确认用户意图
+- 建议先用 `--dry-run` 预览请求（如支持）
+- 不要猜测 API 路径或参数——必须从文档中获取确认
+- 涉及敏感操作（删除群、移除成员等）时，向用户说明影响范围
+
+## 使用场景示例
+
+### 场景 1：用户需要拉人进群（未被 CLI 封装）
+
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 发现没有 chat_members 相关的 create 命令
+
+# Step 2-4: 通过文档挖掘获得 API 规范
+# → POST /open-apis/im/v1/chats/:chat_id/members
+
+# Step 5: 调用
+lark-cli api POST /open-apis/im/v1/chats/oc_xxx/members \
+  --data '{"id_list":["ou_xxx","ou_yyy"]}' \
+  --params '{"member_id_type":"open_id"}'
+```
+
+### 场景 2：用户需要设置群公告
+
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 没有 announcement 相关命令
+
+# Step 2-4: 挖掘文档
+# → PATCH /open-apis/im/v1/chats/:chat_id/announcement
+
+# Step 5: 调用
+lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement \
+  --data '{"revision":"0","requests":["<html>公告内容</html>"]}'
+```
+
+## 参考
+
+- [lark-shared](../lark-shared/SKILL.md) — 认证和全局参数
+- [lark-skill-maker](../lark-skill-maker/SKILL.md) — 如需将挖掘到的 API 固化为新 Skill

package/server/assets/skills/lark-tools/cli-skills/lark-shared/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: lark-shared
+version: 1.0.0
+description:
+  '飞书/Lark CLI 共享基础：应用配置初始化、认证登录（auth login）、身份切换（--as user/bot）、权限与
+  scope 管理、Permission denied 错误处理、安全规则。当用户需要第一次配置(`lark-cli config
+  init`)、使用登录授权(`lark-cli auth login`)、遇到权限不足、切换 user/bot 身份、配置
+  scope、或首次使用 lark-cli 时触发。'
+---
+
+# lark-cli 共享规则
+
+本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
+
+> **mavis 适配说明 (重要)**:
+>
+> - **绑定飞书 bot（首次使用、新机器）**：用
+>   `mavis im channel bind <agent> --platform feishu --app-id <appId> --app-secret <appSecret>`
+>   写入 local-runtime 原生 Feishu channel store（详见入口 `lark-tools/SKILL.md`）。
+> - **首次用户身份授权（一次性拿到推荐 scope 全集）**：需要用户身份时，由 agent 运行
+>   `lark-cli auth login --recommend`，UI/聊天里只展示授权 URL 给用户点击。
+> - **运行时检测到缺 scope**：按 §[Agent 代理发起认证](#agent-代理发起认证)
+>   的 canonical 模板执行（`--no-wait --json` 取 URL → 后台 `--device-code` 等用户）。**不要** curl
+>   runtime、不要再用 `--domain`。仅在推荐 scope 集合之外的高敏感 scope 才会触发这条路径。
+> - 本文件其余部分（身份选择原则、scope 概念、更新检查、安全规则）完全适用，无需特殊适配。
+
+## 配置初始化
+
+mavis 中**首次绑定 bot** 走 local-runtime channel bind（详见
+`lark-tools/SKILL.md`）。`lark-cli config init` 只在官方 CLI
+store 尚未初始化、且你需要直接运行 terminal `lark-cli` 时使用。
+
+> 仅当 local-runtime 未绑定 Feishu bot 时才需要这一步；已有 appId 时跳过。
+
+## 认证
+
+### 身份类型
+
+两种身份类型，通过 `--as` 切换：
+
+| 身份          | 标识        | 获取方式                                                  | 适用场景                             |
+| ------------- | ----------- | --------------------------------------------------------- | ------------------------------------ |
+| user 用户身份 | `--as user` | `lark-cli auth login --recommend`（首次）+ `--scope` 增量 | 访问用户自己的资源（日历、云空间等） |
+| bot 应用身份  | `--as bot`  | 自动，只需 appId + appSecret                              | 应用级操作,访问bot自己的资源         |
+
+### 身份选择原则
+
+输出的 `[identity: bot/user]` 代表当前身份。bot 与 user 表现差异很大，需确认身份符合目标需求：
+
+- **Bot 看不到用户资源**：无法访问用户的日历、云空间文档、邮箱等个人资源。例如 `--as bot`
+  查日程返回 bot 自己的（空）日历
+- **Bot 无法代表用户操作**：发消息以应用名义发送，创建文档归属 bot
+- **Bot 权限**：只需在飞书开发者后台开通 scope，无需 `auth login`
+- **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足
+
+### 权限不足处理
+
+遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
+
+错误响应中包含关键信息：
+
+- `permission_violations`：列出缺失的 scope (N选1)
+- `console_url`：飞书开发者后台的权限配置链接
+- `hint`：建议的修复命令
+
+#### Bot 身份（`--as bot`）
+
+将错误中的 `console_url` 提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
+
+#### User 身份（`--as user`）
+
+```bash
+# 首次授权（推荐 / 默认动作）：一次性拿到飞书会自动批准的推荐 scope 全集
+lark-cli auth login --recommend
+
+# 增量授权：仅当报错说缺某个推荐范围之外的高敏感 scope 时使用
+lark-cli auth login --scope "<missing_scope>"
+```
+
+**规则**：
+
+- 首次或缺少基础能力时**默认走 `--recommend`**——一次过、飞书自动批、覆盖 80%+ 日常 domain。
+- 仅当运行时报错明确缺**推荐范围之外**的 scope（如
+  `contact:user:search`、`search:message`、`im:message.group_msg:get_as_user` 等高敏感 scope）才走
+  `--scope` 增量。
+- **不要再用 `--domain`**——按 domain 申请会让用户每用一个新模块就被弹一次授权，体验差。`--recommend`
+  已经覆盖各 domain 的常用 scope。
+- 多次 login 的 scope 会累积（增量授权），`--recommend` 之上再叠 `--scope` 是安全的。
+- 在 mavis 中，local-runtime 负责 bot 绑定；用户 OAuth 仍由 `lark-cli auth login --recommend` 或增量
+  `--scope` 完成。
+
+#### Agent 代理发起认证
+
+> **Hard rule**：禁止把 `lark-cli auth login`
+> 整条命令贴给用户让他自己跑。你有 bash，命令你跑；用户只负责浏览器点同意按钮。
+
+`lark-cli` 已为 AI agent 设计非交互模式：`--no-wait --json` 立即返回 `verification_url` +
+`device_code`（不阻塞），再后台跑 `--device-code` 等用户完成。canonical 流程：
+
+```bash
+# 1) 启动 device flow，立即拿 verification_url（不阻塞，10 分钟有效）
+#    缺基础 scope 用 --recommend；缺推荐之外的高敏感 scope 用 --scope "<name>"
+RESP=$(lark-cli auth login --no-wait --json --scope "search:message")
+URL=$(echo "$RESP"  | jq -r .verification_url)
+CODE=$(echo "$RESP" | jq -r .device_code)
+
+# 2) 把 URL 发给用户点同意（user_code 可一并给出便于核对）
+echo "请点击授权链接：$URL"
+
+# 3) 后台跑 device-code 等用户完成，token 自动落到全局 lark-cli store
+nohup lark-cli auth login --device-code "$CODE" --json \
+  > /tmp/lark-auth-$$.log 2>&1 &
+disown
+```
+
+❌ 反例：把 `lark-cli auth login --scope "..."` 命令贴给用户、让他跑完把输出贴回来。
+
+授权完成后 token 自动写入全局 lark-cli store（`~/.lark-cli/` +
+`~/Library/Application Support/lark-cli/*.enc`），终端 lark-cli 后续直接复用。
+
+## 更新检查
+
+lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含
+`message`、`command` 等）。
+
+**当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
+
+1. 告知用户当前版本和最新版本号
+2. 提议执行更新（CLI 和 Skills 需要同时更新）：
+   ```bash
+   npm update -g @larksuite/cli && npx skills add larksuite/cli -g -y
+   ```
+3. 更新完成后提醒用户：**退出并重新打开 AI Agent**以加载最新 Skills
+
+**规则**：不要静默忽略更新提示。即使当前任务与更新无关，也应在完成用户请求后补充告知。
+
+## 安全规则
+
+- **禁止输出密钥**（appSecret、accessToken）到终端明文。
+- **写入/删除操作前必须确认用户意图**。
+- 用 `--dry-run` 预览危险请求。