Skip to content

Commit a7f3efd

Browse files
SunPeiYang996SunPeiYang996
committed
fix(docs): hide docs api-version compat flag
1 parent 40a09c8 commit a7f3efd

31 files changed

Lines changed: 147 additions & 148 deletions

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ Prefixed with `+`, designed to be friendly for both humans and AI, with smart de
198198
```bash
199199
lark-cli calendar +agenda
200200
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
201-
lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
201+
lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
202202
```
203203

204204
Run `lark-cli <service> --help` to see all shortcut commands.

‎README.zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义
199199
```bash
200200
lark-cli calendar +agenda
201201
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
202-
lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
202+
lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
203203
```
204204

205205
运行 `lark-cli <service> --help` 查看所有快捷命令。

‎shortcuts/doc/docs_create_test.go‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,6 @@ func TestDocsCreateV2BotAutoGrantSkippedWithoutCurrentUser(t *testing.T) {
9090

9191
err := runDocsCreateShortcut(t, f, stdout, []string{
9292
"+create",
93-
"--api-version", "v2",
9493
"--content", "<title>内容</title><p>正文</p>",
9594
"--as", "bot",
9695
})
@@ -125,7 +124,6 @@ func TestDocsCreateV2UserSkipsPermissionGrantAugmentation(t *testing.T) {
125124

126125
err := runDocsCreateShortcut(t, f, stdout, []string{
127126
"+create",
128-
"--api-version", "v2",
129127
"--content", "<title>内容</title><p>正文</p>",
130128
"--as", "user",
131129
})
@@ -163,7 +161,6 @@ func TestDocsCreateV2BotAutoGrantFailureDoesNotFailCreate(t *testing.T) {
163161

164162
err := runDocsCreateShortcut(t, f, stdout, []string{
165163
"+create",
166-
"--api-version", "v2",
167164
"--content", "<title>内容</title><p>正文</p>",
168165
"--as", "bot",
169166
})
@@ -201,7 +198,6 @@ func TestDocsCreateV2FallbackURLWhenBackendOmitsIt(t *testing.T) {
201198

202199
err := runDocsCreateShortcut(t, f, stdout, []string{
203200
"+create",
204-
"--api-version", "v2",
205201
"--content", "<title>内容</title><p>正文</p>",
206202
"--as", "user",
207203
})
@@ -233,7 +229,6 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
233229

234230
err := runDocsCreateShortcut(t, f, stdout, []string{
235231
"+create",
236-
"--api-version", "v2",
237232
"--content", "<title>内容</title><p>正文</p>",
238233
"--as", "user",
239234
})
@@ -248,7 +243,7 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
248243
}
249244
}
250245

251-
func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
246+
func TestDocsCreateAPIVersionCompatFlagIsIgnored(t *testing.T) {
252247
t.Parallel()
253248

254249
f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
@@ -262,7 +257,7 @@ func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
262257

263258
err := runDocsCreateShortcut(t, f, stdout, []string{
264259
"+create",
265-
"--api-version", "v1",
260+
"--api-version", "legacy",
266261
"--content", "<title>项目计划</title>",
267262
"--as", "user",
268263
})

‎shortcuts/doc/docs_fetch_v2_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -507,10 +507,10 @@ func TestDocsFetchDryRunDefaultsToV2Endpoint(t *testing.T) {
507507
}
508508
}
509509

510-
func TestDocsFetchAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
510+
func TestDocsFetchAPIVersionCompatFlagIsIgnored(t *testing.T) {
511511
t.Parallel()
512512

513-
runtime := newFetchShortcutTestRuntime(t, "v1", nil)
513+
runtime := newFetchShortcutTestRuntime(t, "legacy", nil)
514514
if err := validateFetchV2(context.Background(), runtime); err != nil {
515515
t.Fatalf("validateFetchV2() error = %v", err)
516516
}

‎shortcuts/doc/docs_update_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ func TestValidCommandsV2(t *testing.T) {
3434
}
3535
}
3636

37-
func TestDocsUpdateDryRunAcceptsDeprecatedAPIVersionValues(t *testing.T) {
38-
for _, apiVersion := range []string{"v1", "v2"} {
37+
func TestDocsUpdateDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
38+
for _, apiVersion := range []string{"v1", "v2", "legacy"} {
3939
t.Run(apiVersion, func(t *testing.T) {
4040
t.Parallel()
4141

‎shortcuts/doc/v2_only.go‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ type docsLegacyFlag struct {
1717

1818
func docsAPIVersionCompatFlag() common.Flag {
1919
return common.Flag{
20-
Name: "api-version",
21-
Desc: "deprecated compatibility flag; docs shortcuts always use v2, and both v1/v2 are accepted for rollback-safe skill examples",
22-
Default: "v2",
20+
Name: "api-version",
21+
Desc: "deprecated compatibility flag; ignored by docs shortcuts",
22+
Hidden: true,
2323
}
2424
}
2525

@@ -54,20 +54,14 @@ func docsLegacyFlagDefinitions(flags []docsLegacyFlag) []common.Flag {
5454
for _, flag := range flags {
5555
out = append(out, common.Flag{
5656
Name: flag.Name,
57-
Desc: "deprecated v1 compatibility flag; run `lark-cli skills read lark-doc` for the v2 CLI skill",
57+
Desc: "deprecated compatibility flag; run `lark-cli skills read lark-doc` for the current CLI skill",
5858
Hidden: true,
5959
})
6060
}
6161
return out
6262
}
6363

6464
func validateDocsV2Only(runtime *common.RuntimeContext, shortcut string, legacyFlags []docsLegacyFlag) error {
65-
switch apiVersion := strings.TrimSpace(runtime.Str("api-version")); apiVersion {
66-
case "", "v1", "v2":
67-
default:
68-
return docsV2OnlyError(shortcut, "--api-version is deprecated and only accepts v1 or v2; both values execute the v2 API", "--api-version")
69-
}
70-
7165
var used []string
7266
var replacements []string
7367
for _, flag := range legacyFlags {

‎shortcuts/doc/v2_only_test.go‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ import (
1111
"github.com/spf13/cobra"
1212
)
1313

14-
func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing.T) {
15-
for _, apiVersion := range []string{"", "v1", "v2"} {
14+
func TestValidateDocsV2OnlyIgnoresAPIVersionValues(t *testing.T) {
15+
for _, apiVersion := range []string{"", "v1", "v2", "v0", "legacy"} {
1616
t.Run(apiVersion, func(t *testing.T) {
1717
runtime := docsV2OnlyTestRuntime(t, apiVersion, false)
1818
if err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}}); err != nil {
@@ -22,28 +22,6 @@ func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing
2222
}
2323
}
2424

25-
func TestValidateDocsV2OnlyRejectsUnknownAPIVersion(t *testing.T) {
26-
runtime := docsV2OnlyTestRuntime(t, "v0", false)
27-
err := validateDocsV2Only(runtime, "+fetch", nil)
28-
if err == nil {
29-
t.Fatal("expected unknown --api-version to be rejected")
30-
}
31-
for _, want := range []string{
32-
"docs +fetch is v2-only",
33-
"--api-version is deprecated and only accepts v1 or v2",
34-
"both values execute the v2 API",
35-
"lark-cli skills read lark-doc references/lark-doc-fetch.md",
36-
"lark-cli skills read lark-doc references/lark-doc-xml.md",
37-
"lark-cli skills read lark-doc references/lark-doc-md.md",
38-
"MUST NOT grep/open local SKILL.md files",
39-
"lark-cli docs +fetch --help",
40-
} {
41-
if !strings.Contains(err.Error(), want) {
42-
t.Fatalf("error missing %q: %v", want, err)
43-
}
44-
}
45-
}
46-
4725
func TestValidateDocsV2OnlyRejectsChangedLegacyFlags(t *testing.T) {
4826
runtime := docsV2OnlyTestRuntime(t, "", true)
4927
err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}})

‎shortcuts/note/note_transcript.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ func ensureUnifiedNote(ctx context.Context, runtime *common.RuntimeContext, note
153153
if detail.DisplayType != "unified" {
154154
if detail.VerbatimDocToken != "" {
155155
return errs.NewValidationError(errs.SubtypeFailedPrecondition, "note %s is not a unified note (note_display_type=%s, verbatim_doc_token=%s)", noteID, detail.DisplayType, detail.VerbatimDocToken).
156-
WithHint("Use docs +fetch --api-version v2 --doc %s for normal note transcripts", detail.VerbatimDocToken)
156+
WithHint("Use docs +fetch --doc %s for normal note transcripts", detail.VerbatimDocToken)
157157
}
158158
return errs.NewValidationError(errs.SubtypeFailedPrecondition, "note %s is not a unified note (note_display_type=%s, verbatim_doc_token=)", noteID, detail.DisplayType).
159159
WithHint("Use note +detail to inspect document tokens")

‎shortcuts/note/note_transcript_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ func TestNoteTranscriptRequiresUnifiedNote(t *testing.T) {
3939
if problem.Subtype != errs.SubtypeFailedPrecondition {
4040
t.Fatalf("subtype = %v, want FailedPrecondition", problem.Subtype)
4141
}
42-
if !strings.Contains(problem.Hint, "docs +fetch --api-version v2 --doc doc_verbatim") {
42+
if !strings.Contains(problem.Hint, "docs +fetch --doc doc_verbatim") {
4343
t.Fatalf("hint = %q, want docs +fetch guidance", problem.Hint)
4444
}
4545
if stdout.Len() != 0 {

‎shortcuts/register_test.go‎

Lines changed: 6 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
246246
shortcutHelp: "Create a Lark document",
247247
visibleFlag: "--content",
248248
skillCommand: "lark-cli skills read lark-doc references/lark-doc-create.md",
249-
hiddenFlags: []string{"markdown", "folder-token", "wiki-node", "wiki-space"},
249+
hiddenFlags: []string{"api-version", "markdown", "folder-token", "wiki-node", "wiki-space"},
250250
contentHelp: []string{
251251
"--title",
252252
"AI agents MUST read",
@@ -258,24 +258,24 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
258258
"MUST NOT grep/open local SKILL.md files",
259259
"use --help for the latest command flags",
260260
},
261-
unwanted: []string{"--markdown", "--folder-token", "--wiki-node", "--wiki-space"},
261+
unwanted: []string{"--api-version", "--markdown", "--folder-token", "--wiki-node", "--wiki-space"},
262262
},
263263
{
264264
name: "fetch",
265265
shortcut: "+fetch",
266266
shortcutHelp: "Fetch Lark document content",
267267
visibleFlag: "read scope",
268268
skillCommand: "lark-cli skills read lark-doc references/lark-doc-fetch.md",
269-
hiddenFlags: []string{"offset", "limit"},
270-
unwanted: []string{"--offset", "--limit"},
269+
hiddenFlags: []string{"api-version", "offset", "limit"},
270+
unwanted: []string{"--api-version", "--offset", "--limit"},
271271
},
272272
{
273273
name: "update",
274274
shortcut: "+update",
275275
shortcutHelp: "Update a Lark document",
276276
visibleFlag: "--command",
277277
skillCommand: "lark-cli skills read lark-doc references/lark-doc-update.md",
278-
hiddenFlags: []string{"mode", "markdown", "selection-with-ellipsis", "selection-by-title", "new-title"},
278+
hiddenFlags: []string{"api-version", "mode", "markdown", "selection-with-ellipsis", "selection-by-title", "new-title"},
279279
contentHelp: []string{
280280
"AI agents MUST read",
281281
"lark-cli skills read lark-doc references/lark-doc-xml.md",
@@ -286,7 +286,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
286286
"MUST NOT grep/open local SKILL.md files",
287287
"use --help for the latest command flags",
288288
},
289-
unwanted: []string{"--mode", "--markdown", "--selection-with-ellipsis", "--selection-by-title", "--new-title"},
289+
unwanted: []string{"--api-version", "--mode", "--markdown", "--selection-with-ellipsis", "--selection-by-title", "--new-title"},
290290
},
291291
}
292292

@@ -312,17 +312,6 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
312312
t.Fatalf("docs %s flag %q should be hidden", tt.shortcut, flagName)
313313
}
314314
}
315-
apiVersionFlag := cmd.Flags().Lookup("api-version")
316-
if apiVersionFlag == nil {
317-
t.Fatalf("docs %s missing --api-version flag", tt.shortcut)
318-
}
319-
if apiVersionFlag.Hidden {
320-
t.Fatalf("docs %s --api-version should be visible", tt.shortcut)
321-
}
322-
if apiVersionFlag.DefValue != "v2" {
323-
t.Fatalf("docs %s --api-version default = %q, want v2", tt.shortcut, apiVersionFlag.DefValue)
324-
}
325-
326315
var out bytes.Buffer
327316
cmd.SetOut(&out)
328317
if err := cmd.Help(); err != nil {
@@ -332,10 +321,6 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
332321
for _, want := range []string{
333322
tt.shortcutHelp,
334323
tt.visibleFlag,
335-
"--api-version",
336-
"deprecated compatibility flag; docs shortcuts always use v2",
337-
"both v1/v2 are accepted",
338-
"(default \"v2\")",
339324
"Start here (required for AI agents):",
340325
"AI agents MUST read the matching embedded skill",
341326
"Do not skip this step",

0 commit comments

Comments
 (0)