@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-okr/references/lark-okr-progress-list.md

@@ -0,0 +1,80 @@
+# okr +progress-list
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+获取目标（Objective）或关键结果（Key Result）的所有进展记录列表。
+
+## 推荐命令
+
+```bash
+# 获取目标的所有进展记录
+lark-cli okr +progress-list \
+  --target-id 1234567890123456789 \
+  --target-type objective
+
+# 获取关键结果的所有进展记录
+lark-cli okr +progress-list \
+  --target-id 9876543210987654321 \
+  --target-type key_result
+```
+
+## 参数
+
+| 参数                    | 必填 | 默认值             | 说明                                             |
+|-------------------------|----|--------------------|--------------------------------------------------|
+| `--target-id`           | 是  | —                  | 目标 ID 或关键结果 ID（int64 类型，正整数）       |
+| `--target-type`         | 是  | —                  | 目标类型：`objective` \| `key_result`            |
+| `--user-id-type`        | 否  | `open_id`          | 用户 ID 类型：`open_id` \| `union_id` \| `user_id` |
+| `--department-id-type`  | 否  | `open_department_id` | 部门 ID 类型：`department_id` \| `open_department_id` |
+| `--dry-run`             | 否  | —                  | 预览 API 调用而不实际执行。                       |
+| `--format`              | 否  | `json`             | 输出格式。                                        |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
+2. 执行 `lark-cli okr +progress-list --target-id "..." --target-type objective`。
+3. 获取该目标或关键结果下的所有进展记录列表。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": [
+    {
+      "progress_id": "1234567890123456789",
+      "modify_time": "2025-01-15 10:30:00",
+      "content": "{...}",
+      "progress_rate": {
+        "percent": 80.0,
+        "status": "done"
+      }
+    }
+  ],
+  "total": 1
+}
+```
+
+其中：
+
+- `progress` — 进展记录数组
+- `content` 字段是 JSON 字符串，为 OKR ContentBlock 富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 与 +progress-get 的区别
+
+| 命令             | 用途                               | API 版本 |
+|------------------|------------------------------------|----------|
+| `+progress-list` | 获取某个目标/关键结果的所有进展记录 | v2       |
+| `+progress-get`  | 根据进展记录 ID 获取单条记录        | v1       |
+
+`+progress-list` 返回的 `progress_list` 数组中每条记录的结构与 `+progress-get` 返回的 `progress` 结构相同。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-okr-progress-get](lark-okr-progress-get.md) -- 根据 ID 获取单条进展记录
+- [lark-okr-progress-create](lark-okr-progress-create.md) -- 创建进展记录
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/dist/skills/larksuite/lark-okr/references/lark-okr-progress-update.md

@@ -0,0 +1,81 @@
+# okr +progress-update
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新指定 ID 的 OKR 进展记录内容。
+
+## 推荐命令
+
+```bash
+# 更新进展记录内容
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的进展内容"}}]}}]}'
+
+# 更新进展记录内容并同时更新进度
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"进度已更新至 90%"}}]}}]}' \
+  --progress-percent 90 \
+  --progress-status normal
+
+# 从文件读取 content（适用于较长的进展内容）
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content @updated_progress.json
+
+# 预览 API 调用而不实际执行
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test"}}]}}]}' \
+  --dry-run
+```
+
+## 参数
+
+| 参数                   | 必填 | 默认值       | 说明                                                                                                             |
+|----------------------|----|-----------|----------------------------------------------------------------------------------------------------------------|
+| `--progress-id`      | 是  | —         | 进展记录 ID（int64 类型，正整数）                                                                                          |
+| `--content`          | 是  | —         | 进展内容，ContentBlock JSON 格式。支持 `@文件路径` 从文件读取。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。                    |
+| `--progress-percent` | 否  | —         | 进度百分比(-99999999999 - 99999999999)。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数 |
+| `--progress-status`  | 否  | —         | 进度状态：`normal`（正常） \| `overdue`（逾期） \| `done`（已完成）。仅在指定 `--progress-percent` 时生效。                               |
+| `--user-id-type`     | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                                                                  |
+| `--dry-run`          | 否  | —         | 预览 API 调用而不实际执行。                                                                                               |
+| `--format`           | 否  | `json`    | 输出格式。                                                                                                          |
+
+## 工作流程
+
+1. 使用 `+progress-get` 获取要更新的进展记录的 ID 和当前内容。
+2. 修改 ContentBlock JSON 格式的进展内容。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。
+3. 执行 `lark-cli okr +progress-update --progress-id "..." --content "..."`。
+4. 报告结果：更新后的进展记录 ID、修改时间、进度百分比等。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 14:30:00",
+    "content": "{...}",
+    "progress_rate": {
+      "percent": 90.0,
+      "status": "normal"
+    }
+  }
+}
+```
+
+其中：
+
+- `content` 字段是 JSON 字符串，为 OKR ContentBlock
+  富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/dist/skills/larksuite/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/dist/skills/larksuite/lark-shared/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: lark-shared
+version: 1.0.0
+description: "Use when first setting up lark-cli, running auth login, switching user/bot identity (--as), handling permission denied or scope errors, needing to update lark-cli, or seeing _notice in JSON output."
+---
+
+# lark-cli 共享规则
+
+本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
+
+## 配置初始化
+
+首次使用需运行 `lark-cli config init` 完成应用配置。
+
+当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
+
+**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时，必须将 URL exactly as returned by the CLI 转发给用户，并把它视为不可修改的 opaque string；不要做 URL encode/decode，不要补 `%20`、空格或标点，不要重新拼接 query，不要改写成 Markdown link text，建议用只包含原始 URL 的代码块单独输出。
+
+```bash
+# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
+lark-cli config init --new
+```
+
+## 认证
+
+### 身份类型
+
+两种身份类型，通过 `--as` 切换：
+
+| 身份 | 标识 | 获取方式 | 适用场景 |
+|------|------|---------|---------|
+| user 用户身份 | `--as user` | `lark-cli auth login` 等 | 访问用户自己的资源（日历、云空间等） |
+| 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
+lark-cli auth login --domain <domain>           # 按业务域授权
+lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推荐,符合最小权限原则）
+```
+
+**规则**：auth login 必须指定范围（`--domain` 或 `--scope`）。多次 login 的 scope 会累积（增量授权）。
+
+#### Agent 代理发起认证（推荐）
+
+当你作为 AI agent 需要帮用户完成认证时，使用background方式 执行以下命令发起授权流程, 并将授权链接原样发给用户：
+
+```bash
+# 发起授权（阻塞直到用户授权完成或过期）
+lark-cli auth login --scope "calendar:calendar:readonly"
+
+```
+
+
+## 更新检查
+
+lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
+
+**当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
+
+1. 告知用户当前版本和最新版本号
+2. 提议执行更新（同时更新 CLI 和 Skills）：
+   ```bash
+   lark-cli update
+   ```
+3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
+
+**重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
+
+**规则**：不要静默忽略更新提示。即使当前任务与更新无关，也应在完成用户请求后补充告知。
+
+## 安全规则
+
+- **禁止输出密钥**（appSecret、accessToken）到终端明文。
+- **写入/删除操作前必须确认用户意图**。
+- 用 `--dry-run` 预览危险请求。
+
+## 高风险操作的审批协议（exit 10）
+
+lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。当你不带 `--yes` 调用这类命令时，CLI 会退出码 `10`、并在 stderr 返回如下结构化 envelope：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "confirmation_required",
+    "message": "drive +delete requires confirmation",
+    "hint": "add --yes to confirm",
+    "risk": {
+      "level": "high-risk-write",
+      "action": "drive +delete"
+    }
+  }
+}
+```
+
+**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
+
+1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation_required"`
+2. **向用户确认**：把 `error.risk.action` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
+3. **用户同意** → 在你**原始 argv 的末尾追加 `--yes`** 后重试
+4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁
+
+**绝对不允许**：
+- 看到 exit 10 就默认加 `--yes` 静默重试（这等于禁用门禁）
+- 把 `confirmation_required` 当网络错误/权限错误处理
+- 在用户没明确同意的前提下追加 `--yes` 重试
+- 用 `sh -c` 等 shell 方式拼接命令重试——用 `exec.Command(argv...)` 参数数组形式，避免 shell 解析把用户参数当作语法
+
+提前预判：想先让用户 review 危险操作的具体请求，调用时加 `--dry-run`——它不触发门禁，会打印完整请求详情（URL / body / params），你可以把这个预览给用户看过再去真正执行。
+
+### 如何识别一条命令是高风险
+
+- shortcut：`lark-cli <service> +<cmd> --help` 顶部会显示 `Risk: high-risk-write`
+- service 命令：`lark-cli schema <service>.<resource>.<method> --format json` 的返回值里 `"risk": "high-risk-write"`