@lark-apaas/coding-steering 0.1.6-alpha.1 → 0.1.6-alpha.11

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

@@ -0,0 +1,90 @@
+# 权限管理 (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

@@ -0,0 +1,164 @@
+# 知识库 (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` 是实际文档标识 |

package/steering/nestjs-react-fullstack/skills/openapi-guide/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: openapi-guide
+description: "OpenAPI 对外开放接口编码规范 + docs/openapi.json 产物维护。覆盖鉴权、用户身份、模块组织、OpenAPI 3.0 JSON 的结构与写入规则。Use when: 创建或修改 /openapi 路由、编写对外开放接口、维护 docs/openapi.json。触发词：openapi, 开放接口, 对外接口, 对外 API, open api, openapi controller, docs/openapi.json"
+steering: true
+steering-inclusion: fileMatch
+steering-topic: openapi_guide
+match-template-name: nestjs-react-fullstack
+file-match-pattern:
+  - "**/*.openapi.controller.ts"
+---
+
+# OpenAPI 对外开放接口编码规范
+
+本规范适用于以 `/openapi` 为前缀的对外开放接口。**除下述差异外，均遵循 `/api` 的接口编码规范**。与 `/api` 的差异速查：
+
+| 维度 | `/api`（内部业务接口） | `/openapi`（对外开放接口） |
+|------|----------------------|--------------------------|
+| 鉴权 | 写操作加 `@NeedLogin()` | **不加** `@NeedLogin()`，鉴权在网关层通过 API Key 完成 |
+| 用户身份 | `req.userContext.userId` 区分用户 | 统一走系统身份，不依赖 `userId` 做业务区分 |
+| Controller 文件 | `xxx.controller.ts` | `xxx.openapi.controller.ts`，放在同一 module 下 |
+| OpenAPI 文档 | 不需要 | **必须**同步维护 `docs/openapi.json`（见下文） |
+
+## 鉴权
+
+`/openapi` 路由的鉴权完全在网关层通过 API Key 完成，Controller 层不需要任何鉴权相关代码。
+
+```typescript
+// ✅ 正确：/openapi 路由不加鉴权装饰器
+@Controller('openapi/orders')
+export class OpenApiOrdersController {
+  @Post()
+  create(@Body() body: CreateOrderRequest) { ... }
+}
+
+// ❌ 错误：给 /openapi 路由加 @NeedLogin()
+@Controller('openapi/orders')
+export class OpenApiOrdersController {
+  @NeedLogin()  // 不需要！
+  @Post()
+  create(@Body() body: CreateOrderRequest) { ... }
+}
+```
+
+## 用户身份
+
+OpenAPI 场景下不区分用户，统一走系统身份。禁止在 `/openapi` Controller 中使用 `req.userContext.userId` 做业务逻辑区分。
+
+```typescript
+// ✅ 正确：不依赖用户身份
+@Get()
+findAll(@Query() query: FindOrdersQuery) {
+  return this.ordersService.findAll(query);
+}
+
+// ❌ 错误：用 userId 过滤数据
+@Get()
+findAll(@Req() req: Request) {
+  return this.ordersService.findByUser(req.userContext.userId);  // OpenAPI 下无意义
+}
+```
+
+## 模块组织
+
+`/openapi` Controller 和 `/api` Controller 放在**同一个 module** 下，共享 Service 层。用文件名 `xxx.openapi.controller.ts` 区分。
+
+```
+modules/orders/
+├── orders.module.ts              # 同时注册两个 Controller
+├── orders.controller.ts          # @Controller('api/orders')      — 内部接口
+├── orders.openapi.controller.ts  # @Controller('openapi/orders')  — 开放接口
+└── orders.service.ts             # 共享业务逻辑
+```
+
+在 `orders.module.ts` 中注册：
+```typescript
+@Module({
+  controllers: [OrdersController, OpenApiOrdersController],
+  providers: [OrdersService],
+})
+export class OrdersModule {}
+```
+
+## OpenAPI 文档产物（必须维护）
+
+整个应用所有 `/openapi` 路由**汇总在一份** `docs/openapi.json` 文件里（仓库根目录）。
+
+- 路径 = 仓库根 `docs/openapi.json`
+- 所有 `*.openapi.controller.ts` 的 endpoint 共享这一个文件的 `paths`
+- 新仓库若没有该文件，Agent 自行创建
+- 该文件是对外 OpenAPI 的**权威 spec**（运行时被读取并对外暴露，不是纯文档）——精确性要求高，写错/漏写会直接影响外部调用方
+- 内部 `/api` 路由**不**写进来
+
+## 何时创建/更新
+
+| 修改场景 | 文档动作 |
+|---|---|
+| 新建 `*.openapi.controller.ts` | 在 `docs/openapi.json` 的 `paths` 下新增对应 path 项 |
+| 已有 openapi controller 上增删 endpoint、改方法/路径/参数 | 精准增删/改对应 `paths["/openapi/..."]` 条目 |
+| 修改 `shared/api.interface.ts` 里被 openapi 路由引用的 interface / type | 同步更新所有受影响 path 的 schema |
+| 修改 service 返回值或 drizzle schema，且类型变化反映到 openapi 路由的响应 | 同步更新对应 path 的 responses schema |
+
+> 编辑 service / interface / schema 时本 skill 不会被 file-match 自动注入；此时 `coding-guide` 的 `## API 规范` 第 8 条会提醒 Agent 主动加载本 skill 完成同步。
+
+## 安全更新协议（避免误删其它 path）
+
+单文件聚合场景下最大的风险是 Agent 编辑某个 path 时意外丢掉其它 controller 的 path。**必须**按以下步骤：
+
+1. **先 Read**：完整读入 `docs/openapi.json`
+2. **再 Edit**：用精确 `Edit` 改特定 `"/openapi/<path>": { ... }` 块，不要 `Write` 全文件
+3. **最后自检**：见末尾「写后自检」小节——确认 `paths` 下所有条目都在、且每条都有 `operationId` + `responses`
+
+## 文件格式
+
+顶层结构**固定**：
+
+```json
+{
+  "paths": {
+    "/openapi/<feature>": { <pathItem> },
+    "/openapi/<feature>/{id}": { <pathItem> }
+  }
+}
+```
+
+硬性规定：
+
+- **path 键**写完整绝对路径（含 `/openapi/` 前缀），与 `@Controller(...)` + `@Get/Post/...(...)` 拼接结果一致
+- **不**放 `basePath`、**不**放 `components`、**不**放 `info`/`servers`——所有 schema 内联，中间件会补齐其它顶层字段
+- 每个 operation 对象**必须**有：`operationId`（= controller 方法名，驼峰）、`summary`（一句中文说明）、`responses`（至少 `"200"`）
+- 路径参数、查询参数、请求体、响应体的位置由 controller 装饰器决定（见下）
+- 同一 URL 上的多个 HTTP 方法共用一个 path 键（如 `@Controller('openapi/tickets')` 下的 `@Post()` 与 `@Get()` 都映射到 `/openapi/tickets`，共享 pathItem）
+
+## Controller 装饰器 → OpenAPI 位置
+
+**位置看装饰器，类型看 TS**——两者缺一不可。
+
+| Nest 装饰器 | OpenAPI 位置 | 备注 |
+|---|---|---|
+| `@Body() body: T` | `requestBody.content['application/json'].schema` = `T` 的 schema | `T` 通常是 `shared/api.interface.ts` 的 interface |
+| `@Query('foo') foo: T` | `parameters[]` 一项：`in: 'query'`, `name: 'foo'`, `schema: T`；`?` → `required: false` | 每个 `@Query('x')` 产一项 |
+| `@Query() q: T` | `parameters[]` 每字段一项：`in: 'query'`, `name: <field>`, `schema: <field 类型>` | 整个 interface 被摊平到 query params |
+| `@Param('id') id: T` | `parameters[]` 一项：`in: 'path'`, `name: 'id'`, **`required: true`**, `schema: T` | path 参数恒 `required: true` |
+| `@Headers('x-foo') v: T` | `parameters[]` 一项：`in: 'header'`, `name: 'x-foo'`, `schema: T` | `X-Api-Key` 等鉴权头走网关层，不写进 spec |
+
+## Schema 权威来源
+
+对外接口的请求/响应类型统一在 `shared/api.interface.ts` 用 TS `interface` / `type` 维护，前后端共享。
+
+三层优先级（从高到低）：
+
+1. **`shared/api.interface.ts` 中的 TS interface** — 请求体类型 / controller 返回值类型的唯一权威。从 controller 方法签名找到对应 interface 名称，再递归展开成 JSON Schema。
+2. **controller 方法签名** — 各参数的 TS 类型与方法返回值类型，就是对应 OpenAPI 位置的 schema 来源（装饰器到 OpenAPI 位置的映射见上表）。类型可以是 `shared/api.interface.ts` 里的 interface、primitive、或 controller 文件内的内联类型声明；方法返回值类型即 OpenAPI 响应 schema 所描述的对象。
+3. **drizzle schema** — 仅作字段底层类型的辅助参考；**绝不**用来扩展 interface 里没有的字段（interface 已显式定义对外字段集合；drizzle 里多出来的内部字段如 `userId`/`internalRemark` 不得出现在 `docs/openapi.json` 里）。
+
+若 service 实现与 interface 脱节，属代码 bug；JSON schema 一律以 interface 为准。
+
+## TS → JSON Schema 映射
+
+| TS 写法 | JSON Schema |
+|---|---|
+| `foo: string` | `{ "type": "string" }`，`"foo"` 进 `required` |
+| `foo?: string` / `foo: string \| undefined` | `{ "type": "string" }`，**不**进 `required` |
+| `foo: number` | `{ "type": "number" }` 或 `"integer"`（看 drizzle 是 `integer()` 还是 `real()`） |
+| `foo: boolean` | `{ "type": "boolean" }` |
+| `type X = 'a' \| 'b' \| 'c'` 或直接字面量联合 | `{ "type": "string", "enum": ["a","b","c"] }` |
+| `foo: SomeInterface` | 递归展开 `{ "type": "object", "required": [...], "properties": { ... } }` |
+| `foo: T[]` | `{ "type": "array", "items": <T 的 schema> }` |
+| `foo: Date` | `{ "type": "string", "format": "date-time" }`（序列化多为 ISO 字符串） |
+| `foo: T \| null`（可空，非"可选"） | 在 `T` 的 schema 上加 `"nullable": true`；`"foo"` 仍进 `required` |
+
+## `required` 三个位置
+
+OpenAPI 3.0 里 `required` 按上下文有三种写法，判定依据**统一是 TS `?` 修饰符**。
+
+| 上下文 | 写法 | 放在哪 |
+|---|---|---|
+| Parameter Object（query/path/header） | `"required": true/false` | 参数对象顶层 |
+| RequestBody Object（请求体整体） | `"required": true` | requestBody 顶层 |
+| Object Schema（对象字段） | `"required": ["field1","field2"]` 字段名数组 | object schema 顶层，**不**在每个 property 内 |
+
+## description 与 example
+
+TS interface 本身不带 `description` 和 `example`。**按字段名语义自行生成**，不改 interface 源码或加 JSDoc hack。
+
+- `description`：一句中文解释，聚焦业务含义，别复述类型
+- `example`：选一个**真实合理**的值（`"13800000000"` 而不是 `"xxx"`）
+
+## 深层嵌套省略规则
+
+响应/请求结构很深时允许偷懒：
+
+- **第一层 properties** — 永远不省略
+- **深层嵌套对象** — 允许只写 `{ "type": "object" }` 不列 properties，但**必须**在这一层写 `example`（swagger-ui 合成不到深层）
+- **展开了 properties 的 object** — 不写顶层 `example`（swagger-ui 会从 property-level 合成）
+- **primitive 字段**（string/number/boolean） — 必须写 property-level `example`
+- **数组** — `items` 写一个元素的 schema + example，数组外层不写 `example`（由 `items` 合成）
+
+## 规则表讲不透的片段示例
+
+TS interface 怎么翻译、装饰器映射到 parameter 的哪个 `in`、`required` 怎么标——全部看上面各节的表。**本节只示范规则表替代不了的 3 件事**：混用装饰器形成的 parameters 数组、第一层完整展开 vs 深层对象省略的对照、description / example 的风格。
+
+```json
+{
+  "paths": {
+    "/openapi/tickets/{assigneeId}": {
+      "get": {
+        "operationId": "listByAssignee",
+        "summary": "按受理人查询工单列表（游标分页）",
+        "parameters": [
+          { "in": "path",  "name": "assigneeId", "required": true,
+            "schema": { "type": "string" }, "description": "受理人 ID", "example": "usr_007" },
+          { "in": "query", "name": "priority", "required": false,
+            "schema": { "type": "string", "enum": ["low","normal","urgent"] },
+            "description": "按优先级过滤", "example": "urgent" },
+          { "in": "query", "name": "cursor", "required": false,
+            "schema": { "type": "string" },
+            "description": "游标（首次请求省略）", "example": "tk_abc" }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["items", "hasMore"],
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "description": "Ticket 详情（深层省略，schema 见 example）",
+                        "example": {
+                          "id": "tk_abc", "title": "空调故障报修", "priority": "urgent",
+                          "assigneeCount": 2, "location": { "building": "A 栋", "floor": 3 }
+                        }
+                      }
+                    },
+                    "nextCursor": { "type": "string", "description": "下一页游标（最后一页省略）", "example": "tk_abc" },
+                    "hasMore": { "type": "boolean", "description": "是否还有下一页", "example": true }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+要点：
+
+- **装饰器混用 → parameters 数组**：`@Param('assigneeId') + @Query('priority') + @Query('cursor')` 合并成 3 项 parameter，path 参数 `required: true`、query 参数 `required: false`
+- **第一层完整展开 + 深层对象省略**：响应外层对象展开，`items` / `hasMore` 进 `required` 数组而 `nextCursor` 不进；数组元素是 `Ticket`，这一层用深层省略——`type: 'object'` + `example` 示范元素结构，不重复翻译 Ticket 的 schema
+- **description / example 风格**：一句中文语义（"按优先级过滤" 而非"过滤参数"）、真实合理值（`"usr_007"` / `"tk_abc"` / `"A 栋"`，不是 `"xxx"` / `"foo"`）
+
+## 写后自检（强制）
+
+每次 Write/Edit 完 `docs/openapi.json` 之后，**必须**立即在项目根执行下面这条自检命令。未通过要当场修到通过为止，才视为本次任务完成：
+
+```bash
+node -e "const M=['get','post','put','patch','delete','head','options'];const s=require('fs').readFileSync('docs/openapi.json','utf8');const o=JSON.parse(s);if(!o.paths||typeof o.paths!=='object')throw new Error('missing paths');for(const [p,item] of Object.entries(o.paths))for(const [m,op] of Object.entries(item)){if(!M.includes(m))continue;if(!op.operationId||!op.responses)throw new Error(p+' '+m+' missing operationId/responses');}console.log('ok, '+Object.keys(o.paths).length+' paths');"
+```
+
+覆盖：JSON 语法错 / 顶层缺 `paths` / 某个 operation 缺 `operationId` 或 `responses`；最后打印 path 数量方便和修改前做比对，防止误删。