Skip to content

Commit a1d446d

Browse files
hugang-larkhugang-lark
committed
docs: add vc-domain-boundaries and improve cross-domain reference enforcement
1 parent e18ea9a commit a1d446d

8 files changed

Lines changed: 215 additions & 2 deletions

File tree

‎shortcuts/vc/vc_notes.go‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,27 @@ const (
5858

5959
const logPrefix = "[vc +notes]"
6060

61+
const minutesNoReadPermissionCode = 2091005
62+
63+
func minutesReadError(err error, minuteToken string) error {
64+
var exitErr *output.ExitError
65+
if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesNoReadPermissionCode {
66+
return err
67+
}
68+
69+
return &output.ExitError{
70+
Code: output.ExitAPI,
71+
Detail: &output.ErrDetail{
72+
Type: "no_read_permission",
73+
Code: minutesNoReadPermissionCode,
74+
Message: fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken),
75+
Hint: "Ask the minute owner for minute file read permission",
76+
Detail: exitErr.Detail.Detail,
77+
},
78+
Err: err,
79+
}
80+
}
81+
6182
// validMinuteToken matches the server's minute-token format and blocks any
6283
// user-supplied token from reaching filesystem paths unsanitized.
6384
var validMinuteToken = regexp.MustCompile(`^[a-z0-9]+$`)
@@ -276,7 +297,13 @@ func fetchNoteByMinuteToken(ctx context.Context, runtime *common.RuntimeContext,
276297

277298
data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
278299
if err != nil {
279-
return map[string]any{"minute_token": minuteToken, "error": fmt.Sprintf("failed to query minutes: %v", err)}
300+
err = minutesReadError(err, minuteToken)
301+
result := map[string]any{"minute_token": minuteToken, "error": err.Error()}
302+
var exitErr *output.ExitError
303+
if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Hint != "" {
304+
result["hint"] = exitErr.Detail.Hint
305+
}
306+
return result
280307
}
281308

282309
minute, _ := data["minute"].(map[string]any)

‎shortcuts/vc/vc_search.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ func meetingSearchDescription(item map[string]interface{}) string {
172172
var VCSearch = common.Shortcut{
173173
Service: "vc",
174174
Command: "+search",
175-
Description: "Search meeting records (requires at least one filter)",
175+
Description: "Search meeting records by keyword, time range, participant, organizer, or meeting room (requires at least one filter)",
176176
Risk: "read",
177177
Scopes: []string{"vc:meeting.search:read"},
178178
AuthTypes: []string{"user"},

‎skills/lark-minutes/SKILL.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ metadata:
1212

1313
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
1414

15+
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
16+
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
17+
> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
18+
> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
19+
> 4. 了解会议总结、分析和信息提取的标准流程
20+
1521
## 核心概念
1622

1723
- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
@@ -134,6 +140,8 @@ lark-cli minutes <resource> <method> [flags] # 调用 API
134140

135141
- `get` — 获取妙记信息
136142

143+
> **权限错误**：如果返回 `[2091005] permission deny`，表示用户没有对应妙记文件的阅读权限，需提示用户联系妙记 owner 申请权限。
144+
137145
## 权限表
138146

139147
| 方法 | 所需 scope |

‎skills/lark-vc/SKILL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ metadata:
1212

1313
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
1414

15+
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
16+
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
17+
> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
18+
> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
19+
> 4. 了解会议总结、分析和信息提取的标准流程
20+
1521
## 核心概念
1622

1723
- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
@@ -29,6 +35,9 @@ metadata:
2935
3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何会议记录。
3036

3137
### 2. 整理会议纪要
38+
39+
> ⚠️ 在选择读取哪个产物前，请先确认你理解 AI 总结链路 vs 录制链路的区别。如不确定，先读 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md) 的「两条链路的独立性」章节。
40+
3241
1. 整理纪要文档时默认给出纪要文档和逐字稿链接即可，无需读取纪要文档或逐字稿内容。
3342
2. 用户明确需要获取纪要文档中的总结、待办、章节产物时，再读取文档获取具体内容。
3443
3. 读取智能纪要（`note_doc_token`）内容时，纪要文档的**第一个 `<whiteboard>`** 标签是封面图（AI 生成的总结可视化），应同时下载展示给用户：

‎skills/lark-vc/references/lark-vc-notes.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
8383
| `create_time` | 创建时间（格式化） |
8484

8585
> **选择哪个 token？** 用户说"会议纪要""总结""待办""纪要内容" → 返回 `note_doc_token` 和 `meeting_notes`（如有）。用户说"逐字稿""完整记录""谁说了什么" → 用 `verbatim_doc_token`。意图不明确时，展示所有文档链接让用户选择。
86+
>
87+
> 📌 不确定该返回哪个 token？参见 [`vc-domain-boundaries.md`](vc-domain-boundaries.md) 的产物链路对比表，了解 AI 总结链路 vs 录制链路的区别。
8688
8789
### minute-tokens 路径的 AI 产物
8890

‎skills/lark-vc/references/lark-vc-search.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@ lark-cli vc +search --query "周会" --page-size 15 --page-token "<PAGE_TOKEN>"
157157

158158
## 搜索结果中的下一步
159159

160+
> 📌 不确定接下来该用 `+notes` 还是 `+recording`？参见 [`vc-domain-boundaries.md`](vc-domain-boundaries.md) 的产物链路对比表，了解 AI 总结链路 vs 录制链路的区别。
161+
160162
搜索结果中的 `meeting_id` 可直接用于继续查询会议纪要或妙记：
161163

162164
```bash

‎skills/lark-vc/references/vc-domain-boundaries.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Calendar/VC/Doc 跨领域关联关系、领域知识和职责边界说明
2+
3+
本文档说明飞书日历（Calendar）、视频会议（VC）、云文档（Doc）三个域之间的关联关系，帮助理解跨域数据流转和产物依赖。
4+
5+
## Calendar 域
6+
7+
- **lark-calendar skill** 负责日历与日程管理，包括创建、查询、修改、删除日程等操作。
8+
- **日程与会议的关系**：日程可以用于提前预约会议，确定会议时间、参与人、会议室、会议主题等信息。日程上可以关联飞书/Lark 视频会议。
9+
- **并非所有会议都通过日程发起**：即时会议不经过日程预约，直接创建。因此，仅查询日程数据无法覆盖所有会议，搜索历史会议应优先使用 `vc +search`。
10+
- **日程上的用户会议纪要**：用户可以在日程上绑定自己的会议纪要文档（MeetingNotes），用于手动记录会议相关信息。该文档与 AI 生成的智能纪要（`note_doc_token`）是不同的文档，相互独立。
11+
12+
> **路由规则**：查询过去已结束的会议 → `lark-vc`；查询未来日程/待开的会 → `lark-calendar`；查询"今天有哪些会议" → 两者结合（`vc +search` 查已结束 + `calendar` 查未开始）。
13+
14+
## VC 域
15+
16+
- **lark-vc skill** 负责视频会议管理，包括搜索历史会议、查询会议产物（智能纪要、逐字稿、妙记等）、查询参会人快照等操作。
17+
- **会议类型**：会议可以是日程会议（由日程发起，有对应的 `calendar_event_id`），也可以是即时会议等其他类型。
18+
19+
### 会议产物
20+
21+
会议产物取决于会中开启的功能，分为两条独立链路：
22+
23+
#### 链路一：开启「AI 总结」
24+
25+
会中开启「AI 总结」功能后，产生以下产物：
26+
27+
| 产物 | Token 字段 | 本质 | 说明 |
28+
|------|-----------|------|------|
29+
| 智能纪要 | `note_doc_token` | 飞书文档 | AI 生成的会议总结与待办 |
30+
| 逐字稿 | `verbatim_doc_token` | 飞书文档 | 完整的逐句发言记录（含说话人、时间戳） |
31+
| 共享文档 | `shared_doc_token` | 飞书文档 | 会中投屏共享的文档信息 |
32+
33+
此外，还存在**用户会议纪要（MeetingNotes）**，对应 `meeting_notes` 字段。这是用户主动绑定到会议的纪要文档，通常用于会前记录会议相关内容，与智能纪要文档相互独立。仅通过 `+notes --calendar-event-ids` 路径返回。
34+
35+
#### 链路二：开启「录制」
36+
37+
会中开启「录制」功能后，产生**妙记产物**（`minute_token`），妙记本身包含以下子产物：
38+
39+
| 子产物 | 说明 |
40+
|--------|------|
41+
| Summary（总结） | 对整场会议的智能总结 |
42+
| Todo（待办） | 会议中识别出的待处理任务列表 |
43+
| Chapter（章节） | 按讨论话题划分的核心内容摘要 |
44+
| Transcript（文字记录） | 整场会议最原始的逐人发言记录 |
45+
46+
#### 两条链路的独立性
47+
48+
- 智能纪要（AI 总结链路）和妙记（录制链路）**相互独立、互不影响**。
49+
- 一场会议可能同时拥有两类产物，也可能只有其中一类，也可能都没有。
50+
- 当两者都存在时，Summary/Todo 内容可能重叠，应根据用户意图选择优先读取哪个。
51+
52+
> **产物选择决策**：智能总结、待办、章节都属于 AI 分析产物，可能只包含最终结论和关键信息，完整的会议信息仍需从逐字稿/文字记录中获取。可根据用户诉求判断使用哪一种类型的产物。如果用户没有明确偏好，对于重复的内容（如智能总结、待办），**优先查询智能纪要（Note），不存在时再降级到妙记（Minutes）**。
53+
54+
#### 逐字稿与文字记录的格式
55+
56+
智能纪要的逐字稿（`verbatim_doc_token`）和妙记的文字记录（Transcript）都记录了用户原始对话内容，格式一致：
57+
58+
```
59+
发言人名称 相对时间戳
60+
<发言内容>
61+
```
62+
63+
示例：
64+
65+
```
66+
张三 00:00:00.195
67+
我们接下来讨论一下项目进度。
68+
```
69+
70+
- 第一行为发言人信息，包含用户名称和发言的相对时间（从会议开始计算的偏移量）。
71+
- 后续行为该发言人的发言内容，直到下一个发言人标记出现。
72+
73+
### 会议总结和分析流程
74+
75+
#### Step 1: 定位会议
76+
77+
根据关键字、组织者、参与人、会议室等条件搜索会议，获取会议列表。
78+
79+
```bash
80+
lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json
81+
```
82+
83+
详细用法请阅读 [`lark-vc-search.md`](lark-vc-search.md)。
84+
85+
#### Step 2: 根据 meeting_id 查询产物
86+
87+
##### 获取会议纪要产物
88+
89+
```bash
90+
lark-cli vc +notes --meeting-ids '<meeting_id1>,<meeting_id2>'
91+
```
92+
93+
可获取智能纪要（`note_doc_token`）、逐字稿（`verbatim_doc_token`）、共享文档（`shared_doc_token`）等文档 Token。详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
94+
95+
其中：
96+
- **智能纪要**包含 AI 生成的总结和待办信息
97+
- **逐字稿**包含完整的会中发言记录
98+
99+
文档正文内容需通过 Doc 域读取（见 Step 3）。
100+
101+
##### 获取妙记产物（录制链路）
102+
103+
1. 查询妙记基本信息，获取 `minute_token`：
104+
105+
```bash
106+
lark-cli vc +recording --meeting-ids '<meeting_id1>,<meeting_id2>'
107+
```
108+
109+
详细用法请阅读 [`lark-vc-recording.md`](lark-vc-recording.md)。
110+
111+
2. 通过 `minute_token` 获取妙记产物内容：
112+
113+
```bash
114+
lark-cli vc +notes --minute-tokens '<minute_token1>,<minute_token2>'
115+
```
116+
117+
可获取妙记的总结、待办、章节、文字记录等信息。详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
118+
119+
#### Step 3: Doc 域拉取文档内容
120+
121+
智能纪要和逐字稿都是飞书文档，需使用 `docs +fetch` 读取正文内容：
122+
123+
```bash
124+
lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
125+
```
126+
127+
详细用法请参考 [lark-doc](../../lark-doc/SKILL.md) skill。
128+
129+
#### Step 4: 判断用户需要的产物内容
130+
131+
- 根据用户诉求（总结/待办/章节/完整发言记录等），选择合适的产物进行分析和信息提取
132+
- 如果两种产物都不存在或没有权限，需如实告知用户
133+
134+
## Doc 域
135+
136+
- **lark-doc skill** 负责飞书云文档管理，包括获取文档元信息、读取文档内容、创建和编辑文档等操作。
137+
- **会议产物的文档本质**：智能纪要（`note_doc_token`）、逐字稿（`verbatim_doc_token`）都是飞书文档，需要通过 `lark-doc` 的 API（如 `docs +fetch`）查询其内容和元信息。
138+
- **文档元信息查询**：获取文档名称、URL 等基本信息时，使用 `drive metas batch_query`；获取文档正文内容时，使用 `docs +fetch --api-version v2`。
139+
140+
## 三域关联总览
141+
142+
```
143+
Calendar (日程) ──── 发起预约 ────► VC (会议)
144+
│
145+
┌──────────────────┤
146+
│ │
147+
AI 总结链路 录制链路
148+
│ │
149+
▼ ▼
150+
智能纪要 (Doc) 妙记 (Minutes)
151+
逐字稿 (Doc) ├── Summary
152+
共享文档 (Doc) ├── Todo
153+
用户纪要 (Doc) ├── Chapter
154+
└── Transcript
155+
```
156+
157+
- Calendar 提供会议预约入口，但并非所有会议都来自日程。
158+
- VC 是会议数据的中心，管理会议记录和产物关联。
159+
- Doc 是会议产物的载体，智能纪要和逐字稿都以飞书文档形式沉淀，需通过 Doc 域 API 读取。

‎skills/lark-workflow-meeting-summary/SKILL.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ metadata:
1111

1212
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**。然后阅读 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)，了解会议纪要相关操作。
1313

14+
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
15+
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
16+
> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
17+
> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
18+
> 4. 了解会议总结、分析和信息提取的标准流程
19+
1420
## 适用场景
1521

1622
- "帮我整理这周的会议纪要" / "总结最近的会议" / "生成会议周报"

0 commit comments

Comments
 (0)