Compare commits

..

1 Commits

Author SHA1 Message Date
zhangheng.023
93754a9b5a fix: fetch official skills from stable index 2026-05-31 19:59:10 +08:00
18 changed files with 311 additions and 800 deletions

View File

@@ -2,22 +2,6 @@
All notable changes to this project will be documented in this file.
## [v1.0.45] - 2026-06-01
### Features
- **errors**: Add typed envelope contract for auth-domain errors (#1135)
- **platform**: Support multiple policy rules per plugin (#1182)
### Bug Fixes
- **vc**: Add domain boundaries and enrich `+notes` (#1172)
- **whiteboard**: Fix whiteboard skill (#1180)
### Refactor
- **auth**: Update login hint and split-flow docs (#1201)
## [v1.0.44] - 2026-05-29
### Features
@@ -964,7 +948,6 @@ Bundled AI agent skills for intelligent assistance:
- Bilingual documentation (English & Chinese).
- CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
[v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45
[v1.0.44]: https://github.com/larksuite/cli/releases/tag/v1.0.44
[v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
[v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42

View File

@@ -279,13 +279,7 @@ func authLoginRun(opts *LoginOptions) error {
"verification_url": authResp.VerificationUriComplete,
"device_code": authResp.DeviceCode,
"expires_in": authResp.ExpiresIn,
"hint": "**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it." +
"**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it." +
"**Display order:** Output the URL first, then place the QR code image below the URL." +
"**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation." +
"For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. **Before ending the turn, tell the user to come back and notify you after completing authorization.**" +
"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself." +
"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
"hint": fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
}
encoder := json.NewEncoder(f.IOStreams.Out)
encoder.SetEscapeHTML(false)

View File

@@ -1042,11 +1042,8 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
"final message of the turn",
"return control to the user",
"do not block on --device-code in the same turn",
"come back and notify",
"YOU must execute",
"lark-cli auth login --device-code <device_code>",
"Do NOT cache",
"lark-cli auth login --no-wait --json",
"After the user confirms authorization in a later step",
"lark-cli auth login --device-code device-code",
} {
if !strings.Contains(hint, want) {
t.Fatalf("hint missing %q, got:\n%s", want, hint)

View File

@@ -9,6 +9,8 @@ import (
"encoding/json"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"os/exec"
"strings"
"testing"
@@ -28,6 +30,22 @@ func newTestFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffe
return f, stdout, stderr
}
func officialSkillsIndexURLForTest(t *testing.T) string {
t.Helper()
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
t.Fatalf("method = %s, want GET", r.Method)
}
if r.URL.Path != "/.well-known/skills/index.json" {
t.Fatalf("path = %s, want /.well-known/skills/index.json", r.URL.Path)
}
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"skills":[{"name":"lark-calendar"},{"name":"lark-mail"}]}`))
}))
t.Cleanup(server.Close)
return server.URL + "/.well-known/skills/index.json"
}
// mockDetect sets up newUpdater to return an Updater with the given DetectResult.
func mockDetect(t *testing.T, result selfupdate.DetectResult) {
t.Helper()
@@ -35,6 +53,8 @@ func mockDetect(t *testing.T, result selfupdate.DetectResult) {
newUpdater = func() *selfupdate.Updater {
u := selfupdate.New()
u.DetectOverride = func() selfupdate.DetectResult { return result }
u.OfficialSkillsIndexURL = officialSkillsIndexURLForTest(t)
u.SkillsCommandOverride = successfulSkillsCommand()
return u
}
t.Cleanup(func() { newUpdater = origNew })
@@ -49,6 +69,7 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
u.DetectOverride = func() selfupdate.DetectResult { return result }
u.NpmInstallOverride = npmFn
u.VerifyOverride = func(string) error { return nil }
u.OfficialSkillsIndexURL = officialSkillsIndexURLForTest(t)
u.SkillsCommandOverride = successfulSkillsCommand()
return u
}
@@ -59,10 +80,14 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
return func(args ...string) *selfupdate.NpmResult {
r := &selfupdate.NpmResult{}
switch strings.Join(args, " ") {
case "-y skills add https://open.feishu.cn --list":
r.Stdout.WriteString("Available Skills\n │ lark-calendar\n │ lark-mail\n")
case "-y skills ls -g":
r.Stdout.WriteString("Global Skills\nlark-calendar /tmp/lark-calendar\ncustom-skill /tmp/custom-skill\n")
case "-y skills add https://open.feishu.cn -s lark-calendar lark-mail -g -y":
// incremental install succeeds
case "-y skills add https://open.feishu.cn -g -y":
// full install succeeds
case "-y skills add larksuite/cli -g -y":
// fallback full install succeeds
default:
}
return r

View File

@@ -10,7 +10,10 @@ import (
"bytes"
"context"
"fmt"
"io"
"net/http"
"os/exec"
"regexp"
"strings"
"time"
@@ -24,6 +27,8 @@ import (
// Tests that mutate execLookPath must not call t.Parallel().
var execLookPath = exec.LookPath
var officialSkillNamePattern = regexp.MustCompile(`^lark-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$`)
// InstallMethod describes how the CLI was installed.
type InstallMethod int
@@ -42,6 +47,13 @@ const (
verifyTimeout = 10 * time.Second
)
const (
officialSkillsIndexDefaultURL = "https://open.feishu.cn/.well-known/skills/index.json"
officialSkillsIndexMaxBytes = 2 << 20
)
var officialSkillsIndexURL = officialSkillsIndexDefaultURL
// DetectResult holds installation detection results.
type DetectResult struct {
Method InstallMethod
@@ -86,6 +98,7 @@ type Updater struct {
SkillsCommandOverride func(args ...string) *NpmResult
VerifyOverride func(expectedVersion string) error
RestoreAvailableOverride func() bool
OfficialSkillsIndexURL string
// backupCreated is set to true by PrepareSelfReplace (Windows) when the
// running binary is successfully renamed to .old. Used by
@@ -154,10 +167,53 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
}
func (u *Updater) ListOfficialSkills() *NpmResult {
r := u.runSkillsListOfficial("https://open.feishu.cn")
if r.Err != nil {
r = u.runSkillsListOfficial("larksuite/cli")
return u.fetchOfficialSkillsIndex()
}
func (u *Updater) fetchOfficialSkillsIndex() *NpmResult {
r := &NpmResult{}
indexURL := officialSkillsIndexURL
if u.OfficialSkillsIndexURL != "" {
indexURL = u.OfficialSkillsIndexURL
}
ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, indexURL, nil)
if err != nil {
r.Err = fmt.Errorf("create official skills index request %s: %w", indexURL, err)
return r
}
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
if ctx.Err() == context.DeadlineExceeded {
r.Err = fmt.Errorf("official skills index fetch timed out after %s: %s", skillsUpdateTimeout, indexURL)
return r
}
r.Err = fmt.Errorf("fetch official skills index %s: %w", indexURL, err)
return r
}
defer resp.Body.Close()
if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
r.Err = fmt.Errorf("fetch official skills index %s: HTTP %s", indexURL, resp.Status)
return r
}
body, err := io.ReadAll(io.LimitReader(resp.Body, officialSkillsIndexMaxBytes+1))
if err != nil {
r.Err = fmt.Errorf("read official skills index %s: %w", indexURL, err)
return r
}
if len(body) > officialSkillsIndexMaxBytes {
r.Err = fmt.Errorf("official skills index %s exceeds %d bytes", indexURL, officialSkillsIndexMaxBytes)
return r
}
_, _ = r.Stdout.Write(body)
return r
}
@@ -166,6 +222,10 @@ func (u *Updater) ListGlobalSkills() *NpmResult {
}
func (u *Updater) InstallSkill(nameList []string) *NpmResult {
if err := validateOfficialSkillNames(nameList); err != nil {
return &NpmResult{Err: err}
}
r := u.runSkillsInstall("https://open.feishu.cn", nameList)
if r.Err != nil {
r = u.runSkillsInstall("larksuite/cli", nameList)
@@ -173,6 +233,15 @@ func (u *Updater) InstallSkill(nameList []string) *NpmResult {
return r
}
func validateOfficialSkillNames(nameList []string) error {
for _, name := range nameList {
if !officialSkillNamePattern.MatchString(name) {
return fmt.Errorf("invalid official skill name %q", name)
}
}
return nil
}
func (u *Updater) InstallAllSkills() *NpmResult {
r := u.runSkillsAdd("https://open.feishu.cn")
if r.Err != nil {
@@ -185,10 +254,6 @@ func (u *Updater) runSkillsAdd(source string) *NpmResult {
return u.runSkillsCommand("-y", "skills", "add", source, "-g", "-y")
}
func (u *Updater) runSkillsListOfficial(source string) *NpmResult {
return u.runSkillsCommand("-y", "skills", "add", source, "--list")
}
func (u *Updater) runSkillsListGlobal() *NpmResult {
return u.runSkillsCommand("-y", "skills", "ls", "-g")
}

View File

@@ -5,6 +5,8 @@ package selfupdate
import (
"fmt"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"runtime"
@@ -174,13 +176,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
run func(*Updater) *NpmResult
want string
}{
{
name: "list official primary",
run: func(u *Updater) *NpmResult {
return u.runSkillsListOfficial("https://open.feishu.cn")
},
want: "-y skills add https://open.feishu.cn --list",
},
{
name: "list global",
run: func(u *Updater) *NpmResult {
@@ -225,29 +220,90 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
}
}
func TestListOfficialSkillsFallsBack(t *testing.T) {
called := []string{}
updater := &Updater{
SkillsCommandOverride: func(args ...string) *NpmResult {
called = append(called, strings.Join(args, " "))
r := &NpmResult{}
if strings.Contains(strings.Join(args, " "), "https://open.feishu.cn") {
r.Err = fmt.Errorf("primary failed")
return r
}
r.Stdout.WriteString("lark-calendar\n")
return r
},
}
func TestListOfficialSkillsFetchesIndexJSON(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
t.Fatalf("method = %s, want GET", r.Method)
}
if r.URL.Path != "/.well-known/skills/index.json" {
t.Fatalf("path = %s, want /.well-known/skills/index.json", r.URL.Path)
}
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"skills":[{"name":"lark-calendar"}]}`))
}))
defer server.Close()
result := updater.ListOfficialSkills()
oldURL := officialSkillsIndexURL
officialSkillsIndexURL = server.URL + "/.well-known/skills/index.json"
defer func() { officialSkillsIndexURL = oldURL }()
u := New()
result := u.ListOfficialSkills()
if result.Err != nil {
t.Fatalf("ListOfficialSkills() err = %v, want nil", result.Err)
}
if len(called) != 2 {
t.Fatalf("called %d commands, want 2: %#v", len(called), called)
}
if !strings.Contains(called[1], "larksuite/cli --list") {
t.Fatalf("fallback call = %q, want larksuite/cli --list", called[1])
if got := result.Stdout.String(); !strings.Contains(got, `"lark-calendar"`) {
t.Fatalf("ListOfficialSkills() stdout = %q, want index JSON", got)
}
}
func TestListOfficialSkillsNon2xxFails(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
http.Error(w, "nope", http.StatusBadGateway)
}))
defer server.Close()
oldURL := officialSkillsIndexURL
officialSkillsIndexURL = server.URL + "/.well-known/skills/index.json"
defer func() { officialSkillsIndexURL = oldURL }()
u := New()
result := u.ListOfficialSkills()
if result.Err == nil {
t.Fatal("ListOfficialSkills() err = nil, want error")
}
if !strings.Contains(result.Err.Error(), "502") {
t.Fatalf("ListOfficialSkills() err = %v, want HTTP status", result.Err)
}
}
func TestListOfficialSkillsTooLargeFails(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write([]byte(strings.Repeat("x", officialSkillsIndexMaxBytes+1)))
}))
defer server.Close()
oldURL := officialSkillsIndexURL
officialSkillsIndexURL = server.URL + "/.well-known/skills/index.json"
defer func() { officialSkillsIndexURL = oldURL }()
u := New()
result := u.ListOfficialSkills()
if result.Err == nil {
t.Fatal("ListOfficialSkills() err = nil, want error")
}
if !strings.Contains(result.Err.Error(), "exceeds") {
t.Fatalf("ListOfficialSkills() err = %v, want size limit error", result.Err)
}
}
func TestInstallSkillRejectsInvalidOfficialNames(t *testing.T) {
called := false
u := &Updater{
SkillsCommandOverride: func(args ...string) *NpmResult {
called = true
return &NpmResult{}
},
}
result := u.InstallSkill([]string{"lark-calendar", "lark-calendar@evil"})
if result.Err == nil {
t.Fatal("InstallSkill() err = nil, want invalid name error")
}
if !strings.Contains(result.Err.Error(), "invalid official skill name") {
t.Fatalf("InstallSkill() err = %v, want invalid name error", result.Err)
}
if called {
t.Fatal("InstallSkill() called skills command for invalid name")
}
}

View File

@@ -4,6 +4,7 @@
package skillscheck
import (
"encoding/json"
"fmt"
"regexp"
"sort"
@@ -14,8 +15,9 @@ import (
)
var (
skillNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_:-]*(@[^\s]+)?$`)
ansiPattern = regexp.MustCompile(`\x1b\[[0-?]*[ -/]*[@-~]`)
skillNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_:-]*(@[^\s]+)?$`)
officialSkillNamePattern = regexp.MustCompile(`^lark-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$`)
ansiPattern = regexp.MustCompile(`\x1b\[[0-?]*[ -/]*[@-~]`)
)
type SyncInput struct {
@@ -41,6 +43,10 @@ func stripANSI(s string) string {
func ParseSkillsList(text string) []string {
text = stripANSI(text)
if skills := parseOfficialSkillsIndex(text); skills != nil {
return skills
}
lines := strings.Split(text, "\n")
// Detect format type
@@ -57,6 +63,40 @@ func ParseSkillsList(text string) []string {
return nil
}
type officialSkillsIndex struct {
Skills []map[string]interface{} `json:"skills"`
}
func parseOfficialSkillsIndex(text string) []string {
trimmed := strings.TrimSpace(text)
if trimmed == "" || !strings.HasPrefix(trimmed, "{") {
return nil
}
var index officialSkillsIndex
if err := json.Unmarshal([]byte(trimmed), &index); err != nil {
return nil
}
if index.Skills == nil {
return nil
}
seen := map[string]bool{}
for _, skill := range index.Skills {
name, ok := skill["name"].(string)
if !ok {
continue
}
name = strings.TrimSpace(name)
if !officialSkillNamePattern.MatchString(name) {
continue
}
seen[name] = true
}
return sortedKeys(seen)
}
// parseGlobalSkillsList parses the output of "npx -y skills ls -g"
func parseGlobalSkillsList(lines []string) []string {
seen := map[string]bool{}

View File

@@ -8,6 +8,7 @@ import (
"os"
"path/filepath"
"reflect"
"strconv"
"strings"
"testing"
"time"
@@ -67,6 +68,56 @@ func TestParseGlobalSkillsListWithANSI(t *testing.T) {
}
}
func TestParseSkillsListOfficialJSONIndex(t *testing.T) {
input := `{
"skills": [
{"name": "lark-mail", "description": "Mail", "files": ["SKILL.md"]},
{"name": "lark-calendar", "description": "Calendar", "files": ["SKILL.md"]},
{"name": "lark-mail", "description": "Duplicate", "files": ["SKILL.md"]}
]
}`
got := ParseSkillsList(input)
want := []string{"lark-calendar", "lark-mail"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("ParseSkillsList() JSON index = %#v, want %#v", got, want)
}
}
func TestParseSkillsListOfficialJSONIndexIgnoresInvalidNames(t *testing.T) {
input := `{
"skills": [
{"name": " lark-calendar "},
{"name": "custom-skill"},
{"name": "lark-bad name"},
{"name": "lark-../../evil"},
{"name": "lark-calendar@evil"},
{"name": "lark-calendar:evil"},
{"name": "lark-calendar/evil"},
{"name": "lark-calendar..evil"},
{"name": "lark-calendar_evil"},
{"name": ""},
{"description": "missing name"},
{"name": 42}
]
}`
got := ParseSkillsList(input)
want := []string{"lark-calendar"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("ParseSkillsList() JSON index invalid names = %#v, want %#v", got, want)
}
}
func TestParseOfficialSkillsListLegacyAvailableSkills(t *testing.T) {
input := "Available Skills\n │ lark-calendar\n │ lark-mail\n"
got := ParseSkillsList(input)
want := []string{"lark-calendar", "lark-mail"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("ParseSkillsList() legacy Available Skills = %#v, want %#v", got, want)
}
}
func TestPlanNormal_WithReadableStatePreservesDeletedAndAddsNew(t *testing.T) {
previous := &SkillsState{OfficialSkills: []string{"lark-calendar", "lark-mail"}}
got := PlanSync(SyncInput{
@@ -125,12 +176,16 @@ type fakeSkillsRunner struct {
func officialSkillsOutput(names ...string) string {
var b strings.Builder
b.WriteString("Available Skills\n")
for _, name := range names {
b.WriteString("│ ")
b.WriteString(name)
b.WriteString("\n")
b.WriteString(`{"skills":[`)
for i, name := range names {
if i > 0 {
b.WriteString(",")
}
b.WriteString(`{"name":`)
b.WriteString(strconv.Quote(name))
b.WriteString(`,"description":"","files":["SKILL.md"]}`)
}
b.WriteString(`]}`)
return b.String()
}

View File

@@ -1,6 +1,6 @@
{
"name": "@larksuite/cli",
"version": "1.0.45",
"version": "1.0.44",
"description": "The official CLI for Lark/Feishu open platform",
"bin": {
"lark-cli": "scripts/run.js"

View File

@@ -38,8 +38,6 @@ import (
var (
scopesMeetingIDs = []string{
"vc:meeting.meetingevent:read",
"vc:note:read",
"vc:record:readonly",
}
scopesMinuteTokens = []string{
"minutes:minutes:readonly",
@@ -50,7 +48,6 @@ var (
"calendar:calendar:read",
"calendar:calendar.event:read",
"vc:meeting.meetingevent:read",
"vc:record:readonly",
}
)
@@ -62,37 +59,6 @@ const (
const logPrefix = "[vc +notes]"
const (
minutesNoReadPermissionCode = 2091005
// recording API specific error codes (used to surface meeting minute_token state).
recordingNotFoundCode = 121004 // 该会议没有妙记文件
recordingNoPermissionCode = 121005 // 非会议参与者无权查看
recordingGeneratingCode = 124002 // 录制/妙记文件仍在生成中
// note detail API specific error code.
noteNoPermissionCode = 121005 // 调用者没有该纪要的阅读权限
)
func minutesReadError(err error, minuteToken string) error {
var exitErr *output.ExitError
if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesNoReadPermissionCode {
return err
}
return &output.ExitError{
Code: output.ExitAPI,
Detail: &output.ErrDetail{
Type: "no_read_permission",
Code: minutesNoReadPermissionCode,
Message: fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken),
Hint: "Ask the minute owner for minute file read permission",
Detail: exitErr.Detail.Detail,
},
Err: err,
}
}
// validMinuteToken matches the server's minute-token format and blocks any
// user-supplied token from reaching filesystem paths unsanitized.
var validMinuteToken = regexp.MustCompile(`^[a-z0-9]+$`)
@@ -230,10 +196,7 @@ func fetchNoteByCalendarEventID(ctx context.Context, runtime *common.RuntimeCont
for _, meetingID := range relInfo.MeetingIDs {
fmt.Fprintf(errOut, "%s event %s → meeting_id=%s\n", logPrefix, sanitizeLogValue(instanceID), sanitizeLogValue(meetingID))
noteResult := fetchNoteByMeetingID(ctx, runtime, meetingID)
// success means note detail was retrieved, regardless of whether the
// recording API (minute_token) call succeeded — minute_token failures
// surface as part of the merged `error` string for downstream visibility.
if _, ok := noteResult["note_doc_token"].(string); ok {
if noteResult["error"] == nil {
for k, v := range noteResult {
result[k] = v
}
@@ -283,51 +246,7 @@ func asStringSlice(v any) []string {
return ss
}
// fetchMeetingMinuteToken queries the recording API of a meeting and returns
// the associated minute_token (parsed from the recording URL) and an
// optional human-friendly error message. On success token is non-empty and
// errMsg is empty; on failure token is empty and errMsg describes the cause:
// - 121004: meeting has no minute file
// - 121005: caller has no permission for the meeting recording
// - 124002: recording / minute file is still being generated
//
// Other failures fall back to the raw API error description so Agents can
// still parse the underlying cause.
func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, errMsg string) {
data, err := runtime.DoAPIJSON(http.MethodGet,
fmt.Sprintf("/open-apis/vc/v1/meetings/%s/recording", validate.EncodePathSegment(meetingID)),
nil, nil)
if err != nil {
var exitErr *output.ExitError
if errors.As(err, &exitErr) && exitErr.Detail != nil {
switch exitErr.Detail.Code {
case recordingNotFoundCode:
return "", "no minute file for this meeting"
case recordingNoPermissionCode:
return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute"
case recordingGeneratingCode:
return "", "minute file is still being generated; please retry later"
}
}
return "", fmt.Sprintf("failed to query recording: %v", err)
}
recording, _ := data["recording"].(map[string]any)
if recording == nil {
return "", "no recording available for this meeting"
}
recordingURL, _ := recording["url"].(string)
if t := extractMinuteToken(recordingURL); t != "" {
return t, ""
}
return "", "no minute_token found in recording URL"
}
// fetchNoteByMeetingID queries notes via meeting_id and additionally fetches
// the meeting's minute_token via the recording API. The two paths are queried
// independently; their failures are merged into a single `error` field
// (semicolon-separated) so Agents always see all causes at once. The
// `minute_token` field is only populated on success.
// fetchNoteByMeetingID queries notes via meeting_id.
func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, meetingID string) map[string]any {
data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/meetings/%s", validate.EncodePathSegment(meetingID)),
larkcore.QueryParams{"with_participants": []string{"false"}, "query_mode": []string{"0"}}, nil)
@@ -340,60 +259,16 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
return map[string]any{"meeting_id": meetingID, "error": "meeting not found"}
}
// Always attempt to query the meeting's minute_token via the recording API,
// regardless of whether the meeting has a note_id, so callers always see
// minute state for follow-up calls (e.g. `vc +notes --minute-tokens=...`).
minuteToken, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
var result map[string]any
var noteErr string
if noteID, _ := meeting["note_id"].(string); noteID != "" {
result = fetchNoteDetail(ctx, runtime, noteID)
if msg, _ := result["error"].(string); msg != "" {
noteErr = msg
delete(result, "error")
}
} else {
result = map[string]any{}
noteErr = "no notes available for this meeting"
noteID, _ := meeting["note_id"].(string)
if noteID == "" {
return map[string]any{"meeting_id": meetingID, "error": "no notes available for this meeting"}
}
result := fetchNoteDetail(ctx, runtime, noteID)
result["meeting_id"] = meetingID
if minuteToken != "" {
result["minute_token"] = minuteToken
}
if combined := joinErrors(noteErr, minuteErr); combined != "" {
result["error"] = combined
}
return result
}
// joinErrors merges multiple non-empty error messages with "; " so Agents can
// see all causes at once when both note and minute paths fail.
func joinErrors(msgs ...string) string {
parts := make([]string, 0, len(msgs))
for _, m := range msgs {
if m != "" {
parts = append(parts, m)
}
}
return strings.Join(parts, "; ")
}
// hasNotesPayload reports whether a result map carries any usable note or
// minute payload, irrespective of partial failures surfaced via `error`.
func hasNotesPayload(m map[string]any) bool {
if m == nil {
return false
}
for _, k := range []string{"note_doc_token", "verbatim_doc_token", "minute_token", "meeting_notes", "shared_doc_tokens", "artifacts"} {
if v, ok := m[k]; ok && v != nil && v != "" {
return true
}
}
return false
}
// fetchNoteByMinuteToken queries notes via minute_token.
// Fetches both note detail (doc tokens) and AI artifacts (summary/todos/chapters inline +
// transcript to file) independently, merging into a single result map for Agent consumption.
@@ -402,13 +277,7 @@ func fetchNoteByMinuteToken(ctx context.Context, runtime *common.RuntimeContext,
data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
if err != nil {
err = minutesReadError(err, minuteToken)
result := map[string]any{"minute_token": minuteToken, "error": err.Error()}
var exitErr *output.ExitError
if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Hint != "" {
result["hint"] = exitErr.Detail.Hint
}
return result
return map[string]any{"minute_token": minuteToken, "error": fmt.Sprintf("failed to query minutes: %v", err)}
}
minute, _ := data["minute"].(map[string]any)
@@ -603,10 +472,6 @@ func extractDocTokens(refs []any) []string {
func fetchNoteDetail(_ context.Context, runtime *common.RuntimeContext, noteID string) map[string]any {
data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)), nil, nil)
if err != nil {
var exitErr *output.ExitError
if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Code == noteNoPermissionCode {
return map[string]any{"error": fmt.Sprintf("[%v]: no read permission for this meeting note", exitErr.Detail.Code)}
}
return map[string]any{"error": fmt.Sprintf("failed to query note detail: %v", err)}
}
@@ -703,9 +568,8 @@ var VCNotes = common.Shortcut{
return common.NewDryRunAPI().
GET("/open-apis/vc/v1/meetings/{meeting_id}").
GET("/open-apis/vc/v1/notes/{note_id}").
GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
Set("meeting_ids", common.SplitCSV(ids)).
Set("steps", "meeting.get → note_id → note detail API + recording API → minute_token")
Set("steps", "meeting.get → note_id → note detail API")
}
if tokens := runtime.Str("minute-tokens"); tokens != "" {
return common.NewDryRunAPI().
@@ -722,9 +586,8 @@ var VCNotes = common.Shortcut{
POST("/open-apis/calendar/v4/calendars/{calendar_id}/events/mget_instance_relation_info").
GET("/open-apis/vc/v1/meetings/{meeting_id}").
GET("/open-apis/vc/v1/notes/{note_id}").
GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
Set("calendar_event_ids", common.SplitCSV(ids)).
Set("steps", "primary calendar → mget_instance_relation_info → meeting_id → meeting.get → note detail API + recording API → minute_token")
Set("steps", "primary calendar → mget_instance_relation_info → meeting_id → meeting.get → note detail API")
},
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
errOut := runtime.IO().ErrOut
@@ -778,13 +641,11 @@ var VCNotes = common.Shortcut{
}
}
// count results: a result counts as "successful" when it carries any
// note/minute payload, even if the merged `error` field surfaces a
// partial failure (e.g. note ok but minute_token lookup failed).
// count results
successCount := 0
for _, r := range results {
m, _ := r.(map[string]any)
if hasNotesPayload(m) {
if m["error"] == nil {
successCount++
}
}

View File

@@ -728,352 +728,3 @@ func TestNotes_TranscriptExplicitOutputDir_PreservesLegacyLayout(t *testing.T) {
t.Errorf("minutes/ should not be created when --output-dir is explicit")
}
}
// ---------------------------------------------------------------------------
// Tests for joinErrors / hasNotesPayload (pure helpers)
// ---------------------------------------------------------------------------
func TestJoinErrors(t *testing.T) {
tests := []struct {
name string
in []string
want string
}{
{"all empty", []string{"", "", ""}, ""},
{"single", []string{"only"}, "only"},
{"two non-empty", []string{"a", "b"}, "a; b"},
{"skip empties", []string{"", "a", "", "b", ""}, "a; b"},
{"three", []string{"x", "y", "z"}, "x; y; z"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := joinErrors(tt.in...); got != tt.want {
t.Errorf("joinErrors(%v) = %q, want %q", tt.in, got, tt.want)
}
})
}
}
func TestHasNotesPayload(t *testing.T) {
tests := []struct {
name string
in map[string]any
want bool
}{
{"nil", nil, false},
{"empty", map[string]any{}, false},
{"only meta", map[string]any{"meeting_id": "m1", "error": "fail"}, false},
{"empty values", map[string]any{"note_doc_token": "", "minute_token": ""}, false},
{"has note_doc_token", map[string]any{"note_doc_token": "doc1"}, true},
{"has verbatim_doc_token", map[string]any{"verbatim_doc_token": "v1"}, true},
{"has minute_token", map[string]any{"minute_token": "obc"}, true},
{"has meeting_notes", map[string]any{"meeting_notes": []string{"d1"}}, true},
{"has shared_doc_tokens", map[string]any{"shared_doc_tokens": []string{"s1"}}, true},
{"has artifacts", map[string]any{"artifacts": map[string]any{"summary": "s"}}, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := hasNotesPayload(tt.in); got != tt.want {
t.Errorf("hasNotesPayload(%v) = %v, want %v", tt.in, got, tt.want)
}
})
}
}
// ---------------------------------------------------------------------------
// Tests for fetchMeetingMinuteToken — recording API → minute_token mapping
// ---------------------------------------------------------------------------
// recordingStub is a small helper for shaping `/v1/meetings/{id}/recording` responses.
func recordingStub(meetingID string, body map[string]any) *httpmock.Stub {
return &httpmock.Stub{
Method: "GET",
URL: "/open-apis/vc/v1/meetings/" + meetingID + "/recording",
Body: body,
}
}
func recordingErrStub(meetingID string, code int, msg string) *httpmock.Stub {
return recordingStub(meetingID, map[string]any{"code": code, "msg": msg})
}
func recordingOKStub(meetingID, url string) *httpmock.Stub {
return recordingStub(meetingID, map[string]any{
"code": 0, "msg": "ok",
"data": map[string]any{
"recording": map[string]any{"url": url},
},
})
}
func TestFetchMeetingMinuteToken_Success(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(recordingOKStub("m_ok", "https://meetings.feishu.cn/minutes/obctoken_ok"))
if err := botExec(t, "fmmt-ok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
token, msg := fetchMeetingMinuteToken(rctx, "m_ok")
if token != "obctoken_ok" {
t.Errorf("token = %q, want obctoken_ok", token)
}
if msg != "" {
t.Errorf("errMsg = %q, want empty", msg)
}
return nil
}); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
func TestFetchMeetingMinuteToken_KnownErrorCodes(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
cases := []struct {
name string
meetingID string
code int
wantMsg string
}{
{"121004 not found", "m_121004", 121004, "no minute file for this meeting"},
{"121005 no permission", "m_121005", 121005, "no permission to access this meeting's minute"},
{"124002 generating", "m_124002", 124002, "minute file is still being generated"},
}
for _, tt := range cases {
t.Run(tt.name, func(t *testing.T) {
f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(recordingErrStub(tt.meetingID, tt.code, "err"))
if err := botExec(t, "fmmt-"+tt.meetingID, f, func(_ context.Context, rctx *common.RuntimeContext) error {
token, msg := fetchMeetingMinuteToken(rctx, tt.meetingID)
if token != "" {
t.Errorf("token = %q, want empty on error", token)
}
if !strings.Contains(msg, tt.wantMsg) {
t.Errorf("errMsg = %q, want contains %q", msg, tt.wantMsg)
}
return nil
}); err != nil {
t.Fatalf("unexpected error: %v", err)
}
})
}
}
func TestFetchMeetingMinuteToken_GenericAPIError(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(recordingErrStub("m_other", 99999, "weird"))
if err := botExec(t, "fmmt-generic", f, func(_ context.Context, rctx *common.RuntimeContext) error {
token, msg := fetchMeetingMinuteToken(rctx, "m_other")
if token != "" {
t.Errorf("token = %q, want empty", token)
}
if !strings.Contains(msg, "failed to query recording") {
t.Errorf("errMsg = %q, want contains 'failed to query recording'", msg)
}
return nil
}); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
func TestFetchMeetingMinuteToken_NoRecording(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(recordingStub("m_norec", map[string]any{
"code": 0, "msg": "ok",
"data": map[string]any{},
}))
if err := botExec(t, "fmmt-norec", f, func(_ context.Context, rctx *common.RuntimeContext) error {
token, msg := fetchMeetingMinuteToken(rctx, "m_norec")
if token != "" {
t.Errorf("token = %q, want empty", token)
}
if !strings.Contains(msg, "no recording available") {
t.Errorf("errMsg = %q, want contains 'no recording available'", msg)
}
return nil
}); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
func TestFetchMeetingMinuteToken_URLWithoutToken(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(recordingOKStub("m_notok", "https://example.com/no/minute/path"))
if err := botExec(t, "fmmt-notok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
token, msg := fetchMeetingMinuteToken(rctx, "m_notok")
if token != "" {
t.Errorf("token = %q, want empty", token)
}
if !strings.Contains(msg, "no minute_token found") {
t.Errorf("errMsg = %q, want contains 'no minute_token found'", msg)
}
return nil
}); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
// ---------------------------------------------------------------------------
// Integration: fetchNoteByMeetingID — note + minute_token combined behavior
// ---------------------------------------------------------------------------
// extractFirstNote runs +notes via --meeting-ids and returns the single result map.
func extractFirstNote(t *testing.T, stdout *bytes.Buffer) map[string]any {
t.Helper()
var resp map[string]any
if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
t.Fatalf("failed to parse output: %v\n%s", err, stdout.String())
}
data, _ := resp["data"].(map[string]any)
notes, _ := data["notes"].([]any)
if len(notes) != 1 {
t.Fatalf("expected 1 note, got %d (%v)", len(notes), notes)
}
note, _ := notes[0].(map[string]any)
return note
}
// assertNoteError verifies the result map's `error` field contains every
// substring in wantSubstrs (order-independent). Pass an empty slice to assert
// the field is absent. Centralized here so tests don't have to repeat the same
// "for each substring, Contains + Errorf" pattern.
func assertNoteError(t *testing.T, note map[string]any, wantSubstrs ...string) {
t.Helper()
errMsg, _ := note["error"].(string)
if len(wantSubstrs) == 0 {
if e, has := note["error"]; has {
t.Errorf("error should be absent, got %v", e)
}
return
}
for _, sub := range wantSubstrs {
if !strings.Contains(errMsg, sub) {
t.Errorf("error %q missing substring %q", errMsg, sub)
}
}
}
// assertNoteFieldAbsent fails the test if any of the named fields is present.
func assertNoteFieldAbsent(t *testing.T, note map[string]any, fields ...string) {
t.Helper()
for _, f := range fields {
if v, has := note[f]; has {
t.Errorf("%s should be absent, got %v", f, v)
}
}
}
func TestNotes_MeetingPath_NoteAndMinuteBothOK(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(meetingGetStub("m_both", "note_both"))
reg.Register(noteDetailStub("note_both"))
reg.Register(recordingOKStub("m_both", "https://meetings.feishu.cn/minutes/obc_both"))
if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_both", "--as", "user"}, f, stdout); err != nil {
t.Fatalf("unexpected error: %v", err)
}
note := extractFirstNote(t, stdout)
if got := note["note_doc_token"]; got != "doc_main" {
t.Errorf("note_doc_token = %v, want doc_main", got)
}
if got := note["minute_token"]; got != "obc_both" {
t.Errorf("minute_token = %v, want obc_both", got)
}
assertNoteError(t, note)
}
func TestNotes_MeetingPath_OnlyMinuteFails_PartialSuccess(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
reg.Register(meetingGetStub("m_minfail", "note_minfail"))
reg.Register(noteDetailStub("note_minfail"))
reg.Register(recordingErrStub("m_minfail", 121005, "no permission"))
if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_minfail", "--as", "user"}, f, stdout); err != nil {
t.Fatalf("unexpected error: %v", err)
}
note := extractFirstNote(t, stdout)
if got := note["note_doc_token"]; got != "doc_main" {
t.Errorf("note_doc_token = %v, want doc_main", got)
}
assertNoteFieldAbsent(t, note, "minute_token")
assertNoteError(t, note, "no permission to access this meeting's minute")
}
func TestNotes_MeetingPath_NoNote_ButMinuteOK(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
// note_id missing on the meeting object → no notes, but minute_token present
reg.Register(meetingGetStub("m_nonote", ""))
reg.Register(recordingOKStub("m_nonote", "https://meetings.feishu.cn/minutes/obc_nonote"))
if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_nonote", "--as", "user"}, f, stdout); err != nil {
t.Fatalf("unexpected error: %v", err)
}
note := extractFirstNote(t, stdout)
if got := note["minute_token"]; got != "obc_nonote" {
t.Errorf("minute_token = %v, want obc_nonote", got)
}
assertNoteError(t, note, "no notes available for this meeting")
}
func TestNotes_MeetingPath_BothFail_ErrorJoinedWithSemicolon(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
// no note_id → "no notes available..."; recording 121004 → "no minute file..."
reg.Register(meetingGetStub("m_bothfail", ""))
reg.Register(recordingErrStub("m_bothfail", 121004, "data not found"))
// Two-path failure with no payload should make the batch return ErrAPI.
err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_bothfail", "--as", "user"}, f, stdout)
if err == nil {
t.Fatalf("expected batch failure error, got nil")
}
note := extractFirstNote(t, stdout)
assertNoteFieldAbsent(t, note, "minute_token")
assertNoteError(t, note,
"no notes available for this meeting",
"no minute file for this meeting",
"; ", // causes joined with semicolon
)
}
// noteDetailErrStub returns a stub that emits an error response from
// /open-apis/vc/v1/notes/{note_id}.
func noteDetailErrStub(noteID string, code int, msg string) *httpmock.Stub {
return &httpmock.Stub{
Method: "GET",
URL: "/open-apis/vc/v1/notes/" + noteID,
Body: map[string]any{"code": code, "msg": msg},
}
}
func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
// note 接口返回 121005 → 阅读权限不足;同时 recording 也返回 121005
// 用以验证两路错误都会被合并到顶层 error 字段(用 "; " 拼接)。
reg.Register(meetingGetStub("m_noteperm", "note_noperm"))
reg.Register(noteDetailErrStub("note_noperm", 121005, "no permission"))
reg.Register(recordingErrStub("m_noteperm", 121005, "no permission"))
err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_noteperm", "--as", "user"}, f, stdout)
if err == nil {
t.Fatalf("expected batch failure error, got nil")
}
note := extractFirstNote(t, stdout)
assertNoteFieldAbsent(t, note, "note_doc_token", "minute_token")
assertNoteError(t, note,
"[121005]",
"no read permission for this meeting note",
"; ", // note + minute causes joined with semicolon
)
}

View File

@@ -172,7 +172,7 @@ func meetingSearchDescription(item map[string]interface{}) string {
var VCSearch = common.Shortcut{
Service: "vc",
Command: "+search",
Description: "Search meeting records by keyword, time range, participant, organizer, or meeting room (requires at least one filter)",
Description: "Search meeting records (requires at least one filter)",
Risk: "read",
Scopes: []string{"vc:meeting.search:read"},
AuthTypes: []string{"user"},

View File

@@ -12,12 +12,6 @@ metadata:
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md),其中包含认证、权限处理**
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**,不读将导致命令使用、会议产物决策、领域边界职责判断错误:
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
> 2. 了解会议产物(妙记和纪要)之间的关联关系,例如:**妙记和纪要产生条件相互独立**
> 3. 了解不同会议产物的组成部分,以便根据需求决策使用哪种产物的数据
> 4. 了解会议总结、分析和信息提取的标准流程
## 核心概念
- **妙记Minutes**:来源于飞书视频会议的录制产物或用户上传的音视频文件,通过 `minute_token` 标识。
@@ -140,8 +134,6 @@ lark-cli minutes <resource> <method> [flags] # 调用 API
- `get` — 获取妙记信息
> **权限错误**:如果返回 `[2091005] permission deny`,表示用户没有对应妙记文件的阅读权限,需提示用户联系妙记 owner 申请权限。
## 权限表
| 方法 | 所需 scope |

View File

@@ -81,29 +81,6 @@ lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json
lark-cli auth login --device-code <device_code>
```
**Split-Flow 完整步骤**
**第一步:发起授权(当前轮)**
1. 执行 `lark-cli auth login --scope "xxx" --no-wait --json`(必须加 `--no-wait --json`
2. 从 JSON 输出中提取 `verification_url``device_code`
3. 生成二维码:`lark-cli auth qrcode <verification_url> --output "xxx"`
4. 将 URL 和二维码展示给用户(先 URL后二维码
5. **结束本轮对话前,必须明确告知用户**"请完成授权后,回来告诉我已授权完成,我会帮你完成后续步骤"
**第二步:完成授权(后续轮)**
1. 等待用户回复"已完成授权"
2. **由你AI agent亲自执行**`lark-cli auth login --device-code <device_code>`
3. 此命令会轮询授权状态并完成登录
4. 如果返回授权成功,流程结束
**关键规则**
- **你必须亲自执行 `--device-code` 命令**,不要指示用户自行执行
- **不要在同一轮中展示 URL 后立刻执行 `--device-code`**,这会导致用户看不到 URL
- **禁止缓存 `verification_url``device_code`**:每次需要授权时,必须重新执行 `lark-cli auth login --no-wait --json` 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用
## 更新检查
lark-cli 命令执行后如果检测到新版本JSON 输出中会包含 `_notice.update` 字段(含 `message``command` 等)。

View File

@@ -12,17 +12,11 @@ metadata:
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md),其中包含认证、权限处理**
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md)**,不读将导致命令使用、会议产物决策、领域边界职责判断错误:
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
> 2. 了解会议产物(妙记和纪要)之间的关联关系,例如:**妙记和纪要产生条件相互独立**
> 3. 了解不同会议产物的组成部分,以便根据需求决策使用哪种产物的数据
> 4. 了解会议总结、分析和信息提取的标准流程
## 核心概念
- **视频会议Meeting**:飞书视频会议实例,通过 meeting_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索(见 `+search`)。
- **会议纪要Note**:视频会议结束后生成的结构化文档,包含纪要文档(包含总结、待办)和逐字稿文档。
- **妙记Minutes**:来源于飞书视频会议的录制产物或用户上传的音视频文件,支持视频/音频的转写,包含总结、待办、章节和文字记录,通过 minute_token 标识。
- **视频会议Meeting**:飞书视频会议实例,通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索(见 `+search`)。
- **会议纪要Note**:视频会议结束后生成的结构化文档,包含纪要文档(包含总结、待办、章节)和逐字稿文档。
- **妙记Minutes**:来源于飞书视频会议的录制产物或用户上传的音视频文件,支持视频/音频的转写和会议纪要,通过 minute\_token 标识。
- **纪要文档MainDoc**AI 智能纪要的主文档,包含 AI 生成的总结和待办,对应 `note_doc_token`
- **用户会议纪要MeetingNotes**:用户主动绑定到会议的纪要文档,对应 `meeting_notes`。仅通过 `--calendar-event-ids` 路径返回。
- **逐字稿VerbatimDoc**:会议的逐句文字记录,包含说话人和时间戳。
@@ -35,23 +29,8 @@ metadata:
3. 搜索结果存在多条数据时,务必注意分页数据获取,不要遗漏任何会议记录。
### 2. 整理会议纪要
> ⚠️ 在选择读取哪个产物前,请先确认你理解 AI 总结链路 vs 录制链路的区别。如不确定,先读 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md) 的「两条链路的独立性」章节
**⚠️ 产物选择决策 — 根据用户意图严格区分:**
| 用户意图 | 必须读取的产物 | 禁止 |
|---------|-------------|------|
| **提炼/总结/重新总结/整理会议内容/回顾会议** | 逐字稿(`verbatim_doc_token`或妙记文字记录Transcript基于原始对话独立分析 | 禁止直接搬运 AI 纪要(`note_doc_token`)的总结作为最终输出|
| **查看待办/章节** | AI 纪要(`note_doc_token`)或妙记产物 — AI 待办更友好(含提出人和负责人),章节按话题划分更结构化 | — |
| **查看纪要链接/文档地址** | 仅返回文档链接,无需读取内容 | — |
| **直接看 AI 总结结果** | AI 纪要(`note_doc_token` | — |
| **谁说了什么/完整发言记录** | 逐字稿(`verbatim_doc_token` | — |
> **为什么"提炼/总结"必须从逐字稿出发?** AI 纪要是模型对会议的二次压缩,可能遗漏讨论细节、争论过程和隐含决策。用户要求"提炼"或"重新总结"时,期望的是基于原始对话的独立分析,而非对 AI 产物的重新排版。AI 纪要可作为补充参考,但不能作为唯一信息源。
1. 整理纪要文档时默认给出纪要文档、逐字稿、妙记链接即可,无需读取纪要文档或逐字稿内容。
2. 用户明确需要获取总结、待办、章节产物时,再读取文档获取具体内容。
1. 整理纪要文档时默认给出纪要文档和逐字稿链接即可,无需读取纪要文档或逐字稿内容。
2. 用户明确需要获取纪要文档中的总结、待办、章节产物时,再读取文档获取具体内容
3. 读取智能纪要(`note_doc_token`)内容时,纪要文档的**第一个 `<whiteboard>`** 标签是封面图AI 生成的总结可视化),应同时下载展示给用户:
```bash
# 1. 读取纪要内容
@@ -64,7 +43,7 @@ lark-cli docs +media-download --type whiteboard --token <whiteboard_token> --out
> **产物目录规范**:同一会议的所有下载产物(录像、逐字稿、封面图等)统一放到 `./minutes/{minute_token}/` 目录下。这与 `minutes +download` 和 `vc +notes --minute-tokens` 的默认落点保持一致,便于 Agent 聚合。显式路径(如封面图)需手动对齐到同一目录。
> **纪要相关文档 — 根据用户意图选择:**
> - `note_doc_token` → **AI 智能纪要**AI 总结 + 待办)
> - `note_doc_token` → **AI 智能纪要**AI 总结 + 待办 + 章节
> - `meeting_notes` → **用户绑定的会议纪要**(用户主动关联到会议的文档,仅 `--calendar-event-ids` 路径返回)
> - `verbatim_doc_token` → **逐字稿**(完整的逐句文字记录,含说话人和时间戳)— 用户说"逐字稿""完整记录""谁说了什么"时用这个
> - 用户说"纪要""总结""纪要内容"时,应同时返回 `note_doc_token` 和 `meeting_notes`(如有)
@@ -140,7 +119,7 @@ Shortcut 是对常用操作的高级封装(`lark-cli vc +<verb> [flags]`)。
| Shortcut | 说明 |
|----------|------|
| [`+search`](references/lark-vc-search.md) | Search meeting records (requires at least one filter) |
| [`+notes`](references/lark-vc-notes.md) | Query meeting notes and minutes (via meeting-ids, minute-tokens, or calendar-event-ids) |
| [`+notes`](references/lark-vc-notes.md) | Query meeting notes (via meeting-ids, minute-tokens, or calendar-event-ids) |
| [`+recording`](references/lark-vc-recording.md) | Query minute_token from meeting-ids or calendar-event-ids |
- 使用 `+search` 命令时,必须阅读 [references/lark-vc-search.md](references/lark-vc-search.md),了解搜索参数和返回值结构。
@@ -179,9 +158,9 @@ lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participa
| 方法 | 所需 scope |
|------|-----------|
| `+notes --meeting-ids` | `vc:meeting.meetingevent:read``vc:note:read``vc:record:readonly` |
| `+notes --meeting-ids` | `vc:meeting.meetingevent:read``vc:note:read` |
| `+notes --minute-tokens` | `vc:note:read``minutes:minutes:readonly``minutes:minutes.artifacts:read``minutes:minutes.transcript:export` |
| `+notes --calendar-event-ids` | `calendar:calendar:read``calendar:calendar.event:read``vc:meeting.meetingevent:read``vc:note:read``vc:record:readonly` |
| `+notes --calendar-event-ids` | `calendar:calendar:read``calendar:calendar.event:read``vc:meeting.meetingevent:read``vc:note:read` |
| `+recording --meeting-ids` | `vc:record:readonly` |
| `+recording --calendar-event-ids` | `vc:record:readonly``calendar:calendar:read``calendar:calendar.event:read` |
| `+search` | `vc:meeting.search:read` |

View File

@@ -63,9 +63,9 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
| 输入 | 所需权限 |
|------|---------|
| `--meeting-ids` | `vc:meeting.meetingevent:read``vc:note:read``vc:record:readonly` |
| `--meeting-ids` | `vc:meeting.meetingevent:read``vc:note:read` |
| `--minute-tokens` | `vc:note:read``minutes:minutes:readonly``minutes:minutes.artifacts:read``minutes:minutes.transcript:export` |
| `--calendar-event-ids` | `calendar:calendar:read``calendar:calendar.event:read``vc:meeting.meetingevent:read``vc:note:read``vc:record:readonly` |
| `--calendar-event-ids` | `calendar:calendar:read``calendar:calendar.event:read``vc:meeting.meetingevent:read``vc:note:read` |
## 输出结果
@@ -75,8 +75,6 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
| 字段 | 说明 |
|------|------|
| `meeting_id` | 会议 ID`--meeting-ids` / `--calendar-event-ids` 路径) |
| `minute_token` | **会议对应的妙记 Token**`--meeting-ids` / `--calendar-event-ids` 路径自动通过录制 API 反查并附加)|
| `note_doc_token` | **AI 智能纪要**文档 Token — AI 生成的总结、待办、章节 |
| `meeting_notes` | **用户绑定的会议纪要**文档 Token 列表 — 用户主动关联到会议的文档(仅 `--calendar-event-ids` 路径返回) |
| `verbatim_doc_token` | **逐字稿**文档 Token — 完整的逐句文字记录,含说话人和时间戳 |
@@ -85,8 +83,6 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
| `create_time` | 创建时间(格式化) |
> **选择哪个 token** 用户说"会议纪要""总结""待办""纪要内容" → 返回 `note_doc_token` 和 `meeting_notes`(如有)。用户说"逐字稿""完整记录""谁说了什么" → 用 `verbatim_doc_token`。意图不明确时,展示所有文档链接让用户选择。
>
> 📌 不确定该返回哪个 token参见 [`vc-domain-boundaries.md`](vc-domain-boundaries.md) 的产物链路对比表,了解 AI 总结链路 vs 录制链路的区别。
### minute-tokens 路径的 AI 产物

View File

@@ -1,154 +0,0 @@
# Calendar/VC/Doc 跨领域关联关系、领域知识和职责边界说明
本文档说明飞书日历Calendar、视频会议VC、云文档Doc三个域之间的关联关系帮助理解跨域数据流转和产物依赖。
## Calendar 域
- **lark-calendar skill** 负责日历与日程管理,包括创建、查询、修改、删除日程等操作。
- **日程与会议的关系**:日程可以用于提前预约会议,确定会议时间、参与人、会议室、会议主题等信息。日程上可以关联飞书/Lark 视频会议。
- **并非所有会议都通过日程发起**:即时会议不经过日程预约,直接创建。因此,仅查询日程数据无法覆盖所有会议,搜索历史会议应优先使用 `vc +search`
- **日程上的用户会议纪要**用户可以在日程上绑定自己的会议纪要文档MeetingNotes用于手动记录会议相关信息。该文档与 AI 生成的智能纪要(`note_doc_token`)是不同的文档,相互独立。
> **路由规则**:查询过去已结束的会议 → `lark-vc`;查询未来日程/待开的会 → `lark-calendar`;查询"今天有哪些会议" → 两者结合(`vc +search` 查已结束 + `calendar` 查未开始)。
## VC 域
- **lark-vc skill** 负责视频会议管理,包括搜索历史会议、查询会议产物(智能纪要、逐字稿、妙记等)、查询参会人快照等操作。
- **会议类型**:会议可以是日程会议(由日程发起,有对应的 `calendar_event_id`),也可以是即时会议等其他类型。
### 会议产物
会议产物取决于会中开启的功能,分为两条独立链路:
#### 链路一开启「AI 总结」
会中开启「AI 总结」功能后,产生以下产物:
| 产物 | Token 字段 | 本质 | 说明 |
|------|-----------|------|------|
| 智能纪要 | `note_doc_token` | 飞书文档 | AI 生成的会议总结与待办 |
| 逐字稿 | `verbatim_doc_token` | 飞书文档 | 完整的逐句发言记录(含说话人、时间戳) |
| 共享文档 | `shared_doc_token` | 飞书文档 | 会中投屏共享的文档信息 |
此外,还存在**用户会议纪要MeetingNotes**,对应 `meeting_notes` 字段。这是用户主动绑定到会议的纪要文档,通常用于会前记录会议相关内容,与智能纪要文档相互独立。仅通过 `+notes --calendar-event-ids` 路径返回。
#### 链路二:开启「录制」
会中开启「录制」功能后,产生**妙记产物**`minute_token`)。注意:妙记不一定是会中产生的,用户上传音视频文件或录音也会产生妙记。妙记本身包含以下子产物:
| 子产物 | 说明 |
|--------|------|
| Summary总结 | 对整场会议的智能总结 |
| Todo待办 | 会议中识别出的待处理任务列表 |
| Chapter章节 | 按讨论话题划分的核心内容摘要 |
| Transcript文字记录 | 整场会议最原始的逐人发言记录 |
#### 两条链路的独立性
- 智能纪要AI 总结链路)和妙记(录制链路)**相互独立、互不影响**。
- 一场会议可能同时拥有两类产物,也可能只有其中一类,也可能都没有。
- 当两者都存在时Summary/Todo 内容可能重叠,应根据用户意图选择优先读取哪个。
> **产物选择决策**
> - **AI 产物 vs 原始记录**:智能总结、待办、章节都属于 AI 分析产物,可能只包含最终结论和关键信息。
> - **用户要求"提炼/总结/重新总结/整理/回顾"会议内容时** → **内容总结必须从逐字稿/文字记录出发,基于原始对话独立分析**。禁止直接搬运 AI 纪要的总结作为最终输出——那只是对 AI 产物的重新排版不是独立提炼。AI 纪要可作为补充参考,但不能作为内容总结的唯一信息源。
> - **用户要求查看待办或章节时** → **应参考 AI 产物的待办和章节**,因为 AI 产物的待办更友好(包含提出人和负责人),章节按话题划分更结构化。
> - **用户只想直接看 AI 总结结果** → 使用 AI 产物的总结。
> - **链路优先级**:如果用户没有明确偏好,对于重复的内容(如智能总结、待办),**优先查询智能纪要Note不存在时再降级到妙记Minutes**。
#### 逐字稿与文字记录的格式
智能纪要的逐字稿(`verbatim_doc_token`和妙记的文字记录Transcript都记录了用户原始对话内容格式一致
```
发言人名称 相对时间戳
<发言内容>
```
示例:
```
张三 00:00:00.195
我们接下来讨论一下项目进度。
```
- 第一行为发言人信息,包含用户名称和发言的相对时间(从会议开始计算的偏移量)。
- 后续行为该发言人的发言内容,直到下一个发言人标记出现。
### 会议总结和分析流程
#### Step 1: 定位会议
根据关键字、组织者、参与人、会议室等条件搜索会议,获取会议列表。
```bash
lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json
```
详细用法请阅读 [`lark-vc-search.md`](lark-vc-search.md)。
#### Step 2: 根据 meeting_id 查询产物
##### 获取会议产物
```bash
lark-cli vc +notes --meeting-ids '<meeting_id1>,<meeting_id2>'
```
可获取会议的所有产物信息,包括:
- 智能纪要(`note_doc_token`)— AI 生成的总结和待办信息
- 逐字稿(`verbatim_doc_token`)— 完整的会中发言记录
- 共享文档(`shared_doc_token`)— 会中投屏共享的文档
- 妙记 Token`minute_token`)— 如存在录制产物则返回
详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
如果返回了 `minute_token`,可通过以下命令获取妙记的详细信息(总结、待办、章节、文字记录):
```bash
lark-cli vc +notes --minute-tokens '<minute_token1>,<minute_token2>'
```
可获取妙记的总结、待办、章节、文字记录等信息。详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
#### Step 3: Doc 域拉取文档内容
智能纪要和逐字稿都是飞书文档,需使用 `docs +fetch` 读取正文内容:
```bash
lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
```
详细用法请参考 [lark-doc](../../lark-doc/SKILL.md) skill。
#### Step 4: 判断用户需要的产物内容
- 根据用户诉求(总结/待办/章节/完整发言记录等),选择合适的产物进行分析和信息提取
- 如果两种产物都不存在或没有权限,需如实告知用户
## Doc 域
- **lark-doc skill** 负责飞书云文档管理,包括获取文档元信息、读取文档内容、创建和编辑文档等操作。
- **会议产物的文档本质**:智能纪要(`note_doc_token`)、逐字稿(`verbatim_doc_token`)都是飞书文档,需要通过 `lark-doc` 的 API`docs +fetch`)查询其内容和元信息。
- **文档元信息查询**获取文档名称、URL 等基本信息时,使用 `drive metas batch_query`;获取文档正文内容时,使用 `docs +fetch --api-version v2`
## 三域关联总览
```
Calendar (日程) ──── 发起预约 ────► VC (会议)
┌──────────────────┤
│ │
AI 总结链路 录制链路
│ │
▼ ▼
智能纪要 (Doc) 妙记 (Minutes)
逐字稿 (Doc) ├── Summary
共享文档 (Doc) ├── Todo
用户纪要 (Doc) ├── Chapter
└── Transcript
```
- Calendar 提供会议预约入口,但并非所有会议都来自日程。
- VC 是会议数据的中心,管理会议记录和产物关联。
- Doc 是会议产物的载体,智能纪要和逐字稿都以飞书文档形式沉淀,需通过 Doc 域 API 读取。

View File

@@ -11,12 +11,6 @@ metadata:
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md),其中包含认证、权限处理**。然后阅读 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md),了解会议纪要相关操作。
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**,不读将导致命令使用、会议产物决策、领域边界职责判断错误:
> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
> 2. 了解会议产物(妙记和纪要)之间的关联关系,例如:**妙记和纪要产生条件相互独立**
> 3. 了解不同会议产物的组成部分,以便根据需求决策使用哪种产物的数据
> 4. 了解会议总结、分析和信息提取的标准流程
## 适用场景
- "帮我整理这周的会议纪要" / "总结最近的会议" / "生成会议周报"