dsh-lark-cli-skills 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 dsh-lark-cli-skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The skill documentation under skills/ is derived from @larksuite/cli
+(https://github.com/larksuite/cli), which is also MIT licensed.
+See NOTICE for details.

package/NOTICE

@@ -0,0 +1,33 @@
+dsh-lark-cli-skills
+===================
+
+This package redistributes agent skill documentation that originates from the
+Lark/Feishu CLI project.
+
+Upstream project
+----------------
+  Package : @larksuite/cli
+  Repo    : https://github.com/larksuite/cli
+  License : MIT
+  Copyright (c) Lark Technologies / Feishu
+
+The files under skills/ are exported verbatim from the lark-cli binary via
+`lark-cli skills list` and `lark-cli skills read`. Their wording, structure and
+examples belong to the upstream project. This repository only:
+
+  - materialises them as files on disk,
+  - registers them with the DeepSeek Harness skill registry, and
+  - ships them alongside the plugin glue code.
+
+No upstream skill text is edited, and no authorship of that text is claimed.
+
+Bundled plugin code
+-------------------
+Everything outside skills/ — lib/, scripts/, cordis.patch.yml, package.json —
+is original work of this repository and is licensed MIT.
+
+Trademarks
+----------
+"Lark" and "Feishu" are trademarks of their respective owners. This package is
+an unofficial integration and is not endorsed by or affiliated with Lark/Feishu
+or with DeepSeek.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# dsh-lark-cli-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Agent skills](https://github.com/larksuite/cli) for the Lark/Feishu CLI, packaged as a **DeepSeek Harness** plugin bundle.
+
+Once installed, the DSH agent can consult and use 27 Lark/Feishu skills — docs, Base, calendar, drive, tasks, wiki, approval, mail, slides, meetings, and more.
+
+[中文文档](./README.zh.md)
+
+## Why lark-im is excluded
+
+This package **deliberately omits** the `lark-im` (instant messaging) skill.
+
+IM channels are normally handled by a dedicated bridge plugin (for example `@xmanrui/dsh-im`). Shipping both would overlap and risk conflicting instructions, so this package covers only **non-IM** Lark capabilities — it **complements** an IM bridge instead of duplicating it.
+
+If you do want `lark-im`, read it directly with `lark-cli skills read lark-im`, or remove it from the `EXCLUDED` set in `scripts/sync-skills.mjs` and re-sync.
+
+## Prerequisite
+
+**`lark-cli` must be installed** — every skill documents its commands:
+
+```bash
+npm install -g @larksuite/cli
+lark-cli --version
+```
+
+The skills are plain Markdown, but without the CLI their commands cannot run.
+
+## Install
+
+```bash
+dsh plugin --profile <your-profile> add dsh-lark-cli-skills
+```
+
+Restart DSH afterwards; the skills appear in the agent's catalog.
+
+## Included skills (27)
+
+`lark-shared` (auth — required by all others), `lark-doc`, `lark-sheets`, `lark-base`, `lark-calendar`, `lark-drive`, `lark-wiki`, `lark-task`, `lark-approval`, `lark-mail`, `lark-slides`, `lark-vc`, `lark-vc-agent`, `lark-minutes`, `lark-meeting`, `lark-note`, `lark-whiteboard`, `lark-okr`, `lark-contact`, `lark-attendance`, `lark-markdown`, `lark-event`, `lark-apps`, `lark-openapi-explorer`, `lark-skill-maker`, `lark-workflow-meeting-summary`, `lark-workflow-standup-report`.
+
+## Updating the skill text
+
+Skill text is **exported** from the locally installed `lark-cli` binary, never hand-written:
+
+```bash
+lark-cli update      # 1. upgrade the CLI
+npm run sync         # 2. re-export
+git add -A && git commit -m "chore: sync skills from lark-cli <version>"
+npm version patch
+npm publish
+```
+
+Detect a stale local copy:
+
+```bash
+npm run sync:check   # exits 1 when out of date
+```
+
+## Provenance and licensing
+
+- **Skill text**: from [`@larksuite/cli`](https://github.com/larksuite/cli), **MIT License**, copyright Lark/Feishu. See [NOTICE](./NOTICE).
+- **Plugin glue code** (`lib/`, `scripts/`, config): MIT License, copyright the authors of this repository.
+
+This package does **not** modify upstream skill text (beyond writing it to files) and does **not** claim authorship of those skills.
+
+## Privacy
+
+Exported skills are **generic documentation** and contain no account data.
+
+The sync script reads only the public output of `lark-cli skills list/read`; it never touches `~/.lark-cli/config.json`, credential storage, or any personal data.
+
+## License
+
+MIT. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/README.zh.md

@@ -0,0 +1,100 @@
+# dsh-lark-cli-skills
+
+把 [lark-cli](https://github.com/larksuite/cli) 的 **agent skills** 打包成 DeepSeek Harness 插件。
+
+安装后，DSH agent 就能直接查阅并使用 27 个飞书/Lark 技能——文档、多维表格、日历、云空间、任务、知识库、审批、邮箱、幻灯片、会议等。
+
+## 为什么不包含 lark-im
+
+本包**刻意排除** `lark-im`（即时通讯）技能。
+
+原因：IM 通道通常由专门的桥接插件负责（例如 `@xmanrui/dsh-im`）。两者同时提供会造成功能重叠与指令冲突，所以这里只补充**非 IM** 的飞书能力，与 IM 插件**互补**而非重复。
+
+如果你确实需要 lark-im 技能，直接从 `lark-cli skills read lark-im` 读取即可，或修改 `scripts/sync-skills.mjs` 里的 `EXCLUDED` 集合后重新同步。
+
+## 前置条件
+
+**必须先安装 `lark-cli`**，因为技能内容描述的都是它的命令：
+
+```bash
+npm install -g @larksuite/cli
+lark-cli --version
+```
+
+技能本身只是 Markdown 文档，但不装 CLI 就无法执行里面的命令。
+
+## 安装
+
+```bash
+dsh plugin --profile <your-profile> add dsh-lark-cli-skills
+```
+
+安装后重启 DSH，agent 的 skill catalog 里会出现 `lark-doc`、`lark-sheets`、`lark-base` 等技能。
+
+## 包含的技能（27 个）
+
+| 技能 | 用途 |
+| --- | --- |
+| `lark-shared` | 认证、身份切换、权限处理（**其他技能都依赖它**） |
+| `lark-doc` | 飞书文档读写 |
+| `lark-sheets` | 电子表格 |
+| `lark-base` | 多维表格 |
+| `lark-calendar` | 日历与会议室 |
+| `lark-drive` | 云空间文件 |
+| `lark-wiki` | 知识库 |
+| `lark-task` | 任务与清单 |
+| `lark-approval` | 审批 |
+| `lark-mail` | 邮箱 |
+| `lark-slides` | 幻灯片 |
+| `lark-vc` / `lark-vc-agent` | 视频会议 |
+| `lark-minutes` / `lark-meeting` / `lark-note` | 妙记与会议纪要 |
+| `lark-whiteboard` | 白板 |
+| `lark-okr` | OKR |
+| `lark-contact` | 通讯录 |
+| `lark-attendance` | 考勤 |
+| `lark-markdown` | 云盘 Markdown |
+| `lark-event` | 实时事件订阅 |
+| `lark-apps` | 妙搭应用开发 |
+| `lark-openapi-explorer` | 通用 OpenAPI 探索 |
+| `lark-skill-maker` | 技能生成辅助 |
+| `lark-workflow-*` | 会议总结 / 站会报告工作流 |
+
+## 更新技能内容
+
+技能内容是从本机 `lark-cli` 二进制里**导出**的，不是手写的。上游发新版后：
+
+```bash
+# 1. 升级 CLI
+lark-cli update
+
+# 2. 重新导出
+npm run sync
+
+# 3. 提交并发布
+git add -A && git commit -m "chore: sync skills from lark-cli <version>"
+npm version patch
+npm publish
+```
+
+检查本地副本是否过期：
+
+```bash
+npm run sync:check   # 过期时退出码为 1
+```
+
+## 内容来源与许可
+
+- **技能文本**：来自 [`@larksuite/cli`](https://github.com/larksuite/cli)，**MIT License**，版权归 Lark/Feishu 所有。见 [NOTICE](./NOTICE)。
+- **插件胶水代码**（`lib/`、`scripts/`、配置）：MIT License，版权归本仓库作者所有。
+
+本包**不修改**上游技能文本的内容（除导出为文件外），也不声称这些技能由本仓库原创。
+
+## 隐私
+
+导出的技能是**通用文档**，不包含任何使用者的账号信息。
+
+同步脚本只读取 `lark-cli skills list/read` 的公开输出，不接触 `~/.lark-cli/config.json`、凭据存储或任何个人数据。
+
+## License
+
+MIT。详见 [LICENSE](./LICENSE) 与 [NOTICE](./NOTICE)。

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-lark-cli-skills — dsh bundle patch
+#
+# Installed with:
+#   dsh plugin --profile <name> add <spec>
+#
+# The loader mounts lib/index.js, which reads every skills/<name>/SKILL.md in
+# this package and registers each one with ctx.skills, so the lark-cli skills
+# appear in the agent's catalog. The reference trees ship alongside each
+# SKILL.md, so relative links inside the skill bodies keep working.
+- insert:
+    - id: dsh-lark-cli-skills
+      name: 'dsh-lark-cli-skills'

package/lib/index.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-lark-cli-skills — dsh bundle entry.
+ *
+ * Registers every skill shipped in ./skills/ with ctx.skills, so the
+ * lark-cli skill set shows up in the agent's catalog once this package is
+ * installed as a dsh profile bundle:
+ *
+ *   dsh plugin --profile <name> add dsh-lark-cli-skills
+ *
+ * Each skill lives in skills/<name>/SKILL.md with its reference files beside
+ * it; resourceBase points at that directory so the relative links inside the
+ * skill body (references/*.md, ../lark-shared/SKILL.md) resolve correctly.
+ *
+ * The skill text is generated from the locally installed lark-cli binary by
+ * scripts/sync-skills.mjs. It is not written by hand — re-run that script to
+ * pick up a new upstream version.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const name = 'dsh-lark-cli-skills';
+export const inject = ['skills'];
+
+const SKILLS_ROOT = fileURLToPath(new URL('../skills/', import.meta.url));
+
+/** Minimal YAML-frontmatter reader for the fields the registry needs. */
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return null;
+  const fm = match[1];
+  const get = (key) => {
+    const line = fm.match(new RegExp('^' + key + ':\\s*(.+)$', 'm'));
+    if (!line) return undefined;
+    let value = line[1].trim();
+    const quoted =
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"));
+    if (quoted) value = value.slice(1, -1);
+    return value;
+  };
+  return {
+    name: get('name'),
+    description: get('description'),
+    whenToUse: get('whenToUse'),
+  };
+}
+
+/** Skill directories present on disk, sorted for deterministic registration. */
+function skillDirectories() {
+  let entries;
+  try {
+    entries = readdirSync(SKILLS_ROOT);
+  } catch (error) {
+    return { error };
+  }
+  return {
+    dirs: entries
+      .filter((entry) => {
+        try {
+          return statSync(join(SKILLS_ROOT, entry)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort(),
+  };
+}
+
+export function apply(ctx) {
+  const { dirs, error } = skillDirectories();
+  if (error !== undefined) {
+    ctx.logger.error('dsh-lark-cli-skills: cannot read skills/ directory: %s', error.message);
+    return;
+  }
+  if (dirs.length === 0) {
+    ctx.logger.warn('dsh-lark-cli-skills: skills/ is empty; nothing to register');
+    return;
+  }
+
+  const disposers = [];
+  let registered = 0;
+
+  for (const dir of dirs) {
+    const skillDir = join(SKILLS_ROOT, dir);
+    const skillFile = join(skillDir, 'SKILL.md');
+
+    let raw;
+    try {
+      raw = readFileSync(skillFile, 'utf8');
+    } catch {
+      // A directory without SKILL.md is not a skill; skip quietly.
+      continue;
+    }
+
+    const meta = parseFrontmatter(raw);
+    if (!meta || !meta.name || !meta.description) {
+      ctx.logger.warn(
+        'dsh-lark-cli-skills: %s/SKILL.md lacks name/description; skipped',
+        dir,
+      );
+      continue;
+    }
+
+    const content = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trimStart();
+
+    try {
+      const disposer = ctx.skills.register({
+        name: meta.name,
+        description: meta.description,
+        ...(meta.whenToUse ? { whenToUse: meta.whenToUse } : {}),
+        content,
+        source: 'runtime',
+        resourceBase: { kind: 'directory', path: skillDir },
+      });
+      if (typeof disposer === 'function') disposers.push(disposer);
+      registered += 1;
+    } catch (error) {
+      ctx.logger.warn(
+        'dsh-lark-cli-skills: failed to register "%s": %s',
+        meta.name,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  ctx.logger.info('dsh-lark-cli-skills: registered %d skill(s)', registered);
+
+  ctx.on('dispose', () => {
+    for (const dispose of disposers) {
+      try {
+        dispose();
+      } catch {
+        // Disposal is best effort.
+      }
+    }
+  });
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "dsh-lark-cli-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Agent skills for the Lark/Feishu CLI (lark-cli), packaged as a DeepSeek Harness plugin bundle. Provides 27 lark-cli skills (docs, sheets, base, calendar, drive, task, wiki, approval, mail, slides, vc and more) to the DSH agent. Intentionally excludes lark-im so it complements — rather than duplicates — an existing IM bridge plugin.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "skills.manifest.json",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "dsh-plugin",
+    "skill",
+    "lark",
+    "feishu",
+    "lark-cli",
+    "agent-skills",
+    "docs",
+    "sheets",
+    "base",
+    "calendar"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "scripts": {
+    "sync": "node scripts/sync-skills.mjs",
+    "sync:check": "node scripts/sync-skills.mjs --check",
+    "sync:dry": "node scripts/sync-skills.mjs --dry-run"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevenjj33/dsh-lark-cli-skills.git"
+  },
+  "homepage": "https://github.com/stevenjj33/dsh-lark-cli-skills#readme",
+  "bugs": {
+    "url": "https://github.com/stevenjj33/dsh-lark-cli-skills/issues"
+  }
+}

package/skills/lark-approval/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: lark-approval
+version: 1.2.0
+description: "飞书审批：查询和处理审批待办/已办/实例，搜索可发起审批定义、查看定义详情并发起原生审批实例。当用户要处理审批任务、查看审批实例、搜索或发起审批时使用。审批待办不是飞书任务；非审批类待办走 lark-task。不负责创建审批定义；三方审批定义不走原生提单。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli approval --help"
+---
+
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+所有命令默认 `--as user`（审批是人的动作）。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，只有在 reference 未覆盖的原生 / 高级场景下，才额外用 `lark-cli ... --help`、`lark-cli schema` 等方式补充确认字段。
+
+## 路由优先级（先判断是不是审批，再选命令）
+
+审批待办不是飞书任务。**只要用户的核心对象是审批单据 / 审批待办 / 审批实例，就优先使用 `lark-approval`，不要让渡给 `lark-task`。**
+
+### 明确归 `lark-approval` 的高优先级语义
+
+出现以下任一语义时，优先走 `lark-approval`：
+
+- 审批待办 / 审批单据 / 审批实例 / 审批意见 / 审批定义
+- 同意 / 拒绝 / 转交 / 退回 / 撤回 / 催办 / 加签 / 抄送
+- 待办列表 / 待办单据 / 已发起审批 / 已办审批 / 审批详情 / 同意可编辑
+
+**判定规则：** 只要最终动作是对审批单据做同意、拒绝、转交、退回、撤回、催办、加签、抄送、查详情、查已发起/已办/待办，就归 `lark-approval`。只有当用户处理的是**非审批类任务/待办**时，才走 [`lark-task`](../lark-task/SKILL.md)。
+
+## 选哪个命令
+
+| 想做什么 | 命令 | 按需读取 reference                                                                  |
+|---|---|---------------------------------------------------------------------------------|
+| 搜可发起定义 | `approvals search` | [`lark-approval-approvals-search.md`](references/lark-approval-approvals-search.md) |
+| 看审批定义详情/提单前确认表单与流程 | `approvals get` | [`lark-approval-approvals-get.md`](references/lark-approval-approvals-get.md)   |
+| 发起原生审批实例/提交请假审批/提交报销审批/创建审批实例 | `instances create` | [`lark-approval-initiate.md`](references/lark-approval-initiate.md)             |
+| 查/搜待办、已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读） | [`lark-approval-tasks-query.md`](references/lark-approval-tasks-query.md)       |
+| 看表单/进度/当前节点 | `instances get` | [`lark-approval-instances-get.md`](references/lark-approval-instances-get.md)   |
+| 同意审批 | `tasks approve` | [`lark-approval-tasks-approve.md`](references/lark-approval-tasks-approve.md)   |
+| 拒绝审批 | `tasks reject` | [`lark-approval-tasks-reject.md`](references/lark-approval-tasks-reject.md)     |
+| 转交审批 | `tasks transfer` | [`lark-approval-tasks-transfer.md`](references/lark-approval-tasks-transfer.md) |
+| 加签审批 | `tasks add_sign` | [`lark-approval-tasks-add-sign.md`](references/lark-approval-tasks-add-sign.md) |
+| 退回审批 | `tasks rollback` | [`lark-approval-tasks-rollback.md`](references/lark-approval-tasks-rollback.md) |
+| 催办审批 | `tasks remind` | [`lark-approval-tasks-remind.md`](references/lark-approval-tasks-remind.md)     |
+| 撤回已发起审批 | `instances cancel` | [`lark-approval-instances-cancel.md`](references/lark-approval-instances-cancel.md) |
+| 给审批实例追加抄送 | `instances cc` | [`lark-approval-instances-cc.md`](references/lark-approval-instances-cc.md)     |
+| 按定义/关键词查已发起审批 | `instances initiated` | [`lark-approval-instances-initiated.md`](references/lark-approval-instances-initiated.md) |
+
+处理链：
+
+- 发起审批：`approvals search` -> `approvals get` -> `instances create`
+- 处理审批：`tasks query` 拿 `instance_code` + `task_id`（操作必须成对带上）→ 只有用户明确需要查看详情、当前节点、表单内容、或流程进度时，再 `instances get` → 执行操作
+
+## 执行原则（减少误路由、误重试和无效消耗）
+
+### 1) 先拿最小必要信息，再执行
+
+- 目标只是处理待办时，优先 `tasks query` 获取 `instance_code` + `task_id`
+- **只有**用户明确要看详情、当前节点、表单内容、流程进度时，才调用 `instances get`
+- 用户已经明确给出 `instance_code` / `task_id` 时，不要先查列表再过滤
+
+### 2) 已知对象时直达动作
+
+- 已拿到 `instance_code` + `task_id` 后，优先直接执行 `tasks approve/reject/transfer/add_sign/rollback/remind`
+- 同一轮里如果已有足够的新鲜查询结果，不要重复 `tasks query`
+- 不要默认走 `list -> filter -> detail -> write` 全链路；对象已明确时应压缩步骤
+
+### 3) 错误码驱动，而不是盲目重试
+
+- 写操作失败后，先看错误码和报错语义，再决定是否补查或结束
+- **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个写操作**
+- 同一个失败原因不要连续多次重试，避免 token 和耗时失控，最多重试1次
+
+## 写操作失败处理：1395001 决策树
+
+当拒绝 / 转交 / 退回 / 撤回 / 同意等写操作返回 `1395001`（任务状态异常 / 写前置校验失败）时，按下面规则处理：
+
+1. **先停止盲目重试**，不要连续重复提交相同写操作，最多重试1次
+2. 优先从以下角度解释：
+   - 任务可能已被他人处理
+   - 单据状态已变化，当前动作已不再允许
+   - 当前用户已不具备该任务的操作资格
+   - 当前节点或单据状态不支持该操作
+3. 如需确认，只补 **一次** 状态查询（`tasks query` 或 `instances get`），不要陷入 query/write 循环
+4. 最终给用户明确结论和下一步建议，而不是继续无意义重试
+
+**特别注意：** 对拒绝 / 转交 / 撤回场景更要严格执行上述规则；这些场景最容易因状态切换而失败。
+
+```bash
+lark-cli approval approvals search --data '{"keyword":"请假"}' --as user
+lark-cli approval approvals get --params '{"approval_code":"<code>"}' --as user
+lark-cli approval instances create --data '{"approval_code":"<code>","form":"[...]"}' --yes --as user
+lark-cli approval tasks query --params '{"topic":"1"}' --as user
+lark-cli approval tasks approve --data '{"instance_code":"<ic>","task_id":"<tid>","comment":"同意"}' --as user
+```
+
+## 不在本 skill 范围
+
+创建审批定义（走飞书客户端或审批管理后台）；三方定义发起（返回 `create_link`，引导用户通过链接发起）；非审批类待办 → [`lark-task`](../lark-task/SKILL.md)

package/skills/lark-approval/references/lark-approval-approvals-get.md

@@ -0,0 +1,128 @@
+
+# approval approvals get
+
+获取单个审批定义详情（用户级只读操作）。适合在发起审批实例前，先确认审批名称、表单控件结构、选项值范围以及流程节点信息。
+
+需要的 scopes: ["approval:approval:read"]
+
+## 命令
+
+```bash
+# 按 approval_code 查询审批定义详情
+lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user
+
+# 表格格式输出，便于快速浏览顶层字段
+lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --format table --as user
+
+# 预览 API 调用，不执行
+lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--params '{...}'` | 是 | 查询参数，使用 JSON 传入 |
+| `approval_code` | 是 | 审批定义 Code；通常来自 `approval approvals search` 的结果 |
+| `locale` | 否 | 返回语言，例如 `zh-CN`、`en-US`、`ja-JP` |
+| `--as user` | 否 | 建议显式指定用户身份；审批定义详情通常按当前用户可见范围读取 |
+| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 常见输入来源
+
+如果你已经有 `approval_code`，可直接查询：
+
+```bash
+lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user
+```
+
+如果你还没有 `approval_code`，先搜索可发起审批定义：
+
+```bash
+lark-cli approval approvals search --data '{"keyword":"请假"}' --as user
+```
+
+## 输出重点字段
+
+返回结果中，优先关注以下字段：
+
+| 字段 | 说明 |
+|------|------|
+| `approval_code` | 审批定义 Code |
+| `approval_name` | 审批定义名称；确认是不是用户想发起的那张单 |
+| `form` | 表单定义快照；用于识别控件 `id`、`type`、选项值范围、明细子控件结构 |
+| `node_list` | 流程节点列表；用于识别节点 key、是否需要补充审批人、是否允许多人 |
+
+## form 的使用重点
+
+`form` 最重要的作用是帮助 agent **识别怎么组装 `instances.create.data.form`**，而不是直接把它原样提交出去。
+
+重点看：
+
+| 字段 / 结构 | 说明 |
+|------|------|
+| `form[].id` | 控件 ID；后续创建实例时必须使用 |
+| `form[].type` | 控件类型，例如 `input`、`date`、`radio`、`checkbox`、`fieldList` |
+| `form[].value` / 选项定义 | 用来识别可选值范围、默认值或选项值 |
+| 明细 / 子控件结构 | 用于识别 `fieldList`、控件组等复杂控件的子字段结构 |
+
+**注意：`approvals.get.form` 不是 `instances.create` 可直接复用的 payload 模板。** 它是“定义快照”，主要用于识别字段结构与选项值范围。
+
+## node_list 的使用重点
+
+`node_list` 主要用于后续决定是否要补 `node_approver_list` / `node_cc_list`。
+
+重点看：
+
+| 字段 | 说明 |
+|------|------|
+| `node_list[].custom_node_id` | 自定义节点标识；后续补节点参数时优先作为 key |
+| `node_list[].node_id` | 节点 ID；若没有 `custom_node_id`，通常退回用它做 key |
+| `node_list[].need_approver` | 是否要求发起人补充审批人 |
+| `node_list[].approver_chosen_multi` | 是否允许为该节点选择多个审批人 |
+
+## 使用建议
+
+- **这是发起原生审批实例前的必要只读步骤。** 推荐固定走：`approvals search` -> `approvals get` -> `instances create`。
+- **如果用户已经明确给了 `approval_code`，直接用这个命令。** 不必再走 `approvals search`。
+- **先确认 `approval_name`。** 避免把相似名称的审批定义搞混。
+- **先用 `form` 识别控件结构，再组装创建 payload。** 不要在未看详情时猜控件 `id`、`type` 或选项值。
+- **先用 `node_list` 看是否需要补审批人。** 若某节点 `need_approver=true`，创建实例时通常要补 `node_approver_list`。
+- **`node_list` 的 key 优先取 `custom_node_id`。** 若不存在，再使用 `node_id`。
+- **`approver_chosen_multi=false` 时，一个节点通常只能补一个审批人。**
+
+## 输出与后续操作
+
+读取定义详情后，常见下一步：
+
+```bash
+# 发起原生审批实例
+lark-cli approval instances create --data '{"approval_code":"<APPROVAL_CODE>","form":"[...]"}' --as user --yes
+```
+
+如果需要进一步理解控件取值与节点参数，优先参考：
+
+- `lark-approval-instance-form-control-parameters.md`
+- `lark-approval-instance-value-sourcing.md`
+- `lark-approval-initiate.md`
+
+## 结果整理方式
+
+**将结果整理为“审批定义概览 + 表单结构摘要 + 节点要求摘要”。**
+
+建议输出成下面这种结构：
+
+```text
+审批定义：请假申请
+approval_code: 7C468A54-8745-2245-9675-08B7C63E7A85
+
+表单控件摘要：
+- leave_type: radio，可选值 [annual_leave, sick_leave]
+- reason: textarea
+- start_end: dateInterval
+
+节点要求摘要：
+- manager_node：need_approver=true，approver_chosen_multi=false
+- hr_node：need_approver=false
+```