@lark-apaas/coding-steering 0.1.6-alpha.0 → 0.1.6-alpha.2

package/steering/nestjs-react-fullstack/skills/feishu/references/messaging.md

@@ -1,207 +0,0 @@
-# 消息 (Messaging)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/im-v1/introduction.md
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中发送和回复飞书消息。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `im:message:send_as_bot` | 以应用身份发送消息 |
-
-## 发送消息
-
-```typescript
-// 发送文本消息
-const res = await client.im.message.create({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    content: JSON.stringify({ text: '你好，这是一条测试消息' }),
-    msg_type: 'text',
-  },
-});
-if (res.code !== 0) throw new Error(`[${res.code}] ${res.msg}`);
-```
-
-### receive_id_type 与 ID 前缀对应关系
-
-| receive_id_type | ID 前缀 | 说明 |
-|-----------------|---------|------|
-| `chat_id` | `oc_` | 群聊 ID |
-| `open_id` | `ou_` | 用户 open_id |
-| `union_id` | `on_` | 用户 union_id |
-| `user_id` | 无固定前缀 | 用户 user_id |
-| `email` | - | 用户邮箱 |
-
-## 发送富文本消息
-
-```typescript
-await client.im.message.create({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    content: JSON.stringify({
-      zh_cn: {
-        title: '项目更新',
-        content: [
-          [
-            { tag: 'text', text: '版本 2.0 已发布，主要更新：' },
-            { tag: 'a', text: '查看详情', href: 'https://example.com' },
-          ],
-        ],
-      },
-    }),
-    msg_type: 'post',
-  },
-});
-```
-
-## 发送卡片消息
-
-```typescript
-// 方式 1：JSON 卡片
-await client.im.message.create({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    content: JSON.stringify({
-      header: {
-        template: 'blue',
-        title: { content: '卡片标题', tag: 'plain_text' },
-      },
-      elements: [
-        { tag: 'markdown', content: '**进度更新**\n- 前端：80%\n- 后端：60%' },
-        {
-          tag: 'action',
-          actions: [
-            { tag: 'button', text: { tag: 'plain_text', content: '确认' }, type: 'primary' },
-          ],
-        },
-      ],
-    }),
-    msg_type: 'interactive',
-  },
-});
-
-// 方式 2：SDK 内置默认卡片（快速使用）
-await client.im.message.create({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    content: lark.messageCard.defaultCard({ title: '标题', content: '内容' }),
-    msg_type: 'interactive',
-  },
-});
-
-// 方式 3：卡片模板（推荐，在卡片搭建工具中配置后使用 template_id）
-await client.im.message.createByCard({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    template_id: 'your_template_id',
-    template_variable: { title: '标题', content: '正文内容' },
-  },
-});
-```
-
-## 回复消息
-
-```typescript
-await client.im.message.reply({
-  path: { message_id: 'om_xxx' },
-  data: {
-    content: JSON.stringify({ text: '收到，我马上处理' }),
-    msg_type: 'text',
-  },
-});
-```
-
-## 编辑消息（24h 内）
-
-```typescript
-await client.im.message.update({
-  path: { message_id: 'om_xxx' },
-  data: {
-    content: JSON.stringify({ text: '已更新的消息内容' }),
-    msg_type: 'text',
-  },
-});
-```
-
-## 更新卡片消息
-
-```typescript
-await client.im.message.patch({
-  path: { message_id: 'om_xxx' },
-  data: {
-    content: JSON.stringify({
-      elements: [{ tag: 'markdown', content: '已更新的卡片内容' }],
-    }),
-  },
-});
-```
-
-## 消息内容格式
-
-### text（文本）
-
-```json
-{"text": "你好，这是一条消息"}
-```
-
-支持 @ 用户：`{"text": "<at user_id=\"ou_xxx\">张三</at> 请查看"}`
-
-### post（富文本）
-
-```json
-{
-  "zh_cn": {
-    "title": "标题",
-    "content": [
-      [
-        {"tag": "text", "text": "普通文本"},
-        {"tag": "a", "text": "链接文字", "href": "https://example.com"},
-        {"tag": "at", "user_id": "ou_xxx"}
-      ]
-    ]
-  }
-}
-```
-
-### interactive（卡片）
-
-```json
-{
-  "header": {
-    "template": "blue",
-    "title": {"content": "卡片标题", "tag": "plain_text"}
-  },
-  "elements": [
-    {"tag": "markdown", "content": "**标题**\n内容文本"},
-    {
-      "tag": "action",
-      "actions": [
-        {"tag": "button", "text": {"tag": "plain_text", "content": "按钮"}, "type": "primary"}
-      ]
-    }
-  ]
-}
-```
-
-## 使用限制
-
-- 向同一用户发消息限频：**5 QPS**
-- 向同一群组发消息限频：群内机器人共享 **5 QPS**
-- 文本消息最大 **150 KB**
-- 卡片/富文本消息最大 **30 KB**
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| `content` 传对象 | 必须 `JSON.stringify({text: 'hello'})` |
-| 群聊 ID 用 `open_id` 类型 | `oc_` 开头的是 `chat_id` |
-| 富文本 content 不是二维数组 | `content: [[{tag:'text', text:'...'}]]` 外层是行数组 |
-| 忘记开启机器人能力 | 应用能力 → 添加机器人 |

package/steering/nestjs-react-fullstack/skills/feishu/references/oauth.md

@@ -1,164 +0,0 @@
-# OAuth 用户授权
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM
-
-默认的 tenant_access_token 以应用身份调用 API。
-部分场景（个人日历、搜索联系人）需要 user_access_token 代表用户操作。
-
-## 授权流程
-
-### 1. 构造 redirect_uri 并重定向用户到授权页面
-
-```typescript
-// 域名和路径根从运行时获取
-const redirectUri = `https://${req.hostname}${process.env.CLIENT_BASE_PATH}/feishu/oauth/callback`;
-const authorizeUrl = `https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=${FEISHU_APP_ID}&redirect_uri=${encodeURIComponent(redirectUri)}&state=${state}`;
-// 返回 302 重定向或将 URL 返回给前端
-```
-
-### 2. 回调中用 code 换取 token
-
-```typescript
-const userId = req.userContext.userId; // 当前登录用户
-await client.userAccessToken.initWithCode({ [userId]: code });
-```
-
-### 3. 获取 token（自动 refresh）
-
-```typescript
-const token = await client.userAccessToken.get(userId);
-```
-
-### 4. 携带 user_access_token 调用 API
-
-```typescript
-await client.calendar.calendarEvent.create(
-  { data: { summary: '我的日程', ... } },
-  lark.withUserAccessToken(token),
-);
-```
-
-## Token 持久化与用户关联
-
-SDK 默认将 token 存在内存，重启后丢失。生产环境需持久化到数据库。
-
-### 建表
-
-```sql
-CREATE TABLE feishu_user_token (
-  user_id           VARCHAR(64) PRIMARY KEY,  -- req.userContext.userId
-  open_id           VARCHAR(64) NOT NULL,     -- 飞书用户标识
-  access_token      TEXT NOT NULL,
-  refresh_token     TEXT NOT NULL,
-  token_expire_at   TIMESTAMPTZ NOT NULL,
-  refresh_expire_at TIMESTAMPTZ NOT NULL,
-  updated_at        TIMESTAMPTZ DEFAULT NOW()
-);
-```
-
-### FeishuOAuthService 示例
-
-回调保存和 token 刷新的完整 NestJS Service 实现：
-
-- `access_token` 有效期 2 小时，`refresh_token` 有效期 30 天
-- 每次 refresh 后，服务端会同时返回**新的 `refresh_token`**（token rotation），必须用新值覆盖旧值，否则下次刷新会失败
-
-```typescript
-import { Injectable, Inject } from '@nestjs/common';
-import { DRIZZLE_DATABASE, type PostgresJsDatabase } from '@lark-apaas/fullstack-nestjs-core';
-import { eq } from 'drizzle-orm';
-import { feishuUserToken } from '@server/database/schema';
-
-@Injectable()
-export class FeishuOAuthService {
-  private readonly EXPIRY_BUFFER_MS = 3 * 60 * 1000; // 预留 3 分钟 buffer
-
-  constructor(
-    private readonly feishuService: FeishuService,
-    @Inject(DRIZZLE_DATABASE) private readonly db: PostgresJsDatabase,
-  ) {}
-
-  /** 回调中用 code 换取 token 并持久化（Step 2 之后调用） */
-  async handleCallback(userId: string, code: string) {
-    const client = this.feishuService.getClient();
-    const tokenRes = await client.authen.oidcAccessToken.create({
-      data: { grant_type: 'authorization_code', code },
-    });
-    if (tokenRes.code !== 0 || !tokenRes.data) {
-      throw new Error(`Feishu OAuth token error [${tokenRes.code}]: ${tokenRes.msg}`);
-    }
-    const { access_token, refresh_token, open_id, expires_in, refresh_expires_in } = tokenRes.data;
-    const now = Date.now();
-    await this.db.insert(feishuUserToken).values({
-      userId,
-      openId: open_id,
-      accessToken: access_token,
-      refreshToken: refresh_token,
-      tokenExpireAt: new Date(now + expires_in * 1000),
-      refreshExpireAt: new Date(now + refresh_expires_in * 1000),
-    }).onConflictDoUpdate({
-      target: feishuUserToken.userId,
-      set: {
-        openId: open_id,
-        accessToken: access_token,
-        refreshToken: refresh_token,
-        tokenExpireAt: new Date(now + expires_in * 1000),
-        refreshExpireAt: new Date(now + refresh_expires_in * 1000),
-      },
-    });
-  }
-
-  /** 获取有效的 user_access_token，自动刷新 */
-  async getValidToken(userId: string): Promise<string> {
-    const [stored] = await this.db
-      .select()
-      .from(feishuUserToken)
-      .where(eq(feishuUserToken.userId, userId));
-    if (!stored) throw new Error('用户未授权飞书，请先完成 OAuth 授权');
-
-    const now = Date.now();
-
-    // 1. access_token 未过期 → 直接返回
-    if (stored.tokenExpireAt.getTime() - now > this.EXPIRY_BUFFER_MS) {
-      return stored.accessToken;
-    }
-
-    // 2. access_token 过期，但 refresh_token 未过期 → 刷新
-    if (stored.refreshExpireAt.getTime() - now > this.EXPIRY_BUFFER_MS) {
-      const client = this.feishuService.getClient();
-      const res = await client.authen.oidcRefreshAccessToken.create({
-        data: { grant_type: 'refresh_token', refresh_token: stored.refreshToken },
-      });
-      if (res.code !== 0 || !res.data) {
-        throw new Error(`Feishu OAuth refresh error [${res.code}]: ${res.msg}`);
-      }
-      const { access_token, refresh_token, expires_in, refresh_expires_in } = res.data;
-
-      // 必须同时更新 access_token 和 refresh_token（token rotation）
-      await this.db.update(feishuUserToken)
-        .set({
-          accessToken: access_token,
-          refreshToken: refresh_token,
-          tokenExpireAt: new Date(now + expires_in * 1000),
-          refreshExpireAt: new Date(now + refresh_expires_in * 1000),
-        })
-        .where(eq(feishuUserToken.userId, userId));
-      return access_token;
-    }
-
-    // 3. refresh_token 也过期 → 需要用户重新授权（回到第 1 步）
-    throw new Error('飞书授权已过期，请重新授权');
-  }
-}
-```
-
-#### 在业务代码中使用
-
-```typescript
-// 在 Controller 或其他 Service 中注入 FeishuOAuthService
-const token = await this.feishuOAuthService.getValidToken(req.userContext.userId);
-await this.feishuService.getClient().calendar.calendarEvent.create(
-  { data: { summary: '我的日程', ... } },
-  lark.withUserAccessToken(token),
-);
-```

package/steering/nestjs-react-fullstack/skills/feishu/references/perm.md

@@ -1,90 +0,0 @@
-# 权限管理 (Permission)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/permission/overview
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书云文档的协作者权限。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `drive:permission` | 管理文档/文件的协作者权限 |
-
-> **敏感操作警告**：权限管理涉及文档访问控制，添加/移除协作者会直接影响用户的文档可见性。操作前请确认目标对象和权限级别。
-
-## 列出协作者
-
-```typescript
-const res = await client.drive.permissionMember.list({
-  path: { token: 'ABC123' },
-  params: { type: 'docx' },
-});
-const members = res.data?.items ?? [];
-// members: [{member_type, member_id, perm, name}, ...]
-```
-
-## 添加协作者
-
-```typescript
-const res = await client.drive.permissionMember.create({
-  path: { token: 'ABC123' },
-  params: { type: 'docx', need_notification: false },
-  data: {
-    member_type: 'email',
-    member_id: 'user@example.com',
-    perm: 'edit',
-  },
-});
-```
-
-## 移除协作者
-
-```typescript
-await client.drive.permissionMember.delete({
-  path: { token: 'ABC123', member_id: 'user@example.com' },
-  params: { type: 'docx', member_type: 'email' },
-});
-```
-
-## Token 类型参考
-
-| 类型 | 说明 |
-|------|------|
-| `doc` | 旧版文档 |
-| `docx` | 新版文档 |
-| `sheet` | 电子表格 |
-| `bitable` | 多维表格 |
-| `folder` | 文件夹 |
-| `file` | 上传的文件 |
-| `wiki` | 知识库节点 |
-| `mindnote` | 思维导图 |
-
-## 成员类型参考
-
-| 类型 | 说明 |
-|------|------|
-| `email` | 邮箱地址 |
-| `openid` | 用户 open_id |
-| `userid` | 用户 user_id |
-| `unionid` | 用户 union_id |
-| `openchat` | 群聊 open_id |
-| `opendepartmentid` | 部门 open_id |
-| `groupid` | 用户组 ID |
-| `wikispaceid` | 知识空间 ID |
-
-## 权限级别参考
-
-| 权限值 | 说明 |
-|--------|------|
-| `view` | 仅查看 |
-| `edit` | 可编辑 |
-| `full_access` | 完全访问（可管理权限） |
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| token 类型与文件实际类型不匹配 | `type` 参数必须与文件实际类型一致（docx/sheet/bitable 等） |
-| 用 wiki URL 的 token 直接操作权限 | Wiki 节点需用 `wiki` 类型，或先获取 `obj_token` 用对应类型 |
-| 添加协作者时成员不存在 | 确认 member_id 正确，email 需要是飞书注册邮箱 |
-| 移除自身的 full_access 权限 | 文档至少需要一个管理员，避免移除最后一个 full_access 成员 |

package/steering/nestjs-react-fullstack/skills/feishu/references/wiki.md

@@ -1,164 +0,0 @@
-# 知识库 (Wiki)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/wiki-v2/wiki-overview
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书知识库。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `wiki:wiki` | 读写知识库 |
-| `wiki:wiki:readonly` | 只读知识库 |
-
-> 机器人需被添加为知识空间成员才能访问：知识空间 → 设置 → 成员管理 → 添加机器人。
-
-## 从 URL 提取 Token
-
-URL 格式：`https://xxx.feishu.cn/wiki/{token}`
-
-```typescript
-const url = 'https://xxx.feishu.cn/wiki/ABC123def';
-const token = new URL(url).pathname.split('/wiki/')[1]; // 'ABC123def'
-```
-
-## 列出知识空间
-
-```typescript
-const res = await client.wiki.space.list({});
-const spaces = res.data?.items ?? [];
-// spaces: [{space_id, name, description, visibility}, ...]
-```
-
-> 如果返回空列表，说明机器人未被添加到任何知识空间。
-
-## 列出节点
-
-```typescript
-// 列出空间根节点
-const res = await client.wiki.spaceNode.list({
-  path: { space_id: '7xxx' },
-});
-const nodes = res.data?.items ?? [];
-// nodes: [{node_token, obj_token, obj_type, title, has_child}, ...]
-
-// 列出子节点
-const childRes = await client.wiki.spaceNode.list({
-  path: { space_id: '7xxx' },
-  params: { parent_node_token: 'wikcnXXX' },
-});
-```
-
-## 获取节点详情
-
-```typescript
-const res = await client.wiki.space.getNode({
-  params: { token: 'ABC123def' }, // 从 URL 提取的 token
-});
-const node = res.data?.node;
-// node: {node_token, space_id, obj_token, obj_type, title, parent_node_token, has_child, creator}
-```
-
-> **关键**：返回的 `obj_token` 是实际文档/表格的 token，需用它来调用 docx/bitable 等 API。
-
-## 创建节点
-
-```typescript
-const res = await client.wiki.spaceNode.create({
-  path: { space_id: '7xxx' },
-  data: {
-    obj_type: 'docx',              // 节点类型
-    node_type: 'origin',            // 固定值
-    title: '新页面',
-    // parent_node_token: 'wikcnXXX', // 可选：父节点
-  },
-});
-const node = res.data?.node;
-// node: {node_token, obj_token, obj_type, title}
-```
-
-### obj_type 取值
-
-| 值 | 说明 |
-|------|------|
-| `docx` | 新版文档（默认） |
-| `doc` | 旧版文档 |
-| `sheet` | 电子表格 |
-| `bitable` | 多维表格 |
-| `mindnote` | 思维导图 |
-| `file` | 文件 |
-| `slides` | 幻灯片 |
-
-## 移动节点
-
-```typescript
-await client.wiki.spaceNode.move({
-  path: { space_id: '7xxx', node_token: 'wikcnXXX' },
-  data: {
-    target_space_id: '7yyy',         // 目标空间（不传则同空间内移动）
-    target_parent_token: 'wikcnYYY', // 目标父节点
-  },
-});
-```
-
-## 重命名节点
-
-```typescript
-await client.wiki.spaceNode.updateTitle({
-  path: { space_id: '7xxx', node_token: 'wikcnXXX' },
-  data: { title: '新标题' },
-});
-```
-
-## Wiki-Doc 工作流（关键）
-
-知识库页面的内容读写必须通过 docx API，流程：
-
-```typescript
-// 1. 获取节点详情 → 拿到 obj_token
-const nodeRes = await client.wiki.space.getNode({
-  params: { token: wikiToken },
-});
-const objToken = nodeRes.data?.node?.obj_token;
-
-// 2. 用 obj_token 作为 doc_token 读取文档
-const contentRes = await client.docx.document.rawContent({
-  path: { document_id: objToken },
-});
-
-// 3. 用 obj_token 作为 doc_token 写入文档
-const convertRes = await client.docx.document.convert({
-  data: { content_type: 'markdown', content: '# 新内容\n\n正文...' },
-});
-await client.docx.documentBlockChildren.create({
-  path: { document_id: objToken, block_id: objToken },
-  data: { children: convertRes.data?.blocks ?? [] },
-});
-```
-
-> **重要**：不要用 `node_token` 或 URL 中的 `token` 直接调用 docx API，必须用 `getNode()` 返回的 `obj_token`。
-
-## 搜索不可用
-
-Wiki API 不提供搜索功能。获取内容需通过以下方式：
-
-- 通过 `spaceNode.list()` 浏览节点树
-- 通过 `space.getNode()` + URL 中的 token 直接查询
-
-## 知识库访问设置
-
-机器人需要被添加为知识空间成员才能访问：
-
-1. 打开知识空间 → 设置 → 成员管理
-2. 添加机器人应用
-3. 参考：https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 用 wiki URL 中的 token 直接调用 docx API | 必须先 `getNode()` 获取 `obj_token`，再用 `obj_token` 调用 docx API |
-| 列出空间返回空但实际有内容 | 机器人未被添加为空间成员 |
-| 尝试搜索知识库内容 | Wiki API 不支持搜索，只能通过 `list` 浏览或 `getNode` 查询 |
-| 创建节点忘记传 `node_type: 'origin'` | `node_type` 是必填字段，值固定为 `'origin'` |
-| 混淆 `node_token` 和 `obj_token` | `node_token` 是知识库节点标识，`obj_token` 是实际文档标识 |