Skip to content

fix: add vc-domain-boundaries and enrich vc +notes#1172

Open
hugang-lark wants to merge 1 commit into
mainfrom
feat/vc_event
Open

fix: add vc-domain-boundaries and enrich vc +notes#1172
hugang-lark wants to merge 1 commit into
mainfrom
feat/vc_event

Conversation

@hugang-lark
Copy link
Copy Markdown
Collaborator

@hugang-lark hugang-lark commented May 29, 2026

Summary

Add a Calendar/VC/Doc cross-domain boundaries document and consequence-driven CRITICAL references across the lark-vc / lark-minutes / lark-workflow-meeting-summary skills, and harden the vc +notes shortcut so meeting-id queries also surface the minute_token and translate common API error codes into actionable hints. This prevents AI agents from skipping domain knowledge or making wrong artifact selections, and gives callers a single, structured response that covers both the AI-summary and recording pipelines in one shot.

Changes

  • Add skills/lark-vc/references/vc-domain-boundaries.md: Calendar/VC/Doc relationships, the two independent meeting artifact pipelines, artifact selection rules, transcript format, and the 4-step meeting summary workflow.
  • Add consequence-driven CRITICAL references and cross-links in lark-vc/SKILL.md, lark-minutes/SKILL.md, lark-workflow-meeting-summary/SKILL.md, lark-vc-notes.md, and lark-vc-search.md so key decision points point to the boundaries doc.
  • Add [2091005] permission deny handling tip for minutes.get in lark-minutes/SKILL.md.
  • Enrich vc +notes (shortcuts/vc/vc_notes.go): reverse-lookup minute_token via the recording API on the --meeting-ids / --calendar-event-ids paths, merge note-side and minute-side failures into a single ; -joined error field, and translate notes 121005 / recording 121004·121005·124002 / minutes 2091005 into friendly hints; update the docs and dry-run output accordingly.

Test Plan

  • make unit-test passes
  • Manually verify lark-cli vc +search, lark-cli vc +notes, and lark-cli minutes minutes get behave as expected (including the new minute_token field and the friendly error hints)

Related Issues

  • None

Summary by CodeRabbit

  • New Features

    • Meeting notes now automatically fetch minute tokens from recording API when querying by meeting IDs or calendar event IDs.
    • Permission-aware error handling with user-friendly hints when lacking read access.
  • Improvements

    • Partial results (note or minute data) now count as successful shortcut executions.
    • Enhanced search shortcut description clarifying available filters.
  • Documentation

    • Added domain boundary guide detailing calendar, VC, and notes interactions.
    • Updated required scopes for meeting ID and calendar event queries.
    • Added pre-start requirements for lark-minutes and meeting summary skills.

Review Change Stack

@hugang-lark hugang-lark added documentation Improvements or additions to documentation domain/vc PR touches the vc domain labels May 29, 2026
@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@github-actions github-actions Bot added the size/L Large or sensitive change across domains or core paths label May 29, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 29, 2026

📝 Walkthrough

Walkthrough

This PR extends the vc +notes shortcut to retrieve minute-tokens from the recording API, merges note-detail and minute-token results with shared error reporting, treats results as successful when containing any note/minute payload, and adds permission-aware error handling. It establishes comprehensive cross-domain documentation clarifying Calendar/VC/Doc boundaries and meeting artifact chains, with prerequisite reading gates across related skills.

Changes

VC Meeting Note Artifact Retrieval

Layer / File(s) Summary
Minute-token permission-denied error wrapper
shortcuts/vc/vc_notes.go
Adds error code constants and minutesReadError that wraps minute-read permission failures into structured output.ExitError with a no_read_permission type and user-facing hint; propagates hint into minute-token results.
Recording API minute-token fetching
shortcuts/vc/vc_notes.go
Introduces fetchMeetingMinuteToken to query /recording, extract minute_token from recording URLs, and map known recording error codes (121004/121005/124002) to user-facing messages.
Merged note+minute fetch and success criteria
shortcuts/vc/vc_notes.go
Reworks fetchNoteByMeetingID to always call recording API for minute_token, optionally fetch note detail, merge note/minute failures via joinErrors, and use hasNotesPayload to mark partial payloads as successful. Updates fetchNoteByCalendarEventID success logic accordingly.
Scope requirements, note-permission handling, and dry-run updates
shortcuts/vc/vc_notes.go
Adds vc:note:read and vc:record:readonly to required scopes for relevant input modes, maps note-detail permission-deny to a specific message, and updates DryRun steps to include recording API/minute-token retrieval.
Test coverage for minute-token fetching and merged flow
shortcuts/vc/vc_notes_test.go
Adds unit tests for joinErrors and hasNotesPayload, recording API stubs and fetchMeetingMinuteToken tests (success, known error codes, generic failures, missing/malformed data), and integration tests for combined +notes --meeting-ids outcomes including permission-denied hint propagation.
Cross-domain boundaries and artifact retrieval documentation
skills/lark-vc/references/vc-domain-boundaries.md
New canonical reference documenting Calendar↔VC↔Doc domain boundaries, product/token mappings (AI summaries vs recordings/minutes), retrieval workflows, transcript expectations, and selection guidance between AI summary and recording chains.
Skill prerequisites and cross-references to domain boundaries
skills/lark-minutes/SKILL.md, skills/lark-vc/SKILL.md, skills/lark-workflow-meeting-summary/SKILL.md, skills/lark-vc/references/lark-vc-notes.md
Adds mandatory pre-start reading of vc-domain-boundaries.md across skills, documents permission guidance for minute-read code 2091005, expands +notes --meeting-ids scope docs, and clarifies minute_token auto-retrieval via recording API.

Search Shortcut Filter Description

Layer / File(s) Summary
Search shortcut filter documentation
shortcuts/vc/vc_search.go
Updates VCSearch shortcut Description to explicitly enumerate supported filters (keyword, time range, participant, organizer, meeting room) while preserving the "requires at least one filter" requirement.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

  • larksuite/cli#333: Both PRs modify shortcuts/vc/vc_notes.go in the --calendar-event-ids/fetchNoteByCalendarEventID flow; related to note token extraction and merged-error handling.
  • larksuite/cli#246: Prior work on meeting-recording/meeting_id → minute_token resolution that this PR builds upon.
  • larksuite/cli#591: Related minutes skill documentation and minute-token semantics that align with this PR's recording/minute handling.

Suggested reviewers

  • zhaoleibd
  • zhicong666-bytedance
  • zhangjun-bytedance

Poem

🐰 The CLI hops, it reads both note and minute,
Errors joined like seeds in a row,
Domain maps guide the curious sprite,
Partial payloads earn their glow. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 48.28% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: adding a vc-domain-boundaries document and enriching the vc +notes feature with improved error handling and minute_token support.
Description check ✅ Passed The description comprehensively covers all required template sections: a clear summary of motivation, a detailed list of main changes across multiple files, a test plan with specific verification steps, and related issues.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/vc_event

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
skills/lark-vc/references/vc-domain-boundaries.md (1)

58-68: ⚡ Quick win

Add language identifiers to code blocks for better rendering.

The code blocks at lines 58-68 (transcript format examples) and lines 142-155 (domain relationship diagram) are missing language identifiers, which can cause inconsistent rendering across markdown processors.

📝 Proposed fix
-```
+```text
 发言人名称 相对时间戳
 <发言内容>

Apply the same fix to the example at lines 65-68 and the diagram at lines 142-155:

```diff
-```
+```text
 Calendar (日程) ──── 发起预约 ────► VC (会议)
 ...
</details>


Also applies to: 142-155

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @skills/lark-vc/references/vc-domain-boundaries.md around lines 58 - 68, The
shown Markdown code blocks for the transcript example ("发言人名称 相对时间戳\n<发言内容>" /
example "张三 00:00:00.195\n我们接下来讨论一下项目进度。") and the domain relationship diagram
("Calendar (日程) ──── 发起预约 ────► VC (会议) ...") lack language identifiers; update
their fences from totext for both the transcript block and the diagram
block so they render consistently across processors (locate the blocks
containing the exact strings "发言人名称 相对时间戳" and "Calendar (日程) ──── 发起预约 ────► VC
(会议)" and replace the opening triple backticks with ```text).


</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @skills/lark-vc/references/vc-domain-boundaries.md:

  • Around line 58-68: The shown Markdown code blocks for the transcript example
    ("发言人名称 相对时间戳\n<发言内容>" / example "张三 00:00:00.195\n我们接下来讨论一下项目进度。") and the
    domain relationship diagram ("Calendar (日程) ──── 发起预约 ────► VC (会议) ...") lack
    language identifiers; update their fences from totext for both the
    transcript block and the diagram block so they render consistently across
    processors (locate the blocks containing the exact strings "发言人名称 相对时间戳" and
    "Calendar (日程) ──── 发起预约 ────► VC (会议)" and replace the opening triple backticks
    with ```text).

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `e81d6c81-595f-4e99-9a29-77935e08a415`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between e18ea9a2e824472c41c279ee80933a5d559a3d86 and a1d446d4df26e534f59e35cd85fd6e2a8596ba46.

</details>

<details>
<summary>📒 Files selected for processing (8)</summary>

* `shortcuts/vc/vc_notes.go`
* `shortcuts/vc/vc_search.go`
* `skills/lark-minutes/SKILL.md`
* `skills/lark-vc/SKILL.md`
* `skills/lark-vc/references/lark-vc-notes.md`
* `skills/lark-vc/references/lark-vc-search.md`
* `skills/lark-vc/references/vc-domain-boundaries.md`
* `skills/lark-workflow-meeting-summary/SKILL.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 29, 2026

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@6398a9ea9d88a546334fd835285f4e5a9e73994e

🧩 Skill update

npx skills add larksuite/cli#feat/vc_event -y -g

@codecov
Copy link
Copy Markdown

codecov Bot commented May 29, 2026

Codecov Report

❌ Patch coverage is 74.68354% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.95%. Comparing base (b1ecf2d) to head (6398a9e).

Files with missing lines Patch % Lines
shortcuts/vc/vc_notes.go 74.68% 20 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1172      +/-   ##
==========================================
+ Coverage   68.92%   68.95%   +0.02%     
==========================================
  Files         629      629              
  Lines       58762    58832      +70     
==========================================
+ Hits        40503    40567      +64     
- Misses      14952    14960       +8     
+ Partials     3307     3305       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@hugang-lark hugang-lark changed the title docs: add vc-domain-boundaries and improve cross-domain reference enforcement fix: add vc-domain-boundaries and improve +notes cmd May 29, 2026
@hugang-lark hugang-lark changed the title fix: add vc-domain-boundaries and improve +notes cmd fix: add vc-domain-boundaries and enrich vc +notes May 29, 2026
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
skills/lark-vc/references/vc-domain-boundaries.md (2)

58-68: ⚡ Quick win

Add language identifier to fenced code blocks.

The code blocks showing transcript format examples should specify a language identifier for proper Markdown rendering.

📝 Proposed fix to add language identifiers
-```
+```text
 发言人名称 相对时间戳
 <发言内容>

示例:

- +text
张三 00:00:00.195
我们接下来讨论一下项目进度。

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-vc/references/vc-domain-boundaries.md` around lines 58 - 68, The
fenced code blocks showing the transcript format (the block starting with "发言人名称
相对时间戳" and the example block starting with "张三 00:00:00.195") need a language
identifier for proper Markdown rendering; update both triple-backtick fences to
use "text" (i.e., change ``` to ```text) so the blocks explicitly declare the
language and render correctly.

142-155: ⚡ Quick win

Add language identifier to ASCII diagram code block.

The code block containing the ASCII diagram should specify a language identifier for proper Markdown rendering.

📝 Proposed fix to add language identifier
-```
+```text
 Calendar (日程) ──── 发起预约 ────► VC (会议)
                                        │
                     ┌──────────────────┤
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-vc/references/vc-domain-boundaries.md` around lines 142 - 155,
The ASCII diagram code block in vc-domain-boundaries.md lacks a language
identifier; update the fenced code block that starts with the diagram (the
triple-backtick block containing "Calendar (日程) ──── 发起预约") to include a
language tag such as "text" (i.e., change ``` to ```text) so Markdown renderers
treat it as preformatted text and preserve the diagram formatting.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/vc/vc_notes.go`:
- Around line 778-787: The success counting incorrectly treats echoed
minute_token entries as successes because hasNotesPayload sees a non-empty
"minute_token"; modify the successCount logic in Execute to be mode-aware: when
running the --minute-tokens path (the mode enforced by Execute/ExactlyOne),
count a result as successful only if the result map from fetchNoteByMinuteToken
contains no non-nil "error" (or error == nil), otherwise for the other paths
keep the existing hasNotesPayload check; update the loop over results (where
successCount is computed) to branch on the mode and check
r.(map[string]any)["error"] for minute-token mode so the all-failed exit and
summary match the per-row FAIL statuses, and re-run hasNotesPayload/minute-token
tests.

---

Nitpick comments:
In `@skills/lark-vc/references/vc-domain-boundaries.md`:
- Around line 58-68: The fenced code blocks showing the transcript format (the
block starting with "发言人名称 相对时间戳" and the example block starting with "张三
00:00:00.195") need a language identifier for proper Markdown rendering; update
both triple-backtick fences to use "text" (i.e., change ``` to ```text) so the
blocks explicitly declare the language and render correctly.
- Around line 142-155: The ASCII diagram code block in vc-domain-boundaries.md
lacks a language identifier; update the fenced code block that starts with the
diagram (the triple-backtick block containing "Calendar (日程) ──── 发起预约") to
include a language tag such as "text" (i.e., change ``` to ```text) so Markdown
renderers treat it as preformatted text and preserve the diagram formatting.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e8ce7a08-f8ac-41fd-af75-f6c29bdf9e58

📥 Commits

Reviewing files that changed from the base of the PR and between a1d446d and 6dc95c7.

📒 Files selected for processing (8)
  • shortcuts/vc/vc_notes.go
  • shortcuts/vc/vc_notes_test.go
  • shortcuts/vc/vc_search.go
  • skills/lark-minutes/SKILL.md
  • skills/lark-vc/SKILL.md
  • skills/lark-vc/references/lark-vc-notes.md
  • skills/lark-vc/references/vc-domain-boundaries.md
  • skills/lark-workflow-meeting-summary/SKILL.md
✅ Files skipped from review due to trivial changes (3)
  • shortcuts/vc/vc_search.go
  • skills/lark-vc/SKILL.md
  • skills/lark-vc/references/lark-vc-notes.md
🚧 Files skipped from review as they are similar to previous changes (2)
  • skills/lark-minutes/SKILL.md
  • skills/lark-workflow-meeting-summary/SKILL.md

Comment thread shortcuts/vc/vc_notes.go
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
skills/lark-vc/references/vc-domain-boundaries.md (2)

58-62: ⚡ Quick win

Add language specifiers to code blocks.

The code blocks showing transcript format examples should include a language specifier for proper syntax highlighting and linting compliance.

📝 Proposed fix
-```
+```text
 发言人名称 相对时间戳
 <发言内容>

- +text
张三 00:00:00.195
我们接下来讨论一下项目进度。

Also applies to: 65-68

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-vc/references/vc-domain-boundaries.md` around lines 58 - 62, Add
a language specifier to the transcript example code fences (change
triple-backtick blocks from ``` to ```text) so they use "text" for proper
highlighting; update the example blocks showing "发言人名称 相对时间戳\n<发言内容>" and the
sample with "张三 00:00:00.195\n我们接下来讨论一下项目进度。" (and the other similar block
later) to begin with ```text instead of ```, ensuring both code fences are
updated.

142-155: ⚡ Quick win

Add language specifier to ASCII diagram code block.

The ASCII art diagram should include a language specifier for markdown linting compliance.

📝 Proposed fix
-```
+```text
 Calendar (日程) ──── 发起预约 ────► VC (会议)
                                        │
                     ┌──────────────────┤
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-vc/references/vc-domain-boundaries.md` around lines 142 - 155,
The markdown ASCII diagram block in vc-domain-boundaries.md lacks a language
specifier; update the opening code fence (the triple backticks that begin the
ASCII art diagram) to include a language tag (e.g., "text") so the block becomes
```text to satisfy linting; ensure only the opening fence is changed and the
closing fence remains ``` so the diagram content (the VC diagram) is unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@skills/lark-vc/references/vc-domain-boundaries.md`:
- Around line 58-62: Add a language specifier to the transcript example code
fences (change triple-backtick blocks from ``` to ```text) so they use "text"
for proper highlighting; update the example blocks showing "发言人名称 相对时间戳\n<发言内容>"
and the sample with "张三 00:00:00.195\n我们接下来讨论一下项目进度。" (and the other similar
block later) to begin with ```text instead of ```, ensuring both code fences are
updated.
- Around line 142-155: The markdown ASCII diagram block in
vc-domain-boundaries.md lacks a language specifier; update the opening code
fence (the triple backticks that begin the ASCII art diagram) to include a
language tag (e.g., "text") so the block becomes ```text to satisfy linting;
ensure only the opening fence is changed and the closing fence remains ``` so
the diagram content (the VC diagram) is unchanged.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: aad06df8-5a51-4e07-9041-1dd073e7f047

📥 Commits

Reviewing files that changed from the base of the PR and between 6dc95c7 and 6398a9e.

📒 Files selected for processing (8)
  • shortcuts/vc/vc_notes.go
  • shortcuts/vc/vc_notes_test.go
  • shortcuts/vc/vc_search.go
  • skills/lark-minutes/SKILL.md
  • skills/lark-vc/SKILL.md
  • skills/lark-vc/references/lark-vc-notes.md
  • skills/lark-vc/references/vc-domain-boundaries.md
  • skills/lark-workflow-meeting-summary/SKILL.md
✅ Files skipped from review due to trivial changes (3)
  • shortcuts/vc/vc_search.go
  • skills/lark-minutes/SKILL.md
  • skills/lark-vc/references/lark-vc-notes.md
🚧 Files skipped from review as they are similar to previous changes (3)
  • skills/lark-workflow-meeting-summary/SKILL.md
  • shortcuts/vc/vc_notes.go
  • shortcuts/vc/vc_notes_test.go

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation domain/vc PR touches the vc domain size/L Large or sensitive change across domains or core paths

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants