From 5034c332febb0f6533d3979c73f77cc352bce5f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Tue, 11 Aug 2026 22:21:51 +0800 Subject: [PATCH 001/250] fix(chat): converge im id flags --- internal/app/param_alias_e2e_test.go | 6 +- internal/app/root_help_test.go | 4 +- internal/cli/param_aliases_generated.go | 389 +++---- internal/cli/param_concepts.json | 12 +- internal/cli/schema_catalog_test.go | 13 +- internal/cli/schema_constraints_runtime.go | 13 +- .../cli/schema_parameter_mapping_ledger.go | 5 +- internal/helpers/chat.go | 997 ++++++++++-------- internal/helpers/chat_command_edges_test.go | 2 +- internal/helpers/chat_message_help_test.go | 4 +- internal/helpers/chat_ports_coverage_test.go | 12 +- .../wukong_weekly_sync_chat_todo_test.go | 14 +- 12 files changed, 711 insertions(+), 760 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 8267390c..02590448 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -417,7 +417,11 @@ func TestCrossPlatformCoverageChatReactionConversationAliasesReachCanonicalPaylo if err != nil { t.Fatalf("alias execution failed: %v", err) } - if ctx == nil || len(ctx.Corrections) != 1 || ctx.Corrections[0].Original != "--"+alias || ctx.Corrections[0].Corrected != "--conversation-id" { + if alias == "open-conversation-id" { + if ctx == nil || len(ctx.Corrections) != 0 { + t.Fatalf("alias corrections = %#v", ctx) + } + } else if ctx == nil || len(ctx.Corrections) != 1 || ctx.Corrections[0].Original != "--"+alias || ctx.Corrections[0].Corrected != "--conversation-id" { t.Fatalf("alias corrections = %#v", ctx) } if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) { diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index eb370a7b..4fc9dcb6 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -92,8 +92,8 @@ func TestRootKeepsMainBranchChatCompatibilityCommands(t *testing.T) { }{ {args: []string{"chat", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"}, {args: []string{"im", "send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"}, - {args: []string{"chat", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group "}, - {args: []string{"im", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group "}, + {args: []string{"chat", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id "}, + {args: []string{"im", "history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id "}, } { command := NewRootCommand() command.SilenceErrors = true diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index d5229552..f3a876dc 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -891,9 +891,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat category add-conv", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -922,9 +920,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat category remove-conv", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -938,66 +934,52 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat chmod", Aliases: map[string]string{ - "chat": "conversation-id", - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", - "staff-id": "user", - "uid": "user", - "user-id": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "user-id": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat clear-messages", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat clear-red-point", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat conversation-info", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", - "staff-id": "user", - "uid": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "userid": "user", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group audit-join-validation", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"staff-id", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat group bots", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group create", @@ -1006,12 +988,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group dismiss", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group get-by-group-id", @@ -1020,12 +999,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group invite-url", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group members", @@ -1100,52 +1076,37 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group notice create", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice edit", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice get", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice list", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group quit", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group rename", @@ -1161,23 +1122,17 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group set-admin", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", - "user-ids": "users", + "chat-id": "conversation-id", + "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, }, { CLIPath: "chat group set-history", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group share-invite", @@ -1191,188 +1146,139 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group transfer-owner", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", - "staff-id": "user", - "uid": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group update-alias", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-icon", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-nick", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-settings", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-mute", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-mute-member", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", - "user-ids": "users", + "chat-id": "conversation-id", + "user-ids": "users", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, }, { CLIPath: "chat group-role add", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role list", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role query-user", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", - "staff-id": "user", - "uid": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role remove", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role remove-user", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", - "staff-id": "user", - "uid": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role set-user", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", - "staff-id": "user", - "uid": "user", - "userid": "user", + "chat-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role update", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat hide", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mark-read", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "msg-id": "message-id", - "open-conversation-id": "conversation-id", - "open-message-id": "message-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat mark-unread", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message add-emoji", Aliases: map[string]string{ - "chat-id": "conversation-id", - "message-id": "msg-id", - "open-conversation-id": "conversation-id", - "open-message-id": "msg-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, }, @@ -1391,10 +1297,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message add-text-emotion", Aliases: map[string]string{ - "chat-id": "conversation-id", - "message-id": "msg-id", - "open-conversation-id": "conversation-id", - "open-message-id": "msg-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, }, @@ -1427,8 +1330,6 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "dest-open-cid": "dest-conversation-id", "destination-conversation-id": "dest-conversation-id", - "message-id": "msg-id", - "open-message-id": "msg-id", "source-conversation-id": "src-conversation-id", "src-open-cid": "src-conversation-id", "target-conversation-id": "dest-conversation-id", @@ -1453,19 +1354,18 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message list", Aliases: map[string]string{ - "chat-id": "group", - "max-result": "limit", - "max-results": "limit", - "open-conversation-id": "group", - "page-size": "limit", - "per-page": "limit", - "staff-id": "user", - "start": "time", - "take": "limit", - "top": "limit", - "uid": "user", - "user-id": "user", - "userid": "user", + "chat-id": "conversation-id", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "staff-id": "user", + "start": "time", + "take": "limit", + "top": "limit", + "uid": "user", + "user-id": "user", + "userid": "user", }, Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, @@ -1516,8 +1416,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message list-mentions", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -1534,8 +1433,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message list-topic-replies", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -1549,40 +1447,30 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message read-status", Aliases: map[string]string{ - "chat-id": "conversation-id", - "msg-id": "message-id", - "open-conversation-id": "conversation-id", - "open-message-id": "message-id", - "user-ids": "users", + "chat-id": "conversation-id", + "user-ids": "users", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"}, }, { CLIPath: "chat message recall", Aliases: map[string]string{ - "chat-id": "conversation-id", - "message-id": "msg-id", - "open-conversation-id": "conversation-id", - "open-message-id": "msg-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message recall-by-bot", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", - "robot": "robot-code", + "chat-id": "conversation-id", + "robot": "robot-code", }, Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message remove-emoji", Aliases: map[string]string{ - "chat-id": "conversation-id", - "message-id": "msg-id", - "open-conversation-id": "conversation-id", - "open-message-id": "msg-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, }, @@ -1601,29 +1489,22 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message remove-text-emotion", Aliases: map[string]string{ - "chat-id": "conversation-id", - "message-id": "msg-id", - "open-conversation-id": "conversation-id", - "open-message-id": "msg-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, }, { CLIPath: "chat message reply", Aliases: map[string]string{ - "chat": "conversation-id", - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", - "ref-message-id": "ref-msg-id", + "chat-id": "conversation-id", + "ref-message-id": "ref-msg-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat message search", Aliases: map[string]string{ - "chat-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -1638,25 +1519,23 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message send", Aliases: map[string]string{ - "chat-id": "group", - "file": "file-path", - "open-conversation-id": "group", - "staff-id": "user", - "to-user": "user", - "uid": "user", - "user-id": "user", - "userid": "user", + "chat-id": "conversation-id", + "file": "file-path", + "staff-id": "user", + "to-user": "user", + "uid": "user", + "user-id": "user", + "userid": "user", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"}, }, { CLIPath: "chat message send-by-bot", Aliases: map[string]string{ - "at-users": "at-user-ids", - "chat-id": "group", - "open-conversation-id": "group", - "robot": "robot-code", - "user-ids": "users", + "at-users": "at-user-ids", + "chat-id": "conversation-id", + "robot": "robot-code", + "user-ids": "users", }, Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"}, Ambiguous: []string{"at-ids"}, @@ -1670,12 +1549,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message send-card", Aliases: map[string]string{ - "chat": "group", - "chat-id": "group", - "conversation-id": "group", - "open-conversation-id": "group", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat message set-pin-msg", @@ -1684,8 +1560,6 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "open-conversation-id", "conversation-id": "open-conversation-id", "group": "open-conversation-id", - "message-id": "msg-id", - "open-message-id": "msg-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, @@ -1696,8 +1570,6 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "open-conversation-id", "conversation-id": "open-conversation-id", "group": "open-conversation-id", - "message-id": "msg-id", - "open-message-id": "msg-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, @@ -1708,8 +1580,6 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "open-conversation-id", "conversation-id": "open-conversation-id", "group": "open-conversation-id", - "message-id": "msg-id", - "open-message-id": "msg-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, @@ -1720,47 +1590,36 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "open-conversation-id", "conversation-id": "open-conversation-id", "group": "open-conversation-id", - "message-id": "msg-id", - "open-message-id": "msg-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat mute", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, }, { CLIPath: "chat mute-at-all", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mute-red-envelope", Aliases: map[string]string{ - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat set-top", Aliases: map[string]string{ - "chat": "conversation-id", - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "contact +dept-members", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index db93b507..0e40b445 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -49,11 +49,11 @@ "chat group members": {"bind": {"id": "open_conversation_id"}}, "chat group members add": {"bind": {"id": "open_conversation_id"}, "block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a list and may contain mixed userId/openDingTalkId values; singular inputs are not promoted automatically."}, "chat group members remove": {"bind": {"id": "open_conversation_id"}}, - "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat mute": {"scoped_aliases": {"group": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id/--id/--chat remain unchanged; other reviewed openConversationId spellings reduce to --conversation-id."}, + "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, + "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, + "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, + "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, + "chat mute": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id and hidden compatibility --group/--id/--chat/--open-conversation-id remain unchanged; reviewed chat-id reduces to --conversation-id."}, "drive list": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, "drive upload": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, "ding +receiver-status": {"scoped_aliases": {"id": "ding-id"}, "note": "generic id reduces to ding-id"}, @@ -252,7 +252,7 @@ {"command": "chat group rename", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"}, {"command": "chat group rename", "emitted": "group-id", "expect": "did-you-mean:blocked", "via": "guard:group-id-vs-open-conversation-id"}, {"command": "chat message send", "emitted": "conversation-id", "expect": "group", "via": "concept:open_conversation_id"}, - {"command": "chat message add-emoji", "emitted": "open-conversation-id", "expect": "conversation-id", "via": "override:scoped"}, + {"command": "chat message add-emoji", "emitted": "open-conversation-id", "expect": "conversation-id", "via": "concept:open_conversation_id"}, {"command": "chat message add-emoji", "emitted": "group-id", "expect": "did-you-mean:blocked", "via": "guard:group-id-vs-open-conversation-id"}, {"command": "chat +group-members", "emitted": "conversation-id", "expect": "did-you-mean:blocked", "via": "guard:group-name-vs-open-conversation-id"}, {"command": "chat +send-to-group", "emitted": "group-name", "expect": "group", "via": "concept:group_name+bind"}, diff --git a/internal/cli/schema_catalog_test.go b/internal/cli/schema_catalog_test.go index 0f5d4aad..9c4bb649 100644 --- a/internal/cli/schema_catalog_test.go +++ b/internal/cli/schema_catalog_test.go @@ -1354,13 +1354,13 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { interfaceType string }{ {"chat message edit", "conversation-id", "openConversationId", true, ""}, - {"chat message edit", "msg-id", "openMessageId", true, ""}, + {"chat message edit", "message-id", "openMessageId", true, ""}, {"chat message edit", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"}, - {"chat message update-text-emotion", "msg-id", "openMsgId", true, ""}, + {"chat message update-text-emotion", "message-id", "openMsgId", true, ""}, {"chat message update-text-emotion", "old-emotion-id", "oldEmotionId", true, ""}, {"chat category batch-info", "category-ids", "categoryIds", true, "array"}, - {"chat category list-by-conv", "group", "openConversationId", true, ""}, - {"chat group update-nick", "group", "openConversationId", true, ""}, + {"chat category list-by-conv", "conversation-id", "openConversationId", true, ""}, + {"chat group update-nick", "conversation-id", "", true, ""}, {"chat group upgrade-to-external", "extension", "extension", false, "object"}, {"chat +messages-send-card", "receiver-open-dingtalk-id", "receiverOpenDingTalkId", false, ""}, {"chat message list-favorites", "size", "", false, "string"}, @@ -1410,7 +1410,10 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { t.Fatal(err) } listParams := schemaMap(listByConv["parameters"]) - for _, hidden := range []string{"conversation-id", "id"} { + if _, ok := listParams["conversation-id"]; !ok { + t.Fatalf("chat category list-by-conv missing public canonical --conversation-id") + } + for _, hidden := range []string{"group", "id"} { if _, ok := listParams[hidden]; ok { t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --%s", hidden) } diff --git a/internal/cli/schema_constraints_runtime.go b/internal/cli/schema_constraints_runtime.go index ecc7ce71..fbc03613 100644 --- a/internal/cli/schema_constraints_runtime.go +++ b/internal/cli/schema_constraints_runtime.go @@ -37,27 +37,22 @@ func init() { registerRequireOneOf("calendar.query_busy_status", "users", "rooms") registerRequireTogether("calendar.update_calendar_event", "recurrence-type", "recurrence-interval", "recurrence-range-type") registerExclusiveOneOf("chat.search_messages_by_sender", "sender-user-id", "sender-open-dingtalk-id") - registerExclusiveOneOf("chat.create_and_send_card", "group", "receiver") + registerExclusiveOneOf("chat.create_and_send_card", "conversation-id", "receiver") RegisterRuntimeSchemaConstraints("chat.chat_permission_grant", RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"conversation-id", "open-dingtalk-id", "user"}}, RequireOneOf: [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}}, }) registerExclusiveOneOf("chat.chat_permission_grant_cross_org_data", "target-org-id", "all") - registerRequireOneOf("chat.add_emoji_reaction", "conversation-id", "group", "id", "chat") - registerRequireOneOf("chat.add_text_emotion", "conversation-id", "group", "id", "chat") registerExclusiveOneOf("chat.clear_conversation_messages", "conversation-id", "id", "chat") registerExclusiveOneOf("chat.clear_conversation_red_point", "conversation-id", "id", "chat") - registerRequireOneOf("chat.update_text_emotion", "conversation-id", "group", "id", "chat") - registerExclusiveOneOf("chat.get_conversation_info", "group", "user", "open-dingtalk-id") + registerExclusiveOneOf("chat.get_conversation_info", "conversation-id", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.hide_conversation", "conversation-id", "id", "chat") - registerExclusiveOneOf("chat.list_conversation_message_v2", "group", "user", "open-dingtalk-id") + registerExclusiveOneOf("chat.list_conversation_message_v2", "conversation-id", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.list_individual_chat_message", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.mark_conversation_unread", "conversation-id", "id", "chat") registerExclusiveOneOf("chat.mark_message_read", "conversation-id", "id", "chat") - registerRequireOneOf("chat.remove_emoji_reaction", "conversation-id", "group", "id", "chat") - registerRequireOneOf("chat.remove_text_emotion", "conversation-id", "group", "id", "chat") registerRequireOneOf("chat.send_personal_message", "text", "content", "msg-type") - registerExclusiveOneOf("chat.send_robot_message", "group", "users") + registerExclusiveOneOf("chat.send_robot_message", "conversation-id", "users") registerRequireOneOf("chat.set_group_member_mute_list", "users", "user") registerExclusiveOneOf("chat.share_group_invite_url", "target", "receiver") registerExclusiveOneOf("chat.transfer_group_owner", "new-owner", "user") diff --git a/internal/cli/schema_parameter_mapping_ledger.go b/internal/cli/schema_parameter_mapping_ledger.go index 2595ee69..605d0a19 100644 --- a/internal/cli/schema_parameter_mapping_ledger.go +++ b/internal/cli/schema_parameter_mapping_ledger.go @@ -252,7 +252,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "chat.batch_query_group_chat_settings --groups": "Reviewed unpinned adapter: chat.batch_query_group_chat_settings has no singular pinned interface_ref; --groups is a CLI wrapper input and does not publish a direct interface property.", "chat.batch_update_group_chat_settings --items": "Reviewed unpinned adapter: chat.batch_update_group_chat_settings has no singular pinned interface_ref; --items is a CLI wrapper input and does not publish a direct interface property.", "chat.create_text_emotion --background-id": "Runtime extension: the executable helper forwards backgroundId to im/create_text_emotion, but the pinned source-revision metadata does not declare that optional property; preserve the compatibility flag without advertising it as a pinned RPC field.", - "chat.get_group_mute_config --group": "Reviewed unpinned adapter: chat.get_group_mute_config has no singular pinned interface_ref; --group is a CLI wrapper input and does not publish a direct interface property.", + "chat.get_group_mute_config --conversation-id": "Reviewed unpinned adapter: chat.get_group_mute_config has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.list_conversation_message_v2 --open-dingtalk-id": "selects the alternate list_individual_chat_message branch", "chat.list_conversation_message_v2 --user": "selects the alternate list_individual_chat_message branch", "chat.list_message_favorites --cursor": "Reviewed unpinned adapter: chat.list_message_favorites has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.", @@ -265,6 +265,9 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "chat.query_msg_read_status --users": "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to targetUserIds or targetOpenDingTalkIds according to its runtime ID shape; there is no single RPC property for this flag", "chat.remove_message_favorite --open-conversation-id": "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.remove_message_favorite --open-message-id": "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-message-id is a CLI wrapper input and does not publish a direct interface property.", + "chat.update_group_nick --conversation-id": "Reviewed unpinned adapter: chat.update_group_nick has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", + "chat.update_text_emotion --conversation-id": "Reviewed unpinned adapter: chat.update_text_emotion has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", + "chat.upgrade_group_to_external --conversation-id": "Reviewed unpinned adapter: chat.upgrade_group_to_external has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.reply_personal_message --ref-msg-id": "serialized into the aggregate content JSON string", "chat.reply_personal_message --ref-sender": "resolved then serialized into the aggregate content JSON string", "chat.reply_personal_message --text": "serialized into the aggregate content JSON string", diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 288e2702..4b41dd41 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -194,6 +194,112 @@ func chatIntFlagOrFallback(cmd *cobra.Command, primary string, aliases ...string return v } +func chatFlagOrAlias(cmd *cobra.Command, primary string, aliases ...string) (string, error) { + value, _ := cmd.Flags().GetString(primary) + value = strings.TrimSpace(value) + for _, alias := range aliases { + aliasValue, _ := cmd.Flags().GetString(alias) + aliasValue = strings.TrimSpace(aliasValue) + if aliasValue == "" { + continue + } + if value != "" && aliasValue != value { + return "", fmt.Errorf("--%s conflicts with --%s", alias, primary) + } + if value == "" { + value = aliasValue + } + } + return value, nil +} + +func requireChatFlagOrAlias(cmd *cobra.Command, primary string, aliases ...string) (string, error) { + value, err := chatFlagOrAlias(cmd, primary, aliases...) + if err != nil { + return "", err + } + if value != "" { + return value, nil + } + return "", validateRequiredFlagWithAliases(cmd, primary, aliases...) +} + +func chatConversationID(cmd *cobra.Command) (string, error) { + return chatFlagOrAlias(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id") +} + +func requireChatConversationID(cmd *cobra.Command) (string, error) { + return requireChatFlagOrAlias(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id") +} + +func chatMessageID(cmd *cobra.Command) (string, error) { + return requireChatFlagOrAlias(cmd, "message-id", "msg-id", "open-message-id") +} + +func installChatIMIDFlagAliases(root *cobra.Command) { + var visit func(*cobra.Command) + visit = func(cmd *cobra.Command) { + installChatFlagAliases(cmd, "conversation-id", []string{"group", "id", "chat", "open-conversation-id"}, requireChatConversationID) + installChatFlagAliases(cmd, "message-id", []string{"msg-id", "open-message-id"}, chatMessageID) + clearChatAliasRequiredAnnotations(cmd, "group", "id", "chat", "open-conversation-id", "msg-id", "open-message-id") + for _, child := range cmd.Commands() { + visit(child) + } + } + visit(root) +} + +func clearChatAliasRequiredAnnotations(cmd *cobra.Command, aliases ...string) { + for _, alias := range aliases { + flag := cmd.Flags().Lookup(alias) + if flag != nil && flag.Annotations != nil { + delete(flag.Annotations, cobra.BashCompOneRequiredFlag) + } + } +} + +func installChatFlagAliases(cmd *cobra.Command, primary string, aliases []string, validate func(*cobra.Command) (string, error)) { + flags := cmd.Flags() + flag := flags.Lookup(primary) + if flag == nil { + return + } + for _, alias := range aliases { + if flags.Lookup(alias) != nil { + if aliasFlag := flags.Lookup(alias); aliasFlag != nil && aliasFlag.Annotations != nil { + delete(aliasFlag.Annotations, cobra.BashCompOneRequiredFlag) + } + continue + } + flags.String(alias, "", "--"+primary+" 的兼容别名") + _ = flags.MarkHidden(alias) + } + required, ok := flag.Annotations[cobra.BashCompOneRequiredFlag] + wasRequired := flag.Annotations != nil && ok && len(required) > 0 && required[0] == "true" + if wasRequired { + delete(flag.Annotations, cobra.BashCompOneRequiredFlag) + } + previous := cmd.PreRunE + cmd.PreRunE = func(cmd *cobra.Command, args []string) error { + value, err := chatFlagOrAlias(cmd, primary, aliases...) + if err != nil { + return err + } + if value != "" { + _ = cmd.Flags().Set(primary, value) + } + if wasRequired { + if _, err := validate(cmd); err != nil { + return err + } + } + if previous != nil { + return previous(cmd, args) + } + return nil + } +} + const maxConversationScopedSearchPages = 40 func runConversationScopedPagedMessageSearch( @@ -543,7 +649,7 @@ func chatMessageListMentionsArgs(cmd *cobra.Command) (map[string]any, error) { "limit": chatIntFlagOrFallback(cmd, "limit", "size"), "cursor": cursor, } - if groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat"); groupID != "" { + if groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat"); groupID != "" { toolArgs["openConversationId"] = groupID } return toolArgs, nil @@ -586,7 +692,7 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) { "limit": chatIntFlagOrFallback(cmd, "limit", "size"), "cursor": cursor, } - if groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat"); groupID != "" { + if groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat"); groupID != "" { toolArgs["openConversationId"] = groupID } return toolArgs, nil @@ -1495,7 +1601,7 @@ func stringFromJSONScalar(value any) string { } func buildConversationTargetArgs(cmd *cobra.Command) (map[string]any, error) { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") rawOpenDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") rawUserID := flagOrFallback(cmd, "user", "userId") @@ -2605,19 +2711,19 @@ func newChatCommand() *cobra.Command { chatMessageListCmd := &cobra.Command{ Use: "list", Short: "拉取会话消息内容", - Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, - Example: ` dws chat message list --group --time "2025-03-01 00:00:00" + Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--conversation-id 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, + Example: ` dws chat message list --conversation-id --time "2025-03-01 00:00:00" dws chat message list --user --time "2025-03-01 00:00:00" --limit 50 dws chat message list --open-dingtalk-id --time "2025-03-01 00:00:00" --limit 50 - dws chat message list --group --time "2025-03-01 00:00:00" --direction older - dws chat message list --group --time "2025-03-01 00:00:00" --jq '.messages[] | {messageId, text}' + dws chat message list --conversation-id --time "2025-03-01 00:00:00" --direction older + dws chat message list --conversation-id --time "2025-03-01 00:00:00" --jq '.messages[] | {messageId, text}' # 查询群 ID: dws chat search --query "群名" # 查询 userId: dws contact user search --query "姓名"`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlags(cmd, "time"); err != nil { return err } - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") userID, _ := cmd.Flags().GetString("user") openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") specified := 0 @@ -2631,10 +2737,10 @@ func newChatCommand() *cobra.Command { specified++ } if specified > 1 { - return fmt.Errorf("--group, --user and --open-dingtalk-id are mutually exclusive, specify exactly one") + return fmt.Errorf("--conversation-id, --user and --open-dingtalk-id are mutually exclusive, specify exactly one") } if specified == 0 { - return fmt.Errorf("--group, --user or --open-dingtalk-id is required") + return fmt.Errorf("--conversation-id, --user or --open-dingtalk-id is required") } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID @@ -2695,13 +2801,12 @@ func newChatCommand() *cobra.Command { UseWhen: []string{"用户明确指定某个会话，并要读取消息或追溯引用回复中的原消息上下文时"}, AvoidWhen: []string{"跨全部会话按时间查询时使用 chat message list-all"}, Examples: []string{ - "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50", - "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", + "dws chat message list --conversation-id --time \"2026-07-01 00:00:00\" --limit 50", + "dws chat message list --conversation-id --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", }, }, Parameters: []contract.ParamDecl{ {Name: "direction", Property: "forward"}, - {Name: "group", Property: "openconversation_id"}, }, }, }) @@ -2787,13 +2892,13 @@ func newChatCommand() *cobra.Command { chatMessageSendCmd := &cobra.Command{ Use: "send", - Short: "以当前用户身份发送消息（--group 群聊 / --user 或 --open-dingtalk-id 单聊）", + Short: "以当前用户身份发送消息（--conversation-id 群聊 / --user 或 --open-dingtalk-id 单聊）", Long: `以当前用户身份发送消息。 ⚠️ 重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。 目标选择（三选一，必填）： - --group 群聊 openconversation_id + --conversation-id 群聊 openconversation_id --user 单聊接收人 userId --open-dingtalk-id 单聊接收人 openDingTalkId @@ -2812,23 +2917,23 @@ func newChatCommand() *cobra.Command { 旧版内联图片消息： 仅当上游已经提供有效 mediaId 时，使用 --msg-type image --media-id。 当前 CLI 不提供本地文件到 mediaId 的上传能力。`, - Example: ` dws chat message send --group "hello" + Example: ` dws chat message send --conversation-id "hello" dws chat message send --user "请查收" dws chat message send --open-dingtalk-id "请查收" - dws chat message send --group --title "周报提醒" "请大家本周五前提交周报" + dws chat message send --conversation-id --title "周报提醒" "请大家本周五前提交周报" # 发送本地图片或文件（图片会作为可下载的 file 附件发送） - dws chat message send --group --msg-type file --file-path ./screenshot.png - dws chat message send --group --msg-type file --file-path ./report.pdf + dws chat message send --conversation-id --msg-type file --file-path ./screenshot.png + dws chat message send --conversation-id --msg-type file --file-path ./report.pdf # 发送本地音频/视频（audio/video 是 file 的语义别名） - dws chat message send --group --msg-type audio --file-path ./recording.mp3 - dws chat message send --group --msg-type video --file-path ./demo.mp4 + dws chat message send --conversation-id --msg-type audio --file-path ./recording.mp3 + dws chat message send --conversation-id --msg-type video --file-path ./demo.mp4 # 旧版内联图片：仅当上游已经持有有效 mediaId 时使用 - dws chat message send --group --msg-type image --media-id + dws chat message send --conversation-id --msg-type image --media-id # 查询群 ID: dws chat search --query "群名" # 查询用户 ID: dws contact user search --query "姓名"`, Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") userID, _ := cmd.Flags().GetString("user") openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") msgUuid, _ := cmd.Flags().GetString("uuid") @@ -2843,10 +2948,10 @@ func newChatCommand() *cobra.Command { specified++ } if specified > 1 { - return fmt.Errorf("--group, --user and --open-dingtalk-id are mutually exclusive, specify exactly one") + return fmt.Errorf("--conversation-id, --user and --open-dingtalk-id are mutually exclusive, specify exactly one") } if specified == 0 { - return fmt.Errorf("--group, --user or --open-dingtalk-id is required") + return fmt.Errorf("--conversation-id, --user or --open-dingtalk-id is required") } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID @@ -3040,34 +3145,33 @@ func newChatCommand() *cobra.Command { AgentSummary: "以当前用户身份发送群聊或单聊消息", UseWhen: []string{"用户明确要以个人身份发送文本或媒体消息时；响应返回 openTaskId 后用 chat message query-send-status 确认投递并取得后续操作所需的消息 ID"}, AvoidWhen: []string{"机器人身份或 Webhook 发送应使用对应命令"}, - Examples: []string{"dws chat message send --group \"项目已更新\""}, + Examples: []string{"dws chat message send --conversation-id \"项目已更新\""}, }, Parameters: []contract.ParamDecl{ {Name: "ai-tag", Property: "clawType", InterfaceType: "string"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds"}, - {Name: "group", Property: "openConversationId"}, {Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"}, }, }, }) - // send-by-bot: 群聊传 --group，单聊传 --users/--open-dingtalk-ids。 + // send-by-bot: 群聊传 --conversation-id，单聊传 --users/--open-dingtalk-ids。 // Markdown 使用 --title/--text，图片使用 --msg-type image/--image-url， // 文件使用 --msg-type file/--file-path，CLI 上传后发送。 chatMessageSendByBotCmd := &cobra.Command{ Use: "send-by-bot", - Short: "机器人发送消息（--group 群聊 / --users 单聊）", - Long: `群聊：传 --group 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --group 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。 + Short: "机器人发送消息（--conversation-id 群聊 / --users 单聊）", + Long: `群聊：传 --conversation-id 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --conversation-id 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。 ⚠️ 重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。`, - Example: ` dws chat message send-by-bot --robot-code --group --title "日报" --text "## 今日完成..." - dws chat message send-by-bot --robot-code --group --msg-type image --image-url "https://example.com/image.png" - dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./report.pdf + Example: ` dws chat message send-by-bot --robot-code --conversation-id --title "日报" --text "## 今日完成..." + dws chat message send-by-bot --robot-code --conversation-id --msg-type image --image-url "https://example.com/image.png" + dws chat message send-by-bot --robot-code --conversation-id --msg-type file --file-path ./report.pdf dws chat message send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报" dws chat message send-by-bot --robot-code --open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "请提交周报" - dws chat message send-by-bot --robot-code --group --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收本周报告" - dws chat message send-by-bot --robot-code --group --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" - dws chat message send-by-bot --robot-code --group --at-all --title "通知" --text "请所有人注意" + dws chat message send-by-bot --robot-code --conversation-id --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收本周报告" + dws chat message send-by-bot --robot-code --conversation-id --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" + dws chat message send-by-bot --robot-code --conversation-id --at-all --title "通知" --text "请所有人注意" # 查询群 ID: dws chat search --query "群名" # 查询 userId: dws contact user search --query "姓名" # robot-code: $DINGTALK_CHAT_ROBOT_CODE`, @@ -3108,15 +3212,15 @@ func newChatCommand() *cobra.Command { } isMarkdownMessage := msgType == "markdown" - chatID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + chatID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") usersStr, _ := cmd.Flags().GetString("users") openDingtalkIdsStr, _ := cmd.Flags().GetString("open-dingtalk-ids") hasDirectTarget := usersStr != "" || openDingtalkIdsStr != "" if chatID != "" && hasDirectTarget { - return fmt.Errorf("--group and --users/--open-dingtalk-ids are mutually exclusive") + return fmt.Errorf("--conversation-id and --users/--open-dingtalk-ids are mutually exclusive") } if chatID == "" && !hasDirectTarget { - return fmt.Errorf("--group or --users/--open-dingtalk-ids is required") + return fmt.Errorf("--conversation-id or --users/--open-dingtalk-ids is required") } userIDs := splitCommaList(usersStr) @@ -3240,7 +3344,7 @@ func newChatCommand() *cobra.Command { AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊", UseWhen: []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时"}, AvoidWhen: []string{"个人身份发送或自定义 Webhook 告警不要使用"}, - Examples: []string{"dws chat message send-by-bot --robot-code --group --title \"日报\" --text \"今日进展\""}, + Examples: []string{"dws chat message send-by-bot --robot-code --conversation-id --title \"日报\" --text \"今日进展\""}, }, // Keep title/text required_when out of Schema: the runtime switch above // enforces Markdown inputs, while adding it breaks merge-base compatibility. @@ -3252,12 +3356,12 @@ func newChatCommand() *cobra.Command { }, }) - // recall-by-bot: 传 --group 为群聊撤回，不传为单聊撤回 + // recall-by-bot: 传 --conversation-id 为群聊撤回，不传为单聊撤回 chatMessageRecallByBotCmd := &cobra.Command{ Use: "recall-by-bot", - Short: "机器人撤回消息（--group 群聊 / 不传为单聊）", - Long: `群聊：传 --group 与 --keys；单聊：仅传 --keys。--keys 为发送时返回的 processQueryKey 列表，逗号分隔。`, - Example: ` dws chat message recall-by-bot --robot-code --group --keys + Short: "机器人撤回消息（--conversation-id 群聊 / 不传为单聊）", + Long: `群聊：传 --conversation-id 与 --keys；单聊：仅传 --keys。--keys 为发送时返回的 processQueryKey 列表，逗号分隔。`, + Example: ` dws chat message recall-by-bot --robot-code --conversation-id --keys dws chat message recall-by-bot --robot-code --keys key1,key2 # 查询群 ID: dws chat search --query "群名" # robot-code: $DINGTALK_CHAT_ROBOT_CODE`, @@ -3272,7 +3376,7 @@ func newChatCommand() *cobra.Command { processQueryKeys = append(processQueryKeys, s) } } - chatID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + chatID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") if chatID != "" { return callMCPToolOnServer("bot", "recall_robot_group_message", map[string]any{ "robotCode": mustGetFlag(cmd, "robot-code"), @@ -3309,7 +3413,7 @@ func newChatCommand() *cobra.Command { AgentSummary: "撤回指定机器人发送的消息", UseWhen: []string{"持有 robotCode 和发送结果 key，需要撤回机器人消息时"}, AvoidWhen: []string{"个人身份消息撤回使用 chat message recall"}, - Examples: []string{"dws chat message recall-by-bot --robot-code --group --keys "}, + Examples: []string{"dws chat message recall-by-bot --robot-code --conversation-id --keys "}, }, }, }) @@ -3417,19 +3521,19 @@ func newChatCommand() *cobra.Command { chatMessageListTopicRepliesCmd := &cobra.Command{ Use: "list-topic-replies", Short: "拉取群话题回复消息列表", - Long: `查询指定群聊中某条话题消息的全部回复。--group 指定群会话 ID，--topic-id 指定话题 ID（由 dws chat message list 返回）。`, - Example: ` dws chat message list-topic-replies --group --topic-id - dws chat message list-topic-replies --group --topic-id --time "2025-03-01 00:00:00" --limit 20 + Long: `查询指定群聊中某条话题消息的全部回复。--conversation-id 指定群会话 ID，--topic-id 指定话题 ID（由 dws chat message list 返回）。`, + Example: ` dws chat message list-topic-replies --conversation-id --topic-id + dws chat message list-topic-replies --conversation-id --topic-id --time "2025-03-01 00:00:00" --limit 20 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "group", "conversation-id", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } if err := validateRequiredFlags(cmd, "topic-id"); err != nil { return err } toolArgs := map[string]any{ - "openconversationId": flagOrFallback(cmd, "group", "conversation-id", "id", "chat"), + "openconversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "topicId": mustGetFlag(cmd, "topic-id"), } if v, _ := cmd.Flags().GetString("time"); v != "" { @@ -3469,11 +3573,10 @@ func newChatCommand() *cobra.Command { AgentSummary: "分页读取指定话题的回复", UseWhen: []string{"已知话题 ID 并需要查看回复串时"}, AvoidWhen: []string{"读取普通会话消息时使用 chat message list"}, - Examples: []string{"dws chat message list-topic-replies --group --topic-id --limit 50"}, + Examples: []string{"dws chat message list-topic-replies --conversation-id --topic-id --limit 50"}, }, Parameters: []contract.ParamDecl{ {Name: "direction", Property: "forward"}, - {Name: "group", Property: "openconversationId"}, {Name: "limit", Property: "pageSize"}, {Name: "time", Property: "startTime"}, }, @@ -3585,9 +3688,9 @@ func newChatCommand() *cobra.Command { Long: `搜索时间范围内 @我 的消息，可选指定群聊。返回结果包含单聊和群聊标识。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, Example: ` dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 dws chat message list-mentions --start "2026-04-01T00:00:00+08:00" --end "2026-04-14T00:00:00+08:00" --limit 20 --cursor 0 - dws chat message list-mentions --group --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 + dws chat message list-mentions --conversation-id --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor - dws chat message list-mentions --group --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --page-all --max-items 200 --page-delay 0 + dws chat message list-mentions --conversation-id --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --page-all --max-items 200 --page-delay 0 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { return RunPagedMCPCommand(cmd, pagedChatConversationMessagesConfig( @@ -3624,7 +3727,6 @@ func newChatCommand() *cobra.Command { }, Parameters: append([]contract.ParamDecl{ {Name: "end", Property: "endTime"}, - {Name: "group", Property: "openConversationId"}, {Name: "start", Property: "startTime"}, }, pagedMCPParamDecls()...), }, @@ -3770,15 +3872,15 @@ func newChatCommand() *cobra.Command { chatMessageSearchCmd := &cobra.Command{ Use: "search", Short: "按关键词搜索消息", - Long: `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --group 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）限定搜索时间范围。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, + Long: `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --conversation-id 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）限定搜索时间范围。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, Example: ` dws chat message search --query "changefree" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 50 --cursor 0 - dws chat message search --query "codereview" --group --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --cursor 0 + dws chat message search --query "codereview" --conversation-id --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --cursor 0 dws chat message search --query "链接" --start "2026-04-15T00:00:00+08:00" --end "2026-04-16T00:00:00+08:00" --limit 100 --cursor dws chat message search --query "发布计划" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --page-all --max-items 300 --page-delay 0 dws chat message search --query "发布计划" --start "2026-07-01T00:00:00+08:00" --end "2026-07-10T00:00:00+08:00" --jq '.messages[] | {messageId, text}' # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") return runConversationScopedPagedMessageSearch( cmd, pagedProjectedChatSearchConfig(cmd, "search_messages_by_keyword", chatMessageSearchArgs), @@ -3817,7 +3919,6 @@ func newChatCommand() *cobra.Command { }, Parameters: append([]contract.ParamDecl{ {Name: "end", Property: "endTime"}, - {Name: "group", Property: "openConversationId"}, {Name: "query", Property: "keyword"}, {Name: "start", Property: "startTime"}, }, pagedMCPParamDecls()...), @@ -3906,10 +4007,10 @@ func newChatCommand() *cobra.Command { Long: `查询以当前用户身份发送的消息的发送状态。需要传入 chat message send 返回的 openTaskId。 发送成功后，查询结果会返回 openMessageId 和 openConversationId，可直接作为 -chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 +chat message edit 或 chat message recall 的 --message-id 和 --conversation-id。 同一组 ID 也可继续用于 chat message read-status（消息参数为 --message-id）；openTaskId 本身不是消息 ID。`, Example: ` dws chat message query-send-status --open-task-id - dws chat message recall --conversation-id --msg-id `, + dws chat message recall --conversation-id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlags(cmd, "open-task-id"); err != nil { return err @@ -3954,22 +4055,22 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Use: "recall", Short: "撤回用户发送的消息", Long: `撤回当前用户发送的消息。需要指定会话 ID 和消息 ID。`, - Example: ` dws chat message recall --conversation-id --msg-id + Example: ` dws chat message recall --conversation-id --message-id # 发送后撤回：send -> query-send-status -> recall - dws chat message send --group --text "待撤回的内容" + dws chat message send --conversation-id --text "待撤回的内容" dws chat message query-send-status --open-task-id <上一步返回的openTaskId> - dws chat message recall --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>`, + dws chat message recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "message-id", "msg-id"); err != nil { return err } return callMCPToolOnServer("im", "recall_message", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), }) }, } @@ -3999,11 +4100,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 "撤回机器人消息时使用 chat message recall-by-bot", "消息 ID 未确认时先用消息查询/搜索拿到 openMessageId", }, - Examples: []string{"dws chat message recall --conversation-id --msg-id "}, + Examples: []string{"dws chat message recall --conversation-id --message-id "}, }, Parameters: []contract.ParamDecl{ {Name: "conversation-id", Property: "openConversationId"}, - {Name: "msg-id", Property: "openMessageId"}, + {Name: "message-id", Property: "openMessageId"}, }, }, }) @@ -4015,22 +4116,22 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 推荐使用 --text 和可选 --title，CLI 会按 Markdown 消息规则生成 content：{"title":"标题","text":"正文"}。 也可以直接使用 --content 传入完整 Markdown content JSON。--text 和 --content 二选一。`, - Example: ` dws chat message edit --conversation-id --msg-id --text "更新后的内容" + Example: ` dws chat message edit --conversation-id --message-id --text "更新后的内容" # 发送后编辑：send -> query-send-status -> edit - dws chat message send --group --text "原始内容" + dws chat message send --conversation-id --text "原始内容" dws chat message query-send-status --open-task-id <上一步返回的openTaskId> - dws chat message edit --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId> --text "更新后的内容" + dws chat message edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId> --text "更新后的内容" - dws chat message edit --group --msg-id --title "标题" --text "更新后的内容" - dws chat message edit --group --msg-id --text "<@all> 请查看" --at-all - dws chat message edit --group --msg-id --text "<@openDingTalkId1> 请查看" --at-open-dingtalk-ids - dws chat message edit --group --msg-id --content '{"title":"标题","text":"更新后的内容"}'`, + dws chat message edit --conversation-id --message-id --title "标题" --text "更新后的内容" + dws chat message edit --conversation-id --message-id --text "<@all> 请查看" --at-all + dws chat message edit --conversation-id --message-id --text "<@openDingTalkId1> 请查看" --at-open-dingtalk-ids + dws chat message edit --conversation-id --message-id --content '{"title":"标题","text":"更新后的内容"}'`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "message-id", "msg-id"); err != nil { return err } content, _ := cmd.Flags().GetString("content") @@ -4059,7 +4160,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 toolArgs := map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), "content": content, } if atAll { @@ -4094,7 +4195,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "编辑当前用户已发送消息的 Markdown 内容", UseWhen: []string{"已有会话 openConversationId 和消息 openMessageId，需要更正已发送消息的标题、正文或 @ 信息"}, AvoidWhen: []string{"发送新消息应使用 chat message send；撤回消息应使用 chat message recall"}, - Examples: []string{"dws chat message edit --conversation-id --msg-id --text \"更新后的内容\""}, + Examples: []string{"dws chat message edit --conversation-id --message-id --text \"更新后的内容\""}, }, Parameters: []contract.ParamDecl{ {Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"}, @@ -4102,9 +4203,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "content", Property: "content", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "msg-id", Property: "openMessageId", Required: boolPtr(true)}, + {Name: "message-id", Property: "openMessageId", Required: boolPtr(true)}, {Name: "text", Property: "text", Required: boolPtr(false)}, {Name: "title", Property: "title", Required: boolPtr(false)}, }, @@ -4120,18 +4220,20 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 dws chat message read-status --conversation-id --message-id --users userId1,userId2 dws chat message read-status --conversation-id --message-id --target-open-dingtalk-ids openDingTalkId1,openDingTalkId2 # 查询会话 ID: dws chat search --query "群名" - # 查询 openMessageId: dws chat message list --group --time "2025-03-01 00:00:00" + # 查询 openMessageId: dws chat message list --conversation-id --time "2025-03-01 00:00:00" # 查询人员: dws contact user search --keyword "姓名" --format json`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + conversationID, err := requireChatConversationID(cmd) + if err != nil { return err } - if err := validateRequiredFlags(cmd, "message-id"); err != nil { + messageID, err := chatMessageID(cmd) + if err != nil { return err } toolArgs := map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMessageId": mustGetFlag(cmd, "message-id"), + "openConversationId": conversationID, + "openMessageId": messageID, } if usersStr := flagOrFallback(cmd, "users", "user", "userId"); usersStr != "" { appendChatIDArgs(toolArgs, parseCSVValues(usersStr), "targetUserIds", "targetOpenDingTalkIds") @@ -4325,7 +4427,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatGroupMembersCmd.AddCommand(chatGroupMemberAddCmd, chatGroupMemberRemoveCmd, chatGroupMembersAddBotCmd) // message 子命令 flags - chatMessageListCmd.Flags().String("group", "", "群聊 openconversation_id（群聊时必填）") + chatMessageListCmd.Flags().String("conversation-id", "", "群聊 openconversation_id（群聊时必填）") chatMessageListCmd.Flags().String("user", "", "单聊用户 userId（单聊时与 --open-dingtalk-id 二选一）") chatMessageListCmd.Flags().String("open-dingtalk-id", "", "单聊用户 openDingTalkId（单聊时与 --user 二选一，适用于无法获取 userId 的场景）") chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)") @@ -4345,7 +4447,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageListDirectCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageListDirectCmd.Flags().MarkHidden("size") - chatMessageSendCmd.Flags().String("group", "", "群聊 openconversation_id（群聊时必填）") + chatMessageSendCmd.Flags().String("conversation-id", "", "群聊 openconversation_id（群聊时必填）") chatMessageSendCmd.Flags().String("user", "", "单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一）") chatMessageSendCmd.Flags().String("open-dingtalk-id", "", "单聊接收人 openDingTalkId（单聊时与 --user 二选一）") chatMessageSendCmd.Flags().String("title", "", "消息标题，显示在消息列表（可选，未指定时使用消息内容）") @@ -4384,8 +4486,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSendCmd.Flags().String("uuid", "", "幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选）") cli.AttachRuntimeSchema(chatMessageSendCmd, "chat", "send_personal_message", "hardcoded:chat") cli.AnnotateRuntimeConstraints(chatMessageSendCmd, cli.RuntimeSchemaConstraints{ - MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, - RequireOneOf: [][]string{{"group", "user", "open-dingtalk-id"}}, + MutuallyExclusive: [][]string{{"conversation-id", "user", "open-dingtalk-id"}}, + RequireOneOf: [][]string{{"conversation-id", "user", "open-dingtalk-id"}}, }) cli.AnnotateRuntimePositionals(chatMessageSendCmd, contract.RuntimeSchemaPositional{ Name: "content", @@ -4399,7 +4501,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSendByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)") _ = chatMessageSendByBotCmd.MarkFlagRequired("robot-code") - chatMessageSendByBotCmd.Flags().String("group", "", "群聊 openConversationId（群聊时必填）") + chatMessageSendByBotCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填）") chatMessageSendByBotCmd.Flags().String("users", "", "用户 userId 列表，逗号分隔，最多20个（单聊时必填）") chatMessageSendByBotCmd.Flags().String("msg-type", "", "消息类型: markdown/image/file（省略时为 markdown；图片使用 image --image-url；本地文件使用 file --file-path）") chatMessageSendByBotCmd.Flags().String("title", "", "Markdown 消息标题（发送 Markdown 时必填）") @@ -4414,7 +4516,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageRecallByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)") _ = chatMessageRecallByBotCmd.MarkFlagRequired("robot-code") - chatMessageRecallByBotCmd.Flags().String("group", "", "群聊 openConversationId（群聊撤回时必填）") + chatMessageRecallByBotCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊撤回时必填）") chatMessageRecallByBotCmd.Flags().String("keys", "", "消息 processQueryKey 列表，逗号分隔 (必填)") _ = chatMessageRecallByBotCmd.MarkFlagRequired("keys") @@ -4434,8 +4536,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 _ = chatBotSearchCmd.Flags().MarkHidden("limit") chatBotSearchCmd.Flags().String("name", "", "按名称搜索") - chatMessageListTopicRepliesCmd.Flags().String("group", "", "群会话 openconversationId (必填)") - _ = chatMessageListTopicRepliesCmd.MarkFlagRequired("group") + chatMessageListTopicRepliesCmd.Flags().String("conversation-id", "", "群会话 openconversationId (必填)") + _ = chatMessageListTopicRepliesCmd.MarkFlagRequired("conversation-id") chatMessageListTopicRepliesCmd.Flags().String("topic-id", "", "话题 ID，由 dws chat message list 返回 (必填)") _ = chatMessageListTopicRepliesCmd.MarkFlagRequired("topic-id") chatMessageListTopicRepliesCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss（可选）") @@ -4471,7 +4573,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AddPagedMCPFlags(chatMessageListBySenderCmd) // list-mentions flags - chatMessageListMentionsCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则查全部）") + chatMessageListMentionsCmd.Flags().String("conversation-id", "", "群聊 openconversation_id（可选，不传则查全部）") chatMessageListMentionsCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)") _ = chatMessageListMentionsCmd.MarkFlagRequired("start") chatMessageListMentionsCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)") @@ -4499,7 +4601,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSearchCmd.Flags().String("query", "", "搜索关键词 (必填)") chatMessageSearchCmd.Flags().String("keyword", "", "--query 的别名") _ = chatMessageSearchCmd.Flags().MarkHidden("keyword") - chatMessageSearchCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则搜索所有会话）") + chatMessageSearchCmd.Flags().String("conversation-id", "", "群聊 openconversation_id（可选，不传则搜索所有会话）") chatMessageSearchCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)") _ = chatMessageSearchCmd.MarkFlagRequired("start") chatMessageSearchCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)") @@ -4594,8 +4696,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 _ = chatMessageRecallCmd.Flags().MarkHidden("id") chatMessageRecallCmd.Flags().String("chat", "", "--conversation-id 的别名") _ = chatMessageRecallCmd.Flags().MarkHidden("chat") - chatMessageRecallCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageRecallCmd.MarkFlagRequired("msg-id") + chatMessageRecallCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageRecallCmd.MarkFlagRequired("message-id") // edit flags chatMessageEditCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填)") @@ -4605,8 +4707,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 _ = chatMessageEditCmd.Flags().MarkHidden("id") chatMessageEditCmd.Flags().String("chat", "", "--conversation-id 的别名") _ = chatMessageEditCmd.Flags().MarkHidden("chat") - chatMessageEditCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageEditCmd.MarkFlagRequired("msg-id") + chatMessageEditCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageEditCmd.MarkFlagRequired("message-id") chatMessageEditCmd.Flags().String("text", "", "编辑后的 Markdown 正文；与 --content 二选一") chatMessageEditCmd.Flags().String("title", "", "消息标题；配合 --text 使用，未传时从正文自动生成") chatMessageEditCmd.Flags().String("content", "", "完整 Markdown content JSON；与 --text 二选一") @@ -4625,8 +4727,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSearchCmd, } for _, c := range groupAliasCmds { - c.Flags().String("conversation-id", "", "--group 的别名") - _ = c.Flags().MarkHidden("conversation-id") + c.Flags().String("group", "", "--conversation-id 的别名") + _ = c.Flags().MarkHidden("group") if c.Flags().Lookup("id") == nil { c.Flags().String("id", "", "--group 的别名") _ = c.Flags().MarkHidden("id") @@ -4641,11 +4743,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Short: "获取会话基础信息", Long: `获取指定会话的基础信息。 发送本地文件消息请优先使用 dws chat message send --msg-type file --file-path <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`, - Example: ` dws chat conversation-info --group --format json + Example: ` dws chat conversation-info --conversation-id --format json dws chat conversation-info --user --format json dws chat conversation-info --open-dingtalk-id --format json`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") rawOpenDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") rawUserID := flagOrFallback(cmd, "user", "userId") specified := 0 @@ -4714,20 +4816,19 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "获取群聊或单聊会话的详细信息", UseWhen: []string{"已知群 ID 或用户标识并需要解析会话详情时"}, AvoidWhen: []string{"按群名查找会话时使用 chat search"}, - Examples: []string{"dws chat conversation-info --group --format json"}, + Examples: []string{"dws chat conversation-info --conversation-id --format json"}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "open-dingtalk-id", Property: "openDingTalkId"}, {Name: "user", Property: "openDingTalkId"}, }, }, }) - chatConversationInfoCmd.Flags().String("group", "", "群聊 openConversationId（群聊时使用）") - chatConversationInfoCmd.Flags().String("conversation-id", "", "--group 的别名") + chatConversationInfoCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时使用）") + chatConversationInfoCmd.Flags().String("group", "", "--conversation-id 的别名") chatConversationInfoCmd.Flags().String("id", "", "--group 的别名") chatConversationInfoCmd.Flags().String("chat", "", "--group 的别名") - _ = chatConversationInfoCmd.Flags().MarkHidden("conversation-id") + _ = chatConversationInfoCmd.Flags().MarkHidden("group") _ = chatConversationInfoCmd.Flags().MarkHidden("id") _ = chatConversationInfoCmd.Flags().MarkHidden("chat") chatConversationInfoCmd.Flags().String("user", "", "单聊对方 userId（单聊时使用）") @@ -4751,15 +4852,15 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Long: `chat file upload 已下线，不再调用 chat/upload_conversation_file_by_url。 发送本地文件消息请改用 chat message send --msg-type file --file-path；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`, - Example: ` dws chat message send --group --msg-type file --file-path ./report.pdf --format json + Example: ` dws chat message send --conversation-id --msg-type file --file-path ./report.pdf --format json dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf --format json`, RunE: func(cmd *cobra.Command, args []string) error { return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file-path <本地路径>") }, } - chatFileUploadCmd.Flags().String("group", "", "群聊 openConversationId（群聊时使用）") - chatFileUploadCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatFileUploadCmd.Flags().MarkHidden("conversation-id") + chatFileUploadCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时使用）") + chatFileUploadCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatFileUploadCmd.Flags().MarkHidden("group") chatFileUploadCmd.Flags().String("id", "", "--group 的别名") _ = chatFileUploadCmd.Flags().MarkHidden("id") chatFileUploadCmd.Flags().String("chat", "", "--group 的别名") @@ -5024,13 +5125,13 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Use: "add-conv", Short: "将会话移动到指定的自定义分组中", Long: `将某个会话添加到一批用户自定义会话分组中。需指定会话 openConversationId 和目标分组 ID 列表。`, - Example: ` dws chat category add-conv --group --category-ids 123,456 + Example: ` dws chat category add-conv --conversation-id --category-ids 123,456 # 分组ID 可通过 dws chat category list 获取 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id") if groupID == "" { - return fmt.Errorf("flag --group is required") + return fmt.Errorf("flag --conversation-id is required") } if err := validateRequiredFlags(cmd, "category-ids"); err != nil { return err @@ -5068,12 +5169,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "将会话加入一个或多个自定义会话分组", UseWhen: []string{"已有会话 openConversationId 和目标 categoryId，需要把会话归入分组时"}, AvoidWhen: []string{"从分组移除会话时使用 chat category remove-conv"}, - Examples: []string{"dws chat category add-conv --group --category-ids 123,456"}, + Examples: []string{"dws chat category add-conv --conversation-id --category-ids 123,456"}, }, Parameters: []contract.ParamDecl{ {Name: "category-ids", Property: "categoryIds", Required: boolPtr(true), InterfaceType: "array"}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5083,11 +5183,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Use: "remove-conv", Short: "将会话从指定的自定义分组中移出", Long: `将某个会话从一批用户自定义会话分组中移出。需指定会话 openConversationId 和目标分组 ID 列表。`, - Example: ` dws chat category remove-conv --group --category-ids 123,456 + Example: ` dws chat category remove-conv --conversation-id --category-ids 123,456 # 分组ID 可通过 dws chat category list 获取 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id") if groupID == "" { return fmt.Errorf("flag --group is required") } @@ -5127,12 +5227,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "将会话从一个或多个自定义会话分组移出", UseWhen: []string{"已有会话 openConversationId 和 categoryId，需要取消会话分组归属时"}, AvoidWhen: []string{"向分组加入会话时使用 chat category add-conv"}, - Examples: []string{"dws chat category remove-conv --group --category-ids 123,456"}, + Examples: []string{"dws chat category remove-conv --conversation-id --category-ids 123,456"}, }, Parameters: []contract.ParamDecl{ {Name: "category-ids", Property: "categoryIds", Required: boolPtr(true), InterfaceType: "array"}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5142,10 +5241,10 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 Use: "list-by-conv", Short: "拉取指定会话所属的用户自定义会话分组", Long: `拉取指定会话所属的用户自定义会话分组。需指定会话 openConversationId。`, - Example: ` dws chat category list-by-conv --group + Example: ` dws chat category list-by-conv --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id") if groupID == "" { return fmt.Errorf("flag --group is required") } @@ -5177,11 +5276,10 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "查询指定会话所属的自定义会话分组", UseWhen: []string{"已有会话 openConversationId，需要反查该会话被放入了哪些自定义分组"}, AvoidWhen: []string{"列出全部自定义分组应使用 chat category list；按 categoryId 查详情应使用 chat category batch-info"}, - Examples: []string{"dws chat category list-by-conv --group "}, + Examples: []string{"dws chat category list-by-conv --conversation-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5335,18 +5433,21 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageAddEmojiCmd := &cobra.Command{ Use: "add-emoji", Short: "对消息添加 emoji 表情回应", - Example: ` dws chat message add-emoji --conversation-id --msg-id --emoji "赞" + Example: ` dws chat message add-emoji --conversation-id --message-id --emoji "赞" # 查询会话 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id", "emoji"); err != nil { + if _, err := chatMessageID(cmd); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "emoji"); err != nil { return err } return callMCPToolOnServer("im", "add_emoji_reaction", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMsgId": mustGetFlag(cmd, "msg-id"), + "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emojiName": mustGetFlag(cmd, "emoji"), }) }, @@ -5374,15 +5475,14 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "给指定消息添加表情回应", UseWhen: []string{"需要对已有消息添加一个 emoji reaction 时"}, AvoidWhen: []string{"发送文本消息或文字表情时不要使用"}, - Examples: []string{"dws chat message add-emoji --conversation-id --msg-id --emoji \"赞\""}, + Examples: []string{"dws chat message add-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, - {Name: "msg-id", Property: "openMsgId"}, + {Name: "message-id", Property: "openMsgId"}, }, }, }) @@ -5390,24 +5490,27 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageAddEmojiCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("chat", "", "--conversation-id 的别名") - chatMessageAddEmojiCmd.Flags().String("msg-id", "", "消息 openMsgId (必填)") + chatMessageAddEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageAddEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") chatMessageRemoveEmojiCmd := &cobra.Command{ Use: "remove-emoji", Short: "移除消息的 emoji 表情回应", - Example: ` dws chat message remove-emoji --conversation-id --msg-id --emoji "赞" + Example: ` dws chat message remove-emoji --conversation-id --message-id --emoji "赞" # 查询会话 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id", "emoji"); err != nil { + if _, err := chatMessageID(cmd); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "emoji"); err != nil { return err } return callMCPToolOnServer("im", "remove_emoji_reaction", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMsgId": mustGetFlag(cmd, "msg-id"), + "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emojiName": mustGetFlag(cmd, "emoji"), }) }, @@ -5435,15 +5538,14 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "移除指定消息上的表情回应", UseWhen: []string{"需要取消此前添加的 emoji reaction 时"}, AvoidWhen: []string{"移除文字表情时使用 chat message remove-text-emotion"}, - Examples: []string{"dws chat message remove-emoji --conversation-id --msg-id --emoji \"赞\""}, + Examples: []string{"dws chat message remove-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, - {Name: "msg-id", Property: "openMsgId"}, + {Name: "message-id", Property: "openMsgId"}, }, }, }) @@ -5451,23 +5553,26 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageRemoveEmojiCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("chat", "", "--conversation-id 的别名") - chatMessageRemoveEmojiCmd.Flags().String("msg-id", "", "消息 openMsgId (必填)") + chatMessageRemoveEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageRemoveEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") chatMessageAddTextEmotionCmd := &cobra.Command{ Use: "add-text-emotion", Short: "对消息添加文字表情回应", - Example: ` dws chat message add-text-emotion --conversation-id --msg-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, + Example: ` dws chat message add-text-emotion --conversation-id --message-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id", "emotion-id", "emotion-name", "text", "background-id"); err != nil { + if _, err := chatMessageID(cmd); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "emotion-id", "emotion-name", "text", "background-id"); err != nil { return err } return callMCPToolOnServer("im", "add_text_emotion", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMsgId": mustGetFlag(cmd, "msg-id"), + "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), "emotionName": mustGetFlag(cmd, "emotion-name"), "text": mustGetFlag(cmd, "text"), @@ -5498,14 +5603,13 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "给指定消息添加已定义的文字表情", UseWhen: []string{"已有文字表情定义并要附加到消息时"}, AvoidWhen: []string{"需要先创建文字表情资源时使用 chat message create-text-emotion"}, - Examples: []string{"dws chat message add-text-emotion --conversation-id --msg-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, + Examples: []string{"dws chat message add-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "msg-id", Property: "openMsgId"}, + {Name: "message-id", Property: "openMsgId"}, }, }, }) @@ -5513,7 +5617,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageAddTextEmotionCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageAddTextEmotionCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageAddTextEmotionCmd.Flags().String("chat", "", "--conversation-id 的别名") - chatMessageAddTextEmotionCmd.Flags().String("msg-id", "", "消息 openMsgId (必填)") + chatMessageAddTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageAddTextEmotionCmd.Flags().String("emotion-id", "", "表情 ID (必填，通过 create-text-emotion 获取)") chatMessageAddTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") chatMessageAddTextEmotionCmd.Flags().String("text", "", "文字内容 (必填)") @@ -5522,17 +5626,20 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageRemoveTextEmotionCmd := &cobra.Command{ Use: "remove-text-emotion", Short: "移除消息的文字表情回应", - Example: ` dws chat message remove-text-emotion --conversation-id --msg-id --emotion-id --emotion-name "赞" --text "nice" --background-id `, + Example: ` dws chat message remove-text-emotion --conversation-id --message-id --emotion-id --emotion-name "赞" --text "nice" --background-id `, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } - if err := validateRequiredFlags(cmd, "msg-id", "emotion-id", "emotion-name", "text", "background-id"); err != nil { + if _, err := chatMessageID(cmd); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "emotion-id", "emotion-name", "text", "background-id"); err != nil { return err } return callMCPToolOnServer("im", "remove_text_emotion", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMsgId": mustGetFlag(cmd, "msg-id"), + "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), "emotionName": mustGetFlag(cmd, "emotion-name"), "text": mustGetFlag(cmd, "text"), @@ -5563,14 +5670,13 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 AgentSummary: "移除指定消息上的文字表情回应", UseWhen: []string{"需要取消已添加的文字表情时"}, AvoidWhen: []string{"移除普通 emoji reaction 时使用 chat message remove-emoji"}, - Examples: []string{"dws chat message remove-text-emotion --conversation-id --msg-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, + Examples: []string{"dws chat message remove-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "msg-id", Property: "openMsgId"}, + {Name: "message-id", Property: "openMsgId"}, }, }, }) @@ -5578,7 +5684,7 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageRemoveTextEmotionCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageRemoveTextEmotionCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageRemoveTextEmotionCmd.Flags().String("chat", "", "--conversation-id 的别名") - chatMessageRemoveTextEmotionCmd.Flags().String("msg-id", "", "消息 openMsgId (必填)") + chatMessageRemoveTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("emotion-id", "", "表情 ID (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("text", "", "文字内容 (必填)") @@ -5587,14 +5693,20 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageUpdateTextEmotionCmd := &cobra.Command{ Use: "update-text-emotion", Short: "更新消息的文字表情回应", - Example: ` dws chat message update-text-emotion --conversation-id --msg-id --old-emotion-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, + Example: ` dws chat message update-text-emotion --conversation-id --message-id --old-emotion-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { return err } + if _, err := chatMessageID(cmd); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "old-emotion-id", "emotion-id", "emotion-name", "text", "background-id"); err != nil { + return err + } return callMCPToolOnServer("im", "update_text_emotion", map[string]any{ "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), - "openMsgId": mustGetFlag(cmd, "msg-id"), + "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "oldEmotionId": mustGetFlag(cmd, "old-emotion-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), "emotionName": mustGetFlag(cmd, "emotion-name"), @@ -5629,34 +5741,28 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 "消息上还没有文字表情时使用 chat message add-text-emotion", "只需清除文字表情时使用 chat message remove-text-emotion", }, - Examples: []string{"dws chat message update-text-emotion --conversation-id --msg-id --old-emotion-id --emotion-id --emotion-name \"处理中\" --text \"处理中 2 分钟\" --background-id im_bg_5"}, + Examples: []string{"dws chat message update-text-emotion --conversation-id --message-id --old-emotion-id --emotion-id --emotion-name \"处理中\" --text \"处理中 2 分钟\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ {Name: "background-id", Property: "backgroundId", Required: boolPtr(true), Description: "新文字表情的背景 ID"}, - {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId；与 --group、--id、--chat 四选一"}, + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId"}, {Name: "emotion-id", Property: "emotionId", Required: boolPtr(true), Description: "新的文字表情 ID，可通过 create-text-emotion 获取"}, {Name: "emotion-name", Property: "emotionName", Required: boolPtr(true), Description: "新的文字表情名称"}, - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "msg-id", Property: "openMsgId", Required: boolPtr(true), Description: "需要原地更新文字表情的消息 openMsgId"}, + {Name: "message-id", Property: "openMsgId", Required: boolPtr(true), Description: "需要原地更新文字表情的消息 openMsgId"}, {Name: "old-emotion-id", Property: "oldEmotionId", Required: boolPtr(true), Description: "消息上当前文字表情的 emotionId"}, {Name: "text", Property: "text", Required: boolPtr(true), Description: "新的文字表情内容"}, }, }, }) chatMessageUpdateTextEmotionCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填，支持单聊/群聊)") - chatMessageUpdateTextEmotionCmd.Flags().String("group", "", "--conversation-id 的别名") - chatMessageUpdateTextEmotionCmd.Flags().String("id", "", "--conversation-id 的别名") - chatMessageUpdateTextEmotionCmd.Flags().String("chat", "", "--conversation-id 的别名") - chatMessageUpdateTextEmotionCmd.Flags().String("msg-id", "", "消息 openMsgId (必填)") + chatMessageUpdateTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("old-emotion-id", "", "待更新的原表情 ID (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("emotion-id", "", "新表情 ID (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("emotion-name", "", "新表情名称 (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("text", "", "新文字内容 (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("background-id", "", "新背景 ID (必填)") - chatMessageUpdateTextEmotionCmd.MarkFlagsOneRequired("conversation-id", "group", "id", "chat") - for _, name := range []string{"msg-id", "old-emotion-id", "emotion-id", "emotion-name", "text", "background-id"} { + _ = chatMessageUpdateTextEmotionCmd.MarkFlagRequired("conversation-id") + for _, name := range []string{"message-id", "old-emotion-id", "emotion-id", "emotion-name", "text", "background-id"} { _ = chatMessageUpdateTextEmotionCmd.MarkFlagRequired(name) } @@ -5720,24 +5826,24 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSendCardCmd := &cobra.Command{ Use: "send-card", Short: "创建并推送流式卡片", - Long: `向群聊或单聊创建并推送流式卡片。群聊传 --group，单聊传 --receiver，二者互斥。 + Long: `向群聊或单聊创建并推送流式卡片。群聊传 --conversation-id，单聊传 --receiver，二者互斥。 创建时无需传入卡片内容，后续通过 update-card 更新内容。 注意：send-card 必须和 update-card 搭配使用。发送卡片后，使用返回的 bizId 调用 update-card 更新内容， 最后一次更新必须将 --flow-status 设为 3（finish），否则卡片会一直处于"生成中"的加载状态。 flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成(FINISH)，4=执行中(EXECUTING)，5=错误(ERROR)。`, - Example: ` dws chat message send-card --group + Example: ` dws chat message send-card --conversation-id dws chat message send-card --receiver # 查询群 ID: dws chat search --query "群名" # 查询人员: dws contact user search --keyword "姓名" --format json`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") receiver, _ := cmd.Flags().GetString("receiver") if groupID == "" && receiver == "" { - return fmt.Errorf("--group or --receiver is required") + return fmt.Errorf("--conversation-id or --receiver is required") } if groupID != "" && receiver != "" { - return fmt.Errorf("--group and --receiver are mutually exclusive") + return fmt.Errorf("--conversation-id and --receiver are mutually exclusive") } toolArgs := map[string]any{} if groupID != "" { @@ -5776,16 +5882,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "创建并向群聊或单聊发送互动卡片", UseWhen: []string{"需要卡片式交互且已准备接收会话或用户时"}, AvoidWhen: []string{"只发送普通文本时使用 send 或 send-by-bot"}, - Examples: []string{"dws chat message send-card --group "}, + Examples: []string{"dws chat message send-card --conversation-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "receiver", Property: "receiverOpenDingTalkId"}, }, }, }) - chatMessageSendCardCmd.Flags().String("group", "", "群聊 openConversationId（群聊时必填，与 --receiver 互斥）") - chatMessageSendCardCmd.Flags().String("receiver", "", "单聊接收者 openDingTalkId（单聊时必填，与 --group 互斥）") + chatMessageSendCardCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填，与 --receiver 互斥）") + chatMessageSendCardCmd.Flags().String("receiver", "", "单聊接收者 openDingTalkId（单聊时必填，与 --conversation-id 互斥）") chatMessageUpdateCardCmd := &cobra.Command{ Use: "update-card", @@ -6069,13 +6174,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 chatGroupTransferOwnerCmd := &cobra.Command{ Use: "transfer-owner", Short: "转让群主", - Example: ` dws chat group transfer-owner --group --new-owner - dws chat group transfer-owner --group --user + Example: ` dws chat group transfer-owner --conversation-id --new-owner + dws chat group transfer-owner --conversation-id --user # 查询群 ID: dws chat search --query "群名" # 查询 openDingTalkId: dws contact user search --query "姓名" # 查询 userId: dws contact user search --query "姓名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } newOwnerOpenDingTalkID, _ := cmd.Flags().GetString("new-owner") @@ -6092,12 +6197,12 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 } if !isOpenDingTalkID(newOwner) { return callMCPToolOnServer("im", "transfer_group_owner", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "newOwnerUid": newOwner, }) } return callMCPToolOnServer("im", "transfer_group_owner", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "newOwnerOpenDingTalkId": newOwner, }) }, @@ -6125,16 +6230,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "把群主身份转让给指定群成员", UseWhen: []string{"现群主明确指定新群主时"}, AvoidWhen: []string{"只是授予管理员权限时使用 chat group set-admin"}, - Examples: []string{"dws chat group transfer-owner --group --new-owner "}, + Examples: []string{"dws chat group transfer-owner --conversation-id --new-owner "}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "new-owner", Property: "newOwnerOpenDingTalkId"}, }, }, }) - chatGroupTransferOwnerCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupTransferOwnerCmd.MarkFlagRequired("group") + chatGroupTransferOwnerCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupTransferOwnerCmd.MarkFlagRequired("conversation-id") chatGroupTransferOwnerCmd.Flags().String("new-owner", "", "新群主 openDingTalkId") chatGroupTransferOwnerCmd.Flags().String("user", "", "新群主 userId") chatGroupTransferOwnerCmd.Flags().String("userId", "", "--user 的别名") @@ -6144,16 +6248,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "invite-url", Short: "获取群邀请链接", Long: `获取群聊邀请链接。可选 --expires-seconds 指定链接有效期（秒），0 表示永久有效，不传则使用服务端默认值。`, - Example: ` dws chat group invite-url --group - dws chat group invite-url --group --expires-seconds 86400 - dws chat group invite-url --group --expires-seconds 0 + Example: ` dws chat group invite-url --conversation-id + dws chat group invite-url --conversation-id --expires-seconds 86400 + dws chat group invite-url --conversation-id --expires-seconds 0 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), } if v, _ := cmd.Flags().GetInt64("expires-seconds"); v >= 0 && cmd.Flags().Changed("expires-seconds") { toolArgs["expiresSeconds"] = v @@ -6184,15 +6288,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "获取指定群聊的邀请链接", UseWhen: []string{"需要生成群邀请链接或设置有效期时"}, AvoidWhen: []string{"需要直接添加已知成员时使用 chat group members add"}, - Examples: []string{"dws chat group invite-url --group --expires-seconds 86400"}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group invite-url --conversation-id --expires-seconds 86400"}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupInviteUrlCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupInviteUrlCmd.MarkFlagRequired("group") + chatGroupInviteUrlCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupInviteUrlCmd.MarkFlagRequired("conversation-id") chatGroupInviteUrlCmd.Flags().Int64("expires-seconds", 0, "链接有效期（秒），0 表示永久有效，不传使用服务端默认值") chatMuteCmd := &cobra.Command{ @@ -6259,14 +6361,14 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "quit", Short: "退出群聊", Long: `当前用户退出指定群聊。退出后将无法查看群消息。`, - Example: ` dws chat group quit --group + Example: ` dws chat group quit --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } return callMCPToolOnServer("im", "quit_group", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), }) }, } @@ -6296,24 +6398,22 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 "需要永久解散整个群时使用 chat group dismiss", "需要踢出其他成员时使用 chat group members remove", }, - Examples: []string{"dws chat group quit --group "}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group quit --conversation-id "}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupQuitCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupQuitCmd.MarkFlagRequired("group") + chatGroupQuitCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupQuitCmd.MarkFlagRequired("conversation-id") chatGroupUpdateIconCmd := &cobra.Command{ Use: "update-icon", Short: "更新群头像", Long: `更新指定群聊的群头像。需传入群 ID 和头像 mediaId。`, - Example: ` dws chat group update-icon --group --icon-media-id + Example: ` dws chat group update-icon --conversation-id --icon-media-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "icon-media-id"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "icon-media-id"); err != nil { return err } iconMediaID := strings.TrimSpace(mustGetFlag(cmd, "icon-media-id")) @@ -6321,7 +6421,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 return fmt.Errorf("invalid --icon-media-id: mediaId 不能为空\n hint: 请使用上游媒体上传能力返回的有效 mediaId；DWS CLI 不提供本地文件到 mediaId 的上传命令") } return callMCPToolOnServer("im", "update_group_icon", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "iconMediaId": iconMediaID, }) }, @@ -6349,15 +6449,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "使用真实媒体 ID 更新群头像", UseWhen: []string{"已有上传后的头像 mediaId 并要修改群头像时"}, AvoidWhen: []string{"没有真实可用 mediaId 时先完成媒体上传"}, - Examples: []string{"dws chat group update-icon --group --icon-media-id @mediaId"}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group update-icon --conversation-id --icon-media-id @mediaId"}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupUpdateIconCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupUpdateIconCmd.MarkFlagRequired("group") + chatGroupUpdateIconCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupUpdateIconCmd.MarkFlagRequired("conversation-id") chatGroupUpdateIconCmd.Flags().String("icon-media-id", "", "群头像 mediaId (必填)") _ = chatGroupUpdateIconCmd.MarkFlagRequired("icon-media-id") @@ -6384,11 +6482,11 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 groupRedEnvelopeSwitch 发红包 groupLiveAuthority 谁可以发起直播 groupBillAuthority 群收款开关`, - Example: ` dws chat group update-settings --group --setting-key searchable --status 1 - dws chat group update-settings --group --setting-key onlyAdminCanAtAll --status 0 + Example: ` dws chat group update-settings --conversation-id --setting-key searchable --status 1 + dws chat group update-settings --conversation-id --setting-key onlyAdminCanAtAll --status 0 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "setting-key"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "setting-key"); err != nil { return err } if !cmd.Flags().Changed("status") { @@ -6396,7 +6494,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 } status, _ := cmd.Flags().GetInt("status") return callMCPToolOnServer("im", "update_group_settings", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "settingKey": mustGetFlag(cmd, "setting-key"), "status": status, }) @@ -6425,15 +6523,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "更新指定群聊的一项设置开关", UseWhen: []string{"需要调整 searchable、入群验证或群权限等设置时"}, AvoidWhen: []string{"全员禁言和成员禁言使用专门的 mute 命令"}, - Examples: []string{"dws chat group update-settings --group --setting-key searchable --status 1"}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group update-settings --conversation-id --setting-key searchable --status 1"}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupUpdateSettingsCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupUpdateSettingsCmd.MarkFlagRequired("group") + chatGroupUpdateSettingsCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupUpdateSettingsCmd.MarkFlagRequired("conversation-id") chatGroupUpdateSettingsCmd.Flags().String("setting-key", "", "群设置项 key (必填)") _ = chatGroupUpdateSettingsCmd.MarkFlagRequired("setting-key") chatGroupUpdateSettingsCmd.Flags().Int("status", 0, "设置值: 0=关闭, 1=开启 (必填)") @@ -6563,7 +6659,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 } toolArgs := map[string]any{ "srcOpenCid": mustGetFlag(cmd, "src-conversation-id"), - "srcOpenMessageId": mustGetFlag(cmd, "msg-id"), + "srcOpenMessageId": flagOrFallback(cmd, "message-id", "msg-id"), "destOpenCid": mustGetFlag(cmd, "dest-conversation-id"), } if v, _ := cmd.Flags().GetString("uuid"); v != "" { @@ -6599,15 +6695,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 }, Parameters: []contract.ParamDecl{ {Name: "dest-conversation-id", Property: "destOpenCid"}, - {Name: "msg-id", Property: "srcOpenMessageId"}, + {Name: "message-id", Property: "srcOpenMessageId"}, {Name: "src-conversation-id", Property: "srcOpenCid"}, }, }, }) chatMessageForwardCmd.Flags().String("src-conversation-id", "", "源会话 openConversationId (必填，支持单聊/群聊)") _ = chatMessageForwardCmd.MarkFlagRequired("src-conversation-id") - chatMessageForwardCmd.Flags().String("msg-id", "", "源消息 openMessageId (必填)") - _ = chatMessageForwardCmd.MarkFlagRequired("msg-id") + chatMessageForwardCmd.Flags().String("message-id", "", "源消息 openMessageId (必填)") + _ = chatMessageForwardCmd.MarkFlagRequired("message-id") chatMessageForwardCmd.Flags().String("dest-conversation-id", "", "目标会话 openConversationId (必填，支持单聊/群聊)") _ = chatMessageForwardCmd.MarkFlagRequired("dest-conversation-id") chatMessageForwardCmd.Flags().String("uuid", "", "幂等键（可选）") @@ -6677,13 +6773,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Short: "查询群用户禁言配置", Long: `查询指定群的用户禁言配置，包括单独禁言黑名单、全员禁言白名单及相关操作时间。 返回的是原始配置记录，不等同于当前被禁言成员列表；全员禁言开关也不在本命令的返回范围内。`, - Example: ` dws chat group get-mute-config --group `, + Example: ` dws chat group get-mute-config --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } return callMCPToolOnServer("im", "get_group_mute_config", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), }) }, } @@ -6710,11 +6806,11 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "查询群用户禁言配置（禁言黑名单/全员禁言白名单）", UseWhen: []string{"用户说 看下群里谁被禁言/禁言配置"}, AvoidWhen: []string{"设置全员禁言用 chat group-mute；禁言个人用 chat group-mute-member"}, - Examples: []string{"dws chat group get-mute-config --group --format json"}, + Examples: []string{"dws chat group get-mute-config --conversation-id --format json"}, }, }, }) - chatGroupGetMuteConfigCmd.Flags().String("group", "", "群聊 openConversationId (必填)") + chatGroupGetMuteConfigCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") chatGroupCmd.AddCommand(chatGroupGetMuteConfigCmd) // ── group-mute: 全员禁言 ─────────────────────────────── @@ -6723,13 +6819,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "group-mute", Short: "全员禁言 / 取消全员禁言", Long: `设置或取消群全员禁言。默认开启全员禁言，传 --off 则取消。`, - Example: ` dws chat group-mute --group - dws chat group-mute --group --off + Example: ` dws chat group-mute --conversation-id + dws chat group-mute --conversation-id --off # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") if groupID == "" { - return fmt.Errorf("flag --group is required\n hint: dws chat group-mute --group ") + return fmt.Errorf("flag --group is required\n hint: dws chat group-mute --conversation-id ") } off, _ := cmd.Flags().GetBool("off") return callMCPToolOnServer("im", "set_group_mute", map[string]any{ @@ -6761,17 +6857,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "开启或关闭群聊全员禁言", UseWhen: []string{"需要控制整个群的发言权限时"}, AvoidWhen: []string{"只禁言指定成员时使用 chat group-mute-member"}, - Examples: []string{"dws chat group-mute --group "}, + Examples: []string{"dws chat group-mute --conversation-id "}, }, Parameters: []contract.ParamDecl{ {Name: "off", Property: "mute", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId"}, }, }, }) - chatGroupMuteCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - chatGroupMuteCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatGroupMuteCmd.Flags().MarkHidden("conversation-id") + chatGroupMuteCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + chatGroupMuteCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatGroupMuteCmd.Flags().MarkHidden("group") chatGroupMuteCmd.Flags().String("id", "", "--group 的别名") _ = chatGroupMuteCmd.Flags().MarkHidden("id") chatGroupMuteCmd.Flags().String("chat", "", "--group 的别名") @@ -6786,15 +6881,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Long: `将指定群成员加入或移出禁言名单。 --mute-time 禁言时长（毫秒），仅支持 5min(300000) / 1h(3600000) / 1d(86400000) / 7d(604800000) / 30d(2592000000)。 默认加入禁言名单，传 --off 则移除。`, - Example: ` dws chat group-mute-member --group --users userId1,userId2 --mute-time 3600000 - dws chat group-mute-member --group --user userId1 --mute-time 3600000 - dws chat group-mute-member --group --user userId1,userId2 --off + Example: ` dws chat group-mute-member --conversation-id --users userId1,userId2 --mute-time 3600000 + dws chat group-mute-member --conversation-id --user userId1 --mute-time 3600000 + dws chat group-mute-member --conversation-id --user userId1,userId2 --off # 查询群 ID: dws chat search --query "群名" # 查询人员: dws contact user search --keyword "姓名" --format json`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") if groupID == "" { - return fmt.Errorf("flag --group is required\n hint: dws chat group-mute-member --group --user --mute-time ") + return fmt.Errorf("flag --group is required\n hint: dws chat group-mute-member --conversation-id --user --mute-time ") } usersRaw := flagOrFallback(cmd, "users", "user", "userId") if usersRaw == "" { @@ -6856,18 +6951,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "禁言或解除禁言指定群成员", UseWhen: []string{"需要按成员设置禁言时长或解除禁言时"}, AvoidWhen: []string{"需要全员禁言时使用 chat group-mute"}, - Examples: []string{"dws chat group-mute-member --group --users userId1,userId2 --mute-time 3600000"}, + Examples: []string{"dws chat group-mute-member --conversation-id --users userId1,userId2 --mute-time 3600000"}, }, Parameters: []contract.ParamDecl{ {Name: "off", Property: "mute", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId"}, {Name: "users", Property: "openDingTalkIds"}, }, }, }) - chatGroupMuteMemberCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - chatGroupMuteMemberCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatGroupMuteMemberCmd.Flags().MarkHidden("conversation-id") + chatGroupMuteMemberCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + chatGroupMuteMemberCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatGroupMuteMemberCmd.Flags().MarkHidden("group") chatGroupMuteMemberCmd.Flags().String("id", "", "--group 的别名") _ = chatGroupMuteMemberCmd.Flags().MarkHidden("id") chatGroupMuteMemberCmd.Flags().String("chat", "", "--group 的别名") @@ -6885,13 +6979,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "set-admin", Short: "设置 / 取消群管理员", Long: `将指定群成员设置为管理员或取消管理员身份。默认设为管理员，传 --off 则取消。`, - Example: ` dws chat group set-admin --group --users userId1,userId2 - dws chat group set-admin --group --user userId1 - dws chat group set-admin --group --user userId1 --off + Example: ` dws chat group set-admin --conversation-id --users userId1,userId2 + dws chat group set-admin --conversation-id --user userId1 + dws chat group set-admin --conversation-id --user userId1 --off # 查询群 ID: dws chat search --query "群名" # 查询人员: dws contact user search --keyword "姓名" --format json`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } usersRaw := flagOrFallback(cmd, "users", "user", "userId") @@ -6901,7 +6995,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 userIDs, openDingTalkIDs := splitChatIDValues(parseCSVValues(usersRaw)) off, _ := cmd.Flags().GetBool("off") toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "admin": !off, } if len(userIDs) > 0 { @@ -6936,17 +7030,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "设置或取消群管理员角色", UseWhen: []string{"需要变更指定成员的群管理员身份时"}, AvoidWhen: []string{"自定义业务角色应使用 chat group-role 系列命令"}, - Examples: []string{"dws chat group set-admin --group --users userId1,userId2"}, + Examples: []string{"dws chat group set-admin --conversation-id --users userId1,userId2"}, }, Parameters: []contract.ParamDecl{ {Name: "off", Property: "admin", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId"}, {Name: "users", Property: "openDingTalkIds"}, }, }, }) - chatGroupSetAdminCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupSetAdminCmd.MarkFlagRequired("group") + chatGroupSetAdminCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupSetAdminCmd.MarkFlagRequired("conversation-id") chatGroupSetAdminCmd.Flags().String("users", "", "成员 userId 列表，逗号分隔（批量）") chatGroupSetAdminCmd.Flags().String("user", "", "成员 userId，支持逗号分隔") chatGroupSetAdminCmd.Flags().String("userId", "", "--user 的别名") @@ -6979,30 +7072,31 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 _ = chatCategoryRenameCmd.MarkFlagRequired("title") // category add-conv flags - chatCategoryAddConvCmd.Flags().String("group", "", "会话 openConversationId (必填)") - chatCategoryAddConvCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatCategoryAddConvCmd.Flags().MarkHidden("conversation-id") + chatCategoryAddConvCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填)") + chatCategoryAddConvCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatCategoryAddConvCmd.Flags().MarkHidden("group") chatCategoryAddConvCmd.Flags().String("id", "", "--group 的别名") _ = chatCategoryAddConvCmd.Flags().MarkHidden("id") chatCategoryAddConvCmd.Flags().String("category-ids", "", "目标分组 ID 列表，逗号分隔 (必填)") _ = chatCategoryAddConvCmd.MarkFlagRequired("category-ids") // category remove-conv flags - chatCategoryRemoveConvCmd.Flags().String("group", "", "会话 openConversationId (必填)") - chatCategoryRemoveConvCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatCategoryRemoveConvCmd.Flags().MarkHidden("conversation-id") + chatCategoryRemoveConvCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填)") + chatCategoryRemoveConvCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatCategoryRemoveConvCmd.Flags().MarkHidden("group") chatCategoryRemoveConvCmd.Flags().String("id", "", "--group 的别名") _ = chatCategoryRemoveConvCmd.Flags().MarkHidden("id") chatCategoryRemoveConvCmd.Flags().String("category-ids", "", "目标分组 ID 列表，逗号分隔 (必填)") _ = chatCategoryRemoveConvCmd.MarkFlagRequired("category-ids") // category list-by-conv flags - chatCategoryListByConvCmd.Flags().String("group", "", "会话 openConversationId (必填)") - chatCategoryListByConvCmd.Flags().String("conversation-id", "", "--group 的别名") - _ = chatCategoryListByConvCmd.Flags().MarkHidden("conversation-id") + chatCategoryListByConvCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填)") + _ = chatCategoryListByConvCmd.MarkFlagRequired("conversation-id") + chatCategoryListByConvCmd.Flags().String("group", "", "--conversation-id 的别名") + _ = chatCategoryListByConvCmd.Flags().MarkHidden("group") chatCategoryListByConvCmd.Flags().String("id", "", "--group 的别名") _ = chatCategoryListByConvCmd.Flags().MarkHidden("id") - cli.AnnotateRuntimeRequiredFlags(chatCategoryListByConvCmd, "group") + cli.AnnotateRuntimeRequiredFlags(chatCategoryListByConvCmd, "conversation-id") // category batch-info flags chatCategoryBatchInfoCmd.Flags().String("category-ids", "", "分组 ID 列表，逗号分隔 (必填)") @@ -7015,12 +7109,12 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 chatGroupRoleListCmd := &cobra.Command{ Use: "list", Short: "拉取会话的群身份列表", - Example: ` dws chat group-role list --group + Example: ` dws chat group-role list --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "group", "conversation-id", "id") + groupID := flagOrFallback(cmd, "conversation-id", "group", "id") if groupID == "" { - return fmt.Errorf("flag --group is required\n hint: dws chat group-role list --group ") + return fmt.Errorf("flag --group is required\n hint: dws chat group-role list --conversation-id ") } return callMCPToolOnServer("im", "list_custom_group_roles", map[string]any{ "openConversationId": groupID, @@ -7050,26 +7144,24 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "列出群聊中的自定义角色", UseWhen: []string{"需要取得角色 ID 或查看角色定义时"}, AvoidWhen: []string{"查询某个成员已分配角色时使用 chat group-role query-user"}, - Examples: []string{"dws chat group-role list --group "}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group-role list --conversation-id "}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupRoleListCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleListCmd.MarkFlagRequired("group") + chatGroupRoleListCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleListCmd.MarkFlagRequired("conversation-id") chatGroupRoleAddCmd := &cobra.Command{ Use: "add", Short: "添加群身份", - Example: ` dws chat group-role add --group --name "管理员"`, + Example: ` dws chat group-role add --conversation-id --name "管理员"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "name"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "name"); err != nil { return err } return callMCPToolOnServer("im", "add_custom_group_role", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "name": mustGetFlag(cmd, "name"), }) }, @@ -7097,28 +7189,26 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "在群聊中创建自定义角色", UseWhen: []string{"需要新增可分配给群成员的业务角色时"}, AvoidWhen: []string{"设置系统管理员角色时使用 chat group set-admin"}, - Examples: []string{"dws chat group-role add --group --name \"值班负责人\""}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group-role add --conversation-id --name \"值班负责人\""}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupRoleAddCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleAddCmd.MarkFlagRequired("group") + chatGroupRoleAddCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleAddCmd.MarkFlagRequired("conversation-id") chatGroupRoleAddCmd.Flags().String("name", "", "群身份名称 (必填)") _ = chatGroupRoleAddCmd.MarkFlagRequired("name") chatGroupRoleUpdateCmd := &cobra.Command{ Use: "update", Short: "更新群身份名称", - Example: ` dws chat group-role update --group --role-id --name "新名称"`, + Example: ` dws chat group-role update --conversation-id --role-id --name "新名称"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "role-id", "name"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "role-id", "name"); err != nil { return err } return callMCPToolOnServer("im", "update_custom_group_role", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "openRoleId": mustGetFlag(cmd, "role-id"), "name": mustGetFlag(cmd, "name"), }) @@ -7147,16 +7237,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "更新群聊自定义角色的名称", UseWhen: []string{"已知角色 ID 并需要重命名该角色时"}, AvoidWhen: []string{"需要变更成员角色分配时使用 set-user 或 remove-user"}, - Examples: []string{"dws chat group-role update --group --role-id --name \"新名称\""}, + Examples: []string{"dws chat group-role update --conversation-id --role-id --name \"新名称\""}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "role-id", Property: "openRoleId"}, }, }, }) - chatGroupRoleUpdateCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleUpdateCmd.MarkFlagRequired("group") + chatGroupRoleUpdateCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleUpdateCmd.MarkFlagRequired("conversation-id") chatGroupRoleUpdateCmd.Flags().String("role-id", "", "群身份 openRoleId，由 group-role list 返回 (必填)") _ = chatGroupRoleUpdateCmd.MarkFlagRequired("role-id") chatGroupRoleUpdateCmd.Flags().String("name", "", "群身份新名称 (必填)") @@ -7165,13 +7254,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 chatGroupRoleRemoveCmd := &cobra.Command{ Use: "remove", Short: "删除群身份", - Example: ` dws chat group-role remove --group --role-id `, + Example: ` dws chat group-role remove --conversation-id --role-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "role-id"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "role-id"); err != nil { return err } return callMCPToolOnServer("im", "remove_custom_group_role", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "openRoleId": mustGetFlag(cmd, "role-id"), }) }, @@ -7199,27 +7288,26 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "删除群聊中的自定义角色", UseWhen: []string{"明确要移除整个自定义角色定义时"}, AvoidWhen: []string{"只取消某个成员的角色时使用 chat group-role remove-user"}, - Examples: []string{"dws chat group-role remove --group --role-id "}, + Examples: []string{"dws chat group-role remove --conversation-id --role-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "role-id", Property: "openRoleId"}, }, }, }) - chatGroupRoleRemoveCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleRemoveCmd.MarkFlagRequired("group") + chatGroupRoleRemoveCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleRemoveCmd.MarkFlagRequired("conversation-id") chatGroupRoleRemoveCmd.Flags().String("role-id", "", "群身份 openRoleId，由 group-role list 返回 (必填)") _ = chatGroupRoleRemoveCmd.MarkFlagRequired("role-id") chatGroupRoleSetUserCmd := &cobra.Command{ Use: "set-user", Short: "设置用户的群身份（覆盖该用户的全部群身份）", - Example: ` dws chat group-role set-user --group --user --role-ids roleId1,roleId2 + Example: ` dws chat group-role set-user --conversation-id --user --role-ids roleId1,roleId2 # 查询人员: dws contact user search --keyword "姓名" --format json - # 查询 role-id: dws chat group-role list --group `, + # 查询 role-id: dws chat group-role list --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "role-ids"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "role-ids"); err != nil { return err } if err := validateRequiredFlagWithAliases(cmd, "user", "userId"); err != nil { @@ -7228,7 +7316,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 roleIDs := parseCSVValues(mustGetFlag(cmd, "role-ids")) user := flagOrFallback(cmd, "user", "userId") toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "openRoleIds": roleIDs, } if isOpenDingTalkID(user) { @@ -7262,17 +7350,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "为指定群成员设置自定义角色", UseWhen: []string{"需要把一个或多个已有角色分配给成员时"}, AvoidWhen: []string{"创建新角色定义时使用 chat group-role add"}, - Examples: []string{"dws chat group-role set-user --group --user --role-ids roleId1,roleId2"}, + Examples: []string{"dws chat group-role set-user --conversation-id --user --role-ids roleId1,roleId2"}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "role-ids", Property: "openRoleIds"}, {Name: "user", Property: "openDingTalkId"}, }, }, }) - chatGroupRoleSetUserCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleSetUserCmd.MarkFlagRequired("group") + chatGroupRoleSetUserCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleSetUserCmd.MarkFlagRequired("conversation-id") chatGroupRoleSetUserCmd.Flags().String("user", "", "用户 userId（必填）") chatGroupRoleSetUserCmd.Flags().String("userId", "", "--user 的别名") _ = chatGroupRoleSetUserCmd.Flags().MarkHidden("userId") @@ -7282,9 +7369,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 chatGroupRoleRemoveUserCmd := &cobra.Command{ Use: "remove-user", Short: "移除用户的指定群身份", - Example: ` dws chat group-role remove-user --group --user --role-ids roleId1,roleId2`, + Example: ` dws chat group-role remove-user --conversation-id --user --role-ids roleId1,roleId2`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "role-ids"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "role-ids"); err != nil { return err } if err := validateRequiredFlagWithAliases(cmd, "user", "userId"); err != nil { @@ -7293,7 +7380,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 roleIDs := parseCSVValues(mustGetFlag(cmd, "role-ids")) user := flagOrFallback(cmd, "user", "userId") toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "openRoleIds": roleIDs, } if isOpenDingTalkID(user) { @@ -7327,17 +7414,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "取消指定成员的一个或多个自定义角色", UseWhen: []string{"需要保留角色定义但解除成员角色时"}, AvoidWhen: []string{"删除角色定义本身时使用 chat group-role remove"}, - Examples: []string{"dws chat group-role remove-user --group --user --role-ids roleId1,roleId2"}, + Examples: []string{"dws chat group-role remove-user --conversation-id --user --role-ids roleId1,roleId2"}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "role-ids", Property: "openRoleIds"}, {Name: "user", Property: "openDingTalkId"}, }, }, }) - chatGroupRoleRemoveUserCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleRemoveUserCmd.MarkFlagRequired("group") + chatGroupRoleRemoveUserCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleRemoveUserCmd.MarkFlagRequired("conversation-id") chatGroupRoleRemoveUserCmd.Flags().String("user", "", "用户 userId（必填）") chatGroupRoleRemoveUserCmd.Flags().String("userId", "", "--user 的别名") _ = chatGroupRoleRemoveUserCmd.Flags().MarkHidden("userId") @@ -7347,9 +7433,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 chatGroupRoleQueryUserCmd := &cobra.Command{ Use: "query-user", Short: "查询群成员的群身份", - Example: ` dws chat group-role query-user --group --user `, + Example: ` dws chat group-role query-user --conversation-id --user `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } if err := validateRequiredFlagWithAliases(cmd, "user", "userId"); err != nil { @@ -7357,7 +7443,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 } user := flagOrFallback(cmd, "user", "userId") toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), } if isOpenDingTalkID(user) { toolArgs["openDingTalkId"] = user @@ -7390,16 +7476,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "查询指定群成员的自定义角色", UseWhen: []string{"需要核对某个成员在群内的业务角色时"}, AvoidWhen: []string{"列出全部角色定义时使用 chat group-role list"}, - Examples: []string{"dws chat group-role query-user --group --user "}, + Examples: []string{"dws chat group-role query-user --conversation-id --user "}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, {Name: "user", Property: "openDingTalkId"}, }, }, }) - chatGroupRoleQueryUserCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupRoleQueryUserCmd.MarkFlagRequired("group") + chatGroupRoleQueryUserCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupRoleQueryUserCmd.MarkFlagRequired("conversation-id") chatGroupRoleQueryUserCmd.Flags().String("user", "", "用户 userId（必填）") chatGroupRoleQueryUserCmd.Flags().String("userId", "", "--user 的别名") _ = chatGroupRoleQueryUserCmd.Flags().MarkHidden("userId") @@ -7420,13 +7505,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "bots", Short: "查看群内所有机器人", Long: `获取指定群聊中的所有机器人列表。`, - Example: ` dws chat group bots --group + Example: ` dws chat group bots --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } - groupID, err := resolveNativeChatTarget(mustGetFlag(cmd, "group")) + groupID, err := resolveNativeChatTarget(flagOrFallback(cmd, "conversation-id", "group", "id", "chat")) if err != nil { return err } @@ -7458,15 +7543,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "列出群内机器人", UseWhen: []string{"需要查看某群已安装哪些机器人或提取 openBotId"}, AvoidWhen: []string{"搜索企业内机器人目录时使用 chat bot find"}, - Examples: []string{"dws chat group bots --group "}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group bots --conversation-id "}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupBotsCmd.Flags().String("group", "", "群聊 openConversationId 或需唯一解析的群名 (必填)") - _ = chatGroupBotsCmd.MarkFlagRequired("group") + chatGroupBotsCmd.Flags().String("conversation-id", "", "群聊 openConversationId 或需唯一解析的群名 (必填)") + _ = chatGroupBotsCmd.MarkFlagRequired("conversation-id") chatGroupMembersRemoveBotCmd := &cobra.Command{ Use: "remove-bot", @@ -7474,7 +7557,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Long: `将指定机器人从群聊中移除。需要群管理员或群主权限。`, Example: ` dws chat group members remove-bot --id --bot-id # 查询群 ID: dws chat search --query "群名" - # 查询群内机器人: dws chat group bots --group `, + # 查询群内机器人: dws chat group bots --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlags(cmd, "id", "bot-id"); err != nil { return err @@ -7601,14 +7684,14 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "dismiss", Short: "解散群聊", Long: `解散指定群聊。该操作不可逆，需要群主权限；必须先获得用户确认，再追加 --yes 执行。`, - Example: ` dws chat group dismiss --group + Example: ` dws chat group dismiss --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } return callMCPToolOnServer("im", "dismiss_group", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), }) }, } @@ -7642,15 +7725,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 "仍需保留群供他人继续使用时不要解散", "目标群未确认或用户未明确同意不可恢复后果时不要执行", }, - Examples: []string{"dws chat group dismiss --group "}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group dismiss --conversation-id "}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupDismissCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupDismissCmd.MarkFlagRequired("group") + chatGroupDismissCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupDismissCmd.MarkFlagRequired("conversation-id") chatGroupSetHistoryCmd := &cobra.Command{ Use: "set-history", @@ -7659,11 +7740,11 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 FORBIDDEN 禁止查看历史消息 RECENT_100 可查看最近 100 条消息 ALL 可查看全部历史消息`, - Example: ` dws chat group set-history --group --option RECENT_100 - dws chat group set-history --group --option FORBIDDEN + Example: ` dws chat group set-history --conversation-id --option RECENT_100 + dws chat group set-history --conversation-id --option FORBIDDEN # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "option"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "option"); err != nil { return err } option := mustGetFlag(cmd, "option") @@ -7673,7 +7754,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 return fmt.Errorf("--option must be one of FORBIDDEN | RECENT_100 | ALL, got %q", option) } return callMCPToolOnServer("im", "update_show_history_msg_option", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "option": option, }) }, @@ -7701,15 +7782,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "设置新成员可见的群历史消息范围", UseWhen: []string{"需要调整新成员入群后的历史消息可见性时"}, AvoidWhen: []string{"普通消息查询或群设置的其他开关不要使用"}, - Examples: []string{"dws chat group set-history --group --option RECENT_100"}, - }, - Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId"}, + Examples: []string{"dws chat group set-history --conversation-id --option RECENT_100"}, }, + Parameters: []contract.ParamDecl{}, }, }) - chatGroupSetHistoryCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupSetHistoryCmd.MarkFlagRequired("group") + chatGroupSetHistoryCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupSetHistoryCmd.MarkFlagRequired("conversation-id") chatGroupSetHistoryCmd.Flags().String("option", "", "可见范围: FORBIDDEN | RECENT_100 | ALL (必填)") _ = chatGroupSetHistoryCmd.MarkFlagRequired("option") @@ -7859,14 +7938,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 如何获取 openConversationId（如果上层已有则直接使用，不必再查）： - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id `, - Example: ` dws chat message set-pin-msg --open-conversation-id --msg-id `, + Example: ` dws chat message set-pin-msg --open-conversation-id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "open-conversation-id", "msg-id"); err != nil { + if err := validateRequiredFlags(cmd, "open-conversation-id"); err != nil { + return err + } + if _, err := chatMessageID(cmd); err != nil { return err } return callMCPToolOnServer("im", "set_pin_message", map[string]any{ "openConversationId": mustGetFlag(cmd, "open-conversation-id"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), }) }, } @@ -7893,17 +7975,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "把指定消息设为会话置顶消息", UseWhen: []string{"需要在会话中置顶一条已知消息时"}, AvoidWhen: []string{"取消置顶使用 chat message unset-pin-msg"}, - Examples: []string{"dws chat message set-pin-msg --open-conversation-id --msg-id "}, + Examples: []string{"dws chat message set-pin-msg --open-conversation-id --message-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "msg-id", Property: "openMessageId"}, + {Name: "message-id", Property: "openMessageId"}, }, }, }) chatMessageSetPinCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填，支持群聊/单聊)") _ = chatMessageSetPinCmd.MarkFlagRequired("open-conversation-id") - chatMessageSetPinCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageSetPinCmd.MarkFlagRequired("msg-id") + chatMessageSetPinCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageSetPinCmd.MarkFlagRequired("message-id") chatMessageUnsetPinCmd := &cobra.Command{ Use: "unset-pin-msg", @@ -7913,14 +7995,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 如何获取 openConversationId（如果上层已有则直接使用，不必再查）： - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id `, - Example: ` dws chat message unset-pin-msg --open-conversation-id --msg-id `, + Example: ` dws chat message unset-pin-msg --open-conversation-id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "open-conversation-id", "msg-id"); err != nil { + if err := validateRequiredFlags(cmd, "open-conversation-id"); err != nil { + return err + } + if _, err := chatMessageID(cmd); err != nil { return err } return callMCPToolOnServer("im", "unset_pin_message", map[string]any{ "openConversationId": mustGetFlag(cmd, "open-conversation-id"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), }) }, } @@ -7947,17 +8032,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "取消指定消息的会话置顶", UseWhen: []string{"需要移除一条已知置顶消息时"}, AvoidWhen: []string{"新增置顶使用 chat message set-pin-msg"}, - Examples: []string{"dws chat message unset-pin-msg --open-conversation-id --msg-id "}, + Examples: []string{"dws chat message unset-pin-msg --open-conversation-id --message-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "msg-id", Property: "openMessageId"}, + {Name: "message-id", Property: "openMessageId"}, }, }, }) chatMessageUnsetPinCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填，支持群聊/单聊)") _ = chatMessageUnsetPinCmd.MarkFlagRequired("open-conversation-id") - chatMessageUnsetPinCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageUnsetPinCmd.MarkFlagRequired("msg-id") + chatMessageUnsetPinCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageUnsetPinCmd.MarkFlagRequired("message-id") chatMessageListPinCmd := &cobra.Command{ Use: "list-pin-msg", @@ -8362,11 +8447,11 @@ status 可选值: AuditIgnore — 忽略（服务端拒绝，不可用） AuditRefuse — 拒绝（服务端拒绝，不可用） AuditBlock — 拒绝且不再接受该用户的申请（服务端拒绝，不可用）`, - Example: ` dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove - dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" + Example: ` dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove + dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" # 查询入群验证记录: dws chat group list-join-validations`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "record-id", "applicant", "inviter", "status"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "record-id", "applicant", "inviter", "status"); err != nil { return err } recordID, err := strconv.ParseInt(mustGetFlag(cmd, "record-id"), 10, 64) @@ -8378,7 +8463,7 @@ status 可选值: return fmt.Errorf("unsupported audit status %q, must be one of: AuditApprove, AuditDelete", status) } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "applyRecordId": recordID, "applicantUid": mustGetFlag(cmd, "applicant"), "inviterUid": mustGetFlag(cmd, "inviter"), @@ -8390,8 +8475,8 @@ status 可选值: return callMCPToolOnServer("im", "audit_join_group", toolArgs) }, } - chatGroupAuditJoinValidationCmd.Flags().String("group", "", "群 openConversationId (必填)") - _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("group") + chatGroupAuditJoinValidationCmd.Flags().String("conversation-id", "", "群 openConversationId (必填)") + _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("conversation-id") chatGroupAuditJoinValidationCmd.Flags().String("record-id", "", "申请记录 ID (必填)") _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("record-id") chatGroupAuditJoinValidationCmd.Flags().String("status", "", "审批动作，真机仅 AuditApprove/AuditDelete 可用；AuditIgnore/AuditRefuse/AuditBlock 服务端拒绝 (必填)") @@ -8424,12 +8509,11 @@ status 可选值: AgentSummary: "审批入群验证记录", UseWhen: []string{"需要对已知入群申请记录执行通过或删除审批动作时"}, AvoidWhen: []string{"还没有 record-id 时先用 chat group list-join-validations 查询"}, - Examples: []string{"dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove"}, + Examples: []string{"dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove"}, }, Parameters: []contract.ParamDecl{ {Name: "applicant", Property: "applicantUid", Required: boolPtr(true)}, {Name: "description", Property: "auditDescription", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "inviter", Property: "inviterUid", Required: boolPtr(true)}, {Name: "record-id", Property: "applyRecordId", Required: boolPtr(true), InterfaceType: "integer"}, {Name: "status", Property: "status", Required: boolPtr(true), Enum: []string{"AuditApprove", "AuditDelete"}}, @@ -8740,7 +8824,7 @@ status 可选值: - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id 如何获取 openMessageId： - - dws chat message list --group --time "2025-03-01 00:00:00"`, + - dws chat message list --conversation-id --time "2025-03-01 00:00:00"`, Example: ` dws chat mark-read --conversation-id --message-id dws chat mark-read --id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { @@ -8748,12 +8832,13 @@ status 可选值: if convID == "" { return fmt.Errorf("flag --conversation-id is required\n hint: dws chat mark-read --conversation-id --message-id ") } - if err := validateRequiredFlags(cmd, "message-id"); err != nil { + messageID, err := chatMessageID(cmd) + if err != nil { return err } return callMCPToolOnServer("im", "mark_message_read", map[string]any{ "openConversationId": convID, - "openMessageId": mustGetFlag(cmd, "message-id"), + "openMessageId": messageID, }) }, } @@ -8808,21 +8893,24 @@ status 可选值: 如何获取 openConversationId（如果上层已有则直接使用，不必再查）： - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id `, - Example: ` dws chat message set-top-msg --open-conversation-id --msg-id `, + Example: ` dws chat message set-top-msg --open-conversation-id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "open-conversation-id", "msg-id"); err != nil { + if err := validateRequiredFlags(cmd, "open-conversation-id"); err != nil { + return err + } + if _, err := chatMessageID(cmd); err != nil { return err } return callMCPToolOnServer("im", "set_top_message", map[string]any{ "openConversationId": mustGetFlag(cmd, "open-conversation-id"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), }) }, } chatMessageSetTopMsgCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填，支持群聊/单聊)") _ = chatMessageSetTopMsgCmd.MarkFlagRequired("open-conversation-id") - chatMessageSetTopMsgCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageSetTopMsgCmd.MarkFlagRequired("msg-id") + chatMessageSetTopMsgCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageSetTopMsgCmd.MarkFlagRequired("message-id") DeclareLeafMetadata(chatMessageSetTopMsgCmd, LeafSpec{ Safety: contract.SafetySpec{ Effect: "write", Risk: "medium", @@ -8846,10 +8934,10 @@ status 可选值: AgentSummary: "将指定会话消息设置为置顶", UseWhen: []string{"需要把群聊或单聊中的某条消息置顶展示时"}, AvoidWhen: []string{"取消消息置顶时使用 chat message unset-top-msg"}, - Examples: []string{"dws chat message set-top-msg --open-conversation-id --msg-id "}, + Examples: []string{"dws chat message set-top-msg --open-conversation-id --message-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "msg-id", Property: "openMessageId", Required: boolPtr(true)}, + {Name: "message-id", Property: "openMessageId", Required: boolPtr(true)}, {Name: "open-conversation-id", Property: "openConversationId", Required: boolPtr(true)}, }, }, @@ -8865,21 +8953,24 @@ status 可选值: 如何获取 openConversationId（如果上层已有则直接使用，不必再查）： - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id `, - Example: ` dws chat message unset-top-msg --open-conversation-id --msg-id `, + Example: ` dws chat message unset-top-msg --open-conversation-id --message-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "open-conversation-id", "msg-id"); err != nil { + if err := validateRequiredFlags(cmd, "open-conversation-id"); err != nil { + return err + } + if _, err := chatMessageID(cmd); err != nil { return err } return callMCPToolOnServer("im", "unset_top_message", map[string]any{ "openConversationId": mustGetFlag(cmd, "open-conversation-id"), - "openMessageId": mustGetFlag(cmd, "msg-id"), + "openMessageId": flagOrFallback(cmd, "message-id", "msg-id"), }) }, } chatMessageUnsetTopMsgCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填，支持群聊/单聊)") _ = chatMessageUnsetTopMsgCmd.MarkFlagRequired("open-conversation-id") - chatMessageUnsetTopMsgCmd.Flags().String("msg-id", "", "消息 openMessageId (必填)") - _ = chatMessageUnsetTopMsgCmd.MarkFlagRequired("msg-id") + chatMessageUnsetTopMsgCmd.Flags().String("message-id", "", "消息 openMessageId (必填)") + _ = chatMessageUnsetTopMsgCmd.MarkFlagRequired("message-id") DeclareLeafMetadata(chatMessageUnsetTopMsgCmd, LeafSpec{ Safety: contract.SafetySpec{ Effect: "write", Risk: "medium", @@ -8903,10 +8994,10 @@ status 可选值: AgentSummary: "取消指定会话消息的置顶", UseWhen: []string{"需要取消某条消息的置顶状态时"}, AvoidWhen: []string{"设置消息置顶时使用 chat message set-top-msg"}, - Examples: []string{"dws chat message unset-top-msg --open-conversation-id --msg-id "}, + Examples: []string{"dws chat message unset-top-msg --open-conversation-id --message-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "msg-id", Property: "openMessageId", Required: boolPtr(true)}, + {Name: "message-id", Property: "openMessageId", Required: boolPtr(true)}, {Name: "open-conversation-id", Property: "openConversationId", Required: boolPtr(true)}, }, }, @@ -8920,17 +9011,17 @@ status 可选值: Use: "update-nick", Short: "设置或清除用户在群内的群昵称", Long: `设置当前用户在指定群聊内的个人群昵称。不传 --nick 时清除当前群昵称。`, - Example: ` dws chat group update-nick --group --nick "我的群昵称" - dws chat group update-nick --group + Example: ` dws chat group update-nick --conversation-id --nick "我的群昵称" + dws chat group update-nick --conversation-id # 不传 --nick 表示清除群昵称 # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } nick, _ := cmd.Flags().GetString("nick") return callMCPToolOnServer("im", "update_group_nick", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "nick": nick, }) }, @@ -8959,18 +9050,18 @@ status 可选值: UseWhen: []string{"用户要求修改自己的群昵称，或明确要求清除群昵称"}, AvoidWhen: []string{"修改群名称应使用 chat group rename；修改其他成员信息不应使用本命令"}, Examples: []string{ - "dws chat group update-nick --group --nick \"项目昵称\"", - "dws chat group update-nick --group ", + "dws chat group update-nick --conversation-id --nick \"项目昵称\"", + "dws chat group update-nick --conversation-id ", }, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "nick", Property: "nick", Required: boolPtr(false)}, }, }, }) - chatGroupUpdateNickCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupUpdateNickCmd.MarkFlagRequired("group") + chatGroupUpdateNickCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupUpdateNickCmd.MarkFlagRequired("conversation-id") chatGroupUpdateNickCmd.Flags().String("nick", "", "个人群昵称，不传则清除群昵称") // ── group update-alias: 设置群备注 ────────────────────────── @@ -8979,20 +9070,20 @@ status 可选值: Use: "update-alias", Short: "设置群备注", Long: `设置当前用户对指定群聊的备注名称（仅自己可见）。`, - Example: ` dws chat group update-alias --group --alias-title "项目A群" + Example: ` dws chat group update-alias --conversation-id --alias-title "项目A群" # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "alias-title"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "alias-title"); err != nil { return err } return callMCPToolOnServer("im", "update_user_group_alias", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "aliasTitle": mustGetFlag(cmd, "alias-title"), }) }, } - chatGroupUpdateAliasCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupUpdateAliasCmd.MarkFlagRequired("group") + chatGroupUpdateAliasCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupUpdateAliasCmd.MarkFlagRequired("conversation-id") chatGroupUpdateAliasCmd.Flags().String("alias-title", "", "群备注标题 (必填)") _ = chatGroupUpdateAliasCmd.MarkFlagRequired("alias-title") DeclareLeafMetadata(chatGroupUpdateAliasCmd, LeafSpec{ @@ -9018,11 +9109,10 @@ status 可选值: AgentSummary: "设置当前用户可见的群备注名称", UseWhen: []string{"用户要求给指定群设置仅自己可见的备注名时"}, AvoidWhen: []string{"修改群公开名称应使用 chat group rename"}, - Examples: []string{"dws chat group update-alias --group --alias-title \"项目A群\""}, + Examples: []string{"dws chat group update-alias --conversation-id --alias-title \"项目A群\""}, }, Parameters: []contract.ParamDecl{ {Name: "alias-title", Property: "aliasTitle", Required: boolPtr(true)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, }, }, }) @@ -9272,16 +9362,16 @@ status 可选值: Long: `在指定群聊中发布群公告，正文为 Markdown 格式。 支持标题、加粗、斜体、删除线、行内代码、链接、代码块、有序/无序/任务列表、表格、引用、分割线、图片、段落、换行。 定时发布：传 --run-at 指定执行时间点，ISO-8601 格式（建议带时区偏移，不带时按北京时区处理）。`, - Example: ` dws chat group notice create --group --content "今晚 22 点系统维护，请提前保存工作内容" - dws chat group notice create --group --content "# 重要通知\n请大家查收" --sticky --send-ding - dws chat group notice create --group --content "明早九点例会" --run-at "2026-07-03T09:00:00+08:00" + Example: ` dws chat group notice create --conversation-id --content "今晚 22 点系统维护，请提前保存工作内容" + dws chat group notice create --conversation-id --content "# 重要通知\n请大家查收" --sticky --send-ding + dws chat group notice create --conversation-id --content "明早九点例会" --run-at "2026-07-03T09:00:00+08:00" # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "content"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "content"); err != nil { return err } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "content": mustGetFlag(cmd, "content"), } if v, _ := cmd.Flags().GetBool("sticky"); v { @@ -9297,8 +9387,8 @@ status 可选值: return callMCPToolOnServer("im", "create_group_notice", toolArgs) }, } - chatGroupNoticeCreateCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupNoticeCreateCmd.MarkFlagRequired("group") + chatGroupNoticeCreateCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupNoticeCreateCmd.MarkFlagRequired("conversation-id") chatGroupNoticeCreateCmd.Flags().String("content", "", "公告正文，Markdown 格式 (必填)") _ = chatGroupNoticeCreateCmd.MarkFlagRequired("content") chatGroupNoticeCreateCmd.Flags().Bool("sticky", false, "是否吊顶置顶（默认 false）") @@ -9327,11 +9417,10 @@ status 可选值: AgentSummary: "在指定群聊中发布群公告", UseWhen: []string{"需要在群聊里发布 Markdown 群公告，可选吊顶、DING 或定时发布时"}, AvoidWhen: []string{"修改已有群公告时使用 chat group notice edit"}, - Examples: []string{"dws chat group notice create --group --content \"今晚维护\""}, + Examples: []string{"dws chat group notice create --conversation-id --content \"今晚维护\""}, }, Parameters: []contract.ParamDecl{ {Name: "content", Property: "content", Required: boolPtr(true)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "run-at", Property: "runAtText", Required: boolPtr(false)}, {Name: "send-ding", Property: "sendDing", Required: boolPtr(false)}, {Name: "sticky", Property: "sticky", Required: boolPtr(false)}, @@ -9343,15 +9432,15 @@ status 可选值: Use: "edit", Short: "修改群公告", Long: `修改指定群聊中的群公告，正文为 Markdown 格式，会整体替换原公告内容。`, - Example: ` dws chat group notice edit --group --notice-id --content "更新后的公告内容" - dws chat group notice edit --group --notice-id --content "更新后的公告内容" --sticky --send-ding - # 查询公告 ID: dws chat group notice list --group `, + Example: ` dws chat group notice edit --conversation-id --notice-id --content "更新后的公告内容" + dws chat group notice edit --conversation-id --notice-id --content "更新后的公告内容" --sticky --send-ding + # 查询公告 ID: dws chat group notice list --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "notice-id", "content"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "notice-id", "content"); err != nil { return err } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "dataId": mustGetFlag(cmd, "notice-id"), "content": mustGetFlag(cmd, "content"), } @@ -9364,8 +9453,8 @@ status 可选值: return callMCPToolOnServer("im", "edit_group_notice", toolArgs) }, } - chatGroupNoticeEditCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupNoticeEditCmd.MarkFlagRequired("group") + chatGroupNoticeEditCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupNoticeEditCmd.MarkFlagRequired("conversation-id") chatGroupNoticeEditCmd.Flags().String("notice-id", "", "群公告 dataId (必填)") _ = chatGroupNoticeEditCmd.MarkFlagRequired("notice-id") chatGroupNoticeEditCmd.Flags().String("content", "", "公告新正文，Markdown 格式 (必填)") @@ -9395,11 +9484,10 @@ status 可选值: AgentSummary: "修改指定群聊中的群公告", UseWhen: []string{"已有公告 dataId，需要替换群公告正文或调整吊顶/DING 状态时"}, AvoidWhen: []string{"发布新公告时使用 chat group notice create"}, - Examples: []string{"dws chat group notice edit --group --notice-id --content \"更新后的公告\""}, + Examples: []string{"dws chat group notice edit --conversation-id --notice-id --content \"更新后的公告\""}, }, Parameters: []contract.ParamDecl{ {Name: "content", Property: "content", Required: boolPtr(true)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "notice-id", Property: "dataId", Required: boolPtr(true)}, {Name: "send-ding", Property: "sendDing", Required: boolPtr(false)}, {Name: "sticky", Property: "sticky", Required: boolPtr(false)}, @@ -9411,20 +9499,20 @@ status 可选值: Use: "get", Short: "查看群公告详情", Long: `查看指定群公告的详情，包含正文摘要、吊顶状态、发布者、已读人数、点赞/评论数等信息。`, - Example: ` dws chat group notice get --group --notice-id - # 查询公告 ID: dws chat group notice list --group `, + Example: ` dws chat group notice get --conversation-id --notice-id + # 查询公告 ID: dws chat group notice list --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "notice-id"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id", "notice-id"); err != nil { return err } return callMCPToolOnServer("im", "get_group_notice", map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), "dataId": mustGetFlag(cmd, "notice-id"), }) }, } - chatGroupNoticeGetCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupNoticeGetCmd.MarkFlagRequired("group") + chatGroupNoticeGetCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupNoticeGetCmd.MarkFlagRequired("conversation-id") chatGroupNoticeGetCmd.Flags().String("notice-id", "", "群公告 dataId (必填)") _ = chatGroupNoticeGetCmd.MarkFlagRequired("notice-id") DeclareLeafMetadata(chatGroupNoticeGetCmd, LeafSpec{ @@ -9450,10 +9538,9 @@ status 可选值: AgentSummary: "查看指定群公告详情", UseWhen: []string{"已有群公告 dataId，需要查看公告详情、状态或互动统计时"}, AvoidWhen: []string{"不知道公告 ID 时先使用 chat group notice list"}, - Examples: []string{"dws chat group notice get --group --notice-id "}, + Examples: []string{"dws chat group notice get --conversation-id --notice-id "}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "notice-id", Property: "dataId", Required: boolPtr(true)}, }, }, @@ -9464,16 +9551,16 @@ status 可选值: Short: "查看群公告列表", Long: `分页查看指定群聊的群公告列表。默认查询已发布公告，传 --scheduled 查询定时公告列表。 支持游标分页，hasMore=true 时用返回的 nextPageCursor 作为下次 --cursor。`, - Example: ` dws chat group notice list --group - dws chat group notice list --group --limit 20 --cursor - dws chat group notice list --group --scheduled + Example: ` dws chat group notice list --conversation-id + dws chat group notice list --conversation-id --limit 20 --cursor + dws chat group notice list --conversation-id --scheduled # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), } if v, _ := cmd.Flags().GetInt("limit"); v > 0 { toolArgs["limit"] = v @@ -9487,8 +9574,8 @@ status 可选值: return callMCPToolOnServer("im", "list_group_notices", toolArgs) }, } - chatGroupNoticeListCmd.Flags().String("group", "", "群聊 openConversationId (必填)") - _ = chatGroupNoticeListCmd.MarkFlagRequired("group") + chatGroupNoticeListCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + _ = chatGroupNoticeListCmd.MarkFlagRequired("conversation-id") chatGroupNoticeListCmd.Flags().Int("limit", 10, "每页返回数量（默认 10，最大 100）") chatGroupNoticeListCmd.Flags().String("cursor", "", "分页游标（首次不传，翻页传返回的 nextPageCursor）") chatGroupNoticeListCmd.Flags().Bool("scheduled", false, "是否查询定时公告列表（默认 false，查询已发布公告）") @@ -9515,11 +9602,10 @@ status 可选值: AgentSummary: "分页查看指定群聊的群公告列表", UseWhen: []string{"需要列出群公告、查找公告 dataId 或翻页查看定时公告时"}, AvoidWhen: []string{"已知 dataId 并只看详情时使用 chat group notice get"}, - Examples: []string{"dws chat group notice list --group --limit 20"}, + Examples: []string{"dws chat group notice list --conversation-id --limit 20"}, }, Parameters: []contract.ParamDecl{ {Name: "cursor", Property: "cursor", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "limit", Property: "limit", Required: boolPtr(false)}, {Name: "scheduled", Property: "scheduled", Required: boolPtr(false)}, }, @@ -9593,15 +9679,15 @@ status 可选值: 本命令升级已有普通群；新建外部群请使用 chat group create --type EXTERNAL。 该操作不可逆，仅群主可执行。正式执行必须通过 --yes 显式确认，可先使用 --dry-run 预览。`, - Example: ` dws chat group upgrade-to-external --group --dry-run - dws chat group upgrade-to-external --group --extension '{"source":"dws"}' --dry-run + Example: ` dws chat group upgrade-to-external --conversation-id --dry-run + dws chat group upgrade-to-external --conversation-id --extension '{"source":"dws"}' --dry-run # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group"); err != nil { + if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { return err } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), } if rawExtension := mustGetFlag(cmd, "extension"); rawExtension != "" { var rawValues map[string]any @@ -9647,16 +9733,16 @@ status 可选值: AgentSummary: "不可逆地把已有普通群升级为外部群", UseWhen: []string{"群主明确要求保留现有会话并升级为可跨组织协作的外部群，且已确认不可逆影响"}, AvoidWhen: []string{"新建外部群应使用 chat group create --type EXTERNAL；未确认群主身份和不可逆影响时不要执行"}, - Examples: []string{"dws chat group upgrade-to-external --group "}, + Examples: []string{"dws chat group upgrade-to-external --conversation-id "}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "extension", Property: "extension", Required: boolPtr(false), InterfaceType: "object"}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, }, }, }) - chatGroupUpgradeToExternalCmd.Flags().String("group", "", "待升级普通群的 openConversationId (必填)") - _ = chatGroupUpgradeToExternalCmd.MarkFlagRequired("group") + chatGroupUpgradeToExternalCmd.Flags().String("conversation-id", "", "待升级普通群的 openConversationId (必填)") + _ = chatGroupUpgradeToExternalCmd.MarkFlagRequired("conversation-id") chatGroupUpgradeToExternalCmd.Flags().String("extension", "", `预留扩展字段 JSON 对象 (可选)，如 '{"source":"dws"}'`) chatCategoryCreateSmartCmd := &cobra.Command{ @@ -9975,7 +10061,8 @@ pl_PL, sv_SE, fi_FI, cs_CZ, ar_SA, tl_PH, he_IL, nl_NL, lo_LA, it_IT`, // the supported nested commands. The chat root's "im" alias makes these // compatibility hints available through both chat and im. root.AddCommand(chatCompatibilityHintSubCmd("send", "use: dws chat message send")) - root.AddCommand(chatCompatibilityHintSubCmd("history", "use: dws chat message list --group ")) + root.AddCommand(chatCompatibilityHintSubCmd("history", "use: dws chat message list --conversation-id ")) + installChatIMIDFlagAliases(root) return root } diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 21f67753..1687be54 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -92,7 +92,7 @@ func TestCrossPlatformCoverageChatStableCompatibilityHintsRemainAvailable(t *tes hint string }{ {path: "send", args: []string{"send", "--group", "cid-stable", "--text", "hello"}, hint: "dws chat message send"}, - {path: "history", args: []string{"history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --group "}, + {path: "history", args: []string{"history", "--group", "cid-stable", "--limit", "20"}, hint: "dws chat message list --conversation-id "}, } { command, remaining, err := root.Find([]string{tc.path}) if err != nil { diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index fcf1548c..eb5b2c26 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -51,7 +51,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing contains: []string{ "send -> query-send-status -> edit", "query-send-status --open-task-id <上一步返回的openTaskId>", - "edit --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>", + "edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>", }, notContain: "chat message list", }, @@ -61,7 +61,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing contains: []string{ "send -> query-send-status -> recall", "query-send-status --open-task-id <上一步返回的openTaskId>", - "recall --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>", + "recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>", }, notContain: "chat message list", }, diff --git a/internal/helpers/chat_ports_coverage_test.go b/internal/helpers/chat_ports_coverage_test.go index 4466a966..a7d8a6d2 100644 --- a/internal/helpers/chat_ports_coverage_test.go +++ b/internal/helpers/chat_ports_coverage_test.go @@ -127,7 +127,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) { { name: "missing conversation-id and aliases", args: dropFlag("--conversation-id"), - wantErr: "at least one of the flags in the group [conversation-id group id chat] is required", + wantErr: "missing required flag: --conversation-id (or --group / --id / --chat / --open-conversation-id)", }, { name: "missing old-emotion-id", @@ -135,7 +135,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) { wantErr: `required flag(s) "old-emotion-id" not set`, }, { - name: "missing msg-id and background-id", + name: "missing message-id and background-id", args: []string{ "message", "update-text-emotion", "--conversation-id", "conv-1", @@ -144,7 +144,7 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) { "--emotion-name", "like", "--text", "nice", }, - wantErr: `required flag(s) "background-id", "msg-id" not set`, + wantErr: "missing required flag: --message-id (or --msg-id / --open-message-id)", }, } for _, test := range tests { @@ -196,12 +196,12 @@ func TestCrossPlatformCoverageChatGroupGetMuteConfigRecordsRawArgs(t *testing.T) } } -func TestCrossPlatformCoverageChatGroupGetMuteConfigRequiresGroup(t *testing.T) { +func TestCrossPlatformCoverageChatGroupGetMuteConfigRequiresConversationID(t *testing.T) { caller := &guardedMutationCaller{} err := executeGuardedMutationCommand(t, caller, newChatCommand, "group", "get-mute-config") - if err == nil || !strings.Contains(err.Error(), "--group") { - t.Fatalf("err = %v, want message containing --group", err) + if err == nil || !strings.Contains(err.Error(), "--conversation-id") { + t.Fatalf("err = %v, want message containing --conversation-id", err) } if len(caller.calls) != 0 { t.Fatalf("tool calls = %#v, want none", caller.calls) diff --git a/internal/helpers/wukong_weekly_sync_chat_todo_test.go b/internal/helpers/wukong_weekly_sync_chat_todo_test.go index a20a664f..3820586d 100644 --- a/internal/helpers/wukong_weekly_sync_chat_todo_test.go +++ b/internal/helpers/wukong_weekly_sync_chat_todo_test.go @@ -116,7 +116,7 @@ func requireWukongWeeklySyncConfirmation(t *testing.T, err error) { func TestCrossPlatformCoverageWukongWeeklyChatCategoryQueries(t *testing.T) { caller := &wukongWeeklySyncCaller{} _, _, err := executeWukongWeeklySyncCommand(t, "chat", caller, newChatCommand, "category", "list-by-conv") - if err == nil || !strings.Contains(err.Error(), "flag --group is required") { + if err == nil || !strings.Contains(err.Error(), "missing required flag: --conversation-id") { t.Fatalf("missing group error = %v", err) } requireWukongWeeklySyncNoCalls(t, caller) @@ -378,15 +378,15 @@ func TestCrossPlatformCoverageWukongWeeklyChatUpdateNickClearSemantics(t *testin if findErr != nil { t.Fatal(findErr) } - if err := updateNick.RunE(updateNick, nil); err == nil || !strings.Contains(err.Error(), "--group") { - t.Fatalf("direct missing group error = %v", err) + if err := updateNick.RunE(updateNick, nil); err == nil || !strings.Contains(err.Error(), "--conversation-id") { + t.Fatalf("direct missing conversation-id error = %v", err) } caller := &wukongWeeklySyncCaller{} _, _, err := executeWukongWeeklySyncCommand(t, "chat", caller, newChatCommand, "group", "update-nick") - if err == nil || !strings.Contains(err.Error(), "group") { - t.Fatalf("missing group error = %v", err) + if err == nil || !strings.Contains(err.Error(), "conversation-id") { + t.Fatalf("missing conversation-id error = %v", err) } requireWukongWeeklySyncNoCalls(t, caller) @@ -428,8 +428,8 @@ func TestCrossPlatformCoverageWukongWeeklyChatUpgradeValidationAndSafety(t *test upgrade.Flags().Bool("yes", false, "") } _ = upgrade.Flags().Set("yes", "true") - if err := upgrade.RunE(upgrade, nil); err == nil || !strings.Contains(err.Error(), "--group") { - t.Fatalf("direct missing group error = %v", err) + if err := upgrade.RunE(upgrade, nil); err == nil || !strings.Contains(err.Error(), "--conversation-id") { + t.Fatalf("direct missing conversation-id error = %v", err) } tests := []struct { From 132dea9aaac9b6a9ee8f219d67aa3a811b5b048a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Tue, 11 Aug 2026 22:51:16 +0800 Subject: [PATCH 002/250] fix(chat): hide remaining im id aliases --- internal/cli/param_aliases_generated.go | 2 +- internal/cli/schema_catalog_test.go | 40 ++++++++++++++++ internal/helpers/chat.go | 56 +++++++++++++++------- internal/helpers/chat_message_help_test.go | 46 ++++++++++++++++++ 4 files changed, 126 insertions(+), 18 deletions(-) diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index f3a876dc..54cf3a80 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -979,7 +979,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group create", diff --git a/internal/cli/schema_catalog_test.go b/internal/cli/schema_catalog_test.go index 9c4bb649..7918dc53 100644 --- a/internal/cli/schema_catalog_test.go +++ b/internal/cli/schema_catalog_test.go @@ -1418,4 +1418,44 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --%s", hidden) } } + + for _, path := range []string{ + "chat message add-emoji", + "chat message remove-emoji", + "chat message add-text-emotion", + "chat message remove-text-emotion", + } { + leaf, err := queryDeliverySchemaPayload([]string{path}) + if err != nil { + t.Fatal(err) + } + params := schemaMap(leaf["parameters"]) + if _, ok := params["conversation-id"]; !ok { + t.Fatalf("%s missing public canonical --conversation-id", path) + } + for _, hidden := range []string{"group", "id", "chat"} { + if _, ok := params[hidden]; ok { + t.Fatalf("%s unexpectedly publishes hidden alias --%s", path, hidden) + } + } + } + + groupBots, err := queryDeliverySchemaPayload([]string{"chat group bots"}) + if err != nil { + t.Fatal(err) + } + groupBotsParams := schemaMap(groupBots["parameters"]) + if _, ok := groupBotsParams["conversation-id"]; !ok { + t.Fatal("chat group bots missing public canonical --conversation-id") + } + groupName := groupBotsParams["group-name"] + if groupName == nil { + t.Fatal("chat group bots missing public canonical --group-name") + } + if groupName["property"] != "groupName" { + t.Fatalf("chat group bots --group-name property = %#v, want groupName", groupName["property"]) + } + if _, ok := groupBotsParams["group"]; ok { + t.Fatal("chat group bots unexpectedly publishes hidden --group alias") + } } diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 4b41dd41..9c7ffd3b 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -264,11 +264,17 @@ func installChatFlagAliases(cmd *cobra.Command, primary string, aliases []string if flag == nil { return } + effectiveAliases := make([]string, 0, len(aliases)) for _, alias := range aliases { + if primary == "conversation-id" && alias == "group" && flags.Lookup("group-name") != nil { + continue + } + effectiveAliases = append(effectiveAliases, alias) if flags.Lookup(alias) != nil { if aliasFlag := flags.Lookup(alias); aliasFlag != nil && aliasFlag.Annotations != nil { delete(aliasFlag.Annotations, cobra.BashCompOneRequiredFlag) } + _ = flags.MarkHidden(alias) continue } flags.String(alias, "", "--"+primary+" 的兼容别名") @@ -281,7 +287,7 @@ func installChatFlagAliases(cmd *cobra.Command, primary string, aliases []string } previous := cmd.PreRunE cmd.PreRunE = func(cmd *cobra.Command, args []string) error { - value, err := chatFlagOrAlias(cmd, primary, aliases...) + value, err := chatFlagOrAlias(cmd, primary, effectiveAliases...) if err != nil { return err } @@ -5478,9 +5484,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message add-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ - {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, {Name: "message-id", Property: "openMsgId"}, }, @@ -5541,9 +5545,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message remove-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ - {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, {Name: "message-id", Property: "openMsgId"}, }, @@ -5606,9 +5608,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message add-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ - {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, }, }, @@ -5673,9 +5673,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message remove-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ - {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, - {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, }, }, @@ -7506,15 +7504,30 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Short: "查看群内所有机器人", Long: `获取指定群聊中的所有机器人列表。`, Example: ` dws chat group bots --conversation-id + dws chat group bots --group-name "项目群" # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { - return err - } - groupID, err := resolveNativeChatTarget(flagOrFallback(cmd, "conversation-id", "group", "id", "chat")) + conversationID, err := chatFlagOrAlias(cmd, "conversation-id", "id", "chat", "open-conversation-id") if err != nil { return err } + groupName, err := chatFlagOrAlias(cmd, "group-name", "group") + if err != nil { + return err + } + if conversationID == "" && groupName == "" { + return validateRequiredFlagWithAliases(cmd, "conversation-id", "group-name", "group", "id", "chat", "open-conversation-id") + } + if conversationID != "" && groupName != "" { + return fmt.Errorf("--conversation-id and --group-name are mutually exclusive") + } + groupID := conversationID + if groupName != "" { + groupID, err = resolveNativeChatTarget(groupName) + if err != nil { + return err + } + } return callMCPToolOnServer("bot", "list_group_bots", map[string]any{ "openConversationId": groupID, }) @@ -7543,13 +7556,22 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "列出群内机器人", UseWhen: []string{"需要查看某群已安装哪些机器人或提取 openBotId"}, AvoidWhen: []string{"搜索企业内机器人目录时使用 chat bot find"}, - Examples: []string{"dws chat group bots --conversation-id "}, + Examples: []string{"dws chat group bots --conversation-id ", "dws chat group bots --group-name \"项目群\""}, + }, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "群聊 openConversationId"}, + {Name: "group-name", Property: "groupName", Required: boolPtr(false), Description: "需唯一解析的群名称"}, }, - Parameters: []contract.ParamDecl{}, }, }) - chatGroupBotsCmd.Flags().String("conversation-id", "", "群聊 openConversationId 或需唯一解析的群名 (必填)") - _ = chatGroupBotsCmd.MarkFlagRequired("conversation-id") + chatGroupBotsCmd.Flags().String("conversation-id", "", "群聊 openConversationId") + chatGroupBotsCmd.Flags().String("group-name", "", "需唯一解析的群名称") + chatGroupBotsCmd.Flags().String("group", "", "--group-name 的兼容别名") + _ = chatGroupBotsCmd.Flags().MarkHidden("group") + cli.AnnotateRuntimeConstraints(chatGroupBotsCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"conversation-id", "group-name"}}, + RequireOneOf: [][]string{{"conversation-id", "group-name"}}, + }) chatGroupMembersRemoveBotCmd := &cobra.Command{ Use: "remove-bot", diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index eb5b2c26..673b17cf 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -90,3 +90,49 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing }) } } + +func TestCrossPlatformCoverageChatReactionHelpHidesConversationAliases(t *testing.T) { + for _, command := range []string{"add-emoji", "remove-emoji", "add-text-emotion", "remove-text-emotion"} { + t.Run(command, func(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) + cmd.SetArgs([]string{"message", command, "--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("chat message %s --help: %v\n%s", command, err, output.String()) + } + + help := output.String() + if !strings.Contains(help, "--conversation-id") { + t.Fatalf("chat message %s help missing --conversation-id:\n%s", command, help) + } + for _, hidden := range []string{"--group", "--id", "--chat"} { + if strings.Contains(help, hidden+" string") { + t.Fatalf("chat message %s help exposes hidden alias %s:\n%s", command, hidden, help) + } + } + }) + } +} + +func TestCrossPlatformCoverageChatGroupBotsHelpSplitsGroupName(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) + cmd.SetArgs([]string{"group", "bots", "--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("chat group bots --help: %v\n%s", err, output.String()) + } + + help := output.String() + for _, visible := range []string{"--conversation-id", "--group-name"} { + if !strings.Contains(help, visible) { + t.Fatalf("chat group bots help missing %s:\n%s", visible, help) + } + } + if strings.Contains(help, "--group string") { + t.Fatalf("chat group bots help exposes hidden --group alias:\n%s", help) + } +} From 1d4c51a4d38aa3a77ef860e875b3f61d9629d52d Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 11:37:47 +0800 Subject: [PATCH 003/250] feat(drive): add local/Drive folder status, pull, push and sync --- CHANGELOG.md | 14 + internal/helpers/drive.go | 107 ++++ internal/helpers/drive_pull.go | 291 ++++++++++ internal/helpers/drive_pull_test.go | 385 ++++++++++++ internal/helpers/drive_push.go | 406 +++++++++++++ internal/helpers/drive_push_test.go | 284 +++++++++ internal/helpers/drive_status.go | 549 ++++++++++++++++++ internal/helpers/drive_status_test.go | 400 +++++++++++++ internal/helpers/drive_sync.go | 542 +++++++++++++++++ internal/helpers/drive_sync_test.go | 417 +++++++++++++ skills/mono/SKILL.md | 2 +- skills/mono/references/products/drive.md | 223 +++++++ skills/multi/dingtalk-drive/SKILL.md | 2 +- .../multi/dingtalk-drive/references/drive.md | 222 +++++++ 14 files changed, 3842 insertions(+), 2 deletions(-) create mode 100644 internal/helpers/drive_pull.go create mode 100644 internal/helpers/drive_pull_test.go create mode 100644 internal/helpers/drive_push.go create mode 100644 internal/helpers/drive_push_test.go create mode 100644 internal/helpers/drive_status.go create mode 100644 internal/helpers/drive_status_test.go create mode 100644 internal/helpers/drive_sync.go create mode 100644 internal/helpers/drive_sync_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 02d4254e..5077b270 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +### Added + +- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`, + `dws drive push`, and `dws drive sync` for file-level comparison and transfer + between a local folder and a Drive folder. Differences come from exact MD5 by + default or from modification time with `--quick`; `status` is read-only, `pull` + and `push` are one-directional with `--if-exists skip|smart|overwrite`, and + `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`. + Only regular files are transferred — online documents and shortcuts are skipped, + neither side deletes extra files, downloads are staged through a temporary file + and committed with an atomic rename, and remote names that would escape + `--local-folder` are reported as failures instead of being written. Every command + prints a structured summary on stdout and exits non-zero when any item fails. + ## [1.0.58-beta.4] - 2026-08-12 ### Added diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index 752ab25d..f637b39f 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -3200,6 +3200,108 @@ func newDriveCommand() *cobra.Command { RegisterCrossProductAliases(child) } + driveStatusCmd := &cobra.Command{ + Use: "status", + Short: "比较本地文件夹与钉盘文件夹的差异", + Long: `比较本地文件夹与钉盘文件夹的差异：本地取 --local-folder（绝对路径），钉盘取 +--remote-folder（文件夹 dentryUuid）指向的文件夹，按精确 MD5（默认）或快速 +modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path 相对各自根目录。 + +输出五类差异： + new_local 仅本地存在 + new_remote 仅钉盘存在 + modified 两侧都存在且本次检测判定为已变更 + unchanged 两侧都存在且本次检测判定为未变更 + unknown 两侧都存在，但 exact 模式下远端无可靠 MD5、无法核对内容（不判 unchanged/modified） + +只比对钉盘 type=file 的二进制文件（跳过在线文档与快捷方式）；本地只比对常规文件。`, + Example: ` dws drive status --local-folder /abs/path/repo --remote-folder + dws drive status --local-folder /abs/path/repo --remote-folder --space-id xxxx + dws drive status --local-folder /abs/path/repo --remote-folder --quick`, + RunE: runDriveStatus, + } + driveStatusCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") + driveStatusCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)") + driveStatusCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") + driveStatusCmd.Flags().Bool("quick", false, "快速模式：只比较 modified_time，不计算 MD5 (可选)") + + drivePullCmd := &cobra.Command{ + Use: "pull", + Short: "把钉盘文件夹单向镜像到本地（Drive → 本地）", + Long: `递归下载钉盘 --remote-folder 文件夹下所有 type=file 的文件到本地 +--local-folder 对应路径（子目录自动创建），单向、文件级镜像。 + +已存在的本地文件按 --if-exists 处理： + overwrite 默认，总是下载覆盖（Drive 作为权威源） + smart 推荐增量同步：本地 modified_time 已 ≥ 远端时则跳过下载 + skip 本地已存在则保持不动 + +输出 summary（downloaded/skipped/failed）与逐文件 items。 +若有文件下载失败，命令以非零退出码退出（error.type=partial_failure）。`, + Example: ` dws drive pull --local-folder /abs/path/repo --remote-folder + dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive pull --local-folder /abs/path/repo --remote-folder --space-id xxxx`, + RunE: runDrivePull, + } + drivePullCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") + drivePullCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)") + drivePullCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") + drivePullCmd.Flags().String("if-exists", "overwrite", "本地文件已存在时的策略: overwrite|smart|skip (可选)") + + drivePushCmd := &cobra.Command{ + Use: "push", + Short: "把本地文件夹单向镜像到钉盘（本地 → Drive）", + Long: `递归把本地 --local-folder 下的文件与子目录（含空目录）镜像到钉盘 +--remote-folder 文件夹：缺失的目录按需创建（已存在则复用，不重建），文件按 +--if-exists 处理。文件级镜像——只新增/覆盖，不删除远端多余文件。 + +已存在的远端文件按 --if-exists 处理： + skip 默认，安全：已存在则保持不动，只新增 + smart 增量同步：远端 modified_time 已 ≥ 本地时跳过，否则走覆盖路径 + overwrite 覆盖远端同名文件 + +输出 summary（uploaded/skipped/failed，uploaded 含新建与覆盖）与逐条 items +（含 folder_created）。若有文件失败，命令以非零退出码退出，结构化结果仍在 stdout。`, + Example: ` dws drive push --local-folder /abs/path/repo --remote-folder + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite`, + RunE: runDrivePush, + } + drivePushCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") + drivePushCmd.Flags().String("remote-folder", "", "钉盘目标文件夹 ID (dentryUuid) (必填)") + drivePushCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") + drivePushCmd.Flags().String("if-exists", "skip", "远端文件已存在时的策略: skip|smart|overwrite (可选)") + + driveSyncCmd := &cobra.Command{ + Use: "sync", + Short: "本地文件夹与钉盘文件夹双向同步（本地 ⇄ Drive）", + Long: `把本地 --local-folder 与钉盘 --remote-folder 做文件级双向同步：先按精确 MD5 +（默认）或快速 modified_time（--quick）算出差异，再按方向执行： + new_local 仅本地存在 → 上传到钉盘（缺失的远端目录按需创建） + new_remote 仅钉盘存在 → 下载到本地 + modified 两侧都变更 → 按 --on-conflict 解决 + unchanged 两侧一致 → 不动 + +两侧都变更时的 --on-conflict 策略： + remote-wins 默认，拉取远端覆盖本地 + local-wins 上传本地覆盖远端 + keep-both 本地文件改名保留，再拉取远端到原路径 + ask 交互式逐个询问 + +exact 模式下远端无可靠 MD5、内容无法核对的文件归入 unknown 并跳过（可改用 --quick）。 +文件级同步——只新增/覆盖，不删除任何一侧的多余文件。输出 summary（pulled/pushed/ +skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出，结构化结果仍在 stdout。`, + Example: ` dws drive sync --local-folder /abs/path/repo --remote-folder + dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict local-wins + dws drive sync --local-folder /abs/path/repo --remote-folder --quick --on-conflict keep-both`, + RunE: runDriveSync, + } + driveSyncCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") + driveSyncCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)") + driveSyncCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") + driveSyncCmd.Flags().String("on-conflict", "remote-wins", "两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (可选)") + driveSyncCmd.Flags().Bool("quick", false, "快速模式：只比较 modified_time，不计算 MD5 (可选)") + driveCmd.AddCommand( driveListCmd, driveListSpacesCmd, @@ -3222,6 +3324,11 @@ func newDriveCommand() *cobra.Command { drivePermissionCmd, drivePublishCmd, recycleCmd, + // 同步命令：status / pull / push / sync + driveStatusCmd, + drivePullCmd, + drivePushCmd, + driveSyncCmd, driveStarCmd, driveCoverCmd, driveRevertCmd, diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go new file mode 100644 index 00000000..f86adac1 --- /dev/null +++ b/internal/helpers/drive_pull.go @@ -0,0 +1,291 @@ +package helpers + +import ( + "context" + "encoding/json" + "fmt" + "os" + "path/filepath" + "runtime" + "sort" + "strings" + "time" + + "github.com/spf13/cobra" + "golang.org/x/text/unicode/norm" +) + +// ========================================================== +// drive pull — 把钉盘文件夹镜像到本地（Drive → 本地） +// ========================================================== +// ────────────────────────────────────────────────────────── +// dws drive pull — 把钉盘文件夹单向、文件级镜像到本地（Drive → 本地） +// +// 递归列出 --remote-folder 指向的钉盘文件夹下所有 type=FILE 的文件，逐一下载到 +// --local-folder 对应的相对路径。已存在的本地文件按 --if-exists 决定 +// overwrite / smart / skip。summary.failed > 0 时以非零退出码退出，并在 +// error.type=partial_failure / error.detail 里返回同一份 summary + items。 +// ────────────────────────────────────────────────────────── + +// --if-exists 的三种策略。 +const ( + ifExistsOverwrite = "overwrite" // 默认：总是下载覆盖（Drive 为权威源） + ifExistsSmart = "smart" // 推荐增量：本地 mtime 已 ≥ 远端 modified_time 则跳过 + ifExistsSkip = "skip" // 本地已存在则保持不动 +) + +// pull 动作分类。 +const ( + pullActionDownloaded = "downloaded" + pullActionSkipped = "skipped" + pullActionFailed = "failed" +) + +// drivePullItem 是输出 items[] 中每个文件的明细。 +type drivePullItem struct { + RelPath string `json:"rel_path"` + Action string `json:"action"` + Error string `json:"error,omitempty"` +} + +// drivePullSummary 是各动作的计数汇总。 +type drivePullSummary struct { + Downloaded int `json:"downloaded"` + Skipped int `json:"skipped"` + Failed int `json:"failed"` +} + +// drivePullResult 是 pull 命令的输出 schema。 +type drivePullResult struct { + Summary drivePullSummary `json:"summary"` + Items []drivePullItem `json:"items"` +} + +// drivePartialFailure 在 summary.failed > 0 时返回：以 exit=1 退出，并把 +// {"error":{"type":"partial_failure","detail":{summary,items}}} 原样透传出去。 +// 结构上满足 core 的 RawStderrError 与 ExitCoder 接口（无需 import internal 包）。 +type drivePartialFailure struct{ raw string } + +func (e *drivePartialFailure) Error() string { return e.raw } +func (e *drivePartialFailure) RawStderr() string { return e.raw } +func (e *drivePartialFailure) ExitCode() int { return 1 } + +// pathCollisionKey 把本地目标路径归一化成「目标文件系统下的等价键」，用于探测多个 +// 远端条目是否会落到同一个本地文件。caseInsensitive 为真时（Windows / 默认 macOS） +// 折叠大小写并做 Unicode NFC 规范化，从而把 A.txt/a.txt、NFC/NFD 记法视为同一目标； +// 大小写敏感文件系统（如 Linux ext4）则按精确路径区分，避免误判合法的异名文件。 +func pathCollisionKey(target string, caseInsensitive bool) string { + p := filepath.Clean(target) + if caseInsensitive { + p = norm.NFC.String(strings.ToLower(p)) + } + return p +} + +// isCaseInsensitiveFS 探测 dir 所在文件系统是否大小写不敏感：在 dir 下创建一个随机 +// 小写名探针文件，再用其大写名 stat；命中同一文件即为不敏感。dir 必须已存在。 +// 探测失败时回退到平台默认（Windows / macOS 视为不敏感，其它敏感）。 +func isCaseInsensitiveFS(dir string) bool { + platformDefault := runtime.GOOS == "windows" || runtime.GOOS == "darwin" + f, err := os.CreateTemp(dir, "dws-caseprobe-*") + if err != nil { + return platformDefault + } + name := f.Name() + _ = f.Close() + defer os.Remove(name) + base := filepath.Base(name) + upper := strings.ToUpper(base) + if upper == base { + return platformDefault // 名称无大小写差异，无法据此判定 + } + _, statErr := os.Stat(filepath.Join(dir, upper)) + return statErr == nil +} + +// detectTargetCollisions 按 caseInsensitive 指定的等价规则，找出会映射到同一本地目标 +// 的多个远端 rel_path，返回被判定冲突的 rel_path 集合（其中每个都不应落盘）。 +func detectTargetCollisions(absDir string, rels []string, caseInsensitive bool) map[string]bool { + groups := make(map[string][]string, len(rels)) + for _, rel := range rels { + target := filepath.Join(absDir, filepath.FromSlash(rel)) + key := pathCollisionKey(target, caseInsensitive) + groups[key] = append(groups[key], rel) + } + collided := make(map[string]bool) + for _, g := range groups { + if len(g) > 1 { + for _, r := range g { + collided[r] = true + } + } + } + return collided +} + +func runDrivePull(cmd *cobra.Command, _ []string) error { + if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil { + return err + } + localDir := mustGetFlag(cmd, "local-folder") + remoteDirID := mustGetFlag(cmd, "remote-folder") + // space-id 可选：不传则由 fetchRemoteDriveTree 使用「我的文件」对应的空间。 + spaceID := mustGetFlag(cmd, "space-id") + + ifExists, _ := cmd.Flags().GetString("if-exists") + if ifExists == "" { + ifExists = ifExistsOverwrite + } + switch ifExists { + case ifExistsOverwrite, ifExistsSmart, ifExistsSkip: + default: + return fmt.Errorf("--if-exists 取值非法: %s（可选 overwrite|smart|skip）", ifExists) + } + + absDir, err := validateLocalDirAbs(localDir) + if err != nil { + return err + } + + ctx := cmd.Context() + // 复用 status 的远端遍历：按 parentId 递归拿到所有 type=FILE 的文件（key 为 rel_path）。 + remote, err := fetchRemoteDriveTree(ctx, spaceID, remoteDirID, false) + if err != nil { + return err + } + + // 稳定顺序输出（rel_path 升序）。 + relPaths := make([]string, 0, len(remote)) + for rel := range remote { + relPaths = append(relPaths, rel) + } + sort.Strings(relPaths) + + // 落盘前先按目标文件系统的路径等价规则做一次全局冲突检查：大小写不敏感 FS 上 + // A.txt 与 a.txt（或 NFC/NFD 异写）会落到同一本地文件，默认 overwrite 会顺序覆盖、 + // 却把两项都报 downloaded 而静默丢文件。冲突的条目一律标记 failed、都不写入。 + // 探针需要根目录存在，这里按 pull「自动创建目标根」的语义先建好。 + if err := os.MkdirAll(absDir, 0o755); err != nil { + return fmt.Errorf("创建本地目录失败: %w", err) + } + collided := detectTargetCollisions(absDir, relPaths, isCaseInsensitiveFS(absDir)) + + res := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} + for _, rel := range relPaths { + rf := remote[rel] + // 多个远端条目映射到同一本地目标 → 全部 failed，不写入任何一个，避免静默覆盖丢文件。 + if collided[rel] { + res.Summary.Failed++ + res.Items = append(res.Items, drivePullItem{ + RelPath: rel, Action: pullActionFailed, + Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", + }) + continue + } + // 二次确认下载目标仍在本地根目录内，逃逸路径记为 failed 而非落盘。 + localPath, terr := resolveLocalTarget(absDir, rel) + if terr != nil { + res.Summary.Failed++ + res.Items = append(res.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: terr.Error()}) + continue + } + + action, perr := pullOneFile(ctx, spaceID, rf, localPath, ifExists) + item := drivePullItem{RelPath: rel, Action: action} + switch action { + case pullActionDownloaded: + res.Summary.Downloaded++ + case pullActionSkipped: + res.Summary.Skipped++ + case pullActionFailed: + res.Summary.Failed++ + if perr != nil { + item.Error = perr.Error() + } + } + res.Items = append(res.Items, item) + } + + if res.Summary.Failed > 0 { + // partial_failure：非零退出码，summary+items 一并放进 error.detail。 + payload := map[string]any{ + "error": map[string]any{ + "type": "partial_failure", + "detail": res, + }, + } + b, _ := json.Marshal(payload) + return &drivePartialFailure{raw: string(b)} + } + return deps.Out.PrintJSON(res) +} + +// pullOneFile 处理单个远端文件：按 --if-exists 决定是否跳过，否则下载到 localPath。 +// 返回动作分类（downloaded / skipped / failed）及失败时的 error。 +func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, ifExists string) (string, error) { + // 本地已存在常规文件时，按策略判断是否跳过下载。 + if fi, statErr := os.Stat(localPath); statErr == nil && fi.Mode().IsRegular() { + switch ifExists { + case ifExistsSkip: + return pullActionSkipped, nil + case ifExistsSmart: + // 远端时间可信且本地 mtime 已 ≥ 远端 → 视为已对齐，跳过； + // 时间缺失/非法时不盲跳，退回继续下载。 + if rf.ModifiedTimeValid && fi.ModTime().UnixMilli() >= rf.ModifiedTime { + return pullActionSkipped, nil + } + case ifExistsOverwrite: + // 总是下载覆盖。 + } + } + + // download_file → 拿到带签名的下载 URL 与请求头，再 HTTP GET 落盘。 + args := map[string]any{"fileId": rf.FileID} + if spaceID != "" { + args["spaceId"] = spaceID + } + text, err := callMCPToolReturnText(ctx, "download_file", args) + if err != nil { + return pullActionFailed, err + } + resourceURL, headers, err := parseDriveDownloadInfo(text) + if err != nil { + return pullActionFailed, err + } + + dir := filepath.Dir(localPath) + if err := os.MkdirAll(dir, 0o755); err != nil { + return pullActionFailed, fmt.Errorf("创建本地目录失败: %w", err) + } + + // 先下载到同目录下的临时文件，完整落盘后再原子 rename 覆盖目标：任何中途失败 + // （网络中断、超时、写盘错误）都不会截断或破坏已存在的原文件。同目录保证 + // rename 在同一文件系统内、可原子替换；rename 会替换目标符号链接本身而非跟随它。 + tmp, err := os.CreateTemp(dir, ".dws-pull-*") + if err != nil { + return pullActionFailed, fmt.Errorf("创建临时文件失败: %w", err) + } + tmpPath := tmp.Name() + _ = tmp.Close() // httpGetFile 会自行 os.Create 覆盖该临时文件 + // 除非成功 rename，否则始终清理临时文件，不留半成品。 + committed := false + defer func() { + if !committed { + _ = os.Remove(tmpPath) + } + }() + + if err := httpGetFile(ctx, resourceURL, headers, tmpPath); err != nil { + return pullActionFailed, err + } + // 对齐 mtime 放在 rename 之前，保证替换后的目标文件时间戳即为远端时间。 + if rf.ModifiedTimeValid { + t := time.UnixMilli(rf.ModifiedTime) + _ = os.Chtimes(tmpPath, t, t) + } + if err := os.Rename(tmpPath, localPath); err != nil { + return pullActionFailed, fmt.Errorf("替换目标文件失败: %w", err) + } + committed = true + return pullActionDownloaded, nil +} diff --git a/internal/helpers/drive_pull_test.go b/internal/helpers/drive_pull_test.go new file mode 100644 index 00000000..c913b9cb --- /dev/null +++ b/internal/helpers/drive_pull_test.go @@ -0,0 +1,385 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +// drivePullMockCaller 按工具名分发：list_files 返回可配置的树，download_file 返回预签名 URL。 +type drivePullMockCaller struct{ listJSON string } + +func (m *drivePullMockCaller) CallTool(_ context.Context, _ string, tool string, _ map[string]any) (*edition.ToolResult, error) { + text := `{"result":{"downloadUrl":"https://oss.example.com/dl"}}` + if tool == "list_files" { + text = m.listJSON + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil +} +func (m *drivePullMockCaller) Format() string { return "raw" } +func (m *drivePullMockCaller) DryRun() bool { return false } +func (m *drivePullMockCaller) Fields() string { return "" } +func (m *drivePullMockCaller) JQ() string { return "" } + +// ────────────────────────────────────────────────────────── +// isSafeRemoteSegment — 远端名称逐段安全校验（拒绝逃逸成分） +// ────────────────────────────────────────────────────────── + +func TestIsSafeRemoteSegment(t *testing.T) { + cases := []struct { + name string + ok bool + }{ + {"report.pdf", true}, + {"报告 2024.xlsx", true}, + {"a.b.c", true}, + {"", false}, + {".", false}, + {"..", false}, + {"a/b", false}, // 正斜杠分隔符 + {`a\b`, false}, // 反斜杠分隔符（Windows） + {"../etc", false}, // 相对上跳 + {"foo/../bar", false}, + {"/abs", false}, // 绝对路径成分 + } + for _, c := range cases { + if got := isSafeRemoteSegment(c.name); got != c.ok { + t.Errorf("isSafeRemoteSegment(%q) = %v, want %v", c.name, got, c.ok) + } + } +} + +// ────────────────────────────────────────────────────────── +// resolveLocalTarget — 拼接后必须仍位于本地根目录内 +// ────────────────────────────────────────────────────────── + +func TestResolveLocalTarget_withinRoot(t *testing.T) { + root := filepath.Clean(t.TempDir()) + got, err := resolveLocalTarget(root, "sub/a.txt") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + want := filepath.Join(root, "sub", "a.txt") + if got != want { + t.Errorf("target = %q, want %q", got, want) + } +} + +// 即便 isSafeRemoteSegment 被绕过，逐段拼出的逃逸路径也必须被 resolveLocalTarget 兜住。 +func TestResolveLocalTarget_escapeRejected(t *testing.T) { + root := filepath.Clean(t.TempDir()) + for _, rel := range []string{"../evil.txt", "../../etc/passwd", "sub/../../out.txt"} { + if _, err := resolveLocalTarget(root, rel); err == nil { + t.Errorf("resolveLocalTarget(%q) should reject escaping path", rel) + } + } +} + +// 根目录内的目录符号链接指向外部时，词法检查会放过（root/sub 仍在 root 下）， +// 必须靠符号链接解析挡住：sub -> /outside 时 sub/a.txt 应被拒绝。 +func TestResolveLocalTarget_dirSymlinkEscapeRejected(t *testing.T) { + root := filepath.Clean(t.TempDir()) + outside := filepath.Clean(t.TempDir()) + + link := filepath.Join(root, "sub") + if err := os.Symlink(outside, link); err != nil { + t.Skipf("平台不支持创建符号链接: %v", err) + } + + if _, err := resolveLocalTarget(root, "sub/a.txt"); err == nil { + t.Fatal("root/sub -> 外部目录时，sub/a.txt 应被拒绝（防符号链接逃逸）") + } + + // 对照：根目录内的真实子目录不应被误伤。 + if err := os.MkdirAll(filepath.Join(root, "real"), 0o755); err != nil { + t.Fatal(err) + } + if _, err := resolveLocalTarget(root, "real/a.txt"); err != nil { + t.Errorf("真实子目录不应被拒绝: %v", err) + } +} + +// 不存在的本地根目录必须放行（不误判逃逸），由后续 MkdirAll 创建。 +func TestResolveLocalTarget_nonexistentRootAllowed(t *testing.T) { + parent := filepath.Clean(t.TempDir()) + absDir := filepath.Join(parent, "not", "created", "yet") // 尚不存在 + got, err := resolveLocalTarget(absDir, "sub/a.txt") + if err != nil { + t.Fatalf("不存在的根目录不应被误判为逃逸: %v", err) + } + if want := filepath.Join(absDir, "sub", "a.txt"); got != want { + t.Errorf("target = %q, want %q", got, want) + } +} + +// 回归：--local-folder 指向尚不存在的绝对路径时，pull 应自动创建目录并下载， +// 而不是把每个远端文件都误判为符号链接逃逸而 failed。 +func TestDrivePull_nonexistentLocalRoot(t *testing.T) { + parent := t.TempDir() + absDir := filepath.Join(parent, "new", "repo") // 尚不存在 + + caller := &drivePullMockCaller{ + listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F1","modifyTime":1000}],"nextToken":""}}`, + } + + prevDeps := deps + prevArgs := os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("REMOTE"), 0o644) + }) + t.Cleanup(func() { + deps = prevDeps + os.Args = prevArgs + SetHTTPGetFile(nil) + }) + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + + full := []string{"pull", "--local-folder", absDir, "--remote-folder", "ROOT"} + os.Args = append([]string{"dws", "drive"}, full...) + root.SetArgs(append([]string{"drive"}, full...)) + + // 全部下载成功时 runDrivePull 返回 nil；若误判逃逸则会有 failed 并返回 partial_failure。 + if err := root.Execute(); err != nil { + t.Fatalf("pull 到不存在的本地根目录不应失败: %v", err) + } + got, rerr := os.ReadFile(filepath.Join(absDir, "a.txt")) + if rerr != nil { + t.Fatalf("目标文件应被创建: %v", rerr) + } + if string(got) != "REMOTE" { + t.Errorf("目标内容 = %q, want REMOTE", got) + } +} + +// ────────────────────────────────────────────────────────── +// detectTargetCollisions — 多个远端条目映射到同一本地目标 +// ────────────────────────────────────────────────────────── + +// 大小写不敏感 FS：A.txt 与 a.txt 落到同一目标 → 两者都判冲突；无关文件不受影响。 +func TestDetectTargetCollisions_caseInsensitive(t *testing.T) { + root := filepath.Clean(t.TempDir()) + rels := []string{"A.txt", "a.txt", "b.txt", "sub/C.md", "sub/c.md"} + collided := detectTargetCollisions(root, rels, true) + + for _, r := range []string{"A.txt", "a.txt", "sub/C.md", "sub/c.md"} { + if !collided[r] { + t.Errorf("%q 应被判为大小写冲突", r) + } + } + if collided["b.txt"] { + t.Error("b.txt 无冲突，不应被标记") + } +} + +// 大小写敏感 FS：A.txt 与 a.txt 是两个合法文件 → 不应误判冲突。 +func TestDetectTargetCollisions_caseSensitive(t *testing.T) { + root := filepath.Clean(t.TempDir()) + rels := []string{"A.txt", "a.txt", "b.txt"} + collided := detectTargetCollisions(root, rels, false) + if len(collided) != 0 { + t.Errorf("大小写敏感 FS 不应有冲突, got %v", collided) + } +} + +// 平台名称规范化冲突：同名的 NFC 与 NFD 记法在不敏感 FS 上落到同一目标 → 冲突。 +func TestDetectTargetCollisions_unicodeNormalization(t *testing.T) { + root := filepath.Clean(t.TempDir()) + nfc := "café.txt" // café（预组合 é） + nfd := "café.txt" // café（e + 组合尖音符） + if nfc == nfd { + t.Fatal("测试数据应为不同字节序列") + } + + ci := detectTargetCollisions(root, []string{nfc, nfd}, true) + if !ci[nfc] || !ci[nfd] { + t.Errorf("NFC/NFD 异写在大小写不敏感 FS 上应判冲突, got %v", ci) + } + // 大小写/规范化敏感 FS 上视为两个不同文件，不冲突。 + cs := detectTargetCollisions(root, []string{nfc, nfd}, false) + if len(cs) != 0 { + t.Errorf("敏感 FS 上 NFC/NFD 不应冲突, got %v", cs) + } +} + +// isCaseInsensitiveFS 应能对临时目录给出与实际探针一致的判定（本机自洽）。 +func TestIsCaseInsensitiveFS_selfConsistent(t *testing.T) { + dir := t.TempDir() + got := isCaseInsensitiveFS(dir) + // 实测：写一个小写名，再用大写名 stat。 + lower := filepath.Join(dir, "probe_case_xyz.txt") + if err := os.WriteFile(lower, []byte("x"), 0o644); err != nil { + t.Fatal(err) + } + _, err := os.Stat(filepath.Join(dir, "PROBE_CASE_XYZ.TXT")) + actualInsensitive := err == nil + if got != actualInsensitive { + t.Errorf("isCaseInsensitiveFS=%v，但实测大写名可 stat=%v", got, actualInsensitive) + } +} + +// ────────────────────────────────────────────────────────── +// pullOneFile — 覆盖下载中断不得破坏原文件（原子替换） +// ────────────────────────────────────────────────────────── + +// 下载中途失败时：命令报告 failed，原有本地文件内容必须原封不动，且不留临时残file。 +func TestPullOneFile_downloadFailureKeepsOriginal(t *testing.T) { + root := t.TempDir() + target := filepath.Join(root, "a.txt") + const original = "ORIGINAL-CONTENT-DO-NOT-LOSE" + mustWrite(t, target, original) + + prevDeps := deps + prevArgs := os.Args + // download_file 的 MCP 调用走 mock；httpGetFile 注入为“写入部分内容后报错”。 + deps = &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + // 模拟传输中断：先截断/写半截，再返回错误。 + _ = os.WriteFile(dest, []byte("HALF"), 0o644) + return errors.New("connection reset") + }) + t.Cleanup(func() { + deps = prevDeps + os.Args = prevArgs + SetHTTPGetFile(nil) + }) + + rf := &remoteFile{RelPath: "a.txt", FileID: "F1"} + action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite) + if action != pullActionFailed || err == nil { + t.Fatalf("expected failed action with error, got action=%q err=%v", action, err) + } + + // 原文件必须保持原内容。 + got, rerr := os.ReadFile(target) + if rerr != nil { + t.Fatalf("原文件应仍存在: %v", rerr) + } + if string(got) != original { + t.Errorf("原文件被破坏: got %q, want %q", got, original) + } + + // 不应残留临时文件。 + entries, _ := os.ReadDir(root) + for _, e := range entries { + if e.Name() != "a.txt" { + t.Errorf("下载失败后残留了临时文件: %s", e.Name()) + } + } +} + +// 下载成功时：临时文件被原子重命名为目标，内容与远端一致。 +func TestPullOneFile_downloadSuccessReplacesTarget(t *testing.T) { + root := t.TempDir() + target := filepath.Join(root, "a.txt") + mustWrite(t, target, "OLD") + + prevDeps := deps + prevArgs := os.Args + deps = &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("NEW-CONTENT"), 0o644) + }) + t.Cleanup(func() { + deps = prevDeps + os.Args = prevArgs + SetHTTPGetFile(nil) + }) + + rf := &remoteFile{RelPath: "a.txt", FileID: "F1"} + action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite) + if err != nil || action != pullActionDownloaded { + t.Fatalf("expected downloaded, got action=%q err=%v", action, err) + } + got, _ := os.ReadFile(target) + if string(got) != "NEW-CONTENT" { + t.Errorf("目标未被替换为新内容: got %q", got) + } + entries, _ := os.ReadDir(root) + if len(entries) != 1 { + t.Errorf("成功后目录应只有目标文件，got %d 项", len(entries)) + } +} + +// ────────────────────────────────────────────────────────── +// parseDriveDownloadInfo — drive download_file 返回解析 +// ────────────────────────────────────────────────────────── + +// drive 的正常返回：result.downloadUrl 是预签名 URL，无需额外 header。 +func TestParseDriveDownloadInfo_downloadUrl(t *testing.T) { + text := `{"result":{"downloadType":"urlPreSignature","downloadUrl":"https://oss.example.com/f.file?Expires=1&Signature=xyz","fileName":"a.txt"},"success":true}` + url, headers, err := parseDriveDownloadInfo(text) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if url != "https://oss.example.com/f.file?Expires=1&Signature=xyz" { + t.Errorf("url = %q", url) + } + if len(headers) != 0 { + t.Errorf("预签名 URL 不应带 header, got %v", headers) + } +} + +// 兼容 flat resourceUrl 字段。 +func TestParseDriveDownloadInfo_resourceUrlFallback(t *testing.T) { + text := `{"resourceUrl":"https://flat.example.com/dl"}` + url, _, err := parseDriveDownloadInfo(text) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if url != "https://flat.example.com/dl" { + t.Errorf("url = %q", url) + } +} + +// 兼容 resourceUrls[].url 数组格式（在 result 包裹下）。 +func TestParseDriveDownloadInfo_resourceUrlsArrayFallback(t *testing.T) { + text := `{"result":{"resourceUrls":[{"url":"https://arr.example.com/dl","headers":{}}]}}` + url, _, err := parseDriveDownloadInfo(text) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if url != "https://arr.example.com/dl" { + t.Errorf("url = %q", url) + } +} + +func TestParseDriveDownloadInfo_missingURL(t *testing.T) { + text := `{"result":{"fileName":"a.txt"}}` + if _, _, err := parseDriveDownloadInfo(text); err == nil { + t.Fatal("expected error when downloadUrl is empty") + } +} + +func TestParseDriveDownloadInfo_invalidJSON(t *testing.T) { + if _, _, err := parseDriveDownloadInfo("not json"); err == nil { + t.Fatal("expected error for invalid JSON") + } +} + +// ────────────────────────────────────────────────────────── +// drivePartialFailure — pull 部分失败错误：exit=1，JSON 原样透传 +// ────────────────────────────────────────────────────────── + +func TestDrivePartialFailure(t *testing.T) { + raw := `{"error":{"type":"partial_failure","detail":{}}}` + e := &drivePartialFailure{raw: raw} + if e.ExitCode() != 1 { + t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) + } + if e.Error() != raw || e.RawStderr() != raw { + t.Errorf("Error()/RawStderr() should return the raw JSON verbatim") + } +} diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go new file mode 100644 index 00000000..52eb2827 --- /dev/null +++ b/internal/helpers/drive_push.go @@ -0,0 +1,406 @@ +package helpers + +import ( + "context" + "encoding/json" + "fmt" + "io/fs" + "log/slog" + "path/filepath" + "sort" + "strings" + + "github.com/spf13/cobra" +) + +// ========================================================== +// drive push — 把本地文件夹镜像到钉盘（本地 → Drive） +// ========================================================== +// ────────────────────────────────────────────────────────── +// dws drive push — 把本地目录单向、文件级镜像到钉盘（本地 → Drive） +// +// 递归遍历 --local-folder 下所有常规文件与子目录（含空目录），按相对路径在 +// --remote-folder 指向的钉盘文件夹里新建/覆盖/跳过。已存在的远端目录复用其 +// fileId、不重建；缺失的目录按需 create_folder。文件按 --if-exists 决定 +// skip / smart / overwrite。summary.failed > 0 时以非零退出码退出（结构化 +// summary + items 仍打印在 stdout 上）。 +// ────────────────────────────────────────────────────────── + +// push 动作分类。 +const ( + pushActionUploaded = "uploaded" // 新建上传 + pushActionOverwritten = "overwritten" // 覆盖已存在的远端文件 + pushActionSkipped = "skipped" // 按 --if-exists 跳过 + pushActionFolderCreated = "folder_created" // 新建远端目录（不计入 uploaded） + pushActionFailed = "failed" +) + +// localPushFile 描述一个待推送的本地常规文件。 +type localPushFile struct { + RelPath string + AbsPath string + ModTimeMillis int64 + Size int64 +} + +// drivePushItem 是输出 items[] 中每个条目的明细。 +type drivePushItem struct { + RelPath string `json:"rel_path"` + Action string `json:"action"` + SizeBytes *int64 `json:"size_bytes,omitempty"` + Error string `json:"error,omitempty"` +} + +// drivePushSummary 是各动作的计数汇总。uploaded 同时统计新建与覆盖。 +type drivePushSummary struct { + Uploaded int `json:"uploaded"` + Skipped int `json:"skipped"` + Failed int `json:"failed"` + Aborted bool `json:"aborted"` +} + +type drivePushResult struct { + Summary drivePushSummary `json:"summary"` + Items []drivePushItem `json:"items"` +} + +// drivePushFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout， +// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明。 +type drivePushFailure struct{ failed int } + +func (e *drivePushFailure) Error() string { + return fmt.Sprintf("drive push: %d file(s) failed", e.failed) +} +func (e *drivePushFailure) RawStderr() string { return e.Error() } +func (e *drivePushFailure) ExitCode() int { return 1 } + +func runDrivePush(cmd *cobra.Command, _ []string) error { + if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil { + return err + } + localDir := mustGetFlag(cmd, "local-folder") + remoteDirID := mustGetFlag(cmd, "remote-folder") + spaceID := mustGetFlag(cmd, "space-id") + + // push 默认 skip（安全，只新增不覆盖）。 + ifExists, _ := cmd.Flags().GetString("if-exists") + if ifExists == "" { + ifExists = ifExistsSkip + } + switch ifExists { + case ifExistsSkip, ifExistsSmart, ifExistsOverwrite: + default: + return fmt.Errorf("--if-exists 取值非法: %s（可选 skip|smart|overwrite）", ifExists) + } + + absDir, err := validateLocalDirAbs(localDir) + if err != nil { + return err + } + + ctx := cmd.Context() + // 远端现状：已存在的文件（用于 --if-exists 判断）与目录（rel_path → fileId，用于复用/定位父目录）。 + remoteFiles, remoteFolders, err := fetchRemoteTreeForPush(ctx, spaceID, remoteDirID) + if err != nil { + return err + } + + localDirs, localFiles, err := walkLocalForPush(absDir) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } + + res := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))} + + // 第一阶段：按需创建远端目录（浅层在前，保证父目录先于子目录存在）。 + for _, dir := range localDirs { + if _, ok := remoteFolders[dir]; ok { + continue // 远端已存在，复用 fileId，不留痕 + } + parentRel, name := splitRel(dir) + parentID, ok := remoteFolders[parentRel] + if !ok || parentID == "" { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: "父目录未能创建"}) + continue + } + fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name) + if cerr != nil || fid == "" { + res.Summary.Failed++ + msg := "create_folder 未返回 fileId" + if cerr != nil { + msg = cerr.Error() + } + res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg}) + continue + } + remoteFolders[dir] = fid + res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFolderCreated}) + } + + // 第二阶段：上传/覆盖/跳过文件。 + for i := range localFiles { + lf := localFiles[i] + size := lf.Size + parentRel, name := splitRel(lf.RelPath) + parentID, ok := remoteFolders[parentRel] + if !ok || parentID == "" { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: "父目录未能创建"}) + continue + } + + rf, exists := remoteFiles[lf.RelPath] + action := pushActionUploaded + overwriteID := "" + if exists { + switch ifExists { + case ifExistsSkip: + res.Summary.Skipped++ + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionSkipped, SizeBytes: &size}) + continue + case ifExistsSmart: + // 远端时间可信且已 ≥ 本地 → 跳过；否则走覆盖路径。 + if rf.ModifiedTimeValid && rf.ModifiedTime >= lf.ModTimeMillis { + res.Summary.Skipped++ + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionSkipped, SizeBytes: &size}) + continue + } + action = pushActionOverwritten + case ifExistsOverwrite: + action = pushActionOverwritten + } + // 覆盖分支必须走覆盖上传（传 overwriteFileId、不传 parentId）， + // 否则会在同目录新建重名副本而非原地覆盖。 + if action == pushActionOverwritten { + overwriteID = rf.FileID + } + } + + if err := pushUploadFile(ctx, spaceID, parentID, overwriteID, name, lf.AbsPath, size); err != nil { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: err.Error()}) + continue + } + res.Summary.Uploaded++ // uploaded 同时统计新建与覆盖 + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: action, SizeBytes: &size}) + } + + // 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。 + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr + } + if res.Summary.Failed > 0 { + return &drivePushFailure{failed: res.Summary.Failed} + } + return nil +} + +// fetchRemoteTreeForPush 递归拉取 rootID 下的远端现状：files（rel_path → *remoteFile， +// 用于 --if-exists 判断）与 folders（rel_path → fileId，rel_path "" 即 rootID 本身）。 +func fetchRemoteTreeForPush(ctx context.Context, spaceID, rootID string) (map[string]*remoteFile, map[string]string, error) { + files := make(map[string]*remoteFile) + folders := map[string]string{"": rootID} + if err := walkRemoteForPush(ctx, spaceID, rootID, "", files, folders, 0); err != nil { + return nil, nil, err + } + return files, folders, nil +} + +func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, files map[string]*remoteFile, folders map[string]string, depth int) error { + if depth > remoteMaxDepth { + return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth) + } + nextToken := "" + for { + args := map[string]any{"maxResults": float64(driveListPageSize)} + if spaceID != "" { + args["spaceId"] = spaceID + } + if parentID != "" { + args["parentId"] = parentID + } + if nextToken != "" { + args["nextToken"] = nextToken + } + + text, err := callMCPToolReturnText(ctx, "list_files", args) + if err != nil { + return err + } + items, token, err := parseDriveList(text) + if err != nil { + return err + } + + for _, it := range items { + name := it.name() + if name == "" { + continue + } + // 与 walkRemoteDir 一致：非规范名称跳过，避免逃逸性 rel_path 进入索引。 + if !isSafeRemoteSegment(name) { + slog.Warn("overlay: 跳过含非法路径成分的远端条目", "name", name, "relBase", relBase) + continue + } + childRel := name + if relBase != "" { + childRel = relBase + "/" + name + } + if it.isFolder() { + folders[childRel] = it.id() + if err := walkRemoteForPush(ctx, spaceID, it.id(), childRel, files, folders, depth+1); err != nil { + return err + } + continue + } + if !it.isFile() { + continue + } + modMillis, modValid := it.modifiedMillis() + files[childRel] = &remoteFile{ + RelPath: childRel, + FileID: it.id(), + Hash: it.hash(), + ModifiedTime: modMillis, + ModifiedTimeValid: modValid, + } + } + + if token == "" || token == nextToken { + break + } + nextToken = token + } + return nil +} + +// walkLocalForPush 遍历本地根目录，返回所有子目录 rel_path（不含根本身，浅层在前） +// 与所有常规文件。dirs 升序排序保证父目录先于子目录被创建。 +func walkLocalForPush(root string) ([]string, []localPushFile, error) { + var dirs []string + var files []localPushFile + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + rel, rerr := filepath.Rel(root, path) + if rerr != nil { + return rerr + } + if rel == "." { + return nil // 根目录本身不处理 + } + relSlash := filepath.ToSlash(rel) + if d.IsDir() { + dirs = append(dirs, relSlash) + return nil + } + info, ierr := d.Info() + if ierr != nil { + return ierr + } + // 只推送常规文件；符号链接、设备文件等忽略。 + if !info.Mode().IsRegular() { + return nil + } + files = append(files, localPushFile{ + RelPath: relSlash, + AbsPath: path, + ModTimeMillis: info.ModTime().UnixMilli(), + Size: info.Size(), + }) + return nil + }) + if err != nil { + return nil, nil, err + } + // 字典序即浅层在前（"a" < "a/b" < "a/b/c"），父目录先于子目录。 + sort.Strings(dirs) + return dirs, files, nil +} + +// pushCreateFolder 在 parentID 下创建名为 name 的文件夹，返回新目录的 fileId。 +func pushCreateFolder(ctx context.Context, spaceID, parentID, name string) (string, error) { + args := map[string]any{"name": name} + if spaceID != "" { + args["spaceId"] = spaceID + } + if parentID != "" { + args["parentId"] = parentID + } + text, err := callMCPToolReturnText(ctx, "create_folder", args) + if err != nil { + return "", err + } + return parseNodeID(text), nil +} + +// pushUploadFile 走 get_upload_info → OSS PUT → commit_upload 三步，把本地文件 +// 上传到 parentID 目录下。复用 drive upload 的凭证解析与 HTTP PUT。 +// +// overwriteFileID 非空时走覆盖流程（与 uploadToDrive 一致）：get_upload_info 与 +// commit_upload 两个阶段都传 overwriteFileId、都不传 parentId（服务端据此设置 +// conflictStrategy=OVERWRITE，原地覆盖而非在同目录新建重名副本）。 +func pushUploadFile(ctx context.Context, spaceID, parentID, overwriteFileID, fileName, filePath string, fileSize int64) error { + step1 := map[string]any{"fileName": fileName, "fileSize": float64(fileSize)} + if spaceID != "" { + step1["spaceId"] = spaceID + } + if overwriteFileID != "" { + step1["overwriteFileId"] = overwriteFileID + } else if parentID != "" { + step1["parentId"] = parentID + } + text, err := callMCPToolReturnText(ctx, "get_upload_info", step1) + if err != nil { + return err + } + resourceURL, uploadID, ossHeaders, err := parseDriveUploadInfo(text) + if err != nil { + return err + } + if err := httpPutFile(ctx, resourceURL, ossHeaders, filePath, fileSize); err != nil { + return err + } + commit := map[string]any{"fileName": fileName, "fileSize": float64(fileSize), "uploadId": uploadID} + if spaceID != "" { + commit["spaceId"] = spaceID + } + if overwriteFileID != "" { + commit["overwriteFileId"] = overwriteFileID + } else if parentID != "" { + commit["parentId"] = parentID + } + _, err = callMCPToolReturnText(ctx, "commit_upload", commit) + return err +} + +// parseNodeID 从 create_folder / commit 等返回里抽出节点 fileId（带 fallback）。 +func parseNodeID(text string) string { + var data map[string]any + if err := json.Unmarshal([]byte(text), &data); err != nil { + return "" + } + if r, ok := data["result"].(map[string]any); ok { + data = r + } + for _, k := range []string{"fileId", "dentryUuid", "dentryId", "id", "nodeId"} { + if s, ok := data[k].(string); ok && s != "" { + return s + } + } + return "" +} + +// splitRel 把 rel_path 拆成父路径与末段名："a/b/c" → ("a/b","c")，"c" → ("","c")。 +func splitRel(rel string) (string, string) { + if i := strings.LastIndex(rel, "/"); i >= 0 { + return rel[:i], rel[i+1:] + } + return "", rel +} + +// checkFileNotDingTalkDoc 通过 get_file_info 检查文件类型， +// 若为钉钉在线文档 (adoc/axls/amind/adraw) 则返回错误，提示使用对应服务命令。 +// 探测失败（如无效 fileId）不阻断流程，让后续 MCP 工具自行报错。 diff --git a/internal/helpers/drive_push_test.go b/internal/helpers/drive_push_test.go new file mode 100644 index 00000000..c0d92ad1 --- /dev/null +++ b/internal/helpers/drive_push_test.go @@ -0,0 +1,284 @@ +package helpers + +import ( + "context" + "io" + "os" + "path/filepath" + "sort" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +// ────────────────────────────────────────────────────────── +// splitRel — rel_path 拆父路径 / 末段名 +// ────────────────────────────────────────────────────────── + +func TestSplitRel(t *testing.T) { + cases := []struct { + in string + parent, base string + }{ + {"a/b/c", "a/b", "c"}, + {"a/b", "a", "b"}, + {"c", "", "c"}, + {"", "", ""}, + } + for _, c := range cases { + p, b := splitRel(c.in) + if p != c.parent || b != c.base { + t.Errorf("splitRel(%q) = (%q,%q), want (%q,%q)", c.in, p, b, c.parent, c.base) + } + } +} + +// ────────────────────────────────────────────────────────── +// parseNodeID — create_folder / commit 返回里抽 fileId +// ────────────────────────────────────────────────────────── + +func TestParseNodeID(t *testing.T) { + cases := []struct { + name string + text string + want string + }{ + {"result.fileId", `{"result":{"fileId":"F1","name":"x"},"success":true}`, "F1"}, + {"top-level fileId", `{"fileId":"F2"}`, "F2"}, + {"dentryUuid fallback", `{"result":{"dentryUuid":"D1"}}`, "D1"}, + {"dentryId fallback", `{"result":{"dentryId":"D2"}}`, "D2"}, + {"missing", `{"result":{"name":"x"}}`, ""}, + {"invalid json", `not json`, ""}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := parseNodeID(c.text); got != c.want { + t.Errorf("parseNodeID = %q, want %q", got, c.want) + } + }) + } +} + +// ────────────────────────────────────────────────────────── +// walkLocalForPush — 本地遍历（含空目录，父目录先于子目录） +// ────────────────────────────────────────────────────────── + +func TestWalkLocalForPush(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "a.txt"), "hello") // 5 bytes + mustWrite(t, filepath.Join(root, "sub1", "b.txt"), "worl") // 4 bytes, 建出 sub1 + if err := os.MkdirAll(filepath.Join(root, "sub1", "sub2"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.MkdirAll(filepath.Join(root, "empty"), 0o755); err != nil { + t.Fatal(err) + } + + dirs, files, err := walkLocalForPush(root) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // 目录：含空目录，不含根本身，且父目录先于子目录（字典序即可保证）。 + wantDirs := []string{"empty", "sub1", "sub1/sub2"} + if !sort.StringsAreSorted(dirs) { + t.Errorf("dirs should be sorted (parent before child): %v", dirs) + } + if !equalStrings(dirs, wantDirs) { + t.Errorf("dirs = %v, want %v", dirs, wantDirs) + } + + // 文件：rel_path 用 /，记录 size 与 mtime。 + byRel := map[string]localPushFile{} + for _, f := range files { + byRel[f.RelPath] = f + } + if len(byRel) != 2 { + t.Fatalf("expected 2 files, got %d: %v", len(byRel), files) + } + a, ok := byRel["a.txt"] + if !ok || a.Size != 5 { + t.Errorf("a.txt size = %d, want 5 (present=%v)", a.Size, ok) + } + if a.AbsPath == "" || a.ModTimeMillis == 0 { + t.Error("file should record AbsPath and mtime") + } + b, ok := byRel["sub1/b.txt"] + if !ok || b.Size != 4 { + t.Errorf("sub1/b.txt size = %d, want 4 (present=%v)", b.Size, ok) + } +} + +// ────────────────────────────────────────────────────────── +// drivePushFailure — push 部分失败错误：exit=1 +// ────────────────────────────────────────────────────────── + +func TestDrivePushFailure(t *testing.T) { + e := &drivePushFailure{failed: 3} + if e.ExitCode() != 1 { + t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) + } + if e.Error() != e.RawStderr() { + t.Error("Error() 与 RawStderr() 应一致") + } + if !strings.Contains(e.Error(), "3") { + t.Errorf("Error() 应包含失败数, got %q", e.Error()) + } +} + +// ────────────────────────────────────────────────────────── +// push 覆盖流程 — get_upload_info / commit_upload 两阶段的 MCP 参数 +// ────────────────────────────────────────────────────────── + +// driveMCPCall 记录一次 MCP 工具调用。 +type driveMCPCall struct { + toolName string + args map[string]any +} + +// driveSyncMockCaller 按工具名分发返回，并记录全部调用，供断言 MCP 参数。 +type driveSyncMockCaller struct { + calls []driveMCPCall + listJSON string // list_files 返回体 + dryRun bool // --dry-run：只算差异，不执行任何写操作 +} + +func (m *driveSyncMockCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) { + m.calls = append(m.calls, driveMCPCall{toolName: toolName, args: args}) + var text string + switch toolName { + case "list_files": + text = m.listJSON + case "get_upload_info": + // 返回可被 parseDriveUploadInfo 解析的凭证。 + text = `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}` + case "download_file": + // 返回可被 parseDriveDownloadInfo 解析的预签名下载链接。 + text = `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}` + default: // commit_upload 等 + text = `{"result":{"fileId":"NEW_FID"},"success":true}` + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil +} + +func (m *driveSyncMockCaller) Format() string { return "raw" } +func (m *driveSyncMockCaller) DryRun() bool { return m.dryRun } +func (m *driveSyncMockCaller) Fields() string { return "" } +func (m *driveSyncMockCaller) JQ() string { return "" } + +func (m *driveSyncMockCaller) callsFor(tool string) []driveMCPCall { + var out []driveMCPCall + for _, c := range m.calls { + if c.toolName == tool { + out = append(out, c) + } + } + return out +} + +// runDrivePushTest 用 mock caller 执行 `drive push`，返回捕获的调用。 +// 注入 httpPutFile 为 no-op，避免真实 OSS 上传。 +func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error { + t.Helper() + + prevDeps := deps + prevOSArgs := os.Args + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) + + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + + full := append([]string{"push", "--local-folder", localDir, "--remote-folder", "ROOT"}, args...) + os.Args = append([]string{"dws", "drive"}, full...) + root.SetArgs(append([]string{"drive"}, full...)) + + t.Cleanup(func() { + deps = prevDeps + os.Args = prevOSArgs + SetHTTPPutFile(nil) + }) + + return root.Execute() +} + +// 覆盖分支：get_upload_info 与 commit_upload 两阶段都必须传 overwriteFileId、都不传 parentId。 +func TestDrivePush_overwriteUsesOverwriteFileId(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "new-content") + + caller := &driveSyncMockCaller{ + // 远端根目录下已存在同名 a.txt，fileId=REMOTE_FID。 + listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"REMOTE_FID","md5":"x","modifyTime":1000}],"nextToken":""}}`, + } + if err := runDrivePushTest(t, caller, dir, "--if-exists", "overwrite"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + up := caller.callsFor("get_upload_info") + if len(up) != 1 { + t.Fatalf("expected 1 get_upload_info call, got %d", len(up)) + } + if got := up[0].args["overwriteFileId"]; got != "REMOTE_FID" { + t.Errorf("get_upload_info overwriteFileId = %v, want REMOTE_FID", got) + } + if _, ok := up[0].args["parentId"]; ok { + t.Error("覆盖时 get_upload_info 不应传 parentId") + } + + commit := caller.callsFor("commit_upload") + if len(commit) != 1 { + t.Fatalf("expected 1 commit_upload call, got %d", len(commit)) + } + if got := commit[0].args["overwriteFileId"]; got != "REMOTE_FID" { + t.Errorf("commit_upload overwriteFileId = %v, want REMOTE_FID", got) + } + if _, ok := commit[0].args["parentId"]; ok { + t.Error("覆盖时 commit_upload 不应传 parentId") + } +} + +// 新建分支：远端不存在同名文件时走普通上传——两阶段都传 parentId、都不传 overwriteFileId。 +func TestDrivePush_newUploadUsesParentId(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "b.txt"), "brand-new") + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[],"nextToken":""}}`, // 远端空 + } + if err := runDrivePushTest(t, caller, dir, "--if-exists", "overwrite"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + up := caller.callsFor("get_upload_info") + if len(up) != 1 { + t.Fatalf("expected 1 get_upload_info call, got %d", len(up)) + } + if _, ok := up[0].args["overwriteFileId"]; ok { + t.Error("新建上传不应传 overwriteFileId") + } + if got := up[0].args["parentId"]; got != "ROOT" { + t.Errorf("get_upload_info parentId = %v, want ROOT", got) + } + commit := caller.callsFor("commit_upload") + if len(commit) != 1 || commit[0].args["parentId"] != "ROOT" { + t.Errorf("commit_upload should carry parentId=ROOT, got %v", commit) + } +} + +func equalStrings(a, b []string) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if a[i] != b[i] { + return false + } + } + return true +} diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go new file mode 100644 index 00000000..7e43f3db --- /dev/null +++ b/internal/helpers/drive_status.go @@ -0,0 +1,549 @@ +package helpers + +import ( + "context" + "crypto/md5" + "encoding/base64" + "encoding/json" + "fmt" + "io" + "io/fs" + "log/slog" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/spf13/cobra" +) + +// ========================================================== +// drive status — 比较本地文件夹与钉盘文件夹的差异 +// ========================================================== +// ────────────────────────────────────────────────────────── +// dws drive status — 比较本地文件夹与钉盘文件夹的差异 +// +// 只读命令：本地取 --local-folder（绝对路径），钉盘取 --remote-folder +// （文件夹 dentryUuid）指向的文件夹，按精确 MD5（默认）或快速 modified_time +// （--quick）逐文件比对，输出 new_local / new_remote / modified / unchanged / +// unknown 五类差异（exact 模式远端无可靠 md5 的文件归入 unknown）。两侧各自递归 +// 遍历，rel_path 相对各自根目录。 +// +// 后端交互（按 parentId 递归拉取 list_files、只保留 type=file 的二进制文件、并为 +// 每个条目填充 hash 或者 modified_time），见 fetchRemoteDriveTree。 +// ────────────────────────────────────────────────────────── + +// driveStatusEntry 是输出 schema 中每个差异项的形态：{"rel_path": "..."}。 +type driveStatusEntry struct { + RelPath string `json:"rel_path"` +} + +// driveStatusResult 是 status 命令成功时的输出 schema。 +// 五个切片都初始化为非 nil，保证 JSON 序列化为 [] 而不是 null。 +// +// unknown：exact 模式下双端都存在、但远端未返回可靠 md5 的文件——此时无法核对 +// 内容，既不能判 unchanged（会误报未变更），也不宜硬判 modified（会误报变更）， +// 如实归入 unknown，让降级模式在输出里显式可见。quick 模式不会产生 unknown。 +type driveStatusResult struct { + Detection string `json:"detection"` + NewLocal []driveStatusEntry `json:"new_local"` + NewRemote []driveStatusEntry `json:"new_remote"` + Modified []driveStatusEntry `json:"modified"` + Unchanged []driveStatusEntry `json:"unchanged"` + Unknown []driveStatusEntry `json:"unknown"` +} + +// localFile 描述一个本地常规文件。 +type localFile struct { + RelPath string + AbsPath string // 绝对路径，用于按需计算 MD5 + Hash string // MD5（base64）；仅在双端都存在且非 quick 模式时按需计算 + Size int64 // 本地文件字节数 + ModTimeMillis int64 // 本地 mtime，Unix 毫秒 +} + +// remoteFile 描述一个云端 type=file 的二进制文件。 +// 由 fetchRemoteDriveTree 填充。 +type remoteFile struct { + RelPath string + FileID string // dentryUuid；pull 下载时作为 download_file 的 fileId + Hash string // 远端 md5（base64，exact 模式用；为空时该文件归入 unknown） + Size int64 // 远端文件字节数 + ModifiedTime int64 // 远端 modified_time，Unix 毫秒（quick / smart 模式比较用） + ModifiedTimeValid bool // 远端时间戳是否可信；不可信时走保守路径 +} + +// 每次 list_files 请求的分页大小。后端约束 maxResults 必须在 1..50 之间。 +const driveListPageSize = 50 + +// remoteMaxDepth 是递归遍历子文件夹的最大层级，防止云端目录出现环形引用时死循环。 +const remoteMaxDepth = 64 + +// fetchRemoteDriveTree 递归拉取云端文件夹 parentID 下的文件树，返回所有 type=FILE 的 +// 二进制文件索引（key 为 rel_path）。spaceID 为空时省略 spaceId 参数，由 MCP Server +// 默认到「我的文件」（与其它 drive 命令一致）；parentID 为待比对的云端根文件夹 dentryUuid。 +// +// 实现要点： +// - 通过 drive 的 list_files MCP 工具，按 parentId（文件夹 dentryUuid）逐层遍历； +// - 单个目录文件过多时按 nextToken 分批拉取（maxResults ≤ 50）； +// - 遇到子文件夹用其 dentryUuid 作为下一层的 parentId 递归进入； +// - rel_path 由各层文件夹名逐层拼接得到（相对 parentID 根），与本地相对路径对齐； +// - 只纳入明确 type=FILE 的条目，其余类型（在线文档、快捷方式等）一律跳过。 +func fetchRemoteDriveTree(ctx context.Context, spaceID, parentID string, quick bool) (map[string]*remoteFile, error) { + out := make(map[string]*remoteFile) + if err := walkRemoteDir(ctx, spaceID, parentID, "", out, 0); err != nil { + return nil, err + } + _ = quick // hash 与 modified_time 都会被填充，比对模式由 compareTrees 决定 + return out, nil +} + +// walkRemoteDir 遍历 parentID 指向的文件夹，把其中的二进制文件写入 out（key 为 rel_path， +// 同名后者覆盖），并递归进入子文件夹。relBase 是当前文件夹相对遍历起点的路径前缀， +// 用于拼接子项的 rel_path。 +func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out map[string]*remoteFile, depth int) error { + if depth > remoteMaxDepth { + return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth) + } + + nextToken := "" + for { + args := map[string]any{"maxResults": float64(driveListPageSize)} + // space-id 为空则省略，交给 MCP Server 默认「我的文件」。 + if spaceID != "" { + args["spaceId"] = spaceID + } + // 按 parentId（文件夹 dentryUuid）导航；空则由 MCP Server 默认列空间根目录。 + if parentID != "" { + args["parentId"] = parentID + } + if nextToken != "" { + args["nextToken"] = nextToken + } + + text, err := callMCPToolReturnText(ctx, "list_files", args) + if err != nil { + return err + } + + items, token, err := parseDriveList(text) + if err != nil { + return err + } + + for _, it := range items { + name := it.name() + if name == "" { + continue + } + // 远端名称可能含 ..、分隔符或卷标，拼进 rel_path 会逃逸本地根目录： + // 非规范名称直接跳过（同名文件夹也不递归），不纳入索引。 + if !isSafeRemoteSegment(name) { + slog.Warn("overlay: 跳过含非法路径成分的远端条目", "name", name, "relBase", relBase) + continue + } + // rel_path 由文件夹名逐层拼接，统一用 / 分隔，与本地相对路径对齐。 + childRel := name + if relBase != "" { + childRel = relBase + "/" + name + } + + if it.isFolder() { + // 用子文件夹的 dentryUuid 作为下一层 parentId 递归进入。 + if err := walkRemoteDir(ctx, spaceID, it.id(), childRel, out, depth+1); err != nil { + return err + } + continue + } + // 只纳入明确 type=FILE 的条目；在线文档、快捷方式等其它类型一律跳过。 + if !it.isFile() { + continue + } + + modMillis, modValid := it.modifiedMillis() + out[childRel] = &remoteFile{ + RelPath: childRel, + FileID: it.id(), + Hash: it.hash(), + Size: it.size(), + ModifiedTime: modMillis, + ModifiedTimeValid: modValid, + } + } + + // 无下一页，或 token 未推进（防御性，避免服务端异常导致死循环）→ 结束。 + if token == "" || token == nextToken { + break + } + nextToken = token + } + return nil +} + +// driveItem 是 list_files 返回里的一个 dentry 条目。 +// 后端字段命名存在多种历史写法，这里用带 fallback 的访问器做防御式解析。 +type driveItem map[string]any + +func (d driveItem) str(keys ...string) string { + for _, k := range keys { + if s, ok := d[k].(string); ok && s != "" { + return s + } + } + return "" +} + +func (d driveItem) name() string { return d.str("name") } +func (d driveItem) id() string { return d.str("fileId") } +func (d driveItem) typ() string { return d.str("type") } +func (d driveItem) hash() string { return d.str("md5") } +func (d driveItem) path() string { return d.str("path") } + +// size 返回远端文件字节数（fileSize 字段），用于 exact 无 md5 时的降级比对。 +func (d driveItem) size() int64 { + switch v := d["fileSize"].(type) { + case float64: + return int64(v) + case json.Number: + if n, err := v.Int64(); err == nil { + return n + } + } + return 0 +} + +func (d driveItem) isFolder() bool { + return strings.ToUpper(d.typ()) == "FOLDER" +} + +func (d driveItem) isFile() bool { + return strings.ToUpper(d.typ()) == "FILE" +} + +func (d driveItem) modifiedMillis() (int64, bool) { + for _, k := range []string{"modifiedTime", "modifyTime", "modified_time", "gmtModified", "lastModifiedTime", "updateTime"} { + if v, ok := d[k]; ok { + if ms, ok := toMillis(v); ok { + return ms, true + } + } + } + return 0, false +} + +// parseDriveList 解析 list_files 返回文本，抽出 items 列表与 nextToken。 +// 兼容两种 result 形态： +// - {"result":{"items":[...],"nextToken":"..."}} +// - {"result":[...]}（result 直接是条目数组，无分页） +func parseDriveList(text string) ([]driveItem, string, error) { + var envelope struct { + Result json.RawMessage `json:"result"` + } + if err := json.Unmarshal([]byte(text), &envelope); err != nil { + return nil, "", fmt.Errorf("解析 list_files 返回失败: %w", err) + } + if len(envelope.Result) == 0 { + return nil, "", nil // 无 result → 空列表 + } + + toItems := func(ms []map[string]any) []driveItem { + items := make([]driveItem, 0, len(ms)) + for _, m := range ms { + items = append(items, driveItem(m)) + } + return items + } + + // 形态一：result 是对象 {items, nextToken} + var obj struct { + Items []map[string]any `json:"items"` + NextToken string `json:"nextToken"` + } + if err := json.Unmarshal(envelope.Result, &obj); err == nil { + return toItems(obj.Items), obj.NextToken, nil + } + + // 形态二：result 直接是条目数组 + var arr []map[string]any + if err := json.Unmarshal(envelope.Result, &arr); err == nil { + return toItems(arr), "", nil + } + + return nil, "", fmt.Errorf("解析 list_files 返回失败: result 既不是 {items:[]} 也不是数组") +} + +// validateLocalDirAbs 校验 --local-folder 必须是绝对路径，返回其清理后的绝对路径。 +func validateLocalDirAbs(localDir string) (string, error) { + if localDir == "" { + return "", fmt.Errorf("flag --local-folder is required") + } + if !filepath.IsAbs(localDir) { + return "", fmt.Errorf("--local-folder 必须是绝对路径: %s", localDir) + } + return filepath.Clean(localDir), nil +} + +// isSafeRemoteSegment 校验单个远端条目名称是否可安全用作一层相对路径段。 +// 拒绝空串、"."、".."、含卷标（如 Windows 的 "C:"）以及任意平台的路径分隔符 +// （/ 与 \）——这些成分拼进 rel_path 后可能让下载目标逃逸出本地根目录。 +func isSafeRemoteSegment(name string) bool { + if name == "" || name == "." || name == ".." { + return false + } + // 任意平台分隔符都不允许出现在单层名称里。 + if strings.ContainsAny(name, `/\`) { + return false + } + // Windows 卷标（"C:"、"C:foo"）等含盘符的名称一律拒绝。 + if filepath.VolumeName(name) != "" { + return false + } + // Clean 后若发生变化，说明名称非规范（含隐藏的 . / .. / 分隔符）。 + if filepath.Clean(name) != name { + return false + } + return true +} + +// resolveLocalTarget 把远端 rel_path 拼到本地根目录 absDir 下，并确认结果仍位于 +// absDir 内。除词法检查（filepath.Rel）外，还解析已存在路径组件的符号链接，防止 +// root 内的目录软链（如 root/sub -> /outside）把落盘点指到根目录外。逃逸时返回错误。 +func resolveLocalTarget(absDir, rel string) (string, error) { + target := filepath.Join(absDir, filepath.FromSlash(rel)) + back, err := filepath.Rel(absDir, target) + if err != nil || back == ".." || strings.HasPrefix(back, ".."+string(filepath.Separator)) { + return "", fmt.Errorf("远端路径 %q 逃逸出本地根目录", rel) + } + if err := verifyNoSymlinkEscape(absDir, target); err != nil { + return "", err + } + return target, nil +} + +// verifyNoSymlinkEscape 挡住「absDir 之内的目录软链指向外部」的逃逸：从 target 的父 +// 目录向上、在**不越过 absDir 边界**的前提下，找到最深的已存在祖先，解析其真实路径 +// （EvalSymlinks 展开整条软链），确认仍位于 absDir 真实路径之内。 +// +// absDir 尚不存在时直接放行：其下不可能有已存在的组件可供逃逸，后续 MkdirAll 只会 +// 创建真实目录、绝不新建软链——这也是 pull 自动创建目标根目录的正常路径。target 尚不 +// 存在的末段同理无软链可谈，故只需校验 [absDir, target] 之间的现有组件。 +func verifyNoSymlinkEscape(absDir, target string) error { + absDir = filepath.Clean(absDir) + realRoot, err := filepath.EvalSymlinks(absDir) + if err != nil { + // 根目录尚不存在（无软链可解析）→ 放行，交给 MkdirAll 按需创建真实目录。 + return nil + } + + ancestor := filepath.Dir(target) + for { + // 越过 absDir 边界（祖先跑到根目录之上）就停止：根目录之上不属于逃逸判定范围。 + rel, relErr := filepath.Rel(absDir, ancestor) + if relErr != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) { + return nil + } + if _, statErr := os.Lstat(ancestor); statErr == nil { + real, evErr := filepath.EvalSymlinks(ancestor) + if evErr != nil { + return fmt.Errorf("解析路径 %q 失败: %w", ancestor, evErr) + } + back, bErr := filepath.Rel(realRoot, real) + if bErr != nil || back == ".." || strings.HasPrefix(back, ".."+string(filepath.Separator)) { + return fmt.Errorf("路径 %q 经符号链接逃逸出本地根目录", target) + } + return nil + } + parent := filepath.Dir(ancestor) + if parent == ancestor { + return nil + } + ancestor = parent + } +} + +// md5File 计算文件内容的 MD5，并按 base64 编码返回（与钉盘 list_files 返回的 +// md5 字段编码一致，便于直接字符串比较）。 +func md5File(path string) (string, error) { + f, err := os.Open(path) + if err != nil { + return "", err + } + defer f.Close() + + h := md5.New() + if _, err := io.Copy(h, f); err != nil { + return "", err + } + return base64.StdEncoding.EncodeToString(h.Sum(nil)), nil +} + +// walkLocalTree 递归遍历本地目录，只收集常规文件（跳过符号链接、设备文件等）。 +// rel_path 统一使用 / 作为分隔符，相对于 root。 +// +// 这里只记录路径与 mtime，不计算 MD5：本地 hash 采用惰性策略，仅在文件双端 +// 都存在且非 quick 模式时，由 compareTrees 按需计算（见 judgeFileMatch）。 +func walkLocalTree(root string) (map[string]*localFile, error) { + files := make(map[string]*localFile) + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() { + return nil + } + info, err := d.Info() + if err != nil { + return err + } + // 只比对常规文件；符号链接、设备文件等被忽略。 + if !info.Mode().IsRegular() { + return nil + } + rel, err := filepath.Rel(root, path) + if err != nil { + return err + } + relSlash := filepath.ToSlash(rel) + + files[relSlash] = &localFile{ + RelPath: relSlash, + AbsPath: path, + Size: info.Size(), + ModTimeMillis: info.ModTime().UnixMilli(), + } + return nil + }) + if err != nil { + return nil, err + } + return files, nil +} + +// 双端都存在文件的比对结论。 +const ( + matchUnchanged = "unchanged" + matchModified = "modified" + matchUnknown = "unknown" // exact 模式且远端无可靠 md5，内容无法核对 +) + +// judgeFileMatch 判定双端都存在的文件本次的比对结论：unchanged / modified / unknown。 +// +// exact 模式下，本地 MD5 在此处按需计算——只有走到这里的文件才是双端都存在的， +// local-only 文件不会触发 hash 计算。若远端未返回 md5（list_files 目前通常如此）， +// 无法核对内容，则返回 unknown：不判 unchanged（避免把不同内容误报为未变更）， +// 也不硬判 modified（避免把相同内容误报为已变更），让降级如实反映在输出中。 +func judgeFileMatch(lf *localFile, rf *remoteFile, quick bool) (string, error) { + if quick { + // quick：远端时间戳必须可信且与本地 mtime 相等才算 unchanged； + // 远端时间缺失/非法时走保守路径记为 modified。 + if rf.ModifiedTimeValid && lf.ModTimeMillis == rf.ModifiedTime { + return matchUnchanged, nil + } + return matchModified, nil + } + + // exact：远端缺少可靠 md5 时无法核对内容 → unknown（既不判 unchanged 也不判 modified）。 + if rf.Hash == "" { + return matchUnknown, nil + } + + // exact：按需计算本地 MD5（base64），再与远端 md5（钉盘也返回 base64）直接比较。 + if lf.Hash == "" { + h, err := md5File(lf.AbsPath) + if err != nil { + return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", lf.RelPath, err) + } + lf.Hash = h + } + if lf.Hash == rf.Hash { + return matchUnchanged, nil + } + return matchModified, nil +} + +// compareTrees 比较本地与云端文件树，产出五类差异。 +func compareTrees(local map[string]*localFile, remote map[string]*remoteFile, detection string, quick bool) (driveStatusResult, error) { + res := driveStatusResult{ + Detection: detection, + NewLocal: []driveStatusEntry{}, + NewRemote: []driveStatusEntry{}, + Modified: []driveStatusEntry{}, + Unchanged: []driveStatusEntry{}, + Unknown: []driveStatusEntry{}, + } + + for rel, lf := range local { + rf, ok := remote[rel] + if !ok { + res.NewLocal = append(res.NewLocal, driveStatusEntry{RelPath: rel}) + continue + } + verdict, err := judgeFileMatch(lf, rf, quick) + if err != nil { + return res, err + } + switch verdict { + case matchUnchanged: + res.Unchanged = append(res.Unchanged, driveStatusEntry{RelPath: rel}) + case matchUnknown: + res.Unknown = append(res.Unknown, driveStatusEntry{RelPath: rel}) + default: + res.Modified = append(res.Modified, driveStatusEntry{RelPath: rel}) + } + } + for rel := range remote { + if _, ok := local[rel]; !ok { + res.NewRemote = append(res.NewRemote, driveStatusEntry{RelPath: rel}) + } + } + + sortEntries(res.NewLocal) + sortEntries(res.NewRemote) + sortEntries(res.Modified) + sortEntries(res.Unchanged) + sortEntries(res.Unknown) + return res, nil +} + +func sortEntries(entries []driveStatusEntry) { + sort.Slice(entries, func(i, j int) bool { return entries[i].RelPath < entries[j].RelPath }) +} + +func runDriveStatus(cmd *cobra.Command, _ []string) error { + if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil { + return err + } + localDir := mustGetFlag(cmd, "local-folder") + // remote-folder 必传：待比对的云端根文件夹 dentryUuid。 + remoteDirID := mustGetFlag(cmd, "remote-folder") + // space-id 可选：不传则由 fetchRemoteDriveTree 使用「我的文件」对应的空间。 + spaceID := mustGetFlag(cmd, "space-id") + + quick, _ := cmd.Flags().GetBool("quick") + detection := "exact" + if quick { + detection = "quick" + } + + absDir, err := validateLocalDirAbs(localDir) + if err != nil { + return err + } + + local, err := walkLocalTree(absDir) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } + + ctx := cmd.Context() + remoteIndex, err := fetchRemoteDriveTree(ctx, spaceID, remoteDirID, quick) + if err != nil { + return err + } + + result, err := compareTrees(local, remoteIndex, detection, quick) + if err != nil { + return err + } + return deps.Out.PrintJSON(result) +} diff --git a/internal/helpers/drive_status_test.go b/internal/helpers/drive_status_test.go new file mode 100644 index 00000000..8bf5e8d7 --- /dev/null +++ b/internal/helpers/drive_status_test.go @@ -0,0 +1,400 @@ +package helpers + +import ( + "os" + "path/filepath" + "testing" +) + +// ────────────────────────────────────────────────────────── +// validateLocalDirAbs — 本地路径校验（必须为绝对路径） +// ────────────────────────────────────────────────────────── + +func TestValidateLocalDirAbs_empty(t *testing.T) { + if _, err := validateLocalDirAbs(""); err == nil { + t.Fatal("expected error for empty --local-folder") + } +} + +func TestValidateLocalDirAbs_relative(t *testing.T) { + if _, err := validateLocalDirAbs(filepath.Join(".", "repo")); err == nil { + t.Fatal("expected error for relative path") + } +} + +func TestValidateLocalDirAbs_ok(t *testing.T) { + abs := filepath.Join(t.TempDir(), "repo") + got, err := validateLocalDirAbs(abs) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got != filepath.Clean(abs) { + t.Errorf("got %q, want %q", got, filepath.Clean(abs)) + } +} + +// ────────────────────────────────────────────────────────── +// walkLocalTree — 本地遍历 +// ────────────────────────────────────────────────────────── + +func TestWalkLocalTree_collectsRegularFiles(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "a.txt"), "hello") + mustWrite(t, filepath.Join(root, "sub", "b.txt"), "world") + + files, err := walkLocalTree(root) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(files) != 2 { + t.Fatalf("expected 2 files, got %d: %v", len(files), files) + } + // rel_path 用 / 分隔（跨平台一致） + if _, ok := files["sub/b.txt"]; !ok { + t.Errorf("expected key sub/b.txt, got keys %v", keys(files)) + } + // walk 阶段不计算 hash（惰性策略），但记录 AbsPath 与 mtime + if files["a.txt"].Hash != "" { + t.Error("walkLocalTree should not compute MD5 eagerly") + } + if files["a.txt"].AbsPath == "" { + t.Error("walkLocalTree should record AbsPath") + } + if files["a.txt"].ModTimeMillis == 0 { + t.Error("walkLocalTree should record mtime") + } +} + +// ────────────────────────────────────────────────────────── +// compareTrees — 四类差异分类 +// ────────────────────────────────────────────────────────── + +func TestCompareTrees_exact(t *testing.T) { + local := map[string]*localFile{ + "same.txt": {RelPath: "same.txt", Hash: "h1"}, + "diff.txt": {RelPath: "diff.txt", Hash: "local"}, + "onlyme.txt": {RelPath: "onlyme.txt", Hash: "h3"}, + } + remote := map[string]*remoteFile{ + "same.txt": {RelPath: "same.txt", Hash: "h1"}, + "diff.txt": {RelPath: "diff.txt", Hash: "remote"}, + "onlythem.txt": {RelPath: "onlythem.txt", Hash: "h4"}, + } + res, err := compareTrees(local, remote, "exact", false) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + assertPaths(t, "unchanged", res.Unchanged, "same.txt") + assertPaths(t, "modified", res.Modified, "diff.txt") + assertPaths(t, "new_local", res.NewLocal, "onlyme.txt") + assertPaths(t, "new_remote", res.NewRemote, "onlythem.txt") + if res.Detection != "exact" { + t.Errorf("detection = %q, want exact", res.Detection) + } +} + +func TestCompareTrees_exact_unknownRemoteHashIsUnknown(t *testing.T) { + local := map[string]*localFile{"a.txt": {RelPath: "a.txt", Hash: "h1"}} + remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", Hash: ""}} + res, err := compareTrees(local, remote, "exact", false) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + // 远端无 md5 → 无法核对内容，归入 unknown（既非 unchanged 也非 modified）。 + assertPaths(t, "unknown", res.Unknown, "a.txt") + if len(res.Unchanged) != 0 { + t.Error("unknown remote hash must not be judged unchanged") + } + if len(res.Modified) != 0 { + t.Error("unknown remote hash must not be judged modified") + } +} + +// TestCompareTrees_exact_hashesOnlyIntersection 验证本地 hash 只在双端都存在时才 +// 计算：local-only 文件即使 AbsPath 指向不存在的文件也不会触发 hash（不报错）。 +func TestCompareTrees_exact_hashesOnlyIntersection(t *testing.T) { + root := t.TempDir() + bothPath := filepath.Join(root, "both.txt") + mustWrite(t, bothPath, "same-content") + h, err := md5File(bothPath) + if err != nil { + t.Fatalf("md5File: %v", err) + } + + local := map[string]*localFile{ + "both.txt": {RelPath: "both.txt", AbsPath: bothPath}, + "local.txt": {RelPath: "local.txt", AbsPath: filepath.Join(root, "does-not-exist.txt")}, + } + remote := map[string]*remoteFile{ + "both.txt": {RelPath: "both.txt", Hash: h}, + } + res, err := compareTrees(local, remote, "exact", false) + if err != nil { + t.Fatalf("local-only file must not be hashed, got error: %v", err) + } + assertPaths(t, "unchanged", res.Unchanged, "both.txt") + assertPaths(t, "new_local", res.NewLocal, "local.txt") + // 双端都存在的 both.txt 被惰性 hash 后应回填 Hash + if local["both.txt"].Hash == "" { + t.Error("intersection file should have been hashed lazily") + } + if local["local.txt"].Hash != "" { + t.Error("local-only file should never be hashed") + } +} + +// TestCompareTrees_exact_noRemoteMD5AllUnknown 验证 exact 模式在远端无 md5 时 +// 一律归入 unknown——不再用 fileSize + modified_time 近似判 unchanged（否则大小与 +// mtime 恰好相同但内容不同的文件会被误报为未变更），无论大小/时间是否相同。 +func TestCompareTrees_exact_noRemoteMD5AllUnknown(t *testing.T) { + local := map[string]*localFile{ + "sameSizeTime.txt": {RelPath: "sameSizeTime.txt", Size: 100, ModTimeMillis: 1000}, + "diffsize.txt": {RelPath: "diffsize.txt", Size: 100, ModTimeMillis: 1000}, + "difftime.txt": {RelPath: "difftime.txt", Size: 100, ModTimeMillis: 1000}, + } + remote := map[string]*remoteFile{ + // 远端均无 md5（Hash 空）→ 全部 unknown，绝不判 unchanged。 + "sameSizeTime.txt": {RelPath: "sameSizeTime.txt", Size: 100, ModifiedTime: 1000, ModifiedTimeValid: true}, + "diffsize.txt": {RelPath: "diffsize.txt", Size: 200, ModifiedTime: 1000, ModifiedTimeValid: true}, + "difftime.txt": {RelPath: "difftime.txt", Size: 100, ModifiedTime: 2000, ModifiedTimeValid: true}, + } + res, err := compareTrees(local, remote, "exact", false) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + assertPaths(t, "unknown", res.Unknown, "diffsize.txt", "difftime.txt", "sameSizeTime.txt") + if len(res.Unchanged) != 0 { + t.Errorf("远端无 md5 时不应有 unchanged, got %v", entryPaths(res.Unchanged)) + } + if len(res.Modified) != 0 { + t.Errorf("远端无 md5 时不应有 modified, got %v", entryPaths(res.Modified)) + } +} + +// TestCompareTrees_exact_base64RemoteMD5 验证 exact 用 base64 md5 比对：本地按 +// base64 算 md5，与钉盘返回的 base64 md5 直接相等 → unchanged。 +func TestCompareTrees_exact_base64RemoteMD5(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "a.txt") + mustWrite(t, p, "hello root\n") // 11 字节，md5 base64 = 6y9K7B0b2K0AInNZZV/70A== + remoteB64 := "6y9K7B0b2K0AInNZZV/70A==" + local := map[string]*localFile{"a.txt": {RelPath: "a.txt", AbsPath: p}} + remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", Hash: remoteB64}} + res, err := compareTrees(local, remote, "exact", false) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + assertPaths(t, "unchanged", res.Unchanged, "a.txt") + if len(res.Modified) != 0 { + t.Errorf("同一 md5(base64) 不应判 modified, got modified=%d", len(res.Modified)) + } + // 本地按需 hash 后应回填为 base64 + if local["a.txt"].Hash != remoteB64 { + t.Errorf("本地 md5 应回填为 base64 %q, got %q", remoteB64, local["a.txt"].Hash) + } +} + +func TestCompareTrees_quick(t *testing.T) { + local := map[string]*localFile{ + "eq.txt": {RelPath: "eq.txt", ModTimeMillis: 1000}, + "ne.txt": {RelPath: "ne.txt", ModTimeMillis: 1000}, + "bad.txt": {RelPath: "bad.txt", ModTimeMillis: 1000}, + } + remote := map[string]*remoteFile{ + "eq.txt": {RelPath: "eq.txt", ModifiedTime: 1000, ModifiedTimeValid: true}, + "ne.txt": {RelPath: "ne.txt", ModifiedTime: 2000, ModifiedTimeValid: true}, + "bad.txt": {RelPath: "bad.txt", ModifiedTime: 1000, ModifiedTimeValid: false}, + } + res, err := compareTrees(local, remote, "quick", true) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + assertPaths(t, "unchanged", res.Unchanged, "eq.txt") + // ne.txt 时间不等、bad.txt 远端时间不可信 → 都记为 modified + assertPaths(t, "modified", res.Modified, "bad.txt", "ne.txt") +} + +func TestCompareTrees_emptyRemote_allNewLocal(t *testing.T) { + local := map[string]*localFile{ + "a.txt": {RelPath: "a.txt", Hash: "h1"}, + "b.txt": {RelPath: "b.txt", Hash: "h2"}, + } + res, err := compareTrees(local, map[string]*remoteFile{}, "exact", false) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + assertPaths(t, "new_local", res.NewLocal, "a.txt", "b.txt") + if len(res.NewRemote) != 0 || len(res.Modified) != 0 || len(res.Unchanged) != 0 { + t.Error("with empty remote, only new_local should be populated") + } +} + +// ────────────────────────────────────────────────────────── +// helpers +// ────────────────────────────────────────────────────────── + +func mustWrite(t *testing.T, path, content string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatalf("mkdir: %v", err) + } + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatalf("write %s: %v", path, err) + } +} + +func keys(m map[string]*localFile) []string { + out := make([]string, 0, len(m)) + for k := range m { + out = append(out, k) + } + return out +} + +func assertPaths(t *testing.T, label string, entries []driveStatusEntry, want ...string) { + t.Helper() + if len(entries) != len(want) { + t.Fatalf("%s: got %d entries %v, want %v", label, len(entries), entryPaths(entries), want) + } + for i, w := range want { + if entries[i].RelPath != w { + t.Errorf("%s[%d] = %q, want %q", label, i, entries[i].RelPath, w) + } + } +} + +func entryPaths(entries []driveStatusEntry) []string { + out := make([]string, len(entries)) + for i, e := range entries { + out[i] = e.RelPath + } + return out +} + +// ────────────────────────────────────────────────────────── +// parseDriveList — list_files 返回解析 +// ────────────────────────────────────────────────────────── + +func TestParseDriveList_resultItems(t *testing.T) { + text := `{"result":{"items":[{"name":"a.txt","type":"file"},{"name":"sub","type":"folder"}],"nextToken":"tok"}}` + items, token, err := parseDriveList(text) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(items) != 2 { + t.Fatalf("expected 2 items, got %d", len(items)) + } + if token != "tok" { + t.Errorf("token = %q, want tok", token) + } +} + +func TestParseDriveList_topLevelArray(t *testing.T) { + text := `{"result":[{"name":"a.txt","type":"file"}]}` + items, token, err := parseDriveList(text) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(items) != 1 || items[0].name() != "a.txt" { + t.Errorf("unexpected items: %v", items) + } + if token != "" { + t.Errorf("expected empty token, got %q", token) + } +} + +func TestParseDriveList_invalid(t *testing.T) { + if _, _, err := parseDriveList("not json"); err == nil { + t.Fatal("expected error for invalid JSON") + } +} + +// ────────────────────────────────────────────────────────── +// driveItem — 字段访问器（带 fallback） +// ────────────────────────────────────────────────────────── + +func TestDriveItem_accessors(t *testing.T) { + it := driveItem{ + "name": "报告.pdf", + "type": "file", + "fileId": "d-123", + "md5": "abc", + "path": "/dir/报告.pdf", + "modifyTime": float64(1700000000000), + } + if it.name() != "报告.pdf" { + t.Errorf("name() = %q", it.name()) + } + if it.id() != "d-123" { + t.Errorf("id() = %q", it.id()) + } + if it.typ() != "file" { + t.Errorf("typ() = %q, want file", it.typ()) + } + if it.hash() != "abc" { + t.Errorf("hash() = %q", it.hash()) + } + if it.path() != "/dir/报告.pdf" { + t.Errorf("path() = %q", it.path()) + } + if it.isFolder() { + t.Error("type=file should not be a folder") + } + if !it.isFile() { + t.Error("type=file should be a file") + } + ms, ok := it.modifiedMillis() + if !ok || ms != 1700000000000 { + t.Errorf("modifiedMillis() = %d,%v", ms, ok) + } +} + +func TestDriveItem_folderAndFile(t *testing.T) { + folder := driveItem{"name": "sub", "type": "folder"} + if !folder.isFolder() || folder.isFile() { + t.Error("type=folder should be folder, not file") + } + file := driveItem{"name": "a.txt", "type": "file"} + if !file.isFile() || file.isFolder() { + t.Error("type=file should be file, not folder") + } + // 非 file / 非 folder 的类型（在线文档、快捷方式等）都不纳入比对。 + doc := driveItem{"name": "设计稿", "type": "docx"} + if doc.isFile() { + t.Error("docx should not be treated as file") + } + shortcut := driveItem{"name": "快捷方式", "type": "shortcut"} + if shortcut.isFile() { + t.Error("shortcut should not be treated as file") + } +} + +// ────────────────────────────────────────────────────────── +// toMillis — 时间字段归一化 +// ────────────────────────────────────────────────────────── + +func TestToMillis(t *testing.T) { + cases := []struct { + name string + in any + want int64 + ok bool + }{ + {"epoch-ms-number", float64(1700000000000), 1700000000000, true}, + {"epoch-ms-string", "1700000000000", 1700000000000, true}, + {"rfc3339", "2023-11-14T22:13:20Z", 1700000000000, true}, + {"zero", float64(0), 0, false}, + {"empty", "", 0, false}, + {"garbage", "not-a-time", 0, false}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + got, ok := toMillis(c.in) + if ok != c.ok || (ok && got != c.want) { + t.Errorf("toMillis(%v) = %d,%v; want %d,%v", c.in, got, ok, c.want, c.ok) + } + }) + } +} diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go new file mode 100644 index 00000000..e86ad9a6 --- /dev/null +++ b/internal/helpers/drive_sync.go @@ -0,0 +1,542 @@ +package helpers + +import ( + "bufio" + "context" + "errors" + "fmt" + "io" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/spf13/cobra" +) + +// ========================================================== +// drive sync — 本地与钉盘双向同步（本地 ⇄ Drive） +// ========================================================== +// ────────────────────────────────────────────────────────── +// dws drive sync — 把 --local-folder 与 --remote-folder 做文件级双向同步。 +// +// 复用 status 的差异判定（exact MD5 / --quick modified_time）先算出 diff，再按方向执行： +// new_local 仅本地存在 → push（缺失的远端目录按需创建，再上传） +// new_remote 仅钉盘存在 → pull（下载到本地对应路径） +// modified 两侧都变更 → 按 --on-conflict 解决： +// remote-wins 默认：拉取远端覆盖本地 +// local-wins ：上传本地覆盖远端 +// keep-both ：本地改名保留，再拉取远端到原路径 +// ask ：交互式逐个询问 +// unknown exact 模式远端无可靠 md5、内容无法核对 → 跳过（记 skipped，提示改用 --quick） +// unchanged 两侧一致 → 不动 +// +// 文件级同步——只新增/覆盖，不删除任何一侧的多余文件。summary.failed > 0 时以非零 +// 退出码退出，结构化 summary + diff + items 仍打印在 stdout 上。 +// ────────────────────────────────────────────────────────── + +// --on-conflict 的四种冲突解决策略。 +const ( + syncConflictLocalWins = "local-wins" // 上传本地覆盖远端 + syncConflictRemoteWins = "remote-wins" // 默认：拉取远端覆盖本地 + syncConflictKeepBoth = "keep-both" // 本地改名保留，再拉取远端到原路径 + syncConflictAsk = "ask" // 交互式逐个询问 +) + +// sync 动作分类（direction 标注每条记录属于哪个方向）。 +const ( + syncDirectionPull = "pull" + syncDirectionPush = "push" + syncDirectionConflict = "conflict" + + syncActionDownloaded = "downloaded" + syncActionUploaded = "uploaded" + syncActionOverwritten = "overwritten" + syncActionFolderCreated = "folder_created" + syncActionRenamedLocal = "renamed_local" + syncActionSkipped = "skipped" + syncActionFailed = "failed" +) + +// driveSyncItem 是输出 items[] 中每条操作的明细。 +type driveSyncItem struct { + RelPath string `json:"rel_path"` + Action string `json:"action"` + Direction string `json:"direction,omitempty"` + Error string `json:"error,omitempty"` +} + +// driveSyncSummary 是各方向的计数汇总。 +type driveSyncSummary struct { + Pulled int `json:"pulled"` + Pushed int `json:"pushed"` + Skipped int `json:"skipped"` + Failed int `json:"failed"` +} + +// driveSyncDiff 是本次同步前算出的五类差异（与 status 同源）。 +type driveSyncDiff struct { + NewLocal []driveStatusEntry `json:"new_local"` + NewRemote []driveStatusEntry `json:"new_remote"` + Modified []driveStatusEntry `json:"modified"` + Unchanged []driveStatusEntry `json:"unchanged"` + Unknown []driveStatusEntry `json:"unknown"` +} + +// driveSyncResult 是 sync 命令的输出 schema。 +type driveSyncResult struct { + Detection string `json:"detection"` + Diff driveSyncDiff `json:"diff"` + Summary driveSyncSummary `json:"summary"` + Items []driveSyncItem `json:"items"` +} + +// driveSyncFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout， +// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明（与 drivePushFailure 一致）。 +type driveSyncFailure struct{ failed int } + +func (e *driveSyncFailure) Error() string { + return fmt.Sprintf("drive sync: %d item(s) failed", e.failed) +} +func (e *driveSyncFailure) RawStderr() string { return e.Error() } +func (e *driveSyncFailure) ExitCode() int { return 1 } + +func runDriveSync(cmd *cobra.Command, _ []string) error { + if err := validateRequiredFlags(cmd, "local-folder", "remote-folder"); err != nil { + return err + } + localDir := mustGetFlag(cmd, "local-folder") + remoteDirID := mustGetFlag(cmd, "remote-folder") + // space-id 可选：不传则由底层使用「我的文件」对应的空间。 + spaceID := mustGetFlag(cmd, "space-id") + + onConflict, _ := cmd.Flags().GetString("on-conflict") + if onConflict == "" { + onConflict = syncConflictRemoteWins + } + switch onConflict { + case syncConflictLocalWins, syncConflictRemoteWins, syncConflictKeepBoth, syncConflictAsk: + default: + return fmt.Errorf("--on-conflict 取值非法: %s（可选 local-wins|remote-wins|keep-both|ask）", onConflict) + } + + quick, _ := cmd.Flags().GetBool("quick") + detection := "exact" + if quick { + detection = "quick" + } + + absDir, err := validateLocalDirAbs(localDir) + if err != nil { + return err + } + + ctx := cmd.Context() + + // 远端现状：文件（含 hash/mtime/fileId）与目录（rel_path → fileId，"" 即根本身）。 + remoteFiles, remoteFolders, err := fetchRemoteTreeForPush(ctx, spaceID, remoteDirID) + if err != nil { + return err + } + // 本地现状：子目录（含空目录，父目录先于子目录）与常规文件。 + localDirs, localFiles, err := walkLocalForPush(absDir) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } + localByRel := make(map[string]localPushFile, len(localFiles)) + for _, f := range localFiles { + localByRel[f.RelPath] = f + } + + // 计算 diff：双端都存在的文件复用 judgeFileMatch，保持与 status 完全一致的判定。 + diff := driveSyncDiff{ + NewLocal: []driveStatusEntry{}, + NewRemote: []driveStatusEntry{}, + Modified: []driveStatusEntry{}, + Unchanged: []driveStatusEntry{}, + Unknown: []driveStatusEntry{}, + } + var newLocal, newRemote, modified, unknown []string + for rel, pf := range localByRel { + rf, ok := remoteFiles[rel] + if !ok { + newLocal = append(newLocal, rel) + continue + } + lf := &localFile{RelPath: pf.RelPath, AbsPath: pf.AbsPath, Size: pf.Size, ModTimeMillis: pf.ModTimeMillis} + verdict, jerr := judgeFileMatch(lf, rf, quick) + if jerr != nil { + return jerr + } + switch verdict { + case matchUnchanged: + diff.Unchanged = append(diff.Unchanged, driveStatusEntry{RelPath: rel}) + case matchUnknown: + unknown = append(unknown, rel) + default: + modified = append(modified, rel) + } + } + for rel := range remoteFiles { + if _, ok := localByRel[rel]; !ok { + newRemote = append(newRemote, rel) + } + } + sort.Strings(newLocal) + sort.Strings(newRemote) + sort.Strings(modified) + sort.Strings(unknown) + for _, rel := range newLocal { + diff.NewLocal = append(diff.NewLocal, driveStatusEntry{RelPath: rel}) + } + for _, rel := range newRemote { + diff.NewRemote = append(diff.NewRemote, driveStatusEntry{RelPath: rel}) + } + for _, rel := range modified { + diff.Modified = append(diff.Modified, driveStatusEntry{RelPath: rel}) + } + for _, rel := range unknown { + diff.Unknown = append(diff.Unknown, driveStatusEntry{RelPath: rel}) + } + sortEntries(diff.Unchanged) + + res := driveSyncResult{Detection: detection, Diff: diff, Items: []driveSyncItem{}} + + // --dry-run：只算差异、不执行任何同步动作。 + if deps.Caller.DryRun() { + deps.Out.PrintInfo("dry-run: 仅计算差异，未执行任何同步操作") + return deps.Out.PrintJSON(res) + } + + // unknown：exact 模式下远端无可靠 md5、内容无法核对，不擅自覆盖任何一侧，记 skipped。 + for _, rel := range unknown { + res.Summary.Skipped++ + res.Items = append(res.Items, driveSyncItem{ + RelPath: rel, Action: syncActionSkipped, Direction: syncDirectionConflict, + Error: "远端无可靠 md5，内容无法核对，已跳过（可改用 --quick 按 modified_time 比对）", + }) + } + + // ask 模式：先把所有 modified 的解决策略问全，再统一执行，避免边执行边交互。 + resolutions := make(map[string]string, len(modified)) + for _, rel := range modified { + strategy := onConflict + if strategy == syncConflictAsk { + strategy, err = driveSyncAskConflict(rel) + if err != nil { + return err + } + } + resolutions[rel] = strategy + } + + // 落盘前先确保本地根存在（供大小写探测与 pull 落盘），并探测目标文件系统大小写敏感性。 + if err := os.MkdirAll(absDir, 0o755); err != nil { + return fmt.Errorf("创建本地目录失败: %w", err) + } + caseInsensitive := isCaseInsensitiveFS(absDir) + + // 远端 → 本地的大小写/规范化冲突：多个远端条目在当前文件系统上映射到同一本地路径时， + // 命中的路径一律标记 failed、都不落盘，避免静默覆盖丢文件（与 pull 同策略）。 + remoteRels := make([]string, 0, len(remoteFiles)) + for rel := range remoteFiles { + remoteRels = append(remoteRels, rel) + } + collided := detectTargetCollisions(absDir, remoteRels, caseInsensitive) + + // occupied：keep-both 生成不冲突的本地重命名目标时用，覆盖两侧全部已知路径。 + occupied := make(map[string]bool) + for rel := range localByRel { + occupied[rel] = true + } + for _, d := range localDirs { + occupied[d] = true + } + for rel := range remoteFiles { + occupied[rel] = true + } + for rel := range remoteFolders { + if rel != "" { + occupied[rel] = true + } + } + + // 阶段 1：镜像本地目录结构到远端（缺失则创建），保证空目录与 push 目标的父目录先存在。 + for _, dir := range localDirs { + if _, ok := remoteFolders[dir]; ok { + continue // 远端已存在，复用 fileId + } + parentRel, name := splitRel(dir) + parentID, ok := remoteFolders[parentRel] + if !ok || parentID == "" { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"}) + continue + } + fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name) + if cerr != nil || fid == "" { + res.Summary.Failed++ + msg := "create_folder 未返回 fileId" + if cerr != nil { + msg = cerr.Error() + } + res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFailed, Direction: syncDirectionPush, Error: msg}) + continue + } + remoteFolders[dir] = fid + res.Summary.Pushed++ + res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFolderCreated, Direction: syncDirectionPush}) + } + + // 阶段 2：new_remote 下载到本地。 + for _, rel := range newRemote { + syncPullFile(&res, ctx, spaceID, remoteFiles[rel], absDir, rel, collided, syncDirectionPull) + } + + // 阶段 3：new_local 上传到远端。 + for _, rel := range newLocal { + pf := localByRel[rel] + syncPushFile(&res, ctx, spaceID, remoteFolders, pf, rel, "") + } + + // 阶段 4：modified 按 --on-conflict 解决。 + for _, rel := range modified { + pf := localByRel[rel] + rf := remoteFiles[rel] + switch resolutions[rel] { + case syncConflictRemoteWins: + syncPullFile(&res, ctx, spaceID, rf, absDir, rel, collided, syncDirectionPull) + case syncConflictLocalWins: + syncPushFile(&res, ctx, spaceID, remoteFolders, pf, rel, rf.FileID) + case syncConflictKeepBoth: + syncKeepBoth(&res, ctx, spaceID, rf, absDir, rel, collided, occupied) + default: // "" — ask 选择跳过 + res.Summary.Skipped++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionSkipped, Direction: syncDirectionConflict}) + } + } + + // 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。 + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr + } + if res.Summary.Failed > 0 { + return &driveSyncFailure{failed: res.Summary.Failed} + } + return nil +} + +// syncPullFile 下载单个远端文件到本地 rel 对应路径（总是覆盖，Drive 为该项权威源）， +// 并把结果计入 res。命中大小写/规范化冲突或逃逸的路径记 failed、不落盘。 +func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, collided map[string]bool, direction string) { + if collided[rel] { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{ + RelPath: rel, Action: syncActionFailed, Direction: direction, + Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", + }) + return + } + localPath, terr := resolveLocalTarget(absDir, rel) + if terr != nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction, Error: terr.Error()}) + return + } + action, perr := pullOneFile(ctx, spaceID, rf, localPath, ifExistsOverwrite) + if action == pullActionDownloaded { + res.Summary.Pulled++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionDownloaded, Direction: direction}) + return + } + res.Summary.Failed++ + item := driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction} + if perr != nil { + item.Error = perr.Error() + } + res.Items = append(res.Items, item) +} + +// syncPushFile 上传单个本地文件到远端；overwriteID 非空时走覆盖上传（原地覆盖同名远端文件）。 +func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, remoteFolders map[string]string, pf localPushFile, rel, overwriteID string) { + parentRel, name := splitRel(rel) + parentID, ok := remoteFolders[parentRel] + if !ok || parentID == "" { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"}) + return + } + if err := pushUploadFile(ctx, spaceID, parentID, overwriteID, name, pf.AbsPath, pf.Size); err != nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: err.Error()}) + return + } + res.Summary.Pushed++ + action := syncActionUploaded + direction := syncDirectionPush + if overwriteID != "" { + action = syncActionOverwritten + direction = syncDirectionConflict + } + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: action, Direction: direction}) +} + +// syncKeepBoth 解决 modified 冲突的 keep-both 策略：先把本地文件改名保留（追加基于 +// 远端 fileId 的不冲突后缀），再把远端文件拉取到原 rel 路径。拉取失败则回滚改名。 +func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, collided, occupied map[string]bool) { + if collided[rel] { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{ + RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, + Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", + }) + return + } + oldAbs, e1 := resolveLocalTarget(absDir, rel) + if e1 != nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e1.Error()}) + return + } + // 以「不覆盖」语义原子占用一个本地重命名目标。occupied 的精确字符串查重覆盖不到 + // 大小写/NFC 等价的既有文件；用 O_CREATE|O_EXCL 让 OS 兜底判等价性，命中则换下一个 + // 后缀，杜绝 os.Rename 静默覆盖等价既有文件导致的数据丢失。 + suffixedRel, newAbs, e2 := reserveSyncKeepBothTarget(absDir, rel, rf.FileID, occupied) + if e2 != nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e2.Error()}) + return + } + // newAbs 此刻是我们刚用 O_EXCL 新建的空占位文件，覆盖它不会丢用户数据；且已确保它 + // 不与任何等价既有文件冲突。 + if err := os.Rename(oldAbs, newAbs); err != nil { + _ = os.Remove(newAbs) // 清理空占位，避免残留 + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: fmt.Sprintf("本地改名保留失败: %v", err)}) + return + } + occupied[suffixedRel] = true + + action, perr := pullOneFile(ctx, spaceID, rf, oldAbs, ifExistsOverwrite) + if action != pullActionDownloaded { + // 拉取失败：回滚改名，把本地文件恢复回原名。pullOneFile 是原子的（下载写临时文件、 + // 成功才 rename，失败时绝不触碰 oldAbs），故此处 oldAbs 必不存在，rename 可直接复原、 + // 无需像参考实现那样先清残留。回滚本身失败时如实上报——本地版本仍以改名后的名字保留、 + // 未丢数据，但需让用户知道文件名已变。 + res.Summary.Failed++ + msg := "" + if perr != nil { + msg = perr.Error() + } + if rbErr := os.Rename(newAbs, oldAbs); rbErr != nil { + if msg != "" { + msg += "; " + } + msg += fmt.Sprintf("回滚改名失败，本地版本保留为 %s: %v", suffixedRel, rbErr) + } + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: msg}) + return + } + res.Summary.Pulled++ + res.Items = append(res.Items, + driveSyncItem{RelPath: suffixedRel, Action: syncActionRenamedLocal, Direction: syncDirectionConflict}, + driveSyncItem{RelPath: rel, Action: syncActionDownloaded, Direction: syncDirectionPull}, + ) +} + +// syncKeepBothCandidate 生成 keep-both 的第 n 个候选相对路径（n=0 为首选）：在扩展名前 +// 插入基于远端 fileId 末段的后缀（缺失时用 conflict），n>0 再追加序号消歧。 +func syncKeepBothCandidate(rel, fileID string, n int) string { + suffix := "conflict" + if fileID != "" { + s := fileID + if len(s) > 8 { + s = s[len(s)-8:] + } + suffix = "conflict-" + s + } + dir, base := splitRel(rel) + ext := filepath.Ext(base) // base 无路径分隔符，取末尾扩展名安全 + stem := strings.TrimSuffix(base, ext) + name := stem + "." + suffix + ext + if n > 0 { + name = fmt.Sprintf("%s.%s.%d%s", stem, suffix, n, ext) + } + if dir == "" { + return name + } + return dir + "/" + name +} + +// driveSyncSuffixedRel 返回首个不在 occupied（纯字符串查重）中的候选。仅用于快速路径与 +// 单元测试；keep-both 实际执行走 reserveSyncKeepBothTarget，以 OS 兜底等价性。 +func driveSyncSuffixedRel(rel, fileID string, occupied map[string]bool) string { + for n := 0; ; n++ { + if cand := syncKeepBothCandidate(rel, fileID, n); !occupied[cand] { + return cand + } + } +} + +// reserveSyncKeepBothTarget 生成并以「不覆盖」语义原子占用一个 keep-both 本地目标。 +// 逐个候选用 O_CREATE|O_EXCL 尝试创建：成功即占住该名，返回其相对路径与绝对路径（调用方 +// 随后可安全 os.Rename 覆盖这个空占位）；EEXIST（含大小写/NFC 等价的既有文件，由 OS 判定） +// 则记入 occupied 并试下一个后缀，绝不覆盖任何既有文件。 +func reserveSyncKeepBothTarget(absDir, rel, fileID string, occupied map[string]bool) (string, string, error) { + for n := 0; ; n++ { + cand := syncKeepBothCandidate(rel, fileID, n) + if occupied[cand] { + continue // 本次运行内已知占用，快速跳过 + } + abs, err := resolveLocalTarget(absDir, cand) + if err != nil { + return "", "", err // 逃逸/符号链接等，直接失败 + } + f, oerr := os.OpenFile(abs, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644) + if oerr == nil { + _ = f.Close() + return cand, abs, nil + } + if os.IsExist(oerr) { + occupied[cand] = true // 等价目标已存在，记下避免重试，换下一个后缀 + continue + } + return "", "", oerr + } +} + +// syncAskStdin 是 --on-conflict=ask 交互提问的输入源，默认 os.Stdin；测试可替换它以 +// 注入非交互（EOF）场景。 +var syncAskStdin io.Reader = os.Stdin + +// driveSyncAskConflict 在 --on-conflict=ask 下交互式询问单个冲突文件的解决策略。 +// 返回四种具体策略之一，或 ""（跳过）。当 stdin 在给出选择前结束（管道/无 TTY 等非交互 +// 环境）时，按文档约定等价于「跳过」，返回 ""——绝不因此中止整个同步，new_local/new_remote +// 等其余差异仍会照常处理。 +func driveSyncAskConflict(rel string) (string, error) { + fmt.Fprintf(os.Stderr, "冲突: 本地与远端都修改了 %q。请选择 [R]远端优先 / [L]本地优先 / [K]保留两者 / [S]跳过 (默认 R): ", rel) + line, err := bufio.NewReader(syncAskStdin).ReadString('\n') + if err != nil && !errors.Is(err, io.EOF) { + return "", fmt.Errorf("读取冲突选择失败 (%s): %w", rel, err) + } + switch strings.TrimSpace(strings.ToLower(line)) { + case "r", "remote", "remote-wins": + return syncConflictRemoteWins, nil + case "l", "local", "local-wins": + return syncConflictLocalWins, nil + case "k", "keep", "keep-both": + return syncConflictKeepBoth, nil + case "s", "skip": + return "", nil + case "": + if errors.Is(err, io.EOF) { + // 非交互（管道/无 TTY）：stdin 在给出选择前结束。按文档约定等价于跳过， + // 返回 "" 而非报错——否则单个冲突会让 runDriveSync 直接中止，连 + // new_local/new_remote 都不再处理。 + return "", nil + } + return syncConflictRemoteWins, nil // 交互式回车 → 默认远端优先 + default: + return "", fmt.Errorf("无效的冲突选择: %q（可选 remote/local/keep/skip）", strings.TrimSpace(line)) + } +} diff --git a/internal/helpers/drive_sync_test.go b/internal/helpers/drive_sync_test.go new file mode 100644 index 00000000..fed0a21b --- /dev/null +++ b/internal/helpers/drive_sync_test.go @@ -0,0 +1,417 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "strconv" + "strings" + "testing" + + "github.com/spf13/cobra" +) + +// errTestDownload 用于模拟 httpGetFile 下载失败。 +var errTestDownload = errors.New("simulated download failure") + +// ────────────────────────────────────────────────────────── +// driveSyncFailure — sync 部分失败错误：exit=1 +// ────────────────────────────────────────────────────────── + +func TestDriveSyncFailure(t *testing.T) { + e := &driveSyncFailure{failed: 2} + if e.ExitCode() != 1 { + t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) + } + if e.Error() != e.RawStderr() { + t.Error("Error() 与 RawStderr() 应一致") + } + if !strings.Contains(e.Error(), "2") { + t.Errorf("Error() 应包含失败数, got %q", e.Error()) + } +} + +// ────────────────────────────────────────────────────────── +// driveSyncSuffixedRel — keep-both 本地重命名目标生成 +// ────────────────────────────────────────────────────────── + +func TestDriveSyncSuffixedRel(t *testing.T) { + // 基本：扩展名前插入基于 fileId 末 8 位的后缀。 + got := driveSyncSuffixedRel("a/b.txt", "0123456789ABCDEF", map[string]bool{}) + if want := "a/b.conflict-89ABCDEF.txt"; got != want { + t.Errorf("suffixed = %q, want %q", got, want) + } + + // 根目录下、无扩展名。 + if got := driveSyncSuffixedRel("readme", "", map[string]bool{}); got != "readme.conflict" { + t.Errorf("suffixed = %q, want readme.conflict", got) + } + + // 首选目标已被占用时追加序号，直到不冲突。 + occupied := map[string]bool{ + "x.conflict-FID.log": true, + "x.conflict-FID.0.log": true, + } + got = driveSyncSuffixedRel("x.log", "FID", occupied) + if want := "x.conflict-FID.1.log"; got != want { + t.Errorf("suffixed with collisions = %q, want %q", got, want) + } +} + +// ────────────────────────────────────────────────────────── +// sync 双向流程 — new_local 上传 / new_remote 下载 +// ────────────────────────────────────────────────────────── + +// runDriveSyncTest 用 mock caller 执行 `drive sync`，注入 httpPutFile / httpGetFile 为 +// 可控 no-op，避免真实 OSS 传输。返回 root.Execute() 的结果。 +func runDriveSyncTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error { + // 默认下载：把远端内容写到目标路径，模拟成功落盘。 + return runDriveSyncTestWithGet(t, caller, func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("remote-content"), 0o644) + }, localDir, args...) +} + +// runDriveSyncTestWithGet 同上，但允许自定义 httpGetFile 行为（例如模拟下载失败）。 +func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn func(context.Context, string, map[string]string, string) error, localDir string, args ...string) error { + t.Helper() + + prevDeps := deps + prevOSArgs := os.Args + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) + SetHTTPGetFile(getFn) + + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + + full := append([]string{"sync", "--local-folder", localDir, "--remote-folder", "ROOT"}, args...) + os.Args = append([]string{"dws", "drive"}, full...) + root.SetArgs(append([]string{"drive"}, full...)) + + t.Cleanup(func() { + deps = prevDeps + os.Args = prevOSArgs + SetHTTPPutFile(nil) + SetHTTPGetFile(nil) + }) + + return root.Execute() +} + +// 双向：本地独有 local.txt 应上传；远端独有 remote.txt 应下载到本地。 +func TestDriveSync_bidirectional(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "local-only") + + caller := &driveSyncMockCaller{ + // 远端仅有 remote.txt（本地不存在）→ new_remote，应被下载。 + listJSON: `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R_FID","md5":"z","modifyTime":2000}],"nextToken":""}}`, + } + if err := runDriveSyncTest(t, caller, dir); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // new_local：local.txt 走 get_upload_info（新建上传，传 parentId=ROOT、不传 overwriteFileId）。 + up := caller.callsFor("get_upload_info") + if len(up) != 1 { + t.Fatalf("expected 1 get_upload_info call, got %d", len(up)) + } + if got := up[0].args["parentId"]; got != "ROOT" { + t.Errorf("get_upload_info parentId = %v, want ROOT", got) + } + if _, ok := up[0].args["overwriteFileId"]; ok { + t.Error("新建上传不应传 overwriteFileId") + } + + // new_remote：remote.txt 走 download_file，并已落盘到本地。 + dl := caller.callsFor("download_file") + if len(dl) != 1 || dl[0].args["fileId"] != "R_FID" { + t.Fatalf("expected 1 download_file(fileId=R_FID), got %v", dl) + } + if _, err := os.Stat(filepath.Join(dir, "remote.txt")); err != nil { + t.Errorf("remote.txt 应被下载到本地: %v", err) + } +} + +// modified + remote-wins：quick 模式下两侧 mtime 不同判为 modified，默认拉取远端覆盖本地。 +func TestDriveSync_modifiedRemoteWins(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-old") + // 本地 mtime 设为与远端不同，quick 模式判为 modified。 + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + } + if err := runDriveSyncTest(t, caller, dir, "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // remote-wins → 下载覆盖本地，且不应发生上传。 + if dl := caller.callsFor("download_file"); len(dl) != 1 || dl[0].args["fileId"] != "F_FID" { + t.Errorf("expected download_file(fileId=F_FID), got %v", dl) + } + if up := caller.callsFor("get_upload_info"); len(up) != 0 { + t.Errorf("remote-wins 不应上传, got %d get_upload_info calls", len(up)) + } + if b, _ := os.ReadFile(p); string(b) != "remote-content" { + t.Errorf("本地文件应被远端内容覆盖, got %q", string(b)) + } +} + +// modified + local-wins：改用 local-wins 时应覆盖上传远端（传 overwriteFileId、不传 parentId）。 +func TestDriveSync_modifiedLocalWins(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-new") + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + } + if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "local-wins"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + up := caller.callsFor("get_upload_info") + if len(up) != 1 { + t.Fatalf("expected 1 get_upload_info call, got %d", len(up)) + } + if got := up[0].args["overwriteFileId"]; got != "F_FID" { + t.Errorf("local-wins 覆盖上传 overwriteFileId = %v, want F_FID", got) + } + if _, ok := up[0].args["parentId"]; ok { + t.Error("覆盖上传不应传 parentId") + } + if dl := caller.callsFor("download_file"); len(dl) != 0 { + t.Errorf("local-wins 不应下载, got %d download_file calls", len(dl)) + } +} + +// --dry-run：只计算差异，不触发任何 MCP 写操作与本地落盘。 +func TestDriveSync_dryRun(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "x") + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R_FID","modifyTime":2000}],"nextToken":""}}`, + dryRun: true, + } + if err := runDriveSyncTest(t, caller, dir); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 { + t.Errorf("dry-run 不应触发下载/上传, got %d 次写操作调用", got) + } + if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) { + t.Error("dry-run 不应把远端文件落盘到本地") + } +} + +// remote-wins 下载失败：本地原文件必须原样保留（pullOneFile 先写临时文件、成功才原子 +// rename 覆盖），且命令以非零退出码退出。 +func TestDriveSync_pullFailureKeepsLocal(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-original") + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + } + failGet := func(context.Context, string, map[string]string, string) error { + return errTestDownload + } + err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick") // 默认 remote-wins + if err == nil { + t.Fatal("下载失败时应以非零退出码退出") + } + if ec, ok := err.(*driveSyncFailure); !ok || ec.ExitCode() != 1 { + t.Fatalf("期望 driveSyncFailure(exit=1), got %T %v", err, err) + } + // 关键：原文件内容与存在性都不被破坏。 + if b, rerr := os.ReadFile(p); rerr != nil || string(b) != "local-original" { + t.Errorf("下载失败后本地原文件应原样保留, got %q err=%v", string(b), rerr) + } +} + +// keep-both 成功路径：本地既有文件改名保留（os.Rename 覆盖 O_EXCL 空占位），远端拉取到 +// 原路径。此测试在 Windows 主机上运行即验证 os.Rename 可替换既有目标（MOVEFILE_REPLACE_ +// EXISTING），覆盖 pull 覆盖与 keep-both 两条 rename 路径的平台行为。 +func TestDriveSync_keepBothSuccess(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-new") + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + } + if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "keep-both"); err != nil { + t.Fatalf("keep-both 成功路径不应报错: %v", err) + } + + // 原路径 f.txt 应为远端内容（拉取落盘）。 + if b, _ := os.ReadFile(p); string(b) != "remote-content" { + t.Errorf("f.txt 应为远端内容, got %q", string(b)) + } + // 本地版本改名保留为 f.conflict-F_FID.txt，内容不变。 + aside := filepath.Join(dir, "f.conflict-F_FID.txt") + if b, err := os.ReadFile(aside); err != nil || string(b) != "local-new" { + t.Errorf("本地版本应改名保留为 %s 且内容不变, got %q err=%v", filepath.Base(aside), string(b), err) + } + // 下载发生一次（拉取远端到原路径），不应有上传。 + if dl := caller.callsFor("download_file"); len(dl) != 1 { + t.Errorf("keep-both 应拉取远端一次, got %d download_file calls", len(dl)) + } + if up := caller.callsFor("get_upload_info"); len(up) != 0 { + t.Errorf("keep-both 不应上传, got %d get_upload_info calls", len(up)) + } +} + +// keep-both 下载失败：改名保留后拉取远端失败，应回滚改名——原文件恢复原名原内容， +// 不留下改名后的残留文件。 +func TestDriveSync_keepBothRollbackOnPullFailure(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-original") + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + } + failGet := func(context.Context, string, map[string]string, string) error { + return errTestDownload + } + err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick", "--on-conflict", "keep-both") + if err == nil { + t.Fatal("下载失败时应以非零退出码退出") + } + // 原文件恢复原名原内容。 + if b, rerr := os.ReadFile(p); rerr != nil || string(b) != "local-original" { + t.Errorf("keep-both 拉取失败应回滚改名, 原文件未恢复: got %q err=%v", string(b), rerr) + } + // 目录下不应残留改名后的 *.conflict-* 文件。 + entries, _ := os.ReadDir(dir) + for _, e := range entries { + if strings.Contains(e.Name(), "conflict-") { + t.Errorf("回滚后不应残留改名文件: %s", e.Name()) + } + } +} + +// reserveSyncKeepBothTarget 不得占用「精确同名」的既有文件（occupied 未记录时）， +// 应原子占位到下一个后缀，且既有文件内容不被破坏。此断言在任何文件系统上都成立。 +func TestReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) { + dir := t.TempDir() + // 预置一个与首选候选精确同名的既有文件（模拟未被 occupied 记录的外部残留）。 + first := "f.conflict-ABCD1234.txt" + mustWrite(t, filepath.Join(dir, first), "existing-data") + + rel, abs, err := reserveSyncKeepBothTarget(dir, "f.txt", "0000ABCD1234", map[string]bool{}) + if err != nil { + t.Fatal(err) + } + if rel == first { + t.Fatalf("不应占用既有文件 %s", first) + } + if want := "f.conflict-ABCD1234.1.txt"; rel != want { + t.Errorf("rel = %q, want %q", rel, want) + } + // 既有文件内容原样保留（未被覆盖）。 + if b, _ := os.ReadFile(filepath.Join(dir, first)); string(b) != "existing-data" { + t.Error("既有文件被覆盖，数据丢失") + } + // 返回的目标是新建的空占位文件。 + if fi, e := os.Stat(abs); e != nil || fi.Size() != 0 { + t.Errorf("占位文件应存在且为空: err=%v", e) + } +} + +// reserveSyncKeepBothTarget 在大小写不敏感文件系统上，不得覆盖与候选「大小写等价」的 +// 既有文件——O_EXCL 由 OS 兜底判等价性，occupied 的精确字符串键覆盖不到这种情况。 +func TestReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) { + dir := t.TempDir() + if !isCaseInsensitiveFS(dir) { + t.Skip("文件系统大小写敏感，跳过大小写等价覆盖测试") + } + // 既有文件用大写变体，occupied 为空（模拟精确键查重覆盖不到的等价文件）。 + existing := "f.CONFLICT-ABCD1234.TXT" + mustWrite(t, filepath.Join(dir, existing), "case-variant-data") + + rel, _, err := reserveSyncKeepBothTarget(dir, "f.txt", "0000abcd1234", map[string]bool{}) + if err != nil { + t.Fatal(err) + } + // 生成的小写候选与既有大写文件在不敏感 FS 上等价，本不应被占用。 + if strings.EqualFold(rel, "f.conflict-abcd1234.txt") { + t.Errorf("首选候选与既有文件等价，不应被占用: %q", rel) + } + // 既有文件内容原样保留。 + if b, _ := os.ReadFile(filepath.Join(dir, existing)); string(b) != "case-variant-data" { + t.Error("大小写等价的既有文件被覆盖，数据丢失") + } +} + +// 非交互 ask（stdin 立即 EOF）：冲突项应被跳过而非中止整个同步， +// new_local 仍上传、new_remote 仍下载，且被跳过的 modified 本地文件不被改动。 +func TestDriveSync_askNonInteractiveSkipsConflict(t *testing.T) { + prev := syncAskStdin + syncAskStdin = strings.NewReader("") // 非交互：立即 EOF + t.Cleanup(func() { syncAskStdin = prev }) + + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "local-only") // new_local → 应上传 + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-old") // modified → ask 非交互跳过 + local := readFileMTimeMillis(t, p) + + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[` + + `{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + differentMillis(local) + `},` + + `{"name":"remote.txt","type":"file","fileId":"R_FID","modifyTime":2000}` + + `],"nextToken":""}}`, + } + if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "ask"); err != nil { + t.Fatalf("非交互 ask 不应中止同步: %v", err) + } + + // new_local 上传、new_remote 下载都应照常发生。 + if up := caller.callsFor("get_upload_info"); len(up) != 1 { + t.Errorf("new_local 应被上传, got %d get_upload_info calls", len(up)) + } + if dl := caller.callsFor("download_file"); len(dl) != 1 || dl[0].args["fileId"] != "R_FID" { + t.Errorf("new_remote 应被下载, got %v", dl) + } + // modified 冲突被跳过：本地 f.txt 未被覆盖。 + if b, _ := os.ReadFile(p); string(b) != "local-old" { + t.Errorf("ask 跳过的 modified 文件不应被改动, got %q", string(b)) + } +} + +// readFileMTimeMillis 返回文件的 mtime（Unix 毫秒）。 +func readFileMTimeMillis(t *testing.T, path string) int64 { + t.Helper() + fi, err := os.Stat(path) + if err != nil { + t.Fatal(err) + } + return fi.ModTime().UnixMilli() +} + +// differentMillis 返回一个与 base 不同的毫秒数字符串，保证 quick 模式判为 modified。 +func differentMillis(base int64) string { + return strconv.FormatInt(base+60000, 10) // 差 1 分钟，足以区分 +} diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index b839af98..2232a4ea 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -82,7 +82,7 @@ cli_version: ">=1.0.15" | `devdoc` | 开放平台文档：搜索开发文档 | [devdoc.md](./references/products/devdoc.md) | | `ding` | DING消息：发送/撤回（应用内/短信/电话） | [ding.md](./references/products/ding.md) | | `doc` | 钉钉文档：搜索/浏览/读写/块级编辑/评论/文件创建/复制/移动/重命名/**删除/导出 docx/权限管理/媒体上传下载** | [doc.md](./references/products/doc.md) | -| `drive` | 钉钉云盘：文件列表/元数据/文件夹/上传(两步)/下载 | [drive.md](./references/products/drive.md) | +| `drive` | 钉钉云盘：文件列表/元数据/文件夹/上传(两步)/下载/本地与钉盘文件夹差异比较(status)/拉取到本地(pull)/推送到钉盘(push)/双向同步(sync) | [drive.md](./references/products/drive.md) | | `hrbrain` | 组织大脑：人才池管理/员工档案专项模块查询（元数据/批量数据/标签/职业历程/绩效）/结构化高级人才搜索（原始条件表达式）；区别于 `contact` 的基础通讯录档案与 `aisearch` 的通用语义找人 | [hrbrain.md](./references/products/hrbrain.md) | | `markdown` | 原生 Markdown 文件：读取/创建/全量覆盖/字面量或 RE2 局部替换 | [markdown.md](./references/products/markdown.md) | | `minutes` | AI听记：听记列表/摘要/关键词/转写/待办/思维导图/发言人/发言人段落总结/热词/录音控制/成员权限/上传 | [minutes.md](./references/products/minutes.md) | diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 80e7e3ed..188e0936 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -343,6 +343,207 @@ Flags: > **注意**：还原操作可能是异步的（返回 `async=true` 和 `taskId`）。 +### 比较本地文件夹与钉盘文件夹的差异 + +只读命令：比较本地文件夹与钉盘文件夹的差异——本地取 `--local-folder`（**绝对路径**），钉盘取 `--remote-folder`（文件夹 dentryUuid，**必传**）指向的文件夹，按精确 MD5（默认）或快速 modified_time（`--quick`）逐文件比对。两侧各自递归遍历，`rel_path` 相对各自根目录。 + +``` +Usage: + dws drive status [flags] +Example: + dws drive status --local-folder /abs/path/repo --remote-folder + dws drive status --local-folder /abs/path/repo --remote-folder --space-id xxxx + dws drive status --local-folder /abs/path/repo --remote-folder --quick +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) +``` + +输出五类差异（`rel_path` 始终以 `/` 分隔、相对各自根目录）： + +| 字段 | 含义 | +|------|------| +| `new_local` | 仅本地存在 | +| `new_remote` | 仅钉盘存在 | +| `modified` | 两侧都存在且本次检测判定为已变更（exact 比 MD5，quick 比 modified_time） | +| `unchanged` | 两侧都存在且本次检测判定为未变更 | +| `unknown` | 两侧都存在，但 exact 模式下**远端未返回可靠 MD5**、无法核对内容——既不判 unchanged 也不判 modified，如实归入此类（quick 模式不会产生 unknown） | + +输出 schema： + +```json +{ + "detection": "exact", + "new_local": [{"rel_path": "..."}], + "new_remote": [{"rel_path": "..."}], + "modified": [{"rel_path": "..."}], + "unchanged": [{"rel_path": "..."}], + "unknown": [{"rel_path": "..."}] +} +``` + +注意事项： + +- 默认 `detection=exact`（比较 MD5）；传 `--quick` 后 `detection=quick`（只比较 modified_time，best-effort）。 +- exact 模式**只在能拿到远端 MD5 时才判定 unchanged/modified**；远端缺失 MD5 的文件一律进入 `unknown`，绝不会因大小 / mtime 恰好相同而被误报为 unchanged。当前 `list_files` 通常不返回 MD5，因此这类文件多会落在 `unknown`——请据此决定是否用 `pull`/`push` 强制对齐。 +- 本地 hash 仅在文件双端都存在、远端有 MD5、且非 `--quick` 模式时才按需计算。 +- 远端条目名称若含 `..`、路径分隔符或盘符等非规范成分，会被直接跳过、不纳入比对（防止逃逸性路径）。 +- 只比对钉盘 `type=file` 的二进制文件；在线文档（docx/sheet/bitable/mindnote/slides）与快捷方式（shortcut）会被跳过。本地只比对常规文件（符号链接、设备文件忽略）。 +- `--local-folder` 必须是绝对路径（相对路径会被直接拒绝）；`--remote-folder` 必传，是钉盘侧待比对文件夹的 dentryUuid（可用 `dws drive list` 查到）。 + +### 把钉盘文件夹拉取（镜像）到本地 + +只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。 + +``` +Usage: + dws drive pull [flags] +Example: + dws drive pull --local-folder /abs/path/repo --remote-folder + dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive pull --local-folder /abs/path/repo --remote-folder --space-id xxxx +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --if-exists string 本地文件已存在时的策略: overwrite|smart|skip (默认 overwrite) +``` + +`--if-exists` 策略： + +| 值 | 行为 | +|----|------| +| `overwrite`（默认） | 总是下载覆盖（Drive 作为权威源） | +| `smart`（推荐增量同步） | 本地 `modified_time` 已 ≥ 远端 `modified_time` 则跳过；时间戳缺失/非法时退回安全路径继续下载 | +| `skip` | 本地已存在则保持不动 | + +输出 schema： + +```json +{ + "summary": {"downloaded": 0, "skipped": 0, "failed": 0}, + "items": [ + {"rel_path": "sub/a.txt", "action": "downloaded"}, + {"rel_path": "b.txt", "action": "skipped"}, + {"rel_path": "c.bin", "action": "failed", "error": "..."} + ] +} +``` + +注意事项： + +- 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 +- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 +- `summary.failed > 0` 时命令以**非零退出码**退出（`error.type=partial_failure`），同一份 `summary + items` 在 `error.detail` 里返回；脚本/agent 直接看 exit code 即可判断成败。 + +### 把本地文件夹推送（镜像）到钉盘 + +只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**只新增/覆盖，不删除远端多余文件。** + +``` +Usage: + dws drive push [flags] +Example: + dws drive push --local-folder /abs/path/repo --remote-folder + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip) +``` + +`--if-exists` 策略（注意默认与 pull 相反，push 默认 `skip` 更安全）： + +| 值 | 行为 | +|----|------| +| `skip`（默认） | 远端已存在则保持不动，只新增 | +| `smart` | 增量同步：远端 `modified_time` 已 ≥ 本地则跳过，否则走覆盖路径 | +| `overwrite` | 覆盖远端同名文件（原地覆盖，保留 fileId，不产生重名副本） | + +输出 schema（`action`：`uploaded` / `overwritten` / `skipped` / `folder_created` / `failed`）： + +```json +{ + "summary": {"uploaded": 0, "skipped": 0, "failed": 0, "aborted": false}, + "items": [ + {"rel_path": "sub", "action": "folder_created"}, + {"rel_path": "a.txt", "action": "uploaded", "size_bytes": 11}, + {"rel_path": "b.txt", "action": "overwritten", "size_bytes": 8}, + {"rel_path": "c.txt", "action": "skipped", "size_bytes": 5}, + {"rel_path": "d.bin", "action": "failed", "size_bytes": 0, "error": "..."} + ] +} +``` + +注意事项： + +- 只上传/覆盖 `type=file`；`summary.uploaded` 同时统计新建与覆盖，**不含目录**。 +- `overwrite` / `smart` 命中覆盖分支时走**覆盖上传**（`get_upload_info` 与 `commit_upload` 两阶段都携带远端 `overwriteFileId`、不传 `parentId`），在原文件上原地覆盖、保留 fileId，不会在同目录新建重名副本。 +- 本地子目录（含空目录）整体镜像：缺失的按需 `create_folder`（以 `folder_created` 留痕），已存在的远端目录复用其 fileId、不重建、不出现在 `items[]`。 +- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，脚本/agent 直接看 exit code 判断成败。 + +### 本地文件夹与钉盘文件夹双向同步 + +读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** + +``` +Usage: + dws drive sync [flags] +Example: + dws drive sync --local-folder /abs/path/repo --remote-folder + dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict local-wins + dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both + dws drive sync --local-folder /abs/path/repo --remote-folder --quick +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --on-conflict string 两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (默认 remote-wins) + --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) +``` + +`--on-conflict` 仅作用于 `modified`（两侧都存在且都变更）的文件： + +| 值 | 行为 | +|----|------| +| `remote-wins`（默认） | 下载远端覆盖本地 | +| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId） | +| `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | +| `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | + +输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；`direction`：`pull` / `push` / `conflict`）： + +```json +{ + "detection": "exact", + "diff": { + "new_local": [{"rel_path": "a.txt"}], + "new_remote": [{"rel_path": "b.txt"}], + "modified": [{"rel_path": "c.txt"}], + "unchanged": [], + "unknown": [] + }, + "summary": {"pulled": 1, "pushed": 1, "skipped": 0, "failed": 0}, + "items": [ + {"rel_path": "b.txt", "action": "downloaded", "direction": "pull"}, + {"rel_path": "a.txt", "action": "uploaded", "direction": "push"}, + {"rel_path": "c.txt", "action": "overwritten", "direction": "conflict"} + ] +} +``` + +注意事项： + +- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符或盘符等非规范成分会被跳过，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 +- `--dry-run` 只算差异并打印 `diff`，不触发任何下载/上传/改名/落盘。 +- `unknown`（exact 模式远端无可靠 MD5）一律计入 `skipped`、不做任何写操作；需要强制对齐时改用单向的 `pull`/`push`。 +- `summary.failed > 0` 时命令以**非零退出码**退出，结构化结果仍打印在 stdout 上。 + ## 意图判断 用户说"我的文件/钉盘/网盘/云盘" → `list` @@ -365,6 +566,10 @@ Flags: 用户说"公开文件/互联网公开/设置公开/让互联网所有人可访问" → `publish set` 用户说"关闭公开/取消公开/取消互联网访问" → `publish unset` 用户说"查看公开状态/是否公开/发布状态" → `publish get` +用户说"比较本地和云盘/看哪些文件变了/同步差异/diff" → `status` +用户说"把钉盘文件夹拉到本地/下载整个文件夹/镜像/同步到本地/pull" → `pull` +用户说"把本地文件夹传到钉盘/推送整个文件夹/上传目录/同步到云端/push" → `push` +用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（两侧都变更时用 `--on-conflict` 决定谁覆盖谁） 关键区分: drive(文件管理) vs doc(文档内容读写) vs wiki(空间管理) @@ -413,6 +618,23 @@ dws drive delete --node --yes --format json # 8. 查看回收站并还原文件 dws drive recycle list --format json dws drive recycle restore --id --format json + +# 9. 比较本地文件夹与钉盘文件夹的差异（只读；remote-folder 必传，用 list 查 dentryUuid） +dws drive status --local-folder /abs/path/repo --remote-folder --format json +dws drive status --local-folder /abs/path/repo --remote-folder --space-id --format json +dws drive status --local-folder /abs/path/repo --remote-folder --quick --format json + +# 10. 把钉盘文件夹镜像到本地（Drive → 本地；smart 为推荐的增量同步） +dws drive pull --local-folder /abs/path/repo --remote-folder --format json +dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart --format json + +# 11. 把本地文件夹镜像到钉盘（本地 → Drive；默认 skip 只新增，smart 增量，overwrite 覆盖） +dws drive push --local-folder /abs/path/repo --remote-folder --format json +dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --format json + +# 12. 本地与钉盘双向同步（两侧都变更时用 --on-conflict 消解，默认 remote-wins） +dws drive sync --local-folder /abs/path/repo --remote-folder --format json +dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both --format json ``` ## 文档空间管理命令 @@ -531,6 +753,7 @@ dws drive move --node <源文件dentryUuid> --folder <目标space的rootFolderId # ── 场景 C: 复制钉盘文件到钉盘 space 下的子文件夹 ── dws drive list --space-id --format json dws drive copy --node <源文件dentryUuid> --folder <目标文件夹fileId> --format json + ``` ## 上下文传递表 diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index b3ce3ba6..b22a7283 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-drive -description: 钉钉文件管理（存储层）。Use when 用户说 钉盘/上传文件/下载文件/文件夹/查文件/找文件/全局搜索文件/复制/移动/重命名/删除/回收站/还原删除文件/权限管理/普通文件下载。任何文件类型都适用；文档内容编辑走 dingtalk-doc，知识库空间和空间内节点管理走 dingtalk-wiki。命令前缀：dws drive。 +description: 钉钉文件管理（存储层）。Use when 用户说 钉盘/上传文件/下载文件/文件夹/查文件/找文件/全局搜索文件/复制/移动/重命名/删除/回收站/还原删除文件/权限管理/普通文件下载/本地与钉盘文件夹差异比较/整个文件夹拉到本地/整个文件夹推到钉盘/双向同步。任何文件类型都适用；文档内容编辑走 dingtalk-doc，知识库空间和空间内节点管理走 dingtalk-wiki。命令前缀：dws drive。 metadata: cli_version: ">=0.2.14" category: product diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 29680fa2..0b35d622 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -328,6 +328,207 @@ Flags: - `hasMore` — 是否有更多数据 - `nextCursor` — 下次分页游标 +### 比较本地文件夹与钉盘文件夹的差异 + +只读命令：比较本地文件夹与钉盘文件夹的差异——本地取 `--local-folder`（**绝对路径**），钉盘取 `--remote-folder`（文件夹 dentryUuid，**必传**）指向的文件夹，按精确 MD5（默认）或快速 modified_time（`--quick`）逐文件比对。两侧各自递归遍历，`rel_path` 相对各自根目录。 + +``` +Usage: + dws drive status [flags] +Example: + dws drive status --local-folder /abs/path/repo --remote-folder + dws drive status --local-folder /abs/path/repo --remote-folder --space-id xxxx + dws drive status --local-folder /abs/path/repo --remote-folder --quick +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) +``` + +输出五类差异（`rel_path` 始终以 `/` 分隔、相对各自根目录）： + +| 字段 | 含义 | +|------|------| +| `new_local` | 仅本地存在 | +| `new_remote` | 仅钉盘存在 | +| `modified` | 两侧都存在且本次检测判定为已变更（exact 比 MD5，quick 比 modified_time） | +| `unchanged` | 两侧都存在且本次检测判定为未变更 | +| `unknown` | 两侧都存在，但 exact 模式下**远端未返回可靠 MD5**、无法核对内容——既不判 unchanged 也不判 modified，如实归入此类（quick 模式不会产生 unknown） | + +输出 schema： + +```json +{ + "detection": "exact", + "new_local": [{"rel_path": "..."}], + "new_remote": [{"rel_path": "..."}], + "modified": [{"rel_path": "..."}], + "unchanged": [{"rel_path": "..."}], + "unknown": [{"rel_path": "..."}] +} +``` + +注意事项： + +- 默认 `detection=exact`（比较 MD5）；传 `--quick` 后 `detection=quick`（只比较 modified_time，best-effort）。 +- exact 模式**只在能拿到远端 MD5 时才判定 unchanged/modified**；远端缺失 MD5 的文件一律进入 `unknown`，绝不会因大小 / mtime 恰好相同而被误报为 unchanged。当前 `list_files` 通常不返回 MD5，因此这类文件多会落在 `unknown`——请据此决定是否用 `pull`/`push` 强制对齐。 +- 本地 hash 仅在文件双端都存在、远端有 MD5、且非 `--quick` 模式时才按需计算。 +- 远端条目名称若含 `..`、路径分隔符或盘符等非规范成分，会被直接跳过、不纳入比对（防止逃逸性路径）。 +- 只比对钉盘 `type=file` 的二进制文件；在线文档（docx/sheet/bitable/mindnote/slides）与快捷方式（shortcut）会被跳过。本地只比对常规文件（符号链接、设备文件忽略）。 +- `--local-folder` 必须是绝对路径（相对路径会被直接拒绝）；`--remote-folder` 必传，是钉盘侧待比对文件夹的 dentryUuid（可用 `dws drive list` 查到）。 + +### 把钉盘文件夹拉取（镜像）到本地 + +只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。 + +``` +Usage: + dws drive pull [flags] +Example: + dws drive pull --local-folder /abs/path/repo --remote-folder + dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive pull --local-folder /abs/path/repo --remote-folder --space-id xxxx +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --if-exists string 本地文件已存在时的策略: overwrite|smart|skip (默认 overwrite) +``` + +`--if-exists` 策略： + +| 值 | 行为 | +|----|------| +| `overwrite`（默认） | 总是下载覆盖（Drive 作为权威源） | +| `smart`（推荐增量同步） | 本地 `modified_time` 已 ≥ 远端 `modified_time` 则跳过；时间戳缺失/非法时退回安全路径继续下载 | +| `skip` | 本地已存在则保持不动 | + +输出 schema： + +```json +{ + "summary": {"downloaded": 0, "skipped": 0, "failed": 0}, + "items": [ + {"rel_path": "sub/a.txt", "action": "downloaded"}, + {"rel_path": "b.txt", "action": "skipped"}, + {"rel_path": "c.bin", "action": "failed", "error": "..."} + ] +} +``` + +注意事项： + +- 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 +- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 +- `summary.failed > 0` 时命令以**非零退出码**退出（`error.type=partial_failure`），同一份 `summary + items` 在 `error.detail` 里返回；脚本/agent 直接看 exit code 即可判断成败。 + +### 把本地文件夹推送（镜像）到钉盘 + +只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**只新增/覆盖，不删除远端多余文件。** + +``` +Usage: + dws drive push [flags] +Example: + dws drive push --local-folder /abs/path/repo --remote-folder + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip) +``` + +`--if-exists` 策略（注意默认与 pull 相反，push 默认 `skip` 更安全）： + +| 值 | 行为 | +|----|------| +| `skip`（默认） | 远端已存在则保持不动，只新增 | +| `smart` | 增量同步：远端 `modified_time` 已 ≥ 本地则跳过，否则走覆盖路径 | +| `overwrite` | 覆盖远端同名文件（原地覆盖，保留 fileId，不产生重名副本） | + +输出 schema（`action`：`uploaded` / `overwritten` / `skipped` / `folder_created` / `failed`）： + +```json +{ + "summary": {"uploaded": 0, "skipped": 0, "failed": 0, "aborted": false}, + "items": [ + {"rel_path": "sub", "action": "folder_created"}, + {"rel_path": "a.txt", "action": "uploaded", "size_bytes": 11}, + {"rel_path": "b.txt", "action": "overwritten", "size_bytes": 8}, + {"rel_path": "c.txt", "action": "skipped", "size_bytes": 5}, + {"rel_path": "d.bin", "action": "failed", "size_bytes": 0, "error": "..."} + ] +} +``` + +注意事项： + +- 只上传/覆盖 `type=file`；`summary.uploaded` 同时统计新建与覆盖，**不含目录**。 +- `overwrite` / `smart` 命中覆盖分支时走**覆盖上传**（`get_upload_info` 与 `commit_upload` 两阶段都携带远端 `overwriteFileId`、不传 `parentId`），在原文件上原地覆盖、保留 fileId，不会在同目录新建重名副本。 +- 本地子目录（含空目录）整体镜像：缺失的按需 `create_folder`（以 `folder_created` 留痕），已存在的远端目录复用其 fileId、不重建、不出现在 `items[]`。 +- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，脚本/agent 直接看 exit code 判断成败。 + +### 本地文件夹与钉盘文件夹双向同步 + +读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** + +``` +Usage: + dws drive sync [flags] +Example: + dws drive sync --local-folder /abs/path/repo --remote-folder + dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict local-wins + dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both + dws drive sync --local-folder /abs/path/repo --remote-folder --quick +Flags: + --local-folder string 本地文件夹绝对路径 (必填) + --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) + --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) + --on-conflict string 两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (默认 remote-wins) + --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) +``` + +`--on-conflict` 仅作用于 `modified`（两侧都存在且都变更）的文件： + +| 值 | 行为 | +|----|------| +| `remote-wins`（默认） | 下载远端覆盖本地 | +| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId） | +| `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | +| `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | + +输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；`direction`：`pull` / `push` / `conflict`）： + +```json +{ + "detection": "exact", + "diff": { + "new_local": [{"rel_path": "a.txt"}], + "new_remote": [{"rel_path": "b.txt"}], + "modified": [{"rel_path": "c.txt"}], + "unchanged": [], + "unknown": [] + }, + "summary": {"pulled": 1, "pushed": 1, "skipped": 0, "failed": 0}, + "items": [ + {"rel_path": "b.txt", "action": "downloaded", "direction": "pull"}, + {"rel_path": "a.txt", "action": "uploaded", "direction": "push"}, + {"rel_path": "c.txt", "action": "overwritten", "direction": "conflict"} + ] +} +``` + +注意事项： + +- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符或盘符等非规范成分会被跳过，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 +- `--dry-run` 只算差异并打印 `diff`，不触发任何下载/上传/改名/落盘。 +- `unknown`（exact 模式远端无可靠 MD5）一律计入 `skipped`、不做任何写操作；需要强制对齐时改用单向的 `pull`/`push`。 +- `summary.failed > 0` 时命令以**非零退出码**退出，结构化结果仍打印在 stdout 上。 + ## 意图判断 用户说"我的文件/钉盘/网盘/云盘" → `list` @@ -357,6 +558,10 @@ Flags: 用户说"公开文件/互联网公开/设置公开/让互联网所有人可访问" → `publish set` 用户说"关闭公开/取消公开/取消互联网访问" → `publish unset` 用户说"查看公开状态/是否公开/发布状态" → `publish get` +用户说"比较本地和云盘/看哪些文件变了/同步差异/diff" → `status` +用户说"把钉盘文件夹拉到本地/下载整个文件夹/镜像/同步到本地/pull" → `pull` +用户说"把本地文件夹传到钉盘/推送整个文件夹/上传目录/同步到云端/push" → `push` +用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（两侧都变更时用 `--on-conflict` 决定谁覆盖谁） 用户说"查任务状态/导出好了没/任务进度/导入状态" → 文档导出用 `dws doc export get --job-id `，导入用 `dws doc import get --task-id ` 关键区分: drive(文件管理) vs doc(文档内容读写) vs wiki(空间管理) @@ -412,6 +617,23 @@ dws drive star add --node --format json dws drive star remove --node --format json dws drive star list --format json dws drive star list --content-types doc,sheet --limit 10 --format json + +# 10. 比较本地文件夹与钉盘文件夹的差异（只读；remote-folder 必传，用 list 查 dentryUuid） +dws drive status --local-folder /abs/path/repo --remote-folder --format json +dws drive status --local-folder /abs/path/repo --remote-folder --space-id --format json +dws drive status --local-folder /abs/path/repo --remote-folder --quick --format json + +# 11. 把钉盘文件夹镜像到本地（Drive → 本地；smart 为推荐的增量同步） +dws drive pull --local-folder /abs/path/repo --remote-folder --format json +dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart --format json + +# 12. 把本地文件夹镜像到钉盘（本地 → Drive；默认 skip 只新增，smart 增量，overwrite 覆盖） +dws drive push --local-folder /abs/path/repo --remote-folder --format json +dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --format json + +# 13. 本地与钉盘双向同步（两侧都变更时用 --on-conflict 消解，默认 remote-wins） +dws drive sync --local-folder /abs/path/repo --remote-folder --format json +dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both --format json ``` ## 无权限引导申请工作流 From b6c508acdf48d131c077e935fc3972ceb6ef6e0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 11:49:14 +0800 Subject: [PATCH 004/250] fix(chat): canonicalize send-card id flags --- internal/cli/schema_constraints_runtime.go | 2 +- internal/helpers/chat.go | 31 +++++++++++---------- internal/helpers/chat_command_edges_test.go | 9 +++--- internal/helpers/chat_message_help_test.go | 23 +++++++++++++++ 4 files changed, 45 insertions(+), 20 deletions(-) diff --git a/internal/cli/schema_constraints_runtime.go b/internal/cli/schema_constraints_runtime.go index fbc03613..1bb7ea9b 100644 --- a/internal/cli/schema_constraints_runtime.go +++ b/internal/cli/schema_constraints_runtime.go @@ -37,7 +37,7 @@ func init() { registerRequireOneOf("calendar.query_busy_status", "users", "rooms") registerRequireTogether("calendar.update_calendar_event", "recurrence-type", "recurrence-interval", "recurrence-range-type") registerExclusiveOneOf("chat.search_messages_by_sender", "sender-user-id", "sender-open-dingtalk-id") - registerExclusiveOneOf("chat.create_and_send_card", "conversation-id", "receiver") + registerExclusiveOneOf("chat.create_and_send_card", "conversation-id", "open-dingtalk-id") RegisterRuntimeSchemaConstraints("chat.chat_permission_grant", RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"conversation-id", "open-dingtalk-id", "user"}}, RequireOneOf: [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}}, diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 45f2af49..0fc2dc99 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -5824,7 +5824,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendCardCmd := &cobra.Command{ Use: "send-card", Short: "创建并推送流式卡片", - Long: `向群聊或单聊创建并推送流式卡片。群聊传 --conversation-id，单聊传 --receiver，二者互斥。 + Long: `向群聊或单聊创建并推送流式卡片。群聊传 --conversation-id，单聊传 --open-dingtalk-id，二者互斥。 群聊创建卡片时可通过 --at-open-dingtalk-ids @指定成员，或通过 --at-all @所有人。 创建时无需传入卡片内容，后续通过 update-card 更新内容。 @@ -5832,24 +5832,24 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id 最后一次更新必须将 --flow-status 设为 3（finish），否则卡片会一直处于"生成中"的加载状态。 flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成(FINISH)，4=执行中(EXECUTING)，5=错误(ERROR)。`, Example: ` dws chat message send-card --conversation-id - dws chat message send-card --group --at-open-dingtalk-ids - dws chat message send-card --group --at-all - dws chat message send-card --receiver + dws chat message send-card --conversation-id --at-open-dingtalk-ids + dws chat message send-card --conversation-id --at-all + dws chat message send-card --open-dingtalk-id # 查询群 ID: dws chat search --query "群名" # 查询人员: dws contact user search --keyword "姓名" --format json`, RunE: func(cmd *cobra.Command, args []string) error { groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") - receiver, _ := cmd.Flags().GetString("receiver") + receiver := flagOrFallback(cmd, "open-dingtalk-id", "receiver") atOpenDingTalkIDs := uniqueNonEmptyStrings(parseCSVValues(mustGetFlag(cmd, "at-open-dingtalk-ids"))) atAll, _ := cmd.Flags().GetBool("at-all") if groupID == "" && receiver == "" { - return fmt.Errorf("--conversation-id or --receiver is required") + return fmt.Errorf("--conversation-id or --open-dingtalk-id is required") } if groupID != "" && receiver != "" { - return fmt.Errorf("--conversation-id and --receiver are mutually exclusive") + return fmt.Errorf("--conversation-id and --open-dingtalk-id are mutually exclusive") } if groupID == "" && (len(atOpenDingTalkIDs) > 0 || atAll) { - return fmt.Errorf("--at-open-dingtalk-ids and --at-all are only supported with --group") + return fmt.Errorf("--at-open-dingtalk-ids and --at-all are only supported with --conversation-id") } toolArgs := map[string]any{} if groupID != "" { @@ -5899,16 +5899,17 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Parameters: []contract.ParamDecl{ {Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds", Required: boolPtr(false), InterfaceType: "array"}, - {Name: "group", Property: "openConversationId"}, - {Name: "receiver", Property: "receiverOpenDingTalkId"}, + {Name: "conversation-id", Property: "openConversationId"}, + {Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"}, }, }, }) - chatMessageSendCardCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填，与 --receiver 互斥）") - chatMessageSendCardCmd.Flags().String("receiver", "", "单聊接收者 openDingTalkId（单聊时必填，与 --conversation-id 互斥）") - chatMessageSendCardCmd.Flags().String("receiver", "", "单聊接收者 openDingTalkId（单聊时必填，与 --group 互斥）") - chatMessageSendCardCmd.Flags().String("at-open-dingtalk-ids", "", "群聊创建卡片时 @ 的 openDingTalkId 列表，逗号分隔（仅与 --group 一起使用）") - chatMessageSendCardCmd.Flags().Bool("at-all", false, "群聊创建卡片时 @ 所有人（仅与 --group 一起使用）") + chatMessageSendCardCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填，与 --open-dingtalk-id 互斥）") + chatMessageSendCardCmd.Flags().String("open-dingtalk-id", "", "单聊接收者 openDingTalkId（单聊时必填，与 --conversation-id 互斥）") + chatMessageSendCardCmd.Flags().String("receiver", "", "--open-dingtalk-id 的兼容别名") + _ = chatMessageSendCardCmd.Flags().MarkHidden("receiver") + chatMessageSendCardCmd.Flags().String("at-open-dingtalk-ids", "", "群聊创建卡片时 @ 的 openDingTalkId 列表，逗号分隔（仅与 --conversation-id 一起使用）") + chatMessageSendCardCmd.Flags().Bool("at-all", false, "群聊创建卡片时 @ 所有人（仅与 --conversation-id 一起使用）") chatMessageUpdateCardCmd := &cobra.Command{ Use: "update-card", diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 4e6f3acd..33f65f06 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -282,7 +282,7 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) { caller := &scriptedToolCaller{} err := runChatCoverageCommand(t, caller, "message", "send-card", - "--group=cid", + "--conversation-id=cid", "--at-open-dingtalk-ids=D1,D2,D1", "--at-all", ) @@ -303,13 +303,13 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) { name string args []string }{ - {name: "member mention rejects direct message", args: []string{"--receiver=D1", "--at-open-dingtalk-ids=D2"}}, - {name: "at all rejects direct message", args: []string{"--receiver=D1", "--at-all"}}, + {name: "member mention rejects direct message", args: []string{"--open-dingtalk-id=D1", "--at-open-dingtalk-ids=D2"}}, + {name: "at all rejects direct message", args: []string{"--open-dingtalk-id=D1", "--at-all"}}, } { t.Run(tc.name, func(t *testing.T) { caller := &scriptedToolCaller{} err := runChatCoverageCommand(t, caller, append([]string{"message", "send-card"}, tc.args...)...) - if err == nil || !strings.Contains(err.Error(), "only supported with --group") { + if err == nil || !strings.Contains(err.Error(), "only supported with --conversation-id") { t.Fatalf("error = %v, want group-only mention validation", err) } if caller.calls != 0 { @@ -332,6 +332,7 @@ func TestCrossPlatformCoverageChatWebhookReplyConversationAndDownloadEdges(t *te _ = runChatCoverageCommand(t, &scriptedToolCaller{}, "conversation-info", "--open-dingtalk-id=D1") _ = runChatCoverageCommand(t, &scriptedToolCaller{}, "conversation-info", "--user=D1") _ = runChatCoverageCommand(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"D1"}]}`}, {text: `{}`}}}, "conversation-info", "--user=u1") + _ = runChatCoverageCommand(t, &scriptedToolCaller{}, "message", "send-card", "--open-dingtalk-id=D1") _ = runChatCoverageCommand(t, &scriptedToolCaller{}, "message", "send-card", "--receiver=D1") oldGet := httpGetFile diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 673b17cf..f47e061d 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -136,3 +136,26 @@ func TestCrossPlatformCoverageChatGroupBotsHelpSplitsGroupName(t *testing.T) { t.Fatalf("chat group bots help exposes hidden --group alias:\n%s", help) } } + +func TestCrossPlatformCoverageChatSendCardHelpUsesCanonicalIDFlags(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) + cmd.SetArgs([]string{"message", "send-card", "--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("chat message send-card --help: %v\n%s", err, output.String()) + } + + help := output.String() + for _, visible := range []string{"--conversation-id", "--open-dingtalk-id"} { + if !strings.Contains(help, visible) { + t.Fatalf("send-card help missing %s:\n%s", visible, help) + } + } + for _, hidden := range []string{"--group", "--receiver"} { + if strings.Contains(help, hidden+" string") { + t.Fatalf("send-card help exposes hidden alias %s:\n%s", hidden, help) + } + } +} From 185fbb1544a3fbe1403eef229bebb72de2693208 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 12:43:44 +0800 Subject: [PATCH 005/250] chore(schema): record drive sync leaves as reviewed pending-review exclusions --- internal/cli/schema_command_exclusions.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/internal/cli/schema_command_exclusions.go b/internal/cli/schema_command_exclusions.go index 328c1f42..3fb2158f 100644 --- a/internal/cli/schema_command_exclusions.go +++ b/internal/cli/schema_command_exclusions.go @@ -99,6 +99,10 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{ "ding message receiver-status", "ding message send-by-message", "ding message send-personal", + "drive pull", + "drive push", + "drive status", + "drive sync", "mail allow-list add", "mail allow-list list", "mail allow-list remove", From 01c1428b663f1985eac1fde43b0d098b608d332c Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 13:33:09 +0800 Subject: [PATCH 006/250] test(drive): cover sync family end-to-end paths and error branches --- internal/helpers/drive_pull_coverage_test.go | 260 ++++++++++ internal/helpers/drive_push_coverage_test.go | 463 ++++++++++++++++++ .../helpers/drive_status_coverage_test.go | 341 +++++++++++++ internal/helpers/drive_sync_coverage_test.go | 412 ++++++++++++++++ internal/helpers/drive_sync_edges_test.go | 302 ++++++++++++ 5 files changed, 1778 insertions(+) create mode 100644 internal/helpers/drive_pull_coverage_test.go create mode 100644 internal/helpers/drive_push_coverage_test.go create mode 100644 internal/helpers/drive_status_coverage_test.go create mode 100644 internal/helpers/drive_sync_coverage_test.go create mode 100644 internal/helpers/drive_sync_edges_test.go diff --git a/internal/helpers/drive_pull_coverage_test.go b/internal/helpers/drive_pull_coverage_test.go new file mode 100644 index 00000000..ef04e2d3 --- /dev/null +++ b/internal/helpers/drive_pull_coverage_test.go @@ -0,0 +1,260 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "strconv" + "strings" + "testing" +) + +// ────────────────────────────────────────────────────────── +// runDrivePull — 端到端：远端树 → 本地落盘 +// ────────────────────────────────────────────────────────── + +// pullListingCaller 返回固定的单层远端清单，download_file 给出预签名链接。 +func pullListingCaller(items string) *driveScriptCaller { + return &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + switch tool { + case "list_files": + if nth > 0 { + return `{"result":{"items":[],"nextToken":""}}`, nil + } + return `{"result":{"items":[` + items + `],"nextToken":""}}`, nil + case "download_file": + return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil + } + return `{"result":{},"success":true}`, nil + }} +} + +// 端到端 pull：远端两个文件都下载到本地，并自动创建缺失的本地根目录。 +func TestDrivePull_endToEndDownloadsAll(t *testing.T) { + root := filepath.Join(t.TempDir(), "created-by-pull") + caller := pullListingCaller( + `{"name":"a.txt","type":"file","fileId":"A","modifyTime":1000},` + + `{"name":"b.txt","type":"file","fileId":"B","modifyTime":2000}`) + + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("remote"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + for _, name := range []string{"a.txt", "b.txt"} { + if b, err := os.ReadFile(filepath.Join(root, name)); err != nil || string(b) != "remote" { + t.Errorf("%s not written: %v / %q", name, err, string(b)) + } + } +} + +// --if-exists skip：本地已存在则不下载。 +func TestDrivePull_ifExistsSkipKeepsLocal(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "a.txt"), "local-original") + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9000}`) + + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("skip must not download") + return nil + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "skip"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(filepath.Join(root, "a.txt")); string(b) != "local-original" { + t.Errorf("local file changed: %q", string(b)) + } +} + +// --if-exists smart：本地 mtime 已 ≥ 远端 → 跳过；远端更新 → 下载。 +func TestDrivePull_ifExistsSmart(t *testing.T) { + t.Run("local newer skips", func(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "a.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local-5000, 10) + `}`) + + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("smart must not download when local is newer") + return nil + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "local" { + t.Errorf("local file changed: %q", string(b)) + } + }) + + t.Run("remote newer downloads", func(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "a.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local+60000, 10) + `}`) + + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("fresh"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "fresh" { + t.Errorf("expected download, got %q", string(b)) + } + }) +} + +// --if-exists 非法值直接拒绝。 +func TestDrivePull_invalidIfExistsRejected(t *testing.T) { + caller := pullListingCaller("") + err := runDriveCmd(t, caller, "pull", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--if-exists", "bogus") + if err == nil || !strings.Contains(err.Error(), "--if-exists") { + t.Fatalf("expected --if-exists rejection, got %v", err) + } +} + +// space-id 透传到 download_file。 +func TestDrivePull_passesSpaceIDToDownload(t *testing.T) { + root := t.TempDir() + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("x"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--space-id", "SP9"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("download_file")[0].args["spaceId"]; got != "SP9" { + t.Errorf("download_file spaceId = %v, want SP9", got) + } +} + +// 下载失败 → 该项记 failed，命令以 partial_failure 非零退出。 +func TestDrivePull_downloadFailureIsPartialFailure(t *testing.T) { + root := t.TempDir() + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT") + var pf *drivePartialFailure + if !errors.As(err, &pf) { + t.Fatalf("expected drivePartialFailure, got %T %v", err, err) + } + if !strings.Contains(pf.raw, "partial_failure") { + t.Errorf("detail missing partial_failure: %s", pf.raw) + } +} + +// download_file 未返回下载链接 → failed（不是 panic，也不落盘）。 +func TestDrivePull_missingDownloadURLFails(t *testing.T) { + root := t.TempDir() + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + if tool == "list_files" { + if nth > 0 { + return `{"result":{"items":[],"nextToken":""}}`, nil + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`, nil + } + return `{"result":{"fileId":"A"},"success":true}`, nil // 无 downloadUrl + }} + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected failure when download_file returns no URL") + } + if _, err := os.Stat(filepath.Join(root, "a.txt")); !os.IsNotExist(err) { + t.Error("nothing must be written when the download URL is missing") + } +} + +// download_file 的 MCP 调用本身失败 → failed。 +func TestDrivePull_downloadToolErrorFails(t *testing.T) { + root := t.TempDir() + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + if tool == "list_files" { + if nth > 0 { + return `{"result":{"items":[],"nextToken":""}}`, nil + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`, nil + } + return "", errTestDownload + }} + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected failure when download_file errors") + } +} + +// 远端名称逃逸出本地根 → 记 failed，不落盘（resolveLocalTarget 二次确认）。 +func TestDrivePull_escapingRelPathIsFailed(t *testing.T) { + root := t.TempDir() + // 远端目录名合法，但目录内的软链把落盘点指到根目录外。 + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + if tool != "list_files" { + return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil + } + switch args["parentId"] { + case "ROOT": + return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`, nil + case "SUB": + return `{"result":{"items":[{"name":"leaked.txt","type":"file","fileId":"L"}],"nextToken":""}}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("leak"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected symlink escape to be reported as failure") + } + if _, err := os.Stat(filepath.Join(outside, "leaked.txt")); !os.IsNotExist(err) { + t.Error("file escaped the local root") + } +} + +// 目标父目录不可创建（同名常规文件占位）→ failed，不 panic。 +func TestPullOneFile_mkdirFailureIsFailed(t *testing.T) { + root := t.TempDir() + // "sub" 是普通文件，MkdirAll("sub") 必然失败。 + mustWrite(t, filepath.Join(root, "sub"), "occupied") + + prevDeps := deps + prevArgs := os.Args + deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { + deps = prevDeps + os.Args = prevArgs + }) + + rf := &remoteFile{RelPath: "sub/x.txt", FileID: "X"} + action, err := pullOneFile(context.Background(), "", rf, filepath.Join(root, "sub", "x.txt"), ifExistsOverwrite) + if action != pullActionFailed || err == nil { + t.Fatalf("action=%q err=%v, want failed + error", action, err) + } +} + +// 探测目录不存在时 isCaseInsensitiveFS 回退平台默认，不 panic。 +func TestIsCaseInsensitiveFS_missingDirFallsBackToPlatformDefault(t *testing.T) { + missing := filepath.Join(t.TempDir(), "absent") + // 只断言不 panic 且返回布尔（具体值取决于平台默认）。 + _ = isCaseInsensitiveFS(missing) +} diff --git a/internal/helpers/drive_push_coverage_test.go b/internal/helpers/drive_push_coverage_test.go new file mode 100644 index 00000000..1b2774f6 --- /dev/null +++ b/internal/helpers/drive_push_coverage_test.go @@ -0,0 +1,463 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "strconv" + "strings" + "testing" +) + +var errTestUpload = errors.New("simulated upload failure") + +// pushOKCaller 是 push 的“一切正常”mock：list_files 按 parentId 返回远端现状， +// create_folder 返回新 fileId，get_upload_info 返回可解析凭证，ln 提交成功。 +func pushOKCaller(listing map[string]string) *driveScriptCaller { + return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + switch tool { + case "list_files": + parent, _ := args["parentId"].(string) + if body, ok := listing[parent]; ok { + return body, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + case "create_folder": + return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil + case "get_upload_info": + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + } + return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil + }} +} + +func withNoopPut(t *testing.T) { + t.Helper() + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) + t.Cleanup(func() { SetHTTPPutFile(nil) }) +} + +// ────────────────────────────────────────────────────────── +// runDrivePush — 端到端 +// ────────────────────────────────────────────────────────── + +// 本地子目录在远端缺失 → 按需 create_folder 并留 folder_created 痕迹，再上传其中文件。 +func TestDrivePush_createsMissingRemoteFolders(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withNoopPut(t) + + caller := pushOKCaller(map[string]string{"ROOT": `{"result":{"items":[],"nextToken":""}}`}) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + cf := caller.callsFor("create_folder") + if len(cf) != 1 || cf[0].args["name"] != "sub" { + t.Fatalf("expected create_folder(sub), got %v", cf) + } + if cf[0].args["parentId"] != "ROOT" { + t.Errorf("create_folder parentId = %v, want ROOT", cf[0].args["parentId"]) + } + // 新建目录的 fileId 必须成为其中文件的 parentId。 + up := caller.callsFor("get_upload_info") + if len(up) != 1 || up[0].args["parentId"] != "NEWDIR" { + t.Errorf("upload parentId = %v, want NEWDIR", up[0].args["parentId"]) + } +} + +// 远端已存在同名目录 → 复用其 fileId，不重建、不出现在 items[]。 +func TestDrivePush_reusesExistingRemoteFolder(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"EXISTING"}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("create_folder"); len(got) != 0 { + t.Errorf("existing remote folder must not be recreated, got %v", got) + } + if up := caller.callsFor("get_upload_info"); up[0].args["parentId"] != "EXISTING" { + t.Errorf("upload parentId = %v, want EXISTING", up[0].args["parentId"]) + } +} + +// create_folder 失败 / 未返回 fileId → 该目录记 failed，其中文件因父目录缺失也 failed。 +func TestDrivePush_folderCreationFailureCascades(t *testing.T) { + for _, tc := range []struct { + name string + reply func(string, map[string]any, int) (string, error) + }{ + {"tool error", func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "create_folder" { + return "", errors.New("create_folder boom") + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }}, + {"no fileId", func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "create_folder" { + return `{"result":{},"success":true}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }}, + } { + t.Run(tc.name, func(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withNoopPut(t) + + caller := &driveScriptCaller{reply: tc.reply} + err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT") + var pf *drivePushFailure + if !errors.As(err, &pf) { + t.Fatalf("expected drivePushFailure, got %T %v", err, err) + } + // 目录 + 其中文件各记一次失败。 + if pf.failed != 2 { + t.Errorf("failed = %d, want 2 (folder + orphaned file)", pf.failed) + } + if got := caller.callsFor("get_upload_info"); len(got) != 0 { + t.Errorf("no upload may happen without a parent folder, got %v", got) + } + }) + } +} + +// --if-exists skip（默认）：远端已存在 → 跳过，不上传。 +func TestDrivePush_ifExistsSkipIsDefault(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("get_upload_info"); len(got) != 0 { + t.Errorf("default skip must not upload, got %v", got) + } +} + +// --if-exists smart：远端时间已 ≥ 本地 → 跳过；远端更旧 → 覆盖上传。 +func TestDrivePush_ifExistsSmart(t *testing.T) { + t.Run("remote newer skips", func(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "a.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + + strconv.FormatInt(local+60000, 10) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("get_upload_info"); len(got) != 0 { + t.Errorf("smart must skip when remote is newer, got %v", got) + } + }) + + t.Run("remote older overwrites in place", func(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "a.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + + strconv.FormatInt(local-60000, 10) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + up := caller.callsFor("get_upload_info") + if len(up) != 1 || up[0].args["overwriteFileId"] != "A" { + t.Fatalf("smart overwrite must pass overwriteFileId=A, got %v", up) + } + if _, has := up[0].args["parentId"]; has { + t.Error("overwrite upload must not carry parentId") + } + }) + + t.Run("remote time invalid overwrites", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + withNoopPut(t) + + // 远端无 modifyTime → 时间不可信，smart 不敢跳过，走覆盖。 + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if up := caller.callsFor("get_upload_info"); len(up) != 1 { + t.Fatalf("expected overwrite upload, got %v", up) + } + }) +} + +// 上传失败 → 记 failed 并以非零退出码退出，结构化结果仍打印。 +func TestDrivePush_uploadFailureExitsNonZero(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) + t.Cleanup(func() { SetHTTPPutFile(nil) }) + + caller := pushOKCaller(nil) + err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT") + var pf *drivePushFailure + if !errors.As(err, &pf) || pf.failed != 1 { + t.Fatalf("expected 1 push failure, got %T %v", err, err) + } +} + +// --if-exists 非法值直接拒绝。 +func TestDrivePush_invalidIfExistsRejected(t *testing.T) { + err := runDriveCmd(t, pushOKCaller(nil), "push", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--if-exists", "bogus") + if err == nil || !strings.Contains(err.Error(), "--if-exists") { + t.Fatalf("expected --if-exists rejection, got %v", err) + } +} + +// space-id 必须透传到 create_folder / get_upload_info / ln 三处。 +func TestDrivePush_passesSpaceIDEverywhere(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "a.txt"), "x") + withNoopPut(t) + + caller := pushOKCaller(nil) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--space-id", "SP7"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + for _, tool := range []string{"list_files", "create_folder", "get_upload_info"} { + calls := caller.callsFor(tool) + if len(calls) == 0 { + t.Fatalf("%s was never called", tool) + } + if calls[0].args["spaceId"] != "SP7" { + t.Errorf("%s spaceId = %v, want SP7", tool, calls[0].args["spaceId"]) + } + } +} + +// 远端列举失败 → push 直接报错，不做任何上传。 +func TestDrivePush_remoteListFailurePropagates(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "x") + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected remote listing failure to propagate") + } +} + +// 本地根目录不存在 → 扫描失败。 +func TestDrivePush_missingLocalRootFails(t *testing.T) { + missing := filepath.Join(t.TempDir(), "absent") + err := runDriveCmd(t, pushOKCaller(nil), "push", "--local-folder", missing, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "扫描本地目录失败") { + t.Fatalf("expected local scan failure, got %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// walkRemoteForPush — 分页、递归、深度上限、非法/空名跳过 +// ────────────────────────────────────────────────────────── + +func TestWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) { + // 递归会插在 ROOT 的两页之间，所以按 (parentId, nextToken) 判定而非调用序号。 + caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) { + parent, _ := args["parentId"].(string) + token, _ := args["nextToken"].(string) + if parent == "SUB" { + return `{"result":{"items":[{"name":"deep.txt","type":"file","fileId":"D"}],"nextToken":""}}`, nil + } + if parent == "ROOT" && token == "" { + return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":"P2"}}`, nil + } + if parent == "ROOT" && token == "P2" { + return `{"result":{"items":[` + + `{"name":"","type":"file","fileId":"EMPTY"},` + + `{"name":"../bad.txt","type":"file","fileId":"BAD"},` + + `{"name":"ok.txt","type":"file","fileId":"OK"}` + + `],"nextToken":""}}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + files, folders, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if _, ok := folders["sub"]; !ok { + t.Error("sub folder must be indexed") + } + if _, ok := files["sub/deep.txt"]; !ok { + t.Error("nested file must be indexed with joined rel_path") + } + if _, ok := files["ok.txt"]; !ok { + t.Error("second page file must be indexed") + } + for _, bad := range []string{"", "../bad.txt"} { + if _, ok := files[bad]; ok { + t.Errorf("unsafe/empty name %q must be skipped", bad) + } + } +} + +func TestWalkRemoteForPush_depthLimitAborts(t *testing.T) { + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil + }} + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + if _, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT"); err == nil || + !strings.Contains(err.Error(), "循环引用") { + t.Fatalf("expected depth-limit abort, got %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// walkLocalForPush — 非常规文件与错误分支 +// ────────────────────────────────────────────────────────── + +func TestWalkLocalForPush_skipsIrregularAndMissingRoot(t *testing.T) { + if _, _, err := walkLocalForPush(filepath.Join(t.TempDir(), "absent")); err == nil { + t.Fatal("expected error for missing root") + } + + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "real.txt"), "x") + if err := os.Symlink(filepath.Join(dir, "absent"), filepath.Join(dir, "dangling")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + _, files, err := walkLocalForPush(dir) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + for _, f := range files { + if f.RelPath == "dangling" { + t.Error("dangling symlink must not be pushed") + } + } +} + +// ────────────────────────────────────────────────────────── +// pushUploadFile — 凭证解析与提交失败分支 +// ────────────────────────────────────────────────────────── + +func TestPushUploadFile_failureBranches(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "a.txt") + mustWrite(t, p, "payload") + + cases := []struct { + name string + reply func(string, map[string]any, int) (string, error) + put func(context.Context, string, map[string]string, string, int64) error + }{ + {"get_upload_info tool error", + func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "get_upload_info" { + return "", errTestUpload + } + return `{"result":{},"success":true}`, nil + }, nil}, + {"unparsable upload credential", + func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "get_upload_info" { + return `{"result":{}}`, nil // 无 resourceUrls + } + return `{"result":{},"success":true}`, nil + }, nil}, + {"oss put fails", + func(string, map[string]any, int) (string, error) { + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + }, + func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }}, + {"commit fails", + func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "get_upload_info" { + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + } + return "", errTestUpload + }, nil}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: &driveScriptCaller{reply: tc.reply}, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + put := tc.put + if put == nil { + put = func(context.Context, string, map[string]string, string, int64) error { return nil } + } + SetHTTPPutFile(put) + t.Cleanup(func() { + deps, os.Args = prevDeps, prevArgs + SetHTTPPutFile(nil) + }) + + if err := pushUploadFile(context.Background(), "SP", "PARENT", "", "a.txt", p, 7); err == nil { + t.Fatal("expected upload failure") + } + }) + } +} + +// pushCreateFolder：MCP 失败上抛，成功时从返回体提取 fileId。 +func TestPushCreateFolder_errorAndSuccess(t *testing.T) { + prevDeps, prevArgs := deps, os.Args + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + deps = &Deps{Caller: &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + return "", errTestUpload + }}, Out: &Formatter{w: io.Discard}} + if _, err := pushCreateFolder(context.Background(), "", "P", "n"); err == nil { + t.Fatal("expected create_folder error to propagate") + } + + ok := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + return `{"result":{"fileId":"FID42"},"success":true}`, nil + }} + deps = &Deps{Caller: ok, Out: &Formatter{w: io.Discard}} + got, err := pushCreateFolder(context.Background(), "SP", "P", "n") + if err != nil || got != "FID42" { + t.Fatalf("pushCreateFolder = (%q, %v), want (FID42, nil)", got, err) + } + if ok.calls[0].args["spaceId"] != "SP" || ok.calls[0].args["parentId"] != "P" { + t.Errorf("create_folder args = %v", ok.calls[0].args) + } +} diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go new file mode 100644 index 00000000..e999a6a6 --- /dev/null +++ b/internal/helpers/drive_status_coverage_test.go @@ -0,0 +1,341 @@ +package helpers + +import ( + "context" + "encoding/json" + "errors" + "io" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +// ────────────────────────────────────────────────────────── +// driveScriptCaller — 可编程 MCP mock：按 (toolName, 第几次调用) 决定返回， +// 覆盖分页、递归、错误分支等 walkRemoteDir / runDriveStatus 路径。 +// ────────────────────────────────────────────────────────── + +type driveScriptCaller struct { + calls []driveMCPCall + reply func(toolName string, args map[string]any, nth int) (string, error) + dryRun bool +} + +func (m *driveScriptCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) { + nth := 0 + for _, c := range m.calls { + if c.toolName == toolName { + nth++ + } + } + m.calls = append(m.calls, driveMCPCall{toolName: toolName, args: args}) + text, err := m.reply(toolName, args, nth) + if err != nil { + return nil, err + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil +} + +func (m *driveScriptCaller) Format() string { return "raw" } +func (m *driveScriptCaller) DryRun() bool { return m.dryRun } +func (m *driveScriptCaller) Fields() string { return "" } +func (m *driveScriptCaller) JQ() string { return "" } + +func (m *driveScriptCaller) callsFor(tool string) []driveMCPCall { + var out []driveMCPCall + for _, c := range m.calls { + if c.toolName == tool { + out = append(out, c) + } + } + return out +} + +var errTestList = errors.New("list_files boom") + +// runDriveCmd 以给定 caller 执行 `dws drive `，返回命令错误。 +func runDriveCmd(t *testing.T, caller edition.ToolCaller, args ...string) error { + t.Helper() + + prevDeps := deps + prevOSArgs := os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + + os.Args = append([]string{"dws", "drive"}, args...) + root.SetArgs(append([]string{"drive"}, args...)) + + t.Cleanup(func() { + deps = prevDeps + os.Args = prevOSArgs + }) + return root.Execute() +} + +// ────────────────────────────────────────────────────────── +// runDriveStatus — 端到端：本地 + 远端树 → diff +// ────────────────────────────────────────────────────────── + +// 端到端 status：递归进入子文件夹、拼接 rel_path、跳过非 file 类型。 +func TestDriveStatus_endToEndNestedTree(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "root.txt"), "r") + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "nested.txt"), "n") + + caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) { + switch args["parentId"] { + case "ROOT": + return `{"result":{"items":[` + + `{"name":"root.txt","type":"file","fileId":"R1","modifyTime":1000},` + + `{"name":"sub","type":"folder","fileId":"SUB"},` + + `{"name":"online.adoc","type":"document","fileId":"D1"},` + + `{"name":"","type":"file","fileId":"EMPTY"},` + + `{"name":"../escape.txt","type":"file","fileId":"BAD"}` + + `],"nextToken":""}}`, nil + case "SUB": + return `{"result":{"items":[{"name":"nested.txt","type":"file","fileId":"N1","modifyTime":2000}],"nextToken":""}}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + + if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // 递归进入 sub 一次；空名/非法名/在线文档都不产生额外调用。 + if got := len(caller.callsFor("list_files")); got != 2 { + t.Errorf("expected 2 list_files calls (ROOT + SUB), got %d", got) + } +} + +// 分页：首页返回 nextToken，第二页取完；token 未推进时必须终止而非死循环。 +func TestDriveStatus_paginationAndStalledToken(t *testing.T) { + dir := t.TempDir() + + caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) { + switch nth { + case 0: + if _, ok := args["nextToken"]; ok { + t.Error("first page must not carry nextToken") + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}],"nextToken":"T1"}}`, nil + case 1: + if args["nextToken"] != "T1" { + t.Errorf("second page nextToken = %v, want T1", args["nextToken"]) + } + // 返回同一个 token → 未推进，必须 break。 + return `{"result":{"items":[{"name":"b.txt","type":"file","fileId":"B"}],"nextToken":"T1"}}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + + if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := len(caller.callsFor("list_files")); got != 2 { + t.Fatalf("stalled token must stop paging after 2 calls, got %d", got) + } +} + +// space-id 显式传入时必须透传到 list_files。 +func TestDriveStatus_passesSpaceID(t *testing.T) { + dir := t.TempDir() + caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--space-id", "SP1"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("list_files")[0].args["spaceId"]; got != "SP1" { + t.Errorf("spaceId = %v, want SP1", got) + } +} + +// list_files 失败 → status 直接报错。 +func TestDriveStatus_listFailurePropagates(t *testing.T) { + dir := t.TempDir() + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} + if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected list_files error to propagate") + } +} + +// 返回体无法解析 → status 报解析失败。 +func TestDriveStatus_unparsableListPropagates(t *testing.T) { + dir := t.TempDir() + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + return `{"result":"not-a-list"}`, nil + }} + err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "list_files") { + t.Fatalf("expected list_files parse error, got %v", err) + } +} + +// exact 模式下本地文件不可读 → MD5 计算失败要作为错误上抛，不能静默当成一致。 +func TestDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) { + if runtime.GOOS == "windows" || os.Geteuid() == 0 { + t.Skip("chmod-based unreadable file needs POSIX perms and a non-root user") + } + dir := t.TempDir() + p := filepath.Join(dir, "secret.txt") + mustWrite(t, p, "data") + if err := os.Chmod(p, 0o000); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(p, 0o644) }) + + caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { + return `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`, nil + }} + err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "MD5") { + t.Fatalf("expected MD5 failure, got %v", err) + } +} + +// --local-folder 不是绝对路径 → 校验拦下，不发起任何 MCP 调用。 +func TestDriveStatus_relativeLocalFolderRejected(t *testing.T) { + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + t.Error("must not call MCP when --local-folder is rejected") + return "", nil + }} + if err := runDriveCmd(t, caller, "status", "--local-folder", "relative/path", "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected relative --local-folder to be rejected") + } +} + +// ────────────────────────────────────────────────────────── +// walkRemoteDir — 深度上限 +// ────────────────────────────────────────────────────────── + +// 远端目录自引用时深度上限必须中止遍历，避免无限递归。 +func TestWalkRemoteDir_depthLimitAborts(t *testing.T) { + caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { + // 每层都返回一个同名子文件夹 → 无限深。 + return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil + }} + prevDeps := deps + prevOSArgs := os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} // 工具路由需要命令上下文 + t.Cleanup(func() { + deps = prevDeps + os.Args = prevOSArgs + }) + + _, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true) + if err == nil || !strings.Contains(err.Error(), "循环引用") { + t.Fatalf("expected depth-limit abort, got %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// isSafeRemoteSegment / resolveLocalTarget 的剩余分支 +// ────────────────────────────────────────────────────────── + +func TestIsSafeRemoteSegment_volumeAndNonCanonical(t *testing.T) { + if runtime.GOOS == "windows" { + if isSafeRemoteSegment(`C:name.txt`) { + t.Error("volume-qualified name must be rejected") + } + } + // 非规范形式（Clean 后不等于自身）必须拒绝。 + for _, name := range []string{"./a.txt", "a/../b.txt", "a//b.txt"} { + if isSafeRemoteSegment(name) { + t.Errorf("non-canonical %q must be rejected", name) + } + } +} + +// ────────────────────────────────────────────────────────── +// md5File / walkLocalTree 错误分支 +// ────────────────────────────────────────────────────────── + +func TestMD5File_missingFile(t *testing.T) { + if _, err := md5File(filepath.Join(t.TempDir(), "nope.bin")); err == nil { + t.Fatal("expected error for missing file") + } +} + +func TestMD5File_directoryIsNotReadable(t *testing.T) { + // 目录不是常规文件：io.Copy 读取时必然报错。 + if _, err := md5File(t.TempDir()); err == nil { + t.Fatal("expected error when hashing a directory") + } +} + +func TestWalkLocalTree_missingRootErrors(t *testing.T) { + if _, err := walkLocalTree(filepath.Join(t.TempDir(), "absent")); err == nil { + t.Fatal("expected error for missing local root") + } +} + +// 非常规文件（FIFO/符号链接目标缺失等）不计入本地索引。 +func TestWalkLocalTree_skipsIrregularEntries(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "real.txt"), "x") + if err := os.Symlink(filepath.Join(dir, "absent"), filepath.Join(dir, "dangling")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + got, err := walkLocalTree(dir) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if _, ok := got["dangling"]; ok { + t.Error("dangling symlink must not be indexed") + } + if _, ok := got["real.txt"]; !ok { + t.Error("regular file must be indexed") + } +} + +// ────────────────────────────────────────────────────────── +// toMillis 的 json.Number / float64 分支 +// ────────────────────────────────────────────────────────── + +func TestDriveItem_modifiedMillisFromNumericForms(t *testing.T) { + if got, ok := (driveItem{"modifyTime": float64(1500)}).modifiedMillis(); !ok || got != 1500 { + t.Errorf("float64 modifyTime = (%d,%v), want (1500,true)", got, ok) + } + if got, ok := (driveItem{"modifyTime": json.Number("2500")}).modifiedMillis(); !ok || got != 2500 { + t.Errorf("json.Number modifyTime = (%d,%v), want (2500,true)", got, ok) + } + if _, ok := (driveItem{"modifyTime": json.Number("nope")}).modifiedMillis(); ok { + t.Error("malformed json.Number modifyTime must be invalid") + } + if _, ok := (driveItem{"modifyTime": float64(0)}).modifiedMillis(); ok { + t.Error("non-positive modifyTime must be invalid") + } + if _, ok := (driveItem{}).modifiedMillis(); ok { + t.Error("missing modifyTime must be invalid") + } +} + +// fileSize 的 float64 / json.Number 两种形态，以及缺失时的兜底。 +func TestDriveItem_sizeForms(t *testing.T) { + if got := (driveItem{"fileSize": float64(42)}).size(); got != 42 { + t.Errorf("float fileSize = %d, want 42", got) + } + if got := (driveItem{"fileSize": json.Number("77")}).size(); got != 77 { + t.Errorf("json.Number fileSize = %d, want 77", got) + } + if got := (driveItem{"fileSize": json.Number("not-a-number")}).size(); got != 0 { + t.Errorf("malformed json.Number fileSize = %d, want 0", got) + } + if got := (driveItem{}).size(); got != 0 { + t.Errorf("missing fileSize = %d, want 0", got) + } +} diff --git a/internal/helpers/drive_sync_coverage_test.go b/internal/helpers/drive_sync_coverage_test.go new file mode 100644 index 00000000..069e89bc --- /dev/null +++ b/internal/helpers/drive_sync_coverage_test.go @@ -0,0 +1,412 @@ +package helpers + +import ( + "context" + "errors" + "os" + "path/filepath" + "strconv" + "strings" + "testing" +) + +// syncCaller 组合 push 与 pull 两侧：list_files 按 parentId 返回远端现状， +// create_folder / get_upload_info / ln 走 push 路径，download_file 走 pull 路径。 +func syncCaller(listing map[string]string) *driveScriptCaller { + return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + switch tool { + case "list_files": + parent, _ := args["parentId"].(string) + if body, ok := listing[parent]; ok { + return body, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + case "create_folder": + return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil + case "get_upload_info": + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + case "download_file": + return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil + } + return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil + }} +} + +// withSyncTransport 注入成功的上传与下载。 +func withSyncTransport(t *testing.T, body string) { + t.Helper() + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte(body), 0o644) + }) + t.Cleanup(func() { + SetHTTPPutFile(nil) + SetHTTPGetFile(nil) + }) +} + +// ────────────────────────────────────────────────────────── +// --on-conflict 取值处理 +// ────────────────────────────────────────────────────────── + +// 显式传空 --on-conflict 时回落默认 remote-wins（而非报非法取值）。 +func TestDriveSync_emptyOnConflictDefaultsToRemoteWins(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-old") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote-new") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", + "--quick", "--on-conflict", ""); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "remote-new" { + t.Errorf("empty --on-conflict must behave as remote-wins, got %q", string(b)) + } +} + +func TestDriveSync_invalidOnConflictRejected(t *testing.T) { + err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", t.TempDir(), + "--remote-folder", "ROOT", "--on-conflict", "bogus") + if err == nil || !strings.Contains(err.Error(), "--on-conflict") { + t.Fatalf("expected --on-conflict rejection, got %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// unchanged / unknown 分类 +// ────────────────────────────────────────────────────────── + +// quick 模式下两侧 mtime 相同 → unchanged，不做任何读写。 +func TestDriveSync_unchangedIsUntouched(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "same.txt") + mustWrite(t, p, "identical") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "should-not-be-used") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"same.txt","type":"file","fileId":"S","modifyTime":` + + strconv.FormatInt(local, 10) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 { + t.Errorf("unchanged file must not be transferred, got %d write calls", got) + } + if b, _ := os.ReadFile(p); string(b) != "identical" { + t.Errorf("unchanged file was modified: %q", string(b)) + } +} + +// exact 模式远端无可靠 md5 → unknown，一律计入 skipped 且不动任何一侧。 +func TestDriveSync_unknownIsSkipped(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "u.txt") + mustWrite(t, p, "local") + withSyncTransport(t, "remote") + + // 无 md5 字段 → exact 模式无法核对内容。 + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"u.txt","type":"file","fileId":"U","modifyTime":1}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 { + t.Errorf("unknown must not be transferred, got %d write calls", got) + } + if b, _ := os.ReadFile(p); string(b) != "local" { + t.Errorf("unknown file was modified: %q", string(b)) + } +} + +// exact 模式下本地不可读 → judgeFileMatch 的 MD5 失败要中止整个 sync。 +func TestDriveSync_md5FailureAborts(t *testing.T) { + if os.Geteuid() == 0 { + t.Skip("chmod-based unreadable file needs a non-root user") + } + dir := t.TempDir() + p := filepath.Join(dir, "secret.txt") + mustWrite(t, p, "data") + if err := os.Chmod(p, 0o000); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(p, 0o644) }) + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected MD5 failure to abort sync") + } +} + +// ────────────────────────────────────────────────────────── +// new_local 推送：按需建目录 +// ────────────────────────────────────────────────────────── + +// 本地子目录在远端缺失 → 建目录（记 folder_created + pushed）再上传其中文件。 +func TestDriveSync_createsRemoteFolderForNewLocal(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withSyncTransport(t, "unused") + + caller := syncCaller(nil) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + cf := caller.callsFor("create_folder") + if len(cf) != 1 || cf[0].args["name"] != "sub" { + t.Fatalf("expected create_folder(sub), got %v", cf) + } + up := caller.callsFor("get_upload_info") + if len(up) != 1 || up[0].args["parentId"] != "NEWDIR" { + t.Errorf("upload parentId = %v, want NEWDIR", up[0].args["parentId"]) + } +} + +// 远端已有同名目录 → 复用，不重建。 +func TestDriveSync_reusesExistingRemoteFolder(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withSyncTransport(t, "unused") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"EXISTING"}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("create_folder"); len(got) != 0 { + t.Errorf("existing folder must be reused, got %v", got) + } +} + +// create_folder 失败 → 目录与其中文件都记 failed，命令非零退出。 +func TestDriveSync_folderCreationFailureCascades(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "deep.txt"), "d") + withSyncTransport(t, "unused") + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "create_folder" { + return "", errors.New("create_folder boom") + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick") + var sf *driveSyncFailure + if !errors.As(err, &sf) || sf.failed != 2 { + t.Fatalf("expected 2 failures (folder + orphaned file), got %T %v", err, err) + } +} + +// new_local 上传失败 → 记 failed 并非零退出。 +func TestDriveSync_pushUploadFailureIsFailed(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "only-local.txt"), "x") + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) + t.Cleanup(func() { SetHTTPPutFile(nil) }) + + caller := syncCaller(nil) + err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick") + var sf *driveSyncFailure + if !errors.As(err, &sf) || sf.failed != 1 { + t.Fatalf("expected 1 push failure, got %T %v", err, err) + } +} + +// ────────────────────────────────────────────────────────── +// --on-conflict ask 的每个交互答案 +// ────────────────────────────────────────────────────────── + +func TestDriveSyncAskConflict_answers(t *testing.T) { + cases := []struct { + input string + want string + isErr bool + }{ + {"r\n", syncConflictRemoteWins, false}, + {"remote\n", syncConflictRemoteWins, false}, + {"l\n", syncConflictLocalWins, false}, + {"local-wins\n", syncConflictLocalWins, false}, + {"k\n", syncConflictKeepBoth, false}, + {"keep\n", syncConflictKeepBoth, false}, + {"s\n", "", false}, + {"skip\n", "", false}, + {"\n", syncConflictRemoteWins, false}, // 交互式回车 → 默认远端优先 + {"nonsense\n", "", true}, + } + for _, tc := range cases { + t.Run(strings.TrimSpace(tc.input), func(t *testing.T) { + prev := syncAskStdin + syncAskStdin = strings.NewReader(tc.input) + t.Cleanup(func() { syncAskStdin = prev }) + + got, err := driveSyncAskConflict("f.txt") + if tc.isErr { + if err == nil { + t.Fatalf("expected error for %q", tc.input) + } + return + } + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got != tc.want { + t.Errorf("driveSyncAskConflict(%q) = %q, want %q", tc.input, got, tc.want) + } + }) + } +} + +// ask 选到无效值时整个 sync 中止（错误上抛，不是静默跳过）。 +func TestDriveSync_askInvalidChoiceAborts(t *testing.T) { + prev := syncAskStdin + syncAskStdin = strings.NewReader("nonsense\n") + t.Cleanup(func() { syncAskStdin = prev }) + + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", + "--quick", "--on-conflict", "ask"); err == nil { + t.Fatal("expected invalid ask choice to abort sync") + } +} + +// ask 选 keep-both：本地改名保留副本，远端拉到原名。 +func TestDriveSync_askKeepBothViaStdin(t *testing.T) { + prev := syncAskStdin + syncAskStdin = strings.NewReader("k\n") + t.Cleanup(func() { syncAskStdin = prev }) + + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-version") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote-version") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"FID12345678","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", + "--quick", "--on-conflict", "ask"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "remote-version" { + t.Errorf("original path must hold the remote version, got %q", string(b)) + } + // 本地副本以 .conflict- 保留。 + entries, _ := os.ReadDir(dir) + var found bool + for _, e := range entries { + if strings.Contains(e.Name(), ".conflict-") { + found = true + if b, _ := os.ReadFile(filepath.Join(dir, e.Name())); string(b) != "local-version" { + t.Errorf("conflict copy content = %q, want local-version", string(b)) + } + } + } + if !found { + t.Errorf("no .conflict-* copy kept, dir = %v", entries) + } +} + +// keep-both 改名失败（目标被目录占位）→ 记 failed，本地原文件保持不动。 +func TestDriveSync_keepBothRenameFailureKeepsLocal(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-version") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote-version") + + // 让候选改名目标 f.conflict-FID12345.txt 被一个目录占住 → O_EXCL 建占位失败。 + if err := os.MkdirAll(filepath.Join(dir, "f.conflict-ID123456.txt"), 0o755); err != nil { + t.Fatal(err) + } + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"FID123456","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + // 无论走到哪个失败分支，本地原文件都不能被破坏。 + _ = runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", + "--quick", "--on-conflict", "keep-both") + if _, err := os.Stat(p); err != nil { + t.Fatalf("local file must still exist: %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// dry-run 与 unknown 组合 +// ────────────────────────────────────────────────────────── + +// dry-run 下即使有 new_local / new_remote / modified 也不产生任何写调用。 +func TestDriveSync_dryRunSkipsEveryWrite(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "l") + p := filepath.Join(dir, "both.txt") + mustWrite(t, p, "local") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[` + + `{"name":"both.txt","type":"file","fileId":"B","modifyTime":` + differentMillis(local) + `},` + + `{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2000}` + + `],"nextToken":""}}`, + }) + caller.dryRun = true + + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")) + + len(caller.callsFor("create_folder")); got != 0 { + t.Errorf("dry-run must not write, got %d calls", got) + } + if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) { + t.Error("dry-run must not materialize remote files locally") + } +} + +// 远端列举失败 → sync 直接报错。 +func TestDriveSync_remoteListFailurePropagates(t *testing.T) { + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} + if err := runDriveCmd(t, caller, "sync", "--local-folder", t.TempDir(), "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected remote listing failure to propagate") + } +} + +// 本地根目录不存在 → 扫描失败上抛。 +func TestDriveSync_missingLocalRootFails(t *testing.T) { + missing := filepath.Join(t.TempDir(), "absent") + if err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", missing, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected missing local root to fail") + } +} diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go new file mode 100644 index 00000000..99f5ab3f --- /dev/null +++ b/internal/helpers/drive_sync_edges_test.go @@ -0,0 +1,302 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/spf13/cobra" +) + +var errTestRead = errors.New("simulated read failure") + +// errReader 让 bufio 读取返回非 EOF 错误，覆盖 ask 的读取失败分支。 +type errReader struct{} + +func (errReader) Read([]byte) (int, error) { return 0, errTestRead } + +// findDriveSubcommand 取出 drive 下的指定子命令，便于直接调用其 RunE。 +func findDriveSubcommand(t *testing.T, name string) *cobra.Command { + t.Helper() + for _, c := range newDriveCommand().Commands() { + if c.Name() == name { + return c + } + } + t.Fatalf("drive subcommand %q not found", name) + return nil +} + +// mustSetFlags 设置一组 flag，任何失败都直接终止用例。 +func mustSetFlags(t *testing.T, cmd *cobra.Command, kv map[string]string) { + t.Helper() + for k, v := range kv { + if err := cmd.Flags().Set(k, v); err != nil { + t.Fatalf("set --%s=%s: %v", k, v, err) + } + } +} + +// ────────────────────────────────────────────────────────── +// --if-exists 显式空值回落默认 +// ────────────────────────────────────────────────────────── + +func TestDrivePull_emptyIfExistsDefaultsToOverwrite(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "a.txt") + mustWrite(t, p, "local-old") + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("remote-new"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", ""); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "remote-new" { + t.Errorf("empty --if-exists must behave as overwrite, got %q", string(b)) + } +} + +func TestDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", ""); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := caller.callsFor("get_upload_info"); len(got) != 0 { + t.Errorf("empty --if-exists must behave as skip, got %v", got) + } +} + +// ────────────────────────────────────────────────────────── +// pullOneFile 的落盘失败分支 +// ────────────────────────────────────────────────────────── + +// 目标目录不可写 → 创建临时文件失败。 +func TestPullOneFile_tempFileCreationFailure(t *testing.T) { + if runtime.GOOS == "windows" || os.Geteuid() == 0 { + t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") + } + root := t.TempDir() + if err := os.Chmod(root, 0o500); err != nil { // r-x：可遍历不可写 + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"}, + filepath.Join(root, "a.txt"), ifExistsOverwrite) + if action != pullActionFailed || err == nil { + t.Fatalf("action=%q err=%v, want failed + error", action, err) + } +} + +// 目标路径是目录 → 最后的原子 rename 失败。 +func TestPullOneFile_renameOntoDirectoryFails(t *testing.T) { + root := t.TempDir() + target := filepath.Join(root, "a.txt") + if err := os.MkdirAll(target, 0o755); err != nil { // 目标被目录占位 + t.Fatal(err) + } + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("payload"), 0o644) + }) + t.Cleanup(func() { + deps, os.Args = prevDeps, prevArgs + SetHTTPGetFile(nil) + }) + + action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"}, + target, ifExistsOverwrite) + if action != pullActionFailed || err == nil { + t.Fatalf("action=%q err=%v, want failed + error", action, err) + } +} + +// ────────────────────────────────────────────────────────── +// PrintJSON 失败分支 +// ────────────────────────────────────────────────────────── + +func TestDrivePush_printFailurePropagates(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "x") + withNoopPut(t) + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: pushOKCaller(nil), Out: &Formatter{w: failingWriter{}}} + os.Args = []string{"dws", "drive", "push"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + cmd := findDriveSubcommand(t, "push") + mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) + if err := runDrivePush(cmd, nil); err == nil { + t.Fatal("expected the PrintJSON writer failure to propagate") + } +} + +func TestDriveSync_printFailurePropagates(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "x") + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) + t.Cleanup(func() { SetHTTPPutFile(nil) }) + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: failingWriter{}}} + os.Args = []string{"dws", "drive", "sync"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + cmd := findDriveSubcommand(t, "sync") + mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT", "quick": "true"}) + if err := runDriveSync(cmd, nil); err == nil { + t.Fatal("expected the PrintJSON writer failure to propagate") + } +} + +// ────────────────────────────────────────────────────────── +// walkLocalForPush / walkLocalTree 的 WalkDir 错误回调 +// ────────────────────────────────────────────────────────── + +func TestWalkLocal_unreadableSubdirectoryErrors(t *testing.T) { + if runtime.GOOS == "windows" || os.Geteuid() == 0 { + t.Skip("unreadable dir needs POSIX perms and a non-root user") + } + dir := t.TempDir() + sub := filepath.Join(dir, "locked") + if err := os.MkdirAll(sub, 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(sub, "inner.txt"), "x") + if err := os.Chmod(sub, 0o000); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(sub, 0o755) }) + + if _, _, err := walkLocalForPush(dir); err == nil { + t.Error("walkLocalForPush must surface the WalkDir error") + } + if _, err := walkLocalTree(dir); err == nil { + t.Error("walkLocalTree must surface the WalkDir error") + } +} + +// ────────────────────────────────────────────────────────── +// verifyNoSymlinkEscape 的剩余分支 +// ────────────────────────────────────────────────────────── + +// 目标位于 absDir 之外 → 走到根目录之上即放行（不是逃逸判定范围）。 +func TestVerifyNoSymlinkEscape_targetOutsideRootIsIgnored(t *testing.T) { + root := t.TempDir() + outside := filepath.Join(t.TempDir(), "elsewhere", "x.txt") + if err := verifyNoSymlinkEscape(root, outside); err != nil { + t.Errorf("target above the root must be ignored, got %v", err) + } +} + +// 已存在路径含符号链接环 → EvalSymlinks 失败要如实上报。 +func TestVerifyNoSymlinkEscape_symlinkLoopErrors(t *testing.T) { + root := t.TempDir() + loop := filepath.Join(root, "loop") + if err := os.Symlink(loop, loop); err != nil { + t.Skipf("self-symlink unsupported: %v", err) + } + err := verifyNoSymlinkEscape(root, filepath.Join(loop, "child.txt")) + if err == nil || !strings.Contains(err.Error(), "解析路径") { + t.Fatalf("expected EvalSymlinks failure, got %v", err) + } +} + +// ────────────────────────────────────────────────────────── +// reserveSyncKeepBothTarget 的失败分支 +// ────────────────────────────────────────────────────────── + +// 候选目标逃逸出本地根（父目录是指向外部的软链）→ 直接失败。 +func TestReserveSyncKeepBothTarget_escapeFails(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + if _, _, err := reserveSyncKeepBothTarget(root, "sub/f.txt", "FID12345678", map[string]bool{}); err == nil { + t.Fatal("expected escaping keep-both target to fail") + } +} + +// 候选目标所在目录不可写 → OpenFile 以非 EEXIST 错误失败，直接上报。 +func TestReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { + if runtime.GOOS == "windows" || os.Geteuid() == 0 { + t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") + } + root := t.TempDir() + if err := os.Chmod(root, 0o500); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + + if _, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", map[string]bool{}); err == nil { + t.Fatal("expected unwritable directory to fail") + } +} + +// occupied 中已知占用的首选候选被跳过，改用下一个后缀。 +func TestReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) { + root := t.TempDir() + first := syncKeepBothCandidate("f.txt", "FID12345678", 0) + occupied := map[string]bool{first: true} + + got, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", occupied) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got == first { + t.Errorf("known-occupied candidate %q must be skipped", first) + } +} + +// ────────────────────────────────────────────────────────── +// ask 读取失败（非 EOF） +// ────────────────────────────────────────────────────────── + +func TestDriveSyncAskConflict_readErrorPropagates(t *testing.T) { + prev := syncAskStdin + syncAskStdin = errReader{} + t.Cleanup(func() { syncAskStdin = prev }) + + if _, err := driveSyncAskConflict("f.txt"); err == nil { + t.Fatal("expected read failure to propagate") + } +} + +// ────────────────────────────────────────────────────────── +// sync：本地根不可创建 +// ────────────────────────────────────────────────────────── + +// --local-folder 指向一个常规文件 → MkdirAll 失败。 +func TestDriveSync_localRootIsFileFails(t *testing.T) { + dir := t.TempDir() + asFile := filepath.Join(dir, "not-a-dir") + mustWrite(t, asFile, "x") + + if err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", asFile, "--remote-folder", "ROOT", "--quick"); err == nil { + t.Fatal("expected a regular-file local root to fail") + } +} From 488411615f712ccf2ff4278ef205e0dfe351a6a4 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 13:38:06 +0800 Subject: [PATCH 007/250] test(drive): cover parent-folder cascades and keep-both rollback paths --- internal/helpers/drive_sync_conflict_test.go | 248 +++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 internal/helpers/drive_sync_conflict_test.go diff --git a/internal/helpers/drive_sync_conflict_test.go b/internal/helpers/drive_sync_conflict_test.go new file mode 100644 index 00000000..148d7d94 --- /dev/null +++ b/internal/helpers/drive_sync_conflict_test.go @@ -0,0 +1,248 @@ +package helpers + +import ( + "context" + "errors" + "io" + "os" + "path/filepath" + "runtime" + "strings" + "testing" +) + +// failFolderCaller 让指定名字的 create_folder 失败，其余一切正常， +// 用于构造「父目录未能创建 → 子目录/子文件连锁失败」。 +func failFolderCaller(failName string) *driveScriptCaller { + return &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + switch tool { + case "list_files": + return `{"result":{"items":[],"nextToken":""}}`, nil + case "create_folder": + if args["name"] == failName { + return "", errors.New("create_folder rejected: " + failName) + } + return `{"result":{"fileId":"NEWDIR"},"success":true}`, nil + case "get_upload_info": + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + case "download_file": + return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil + } + return `{"result":{"fileId":"NEWFILE"},"success":true}`, nil + }} +} + +// mkNested 建出 a/b/deep.txt 结构。 +func mkNested(t *testing.T) string { + t.Helper() + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "a", "b"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "a", "b", "deep.txt"), "d") + return dir +} + +// 顶层目录 a 建失败 → 子目录 a/b 因父目录缺失也 failed，其中文件同样 failed。 +func TestDrivePush_nestedDirFailsWhenParentMissing(t *testing.T) { + dir := mkNested(t) + withNoopPut(t) + + caller := failFolderCaller("a") + err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT") + var pf *drivePushFailure + if !errors.As(err, &pf) { + t.Fatalf("expected drivePushFailure, got %T %v", err, err) + } + // a（建失败）+ a/b（父缺失）+ a/b/deep.txt（父缺失）= 3 + if pf.failed != 3 { + t.Errorf("failed = %d, want 3", pf.failed) + } + if got := caller.callsFor("get_upload_info"); len(got) != 0 { + t.Errorf("nothing may upload without a parent folder, got %v", got) + } +} + +func TestDriveSync_nestedDirFailsWhenParentMissing(t *testing.T) { + dir := mkNested(t) + withNoopPut(t) + + caller := failFolderCaller("a") + err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick") + var sf *driveSyncFailure + if !errors.As(err, &sf) { + t.Fatalf("expected driveSyncFailure, got %T %v", err, err) + } + if sf.failed != 3 { + t.Errorf("failed = %d, want 3", sf.failed) + } +} + +// new_remote 落盘目标经软链逃逸出本地根 → 记 failed，不写到根目录之外。 +func TestDriveSync_newRemoteEscapeIsFailed(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + withSyncTransport(t, "leak") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`, + "SUB": `{"result":{"items":[{"name":"leaked.txt","type":"file","fileId":"L","modifyTime":1}],"nextToken":""}}`, + }) + err := runDriveCmd(t, caller, "sync", "--local-folder", root, "--remote-folder", "ROOT", "--quick") + var sf *driveSyncFailure + if !errors.As(err, &sf) { + t.Fatalf("expected driveSyncFailure, got %T %v", err, err) + } + if _, statErr := os.Stat(filepath.Join(outside, "leaked.txt")); !os.IsNotExist(statErr) { + t.Error("file escaped the local root") + } +} + +// ────────────────────────────────────────────────────────── +// keep-both 的失败与回滚分支 +// ────────────────────────────────────────────────────────── + +// syncKeepBoth 在 rel 逃逸时直接 failed（resolveLocalTarget 报错）。 +func TestSyncKeepBoth_escapingRelIsFailed(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "sub/f.txt", FileID: "FID12345678"}, + root, "sub/f.txt", map[string]bool{}, map[string]bool{}) + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } +} + +// collided 命中时 keep-both 直接 failed，不做任何改名。 +func TestSyncKeepBoth_collidedIsFailed(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "f.txt"), "local") + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, + root, "f.txt", map[string]bool{"f.txt": true}, map[string]bool{}) + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } + if b, _ := os.ReadFile(filepath.Join(root, "f.txt")); string(b) != "local" { + t.Errorf("collided keep-both must not touch the local file, got %q", string(b)) + } +} + +// 占用改名目标失败（目录不可写）→ failed。 +func TestSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { + if runtime.GOOS == "windows" || os.Geteuid() == 0 { + t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") + } + root := t.TempDir() + mustWrite(t, filepath.Join(root, "f.txt"), "local") + if err := os.Chmod(root, 0o500); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, + root, "f.txt", map[string]bool{}, map[string]bool{}) + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } +} + +// 改名本身失败（本地原文件其实是目录）→ failed，并清理刚建的空占位。 +func TestSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { + root := t.TempDir() + // rel 指向一个非空目录：os.Rename(dir, emptyFile) 会失败。 + if err := os.MkdirAll(filepath.Join(root, "f.txt", "inner"), 0o755); err != nil { + t.Fatal(err) + } + res := &driveSyncResult{} + occupied := map[string]bool{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, + root, "f.txt", map[string]bool{}, occupied) + + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } + // 空占位必须被清理，不留残留。 + if _, err := os.Stat(filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))); !os.IsNotExist(err) { + t.Error("empty placeholder must be removed after a failed rename") + } +} + +// 拉取失败 → 回滚改名，本地文件恢复原名与原内容。 +func TestSyncKeepBoth_pullFailureRollsBackRename(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "f.txt") + mustWrite(t, p, "local-version") + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) + t.Cleanup(func() { + deps, os.Args = prevDeps, prevArgs + SetHTTPGetFile(nil) + }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, + root, "f.txt", map[string]bool{}, map[string]bool{}) + + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } + if b, err := os.ReadFile(p); err != nil || string(b) != "local-version" { + t.Fatalf("rename must be rolled back: %v / %q", err, string(b)) + } + if _, err := os.Stat(filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))); !os.IsNotExist(err) { + t.Error("renamed copy must not survive a successful rollback") + } +} + +// 拉取失败且回滚也失败 → 如实上报“本地版本保留为 <改名>”，不谎称成功。 +func TestSyncKeepBoth_rollbackFailureIsReported(t *testing.T) { + root := t.TempDir() + p := filepath.Join(root, "f.txt") + mustWrite(t, p, "local-version") + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + // 下载失败前先把原名占住一个目录，使回滚 rename 无法复原。 + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + if err := os.MkdirAll(filepath.Join(p, "blocker"), 0o755); err != nil { + return err + } + return errTestDownload + }) + t.Cleanup(func() { + deps, os.Args = prevDeps, prevArgs + SetHTTPGetFile(nil) + }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, + root, "f.txt", map[string]bool{}, map[string]bool{}) + + if res.Summary.Failed != 1 { + t.Fatalf("failed = %d, want 1", res.Summary.Failed) + } + if len(res.Items) != 1 || res.Items[0].Action != syncActionFailed { + t.Fatalf("items = %+v", res.Items) + } + // 数据没丢：本地版本仍以改名后的名字存在，且错误信息点明了这一点。 + suffixed := syncKeepBothCandidate("f.txt", "FID12345678", 0) + if b, err := os.ReadFile(filepath.Join(root, suffixed)); err != nil || string(b) != "local-version" { + t.Fatalf("local version must survive as %s: %v / %q", suffixed, err, string(b)) + } + if !strings.Contains(res.Items[0].Error, "回滚改名失败") { + t.Errorf("error must disclose the failed rollback, got %q", res.Items[0].Error) + } +} From f256d7a43c10c29161ded902aceb2e80078cba6a Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 13:57:48 +0800 Subject: [PATCH 008/250] refactor(drive): add case-detection seam, split Windows guards, extract walk callbacks --- internal/helpers/drive_pull.go | 15 +- internal/helpers/drive_push.go | 66 +++--- internal/helpers/drive_status.go | 72 +++---- internal/helpers/drive_status_unix.go | 8 + internal/helpers/drive_status_windows.go | 20 ++ internal/helpers/drive_sync_platform_test.go | 216 +++++++++++++++++++ 6 files changed, 328 insertions(+), 69 deletions(-) create mode 100644 internal/helpers/drive_status_unix.go create mode 100644 internal/helpers/drive_status_windows.go create mode 100644 internal/helpers/drive_sync_platform_test.go diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index f86adac1..3e1d875e 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -82,12 +82,21 @@ func pathCollisionKey(target string, caseInsensitive bool) string { return p } -// isCaseInsensitiveFS 探测 dir 所在文件系统是否大小写不敏感：在 dir 下创建一个随机 +// isCaseInsensitiveFS 是大小写探测的注入点（与 httpGetFile / httpPutFile 同样的 seam）： +// 生产路径始终是 detectCaseInsensitiveFS，测试可替换它，以便在大小写敏感的 CI 文件系统上 +// 也能走到「等价路径冲突」分支。 +var isCaseInsensitiveFS = detectCaseInsensitiveFS + +// caseProbePattern 是探针文件名模板。抽成变量只为可测：纯数字模板的大写与原名相同， +// 可覆盖「名称无大小写差异、无法据此判定」的回退分支。 +var caseProbePattern = "dws-caseprobe-*" + +// detectCaseInsensitiveFS 探测 dir 所在文件系统是否大小写不敏感：在 dir 下创建一个随机 // 小写名探针文件，再用其大写名 stat；命中同一文件即为不敏感。dir 必须已存在。 // 探测失败时回退到平台默认（Windows / macOS 视为不敏感，其它敏感）。 -func isCaseInsensitiveFS(dir string) bool { +func detectCaseInsensitiveFS(dir string) bool { platformDefault := runtime.GOOS == "windows" || runtime.GOOS == "darwin" - f, err := os.CreateTemp(dir, "dws-caseprobe-*") + f, err := os.CreateTemp(dir, caseProbePattern) if err != nil { return platformDefault } diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index 52eb2827..fcce42c5 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -281,36 +281,7 @@ func walkLocalForPush(root string) ([]string, []localPushFile, error) { var dirs []string var files []localPushFile err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { - if err != nil { - return err - } - rel, rerr := filepath.Rel(root, path) - if rerr != nil { - return rerr - } - if rel == "." { - return nil // 根目录本身不处理 - } - relSlash := filepath.ToSlash(rel) - if d.IsDir() { - dirs = append(dirs, relSlash) - return nil - } - info, ierr := d.Info() - if ierr != nil { - return ierr - } - // 只推送常规文件；符号链接、设备文件等忽略。 - if !info.Mode().IsRegular() { - return nil - } - files = append(files, localPushFile{ - RelPath: relSlash, - AbsPath: path, - ModTimeMillis: info.ModTime().UnixMilli(), - Size: info.Size(), - }) - return nil + return walkLocalForPushEntry(root, path, d, err, &dirs, &files) }) if err != nil { return nil, nil, err @@ -320,6 +291,41 @@ func walkLocalForPush(root string) ([]string, []localPushFile, error) { return dirs, files, nil } +// walkLocalForPushEntry 是 walkLocalForPush 的单条目处理逻辑。抽成命名函数只为可测： +// filepath.Rel / Info() 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。 +func walkLocalForPushEntry(root, path string, d fs.DirEntry, err error, dirs *[]string, files *[]localPushFile) error { + if err != nil { + return err + } + rel, rerr := filepath.Rel(root, path) + if rerr != nil { + return rerr + } + if rel == "." { + return nil // 根目录本身不处理 + } + relSlash := filepath.ToSlash(rel) + if d.IsDir() { + *dirs = append(*dirs, relSlash) + return nil + } + info, ierr := d.Info() + if ierr != nil { + return ierr + } + // 只推送常规文件；符号链接、设备文件等忽略。 + if !info.Mode().IsRegular() { + return nil + } + *files = append(*files, localPushFile{ + RelPath: relSlash, + AbsPath: path, + ModTimeMillis: info.ModTime().UnixMilli(), + Size: info.Size(), + }) + return nil +} + // pushCreateFolder 在 parentID 下创建名为 name 的文件夹，返回新目录的 fileId。 func pushCreateFolder(ctx context.Context, spaceID, parentID, name string) (string, error) { args := map[string]any{"name": name} diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 7e43f3db..11239bc7 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -294,15 +294,9 @@ func isSafeRemoteSegment(name string) bool { if strings.ContainsAny(name, `/\`) { return false } - // Windows 卷标（"C:"、"C:foo"）等含盘符的名称一律拒绝。 - if filepath.VolumeName(name) != "" { - return false - } - // Clean 后若发生变化，说明名称非规范（含隐藏的 . / .. / 分隔符）。 - if filepath.Clean(name) != name { - return false - } - return true + // 余下的卷标/规范化检查只在 Windows 上可达：Unix 的 filepath.VolumeName 恒为空， + // 且经上面的分隔符过滤后 filepath.Clean 不会再改写名称。按平台分文件承载。 + return isSafeRemoteSegmentPlatform(name) } // resolveLocalTarget 把远端 rel_path 拼到本地根目录 absDir 下，并确认结果仍位于 @@ -385,33 +379,7 @@ func md5File(path string) (string, error) { func walkLocalTree(root string) (map[string]*localFile, error) { files := make(map[string]*localFile) err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { - if err != nil { - return err - } - if d.IsDir() { - return nil - } - info, err := d.Info() - if err != nil { - return err - } - // 只比对常规文件；符号链接、设备文件等被忽略。 - if !info.Mode().IsRegular() { - return nil - } - rel, err := filepath.Rel(root, path) - if err != nil { - return err - } - relSlash := filepath.ToSlash(rel) - - files[relSlash] = &localFile{ - RelPath: relSlash, - AbsPath: path, - Size: info.Size(), - ModTimeMillis: info.ModTime().UnixMilli(), - } - return nil + return walkLocalTreeEntry(root, path, d, err, files) }) if err != nil { return nil, err @@ -419,6 +387,38 @@ func walkLocalTree(root string) (map[string]*localFile, error) { return files, nil } +// walkLocalTreeEntry 是 walkLocalTree 的单条目处理逻辑。抽成命名函数只为可测： +// Info() / filepath.Rel 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。 +func walkLocalTreeEntry(root, path string, d fs.DirEntry, err error, files map[string]*localFile) error { + if err != nil { + return err + } + if d.IsDir() { + return nil + } + info, err := d.Info() + if err != nil { + return err + } + // 只比对常规文件；符号链接、设备文件等被忽略。 + if !info.Mode().IsRegular() { + return nil + } + rel, err := filepath.Rel(root, path) + if err != nil { + return err + } + relSlash := filepath.ToSlash(rel) + + files[relSlash] = &localFile{ + RelPath: relSlash, + AbsPath: path, + Size: info.Size(), + ModTimeMillis: info.ModTime().UnixMilli(), + } + return nil +} + // 双端都存在文件的比对结论。 const ( matchUnchanged = "unchanged" diff --git a/internal/helpers/drive_status_unix.go b/internal/helpers/drive_status_unix.go new file mode 100644 index 00000000..fa5e9258 --- /dev/null +++ b/internal/helpers/drive_status_unix.go @@ -0,0 +1,8 @@ +//go:build !windows + +package helpers + +// isSafeRemoteSegmentPlatform 在非 Windows 平台没有额外约束：filepath.VolumeName +// 恒为空字符串，而调用方已过滤掉 ""、"."、".." 与任意平台分隔符，剩下的名称 +// filepath.Clean 不会再改写。 +func isSafeRemoteSegmentPlatform(string) bool { return true } diff --git a/internal/helpers/drive_status_windows.go b/internal/helpers/drive_status_windows.go new file mode 100644 index 00000000..b9ef2de4 --- /dev/null +++ b/internal/helpers/drive_status_windows.go @@ -0,0 +1,20 @@ +//go:build windows + +package helpers + +import "path/filepath" + +// isSafeRemoteSegmentPlatform 承载 Windows 专有的单层名称校验。 +// +// 拒绝含盘符的名称（"C:"、"C:foo"）——Windows 上 filepath.VolumeName 会识别它们， +// 拼进 rel_path 后可让落盘目标逃逸出本地根目录；并在 Clean 改写名称时拒绝，兜住 +// 分隔符过滤之外的非规范形式。 +func isSafeRemoteSegmentPlatform(name string) bool { + if filepath.VolumeName(name) != "" { + return false + } + if filepath.Clean(name) != name { + return false + } + return true +} diff --git a/internal/helpers/drive_sync_platform_test.go b/internal/helpers/drive_sync_platform_test.go new file mode 100644 index 00000000..0705b61f --- /dev/null +++ b/internal/helpers/drive_sync_platform_test.go @@ -0,0 +1,216 @@ +package helpers + +import ( + "context" + "errors" + "io/fs" + "os" + "path/filepath" + "runtime" + "testing" + "time" +) + +// forceCaseInsensitiveFS 在当前用例内把大小写探测钉成不敏感，使等价路径冲突分支 +// 在大小写敏感的 CI 文件系统（ext4）上同样可达。 +func forceCaseInsensitiveFS(t *testing.T) { + t.Helper() + prev := isCaseInsensitiveFS + isCaseInsensitiveFS = func(string) bool { return true } + t.Cleanup(func() { isCaseInsensitiveFS = prev }) +} + +// ────────────────────────────────────────────────────────── +// 等价路径冲突：pull / sync 都必须全部记 failed 且一个都不落盘 +// ────────────────────────────────────────────────────────── + +// 远端 A.txt 与 a.txt 在大小写不敏感目标上映射到同一本地文件 → 两项都 failed， +// 绝不顺序覆盖导致静默丢文件。 +func TestDrivePull_equivalentPathCollisionFailsBoth(t *testing.T) { + forceCaseInsensitiveFS(t) + root := t.TempDir() + + caller := pullListingCaller( + `{"name":"A.txt","type":"file","fileId":"UP","modifyTime":1},` + + `{"name":"a.txt","type":"file","fileId":"LOW","modifyTime":2}`) + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("collided entries must not be downloaded") + return nil + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT") + var pf *drivePartialFailure + if !errors.As(err, &pf) { + t.Fatalf("expected drivePartialFailure, got %T %v", err, err) + } + for _, name := range []string{"A.txt", "a.txt"} { + if _, statErr := os.Stat(filepath.Join(root, name)); !os.IsNotExist(statErr) { + t.Errorf("%s must not be written on collision", name) + } + } +} + +// sync 的 new_remote 阶段同样拒绝等价冲突项。 +func TestDriveSync_equivalentPathCollisionFailsBoth(t *testing.T) { + forceCaseInsensitiveFS(t) + root := t.TempDir() + withSyncTransport(t, "remote") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[` + + `{"name":"A.txt","type":"file","fileId":"UP","modifyTime":1},` + + `{"name":"a.txt","type":"file","fileId":"LOW","modifyTime":2}` + + `],"nextToken":""}}`, + }) + err := runDriveCmd(t, caller, "sync", "--local-folder", root, "--remote-folder", "ROOT", "--quick") + var sf *driveSyncFailure + if !errors.As(err, &sf) { + t.Fatalf("expected driveSyncFailure, got %T %v", err, err) + } + if sf.failed != 2 { + t.Errorf("failed = %d, want 2 (both collided entries)", sf.failed) + } +} + +// ────────────────────────────────────────────────────────── +// detectCaseInsensitiveFS：探针名无大小写差异时回退平台默认 +// ────────────────────────────────────────────────────────── + +func TestDetectCaseInsensitiveFS_caselessProbeFallsBackToPlatformDefault(t *testing.T) { + prev := caseProbePattern + caseProbePattern = "1234567890*" // 纯数字：ToUpper 与原名相同，无法据此判定 + t.Cleanup(func() { caseProbePattern = prev }) + + dir := t.TempDir() + got := detectCaseInsensitiveFS(dir) + // 回退值即平台默认；这里只断言它与平台默认一致，不写死具体布尔。 + want := runtime.GOOS == "windows" || runtime.GOOS == "darwin" + if got != want { + t.Errorf("detectCaseInsensitiveFS = %v, want platform default %v", got, want) + } +} + +// ────────────────────────────────────────────────────────── +// isSafeRemoteSegmentPlatform：非 Windows 平台无额外约束 +// ────────────────────────────────────────────────────────── + +func TestIsSafeRemoteSegmentPlatform_allowsPlainNames(t *testing.T) { + for _, name := range []string{"a.txt", "报告.pdf", "with space.md", "..."} { + if !isSafeRemoteSegmentPlatform(name) { + t.Errorf("isSafeRemoteSegmentPlatform(%q) = false, want true", name) + } + } +} + +// ────────────────────────────────────────────────────────── +// WalkDir 单条目处理：Info() 与 filepath.Rel 的失败分支 +// ────────────────────────────────────────────────────────── + +// errDirEntry 是一个 Info() 必然报错的 fs.DirEntry。 +type errDirEntry struct{ dir bool } + +func (e errDirEntry) Name() string { return "entry" } +func (e errDirEntry) IsDir() bool { return e.dir } +func (e errDirEntry) Type() fs.FileMode { return 0 } +func (e errDirEntry) Info() (fs.FileInfo, error) { return nil, errTestInfo } + +var errTestInfo = errors.New("simulated DirEntry.Info failure") + +// irregularDirEntry 的 Info() 成功，但报告为非常规文件（如设备文件）。 +type irregularDirEntry struct{} + +func (irregularDirEntry) Name() string { return "dev" } +func (irregularDirEntry) IsDir() bool { return false } +func (irregularDirEntry) Type() fs.FileMode { return fs.ModeDevice } +func (irregularDirEntry) Info() (fs.FileInfo, error) { return irregularFileInfo{}, nil } + +type irregularFileInfo struct{} + +func (irregularFileInfo) Name() string { return "dev" } +func (irregularFileInfo) Size() int64 { return 0 } +func (irregularFileInfo) Mode() fs.FileMode { return fs.ModeDevice } +func (irregularFileInfo) ModTime() time.Time { return time.Unix(0, 0) } +func (irregularFileInfo) IsDir() bool { return false } +func (irregularFileInfo) Sys() any { return nil } + +func TestWalkLocalTreeEntry_errorBranches(t *testing.T) { + files := map[string]*localFile{} + + // WalkDir 自身报错原样上抛。 + if err := walkLocalTreeEntry("/root", "/root/a", errDirEntry{}, errTestInfo, files); !errors.Is(err, errTestInfo) { + t.Errorf("incoming error must propagate, got %v", err) + } + // 目录条目直接跳过。 + if err := walkLocalTreeEntry("/root", "/root/sub", errDirEntry{dir: true}, nil, files); err != nil { + t.Errorf("directory entry must be skipped, got %v", err) + } + // Info() 失败上抛。 + if err := walkLocalTreeEntry("/root", "/root/a", errDirEntry{}, nil, files); !errors.Is(err, errTestInfo) { + t.Errorf("Info() error must propagate, got %v", err) + } + // 非常规文件忽略。 + if err := walkLocalTreeEntry("/root", "/root/dev", irregularDirEntry{}, nil, files); err != nil { + t.Errorf("irregular entry must be skipped, got %v", err) + } + // filepath.Rel 失败（root 绝对、path 相对）上抛。 + if err := walkLocalTreeEntry("/root", "relative/path", regularDirEntry{}, nil, files); err == nil { + t.Error("filepath.Rel error must propagate") + } + if len(files) != 0 { + t.Errorf("no entry should have been indexed, got %v", files) + } +} + +// regularDirEntry 的 Info() 返回一个常规文件，用于走到 filepath.Rel。 +type regularDirEntry struct{} + +func (regularDirEntry) Name() string { return "a" } +func (regularDirEntry) IsDir() bool { return false } +func (regularDirEntry) Type() fs.FileMode { return 0 } +func (regularDirEntry) Info() (fs.FileInfo, error) { return regularFileInfo{}, nil } + +type regularFileInfo struct{} + +func (regularFileInfo) Name() string { return "a" } +func (regularFileInfo) Size() int64 { return 1 } +func (regularFileInfo) Mode() fs.FileMode { return 0o644 } +func (regularFileInfo) ModTime() time.Time { return time.Unix(1, 0) } +func (regularFileInfo) IsDir() bool { return false } +func (regularFileInfo) Sys() any { return nil } + +func TestWalkLocalForPushEntry_errorBranches(t *testing.T) { + var dirs []string + var files []localPushFile + + // WalkDir 自身报错原样上抛。 + if err := walkLocalForPushEntry("/root", "/root/a", regularDirEntry{}, errTestInfo, &dirs, &files); !errors.Is(err, errTestInfo) { + t.Errorf("incoming error must propagate, got %v", err) + } + // filepath.Rel 失败上抛。 + if err := walkLocalForPushEntry("/root", "relative/path", regularDirEntry{}, nil, &dirs, &files); err == nil { + t.Error("filepath.Rel error must propagate") + } + // 根目录本身跳过。 + if err := walkLocalForPushEntry("/root", "/root", regularDirEntry{}, nil, &dirs, &files); err != nil { + t.Errorf("root itself must be skipped, got %v", err) + } + // Info() 失败上抛。 + if err := walkLocalForPushEntry("/root", "/root/a", errDirEntry{}, nil, &dirs, &files); !errors.Is(err, errTestInfo) { + t.Errorf("Info() error must propagate, got %v", err) + } + // 非常规文件忽略。 + if err := walkLocalForPushEntry("/root", "/root/dev", irregularDirEntry{}, nil, &dirs, &files); err != nil { + t.Errorf("irregular entry must be skipped, got %v", err) + } + // 目录条目进 dirs。 + if err := walkLocalForPushEntry("/root", "/root/sub", errDirEntry{dir: true}, nil, &dirs, &files); err != nil { + t.Errorf("directory entry must be recorded, got %v", err) + } + if len(dirs) != 1 || dirs[0] != "sub" { + t.Errorf("dirs = %v, want [sub]", dirs) + } + if len(files) != 0 { + t.Errorf("files = %v, want empty", files) + } +} From 6910bda9c72ee03e9a8545d4728e339904514b92 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 14:09:35 +0800 Subject: [PATCH 009/250] refactor(drive): drop unreachable fixed-point guard in symlink escape check --- internal/helpers/drive_status.go | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 11239bc7..eaeb360a 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -329,6 +329,10 @@ func verifyNoSymlinkEscape(absDir, target string) error { return nil } + // 循环必然终止，无需不动点兜底：每轮 ancestor 严格变短，要么越界后由下面的 ".." + // 分支退出，要么下降到 absDir 自身——absDir 必然存在（EvalSymlinks 刚成功），于是 + // 在 Lstat 成功分支退出。即便 absDir 在此期间被删除，下一轮 ancestor 升到 absDir + // 之上，同样由 ".." 分支退出。 ancestor := filepath.Dir(target) for { // 越过 absDir 边界（祖先跑到根目录之上）就停止：根目录之上不属于逃逸判定范围。 @@ -347,11 +351,7 @@ func verifyNoSymlinkEscape(absDir, target string) error { } return nil } - parent := filepath.Dir(ancestor) - if parent == ancestor { - return nil - } - ancestor = parent + ancestor = filepath.Dir(ancestor) } } From 0a90c0350d90820fd466709101777820449133be Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 14:26:45 +0800 Subject: [PATCH 010/250] docs(changelog): move release note to a .changes fragment --- .changes/drive-folder-sync.md | 15 +++++++++++++++ CHANGELOG.md | 14 -------------- 2 files changed, 15 insertions(+), 14 deletions(-) create mode 100644 .changes/drive-folder-sync.md diff --git a/.changes/drive-folder-sync.md b/.changes/drive-folder-sync.md new file mode 100644 index 00000000..a42fbf36 --- /dev/null +++ b/.changes/drive-folder-sync.md @@ -0,0 +1,15 @@ +--- +category: Added +--- + +- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`, + `dws drive push`, and `dws drive sync` for file-level comparison and transfer + between a local folder and a Drive folder. Differences come from exact MD5 by + default or from modification time with `--quick`; `status` is read-only, `pull` + and `push` are one-directional with `--if-exists skip|smart|overwrite`, and + `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`. + Only regular files are transferred — online documents and shortcuts are skipped, + neither side deletes extra files, downloads are staged through a temporary file + and committed with an atomic rename, and remote names that would escape + `--local-folder` are reported as failures instead of being written. Every command + prints a structured summary on stdout and exits non-zero when any item fails. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5077b270..02d4254e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,20 +6,6 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] -### Added - -- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`, - `dws drive push`, and `dws drive sync` for file-level comparison and transfer - between a local folder and a Drive folder. Differences come from exact MD5 by - default or from modification time with `--quick`; `status` is read-only, `pull` - and `push` are one-directional with `--if-exists skip|smart|overwrite`, and - `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`. - Only regular files are transferred — online documents and shortcuts are skipped, - neither side deletes extra files, downloads are staged through a temporary file - and committed with an atomic rename, and remote names that would escape - `--local-folder` are reported as failures instead of being written. Every command - prints a structured summary on stdout and exits non-zero when any item fails. - ## [1.0.58-beta.4] - 2026-08-12 ### Added From 54aefaaf6049c8c9278fa9a1814d3430159fd59f Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 15:22:08 +0800 Subject: [PATCH 011/250] test(drive): use testseam for seam swaps and expose tests to platform coverage runners --- internal/helpers/drive_pull_coverage_test.go | 22 ++++----- internal/helpers/drive_pull_test.go | 36 +++++++------- internal/helpers/drive_push_coverage_test.go | 30 ++++++------ internal/helpers/drive_push_test.go | 12 ++--- .../helpers/drive_status_coverage_test.go | 30 ++++++------ internal/helpers/drive_status_test.go | 34 +++++++------- internal/helpers/drive_sync_conflict_test.go | 18 +++---- internal/helpers/drive_sync_coverage_test.go | 47 +++++++++---------- internal/helpers/drive_sync_edges_test.go | 33 +++++++------ internal/helpers/drive_sync_platform_test.go | 23 +++++---- internal/helpers/drive_sync_test.go | 29 ++++++------ 11 files changed, 154 insertions(+), 160 deletions(-) diff --git a/internal/helpers/drive_pull_coverage_test.go b/internal/helpers/drive_pull_coverage_test.go index ef04e2d3..f59c93b5 100644 --- a/internal/helpers/drive_pull_coverage_test.go +++ b/internal/helpers/drive_pull_coverage_test.go @@ -32,7 +32,7 @@ func pullListingCaller(items string) *driveScriptCaller { } // 端到端 pull：远端两个文件都下载到本地，并自动创建缺失的本地根目录。 -func TestDrivePull_endToEndDownloadsAll(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_endToEndDownloadsAll(t *testing.T) { root := filepath.Join(t.TempDir(), "created-by-pull") caller := pullListingCaller( `{"name":"a.txt","type":"file","fileId":"A","modifyTime":1000},` + @@ -54,7 +54,7 @@ func TestDrivePull_endToEndDownloadsAll(t *testing.T) { } // --if-exists skip：本地已存在则不下载。 -func TestDrivePull_ifExistsSkipKeepsLocal(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_ifExistsSkipKeepsLocal(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "a.txt"), "local-original") caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9000}`) @@ -74,7 +74,7 @@ func TestDrivePull_ifExistsSkipKeepsLocal(t *testing.T) { } // --if-exists smart：本地 mtime 已 ≥ 远端 → 跳过；远端更新 → 下载。 -func TestDrivePull_ifExistsSmart(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_ifExistsSmart(t *testing.T) { t.Run("local newer skips", func(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "a.txt") @@ -118,7 +118,7 @@ func TestDrivePull_ifExistsSmart(t *testing.T) { } // --if-exists 非法值直接拒绝。 -func TestDrivePull_invalidIfExistsRejected(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_invalidIfExistsRejected(t *testing.T) { caller := pullListingCaller("") err := runDriveCmd(t, caller, "pull", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--if-exists", "bogus") if err == nil || !strings.Contains(err.Error(), "--if-exists") { @@ -127,7 +127,7 @@ func TestDrivePull_invalidIfExistsRejected(t *testing.T) { } // space-id 透传到 download_file。 -func TestDrivePull_passesSpaceIDToDownload(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_passesSpaceIDToDownload(t *testing.T) { root := t.TempDir() caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { @@ -144,7 +144,7 @@ func TestDrivePull_passesSpaceIDToDownload(t *testing.T) { } // 下载失败 → 该项记 failed，命令以 partial_failure 非零退出。 -func TestDrivePull_downloadFailureIsPartialFailure(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_downloadFailureIsPartialFailure(t *testing.T) { root := t.TempDir() caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) @@ -161,7 +161,7 @@ func TestDrivePull_downloadFailureIsPartialFailure(t *testing.T) { } // download_file 未返回下载链接 → failed（不是 panic，也不落盘）。 -func TestDrivePull_missingDownloadURLFails(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_missingDownloadURLFails(t *testing.T) { root := t.TempDir() caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { if tool == "list_files" { @@ -181,7 +181,7 @@ func TestDrivePull_missingDownloadURLFails(t *testing.T) { } // download_file 的 MCP 调用本身失败 → failed。 -func TestDrivePull_downloadToolErrorFails(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_downloadToolErrorFails(t *testing.T) { root := t.TempDir() caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { if tool == "list_files" { @@ -198,7 +198,7 @@ func TestDrivePull_downloadToolErrorFails(t *testing.T) { } // 远端名称逃逸出本地根 → 记 failed，不落盘（resolveLocalTarget 二次确认）。 -func TestDrivePull_escapingRelPathIsFailed(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_escapingRelPathIsFailed(t *testing.T) { root := t.TempDir() // 远端目录名合法，但目录内的软链把落盘点指到根目录外。 outside := t.TempDir() @@ -231,7 +231,7 @@ func TestDrivePull_escapingRelPathIsFailed(t *testing.T) { } // 目标父目录不可创建（同名常规文件占位）→ failed，不 panic。 -func TestPullOneFile_mkdirFailureIsFailed(t *testing.T) { +func TestCrossPlatformCoveragePullOneFile_mkdirFailureIsFailed(t *testing.T) { root := t.TempDir() // "sub" 是普通文件，MkdirAll("sub") 必然失败。 mustWrite(t, filepath.Join(root, "sub"), "occupied") @@ -253,7 +253,7 @@ func TestPullOneFile_mkdirFailureIsFailed(t *testing.T) { } // 探测目录不存在时 isCaseInsensitiveFS 回退平台默认，不 panic。 -func TestIsCaseInsensitiveFS_missingDirFallsBackToPlatformDefault(t *testing.T) { +func TestCrossPlatformCoverageIsCaseInsensitiveFS_missingDirFallsBackToPlatformDefault(t *testing.T) { missing := filepath.Join(t.TempDir(), "absent") // 只断言不 panic 且返回布尔（具体值取决于平台默认）。 _ = isCaseInsensitiveFS(missing) diff --git a/internal/helpers/drive_pull_test.go b/internal/helpers/drive_pull_test.go index c913b9cb..032eb1d7 100644 --- a/internal/helpers/drive_pull_test.go +++ b/internal/helpers/drive_pull_test.go @@ -31,7 +31,7 @@ func (m *drivePullMockCaller) JQ() string { return "" } // isSafeRemoteSegment — 远端名称逐段安全校验（拒绝逃逸成分） // ────────────────────────────────────────────────────────── -func TestIsSafeRemoteSegment(t *testing.T) { +func TestCrossPlatformCoverageIsSafeRemoteSegment(t *testing.T) { cases := []struct { name string ok bool @@ -59,7 +59,7 @@ func TestIsSafeRemoteSegment(t *testing.T) { // resolveLocalTarget — 拼接后必须仍位于本地根目录内 // ────────────────────────────────────────────────────────── -func TestResolveLocalTarget_withinRoot(t *testing.T) { +func TestCrossPlatformCoverageResolveLocalTarget_withinRoot(t *testing.T) { root := filepath.Clean(t.TempDir()) got, err := resolveLocalTarget(root, "sub/a.txt") if err != nil { @@ -72,7 +72,7 @@ func TestResolveLocalTarget_withinRoot(t *testing.T) { } // 即便 isSafeRemoteSegment 被绕过，逐段拼出的逃逸路径也必须被 resolveLocalTarget 兜住。 -func TestResolveLocalTarget_escapeRejected(t *testing.T) { +func TestCrossPlatformCoverageResolveLocalTarget_escapeRejected(t *testing.T) { root := filepath.Clean(t.TempDir()) for _, rel := range []string{"../evil.txt", "../../etc/passwd", "sub/../../out.txt"} { if _, err := resolveLocalTarget(root, rel); err == nil { @@ -83,7 +83,7 @@ func TestResolveLocalTarget_escapeRejected(t *testing.T) { // 根目录内的目录符号链接指向外部时，词法检查会放过（root/sub 仍在 root 下）， // 必须靠符号链接解析挡住：sub -> /outside 时 sub/a.txt 应被拒绝。 -func TestResolveLocalTarget_dirSymlinkEscapeRejected(t *testing.T) { +func TestCrossPlatformCoverageResolveLocalTarget_dirSymlinkEscapeRejected(t *testing.T) { root := filepath.Clean(t.TempDir()) outside := filepath.Clean(t.TempDir()) @@ -106,7 +106,7 @@ func TestResolveLocalTarget_dirSymlinkEscapeRejected(t *testing.T) { } // 不存在的本地根目录必须放行（不误判逃逸），由后续 MkdirAll 创建。 -func TestResolveLocalTarget_nonexistentRootAllowed(t *testing.T) { +func TestCrossPlatformCoverageResolveLocalTarget_nonexistentRootAllowed(t *testing.T) { parent := filepath.Clean(t.TempDir()) absDir := filepath.Join(parent, "not", "created", "yet") // 尚不存在 got, err := resolveLocalTarget(absDir, "sub/a.txt") @@ -120,7 +120,7 @@ func TestResolveLocalTarget_nonexistentRootAllowed(t *testing.T) { // 回归：--local-folder 指向尚不存在的绝对路径时，pull 应自动创建目录并下载， // 而不是把每个远端文件都误判为符号链接逃逸而 failed。 -func TestDrivePull_nonexistentLocalRoot(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_nonexistentLocalRoot(t *testing.T) { parent := t.TempDir() absDir := filepath.Join(parent, "new", "repo") // 尚不存在 @@ -167,7 +167,7 @@ func TestDrivePull_nonexistentLocalRoot(t *testing.T) { // ────────────────────────────────────────────────────────── // 大小写不敏感 FS：A.txt 与 a.txt 落到同一目标 → 两者都判冲突；无关文件不受影响。 -func TestDetectTargetCollisions_caseInsensitive(t *testing.T) { +func TestCrossPlatformCoverageDetectTargetCollisions_caseInsensitive(t *testing.T) { root := filepath.Clean(t.TempDir()) rels := []string{"A.txt", "a.txt", "b.txt", "sub/C.md", "sub/c.md"} collided := detectTargetCollisions(root, rels, true) @@ -183,7 +183,7 @@ func TestDetectTargetCollisions_caseInsensitive(t *testing.T) { } // 大小写敏感 FS：A.txt 与 a.txt 是两个合法文件 → 不应误判冲突。 -func TestDetectTargetCollisions_caseSensitive(t *testing.T) { +func TestCrossPlatformCoverageDetectTargetCollisions_caseSensitive(t *testing.T) { root := filepath.Clean(t.TempDir()) rels := []string{"A.txt", "a.txt", "b.txt"} collided := detectTargetCollisions(root, rels, false) @@ -193,7 +193,7 @@ func TestDetectTargetCollisions_caseSensitive(t *testing.T) { } // 平台名称规范化冲突：同名的 NFC 与 NFD 记法在不敏感 FS 上落到同一目标 → 冲突。 -func TestDetectTargetCollisions_unicodeNormalization(t *testing.T) { +func TestCrossPlatformCoverageDetectTargetCollisions_unicodeNormalization(t *testing.T) { root := filepath.Clean(t.TempDir()) nfc := "café.txt" // café（预组合 é） nfd := "café.txt" // café（e + 组合尖音符） @@ -213,7 +213,7 @@ func TestDetectTargetCollisions_unicodeNormalization(t *testing.T) { } // isCaseInsensitiveFS 应能对临时目录给出与实际探针一致的判定（本机自洽）。 -func TestIsCaseInsensitiveFS_selfConsistent(t *testing.T) { +func TestCrossPlatformCoverageIsCaseInsensitiveFS_selfConsistent(t *testing.T) { dir := t.TempDir() got := isCaseInsensitiveFS(dir) // 实测：写一个小写名，再用大写名 stat。 @@ -233,7 +233,7 @@ func TestIsCaseInsensitiveFS_selfConsistent(t *testing.T) { // ────────────────────────────────────────────────────────── // 下载中途失败时：命令报告 failed，原有本地文件内容必须原封不动，且不留临时残file。 -func TestPullOneFile_downloadFailureKeepsOriginal(t *testing.T) { +func TestCrossPlatformCoveragePullOneFile_downloadFailureKeepsOriginal(t *testing.T) { root := t.TempDir() target := filepath.Join(root, "a.txt") const original = "ORIGINAL-CONTENT-DO-NOT-LOSE" @@ -280,7 +280,7 @@ func TestPullOneFile_downloadFailureKeepsOriginal(t *testing.T) { } // 下载成功时：临时文件被原子重命名为目标，内容与远端一致。 -func TestPullOneFile_downloadSuccessReplacesTarget(t *testing.T) { +func TestCrossPlatformCoveragePullOneFile_downloadSuccessReplacesTarget(t *testing.T) { root := t.TempDir() target := filepath.Join(root, "a.txt") mustWrite(t, target, "OLD") @@ -318,7 +318,7 @@ func TestPullOneFile_downloadSuccessReplacesTarget(t *testing.T) { // ────────────────────────────────────────────────────────── // drive 的正常返回：result.downloadUrl 是预签名 URL，无需额外 header。 -func TestParseDriveDownloadInfo_downloadUrl(t *testing.T) { +func TestCrossPlatformCoverageParseDriveDownloadInfo_downloadUrl(t *testing.T) { text := `{"result":{"downloadType":"urlPreSignature","downloadUrl":"https://oss.example.com/f.file?Expires=1&Signature=xyz","fileName":"a.txt"},"success":true}` url, headers, err := parseDriveDownloadInfo(text) if err != nil { @@ -333,7 +333,7 @@ func TestParseDriveDownloadInfo_downloadUrl(t *testing.T) { } // 兼容 flat resourceUrl 字段。 -func TestParseDriveDownloadInfo_resourceUrlFallback(t *testing.T) { +func TestCrossPlatformCoverageParseDriveDownloadInfo_resourceUrlFallback(t *testing.T) { text := `{"resourceUrl":"https://flat.example.com/dl"}` url, _, err := parseDriveDownloadInfo(text) if err != nil { @@ -345,7 +345,7 @@ func TestParseDriveDownloadInfo_resourceUrlFallback(t *testing.T) { } // 兼容 resourceUrls[].url 数组格式（在 result 包裹下）。 -func TestParseDriveDownloadInfo_resourceUrlsArrayFallback(t *testing.T) { +func TestCrossPlatformCoverageParseDriveDownloadInfo_resourceUrlsArrayFallback(t *testing.T) { text := `{"result":{"resourceUrls":[{"url":"https://arr.example.com/dl","headers":{}}]}}` url, _, err := parseDriveDownloadInfo(text) if err != nil { @@ -356,14 +356,14 @@ func TestParseDriveDownloadInfo_resourceUrlsArrayFallback(t *testing.T) { } } -func TestParseDriveDownloadInfo_missingURL(t *testing.T) { +func TestCrossPlatformCoverageParseDriveDownloadInfo_missingURL(t *testing.T) { text := `{"result":{"fileName":"a.txt"}}` if _, _, err := parseDriveDownloadInfo(text); err == nil { t.Fatal("expected error when downloadUrl is empty") } } -func TestParseDriveDownloadInfo_invalidJSON(t *testing.T) { +func TestCrossPlatformCoverageParseDriveDownloadInfo_invalidJSON(t *testing.T) { if _, _, err := parseDriveDownloadInfo("not json"); err == nil { t.Fatal("expected error for invalid JSON") } @@ -373,7 +373,7 @@ func TestParseDriveDownloadInfo_invalidJSON(t *testing.T) { // drivePartialFailure — pull 部分失败错误：exit=1，JSON 原样透传 // ────────────────────────────────────────────────────────── -func TestDrivePartialFailure(t *testing.T) { +func TestCrossPlatformCoverageDrivePartialFailure(t *testing.T) { raw := `{"error":{"type":"partial_failure","detail":{}}}` e := &drivePartialFailure{raw: raw} if e.ExitCode() != 1 { diff --git a/internal/helpers/drive_push_coverage_test.go b/internal/helpers/drive_push_coverage_test.go index 1b2774f6..c279ae3f 100644 --- a/internal/helpers/drive_push_coverage_test.go +++ b/internal/helpers/drive_push_coverage_test.go @@ -44,7 +44,7 @@ func withNoopPut(t *testing.T) { // ────────────────────────────────────────────────────────── // 本地子目录在远端缺失 → 按需 create_folder 并留 folder_created 痕迹，再上传其中文件。 -func TestDrivePush_createsMissingRemoteFolders(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_createsMissingRemoteFolders(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -71,7 +71,7 @@ func TestDrivePush_createsMissingRemoteFolders(t *testing.T) { } // 远端已存在同名目录 → 复用其 fileId，不重建、不出现在 items[]。 -func TestDrivePush_reusesExistingRemoteFolder(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_reusesExistingRemoteFolder(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -94,7 +94,7 @@ func TestDrivePush_reusesExistingRemoteFolder(t *testing.T) { } // create_folder 失败 / 未返回 fileId → 该目录记 failed，其中文件因父目录缺失也 failed。 -func TestDrivePush_folderCreationFailureCascades(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_folderCreationFailureCascades(t *testing.T) { for _, tc := range []struct { name string reply func(string, map[string]any, int) (string, error) @@ -138,7 +138,7 @@ func TestDrivePush_folderCreationFailureCascades(t *testing.T) { } // --if-exists skip（默认）：远端已存在 → 跳过，不上传。 -func TestDrivePush_ifExistsSkipIsDefault(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_ifExistsSkipIsDefault(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "local") withNoopPut(t) @@ -155,7 +155,7 @@ func TestDrivePush_ifExistsSkipIsDefault(t *testing.T) { } // --if-exists smart：远端时间已 ≥ 本地 → 跳过；远端更旧 → 覆盖上传。 -func TestDrivePush_ifExistsSmart(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_ifExistsSmart(t *testing.T) { t.Run("remote newer skips", func(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "a.txt") @@ -217,7 +217,7 @@ func TestDrivePush_ifExistsSmart(t *testing.T) { } // 上传失败 → 记 failed 并以非零退出码退出，结构化结果仍打印。 -func TestDrivePush_uploadFailureExitsNonZero(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_uploadFailureExitsNonZero(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "local") SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) @@ -232,7 +232,7 @@ func TestDrivePush_uploadFailureExitsNonZero(t *testing.T) { } // --if-exists 非法值直接拒绝。 -func TestDrivePush_invalidIfExistsRejected(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_invalidIfExistsRejected(t *testing.T) { err := runDriveCmd(t, pushOKCaller(nil), "push", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--if-exists", "bogus") if err == nil || !strings.Contains(err.Error(), "--if-exists") { t.Fatalf("expected --if-exists rejection, got %v", err) @@ -240,7 +240,7 @@ func TestDrivePush_invalidIfExistsRejected(t *testing.T) { } // space-id 必须透传到 create_folder / get_upload_info / ln 三处。 -func TestDrivePush_passesSpaceIDEverywhere(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_passesSpaceIDEverywhere(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -264,7 +264,7 @@ func TestDrivePush_passesSpaceIDEverywhere(t *testing.T) { } // 远端列举失败 → push 直接报错，不做任何上传。 -func TestDrivePush_remoteListFailurePropagates(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_remoteListFailurePropagates(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "x") caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} @@ -274,7 +274,7 @@ func TestDrivePush_remoteListFailurePropagates(t *testing.T) { } // 本地根目录不存在 → 扫描失败。 -func TestDrivePush_missingLocalRootFails(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_missingLocalRootFails(t *testing.T) { missing := filepath.Join(t.TempDir(), "absent") err := runDriveCmd(t, pushOKCaller(nil), "push", "--local-folder", missing, "--remote-folder", "ROOT") if err == nil || !strings.Contains(err.Error(), "扫描本地目录失败") { @@ -286,7 +286,7 @@ func TestDrivePush_missingLocalRootFails(t *testing.T) { // walkRemoteForPush — 分页、递归、深度上限、非法/空名跳过 // ────────────────────────────────────────────────────────── -func TestWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) { +func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) { // 递归会插在 ROOT 的两页之间，所以按 (parentId, nextToken) 判定而非调用序号。 caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) { parent, _ := args["parentId"].(string) @@ -332,7 +332,7 @@ func TestWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) { } } -func TestWalkRemoteForPush_depthLimitAborts(t *testing.T) { +func TestCrossPlatformCoverageWalkRemoteForPush_depthLimitAborts(t *testing.T) { caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil }} @@ -351,7 +351,7 @@ func TestWalkRemoteForPush_depthLimitAborts(t *testing.T) { // walkLocalForPush — 非常规文件与错误分支 // ────────────────────────────────────────────────────────── -func TestWalkLocalForPush_skipsIrregularAndMissingRoot(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalForPush_skipsIrregularAndMissingRoot(t *testing.T) { if _, _, err := walkLocalForPush(filepath.Join(t.TempDir(), "absent")); err == nil { t.Fatal("expected error for missing root") } @@ -376,7 +376,7 @@ func TestWalkLocalForPush_skipsIrregularAndMissingRoot(t *testing.T) { // pushUploadFile — 凭证解析与提交失败分支 // ────────────────────────────────────────────────────────── -func TestPushUploadFile_failureBranches(t *testing.T) { +func TestCrossPlatformCoveragePushUploadFile_failureBranches(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "a.txt") mustWrite(t, p, "payload") @@ -437,7 +437,7 @@ func TestPushUploadFile_failureBranches(t *testing.T) { } // pushCreateFolder：MCP 失败上抛，成功时从返回体提取 fileId。 -func TestPushCreateFolder_errorAndSuccess(t *testing.T) { +func TestCrossPlatformCoveragePushCreateFolder_errorAndSuccess(t *testing.T) { prevDeps, prevArgs := deps, os.Args os.Args = []string{"dws", "drive"} t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) diff --git a/internal/helpers/drive_push_test.go b/internal/helpers/drive_push_test.go index c0d92ad1..809c0bdc 100644 --- a/internal/helpers/drive_push_test.go +++ b/internal/helpers/drive_push_test.go @@ -17,7 +17,7 @@ import ( // splitRel — rel_path 拆父路径 / 末段名 // ────────────────────────────────────────────────────────── -func TestSplitRel(t *testing.T) { +func TestCrossPlatformCoverageSplitRel(t *testing.T) { cases := []struct { in string parent, base string @@ -39,7 +39,7 @@ func TestSplitRel(t *testing.T) { // parseNodeID — create_folder / commit 返回里抽 fileId // ────────────────────────────────────────────────────────── -func TestParseNodeID(t *testing.T) { +func TestCrossPlatformCoverageParseNodeID(t *testing.T) { cases := []struct { name string text string @@ -65,7 +65,7 @@ func TestParseNodeID(t *testing.T) { // walkLocalForPush — 本地遍历（含空目录，父目录先于子目录） // ────────────────────────────────────────────────────────── -func TestWalkLocalForPush(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalForPush(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "a.txt"), "hello") // 5 bytes mustWrite(t, filepath.Join(root, "sub1", "b.txt"), "worl") // 4 bytes, 建出 sub1 @@ -115,7 +115,7 @@ func TestWalkLocalForPush(t *testing.T) { // drivePushFailure — push 部分失败错误：exit=1 // ────────────────────────────────────────────────────────── -func TestDrivePushFailure(t *testing.T) { +func TestCrossPlatformCoverageDrivePushFailure(t *testing.T) { e := &drivePushFailure{failed: 3} if e.ExitCode() != 1 { t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) @@ -208,7 +208,7 @@ func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string } // 覆盖分支：get_upload_info 与 commit_upload 两阶段都必须传 overwriteFileId、都不传 parentId。 -func TestDrivePush_overwriteUsesOverwriteFileId(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_overwriteUsesOverwriteFileId(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "new-content") @@ -244,7 +244,7 @@ func TestDrivePush_overwriteUsesOverwriteFileId(t *testing.T) { } // 新建分支：远端不存在同名文件时走普通上传——两阶段都传 parentId、都不传 overwriteFileId。 -func TestDrivePush_newUploadUsesParentId(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_newUploadUsesParentId(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "b.txt"), "brand-new") diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index e999a6a6..8c6471cb 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -86,7 +86,7 @@ func runDriveCmd(t *testing.T, caller edition.ToolCaller, args ...string) error // ────────────────────────────────────────────────────────── // 端到端 status：递归进入子文件夹、拼接 rel_path、跳过非 file 类型。 -func TestDriveStatus_endToEndNestedTree(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_endToEndNestedTree(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "root.txt"), "r") if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { @@ -121,7 +121,7 @@ func TestDriveStatus_endToEndNestedTree(t *testing.T) { } // 分页：首页返回 nextToken，第二页取完；token 未推进时必须终止而非死循环。 -func TestDriveStatus_paginationAndStalledToken(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_paginationAndStalledToken(t *testing.T) { dir := t.TempDir() caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) { @@ -150,7 +150,7 @@ func TestDriveStatus_paginationAndStalledToken(t *testing.T) { } // space-id 显式传入时必须透传到 list_files。 -func TestDriveStatus_passesSpaceID(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_passesSpaceID(t *testing.T) { dir := t.TempDir() caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { return `{"result":{"items":[],"nextToken":""}}`, nil @@ -164,7 +164,7 @@ func TestDriveStatus_passesSpaceID(t *testing.T) { } // list_files 失败 → status 直接报错。 -func TestDriveStatus_listFailurePropagates(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_listFailurePropagates(t *testing.T) { dir := t.TempDir() caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { @@ -173,7 +173,7 @@ func TestDriveStatus_listFailurePropagates(t *testing.T) { } // 返回体无法解析 → status 报解析失败。 -func TestDriveStatus_unparsableListPropagates(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_unparsableListPropagates(t *testing.T) { dir := t.TempDir() caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return `{"result":"not-a-list"}`, nil @@ -185,7 +185,7 @@ func TestDriveStatus_unparsableListPropagates(t *testing.T) { } // exact 模式下本地文件不可读 → MD5 计算失败要作为错误上抛，不能静默当成一致。 -func TestDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) { if runtime.GOOS == "windows" || os.Geteuid() == 0 { t.Skip("chmod-based unreadable file needs POSIX perms and a non-root user") } @@ -207,7 +207,7 @@ func TestDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) { } // --local-folder 不是绝对路径 → 校验拦下，不发起任何 MCP 调用。 -func TestDriveStatus_relativeLocalFolderRejected(t *testing.T) { +func TestCrossPlatformCoverageDriveStatus_relativeLocalFolderRejected(t *testing.T) { caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { t.Error("must not call MCP when --local-folder is rejected") return "", nil @@ -222,7 +222,7 @@ func TestDriveStatus_relativeLocalFolderRejected(t *testing.T) { // ────────────────────────────────────────────────────────── // 远端目录自引用时深度上限必须中止遍历，避免无限递归。 -func TestWalkRemoteDir_depthLimitAborts(t *testing.T) { +func TestCrossPlatformCoverageWalkRemoteDir_depthLimitAborts(t *testing.T) { caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { // 每层都返回一个同名子文件夹 → 无限深。 return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil @@ -246,7 +246,7 @@ func TestWalkRemoteDir_depthLimitAborts(t *testing.T) { // isSafeRemoteSegment / resolveLocalTarget 的剩余分支 // ────────────────────────────────────────────────────────── -func TestIsSafeRemoteSegment_volumeAndNonCanonical(t *testing.T) { +func TestCrossPlatformCoverageIsSafeRemoteSegment_volumeAndNonCanonical(t *testing.T) { if runtime.GOOS == "windows" { if isSafeRemoteSegment(`C:name.txt`) { t.Error("volume-qualified name must be rejected") @@ -264,27 +264,27 @@ func TestIsSafeRemoteSegment_volumeAndNonCanonical(t *testing.T) { // md5File / walkLocalTree 错误分支 // ────────────────────────────────────────────────────────── -func TestMD5File_missingFile(t *testing.T) { +func TestCrossPlatformCoverageMD5File_missingFile(t *testing.T) { if _, err := md5File(filepath.Join(t.TempDir(), "nope.bin")); err == nil { t.Fatal("expected error for missing file") } } -func TestMD5File_directoryIsNotReadable(t *testing.T) { +func TestCrossPlatformCoverageMD5File_directoryIsNotReadable(t *testing.T) { // 目录不是常规文件：io.Copy 读取时必然报错。 if _, err := md5File(t.TempDir()); err == nil { t.Fatal("expected error when hashing a directory") } } -func TestWalkLocalTree_missingRootErrors(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalTree_missingRootErrors(t *testing.T) { if _, err := walkLocalTree(filepath.Join(t.TempDir(), "absent")); err == nil { t.Fatal("expected error for missing local root") } } // 非常规文件（FIFO/符号链接目标缺失等）不计入本地索引。 -func TestWalkLocalTree_skipsIrregularEntries(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalTree_skipsIrregularEntries(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "real.txt"), "x") if err := os.Symlink(filepath.Join(dir, "absent"), filepath.Join(dir, "dangling")); err != nil { @@ -306,7 +306,7 @@ func TestWalkLocalTree_skipsIrregularEntries(t *testing.T) { // toMillis 的 json.Number / float64 分支 // ────────────────────────────────────────────────────────── -func TestDriveItem_modifiedMillisFromNumericForms(t *testing.T) { +func TestCrossPlatformCoverageDriveItem_modifiedMillisFromNumericForms(t *testing.T) { if got, ok := (driveItem{"modifyTime": float64(1500)}).modifiedMillis(); !ok || got != 1500 { t.Errorf("float64 modifyTime = (%d,%v), want (1500,true)", got, ok) } @@ -325,7 +325,7 @@ func TestDriveItem_modifiedMillisFromNumericForms(t *testing.T) { } // fileSize 的 float64 / json.Number 两种形态，以及缺失时的兜底。 -func TestDriveItem_sizeForms(t *testing.T) { +func TestCrossPlatformCoverageDriveItem_sizeForms(t *testing.T) { if got := (driveItem{"fileSize": float64(42)}).size(); got != 42 { t.Errorf("float fileSize = %d, want 42", got) } diff --git a/internal/helpers/drive_status_test.go b/internal/helpers/drive_status_test.go index 8bf5e8d7..097af9d2 100644 --- a/internal/helpers/drive_status_test.go +++ b/internal/helpers/drive_status_test.go @@ -10,19 +10,19 @@ import ( // validateLocalDirAbs — 本地路径校验（必须为绝对路径） // ────────────────────────────────────────────────────────── -func TestValidateLocalDirAbs_empty(t *testing.T) { +func TestCrossPlatformCoverageValidateLocalDirAbs_empty(t *testing.T) { if _, err := validateLocalDirAbs(""); err == nil { t.Fatal("expected error for empty --local-folder") } } -func TestValidateLocalDirAbs_relative(t *testing.T) { +func TestCrossPlatformCoverageValidateLocalDirAbs_relative(t *testing.T) { if _, err := validateLocalDirAbs(filepath.Join(".", "repo")); err == nil { t.Fatal("expected error for relative path") } } -func TestValidateLocalDirAbs_ok(t *testing.T) { +func TestCrossPlatformCoverageValidateLocalDirAbs_ok(t *testing.T) { abs := filepath.Join(t.TempDir(), "repo") got, err := validateLocalDirAbs(abs) if err != nil { @@ -37,7 +37,7 @@ func TestValidateLocalDirAbs_ok(t *testing.T) { // walkLocalTree — 本地遍历 // ────────────────────────────────────────────────────────── -func TestWalkLocalTree_collectsRegularFiles(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalTree_collectsRegularFiles(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "a.txt"), "hello") mustWrite(t, filepath.Join(root, "sub", "b.txt"), "world") @@ -69,7 +69,7 @@ func TestWalkLocalTree_collectsRegularFiles(t *testing.T) { // compareTrees — 四类差异分类 // ────────────────────────────────────────────────────────── -func TestCompareTrees_exact(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_exact(t *testing.T) { local := map[string]*localFile{ "same.txt": {RelPath: "same.txt", Hash: "h1"}, "diff.txt": {RelPath: "diff.txt", Hash: "local"}, @@ -94,7 +94,7 @@ func TestCompareTrees_exact(t *testing.T) { } } -func TestCompareTrees_exact_unknownRemoteHashIsUnknown(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_exact_unknownRemoteHashIsUnknown(t *testing.T) { local := map[string]*localFile{"a.txt": {RelPath: "a.txt", Hash: "h1"}} remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", Hash: ""}} res, err := compareTrees(local, remote, "exact", false) @@ -113,7 +113,7 @@ func TestCompareTrees_exact_unknownRemoteHashIsUnknown(t *testing.T) { // TestCompareTrees_exact_hashesOnlyIntersection 验证本地 hash 只在双端都存在时才 // 计算：local-only 文件即使 AbsPath 指向不存在的文件也不会触发 hash（不报错）。 -func TestCompareTrees_exact_hashesOnlyIntersection(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_exact_hashesOnlyIntersection(t *testing.T) { root := t.TempDir() bothPath := filepath.Join(root, "both.txt") mustWrite(t, bothPath, "same-content") @@ -147,7 +147,7 @@ func TestCompareTrees_exact_hashesOnlyIntersection(t *testing.T) { // TestCompareTrees_exact_noRemoteMD5AllUnknown 验证 exact 模式在远端无 md5 时 // 一律归入 unknown——不再用 fileSize + modified_time 近似判 unchanged（否则大小与 // mtime 恰好相同但内容不同的文件会被误报为未变更），无论大小/时间是否相同。 -func TestCompareTrees_exact_noRemoteMD5AllUnknown(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_exact_noRemoteMD5AllUnknown(t *testing.T) { local := map[string]*localFile{ "sameSizeTime.txt": {RelPath: "sameSizeTime.txt", Size: 100, ModTimeMillis: 1000}, "diffsize.txt": {RelPath: "diffsize.txt", Size: 100, ModTimeMillis: 1000}, @@ -174,7 +174,7 @@ func TestCompareTrees_exact_noRemoteMD5AllUnknown(t *testing.T) { // TestCompareTrees_exact_base64RemoteMD5 验证 exact 用 base64 md5 比对：本地按 // base64 算 md5，与钉盘返回的 base64 md5 直接相等 → unchanged。 -func TestCompareTrees_exact_base64RemoteMD5(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_exact_base64RemoteMD5(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "a.txt") mustWrite(t, p, "hello root\n") // 11 字节，md5 base64 = 6y9K7B0b2K0AInNZZV/70A== @@ -195,7 +195,7 @@ func TestCompareTrees_exact_base64RemoteMD5(t *testing.T) { } } -func TestCompareTrees_quick(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_quick(t *testing.T) { local := map[string]*localFile{ "eq.txt": {RelPath: "eq.txt", ModTimeMillis: 1000}, "ne.txt": {RelPath: "ne.txt", ModTimeMillis: 1000}, @@ -216,7 +216,7 @@ func TestCompareTrees_quick(t *testing.T) { assertPaths(t, "modified", res.Modified, "bad.txt", "ne.txt") } -func TestCompareTrees_emptyRemote_allNewLocal(t *testing.T) { +func TestCrossPlatformCoverageCompareTrees_emptyRemote_allNewLocal(t *testing.T) { local := map[string]*localFile{ "a.txt": {RelPath: "a.txt", Hash: "h1"}, "b.txt": {RelPath: "b.txt", Hash: "h2"}, @@ -277,7 +277,7 @@ func entryPaths(entries []driveStatusEntry) []string { // parseDriveList — list_files 返回解析 // ────────────────────────────────────────────────────────── -func TestParseDriveList_resultItems(t *testing.T) { +func TestCrossPlatformCoverageParseDriveList_resultItems(t *testing.T) { text := `{"result":{"items":[{"name":"a.txt","type":"file"},{"name":"sub","type":"folder"}],"nextToken":"tok"}}` items, token, err := parseDriveList(text) if err != nil { @@ -291,7 +291,7 @@ func TestParseDriveList_resultItems(t *testing.T) { } } -func TestParseDriveList_topLevelArray(t *testing.T) { +func TestCrossPlatformCoverageParseDriveList_topLevelArray(t *testing.T) { text := `{"result":[{"name":"a.txt","type":"file"}]}` items, token, err := parseDriveList(text) if err != nil { @@ -305,7 +305,7 @@ func TestParseDriveList_topLevelArray(t *testing.T) { } } -func TestParseDriveList_invalid(t *testing.T) { +func TestCrossPlatformCoverageParseDriveList_invalid(t *testing.T) { if _, _, err := parseDriveList("not json"); err == nil { t.Fatal("expected error for invalid JSON") } @@ -315,7 +315,7 @@ func TestParseDriveList_invalid(t *testing.T) { // driveItem — 字段访问器（带 fallback） // ────────────────────────────────────────────────────────── -func TestDriveItem_accessors(t *testing.T) { +func TestCrossPlatformCoverageDriveItem_accessors(t *testing.T) { it := driveItem{ "name": "报告.pdf", "type": "file", @@ -351,7 +351,7 @@ func TestDriveItem_accessors(t *testing.T) { } } -func TestDriveItem_folderAndFile(t *testing.T) { +func TestCrossPlatformCoverageDriveItem_folderAndFile(t *testing.T) { folder := driveItem{"name": "sub", "type": "folder"} if !folder.isFolder() || folder.isFile() { t.Error("type=folder should be folder, not file") @@ -375,7 +375,7 @@ func TestDriveItem_folderAndFile(t *testing.T) { // toMillis — 时间字段归一化 // ────────────────────────────────────────────────────────── -func TestToMillis(t *testing.T) { +func TestCrossPlatformCoverageToMillis(t *testing.T) { cases := []struct { name string in any diff --git a/internal/helpers/drive_sync_conflict_test.go b/internal/helpers/drive_sync_conflict_test.go index 148d7d94..c57fd385 100644 --- a/internal/helpers/drive_sync_conflict_test.go +++ b/internal/helpers/drive_sync_conflict_test.go @@ -44,7 +44,7 @@ func mkNested(t *testing.T) string { } // 顶层目录 a 建失败 → 子目录 a/b 因父目录缺失也 failed，其中文件同样 failed。 -func TestDrivePush_nestedDirFailsWhenParentMissing(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_nestedDirFailsWhenParentMissing(t *testing.T) { dir := mkNested(t) withNoopPut(t) @@ -63,7 +63,7 @@ func TestDrivePush_nestedDirFailsWhenParentMissing(t *testing.T) { } } -func TestDriveSync_nestedDirFailsWhenParentMissing(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_nestedDirFailsWhenParentMissing(t *testing.T) { dir := mkNested(t) withNoopPut(t) @@ -79,7 +79,7 @@ func TestDriveSync_nestedDirFailsWhenParentMissing(t *testing.T) { } // new_remote 落盘目标经软链逃逸出本地根 → 记 failed，不写到根目录之外。 -func TestDriveSync_newRemoteEscapeIsFailed(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_newRemoteEscapeIsFailed(t *testing.T) { root := t.TempDir() outside := t.TempDir() if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { @@ -106,7 +106,7 @@ func TestDriveSync_newRemoteEscapeIsFailed(t *testing.T) { // ────────────────────────────────────────────────────────── // syncKeepBoth 在 rel 逃逸时直接 failed（resolveLocalTarget 报错）。 -func TestSyncKeepBoth_escapingRelIsFailed(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_escapingRelIsFailed(t *testing.T) { root := t.TempDir() outside := t.TempDir() if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { @@ -121,7 +121,7 @@ func TestSyncKeepBoth_escapingRelIsFailed(t *testing.T) { } // collided 命中时 keep-both 直接 failed，不做任何改名。 -func TestSyncKeepBoth_collidedIsFailed(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_collidedIsFailed(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "f.txt"), "local") res := &driveSyncResult{} @@ -136,7 +136,7 @@ func TestSyncKeepBoth_collidedIsFailed(t *testing.T) { } // 占用改名目标失败（目录不可写）→ failed。 -func TestSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { if runtime.GOOS == "windows" || os.Geteuid() == 0 { t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") } @@ -156,7 +156,7 @@ func TestSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { } // 改名本身失败（本地原文件其实是目录）→ failed，并清理刚建的空占位。 -func TestSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { root := t.TempDir() // rel 指向一个非空目录：os.Rename(dir, emptyFile) 会失败。 if err := os.MkdirAll(filepath.Join(root, "f.txt", "inner"), 0o755); err != nil { @@ -177,7 +177,7 @@ func TestSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { } // 拉取失败 → 回滚改名，本地文件恢复原名与原内容。 -func TestSyncKeepBoth_pullFailureRollsBackRename(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_pullFailureRollsBackRename(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "f.txt") mustWrite(t, p, "local-version") @@ -207,7 +207,7 @@ func TestSyncKeepBoth_pullFailureRollsBackRename(t *testing.T) { } // 拉取失败且回滚也失败 → 如实上报“本地版本保留为 <改名>”，不谎称成功。 -func TestSyncKeepBoth_rollbackFailureIsReported(t *testing.T) { +func TestCrossPlatformCoverageSyncKeepBoth_rollbackFailureIsReported(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "f.txt") mustWrite(t, p, "local-version") diff --git a/internal/helpers/drive_sync_coverage_test.go b/internal/helpers/drive_sync_coverage_test.go index 069e89bc..15d04b30 100644 --- a/internal/helpers/drive_sync_coverage_test.go +++ b/internal/helpers/drive_sync_coverage_test.go @@ -3,11 +3,14 @@ package helpers import ( "context" "errors" + "io" "os" "path/filepath" "strconv" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // syncCaller 组合 push 与 pull 两侧：list_files 按 parentId 返回远端现状， @@ -50,7 +53,7 @@ func withSyncTransport(t *testing.T, body string) { // ────────────────────────────────────────────────────────── // 显式传空 --on-conflict 时回落默认 remote-wins（而非报非法取值）。 -func TestDriveSync_emptyOnConflictDefaultsToRemoteWins(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_emptyOnConflictDefaultsToRemoteWins(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-old") @@ -70,7 +73,7 @@ func TestDriveSync_emptyOnConflictDefaultsToRemoteWins(t *testing.T) { } } -func TestDriveSync_invalidOnConflictRejected(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_invalidOnConflictRejected(t *testing.T) { err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", t.TempDir(), "--remote-folder", "ROOT", "--on-conflict", "bogus") if err == nil || !strings.Contains(err.Error(), "--on-conflict") { @@ -83,7 +86,7 @@ func TestDriveSync_invalidOnConflictRejected(t *testing.T) { // ────────────────────────────────────────────────────────── // quick 模式下两侧 mtime 相同 → unchanged，不做任何读写。 -func TestDriveSync_unchangedIsUntouched(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_unchangedIsUntouched(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "same.txt") mustWrite(t, p, "identical") @@ -106,7 +109,7 @@ func TestDriveSync_unchangedIsUntouched(t *testing.T) { } // exact 模式远端无可靠 md5 → unknown，一律计入 skipped 且不动任何一侧。 -func TestDriveSync_unknownIsSkipped(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_unknownIsSkipped(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "u.txt") mustWrite(t, p, "local") @@ -128,7 +131,7 @@ func TestDriveSync_unknownIsSkipped(t *testing.T) { } // exact 模式下本地不可读 → judgeFileMatch 的 MD5 失败要中止整个 sync。 -func TestDriveSync_md5FailureAborts(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_md5FailureAborts(t *testing.T) { if os.Geteuid() == 0 { t.Skip("chmod-based unreadable file needs a non-root user") } @@ -153,7 +156,7 @@ func TestDriveSync_md5FailureAborts(t *testing.T) { // ────────────────────────────────────────────────────────── // 本地子目录在远端缺失 → 建目录（记 folder_created + pushed）再上传其中文件。 -func TestDriveSync_createsRemoteFolderForNewLocal(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_createsRemoteFolderForNewLocal(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -176,7 +179,7 @@ func TestDriveSync_createsRemoteFolderForNewLocal(t *testing.T) { } // 远端已有同名目录 → 复用，不重建。 -func TestDriveSync_reusesExistingRemoteFolder(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_reusesExistingRemoteFolder(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -196,7 +199,7 @@ func TestDriveSync_reusesExistingRemoteFolder(t *testing.T) { } // create_folder 失败 → 目录与其中文件都记 failed，命令非零退出。 -func TestDriveSync_folderCreationFailureCascades(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_folderCreationFailureCascades(t *testing.T) { dir := t.TempDir() if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { t.Fatal(err) @@ -218,7 +221,7 @@ func TestDriveSync_folderCreationFailureCascades(t *testing.T) { } // new_local 上传失败 → 记 failed 并非零退出。 -func TestDriveSync_pushUploadFailureIsFailed(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_pushUploadFailureIsFailed(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "only-local.txt"), "x") SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) @@ -236,7 +239,7 @@ func TestDriveSync_pushUploadFailureIsFailed(t *testing.T) { // --on-conflict ask 的每个交互答案 // ────────────────────────────────────────────────────────── -func TestDriveSyncAskConflict_answers(t *testing.T) { +func TestCrossPlatformCoverageDriveSyncAskConflict_answers(t *testing.T) { cases := []struct { input string want string @@ -255,9 +258,7 @@ func TestDriveSyncAskConflict_answers(t *testing.T) { } for _, tc := range cases { t.Run(strings.TrimSpace(tc.input), func(t *testing.T) { - prev := syncAskStdin - syncAskStdin = strings.NewReader(tc.input) - t.Cleanup(func() { syncAskStdin = prev }) + testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader(tc.input))) got, err := driveSyncAskConflict("f.txt") if tc.isErr { @@ -277,10 +278,8 @@ func TestDriveSyncAskConflict_answers(t *testing.T) { } // ask 选到无效值时整个 sync 中止（错误上抛，不是静默跳过）。 -func TestDriveSync_askInvalidChoiceAborts(t *testing.T) { - prev := syncAskStdin - syncAskStdin = strings.NewReader("nonsense\n") - t.Cleanup(func() { syncAskStdin = prev }) +func TestCrossPlatformCoverageDriveSync_askInvalidChoiceAborts(t *testing.T) { + testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader("nonsense\n"))) dir := t.TempDir() p := filepath.Join(dir, "f.txt") @@ -299,10 +298,8 @@ func TestDriveSync_askInvalidChoiceAborts(t *testing.T) { } // ask 选 keep-both：本地改名保留副本，远端拉到原名。 -func TestDriveSync_askKeepBothViaStdin(t *testing.T) { - prev := syncAskStdin - syncAskStdin = strings.NewReader("k\n") - t.Cleanup(func() { syncAskStdin = prev }) +func TestCrossPlatformCoverageDriveSync_askKeepBothViaStdin(t *testing.T) { + testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader("k\n"))) dir := t.TempDir() p := filepath.Join(dir, "f.txt") @@ -338,7 +335,7 @@ func TestDriveSync_askKeepBothViaStdin(t *testing.T) { } // keep-both 改名失败（目标被目录占位）→ 记 failed，本地原文件保持不动。 -func TestDriveSync_keepBothRenameFailureKeepsLocal(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_keepBothRenameFailureKeepsLocal(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-version") @@ -367,7 +364,7 @@ func TestDriveSync_keepBothRenameFailureKeepsLocal(t *testing.T) { // ────────────────────────────────────────────────────────── // dry-run 下即使有 new_local / new_remote / modified 也不产生任何写调用。 -func TestDriveSync_dryRunSkipsEveryWrite(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_dryRunSkipsEveryWrite(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "local.txt"), "l") p := filepath.Join(dir, "both.txt") @@ -396,7 +393,7 @@ func TestDriveSync_dryRunSkipsEveryWrite(t *testing.T) { } // 远端列举失败 → sync 直接报错。 -func TestDriveSync_remoteListFailurePropagates(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_remoteListFailurePropagates(t *testing.T) { caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestList }} if err := runDriveCmd(t, caller, "sync", "--local-folder", t.TempDir(), "--remote-folder", "ROOT"); err == nil { t.Fatal("expected remote listing failure to propagate") @@ -404,7 +401,7 @@ func TestDriveSync_remoteListFailurePropagates(t *testing.T) { } // 本地根目录不存在 → 扫描失败上抛。 -func TestDriveSync_missingLocalRootFails(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_missingLocalRootFails(t *testing.T) { missing := filepath.Join(t.TempDir(), "absent") if err := runDriveCmd(t, syncCaller(nil), "sync", "--local-folder", missing, "--remote-folder", "ROOT"); err == nil { t.Fatal("expected missing local root to fail") diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go index 99f5ab3f..84843247 100644 --- a/internal/helpers/drive_sync_edges_test.go +++ b/internal/helpers/drive_sync_edges_test.go @@ -10,6 +10,7 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/spf13/cobra" ) @@ -46,7 +47,7 @@ func mustSetFlags(t *testing.T, cmd *cobra.Command, kv map[string]string) { // --if-exists 显式空值回落默认 // ────────────────────────────────────────────────────────── -func TestDrivePull_emptyIfExistsDefaultsToOverwrite(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToOverwrite(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "a.txt") mustWrite(t, p, "local-old") @@ -64,7 +65,7 @@ func TestDrivePull_emptyIfExistsDefaultsToOverwrite(t *testing.T) { } } -func TestDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "local") withNoopPut(t) @@ -85,7 +86,7 @@ func TestDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T) { // ────────────────────────────────────────────────────────── // 目标目录不可写 → 创建临时文件失败。 -func TestPullOneFile_tempFileCreationFailure(t *testing.T) { +func TestCrossPlatformCoveragePullOneFile_tempFileCreationFailure(t *testing.T) { if runtime.GOOS == "windows" || os.Geteuid() == 0 { t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") } @@ -108,7 +109,7 @@ func TestPullOneFile_tempFileCreationFailure(t *testing.T) { } // 目标路径是目录 → 最后的原子 rename 失败。 -func TestPullOneFile_renameOntoDirectoryFails(t *testing.T) { +func TestCrossPlatformCoveragePullOneFile_renameOntoDirectoryFails(t *testing.T) { root := t.TempDir() target := filepath.Join(root, "a.txt") if err := os.MkdirAll(target, 0o755); err != nil { // 目标被目录占位 @@ -137,7 +138,7 @@ func TestPullOneFile_renameOntoDirectoryFails(t *testing.T) { // PrintJSON 失败分支 // ────────────────────────────────────────────────────────── -func TestDrivePush_printFailurePropagates(t *testing.T) { +func TestCrossPlatformCoverageDrivePush_printFailurePropagates(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "x") withNoopPut(t) @@ -154,7 +155,7 @@ func TestDrivePush_printFailurePropagates(t *testing.T) { } } -func TestDriveSync_printFailurePropagates(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_printFailurePropagates(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "x") SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) @@ -176,7 +177,7 @@ func TestDriveSync_printFailurePropagates(t *testing.T) { // walkLocalForPush / walkLocalTree 的 WalkDir 错误回调 // ────────────────────────────────────────────────────────── -func TestWalkLocal_unreadableSubdirectoryErrors(t *testing.T) { +func TestCrossPlatformCoverageWalkLocal_unreadableSubdirectoryErrors(t *testing.T) { if runtime.GOOS == "windows" || os.Geteuid() == 0 { t.Skip("unreadable dir needs POSIX perms and a non-root user") } @@ -204,7 +205,7 @@ func TestWalkLocal_unreadableSubdirectoryErrors(t *testing.T) { // ────────────────────────────────────────────────────────── // 目标位于 absDir 之外 → 走到根目录之上即放行（不是逃逸判定范围）。 -func TestVerifyNoSymlinkEscape_targetOutsideRootIsIgnored(t *testing.T) { +func TestCrossPlatformCoverageVerifyNoSymlinkEscape_targetOutsideRootIsIgnored(t *testing.T) { root := t.TempDir() outside := filepath.Join(t.TempDir(), "elsewhere", "x.txt") if err := verifyNoSymlinkEscape(root, outside); err != nil { @@ -213,7 +214,7 @@ func TestVerifyNoSymlinkEscape_targetOutsideRootIsIgnored(t *testing.T) { } // 已存在路径含符号链接环 → EvalSymlinks 失败要如实上报。 -func TestVerifyNoSymlinkEscape_symlinkLoopErrors(t *testing.T) { +func TestCrossPlatformCoverageVerifyNoSymlinkEscape_symlinkLoopErrors(t *testing.T) { root := t.TempDir() loop := filepath.Join(root, "loop") if err := os.Symlink(loop, loop); err != nil { @@ -230,7 +231,7 @@ func TestVerifyNoSymlinkEscape_symlinkLoopErrors(t *testing.T) { // ────────────────────────────────────────────────────────── // 候选目标逃逸出本地根（父目录是指向外部的软链）→ 直接失败。 -func TestReserveSyncKeepBothTarget_escapeFails(t *testing.T) { +func TestCrossPlatformCoverageReserveSyncKeepBothTarget_escapeFails(t *testing.T) { root := t.TempDir() outside := t.TempDir() if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { @@ -242,7 +243,7 @@ func TestReserveSyncKeepBothTarget_escapeFails(t *testing.T) { } // 候选目标所在目录不可写 → OpenFile 以非 EEXIST 错误失败，直接上报。 -func TestReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { +func TestCrossPlatformCoverageReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { if runtime.GOOS == "windows" || os.Geteuid() == 0 { t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") } @@ -258,7 +259,7 @@ func TestReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { } // occupied 中已知占用的首选候选被跳过，改用下一个后缀。 -func TestReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) { +func TestCrossPlatformCoverageReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) { root := t.TempDir() first := syncKeepBothCandidate("f.txt", "FID12345678", 0) occupied := map[string]bool{first: true} @@ -276,10 +277,8 @@ func TestReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) { // ask 读取失败（非 EOF） // ────────────────────────────────────────────────────────── -func TestDriveSyncAskConflict_readErrorPropagates(t *testing.T) { - prev := syncAskStdin - syncAskStdin = errReader{} - t.Cleanup(func() { syncAskStdin = prev }) +func TestCrossPlatformCoverageDriveSyncAskConflict_readErrorPropagates(t *testing.T) { + testseam.Swap(t, &syncAskStdin, io.Reader(errReader{})) if _, err := driveSyncAskConflict("f.txt"); err == nil { t.Fatal("expected read failure to propagate") @@ -291,7 +290,7 @@ func TestDriveSyncAskConflict_readErrorPropagates(t *testing.T) { // ────────────────────────────────────────────────────────── // --local-folder 指向一个常规文件 → MkdirAll 失败。 -func TestDriveSync_localRootIsFileFails(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_localRootIsFileFails(t *testing.T) { dir := t.TempDir() asFile := filepath.Join(dir, "not-a-dir") mustWrite(t, asFile, "x") diff --git a/internal/helpers/drive_sync_platform_test.go b/internal/helpers/drive_sync_platform_test.go index 0705b61f..71f9313b 100644 --- a/internal/helpers/drive_sync_platform_test.go +++ b/internal/helpers/drive_sync_platform_test.go @@ -9,15 +9,15 @@ import ( "runtime" "testing" "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // forceCaseInsensitiveFS 在当前用例内把大小写探测钉成不敏感，使等价路径冲突分支 // 在大小写敏感的 CI 文件系统（ext4）上同样可达。 func forceCaseInsensitiveFS(t *testing.T) { t.Helper() - prev := isCaseInsensitiveFS - isCaseInsensitiveFS = func(string) bool { return true } - t.Cleanup(func() { isCaseInsensitiveFS = prev }) + testseam.Swap(t, &isCaseInsensitiveFS, func(string) bool { return true }) } // ────────────────────────────────────────────────────────── @@ -26,7 +26,7 @@ func forceCaseInsensitiveFS(t *testing.T) { // 远端 A.txt 与 a.txt 在大小写不敏感目标上映射到同一本地文件 → 两项都 failed， // 绝不顺序覆盖导致静默丢文件。 -func TestDrivePull_equivalentPathCollisionFailsBoth(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_equivalentPathCollisionFailsBoth(t *testing.T) { forceCaseInsensitiveFS(t) root := t.TempDir() @@ -52,7 +52,7 @@ func TestDrivePull_equivalentPathCollisionFailsBoth(t *testing.T) { } // sync 的 new_remote 阶段同样拒绝等价冲突项。 -func TestDriveSync_equivalentPathCollisionFailsBoth(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_equivalentPathCollisionFailsBoth(t *testing.T) { forceCaseInsensitiveFS(t) root := t.TempDir() withSyncTransport(t, "remote") @@ -77,10 +77,9 @@ func TestDriveSync_equivalentPathCollisionFailsBoth(t *testing.T) { // detectCaseInsensitiveFS：探针名无大小写差异时回退平台默认 // ────────────────────────────────────────────────────────── -func TestDetectCaseInsensitiveFS_caselessProbeFallsBackToPlatformDefault(t *testing.T) { - prev := caseProbePattern - caseProbePattern = "1234567890*" // 纯数字：ToUpper 与原名相同，无法据此判定 - t.Cleanup(func() { caseProbePattern = prev }) +func TestCrossPlatformCoverageDetectCaseInsensitiveFS_caselessProbeFallsBackToPlatformDefault(t *testing.T) { + // 纯数字模板：ToUpper 与原名相同，无法据此判定。 + testseam.Swap(t, &caseProbePattern, "1234567890*") dir := t.TempDir() got := detectCaseInsensitiveFS(dir) @@ -95,7 +94,7 @@ func TestDetectCaseInsensitiveFS_caselessProbeFallsBackToPlatformDefault(t *test // isSafeRemoteSegmentPlatform：非 Windows 平台无额外约束 // ────────────────────────────────────────────────────────── -func TestIsSafeRemoteSegmentPlatform_allowsPlainNames(t *testing.T) { +func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_allowsPlainNames(t *testing.T) { for _, name := range []string{"a.txt", "报告.pdf", "with space.md", "..."} { if !isSafeRemoteSegmentPlatform(name) { t.Errorf("isSafeRemoteSegmentPlatform(%q) = false, want true", name) @@ -134,7 +133,7 @@ func (irregularFileInfo) ModTime() time.Time { return time.Unix(0, 0) } func (irregularFileInfo) IsDir() bool { return false } func (irregularFileInfo) Sys() any { return nil } -func TestWalkLocalTreeEntry_errorBranches(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalTreeEntry_errorBranches(t *testing.T) { files := map[string]*localFile{} // WalkDir 自身报错原样上抛。 @@ -179,7 +178,7 @@ func (regularFileInfo) ModTime() time.Time { return time.Unix(1, 0) } func (regularFileInfo) IsDir() bool { return false } func (regularFileInfo) Sys() any { return nil } -func TestWalkLocalForPushEntry_errorBranches(t *testing.T) { +func TestCrossPlatformCoverageWalkLocalForPushEntry_errorBranches(t *testing.T) { var dirs []string var files []localPushFile diff --git a/internal/helpers/drive_sync_test.go b/internal/helpers/drive_sync_test.go index fed0a21b..6dab3f7b 100644 --- a/internal/helpers/drive_sync_test.go +++ b/internal/helpers/drive_sync_test.go @@ -10,6 +10,7 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/spf13/cobra" ) @@ -20,7 +21,7 @@ var errTestDownload = errors.New("simulated download failure") // driveSyncFailure — sync 部分失败错误：exit=1 // ────────────────────────────────────────────────────────── -func TestDriveSyncFailure(t *testing.T) { +func TestCrossPlatformCoverageDriveSyncFailure(t *testing.T) { e := &driveSyncFailure{failed: 2} if e.ExitCode() != 1 { t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) @@ -37,7 +38,7 @@ func TestDriveSyncFailure(t *testing.T) { // driveSyncSuffixedRel — keep-both 本地重命名目标生成 // ────────────────────────────────────────────────────────── -func TestDriveSyncSuffixedRel(t *testing.T) { +func TestCrossPlatformCoverageDriveSyncSuffixedRel(t *testing.T) { // 基本：扩展名前插入基于 fileId 末 8 位的后缀。 got := driveSyncSuffixedRel("a/b.txt", "0123456789ABCDEF", map[string]bool{}) if want := "a/b.conflict-89ABCDEF.txt"; got != want { @@ -104,7 +105,7 @@ func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn fu } // 双向：本地独有 local.txt 应上传；远端独有 remote.txt 应下载到本地。 -func TestDriveSync_bidirectional(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_bidirectional(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "local.txt"), "local-only") @@ -139,7 +140,7 @@ func TestDriveSync_bidirectional(t *testing.T) { } // modified + remote-wins：quick 模式下两侧 mtime 不同判为 modified，默认拉取远端覆盖本地。 -func TestDriveSync_modifiedRemoteWins(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_modifiedRemoteWins(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-old") @@ -167,7 +168,7 @@ func TestDriveSync_modifiedRemoteWins(t *testing.T) { } // modified + local-wins：改用 local-wins 时应覆盖上传远端（传 overwriteFileId、不传 parentId）。 -func TestDriveSync_modifiedLocalWins(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_modifiedLocalWins(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-new") @@ -197,7 +198,7 @@ func TestDriveSync_modifiedLocalWins(t *testing.T) { } // --dry-run：只计算差异，不触发任何 MCP 写操作与本地落盘。 -func TestDriveSync_dryRun(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_dryRun(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "local.txt"), "x") @@ -219,7 +220,7 @@ func TestDriveSync_dryRun(t *testing.T) { // remote-wins 下载失败：本地原文件必须原样保留（pullOneFile 先写临时文件、成功才原子 // rename 覆盖），且命令以非零退出码退出。 -func TestDriveSync_pullFailureKeepsLocal(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_pullFailureKeepsLocal(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-original") @@ -248,7 +249,7 @@ func TestDriveSync_pullFailureKeepsLocal(t *testing.T) { // keep-both 成功路径：本地既有文件改名保留（os.Rename 覆盖 O_EXCL 空占位），远端拉取到 // 原路径。此测试在 Windows 主机上运行即验证 os.Rename 可替换既有目标（MOVEFILE_REPLACE_ // EXISTING），覆盖 pull 覆盖与 keep-both 两条 rename 路径的平台行为。 -func TestDriveSync_keepBothSuccess(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_keepBothSuccess(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-new") @@ -282,7 +283,7 @@ func TestDriveSync_keepBothSuccess(t *testing.T) { // keep-both 下载失败：改名保留后拉取远端失败，应回滚改名——原文件恢复原名原内容， // 不留下改名后的残留文件。 -func TestDriveSync_keepBothRollbackOnPullFailure(t *testing.T) { +func TestCrossPlatformCoverageDriveSync_keepBothRollbackOnPullFailure(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-original") @@ -314,7 +315,7 @@ func TestDriveSync_keepBothRollbackOnPullFailure(t *testing.T) { // reserveSyncKeepBothTarget 不得占用「精确同名」的既有文件（occupied 未记录时）， // 应原子占位到下一个后缀，且既有文件内容不被破坏。此断言在任何文件系统上都成立。 -func TestReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) { +func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) { dir := t.TempDir() // 预置一个与首选候选精确同名的既有文件（模拟未被 occupied 记录的外部残留）。 first := "f.conflict-ABCD1234.txt" @@ -342,7 +343,7 @@ func TestReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) { // reserveSyncKeepBothTarget 在大小写不敏感文件系统上，不得覆盖与候选「大小写等价」的 // 既有文件——O_EXCL 由 OS 兜底判等价性，occupied 的精确字符串键覆盖不到这种情况。 -func TestReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) { +func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) { dir := t.TempDir() if !isCaseInsensitiveFS(dir) { t.Skip("文件系统大小写敏感，跳过大小写等价覆盖测试") @@ -367,10 +368,8 @@ func TestReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) { // 非交互 ask（stdin 立即 EOF）：冲突项应被跳过而非中止整个同步， // new_local 仍上传、new_remote 仍下载，且被跳过的 modified 本地文件不被改动。 -func TestDriveSync_askNonInteractiveSkipsConflict(t *testing.T) { - prev := syncAskStdin - syncAskStdin = strings.NewReader("") // 非交互：立即 EOF - t.Cleanup(func() { syncAskStdin = prev }) +func TestCrossPlatformCoverageDriveSync_askNonInteractiveSkipsConflict(t *testing.T) { + testseam.Swap(t, &syncAskStdin, io.Reader(strings.NewReader(""))) // 非交互：立即 EOF dir := t.TempDir() mustWrite(t, filepath.Join(dir, "local.txt"), "local-only") // new_local → 应上传 From 56bb50913b2f5094525d96ca343cc898ff722a60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 16:23:13 +0800 Subject: [PATCH 012/250] feat(chat): default message query time ranges --- internal/helpers/chat.go | 112 +++++++++--------- internal/helpers/chat_message_help_test.go | 93 +++++++++++++++ .../helpers/chat_message_pagination_test.go | 84 +++++++++++++ .../helpers/im_read_result_contract_test.go | 38 +++++- test/fixtures/cli-interface-baseline.txt | 8 +- 5 files changed, 275 insertions(+), 60 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 3bf56fe6..3cc7a516 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -467,22 +467,17 @@ func validateNativeSearchConversationScope(conversationIDs []string) error { } func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { - if err := validateRequiredFlags(cmd, "start", "end"); err != nil { - return nil, err - } + startRaw, endRaw := defaultChatMessageTimeRange(cmd, 24*time.Hour) cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ - "startTime": mustGetFlag(cmd, "start"), - "endTime": mustGetFlag(cmd, "end"), + "startTime": startRaw, + "endTime": endRaw, "limit": chatIntFlagOrFallback(cmd, "limit", "size"), "cursor": cursor, }, nil } func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { - if err := validateRequiredFlags(cmd, "start"); err != nil { - return nil, err - } senderUserID := flagOrFallback(cmd, "sender-user-id", "sender") senderOpenDingTalkID, _ := cmd.Flags().GetString("sender-open-dingtalk-id") if senderUserID != "" && senderOpenDingTalkID != "" { @@ -491,14 +486,11 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { if senderUserID == "" && senderOpenDingTalkID == "" { return nil, fmt.Errorf("--sender-user-id or --sender-open-dingtalk-id is required") } - startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start")) + startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err } - endRaw, _ := cmd.Flags().GetString("end") - if strings.TrimSpace(endRaw) == "" { - endRaw = time.Now().Format(time.RFC3339) - } endMs, err := parseISOTimeToMillis("end", endRaw) if err != nil { return nil, err @@ -522,14 +514,12 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { } func chatMessageListMentionsArgs(cmd *cobra.Command) (map[string]any, error) { - if err := validateRequiredFlags(cmd, "start", "end"); err != nil { - return nil, err - } - startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start")) + startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err } - endMs, err := parseISOTimeToMillis("end", mustGetFlag(cmd, "end")) + endMs, err := parseISOTimeToMillis("end", endRaw) if err != nil { return nil, err } @@ -564,14 +554,12 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) { if err := validateRequiredFlagWithAliases(cmd, "query", "keyword"); err != nil { return nil, err } - if err := validateRequiredFlags(cmd, "start", "end"); err != nil { - return nil, err - } - startMs, err := parseISOTimeToMillis("start", mustGetFlag(cmd, "start")) + startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err } - endMs, err := parseISOTimeToMillis("end", mustGetFlag(cmd, "end")) + endMs, err := parseISOTimeToMillis("end", endRaw) if err != nil { return nil, err } @@ -592,6 +580,19 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) { return toolArgs, nil } +func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string) { + startRaw := mustGetFlag(cmd, "start") + endRaw := mustGetFlag(cmd, "end") + now := time.Now() + if endRaw == "" { + endRaw = now.Format(time.RFC3339) + } + if startRaw == "" { + startRaw = now.Add(-lookback).Format(time.RFC3339) + } + return startRaw, endRaw +} + func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { toolArgs := map[string]any{} if v := flagOrFallback(cmd, "query", "keyword"); v != "" { @@ -2605,8 +2606,9 @@ func newChatCommand() *cobra.Command { chatMessageListCmd := &cobra.Command{ Use: "list", Short: "拉取会话消息内容", - Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, - Example: ` dws chat message list --group --time "2025-03-01 00:00:00" + Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。--time 可选，不传时默认当前时间并向旧消息拉取。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, + Example: ` dws chat message list --group + dws chat message list --group --time "2025-03-01 00:00:00" dws chat message list --user --time "2025-03-01 00:00:00" --limit 50 dws chat message list --open-dingtalk-id --time "2025-03-01 00:00:00" --limit 50 dws chat message list --group --time "2025-03-01 00:00:00" --direction older @@ -2614,9 +2616,6 @@ func newChatCommand() *cobra.Command { # 查询群 ID: dws chat search --query "群名" # 查询 userId: dws contact user search --query "姓名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "time"); err != nil { - return err - } groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") userID, _ := cmd.Flags().GetString("user") openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") @@ -2640,11 +2639,16 @@ func newChatCommand() *cobra.Command { openDingTalkID = userID userID = "" } - forward, err := resolveMessageForward(cmd, true) + timeVal := mustGetFlag(cmd, "time") + defaultForward := true + if timeVal == "" { + timeVal = time.Now().Format("2006-01-02 15:04:05") + defaultForward = false + } + forward, err := resolveMessageForward(cmd, defaultForward) if err != nil { return err } - timeVal := mustGetFlag(cmd, "time") if groupID != "" { toolArgs := map[string]any{ "openconversation_id": groupID, @@ -2695,6 +2699,7 @@ func newChatCommand() *cobra.Command { UseWhen: []string{"用户明确指定某个会话，并要读取消息或追溯引用回复中的原消息上下文时"}, AvoidWhen: []string{"跨全部会话按时间查询时使用 chat message list-all"}, Examples: []string{ + "dws chat message list --group --limit 50", "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50", "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", }, @@ -3483,7 +3488,7 @@ func newChatCommand() *cobra.Command { chatMessageListAllCmd := &cobra.Command{ Use: "list-all", Short: "拉取指定时间范围内当前用户的所有会话消息", - Long: `分页拉取当前登录用户在指定时间范围内的所有会话消息。--start 和 --end 限定时间范围，--limit 指定每页数量，--cursor 传分页游标（首页传 0）。服务端按 cursor 分页返回，hasMore=true 时用返回的 nextCursor 值继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。如果当前账号没有消息搜索权益，CLI 会保留服务端返回的友好提示与开通入口；不要把权限错误解释为时间范围内没有消息。`, + Long: `分页拉取当前登录用户在指定时间范围内的所有会话消息。--start 和 --end 可选，不传时默认最近 1 天到当前时间，避免跨全部会话范围过大；--limit 指定每页数量，--cursor 传分页游标（首页传 0）。服务端按 cursor 分页返回，hasMore=true 时用返回的 nextCursor 值继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。如果当前账号没有消息搜索权益，CLI 会保留服务端返回的友好提示与开通入口；不要把权限错误解释为时间范围内没有消息。`, Example: ` dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50 dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50 --cursor "abc123token" dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 100 --page-all --page-limit 20 --max-items 500 --page-delay 0`, @@ -3530,7 +3535,7 @@ func newChatCommand() *cobra.Command { chatMessageListBySenderCmd := &cobra.Command{ Use: "list-by-sender", Short: "拉取指定发送者的消息（包含单聊和群聊）", - Long: `搜索特定人发送给我的消息，返回结果包含单聊和群聊标识。--sender-user-id 指定发送者 userId，--sender-open-dingtalk-id 指定发送者 openDingTalkId，二者互斥。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, + Long: `搜索特定人发送给我的消息，返回结果包含单聊和群聊标识。--sender-user-id 指定发送者 userId，--sender-open-dingtalk-id 指定发送者 openDingTalkId，二者互斥。--start 和 --end 可选，不传时默认最近 7 天到当前时间。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, Example: ` dws chat message list-by-sender --sender-user-id --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 dws chat message list-by-sender --sender-open-dingtalk-id --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 dws chat message list-by-sender --sender-user-id --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --limit 20 --cursor 0 @@ -3582,7 +3587,7 @@ func newChatCommand() *cobra.Command { chatMessageListMentionsCmd := &cobra.Command{ Use: "list-mentions", Short: "拉取 @我 的消息", - Long: `搜索时间范围内 @我 的消息，可选指定群聊。返回结果包含单聊和群聊标识。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, + Long: `搜索时间范围内 @我 的消息，可选指定群聊。--start 和 --end 可选，不传时默认最近 7 天到当前时间。返回结果包含单聊和群聊标识。分页参数 --limit（默认 50）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持单页调用。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, Example: ` dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 dws chat message list-mentions --start "2026-04-01T00:00:00+08:00" --end "2026-04-14T00:00:00+08:00" --limit 20 --cursor 0 dws chat message list-mentions --group --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0 @@ -3770,7 +3775,7 @@ func newChatCommand() *cobra.Command { chatMessageSearchCmd := &cobra.Command{ Use: "search", Short: "按关键词搜索消息", - Long: `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --group 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）限定搜索时间范围。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, + Long: `在当前用户的会话中按关键词搜索消息。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId、content 和原始 result。--query 指定搜索关键词（必填）。可选 --group 限定搜索某个会话，不传则搜索所有会话。显式指定会话时，CLI 会先验证 CID，再扫描全局搜索流并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID；默认最多扫描 40 页并返回至 --limit 条范围内消息。时间参数 --start/--end（ISO-8601）可选，不传时默认最近 7 天到当前时间。分页参数 --limit（默认 100）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。未指定会话时默认只读取单页；只有显式传 --page-all 才会自动翻页并保留、合并 result.conversationMessagesList，同一会话跨页合并 messages。只传 --page-limit、--max-items 或 --page-delay 仍保持默认行为。自动翻页时 --page-limit 控制最多请求页数，--max-items 按消息数精确截断，--page-delay 控制页间等待毫秒数。`, Example: ` dws chat message search --query "changefree" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 50 --cursor 0 dws chat message search --query "codereview" --group --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --cursor 0 dws chat message search --query "链接" --start "2026-04-15T00:00:00+08:00" --end "2026-04-16T00:00:00+08:00" --limit 100 --cursor @@ -4328,9 +4333,9 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageListCmd.Flags().String("group", "", "群聊 openconversation_id（群聊时必填）") chatMessageListCmd.Flags().String("user", "", "单聊用户 userId（单聊时与 --open-dingtalk-id 二选一）") chatMessageListCmd.Flags().String("open-dingtalk-id", "", "单聊用户 openDingTalkId（单聊时与 --user 二选一，适用于无法获取 userId 的场景）") - chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)") - chatMessageListCmd.Flags().String("direction", "", "时间方向: newer=从给定时间往现在拉，older=从给定时间往以前拉（推荐）") - chatMessageListCmd.Flags().String("forward", "true", "true 等价 --direction newer，false 等价 --direction older") + chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间）") + chatMessageListCmd.Flags().String("direction", "", "时间方向: newer=从给定时间往现在拉，older=从给定时间往以前拉（未传 --time 时默认 older）") + chatMessageListCmd.Flags().String("forward", "true", "true 等价 --direction newer，false 等价 --direction older（未传 --time 时默认 false）") _ = chatMessageListCmd.Flags().MarkHidden("forward") chatMessageListCmd.Flags().Int("limit", 0, "返回数量，不传则不限制") chatMessageListCmd.Flags().Int("size", 0, "--limit 的旧版别名") @@ -4444,10 +4449,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageListTopicRepliesCmd.Flags().String("forward", "false", "true 等价 --direction newer，false 等价 --direction older（默认 false）") _ = chatMessageListTopicRepliesCmd.Flags().MarkHidden("forward") - chatMessageListAllCmd.Flags().String("start", "", "起始时间，格式: yyyy-MM-dd HH:mm:ss (必填)") - _ = chatMessageListAllCmd.MarkFlagRequired("start") - chatMessageListAllCmd.Flags().String("end", "", "结束时间，格式: yyyy-MM-dd HH:mm:ss (必填)") - _ = chatMessageListAllCmd.MarkFlagRequired("end") + chatMessageListAllCmd.Flags().String("start", "", "起始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间前 1 天）") + chatMessageListAllCmd.Flags().String("end", "", "结束时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间）") chatMessageListAllCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）") chatMessageListAllCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageListAllCmd.Flags().MarkHidden("size") @@ -4461,9 +4464,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageListBySenderCmd.Flags().String("sender-open-dingtalk-id", "", "发送者 openDingTalkId（与 --sender-user-id 二选一，适用于无法获取 userId 的场景）") chatMessageListBySenderCmd.Flags().String("user", "", "") _ = chatMessageListBySenderCmd.Flags().MarkHidden("user") - chatMessageListBySenderCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)") - _ = chatMessageListBySenderCmd.MarkFlagRequired("start") - chatMessageListBySenderCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)") + chatMessageListBySenderCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）") + chatMessageListBySenderCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）") chatMessageListBySenderCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）") chatMessageListBySenderCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageListBySenderCmd.Flags().MarkHidden("size") @@ -4472,10 +4474,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 // list-mentions flags chatMessageListMentionsCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则查全部）") - chatMessageListMentionsCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)") - _ = chatMessageListMentionsCmd.MarkFlagRequired("start") - chatMessageListMentionsCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)") - _ = chatMessageListMentionsCmd.MarkFlagRequired("end") + chatMessageListMentionsCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）") + chatMessageListMentionsCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）") chatMessageListMentionsCmd.Flags().Int("limit", 50, "每页返回数量（默认 50）") chatMessageListMentionsCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageListMentionsCmd.Flags().MarkHidden("size") @@ -4500,10 +4500,8 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 chatMessageSearchCmd.Flags().String("keyword", "", "--query 的别名") _ = chatMessageSearchCmd.Flags().MarkHidden("keyword") chatMessageSearchCmd.Flags().String("group", "", "群聊 openconversation_id（可选，不传则搜索所有会话）") - chatMessageSearchCmd.Flags().String("start", "", "开始时间，ISO-8601 格式 (必填)") - _ = chatMessageSearchCmd.MarkFlagRequired("start") - chatMessageSearchCmd.Flags().String("end", "", "结束时间，ISO-8601 格式 (必填)") - _ = chatMessageSearchCmd.MarkFlagRequired("end") + chatMessageSearchCmd.Flags().String("start", "", "开始时间，ISO-8601 格式（可选，默认当前时间前 7 天）") + chatMessageSearchCmd.Flags().String("end", "", "结束时间，ISO-8601 格式（可选，默认当前时间）") chatMessageSearchCmd.Flags().Int("limit", 100, "每页返回数量（默认 100）") chatMessageSearchCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageSearchCmd.Flags().MarkHidden("size") @@ -5913,6 +5911,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Short: "下载消息中的资源（图片/视频/语音等）到本地", Long: `下载聊天消息中的图片、视频、语音等资源到本地文件。 +本命令只支持聊天消息 mediaId 下载，不支持钉盘 fileId。 +如需用 fileId 下载，请使用钉盘/drive 下载命令。 + 流程: 1. 根据 resourceType + resource-id + message-id + open-conversation-id 向服务端获取下载 URL 2. HTTP GET 下载文件到本地 @@ -5923,6 +5924,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 dws chat message download-media --type mediaId --resource-id --message-id --open-conversation-id --output ./downloads/ dws chat message download-media --type mediaId --resource-id --message-id --open-conversation-id --output ./photo.jpg # resource-id: 从 dws chat message list 返回的消息内容中获取 mediaId + # 不支持钉盘 fileId；fileId 下载请使用钉盘/drive 下载命令 # message-id: 从 dws chat message list 返回的 openMessageId # open-conversation-id: 从 dws chat search 获取 openConversationId`, PreRunE: func(cmd *cobra.Command, args []string) error { @@ -6052,16 +6054,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Selection: contract.SelectionSpec{ AgentSummary: "下载消息中的媒体资源到本地", UseWhen: []string{"已知消息、会话和资源 ID，需要保存媒体文件时"}, - AvoidWhen: []string{"只查看文本消息内容时使用对应消息查询命令"}, + AvoidWhen: []string{"只查看文本消息内容时使用对应消息查询命令", "资源是钉盘 fileId 时使用钉盘/drive 下载命令"}, Examples: []string{"dws chat message download-media --type mediaId --resource-id --message-id --open-conversation-id --output ."}, }, }, }) // download-media flags - chatMessageDownloadMediaCmd.Flags().String("type", "", "资源类型: mediaId (必填)") + chatMessageDownloadMediaCmd.Flags().String("type", "", "资源类型: mediaId（必填；仅支持聊天消息 mediaId，不支持钉盘 fileId）") _ = chatMessageDownloadMediaCmd.MarkFlagRequired("type") - chatMessageDownloadMediaCmd.Flags().String("resource-id", "", "资源 ID，mediaId 类型时为消息中的 mediaId 值 (必填)") + chatMessageDownloadMediaCmd.Flags().String("resource-id", "", "资源 ID，mediaId 类型时为消息中的 mediaId 值（必填；不是钉盘 fileId）") _ = chatMessageDownloadMediaCmd.MarkFlagRequired("resource-id") chatMessageDownloadMediaCmd.Flags().String("open-conversation-id", "", "会话 openConversationId (必填)") _ = chatMessageDownloadMediaCmd.MarkFlagRequired("open-conversation-id") diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index fcf1548c..6941e2e8 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -90,3 +90,96 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing }) } } + +func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *testing.T) { + tests := []struct { + name string + args []string + contains []string + absent []string + }{ + { + name: "list", + args: []string{"message", "list", "--help"}, + contains: []string{ + "--time 可选，不传时默认当前时间并向旧消息拉取", + "默认当前时间", + "未传 --time 时默认 older", + }, + absent: []string{"开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)"}, + }, + { + name: "search", + args: []string{"message", "search", "--help"}, + contains: []string{ + "可选，不传时默认最近 7 天到当前时间", + "默认当前时间前 7 天", + "默认当前时间", + }, + absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"}, + }, + { + name: "list-by-sender", + args: []string{"message", "list-by-sender", "--help"}, + contains: []string{ + "--start 和 --end 可选，不传时默认最近 7 天到当前时间", + "默认当前时间前 7 天", + "默认当前时间", + }, + absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"}, + }, + { + name: "list-mentions", + args: []string{"message", "list-mentions", "--help"}, + contains: []string{ + "--start 和 --end 可选，不传时默认最近 7 天到当前时间", + "默认当前时间前 7 天", + "默认当前时间", + }, + absent: []string{"开始时间，ISO-8601 格式 (必填)", "结束时间，ISO-8601 格式 (必填)"}, + }, + { + name: "list-all", + args: []string{"message", "list-all", "--help"}, + contains: []string{ + "--start 和 --end 可选，不传时默认最近 1 天到当前时间", + "默认当前时间前 1 天", + "默认当前时间", + }, + absent: []string{"起始时间，格式: yyyy-MM-dd HH:mm:ss (必填)", "结束时间，格式: yyyy-MM-dd HH:mm:ss (必填)"}, + }, + { + name: "download-media", + args: []string{"message", "download-media", "--help"}, + contains: []string{ + "只支持聊天消息 mediaId 下载，不支持钉盘 fileId", + "fileId 下载请使用钉盘/drive 下载命令", + "仅支持聊天消息 mediaId，不支持钉盘 fileId", + }, + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) + cmd.SetArgs(test.args) + if err := cmd.Execute(); err != nil { + t.Fatalf("dws chat %s: %v\n%s", strings.Join(test.args, " "), err, output.String()) + } + help := output.String() + for _, want := range test.contains { + if !strings.Contains(help, want) { + t.Errorf("chat message %s help missing %q:\n%s", test.name, want, help) + } + } + for _, unwanted := range test.absent { + if strings.Contains(help, unwanted) { + t.Errorf("chat message %s help still contains %q:\n%s", test.name, unwanted, help) + } + } + }) + } +} diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 21bac2c7..2b6c28ab 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -148,6 +148,90 @@ func TestChatMessagePaginationDefaultSinglePageUnchanged(t *testing.T) { } } +func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) { + tests := []struct { + name string + args []string + wantTool string + wantLookback time.Duration + }{ + { + name: "list-all defaults to one day", + args: []string{"message", "list-all"}, + wantTool: "search_messages_by_time_range", + wantLookback: 24 * time.Hour, + }, + { + name: "list-by-sender defaults to seven days", + args: []string{"message", "list-by-sender", "--sender-user-id", "u1"}, + wantTool: "search_messages_by_sender", + wantLookback: 7 * 24 * time.Hour, + }, + { + name: "list-mentions defaults to seven days", + args: []string{"message", "list-mentions"}, + wantTool: "search_at_me_message", + wantLookback: 7 * 24 * time.Hour, + }, + { + name: "search defaults to seven days", + args: []string{"message", "search", "--query", "发布"}, + wantTool: "search_messages_by_keyword", + wantLookback: 7 * 24 * time.Hour, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatMessagePaginationCaller{} + before := time.Now() + _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) + after := time.Now() + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one call", caller.calls) + } + got := caller.calls[0] + if got.tool != tt.wantTool { + t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) + } + startMs := numericArgAsInt64(t, got.args["startTime"]) + endMs := numericArgAsInt64(t, got.args["endTime"]) + if endMs < before.UnixMilli() || endMs > after.Add(time.Second).UnixMilli() { + t.Fatalf("endTime = %d, want between %d and %d", endMs, before.UnixMilli(), after.Add(time.Second).UnixMilli()) + } + wantStartMin := before.Add(-tt.wantLookback).UnixMilli() + wantStartMax := after.Add(-tt.wantLookback).Add(time.Second).UnixMilli() + if startMs < wantStartMin || startMs > wantStartMax { + t.Fatalf("startTime = %d, want between %d and %d", startMs, wantStartMin, wantStartMax) + } + }) + } +} + +func numericArgAsInt64(t *testing.T, value any) int64 { + t.Helper() + switch v := value.(type) { + case int64: + return v + case int: + return int64(v) + case float64: + return int64(v) + case string: + parsed, err := parseISOTimeToMillis("time", v) + if err != nil { + t.Fatalf("parse time arg %q: %v", v, err) + } + return parsed + default: + t.Fatalf("unsupported numeric arg type %T (%#v)", value, value) + return 0 + } +} + func TestChatMessagePaginationPageAllAggregatesSevenCommands(t *testing.T) { tests := []struct { name string diff --git a/internal/helpers/im_read_result_contract_test.go b/internal/helpers/im_read_result_contract_test.go index 3cff91cc..d2df5bc2 100644 --- a/internal/helpers/im_read_result_contract_test.go +++ b/internal/helpers/im_read_result_contract_test.go @@ -22,6 +22,7 @@ import ( "os" "reflect" "testing" + "time" "github.com/spf13/cobra" @@ -39,11 +40,16 @@ type imReadResultCaller struct { results map[string]*edition.ToolResult errors map[string]error calls []imReadResultCall + args map[string]any dryRun bool } -func (c *imReadResultCaller) CallTool(_ context.Context, productID, toolName string, _ map[string]any) (*edition.ToolResult, error) { +func (c *imReadResultCaller) CallTool(_ context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) { c.calls = append(c.calls, imReadResultCall{productID: productID, toolName: toolName}) + c.args = map[string]any{} + for k, v := range args { + c.args[k] = v + } if err := c.errors[toolName]; err != nil { return nil, err } @@ -203,6 +209,36 @@ func TestCrossPlatformCoverageChatMessageListProjectsStableFieldsAndPreservesLeg } } +func TestCrossPlatformCoverageChatMessageListDefaultsTimeAndOlderDirection(t *testing.T) { + payload := `{"result":{"messages":[],"hasMore":false}}` + caller := &imReadResultCaller{responses: map[string]string{"list_conversation_message_v2": payload}} + + before := time.Now() + _, err := executeIMReadCommand(t, caller, []string{"dws", "chat"}, newChatCommand, + "message", "list", "--group", "cid-1", "--limit", "50") + after := time.Now() + if err != nil { + t.Fatalf("chat message list returned error: %v", err) + } + if len(caller.calls) != 1 || caller.calls[0] != (imReadResultCall{productID: "chat", toolName: "list_conversation_message_v2"}) { + t.Fatalf("calls = %#v, want chat/list_conversation_message_v2", caller.calls) + } + if got := caller.args["forward"]; got != false { + t.Fatalf("forward = %#v, want false when --time is omitted", got) + } + timeRaw, ok := caller.args["time"].(string) + if !ok || strings.TrimSpace(timeRaw) == "" { + t.Fatalf("time arg = %#v, want generated current time", caller.args["time"]) + } + gotTime, err := time.ParseInLocation("2006-01-02 15:04:05", timeRaw, time.Local) + if err != nil { + t.Fatalf("parse generated time %q: %v", timeRaw, err) + } + if gotTime.Before(before.Add(-time.Second)) || gotTime.After(after.Add(time.Second)) { + t.Fatalf("time = %s, want between %s and %s", gotTime, before, after) + } +} + func TestCrossPlatformCoverageChatMessageSearchProjectsStableFieldsAndPreservesLegacy(t *testing.T) { payload := `{ "result": { diff --git a/test/fixtures/cli-interface-baseline.txt b/test/fixtures/cli-interface-baseline.txt index fab13963..db802415 100644 --- a/test/fixtures/cli-interface-baseline.txt +++ b/test/fixtures/cli-interface-baseline.txt @@ -2692,7 +2692,7 @@ [chat.message.list-all] runnable: true hidden: false - flags: --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=true|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=true|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited + flags: --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=false|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=false|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited [chat.message.list-by-ids] runnable: true @@ -2702,7 +2702,7 @@ [chat.message.list-by-sender] runnable: true hidden: false - flags: --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=false|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --sender:string|required=false|hidden=true|no-opt=""|scope=local, --sender-open-dingtalk-id:string|required=false|hidden=false|no-opt=""|scope=local, --sender-user-id:string|required=false|hidden=false|no-opt=""|scope=local, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=true|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, --user:string|required=false|hidden=true|no-opt=""|scope=local, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited + flags: --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=false|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --sender:string|required=false|hidden=true|no-opt=""|scope=local, --sender-open-dingtalk-id:string|required=false|hidden=false|no-opt=""|scope=local, --sender-user-id:string|required=false|hidden=false|no-opt=""|scope=local, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=false|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, --user:string|required=false|hidden=true|no-opt=""|scope=local, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited [chat.message.list-emotion-replies] runnable: true @@ -2722,7 +2722,7 @@ [chat.message.list-mentions] runnable: true hidden: false - flags: --chat:string|required=false|hidden=true|no-opt=""|scope=local, --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --conversation-id:string|required=false|hidden=true|no-opt=""|scope=local, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=true|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, --group:string|required=false|hidden=false|no-opt=""|scope=local, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --id:string|required=false|hidden=true|no-opt=""|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=true|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited + flags: --chat:string|required=false|hidden=true|no-opt=""|scope=local, --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --conversation-id:string|required=false|hidden=true|no-opt=""|scope=local, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=false|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, --group:string|required=false|hidden=false|no-opt=""|scope=local, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --id:string|required=false|hidden=true|no-opt=""|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=false|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited [chat.message.list-pin-msg] runnable: true @@ -2782,7 +2782,7 @@ [chat.message.search] runnable: true hidden: false - flags: --chat:string|required=false|hidden=true|no-opt=""|scope=local, --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --conversation-id:string|required=false|hidden=true|no-opt=""|scope=local, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=true|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, --group:string|required=false|hidden=false|no-opt=""|scope=local, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --id:string|required=false|hidden=true|no-opt=""|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --keyword:string|required=false|hidden=true|no-opt=""|scope=local, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --query:string|required=false|hidden=false|no-opt=""|scope=local, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=true|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited + flags: --chat:string|required=false|hidden=true|no-opt=""|scope=local, --client-id:string|required=false|hidden=false|no-opt=""|scope=inherited, --client-secret:string|required=false|hidden=false|no-opt=""|scope=inherited, --conversation-id:string|required=false|hidden=true|no-opt=""|scope=local, --cursor:string|required=false|hidden=false|no-opt=""|scope=local, --debug:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=inherited, --end:string|required=false|hidden=false|no-opt=""|scope=local, --fields:string|required=false|hidden=false|no-opt=""|scope=inherited, -f/--format:string|required=false|hidden=false|no-opt=""|scope=inherited, --group:string|required=false|hidden=false|no-opt=""|scope=local, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --id:string|required=false|hidden=true|no-opt=""|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=inherited, --keyword:string|required=false|hidden=true|no-opt=""|scope=local, --limit:int|required=false|hidden=false|no-opt=""|scope=local, --mock:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -o/--output:string|required=false|hidden=true|no-opt=""|scope=inherited, --profile:string|required=false|hidden=false|no-opt=""|scope=inherited, --query:string|required=false|hidden=false|no-opt=""|scope=local, --size:int|required=false|hidden=true|no-opt=""|scope=local, --start:string|required=false|hidden=false|no-opt=""|scope=local, --timeout:int|required=false|hidden=false|no-opt=""|scope=inherited, --token:string|required=false|hidden=true|no-opt=""|scope=inherited, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=inherited, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=inherited [chat.message.search-advanced] runnable: true From a53971b146860f20852c6ccba90540129a116b37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 16:23:17 +0800 Subject: [PATCH 013/250] feat(cli): standardize Doc and Drive parameter aliases --- internal/app/param_alias_e2e_test.go | 39 + .../param_alias_payload_equivalence_test.go | 206 ++- internal/cli/param_aliases_generated.go | 1507 ++++++++++++++--- internal/cli/param_concepts.json | 259 ++- 4 files changed, 1757 insertions(+), 254 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 8267390c..77b9ac5b 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -68,6 +68,45 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string return `{"result":[{"templateId":"fixture-template-id"}]}` case "create_document": return `{"nodeId":"fixture-node"}` + case "list_files": + return `{"success":true,"result":{"files":[],"hasMore":false}}` + case "list_recycle_items": + return `{"success":true,"result":{"recycleItems":[{"recycleItemId":"recycle-1","originalName":"Fixture Node"}],"hasMore":false}}` + case "get_star_list": + return `{"success":true,"result":{"starList":[],"hasMore":false}}` + case "list_file_versions": + return `{"success":true,"result":{"versions":[{"version":3,"name":"Fixture Version"}],"hasMore":false}}` + case "get_file_info": + name := "Fixture Node" + for index := len(c.calls) - 2; index >= 0; index-- { + call := c.calls[index] + switch call.tool { + case "create_folder": + if value, ok := call.args["name"].(string); ok { + name = value + } + index = -1 + case "rename_document": + if value, ok := call.args["newName"].(string); ok { + name = value + } + index = -1 + } + } + encoded, _ := json.Marshal(map[string]any{"success": true, "result": map[string]any{"fileId": "node-1", "name": name}}) + return string(encoded) + case "get_cover", "get_node_stats": + return `{"success":true,"result":{"nodeId":"node-1"}}` + case "get_file_publish_status": + return `{"success":true,"result":{"fileId":"node-1","published":false}}` + case "create_folder", "create_shortcut": + return `{"success":true,"fileId":"node-1"}` + case "delete_document", "mark_star", "unmark_star", "restore_recycle_item", "rename_document", "revert_file_version": + return `{"success":true,"fileId":"node-1"}` + case "set_file_publish": + return `{"success":true}` + case "download_file", "download_file_version": + return `{"success":true,"result":{"downloadUrl":"http://invalid.test/fixture.bin","fileName":"fixture.bin"}}` case "get_document_content": for index := len(c.calls) - 2; index >= 0; index-- { call := c.calls[index] diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 494a8b6c..064bc154 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -124,6 +124,7 @@ var paramAliasCompleteCommands = map[string][]string{ "doc +version-revert": {"doc", "+version-revert", "--node", "node-1", "--version", "3", "--yes"}, "doc +version-save": {"doc", "+version-save", "--node", "node-1", "--yes"}, "doc +update": {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"}, + "doc +export": {"doc", "+export", "--node", "node-1", "--export-format", "docx", "--output", "exports/fixture.docx"}, "doc block insert": {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"}, "doc block update": {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"}, "doc comment create": {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"}, @@ -131,9 +132,43 @@ var paramAliasCompleteCommands = map[string][]string{ "doc comment delete": {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"}, "doc comment reply": {"doc", "comment", "reply", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture reply", "--mentioned-open-conversation-id", "cid-1,cid-2", "--yes"}, "doc comment update": {"doc", "comment", "update", "--node", "node-1", "--comment-key", "comment-1", "--content", "fixture update", "--yes"}, + "doc create": {"doc", "create", "--name", "Fixture Document", "--workspace", "workspace-1"}, "doc version revert": {"doc", "version", "revert", "--node", "node-1", "--version", "3", "--yes"}, + "drive +cover": {"drive", "+cover", "--node", "node-1"}, + "drive +create-folder": {"drive", "+create-folder", "--name", "Fixture Folder", "--space-id", "space-1", "--folder", "folder-1"}, + "drive +create-shortcut": {"drive", "+create-shortcut", "--node", "node-1", "--folder", "folder-1", "--workspace", "workspace-1"}, + "drive +delete": {"drive", "+delete", "--node", "node-1", "--yes"}, + "drive +download": {"drive", "+download", "--node", "node-1", "--space-id", "space-1", "--output", "downloads/fixture.bin"}, + "drive +info": {"drive", "+info", "--node", "node-1", "--space-id", "space-1"}, + "drive +inspect": {"drive", "+inspect", "--node", "node-1", "--space-id", "space-1", "--include-stats"}, + "drive +list": {"drive", "+list", "--space-id", "space-1", "--folder", "folder-1", "--limit", "7", "--cursor", "cursor-1", "--order-by", "name", "--order", "asc"}, + "drive +publish-get": {"drive", "+publish-get", "--node", "node-1"}, + "drive +publish-unset": {"drive", "+publish-unset", "--node", "node-1", "--yes"}, + "drive +recycle-list": {"drive", "+recycle-list", "--space-id", "space-1", "--limit", "7", "--cursor", "cursor-1"}, + "drive +recycle-restore": {"drive", "+recycle-restore", "--id", "recycle-1", "--yes"}, + "drive +rename": {"drive", "+rename", "--node", "node-1", "--name", "Fixture Renamed", "--yes"}, + "drive +search": {"drive", "+search", "--query", "fixture"}, + "drive +star-add": {"drive", "+star-add", "--node", "node-1"}, + "drive +star-list": {"drive", "+star-list", "--limit", "7", "--cursor", "cursor-1"}, + "drive +star-remove": {"drive", "+star-remove", "--node", "node-1"}, + "drive +stats": {"drive", "+stats", "--node", "node-1"}, + "drive +upload": {"drive", "+upload", "--file", "param_alias_payload_equivalence_test.go", "--file-name", "fixture.txt", "--mime-type", "text/plain", "--space-id", "space-1", "--node", "node-1", "--yes"}, + "drive +version-download": {"drive", "+version-download", "--node", "node-1", "--version", "3", "--output", "downloads/fixture-v3.bin"}, + "drive +version-get": {"drive", "+version-get", "--node", "node-1", "--version", "3"}, + "drive +version-history": {"drive", "+version-history", "--node", "node-1", "--limit", "7", "--cursor", "cursor-1"}, + "drive +version-revert": {"drive", "+version-revert", "--node", "node-1", "--version", "3", "--yes"}, + "drive commit": {"drive", "commit", "--file-name", "fixture.txt", "--file-size", "7", "--upload-id", "upload-1", "--space-id", "space-1"}, + "drive copy": {"drive", "copy", "--node", "node-1", "--folder", "folder-1"}, + "drive download": {"drive", "download", "--node", "node-1", "--output", "downloads/fixture.bin", "--version", "3", "--space-id", "space-1"}, "drive info": {"drive", "info", "--node", "node-1", "--space-id", "space-1"}, "drive list": {"drive", "list", "--folder", "folder-1", "--limit", "7"}, + "drive mkdir": {"drive", "mkdir", "--name", "Fixture Folder", "--space-id", "space-1"}, + "drive permission add": {"drive", "permission", "add", "--node", "node-1", "--users", "user-1,user-2", "--role", "READER"}, + "drive recycle list": {"drive", "recycle", "list", "--space-id", "space-1", "--limit", "7"}, + "drive recycle restore": {"drive", "recycle", "restore", "--id", "recycle-1"}, + "drive search": {"drive", "search", "--query", "fixture", "--created-from", "1", "--created-to", "2", "--modified-from", "3", "--modified-to", "4", "--creator-uids", "user-1,user-2"}, + "drive upload": {"drive", "upload", "--file", "../../go.mod", "--space-id", "space-1"}, + "drive upload-info": {"drive", "upload-info", "--file-name", "fixture.txt", "--file-size", "7", "--space-id", "space-1"}, "mail +find-mail-user": {"mail", "+find-mail-user", "--query", "fixture", "--limit", "7"}, "mail folder update": {"mail", "folder", "update", "--email", "fixture@example.com", "--id", "folder-1", "--name", "Fixture Folder", "--yes"}, "mail message search": {"mail", "message", "search", "--email", "fixture@example.com", "--query", "subject:fixture"}, @@ -156,6 +191,19 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ "doc block insert": { "parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"}, }, + "doc +inspect": { + "include-permissions": {"doc", "+inspect", "--node", "node-1", "--include-permissions"}, + }, + "doc +search": { + "created-from": {"doc", "+search", "--query", "fixture", "--created-from", "1"}, + "creator-uids": {"doc", "+search", "--query", "fixture", "--creator-uids", "user-1,user-2"}, + }, + "drive list": { + "workspace": {"drive", "list", "--workspace", "workspace-1", "--limit", "7"}, + "order-by": {"drive", "list", "--folder", "folder-1", "--order-by", "name", "--limit", "7"}, + "space-id": {"drive", "list", "--space-id", "space-1", "--limit", "7"}, + "order": {"drive", "list", "--folder", "folder-1", "--order", "asc", "--limit", "7"}, + }, "chat message list": { "user": {"chat", "message", "list", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"}, }, @@ -241,12 +289,87 @@ var paramAliasNewIMCases = []struct { {command: "chat +messages-set-pin", emitted: "conversation-id", canonical: "open-conversation-id"}, } +// paramAliasNewDriveCases is the exact executable-alias set introduced by the +// reviewed Drive expansion. Guard fixtures are covered separately by the +// exhaustive runtime-contract tests; every entry here must preserve the final +// transport payload of its canonical spelling. +var paramAliasNewDriveCases = []struct { + command string + emitted string + canonical string +}{ + {command: "drive +cover", emitted: "dentry-uuid", canonical: "node"}, + {command: "drive +create-folder", emitted: "folder-name", canonical: "name"}, + {command: "drive +create-folder", emitted: "storage-space-id", canonical: "space-id"}, + {command: "drive +create-shortcut", emitted: "source-file-id", canonical: "node"}, + {command: "drive +create-shortcut", emitted: "target-folder-id", canonical: "folder"}, + {command: "drive +create-shortcut", emitted: "target-workspace-id", canonical: "workspace"}, + {command: "drive +delete", emitted: "file-id", canonical: "node"}, + {command: "drive +download", emitted: "dentry-uuid", canonical: "node"}, + {command: "drive +download", emitted: "destination-path", canonical: "output"}, + {command: "drive +inspect", emitted: "include-statistics", canonical: "include-stats"}, + {command: "drive +list", emitted: "folder-id", canonical: "folder"}, + {command: "drive +list", emitted: "page-size", canonical: "limit"}, + {command: "drive +list", emitted: "next-token", canonical: "cursor"}, + {command: "drive +list", emitted: "sort-direction", canonical: "order"}, + {command: "drive +list", emitted: "sort-by", canonical: "order-by"}, + {command: "drive +publish-get", emitted: "dentry-uuid", canonical: "node"}, + {command: "drive +publish-unset", emitted: "file-id", canonical: "node"}, + {command: "drive +recycle-list", emitted: "storage-space-id", canonical: "space-id"}, + {command: "drive +recycle-list", emitted: "page-token", canonical: "cursor"}, + {command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"}, + {command: "drive +rename", emitted: "file-id", canonical: "node"}, + {command: "drive +rename", emitted: "new-name", canonical: "name"}, + {command: "drive +star-add", emitted: "dentry-uuid", canonical: "node"}, + {command: "drive +star-list", emitted: "max-results", canonical: "limit"}, + {command: "drive +star-remove", emitted: "file-id", canonical: "node"}, + {command: "drive +stats", emitted: "dentry-uuid", canonical: "node"}, + {command: "drive +upload", emitted: "source-file", canonical: "file"}, + {command: "drive +upload", emitted: "name", canonical: "file-name"}, + {command: "drive +upload", emitted: "overwrite-node-id", canonical: "node"}, + {command: "drive +version-download", emitted: "version-number", canonical: "version"}, + {command: "drive +version-download", emitted: "save-path", canonical: "output"}, + {command: "drive +version-get", emitted: "version-no", canonical: "version"}, + {command: "drive +version-history", emitted: "next-cursor", canonical: "cursor"}, + {command: "drive +version-history", emitted: "page-size", canonical: "limit"}, + {command: "drive +version-revert", emitted: "version-number", canonical: "version"}, + {command: "drive +cover", emitted: "node-id", canonical: "node"}, + {command: "drive +create-shortcut", emitted: "node-id", canonical: "node"}, + {command: "drive +delete", emitted: "node-id", canonical: "node"}, + {command: "drive +download", emitted: "node-id", canonical: "node"}, + {command: "drive +inspect", emitted: "node-id", canonical: "node"}, + {command: "drive +publish-get", emitted: "node-id", canonical: "node"}, + {command: "drive +publish-unset", emitted: "node-id", canonical: "node"}, + {command: "drive +rename", emitted: "node-id", canonical: "node"}, + {command: "drive +star-add", emitted: "node-id", canonical: "node"}, + {command: "drive +star-remove", emitted: "node-id", canonical: "node"}, + {command: "drive +stats", emitted: "node-id", canonical: "node"}, + {command: "drive +upload", emitted: "node-id", canonical: "node"}, + {command: "drive +version-download", emitted: "node-id", canonical: "node"}, + {command: "drive +version-get", emitted: "node-id", canonical: "node"}, + {command: "drive +version-history", emitted: "node-id", canonical: "node"}, + {command: "drive +version-revert", emitted: "node-id", canonical: "node"}, + {command: "drive +cover", emitted: "url", canonical: "node"}, + {command: "drive +create-shortcut", emitted: "document-id", canonical: "node"}, + {command: "drive +delete", emitted: "folder-id", canonical: "node"}, + {command: "drive +inspect", emitted: "document-id", canonical: "node"}, + {command: "drive +inspect", emitted: "folder-id", canonical: "node"}, + {command: "drive +publish-get", emitted: "url", canonical: "node"}, + {command: "drive +publish-unset", emitted: "document-url", canonical: "node"}, + {command: "drive +rename", emitted: "document-id", canonical: "node"}, + {command: "drive +rename", emitted: "folder-id", canonical: "node"}, + {command: "drive +star-add", emitted: "url", canonical: "node"}, + {command: "drive +star-remove", emitted: "doc-id", canonical: "node"}, + {command: "drive +stats", emitted: "document-url", canonical: "node"}, + {command: "drive +upload", emitted: "file-id", canonical: "node"}, +} + // paramAliasRepresentativePayloadCases keeps final transport coverage across // old concept aliases, command overrides, native compatibility flags, read and // write commands, and different products. Every reviewed alias is still // checked through the embedded PreParse delivery path and against a complete -// business-valid command template. The separate IM gate below continues to -// execute every alias introduced by the current IM optimization. +// business-valid command template. The dedicated product gates below continue +// to execute every alias introduced by the reviewed IM and Drive expansions. // // Keeping the older 100+ aliases at the contract layer avoids rebuilding and // executing the complete 800+ command Root twice per spelling under -race. @@ -421,14 +544,79 @@ func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayl } } -// Resource download deliberately continues from the transport call into a -// local HTTPS download. The generic capture caller returns an empty object, so -// this command's stable post-transport validation error is the expected test -// boundary; canonical and alias calls must still produce the same request and -// the same error. +func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) { + activeAliases := 0 + for _, test := range paramAliasNewDriveCases { + test := test + t.Run(test.command+"/"+test.emitted, func(t *testing.T) { + complete, ok := paramAliasCompleteCommand(test.command, test.canonical) + if !ok { + t.Fatal("reviewed Drive alias has no complete-command E2E template") + } + canonicalArgs := append([]string(nil), complete...) + aliasArgs, replacements := replaceLongFlag(canonicalArgs, test.canonical, test.emitted) + if replacements != 1 { + t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, canonicalArgs) + } + + canonicalCaller := ¶mAliasCaptureCaller{} + _, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...) + if canonicalErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, canonicalErr) { + t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls) + } + if len(canonicalCaller.calls) == 0 { + t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs) + } + + entry, exists := cli.LookupParamAlias(test.command) + target, active := entry.ResolveAlias(test.emitted) + if !exists || !active { + return + } + if target != test.canonical { + t.Fatalf("active reviewed Drive alias --%s resolves to --%s, want --%s", test.emitted, target, test.canonical) + } + activeAliases++ + + aliasCaller := ¶mAliasCaptureCaller{} + ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...) + if aliasErr != nil && !paramAliasExpectedCaptureBoundaryError(test.command, aliasErr) { + t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls) + } + if ctx == nil { + t.Fatal("complete alias command skipped PreParse") + } + if (canonicalErr == nil) != (aliasErr == nil) || (canonicalErr != nil && canonicalErr.Error() != aliasErr.Error()) { + t.Fatalf("canonical and alias completion errors differ: canonical=%v alias=%v", canonicalErr, aliasErr) + } + if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) { + t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls) + } + }) + } + if activeAliases != len(paramAliasNewDriveCases) { + t.Fatalf("new Drive aliases active in embedded table = %d, want %d", activeAliases, len(paramAliasNewDriveCases)) + } +} + +// Some artifact commands deliberately continue past the final captured +// transport call into local download/upload handling. Deterministic invalid +// resource responses form their expected post-transport test boundary; +// canonical and alias calls must still produce the same request and error. func paramAliasExpectedCaptureBoundaryError(command string, err error) bool { - return command == "chat +messages-resource-download" && err != nil && - strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址") + if err == nil { + return false + } + switch command { + case "chat +messages-resource-download": + return strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址") + case "drive +download", "drive +version-download": + return strings.Contains(err.Error(), "下载地址必须是受信任域名上的 HTTPS URL") + case "drive +upload": + return strings.Contains(err.Error(), "incomplete drive upload credentials") + default: + return false + } } // +chat-messages supplies the current wall-clock time when callers omit diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index d5229552..58ffe989 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -1883,51 +1883,62 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +access-change", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "node-id": "node", - "space": "workspace", - "space-id": "workspace", - "url": "node", - "workspace-id": "workspace", + "access-role": "role", + "dentry-uuid": "node", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "knowledge-base-id": "workspace", + "member-role": "role", + "node-id": "node", + "permission-role": "role", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +access-grant", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "node-id": "node", - "space": "workspace", - "space-id": "workspace", - "url": "node", - "workspace-id": "workspace", + "access-role": "role", + "dentry-uuid": "node", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "knowledge-base-id": "workspace", + "member-role": "role", + "node-id": "node", + "permission-role": "role", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "space", "space-id", "storage-space-id", "target-user-id", "target-user-ids", "task-id", "template-id", "user-id", "user-ids", "version"}, + Ambiguous: []string{"target-user", "user", "users"}, }, { CLIPath: "doc +access-revoke", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "node-id": "node", - "space": "workspace", - "space-id": "workspace", - "url": "node", - "workspace-id": "workspace", + "dentry-uuid": "node", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "knowledge-base-id": "workspace", + "node-id": "node", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +background-delete", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -1935,11 +1946,12 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +background-update", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -1947,12 +1959,13 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +checkpoint-update", Aliases: map[string]string{ "body": "content", + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -1961,12 +1974,13 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-create", Aliases: map[string]string{ "body": "content", + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -1975,12 +1989,13 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "url": "node", }, - Blocked: []string{"chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "dentry-id", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-delete", Aliases: map[string]string{ "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -1988,11 +2003,12 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2010,13 +2026,14 @@ var generatedParamAliases = []ParamAliasEntry{ "top": "limit", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "offset", "page", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-reply", Aliases: map[string]string{ "body": "content", "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2025,13 +2042,14 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "url": "node", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "dentry-id", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-update", Aliases: map[string]string{ "body": "content", "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2040,65 +2058,67 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "url": "node", }, - Blocked: []string{"block-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +copy", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "folder-id": "folder", - "node-id": "node", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "space": "workspace", - "space-id": "workspace", - "url": "node", - "workspace-id": "workspace", + "dentry-uuid": "node", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "node-id": "node", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +create", Aliases: map[string]string{ - "body": "content", - "content-format": "doc-format", - "folder-id": "folder", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "space": "workspace", - "space-id": "workspace", - "text": "content", - "workspace-id": "workspace", + "body": "content", + "content-format": "doc-format", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "text": "content", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"content-file", "export-format", "mime-type", "node", "parent-id", "title"}, + Blocked: []string{"content-file", "dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "mime-type", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id", "title"}, }, { CLIPath: "doc +create-from-template", Aliases: map[string]string{ - "folder-id": "folder", - "keyword": "query", - "keywords": "query", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "q": "query", - "search-word": "query", - "space": "workspace", - "space-id": "workspace", - "workspace-id": "workspace", + "folder-id": "folder", + "keyword": "query", + "keywords": "query", + "knowledge-base-id": "workspace", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "q": "query", + "search-word": "query", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"node", "parent-id", "subject", "text", "title"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id", "subject", "text", "title"}, }, { CLIPath: "doc +doc-append", Aliases: map[string]string{ "body": "text", "content": "text", + "dentry-uuid": "doc", "doc-id": "doc", "document-id": "doc", "file-id": "doc", @@ -2106,30 +2126,38 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "doc", "url": "doc", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +export", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "node-id": "node", - "url": "node", + "dentry-uuid": "node", + "destination-path": "output", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "node-id": "node", + "output-path": "output", + "save-path": "output", + "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "content-file", "dentry-id", "file", "file-path", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "wait", "workspace", "workspace-id"}, }, { CLIPath: "doc +export-get", Aliases: map[string]string{ - "export-job-id": "job-id", + "destination-path": "output", + "export-job-id": "job-id", + "output-path": "output", + "save-path": "output", }, - Blocked: []string{"doc-id", "document-id", "file-id", "node", "node-id", "task-id", "url"}, + Blocked: []string{"content-file", "doc-id", "document-id", "file", "file-id", "file-path", "folder", "folder-id", "node", "node-id", "task-id", "url"}, }, { CLIPath: "doc +export-submit", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2137,11 +2165,12 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +fetch", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2151,7 +2180,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-block": "start-block-id", "url": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "content-format", "dentry-id", "doc-format", "folder", "folder-id", "id", "job-id", "name", "parent-id", "range", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { @@ -2174,20 +2203,24 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +grant-and-share", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "node-id": "node", - "space": "workspace", - "space-id": "workspace", - "workspace-id": "workspace", + "access-role": "role", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "knowledge-base-id": "workspace", + "member-role": "role", + "node-id": "node", + "permission-role": "role", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"folder"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "permission", "public-permission", "reserve-role", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc +history-list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2195,11 +2228,12 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +history-revert", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2209,11 +2243,12 @@ var generatedParamAliases = []ParamAliasEntry{ "version-no": "version", "version-number": "version", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "workspace", "workspace-id"}, }, { CLIPath: "doc +history-save", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2221,66 +2256,74 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +import", Aliases: map[string]string{ - "folder-id": "folder", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "space": "workspace", - "space-id": "workspace", - "workspace-id": "workspace", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"node", "parent-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc +inspect", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", + "include-access": "include-permissions", + "include-member": "include-permissions", + "include-members": "include-permissions", "include-versions": "include-history", "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "include", "include-info", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "include", "include-blocks", "include-content", "include-info", "include-meta", "include-metadata", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +list", Aliases: map[string]string{ - "folder-id": "folder", - "max-result": "limit", - "max-results": "limit", - "next-cursor": "cursor", - "next-page-token": "cursor", - "next-token": "cursor", - "page-size": "limit", - "page-token": "cursor", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "per-page": "limit", - "size": "limit", - "space": "workspace", - "space-id": "workspace", - "take": "limit", - "top": "limit", - "workspace-id": "workspace", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"count", "node", "offset", "page", "parent-id"}, + Blocked: []string{"count", "dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "offset", "page", "parent-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc +media-download", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "node-id": "node", + "destination-path": "output", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "node-id": "node", + "output-path": "output", + "save-path": "output", }, + Blocked: []string{"content-file", "file", "file-path", "folder", "folder-id"}, Ambiguous: []string{"file-id", "url"}, }, { @@ -2291,6 +2334,7 @@ var generatedParamAliases = []ParamAliasEntry{ "document-id": "node", "node-id": "node", }, + Blocked: []string{"after-block-id", "before-block-id"}, Ambiguous: []string{"file-id", "url"}, }, { @@ -2316,21 +2360,22 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +move", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "file-id": "node", - "folder-id": "folder", - "node-id": "node", - "parent-folder": "folder", - "parent-folder-id": "folder", - "parent-node-id": "folder", - "space": "workspace", - "space-id": "workspace", - "url": "node", - "workspace-id": "workspace", + "dentry-uuid": "node", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "file-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "node-id": "node", + "parent-folder": "folder", + "parent-folder-id": "folder", + "parent-node-id": "folder", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +resource-delete", @@ -2345,11 +2390,15 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +resource-download", Aliases: map[string]string{ - "doc": "node", - "doc-id": "node", - "document-id": "node", - "node-id": "node", + "destination-path": "output", + "doc": "node", + "doc-id": "node", + "document-id": "node", + "node-id": "node", + "output-path": "output", + "save-path": "output", }, + Blocked: []string{"content-file", "file", "file-path", "folder", "folder-id"}, Ambiguous: []string{"file-id", "url"}, }, { @@ -2365,6 +2414,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +review", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2372,28 +2422,37 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +search", Aliases: map[string]string{ - "keyword": "query", - "keywords": "query", - "max-result": "limit", - "max-results": "limit", - "next-cursor": "cursor", - "next-page-token": "cursor", - "next-token": "cursor", - "page-size": "limit", - "page-token": "cursor", - "per-page": "limit", - "q": "query", - "search-word": "query", - "size": "limit", - "take": "limit", - "top": "limit", + "create-time-from": "created-from", + "create-time-to": "created-to", + "created-after": "created-from", + "created-before": "created-to", + "created-by-user-ids": "creator-uids", + "created-time-end": "created-to", + "created-time-start": "created-from", + "creator-ids": "creator-uids", + "creator-user-ids": "creator-uids", + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", }, - Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, + Blocked: []string{"count", "end", "from", "modified-from", "modified-to", "modifier-uids", "name", "offset", "owner-id", "page", "start", "subject", "text", "title", "to", "user", "user-id", "user-ids", "users"}, }, { CLIPath: "doc +share", @@ -2453,11 +2512,13 @@ var generatedParamAliases = []ParamAliasEntry{ "revision": "expected-revision", "url": "node", }, - Blocked: []string{"content-file", "export-format", "mime-type", "version", "version-no", "version-number"}, + Blocked: []string{"content-file", "export-format", "mime-type", "version", "version-no", "version-number"}, + Ambiguous: []string{"element"}, }, { CLIPath: "doc +version-list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2465,12 +2526,13 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"max-result", "max-results", "next-cursor", "next-page-token", "next-token", "per-page", "size", "take", "top"}, }, { CLIPath: "doc +version-revert", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2480,11 +2542,12 @@ var generatedParamAliases = []ParamAliasEntry{ "version-no": "version", "version-number": "version", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "workspace", "workspace-id"}, }, { CLIPath: "doc +version-save", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-id": "node", "document-id": "node", @@ -2492,52 +2555,57 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "message", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc block delete", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "index", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "dentry-id", "folder", "folder-id", "index", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc block insert", Aliases: map[string]string{ "body": "text", "content": "text", + "dentry-uuid": "node", "doc": "node", "document-id": "node", "parent-block-id": "parent-block", "ref-block-id": "ref-block", "reference-block-id": "ref-block", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { CLIPath: "doc block list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc block update", Aliases: map[string]string{ "body": "text", "content": "text", + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment create", Aliases: map[string]string{ "body": "content", + "dentry-uuid": "node", "doc": "node", "document-id": "node", "mentioned-open-conversation-ids": "mentioned-open-conversation-id", @@ -2545,30 +2613,33 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "dentry-id", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment create-inline", Aliases: map[string]string{ "body": "content", + "dentry-uuid": "node", "doc": "node", "document-id": "node", "text": "content", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment delete", Aliases: map[string]string{ "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", "max-result": "limit", @@ -2580,13 +2651,14 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "dentry-id", "folder", "folder-id", "job-id", "name", "offset", "page", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment reply", Aliases: map[string]string{ "body": "content", "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "document-id": "node", "mentioned-open-conversation-ids": "mentioned-open-conversation-id", @@ -2594,13 +2666,14 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "dentry-id", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment update", Aliases: map[string]string{ "body": "content", "comment-id": "comment-key", + "dentry-uuid": "node", "doc": "node", "document-id": "node", "mentioned-open-conversation-ids": "mentioned-open-conversation-id", @@ -2608,26 +2681,27 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "dentry-id", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc create", Aliases: map[string]string{ - "body": "content", - "doc-format": "content-format", - "space": "workspace", - "space-id": "workspace", - "text": "content", + "body": "content", + "doc-format": "content-format", + "knowledge-base-id": "workspace", + "text": "content", + "wiki-workspace-id": "workspace", }, - Blocked: []string{"export-format", "mime-type", "node"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "folder-id", "mime-type", "node", "node-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc export", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc export get", @@ -2639,18 +2713,18 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc file create", Aliases: map[string]string{ - "space": "workspace", - "space-id": "workspace", + "knowledge-base-id": "workspace", + "wiki-workspace-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc import", Aliases: map[string]string{ - "space": "workspace", - "space-id": "workspace", + "knowledge-base-id": "workspace", + "wiki-workspace-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc import get", @@ -2662,94 +2736,107 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc info", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc media download", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc media insert", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", "ref-block-id": "ref-block", "reference-block-id": "ref-block", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-block", "parent-block-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "parent-block", "parent-block-id", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { CLIPath: "doc media upload", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc read", Aliases: map[string]string{ - "doc": "node", - "document-id": "node", + "dentry-uuid": "node", + "destination-path": "output", + "doc": "node", + "document-id": "node", + "output-path": "output", + "save-path": "output", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "content-file", "dentry-id", "file", "file-path", "folder", "folder-id", "job-id", "name", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { CLIPath: "doc style background clear", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style background set", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style cover clear", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style cover set", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style get", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc template apply", Aliases: map[string]string{ - "space": "workspace", - "space-id": "workspace", + "knowledge-base-id": "workspace", + "wiki-workspace-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "space", "space-id", "storage-space-id"}, }, { CLIPath: "doc template list", @@ -2785,16 +2872,18 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc update", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "doc-format": "content-format", "document-id": "node", "expected-revision": "revision", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "export-format", "folder", "folder-id", "job-id", "mime-type", "parent-id", "task-id", "template-id", "version", "version-no", "version-number", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "export-format", "folder", "folder-id", "job-id", "mime-type", "name", "parent-id", "role", "space-id", "stdin", "task-id", "template-id", "version", "version-no", "version-number", "workspace", "workspace-id"}, }, { CLIPath: "doc version list", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", "max-result": "limit", @@ -2806,53 +2895,1029 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "dentry-id", "folder", "folder-id", "job-id", "name", "offset", "page", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc version revert", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", "version-no": "version", "version-number": "version", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "workspace", "workspace-id"}, }, { CLIPath: "doc version save", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc whiteboard insert", Aliases: map[string]string{ + "dentry-uuid": "node", "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +copy", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "node-id", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "target-id"}, + }, + { + CLIPath: "drive +cover", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +create-folder", + Aliases: map[string]string{ + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "name", + "drive-space-id": "space-id", + "folder-id": "folder", + "folder-name": "name", + "new-name": "name", + "parent-directory-id": "folder", + "parent-folder-id": "folder", + "storage-space-id": "space-id", + }, + Blocked: []string{"dentry-id", "knowledge-base-id", "parent-id", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +create-shortcut", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "node-id": "node", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "url": "node", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "doc", "drive-space-id", "name", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "id", "target-id"}, + }, + { + CLIPath: "drive +delete", + Aliases: map[string]string{ + "dentry-uuid": "node", + "file-id": "node", + "folder": "node", + "folder-id": "node", + "node-id": "node", + }, + Blocked: []string{"dentry-id", "doc", "doc-id", "document-id", "document-url", "id", "name", "url"}, + }, + { + CLIPath: "drive +download", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-path": "output", + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "file-id": "node", + "node-id": "node", + "output-path": "output", + "save-path": "output", + "storage-space-id": "space-id", + }, + Blocked: []string{"content-file", "dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "knowledge-base-id", "name", "space", "url", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +find-file", + Aliases: map[string]string{ + "keyword": "query", + "keywords": "query", + "q": "query", + "search-word": "query", + }, + Blocked: []string{"name", "subject", "text", "title"}, + }, + { + CLIPath: "drive +info", + Aliases: map[string]string{ + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "storage-space-id": "space-id", + }, + Blocked: []string{"dentry-id", "document-url", "knowledge-base-id", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +inspect", + Aliases: map[string]string{ + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "doc-id": "node", + "document-id": "node", + "drive-space-id": "space-id", + "file-id": "node", + "folder": "node", + "folder-id": "node", + "include-public-status": "include-publish", + "include-publish-status": "include-publish", + "include-statistics": "include-stats", + "include-thumbnail": "include-cover", + "node-id": "node", + "storage-space-id": "space-id", + }, + Blocked: []string{"dentry-id", "doc", "document-url", "id", "include", "include-content", "include-history", "include-permissions", "knowledge-base-id", "name", "space", "url", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +list", + Aliases: map[string]string{ + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "drive-space-id": "space-id", + "folder-id": "folder", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "order-direction": "order", + "order-field": "order-by", + "page-size": "limit", + "page-token": "cursor", + "parent-folder-id": "folder", + "per-page": "limit", + "size": "limit", + "sort": "order", + "sort-by": "order-by", + "sort-direction": "order", + "sort-field": "order-by", + "storage-space-id": "space-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "dentry-id", "knowledge-base-id", "offset", "page", "wiki-workspace-id", "workspace", "workspace-id"}, + Ambiguous: []string{"root-id", "space"}, + }, + { + CLIPath: "drive +move", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + "workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "node-id", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "target-id"}, + }, + { + CLIPath: "drive +publish-get", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +publish-unset", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +recent", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + Ambiguous: []string{"type", "types"}, + }, + { + CLIPath: "drive +recycle-list", + Aliases: map[string]string{ + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "storage-space-id": "space-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "knowledge-base-id", "offset", "page", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive +recycle-restore", + Aliases: map[string]string{ + "deleted-item-id": "id", + "recycle-item-id": "id", + "trash-item-id": "id", + }, + Blocked: []string{"file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"}, + }, + { + CLIPath: "drive +rename", + Aliases: map[string]string{ + "dentry-uuid": "node", + "display-name": "name", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "file-name": "name", + "folder": "node", + "folder-id": "node", + "id": "node", + "new-name": "name", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive +search", + Aliases: map[string]string{ + "create-time-from": "created-from", + "create-time-to": "created-to", + "created-after": "created-from", + "created-before": "created-to", + "created-by-user-ids": "creator-uids", + "created-time-end": "created-to", + "created-time-start": "created-from", + "creator-ids": "creator-uids", + "creator-user-ids": "creator-uids", + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "modified-after": "modified-from", + "modified-before": "modified-to", + "modified-time-end": "modified-to", + "modified-time-start": "modified-from", + "modify-time-from": "modified-from", + "modify-time-to": "modified-to", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "modifier-uids", "name", "offset", "owner-id", "page", "subject", "text", "title", "user", "user-id", "user-ids", "users"}, + Ambiguous: []string{"end", "from", "start", "time-from", "time-to", "to", "types"}, + }, + { + CLIPath: "drive +search-docs", + Aliases: map[string]string{ + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "name", "page", "subject", "text", "title"}, + }, + { + CLIPath: "drive +star-add", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +star-list", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + Ambiguous: []string{"type", "types"}, + }, + { + CLIPath: "drive +star-remove", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +stats", + Aliases: map[string]string{ + "dentry-uuid": "node", + "doc-id": "node", + "document-id": "node", + "document-url": "node", + "file-id": "node", + "id": "node", + "node-id": "node", + "url": "node", + }, + Blocked: []string{"dentry-id", "doc", "folder", "folder-id", "name"}, + }, + { + CLIPath: "drive +upload", + Aliases: map[string]string{ + "content-type": "mime-type", + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "file-name", + "drive-space-id": "space-id", + "file-id": "node", + "file-path": "file", + "filename": "file-name", + "folder-id": "folder", + "local-file": "file", + "name": "file-name", + "node-id": "node", + "overwrite-node-id": "node", + "parent-directory-id": "folder", + "parent-folder-id": "folder", + "source-file": "file", + "storage-space-id": "space-id", + "target-folder-id": "folder", + "upload-name": "file-name", + }, + Blocked: []string{"dentry-id", "document-url", "knowledge-base-id", "output-path", "wiki-workspace-id", "workspace", "workspace-id"}, + Ambiguous: []string{"destination-id", "space", "target-id"}, + }, + { + CLIPath: "drive +version-download", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-path": "output", + "file-id": "node", + "node-id": "node", + "output-path": "output", + "save-path": "output", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"content-file", "dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "name", "revision", "url"}, + }, + { + CLIPath: "drive +version-get", + Aliases: map[string]string{ + "dentry-uuid": "node", + "file-id": "node", + "node-id": "node", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "revision", "url"}, + }, + { + CLIPath: "drive +version-history", + Aliases: map[string]string{ + "dentry-uuid": "node", + "file-id": "node", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "node-id": "node", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "offset", "page", "url"}, + }, + { + CLIPath: "drive +version-revert", + Aliases: map[string]string{ + "dentry-uuid": "node", + "file-id": "node", + "node-id": "node", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "revision", "url"}, + }, + { + CLIPath: "drive commit", + Aliases: map[string]string{ + "content-length": "file-size", + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "file-name", + "drive-space-id": "space-id", + "file-size-bytes": "file-size", + "filename": "file-name", + "folder-id": "folder", + "name": "file-name", + "parent-directory-id": "folder", + "size-bytes": "file-size", + "storage-space-id": "space-id", + "upload-name": "file-name", + "upload-session-id": "upload-id", + }, + Blocked: []string{"knowledge-base-id", "limit", "page-size", "part-size", "size", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive copy", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "document-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "target-id"}, + }, + { + CLIPath: "drive cover", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive delete", + Aliases: map[string]string{ + "dentry-uuid": "node", + }, + Blocked: []string{"dentry-id", "document-url"}, + }, + { + CLIPath: "drive download", + Aliases: map[string]string{ + "chunk-size": "part-size", + "concurrency": "parallel", + "dentry-uuid": "node", + "destination-path": "output", + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "output-path": "output", + "parallelism": "parallel", + "save-path": "output", + "storage-space-id": "space-id", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"content-file", "dentry-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "knowledge-base-id", "revision", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive download-version", + Aliases: map[string]string{ + "chunk-size": "part-size", + "concurrency": "parallel", + "dentry-uuid": "node", + "destination-path": "output", + "document-id": "node", + "output-path": "output", + "parallelism": "parallel", + "save-path": "output", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"content-file", "dentry-id", "file", "file-path", "folder", "folder-id", "revision"}, }, { CLIPath: "drive info", Aliases: map[string]string{ - "space": "space-id", - "workspace": "space-id", - "workspace-id": "space-id", + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "storage-space-id": "space-id", }, - Blocked: []string{"folder"}, + Blocked: []string{"dentry-id", "document-url", "knowledge-base-id", "space", "wiki-workspace-id", "workspace", "workspace-id"}, }, { CLIPath: "drive list", Aliases: map[string]string{ - "folder-id": "folder", + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "document-id": "node", + "drive-space-id": "space-id", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "order-direction": "order", + "order-field": "order-by", + "per-page": "limit", + "size": "limit", + "sort": "order", + "sort-by": "order-by", + "sort-direction": "order", + "sort-field": "order-by", + "storage-space-id": "space-id", + "take": "limit", + "top": "limit", + "wiki-workspace-id": "workspace", }, - Ambiguous: []string{"space"}, + Blocked: []string{"count", "dentry-id", "offset", "page"}, + Ambiguous: []string{"root-id", "space"}, }, { - CLIPath: "drive upload", - Ambiguous: []string{"space"}, + CLIPath: "drive list-spaces", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + }, + { + CLIPath: "drive mkdir", + Aliases: map[string]string{ + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "name", + "drive-space-id": "space-id", + "folder-id": "folder", + "folder-name": "name", + "new-name": "name", + "parent-directory-id": "folder", + "storage-space-id": "space-id", + }, + Blocked: []string{"knowledge-base-id", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive move", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "document-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "target-id"}, + }, + { + CLIPath: "drive permission add", + Aliases: map[string]string{ + "access-role": "role", + "collaborator-ids": "users", + "dentry-uuid": "node", + "document-id": "node", + "knowledge-base-id": "workspace", + "member-role": "role", + "member-user-ids": "users", + "permission-role": "role", + "target-node-id": "node", + "target-user-ids": "users", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "permission", "public-permission", "reserve-role", "space", "space-id", "storage-space-id"}, + }, + { + CLIPath: "drive permission apply", + Aliases: map[string]string{ + "access-role": "role", + "apply-reason": "reason", + "approver-ids": "users", + "approver-user-ids": "users", + "dentry-uuid": "node", + "document-id": "node", + "member-role": "role", + "notification-mode": "notify-mode", + "permission-role": "role", + "target-node-id": "node", + }, + Blocked: []string{"dentry-id", "filter-role", "permission", "public-permission", "reserve-role"}, + }, + { + CLIPath: "drive permission apply-info", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive permission list", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + "knowledge-base-id": "workspace", + "max-result": "limit", + "per-page": "limit", + "permission-role-filter": "filter-role", + "role-filter": "filter-role", + "size": "limit", + "take": "limit", + "target-node-id": "node", + "top": "limit", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"count", "cursor", "dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "page", "permission", "role", "space", "space-id", "storage-space-id"}, + }, + { + CLIPath: "drive permission remove", + Aliases: map[string]string{ + "collaborator-ids": "users", + "dentry-uuid": "node", + "document-id": "node", + "knowledge-base-id": "workspace", + "member-user-ids": "users", + "target-node-id": "node", + "target-user-ids": "users", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "space", "space-id", "storage-space-id"}, + }, + { + CLIPath: "drive permission transfer-owner", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + "keep-role": "reserve-role", + "knowledge-base-id": "workspace", + "new-owner-id": "new-owner", + "new-owner-user-id": "new-owner", + "old-owner-role": "reserve-role", + "target-node-id": "node", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"current-owner", "dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "space", "space-id", "storage-space-id", "user-ids", "users"}, + Ambiguous: []string{"owner", "owner-user-id", "target-id", "user-id"}, + }, + { + CLIPath: "drive permission update", + Aliases: map[string]string{ + "access-role": "role", + "collaborator-ids": "users", + "dentry-uuid": "node", + "document-id": "node", + "knowledge-base-id": "workspace", + "member-role": "role", + "member-user-ids": "users", + "permission-role": "role", + "target-node-id": "node", + "target-user-ids": "users", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "permission", "public-permission", "reserve-role", "space", "space-id", "storage-space-id"}, + }, + { + CLIPath: "drive publish get", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive publish set", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + "public-permission": "permission", + "public-role": "permission", + }, + Blocked: []string{"access-role", "dentry-id", "permission-role", "role"}, + }, + { + CLIPath: "drive publish unset", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive recent", + Aliases: map[string]string{ + "max-result": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + Ambiguous: []string{"type", "types"}, + }, + { + CLIPath: "drive recycle list", + Aliases: map[string]string{ + "dingdrive-space-id": "space-id", + "drive-space-id": "space-id", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "per-page": "limit", + "size": "limit", + "storage-space-id": "space-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "knowledge-base-id", "offset", "page", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + }, + { + CLIPath: "drive recycle restore", + Aliases: map[string]string{ + "deleted-item-id": "id", + "recycle-item-id": "id", + "trash-item-id": "id", + }, + Blocked: []string{"file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"}, + }, + { + CLIPath: "drive rename", + Aliases: map[string]string{ + "dentry-uuid": "node", + "display-name": "name", + "document-id": "node", + "file-name": "name", + "new-name": "name", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive revert", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + "version-no": "version", + "version-number": "version", + }, + Blocked: []string{"dentry-id", "revision"}, + }, + { + CLIPath: "drive search", + Aliases: map[string]string{ + "create-time-from": "created-from", + "create-time-to": "created-to", + "created-after": "created-from", + "created-before": "created-to", + "created-by-user-ids": "creator-uids", + "created-time-end": "created-to", + "created-time-start": "created-from", + "creator-ids": "creator-uids", + "creator-user-ids": "creator-uids", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "modified-after": "modified-from", + "modified-before": "modified-to", + "modified-time-end": "modified-to", + "modified-time-start": "modified-from", + "modify-time-from": "modified-from", + "modify-time-to": "modified-to", + "next-cursor": "cursor", + "next-page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "modifier-uids", "name", "offset", "owner-id", "page", "subject", "text", "title", "user", "user-id", "user-ids", "users"}, + Ambiguous: []string{"end", "from", "start", "time-from", "time-to", "to", "types"}, + }, + { + CLIPath: "drive shortcut", + Aliases: map[string]string{ + "dentry-uuid": "node", + "destination-folder-id": "folder", + "destination-workspace-id": "workspace", + "directory-id": "folder", + "document-id": "node", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "source-file-id": "node", + "source-node-id": "node", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space", "space-id", "storage-space-id"}, + Ambiguous: []string{"destination-id", "target-id"}, + }, + { + CLIPath: "drive star add", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive star list", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "order": "sort", + "order-direction": "sort", + "order-field": "order-by", + "per-page": "limit", + "size": "limit", + "sort-by": "order-by", + "sort-direction": "sort", + "sort-field": "order-by", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + Ambiguous: []string{"type", "types"}, + }, + { + CLIPath: "drive star remove", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive stats", + Aliases: map[string]string{ + "dentry-uuid": "node", + "document-id": "node", + }, + Blocked: []string{"dentry-id"}, + }, + { + CLIPath: "drive upload", + Aliases: map[string]string{ + "content-type": "mime-type", + "dentry-uuid": "node", + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "file-name", + "drive-space-id": "space-id", + "filename": "file-name", + "folder-id": "folder", + "knowledge-base-id": "workspace", + "name": "file-name", + "overwrite-node-id": "node", + "source-file": "file", + "storage-space-id": "space-id", + "target-folder-id": "folder", + "target-workspace-id": "workspace", + "upload-name": "file-name", + "wiki-workspace-id": "workspace", + }, + Blocked: []string{"dentry-id", "document-url", "output-path"}, + Ambiguous: []string{"destination-id", "space", "target-id"}, + }, + { + CLIPath: "drive upload-info", + Aliases: map[string]string{ + "content-length": "file-size", + "content-type": "mime-type", + "dingdrive-space-id": "space-id", + "directory-id": "folder", + "display-name": "file-name", + "drive-space-id": "space-id", + "file-size-bytes": "file-size", + "filename": "file-name", + "folder-id": "folder", + "name": "file-name", + "parent-directory-id": "folder", + "size-bytes": "file-size", + "storage-space-id": "space-id", + "upload-name": "file-name", + }, + Blocked: []string{"knowledge-base-id", "limit", "page-size", "part-size", "size", "space", "wiki-workspace-id", "workspace", "workspace-id"}, }, { CLIPath: "mail +find-mail-user", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index db93b507..edc6a396 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -10,10 +10,10 @@ }, "concepts": { - "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"}, - "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "mail thread list", "oa +list-executed"], "risk": "green"}, + "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "drive +find-file", "drive +search", "drive +search-docs", "drive search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"}, + "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +search-docs", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive permission list", "drive recent", "drive recycle list", "drive search", "drive star list", "mail thread list", "oa +list-executed"], "risk": "green"}, "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"}, - "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list"], "risk": "green"}, + "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive recent", "drive recycle list", "drive search", "drive star list"], "risk": "green"}, "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc +checkpoint-update", "doc +comment-create", "doc +comment-reply", "doc +comment-update", "doc +create", "doc +doc-append", "doc block insert", "doc block update", "doc comment create", "doc comment create-inline", "doc comment reply", "doc comment update", "doc create"], "risk": "green"}, "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"}, "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"}, @@ -31,20 +31,31 @@ "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat +messages-batch-send-by-bot", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot"], "risk": "yellow"}, "open_dingtalk_ids": {"denotes": "DingTalk openDingTalkId list with unchanged element values", "canonical_hint": "open-dingtalk-ids", "members": ["open-dingtalk-ids"], "excludes": ["user", "user-id", "user-ids", "staff-id", "users"], "commands": ["chat +chat-members-get", "chat category create-smart", "chat group members list-by-ids", "chat message send-by-bot"], "risk": "yellow"}, "ding_id": {"denotes": "DING id", "canonical_hint": "ding-id", "members": ["ding-id", "open-ding-id"], "excludes": ["id"], "commands": ["ding message receiver-status"], "risk": "yellow"}, - "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive list", "mail folder update"], "risk": "green"}, - "space_id": {"denotes": "drive/wiki/Doc workspace id with unchanged value", "canonical_hint": "space-id", "members": ["space-id", "space", "workspace", "workspace-id"], "excludes": ["folder", "node"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive info"], "risk": "yellow"}, + "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive +copy", "drive +create-folder", "drive +create-shortcut", "drive +list", "drive +move", "drive +upload", "drive commit", "drive copy", "drive list", "drive mkdir", "drive move", "drive shortcut", "drive upload", "drive upload-info", "mail folder update"], "risk": "green"}, + "drive_storage_space_id": {"denotes": "single numeric DingDrive storage space ID with unchanged value", "canonical_hint": "space-id", "members": ["space-id", "drive-space-id", "storage-space-id", "dingdrive-space-id"], "excludes": ["space", "workspace", "workspace-id", "knowledge-base-id", "wiki-workspace-id"], "commands": ["drive +create-folder", "drive +download", "drive +info", "drive +inspect", "drive +list", "drive +recycle-list", "drive +upload", "drive commit", "drive download", "drive info", "drive list", "drive mkdir", "drive recycle list", "drive upload", "drive upload-info"], "risk": "yellow"}, "app_id": {"denotes": "application id", "canonical_hint": "unified-app-id", "members": ["app-id", "unified-app-id", "application-id"], "excludes": ["app-key", "app-secret", "agent-id"], "commands": ["dev app get"], "risk": "yellow"}, "robot_code": {"denotes": "robot code", "canonical_hint": "robot-code", "members": ["robot-code", "robot"], "excludes": ["robot-id", "bot-id", "open-bot-id", "bot-code"], "commands": ["chat +chat-add-bot", "chat +messages-batch-recall-by-bot", "chat +messages-batch-send-by-bot", "chat +messages-recall-by-bot", "chat +messages-send-by-bot", "chat group members add-bot", "chat message recall-by-bot", "chat message send-by-bot", "ding message send"], "risk": "yellow"}, "open_bot_id": {"denotes": "single DingTalk openBotId with unchanged value", "canonical_hint": "bot-id", "members": ["bot-id", "open-bot-id"], "excludes": ["robot-code", "robot", "robot-id", "bot-code"], "commands": ["chat +chat-remove-bot", "chat group members remove-bot"], "risk": "yellow"}, - "doc_node_id": {"denotes": "single DingTalk document nodeId or accepted document URL/token with unchanged value", "canonical_hint": "node", "members": ["node", "node-id", "doc", "doc-id", "file-id", "document-id", "url"], "excludes": ["id", "folder", "folder-id", "parent-id", "workspace", "workspace-id", "block-id", "comment-id", "comment-key", "job-id", "task-id", "template-id", "version", "revision"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +background-delete", "doc +background-update", "doc +checkpoint-update", "doc +comment-create", "doc +comment-delete", "doc +comment-list", "doc +comment-reply", "doc +comment-update", "doc +copy", "doc +doc-append", "doc +export", "doc +export-submit", "doc +fetch", "doc +history-list", "doc +history-revert", "doc +history-save", "doc +inspect", "doc +move", "doc +review", "doc +version-list", "doc +version-revert", "doc +version-save", "doc block delete", "doc block insert", "doc block list", "doc block update", "doc comment create", "doc comment create-inline", "doc comment delete", "doc comment list", "doc comment reply", "doc comment update", "doc export", "doc info", "doc media download", "doc media insert", "doc media upload", "doc read", "doc style background clear", "doc style background set", "doc style cover clear", "doc style cover set", "doc style get", "doc update", "doc version list", "doc version revert", "doc version save", "doc whiteboard insert"], "risk": "yellow"}, + "doc_node_id": {"denotes": "single DingTalk document nodeId or accepted document URL/token with unchanged value", "canonical_hint": "node", "members": ["node", "node-id", "doc", "doc-id", "file-id", "document-id", "url", "dentry-uuid"], "excludes": ["id", "folder", "folder-id", "parent-id", "workspace", "workspace-id", "block-id", "comment-id", "comment-key", "job-id", "task-id", "template-id", "version", "revision", "dentry-id", "space-id", "name", "role"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +background-delete", "doc +background-update", "doc +checkpoint-update", "doc +comment-create", "doc +comment-delete", "doc +comment-list", "doc +comment-reply", "doc +comment-update", "doc +copy", "doc +doc-append", "doc +export", "doc +export-submit", "doc +fetch", "doc +history-list", "doc +history-revert", "doc +history-save", "doc +inspect", "doc +move", "doc +review", "doc +version-list", "doc +version-revert", "doc +version-save", "doc block delete", "doc block insert", "doc block list", "doc block update", "doc comment create", "doc comment create-inline", "doc comment delete", "doc comment list", "doc comment reply", "doc comment update", "doc export", "doc info", "doc media download", "doc media insert", "doc media upload", "doc read", "doc style background clear", "doc style background set", "doc style cover clear", "doc style cover set", "doc style get", "doc update", "doc version list", "doc version revert", "doc version save", "doc whiteboard insert"], "risk": "yellow"}, "doc_comment_key": {"denotes": "single DingTalk document commentKey with unchanged value", "canonical_hint": "comment-key", "members": ["comment-key", "comment-id"], "excludes": ["id", "node", "node-id", "doc-id", "block-id"], "commands": ["doc +comment-delete", "doc +comment-reply", "doc +comment-update", "doc comment delete", "doc comment reply", "doc comment update"], "risk": "yellow"}, - "doc_version_number": {"denotes": "single DingTalk document historical version number with unchanged integer value", "canonical_hint": "version", "members": ["version", "version-number", "version-no"], "excludes": ["revision", "id", "node", "node-id", "doc-id"], "commands": ["doc +history-revert", "doc +version-revert", "doc version revert"], "risk": "yellow"}, + "doc_version_number": {"denotes": "single document or Drive ordinary-file historical version number with unchanged positive integer value", "canonical_hint": "version", "members": ["version", "version-number", "version-no"], "excludes": ["revision", "id", "node", "node-id", "doc-id"], "commands": ["doc +history-revert", "doc +version-revert", "doc version revert", "drive +version-download", "drive +version-get", "drive +version-revert", "drive download", "drive download-version", "drive revert"], "risk": "yellow"}, "doc_content_format": {"denotes": "DingTalk document body format with unchanged markdown/jsonml value", "canonical_hint": "content-format", "members": ["content-format", "doc-format"], "excludes": ["format", "export-format", "mime-type"], "commands": ["doc +create", "doc +update", "doc create", "doc update"], "risk": "green"}, - "doc_edit_revision": {"denotes": "single optimistic-concurrency revision for a document edit", "canonical_hint": "revision", "members": ["revision", "expected-revision"], "excludes": ["version", "version-number", "version-no"], "commands": ["doc +update", "doc update"], "risk": "yellow"} + "doc_edit_revision": {"denotes": "single optimistic-concurrency revision for a document edit", "canonical_hint": "revision", "members": ["revision", "expected-revision"], "excludes": ["version", "version-number", "version-no"], "commands": ["doc +update", "doc update"], "risk": "yellow"}, + "drive_recycle_item_id": {"denotes": "single Drive recycle-bin item ID returned by recycle list", "canonical_hint": "id", "members": ["id", "recycle-item-id", "trash-item-id", "deleted-item-id"], "excludes": ["node", "node-id", "file-id", "folder-id", "space-id", "workspace-id"], "commands": ["drive +recycle-restore", "drive recycle restore"], "risk": "yellow"}, + "drive_modified_time_start": {"denotes": "Drive search modified-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "modified-from", "members": ["modified-from", "modified-after", "modify-time-from", "modified-time-start"], "excludes": ["modified-to", "created-from", "created-to", "start", "from"], "commands": ["drive +search", "drive search"], "risk": "yellow"}, + "drive_modified_time_end": {"denotes": "Drive search modified-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "modified-to", "members": ["modified-to", "modified-before", "modify-time-to", "modified-time-end"], "excludes": ["modified-from", "created-from", "created-to", "end", "to"], "commands": ["drive +search", "drive search"], "risk": "yellow"}, + "drive_file_size_bytes": {"denotes": "file size in bytes passed unchanged", "canonical_hint": "file-size", "members": ["file-size", "file-size-bytes", "size-bytes", "content-length"], "excludes": ["part-size", "page-size", "limit", "size"], "commands": ["drive commit", "drive upload-info"], "risk": "yellow"}, + "drive_sort_direction": {"denotes": "Drive result sort direction with unchanged asc/desc enum", "canonical_hint": "order", "members": ["order", "sort", "sort-direction", "order-direction"], "excludes": ["order-by", "sort-by", "order-field"], "commands": ["drive +list", "drive list", "drive star list"], "risk": "green"}, + "workspace_id": {"denotes": "single knowledge-base or document-space workspace ID/URL passed unchanged; never a numeric DingDrive storage space ID", "canonical_hint": "workspace", "members": ["workspace", "workspace-id", "knowledge-base-id", "wiki-workspace-id"], "excludes": ["space", "space-id", "drive-space-id", "storage-space-id", "dingdrive-space-id", "folder", "folder-id", "node", "node-id", "dentry-id"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive +copy", "drive +create-shortcut", "drive +move", "drive copy", "drive list", "drive move", "drive permission add", "drive permission list", "drive permission remove", "drive permission transfer-owner", "drive permission update", "drive shortcut", "drive upload"], "risk": "yellow"}, + "created_time_start": {"denotes": "Doc/Drive search created-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "created-from", "members": ["created-from", "created-after", "create-time-from", "created-time-start"], "excludes": ["created-to", "modified-from", "modified-to", "start", "from"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, + "created_time_end": {"denotes": "Doc/Drive search created-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "created-to", "members": ["created-to", "created-before", "create-time-to", "created-time-end"], "excludes": ["created-from", "modified-from", "modified-to", "end", "to"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, + "document_permission_role": {"denotes": "direct document-space permission role on grant/apply/update, passed unchanged", "canonical_hint": "role", "members": ["role", "permission-role", "access-role", "member-role"], "excludes": ["filter-role", "reserve-role", "permission", "public-permission"], "commands": ["doc +access-change", "doc +access-grant", "doc +grant-and-share", "drive permission add", "drive permission apply", "drive permission update"], "risk": "yellow"}, + "creator_user_ids": {"denotes": "creator userId list used to filter Doc/Drive search results, passed unchanged", "canonical_hint": "creator-uids", "members": ["creator-uids", "creator-user-ids", "creator-ids", "created-by-user-ids"], "excludes": ["user", "user-id", "user-ids", "users", "owner-id", "modifier-uids"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, + "local_output_path": {"denotes": "local destination file or directory path for a download/export result, passed unchanged", "canonical_hint": "output", "members": ["output", "output-path", "destination-path", "save-path"], "excludes": ["file", "file-path", "folder", "folder-id", "content-file"], "commands": ["doc +export", "doc +export-get", "doc +media-download", "doc +resource-download", "doc read", "drive +download", "drive +version-download", "drive download", "drive download-version"], "risk": "green"} }, "command_overrides": { - "doc +version-list": {"ambiguous": ["size", "max-results", "max-result", "take", "top", "per-page", "next-cursor", "next-token", "next-page-token"], "note": "--limit/--cursor and the shipped visible compatibility flags --page-size/--page-token remain native. Other pagination spellings cannot choose between two visible real flags and must stop before execution."}, + "doc +version-list": {"ambiguous": ["size", "max-results", "max-result", "take", "top", "per-page", "next-cursor", "next-token", "next-page-token"], "note": "--limit/--cursor and the shipped visible compatibility flags --page-size/--page-token remain native. Other pagination spellings cannot choose between two visible real flags and must stop before execution."}, "chat group rename": {"bind": {"id": "open_conversation_id"}, "note": "This command's real --id carries one openConversationId; aliases reduce to --id without changing the value."}, "chat group members": {"bind": {"id": "open_conversation_id"}}, "chat group members add": {"bind": {"id": "open_conversation_id"}, "block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a list and may contain mixed userId/openDingTalkId values; singular inputs are not promoted automatically."}, @@ -54,8 +65,8 @@ "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id stay native; numeric groupId and list spellings are rejected."}, "chat mute": {"scoped_aliases": {"group": "conversation-id", "chat-id": "conversation-id", "open-conversation-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id/--id/--chat remain unchanged; other reviewed openConversationId spellings reduce to --conversation-id."}, - "drive list": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, - "drive upload": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, + "drive list": {"ambiguous": ["root-id", "space"], "note": "Numeric --space-id and knowledge-base --workspace are distinct routes; bare --space/--root-id cannot select a domain or folder.", "scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}, "scope_strict": true, "block": ["dentry-id"]}, + "drive upload": {"ambiguous": ["destination-id", "space", "target-id"], "note": "Local file, display name, MIME, overwrite node, folder, storage space, and knowledge-base workspace remain distinct roles.", "scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "overwrite-node-id": "node", "target-folder-id": "folder", "target-workspace-id": "workspace", "source-file": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "output-path"], "scope_strict": true}, "ding +receiver-status": {"scoped_aliases": {"id": "ding-id"}, "note": "generic id reduces to ding-id"}, "ding message receiver-status": {"scoped_aliases": {"id": "ding-id"}}, "contact user profile get": {"scoped_aliases": {"id": "staff-id", "ids": "staff-id"}, "note": "user-id is reduced by the user_id concept; generic id/ids bound explicitly"}, @@ -114,7 +125,7 @@ "doc export get": {"scoped_aliases": {"export-job-id": "job-id"}, "block": ["doc-id", "document-id", "file-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one export jobId. Document node identifiers are rejected; native hidden --task-id remains the command's reviewed add-only compatibility alias for --job-id."}, "doc import get": {"scoped_aliases": {"import-task-id": "task-id"}, "block": ["doc-id", "document-id", "file-id", "job-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one import taskId. Document node identifiers and export jobId spellings are different entities and are rejected."}, "doc +share-doc": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a document nodeId into a URL, so identifier spellings are rejected with guidance to provide --url."}, - "doc update": {"block": ["version", "version-no", "version-number"], "note": "--revision is an optimistic-concurrency revision, not a historical document version number. Version spellings must not reduce to --revision."}, + "doc update": {"block": ["stdin", "version", "version-no", "version-number"], "note": "--revision is an optimistic-concurrency revision, not a historical document version number. Version spellings must not reduce to --revision. --stdin is not a real switch: stdin input is expressed as --content -, which requires a value-form transformation outside central name aliases."}, "report outbox list": {"block": ["template-type"], "note": "type vs name are different fields"}, "chat group members add-bot": {"bind": {"id": "open_conversation_id"}}, "chat group members list-by-ids": {"bind": {"id": "open_conversation_id", "users": "open_dingtalk_ids"}, "block": ["user-id", "user-ids"], "note": "This command's --id carries openConversationId, while --users carries an openDingTalkId list."}, @@ -158,21 +169,80 @@ "chat +messages-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values, not openMessageId values."}, "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["group", "msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The observed --group spelling carried a natural group name and is blocked. The only message role is the referenced message; plural IDs are not accepted, while --chat remains a CID alias and native --message-id stays native."}, "chat +messages-resource-download": {"block": ["download-dir"], "note": "--output may be a file or directory under workspace safety rules; a download directory cannot be assumed equivalent."}, + "doc +access-grant": {"block": ["target-user-id", "target-user-ids", "user-id", "user-ids"], "ambiguous": ["target-user", "user", "users"], "scope_strict": true, "note": "The real --to accepts collaborator names and resolves them before granting access. Explicit ID spellings cannot be passed through unchanged, while role-free user spellings do not prove whether their values are names or IDs."}, "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create."}, "doc +create-from-template": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, "doc +import": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, - "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value."}, - "doc +inspect": {"scoped_aliases": {"include-versions": "include-history"}, "block": ["include", "include-info"], "scope_strict": true, "note": "Historical versions and history are the same optional section on this exact shortcut. Generic --include needs value-dependent flag expansion, while base document info is always returned, so those spellings are rejected with precise guidance."}, - "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary and must stop before execution."}, + "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "ambiguous": ["element"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value. --element cannot choose between document content, a block target, or an insertion reference."}, + "doc +inspect": {"scoped_aliases": {"include-access": "include-permissions", "include-member": "include-permissions", "include-members": "include-permissions", "include-versions": "include-history"}, "block": ["include", "include-blocks", "include-content", "include-info", "include-meta", "include-metadata"], "scope_strict": true, "note": "Access/member spellings denote the same optional permission list, and versions/history denote the same history section. Generic --include needs value-dependent expansion; base metadata is already returned; block/content reads belong to +fetch, so those spellings stop before fuzzy correction or dispatch."}, + "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "block": ["content-format", "doc-format", "range"], "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary. --range is an invented composite argument observed alongside --scope range and cannot be split into block IDs by name-only normalization; content-format spellings do not map to the independent --detail contract."}, + "doc +export": {"block": ["wait"], "scope_strict": true, "note": "The shortcut already submits, polls, and downloads in one workflow. A generic --wait value cannot be converted into the distinct integer --max-polls contract by parameter-name normalization."}, "doc +media-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose between document and media identities."}, - "doc +media-insert": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and local-media roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."}, + "doc +media-insert": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "block": ["after-block-id", "before-block-id"], "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and local-media roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role. Before/after block spellings each require expansion into both --ref-block and --where, which name-only normalization cannot perform."}, "doc +media-list": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "The command lists media inside one document, so only strong document spellings map to --node. File and URL spellings remain role-ambiguous."}, "doc +media-preview": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."}, "doc +resource-delete": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command removes a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."}, "doc +resource-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command downloads a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."}, "doc +resource-update": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has document-node, local-file, and HTTPS image URL roles. Only strong document spellings map to --node; --file-id and --url must stop as ambiguous."}, "doc +share": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a node identifier into a URL, so identifier spellings are rejected with guidance to provide --url."}, - "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native."} + "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native."}, + "doc +version-save": {"block": ["message", "title"], "scope_strict": true, "note": "The current snapshot API accepts only the document target. Version title/message metadata are unsupported and cannot be represented by another existing flag."}, + "drive copy": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]}, + "drive cover": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive download-version": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "chunk-size": "part-size", "concurrency": "parallel", "parallelism": "parallel"}, "scope_strict": true, "note": "Output path, chunk size, and concurrency names preserve values; local input and remote folder roles remain blocked.", "block": ["dentry-id", "file", "file-path", "folder", "folder-id"]}, + "drive move": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]}, + "drive permission add": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]}, + "drive permission apply": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "approver-user-ids": "users", "approver-ids": "users", "target-node-id": "node", "apply-reason": "reason", "notification-mode": "notify-mode"}, "scope_strict": true, "note": "The user list denotes approvers, not target collaborators; values and notification enum are passed unchanged.", "block": ["dentry-id"]}, + "drive permission apply-info": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive permission list": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "role-filter": "filter-role", "permission-role-filter": "filter-role", "target-node-id": "node"}, "scope_strict": true, "note": "Filtering by a role is not the same as granting/updating a role.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "permission", "role", "space-id", "storage-space-id"]}, + "drive permission remove": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]}, + "drive permission transfer-owner": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "target-node-id": "node", "target-workspace-id": "workspace", "old-owner-role": "reserve-role", "keep-role": "reserve-role", "new-owner-id": "new-owner", "new-owner-user-id": "new-owner"}, "scope_strict": true, "note": "Node/workspace target and new/old owner roles are distinct on this irreversible command; role-free names stop before dispatch.", "block": ["current-owner", "dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id", "user-ids", "users"], "ambiguous": ["owner", "owner-user-id", "target-id", "user-id"]}, + "drive permission update": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "member-user-ids": "users", "collaborator-ids": "users", "target-user-ids": "users", "target-node-id": "node"}, "scope_strict": true, "note": "The user list denotes target collaborators on this exact node permission command; the native singular compatibility spellings remain native.", "block": ["dentry-id", "dingdrive-space-id", "drive-space-id", "space-id", "storage-space-id"]}, + "drive publish get": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive publish set": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "public-permission": "permission", "public-role": "permission"}, "scope_strict": true, "note": "Internet-public permission is not the same as a direct collaborator role.", "block": ["access-role", "dentry-id", "permission-role", "role"]}, + "drive publish unset": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive rename": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "file-name": "name", "display-name": "name", "new-name": "name"}, "scope_strict": true, "note": "The name is this exact folder/node display name; search query and local path are different roles.", "block": ["dentry-id"]}, + "drive revert": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive shortcut": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]}, + "drive star add": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive star remove": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive stats": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, + "drive +cover": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "This shortcut calls the same get_cover nodeId interface as drive cover, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId, folder-role spellings and --name remain protected."}, + "drive +copy": {"scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "ambiguous": ["destination-id", "target-id"]}, + "drive +create-folder": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "folder-name": "name", "display-name": "name", "new-name": "name"}, "block": ["dentry-id", "parent-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "The new shortcut creates a numeric DingDrive-space folder. Folder display name, parent dentryUuid and numeric storage space are separate roles; knowledge-base workspace spellings are not accepted."}, + "drive +create-shortcut": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "doc", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles. The source ID/URL aliases match drive shortcut and pass through unchanged; generic target/id spellings remain ambiguous, and storage-space IDs are not knowledge-base workspace IDs.", "ambiguous": ["destination-id", "id", "target-id"]}, + "drive +delete": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "folder": "node", "folder-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "id", "name", "url"], "scope_strict": true, "note": "Delete targets one already confirmed Drive file or folder dentryUuid. Folder spellings are the same single target role; numeric dentryId, unreviewed Doc URL spellings and --name stop before confirmation or write dispatch."}, + "drive +download": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "knowledge-base-id", "name", "url", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "The remote ordinary-file node and local output path are different roles. Node-ID spelling is accepted, while Doc URLs, local input paths, folders, knowledge-base workspaces and numeric dentryId values are not interchangeable."}, + "drive +info": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."}, + "drive +inspect": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "folder": "node", "folder-id": "node", "include-statistics": "include-stats", "include-publish-status": "include-publish", "include-public-status": "include-publish", "include-thumbnail": "include-cover"}, "block": ["dentry-id", "doc", "document-url", "id", "include", "include-content", "include-history", "include-permissions", "name", "url"], "scope_strict": true, "note": "Drive inspect accepts one file, folder or document node ID and can aggregate only stats, public-publish status and cover. URL spellings, Doc inspect section names and a generic --include remain protected because this shortcut does not declare URL input or value splitting."}, + "drive +list": {"ambiguous": ["root-id", "space"], "scoped_aliases": {"directory-id": "folder", "parent-folder-id": "folder", "order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}, "block": ["dentry-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This shortcut accepts one numeric DingDrive space and an optional parent dentryUuid; it does not accept a knowledge-base workspace. Sort field and direction remain separate roles."}, + "drive +move": {"scoped_aliases": {"dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "document-url", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "ambiguous": ["destination-id", "target-id"]}, + "drive +publish-get": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same publication-status fileId interface as drive publish get, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."}, + "drive +publish-unset": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same set_file_publish fileId interface as drive publish unset, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected before confirmation."}, + "drive +recycle-restore": {"bind": {"id": "drive_recycle_item_id"}, "block": ["file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"], "scope_strict": true, "note": "The real --id is a recycleItemId returned by drive +recycle-list, not a normal Drive node ID."}, + "drive +rename": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node", "folder": "node", "folder-id": "node", "file-name": "name", "display-name": "name", "new-name": "name"}, "block": ["dentry-id"], "scope_strict": true, "note": "The existing document, file or folder node and the requested new display name are separate required roles. Node ID/URL aliases match drive rename and pass through unchanged; numeric dentryId remains protected."}, + "drive delete": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url"], "scope_strict": true, "note": "This command publicly accepts an ID-only Drive node; dentry spellings preserve the value and URL-specific spellings remain protected."}, + "drive download": {"scoped_aliases": {"dentry-uuid": "node", "chunk-size": "part-size", "concurrency": "parallel", "parallelism": "parallel"}, "block": ["dentry-id", "document-url", "file", "file-path", "folder", "folder-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "Output path, chunk size, and concurrency names preserve values; local input and remote folder roles remain blocked."}, + "drive info": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."}, + "drive commit": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "upload-session-id": "upload-id", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "Upload session, file name, file size in bytes, parent folder, and storage space remain separate roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, + "drive mkdir": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "folder-name": "name", "display-name": "name", "new-name": "name"}, "scope_strict": true, "note": "The name is this exact folder/node display name; search query and local path are different roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, + "drive upload-info": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "content-type": "mime-type", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "File metadata aliases preserve MIME and byte units; file path and upload session are different stages.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, + "drive recycle list": {"block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."}, + "drive search": {"ambiguous": ["end", "from", "start", "time-from", "time-to", "to", "types"], "block": ["offset", "page"], "scope_strict": true, "note": "Created/modified ranges and file/content type arrays are separate roles; generic time/type names are not guessed."}, + "drive +search": {"ambiguous": ["end", "from", "start", "time-from", "time-to", "to", "types"], "block": ["offset", "page"], "scope_strict": true, "note": "Created/modified ranges and file/content type arrays are separate roles; generic time/type names are not guessed."}, + "drive +star-add": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same mark_star nodeId interface as drive star add, so its reviewed document/node ID and URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."}, + "drive +star-remove": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same unmark_star nodeId interface as drive star remove, so its reviewed document/node ID and URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."}, + "drive +stats": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node"}, "block": ["dentry-id", "doc", "folder", "folder-id", "name"], "scope_strict": true, "note": "The shortcut calls the same get_node_stats nodeId interface as drive stats, so its reviewed ID/URL aliases are preserved unchanged. Numeric dentryId and folder/name roles remain protected."}, + "drive +version-download": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "file", "file-path", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "Ordinary-file node, positive historical version number and local output path are three distinct roles; revision and Doc URL spellings must not be guessed."}, + "drive +version-get": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "This command reads one ordinary-file historical version by node ID and positive version number; document revision and URL roles are different."}, + "drive +version-history": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "This command pages versions for one ordinary-file Drive node; document URLs and numeric dentryId are not accepted."}, + "drive +version-revert": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node"}, "block": ["dentry-id", "doc", "doc-id", "document-id", "document-url", "folder", "folder-id", "id", "name", "url"], "scope_strict": true, "note": "The high-risk revert targets one ordinary-file Drive node and a positive historical version number. Doc revisions and URLs must stop before confirmation or write dispatch."}, + "drive recycle restore": {"bind": {"id": "drive_recycle_item_id"}, "block": ["file-id", "folder-id", "node", "node-id", "space-id", "workspace-id"], "scope_strict": true, "note": "The real --id is a recycle-item ID from recycle list, not a normal Drive node ID."}, + "drive star list": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Content types and resource types are separate arrays; a generic type list cannot choose one.", "scoped_aliases": {"order-field": "order-by", "sort-by": "order-by", "sort-field": "order-by"}}, + "drive recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."}, + "drive +recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."}, + "drive +star-list": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "The shortcut exposes only the API contentTypes filter. Generic type spellings may denote file extensions or node/resource types, so the current name-only layer must not guess the value domain."}, + "drive +upload": {"ambiguous": ["destination-id", "space", "target-id"], "scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "overwrite-node-id": "node", "directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "target-folder-id": "folder", "source-file": "file", "local-file": "file", "file-path": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id", "output-path"], "scope_strict": true, "note": "Local source path, remote display name, MIME type, parent folder, numeric storage space and optional overwrite node are distinct roles. ID-suffixed file/node spellings denote the overwrite target; the shortcut does not expose a knowledge-base workspace route."} }, "validation_fixture": { @@ -243,7 +313,7 @@ {"command": "doc +export-get", "emitted": "node", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "doc block delete", "emitted": "index", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "doc block insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-multi-parameter-transform", "occ": 2}, - {"command": "drive info", "emitted": "workspace", "expect": "space-id", "via": "concept:space_id", "occ": 2}, + {"command": "drive info", "emitted": "workspace", "expect": "did-you-mean:blocked", "via": "guard:workspace-vs-numeric-storage-space", "occ": 2}, {"command": "mail folder update", "emitted": "folder-id", "expect": "id", "via": "override:bind(folder_id)", "occ": 2}, {"command": "report outbox list", "emitted": "template-type", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "chat +group-members", "emitted": "group-name", "expect": "group", "via": "concept:group_name+bind"}, @@ -325,7 +395,7 @@ {"command": "doc +search", "emitted": "q", "expect": "query", "via": "concept:search_query"}, {"command": "doc +comment-list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size"}, {"command": "doc +list", "emitted": "page-token", "expect": "cursor", "via": "concept:page_cursor"}, - {"command": "doc +copy", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"}, + {"command": "doc +copy", "emitted": "workspace-id", "expect": "workspace", "via": "concept:workspace_id"}, {"command": "doc +copy", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"}, {"command": "doc +copy", "emitted": "parent-id", "expect": "did-you-mean:blocked", "via": "guard:doc-folder-value-domain"}, {"command": "doc +comment-reply", "emitted": "comment-id", "expect": "comment-key", "via": "concept:doc_comment_key"}, @@ -415,9 +485,9 @@ {"command": "doc +create", "emitted": "content-format", "expect": "doc-format", "via": "concept:doc_content_format"}, {"command": "doc +create", "emitted": "content-file", "expect": "did-you-mean:blocked", "via": "guard:requires-file-read-transform"}, {"command": "doc +inspect", "emitted": "include-versions", "expect": "include-history", "via": "override:scoped-section"}, - {"command": "doc +inspect", "emitted": "include", "expect": "did-you-mean:blocked", "via": "guard:requires-value-dependent-flag-expansion"}, - {"command": "doc +inspect", "emitted": "include-info", "expect": "did-you-mean:blocked", "via": "guard:base-info-always-returned"}, - {"command": "doc +update", "emitted": "mode", "expect": "command", "via": "override:scoped-operation"}, + {"command": "doc +inspect", "emitted": "include", "expect": "did-you-mean:blocked", "via": "guard:requires-value-dependent-flag-expansion", "occ": 1}, + {"command": "doc +inspect", "emitted": "include-info", "expect": "did-you-mean:blocked", "via": "guard:base-info-always-returned", "occ": 1}, + {"command": "doc +update", "emitted": "mode", "expect": "command", "via": "override:scoped-operation", "occ": 5}, {"command": "doc +update", "emitted": "revision", "expect": "expected-revision", "via": "concept:doc_edit_revision"}, {"command": "doc +update", "emitted": "version", "expect": "did-you-mean:blocked", "via": "guard:historical-version-vs-edit-revision"}, {"command": "doc +fetch", "emitted": "start-block", "expect": "start-block-id", "via": "override:scoped-boundary-role"}, @@ -425,11 +495,152 @@ {"command": "doc +access-grant", "emitted": "doc-id", "expect": "node", "via": "concept:doc_node_id"}, {"command": "doc +history-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"}, {"command": "doc +create-from-template", "emitted": "keyword", "expect": "query", "via": "concept:search_query"}, - {"command": "doc +create-from-template", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"}, + {"command": "doc +create-from-template", "emitted": "workspace-id", "expect": "workspace", "via": "concept:workspace_id"}, {"command": "doc +create-from-template", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"}, {"command": "doc +media-download", "emitted": "file-id", "expect": "did-you-mean:ambiguous", "via": "guard:document-node-vs-attachment-resource-role"}, {"command": "doc +resource-update", "emitted": "url", "expect": "did-you-mean:ambiguous", "via": "guard:document-url-vs-image-url-role"}, - {"command": "doc +share", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"} + {"command": "doc +share", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"}, + {"command": "doc +copy", "emitted": "dentry-uuid", "expect": "node", "via": "concept:doc_node_id"}, + {"command": "doc info", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-dentry-uuid"}, + {"command": "doc create", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"}, + {"command": "doc create", "emitted": "space-id", "expect": "did-you-mean:blocked", "via": "guard:storage-space-vs-workspace"}, + {"command": "drive list", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"}, + {"command": "drive list", "emitted": "order-field", "expect": "order-by", "via": "override:scoped-sort-field"}, + {"command": "drive info", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-node-id"}, + {"command": "drive info", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-dentry-uuid"}, + {"command": "drive copy", "emitted": "target-folder-id", "expect": "folder", "via": "override:scoped-destination-folder"}, + {"command": "drive copy", "emitted": "target-id", "expect": "did-you-mean:ambiguous", "via": "guard:destination-role-required"}, + {"command": "drive search", "emitted": "created-after", "expect": "created-from", "via": "concept:created_time_start"}, + {"command": "drive search", "emitted": "created-before", "expect": "created-to", "via": "concept:created_time_end"}, + {"command": "drive search", "emitted": "modified-after", "expect": "modified-from", "via": "concept:drive_modified_time_start"}, + {"command": "drive search", "emitted": "modified-before", "expect": "modified-to", "via": "concept:drive_modified_time_end"}, + {"command": "drive search", "emitted": "creator-user-ids", "expect": "creator-uids", "via": "concept:creator_user_ids"}, + {"command": "drive permission add", "emitted": "permission-role", "expect": "role", "via": "concept:document_permission_role"}, + {"command": "drive permission list", "emitted": "role", "expect": "did-you-mean:blocked", "via": "guard:permission-role-vs-filter-role"}, + {"command": "drive upload", "emitted": "source-file", "expect": "file", "via": "override:scoped-local-file"}, + {"command": "doc +search", "emitted": "created-after", "expect": "created-from", "via": "concept:created_time_start"}, + {"command": "doc +search", "emitted": "creator-user-ids", "expect": "creator-uids", "via": "concept:creator_user_ids"}, + {"command": "doc +access-grant", "emitted": "permission-role", "expect": "role", "via": "concept:document_permission_role"}, + {"command": "doc +export", "emitted": "output-path", "expect": "output", "via": "concept:local_output_path"}, + {"command": "drive download", "emitted": "destination-path", "expect": "output", "via": "concept:local_output_path"}, + {"command": "drive download", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"}, + {"command": "drive recycle restore", "emitted": "recycle-item-id", "expect": "id", "via": "concept:drive_recycle_item_id"}, + {"command": "drive upload-info", "emitted": "size-bytes", "expect": "file-size", "via": "concept:drive_file_size_bytes"}, + {"command": "drive +info", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive commit", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive download", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive info", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive list", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive list", "emitted": "sort-direction", "expect": "order", "via": "concept:drive_sort_direction"}, + {"command": "drive mkdir", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive recycle list", "emitted": "drive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive upload", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive upload-info", "emitted": "dingdrive-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "doc +access-grant", "emitted": "user", "expect": "did-you-mean:ambiguous", "via": "guard:collaborator-name-vs-id-value-domain", "occ": 6}, + {"command": "doc +access-grant", "emitted": "target-user", "expect": "did-you-mean:ambiguous", "via": "guard:collaborator-name-vs-id-value-domain", "occ": 1}, + {"command": "doc +access-grant", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver", "occ": 1}, + {"command": "doc +access-grant", "emitted": "user-ids", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver", "occ": 1}, + {"command": "doc +access-grant", "emitted": "target-user-id", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver"}, + {"command": "doc +access-grant", "emitted": "target-user-ids", "expect": "did-you-mean:blocked", "via": "guard:user-id-cannot-feed-name-resolver"}, + {"command": "doc +fetch", "emitted": "content-format", "expect": "did-you-mean:blocked", "via": "guard:content-format-vs-detail-contract", "occ": 3}, + {"command": "doc +fetch", "emitted": "doc-format", "expect": "did-you-mean:blocked", "via": "guard:content-format-vs-detail-contract", "occ": 1}, + {"command": "doc +fetch", "emitted": "range", "expect": "did-you-mean:blocked", "via": "guard:composite-range-needs-block-ids", "occ": 1}, + {"command": "doc +inspect", "emitted": "include-access", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 3}, + {"command": "doc +inspect", "emitted": "include-member", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 1}, + {"command": "doc +inspect", "emitted": "include-members", "expect": "include-permissions", "via": "override:scoped-permission-section", "occ": 2}, + {"command": "doc +inspect", "emitted": "include-meta", "expect": "did-you-mean:blocked", "via": "guard:base-metadata-already-returned", "occ": 2}, + {"command": "doc +inspect", "emitted": "include-metadata", "expect": "did-you-mean:blocked", "via": "guard:base-metadata-already-returned", "occ": 1}, + {"command": "doc +inspect", "emitted": "include-blocks", "expect": "did-you-mean:blocked", "via": "guard:content-read-belongs-to-fetch", "occ": 1}, + {"command": "doc +inspect", "emitted": "include-content", "expect": "did-you-mean:blocked", "via": "guard:content-read-belongs-to-fetch", "occ": 1}, + {"command": "doc +inspect", "emitted": "role", "expect": "did-you-mean:blocked", "via": "guard:permission-role-vs-document-node", "occ": 1}, + {"command": "doc +copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role", "occ": 2}, + {"command": "doc +export", "emitted": "wait", "expect": "did-you-mean:blocked", "via": "guard:workflow-wait-vs-max-polls", "occ": 1}, + {"command": "doc +media-insert", "emitted": "after-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-ref-block-and-where-expansion", "occ": 1}, + {"command": "doc +media-insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-ref-block-and-where-expansion"}, + {"command": "doc +update", "emitted": "content-file", "expect": "did-you-mean:blocked", "via": "guard:requires-file-read-transform", "occ": 1}, + {"command": "doc +update", "emitted": "element", "expect": "did-you-mean:ambiguous", "via": "guard:content-vs-block-vs-reference-role", "occ": 1}, + {"command": "doc update", "emitted": "stdin", "expect": "did-you-mean:blocked", "via": "guard:stdin-requires-content-dash-transform", "occ": 1}, + {"command": "doc +version-save", "emitted": "title", "expect": "did-you-mean:blocked", "via": "guard:unsupported-version-metadata", "occ": 1}, + {"command": "doc +version-save", "emitted": "message", "expect": "did-you-mean:blocked", "via": "guard:unsupported-version-metadata", "occ": 1}, + {"command": "drive +search", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 1}, + {"command": "contact +search-user", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:person-name-vs-search-query", "occ": 1}, + {"command": "drive copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"}, + {"command": "drive +copy", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"}, + {"command": "drive move", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"}, + {"command": "drive +move", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"}, + {"command": "drive shortcut", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-node-role"}, + {"command": "drive +cover", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +cover", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-drive-node"}, + {"command": "drive +create-folder", "emitted": "folder-name", "expect": "name", "via": "override:scoped-folder-name"}, + {"command": "drive +create-folder", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive +create-shortcut", "emitted": "source-file-id", "expect": "node", "via": "override:scoped-source-node"}, + {"command": "drive +create-shortcut", "emitted": "target-folder-id", "expect": "folder", "via": "override:scoped-target-folder"}, + {"command": "drive +create-shortcut", "emitted": "target-workspace-id", "expect": "workspace", "via": "override:scoped-target-workspace"}, + {"command": "drive +create-shortcut", "emitted": "name", "expect": "did-you-mean:blocked", "via": "guard:fuzzy-name-vs-drive-node"}, + {"command": "drive +delete", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +delete", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-node-id"}, + {"command": "drive +download", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +download", "emitted": "destination-path", "expect": "output", "via": "concept:local_output_path"}, + {"command": "drive +inspect", "emitted": "include-statistics", "expect": "include-stats", "via": "override:scoped-inspect-section"}, + {"command": "drive +inspect", "emitted": "include-history", "expect": "did-you-mean:blocked", "via": "guard:doc-inspect-section"}, + {"command": "drive +list", "emitted": "folder-id", "expect": "folder", "via": "concept:folder_id"}, + {"command": "drive +list", "emitted": "page-size", "expect": "limit", "via": "concept:pagination_size"}, + {"command": "drive +list", "emitted": "next-token", "expect": "cursor", "via": "concept:page_cursor"}, + {"command": "drive +list", "emitted": "sort-direction", "expect": "order", "via": "concept:drive_sort_direction"}, + {"command": "drive +list", "emitted": "sort-by", "expect": "order-by", "via": "override:scoped-sort-field"}, + {"command": "drive +publish-get", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +publish-unset", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +recycle-list", "emitted": "storage-space-id", "expect": "space-id", "via": "concept:drive_storage_space_id"}, + {"command": "drive +recycle-list", "emitted": "page-token", "expect": "cursor", "via": "concept:page_cursor"}, + {"command": "drive +recycle-restore", "emitted": "recycle-item-id", "expect": "id", "via": "override:bind(drive_recycle_item_id)"}, + {"command": "drive +recycle-restore", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:recycle-item-vs-node-id"}, + {"command": "drive +rename", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +rename", "emitted": "new-name", "expect": "name", "via": "override:scoped-display-name"}, + {"command": "drive +star-add", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +star-list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size"}, + {"command": "drive +star-list", "emitted": "types", "expect": "did-you-mean:ambiguous", "via": "guard:content-type-value-domain"}, + {"command": "drive +star-remove", "emitted": "file-id", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +stats", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-drive-node"}, + {"command": "drive +upload", "emitted": "source-file", "expect": "file", "via": "override:scoped-local-file"}, + {"command": "drive +upload", "emitted": "name", "expect": "file-name", "via": "override:scoped-remote-name"}, + {"command": "drive +upload", "emitted": "overwrite-node-id", "expect": "node", "via": "override:scoped-overwrite-node"}, + {"command": "drive +upload", "emitted": "workspace-id", "expect": "did-you-mean:blocked", "via": "guard:unsupported-workspace-route"}, + {"command": "drive +version-download", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"}, + {"command": "drive +version-download", "emitted": "save-path", "expect": "output", "via": "concept:local_output_path"}, + {"command": "drive +version-get", "emitted": "version-no", "expect": "version", "via": "concept:doc_version_number"}, + {"command": "drive +version-history", "emitted": "next-cursor", "expect": "cursor", "via": "concept:page_cursor"}, + {"command": "drive +version-history", "emitted": "page-size", "expect": "limit", "via": "concept:pagination_size"}, + {"command": "drive +version-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"}, + {"command": "drive +version-revert", "emitted": "revision", "expect": "did-you-mean:blocked", "via": "guard:document-revision-vs-file-version"}, + {"command": "drive +cover", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +create-shortcut", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +delete", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +download", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +inspect", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +publish-get", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +publish-unset", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +rename", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +star-add", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +star-remove", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +stats", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +upload", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +version-download", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +version-get", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +version-history", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +version-revert", "emitted": "node-id", "expect": "node", "via": "override:node-id-parity"}, + {"command": "drive +cover", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +create-shortcut", "emitted": "document-id", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +delete", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"}, + {"command": "drive +inspect", "emitted": "document-id", "expect": "node", "via": "override:document-node-id"}, + {"command": "drive +inspect", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"}, + {"command": "drive +publish-get", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +publish-unset", "emitted": "document-url", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +rename", "emitted": "document-id", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +rename", "emitted": "folder-id", "expect": "node", "via": "override:single-folder-node-role"}, + {"command": "drive +star-add", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +star-remove", "emitted": "doc-id", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +stats", "emitted": "document-url", "expect": "node", "via": "override:existing-command-parity"}, + {"command": "drive +upload", "emitted": "file-id", "expect": "node", "via": "override:overwrite-node-id-role"} ] } } From fd26152141d95ce72b93ae33080c4e76fb2cc213 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 16:24:03 +0800 Subject: [PATCH 014/250] docs(release): note Doc and Drive parameter aliases --- .changes/doc-drive-param-aliases.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changes/doc-drive-param-aliases.md diff --git a/.changes/doc-drive-param-aliases.md b/.changes/doc-drive-param-aliases.md new file mode 100644 index 00000000..0bc4bdcb --- /dev/null +++ b/.changes/doc-drive-param-aliases.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Doc and Drive parameter aliases** — normalizes reviewed identifier, pagination, path, version, and role synonyms while blocking ambiguous values before dispatch. From dacf1669353f63c6ef73c3872f18049b8660b8cc Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 16:34:10 +0800 Subject: [PATCH 015/250] fix(drive): require confirmation for folder sync writes --- internal/cli/schema_command_exclusions.go | 4 - internal/helpers/drive.go | 161 +++++++++- internal/helpers/drive_pull.go | 9 +- internal/helpers/drive_pull_test.go | 3 +- internal/helpers/drive_push_test.go | 3 +- .../helpers/drive_status_coverage_test.go | 17 +- internal/helpers/drive_sync.go | 20 +- .../helpers/drive_sync_confirmation_test.go | 290 ++++++++++++++++++ internal/helpers/drive_sync_coverage_test.go | 8 +- internal/helpers/drive_sync_edges_test.go | 6 +- internal/helpers/drive_sync_gaps_test.go | 111 +++++++ internal/helpers/drive_sync_test.go | 9 +- skills/mono/references/products/drive.md | 29 +- .../multi/dingtalk-drive/references/drive.md | 29 +- 14 files changed, 635 insertions(+), 64 deletions(-) create mode 100644 internal/helpers/drive_sync_confirmation_test.go create mode 100644 internal/helpers/drive_sync_gaps_test.go diff --git a/internal/cli/schema_command_exclusions.go b/internal/cli/schema_command_exclusions.go index 3fb2158f..328c1f42 100644 --- a/internal/cli/schema_command_exclusions.go +++ b/internal/cli/schema_command_exclusions.go @@ -99,10 +99,6 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{ "ding message receiver-status", "ding message send-by-message", "ding message send-personal", - "drive pull", - "drive push", - "drive status", - "drive sync", "mail allow-list add", "mail allow-list list", "mail allow-list remove", diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index 7fe1b064..b554a176 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -3311,9 +3311,12 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path --local-folder 对应路径（子目录自动创建），单向、文件级镜像。 已存在的本地文件按 --if-exists 处理： - overwrite 默认，总是下载覆盖（Drive 作为权威源） + skip 默认，安全：本地已存在则保持不动，只新增 smart 推荐增量同步：本地 modified_time 已 ≥ 远端时则跳过下载 - skip 本地已存在则保持不动 + overwrite 总是下载覆盖（Drive 作为权威源） + +该命令会写入本地文件系统，执行前需要用户确认；非交互环境先用 --dry-run +预览，确认后以相同参数追加 --yes 执行。 输出 summary（downloaded/skipped/failed）与逐文件 items。 若有文件下载失败，命令以非零退出码退出（error.type=partial_failure）。`, @@ -3325,7 +3328,7 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path drivePullCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") drivePullCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)") drivePullCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") - drivePullCmd.Flags().String("if-exists", "overwrite", "本地文件已存在时的策略: overwrite|smart|skip (可选)") + drivePullCmd.Flags().String("if-exists", "skip", "本地文件已存在时的策略: skip|smart|overwrite；命令会写本地，执行需确认 (可选)") drivePushCmd := &cobra.Command{ Use: "push", @@ -3339,6 +3342,9 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path smart 增量同步：远端 modified_time 已 ≥ 本地时跳过，否则走覆盖路径 overwrite 覆盖远端同名文件 +该命令会写入钉盘，执行前需要用户确认；非交互环境先用 --dry-run 预览， +确认后以相同参数追加 --yes 执行。 + 输出 summary（uploaded/skipped/failed，uploaded 含新建与覆盖）与逐条 items （含 folder_created）。若有文件失败，命令以非零退出码退出，结构化结果仍在 stdout。`, Example: ` dws drive push --local-folder /abs/path/repo --remote-folder @@ -3349,7 +3355,7 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path drivePushCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") drivePushCmd.Flags().String("remote-folder", "", "钉盘目标文件夹 ID (dentryUuid) (必填)") drivePushCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") - drivePushCmd.Flags().String("if-exists", "skip", "远端文件已存在时的策略: skip|smart|overwrite (可选)") + drivePushCmd.Flags().String("if-exists", "skip", "远端文件已存在时的策略: skip|smart|overwrite；命令会写钉盘，执行需确认 (可选)") driveSyncCmd := &cobra.Command{ Use: "sync", @@ -3362,14 +3368,18 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path unchanged 两侧一致 → 不动 两侧都变更时的 --on-conflict 策略： - remote-wins 默认，拉取远端覆盖本地 + skip 默认，两侧都不动并保留两边内容 + remote-wins 拉取远端覆盖本地 local-wins 上传本地覆盖远端 keep-both 本地文件改名保留，再拉取远端到原路径 ask 交互式逐个询问 exact 模式下远端无可靠 MD5、内容无法核对的文件归入 unknown 并跳过（可改用 --quick）。 文件级同步——只新增/覆盖，不删除任何一侧的多余文件。输出 summary（pulled/pushed/ -skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出，结构化结果仍在 stdout。`, +skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出，结构化结果仍在 stdout。 + +该命令会同时写入本地与钉盘，执行前需要用户确认；非交互环境先用 --dry-run +预览，确认后以相同参数追加 --yes 执行。`, Example: ` dws drive sync --local-folder /abs/path/repo --remote-folder dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict local-wins dws drive sync --local-folder /abs/path/repo --remote-folder --quick --on-conflict keep-both`, @@ -3378,9 +3388,146 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 driveSyncCmd.Flags().String("local-folder", "", "本地文件夹绝对路径 (必填)") driveSyncCmd.Flags().String("remote-folder", "", "钉盘文件夹 ID (dentryUuid) (必填)") driveSyncCmd.Flags().String("space-id", "", "钉盘空间 ID，不传则使用「我的文件」(可选)") - driveSyncCmd.Flags().String("on-conflict", "remote-wins", "两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (可选)") + driveSyncCmd.Flags().String("on-conflict", "skip", "两侧都变更时的策略: skip|remote-wins|local-wins|keep-both|ask；命令会写双端，执行需确认 (可选)") driveSyncCmd.Flags().Bool("quick", false, "快速模式：只比较 modified_time，不计算 MD5 (可选)") + DeclareLeafMetadata(driveStatusCmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", + Confirmation: "not_required", Idempotency: "unknown", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "drive", + Name: "folder_status", + CanonicalPath: "drive.folder_status", + CLIPath: "drive status", + PrimaryCLIPath: "drive status", + }, + Description: "比较本地文件夹与钉盘文件夹的差异，只读不落盘。", + Interface: &contract.InterfaceSpec{ + Mode: "composite", + Availability: "available", + Reason: "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files, walks the local tree, and compares both sides by MD5 or modification time; no single pinned RPC represents the diff.", + }, + Selection: contract.SelectionSpec{ + AgentSummary: "比较本地文件夹与钉盘文件夹的差异，只读不落盘。", + UseWhen: []string{"需要先看清本地与钉盘之间哪些文件新增、变更或一致，再决定拉取还是推送时"}, + AvoidWhen: []string{"只要单个文件的元数据用 drive info；要真正传输文件用 drive pull / push / sync"}, + Examples: []string{ + "dws drive status --local-folder /abs/path/repo --remote-folder ", + "dws drive status --local-folder /abs/path/repo --remote-folder --quick", + }, + }, + Parameters: []contract.ParamDecl{ + {Name: "local-folder", Required: boolPtr(true)}, + {Name: "remote-folder", Required: boolPtr(true)}, + }, + }, + }) + DeclareLeafMetadata(drivePullCmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "write", Risk: "high", + Confirmation: "user_required", Idempotency: "unknown", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "drive", + Name: "folder_pull", + CanonicalPath: "drive.folder_pull", + CLIPath: "drive pull", + PrimaryCLIPath: "drive pull", + }, + Description: "把钉盘文件夹单向镜像到本地；写操作需确认，默认跳过本地既有文件。", + Interface: &contract.InterfaceSpec{ + Mode: "composite", + Availability: "available", + Reason: "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files and then downloads each file through drive/download_file plus an HTTP GET into a temporary file committed by an atomic rename; no single pinned RPC represents the mirror.", + }, + Selection: contract.SelectionSpec{ + AgentSummary: "把钉盘文件夹单向镜像到本地；写操作需确认，默认跳过本地既有文件。", + UseWhen: []string{"需要把整个钉盘文件夹拉到本地目录时"}, + AvoidWhen: []string{"只下载单个文件用 drive download；要把本地推到钉盘用 drive push；要双向对齐用 drive sync"}, + Examples: []string{ + "dws drive pull --local-folder /abs/path/repo --remote-folder ", + "dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart --dry-run", + }, + }, + Parameters: []contract.ParamDecl{ + {Name: "local-folder", Required: boolPtr(true)}, + {Name: "remote-folder", Required: boolPtr(true)}, + }, + }, + }) + DeclareLeafMetadata(drivePushCmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "write", Risk: "high", + Confirmation: "user_required", Idempotency: "unknown", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "drive", + Name: "folder_push", + CanonicalPath: "drive.folder_push", + CLIPath: "drive push", + PrimaryCLIPath: "drive push", + }, + Description: "把本地文件夹单向镜像到钉盘；写操作需确认，默认跳过远端既有文件。", + Interface: &contract.InterfaceSpec{ + Mode: "composite", + Availability: "available", + Reason: "Reviewed composite workflow: the command recursively lists the remote folder through drive/list_files, creates missing folders through drive/create_folder, and uploads each file through drive/get_upload_info plus an HTTP PUT and drive/commit_upload; no single pinned RPC represents the mirror.", + }, + Selection: contract.SelectionSpec{ + AgentSummary: "把本地文件夹单向镜像到钉盘；写操作需确认，默认跳过远端既有文件。", + UseWhen: []string{"需要把整个本地目录推送到钉盘文件夹时"}, + AvoidWhen: []string{"只上传单个文件用 drive upload；要把钉盘拉到本地用 drive pull；要双向对齐用 drive sync"}, + Examples: []string{ + "dws drive push --local-folder /abs/path/repo --remote-folder ", + "dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --dry-run", + }, + }, + Parameters: []contract.ParamDecl{ + {Name: "local-folder", Required: boolPtr(true)}, + {Name: "remote-folder", Required: boolPtr(true)}, + }, + }, + }) + DeclareLeafMetadata(driveSyncCmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "write", Risk: "high", + Confirmation: "user_required", Idempotency: "unknown", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "drive", + Name: "folder_sync", + CanonicalPath: "drive.folder_sync", + CLIPath: "drive sync", + PrimaryCLIPath: "drive sync", + }, + Description: "本地与钉盘文件夹双向同步；写操作需确认，默认跳过双端冲突。", + Interface: &contract.InterfaceSpec{ + Mode: "composite", + Availability: "available", + Reason: "Reviewed composite workflow: the command computes the same diff as drive status and then resolves it in both directions through drive/download_file, drive/create_folder, drive/get_upload_info and drive/commit_upload according to --on-conflict; no single pinned RPC represents the bidirectional sync.", + }, + Selection: contract.SelectionSpec{ + AgentSummary: "本地与钉盘文件夹双向同步；写操作需确认，默认跳过双端冲突。", + UseWhen: []string{"需要让本地目录与钉盘文件夹互相补齐时"}, + AvoidWhen: []string{"只需单方向镜像用 drive pull / push；只想看差异用 drive status"}, + Examples: []string{ + "dws drive sync --local-folder /abs/path/repo --remote-folder ", + "dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict remote-wins --dry-run", + }, + }, + Parameters: []contract.ParamDecl{ + {Name: "local-folder", Required: boolPtr(true)}, + {Name: "remote-folder", Required: boolPtr(true)}, + }, + }, + }) + driveCmd.AddCommand( driveListCmd, driveListSpacesCmd, diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index 3e1d875e..9671cf88 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -29,9 +29,9 @@ import ( // --if-exists 的三种策略。 const ( - ifExistsOverwrite = "overwrite" // 默认：总是下载覆盖（Drive 为权威源） + ifExistsOverwrite = "overwrite" // 总是下载覆盖（Drive 为权威源） ifExistsSmart = "smart" // 推荐增量：本地 mtime 已 ≥ 远端 modified_time 则跳过 - ifExistsSkip = "skip" // 本地已存在则保持不动 + ifExistsSkip = "skip" // 默认：本地已存在则保持不动 ) // pull 动作分类。 @@ -143,7 +143,8 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { ifExists, _ := cmd.Flags().GetString("if-exists") if ifExists == "" { - ifExists = ifExistsOverwrite + // 安全默认：不自动覆盖本地既有文件。 + ifExists = ifExistsSkip } switch ifExists { case ifExistsOverwrite, ifExistsSmart, ifExistsSkip: @@ -171,7 +172,7 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { sort.Strings(relPaths) // 落盘前先按目标文件系统的路径等价规则做一次全局冲突检查：大小写不敏感 FS 上 - // A.txt 与 a.txt（或 NFC/NFD 异写）会落到同一本地文件，默认 overwrite 会顺序覆盖、 + // A.txt 与 a.txt（或 NFC/NFD 异写）会落到同一本地文件；overwrite 会顺序覆盖、 // 却把两项都报 downloaded 而静默丢文件。冲突的条目一律标记 failed、都不写入。 // 探针需要根目录存在，这里按 pull「自动创建目标根」的语义先建好。 if err := os.MkdirAll(absDir, 0o755); err != nil { diff --git a/internal/helpers/drive_pull_test.go b/internal/helpers/drive_pull_test.go index 032eb1d7..83233eca 100644 --- a/internal/helpers/drive_pull_test.go +++ b/internal/helpers/drive_pull_test.go @@ -145,7 +145,8 @@ func TestCrossPlatformCoverageDrivePull_nonexistentLocalRoot(t *testing.T) { root.PersistentFlags().Bool("dry-run", false, "") root.AddCommand(newDriveCommand()) - full := []string{"pull", "--local-folder", absDir, "--remote-folder", "ROOT"} + // pull/push 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 + full := []string{"pull", "--local-folder", absDir, "--remote-folder", "ROOT", "--yes"} os.Args = append([]string{"dws", "drive"}, full...) root.SetArgs(append([]string{"drive"}, full...)) diff --git a/internal/helpers/drive_push_test.go b/internal/helpers/drive_push_test.go index 809c0bdc..984dd582 100644 --- a/internal/helpers/drive_push_test.go +++ b/internal/helpers/drive_push_test.go @@ -194,7 +194,8 @@ func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string root.PersistentFlags().Bool("dry-run", false, "") root.AddCommand(newDriveCommand()) - full := append([]string{"push", "--local-folder", localDir, "--remote-folder", "ROOT"}, args...) + // pull/push 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 + full := append([]string{"push", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...) os.Args = append([]string{"dws", "drive"}, full...) root.SetArgs(append([]string{"drive"}, full...)) diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index 8c6471cb..9c14387d 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -58,9 +58,24 @@ func (m *driveScriptCaller) callsFor(tool string) []driveMCPCall { var errTestList = errors.New("list_files boom") -// runDriveCmd 以给定 caller 执行 `dws drive `，返回命令错误。 +// runDriveCmd 以给定 caller 执行 `dws drive `。 +// +// pull / push / sync 声明了 Safety.Confirmation = user_required，非交互环境下必须带 +// --yes 才能越过统一确认门；这里自动补上，让用例专注被测行为。要断言「未确认即拒绝」 +// 请改用 runDriveCmdWithoutConfirm。 func runDriveCmd(t *testing.T, caller edition.ToolCaller, args ...string) error { t.Helper() + switch { + case len(args) == 0: + case args[0] == "pull", args[0] == "push", args[0] == "sync": + args = append(args, "--yes") + } + return runDriveCmdWithoutConfirm(t, caller, args...) +} + +// runDriveCmdWithoutConfirm 原样执行，不补 --yes，用于验证确认门本身。 +func runDriveCmdWithoutConfirm(t *testing.T, caller edition.ToolCaller, args ...string) error { + t.Helper() prevDeps := deps prevOSArgs := os.Args diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go index e86ad9a6..9019eafb 100644 --- a/internal/helpers/drive_sync.go +++ b/internal/helpers/drive_sync.go @@ -24,7 +24,8 @@ import ( // new_local 仅本地存在 → push（缺失的远端目录按需创建，再上传） // new_remote 仅钉盘存在 → pull（下载到本地对应路径） // modified 两侧都变更 → 按 --on-conflict 解决： -// remote-wins 默认：拉取远端覆盖本地 +// skip 默认：两侧都不动并保留两边内容 +// remote-wins ：拉取远端覆盖本地 // local-wins ：上传本地覆盖远端 // keep-both ：本地改名保留，再拉取远端到原路径 // ask ：交互式逐个询问 @@ -35,12 +36,13 @@ import ( // 退出码退出，结构化 summary + diff + items 仍打印在 stdout 上。 // ────────────────────────────────────────────────────────── -// --on-conflict 的四种冲突解决策略。 +// --on-conflict 的五种冲突解决策略。 const ( syncConflictLocalWins = "local-wins" // 上传本地覆盖远端 - syncConflictRemoteWins = "remote-wins" // 默认：拉取远端覆盖本地 + syncConflictRemoteWins = "remote-wins" // 拉取远端覆盖本地 syncConflictKeepBoth = "keep-both" // 本地改名保留，再拉取远端到原路径 syncConflictAsk = "ask" // 交互式逐个询问 + syncConflictSkip = "skip" // 默认：两侧都变更时什么都不做，两边内容都保留 ) // sync 动作分类（direction 标注每条记录属于哪个方向）。 @@ -112,12 +114,13 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { onConflict, _ := cmd.Flags().GetString("on-conflict") if onConflict == "" { - onConflict = syncConflictRemoteWins + // 安全默认：两侧都变更时不擅自覆盖任何一侧。 + onConflict = syncConflictSkip } switch onConflict { - case syncConflictLocalWins, syncConflictRemoteWins, syncConflictKeepBoth, syncConflictAsk: + case syncConflictSkip, syncConflictLocalWins, syncConflictRemoteWins, syncConflictKeepBoth, syncConflictAsk: default: - return fmt.Errorf("--on-conflict 取值非法: %s（可选 local-wins|remote-wins|keep-both|ask）", onConflict) + return fmt.Errorf("--on-conflict 取值非法: %s（可选 skip|local-wins|remote-wins|keep-both|ask）", onConflict) } quick, _ := cmd.Flags().GetBool("quick") @@ -221,11 +224,14 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { resolutions := make(map[string]string, len(modified)) for _, rel := range modified { strategy := onConflict - if strategy == syncConflictAsk { + switch strategy { + case syncConflictAsk: strategy, err = driveSyncAskConflict(rel) if err != nil { return err } + case syncConflictSkip: + strategy = "" // 与 ask 选择「跳过」同一条落地路径 } resolutions[rel] = strategy } diff --git a/internal/helpers/drive_sync_confirmation_test.go b/internal/helpers/drive_sync_confirmation_test.go new file mode 100644 index 00000000..25db77d4 --- /dev/null +++ b/internal/helpers/drive_sync_confirmation_test.go @@ -0,0 +1,290 @@ +package helpers + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" +) + +// pull / push / sync 声明 Safety.Confirmation = user_required。本文件断言两件事： +// 1. 未确认（无 --yes、非 dry-run）时命令必须在任何写操作之前拒绝执行； +// 2. 明确确认（--yes）后才发出精确的工具调用并落盘。 +// status 是只读叶子（not_required），不受确认门约束。 + +// ────────────────────────────────────────────────────────── +// 1. 未确认即拒绝，且一个写操作都不发生 +// ────────────────────────────────────────────────────────── + +func TestCrossPlatformCoverageDriveSyncFamily_refusesWithoutConfirmation(t *testing.T) { + cases := []struct { + name string + args []string + setup func(t *testing.T, dir string) + listJSON string + }{ + { + name: "pull", + args: []string{"pull"}, + // 远端有文件、本地为空：即便是纯新增也必须先确认。 + listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`, + }, + { + name: "push", + args: []string{"push"}, + setup: func(t *testing.T, dir string) { mustWrite(t, filepath.Join(dir, "a.txt"), "local") }, + listJSON: `{"result":{"items":[],"nextToken":""}}`, + }, + { + name: "sync", + args: []string{"sync", "--quick", "--on-conflict", "remote-wins"}, + setup: func(t *testing.T, dir string) { mustWrite(t, filepath.Join(dir, "a.txt"), "local") }, + listJSON: `{"result":{"items":[{"name":"b.txt","type":"file","fileId":"B","modifyTime":2}],"nextToken":""}}`, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + dir := t.TempDir() + if tc.setup != nil { + tc.setup(t, dir) + } + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + switch tool { + case "list_files": + if nth > 0 { + return `{"result":{"items":[],"nextToken":""}}`, nil + } + return tc.listJSON, nil + case "download_file": + return `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}`, nil + case "get_upload_info": + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + } + return `{"result":{"fileId":"NEW"},"success":true}`, nil + }} + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + t.Error("no download may happen before confirmation") + return os.WriteFile(dest, []byte("leaked"), 0o644) + }) + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + t.Error("no upload may happen before confirmation") + return nil + }) + t.Cleanup(func() { + SetHTTPGetFile(nil) + SetHTTPPutFile(nil) + }) + + args := append(append([]string{}, tc.args...), "--local-folder", dir, "--remote-folder", "ROOT") + err := runDriveCmdWithoutConfirm(t, caller, args...) + if err == nil { + t.Fatal("expected the command to refuse without --yes") + } + if !strings.Contains(err.Error(), "--yes") { + t.Errorf("error must tell the user to confirm with --yes, got %q", err.Error()) + } + // 拒绝必须发生在任何写工具调用之前。 + for _, tool := range []string{"download_file", "get_upload_info", "create_folder", "ln"} { + if got := caller.callsFor(tool); len(got) != 0 { + t.Errorf("%s must not be called before confirmation, got %v", tool, got) + } + } + // 本地目录不得新增任何文件。 + entries, _ := os.ReadDir(dir) + for _, e := range entries { + if e.Name() == "b.txt" || e.Name() == "a.txt" && tc.name == "pull" { + t.Errorf("%s must not be materialized before confirmation", e.Name()) + } + } + }) + } +} + +// --dry-run 无需 --yes 也能预览：这是让用户看清将发生什么的必要出口，且不写任何东西。 +func TestCrossPlatformCoverageDriveSyncFamily_dryRunNeedsNoConfirmation(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "l") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}],"nextToken":""}}`, + }) + caller.dryRun = true + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("dry-run must not download") + return nil + }) + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + t.Error("dry-run must not upload") + return nil + }) + t.Cleanup(func() { + SetHTTPGetFile(nil) + SetHTTPPutFile(nil) + }) + + if err := runDriveCmdWithoutConfirm(t, caller, "sync", + "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("dry-run must not require confirmation: %v", err) + } + if _, err := os.Stat(filepath.Join(dir, "remote.txt")); !os.IsNotExist(err) { + t.Error("dry-run must not write remote files locally") + } +} + +// ────────────────────────────────────────────────────────── +// 2. 明确确认后才发出精确的工具调用 +// ────────────────────────────────────────────────────────── + +// sync --on-conflict remote-wins --yes：确认后只下载指定远端文件，且不上传。 +func TestCrossPlatformCoverageDriveSync_confirmedRemoteWinsIssuesExactCalls(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-version") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote-version") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmdWithoutConfirm(t, caller, "sync", "--local-folder", dir, + "--remote-folder", "ROOT", "--quick", "--on-conflict", "remote-wins", "--yes"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + dl := caller.callsFor("download_file") + if len(dl) != 1 || dl[0].args["fileId"] != "F" { + t.Fatalf("expected exactly one download_file(fileId=F), got %v", dl) + } + if up := caller.callsFor("get_upload_info"); len(up) != 0 { + t.Errorf("remote-wins must not upload, got %v", up) + } + if b, _ := os.ReadFile(p); string(b) != "remote-version" { + t.Errorf("remote-wins must replace the local content, got %q", string(b)) + } +} + +// pull --if-exists overwrite --yes：确认后才 download_file(fileId=A) 并覆盖本地内容。 +func TestCrossPlatformCoverageDrivePull_confirmedOverwriteIssuesExactCalls(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "a.txt") + mustWrite(t, p, "local-old") + + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`) + SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("remote-new"), 0o644) + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmdWithoutConfirm(t, caller, "pull", "--local-folder", dir, + "--remote-folder", "ROOT", "--if-exists", "overwrite", "--yes"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + dl := caller.callsFor("download_file") + if len(dl) != 1 || dl[0].args["fileId"] != "A" { + t.Fatalf("expected exactly one download_file(fileId=A), got %v", dl) + } + if b, _ := os.ReadFile(p); string(b) != "remote-new" { + t.Errorf("confirmed overwrite must replace the local file, got %q", string(b)) + } +} + +// push --if-exists overwrite --yes：确认后原地覆盖，必须带 overwriteFileId 且不带 parentId。 +func TestCrossPlatformCoverageDrivePush_confirmedOverwriteIssuesExactCalls(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}],"nextToken":""}}`, + }) + if err := runDriveCmdWithoutConfirm(t, caller, "push", "--local-folder", dir, + "--remote-folder", "ROOT", "--if-exists", "overwrite", "--yes"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + up := caller.callsFor("get_upload_info") + if len(up) != 1 || up[0].args["overwriteFileId"] != "A" { + t.Fatalf("expected get_upload_info(overwriteFileId=A), got %v", up) + } + if _, has := up[0].args["parentId"]; has { + t.Error("in-place overwrite must not carry parentId") + } +} + +// sync --on-conflict local-wins --yes：确认后覆盖上传远端，且不下载。 +func TestCrossPlatformCoverageDriveSync_confirmedLocalWinsIssuesExactCalls(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-version") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "unused") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmdWithoutConfirm(t, caller, "sync", "--local-folder", dir, + "--remote-folder", "ROOT", "--quick", "--on-conflict", "local-wins", "--yes"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + up := caller.callsFor("get_upload_info") + if len(up) != 1 || up[0].args["overwriteFileId"] != "F" { + t.Fatalf("expected get_upload_info(overwriteFileId=F), got %v", up) + } + if dl := caller.callsFor("download_file"); len(dl) != 0 { + t.Errorf("local-wins must not download, got %v", dl) + } + if b, _ := os.ReadFile(p); string(b) != "local-version" { + t.Errorf("local-wins must keep the local content, got %q", string(b)) + } +} + +// ────────────────────────────────────────────────────────── +// 3. 安全默认值本身 +// ────────────────────────────────────────────────────────── + +// sync 默认 --on-conflict=skip：两侧都变更时两边内容都保留，且不发出任何传输调用。 +func TestCrossPlatformCoverageDriveSync_defaultSkipsConflictsEntirely(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "f.txt") + mustWrite(t, p, "local-version") + local := readFileMTimeMillis(t, p) + withSyncTransport(t, "remote-version") + + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F","modifyTime":` + + differentMillis(local) + `}],"nextToken":""}}`, + }) + if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got := len(caller.callsFor("download_file")) + len(caller.callsFor("get_upload_info")); got != 0 { + t.Errorf("default skip must not transfer anything, got %d calls", got) + } + if b, _ := os.ReadFile(p); string(b) != "local-version" { + t.Errorf("default skip must keep the local content, got %q", string(b)) + } +} + +// pull 默认 --if-exists=skip：本地已存在的文件不被覆盖。 +func TestCrossPlatformCoverageDrivePull_defaultSkipsExistingLocalFiles(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "a.txt") + mustWrite(t, p, "local-old") + + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`) + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("default skip must not download over an existing local file") + return nil + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + if err := runDriveCmd(t, caller, "pull", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if b, _ := os.ReadFile(p); string(b) != "local-old" { + t.Errorf("default skip must keep the local file, got %q", string(b)) + } +} diff --git a/internal/helpers/drive_sync_coverage_test.go b/internal/helpers/drive_sync_coverage_test.go index 15d04b30..bdf901da 100644 --- a/internal/helpers/drive_sync_coverage_test.go +++ b/internal/helpers/drive_sync_coverage_test.go @@ -52,8 +52,8 @@ func withSyncTransport(t *testing.T, body string) { // --on-conflict 取值处理 // ────────────────────────────────────────────────────────── -// 显式传空 --on-conflict 时回落默认 remote-wins（而非报非法取值）。 -func TestCrossPlatformCoverageDriveSync_emptyOnConflictDefaultsToRemoteWins(t *testing.T) { +// 显式传空 --on-conflict 时回落安全默认 skip：两侧都变更时两边内容都不动。 +func TestCrossPlatformCoverageDriveSync_emptyOnConflictDefaultsToSkip(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-old") @@ -68,8 +68,8 @@ func TestCrossPlatformCoverageDriveSync_emptyOnConflictDefaultsToRemoteWins(t *t "--quick", "--on-conflict", ""); err != nil { t.Fatalf("unexpected error: %v", err) } - if b, _ := os.ReadFile(p); string(b) != "remote-new" { - t.Errorf("empty --on-conflict must behave as remote-wins, got %q", string(b)) + if b, _ := os.ReadFile(p); string(b) != "local-old" { + t.Errorf("empty --on-conflict must default to skip and keep the local file, got %q", string(b)) } } diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go index 84843247..7e57e703 100644 --- a/internal/helpers/drive_sync_edges_test.go +++ b/internal/helpers/drive_sync_edges_test.go @@ -47,7 +47,7 @@ func mustSetFlags(t *testing.T, cmd *cobra.Command, kv map[string]string) { // --if-exists 显式空值回落默认 // ────────────────────────────────────────────────────────── -func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToOverwrite(t *testing.T) { +func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToSkip(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "a.txt") mustWrite(t, p, "local-old") @@ -60,8 +60,8 @@ func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToOverwrite(t *test if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", ""); err != nil { t.Fatalf("unexpected error: %v", err) } - if b, _ := os.ReadFile(p); string(b) != "remote-new" { - t.Errorf("empty --if-exists must behave as overwrite, got %q", string(b)) + if b, _ := os.ReadFile(p); string(b) != "local-old" { + t.Errorf("empty --if-exists must default to skip and keep the local file, got %q", string(b)) } } diff --git a/internal/helpers/drive_sync_gaps_test.go b/internal/helpers/drive_sync_gaps_test.go new file mode 100644 index 00000000..5165c757 --- /dev/null +++ b/internal/helpers/drive_sync_gaps_test.go @@ -0,0 +1,111 @@ +package helpers + +import ( + "context" + "io" + "os" + "path/filepath" + "strings" + "testing" +) + +// 本文件补齐几条在默认策略改为 skip 后失去覆盖的边界分支。 + +// pull 自动创建目标根失败（--local-folder 指向一个常规文件）→ 明确报错，不落盘。 +func TestCrossPlatformCoverageDrivePull_localRootIsFileFails(t *testing.T) { + dir := t.TempDir() + asFile := filepath.Join(dir, "not-a-dir") + mustWrite(t, asFile, "x") + + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) + err := runDriveCmd(t, caller, "pull", "--local-folder", asFile, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "创建本地目录失败") { + t.Fatalf("expected local root creation failure, got %v", err) + } +} + +// push 遍历远端时 list_files 在**子目录**层失败 → 错误如实上抛（walkRemoteForPush 的递归错误分支）。 +func TestCrossPlatformCoverageDrivePush_remoteSubdirListFailurePropagates(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "x") + withNoopPut(t) + + caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + if tool != "list_files" { + return `{"result":{},"success":true}`, nil + } + switch args["parentId"] { + case "ROOT": + return `{"result":{"items":[{"name":"sub","type":"folder","fileId":"SUB"}],"nextToken":""}}`, nil + default: + return "", errTestList // 递归进入子目录后失败 + } + }} + if err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { + t.Fatal("expected the nested list_files failure to propagate") + } +} + +// push 的远端索引跳过非 file 类型（在线文档/快捷方式），不把它们当成可覆盖的既有文件。 +func TestCrossPlatformCoverageDrivePush_remoteNonFileEntriesAreSkipped(t *testing.T) { + caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + if tool != "list_files" { + return `{"result":{},"success":true}`, nil + } + if args["parentId"] == "ROOT" { + return `{"result":{"items":[` + + `{"name":"online.adoc","type":"document","fileId":"D1"},` + + `{"name":"link","type":"shortcut","fileId":"S1"},` + + `{"name":"real.txt","type":"file","fileId":"F1"}` + + `],"nextToken":""}}`, nil + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + files, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if _, ok := files["real.txt"]; !ok { + t.Error("regular file must be indexed") + } + for _, skipped := range []string{"online.adoc", "link"} { + if _, ok := files[skipped]; ok { + t.Errorf("non-file entry %q must not be indexed", skipped) + } + } +} + +// list_files 返回体没有 result 字段 → 视为空列表，而不是解析错误。 +func TestCrossPlatformCoverageParseDriveList_missingResultIsEmpty(t *testing.T) { + items, token, err := parseDriveList(`{"success":true}`) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(items) != 0 || token != "" { + t.Errorf("parseDriveList = (%v, %q), want empty list", items, token) + } +} + +// push 遍历远端时返回体无法解析 → 解析错误如实上抛（与调用失败是不同分支）。 +func TestCrossPlatformCoverageDrivePush_remoteListParseFailurePropagates(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "x") + withNoopPut(t) + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "list_files" { + return `{"result":{},"success":true}`, nil + } + return `{"result":"not-a-list"}`, nil // 既不是 {items:[]} 也不是数组 + }} + err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "list_files") { + t.Fatalf("expected a list_files parse error, got %v", err) + } +} diff --git a/internal/helpers/drive_sync_test.go b/internal/helpers/drive_sync_test.go index 6dab3f7b..e2221dac 100644 --- a/internal/helpers/drive_sync_test.go +++ b/internal/helpers/drive_sync_test.go @@ -90,7 +90,8 @@ func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn fu root.PersistentFlags().Bool("dry-run", false, "") root.AddCommand(newDriveCommand()) - full := append([]string{"sync", "--local-folder", localDir, "--remote-folder", "ROOT"}, args...) + // sync 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 + full := append([]string{"sync", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...) os.Args = append([]string{"dws", "drive"}, full...) root.SetArgs(append([]string{"drive"}, full...)) @@ -139,7 +140,7 @@ func TestCrossPlatformCoverageDriveSync_bidirectional(t *testing.T) { } } -// modified + remote-wins：quick 模式下两侧 mtime 不同判为 modified，默认拉取远端覆盖本地。 +// modified + remote-wins：quick 模式下两侧 mtime 不同判为 modified，并显式拉取远端覆盖本地。 func TestCrossPlatformCoverageDriveSync_modifiedRemoteWins(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") @@ -151,7 +152,7 @@ func TestCrossPlatformCoverageDriveSync_modifiedRemoteWins(t *testing.T) { listJSON: `{"result":{"items":[{"name":"f.txt","type":"file","fileId":"F_FID","modifyTime":` + differentMillis(local) + `}],"nextToken":""}}`, } - if err := runDriveSyncTest(t, caller, dir, "--quick"); err != nil { + if err := runDriveSyncTest(t, caller, dir, "--quick", "--on-conflict", "remote-wins"); err != nil { t.Fatalf("unexpected error: %v", err) } @@ -233,7 +234,7 @@ func TestCrossPlatformCoverageDriveSync_pullFailureKeepsLocal(t *testing.T) { failGet := func(context.Context, string, map[string]string, string) error { return errTestDownload } - err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick") // 默认 remote-wins + err := runDriveSyncTestWithGet(t, caller, failGet, dir, "--quick", "--on-conflict", "remote-wins") if err == nil { t.Fatal("下载失败时应以非零退出码退出") } diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 188e0936..bb4c56cd 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -395,7 +395,7 @@ Flags: ### 把钉盘文件夹拉取（镜像）到本地 -只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。 +只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。** ``` Usage: @@ -408,16 +408,16 @@ Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 本地文件已存在时的策略: overwrite|smart|skip (默认 overwrite) + --if-exists string 本地文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写本地，执行需确认) ``` `--if-exists` 策略： | 值 | 行为 | |----|------| -| `overwrite`（默认） | 总是下载覆盖（Drive 作为权威源） | +| `skip`（默认） | 本地已存在则保持不动，只新增 | | `smart`（推荐增量同步） | 本地 `modified_time` 已 ≥ 远端 `modified_time` 则跳过；时间戳缺失/非法时退回安全路径继续下载 | -| `skip` | 本地已存在则保持不动 | +| `overwrite` | 总是下载覆盖（Drive 作为权威源） | 输出 schema： @@ -441,7 +441,7 @@ Flags: ### 把本地文件夹推送（镜像）到钉盘 -只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**只新增/覆盖，不删除远端多余文件。** +只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。只新增/覆盖，不删除远端多余文件。** ``` Usage: @@ -449,15 +449,15 @@ Usage: Example: dws drive push --local-folder /abs/path/repo --remote-folder dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite --yes Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip) + --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写钉盘，执行需确认) ``` -`--if-exists` 策略（注意默认与 pull 相反，push 默认 `skip` 更安全）： +`--if-exists` 策略（与 pull 一样默认 `skip`，避免未显式选择时覆盖既有文件）： | 值 | 行为 | |----|------| @@ -489,7 +489,7 @@ Flags: ### 本地文件夹与钉盘文件夹双向同步 -读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** +读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。**这是写操作，非交互环境下必须显式加 `--yes`；先用 `--dry-run` 看清将发生什么。**先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** ``` Usage: @@ -503,7 +503,7 @@ Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --on-conflict string 两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (默认 remote-wins) + --on-conflict string 两侧都变更时的策略: skip|remote-wins|local-wins|keep-both|ask (默认 skip；命令写双端，执行需确认) --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) ``` @@ -511,8 +511,9 @@ Flags: | 值 | 行为 | |----|------| -| `remote-wins`（默认） | 下载远端覆盖本地 | -| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId） | +| `skip`（默认） | 两侧都不动，两边内容都保留，计入 `skipped` | +| `remote-wins` | 下载远端覆盖本地（需 `--yes`） | +| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId；需 `--yes`） | | `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | | `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | @@ -569,7 +570,7 @@ Flags: 用户说"比较本地和云盘/看哪些文件变了/同步差异/diff" → `status` 用户说"把钉盘文件夹拉到本地/下载整个文件夹/镜像/同步到本地/pull" → `pull` 用户说"把本地文件夹传到钉盘/推送整个文件夹/上传目录/同步到云端/push" → `push` -用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（两侧都变更时用 `--on-conflict` 决定谁覆盖谁） +用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（默认两侧都变更时跳过；要覆盖须显式给 `--on-conflict` 并加 `--yes`） 关键区分: drive(文件管理) vs doc(文档内容读写) vs wiki(空间管理) @@ -632,7 +633,7 @@ dws drive pull --local-folder /abs/path/repo --remote-folder --if-e dws drive push --local-folder /abs/path/repo --remote-folder --format json dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --format json -# 12. 本地与钉盘双向同步（两侧都变更时用 --on-conflict 消解，默认 remote-wins） +# 12. 本地与钉盘双向同步（默认 --on-conflict=skip 两侧都不动；要覆盖须显式选策略并加 --yes） dws drive sync --local-folder /abs/path/repo --remote-folder --format json dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both --format json ``` diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 0b35d622..87d99ed2 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -380,7 +380,7 @@ Flags: ### 把钉盘文件夹拉取（镜像）到本地 -只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。 +只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。** ``` Usage: @@ -393,16 +393,16 @@ Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 本地文件已存在时的策略: overwrite|smart|skip (默认 overwrite) + --if-exists string 本地文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写本地，执行需确认) ``` `--if-exists` 策略： | 值 | 行为 | |----|------| -| `overwrite`（默认） | 总是下载覆盖（Drive 作为权威源） | +| `skip`（默认） | 本地已存在则保持不动，只新增 | | `smart`（推荐增量同步） | 本地 `modified_time` 已 ≥ 远端 `modified_time` 则跳过；时间戳缺失/非法时退回安全路径继续下载 | -| `skip` | 本地已存在则保持不动 | +| `overwrite` | 总是下载覆盖（Drive 作为权威源） | 输出 schema： @@ -426,7 +426,7 @@ Flags: ### 把本地文件夹推送（镜像）到钉盘 -只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**只新增/覆盖，不删除远端多余文件。** +只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。只新增/覆盖，不删除远端多余文件。** ``` Usage: @@ -434,15 +434,15 @@ Usage: Example: dws drive push --local-folder /abs/path/repo --remote-folder dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite --yes Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip) + --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写钉盘，执行需确认) ``` -`--if-exists` 策略（注意默认与 pull 相反，push 默认 `skip` 更安全）： +`--if-exists` 策略（与 pull 一样默认 `skip`，避免未显式选择时覆盖既有文件）： | 值 | 行为 | |----|------| @@ -474,7 +474,7 @@ Flags: ### 本地文件夹与钉盘文件夹双向同步 -读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** +读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。**这是写操作，非交互环境下必须显式加 `--yes`；先用 `--dry-run` 看清将发生什么。**先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** ``` Usage: @@ -488,7 +488,7 @@ Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --on-conflict string 两侧都变更时的策略: remote-wins|local-wins|keep-both|ask (默认 remote-wins) + --on-conflict string 两侧都变更时的策略: skip|remote-wins|local-wins|keep-both|ask (默认 skip；命令写双端，执行需确认) --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) ``` @@ -496,8 +496,9 @@ Flags: | 值 | 行为 | |----|------| -| `remote-wins`（默认） | 下载远端覆盖本地 | -| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId） | +| `skip`（默认） | 两侧都不动，两边内容都保留，计入 `skipped` | +| `remote-wins` | 下载远端覆盖本地（需 `--yes`） | +| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId；需 `--yes`） | | `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | | `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | @@ -561,7 +562,7 @@ Flags: 用户说"比较本地和云盘/看哪些文件变了/同步差异/diff" → `status` 用户说"把钉盘文件夹拉到本地/下载整个文件夹/镜像/同步到本地/pull" → `pull` 用户说"把本地文件夹传到钉盘/推送整个文件夹/上传目录/同步到云端/push" → `push` -用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（两侧都变更时用 `--on-conflict` 决定谁覆盖谁） +用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（默认两侧都变更时跳过；要覆盖须显式给 `--on-conflict` 并加 `--yes`） 用户说"查任务状态/导出好了没/任务进度/导入状态" → 文档导出用 `dws doc export get --job-id `，导入用 `dws doc import get --task-id ` 关键区分: drive(文件管理) vs doc(文档内容读写) vs wiki(空间管理) @@ -631,7 +632,7 @@ dws drive pull --local-folder /abs/path/repo --remote-folder --if-e dws drive push --local-folder /abs/path/repo --remote-folder --format json dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --format json -# 13. 本地与钉盘双向同步（两侧都变更时用 --on-conflict 消解，默认 remote-wins） +# 13. 本地与钉盘双向同步（默认 --on-conflict=skip 两侧都不动；要覆盖须显式选策略并加 --yes） dws drive sync --local-folder /abs/path/repo --remote-folder --format json dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both --format json ``` From 9c14d9a6e15d5b1a0e090f9fbebef24fbf40f145 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 16:42:27 +0800 Subject: [PATCH 016/250] fix(chat): repair message time defaults checks --- internal/helpers/chat.go | 1 - internal/helpers/chat_message_pagination_test.go | 8 +++++--- internal/helpers/im_read_result_contract_test.go | 1 + 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 3cc7a516..83bc0567 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -2700,7 +2700,6 @@ func newChatCommand() *cobra.Command { AvoidWhen: []string{"跨全部会话按时间查询时使用 chat message list-all"}, Examples: []string{ "dws chat message list --group --limit 50", - "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50", "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", }, }, diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 2b6c28ab..2706b621 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -199,10 +199,12 @@ func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) { } startMs := numericArgAsInt64(t, got.args["startTime"]) endMs := numericArgAsInt64(t, got.args["endTime"]) - if endMs < before.UnixMilli() || endMs > after.Add(time.Second).UnixMilli() { - t.Fatalf("endTime = %d, want between %d and %d", endMs, before.UnixMilli(), after.Add(time.Second).UnixMilli()) + wantEndMin := before.Truncate(time.Second).UnixMilli() + wantEndMax := after.Add(time.Second).UnixMilli() + if endMs < wantEndMin || endMs > wantEndMax { + t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax) } - wantStartMin := before.Add(-tt.wantLookback).UnixMilli() + wantStartMin := before.Add(-tt.wantLookback).Truncate(time.Second).UnixMilli() wantStartMax := after.Add(-tt.wantLookback).Add(time.Second).UnixMilli() if startMs < wantStartMin || startMs > wantStartMax { t.Fatalf("startTime = %d, want between %d and %d", startMs, wantStartMin, wantStartMax) diff --git a/internal/helpers/im_read_result_contract_test.go b/internal/helpers/im_read_result_contract_test.go index d2df5bc2..0d983925 100644 --- a/internal/helpers/im_read_result_contract_test.go +++ b/internal/helpers/im_read_result_contract_test.go @@ -21,6 +21,7 @@ import ( "io" "os" "reflect" + "strings" "testing" "time" From 07c5d25d5599152bc6ed36fba37cd9ab60ea0fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 17:14:23 +0800 Subject: [PATCH 017/250] fix(cli): cover doc search time aliases --- internal/app/param_alias_payload_equivalence_test.go | 3 +++ internal/cli/param_aliases_generated.go | 6 ++++++ internal/cli/param_concepts.json | 6 ++++-- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 064bc154..a4fe2e16 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -196,6 +196,7 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ }, "doc +search": { "created-from": {"doc", "+search", "--query", "fixture", "--created-from", "1"}, + "created-to": {"doc", "+search", "--query", "fixture", "--created-to", "2"}, "creator-uids": {"doc", "+search", "--query", "fixture", "--creator-uids", "user-1,user-2"}, }, "drive list": { @@ -392,6 +393,8 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("doc +fetch", "start-block"): true, // section boundary role remains exact paramAliasPayloadCaseKey("doc +history-revert", "version-number"): true, // destructive history version alias keeps confirmation paramAliasPayloadCaseKey("doc +inspect", "include-versions"): true, // boolean section alias preserves value + paramAliasPayloadCaseKey("doc +search", "create-time-start"): true, // observed lower-bound spelling preserves milliseconds + paramAliasPayloadCaseKey("doc +search", "create-time-end"): true, // observed upper-bound spelling preserves milliseconds paramAliasPayloadCaseKey("doc +template-list", "next-token"): true, // Doc cursor alias on a read shortcut paramAliasPayloadCaseKey("doc +update", "mode"): true, // write operation selector alias paramAliasPayloadCaseKey("doc +update", "revision"): true, // optimistic edit revision alias diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index 58ffe989..c7101d5d 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -2427,7 +2427,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +search", Aliases: map[string]string{ + "create-time-end": "created-to", "create-time-from": "created-from", + "create-time-start": "created-from", "create-time-to": "created-to", "created-after": "created-from", "created-before": "created-to", @@ -3212,7 +3214,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "drive +search", Aliases: map[string]string{ + "create-time-end": "created-to", "create-time-from": "created-from", + "create-time-start": "created-from", "create-time-to": "created-to", "created-after": "created-from", "created-before": "created-to", @@ -3781,7 +3785,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "drive search", Aliases: map[string]string{ + "create-time-end": "created-to", "create-time-from": "created-from", + "create-time-start": "created-from", "create-time-to": "created-to", "created-after": "created-from", "created-before": "created-to", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index edc6a396..6a9433f1 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -47,8 +47,8 @@ "drive_file_size_bytes": {"denotes": "file size in bytes passed unchanged", "canonical_hint": "file-size", "members": ["file-size", "file-size-bytes", "size-bytes", "content-length"], "excludes": ["part-size", "page-size", "limit", "size"], "commands": ["drive commit", "drive upload-info"], "risk": "yellow"}, "drive_sort_direction": {"denotes": "Drive result sort direction with unchanged asc/desc enum", "canonical_hint": "order", "members": ["order", "sort", "sort-direction", "order-direction"], "excludes": ["order-by", "sort-by", "order-field"], "commands": ["drive +list", "drive list", "drive star list"], "risk": "green"}, "workspace_id": {"denotes": "single knowledge-base or document-space workspace ID/URL passed unchanged; never a numeric DingDrive storage space ID", "canonical_hint": "workspace", "members": ["workspace", "workspace-id", "knowledge-base-id", "wiki-workspace-id"], "excludes": ["space", "space-id", "drive-space-id", "storage-space-id", "dingdrive-space-id", "folder", "folder-id", "node", "node-id", "dentry-id"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive +copy", "drive +create-shortcut", "drive +move", "drive copy", "drive list", "drive move", "drive permission add", "drive permission list", "drive permission remove", "drive permission transfer-owner", "drive permission update", "drive shortcut", "drive upload"], "risk": "yellow"}, - "created_time_start": {"denotes": "Doc/Drive search created-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "created-from", "members": ["created-from", "created-after", "create-time-from", "created-time-start"], "excludes": ["created-to", "modified-from", "modified-to", "start", "from"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, - "created_time_end": {"denotes": "Doc/Drive search created-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "created-to", "members": ["created-to", "created-before", "create-time-to", "created-time-end"], "excludes": ["created-from", "modified-from", "modified-to", "end", "to"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, + "created_time_start": {"denotes": "Doc/Drive search created-time lower bound in unchanged millisecond timestamp unit", "canonical_hint": "created-from", "members": ["created-from", "created-after", "create-time-from", "created-time-start", "create-time-start"], "excludes": ["created-to", "modified-from", "modified-to", "start", "from"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, + "created_time_end": {"denotes": "Doc/Drive search created-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "created-to", "members": ["created-to", "created-before", "create-time-to", "created-time-end", "create-time-end"], "excludes": ["created-from", "modified-from", "modified-to", "end", "to"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, "document_permission_role": {"denotes": "direct document-space permission role on grant/apply/update, passed unchanged", "canonical_hint": "role", "members": ["role", "permission-role", "access-role", "member-role"], "excludes": ["filter-role", "reserve-role", "permission", "public-permission"], "commands": ["doc +access-change", "doc +access-grant", "doc +grant-and-share", "drive permission add", "drive permission apply", "drive permission update"], "risk": "yellow"}, "creator_user_ids": {"denotes": "creator userId list used to filter Doc/Drive search results, passed unchanged", "canonical_hint": "creator-uids", "members": ["creator-uids", "creator-user-ids", "creator-ids", "created-by-user-ids"], "excludes": ["user", "user-id", "user-ids", "users", "owner-id", "modifier-uids"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, "local_output_path": {"denotes": "local destination file or directory path for a download/export result, passed unchanged", "canonical_hint": "output", "members": ["output", "output-path", "destination-path", "save-path"], "excludes": ["file", "file-path", "folder", "folder-id", "content-file"], "commands": ["doc +export", "doc +export-get", "doc +media-download", "doc +resource-download", "doc read", "drive +download", "drive +version-download", "drive download", "drive download-version"], "risk": "green"} @@ -519,6 +519,8 @@ {"command": "drive permission list", "emitted": "role", "expect": "did-you-mean:blocked", "via": "guard:permission-role-vs-filter-role"}, {"command": "drive upload", "emitted": "source-file", "expect": "file", "via": "override:scoped-local-file"}, {"command": "doc +search", "emitted": "created-after", "expect": "created-from", "via": "concept:created_time_start"}, + {"command": "doc +search", "emitted": "create-time-start", "expect": "created-from", "via": "concept:created_time_start", "occ": 1}, + {"command": "doc +search", "emitted": "create-time-end", "expect": "created-to", "via": "concept:created_time_end", "occ": 1}, {"command": "doc +search", "emitted": "creator-user-ids", "expect": "creator-uids", "via": "concept:creator_user_ids"}, {"command": "doc +access-grant", "emitted": "permission-role", "expect": "role", "via": "concept:document_permission_role"}, {"command": "doc +export", "emitted": "output-path", "expect": "output", "via": "concept:local_output_path"}, From 5282a55a546cf62852e17064f5fd7451775fdef0 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 17:24:54 +0800 Subject: [PATCH 018/250] test(drive): make MD5 failure coverage portable --- internal/helpers/drive_status.go | 5 +++-- internal/helpers/drive_sync_coverage_test.go | 19 +++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index eaeb360a..a1a48c88 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -356,8 +356,9 @@ func verifyNoSymlinkEscape(absDir, target string) error { } // md5File 计算文件内容的 MD5，并按 base64 编码返回（与钉盘 list_files 返回的 -// md5 字段编码一致，便于直接字符串比较）。 -func md5File(path string) (string, error) { +// md5 字段编码一致，便于直接字符串比较）。变量形式只用于测试确定性注入读取失败； +// 测试必须通过 testseam.Swap 替换并自动恢复。 +var md5File = func(path string) (string, error) { f, err := os.Open(path) if err != nil { return "", err diff --git a/internal/helpers/drive_sync_coverage_test.go b/internal/helpers/drive_sync_coverage_test.go index bdf901da..1ab48574 100644 --- a/internal/helpers/drive_sync_coverage_test.go +++ b/internal/helpers/drive_sync_coverage_test.go @@ -130,24 +130,23 @@ func TestCrossPlatformCoverageDriveSync_unknownIsSkipped(t *testing.T) { } } -// exact 模式下本地不可读 → judgeFileMatch 的 MD5 失败要中止整个 sync。 +// exact 模式下本地 MD5 计算失败 → 整个 sync 中止。错误通过 seam 确定性注入， +// 避免依赖 chmod：Windows 不遵循 POSIX 的 000 权限语义。 func TestCrossPlatformCoverageDriveSync_md5FailureAborts(t *testing.T) { - if os.Geteuid() == 0 { - t.Skip("chmod-based unreadable file needs a non-root user") - } + testseam.Swap(t, &md5File, func(string) (string, error) { + return "", errors.New("md5 boom") + }) + dir := t.TempDir() p := filepath.Join(dir, "secret.txt") mustWrite(t, p, "data") - if err := os.Chmod(p, 0o000); err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = os.Chmod(p, 0o644) }) caller := syncCaller(map[string]string{ "ROOT": `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`, }) - if err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT"); err == nil { - t.Fatal("expected MD5 failure to abort sync") + err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "MD5") { + t.Fatalf("expected MD5 failure to abort sync, got %v", err) } } From f2a3025f414825cacbbd1081b78d4d71894cf9ec Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 17:52:38 +0800 Subject: [PATCH 019/250] test(drive): cover Windows sync branches --- internal/helpers/drive_pull.go | 6 ++++- internal/helpers/drive_status.go | 6 ++++- .../helpers/drive_status_coverage_test.go | 26 ++++++++++++++----- internal/helpers/drive_sync.go | 13 +++++++--- internal/helpers/drive_sync_conflict_test.go | 21 +++++++-------- internal/helpers/drive_sync_edges_test.go | 20 +++++--------- internal/helpers/drive_sync_platform_test.go | 9 +++++++ 7 files changed, 63 insertions(+), 38 deletions(-) diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index 9671cf88..4231a507 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -34,6 +34,10 @@ const ( ifExistsSkip = "skip" // 默认：本地已存在则保持不动 ) +// pullCreateTemp 仅作为文件系统失败分支的确定性测试 seam；测试必须通过 +// testseam.Swap 替换并自动恢复。 +var pullCreateTemp = os.CreateTemp + // pull 动作分类。 const ( pullActionDownloaded = "downloaded" @@ -271,7 +275,7 @@ func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, // 先下载到同目录下的临时文件，完整落盘后再原子 rename 覆盖目标：任何中途失败 // （网络中断、超时、写盘错误）都不会截断或破坏已存在的原文件。同目录保证 // rename 在同一文件系统内、可原子替换；rename 会替换目标符号链接本身而非跟随它。 - tmp, err := os.CreateTemp(dir, ".dws-pull-*") + tmp, err := pullCreateTemp(dir, ".dws-pull-*") if err != nil { return pullActionFailed, fmt.Errorf("创建临时文件失败: %w", err) } diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index a1a48c88..cafe7f80 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -388,6 +388,10 @@ func walkLocalTree(root string) (map[string]*localFile, error) { return files, nil } +// runDriveStatusWalkLocalTree 仅作为 runDriveStatus 扫描失败分支的确定性测试 seam； +// 测试必须通过 testseam.Swap 替换并自动恢复。 +var runDriveStatusWalkLocalTree = walkLocalTree + // walkLocalTreeEntry 是 walkLocalTree 的单条目处理逻辑。抽成命名函数只为可测： // Info() / filepath.Rel 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。 func walkLocalTreeEntry(root, path string, d fs.DirEntry, err error, files map[string]*localFile) error { @@ -531,7 +535,7 @@ func runDriveStatus(cmd *cobra.Command, _ []string) error { return err } - local, err := walkLocalTree(absDir) + local, err := runDriveStatusWalkLocalTree(absDir) if err != nil { return fmt.Errorf("扫描本地目录失败: %w", err) } diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index 9c14387d..c1b53fd2 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -11,6 +11,7 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) @@ -201,16 +202,12 @@ func TestCrossPlatformCoverageDriveStatus_unparsableListPropagates(t *testing.T) // exact 模式下本地文件不可读 → MD5 计算失败要作为错误上抛，不能静默当成一致。 func TestCrossPlatformCoverageDriveStatus_unreadableLocalFileFailsExactCompare(t *testing.T) { - if runtime.GOOS == "windows" || os.Geteuid() == 0 { - t.Skip("chmod-based unreadable file needs POSIX perms and a non-root user") - } dir := t.TempDir() p := filepath.Join(dir, "secret.txt") mustWrite(t, p, "data") - if err := os.Chmod(p, 0o000); err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = os.Chmod(p, 0o644) }) + testseam.Swap(t, &md5File, func(string) (string, error) { + return "", errors.New("MD5 boom") + }) caller := &driveScriptCaller{reply: func(_ string, _ map[string]any, _ int) (string, error) { return `{"result":{"items":[{"name":"secret.txt","type":"file","fileId":"S","md5":"abc"}],"nextToken":""}}`, nil @@ -221,6 +218,21 @@ func TestCrossPlatformCoverageDriveStatus_unreadableLocalFileFailsExactCompare(t } } +func TestCrossPlatformCoverageDriveStatus_walkLocalFailurePropagates(t *testing.T) { + dir := t.TempDir() + testseam.Swap(t, &runDriveStatusWalkLocalTree, func(string) (map[string]*localFile, error) { + return nil, errors.New("walk boom") + }) + caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + t.Error("local scan failure must abort before MCP calls") + return "", nil + }} + err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT") + if err == nil || !strings.Contains(err.Error(), "扫描本地目录失败") { + t.Fatalf("expected local scan failure, got %v", err) + } +} + // --local-folder 不是绝对路径 → 校验拦下，不发起任何 MCP 调用。 func TestCrossPlatformCoverageDriveStatus_relativeLocalFolderRejected(t *testing.T) { caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go index 9019eafb..79e06e4a 100644 --- a/internal/helpers/drive_sync.go +++ b/internal/helpers/drive_sync.go @@ -14,6 +14,13 @@ import ( "github.com/spf13/cobra" ) +// syncRename 与 syncOpenFile 仅作为文件系统失败分支的确定性测试 seam；测试必须 +// 通过 testseam.Swap 替换并自动恢复。 +var ( + syncRename = os.Rename + syncOpenFile = os.OpenFile +) + // ========================================================== // drive sync — 本地与钉盘双向同步（本地 ⇄ Drive） // ========================================================== @@ -415,7 +422,7 @@ func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf } // newAbs 此刻是我们刚用 O_EXCL 新建的空占位文件，覆盖它不会丢用户数据；且已确保它 // 不与任何等价既有文件冲突。 - if err := os.Rename(oldAbs, newAbs); err != nil { + if err := syncRename(oldAbs, newAbs); err != nil { _ = os.Remove(newAbs) // 清理空占位，避免残留 res.Summary.Failed++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: fmt.Sprintf("本地改名保留失败: %v", err)}) @@ -434,7 +441,7 @@ func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf if perr != nil { msg = perr.Error() } - if rbErr := os.Rename(newAbs, oldAbs); rbErr != nil { + if rbErr := syncRename(newAbs, oldAbs); rbErr != nil { if msg != "" { msg += "; " } @@ -498,7 +505,7 @@ func reserveSyncKeepBothTarget(absDir, rel, fileID string, occupied map[string]b if err != nil { return "", "", err // 逃逸/符号链接等，直接失败 } - f, oerr := os.OpenFile(abs, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644) + f, oerr := syncOpenFile(abs, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644) if oerr == nil { _ = f.Close() return cand, abs, nil diff --git a/internal/helpers/drive_sync_conflict_test.go b/internal/helpers/drive_sync_conflict_test.go index c57fd385..b3a98bb6 100644 --- a/internal/helpers/drive_sync_conflict_test.go +++ b/internal/helpers/drive_sync_conflict_test.go @@ -6,9 +6,10 @@ import ( "io" "os" "path/filepath" - "runtime" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // failFolderCaller 让指定名字的 create_folder 失败，其余一切正常， @@ -137,15 +138,11 @@ func TestCrossPlatformCoverageSyncKeepBoth_collidedIsFailed(t *testing.T) { // 占用改名目标失败（目录不可写）→ failed。 func TestCrossPlatformCoverageSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { - if runtime.GOOS == "windows" || os.Geteuid() == 0 { - t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") - } root := t.TempDir() mustWrite(t, filepath.Join(root, "f.txt"), "local") - if err := os.Chmod(root, 0o500); err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + testseam.Swap(t, &syncOpenFile, func(string, int, os.FileMode) (*os.File, error) { + return nil, errors.New("open file boom") + }) res := &driveSyncResult{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, @@ -158,10 +155,10 @@ func TestCrossPlatformCoverageSyncKeepBoth_reserveFailureIsFailed(t *testing.T) // 改名本身失败（本地原文件其实是目录）→ failed，并清理刚建的空占位。 func TestCrossPlatformCoverageSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { root := t.TempDir() - // rel 指向一个非空目录：os.Rename(dir, emptyFile) 会失败。 - if err := os.MkdirAll(filepath.Join(root, "f.txt", "inner"), 0o755); err != nil { - t.Fatal(err) - } + mustWrite(t, filepath.Join(root, "f.txt"), "local") + testseam.Swap(t, &syncRename, func(string, string) error { + return errors.New("rename boom") + }) res := &driveSyncResult{} occupied := map[string]bool{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go index 7e57e703..e2655b68 100644 --- a/internal/helpers/drive_sync_edges_test.go +++ b/internal/helpers/drive_sync_edges_test.go @@ -87,14 +87,10 @@ func TestCrossPlatformCoverageDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T // 目标目录不可写 → 创建临时文件失败。 func TestCrossPlatformCoveragePullOneFile_tempFileCreationFailure(t *testing.T) { - if runtime.GOOS == "windows" || os.Geteuid() == 0 { - t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") - } root := t.TempDir() - if err := os.Chmod(root, 0o500); err != nil { // r-x：可遍历不可写 - t.Fatal(err) - } - t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + testseam.Swap(t, &pullCreateTemp, func(string, string) (*os.File, error) { + return nil, errors.New("create temp boom") + }) prevDeps, prevArgs := deps, os.Args deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} @@ -244,14 +240,10 @@ func TestCrossPlatformCoverageReserveSyncKeepBothTarget_escapeFails(t *testing.T // 候选目标所在目录不可写 → OpenFile 以非 EEXIST 错误失败，直接上报。 func TestCrossPlatformCoverageReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { - if runtime.GOOS == "windows" || os.Geteuid() == 0 { - t.Skip("read-only dir enforcement needs POSIX perms and a non-root user") - } root := t.TempDir() - if err := os.Chmod(root, 0o500); err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = os.Chmod(root, 0o755) }) + testseam.Swap(t, &syncOpenFile, func(string, int, os.FileMode) (*os.File, error) { + return nil, errors.New("open file boom") + }) if _, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", map[string]bool{}); err == nil { t.Fatal("expected unwritable directory to fail") diff --git a/internal/helpers/drive_sync_platform_test.go b/internal/helpers/drive_sync_platform_test.go index 71f9313b..2ab28887 100644 --- a/internal/helpers/drive_sync_platform_test.go +++ b/internal/helpers/drive_sync_platform_test.go @@ -102,6 +102,15 @@ func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_allowsPlainNames(t *te } } +func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_rejectsNonCanonicalWindowsName(t *testing.T) { + if runtime.GOOS != "windows" { + return + } + if isSafeRemoteSegmentPlatform(`dir\..\file.txt`) { + t.Error("Windows non-canonical segment must be rejected") + } +} + // ────────────────────────────────────────────────────────── // WalkDir 单条目处理：Info() 与 filepath.Rel 的失败分支 // ────────────────────────────────────────────────────────── From 388ae0d37be84e5a16bd3ad0aa8d5359efe0bab9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 17:59:54 +0800 Subject: [PATCH 020/250] ci: shard parameter alias changes --- .github/workflows/ci.yml | 6 ++++++ test/scripts/changelog_pr_gate_test.go | 14 +++++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eace8f78..ba5d31ab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,6 +151,12 @@ jobs: filename.startsWith('internal/helpers/') || filename.startsWith('internal/generator/') || filename.startsWith('internal/cli/schema') || + // Parameter aliases are reduced against the live command tree. + // Their reverse-dependency set is too large for one focused + // race job, so use the existing full-suite shards. + filename === 'internal/cli/param_concepts.json' || + filename === 'internal/cli/param_concepts.schema.json' || + filename === 'internal/cli/param_aliases_generated.go' || filename.startsWith('internal/interfacesnapshot/') || filename.startsWith('internal/app/upgrade') || filename.startsWith('internal/transport/') || diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index bf05855b..93a73f07 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -973,7 +973,7 @@ if (!isInterfaceSensitive("internal/corecmd/corecmd.go")) { } } -func TestHighRiskClassificationShardsHelperChanges(t *testing.T) { +func TestHighRiskClassificationShardsFanoutChanges(t *testing.T) { root, err := filepath.Abs(filepath.Join("..", "..")) if err != nil { t.Fatalf("Abs(repo root) error = %v", err) @@ -996,6 +996,18 @@ if (!isHighRisk("internal/helpers/minutes.go")) { if (isHighRisk("internal/helpersx/minutes.go")) { throw new Error("helper high-risk classification must respect the path boundary"); } +for (const filename of [ + "internal/cli/param_concepts.json", + "internal/cli/param_concepts.schema.json", + "internal/cli/param_aliases_generated.go", +]) { + if (!isHighRisk(filename)) { + throw new Error(filename + " must use the sharded full suite"); + } +} +if (isHighRisk("internal/cli/param_concepts.json.bak")) { + throw new Error("parameter-alias high-risk classification must use exact paths"); +} ` cmd := exec.Command("node", "-e", probe) if output, err := cmd.CombinedOutput(); err != nil { From 1f1c27d68f3fcec7b952f951489fdb2e7c5aa2ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 18:06:10 +0800 Subject: [PATCH 021/250] fix(chat): restore audit join group flag --- internal/app/schema_shortcut_contract_test.go | 4 ++ internal/cli/param_aliases_generated.go | 7 +- internal/cli/param_concepts.json | 2 +- internal/helpers/chat.go | 15 +++-- internal/helpers/chat_command_edges_test.go | 65 +++++++++++++++++++ internal/helpers/chat_message_help_test.go | 19 ++++++ 6 files changed, 99 insertions(+), 13 deletions(-) diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index c1fe119c..c8f2f721 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -207,7 +207,11 @@ func assertChatCatalogCompleteLeafContracts(t testing.TB) { }) auditJoin := executeShortcutSchemaQuery(t, "--cli-path", "chat group audit-join-validation") + assertSchemaLeafParameterRequired(t, auditJoin, "chat group audit-join-validation", "group", true) assertSchemaLeafParameterEnum(t, auditJoin, "chat group audit-join-validation", "status", []string{"AuditApprove", "AuditDelete"}) + if parameters := schemaContractMap(auditJoin["parameters"]); parameters["conversation-id"] != nil { + t.Fatalf("chat group audit-join-validation publishes unapproved --conversation-id migration: %#v", parameters["conversation-id"]) + } } func assertSchemaLeafParameterRequired(t testing.TB, leaf map[string]any, cliPath, name string, want bool) { diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index 54cf3a80..097753bb 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -967,11 +967,8 @@ var generatedParamAliases = []ParamAliasEntry{ Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { - CLIPath: "chat group audit-join-validation", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat group audit-join-validation", + Blocked: []string{"chat", "chat-id", "conversation-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-id", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"staff-id", "uid", "user", "user-id", "userid"}, }, { diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 0e40b445..69799c81 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -129,7 +129,7 @@ "chat +chat-set-admin": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat +messages-read-status": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."}, - "chat group audit-join-validation": {"ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "A role-free user identifier cannot choose between the required --applicant and --inviter roles."}, + "chat group audit-join-validation": {"block": ["conversation-id", "open-conversation-id", "chat", "chat-id", "id"], "ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "This command keeps the legacy visible --group surface until a reviewed flag migration exists; role-free user identifiers cannot choose between the required --applicant and --inviter roles."}, "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."}, "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."}, "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."}, diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 0fc2dc99..897d682b 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -8490,11 +8490,11 @@ status 可选值: AuditIgnore — 忽略（服务端拒绝，不可用） AuditRefuse — 拒绝（服务端拒绝，不可用） AuditBlock — 拒绝且不再接受该用户的申请（服务端拒绝，不可用）`, - Example: ` dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove - dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" + Example: ` dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove + dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" # 查询入群验证记录: dws chat group list-join-validations`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "conversation-id", "record-id", "applicant", "inviter", "status"); err != nil { + if err := validateRequiredFlags(cmd, "group", "record-id", "applicant", "inviter", "status"); err != nil { return err } recordID, err := strconv.ParseInt(mustGetFlag(cmd, "record-id"), 10, 64) @@ -8506,7 +8506,7 @@ status 可选值: return fmt.Errorf("unsupported audit status %q, must be one of: AuditApprove, AuditDelete", status) } toolArgs := map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": mustGetFlag(cmd, "group"), "applyRecordId": recordID, "applicantUid": mustGetFlag(cmd, "applicant"), "inviterUid": mustGetFlag(cmd, "inviter"), @@ -8518,8 +8518,8 @@ status 可选值: return callMCPToolOnServer("im", "audit_join_group", toolArgs) }, } - chatGroupAuditJoinValidationCmd.Flags().String("conversation-id", "", "群 openConversationId (必填)") - _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("conversation-id") + chatGroupAuditJoinValidationCmd.Flags().String("group", "", "群 openConversationId (必填)") + _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("group") chatGroupAuditJoinValidationCmd.Flags().String("record-id", "", "申请记录 ID (必填)") _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("record-id") chatGroupAuditJoinValidationCmd.Flags().String("status", "", "审批动作，真机仅 AuditApprove/AuditDelete 可用；AuditIgnore/AuditRefuse/AuditBlock 服务端拒绝 (必填)") @@ -8552,11 +8552,12 @@ status 可选值: AgentSummary: "审批入群验证记录", UseWhen: []string{"需要对已知入群申请记录执行通过或删除审批动作时"}, AvoidWhen: []string{"还没有 record-id 时先用 chat group list-join-validations 查询"}, - Examples: []string{"dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove"}, + Examples: []string{"dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove"}, }, Parameters: []contract.ParamDecl{ {Name: "applicant", Property: "applicantUid", Required: boolPtr(true)}, {Name: "description", Property: "auditDescription", Required: boolPtr(false)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "inviter", Property: "inviterUid", Required: boolPtr(true)}, {Name: "record-id", Property: "applyRecordId", Required: boolPtr(true), InterfaceType: "integer"}, {Name: "status", Property: "status", Required: boolPtr(true), Enum: []string{"AuditApprove", "AuditDelete"}}, diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 33f65f06..0d49f0ed 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -319,6 +319,71 @@ func TestCrossPlatformCoverageChatNativeSendCardMentions(t *testing.T) { } } +func TestCrossPlatformCoverageChatSendCardHiddenAliasesMapToCanonicalPayload(t *testing.T) { + previousDeps, previousArgs := deps, os.Args + os.Args = []string{"dws", "chat"} + t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs }) + + for _, tc := range []struct { + name string + args []string + want map[string]any + }{ + { + name: "group alias", + args: []string{"--group=cid"}, + want: map[string]any{"openConversationId": "cid"}, + }, + { + name: "receiver alias", + args: []string{"--receiver=D1"}, + want: map[string]any{"receiverOpenDingTalkId": "D1"}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + err := runChatCoverageCommand(t, caller, append([]string{"message", "send-card"}, tc.args...)...) + if err != nil { + t.Fatal(err) + } + if caller.calls != 1 || caller.server != "im" || caller.tool != "create_and_send_card" || !reflect.DeepEqual(caller.args, tc.want) { + t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, tc.want) + } + }) + } +} + +func TestCrossPlatformCoverageChatGroupAuditJoinValidationUsesGroupPayload(t *testing.T) { + previousDeps, previousArgs := deps, os.Args + os.Args = []string{"dws", "chat"} + t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs }) + + caller := &scriptedToolCaller{} + err := runChatCoverageCommand(t, caller, + "group", "audit-join-validation", + "--group=cid", + "--record-id=123", + "--applicant=D-applicant", + "--inviter=D-inviter", + "--status=AuditDelete", + "--description=deny", + ) + if err != nil { + t.Fatal(err) + } + want := map[string]any{ + "openConversationId": "cid", + "applyRecordId": int64(123), + "applicantUid": "D-applicant", + "inviterUid": "D-inviter", + "status": "AuditDelete", + "auditDescription": "deny", + } + if caller.calls != 1 || caller.server != "im" || caller.tool != "audit_join_group" || !reflect.DeepEqual(caller.args, want) { + t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, want) + } +} + func TestCrossPlatformCoverageChatWebhookReplyConversationAndDownloadEdges(t *testing.T) { previousDeps, previousArgs := deps, os.Args os.Args = []string{"dws", "chat"} diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index f47e061d..15d340df 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -159,3 +159,22 @@ func TestCrossPlatformCoverageChatSendCardHelpUsesCanonicalIDFlags(t *testing.T) } } } + +func TestCrossPlatformCoverageChatGroupAuditJoinValidationHelpKeepsLegacyGroup(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) + cmd.SetArgs([]string{"group", "audit-join-validation", "--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("chat group audit-join-validation --help: %v\n%s", err, output.String()) + } + + help := output.String() + if !strings.Contains(help, "--group") { + t.Fatalf("audit-join-validation help missing --group:\n%s", help) + } + if strings.Contains(help, "--conversation-id") { + t.Fatalf("audit-join-validation help exposes unapproved migration flag --conversation-id:\n%s", help) + } +} From 21c65819754041a129b31a4b9e91d40d0fe045ee Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 18:31:09 +0800 Subject: [PATCH 022/250] docs(drive): keep confirmation out of examples --- skills/mono/references/products/drive.md | 2 +- skills/multi/dingtalk-drive/references/drive.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index bb4c56cd..6ee96349 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -449,7 +449,7 @@ Usage: Example: dws drive push --local-folder /abs/path/repo --remote-folder dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite --yes + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 87d99ed2..e9d26c24 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -434,7 +434,7 @@ Usage: Example: dws drive push --local-folder /abs/path/repo --remote-folder dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite --yes + dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite Flags: --local-folder string 本地文件夹绝对路径 (必填) --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) From e08fb484a8b74cdf8beaa5f5bca7fe563dc95a2c Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 19:02:56 +0800 Subject: [PATCH 023/250] fix(drive): make folder dry-run side-effect free --- internal/helpers/drive_pull.go | 56 +++++++ internal/helpers/drive_push.go | 69 ++++++++- internal/helpers/drive_push_test.go | 4 + internal/helpers/drive_status.go | 11 +- .../helpers/drive_status_coverage_test.go | 4 + .../helpers/drive_sync_confirmation_test.go | 144 ++++++++++++++++++ 6 files changed, 286 insertions(+), 2 deletions(-) diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index 4231a507..9a40f2db 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -65,6 +65,15 @@ type drivePullResult struct { Items []drivePullItem `json:"items"` } +type drivePullDryRunResult struct { + DryRun bool `json:"dry_run"` + Executed bool `json:"executed"` + PreviewKind string `json:"preview_kind"` + Operation string `json:"operation"` + IfExists string `json:"if_exists"` + Plan drivePullResult `json:"plan"` +} + // drivePartialFailure 在 summary.failed > 0 时返回：以 exit=1 退出，并把 // {"error":{"type":"partial_failure","detail":{summary,items}}} 原样透传出去。 // 结构上满足 core 的 RawStderrError 与 ExitCoder 接口（无需 import internal 包）。 @@ -174,6 +183,9 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { relPaths = append(relPaths, rel) } sort.Strings(relPaths) + if deps.Caller.DryRun() { + return printDrivePullDryRun(absDir, ifExists, remote, relPaths) + } // 落盘前先按目标文件系统的路径等价规则做一次全局冲突检查：大小写不敏感 FS 上 // A.txt 与 a.txt（或 NFC/NFD 异写）会落到同一本地文件；overwrite 会顺序覆盖、 @@ -234,6 +246,50 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { return deps.Out.PrintJSON(res) } +func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string) error { + plan := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} + caseInsensitive := runtime.GOOS == "windows" || runtime.GOOS == "darwin" + collided := detectTargetCollisions(absDir, relPaths, caseInsensitive) + for _, rel := range relPaths { + if collided[rel] { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePullItem{ + RelPath: rel, Action: pullActionFailed, + Error: "多个远端条目在目标平台默认文件系统上映射到同一本地路径，计划已拒绝", + }) + continue + } + localPath, err := resolveLocalTarget(absDir, rel) + if err != nil { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: err.Error()}) + continue + } + action := pullActionDownloaded + if fi, statErr := os.Stat(localPath); statErr == nil && fi.Mode().IsRegular() { + switch ifExists { + case ifExistsSkip: + action = pullActionSkipped + case ifExistsSmart: + rf := remote[rel] + if rf.ModifiedTimeValid && fi.ModTime().UnixMilli() >= rf.ModifiedTime { + action = pullActionSkipped + } + } + } + if action == pullActionSkipped { + plan.Summary.Skipped++ + } else { + plan.Summary.Downloaded++ + } + plan.Items = append(plan.Items, drivePullItem{RelPath: rel, Action: action}) + } + return deps.Out.PrintJSON(drivePullDryRunResult{ + DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive pull", + IfExists: ifExists, Plan: plan, + }) +} + // pullOneFile 处理单个远端文件：按 --if-exists 决定是否跳过，否则下载到 localPath。 // 返回动作分类（downloaded / skipped / failed）及失败时的 error。 func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, ifExists string) (string, error) { diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index fcce42c5..741fa7eb 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -64,6 +64,15 @@ type drivePushResult struct { Items []drivePushItem `json:"items"` } +type drivePushDryRunResult struct { + DryRun bool `json:"dry_run"` + Executed bool `json:"executed"` + PreviewKind string `json:"preview_kind"` + Operation string `json:"operation"` + IfExists string `json:"if_exists"` + Plan drivePushResult `json:"plan"` +} + // drivePushFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout， // 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明。 type drivePushFailure struct{ failed int } @@ -111,6 +120,9 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { } res := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))} + if deps.Caller.DryRun() { + return printDrivePushDryRun(ifExists, remoteFiles, remoteFolders, localDirs, localFiles) + } // 第一阶段：按需创建远端目录（浅层在前，保证父目录先于子目录存在）。 for _, dir := range localDirs { @@ -224,7 +236,7 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f args["nextToken"] = nextToken } - text, err := callMCPToolReturnText(ctx, "list_files", args) + text, err := callDriveListFiles(ctx, args) if err != nil { return err } @@ -275,6 +287,61 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f return nil } +func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, remoteFolders map[string]string, localDirs []string, localFiles []localPushFile) error { + plan := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))} + plannedFolders := make(map[string]string, len(remoteFolders)+len(localDirs)) + for rel, fileID := range remoteFolders { + plannedFolders[rel] = fileID + } + for _, dir := range localDirs { + if _, ok := plannedFolders[dir]; ok { + continue + } + parentRel, _ := splitRel(dir) + if plannedFolders[parentRel] == "" { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: "父目录未能创建"}) + continue + } + plannedFolders[dir] = "dry-run-planned-folder" + plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFolderCreated}) + } + for _, lf := range localFiles { + size := lf.Size + parentRel, _ := splitRel(lf.RelPath) + if plannedFolders[parentRel] == "" { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: "父目录未能创建"}) + continue + } + action := pushActionUploaded + if rf, exists := remoteFiles[lf.RelPath]; exists { + switch ifExists { + case ifExistsSkip: + action = pushActionSkipped + case ifExistsSmart: + if rf.ModifiedTimeValid && rf.ModifiedTime >= lf.ModTimeMillis { + action = pushActionSkipped + } else { + action = pushActionOverwritten + } + case ifExistsOverwrite: + action = pushActionOverwritten + } + } + if action == pushActionSkipped { + plan.Summary.Skipped++ + } else { + plan.Summary.Uploaded++ + } + plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: action, SizeBytes: &size}) + } + return deps.Out.PrintJSON(drivePushDryRunResult{ + DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive push", + IfExists: ifExists, Plan: plan, + }) +} + // walkLocalForPush 遍历本地根目录，返回所有子目录 rel_path（不含根本身，浅层在前） // 与所有常规文件。dirs 升序排序保证父目录先于子目录被创建。 func walkLocalForPush(root string) ([]string, []localPushFile, error) { diff --git a/internal/helpers/drive_push_test.go b/internal/helpers/drive_push_test.go index 984dd582..c424e75f 100644 --- a/internal/helpers/drive_push_test.go +++ b/internal/helpers/drive_push_test.go @@ -163,6 +163,10 @@ func (m *driveSyncMockCaller) CallTool(_ context.Context, _ string, toolName str return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil } +func (m *driveSyncMockCaller) CallReadTool(ctx context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) { + return m.CallTool(ctx, productID, toolName, args) +} + func (m *driveSyncMockCaller) Format() string { return "raw" } func (m *driveSyncMockCaller) DryRun() bool { return m.dryRun } func (m *driveSyncMockCaller) Fields() string { return "" } diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index cafe7f80..b62afa8b 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -121,7 +121,7 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m args["nextToken"] = nextToken } - text, err := callMCPToolReturnText(ctx, "list_files", args) + text, err := callDriveListFiles(ctx, args) if err != nil { return err } @@ -180,6 +180,15 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m return nil } +// callDriveListFiles 让文件夹同步族在 --dry-run 下仍可通过受控只读通道获取 +// 远端现状；普通 CallTool 在 dry-run 下只会返回执行计划，不能被当作业务数据解析。 +func callDriveListFiles(ctx context.Context, args map[string]any) (string, error) { + if deps.Caller.DryRun() { + return callMCPReadToolReturnTextOnServer(ctx, "drive", "list_files", args) + } + return callMCPToolReturnText(ctx, "list_files", args) +} + // driveItem 是 list_files 返回里的一个 dentry 条目。 // 后端字段命名存在多种历史写法，这里用带 fallback 的访问器做防御式解析。 type driveItem map[string]any diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index c1b53fd2..79222ce0 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -42,6 +42,10 @@ func (m *driveScriptCaller) CallTool(_ context.Context, _ string, toolName strin return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil } +func (m *driveScriptCaller) CallReadTool(ctx context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) { + return m.CallTool(ctx, productID, toolName, args) +} + func (m *driveScriptCaller) Format() string { return "raw" } func (m *driveScriptCaller) DryRun() bool { return m.dryRun } func (m *driveScriptCaller) Fields() string { return "" } diff --git a/internal/helpers/drive_sync_confirmation_test.go b/internal/helpers/drive_sync_confirmation_test.go index 25db77d4..6f7cbbf2 100644 --- a/internal/helpers/drive_sync_confirmation_test.go +++ b/internal/helpers/drive_sync_confirmation_test.go @@ -1,6 +1,7 @@ package helpers import ( + "bytes" "context" "os" "path/filepath" @@ -134,6 +135,149 @@ func TestCrossPlatformCoverageDriveSyncFamily_dryRunNeedsNoConfirmation(t *testi } } +func TestCrossPlatformCoverageDrivePull_dryRunPlansWithoutLocalWrites(t *testing.T) { + parent := t.TempDir() + target := filepath.Join(parent, "not-created") + caller := pullListingCaller(`{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}`) + caller.dryRun = true + SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + t.Error("dry-run must not download") + return nil + }) + t.Cleanup(func() { SetHTTPGetFile(nil) }) + + var out bytes.Buffer + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} + os.Args = []string{"dws", "drive", "pull"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": target, "remote-folder": "ROOT"}) + if err := cmd.RunE(cmd, nil); err != nil { + t.Fatalf("dry-run pull: %v", err) + } + if _, err := os.Stat(target); !os.IsNotExist(err) { + t.Fatalf("dry-run must not create local root: %v", err) + } + if got := len(caller.callsFor("download_file")); got != 0 { + t.Fatalf("download_file calls = %d, want 0", got) + } + if text := out.String(); !strings.Contains(text, `"dry_run": true`) || !strings.Contains(text, `"remote.txt"`) { + t.Fatalf("missing pull plan: %s", text) + } +} + +func TestCrossPlatformCoverageDrivePush_dryRunPlansWithoutRemoteWrites(t *testing.T) { + dir := t.TempDir() + if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(dir, "sub", "local.txt"), "local") + caller := syncCaller(nil) + caller.dryRun = true + SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + t.Error("dry-run must not upload") + return nil + }) + t.Cleanup(func() { SetHTTPPutFile(nil) }) + + var out bytes.Buffer + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} + os.Args = []string{"dws", "drive", "push"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + cmd := findDriveSubcommand(t, "push") + mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) + if err := cmd.RunE(cmd, nil); err != nil { + t.Fatalf("dry-run push: %v", err) + } + for _, tool := range []string{"create_folder", "get_upload_info", "commit_upload"} { + if got := len(caller.callsFor(tool)); got != 0 { + t.Fatalf("%s calls = %d, want 0", tool, got) + } + } + if text := out.String(); !strings.Contains(text, `"dry_run": true`) || !strings.Contains(text, `"sub/local.txt"`) { + t.Fatalf("missing push plan: %s", text) + } +} + +func TestCrossPlatformCoverageDrivePull_dryRunPlanBranches(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "skip.txt"), "skip") + mustWrite(t, filepath.Join(root, "smart.txt"), "smart") + remote := map[string]*remoteFile{ + "A.txt": {RelPath: "A.txt"}, + "a.txt": {RelPath: "a.txt"}, + "../escape": {RelPath: "../escape"}, + "skip.txt": {RelPath: "skip.txt"}, + "smart.txt": {RelPath: "smart.txt", ModifiedTime: 1, ModifiedTimeValid: true}, + "new.txt": {RelPath: "new.txt"}, + } + var out bytes.Buffer + prevDeps := deps + deps = &Deps{Out: &Formatter{w: &out}} + t.Cleanup(func() { deps = prevDeps }) + + if err := printDrivePullDryRun(root, ifExistsSkip, remote, + []string{"A.txt", "a.txt", "../escape", "skip.txt", "new.txt"}); err != nil { + t.Fatalf("skip plan: %v", err) + } + if text := out.String(); !strings.Contains(text, pullActionFailed) || !strings.Contains(text, pullActionSkipped) || !strings.Contains(text, pullActionDownloaded) { + t.Fatalf("skip plan did not cover failed/skipped/downloaded: %s", text) + } + out.Reset() + if err := printDrivePullDryRun(root, ifExistsSmart, remote, []string{"smart.txt"}); err != nil { + t.Fatalf("smart plan: %v", err) + } + if !strings.Contains(out.String(), pullActionSkipped) { + t.Fatalf("smart plan must skip newer local file: %s", out.String()) + } +} + +func TestCrossPlatformCoverageDrivePush_dryRunPlanBranches(t *testing.T) { + var out bytes.Buffer + prevDeps := deps + deps = &Deps{Out: &Formatter{w: &out}} + t.Cleanup(func() { deps = prevDeps }) + remoteFolders := map[string]string{"": "ROOT", "existing": "EXISTING"} + remoteFiles := map[string]*remoteFile{ + "skip.txt": {RelPath: "skip.txt"}, + "smart-skip.txt": {RelPath: "smart-skip.txt", ModifiedTime: 20, ModifiedTimeValid: true}, + "smart-overwrite.txt": {RelPath: "smart-overwrite.txt", ModifiedTime: 1, ModifiedTimeValid: true}, + "overwrite.txt": {RelPath: "overwrite.txt"}, + } + files := func(paths ...string) []localPushFile { + result := make([]localPushFile, 0, len(paths)) + for _, path := range paths { + result = append(result, localPushFile{RelPath: path, Size: 1, ModTimeMillis: 10}) + } + return result + } + + if err := printDrivePushDryRun(ifExistsSkip, remoteFiles, remoteFolders, + []string{"existing", "missing/child"}, files("orphan/a.txt", "skip.txt", "new.txt")); err != nil { + t.Fatalf("skip plan: %v", err) + } + if text := out.String(); !strings.Contains(text, pushActionFailed) || !strings.Contains(text, pushActionSkipped) || !strings.Contains(text, pushActionUploaded) { + t.Fatalf("skip plan did not cover failed/skipped/uploaded: %s", text) + } + out.Reset() + if err := printDrivePushDryRun(ifExistsSmart, remoteFiles, remoteFolders, nil, + files("smart-skip.txt", "smart-overwrite.txt")); err != nil { + t.Fatalf("smart plan: %v", err) + } + if text := out.String(); !strings.Contains(text, pushActionSkipped) || !strings.Contains(text, pushActionOverwritten) { + t.Fatalf("smart plan did not cover skip/overwrite: %s", text) + } + out.Reset() + if err := printDrivePushDryRun(ifExistsOverwrite, remoteFiles, remoteFolders, nil, files("overwrite.txt")); err != nil { + t.Fatalf("overwrite plan: %v", err) + } + if !strings.Contains(out.String(), pushActionOverwritten) { + t.Fatalf("overwrite plan must overwrite existing file: %s", out.String()) + } +} + // ────────────────────────────────────────────────────────── // 2. 明确确认后才发出精确的工具调用 // ────────────────────────────────────────────────────────── From b29a12abbf84d77014c0ea2ca4170909b09412c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 19:05:11 +0800 Subject: [PATCH 024/250] test: harden parameter alias safety gates --- .github/workflows/ci.yml | 9 ++- .../param_alias_payload_equivalence_test.go | 72 +++++++++++++++++++ test/scripts/changelog_pr_gate_test.go | 24 ++++++- 3 files changed, 100 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ba5d31ab..4707eb50 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -537,10 +537,13 @@ jobs: test -n "$package_output" mapfile -t packages <<< "$package_output" test "${#packages[@]}" -gt 0 - # cli/smoke own heavy NewRootCommand / Schema assembly under -race; give - # them a dedicated budget so remaining is not SIGTERM'd by OOM/timeout. + # app/cli/smoke own heavy NewRootCommand / Schema assembly under + # -race; give them a dedicated budget so slower hosted runners do not + # hit the package timeout while the shards remain independently bounded. timeout_budget=12m - if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then + if [ "$TEST_SHARD" = "app" ] || + [ "$TEST_SHARD" = "cli" ] || + [ "$TEST_SHARD" = "smoke" ]; then timeout_budget=15m fi go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}" diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index a4fe2e16..eaa2a0b7 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -4,11 +4,13 @@ package app import ( + "errors" "reflect" "strings" "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline" ) @@ -365,6 +367,24 @@ var paramAliasNewDriveCases = []struct { {command: "drive +upload", emitted: "file-id", canonical: "node"}, } +// paramAliasNewDriveConfirmationCases selects one newly reviewed alias for +// every Drive command in the expansion whose declared runtime safety requires +// confirmation. The full matrix below proves all spellings preserve the +// confirmed payload; this smaller matrix proves aliases cannot cross the +// confirmation boundary before any transport call is made. +var paramAliasNewDriveConfirmationCases = []struct { + command string + emitted string + canonical string +}{ + {command: "drive +delete", emitted: "file-id", canonical: "node"}, + {command: "drive +publish-unset", emitted: "document-url", canonical: "node"}, + {command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"}, + {command: "drive +rename", emitted: "new-name", canonical: "name"}, + {command: "drive +upload", emitted: "source-file", canonical: "file"}, + {command: "drive +version-revert", emitted: "version-number", canonical: "version"}, +} + // paramAliasRepresentativePayloadCases keeps final transport coverage across // old concept aliases, command overrides, native compatibility flags, read and // write commands, and different products. Every reviewed alias is still @@ -602,6 +622,45 @@ func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalP } } +func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *testing.T) { + for _, test := range paramAliasNewDriveConfirmationCases { + test := test + t.Run(test.command+"/"+test.emitted, func(t *testing.T) { + complete, ok := paramAliasCompleteCommand(test.command, test.canonical) + if !ok { + t.Fatal("reviewed Drive confirmation alias has no complete-command E2E template") + } + aliasArgs, replacements := replaceLongFlag(complete, test.canonical, test.emitted) + if replacements != 1 { + t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, complete) + } + unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes") + if removals != 1 { + t.Fatalf("confirmation template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs) + } + + entry, exists := cli.LookupParamAlias(test.command) + target, active := entry.ResolveAlias(test.emitted) + if !exists || !active || target != test.canonical { + t.Fatalf("reviewed Drive alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical) + } + + caller := ¶mAliasCaptureCaller{} + ctx, err := executeParamAliasPayloadE2E(t, caller, unconfirmedArgs...) + if ctx == nil { + t.Fatal("unconfirmed alias command skipped PreParse") + } + var appErr *apperrors.Error + if !errors.As(err, &appErr) || appErr.Reason != "confirmation_required" { + t.Fatalf("unconfirmed alias command error = %#v, want confirmation_required\nargs=%v", err, unconfirmedArgs) + } + if len(caller.calls) != 0 { + t.Fatalf("unconfirmed alias command crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, caller.calls) + } + }) + } +} + // Some artifact commands deliberately continue past the final captured // transport call into local download/upload handling. Deterministic invalid // resource responses form their expected post-transport test boundary; @@ -674,3 +733,16 @@ func replaceLongFlag(args []string, canonical, emitted string) ([]string, int) { } return out, replacements } + +func removeExactArg(args []string, target string) ([]string, int) { + out := make([]string, 0, len(args)) + removals := 0 + for _, arg := range args { + if arg == target { + removals++ + continue + } + out = append(out, arg) + } + return out, removals +} diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index 93a73f07..d01f366e 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -6,6 +6,7 @@ import ( "path/filepath" "strings" "testing" + "time" ) type changelogGateRepo struct { @@ -71,6 +72,20 @@ func newChangelogGateRepo(t *testing.T) *changelogGateRepo { t.Fatalf("Abs(repo root) error = %v", err) } root := t.TempDir() + // Git may briefly continue automatic repository maintenance after a command + // exits on hosted runners. Proactively remove the fixture with bounded + // retries before testing.TempDir performs its strict final cleanup. + t.Cleanup(func() { + var cleanupErr error + for attempt := 0; attempt < 10; attempt++ { + cleanupErr = os.RemoveAll(root) + if cleanupErr == nil { + return + } + time.Sleep(time.Duration(attempt+1) * 10 * time.Millisecond) + } + t.Errorf("RemoveAll changelog gate repository after retries: %v", cleanupErr) + }) for _, path := range []string{ "LICENSE", @@ -108,6 +123,8 @@ func newChangelogGateRepo(t *testing.T) *changelogGateRepo { changelogGateWrite(t, root, "CHANGELOG.md", changelogGateBase, 0o644) changelogGateGit(t, root, "init", "-b", "main") + changelogGateGit(t, root, "config", "gc.auto", "0") + changelogGateGit(t, root, "config", "maintenance.auto", "false") changelogGateGit(t, root, "config", "user.name", "Changelog Gate Test") changelogGateGit(t, root, "config", "user.email", "changelog-gate@example.com") changelogGateGit(t, root, "add", ".") @@ -1166,10 +1183,13 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { } raceJob := admission[raceStart:raceEnd] // Full race shards use a dynamic package-level timeout: default/floor 12m, - // with cli/smoke raised to 15m for NewRootCommand / Schema assembly under -race. + // with app/cli/smoke raised to 15m for NewRootCommand / Schema assembly under + // -race on slower hosted runners. for _, want := range []string{ "timeout_budget=12m", - `if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then`, + `if [ "$TEST_SHARD" = "app" ] ||`, + `[ "$TEST_SHARD" = "cli" ] ||`, + `[ "$TEST_SHARD" = "smoke" ]; then`, "timeout_budget=15m", `go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"`, "- smoke", From 0e856f5a6ea792744092ffaff976e6f020bcf368 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 19:25:14 +0800 Subject: [PATCH 025/250] test(drive): cover dry-run collisions on Linux --- internal/helpers/drive_pull.go | 6 +++--- internal/helpers/drive_sync_confirmation_test.go | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index 9a40f2db..1a8d3894 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -184,7 +184,8 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { } sort.Strings(relPaths) if deps.Caller.DryRun() { - return printDrivePullDryRun(absDir, ifExists, remote, relPaths) + caseInsensitive := runtime.GOOS == "windows" || runtime.GOOS == "darwin" + return printDrivePullDryRun(absDir, ifExists, remote, relPaths, caseInsensitive) } // 落盘前先按目标文件系统的路径等价规则做一次全局冲突检查：大小写不敏感 FS 上 @@ -246,9 +247,8 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { return deps.Out.PrintJSON(res) } -func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string) error { +func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool) error { plan := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} - caseInsensitive := runtime.GOOS == "windows" || runtime.GOOS == "darwin" collided := detectTargetCollisions(absDir, relPaths, caseInsensitive) for _, rel := range relPaths { if collided[rel] { diff --git a/internal/helpers/drive_sync_confirmation_test.go b/internal/helpers/drive_sync_confirmation_test.go index 6f7cbbf2..73a18c03 100644 --- a/internal/helpers/drive_sync_confirmation_test.go +++ b/internal/helpers/drive_sync_confirmation_test.go @@ -219,14 +219,14 @@ func TestCrossPlatformCoverageDrivePull_dryRunPlanBranches(t *testing.T) { t.Cleanup(func() { deps = prevDeps }) if err := printDrivePullDryRun(root, ifExistsSkip, remote, - []string{"A.txt", "a.txt", "../escape", "skip.txt", "new.txt"}); err != nil { + []string{"A.txt", "a.txt", "../escape", "skip.txt", "new.txt"}, true); err != nil { t.Fatalf("skip plan: %v", err) } if text := out.String(); !strings.Contains(text, pullActionFailed) || !strings.Contains(text, pullActionSkipped) || !strings.Contains(text, pullActionDownloaded) { t.Fatalf("skip plan did not cover failed/skipped/downloaded: %s", text) } out.Reset() - if err := printDrivePullDryRun(root, ifExistsSmart, remote, []string{"smart.txt"}); err != nil { + if err := printDrivePullDryRun(root, ifExistsSmart, remote, []string{"smart.txt"}, false); err != nil { t.Fatalf("smart plan: %v", err) } if !strings.Contains(out.String(), pullActionSkipped) { From 65a00b497b55dcbe3a6bb45b2d4ab1784dfab447 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 20:06:09 +0800 Subject: [PATCH 026/250] fix(chat): migrate audit join validation id flag --- internal/app/schema_shortcut_contract_test.go | 6 +- internal/cli/param_aliases_generated.go | 8 +- internal/cli/param_concepts.json | 1 - internal/helpers/chat.go | 38 +++-- internal/helpers/chat_command_edges_test.go | 136 +++++++++++++++--- internal/helpers/chat_message_help_test.go | 45 +++++- .../approved-flag-migrations-v1.json | 2 +- 7 files changed, 192 insertions(+), 44 deletions(-) diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 360613a6..55950aa0 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -207,10 +207,10 @@ func assertChatCatalogCompleteLeafContracts(t testing.TB) { }) auditJoin := executeShortcutSchemaQuery(t, "--cli-path", "chat group audit-join-validation") - assertSchemaLeafParameterRequired(t, auditJoin, "chat group audit-join-validation", "group", true) + assertSchemaLeafParameterRequired(t, auditJoin, "chat group audit-join-validation", "conversation-id", true) assertSchemaLeafParameterEnum(t, auditJoin, "chat group audit-join-validation", "status", []string{"AuditApprove", "AuditDelete"}) - if parameters := schemaContractMap(auditJoin["parameters"]); parameters["conversation-id"] != nil { - t.Fatalf("chat group audit-join-validation publishes unapproved --conversation-id migration: %#v", parameters["conversation-id"]) + if parameters := schemaContractMap(auditJoin["parameters"]); parameters["group"] != nil { + t.Fatalf("chat group audit-join-validation publishes hidden --group alias: %#v", parameters["group"]) } } diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index 097753bb..e5fc9df1 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -967,9 +967,11 @@ var generatedParamAliases = []ParamAliasEntry{ Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { - CLIPath: "chat group audit-join-validation", - Blocked: []string{"chat", "chat-id", "conversation-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-id", "open-conversation-ids", "source", "src-conversation-id", "target"}, - Ambiguous: []string{"staff-id", "uid", "user", "user-id", "userid"}, + CLIPath: "chat group audit-join-validation", + Aliases: map[string]string{ + "chat-id": "conversation-id", + }, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group bots", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 69799c81..7d37a432 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -129,7 +129,6 @@ "chat +chat-set-admin": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat +messages-read-status": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."}, - "chat group audit-join-validation": {"block": ["conversation-id", "open-conversation-id", "chat", "chat-id", "id"], "ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "This command keeps the legacy visible --group surface until a reviewed flag migration exists; role-free user identifiers cannot choose between the required --applicant and --inviter roles."}, "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."}, "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."}, "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."}, diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 897d682b..aac7990f 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -18,6 +18,7 @@ import ( "unicode/utf8" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" @@ -247,6 +248,19 @@ func installChatIMIDFlagAliases(root *cobra.Command) { } } visit(root) + restoreChatAuditJoinValidationCanonicalRequired(root) +} + +func restoreChatAuditJoinValidationCanonicalRequired(root *cobra.Command) { + if root == nil { + return + } + cmd, _, err := root.Find([]string{"group", "audit-join-validation"}) + if err != nil || cmd == nil { + return + } + _ = cmd.MarkFlagRequired("conversation-id") + clearChatAliasRequiredAnnotations(cmd, "group") } func clearChatAliasRequiredAnnotations(cmd *cobra.Command, aliases ...string) { @@ -8490,11 +8504,14 @@ status 可选值: AuditIgnore — 忽略（服务端拒绝，不可用） AuditRefuse — 拒绝（服务端拒绝，不可用） AuditBlock — 拒绝且不再接受该用户的申请（服务端拒绝，不可用）`, - Example: ` dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove - dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" + Example: ` dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove + dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditDelete --description "不符合入群条件" # 查询入群验证记录: dws chat group list-join-validations`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "group", "record-id", "applicant", "inviter", "status"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group"); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "record-id", "applicant", "inviter", "status"); err != nil { return err } recordID, err := strconv.ParseInt(mustGetFlag(cmd, "record-id"), 10, 64) @@ -8506,7 +8523,7 @@ status 可选值: return fmt.Errorf("unsupported audit status %q, must be one of: AuditApprove, AuditDelete", status) } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "group"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group"), "applyRecordId": recordID, "applicantUid": mustGetFlag(cmd, "applicant"), "inviterUid": mustGetFlag(cmd, "inviter"), @@ -8518,8 +8535,13 @@ status 可选值: return callMCPToolOnServer("im", "audit_join_group", toolArgs) }, } - chatGroupAuditJoinValidationCmd.Flags().String("group", "", "群 openConversationId (必填)") - _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("group") + corecmd.RegisterFlags(chatGroupAuditJoinValidationCmd, []LeafFlag{{ + Name: "conversation-id", + Usage: "群 openConversationId (必填)", + Required: true, + Aliases: []string{"group"}, + }}) + _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("conversation-id") chatGroupAuditJoinValidationCmd.Flags().String("record-id", "", "申请记录 ID (必填)") _ = chatGroupAuditJoinValidationCmd.MarkFlagRequired("record-id") chatGroupAuditJoinValidationCmd.Flags().String("status", "", "审批动作，真机仅 AuditApprove/AuditDelete 可用；AuditIgnore/AuditRefuse/AuditBlock 服务端拒绝 (必填)") @@ -8552,12 +8574,12 @@ status 可选值: AgentSummary: "审批入群验证记录", UseWhen: []string{"需要对已知入群申请记录执行通过或删除审批动作时"}, AvoidWhen: []string{"还没有 record-id 时先用 chat group list-join-validations 查询"}, - Examples: []string{"dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove"}, + Examples: []string{"dws chat group audit-join-validation --conversation-id --record-id 123456 --applicant --inviter --status AuditApprove"}, }, Parameters: []contract.ParamDecl{ {Name: "applicant", Property: "applicantUid", Required: boolPtr(true)}, + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "description", Property: "auditDescription", Required: boolPtr(false)}, - {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "inviter", Property: "inviterUid", Required: boolPtr(true)}, {Name: "record-id", Property: "applyRecordId", Required: boolPtr(true), InterfaceType: "integer"}, {Name: "status", Property: "status", Required: boolPtr(true), Enum: []string{"AuditApprove", "AuditDelete"}}, diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 0d49f0ed..0f42875b 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -3,6 +3,7 @@ package helpers import ( "context" "errors" + "fmt" "io" "os" "path/filepath" @@ -32,14 +33,26 @@ func runChatCoverageCommand(t *testing.T, caller edition.ToolCaller, args ...str func runChatCoverageDirect(t *testing.T, path []string, flags map[string]string) error { t.Helper() - command, _, err := newChatCommand().Find(path) + InitDeps(&scriptedToolCaller{}) + deps.Out.w = io.Discard + deps.Out.errW = io.Discard + root := newChatCommand() + installExampleGlobalFlags(root) + root.PersistentFlags().Bool("debug", false, "") + root.PersistentFlags().Bool("verbose", false, "") + command, _, err := root.Find(path) if err != nil { return err } for name, value := range flags { - if err := command.Flags().Set(name, value); err != nil { + flag := command.Flag(name) + if flag == nil { + return fmt.Errorf("no such flag -%s", name) + } + if err := flag.Value.Set(value); err != nil { return err } + flag.Changed = true } return command.RunE(command, nil) } @@ -190,7 +203,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"group", "transfer-owner", "--group=cid", "--new-owner=D-owner"}, {"group", "update-icon", "--group=cid", "--icon-media-id=@valid"}, {"group", "set-history", "--group=cid", "--option=ALL"}, - {"group", "audit-join-validation", "--group=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"}, + {"group", "audit-join-validation", "--conversation-id=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"}, {"mark-read", "--conversation-id=cid", "--message-id=mid"}, {"text", "translate", "--query=hello", "--to=zh_CN"}, {"group-role", "set-user", "--group=cid", "--user=D1", "--role-ids=r1"}, @@ -353,34 +366,111 @@ func TestCrossPlatformCoverageChatSendCardHiddenAliasesMapToCanonicalPayload(t * } } -func TestCrossPlatformCoverageChatGroupAuditJoinValidationUsesGroupPayload(t *testing.T) { +func TestCrossPlatformCoverageChatGroupAuditJoinValidationUsesCanonicalAndAliasPayload(t *testing.T) { previousDeps, previousArgs := deps, os.Args os.Args = []string{"dws", "chat"} t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs }) - caller := &scriptedToolCaller{} - err := runChatCoverageCommand(t, caller, - "group", "audit-join-validation", - "--group=cid", - "--record-id=123", - "--applicant=D-applicant", - "--inviter=D-inviter", - "--status=AuditDelete", - "--description=deny", - ) + for _, tc := range []struct { + name string + flag string + }{ + {name: "canonical conversation-id", flag: "--conversation-id=cid"}, + {name: "hidden group alias", flag: "--group=cid"}, + } { + t.Run(tc.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + err := runChatCoverageCommand(t, caller, + "group", "audit-join-validation", + tc.flag, + "--record-id=123", + "--applicant=D-applicant", + "--inviter=D-inviter", + "--status=AuditDelete", + "--description=deny", + ) + if err != nil { + t.Fatal(err) + } + want := map[string]any{ + "openConversationId": "cid", + "applyRecordId": int64(123), + "applicantUid": "D-applicant", + "inviterUid": "D-inviter", + "status": "AuditDelete", + "auditDescription": "deny", + } + if caller.calls != 1 || caller.server != "im" || caller.tool != "audit_join_group" || !reflect.DeepEqual(caller.args, want) { + t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, want) + } + }) + } +} + +func TestCrossPlatformCoverageChatIMIDMigrationRequiredFlagErrors(t *testing.T) { + previousDeps, previousArgs := deps, os.Args + os.Args = []string{"dws", "chat"} + t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs }) + + tests := []struct { + name string + path []string + flag map[string]string + want string + }{ + {name: "message list mutually exclusive targets", path: []string{"message", "list"}, flag: map[string]string{"conversation-id": "cid", "user": "u1", "time": "2026-01-01"}, want: "mutually exclusive"}, + {name: "message list missing target", path: []string{"message", "list"}, flag: map[string]string{"time": "2026-01-01"}, want: "--conversation-id, --user or --open-dingtalk-id is required"}, + {name: "topic replies missing conversation", path: []string{"message", "list-topic-replies"}, flag: map[string]string{"topic-id": "t1"}, want: "conversation-id"}, + {name: "read status missing conversation", path: []string{"message", "read-status"}, flag: map[string]string{"message-id": "m1"}, want: "conversation-id"}, + {name: "read status conflicting aliases", path: []string{"message", "read-status"}, flag: map[string]string{"conversation-id": "cid1", "group": "cid2", "message-id": "m1"}, want: "conflicts"}, + {name: "read status missing message", path: []string{"message", "read-status"}, flag: map[string]string{"conversation-id": "cid"}, want: "message-id"}, + {name: "update text emotion missing message", path: []string{"message", "update-text-emotion"}, flag: map[string]string{"conversation-id": "cid", "old-emotion-id": "e1", "emotion-id": "e2", "emotion-name": "n", "text": "t", "background-id": "b"}, want: "message-id"}, + {name: "update text emotion missing detail flag", path: []string{"message", "update-text-emotion"}, flag: map[string]string{"conversation-id": "cid", "message-id": "m1", "old-emotion-id": "e1", "emotion-id": "e2", "emotion-name": "n", "text": "t"}, want: "background-id"}, + {name: "transfer owner missing conversation", path: []string{"group", "transfer-owner"}, flag: map[string]string{"new-owner": "D1"}, want: "conversation-id"}, + {name: "invite url missing conversation", path: []string{"group", "invite-url"}, want: "conversation-id"}, + {name: "quit missing conversation", path: []string{"group", "quit"}, want: "conversation-id"}, + {name: "update icon missing conversation", path: []string{"group", "update-icon"}, flag: map[string]string{"icon-media-id": "@media"}, want: "conversation-id"}, + {name: "update settings missing conversation", path: []string{"group", "update-settings"}, flag: map[string]string{"setting-key": "searchable"}, want: "conversation-id"}, + {name: "set admin missing conversation", path: []string{"group", "set-admin"}, flag: map[string]string{"users": "D1"}, want: "conversation-id"}, + {name: "role list missing conversation", path: []string{"group-role", "list"}, want: "group"}, + {name: "role add missing conversation", path: []string{"group-role", "add"}, flag: map[string]string{"name": "role"}, want: "conversation-id"}, + {name: "role update missing conversation", path: []string{"group-role", "update"}, flag: map[string]string{"role-id": "r1", "name": "role"}, want: "conversation-id"}, + {name: "role remove missing conversation", path: []string{"group-role", "remove"}, flag: map[string]string{"role-id": "r1"}, want: "conversation-id"}, + {name: "role set user missing conversation", path: []string{"group-role", "set-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"}, + {name: "role remove user missing conversation", path: []string{"group-role", "remove-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"}, + {name: "role query user missing conversation", path: []string{"group-role", "query-user"}, flag: map[string]string{"user": "D1"}, want: "conversation-id"}, + {name: "bots conflicting conversation aliases", path: []string{"group", "bots"}, flag: map[string]string{"conversation-id": "cid1", "id": "cid2"}, want: "conflicts"}, + {name: "bots conflicting group aliases", path: []string{"group", "bots"}, flag: map[string]string{"group-name": "项目群", "group": "cid"}, want: "conflicts"}, + {name: "dismiss missing conversation", path: []string{"group", "dismiss"}, flag: map[string]string{"yes": "true"}, want: "conversation-id"}, + {name: "set history missing conversation", path: []string{"group", "set-history"}, flag: map[string]string{"option": "ALL"}, want: "conversation-id"}, + {name: "set pin missing message", path: []string{"message", "set-pin-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"}, + {name: "unset pin missing message", path: []string{"message", "unset-pin-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"}, + {name: "audit join missing conversation", path: []string{"group", "audit-join-validation"}, flag: map[string]string{"record-id": "1", "applicant": "D1", "inviter": "D2", "status": "AuditApprove"}, want: "conversation-id"}, + {name: "set top missing message", path: []string{"message", "set-top-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"}, + {name: "unset top missing message", path: []string{"message", "unset-top-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"}, + {name: "update alias missing conversation", path: []string{"group", "update-alias"}, flag: map[string]string{"alias-title": "alias"}, want: "conversation-id"}, + {name: "notice create missing conversation", path: []string{"group", "notice", "create"}, flag: map[string]string{"content": "hello"}, want: "conversation-id"}, + {name: "notice edit missing conversation", path: []string{"group", "notice", "edit"}, flag: map[string]string{"notice-id": "n1", "content": "hello"}, want: "conversation-id"}, + {name: "notice get missing conversation", path: []string{"group", "notice", "get"}, flag: map[string]string{"notice-id": "n1"}, want: "conversation-id"}, + {name: "notice list missing conversation", path: []string{"group", "notice", "list"}, want: "conversation-id"}, + } + + probe := newChatCommand() + messageList, _, err := probe.Find([]string{"message", "list"}) if err != nil { t.Fatal(err) } - want := map[string]any{ - "openConversationId": "cid", - "applyRecordId": int64(123), - "applicantUid": "D-applicant", - "inviterUid": "D-inviter", - "status": "AuditDelete", - "auditDescription": "deny", + if got, err := chatConversationID(messageList); err != nil || got != "" { + t.Fatalf("empty chatConversationID = %q, %v", got, err) } - if caller.calls != 1 || caller.server != "im" || caller.tool != "audit_join_group" || !reflect.DeepEqual(caller.args, want) { - t.Fatalf("call = count:%d server:%q tool:%q args:%#v, want %#v", caller.calls, caller.server, caller.tool, caller.args, want) + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + err := runChatCoverageDirect(t, tc.path, tc.flag) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want containing %q", err, tc.want) + } + }) } } diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 15d340df..0781dbab 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -17,8 +17,43 @@ import ( "bytes" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" + "github.com/spf13/cobra" ) +func TestCrossPlatformCoverageChatGroupAuditJoinValidationAliasContract(t *testing.T) { + cmd := newChatCommand() + leaf, _, err := cmd.Find([]string{"group", "audit-join-validation"}) + if err != nil { + t.Fatal(err) + } + canonical := leaf.Flags().Lookup("conversation-id") + if canonical == nil || canonical.Hidden { + t.Fatalf("conversation-id flag = %#v, want visible canonical", canonical) + } + legacy := leaf.Flags().Lookup("group") + if legacy == nil || !legacy.Hidden { + t.Fatalf("group flag = %#v, want hidden compatibility alias", legacy) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "conversation-id" { + t.Fatalf("group alias_of annotation = %#v", got) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("group alias_origin annotation = %#v", got) + } + if got := legacy.Annotations[cobra.BashCompOneRequiredFlag]; len(got) != 0 { + t.Fatalf("hidden group alias kept required annotation: %#v", got) + } +} + +func TestCrossPlatformCoverageChatGroupAuditJoinValidationRestoreRequiredNoop(t *testing.T) { + restoreChatAuditJoinValidationCanonicalRequired(nil) + root := &cobra.Command{Use: "chat"} + root.AddCommand(&cobra.Command{Use: "other"}) + restoreChatAuditJoinValidationCanonicalRequired(root) +} + func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing.T) { tests := []struct { name string @@ -160,7 +195,7 @@ func TestCrossPlatformCoverageChatSendCardHelpUsesCanonicalIDFlags(t *testing.T) } } -func TestCrossPlatformCoverageChatGroupAuditJoinValidationHelpKeepsLegacyGroup(t *testing.T) { +func TestCrossPlatformCoverageChatGroupAuditJoinValidationHelpUsesCanonicalConversationID(t *testing.T) { cmd := newChatCommand() var output bytes.Buffer cmd.SetOut(&output) @@ -171,10 +206,10 @@ func TestCrossPlatformCoverageChatGroupAuditJoinValidationHelpKeepsLegacyGroup(t } help := output.String() - if !strings.Contains(help, "--group") { - t.Fatalf("audit-join-validation help missing --group:\n%s", help) + if !strings.Contains(help, "--conversation-id") { + t.Fatalf("audit-join-validation help missing --conversation-id:\n%s", help) } - if strings.Contains(help, "--conversation-id") { - t.Fatalf("audit-join-validation help exposes unapproved migration flag --conversation-id:\n%s", help) + if strings.Contains(help, "--group string") { + t.Fatalf("audit-join-validation help exposes hidden --group alias:\n%s", help) } } diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index d52e59e4..49753948 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -31,7 +31,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { From d40a22aeb02fab1cd6403c4888c44289ea269a35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 20:17:10 +0800 Subject: [PATCH 027/250] fix(chat): default start from explicit message end --- internal/helpers/chat.go | 36 +++-- .../helpers/chat_message_pagination_test.go | 128 ++++++++++++++++++ 2 files changed, 155 insertions(+), 9 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 83bc0567..a1fef36d 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -467,7 +467,10 @@ func validateNativeSearchConversationScope(conversationIDs []string) error { } func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { - startRaw, endRaw := defaultChatMessageTimeRange(cmd, 24*time.Hour) + startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 24*time.Hour) + if err != nil { + return nil, err + } cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ "startTime": startRaw, @@ -486,7 +489,10 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { if senderUserID == "" && senderOpenDingTalkID == "" { return nil, fmt.Errorf("--sender-user-id or --sender-open-dingtalk-id is required") } - startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + if err != nil { + return nil, err + } startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err @@ -514,7 +520,10 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { } func chatMessageListMentionsArgs(cmd *cobra.Command) (map[string]any, error) { - startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + if err != nil { + return nil, err + } startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err @@ -554,7 +563,10 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) { if err := validateRequiredFlagWithAliases(cmd, "query", "keyword"); err != nil { return nil, err } - startRaw, endRaw := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) + if err != nil { + return nil, err + } startMs, err := parseISOTimeToMillis("start", startRaw) if err != nil { return nil, err @@ -580,17 +592,23 @@ func chatMessageSearchArgs(cmd *cobra.Command) (map[string]any, error) { return toolArgs, nil } -func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string) { +func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string, error) { startRaw := mustGetFlag(cmd, "start") endRaw := mustGetFlag(cmd, "end") - now := time.Now() + anchor := time.Now() if endRaw == "" { - endRaw = now.Format(time.RFC3339) + endRaw = anchor.Format(time.RFC3339) + } else { + endMs, err := parseISOTimeToMillis("end", endRaw) + if err != nil { + return "", "", err + } + anchor = time.UnixMilli(endMs) } if startRaw == "" { - startRaw = now.Add(-lookback).Format(time.RFC3339) + startRaw = anchor.Add(-lookback).Format(time.RFC3339) } - return startRaw, endRaw + return startRaw, endRaw, nil } func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 2706b621..8911b5e1 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -213,6 +213,134 @@ func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) { } } +func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { + endRaw := "2026-01-01T00:00:00+08:00" + endMs, err := parseISOTimeToMillis("end", endRaw) + if err != nil { + t.Fatal(err) + } + tests := []struct { + name string + args []string + wantTool string + wantLookback time.Duration + }{ + { + name: "list-all defaults start one day before explicit end", + args: []string{"message", "list-all", "--end", endRaw}, + wantTool: "search_messages_by_time_range", + wantLookback: 24 * time.Hour, + }, + { + name: "list-by-sender defaults start seven days before explicit end", + args: []string{"message", "list-by-sender", "--sender-user-id", "u1", "--end", endRaw}, + wantTool: "search_messages_by_sender", + wantLookback: 7 * 24 * time.Hour, + }, + { + name: "list-mentions defaults start seven days before explicit end", + args: []string{"message", "list-mentions", "--end", endRaw}, + wantTool: "search_at_me_message", + wantLookback: 7 * 24 * time.Hour, + }, + { + name: "search defaults start seven days before explicit end", + args: []string{"message", "search", "--query", "发布", "--end", endRaw}, + wantTool: "search_messages_by_keyword", + wantLookback: 7 * 24 * time.Hour, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatMessagePaginationCaller{} + _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one call", caller.calls) + } + got := caller.calls[0] + if got.tool != tt.wantTool { + t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) + } + startMs := numericArgAsInt64(t, got.args["startTime"]) + gotEndMs := numericArgAsInt64(t, got.args["endTime"]) + if gotEndMs != endMs { + t.Fatalf("endTime = %d, want %d", gotEndMs, endMs) + } + wantStartMs := time.UnixMilli(endMs).Add(-tt.wantLookback).UnixMilli() + if startMs != wantStartMs { + t.Fatalf("startTime = %d, want %d", startMs, wantStartMs) + } + }) + } +} + +func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing.T) { + startRaw := "2026-01-01T00:00:00+08:00" + startMs, err := parseISOTimeToMillis("start", startRaw) + if err != nil { + t.Fatal(err) + } + tests := []struct { + name string + args []string + wantTool string + }{ + { + name: "list-all defaults end to now", + args: []string{"message", "list-all", "--start", startRaw}, + wantTool: "search_messages_by_time_range", + }, + { + name: "list-by-sender defaults end to now", + args: []string{"message", "list-by-sender", "--sender-user-id", "u1", "--start", startRaw}, + wantTool: "search_messages_by_sender", + }, + { + name: "list-mentions defaults end to now", + args: []string{"message", "list-mentions", "--start", startRaw}, + wantTool: "search_at_me_message", + }, + { + name: "search defaults end to now", + args: []string{"message", "search", "--query", "发布", "--start", startRaw}, + wantTool: "search_messages_by_keyword", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatMessagePaginationCaller{} + before := time.Now() + _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) + after := time.Now() + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one call", caller.calls) + } + got := caller.calls[0] + if got.tool != tt.wantTool { + t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) + } + gotStartMs := numericArgAsInt64(t, got.args["startTime"]) + if gotStartMs != startMs { + t.Fatalf("startTime = %d, want %d", gotStartMs, startMs) + } + endMs := numericArgAsInt64(t, got.args["endTime"]) + wantEndMin := before.Truncate(time.Second).UnixMilli() + wantEndMax := after.Add(time.Second).UnixMilli() + if endMs < wantEndMin || endMs > wantEndMax { + t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax) + } + }) + } +} + func numericArgAsInt64(t *testing.T, value any) int64 { t.Helper() switch v := value.(type) { From 30f3273a17b6ec5d968e8c530d930f0eb4449d45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 20:43:56 +0800 Subject: [PATCH 028/250] fix(chat): validate message list-all time range --- .changes/973-chat-message-time-defaults.md | 5 +++ internal/helpers/chat.go | 11 ++++++ .../helpers/chat_message_pagination_test.go | 36 +++++++++++++++++++ 3 files changed, 52 insertions(+) create mode 100644 .changes/973-chat-message-time-defaults.md diff --git a/.changes/973-chat-message-time-defaults.md b/.changes/973-chat-message-time-defaults.md new file mode 100644 index 00000000..1a6e5496 --- /dev/null +++ b/.changes/973-chat-message-time-defaults.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Chat message time defaults** (#973) — validates `chat message list-all` time ranges locally and defaults omitted message-query time bounds without creating reversed windows. diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index a1fef36d..d9352996 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -471,6 +471,17 @@ func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { if err != nil { return nil, err } + startMs, err := parseISOTimeToMillis("start", startRaw) + if err != nil { + return nil, err + } + endMs, err := parseISOTimeToMillis("end", endRaw) + if err != nil { + return nil, err + } + if err := validateTimeRange(startMs, endMs); err != nil { + return nil, err + } cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ "startTime": startRaw, diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 8911b5e1..221bffa3 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -6,6 +6,7 @@ import ( "encoding/json" "io" "reflect" + "strings" "testing" "time" @@ -341,6 +342,41 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing } } +func TestChatMessageListAllRejectsInvalidTimeRanges(t *testing.T) { + tests := []struct { + name string + args []string + wantErr string + }{ + { + name: "invalid start", + args: []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"}, + wantErr: "cannot parse time for --start", + }, + { + name: "end before start", + args: []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"}, + wantErr: "--end must be after --start", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatMessagePaginationCaller{} + _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) + if err == nil { + t.Fatal("command succeeded, want validation error") + } + if !strings.Contains(err.Error(), tt.wantErr) { + t.Fatalf("error = %v, want containing %q", err, tt.wantErr) + } + if len(caller.calls) != 0 { + t.Fatalf("calls = %#v, want no MCP call", caller.calls) + } + }) + } +} + func numericArgAsInt64(t *testing.T, value any) int64 { t.Helper() switch v := value.(type) { From 1dabfa1dc6fece3adc2b249904717be790dad4e2 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 20:48:16 +0800 Subject: [PATCH 029/250] fix(drive): keep pull partial results on stdout --- internal/helpers/drive.go | 2 +- internal/helpers/drive_pull.go | 36 +++++++++---------- internal/helpers/drive_pull_coverage_test.go | 18 ++++++++-- internal/helpers/drive_pull_test.go | 10 +++--- internal/helpers/drive_sync_edges_test.go | 15 ++++++++ skills/mono/references/products/drive.md | 2 +- .../multi/dingtalk-drive/references/drive.md | 2 +- 7 files changed, 54 insertions(+), 31 deletions(-) diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index acbd8bfc..b5455fb6 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -3319,7 +3319,7 @@ modified_time（--quick）逐文件比对。两侧各自递归遍历，rel_path 预览，确认后以相同参数追加 --yes 执行。 输出 summary（downloaded/skipped/failed）与逐文件 items。 -若有文件下载失败，命令以非零退出码退出（error.type=partial_failure）。`, +若有文件下载失败，命令以非零退出码退出，结构化结果仍在 stdout。`, Example: ` dws drive pull --local-folder /abs/path/repo --remote-folder dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart dws drive pull --local-folder /abs/path/repo --remote-folder --space-id xxxx`, diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index 1a8d3894..ceeea8c5 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -2,7 +2,6 @@ package helpers import ( "context" - "encoding/json" "fmt" "os" "path/filepath" @@ -23,8 +22,8 @@ import ( // // 递归列出 --remote-folder 指向的钉盘文件夹下所有 type=FILE 的文件，逐一下载到 // --local-folder 对应的相对路径。已存在的本地文件按 --if-exists 决定 -// overwrite / smart / skip。summary.failed > 0 时以非零退出码退出，并在 -// error.type=partial_failure / error.detail 里返回同一份 summary + items。 +// overwrite / smart / skip。结构化 summary + items 始终打印到 stdout； +// summary.failed > 0 时额外以非零退出码退出。 // ────────────────────────────────────────────────────────── // --if-exists 的三种策略。 @@ -74,13 +73,14 @@ type drivePullDryRunResult struct { Plan drivePullResult `json:"plan"` } -// drivePartialFailure 在 summary.failed > 0 时返回：以 exit=1 退出，并把 -// {"error":{"type":"partial_failure","detail":{summary,items}}} 原样透传出去。 -// 结构上满足 core 的 RawStderrError 与 ExitCoder 接口（无需 import internal 包）。 -type drivePartialFailure struct{ raw string } +// drivePartialFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout， +// 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明（与 push/sync 一致）。 +type drivePartialFailure struct{ failed int } -func (e *drivePartialFailure) Error() string { return e.raw } -func (e *drivePartialFailure) RawStderr() string { return e.raw } +func (e *drivePartialFailure) Error() string { + return fmt.Sprintf("drive pull: %d file(s) failed", e.failed) +} +func (e *drivePartialFailure) RawStderr() string { return e.Error() } func (e *drivePartialFailure) ExitCode() int { return 1 } // pathCollisionKey 把本地目标路径归一化成「目标文件系统下的等价键」，用于探测多个 @@ -233,18 +233,14 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { res.Items = append(res.Items, item) } - if res.Summary.Failed > 0 { - // partial_failure：非零退出码，summary+items 一并放进 error.detail。 - payload := map[string]any{ - "error": map[string]any{ - "type": "partial_failure", - "detail": res, - }, - } - b, _ := json.Marshal(payload) - return &drivePartialFailure{raw: string(b)} + // 结构化结果始终打印到 stdout；有失败则额外以非零退出码退出。 + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr } - return deps.Out.PrintJSON(res) + if res.Summary.Failed > 0 { + return &drivePartialFailure{failed: res.Summary.Failed} + } + return nil } func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool) error { diff --git a/internal/helpers/drive_pull_coverage_test.go b/internal/helpers/drive_pull_coverage_test.go index f59c93b5..8809f9b5 100644 --- a/internal/helpers/drive_pull_coverage_test.go +++ b/internal/helpers/drive_pull_coverage_test.go @@ -150,13 +150,25 @@ func TestCrossPlatformCoverageDrivePull_downloadFailureIsPartialFailure(t *testi SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) t.Cleanup(func() { SetHTTPGetFile(nil) }) - err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT") + var out strings.Builder + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} + os.Args = []string{"dws", "drive", "pull"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + err := runDrivePull(cmd, nil) var pf *drivePartialFailure if !errors.As(err, &pf) { t.Fatalf("expected drivePartialFailure, got %T %v", err, err) } - if !strings.Contains(pf.raw, "partial_failure") { - t.Errorf("detail missing partial_failure: %s", pf.raw) + if pf.failed != 1 || pf.RawStderr() != "drive pull: 1 file(s) failed" { + t.Errorf("partial failure = %#v, stderr = %q", pf, pf.RawStderr()) + } + stdout := out.String() + if !strings.Contains(stdout, `"failed": 1`) || !strings.Contains(stdout, `"rel_path": "a.txt"`) { + t.Errorf("stdout must retain the structured partial result: %s", stdout) } } diff --git a/internal/helpers/drive_pull_test.go b/internal/helpers/drive_pull_test.go index 83233eca..f7543bab 100644 --- a/internal/helpers/drive_pull_test.go +++ b/internal/helpers/drive_pull_test.go @@ -371,16 +371,16 @@ func TestCrossPlatformCoverageParseDriveDownloadInfo_invalidJSON(t *testing.T) { } // ────────────────────────────────────────────────────────── -// drivePartialFailure — pull 部分失败错误：exit=1，JSON 原样透传 +// drivePartialFailure — pull 部分失败错误：exit=1，stderr 仅保留简短说明 // ────────────────────────────────────────────────────────── func TestCrossPlatformCoverageDrivePartialFailure(t *testing.T) { - raw := `{"error":{"type":"partial_failure","detail":{}}}` - e := &drivePartialFailure{raw: raw} + e := &drivePartialFailure{failed: 2} if e.ExitCode() != 1 { t.Errorf("ExitCode() = %d, want 1", e.ExitCode()) } - if e.Error() != raw || e.RawStderr() != raw { - t.Errorf("Error()/RawStderr() should return the raw JSON verbatim") + want := "drive pull: 2 file(s) failed" + if e.Error() != want || e.RawStderr() != want { + t.Errorf("Error()/RawStderr() = %q / %q, want %q", e.Error(), e.RawStderr(), want) } } diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go index e2655b68..c8c3cfbf 100644 --- a/internal/helpers/drive_sync_edges_test.go +++ b/internal/helpers/drive_sync_edges_test.go @@ -134,6 +134,21 @@ func TestCrossPlatformCoveragePullOneFile_renameOntoDirectoryFails(t *testing.T) // PrintJSON 失败分支 // ────────────────────────────────────────────────────────── +func TestCrossPlatformCoverageDrivePull_printFailurePropagates(t *testing.T) { + dir := t.TempDir() + + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: failingWriter{}}} + os.Args = []string{"dws", "drive", "pull"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) + if err := runDrivePull(cmd, nil); err == nil { + t.Fatal("expected the PrintJSON writer failure to propagate") + } +} + func TestCrossPlatformCoverageDrivePush_printFailurePropagates(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "x") diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 6ee96349..5289cf76 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -437,7 +437,7 @@ Flags: - 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 - 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 - 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 -- `summary.failed > 0` 时命令以**非零退出码**退出（`error.type=partial_failure`），同一份 `summary + items` 在 `error.detail` 里返回；脚本/agent 直接看 exit code 即可判断成败。 +- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，stderr 只保留简短失败说明。脚本/agent 直接看 exit code 即可判断成败。 ### 把本地文件夹推送（镜像）到钉盘 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index e9d26c24..04703443 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -422,7 +422,7 @@ Flags: - 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 - 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 - 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 -- `summary.failed > 0` 时命令以**非零退出码**退出（`error.type=partial_failure`），同一份 `summary + items` 在 `error.detail` 里返回；脚本/agent 直接看 exit code 即可判断成败。 +- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，stderr 只保留简短失败说明。脚本/agent 直接看 exit code 即可判断成败。 ### 把本地文件夹推送（镜像）到钉盘 From cf8dd167a4d87e894f30dada07ca3ac78c12add2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 20:49:57 +0800 Subject: [PATCH 030/250] fix(cli): preserve scoped space aliases --- .../param_alias_payload_equivalence_test.go | 2 + internal/cli/param_aliases_generated.go | 61 ++++++++++++----- internal/cli/param_aliases_test.go | 65 +++++++++++++++++++ internal/cli/param_concepts.json | 28 ++++---- 4 files changed, 130 insertions(+), 26 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index eaa2a0b7..2db173ef 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -405,6 +405,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("devdoc article search", "current-page"): true, // command override paramAliasPayloadCaseKey("doc +comment-create", "body"): true, // write shortcut content alias paramAliasPayloadCaseKey("doc +copy", "parent-folder-id"): true, // Doc folder role on a write shortcut + paramAliasPayloadCaseKey("doc create", "space-id"): true, // published Doc workspace compatibility remains payload-equivalent paramAliasPayloadCaseKey("doc +create", "content-format"): true, // shortcut format alias preserves markdown/jsonml enum paramAliasPayloadCaseKey("doc +create-from-template", "keyword"): true, // template search alias composes with a write workflow paramAliasPayloadCaseKey("doc +create-from-template", "workspace-id"): true, // template target workspace identifier @@ -424,6 +425,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("doc block insert", "parent-block-id"): true, // scoped block-role alias paramAliasPayloadCaseKey("doc comment delete", "comment-id"): true, // destructive comment-key alias paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role + paramAliasPayloadCaseKey("drive info", "workspace"): true, // published numeric storage-space compatibility remains payload-equivalent paramAliasPayloadCaseKey("mail folder update", "folder-id"): true, // write-command identifier alias paramAliasPayloadCaseKey("report list", "from-date"): true, // date-range concept alias } diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index c7101d5d..dc98598e 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -1893,11 +1893,13 @@ var generatedParamAliases = []ParamAliasEntry{ "member-role": "role", "node-id": "node", "permission-role": "role", + "space": "workspace", + "space-id": "workspace", "url": "node", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +access-grant", @@ -1912,11 +1914,13 @@ var generatedParamAliases = []ParamAliasEntry{ "member-role": "role", "node-id": "node", "permission-role": "role", + "space": "workspace", + "space-id": "workspace", "url": "node", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "space", "space-id", "storage-space-id", "target-user-id", "target-user-ids", "task-id", "template-id", "user-id", "user-ids", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "id", "job-id", "name", "parent-id", "permission", "public-permission", "reserve-role", "revision", "storage-space-id", "target-user-id", "target-user-ids", "task-id", "template-id", "user-id", "user-ids", "version"}, Ambiguous: []string{"target-user", "user", "users"}, }, { @@ -1929,11 +1933,13 @@ var generatedParamAliases = []ParamAliasEntry{ "file-id": "node", "knowledge-base-id": "workspace", "node-id": "node", + "space": "workspace", + "space-id": "workspace", "url": "node", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +background-delete", @@ -2074,11 +2080,13 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", + "space": "workspace", + "space-id": "workspace", "url": "node", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +create", @@ -2090,11 +2098,13 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", + "space": "workspace", + "space-id": "workspace", "text": "content", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"content-file", "dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "mime-type", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id", "title"}, + Blocked: []string{"content-file", "dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "mime-type", "node", "node-id", "parent-id", "storage-space-id", "title"}, }, { CLIPath: "doc +create-from-template", @@ -2108,10 +2118,12 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-node-id": "folder", "q": "query", "search-word": "query", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id", "subject", "text", "title"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "storage-space-id", "subject", "text", "title"}, }, { CLIPath: "doc +doc-append", @@ -2212,10 +2224,12 @@ var generatedParamAliases = []ParamAliasEntry{ "member-role": "role", "node-id": "node", "permission-role": "role", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "permission", "public-permission", "reserve-role", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "filter-role", "folder", "folder-id", "permission", "public-permission", "reserve-role", "storage-space-id"}, }, { CLIPath: "doc +history-list", @@ -2266,10 +2280,12 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "parent-id", "storage-space-id"}, }, { CLIPath: "doc +inspect", @@ -2305,12 +2321,14 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-node-id": "folder", "per-page": "limit", "size": "limit", + "space": "workspace", + "space-id": "workspace", "take": "limit", "top": "limit", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"count", "dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "offset", "page", "parent-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"count", "dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "offset", "page", "parent-id", "storage-space-id"}, }, { CLIPath: "doc +media-download", @@ -2371,11 +2389,13 @@ var generatedParamAliases = []ParamAliasEntry{ "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", + "space": "workspace", + "space-id": "workspace", "url": "node", "wiki-workspace-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "space", "space-id", "storage-space-id", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "dingdrive-space-id", "drive-space-id", "id", "job-id", "name", "parent-id", "revision", "role", "storage-space-id", "task-id", "template-id", "version"}, }, { CLIPath: "doc +resource-delete", @@ -2691,10 +2711,12 @@ var generatedParamAliases = []ParamAliasEntry{ "body": "content", "doc-format": "content-format", "knowledge-base-id": "workspace", + "space": "workspace", + "space-id": "workspace", "text": "content", "wiki-workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "folder-id", "mime-type", "node", "node-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "export-format", "folder-id", "mime-type", "node", "node-id", "storage-space-id"}, }, { CLIPath: "doc export", @@ -2716,17 +2738,21 @@ var generatedParamAliases = []ParamAliasEntry{ CLIPath: "doc file create", Aliases: map[string]string{ "knowledge-base-id": "workspace", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "storage-space-id"}, }, { CLIPath: "doc import", Aliases: map[string]string{ "knowledge-base-id": "workspace", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "node", "node-id", "storage-space-id"}, }, { CLIPath: "doc import get", @@ -2836,9 +2862,11 @@ var generatedParamAliases = []ParamAliasEntry{ CLIPath: "doc template apply", Aliases: map[string]string{ "knowledge-base-id": "workspace", + "space": "workspace", + "space-id": "workspace", "wiki-workspace-id": "workspace", }, - Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "space", "space-id", "storage-space-id"}, + Blocked: []string{"dentry-id", "dingdrive-space-id", "drive-space-id", "folder-id", "node", "node-id", "storage-space-id"}, }, { CLIPath: "doc template list", @@ -3504,9 +3532,12 @@ var generatedParamAliases = []ParamAliasEntry{ "dentry-uuid": "node", "dingdrive-space-id": "space-id", "drive-space-id": "space-id", + "space": "space-id", "storage-space-id": "space-id", + "workspace": "space-id", + "workspace-id": "space-id", }, - Blocked: []string{"dentry-id", "document-url", "knowledge-base-id", "space", "wiki-workspace-id", "workspace", "workspace-id"}, + Blocked: []string{"dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id"}, }, { CLIPath: "drive list", diff --git a/internal/cli/param_aliases_test.go b/internal/cli/param_aliases_test.go index aab959b7..64f76daa 100644 --- a/internal/cli/param_aliases_test.go +++ b/internal/cli/param_aliases_test.go @@ -515,3 +515,68 @@ func TestGeneratedParamAliasesAreWellFormed(t *testing.T) { } } } + +func TestCrossPlatformCoveragePublishedSpaceWorkspaceAliasesRemainExecutable(t *testing.T) { + docCommands := []string{ + "doc +access-change", + "doc +access-grant", + "doc +access-revoke", + "doc +copy", + "doc +create", + "doc +create-from-template", + "doc +grant-and-share", + "doc +import", + "doc +list", + "doc +move", + "doc create", + "doc file create", + "doc import", + "doc template apply", + } + for _, command := range docCommands { + entry, ok := LookupParamAlias(command) + if !ok { + t.Errorf("published Doc command %q has no generated parameter-alias entry", command) + continue + } + for _, emitted := range []string{"space", "space-id"} { + target, active := entry.ResolveAlias(emitted) + if !active || target != "workspace" { + t.Errorf("%s --%s resolution = active:%v target:%q, want --workspace", command, emitted, active, target) + } + if entry.IsBlocked(emitted) || entry.IsAmbiguous(emitted) { + t.Errorf("%s --%s remains protected after restoring its published alias", command, emitted) + } + } + } + + driveInfo, ok := LookupParamAlias("drive info") + if !ok { + t.Fatal("published drive info command has no generated parameter-alias entry") + } + for _, emitted := range []string{"space", "workspace", "workspace-id"} { + target, active := driveInfo.ResolveAlias(emitted) + if !active || target != "space-id" { + t.Errorf("drive info --%s resolution = active:%v target:%q, want --space-id", emitted, active, target) + } + if driveInfo.IsBlocked(emitted) || driveInfo.IsAmbiguous(emitted) { + t.Errorf("drive info --%s remains protected after restoring its published alias", emitted) + } + } + + // Compatibility remains exact-path scoped. Strong type spellings introduced + // after the split continue to guard the two value domains elsewhere. + for _, test := range []struct { + command string + emitted string + }{ + {command: "doc create", emitted: "storage-space-id"}, + {command: "drive +upload", emitted: "workspace-id"}, + {command: "drive info", emitted: "knowledge-base-id"}, + } { + entry, ok := LookupParamAlias(test.command) + if !ok || !entry.IsBlocked(test.emitted) { + t.Errorf("%s --%s must remain blocked outside the published compatibility set", test.command, test.emitted) + } + } +} diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 6a9433f1..eb8f5d17 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -112,9 +112,9 @@ "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain."}, "doc +export-get": {"block": ["doc-id", "document-id", "file-id", "node", "node-id", "task-id", "url"], "note": "This command queries one export jobId. Document node identifiers and import taskId spellings are different entities and are rejected.", "scoped_aliases": {"export-job-id": "job-id"}, "scope_strict": true}, "doc block delete": {"block": ["index"], "note": "index (position) vs node (node id) are different"}, - "doc +copy": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, - "doc +list": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, - "doc +move": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, + "doc +copy": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve the compatibility published before workspace and numeric DingDrive storage-space concepts were split; they do not make those value domains globally equivalent."}, + "doc +list": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve the compatibility published before workspace and numeric DingDrive storage-space concepts were split; they do not make those value domains globally equivalent."}, + "doc +move": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve the compatibility published before workspace and numeric DingDrive storage-space concepts were split; they do not make those value domains globally equivalent."}, "doc comment create": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."}, "doc comment reply": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."}, "doc comment update": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."}, @@ -169,10 +169,16 @@ "chat +messages-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values, not openMessageId values."}, "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["group", "msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The observed --group spelling carried a natural group name and is blocked. The only message role is the referenced message; plural IDs are not accepted, while --chat remains a CID alias and native --message-id stays native."}, "chat +messages-resource-download": {"block": ["download-dir"], "note": "--output may be a file or directory under workspace safety rules; a download directory cannot be assumed equivalent."}, - "doc +access-grant": {"block": ["target-user-id", "target-user-ids", "user-id", "user-ids"], "ambiguous": ["target-user", "user", "users"], "scope_strict": true, "note": "The real --to accepts collaborator names and resolves them before granting access. Explicit ID spellings cannot be passed through unchanged, while role-free user spellings do not prove whether their values are names or IDs."}, - "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create."}, - "doc +create-from-template": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, - "doc +import": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, + "doc +access-change": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, + "doc +access-grant": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "block": ["target-user-id", "target-user-ids", "user-id", "user-ids"], "ambiguous": ["target-user", "user", "users"], "scope_strict": true, "note": "The real --to accepts collaborator names and resolves them before granting access. Explicit ID spellings cannot be passed through unchanged, while role-free user spellings do not prove whether their values are names or IDs. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, + "doc +access-revoke": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, + "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, + "doc +create-from-template": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, + "doc +import": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder", "space": "workspace", "space-id": "workspace"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, + "doc create": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, + "doc file create": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, + "doc import": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, + "doc template apply": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "ambiguous": ["element"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value. --element cannot choose between document content, a block target, or an insertion reference."}, "doc +inspect": {"scoped_aliases": {"include-access": "include-permissions", "include-member": "include-permissions", "include-members": "include-permissions", "include-versions": "include-history"}, "block": ["include", "include-blocks", "include-content", "include-info", "include-meta", "include-metadata"], "scope_strict": true, "note": "Access/member spellings denote the same optional permission list, and versions/history denote the same history section. Generic --include needs value-dependent expansion; base metadata is already returned; block/content reads belong to +fetch, so those spellings stop before fuzzy correction or dispatch."}, "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "block": ["content-format", "doc-format", "range"], "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary. --range is an invented composite argument observed alongside --scope range and cannot be split into block IDs by name-only normalization; content-format spellings do not map to the independent --detail contract."}, @@ -185,7 +191,7 @@ "doc +resource-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command downloads a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."}, "doc +resource-update": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has document-node, local-file, and HTTPS image URL roles. Only strong document spellings map to --node; --file-id and --url must stop as ambiguous."}, "doc +share": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a node identifier into a URL, so identifier spellings are rejected with guidance to provide --url."}, - "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native."}, + "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, "doc +version-save": {"block": ["message", "title"], "scope_strict": true, "note": "The current snapshot API accepts only the document target. Version title/message metadata are unsupported and cannot be represented by another existing flag."}, "drive copy": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node", "directory-id": "folder", "source-node-id": "node", "source-file-id": "node", "target-folder-id": "folder", "destination-folder-id": "folder", "target-workspace-id": "workspace", "destination-workspace-id": "workspace"}, "scope_strict": true, "note": "Source node and destination folder/workspace are different roles; role-free target IDs stop before write dispatch. --name is not a rename field on this command and must not be fuzzy-corrected to --node.", "block": ["dentry-id", "destination-node-id", "dingdrive-space-id", "drive-space-id", "name", "source-folder-id", "space-id", "storage-space-id"], "ambiguous": ["destination-id", "target-id"]}, "drive cover": {"scoped_aliases": {"document-id": "node", "dentry-uuid": "node"}, "scope_strict": true, "note": "The command accepts a Drive node ID or URL; native file-id/node-id/doc-id/url aliases stay native and are not duplicated centrally.", "block": ["dentry-id"]}, @@ -223,7 +229,7 @@ "drive +rename": {"scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "doc-id": "node", "document-id": "node", "url": "node", "document-url": "node", "id": "node", "folder": "node", "folder-id": "node", "file-name": "name", "display-name": "name", "new-name": "name"}, "block": ["dentry-id"], "scope_strict": true, "note": "The existing document, file or folder node and the requested new display name are separate required roles. Node ID/URL aliases match drive rename and pass through unchanged; numeric dentryId remains protected."}, "drive delete": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url"], "scope_strict": true, "note": "This command publicly accepts an ID-only Drive node; dentry spellings preserve the value and URL-specific spellings remain protected."}, "drive download": {"scoped_aliases": {"dentry-uuid": "node", "chunk-size": "part-size", "concurrency": "parallel", "parallelism": "parallel"}, "block": ["dentry-id", "document-url", "file", "file-path", "folder", "folder-id", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "Output path, chunk size, and concurrency names preserve values; local input and remote folder roles remain blocked."}, - "drive info": {"scoped_aliases": {"dentry-uuid": "node"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target; knowledge-base workspace spellings are a different value domain."}, + "drive info": {"scoped_aliases": {"dentry-uuid": "node", "space": "space-id", "workspace": "space-id", "workspace-id": "space-id"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id"], "scope_strict": true, "note": "This command has only a numeric DingDrive space target. Its command-scoped --space/--workspace/--workspace-id aliases preserve compatibility published before the workspace/storage-space concept split and pass the value unchanged to --space-id; new commands must not infer that knowledge-base workspace IDs and numeric storage-space IDs are globally interchangeable."}, "drive commit": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "upload-session-id": "upload-id", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "Upload session, file name, file size in bytes, parent folder, and storage space remain separate roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, "drive mkdir": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "folder-name": "name", "display-name": "name", "new-name": "name"}, "scope_strict": true, "note": "The name is this exact folder/node display name; search query and local path are different roles.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, "drive upload-info": {"scoped_aliases": {"directory-id": "folder", "parent-directory-id": "folder", "content-type": "mime-type", "size-bytes": "file-size", "name": "file-name", "display-name": "file-name", "filename": "file-name", "upload-name": "file-name"}, "scope_strict": true, "note": "File metadata aliases preserve MIME and byte units; file path and upload session are different stages.", "block": ["knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id"]}, @@ -313,7 +319,7 @@ {"command": "doc +export-get", "emitted": "node", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "doc block delete", "emitted": "index", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "doc block insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-multi-parameter-transform", "occ": 2}, - {"command": "drive info", "emitted": "workspace", "expect": "did-you-mean:blocked", "via": "guard:workspace-vs-numeric-storage-space", "occ": 2}, + {"command": "drive info", "emitted": "workspace", "expect": "space-id", "via": "override:published-storage-space-compatibility", "occ": 2}, {"command": "mail folder update", "emitted": "folder-id", "expect": "id", "via": "override:bind(folder_id)", "occ": 2}, {"command": "report outbox list", "emitted": "template-type", "expect": "did-you-mean:blocked", "via": "override:block", "occ": 2}, {"command": "chat +group-members", "emitted": "group-name", "expect": "group", "via": "concept:group_name+bind"}, @@ -503,7 +509,7 @@ {"command": "doc +copy", "emitted": "dentry-uuid", "expect": "node", "via": "concept:doc_node_id"}, {"command": "doc info", "emitted": "dentry-id", "expect": "did-you-mean:blocked", "via": "guard:dentry-id-vs-dentry-uuid"}, {"command": "doc create", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"}, - {"command": "doc create", "emitted": "space-id", "expect": "did-you-mean:blocked", "via": "guard:storage-space-vs-workspace"}, + {"command": "doc create", "emitted": "space-id", "expect": "workspace", "via": "override:published-workspace-compatibility"}, {"command": "drive list", "emitted": "knowledge-base-id", "expect": "workspace", "via": "concept:workspace_id"}, {"command": "drive list", "emitted": "order-field", "expect": "order-by", "via": "override:scoped-sort-field"}, {"command": "drive info", "emitted": "dentry-uuid", "expect": "node", "via": "override:scoped-node-id"}, From a55bd9bff8c5a1a44ffcc50ca0dcb93e35177f1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 20:52:50 +0800 Subject: [PATCH 031/250] fix(chat): complete pending id flag migrations --- internal/corecmd/corecmd.go | 37 ++++-- internal/helpers/chat.go | 110 ++++++++++++------ internal/helpers/chat_message_help_test.go | 49 +++++++- .../approved-flag-migrations-v1.json | 62 +++++----- 4 files changed, 178 insertions(+), 80 deletions(-) diff --git a/internal/corecmd/corecmd.go b/internal/corecmd/corecmd.go index 9e61c886..5d0fbe59 100644 --- a/internal/corecmd/corecmd.go +++ b/internal/corecmd/corecmd.go @@ -578,18 +578,7 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) { for _, alias := range flag.Aliases { RegisterFlag(cmd, flag.Kind, alias, "", flag.Usage+" (alias)") _ = cmd.Flags().MarkHidden(alias) - if registered := cmd.Flags().Lookup(alias); registered != nil { - runtimeannotate.SetFlagAnnotation( - registered, - runtimeannotate.AnnotationFlagAliasOf, - flag.Name, - ) - runtimeannotate.SetFlagAnnotation( - registered, - runtimeannotate.AnnotationFlagAliasOrigin, - runtimeannotate.FlagAliasOriginCorecmdV1, - ) - } + AnnotateFlagAlias(cmd, alias, flag.Name) } if flag.MarkRequired { _ = cmd.MarkFlagRequired(flag.Name) @@ -600,6 +589,30 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) { } } +// AnnotateFlagAlias records framework-owned evidence that aliasName is a hidden +// compatibility alias for canonicalName. It is for commands that already own +// their Cobra flag registration outside FlagSpec but still need the same +// interface-snapshot alias contract as FlagSpec.Aliases. +func AnnotateFlagAlias(cmd *cobra.Command, aliasName, canonicalName string) { + if cmd == nil { + return + } + registered := cmd.Flags().Lookup(aliasName) + if registered == nil { + return + } + runtimeannotate.SetFlagAnnotation( + registered, + runtimeannotate.AnnotationFlagAliasOf, + canonicalName, + ) + runtimeannotate.SetFlagAnnotation( + registered, + runtimeannotate.AnnotationFlagAliasOrigin, + runtimeannotate.FlagAliasOriginCorecmdV1, + ) +} + // RegisterFlag registers one flag by Kind. Default is applied at registration // for every kind so --help DefValue matches the declared fallback. // Malformed KindInt / KindBool Default values panic at registration (fail-closed) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 2fb5ca50..ce76621c 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -248,19 +248,79 @@ func installChatIMIDFlagAliases(root *cobra.Command) { } } visit(root) - restoreChatAuditJoinValidationCanonicalRequired(root) + restoreChatGroupBotsLegacyRequired(root) + restoreChatPendingMigrationCanonicalRequired(root) } -func restoreChatAuditJoinValidationCanonicalRequired(root *cobra.Command) { +func restoreChatGroupBotsLegacyRequired(root *cobra.Command) { if root == nil { return } - cmd, _, err := root.Find([]string{"group", "audit-join-validation"}) + cmd, _, err := root.Find([]string{"group", "bots"}) if err != nil || cmd == nil { return } - _ = cmd.MarkFlagRequired("conversation-id") - clearChatAliasRequiredAnnotations(cmd, "group") + _ = cmd.MarkFlagRequired("group") +} + +func restoreChatPendingMigrationCanonicalRequired(root *cobra.Command) { + if root == nil { + return + } + for _, path := range chatPendingConversationIDMigrationPaths { + cmd, _, err := root.Find(path) + if err != nil || cmd == nil { + continue + } + _ = cmd.MarkFlagRequired("conversation-id") + clearChatAliasRequiredAnnotations(cmd, "group", "id", "chat", "open-conversation-id") + } + for _, path := range chatPendingMessageIDMigrationPaths { + cmd, _, err := root.Find(path) + if err != nil || cmd == nil { + continue + } + _ = cmd.MarkFlagRequired("message-id") + clearChatAliasRequiredAnnotations(cmd, "msg-id", "open-message-id") + } +} + +var chatPendingConversationIDMigrationPaths = [][]string{ + {"group", "audit-join-validation"}, + {"group", "dismiss"}, + {"group", "invite-url"}, + {"group", "notice", "create"}, + {"group", "notice", "edit"}, + {"group", "notice", "get"}, + {"group", "notice", "list"}, + {"group", "quit"}, + {"group", "set-admin"}, + {"group", "set-history"}, + {"group", "transfer-owner"}, + {"group", "update-alias"}, + {"group", "update-icon"}, + {"group", "update-nick"}, + {"group", "update-settings"}, + {"group", "upgrade-to-external"}, + {"group-role", "add"}, + {"group-role", "list"}, + {"group-role", "query-user"}, + {"group-role", "remove-user"}, + {"group-role", "remove"}, + {"group-role", "set-user"}, + {"group-role", "update"}, + {"message", "list-topic-replies"}, +} + +var chatPendingMessageIDMigrationPaths = [][]string{ + {"message", "edit"}, + {"message", "forward"}, + {"message", "recall"}, + {"message", "set-pin-msg"}, + {"message", "set-top-msg"}, + {"message", "unset-pin-msg"}, + {"message", "unset-top-msg"}, + {"message", "update-text-emotion"}, } func clearChatAliasRequiredAnnotations(cmd *cobra.Command, aliases ...string) { @@ -289,10 +349,12 @@ func installChatFlagAliases(cmd *cobra.Command, primary string, aliases []string delete(aliasFlag.Annotations, cobra.BashCompOneRequiredFlag) } _ = flags.MarkHidden(alias) + corecmd.AnnotateFlagAlias(cmd, alias, primary) continue } flags.String(alias, "", "--"+primary+" 的兼容别名") _ = flags.MarkHidden(alias) + corecmd.AnnotateFlagAlias(cmd, alias, primary) } required, ok := flag.Annotations[cobra.BashCompOneRequiredFlag] wasRequired := flag.Annotations != nil && ok && len(required) > 0 && required[0] == "true" @@ -7542,31 +7604,16 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Use: "bots", Short: "查看群内所有机器人", Long: `获取指定群聊中的所有机器人列表。`, - Example: ` dws chat group bots --conversation-id - dws chat group bots --group-name "项目群" + Example: ` dws chat group bots --group # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - conversationID, err := chatFlagOrAlias(cmd, "conversation-id", "id", "chat", "open-conversation-id") - if err != nil { + if err := validateRequiredFlags(cmd, "group"); err != nil { return err } - groupName, err := chatFlagOrAlias(cmd, "group-name", "group") + groupID, err := resolveNativeChatTarget(mustGetFlag(cmd, "group")) if err != nil { return err } - if conversationID == "" && groupName == "" { - return validateRequiredFlagWithAliases(cmd, "conversation-id", "group-name", "group", "id", "chat", "open-conversation-id") - } - if conversationID != "" && groupName != "" { - return fmt.Errorf("--conversation-id and --group-name are mutually exclusive") - } - groupID := conversationID - if groupName != "" { - groupID, err = resolveNativeChatTarget(groupName) - if err != nil { - return err - } - } return callMCPToolOnServer("bot", "list_group_bots", map[string]any{ "openConversationId": groupID, }) @@ -7595,22 +7642,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "列出群内机器人", UseWhen: []string{"需要查看某群已安装哪些机器人或提取 openBotId"}, AvoidWhen: []string{"搜索企业内机器人目录时使用 chat bot find"}, - Examples: []string{"dws chat group bots --conversation-id ", "dws chat group bots --group-name \"项目群\""}, + Examples: []string{"dws chat group bots --group "}, }, Parameters: []contract.ParamDecl{ - {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "群聊 openConversationId"}, - {Name: "group-name", Property: "groupName", Required: boolPtr(false), Description: "需唯一解析的群名称"}, + {Name: "group", Property: "openConversationId"}, }, }, }) - chatGroupBotsCmd.Flags().String("conversation-id", "", "群聊 openConversationId") - chatGroupBotsCmd.Flags().String("group-name", "", "需唯一解析的群名称") - chatGroupBotsCmd.Flags().String("group", "", "--group-name 的兼容别名") - _ = chatGroupBotsCmd.Flags().MarkHidden("group") - cli.AnnotateRuntimeConstraints(chatGroupBotsCmd, cli.RuntimeSchemaConstraints{ - MutuallyExclusive: [][]string{{"conversation-id", "group-name"}}, - RequireOneOf: [][]string{{"conversation-id", "group-name"}}, - }) + chatGroupBotsCmd.Flags().String("group", "", "群聊 openConversationId 或需唯一解析的群名 (必填)") + _ = chatGroupBotsCmd.MarkFlagRequired("group") chatGroupMembersRemoveBotCmd := &cobra.Command{ Use: "remove-bot", @@ -7618,7 +7658,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Long: `将指定机器人从群聊中移除。需要群管理员或群主权限。`, Example: ` dws chat group members remove-bot --id --bot-id # 查询群 ID: dws chat search --query "群名" - # 查询群内机器人: dws chat group bots --conversation-id `, + # 查询群内机器人: dws chat group bots --group `, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlags(cmd, "id", "bot-id"); err != nil { return err diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 0781dbab..4c7323ac 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -48,10 +48,55 @@ func TestCrossPlatformCoverageChatGroupAuditJoinValidationAliasContract(t *testi } func TestCrossPlatformCoverageChatGroupAuditJoinValidationRestoreRequiredNoop(t *testing.T) { - restoreChatAuditJoinValidationCanonicalRequired(nil) + restoreChatGroupBotsLegacyRequired(nil) + restoreChatPendingMigrationCanonicalRequired(nil) root := &cobra.Command{Use: "chat"} root.AddCommand(&cobra.Command{Use: "other"}) - restoreChatAuditJoinValidationCanonicalRequired(root) + restoreChatGroupBotsLegacyRequired(root) + restoreChatPendingMigrationCanonicalRequired(root) +} + +func TestCrossPlatformCoverageChatGroupBotsKeepsLegacyGroupFlag(t *testing.T) { + cmd := newChatCommand() + leaf, _, err := cmd.Find([]string{"group", "bots"}) + if err != nil { + t.Fatal(err) + } + group := leaf.Flags().Lookup("group") + if group == nil || group.Hidden { + t.Fatalf("group flag = %#v, want visible legacy flag", group) + } + if got := group.Annotations[cobra.BashCompOneRequiredFlag]; len(got) == 0 || got[0] != "true" { + t.Fatalf("group required annotation = %#v, want true", got) + } + if leaf.Flags().Lookup("conversation-id") != nil { + t.Fatalf("chat group bots still exposes migrated --conversation-id") + } + if leaf.Flags().Lookup("group-name") != nil { + t.Fatalf("chat group bots still exposes migrated --group-name") + } +} + +func TestCrossPlatformCoverageChatPendingMigrationAliasesMatchManifest(t *testing.T) { + cmd := newChatCommand() + leaf, _, err := cmd.Find([]string{"group", "dismiss"}) + if err != nil { + t.Fatal(err) + } + canonical := leaf.Flags().Lookup("conversation-id") + if canonical == nil { + t.Fatal("missing conversation-id flag") + } + if got := canonical.Annotations[cobra.BashCompOneRequiredFlag]; len(got) == 0 || got[0] != "true" { + t.Fatalf("conversation-id required annotation = %#v, want true", got) + } + legacy := leaf.Flags().Lookup("group") + if legacy == nil || !legacy.Hidden { + t.Fatalf("group flag = %#v, want hidden legacy alias", legacy) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "conversation-id" { + t.Fatalf("group alias_of annotation = %#v", got) + } } func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing.T) { diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index 49753948..576bdaff 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -97,7 +97,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -130,7 +130,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -163,7 +163,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -196,7 +196,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -229,7 +229,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -262,7 +262,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -295,7 +295,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -328,7 +328,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -361,7 +361,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -394,7 +394,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -427,7 +427,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -460,7 +460,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -493,7 +493,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -526,7 +526,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -559,7 +559,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -592,7 +592,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -625,7 +625,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -658,7 +658,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -691,7 +691,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -724,7 +724,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -757,7 +757,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -790,7 +790,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -823,7 +823,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -856,7 +856,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -892,7 +892,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -925,7 +925,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -958,7 +958,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -991,7 +991,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -1024,7 +1024,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -1057,7 +1057,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { @@ -1090,7 +1090,7 @@ "required": true } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, { From 6a4744073c2d760f99a6496d6ce1c9304f93e5bd Mon Sep 17 00:00:00 2001 From: fengbai Date: Wed, 12 Aug 2026 21:07:59 +0800 Subject: [PATCH 032/250] feat(calendar): add event share-info command --- .changes/calendar-event-share-info.md | 5 ++ internal/helpers/calendar.go | 84 ++++++++++++++++++- skills/mono/references/products/calendar.md | 21 +++++ .../dingtalk-calendar/references/calendar.md | 21 +++++ 4 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 .changes/calendar-event-share-info.md diff --git a/.changes/calendar-event-share-info.md b/.changes/calendar-event-share-info.md new file mode 100644 index 00000000..2ec9f1fa --- /dev/null +++ b/.changes/calendar-event-share-info.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **Calendar event share-info** — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`. diff --git a/internal/helpers/calendar.go b/internal/helpers/calendar.go index 71eb3c6a..71d872f6 100644 --- a/internal/helpers/calendar.go +++ b/internal/helpers/calendar.go @@ -230,7 +230,7 @@ func newCalendarCommand() *cobra.Command { Long: `管理钉钉日历：日程、参会人、会议室、闲忙、附件、日历本、访问权限。调用前必须先使用 --help 查看参数结构。 命令结构: - dws calendar event [list|get|create|update|delete|suggest|respond|instances] 日程管理 + dws calendar event [list|get|create|update|delete|suggest|respond|instances|share-info] 日程管理 dws calendar attendee [list|add|delete] 参会人管理 dws calendar room [search|add|delete|list-groups] 会议室管理 dws calendar busy search 闲忙查询 (可查人、查会议室) @@ -2259,7 +2259,87 @@ func newCalendarCommand() *cobra.Command { eventInstancesCmd.Flags().Int("count", 0, "") _ = eventInstancesCmd.Flags().MarkHidden("count") - eventCmd.AddCommand(eventListCmd, eventGetCmd, eventCreateCmd, eventUpdateCmd, eventDeleteCmd, eventSuggestCmd, eventRespondCmd, eventInstancesCmd) + eventShareInfoCmd := &cobra.Command{ + Use: "share-info", + Aliases: []string{"share_info"}, + Short: "获取日程的分享信息", + Long: `根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程。`, + Example: ` dws calendar event share-info --id EVENT_ID # 查询 eventId: dws calendar event list + dws calendar event share-info --id EVENT_ID --language zh-CN + dws calendar event share-info --id EVENT_ID --calendar-id primary`, + RunE: func(cmd *cobra.Command, args []string) error { + eventID, err := mustFlagOrFallback(cmd, "id", "event", "event-id", "eventId") + if err != nil { + return err + } + toolArgs := map[string]any{"eventId": eventID} + if v := flagOrFallback(cmd, "calendar-id", "calendarId", "calendar"); v != "" { + toolArgs["calendarId"] = v + } + if v := flagOrFallback(cmd, "language", "lang"); v != "" { + toolArgs["language"] = v + } + return callMCPTool("get_event_share_info", toolArgs) + }, + } + DeclareLeafMetadata(eventShareInfoCmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "calendar", + Name: "get_event_share_info", + CanonicalPath: "calendar.get_event_share_info", + CLIPath: "calendar event share-info", + PrimaryCLIPath: "calendar event share-info", + Aliases: []string{"calendar event share_info"}, + }, + Description: "获取日程的分享信息", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "calendar", RPCName: "get_event_share_info"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "获取日程的分享信息（主题、组织人、地点、入会信息等）", + UseWhen: []string{"已知 eventId，需要获取日程分享信息或入会信息用于分享给他人时"}, + AvoidWhen: []string{ + "要查看日程详情改用 dws calendar event get", + "未知 eventId 时先 dws calendar event list", + }, + Examples: []string{ + "dws calendar event share-info --id ", + "dws calendar event share-info --id --language zh-CN", + }, + }, + Parameters: []contract.ParamDecl{ + {Name: "id", Property: "eventId", Required: boolPtr(true)}, + {Name: "calendar-id", Property: "calendarId"}, + {Name: "language", Property: "language"}, + }, + }, + }) + + // EventShareInfo flags + eventShareInfoCmd.Flags().String("id", "", "日程 ID (必填)") + eventShareInfoCmd.Flags().String("event", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("event") + eventShareInfoCmd.Flags().String("event-id", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("event-id") + eventShareInfoCmd.Flags().String("eventId", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("eventId") + eventShareInfoCmd.Flags().String("calendar-id", "", "日历 ID (默认 primary 主日历)") + eventShareInfoCmd.Flags().String("calendarId", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("calendarId") + eventShareInfoCmd.Flags().String("calendar", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("calendar") + eventShareInfoCmd.Flags().String("language", "", "语言代码 (可选，默认 en-US，如 zh-CN)") + eventShareInfoCmd.Flags().String("lang", "", "") + _ = eventShareInfoCmd.Flags().MarkHidden("lang") + + eventCmd.AddCommand(eventListCmd, eventGetCmd, eventCreateCmd, eventUpdateCmd, eventDeleteCmd, eventSuggestCmd, eventRespondCmd, eventInstancesCmd, eventShareInfoCmd) // participant participantCmd.PersistentFlags().String("event", "", "日程 ID (必填)") diff --git a/skills/mono/references/products/calendar.md b/skills/mono/references/products/calendar.md index 70b3d2bc..4711854b 100644 --- a/skills/mono/references/products/calendar.md +++ b/skills/mono/references/products/calendar.md @@ -44,6 +44,8 @@ dws calendar event [create|update|get|delete|respond] [flags] dws calendar event list [flags] # 查询循环日程的实例列表（按时间范围展开重复日程） dws calendar event instances [flags] +# 获取日程的分享信息（日程主题、组织人、地点、入会信息等，用于向他人分享日程） +dws calendar event share-info [flags] # 对于非明确时间或一段时间范围的约会场景，可基于所有参会人的忙闲状态，推荐多个可用的时间块方案 dws calendar event suggest [flags] ``` @@ -160,6 +162,22 @@ Flags: > **默认行为**：不传 `--start` / `--end` 时，默认返回今天的实例（00:00:00 ~ 23:59:59）。 > **分页**：单次最多返回 `--limit` 指定的条数（默认/最大 100）；当结果超过 limit 时，返回体包含 `nextCursor` 字段。 +### 获取日程分享信息 +``` +Usage: + dws calendar event share-info [flags] +Example: + dws calendar event share-info --id + dws calendar event share-info --id --language zh-CN + dws calendar event share-info --id --calendar-id primary +Flags: + --id string 日程 ID (必填) + --calendar-id string 日历 ID (可选，默认 primary 主日历) + --language string 语言代码 (可选，默认 en-US，如 zh-CN) +``` + +> **说明**：根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程（如发送到群聊、邮件）。中文内容建议传 `--language zh-CN`。 + ### 创建日程 ``` Usage: @@ -585,6 +603,7 @@ Flags: - 推荐时间/什么时候有空/协调时间 → `event suggest` - 接受/拒绝/暂定日程 → `event respond` - 查询循环日程/重复日程的每次实例/展开循环日程 → `event instances` +- 分享日程/把日程发给别人/获取日程分享信息或入会信息 → `event share-info` 用户说"参会人/与会者": - 查看 → `attendee list` @@ -691,6 +710,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 | `event suggest` | 推荐的时间段 | event create 的 --start/--end | | `event respond` | 响应结果 | — | | `event instances` | `result.events[].id`, `nextCursor` | event get/update/delete/respond 的 --id；下一页 --cursor | +| `event share-info` | 日程分享信息（主题、组织人、地点、入会信息等） | 分享给他人（如 chat/mail 发送） | | `room search` | `rooms[].roomId` | room add 的 --rooms 或 event create 的 --rooms | | `room list-groups` | `groups[].groupId` | room search 的 --group-id | | `book list` | `id`（如 `primary`） | event list/get 的 --calendar-id, book get/update 的 --id | @@ -718,6 +738,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 - **日历本**：`book list` 返回的 `id` 才是合法 `calendarId`；如无明确说明，`event list` / `event get` 都不要带 `--calendar-id`，让接口默认走 primary 主日历 - **分页查询**：`event list` / `event instances` 均支持 `--limit`（控制每页条数，默认/最大 100）和 `--cursor`（翻页游标）；**首次查询无需传 `--cursor`**，仅当返回体中包含 `nextCursor` 时，将其作为 `--cursor` 传入可获取下一页 - **循环日程实例**：`event instances` 用于按时间范围展开重复日程（SeriesMaster）的每一个实例；**普通非循环日程调用该命令将查不到任何实例信息** +- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（默认 en-US，中文场景传 zh-CN） - **日程提醒**：`event create` 支持 `--remind-minutes` 设置开始前提醒，逗号分隔多个分钟数（如 `--remind-minutes 5,10,15`），不传则默认15分钟提醒 - **会议室分页**：`room search` 支持 `--limit`（每页条数，默认100，最大100）和 `--page`（分页起始位置，默认0），与 `room list-groups` 分页风格一致 diff --git a/skills/multi/dingtalk-calendar/references/calendar.md b/skills/multi/dingtalk-calendar/references/calendar.md index 70b3d2bc..4711854b 100644 --- a/skills/multi/dingtalk-calendar/references/calendar.md +++ b/skills/multi/dingtalk-calendar/references/calendar.md @@ -44,6 +44,8 @@ dws calendar event [create|update|get|delete|respond] [flags] dws calendar event list [flags] # 查询循环日程的实例列表（按时间范围展开重复日程） dws calendar event instances [flags] +# 获取日程的分享信息（日程主题、组织人、地点、入会信息等，用于向他人分享日程） +dws calendar event share-info [flags] # 对于非明确时间或一段时间范围的约会场景，可基于所有参会人的忙闲状态，推荐多个可用的时间块方案 dws calendar event suggest [flags] ``` @@ -160,6 +162,22 @@ Flags: > **默认行为**：不传 `--start` / `--end` 时，默认返回今天的实例（00:00:00 ~ 23:59:59）。 > **分页**：单次最多返回 `--limit` 指定的条数（默认/最大 100）；当结果超过 limit 时，返回体包含 `nextCursor` 字段。 +### 获取日程分享信息 +``` +Usage: + dws calendar event share-info [flags] +Example: + dws calendar event share-info --id + dws calendar event share-info --id --language zh-CN + dws calendar event share-info --id --calendar-id primary +Flags: + --id string 日程 ID (必填) + --calendar-id string 日历 ID (可选，默认 primary 主日历) + --language string 语言代码 (可选，默认 en-US，如 zh-CN) +``` + +> **说明**：根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程（如发送到群聊、邮件）。中文内容建议传 `--language zh-CN`。 + ### 创建日程 ``` Usage: @@ -585,6 +603,7 @@ Flags: - 推荐时间/什么时候有空/协调时间 → `event suggest` - 接受/拒绝/暂定日程 → `event respond` - 查询循环日程/重复日程的每次实例/展开循环日程 → `event instances` +- 分享日程/把日程发给别人/获取日程分享信息或入会信息 → `event share-info` 用户说"参会人/与会者": - 查看 → `attendee list` @@ -691,6 +710,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 | `event suggest` | 推荐的时间段 | event create 的 --start/--end | | `event respond` | 响应结果 | — | | `event instances` | `result.events[].id`, `nextCursor` | event get/update/delete/respond 的 --id；下一页 --cursor | +| `event share-info` | 日程分享信息（主题、组织人、地点、入会信息等） | 分享给他人（如 chat/mail 发送） | | `room search` | `rooms[].roomId` | room add 的 --rooms 或 event create 的 --rooms | | `room list-groups` | `groups[].groupId` | room search 的 --group-id | | `book list` | `id`（如 `primary`） | event list/get 的 --calendar-id, book get/update 的 --id | @@ -718,6 +738,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 - **日历本**：`book list` 返回的 `id` 才是合法 `calendarId`；如无明确说明，`event list` / `event get` 都不要带 `--calendar-id`，让接口默认走 primary 主日历 - **分页查询**：`event list` / `event instances` 均支持 `--limit`（控制每页条数，默认/最大 100）和 `--cursor`（翻页游标）；**首次查询无需传 `--cursor`**，仅当返回体中包含 `nextCursor` 时，将其作为 `--cursor` 传入可获取下一页 - **循环日程实例**：`event instances` 用于按时间范围展开重复日程（SeriesMaster）的每一个实例；**普通非循环日程调用该命令将查不到任何实例信息** +- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（默认 en-US，中文场景传 zh-CN） - **日程提醒**：`event create` 支持 `--remind-minutes` 设置开始前提醒，逗号分隔多个分钟数（如 `--remind-minutes 5,10,15`），不传则默认15分钟提醒 - **会议室分页**：`room search` 支持 `--limit`（每页条数，默认100，最大100）和 `--page`（分页起始位置，默认0），与 `room list-groups` 分页风格一致 From 8aee08268d38a8fc7bc8d5038ec0dfb12bde278d Mon Sep 17 00:00:00 2001 From: fengbai Date: Wed, 12 Aug 2026 21:17:32 +0800 Subject: [PATCH 033/250] test(calendar): add event share-info dry-run and required-flag tests --- internal/app/root_help_test.go | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index eb370a7b..31949cd3 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -403,6 +403,35 @@ func TestCalendarEventListDryRunPreviewsOnly(t *testing.T) { } } +func TestCalendarEventShareInfoDryRunPreviewsOnly(t *testing.T) { + got, err := executeRootCaptureStdout(t, []string{ + "--dry-run", "calendar", "event", "share-info", + "--id", "EVT_001", + "--language", "zh-CN", + "--calendar-id", "primary", + }) + if err != nil { + t.Fatalf("calendar event share-info --dry-run error = %v\n%s", err, got) + } + for _, want := range []string{"get_event_share_info", "eventId", "EVT_001", "zh-CN", "primary"} { + if !strings.Contains(got, want) { + t.Fatalf("calendar event share-info dry-run output missing %q:\n%s", want, got) + } + } +} + +func TestCalendarEventShareInfoRequiresEventID(t *testing.T) { + got, err := executeRootCaptureStdout(t, []string{ + "--dry-run", "calendar", "event", "share-info", + }) + if err == nil { + t.Fatalf("calendar event share-info without --id: expected error, got nil\n%s", got) + } + if strings.Contains(got, "\"executed\": true") { + t.Fatalf("share-info without --id must not execute:\n%s", got) + } +} + func TestRootKeepsSVIPChatCompatibilityFlags(t *testing.T) { root := NewRootCommand() From ae6d9aa16db21e977cedcbab1ec00703084d68fc Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 22:04:57 +0800 Subject: [PATCH 034/250] fix(drive): reject push path type conflicts Check opposite-type remote entries before dry-run planning or actual writes, and cover both file-folder conflict directions. --- internal/helpers/drive_push.go | 35 ++++++ .../helpers/drive_push_type_conflict_test.go | 108 ++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 internal/helpers/drive_push_type_conflict_test.go diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index 741fa7eb..d1d10ec2 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -126,6 +126,11 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { // 第一阶段：按需创建远端目录（浅层在前，保证父目录先于子目录存在）。 for _, dir := range localDirs { + if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg}) + continue + } if _, ok := remoteFolders[dir]; ok { continue // 远端已存在，复用 fileId，不留痕 } @@ -154,6 +159,11 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { for i := range localFiles { lf := localFiles[i] size := lf.Size + if msg := pushTypeConflictError(lf.RelPath, false, remoteFiles, remoteFolders); msg != "" { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: msg}) + continue + } parentRel, name := splitRel(lf.RelPath) parentID, ok := remoteFolders[parentRel] if !ok || parentID == "" { @@ -294,6 +304,11 @@ func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, r plannedFolders[rel] = fileID } for _, dir := range localDirs { + if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg}) + continue + } if _, ok := plannedFolders[dir]; ok { continue } @@ -308,6 +323,11 @@ func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, r } for _, lf := range localFiles { size := lf.Size + if msg := pushTypeConflictError(lf.RelPath, false, remoteFiles, remoteFolders); msg != "" { + plan.Summary.Failed++ + plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: msg}) + continue + } parentRel, _ := splitRel(lf.RelPath) if plannedFolders[parentRel] == "" { plan.Summary.Failed++ @@ -342,6 +362,21 @@ func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, r }) } +// pushTypeConflictError 在任何写操作或 dry-run 成功预览之前，拒绝同一路径下 +// “本地目录 ↔ 远端文件”或“本地文件 ↔ 远端目录”的类型冲突。 +func pushTypeConflictError(rel string, localIsFolder bool, remoteFiles map[string]*remoteFile, remoteFolders map[string]string) string { + if localIsFolder { + if _, exists := remoteFiles[rel]; exists { + return "远端同路径已存在文件，无法创建目录" + } + return "" + } + if _, exists := remoteFolders[rel]; exists { + return "远端同路径已存在目录，无法上传文件" + } + return "" +} + // walkLocalForPush 遍历本地根目录，返回所有子目录 rel_path（不含根本身，浅层在前） // 与所有常规文件。dirs 升序排序保证父目录先于子目录被创建。 func walkLocalForPush(root string) ([]string, []localPushFile, error) { diff --git a/internal/helpers/drive_push_type_conflict_test.go b/internal/helpers/drive_push_type_conflict_test.go new file mode 100644 index 00000000..e6e294fb --- /dev/null +++ b/internal/helpers/drive_push_type_conflict_test.go @@ -0,0 +1,108 @@ +package helpers + +import ( + "bytes" + "encoding/json" + "errors" + "os" + "path/filepath" + "testing" +) + +func TestCrossPlatformCoverageDrivePushDryRun_typeConflictsFail(t *testing.T) { + var out bytes.Buffer + prevDeps := deps + deps = &Deps{Out: &Formatter{w: &out}} + t.Cleanup(func() { deps = prevDeps }) + + tests := []struct { + name string + remoteFiles map[string]*remoteFile + remoteFolders map[string]string + localDirs []string + localFiles []localPushFile + }{ + { + name: "remote file conflicts with local folder", + remoteFiles: map[string]*remoteFile{"conflict": {RelPath: "conflict", FileID: "REMOTE_FILE"}}, + remoteFolders: map[string]string{"": "ROOT"}, + localDirs: []string{"conflict"}, + }, + { + name: "remote folder conflicts with local file", + remoteFiles: map[string]*remoteFile{}, + remoteFolders: map[string]string{"": "ROOT", "conflict": "REMOTE_FOLDER"}, + localFiles: []localPushFile{{RelPath: "conflict", Size: 1}}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + out.Reset() + if err := printDrivePushDryRun(ifExistsSkip, tt.remoteFiles, tt.remoteFolders, tt.localDirs, tt.localFiles); err != nil { + t.Fatalf("printDrivePushDryRun: %v", err) + } + + var got drivePushDryRunResult + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("decode dry-run result: %v\n%s", err, out.String()) + } + if got.Plan.Summary.Failed != 1 || got.Plan.Summary.Uploaded != 0 { + t.Fatalf("summary = %+v, want failed=1 uploaded=0", got.Plan.Summary) + } + if len(got.Plan.Items) != 1 || got.Plan.Items[0].Action != pushActionFailed || got.Plan.Items[0].Error == "" { + t.Fatalf("items = %+v, want one failed item with an error", got.Plan.Items) + } + }) + } +} + +func TestCrossPlatformCoverageDrivePush_typeConflictsFailBeforeWrites(t *testing.T) { + tests := []struct { + name string + prepare func(*testing.T, string) + remoteItem string + }{ + { + name: "remote file conflicts with local folder", + prepare: func(t *testing.T, root string) { + t.Helper() + if err := os.Mkdir(filepath.Join(root, "conflict"), 0o755); err != nil { + t.Fatal(err) + } + }, + remoteItem: `{"name":"conflict","type":"file","fileId":"REMOTE_FILE"}`, + }, + { + name: "remote folder conflicts with local file", + prepare: func(t *testing.T, root string) { + t.Helper() + mustWrite(t, filepath.Join(root, "conflict"), "local") + }, + remoteItem: `{"name":"conflict","type":"folder","fileId":"REMOTE_FOLDER"}`, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + root := t.TempDir() + tt.prepare(t, root) + withNoopPut(t) + + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[` + tt.remoteItem + `],"nextToken":""}}`, + }) + err := runDriveCmd(t, caller, "push", "--local-folder", root, "--remote-folder", "ROOT") + var failure *drivePushFailure + if !errors.As(err, &failure) || failure.failed != 1 { + t.Fatalf("error = %T %v, want drivePushFailure(failed=1)", err, err) + } + if calls := caller.callsFor("create_folder"); len(calls) != 0 { + t.Fatalf("type conflict must not create folders, got %v", calls) + } + if calls := caller.callsFor("get_upload_info"); len(calls) != 0 { + t.Fatalf("type conflict must not upload, got %v", calls) + } + }) + } +} From 657f9ee3684a4a35a1dc5fb12d49829593f46306 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 22:29:22 +0800 Subject: [PATCH 035/250] ci(test): extend app race shard timeout --- .github/workflows/ci.yml | 4 ++-- test/scripts/changelog_pr_gate_test.go | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eace8f78..2815611e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -531,10 +531,10 @@ jobs: test -n "$package_output" mapfile -t packages <<< "$package_output" test "${#packages[@]}" -gt 0 - # cli/smoke own heavy NewRootCommand / Schema assembly under -race; give + # app/cli/smoke own heavy NewRootCommand / Schema assembly under -race; give # them a dedicated budget so remaining is not SIGTERM'd by OOM/timeout. timeout_budget=12m - if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then + if [ "$TEST_SHARD" = "app" ] || [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then timeout_budget=15m fi go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}" diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index bf05855b..0a24168d 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -1154,10 +1154,10 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { } raceJob := admission[raceStart:raceEnd] // Full race shards use a dynamic package-level timeout: default/floor 12m, - // with cli/smoke raised to 15m for NewRootCommand / Schema assembly under -race. + // with app/cli/smoke raised to 15m for NewRootCommand / Schema assembly under -race. for _, want := range []string{ "timeout_budget=12m", - `if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then`, + `if [ "$TEST_SHARD" = "app" ] || [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then`, "timeout_budget=15m", `go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"`, "- smoke", From 18c8e8390c41f7bfdda28f1432377b521f406eda Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 22:30:09 +0800 Subject: [PATCH 036/250] fix(drive): reject duplicate remote paths Reserve each remote file or folder rel_path exactly once so pagination and traversal order cannot silently discard mirror entries. --- internal/helpers/drive_push.go | 13 ++- .../helpers/drive_remote_duplicate_test.go | 86 +++++++++++++++++++ internal/helpers/drive_status.go | 29 +++++-- 3 files changed, 119 insertions(+), 9 deletions(-) create mode 100644 internal/helpers/drive_remote_duplicate_test.go diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index d1d10ec2..42cf2242 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -223,13 +223,14 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { func fetchRemoteTreeForPush(ctx context.Context, spaceID, rootID string) (map[string]*remoteFile, map[string]string, error) { files := make(map[string]*remoteFile) folders := map[string]string{"": rootID} - if err := walkRemoteForPush(ctx, spaceID, rootID, "", files, folders, 0); err != nil { + occupied := make(map[string]string) + if err := walkRemoteForPush(ctx, spaceID, rootID, "", files, folders, occupied, 0); err != nil { return nil, nil, err } return files, folders, nil } -func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, files map[string]*remoteFile, folders map[string]string, depth int) error { +func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, files map[string]*remoteFile, folders map[string]string, occupied map[string]string, depth int) error { if depth > remoteMaxDepth { return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth) } @@ -270,8 +271,11 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f childRel = relBase + "/" + name } if it.isFolder() { + if err := claimRemotePath(occupied, childRel, "目录"); err != nil { + return err + } folders[childRel] = it.id() - if err := walkRemoteForPush(ctx, spaceID, it.id(), childRel, files, folders, depth+1); err != nil { + if err := walkRemoteForPush(ctx, spaceID, it.id(), childRel, files, folders, occupied, depth+1); err != nil { return err } continue @@ -279,6 +283,9 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f if !it.isFile() { continue } + if err := claimRemotePath(occupied, childRel, "文件"); err != nil { + return err + } modMillis, modValid := it.modifiedMillis() files[childRel] = &remoteFile{ RelPath: childRel, diff --git a/internal/helpers/drive_remote_duplicate_test.go b/internal/helpers/drive_remote_duplicate_test.go new file mode 100644 index 00000000..d8b25830 --- /dev/null +++ b/internal/helpers/drive_remote_duplicate_test.go @@ -0,0 +1,86 @@ +package helpers + +import ( + "context" + "io" + "os" + "strings" + "testing" +) + +func TestCrossPlatformCoverageDriveRemoteTree_duplicatePathsFail(t *testing.T) { + tests := []struct { + name string + reply func(string, map[string]any, int) (string, error) + path string + }{ + { + name: "same file path across pages", + path: "duplicate.txt", + reply: func(_ string, args map[string]any, _ int) (string, error) { + if _, ok := args["nextToken"]; !ok { + return `{"result":{"items":[{"name":"duplicate.txt","type":"file","fileId":"F1"}],"nextToken":"PAGE2"}}`, nil + } + return `{"result":{"items":[{"name":"duplicate.txt","type":"file","fileId":"F2"}],"nextToken":""}}`, nil + }, + }, + { + name: "same folder path with duplicate descendants", + path: "duplicate", + reply: func(_ string, args map[string]any, _ int) (string, error) { + switch args["parentId"] { + case "ROOT": + return `{"result":{"items":[` + + `{"name":"duplicate","type":"folder","fileId":"D1"},` + + `{"name":"duplicate","type":"folder","fileId":"D2"}` + + `],"nextToken":""}}`, nil + case "D1": + return `{"result":{"items":[{"name":"child.txt","type":"file","fileId":"C1"}],"nextToken":""}}`, nil + case "D2": + return `{"result":{"items":[{"name":"child.txt","type":"file","fileId":"C2"}],"nextToken":""}}`, nil + default: + return `{"result":{"items":[],"nextToken":""}}`, nil + } + }, + }, + } + + fetchers := []struct { + name string + fetch func(context.Context) error + }{ + { + name: "status and pull tree", + fetch: func(ctx context.Context) error { + _, err := fetchRemoteDriveTree(ctx, "", "ROOT", true) + return err + }, + }, + { + name: "push and sync tree", + fetch: func(ctx context.Context) error { + _, _, err := fetchRemoteTreeForPush(ctx, "", "ROOT") + return err + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + for _, fetcher := range fetchers { + t.Run(fetcher.name, func(t *testing.T) { + caller := &driveScriptCaller{reply: tt.reply} + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + err := fetcher.fetch(context.Background()) + if err == nil || !strings.Contains(err.Error(), "重复远端路径") || !strings.Contains(err.Error(), tt.path) { + t.Fatalf("error = %v, want duplicate remote path %q", err, tt.path) + } + }) + } + }) + } +} diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index b62afa8b..1da6b41b 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -91,17 +91,18 @@ const remoteMaxDepth = 64 // - 只纳入明确 type=FILE 的条目，其余类型（在线文档、快捷方式等）一律跳过。 func fetchRemoteDriveTree(ctx context.Context, spaceID, parentID string, quick bool) (map[string]*remoteFile, error) { out := make(map[string]*remoteFile) - if err := walkRemoteDir(ctx, spaceID, parentID, "", out, 0); err != nil { + occupied := make(map[string]string) + if err := walkRemoteDir(ctx, spaceID, parentID, "", out, occupied, 0); err != nil { return nil, err } _ = quick // hash 与 modified_time 都会被填充，比对模式由 compareTrees 决定 return out, nil } -// walkRemoteDir 遍历 parentID 指向的文件夹，把其中的二进制文件写入 out（key 为 rel_path， -// 同名后者覆盖），并递归进入子文件夹。relBase 是当前文件夹相对遍历起点的路径前缀， -// 用于拼接子项的 rel_path。 -func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out map[string]*remoteFile, depth int) error { +// walkRemoteDir 遍历 parentID 指向的文件夹，把其中的二进制文件写入 out（key 为 rel_path）， +// 并递归进入子文件夹。occupied 同时记录文件和目录；精确路径被第二个条目占用时立即失败， +// 防止分页或返回顺序决定最终镜像。relBase 是当前文件夹相对遍历起点的路径前缀。 +func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out map[string]*remoteFile, occupied map[string]string, depth int) error { if depth > remoteMaxDepth { return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth) } @@ -149,8 +150,11 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m } if it.isFolder() { + if err := claimRemotePath(occupied, childRel, "目录"); err != nil { + return err + } // 用子文件夹的 dentryUuid 作为下一层 parentId 递归进入。 - if err := walkRemoteDir(ctx, spaceID, it.id(), childRel, out, depth+1); err != nil { + if err := walkRemoteDir(ctx, spaceID, it.id(), childRel, out, occupied, depth+1); err != nil { return err } continue @@ -159,6 +163,9 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m if !it.isFile() { continue } + if err := claimRemotePath(occupied, childRel, "文件"); err != nil { + return err + } modMillis, modValid := it.modifiedMillis() out[childRel] = &remoteFile{ @@ -180,6 +187,16 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m return nil } +// claimRemotePath 保证一棵远端树中的每个精确 rel_path 只对应一个文件或目录。 +// 重复条目会让本地镜像不可完整表达，因此必须失败，不能任意选择其中一个 fileId。 +func claimRemotePath(occupied map[string]string, rel, kind string) error { + if previous, exists := occupied[rel]; exists { + return fmt.Errorf("检测到重复远端路径 %q（已有%s，重复%s），无法构建确定性镜像", rel, previous, kind) + } + occupied[rel] = kind + return nil +} + // callDriveListFiles 让文件夹同步族在 --dry-run 下仍可通过受控只读通道获取 // 远端现状；普通 CallTool 在 dry-run 下只会返回执行计划，不能被当作业务数据解析。 func callDriveListFiles(ctx context.Context, args map[string]any) (string, error) { From 6bf78f1783f20fed1b45cd733cd406e9d25b4e3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 12 Aug 2026 22:46:05 +0800 Subject: [PATCH 037/250] test(ci): isolate app race partitions --- .github/workflows/ci.yml | 19 ++-- internal/app/pat_auth_retry_test.go | 11 ++ internal/app/testmain_test.go | 4 + scripts/ci/run-app-race-tests.sh | 126 ++++++++++++++++++++++ test/scripts/changelog_pr_gate_test.go | 13 ++- test/scripts/ci_test_package_plan_test.go | 19 ++++ 6 files changed, 181 insertions(+), 11 deletions(-) create mode 100755 scripts/ci/run-app-race-tests.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4707eb50..cff2c0dd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -501,7 +501,8 @@ jobs: needs: lint if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }} runs-on: ubuntu-latest - # cli/smoke shards need headroom beyond go test -timeout for setup + assembly. + # app runs several independently bounded processes; cli/smoke need headroom + # beyond go test -timeout for setup + assembly. timeout-minutes: 20 strategy: fail-fast: false @@ -537,12 +538,18 @@ jobs: test -n "$package_output" mapfile -t packages <<< "$package_output" test "${#packages[@]}" -gt 0 - # app/cli/smoke own heavy NewRootCommand / Schema assembly under - # -race; give them a dedicated budget so slower hosted runners do not - # hit the package timeout while the shards remain independently bounded. + if [ "$TEST_SHARD" = "app" ]; then + # A single long-lived app test process retains every constructed + # command tree in framework registries. Isolate Schema assembly and + # bounded name ranges so each process releases that state on exit. + test "${#packages[@]}" -eq 1 + ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" + exit 0 + fi + # cli/smoke own heavy NewRootCommand / Schema assembly under -race; + # give them a dedicated package timeout on slower hosted runners. timeout_budget=12m - if [ "$TEST_SHARD" = "app" ] || - [ "$TEST_SHARD" = "cli" ] || + if [ "$TEST_SHARD" = "cli" ] || [ "$TEST_SHARD" = "smoke" ]; then timeout_budget=15m fi diff --git a/internal/app/pat_auth_retry_test.go b/internal/app/pat_auth_retry_test.go index 11b8eae5..2d803e37 100644 --- a/internal/app/pat_auth_retry_test.go +++ b/internal/app/pat_auth_retry_test.go @@ -30,6 +30,7 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct" ) @@ -218,8 +219,16 @@ func TestPatScopeError_Error(t *testing.T) { // /cli/oauth/device/poll?flowId= with the given status sequence. // It also writes the server URL into a temp DWS_CONFIG_DIR/mcp_url so that // GetMCPBaseURL() returns the test server address. +func stubPATPollAccessToken(t *testing.T) { + t.Helper() + testseam.Swap(t, &patResolveAccessToken, func(context.Context, string, string) (string, error) { + return "", authpkg.ErrTokenDataNotFound + }) +} + func setupPollServer(t *testing.T, statuses []authpkg.DevicePollResponse) (*httptest.Server, string) { t.Helper() + stubPATPollAccessToken(t) var callCount atomic.Int32 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { @@ -381,6 +390,7 @@ func TestPollPatDeviceFlow_ServerErrorFallback(t *testing.T) { } func TestPollPatDeviceFlow_RedirectSkipped(t *testing.T) { + stubPATPollAccessToken(t) // When server returns 302 (SSO redirect), poll should continue until real response. var callCount int32 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { @@ -540,6 +550,7 @@ func (m *mockRunner) Run(ctx context.Context, inv executor.Invocation) (executor // It responds to device poll requests with the given status after the first poll. func setupHandlePATServer(t *testing.T, terminalStatus string, authCode string) (*httptest.Server, string) { t.Helper() + stubPATPollAccessToken(t) var pollCount atomic.Int32 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { diff --git a/internal/app/testmain_test.go b/internal/app/testmain_test.go index 5bed65f4..34e1adaa 100644 --- a/internal/app/testmain_test.go +++ b/internal/app/testmain_test.go @@ -83,6 +83,10 @@ func TestMain(m *testing.M) { // remove a TempDir while the audit lock is still open. setupAuditSink() openBrowserFunc = func(string) error { return nil } + // App tests may run in filtered CI processes. Install the same lazy Schema + // source factory as NewRootCommand without constructing a root so ResolveMeta + // tests never depend on an earlier test having initialized process state. + registerSchemaRuntimeDelivery() code := m.Run() StopAllStdioClients() CloseAuditSink() diff --git a/scripts/ci/run-app-race-tests.sh b/scripts/ci/run-app-race-tests.sh new file mode 100755 index 00000000..9922e9ab --- /dev/null +++ b/scripts/ci/run-app-race-tests.sh @@ -0,0 +1,126 @@ +#!/bin/sh +set -eu + +ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)" + +usage() { + printf '%s\n' \ + "usage: $0 verify " \ + " $0 run " >&2 + exit 2 +} + +[ "$#" -eq 2 ] || usage +mode="$1" +app_package="$2" + +case "$mode" in + verify|run) ;; + *) usage ;; +esac + +workdir="$(mktemp -d "${TMPDIR:-/tmp}/dws-app-race-tests.XXXXXX")" +trap 'rm -rf "$workdir"' EXIT HUP INT TERM + +tests="$workdir/tests" +duplicates="$workdir/duplicates" +list_output="$workdir/list-output" + +cd "$ROOT" +if ! go test "$app_package" -list '^(Test|Example|Fuzz)' > "$list_output"; then + printf 'app race partition discovery failed for %s\n' "$app_package" >&2 + exit 1 +fi +awk '/^(Test|Example|Fuzz)/ { print $1 }' "$list_output" > "$tests" + +if [ ! -s "$tests" ]; then + printf 'app race partition discovery found no tests in %s\n' "$app_package" >&2 + exit 1 +fi + +LC_ALL=C sort "$tests" | uniq -d > "$duplicates" +if [ -s "$duplicates" ]; then + printf '%s\n' 'app race partition discovery found duplicate top-level tests:' >&2 + sed 's/^/ /' "$duplicates" >&2 + exit 1 +fi + +schema_count=0 +ab_count=0 +c_count=0 +dr_count=0 +sz_count=0 +unmatched_count=0 + +while IFS= read -r test_name; do + case "$test_name" in + Test*Schema*) schema_count=$((schema_count + 1)) ;; + Test[A-B]*) ab_count=$((ab_count + 1)) ;; + TestC*) c_count=$((c_count + 1)) ;; + Test[D-R]*) dr_count=$((dr_count + 1)) ;; + Test[S-Z]*|Example*|Fuzz*) sz_count=$((sz_count + 1)) ;; + *) + printf 'unmatched app race test: %s\n' "$test_name" >&2 + unmatched_count=$((unmatched_count + 1)) + ;; + esac +done < "$tests" + +if [ "$unmatched_count" -ne 0 ]; then + exit 1 +fi + +for partition in \ + "schema:$schema_count" \ + "a-b:$ab_count" \ + "c:$c_count" \ + "d-r:$dr_count" \ + "s-z-example-fuzz:$sz_count" +do + name="${partition%%:*}" + count="${partition#*:}" + if [ "$count" -eq 0 ]; then + printf 'app race partition %s is empty\n' "$name" >&2 + exit 1 + fi +done + +total_count="$(wc -l < "$tests" | tr -d ' ')" +assigned_count=$((schema_count + ab_count + c_count + dr_count + sz_count)) +if [ "$assigned_count" -ne "$total_count" ]; then + printf 'app race partitions assigned %s tests, want %s\n' "$assigned_count" "$total_count" >&2 + exit 1 +fi + +printf 'app race partitions cover %s top-level tests exactly once: schema=%s a-b=%s c=%s d-r=%s s-z-example-fuzz=%s\n' \ + "$total_count" "$schema_count" "$ab_count" "$c_count" "$dr_count" "$sz_count" + +if [ "$mode" = "verify" ]; then + exit 0 +fi + +run_partition() { + name="$1" + run_pattern="$2" + skip_pattern="${3:-}" + + printf 'running internal/app race partition %s\n' "$name" + if [ -n "$skip_pattern" ]; then + go test -v -race -count=1 -timeout=15m \ + -run "$run_pattern" -skip "$skip_pattern" "$app_package" + else + go test -v -race -count=1 -timeout=15m \ + -run "$run_pattern" "$app_package" + fi +} + +# Schema assembly has the largest transient memory footprint. Run those tests +# in a fresh process, then keep each remaining name range in its own process so +# command trees retained by process-global registries are released between +# partitions. The complementary run/skip patterns preserve the full test set. +schema_pattern='^Test.*Schema' +run_partition schema "$schema_pattern" +run_partition a-b '^Test[A-B]' "$schema_pattern" +run_partition c '^TestC' "$schema_pattern" +run_partition d-r '^Test[D-R]' "$schema_pattern" +run_partition s-z-example-fuzz '^(Test[S-Z]|Example|Fuzz)' "$schema_pattern" diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index d01f366e..f8d91288 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -1182,13 +1182,16 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { t.Fatal("Code Admission workflow missing race test job boundaries") } raceJob := admission[raceStart:raceEnd] - // Full race shards use a dynamic package-level timeout: default/floor 12m, - // with app/cli/smoke raised to 15m for NewRootCommand / Schema assembly under - // -race on slower hosted runners. + // The app shard uses independently bounded test processes so process-global + // command registries are released before the Schema assembly peak. Other full + // race shards retain the dynamic package timeout: default/floor 12m, with + // cli/smoke raised to 15m on slower hosted runners. for _, want := range []string{ + `if [ "$TEST_SHARD" = "app" ]; then`, + `test "${#packages[@]}" -eq 1`, + `./scripts/ci/run-app-race-tests.sh run "${packages[0]}"`, "timeout_budget=12m", - `if [ "$TEST_SHARD" = "app" ] ||`, - `[ "$TEST_SHARD" = "cli" ] ||`, + `if [ "$TEST_SHARD" = "cli" ] ||`, `[ "$TEST_SHARD" = "smoke" ]; then`, "timeout_budget=15m", `go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"`, diff --git a/test/scripts/ci_test_package_plan_test.go b/test/scripts/ci_test_package_plan_test.go index 51a1943a..136ce8ec 100644 --- a/test/scripts/ci_test_package_plan_test.go +++ b/test/scripts/ci_test_package_plan_test.go @@ -47,6 +47,25 @@ func TestCITestPackagePlanRoutesPublicTestSuites(t *testing.T) { } } +func TestCIAppRacePartitionsCoverTopLevelTestsExactlyOnce(t *testing.T) { + root := testPackagePlanRoot(t) + packages := strings.Fields(runTestPackagePlan(t, root, "list", "app")) + if len(packages) != 1 { + t.Fatalf("app package shard = %v, want exactly one package", packages) + } + + script := filepath.Join(root, "scripts", "ci", "run-app-race-tests.sh") + cmd := exec.Command("sh", script, "verify", packages[0]) + cmd.Dir = root + output, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("%s verify %s failed: %v\n%s", script, packages[0], err, output) + } + if !strings.Contains(string(output), "top-level tests exactly once") { + t.Fatalf("verify output = %q, want exact coverage summary", output) + } +} + func TestCITestPackagePlanFailsClosedWhenGoListFails(t *testing.T) { root := testPackagePlanRoot(t) fakeBin := t.TempDir() From 4d13905cb86d8abfb460f787a00356228409ee1f Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 12 Aug 2026 23:06:55 +0800 Subject: [PATCH 038/250] fix(drive): fail closed on invalid remote folders Use explicit platform replace semantics for pull and sync, and reject recursive folder entries without a supported non-empty node ID. --- internal/helpers/drive_pull.go | 2 +- internal/helpers/drive_push.go | 8 +- .../helpers/drive_remote_folder_id_test.go | 79 +++++++++++++++++++ internal/helpers/drive_replace_unix.go | 11 +++ internal/helpers/drive_replace_windows.go | 11 +++ .../helpers/drive_replace_windows_test.go | 33 ++++++++ internal/helpers/drive_status.go | 8 +- internal/helpers/drive_sync.go | 2 +- 8 files changed, 148 insertions(+), 6 deletions(-) create mode 100644 internal/helpers/drive_remote_folder_id_test.go create mode 100644 internal/helpers/drive_replace_unix.go create mode 100644 internal/helpers/drive_replace_windows.go create mode 100644 internal/helpers/drive_replace_windows_test.go diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index ceeea8c5..c894d7f3 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -349,7 +349,7 @@ func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, t := time.UnixMilli(rf.ModifiedTime) _ = os.Chtimes(tmpPath, t, t) } - if err := os.Rename(tmpPath, localPath); err != nil { + if err := driveReplaceFile(tmpPath, localPath); err != nil { return pullActionFailed, fmt.Errorf("替换目标文件失败: %w", err) } committed = true diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index 42cf2242..5d790824 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -274,8 +274,12 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f if err := claimRemotePath(occupied, childRel, "目录"); err != nil { return err } - folders[childRel] = it.id() - if err := walkRemoteForPush(ctx, spaceID, it.id(), childRel, files, folders, occupied, depth+1); err != nil { + folderID := it.id() + if folderID == "" { + return fmt.Errorf("远端目录 %q 缺少目录 ID，已中止递归", childRel) + } + folders[childRel] = folderID + if err := walkRemoteForPush(ctx, spaceID, folderID, childRel, files, folders, occupied, depth+1); err != nil { return err } continue diff --git a/internal/helpers/drive_remote_folder_id_test.go b/internal/helpers/drive_remote_folder_id_test.go new file mode 100644 index 00000000..364a6429 --- /dev/null +++ b/internal/helpers/drive_remote_folder_id_test.go @@ -0,0 +1,79 @@ +package helpers + +import ( + "context" + "io" + "os" + "strings" + "testing" +) + +func TestCrossPlatformCoverageDriveRemoteTree_folderIDFallbacks(t *testing.T) { + for _, key := range []string{"fileId", "dentryUuid", "dentryId", "id", "nodeId"} { + t.Run(key, func(t *testing.T) { + caller := &driveScriptCaller{reply: func(_ string, args map[string]any, _ int) (string, error) { + if args["parentId"] == "ROOT" { + return `{"result":{"items":[{"name":"sub","type":"folder","` + key + `":"SUB"}],"nextToken":""}}`, nil + } + if args["parentId"] != "SUB" { + t.Fatalf("nested parentId = %v, want SUB", args["parentId"]) + } + return `{"result":{"items":[],"nextToken":""}}`, nil + }} + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + if _, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true); err != nil { + t.Fatalf("fetch with %s: %v", key, err) + } + if got := len(caller.callsFor("list_files")); got != 2 { + t.Fatalf("list_files calls = %d, want root + nested", got) + } + }) + } +} + +func TestCrossPlatformCoverageDriveRemoteTree_missingFolderIDFailsClosed(t *testing.T) { + for _, fetcher := range []struct { + name string + fetch func(context.Context) error + }{ + { + name: "status and pull tree", + fetch: func(ctx context.Context) error { + _, err := fetchRemoteDriveTree(ctx, "", "ROOT", true) + return err + }, + }, + { + name: "push and sync tree", + fetch: func(ctx context.Context) error { + _, _, err := fetchRemoteTreeForPush(ctx, "", "ROOT") + return err + }, + }, + } { + t.Run(fetcher.name, func(t *testing.T) { + caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) { + if nth > 0 || args["parentId"] != "ROOT" { + t.Fatalf("missing folder ID must not trigger another list_files call: nth=%d args=%v", nth, args) + } + return `{"result":{"items":[{"name":"sub","type":"folder"}],"nextToken":""}}`, nil + }} + prevDeps, prevArgs := deps, os.Args + deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + os.Args = []string{"dws", "drive"} + t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + + err := fetcher.fetch(context.Background()) + if err == nil || !strings.Contains(err.Error(), "目录 ID") || !strings.Contains(err.Error(), "sub") { + t.Fatalf("error = %v, want missing folder ID for sub", err) + } + if got := len(caller.callsFor("list_files")); got != 1 { + t.Fatalf("list_files calls = %d, want only root query", got) + } + }) + } +} diff --git a/internal/helpers/drive_replace_unix.go b/internal/helpers/drive_replace_unix.go new file mode 100644 index 00000000..8e10f947 --- /dev/null +++ b/internal/helpers/drive_replace_unix.go @@ -0,0 +1,11 @@ +//go:build !windows + +package helpers + +import "os" + +// driveReplaceFile 在同一文件系统内以 source 替换既有非目录 target。 +// Unix 的 rename(2) 原生提供原子替换语义。 +func driveReplaceFile(source, target string) error { + return os.Rename(source, target) +} diff --git a/internal/helpers/drive_replace_windows.go b/internal/helpers/drive_replace_windows.go new file mode 100644 index 00000000..2d729549 --- /dev/null +++ b/internal/helpers/drive_replace_windows.go @@ -0,0 +1,11 @@ +//go:build windows + +package helpers + +import "golang.org/x/sys/windows" + +// driveReplaceFile 使用 MoveFileEx(MOVEFILE_REPLACE_EXISTING) 替换既有非目录目标。 +// 不使用“先删除再改名”，避免覆盖过程中出现目标暂时缺失或原文件丢失。 +func driveReplaceFile(source, target string) error { + return windows.Rename(source, target) +} diff --git a/internal/helpers/drive_replace_windows_test.go b/internal/helpers/drive_replace_windows_test.go new file mode 100644 index 00000000..7efa8827 --- /dev/null +++ b/internal/helpers/drive_replace_windows_test.go @@ -0,0 +1,33 @@ +//go:build windows + +package helpers + +import ( + "os" + "path/filepath" + "testing" +) + +// Windows 必须通过 MOVEFILE_REPLACE_EXISTING 原子替换既有非目录目标；该路径同时 +// 服务 pull overwrite、sync remote-wins 与 keep-both 的占位文件替换。 +func TestCrossPlatformCoverageDriveReplaceFileWindows_replacesExistingTarget(t *testing.T) { + dir := t.TempDir() + source := filepath.Join(dir, "source.tmp") + target := filepath.Join(dir, "target.txt") + if err := os.WriteFile(source, []byte("new"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(target, []byte("old"), 0o600); err != nil { + t.Fatal(err) + } + + if err := driveReplaceFile(source, target); err != nil { + t.Fatalf("replace existing target: %v", err) + } + if got, err := os.ReadFile(target); err != nil || string(got) != "new" { + t.Fatalf("target = %q, err=%v; want new content", got, err) + } + if _, err := os.Stat(source); !os.IsNotExist(err) { + t.Fatalf("source must be moved, stat err=%v", err) + } +} diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 1da6b41b..c1075e73 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -153,8 +153,12 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m if err := claimRemotePath(occupied, childRel, "目录"); err != nil { return err } + folderID := it.id() + if folderID == "" { + return fmt.Errorf("远端目录 %q 缺少目录 ID，已中止递归", childRel) + } // 用子文件夹的 dentryUuid 作为下一层 parentId 递归进入。 - if err := walkRemoteDir(ctx, spaceID, it.id(), childRel, out, occupied, depth+1); err != nil { + if err := walkRemoteDir(ctx, spaceID, folderID, childRel, out, occupied, depth+1); err != nil { return err } continue @@ -220,7 +224,7 @@ func (d driveItem) str(keys ...string) string { } func (d driveItem) name() string { return d.str("name") } -func (d driveItem) id() string { return d.str("fileId") } +func (d driveItem) id() string { return d.str("fileId", "dentryUuid", "dentryId", "id", "nodeId") } func (d driveItem) typ() string { return d.str("type") } func (d driveItem) hash() string { return d.str("md5") } func (d driveItem) path() string { return d.str("path") } diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go index 79e06e4a..7400add3 100644 --- a/internal/helpers/drive_sync.go +++ b/internal/helpers/drive_sync.go @@ -17,7 +17,7 @@ import ( // syncRename 与 syncOpenFile 仅作为文件系统失败分支的确定性测试 seam；测试必须 // 通过 testseam.Swap 替换并自动恢复。 var ( - syncRename = os.Rename + syncRename = driveReplaceFile syncOpenFile = os.OpenFile ) From b92ac4db0fab5603b3b35c183e21bb9f87ffb548 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 23:16:33 +0800 Subject: [PATCH 039/250] fix(chat): preserve list-all time format --- internal/helpers/chat.go | 15 +++--- internal/helpers/chat_command_edges_test.go | 2 + .../helpers/chat_message_pagination_test.go | 52 ++++++++++++++++--- 3 files changed, 57 insertions(+), 12 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 464095b8..532a1584 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -475,17 +475,16 @@ func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { if err != nil { return nil, err } - endMs, err := parseISOTimeToMillis("end", endRaw) - if err != nil { - return nil, err - } + endMs, _ := parseISOTimeToMillis("end", endRaw) if err := validateTimeRange(startMs, endMs); err != nil { return nil, err } + startTime := formatChatMessageListAllTime(startMs) + endTime := formatChatMessageListAllTime(endMs) cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ - "startTime": startRaw, - "endTime": endRaw, + "startTime": startTime, + "endTime": endTime, "limit": chatIntFlagOrFallback(cmd, "limit", "size"), "cursor": cursor, }, nil @@ -622,6 +621,10 @@ func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (st return startRaw, endRaw, nil } +func formatChatMessageListAllTime(ms int64) string { + return time.UnixMilli(ms).In(shanghaiLocation()).Format("2006-01-02 15:04:05") +} + func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { toolArgs := map[string]any{} if v := flagOrFallback(cmd, "query", "keyword"); v != "" { diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 6b12c044..cadc2207 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -168,6 +168,8 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"message", "list", "--user=D-user", "--time=2026-01-01", "--limit=1"}, {"message", "list", "--open-dingtalk-id=D-user", "--time=2026-01-01", "--direction=sideways"}, {"message", "list-direct", "--user=D-user", "--limit=1"}, + {"message", "list-all", "--start=2026-01-01 00:00:00", "--end=bad"}, + {"message", "list-all", "--start=2026-01-02 00:00:00", "--end=2026-01-01 00:00:00"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-02T00:00:00Z", "--end=2026-01-01T00:00:00Z"}, diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 221bffa3..78eca26c 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -198,8 +198,8 @@ func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) { if got.tool != tt.wantTool { t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) } - startMs := numericArgAsInt64(t, got.args["startTime"]) - endMs := numericArgAsInt64(t, got.args["endTime"]) + startMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool) + endMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool) wantEndMin := before.Truncate(time.Second).UnixMilli() wantEndMax := after.Add(time.Second).UnixMilli() if endMs < wantEndMin || endMs > wantEndMax { @@ -266,8 +266,8 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { if got.tool != tt.wantTool { t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) } - startMs := numericArgAsInt64(t, got.args["startTime"]) - gotEndMs := numericArgAsInt64(t, got.args["endTime"]) + startMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool) + gotEndMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool) if gotEndMs != endMs { t.Fatalf("endTime = %d, want %d", gotEndMs, endMs) } @@ -275,6 +275,10 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { if startMs != wantStartMs { t.Fatalf("startTime = %d, want %d", startMs, wantStartMs) } + if tt.wantTool == "search_messages_by_time_range" { + assertStringArg(t, got.args["startTime"], "2025-12-31 00:00:00") + assertStringArg(t, got.args["endTime"], "2026-01-01 00:00:00") + } }) } } @@ -328,16 +332,20 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing if got.tool != tt.wantTool { t.Fatalf("tool = %q, want %q", got.tool, tt.wantTool) } - gotStartMs := numericArgAsInt64(t, got.args["startTime"]) + gotStartMs := chatMessageTimeArgAsMillis(t, got.args["startTime"], tt.wantTool) if gotStartMs != startMs { t.Fatalf("startTime = %d, want %d", gotStartMs, startMs) } - endMs := numericArgAsInt64(t, got.args["endTime"]) + endMs := chatMessageTimeArgAsMillis(t, got.args["endTime"], tt.wantTool) wantEndMin := before.Truncate(time.Second).UnixMilli() wantEndMax := after.Add(time.Second).UnixMilli() if endMs < wantEndMin || endMs > wantEndMax { t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax) } + if tt.wantTool == "search_messages_by_time_range" { + assertStringArg(t, got.args["startTime"], "2026-01-01 00:00:00") + parseChatMessageListAllTimeArg(t, got.args["endTime"]) + } }) } } @@ -398,6 +406,38 @@ func numericArgAsInt64(t *testing.T, value any) int64 { } } +func chatMessageTimeArgAsMillis(t *testing.T, value any, tool string) int64 { + t.Helper() + if tool == "search_messages_by_time_range" { + return parseChatMessageListAllTimeArg(t, value).UnixMilli() + } + return numericArgAsInt64(t, value) +} + +func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time { + t.Helper() + raw, ok := value.(string) + if !ok { + t.Fatalf("time arg = %#v, want yyyy-MM-dd HH:mm:ss string", value) + } + if strings.Contains(raw, "T") { + t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw) + } + parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, shanghaiLocation()) + if err != nil { + t.Fatalf("time arg = %q, parse err = %v", raw, err) + } + return parsed +} + +func assertStringArg(t *testing.T, value any, want string) { + t.Helper() + got, ok := value.(string) + if !ok || got != want { + t.Fatalf("arg = %#v, want %q", value, want) + } +} + func TestChatMessagePaginationPageAllAggregatesSevenCommands(t *testing.T) { tests := []struct { name string From dbee2de1d5c40e1f2f7919d08a4311481b07da7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Wed, 12 Aug 2026 22:33:15 +0800 Subject: [PATCH 040/250] fix(chat): align im id flag migration scope --- internal/cli/param_aliases_generated.go | 162 ++++++++++-------- internal/cli/param_concepts.json | 26 +-- internal/cli/schema_catalog_test.go | 37 ++-- internal/corecmd/corecmd_test.go | 10 ++ internal/helpers/chat.go | 151 +++++++++++++--- internal/helpers/chat_command_edges_test.go | 79 ++++++++- internal/helpers/chat_message_help_test.go | 28 +-- internal/helpers/chat_ports_coverage_test.go | 74 ++++++-- .../wukong_weekly_sync_chat_todo_test.go | 2 +- 9 files changed, 414 insertions(+), 155 deletions(-) diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index e5fc9df1..63c62457 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -889,11 +889,9 @@ var generatedParamAliases = []ParamAliasEntry{ Blocked: []string{"cursor"}, }, { - CLIPath: "chat category add-conv", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat category add-conv", + Blocked: []string{"category-id"}, + Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { CLIPath: "chat category create", @@ -918,11 +916,9 @@ var generatedParamAliases = []ParamAliasEntry{ Blocked: []string{"category-ids"}, }, { - CLIPath: "chat category remove-conv", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat category remove-conv", + Blocked: []string{"category-id"}, + Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { CLIPath: "chat category rename", @@ -934,37 +930,44 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat chmod", Aliases: map[string]string{ - "chat-id": "conversation-id", - "staff-id": "user", - "uid": "user", - "user-id": "user", - "userid": "user", + "chat": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", + "staff-id": "user", + "uid": "user", + "user-id": "user", + "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat clear-messages", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat clear-red-point", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat conversation-info", Aliases: map[string]string{ - "chat-id": "conversation-id", "staff-id": "user", "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "name", "to-user", "user-ids", "users"}, + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat group audit-join-validation", @@ -976,9 +979,12 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat group bots", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat": "group", + "chat-id": "group", + "conversation-id": "group", + "open-conversation-id": "group", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group create", @@ -1181,19 +1187,16 @@ var generatedParamAliases = []ParamAliasEntry{ Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { - CLIPath: "chat group-mute", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat group-mute", + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat group-mute-member", Aliases: map[string]string{ - "chat-id": "conversation-id", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, + Blocked: []string{"at-user-ids", "staff-id", "uid", "userid"}, + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat group-role add", @@ -1256,21 +1259,29 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat hide", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mark-read", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "msg-id": "message-id", + "open-conversation-id": "conversation-id", + "open-message-id": "message-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat mark-unread", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, @@ -1279,7 +1290,8 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Ambiguous: []string{"open-message-id"}, }, { CLIPath: "chat message add-favorite", @@ -1298,7 +1310,8 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Ambiguous: []string{"open-message-id"}, }, { CLIPath: "chat message combine-forward", @@ -1353,7 +1366,6 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message list", Aliases: map[string]string{ - "chat-id": "conversation-id", "max-result": "limit", "max-results": "limit", "page-size": "limit", @@ -1366,7 +1378,8 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "count", "cursor", "end", "name", "page", "to-user", "user-ids", "users"}, + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat message list-all", @@ -1413,11 +1426,8 @@ var generatedParamAliases = []ParamAliasEntry{ }, }, { - CLIPath: "chat message list-mentions", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat message list-mentions", + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat message list-pin-msg", @@ -1446,32 +1456,37 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message read-status", Aliases: map[string]string{ - "chat-id": "conversation-id", - "user-ids": "users", + "chat-id": "conversation-id", + "msg-id": "message-id", + "open-conversation-id": "conversation-id", + "open-message-id": "message-id", + "user-ids": "users", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"}, }, { CLIPath: "chat message recall", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message recall-by-bot", Aliases: map[string]string{ - "chat-id": "conversation-id", - "robot": "robot-code", + "robot": "robot-code", }, - Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"}, + Blocked: []string{"bot-code", "bot-id", "open-bot-id", "robot-id"}, + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat message remove-emoji", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Ambiguous: []string{"open-message-id"}, }, { CLIPath: "chat message remove-favorite", @@ -1490,22 +1505,23 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Ambiguous: []string{"open-message-id"}, }, { CLIPath: "chat message reply", Aliases: map[string]string{ - "chat-id": "conversation-id", - "ref-message-id": "ref-msg-id", + "chat": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", + "ref-message-id": "ref-msg-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, }, { - CLIPath: "chat message search", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + CLIPath: "chat message search", + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat message search-advanced", @@ -1518,7 +1534,6 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message send", Aliases: map[string]string{ - "chat-id": "conversation-id", "file": "file-path", "staff-id": "user", "to-user": "user", @@ -1526,18 +1541,18 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "name", "user-ids", "users"}, + Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { CLIPath: "chat message send-by-bot", Aliases: map[string]string{ "at-users": "at-user-ids", - "chat-id": "conversation-id", "robot": "robot-code", "user-ids": "users", }, - Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"}, - Ambiguous: []string{"at-ids"}, + Blocked: []string{"bot-code", "bot-id", "open-bot-id", "robot-id", "staff-id", "to-user-id", "uid", "user", "user-id", "userid"}, + Ambiguous: []string{"at-ids", "chat-id", "open-conversation-id"}, }, { CLIPath: "chat message send-by-webhook", @@ -1546,11 +1561,9 @@ var generatedParamAliases = []ParamAliasEntry{ }, }, { - CLIPath: "chat message send-card", - Aliases: map[string]string{ - "chat-id": "conversation-id", - }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + CLIPath: "chat message send-card", + Blocked: []string{"staff-id", "uid", "user", "user-id", "userid"}, + Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { CLIPath: "chat message set-pin-msg", @@ -1602,23 +1615,30 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat mute-at-all", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mute-red-envelope", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat set-top", Aliases: map[string]string{ - "chat-id": "conversation-id", + "chat": "conversation-id", + "chat-id": "conversation-id", + "group": "conversation-id", + "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "contact +dept-members", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 7d37a432..1bba1a07 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -49,10 +49,16 @@ "chat group members": {"bind": {"id": "open_conversation_id"}}, "chat group members add": {"bind": {"id": "open_conversation_id"}, "block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a list and may contain mixed userId/openDingTalkId values; singular inputs are not promoted automatically."}, "chat group members remove": {"bind": {"id": "open_conversation_id"}}, - "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, - "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id stay native; numeric groupId and list spellings are rejected."}, + "chat conversation-info": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat group-mute": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat group-mute-member": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat message add-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."}, + "chat message add-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."}, + "chat message list-mentions": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat message recall-by-bot": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat message remove-emoji": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."}, + "chat message remove-text-emotion": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "ambiguous": ["open-message-id"], "note": "Native --chat/--group/--id/--conversation-id/--open-conversation-id and visible --message-id/--msg-id stay executable; numeric/list spellings are rejected."}, + "chat message search": {"ambiguous": ["chat-id", "open-conversation-id"], "note": "Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat mute": {"scoped_aliases": {"chat-id": "conversation-id"}, "block": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "note": "Native --conversation-id and hidden compatibility --group/--id/--chat/--open-conversation-id remain unchanged; reviewed chat-id reduces to --conversation-id."}, "drive list": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, "drive upload": {"ambiguous": ["space"], "note": "both --space-id and native compatibility --workspace-id/--workspace exist; bare --space cannot choose one"}, @@ -73,12 +79,12 @@ "chat +unread-chats": {"scoped_aliases": {"limit": "count", "size": "count"}, "scope_strict": true, "note": "On this exact command, limit and size both denote the returned unread-conversation count."}, "chat message list-unread-conversations": {"scoped_aliases": {"limit": "count", "size": "count"}, "scope_strict": true, "note": "On this exact command, limit and size both denote the returned unread-conversation count."}, "chat +messages-list-direct": {"scoped_aliases": {"start": "time"}, "block": ["end"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented."}, - "chat message list": {"scoped_aliases": {"start": "time"}, "block": ["end"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented."}, + "chat message list": {"scoped_aliases": {"start": "time"}, "block": ["end"], "ambiguous": ["chat-id", "open-conversation-id"], "scope_strict": true, "note": "This exact command accepts one start boundary in yyyy-MM-dd HH:mm:ss; an end-only input cannot be represented. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat message list-by-sender": {"scoped_aliases": {"user-id": "sender-user-id", "open-dingtalk-id": "sender-open-dingtalk-id"}, "block": ["time"], "scope_strict": true, "note": "Only same-role sender identifiers are mapped; --time cannot supply the required RFC3339 start/end range."}, "contact +resolve-dept": {"bind": {"name": "search_query"}, "note": "The real --name is a department-name search keyword and carries the search_query concept on this shortcut."}, "contact +list-sub-depts": {"block": ["name", "query"], "note": "--dept is an integer department id; names and search queries require a separate resolution command"}, "contact +dept-members": {"bind": {"dept": "search_query"}, "scoped_aliases": {"name": "dept"}, "note": "The real --dept is a department-name search keyword; search spellings come from search_query, while --name remains command-scoped."}, - "chat message send": {"scoped_aliases": {"to-user": "user", "file": "file-path"}, "note": "Recipient and local-file-path aliases are exact to this command; obsolete file metadata flags remain unsupported."}, + "chat message send": {"scoped_aliases": {"to-user": "user", "file": "file-path"}, "ambiguous": ["chat-id", "open-conversation-id"], "note": "Recipient and local-file-path aliases are exact to this command; obsolete file metadata flags remain unsupported. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat +group-members": {"bind": {"group": "group_name"}, "note": "The real --group is a group-name search keyword on this shortcut, not an identifier."}, "chat +category-create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact shortcut."}, "chat category create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact command."}, @@ -87,8 +93,8 @@ "chat +category-delete": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."}, "chat category delete": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."}, "chat category list-conversations": {"block": ["category-ids"], "note": "This command requires one category id; list cardinality is not reduced automatically."}, - "chat category add-conv": {"block": ["category-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input."}, - "chat category remove-conv": {"block": ["category-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input."}, + "chat category add-conv": {"block": ["category-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat category remove-conv": {"block": ["category-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "This command requires a category-id list; one id is not promoted into a batch input. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat +chat-role-update": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."}, "chat group-role remove": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."}, "chat group-role update": {"block": ["role-ids"], "note": "This command requires one role id; list cardinality is not reduced automatically."}, @@ -98,7 +104,7 @@ "chat +messages-send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact shortcut."}, "chat message send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact command."}, "doc block insert": {"block": ["before-block-id"], "note": "Parent and reference roles remain distinct. --before-block-id needs both --ref-block and --where before, while role-free --block-id cannot choose parent versus reference.", "scoped_aliases": {"parent-block-id": "parent-block", "ref-block-id": "ref-block", "reference-block-id": "ref-block"}, "ambiguous": ["block-id"], "scope_strict": true}, - "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain."}, + "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids", "chat-id", "open-conversation-id"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "doc +export-get": {"block": ["doc-id", "document-id", "file-id", "node", "node-id", "task-id", "url"], "note": "This command queries one export jobId. Document node identifiers and import taskId spellings are different entities and are rejected.", "scoped_aliases": {"export-job-id": "job-id"}, "scope_strict": true}, "doc block delete": {"block": ["index"], "note": "index (position) vs node (node id) are different"}, "doc +copy": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."}, @@ -130,7 +136,7 @@ "chat +messages-read-status": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."}, "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."}, - "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."}, + "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."}, "chat +category-list-conversations": {"block": ["category-ids"], "note": "The real --category-id is singular; list cardinality is not reduced automatically."}, "chat +category-remove-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."}, diff --git a/internal/cli/schema_catalog_test.go b/internal/cli/schema_catalog_test.go index 355c8a42..9c0cd111 100644 --- a/internal/cli/schema_catalog_test.go +++ b/internal/cli/schema_catalog_test.go @@ -1396,7 +1396,8 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { } } - // Hidden conversation aliases must stay unpublished (merge-base parity). + // Manifest-covered migrations hide legacy aliases; manifest-external + // commands keep their existing visible flags for compatibility. editLeaf, err := queryDeliverySchemaPayload([]string{"chat message edit"}) if err != nil { t.Fatal(err) @@ -1415,10 +1416,11 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { if _, ok := listParams["conversation-id"]; !ok { t.Fatalf("chat category list-by-conv missing public canonical --conversation-id") } - for _, hidden := range []string{"group", "id"} { - if _, ok := listParams[hidden]; ok { - t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --%s", hidden) - } + if _, ok := listParams["group"]; !ok { + t.Fatalf("chat category list-by-conv unexpectedly hides manifest-external --group") + } + if _, ok := listParams["id"]; ok { + t.Fatalf("chat category list-by-conv unexpectedly publishes hidden alias --id") } for _, path := range []string{ @@ -1435,9 +1437,9 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { if _, ok := params["conversation-id"]; !ok { t.Fatalf("%s missing public canonical --conversation-id", path) } - for _, hidden := range []string{"group", "id", "chat"} { - if _, ok := params[hidden]; ok { - t.Fatalf("%s unexpectedly publishes hidden alias --%s", path, hidden) + for _, visible := range []string{"group", "id", "chat"} { + if _, ok := params[visible]; !ok { + t.Fatalf("%s unexpectedly hides manifest-external --%s", path, visible) } } } @@ -1447,17 +1449,16 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { t.Fatal(err) } groupBotsParams := schemaMap(groupBots["parameters"]) - if _, ok := groupBotsParams["conversation-id"]; !ok { - t.Fatal("chat group bots missing public canonical --conversation-id") + group := groupBotsParams["group"] + if group == nil { + t.Fatal("chat group bots missing public legacy --group") } - groupName := groupBotsParams["group-name"] - if groupName == nil { - t.Fatal("chat group bots missing public canonical --group-name") + if group["property"] != "openConversationId" { + t.Fatalf("chat group bots --group property = %#v, want openConversationId", group["property"]) } - if groupName["property"] != "groupName" { - t.Fatalf("chat group bots --group-name property = %#v, want groupName", groupName["property"]) - } - if _, ok := groupBotsParams["group"]; ok { - t.Fatal("chat group bots unexpectedly publishes hidden --group alias") + for _, migrated := range []string{"conversation-id", "group-name"} { + if _, ok := groupBotsParams[migrated]; ok { + t.Fatalf("chat group bots unexpectedly publishes migrated --%s", migrated) + } } } diff --git a/internal/corecmd/corecmd_test.go b/internal/corecmd/corecmd_test.go index 570b268a..a5ae5b96 100644 --- a/internal/corecmd/corecmd_test.go +++ b/internal/corecmd/corecmd_test.go @@ -116,6 +116,16 @@ func TestCrossPlatformCoverageRegisterFlagsAllKinds(t *testing.T) { } } +func TestCrossPlatformCoverageAnnotateFlagAliasIgnoresMissingInputs(t *testing.T) { + AnnotateFlagAlias(nil, "alias", "canonical") + + cmd := newTestCommand() + AnnotateFlagAlias(cmd, "missing", "canonical") + if flag := cmd.Flags().Lookup("missing"); flag != nil { + t.Fatalf("unexpected missing flag registered: %#v", flag) + } +} + // ── effective value fallback chain ───────────────────────────────── func TestCrossPlatformCoverageEffectiveValueFallbackChain(t *testing.T) { diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index ce76621c..e0ea7d4e 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -238,18 +238,101 @@ func chatMessageID(cmd *cobra.Command) (string, error) { } func installChatIMIDFlagAliases(root *cobra.Command) { - var visit func(*cobra.Command) - visit = func(cmd *cobra.Command) { - installChatFlagAliases(cmd, "conversation-id", []string{"group", "id", "chat", "open-conversation-id"}, requireChatConversationID) - installChatFlagAliases(cmd, "message-id", []string{"msg-id", "open-message-id"}, chatMessageID) - clearChatAliasRequiredAnnotations(cmd, "group", "id", "chat", "open-conversation-id", "msg-id", "open-message-id") + conversationMigrationPaths := chatMigrationPathSet(chatPendingConversationIDMigrationPaths) + messageMigrationPaths := chatMigrationPathSet(chatPendingMessageIDMigrationPaths) + var visit func(*cobra.Command, []string) + visit = func(cmd *cobra.Command, path []string) { + key := strings.Join(path, " ") + if conversationMigrationPaths[key] { + installChatFlagAliases(cmd, "conversation-id", []string{"group", "id", "chat", "open-conversation-id"}, requireChatConversationID) + clearChatAliasRequiredAnnotations(cmd, "group", "id", "chat", "open-conversation-id") + } + if messageMigrationPaths[key] { + installChatFlagAliases(cmd, "message-id", []string{"msg-id", "open-message-id"}, chatMessageID) + clearChatAliasRequiredAnnotations(cmd, "msg-id", "open-message-id") + } for _, child := range cmd.Commands() { - visit(child) + visit(child, append(path, child.Name())) } } - visit(root) + visit(root, nil) restoreChatGroupBotsLegacyRequired(root) restoreChatPendingMigrationCanonicalRequired(root) + restoreChatManifestExternalVisibleFlags(root) +} + +func chatMigrationPathSet(paths [][]string) map[string]bool { + set := make(map[string]bool, len(paths)) + for _, path := range paths { + set[strings.Join(path, " ")] = true + } + return set +} + +func restoreChatManifestExternalVisibleFlags(root *cobra.Command) { + if root == nil { + return + } + for _, spec := range chatManifestExternalVisibleFlagSpecs { + cmd, _, err := root.Find(spec.path) + if err != nil || cmd == nil { + continue + } + for _, flag := range spec.flags { + ensureVisibleStringFlag(cmd, flag.name, flag.usage) + } + for _, flag := range spec.optionalFlags { + if f := cmd.Flags().Lookup(flag); f != nil && f.Annotations != nil { + delete(f.Annotations, cobra.BashCompOneRequiredFlag) + } + } + } +} + +func ensureVisibleStringFlag(cmd *cobra.Command, name, usage string) { + flag := cmd.Flags().Lookup(name) + if flag == nil { + cmd.Flags().String(name, "", usage) + flag = cmd.Flags().Lookup(name) + } + if flag != nil { + flag.Hidden = false + } +} + +type chatVisibleFlagSpec struct { + name string + usage string +} + +type chatVisibleFlagCommandSpec struct { + path []string + flags []chatVisibleFlagSpec + optionalFlags []string +} + +var chatManifestExternalVisibleFlagSpecs = []chatVisibleFlagCommandSpec{ + {path: []string{"category", "add-conv"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"category", "list-by-conv"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}, optionalFlags: []string{"conversation-id"}}, + {path: []string{"category", "remove-conv"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"conversation-info"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"file", "upload"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"group", "get-mute-config"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"group-mute"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"group-mute-member"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "add-emoji"}, flags: []chatVisibleFlagSpec{{"msg-id", "--message-id 的别名"}}}, + {path: []string{"message", "add-text-emotion"}, flags: []chatVisibleFlagSpec{{"msg-id", "--message-id 的别名"}}}, + {path: []string{"message", "list"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "list-mentions"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "recall-by-bot"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "remove-emoji"}, flags: []chatVisibleFlagSpec{{"msg-id", "--message-id 的别名"}}}, + {path: []string{"message", "remove-text-emotion"}, flags: []chatVisibleFlagSpec{{"msg-id", "--message-id 的别名"}}}, + {path: []string{"message", "search"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "send"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "send-by-bot"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}}}, + {path: []string{"message", "send-card"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}, {"receiver", "--open-dingtalk-id 的兼容别名"}}}, + {path: []string{"message", "update-text-emotion"}, flags: []chatVisibleFlagSpec{{"group", "--conversation-id 的别名"}, {"id", "--conversation-id 的别名"}, {"chat", "--conversation-id 的别名"}}, optionalFlags: []string{"conversation-id"}}, + {path: []string{"mute"}, flags: []chatVisibleFlagSpec{{"chat", "--conversation-id 的别名"}, {"id", "--conversation-id 的别名"}}}, } func restoreChatGroupBotsLegacyRequired(root *cobra.Command) { @@ -5330,12 +5413,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Example: ` dws chat category list-by-conv --conversation-id # 查询群 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - groupID := flagOrFallback(cmd, "conversation-id", "group", "id") - if groupID == "" { - return fmt.Errorf("flag --group is required") + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id"); err != nil { + return err } return callMCPToolOnServer("im", "list_conv_categories_by_conv", map[string]any{ - "openConversationId": groupID, + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id"), }) }, } @@ -5366,6 +5448,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id }, Parameters: []contract.ParamDecl{ {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5522,7 +5605,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Example: ` dws chat message add-emoji --conversation-id --message-id --emoji "赞" # 查询会话 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"); err != nil { return err } if _, err := chatMessageID(cmd); err != nil { @@ -5532,7 +5615,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id return err } return callMCPToolOnServer("im", "add_emoji_reaction", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"), "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emojiName": mustGetFlag(cmd, "emoji"), }) @@ -5574,6 +5657,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageAddEmojiCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("chat", "", "--conversation-id 的别名") + chatMessageAddEmojiCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageAddEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") @@ -5583,7 +5667,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Example: ` dws chat message remove-emoji --conversation-id --message-id --emoji "赞" # 查询会话 ID: dws chat search --query "群名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"); err != nil { return err } if _, err := chatMessageID(cmd); err != nil { @@ -5593,7 +5677,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id return err } return callMCPToolOnServer("im", "remove_emoji_reaction", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"), "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emojiName": mustGetFlag(cmd, "emoji"), }) @@ -5635,6 +5719,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageRemoveEmojiCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("chat", "", "--conversation-id 的别名") + chatMessageRemoveEmojiCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageRemoveEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") @@ -5643,7 +5728,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Short: "对消息添加文字表情回应", Example: ` dws chat message add-text-emotion --conversation-id --message-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"); err != nil { return err } if _, err := chatMessageID(cmd); err != nil { @@ -5653,7 +5738,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id return err } return callMCPToolOnServer("im", "add_text_emotion", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"), "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), "emotionName": mustGetFlag(cmd, "emotion-name"), @@ -5697,6 +5782,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageAddTextEmotionCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageAddTextEmotionCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageAddTextEmotionCmd.Flags().String("chat", "", "--conversation-id 的别名") + chatMessageAddTextEmotionCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageAddTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageAddTextEmotionCmd.Flags().String("emotion-id", "", "表情 ID (必填，通过 create-text-emotion 获取)") chatMessageAddTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") @@ -5708,7 +5794,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Short: "移除消息的文字表情回应", Example: ` dws chat message remove-text-emotion --conversation-id --message-id --emotion-id --emotion-name "赞" --text "nice" --background-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"); err != nil { return err } if _, err := chatMessageID(cmd); err != nil { @@ -5718,7 +5804,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id return err } return callMCPToolOnServer("im", "remove_text_emotion", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"), "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), "emotionName": mustGetFlag(cmd, "emotion-name"), @@ -5762,6 +5848,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageRemoveTextEmotionCmd.Flags().String("group", "", "--conversation-id 的别名") chatMessageRemoveTextEmotionCmd.Flags().String("id", "", "--conversation-id 的别名") chatMessageRemoveTextEmotionCmd.Flags().String("chat", "", "--conversation-id 的别名") + chatMessageRemoveTextEmotionCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageRemoveTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("emotion-id", "", "表情 ID (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") @@ -5773,7 +5860,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Short: "更新消息的文字表情回应", Example: ` dws chat message update-text-emotion --conversation-id --message-id --old-emotion-id --emotion-id --emotion-name "赞" --text "nice" --background-id im_bg_5`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"); err != nil { return err } if _, err := chatMessageID(cmd); err != nil { @@ -5783,7 +5870,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id return err } return callMCPToolOnServer("im", "update_text_emotion", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat", "open-conversation-id"), "openMsgId": flagOrFallback(cmd, "message-id", "msg-id"), "oldEmotionId": mustGetFlag(cmd, "old-emotion-id"), "emotionId": mustGetFlag(cmd, "emotion-id"), @@ -5823,16 +5910,21 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id }, Parameters: []contract.ParamDecl{ {Name: "background-id", Property: "backgroundId", Required: boolPtr(true), Description: "新文字表情的背景 ID"}, + {Name: "chat", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId 兼容入口"}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId"}, {Name: "emotion-id", Property: "emotionId", Required: boolPtr(true), Description: "新的文字表情 ID，可通过 create-text-emotion 获取"}, {Name: "emotion-name", Property: "emotionName", Required: boolPtr(true), Description: "新的文字表情名称"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId 兼容入口"}, + {Name: "id", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId 兼容入口"}, {Name: "message-id", Property: "openMsgId", Required: boolPtr(true), Description: "需要原地更新文字表情的消息 openMsgId"}, {Name: "old-emotion-id", Property: "oldEmotionId", Required: boolPtr(true), Description: "消息上当前文字表情的 emotionId"}, + {Name: "open-conversation-id", Property: "openConversationId", Required: boolPtr(false), Description: "会话 openConversationId 兼容入口"}, {Name: "text", Property: "text", Required: boolPtr(true), Description: "新的文字表情内容"}, }, }, }) chatMessageUpdateTextEmotionCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填，支持单聊/群聊)") + chatMessageUpdateTextEmotionCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageUpdateTextEmotionCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("old-emotion-id", "", "待更新的原表情 ID (必填)") chatMessageUpdateTextEmotionCmd.Flags().String("emotion-id", "", "新表情 ID (必填)") @@ -6751,9 +6843,12 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id （openDingTalkId 可通过 dws contact user search --query "姓名" 获取）`, - Example: ` dws chat message forward --src-conversation-id --msg-id --dest-conversation-id `, + Example: ` dws chat message forward --src-conversation-id --message-id --dest-conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "src-conversation-id", "msg-id", "dest-conversation-id"); err != nil { + if err := validateRequiredFlags(cmd, "src-conversation-id", "dest-conversation-id"); err != nil { + return err + } + if err := validateRequiredFlagWithAliases(cmd, "message-id", "msg-id"); err != nil { return err } toolArgs := map[string]any{ @@ -6790,7 +6885,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "把一条已有消息转发到另一个会话", UseWhen: []string{"已知源消息与源、目标会话 ID 时"}, AvoidWhen: []string{"合并转发多条消息时使用 chat message combine-forward"}, - Examples: []string{"dws chat message forward --src-conversation-id --msg-id --dest-conversation-id "}, + Examples: []string{"dws chat message forward --src-conversation-id --message-id --dest-conversation-id "}, }, Parameters: []contract.ParamDecl{ {Name: "dest-conversation-id", Property: "destOpenCid"}, @@ -6874,11 +6969,11 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 返回的是原始配置记录，不等同于当前被禁言成员列表；全员禁言开关也不在本命令的返回范围内。`, Example: ` dws chat group get-mute-config --conversation-id `, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "conversation-id"); err != nil { + if err := validateRequiredFlagWithAliases(cmd, "conversation-id", "group"); err != nil { return err } return callMCPToolOnServer("im", "get_group_mute_config", map[string]any{ - "openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"), + "openConversationId": flagOrFallback(cmd, "conversation-id", "group"), }) }, } @@ -6907,9 +7002,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"设置全员禁言用 chat group-mute；禁言个人用 chat group-mute-member"}, Examples: []string{"dws chat group get-mute-config --conversation-id --format json"}, }, + Parameters: []contract.ParamDecl{ + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + }, }, }) chatGroupGetMuteConfigCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") + chatGroupGetMuteConfigCmd.Flags().String("group", "", "--conversation-id 的别名") chatGroupCmd.AddCommand(chatGroupGetMuteConfigCmd) // ── group-mute: 全员禁言 ─────────────────────────────── diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 0f42875b..b8553d05 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -12,6 +12,7 @@ import ( "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" ) func runChatCoverageCommand(t *testing.T, caller edition.ToolCaller, args ...string) error { @@ -126,6 +127,80 @@ func TestCrossPlatformCoverageChatStableCompatibilityHintsRemainAvailable(t *tes } } +func TestCrossPlatformCoverageChatAliasInstallerRemainingEdges(t *testing.T) { + restoreChatManifestExternalVisibleFlags(nil) + + mismatchedRoot := &cobra.Command{Use: "chat"} + mismatchedRoot.AddCommand(&cobra.Command{Use: "other"}) + restoreChatManifestExternalVisibleFlags(mismatchedRoot) + + missingPrimary := &cobra.Command{Use: "leaf"} + installChatFlagAliases(missingPrimary, "conversation-id", []string{"group"}, requireChatConversationID) + if flag := missingPrimary.Flags().Lookup("group"); flag != nil { + t.Fatalf("alias registered without canonical flag: %#v", flag) + } + + skipGroup := &cobra.Command{Use: "leaf", RunE: func(cmd *cobra.Command, args []string) error { return nil }} + skipGroup.Flags().String("conversation-id", "", "") + skipGroup.Flags().String("group-name", "", "") + installChatFlagAliases(skipGroup, "conversation-id", []string{"group", "chat"}, requireChatConversationID) + if flag := skipGroup.Flags().Lookup("group"); flag != nil { + t.Fatalf("group alias registered beside group-name: %#v", flag) + } + if flag := skipGroup.Flags().Lookup("chat"); flag == nil { + t.Fatal("non-group alias was not registered") + } + + preRunCalled := false + withPreRun := &cobra.Command{ + Use: "leaf", + PreRunE: func(cmd *cobra.Command, args []string) error { + preRunCalled = true + return nil + }, + RunE: func(cmd *cobra.Command, args []string) error { return nil }, + } + withPreRun.Flags().String("conversation-id", "", "") + installChatFlagAliases(withPreRun, "conversation-id", []string{"group"}, requireChatConversationID) + withPreRun.SetArgs([]string{"--group", "cid"}) + if err := withPreRun.ExecuteContext(context.Background()); err != nil { + t.Fatalf("execute with alias and previous PreRunE: %v", err) + } + if !preRunCalled { + t.Fatal("previous PreRunE was not called") + } +} + +func TestCrossPlatformCoverageChatMessageForwardRequiresMessageID(t *testing.T) { + caller := &productExampleCaller{} + InitDeps(caller) + deps.Out.w = io.Discard + deps.Out.errW = io.Discard + root := newChatCommand() + command, _, err := root.Find([]string{"message", "forward"}) + if err != nil { + t.Fatal(err) + } + for _, name := range []string{"message-id", "msg-id"} { + if flag := command.Flags().Lookup(name); flag != nil && flag.Annotations != nil { + delete(flag.Annotations, cobra.BashCompOneRequiredFlag) + } + } + if err := command.Flags().Set("src-conversation-id", "src"); err != nil { + t.Fatal(err) + } + if err := command.Flags().Set("dest-conversation-id", "dest"); err != nil { + t.Fatal(err) + } + err = command.RunE(command, nil) + if err == nil || !strings.Contains(err.Error(), "missing required flag: --message-id") { + t.Fatalf("forward missing message id error = %v", err) + } + if caller.calls != 0 { + t.Fatalf("tool calls = %d, want 0", caller.calls) + } +} + func TestCrossPlatformCoverageChatGroupUpdateIconAcceptsUploadedMediaIDPrefixes(t *testing.T) { previousDeps, previousArgs := deps, os.Args os.Args = []string{"dws", "chat"} @@ -439,8 +514,8 @@ func TestCrossPlatformCoverageChatIMIDMigrationRequiredFlagErrors(t *testing.T) {name: "role set user missing conversation", path: []string{"group-role", "set-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"}, {name: "role remove user missing conversation", path: []string{"group-role", "remove-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"}, {name: "role query user missing conversation", path: []string{"group-role", "query-user"}, flag: map[string]string{"user": "D1"}, want: "conversation-id"}, - {name: "bots conflicting conversation aliases", path: []string{"group", "bots"}, flag: map[string]string{"conversation-id": "cid1", "id": "cid2"}, want: "conflicts"}, - {name: "bots conflicting group aliases", path: []string{"group", "bots"}, flag: map[string]string{"group-name": "项目群", "group": "cid"}, want: "conflicts"}, + {name: "bots missing legacy group", path: []string{"group", "bots"}, want: "group"}, + {name: "bots rejects migrated conversation id", path: []string{"group", "bots"}, flag: map[string]string{"conversation-id": "cid"}, want: "no such flag"}, {name: "dismiss missing conversation", path: []string{"group", "dismiss"}, flag: map[string]string{"yes": "true"}, want: "conversation-id"}, {name: "set history missing conversation", path: []string{"group", "set-history"}, flag: map[string]string{"option": "ALL"}, want: "conversation-id"}, {name: "set pin missing message", path: []string{"message", "set-pin-msg"}, flag: map[string]string{"open-conversation-id": "cid"}, want: "message-id"}, diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 4c7323ac..bc11c366 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -171,7 +171,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing } } -func TestCrossPlatformCoverageChatReactionHelpHidesConversationAliases(t *testing.T) { +func TestCrossPlatformCoverageChatReactionHelpKeepsManifestExternalAliasesVisible(t *testing.T) { for _, command := range []string{"add-emoji", "remove-emoji", "add-text-emotion", "remove-text-emotion"} { t.Run(command, func(t *testing.T) { cmd := newChatCommand() @@ -187,16 +187,16 @@ func TestCrossPlatformCoverageChatReactionHelpHidesConversationAliases(t *testin if !strings.Contains(help, "--conversation-id") { t.Fatalf("chat message %s help missing --conversation-id:\n%s", command, help) } - for _, hidden := range []string{"--group", "--id", "--chat"} { - if strings.Contains(help, hidden+" string") { - t.Fatalf("chat message %s help exposes hidden alias %s:\n%s", command, hidden, help) + for _, visible := range []string{"--group", "--id", "--chat"} { + if !strings.Contains(help, visible+" string") { + t.Fatalf("chat message %s help hides manifest-external alias %s:\n%s", command, visible, help) } } }) } } -func TestCrossPlatformCoverageChatGroupBotsHelpSplitsGroupName(t *testing.T) { +func TestCrossPlatformCoverageChatGroupBotsHelpKeepsLegacyGroup(t *testing.T) { cmd := newChatCommand() var output bytes.Buffer cmd.SetOut(&output) @@ -207,13 +207,13 @@ func TestCrossPlatformCoverageChatGroupBotsHelpSplitsGroupName(t *testing.T) { } help := output.String() - for _, visible := range []string{"--conversation-id", "--group-name"} { - if !strings.Contains(help, visible) { - t.Fatalf("chat group bots help missing %s:\n%s", visible, help) - } + if !strings.Contains(help, "--group string") { + t.Fatalf("chat group bots help missing visible --group:\n%s", help) } - if strings.Contains(help, "--group string") { - t.Fatalf("chat group bots help exposes hidden --group alias:\n%s", help) + for _, hidden := range []string{"--conversation-id", "--group-name"} { + if strings.Contains(help, hidden) { + t.Fatalf("chat group bots help exposes migrated flag %s:\n%s", hidden, help) + } } } @@ -233,9 +233,9 @@ func TestCrossPlatformCoverageChatSendCardHelpUsesCanonicalIDFlags(t *testing.T) t.Fatalf("send-card help missing %s:\n%s", visible, help) } } - for _, hidden := range []string{"--group", "--receiver"} { - if strings.Contains(help, hidden+" string") { - t.Fatalf("send-card help exposes hidden alias %s:\n%s", hidden, help) + for _, visible := range []string{"--group", "--receiver"} { + if !strings.Contains(help, visible+" string") { + t.Fatalf("send-card help hides manifest-external alias %s:\n%s", visible, help) } } } diff --git a/internal/helpers/chat_ports_coverage_test.go b/internal/helpers/chat_ports_coverage_test.go index a7d8a6d2..025e31f9 100644 --- a/internal/helpers/chat_ports_coverage_test.go +++ b/internal/helpers/chat_ports_coverage_test.go @@ -81,6 +81,32 @@ func TestCrossPlatformCoverageChatUpdateTextEmotion(t *testing.T) { }, }, }, + { + name: "open-conversation-id alias", + args: []string{ + "message", "update-text-emotion", + "--open-conversation-id", "conv-3", + "--message-id", "msg-3", + "--old-emotion-id", "old-3", + "--emotion-id", "new-3", + "--emotion-name", "smile", + "--text", "done", + "--background-id", "im_bg_2", + }, + want: guardedMutationCall{ + productID: "im", + toolName: "update_text_emotion", + args: map[string]any{ + "openConversationId": "conv-3", + "openMsgId": "msg-3", + "oldEmotionId": "old-3", + "emotionId": "new-3", + "emotionName": "smile", + "text": "done", + "backgroundId": "im_bg_2", + }, + }, + }, } for _, test := range tests { test := test @@ -163,19 +189,41 @@ func TestCrossPlatformCoverageChatUpdateTextEmotionRequiredFlags(t *testing.T) { } func TestCrossPlatformCoverageChatGroupGetMuteConfig(t *testing.T) { - caller := &guardedMutationCaller{} - err := executeGuardedMutationCommand(t, caller, newChatCommand, - "group", "get-mute-config", "--group", "conv-1") - if err != nil { - t.Fatalf("get-mute-config returned error: %v", err) - } - want := guardedMutationCall{ - productID: "im", - toolName: "get_group_mute_config", - args: map[string]any{"openConversationId": "conv-1"}, - } - if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) { - t.Fatalf("tool calls = %#v, want %#v", caller.calls, want) + for _, test := range []struct { + name string + args []string + want guardedMutationCall + }{ + { + name: "legacy group alias", + args: []string{"group", "get-mute-config", "--group", "conv-1"}, + want: guardedMutationCall{ + productID: "im", + toolName: "get_group_mute_config", + args: map[string]any{"openConversationId": "conv-1"}, + }, + }, + { + name: "canonical conversation id", + args: []string{"group", "get-mute-config", "--conversation-id", "conv-2"}, + want: guardedMutationCall{ + productID: "im", + toolName: "get_group_mute_config", + args: map[string]any{"openConversationId": "conv-2"}, + }, + }, + } { + test := test + t.Run(test.name, func(t *testing.T) { + caller := &guardedMutationCaller{} + err := executeGuardedMutationCommand(t, caller, newChatCommand, test.args...) + if err != nil { + t.Fatalf("get-mute-config returned error: %v", err) + } + if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], test.want) { + t.Fatalf("tool calls = %#v, want %#v", caller.calls, test.want) + } + }) } } diff --git a/internal/helpers/wukong_weekly_sync_chat_todo_test.go b/internal/helpers/wukong_weekly_sync_chat_todo_test.go index 3820586d..efe5d871 100644 --- a/internal/helpers/wukong_weekly_sync_chat_todo_test.go +++ b/internal/helpers/wukong_weekly_sync_chat_todo_test.go @@ -117,7 +117,7 @@ func TestCrossPlatformCoverageWukongWeeklyChatCategoryQueries(t *testing.T) { caller := &wukongWeeklySyncCaller{} _, _, err := executeWukongWeeklySyncCommand(t, "chat", caller, newChatCommand, "category", "list-by-conv") if err == nil || !strings.Contains(err.Error(), "missing required flag: --conversation-id") { - t.Fatalf("missing group error = %v", err) + t.Fatalf("missing conversation ID error = %v", err) } requireWukongWeeklySyncNoCalls(t, caller) From 6fdf6e0678104f5ef72d684a1ef0e21dc67c7997 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 10:01:10 +0800 Subject: [PATCH 041/250] fix(drive): reject sync path type conflicts --- internal/helpers/drive_sync.go | 48 +++++++ .../helpers/drive_sync_type_conflict_test.go | 131 ++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 internal/helpers/drive_sync_type_conflict_test.go diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go index 7400add3..d0baefb0 100644 --- a/internal/helpers/drive_sync.go +++ b/internal/helpers/drive_sync.go @@ -158,6 +158,21 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { localByRel[f.RelPath] = f } + // 在计算 diff 前先识别文件/目录同路径冲突。冲突根及其全部后代都不能再进入 + // new_local / new_remote 或后续执行阶段，否则会在远端制造同名异类对象，或尝试 + // 把远端目录内容下载到本地文件之下。 + typeConflicts := make(map[string]string) + for _, dir := range localDirs { + if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { + typeConflicts[dir] = msg + } + } + for rel := range localByRel { + if msg := pushTypeConflictError(rel, false, remoteFiles, remoteFolders); msg != "" { + typeConflicts[rel] = msg + } + } + // 计算 diff：双端都存在的文件复用 judgeFileMatch，保持与 status 完全一致的判定。 diff := driveSyncDiff{ NewLocal: []driveStatusEntry{}, @@ -168,6 +183,9 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { } var newLocal, newRemote, modified, unknown []string for rel, pf := range localByRel { + if syncPathBlockedByTypeConflict(rel, typeConflicts) { + continue + } rf, ok := remoteFiles[rel] if !ok { newLocal = append(newLocal, rel) @@ -188,6 +206,9 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { } } for rel := range remoteFiles { + if syncPathBlockedByTypeConflict(rel, typeConflicts) { + continue + } if _, ok := localByRel[rel]; !ok { newRemote = append(newRemote, rel) } @@ -211,6 +232,18 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { sortEntries(diff.Unchanged) res := driveSyncResult{Detection: detection, Diff: diff, Items: []driveSyncItem{}} + conflictRels := make([]string, 0, len(typeConflicts)) + for rel := range typeConflicts { + conflictRels = append(conflictRels, rel) + } + sort.Strings(conflictRels) + for _, rel := range conflictRels { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{ + RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, + Error: typeConflicts[rel], + }) + } // --dry-run：只算差异、不执行任何同步动作。 if deps.Caller.DryRun() { @@ -276,6 +309,9 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { // 阶段 1：镜像本地目录结构到远端（缺失则创建），保证空目录与 push 目标的父目录先存在。 for _, dir := range localDirs { + if syncPathBlockedByTypeConflict(dir, typeConflicts) { + continue + } if _, ok := remoteFolders[dir]; ok { continue // 远端已存在，复用 fileId } @@ -339,6 +375,18 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { return nil } +// syncPathBlockedByTypeConflict 判断 rel 本身或任一祖先是否是文件/目录类型冲突根。 +// 祖先检查保证冲突目录下的本地、远端后代不会绕过根路径的 fail-closed 结论。 +func syncPathBlockedByTypeConflict(rel string, conflicts map[string]string) bool { + for rel != "" { + if _, blocked := conflicts[rel]; blocked { + return true + } + rel, _ = splitRel(rel) + } + return false +} + // syncPullFile 下载单个远端文件到本地 rel 对应路径（总是覆盖，Drive 为该项权威源）， // 并把结果计入 res。命中大小写/规范化冲突或逃逸的路径记 failed、不落盘。 func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, collided map[string]bool, direction string) { diff --git a/internal/helpers/drive_sync_type_conflict_test.go b/internal/helpers/drive_sync_type_conflict_test.go new file mode 100644 index 00000000..dbb66b66 --- /dev/null +++ b/internal/helpers/drive_sync_type_conflict_test.go @@ -0,0 +1,131 @@ +package helpers + +import ( + "bytes" + "context" + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +type driveSyncTypeConflictFixture struct { + name string + setup func(t *testing.T, root string) + listings map[string]string +} + +func driveSyncTypeConflictFixtures() []driveSyncTypeConflictFixture { + return []driveSyncTypeConflictFixture{ + { + name: "local folder conflicts with remote file", + setup: func(t *testing.T, root string) { + t.Helper() + mustWrite(t, filepath.Join(root, "conflict", "local.txt"), "local") + }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"conflict","type":"file","fileId":"REMOTE_FILE","modifyTime":1}],"nextToken":""}}`, + }, + }, + { + name: "local file conflicts with remote folder", + setup: func(t *testing.T, root string) { + t.Helper() + mustWrite(t, filepath.Join(root, "conflict"), "local") + }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"conflict","type":"folder","fileId":"REMOTE_FOLDER"}],"nextToken":""}}`, + "REMOTE_FOLDER": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"REMOTE_CHILD","modifyTime":1}],"nextToken":""}}`, + }, + }, + } +} + +func TestCrossPlatformCoverageDriveSync_typeConflictsFailClosedBeforeWrites(t *testing.T) { + for _, tc := range driveSyncTypeConflictFixtures() { + t.Run(tc.name, func(t *testing.T) { + root := t.TempDir() + tc.setup(t, root) + caller := syncCaller(tc.listings) + + transferCalls := captureDriveSyncTransfers(t) + + err := runDriveCmd(t, caller, "sync", "--local-folder", root, + "--remote-folder", "ROOT", "--quick") + var syncFailure *driveSyncFailure + if !errors.As(err, &syncFailure) || syncFailure.failed != 1 { + t.Fatalf("type conflict error = %v, want one failed item", err) + } + assertDriveSyncNoWriteCalls(t, caller, transferCalls) + }) + } +} + +func TestCrossPlatformCoverageDriveSync_dryRunReportsTypeConflictsWithoutWrites(t *testing.T) { + for _, tc := range driveSyncTypeConflictFixtures() { + t.Run(tc.name, func(t *testing.T) { + root := t.TempDir() + tc.setup(t, root) + caller := syncCaller(tc.listings) + caller.dryRun = true + + transferCalls := captureDriveSyncTransfers(t) + + var out bytes.Buffer + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"}) + + cmd := findDriveSubcommand(t, "sync") + mustSetFlags(t, cmd, map[string]string{ + "local-folder": root, + "remote-folder": "ROOT", + "quick": "true", + }) + if err := cmd.RunE(cmd, nil); err != nil { + t.Fatalf("dry-run type conflict: %v", err) + } + + text := out.String() + if !strings.Contains(text, `"failed": 1`) || + !strings.Contains(text, `"action": "failed"`) || + !strings.Contains(text, `"rel_path": "conflict"`) { + t.Fatalf("dry-run must report the type conflict as failed: %s", text) + } + assertDriveSyncNoWriteCalls(t, caller, transferCalls) + }) + } +} + +type driveSyncTransferCalls struct { + get int + put int +} + +func captureDriveSyncTransfers(t *testing.T) *driveSyncTransferCalls { + t.Helper() + calls := &driveSyncTransferCalls{} + testseam.Swap(t, &httpGetFile, func(context.Context, string, map[string]string, string) error { + calls.get++ + return nil + }) + testseam.Swap(t, &httpPutFile, func(context.Context, string, map[string]string, string, int64) error { + calls.put++ + return nil + }) + return calls +} + +func assertDriveSyncNoWriteCalls(t *testing.T, caller *driveScriptCaller, transferCalls *driveSyncTransferCalls) { + t.Helper() + for _, tool := range []string{"create_folder", "download_file", "get_upload_info", "commit_upload"} { + if calls := caller.callsFor(tool); len(calls) != 0 { + t.Errorf("type conflict must not call %s, got %v", tool, calls) + } + } + if transferCalls.get != 0 || transferCalls.put != 0 { + t.Errorf("type conflict must not transfer HTTP content, GET=%d PUT=%d", transferCalls.get, transferCalls.put) + } +} From 19e19bcd2bd4a3926bf80708a50ef0720eb3d570 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 12 Aug 2026 17:44:13 +0800 Subject: [PATCH 042/250] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E6=8B=9B?= =?UTF-8?q?=E8=81=98=E8=81=8C=E4=BD=8D=E7=AE=A1=E7=90=86=20to#85340676?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .changes/976-recruit-job.md | 5 + internal/helpers/recruit.go | 284 ++++++++++++++++++ internal/helpers/recruit_test.go | 207 +++++++++++++ internal/helpers/register_products_test.go | 2 +- internal/helpers/register_recruit.go | 11 + pkg/edition/default.go | 16 +- pkg/edition/edition_test.go | 8 + skills/content-qa/mono-multi-coverage.yaml | 4 + skills/mono/SKILL.md | 2 + skills/mono/references/products/recruit.md | 29 ++ skills/multi/dingtalk-misc/SKILL.md | 3 +- .../multi/dingtalk-misc/references/recruit.md | 64 ++++ test/cli/unregistered_modules_command_test.go | 5 +- 13 files changed, 632 insertions(+), 8 deletions(-) create mode 100644 .changes/976-recruit-job.md create mode 100644 internal/helpers/recruit.go create mode 100644 internal/helpers/recruit_test.go create mode 100644 internal/helpers/register_recruit.go create mode 100644 skills/mono/references/products/recruit.md create mode 100644 skills/multi/dingtalk-misc/references/recruit.md diff --git a/.changes/976-recruit-job.md b/.changes/976-recruit-job.md new file mode 100644 index 00000000..a1be13c3 --- /dev/null +++ b/.changes/976-recruit-job.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **招聘职位管理** (#976) — 新增招聘职位列表、详情查询和职位创建命令。 diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go new file mode 100644 index 00000000..315fbc39 --- /dev/null +++ b/internal/helpers/recruit.go @@ -0,0 +1,284 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package helpers + +import ( + "encoding/json" + "fmt" + "os" + "strings" + + "github.com/spf13/cobra" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" +) + +const ( + recruitServerID = "recruit" + recruitCreateJobTool = "create_job" + recruitGetJobTool = "get_job_detail" + recruitListJobsTool = "list_jobs" +) + +var recruitDryRun = &contract.DryRunSpec{ + PreviewKind: contract.DryRunPreviewInvocation, + RemoteReads: false, +} + +func newRecruitCommand() *cobra.Command { + contract.RegisterProductDecl(contract.ProductDecl{ + ID: "recruit", + Selection: contract.ProductSelectionDecl{ + AgentSummary: "查询和创建钉钉招聘职位", + UseWhen: []string{"需要查询招聘职位列表、查看职位详情或创建职位时"}, + AvoidWhen: []string{"查询企业员工与组织架构使用 contact；查询人才池、职业历程或绩效使用 hrbrain"}, + }, + }) + + root := &cobra.Command{ + Use: "recruit", + Short: "钉钉招聘", + Long: "查询和创建钉钉招聘中的职位信息。", + RunE: groupRunE, + } + job := &cobra.Command{ + Use: "job", + Short: "招聘职位管理", + RunE: groupRunE, + } + job.AddCommand( + newRecruitJobListCommand(), + newRecruitJobGetCommand(), + newRecruitJobCreateCommand(), + ) + root.AddCommand(job) + return root +} + +func newRecruitJobListCommand() *cobra.Command { + return NewLeafCommand(LeafSpec{ + Use: "list", + Short: "查询招聘职位列表", + Long: "按职位 ID、关键词、状态、创建人、职位性质等条件分页查询招聘职位。", + Example: " dws recruit job list --keyword Java --status open --size 20 --format json\n dws recruit job list --job-ids JOB_ID_1,JOB_ID_2 --format json", + Server: recruitServerID, + Tool: recruitListJobsTool, + Safety: recruitSafetyRead(), + Flags: []LeafFlag{ + {Name: "job-ids", Usage: "职位 ID，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "jobIds"}, + {Name: "required-edu", Usage: "学历要求枚举值", Kind: LeafInt, Bind: "requiredEdu"}, + {Name: "status", Usage: "职位状态：draft/open/invalid/closed，多个值用逗号分隔", Bind: "statusList", Trim: true, OmitEmpty: true, Transform: transformRecruitStatuses}, + {Name: "job-nature", Usage: "职位性质", Bind: "jobNature", Trim: true, OmitEmpty: true}, + {Name: "campus", Usage: "是否为校园招聘", Kind: LeafBool, Bind: "campus"}, + {Name: "start-modified-time", Usage: "修改时间范围起点", Bind: "startModifiedTime", Trim: true, OmitEmpty: true}, + {Name: "end-modified-time", Usage: "修改时间范围终点", Bind: "endModifiedTime", Trim: true, OmitEmpty: true}, + {Name: "creator-user-ids", Usage: "创建人 userId，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "creatorUserIds"}, + {Name: "keyword", Usage: "职位搜索关键词", Bind: "keyword", Trim: true, OmitEmpty: true}, + {Name: "category", Usage: "职位分类", Bind: "category", Trim: true, OmitEmpty: true}, + {Name: "cursor", Usage: "分页游标；首次查询不传，翻页时传返回的 nextCursor", Kind: LeafInt, Bind: "cursor"}, + {Name: "size", Usage: "分页大小，默认 20", Kind: LeafInt, Bind: "size", ArgDefault: "20"}, + }, + Validate: validateRecruitList, + Call: runRecruitJobList, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitListJobsTool, CanonicalPath: "recruit.list_jobs", CLIPath: "recruit job list", PrimaryCLIPath: "recruit job list"}, + Description: "按条件分页查询招聘职位", + DryRun: recruitDryRun, + Interface: recruitMCPInterface(recruitListJobsTool), + Selection: contract.SelectionSpec{ + AgentSummary: "按关键词、状态、创建人等条件分页查询招聘职位", + UseWhen: []string{"需要查找职位、筛选在招职位或取得 jobId 时"}, + AvoidWhen: []string{"已经持有明确 jobId 且需要完整详情时使用 recruit job get"}, + Examples: []string{`dws recruit job list --keyword "Java" --status open --size 20 --format json`}, + }, + Parameters: recruitListParamDecls(), + }, + }) +} + +func runRecruitJobList(_ *cobra.Command, tool string, args map[string]any) error { + params := map[string]any{"param": map[string]any{}, "size": args["size"]} + query := params["param"].(map[string]any) + for key, value := range args { + switch key { + case "cursor": + params[key] = value + case "size": + default: + query[key] = value + } + } + return callMCPToolOnServer(recruitServerID, tool, params) +} + +func newRecruitJobGetCommand() *cobra.Command { + return NewLeafCommand(LeafSpec{ + Use: "get", + Short: "查询招聘职位详情", + Long: "根据职位 ID 查询招聘职位详情。", + Example: " dws recruit job get --job-id JOB_ID --format json", + Server: recruitServerID, + Tool: recruitGetJobTool, + Safety: recruitSafetyRead(), + Flags: []LeafFlag{{ + Name: "job-id", Usage: "职位 ID（必填）", Bind: "jobId", Trim: true, + Required: true, RequiredHint: "--job-id 为必填", + }}, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitGetJobTool, CanonicalPath: "recruit.get_job_detail", CLIPath: "recruit job get", PrimaryCLIPath: "recruit job get"}, + Description: "根据职位 ID 查询招聘职位详情", + DryRun: recruitDryRun, + Interface: recruitMCPInterface(recruitGetJobTool), + Selection: contract.SelectionSpec{ + AgentSummary: "获取指定招聘职位的完整信息", + UseWhen: []string{"已经持有明确 jobId，需要查看职位详情时"}, + AvoidWhen: []string{"不知道 jobId 时先使用 recruit job list 查询"}, + Examples: []string{"dws recruit job get --job-id --format json"}, + }, + Parameters: []contract.ParamDecl{{Name: "job-id", Property: "jobId", Required: boolPtr(true), InterfaceType: "string"}}, + }, + }) +} + +func newRecruitJobCreateCommand() *cobra.Command { + return NewLeafCommand(LeafSpec{ + Use: "create", + Short: "创建招聘职位", + Long: "从 JSON 文件读取职位信息并创建招聘职位。该操作会写入远端招聘系统，执行前必须确认。", + Example: " dws recruit job create --from ./job.json --dry-run --format json\n dws recruit job create --from ./job.json --format json", + Server: recruitServerID, + Tool: recruitCreateJobTool, + Safety: recruitSafetyCreate(), + Flags: []LeafFlag{{ + Name: "from", Usage: "职位 JSON 文件路径（必填）", Bind: "atsAddJobParam", Trim: true, + Required: true, RequiredHint: "--from 为必填", Transform: loadRecruitJobFile, + }}, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitCreateJobTool, CanonicalPath: "recruit.create_job", CLIPath: "recruit job create", PrimaryCLIPath: "recruit job create"}, + Description: "从 JSON 文件创建招聘职位", + DryRun: recruitDryRun, + Interface: recruitMCPInterface(recruitCreateJobTool), + Selection: contract.SelectionSpec{ + AgentSummary: "使用结构化 JSON 创建招聘职位", + UseWhen: []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、minSalary、maxSalary"}, + AvoidWhen: []string{"仅查询职位时使用 recruit job list 或 recruit job get"}, + Examples: []string{"dws recruit job create --from ./job.json --dry-run --format json"}, + }, + Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 读取后作为 atsAddJobParam 对象发送"}}, + }, + }) +} + +func recruitListParamDecls() []contract.ParamDecl { + return []contract.ParamDecl{ + {Name: "job-ids", Property: "param.jobIds", InterfaceType: "array"}, + {Name: "required-edu", Property: "param.requiredEdu", InterfaceType: "number"}, + {Name: "status", Property: "param.statusList", InterfaceType: "array", Enum: []string{"draft", "open", "invalid", "closed"}}, + {Name: "job-nature", Property: "param.jobNature", InterfaceType: "string"}, + {Name: "campus", Property: "param.campus", InterfaceType: "boolean"}, + {Name: "start-modified-time", Property: "param.startModifiedTime", InterfaceType: "string"}, + {Name: "end-modified-time", Property: "param.endModifiedTime", InterfaceType: "string"}, + {Name: "creator-user-ids", Property: "param.creatorUserIds", InterfaceType: "array"}, + {Name: "keyword", Property: "param.keyword", InterfaceType: "string"}, + {Name: "category", Property: "param.category", InterfaceType: "string"}, + {Name: "cursor", Property: "cursor", InterfaceType: "number"}, + {Name: "size", Property: "size", Required: boolPtr(true), InterfaceType: "number"}, + } +} + +func recruitMCPInterface(tool string) *contract.InterfaceSpec { + return &contract.InterfaceSpec{ + Mode: contract.InterfaceModeMCP, + Availability: contract.InterfaceAvailable, + Ref: &contract.InterfaceRefSpec{ProductID: recruitServerID, RPCName: tool}, + } +} + +func recruitSafetyRead() contract.SafetySpec { + return contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"} +} + +func recruitSafetyCreate() contract.SafetySpec { + return contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "non_idempotent"} +} + +func transformRecruitStatuses(raw string) (any, error) { + values := strings.Split(raw, ",") + statuses := make([]int, 0, len(values)) + seen := make(map[int]bool, len(values)) + lookup := map[string]int{"draft": 0, "open": 1, "invalid": 2, "closed": 3} + for _, value := range values { + name := strings.ToLower(strings.TrimSpace(value)) + if name == "" { + continue + } + status, ok := lookup[name] + if !ok { + return nil, apperrors.NewValidation(fmt.Sprintf("--status 不支持 %q，可选 draft/open/invalid/closed", value)) + } + if !seen[status] { + statuses = append(statuses, status) + seen[status] = true + } + } + return statuses, nil +} + +func validateRecruitList(cmd *cobra.Command, _ []string) error { + if cursor, _ := cmd.Flags().GetInt("cursor"); cursor < 0 { + return apperrors.NewValidation("--cursor 必须大于或等于 0") + } + size, _ := cmd.Flags().GetInt("size") + if cmd.Flags().Changed("size") && (size < 1 || size > 100) { + return apperrors.NewValidation("--size 必须在 1 到 100 之间") + } + return nil +} + +func loadRecruitJobFile(path string) (any, error) { + data, err := os.ReadFile(strings.TrimSpace(path)) + if err != nil { + return nil, fmt.Errorf("读取职位 JSON 失败: %w", err) + } + var job map[string]any + if err := json.Unmarshal(data, &job); err != nil { + return nil, apperrors.NewValidation(fmt.Sprintf("职位文件不是有效的 JSON 对象: %v", err)) + } + if job == nil { + return nil, apperrors.NewValidation("职位 JSON 顶层必须是对象") + } + if err := validateRecruitJob(job); err != nil { + return nil, err + } + return job, nil +} + +func validateRecruitJob(job map[string]any) error { + for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "minSalary", "maxSalary"} { + value, ok := job[name] + if !ok || value == nil || (isString(value) && strings.TrimSpace(value.(string)) == "") { + return apperrors.NewValidation(fmt.Sprintf("职位 JSON 缺少必填字段 %s", name)) + } + } + for _, name := range []string{"name", "description", "jobNature"} { + if !isString(job[name]) { + return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是字符串", name)) + } + } + for _, name := range []string{"requiredEdu", "minSalary", "maxSalary"} { + if _, ok := job[name].(float64); !ok { + return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是数字", name)) + } + } + if job["minSalary"].(float64) > job["maxSalary"].(float64) { + return apperrors.NewValidation("职位 JSON 中 minSalary 不能大于 maxSalary") + } + return nil +} + +func isString(value any) bool { + _, ok := value.(string) + return ok +} diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go new file mode 100644 index 00000000..274ab409 --- /dev/null +++ b/internal/helpers/recruit_test.go @@ -0,0 +1,207 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package helpers + +import ( + "context" + "encoding/json" + stderrors "errors" + "io" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" +) + +type recruitCapturedCall struct { + productID string + tool string + args map[string]any +} + +type recruitCaptureCaller struct { + productID string + tool string + args map[string]any + calls []recruitCapturedCall +} + +func (c *recruitCaptureCaller) CallTool(_ context.Context, productID, tool string, args map[string]any) (*edition.ToolResult, error) { + c.productID = productID + c.tool = tool + c.args = args + c.calls = append(c.calls, recruitCapturedCall{productID: productID, tool: tool, args: args}) + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{}`}}}, nil +} + +func (c *recruitCaptureCaller) Format() string { return "json" } +func (c *recruitCaptureCaller) DryRun() bool { return false } +func (c *recruitCaptureCaller) Fields() string { return "" } +func (c *recruitCaptureCaller) JQ() string { return "" } + +func withRecruitCaller(t *testing.T) *recruitCaptureCaller { + t.Helper() + caller := &recruitCaptureCaller{} + InitDepsForTest(t, caller) + deps.Out.w = io.Discard + return caller +} + +func TestRecruitJobListWrapsQueryParameters(t *testing.T) { + caller := withRecruitCaller(t) + cmd := newRecruitJobListCommand() + cmd.SetArgs([]string{ + "--keyword", "Java", "--status", "open,draft", "--creator-user-ids", "u1,u2", + "--campus=false", "--cursor", "10", "--size", "30", + }) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if caller.productID != recruitServerID || caller.tool != recruitListJobsTool { + t.Fatalf("dispatch = %s/%s, want %s/%s", caller.productID, caller.tool, recruitServerID, recruitListJobsTool) + } + if caller.args["cursor"] != 10 || caller.args["size"] != 30 { + t.Fatalf("pagination args = %#v", caller.args) + } + param, ok := caller.args["param"].(map[string]any) + if !ok { + t.Fatalf("param = %#v, want object", caller.args["param"]) + } + if param["keyword"] != "Java" || param["campus"] != false { + t.Fatalf("param = %#v", param) + } + statuses, ok := param["statusList"].([]int) + if !ok || len(statuses) != 2 || statuses[0] != 1 || statuses[1] != 0 { + t.Fatalf("statusList = %#v", param["statusList"]) + } + creators, ok := param["creatorUserIds"].([]string) + if !ok || len(creators) != 2 || creators[0] != "u1" || creators[1] != "u2" { + t.Fatalf("creatorUserIds = %#v", param["creatorUserIds"]) + } +} + +func TestRecruitJobListDefaultsAndValidation(t *testing.T) { + caller := withRecruitCaller(t) + cmd := newRecruitJobListCommand() + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if caller.args["size"] != 20 { + t.Fatalf("size = %#v, want 20", caller.args["size"]) + } + if _, ok := caller.args["cursor"]; ok { + t.Fatalf("first page unexpectedly sent cursor: %#v", caller.args) + } + + badStatus := newRecruitJobListCommand() + badStatus.SetArgs([]string{"--status", "unknown"}) + if err := badStatus.Execute(); err == nil || !strings.Contains(err.Error(), "draft/open/invalid/closed") { + t.Fatalf("invalid status error = %v", err) + } + + badSize := newRecruitJobListCommand() + badSize.SetArgs([]string{"--size", "101"}) + if err := badSize.Execute(); err == nil || !strings.Contains(err.Error(), "1 到 100") { + t.Fatalf("invalid size error = %v", err) + } +} + +func TestRecruitJobGetDispatchesJobID(t *testing.T) { + caller := withRecruitCaller(t) + cmd := newRecruitJobGetCommand() + cmd.SetArgs([]string{"--job-id", "job-1"}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if caller.productID != recruitServerID || caller.tool != recruitGetJobTool || caller.args["jobId"] != "job-1" { + t.Fatalf("captured call = %s/%s %#v", caller.productID, caller.tool, caller.args) + } +} + +func writeRecruitJobFixture(t *testing.T) (string, map[string]any) { + t.Helper() + path := filepath.Join(t.TempDir(), "job.json") + job := map[string]any{ + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", + "requiredEdu": 1, "minSalary": 20000, "maxSalary": 35000, + } + data, err := json.Marshal(job) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, data, 0o600); err != nil { + t.Fatal(err) + } + return path, job +} + +func TestRecruitJobCreateRequiresConfirmationBeforeRemoteCall(t *testing.T) { + caller := withRecruitCaller(t) + path, _ := writeRecruitJobFixture(t) + cmd := newRecruitJobCreateCommand() + cmd.Flags().Bool("yes", false, "确认创建") + cmd.SetIn(strings.NewReader("")) + cmd.SetArgs([]string{"--from", path}) + err := cmd.Execute() + var appErr *apperrors.Error + if !stderrors.As(err, &appErr) || appErr.Reason != "confirmation_required" { + t.Fatalf("create without confirmation error = %T %v, want confirmation_required", err, err) + } + if len(caller.calls) != 0 { + t.Fatalf("MCP calls before confirmation = %d: %#v, want none", len(caller.calls), caller.calls) + } +} + +func TestRecruitJobCreateCallsRemoteOnceWhenConfirmed(t *testing.T) { + caller := withRecruitCaller(t) + path, _ := writeRecruitJobFixture(t) + cmd := newRecruitJobCreateCommand() + cmd.Flags().Bool("yes", false, "确认创建") + cmd.SetArgs([]string{"--from", path, "--yes"}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("MCP calls after confirmation = %d: %#v, want exactly one", len(caller.calls), caller.calls) + } + call := caller.calls[0] + if call.productID != recruitServerID || call.tool != recruitCreateJobTool { + t.Fatalf("dispatch = %s/%s, want %s/%s", call.productID, call.tool, recruitServerID, recruitCreateJobTool) + } + wantArgs := map[string]any{"atsAddJobParam": map[string]any{ + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", + "requiredEdu": float64(1), "minSalary": float64(20000), "maxSalary": float64(35000), + }} + if !reflect.DeepEqual(call.args, wantArgs) { + t.Fatalf("args = %#v, want %#v", call.args, wantArgs) + } +} + +func TestRecruitCreateValidatesJobFile(t *testing.T) { + withRecruitCaller(t) + badPath := filepath.Join(t.TempDir(), "bad-job.json") + if err := os.WriteFile(badPath, []byte(`{"name":"缺字段"}`), 0o600); err != nil { + t.Fatal(err) + } + bad := newRecruitJobCreateCommand() + bad.Flags().Bool("yes", false, "确认创建") + bad.SetArgs([]string{"--from", badPath, "--yes"}) + if err := bad.Execute(); err == nil || !strings.Contains(err.Error(), "description") { + t.Fatalf("missing field error = %v", err) + } +} + +func TestRecruitCommandTree(t *testing.T) { + root := newRecruitCommand() + for _, path := range [][]string{{"job", "list"}, {"job", "get"}, {"job", "create"}} { + cmd, _, err := root.Find(path) + if err != nil || cmd == root || cmd.Name() != path[len(path)-1] { + t.Fatalf("Find(%v) = %v, %v", path, cmd, err) + } + } +} diff --git a/internal/helpers/register_products_test.go b/internal/helpers/register_products_test.go index 7e89a565..16933d43 100644 --- a/internal/helpers/register_products_test.go +++ b/internal/helpers/register_products_test.go @@ -31,7 +31,7 @@ func TestCrossPlatformCoveragePublicProductCommandsBuildCompleteUniqueTrees(t *t for _, want := range []string{ "agoal", "aisearch", "aitable", "attendance", "calendar", "chat", "contact", "devdoc", "ding", "doc", "drive", "live", "mail", - "markdown", "minutes", "oa", "report", "sheet", "todo", "wiki", "whiteboard", + "markdown", "minutes", "oa", "recruit", "report", "sheet", "todo", "wiki", "whiteboard", } { if !seenProducts[want] { t.Errorf("public product %q was not registered", want) diff --git a/internal/helpers/register_recruit.go b/internal/helpers/register_recruit.go new file mode 100644 index 00000000..3ba9ceb2 --- /dev/null +++ b/internal/helpers/register_recruit.go @@ -0,0 +1,11 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package helpers + +// 招聘是开源库显式维护的公开命令，不依赖生成式产品注册表。 +func init() { + RegisterPublic(func() Handler { + return wukongHandler{name: "recruit", buildFn: newRecruitCommand} + }) +} diff --git a/pkg/edition/default.go b/pkg/edition/default.go index 5e0310b6..04e92642 100644 --- a/pkg/edition/default.go +++ b/pkg/edition/default.go @@ -43,11 +43,11 @@ func defaultHooks() *Hooks { } } -// openSupplementServers returns helper-only MCP endpoints owned by the open -// CLI. They are callable by explicit server ID but are deliberately excluded -// from VisibleProducts, so no top-level product command is generated. They -// stay separate from syncdata.StaticServers because only explicitly wired CLI -// helpers may call them; they are not public MCP product surfaces. +// openSupplementServers returns explicitly wired MCP endpoints owned by the +// open CLI. They are callable by explicit server ID but are deliberately +// excluded from VisibleProducts, so this hook never generates a top-level +// product command. A public command using one of these endpoints must register +// its Cobra tree explicitly via helpers.RegisterPublic. func openSupplementServers() []ServerInfo { return []ServerInfo{ { @@ -60,6 +60,12 @@ func openSupplementServers() []ServerInfo { Name: "钉钉白板", Endpoint: "https://mcp-gw.dingtalk.com/server/whiteboard", }, + { + ID: "recruit", + Name: "钉钉招聘", + Endpoint: "https://mcp-gw.dingtalk.com/server/f69b54ada16c57b603c0e5e1c36f464ba73dcee28d64bb701ff2682c259c0cff", + Prefixes: []string{"recruit", "job"}, + }, } } diff --git a/pkg/edition/edition_test.go b/pkg/edition/edition_test.go index c581c714..7418836e 100644 --- a/pkg/edition/edition_test.go +++ b/pkg/edition/edition_test.go @@ -107,7 +107,12 @@ func TestOpenSupplementServersIncludesMCPMeta(t *testing.T) { servers := openSupplementServers() foundMCPMeta := false foundWhiteboard := false + foundRecruit := false for _, server := range servers { + if server.ID == "recruit" { + foundRecruit = server.Endpoint == "https://mcp-gw.dingtalk.com/server/f69b54ada16c57b603c0e5e1c36f464ba73dcee28d64bb701ff2682c259c0cff" && + len(server.Prefixes) == 2 && server.Prefixes[0] == "recruit" && server.Prefixes[1] == "job" + } if server.ID == "whiteboard" { foundWhiteboard = server.Endpoint == "https://mcp-gw.dingtalk.com/server/whiteboard" } @@ -128,4 +133,7 @@ func TestOpenSupplementServersIncludesMCPMeta(t *testing.T) { if !foundWhiteboard { t.Fatal("openSupplementServers() missing helper-only whiteboard endpoint") } + if !foundRecruit { + t.Fatal("openSupplementServers() missing explicitly wired recruit endpoint") + } } diff --git a/skills/content-qa/mono-multi-coverage.yaml b/skills/content-qa/mono-multi-coverage.yaml index 440c149e..8dc8895a 100644 --- a/skills/content-qa/mono-multi-coverage.yaml +++ b/skills/content-qa/mono-multi-coverage.yaml @@ -108,6 +108,10 @@ coverage: multi_skill: dingtalk-misc multi_refs: - references/whiteboard.md + - mono: recruit + multi_skill: dingtalk-misc + multi_refs: + - references/recruit.md omit_coverage: - mono: simple diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index 8fbd5975..3f491809 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -94,6 +94,7 @@ cli_version: ">=1.0.15" | `todo` | 待办：创建(含优先级/截止时间/循环)/查询/修改/标记完成/删除 | [todo.md](./references/products/todo.md) | | `wiki` | 知识库：空间创建/详情/列表/搜索 + 成员管理 + 知识库动态查询 | [wiki.md](./references/products/wiki.md) | | `whiteboard` | 文档内嵌白板：读取 OpenNodes、追加节点、整页重建 | [whiteboard.md](./references/products/whiteboard.md) | +| `recruit` | 钉钉招聘：查询职位列表、获取职位详情、创建职位 | [recruit.md](./references/products/recruit.md) | | `event` | 个人 IM/OA 事件：监听消息、群生命周期、审批任务与审批实例事件，NDJSON 输出（实时驱动 Agent）| [event.md](./references/products/event.md) | ## 意图判断决策树 @@ -121,6 +122,7 @@ cli_version: ">=1.0.15" 用户提到"待办/TODO/任务提醒/循环待办" → `todo` 用户提到"创建知识库/知识库列表/搜索知识库空间/wiki/团队空间/知识库成员管理/我的文档个人空间" → `wiki` 用户提到"文档内嵌白板/画布/OpenNodes/白板节点/连接线/整页重建白板" → `whiteboard`；创建空白板卡片先走 `doc whiteboard insert` +用户提到"招聘/职位/JD/在招职位/创建职位/职位详情" → `recruit` 用户提到"监听有人@我/监听单聊或群消息/监听所有单聊或群消息/监听某人发送的消息/监听消息已读/监听消息撤回/监听消息贴表情或表情回应/订阅个人 IM 事件/实时接收钉钉事件/监听并自动回复消息/驱动 Agent 处理消息" → `event +listen-im`；群成员加入/退出、群改名/解散或明确原始 EventKey/Filter DSL → `event consume` 用户提到"监听待我审批的任务/监听审批任务创建、完成或转交/监听审批单发起或终止/监听我发起的审批完成/监听审批实例完成/订阅 OA 事件/event consume user_oa_approval_*" → `event consume` diff --git a/skills/mono/references/products/recruit.md b/skills/mono/references/products/recruit.md new file mode 100644 index 00000000..6c2b48f8 --- /dev/null +++ b/skills/mono/references/products/recruit.md @@ -0,0 +1,29 @@ +# 钉钉招聘 + +`dws recruit` 提供招聘职位列表、职位详情和职位创建能力。组织、业务标识和当前 +操作人由登录身份及 MCP Connector 注入，不要要求用户提供或猜测身份字段。 + +## 查询 + +```bash +dws recruit job list --keyword "Java" --status open --size 20 --format json +dws recruit job get --job-id JOB_ID --format json +``` + +列表状态支持 `draft`、`open`、`invalid`、`closed`。首页不传 `--cursor`； +`hasMore=true` 时把响应 `nextCursor` 回填。查询详情前必须从真实列表结果取得 +`jobId`。 + +## 创建 + +创建是非幂等写操作。先用 `--dry-run` 检查；实际执行必须经过用户明确确认，并 +交由 CLI 的确认流程处理： + +```bash +dws recruit job create --from ./job.json --dry-run --format json +dws recruit job create --from ./job.json --format json +``` + +JSON 必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、 +`minSalary`、`maxSalary`。后三者为数字，且最低薪资不得大于最高薪资。文件只写 +职位对象，不要添加 MCP 信封字段 `atsAddJobParam`。 diff --git a/skills/multi/dingtalk-misc/SKILL.md b/skills/multi/dingtalk-misc/SKILL.md index 487f8c7f..d4eed650 100644 --- a/skills/multi/dingtalk-misc/SKILL.md +++ b/skills/multi/dingtalk-misc/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-misc -description: 长尾产品集合技能，覆盖低频钉钉产品：OA审批查询与处理/考勤/直播/DING紧急消息/开放平台应用管理/Agoal目标管理/日志日报周报/电子表格/开放平台文档搜索/文档内嵌白板/DWS技能市场安装/组织大脑Hrbrain/原生Markdown/PAT行为授权/多组织profile。Use when 用户提到上述任一产品，或查待审批/同意拒绝转交撤销审批/打卡/排班/OKR/日报周报/单元格读写/白板节点读写/搜索安装技能/开发者后台应用/人才池/员工档案/职业历程/绩效/原生.md文件/PAT授权/切换组织/跨组织/profile 等相关操作。未来审批任务或实例变化的实时监听不属于本 skill，应使用 dingtalk-event。命中后由本 skill 的「产品索引表」定位具体子产品和命令前缀，再按对应子产品说明执行。 +description: 长尾产品集合技能，覆盖低频钉钉产品：OA审批查询与处理/考勤/直播/DING紧急消息/开放平台应用管理/Agoal目标管理/日志日报周报/电子表格/开放平台文档搜索/文档内嵌白板/钉钉招聘/DWS技能市场安装/组织大脑Hrbrain/原生Markdown/PAT行为授权/多组织profile。Use when 用户提到上述任一产品，或查待审批/同意拒绝转交撤销审批/打卡/排班/OKR/日报周报/单元格读写/白板节点读写/招聘职位/JD/创建职位/搜索安装技能/开发者后台应用/人才池/员工档案/职业历程/绩效/原生.md文件/PAT授权/切换组织/跨组织/profile 等相关操作。未来审批任务或实例变化的实时监听不属于本 skill，应使用 dingtalk-event。命中后由本 skill 的「产品索引表」定位具体子产品和命令前缀，再按对应子产品说明执行。 metadata: cli_version: ">=0.2.14" category: product @@ -31,6 +31,7 @@ metadata: | 电子表格 / 工作表 / 单元格读写 / 公式 / 超链接 / 浮动图片 | 电子表格创建/读写/公式/超链接/浮动图片/导出 | `dws sheet` | [sheet.md](references/sheet.md) | | 开放平台文档 / API文档 / 接口文档 / 接口报错 | 开放平台开发文档搜索 | `dws devdoc` | [devdoc.md](references/devdoc.md) | | 白板 / 画布 / OpenNodes / 白板节点 | 读取和更新钉钉文档中的内嵌白板 | `dws whiteboard` | [whiteboard.md](references/whiteboard.md) | +| 招聘 / 职位 / JD / 在招职位 / 创建职位 / 职位详情 | 钉钉招聘职位的查询、详情与创建 | `dws recruit` | [recruit.md](references/recruit.md) | | 搜索技能 / 找技能 / 安装技能 / 技能市场 / 安装 DWS mono 或 multi skill | DWS 技能市场搜索、下载、安装与内置技能部署 | `dws skill` | [skill.md](references/skill.md) | | 人才池 / 储备干部池 / 员工档案 / 职业历程 / 绩效记录 / 员工标签 / 组织大脑 / 人才搜索 | 组织大脑：人才池、员工档案专项模块与结构化人才搜索 | `dws hrbrain` | [hrbrain.md](references/hrbrain.md) | | 原生 Markdown / `.md` 原文 / 覆盖 Markdown / 局部替换 Markdown | 原生 `.md` 文件读取、创建、全量覆盖与局部替换 | `dws markdown` | [markdown.md](references/markdown.md) | diff --git a/skills/multi/dingtalk-misc/references/recruit.md b/skills/multi/dingtalk-misc/references/recruit.md new file mode 100644 index 00000000..d6209be9 --- /dev/null +++ b/skills/multi/dingtalk-misc/references/recruit.md @@ -0,0 +1,64 @@ +# 钉钉招聘 + +`dws recruit` 查询和创建钉钉招聘职位。当前公开命令只覆盖职位列表、职位详情和 +职位创建；候选人、面试、Offer、职位修改、开放或关闭尚未作为稳定命令发布。 + +所有命令都应加 `--format json`。组织、业务标识和当前操作人由登录身份及 MCP +Connector 注入，不要要求用户提供或猜测 `corpId`、`bizCode`、`opUserId`。 + +## 查询职位列表 + +```bash +dws recruit job list --format json +dws recruit job list --keyword "Java" --status open --size 20 --format json +dws recruit job list --job-ids JOB_ID_1,JOB_ID_2 --format json +``` + +可选筛选包括 `--job-ids`、`--required-edu`、`--status`、`--job-nature`、 +`--campus`、`--start-modified-time`、`--end-modified-time`、 +`--creator-user-ids`、`--keyword`、`--category`。状态接受： + +- `draft`：草稿 +- `open`：招聘中 +- `invalid`：已失效 +- `closed`：已关闭/完成 + +`--size` 默认 20，范围 1–100。首页不传 `--cursor`；响应 `hasMore=true` 时， +把 `nextCursor` 回填到下一次查询。 + +## 查询职位详情 + +先从列表结果取得真实 `jobId`，不得编造： + +```bash +dws recruit job get --job-id JOB_ID --format json +``` + +## 创建职位 + +创建是非幂等远端写入。先准备只包含职位对象的 UTF-8 JSON 文件，并用 +`--dry-run` 检查完整调用；向用户展示职位名称、性质、薪资和负责人，取得明确 +确认后，交由 CLI 的确认流程执行实际创建。不要在存储示例中加入确认绕过参数。 + +```bash +dws recruit job create --from ./job.json --dry-run --format json +dws recruit job create --from ./job.json --format json +``` + +最小 `job.json`： + +```json +{ + "name": "Java 开发工程师", + "description": "负责服务端系统开发", + "jobNature": "FULL_TIME", + "requiredEdu": 1, + "minSalary": 20000, + "maxSalary": 35000 +} +``` + +六个字段均为必填；`requiredEdu`、`minSalary`、`maxSalary` 必须为数字，且 +`minSalary` 不得大于 `maxSalary`。可选字段以当前 +`dws recruit job create --help` 和 leaf Schema 为准；不要把 MCP 信封字段 +`atsAddJobParam` 写进文件，CLI 会自动包装。 diff --git a/test/cli/unregistered_modules_command_test.go b/test/cli/unregistered_modules_command_test.go index 1f89476c..89d0f01a 100644 --- a/test/cli/unregistered_modules_command_test.go +++ b/test/cli/unregistered_modules_command_test.go @@ -22,7 +22,7 @@ func TestRootHelpHidesRecoveredModules(t *testing.T) { // All of these commands should be hidden because they are not in // the dynamic server discovery product list. for _, module := range []string{ - "aisearch", "contract", "recruit", + "aisearch", "contract", "chat", "drive", "minutes", "mail", "credit", "credit-risk", "finance", "message", "notify", "doc", } { @@ -30,4 +30,7 @@ func TestRootHelpHidesRecoveredModules(t *testing.T) { t.Fatalf("root help should not show hidden module %q:\n%s", module, got) } } + if !strings.Contains(got, "● recruit ") { + t.Fatalf("root help should show explicitly registered recruit module:\n%s", got) + } } From 19a21b8f7e788034667cbac61c90d5b05aff516d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 10:54:51 +0800 Subject: [PATCH 043/250] fix(chat): avoid explicit zone in list-all formatting --- internal/helpers/chat.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 532a1584..34a45d0f 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -622,7 +622,7 @@ func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (st } func formatChatMessageListAllTime(ms int64) string { - return time.UnixMilli(ms).In(shanghaiLocation()).Format("2006-01-02 15:04:05") + return time.UnixMilli(ms).Format("2006-01-02 15:04:05") } func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { From a55880ce82442f6bea08b2de0cb209654aa3e1b1 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 11:10:53 +0800 Subject: [PATCH 044/250] fix(drive): reject unsafe remote names --- internal/helpers/drive_push.go | 15 +-- internal/helpers/drive_push_coverage_test.go | 11 +- .../helpers/drive_remote_unsafe_name_test.go | 125 ++++++++++++++++++ internal/helpers/drive_status.go | 38 ++++-- .../helpers/drive_status_coverage_test.go | 6 +- 5 files changed, 162 insertions(+), 33 deletions(-) create mode 100644 internal/helpers/drive_remote_unsafe_name_test.go diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index 5d790824..ff617007 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -5,7 +5,6 @@ import ( "encoding/json" "fmt" "io/fs" - "log/slog" "path/filepath" "sort" "strings" @@ -257,13 +256,11 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f } for _, it := range items { - name := it.name() - if name == "" { - continue + name, included, err := remoteMirrorEntryName(it, relBase) + if err != nil { + return err } - // 与 walkRemoteDir 一致：非规范名称跳过，避免逃逸性 rel_path 进入索引。 - if !isSafeRemoteSegment(name) { - slog.Warn("overlay: 跳过含非法路径成分的远端条目", "name", name, "relBase", relBase) + if !included { continue } childRel := name @@ -284,9 +281,7 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f } continue } - if !it.isFile() { - continue - } + // 非文件类型已由 remoteMirrorEntryName 过滤；目录在上方完成递归后返回。 if err := claimRemotePath(occupied, childRel, "文件"); err != nil { return err } diff --git a/internal/helpers/drive_push_coverage_test.go b/internal/helpers/drive_push_coverage_test.go index c279ae3f..494ef24c 100644 --- a/internal/helpers/drive_push_coverage_test.go +++ b/internal/helpers/drive_push_coverage_test.go @@ -283,7 +283,7 @@ func TestCrossPlatformCoverageDrivePush_missingLocalRootFails(t *testing.T) { } // ────────────────────────────────────────────────────────── -// walkRemoteForPush — 分页、递归、深度上限、非法/空名跳过 +// walkRemoteForPush — 分页、递归、深度上限、非镜像类型跳过 // ────────────────────────────────────────────────────────── func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *testing.T) { @@ -299,8 +299,7 @@ func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *t } if parent == "ROOT" && token == "P2" { return `{"result":{"items":[` + - `{"name":"","type":"file","fileId":"EMPTY"},` + - `{"name":"../bad.txt","type":"file","fileId":"BAD"},` + + `{"name":"online.adoc","type":"document","fileId":"DOC"},` + `{"name":"ok.txt","type":"file","fileId":"OK"}` + `],"nextToken":""}}`, nil } @@ -325,10 +324,8 @@ func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *t if _, ok := files["ok.txt"]; !ok { t.Error("second page file must be indexed") } - for _, bad := range []string{"", "../bad.txt"} { - if _, ok := files[bad]; ok { - t.Errorf("unsafe/empty name %q must be skipped", bad) - } + if _, ok := files["online.adoc"]; ok { + t.Error("non-file document must remain outside the folder mirror index") } } diff --git a/internal/helpers/drive_remote_unsafe_name_test.go b/internal/helpers/drive_remote_unsafe_name_test.go new file mode 100644 index 00000000..393f2fb7 --- /dev/null +++ b/internal/helpers/drive_remote_unsafe_name_test.go @@ -0,0 +1,125 @@ +package helpers + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageDriveRemoteTree_unsafeNamesFailClosed(t *testing.T) { + tests := []struct { + name string + listing string + wantKind string + }{ + { + name: "file name containing a backslash", + listing: `{"result":{"items":[{"name":"a\\b.txt","type":"file","fileId":"UNSAFE_FILE"}],"nextToken":""}}`, + wantKind: "文件", + }, + { + name: "folder name escaping its parent", + listing: `{"result":{"items":[{"name":"..","type":"folder","fileId":"UNSAFE_FOLDER"}],"nextToken":""}}`, + wantKind: "目录", + }, + } + + commands := []struct { + name string + args func(localRoot string) []string + prepare func(t *testing.T, localRoot string) + }{ + { + name: "status", + args: func(localRoot string) []string { + return []string{"status", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"} + }, + prepare: func(t *testing.T, localRoot string) { + t.Helper() + if err := os.MkdirAll(localRoot, 0o755); err != nil { + t.Fatal(err) + } + }, + }, + { + name: "pull", + args: func(localRoot string) []string { + return []string{"pull", "--local-folder", localRoot, "--remote-folder", "ROOT"} + }, + }, + { + name: "push", + args: func(localRoot string) []string { + return []string{"push", "--local-folder", localRoot, "--remote-folder", "ROOT"} + }, + prepare: prepareUnsafeNameWriteSource, + }, + { + name: "sync", + args: func(localRoot string) []string { + return []string{"sync", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"} + }, + prepare: prepareUnsafeNameWriteSource, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + for _, command := range commands { + t.Run(command.name, func(t *testing.T) { + localRoot := filepath.Join(t.TempDir(), "mirror") + if command.prepare != nil { + command.prepare(t, localRoot) + } + + caller := &driveScriptCaller{reply: func(tool string, args map[string]any, nth int) (string, error) { + if tool != "list_files" || nth != 0 || args["parentId"] != "ROOT" { + t.Fatalf("unsafe remote entry must stop before recursion: tool=%s nth=%d args=%v", tool, nth, args) + } + return tt.listing, nil + }} + getCalls, putCalls := 0, 0 + testseam.Swap(t, &httpGetFile, func(context.Context, string, map[string]string, string) error { + getCalls++ + return nil + }) + testseam.Swap(t, &httpPutFile, func(context.Context, string, map[string]string, string, int64) error { + putCalls++ + return nil + }) + + err := runDriveCmd(t, caller, command.args(localRoot)...) + if err == nil || !strings.Contains(err.Error(), "无法安全映射到本地路径") || + !strings.Contains(err.Error(), tt.wantKind) { + t.Fatalf("error = %v, want unsafe remote %s name failure", err, tt.wantKind) + } + if got := len(caller.callsFor("list_files")); got != 1 { + t.Fatalf("list_files calls = %d, want only the root query", got) + } + for _, tool := range []string{"create_folder", "download_file", "get_upload_info", "commit_upload"} { + if calls := caller.callsFor(tool); len(calls) != 0 { + t.Fatalf("unsafe remote name must not call %s: %v", tool, calls) + } + } + if getCalls != 0 || putCalls != 0 { + t.Fatalf("unsafe remote name must not transfer content: GET=%d PUT=%d", getCalls, putCalls) + } + if command.name == "pull" { + if _, statErr := os.Stat(localRoot); !os.IsNotExist(statErr) { + t.Fatalf("pull must fail before creating its local root: %v", statErr) + } + } + }) + } + }) + } +} + +func prepareUnsafeNameWriteSource(t *testing.T, localRoot string) { + t.Helper() + mustWrite(t, filepath.Join(localRoot, "local.txt"), "local") +} diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index c1075e73..09e9319b 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -8,7 +8,6 @@ import ( "fmt" "io" "io/fs" - "log/slog" "os" "path/filepath" "sort" @@ -133,14 +132,11 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m } for _, it := range items { - name := it.name() - if name == "" { - continue + name, included, err := remoteMirrorEntryName(it, relBase) + if err != nil { + return err } - // 远端名称可能含 ..、分隔符或卷标，拼进 rel_path 会逃逸本地根目录： - // 非规范名称直接跳过（同名文件夹也不递归），不纳入索引。 - if !isSafeRemoteSegment(name) { - slog.Warn("overlay: 跳过含非法路径成分的远端条目", "name", name, "relBase", relBase) + if !included { continue } // rel_path 由文件夹名逐层拼接，统一用 / 分隔，与本地相对路径对齐。 @@ -163,10 +159,7 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m } continue } - // 只纳入明确 type=FILE 的条目；在线文档、快捷方式等其它类型一律跳过。 - if !it.isFile() { - continue - } + // 非文件类型已由 remoteMirrorEntryName 过滤；目录在上方完成递归后返回。 if err := claimRemotePath(occupied, childRel, "文件"); err != nil { return err } @@ -201,6 +194,27 @@ func claimRemotePath(occupied map[string]string, rel, kind string) error { return nil } +// remoteMirrorEntryName 只选择文件夹镜像支持的 file / folder 条目，并验证其名称 +// 能安全、无歧义地表示为本地单层路径。无法表示的镜像条目必须中止整棵远端树构建； +// 静默跳过会让 status/pull/push/sync 在遗漏文件或目录子树时误报成功。 +func remoteMirrorEntryName(it driveItem, relBase string) (string, bool, error) { + kind := "" + switch { + case it.isFolder(): + kind = "目录" + case it.isFile(): + kind = "文件" + default: + return "", false, nil + } + + name := it.name() + if !isSafeRemoteSegment(name) { + return "", false, fmt.Errorf("远端%s名称 %q 无法安全映射到本地路径（父路径 %q），已中止", kind, name, relBase) + } + return name, true, nil +} + // callDriveListFiles 让文件夹同步族在 --dry-run 下仍可通过受控只读通道获取 // 远端现状；普通 CallTool 在 dry-run 下只会返回执行计划，不能被当作业务数据解析。 func callDriveListFiles(ctx context.Context, args map[string]any) (string, error) { diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index 79222ce0..fdfed660 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -120,9 +120,7 @@ func TestCrossPlatformCoverageDriveStatus_endToEndNestedTree(t *testing.T) { return `{"result":{"items":[` + `{"name":"root.txt","type":"file","fileId":"R1","modifyTime":1000},` + `{"name":"sub","type":"folder","fileId":"SUB"},` + - `{"name":"online.adoc","type":"document","fileId":"D1"},` + - `{"name":"","type":"file","fileId":"EMPTY"},` + - `{"name":"../escape.txt","type":"file","fileId":"BAD"}` + + `{"name":"online.adoc","type":"document","fileId":"D1"}` + `],"nextToken":""}}`, nil case "SUB": return `{"result":{"items":[{"name":"nested.txt","type":"file","fileId":"N1","modifyTime":2000}],"nextToken":""}}`, nil @@ -134,7 +132,7 @@ func TestCrossPlatformCoverageDriveStatus_endToEndNestedTree(t *testing.T) { t.Fatalf("unexpected error: %v", err) } - // 递归进入 sub 一次；空名/非法名/在线文档都不产生额外调用。 + // 递归进入 sub 一次；不属于文件夹镜像范围的在线文档不产生额外调用。 if got := len(caller.callsFor("list_files")); got != 2 { t.Errorf("expected 2 list_files calls (ROOT + SUB), got %d", got) } From 2778bef5bda10e13d9b7b9213874913f88872913 Mon Sep 17 00:00:00 2001 From: xiatian Date: Thu, 13 Aug 2026 11:46:58 +0800 Subject: [PATCH 045/250] feat(sheet): support source range dropdowns and read completion --- .changes/sheet-source-range-dropdowns.md | 6 + internal/helpers/sheet_batch.go | 42 +++- internal/helpers/sheet_batch_test.go | 10 +- internal/helpers/sheet_data.go | 12 +- internal/helpers/sheet_dimension.go | 112 ++++++++-- .../sheet_dropdown_source_range_test.go | 171 +++++++++++++++ internal/helpers/sheet_range_ops.go | 19 +- .../helpers/sheet_read_completion_test.go | 202 ++++++++++++++++++ internal/helpers/sheet_validate.go | 54 +++-- .../products/sheet/sheet-batch-operations.md | 4 +- .../products/sheet/sheet-dropdown.md | 37 ++-- .../products/sheet/sheet-read-data.md | 38 +++- .../products/sheet/sheet-write-data.md | 7 +- .../sheet/sheet-batch-operations.md | 4 +- .../references/sheet/sheet-dropdown.md | 37 ++-- .../references/sheet/sheet-read-data.md | 38 +++- .../references/sheet/sheet-write-data.md | 7 +- 17 files changed, 707 insertions(+), 93 deletions(-) create mode 100644 .changes/sheet-source-range-dropdowns.md create mode 100644 internal/helpers/sheet_dropdown_source_range_test.go create mode 100644 internal/helpers/sheet_read_completion_test.go diff --git a/.changes/sheet-source-range-dropdowns.md b/.changes/sheet-source-range-dropdowns.md new file mode 100644 index 00000000..55d58640 --- /dev/null +++ b/.changes/sheet-source-range-dropdowns.md @@ -0,0 +1,6 @@ +--- +category: Added +--- + +- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. +- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads. diff --git a/internal/helpers/sheet_batch.go b/internal/helpers/sheet_batch.go index 218a88fd..664bc4ae 100644 --- a/internal/helpers/sheet_batch.go +++ b/internal/helpers/sheet_batch.go @@ -60,6 +60,11 @@ func translateBatchOp(op map[string]any) (map[string]any, error) { if !ok { return nil, fmt.Errorf("unsupported toolName %q: must be a CLI command name (e.g. \"range clear\", \"range update\", \"merge-cells\"). Run 'dws sheet batch-update --help' for the full list", toolName) } + if toolName == "set-dropdown" { + if err := validateBatchSetDropdownInput(input); err != nil { + return nil, err + } + } return map[string]any{ "toolName": mapping.mcpTool, @@ -67,6 +72,33 @@ func translateBatchOp(op map[string]any) (map[string]any, error) { }, nil } +func validateBatchSetDropdownInput(input map[string]any) error { + if _, exists := input["source-colors"]; exists { + return fmt.Errorf("set-dropdown: SourceRange 颜色写入暂不支持") + } + if _, exists := input["colors"]; exists { + return fmt.Errorf("set-dropdown: SourceRange 颜色写入暂不支持") + } + + options, hasOptions := input["options"] + hasOptions = hasOptions && options != nil + sourceRange := batchStr(input, "source-range") + sourceSheetID := batchStr(input, "source-sheet-id") + hasSourceRange := sourceRange != "" + if hasOptions == hasSourceRange { + return fmt.Errorf("set-dropdown: options 与 source-range 必须且只能指定一个") + } + if hasSourceRange != (sourceSheetID != "") { + return fmt.Errorf("set-dropdown: source-range 与 source-sheet-id 必须同时指定") + } + if hasSourceRange { + if err := validateDropdownSourceRangeNotation(sourceRange); err != nil { + return fmt.Errorf("set-dropdown: %w", err) + } + } + return nil +} + // ── BuildXxxArgs: CLI flag → MCP param 转换函数 ────────────────────────────────── // 每个函数接收 CLI flag 名（kebab-case）的 map，输出 MCP 参数名（camelCase）的 map。 // 目前集中放在此文件；后续拆分命令文件时可移到各命令所在文件。 @@ -215,7 +247,15 @@ func BuildSetDropdownArgs(input map[string]any) map[string]any { args := map[string]any{ "sheetId": batchStr(input, "sheet-id"), "range": batchStr(input, "range"), - "options": input["options"], + } + if options, ok := input["options"]; ok && options != nil { + args["options"] = options + } + if sourceRange := batchStr(input, "source-range"); sourceRange != "" { + args["sourceRange"] = map[string]any{ + "sheetId": batchStr(input, "source-sheet-id"), + "a1Notation": sourceRange, + } } if v, ok := input["multi-select"]; ok { args["enableMultiSelect"] = v diff --git a/internal/helpers/sheet_batch_test.go b/internal/helpers/sheet_batch_test.go index f7038d08..edb85887 100644 --- a/internal/helpers/sheet_batch_test.go +++ b/internal/helpers/sheet_batch_test.go @@ -23,7 +23,15 @@ func TestCrossPlatformCoverageSheetBatchOperationTranslationCoversEveryMapping(t "group-state": "fold", } for name, mapping := range batchOpDispatch { - got, err := translateBatchOp(map[string]any{"toolName": name, "input": input}) + opInput := input + if name == "set-dropdown" { + opInput = make(map[string]any, len(input)) + for key, value := range input { + opInput[key] = value + } + delete(opInput, "source-range") + } + got, err := translateBatchOp(map[string]any{"toolName": name, "input": opInput}) if err != nil { t.Errorf("translateBatchOp(%q): %v", name, err) continue diff --git a/internal/helpers/sheet_data.go b/internal/helpers/sheet_data.go index 3cdb77b0..be6e9d2d 100644 --- a/internal/helpers/sheet_data.go +++ b/internal/helpers/sheet_data.go @@ -388,7 +388,10 @@ range update 与合并区域冲突时返回 MERGED_CELLS_CONFLICT 的行为。 csv 带 [row=N] 行号前缀的 CSV 文本 colIndices 列字母映射数组（定位列用 colIndices[j]，禁止手数逗号） rowIndices 行号映射数组 - hasMore 是否因 maxChars 截断 + hasMore 目标范围是否还有未返回数据 + truncationReasons 部分返回原因：max_cells / max_chars + resolvedRange 未传 --range 时底层解析出的完整目标范围 + returnedRange 本次实际完整返回的范围 取值模式（--value-render-option）： formatted_value 格式化后的展示值（默认），如 ¥1,000.00、2025-06-01 @@ -398,9 +401,14 @@ range update 与合并区域冲突时返回 MERGED_CELLS_CONFLICT 的行为。 与 range read 的区别： - CSV 格式 token 消耗约为 JSON 的 1/3 - 支持选择取值模式 - - 自动防爆（max-chars 截断 + has_more 标志） + - 自动防爆（30,000 单元格 / max-chars 上限 + hasMore 标志） - [row=N] 前缀防止行号计算错误 +当 hasMore=true 时本命令不会自动续读；请结合目标范围和 +returnedRange 从下一行显式传 --range。max_cells 不能通过增大 +--max-chars 解决。收到 forbidden.document.sizeOverLimit 表示工作簿整体 +无法装载，应创建更小副本或拆分工作簿，缩小 --range 不能解决。 + 注意：csv-get 不返回合并单元格结构。查看合并范围请使用 dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 mergedRanges。`, Example: ` dws sheet csv-get --node NODE_ID diff --git a/internal/helpers/sheet_dimension.go b/internal/helpers/sheet_dimension.go index 4ce8d7ba..2b442f02 100644 --- a/internal/helpers/sheet_dimension.go +++ b/internal/helpers/sheet_dimension.go @@ -6,6 +6,7 @@ import ( "strconv" "strings" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" "github.com/spf13/cobra" ) @@ -18,6 +19,16 @@ func sizeTypeEnumHint(dimension string) string { return "pixel / standard" } +func validateDropdownSourceRangeNotation(sourceRange string) error { + if strings.Contains(sourceRange, "!") { + return fmt.Errorf("--source-range 不能包含工作表前缀；请通过 --source-sheet-id 指定来源工作表") + } + if strings.HasPrefix(sourceRange, "=") || strings.Contains(sourceRange, ",") { + return fmt.Errorf("--source-range 必须是单一连续区域，不能是公式、表达式或多区域引用") + } + return nil +} + // newDimensionCmds creates dimension-related commands: insert/delete/update/move/add-dimension, // merge-cells, unmerge-cells, and dropdown commands (set/get/delete-dropdown). func newDimensionCmds() []*cobra.Command { @@ -775,15 +786,23 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 Short: "设置下拉列表", Long: `在钉钉表格的指定单元格范围内设置下拉列表。 -设置后，用户可以在这些单元格中从预定义的选项列表中选择值。 -支持自定义每个选项的颜色和是否允许多选。 +Inline 模式通过 --options 提供静态选项，支持选项颜色。 +SourceRange 模式通过 --source-sheet-id + --source-range 引用同一工作簿内的来源区域， +支持跨工作表、整行和整列引用；读取配置时不会展开来源区域的当前值或颜色。 +两种模式都支持 --multi-select，并且 --options 与 --source-range 必须且只能指定一个。 如果目标范围已存在下拉列表，会被新的配置覆盖。 nodeId 支持传入文档链接 URL 或文档 ID（dentryUuid），系统自动识别。 sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获取。 --options 为 JSON 数组，每个元素包含 value（必填）和 color（可选）。 -选项值不能包含英文逗号。`, +选项值不能包含英文逗号。 + +--source-range 只接受不含工作表前缀的 A1 区域，例如 T1:T3、T:T 或 1:3； +来源工作表由 --source-sheet-id 单独指定。SourceRange 颜色写入暂不支持。 + +已知限制：服务端写入的 SourceRange 不会在工作表重命名或行列插入、删除、移动后 +自动更新；执行这些结构操作后应重新写入下拉来源。`, Example: ` # 设置单选下拉列表 dws sheet set-dropdown --node NODE_ID --sheet-id SHEET_ID --range "A2:A100" \ --options '[{"value":"选项1"},{"value":"选项2"},{"value":"选项3"}]' @@ -793,32 +812,63 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 --options '[{"value":"高","color":"#ff0000"},{"value":"中","color":"#ffaa00"},{"value":"低","color":"#00ff00"}]' \ --multi-select + # 引用同一工作簿内另一工作表的区域作为候选项来源 + dws sheet set-dropdown --node NODE_ID --sheet-id TARGET_SHEET_ID --range "C2:C100" \ + --source-sheet-id SOURCE_SHEET_ID --source-range "T1:T3" + # 使用文档链接 URL dws sheet set-dropdown --node "https://alidocs.dingtalk.com/i/nodes/" \ --sheet-id SHEET_ID --range "C1:C10" --options '[{"value":"是"},{"value":"否"}]'`, RunE: func(cmd *cobra.Command, args []string) error { + if err := validateRequiredFlags(cmd, "node", "sheet-id", "range"); err != nil { + return err + } optionsStr := mustGetFlag(cmd, "options") - var options []map[string]any - if err := json.Unmarshal([]byte(optionsStr), &options); err != nil { - return fmt.Errorf("--options JSON 解析失败: %w", err) + sourceSheetID := mustGetFlag(cmd, "source-sheet-id") + sourceRange := mustGetFlag(cmd, "source-range") + hasOptions := optionsStr != "" + hasSourceRange := sourceRange != "" + if hasOptions == hasSourceRange { + return fmt.Errorf("--options 与 --source-range 必须且只能指定一个") } - if len(options) == 0 { - return fmt.Errorf("--options 至少包含 1 个选项") + if hasSourceRange && sourceSheetID == "" { + return fmt.Errorf("使用 --source-range 时必须同时指定 --source-sheet-id") } - for i, opt := range options { - val, ok := opt["value"].(string) - if !ok || val == "" { - return fmt.Errorf("--options[%d] 缺少必填的 value 字段或 value 为空", i) - } - if strings.Contains(val, ",") { - return fmt.Errorf("--options[%d].value 不能包含英文逗号: %q", i, val) - } + if !hasSourceRange && sourceSheetID != "" { + return fmt.Errorf("使用 --source-sheet-id 时必须同时指定 --source-range") } + toolArgs := map[string]any{ "nodeId": mustGetFlag(cmd, "node"), "sheetId": mustGetFlag(cmd, "sheet-id"), "range": mustGetFlag(cmd, "range"), - "options": options, + } + if hasOptions { + var options []map[string]any + if err := json.Unmarshal([]byte(optionsStr), &options); err != nil { + return fmt.Errorf("--options JSON 解析失败: %w", err) + } + if len(options) == 0 { + return fmt.Errorf("--options 至少包含 1 个选项") + } + for i, opt := range options { + val, ok := opt["value"].(string) + if !ok || val == "" { + return fmt.Errorf("--options[%d] 缺少必填的 value 字段或 value 为空", i) + } + if strings.Contains(val, ",") { + return fmt.Errorf("--options[%d].value 不能包含英文逗号: %q", i, val) + } + } + toolArgs["options"] = options + } else { + if err := validateDropdownSourceRangeNotation(sourceRange); err != nil { + return err + } + toolArgs["sourceRange"] = map[string]any{ + "sheetId": sourceSheetID, + "a1Notation": sourceRange, + } } if multiSelect, _ := cmd.Flags().GetBool("multi-select"); multiSelect { toolArgs["enableMultiSelect"] = true @@ -839,36 +889,54 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 CLIPath: "sheet set-dropdown", PrimaryCLIPath: "sheet set-dropdown", }, - Description: "为指定范围设置下拉列表（可多选、可带颜色）。", + Description: "为指定范围设置 Inline 或 SourceRange 下拉列表（可多选；颜色仅 Inline 支持）。", Interface: &contract.InterfaceSpec{ Mode: "mcp", Availability: "available", Ref: &contract.InterfaceRefSpec{ProductID: "sheet", RPCName: "set_dropdown_lists"}, }, Selection: contract.SelectionSpec{ - AgentSummary: "为指定范围设置下拉列表（可多选、可带颜色）。", + AgentSummary: "为指定范围设置 Inline 或 SourceRange 下拉列表；SourceRange 可跨同一工作簿内的工作表。", UseWhen: []string{"需要给单元格配置可选值下拉约束时"}, AvoidWhen: []string{"查看已有下拉用 get-dropdown；移除下拉用 delete-dropdown"}, - Examples: []string{"dws sheet set-dropdown --node --sheet-id --range \"A2:A100\" --options '[{\"value\":\"选项1\"},{\"value\":\"选项2\"}]'"}, + Examples: []string{ + "dws sheet set-dropdown --node --sheet-id --range \"A2:A100\" --options '[{\"value\":\"选项1\"},{\"value\":\"选项2\"}]'", + "dws sheet set-dropdown --node --sheet-id --range \"B2:B100\" --source-sheet-id --source-range \"T1:T3\"", + }, }, Parameters: []contract.ParamDecl{ {Name: "multi-select", Property: "enableMultiSelect"}, {Name: "node", Property: "nodeId"}, + {Name: "options", Property: "options", Required: boolPtr(false), RequiredWhen: "exactly one of --options or --source-range must be provided"}, + {Name: "source-sheet-id", Property: "sourceRange.sheetId", Required: boolPtr(false), RequiredWhen: "--source-range is provided"}, + {Name: "source-range", Property: "sourceRange.a1Notation", Required: boolPtr(false), RequiredWhen: "exactly one of --options or --source-range must be provided"}, }, }, }) setDropdownCmd.Flags().String("node", "", "表格文档 ID 或 URL (必填)") setDropdownCmd.Flags().String("sheet-id", "", "工作表 ID 或名称 (必填)") setDropdownCmd.Flags().String("range", "", "目标单元格范围，A1 表示法，如 A2:A100 (必填)") - setDropdownCmd.Flags().String("options", "", `下拉选项 JSON 数组 (必填)，如 '[{"value":"选项1","color":"#ff0000"}]'`) + setDropdownCmd.Flags().String("options", "", `Inline 下拉选项 JSON 数组，与 --source-range 二选一，如 '[{"value":"选项1","color":"#ff0000"}]'`) + setDropdownCmd.Flags().String("source-sheet-id", "", "SourceRange 来源工作表 ID；使用 --source-range 时必填") + setDropdownCmd.Flags().String("source-range", "", "SourceRange 来源区域，与 --options 二选一；不含工作表前缀，如 T1:T3、T:T 或 1:3") setDropdownCmd.Flags().Bool("multi-select", false, "是否允许多选（默认单选）") + cli.AnnotateRuntimeFlagFormat(setDropdownCmd, "source-range", "a1-range") + setDropdownCmd.MarkFlagsOneRequired("options", "source-range") + setDropdownCmd.MarkFlagsMutuallyExclusive("options", "source-range") + setDropdownCmd.MarkFlagsRequiredTogether("source-sheet-id", "source-range") + cli.AnnotateRuntimeConstraints(setDropdownCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"options", "source-range"}}, + RequireOneOf: [][]string{{"options", "source-range"}}, + RequireTogether: [][]string{{"source-sheet-id", "source-range"}}, + }) getDropdownCmd := &cobra.Command{ Use: "get-dropdown", Short: "获取下拉列表配置", Long: `查询钉钉表格指定范围内的下拉列表配置。 -返回范围内所有单元格的下拉列表配置信息，包括选项值和颜色。 +Inline 配置返回 conditionValues 和 options；SourceRange 配置返回 +sourceType/sourceRange/sourceRangeStatus/enableMultiSelect，不展开来源区域的候选值或颜色。 如果范围内存在多个不同的下拉列表配置，会分别返回每组配置及其覆盖的单元格列表。 如果范围内没有设置下拉列表，返回空。 diff --git a/internal/helpers/sheet_dropdown_source_range_test.go b/internal/helpers/sheet_dropdown_source_range_test.go new file mode 100644 index 00000000..af7c1eeb --- /dev/null +++ b/internal/helpers/sheet_dropdown_source_range_test.go @@ -0,0 +1,171 @@ +package helpers + +import ( + "encoding/json" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" +) + +func TestCrossPlatformCoverageSetDropdownSourceRangeCommand(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"success":true}`}}} + installScriptedCaller(t, caller) + err := executeDimensionCoverage(t, "set-dropdown", + "--node", "node-1", + "--sheet-id", "target-sheet", + "--range", "B2:B100", + "--source-sheet-id", "source-sheet", + "--source-range", "$t$1:$t$3", + "--multi-select", + ) + if err != nil { + t.Fatalf("set SourceRange dropdown: %v", err) + } + if caller.tool != "set_dropdown_lists" { + t.Fatalf("tool = %q, want set_dropdown_lists", caller.tool) + } + if _, exists := caller.args["options"]; exists { + t.Fatalf("SourceRange request must omit options: %#v", caller.args) + } + source, ok := caller.args["sourceRange"].(map[string]any) + if !ok { + t.Fatalf("sourceRange = %#v", caller.args["sourceRange"]) + } + if source["sheetId"] != "source-sheet" || source["a1Notation"] != "$t$1:$t$3" { + t.Fatalf("sourceRange = %#v", source) + } + if caller.args["enableMultiSelect"] != true { + t.Fatalf("enableMultiSelect = %#v", caller.args["enableMultiSelect"]) + } +} + +func TestCrossPlatformCoverageSetDropdownInlineCommandStillOmitsSourceRange(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"success":true}`}}} + installScriptedCaller(t, caller) + err := executeDimensionCoverage(t, "set-dropdown", + "--node", "node-1", + "--sheet-id", "sheet-1", + "--range", "A1:A3", + "--options", `[{"value":"one","color":"#ff0000"}]`, + ) + if err != nil { + t.Fatalf("set inline dropdown: %v", err) + } + if _, exists := caller.args["sourceRange"]; exists { + t.Fatalf("inline request must omit sourceRange: %#v", caller.args) + } + options, ok := caller.args["options"].([]map[string]any) + if !ok || len(options) != 1 || options[0]["value"] != "one" { + t.Fatalf("options = %#v", caller.args["options"]) + } +} + +func TestCrossPlatformCoverageSetDropdownModeConstraints(t *testing.T) { + base := []string{"--node", "node", "--sheet-id", "sheet", "--range", "A1"} + tests := []struct { + name string + args []string + want string + }{ + {name: "neither", want: "one of the flags"}, + {name: "both", args: []string{"--options", `[{"value":"one"}]`, "--source-sheet-id", "source", "--source-range", "A1:A3"}, want: "none of the others"}, + {name: "source sheet without range", args: []string{"--options", `[{"value":"one"}]`, "--source-sheet-id", "source"}, want: "must all be set"}, + {name: "range without source sheet", args: []string{"--source-range", "A1:A3"}, want: "must all be set"}, + {name: "sheet prefix", args: []string{"--source-sheet-id", "source", "--source-range", "Sheet2!A1:A3"}, want: "不能包含工作表前缀"}, + {name: "formula", args: []string{"--source-sheet-id", "source", "--source-range", "=A1:A3"}, want: "必须是单一连续区域"}, + {name: "multi region", args: []string{"--source-sheet-id", "source", "--source-range", "A1:A3,C1:C3"}, want: "必须是单一连续区域"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + installScriptedCaller(t, caller) + args := append(append([]string{}, base...), tc.args...) + err := executeDimensionCoverage(t, "set-dropdown", args...) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want contains %q", err, tc.want) + } + if caller.calls != 0 { + t.Fatalf("calls = %d, validation must fail before request", caller.calls) + } + }) + } +} + +func TestCrossPlatformCoverageSetDropdownSchemaConstraints(t *testing.T) { + cmd := dimensionCoverageCommand(t, "set-dropdown") + constraints := runtimeannotate.CommandConstraints(cmd) + want := runtimeannotate.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"options", "source-range"}}, + RequireOneOf: [][]string{{"options", "source-range"}}, + RequireTogether: [][]string{{"source-sheet-id", "source-range"}}, + } + gotJSON, _ := json.Marshal(constraints) + wantJSON, _ := json.Marshal(runtimeannotate.NormalizeConstraints(want)) + if string(gotJSON) != string(wantJSON) { + t.Fatalf("constraints = %s, want %s", gotJSON, wantJSON) + } +} + +func TestCrossPlatformCoverageBatchSetDropdownSourceRange(t *testing.T) { + got, err := translateBatchOp(map[string]any{ + "toolName": "set-dropdown", + "input": map[string]any{ + "sheet-id": "target-sheet", + "range": "B2:B100", + "source-sheet-id": "source-sheet", + "source-range": "T:T", + "multi-select": true, + }, + }) + if err != nil { + t.Fatalf("translate SourceRange batch op: %v", err) + } + input := got["input"].(map[string]any) + if _, exists := input["options"]; exists { + t.Fatalf("SourceRange batch input must omit options: %#v", input) + } + source := input["sourceRange"].(map[string]any) + if source["sheetId"] != "source-sheet" || source["a1Notation"] != "T:T" { + t.Fatalf("sourceRange = %#v", source) + } + + invalid := []map[string]any{ + {}, + {"options": []any{map[string]any{"value": "one"}}, "source-sheet-id": "source", "source-range": "A1:A3"}, + {"source-range": "A1:A3"}, + {"source-sheet-id": "source", "source-range": "A1:A3", "colors": []any{"#fff"}}, + {"source-sheet-id": "source", "source-range": "Sheet2!A1:A3"}, + } + for _, value := range invalid { + if _, err := translateBatchOp(map[string]any{"toolName": "set-dropdown", "input": value}); err == nil { + t.Errorf("invalid batch SourceRange input %#v returned nil", value) + } + } +} + +func TestCrossPlatformCoverageValidateSourceRangeDataValidation(t *testing.T) { + valid := []any{ + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}}, + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "missing-sheet", "a1Notation": "not-validated-locally"}, "enableMultiSelect": true}, + } + for _, value := range valid { + if err := validateDataValidation(value, "dv"); err != nil { + t.Errorf("valid SourceRange data validation %#v: %v", value, err) + } + } + + invalid := []any{ + map[string]any{"type": "dropdown", "options": []any{map[string]any{"value": "one"}}, "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}}, + map[string]any{"type": "dropdown", "sourceRange": "T1:T3"}, + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"a1Notation": "T1:T3"}}, + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source"}}, + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3", "colors": []any{"#fff"}}}, + map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}, "enableMultiSelect": "yes"}, + } + for _, value := range invalid { + if err := validateDataValidation(value, "dv"); err == nil { + t.Errorf("invalid SourceRange data validation %#v returned nil", value) + } + } +} diff --git a/internal/helpers/sheet_range_ops.go b/internal/helpers/sheet_range_ops.go index 5d6c8217..8bd07dc9 100644 --- a/internal/helpers/sheet_range_ops.go +++ b/internal/helpers/sheet_range_ops.go @@ -26,6 +26,16 @@ func newRangeCmd() *cobra.Command { value 单元格值（内容由 --value-render-option 决定） dataValidation 数据验证配置（下拉列表/复选框），无则为 null hyperlink 单元格级超链接（path/sheet/range），无则省略 +顶层还会返回 rowIndices / colIndices 与完成度字段： + hasMore 目标范围是否还有未返回数据 + truncationReasons 部分返回原因（max_cells） + resolvedRange 未传 --range 时底层解析出的完整目标范围 + returnedRange 本次实际完整返回的范围 + +单次最多返回 30,000 个单元格。hasMore=true 是部分成功，本命令 +不会自动续读；请结合目标范围和 returnedRange 从下一行显式传 +--range。收到 forbidden.document.sizeOverLimit 则表示工作簿整体无法装载， +应创建更小副本或拆分工作簿，缩小 --range 不能解决。 注意：range read/get 不返回合并单元格结构。查看合并范围请使用 dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 mergedRanges。 @@ -157,7 +167,12 @@ dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 merg 2) {"dataValidation":{"type":"none"}} → 显式清除该单元格 DV 3) {"dataValidation":{"type":"dropdown",...}} → 写新 dropdown（覆盖） {"dataValidation":{"type":"checkbox",...}} → 写新 checkbox（覆盖） - dropdown: {"dataValidation":{"type":"dropdown","options":[{"value":"选项1"}],"enableMultiSelect":false}} + Inline dropdown: + {"dataValidation":{"type":"dropdown","options":[{"value":"选项1"}],"enableMultiSelect":false}} + SourceRange dropdown（同一工作簿内可跨工作表；不展开来源 values，不支持 colors）： + {"dataValidation":{"type":"dropdown","sourceRange":{"sheetId":"SOURCE_SHEET_ID","a1Notation":"T1:T3"},"enableMultiSelect":false}} + dropdown 的 options 与 sourceRange 必须且只能传一个。SourceRange 支持普通区域、整行和整列； + a1Notation 不带工作表前缀，来源工作表单独写在 sheetId。 checkbox: {"dataValidation":{"type":"checkbox","checked":true}} 可与 text/richText 共存，也可单独使用（如 {dataValidation:{type:"none"}} 仅清除 DV 不写值） @@ -169,6 +184,8 @@ dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 merg - 只设样式或批量刷整片区域样式请用 dws sheet range set-style；写值同时设置少量 cell 样式可用 cellStyles - 目标范围与已有合并区域冲突时，range update 会返回 MERGED_CELLS_CONFLICT；先用 sheet info 查看 mergedRanges，取消合并后写入，必要时再重新合并 - csv-put 的合并处理不同：目标区域含合并单元格时会打散合并并写入 CSV 值或公式 + - SourceRange 当前不会随工作表重命名或行列结构调整自动更新；执行结构操作后应重新写入 + - 同一 cell 的 value/style 已写入但 SourceRange 校验失败时，服务端可返回 success=true，并通过 message 明确下拉未创建；必须检查 message，必要时重新读取确认 - 清空整片区域请用 dws sheet range clear`, Example: ` # 写入文本 dws sheet range update --node NODE_ID --sheet-id SHEET_ID --range "A1:B2" \ diff --git a/internal/helpers/sheet_read_completion_test.go b/internal/helpers/sheet_read_completion_test.go new file mode 100644 index 00000000..dca4bfdc --- /dev/null +++ b/internal/helpers/sheet_read_completion_test.go @@ -0,0 +1,202 @@ +package helpers + +import ( + "bytes" + "encoding/json" + "errors" + "strings" + "testing" +) + +func executeSheetReadCompletionCommand(t *testing.T, caller *scriptedToolCaller, args ...string) (*bytes.Buffer, error) { + t.Helper() + installScriptedCaller(t, caller) + installSheetProductArgs(t) + + stdout := &bytes.Buffer{} + deps.Out.w = stdout + + cmd := newSheetCommand() + cmd.SilenceErrors = true + cmd.SilenceUsage = true + cmd.SetArgs(args) + return stdout, cmd.Execute() +} + +func decodeSheetReadOutput(t *testing.T, stdout *bytes.Buffer) map[string]any { + t.Helper() + var got map[string]any + if err := json.Unmarshal(stdout.Bytes(), &got); err != nil { + t.Fatalf("decode sheet read output %q: %v", stdout.String(), err) + } + return got +} + +func assertSheetReadCompletionMetadata(t *testing.T, got map[string]any) { + t.Helper() + if hasMore, ok := got["hasMore"].(bool); !ok || !hasMore { + t.Fatalf("hasMore = %#v, want true", got["hasMore"]) + } + if got["resolvedRange"] != "A1:A30001" { + t.Fatalf("resolvedRange = %#v", got["resolvedRange"]) + } + if got["returnedRange"] != "A1:A30000" { + t.Fatalf("returnedRange = %#v", got["returnedRange"]) + } + reasons, ok := got["truncationReasons"].([]any) + if !ok || len(reasons) == 0 || reasons[0] != "max_cells" { + t.Fatalf("truncationReasons = %#v", got["truncationReasons"]) + } +} + +// csv-get intentionally projects the MCP response rather than inventing a +// client-side page model. Keep all completion metadata visible and make one +// request only, even when the server reports a partial success. +func TestSheetCSVGetPreservesCompletionMetadataWithoutAutoPagination(t *testing.T) { + const response = `{"csv":"[row=1]1\n","colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells","max_chars"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}` + caller := &scriptedToolCaller{ + format: "raw", + steps: []scriptedToolStep{{text: response}}, + } + + stdout, err := executeSheetReadCompletionCommand(t, caller, + "csv-get", "--node", "NODE") + if err != nil { + t.Fatalf("csv-get: %v", err) + } + if caller.calls != 1 || caller.tool != "get_range_as_csv" { + t.Fatalf("calls/tool = %d/%q, want one get_range_as_csv call", caller.calls, caller.tool) + } + if _, exists := caller.args["range"]; exists { + t.Fatalf("omitted range was unexpectedly synthesized by the CLI: %#v", caller.args["range"]) + } + if got := strings.TrimSpace(stdout.String()); got != response { + t.Fatalf("raw csv-get response changed:\n got: %s\nwant: %s", got, response) + } + + got := decodeSheetReadOutput(t, stdout) + assertSheetReadCompletionMetadata(t, got) + reasons := got["truncationReasons"].([]any) + if len(reasons) != 2 || reasons[1] != "max_chars" { + t.Fatalf("truncationReasons = %#v, want max_cells and max_chars", reasons) + } +} + +// range read parses the get_cell_infos envelope to remove empty per-cell +// schema shells. That cleanup must not discard new top-level completion fields. +func TestSheetRangeReadPreservesCompletionMetadataWithoutAutoPagination(t *testing.T) { + const response = `{"cells":[[{"value":"1","dataValidation":{"type":null},"hyperlink":{"url":null}}]],"colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}` + caller := &scriptedToolCaller{ + format: "json", + steps: []scriptedToolStep{{text: response}}, + } + + stdout, err := executeSheetReadCompletionCommand(t, caller, + "range", "read", "--node", "NODE") + if err != nil { + t.Fatalf("range read: %v", err) + } + if caller.calls != 1 || caller.tool != "get_cell_infos" { + t.Fatalf("calls/tool = %d/%q, want one get_cell_infos call", caller.calls, caller.tool) + } + if _, exists := caller.args["range"]; exists { + t.Fatalf("omitted range was unexpectedly synthesized by the CLI: %#v", caller.args["range"]) + } + + got := decodeSheetReadOutput(t, stdout) + assertSheetReadCompletionMetadata(t, got) + cells := got["cells"].([]any) + row := cells[0].([]any) + cell := row[0].(map[string]any) + if _, exists := cell["dataValidation"]; exists { + t.Fatalf("empty dataValidation shell was not removed: %#v", cell) + } + if _, exists := cell["hyperlink"]; exists { + t.Fatalf("empty hyperlink shell was not removed: %#v", cell) + } +} + +// sheet +read calls get_cell_infos through this direct passthrough instead of +// callMCPToolCellInfos. Lock that third read surface to the same raw envelope +// contract and to one request only. +func TestSheetCellInfosDirectPassthroughPreservesCompletionMetadata(t *testing.T) { + const response = `{"cells":[[{"value":"1"}]],"colIndices":["A"],"rowIndices":[1],"hasMore":true,"truncationReasons":["max_cells"],"resolvedRange":"A1:A30001","returnedRange":"A1:A30000","message":"partial"}` + caller := &scriptedToolCaller{ + format: "raw", + steps: []scriptedToolStep{{text: response}}, + } + installScriptedCaller(t, caller) + stdout := &bytes.Buffer{} + deps.Out.w = stdout + + if err := CallMCPToolOnServer("sheet", "get_cell_infos", map[string]any{"nodeId": "NODE"}); err != nil { + t.Fatalf("direct get_cell_infos: %v", err) + } + if caller.calls != 1 || caller.server != "sheet" || caller.tool != "get_cell_infos" { + t.Fatalf("calls/server/tool = %d/%q/%q", caller.calls, caller.server, caller.tool) + } + if got := strings.TrimSpace(stdout.String()); got != response { + t.Fatalf("raw get_cell_infos response changed:\n got: %s\nwant: %s", got, response) + } + assertSheetReadCompletionMetadata(t, decodeSheetReadOutput(t, stdout)) +} + +// Large-CP failure is not a pageable success. Both the raw csv-get path and +// both get_cell_infos paths must retain the backend code and safe user message +// exactly, matching the generic get_all_sheets error-classification path. +func TestSheetReadPreservesWorkbookSizeOverLimitError(t *testing.T) { + const response = `{"success":false,"errorCode":"forbidden.document.sizeOverLimit","errorMessage":"The workbook data is too large to process. Use a smaller copy or split the workbook, then try again."}` + tests := []struct { + name string + args []string + tool string + direct bool + }{ + {name: "csv-get", args: []string{"csv-get", "--node", "NODE"}, tool: "get_range_as_csv"}, + {name: "range-read", args: []string{"range", "read", "--node", "NODE"}, tool: "get_cell_infos"}, + {name: "cell-infos-direct", tool: "get_cell_infos", direct: true}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{ + format: "json", + steps: []scriptedToolStep{{text: response}}, + } + var stdout *bytes.Buffer + var err error + if test.direct { + installScriptedCaller(t, caller) + stdout = &bytes.Buffer{} + deps.Out.w = stdout + err = CallMCPToolOnServer("sheet", test.tool, map[string]any{"nodeId": "NODE"}) + } else { + stdout, err = executeSheetReadCompletionCommand(t, caller, test.args...) + } + if err == nil { + t.Fatal("large-CP response was accepted as success") + } + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeMCPToolError { + t.Fatalf("error = %T %v, want MCP tool error", err, err) + } + if cliErr.Message != response { + t.Fatalf("backend error payload changed:\n got: %s\nwant: %s", cliErr.Message, response) + } + for _, want := range []string{ + "forbidden.document.sizeOverLimit", + "The workbook data is too large to process.", + } { + if !strings.Contains(err.Error(), want) { + t.Errorf("error %q does not preserve %q", err, want) + } + } + if stdout.Len() != 0 { + t.Fatalf("failure wrote a success body: %q", stdout.String()) + } + if caller.calls != 1 || caller.tool != test.tool { + t.Fatalf("calls/tool = %d/%q, want one %s call", caller.calls, caller.tool, test.tool) + } + }) + } +} diff --git a/internal/helpers/sheet_validate.go b/internal/helpers/sheet_validate.go index e40a7cb3..f32e6836 100644 --- a/internal/helpers/sheet_validate.go +++ b/internal/helpers/sheet_validate.go @@ -239,22 +239,48 @@ func validateDataValidation(dvRaw any, path string) error { } switch dvType { case "dropdown": - optionsRaw, ok := dv["options"] - if !ok { - return fmt.Errorf("%s: type=dropdown 必须包含 options 数组", path) + optionsRaw, hasOptions := dv["options"] + sourceRangeRaw, hasSourceRange := dv["sourceRange"] + hasOptions = hasOptions && optionsRaw != nil + hasSourceRange = hasSourceRange && sourceRangeRaw != nil + if hasOptions == hasSourceRange { + return fmt.Errorf("%s: type=dropdown 的 options 与 sourceRange 必须且只能包含一个", path) } - options, ok := optionsRaw.([]any) - if !ok || len(options) == 0 { - return fmt.Errorf("%s.options 必须为非空数组", path) - } - for i, opt := range options { - optMap, ok := opt.(map[string]any) - if !ok { - return fmt.Errorf("%s.options[%d] 必须为 object（如 {\"value\":\"选项\"}）", path, i) + if hasOptions { + options, ok := optionsRaw.([]any) + if !ok || len(options) == 0 { + return fmt.Errorf("%s.options 必须为非空数组", path) } - val, ok := optMap["value"].(string) - if !ok || val == "" { - return fmt.Errorf("%s.options[%d].value 必须为非空字符串", path, i) + for i, opt := range options { + optMap, ok := opt.(map[string]any) + if !ok { + return fmt.Errorf("%s.options[%d] 必须为 object（如 {\"value\":\"选项\"}）", path, i) + } + val, ok := optMap["value"].(string) + if !ok || val == "" { + return fmt.Errorf("%s.options[%d].value 必须为非空字符串", path, i) + } + } + } else { + sourceRange, ok := sourceRangeRaw.(map[string]any) + if !ok { + return fmt.Errorf("%s.sourceRange 必须为 object", path) + } + if _, exists := sourceRange["colors"]; exists { + return fmt.Errorf("%s.sourceRange.colors 暂不支持", path) + } + sheetID, ok := sourceRange["sheetId"].(string) + if !ok || strings.TrimSpace(sheetID) == "" { + return fmt.Errorf("%s.sourceRange.sheetId 必须为非空字符串", path) + } + a1Notation, ok := sourceRange["a1Notation"].(string) + if !ok || strings.TrimSpace(a1Notation) == "" { + return fmt.Errorf("%s.sourceRange.a1Notation 必须为非空字符串", path) + } + } + if multi, exists := dv["enableMultiSelect"]; exists { + if _, ok := multi.(bool); !ok { + return fmt.Errorf("%s.enableMultiSelect 必须为 boolean", path) } } case "checkbox": diff --git a/skills/mono/references/products/sheet/sheet-batch-operations.md b/skills/mono/references/products/sheet/sheet-batch-operations.md index 8d922bec..4654840f 100644 --- a/skills/mono/references/products/sheet/sheet-batch-operations.md +++ b/skills/mono/references/products/sheet/sheet-batch-operations.md @@ -83,7 +83,8 @@ Example: {"toolName":"range update","input":{"sheet-id":"Sheet1","range":"A1","values":[[{"type":"text","text":"hello"}]]}}, {"toolName":"merge-cells","input":{"sheet-id":"Sheet1","range":"A1:B1","merge-type":"mergeAll"}}, {"toolName":"update-dimension","input":{"sheet-id":"Sheet1","dimension":"ROWS","start-index":"1","length":1,"pixel-size":40}}, - {"toolName":"group-dimension","input":{"sheet-id":"Sheet1","range":"3:7","group-state":"expand"}} + {"toolName":"group-dimension","input":{"sheet-id":"Sheet1","range":"3:7","group-state":"expand"}}, + {"toolName":"set-dropdown","input":{"sheet-id":"Sheet1","range":"C2:C100","source-sheet-id":"SourceSheet","source-range":"T1:T3"}} ]' dws sheet batch-update --node --continue-on-error --operations '[...]' Flags: @@ -101,6 +102,7 @@ Notes: - operations 最多 20 条 - 当需要对多个区域执行相同清除时，优先使用 `range batch-clear`（更简洁） - `csv-put` 子操作与独立命令语义一致：CSV 字段值以 `=` 开头时按公式解析；前加单引号时写入以 `=` 开头的字面文本 + - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。SourceRange 颜色写入暂不支持，且不会随 sheet 重命名或行列结构操作自动更新 - 典型场景：先插入行列再写入数据、先清除再写入、批量合并+调整行高列宽 - `group-dimension` 在 batch 中只适合默认展开分组；需要 `--group-state fold` 时请使用独立 `dws sheet group-dimension` - `table-put` 不支持放进 batch-update；结构化 table 请用独立 `dws sheet table-put` diff --git a/skills/mono/references/products/sheet/sheet-dropdown.md b/skills/mono/references/products/sheet/sheet-dropdown.md index 0b135aa4..b6e2e658 100644 --- a/skills/mono/references/products/sheet/sheet-dropdown.md +++ b/skills/mono/references/products/sheet/sheet-dropdown.md @@ -7,6 +7,7 @@ 用户说"设置下拉列表/下拉选项/下拉菜单/添加下拉/配置下拉": - 设置下拉列表 → `set-dropdown` - 设置多选下拉 → `set-dropdown --multi-select` +- 引用单元格区域作为候选项 → `set-dropdown --source-sheet-id ... --source-range ...` 用户说"查看下拉列表/获取下拉配置/下拉列表有哪些选项": - 获取下拉列表配置 → `get-dropdown` @@ -29,18 +30,25 @@ Example: dws sheet set-dropdown --node --sheet-id --range "B2:B50" \ --options '[{"value":"高","color":"#ff0000"},{"value":"中","color":"#ffaa00"},{"value":"低","color":"#00ff00"}]' \ --multi-select + + # 引用同一工作簿内另一工作表的区域作为候选项来源 + dws sheet set-dropdown --node --sheet-id --range "C2:C100" \ + --source-sheet-id --source-range "T1:T3" Flags: - --node string 表格文档 ID 或 URL (必填) - --sheet-id string 工作表 ID 或名称 (必填) - --range string 目标单元格范围，A1 表示法，如 A2:A100 (必填) - --options string 下拉选项 JSON 数组 (必填)，如 '[{"value":"选项1","color":"#ff0000"}]' - --multi-select 是否允许多选（默认单选） + --node string 表格文档 ID 或 URL (必填) + --sheet-id string 工作表 ID 或名称 (必填) + --range string 目标单元格范围，A1 表示法，如 A2:A100 (必填) + --options string Inline 下拉选项 JSON 数组，与 --source-range 二选一 + --source-sheet-id string SourceRange 来源工作表 ID，与 --source-range 同时指定 + --source-range string SourceRange 来源区域，与 --options 二选一；不带工作表前缀 + --multi-select 是否允许多选（默认单选） ``` -在指定单元格范围内设置下拉列表。设置后用户可从预定义选项中选择值。 -- **用途**：为单元格配置下拉列表，支持自定义选项颜色和多选。 +在指定单元格范围内设置下拉列表。Inline 模式直接存储选项；SourceRange 模式引用同一工作簿内的来源区域，可跨工作表，并支持普通区域、整行和整列。 +- **用途**：为单元格配置静态选项或区域来源下拉，两种模式都支持多选；颜色仅 Inline 支持。 - **场景**：规范数据输入，如状态选择（完成/进行中/待处理）、优先级（高/中/低）等。 -- **注意**：选项值不能包含英文逗号；如果目标范围已存在下拉列表，会被新配置覆盖。 +- **注意**：`--options` 与 `--source-range` 必须且只能指定一个。`--source-range` 只写 `T1:T3`、`T:T`、`1:3` 这类 A1 区域，来源工作表通过 `--source-sheet-id` 单独指定；不接受工作表前缀、公式或多区域。SourceRange 颜色写入暂不支持。 +- **静态引用限制**：服务端写入的 SourceRange 不会随工作表重命名或行列插入、删除、移动自动更新；结构操作后应重新写入该下拉来源。 ### 获取下拉列表配置 ``` @@ -55,10 +63,10 @@ Flags: --range string 查询范围，A1 表示法，如 A1:A100 (必填) ``` -查询指定范围内的下拉列表配置信息，包括选项值、颜色和是否多选。 +查询指定范围内的下拉列表配置信息。 - **用途**：查看单元格已设置的下拉列表选项和配置。 - **场景**：在修改下拉列表前先查询现有配置；确认下拉列表是否设置成功。 -- **返回**：`dataValidations` 数组，相同选项的单元格聚合为一组，每组包含 `conditionValues`（选项值）、`ranges`（覆盖范围）、`options`（含 `enableMultiSelect` 和 `colorValueMap`）。范围内无下拉列表时 `hasDropdown` 为 false。 +- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`sourceRange:{sheetId,a1Notation}`、`enableMultiSelect` 和 `ranges`，不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 ### 删除下拉列表 ``` @@ -81,14 +89,15 @@ Flags: | 操作 | 从返回中提取 | 用于 | |------|-------------|------| -| `set-dropdown` | `range` 实际设置范围、`optionCount` 选项数量、`enableMultiSelect` 是否多选 | 确认下拉列表设置成功 | -| `get-dropdown` | `hasDropdown` 是否存在下拉、`dataValidations` 下拉配置列表（含 `conditionValues`、`ranges`、`options`） | 查看已有下拉配置 | +| `set-dropdown` | `range` 实际设置范围、`enableMultiSelect` 是否多选；仅 Inline 模式返回 `optionCount` | 确认下拉列表设置成功 | +| `get-dropdown` | `hasDropdown`、`dataValidations`；按 `sourceType` 区分 Inline 与 SourceRange | 查看已有下拉配置 | | `delete-dropdown` | `range` 实际删除范围 | 确认下拉列表删除完成 | | `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id | ## 注意事项 - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等） -- `set-dropdown` 在指定范围内设置下拉列表，`--options` 为 JSON 数组，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB` 格式）。选项值不能包含英文逗号。`--multi-select` 启用多选模式。如果目标范围已存在下拉列表，会被新配置覆盖 -- `get-dropdown` 查询指定范围内的下拉列表配置，返回 `dataValidations` 数组，相同选项的单元格聚合为一组。无下拉列表时 `hasDropdown` 为 false +- `set-dropdown` 的 Inline 模式使用 `--options`，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB`）；SourceRange 模式使用 `--source-sheet-id` + `--source-range`。两种模式均可用 `--multi-select`，并会覆盖目标范围已有下拉 +- SourceRange 当前是静态引用，不会随 sheet 重命名或行列结构操作自动调整；颜色写入暂不支持 +- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，不回退展开候选值 - `delete-dropdown` 删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。已填写的值不会被清除。目标范围不存在下拉列表时操作仍返回成功 diff --git a/skills/mono/references/products/sheet/sheet-read-data.md b/skills/mono/references/products/sheet/sheet-read-data.md index 0e2ae054..4963fc2a 100644 --- a/skills/mono/references/products/sheet/sheet-read-data.md +++ b/skills/mono/references/products/sheet/sheet-read-data.md @@ -13,7 +13,7 @@ | 读取目的 | 推荐命令 | 说明 | |---------|---------|------| -| 快速查看纯值、数据分析、大表分批读取 | `csv-get` | CSV 格式，token 消耗约为 JSON 的 1/3，内置 maxChars 防爆 | +| 快速查看纯值、数据分析、大表分批读取 | `csv-get` | CSV 格式，token 消耗约为 JSON 的 1/3，内置 30,000 单元格和 maxChars 防爆 | | 按 table/dataframe 协议读取 | `table-get` | 返回 `columns` / `data` / `dtypes` / `formats`；默认首行为表头 | | 查看数据验证配置（下拉/复选框） | `range read` | 返回 per-cell 结构，含 dataValidation | | 查看单元格样式（背景色/字体/对齐等） | `range read` | 返回 per-cell 结构，含 cellStyles（仅显式设置的样式） | @@ -52,7 +52,10 @@ Flags: - `csv` — CSV 文本，每逻辑行前加 `[row=N]` 前缀标注真实表格行号。行号一律从此前缀读取，禁止手算 - `colIndices` — 列字母映射数组（如 `["A","B","C"]`）。定位列字母用 `colIndices[j]`，禁止手数逗号 - `rowIndices` — 行号映射数组（如 `[1,2,3]`） -- `hasMore` — 是否因 maxChars 截断。为 true 时需要调整 `--range` 继续分页读取 +- `hasMore` — 完整目标范围是否还有未返回数据。`true` 是部分成功，不能宣称已读完 +- `truncationReasons` — 部分返回原因。`max_cells` 表示命中单次 30,000 单元格上限；`max_chars` 表示命中 CSV 字符上限，两者可同时出现 +- `resolvedRange` — 仅在未传 `--range` 时返回，表示底层解析出的完整目标范围 +- `returnedRange` — 本次实际完整返回的精确范围；它不是服务端续读游标 `csv-get` 不返回合并单元格结构。若 CSV 中出现合并区域的非左上角单元格为空，不能据此判断该区域"无内容"；需要先用 `dws sheet info --node --sheet-id --format json` 读取 `mergedRanges`，再结合左上角单元格理解合并区域语义。 @@ -63,10 +66,15 @@ Flags: | `raw_value` | 原始值（如 1000、45808） | 数据处理、计算 | | `formula` | 公式文本（如 =SUM(A1:A10)），无公式时回退原始值 | 查看/复制公式 | -**大表分批读取**：当 `hasMore=true` 或数据量很大时，按行窗口分批： -- 先通过 `info` 获取 `nonEmptyRange.range`，或用 `nonEmptyRange.lastRow` / `nonEmptyRange.lastColumn` 确定 A1 边界 -- 分批读取：`--range "A1:J500"`、`--range "A501:J1000"` …… -- 单次建议 ≤5000 单元格 +**大表分批读取**：`csv-get` 不会自动发起后续请求。当 `hasMore=true` 时： +- 显式传了 `--range` 时，该范围是完整目标；未传时，以 `resolvedRange` 为完整目标 +- 根据 `returnedRange` 的结束行，从下一行开始显式构造新的 `--range`；例如目标是 `A1:A30001`、本次返回 `A1:A30000`，则继续读 `A30001:A30001` +- `max_cells` 不能通过增大 `--max-chars` 解决；`max_chars` 且没有 `returnedRange` 时，增大 `--max-chars` 或缩小列范围 +- 上述完成度协议覆盖未传 `--range` 和显式有限矩形范围；`A:A`、`1:1` 等非有限范围可能不返回完成度字段，建议先用 `sheet info` 的 `nonEmptyRange` 换算成有限范围再读 +- 即使未命中硬上限，单次仍建议控制在 5000 单元格以内，减少超时和 token 消耗 + +**工作簿过大失败与部分成功不同**：收到顶层 +`errorCode=forbidden.document.sizeOverLimit` 和对应 `errorMessage` 时，表示工作簿整体无法装载。应停止读取并提示创建更小副本或拆分工作簿；缩小 `--range` 不能解决这类错误。不要把它当成 `hasMore=true` 的可续读结果。 ### 以 table/dataframe 协议读取结构化数据 ``` @@ -130,6 +138,8 @@ Flags: ``` **返回字段说明**： +- `rowIndices` / `colIndices` — 本次返回的真实行号与列字母映射 +- `hasMore` / `truncationReasons` / `resolvedRange` / `returnedRange` — 语义与 `csv-get` 相同；`range read` 的 `truncationReasons` 主要为 `max_cells` - `cells` — 二维数组，第一维为行，第二维为列。每个元素为 per-cell 对象，字段如下： | 字段 | 类型 | 是否必有 | 说明 | @@ -146,10 +156,16 @@ Flags: | type | 字段 | 说明 | |------|------|------| -| `dropdown` | `options: [{value: string, color?: string}]` | 下拉选项列表 | -| `dropdown` | `enableMultiSelect: boolean` | 是否允许多选 | +| `dropdown` Inline | `sourceType: "inline"` | 静态选项模式 | +| `dropdown` Inline | `options: [{value: string, color?: string}]` | 下拉选项列表 | +| `dropdown` Inline | `enableMultiSelect: boolean` | 是否允许多选 | +| `dropdown` SourceRange | `sourceType: "sourceRange"` | 区域来源模式 | +| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 同一工作簿内的来源工作表和规范化 A1 区域 | +| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置 | | `checkbox` | `checked: boolean` | 当前勾选状态 | +SourceRange 模式只返回引用元数据，不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。 + **hyperlink 结构**： | type | 字段 | 说明 | @@ -216,7 +232,7 @@ Flags: **公式校验建议**：写公式后不要只看写入返回结果。先用 `formula` 模式确认公式文本已落表，再运行 `formula-verify` 聚合扫描错误；关键业务数值继续用 `raw_value` 抽样对账。详见 [sheet-formula](./sheet-formula.md)。 -**超时处理建议**：读取大范围数据时若出现超时或响应过慢，请主动缩小 `--range` 查询范围，**建议单次读取的单元格数量控制在 5000 个以内**（例如 50 行 × 100 列、100 行 × 50 列）。对于大表可采用分页读取策略： +**超时处理建议**：读取大范围数据时若出现超时或响应过慢，请主动缩小 `--range` 查询范围，**建议单次读取的单元格数量控制在 5000 个以内**（例如 50 行 × 100 列、100 行 × 50 列）。对于大表可采用分批读取策略，每次都必须检查 `hasMore`： - 先通过 `info` 获取 `nonEmptyRange.range`，或用 `nonEmptyRange.lastRow` / `nonEmptyRange.lastColumn` 确定 A1 边界 - 按行分批读取，如 `A1:J500`、`A501:J1000`、`A1001:J1500` …… - 避免不传 `--range` 直接读取整个大工作表 @@ -232,7 +248,7 @@ dws sheet list --node --format json # 2. 查看工作表详情（行列数、最后非空位置、mergedRanges 等） dws sheet info --node --sheet-id --format json -# 3. 读取全部数据 +# 3. 读取数据（只有 hasMore=false 才代表目标范围已完整返回） dws sheet range read --node --sheet-id --format json # 4. 读取指定区域 @@ -251,6 +267,8 @@ dws sheet range read --node --sheet-id --range "A1:D10" --f - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败 - `range read` 不传 `--range` 时默认读取整个工作表的全部非空数据 - `range read` 的 `--range` 支持 `Sheet1!A1:D10` 格式直接指定工作表（此时忽略 `--sheet-id`） +- ★ `csv-get` 和 `range read` 都必须检查 `hasMore`；`true` 时结合目标范围与 `returnedRange` 显式分批，CLI 不会自动续读 +- ★ `forbidden.document.sizeOverLimit` 是工作簿装载失败，不是 30,000 单元格部分成功；缩小 `--range` 不能修复 - ★ `csv-get` / `range read` / `range get` 不返回合并单元格结构；查看合并范围必须用 `sheet info` 的 `mergedRanges` - `table-get` 返回 table/dataframe 结构，适合需要 `columns` / `data` / `dtypes` / `formats` 的场景；它不返回 per-cell 元数据，也不替代 `range read` - ★ 大整数和长数字标识符回读校验：精确 ID 应是字符串 / `object`；若看到 `float64`，说明它已经按数值路径处理，超过 `9007199254740991` 时可能已丢精度 diff --git a/skills/mono/references/products/sheet/sheet-write-data.md b/skills/mono/references/products/sheet/sheet-write-data.md index eaa5e695..d2e61e65 100644 --- a/skills/mono/references/products/sheet/sheet-write-data.md +++ b/skills/mono/references/products/sheet/sheet-write-data.md @@ -386,9 +386,14 @@ Flags: **dropdown（下拉列表）**： ```json { "type": "text", "text": "High", "dataValidation": { "type": "dropdown", "options": [{"value":"High","color":"#00ff00"},{"value":"Low","color":"#ff0000"}], "enableMultiSelect": false } } +{ "dataValidation": { "type": "dropdown", "sourceRange": {"sheetId":"SOURCE_SHEET_ID","a1Notation":"T1:T3"}, "enableMultiSelect": false } } ``` -- `options`：必填，`[{value, color?}]` 数组 +- `options` 与 `sourceRange` 必须且只能提供一个 +- Inline：`options` 为非空 `[{value, color?}]` 数组 +- SourceRange：`sourceRange` 为 `{sheetId,a1Notation}`；可引用同一工作簿内其他工作表，支持普通区域、整行和整列。`a1Notation` 不带工作表前缀，不接受公式或多区域；颜色写入暂不支持 - `enableMultiSelect`：可选，是否多选，默认 false +- SourceRange 当前不会随工作表重命名或行列插入、删除、移动自动更新，结构操作后应重新写入 +- 复合 cell 写入中，如果值或样式已成功落盘但 SourceRange 校验失败，服务端可返回 `success:true` 并通过 `message` 说明下拉未创建；必须检查 `message` 并按需回读 **checkbox（复选框）**： ```json diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md b/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md index 8d922bec..4654840f 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md @@ -83,7 +83,8 @@ Example: {"toolName":"range update","input":{"sheet-id":"Sheet1","range":"A1","values":[[{"type":"text","text":"hello"}]]}}, {"toolName":"merge-cells","input":{"sheet-id":"Sheet1","range":"A1:B1","merge-type":"mergeAll"}}, {"toolName":"update-dimension","input":{"sheet-id":"Sheet1","dimension":"ROWS","start-index":"1","length":1,"pixel-size":40}}, - {"toolName":"group-dimension","input":{"sheet-id":"Sheet1","range":"3:7","group-state":"expand"}} + {"toolName":"group-dimension","input":{"sheet-id":"Sheet1","range":"3:7","group-state":"expand"}}, + {"toolName":"set-dropdown","input":{"sheet-id":"Sheet1","range":"C2:C100","source-sheet-id":"SourceSheet","source-range":"T1:T3"}} ]' dws sheet batch-update --node --continue-on-error --operations '[...]' Flags: @@ -101,6 +102,7 @@ Notes: - operations 最多 20 条 - 当需要对多个区域执行相同清除时，优先使用 `range batch-clear`（更简洁） - `csv-put` 子操作与独立命令语义一致：CSV 字段值以 `=` 开头时按公式解析；前加单引号时写入以 `=` 开头的字面文本 + - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。SourceRange 颜色写入暂不支持，且不会随 sheet 重命名或行列结构操作自动更新 - 典型场景：先插入行列再写入数据、先清除再写入、批量合并+调整行高列宽 - `group-dimension` 在 batch 中只适合默认展开分组；需要 `--group-state fold` 时请使用独立 `dws sheet group-dimension` - `table-put` 不支持放进 batch-update；结构化 table 请用独立 `dws sheet table-put` diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md b/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md index 0b135aa4..b6e2e658 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md @@ -7,6 +7,7 @@ 用户说"设置下拉列表/下拉选项/下拉菜单/添加下拉/配置下拉": - 设置下拉列表 → `set-dropdown` - 设置多选下拉 → `set-dropdown --multi-select` +- 引用单元格区域作为候选项 → `set-dropdown --source-sheet-id ... --source-range ...` 用户说"查看下拉列表/获取下拉配置/下拉列表有哪些选项": - 获取下拉列表配置 → `get-dropdown` @@ -29,18 +30,25 @@ Example: dws sheet set-dropdown --node --sheet-id --range "B2:B50" \ --options '[{"value":"高","color":"#ff0000"},{"value":"中","color":"#ffaa00"},{"value":"低","color":"#00ff00"}]' \ --multi-select + + # 引用同一工作簿内另一工作表的区域作为候选项来源 + dws sheet set-dropdown --node --sheet-id --range "C2:C100" \ + --source-sheet-id --source-range "T1:T3" Flags: - --node string 表格文档 ID 或 URL (必填) - --sheet-id string 工作表 ID 或名称 (必填) - --range string 目标单元格范围，A1 表示法，如 A2:A100 (必填) - --options string 下拉选项 JSON 数组 (必填)，如 '[{"value":"选项1","color":"#ff0000"}]' - --multi-select 是否允许多选（默认单选） + --node string 表格文档 ID 或 URL (必填) + --sheet-id string 工作表 ID 或名称 (必填) + --range string 目标单元格范围，A1 表示法，如 A2:A100 (必填) + --options string Inline 下拉选项 JSON 数组，与 --source-range 二选一 + --source-sheet-id string SourceRange 来源工作表 ID，与 --source-range 同时指定 + --source-range string SourceRange 来源区域，与 --options 二选一；不带工作表前缀 + --multi-select 是否允许多选（默认单选） ``` -在指定单元格范围内设置下拉列表。设置后用户可从预定义选项中选择值。 -- **用途**：为单元格配置下拉列表，支持自定义选项颜色和多选。 +在指定单元格范围内设置下拉列表。Inline 模式直接存储选项；SourceRange 模式引用同一工作簿内的来源区域，可跨工作表，并支持普通区域、整行和整列。 +- **用途**：为单元格配置静态选项或区域来源下拉，两种模式都支持多选；颜色仅 Inline 支持。 - **场景**：规范数据输入，如状态选择（完成/进行中/待处理）、优先级（高/中/低）等。 -- **注意**：选项值不能包含英文逗号；如果目标范围已存在下拉列表，会被新配置覆盖。 +- **注意**：`--options` 与 `--source-range` 必须且只能指定一个。`--source-range` 只写 `T1:T3`、`T:T`、`1:3` 这类 A1 区域，来源工作表通过 `--source-sheet-id` 单独指定；不接受工作表前缀、公式或多区域。SourceRange 颜色写入暂不支持。 +- **静态引用限制**：服务端写入的 SourceRange 不会随工作表重命名或行列插入、删除、移动自动更新；结构操作后应重新写入该下拉来源。 ### 获取下拉列表配置 ``` @@ -55,10 +63,10 @@ Flags: --range string 查询范围，A1 表示法，如 A1:A100 (必填) ``` -查询指定范围内的下拉列表配置信息，包括选项值、颜色和是否多选。 +查询指定范围内的下拉列表配置信息。 - **用途**：查看单元格已设置的下拉列表选项和配置。 - **场景**：在修改下拉列表前先查询现有配置；确认下拉列表是否设置成功。 -- **返回**：`dataValidations` 数组，相同选项的单元格聚合为一组，每组包含 `conditionValues`（选项值）、`ranges`（覆盖范围）、`options`（含 `enableMultiSelect` 和 `colorValueMap`）。范围内无下拉列表时 `hasDropdown` 为 false。 +- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`sourceRange:{sheetId,a1Notation}`、`enableMultiSelect` 和 `ranges`，不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 ### 删除下拉列表 ``` @@ -81,14 +89,15 @@ Flags: | 操作 | 从返回中提取 | 用于 | |------|-------------|------| -| `set-dropdown` | `range` 实际设置范围、`optionCount` 选项数量、`enableMultiSelect` 是否多选 | 确认下拉列表设置成功 | -| `get-dropdown` | `hasDropdown` 是否存在下拉、`dataValidations` 下拉配置列表（含 `conditionValues`、`ranges`、`options`） | 查看已有下拉配置 | +| `set-dropdown` | `range` 实际设置范围、`enableMultiSelect` 是否多选；仅 Inline 模式返回 `optionCount` | 确认下拉列表设置成功 | +| `get-dropdown` | `hasDropdown`、`dataValidations`；按 `sourceType` 区分 Inline 与 SourceRange | 查看已有下拉配置 | | `delete-dropdown` | `range` 实际删除范围 | 确认下拉列表删除完成 | | `list` | 工作表的 `sheetId` | info / range read / range update / find 的 --sheet-id | ## 注意事项 - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等） -- `set-dropdown` 在指定范围内设置下拉列表，`--options` 为 JSON 数组，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB` 格式）。选项值不能包含英文逗号。`--multi-select` 启用多选模式。如果目标范围已存在下拉列表，会被新配置覆盖 -- `get-dropdown` 查询指定范围内的下拉列表配置，返回 `dataValidations` 数组，相同选项的单元格聚合为一组。无下拉列表时 `hasDropdown` 为 false +- `set-dropdown` 的 Inline 模式使用 `--options`，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB`）；SourceRange 模式使用 `--source-sheet-id` + `--source-range`。两种模式均可用 `--multi-select`，并会覆盖目标范围已有下拉 +- SourceRange 当前是静态引用，不会随 sheet 重命名或行列结构操作自动调整；颜色写入暂不支持 +- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，不回退展开候选值 - `delete-dropdown` 删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。已填写的值不会被清除。目标范围不存在下拉列表时操作仍返回成功 diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md b/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md index 0e2ae054..4963fc2a 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md @@ -13,7 +13,7 @@ | 读取目的 | 推荐命令 | 说明 | |---------|---------|------| -| 快速查看纯值、数据分析、大表分批读取 | `csv-get` | CSV 格式，token 消耗约为 JSON 的 1/3，内置 maxChars 防爆 | +| 快速查看纯值、数据分析、大表分批读取 | `csv-get` | CSV 格式，token 消耗约为 JSON 的 1/3，内置 30,000 单元格和 maxChars 防爆 | | 按 table/dataframe 协议读取 | `table-get` | 返回 `columns` / `data` / `dtypes` / `formats`；默认首行为表头 | | 查看数据验证配置（下拉/复选框） | `range read` | 返回 per-cell 结构，含 dataValidation | | 查看单元格样式（背景色/字体/对齐等） | `range read` | 返回 per-cell 结构，含 cellStyles（仅显式设置的样式） | @@ -52,7 +52,10 @@ Flags: - `csv` — CSV 文本，每逻辑行前加 `[row=N]` 前缀标注真实表格行号。行号一律从此前缀读取，禁止手算 - `colIndices` — 列字母映射数组（如 `["A","B","C"]`）。定位列字母用 `colIndices[j]`，禁止手数逗号 - `rowIndices` — 行号映射数组（如 `[1,2,3]`） -- `hasMore` — 是否因 maxChars 截断。为 true 时需要调整 `--range` 继续分页读取 +- `hasMore` — 完整目标范围是否还有未返回数据。`true` 是部分成功，不能宣称已读完 +- `truncationReasons` — 部分返回原因。`max_cells` 表示命中单次 30,000 单元格上限；`max_chars` 表示命中 CSV 字符上限，两者可同时出现 +- `resolvedRange` — 仅在未传 `--range` 时返回，表示底层解析出的完整目标范围 +- `returnedRange` — 本次实际完整返回的精确范围；它不是服务端续读游标 `csv-get` 不返回合并单元格结构。若 CSV 中出现合并区域的非左上角单元格为空，不能据此判断该区域"无内容"；需要先用 `dws sheet info --node --sheet-id --format json` 读取 `mergedRanges`，再结合左上角单元格理解合并区域语义。 @@ -63,10 +66,15 @@ Flags: | `raw_value` | 原始值（如 1000、45808） | 数据处理、计算 | | `formula` | 公式文本（如 =SUM(A1:A10)），无公式时回退原始值 | 查看/复制公式 | -**大表分批读取**：当 `hasMore=true` 或数据量很大时，按行窗口分批： -- 先通过 `info` 获取 `nonEmptyRange.range`，或用 `nonEmptyRange.lastRow` / `nonEmptyRange.lastColumn` 确定 A1 边界 -- 分批读取：`--range "A1:J500"`、`--range "A501:J1000"` …… -- 单次建议 ≤5000 单元格 +**大表分批读取**：`csv-get` 不会自动发起后续请求。当 `hasMore=true` 时： +- 显式传了 `--range` 时，该范围是完整目标；未传时，以 `resolvedRange` 为完整目标 +- 根据 `returnedRange` 的结束行，从下一行开始显式构造新的 `--range`；例如目标是 `A1:A30001`、本次返回 `A1:A30000`，则继续读 `A30001:A30001` +- `max_cells` 不能通过增大 `--max-chars` 解决；`max_chars` 且没有 `returnedRange` 时，增大 `--max-chars` 或缩小列范围 +- 上述完成度协议覆盖未传 `--range` 和显式有限矩形范围；`A:A`、`1:1` 等非有限范围可能不返回完成度字段，建议先用 `sheet info` 的 `nonEmptyRange` 换算成有限范围再读 +- 即使未命中硬上限，单次仍建议控制在 5000 单元格以内，减少超时和 token 消耗 + +**工作簿过大失败与部分成功不同**：收到顶层 +`errorCode=forbidden.document.sizeOverLimit` 和对应 `errorMessage` 时，表示工作簿整体无法装载。应停止读取并提示创建更小副本或拆分工作簿；缩小 `--range` 不能解决这类错误。不要把它当成 `hasMore=true` 的可续读结果。 ### 以 table/dataframe 协议读取结构化数据 ``` @@ -130,6 +138,8 @@ Flags: ``` **返回字段说明**： +- `rowIndices` / `colIndices` — 本次返回的真实行号与列字母映射 +- `hasMore` / `truncationReasons` / `resolvedRange` / `returnedRange` — 语义与 `csv-get` 相同；`range read` 的 `truncationReasons` 主要为 `max_cells` - `cells` — 二维数组，第一维为行，第二维为列。每个元素为 per-cell 对象，字段如下： | 字段 | 类型 | 是否必有 | 说明 | @@ -146,10 +156,16 @@ Flags: | type | 字段 | 说明 | |------|------|------| -| `dropdown` | `options: [{value: string, color?: string}]` | 下拉选项列表 | -| `dropdown` | `enableMultiSelect: boolean` | 是否允许多选 | +| `dropdown` Inline | `sourceType: "inline"` | 静态选项模式 | +| `dropdown` Inline | `options: [{value: string, color?: string}]` | 下拉选项列表 | +| `dropdown` Inline | `enableMultiSelect: boolean` | 是否允许多选 | +| `dropdown` SourceRange | `sourceType: "sourceRange"` | 区域来源模式 | +| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 同一工作簿内的来源工作表和规范化 A1 区域 | +| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置 | | `checkbox` | `checked: boolean` | 当前勾选状态 | +SourceRange 模式只返回引用元数据，不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。 + **hyperlink 结构**： | type | 字段 | 说明 | @@ -216,7 +232,7 @@ Flags: **公式校验建议**：写公式后不要只看写入返回结果。先用 `formula` 模式确认公式文本已落表，再运行 `formula-verify` 聚合扫描错误；关键业务数值继续用 `raw_value` 抽样对账。详见 [sheet-formula](./sheet-formula.md)。 -**超时处理建议**：读取大范围数据时若出现超时或响应过慢，请主动缩小 `--range` 查询范围，**建议单次读取的单元格数量控制在 5000 个以内**（例如 50 行 × 100 列、100 行 × 50 列）。对于大表可采用分页读取策略： +**超时处理建议**：读取大范围数据时若出现超时或响应过慢，请主动缩小 `--range` 查询范围，**建议单次读取的单元格数量控制在 5000 个以内**（例如 50 行 × 100 列、100 行 × 50 列）。对于大表可采用分批读取策略，每次都必须检查 `hasMore`： - 先通过 `info` 获取 `nonEmptyRange.range`，或用 `nonEmptyRange.lastRow` / `nonEmptyRange.lastColumn` 确定 A1 边界 - 按行分批读取，如 `A1:J500`、`A501:J1000`、`A1001:J1500` …… - 避免不传 `--range` 直接读取整个大工作表 @@ -232,7 +248,7 @@ dws sheet list --node --format json # 2. 查看工作表详情（行列数、最后非空位置、mergedRanges 等） dws sheet info --node --sheet-id --format json -# 3. 读取全部数据 +# 3. 读取数据（只有 hasMore=false 才代表目标范围已完整返回） dws sheet range read --node --sheet-id --format json # 4. 读取指定区域 @@ -251,6 +267,8 @@ dws sheet range read --node --sheet-id --range "A1:D10" --f - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败 - `range read` 不传 `--range` 时默认读取整个工作表的全部非空数据 - `range read` 的 `--range` 支持 `Sheet1!A1:D10` 格式直接指定工作表（此时忽略 `--sheet-id`） +- ★ `csv-get` 和 `range read` 都必须检查 `hasMore`；`true` 时结合目标范围与 `returnedRange` 显式分批，CLI 不会自动续读 +- ★ `forbidden.document.sizeOverLimit` 是工作簿装载失败，不是 30,000 单元格部分成功；缩小 `--range` 不能修复 - ★ `csv-get` / `range read` / `range get` 不返回合并单元格结构；查看合并范围必须用 `sheet info` 的 `mergedRanges` - `table-get` 返回 table/dataframe 结构，适合需要 `columns` / `data` / `dtypes` / `formats` 的场景；它不返回 per-cell 元数据，也不替代 `range read` - ★ 大整数和长数字标识符回读校验：精确 ID 应是字符串 / `object`；若看到 `float64`，说明它已经按数值路径处理，超过 `9007199254740991` 时可能已丢精度 diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md b/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md index eaa5e695..d2e61e65 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md @@ -386,9 +386,14 @@ Flags: **dropdown（下拉列表）**： ```json { "type": "text", "text": "High", "dataValidation": { "type": "dropdown", "options": [{"value":"High","color":"#00ff00"},{"value":"Low","color":"#ff0000"}], "enableMultiSelect": false } } +{ "dataValidation": { "type": "dropdown", "sourceRange": {"sheetId":"SOURCE_SHEET_ID","a1Notation":"T1:T3"}, "enableMultiSelect": false } } ``` -- `options`：必填，`[{value, color?}]` 数组 +- `options` 与 `sourceRange` 必须且只能提供一个 +- Inline：`options` 为非空 `[{value, color?}]` 数组 +- SourceRange：`sourceRange` 为 `{sheetId,a1Notation}`；可引用同一工作簿内其他工作表，支持普通区域、整行和整列。`a1Notation` 不带工作表前缀，不接受公式或多区域；颜色写入暂不支持 - `enableMultiSelect`：可选，是否多选，默认 false +- SourceRange 当前不会随工作表重命名或行列插入、删除、移动自动更新，结构操作后应重新写入 +- 复合 cell 写入中，如果值或样式已成功落盘但 SourceRange 校验失败，服务端可返回 `success:true` 并通过 `message` 说明下拉未创建；必须检查 `message` 并按需回读 **checkbox（复选框）**： ```json From 7bf8ce79bd3c5c5a29ea7f0a76de2ed6cb8e67d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 12:07:06 +0800 Subject: [PATCH 046/250] chore(policy): to #85411130 add idempotency flag migration ledger --- .../approved-flag-migrations-v1.json | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index d52e59e4..a89aaea1 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -928,6 +928,39 @@ "state": "pending", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, + { + "command": "dws chat message send", + "legacy": { + "name": "uuid", + "before": { + "present": true, + "type": "string", + "scope": "local", + "required": false + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "hidden": true, + "alias_of": "idempotency-key" + } + }, + "canonical": { + "name": "idempotency-key", + "before": { + "present": false + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "required": false + } + }, + "state": "pending", + "reason": "保留旧 argv 兼容性，并将幂等参数规范 flag 设为唯一可见入口" + }, { "command": "dws chat message set-pin-msg", "legacy": { From def6ed4d2fbb89639e2b20fa9987536fd8932d9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 12:16:16 +0800 Subject: [PATCH 047/250] test(chat): align list-all time expectations --- internal/helpers/chat_message_pagination_test.go | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 78eca26c..61ad4c2f 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -83,7 +83,12 @@ func TestChatMessagePaginationDefaultSinglePageUnchanged(t *testing.T) { args: []string{"message", "list-all", "--start", "2026-08-01 00:00:00", "--end", "2026-08-02 00:00:00"}, server: "", tool: "search_messages_by_time_range", - want: map[string]any{"startTime": "2026-08-01 00:00:00", "endTime": "2026-08-02 00:00:00", "limit": 50, "cursor": "0"}, + want: map[string]any{ + "startTime": formatChatMessageListAllTime(1785513600000), + "endTime": formatChatMessageListAllTime(1785600000000), + "limit": 50, + "cursor": "0", + }, }, { name: "list-by-sender", @@ -276,8 +281,8 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { t.Fatalf("startTime = %d, want %d", startMs, wantStartMs) } if tt.wantTool == "search_messages_by_time_range" { - assertStringArg(t, got.args["startTime"], "2025-12-31 00:00:00") - assertStringArg(t, got.args["endTime"], "2026-01-01 00:00:00") + assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(wantStartMs)) + assertStringArg(t, got.args["endTime"], formatChatMessageListAllTime(endMs)) } }) } @@ -343,7 +348,7 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax) } if tt.wantTool == "search_messages_by_time_range" { - assertStringArg(t, got.args["startTime"], "2026-01-01 00:00:00") + assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(startMs)) parseChatMessageListAllTimeArg(t, got.args["endTime"]) } }) @@ -423,7 +428,7 @@ func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time { if strings.Contains(raw, "T") { t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw) } - parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, shanghaiLocation()) + parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local) if err != nil { t.Fatalf("time arg = %q, parse err = %v", raw, err) } From 43882bf9598c698d4582794fbf0bd8d122db02f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 13:01:32 +0800 Subject: [PATCH 048/250] fix(chat): preserve schema compatibility for im flags --- internal/cli/schema_constraints_runtime.go | 8 +- .../cli/schema_parameter_mapping_ledger.go | 3 +- internal/helpers/chat.go | 122 +++++++++++++++--- 3 files changed, 110 insertions(+), 23 deletions(-) diff --git a/internal/cli/schema_constraints_runtime.go b/internal/cli/schema_constraints_runtime.go index 1bb7ea9b..397a6708 100644 --- a/internal/cli/schema_constraints_runtime.go +++ b/internal/cli/schema_constraints_runtime.go @@ -37,7 +37,7 @@ func init() { registerRequireOneOf("calendar.query_busy_status", "users", "rooms") registerRequireTogether("calendar.update_calendar_event", "recurrence-type", "recurrence-interval", "recurrence-range-type") registerExclusiveOneOf("chat.search_messages_by_sender", "sender-user-id", "sender-open-dingtalk-id") - registerExclusiveOneOf("chat.create_and_send_card", "conversation-id", "open-dingtalk-id") + registerExclusiveOneOf("chat.create_and_send_card", "group", "receiver") RegisterRuntimeSchemaConstraints("chat.chat_permission_grant", RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"conversation-id", "open-dingtalk-id", "user"}}, RequireOneOf: [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}}, @@ -45,14 +45,14 @@ func init() { registerExclusiveOneOf("chat.chat_permission_grant_cross_org_data", "target-org-id", "all") registerExclusiveOneOf("chat.clear_conversation_messages", "conversation-id", "id", "chat") registerExclusiveOneOf("chat.clear_conversation_red_point", "conversation-id", "id", "chat") - registerExclusiveOneOf("chat.get_conversation_info", "conversation-id", "user", "open-dingtalk-id") + registerExclusiveOneOf("chat.get_conversation_info", "group", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.hide_conversation", "conversation-id", "id", "chat") - registerExclusiveOneOf("chat.list_conversation_message_v2", "conversation-id", "user", "open-dingtalk-id") + registerExclusiveOneOf("chat.list_conversation_message_v2", "group", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.list_individual_chat_message", "user", "open-dingtalk-id") registerExclusiveOneOf("chat.mark_conversation_unread", "conversation-id", "id", "chat") registerExclusiveOneOf("chat.mark_message_read", "conversation-id", "id", "chat") registerRequireOneOf("chat.send_personal_message", "text", "content", "msg-type") - registerExclusiveOneOf("chat.send_robot_message", "conversation-id", "users") + registerExclusiveOneOf("chat.send_robot_message", "group", "users") registerRequireOneOf("chat.set_group_member_mute_list", "users", "user") registerExclusiveOneOf("chat.share_group_invite_url", "target", "receiver") registerExclusiveOneOf("chat.transfer_group_owner", "new-owner", "user") diff --git a/internal/cli/schema_parameter_mapping_ledger.go b/internal/cli/schema_parameter_mapping_ledger.go index 605d0a19..a68844f7 100644 --- a/internal/cli/schema_parameter_mapping_ledger.go +++ b/internal/cli/schema_parameter_mapping_ledger.go @@ -253,6 +253,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "chat.batch_update_group_chat_settings --items": "Reviewed unpinned adapter: chat.batch_update_group_chat_settings has no singular pinned interface_ref; --items is a CLI wrapper input and does not publish a direct interface property.", "chat.create_text_emotion --background-id": "Runtime extension: the executable helper forwards backgroundId to im/create_text_emotion, but the pinned source-revision metadata does not declare that optional property; preserve the compatibility flag without advertising it as a pinned RPC field.", "chat.get_group_mute_config --conversation-id": "Reviewed unpinned adapter: chat.get_group_mute_config has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", + "chat.get_group_mute_config --group": "Reviewed legacy Schema compatibility: the historical visible --group wrapper input was required but did not publish a direct interface property.", "chat.list_conversation_message_v2 --open-dingtalk-id": "selects the alternate list_individual_chat_message branch", "chat.list_conversation_message_v2 --user": "selects the alternate list_individual_chat_message branch", "chat.list_message_favorites --cursor": "Reviewed unpinned adapter: chat.list_message_favorites has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.", @@ -265,9 +266,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "chat.query_msg_read_status --users": "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to targetUserIds or targetOpenDingTalkIds according to its runtime ID shape; there is no single RPC property for this flag", "chat.remove_message_favorite --open-conversation-id": "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.remove_message_favorite --open-message-id": "Reviewed unpinned adapter: chat.remove_message_favorite has no singular pinned interface_ref; --open-message-id is a CLI wrapper input and does not publish a direct interface property.", - "chat.update_group_nick --conversation-id": "Reviewed unpinned adapter: chat.update_group_nick has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.update_text_emotion --conversation-id": "Reviewed unpinned adapter: chat.update_text_emotion has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", - "chat.upgrade_group_to_external --conversation-id": "Reviewed unpinned adapter: chat.upgrade_group_to_external has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.reply_personal_message --ref-msg-id": "serialized into the aggregate content JSON string", "chat.reply_personal_message --ref-sender": "resolved then serialized into the aggregate content JSON string", "chat.reply_personal_message --text": "serialized into the aggregate content JSON string", diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index e0ea7d4e..99da3684 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -2966,12 +2966,13 @@ func newChatCommand() *cobra.Command { UseWhen: []string{"用户明确指定某个会话，并要读取消息或追溯引用回复中的原消息上下文时"}, AvoidWhen: []string{"跨全部会话按时间查询时使用 chat message list-all"}, Examples: []string{ - "dws chat message list --conversation-id --time \"2026-07-01 00:00:00\" --limit 50", - "dws chat message list --conversation-id --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", + "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50", + "dws chat message list --group --time \"2026-07-01 00:00:00\" --limit 50 --jq '.messages[] | {messageId, text}'", }, }, Parameters: []contract.ParamDecl{ {Name: "direction", Property: "forward"}, + {Name: "group", Property: "openconversation_id", Required: boolPtr(false)}, }, }, }) @@ -3314,11 +3315,12 @@ func newChatCommand() *cobra.Command { AgentSummary: "以当前用户身份发送群聊或单聊消息", UseWhen: []string{"用户明确要以个人身份发送文本或媒体消息时；响应返回 openTaskId 后用 chat message query-send-status 确认投递并取得后续操作所需的消息 ID"}, AvoidWhen: []string{"机器人身份或 Webhook 发送应使用对应命令"}, - Examples: []string{"dws chat message send --conversation-id \"项目已更新\""}, + Examples: []string{"dws chat message send --group \"项目已更新\""}, }, Parameters: []contract.ParamDecl{ {Name: "ai-tag", Property: "clawType", InterfaceType: "string"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"}, }, }, @@ -3513,11 +3515,12 @@ func newChatCommand() *cobra.Command { AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊", UseWhen: []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时"}, AvoidWhen: []string{"个人身份发送或自定义 Webhook 告警不要使用"}, - Examples: []string{"dws chat message send-by-bot --robot-code --conversation-id --title \"日报\" --text \"今日进展\""}, + Examples: []string{"dws chat message send-by-bot --robot-code --group --title \"日报\" --text \"今日进展\""}, }, // Keep title/text required_when out of Schema: the runtime switch above // enforces Markdown inputs, while adding it breaks merge-base compatibility. Parameters: []contract.ParamDecl{ + {Name: "group", Property: "group", Required: boolPtr(false)}, {Name: "msg-type", RequiredWhen: "image-url or file-path is provided", Enum: []string{"markdown", "image", "file"}}, {Name: "image-url", RequiredWhen: "msg-type is image"}, {Name: "file-path", RequiredWhen: "msg-type is file"}, @@ -3745,6 +3748,7 @@ func newChatCommand() *cobra.Command { Examples: []string{"dws chat message list-topic-replies --conversation-id --topic-id --limit 50"}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openconversationId"}, {Name: "direction", Property: "forward"}, {Name: "limit", Property: "pageSize"}, {Name: "time", Property: "startTime"}, @@ -3896,6 +3900,7 @@ func newChatCommand() *cobra.Command { }, Parameters: append([]contract.ParamDecl{ {Name: "end", Property: "endTime"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "start", Property: "startTime"}, }, pagedMCPParamDecls()...), }, @@ -4088,6 +4093,7 @@ func newChatCommand() *cobra.Command { }, Parameters: append([]contract.ParamDecl{ {Name: "end", Property: "endTime"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "query", Property: "keyword"}, {Name: "start", Property: "startTime"}, }, pagedMCPParamDecls()...), @@ -4606,6 +4612,10 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageListCmd.Flags().Int("limit", 0, "返回数量，不传则不限制") chatMessageListCmd.Flags().Int("size", 0, "--limit 的旧版别名") _ = chatMessageListCmd.Flags().MarkHidden("size") + cli.AnnotateRuntimeConstraints(chatMessageListCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, + RequireOneOf: [][]string{{"group", "user", "open-dingtalk-id"}}, + }) chatMessageListDirectCmd.Flags().String("user", "", "对方 userId（同组织内同事，与 --open-dingtalk-id 二选一）") chatMessageListDirectCmd.Flags().String("open-dingtalk-id", "", "对方 openDingTalkId（非同组织普通好友场景，与 --user 二选一）") chatMessageListDirectCmd.Flags().String("time", "", "开始时间，格式 yyyy-MM-dd HH:mm:ss (必填)") @@ -4655,8 +4665,8 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendCmd.Flags().String("uuid", "", "幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选）") cli.AttachRuntimeSchema(chatMessageSendCmd, "chat", "send_personal_message", "hardcoded:chat") cli.AnnotateRuntimeConstraints(chatMessageSendCmd, cli.RuntimeSchemaConstraints{ - MutuallyExclusive: [][]string{{"conversation-id", "user", "open-dingtalk-id"}}, - RequireOneOf: [][]string{{"conversation-id", "user", "open-dingtalk-id"}}, + MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, + RequireOneOf: [][]string{{"group", "user", "open-dingtalk-id"}}, }) cli.AnnotateRuntimePositionals(chatMessageSendCmd, contract.RuntimeSchemaPositional{ Name: "content", @@ -4681,6 +4691,10 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendByBotCmd.Flags().String("open-dingtalk-ids", "", "用户 openDingtalkId 列表，逗号分隔（单聊时可替代 --users，可选）") chatMessageSendByBotCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingtalkId 列表，逗号分隔（仅群聊时生效，可选）") chatMessageSendByBotCmd.Flags().Bool("at-all", false, "@所有人（可选），服务端接收字符串 true/false") + cli.AnnotateRuntimeConstraints(chatMessageSendByBotCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"group", "users"}}, + RequireOneOf: [][]string{{"group", "users"}}, + }) cli.AnnotateRuntimeFlagFormat(chatMessageSendByBotCmd, "file-path", "file-path") chatMessageRecallByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)") @@ -4985,10 +4999,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id AgentSummary: "获取群聊或单聊会话的详细信息", UseWhen: []string{"已知群 ID 或用户标识并需要解析会话详情时"}, AvoidWhen: []string{"按群名查找会话时使用 chat search"}, - Examples: []string{"dws chat conversation-info --conversation-id --format json"}, + Examples: []string{"dws chat conversation-info --group --format json"}, }, Parameters: []contract.ParamDecl{ {Name: "open-dingtalk-id", Property: "openDingTalkId"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "user", Property: "openDingTalkId"}, }, }, @@ -5004,6 +5019,10 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatConversationInfoCmd.Flags().String("userId", "", "--user 的别名") _ = chatConversationInfoCmd.Flags().MarkHidden("userId") chatConversationInfoCmd.Flags().String("open-dingtalk-id", "", "单聊对方 openDingTalkId（单聊时使用）") + cli.AnnotateRuntimeConstraints(chatConversationInfoCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, + RequireOneOf: [][]string{{"group", "user", "open-dingtalk-id"}}, + }) // ── file 子命令（会话文件上传，不暴露 spaceId）─────────────── @@ -5343,6 +5362,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Parameters: []contract.ParamDecl{ {Name: "category-ids", Property: "categoryIds", Required: boolPtr(true), InterfaceType: "array"}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5401,6 +5421,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Parameters: []contract.ParamDecl{ {Name: "category-ids", Property: "categoryIds", Required: boolPtr(true), InterfaceType: "array"}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, }, }, @@ -5647,9 +5668,13 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message add-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ + {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, + {Name: "msg-id", Property: "openMsgId", Required: boolPtr(true)}, }, }, }) @@ -5660,6 +5685,9 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageAddEmojiCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageAddEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageAddEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") + cli.AnnotateRuntimeConstraints(chatMessageAddEmojiCmd, cli.RuntimeSchemaConstraints{ + RequireOneOf: [][]string{{"conversation-id", "group", "id", "chat"}}, + }) chatMessageRemoveEmojiCmd := &cobra.Command{ Use: "remove-emoji", @@ -5709,9 +5737,13 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message remove-emoji --conversation-id --message-id --emoji \"赞\""}, }, Parameters: []contract.ParamDecl{ + {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "emoji", Property: "emojiName"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, + {Name: "msg-id", Property: "openMsgId", Required: boolPtr(true)}, }, }, }) @@ -5722,6 +5754,9 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageRemoveEmojiCmd.Flags().String("open-conversation-id", "", "--conversation-id 的别名") chatMessageRemoveEmojiCmd.Flags().String("message-id", "", "消息 openMsgId (必填)") chatMessageRemoveEmojiCmd.Flags().String("emoji", "", "emoji 表情名称 (必填)") + cli.AnnotateRuntimeConstraints(chatMessageRemoveEmojiCmd, cli.RuntimeSchemaConstraints{ + RequireOneOf: [][]string{{"conversation-id", "group", "id", "chat"}}, + }) chatMessageAddTextEmotionCmd := &cobra.Command{ Use: "add-text-emotion", @@ -5773,8 +5808,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message add-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ + {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, + {Name: "msg-id", Property: "openMsgId", Required: boolPtr(true)}, }, }, }) @@ -5788,6 +5827,9 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageAddTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") chatMessageAddTextEmotionCmd.Flags().String("text", "", "文字内容 (必填)") chatMessageAddTextEmotionCmd.Flags().String("background-id", "", "背景 ID (必填)") + cli.AnnotateRuntimeConstraints(chatMessageAddTextEmotionCmd, cli.RuntimeSchemaConstraints{ + RequireOneOf: [][]string{{"conversation-id", "group", "id", "chat"}}, + }) chatMessageRemoveTextEmotionCmd := &cobra.Command{ Use: "remove-text-emotion", @@ -5839,8 +5881,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Examples: []string{"dws chat message remove-text-emotion --conversation-id --message-id --emotion-id --emotion-name \"赞\" --text \"nice\" --background-id im_bg_5"}, }, Parameters: []contract.ParamDecl{ + {Name: "chat", Property: "openConversationId", Required: boolPtr(false)}, {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "id", Property: "openConversationId", Required: boolPtr(false)}, {Name: "message-id", Property: "openMsgId"}, + {Name: "msg-id", Property: "openMsgId", Required: boolPtr(true)}, }, }, }) @@ -5854,6 +5900,9 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageRemoveTextEmotionCmd.Flags().String("emotion-name", "", "表情名称 (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("text", "", "文字内容 (必填)") chatMessageRemoveTextEmotionCmd.Flags().String("background-id", "", "背景 ID (必填)") + cli.AnnotateRuntimeConstraints(chatMessageRemoveTextEmotionCmd, cli.RuntimeSchemaConstraints{ + RequireOneOf: [][]string{{"conversation-id", "group", "id", "chat"}}, + }) chatMessageUpdateTextEmotionCmd := &cobra.Command{ Use: "update-text-emotion", @@ -5935,6 +5984,9 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id for _, name := range []string{"message-id", "old-emotion-id", "emotion-id", "emotion-name", "text", "background-id"} { _ = chatMessageUpdateTextEmotionCmd.MarkFlagRequired(name) } + cli.AnnotateRuntimeConstraints(chatMessageUpdateTextEmotionCmd, cli.RuntimeSchemaConstraints{ + RequireOneOf: [][]string{{"conversation-id", "group", "id", "chat"}}, + }) // ── 创建文字表情（获取 emotionId）────────────────────── @@ -6066,13 +6118,15 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "创建并向群聊或单聊发送互动卡片；群聊创建时可 @成员或 @所有人", UseWhen: []string{"需要创建卡片且已准备接收会话或用户时；群聊创建可同时指定 @成员或 @所有人"}, AvoidWhen: []string{"只发送普通文本时使用 send 或 send-by-bot"}, - Examples: []string{"dws chat message send-card --conversation-id "}, + Examples: []string{"dws chat message send-card --group "}, }, Parameters: []contract.ParamDecl{ {Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds", Required: boolPtr(false), InterfaceType: "array"}, {Name: "conversation-id", Property: "openConversationId"}, + {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, {Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"}, + {Name: "receiver", Property: "receiverOpenDingTalkId", Required: boolPtr(false)}, }, }, }) @@ -6082,6 +6136,10 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 _ = chatMessageSendCardCmd.Flags().MarkHidden("receiver") chatMessageSendCardCmd.Flags().String("at-open-dingtalk-ids", "", "群聊创建卡片时 @ 的 openDingTalkId 列表，逗号分隔（仅与 --conversation-id 一起使用）") chatMessageSendCardCmd.Flags().Bool("at-all", false, "群聊创建卡片时 @ 所有人（仅与 --conversation-id 一起使用）") + cli.AnnotateRuntimeConstraints(chatMessageSendCardCmd, cli.RuntimeSchemaConstraints{ + MutuallyExclusive: [][]string{{"group", "receiver"}}, + RequireOneOf: [][]string{{"group", "receiver"}}, + }) chatMessageUpdateCardCmd := &cobra.Command{ Use: "update-card", @@ -6424,6 +6482,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group transfer-owner --conversation-id --new-owner "}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "new-owner", Property: "newOwnerOpenDingTalkId"}, }, }, @@ -6481,7 +6540,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"需要直接添加已知成员时使用 chat group members add"}, Examples: []string{"dws chat group invite-url --conversation-id --expires-seconds 86400"}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupInviteUrlCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -6591,7 +6652,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 }, Examples: []string{"dws chat group quit --conversation-id "}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupQuitCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -6642,7 +6705,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"没有真实可用 mediaId 时先完成媒体上传"}, Examples: []string{"dws chat group update-icon --conversation-id --icon-media-id @mediaId"}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupUpdateIconCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -6716,7 +6781,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"全员禁言和成员禁言使用专门的 mute 命令"}, Examples: []string{"dws chat group update-settings --conversation-id --setting-key searchable --status 1"}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupUpdateSettingsCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -7003,7 +7070,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group get-mute-config --conversation-id --format json"}, }, Parameters: []contract.ParamDecl{ - {Name: "group", Property: "openConversationId", Required: boolPtr(false)}, + {Name: "group", Required: boolPtr(true)}, }, }, }) @@ -7058,6 +7125,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-mute --conversation-id "}, }, Parameters: []contract.ParamDecl{ + {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "off", Property: "mute", Required: boolPtr(false)}, }, }, @@ -7152,6 +7220,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-mute-member --conversation-id --users userId1,userId2 --mute-time 3600000"}, }, Parameters: []contract.ParamDecl{ + {Name: "group", Property: "openConversationId", Required: boolPtr(true)}, {Name: "off", Property: "mute", Required: boolPtr(false)}, {Name: "users", Property: "openDingTalkIds"}, }, @@ -7231,6 +7300,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group set-admin --conversation-id --users userId1,userId2"}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "off", Property: "admin", Required: boolPtr(false)}, {Name: "users", Property: "openDingTalkIds"}, }, @@ -7344,7 +7414,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"查询某个成员已分配角色时使用 chat group-role query-user"}, Examples: []string{"dws chat group-role list --conversation-id "}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupRoleListCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -7389,7 +7461,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"设置系统管理员角色时使用 chat group set-admin"}, Examples: []string{"dws chat group-role add --conversation-id --name \"值班负责人\""}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupRoleAddCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -7438,6 +7512,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-role update --conversation-id --role-id --name \"新名称\""}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "role-id", Property: "openRoleId"}, }, }, @@ -7489,6 +7564,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-role remove --conversation-id --role-id "}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "role-id", Property: "openRoleId"}, }, }, @@ -7551,6 +7627,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-role set-user --conversation-id --user --role-ids roleId1,roleId2"}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "role-ids", Property: "openRoleIds"}, {Name: "user", Property: "openDingTalkId"}, }, @@ -7615,6 +7692,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-role remove-user --conversation-id --user --role-ids roleId1,roleId2"}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "role-ids", Property: "openRoleIds"}, {Name: "user", Property: "openDingTalkId"}, }, @@ -7677,6 +7755,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 Examples: []string{"dws chat group-role query-user --conversation-id --user "}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, {Name: "user", Property: "openDingTalkId"}, }, }, @@ -7927,7 +8006,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 }, Examples: []string{"dws chat group dismiss --conversation-id "}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupDismissCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -7984,7 +8065,9 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AvoidWhen: []string{"普通消息查询或群设置的其他开关不要使用"}, Examples: []string{"dws chat group set-history --conversation-id --option RECENT_100"}, }, - Parameters: []contract.ParamDecl{}, + Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId"}, + }, }, }) chatGroupSetHistoryCmd.Flags().String("conversation-id", "", "群聊 openConversationId (必填)") @@ -9321,6 +9404,7 @@ status 可选值: Examples: []string{"dws chat group update-alias --conversation-id --alias-title \"项目A群\""}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "alias-title", Property: "aliasTitle", Required: boolPtr(true)}, }, }, @@ -9629,6 +9713,7 @@ status 可选值: Examples: []string{"dws chat group notice create --conversation-id --content \"今晚维护\""}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "content", Property: "content", Required: boolPtr(true)}, {Name: "run-at", Property: "runAtText", Required: boolPtr(false)}, {Name: "send-ding", Property: "sendDing", Required: boolPtr(false)}, @@ -9696,6 +9781,7 @@ status 可选值: Examples: []string{"dws chat group notice edit --conversation-id --notice-id --content \"更新后的公告\""}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "content", Property: "content", Required: boolPtr(true)}, {Name: "notice-id", Property: "dataId", Required: boolPtr(true)}, {Name: "send-ding", Property: "sendDing", Required: boolPtr(false)}, @@ -9750,6 +9836,7 @@ status 可选值: Examples: []string{"dws chat group notice get --conversation-id --notice-id "}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "notice-id", Property: "dataId", Required: boolPtr(true)}, }, }, @@ -9814,6 +9901,7 @@ status 可选值: Examples: []string{"dws chat group notice list --conversation-id --limit 20"}, }, Parameters: []contract.ParamDecl{ + {Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)}, {Name: "cursor", Property: "cursor", Required: boolPtr(false)}, {Name: "limit", Property: "limit", Required: boolPtr(false)}, {Name: "scheduled", Property: "scheduled", Required: boolPtr(false)}, From d32bbe009dd638d8a455d2d98ca97efac54f52bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 13:28:00 +0800 Subject: [PATCH 049/250] fix(chat): expose idempotency key for message send --- internal/app/param_alias_e2e_test.go | 25 ++++++++++++++++++- .../param_alias_payload_equivalence_test.go | 6 ++--- internal/app/root_help_test.go | 8 ++++++ internal/cli/schema_catalog_test.go | 9 +++++++ internal/helpers/chat.go | 7 ++++-- 5 files changed, 49 insertions(+), 6 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 8267390c..a14170de 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -324,7 +324,7 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) { "chat", "message", "send", "--to-user", "D-recipient", "--text", "hello alias", - "--uuid", "alias-e2e", + "--idempotency-key", "alias-e2e", ) if err != nil { t.Fatalf("chat write alias E2E error = %v", err) @@ -350,6 +350,29 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) { } } +func TestCrossPlatformCoverageChatMessageSendLegacyUUIDAliasFinalPayload(t *testing.T) { + caller := ¶mAliasCaptureCaller{} + _, err := executeParamAliasE2E(t, caller, + "chat", "message", "send", + "--group", "fixture-conversation", + "--text", "hello legacy uuid", + "--uuid", "legacy-alias-e2e", + ) + if err != nil { + t.Fatalf("chat message send legacy uuid error = %v", err) + } + if len(caller.calls) != 1 || caller.calls[0].tool != "send_personal_message" { + t.Fatalf("chat calls = %#v", caller.calls) + } + payload := caller.calls[0].args + if payload["uuid"] != "legacy-alias-e2e" || payload["openConversationId"] != "fixture-conversation" { + t.Fatalf("chat legacy uuid payload = %#v", payload) + } + if _, exists := payload["idempotency-key"]; exists { + t.Fatalf("chat payload leaked CLI-only idempotency-key: %#v", payload) + } +} + func TestCrossPlatformCoverageChatReactionConversationAliasesReachCanonicalPayload(t *testing.T) { tests := []struct { name string diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 494a8b6c..0db9b2dc 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -88,7 +88,7 @@ var paramAliasCompleteCommands = map[string][]string{ "chat message recall": {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"}, "chat message reply": {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"}, "chat message search-advanced": {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"}, - "chat message send": {"chat", "message", "send", "--user", "D-recipient", "--text", "hello fixture", "--uuid", "param-alias-equivalence", "--yes"}, + "chat message send": {"chat", "message", "send", "--user", "D-recipient", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"}, "chat message send-by-bot": {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"}, "chat message send-by-webhook": {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"}, "contact +dept-members": {"contact", "+dept-members", "--dept", "Fixture Dept"}, @@ -163,8 +163,8 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ "sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", "D-sender", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"}, }, "chat message send": { - "group": {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--uuid", "param-alias-equivalence-group", "--yes"}, - "file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--uuid", "param-alias-equivalence-file", "--yes"}, + "group": {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"}, + "file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"}, }, "chat +conversation-set-top": { "conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"}, diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index eb370a7b..79c1c967 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -369,6 +369,14 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) { t.Fatalf("chat message send missing --%s", flag) } } + idempotencyKey := send.Flags().Lookup("idempotency-key") + if idempotencyKey == nil { + t.Fatal("chat message send missing --idempotency-key") + } + legacyUUID := send.Flags().Lookup("uuid") + if legacyUUID == nil || !legacyUUID.Hidden { + t.Fatalf("chat message send --uuid hidden = %#v, want hidden compatibility flag", legacyUUID) + } got, err := executeRootCaptureStdout(t, []string{ "chat", "file", "upload", diff --git a/internal/cli/schema_catalog_test.go b/internal/cli/schema_catalog_test.go index e653256a..0360ae3a 100644 --- a/internal/cli/schema_catalog_test.go +++ b/internal/cli/schema_catalog_test.go @@ -1356,6 +1356,7 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { {"chat message edit", "conversation-id", "openConversationId", true, ""}, {"chat message edit", "msg-id", "openMessageId", true, ""}, {"chat message edit", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"}, + {"chat message send", "idempotency-key", "uuid", false, ""}, {"chat message send-card", "at-all", "atAll", false, ""}, {"chat message send-card", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"}, {"chat message update-text-emotion", "msg-id", "openMsgId", true, ""}, @@ -1407,6 +1408,14 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) { t.Fatalf("chat message edit unexpectedly publishes hidden alias --%s", hidden) } } + sendLeaf, err = queryDeliverySchemaPayload([]string{"chat message send"}) + if err != nil { + t.Fatal(err) + } + sendParams = schemaMap(sendLeaf["parameters"]) + if _, ok := sendParams["uuid"]; ok { + t.Fatal("chat message send unexpectedly publishes hidden alias --uuid") + } listByConv, err := queryDeliverySchemaPayload([]string{"chat category list-by-conv"}) if err != nil { t.Fatal(err) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index dd91e2eb..1f8ad37f 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -2835,7 +2835,7 @@ func newChatCommand() *cobra.Command { groupID := flagOrFallback(cmd, "group", "conversation-id", "id", "chat") userID, _ := cmd.Flags().GetString("user") openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") - msgUuid, _ := cmd.Flags().GetString("uuid") + msgUuid := flagOrFallback(cmd, "idempotency-key", "uuid") specified := 0 if groupID != "" { specified++ @@ -3050,6 +3050,7 @@ func newChatCommand() *cobra.Command { {Name: "ai-tag", Property: "clawType", InterfaceType: "string"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds"}, {Name: "group", Property: "openConversationId"}, + {Name: "idempotency-key", Property: "uuid"}, {Name: "open-dingtalk-id", Property: "receiverOpenDingTalkId"}, }, }, @@ -4385,7 +4386,9 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 _ = chatMessageSendCmd.Flags().MarkHidden("file-type") _ = chatMessageSendCmd.Flags().MarkHidden("file-size") chatMessageSendCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）") - chatMessageSendCmd.Flags().String("uuid", "", "幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选）") + chatMessageSendCmd.Flags().String("idempotency-key", "", "幂等键，相同 key 在 24h 内不会重复发送（可选）") + chatMessageSendCmd.Flags().String("uuid", "", "--idempotency-key 的兼容别名") + _ = chatMessageSendCmd.Flags().MarkHidden("uuid") cli.AttachRuntimeSchema(chatMessageSendCmd, "chat", "send_personal_message", "hardcoded:chat") cli.AnnotateRuntimeConstraints(chatMessageSendCmd, cli.RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, From f3f117440702146a57614bbb9346577b166246a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 13:35:55 +0800 Subject: [PATCH 050/250] chore(ci): rerun pr checks From 8ee9fc3f48e209e79bf1fcab2ebd5df979309a11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Thu, 13 Aug 2026 13:50:18 +0800 Subject: [PATCH 051/250] =?UTF-8?q?fix:=20=E8=A1=A5=E5=85=85=E6=8B=9B?= =?UTF-8?q?=E8=81=98=E7=BB=93=E6=9E=9C=E4=B8=8E=E5=88=86=E9=A1=B5=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=20to#85340676?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../app/schema_agent_examples_dry_run_test.go | 8 ++ internal/helpers/recruit.go | 25 ++++- internal/helpers/recruit_test.go | 99 +++++++++++++++++++ test/fixtures/cli-interface-baseline.txt | 2 +- 4 files changed, 132 insertions(+), 2 deletions(-) diff --git a/internal/app/schema_agent_examples_dry_run_test.go b/internal/app/schema_agent_examples_dry_run_test.go index a3b8906f..5497810d 100644 --- a/internal/app/schema_agent_examples_dry_run_test.go +++ b/internal/app/schema_agent_examples_dry_run_test.go @@ -274,6 +274,7 @@ type agentExampleFiles struct { markdown string json string batch string + job string binary string image string } @@ -283,12 +284,14 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles { markdown := filepath.Join(root, "content.md") jsonFile := filepath.Join(root, "report.json") batch := filepath.Join(root, "styles.json") + job := filepath.Join(root, "job.json") binary := filepath.Join(root, "report.pdf") image := filepath.Join(root, "chart.png") for path, content := range map[string][]byte{ markdown: []byte("# Agent dry-run fixture\n\nNo business call is allowed.\n"), jsonFile: []byte(`[{"content":"Agent dry-run fixture","sort":"0","key":"fixture","contentType":"markdown","type":"1"}]`), batch: []byte(`[{"sheetId":"Sheet1","range":"A1:B2","fontWeight":"bold"}]`), + job: []byte(`{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL_TIME","requiredEdu":1,"minSalary":20000,"maxSalary":35000}`), binary: []byte("%PDF-1.4\n%%EOF\n"), image: {0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'}, } { @@ -301,6 +304,7 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles { markdown: "./" + filepath.Base(markdown), json: "./" + filepath.Base(jsonFile), batch: "./" + filepath.Base(batch), + job: "./" + filepath.Base(job), binary: "./" + filepath.Base(binary), image: "./" + filepath.Base(image), } @@ -351,6 +355,10 @@ func materializeAgentExampleArgv(argv []string, files agentExampleFiles) []strin replacement = files.markdown case "contents-file": replacement = files.json + case "from": + if strings.HasSuffix(strings.ToLower(value), "job.json") { + replacement = files.job + } case "batch": if strings.HasSuffix(strings.ToLower(value), "styles.json") { replacement = files.batch diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 315fbc39..c2756305 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -23,10 +23,29 @@ const ( ) var recruitDryRun = &contract.DryRunSpec{ - PreviewKind: contract.DryRunPreviewInvocation, + PreviewKind: contract.DryRunPreviewRequest, RemoteReads: false, } +var ( + recruitListResult = &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"object","description":"当前页招聘职位查询结果","properties":{"jobs":{"type":"array","description":"当前页职位记录","items":{"type":"object","description":"招聘职位摘要","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}},"hasMore":{"type":"boolean","description":"服务端是否还有下一页"},"nextCursor":{"description":"下一页游标；仅在 hasMore 为 true 时用于续查","oneOf":[{"type":"number"},{"type":"string"}]}},"additionalProperties":true}`), + } + recruitJobDetailResult = &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"object","description":"招聘职位详情","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"description":{"type":"string","description":"职位描述"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}`), + } + recruitCreateJobResult = &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"object","description":"招聘职位创建结果","properties":{"jobId":{"type":"string","description":"新创建的职位 ID"}},"required":["jobId"],"additionalProperties":true}`), + } +) + +func recruitCursorPagination() *contract.PaginationSpec { + return &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"} +} + func newRecruitCommand() *cobra.Command { contract.RegisterProductDecl(contract.ProductDecl{ ID: "recruit", @@ -86,6 +105,8 @@ func newRecruitJobListCommand() *cobra.Command { Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitListJobsTool, CanonicalPath: "recruit.list_jobs", CLIPath: "recruit job list", PrimaryCLIPath: "recruit job list"}, Description: "按条件分页查询招聘职位", DryRun: recruitDryRun, + Result: recruitListResult, + Pagination: recruitCursorPagination(), Interface: recruitMCPInterface(recruitListJobsTool), Selection: contract.SelectionSpec{ AgentSummary: "按关键词、状态、创建人等条件分页查询招聘职位", @@ -130,6 +151,7 @@ func newRecruitJobGetCommand() *cobra.Command { Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitGetJobTool, CanonicalPath: "recruit.get_job_detail", CLIPath: "recruit job get", PrimaryCLIPath: "recruit job get"}, Description: "根据职位 ID 查询招聘职位详情", DryRun: recruitDryRun, + Result: recruitJobDetailResult, Interface: recruitMCPInterface(recruitGetJobTool), Selection: contract.SelectionSpec{ AgentSummary: "获取指定招聘职位的完整信息", @@ -159,6 +181,7 @@ func newRecruitJobCreateCommand() *cobra.Command { Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitCreateJobTool, CanonicalPath: "recruit.create_job", CLIPath: "recruit job create", PrimaryCLIPath: "recruit job create"}, Description: "从 JSON 文件创建招聘职位", DryRun: recruitDryRun, + Result: recruitCreateJobResult, Interface: recruitMCPInterface(recruitCreateJobTool), Selection: contract.SelectionSpec{ AgentSummary: "使用结构化 JSON 创建招聘职位", diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 274ab409..77f319ba 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -14,6 +14,8 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) @@ -196,6 +198,52 @@ func TestRecruitCreateValidatesJobFile(t *testing.T) { } } +func TestRecruitValidationBranches(t *testing.T) { + statuses, err := transformRecruitStatuses(" open, ,open,closed ") + if err != nil || !reflect.DeepEqual(statuses, []int{1, 3}) { + t.Fatalf("statuses = %#v, err = %v", statuses, err) + } + + negativeCursor := newRecruitJobListCommand() + negativeCursor.SetArgs([]string{"--cursor", "-1"}) + if err := negativeCursor.Execute(); err == nil || !strings.Contains(err.Error(), "大于或等于 0") { + t.Fatalf("negative cursor error = %v", err) + } + + nullPath := filepath.Join(t.TempDir(), "null.json") + if err := os.WriteFile(nullPath, []byte("null"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := loadRecruitJobFile(nullPath); err == nil || !strings.Contains(err.Error(), "顶层必须是对象") { + t.Fatalf("null job error = %v", err) + } + + base := map[string]any{ + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", + "requiredEdu": float64(1), "minSalary": float64(20000), "maxSalary": float64(35000), + } + for _, test := range []struct { + name string + mutate func(map[string]any) + want string + }{ + {name: "string type", mutate: func(job map[string]any) { job["name"] = 1 }, want: "name 必须是字符串"}, + {name: "number type", mutate: func(job map[string]any) { job["requiredEdu"] = "本科" }, want: "requiredEdu 必须是数字"}, + {name: "salary range", mutate: func(job map[string]any) { job["minSalary"] = float64(40000) }, want: "minSalary 不能大于 maxSalary"}, + } { + t.Run(test.name, func(t *testing.T) { + job := make(map[string]any, len(base)) + for key, value := range base { + job[key] = value + } + test.mutate(job) + if err := validateRecruitJob(job); err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("validation error = %v, want %q", err, test.want) + } + }) + } +} + func TestRecruitCommandTree(t *testing.T) { root := newRecruitCommand() for _, path := range [][]string{{"job", "list"}, {"job", "get"}, {"job", "create"}} { @@ -205,3 +253,54 @@ func TestRecruitCommandTree(t *testing.T) { } } } + +func TestRecruitResultAndPaginationContractsReachContractFinal(t *testing.T) { + root := newRecruitCommand() + tests := []struct { + path []string + canonical string + resultField string + pagination bool + }{ + {path: []string{"job", "list"}, canonical: "recruit.list_jobs", resultField: "jobs", pagination: true}, + {path: []string{"job", "get"}, canonical: "recruit.get_job_detail", resultField: "jobId"}, + {path: []string{"job", "create"}, canonical: "recruit.create_job", resultField: "jobId"}, + } + for _, test := range tests { + t.Run(test.canonical, func(t *testing.T) { + leaf, _, err := root.Find(test.path) + if err != nil { + t.Fatal(err) + } + final, ok := contractfinal.RuntimeContractFinal(leaf) + if !ok || final.Identity == nil || final.Identity.CanonicalPath != test.canonical { + t.Fatalf("final identity = %#v, found = %v", final.Identity, ok) + } + if final.Result == nil { + t.Fatal("final Result is nil") + } + wantOutcomes := []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure} + if !reflect.DeepEqual(final.Result.Outcomes, wantOutcomes) { + t.Fatalf("outcomes = %#v, want %#v", final.Result.Outcomes, wantOutcomes) + } + var schema struct { + Type string `json:"type"` + Properties map[string]json.RawMessage `json:"properties"` + } + if err := json.Unmarshal(final.Result.DataSchema, &schema); err != nil { + t.Fatalf("unmarshal result data_schema: %v", err) + } + if schema.Type != "object" || len(schema.Properties[test.resultField]) == 0 { + t.Fatalf("result data_schema = %s, want object property %q", final.Result.DataSchema, test.resultField) + } + if test.pagination { + if final.Pagination == nil || final.Pagination.Kind != contract.PaginationKindCursor || + final.Pagination.CursorParameter != "cursor" || final.Pagination.MetaPath != contract.PaginationMetaPath { + t.Fatalf("pagination = %#v, want cursor contract", final.Pagination) + } + } else if final.Pagination != nil { + t.Fatalf("pagination = %#v, want nil", final.Pagination) + } + }) + } +} diff --git a/test/fixtures/cli-interface-baseline.txt b/test/fixtures/cli-interface-baseline.txt index fab13963..31193263 100644 --- a/test/fixtures/cli-interface-baseline.txt +++ b/test/fixtures/cli-interface-baseline.txt @@ -1,7 +1,7 @@ [root] runnable: true hidden: false - commands: agoal, aisearch, aitable, api, attendance, audit, auth, cache, calendar, chat, completion, config, contact, dev, devapp, devdoc, ding, doc, doctor, drive, event, help, hrbrain, live, mail, markdown, mcp, minutes, oa, pat, plugin, profile, recovery, report, schema, sheet, skill, todo, upgrade, version, whiteboard, wiki + commands: agoal, aisearch, aitable, api, attendance, audit, auth, cache, calendar, chat, completion, config, contact, dev, devapp, devdoc, ding, doc, doctor, drive, event, help, hrbrain, live, mail, markdown, mcp, minutes, oa, pat, plugin, profile, recovery, recruit, report, schema, sheet, skill, todo, upgrade, version, whiteboard, wiki flags: --client-id:string|required=false|hidden=false|no-opt=""|scope=persistent, --client-secret:string|required=false|hidden=false|no-opt=""|scope=persistent, --debug:bool|required=false|hidden=false|no-opt="true"|scope=persistent, --dry-run:bool|required=false|hidden=false|no-opt="true"|scope=persistent, --fields:string|required=false|hidden=false|no-opt=""|scope=persistent, -f/--format:string|required=false|hidden=false|no-opt=""|scope=persistent, -h/--help:bool|required=false|hidden=false|no-opt="true"|scope=local, --jq:string|required=false|hidden=false|no-opt=""|scope=persistent, --mock:bool|required=false|hidden=false|no-opt="true"|scope=persistent, -o/--output:string|required=false|hidden=true|no-opt=""|scope=persistent, --profile:string|required=false|hidden=false|no-opt=""|scope=persistent, --timeout:int|required=false|hidden=false|no-opt=""|scope=persistent, --token:string|required=false|hidden=true|no-opt=""|scope=persistent, -v/--verbose:bool|required=false|hidden=false|no-opt="true"|scope=persistent, -y/--yes:bool|required=false|hidden=false|no-opt="true"|scope=persistent [agoal] From 9edc587e96799d5a25b5b860acd75a98c8530ba9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 12:07:06 +0800 Subject: [PATCH 052/250] chore(policy): to #85411130 add idempotency flag migration ledger --- .../approved-flag-migrations-v1.json | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index d52e59e4..a89aaea1 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -928,6 +928,39 @@ "state": "pending", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, + { + "command": "dws chat message send", + "legacy": { + "name": "uuid", + "before": { + "present": true, + "type": "string", + "scope": "local", + "required": false + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "hidden": true, + "alias_of": "idempotency-key" + } + }, + "canonical": { + "name": "idempotency-key", + "before": { + "present": false + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "required": false + } + }, + "state": "pending", + "reason": "保留旧 argv 兼容性，并将幂等参数规范 flag 设为唯一可见入口" + }, { "command": "dws chat message set-pin-msg", "legacy": { From 9c59206d2f230440de55d84d8a23afbb98227577 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=B7=E5=BF=83=E8=8F=9C?= Date: Mon, 10 Aug 2026 20:11:48 +0800 Subject: [PATCH 053/250] feat(drive): add drive list --type/--start/--end client-side filtering --- CHANGELOG.md | 11 + internal/helpers/drive.go | 28 +- internal/helpers/drive_depth.go | 25 +- internal/helpers/drive_depth_test.go | 34 +- internal/helpers/drive_list_filter.go | 229 +++++++++ internal/helpers/drive_list_filter_test.go | 469 ++++++++++++++++++ internal/helpers/pr868_coverage_gaps_test.go | 2 +- skills/mono/references/products/drive.md | 21 + .../multi/dingtalk-drive/references/drive.md | 21 + 9 files changed, 808 insertions(+), 32 deletions(-) create mode 100644 internal/helpers/drive_list_filter.go create mode 100644 internal/helpers/drive_list_filter_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d1d23e1..bfb18edc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,6 +83,14 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th - **Personal OA approval events** — personal event consumers now support task creation, completion, redirection, instance start, termination, and completion events, with typed output and matching usage documentation. +- **Drive list type/time filtering** — `dws drive list` gains `--type + file|folder`, `--start`, and `--end` for client-side filtering by node type + and modification time on both the pan and workspace routes. Filtering runs + a bounded full scan of the target directory (2000-entry cap, reported via + `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is + mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/ + `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339, + zone-less ISO 8601 (Asia/Shanghai), or a plain date. ### Fixed @@ -103,6 +111,9 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th stale OAuth profile. Detached buses negotiate an owner-only, memory-only IPC credential channel; tokens are never placed in child argv, environment, profiles, logs, or run-state files. +- **Drive list pattern filtering** — `dws drive list --pattern` on the + single-layer pan route now filters the returned page by name pattern; the + flag was previously accepted but silently ignored. ### Changed diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index ccceafbf..6fbf6782 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -413,6 +413,13 @@ func newDriveCommand() *cobra.Command { } } + // --type/--start/--end 客户端过滤：激活即切 BFS 全量拉取后筛（两路由统一）； + // 未启用返回零值，存量分支字节级不变。互斥/非法值/start>end 在此拒绝。 + filter, err := parseDriveListFilter(cmd) + if err != nil { + return err + } + // --versions 模式：列出文件历史版本（仅普通文件） // 先于 --depth 校验执行：versions 模式合法使用 --limit， // 不应被「--limit 与 --depth 不兼容」的误导性报错拦截。 @@ -454,7 +461,8 @@ func newDriveCommand() *cobra.Command { if workspaceID != "" { // depth>1 时 --pattern 放开（先递归后过滤）；--order-by/--space-id/--thumbnail // 知识库无对应参数，静默忽略。 - if depth > 1 || latest > 0 { + // filter 激活时 depth==1 也走 BFS 退化态（全量拉取→CLI 侧筛）。 + if depth > 1 || latest > 0 || filter.active() { quiet, _ := cmd.Flags().GetBool("quiet") baseArgs := map[string]any{"workspaceId": workspaceID} rootFolder := docFolderFlag(cmd, "node", "file-id") @@ -463,7 +471,7 @@ func newDriveCommand() *cobra.Command { return err } } - return runDriveListDepth(cmd, newDocDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest) + return runDriveListDepth(cmd, newDocDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest, filter) } if pattern != "" { return &CLIError{ @@ -487,7 +495,9 @@ func newDriveCommand() *cobra.Command { return callMCPToolOnServer("doc", "list_nodes", toolArgs) } - if depth > 1 { + // 钉盘：filter 激活即 depth=1 单层退化态（全量翻完当前目录后 CLI 侧筛）； + // filter+latest 单层同走 BFS（先筛后排，不走 runDriveListLatest 凑够即停）。 + if depth > 1 || filter.active() { quiet, _ := cmd.Flags().GetBool("quiet") baseArgs := map[string]any{} if v, _ := cmd.Flags().GetString("space-id"); v != "" { @@ -508,7 +518,7 @@ func newDriveCommand() *cobra.Command { return err } } - return runDriveListDepth(cmd, newDrivePanDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest) + return runDriveListDepth(cmd, newDrivePanDepthRoute(), baseArgs, rootFolder, depth, pattern, quiet, latest, filter) } // 默认路由：钉盘文件列表 @@ -563,6 +573,11 @@ func newDriveCommand() *cobra.Command { if v, _ := cmd.Flags().GetBool("thumbnail"); v { argsMap["withThumbnail"] = true } + // --pattern 页内过滤（现状缺口附带修复：透传即打印无法夹过滤，取回解析后筛）； + // 不带 pattern 时保持 callMCPTool 纯透传，存量行为不变。 + if pattern != "" { + return callDriveListPageWithPattern(argsMap, pattern) + } return callMCPTool("list_files", argsMap) }, } @@ -591,11 +606,13 @@ func newDriveCommand() *cobra.Command { "用户要浏览「我的文件」/钉盘/网盘某目录下有哪些文件或文件夹时", "已知父文件夹 dentryUuid，要列出其子项以便继续 download/copy/move 时", "传 --workspace 时要列出文档空间/知识库根或子目录（与 wiki node list 场景重叠时，用户说钉盘/我的文件优先本命令）", + "要在已知目录内按类型/修改时间做无关键词筛选时：--type file --start 7d（钉盘与知识库路由均可，CLI 侧过滤）", }, AvoidWhen: []string{ "只记得关键词、不知道所在目录时改用 dws drive search", "明确要在某个知识库内按目录浏览且已有 workspaceId 时可用 dws wiki node list", "要找最近打开/编辑过的文档改用 dws drive recent", + "带关键词的过滤改用 dws drive search（--extensions/--modified-from 等已可用）", }, Examples: []string{ "dws drive list --limit 20 --format json", @@ -1211,6 +1228,9 @@ func newDriveCommand() *cobra.Command { driveListCmd.Flags().Int("depth", 1, "递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥；与 --workspace 组合时走知识库递归 (可选)") driveListCmd.Flags().Int("latest", 0, "按修改时间取最新 N 个文件（1~50）；与 --pattern 组合时表示名称匹配的文件中最新 N 个；可与 --workspace/--depth 组合；与 --order-by/--order/--limit/--cursor 互斥 (可选)") driveListCmd.Flags().Bool("quiet", false, "关闭递归进度输出(stderr)，不影响 stdout JSON (--depth>1 或 --latest 多页扫描时有效) (可选)") + driveListCmd.Flags().String("type", "", "按节点类型过滤: file|folder（客户端过滤：全量扫描后筛，钉盘/知识库均可用；与 --versions/--cursor/--order-by/--order/--limit 互斥）(可选)") + driveListCmd.Flags().String("start", "", "按修改时间过滤·起始: 相对时间如 24h/7d/2w、RFC3339、YYYY-MM-DD（客户端过滤，互斥同 --type）(可选)") + driveListCmd.Flags().String("end", "", "按修改时间过滤·截止: 语法同 --start（客户端过滤，互斥同 --type）(可选)") driveInfoCmd.Flags().String("node", "", "节点 ID (dentryUuid) (必填)") driveInfoCmd.Flags().String("space-id", "", "节点所属空间 ID (可选)") diff --git a/internal/helpers/drive_depth.go b/internal/helpers/drive_depth.go index 4dfe98ee..b70a6c1f 100644 --- a/internal/helpers/drive_depth.go +++ b/internal/helpers/drive_depth.go @@ -178,7 +178,8 @@ func newDocDepthRoute() driveDepthRoute { } // SIGINT 检查两点（出队后发首页前 + 翻页循环发每页前），入队是纯内存操作不检查。 -func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[string]any, rootFolderID string, maxDepth int, pattern string, quiet bool, latest int) error { +// filter 零值 = 未启用；启用时由 emitDriveDepthResult 管线在 pattern 之后、latest 之前筛。 +func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[string]any, rootFolderID string, maxDepth int, pattern string, quiet bool, latest int, filter driveListFilter) error { if deps.Caller.DryRun() { return printDriveDepthDryRun(route, baseArgs, maxDepth) } @@ -209,7 +210,7 @@ func runDriveListDepth(cmd *cobra.Command, route driveDepthRoute, baseArgs map[s bfs: for len(queue) > 0 { if ctx.Err() != nil { - return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth) + return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter) } folder := queue[0] queue = queue[1:] @@ -220,7 +221,7 @@ bfs: pages := 0 for { if ctx.Err() != nil { - return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth) + return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter) } pages++ if pages > maxPagesPerFolder { @@ -233,7 +234,7 @@ bfs: args := route.buildArgs(baseArgs, folder.id, pageToken) text, err := route.fetchPage(ctx, args) if ctx.Err() != nil { - return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth) + return emitDriveDepthCancelled(collected, errs, pattern, latest, maxDepth, route, filter) } if err != nil { folderErr = err @@ -297,7 +298,7 @@ bfs: if driveDepthUnrecoverable(folderErr) { // partial 照吐 stdout，错误详情走 stderr，非零退出 errs = append(errs, newDriveDepthError(folder, folderErr)) - if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth); emitErr != nil { + if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter); emitErr != nil { return emitErr } return folderErr @@ -338,18 +339,18 @@ bfs: } } - return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth) + return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter) } -func emitDriveDepthCancelled(items []map[string]any, errs []driveDepthError, pattern string, latest, reqDepth int) error { - if err := emitDriveDepthResult(items, errs, true, pattern, latest, reqDepth); err != nil { +func emitDriveDepthCancelled(items []map[string]any, errs []driveDepthError, pattern string, latest, reqDepth int, route driveDepthRoute, filter driveListFilter) error { + if err := emitDriveDepthResult(items, errs, true, pattern, latest, reqDepth, route, filter); err != nil { return err } return &driveDepthCancelledError{} } // depth>1 不输出 nextToken。 -func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, truncated bool, pattern string, latest, reqDepth int) error { +func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, truncated bool, pattern string, latest, reqDepth int, route driveDepthRoute, filter driveListFilter) error { if pattern != "" { // 先递归后过滤，过滤仅作用于输出项，不阻止文件夹下钻 filtered := make([]map[string]any, 0, len(items)) @@ -364,6 +365,10 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca } items = filtered } + if filter.active() { + // 类型（route.isFolder 反判）+ 时间（直读收集段注入的 sortTime 毫秒）区间筛 + items = applyDriveListFilter(items, route, filter) + } if latest > 0 { items = applyDriveListLatest(items, latest) } else { @@ -383,7 +388,7 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca maxDepth = d } } - if latest > 0 && reqDepth == 1 { + if (latest > 0 || filter.active()) && reqDepth == 1 { stripDriveDepthDecorations(items) } if items == nil { diff --git a/internal/helpers/drive_depth_test.go b/internal/helpers/drive_depth_test.go index 14b44201..d4af7ebd 100644 --- a/internal/helpers/drive_depth_test.go +++ b/internal/helpers/drive_depth_test.go @@ -306,7 +306,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) { {"name": "a-file.xlsx", "rel_path": "a", "depth": 2, "fileId": "f1"}, {"name": "skip-me.csv", "rel_path": "c", "depth": 1, "fileId": "f3"}, } - if err := emitDriveDepthResult(items, nil, false, "*.xlsx", 0, 0); err != nil { + if err := emitDriveDepthResult(items, nil, false, "*.xlsx", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil { t.Fatal(err) } result := decodeDepthResult(t, out) @@ -325,7 +325,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) { } out.Reset() - if err := emitDriveDepthResult(nil, nil, false, "", 0, 0); err != nil { + if err := emitDriveDepthResult(nil, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil { t.Fatal(err) } result = decodeDepthResult(t, out) @@ -338,7 +338,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) { {"name": "dup", "rel_path": "p/dup", "fileId": "a1"}, } out.Reset() - if err := emitDriveDepthResult(samePath, nil, false, "", 0, 0); err != nil { + if err := emitDriveDepthResult(samePath, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err != nil { t.Fatal(err) } got = decodeDepthResult(t, out)["items"].([]any) @@ -347,7 +347,7 @@ func TestCrossPlatformCoverageEmitDriveDepthResult(t *testing.T) { } deps.Out.w = failingWriter{} - if err := emitDriveDepthResult(nil, nil, false, "", 0, 0); err == nil { + if err := emitDriveDepthResult(nil, nil, false, "", 0, 0, newDrivePanDepthRoute(), driveListFilter{}); err == nil { t.Fatal("failing writer returned nil") } } @@ -382,7 +382,7 @@ func runDepthBFS(t *testing.T, caller *scriptedToolCaller, route driveDepthRoute t.Helper() out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, route, map[string]any{}, root, maxDepth, pattern, true, 0) + err := runDriveListDepth(cmd, route, map[string]any{}, root, maxDepth, pattern, true, 0, driveListFilter{}) return decodeDepthResult(t, out), err } @@ -390,7 +390,7 @@ func TestCrossPlatformCoverageRunDriveListDepthDryRun(t *testing.T) { caller := &scriptedToolCaller{format: "json", dry: true} out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0); err != nil { + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{}); err != nil { t.Fatal(err) } if caller.calls != 0 { @@ -413,7 +413,7 @@ func TestCrossPlatformCoverageRunDriveListDepthPanBFS(t *testing.T) { }} out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", false, 0); err != nil { + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", false, 0, driveListFilter{}); err != nil { t.Fatal(err) } if caller.calls != 2 { @@ -548,7 +548,7 @@ func TestCrossPlatformCoverageRunDriveListDepthRateLimitResumesFromFailedPage(t deps.Out.w = out deps.Out.errW = io.Discard cmd := &cobra.Command{Use: "list"} - if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0); err != nil { + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}); err != nil { t.Fatal(err) } if len(caller.calls) != 3 { @@ -593,7 +593,7 @@ func TestCrossPlatformCoverageRunDriveListDepthRootFailure(t *testing.T) { }} installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil { t.Fatal("root failure returned nil") } @@ -610,7 +610,7 @@ func TestCrossPlatformCoverageRunDriveListDepthUnrecoverable(t *testing.T) { }} out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil { t.Fatal("unrecoverable returned nil") } @@ -635,7 +635,7 @@ func TestCrossPlatformCoverageRunDriveListDepthUnrecoverableEmitFailure(t *testi installDepthCaller(t, caller) deps.Out.w = failingWriter{} cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil || !strings.Contains(err.Error(), "write failed") { t.Fatalf("err = %v, want emit failure", err) } @@ -648,7 +648,7 @@ func TestCrossPlatformCoverageRunDriveListDepthPaginationLoop(t *testing.T) { }} installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil || !strings.Contains(err.Error(), "cursor loop suspected") { t.Fatalf("err = %v, want pagination anomaly", err) } @@ -690,7 +690,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelled(t *testing.T) { cancel() cmd := &cobra.Command{Use: "list"} cmd.SetContext(ctx) - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) var cancelErr *driveDepthCancelledError if !errors.As(err, &cancelErr) { t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err) @@ -710,7 +710,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledEmitFailure(t *testing.T cancel() cmd := &cobra.Command{Use: "list"} cmd.SetContext(ctx) - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil || !strings.Contains(err.Error(), "write failed") { t.Fatalf("err = %v, want emit failure", err) } @@ -724,7 +724,7 @@ func TestCrossPlatformCoverageRunDriveListDepthFinalEmitFailure(t *testing.T) { installDepthCaller(t, caller) deps.Out.w = failingWriter{} cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) if err == nil || !strings.Contains(err.Error(), "write failed") { t.Fatalf("err = %v, want emit failure", err) } @@ -772,7 +772,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledInsidePagination(t *test out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} cmd.SetContext(ctx) - err := runDriveListDepth(cmd, route, map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, route, map[string]any{}, "", 3, "", true, 0, driveListFilter{}) var cancelErr *driveDepthCancelledError if !errors.As(err, &cancelErr) { t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err) @@ -801,7 +801,7 @@ func TestCrossPlatformCoverageRunDriveListDepthCancelledAfterFetch(t *testing.T) deps.Out.errW = io.Discard cmd := &cobra.Command{Use: "list"} cmd.SetContext(ctx) - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 0, driveListFilter{}) var cancelErr *driveDepthCancelledError if !errors.As(err, &cancelErr) { t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err) diff --git a/internal/helpers/drive_list_filter.go b/internal/helpers/drive_list_filter.go new file mode 100644 index 00000000..f86bda84 --- /dev/null +++ b/internal/helpers/drive_list_filter.go @@ -0,0 +1,229 @@ +package helpers + +import ( + "context" + "encoding/json" + "fmt" + "strconv" + "strings" + "time" + + "github.com/spf13/cobra" +) + +// ────────────────────────────────────────────────────────── +// drive list --type/--start/--end 客户端过滤（CLI 侧筛） +// +// 两路由统一（拍板⑤）：钉盘与知识库均为全量拉取后在进程内筛—— +// 复用 depth/latest 的 BFS 基建（钉盘单层 = depth=1 退化态，全量翻完当前目录不下钻）， +// 过滤挂在 emitDriveDepthResult 管线内（pattern 名称筛之后、latest Top-N 之前）。 +// 类型判定复用 route.isFolder 反判；时间比较直读 BFS 收集段注入的 sortTime 毫秒。 +// ────────────────────────────────────────────────────────── + +type driveListFilter struct { + nodeType string // ""=不过滤 / "file" / "folder" + startMs int64 + endMs int64 + hasStart bool + hasEnd bool +} + +func (f driveListFilter) active() bool { + return f.nodeType != "" || f.hasStart || f.hasEnd +} + +// parseDriveListFilter 读取并校验 --type/--start/--end。 +// 三 flag 均未给值时返回零值（active()=false，调用方走存量分支）。 +// 非法值 / start>end / 互斥组合在此拒绝（退出码 3，风格对齐 drive_latest.go 互斥条款）。 +func parseDriveListFilter(cmd *cobra.Command) (driveListFilter, error) { + var filter driveListFilter + nodeType, _ := cmd.Flags().GetString("type") + startRaw, _ := cmd.Flags().GetString("start") + endRaw, _ := cmd.Flags().GetString("end") + nodeType = strings.TrimSpace(nodeType) + startRaw = strings.TrimSpace(startRaw) + endRaw = strings.TrimSpace(endRaw) + if nodeType == "" && startRaw == "" && endRaw == "" { + return filter, nil + } + + if nodeType != "" { + switch strings.ToLower(nodeType) { + case "file", "folder": + filter.nodeType = strings.ToLower(nodeType) + default: + return filter, &CLIError{ + Code: CodeInvalidParam, + Message: fmt.Sprintf("--type 取值非法: %q（合法值: file|folder）", nodeType), + } + } + } + if startRaw != "" { + ms, err := parseDriveListTime(startRaw) + if err != nil { + return filter, &CLIError{Code: CodeInvalidParam, Message: fmt.Sprintf("--start %s", err)} + } + filter.startMs = ms + filter.hasStart = true + } + if endRaw != "" { + ms, err := parseDriveListTime(endRaw) + if err != nil { + return filter, &CLIError{Code: CodeInvalidParam, Message: fmt.Sprintf("--end %s", err)} + } + filter.endMs = ms + filter.hasEnd = true + } + if filter.hasStart && filter.hasEnd && filter.startMs > filter.endMs { + return filter, &CLIError{ + Code: CodeInvalidParam, + Message: fmt.Sprintf("--start %q 晚于 --end %q，请修正时间范围", startRaw, endRaw), + } + } + + // 互斥：filter 为 CLI 侧全量扫描模式，服务端分页/排序语义无法保持。 + if cmd.Flags().Changed("versions") { + return filter, driveListFilterExclusiveError("versions", "--versions 为独立的版本列表模式，请去掉 --versions 或过滤条件") + } + if v := flagOrFallback(cmd, "cursor", "next-token", "page-token"); v != "" { + return filter, driveListFilterExclusiveError("cursor", "过滤模式为从头全量扫描，无连续游标；如需逐页翻页请去掉过滤条件") + } + for _, f := range []string{"order-by", "order"} { + if cmd.Flags().Changed(f) { + return filter, driveListFilterExclusiveError(f, "过滤模式输出由客户端筛选后重排，服务端排序语义无法保持；如需服务端排序请去掉过滤条件") + } + } + if cmd.Flags().Changed("limit") || cmd.Flags().Changed("max") { + return filter, driveListFilterExclusiveError("limit", "过滤模式为全量扫描，数据量由全局上限 2000 与目录范围控制；如需控制单页条数请去掉过滤条件") + } + return filter, nil +} + +func driveListFilterExclusiveError(flag, guidance string) error { + return &CLIError{ + Code: CodeInvalidParam, + Message: fmt.Sprintf("--type/--start/--end 不能与 --%s 同时使用：%s", flag, guidance), + } +} + +// parseDriveListTime 单一时间解析入口：先试相对时间语法，失败回落 ISO8601 +// （agoal.go parseISO8601ToMillis，RFC3339/无时区默认 Asia/Shanghai/仅日期）。 +// 两 flag 共用同一入口；不接受毫秒时间戳（规约红线，与 search 历史遗留切割）。 +func parseDriveListTime(value string) (int64, error) { + if ms, ok := parseDriveRelativeTimeAgo(value); ok { + return ms, nil + } + if ms, err := parseISO8601ToMillis(value); err == nil { + return ms, nil + } + return 0, fmt.Errorf("时间格式不支持: %q（支持: 相对时间如 24h/7d/2w、RFC3339 如 2026-08-01T00:00:00+08:00、无时区 ISO8601 如 2026-08-01 08:00:00（默认 Asia/Shanghai）、仅日期 2026-08-01；不支持毫秒时间戳与 m 单位）", value) +} + +// parseDriveRelativeTimeAgo 相对时间 Nh/Nd/Nw（小时/天/周），按本机时钟换算为绝对毫秒。 +// 不支持 m 单位（lark 双解析器 m=分钟/月语义打架的教训，直接规避）； +// ok=false 表示非相对时间语法，由调用方回落 ISO8601 解析。 +func parseDriveRelativeTimeAgo(value string) (int64, bool) { + s := strings.TrimSpace(value) + if len(s) < 2 { + return 0, false + } + var unit time.Duration + switch s[len(s)-1] { + case 'h': + unit = time.Hour + case 'd': + unit = 24 * time.Hour + case 'w': + unit = 7 * 24 * time.Hour + default: + return 0, false + } + n, err := strconv.Atoi(s[:len(s)-1]) + if err != nil || n <= 0 { + return 0, false + } + return time.Now().Add(-time.Duration(n) * unit).UnixMilli(), true +} + +// applyDriveListFilter 在 emit 管线内做类型/时间筛（pattern 之后、latest Top-N 之前）。 +func applyDriveListFilter(items []map[string]any, route driveDepthRoute, filter driveListFilter) []map[string]any { + filtered := make([]map[string]any, 0, len(items)) + for _, item := range items { + if filter.nodeType != "" { + folder := route.isFolder(item) + if filter.nodeType == "folder" && !folder { + continue + } + if filter.nodeType == "file" && folder { + continue + } + } + if filter.hasStart || filter.hasEnd { + // sortTime 由 BFS 收集段无条件注入（drive_depth.go 时间戳归一）； + // 无时间信息的条目（sortTime<=0）在时间条件下不可判定，保守滤除。 + ts, _ := item["sortTime"].(int64) + if ts <= 0 { + continue + } + if filter.hasStart && ts < filter.startMs { + continue + } + if filter.hasEnd && ts > filter.endMs { + continue + } + } + filtered = append(filtered, item) + } + return filtered +} + +// callDriveListPageWithPattern 单层钉盘 --pattern 页内过滤（现状缺口附带修复： +// 纯透传分支此前未消费 pattern，flag 文案承诺的客户端过滤静默失效）。 +// callMCPTool 透传即打印、无夹过滤的钩子，故取回解析后页内筛再输出； +// 输出保留原 body 形态（nextToken 等分页字段不动），仅条目数组被筛。 +func callDriveListPageWithPattern(argsMap map[string]any, pattern string) error { + if deps.Caller.DryRun() { + return deps.Out.PrintJSON(map[string]any{ + "dry_run": true, + "executed": false, + "tool": "list_files", + "arguments": argsMap, + "pattern": pattern, + "note": "pattern 为客户端过滤，仅作用于本页返回条目", + }) + } + text, err := callMCPToolReturnText(context.Background(), "list_files", argsMap) + if err != nil { + return err + } + var body map[string]any + if json.Unmarshal([]byte(text), &body) != nil { + // 非 JSON 返回无法筛，原样输出（与透传分支的兜底形态一致）。 + deps.Out.PrintRaw(text) + return nil + } + target := body + if inner, ok := body["result"].(map[string]any); ok && driveDepthListItemsKey(inner) != "" { + target = inner + } + if key := driveDepthListItemsKey(target); key != "" { + arr, _ := target[key].([]any) + filtered := make([]any, 0, len(arr)) + for _, entry := range arr { + item, ok := entry.(map[string]any) + if !ok { + filtered = append(filtered, entry) + continue + } + name, _ := item["name"].(string) + if name == "" { + name, _ = item["fileName"].(string) + } + if matchDriveNamePattern(name, pattern) { + filtered = append(filtered, entry) + } + } + target[key] = filtered + } + return deps.Out.PrintJSON(body) +} diff --git a/internal/helpers/drive_list_filter_test.go b/internal/helpers/drive_list_filter_test.go new file mode 100644 index 00000000..e4e0e13d --- /dev/null +++ b/internal/helpers/drive_list_filter_test.go @@ -0,0 +1,469 @@ +package helpers + +import ( + "bytes" + "errors" + "fmt" + "io" + "os" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" +) + +// drive list --type/--start/--end 客户端过滤测试矩阵（设计稿 §9.3）。 +// 命令级用例统一经 executeDriveListCapture 捕获 stdout JSON； +// 零值 filter 的存量分支行为由 drive_depth_test.go / drive_list_modes_test.go 既有用例兜底。 + +// 钉盘路由（serverID 空）经 resolveProductID 扫 os.Args 推断产品，命令级测试需伪装命令行。 +func useDriveListArgs(t *testing.T) { + t.Helper() + old := os.Args + os.Args = []string{"dws", "drive", "list"} + t.Cleanup(func() { os.Args = old }) +} + +func executeDriveListCapture(t *testing.T, caller edition.ToolCaller, args ...string) (*bytes.Buffer, error) { + t.Helper() + previousDeps := deps + t.Cleanup(func() { deps = previousDeps }) + InitDeps(caller) + buf := &bytes.Buffer{} + deps.Out.w = buf + deps.Out.errW = io.Discard + root := newDriveCommand() + root.SilenceErrors = true + root.SilenceUsage = true + root.SetArgs(args) + err := root.Execute() + return buf, err +} + +// 1. 正向：--workspace --type file → list_nodes 全量拉取后仅 file，单层剥装饰字段。 +func TestCrossPlatformCoverageDriveListFilterWorkspaceTypeFile(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"nodes":[ + {"nodeId":"n1","name":"doc1","nodeType":"doc","updateTime":1754000000000}, + {"nodeId":"n2","name":"sub","nodeType":"folder","updateTime":1754000000000} + ],"hasMore":false}`}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--workspace", "ws-1", "--type", "file") + if err != nil { + t.Fatal(err) + } + if caller.calls != 1 { + t.Fatalf("calls = %d, want 1（depth=1 退化态不下钻 folder）", caller.calls) + } + result := decodeDepthResult(t, buf) + items := result["items"].([]any) + if len(items) != 1 { + t.Fatalf("filtered items = %#v", items) + } + item := items[0].(map[string]any) + if item["nodeId"] != "n1" { + t.Fatalf("item = %#v", item) + } + for _, key := range []string{"depth", "parentId", "rel_path", "sortTime"} { + if _, ok := item[key]; ok { + t.Fatalf("decoration %q not stripped: %#v", key, item) + } + } + if result["truncated"] != false || result["maxDepth"] != float64(1) { + t.Fatalf("result = %#v", result) + } +} + +// 2. 正向：--workspace --start 7d --end → sortTime 区间断言。 +func TestCrossPlatformCoverageDriveListFilterWorkspaceTimeRange(t *testing.T) { + now := time.Now() + within := now.Add(-24 * time.Hour).UnixMilli() + before := now.Add(-30 * 24 * time.Hour).UnixMilli() + after := now.Add(24 * time.Hour).UnixMilli() + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: fmt.Sprintf(`{"nodes":[ + {"nodeId":"in","name":"within","nodeType":"doc","updateTime":%d}, + {"nodeId":"old","name":"before","nodeType":"doc","updateTime":%d}, + {"nodeId":"new","name":"after","nodeType":"doc","updateTime":%d} + ],"hasMore":false}`, within, before, after)}, + }} + buf, err := executeDriveListCapture(t, caller, + "list", "--workspace", "ws-1", "--start", "7d", "--end", now.Format(time.RFC3339)) + if err != nil { + t.Fatal(err) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 1 || items[0].(map[string]any)["nodeId"] != "in" { + t.Fatalf("time-range items = %#v", items) + } +} + +// 3. 组合：--workspace --depth 2 --type file → BFS 路径 filter 生效，装饰字段保留。 +func TestCrossPlatformCoverageDriveListFilterWithDepthKeepsDecorations(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"nodes":[ + {"nodeId":"fA","name":"dirA","nodeType":"folder"}, + {"nodeId":"n1","name":"doc1","nodeType":"doc"} + ],"hasMore":false}`}, + {text: `{"nodes":[{"nodeId":"n2","name":"doc2","nodeType":"doc"}],"hasMore":false}`}, + }} + buf, err := executeDriveListCapture(t, caller, + "list", "--workspace", "ws-1", "--depth", "2", "--type", "file") + if err != nil { + t.Fatal(err) + } + if caller.calls != 2 { + t.Fatalf("calls = %d, want 2（depth=2 下钻 dirA）", caller.calls) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 2 { + t.Fatalf("filtered items = %#v（folder 应被滤除）", items) + } + for _, raw := range items { + item := raw.(map[string]any) + if _, ok := item["depth"]; !ok { + t.Fatalf("depth>1 装饰字段应保留: %#v", item) + } + } +} + +// 4. 组合：--workspace --type file --latest 3 → filter 先筛后 Top-N； +// 触顶时 LATEST_SCAN_TRUNCATED 拒绝优先于 filter 的 partial 语义。 +func TestCrossPlatformCoverageDriveListFilterWithLatestTopN(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"nodes":[ + {"nodeId":"d1","name":"dir","nodeType":"folder","updateTime":400}, + {"nodeId":"f1","name":"a","nodeType":"doc","updateTime":100}, + {"nodeId":"f2","name":"b","nodeType":"doc","updateTime":300}, + {"nodeId":"f3","name":"c","nodeType":"doc","updateTime":200}, + {"nodeId":"f4","name":"d","nodeType":"doc","updateTime":50} + ],"hasMore":false}`}, + }} + buf, err := executeDriveListCapture(t, caller, + "list", "--workspace", "ws-1", "--type", "file", "--latest", "2") + if err != nil { + t.Fatal(err) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 2 { + t.Fatalf("top-n items = %#v", items) + } + // folder（updateTime 最大）不得进入 Top-N 排序基；筛选后按 sortTime 倒序。 + if items[0].(map[string]any)["nodeId"] != "f2" || items[1].(map[string]any)["nodeId"] != "f3" { + t.Fatalf("top-n order = %#v", items) + } +} + +func TestCrossPlatformCoverageDriveListFilterLatestTruncatedRejected(t *testing.T) { + useDriveListArgs(t) + var sb strings.Builder + sb.WriteString(`{"items":[`) + for i := 0; i < driveDepthMaxItems; i++ { + if i > 0 { + sb.WriteString(",") + } + fmt.Fprintf(&sb, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifyTime":%d}`, i, i, 1000+i) + } + sb.WriteString(`]}`) + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}} + _, err := executeDriveListCapture(t, caller, "list", "--type", "file", "--latest", "2") + if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_TRUNCATED") { + t.Fatalf("err = %v, want LATEST_SCAN_TRUNCATED", err) + } +} + +// 5. 钉盘路由：--folder + --type file 单层退化态全量翻页后仅 file； +// --start 7d --latest 3 走 BFS(depth=1)；filter 与 cursor/order-by/order/limit/versions 互斥退出码 3。 +func TestCrossPlatformCoverageDriveListFilterPanFolderTypeFile(t *testing.T) { + useDriveListArgs(t) + caller := &depthArgsRecordingCaller{steps: []scriptedToolStep{ + {text: `{"items":[ + {"fileId":"d1","name":"sub","type":"FOLDER"}, + {"fileId":"f1","name":"a.txt","type":"FILE"} + ],"nextToken":"p2"}`}, + {text: `{"items":[{"fileId":"f2","name":"b.txt","type":"FILE"}]}`}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--folder", "root-1", "--type", "file") + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 2 { + t.Fatalf("calls = %d, want 2（翻完当前目录两页，sub 不下钻）", len(caller.calls)) + } + if caller.calls[0]["parentId"] != "root-1" || caller.calls[0]["maxResults"] != float64(driveDepthPageSize) { + t.Fatalf("page args = %#v", caller.calls[0]) + } + if caller.calls[1]["nextToken"] != "p2" { + t.Fatalf("page2 args = %#v", caller.calls[1]) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 2 { + t.Fatalf("filtered items = %#v", items) + } + for _, raw := range items { + item := raw.(map[string]any) + if item["type"] != "FILE" { + t.Fatalf("folder leaked: %#v", item) + } + if _, ok := item["depth"]; ok { + t.Fatalf("single-layer decorations not stripped: %#v", item) + } + } +} + +func TestCrossPlatformCoverageDriveListFilterPanStartWithLatest(t *testing.T) { + useDriveListArgs(t) + now := time.Now() + within := now.Add(-24 * time.Hour).UnixMilli() + stale := now.Add(-30 * 24 * time.Hour).UnixMilli() + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: fmt.Sprintf(`{"items":[ + {"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d}, + {"fileId":"f2","name":"b.txt","type":"FILE","modifyTime":%d}, + {"fileId":"f3","name":"c.txt","type":"FILE","modifyTime":%d} + ]}`, within-1000, within, stale)}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--start", "7d", "--latest", "1") + if err != nil { + t.Fatal(err) + } + result := decodeDepthResult(t, buf) + if _, ok := result["truncated"]; !ok { + t.Fatalf("filter+latest 应走 BFS 聚合形态: %#v", result) + } + items := result["items"].([]any) + // --start 7d 先筛掉 stale，Top-1 取 sortTime 最大的 f2。 + if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f2" { + t.Fatalf("items = %#v", items) + } +} + +func TestCrossPlatformCoverageDriveListFilterExclusiveFlags(t *testing.T) { + cases := [][]string{ + {"list", "--type", "file", "--cursor", "c1"}, + {"list", "--type", "file", "--order-by", "name"}, + {"list", "--start", "7d", "--order", "asc"}, + {"list", "--type", "file", "--limit", "5"}, + {"list", "--end", "2026-08-01", "--max", "5"}, + {"list", "--versions", "--node", "n1", "--type", "file"}, + } + for _, args := range cases { + caller := &scriptedToolCaller{} + _, err := executeDriveListCapture(t, caller, args...) + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation { + t.Fatalf("args %v: err = %v, want CLIError exit 3", args, err) + } + if !strings.Contains(err.Error(), "不能与") || !strings.Contains(err.Error(), "同时使用") { + t.Fatalf("args %v: err = %v, want exclusivity message", args, err) + } + if caller.calls != 0 { + t.Fatalf("args %v: calls = %d, want 0", args, caller.calls) + } + } +} + +// 6. 边界：--type 非法值列合法值；start>end 退出码 3；相对时间解析与 m/毫秒拒绝。 +func TestCrossPlatformCoverageDriveListFilterInvalidValues(t *testing.T) { + caller := &scriptedToolCaller{} + _, err := executeDriveListCapture(t, caller, "list", "--type", "dir") + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation { + t.Fatalf("--type dir err = %v, want exit 3", err) + } + if !strings.Contains(err.Error(), "file|folder") { + t.Fatalf("--type dir err = %v, want valid values listed", err) + } + + _, err = executeDriveListCapture(t, caller, "list", "--start", "2026-08-10", "--end", "2026-08-01") + if !errors.As(err, &cliErr) || cliErr.ExitCode() != ExitValidation { + t.Fatalf("start>end err = %v, want exit 3", err) + } + if !strings.Contains(err.Error(), "晚于") { + t.Fatalf("start>end err = %v", err) + } + if caller.calls != 0 { + t.Fatalf("calls = %d, want 0", caller.calls) + } +} + +func TestCrossPlatformCoverageDriveListFilterTimeParsing(t *testing.T) { + // 相对时间按本机时钟换算为绝对毫秒。 + for _, tc := range []struct { + raw string + unit time.Duration + }{ + {"24h", time.Hour}, + {"7d", 24 * time.Hour}, + {"2w", 7 * 24 * time.Hour}, + } { + before := time.Now() + ms, err := parseDriveListTime(tc.raw) + after := time.Now() + if err != nil { + t.Fatalf("%s: %v", tc.raw, err) + } + expected := time.Duration(mustAtoi(t, tc.raw[:len(tc.raw)-1])) * tc.unit + lo := before.Add(-expected).UnixMilli() + hi := after.Add(-expected).UnixMilli() + if ms < lo || ms > hi { + t.Fatalf("%s: ms = %d, want in [%d, %d]", tc.raw, ms, lo, hi) + } + } + + // RFC3339 / 无时区 ISO8601（默认 Asia/Shanghai）/ 仅日期。 + shanghai := time.FixedZone("CST", 8*3600) + for _, tc := range []struct { + raw string + want int64 + }{ + {"2026-08-01T00:00:00+08:00", time.Date(2026, 8, 1, 0, 0, 0, 0, shanghai).UnixMilli()}, + {"2026-08-01 08:00:00", time.Date(2026, 8, 1, 8, 0, 0, 0, shanghai).UnixMilli()}, + {"2026-08-01", time.Date(2026, 8, 1, 0, 0, 0, 0, shanghai).UnixMilli()}, + } { + ms, err := parseDriveListTime(tc.raw) + if err != nil || ms != tc.want { + t.Fatalf("%s: ms = %d err = %v, want %d", tc.raw, ms, err, tc.want) + } + } + + // m 单位 / 毫秒时间戳 / 零与负值一律拒绝。 + for _, raw := range []string{"7m", "30m", "1754000000000", "0d", "-3d", "abc"} { + if _, err := parseDriveListTime(raw); err == nil { + t.Fatalf("%q accepted, want rejection", raw) + } + } +} + +func mustAtoi(t *testing.T, s string) int { + t.Helper() + n := 0 + if _, err := fmt.Sscanf(s, "%d", &n); err != nil { + t.Fatalf("atoi %q: %v", s, err) + } + return n +} + +// 7. dry-run：--workspace --type file --dry-run → printDriveDepthDryRun 路径，不发起调用。 +func TestCrossPlatformCoverageDriveListFilterDryRun(t *testing.T) { + caller := &scriptedToolCaller{format: "json", dry: true} + buf, err := executeDriveListCapture(t, caller, "list", "--workspace", "ws-1", "--type", "file") + if err != nil { + t.Fatal(err) + } + if caller.calls != 0 { + t.Fatalf("dry-run calls = %d", caller.calls) + } + result := decodeDepthResult(t, buf) + if result["dry_run"] != true || result["tool"] != "list_nodes" || result["maxDepth"] != float64(1) { + t.Fatalf("dry-run payload = %#v", result) + } +} + +// 8. 触顶：2000 条上限 → partial + truncated=true + 退出码 0（filter 触顶结果不全但不会错）。 +func TestCrossPlatformCoverageDriveListFilterTruncatedPartial(t *testing.T) { + useDriveListArgs(t) + var sb strings.Builder + sb.WriteString(`{"items":[`) + for i := 0; i < driveDepthMaxItems; i++ { + if i > 0 { + sb.WriteString(",") + } + fmt.Fprintf(&sb, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifyTime":%d}`, i, i, 1000+i) + } + sb.WriteString(`]}`) + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}} + buf, err := executeDriveListCapture(t, caller, "list", "--type", "file") + if err != nil { + t.Fatalf("filter 触顶应放行（退出码 0）: %v", err) + } + result := decodeDepthResult(t, buf) + if result["truncated"] != true { + t.Fatalf("truncated = %#v", result["truncated"]) + } + if got := len(result["items"].([]any)); got != driveDepthMaxItems { + t.Fatalf("items len = %d, want %d（全 FILE 类型筛全保留）", got, driveDepthMaxItems) + } +} + +// 9. 回归：不带 filter 的存量分支行为不变；--pattern 单层钉盘页内过滤为本次有意修复。 +func TestCrossPlatformCoverageDriveListFilterRegressionUnaffectedPaths(t *testing.T) { + useDriveListArgs(t) + // 单层纯透传（无 filter/pattern）：body 原样输出，args 语义不变。 + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[{"fileId":"f1","name":"a.txt"}],"nextToken":"nt"}`}, + }} + buf, err := executeDriveListCapture(t, caller, "list") + if err != nil { + t.Fatal(err) + } + result := decodeDepthResult(t, buf) + if result["nextToken"] != "nt" || len(result["items"].([]any)) != 1 { + t.Fatalf("透传 body 被改变: %#v", result) + } + if _, ok := result["truncated"]; ok { + t.Fatalf("透传形态不应含 BFS 聚合字段: %#v", result) + } + if caller.args["maxResults"] != float64(20) { + t.Fatalf("args = %#v", caller.args) + } + + // workspace 单层透传：无 filter/depth/latest 时仍走单页 list_nodes。 + caller2 := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"nodes":[{"nodeId":"n1","name":"doc1","nodeType":"doc"}],"hasMore":false}`}, + }} + buf2, err := executeDriveListCapture(t, caller2, "list", "--workspace", "ws-1") + if err != nil { + t.Fatal(err) + } + result2 := decodeDepthResult(t, buf2) + if _, ok := result2["nodes"]; !ok { + t.Fatalf("workspace 单层透传形态被改变: %#v", result2) + } + if caller2.args["pageSize"] != 20 || caller2.args["workspaceId"] != "ws-1" { + t.Fatalf("args = %#v", caller2.args) + } + + // 钉盘单层 --latest（无 filter）：仍走 runDriveListLatest（非 BFS 聚合形态）。 + now := time.Now().UnixMilli() + caller3 := &depthArgsRecordingCaller{steps: []scriptedToolStep{ + {text: fmt.Sprintf(`{"items":[{"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d}],"nextToken":""}`, now)}, + }} + buf3, err := executeDriveListCapture(t, caller3, "list", "--latest", "1") + if err != nil { + t.Fatal(err) + } + result3 := decodeDepthResult(t, buf3) + if _, ok := result3["truncated"]; ok { + t.Fatalf("单层 latest 不应切到 BFS 聚合形态: %#v", result3) + } + if len(result3["items"].([]any)) != 1 { + t.Fatalf("items = %#v", result3["items"]) + } + if caller3.calls[0]["orderBy"] != "modifyTime" || caller3.calls[0]["order"] != "desc" { + t.Fatalf("latest 扫描参数被改变: %#v", caller3.calls[0]) + } +} + +func TestCrossPlatformCoverageDriveListPatternSingleLayerFixed(t *testing.T) { + useDriveListArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[ + {"fileId":"f1","name":"a.txt"}, + {"fileId":"f2","name":"b.md"} + ],"nextToken":"nt"}`}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--pattern", "*.txt") + if err != nil { + t.Fatal(err) + } + result := decodeDepthResult(t, buf) + items := result["items"].([]any) + if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f1" { + t.Fatalf("pattern 页内过滤未生效: %#v", items) + } + if result["nextToken"] != "nt" { + t.Fatalf("分页字段应保留: %#v", result) + } +} diff --git a/internal/helpers/pr868_coverage_gaps_test.go b/internal/helpers/pr868_coverage_gaps_test.go index cc34a257..5b77a200 100644 --- a/internal/helpers/pr868_coverage_gaps_test.go +++ b/internal/helpers/pr868_coverage_gaps_test.go @@ -674,7 +674,7 @@ func TestCrossPlatformCoverageDriveDepthLatestTruncatedAndSortTime(t *testing.T) caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: sb.String()}}} out := installDepthCaller(t, caller) cmd := &cobra.Command{Use: "list"} - err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 2) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 2, driveListFilter{}) if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_TRUNCATED") { t.Fatalf("err=%v, want LATEST_SCAN_TRUNCATED", err) } diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 80e7e3ed..96fceca4 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -34,6 +34,7 @@ Usage: Example: dws drive list --limit 20 dws drive list --limit 20 --folder --order-by name --order asc + dws drive list --folder --type file --start 7d Flags: --limit int 每页返回数量，默认 20，最大 50 (可选) --cursor string 分页游标，首次不传 (可选) @@ -43,10 +44,30 @@ Flags: --space-id string 钉盘空间 ID (纯数字)，不传则使用「我的文件」对应 spaceId (可选) --workspace string 文档空间/知识库 ID (加密 string 或 URL)，传入则路由到文档空间 (可选) --thumbnail 是否返回缩略图信息 (可选，仅钉盘) + --pattern string 按名称通配过滤结果，如 "*日报*"（客户端过滤，无通配符时按子串匹配）(可选) + --depth int 递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥 (可选) + --type string 按节点类型过滤: file|folder（客户端过滤，见下节）(可选) + --start string 按修改时间过滤·起始，如 7d / 2026-08-01 / RFC3339 (可选) + --end string 按修改时间过滤·截止，语法同 --start (可选) ``` > 统一入口：默认列钉盘空间（`--space-id` 纯数字）；传 `--workspace` 时路由到文档空间/知识库列表。 +类型/时间过滤（`--type` / `--start` / `--end`）： +- 语义：`--type` 按节点类型（file=文件 / folder=文件夹）；`--start`/`--end` 按**修改时间**圈定区间。 + 注意与 `dws drive search` 的 `--modified-from/--modified-to` 区分：那两个收毫秒时间戳，这里收字符串语法； + `--type`（节点类型）与 search 的 `--file-types`（内容类型 alidoc/image/...）也不是一回事。 +- 时间语法：相对时间 `24h`/`7d`/`2w`（小时/天/周，按本机时钟换算）、RFC3339（`2026-08-01T00:00:00+08:00`）、 + 无时区 ISO8601（`2026-08-01 08:00:00`，默认 Asia/Shanghai）、仅日期（`2026-08-01`）； + 不支持毫秒时间戳，不支持 `m` 单位。 +- 执行方式：钉盘与知识库（--workspace）两路由统一为**客户端过滤**——全量扫描当前目录后在进程内筛选； + 与 `--depth>1` 组合时递归扫描后筛（被滤掉的条目仍占 2000 条全局上限）。 +- 互斥：与 `--versions`/`--cursor`/`--order-by`/`--order`/`--limit` 不能同时使用（过滤模式为全量扫描， + 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`+--latest` 表示「符合条件的条目中最新 N 个」。 +- 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 +- 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； + 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 + ### 获取钉盘空间列表 > **Deprecated**：推荐改用 `dws wiki space list --type orgSpace` / `--type mySpace`（见 [wiki.md](./wiki.md)）。本命令仍可用，仅作兼容保留。 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 29680fa2..21a7534d 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -30,6 +30,7 @@ Usage: Example: dws drive list --limit 20 dws drive list --limit 20 --folder --order-by name --order asc + dws drive list --folder --type file --start 7d Flags: --limit int 每页返回数量，默认 20，最大 50 (可选) --cursor string 分页游标，首次不传 (可选) @@ -38,8 +39,28 @@ Flags: --folder string 父节点 ID (dentryUuid)，不传则列出空间根目录 (可选) --space-id string 空间 ID，不传则使用「我的文件」对应 spaceId (可选) --thumbnail 是否返回缩略图信息 (可选) + --pattern string 按名称通配过滤结果，如 "*日报*"（客户端过滤，无通配符时按子串匹配）(可选) + --depth int 递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥 (可选) + --type string 按节点类型过滤: file|folder（客户端过滤，见下节）(可选) + --start string 按修改时间过滤·起始，如 7d / 2026-08-01 / RFC3339 (可选) + --end string 按修改时间过滤·截止，语法同 --start (可选) ``` +类型/时间过滤（`--type` / `--start` / `--end`）： +- 语义：`--type` 按节点类型（file=文件 / folder=文件夹）；`--start`/`--end` 按**修改时间**圈定区间。 + 注意与 `dws drive search` 的 `--modified-from/--modified-to` 区分：那两个收毫秒时间戳，这里收字符串语法； + `--type`（节点类型）与 search 的 `--file-types`（内容类型 alidoc/image/...）也不是一回事。 +- 时间语法：相对时间 `24h`/`7d`/`2w`（小时/天/周，按本机时钟换算）、RFC3339（`2026-08-01T00:00:00+08:00`）、 + 无时区 ISO8601（`2026-08-01 08:00:00`，默认 Asia/Shanghai）、仅日期（`2026-08-01`）； + 不支持毫秒时间戳，不支持 `m` 单位。 +- 执行方式：钉盘与知识库（--workspace）两路由统一为**客户端过滤**——全量扫描当前目录后在进程内筛选； + 与 `--depth>1` 组合时递归扫描后筛（被滤掉的条目仍占 2000 条全局上限）。 +- 互斥：与 `--versions`/`--cursor`/`--order-by`/`--order`/`--limit` 不能同时使用（过滤模式为全量扫描， + 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`+--latest` 表示「符合条件的条目中最新 N 个」。 +- 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 +- 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； + 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 + ### 获取钉盘空间列表 ``` From 647bdb251c5240cc5b821997751c90a262048f96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=B7=E5=BF=83=E8=8F=9C?= Date: Tue, 11 Aug 2026 11:31:25 +0800 Subject: [PATCH 054/250] test(drive): cover drive list filter/pattern edge branches --- internal/helpers/drive_list_filter_test.go | 95 ++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/internal/helpers/drive_list_filter_test.go b/internal/helpers/drive_list_filter_test.go index e4e0e13d..6e56912d 100644 --- a/internal/helpers/drive_list_filter_test.go +++ b/internal/helpers/drive_list_filter_test.go @@ -467,3 +467,98 @@ func TestCrossPlatformCoverageDriveListPatternSingleLayerFixed(t *testing.T) { t.Fatalf("分页字段应保留: %#v", result) } } + +// 10. 钉盘路由：--type folder 反向筛（FILE 被滤除，仅 FOLDER 保留）。 +func TestCrossPlatformCoverageDriveListFilterPanFolderTypeFolder(t *testing.T) { + useDriveListArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[ + {"fileId":"d1","name":"sub","type":"FOLDER"}, + {"fileId":"f1","name":"a.txt","type":"FILE"} + ]}`}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--folder", "root-1", "--type", "folder") + if err != nil { + t.Fatal(err) + } + if caller.calls != 1 { + t.Fatalf("calls = %d, want 1（depth=1 退化态不下钻 folder）", caller.calls) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 1 || items[0].(map[string]any)["fileId"] != "d1" { + t.Fatalf("folder filter items = %#v", items) + } +} + +// 11. 钉盘路由：--start 下无时间信息的条目（sortTime<=0）不可判定，保守滤除。 +func TestCrossPlatformCoverageDriveListFilterPanMissingTimeDropped(t *testing.T) { + useDriveListArgs(t) + now := time.Now().UnixMilli() + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: fmt.Sprintf(`{"items":[ + {"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d}, + {"fileId":"f2","name":"no-time.txt","type":"FILE"} + ]}`, now)}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--start", "7d") + if err != nil { + t.Fatal(err) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 1 || items[0].(map[string]any)["fileId"] != "f1" { + t.Fatalf("missing-time 条目应被滤除: %#v", items) + } +} + +// 12. 单层钉盘 --pattern 页内过滤边界：dry-run 预览 / MCP 错误透传 / 非 JSON 原样输出 / +// 非 map 条目保留 + name 缺失时 fileName 兜底匹配。 +func TestCrossPlatformCoverageDriveListPatternPassthroughEdges(t *testing.T) { + useDriveListArgs(t) + + // dry-run：打印预览，不发起调用。 + dryCaller := &scriptedToolCaller{dry: true} + buf, err := executeDriveListCapture(t, dryCaller, "list", "--pattern", "*.txt") + if err != nil { + t.Fatal(err) + } + if dryCaller.calls != 0 { + t.Fatalf("dry-run calls = %d", dryCaller.calls) + } + preview := decodeDepthResult(t, buf) + if preview["dry_run"] != true || preview["tool"] != "list_files" || preview["pattern"] != "*.txt" { + t.Fatalf("dry-run payload = %#v", preview) + } + + // MCP 错误：原样返回。 + errCaller := &scriptedToolCaller{steps: []scriptedToolStep{{err: errors.New("boom")}}} + if _, err := executeDriveListCapture(t, errCaller, "list", "--pattern", "*.txt"); err == nil || !strings.Contains(err.Error(), "boom") { + t.Fatalf("err = %v, want boom", err) + } + + // 非 JSON 返回：无法筛，原样输出（与透传分支兜底形态一致）。 + rawCaller := &scriptedToolCaller{steps: []scriptedToolStep{{text: "plain-text-result"}}} + rawBuf, err := executeDriveListCapture(t, rawCaller, "list", "--pattern", "*.txt") + if err != nil { + t.Fatal(err) + } + if !strings.Contains(rawBuf.String(), "plain-text-result") { + t.Fatalf("raw output = %q", rawBuf.String()) + } + + // 非 map 条目原样保留；name 缺失时 fileName 兜底参与匹配。 + mixedCaller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[ + "raw-entry", + {"fileId":"f1","fileName":"日报模板.doc"}, + {"fileId":"f2","name":"其他.txt"} + ],"nextToken":"nt"}`}, + }} + mixedBuf, err := executeDriveListCapture(t, mixedCaller, "list", "--pattern", "*模板*") + if err != nil { + t.Fatal(err) + } + mixed := decodeDepthResult(t, mixedBuf)["items"].([]any) + if len(mixed) != 2 || mixed[0] != "raw-entry" || mixed[1].(map[string]any)["fileId"] != "f1" { + t.Fatalf("items = %#v", mixed) + } +} From 273a3ab5ddda0a5bc080605a09f9598146b0882d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=B7=E5=BF=83=E8=8F=9C?= Date: Thu, 13 Aug 2026 11:30:38 +0800 Subject: [PATCH 055/250] chore: migrate drive list changelog entries to release fragments --- .changes/942-drive-list-filter.md | 12 ++++++++++++ .changes/942-drive-list-pattern-fix.md | 7 +++++++ CHANGELOG.md | 11 ----------- 3 files changed, 19 insertions(+), 11 deletions(-) create mode 100644 .changes/942-drive-list-filter.md create mode 100644 .changes/942-drive-list-pattern-fix.md diff --git a/.changes/942-drive-list-filter.md b/.changes/942-drive-list-filter.md new file mode 100644 index 00000000..06deb44e --- /dev/null +++ b/.changes/942-drive-list-filter.md @@ -0,0 +1,12 @@ +--- +category: Added +--- + +- **Drive list type/time filtering** (#942) — `dws drive list` gains `--type + file|folder`, `--start`, and `--end` for client-side filtering by node type + and modification time on both the pan and workspace routes. Filtering runs + a bounded full scan of the target directory (2000-entry cap, reported via + `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is + mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/ + `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339, + zone-less ISO 8601 (Asia/Shanghai), or a plain date. diff --git a/.changes/942-drive-list-pattern-fix.md b/.changes/942-drive-list-pattern-fix.md new file mode 100644 index 00000000..5115bd45 --- /dev/null +++ b/.changes/942-drive-list-pattern-fix.md @@ -0,0 +1,7 @@ +--- +category: Fixed +--- + +- **Drive list pattern filtering** (#942) — `dws drive list --pattern` on the + single-layer pan route now filters the returned page by name pattern; the + flag was previously accepted but silently ignored. diff --git a/CHANGELOG.md b/CHANGELOG.md index bfb18edc..7d1d23e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,14 +83,6 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th - **Personal OA approval events** — personal event consumers now support task creation, completion, redirection, instance start, termination, and completion events, with typed output and matching usage documentation. -- **Drive list type/time filtering** — `dws drive list` gains `--type - file|folder`, `--start`, and `--end` for client-side filtering by node type - and modification time on both the pan and workspace routes. Filtering runs - a bounded full scan of the target directory (2000-entry cap, reported via - `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is - mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/ - `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339, - zone-less ISO 8601 (Asia/Shanghai), or a plain date. ### Fixed @@ -111,9 +103,6 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th stale OAuth profile. Detached buses negotiate an owner-only, memory-only IPC credential channel; tokens are never placed in child argv, environment, profiles, logs, or run-state files. -- **Drive list pattern filtering** — `dws drive list --pattern` on the - single-layer pan route now filters the returned page by name pattern; the - flag was previously accepted but silently ignored. ### Changed From 45a80185f629864cb6a029ea7642f416a45f1b97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 14:42:26 +0800 Subject: [PATCH 056/250] fix(chat): pass explicit list-all times through --- .changes/973-chat-message-time-defaults.md | 2 +- internal/helpers/chat.go | 16 +---- .../helpers/chat_message_pagination_test.go | 59 ++++++++++--------- 3 files changed, 36 insertions(+), 41 deletions(-) diff --git a/.changes/973-chat-message-time-defaults.md b/.changes/973-chat-message-time-defaults.md index 1a6e5496..fbe6ba2c 100644 --- a/.changes/973-chat-message-time-defaults.md +++ b/.changes/973-chat-message-time-defaults.md @@ -2,4 +2,4 @@ category: Fixed --- -- **Chat message time defaults** (#973) — validates `chat message list-all` time ranges locally and defaults omitted message-query time bounds without creating reversed windows. +- **Chat message time defaults** (#973) — defaults omitted message-query time bounds without creating reversed windows. diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 34a45d0f..c1c7e672 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -471,20 +471,10 @@ func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { if err != nil { return nil, err } - startMs, err := parseISOTimeToMillis("start", startRaw) - if err != nil { - return nil, err - } - endMs, _ := parseISOTimeToMillis("end", endRaw) - if err := validateTimeRange(startMs, endMs); err != nil { - return nil, err - } - startTime := formatChatMessageListAllTime(startMs) - endTime := formatChatMessageListAllTime(endMs) cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ - "startTime": startTime, - "endTime": endTime, + "startTime": startRaw, + "endTime": endRaw, "limit": chatIntFlagOrFallback(cmd, "limit", "size"), "cursor": cursor, }, nil @@ -608,7 +598,7 @@ func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (st anchor := time.Now() if endRaw == "" { endRaw = anchor.Format(time.RFC3339) - } else { + } else if startRaw == "" { endMs, err := parseISOTimeToMillis("end", endRaw) if err != nil { return "", "", err diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index 61ad4c2f..f373e130 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -83,12 +83,7 @@ func TestChatMessagePaginationDefaultSinglePageUnchanged(t *testing.T) { args: []string{"message", "list-all", "--start", "2026-08-01 00:00:00", "--end", "2026-08-02 00:00:00"}, server: "", tool: "search_messages_by_time_range", - want: map[string]any{ - "startTime": formatChatMessageListAllTime(1785513600000), - "endTime": formatChatMessageListAllTime(1785600000000), - "limit": 50, - "cursor": "0", - }, + want: map[string]any{"startTime": "2026-08-01 00:00:00", "endTime": "2026-08-02 00:00:00", "limit": 50, "cursor": "0"}, }, { name: "list-by-sender", @@ -281,8 +276,8 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { t.Fatalf("startTime = %d, want %d", startMs, wantStartMs) } if tt.wantTool == "search_messages_by_time_range" { - assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(wantStartMs)) - assertStringArg(t, got.args["endTime"], formatChatMessageListAllTime(endMs)) + assertStringArg(t, got.args["startTime"], time.UnixMilli(wantStartMs).Format(time.RFC3339)) + assertStringArg(t, got.args["endTime"], endRaw) } }) } @@ -348,28 +343,31 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing t.Fatalf("endTime = %d, want between %d and %d", endMs, wantEndMin, wantEndMax) } if tt.wantTool == "search_messages_by_time_range" { - assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(startMs)) + assertStringArg(t, got.args["startTime"], startRaw) parseChatMessageListAllTimeArg(t, got.args["endTime"]) } }) } } -func TestChatMessageListAllRejectsInvalidTimeRanges(t *testing.T) { +func TestChatMessageListAllPassesExplicitTimeBoundsThrough(t *testing.T) { tests := []struct { - name string - args []string - wantErr string + name string + args []string + wantStart string + wantEnd string }{ { - name: "invalid start", - args: []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"}, - wantErr: "cannot parse time for --start", + name: "invalid start", + args: []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"}, + wantStart: "not-a-time", + wantEnd: "2020-01-01T00:00:00+08:00", }, { - name: "end before start", - args: []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"}, - wantErr: "--end must be after --start", + name: "end before start", + args: []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"}, + wantStart: "2021-01-01T00:00:00+08:00", + wantEnd: "2020-01-01T00:00:00+08:00", }, } @@ -377,15 +375,18 @@ func TestChatMessageListAllRejectsInvalidTimeRanges(t *testing.T) { t.Run(tt.name, func(t *testing.T) { caller := &chatMessagePaginationCaller{} _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) - if err == nil { - t.Fatal("command succeeded, want validation error") + if err != nil { + t.Fatal(err) } - if !strings.Contains(err.Error(), tt.wantErr) { - t.Fatalf("error = %v, want containing %q", err, tt.wantErr) + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one MCP call", caller.calls) } - if len(caller.calls) != 0 { - t.Fatalf("calls = %#v, want no MCP call", caller.calls) + got := caller.calls[0] + if got.tool != "search_messages_by_time_range" { + t.Fatalf("tool = %q, want search_messages_by_time_range", got.tool) } + assertStringArg(t, got.args["startTime"], tt.wantStart) + assertStringArg(t, got.args["endTime"], tt.wantEnd) }) } } @@ -423,10 +424,14 @@ func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time { t.Helper() raw, ok := value.(string) if !ok { - t.Fatalf("time arg = %#v, want yyyy-MM-dd HH:mm:ss string", value) + t.Fatalf("time arg = %#v, want time string", value) } if strings.Contains(raw, "T") { - t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw) + parsedMs, err := parseISOTimeToMillis("time", raw) + if err != nil { + t.Fatalf("time arg = %q, parse err = %v", raw, err) + } + return time.UnixMilli(parsedMs) } parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local) if err != nil { From 14818775c52786169f28153eb12327531c89fd58 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Wed, 22 Jul 2026 15:41:44 +0800 Subject: [PATCH 057/250] DWS support global --- internal/app/auth_command.go | 19 +++++++ internal/app/auth_command_test.go | 31 ++++++++++++ internal/auth/auth_extra_test.go | 22 ++++++++ internal/auth/device_flow.go | 26 +++++++++- internal/auth/device_flow_test.go | 11 ++++ internal/auth/endpoints.go | 59 ++++++++++++++++++++-- internal/auth/oauth_helpers.go | 83 ++++++++++++++++++++++++++----- internal/auth/oauth_provider.go | 30 +++++++++-- internal/auth/token.go | 1 + 9 files changed, 259 insertions(+), 23 deletions(-) diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index e887341b..3357acf3 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -48,6 +48,7 @@ type authLoginConfig struct { TargetCorpID string HistoryProfileSelector string HistoryProfileSelectorExplicit bool + International bool } type authLoginGuideAction string @@ -116,6 +117,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { 示例: dws auth login # 本机登录并新增/刷新一个组织 profile dws auth login --profile # 指定本次授权目标组织，不持久切换当前组织 + dws auth login --intl # 使用钉钉国际登录入口 dws auth login --recommend # 无交互批量授权服务端推荐权限 dws auth login --device # SSH 远程 / 无头环境登录 (设备流) dws auth login --force # 兼容保留；login 默认已忽略缓存并进入授权流程 @@ -149,6 +151,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { provider := authpkg.NewDeviceFlowProvider(configDir, nil) provider.Output = cmd.ErrOrStderr() provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser") + if cfg.International { + provider.SetLoginRegion(authpkg.LoginRegionInternational) + } provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error { return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data, authLoginHistoryHint{ Selector: cfg.HistoryProfileSelector, @@ -167,6 +172,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { provider.Output = cmd.ErrOrStderr() provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser") provider.TargetCorpID = cfg.TargetCorpID + if cfg.International { + provider.LoginRegion = authpkg.LoginRegionInternational + } provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error { return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data, authLoginHistoryHint{ Selector: cfg.HistoryProfileSelector, @@ -278,6 +286,8 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { } cmd.Flags().String("token", "", "Access token") cmd.Flags().Bool("device", false, "Use device authorization flow") + cmd.Flags().Bool("intl", false, "Use DingTalk international login") + cmd.Flags().Bool("international", false, "Use DingTalk international login") cmd.Flags().Bool("force", false, "兼容保留；login 默认已忽略缓存并进入授权流程") cmd.Flags().Bool("recommend", false, "登录成功后无交互批量授权服务端推荐权限") // Hidden compatibility flags @@ -1225,6 +1235,14 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) { if err != nil { return authLoginConfig{}, apperrors.NewInternal("failed to read --device") } + intl, err := cmd.Flags().GetBool("intl") + if err != nil { + return authLoginConfig{}, apperrors.NewInternal("failed to read --intl") + } + international, err := cmd.Flags().GetBool("international") + if err != nil { + return authLoginConfig{}, apperrors.NewInternal("failed to read --international") + } force, err := cmd.Flags().GetBool("force") if err != nil { return authLoginConfig{}, apperrors.NewInternal("failed to read --force") @@ -1266,6 +1284,7 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) { TargetCorpID: targetCorpID, HistoryProfileSelector: historyProfileSelector, HistoryProfileSelectorExplicit: historyProfileSelectorExplicit, + International: intl || international, }, nil } diff --git a/internal/app/auth_command_test.go b/internal/app/auth_command_test.go index 486cd98a..7d4f1e86 100644 --- a/internal/app/auth_command_test.go +++ b/internal/app/auth_command_test.go @@ -1033,6 +1033,8 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) { login := &cobra.Command{Use: "login"} login.Flags().String("token", "", "") login.Flags().Bool("device", false, "") + login.Flags().Bool("intl", false, "") + login.Flags().Bool("international", false, "") login.Flags().Bool("force", false, "") login.Flags().Bool("recommend", false, "") root.AddCommand(login) @@ -1061,6 +1063,35 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) { } } +func TestResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { + for _, flag := range []string{"intl", "international"} { + t.Run(flag, func(t *testing.T) { + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().Bool("yes", false, "") + login := &cobra.Command{Use: "login"} + login.Flags().String("token", "", "") + login.Flags().Bool("device", false, "") + login.Flags().Bool("intl", false, "") + login.Flags().Bool("international", false, "") + login.Flags().Bool("force", false, "") + login.Flags().Bool("recommend", false, "") + root.AddCommand(login) + + if err := login.Flags().Set(flag, "true"); err != nil { + t.Fatalf("set %s: %v", flag, err) + } + + cfg, err := resolveAuthLoginConfig(login) + if err != nil { + t.Fatalf("resolveAuthLoginConfig error = %v", err) + } + if !cfg.International { + t.Fatalf("International = false for --%s, want true", flag) + } + }) + } +} + func TestAuthLoginForcesAuthorizationByDefault(t *testing.T) { if !authLoginForcesAuthorization(authLoginConfig{}) { t.Fatal("auth login should force authorization by default so each login can add an organization profile") diff --git a/internal/auth/auth_extra_test.go b/internal/auth/auth_extra_test.go index d64d9ee8..07202e7a 100644 --- a/internal/auth/auth_extra_test.go +++ b/internal/auth/auth_extra_test.go @@ -424,6 +424,28 @@ func TestBuildAuthURLIncludesTargetCorpID(t *testing.T) { } } +func TestBuildAuthURLForInternationalRegion(t *testing.T) { + authURL := buildAuthURLForRegion("client-id", "http://127.0.0.1:1234/callback", "", LoginRegionInternational) + if !strings.HasPrefix(authURL, InternationalAuthorizeURL+"?") { + t.Fatalf("auth URL = %s, want international authorize host", authURL) + } +} + +func TestLoginRegionEndpointDefaults(t *testing.T) { + if got := AuthorizeURLForLoginRegion(LoginRegionDefault); got != AuthorizeURL { + t.Fatalf("default authorize URL = %q, want %q", got, AuthorizeURL) + } + if got := UserAccessTokenURLForLoginRegion(LoginRegionInternational); got != InternationalUserAccessTokenURL { + t.Fatalf("international user access token URL = %q, want %q", got, InternationalUserAccessTokenURL) + } + if got := MCPBaseURLForLoginRegion(LoginRegionInternational); got != InternationalMCPBaseURL { + t.Fatalf("international MCP base URL = %q, want %q", got, InternationalMCPBaseURL) + } + if got := DeviceBaseURLForLoginRegion(LoginRegionInternational); got != InternationalDeviceBaseURL { + t.Fatalf("international device base URL = %q, want %q", got, InternationalDeviceBaseURL) + } +} + func buildTokenDataFromResponse(resp tokenResponse) *TokenData { if resp.AccessToken == "" { return nil diff --git a/internal/auth/device_flow.go b/internal/auth/device_flow.go index c711949a..a990072d 100644 --- a/internal/auth/device_flow.go +++ b/internal/auth/device_flow.go @@ -74,6 +74,20 @@ var ( } ) +func deviceFetchClientIDForLoginRegion(ctx context.Context, region LoginRegion) (string, error) { + if region.IsInternational() { + return FetchClientIDFromMCPForLoginRegion(ctx, region) + } + return deviceFetchClientID(ctx) +} + +func deviceGetAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) { + if region.IsInternational() { + return GetSuperAdminsForLoginRegion(ctx, accessToken, region) + } + return deviceGetAdmins(ctx, accessToken) +} + type DeviceFlowProvider struct { configDir string clientID string @@ -85,6 +99,7 @@ type DeviceFlowProvider struct { httpClient *http.Client NoBrowser bool IdentityEnricher func(context.Context, *TokenData) error + LoginRegion LoginRegion } func NewDeviceFlowProvider(configDir string, logger *slog.Logger) *DeviceFlowProvider { @@ -104,6 +119,12 @@ func (p *DeviceFlowProvider) SetBaseURL(baseURL string) { p.baseURL = strings.TrimRight(baseURL, "/") } +func (p *DeviceFlowProvider) SetLoginRegion(region LoginRegion) { + p.LoginRegion = region + p.baseURL = DeviceBaseURLForLoginRegion(region) + p.terminalBaseURL = MCPBaseURLForLoginRegion(region) +} + // SetTerminalBaseURL sets the terminal API base URL for device flow polling. func (p *DeviceFlowProvider) SetTerminalBaseURL(baseURL string) { p.terminalBaseURL = strings.TrimRight(baseURL, "/") @@ -213,7 +234,7 @@ func (p *DeviceFlowProvider) Login(ctx context.Context) (*TokenData, error) { if p.logger != nil { p.logger.Debug("fetching client ID from MCP server (device flow always re-fetches)") } - mcpClientID, mcpErr := deviceFetchClientID(ctx) + mcpClientID, mcpErr := deviceFetchClientIDForLoginRegion(ctx, p.LoginRegion) if mcpErr != nil { return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr) } @@ -272,6 +293,7 @@ func (p *DeviceFlowProvider) loginOnce(ctx context.Context, attempt int) (*Token clientID: p.clientID, logger: p.logger, IdentityEnricher: p.IdentityEnricher, + LoginRegion: p.LoginRegion, } tokenData, err := deviceExchangeCode(oauthProvider, ctx, tokenResult.AuthCode) if err != nil { @@ -331,7 +353,7 @@ func (p *DeviceFlowProvider) loginOnce(ctx context.Context, attempt int) (*Token _, _ = fmt.Fprintln(p.output(), i18n.T(" 你所选择的组织管理员尚未开启「允许成员通过 CLI 访问其个人数据」的权限。")) _, _ = fmt.Fprintln(p.output(), "") - admins, adminErr := deviceGetAdmins(ctx, tokenData.AccessToken) + admins, adminErr := deviceGetAdminsForLoginRegion(ctx, tokenData.AccessToken, p.LoginRegion) if adminErr == nil && admins.Success && len(admins.Result) > 0 { maxAdmins := 3 if len(admins.Result) < maxAdmins { diff --git a/internal/auth/device_flow_test.go b/internal/auth/device_flow_test.go index 0abc4730..72d64c31 100644 --- a/internal/auth/device_flow_test.go +++ b/internal/auth/device_flow_test.go @@ -90,6 +90,17 @@ func TestRequestDeviceCodeSuccess(t *testing.T) { } } +func TestDeviceFlowSetLoginRegionUsesInternationalBaseURL(t *testing.T) { + provider := NewDeviceFlowProvider(t.TempDir(), newDeviceFlowTestLogger()) + provider.SetLoginRegion(LoginRegionInternational) + if provider.baseURL != InternationalDeviceBaseURL { + t.Fatalf("baseURL = %q, want %q", provider.baseURL, InternationalDeviceBaseURL) + } + if provider.terminalBaseURL != InternationalMCPBaseURL { + t.Fatalf("terminalBaseURL = %q, want %q", provider.terminalBaseURL, InternationalMCPBaseURL) + } +} + func TestWaitForAuthorizationSucceedsAfterPending(t *testing.T) { t.Parallel() diff --git a/internal/auth/endpoints.go b/internal/auth/endpoints.go index 098297f2..5181f075 100644 --- a/internal/auth/endpoints.go +++ b/internal/auth/endpoints.go @@ -50,9 +50,15 @@ const ( // AuthorizeURL is the DingTalk OAuth authorization page. AuthorizeURL = "https://login.dingtalk.com/oauth2/auth" + // InternationalAuthorizeURL is the DingTalk international OAuth authorization page. + InternationalAuthorizeURL = "https://login.dingtalk.io/oauth2/auth" + // UserAccessTokenURL exchanges an authorization code for user tokens. UserAccessTokenURL = "https://api.dingtalk.com/v1.0/oauth2/userAccessToken" + // InternationalUserAccessTokenURL exchanges authorization codes for international user tokens. + InternationalUserAccessTokenURL = "https://api.dingtalk.io/v1.0/oauth2/userAccessToken" + // UserInfoURL fetches the authenticated user's profile. UserInfoURL = "https://api.dingtalk.com/v1.0/contact/users/me" @@ -75,6 +81,9 @@ const ( // DefaultDeviceBaseURL is the login server base URL for device flow. DefaultDeviceBaseURL = "https://login.dingtalk.com" + // InternationalDeviceBaseURL is the international login server base URL for device flow. + InternationalDeviceBaseURL = "https://login.dingtalk.io" + // DeviceCodePath requests a device_code and user_code. DeviceCodePath = "/oauth2/device/code.json" @@ -96,11 +105,12 @@ const ( LogoutContinueURL = "https://login.dingtalk.com" // MCP API endpoints for CLI authorization management. - DefaultMCPBaseURL = config.DefaultMCPBaseURL - CLIAuthEnabledPath = "/cli/cliAuthEnabled" - SuperAdminPath = "/cli/superAdmin" - SendCliAuthApplyPath = "/cli/sendCliAuthApply" - ClientIDPath = "/cli/clientId" + DefaultMCPBaseURL = config.DefaultMCPBaseURL + InternationalMCPBaseURL = "https://mcp.dingtalk.io" + CLIAuthEnabledPath = "/cli/cliAuthEnabled" + SuperAdminPath = "/cli/superAdmin" + SendCliAuthApplyPath = "/cli/sendCliAuthApply" + ClientIDPath = "/cli/clientId" // MCP OAuth endpoints (used when clientId is fetched from MCP). MCPOAuthTokenPath = "/oauth2/getToken" @@ -114,6 +124,45 @@ const ( AppAccessTokenURL = "https://api.dingtalk.com/v1.0/oauth2/accessToken" ) +type LoginRegion string + +const ( + LoginRegionDefault LoginRegion = "" + LoginRegionInternational LoginRegion = "international" +) + +func (r LoginRegion) IsInternational() bool { + return r == LoginRegionInternational +} + +func AuthorizeURLForLoginRegion(region LoginRegion) string { + if region.IsInternational() { + return InternationalAuthorizeURL + } + return AuthorizeURL +} + +func DeviceBaseURLForLoginRegion(region LoginRegion) string { + if region.IsInternational() { + return InternationalDeviceBaseURL + } + return DefaultDeviceBaseURL +} + +func MCPBaseURLForLoginRegion(region LoginRegion) string { + if region.IsInternational() { + return InternationalMCPBaseURL + } + return GetMCPBaseURL() +} + +func UserAccessTokenURLForLoginRegion(region LoginRegion) string { + if region.IsInternational() { + return InternationalUserAccessTokenURL + } + return UserAccessTokenURL +} + // GetTerminalBaseURL returns the terminal base URL with priority: // 1. ~/.dws/terminal_url file content (for pre-release environment) // 2. Default value (https://open-dev.dingtalk.com) diff --git a/internal/auth/oauth_helpers.go b/internal/auth/oauth_helpers.go index cc30a4a3..0dbdd783 100644 --- a/internal/auth/oauth_helpers.go +++ b/internal/auth/oauth_helpers.go @@ -51,7 +51,7 @@ func (p *OAuthProvider) exchangeCode(ctx context.Context, code string) (*TokenDa "code": code, "grantType": "authorization_code", } - resp, err := p.postJSON(ctx, UserAccessTokenURL, body) + resp, err := p.postJSON(ctx, UserAccessTokenURLForLoginRegion(p.loginRegion()), body) if err != nil { return nil, err } @@ -62,6 +62,7 @@ func (p *OAuthProvider) exchangeCode(ctx context.Context, code string) (*TokenDa // Snapshot credentials used for this token (for refresh) data.ClientID = clientID data.Source = resolveCredentialSource() + p.applyLoginRegionToToken(data) // Save clientSecret for future refresh (even if env changes) if err := oauthSaveClientSecret(clientID, clientSecret); err != nil { // Log warning but don't fail login @@ -91,11 +92,36 @@ func ExchangeCodeForToken(ctx context.Context, configDir, code string) (*TokenDa return data, nil } +func (p *OAuthProvider) loginRegion() LoginRegion { + if p == nil { + return LoginRegionDefault + } + return p.LoginRegion +} + +func (p *OAuthProvider) useTokenLoginRegion(data *TokenData) { + if p == nil || p.LoginRegion != LoginRegionDefault || data == nil { + return + } + if region := LoginRegion(strings.TrimSpace(data.LoginRegion)); region != LoginRegionDefault { + p.LoginRegion = region + } +} + +func (p *OAuthProvider) applyLoginRegionToToken(data *TokenData) { + if data == nil { + return + } + if region := p.loginRegion(); region != LoginRegionDefault { + data.LoginRegion = string(region) + } +} + // exchangeCodeViaMCP exchanges auth code for token via MCP proxy. // This is used when client secret is not available (server-side secret management). func (p *OAuthProvider) exchangeCodeViaMCP(ctx context.Context, code string) (*TokenData, error) { clientID := ClientID() - url := GetMCPBaseURL() + MCPOAuthTokenPath + url := MCPBaseURLForLoginRegion(p.loginRegion()) + MCPOAuthTokenPath body := map[string]string{ "clientId": clientID, "authCode": code, @@ -112,6 +138,7 @@ func (p *OAuthProvider) exchangeCodeViaMCP(ctx context.Context, code string) (*T // Snapshot credentials used for this token (for refresh) data.ClientID = clientID data.Source = "mcp" + p.applyLoginRegionToToken(data) // MCP mode doesn't need to save clientSecret (server-side managed) return data, nil } @@ -120,8 +147,10 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token // Use stored Source to determine refresh path (not current runtime state) // This ensures refresh works even if environment variables changed since login if data.Source == "mcp" { + p.useTokenLoginRegion(data) return p.refreshViaMCP(ctx, data) } + p.useTokenLoginRegion(data) // Direct mode: use stored clientId and load saved clientSecret clientID := data.ClientID @@ -145,7 +174,7 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token "refreshToken": data.RefreshToken, "grantType": "refresh_token", } - resp, err := p.postJSON(ctx, UserAccessTokenURL, body) + resp, err := p.postJSON(ctx, UserAccessTokenURLForLoginRegion(p.loginRegion()), body) if err != nil { return nil, err } @@ -156,6 +185,7 @@ func (p *OAuthProvider) refreshWithRefreshToken(ctx context.Context, data *Token // Preserve original credentials info updated.ClientID = data.ClientID updated.Source = data.Source + updated.LoginRegion = data.LoginRegion updated.PersistentCode = data.PersistentCode updated.CorpID = data.CorpID updated.UserID = data.UserID @@ -185,7 +215,7 @@ func (p *OAuthProvider) refreshViaMCP(ctx context.Context, data *TokenData) (*To return nil, fmt.Errorf("无法刷新 token: 缺少 clientId，请重新登录") } - url := GetMCPBaseURL() + MCPRefreshTokenPath + url := MCPBaseURLForLoginRegion(p.loginRegion()) + MCPRefreshTokenPath body := map[string]string{ "clientId": clientID, "refreshToken": data.RefreshToken, @@ -202,6 +232,7 @@ func (p *OAuthProvider) refreshViaMCP(ctx context.Context, data *TokenData) (*To // Preserve original credentials info updated.ClientID = data.ClientID updated.Source = data.Source + updated.LoginRegion = data.LoginRegion updated.PersistentCode = data.PersistentCode updated.CorpID = data.CorpID updated.UserID = data.UserID @@ -371,6 +402,10 @@ func firstNonEmpty(values ...string) string { } func buildAuthURL(clientID, redirectURI, targetCorpID string) string { + return buildAuthURLForRegion(clientID, redirectURI, targetCorpID, LoginRegionDefault) +} + +func buildAuthURLForRegion(clientID, redirectURI, targetCorpID string, region LoginRegion) string { params := url.Values{ "client_id": {clientID}, "redirect_uri": {redirectURI}, @@ -381,7 +416,7 @@ func buildAuthURL(clientID, redirectURI, targetCorpID string) string { if targetCorpID = strings.TrimSpace(targetCorpID); targetCorpID != "" { params.Set("corpId", targetCorpID) } - return AuthorizeURL + "?" + params.Encode() + return AuthorizeURLForLoginRegion(region) + "?" + params.Encode() } const successHTML = ` @@ -1416,7 +1451,7 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str } func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) { - url := GetMCPBaseURL() + CLIAuthEnabledPath + url := MCPBaseURLForLoginRegion(p.loginRegion()) + CLIAuthEnabledPath req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { return nil, fmt.Errorf("creating request: %w", err) @@ -1452,6 +1487,10 @@ func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken s // GetSuperAdmins fetches the list of corp super admins. // It retries up to mcpRequestMaxRetries times on transient errors. func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminResponse, error) { + return GetSuperAdminsForLoginRegion(ctx, accessToken, LoginRegionDefault) +} + +func GetSuperAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) { var lastErr error for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ { if attempt > 0 { @@ -1461,7 +1500,7 @@ func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespons case <-oauthRetryAfter(time.Duration(attempt) * time.Second): } } - result, err := doGetSuperAdmins(ctx, accessToken) + result, err := doGetSuperAdminsForLoginRegion(ctx, accessToken, region) if err == nil { return result, nil } @@ -1471,7 +1510,11 @@ func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespons } func doGetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminResponse, error) { - url := GetMCPBaseURL() + SuperAdminPath + return doGetSuperAdminsForLoginRegion(ctx, accessToken, LoginRegionDefault) +} + +func doGetSuperAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) { + url := MCPBaseURLForLoginRegion(region) + SuperAdminPath req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { return nil, fmt.Errorf("creating request: %w", err) @@ -1500,6 +1543,10 @@ func doGetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminRespo // SendCliAuthApply sends a CLI auth apply request to the specified admin. // It retries up to mcpRequestMaxRetries times on transient errors. func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*SendApplyResponse, error) { + return SendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, LoginRegionDefault) +} + +func SendCliAuthApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) { var lastErr error for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ { if attempt > 0 { @@ -1509,7 +1556,7 @@ func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*S case <-oauthRetryAfter(time.Duration(attempt) * time.Second): } } - result, err := doSendCliAuthApply(ctx, accessToken, adminStaffID) + result, err := doSendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, region) if err == nil { return result, nil } @@ -1519,7 +1566,11 @@ func SendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*S } func doSendCliAuthApply(ctx context.Context, accessToken, adminStaffID string) (*SendApplyResponse, error) { - url := GetMCPBaseURL() + SendCliAuthApplyPath + "?adminStaffId=" + adminStaffID + return doSendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, LoginRegionDefault) +} + +func doSendCliAuthApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) { + url := MCPBaseURLForLoginRegion(region) + SendCliAuthApplyPath + "?adminStaffId=" + adminStaffID req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { return nil, fmt.Errorf("creating request: %w", err) @@ -1557,6 +1608,10 @@ type ClientIDResponse struct { // This is used when no client ID is provided via flags, config, or env vars. // It retries up to mcpRequestMaxRetries times on transient errors. func FetchClientIDFromMCP(ctx context.Context) (string, error) { + return FetchClientIDFromMCPForLoginRegion(ctx, LoginRegionDefault) +} + +func FetchClientIDFromMCPForLoginRegion(ctx context.Context, region LoginRegion) (string, error) { var lastErr error for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ { if attempt > 0 { @@ -1566,7 +1621,7 @@ func FetchClientIDFromMCP(ctx context.Context) (string, error) { case <-oauthRetryAfter(time.Duration(attempt) * time.Second): } } - id, err := doFetchClientIDFromMCP(ctx) + id, err := doFetchClientIDFromMCPForLoginRegion(ctx, region) if err == nil { return id, nil } @@ -1576,7 +1631,11 @@ func FetchClientIDFromMCP(ctx context.Context) (string, error) { } func doFetchClientIDFromMCP(ctx context.Context) (string, error) { - url := GetMCPBaseURL() + ClientIDPath + return doFetchClientIDFromMCPForLoginRegion(ctx, LoginRegionDefault) +} + +func doFetchClientIDFromMCPForLoginRegion(ctx context.Context, region LoginRegion) (string, error) { + url := MCPBaseURLForLoginRegion(region) + ClientIDPath req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { return "", fmt.Errorf("creating request: %w", err) diff --git a/internal/auth/oauth_provider.go b/internal/auth/oauth_provider.go index 2396f650..91da2172 100644 --- a/internal/auth/oauth_provider.go +++ b/internal/auth/oauth_provider.go @@ -68,6 +68,27 @@ var ( oauthSleep = time.Sleep ) +func oauthFetchClientIDForLoginRegion(ctx context.Context, region LoginRegion) (string, error) { + if region.IsInternational() { + return FetchClientIDFromMCPForLoginRegion(ctx, region) + } + return oauthFetchClientID(ctx) +} + +func oauthGetAdminsForLoginRegion(ctx context.Context, accessToken string, region LoginRegion) (*SuperAdminResponse, error) { + if region.IsInternational() { + return GetSuperAdminsForLoginRegion(ctx, accessToken, region) + } + return oauthGetAdmins(ctx, accessToken) +} + +func oauthSendApplyForLoginRegion(ctx context.Context, accessToken, adminStaffID string, region LoginRegion) (*SendApplyResponse, error) { + if region.IsInternational() { + return SendCliAuthApplyForLoginRegion(ctx, accessToken, adminStaffID, region) + } + return oauthSendApply(ctx, accessToken, adminStaffID) +} + // OAuthProvider handles the DingTalk OAuth 2.0 authorization code flow. type OAuthProvider struct { configDir string @@ -80,6 +101,7 @@ type OAuthProvider struct { // IdentityEnricher resolves userId/userName/corpName while the freshly // exchanged access token is still only in memory. IdentityEnricher func(context.Context, *TokenData) error + LoginRegion LoginRegion } // NewOAuthProvider creates a new OAuth provider. @@ -173,7 +195,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro if p.logger != nil { p.logger.Debug("fetching client ID from MCP server (OAuth flow always re-fetches)") } - mcpClientID, mcpErr := oauthFetchClientID(ctx) + mcpClientID, mcpErr := oauthFetchClientIDForLoginRegion(ctx, p.LoginRegion) if mcpErr != nil { return nil, fmt.Errorf("%s: %w", i18n.T("获取 Client ID 失败"), mcpErr) } @@ -401,7 +423,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro _, _ = w.Write([]byte(`{"success":false,"errorMsg":"授权尚未完成"}`)) return } - result, err := oauthGetAdmins(ctx, token.AccessToken) + result, err := oauthGetAdminsForLoginRegion(ctx, token.AccessToken, p.LoginRegion) if err != nil { _, _ = fmt.Fprintf(w, `{"success":false,"errorMsg":"%s"}`, err.Error()) return @@ -425,7 +447,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro _, _ = w.Write([]byte(`{"success":false,"errorMsg":"授权尚未完成"}`)) return } - result, err := oauthSendApply(ctx, token.AccessToken, adminStaffID) + result, err := oauthSendApplyForLoginRegion(ctx, token.AccessToken, adminStaffID, p.LoginRegion) if err != nil { _, _ = fmt.Fprintf(w, `{"success":false,"errorMsg":"%s"}`, err.Error()) return @@ -491,7 +513,7 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro _ = server.Shutdown(shutCtx) }() - authURL := buildAuthURL(p.clientID, redirectURI, p.TargetCorpID) + authURL := buildAuthURLForRegion(p.clientID, redirectURI, p.TargetCorpID, p.LoginRegion) if p.logger != nil { p.logger.Debug("authorization URL", "url", authURL) } diff --git a/internal/auth/token.go b/internal/auth/token.go index b4d02294..c511b45b 100644 --- a/internal/auth/token.go +++ b/internal/auth/token.go @@ -97,6 +97,7 @@ type TokenData struct { ClientID string `json:"client_id,omitempty"` // Associated app client ID for refresh UpdatedAt string `json:"updated_at,omitempty"` Source string `json:"source,omitempty"` + LoginRegion string `json:"login_region,omitempty"` // LegacyOrgScopedProfile is an in-memory destination for an explicitly // matched historical profile whose userId was never resolved. It is never // persisted as token material. From 90070840f1390dcf997d283175444dd43a275603 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Thu, 23 Jul 2026 16:37:53 +0800 Subject: [PATCH 058/250] compatible with global auth --- internal/app/auth_command.go | 134 ++++++++++++++++++ internal/app/auth_command_test.go | 180 ++++++++++++++++++++++++ internal/app/direct_runtime.go | 31 +++- internal/app/root_help_test.go | 34 +++++ internal/auth/auth_extra_test.go | 21 +++ internal/auth/cli_auth_check_test.go | 55 ++++++++ internal/auth/endpoints.go | 55 ++++++++ internal/auth/oauth_helpers.go | 57 +++++++- internal/transport/client.go | 8 +- internal/transport/client_extra_test.go | 12 ++ internal/transport/client_test.go | 10 ++ 11 files changed, 589 insertions(+), 8 deletions(-) diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index 3357acf3..508c4836 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -20,6 +20,8 @@ import ( "encoding/json" "fmt" "io" + "net" + "net/url" "os" "path/filepath" "runtime" @@ -49,6 +51,13 @@ type authLoginConfig struct { HistoryProfileSelector string HistoryProfileSelectorExplicit bool International bool + PreURL string + MCPURL string +} + +type authLoginEndpointOverrides struct { + LoginURL string + MCPURL string } type authLoginGuideAction string @@ -118,6 +127,8 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { dws auth login # 本机登录并新增/刷新一个组织 profile dws auth login --profile # 指定本次授权目标组织，不持久切换当前组织 dws auth login --intl # 使用钉钉国际登录入口 + dws auth login --intl --pre-url https://pre-login.dingtalk.io + dws auth login --intl --pre-url https://pre-mcp.dingtalk.io dws auth login --recommend # 无交互批量授权服务端推荐权限 dws auth login --device # SSH 远程 / 无头环境登录 (设备流) dws auth login --force # 兼容保留；login 默认已忽略缓存并进入授权流程 @@ -128,6 +139,22 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { if err != nil { return err } + var preOverrides authLoginEndpointOverrides + if cfg.PreURL != "" { + var err error + preOverrides, err = authLoginEndpointOverridesForPreURL(cfg.PreURL) + if err != nil { + return err + } + restoreLoginBaseURL := authpkg.PushLoginBaseURLOverride(preOverrides.LoginURL) + defer restoreLoginBaseURL() + } + mcpBaseURL, persistMCPURL, err := authLoginMCPBaseURLForConfig(cfg, preOverrides) + if err != nil { + return err + } + restoreMCPBaseURL := authpkg.PushMCPBaseURLOverride(mcpBaseURL) + defer restoreMCPBaseURL() configDir := defaultConfigDir() var tokenData *authpkg.TokenData format, _ := cmd.Root().PersistentFlags().GetString("format") @@ -188,6 +215,11 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { } } + if tokenData != nil { + if err := persistAuthLoginMCPBaseURL(configDir, mcpBaseURL, persistMCPURL); err != nil { + return apperrors.NewInternal(fmt.Sprintf("failed to persist MCP URL: %v", err)) + } + } ResetRuntimeTokenCache() clearCompatCache() w := cmd.OutOrStdout() @@ -288,6 +320,8 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { cmd.Flags().Bool("device", false, "Use device authorization flow") cmd.Flags().Bool("intl", false, "Use DingTalk international login") cmd.Flags().Bool("international", false, "Use DingTalk international login") + cmd.Flags().String("pre-url", "", "Override pre-release login/MCP base URL for this login") + cmd.Flags().String("mcp-url", "", "Override MCP base URL for this login") cmd.Flags().Bool("force", false, "兼容保留；login 默认已忽略缓存并进入授权流程") cmd.Flags().Bool("recommend", false, "登录成功后无交互批量授权服务端推荐权限") // Hidden compatibility flags @@ -1251,6 +1285,14 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) { if err != nil { return authLoginConfig{}, apperrors.NewInternal("failed to read --recommend") } + preURL, err := cmd.Flags().GetString("pre-url") + if err != nil { + return authLoginConfig{}, apperrors.NewInternal("failed to read --pre-url") + } + mcpURL, err := cmd.Flags().GetString("mcp-url") + if err != nil { + return authLoginConfig{}, apperrors.NewInternal("failed to read --mcp-url") + } yes := false profileSelector := "" if cmd.Root() != nil { @@ -1285,9 +1327,101 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) { HistoryProfileSelector: historyProfileSelector, HistoryProfileSelectorExplicit: historyProfileSelectorExplicit, International: intl || international, + PreURL: strings.TrimSpace(preURL), + MCPURL: strings.TrimSpace(mcpURL), }, nil } +func authLoginEndpointOverridesForPreURL(raw string) (authLoginEndpointOverrides, error) { + parsed, normalized, err := normalizeAuthLoginBaseURL(raw, "--pre-url") + if err != nil { + return authLoginEndpointOverrides{}, err + } + host := strings.ToLower(parsed.Hostname()) + switch { + case strings.HasPrefix(host, "pre-login."): + return authLoginEndpointOverrides{ + LoginURL: normalized, + MCPURL: authLoginURLWithHost(parsed, "pre-mcp."+strings.TrimPrefix(host, "pre-login.")), + }, nil + case strings.HasPrefix(host, "pre-mcp."): + return authLoginEndpointOverrides{ + LoginURL: authLoginURLWithHost(parsed, "pre-login."+strings.TrimPrefix(host, "pre-mcp.")), + MCPURL: normalized, + }, nil + default: + return authLoginEndpointOverrides{}, apperrors.NewValidation("--pre-url must be a pre-login.* or pre-mcp.* URL") + } +} + +func authLoginMCPBaseURLForConfig(cfg authLoginConfig, preOverrides authLoginEndpointOverrides) (string, bool, error) { + if cfg.MCPURL != "" { + _, normalized, err := normalizeAuthLoginBaseURL(cfg.MCPURL, "--mcp-url") + if err != nil { + return "", false, err + } + return normalized, true, nil + } + if cfg.PreURL != "" { + if preOverrides.MCPURL == "" { + var err error + preOverrides, err = authLoginEndpointOverridesForPreURL(cfg.PreURL) + if err != nil { + return "", false, err + } + } + return preOverrides.MCPURL, true, nil + } + if cfg.International { + return authpkg.InternationalMCPBaseURL, true, nil + } + return authpkg.DefaultMCPBaseURL, false, nil +} + +func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persist bool) error { + if persist { + return authpkg.NewManager(configDir, nil).SaveMCPURL(mcpBaseURL) + } + if err := os.Remove(filepath.Join(configDir, "mcp_url")); err != nil && !os.IsNotExist(err) { + return err + } + return nil +} + +func normalizeAuthLoginBaseURL(raw, flagName string) (*url.URL, string, error) { + value := strings.TrimSpace(raw) + if value == "" { + return nil, "", apperrors.NewValidation(flagName + " cannot be empty") + } + if !strings.Contains(value, "://") { + value = "https://" + value + } + parsed, err := url.Parse(value) + if err != nil { + return nil, "", apperrors.NewValidation(fmt.Sprintf("invalid %s: %v", flagName, err)) + } + if parsed.Scheme != "http" && parsed.Scheme != "https" { + return nil, "", apperrors.NewValidation(flagName + " must use http or https") + } + if parsed.Hostname() == "" { + return nil, "", apperrors.NewValidation(flagName + " must include a host") + } + parsed.RawQuery = "" + parsed.Fragment = "" + parsed.Path = strings.TrimRight(parsed.Path, "/") + return parsed, strings.TrimRight(parsed.String(), "/"), nil +} + +func authLoginURLWithHost(parsed *url.URL, host string) string { + copyURL := *parsed + if port := parsed.Port(); port != "" { + copyURL.Host = net.JoinHostPort(host, port) + } else { + copyURL.Host = host + } + return strings.TrimRight(copyURL.String(), "/") +} + func authLoginForcesAuthorization(_ authLoginConfig) bool { return true } diff --git a/internal/app/auth_command_test.go b/internal/app/auth_command_test.go index 7d4f1e86..a1ea7144 100644 --- a/internal/app/auth_command_test.go +++ b/internal/app/auth_command_test.go @@ -1037,6 +1037,8 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) { login.Flags().Bool("international", false, "") login.Flags().Bool("force", false, "") login.Flags().Bool("recommend", false, "") + login.Flags().String("pre-url", "", "") + login.Flags().String("mcp-url", "", "") root.AddCommand(login) if err := root.PersistentFlags().Set("yes", "true"); err != nil { @@ -1075,6 +1077,8 @@ func TestResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { login.Flags().Bool("international", false, "") login.Flags().Bool("force", false, "") login.Flags().Bool("recommend", false, "") + login.Flags().String("pre-url", "", "") + login.Flags().String("mcp-url", "", "") root.AddCommand(login) if err := login.Flags().Set(flag, "true"); err != nil { @@ -1092,6 +1096,182 @@ func TestResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { } } +func TestResolveAuthLoginConfigReadsMCPURL(t *testing.T) { + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().Bool("yes", false, "") + login := &cobra.Command{Use: "login"} + login.Flags().String("token", "", "") + login.Flags().Bool("device", false, "") + login.Flags().Bool("intl", false, "") + login.Flags().Bool("international", false, "") + login.Flags().Bool("force", false, "") + login.Flags().Bool("recommend", false, "") + login.Flags().String("pre-url", "", "") + login.Flags().String("mcp-url", "", "") + root.AddCommand(login) + + if err := login.Flags().Set("mcp-url", " https://pre-mcp.dingtalk.io/ "); err != nil { + t.Fatalf("set mcp-url: %v", err) + } + + cfg, err := resolveAuthLoginConfig(login) + if err != nil { + t.Fatalf("resolveAuthLoginConfig error = %v", err) + } + if cfg.MCPURL != "https://pre-mcp.dingtalk.io/" { + t.Fatalf("MCPURL = %q, want trimmed flag value", cfg.MCPURL) + } +} + +func TestResolveAuthLoginConfigReadsPreURL(t *testing.T) { + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().Bool("yes", false, "") + login := &cobra.Command{Use: "login"} + login.Flags().String("token", "", "") + login.Flags().Bool("device", false, "") + login.Flags().Bool("intl", false, "") + login.Flags().Bool("international", false, "") + login.Flags().Bool("force", false, "") + login.Flags().Bool("recommend", false, "") + login.Flags().String("pre-url", "", "") + login.Flags().String("mcp-url", "", "") + root.AddCommand(login) + + if err := login.Flags().Set("pre-url", " pre-login.dingtalk.io "); err != nil { + t.Fatalf("set pre-url: %v", err) + } + + cfg, err := resolveAuthLoginConfig(login) + if err != nil { + t.Fatalf("resolveAuthLoginConfig error = %v", err) + } + if cfg.PreURL != "pre-login.dingtalk.io" { + t.Fatalf("PreURL = %q, want trimmed flag value", cfg.PreURL) + } +} + +func TestAuthLoginEndpointOverridesForPreURL(t *testing.T) { + tests := []struct { + name string + raw string + wantLogin string + wantMCP string + }{ + { + name: "pre login", + raw: "https://pre-login.dingtalk.io/", + wantLogin: "https://pre-login.dingtalk.io", + wantMCP: "https://pre-mcp.dingtalk.io", + }, + { + name: "pre mcp", + raw: "pre-mcp.dingtalk.io", + wantLogin: "https://pre-login.dingtalk.io", + wantMCP: "https://pre-mcp.dingtalk.io", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := authLoginEndpointOverridesForPreURL(tc.raw) + if err != nil { + t.Fatalf("authLoginEndpointOverridesForPreURL error = %v", err) + } + if got.LoginURL != tc.wantLogin || got.MCPURL != tc.wantMCP { + t.Fatalf("overrides = %#v, want login %q mcp %q", got, tc.wantLogin, tc.wantMCP) + } + }) + } +} + +func TestAuthLoginMCPBaseURLForConfig(t *testing.T) { + tests := []struct { + name string + cfg authLoginConfig + preOverride authLoginEndpointOverrides + wantURL string + wantPersist bool + }{ + { + name: "default center login uses com without persisted override", + cfg: authLoginConfig{}, + wantURL: authpkg.DefaultMCPBaseURL, + wantPersist: false, + }, + { + name: "international login persists io", + cfg: authLoginConfig{International: true}, + wantURL: authpkg.InternationalMCPBaseURL, + wantPersist: true, + }, + { + name: "pre login persists mapped pre mcp", + cfg: authLoginConfig{PreURL: "pre-login.dingtalk.io"}, + preOverride: authLoginEndpointOverrides{ + LoginURL: "https://pre-login.dingtalk.io", + MCPURL: "https://pre-mcp.dingtalk.io", + }, + wantURL: "https://pre-mcp.dingtalk.io", + wantPersist: true, + }, + { + name: "explicit mcp url wins over pre url", + cfg: authLoginConfig{ + PreURL: "pre-login.dingtalk.io", + MCPURL: " https://custom-mcp.example.com/ ", + }, + preOverride: authLoginEndpointOverrides{ + LoginURL: "https://pre-login.dingtalk.io", + MCPURL: "https://pre-mcp.dingtalk.io", + }, + wantURL: "https://custom-mcp.example.com", + wantPersist: true, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + gotURL, gotPersist, err := authLoginMCPBaseURLForConfig(tc.cfg, tc.preOverride) + if err != nil { + t.Fatalf("authLoginMCPBaseURLForConfig error = %v", err) + } + if gotURL != tc.wantURL || gotPersist != tc.wantPersist { + t.Fatalf("got url=%q persist=%v, want url=%q persist=%v", gotURL, gotPersist, tc.wantURL, tc.wantPersist) + } + }) + } +} + +func TestPersistAuthLoginMCPBaseURL(t *testing.T) { + t.Run("persists selected io mcp url", func(t *testing.T) { + configDir := t.TempDir() + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, true); err != nil { + t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err) + } + data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")) + if err != nil { + t.Fatalf("ReadFile(mcp_url) error = %v", err) + } + if string(data) != authpkg.InternationalMCPBaseURL { + t.Fatalf("mcp_url = %q, want %q", string(data), authpkg.InternationalMCPBaseURL) + } + }) + + t.Run("center login clears previous persisted override", func(t *testing.T) { + configDir := t.TempDir() + mcpURLPath := filepath.Join(configDir, "mcp_url") + if err := os.WriteFile(mcpURLPath, []byte("https://mcp.dingtalk.io"), 0o600); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, false); err != nil { + t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err) + } + if _, err := os.Stat(mcpURLPath); !os.IsNotExist(err) { + t.Fatalf("mcp_url still exists after center login, stat err = %v", err) + } + }) +} + func TestAuthLoginForcesAuthorizationByDefault(t *testing.T) { if !authLoginForcesAuthorization(authLoginConfig{}) { t.Fatal("auth login should force authorization by default so each login can add an organization profile") diff --git a/internal/app/direct_runtime.go b/internal/app/direct_runtime.go index 1597d6bd..3fdc76e5 100644 --- a/internal/app/direct_runtime.go +++ b/internal/app/direct_runtime.go @@ -131,7 +131,7 @@ func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[strin return } id := strings.TrimSpace(server.CLI.ID) - endpoint := strings.TrimSpace(server.Endpoint) + endpoint := activeDingTalkGatewayEndpoint(server.Endpoint) if id != "" && endpoint != "" { endpoints[id] = endpoint products[id] = true @@ -282,7 +282,7 @@ func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo return "", false } for _, server := range fn() { - endpoint := strings.TrimSpace(server.Endpoint) + endpoint := activeDingTalkGatewayEndpoint(server.Endpoint) if endpoint == "" { continue } @@ -298,6 +298,33 @@ func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo return "", false } +func activeDingTalkGatewayEndpoint(endpoint string) string { + endpoint = strings.TrimSpace(endpoint) + parsed, err := url.Parse(endpoint) + if err != nil || parsed.Scheme == "" || parsed.Host == "" { + return endpoint + } + if !isDingTalkMCPGatewayHost(parsed.Hostname()) { + return endpoint + } + base, err := url.Parse(defaultPATGatewayBaseURL()) + if err != nil || base.Scheme == "" || base.Host == "" { + return endpoint + } + parsed.Scheme = base.Scheme + parsed.Host = base.Host + return strings.TrimRight(parsed.String(), "/") +} + +func isDingTalkMCPGatewayHost(host string) bool { + switch strings.ToLower(strings.TrimSpace(host)) { + case "mcp-gw.dingtalk.com", "pre-mcp-gw.dingtalk.com", "mcp-gw.dingtalk.io", "pre-mcp-gw.dingtalk.io": + return true + default: + return false + } +} + // DirectRuntimeProductIDs returns product IDs that should stay visible for // direct runtime execution. Dynamic products come from MCP discovery/plugin // registration; built-in helper products such as devapp resolve their endpoint diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index eb370a7b..aa080db3 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -473,6 +473,40 @@ func TestInjectStaticServersMergesStaticAndSupplementServers(t *testing.T) { } } +func TestStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) { + previous := edition.Get() + defer edition.Override(previous) + defer SetDynamicServers(nil) + + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) + if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://pre-mcp.dingtalk.io\n"), 0o600); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + + edition.Override(&edition.Hooks{ + Name: "test", + StaticServers: func() []edition.ServerInfo { + return []edition.ServerInfo{{ + ID: "contact", + Name: "Contact", + Endpoint: "https://mcp-gw.dingtalk.com/server/contact?key=abc", + Prefixes: []string{"user"}, + }} + }, + }) + + injectStaticServers() + + for _, productID := range []string{"contact", "user"} { + got, ok := directRuntimeEndpoint(productID, "") + want := "https://pre-mcp-gw.dingtalk.io/server/contact?key=abc" + if !ok || got != want { + t.Fatalf("directRuntimeEndpoint(%q) = %q, %v; want %q, true", productID, got, ok, want) + } + } +} + func mustFindCommand(t *testing.T, root *cobra.Command, path ...string) *cobra.Command { t.Helper() cmd := root diff --git a/internal/auth/auth_extra_test.go b/internal/auth/auth_extra_test.go index 07202e7a..afff7403 100644 --- a/internal/auth/auth_extra_test.go +++ b/internal/auth/auth_extra_test.go @@ -446,6 +446,27 @@ func TestLoginRegionEndpointDefaults(t *testing.T) { } } +func TestMCPBaseURLOverrideAffectsInternationalRegion(t *testing.T) { + restore := PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io/") + defer restore() + + if got := MCPBaseURLForLoginRegion(LoginRegionInternational); got != "https://pre-mcp.dingtalk.io" { + t.Fatalf("international MCP base URL = %q, want override", got) + } +} + +func TestLoginBaseURLOverrideAffectsInternationalRegion(t *testing.T) { + restore := PushLoginBaseURLOverride("https://pre-login.dingtalk.io/") + defer restore() + + if got := DeviceBaseURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io" { + t.Fatalf("international device base URL = %q, want override", got) + } + if got := AuthorizeURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io/oauth2/auth" { + t.Fatalf("international authorize URL = %q, want override", got) + } +} + func buildTokenDataFromResponse(resp tokenResponse) *TokenData { if resp.AccessToken == "" { return nil diff --git a/internal/auth/cli_auth_check_test.go b/internal/auth/cli_auth_check_test.go index 6ed68644..7fb10fba 100644 --- a/internal/auth/cli_auth_check_test.go +++ b/internal/auth/cli_auth_check_test.go @@ -14,10 +14,12 @@ package auth import ( + "bytes" "context" "encoding/json" "fmt" "io" + "log/slog" "net/http" "net/http/httptest" "os" @@ -206,6 +208,59 @@ func TestCheckCLIAuthEnabled_Enabled(t *testing.T) { t.Logf("✅ Normal enabled response: success=%v, enabled=%v", status.Success, status.Result.CLIAuthEnabled) } +func TestCheckCLIAuthEnabled_TraceHeadersAndDebugLog(t *testing.T) { + t.Setenv("DINGTALK_TRACE_ID", "trace-for-cli-auth-test") + + var logBuf bytes.Buffer + previousLogger := slog.Default() + slog.SetDefault(slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug}))) + defer slog.SetDefault(previousLogger) + + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if got := r.Header.Get("EagleEye-TraceId"); got != "trace-for-cli-auth-test" { + t.Errorf("EagleEye-TraceId = %q, want trace-for-cli-auth-test", got) + } + if got := r.Header.Get("X-Dingtalk-Trace-Id"); got != "trace-for-cli-auth-test" { + t.Errorf("X-Dingtalk-Trace-Id = %q, want trace-for-cli-auth-test", got) + } + w.Header().Set("EagleEye-TraceId", "server-trace-001") + w.Header().Set("EagleEye-RpcId", "rpc-001") + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(CLIAuthStatus{ + Success: true, + Result: &CLIAuthResult{CLIAuthEnabled: true}, + }) + })) + defer srv.Close() + + configDir := setupMCPConfigDir(t, srv.URL) + p := &OAuthProvider{configDir: configDir, httpClient: srv.Client()} + + status, err := p.CheckCLIAuthEnabled(context.Background(), "sensitive-token") + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if status.Result == nil || !status.Result.CLIAuthEnabled { + t.Fatal("expected CLIAuthEnabled=true") + } + + logs := logBuf.String() + for _, want := range []string{ + "auth.cli_auth_enabled.request", + "auth.cli_auth_enabled.response", + "trace-for-cli-auth-test", + "server-trace-001", + "rpc-001", + } { + if !strings.Contains(logs, want) { + t.Fatalf("debug logs missing %q, got: %s", want, logs) + } + } + if strings.Contains(logs, "sensitive-token") { + t.Fatalf("debug logs leaked access token: %s", logs) + } +} + func TestCheckCLIAuthEnabled_Disabled(t *testing.T) { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") diff --git a/internal/auth/endpoints.go b/internal/auth/endpoints.go index 5181f075..54878664 100644 --- a/internal/auth/endpoints.go +++ b/internal/auth/endpoints.go @@ -136,6 +136,9 @@ func (r LoginRegion) IsInternational() bool { } func AuthorizeURLForLoginRegion(region LoginRegion) string { + if override := LoginBaseURLOverride(); override != "" { + return override + "/oauth2/auth" + } if region.IsInternational() { return InternationalAuthorizeURL } @@ -143,6 +146,9 @@ func AuthorizeURLForLoginRegion(region LoginRegion) string { } func DeviceBaseURLForLoginRegion(region LoginRegion) string { + if override := LoginBaseURLOverride(); override != "" { + return override + } if region.IsInternational() { return InternationalDeviceBaseURL } @@ -150,6 +156,9 @@ func DeviceBaseURLForLoginRegion(region LoginRegion) string { } func MCPBaseURLForLoginRegion(region LoginRegion) string { + if override := MCPBaseURLOverride(); override != "" { + return override + } if region.IsInternational() { return InternationalMCPBaseURL } @@ -195,8 +204,54 @@ var ( // clientIDFromMCP indicates whether the clientID was fetched from MCP server. // When true, MCP OAuth endpoints should be used instead of direct DingTalk API. clientIDFromMCP bool + + loginBaseURLMu sync.RWMutex + loginBaseURLOverride string + mcpBaseURLMu sync.RWMutex + mcpBaseURLOverride string ) +// PushLoginBaseURLOverride sets a process-local DingTalk login base URL +// override and returns a restore function. +func PushLoginBaseURLOverride(baseURL string) func() { + loginBaseURLMu.Lock() + previous := loginBaseURLOverride + loginBaseURLOverride = strings.TrimRight(strings.TrimSpace(baseURL), "/") + loginBaseURLMu.Unlock() + return func() { + loginBaseURLMu.Lock() + loginBaseURLOverride = previous + loginBaseURLMu.Unlock() + } +} + +func LoginBaseURLOverride() string { + loginBaseURLMu.RLock() + defer loginBaseURLMu.RUnlock() + return loginBaseURLOverride +} + +// PushMCPBaseURLOverride sets a process-local MCP base URL override and returns +// a restore function. It is intended for one command invocation, such as +// pre-release smoke testing. +func PushMCPBaseURLOverride(baseURL string) func() { + mcpBaseURLMu.Lock() + previous := mcpBaseURLOverride + mcpBaseURLOverride = strings.TrimRight(strings.TrimSpace(baseURL), "/") + mcpBaseURLMu.Unlock() + return func() { + mcpBaseURLMu.Lock() + mcpBaseURLOverride = previous + mcpBaseURLMu.Unlock() + } +} + +func MCPBaseURLOverride() string { + mcpBaseURLMu.RLock() + defer mcpBaseURLMu.RUnlock() + return mcpBaseURLOverride +} + // SetClientIDFromMCP sets the clientID fetched from MCP server and marks it as MCP-sourced. func SetClientIDFromMCP(id string) { clientMu.Lock() diff --git a/internal/auth/oauth_helpers.go b/internal/auth/oauth_helpers.go index 0dbdd783..4e16c5fc 100644 --- a/internal/auth/oauth_helpers.go +++ b/internal/auth/oauth_helpers.go @@ -20,6 +20,7 @@ import ( "fmt" "html" "io" + "log/slog" "net/http" "net/url" "os" @@ -28,6 +29,7 @@ import ( "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config" + "github.com/google/uuid" ) var ( @@ -1433,6 +1435,7 @@ const mcpRequestMaxRetries = 3 // false negatives caused by momentary network issues. func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) { var lastErr error + traceID := cliAuthTraceID() for attempt := 0; attempt < mcpRequestMaxRetries; attempt++ { if attempt > 0 { select { @@ -1441,7 +1444,7 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str case <-oauthRetryAfter(time.Duration(attempt) * time.Second): } } - status, err := p.doCheckCLIAuthEnabled(ctx, accessToken) + status, err := p.doCheckCLIAuthEnabled(ctx, accessToken, attempt+1, traceID) if err == nil { return status, nil } @@ -1450,17 +1453,24 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str return nil, fmt.Errorf("check CLI auth status failed after %d attempts: %w", mcpRequestMaxRetries, lastErr) } -func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) { +func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string, attempt int, traceID string) (*CLIAuthStatus, error) { url := MCPBaseURLForLoginRegion(p.loginRegion()) + CLIAuthEnabledPath req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { return nil, fmt.Errorf("creating request: %w", err) } req.Header.Set("x-user-access-token", accessToken) + applyCLIAuthTraceHeaders(req, traceID) if ch := os.Getenv("DWS_CHANNEL"); ch != "" { req.Header.Set("x-dws-channel", ch) } applyEditionEnterpriseCredentialHeaders(req) + slog.Debug("auth.cli_auth_enabled.request", + "attempt", attempt, + "url", url, + "trace_id", traceID, + "channel", os.Getenv("DWS_CHANNEL"), + ) client := p.httpClient if client == nil { @@ -1468,9 +1478,23 @@ func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken s } resp, err := client.Do(req) if err != nil { + slog.Debug("auth.cli_auth_enabled.error", + "attempt", attempt, + "url", url, + "trace_id", traceID, + "error", err, + ) return nil, fmt.Errorf("sending request: %w", err) } defer resp.Body.Close() + slog.Debug("auth.cli_auth_enabled.response", + "attempt", attempt, + "url", url, + "status", resp.StatusCode, + "trace_id", traceID, + "response_trace_id", cliAuthResponseTraceID(resp.Header), + "eagleeye_rpc_id", resp.Header.Get("EagleEye-RpcId"), + ) data, err := io.ReadAll(io.LimitReader(resp.Body, config.MaxResponseBodySize)) if err != nil { @@ -1484,6 +1508,35 @@ func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken s return &status, nil } +func cliAuthTraceID() string { + if traceID := strings.TrimSpace(os.Getenv("DINGTALK_TRACE_ID")); traceID != "" { + return traceID + } + return strings.ReplaceAll(uuid.NewString(), "-", "") +} + +func applyCLIAuthTraceHeaders(req *http.Request, traceID string) { + if req == nil || traceID == "" { + return + } + req.Header.Set("EagleEye-TraceId", traceID) + req.Header.Set("X-Dingtalk-Trace-Id", traceID) +} + +func cliAuthResponseTraceID(headers http.Header) string { + for _, key := range []string{ + "EagleEye-TraceId", + "X-Trace-Id", + "X-Request-Id", + "X-Dingtalk-Trace-Id", + } { + if value := strings.TrimSpace(headers.Get(key)); value != "" { + return value + } + } + return "" +} + // GetSuperAdmins fetches the list of corp super admins. // It retries up to mcpRequestMaxRetries times on transient errors. func GetSuperAdmins(ctx context.Context, accessToken string) (*SuperAdminResponse, error) { diff --git a/internal/transport/client.go b/internal/transport/client.go index ddbae10d..73bac675 100644 --- a/internal/transport/client.go +++ b/internal/transport/client.go @@ -50,14 +50,14 @@ func init() { Name: "DWS_TRUSTED_DOMAINS", Category: configmeta.CategoryNetwork, Description: "信任的 HTTPS 域名白名单 (逗号分隔，* 信任所有)", - DefaultValue: "*.dingtalk.com", - Example: "*.dingtalk.com,custom.example.com", + DefaultValue: "*.dingtalk.com,*.dingtalk.io", + Example: "*.dingtalk.com,*.dingtalk.io,custom.example.com", }) } const ( trustedDomainsEnv = "DWS_TRUSTED_DOMAINS" - defaultTrustedDomains = "*.dingtalk.com" + defaultTrustedDomains = "*.dingtalk.com,*.dingtalk.io" // defaultHTTPTimeout is the default timeout for HTTP transport requests. defaultHTTPTimeout = 30 * time.Second @@ -654,7 +654,7 @@ func shouldPreserveEndpointQuery(parsed *url.URL) bool { return false } switch strings.ToLower(parsed.Hostname()) { - case "mcp-gw.dingtalk.com", "pre-mcp-gw.dingtalk.com": + case "mcp-gw.dingtalk.com", "pre-mcp-gw.dingtalk.com", "mcp-gw.dingtalk.io", "pre-mcp-gw.dingtalk.io": return true default: return false diff --git a/internal/transport/client_extra_test.go b/internal/transport/client_extra_test.go index d9a1b070..fc0da902 100644 --- a/internal/transport/client_extra_test.go +++ b/internal/transport/client_extra_test.go @@ -234,6 +234,18 @@ func TestIsEndpointTrusted_DomainMatch(t *testing.T) { } } +func TestIsEndpointTrusted_DefaultIncludesDingTalkInternational(t *testing.T) { + t.Setenv("DWS_ALLOW_HTTP_ENDPOINTS", "") + t.Setenv("DWS_TRUSTED_DOMAINS", "") + c := NewClient(nil) + if !c.isEndpointTrusted("https://mcp-gw.dingtalk.com/server/contact") { + t.Fatal("default trusted domains should trust dingtalk.com") + } + if !c.isEndpointTrusted("https://pre-mcp-gw.dingtalk.io/server/contact") { + t.Fatal("default trusted domains should trust dingtalk.io") + } +} + func TestHttpStatusError(t *testing.T) { t.Parallel() codes := []int{ diff --git a/internal/transport/client_test.go b/internal/transport/client_test.go index 509a9a31..4d72256f 100644 --- a/internal/transport/client_test.go +++ b/internal/transport/client_test.go @@ -562,6 +562,16 @@ func TestSanitizeJSONRPCEndpointPreservesDingTalkMCPGatewayQuery(t *testing.T) { endpoint: "https://mcp-gw.dingtalk.com/server/demo?key=secret#frag", want: "https://mcp-gw.dingtalk.com/server/demo?key=secret", }, + { + name: "prepub international gateway", + endpoint: "https://pre-mcp-gw.dingtalk.io/server/demo?key=secret#frag", + want: "https://pre-mcp-gw.dingtalk.io/server/demo?key=secret", + }, + { + name: "prod international gateway", + endpoint: "https://mcp-gw.dingtalk.io/server/demo?key=secret#frag", + want: "https://mcp-gw.dingtalk.io/server/demo?key=secret", + }, } for _, tt := range cases { From d9ba74aac060e1874c9e3ec77688a6e01c131800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Fri, 7 Aug 2026 18:06:10 +0800 Subject: [PATCH 059/250] compatible with global auth --- internal/auth/auth_extra_test.go | 9 +++++++++ internal/auth/oauth_helpers.go | 13 +++++++++---- internal/auth/oauth_provider.go | 8 +++++++- internal/errors/errors_test.go | 25 +++++++++++++++++++++++++ pkg/config/constants.go | 16 ++++++++++++++-- pkg/config/constants_test.go | 28 ++++++++++++++++++++++++++++ 6 files changed, 92 insertions(+), 7 deletions(-) diff --git a/internal/auth/auth_extra_test.go b/internal/auth/auth_extra_test.go index afff7403..ccfb68a5 100644 --- a/internal/auth/auth_extra_test.go +++ b/internal/auth/auth_extra_test.go @@ -431,6 +431,15 @@ func TestBuildAuthURLForInternationalRegion(t *testing.T) { } } +func TestNotEnabledHTMLUsesRegionAwareAuthorizeURL(t *testing.T) { + if !strings.Contains(notEnabledHTML, "status.authorizeUrl") { + t.Fatal("not-enabled page must read the authorize URL from the regional login status") + } + if strings.Contains(notEnabledHTML, `"https://login.dingtalk.com/oauth2/auth?client_id="`) { + t.Fatal("not-enabled page must not hard-code the domestic authorize URL") + } +} + func TestLoginRegionEndpointDefaults(t *testing.T) { if got := AuthorizeURLForLoginRegion(LoginRegionDefault); got != AuthorizeURL { t.Fatalf("default authorize URL = %q, want %q", got, AuthorizeURL) diff --git a/internal/auth/oauth_helpers.go b/internal/auth/oauth_helpers.go index 4e16c5fc..fe2c4728 100644 --- a/internal/auth/oauth_helpers.go +++ b/internal/auth/oauth_helpers.go @@ -974,14 +974,15 @@ const notEnabledHTML = ` clientId = status.clientId || ""; applySent = status.applySent || false; selectedAdminId = status.selectedAdminId || ""; + const authorizeUrl = status.authorizeUrl || ""; - if (clientId) { + if (clientId && authorizeUrl) { const port = location.port; const redirectUri = encodeURIComponent( "http://127.0.0.1:" + port + "/callback" ); backLink.href = - "https://login.dingtalk.com/oauth2/auth?client_id=" + + authorizeUrl + "?client_id=" + clientId + "&prompt=consent&redirect_uri=" + redirectUri + @@ -1444,7 +1445,7 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str case <-oauthRetryAfter(time.Duration(attempt) * time.Second): } } - status, err := p.doCheckCLIAuthEnabled(ctx, accessToken, attempt+1, traceID) + status, err := p.doCheckCLIAuthEnabledAttempt(ctx, accessToken, attempt+1, traceID) if err == nil { return status, nil } @@ -1453,7 +1454,11 @@ func (p *OAuthProvider) CheckCLIAuthEnabled(ctx context.Context, accessToken str return nil, fmt.Errorf("check CLI auth status failed after %d attempts: %w", mcpRequestMaxRetries, lastErr) } -func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string, attempt int, traceID string) (*CLIAuthStatus, error) { +func (p *OAuthProvider) doCheckCLIAuthEnabled(ctx context.Context, accessToken string) (*CLIAuthStatus, error) { + return p.doCheckCLIAuthEnabledAttempt(ctx, accessToken, 1, cliAuthTraceID()) +} + +func (p *OAuthProvider) doCheckCLIAuthEnabledAttempt(ctx context.Context, accessToken string, attempt int, traceID string) (*CLIAuthStatus, error) { url := MCPBaseURLForLoginRegion(p.loginRegion()) + CLIAuthEnabledPath req, err := oauthNewRequest(ctx, http.MethodGet, url, nil) if err != nil { diff --git a/internal/auth/oauth_provider.go b/internal/auth/oauth_provider.go index 91da2172..da6b66df 100644 --- a/internal/auth/oauth_provider.go +++ b/internal/auth/oauth_provider.go @@ -470,7 +470,13 @@ func (p *OAuthProvider) Login(ctx context.Context, force bool) (*TokenData, erro applySent := callbackApplySent selectedAdminId := callbackSelectedAdminId callbackTokenMu.Unlock() - _, _ = fmt.Fprintf(w, `{"clientId":"%s","applySent":%t,"selectedAdminId":"%s"}`, p.clientID, applySent, selectedAdminId) + data, _ := json.Marshal(map[string]any{ + "clientId": p.clientID, + "authorizeUrl": AuthorizeURLForLoginRegion(p.LoginRegion), + "applySent": applySent, + "selectedAdminId": selectedAdminId, + }) + _, _ = w.Write(data) }) // API endpoint: check CLI auth enabled status diff --git a/internal/errors/errors_test.go b/internal/errors/errors_test.go index 092f2c84..a2a7d11c 100644 --- a/internal/errors/errors_test.go +++ b/internal/errors/errors_test.go @@ -15,9 +15,13 @@ package errors import ( stderrors "errors" + "os" + "path/filepath" "strings" "testing" "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config" ) func TestCrossPlatformCoverageExitCodeByCategory(t *testing.T) { @@ -382,6 +386,27 @@ func TestCrossPlatformCoverageServerGuidanceSuppressesUnsafeActionURL(t *testing } } +func TestPrintJSONCLIOrgNotAuthorizedUsesInternationalActionURL(t *testing.T) { + dir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", dir) + if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), config.FilePerm); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + + var b strings.Builder + if err := PrintJSON(&b, NewAPI( + "business error", + WithServerDiag(ServerDiagnostics{ServerErrorCode: "CLI_ORG_NOT_AUTHORIZED"}), + )); err != nil { + t.Fatalf("PrintJSON() error = %v", err) + } + + want := `"action_url": "https://open-dev.dingtalk.io/fe/old#/developerSettings"` + if got := b.String(); !strings.Contains(got, want) { + t.Fatalf("expected international action_url %q, got %q", want, got) + } +} + func TestCrossPlatformCoveragePrintJSONIncludesRPCCodeAndData(t *testing.T) { t.Parallel() diff --git a/pkg/config/constants.go b/pkg/config/constants.go index c986e45a..4e7b934b 100644 --- a/pkg/config/constants.go +++ b/pkg/config/constants.go @@ -17,6 +17,7 @@ package config import ( + "net/url" "os" "path/filepath" "strings" @@ -169,6 +170,10 @@ const ( // Override at runtime via ~/.dws/terminal_url file. DefaultTerminalBaseURL = "https://open-dev.dingtalk.com" + // InternationalTerminalBaseURL is the DingTalk international developer + // platform base URL. + InternationalTerminalBaseURL = "https://open-dev.dingtalk.io" + // DeveloperSettingsPath is the path to the organization developer // settings page (CLI access management). DeveloperSettingsPath = "/fe/old#/developerSettings" @@ -201,8 +206,9 @@ func GetMCPBaseURL() string { } // GetTerminalBaseURL returns the terminal base URL with priority: -// 1. ~/.dws/terminal_url file content (for pre-release environment) -// 2. Default value (https://open-dev.dingtalk.com) +// 1. ~/.dws/terminal_url file content (for custom environments) +// 2. International terminal when the configured MCP endpoint uses .io +// 3. Default value (https://open-dev.dingtalk.com) func GetTerminalBaseURL() string { terminalURLPath := filepath.Join(DefaultConfigDir(), "terminal_url") if data, err := os.ReadFile(terminalURLPath); err == nil { @@ -210,6 +216,12 @@ func GetTerminalBaseURL() string { return u } } + if parsed, err := url.Parse(GetMCPBaseURL()); err == nil { + host := strings.ToLower(parsed.Hostname()) + if host == "dingtalk.io" || strings.HasSuffix(host, ".dingtalk.io") { + return InternationalTerminalBaseURL + } + } return DefaultTerminalBaseURL } diff --git a/pkg/config/constants_test.go b/pkg/config/constants_test.go index c9e538b0..2c72b065 100644 --- a/pkg/config/constants_test.go +++ b/pkg/config/constants_test.go @@ -219,6 +219,34 @@ func TestGetMCPBaseURLUsesConfigFile(t *testing.T) { } } +func TestGetDeveloperSettingsURLUsesInternationalMCPRegion(t *testing.T) { + dir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", dir) + if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), FilePerm); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + + want := "https://open-dev.dingtalk.io/fe/old#/developerSettings" + if got := GetDeveloperSettingsURL(); got != want { + t.Fatalf("GetDeveloperSettingsURL() = %q, want %q", got, want) + } +} + +func TestGetTerminalBaseURLPrefersExplicitConfig(t *testing.T) { + dir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", dir) + if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), FilePerm); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + if err := os.WriteFile(filepath.Join(dir, "terminal_url"), []byte("https://custom-open-dev.example.com\n"), FilePerm); err != nil { + t.Fatalf("WriteFile(terminal_url) error = %v", err) + } + + if got := GetTerminalBaseURL(); got != "https://custom-open-dev.example.com" { + t.Fatalf("GetTerminalBaseURL() = %q, want explicit terminal URL", got) + } +} + func TestMaxUploadFileSize(t *testing.T) { t.Parallel() var want int64 = 100 * 1024 * 1024 From 1f6010f998806483536c0ab30cd193bc6ea0b02f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Thu, 13 Aug 2026 11:22:02 +0800 Subject: [PATCH 060/250] aicr endpoint bugfix --- internal/app/access_token_manager_test.go | 8 ++- internal/app/access_token_resolve.go | 16 ++++-- internal/app/agent_metadata_test.go | 4 +- internal/app/direct_runtime.go | 69 ++++++++++++++++++++++- internal/app/root_help_test.go | 41 ++++++++++++++ internal/app/runner.go | 41 ++++++++++---- 6 files changed, 156 insertions(+), 23 deletions(-) diff --git a/internal/app/access_token_manager_test.go b/internal/app/access_token_manager_test.go index e996b7be..358015d2 100644 --- a/internal/app/access_token_manager_test.go +++ b/internal/app/access_token_manager_test.go @@ -65,12 +65,16 @@ func TestCrossPlatformCoverageTokenManagerCachesUntilMarkerRevisionChanges(t *te token := "token-a" installTokenManagerFakes(t, func() (*authpkg.TokenData, error) { calls.Add(1) - return &authpkg.TokenData{AccessToken: token, ExpiresAt: time.Now().Add(time.Hour)}, nil + return &authpkg.TokenData{ + AccessToken: token, + ExpiresAt: time.Now().Add(time.Hour), + LoginRegion: string(authpkg.LoginRegionInternational), + }, nil }) manager := NewTokenManager() first, err := manager.Get(context.Background(), configDir, "") - if err != nil || first.AccessToken != "token-a" { + if err != nil || first.AccessToken != "token-a" || first.LoginRegion != authpkg.LoginRegionInternational || !first.LoginRegionKnown { t.Fatalf("first token = %#v, %v", first, err) } second, err := manager.Get(context.Background(), configDir, "") diff --git a/internal/app/access_token_resolve.go b/internal/app/access_token_resolve.go index c5c969d9..df605673 100644 --- a/internal/app/access_token_resolve.go +++ b/internal/app/access_token_resolve.go @@ -41,9 +41,11 @@ type accessTokenSnapshotGetter interface { // AccessTokenSnapshot is the minimal bearer view needed by the process cache. // Refresh-token material never leaves the auth package. type AccessTokenSnapshot struct { - AccessToken string - ExpiresAt time.Time - Source string + AccessToken string + ExpiresAt time.Time + Source string + LoginRegion authpkg.LoginRegion + LoginRegionKnown bool } type tokenManagerKey struct { @@ -223,9 +225,11 @@ func resolveAccessTokenSnapshotFromDir(ctx context.Context, configDir, profile s data, err := snapshotProvider.GetTokenSnapshot(ctx) if err == nil && data != nil && strings.TrimSpace(data.AccessToken) != "" { return AccessTokenSnapshot{ - AccessToken: strings.TrimSpace(data.AccessToken), - ExpiresAt: data.ExpiresAt, - Source: "oauth", + AccessToken: strings.TrimSpace(data.AccessToken), + ExpiresAt: data.ExpiresAt, + Source: "oauth", + LoginRegion: authpkg.LoginRegion(strings.TrimSpace(data.LoginRegion)), + LoginRegionKnown: true, }, nil } if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) { diff --git a/internal/app/agent_metadata_test.go b/internal/app/agent_metadata_test.go index 2bae8254..3caaa926 100644 --- a/internal/app/agent_metadata_test.go +++ b/internal/app/agent_metadata_test.go @@ -712,9 +712,9 @@ func TestCrossPlatformCoverageAgentMetadataMCPAndPluginScoping(t *testing.T) { // calls must fail before preflight or transport while anonymous plugins remain // valid above. resolveCalled := false - testseam.Swap(t, &runnerResolveAuthToken, func(*runtimeRunner, context.Context) (string, error) { + testseam.Swap(t, &runnerResolveAuthSnapshot, func(*runtimeRunner, context.Context) (AccessTokenSnapshot, error) { resolveCalled = true - return "", nil + return AccessTokenSnapshot{}, nil }) callsBefore := len(captured) unauthenticated := &runtimeRunner{ diff --git a/internal/app/direct_runtime.go b/internal/app/direct_runtime.go index 3fdc76e5..6bec3b11 100644 --- a/internal/app/direct_runtime.go +++ b/internal/app/direct_runtime.go @@ -74,6 +74,20 @@ func defaultPATMCPEndpoint() string { func defaultPATGatewayBaseURL() string { raw := strings.TrimSpace(authpkg.GetMCPBaseURL()) + return mcpGatewayBaseURL(raw) +} + +func defaultPATGatewayBaseURLForLoginRegion(region authpkg.LoginRegion) string { + raw := strings.TrimSpace(authpkg.GetMCPBaseURL()) + if override := authpkg.MCPBaseURLOverride(); override != "" { + raw = override + } else { + raw = mcpBaseURLForLoginRegion(raw, region) + } + return mcpGatewayBaseURL(raw) +} + +func mcpGatewayBaseURL(raw string) string { parsed, err := url.Parse(raw) if err != nil || parsed.Scheme == "" || parsed.Host == "" { return strings.TrimRight(raw, "/") @@ -100,6 +114,33 @@ func defaultPATGatewayBaseURL() string { return strings.TrimRight(parsed.String(), "/") } +func mcpBaseURLForLoginRegion(raw string, region authpkg.LoginRegion) string { + parsed, err := url.Parse(strings.TrimSpace(raw)) + if err != nil || parsed.Scheme == "" || parsed.Host == "" { + return raw + } + host := strings.ToLower(parsed.Hostname()) + fromSuffix, toSuffix := ".dingtalk.io", ".dingtalk.com" + if region.IsInternational() { + fromSuffix, toSuffix = toSuffix, fromSuffix + } + bareFrom := strings.TrimPrefix(fromSuffix, ".") + if host != bareFrom && !strings.HasSuffix(host, fromSuffix) { + return raw + } + if host == bareFrom { + host = strings.TrimPrefix(toSuffix, ".") + } else { + host = strings.TrimSuffix(host, fromSuffix) + toSuffix + } + if port := parsed.Port(); port != "" { + parsed.Host = net.JoinHostPort(host, port) + } else { + parsed.Host = host + } + return parsed.String() +} + // SetDynamicServers injects server data discovered from servers.json. // All product endpoints are resolved dynamically from this data. func SetDynamicServers(servers []mcptypes.ServerDescriptor) { @@ -262,6 +303,19 @@ func directRuntimeEndpoint(productID, toolName string) (string, bool) { return "", false } +func hasDirectRuntimeEndpointOverride(productID string) bool { + normalized := normalizeDirectRuntimeProductID(productID) + for _, candidate := range []string{strings.TrimSpace(productID), normalized} { + if candidate == "" { + continue + } + if _, ok := productEndpointOverride(candidate); ok { + return true + } + } + return false +} + func editionServerEndpoint(productID string) (string, bool) { productID = strings.TrimSpace(productID) if productID == "" { @@ -299,6 +353,14 @@ func endpointFromEditionServers(productID string, fn func() []edition.ServerInfo } func activeDingTalkGatewayEndpoint(endpoint string) string { + return activeDingTalkGatewayEndpointWithBase(endpoint, defaultPATGatewayBaseURL()) +} + +func activeDingTalkGatewayEndpointForLoginRegion(endpoint string, region authpkg.LoginRegion) string { + return activeDingTalkGatewayEndpointWithBase(endpoint, defaultPATGatewayBaseURLForLoginRegion(region)) +} + +func activeDingTalkGatewayEndpointWithBase(endpoint, gatewayBaseURL string) string { endpoint = strings.TrimSpace(endpoint) parsed, err := url.Parse(endpoint) if err != nil || parsed.Scheme == "" || parsed.Host == "" { @@ -307,7 +369,7 @@ func activeDingTalkGatewayEndpoint(endpoint string) string { if !isDingTalkMCPGatewayHost(parsed.Hostname()) { return endpoint } - base, err := url.Parse(defaultPATGatewayBaseURL()) + base, err := url.Parse(gatewayBaseURL) if err != nil || base.Scheme == "" || base.Host == "" { return endpoint } @@ -325,6 +387,11 @@ func isDingTalkMCPGatewayHost(host string) bool { } } +func isDingTalkMCPGatewayEndpoint(endpoint string) bool { + parsed, err := url.Parse(strings.TrimSpace(endpoint)) + return err == nil && isDingTalkMCPGatewayHost(parsed.Hostname()) +} + // DirectRuntimeProductIDs returns product IDs that should stay visible for // direct runtime execution. Dynamic products come from MCP discovery/plugin // registration; built-in helper products such as devapp resolve their endpoint diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index aa080db3..b5e15e9a 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -22,6 +22,7 @@ import ( "strings" "testing" + authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" @@ -507,6 +508,46 @@ func TestStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) { } } +func TestDingTalkEndpointsFollowSelectedTokenRegion(t *testing.T) { + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) + mcpURLPath := filepath.Join(configDir, "mcp_url") + + if err := os.WriteFile(mcpURLPath, []byte("https://pre-mcp.dingtalk.io\n"), 0o600); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + endpoint := "https://pre-mcp-gw.dingtalk.io/server/contact?key=abc" + if got, want := activeDingTalkGatewayEndpointForLoginRegion(endpoint, authpkg.LoginRegionDefault), "https://pre-mcp-gw.dingtalk.com/server/contact?key=abc"; got != want { + t.Fatalf("domestic profile endpoint = %q, want %q", got, want) + } + if got := activeDingTalkGatewayEndpointForLoginRegion(endpoint, authpkg.LoginRegionInternational); got != endpoint { + t.Fatalf("international profile endpoint = %q, want %q", got, endpoint) + } + + if err := os.WriteFile(mcpURLPath, []byte("https://mcp.dingtalk.com\n"), 0o600); err != nil { + t.Fatalf("WriteFile(mcp_url) error = %v", err) + } + if got, want := activeDingTalkGatewayEndpointForLoginRegion("https://mcp-gw.dingtalk.com/server/contact", authpkg.LoginRegionInternational), "https://mcp-gw.dingtalk.io/server/contact"; got != want { + t.Fatalf("international profile endpoint from domestic config = %q, want %q", got, want) + } +} + +func TestDingTalkEndpointUsesLoginScopedMCPOverride(t *testing.T) { + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) + restore := authpkg.PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io") + defer restore() + + got := activeDingTalkGatewayEndpointForLoginRegion( + "https://mcp-gw.dingtalk.com/server/contact", + authpkg.LoginRegionDefault, + ) + want := "https://pre-mcp-gw.dingtalk.io/server/contact" + if got != want { + t.Fatalf("login-scoped endpoint = %q, want %q", got, want) + } +} + func mustFindCommand(t *testing.T, root *cobra.Command, path ...string) *cobra.Command { t.Helper() cmd := root diff --git a/internal/app/runner.go b/internal/app/runner.go index 175f70b9..36e78c1f 100644 --- a/internal/app/runner.go +++ b/internal/app/runner.go @@ -162,7 +162,7 @@ var ( runnerResolveMultiProfileSelections = resolveMultiProfileSelections runnerResolveProfile = authpkg.ResolveProfile runnerGetCachedRuntimeToken = getCachedRuntimeToken - runnerResolveAuthToken = (*runtimeRunner).resolveAuthToken + runnerResolveAuthSnapshot = (*runtimeRunner).resolveAuthSnapshot runnerPreflightDocDownload = (*runtimeRunner).preflightDocDownload runnerCallTool = (*transport.Client).CallTool runnerStdioEnsureInitialized = (*transport.StdioClient).EnsureInitialized @@ -552,11 +552,16 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string, if hasPluginAuth { authToken = pluginAuth.Token } else if !invocation.DryRun && (r.globalFlags == nil || !r.globalFlags.Mock) { - var tokenErr error - authToken, tokenErr = runnerResolveAuthToken(r, ctx) + snapshot, tokenErr := runnerResolveAuthSnapshot(r, ctx) if tokenErr != nil { return executor.Result{}, tokenResolutionError(tokenErr) } + authToken = snapshot.AccessToken + if !hasDirectRuntimeEndpointOverride(invocation.CanonicalProduct) && + isDingTalkMCPGatewayEndpoint(endpoint) && + (snapshot.LoginRegionKnown || authpkg.MCPBaseURLOverride() != "") { + endpoint = activeDingTalkGatewayEndpointForLoginRegion(endpoint, snapshot.LoginRegion) + } } var timeoutSec int @@ -877,21 +882,33 @@ func (r *runtimeRunner) executeStdioInvocationAtEndpoint( } func (r *runtimeRunner) resolveAuthToken(ctx context.Context) (string, error) { - explicitToken := "" - if r != nil && r.globalFlags != nil { - explicitToken = r.globalFlags.Token - } - return resolveRuntimeAuthToken(ctx, explicitToken) -} - -func resolveRuntimeAuthToken(ctx context.Context, explicitToken string) (string, error) { - snapshot, err := runtimeTokenManager.Get(ctx, defaultConfigDir(), explicitToken) + snapshot, err := r.resolveAuthSnapshot(ctx) if err != nil { return "", err } return snapshot.AccessToken, nil } +func (r *runtimeRunner) resolveAuthSnapshot(ctx context.Context) (AccessTokenSnapshot, error) { + explicitToken := "" + if r != nil && r.globalFlags != nil { + explicitToken = r.globalFlags.Token + } + return resolveRuntimeAuthSnapshot(ctx, explicitToken) +} + +func resolveRuntimeAuthToken(ctx context.Context, explicitToken string) (string, error) { + snapshot, err := resolveRuntimeAuthSnapshot(ctx, explicitToken) + if err != nil { + return "", err + } + return snapshot.AccessToken, nil +} + +func resolveRuntimeAuthSnapshot(ctx context.Context, explicitToken string) (AccessTokenSnapshot, error) { + return runtimeTokenManager.Get(ctx, defaultConfigDir(), explicitToken) +} + // getCachedRuntimeToken is kept as the prefetch seam used by runner tests. The // cache itself lives exclusively in TokenManager. func getCachedRuntimeToken(ctx context.Context) (string, error) { From 427d0cc1fca8ee021906f4efaa89bc4cf6237986 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Thu, 13 Aug 2026 15:00:00 +0800 Subject: [PATCH 061/250] docs: add international region release note --- .changes/global-dingtalk-region.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changes/global-dingtalk-region.md diff --git a/.changes/global-dingtalk-region.md b/.changes/global-dingtalk-region.md new file mode 100644 index 00000000..b488979d --- /dev/null +++ b/.changes/global-dingtalk-region.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **International DingTalk region support** — adds `.io` login and MCP routing, pre-release endpoint overrides, and profile-aware gateway selection while preserving the existing `.com` flow. From 75bd5184472167673f7cc1e8334e26161a1957ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=B7=E5=BF=83=E8=8F=9C?= Date: Thu, 13 Aug 2026 15:19:46 +0800 Subject: [PATCH 062/250] fix(drive): honor --type folder in --latest top-N and harden filter mutexes --- .changes/942-drive-list-pattern-fix.md | 5 ++++ internal/helpers/drive_depth.go | 3 ++- internal/helpers/drive_latest.go | 5 ++-- internal/helpers/drive_list_filter.go | 7 ++++-- internal/helpers/drive_list_filter_test.go | 23 +++++++++++++++++++ internal/helpers/pr868_coverage_gaps_test.go | 2 +- .../helpers/pr868_surfaces_coverage_test.go | 2 +- skills/mono/references/products/drive.md | 2 +- .../multi/dingtalk-drive/references/drive.md | 3 ++- 9 files changed, 43 insertions(+), 9 deletions(-) diff --git a/.changes/942-drive-list-pattern-fix.md b/.changes/942-drive-list-pattern-fix.md index 5115bd45..fe405c48 100644 --- a/.changes/942-drive-list-pattern-fix.md +++ b/.changes/942-drive-list-pattern-fix.md @@ -5,3 +5,8 @@ category: Fixed - **Drive list pattern filtering** (#942) — `dws drive list --pattern` on the single-layer pan route now filters the returned page by name pattern; the flag was previously accepted but silently ignored. + +- **Drive list `--type folder --latest` composition** (#942) — `--latest` now + ranks the filtered entries (folders included when `--type folder` is set) + instead of unconditionally dropping folders, so the documented combination + returns the most recently modified folders rather than an empty list. diff --git a/internal/helpers/drive_depth.go b/internal/helpers/drive_depth.go index b70a6c1f..09432f7c 100644 --- a/internal/helpers/drive_depth.go +++ b/internal/helpers/drive_depth.go @@ -370,7 +370,8 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca items = applyDriveListFilter(items, route, filter) } if latest > 0 { - items = applyDriveListLatest(items, latest) + // --type folder 时 latest 对过滤后的目录取 Top-N，避免「先留目录再剔目录」的空结果。 + items = applyDriveListLatest(items, latest, filter.nodeType == "folder") } else { // 排列为 rel_path 树序：BFS 只决定截断时哪些条目入选，树序决定呈现顺序。 sort.SliceStable(items, func(i, j int) bool { diff --git a/internal/helpers/drive_latest.go b/internal/helpers/drive_latest.go index 1668d216..db8b9541 100644 --- a/internal/helpers/drive_latest.go +++ b/internal/helpers/drive_latest.go @@ -49,10 +49,11 @@ func driveLatestExclusiveError(flag string, latest int) error { } } -func applyDriveListLatest(items []map[string]any, latest int) []map[string]any { +// foldersOnly=true 时对目录取 Top-N（--type folder --latest 组合），否则对文件取 Top-N。 +func applyDriveListLatest(items []map[string]any, latest int, foldersOnly bool) []map[string]any { files := make([]map[string]any, 0, len(items)) for _, item := range items { - if isDriveDepthFolder(item) || isDocDepthFolder(item) { + if (isDriveDepthFolder(item) || isDocDepthFolder(item)) != foldersOnly { continue } files = append(files, item) diff --git a/internal/helpers/drive_list_filter.go b/internal/helpers/drive_list_filter.go index f86bda84..292dea2b 100644 --- a/internal/helpers/drive_list_filter.go +++ b/internal/helpers/drive_list_filter.go @@ -85,8 +85,11 @@ func parseDriveListFilter(cmd *cobra.Command) (driveListFilter, error) { if cmd.Flags().Changed("versions") { return filter, driveListFilterExclusiveError("versions", "--versions 为独立的版本列表模式，请去掉 --versions 或过滤条件") } - if v := flagOrFallback(cmd, "cursor", "next-token", "page-token"); v != "" { - return filter, driveListFilterExclusiveError("cursor", "过滤模式为从头全量扫描，无连续游标；如需逐页翻页请去掉过滤条件") + // 用 Changed 判定而非值非空：显式 --cursor= 空值同样视为启用游标分页。 + for _, f := range []string{"cursor", "next-token", "page-token"} { + if fl := cmd.Flags().Lookup(f); fl != nil && fl.Changed { + return filter, driveListFilterExclusiveError("cursor", "过滤模式为从头全量扫描，无连续游标；如需逐页翻页请去掉过滤条件") + } } for _, f := range []string{"order-by", "order"} { if cmd.Flags().Changed(f) { diff --git a/internal/helpers/drive_list_filter_test.go b/internal/helpers/drive_list_filter_test.go index 6e56912d..8f4f3fb4 100644 --- a/internal/helpers/drive_list_filter_test.go +++ b/internal/helpers/drive_list_filter_test.go @@ -242,6 +242,7 @@ func TestCrossPlatformCoverageDriveListFilterPanStartWithLatest(t *testing.T) { func TestCrossPlatformCoverageDriveListFilterExclusiveFlags(t *testing.T) { cases := [][]string{ {"list", "--type", "file", "--cursor", "c1"}, + {"list", "--type", "file", "--cursor", ""}, {"list", "--type", "file", "--order-by", "name"}, {"list", "--start", "7d", "--order", "asc"}, {"list", "--type", "file", "--limit", "5"}, @@ -562,3 +563,25 @@ func TestCrossPlatformCoverageDriveListPatternPassthroughEdges(t *testing.T) { t.Fatalf("items = %#v", mixed) } } + +// 13. --type folder --latest 回归（P1 CR）：latest 对过滤后的目录按时间取 Top-N， +// 不再「先留目录再剔目录」返回空列表。 +func TestCrossPlatformCoverageDriveListFilterFolderLatest(t *testing.T) { + useDriveListArgs(t) + now := time.Now().UnixMilli() + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: fmt.Sprintf(`{"items":[ + {"fileId":"d1","name":"old-dir","type":"FOLDER","modifyTime":%d}, + {"fileId":"d2","name":"new-dir","type":"FOLDER","modifyTime":%d}, + {"fileId":"f1","name":"a.txt","type":"FILE","modifyTime":%d} + ]}`, now-5000, now, now)}, + }} + buf, err := executeDriveListCapture(t, caller, "list", "--type", "folder", "--latest", "1") + if err != nil { + t.Fatal(err) + } + items := decodeDepthResult(t, buf)["items"].([]any) + if len(items) != 1 || items[0].(map[string]any)["fileId"] != "d2" { + t.Fatalf("folder latest items = %#v", items) + } +} diff --git a/internal/helpers/pr868_coverage_gaps_test.go b/internal/helpers/pr868_coverage_gaps_test.go index 5b77a200..d9cf18b2 100644 --- a/internal/helpers/pr868_coverage_gaps_test.go +++ b/internal/helpers/pr868_coverage_gaps_test.go @@ -611,7 +611,7 @@ func TestCrossPlatformCoverageDriveLatestRemaining(t *testing.T) { {"name": "c", "sortTime": int64(5), "rel_path": "z", "fileId": "3", "type": "file"}, {"nodeType": "Folder", "name": "folder"}, } - got := applyDriveListLatest(items, 10) + got := applyDriveListLatest(items, 10, false) if len(got) != 3 { t.Fatalf("len=%d", len(got)) } diff --git a/internal/helpers/pr868_surfaces_coverage_test.go b/internal/helpers/pr868_surfaces_coverage_test.go index 1a2f86a5..5fc5d438 100644 --- a/internal/helpers/pr868_surfaces_coverage_test.go +++ b/internal/helpers/pr868_surfaces_coverage_test.go @@ -322,7 +322,7 @@ func TestCrossPlatformCoverageDriveLatestHelpers(t *testing.T) { {"name": "a.txt", "sortTime": int64(2), "rel_path": "a", "fileId": "1", "type": "file"}, {"name": "dir", "sortTime": int64(9), "type": "folder", "dentryType": "folder"}, } - got := applyDriveListLatest(items, 1) + got := applyDriveListLatest(items, 1, false) if len(got) != 1 { t.Fatalf("latest len=%d", len(got)) } diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 96fceca4..df7c666d 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -63,7 +63,7 @@ Flags: - 执行方式：钉盘与知识库（--workspace）两路由统一为**客户端过滤**——全量扫描当前目录后在进程内筛选； 与 `--depth>1` 组合时递归扫描后筛（被滤掉的条目仍占 2000 条全局上限）。 - 互斥：与 `--versions`/`--cursor`/`--order-by`/`--order`/`--limit` 不能同时使用（过滤模式为全量扫描， - 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`+--latest` 表示「符合条件的条目中最新 N 个」。 + 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`--latest` 表示「符合条件的条目中最新 N 个」。 - 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 - 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 21a7534d..486ef118 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -38,6 +38,7 @@ Flags: --order-by string 排序字段: createTime|modifyTime|name (可选) --folder string 父节点 ID (dentryUuid)，不传则列出空间根目录 (可选) --space-id string 空间 ID，不传则使用「我的文件」对应 spaceId (可选) + --workspace string 文档空间/知识库 ID (加密 string 或 URL)，传入则路由到文档空间 (可选) --thumbnail 是否返回缩略图信息 (可选) --pattern string 按名称通配过滤结果，如 "*日报*"（客户端过滤，无通配符时按子串匹配）(可选) --depth int 递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥 (可选) @@ -56,7 +57,7 @@ Flags: - 执行方式：钉盘与知识库（--workspace）两路由统一为**客户端过滤**——全量扫描当前目录后在进程内筛选； 与 `--depth>1` 组合时递归扫描后筛（被滤掉的条目仍占 2000 条全局上限）。 - 互斥：与 `--versions`/`--cursor`/`--order-by`/`--order`/`--limit` 不能同时使用（过滤模式为全量扫描， - 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`+--latest` 表示「符合条件的条目中最新 N 个」。 + 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`--latest` 表示「符合条件的条目中最新 N 个」。 - 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 - 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 From d525648b45266167b9cbf2b2ec682132b540ee6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 15:24:27 +0800 Subject: [PATCH 063/250] fix(chat): support read-status conversation aliases --- internal/helpers/chat.go | 1 + internal/helpers/chat_command_edges_test.go | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 99da3684..ebc94754 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -393,6 +393,7 @@ var chatPendingConversationIDMigrationPaths = [][]string{ {"group-role", "set-user"}, {"group-role", "update"}, {"message", "list-topic-replies"}, + {"message", "read-status"}, } var chatPendingMessageIDMigrationPaths = [][]string{ diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index b8553d05..797b5013 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -549,6 +549,26 @@ func TestCrossPlatformCoverageChatIMIDMigrationRequiredFlagErrors(t *testing.T) } } +func TestCrossPlatformCoverageChatMessageReadStatusConversationAliasesExecute(t *testing.T) { + for _, alias := range []string{"group", "id", "chat", "open-conversation-id"} { + t.Run(alias, func(t *testing.T) { + caller := &scriptedToolCaller{} + if err := runChatCoverageCommand(t, caller, "message", "read-status", "--"+alias, "cid-1", "--message-id", "msg-1"); err != nil { + t.Fatal(err) + } + if caller.server != "im" || caller.tool != "query_msg_read_status" { + t.Fatalf("call = %s/%s, want im/query_msg_read_status", caller.server, caller.tool) + } + if got := caller.args["openConversationId"]; got != "cid-1" { + t.Fatalf("openConversationId = %#v, want cid-1", got) + } + if got := caller.args["openMessageId"]; got != "msg-1" { + t.Fatalf("openMessageId = %#v, want msg-1", got) + } + }) + } +} + func TestCrossPlatformCoverageChatWebhookReplyConversationAndDownloadEdges(t *testing.T) { previousDeps, previousArgs := deps, os.Args os.Args = []string{"dws", "chat"} From 9eeb0681ff2f199984b85a4f17b736465174be17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 15:31:35 +0800 Subject: [PATCH 064/250] test(chat): cover list-all time defaults in platform gate --- internal/helpers/chat_command_edges_test.go | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index cadc2207..2c97ce06 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -160,6 +160,9 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) os.Args = []string{"dws", "chat"} t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs }) caller := &productExampleCaller{} + if got := formatChatMessageListAllTime(0); got == "" { + t.Fatal("formatChatMessageListAllTime returned empty string") + } commands := [][]string{ {"chmod", "chat.read", "--ttl="}, @@ -168,6 +171,10 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"message", "list", "--user=D-user", "--time=2026-01-01", "--limit=1"}, {"message", "list", "--open-dingtalk-id=D-user", "--time=2026-01-01", "--direction=sideways"}, {"message", "list-direct", "--user=D-user", "--limit=1"}, + {"message", "list-all"}, + {"message", "list-all", "--end=2026-01-02T00:00:00Z"}, + {"message", "list-all", "--end=bad"}, + {"message", "list-all", "--start=not-a-time", "--end=2026-01-02T00:00:00Z"}, {"message", "list-all", "--start=2026-01-01 00:00:00", "--end=bad"}, {"message", "list-all", "--start=2026-01-02 00:00:00", "--end=2026-01-01 00:00:00"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=bad"}, From 5ef52503aece1f2f27895cdff373f03bc9d80ef9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Thu, 13 Aug 2026 15:37:49 +0800 Subject: [PATCH 065/250] fix(recruit): align result and cursor contracts --- internal/app/schema_recruit_contract_test.go | 62 ++++++++ internal/helpers/recruit.go | 141 +++++++++++++---- internal/helpers/recruit_test.go | 153 +++++++++++++++++-- 3 files changed, 314 insertions(+), 42 deletions(-) create mode 100644 internal/app/schema_recruit_contract_test.go diff --git a/internal/app/schema_recruit_contract_test.go b/internal/app/schema_recruit_contract_test.go new file mode 100644 index 00000000..6c6c4a2c --- /dev/null +++ b/internal/app/schema_recruit_contract_test.go @@ -0,0 +1,62 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package app + +import ( + "bytes" + "encoding/json" + "reflect" + "testing" +) + +func recruitSchemaLeaf(t *testing.T, canonical string, compact bool) map[string]any { + t.Helper() + root := NewRootCommand() + var stdout, stderr bytes.Buffer + root.SetOut(&stdout) + root.SetErr(&stderr) + args := []string{"schema", canonical, "--format", "json"} + if compact { + args = append(args, "--compact") + } + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatalf("execute schema %s compact=%v: %v; stderr=%s", canonical, compact, err, stderr.String()) + } + var payload map[string]any + if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil { + t.Fatalf("decode schema %s compact=%v: %v", canonical, compact, err) + } + return payload +} + +func TestRecruitDeliveredSchemaPublishesResultAndPagination(t *testing.T) { + for _, canonical := range []string{"recruit.list_jobs", "recruit.get_job_detail", "recruit.create_job"} { + t.Run(canonical, func(t *testing.T) { + full := recruitSchemaLeaf(t, canonical, false) + compact := recruitSchemaLeaf(t, canonical, true) + if full["result"] == nil || compact["result"] == nil { + t.Fatalf("result missing: full=%#v compact=%#v", full["result"], compact["result"]) + } + if !reflect.DeepEqual(full["result"], compact["result"]) { + t.Fatalf("full/compact result mismatch\nfull=%#v\ncompact=%#v", full["result"], compact["result"]) + } + if canonical == "recruit.list_jobs" { + if full["pagination"] == nil || compact["pagination"] == nil { + t.Fatalf("list pagination missing: full=%#v compact=%#v", full["pagination"], compact["pagination"]) + } + if !reflect.DeepEqual(full["pagination"], compact["pagination"]) { + t.Fatalf("full/compact pagination mismatch\nfull=%#v\ncompact=%#v", full["pagination"], compact["pagination"]) + } + parameters, _ := full["parameters"].(map[string]any) + cursor, _ := parameters["cursor"].(map[string]any) + if cursor["type"] != "string" || cursor["interface_type"] != "number" { + t.Fatalf("cursor contract = %#v, want CLI string converted to MCP number", cursor) + } + } else if full["pagination"] != nil || compact["pagination"] != nil { + t.Fatalf("non-list pagination must be absent: full=%#v compact=%#v", full["pagination"], compact["pagination"]) + } + }) + } +} diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index c2756305..73997371 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -7,12 +7,14 @@ import ( "encoding/json" "fmt" "os" + "strconv" "strings" "github.com/spf13/cobra" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" ) const ( @@ -30,7 +32,7 @@ var recruitDryRun = &contract.DryRunSpec{ var ( recruitListResult = &contract.ResultSpec{ Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, - DataSchema: json.RawMessage(`{"type":"object","description":"当前页招聘职位查询结果","properties":{"jobs":{"type":"array","description":"当前页职位记录","items":{"type":"object","description":"招聘职位摘要","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}},"hasMore":{"type":"boolean","description":"服务端是否还有下一页"},"nextCursor":{"description":"下一页游标；仅在 hasMore 为 true 时用于续查","oneOf":[{"type":"number"},{"type":"string"}]}},"additionalProperties":true}`), + DataSchema: json.RawMessage(`{"type":"object","description":"当前页招聘职位查询结果；续页信息位于 meta.pagination","properties":{"jobs":{"type":"array","description":"当前页职位记录","items":{"type":"object","description":"招聘职位摘要","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}}},"additionalProperties":true}`), } recruitJobDetailResult = &contract.ResultSpec{ Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, @@ -78,13 +80,14 @@ func newRecruitCommand() *cobra.Command { func newRecruitJobListCommand() *cobra.Command { return NewLeafCommand(LeafSpec{ - Use: "list", - Short: "查询招聘职位列表", - Long: "按职位 ID、关键词、状态、创建人、职位性质等条件分页查询招聘职位。", - Example: " dws recruit job list --keyword Java --status open --size 20 --format json\n dws recruit job list --job-ids JOB_ID_1,JOB_ID_2 --format json", - Server: recruitServerID, - Tool: recruitListJobsTool, - Safety: recruitSafetyRead(), + Use: "list", + Short: "查询招聘职位列表", + Long: "按职位 ID、关键词、状态、创建人、职位性质等条件分页查询招聘职位。", + Example: " dws recruit job list --keyword Java --status open --size 20 --format json\n dws recruit job list --job-ids JOB_ID_1,JOB_ID_2 --format json", + Server: recruitServerID, + Tool: recruitListJobsTool, + Safety: recruitSafetyRead(), + OutputRollout: output.RolloutUnifiedActive, Flags: []LeafFlag{ {Name: "job-ids", Usage: "职位 ID，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "jobIds"}, {Name: "required-edu", Usage: "学历要求枚举值", Kind: LeafInt, Bind: "requiredEdu"}, @@ -96,11 +99,11 @@ func newRecruitJobListCommand() *cobra.Command { {Name: "creator-user-ids", Usage: "创建人 userId，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "creatorUserIds"}, {Name: "keyword", Usage: "职位搜索关键词", Bind: "keyword", Trim: true, OmitEmpty: true}, {Name: "category", Usage: "职位分类", Bind: "category", Trim: true, OmitEmpty: true}, - {Name: "cursor", Usage: "分页游标；首次查询不传，翻页时传返回的 nextCursor", Kind: LeafInt, Bind: "cursor"}, + {Name: "cursor", Usage: "分页游标；首次查询不传，翻页时原样回填返回的 nextCursor", Bind: "cursor", Trim: true, OmitEmpty: true, Transform: transformRecruitCursor}, {Name: "size", Usage: "分页大小，默认 20", Kind: LeafInt, Bind: "size", ArgDefault: "20"}, }, - Validate: validateRecruitList, - Call: runRecruitJobList, + Validate: validateRecruitList, + ResultCall: recruitResultCall, Contract: LeafContract{ Identity: contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitListJobsTool, CanonicalPath: "recruit.list_jobs", CLIPath: "recruit job list", PrimaryCLIPath: "recruit job list"}, Description: "按条件分页查询招聘职位", @@ -119,7 +122,7 @@ func newRecruitJobListCommand() *cobra.Command { }) } -func runRecruitJobList(_ *cobra.Command, tool string, args map[string]any) error { +func recruitListToolArgs(args map[string]any) map[string]any { params := map[string]any{"param": map[string]any{}, "size": args["size"]} query := params["param"].(map[string]any) for key, value := range args { @@ -131,18 +134,88 @@ func runRecruitJobList(_ *cobra.Command, tool string, args map[string]any) error query[key] = value } } - return callMCPToolOnServer(recruitServerID, tool, params) + return params +} + +func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (output.CommandResult, error) { + toolArgs := args + if tool == recruitListJobsTool { + toolArgs = recruitListToolArgs(args) + } + if deps.Caller.DryRun() { + return output.Success(map[string]any{ + "tool": tool, "arguments": toolArgs, "executed": false, + }, output.WithDryRun()), nil + } + data, err := CallMCPToolDataOnServer(cmd.Context(), recruitServerID, tool, toolArgs) + if err != nil { + return nil, err + } + if tool != recruitListJobsTool { + return output.Success(data), nil + } + clean, meta, err := recruitListResultData(data) + if err != nil { + return output.Failure(&output.ErrorInfo{ + Type: "api", Subtype: "pagination_inconsistent", Message: err.Error(), + Hint: "保留原始响应并停止翻页；不要把当前页当作完整结果。", + }), nil + } + return output.Success(clean, output.WithMeta(meta)), nil +} + +func recruitListResultData(data any) (any, *output.Meta, error) { + object, ok := data.(map[string]any) + if !ok { + return nil, nil, fmt.Errorf("list_jobs 返回值必须是 JSON 对象") + } + hasMore, ok := object["hasMore"].(bool) + if !ok { + return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore") + } + nextToken := "" + if raw, exists := object["nextCursor"]; exists && raw != nil { + switch value := raw.(type) { + case string: + nextToken = strings.TrimSpace(value) + case float64: + nextToken = strconv.FormatFloat(value, 'f', -1, 64) + default: + return nil, nil, fmt.Errorf("list_jobs 的 nextCursor 必须是字符串或数字") + } + } + if hasMore && nextToken == "" { + return nil, nil, fmt.Errorf("list_jobs 返回 hasMore=true 但缺少 nextCursor") + } + if !hasMore { + nextToken = "" + } + clean := make(map[string]any, len(object)-2) + for key, value := range object { + if key != "hasMore" && key != "nextCursor" { + clean[key] = value + } + } + pagination := &output.Pagination{EndpointExhausted: !hasMore, NextToken: nextToken, Pages: 1} + meta := &output.Meta{Pagination: pagination} + if jobs, exists := clean["jobs"].([]any); exists { + meta.Count = output.NewCount(len(jobs)) + pagination.Items = len(jobs) + } + return clean, meta, nil } func newRecruitJobGetCommand() *cobra.Command { return NewLeafCommand(LeafSpec{ - Use: "get", - Short: "查询招聘职位详情", - Long: "根据职位 ID 查询招聘职位详情。", - Example: " dws recruit job get --job-id JOB_ID --format json", - Server: recruitServerID, - Tool: recruitGetJobTool, - Safety: recruitSafetyRead(), + Use: "get", + Short: "查询招聘职位详情", + Long: "根据职位 ID 查询招聘职位详情。", + Example: " dws recruit job get --job-id JOB_ID --format json", + Server: recruitServerID, + Tool: recruitGetJobTool, + Safety: recruitSafetyRead(), + OutputRollout: output.RolloutUnifiedActive, + ResultCall: recruitResultCall, Flags: []LeafFlag{{ Name: "job-id", Usage: "职位 ID（必填）", Bind: "jobId", Trim: true, Required: true, RequiredHint: "--job-id 为必填", @@ -166,13 +239,15 @@ func newRecruitJobGetCommand() *cobra.Command { func newRecruitJobCreateCommand() *cobra.Command { return NewLeafCommand(LeafSpec{ - Use: "create", - Short: "创建招聘职位", - Long: "从 JSON 文件读取职位信息并创建招聘职位。该操作会写入远端招聘系统，执行前必须确认。", - Example: " dws recruit job create --from ./job.json --dry-run --format json\n dws recruit job create --from ./job.json --format json", - Server: recruitServerID, - Tool: recruitCreateJobTool, - Safety: recruitSafetyCreate(), + Use: "create", + Short: "创建招聘职位", + Long: "从 JSON 文件读取职位信息并创建招聘职位。该操作会写入远端招聘系统，执行前必须确认。", + Example: " dws recruit job create --from ./job.json --dry-run --format json\n dws recruit job create --from ./job.json --format json", + Server: recruitServerID, + Tool: recruitCreateJobTool, + Safety: recruitSafetyCreate(), + OutputRollout: output.RolloutUnifiedActive, + ResultCall: recruitResultCall, Flags: []LeafFlag{{ Name: "from", Usage: "职位 JSON 文件路径（必填）", Bind: "atsAddJobParam", Trim: true, Required: true, RequiredHint: "--from 为必填", Transform: loadRecruitJobFile, @@ -249,10 +324,16 @@ func transformRecruitStatuses(raw string) (any, error) { return statuses, nil } -func validateRecruitList(cmd *cobra.Command, _ []string) error { - if cursor, _ := cmd.Flags().GetInt("cursor"); cursor < 0 { - return apperrors.NewValidation("--cursor 必须大于或等于 0") +func transformRecruitCursor(raw string) (any, error) { + value := strings.TrimSpace(raw) + cursor, err := strconv.ParseInt(value, 10, 64) + if err != nil || cursor < 0 { + return nil, apperrors.NewValidation("--cursor 必须是大于或等于 0 的整数") } + return cursor, nil +} + +func validateRecruitList(cmd *cobra.Command, _ []string) error { size, _ := cmd.Flags().GetInt("size") if cmd.Flags().Changed("size") && (size < 1 || size > 100) { return apperrors.NewValidation("--size 必须在 1 到 100 之间") diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 77f319ba..bfcb3936 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -14,9 +14,12 @@ import ( "strings" "testing" + "github.com/spf13/cobra" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) @@ -31,6 +34,9 @@ type recruitCaptureCaller struct { tool string args map[string]any calls []recruitCapturedCall + err error + text string + dryRun bool } func (c *recruitCaptureCaller) CallTool(_ context.Context, productID, tool string, args map[string]any) (*edition.ToolResult, error) { @@ -38,11 +44,24 @@ func (c *recruitCaptureCaller) CallTool(_ context.Context, productID, tool strin c.tool = tool c.args = args c.calls = append(c.calls, recruitCapturedCall{productID: productID, tool: tool, args: args}) - return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{}`}}}, nil + if c.err != nil { + return nil, c.err + } + text := c.text + if text == "" { + text = `{}` + switch tool { + case recruitListJobsTool: + text = `{"jobs":[],"hasMore":false}` + case recruitCreateJobTool: + text = `{"jobId":"created-job"}` + } + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil } func (c *recruitCaptureCaller) Format() string { return "json" } -func (c *recruitCaptureCaller) DryRun() bool { return false } +func (c *recruitCaptureCaller) DryRun() bool { return c.dryRun } func (c *recruitCaptureCaller) Fields() string { return "" } func (c *recruitCaptureCaller) JQ() string { return "" } @@ -54,9 +73,15 @@ func withRecruitCaller(t *testing.T) *recruitCaptureCaller { return caller } +func prepareRecruitTestCommand(cmd *cobra.Command) *cobra.Command { + ctx, _ := output.WithResultStore(context.Background()) + cmd.SetContext(ctx) + return cmd +} + func TestRecruitJobListWrapsQueryParameters(t *testing.T) { caller := withRecruitCaller(t) - cmd := newRecruitJobListCommand() + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) cmd.SetArgs([]string{ "--keyword", "Java", "--status", "open,draft", "--creator-user-ids", "u1,u2", "--campus=false", "--cursor", "10", "--size", "30", @@ -67,7 +92,7 @@ func TestRecruitJobListWrapsQueryParameters(t *testing.T) { if caller.productID != recruitServerID || caller.tool != recruitListJobsTool { t.Fatalf("dispatch = %s/%s, want %s/%s", caller.productID, caller.tool, recruitServerID, recruitListJobsTool) } - if caller.args["cursor"] != 10 || caller.args["size"] != 30 { + if caller.args["cursor"] != int64(10) || caller.args["size"] != 30 { t.Fatalf("pagination args = %#v", caller.args) } param, ok := caller.args["param"].(map[string]any) @@ -87,9 +112,29 @@ func TestRecruitJobListWrapsQueryParameters(t *testing.T) { } } +func TestRecruitJobListCursorRoundTrip(t *testing.T) { + caller := withRecruitCaller(t) + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + cmd.SetArgs([]string{"--cursor", "9223372036854775807"}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if got := caller.args["cursor"]; got != int64(9223372036854775807) { + t.Fatalf("cursor = %#v (%T), want max int64", got, got) + } + + for _, cursor := range []string{"not-a-cursor", "9223372036854775808"} { + invalid := prepareRecruitTestCommand(newRecruitJobListCommand()) + invalid.SetArgs([]string{"--cursor", cursor}) + if err := invalid.Execute(); err == nil || !strings.Contains(err.Error(), "大于或等于 0 的整数") { + t.Fatalf("cursor %q error = %v", cursor, err) + } + } +} + func TestRecruitJobListDefaultsAndValidation(t *testing.T) { caller := withRecruitCaller(t) - cmd := newRecruitJobListCommand() + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) if err := cmd.Execute(); err != nil { t.Fatal(err) } @@ -100,13 +145,13 @@ func TestRecruitJobListDefaultsAndValidation(t *testing.T) { t.Fatalf("first page unexpectedly sent cursor: %#v", caller.args) } - badStatus := newRecruitJobListCommand() + badStatus := prepareRecruitTestCommand(newRecruitJobListCommand()) badStatus.SetArgs([]string{"--status", "unknown"}) if err := badStatus.Execute(); err == nil || !strings.Contains(err.Error(), "draft/open/invalid/closed") { t.Fatalf("invalid status error = %v", err) } - badSize := newRecruitJobListCommand() + badSize := prepareRecruitTestCommand(newRecruitJobListCommand()) badSize.SetArgs([]string{"--size", "101"}) if err := badSize.Execute(); err == nil || !strings.Contains(err.Error(), "1 到 100") { t.Fatalf("invalid size error = %v", err) @@ -115,7 +160,7 @@ func TestRecruitJobListDefaultsAndValidation(t *testing.T) { func TestRecruitJobGetDispatchesJobID(t *testing.T) { caller := withRecruitCaller(t) - cmd := newRecruitJobGetCommand() + cmd := prepareRecruitTestCommand(newRecruitJobGetCommand()) cmd.SetArgs([]string{"--job-id", "job-1"}) if err := cmd.Execute(); err != nil { t.Fatal(err) @@ -145,7 +190,7 @@ func writeRecruitJobFixture(t *testing.T) (string, map[string]any) { func TestRecruitJobCreateRequiresConfirmationBeforeRemoteCall(t *testing.T) { caller := withRecruitCaller(t) path, _ := writeRecruitJobFixture(t) - cmd := newRecruitJobCreateCommand() + cmd := prepareRecruitTestCommand(newRecruitJobCreateCommand()) cmd.Flags().Bool("yes", false, "确认创建") cmd.SetIn(strings.NewReader("")) cmd.SetArgs([]string{"--from", path}) @@ -162,7 +207,7 @@ func TestRecruitJobCreateRequiresConfirmationBeforeRemoteCall(t *testing.T) { func TestRecruitJobCreateCallsRemoteOnceWhenConfirmed(t *testing.T) { caller := withRecruitCaller(t) path, _ := writeRecruitJobFixture(t) - cmd := newRecruitJobCreateCommand() + cmd := prepareRecruitTestCommand(newRecruitJobCreateCommand()) cmd.Flags().Bool("yes", false, "确认创建") cmd.SetArgs([]string{"--from", path, "--yes"}) if err := cmd.Execute(); err != nil { @@ -190,7 +235,7 @@ func TestRecruitCreateValidatesJobFile(t *testing.T) { if err := os.WriteFile(badPath, []byte(`{"name":"缺字段"}`), 0o600); err != nil { t.Fatal(err) } - bad := newRecruitJobCreateCommand() + bad := prepareRecruitTestCommand(newRecruitJobCreateCommand()) bad.Flags().Bool("yes", false, "确认创建") bad.SetArgs([]string{"--from", badPath, "--yes"}) if err := bad.Execute(); err == nil || !strings.Contains(err.Error(), "description") { @@ -204,7 +249,7 @@ func TestRecruitValidationBranches(t *testing.T) { t.Fatalf("statuses = %#v, err = %v", statuses, err) } - negativeCursor := newRecruitJobListCommand() + negativeCursor := prepareRecruitTestCommand(newRecruitJobListCommand()) negativeCursor.SetArgs([]string{"--cursor", "-1"}) if err := negativeCursor.Execute(); err == nil || !strings.Contains(err.Error(), "大于或等于 0") { t.Fatalf("negative cursor error = %v", err) @@ -217,6 +262,16 @@ func TestRecruitValidationBranches(t *testing.T) { if _, err := loadRecruitJobFile(nullPath); err == nil || !strings.Contains(err.Error(), "顶层必须是对象") { t.Fatalf("null job error = %v", err) } + if _, err := loadRecruitJobFile(filepath.Join(t.TempDir(), "missing.json")); err == nil || !strings.Contains(err.Error(), "读取职位 JSON 失败") { + t.Fatalf("missing job file error = %v", err) + } + invalidPath := filepath.Join(t.TempDir(), "invalid.json") + if err := os.WriteFile(invalidPath, []byte("{"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := loadRecruitJobFile(invalidPath); err == nil || !strings.Contains(err.Error(), "不是有效的 JSON 对象") { + t.Fatalf("invalid job JSON error = %v", err) + } base := map[string]any{ "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", @@ -244,6 +299,80 @@ func TestRecruitValidationBranches(t *testing.T) { } } +func TestRecruitListResultData(t *testing.T) { + for _, test := range []struct { + name string + data any + want string + }{ + {name: "not object", data: []any{}, want: "必须是 JSON 对象"}, + {name: "missing hasMore", data: map[string]any{}, want: "缺少布尔字段 hasMore"}, + {name: "invalid cursor", data: map[string]any{"hasMore": true, "nextCursor": true}, want: "必须是字符串或数字"}, + {name: "missing cursor", data: map[string]any{"hasMore": true}, want: "缺少 nextCursor"}, + } { + t.Run(test.name, func(t *testing.T) { + if _, _, err := recruitListResultData(test.data); err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("error = %v, want %q", err, test.want) + } + }) + } + + data, meta, err := recruitListResultData(map[string]any{ + "jobs": []any{map[string]any{"jobId": "job-1"}}, "hasMore": true, "nextCursor": float64(12), + }) + if err != nil { + t.Fatal(err) + } + if meta.Count == nil || *meta.Count != 1 || meta.Pagination.EndpointExhausted || + meta.Pagination.NextToken != "12" || meta.Pagination.Pages != 1 || meta.Pagination.Items != 1 { + t.Fatalf("meta = %#v", meta) + } + clean := data.(map[string]any) + if _, exists := clean["hasMore"]; exists || clean["jobs"] == nil { + t.Fatalf("clean data = %#v", clean) + } + + _, terminal, err := recruitListResultData(map[string]any{"jobs": []any{}, "hasMore": false, "nextCursor": "ignored"}) + if err != nil || !terminal.Pagination.EndpointExhausted || terminal.Pagination.NextToken != "" { + t.Fatalf("terminal meta = %#v, err = %v", terminal, err) + } +} + +func TestRecruitResultCallPropagatesMCPError(t *testing.T) { + caller := withRecruitCaller(t) + caller.err = stderrors.New("transport failed") + cmd := prepareRecruitTestCommand(newRecruitJobGetCommand()) + if _, err := recruitResultCall(cmd, recruitGetJobTool, map[string]any{"jobId": "job-1"}); err == nil { + t.Fatal("expected MCP error") + } +} + +func TestRecruitResultCallRejectsInconsistentPagination(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = `{"jobs":[],"hasMore":true}` + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + result, err := recruitResultCall(cmd, recruitListJobsTool, map[string]any{"size": 20}) + if err != nil { + t.Fatal(err) + } + if result.Outcome() != output.OutcomeFailure { + t.Fatalf("outcome = %s, want failure", result.Outcome()) + } +} + +func TestRecruitResultCallDryRun(t *testing.T) { + caller := withRecruitCaller(t) + caller.dryRun = true + cmd := prepareRecruitTestCommand(newRecruitJobGetCommand()) + result, err := recruitResultCall(cmd, recruitGetJobTool, map[string]any{"jobId": "job-1"}) + if err != nil { + t.Fatal(err) + } + if result.Outcome() != output.OutcomeSuccess || len(caller.calls) != 0 { + t.Fatalf("outcome = %s, calls = %d", result.Outcome(), len(caller.calls)) + } +} + func TestRecruitCommandTree(t *testing.T) { root := newRecruitCommand() for _, path := range [][]string{{"job", "list"}, {"job", "get"}, {"job", "create"}} { From 8c00068364b999d2f56dd619edaeb999c624b406 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 15:49:59 +0800 Subject: [PATCH 066/250] fix(drive): harden folder mirror safety --- internal/helpers/drive.go | 19 + internal/helpers/drive_folder_contract.go | 146 +++ .../helpers/drive_folder_contract_test.go | 182 ++++ .../drive_mirror_coverage_gaps_test.go | 163 ++++ .../helpers/drive_mirror_preflight_test.go | 376 +++++++ internal/helpers/drive_pull.go | 739 ++++++++++++-- internal/helpers/drive_pull_coverage_test.go | 39 +- .../helpers/drive_pull_plan_coverage_test.go | 507 ++++++++++ internal/helpers/drive_pull_test.go | 40 +- internal/helpers/drive_pull_times_unix.go | 16 + internal/helpers/drive_pull_times_windows.go | 16 + internal/helpers/drive_pull_toctou_test.go | 915 ++++++++++++++++++ internal/helpers/drive_push.go | 395 +++++++- internal/helpers/drive_push_coverage_test.go | 41 +- .../drive_push_sync_final_coverage_test.go | 632 ++++++++++++ internal/helpers/drive_push_test.go | 105 +- internal/helpers/drive_push_toctou_test.go | 136 +++ .../helpers/drive_push_type_conflict_test.go | 6 +- .../helpers/drive_remote_duplicate_test.go | 8 +- .../helpers/drive_remote_folder_id_test.go | 14 +- .../drive_remote_tree_integrity_test.go | 309 ++++++ .../helpers/drive_remote_unsafe_name_test.go | 4 +- internal/helpers/drive_status.go | 104 +- .../helpers/drive_status_coverage_test.go | 34 +- internal/helpers/drive_status_windows.go | 40 +- internal/helpers/drive_sync.go | 255 +++-- .../helpers/drive_sync_confirmation_test.go | 50 +- internal/helpers/drive_sync_conflict_test.go | 99 +- internal/helpers/drive_sync_coverage_test.go | 13 +- internal/helpers/drive_sync_edges_test.go | 53 +- internal/helpers/drive_sync_gaps_test.go | 20 +- internal/helpers/drive_sync_platform_test.go | 19 +- internal/helpers/drive_sync_test.go | 90 +- .../helpers/drive_sync_type_conflict_test.go | 4 +- skills/mono/references/products/drive.md | 15 +- .../multi/dingtalk-drive/references/drive.md | 15 +- 36 files changed, 5067 insertions(+), 552 deletions(-) create mode 100644 internal/helpers/drive_folder_contract.go create mode 100644 internal/helpers/drive_folder_contract_test.go create mode 100644 internal/helpers/drive_mirror_coverage_gaps_test.go create mode 100644 internal/helpers/drive_mirror_preflight_test.go create mode 100644 internal/helpers/drive_pull_plan_coverage_test.go create mode 100644 internal/helpers/drive_pull_times_unix.go create mode 100644 internal/helpers/drive_pull_times_windows.go create mode 100644 internal/helpers/drive_pull_toctou_test.go create mode 100644 internal/helpers/drive_push_sync_final_coverage_test.go create mode 100644 internal/helpers/drive_push_toctou_test.go create mode 100644 internal/helpers/drive_remote_tree_integrity_test.go diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index b5455fb6..e01197ed 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -3405,6 +3405,7 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 PrimaryCLIPath: "drive status", }, Description: "比较本地文件夹与钉盘文件夹的差异，只读不落盘。", + Result: driveFolderStatusResultSpec(), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -3439,6 +3440,11 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 PrimaryCLIPath: "drive pull", }, Description: "把钉盘文件夹单向镜像到本地；写操作需确认，默认跳过本地既有文件。", + DryRun: &contract.DryRunSpec{ + PreviewKind: contract.DryRunPreviewPlan, + RemoteReads: true, + }, + Result: driveFolderPullResultSpec(), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -3452,6 +3458,7 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 "dws drive pull --local-folder /abs/path/repo --remote-folder ", "dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart --dry-run", }, + ExampleDispositions: driveFolderStatefulExampleDispositions(), }, Parameters: []contract.ParamDecl{ {Name: "local-folder", Required: boolPtr(true)}, @@ -3473,6 +3480,11 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 PrimaryCLIPath: "drive push", }, Description: "把本地文件夹单向镜像到钉盘；写操作需确认，默认跳过远端既有文件。", + DryRun: &contract.DryRunSpec{ + PreviewKind: contract.DryRunPreviewPlan, + RemoteReads: true, + }, + Result: driveFolderPushResultSpec(), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -3486,6 +3498,7 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 "dws drive push --local-folder /abs/path/repo --remote-folder ", "dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --dry-run", }, + ExampleDispositions: driveFolderStatefulExampleDispositions(), }, Parameters: []contract.ParamDecl{ {Name: "local-folder", Required: boolPtr(true)}, @@ -3507,6 +3520,11 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 PrimaryCLIPath: "drive sync", }, Description: "本地与钉盘文件夹双向同步；写操作需确认，默认跳过双端冲突。", + DryRun: &contract.DryRunSpec{ + PreviewKind: contract.DryRunPreviewPlan, + RemoteReads: true, + }, + Result: driveFolderSyncResultSpec(), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -3520,6 +3538,7 @@ skipped/failed）、diff 与逐条 items；有失败则以非零退出码退出 "dws drive sync --local-folder /abs/path/repo --remote-folder ", "dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict remote-wins --dry-run", }, + ExampleDispositions: driveFolderStatefulExampleDispositions(), }, Parameters: []contract.ParamDecl{ {Name: "local-folder", Required: boolPtr(true)}, diff --git a/internal/helpers/drive_folder_contract.go b/internal/helpers/drive_folder_contract.go new file mode 100644 index 00000000..624db528 --- /dev/null +++ b/internal/helpers/drive_folder_contract.go @@ -0,0 +1,146 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package helpers + +import ( + "encoding/json" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" +) + +// driveFolderStatefulExampleDispositions 明确记录文件夹镜像示例为什么只做契约校验： +// 预览必须读取用户指定的本地目录与真实钉盘目录，无法在隔离的 Agent 示例环境中伪造。 +// DryRun 能力仍由 ContractFinal 正式发布，命令级测试负责执行并验证零写入预览。 +func driveFolderStatefulExampleDispositions() []contract.ExampleDisposition { + first, second := 0, 1 + return []contract.ExampleDisposition{ + { + Index: &first, + Mode: contract.ExampleDispositionModeContractOnly, + ReasonCode: contract.ExampleDispositionReasonStatefulPreflight, + Reason: "预览需要读取用户指定的真实钉盘目录和本地文件系统状态", + Reviewed: true, + }, + { + Index: &second, + Mode: contract.ExampleDispositionModeContractOnly, + ReasonCode: contract.ExampleDispositionReasonStatefulPreflight, + Reason: "预览需要读取用户指定的真实钉盘目录和本地文件系统状态", + Reviewed: true, + }, + } +} + +func driveFolderStatusResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"本地文件夹与钉盘文件夹的差异", + "properties":{ + "detection":{"type":"string","description":"差异检测模式","enum":["exact","quick"]}, + "new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}, + "new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}, + "modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}, + "unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}, + "unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}} + }, + "required":["detection","new_local","new_remote","modified","unchanged","unknown"], + "additionalProperties":false +}`), + } +} + +func driveFolderPullResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomePartialFailure, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"钉盘文件夹拉取的执行结果或预览计划", + "properties":{ + "summary":{"type":"object","description":"真实执行的动作计数","properties":{"downloaded":{"type":"integer","description":"成功下载的文件数"},"skipped":{"type":"integer","description":"按策略跳过的文件数"},"failed":{"type":"integer","description":"失败的文件数"}},"required":["downloaded","skipped","failed"],"additionalProperties":false}, + "items":{"type":"array","description":"真实执行的逐文件结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"},"action":{"type":"string","description":"执行动作"},"error":{"type":"string","description":"失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}, + "dry_run":{"type":"boolean","description":"是否为只读预览"}, + "executed":{"type":"boolean","description":"是否执行了写操作"}, + "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]}, + "operation":{"type":"string","description":"预览的命令"}, + "if_exists":{"type":"string","description":"本地同名文件处理策略"}, + "plan":{"type":"object","description":"预览的拉取计划","properties":{"summary":{"type":"object","description":"计划动作计数","properties":{"downloaded":{"type":"integer","description":"计划下载的文件数"},"skipped":{"type":"integer","description":"计划跳过的文件数"},"failed":{"type":"integer","description":"预检失败的文件数"}},"required":["downloaded","skipped","failed"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐文件动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"},"action":{"type":"string","description":"计划动作"},"error":{"type":"string","description":"预检失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["summary","items"],"additionalProperties":false} + }, + "additionalProperties":false +}`), + } +} + +func driveFolderPushResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomePartialFailure, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"本地文件夹推送的执行结果或预览计划", + "properties":{ + "summary":{"type":"object","description":"真实执行的动作计数","properties":{"uploaded":{"type":"integer","description":"成功上传或覆盖的文件数"},"skipped":{"type":"integer","description":"按策略跳过的文件数"},"failed":{"type":"integer","description":"失败的条目数"},"aborted":{"type":"boolean","description":"是否因失败中止后续上传"}},"required":["uploaded","skipped","failed","aborted"],"additionalProperties":false}, + "items":{"type":"array","description":"真实执行的逐条目结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"执行动作"},"size_bytes":{"type":"integer","description":"文件字节数"},"error":{"type":"string","description":"失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}, + "dry_run":{"type":"boolean","description":"是否为只读预览"}, + "executed":{"type":"boolean","description":"是否执行了写操作"}, + "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]}, + "operation":{"type":"string","description":"预览的命令"}, + "if_exists":{"type":"string","description":"远端同名文件处理策略"}, + "plan":{"type":"object","description":"预览的推送计划","properties":{"summary":{"type":"object","description":"计划动作计数","properties":{"uploaded":{"type":"integer","description":"计划上传或覆盖的文件数"},"skipped":{"type":"integer","description":"计划跳过的文件数"},"failed":{"type":"integer","description":"预检失败的条目数"},"aborted":{"type":"boolean","description":"计划是否会中止"}},"required":["uploaded","skipped","failed","aborted"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐条目动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"计划动作"},"size_bytes":{"type":"integer","description":"文件字节数"},"error":{"type":"string","description":"预检失败原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["summary","items"],"additionalProperties":false} + }, + "additionalProperties":false +}`), + } +} + +func driveFolderSyncResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomePartialFailure, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"本地与钉盘双向同步的执行结果或预览计划", + "properties":{ + "detection":{"type":"string","description":"差异检测模式","enum":["exact","quick"]}, + "diff":{"type":"object","description":"同步前的双端差异","properties":{"new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}},"required":["new_local","new_remote","modified","unchanged","unknown"],"additionalProperties":false}, + "summary":{"type":"object","description":"真实执行的动作计数","properties":{"pulled":{"type":"integer","description":"成功拉取的条目数"},"pushed":{"type":"integer","description":"成功推送的条目数"},"skipped":{"type":"integer","description":"跳过的条目数"},"failed":{"type":"integer","description":"失败的条目数"}},"required":["pulled","pushed","skipped","failed"],"additionalProperties":false}, + "items":{"type":"array","description":"真实执行的逐条目结果","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"执行动作"},"direction":{"type":"string","description":"同步方向"},"error":{"type":"string","description":"失败或跳过原因"}},"required":["rel_path","action"],"additionalProperties":false}}, + "dry_run":{"type":"boolean","description":"是否为只读预览","const":true}, + "executed":{"type":"boolean","description":"是否执行了写操作","const":false}, + "preview_kind":{"type":"string","description":"预览类型","enum":["plan"]}, + "operation":{"type":"string","description":"预览的命令","const":"drive sync"}, + "plan":{"type":"object","description":"预览的同步计划","properties":{"detection":{"type":"string","description":"计划使用的差异检测模式","enum":["exact","quick"]},"diff":{"type":"object","description":"计划执行前的双端差异","properties":{"new_local":{"type":"array","description":"仅本地存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"new_remote":{"type":"array","description":"仅钉盘存在的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"modified":{"type":"array","description":"双端都存在但内容或时间不同的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unchanged":{"type":"array","description":"双端一致的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}},"unknown":{"type":"array","description":"exact 模式下因缺少可靠远端哈希而无法判定的文件","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件路径"}},"required":["rel_path"],"additionalProperties":false}}},"required":["new_local","new_remote","modified","unchanged","unknown"],"additionalProperties":false},"summary":{"type":"object","description":"计划动作计数","properties":{"pulled":{"type":"integer","description":"计划拉取的条目数"},"pushed":{"type":"integer","description":"计划推送的条目数"},"skipped":{"type":"integer","description":"计划跳过的条目数"},"failed":{"type":"integer","description":"预检失败的条目数"}},"required":["pulled","pushed","skipped","failed"],"additionalProperties":false},"items":{"type":"array","description":"计划中的逐条目动作","items":{"type":"object","properties":{"rel_path":{"type":"string","description":"相对文件或目录路径"},"action":{"type":"string","description":"计划动作"},"direction":{"type":"string","description":"同步方向"},"error":{"type":"string","description":"失败或跳过原因"}},"required":["rel_path","action"],"additionalProperties":false}}},"required":["detection","diff","summary","items"],"additionalProperties":false} + }, + "oneOf":[ + {"required":["detection","diff","summary","items"]}, + {"required":["dry_run","executed","preview_kind","operation","plan"]} + ], + "additionalProperties":false +}`), + } +} diff --git a/internal/helpers/drive_folder_contract_test.go b/internal/helpers/drive_folder_contract_test.go new file mode 100644 index 00000000..6495708d --- /dev/null +++ b/internal/helpers/drive_folder_contract_test.go @@ -0,0 +1,182 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package helpers + +import ( + "encoding/json" + "reflect" + "sort" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal" +) + +func TestCrossPlatformCoverageDriveFolderContractsPublishResultAndDryRun(t *testing.T) { + drive := newDriveCommand() + want := map[string]struct { + canonical string + dryRun bool + outcomes []contract.ResultOutcome + properties []string + }{ + "status": { + canonical: "drive.folder_status", + outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + properties: []string{"detection", "modified", "new_local", "new_remote", "unchanged", "unknown"}, + }, + "pull": { + canonical: "drive.folder_pull", + dryRun: true, + outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure}, + properties: []string{"dry_run", "executed", "if_exists", "items", "operation", "plan", "preview_kind", "summary"}, + }, + "push": { + canonical: "drive.folder_push", + dryRun: true, + outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure}, + properties: []string{"dry_run", "executed", "if_exists", "items", "operation", "plan", "preview_kind", "summary"}, + }, + "sync": { + canonical: "drive.folder_sync", + dryRun: true, + outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomePartialFailure, contract.ResultOutcomeFailure}, + properties: []string{"detection", "diff", "dry_run", "executed", "items", "operation", "plan", "preview_kind", "summary"}, + }, + } + + for name, expectation := range want { + t.Run(name, func(t *testing.T) { + leaf, _, err := drive.Find([]string{name}) + if err != nil || leaf == nil { + t.Fatalf("find drive %s: command=%v err=%v", name, leaf, err) + } + final, ok := contractfinal.RuntimeContractFinal(leaf) + if !ok || final.Identity == nil || final.Identity.CanonicalPath != expectation.canonical { + t.Fatalf("drive %s ContractFinal identity = %#v", name, final.Identity) + } + if final.Result == nil || !reflect.DeepEqual(final.Result.Outcomes, expectation.outcomes) { + t.Fatalf("drive %s result = %#v, want outcomes %#v", name, final.Result, expectation.outcomes) + } + properties := resultSchemaProperties(t, final.Result.DataSchema) + if got := sortedContractSchemaKeys(properties); !reflect.DeepEqual(got, expectation.properties) { + t.Fatalf("drive %s result properties = %#v, want %#v", name, got, expectation.properties) + } + if expectation.dryRun { + if final.DryRun == nil || final.DryRun.PreviewKind != contract.DryRunPreviewPlan || !final.DryRun.RemoteReads { + t.Fatalf("drive %s dry_run = %#v, want remote-reading plan", name, final.DryRun) + } + if final.Selection == nil || len(final.Selection.ExampleDispositions) != len(final.Selection.Examples) { + t.Fatalf("drive %s stateful example dispositions = %#v", name, final.Selection) + } + for _, disposition := range final.Selection.ExampleDispositions { + if disposition.Mode != contract.ExampleDispositionModeContractOnly || + disposition.ReasonCode != contract.ExampleDispositionReasonStatefulPreflight || !disposition.Reviewed { + t.Fatalf("drive %s invalid example disposition: %#v", name, disposition) + } + } + } else if final.DryRun != nil { + t.Fatalf("drive %s unexpectedly publishes dry_run: %#v", name, final.DryRun) + } + + if name == "sync" { + assertDriveSyncResultSchema(t, final.Result.DataSchema) + } + }) + } +} + +func resultSchemaProperties(t *testing.T, raw json.RawMessage) map[string]any { + t.Helper() + var schema map[string]any + if err := json.Unmarshal(raw, &schema); err != nil { + t.Fatalf("result data_schema is not JSON: %v\n%s", err, raw) + } + properties, ok := schema["properties"].(map[string]any) + if !ok { + t.Fatalf("result data_schema.properties = %#v, want object", schema["properties"]) + } + return properties +} + +func sortedContractSchemaKeys(values map[string]any) []string { + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + sort.Strings(keys) + return keys +} + +func assertDriveSyncResultSchema(t *testing.T, raw json.RawMessage) { + t.Helper() + properties := resultSchemaProperties(t, raw) + diff := schemaObjectProperty(t, properties, "diff") + assertSchemaRequired(t, diff, "new_local", "new_remote", "modified", "unchanged", "unknown") + if got := sortedContractSchemaKeys(schemaProperties(t, diff)); !reflect.DeepEqual(got, []string{"modified", "new_local", "new_remote", "unchanged", "unknown"}) { + t.Fatalf("sync diff properties = %#v", got) + } + + plan := schemaObjectProperty(t, properties, "plan") + assertSchemaRequired(t, plan, "detection", "diff", "summary", "items") + planProperties := schemaProperties(t, plan) + planDiff := schemaObjectProperty(t, planProperties, "diff") + assertSchemaRequired(t, planDiff, "new_local", "new_remote", "modified", "unchanged", "unknown") + + var schema map[string]any + if err := json.Unmarshal(raw, &schema); err != nil { + t.Fatal(err) + } + oneOf, ok := schema["oneOf"].([]any) + if !ok || len(oneOf) != 2 { + t.Fatalf("sync result oneOf = %#v, want execution/dry-run alternatives", schema["oneOf"]) + } +} + +func schemaObjectProperty(t *testing.T, properties map[string]any, name string) map[string]any { + t.Helper() + property, ok := properties[name].(map[string]any) + if !ok || property["type"] != "object" { + t.Fatalf("schema property %s = %#v, want object", name, properties[name]) + } + return property +} + +func schemaProperties(t *testing.T, schema map[string]any) map[string]any { + t.Helper() + properties, ok := schema["properties"].(map[string]any) + if !ok { + t.Fatalf("schema properties = %#v, want object", schema["properties"]) + } + return properties +} + +func assertSchemaRequired(t *testing.T, schema map[string]any, want ...string) { + t.Helper() + raw, ok := schema["required"].([]any) + if !ok { + t.Fatalf("schema required = %#v", schema["required"]) + } + got := make([]string, 0, len(raw)) + for _, value := range raw { + text, ok := value.(string) + if !ok { + t.Fatalf("schema required value = %#v, want string", value) + } + got = append(got, text) + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("schema required = %#v, want %#v", got, want) + } +} diff --git a/internal/helpers/drive_mirror_coverage_gaps_test.go b/internal/helpers/drive_mirror_coverage_gaps_test.go new file mode 100644 index 00000000..bfcb5c3e --- /dev/null +++ b/internal/helpers/drive_mirror_coverage_gaps_test.go @@ -0,0 +1,163 @@ +package helpers + +import ( + "context" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +// TestCrossPlatformCoverageDriveMirrorCoverageGaps 覆盖镜像整批 preflight 引入的 +// 输出失败和防御式解析分支。测试只调用命名 helper，不依赖真实 Drive 或网络。 +func TestCrossPlatformCoverageDriveMirrorCoverageGaps(t *testing.T) { + t.Run("preflight output failures", func(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, "a.txt"), "local") + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`, + }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + pull := findDriveSubcommand(t, "pull") + mustSetFlags(t, pull, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDrivePull(pull, nil); err == nil || !strings.Contains(err.Error(), "write failed") { + t.Fatalf("pull preflight output error = %v", err) + } + + push := findDriveSubcommand(t, "push") + mustSetFlags(t, push, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDrivePush(push, nil); err == nil || !strings.Contains(err.Error(), "write failed") { + t.Fatalf("push preflight output error = %v", err) + } + + sync := findDriveSubcommand(t, "sync") + mustSetFlags(t, sync, map[string]string{"local-folder": root, "remote-folder": "ROOT", "quick": "true"}) + if err := runDriveSync(sync, nil); err == nil || !strings.Contains(err.Error(), "write failed") { + t.Fatalf("sync preflight output error = %v", err) + } + }) + + t.Run("pull remote-only preflight output failure", func(t *testing.T) { + root := t.TempDir() + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`, + }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + pull := findDriveSubcommand(t, "pull") + mustSetFlags(t, pull, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDrivePull(pull, nil); err == nil || !strings.Contains(err.Error(), "write failed") { + t.Fatalf("pull remote-only preflight output error = %v", err) + } + }) + + t.Run("dry run preflight output failures", func(t *testing.T) { + root := t.TempDir() + remote := map[string]*remoteFile{"A.txt": {RelPath: "A.txt"}, "a.txt": {RelPath: "a.txt"}} + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: failingWriter{}}}) + if err := printDrivePullDryRun(root, ifExistsSkip, remote, []string{"A.txt", "a.txt"}, true); err == nil { + t.Fatal("pull dry-run preflight must propagate output failure") + } + local := []localPushFile{{RelPath: "a.txt"}} + if err := printDrivePushDryRun(ifExistsSkip, + map[string]*remoteFile{"A.txt": {RelPath: "A.txt"}}, map[string]string{"": "ROOT"}, nil, local); err == nil { + t.Fatal("push dry-run preflight must propagate output failure") + } + }) + + t.Run("parser errors", func(t *testing.T) { + for _, body := range []string{ + `{"result":`, + `{"result":{"items":[],"hasMore":"bad"}}`, + `{"result":{"items":null}}`, + `{"result":{"items":"bad"}}`, + `{"result":[`, + `{"result":[true]}`, + `{"result":[{}]}`, + `{"result":true}`, + } { + if _, _, err := parseDriveList(body); err == nil { + t.Errorf("parseDriveList(%q) unexpectedly succeeded", body) + } + } + }) + + t.Run("pull dry-run existing-file policies", func(t *testing.T) { + root := t.TempDir() + skipPath := filepath.Join(root, "skip.txt") + smartPath := filepath.Join(root, "smart.txt") + mustWrite(t, skipPath, "skip") + mustWrite(t, smartPath, "smart") + smartMTime := readFileMTimeMillis(t, smartPath) + remote := map[string]*remoteFile{ + "skip.txt": {RelPath: "skip.txt"}, + "smart.txt": {RelPath: "smart.txt", ModifiedTime: smartMTime - 1, ModifiedTimeValid: true}, + } + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: io.Discard}}) + if err := printDrivePullDryRunWithPreflight(root, ifExistsSkip, remote, []string{"skip.txt"}, false, nil); err != nil { + t.Fatal(err) + } + if err := printDrivePullDryRunWithPreflight(root, ifExistsSmart, remote, []string{"smart.txt"}, false, nil); err != nil { + t.Fatal(err) + } + remote["smart.txt"] = &remoteFile{RelPath: "smart.txt"} + if err := printDrivePullDryRunWithPreflight(root, ifExistsSmart, remote, []string{"smart.txt"}, false, nil); err != nil { + t.Fatal(err) + } + }) + + t.Run("pull mkdir and replace errors", func(t *testing.T) { + root := t.TempDir() + caller := pullListingCaller("") + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + testseam.Swap(t, &pullMkdirAll, func(string, os.FileMode) error { return errTestDownload }) + if action, err := pullOneFile(context.Background(), "", &remoteFile{FileID: "F"}, + filepath.Join(root, "blocked", "x.txt"), ifExistsOverwrite); action != pullActionFailed || err == nil { + t.Fatalf("mkdir failure = (%q, %v)", action, err) + } + + targetDir := t.TempDir() + mustWrite(t, filepath.Join(targetDir, "target.txt"), "local") + testseam.Swap(t, &pullMkdirAll, os.MkdirAll) + testseam.Swap(t, &pullRename, func(*os.Root, string, string) error { return errTestDownload }) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { + return os.WriteFile(dest, []byte("remote"), 0o644) + }) + if action, err := pullOneFile(context.Background(), "", &remoteFile{FileID: "F"}, + filepath.Join(targetDir, "target.txt"), ifExistsOverwrite); action != pullActionFailed || err == nil { + t.Fatalf("replace failure = (%q, %v)", action, err) + } + }) + + t.Run("sync pull defensive failures", func(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + res := &driveSyncResult{} + syncPullFile(res, context.Background(), "", &remoteFile{FileID: "F"}, root, "sub/a.txt", syncDirectionPull) + if res.Summary.Failed != 1 { + t.Fatalf("escape failed = %d", res.Summary.Failed) + } + }) + + t.Run("pull remote file rechecks symlink escape", func(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Symlink(outside, filepath.Join(root, "sub")); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + action, err := pullRemoteFile(context.Background(), "", &remoteFile{FileID: "F"}, root, + "sub/a.txt", ifExistsOverwrite) + if action != pullActionFailed || err == nil { + t.Fatalf("pull remote TOCTOU guard = (%q, %v)", action, err) + } + }) +} diff --git a/internal/helpers/drive_mirror_preflight_test.go b/internal/helpers/drive_mirror_preflight_test.go new file mode 100644 index 00000000..b2abc561 --- /dev/null +++ b/internal/helpers/drive_mirror_preflight_test.go @@ -0,0 +1,376 @@ +package helpers + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" + "github.com/spf13/cobra" +) + +func runDriveMirrorCommand(t *testing.T, caller *driveScriptCaller, dryRun bool, args ...string) ([]byte, error) { + t.Helper() + caller.dryRun = dryRun + var out bytes.Buffer + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + full := append(append([]string{}, args...), "--yes") + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...)) + root.SetArgs(append([]string{"drive"}, full...)) + err := root.Execute() + return append([]byte(nil), out.Bytes()...), err +} + +func captureMirrorHTTP(t *testing.T) (getCalls, putCalls *int) { + t.Helper() + gets, puts := 0, 0 + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { + gets++ + return nil + }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + puts++ + return nil + }) + return &gets, &puts +} + +func assertMirrorPreflightNoWrites(t *testing.T, caller *driveScriptCaller, getCalls, putCalls int) { + t.Helper() + for _, tool := range []string{"create_folder", "download_file", "get_upload_info", "commit_upload"} { + if calls := caller.callsFor(tool); len(calls) != 0 { + t.Errorf("mirror preflight must not call %s: %v", tool, calls) + } + } + if getCalls != 0 || putCalls != 0 { + t.Errorf("mirror preflight must not transfer content: GET=%d PUT=%d", getCalls, putCalls) + } +} + +func TestCrossPlatformCoverageDrivePull_nonRegularTargetFailsBeforeDownload(t *testing.T) { + for _, dryRun := range []bool{false, true} { + name := "execute" + if dryRun { + name = "dry-run" + } + t.Run(name, func(t *testing.T) { + root := t.TempDir() + if err := os.Mkdir(filepath.Join(root, "blocked.txt"), 0o755); err != nil { + t.Fatal(err) + } + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"blocked.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`, + }) + gets, puts := captureMirrorHTTP(t) + out, err := runDriveMirrorCommand(t, caller, dryRun, "pull", "--local-folder", root, "--remote-folder", "ROOT") + if dryRun { + if err != nil { + t.Fatalf("pull dry-run: %v", err) + } + var got drivePullDryRunResult + if jsonErr := json.Unmarshal(out, &got); jsonErr != nil { + t.Fatalf("pull dry-run output is not JSON: %v\n%s", jsonErr, out) + } + if got.Plan.Summary.Failed != 1 || len(got.Plan.Items) != 1 || !strings.Contains(got.Plan.Items[0].Error, "不是常规文件") { + t.Fatalf("pull dry-run plan = %+v, want one non-regular target failure", got.Plan) + } + } else { + var failure *drivePartialFailure + if !errors.As(err, &failure) || failure.failed != 1 { + t.Fatalf("pull error = %v, want one failed item", err) + } + } + assertMirrorPreflightNoWrites(t, caller, *gets, *puts) + }) + } +} + +func TestCrossPlatformCoverageDrivePull_nonRegularTargetAbortsWholeBatchBeforeDownload(t *testing.T) { + for _, command := range []string{"pull", "sync"} { + for _, dryRun := range []bool{false, true} { + name := command + "/execute" + if dryRun { + name = command + "/dry-run" + } + t.Run(name, func(t *testing.T) { + root := t.TempDir() + if err := os.Mkdir(filepath.Join(root, "z-blocked.txt"), 0o755); err != nil { + t.Fatal(err) + } + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a-first.txt","type":"file","fileId":"FIRST"},{"name":"z-blocked.txt","type":"file","fileId":"BLOCKED"}],"nextToken":""}}`, + }) + gets, puts := captureMirrorHTTP(t) + args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + out, err := runDriveMirrorCommand(t, caller, dryRun, args...) + if dryRun { + if err != nil { + t.Fatalf("%s dry-run: %v", command, err) + } + if command == "pull" { + var got drivePullDryRunResult + if jsonErr := json.Unmarshal(out, &got); jsonErr != nil || got.Plan.Summary.Failed != 2 { + t.Fatalf("pull dry-run preflight = %+v, json error %v", got, jsonErr) + } + } else { + assertMirrorDryRunFailureJSON(t, command, out) + } + } else if err == nil { + t.Fatalf("%s must abort the whole batch", command) + } + if _, statErr := os.Stat(filepath.Join(root, "a-first.txt")); !os.IsNotExist(statErr) { + t.Fatalf("%s wrote an earlier file before discovering the conflict: %v", command, statErr) + } + assertMirrorPreflightNoWrites(t, caller, *gets, *puts) + }) + } + } +} + +func TestCrossPlatformCoverageDrivePull_remoteEquivalentTreeFailsBeforeDownload(t *testing.T) { + tests := []struct { + name string + listings map[string]string + wantFail int + }{ + { + name: "equivalent files", + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`, + }, + wantFail: 2, + }, + { + name: "equivalent folder prefixes", + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"Folder","type":"folder","fileId":"UP_DIR"},{"name":"folder","type":"folder","fileId":"LOW_DIR"}],"nextToken":""}}`, + "UP_DIR": `{"result":{"items":[{"name":"up.txt","type":"file","fileId":"UP"}],"nextToken":""}}`, + "LOW_DIR": `{"result":{"items":[{"name":"low.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`, + }, + wantFail: 2, + }, + } + for _, tt := range tests { + for _, dryRun := range []bool{false, true} { + name := tt.name + "/execute" + if dryRun { + name = tt.name + "/dry-run" + } + t.Run(name, func(t *testing.T) { + root := t.TempDir() + caller := syncCaller(tt.listings) + gets, puts := captureMirrorHTTP(t) + out, err := runDriveMirrorCommand(t, caller, dryRun, "pull", "--local-folder", root, "--remote-folder", "ROOT") + if dryRun { + if err != nil { + t.Fatalf("pull dry-run: %v", err) + } + var got drivePullDryRunResult + if jsonErr := json.Unmarshal(out, &got); jsonErr != nil { + t.Fatalf("pull dry-run output is not JSON: %v\n%s", jsonErr, out) + } + if got.Plan.Summary.Failed != tt.wantFail || got.Plan.Summary.Downloaded != 0 { + t.Fatalf("pull dry-run plan = %+v", got.Plan) + } + } else { + var failure *drivePartialFailure + if !errors.As(err, &failure) || failure.failed != tt.wantFail { + t.Fatalf("pull error = %v, want %d failed items", err, tt.wantFail) + } + } + if !strings.Contains(string(out), "等价路径") { + t.Fatalf("pull output must explain equivalent path ambiguity: %s", out) + } + assertMirrorPreflightNoWrites(t, caller, *gets, *puts) + }) + } + } +} + +func TestCrossPlatformCoverageDriveMirror_unsafeLocalNamesFailClosed(t *testing.T) { + if os.PathSeparator == '\\' { + t.Skip("current platform cannot create a local name containing a backslash") + } + for _, command := range []string{"push", "sync"} { + for _, dryRun := range []bool{false, true} { + name := command + "/execute" + if dryRun { + name = command + "/dry-run" + } + t.Run(name, func(t *testing.T) { + root := t.TempDir() + mustWrite(t, filepath.Join(root, `unsafe\name.txt`), "local") + caller := syncCaller(nil) + gets, puts := captureMirrorHTTP(t) + args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + out, err := runDriveMirrorCommand(t, caller, dryRun, args...) + if dryRun { + if err != nil { + t.Fatalf("%s dry-run: %v", command, err) + } + assertMirrorDryRunFailureJSON(t, command, out) + } else if err == nil { + t.Fatalf("%s must fail an unsafe local name", command) + } + if !strings.Contains(string(out), "无法安全映射到远端") { + t.Fatalf("%s output must explain unsafe local name: %s", command, out) + } + assertMirrorPreflightNoWrites(t, caller, *gets, *puts) + }) + } + } + + // NUL 不能由真实文件系统创建，直接覆盖契约 helper，避免该分支成为死角。 + preflight := buildMirrorPreflight(nil, []localPushFile{{RelPath: "bad\x00name.txt"}}, nil, map[string]string{"": "ROOT"}) + if !strings.Contains(preflight["bad\x00name.txt"], "无法安全映射到远端") { + t.Fatalf("NUL name preflight = %v", preflight) + } + if err := rejectNonRegularLocalTarget("bad\x00target"); err == nil || !strings.Contains(err.Error(), "检查本地目标失败") { + t.Fatalf("invalid local target error = %v", err) + } + + localCollision := buildMirrorPreflight(nil, []localPushFile{{RelPath: "A.txt"}, {RelPath: "a.txt"}}, nil, map[string]string{"": "ROOT"}) + for _, rel := range []string{"A.txt", "a.txt"} { + if !strings.Contains(localCollision[rel], "等价路径") { + t.Fatalf("local equivalent collision %q = %q", rel, localCollision[rel]) + } + } + prefixCollision := buildMirrorPreflight(nil, []localPushFile{{RelPath: "A/x.txt"}}, + map[string]*remoteFile{"a/y.txt": {RelPath: "a/y.txt"}}, map[string]string{"": "ROOT"}) + for _, rel := range []string{"A", "a"} { + if !strings.Contains(prefixCollision[rel], "等价路径") { + t.Fatalf("equivalent ancestor collision %q = %q", rel, prefixCollision[rel]) + } + } +} + +func TestCrossPlatformCoverageDriveMirror_crossSideEquivalentPathsFailBeforeWrites(t *testing.T) { + tests := []struct { + name string + prepare func(*testing.T, string) + listings map[string]string + }{ + { + name: "case-equivalent files", + prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "a.txt"), "local") }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`, + }, + }, + { + name: "case-equivalent folder prefixes", + prepare: func(t *testing.T, root string) { + mustWrite(t, filepath.Join(root, "Folder", "local.txt"), "local") + }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"folder","type":"folder","fileId":"REMOTE_DIR"}],"nextToken":""}}`, + "REMOTE_DIR": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"REMOTE_FILE"}],"nextToken":""}}`, + }, + }, + { + name: "unicode-equivalent files", + prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "caf\u00e9.txt"), "local") }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"cafe\u0301.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}`, + }, + }, + { + name: "equivalent path type ambiguity", + prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "item"), "local") }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"ITEM","type":"folder","fileId":"REMOTE_DIR"}],"nextToken":""}}`, + "REMOTE_DIR": `{"result":{"items":[],"nextToken":""}}`, + }, + }, + { + name: "remote-only equivalent files", + prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "safe-local.txt"), "local") }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"A.txt","type":"file","fileId":"UP"},{"name":"a.txt","type":"file","fileId":"LOW"}],"nextToken":""}}`, + }, + }, + { + name: "remote-only equivalent folders", + prepare: func(t *testing.T, root string) { mustWrite(t, filepath.Join(root, "safe-local.txt"), "local") }, + listings: map[string]string{ + "ROOT": `{"result":{"items":[{"name":"Folder","type":"folder","fileId":"UP_DIR"},{"name":"folder","type":"folder","fileId":"LOW_DIR"}],"nextToken":""}}`, + "UP_DIR": `{"result":{"items":[],"nextToken":""}}`, + "LOW_DIR": `{"result":{"items":[],"nextToken":""}}`, + }, + }, + } + + for _, tt := range tests { + for _, command := range []string{"push", "sync"} { + for _, dryRun := range []bool{false, true} { + name := tt.name + "/" + command + "/execute" + if dryRun { + name = tt.name + "/" + command + "/dry-run" + } + t.Run(name, func(t *testing.T) { + root := t.TempDir() + tt.prepare(t, root) + caller := syncCaller(tt.listings) + gets, puts := captureMirrorHTTP(t) + args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + out, err := runDriveMirrorCommand(t, caller, dryRun, args...) + if dryRun { + if err != nil { + t.Fatalf("%s dry-run: %v", command, err) + } + assertMirrorDryRunFailureJSON(t, command, out) + } else if err == nil { + t.Fatalf("%s must reject an equivalent cross-side path", command) + } + if !strings.Contains(string(out), "等价路径") { + t.Fatalf("%s output must explain equivalent path ambiguity: %s", command, out) + } + assertMirrorPreflightNoWrites(t, caller, *gets, *puts) + }) + } + } + } +} + +func assertMirrorDryRunFailureJSON(t *testing.T, command string, out []byte) { + t.Helper() + switch command { + case "push": + var got drivePushDryRunResult + if err := json.Unmarshal(out, &got); err != nil { + t.Fatalf("push dry-run output is not JSON: %v\n%s", err, out) + } + if !got.DryRun || got.Executed || got.Operation != "drive push" || got.Plan.Summary.Failed == 0 || !got.Plan.Summary.Aborted { + t.Fatalf("push dry-run result = %+v", got) + } + case "sync": + var got driveSyncDryRunResult + if err := json.Unmarshal(out, &got); err != nil { + t.Fatalf("sync dry-run output is not standalone JSON: %v\n%s", err, out) + } + if !got.DryRun || got.Executed || got.PreviewKind != "plan" || got.Operation != "drive sync" || got.Plan.Summary.Failed == 0 { + t.Fatalf("sync dry-run result = %+v", got) + } + default: + t.Fatalf("unsupported command %q", command) + } +} diff --git a/internal/helpers/drive_pull.go b/internal/helpers/drive_pull.go index c894d7f3..d8802d5e 100644 --- a/internal/helpers/drive_pull.go +++ b/internal/helpers/drive_pull.go @@ -3,6 +3,8 @@ package helpers import ( "context" "fmt" + "io" + "net/http" "os" "path/filepath" "runtime" @@ -10,6 +12,7 @@ import ( "strings" "time" + "github.com/google/uuid" "github.com/spf13/cobra" "golang.org/x/text/unicode/norm" ) @@ -33,9 +36,37 @@ const ( ifExistsSkip = "skip" // 默认：本地已存在则保持不动 ) -// pullCreateTemp 仅作为文件系统失败分支的确定性测试 seam；测试必须通过 -// testseam.Swap 替换并自动恢复。 -var pullCreateTemp = os.CreateTemp +// pull 下载路径使用 os.Root 固定根目录和目标父目录。以下 seam 只用于 +// 确定性覆盖文件系统与传输失败分支；测试必须通过 testseam.Swap 替换。 +var ( + pullMkdirAll = os.MkdirAll + pullOpenRoot = os.OpenRoot + pullRelPath = filepath.Rel + pullPathStat = os.Stat + pullPathLstat = os.Lstat + pullTargetLstat = os.Lstat + pullRootMkdir = func(root *os.Root, name string, mode os.FileMode) error { + return root.Mkdir(name, mode) + } + pullOpenParentRoot = func(root *os.Root, name string) (*os.Root, error) { + return root.OpenRoot(name) + } + pullRootStat = func(root *os.Root, name string) (os.FileInfo, error) { return root.Stat(name) } + pullRootLstat = func(root *os.Root, name string) (os.FileInfo, error) { return root.Lstat(name) } + pullCreateTemp = createPinnedPullTemp + pullTempName = uuid.NewString + pullSyncTemp = func(file *os.File) error { return file.Sync() } + pullCloseTemp = func(file *os.File) error { return file.Close() } + pullRename = func(root *os.Root, oldName, newName string) error { + return root.Rename(oldName, newName) + } + pullLink = func(root *os.Root, oldName, newName string) error { return root.Link(oldName, newName) } + pullRemove = func(root *os.Root, name string) error { return root.Remove(name) } + pullDownloadFile = defaultPullDownloadFile + pullHTTPDo = func(request *http.Request) (*http.Response, error) { + return (&http.Client{Timeout: 10 * time.Minute}).Do(request) + } +) // pull 动作分类。 const ( @@ -169,6 +200,13 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { if err != nil { return err } + // 在任何远端读取之前固定本地根计划：既有根立即持有 os.Root；不存在的根只固定 + // 最近既存祖先并记录尚缺的逐层后缀。远端清单不完整或预检失败时不得创建本地根。 + rootPlan, err := planPinnedPullRoot(absDir) + if err != nil { + return err + } + defer rootPlan.close() ctx := cmd.Context() // 复用 status 的远端遍历：按 parentId 递归拿到所有 type=FILE 的文件（key 为 rel_path）。 @@ -183,41 +221,34 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { relPaths = append(relPaths, rel) } sort.Strings(relPaths) + preflight, localInfo, err := buildDrivePullPreflightFromPlan(rootPlan, remote) + if err != nil { + return err + } if deps.Caller.DryRun() { - caseInsensitive := runtime.GOOS == "windows" || runtime.GOOS == "darwin" - return printDrivePullDryRun(absDir, ifExists, remote, relPaths, caseInsensitive) + return printDrivePullDryRunWithLocalInfo(ifExists, remote, relPaths, preflight, localInfo) } - - // 落盘前先按目标文件系统的路径等价规则做一次全局冲突检查：大小写不敏感 FS 上 - // A.txt 与 a.txt（或 NFC/NFD 异写）会落到同一本地文件；overwrite 会顺序覆盖、 - // 却把两项都报 downloaded 而静默丢文件。冲突的条目一律标记 failed、都不写入。 - // 探针需要根目录存在，这里按 pull「自动创建目标根」的语义先建好。 - if err := os.MkdirAll(absDir, 0o755); err != nil { - return fmt.Errorf("创建本地目录失败: %w", err) + // 镜像契约独立于当前主机文件系统：远端 A/a 或 NFC/NFD 异写（包括目录 + // 前缀）在任何落盘前整批拒绝，避免同一远端树在不同平台得到不同镜像。 + if len(preflight) > 0 { + res := drivePullPreflightFailureResult(relPaths, preflight) + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr + } + return &drivePartialFailure{failed: res.Summary.Failed} } - collided := detectTargetCollisions(absDir, relPaths, isCaseInsensitiveFS(absDir)) + pinnedRoot, err := rootPlan.materialize() + if err != nil { + return err + } + defer pinnedRoot.close() res := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} for _, rel := range relPaths { rf := remote[rel] - // 多个远端条目映射到同一本地目标 → 全部 failed，不写入任何一个，避免静默覆盖丢文件。 - if collided[rel] { - res.Summary.Failed++ - res.Items = append(res.Items, drivePullItem{ - RelPath: rel, Action: pullActionFailed, - Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", - }) - continue - } - // 二次确认下载目标仍在本地根目录内，逃逸路径记为 failed 而非落盘。 - localPath, terr := resolveLocalTarget(absDir, rel) - if terr != nil { - res.Summary.Failed++ - res.Items = append(res.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: terr.Error()}) - continue - } - - action, perr := pullOneFile(ctx, spaceID, rf, localPath, ifExists) + // preflight 与真正下载之间仍需二次解析，挡住祖先目录被并发替换为软链的 + // TOCTOU 逃逸；pullRemoteFile 将该检查收口在写入入口前。 + action, perr := pullRemoteFilePinned(ctx, spaceID, rf, pinnedRoot, rel, ifExists) item := drivePullItem{RelPath: rel, Action: action} switch action { case pullActionDownloaded: @@ -244,25 +275,37 @@ func runDrivePull(cmd *cobra.Command, _ []string) error { } func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool) error { - plan := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} - collided := detectTargetCollisions(absDir, relPaths, caseInsensitive) + return printDrivePullDryRunWithPreflight(absDir, ifExists, remote, relPaths, caseInsensitive, + buildDrivePullPreflight(absDir, remote)) +} + +func printDrivePullDryRunWithPreflight(absDir, ifExists string, remote map[string]*remoteFile, relPaths []string, caseInsensitive bool, preflight map[string]string) error { + localInfo := make(map[string]os.FileInfo, len(relPaths)) for _, rel := range relPaths { - if collided[rel] { - plan.Summary.Failed++ - plan.Items = append(plan.Items, drivePullItem{ - RelPath: rel, Action: pullActionFailed, - Error: "多个远端条目在目标平台默认文件系统上映射到同一本地路径，计划已拒绝", - }) - continue - } localPath, err := resolveLocalTarget(absDir, rel) if err != nil { - plan.Summary.Failed++ - plan.Items = append(plan.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: err.Error()}) continue } + if info, statErr := os.Stat(localPath); statErr == nil && info.Mode().IsRegular() { + localInfo[rel] = info + } + } + _ = caseInsensitive // 保留 helper 的平台预览参数兼容性。 + return printDrivePullDryRunWithLocalInfo(ifExists, remote, relPaths, preflight, localInfo) +} + +func printDrivePullDryRunWithLocalInfo(ifExists string, remote map[string]*remoteFile, relPaths []string, preflight map[string]string, localInfo map[string]os.FileInfo) error { + plan := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} + if len(preflight) > 0 { + plan = drivePullPreflightFailureResult(relPaths, preflight) + return deps.Out.PrintJSON(drivePullDryRunResult{ + DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive pull", + IfExists: ifExists, Plan: plan, + }) + } + for _, rel := range relPaths { action := pullActionDownloaded - if fi, statErr := os.Stat(localPath); statErr == nil && fi.Mode().IsRegular() { + if fi := localInfo[rel]; fi != nil { switch ifExists { case ifExistsSkip: action = pullActionSkipped @@ -286,18 +329,130 @@ func printDrivePullDryRun(absDir, ifExists string, remote map[string]*remoteFile }) } +// buildDrivePullPreflight 在创建本地根目录、探测文件系统或下载任一文件之前， +// 一次性验证完整远端树及每个本地落盘目标。任一目标是目录、符号链接、设备文件， +// 或经既有符号链接逃逸时，整批 pull 都必须零写入中止。 +func buildDrivePullPreflight(absDir string, remote map[string]*remoteFile) map[string]string { + failures := buildMirrorPreflight(nil, nil, remote, nil) + addLocalTargetPreflightFailures(absDir, remote, failures) + return failures +} + +// buildDrivePullPreflightFromPlan 只从 list_files 前已固定的根计划读取本地状态。 +// existing 根不再按 absDir 重开路径；missing 根在 ancestor Root 下仍必须完整缺失。 +func buildDrivePullPreflightFromPlan(plan *pinnedPullRootPlan, remote map[string]*remoteFile) (map[string]string, map[string]os.FileInfo, error) { + failures := buildMirrorPreflight(nil, nil, remote, nil) + localInfo := make(map[string]os.FileInfo, len(remote)) + if err := plan.verify(); err != nil { + return nil, nil, err + } + if plan.existing != nil { + addPinnedLocalTargetPreflightFailures(plan.existing, remote, failures) + for rel := range remote { + if mirrorPreflightFailureForRel(rel, failures) != "" { + continue + } + info, err := pullRootLstat(plan.existing.root, filepath.FromSlash(rel)) + if err == nil && info.Mode().IsRegular() { + localInfo[rel] = info + } + } + } + if err := plan.verify(); err != nil { + return nil, nil, err + } + return failures, localInfo, nil +} + +func addLocalTargetPreflightFailures(absDir string, remote map[string]*remoteFile, failures map[string]string) { + for rel := range remote { + // 已被名称/类型冲突根屏蔽的后代不重复计错；一个冲突根只报告一次。 + if mirrorPreflightFailureForRel(rel, failures) != "" { + continue + } + localPath, err := resolveLocalTarget(absDir, rel) + if err == nil { + err = rejectNonRegularLocalTarget(localPath) + } + if err != nil { + failures[rel] = err.Error() + } + } +} + +func drivePullPreflightFailureResult(relPaths []string, preflight map[string]string) drivePullResult { + res := drivePullResult{Items: make([]drivePullItem, 0, len(relPaths))} + for _, rel := range relPaths { + msg := mirrorPreflightFailureForRel(rel, preflight) + if msg == "" { + msg = "另一镜像条目未通过预检，整批拉取已中止" + } + res.Summary.Failed++ + res.Items = append(res.Items, drivePullItem{RelPath: rel, Action: pullActionFailed, Error: msg}) + } + return res +} + +func mirrorPreflightFailureForRel(rel string, preflight map[string]string) string { + for rel != "" { + if msg := preflight[rel]; msg != "" { + return msg + } + rel, _ = splitRel(rel) + } + return "" +} + +func pullRemoteFile(ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, ifExists string) (string, error) { + return pullOneFileAtRoot(ctx, spaceID, rf, absDir, rel, ifExists) +} + +func pullRemoteFilePinned(ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel, ifExists string) (string, error) { + target, err := root.openTarget(rel) + if err != nil { + return pullActionFailed, err + } + defer target.close() + return pullOneFilePinned(ctx, spaceID, rf, target, ifExists) +} + // pullOneFile 处理单个远端文件：按 --if-exists 决定是否跳过，否则下载到 localPath。 // 返回动作分类（downloaded / skipped / failed）及失败时的 error。 func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, ifExists string) (string, error) { + return pullOneFileAtRoot(ctx, spaceID, rf, filepath.Dir(localPath), filepath.Base(localPath), ifExists) +} + +func pullOneFileAtRoot(ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, ifExists string) (string, error) { + root, err := openPinnedPullRoot(absDir) + if err != nil { + return pullActionFailed, err + } + defer root.close() + target, err := root.openTarget(rel) + if err != nil { + return pullActionFailed, err + } + defer target.close() + return pullOneFilePinned(ctx, spaceID, rf, target, ifExists) +} + +func pullOneFilePinned(ctx context.Context, spaceID string, rf *remoteFile, target *pinnedPullTarget, ifExists string) (string, error) { + // 镜像文件的目标若已存在，必须是常规文件。目录、设备、FIFO 等都不能交给 + // download_file / 临时文件写入流程，否则 dry-run 与执行结论会分叉，且目录目标 + // 会在发出远端读请求后才失败。 + initialInfo, err := target.regularTargetInfo() + if err != nil { + return pullActionFailed, err + } // 本地已存在常规文件时，按策略判断是否跳过下载。 - if fi, statErr := os.Stat(localPath); statErr == nil && fi.Mode().IsRegular() { + if initialInfo != nil { switch ifExists { case ifExistsSkip: return pullActionSkipped, nil case ifExistsSmart: // 远端时间可信且本地 mtime 已 ≥ 远端 → 视为已对齐，跳过； // 时间缺失/非法时不盲跳，退回继续下载。 - if rf.ModifiedTimeValid && fi.ModTime().UnixMilli() >= rf.ModifiedTime { + if rf.ModifiedTimeValid && initialInfo.ModTime().UnixMilli() >= rf.ModifiedTime { return pullActionSkipped, nil } case ifExistsOverwrite: @@ -319,39 +474,501 @@ func pullOneFile(ctx context.Context, spaceID string, rf *remoteFile, localPath, return pullActionFailed, err } - dir := filepath.Dir(localPath) - if err := os.MkdirAll(dir, 0o755); err != nil { - return pullActionFailed, fmt.Errorf("创建本地目录失败: %w", err) + // download_file 可执行任意时长的远端读。在任何 HTTP GET 或临时文件写入前， + // 必须确认目标父目录仍是最初固定在本地根下的同一目录。 + if err := target.verifyParent(); err != nil { + return pullActionFailed, err } - // 先下载到同目录下的临时文件，完整落盘后再原子 rename 覆盖目标：任何中途失败 - // （网络中断、超时、写盘错误）都不会截断或破坏已存在的原文件。同目录保证 - // rename 在同一文件系统内、可原子替换；rename 会替换目标符号链接本身而非跟随它。 - tmp, err := pullCreateTemp(dir, ".dws-pull-*") + // 临时文件通过已固定的 os.Root 直接打开，下载直接写已打开的句柄； + // 生产路径不会再按可被换链的绝对路径重新打开临时文件。 + tmp, tmpName, err := pullCreateTemp(target.parentRoot) if err != nil { return pullActionFailed, fmt.Errorf("创建临时文件失败: %w", err) } - tmpPath := tmp.Name() - _ = tmp.Close() // httpGetFile 会自行 os.Create 覆盖该临时文件 // 除非成功 rename，否则始终清理临时文件，不留半成品。 committed := false + tmpInfo, err := tmp.Stat() + if err != nil { + _ = tmp.Close() + _ = target.parentRoot.Remove(tmpName) + return pullActionFailed, fmt.Errorf("读取临时文件身份失败: %w", err) + } defer func() { + _ = tmp.Close() if !committed { - _ = os.Remove(tmpPath) + _ = target.parentRoot.Remove(tmpName) } }() - if err := httpGetFile(ctx, resourceURL, headers, tmpPath); err != nil { + if err := pullDownloadFile(ctx, resourceURL, headers, tmp); err != nil { return pullActionFailed, err } - // 对齐 mtime 放在 rename 之前，保证替换后的目标文件时间戳即为远端时间。 + // 通过仍打开的文件句柄设置 mtime，避免按 tmpName 重新解析路径产生 symlink TOCTOU。 + // 时间对齐延续既有 best-effort 语义，失败不影响已完整下载内容的发布。 if rf.ModifiedTimeValid { - t := time.UnixMilli(rf.ModifiedTime) - _ = os.Chtimes(tmpPath, t, t) + _ = setPullFileTimes(tmp, time.UnixMilli(rf.ModifiedTime)) } - if err := driveReplaceFile(tmpPath, localPath); err != nil { + if err := pullSyncTemp(tmp); err != nil { + return pullActionFailed, fmt.Errorf("同步临时文件失败: %w", err) + } + if err := pullCloseTemp(tmp); err != nil { + return pullActionFailed, fmt.Errorf("关闭临时文件失败: %w", err) + } + currentTmp, err := pullRootLstat(target.parentRoot, tmpName) + if err != nil || !os.SameFile(tmpInfo, currentTmp) { + return pullActionFailed, fmt.Errorf("临时文件在下载期间被替换，已中止发布") + } + // 网络传输期间父目录仍可能被移走或替换。发布前再核对父目录身份和 + // 目标类型；不一致时只删除固定目录内的临时文件，绝不发布。 + if err := target.verifyParent(); err != nil { + return pullActionFailed, err + } + currentTarget, err := target.regularTargetInfo() + if err != nil { + return pullActionFailed, err + } + if ifExists != ifExistsOverwrite { + if currentTarget != nil && (initialInfo == nil || !os.SameFile(initialInfo, currentTarget)) { + return pullActionSkipped, nil + } + if ifExists == ifExistsSmart && currentTarget != nil && rf.ModifiedTimeValid && currentTarget.ModTime().UnixMilli() >= rf.ModifiedTime { + return pullActionSkipped, nil + } + } + if currentTarget == nil && ifExists != ifExistsOverwrite { + if err := pullLink(target.parentRoot, tmpName, target.name); err != nil { + if concurrent, statErr := target.regularTargetInfo(); statErr == nil && concurrent != nil { + return pullActionSkipped, nil + } + return pullActionFailed, fmt.Errorf("发布目标文件失败: %w", err) + } + if err := pullRemove(target.parentRoot, tmpName); err != nil { + return pullActionFailed, fmt.Errorf("清理临时文件失败: %w", err) + } + } else if err := pullRename(target.parentRoot, tmpName, target.name); err != nil { return pullActionFailed, fmt.Errorf("替换目标文件失败: %w", err) } + finalInfo, err := pullRootLstat(target.parentRoot, target.name) + if err != nil || !os.SameFile(tmpInfo, finalInfo) { + // 身份不匹配意味着发布后 terminal entry 可能已被并发替换；保留未知对象并报错， + // 不做 Lstat→Remove 的第二次 check/use，以免误删用户并发创建的文件。 + return pullActionFailed, fmt.Errorf("发布后的目标文件身份不一致") + } + if err := target.verifyParent(); err != nil { + // 固定目录已从命令根路径移走时，保留句柄内已完成的结果并报失败；不能无条件 + // Remove，因为发布后同名 terminal entry 仍可能被并发替换。 + return pullActionFailed, err + } committed = true return pullActionDownloaded, nil } + +type pinnedPullRoot struct { + absDir string + root *os.Root + rootInfo os.FileInfo + pathInfo os.FileInfo +} + +// pinnedPullRootPlan 在远端清单读取前固定 pull 的本地根状态。existing 非空表示 +// absDir 当时已存在；否则 ancestor 固定最近既存祖先，missing 保存从祖先到 absDir +// 的逐层目录名。missing 只有在完整远端清单和本地预检通过后才允许物化。 +type pinnedPullRootPlan struct { + absDir string + existing *pinnedPullRoot + ancestor *pinnedPullRoot + missing []string +} + +type pinnedPullTarget struct { + base *pinnedPullRoot + parentRoot *os.Root + parentChain []pinnedPullDirIdentity + name string + ownsBase bool +} + +type pinnedPullDirIdentity struct { + rel string + info os.FileInfo +} + +func planPinnedPullRoot(absDir string) (*pinnedPullRootPlan, error) { + info, err := pullPathStat(absDir) + if err == nil { + if !info.IsDir() { + return nil, fmt.Errorf("创建本地目录失败: %s 已存在且不是目录", absDir) + } + root, openErr := openExistingPinnedPullRoot(absDir) + if openErr != nil { + return nil, openErr + } + return &pinnedPullRootPlan{absDir: absDir, existing: root}, nil + } + if !os.IsNotExist(err) { + return nil, fmt.Errorf("检查本地目录失败: %w", err) + } + + ancestorPath := absDir + missing := make([]string, 0, 4) + for { + parent := filepath.Dir(ancestorPath) + // absDir 已是验证过的绝对路径；文件系统根目录始终存在， + // 因此循环必然在到达 parent == ancestorPath 之前以 Stat 成功结束。 + name := filepath.Base(ancestorPath) + missing = append([]string{name}, missing...) + ancestorPath = parent + info, statErr := pullPathStat(ancestorPath) + if statErr == nil { + if !info.IsDir() { + return nil, fmt.Errorf("创建本地目录失败: %s 已存在且不是目录", ancestorPath) + } + break + } + if !os.IsNotExist(statErr) { + return nil, fmt.Errorf("检查本地目录失败: %w", statErr) + } + } + ancestor, openErr := openExistingPinnedPullRoot(ancestorPath) + if openErr != nil { + return nil, openErr + } + plan := &pinnedPullRootPlan{absDir: absDir, ancestor: ancestor, missing: missing} + if verifyErr := plan.verify(); verifyErr != nil { + plan.close() + return nil, verifyErr + } + return plan, nil +} + +func (plan *pinnedPullRootPlan) verify() error { + if plan.existing != nil { + return plan.existing.verify() + } + if plan.ancestor == nil { + return fmt.Errorf("本地根目录计划无效") + } + if err := plan.ancestor.verify(); err != nil { + return err + } + prefix := "" + for _, segment := range plan.missing { + prefix = filepath.Join(prefix, segment) + _, err := pullRootLstat(plan.ancestor.root, prefix) + if err == nil { + return fmt.Errorf("本地根目录 %q 在远端读取期间被占用，已中止写入", plan.absDir) + } + if !os.IsNotExist(err) { + return fmt.Errorf("检查本地根目录计划失败: %w", err) + } + // 第一层缺失后更深的路径不可能存在；物化时每层 Mkdir 仍以 no-clobber + // 语义拒绝 verify 与创建之间的并发抢占。 + break + } + return nil +} + +func (plan *pinnedPullRootPlan) materialize() (*pinnedPullRoot, error) { + if err := plan.verify(); err != nil { + return nil, err + } + if plan.existing != nil { + root := plan.existing + plan.existing = nil + return root, nil + } + + current, err := pullOpenParentRoot(plan.ancestor.root, ".") + if err != nil { + return nil, fmt.Errorf("固定本地根祖先失败: %w", err) + } + for _, segment := range plan.missing { + if err := pullRootMkdir(current, segment, 0o755); err != nil { + _ = current.Close() + return nil, fmt.Errorf("创建本地目录失败: %w", err) + } + createdInfo, err := pullRootLstat(current, segment) + if err != nil || !createdInfo.IsDir() { + _ = current.Close() + return nil, fmt.Errorf("读取新建本地目录身份失败") + } + next, err := pullOpenParentRoot(current, segment) + if err != nil { + _ = current.Close() + return nil, fmt.Errorf("固定新建本地目录失败: %w", err) + } + nextInfo, statErr := pullRootStat(next, ".") + if statErr != nil || !os.SameFile(createdInfo, nextInfo) { + _ = next.Close() + _ = current.Close() + return nil, fmt.Errorf("新建本地目录在固定期间被替换，已中止写入") + } + _ = current.Close() + current = next + } + rootInfo, err := pullRootStat(current, ".") + if err != nil { + _ = current.Close() + return nil, fmt.Errorf("读取本地根目录身份失败: %w", err) + } + pathInfo, err := pullPathLstat(plan.absDir) + if err != nil { + _ = current.Close() + return nil, fmt.Errorf("读取本地根目录路径身份失败: %w", err) + } + root := &pinnedPullRoot{absDir: plan.absDir, root: current, rootInfo: rootInfo, pathInfo: pathInfo} + if err := root.verify(); err != nil { + root.close() + return nil, err + } + return root, nil +} + +func (plan *pinnedPullRootPlan) close() { + if plan.existing != nil { + plan.existing.close() + plan.existing = nil + } + if plan.ancestor != nil { + plan.ancestor.close() + plan.ancestor = nil + } +} + +func openPinnedPullRoot(absDir string) (*pinnedPullRoot, error) { + if err := pullMkdirAll(absDir, 0o755); err != nil { + return nil, fmt.Errorf("创建本地目录失败: %w", err) + } + return openExistingPinnedPullRoot(absDir) +} + +// openExistingPinnedPullRoot 只固定已经存在的本地目录。push/sync 必须用这一入口： +// 本地源根不存在时直接失败，不能为了扫描或上传隐式创建一个空源目录。 +func openExistingPinnedPullRoot(absDir string) (*pinnedPullRoot, error) { + baseRoot, err := pullOpenRoot(absDir) + if err != nil { + return nil, fmt.Errorf("打开本地根目录失败: %w", err) + } + rootInfo, err := pullRootStat(baseRoot, ".") + if err != nil { + _ = baseRoot.Close() + return nil, fmt.Errorf("读取本地根目录身份失败: %w", err) + } + pathInfo, err := pullPathLstat(absDir) + if err != nil { + _ = baseRoot.Close() + return nil, fmt.Errorf("读取本地根目录路径身份失败: %w", err) + } + root := &pinnedPullRoot{absDir: absDir, root: baseRoot, rootInfo: rootInfo, pathInfo: pathInfo} + if err := root.verify(); err != nil { + root.close() + return nil, err + } + return root, nil +} + +func openPinnedPullTarget(absDir, rel string) (*pinnedPullTarget, error) { + root, err := openPinnedPullRoot(absDir) + if err != nil { + return nil, err + } + target, err := root.openTarget(rel) + if err != nil { + root.close() + return nil, err + } + target.ownsBase = true + return target, nil +} + +func (root *pinnedPullRoot) openTarget(rel string) (*pinnedPullTarget, error) { + if err := root.verify(); err != nil { + return nil, err + } + localPath := filepath.Join(root.absDir, filepath.FromSlash(rel)) + localRel, err := pullRelPath(root.absDir, localPath) + if err != nil || localRel == ".." || strings.HasPrefix(localRel, ".."+string(filepath.Separator)) { + return nil, fmt.Errorf("远端路径 %q 逃逸出本地根目录", rel) + } + parentRel := filepath.Dir(localRel) + parentRoot, parentChain, err := root.openTargetParent(parentRel) + if err != nil { + return nil, err + } + target := &pinnedPullTarget{ + base: root, parentRoot: parentRoot, parentChain: parentChain, + name: filepath.Base(localRel), + } + if err := target.verifyParent(); err != nil { + target.close() + return nil, err + } + return target, nil +} + +// openTargetParent 从固定根开始逐层创建并打开目标父目录。os.Root 会安全地阻止 +// 软链接逃逸根外，但允许跟随仍指向根内的相对软链接；镜像语义不能接受这种重定向， +// 否则 remote sub/a.txt 可能覆盖同一根下 victim/a.txt。因此每一层都必须： +// +// 1. 以 Lstat 拒绝软链接 / junction 及非目录； +// 2. 通过上一层已固定的 Root 打开下一层； +// 3. 再以 Lstat + SameFile 证明打开的就是目录项本身，而不是竞态中换入的链接目标。 +// +// parentChain 保存每一层目录项身份，后续每次 verifyParent 都从命令根重新复核。 +func (root *pinnedPullRoot) openTargetParent(parentRel string) (*os.Root, []pinnedPullDirIdentity, error) { + current, err := pullOpenParentRoot(root.root, ".") + if err != nil { + return nil, nil, fmt.Errorf("固定本地目标目录失败: %w", err) + } + chain := make([]pinnedPullDirIdentity, 0, 4) + if parentRel == "." { + info, err := pullRootLstat(root.root, ".") + if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + _ = current.Close() + return nil, nil, fmt.Errorf("本地目标目录不是可固定的真实目录") + } + openedInfo, statErr := pullRootStat(current, ".") + if statErr != nil || !os.SameFile(info, openedInfo) { + _ = current.Close() + return nil, nil, fmt.Errorf("本地目标目录在固定期间被替换，已中止写入") + } + chain = append(chain, pinnedPullDirIdentity{rel: ".", info: info}) + return current, chain, nil + } + + prefix := "" + for _, segment := range strings.Split(parentRel, string(filepath.Separator)) { + info, lstatErr := pullRootLstat(current, segment) + if os.IsNotExist(lstatErr) { + if mkdirErr := pullRootMkdir(current, segment, 0o755); mkdirErr != nil { + _ = current.Close() + return nil, nil, fmt.Errorf("创建本地目录失败: %w", mkdirErr) + } + info, lstatErr = pullRootLstat(current, segment) + } + if lstatErr != nil { + _ = current.Close() + return nil, nil, fmt.Errorf("检查本地目标目录失败: %w", lstatErr) + } + if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + _ = current.Close() + return nil, nil, fmt.Errorf("本地目标目录 %q 已存在且不是可固定的真实目录，已拒绝镜像", filepath.Join(prefix, segment)) + } + + next, openErr := pullOpenParentRoot(current, segment) + if openErr != nil { + _ = current.Close() + return nil, nil, fmt.Errorf("固定本地目标目录失败: %w", openErr) + } + openedInfo, statErr := pullRootStat(next, ".") + currentInfo, currentErr := pullRootLstat(current, segment) + if statErr != nil || currentErr != nil || !currentInfo.IsDir() || currentInfo.Mode()&os.ModeSymlink != 0 || + !os.SameFile(info, currentInfo) || !os.SameFile(currentInfo, openedInfo) { + _ = next.Close() + _ = current.Close() + return nil, nil, fmt.Errorf("本地目标目录在固定期间被替换，已中止写入") + } + prefix = filepath.Join(prefix, segment) + chain = append(chain, pinnedPullDirIdentity{rel: prefix, info: currentInfo}) + _ = current.Close() + current = next + } + return current, chain, nil +} + +func (root *pinnedPullRoot) verify() error { + current, err := pullPathStat(root.absDir) + currentPath, pathErr := pullPathLstat(root.absDir) + if err != nil || pathErr != nil || !os.SameFile(root.rootInfo, current) || !os.SameFile(root.pathInfo, currentPath) { + return fmt.Errorf("本地根目录在同步期间被替换，已中止写入") + } + return nil +} + +func (root *pinnedPullRoot) close() { _ = root.root.Close() } + +func (target *pinnedPullTarget) close() { + _ = target.parentRoot.Close() + if target.ownsBase { + target.base.close() + } +} + +func (target *pinnedPullTarget) verifyParent() error { + if err := target.base.verify(); err != nil { + return err + } + for _, expected := range target.parentChain { + current, err := pullRootLstat(target.base.root, expected.rel) + if err != nil || !current.IsDir() || current.Mode()&os.ModeSymlink != 0 || !os.SameFile(expected.info, current) { + return fmt.Errorf("本地目标目录在下载期间被替换，已中止写入") + } + } + return nil +} + +func (target *pinnedPullTarget) regularTargetInfo() (os.FileInfo, error) { + info, err := pullRootLstat(target.parentRoot, target.name) + if err != nil { + if os.IsNotExist(err) { + return nil, nil + } + return nil, fmt.Errorf("检查本地目标失败: %w", err) + } + if !info.Mode().IsRegular() { + return nil, fmt.Errorf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", target.name) + } + return info, nil +} + +func createPinnedPullTemp(root *os.Root) (*os.File, string, error) { + for i := 0; i < 100; i++ { + name := ".dws-pull-" + pullTempName() + file, err := root.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600) + if err == nil { + return file, name, nil + } + if !os.IsExist(err) { + return nil, "", err + } + } + return nil, "", fmt.Errorf("创建不重名临时文件失败") +} + +func defaultPullDownloadFile(ctx context.Context, url string, headers map[string]string, destination *os.File) error { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) + if err != nil { + return err + } + for key, value := range headers { + req.Header.Set(key, value) + } + resp, err := pullHTTPDo(req) + if err != nil { + return err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + body, _ := io.ReadAll(resp.Body) + return &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)} + } + _, err = io.Copy(destination, resp.Body) + return err +} + +// rejectNonRegularLocalTarget 在任何下载工具调用或临时文件创建之前，拒绝已存在但 +// 不是常规文件的镜像目标。不存在的目标可由后续流程安全创建。 +func rejectNonRegularLocalTarget(localPath string) error { + info, err := pullTargetLstat(localPath) + if err != nil { + if os.IsNotExist(err) { + return nil + } + return fmt.Errorf("检查本地目标失败: %w", err) + } + if !info.Mode().IsRegular() { + return fmt.Errorf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", localPath) + } + return nil +} diff --git a/internal/helpers/drive_pull_coverage_test.go b/internal/helpers/drive_pull_coverage_test.go index 8809f9b5..6d1c63ed 100644 --- a/internal/helpers/drive_pull_coverage_test.go +++ b/internal/helpers/drive_pull_coverage_test.go @@ -9,6 +9,8 @@ import ( "strconv" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // ────────────────────────────────────────────────────────── @@ -38,10 +40,9 @@ func TestCrossPlatformCoverageDrivePull_endToEndDownloadsAll(t *testing.T) { `{"name":"a.txt","type":"file","fileId":"A","modifyTime":1000},` + `{"name":"b.txt","type":"file","fileId":"B","modifyTime":2000}`) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("remote"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err != nil { t.Fatalf("unexpected error: %v", err) @@ -59,11 +60,10 @@ func TestCrossPlatformCoverageDrivePull_ifExistsSkipKeepsLocal(t *testing.T) { mustWrite(t, filepath.Join(root, "a.txt"), "local-original") caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9000}`) - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("skip must not download") return nil }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "skip"); err != nil { t.Fatalf("unexpected error: %v", err) @@ -82,11 +82,10 @@ func TestCrossPlatformCoverageDrivePull_ifExistsSmart(t *testing.T) { local := readFileMTimeMillis(t, p) caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local-5000, 10) + `}`) - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("smart must not download when local is newer") return nil }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { t.Fatalf("unexpected error: %v", err) @@ -103,10 +102,9 @@ func TestCrossPlatformCoverageDrivePull_ifExistsSmart(t *testing.T) { local := readFileMTimeMillis(t, p) caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":` + strconv.FormatInt(local+60000, 10) + `}`) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("fresh"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "smart"); err != nil { t.Fatalf("unexpected error: %v", err) @@ -130,10 +128,9 @@ func TestCrossPlatformCoverageDrivePull_invalidIfExistsRejected(t *testing.T) { func TestCrossPlatformCoverageDrivePull_passesSpaceIDToDownload(t *testing.T) { root := t.TempDir() caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("x"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--space-id", "SP9"); err != nil { t.Fatalf("unexpected error: %v", err) @@ -147,14 +144,11 @@ func TestCrossPlatformCoverageDrivePull_passesSpaceIDToDownload(t *testing.T) { func TestCrossPlatformCoverageDrivePull_downloadFailureIsPartialFailure(t *testing.T) { root := t.TempDir() caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload }) var out strings.Builder - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} - os.Args = []string{"dws", "drive", "pull"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"}) cmd := findDriveSubcommand(t, "pull") mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) @@ -229,10 +223,9 @@ func TestCrossPlatformCoverageDrivePull_escapingRelPathIsFailed(t *testing.T) { } return `{"result":{"items":[],"nextToken":""}}`, nil }} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("leak"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT"); err == nil { t.Fatal("expected symlink escape to be reported as failure") @@ -248,14 +241,8 @@ func TestCrossPlatformCoveragePullOneFile_mkdirFailureIsFailed(t *testing.T) { // "sub" 是普通文件，MkdirAll("sub") 必然失败。 mustWrite(t, filepath.Join(root, "sub"), "occupied") - prevDeps := deps - prevArgs := os.Args - deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { - deps = prevDeps - os.Args = prevArgs - }) + testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) rf := &remoteFile{RelPath: "sub/x.txt", FileID: "X"} action, err := pullOneFile(context.Background(), "", rf, filepath.Join(root, "sub", "x.txt"), ifExistsOverwrite) diff --git a/internal/helpers/drive_pull_plan_coverage_test.go b/internal/helpers/drive_pull_plan_coverage_test.go new file mode 100644 index 00000000..0c155338 --- /dev/null +++ b/internal/helpers/drive_pull_plan_coverage_test.go @@ -0,0 +1,507 @@ +package helpers + +import ( + "context" + "errors" + "io" + "net/http" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func newPinnedPullRootForCoverage(t *testing.T, path string) *pinnedPullRoot { + t.Helper() + root, err := openExistingPinnedPullRoot(path) + if err != nil { + t.Fatal(err) + } + t.Cleanup(root.close) + return root +} + +func newMissingPinnedPullPlanForCoverage(t *testing.T) *pinnedPullRootPlan { + t.Helper() + root := filepath.Join(t.TempDir(), "missing", "mirror") + plan, err := planPinnedPullRoot(root) + if err != nil { + t.Fatal(err) + } + t.Cleanup(plan.close) + return plan +} + +func TestCrossPlatformCoverageDrivePullRootPlanFailures(t *testing.T) { + t.Run("existing root open", func(t *testing.T) { + testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload }) + if _, err := planPinnedPullRoot(t.TempDir()); err == nil { + t.Fatal("expected existing-root open failure") + } + }) + + t.Run("ancestor is a file", func(t *testing.T) { + parent := t.TempDir() + file := filepath.Join(parent, "file") + mustWrite(t, file, "x") + if _, err := planPinnedPullRoot(filepath.Join(file, "child")); err == nil || + (!strings.Contains(err.Error(), "不是目录") && !strings.Contains(err.Error(), "not a directory")) { + t.Fatalf("error = %v", err) + } + }) + + t.Run("ancestor discovered as file", func(t *testing.T) { + file := filepath.Join(t.TempDir(), "file") + mustWrite(t, file, "x") + calls := 0 + testseam.Swap(t, &pullPathStat, func(string) (os.FileInfo, error) { + calls++ + if calls == 1 { + return nil, os.ErrNotExist + } + return os.Stat(file) + }) + if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil || !strings.Contains(err.Error(), "不是目录") { + t.Fatalf("error = %v", err) + } + }) + + t.Run("ancestor open", func(t *testing.T) { + testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload }) + if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil { + t.Fatal("expected ancestor open failure") + } + }) + + t.Run("path stat errors", func(t *testing.T) { + for _, initial := range []bool{true, false} { + t.Run(map[bool]string{true: "initial", false: "ancestor"}[initial], func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) { + calls++ + if initial || calls > 1 { + return nil, errTestDownload + } + return nil, os.ErrNotExist + }) + if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil { + t.Fatal("expected path stat failure") + } + }) + } + }) + + t.Run("initial verification", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls == 1 { + return nil, errTestDownload + } + return root.Lstat(name) + }) + if _, err := planPinnedPullRoot(filepath.Join(t.TempDir(), "missing")); err == nil { + t.Fatal("expected initial plan verification failure") + } + }) + + t.Run("invalid and changed plan", func(t *testing.T) { + if err := (&pinnedPullRootPlan{}).verify(); err == nil { + t.Fatal("expected invalid plan failure") + } + root := newPinnedPullRootForCoverage(t, t.TempDir()) + bad := *root + bad.absDir = filepath.Join(t.TempDir(), "gone") + if err := (&pinnedPullRootPlan{ancestor: &bad}).verify(); err == nil { + t.Fatal("expected changed ancestor failure") + } + }) + + t.Run("unexpected missing-path lstat", func(t *testing.T) { + plan := newMissingPinnedPullPlanForCoverage(t) + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload }) + if err := plan.verify(); err == nil { + t.Fatal("expected missing-path lstat failure") + } + }) +} + +func TestCrossPlatformCoverageDrivePullRootMaterializeFailures(t *testing.T) { + t.Run("verification", func(t *testing.T) { + if _, err := (&pinnedPullRootPlan{}).materialize(); err == nil { + t.Fatal("expected materialize verification failure") + } + }) + + for _, tc := range []struct { + name string + stub func(*testing.T) + }{ + {"open ancestor", func(t *testing.T) { + testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload }) + }}, + {"mkdir", func(t *testing.T) { + testseam.Swap(t, &pullRootMkdir, func(*os.Root, string, os.FileMode) error { return errTestDownload }) + }}, + {"created lstat", func(t *testing.T) { + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload }) + }}, + {"created not directory", func(t *testing.T) { + file := filepath.Join(t.TempDir(), "file") + mustWrite(t, file, "x") + info, err := os.Lstat(file) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return info, nil }) + }}, + {"created changes before root identity", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls == 2 { + return nil, errTestDownload + } + return root.Lstat(name) + }) + }}, + {"open created", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullOpenParentRoot, func(root *os.Root, name string) (*os.Root, error) { + calls++ + if calls > 1 { + return nil, errTestDownload + } + return root.OpenRoot(name) + }) + }}, + {"created identity", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls == 1 { + return nil, errTestDownload + } + return root.Stat(name) + }) + }}, + {"final root stat", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls == 3 { + return nil, errTestDownload + } + return root.Stat(name) + }) + }}, + {"final verification", func(t *testing.T) { + calls := 0 + testseam.Swap(t, &pullPathLstat, func(path string) (os.FileInfo, error) { + calls++ + if calls >= 2 { + return nil, errTestDownload + } + return os.Lstat(path) + }) + }}, + } { + t.Run(tc.name, func(t *testing.T) { + plan := newMissingPinnedPullPlanForCoverage(t) + tc.stub(t) + if root, err := plan.materialize(); err == nil { + root.close() + t.Fatal("expected materialize failure") + } + }) + } + + t.Run("final lstat and verify", func(t *testing.T) { + for _, failAt := range []int{1, 2} { + t.Run(string(rune('0'+failAt)), func(t *testing.T) { + plan := newMissingPinnedPullPlanForCoverage(t) + calls := 0 + if failAt == 1 { + testseam.Swap(t, &pullPathLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload }) + } else { + testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) { + calls++ + if calls >= 2 { + return nil, errTestDownload + } + return os.Stat(path) + }) + } + if root, err := plan.materialize(); err == nil { + root.close() + t.Fatal("expected final materialize failure") + } + }) + } + }) + + t.Run("open existing path identity and verification", func(t *testing.T) { + for _, fail := range []string{"lstat", "verify"} { + t.Run(fail, func(t *testing.T) { + dir := t.TempDir() + if fail == "lstat" { + testseam.Swap(t, &pullPathLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload }) + } else { + pathCalls := 0 + testseam.Swap(t, &pullPathLstat, func(path string) (os.FileInfo, error) { + pathCalls++ + if pathCalls >= 2 { + return nil, errTestDownload + } + return os.Lstat(path) + }) + } + if _, err := openExistingPinnedPullRoot(dir); err == nil { + t.Fatal("expected existing-root identity failure") + } + }) + } + }) +} + +func TestCrossPlatformCoverageDrivePullPublishRaces(t *testing.T) { + t.Run("smart concurrent target", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + mustWrite(t, filepath.Join(root, "a.txt"), "older") + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + return os.Chtimes(filepath.Join(root, "a.txt"), time.Now(), time.Now().Add(time.Hour)) + }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F", ModifiedTimeValid: true}, root, "a.txt", ifExistsSmart) + if err != nil || action != pullActionSkipped { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("link loses to regular target", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullLink, func(parent *os.Root, _, target string) error { + file, err := parent.OpenFile(target, os.O_CREATE|os.O_WRONLY, 0o600) + if err == nil { + _ = file.Close() + } + return os.ErrExist + }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsSkip) + if err != nil || action != pullActionSkipped { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("link cleanup", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullRemove, func(*os.Root, string) error { return errTestDownload }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsSkip) + if err == nil || action != pullActionFailed || !strings.Contains(err.Error(), "清理临时文件") { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("post publish parent", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + statCalls := 0 + testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) { + statCalls++ + if statCalls >= 5 { + return nil, errTestDownload + } + return os.Stat(path) + }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + if err == nil || action != pullActionFailed { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("overwrite rename", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullRename, func(*os.Root, string, string) error { return errTestDownload }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + if err == nil || action != pullActionFailed { + t.Fatalf("action=%q err=%v", action, err) + } + }) +} + +func TestCrossPlatformCoverageDrivePullPlanCallers(t *testing.T) { + t.Run("second preflight verification", func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "local") + root := newPinnedPullRootForCoverage(t, dir) + plan := &pinnedPullRootPlan{absDir: root.absDir, existing: root} + moved := false + testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) { + info, err := parent.Lstat(name) + if name == "a.txt" && !moved { + moved = true + if renameErr := os.Rename(dir, dir+"-pinned"); renameErr != nil { + t.Fatal(renameErr) + } + if mkdirErr := os.Mkdir(dir, 0o755); mkdirErr != nil { + t.Fatal(mkdirErr) + } + } + return info, err + }) + if _, _, err := buildDrivePullPreflightFromPlan(plan, map[string]*remoteFile{"a.txt": {RelPath: "a.txt"}}); err == nil { + t.Fatal("expected second verification failure") + } + }) + + t.Run("command materialize", func(t *testing.T) { + root := filepath.Join(t.TempDir(), "missing") + caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A"}`) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload }) + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDrivePull(cmd, nil); err == nil || !errors.Is(err, errTestDownload) { + t.Fatalf("error = %v", err) + } + }) + + t.Run("preflight output", func(t *testing.T) { + root := t.TempDir() + caller := pullListingCaller(`{"name":"A.txt","type":"file","fileId":"A"},{"name":"a.txt","type":"file","fileId":"B"}`) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDrivePull(cmd, nil); err == nil { + t.Fatal("expected preflight output failure") + } + }) + + t.Run("remote helper", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + action, err := pullRemoteFile(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + if err != nil || action != pullActionDownloaded { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("target construction final verification", func(t *testing.T) { + root := newPinnedPullRootForCoverage(t, t.TempDir()) + calls := 0 + testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls >= 2 && name == "." { + return nil, errTestDownload + } + return parent.Lstat(name) + }) + if _, err := root.openTarget("a.txt"); err == nil { + t.Fatal("expected target verification failure") + } + }) +} + +func TestCrossPlatformCoverageDrivePullDefaultTransportWithoutListener(t *testing.T) { + destination, err := os.Create(filepath.Join(t.TempDir(), "payload")) + if err != nil { + t.Fatal(err) + } + defer destination.Close() + + if err := defaultPullDownloadFile(context.Background(), ":", nil, destination); err == nil { + t.Fatal("expected invalid request URL") + } + + t.Run("transport error", func(t *testing.T) { + testseam.Swap(t, &pullHTTPDo, func(*http.Request) (*http.Response, error) { return nil, errTestDownload }) + if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, destination); !errors.Is(err, errTestDownload) { + t.Fatalf("error = %v", err) + } + }) + + t.Run("status", func(t *testing.T) { + testseam.Swap(t, &pullHTTPDo, func(request *http.Request) (*http.Response, error) { + if request.Header.Get("X-Test") != "yes" { + t.Fatalf("header = %q", request.Header.Get("X-Test")) + } + return &http.Response{StatusCode: http.StatusTeapot, Body: io.NopCloser(strings.NewReader("denied"))}, nil + }) + if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", map[string]string{"X-Test": "yes"}, destination); err == nil { + t.Fatal("expected status failure") + } + }) + + t.Run("success and copy", func(t *testing.T) { + testseam.Swap(t, &pullHTTPDo, func(*http.Request) (*http.Response, error) { + return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader("payload"))}, nil + }) + if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, destination); err != nil { + t.Fatal(err) + } + closed, createErr := os.Create(filepath.Join(t.TempDir(), "closed")) + if createErr != nil { + t.Fatal(createErr) + } + _ = closed.Close() + if err := defaultPullDownloadFile(context.Background(), "https://example.invalid", nil, closed); err == nil { + t.Fatal("expected copy failure") + } + }) +} + +func TestCrossPlatformCoverageDrivePullMTimeHandle(t *testing.T) { + file, err := os.Create(filepath.Join(t.TempDir(), "mtime")) + if err != nil { + t.Fatal(err) + } + defer file.Close() + if err := setPullFileTimes(file, time.Unix(123, 0)); err != nil { + t.Fatal(err) + } +} + +func TestCrossPlatformCoverageDrivePullDryRunLocalPolicies(t *testing.T) { + root := t.TempDir() + path := filepath.Join(root, "a.txt") + mustWrite(t, path, "local") + info, err := os.Stat(path) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: io.Discard}}) + remote := map[string]*remoteFile{"a.txt": {RelPath: "a.txt", ModifiedTimeValid: true, ModifiedTime: info.ModTime().UnixMilli()}} + for _, policy := range []string{ifExistsSkip, ifExistsSmart, ifExistsOverwrite} { + if err := printDrivePullDryRunWithLocalInfo(policy, remote, []string{"a.txt"}, nil, map[string]os.FileInfo{"a.txt": info}); err != nil { + t.Fatalf("policy %s: %v", policy, err) + } + } + if err := printDrivePullDryRunWithLocalInfo(ifExistsSkip, remote, []string{"missing.txt"}, nil, nil); err != nil { + t.Fatal(err) + } +} + +func TestCrossPlatformCoverageDrivePullRejectNonRegular(t *testing.T) { + if err := rejectNonRegularLocalTarget(filepath.Join(t.TempDir(), "missing")); err != nil { + t.Fatal(err) + } + dir := t.TempDir() + if err := rejectNonRegularLocalTarget(dir); err == nil { + t.Fatal("expected directory rejection") + } + testseam.Swap(t, &pullTargetLstat, func(string) (os.FileInfo, error) { return nil, errTestDownload }) + if err := rejectNonRegularLocalTarget("target"); err == nil { + t.Fatal("expected lstat failure") + } +} diff --git a/internal/helpers/drive_pull_test.go b/internal/helpers/drive_pull_test.go index f7543bab..e2d70cc8 100644 --- a/internal/helpers/drive_pull_test.go +++ b/internal/helpers/drive_pull_test.go @@ -8,6 +8,7 @@ import ( "path/filepath" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) @@ -128,17 +129,10 @@ func TestCrossPlatformCoverageDrivePull_nonexistentLocalRoot(t *testing.T) { listJSON: `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F1","modifyTime":1000}],"nextToken":""}}`, } - prevDeps := deps - prevArgs := os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("REMOTE"), 0o644) }) - t.Cleanup(func() { - deps = prevDeps - os.Args = prevArgs - SetHTTPGetFile(nil) - }) root := &cobra.Command{Use: "dws"} root.PersistentFlags().BoolP("yes", "y", false, "") @@ -147,7 +141,7 @@ func TestCrossPlatformCoverageDrivePull_nonexistentLocalRoot(t *testing.T) { // pull/push 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 full := []string{"pull", "--local-folder", absDir, "--remote-folder", "ROOT", "--yes"} - os.Args = append([]string{"dws", "drive"}, full...) + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...)) root.SetArgs(append([]string{"drive"}, full...)) // 全部下载成功时 runDrivePull 返回 nil；若误判逃逸则会有 failed 并返回 partial_failure。 @@ -240,21 +234,14 @@ func TestCrossPlatformCoveragePullOneFile_downloadFailureKeepsOriginal(t *testin const original = "ORIGINAL-CONTENT-DO-NOT-LOSE" mustWrite(t, target, original) - prevDeps := deps - prevArgs := os.Args // download_file 的 MCP 调用走 mock；httpGetFile 注入为“写入部分内容后报错”。 - deps = &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + testseam.Swap(t, &deps, &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { // 模拟传输中断：先截断/写半截，再返回错误。 _ = os.WriteFile(dest, []byte("HALF"), 0o644) return errors.New("connection reset") }) - t.Cleanup(func() { - deps = prevDeps - os.Args = prevArgs - SetHTTPGetFile(nil) - }) rf := &remoteFile{RelPath: "a.txt", FileID: "F1"} action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite) @@ -286,18 +273,11 @@ func TestCrossPlatformCoveragePullOneFile_downloadSuccessReplacesTarget(t *testi target := filepath.Join(root, "a.txt") mustWrite(t, target, "OLD") - prevDeps := deps - prevArgs := os.Args - deps = &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + testseam.Swap(t, &deps, &Deps{Caller: &drivePullMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("NEW-CONTENT"), 0o644) }) - t.Cleanup(func() { - deps = prevDeps - os.Args = prevArgs - SetHTTPGetFile(nil) - }) rf := &remoteFile{RelPath: "a.txt", FileID: "F1"} action, err := pullOneFile(context.Background(), "", rf, target, ifExistsOverwrite) diff --git a/internal/helpers/drive_pull_times_unix.go b/internal/helpers/drive_pull_times_unix.go new file mode 100644 index 00000000..23d9efd9 --- /dev/null +++ b/internal/helpers/drive_pull_times_unix.go @@ -0,0 +1,16 @@ +//go:build !windows + +package helpers + +import ( + "os" + "time" + + "golang.org/x/sys/unix" +) + +// setPullFileTimes 只通过已打开文件描述符更新访问/修改时间，不重新解析文件名。 +func setPullFileTimes(file *os.File, modified time.Time) error { + stamp := unix.NsecToTimeval(modified.UnixNano()) + return unix.Futimes(int(file.Fd()), []unix.Timeval{stamp, stamp}) +} diff --git a/internal/helpers/drive_pull_times_windows.go b/internal/helpers/drive_pull_times_windows.go new file mode 100644 index 00000000..a1b9e69d --- /dev/null +++ b/internal/helpers/drive_pull_times_windows.go @@ -0,0 +1,16 @@ +//go:build windows + +package helpers + +import ( + "os" + "time" + + "golang.org/x/sys/windows" +) + +// setPullFileTimes 只通过已打开文件句柄更新访问/修改时间，不重新解析文件名。 +func setPullFileTimes(file *os.File, modified time.Time) error { + stamp := windows.NsecToFiletime(modified.UnixNano()) + return windows.SetFileTime(windows.Handle(file.Fd()), nil, &stamp, &stamp) +} diff --git a/internal/helpers/drive_pull_toctou_test.go b/internal/helpers/drive_pull_toctou_test.go new file mode 100644 index 00000000..d32f4a6b --- /dev/null +++ b/internal/helpers/drive_pull_toctou_test.go @@ -0,0 +1,915 @@ +package helpers + +import ( + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func installPinnedPullSuccess(t *testing.T) { + t.Helper() + testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + _, err := destination.WriteString("remote") + return err + }) +} + +// replacePullAncestorWithOutsideLink 把已被 pull 固定的 sub 目录移走， +// 再在原名处放置指向根外的符号链接，确定性复现远端调用/下载期间的换链。 +func replacePullAncestorWithOutsideLink(t *testing.T, root, outside string) string { + t.Helper() + sub := filepath.Join(root, "sub") + parked := filepath.Join(root, "sub-pinned") + if err := os.Rename(sub, parked); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, sub); err != nil { + t.Skipf("平台不支持创建符号链接: %v", err) + } + return parked +} + +func runPullTOCTOUCase(t *testing.T, command string, root string) error { + t.Helper() + rf := &remoteFile{RelPath: "sub/a.txt", FileID: "F"} + if command == "pull" { + _, err := pullOneFileAtRoot(context.Background(), "", rf, root, rf.RelPath, ifExistsOverwrite) + return err + } + res := &driveSyncResult{} + syncPullFile(res, context.Background(), "", rf, root, rf.RelPath, syncDirectionPull) + if res.Summary.Failed != 1 || len(res.Items) != 1 { + t.Fatalf("sync TOCTOU result = %#v", res) + } + if res.Items[0].Error == "" { + t.Fatal("sync TOCTOU failure must retain the cause") + } + return &drivePullTestError{message: res.Items[0].Error} +} + +type drivePullTestError struct{ message string } + +func (e *drivePullTestError) Error() string { return e.message } + +// download_file 返回期间父目录被换成指向根外的软链时，pull/sync +// 必须在创建临时文件和发出 HTTP GET 前失败。 +func TestCrossPlatformCoverageDrivePullSyncRejectAncestorSwapBeforeTransfer(t *testing.T) { + for _, command := range []string{"pull", "sync"} { + t.Run(command, func(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil { + t.Fatal(err) + } + + var parked string + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "download_file" { + t.Fatalf("unexpected MCP tool %q", tool) + } + parked = replacePullAncestorWithOutsideLink(t, root, outside) + return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + tempCalls, getCalls := 0, 0 + testseam.Swap(t, &pullCreateTemp, func(root *os.Root) (*os.File, string, error) { + tempCalls++ + return createPinnedPullTemp(root) + }) + testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error { + getCalls++ + return nil + }) + + err := runPullTOCTOUCase(t, command, root) + if err == nil { + t.Fatal("换链后不应继续下载") + } + if tempCalls != 0 || getCalls != 0 { + t.Fatalf("换链后发生了落盘: temp=%d HTTP_GET=%d", tempCalls, getCalls) + } + if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 { + t.Fatalf("根外目录被写入: entries=%v err=%v", entries, readErr) + } + if entries, readErr := os.ReadDir(parked); readErr != nil || len(entries) != 0 { + t.Fatalf("已移走的固定目录被写入: entries=%v err=%v", entries, readErr) + } + }) + } +} + +// HTTP 传输完成前父目录被换链时，已打开临时文件可以安全清理， +// 但最终发布必须在再次核对父目录身份后失败，不得沿新软链写到根外。 +func TestCrossPlatformCoverageDrivePullSyncRechecksAncestorBeforePublish(t *testing.T) { + for _, command := range []string{"pull", "sync"} { + t.Run(command, func(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil { + t.Fatal(err) + } + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + parked := "" + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + parked = replacePullAncestorWithOutsideLink(t, root, outside) + return nil + }) + + err := runPullTOCTOUCase(t, command, root) + if err == nil { + t.Fatal("发布前换链未被拒绝") + } + if command == "pull" && !strings.Contains(err.Error(), "目标目录在下载期间被替换") { + t.Fatalf("pull error = %v", err) + } + if _, statErr := os.Stat(filepath.Join(outside, "a.txt")); !os.IsNotExist(statErr) { + t.Fatalf("根外目标被发布: %v", statErr) + } + if entries, readErr := os.ReadDir(parked); readErr != nil || len(entries) != 0 { + t.Fatalf("失败后应清理临时文件: entries=%v err=%v", entries, readErr) + } + }) + } +} + +func TestCrossPlatformCoverageDriveSyncKeepBothRejectsAncestorSwapWithoutRollback(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + sub := filepath.Join(root, "sub") + if err := os.Mkdir(sub, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(sub, "a.txt"), []byte("local"), 0o600); err != nil { + t.Fatal(err) + } + testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + parked := "" + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + parked = replacePullAncestorWithOutsideLink(t, root, outside) + return nil + }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "sub/a.txt", map[string]bool{}) + + if res.Summary.Failed != 1 || len(res.Items) != 1 { + t.Fatalf("keep-both TOCTOU result = %#v", res) + } + if !strings.Contains(res.Items[0].Error, "目标目录在下载期间被替换") { + t.Fatalf("error = %q", res.Items[0].Error) + } + if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 { + t.Fatalf("不得沿换链路径触碰根外目录: entries=%v err=%v", entries, err) + } + kept := filepath.Join(parked, "a.conflict-FID.txt") + if content, err := os.ReadFile(kept); err != nil || string(content) != "local" { + t.Fatalf("本地保留硬链接应留在原固定目录: content=%q err=%v", content, err) + } +} + +func TestCrossPlatformCoveragePinnedPullFilesystemErrorBranches(t *testing.T) { + t.Run("root mkdir", func(t *testing.T) { + testseam.Swap(t, &pullMkdirAll, func(string, os.FileMode) error { return errTestDownload }) + if _, err := openPinnedPullTarget(filepath.Join(t.TempDir(), "root"), "a.txt"); err == nil { + t.Fatal("expected root mkdir failure") + } + }) + + t.Run("open root", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullOpenRoot, func(string) (*os.Root, error) { return nil, errTestDownload }) + if _, err := openPinnedPullTarget(root, "a.txt"); err == nil { + t.Fatal("expected root open failure") + } + }) + + t.Run("relative path", func(t *testing.T) { + root := t.TempDir() + for name, relFn := range map[string]func(string, string) (string, error){ + "error": func(string, string) (string, error) { return "", errTestDownload }, + "escape": func(string, string) (string, error) { return "../escape", nil }, + } { + t.Run(name, func(t *testing.T) { + testseam.Swap(t, &pullRelPath, relFn) + if _, err := openPinnedPullTarget(root, "a.txt"); err == nil { + t.Fatal("expected relative-path failure") + } + }) + } + }) + + t.Run("parent mkdir", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullRootMkdir, func(*os.Root, string, os.FileMode) error { return errTestDownload }) + if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil { + t.Fatal("expected parent mkdir failure") + } + }) + + t.Run("parent mkdir success", func(t *testing.T) { + root := t.TempDir() + target, err := openPinnedPullTarget(root, "sub/a.txt") + if err != nil { + t.Fatal(err) + } + target.close() + if info, err := os.Lstat(filepath.Join(root, "sub")); err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + t.Fatalf("created parent is not a real directory: info=%v err=%v", info, err) + } + }) + + t.Run("open root clone", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullOpenParentRoot, func(*os.Root, string) (*os.Root, error) { return nil, errTestDownload }) + if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil { + t.Fatal("expected root clone failure") + } + }) + + t.Run("open parent segment", func(t *testing.T) { + root := t.TempDir() + if err := os.Mkdir(filepath.Join(root, "sub"), 0o755); err != nil { + t.Fatal(err) + } + testseam.Swap(t, &pullOpenParentRoot, func(root *os.Root, name string) (*os.Root, error) { + if name == "sub" { + return nil, errTestDownload + } + return root.OpenRoot(name) + }) + if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil { + t.Fatal("expected parent segment open failure") + } + }) + + t.Run("lstat root parent", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload }) + if _, err := openPinnedPullTarget(root, "a.txt"); err == nil { + t.Fatal("expected root parent lstat failure") + } + }) + + t.Run("lstat parent segment", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + if name == "sub" { + return nil, errTestDownload + } + return root.Lstat(name) + }) + if _, err := openPinnedPullTarget(root, "sub/a.txt"); err == nil { + t.Fatal("expected parent segment lstat failure") + } + }) + + t.Run("stat parent", func(t *testing.T) { + root := t.TempDir() + testseam.Swap(t, &pullRootStat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload }) + if _, err := openPinnedPullTarget(root, "a.txt"); err == nil { + t.Fatal("expected parent stat failure") + } + }) + + t.Run("parent changes while target opens", func(t *testing.T) { + root := t.TempDir() + calls := 0 + testseam.Swap(t, &pullRootStat, func(root *os.Root, name string) (os.FileInfo, error) { + calls++ + if calls == 2 { + return nil, errTestDownload + } + return root.Stat(name) + }) + if _, err := openPinnedPullTarget(root, "a.txt"); err == nil { + t.Fatal("expected construction-time parent identity failure") + } + }) + + t.Run("lstat target", func(t *testing.T) { + root := t.TempDir() + target, err := openPinnedPullTarget(root, "a.txt") + if err != nil { + t.Fatal(err) + } + defer target.close() + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { return nil, errTestDownload }) + if _, err := target.regularTargetInfo(); err == nil { + t.Fatal("expected target lstat failure") + } + }) + + t.Run("create temp root error and collision exhaustion", func(t *testing.T) { + closed, err := os.OpenRoot(t.TempDir()) + if err != nil { + t.Fatal(err) + } + _ = closed.Close() + if _, _, err := createPinnedPullTemp(closed); err == nil { + t.Fatal("expected closed root failure") + } + + rootDir := t.TempDir() + root, err := os.OpenRoot(rootDir) + if err != nil { + t.Fatal(err) + } + defer root.Close() + const collision = "collision" + if err := os.WriteFile(filepath.Join(rootDir, ".dws-pull-"+collision), []byte("x"), 0o600); err != nil { + t.Fatal(err) + } + testseam.Swap(t, &pullTempName, func() string { return collision }) + if _, _, err := createPinnedPullTemp(root); err == nil { + t.Fatal("expected collision exhaustion") + } + }) +} + +func TestCrossPlatformCoveragePinnedPullPublicationErrorBranches(t *testing.T) { + call := func(t *testing.T, root string) error { + t.Helper() + _, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + return err + } + + t.Run("temp stat", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullCreateTemp, func(root *os.Root) (*os.File, string, error) { + file, name, err := createPinnedPullTemp(root) + if err == nil { + _ = file.Close() + } + return file, name, err + }) + if err := call(t, root); err == nil || !strings.Contains(err.Error(), "读取临时文件身份失败") { + t.Fatalf("error = %v", err) + } + }) + + t.Run("temp sync", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullSyncTemp, func(*os.File) error { return errTestDownload }) + if err := call(t, root); err == nil || !strings.Contains(err.Error(), "同步临时文件失败") { + t.Fatalf("error = %v", err) + } + }) + + t.Run("temp close", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullCloseTemp, func(*os.File) error { return errTestDownload }) + if err := call(t, root); err == nil || !strings.Contains(err.Error(), "关闭临时文件失败") { + t.Fatalf("error = %v", err) + } + }) + + t.Run("temp identity", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + other := filepath.Join(t.TempDir(), "other") + if err := os.WriteFile(other, []byte("other"), 0o600); err != nil { + t.Fatal(err) + } + otherInfo, err := os.Lstat(other) + if err != nil { + t.Fatal(err) + } + downloaded := false + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + downloaded = true + _, err := destination.WriteString("remote") + return err + }) + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + if downloaded && strings.HasPrefix(name, ".dws-pull-") { + return otherInfo, nil + } + return root.Lstat(name) + }) + if err := call(t, root); err == nil || !strings.Contains(err.Error(), "临时文件在下载期间被替换") { + t.Fatalf("error = %v", err) + } + }) + + t.Run("target becomes directory", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + return os.Mkdir(filepath.Join(root, "a.txt"), 0o755) + }) + if err := call(t, root); err == nil || !strings.Contains(err.Error(), "不是常规文件") { + t.Fatalf("error = %v", err) + } + }) +} + +func TestCrossPlatformCoverageDefaultPullDownloadFileBranches(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) { + if request.Header.Get("X-Test") != "yes" { + t.Errorf("header = %q", request.Header.Get("X-Test")) + } + if request.URL.Path == "/status" { + http.Error(w, "denied", http.StatusTeapot) + return + } + _, _ = io.WriteString(w, "payload") + })) + defer server.Close() + + destination, err := os.Create(filepath.Join(t.TempDir(), "payload")) + if err != nil { + t.Fatal(err) + } + defer destination.Close() + if err := defaultPullDownloadFile(context.Background(), ":", nil, destination); err == nil { + t.Fatal("expected invalid request URL") + } + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + if err := defaultPullDownloadFile(cancelled, server.URL, nil, destination); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled error = %v", err) + } + if err := defaultPullDownloadFile(context.Background(), server.URL+"/status", map[string]string{"X-Test": "yes"}, destination); err == nil { + t.Fatal("expected HTTP status failure") + } + if err := defaultPullDownloadFile(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}, destination); err != nil { + t.Fatal(err) + } + + closed, err := os.Create(filepath.Join(t.TempDir(), "closed")) + if err != nil { + t.Fatal(err) + } + _ = closed.Close() + if err := defaultPullDownloadFile(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}, closed); err == nil { + t.Fatal("expected destination copy failure") + } +} + +func TestCrossPlatformCoverageDriveSyncKeepBothLinkRemainsPinnedWhenParentMoves(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + sub := filepath.Join(root, "sub") + if err := os.Mkdir(sub, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(sub, "a.txt"), []byte("local"), 0o600); err != nil { + t.Fatal(err) + } + for name, content := range map[string]string{ + "a.txt": "attacker-destination", + "a.conflict-FID.txt": "attacker-source", + } { + if err := os.WriteFile(filepath.Join(outside, name), []byte(content), 0o600); err != nil { + t.Fatal(err) + } + } + testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + links := 0 + parked := "" + testseam.Swap(t, &syncRootLink, func(parent *os.Root, oldName, newName string) error { + links++ + // reserve 已完成 verifyParent；在真正 no-clobber Link 前换链，验证操作 + // 仍只落在已固定的 parentRoot，而不会沿新软链进入根外目录。 + parked = replacePullAncestorWithOutsideLink(t, root, outside) + return parent.Link(oldName, newName) + }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "sub/a.txt", map[string]bool{}) + if res.Summary.Failed != 1 || links != 1 { + t.Fatalf("result=%#v links=%d", res, links) + } + for _, name := range []string{"a.txt", "a.conflict-FID.txt"} { + if content, err := os.ReadFile(filepath.Join(parked, name)); err != nil || string(content) != "local" { + t.Fatalf("固定目录内的 %s 未安全保留: content=%q err=%v", name, content, err) + } + } + for name, want := range map[string]string{ + "a.txt": "attacker-destination", + "a.conflict-FID.txt": "attacker-source", + } { + if content, err := os.ReadFile(filepath.Join(outside, name)); err != nil || string(content) != want { + t.Fatalf("根外 %s 被硬链接触碰: content=%q err=%v", name, content, err) + } + } +} + +func TestCrossPlatformCoverageDriveSyncKeepBothDetectsCandidateMutationDuringTransfer(t *testing.T) { + for _, mutation := range []string{"deleted", "replaced", "modified"} { + t.Run(mutation, func(t *testing.T) { + root := t.TempDir() + if err := os.WriteFile(filepath.Join(root, "a.txt"), []byte("local"), 0o600); err != nil { + t.Fatal(err) + } + candidate := filepath.Join(root, "a.conflict-FID.txt") + testseam.Swap(t, &deps, &Deps{Caller: &driveSyncMockCaller{}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + switch mutation { + case "deleted": + return os.Remove(candidate) + case "replaced": + if err := os.Remove(candidate); err != nil { + return err + } + return os.WriteFile(candidate, []byte("attacker"), 0o600) + default: + return os.WriteFile(candidate, []byte("modified-local-version"), 0o600) + } + }) + + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "FID"}, root, "a.txt", map[string]bool{}) + if res.Summary.Failed != 1 || res.Summary.Pulled != 0 || len(res.Items) != 1 { + t.Fatalf("result=%#v", res) + } + if res.Items[0].Action != syncActionFailed || !strings.Contains(res.Items[0].Error, "本地保留版本在传输期间") { + t.Fatalf("candidate mutation must be failed, got %#v", res.Items) + } + if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "remote" { + t.Fatalf("remote publish result changed: content=%q err=%v", content, err) + } + }) + } +} + +func TestCrossPlatformCoverageDrivePullCommandPinsRootAcrossAllFiles(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + caller := pullListingCaller( + `{"name":"a.txt","type":"file","fileId":"A"},` + + `{"name":"b.txt","type":"file","fileId":"B"}`) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"}) + + calls := 0 + parked := filepath.Join(t.TempDir(), "original-root") + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + calls++ + if _, err := destination.WriteString("remote"); err != nil { + return err + } + if calls == 1 { + if err := os.Rename(root, parked); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, root); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + } + return nil + }) + + cmd := findDriveSubcommand(t, "pull") + mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT", "if-exists": "overwrite"}) + if err := runDrivePull(cmd, nil); err == nil { + t.Fatal("root replacement must fail the command") + } + if calls != 1 { + t.Fatalf("second file must fail before transfer when command root changed: calls=%d", calls) + } + if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 { + t.Fatalf("outside root was touched: entries=%v err=%v", entries, err) + } +} + +func TestCrossPlatformCoverageDrivePullPlansExistingRootBeforeRemoteRead(t *testing.T) { + parent := t.TempDir() + root := filepath.Join(parent, "mirror") + outside := t.TempDir() + parked := filepath.Join(parent, "mirror-pinned") + if err := os.Mkdir(root, 0o755); err != nil { + t.Fatal(err) + } + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "list_files" { + t.Fatalf("root replacement must stop before %s", tool) + } + if err := os.Rename(root, parked); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, root); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil + }} + getCalls := 0 + testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error { + getCalls++ + return nil + }) + + err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "overwrite") + if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") { + t.Fatalf("error=%v", err) + } + if len(caller.callsFor("download_file")) != 0 || getCalls != 0 { + t.Fatalf("root replacement reached transfer: MCP=%d GET=%d", len(caller.callsFor("download_file")), getCalls) + } + if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 { + t.Fatalf("outside root was touched: entries=%v err=%v", entries, readErr) + } +} + +func TestCrossPlatformCoverageDrivePullPlansMissingRootBeforeRemoteRead(t *testing.T) { + for _, takeover := range []string{"directory", "symlink"} { + t.Run(takeover, func(t *testing.T) { + parent := t.TempDir() + root := filepath.Join(parent, "missing", "mirror") + outside := t.TempDir() + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "list_files" { + t.Fatalf("missing-root takeover must stop before %s", tool) + } + if takeover == "directory" { + if err := os.MkdirAll(root, 0o755); err != nil { + t.Fatal(err) + } + } else { + if err := os.MkdirAll(filepath.Dir(root), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, root); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil + }} + getCalls := 0 + testseam.Swap(t, &pullDownloadFile, func(context.Context, string, map[string]string, *os.File) error { + getCalls++ + return nil + }) + + err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", "overwrite") + if err == nil || !strings.Contains(err.Error(), "在远端读取期间被占用") { + t.Fatalf("error=%v", err) + } + if len(caller.callsFor("download_file")) != 0 || getCalls != 0 { + t.Fatalf("missing-root takeover reached transfer: MCP=%d GET=%d", len(caller.callsFor("download_file")), getCalls) + } + if entries, readErr := os.ReadDir(outside); readErr != nil || len(entries) != 0 { + t.Fatalf("outside root was touched: entries=%v err=%v", entries, readErr) + } + }) + } +} + +func TestCrossPlatformCoverageDrivePullDryRunDoesNotMaterializeMissingRoot(t *testing.T) { + root := filepath.Join(t.TempDir(), "missing", "mirror") + caller := &driveScriptCaller{dryRun: true, reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "list_files" { + t.Fatalf("dry-run must stop before %s", tool) + } + return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil + }} + if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--dry-run"); err != nil { + t.Fatal(err) + } + if _, err := os.Lstat(root); !os.IsNotExist(err) { + t.Fatalf("dry-run materialized missing root: %v", err) + } +} + +func TestCrossPlatformCoverageDriveSyncCommandPinsRootAcrossAllFiles(t *testing.T) { + root := t.TempDir() + outside := t.TempDir() + caller := &driveSyncMockCaller{listJSON: `{"result":{"items":[` + + `{"name":"a.txt","type":"file","fileId":"A"},` + + `{"name":"b.txt","type":"file","fileId":"B"}` + + `],"nextToken":""}}`} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"}) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) + + calls := 0 + parked := filepath.Join(t.TempDir(), "original-root") + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + calls++ + if _, err := destination.WriteString("remote"); err != nil { + return err + } + if calls == 1 { + if err := os.Rename(root, parked); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, root); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + } + return nil + }) + + cmd := findDriveSubcommand(t, "sync") + mustSetFlags(t, cmd, map[string]string{"local-folder": root, "remote-folder": "ROOT"}) + if err := runDriveSync(cmd, nil); err == nil { + t.Fatal("root replacement must fail sync") + } + if calls != 1 { + t.Fatalf("second sync file must fail before transfer when command root changed: calls=%d", calls) + } + if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 { + t.Fatalf("outside root was touched: entries=%v err=%v", entries, err) + } +} + +func TestCrossPlatformCoverageDrivePullReappliesSkipAndSmartAtPublish(t *testing.T) { + for _, policy := range []string{ifExistsSkip, ifExistsSmart} { + t.Run(policy, func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + return os.WriteFile(filepath.Join(root, "a.txt"), []byte("concurrent"), 0o600) + }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", policy) + if err != nil || action != pullActionSkipped { + t.Fatalf("action=%q err=%v", action, err) + } + if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "concurrent" { + t.Fatalf("concurrent target was overwritten: content=%q err=%v", content, err) + } + }) + } +} + +func TestCrossPlatformCoverageDrivePullPublicationIdentityAndLinkFailures(t *testing.T) { + t.Run("link failure without target is not skipped", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + testseam.Swap(t, &pullLink, func(*os.Root, string, string) error { return errTestDownload }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsSkip) + if err == nil || action != pullActionFailed || !strings.Contains(err.Error(), "发布目标文件失败") { + t.Fatalf("action=%q err=%v", action, err) + } + }) + + t.Run("post publish mismatch preserves unknown terminal", func(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + other := filepath.Join(t.TempDir(), "other") + if err := os.WriteFile(other, []byte("other"), 0o600); err != nil { + t.Fatal(err) + } + otherInfo, _ := os.Lstat(other) + published := false + testseam.Swap(t, &pullRename, func(root *os.Root, oldName, newName string) error { + if err := root.Rename(oldName, newName); err != nil { + return err + } + published = true + return nil + }) + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + if published && name == "a.txt" { + return otherInfo, nil + } + return root.Lstat(name) + }) + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + if err == nil || action != pullActionFailed { + t.Fatalf("action=%q err=%v", action, err) + } + if content, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(content) != "remote" { + t.Fatalf("未知 terminal entry 应保留: content=%q err=%v", content, err) + } + }) +} + +// os.Root 只保证路径不能逃逸根目录，仍会跟随指向根内目录的相对软链接。若 sub 在 +// Lstat 与 OpenRoot 之间被换成 sub -> victim，pull/sync/keep-both 都必须在任何远端 +// 读取或本地写入前拒绝，不能把 remote sub/a.txt 重定向到 victim/a.txt。 +func TestCrossPlatformCoverageDrivePullSyncKeepBothRejectRootInternalRedirect(t *testing.T) { + for _, redirect := range []string{"symlink", "directory"} { + for _, command := range []string{"pull", "sync", "keep-both"} { + t.Run(redirect+"/"+command, func(t *testing.T) { + root := t.TempDir() + sub := filepath.Join(root, "sub") + parked := filepath.Join(root, "sub-pinned") + victim := filepath.Join(root, "victim") + if err := os.Mkdir(sub, 0o755); err != nil { + t.Fatal(err) + } + if err := os.Mkdir(victim, 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(sub, "a.txt"), "local") + mustWrite(t, filepath.Join(victim, "a.txt"), "victim") + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "download_file" { + t.Fatalf("unexpected tool %q", tool) + } + return `{"result":{"downloadUrl":"https://oss.example.com/get"}}`, nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + _, err := destination.WriteString("remote") + return err + }) + + redirectedVictim := filepath.Join(victim, "a.txt") + swapped := false + testseam.Swap(t, &pullOpenParentRoot, func(parent *os.Root, name string) (*os.Root, error) { + if name == "sub" && !swapped { + swapped = true + if err := os.Rename(sub, parked); err != nil { + t.Fatal(err) + } + if redirect == "symlink" { + if err := os.Symlink("victim", sub); err != nil { + t.Skipf("平台不支持创建符号链接: %v", err) + } + } else { + if err := os.Rename(victim, sub); err != nil { + t.Fatal(err) + } + redirectedVictim = filepath.Join(sub, "a.txt") + } + } + return parent.OpenRoot(name) + }) + + rf := &remoteFile{RelPath: "sub/a.txt", FileID: "F"} + switch command { + case "pull": + action, err := pullOneFileAtRoot(context.Background(), "", rf, root, rf.RelPath, ifExistsOverwrite) + if err == nil || action != pullActionFailed { + t.Fatalf("action=%q err=%v", action, err) + } + case "sync": + res := &driveSyncResult{} + syncPullFile(res, context.Background(), "", rf, root, rf.RelPath, syncDirectionPull) + if res.Summary.Failed != 1 || res.Summary.Pulled != 0 { + t.Fatalf("sync result=%#v", res) + } + default: + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", rf, root, rf.RelPath, map[string]bool{}) + if res.Summary.Failed != 1 || res.Summary.Pulled != 0 { + t.Fatalf("keep-both result=%#v", res) + } + } + + if !swapped { + t.Fatal("test did not install the root-internal redirect") + } + if got := len(caller.callsFor("download_file")); got != 0 { + t.Fatalf("root-internal redirect reached download_file: %d", got) + } + for path, want := range map[string]string{ + filepath.Join(parked, "a.txt"): "local", + redirectedVictim: "victim", + } { + content, err := os.ReadFile(path) + if err != nil || string(content) != want { + t.Fatalf("%s changed: content=%q err=%v", path, content, err) + } + } + if matches, err := filepath.Glob(filepath.Join(filepath.Dir(redirectedVictim), "a.conflict-*.txt")); err != nil || len(matches) != 0 { + t.Fatalf("keep-both wrote into redirected victim: matches=%v err=%v", matches, err) + } + }) + } + } +} diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index ff617007..37eaec56 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -2,14 +2,21 @@ package helpers import ( "context" + "crypto/md5" + "encoding/base64" "encoding/json" "fmt" + "io" "io/fs" + "net/http" + "os" "path/filepath" "sort" "strings" + "time" "github.com/spf13/cobra" + "golang.org/x/text/unicode/norm" ) // ========================================================== @@ -40,8 +47,28 @@ type localPushFile struct { AbsPath string ModTimeMillis int64 Size int64 + scanInfo os.FileInfo } +// pushPutOpenedFile 把已由固定 os.Root 打开的本地文件句柄上传到 OSS。生产 push/sync +// 不再把可被并发换链的绝对路径交给 HTTP 层重新打开；测试必须通过 testseam.Swap 替换。 +var ( + pushPutOpenedFile = defaultPushPutOpenedFile + pushStatOpenedFile = func(file *os.File) (os.FileInfo, error) { + return file.Stat() + } + pushVerifyPinnedSourceRoot = func(root *pinnedPullRoot) error { + return root.verify() + } + pushMD5OpenedFile = func(file *os.File) (string, error) { + hash := md5.New() + if _, err := io.Copy(hash, file); err != nil { + return "", err + } + return base64.StdEncoding.EncodeToString(hash.Sum(nil)), nil + } +) + // drivePushItem 是输出 items[] 中每个条目的明细。 type drivePushItem struct { RelPath string `json:"rel_path"` @@ -105,6 +132,16 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { if err != nil { return err } + pinnedRoot, err := openExistingPinnedPullRoot(absDir) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } + defer pinnedRoot.close() + + localDirs, localFiles, err := runDriveMirrorWalkLocalForPushPinned(pinnedRoot) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } ctx := cmd.Context() // 远端现状：已存在的文件（用于 --if-exists 判断）与目录（rel_path → fileId，用于复用/定位父目录）。 @@ -113,23 +150,27 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { return err } - localDirs, localFiles, err := walkLocalForPush(absDir) - if err != nil { - return fmt.Errorf("扫描本地目录失败: %w", err) - } + preflight := buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders) res := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))} if deps.Caller.DryRun() { - return printDrivePushDryRun(ifExists, remoteFiles, remoteFolders, localDirs, localFiles) + return printDrivePushDryRunWithPreflight(ifExists, remoteFiles, remoteFolders, localDirs, localFiles, preflight) + } + if len(preflight) > 0 { + appendDrivePushPreflightFailures(&res, preflight) + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr + } + return &drivePushFailure{failed: res.Summary.Failed} + } + // 本地扫描与远端读取都可能耗时。首个远端写之前确认命令行路径仍指向最初固定 + // 的根；若根已被移走或替换，整批中止，不能把替代目录的数据当成扫描快照上传。 + if err := pinnedRoot.verify(); err != nil { + return err } // 第一阶段：按需创建远端目录（浅层在前，保证父目录先于子目录存在）。 for _, dir := range localDirs { - if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { - res.Summary.Failed++ - res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg}) - continue - } if _, ok := remoteFolders[dir]; ok { continue // 远端已存在，复用 fileId，不留痕 } @@ -140,6 +181,9 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { res.Items = append(res.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: "父目录未能创建"}) continue } + if err := pinnedRoot.verify(); err != nil { + return err + } fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name) if cerr != nil || fid == "" { res.Summary.Failed++ @@ -158,11 +202,6 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { for i := range localFiles { lf := localFiles[i] size := lf.Size - if msg := pushTypeConflictError(lf.RelPath, false, remoteFiles, remoteFolders); msg != "" { - res.Summary.Failed++ - res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: msg}) - continue - } parentRel, name := splitRel(lf.RelPath) parentID, ok := remoteFolders[parentRel] if !ok || parentID == "" { @@ -198,7 +237,7 @@ func runDrivePush(cmd *cobra.Command, _ []string) error { } } - if err := pushUploadFile(ctx, spaceID, parentID, overwriteID, name, lf.AbsPath, size); err != nil { + if err := pushUploadFilePinned(ctx, spaceID, parentID, overwriteID, name, pinnedRoot, lf); err != nil { res.Summary.Failed++ res.Items = append(res.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: err.Error()}) continue @@ -234,6 +273,7 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f return fmt.Errorf("drive 目录层级超过 %d 层，疑似循环引用，已中止", remoteMaxDepth) } nextToken := "" + seenTokens := make(map[string]struct{}) for { args := map[string]any{"maxResults": float64(driveListPageSize)} if spaceID != "" { @@ -285,36 +325,51 @@ func walkRemoteForPush(ctx context.Context, spaceID, parentID, relBase string, f if err := claimRemotePath(occupied, childRel, "文件"); err != nil { return err } + fileID := it.id() + if fileID == "" { + return fmt.Errorf("远端文件 %q 缺少文件 ID，已中止遍历", childRel) + } modMillis, modValid := it.modifiedMillis() files[childRel] = &remoteFile{ RelPath: childRel, - FileID: it.id(), + FileID: fileID, Hash: it.hash(), ModifiedTime: modMillis, ModifiedTimeValid: modValid, } } - if token == "" || token == nextToken { + if token == "" { break } + if _, exists := seenTokens[token]; exists { + return fmt.Errorf("远端目录 %q 的分页 token 重复，疑似分页循环，已中止", relBase) + } + seenTokens[token] = struct{}{} nextToken = token } return nil } func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, remoteFolders map[string]string, localDirs []string, localFiles []localPushFile) error { + return printDrivePushDryRunWithPreflight(ifExists, remoteFiles, remoteFolders, localDirs, localFiles, + buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders)) +} + +func printDrivePushDryRunWithPreflight(ifExists string, remoteFiles map[string]*remoteFile, remoteFolders map[string]string, localDirs []string, localFiles []localPushFile, preflight map[string]string) error { plan := drivePushResult{Items: make([]drivePushItem, 0, len(localDirs)+len(localFiles))} + if len(preflight) > 0 { + appendDrivePushPreflightFailures(&plan, preflight) + return deps.Out.PrintJSON(drivePushDryRunResult{ + DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive push", + IfExists: ifExists, Plan: plan, + }) + } plannedFolders := make(map[string]string, len(remoteFolders)+len(localDirs)) for rel, fileID := range remoteFolders { plannedFolders[rel] = fileID } for _, dir := range localDirs { - if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { - plan.Summary.Failed++ - plan.Items = append(plan.Items, drivePushItem{RelPath: dir, Action: pushActionFailed, Error: msg}) - continue - } if _, ok := plannedFolders[dir]; ok { continue } @@ -329,11 +384,6 @@ func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, r } for _, lf := range localFiles { size := lf.Size - if msg := pushTypeConflictError(lf.RelPath, false, remoteFiles, remoteFolders); msg != "" { - plan.Summary.Failed++ - plan.Items = append(plan.Items, drivePushItem{RelPath: lf.RelPath, Action: pushActionFailed, SizeBytes: &size, Error: msg}) - continue - } parentRel, _ := splitRel(lf.RelPath) if plannedFolders[parentRel] == "" { plan.Summary.Failed++ @@ -368,6 +418,14 @@ func printDrivePushDryRun(ifExists string, remoteFiles map[string]*remoteFile, r }) } +func appendDrivePushPreflightFailures(res *drivePushResult, preflight map[string]string) { + res.Summary.Aborted = true + for _, rel := range mirrorPreflightFailureRels(preflight) { + res.Summary.Failed++ + res.Items = append(res.Items, drivePushItem{RelPath: rel, Action: pushActionFailed, Error: preflight[rel]}) + } +} + // pushTypeConflictError 在任何写操作或 dry-run 成功预览之前，拒绝同一路径下 // “本地目录 ↔ 远端文件”或“本地文件 ↔ 远端目录”的类型冲突。 func pushTypeConflictError(rel string, localIsFolder bool, remoteFiles map[string]*remoteFile, remoteFolders map[string]string) string { @@ -386,19 +444,206 @@ func pushTypeConflictError(rel string, localIsFolder bool, remoteFiles map[strin // walkLocalForPush 遍历本地根目录，返回所有子目录 rel_path（不含根本身，浅层在前） // 与所有常规文件。dirs 升序排序保证父目录先于子目录被创建。 func walkLocalForPush(root string) ([]string, []localPushFile, error) { + pinned, err := openExistingPinnedPullRoot(root) + if err != nil { + return nil, nil, err + } + defer pinned.close() + return walkLocalForPushPinned(pinned) +} + +// 文件系统遍历与命令入口通过显式 seam 暴露仅用于确定性覆盖 I/O 失败；测试必须用 +// testseam.Swap 替换，生产仍直接使用 fs.WalkDir / walkLocalForPushPinned。 +var ( + walkPinnedLocalFS = fs.WalkDir + runDriveMirrorWalkLocalForPushPinned = walkLocalForPushPinned +) + +// walkLocalForPushPinned 从命令开始时固定的同一个 os.Root/FS 扫描本地树。即使调用方 +// 给出的路径随后被替换成软链或另一目录，遍历也只会读取原目录树。 +func walkLocalForPushPinned(root *pinnedPullRoot) ([]string, []localPushFile, error) { + if err := root.verify(); err != nil { + return nil, nil, err + } var dirs []string var files []localPushFile - err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { - return walkLocalForPushEntry(root, path, d, err, &dirs, &files) + err := walkPinnedLocalFS(root.root.FS(), ".", func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if path == "." { + return nil + } + relSlash := filepath.ToSlash(path) + if d.IsDir() { + dirs = append(dirs, relSlash) + return nil + } + info, infoErr := d.Info() + if infoErr != nil { + return infoErr + } + if !info.Mode().IsRegular() { + return nil + } + files = append(files, localPushFile{ + RelPath: relSlash, AbsPath: filepath.Join(root.absDir, filepath.FromSlash(relSlash)), + ModTimeMillis: info.ModTime().UnixMilli(), Size: info.Size(), scanInfo: info, + }) + return nil }) if err != nil { return nil, nil, err } + if err := root.verify(); err != nil { + return nil, nil, err + } // 字典序即浅层在前（"a" < "a/b" < "a/b/c"），父目录先于子目录。 sort.Strings(dirs) + sort.Slice(files, func(i, j int) bool { return files[i].RelPath < files[j].RelPath }) return dirs, files, nil } +// judgePinnedPushFileMatch 与 judgeFileMatch 的判定保持一致，但 exact 模式只从固定 +// os.Root 打开的句柄计算 MD5，绝不按可被换链的 AbsPath 重开文件。 +func judgePinnedPushFileMatch(root *pinnedPullRoot, local localPushFile, remote *remoteFile, quick bool) (string, error) { + if quick { + if remote.ModifiedTimeValid && local.ModTimeMillis == remote.ModifiedTime { + return matchUnchanged, nil + } + return matchModified, nil + } + if remote.Hash == "" { + return matchUnknown, nil + } + file, err := root.root.Open(filepath.FromSlash(local.RelPath)) + if err != nil { + return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", local.RelPath, err) + } + defer file.Close() + info, err := pushStatOpenedFile(file) + if err != nil || !info.Mode().IsRegular() || (local.scanInfo != nil && !os.SameFile(local.scanInfo, info)) { + return "", fmt.Errorf("计算 %s 的 MD5 失败: 本地文件在扫描后被替换", local.RelPath) + } + hash, err := pushMD5OpenedFile(file) + if err != nil { + return "", fmt.Errorf("计算 %s 的 MD5 失败: %w", local.RelPath, err) + } + if err := pushVerifyPinnedSourceRoot(root); err != nil { + return "", err + } + if hash == remote.Hash { + return matchUnchanged, nil + } + return matchModified, nil +} + +// mirrorPathKey 表示 Drive 镜像契约中的等价路径：逐段 Unicode NFC + 大小写折叠。 +// 该规则独立于运行命令的本地文件系统，避免 macOS/Windows 与 Drive 间把 a/A 或 +// NFC/NFD 当成“双向新增”，也避免把等价目录前缀错误拼接成另一棵树。 +func mirrorPathKey(rel string) string { + parts := strings.Split(rel, "/") + for i := range parts { + parts[i] = norm.NFC.String(strings.ToLower(parts[i])) + } + return strings.Join(parts, "/") +} + +func mirrorLocalRelError(rel string) string { + for _, segment := range strings.Split(rel, "/") { + if !isSafeRemoteSegment(segment) || strings.IndexByte(segment, 0) >= 0 { + return fmt.Sprintf("本地路径 %q 含无法安全映射到远端的名称段 %q，已中止镜像", rel, segment) + } + } + return "" +} + +// buildMirrorPreflight 在任何远端写之前统一检查本地名称和双端等价路径/类型。 +// 每个条目同时声明全部祖先目录，因而 local A/x 与 remote a/y 会在祖先键上冲突； +// 即便本地为空，remote A/a 也会被完整性门禁识别。调用方必须整体拒绝写入，不能只 +// 跳过冲突项。 +func buildMirrorPreflight(localDirs []string, localFiles []localPushFile, remoteFiles map[string]*remoteFile, remoteFolders map[string]string) map[string]string { + type mirrorKind string + const ( + mirrorFile mirrorKind = "文件" + mirrorDir mirrorKind = "目录" + ) + type entry struct { + rel string + kind mirrorKind + } + local := make(map[string]map[entry]struct{}) + remote := make(map[string]map[entry]struct{}) + failures := make(map[string]string) + addClaims := func(index map[string]map[entry]struct{}, rel string, kind mirrorKind) { + parts := strings.Split(rel, "/") + for i := range parts { + claimKind := mirrorDir + if i == len(parts)-1 { + claimKind = kind + } + claimRel := strings.Join(parts[:i+1], "/") + key := mirrorPathKey(claimRel) + if index[key] == nil { + index[key] = make(map[entry]struct{}) + } + index[key][entry{rel: claimRel, kind: claimKind}] = struct{}{} + } + } + addLocal := func(rel string, kind mirrorKind) { + if msg := mirrorLocalRelError(rel); msg != "" { + failures[rel] = msg + } + addClaims(local, rel, kind) + } + for _, rel := range localDirs { + addLocal(rel, mirrorDir) + } + for _, f := range localFiles { + addLocal(f.RelPath, mirrorFile) + } + for rel := range remoteFolders { + if rel != "" { + addClaims(remote, rel, mirrorDir) + } + } + for rel := range remoteFiles { + addClaims(remote, rel, mirrorFile) + } + keys := make(map[string]struct{}, len(local)+len(remote)) + for key := range local { + keys[key] = struct{}{} + } + for key := range remote { + keys[key] = struct{}{} + } + for key := range keys { + claims := make(map[entry]struct{}, len(local[key])+len(remote[key])) + for claim := range local[key] { + claims[claim] = struct{}{} + } + for claim := range remote[key] { + claims[claim] = struct{}{} + } + if len(claims) <= 1 { + continue + } + for claim := range claims { + failures[claim.rel] = fmt.Sprintf("%s路径 %q 在镜像规则下存在大小写/Unicode NFC 等价路径拼写或类型歧义，已中止镜像", claim.kind, claim.rel) + } + } + return failures +} + +func mirrorPreflightFailureRels(preflight map[string]string) []string { + rels := make([]string, 0, len(preflight)) + for rel := range preflight { + rels = append(rels, rel) + } + sort.Strings(rels) + return rels +} + // walkLocalForPushEntry 是 walkLocalForPush 的单条目处理逻辑。抽成命名函数只为可测： // filepath.Rel / Info() 的失败在真实 WalkDir 下几乎不可复现，单测可直接注入。 func walkLocalForPushEntry(root, path string, d fs.DirEntry, err error, dirs *[]string, files *[]localPushFile) error { @@ -430,6 +675,7 @@ func walkLocalForPushEntry(root, path string, d fs.DirEntry, err error, dirs *[] AbsPath: path, ModTimeMillis: info.ModTime().UnixMilli(), Size: info.Size(), + scanInfo: info, }) return nil } @@ -457,6 +703,51 @@ func pushCreateFolder(ctx context.Context, spaceID, parentID, name string) (stri // commit_upload 两个阶段都传 overwriteFileId、都不传 parentId（服务端据此设置 // conflictStrategy=OVERWRITE，原地覆盖而非在同目录新建重名副本）。 func pushUploadFile(ctx context.Context, spaceID, parentID, overwriteFileID, fileName, filePath string, fileSize int64) error { + return pushUploadWithTransport(ctx, spaceID, parentID, overwriteFileID, fileName, fileSize, + func(resourceURL string, ossHeaders map[string]string) error { + return httpPutFile(ctx, resourceURL, ossHeaders, filePath, fileSize) + }) +} + +// pushUploadFilePinned 从固定本地根打开 rel_path，并在发出 get_upload_info 前核对 +// 文件身份与扫描快照。HTTP PUT 只读取这个已打开句柄，绝不按 AbsPath 二次解析。 +func pushUploadFilePinned(ctx context.Context, spaceID, parentID, overwriteFileID, fileName string, root *pinnedPullRoot, local localPushFile) error { + if err := root.verify(); err != nil { + return err + } + file, err := root.root.Open(filepath.FromSlash(local.RelPath)) + if err != nil { + return fmt.Errorf("打开本地上传文件失败: %w", err) + } + defer file.Close() + info, err := pushStatOpenedFile(file) + if err != nil { + return fmt.Errorf("读取本地上传文件身份失败: %w", err) + } + if !info.Mode().IsRegular() { + return fmt.Errorf("本地上传目标 %q 已不再是常规文件", local.RelPath) + } + if local.scanInfo != nil && !os.SameFile(local.scanInfo, info) { + return fmt.Errorf("本地上传目标 %q 在扫描后被替换，已中止上传", local.RelPath) + } + if info.Size() != local.Size || info.ModTime().UnixMilli() != local.ModTimeMillis { + return fmt.Errorf("本地上传目标 %q 在扫描后发生变化，已中止上传", local.RelPath) + } + if err := pushVerifyPinnedSourceRoot(root); err != nil { + return err + } + return pushUploadWithTransport(ctx, spaceID, parentID, overwriteFileID, fileName, local.Size, + func(resourceURL string, ossHeaders map[string]string) error { + if err := pushPutOpenedFile(ctx, resourceURL, ossHeaders, file, local.Size); err != nil { + return err + } + // OSS 传输期间若命令行根已被替换，不提交这个上传会话；已发送的字节仍来自 + // 固定根内的原文件句柄，不可能读取替代路径或根外内容。 + return root.verify() + }) +} + +func pushUploadWithTransport(ctx context.Context, spaceID, parentID, overwriteFileID, fileName string, fileSize int64, put func(string, map[string]string) error) error { step1 := map[string]any{"fileName": fileName, "fileSize": float64(fileSize)} if spaceID != "" { step1["spaceId"] = spaceID @@ -474,7 +765,7 @@ func pushUploadFile(ctx context.Context, spaceID, parentID, overwriteFileID, fil if err != nil { return err } - if err := httpPutFile(ctx, resourceURL, ossHeaders, filePath, fileSize); err != nil { + if err := put(resourceURL, ossHeaders); err != nil { return err } commit := map[string]any{"fileName": fileName, "fileSize": float64(fileSize), "uploadId": uploadID} @@ -486,8 +777,46 @@ func pushUploadFile(ctx context.Context, spaceID, parentID, overwriteFileID, fil } else if parentID != "" { commit["parentId"] = parentID } - _, err = callMCPToolReturnText(ctx, "commit_upload", commit) - return err + commitText, err := callMCPToolReturnText(ctx, "commit_upload", commit) + if err != nil { + return err + } + if strings.TrimSpace(commitText) == "" { + return fmt.Errorf("commit_upload returned no business result; remote effect is unknown") + } + var result map[string]any + if err := json.Unmarshal([]byte(commitText), &result); err != nil { + return fmt.Errorf("parse commit_upload response: %w", err) + } + if len(result) == 0 { + return fmt.Errorf("commit_upload returned an empty JSON object; remote effect is unknown") + } + return nil +} + +func defaultPushPutOpenedFile(ctx context.Context, url string, headers map[string]string, file *os.File, fileSize int64) error { + if _, err := file.Seek(0, io.SeekStart); err != nil { + return fmt.Errorf("failed to seek upload file: %w", err) + } + req, err := http.NewRequestWithContext(ctx, http.MethodPut, url, file) + if err != nil { + return fmt.Errorf("failed to create upload request: %w", err) + } + req.ContentLength = fileSize + req.Header.Del("Content-Type") + for key, value := range headers { + req.Header.Set(key, value) + } + resp, err := (&http.Client{Timeout: 5 * time.Minute}).Do(req) + if err != nil { + return fmt.Errorf("file upload failed: %w", err) + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + body, _ := io.ReadAll(resp.Body) + return fmt.Errorf("OSS upload failed: %w", &httpStatusError{StatusCode: resp.StatusCode, Body: string(body)}) + } + return nil } // parseNodeID 从 create_folder / commit 等返回里抽出节点 fileId（带 fallback）。 diff --git a/internal/helpers/drive_push_coverage_test.go b/internal/helpers/drive_push_coverage_test.go index 494ef24c..56a22960 100644 --- a/internal/helpers/drive_push_coverage_test.go +++ b/internal/helpers/drive_push_coverage_test.go @@ -9,6 +9,8 @@ import ( "strconv" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) var errTestUpload = errors.New("simulated upload failure") @@ -35,8 +37,7 @@ func pushOKCaller(listing map[string]string) *driveScriptCaller { func withNoopPut(t *testing.T) { t.Helper() - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) - t.Cleanup(func() { SetHTTPPutFile(nil) }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) } // ────────────────────────────────────────────────────────── @@ -220,8 +221,7 @@ func TestCrossPlatformCoverageDrivePush_ifExistsSmart(t *testing.T) { func TestCrossPlatformCoverageDrivePush_uploadFailureExitsNonZero(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "local") - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) - t.Cleanup(func() { SetHTTPPutFile(nil) }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return errTestUpload }) caller := pushOKCaller(nil) err := runDriveCmd(t, caller, "push", "--local-folder", dir, "--remote-folder", "ROOT") @@ -306,10 +306,8 @@ func TestCrossPlatformCoverageWalkRemoteForPush_paginationRecursionAndSkips(t *t return `{"result":{"items":[],"nextToken":""}}`, nil }} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) files, folders, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT") if err != nil { @@ -333,10 +331,8 @@ func TestCrossPlatformCoverageWalkRemoteForPush_depthLimitAborts(t *testing.T) { caller := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil }} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) if _, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT"); err == nil || !strings.Contains(err.Error(), "循环引用") { @@ -413,18 +409,13 @@ func TestCrossPlatformCoveragePushUploadFile_failureBranches(t *testing.T) { for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: &driveScriptCaller{reply: tc.reply}, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} + testseam.Swap(t, &deps, &Deps{Caller: &driveScriptCaller{reply: tc.reply}, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) put := tc.put if put == nil { put = func(context.Context, string, map[string]string, string, int64) error { return nil } } - SetHTTPPutFile(put) - t.Cleanup(func() { - deps, os.Args = prevDeps, prevArgs - SetHTTPPutFile(nil) - }) + testseam.Swap(t, &httpPutFile, put) if err := pushUploadFile(context.Background(), "SP", "PARENT", "", "a.txt", p, 7); err == nil { t.Fatal("expected upload failure") @@ -435,13 +426,11 @@ func TestCrossPlatformCoveragePushUploadFile_failureBranches(t *testing.T) { // pushCreateFolder：MCP 失败上抛，成功时从返回体提取 fileId。 func TestCrossPlatformCoveragePushCreateFolder_errorAndSuccess(t *testing.T) { - prevDeps, prevArgs := deps, os.Args - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) - deps = &Deps{Caller: &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { + testseam.Swap(t, &deps, &Deps{Caller: &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return "", errTestUpload - }}, Out: &Formatter{w: io.Discard}} + }}, Out: &Formatter{w: io.Discard}}) if _, err := pushCreateFolder(context.Background(), "", "P", "n"); err == nil { t.Fatal("expected create_folder error to propagate") } @@ -449,7 +438,7 @@ func TestCrossPlatformCoveragePushCreateFolder_errorAndSuccess(t *testing.T) { ok := &driveScriptCaller{reply: func(string, map[string]any, int) (string, error) { return `{"result":{"fileId":"FID42"},"success":true}`, nil }} - deps = &Deps{Caller: ok, Out: &Formatter{w: io.Discard}} + testseam.Swap(t, &deps, &Deps{Caller: ok, Out: &Formatter{w: io.Discard}}) got, err := pushCreateFolder(context.Background(), "SP", "P", "n") if err != nil || got != "FID42" { t.Fatalf("pushCreateFolder = (%q, %v), want (FID42, nil)", got, err) diff --git a/internal/helpers/drive_push_sync_final_coverage_test.go b/internal/helpers/drive_push_sync_final_coverage_test.go new file mode 100644 index 00000000..ddbe2a8b --- /dev/null +++ b/internal/helpers/drive_push_sync_final_coverage_test.go @@ -0,0 +1,632 @@ +package helpers + +import ( + "context" + "crypto/md5" + "encoding/base64" + "errors" + "io" + "io/fs" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +var errDriveFinalCoverage = errors.New("drive final coverage failure") + +func openDriveFinalCoverageRoot(t *testing.T) (string, *pinnedPullRoot, localPushFile) { + t.Helper() + rootPath := t.TempDir() + path := filepath.Join(rootPath, "a.txt") + mustWrite(t, path, "payload") + info, err := os.Lstat(path) + if err != nil { + t.Fatal(err) + } + root, err := openExistingPinnedPullRoot(rootPath) + if err != nil { + t.Fatal(err) + } + t.Cleanup(root.close) + return rootPath, root, localPushFile{ + RelPath: "a.txt", AbsPath: path, Size: info.Size(), + ModTimeMillis: info.ModTime().UnixMilli(), scanInfo: info, + } +} + +func TestCrossPlatformCoverageDrivePushFinalMD5AndPinnedMatchEdges(t *testing.T) { + t.Run("default md5 success and read failure", func(t *testing.T) { + path := filepath.Join(t.TempDir(), "payload") + mustWrite(t, path, "payload") + file, err := os.Open(path) + if err != nil { + t.Fatal(err) + } + got, err := pushMD5OpenedFile(file) + _ = file.Close() + wantSum := md5.Sum([]byte("payload")) + want := base64.StdEncoding.EncodeToString(wantSum[:]) + if err != nil || got != want { + t.Fatalf("md5=(%q,%v), want %q", got, err, want) + } + if _, err := pushMD5OpenedFile(file); err == nil { + t.Fatal("closed file must fail MD5 reading") + } + }) + + t.Run("open failure", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + local.RelPath = "missing.txt" + if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil { + t.Fatal("missing file must fail exact matching") + } + }) + + t.Run("stat and identity failures", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &pushStatOpenedFile, func(*os.File) (os.FileInfo, error) { + return nil, errDriveFinalCoverage + }) + if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil { + t.Fatal("opened file stat failure must abort matching") + } + }) + + t.Run("directory and replaced scan identity", func(t *testing.T) { + rootPath, root, local := openDriveFinalCoverageRoot(t) + if _, err := judgePinnedPushFileMatch(root, localPushFile{RelPath: "."}, &remoteFile{Hash: "x"}, false); err == nil { + t.Fatal("directory must not be hashed as a regular file") + } + other := filepath.Join(rootPath, "other.txt") + mustWrite(t, other, "other") + otherInfo, _ := os.Lstat(other) + local.scanInfo = otherInfo + if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil { + t.Fatal("scan identity mismatch must abort matching") + } + }) + + t.Run("hash failure and root verification", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &pushMD5OpenedFile, func(*os.File) (string, error) { + return "", errDriveFinalCoverage + }) + if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "x"}, false); err == nil { + t.Fatal("hash read failure must abort matching") + } + }) + + t.Run("root verification and both verdicts", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + sum := md5.Sum([]byte("payload")) + hash := base64.StdEncoding.EncodeToString(sum[:]) + testseam.Swap(t, &pushVerifyPinnedSourceRoot, func(*pinnedPullRoot) error { + return errDriveFinalCoverage + }) + if _, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: hash}, false); !errors.Is(err, errDriveFinalCoverage) { + t.Fatalf("root verification error=%v", err) + } + }) + + t.Run("unchanged and modified", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + sum := md5.Sum([]byte("payload")) + hash := base64.StdEncoding.EncodeToString(sum[:]) + if got, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: hash}, false); err != nil || got != matchUnchanged { + t.Fatalf("equal hash=(%q,%v)", got, err) + } + if got, err := judgePinnedPushFileMatch(root, local, &remoteFile{Hash: "different"}, false); err != nil || got != matchModified { + t.Fatalf("different hash=(%q,%v)", got, err) + } + }) +} + +func TestCrossPlatformCoverageDrivePushFinalPinnedUploadGuards(t *testing.T) { + t.Run("initial root replacement", func(t *testing.T) { + rootPath, root, local := openDriveFinalCoverageRoot(t) + moved := filepath.Join(filepath.Dir(rootPath), "moved-root") + replacePinnedMirrorRoot(t, rootPath, moved) + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil { + t.Fatal("replaced root must abort before opening upload") + } + }) + + t.Run("open and stat failures", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + _ = root.root.Close() + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil { + t.Fatal("closed pinned root must fail file open") + } + }) + + t.Run("opened file stat failure", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &pushStatOpenedFile, func(*os.File) (os.FileInfo, error) { + return nil, errDriveFinalCoverage + }) + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); err == nil { + t.Fatal("stat failure must abort upload") + } + }) + + t.Run("non regular replaced and changed", func(t *testing.T) { + rootPath, root, local := openDriveFinalCoverageRoot(t) + if err := pushUploadFilePinned(context.Background(), "", "P", "", "root", root, localPushFile{RelPath: "."}); err == nil { + t.Fatal("directory upload must fail") + } + other := filepath.Join(rootPath, "other") + mustWrite(t, other, "other") + otherInfo, _ := os.Lstat(other) + replaced := local + replaced.scanInfo = otherInfo + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, replaced); err == nil { + t.Fatal("replaced scan identity must fail") + } + changed := local + changed.Size++ + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, changed); err == nil { + t.Fatal("changed size must fail") + } + }) + + t.Run("second root verification", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &pushVerifyPinnedSourceRoot, func(*pinnedPullRoot) error { + return errDriveFinalCoverage + }) + if err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local); !errors.Is(err, errDriveFinalCoverage) { + t.Fatalf("second verification error=%v", err) + } + }) +} + +func TestCrossPlatformCoverageDrivePushFinalWalkAndCommandGates(t *testing.T) { + t.Run("command scan errors", func(t *testing.T) { + for _, command := range []string{"push", "sync"} { + t.Run(command, func(t *testing.T) { + testseam.Swap(t, &runDriveMirrorWalkLocalForPushPinned, func(*pinnedPullRoot) ([]string, []localPushFile, error) { + return nil, nil, errDriveFinalCoverage + }) + err := runDriveCmd(t, pushOKCaller(nil), command, "--local-folder", t.TempDir(), "--remote-folder", "ROOT") + if !errors.Is(err, errDriveFinalCoverage) { + t.Fatalf("scan error=%v", err) + } + }) + } + }) + + t.Run("walk initial and callback errors", func(t *testing.T) { + rootPath, root, _ := openDriveFinalCoverageRoot(t) + moved := filepath.Join(filepath.Dir(rootPath), "moved-walk-root") + replacePinnedMirrorRoot(t, rootPath, moved) + if _, _, err := walkLocalForPushPinned(root); err == nil { + t.Fatal("initial root replacement must fail walk") + } + }) + + t.Run("walk entry info error", func(t *testing.T) { + _, root, _ := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, fn fs.WalkDirFunc) error { + return fn("bad", errDirEntry{}, nil) + }) + if _, _, err := walkLocalForPushPinned(root); !errors.Is(err, errTestInfo) { + t.Fatalf("walk info error=%v", err) + } + }) + + t.Run("walk final root verification", func(t *testing.T) { + rootPath, root, _ := openDriveFinalCoverageRoot(t) + moved := filepath.Join(filepath.Dir(rootPath), "moved-after-walk") + testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, _ fs.WalkDirFunc) error { + replacePinnedMirrorRoot(t, rootPath, moved) + return nil + }) + if _, _, err := walkLocalForPushPinned(root); err == nil { + t.Fatal("post-walk root replacement must fail") + } + }) + + t.Run("regular entry", func(t *testing.T) { + var dirs []string + var files []localPushFile + if err := walkLocalForPushEntry("/root", "/root/a", regularDirEntry{}, nil, &dirs, &files); err != nil || len(files) != 1 { + t.Fatalf("files=%v err=%v", files, err) + } + }) + + t.Run("root replacement between folder writes", func(t *testing.T) { + for _, command := range []string{"push", "sync"} { + t.Run(command, func(t *testing.T) { + parent := t.TempDir() + rootPath := filepath.Join(parent, "root") + if err := os.MkdirAll(filepath.Join(rootPath, "a"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.MkdirAll(filepath.Join(rootPath, "b"), 0o755); err != nil { + t.Fatal(err) + } + moved := filepath.Join(parent, "moved") + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + switch tool { + case "list_files": + return `{"result":{"items":[]}}`, nil + case "create_folder": + if nth == 0 { + replacePinnedMirrorRoot(t, rootPath, moved) + } + return `{"result":{"fileId":"DIR"}}`, nil + default: + return `{"result":{"fileId":"FILE"}}`, nil + } + }} + args := []string{command, "--local-folder", rootPath, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + if err := runDriveCmd(t, caller, args...); err == nil || !strings.Contains(err.Error(), "本地根目录") { + t.Fatalf("root replacement error=%v", err) + } + }) + } + }) +} + +func TestCrossPlatformCoverageDrivePushFinalDefaultOpenedPUTAndCommit(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) { + if request.Header.Get("X-Test") != "yes" { + t.Errorf("header=%q", request.Header.Get("X-Test")) + } + if request.URL.Path == "/status" { + http.Error(w, "denied", http.StatusTeapot) + return + } + _, _ = io.Copy(io.Discard, request.Body) + })) + defer server.Close() + path := filepath.Join(t.TempDir(), "payload") + mustWrite(t, path, "payload") + put := func(ctx context.Context, url string, headers map[string]string) error { + file, err := os.Open(path) + if err != nil { + return err + } + defer file.Close() + return defaultPushPutOpenedFile(ctx, url, headers, file, 7) + } + if err := put(context.Background(), ":", nil); err == nil { + t.Fatal("invalid PUT URL must fail") + } + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + if err := put(cancelled, server.URL, nil); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled PUT error=%v", err) + } + if err := put(context.Background(), server.URL+"/status", map[string]string{"X-Test": "yes"}); err == nil { + t.Fatal("non-200 PUT must fail") + } + if err := put(context.Background(), server.URL+"/ok", map[string]string{"X-Test": "yes"}); err != nil { + t.Fatal(err) + } + closed, err := os.Open(path) + if err != nil { + t.Fatal(err) + } + _ = closed.Close() + if err := defaultPushPutOpenedFile(context.Background(), server.URL, nil, closed, 7); err == nil { + t.Fatal("closed upload file must fail seek") + } + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "get_upload_info" { + return `{"result":{"resourceUrls":[{"url":"https://upload.invalid","headers":{}}],"uploadId":"U"}}`, nil + } + return "{", nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + if err := pushUploadWithTransport(context.Background(), "", "P", "", "a.txt", 7, func(string, map[string]string) error { return nil }); err == nil || !strings.Contains(err.Error(), "parse commit_upload") { + t.Fatalf("malformed commit error=%v", err) + } +} + +func TestCrossPlatformCoverageDriveSyncFinalPreflightAndKeepBothErrors(t *testing.T) { + t.Run("local target preflight lstat error and directory", func(t *testing.T) { + _, root, _ := openDriveFinalCoverageRoot(t) + failures := map[string]string{} + testseam.Swap(t, &pullRootLstat, func(*os.Root, string) (os.FileInfo, error) { + return nil, errDriveFinalCoverage + }) + addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"remote.txt": {}}, failures) + if !strings.Contains(failures["remote.txt"], "检查本地目标失败") { + t.Fatalf("failures=%v", failures) + } + }) + + t.Run("local target preflight walks existing directory", func(t *testing.T) { + rootPath, root, _ := openDriveFinalCoverageRoot(t) + if err := os.Mkdir(filepath.Join(rootPath, "sub"), 0o755); err != nil { + t.Fatal(err) + } + failures := map[string]string{} + addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"sub/remote.txt": {}}, failures) + if len(failures) != 0 { + t.Fatalf("failures=%v", failures) + } + addPinnedLocalTargetPreflightFailures(root, map[string]*remoteFile{"sub": {}}, failures) + if failures["sub"] == "" { + t.Fatal("terminal directory must fail file target preflight") + } + }) + + t.Run("wrapper root failures", func(t *testing.T) { + path := filepath.Join(t.TempDir(), "file") + mustWrite(t, path, "x") + pullResult := &driveSyncResult{} + syncPullFile(pullResult, context.Background(), "", &remoteFile{}, path, "a", syncDirectionPull) + if pullResult.Summary.Failed != 1 { + t.Fatalf("pull result=%#v", pullResult) + } + keepResult := &driveSyncResult{} + syncKeepBoth(keepResult, context.Background(), "", &remoteFile{}, path, "a", map[string]bool{}) + if keepResult.Summary.Failed != 1 { + t.Fatalf("keep result=%#v", keepResult) + } + }) + + t.Run("missing and non-regular local versions", func(t *testing.T) { + rootPath := t.TempDir() + missing := &driveSyncResult{} + syncKeepBoth(missing, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "missing.txt", map[string]bool{}) + if missing.Summary.Failed != 1 || !strings.Contains(missing.Items[0].Error, "不存在") { + t.Fatalf("missing result=%#v", missing) + } + if err := os.Mkdir(filepath.Join(rootPath, "dir"), 0o755); err != nil { + t.Fatal(err) + } + nonRegular := &driveSyncResult{} + syncKeepBoth(nonRegular, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "dir", map[string]bool{}) + if nonRegular.Summary.Failed != 1 || !strings.Contains(nonRegular.Items[0].Error, "不是常规文件") { + t.Fatalf("non-regular result=%#v", nonRegular) + } + }) + + t.Run("saved identity mismatch", func(t *testing.T) { + rootPath := t.TempDir() + mustWrite(t, filepath.Join(rootPath, "a.txt"), "local") + other := filepath.Join(t.TempDir(), "other") + mustWrite(t, other, "other") + otherInfo, _ := os.Lstat(other) + candidate := filepath.FromSlash(syncKeepBothCandidate("a.txt", "F", 0)) + testseam.Swap(t, &pullRootLstat, func(root *os.Root, name string) (os.FileInfo, error) { + if name == candidate { + return otherInfo, nil + } + return root.Lstat(name) + }) + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", map[string]bool{}) + if res.Summary.Failed != 1 || !strings.Contains(res.Items[0].Error, "身份不一致") { + t.Fatalf("result=%#v", res) + } + }) + + t.Run("nil transfer error fallback", func(t *testing.T) { + rootPath := t.TempDir() + mustWrite(t, filepath.Join(rootPath, "a.txt"), "local") + testseam.Swap(t, &syncPullOneFilePinned, func(context.Context, string, *remoteFile, *pinnedPullTarget, string) (string, error) { + return pullActionFailed, nil + }) + res := &driveSyncResult{} + syncKeepBoth(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", map[string]bool{}) + if res.Summary.Failed != 1 || !strings.Contains(res.Items[0].Error, "未能拉取") { + t.Fatalf("result=%#v", res) + } + }) + + t.Run("unsafe candidate and parent verification", func(t *testing.T) { + rootPath := t.TempDir() + mustWrite(t, filepath.Join(rootPath, "a.txt"), "local") + target, err := openPinnedPullTarget(rootPath, "a.txt") + if err != nil { + t.Fatal(err) + } + if _, _, err := reserveSyncKeepBothTargetPinned(target, "\x00", "", map[string]bool{}); err == nil { + t.Fatal("unsafe candidate must fail") + } + target.close() + + target, err = openPinnedPullTarget(rootPath, "a.txt") + if err != nil { + t.Fatal(err) + } + defer target.close() + moved := filepath.Join(filepath.Dir(rootPath), "moved-keep-root") + replacePinnedMirrorRoot(t, rootPath, moved) + if _, _, err := reserveSyncKeepBothTargetPinned(target, "a.txt", "", map[string]bool{}); err == nil { + t.Fatal("replaced parent must fail before link") + } + }) +} + +type driveFinalCallbackReader struct{ callback func() } + +func (reader driveFinalCallbackReader) Read(buffer []byte) (int, error) { + reader.callback() + return copy(buffer, "s\n"), nil +} + +func TestCrossPlatformCoverageDriveSyncFinalPostDecisionRootVerification(t *testing.T) { + parent := t.TempDir() + rootPath := filepath.Join(parent, "root") + if err := os.Mkdir(rootPath, 0o755); err != nil { + t.Fatal(err) + } + path := filepath.Join(rootPath, "a.txt") + mustWrite(t, path, "local") + mtime := readFileMTimeMillis(t, path) + moved := filepath.Join(parent, "moved") + testseam.Swap(t, &syncAskStdin, io.Reader(driveFinalCallbackReader{callback: func() { + replacePinnedMirrorRoot(t, rootPath, moved) + }})) + caller := syncCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F","modifyTime":` + differentMillis(mtime) + `}]}}`, + }) + err := runDriveCmd(t, caller, "sync", "--local-folder", rootPath, "--remote-folder", "ROOT", "--quick", "--on-conflict", "ask") + if err == nil || !strings.Contains(err.Error(), "本地根目录") { + t.Fatalf("post-decision root verification error=%v", err) + } +} + +func TestCrossPlatformCoverageDrivePushSyncFinalCommandValidationAndPrintErrors(t *testing.T) { + for _, command := range []string{"push", "sync"} { + t.Run(command+" required", func(t *testing.T) { + cmd := findDriveSubcommand(t, command) + var err error + if command == "push" { + err = runDrivePush(cmd, nil) + } else { + err = runDriveSync(cmd, nil) + } + if err == nil || !strings.Contains(err.Error(), "required") { + t.Fatalf("required error=%v", err) + } + }) + + t.Run(command+" relative", func(t *testing.T) { + cmd := findDriveSubcommand(t, command) + mustSetFlags(t, cmd, map[string]string{"local-folder": "relative", "remote-folder": "ROOT"}) + var err error + if command == "push" { + err = runDrivePush(cmd, nil) + } else { + err = runDriveSync(cmd, nil) + } + if err == nil || !strings.Contains(err.Error(), "绝对路径") { + t.Fatalf("relative error=%v", err) + } + }) + + t.Run(command+" preflight print", func(t *testing.T) { + rootPath := t.TempDir() + mustWrite(t, filepath.Join(rootPath, "A.txt"), "local") + caller := pushOKCaller(map[string]string{ + "ROOT": `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"F"}]}}`, + }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", command}) + cmd := findDriveSubcommand(t, command) + flags := map[string]string{"local-folder": rootPath, "remote-folder": "ROOT"} + if command == "sync" { + flags["quick"] = "true" + } + mustSetFlags(t, cmd, flags) + var err error + if command == "push" { + err = runDrivePush(cmd, nil) + } else { + err = runDriveSync(cmd, nil) + } + if err == nil || !strings.Contains(err.Error(), "write failed") { + t.Fatalf("PrintJSON error=%v", err) + } + }) + } +} + +func TestCrossPlatformCoverageDriveSyncFinalPullWrapperSuccess(t *testing.T) { + rootPath := t.TempDir() + installPinnedPullSuccess(t) + res := &driveSyncResult{} + syncPullFile(res, context.Background(), "", &remoteFile{FileID: "F"}, rootPath, "a.txt", syncDirectionPull) + if res.Summary.Pulled != 1 || res.Summary.Failed != 0 { + t.Fatalf("result=%#v", res) + } +} + +func TestCrossPlatformCoverageDrivePushFinalPureRemainingEdges(t *testing.T) { + if got := mirrorLocalRelError("good/../bad"); got == "" { + t.Fatal("unsafe local mirror segment must fail") + } + failures := buildMirrorPreflight(nil, []localPushFile{{RelPath: "bad\x00name"}}, nil, nil) + if failures["bad\x00name"] == "" { + t.Fatalf("failures=%v", failures) + } + if got := parseNodeID("{"); got != "" { + t.Fatalf("malformed node ID=%q", got) + } +} + +func TestCrossPlatformCoverageDrivePushFinalRemoteWalkerFailClosedEdges(t *testing.T) { + cases := []struct { + name string + reply func(map[string]any) string + want string + }{ + { + name: "unsafe entry", + reply: func(map[string]any) string { + return `{"result":{"items":[{"name":"../escape","type":"file","fileId":"F"}]}}` + }, + want: "无法安全映射", + }, + { + name: "duplicate folder", + reply: func(args map[string]any) string { + if args["parentId"] == "D" { + return `{"result":{"items":[]}}` + } + return `{"result":{"items":[{"name":"dir","type":"folder","fileId":"D"},{"name":"dir","type":"folder","fileId":"D"}]}}` + }, + want: "重复", + }, + { + name: "folder without ID", + reply: func(map[string]any) string { + return `{"result":{"items":[{"name":"dir","type":"folder"}]}}` + }, + want: "缺少目录 ID", + }, + { + name: "duplicate file", + reply: func(map[string]any) string { + return `{"result":{"items":[{"name":"a","type":"file","fileId":"A"},{"name":"a","type":"file","fileId":"A"}]}}` + }, + want: "重复", + }, + { + name: "file without ID", + reply: func(map[string]any) string { + return `{"result":{"items":[{"name":"a","type":"file"}]}}` + }, + want: "缺少文件 ID", + }, + { + name: "pagination cycle", + reply: func(map[string]any) string { + return `{"result":{"items":[],"nextToken":"P"}}` + }, + want: "分页 token 重复", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + caller := &driveScriptCaller{reply: func(tool string, args map[string]any, _ int) (string, error) { + if tool != "list_files" { + t.Fatalf("unexpected tool %s", tool) + } + return tc.reply(args), nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + _, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT") + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error=%v, want %q", err, tc.want) + } + }) + } +} diff --git a/internal/helpers/drive_push_test.go b/internal/helpers/drive_push_test.go index c424e75f..6999f407 100644 --- a/internal/helpers/drive_push_test.go +++ b/internal/helpers/drive_push_test.go @@ -1,7 +1,10 @@ package helpers import ( + "bytes" "context" + "encoding/json" + "fmt" "io" "os" "path/filepath" @@ -9,6 +12,7 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) @@ -140,9 +144,10 @@ type driveMCPCall struct { // driveSyncMockCaller 按工具名分发返回，并记录全部调用，供断言 MCP 参数。 type driveSyncMockCaller struct { - calls []driveMCPCall - listJSON string // list_files 返回体 - dryRun bool // --dry-run：只算差异，不执行任何写操作 + calls []driveMCPCall + listJSON string // list_files 返回体 + commitJSON *string // 非 nil 时覆盖 commit_upload 返回体（包括空响应） + dryRun bool // --dry-run：只算差异，不执行任何写操作 } func (m *driveSyncMockCaller) CallTool(_ context.Context, _ string, toolName string, args map[string]any) (*edition.ToolResult, error) { @@ -157,7 +162,13 @@ func (m *driveSyncMockCaller) CallTool(_ context.Context, _ string, toolName str case "download_file": // 返回可被 parseDriveDownloadInfo 解析的预签名下载链接。 text = `{"result":{"downloadUrl":"https://oss.example.com/get","headers":{}}}` - default: // commit_upload 等 + case "commit_upload": + if m.commitJSON != nil { + text = *m.commitJSON + } else { + text = `{"result":{"fileId":"NEW_FID"},"success":true}` + } + default: text = `{"result":{"fileId":"NEW_FID"},"success":true}` } return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil @@ -183,15 +194,12 @@ func (m *driveSyncMockCaller) callsFor(tool string) []driveMCPCall { } // runDrivePushTest 用 mock caller 执行 `drive push`，返回捕获的调用。 -// 注入 httpPutFile 为 no-op，避免真实 OSS 上传。 +// 注入已打开文件句柄的 PUT seam 为 no-op，避免真实 OSS 上传。 func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error { t.Helper() - prevDeps := deps - prevOSArgs := os.Args - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) - - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) root := &cobra.Command{Use: "dws"} root.PersistentFlags().BoolP("yes", "y", false, "") @@ -200,18 +208,51 @@ func runDrivePushTest(t *testing.T, caller *driveSyncMockCaller, localDir string // pull/push 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 full := append([]string{"push", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...) - os.Args = append([]string{"dws", "drive"}, full...) + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...)) root.SetArgs(append([]string{"drive"}, full...)) - t.Cleanup(func() { - deps = prevDeps - os.Args = prevOSArgs - SetHTTPPutFile(nil) - }) - return root.Execute() } +func runDriveMirrorUploadCommandCapture(t *testing.T, command string, caller *driveSyncMockCaller, localDir string) (error, string, int) { + t.Helper() + putCalls := 0 + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + putCalls++ + return nil + }) + var out bytes.Buffer + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().BoolP("yes", "y", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.AddCommand(newDriveCommand()) + full := []string{command, "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"} + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...)) + root.SetArgs(append([]string{"drive"}, full...)) + return root.Execute(), out.String(), putCalls +} + +func assertMirrorUploadFailedJSON(t *testing.T, output string) { + t.Helper() + var payload struct { + Summary struct { + Failed int `json:"failed"` + } `json:"summary"` + Items []struct { + Action string `json:"action"` + Error string `json:"error"` + } `json:"items"` + } + if err := json.Unmarshal([]byte(output), &payload); err != nil { + t.Fatalf("output is not structured JSON: %q: %v", output, err) + } + if payload.Summary.Failed != 1 || len(payload.Items) != 1 || payload.Items[0].Action != pushActionFailed || payload.Items[0].Error == "" { + t.Fatalf("structured failure=%#v", payload) + } +} + // 覆盖分支：get_upload_info 与 commit_upload 两阶段都必须传 overwriteFileId、都不传 parentId。 func TestCrossPlatformCoverageDrivePush_overwriteUsesOverwriteFileId(t *testing.T) { dir := t.TempDir() @@ -276,6 +317,36 @@ func TestCrossPlatformCoverageDrivePush_newUploadUsesParentId(t *testing.T) { } } +func TestCrossPlatformCoverageDrivePushRejectsUnknownCommitEffect(t *testing.T) { + for _, response := range []string{"", `{}`} { + t.Run(fmt.Sprintf("response-%q", response), func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "payload") + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[]}}`, + commitJSON: &response, + } + err, output, putCalls := runDriveMirrorUploadCommandCapture(t, "push", caller, dir) + if err == nil { + t.Fatal("empty commit result must make push exit non-zero") + } + if failure, ok := err.(*drivePushFailure); !ok || failure.ExitCode() != 1 { + t.Fatalf("error=%T %v", err, err) + } + assertMirrorUploadFailedJSON(t, output) + if putCalls != 1 { + t.Fatalf("OSS PUT calls=%d, want exactly 1", putCalls) + } + if got := len(caller.callsFor("get_upload_info")); got != 1 { + t.Fatalf("get_upload_info calls=%d, want 1", got) + } + if got := len(caller.callsFor("commit_upload")); got != 1 { + t.Fatalf("commit_upload calls=%d, want 1", got) + } + }) + } +} + func equalStrings(a, b []string) bool { if len(a) != len(b) { return false diff --git a/internal/helpers/drive_push_toctou_test.go b/internal/helpers/drive_push_toctou_test.go new file mode 100644 index 00000000..cfe0ccd3 --- /dev/null +++ b/internal/helpers/drive_push_toctou_test.go @@ -0,0 +1,136 @@ +package helpers + +import ( + "context" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func replacePinnedMirrorRoot(t *testing.T, root, moved string) { + t.Helper() + if err := os.Rename(root, moved); err != nil { + t.Fatalf("move pinned root: %v", err) + } + if err := os.Mkdir(root, 0o755); err != nil { + t.Fatalf("create replacement root: %v", err) + } + mustWrite(t, filepath.Join(root, "a.txt"), "outside-replacement") +} + +// 本地扫描完成后、任何 create_folder/get_upload_info/commit_upload 前若命令行根已 +// 被另一目录替换，push 与 sync 都必须整批失败，不能把替代目录当成扫描快照继续写远端。 +func TestCrossPlatformCoverageDrivePushSyncRejectRootReplacementBeforeRemoteWrite(t *testing.T) { + for _, command := range []string{"push", "sync"} { + t.Run(command, func(t *testing.T) { + parent := t.TempDir() + root := filepath.Join(parent, "root") + moved := filepath.Join(parent, "moved-original") + if err := os.Mkdir(root, 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(root, "a.txt"), "pinned-original") + + replaced := false + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool == "list_files" { + if !replaced { + replacePinnedMirrorRoot(t, root, moved) + replaced = true + } + return `{"result":{"items":[],"nextToken":""}}`, nil + } + return `{"result":{"fileId":"UNEXPECTED"},"success":true}`, nil + }} + putCalls := 0 + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + putCalls++ + return nil + }) + + args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + err := runDriveCmd(t, caller, args...) + if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") { + t.Fatalf("expected root replacement rejection, got %v", err) + } + for _, tool := range []string{"create_folder", "get_upload_info", "commit_upload"} { + if got := caller.callsFor(tool); len(got) != 0 { + t.Errorf("%s must not run after root replacement: %v", tool, got) + } + } + if putCalls != 0 { + t.Fatalf("OSS PUT must not run after root replacement, got %d", putCalls) + } + if b, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(b) != "outside-replacement" { + t.Fatalf("replacement tree changed: %q err=%v", string(b), err) + } + }) + } +} + +// 即使根在 get_upload_info 之后、OSS PUT 读取前被替换，PUT 也只能读取扫描时固定根 +// 打开的文件句柄。传输后身份复核会拒绝 commit，替代目录内容绝不能泄漏到上传流。 +func TestCrossPlatformCoverageDrivePushSyncUploadReadsPinnedFileHandle(t *testing.T) { + for _, command := range []string{"push", "sync"} { + t.Run(command, func(t *testing.T) { + parent := t.TempDir() + root := filepath.Join(parent, "root") + moved := filepath.Join(parent, "moved-original") + if err := os.Mkdir(root, 0o755); err != nil { + t.Fatal(err) + } + mustWrite(t, filepath.Join(root, "a.txt"), "pinned-original") + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + switch tool { + case "list_files": + return `{"result":{"items":[],"nextToken":""}}`, nil + case "get_upload_info": + return `{"result":{"resourceUrls":[{"url":"https://oss.example.com/put","headers":{}}],"uploadId":"U1"}}`, nil + } + return `{"result":{"fileId":"NEW"},"success":true}`, nil + }} + + var uploaded string + putCalls := 0 + testseam.Swap(t, &pushPutOpenedFile, func(_ context.Context, _ string, _ map[string]string, file *os.File, _ int64) error { + putCalls++ + replacePinnedMirrorRoot(t, root, moved) + body, err := io.ReadAll(file) + if err != nil { + return err + } + uploaded = string(body) + return nil + }) + + args := []string{command, "--local-folder", root, "--remote-folder", "ROOT"} + if command == "sync" { + args = append(args, "--quick") + } + err := runDriveCmd(t, caller, args...) + if err == nil { + t.Fatal("root replacement during PUT must prevent commit") + } + if putCalls != 1 || uploaded != "pinned-original" { + t.Fatalf("PUT read %q in %d call(s), want pinned-original once", uploaded, putCalls) + } + if commits := caller.callsFor("commit_upload"); len(commits) != 0 { + t.Fatalf("root replacement must prevent commit_upload: %v", commits) + } + if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "outside-replacement" { + t.Fatalf("replacement file was read or changed: %q err=%v", string(b), readErr) + } + if b, readErr := os.ReadFile(filepath.Join(moved, "a.txt")); readErr != nil || string(b) != "pinned-original" { + t.Fatalf("pinned original changed: %q err=%v", string(b), readErr) + } + }) + } +} diff --git a/internal/helpers/drive_push_type_conflict_test.go b/internal/helpers/drive_push_type_conflict_test.go index e6e294fb..d2d56435 100644 --- a/internal/helpers/drive_push_type_conflict_test.go +++ b/internal/helpers/drive_push_type_conflict_test.go @@ -7,13 +7,13 @@ import ( "os" "path/filepath" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) func TestCrossPlatformCoverageDrivePushDryRun_typeConflictsFail(t *testing.T) { var out bytes.Buffer - prevDeps := deps - deps = &Deps{Out: &Formatter{w: &out}} - t.Cleanup(func() { deps = prevDeps }) + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}}) tests := []struct { name string diff --git a/internal/helpers/drive_remote_duplicate_test.go b/internal/helpers/drive_remote_duplicate_test.go index d8b25830..b027575b 100644 --- a/internal/helpers/drive_remote_duplicate_test.go +++ b/internal/helpers/drive_remote_duplicate_test.go @@ -6,6 +6,8 @@ import ( "os" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) func TestCrossPlatformCoverageDriveRemoteTree_duplicatePathsFail(t *testing.T) { @@ -70,10 +72,8 @@ func TestCrossPlatformCoverageDriveRemoteTree_duplicatePathsFail(t *testing.T) { for _, fetcher := range fetchers { t.Run(fetcher.name, func(t *testing.T) { caller := &driveScriptCaller{reply: tt.reply} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) err := fetcher.fetch(context.Background()) if err == nil || !strings.Contains(err.Error(), "重复远端路径") || !strings.Contains(err.Error(), tt.path) { diff --git a/internal/helpers/drive_remote_folder_id_test.go b/internal/helpers/drive_remote_folder_id_test.go index 364a6429..a791b010 100644 --- a/internal/helpers/drive_remote_folder_id_test.go +++ b/internal/helpers/drive_remote_folder_id_test.go @@ -6,6 +6,8 @@ import ( "os" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) func TestCrossPlatformCoverageDriveRemoteTree_folderIDFallbacks(t *testing.T) { @@ -20,10 +22,8 @@ func TestCrossPlatformCoverageDriveRemoteTree_folderIDFallbacks(t *testing.T) { } return `{"result":{"items":[],"nextToken":""}}`, nil }} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) if _, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true); err != nil { t.Fatalf("fetch with %s: %v", key, err) @@ -62,10 +62,8 @@ func TestCrossPlatformCoverageDriveRemoteTree_missingFolderIDFailsClosed(t *test } return `{"result":{"items":[{"name":"sub","type":"folder"}],"nextToken":""}}`, nil }} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) err := fetcher.fetch(context.Background()) if err == nil || !strings.Contains(err.Error(), "目录 ID") || !strings.Contains(err.Error(), "sub") { diff --git a/internal/helpers/drive_remote_tree_integrity_test.go b/internal/helpers/drive_remote_tree_integrity_test.go new file mode 100644 index 00000000..7f7e2437 --- /dev/null +++ b/internal/helpers/drive_remote_tree_integrity_test.go @@ -0,0 +1,309 @@ +package helpers + +import ( + "context" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageParseDriveList_requiresAuthoritativeResult(t *testing.T) { + tests := []struct { + name string + body string + wantError string + wantItems int + }{ + {name: "missing result", body: `{}`, wantError: "缺少 result"}, + {name: "null result", body: `{"result":null}`, wantError: "result 为 null"}, + {name: "empty result object", body: `{"result":{}}`, wantError: "缺少 items"}, + {name: "null item", body: `{"result":{"items":[null]}}`, wantError: "缺少有效 type"}, + {name: "empty item object", body: `{"result":{"items":[{}]}}`, wantError: "缺少有效 type"}, + {name: "item missing type", body: `{"result":{"items":[{"name":"unknown"}]}}`, wantError: "缺少有效 type"}, + {name: "item empty type", body: `{"result":{"items":[{"name":"unknown","type":" "}]}}`, wantError: "缺少有效 type"}, + {name: "has more without token", body: `{"result":{"items":[],"hasMore":true,"nextToken":""}}`, wantError: "hasMore=true"}, + {name: "empty items", body: `{"result":{"items":[]}}`}, + {name: "empty result array", body: `{"result":[]}`}, + {name: "explicit unsupported type remains parseable", body: `{"result":{"items":[{"name":"online.adoc","type":"document"}]}}`, wantItems: 1}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + items, token, err := parseDriveList(tt.body) + if tt.wantError != "" { + if err == nil || !strings.Contains(err.Error(), tt.wantError) { + t.Fatalf("parseDriveList error = %v, want containing %q", err, tt.wantError) + } + return + } + if err != nil { + t.Fatalf("parseDriveList(%s): %v", tt.body, err) + } + if len(items) != tt.wantItems || token != "" { + t.Fatalf("parseDriveList(%s) = (%v, %q), want %d authoritative item(s) with no token", tt.body, items, token, tt.wantItems) + } + }) + } +} + +func TestCrossPlatformCoverageDriveRemoteTree_integrityFailuresStopFourCommandsBeforeWrites(t *testing.T) { + failures := []struct { + name string + wantError string + wantListCalls int + reply func(int) string + }{ + { + name: "missing result", + wantError: "缺少 result", + wantListCalls: 1, + reply: func(int) string { return `{}` }, + }, + { + name: "null result", + wantError: "result 为 null", + wantListCalls: 1, + reply: func(int) string { return `{"result":null}` }, + }, + { + name: "empty result object", + wantError: "缺少 items", + wantListCalls: 1, + reply: func(int) string { return `{"result":{}}` }, + }, + { + name: "null item", + wantError: "缺少有效 type", + wantListCalls: 1, + reply: func(int) string { return `{"result":{"items":[null],"nextToken":""}}` }, + }, + { + name: "empty item object", + wantError: "缺少有效 type", + wantListCalls: 1, + reply: func(int) string { return `{"result":{"items":[{}],"nextToken":""}}` }, + }, + { + name: "item missing type", + wantError: "缺少有效 type", + wantListCalls: 1, + reply: func(int) string { + return `{"result":{"items":[{"name":"unknown"}],"nextToken":""}}` + }, + }, + { + name: "item empty type", + wantError: "缺少有效 type", + wantListCalls: 1, + reply: func(int) string { + return `{"result":{"items":[{"name":"unknown","type":""}],"nextToken":""}}` + }, + }, + { + name: "has more without token", + wantError: "hasMore=true", + wantListCalls: 1, + reply: func(int) string { + return `{"result":{"items":[],"hasMore":true,"nextToken":""}}` + }, + }, + { + name: "file without an ID", + wantError: "缺少文件 ID", + wantListCalls: 1, + reply: func(int) string { + return `{"result":{"items":[{"name":"remote.txt","type":"file"}],"nextToken":""}}` + }, + }, + { + name: "file name with an ASCII control", + wantError: "无法安全映射到本地路径", + wantListCalls: 1, + reply: func(int) string { + return `{"result":{"items":[{"name":"remote\u0000.txt","type":"file","fileId":"REMOTE"}],"nextToken":""}}` + }, + }, + { + name: "pagination token cycle", + wantError: "分页 token", + wantListCalls: 3, + reply: func(nth int) string { + tokens := []string{"PAGE_A", "PAGE_B", "PAGE_A"} + if nth >= len(tokens) { + return `{"result":{"items":[],"nextToken":""}}` + } + return fmt.Sprintf(`{"result":{"items":[],"nextToken":%q}}`, tokens[nth]) + }, + }, + } + + commands := []struct { + name string + args func(string) []string + prepare func(*testing.T, string) + }{ + { + name: "status", + args: func(localRoot string) []string { + return []string{"status", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"} + }, + prepare: prepareRemoteTreeReadRoot, + }, + { + name: "pull", + args: func(localRoot string) []string { + return []string{"pull", "--local-folder", localRoot, "--remote-folder", "ROOT"} + }, + }, + { + name: "push", + args: func(localRoot string) []string { + return []string{"push", "--local-folder", localRoot, "--remote-folder", "ROOT"} + }, + prepare: prepareRemoteTreeWriteSource, + }, + { + name: "sync", + args: func(localRoot string) []string { + return []string{"sync", "--local-folder", localRoot, "--remote-folder", "ROOT", "--quick"} + }, + prepare: prepareRemoteTreeWriteSource, + }, + } + + for _, failure := range failures { + t.Run(failure.name, func(t *testing.T) { + for _, command := range commands { + t.Run(command.name, func(t *testing.T) { + localRoot := filepath.Join(t.TempDir(), "mirror") + if command.prepare != nil { + command.prepare(t, localRoot) + } + + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, nth int) (string, error) { + if tool != "list_files" { + return "", fmt.Errorf("远端清单预检完成前调用了写工具 %s", tool) + } + return failure.reply(nth), nil + }} + getCalls, putCalls := swapRemoteTreeTransferCounters(t) + + err := runDriveCmd(t, caller, command.args(localRoot)...) + if err == nil || !strings.Contains(err.Error(), failure.wantError) { + t.Fatalf("error = %v, want remote tree integrity failure containing %q", err, failure.wantError) + } + if got := len(caller.callsFor("list_files")); got != failure.wantListCalls { + t.Fatalf("list_files calls = %d, want %d", got, failure.wantListCalls) + } + for _, call := range caller.calls { + if call.toolName != "list_files" { + t.Fatalf("remote tree integrity failure must stop before MCP writes, got %s", call.toolName) + } + } + if *getCalls != 0 || *putCalls != 0 { + t.Fatalf("remote tree integrity failure must stop before transfers: GET=%d PUT=%d", *getCalls, *putCalls) + } + if command.name == "pull" { + if _, statErr := os.Stat(localRoot); !os.IsNotExist(statErr) { + t.Fatalf("pull must fail before creating its local root: %v", statErr) + } + } + }) + } + }) + } +} + +func TestCrossPlatformCoverageDriveRemoteTree_validEmptyListsRemainSupported(t *testing.T) { + for _, listing := range []struct { + name string + body string + }{ + {name: "items object", body: `{"result":{"items":[]}}`}, + {name: "result array", body: `{"result":[]}`}, + } { + t.Run(listing.name, func(t *testing.T) { + for _, fetcher := range []struct { + name string + fetch func(context.Context) error + }{ + { + name: "status and pull walker", + fetch: func(ctx context.Context) error { + files, err := fetchRemoteDriveTree(ctx, "", "ROOT", true) + if len(files) != 0 { + return fmt.Errorf("remote files = %v, want empty", files) + } + return err + }, + }, + { + name: "push and sync walker", + fetch: func(ctx context.Context) error { + files, folders, err := fetchRemoteTreeForPush(ctx, "", "ROOT") + if len(files) != 0 || len(folders) != 1 || folders[""] != "ROOT" { + return fmt.Errorf("remote tree = files %v folders %v, want empty root", files, folders) + } + return err + }, + }, + } { + t.Run(fetcher.name, func(t *testing.T) { + caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { + if tool != "list_files" { + t.Fatalf("unexpected tool %s", tool) + } + return listing.body, nil + }} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + if err := fetcher.fetch(context.Background()); err != nil { + t.Fatalf("valid empty listing: %v", err) + } + if got := len(caller.callsFor("list_files")); got != 1 { + t.Fatalf("list_files calls = %d, want 1", got) + } + }) + } + }) + } +} + +func TestCrossPlatformCoverageIsSafeRemoteSegment_rejectsASCIIControls(t *testing.T) { + for _, name := range []string{"nul\x00name", "unit\x1fseparator", "delete\x7fcharacter"} { + if isSafeRemoteSegment(name) { + t.Errorf("isSafeRemoteSegment(%q) = true, want false", name) + } + } +} + +func prepareRemoteTreeReadRoot(t *testing.T, localRoot string) { + t.Helper() + if err := os.MkdirAll(localRoot, 0o755); err != nil { + t.Fatal(err) + } +} + +func prepareRemoteTreeWriteSource(t *testing.T, localRoot string) { + t.Helper() + mustWrite(t, filepath.Join(localRoot, "local.txt"), "local") +} + +func swapRemoteTreeTransferCounters(t *testing.T) (*int, *int) { + t.Helper() + getCalls, putCalls := 0, 0 + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { + getCalls++ + return nil + }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + putCalls++ + return nil + }) + return &getCalls, &putCalls +} diff --git a/internal/helpers/drive_remote_unsafe_name_test.go b/internal/helpers/drive_remote_unsafe_name_test.go index 393f2fb7..42737e11 100644 --- a/internal/helpers/drive_remote_unsafe_name_test.go +++ b/internal/helpers/drive_remote_unsafe_name_test.go @@ -83,11 +83,11 @@ func TestCrossPlatformCoverageDriveRemoteTree_unsafeNamesFailClosed(t *testing.T return tt.listing, nil }} getCalls, putCalls := 0, 0 - testseam.Swap(t, &httpGetFile, func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { getCalls++ return nil }) - testseam.Swap(t, &httpPutFile, func(context.Context, string, map[string]string, string, int64) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { putCalls++ return nil }) diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 09e9319b..4955dccf 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -1,6 +1,7 @@ package helpers import ( + "bytes" "context" "crypto/md5" "encoding/base64" @@ -107,6 +108,7 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m } nextToken := "" + seenTokens := make(map[string]struct{}) for { args := map[string]any{"maxResults": float64(driveListPageSize)} // space-id 为空则省略，交给 MCP Server 默认「我的文件」。 @@ -163,11 +165,15 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m if err := claimRemotePath(occupied, childRel, "文件"); err != nil { return err } + fileID := it.id() + if fileID == "" { + return fmt.Errorf("远端文件 %q 缺少文件 ID，已中止遍历", childRel) + } modMillis, modValid := it.modifiedMillis() out[childRel] = &remoteFile{ RelPath: childRel, - FileID: it.id(), + FileID: fileID, Hash: it.hash(), Size: it.size(), ModifiedTime: modMillis, @@ -175,10 +181,13 @@ func walkRemoteDir(ctx context.Context, spaceID, parentID, relBase string, out m } } - // 无下一页，或 token 未推进（防御性，避免服务端异常导致死循环）→ 结束。 - if token == "" || token == nextToken { + if token == "" { break } + if _, exists := seenTokens[token]; exists { + return fmt.Errorf("远端目录 %q 的分页 token 重复，疑似分页循环，已中止", relBase) + } + seenTokens[token] = struct{}{} nextToken = token } return nil @@ -280,37 +289,72 @@ func (d driveItem) modifiedMillis() (int64, bool) { // - {"result":{"items":[...],"nextToken":"..."}} // - {"result":[...]}（result 直接是条目数组，无分页） func parseDriveList(text string) ([]driveItem, string, error) { - var envelope struct { - Result json.RawMessage `json:"result"` - } + var envelope map[string]json.RawMessage if err := json.Unmarshal([]byte(text), &envelope); err != nil { return nil, "", fmt.Errorf("解析 list_files 返回失败: %w", err) } - if len(envelope.Result) == 0 { - return nil, "", nil // 无 result → 空列表 + result, exists := envelope["result"] + if !exists { + return nil, "", fmt.Errorf("解析 list_files 返回失败: 缺少 result") + } + result = json.RawMessage(bytes.TrimSpace(result)) + if bytes.Equal(result, []byte("null")) { + return nil, "", fmt.Errorf("解析 list_files 返回失败: result 为 null") } - toItems := func(ms []map[string]any) []driveItem { + toItems := func(ms []map[string]any) ([]driveItem, error) { items := make([]driveItem, 0, len(ms)) - for _, m := range ms { - items = append(items, driveItem(m)) + for index, m := range ms { + item := driveItem(m) + // FILE / FOLDER 之外的显式类型（在线文档、快捷方式等）可以由镜像 + // walker 跳过；但 null、空对象或缺少有效 type 的条目不是一个可判定的 + // 业务对象。静默跳过会把不完整清单伪装成权威目录，必须失败关闭。 + if m == nil || strings.TrimSpace(item.typ()) == "" { + return nil, fmt.Errorf("解析 list_files 返回失败: result.items[%d] 缺少有效 type", index) + } + items = append(items, item) } - return items + return items, nil } - // 形态一：result 是对象 {items, nextToken} - var obj struct { - Items []map[string]any `json:"items"` - NextToken string `json:"nextToken"` - } - if err := json.Unmarshal(envelope.Result, &obj); err == nil { - return toItems(obj.Items), obj.NextToken, nil - } - - // 形态二：result 直接是条目数组 - var arr []map[string]any - if err := json.Unmarshal(envelope.Result, &arr); err == nil { - return toItems(arr), "", nil + switch { + case len(result) > 0 && result[0] == '{': + // 形态一：result 是对象 {items, nextToken}。items 必须显式存在，不能把 + // 缺失/null 的非权威响应误判为空目录。 + var obj struct { + Items json.RawMessage `json:"items"` + NextToken string `json:"nextToken"` + HasMore *bool `json:"hasMore"` + } + if err := json.Unmarshal(result, &obj); err != nil { + return nil, "", fmt.Errorf("解析 list_files 返回失败: %w", err) + } + if len(obj.Items) == 0 { + return nil, "", fmt.Errorf("解析 list_files 返回失败: result 缺少 items") + } + var items []map[string]any + if err := json.Unmarshal(obj.Items, &items); err != nil || items == nil { + return nil, "", fmt.Errorf("解析 list_files 返回失败: result.items 不是数组") + } + if obj.HasMore != nil && *obj.HasMore && obj.NextToken == "" { + return nil, "", fmt.Errorf("解析 list_files 返回失败: hasMore=true 但 nextToken 为空，远端清单可能被截断") + } + parsed, err := toItems(items) + if err != nil { + return nil, "", err + } + return parsed, obj.NextToken, nil + case len(result) > 0 && result[0] == '[': + // 形态二：result 直接是条目数组。 + var arr []map[string]any + if err := json.Unmarshal(result, &arr); err != nil { + return nil, "", fmt.Errorf("解析 list_files 返回失败: result 数组无效: %w", err) + } + parsed, err := toItems(arr) + if err != nil { + return nil, "", err + } + return parsed, "", nil } return nil, "", fmt.Errorf("解析 list_files 返回失败: result 既不是 {items:[]} 也不是数组") @@ -328,12 +372,18 @@ func validateLocalDirAbs(localDir string) (string, error) { } // isSafeRemoteSegment 校验单个远端条目名称是否可安全用作一层相对路径段。 -// 拒绝空串、"."、".."、含卷标（如 Windows 的 "C:"）以及任意平台的路径分隔符 -// （/ 与 \）——这些成分拼进 rel_path 后可能让下载目标逃逸出本地根目录。 +// 拒绝空串、"."、".."、ASCII 控制字符、含卷标（如 Windows 的 "C:"）以及任意平台 +// 的路径分隔符（/ 与 \）——这些成分无法安全表示为本地文件名，或可能让下载目标逃逸 +// 出本地根目录。 func isSafeRemoteSegment(name string) bool { if name == "" || name == "." || name == ".." { return false } + for i := 0; i < len(name); i++ { + if name[i] <= 0x1f || name[i] == 0x7f { + return false + } + } // 任意平台分隔符都不允许出现在单层名称里。 if strings.ContainsAny(name, `/\`) { return false diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index fdfed660..3e9a3869 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -82,22 +82,15 @@ func runDriveCmd(t *testing.T, caller edition.ToolCaller, args ...string) error func runDriveCmdWithoutConfirm(t *testing.T, caller edition.ToolCaller, args ...string) error { t.Helper() - prevDeps := deps - prevOSArgs := os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) root := &cobra.Command{Use: "dws"} root.PersistentFlags().BoolP("yes", "y", false, "") root.PersistentFlags().Bool("dry-run", false, "") root.AddCommand(newDriveCommand()) - os.Args = append([]string{"dws", "drive"}, args...) + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, args...)) root.SetArgs(append([]string{"drive"}, args...)) - - t.Cleanup(func() { - deps = prevDeps - os.Args = prevOSArgs - }) return root.Execute() } @@ -138,8 +131,8 @@ func TestCrossPlatformCoverageDriveStatus_endToEndNestedTree(t *testing.T) { } } -// 分页：首页返回 nextToken，第二页取完；token 未推进时必须终止而非死循环。 -func TestCrossPlatformCoverageDriveStatus_paginationAndStalledToken(t *testing.T) { +// 分页 token 未推进意味着远端清单可能被截断，必须失败而不是把当前页当作 EOF。 +func TestCrossPlatformCoverageDriveStatus_stalledPaginationTokenFailsClosed(t *testing.T) { dir := t.TempDir() caller := &driveScriptCaller{reply: func(_ string, args map[string]any, nth int) (string, error) { @@ -153,17 +146,18 @@ func TestCrossPlatformCoverageDriveStatus_paginationAndStalledToken(t *testing.T if args["nextToken"] != "T1" { t.Errorf("second page nextToken = %v, want T1", args["nextToken"]) } - // 返回同一个 token → 未推进，必须 break。 + // 返回同一个 token → 未推进，必须 fail closed。 return `{"result":{"items":[{"name":"b.txt","type":"file","fileId":"B"}],"nextToken":"T1"}}`, nil } return `{"result":{"items":[],"nextToken":""}}`, nil }} - if err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { - t.Fatalf("unexpected error: %v", err) + err := runDriveCmd(t, caller, "status", "--local-folder", dir, "--remote-folder", "ROOT", "--quick") + if err == nil || !strings.Contains(err.Error(), "分页 token") { + t.Fatalf("error = %v, want stalled pagination failure", err) } if got := len(caller.callsFor("list_files")); got != 2 { - t.Fatalf("stalled token must stop paging after 2 calls, got %d", got) + t.Fatalf("stalled token must fail after 2 calls, got %d", got) } } @@ -256,14 +250,8 @@ func TestCrossPlatformCoverageWalkRemoteDir_depthLimitAborts(t *testing.T) { // 每层都返回一个同名子文件夹 → 无限深。 return `{"result":{"items":[{"name":"loop","type":"folder","fileId":"LOOP"}],"nextToken":""}}`, nil }} - prevDeps := deps - prevOSArgs := os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} // 工具路由需要命令上下文 - t.Cleanup(func() { - deps = prevDeps - os.Args = prevOSArgs - }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) // 工具路由需要命令上下文 _, err := fetchRemoteDriveTree(context.Background(), "", "ROOT", true) if err == nil || !strings.Contains(err.Error(), "循环引用") { diff --git a/internal/helpers/drive_status_windows.go b/internal/helpers/drive_status_windows.go index b9ef2de4..61241551 100644 --- a/internal/helpers/drive_status_windows.go +++ b/internal/helpers/drive_status_windows.go @@ -2,13 +2,16 @@ package helpers -import "path/filepath" +import ( + "path/filepath" + "strings" +) // isSafeRemoteSegmentPlatform 承载 Windows 专有的单层名称校验。 // -// 拒绝含盘符的名称（"C:"、"C:foo"）——Windows 上 filepath.VolumeName 会识别它们， -// 拼进 rel_path 后可让落盘目标逃逸出本地根目录；并在 Clean 改写名称时拒绝，兜住 -// 分隔符过滤之外的非规范形式。 +// 除盘符与 Clean 改写外，还拒绝 Win32 非法字符、尾随点/空格以及设备保留名。 +// 这些名称即使不造成词法逃逸，也可能无法落盘、落到 ADS，或与另一个名称映射到 +// 同一 Win32 对象；文件夹镜像必须在构建权威远端树时统一 fail closed。 func isSafeRemoteSegmentPlatform(name string) bool { if filepath.VolumeName(name) != "" { return false @@ -16,5 +19,34 @@ func isSafeRemoteSegmentPlatform(name string) bool { if filepath.Clean(name) != name { return false } + if strings.TrimRight(name, " .") != name { + return false + } + for _, char := range name { + if char < 0x20 || char == 0x7f || strings.ContainsRune(`<>:"|?*`, char) { + return false + } + } + if isWindowsReservedMirrorName(name) { + return false + } return true } + +func isWindowsReservedMirrorName(name string) bool { + base := name + if index := strings.IndexAny(base, ".:"); index >= 0 { + base = base[:index] + } + base = strings.ToUpper(strings.TrimRight(base, " .")) + switch base { + case "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$": + return true + } + if len(base) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) && base[3] >= '1' && base[3] <= '9' { + return true + } + runes := []rune(base) + return len(runes) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) && + strings.ContainsRune("¹²³", runes[3]) +} diff --git a/internal/helpers/drive_sync.go b/internal/helpers/drive_sync.go index d0baefb0..dad77166 100644 --- a/internal/helpers/drive_sync.go +++ b/internal/helpers/drive_sync.go @@ -14,11 +14,11 @@ import ( "github.com/spf13/cobra" ) -// syncRename 与 syncOpenFile 仅作为文件系统失败分支的确定性测试 seam；测试必须 -// 通过 testseam.Swap 替换并自动恢复。 +// keep-both 的本地保留副本通过同一个固定父目录 os.Root 原子建立硬链接；以下 seam +// 仅用于文件系统失败与并发替换的确定性测试，测试必须通过 testseam.Swap 替换。 var ( - syncRename = driveReplaceFile - syncOpenFile = os.OpenFile + syncRootLink = func(root *os.Root, oldName, newName string) error { return root.Link(oldName, newName) } + syncPullOneFilePinned = pullOneFilePinned ) // ========================================================== @@ -100,6 +100,14 @@ type driveSyncResult struct { Items []driveSyncItem `json:"items"` } +type driveSyncDryRunResult struct { + DryRun bool `json:"dry_run"` + Executed bool `json:"executed"` + PreviewKind string `json:"preview_kind"` + Operation string `json:"operation"` + Plan driveSyncResult `json:"plan"` +} + // driveSyncFailure 在 summary.failed > 0 时返回：结构化结果已打印到 stdout， // 这里只负责以 exit=1 退出并向 stderr 输出一行简短说明（与 drivePushFailure 一致）。 type driveSyncFailure struct{ failed int } @@ -140,6 +148,16 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { if err != nil { return err } + pinnedRoot, err := openExistingPinnedPullRoot(absDir) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } + defer pinnedRoot.close() + // sync 的本地快照与后续 hash / upload / pull 全部绑定到同一个固定根。 + localDirs, localFiles, err := runDriveMirrorWalkLocalForPushPinned(pinnedRoot) + if err != nil { + return fmt.Errorf("扫描本地目录失败: %w", err) + } ctx := cmd.Context() @@ -148,20 +166,20 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { if err != nil { return err } - // 本地现状：子目录（含空目录，父目录先于子目录）与常规文件。 - localDirs, localFiles, err := walkLocalForPush(absDir) - if err != nil { - return fmt.Errorf("扫描本地目录失败: %w", err) - } localByRel := make(map[string]localPushFile, len(localFiles)) for _, f := range localFiles { localByRel[f.RelPath] = f } + preflight := buildMirrorPreflight(localDirs, localFiles, remoteFiles, remoteFolders) + addPinnedLocalTargetPreflightFailures(pinnedRoot, remoteFiles, preflight) // 在计算 diff 前先识别文件/目录同路径冲突。冲突根及其全部后代都不能再进入 // new_local / new_remote 或后续执行阶段，否则会在远端制造同名异类对象，或尝试 // 把远端目录内容下载到本地文件之下。 typeConflicts := make(map[string]string) + for rel, msg := range preflight { + typeConflicts[rel] = msg + } for _, dir := range localDirs { if msg := pushTypeConflictError(dir, true, remoteFiles, remoteFolders); msg != "" { typeConflicts[dir] = msg @@ -191,8 +209,7 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { newLocal = append(newLocal, rel) continue } - lf := &localFile{RelPath: pf.RelPath, AbsPath: pf.AbsPath, Size: pf.Size, ModTimeMillis: pf.ModTimeMillis} - verdict, jerr := judgeFileMatch(lf, rf, quick) + verdict, jerr := judgePinnedPushFileMatch(pinnedRoot, pf, rf, quick) if jerr != nil { return jerr } @@ -244,11 +261,23 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { Error: typeConflicts[rel], }) } + if err := pinnedRoot.verify(); err != nil { + return err + } // --dry-run：只算差异、不执行任何同步动作。 if deps.Caller.DryRun() { - deps.Out.PrintInfo("dry-run: 仅计算差异，未执行任何同步操作") - return deps.Out.PrintJSON(res) + return deps.Out.PrintJSON(driveSyncDryRunResult{ + DryRun: true, Executed: false, PreviewKind: "plan", Operation: "drive sync", Plan: res, + }) + } + // 镜像前置检查是整批门禁：发现任一本地非法名称或跨端等价路径歧义后， + // sync 不得执行 create/download/upload 等任一写动作。 + if len(preflight) > 0 { + if perr := deps.Out.PrintJSON(res); perr != nil { + return perr + } + return &driveSyncFailure{failed: res.Summary.Failed} } // unknown：exact 模式下远端无可靠 md5、内容无法核对，不擅自覆盖任何一侧，记 skipped。 @@ -275,20 +304,10 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { } resolutions[rel] = strategy } - - // 落盘前先确保本地根存在（供大小写探测与 pull 落盘），并探测目标文件系统大小写敏感性。 - if err := os.MkdirAll(absDir, 0o755); err != nil { - return fmt.Errorf("创建本地目录失败: %w", err) + // 交互决策期间本地根也可能被替换；首个双端写动作前再次核对固定身份。 + if err := pinnedRoot.verify(); err != nil { + return err } - caseInsensitive := isCaseInsensitiveFS(absDir) - - // 远端 → 本地的大小写/规范化冲突：多个远端条目在当前文件系统上映射到同一本地路径时， - // 命中的路径一律标记 failed、都不落盘，避免静默覆盖丢文件（与 pull 同策略）。 - remoteRels := make([]string, 0, len(remoteFiles)) - for rel := range remoteFiles { - remoteRels = append(remoteRels, rel) - } - collided := detectTargetCollisions(absDir, remoteRels, caseInsensitive) // occupied：keep-both 生成不冲突的本地重命名目标时用，覆盖两侧全部已知路径。 occupied := make(map[string]bool) @@ -309,9 +328,6 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { // 阶段 1：镜像本地目录结构到远端（缺失则创建），保证空目录与 push 目标的父目录先存在。 for _, dir := range localDirs { - if syncPathBlockedByTypeConflict(dir, typeConflicts) { - continue - } if _, ok := remoteFolders[dir]; ok { continue // 远端已存在，复用 fileId } @@ -322,6 +338,9 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { res.Items = append(res.Items, driveSyncItem{RelPath: dir, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"}) continue } + if err := pinnedRoot.verify(); err != nil { + return err + } fid, cerr := pushCreateFolder(ctx, spaceID, parentID, name) if cerr != nil || fid == "" { res.Summary.Failed++ @@ -339,13 +358,13 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { // 阶段 2：new_remote 下载到本地。 for _, rel := range newRemote { - syncPullFile(&res, ctx, spaceID, remoteFiles[rel], absDir, rel, collided, syncDirectionPull) + syncPullFilePinned(&res, ctx, spaceID, remoteFiles[rel], pinnedRoot, rel, syncDirectionPull) } // 阶段 3：new_local 上传到远端。 for _, rel := range newLocal { pf := localByRel[rel] - syncPushFile(&res, ctx, spaceID, remoteFolders, pf, rel, "") + syncPushFile(&res, ctx, spaceID, remoteFolders, pinnedRoot, pf, rel, "") } // 阶段 4：modified 按 --on-conflict 解决。 @@ -354,11 +373,11 @@ func runDriveSync(cmd *cobra.Command, _ []string) error { rf := remoteFiles[rel] switch resolutions[rel] { case syncConflictRemoteWins: - syncPullFile(&res, ctx, spaceID, rf, absDir, rel, collided, syncDirectionPull) + syncPullFilePinned(&res, ctx, spaceID, rf, pinnedRoot, rel, syncDirectionPull) case syncConflictLocalWins: - syncPushFile(&res, ctx, spaceID, remoteFolders, pf, rel, rf.FileID) + syncPushFile(&res, ctx, spaceID, remoteFolders, pinnedRoot, pf, rel, rf.FileID) case syncConflictKeepBoth: - syncKeepBoth(&res, ctx, spaceID, rf, absDir, rel, collided, occupied) + syncKeepBothPinned(&res, ctx, spaceID, rf, pinnedRoot, rel, occupied) default: // "" — ask 选择跳过 res.Summary.Skipped++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionSkipped, Direction: syncDirectionConflict}) @@ -387,24 +406,54 @@ func syncPathBlockedByTypeConflict(rel string, conflicts map[string]string) bool return false } +// addPinnedLocalTargetPreflightFailures 从 sync 已固定的本地根核对所有远端落盘点。 +// 每一层既有祖先都必须是真实目录，末段若存在则必须是常规文件；软链即使仍指向根内 +// 也不属于可移植镜像树，必须在任何双端写之前整批拒绝。 +func addPinnedLocalTargetPreflightFailures(root *pinnedPullRoot, remote map[string]*remoteFile, failures map[string]string) { + for rel := range remote { + if mirrorPreflightFailureForRel(rel, failures) != "" { + continue + } + parts := strings.Split(filepath.FromSlash(rel), string(filepath.Separator)) + for i := range parts { + name := filepath.Join(parts[:i+1]...) + info, err := pullRootLstat(root.root, name) + if err != nil { + if os.IsNotExist(err) { + break + } + failures[rel] = fmt.Sprintf("检查本地目标失败: %v", err) + break + } + if i < len(parts)-1 { + if !info.IsDir() { + failures[rel] = fmt.Sprintf("本地目标 %q 的祖先 %q 已存在且不是目录，已拒绝镜像", rel, filepath.ToSlash(name)) + break + } + continue + } + if !info.Mode().IsRegular() { + failures[rel] = fmt.Sprintf("本地目标 %q 已存在且不是常规文件，已拒绝覆盖", rel) + } + } + } +} + // syncPullFile 下载单个远端文件到本地 rel 对应路径（总是覆盖，Drive 为该项权威源）， // 并把结果计入 res。命中大小写/规范化冲突或逃逸的路径记 failed、不落盘。 -func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, collided map[string]bool, direction string) { - if collided[rel] { +func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel, direction string) { + root, err := openPinnedPullRoot(absDir) + if err != nil { res.Summary.Failed++ - res.Items = append(res.Items, driveSyncItem{ - RelPath: rel, Action: syncActionFailed, Direction: direction, - Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", - }) + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction, Error: err.Error()}) return } - localPath, terr := resolveLocalTarget(absDir, rel) - if terr != nil { - res.Summary.Failed++ - res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: direction, Error: terr.Error()}) - return - } - action, perr := pullOneFile(ctx, spaceID, rf, localPath, ifExistsOverwrite) + defer root.close() + syncPullFilePinned(res, ctx, spaceID, rf, root, rel, direction) +} + +func syncPullFilePinned(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel string, direction string) { + action, perr := pullRemoteFilePinned(ctx, spaceID, rf, root, rel, ifExistsOverwrite) if action == pullActionDownloaded { res.Summary.Pulled++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionDownloaded, Direction: direction}) @@ -419,7 +468,7 @@ func syncPullFile(res *driveSyncResult, ctx context.Context, spaceID string, rf } // syncPushFile 上传单个本地文件到远端；overwriteID 非空时走覆盖上传（原地覆盖同名远端文件）。 -func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, remoteFolders map[string]string, pf localPushFile, rel, overwriteID string) { +func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, remoteFolders map[string]string, root *pinnedPullRoot, pf localPushFile, rel, overwriteID string) { parentRel, name := splitRel(rel) parentID, ok := remoteFolders[parentRel] if !ok || parentID == "" { @@ -427,7 +476,7 @@ func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, rem res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: "父目录未能创建"}) return } - if err := pushUploadFile(ctx, spaceID, parentID, overwriteID, name, pf.AbsPath, pf.Size); err != nil { + if err := pushUploadFilePinned(ctx, spaceID, parentID, overwriteID, name, root, pf); err != nil { res.Summary.Failed++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionPush, Error: err.Error()}) return @@ -442,62 +491,74 @@ func syncPushFile(res *driveSyncResult, ctx context.Context, spaceID string, rem res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: action, Direction: direction}) } -// syncKeepBoth 解决 modified 冲突的 keep-both 策略：先把本地文件改名保留（追加基于 -// 远端 fileId 的不冲突后缀），再把远端文件拉取到原 rel 路径。拉取失败则回滚改名。 -func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, collided, occupied map[string]bool) { - if collided[rel] { +// syncKeepBoth 解决 modified 冲突的 keep-both 策略：先为本地文件原子建立带冲突后缀 +// 的 no-clobber 硬链接，再把远端文件拉取到原 rel 路径。拉取失败时保留两个本地名字， +// 不执行可能误删或覆盖并发文件的回滚。 +func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, absDir, rel string, occupied map[string]bool) { + root, err := openPinnedPullRoot(absDir) + if err != nil { res.Summary.Failed++ - res.Items = append(res.Items, driveSyncItem{ - RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, - Error: "多个远端条目在当前文件系统上映射到同一本地路径（大小写/规范化冲突），已跳过以避免覆盖丢失", - }) + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: err.Error()}) return } - oldAbs, e1 := resolveLocalTarget(absDir, rel) + defer root.close() + syncKeepBothPinned(res, ctx, spaceID, rf, root, rel, occupied) +} + +func syncKeepBothPinned(res *driveSyncResult, ctx context.Context, spaceID string, rf *remoteFile, root *pinnedPullRoot, rel string, occupied map[string]bool) { + pinned, e1 := root.openTarget(rel) if e1 != nil { res.Summary.Failed++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e1.Error()}) return } - // 以「不覆盖」语义原子占用一个本地重命名目标。occupied 的精确字符串查重覆盖不到 - // 大小写/NFC 等价的既有文件；用 O_CREATE|O_EXCL 让 OS 兜底判等价性，命中则换下一个 - // 后缀，杜绝 os.Rename 静默覆盖等价既有文件导致的数据丢失。 - suffixedRel, newAbs, e2 := reserveSyncKeepBothTarget(absDir, rel, rf.FileID, occupied) + defer pinned.close() + localInfo, err := pinned.regularTargetInfo() + if err != nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: err.Error()}) + return + } + if localInfo == nil { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本不存在"}) + return + } + // Root.Link(original,candidate) 在同一固定父目录中原子 no-clobber 地保留本地版本。 + // occupied 的精确字符串查重覆盖不到的文件系统等价名称，由 Link 的 EEXIST 兜底。 + suffixedRel, newName, e2 := reserveSyncKeepBothTargetPinned(pinned, rel, rf.FileID, occupied) if e2 != nil { res.Summary.Failed++ res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: e2.Error()}) return } - // newAbs 此刻是我们刚用 O_EXCL 新建的空占位文件，覆盖它不会丢用户数据；且已确保它 - // 不与任何等价既有文件冲突。 - if err := syncRename(oldAbs, newAbs); err != nil { - _ = os.Remove(newAbs) // 清理空占位，避免残留 + savedInfo, err := pullRootLstat(pinned.parentRoot, newName) + if err != nil || !sameKeepBothVersion(localInfo, savedInfo) { res.Summary.Failed++ - res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: fmt.Sprintf("本地改名保留失败: %v", err)}) + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本身份不一致"}) return } occupied[suffixedRel] = true - action, perr := pullOneFile(ctx, spaceID, rf, oldAbs, ifExistsOverwrite) + action, perr := syncPullOneFilePinned(ctx, spaceID, rf, pinned, ifExistsOverwrite) if action != pullActionDownloaded { - // 拉取失败：回滚改名，把本地文件恢复回原名。pullOneFile 是原子的（下载写临时文件、 - // 成功才 rename，失败时绝不触碰 oldAbs），故此处 oldAbs 必不存在，rename 可直接复原、 - // 无需像参考实现那样先清残留。回滚本身失败时如实上报——本地版本仍以改名后的名字保留、 - // 未丢数据，但需让用户知道文件名已变。 res.Summary.Failed++ msg := "" if perr != nil { msg = perr.Error() } - if rbErr := syncRename(newAbs, oldAbs); rbErr != nil { - if msg != "" { - msg += "; " - } - msg += fmt.Sprintf("回滚改名失败，本地版本保留为 %s: %v", suffixedRel, rbErr) + if msg == "" { + msg = "远端版本未能拉取，本地保留版本已保留" } res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: msg}) return } + currentSaved, err := pullRootLstat(pinned.parentRoot, newName) + if err != nil || !sameKeepBothVersion(savedInfo, currentSaved) { + res.Summary.Failed++ + res.Items = append(res.Items, driveSyncItem{RelPath: rel, Action: syncActionFailed, Direction: syncDirectionConflict, Error: "本地保留版本在传输期间被删除、替换或修改"}) + return + } res.Summary.Pulled++ res.Items = append(res.Items, driveSyncItem{RelPath: suffixedRel, Action: syncActionRenamedLocal, Direction: syncDirectionConflict}, @@ -505,6 +566,12 @@ func syncKeepBoth(res *driveSyncResult, ctx context.Context, spaceID string, rf ) } +func sameKeepBothVersion(expected, current os.FileInfo) bool { + return expected != nil && current != nil && current.Mode().IsRegular() && + os.SameFile(expected, current) && expected.Size() == current.Size() && + expected.ModTime().Equal(current.ModTime()) +} + // syncKeepBothCandidate 生成 keep-both 的第 n 个候选相对路径（n=0 为首选）：在扩展名前 // 插入基于远端 fileId 末段的后缀（缺失时用 conflict），n>0 再追加序号消歧。 func syncKeepBothCandidate(rel, fileID string, n int) string { @@ -539,24 +606,38 @@ func driveSyncSuffixedRel(rel, fileID string, occupied map[string]bool) string { } } -// reserveSyncKeepBothTarget 生成并以「不覆盖」语义原子占用一个 keep-both 本地目标。 -// 逐个候选用 O_CREATE|O_EXCL 尝试创建：成功即占住该名，返回其相对路径与绝对路径（调用方 -// 随后可安全 os.Rename 覆盖这个空占位）；EEXIST（含大小写/NFC 等价的既有文件，由 OS 判定） -// 则记入 occupied 并试下一个后缀，绝不覆盖任何既有文件。 +// reserveSyncKeepBothTarget 生成候选并通过 Root.Link(original,candidate) 原子建立 +// no-clobber 本地保留版本。EEXIST（含文件系统等价名称）时换下一个候选。 func reserveSyncKeepBothTarget(absDir, rel, fileID string, occupied map[string]bool) (string, string, error) { + target, err := openPinnedPullTarget(absDir, rel) + if err != nil { + return "", "", err + } + defer target.close() + candidate, _, err := reserveSyncKeepBothTargetPinned(target, rel, fileID, occupied) + if err != nil { + return "", "", err + } + return candidate, filepath.Join(absDir, filepath.FromSlash(candidate)), nil +} + +func reserveSyncKeepBothTargetPinned(target *pinnedPullTarget, rel, fileID string, occupied map[string]bool) (string, string, error) { + parentRel, _ := splitRel(rel) for n := 0; ; n++ { cand := syncKeepBothCandidate(rel, fileID, n) if occupied[cand] { continue // 本次运行内已知占用，快速跳过 } - abs, err := resolveLocalTarget(absDir, cand) - if err != nil { - return "", "", err // 逃逸/符号链接等，直接失败 + candidateParent, candidateName := splitRel(cand) + if candidateParent != parentRel || !isSafeRemoteSegment(candidateName) { + return "", "", fmt.Errorf("keep-both 候选路径 %q 不在原目标目录内", cand) } - f, oerr := syncOpenFile(abs, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644) + if err := target.verifyParent(); err != nil { + return "", "", err + } + oerr := syncRootLink(target.parentRoot, target.name, filepath.FromSlash(candidateName)) if oerr == nil { - _ = f.Close() - return cand, abs, nil + return cand, filepath.FromSlash(candidateName), nil } if os.IsExist(oerr) { occupied[cand] = true // 等价目标已存在，记下避免重试，换下一个后缀 diff --git a/internal/helpers/drive_sync_confirmation_test.go b/internal/helpers/drive_sync_confirmation_test.go index 73a18c03..8c22e83b 100644 --- a/internal/helpers/drive_sync_confirmation_test.go +++ b/internal/helpers/drive_sync_confirmation_test.go @@ -7,6 +7,8 @@ import ( "path/filepath" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // pull / push / sync 声明 Safety.Confirmation = user_required。本文件断言两件事： @@ -66,18 +68,14 @@ func TestCrossPlatformCoverageDriveSyncFamily_refusesWithoutConfirmation(t *test } return `{"result":{"fileId":"NEW"},"success":true}`, nil }} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { t.Error("no download may happen before confirmation") return os.WriteFile(dest, []byte("leaked"), 0o644) }) - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { t.Error("no upload may happen before confirmation") return nil }) - t.Cleanup(func() { - SetHTTPGetFile(nil) - SetHTTPPutFile(nil) - }) args := append(append([]string{}, tc.args...), "--local-folder", dir, "--remote-folder", "ROOT") err := runDriveCmdWithoutConfirm(t, caller, args...) @@ -113,18 +111,14 @@ func TestCrossPlatformCoverageDriveSyncFamily_dryRunNeedsNoConfirmation(t *testi "ROOT": `{"result":{"items":[{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}],"nextToken":""}}`, }) caller.dryRun = true - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("dry-run must not download") return nil }) - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { t.Error("dry-run must not upload") return nil }) - t.Cleanup(func() { - SetHTTPGetFile(nil) - SetHTTPPutFile(nil) - }) if err := runDriveCmdWithoutConfirm(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick"); err != nil { @@ -140,17 +134,14 @@ func TestCrossPlatformCoverageDrivePull_dryRunPlansWithoutLocalWrites(t *testing target := filepath.Join(parent, "not-created") caller := pullListingCaller(`{"name":"remote.txt","type":"file","fileId":"R","modifyTime":2}`) caller.dryRun = true - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("dry-run must not download") return nil }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) var out bytes.Buffer - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} - os.Args = []string{"dws", "drive", "pull"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"}) cmd := findDriveSubcommand(t, "pull") mustSetFlags(t, cmd, map[string]string{"local-folder": target, "remote-folder": "ROOT"}) if err := cmd.RunE(cmd, nil); err != nil { @@ -175,17 +166,14 @@ func TestCrossPlatformCoverageDrivePush_dryRunPlansWithoutRemoteWrites(t *testin mustWrite(t, filepath.Join(dir, "sub", "local.txt"), "local") caller := syncCaller(nil) caller.dryRun = true - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { t.Error("dry-run must not upload") return nil }) - t.Cleanup(func() { SetHTTPPutFile(nil) }) var out bytes.Buffer - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: &out}} - os.Args = []string{"dws", "drive", "push"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: &out}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "push"}) cmd := findDriveSubcommand(t, "push") mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) if err := cmd.RunE(cmd, nil); err != nil { @@ -214,9 +202,7 @@ func TestCrossPlatformCoverageDrivePull_dryRunPlanBranches(t *testing.T) { "new.txt": {RelPath: "new.txt"}, } var out bytes.Buffer - prevDeps := deps - deps = &Deps{Out: &Formatter{w: &out}} - t.Cleanup(func() { deps = prevDeps }) + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}}) if err := printDrivePullDryRun(root, ifExistsSkip, remote, []string{"A.txt", "a.txt", "../escape", "skip.txt", "new.txt"}, true); err != nil { @@ -236,9 +222,7 @@ func TestCrossPlatformCoverageDrivePull_dryRunPlanBranches(t *testing.T) { func TestCrossPlatformCoverageDrivePush_dryRunPlanBranches(t *testing.T) { var out bytes.Buffer - prevDeps := deps - deps = &Deps{Out: &Formatter{w: &out}} - t.Cleanup(func() { deps = prevDeps }) + testseam.Swap(t, &deps, &Deps{Out: &Formatter{w: &out}}) remoteFolders := map[string]string{"": "ROOT", "existing": "EXISTING"} remoteFiles := map[string]*remoteFile{ "skip.txt": {RelPath: "skip.txt"}, @@ -317,10 +301,9 @@ func TestCrossPlatformCoverageDrivePull_confirmedOverwriteIssuesExactCalls(t *te mustWrite(t, p, "local-old") caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("remote-new"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmdWithoutConfirm(t, caller, "pull", "--local-folder", dir, "--remote-folder", "ROOT", "--if-exists", "overwrite", "--yes"); err != nil { @@ -419,11 +402,10 @@ func TestCrossPlatformCoverageDrivePull_defaultSkipsExistingLocalFiles(t *testin mustWrite(t, p, "local-old") caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":9}`) - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("default skip must not download over an existing local file") return nil }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", dir, "--remote-folder", "ROOT"); err != nil { t.Fatalf("unexpected error: %v", err) diff --git a/internal/helpers/drive_sync_conflict_test.go b/internal/helpers/drive_sync_conflict_test.go index b3a98bb6..962e20e9 100644 --- a/internal/helpers/drive_sync_conflict_test.go +++ b/internal/helpers/drive_sync_conflict_test.go @@ -6,7 +6,6 @@ import ( "io" "os" "path/filepath" - "strings" "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" @@ -115,118 +114,95 @@ func TestCrossPlatformCoverageSyncKeepBoth_escapingRelIsFailed(t *testing.T) { } res := &driveSyncResult{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "sub/f.txt", FileID: "FID12345678"}, - root, "sub/f.txt", map[string]bool{}, map[string]bool{}) + root, "sub/f.txt", map[string]bool{}) if res.Summary.Failed != 1 { t.Fatalf("failed = %d, want 1", res.Summary.Failed) } } -// collided 命中时 keep-both 直接 failed，不做任何改名。 -func TestCrossPlatformCoverageSyncKeepBoth_collidedIsFailed(t *testing.T) { - root := t.TempDir() - mustWrite(t, filepath.Join(root, "f.txt"), "local") - res := &driveSyncResult{} - syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, - root, "f.txt", map[string]bool{"f.txt": true}, map[string]bool{}) - if res.Summary.Failed != 1 { - t.Fatalf("failed = %d, want 1", res.Summary.Failed) - } - if b, _ := os.ReadFile(filepath.Join(root, "f.txt")); string(b) != "local" { - t.Errorf("collided keep-both must not touch the local file, got %q", string(b)) - } -} - -// 占用改名目标失败（目录不可写）→ failed。 +// 原子建立本地保留硬链接失败 → failed。 func TestCrossPlatformCoverageSyncKeepBoth_reserveFailureIsFailed(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "f.txt"), "local") - testseam.Swap(t, &syncOpenFile, func(string, int, os.FileMode) (*os.File, error) { - return nil, errors.New("open file boom") + testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error { + return errors.New("link boom") }) res := &driveSyncResult{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, - root, "f.txt", map[string]bool{}, map[string]bool{}) + root, "f.txt", map[string]bool{}) if res.Summary.Failed != 1 { t.Fatalf("failed = %d, want 1", res.Summary.Failed) } } -// 改名本身失败（本地原文件其实是目录）→ failed，并清理刚建的空占位。 -func TestCrossPlatformCoverageSyncKeepBoth_renameFailureCleansPlaceholder(t *testing.T) { +// Link 失败不得留下空占位，也不得移动或修改原文件。 +func TestCrossPlatformCoverageSyncKeepBoth_linkFailureLeavesOriginal(t *testing.T) { root := t.TempDir() mustWrite(t, filepath.Join(root, "f.txt"), "local") - testseam.Swap(t, &syncRename, func(string, string) error { - return errors.New("rename boom") + testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error { + return errors.New("link boom") }) res := &driveSyncResult{} occupied := map[string]bool{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, - root, "f.txt", map[string]bool{}, occupied) + root, "f.txt", occupied) if res.Summary.Failed != 1 { t.Fatalf("failed = %d, want 1", res.Summary.Failed) } - // 空占位必须被清理，不留残留。 if _, err := os.Stat(filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))); !os.IsNotExist(err) { - t.Error("empty placeholder must be removed after a failed rename") + t.Error("failed link must not leave a placeholder") + } + if content, err := os.ReadFile(filepath.Join(root, "f.txt")); err != nil || string(content) != "local" { + t.Fatalf("original changed after failed link: content=%q err=%v", content, err) } } -// 拉取失败 → 回滚改名，本地文件恢复原名与原内容。 -func TestCrossPlatformCoverageSyncKeepBoth_pullFailureRollsBackRename(t *testing.T) { +// 拉取失败时不做回滚：原名尚未发布，候选硬链接也保留，避免误删并发对象。 +func TestCrossPlatformCoverageSyncKeepBoth_pullFailurePreservesCandidate(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "f.txt") mustWrite(t, p, "local-version") - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { return errTestDownload }) - t.Cleanup(func() { - deps, os.Args = prevDeps, prevArgs - SetHTTPGetFile(nil) - }) + testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload }) res := &driveSyncResult{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, - root, "f.txt", map[string]bool{}, map[string]bool{}) + root, "f.txt", map[string]bool{}) if res.Summary.Failed != 1 { t.Fatalf("failed = %d, want 1", res.Summary.Failed) } if b, err := os.ReadFile(p); err != nil || string(b) != "local-version" { - t.Fatalf("rename must be rolled back: %v / %q", err, string(b)) + t.Fatalf("original must remain before publish: %v / %q", err, string(b)) } - if _, err := os.Stat(filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0))); !os.IsNotExist(err) { - t.Error("renamed copy must not survive a successful rollback") + suffixed := filepath.Join(root, syncKeepBothCandidate("f.txt", "FID12345678", 0)) + if b, err := os.ReadFile(suffixed); err != nil || string(b) != "local-version" { + t.Fatalf("candidate must remain after pull failure: %v / %q", err, string(b)) + } + originalInfo, _ := os.Lstat(p) + candidateInfo, _ := os.Lstat(suffixed) + if !os.SameFile(originalInfo, candidateInfo) { + t.Fatal("candidate must be a hard link to the original local version") } } -// 拉取失败且回滚也失败 → 如实上报“本地版本保留为 <改名>”，不谎称成功。 -func TestCrossPlatformCoverageSyncKeepBoth_rollbackFailureIsReported(t *testing.T) { +// 拉取失败只能上报 failed，不得产生 renamed_local 成功项。 +func TestCrossPlatformCoverageSyncKeepBoth_pullFailureDoesNotReportRenamed(t *testing.T) { root := t.TempDir() p := filepath.Join(root, "f.txt") mustWrite(t, p, "local-version") - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - // 下载失败前先把原名占住一个目录，使回滚 rename 无法复原。 - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { - if err := os.MkdirAll(filepath.Join(p, "blocker"), 0o755); err != nil { - return err - } - return errTestDownload - }) - t.Cleanup(func() { - deps, os.Args = prevDeps, prevArgs - SetHTTPGetFile(nil) - }) + testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { return errTestDownload }) res := &driveSyncResult{} syncKeepBoth(res, context.Background(), "", &remoteFile{RelPath: "f.txt", FileID: "FID12345678"}, - root, "f.txt", map[string]bool{}, map[string]bool{}) + root, "f.txt", map[string]bool{}) if res.Summary.Failed != 1 { t.Fatalf("failed = %d, want 1", res.Summary.Failed) @@ -234,12 +210,11 @@ func TestCrossPlatformCoverageSyncKeepBoth_rollbackFailureIsReported(t *testing. if len(res.Items) != 1 || res.Items[0].Action != syncActionFailed { t.Fatalf("items = %+v", res.Items) } - // 数据没丢：本地版本仍以改名后的名字存在，且错误信息点明了这一点。 suffixed := syncKeepBothCandidate("f.txt", "FID12345678", 0) if b, err := os.ReadFile(filepath.Join(root, suffixed)); err != nil || string(b) != "local-version" { t.Fatalf("local version must survive as %s: %v / %q", suffixed, err, string(b)) } - if !strings.Contains(res.Items[0].Error, "回滚改名失败") { - t.Errorf("error must disclose the failed rollback, got %q", res.Items[0].Error) + if res.Items[0].Action == syncActionRenamedLocal { + t.Fatalf("pull failure must not report renamed_local: %#v", res.Items) } } diff --git a/internal/helpers/drive_sync_coverage_test.go b/internal/helpers/drive_sync_coverage_test.go index 1ab48574..f90b0f63 100644 --- a/internal/helpers/drive_sync_coverage_test.go +++ b/internal/helpers/drive_sync_coverage_test.go @@ -38,14 +38,10 @@ func syncCaller(listing map[string]string) *driveScriptCaller { // withSyncTransport 注入成功的上传与下载。 func withSyncTransport(t *testing.T, body string) { t.Helper() - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte(body), 0o644) }) - t.Cleanup(func() { - SetHTTPPutFile(nil) - SetHTTPGetFile(nil) - }) } // ────────────────────────────────────────────────────────── @@ -133,7 +129,7 @@ func TestCrossPlatformCoverageDriveSync_unknownIsSkipped(t *testing.T) { // exact 模式下本地 MD5 计算失败 → 整个 sync 中止。错误通过 seam 确定性注入， // 避免依赖 chmod：Windows 不遵循 POSIX 的 000 权限语义。 func TestCrossPlatformCoverageDriveSync_md5FailureAborts(t *testing.T) { - testseam.Swap(t, &md5File, func(string) (string, error) { + testseam.Swap(t, &pushMD5OpenedFile, func(*os.File) (string, error) { return "", errors.New("md5 boom") }) @@ -223,8 +219,7 @@ func TestCrossPlatformCoverageDriveSync_folderCreationFailureCascades(t *testing func TestCrossPlatformCoverageDriveSync_pushUploadFailureIsFailed(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "only-local.txt"), "x") - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return errTestUpload }) - t.Cleanup(func() { SetHTTPPutFile(nil) }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return errTestUpload }) caller := syncCaller(nil) err := runDriveCmd(t, caller, "sync", "--local-folder", dir, "--remote-folder", "ROOT", "--quick") diff --git a/internal/helpers/drive_sync_edges_test.go b/internal/helpers/drive_sync_edges_test.go index c8c3cfbf..f55d9065 100644 --- a/internal/helpers/drive_sync_edges_test.go +++ b/internal/helpers/drive_sync_edges_test.go @@ -52,10 +52,9 @@ func TestCrossPlatformCoverageDrivePull_emptyIfExistsDefaultsToSkip(t *testing.T p := filepath.Join(root, "a.txt") mustWrite(t, p, "local-old") caller := pullListingCaller(`{"name":"a.txt","type":"file","fileId":"A","modifyTime":1}`) - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("remote-new"), 0o644) }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) if err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT", "--if-exists", ""); err != nil { t.Fatalf("unexpected error: %v", err) @@ -88,14 +87,12 @@ func TestCrossPlatformCoverageDrivePush_emptyIfExistsDefaultsToSkip(t *testing.T // 目标目录不可写 → 创建临时文件失败。 func TestCrossPlatformCoveragePullOneFile_tempFileCreationFailure(t *testing.T) { root := t.TempDir() - testseam.Swap(t, &pullCreateTemp, func(string, string) (*os.File, error) { - return nil, errors.New("create temp boom") + testseam.Swap(t, &pullCreateTemp, func(*os.Root) (*os.File, string, error) { + return nil, "", errors.New("create temp boom") }) - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"}, filepath.Join(root, "a.txt"), ifExistsOverwrite) @@ -112,16 +109,11 @@ func TestCrossPlatformCoveragePullOneFile_renameOntoDirectoryFails(t *testing.T) t.Fatal(err) } - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - SetHTTPGetFile(func(_ context.Context, _ string, _ map[string]string, dest string) error { + testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + swapPullDownloadPath(t, func(_ context.Context, _ string, _ map[string]string, dest string) error { return os.WriteFile(dest, []byte("payload"), 0o644) }) - t.Cleanup(func() { - deps, os.Args = prevDeps, prevArgs - SetHTTPGetFile(nil) - }) action, err := pullOneFile(context.Background(), "", &remoteFile{RelPath: "a.txt", FileID: "A"}, target, ifExistsOverwrite) @@ -137,10 +129,8 @@ func TestCrossPlatformCoveragePullOneFile_renameOntoDirectoryFails(t *testing.T) func TestCrossPlatformCoverageDrivePull_printFailurePropagates(t *testing.T) { dir := t.TempDir() - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: failingWriter{}}} - os.Args = []string{"dws", "drive", "pull"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: pullListingCaller(""), Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "pull"}) cmd := findDriveSubcommand(t, "pull") mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) @@ -154,10 +144,8 @@ func TestCrossPlatformCoverageDrivePush_printFailurePropagates(t *testing.T) { mustWrite(t, filepath.Join(dir, "a.txt"), "x") withNoopPut(t) - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: pushOKCaller(nil), Out: &Formatter{w: failingWriter{}}} - os.Args = []string{"dws", "drive", "push"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: pushOKCaller(nil), Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "push"}) cmd := findDriveSubcommand(t, "push") mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT"}) @@ -169,13 +157,10 @@ func TestCrossPlatformCoverageDrivePush_printFailurePropagates(t *testing.T) { func TestCrossPlatformCoverageDriveSync_printFailurePropagates(t *testing.T) { dir := t.TempDir() mustWrite(t, filepath.Join(dir, "a.txt"), "x") - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) - t.Cleanup(func() { SetHTTPPutFile(nil) }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: syncCaller(nil), Out: &Formatter{w: failingWriter{}}} - os.Args = []string{"dws", "drive", "sync"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: syncCaller(nil), Out: &Formatter{w: failingWriter{}}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive", "sync"}) cmd := findDriveSubcommand(t, "sync") mustSetFlags(t, cmd, map[string]string{"local-folder": dir, "remote-folder": "ROOT", "quick": "true"}) @@ -253,11 +238,12 @@ func TestCrossPlatformCoverageReserveSyncKeepBothTarget_escapeFails(t *testing.T } } -// 候选目标所在目录不可写 → OpenFile 以非 EEXIST 错误失败，直接上报。 +// 候选硬链接创建返回非 EEXIST 错误时直接上报。 func TestCrossPlatformCoverageReserveSyncKeepBothTarget_unwritableDirFails(t *testing.T) { root := t.TempDir() - testseam.Swap(t, &syncOpenFile, func(string, int, os.FileMode) (*os.File, error) { - return nil, errors.New("open file boom") + mustWrite(t, filepath.Join(root, "f.txt"), "local") + testseam.Swap(t, &syncRootLink, func(*os.Root, string, string) error { + return errors.New("link boom") }) if _, _, err := reserveSyncKeepBothTarget(root, "f.txt", "FID12345678", map[string]bool{}); err == nil { @@ -268,6 +254,7 @@ func TestCrossPlatformCoverageReserveSyncKeepBothTarget_unwritableDirFails(t *te // occupied 中已知占用的首选候选被跳过，改用下一个后缀。 func TestCrossPlatformCoverageReserveSyncKeepBothTarget_skipsKnownOccupied(t *testing.T) { root := t.TempDir() + mustWrite(t, filepath.Join(root, "f.txt"), "local") first := syncKeepBothCandidate("f.txt", "FID12345678", 0) occupied := map[string]bool{first: true} diff --git a/internal/helpers/drive_sync_gaps_test.go b/internal/helpers/drive_sync_gaps_test.go index 5165c757..4d622446 100644 --- a/internal/helpers/drive_sync_gaps_test.go +++ b/internal/helpers/drive_sync_gaps_test.go @@ -7,6 +7,8 @@ import ( "path/filepath" "strings" "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) // 本文件补齐几条在默认策略改为 skip 后失去覆盖的边界分支。 @@ -62,10 +64,8 @@ func TestCrossPlatformCoverageDrivePush_remoteNonFileEntriesAreSkipped(t *testin return `{"result":{"items":[],"nextToken":""}}`, nil }} - prevDeps, prevArgs := deps, os.Args - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} - os.Args = []string{"dws", "drive"} - t.Cleanup(func() { deps, os.Args = prevDeps, prevArgs }) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) files, _, err := fetchRemoteTreeForPush(context.Background(), "", "ROOT") if err != nil { @@ -81,14 +81,10 @@ func TestCrossPlatformCoverageDrivePush_remoteNonFileEntriesAreSkipped(t *testin } } -// list_files 返回体没有 result 字段 → 视为空列表，而不是解析错误。 -func TestCrossPlatformCoverageParseDriveList_missingResultIsEmpty(t *testing.T) { - items, token, err := parseDriveList(`{"success":true}`) - if err != nil { - t.Fatalf("unexpected error: %v", err) - } - if len(items) != 0 || token != "" { - t.Errorf("parseDriveList = (%v, %q), want empty list", items, token) +// list_files 是远端权威树的数据来源；缺失 result 不能伪装成空目录。 +func TestCrossPlatformCoverageParseDriveList_missingResultFailsClosed(t *testing.T) { + if _, _, err := parseDriveList(`{"success":true}`); err == nil || !strings.Contains(err.Error(), "缺少 result") { + t.Fatalf("parseDriveList error = %v, want missing-result failure", err) } } diff --git a/internal/helpers/drive_sync_platform_test.go b/internal/helpers/drive_sync_platform_test.go index 2ab28887..d7f19fb3 100644 --- a/internal/helpers/drive_sync_platform_test.go +++ b/internal/helpers/drive_sync_platform_test.go @@ -33,11 +33,10 @@ func TestCrossPlatformCoverageDrivePull_equivalentPathCollisionFailsBoth(t *test caller := pullListingCaller( `{"name":"A.txt","type":"file","fileId":"UP","modifyTime":1},` + `{"name":"a.txt","type":"file","fileId":"LOW","modifyTime":2}`) - SetHTTPGetFile(func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { t.Error("collided entries must not be downloaded") return nil }) - t.Cleanup(func() { SetHTTPGetFile(nil) }) err := runDriveCmd(t, caller, "pull", "--local-folder", root, "--remote-folder", "ROOT") var pf *drivePartialFailure @@ -95,7 +94,7 @@ func TestCrossPlatformCoverageDetectCaseInsensitiveFS_caselessProbeFallsBackToPl // ────────────────────────────────────────────────────────── func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_allowsPlainNames(t *testing.T) { - for _, name := range []string{"a.txt", "报告.pdf", "with space.md", "..."} { + for _, name := range []string{"a.txt", "报告.pdf", "with space.md"} { if !isSafeRemoteSegmentPlatform(name) { t.Errorf("isSafeRemoteSegmentPlatform(%q) = false, want true", name) } @@ -106,8 +105,18 @@ func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_rejectsNonCanonicalWin if runtime.GOOS != "windows" { return } - if isSafeRemoteSegmentPlatform(`dir\..\file.txt`) { - t.Error("Windows non-canonical segment must be rejected") + for _, name := range []string{ + `C:relative`, `a?.txt`, `a*.txt`, `a:stream`, `a<.txt`, `a>.txt`, `a|.txt`, `a".txt`, + "name.", "name ", "...", "CON", "con.txt", "PRN", "AUX", "NUL", "COM1", "LPT9", "COM¹", "CONIN$", + } { + if isSafeRemoteSegmentPlatform(name) { + t.Errorf("Windows unsafe segment %q must be rejected", name) + } + } + for _, name := range []string{"report.txt", "报告 2026.pdf", "COM10", "LPT0"} { + if !isSafeRemoteSegmentPlatform(name) { + t.Errorf("Windows ordinary segment %q must be accepted", name) + } } } diff --git a/internal/helpers/drive_sync_test.go b/internal/helpers/drive_sync_test.go index e2221dac..854aecb3 100644 --- a/internal/helpers/drive_sync_test.go +++ b/internal/helpers/drive_sync_test.go @@ -17,6 +17,16 @@ import ( // errTestDownload 用于模拟 httpGetFile 下载失败。 var errTestDownload = errors.New("simulated download failure") +// swapPullDownloadPath 为存量测试保留基于路径的传输模拟写法。 +// 生产 pull/sync 始终把已由 os.Root 安全打开的句柄交给 pullDownloadFile； +// 只有测试适配层才把该句柄的名称传给旧 callback。 +func swapPullDownloadPath(t *testing.T, fn func(context.Context, string, map[string]string, string) error) { + t.Helper() + testseam.Swap(t, &pullDownloadFile, func(ctx context.Context, url string, headers map[string]string, destination *os.File) error { + return fn(ctx, url, headers, destination.Name()) + }) +} + // ────────────────────────────────────────────────────────── // driveSyncFailure — sync 部分失败错误：exit=1 // ────────────────────────────────────────────────────────── @@ -65,7 +75,7 @@ func TestCrossPlatformCoverageDriveSyncSuffixedRel(t *testing.T) { // sync 双向流程 — new_local 上传 / new_remote 下载 // ────────────────────────────────────────────────────────── -// runDriveSyncTest 用 mock caller 执行 `drive sync`，注入 httpPutFile / httpGetFile 为 +// runDriveSyncTest 用 mock caller 执行 `drive sync`，注入 opened-file PUT / GET 为 // 可控 no-op，避免真实 OSS 传输。返回 root.Execute() 的结果。 func runDriveSyncTest(t *testing.T, caller *driveSyncMockCaller, localDir string, args ...string) error { // 默认下载：把远端内容写到目标路径，模拟成功落盘。 @@ -78,12 +88,9 @@ func runDriveSyncTest(t *testing.T, caller *driveSyncMockCaller, localDir string func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn func(context.Context, string, map[string]string, string) error, localDir string, args ...string) error { t.Helper() - prevDeps := deps - prevOSArgs := os.Args - SetHTTPPutFile(func(context.Context, string, map[string]string, string, int64) error { return nil }) - SetHTTPGetFile(getFn) - - deps = &Deps{Caller: caller, Out: &Formatter{w: io.Discard}} + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { return nil }) + swapPullDownloadPath(t, getFn) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) root := &cobra.Command{Use: "dws"} root.PersistentFlags().BoolP("yes", "y", false, "") @@ -92,16 +99,9 @@ func runDriveSyncTestWithGet(t *testing.T, caller *driveSyncMockCaller, getFn fu // sync 是 user_required 叶子，非交互环境需 --yes 才能越过统一确认门。 full := append([]string{"sync", "--local-folder", localDir, "--remote-folder", "ROOT", "--yes"}, args...) - os.Args = append([]string{"dws", "drive"}, full...) + testseam.Swap(t, &os.Args, append([]string{"dws", "drive"}, full...)) root.SetArgs(append([]string{"drive"}, full...)) - t.Cleanup(func() { - deps = prevDeps - os.Args = prevOSArgs - SetHTTPPutFile(nil) - SetHTTPGetFile(nil) - }) - return root.Execute() } @@ -198,6 +198,36 @@ func TestCrossPlatformCoverageDriveSync_modifiedLocalWins(t *testing.T) { } } +func TestCrossPlatformCoverageDriveSyncRejectsUnknownCommitEffect(t *testing.T) { + for _, response := range []string{"", `{}`} { + t.Run(response, func(t *testing.T) { + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "local.txt"), "payload") + caller := &driveSyncMockCaller{ + listJSON: `{"result":{"items":[]}}`, + commitJSON: &response, + } + err, output, putCalls := runDriveMirrorUploadCommandCapture(t, "sync", caller, dir) + if err == nil { + t.Fatal("empty commit result must make sync exit non-zero") + } + if failure, ok := err.(*driveSyncFailure); !ok || failure.ExitCode() != 1 { + t.Fatalf("error=%T %v", err, err) + } + assertMirrorUploadFailedJSON(t, output) + if putCalls != 1 { + t.Fatalf("OSS PUT calls=%d, want exactly 1", putCalls) + } + if got := len(caller.callsFor("get_upload_info")); got != 1 { + t.Fatalf("get_upload_info calls=%d, want 1", got) + } + if got := len(caller.callsFor("commit_upload")); got != 1 { + t.Fatalf("commit_upload calls=%d, want 1", got) + } + }) + } +} + // --dry-run：只计算差异，不触发任何 MCP 写操作与本地落盘。 func TestCrossPlatformCoverageDriveSync_dryRun(t *testing.T) { dir := t.TempDir() @@ -247,9 +277,7 @@ func TestCrossPlatformCoverageDriveSync_pullFailureKeepsLocal(t *testing.T) { } } -// keep-both 成功路径：本地既有文件改名保留（os.Rename 覆盖 O_EXCL 空占位），远端拉取到 -// 原路径。此测试在 Windows 主机上运行即验证 os.Rename 可替换既有目标（MOVEFILE_REPLACE_ -// EXISTING），覆盖 pull 覆盖与 keep-both 两条 rename 路径的平台行为。 +// keep-both 成功路径：先以 no-clobber 硬链接保留本地版本，再把远端拉取到原路径。 func TestCrossPlatformCoverageDriveSync_keepBothSuccess(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") @@ -282,9 +310,8 @@ func TestCrossPlatformCoverageDriveSync_keepBothSuccess(t *testing.T) { } } -// keep-both 下载失败：改名保留后拉取远端失败，应回滚改名——原文件恢复原名原内容， -// 不留下改名后的残留文件。 -func TestCrossPlatformCoverageDriveSync_keepBothRollbackOnPullFailure(t *testing.T) { +// keep-both 下载失败：不做可能误删并发文件的回滚，原名与本地保留候选都应保留。 +func TestCrossPlatformCoverageDriveSync_keepBothPreservesLinkOnPullFailure(t *testing.T) { dir := t.TempDir() p := filepath.Join(dir, "f.txt") mustWrite(t, p, "local-original") @@ -301,16 +328,13 @@ func TestCrossPlatformCoverageDriveSync_keepBothRollbackOnPullFailure(t *testing if err == nil { t.Fatal("下载失败时应以非零退出码退出") } - // 原文件恢复原名原内容。 + // 原名尚未被远端发布，保持原内容。 if b, rerr := os.ReadFile(p); rerr != nil || string(b) != "local-original" { - t.Errorf("keep-both 拉取失败应回滚改名, 原文件未恢复: got %q err=%v", string(b), rerr) + t.Errorf("keep-both 拉取失败后原文件应保留: got %q err=%v", string(b), rerr) } - // 目录下不应残留改名后的 *.conflict-* 文件。 - entries, _ := os.ReadDir(dir) - for _, e := range entries { - if strings.Contains(e.Name(), "conflict-") { - t.Errorf("回滚后不应残留改名文件: %s", e.Name()) - } + aside := filepath.Join(dir, "f.conflict-F_FID.txt") + if b, rerr := os.ReadFile(aside); rerr != nil || string(b) != "local-original" { + t.Errorf("keep-both 拉取失败后候选应保留: got %q err=%v", string(b), rerr) } } @@ -318,6 +342,7 @@ func TestCrossPlatformCoverageDriveSync_keepBothRollbackOnPullFailure(t *testing // 应原子占位到下一个后缀，且既有文件内容不被破坏。此断言在任何文件系统上都成立。 func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteExact(t *testing.T) { dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "f.txt"), "local-data") // 预置一个与首选候选精确同名的既有文件（模拟未被 occupied 记录的外部残留）。 first := "f.conflict-ABCD1234.txt" mustWrite(t, filepath.Join(dir, first), "existing-data") @@ -336,9 +361,9 @@ func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteExact(t *test if b, _ := os.ReadFile(filepath.Join(dir, first)); string(b) != "existing-data" { t.Error("既有文件被覆盖，数据丢失") } - // 返回的目标是新建的空占位文件。 - if fi, e := os.Stat(abs); e != nil || fi.Size() != 0 { - t.Errorf("占位文件应存在且为空: err=%v", e) + // 返回的目标是原始本地版本的硬链接，不是空占位。 + if b, e := os.ReadFile(abs); e != nil || string(b) != "local-data" { + t.Errorf("候选硬链接内容错误: content=%q err=%v", b, e) } } @@ -346,6 +371,7 @@ func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteExact(t *test // 既有文件——O_EXCL 由 OS 兜底判等价性，occupied 的精确字符串键覆盖不到这种情况。 func TestCrossPlatformCoverageReserveSyncKeepBothTarget_noOverwriteCaseEquivalent(t *testing.T) { dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "f.txt"), "local-data") if !isCaseInsensitiveFS(dir) { t.Skip("文件系统大小写敏感，跳过大小写等价覆盖测试") } diff --git a/internal/helpers/drive_sync_type_conflict_test.go b/internal/helpers/drive_sync_type_conflict_test.go index dbb66b66..9ed891ae 100644 --- a/internal/helpers/drive_sync_type_conflict_test.go +++ b/internal/helpers/drive_sync_type_conflict_test.go @@ -107,11 +107,11 @@ type driveSyncTransferCalls struct { func captureDriveSyncTransfers(t *testing.T) *driveSyncTransferCalls { t.Helper() calls := &driveSyncTransferCalls{} - testseam.Swap(t, &httpGetFile, func(context.Context, string, map[string]string, string) error { + swapPullDownloadPath(t, func(context.Context, string, map[string]string, string) error { calls.get++ return nil }) - testseam.Swap(t, &httpPutFile, func(context.Context, string, map[string]string, string, int64) error { + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { calls.put++ return nil }) diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 5289cf76..3842b17d 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -389,7 +389,7 @@ Flags: - 默认 `detection=exact`（比较 MD5）；传 `--quick` 后 `detection=quick`（只比较 modified_time，best-effort）。 - exact 模式**只在能拿到远端 MD5 时才判定 unchanged/modified**；远端缺失 MD5 的文件一律进入 `unknown`，绝不会因大小 / mtime 恰好相同而被误报为 unchanged。当前 `list_files` 通常不返回 MD5，因此这类文件多会落在 `unknown`——请据此决定是否用 `pull`/`push` 强制对齐。 - 本地 hash 仅在文件双端都存在、远端有 MD5、且非 `--quick` 模式时才按需计算。 -- 远端条目名称若含 `..`、路径分隔符或盘符等非规范成分，会被直接跳过、不纳入比对（防止逃逸性路径）。 +- 远端文件或文件夹名称若无法安全、无歧义地映射到本地路径（如 `..`、路径分隔符、盘符或目标平台保留名），命令会中止整棵远端树并返回失败；不会静默跳过后继续报告不完整结果。 - 只比对钉盘 `type=file` 的二进制文件；在线文档（docx/sheet/bitable/mindnote/slides）与快捷方式（shortcut）会被跳过。本地只比对常规文件（符号链接、设备文件忽略）。 - `--local-folder` 必须是绝对路径（相对路径会被直接拒绝）；`--remote-folder` 必传，是钉盘侧待比对文件夹的 dentryUuid（可用 `dws drive list` 查到）。 @@ -435,7 +435,8 @@ Flags: 注意事项： - 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 -- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时，命令会在下载前中止整棵远端树；拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 镜像采用跨平台一致的路径等价规则：远端树中若出现 `A/a`、Unicode NFC/NFD 异写，或等价目录前缀下的不同子树，会在任何下载前整批失败，避免不同文件系统得到不一致结果。 - 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 - `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，stderr 只保留简短失败说明。脚本/agent 直接看 exit code 即可判断成败。 @@ -485,6 +486,7 @@ Flags: - 只上传/覆盖 `type=file`；`summary.uploaded` 同时统计新建与覆盖，**不含目录**。 - `overwrite` / `smart` 命中覆盖分支时走**覆盖上传**（`get_upload_info` 与 `commit_upload` 两阶段都携带远端 `overwriteFileId`、不传 `parentId`），在原文件上原地覆盖、保留 fileId，不会在同目录新建重名副本。 - 本地子目录（含空目录）整体镜像：缺失的按需 `create_folder`（以 `folder_created` 留痕），已存在的远端目录复用其 fileId、不重建、不出现在 `items[]`。 +- 本地名称若含反斜杠、控制字符等无法安全映射到钉盘的成分，或双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义，命令会在任何创建或上传前整批失败；不会只跳过冲突项后继续写入。 - `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，脚本/agent 直接看 exit code 判断成败。 ### 本地文件夹与钉盘文件夹双向同步 @@ -514,10 +516,10 @@ Flags: | `skip`（默认） | 两侧都不动，两边内容都保留，计入 `skipped` | | `remote-wins` | 下载远端覆盖本地（需 `--yes`） | | `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId；需 `--yes`） | -| `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | +| `keep-both` | 先在同一目录以不覆盖的原子硬链接保留本地副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败时原文件与候选副本都保留并报告失败，不做可能误伤并发文件的回滚 | | `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | -输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；`direction`：`pull` / `push` / `conflict`）： +输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；其中 `renamed_local` 是兼容动作名，表示已成功保留本地冲突副本；`direction`：`pull` / `push` / `conflict`）： ```json { @@ -540,8 +542,9 @@ Flags: 注意事项： -- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符或盘符等非规范成分会被跳过，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 -- `--dry-run` 只算差异并打印 `diff`，不触发任何下载/上传/改名/落盘。 +- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时会在任何同步写入前中止整棵远端树，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 +- `--dry-run` 只算差异并输出独立 JSON 预览对象，不触发任何下载/上传/改名/落盘；差异位于顶层预览对象的 `plan.diff`（同时包含 `dry_run=true`、`executed=false` 与 `preview_kind=plan`）。 +- 双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义时，`sync` 会在任何一侧写入前整批失败；本地无法安全映射到钉盘的名称同样 fail-closed。 - `unknown`（exact 模式远端无可靠 MD5）一律计入 `skipped`、不做任何写操作；需要强制对齐时改用单向的 `pull`/`push`。 - `summary.failed > 0` 时命令以**非零退出码**退出，结构化结果仍打印在 stdout 上。 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 04703443..096a3c8a 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -374,7 +374,7 @@ Flags: - 默认 `detection=exact`（比较 MD5）；传 `--quick` 后 `detection=quick`（只比较 modified_time，best-effort）。 - exact 模式**只在能拿到远端 MD5 时才判定 unchanged/modified**；远端缺失 MD5 的文件一律进入 `unknown`，绝不会因大小 / mtime 恰好相同而被误报为 unchanged。当前 `list_files` 通常不返回 MD5，因此这类文件多会落在 `unknown`——请据此决定是否用 `pull`/`push` 强制对齐。 - 本地 hash 仅在文件双端都存在、远端有 MD5、且非 `--quick` 模式时才按需计算。 -- 远端条目名称若含 `..`、路径分隔符或盘符等非规范成分，会被直接跳过、不纳入比对（防止逃逸性路径）。 +- 远端文件或文件夹名称若无法安全、无歧义地映射到本地路径（如 `..`、路径分隔符、盘符或目标平台保留名），命令会中止整棵远端树并返回失败；不会静默跳过后继续报告不完整结果。 - 只比对钉盘 `type=file` 的二进制文件；在线文档（docx/sheet/bitable/mindnote/slides）与快捷方式（shortcut）会被跳过。本地只比对常规文件（符号链接、设备文件忽略）。 - `--local-folder` 必须是绝对路径（相对路径会被直接拒绝）；`--remote-folder` 必传，是钉盘侧待比对文件夹的 dentryUuid（可用 `dws drive list` 查到）。 @@ -420,7 +420,8 @@ Flags: 注意事项： - 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 -- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符或盘符等非规范成分的条目会被跳过，拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时，命令会在下载前中止整棵远端树；拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 +- 镜像采用跨平台一致的路径等价规则：远端树中若出现 `A/a`、Unicode NFC/NFD 异写，或等价目录前缀下的不同子树，会在任何下载前整批失败，避免不同文件系统得到不一致结果。 - 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 - `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，stderr 只保留简短失败说明。脚本/agent 直接看 exit code 即可判断成败。 @@ -470,6 +471,7 @@ Flags: - 只上传/覆盖 `type=file`；`summary.uploaded` 同时统计新建与覆盖，**不含目录**。 - `overwrite` / `smart` 命中覆盖分支时走**覆盖上传**（`get_upload_info` 与 `commit_upload` 两阶段都携带远端 `overwriteFileId`、不传 `parentId`），在原文件上原地覆盖、保留 fileId，不会在同目录新建重名副本。 - 本地子目录（含空目录）整体镜像：缺失的按需 `create_folder`（以 `folder_created` 留痕），已存在的远端目录复用其 fileId、不重建、不出现在 `items[]`。 +- 本地名称若含反斜杠、控制字符等无法安全映射到钉盘的成分，或双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义，命令会在任何创建或上传前整批失败；不会只跳过冲突项后继续写入。 - `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，脚本/agent 直接看 exit code 判断成败。 ### 本地文件夹与钉盘文件夹双向同步 @@ -499,10 +501,10 @@ Flags: | `skip`（默认） | 两侧都不动，两边内容都保留，计入 `skipped` | | `remote-wins` | 下载远端覆盖本地（需 `--yes`） | | `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId；需 `--yes`） | -| `keep-both` | 本地先改名保留副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败会回滚改名、恢复原文件 | +| `keep-both` | 先在同一目录以不覆盖的原子硬链接保留本地副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败时原文件与候选副本都保留并报告失败，不做可能误伤并发文件的回滚 | | `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | -输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；`direction`：`pull` / `push` / `conflict`）： +输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；其中 `renamed_local` 是兼容动作名，表示已成功保留本地冲突副本；`direction`：`pull` / `push` / `conflict`）： ```json { @@ -525,8 +527,9 @@ Flags: 注意事项： -- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符或盘符等非规范成分会被跳过，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 -- `--dry-run` 只算差异并打印 `diff`，不触发任何下载/上传/改名/落盘。 +- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时会在任何同步写入前中止整棵远端树，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 +- `--dry-run` 只算差异并输出独立 JSON 预览对象，不触发任何下载/上传/改名/落盘；差异位于顶层预览对象的 `plan.diff`（同时包含 `dry_run=true`、`executed=false` 与 `preview_kind=plan`）。 +- 双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义时，`sync` 会在任何一侧写入前整批失败；本地无法安全映射到钉盘的名称同样 fail-closed。 - `unknown`（exact 模式远端无可靠 MD5）一律计入 `skipped`、不做任何写操作；需要强制对齐时改用单向的 `pull`/`push`。 - `summary.failed > 0` 时命令以**非零退出码**退出，结构化结果仍打印在 stdout 上。 From 6b3f2e29bd7c115a1512f3c56b6fb71ba48a4f13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Thu, 13 Aug 2026 16:08:35 +0800 Subject: [PATCH 067/250] docs: add international region usage guide --- README.md | 1 + README_zh.md | 1 + docs/international-region-guide.md | 154 +++++++++++++++++++ docs/international-region-guide.zh-CN.md | 185 +++++++++++++++++++++++ internal/app/auth_command.go | 13 +- 5 files changed, 350 insertions(+), 4 deletions(-) create mode 100644 docs/international-region-guide.md create mode 100644 docs/international-region-guide.zh-CN.md diff --git a/README.md b/README.md index b29410ae..ec3e7416 100644 --- a/README.md +++ b/README.md @@ -786,6 +786,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step ## Reference & Docs +- [International DingTalk (`.io`) guide](./docs/international-region-guide.md) — international login, domestic/international profile switching, isolated testing, and troubleshooting - [Command Index](./docs/command-index.md) — every runtime command with description and when-to-use guidance - [Reference](./docs/reference.md) — environment variables, exit codes, output formats, shell completion - [Architecture](./docs/architecture.md) — static endpoint pipeline, command surface, transport layer diff --git a/README_zh.md b/README_zh.md index b61cb62d..e47544a4 100644 --- a/README_zh.md +++ b/README_zh.md @@ -777,6 +777,7 @@ dws dev connect --channel auto --robot-client-id --robot-client-secret \ + --client-secret +``` + +This mode still requires the user to complete OAuth authorization in a browser; it is not a userless `client_credentials` login. The application must be configured on the international developer platform with the required callback and permissions. Never commit an AppSecret to source control or include it in logs. + +## Verify the login + +```bash +dws auth status --format json +dws profile list --format json +dws contact user get-self +``` + +The last command is a read-only smoke check. If the organization has not enabled CLI access, an organization administrator must enable it or approve the access request on the international developer platform. + +## Use domestic and international profiles together + +```bash +# Domestic (.com) +dws auth login + +# International (.io) +dws auth login --intl + +# Find the stable profile selectors +dws profile list --format json +``` + +Persistently switch profiles: + +```bash +dws profile switch : +``` + +Toggle back to the previous profile: + +```bash +dws profile switch - +``` + +Select a profile for one command without changing the default: + +```bash +dws --profile : contact user get-self +``` + +Do not add `--intl` to business commands. DWS routes official endpoints from the selected profile's Token region. + +## Isolated smoke testing + +Use a separate configuration directory to avoid changing the normal `~/.dws` login state: + +```bash +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth login --intl +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth status --format json +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws contact user get-self +``` + +Use the same `DWS_CONFIG_DIR` for every command. Use `./dws` for a source build and `dws` for an installed release. + +## Pre-release overrides (maintainers only) + +Normal international users need only `--intl`; they should not set `--pre-url` or `--mcp-url`. + +Maintainers can test the pre-release login/MCP pair with: + +```bash +dws auth login --intl --pre-url https://pre-login.dingtalk.io +``` + +A corresponding `pre-mcp.*` URL is also accepted, and DWS derives the paired `pre-login.*` / `pre-mcp.*` bases. `--mcp-url` explicitly overrides the MCP base URL for that login. + +Pre-release services may require internal network access or allowlisted accounts. `--pre-url` is intended primarily for the MCP-managed credential flow. Do not combine it with direct custom `--client-id/--client-secret` mode unless the pre-release API contract explicitly supports that combination. + +## Troubleshooting + +### The browser still opens a `.com` page + +1. Run `dws auth login --help` and confirm `--intl` is present. +2. For a source checkout, use `./dws` instead of an older installed binary. +3. Confirm the executed command is `dws auth login --intl`. + +### A business command appears to use the wrong region + +Run `dws profile list --format json`, then switch with the exact `:` selector or use the global `--profile` option. For a legacy Token created before region metadata existed, reauthorize it with `dws auth login --intl` for an international account or `dws auth login` for a domestic account. + +### Login succeeds but the command reports missing permission + +This normally means the organization has not enabled CLI access or the application lacks a required permission. It does not by itself indicate a region-routing failure. + +### Should I edit `~/.dws/mcp_url` manually? + +No. Normal users should establish the login with `dws auth login` or `dws auth login --intl`. DWS then routes official endpoints from the selected Token/profile. Manual configuration is reserved for maintainers who explicitly control the target environment. + +## Command reference + +| Scenario | Command | +|---|---| +| Domestic browser login | `dws auth login` | +| International browser login | `dws auth login --intl` | +| International device login | `dws auth login --intl --device` | +| Check auth state | `dws auth status --format json` | +| List profiles | `dws profile list --format json` | +| Persistently switch profile | `dws profile switch :` | +| Toggle to previous profile | `dws profile switch -` | +| Select a profile once | `dws --profile : ` | diff --git a/docs/international-region-guide.zh-CN.md b/docs/international-region-guide.zh-CN.md new file mode 100644 index 00000000..8ad9d3ac --- /dev/null +++ b/docs/international-region-guide.zh-CN.md @@ -0,0 +1,185 @@ +# DWS 国际版（DingTalk `.io`）使用手册 + +本手册适用于使用钉钉国际版账号登录并调用国际站服务的用户。 + +## 核心规则 + +- `dws auth login --intl` 创建或刷新国际版登录，使用 `*.dingtalk.io` 登录、鉴权和 MCP 服务。 +- 不传 `--intl` 时仍使用国内钉钉 `*.dingtalk.com`，原有链路保持不变。 +- `--intl` 只用于登录命令。登录完成后，`contact`、`calendar`、`doc` 等业务命令不需要再传该参数。 +- 每个 Token 会记录登录区域。执行业务命令时，DWS 根据当前或 `--profile` 指定的账号自动选择 `.com` 或 `.io` 网关。 +- `--international` 是 `--intl` 的兼容别名；新脚本推荐使用较短的 `--intl`。 + +## 确认当前版本支持国际版 + +运行： + +```bash +dws auth login --help +``` + +帮助中应包含： + +```text +--intl +--international +``` + +从源码分支验证时，先在仓库根目录构建，并始终使用本次构建的 `./dws`，避免误用系统中已安装的旧版本： + +```bash +make build +./dws auth login --help +``` + +## 国际版登录 + +### 浏览器登录 + +```bash +dws auth login --intl +``` + +DWS 会打开国际版登录页面。完成扫码或账号授权后，登录结果会保存为本机 profile。 + +### 设备码登录 + +适用于 SSH、容器或没有可用浏览器的环境： + +```bash +dws auth login --intl --device +``` + +按照终端提示，在另一台可打开浏览器的设备上完成授权。 + +### 使用自有应用凭证完成用户 OAuth + +```bash +dws auth login --intl \ + --client-id \ + --client-secret +``` + +该模式仍然需要用户在浏览器中完成 OAuth 授权，不是无用户授权的 `client_credentials` 登录。应用必须在国际版开放平台正确配置回调地址和所需权限。不要在命令历史、日志或 PR 中提交真实的 AppSecret。 + +## 验证登录和业务调用 + +查看当前登录状态： + +```bash +dws auth status --format json +``` + +列出本机全部账号并找到当前 profile： + +```bash +dws profile list --format json +``` + +执行一个只读命令验证国际链路，例如： + +```bash +dws contact user get-self +``` + +登录状态正常但业务命令提示组织未开通 CLI 时，需要由国际版组织管理员在国际版开发者平台开启 CLI 访问或完成授权审批。 + +## 国内版和国际版账号并存 + +可以在同一台机器上分别登录国内版和国际版账号： + +```bash +# 国内版（.com） +dws auth login + +# 国际版（.io） +dws auth login --intl + +# 查看稳定的 profile 选择器 +dws profile list --format json +``` + +持久切换账号： + +```bash +dws profile switch : +``` + +切回上一个账号： + +```bash +dws profile switch - +``` + +只为单次命令指定账号，不修改默认账号： + +```bash +dws --profile : contact user get-self +``` + +DWS 会按照选中 profile 的 Token 区域自动选择 `.com` 或 `.io`，不需要在业务命令上追加 `--intl`。 + +## 使用独立配置目录进行验证 + +如果不希望测试登录影响日常使用的 `~/.dws`，可以指定独立配置目录： + +```bash +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth login --intl +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth status --format json +DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws contact user get-self +``` + +请在三条命令中使用同一个 `DWS_CONFIG_DIR`。验证源码分支时使用 `./dws`；验证已安装版本时可改为 `dws`。 + +## 预发参数（仅维护者） + +普通国际版用户只需要 `--intl`，不要配置 `--pre-url` 或 `--mcp-url`。 + +维护者验证预发登录/MCP 链路时可以使用： + +```bash +dws auth login --intl --pre-url https://pre-login.dingtalk.io +``` + +也可以传入对应的 `pre-mcp.*` 地址；DWS 会推导配套的 `pre-login.*` / `pre-mcp.*` 地址。`--mcp-url` 用于显式覆盖本次登录的 MCP base URL。 + +预发环境可能只对内网或特定测试账号开放。`--pre-url` 主要服务于 MCP 托管凭证登录流程；除非预发 API 契约已经明确支持，否则不要把它与自有 `--client-id/--client-secret` 直连模式组合使用。 + +## 常见问题 + +### 仍然打开 `.com` 登录页面 + +1. 运行 `dws auth login --help`，确认当前二进制包含 `--intl`。 +2. 从源码验证时使用 `./dws`，不要误用 PATH 中的旧版本。 +3. 确认实际执行的是 `dws auth login --intl`，而不是普通 `dws auth login`。 + +### 业务命令似乎使用了错误区域 + +先检查当前账号： + +```bash +dws profile list --format json +``` + +然后使用精确的 `:` 切换或通过全局 `--profile` 单次指定。对于在区域字段引入前生成的历史 Token，建议使用正确的登录方式重新授权：国际账号执行 `dws auth login --intl`，国内账号执行 `dws auth login`。 + +### 登录成功但提示没有权限 + +这通常是组织 CLI 准入或应用授权问题，不代表区域路由失败。请确认目标组织已开启 CLI 访问，并且当前应用拥有命令所需权限。 + +### 是否需要手工修改 `~/.dws/mcp_url` + +不需要。正常使用应通过 `dws auth login` 或 `dws auth login --intl` 建立登录态；业务命令会根据选中的 Token/profile 自动路由。手工修改配置只适用于明确了解目标环境的维护者调试场景。 + +## 命令速查 + +| 场景 | 命令 | +|---|---| +| 国内版浏览器登录 | `dws auth login` | +| 国际版浏览器登录 | `dws auth login --intl` | +| 国际版设备码登录 | `dws auth login --intl --device` | +| 查看登录状态 | `dws auth status --format json` | +| 查看所有账号 | `dws profile list --format json` | +| 持久切换账号 | `dws profile switch :` | +| 切回上一个账号 | `dws profile switch -` | +| 单次指定账号 | `dws --profile : ` | diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index 508c4836..07e58d9b 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -113,12 +113,17 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { 支持的登录方式: - OAuth Loopback 流 (默认): 本机自动起 127.0.0.1 监听接收回调，浏览器授权后自动完成 - OAuth 设备流 (--device): 显示 user_code + 短 URL，适合 SSH 远程 / 容器 / 无头环境 + - 自有应用 OAuth (--client-id/--client-secret): 使用指定应用完成用户授权 - 直接提供 Token (--token): 跳过授权，使用已有 token 不支持的登录方式: - 邮箱/密码登录 - 手机号/验证码登录 - - 应用凭证 (AppKey/AppSecret) 直接登录 + - 无用户授权的纯应用凭证 (client_credentials) 登录 + +区域: + - 默认使用国内钉钉 .com 登录与服务端点 + - --intl（或 --international）使用国际版 .io 登录；后续业务命令按所选 profile 自动路由 注意: SSH 远程或无头环境（无本地浏览器可访问远端的 127.0.0.1）请使用 --device， 否则 OAuth 回调会跳到本机不可达的 127.0.0.1 链接，授权完成后无法回写 token。 @@ -126,7 +131,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { 示例: dws auth login # 本机登录并新增/刷新一个组织 profile dws auth login --profile # 指定本次授权目标组织，不持久切换当前组织 - dws auth login --intl # 使用钉钉国际登录入口 + dws auth login --intl # 使用钉钉国际版 .io 登录入口 dws auth login --intl --pre-url https://pre-login.dingtalk.io dws auth login --intl --pre-url https://pre-mcp.dingtalk.io dws auth login --recommend # 无交互批量授权服务端推荐权限 @@ -318,8 +323,8 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { } cmd.Flags().String("token", "", "Access token") cmd.Flags().Bool("device", false, "Use device authorization flow") - cmd.Flags().Bool("intl", false, "Use DingTalk international login") - cmd.Flags().Bool("international", false, "Use DingTalk international login") + cmd.Flags().Bool("intl", false, "Use DingTalk international (.io) login and service endpoints") + cmd.Flags().Bool("international", false, "Use DingTalk international (.io) login and service endpoints") cmd.Flags().String("pre-url", "", "Override pre-release login/MCP base URL for this login") cmd.Flags().String("mcp-url", "", "Override MCP base URL for this login") cmd.Flags().Bool("force", false, "兼容保留；login 默认已忽略缓存并进入授权流程") From 6abffce4e5e8f8e79b87629df6c8334255f37019 Mon Sep 17 00:00:00 2001 From: xiatian Date: Thu, 13 Aug 2026 16:13:30 +0800 Subject: [PATCH 068/250] fix(sheet): preserve dropdown schema compatibility --- internal/helpers/sheet_dimension.go | 6 --- .../sheet_dropdown_source_range_test.go | 49 ++++++++++++++----- 2 files changed, 37 insertions(+), 18 deletions(-) diff --git a/internal/helpers/sheet_dimension.go b/internal/helpers/sheet_dimension.go index 2b442f02..1b902cc6 100644 --- a/internal/helpers/sheet_dimension.go +++ b/internal/helpers/sheet_dimension.go @@ -907,7 +907,6 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 Parameters: []contract.ParamDecl{ {Name: "multi-select", Property: "enableMultiSelect"}, {Name: "node", Property: "nodeId"}, - {Name: "options", Property: "options", Required: boolPtr(false), RequiredWhen: "exactly one of --options or --source-range must be provided"}, {Name: "source-sheet-id", Property: "sourceRange.sheetId", Required: boolPtr(false), RequiredWhen: "--source-range is provided"}, {Name: "source-range", Property: "sourceRange.a1Notation", Required: boolPtr(false), RequiredWhen: "exactly one of --options or --source-range must be provided"}, }, @@ -924,11 +923,6 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 setDropdownCmd.MarkFlagsOneRequired("options", "source-range") setDropdownCmd.MarkFlagsMutuallyExclusive("options", "source-range") setDropdownCmd.MarkFlagsRequiredTogether("source-sheet-id", "source-range") - cli.AnnotateRuntimeConstraints(setDropdownCmd, cli.RuntimeSchemaConstraints{ - MutuallyExclusive: [][]string{{"options", "source-range"}}, - RequireOneOf: [][]string{{"options", "source-range"}}, - RequireTogether: [][]string{{"source-sheet-id", "source-range"}}, - }) getDropdownCmd := &cobra.Command{ Use: "get-dropdown", diff --git a/internal/helpers/sheet_dropdown_source_range_test.go b/internal/helpers/sheet_dropdown_source_range_test.go index af7c1eeb..071e8ba4 100644 --- a/internal/helpers/sheet_dropdown_source_range_test.go +++ b/internal/helpers/sheet_dropdown_source_range_test.go @@ -1,7 +1,6 @@ package helpers import ( - "encoding/json" "strings" "testing" @@ -92,18 +91,43 @@ func TestCrossPlatformCoverageSetDropdownModeConstraints(t *testing.T) { } } -func TestCrossPlatformCoverageSetDropdownSchemaConstraints(t *testing.T) { - cmd := dimensionCoverageCommand(t, "set-dropdown") - constraints := runtimeannotate.CommandConstraints(cmd) - want := runtimeannotate.RuntimeSchemaConstraints{ - MutuallyExclusive: [][]string{{"options", "source-range"}}, - RequireOneOf: [][]string{{"options", "source-range"}}, - RequireTogether: [][]string{{"source-sheet-id", "source-range"}}, +func TestCrossPlatformCoverageSetDropdownRunEValidation(t *testing.T) { + tests := []struct { + name string + options string + source string + rangeID string + want string + }{ + {name: "neither mode", want: "必须且只能指定一个"}, + {name: "source range without sheet", rangeID: "A1:A3", want: "必须同时指定 --source-sheet-id"}, + {name: "source sheet without range", options: `[{"value":"one"}]`, source: "source", want: "必须同时指定 --source-range"}, + {name: "invalid options JSON", options: "{", want: "JSON 解析失败"}, + {name: "missing option value", options: `[{}]`, want: "value 为空"}, } - gotJSON, _ := json.Marshal(constraints) - wantJSON, _ := json.Marshal(runtimeannotate.NormalizeConstraints(want)) - if string(gotJSON) != string(wantJSON) { - t.Fatalf("constraints = %s, want %s", gotJSON, wantJSON) + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + cmd := dimensionCoverageCommand(t, "set-dropdown") + for name, value := range map[string]string{ + "node": "node", "sheet-id": "sheet", "range": "A1", + "options": tc.options, "source-sheet-id": tc.source, "source-range": tc.rangeID, + } { + if err := cmd.Flags().Set(name, value); err != nil { + t.Fatalf("set --%s: %v", name, err) + } + } + err := cmd.RunE(cmd, nil) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want contains %q", err, tc.want) + } + }) + } +} + +func TestCrossPlatformCoverageSetDropdownPreservesSchemaConstraints(t *testing.T) { + cmd := dimensionCoverageCommand(t, "set-dropdown") + if constraints := runtimeannotate.CommandConstraints(cmd); !runtimeannotate.ConstraintsEmpty(constraints) { + t.Fatalf("constraints = %#v, want no new schema-level constraints", constraints) } } @@ -135,6 +159,7 @@ func TestCrossPlatformCoverageBatchSetDropdownSourceRange(t *testing.T) { {"options": []any{map[string]any{"value": "one"}}, "source-sheet-id": "source", "source-range": "A1:A3"}, {"source-range": "A1:A3"}, {"source-sheet-id": "source", "source-range": "A1:A3", "colors": []any{"#fff"}}, + {"source-sheet-id": "source", "source-range": "A1:A3", "source-colors": []any{"#fff"}}, {"source-sheet-id": "source", "source-range": "Sheet2!A1:A3"}, } for _, value := range invalid { From 35f399e2cf78a72073f5e6a2359d3aa2dd1d5651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 16:16:00 +0800 Subject: [PATCH 069/250] fix(chat): use Shanghai time for message defaults --- internal/helpers/chat.go | 8 +++- internal/helpers/chat_message_search_test.go | 43 ++++++++++++++++++++ 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index c1c7e672..69af617d 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -615,6 +615,10 @@ func formatChatMessageListAllTime(ms int64) string { return time.UnixMilli(ms).Format("2006-01-02 15:04:05") } +func defaultChatMessageListTime() string { + return time.Now().In(shanghaiLocation()).Format("2006-01-02 15:04:05") +} + func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { toolArgs := map[string]any{} if v := flagOrFallback(cmd, "query", "keyword"); v != "" { @@ -2664,7 +2668,7 @@ func newChatCommand() *cobra.Command { timeVal := mustGetFlag(cmd, "time") defaultForward := true if timeVal == "" { - timeVal = time.Now().Format("2006-01-02 15:04:05") + timeVal = defaultChatMessageListTime() defaultForward = false } forward, err := resolveMessageForward(cmd, defaultForward) @@ -2756,7 +2760,7 @@ func newChatCommand() *cobra.Command { timeVal, _ := cmd.Flags().GetString("time") defaultForward := true if strings.TrimSpace(timeVal) == "" { - timeVal = time.Now().Format("2006-01-02 15:04:05") + timeVal = defaultChatMessageListTime() defaultForward = false } forward, err := resolveMessageForward(cmd, defaultForward) diff --git a/internal/helpers/chat_message_search_test.go b/internal/helpers/chat_message_search_test.go index 340a3bd6..44c68aab 100644 --- a/internal/helpers/chat_message_search_test.go +++ b/internal/helpers/chat_message_search_test.go @@ -724,6 +724,49 @@ func TestCrossPlatformCoverageChatMessageListUsesMCPMetadataGroupKey(t *testing. } } +func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t *testing.T) { + previousLocal := time.Local + time.Local = time.UTC + t.Cleanup(func() { time.Local = previousLocal }) + + tests := []struct { + name string + args []string + }{ + {name: "group", args: []string{"message", "list", "--group", "cid-1", "--limit", "50"}}, + {name: "direct", args: []string{"message", "list-direct", "--user", "user-1", "--limit", "50"}}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatChangedContractCaller{} + before := time.Now() + err := executeChatChangedContract(t, caller, tt.args...) + after := time.Now() + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one MCP call", caller.calls) + } + raw, ok := caller.calls[0].args["time"].(string) + if !ok || raw == "" { + t.Fatalf("time arg = %#v, want non-empty string", caller.calls[0].args["time"]) + } + got, err := time.ParseInLocation("2006-01-02 15:04:05", raw, shanghaiLocation()) + if err != nil { + t.Fatalf("time arg = %q, parse err = %v", raw, err) + } + if got.Before(before.Add(-time.Second)) || got.After(after.Add(time.Second)) { + t.Fatalf("time arg = %q (%s), want current time in Shanghai between %s and %s", raw, got, before, after) + } + if caller.calls[0].args["forward"] != false { + t.Fatalf("forward = %#v, want false when --time is omitted", caller.calls[0].args["forward"]) + } + }) + } +} + func TestCrossPlatformCoverageChatAuditUsesUserIDs(t *testing.T) { caller := &chatChangedContractCaller{} err := executeChatChangedContract(t, caller, From 913b7cf9a92e580e27e2049013d7ecf52caaa250 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 16:15:41 +0800 Subject: [PATCH 070/250] chore(cli): refresh generated param aliases --- internal/cli/param_aliases_generated.go | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index 63c62457..b7e9d366 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -1456,11 +1456,10 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message read-status", Aliases: map[string]string{ - "chat-id": "conversation-id", - "msg-id": "message-id", - "open-conversation-id": "conversation-id", - "open-message-id": "message-id", - "user-ids": "users", + "chat-id": "conversation-id", + "msg-id": "message-id", + "open-message-id": "message-id", + "user-ids": "users", }, Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"}, }, From 4b8d94c24eab4c8fb7138c28fd0b83263f297887 Mon Sep 17 00:00:00 2001 From: xiatian Date: Thu, 13 Aug 2026 17:15:22 +0800 Subject: [PATCH 071/250] ci: retry interrupted app race shard From a32608f96400fcba8aa2af35b84c3341b6122e04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 17:38:35 +0800 Subject: [PATCH 072/250] fix(chat): use local time for message defaults --- internal/helpers/chat.go | 23 +++++++++++++++++-- .../helpers/chat_message_pagination_test.go | 22 ++++++++++++++++-- internal/helpers/chat_message_search_test.go | 6 ++--- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 69af617d..5950772a 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -467,7 +467,7 @@ func validateNativeSearchConversationScope(conversationIDs []string) error { } func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { - startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 24*time.Hour) + startRaw, endRaw, err := defaultChatMessageListAllTimeRange(cmd, 24*time.Hour) if err != nil { return nil, err } @@ -480,6 +480,25 @@ func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { }, nil } +func defaultChatMessageListAllTimeRange(cmd *cobra.Command, lookback time.Duration) (string, string, error) { + startRaw := mustGetFlag(cmd, "start") + endRaw := mustGetFlag(cmd, "end") + anchor := time.Now() + if endRaw == "" { + endRaw = formatChatMessageListAllTime(anchor.UnixMilli()) + } else if startRaw == "" { + endMs, err := parseISOTimeToMillis("end", endRaw) + if err != nil { + return "", "", err + } + anchor = time.UnixMilli(endMs) + } + if startRaw == "" { + startRaw = formatChatMessageListAllTime(anchor.Add(-lookback).UnixMilli()) + } + return startRaw, endRaw, nil +} + func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { senderUserID := flagOrFallback(cmd, "sender-user-id", "sender") senderOpenDingTalkID, _ := cmd.Flags().GetString("sender-open-dingtalk-id") @@ -616,7 +635,7 @@ func formatChatMessageListAllTime(ms int64) string { } func defaultChatMessageListTime() string { - return time.Now().In(shanghaiLocation()).Format("2006-01-02 15:04:05") + return time.Now().Format("2006-01-02 15:04:05") } func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index f373e130..e444eb5b 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -210,6 +210,10 @@ func TestChatMessagePaginationUsesDefaultTimeWindows(t *testing.T) { if startMs < wantStartMin || startMs > wantStartMax { t.Fatalf("startTime = %d, want between %d and %d", startMs, wantStartMin, wantStartMax) } + if tt.wantTool == "search_messages_by_time_range" { + assertChatMessageListAllTimeFormat(t, got.args["startTime"]) + assertChatMessageListAllTimeFormat(t, got.args["endTime"]) + } }) } } @@ -276,7 +280,7 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { t.Fatalf("startTime = %d, want %d", startMs, wantStartMs) } if tt.wantTool == "search_messages_by_time_range" { - assertStringArg(t, got.args["startTime"], time.UnixMilli(wantStartMs).Format(time.RFC3339)) + assertStringArg(t, got.args["startTime"], formatChatMessageListAllTime(wantStartMs)) assertStringArg(t, got.args["endTime"], endRaw) } }) @@ -344,7 +348,7 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing } if tt.wantTool == "search_messages_by_time_range" { assertStringArg(t, got.args["startTime"], startRaw) - parseChatMessageListAllTimeArg(t, got.args["endTime"]) + assertChatMessageListAllTimeFormat(t, got.args["endTime"]) } }) } @@ -440,6 +444,20 @@ func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time { return parsed } +func assertChatMessageListAllTimeFormat(t *testing.T, value any) { + t.Helper() + raw, ok := value.(string) + if !ok { + t.Fatalf("time arg = %#v, want time string", value) + } + if strings.Contains(raw, "T") { + t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw) + } + if _, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local); err != nil { + t.Fatalf("time arg = %q, parse err = %v", raw, err) + } +} + func assertStringArg(t *testing.T, value any, want string) { t.Helper() got, ok := value.(string) diff --git a/internal/helpers/chat_message_search_test.go b/internal/helpers/chat_message_search_test.go index 44c68aab..eeec924e 100644 --- a/internal/helpers/chat_message_search_test.go +++ b/internal/helpers/chat_message_search_test.go @@ -724,7 +724,7 @@ func TestCrossPlatformCoverageChatMessageListUsesMCPMetadataGroupKey(t *testing. } } -func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t *testing.T) { +func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesLocalLocation(t *testing.T) { previousLocal := time.Local time.Local = time.UTC t.Cleanup(func() { time.Local = previousLocal }) @@ -753,12 +753,12 @@ func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t * if !ok || raw == "" { t.Fatalf("time arg = %#v, want non-empty string", caller.calls[0].args["time"]) } - got, err := time.ParseInLocation("2006-01-02 15:04:05", raw, shanghaiLocation()) + got, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local) if err != nil { t.Fatalf("time arg = %q, parse err = %v", raw, err) } if got.Before(before.Add(-time.Second)) || got.After(after.Add(time.Second)) { - t.Fatalf("time arg = %q (%s), want current time in Shanghai between %s and %s", raw, got, before, after) + t.Fatalf("time arg = %q (%s), want current local time between %s and %s", raw, got, before, after) } if caller.calls[0].args["forward"] != false { t.Fatalf("forward = %#v, want false when --time is omitted", caller.calls[0].args["forward"]) From 18fad57bbe0c37f0ffd9e35bb66ae439e8ec3698 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 17:44:56 +0800 Subject: [PATCH 073/250] docs: seal changelog for v1.0.58 --- CHANGELOG.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1809c488..0656ba9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,30 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +## [1.0.58] - 2026-08-13 + +This release promotes the sealed `v1.0.58-beta.6` contents to stable. + +### Changed + +- **Expanded collaborative workflows** — adds full AI Table, Sheet, Minutes, + approval-event, Drive-comment, document export, and CSV workflow support, + including safer validation, explicit confirmation for writes, and + machine-readable completion receipts. +- **More capable Chat operations** — adds robot image/file messages, toolbar + management, streaming-card mentions, automatic pagination controls, and + clearer post-send ID, Markdown-image, paging, and result-shape guidance. +- **Reliable Agent and CLI contracts** — expands Agent-visible Chat and + Minutes commands, aligns bundled skills, improves schema/result envelopes, + and hardens parameter, pagination, runtime-token, and write-result + verification so ambiguous or incomplete operations fail closed. +- **Multi-skill install and upgrade** — makes the multi-skill layout the + default for fresh installs and upgrades while preserving an explicit legacy + mono option. +- **Safer release delivery** — strengthens release-equivalent compatibility, + sealing, package verification, and evaluation-dispatch checks for more + reliable cross-platform releases. + ## [1.0.58-beta.6] - 2026-08-13 ### Fixed From 90278ab2fc69215cf41942e405d9774b80193750 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 18:01:57 +0800 Subject: [PATCH 074/250] test(chat): cover message default end window --- internal/helpers/chat_command_edges_test.go | 1 + 1 file changed, 1 insertion(+) diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 2c97ce06..93322ff4 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -180,6 +180,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"message", "list-by-sender", "--sender-user-id=u1", "--start=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-02T00:00:00Z", "--end=2026-01-01T00:00:00Z"}, + {"message", "list-by-sender", "--sender-user-id=u1", "--end=2026-01-02T00:00:00Z"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=2026-01-02T00:00:00Z"}, {"message", "list-by-sender", "--sender-open-dingtalk-id=D1", "--start=2026-01-01T00:00:00Z"}, {"message", "list-mentions", "--start=bad", "--end=2026-01-02T00:00:00Z"}, From ec83d8ff53df366f5388baeb2c09b50b7398c0bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Thu, 13 Aug 2026 18:10:23 +0800 Subject: [PATCH 075/250] fix(auth): harden international login routing --- internal/app/auth_command.go | 23 ++- .../app/auth_command_full_coverage_test.go | 41 +++++- internal/app/auth_command_test.go | 135 ++++++++++++++++-- internal/app/coverage_edges_test.go | 67 ++++++++- internal/app/root_help_test.go | 6 +- internal/app/runner_full_coverage_test.go | 30 ++++ internal/auth/auth_extra_test.go | 39 ++++- internal/auth/cli_auth_check_test.go | 48 ++++++- internal/auth/device_flow_test.go | 2 +- internal/auth/endpoints.go | 3 + internal/errors/errors_test.go | 2 +- internal/transport/client_extra_test.go | 8 +- pkg/config/constants_test.go | 4 +- 13 files changed, 373 insertions(+), 35 deletions(-) diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index 07e58d9b..d4e0f7c1 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -173,6 +173,9 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { AccessToken: cfg.Token, ExpiresAt: time.Now().Add(config.ManualTokenExpiry), } + if cfg.International { + tokenData.LoginRegion = string(authpkg.LoginRegionInternational) + } if err := authSaveTokenData(configDir, tokenData); err != nil { return apperrors.NewInternal(fmt.Sprintf("failed to persist auth token: %v", err)) } @@ -1384,13 +1387,10 @@ func authLoginMCPBaseURLForConfig(cfg authLoginConfig, preOverrides authLoginEnd } func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persist bool) error { - if persist { - return authpkg.NewManager(configDir, nil).SaveMCPURL(mcpBaseURL) + if !persist { + return nil } - if err := os.Remove(filepath.Join(configDir, "mcp_url")); err != nil && !os.IsNotExist(err) { - return err - } - return nil + return authpkg.NewManager(configDir, nil).SaveMCPURL(mcpBaseURL) } func normalizeAuthLoginBaseURL(raw, flagName string) (*url.URL, string, error) { @@ -1411,12 +1411,23 @@ func normalizeAuthLoginBaseURL(raw, flagName string) (*url.URL, string, error) { if parsed.Hostname() == "" { return nil, "", apperrors.NewValidation(flagName + " must include a host") } + if parsed.Scheme == "http" && !isAuthLoginLoopbackHost(parsed.Hostname()) { + return nil, "", apperrors.NewValidation(flagName + " must use HTTPS, except for a loopback HTTP test endpoint") + } parsed.RawQuery = "" parsed.Fragment = "" parsed.Path = strings.TrimRight(parsed.Path, "/") return parsed, strings.TrimRight(parsed.String(), "/"), nil } +func isAuthLoginLoopbackHost(host string) bool { + if strings.EqualFold(strings.TrimSpace(host), "localhost") { + return true + } + ip := net.ParseIP(strings.TrimSpace(host)) + return ip != nil && ip.IsLoopback() +} + func authLoginURLWithHost(parsed *url.URL, host string) string { copyURL := *parsed if port := parsed.Port(); port != "" { diff --git a/internal/app/auth_command_full_coverage_test.go b/internal/app/auth_command_full_coverage_test.go index b572a375..4ba58ac3 100644 --- a/internal/app/auth_command_full_coverage_test.go +++ b/internal/app/auth_command_full_coverage_test.go @@ -7,6 +7,7 @@ import ( "fmt" "io" "os" + "path/filepath" "strings" "testing" "time" @@ -214,7 +215,8 @@ func TestCrossPlatformCoverageAuthCoverageFormsParentAndTargets(t *testing.T) { } func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) { - t.Setenv("DWS_CONFIG_DIR", t.TempDir()) + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) oldSave := authSaveTokenData oldDevice := authDeviceLogin oldOAuth := authOAuthLogin @@ -255,6 +257,15 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) { if out, _, err := authCoverageRunLogin(t, nil, "json", true, map[string]string{"token": "token"}); err != nil || !strings.Contains(out, `"token_valid": true`) { t.Fatalf("json token login = %q, %v", out, err) } + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "pre-url": "https://example.com"}); err == nil { + t.Fatal("invalid pre-release host should fail") + } + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "mcp-url": "http://remote.example.com"}); err == nil { + t.Fatal("remote plaintext MCP URL should fail") + } + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "pre-url": "https://pre-login.dingtalk.io"}); err != nil { + t.Fatalf("pre-release token login = %v", err) + } authDeviceLogin = func(*authpkg.DeviceFlowProvider, context.Context) (*authpkg.TokenData, error) { return nil, errors.New("device") @@ -271,6 +282,15 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) { if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true", "no-browser": "true"}); err != nil { t.Fatal(err) } + authDeviceLogin = func(provider *authpkg.DeviceFlowProvider, _ context.Context) (*authpkg.TokenData, error) { + if provider.LoginRegion != authpkg.LoginRegionInternational { + t.Errorf("device login region = %q, want international", provider.LoginRegion) + } + return &authpkg.TokenData{AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour)}, nil + } + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true", "intl": "true"}); err != nil { + t.Fatalf("international device login = %v", err) + } authOAuthLogin = func(*authpkg.OAuthProvider, context.Context, bool) (*authpkg.TokenData, error) { return nil, errors.New("oauth") @@ -291,6 +311,25 @@ func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) { if out, _, err := authCoverageRunLogin(t, caller, "table", true, map[string]string{"no-browser": "true"}); err != nil || !strings.Contains(out, "Corp") { t.Fatalf("oauth success = %q, %v", out, err) } + authOAuthLogin = func(provider *authpkg.OAuthProvider, _ context.Context, _ bool) (*authpkg.TokenData, error) { + if provider.LoginRegion != authpkg.LoginRegionInternational { + t.Errorf("OAuth login region = %q, want international", provider.LoginRegion) + } + return &authpkg.TokenData{AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour)}, nil + } + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"intl": "true"}); err != nil { + t.Fatalf("international OAuth login = %v", err) + } + + blockedConfigDir := t.TempDir() + if err := os.Mkdir(filepath.Join(blockedConfigDir, "mcp_url"), 0o700); err != nil { + t.Fatal(err) + } + t.Setenv("DWS_CONFIG_DIR", blockedConfigDir) + if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token", "intl": "true"}); err == nil || !strings.Contains(err.Error(), "failed to persist MCP URL") { + t.Fatalf("MCP URL persist failure = %v", err) + } + t.Setenv("DWS_CONFIG_DIR", configDir) authRunLoginRecommend = func(context.Context, edition.ToolCaller, io.Writer, pat.LoginRecommendOptions) error { return errors.New("recommend") diff --git a/internal/app/auth_command_test.go b/internal/app/auth_command_test.go index a1ea7144..e4707218 100644 --- a/internal/app/auth_command_test.go +++ b/internal/app/auth_command_test.go @@ -1065,7 +1065,7 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) { } } -func TestResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { +func TestCrossPlatformCoverageResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { for _, flag := range []string{"intl", "international"} { t.Run(flag, func(t *testing.T) { root := &cobra.Command{Use: "dws"} @@ -1094,9 +1094,61 @@ func TestResolveAuthLoginConfigReadsInternationalAliases(t *testing.T) { } }) } + + for _, tc := range []struct { + name string + setup func(*cobra.Command) + }{ + { + name: "missing intl", + setup: func(cmd *cobra.Command) { + cmd.Flags().String("token", "", "") + cmd.Flags().Bool("device", false, "") + }, + }, + { + name: "missing international", + setup: func(cmd *cobra.Command) { + cmd.Flags().String("token", "", "") + cmd.Flags().Bool("device", false, "") + cmd.Flags().Bool("intl", false, "") + }, + }, + { + name: "missing pre url", + setup: func(cmd *cobra.Command) { + cmd.Flags().String("token", "", "") + cmd.Flags().Bool("device", false, "") + cmd.Flags().Bool("intl", false, "") + cmd.Flags().Bool("international", false, "") + cmd.Flags().Bool("force", false, "") + cmd.Flags().Bool("recommend", false, "") + }, + }, + { + name: "missing mcp url", + setup: func(cmd *cobra.Command) { + cmd.Flags().String("token", "", "") + cmd.Flags().Bool("device", false, "") + cmd.Flags().Bool("intl", false, "") + cmd.Flags().Bool("international", false, "") + cmd.Flags().Bool("force", false, "") + cmd.Flags().Bool("recommend", false, "") + cmd.Flags().String("pre-url", "", "") + }, + }, + } { + t.Run(tc.name, func(t *testing.T) { + cmd := &cobra.Command{Use: "login"} + tc.setup(cmd) + if _, err := resolveAuthLoginConfig(cmd); err == nil { + t.Fatal("resolveAuthLoginConfig succeeded with an incomplete flag set") + } + }) + } } -func TestResolveAuthLoginConfigReadsMCPURL(t *testing.T) { +func TestCrossPlatformCoverageResolveAuthLoginConfigReadsMCPURL(t *testing.T) { root := &cobra.Command{Use: "dws"} root.PersistentFlags().Bool("yes", false, "") login := &cobra.Command{Use: "login"} @@ -1123,7 +1175,7 @@ func TestResolveAuthLoginConfigReadsMCPURL(t *testing.T) { } } -func TestResolveAuthLoginConfigReadsPreURL(t *testing.T) { +func TestCrossPlatformCoverageResolveAuthLoginConfigReadsPreURL(t *testing.T) { root := &cobra.Command{Use: "dws"} root.PersistentFlags().Bool("yes", false, "") login := &cobra.Command{Use: "login"} @@ -1150,7 +1202,7 @@ func TestResolveAuthLoginConfigReadsPreURL(t *testing.T) { } } -func TestAuthLoginEndpointOverridesForPreURL(t *testing.T) { +func TestCrossPlatformCoverageAuthLoginEndpointOverridesForPreURL(t *testing.T) { tests := []struct { name string raw string @@ -1169,6 +1221,12 @@ func TestAuthLoginEndpointOverridesForPreURL(t *testing.T) { wantLogin: "https://pre-login.dingtalk.io", wantMCP: "https://pre-mcp.dingtalk.io", }, + { + name: "pre login with port", + raw: "https://pre-login.dingtalk.io:8443/path/", + wantLogin: "https://pre-login.dingtalk.io:8443/path", + wantMCP: "https://pre-mcp.dingtalk.io:8443/path", + }, } for _, tc := range tests { @@ -1182,9 +1240,15 @@ func TestAuthLoginEndpointOverridesForPreURL(t *testing.T) { } }) } + + for _, raw := range []string{"https://example.com", "http://pre-login.example.com"} { + if _, err := authLoginEndpointOverridesForPreURL(raw); err == nil { + t.Fatalf("authLoginEndpointOverridesForPreURL(%q) succeeded", raw) + } + } } -func TestAuthLoginMCPBaseURLForConfig(t *testing.T) { +func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) { tests := []struct { name string cfg authLoginConfig @@ -1240,9 +1304,18 @@ func TestAuthLoginMCPBaseURLForConfig(t *testing.T) { } }) } + + for _, cfg := range []authLoginConfig{ + {MCPURL: "http://remote.example.com"}, + {PreURL: "https://example.com"}, + } { + if _, _, err := authLoginMCPBaseURLForConfig(cfg, authLoginEndpointOverrides{}); err == nil { + t.Fatalf("authLoginMCPBaseURLForConfig(%#v) succeeded", cfg) + } + } } -func TestPersistAuthLoginMCPBaseURL(t *testing.T) { +func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { t.Run("persists selected io mcp url", func(t *testing.T) { configDir := t.TempDir() if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, true); err != nil { @@ -1257,21 +1330,63 @@ func TestPersistAuthLoginMCPBaseURL(t *testing.T) { } }) - t.Run("center login clears previous persisted override", func(t *testing.T) { + t.Run("center login preserves previous persisted override", func(t *testing.T) { configDir := t.TempDir() mcpURLPath := filepath.Join(configDir, "mcp_url") - if err := os.WriteFile(mcpURLPath, []byte("https://mcp.dingtalk.io"), 0o600); err != nil { + const customURL = "https://custom-mcp.example.com" + if err := os.WriteFile(mcpURLPath, []byte(customURL), 0o600); err != nil { t.Fatalf("WriteFile(mcp_url) error = %v", err) } if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, false); err != nil { t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err) } - if _, err := os.Stat(mcpURLPath); !os.IsNotExist(err) { - t.Fatalf("mcp_url still exists after center login, stat err = %v", err) + data, err := os.ReadFile(mcpURLPath) + if err != nil { + t.Fatalf("ReadFile(mcp_url) error = %v", err) + } + if string(data) != customURL { + t.Fatalf("mcp_url = %q, want preserved override %q", string(data), customURL) } }) } +func TestCrossPlatformCoverageNormalizeAuthLoginBaseURLTransportSecurity(t *testing.T) { + tests := []struct { + name string + raw string + wantURL string + wantErr string + }{ + {name: "https remote", raw: "https://pre-mcp.example.com/path/?secret=drop#fragment", wantURL: "https://pre-mcp.example.com/path"}, + {name: "http localhost", raw: "http://localhost:8080/", wantURL: "http://localhost:8080"}, + {name: "http IPv4 loopback", raw: "http://127.0.0.1:8080", wantURL: "http://127.0.0.1:8080"}, + {name: "http IPv6 loopback", raw: "http://[::1]:8080", wantURL: "http://[::1]:8080"}, + {name: "http remote", raw: "http://pre-mcp.example.com", wantErr: "must use HTTPS"}, + {name: "empty", raw: " ", wantErr: "cannot be empty"}, + {name: "invalid URL", raw: "https://%", wantErr: "invalid --mcp-url"}, + {name: "invalid scheme", raw: "ftp://pre-mcp.example.com", wantErr: "must use http or https"}, + {name: "missing host", raw: "https:///path", wantErr: "must include a host"}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + _, got, err := normalizeAuthLoginBaseURL(tc.raw, "--mcp-url") + if tc.wantErr != "" { + if err == nil || !strings.Contains(err.Error(), tc.wantErr) { + t.Fatalf("normalizeAuthLoginBaseURL error = %v, want containing %q", err, tc.wantErr) + } + return + } + if err != nil { + t.Fatalf("normalizeAuthLoginBaseURL error = %v", err) + } + if got != tc.wantURL { + t.Fatalf("normalized URL = %q, want %q", got, tc.wantURL) + } + }) + } +} + func TestAuthLoginForcesAuthorizationByDefault(t *testing.T) { if !authLoginForcesAuthorization(authLoginConfig{}) { t.Fatal("auth login should force authorization by default so each login can add an organization profile") diff --git a/internal/app/coverage_edges_test.go b/internal/app/coverage_edges_test.go index db7e8f86..9d634365 100644 --- a/internal/app/coverage_edges_test.go +++ b/internal/app/coverage_edges_test.go @@ -326,6 +326,29 @@ func TestCrossPlatformCoverageSmallAppRegistryAndRootCoverage(t *testing.T) { func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) { oldEdition := edition.Get() t.Cleanup(func() { edition.Override(oldEdition); SetDynamicServers(nil) }) + for _, tc := range []struct { + raw string + region authpkg.LoginRegion + want string + }{ + {raw: "%", want: "%"}, + {raw: "https://dingtalk.io/path", want: "https://dingtalk.com/path"}, + {raw: "https://mcp.dingtalk.com:8443/path", region: authpkg.LoginRegionInternational, want: "https://mcp.dingtalk.io:8443/path"}, + } { + if got := mcpBaseURLForLoginRegion(tc.raw, tc.region); got != tc.want { + t.Fatalf("mcpBaseURLForLoginRegion(%q, %q) = %q, want %q", tc.raw, tc.region, got, tc.want) + } + } + if hasDirectRuntimeEndpointOverride("") { + t.Fatal("blank product unexpectedly has an endpoint override") + } + t.Setenv("DINGTALK_COVERAGE_PRODUCT_MCP_URL", "https://override.test") + if !hasDirectRuntimeEndpointOverride("coverage-product") { + t.Fatal("configured product endpoint override was not detected") + } + if got := activeDingTalkGatewayEndpointWithBase("https://mcp-gw.dingtalk.com/server/contact", "%"); got != "https://mcp-gw.dingtalk.com/server/contact" { + t.Fatalf("invalid gateway base rewrote endpoint to %q", got) + } server := mcptypes.ServerDescriptor{ Endpoint: "https://one.test", CLI: mcptypes.CLIOverlay{ @@ -913,12 +936,21 @@ func TestCrossPlatformCoverageAuthCommandPureCoverage(t *testing.T) { } func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) { + t.Setenv(keychain.DisableKeychainEnv, "1") + t.Setenv(keychain.StorageDirEnv, t.TempDir()) oldInteractive := authLoginInteractiveTerminal authLoginInteractiveTerminal = func() bool { return false } t.Cleanup(func() { authLoginInteractiveTerminal = oldInteractive; authpkg.SetRuntimeProfile("") }) - for _, format := range []string{"table", "json"} { - t.Run(format, func(t *testing.T) { - t.Setenv("DWS_CONFIG_DIR", t.TempDir()) + for _, tc := range []struct { + format string + international bool + }{ + {format: "table"}, + {format: "json", international: true}, + } { + t.Run(tc.format, func(t *testing.T) { + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) root := &cobra.Command{Use: "dws"} root.PersistentFlags().String("format", "table", "") root.PersistentFlags().Bool("yes", false, "") @@ -929,13 +961,40 @@ func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) { root.SetOut(&output) root.SetErr(io.Discard) args := []string{"login", "--token", "manual-token", "--yes"} - if format == "json" { + if tc.international { + args = append(args, "--intl") + } + if tc.format == "json" { args = append(args, "--format", "json") } root.SetArgs(args) if err := root.Execute(); err != nil || output.Len() == 0 { t.Fatalf("token login = %q %v", output.String(), err) } + data, err := authpkg.LoadTokenData(configDir) + if err != nil { + t.Fatalf("LoadTokenData error = %v", err) + } + wantRegion := "" + if tc.international { + wantRegion = string(authpkg.LoginRegionInternational) + } + if data.LoginRegion != wantRegion { + t.Fatalf("LoginRegion = %q, want %q", data.LoginRegion, wantRegion) + } + if tc.international { + snapshot, err := resolveAccessTokenSnapshotFromDir(context.Background(), configDir, "") + if err != nil { + t.Fatalf("resolveAccessTokenSnapshotFromDir error = %v", err) + } + gotEndpoint := activeDingTalkGatewayEndpointForLoginRegion( + "https://mcp-gw.dingtalk.com/server/contact", + snapshot.LoginRegion, + ) + if wantEndpoint := "https://mcp-gw.dingtalk.io/server/contact"; gotEndpoint != wantEndpoint { + t.Fatalf("international manual-token endpoint = %q, want %q", gotEndpoint, wantEndpoint) + } + } }) } diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index b5e15e9a..836287a7 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -474,7 +474,7 @@ func TestInjectStaticServersMergesStaticAndSupplementServers(t *testing.T) { } } -func TestStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) { +func TestCrossPlatformCoverageStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) { previous := edition.Get() defer edition.Override(previous) defer SetDynamicServers(nil) @@ -508,7 +508,7 @@ func TestStaticDingTalkEndpointsFollowConfiguredMCPBaseURL(t *testing.T) { } } -func TestDingTalkEndpointsFollowSelectedTokenRegion(t *testing.T) { +func TestCrossPlatformCoverageDingTalkEndpointsFollowSelectedTokenRegion(t *testing.T) { configDir := t.TempDir() t.Setenv("DWS_CONFIG_DIR", configDir) mcpURLPath := filepath.Join(configDir, "mcp_url") @@ -532,7 +532,7 @@ func TestDingTalkEndpointsFollowSelectedTokenRegion(t *testing.T) { } } -func TestDingTalkEndpointUsesLoginScopedMCPOverride(t *testing.T) { +func TestCrossPlatformCoverageDingTalkEndpointUsesLoginScopedMCPOverride(t *testing.T) { configDir := t.TempDir() t.Setenv("DWS_CONFIG_DIR", configDir) restore := authpkg.PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io") diff --git a/internal/app/runner_full_coverage_test.go b/internal/app/runner_full_coverage_test.go index 34e1b0ba..28de556c 100644 --- a/internal/app/runner_full_coverage_test.go +++ b/internal/app/runner_full_coverage_test.go @@ -127,12 +127,14 @@ func TestCrossPlatformCoverageRunnerRemainingRoutingCoverage(t *testing.T) { } func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) { + t.Setenv("DWS_CONFIG_DIR", t.TempDir()) oldEdition := edition.Get() oldPreflight := runnerPreflightDocDownload oldCall := runnerCallTool oldHandle := runnerHandlePatAuthCheck oldRetry := runnerRetryWithPatAuthRetry oldCapture := runnerCaptureRuntimeFailure + oldResolveSnapshot := runnerResolveAuthSnapshot t.Cleanup(func() { edition.Override(oldEdition) runnerPreflightDocDownload = oldPreflight @@ -140,6 +142,7 @@ func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) { runnerHandlePatAuthCheck = oldHandle runnerRetryWithPatAuthRetry = oldRetry runnerCaptureRuntimeFailure = oldCapture + runnerResolveAuthSnapshot = oldResolveSnapshot }) pluginAuthMu.Lock() @@ -168,6 +171,27 @@ func TestCrossPlatformCoverageRunnerRemainingExecutionCoverage(t *testing.T) { if got, err := r.executeInvocation(context.Background(), "https://example.test", inv); err != nil || !got.Invocation.Implemented { t.Fatalf("default auth execution = %#v, %v", got, err) } + runnerResolveAuthSnapshot = func(*runtimeRunner, context.Context) (AccessTokenSnapshot, error) { + return AccessTokenSnapshot{ + AccessToken: "international-token", + LoginRegion: authpkg.LoginRegionInternational, + LoginRegionKnown: true, + }, nil + } + successfulCall := runnerCallTool + routedEndpoint := "" + runnerCallTool = func(_ *transport.Client, _ context.Context, endpoint, _ string, _ map[string]any) (transport.ToolCallResult, error) { + routedEndpoint = endpoint + return transport.ToolCallResult{Content: map[string]any{"value": 1}}, nil + } + if _, err := r.executeInvocation(context.Background(), "https://mcp-gw.dingtalk.com/server/contact", inv); err != nil { + t.Fatalf("international auth execution = %v", err) + } + if routedEndpoint != "https://mcp-gw.dingtalk.io/server/contact" { + t.Fatalf("international routed endpoint = %q", routedEndpoint) + } + runnerResolveAuthSnapshot = oldResolveSnapshot + runnerCallTool = successfulCall wantErr := errors.New("preflight") runnerPreflightDocDownload = func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error { @@ -362,6 +386,12 @@ func TestCrossPlatformCoverageRunnerRemainingStdioAuthAndHeadersCoverage(t *test if got, err := resolveRuntimeAuthToken(context.Background(), " runtime "); err != nil || got != "runtime" { t.Fatalf("runtime explicit token = %q, %v", got, err) } + edition.Override(&edition.Hooks{TokenProvider: func(context.Context, func() (string, error)) (string, error) { + return "", errors.New("snapshot failed") + }}) + if _, err := r.resolveAuthToken(context.Background()); err == nil || !strings.Contains(err.Error(), "snapshot failed") { + t.Fatalf("resolveAuthToken error = %v", err) + } t.Setenv(envDWSChannel, "channel") edition.Override(&edition.Hooks{ diff --git a/internal/auth/auth_extra_test.go b/internal/auth/auth_extra_test.go index ccfb68a5..bc4909bd 100644 --- a/internal/auth/auth_extra_test.go +++ b/internal/auth/auth_extra_test.go @@ -424,14 +424,14 @@ func TestBuildAuthURLIncludesTargetCorpID(t *testing.T) { } } -func TestBuildAuthURLForInternationalRegion(t *testing.T) { +func TestCrossPlatformCoverageBuildAuthURLForInternationalRegion(t *testing.T) { authURL := buildAuthURLForRegion("client-id", "http://127.0.0.1:1234/callback", "", LoginRegionInternational) if !strings.HasPrefix(authURL, InternationalAuthorizeURL+"?") { t.Fatalf("auth URL = %s, want international authorize host", authURL) } } -func TestNotEnabledHTMLUsesRegionAwareAuthorizeURL(t *testing.T) { +func TestCrossPlatformCoverageNotEnabledHTMLUsesRegionAwareAuthorizeURL(t *testing.T) { if !strings.Contains(notEnabledHTML, "status.authorizeUrl") { t.Fatal("not-enabled page must read the authorize URL from the regional login status") } @@ -440,10 +440,13 @@ func TestNotEnabledHTMLUsesRegionAwareAuthorizeURL(t *testing.T) { } } -func TestLoginRegionEndpointDefaults(t *testing.T) { +func TestCrossPlatformCoverageLoginRegionEndpointDefaults(t *testing.T) { if got := AuthorizeURLForLoginRegion(LoginRegionDefault); got != AuthorizeURL { t.Fatalf("default authorize URL = %q, want %q", got, AuthorizeURL) } + if got := DeviceBaseURLForLoginRegion(LoginRegionDefault); got != DefaultDeviceBaseURL { + t.Fatalf("default device base URL = %q, want %q", got, DefaultDeviceBaseURL) + } if got := UserAccessTokenURLForLoginRegion(LoginRegionInternational); got != InternationalUserAccessTokenURL { t.Fatalf("international user access token URL = %q, want %q", got, InternationalUserAccessTokenURL) } @@ -455,7 +458,30 @@ func TestLoginRegionEndpointDefaults(t *testing.T) { } } -func TestMCPBaseURLOverrideAffectsInternationalRegion(t *testing.T) { +func TestCrossPlatformCoverageOAuthProviderLoginRegionHelpers(t *testing.T) { + var nilProvider *OAuthProvider + if got := nilProvider.loginRegion(); got != LoginRegionDefault { + t.Fatalf("nil provider login region = %q", got) + } + nilProvider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionInternational)}) + nilProvider.applyLoginRegionToToken(&TokenData{}) + + provider := &OAuthProvider{} + provider.useTokenLoginRegion(nil) + provider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionInternational)}) + if provider.LoginRegion != LoginRegionInternational { + t.Fatalf("provider login region = %q, want international", provider.LoginRegion) + } + provider.useTokenLoginRegion(&TokenData{LoginRegion: string(LoginRegionDefault)}) + provider.applyLoginRegionToToken(nil) + token := &TokenData{} + provider.applyLoginRegionToToken(token) + if token.LoginRegion != string(LoginRegionInternational) { + t.Fatalf("token login region = %q, want international", token.LoginRegion) + } +} + +func TestCrossPlatformCoverageMCPBaseURLOverrideAffectsInternationalRegion(t *testing.T) { restore := PushMCPBaseURLOverride("https://pre-mcp.dingtalk.io/") defer restore() @@ -464,7 +490,7 @@ func TestMCPBaseURLOverrideAffectsInternationalRegion(t *testing.T) { } } -func TestLoginBaseURLOverrideAffectsInternationalRegion(t *testing.T) { +func TestCrossPlatformCoverageLoginBaseURLOverrideAffectsInternationalRegion(t *testing.T) { restore := PushLoginBaseURLOverride("https://pre-login.dingtalk.io/") defer restore() @@ -474,6 +500,9 @@ func TestLoginBaseURLOverrideAffectsInternationalRegion(t *testing.T) { if got := AuthorizeURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io/oauth2/auth" { t.Fatalf("international authorize URL = %q, want override", got) } + if got := UserAccessTokenURLForLoginRegion(LoginRegionInternational); got != "https://pre-login.dingtalk.io/v1.0/oauth2/userAccessToken" { + t.Fatalf("international user access token URL = %q, want override", got) + } } func buildTokenDataFromResponse(resp tokenResponse) *TokenData { diff --git a/internal/auth/cli_auth_check_test.go b/internal/auth/cli_auth_check_test.go index 7fb10fba..802035ea 100644 --- a/internal/auth/cli_auth_check_test.go +++ b/internal/auth/cli_auth_check_test.go @@ -208,8 +208,10 @@ func TestCheckCLIAuthEnabled_Enabled(t *testing.T) { t.Logf("✅ Normal enabled response: success=%v, enabled=%v", status.Success, status.Result.CLIAuthEnabled) } -func TestCheckCLIAuthEnabled_TraceHeadersAndDebugLog(t *testing.T) { +func TestCrossPlatformCoverageCheckCLIAuthEnabledTraceHeadersAndDebugLog(t *testing.T) { t.Setenv("DINGTALK_TRACE_ID", "trace-for-cli-auth-test") + applyCLIAuthTraceHeaders(nil, "trace-for-cli-auth-test") + applyCLIAuthTraceHeaders(httptest.NewRequest(http.MethodGet, "https://example.com", nil), "") var logBuf bytes.Buffer previousLogger := slog.Default() @@ -261,6 +263,50 @@ func TestCheckCLIAuthEnabled_TraceHeadersAndDebugLog(t *testing.T) { } } +func TestCrossPlatformCoverageInternationalLoginRegionRequestWrappers(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case ClientIDPath: + _ = json.NewEncoder(w).Encode(ClientIDResponse{Success: true, Result: "international-client"}) + case SuperAdminPath: + _ = json.NewEncoder(w).Encode(SuperAdminResponse{Success: true, Result: []SuperAdmin{{StaffID: "admin"}}}) + case SendCliAuthApplyPath: + _ = json.NewEncoder(w).Encode(SendApplyResponse{Success: true, Result: true}) + default: + http.NotFound(w, r) + } + })) + defer server.Close() + + oldClient := oauthHTTPClient + oauthHTTPClient = server.Client() + restoreBaseURL := PushMCPBaseURLOverride(server.URL) + t.Cleanup(func() { + restoreBaseURL() + oauthHTTPClient = oldClient + }) + + ctx := context.Background() + for name, fetch := range map[string]func() (string, error){ + "device": func() (string, error) { return deviceFetchClientIDForLoginRegion(ctx, LoginRegionInternational) }, + "oauth": func() (string, error) { return oauthFetchClientIDForLoginRegion(ctx, LoginRegionInternational) }, + } { + if got, err := fetch(); err != nil || got != "international-client" { + t.Fatalf("%s client ID = %q, %v", name, got, err) + } + } + if got, err := deviceGetAdminsForLoginRegion(ctx, "token", LoginRegionInternational); err != nil || !got.Success { + t.Fatalf("device admins = %#v, %v", got, err) + } + if got, err := oauthGetAdminsForLoginRegion(ctx, "token", LoginRegionInternational); err != nil || !got.Success { + t.Fatalf("OAuth admins = %#v, %v", got, err) + } + if got, err := oauthSendApplyForLoginRegion(ctx, "token", "admin", LoginRegionInternational); err != nil || !got.Success { + t.Fatalf("OAuth apply = %#v, %v", got, err) + } +} + func TestCheckCLIAuthEnabled_Disabled(t *testing.T) { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") diff --git a/internal/auth/device_flow_test.go b/internal/auth/device_flow_test.go index 72d64c31..df517041 100644 --- a/internal/auth/device_flow_test.go +++ b/internal/auth/device_flow_test.go @@ -90,7 +90,7 @@ func TestRequestDeviceCodeSuccess(t *testing.T) { } } -func TestDeviceFlowSetLoginRegionUsesInternationalBaseURL(t *testing.T) { +func TestCrossPlatformCoverageDeviceFlowSetLoginRegionUsesInternationalBaseURL(t *testing.T) { provider := NewDeviceFlowProvider(t.TempDir(), newDeviceFlowTestLogger()) provider.SetLoginRegion(LoginRegionInternational) if provider.baseURL != InternationalDeviceBaseURL { diff --git a/internal/auth/endpoints.go b/internal/auth/endpoints.go index 54878664..31a204cc 100644 --- a/internal/auth/endpoints.go +++ b/internal/auth/endpoints.go @@ -166,6 +166,9 @@ func MCPBaseURLForLoginRegion(region LoginRegion) string { } func UserAccessTokenURLForLoginRegion(region LoginRegion) string { + if override := LoginBaseURLOverride(); override != "" { + return override + "/v1.0/oauth2/userAccessToken" + } if region.IsInternational() { return InternationalUserAccessTokenURL } diff --git a/internal/errors/errors_test.go b/internal/errors/errors_test.go index a2a7d11c..60918b1b 100644 --- a/internal/errors/errors_test.go +++ b/internal/errors/errors_test.go @@ -386,7 +386,7 @@ func TestCrossPlatformCoverageServerGuidanceSuppressesUnsafeActionURL(t *testing } } -func TestPrintJSONCLIOrgNotAuthorizedUsesInternationalActionURL(t *testing.T) { +func TestCrossPlatformCoveragePrintJSONCLIOrgNotAuthorizedUsesInternationalActionURL(t *testing.T) { dir := t.TempDir() t.Setenv("DWS_CONFIG_DIR", dir) if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), config.FilePerm); err != nil { diff --git a/internal/transport/client_extra_test.go b/internal/transport/client_extra_test.go index fc0da902..782e0006 100644 --- a/internal/transport/client_extra_test.go +++ b/internal/transport/client_extra_test.go @@ -6,6 +6,7 @@ import ( "io" "log/slog" "net/http" + "net/url" "strings" "testing" ) @@ -234,7 +235,7 @@ func TestIsEndpointTrusted_DomainMatch(t *testing.T) { } } -func TestIsEndpointTrusted_DefaultIncludesDingTalkInternational(t *testing.T) { +func TestCrossPlatformCoverageIsEndpointTrustedDefaultIncludesDingTalkInternational(t *testing.T) { t.Setenv("DWS_ALLOW_HTTP_ENDPOINTS", "") t.Setenv("DWS_TRUSTED_DOMAINS", "") c := NewClient(nil) @@ -244,6 +245,11 @@ func TestIsEndpointTrusted_DefaultIncludesDingTalkInternational(t *testing.T) { if !c.isEndpointTrusted("https://pre-mcp-gw.dingtalk.io/server/contact") { t.Fatal("default trusted domains should trust dingtalk.io") } + for _, host := range []string{"mcp-gw.dingtalk.io", "pre-mcp-gw.dingtalk.io"} { + if !shouldPreserveEndpointQuery(&url.URL{Scheme: "https", Host: host}) { + t.Fatalf("international gateway %q should preserve endpoint query", host) + } + } } func TestHttpStatusError(t *testing.T) { diff --git a/pkg/config/constants_test.go b/pkg/config/constants_test.go index 2c72b065..7296b231 100644 --- a/pkg/config/constants_test.go +++ b/pkg/config/constants_test.go @@ -219,7 +219,7 @@ func TestGetMCPBaseURLUsesConfigFile(t *testing.T) { } } -func TestGetDeveloperSettingsURLUsesInternationalMCPRegion(t *testing.T) { +func TestCrossPlatformCoverageGetDeveloperSettingsURLUsesInternationalMCPRegion(t *testing.T) { dir := t.TempDir() t.Setenv("DWS_CONFIG_DIR", dir) if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), FilePerm); err != nil { @@ -232,7 +232,7 @@ func TestGetDeveloperSettingsURLUsesInternationalMCPRegion(t *testing.T) { } } -func TestGetTerminalBaseURLPrefersExplicitConfig(t *testing.T) { +func TestCrossPlatformCoverageGetTerminalBaseURLPrefersExplicitConfig(t *testing.T) { dir := t.TempDir() t.Setenv("DWS_CONFIG_DIR", dir) if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://mcp.dingtalk.io\n"), FilePerm); err != nil { From 973671bdf18d8b8b4bba82906e165e872d66efb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=B7=E5=BF=83=E8=8F=9C?= Date: Thu, 13 Aug 2026 18:36:38 +0800 Subject: [PATCH 076/250] chore: trigger auto CR re-review From 78d94380e790bf435c788668c6c0644c6d3ab210 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 18:54:00 +0800 Subject: [PATCH 077/250] docs(changes): note chat im id flag migration --- .changes/954-chat-im-id-flags.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changes/954-chat-im-id-flags.md diff --git a/.changes/954-chat-im-id-flags.md b/.changes/954-chat-im-id-flags.md new file mode 100644 index 00000000..82012fc3 --- /dev/null +++ b/.changes/954-chat-im-id-flags.md @@ -0,0 +1,5 @@ +--- +category: Changed +--- + +- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` and `--message-id` while keeping legacy flags as compatibility aliases where applicable. From 5cbf18713ab0f69aa4e13dec5adc618a384abd66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 18:57:44 +0800 Subject: [PATCH 078/250] docs(changes): expand chat im flag migration note --- .changes/954-chat-im-id-flags.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.changes/954-chat-im-id-flags.md b/.changes/954-chat-im-id-flags.md index 82012fc3..a64f4369 100644 --- a/.changes/954-chat-im-id-flags.md +++ b/.changes/954-chat-im-id-flags.md @@ -2,4 +2,6 @@ category: Changed --- -- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` and `--message-id` while keeping legacy flags as compatibility aliases where applicable. +- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` for conversation IDs and `--message-id` for message IDs, so help, Schema, and Agent recommendations use the same canonical flags. +- **Legacy chat flag compatibility** (#954) — keeps older chat IM ID flags such as `--group`, `--id`, `--chat`, `--open-conversation-id`, `--msg-id`, and `--open-message-id` working as compatibility aliases where applicable, while hiding migrated aliases from recommended help and Schema surfaces. +- **Chat group name flags** (#954) — moves chat commands that accept a group name to the explicit `--group-name` flag, removing the public `--group` ambiguity between group names and conversation IDs on migrated command surfaces. From 14a21754348fc58a417a38e3f9f83bf0c75843b4 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 19:04:57 +0800 Subject: [PATCH 079/250] fix(ci): preserve delivered stable compatibility baseline --- .github/workflows/release.yml | 34 ++++++++ test/scripts/package_script_test.go | 130 ++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 08e83fd8..8ee47b14 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2645,6 +2645,40 @@ jobs: "$GITHUB_WORKSPACE/tmp/trusted-release-tooling/scripts/release/verify-github-tag-authority.sh" \ "$RELEASE_VERSION" "$RELEASE_COMMIT" "$RELEASE_TAG_OBJECT" + # The sealed candidate tag is intentionally visible while its GitHub + # authority is checked above. Compatibility must instead discover the + # previous delivered stable tag, so hide only this verified candidate + # from this isolated runner's local tag namespace. + - name: Prepare delivered-stable compatibility ref view + if: ${{ matrix.check == 'compatibility' }} + env: + RELEASE_VERSION: ${{ needs.release-contract.outputs.release_version }} + RELEASE_COMMIT: ${{ needs.release-contract.outputs.release_commit }} + RELEASE_TAG_OBJECT: ${{ needs.release-contract.outputs.release_tag_object }} + PREVIOUS_STABLE: ${{ needs.release-contract.outputs.previous_stable }} + PREVIOUS_STABLE_COMMIT: ${{ needs.release-contract.outputs.previous_stable_commit }} + run: | + set -eu + test -n "$RELEASE_VERSION" + test -n "$RELEASE_COMMIT" + test -n "$RELEASE_TAG_OBJECT" + test -n "$PREVIOUS_STABLE" + test -n "$PREVIOUS_STABLE_COMMIT" + test "$RELEASE_VERSION" != "$PREVIOUS_STABLE" + test "$(git rev-parse HEAD)" = "$RELEASE_COMMIT" + test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}")" = "$RELEASE_TAG_OBJECT" + test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}^{commit}")" = "$RELEASE_COMMIT" + test "$(git rev-parse --verify "${PREVIOUS_STABLE}^{commit}")" = "$PREVIOUS_STABLE_COMMIT" + + git update-ref -d "refs/tags/${RELEASE_VERSION}" "$RELEASE_TAG_OBJECT" + + if git show-ref --verify --quiet "refs/tags/${RELEASE_VERSION}"; then + echo "sealed candidate tag is still visible to compatibility baseline discovery" >&2 + exit 2 + fi + test "$(git rev-parse HEAD)" = "$RELEASE_COMMIT" + test "$(git rev-parse --verify "${PREVIOUS_STABLE}^{commit}")" = "$PREVIOUS_STABLE_COMMIT" + - name: Set up Go uses: actions/setup-go@v5 with: diff --git a/test/scripts/package_script_test.go b/test/scripts/package_script_test.go index 62b51c6c..fd3746ba 100644 --- a/test/scripts/package_script_test.go +++ b/test/scripts/package_script_test.go @@ -1222,6 +1222,136 @@ func TestReleaseWorkflowParallelizesSealedValidationWithoutWeakeningPublication( } } +func TestReleaseWorkflowHidesOnlyVerifiedSealedTagFromCompatibilityBaseline(t *testing.T) { + t.Parallel() + workflow := readReleaseWorkflow(t) + validation := releaseWorkflowSection(t, workflow, " release-validation:\n", "\n release-plan:\n") + preparedView := releaseWorkflowSection( + t, + validation, + " - name: Prepare delivered-stable compatibility ref view\n", + "\n - name: Set up Go\n", + ) + script := releaseWorkflowRunScript( + t, + validation, + "Prepare delivered-stable compatibility ref view", + "Set up Go", + ) + + if !strings.Contains(preparedView, "if: ${{ matrix.check == 'compatibility' }}") { + t.Fatal("delivered-stable ref view must run only for the compatibility matrix leg") + } + for _, required := range []string{ + "RELEASE_VERSION: ${{ needs.release-contract.outputs.release_version }}", + "RELEASE_COMMIT: ${{ needs.release-contract.outputs.release_commit }}", + "RELEASE_TAG_OBJECT: ${{ needs.release-contract.outputs.release_tag_object }}", + "PREVIOUS_STABLE: ${{ needs.release-contract.outputs.previous_stable }}", + "PREVIOUS_STABLE_COMMIT: ${{ needs.release-contract.outputs.previous_stable_commit }}", + } { + if !strings.Contains(preparedView, required) { + t.Errorf("delivered-stable compatibility view is missing %q", required) + } + } + for _, required := range []string{ + `test "$RELEASE_VERSION" != "$PREVIOUS_STABLE"`, + `test "$(git rev-parse HEAD)" = "$RELEASE_COMMIT"`, + `test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}")" = "$RELEASE_TAG_OBJECT"`, + `test "$(git rev-parse --verify "refs/tags/${RELEASE_VERSION}^{commit}")" = "$RELEASE_COMMIT"`, + `test "$(git rev-parse --verify "${PREVIOUS_STABLE}^{commit}")" = "$PREVIOUS_STABLE_COMMIT"`, + `git update-ref -d "refs/tags/${RELEASE_VERSION}" "$RELEASE_TAG_OBJECT"`, + `git show-ref --verify --quiet "refs/tags/${RELEASE_VERSION}"`, + } { + if !strings.Contains(script, required) { + t.Errorf("delivered-stable compatibility view is missing %q", required) + } + } + + verifiedTag := strings.Index(validation, "verify-github-tag-authority.sh") + deleteLocalTag := strings.Index(validation, "git update-ref -d") + compatibility := strings.Index(validation, "check-command-compatibility.sh") + if verifiedTag == -1 || deleteLocalTag == -1 || compatibility == -1 || + verifiedTag > deleteLocalTag || deleteLocalTag > compatibility { + t.Fatal("release tag authority verification, local candidate removal, and compatibility checking must stay ordered") + } + for _, forbidden := range []string{"git push --delete", "github.rest.git.deleteRef"} { + if strings.Contains(workflow, forbidden) { + t.Errorf("release workflow must not delete a remote ref: found %q", forbidden) + } + } + + repo, err := os.MkdirTemp(".", ".release-compatibility-test-") + if err != nil { + t.Fatalf("MkdirTemp(release compatibility test repository) error = %v", err) + } + t.Cleanup(func() { + if err := os.RemoveAll(repo); err != nil { + t.Errorf("RemoveAll(%s) error = %v", repo, err) + } + }) + mustRun(t, repo, "git", "init", "-b", "main") + mustRun(t, repo, "git", "config", "user.name", "Release Compatibility Test") + mustRun(t, repo, "git", "config", "user.email", "release-compatibility@example.com") + mustWriteFile(t, filepath.Join(repo, "tracked"), []byte("stable\n"), 0o644) + mustRun(t, repo, "git", "add", "tracked") + mustRun(t, repo, "git", "commit", "-m", "stable release") + previousStableCommit := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "HEAD")) + mustRun(t, repo, "git", "tag", "-a", "v1.0.57", "-m", "v1.0.57") + mustWriteFile(t, filepath.Join(repo, "tracked"), []byte("sealed\n"), 0o644) + mustRun(t, repo, "git", "commit", "-am", "sealed release") + releaseCommit := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "HEAD")) + mustRun(t, repo, "git", "tag", "-a", "v1.0.58", "-m", "v1.0.58") + releaseTagObject := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "refs/tags/v1.0.58")) + + run := func(tagObject string) ([]byte, error) { + cmd := exec.Command("sh", "-c", script) + cmd.Dir = repo + cmd.Env = make([]string, 0, len(os.Environ())+5) + for _, entry := range os.Environ() { + if strings.HasPrefix(entry, "RELEASE_VERSION=") || + strings.HasPrefix(entry, "RELEASE_COMMIT=") || + strings.HasPrefix(entry, "RELEASE_TAG_OBJECT=") || + strings.HasPrefix(entry, "PREVIOUS_STABLE=") || + strings.HasPrefix(entry, "PREVIOUS_STABLE_COMMIT=") { + continue + } + cmd.Env = append(cmd.Env, entry) + } + cmd.Env = append(cmd.Env, + "RELEASE_VERSION=v1.0.58", + "RELEASE_COMMIT="+releaseCommit, + "RELEASE_TAG_OBJECT="+tagObject, + "PREVIOUS_STABLE=v1.0.57", + "PREVIOUS_STABLE_COMMIT="+previousStableCommit, + ) + return cmd.CombinedOutput() + } + + if output, err := run(releaseTagObject); err != nil { + t.Fatalf("prepared compatibility ref view failed: %v\noutput:\n%s", err, output) + } + candidateTag := exec.Command("git", "rev-parse", "--verify", "refs/tags/v1.0.58") + candidateTag.Dir = repo + if _, err := candidateTag.CombinedOutput(); err == nil { + t.Fatal("prepared compatibility ref view left the sealed candidate tag visible") + } + mustRun(t, repo, "git", "cat-file", "-e", releaseTagObject+"^{tag}") + if got := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "refs/tags/v1.0.57^{commit}")); got != previousStableCommit { + t.Fatalf("previous stable tag commit = %s, want %s", got, previousStableCommit) + } + if got := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "HEAD")); got != releaseCommit { + t.Fatalf("HEAD after prepared compatibility ref view = %s, want %s", got, releaseCommit) + } + + mustRun(t, repo, "git", "update-ref", "refs/tags/v1.0.58", releaseTagObject) + if output, err := run(strings.Repeat("0", 40)); err == nil { + t.Fatalf("prepared compatibility ref view unexpectedly accepted a mismatched tag object\noutput:\n%s", output) + } + if got := strings.TrimSpace(mustOutput(t, repo, "git", "rev-parse", "refs/tags/v1.0.58")); got != releaseTagObject { + t.Fatalf("mismatched tag object removed or changed the local sealed tag: got %s, want %s", got, releaseTagObject) + } +} + func TestReleaseFingerprintRefPatternsMatchAllAllocatedTags(t *testing.T) { t.Parallel() repo := t.TempDir() From 91090a13b9a0adff8fbf419ad1141bb54ed37e99 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 11:51:41 +0000 Subject: [PATCH 080/250] chore: update formula for v1.0.58 [skip ci] --- Formula/dingtalk-workspace-cli.rb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Formula/dingtalk-workspace-cli.rb b/Formula/dingtalk-workspace-cli.rb index fffbf6c0..46d064f7 100644 --- a/Formula/dingtalk-workspace-cli.rb +++ b/Formula/dingtalk-workspace-cli.rb @@ -1,33 +1,33 @@ class DingtalkWorkspaceCli < Formula desc "Automate DingTalk workspace tasks from the terminal" homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli" - version "1.0.57" + version "1.0.58" license "Apache-2.0" on_macos do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-arm64.tar.gz" - sha256 "c01c28dc13948a70fca905207073dc8dbd22f7ba7fc90e68b3316eb9a9c98e88" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-darwin-arm64.tar.gz" + sha256 "7d98599f90cae9d42b51ff2863efc87dbfb4a3176ff3c84fc2216110c0157a70" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-darwin-amd64.tar.gz" - sha256 "d7baa218beefc851c6a933b456055195f8272984ce008d7e0122bdfc5dad94ea" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-darwin-amd64.tar.gz" + sha256 "4c12e35e5bf7e0905812cd42dc94a5345068a2c16e306bb50b13c5c78b5cb95d" end end on_linux do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-arm64.tar.gz" - sha256 "0bbe9c233a3ff585077bae1ac5000937c32d967846d14cc44c46f98d49b95ae2" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-linux-arm64.tar.gz" + sha256 "5ef6bde24bc3db6a11a0f1d0b3343a048956b2cbcf6cd3409a037fb6ba425489" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-linux-amd64.tar.gz" - sha256 "f113ce3654f21d1f9ecc7c196f815aeafbca54d377a347b244a15116c5cba698" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-linux-amd64.tar.gz" + sha256 "3ccadcc6f070a39d2b2ba20429a4fcdc2f21639bf79f34361dc7d16f501bfda6" end end resource "skills" do - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-skills.zip" - sha256 "0c9667209cf30761427a8f9348149cbbf1e397aa3c25587e99f205bc7525e101" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58/dws-skills.zip" + sha256 "2626debc21c3daadfd155b4c167b2219b97e801398fe4441a8b48138960ab264" end def install From 504db23823695bcf0d7ac6df36776144bae70f19 Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 20:55:06 +0800 Subject: [PATCH 081/250] test(drive): cover platform-only branches missed by the platform coverage gate The platform coverage gate runs only TestAllShortcuts and TestCrossPlatformCoverage*, so several changed statements had no platform test exercising them: - drive_pull.go: the smart-policy re-check that skips publication when the target is refreshed in place (same inode) while the download is running. - drive_pull.go: the post-publish verifyParent failure, where the result is already on disk and must not be rolled back. - drive_replace_unix.go: rename(2) replacement of an existing target; the Windows side already had the symmetric test. - drive_status_windows.go: the filepath.Clean rewrite guard had no input reaching it, because isSafeRemoteSegment filters separators upstream. macOS changed-code coverage: 99.8053% -> 100.0000% (1541 statements). --- .../drive_pull_publish_recheck_test.go | 91 +++++++++++++++++++ internal/helpers/drive_replace_unix_test.go | 34 +++++++ internal/helpers/drive_sync_platform_test.go | 3 + 3 files changed, 128 insertions(+) create mode 100644 internal/helpers/drive_pull_publish_recheck_test.go create mode 100644 internal/helpers/drive_replace_unix_test.go diff --git a/internal/helpers/drive_pull_publish_recheck_test.go b/internal/helpers/drive_pull_publish_recheck_test.go new file mode 100644 index 00000000..ce00ff03 --- /dev/null +++ b/internal/helpers/drive_pull_publish_recheck_test.go @@ -0,0 +1,91 @@ +package helpers + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +// smart 策略在入口按固定的 initialInfo 判定「本地落后、需要下载」，但远端读与落盘 +// 期间同一 inode 的 mtime 仍可能被并发写者推到 ≥ 远端时间。此时发布会用旧的远端版本 +// 覆盖更新的本地内容，因此必须在发布前按当前状态二次判定并跳过。 +func TestCrossPlatformCoverageDrivePullSmartSkipsWhenTargetCatchesUpDuringDownload(t *testing.T) { + root := t.TempDir() + target := filepath.Join(root, "a.txt") + const remoteMillis int64 = 2_000_000 + if err := os.WriteFile(target, []byte("local"), 0o600); err != nil { + t.Fatal(err) + } + // 入口处的 mtime 必须严格早于远端，否则在发出远端读之前就已跳过。 + stale := time.UnixMilli(remoteMillis - 60_000) + if err := os.Chtimes(target, stale, stale); err != nil { + t.Fatal(err) + } + installPinnedPullSuccess(t) + testseam.Swap(t, &pullDownloadFile, func(_ context.Context, _ string, _ map[string]string, destination *os.File) error { + if _, err := destination.WriteString("remote"); err != nil { + return err + } + // 就地改时间：inode 不变，所以身份比较仍然成立，只有时间判定能拦下发布。 + fresh := time.UnixMilli(remoteMillis + 60_000) + return os.Chtimes(target, fresh, fresh) + }) + + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{ + FileID: "F", + ModifiedTime: remoteMillis, + ModifiedTimeValid: true, + }, root, "a.txt", ifExistsSmart) + if err != nil { + t.Fatalf("pull = %v", err) + } + if action != pullActionSkipped { + t.Fatalf("action = %q, want %q", action, pullActionSkipped) + } + if got, err := os.ReadFile(target); err != nil || string(got) != "local" { + t.Fatalf("target = %q, err=%v; 追平后的本地内容必须保留", got, err) + } +} + +// 发布成功后固定目录仍可能被移走。此时结果已经落盘，门禁只能报失败而不能回删—— +// 同名 terminal entry 可能已被并发替换，二次 Lstat→Remove 会误删他人的文件。 +func TestCrossPlatformCoverageDrivePullFailsWhenPinnedRootMovesAfterPublish(t *testing.T) { + root := t.TempDir() + installPinnedPullSuccess(t) + decoy := t.TempDir() + decoyInfo, err := os.Stat(decoy) + if err != nil { + t.Fatal(err) + } + published := false + testseam.Swap(t, &pullRename, func(parent *os.Root, oldName, newName string) error { + if err := parent.Rename(oldName, newName); err != nil { + return err + } + published = true + return nil + }) + // 只在发布之后让根目录身份不匹配：下载前与发布前的两次核对都必须先通过。 + testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) { + if published { + return decoyInfo, nil + } + return os.Stat(path) + }) + + action, err := pullOneFileAtRoot(context.Background(), "", &remoteFile{FileID: "F"}, root, "a.txt", ifExistsOverwrite) + if err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") { + t.Fatalf("error = %v", err) + } + if action != pullActionFailed { + t.Fatalf("action = %q, want %q", action, pullActionFailed) + } + if got, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(got) != "remote" { + t.Fatalf("published target = %q, err=%v; 已发布的结果不得被回删", got, err) + } +} diff --git a/internal/helpers/drive_replace_unix_test.go b/internal/helpers/drive_replace_unix_test.go new file mode 100644 index 00000000..70a5b94e --- /dev/null +++ b/internal/helpers/drive_replace_unix_test.go @@ -0,0 +1,34 @@ +//go:build !windows + +package helpers + +import ( + "os" + "path/filepath" + "testing" +) + +// Unix 的 rename(2) 原生提供原子替换语义；该路径与 Windows 的 +// MOVEFILE_REPLACE_EXISTING 同样服务 pull overwrite、sync remote-wins 与 +// keep-both 的占位文件替换，因此两侧都需要平台覆盖。 +func TestCrossPlatformCoverageDriveReplaceFileUnix_replacesExistingTarget(t *testing.T) { + dir := t.TempDir() + source := filepath.Join(dir, "source.tmp") + target := filepath.Join(dir, "target.txt") + if err := os.WriteFile(source, []byte("new"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(target, []byte("old"), 0o600); err != nil { + t.Fatal(err) + } + + if err := driveReplaceFile(source, target); err != nil { + t.Fatalf("replace existing target: %v", err) + } + if got, err := os.ReadFile(target); err != nil || string(got) != "new" { + t.Fatalf("target = %q, err=%v; want new content", got, err) + } + if _, err := os.Stat(source); !os.IsNotExist(err) { + t.Fatalf("source must be moved, stat err=%v", err) + } +} diff --git a/internal/helpers/drive_sync_platform_test.go b/internal/helpers/drive_sync_platform_test.go index d7f19fb3..2fa85b72 100644 --- a/internal/helpers/drive_sync_platform_test.go +++ b/internal/helpers/drive_sync_platform_test.go @@ -108,6 +108,9 @@ func TestCrossPlatformCoverageIsSafeRemoteSegmentPlatform_rejectsNonCanonicalWin for _, name := range []string{ `C:relative`, `a?.txt`, `a*.txt`, `a:stream`, `a<.txt`, `a>.txt`, `a|.txt`, `a".txt`, "name.", "name ", "...", "CON", "con.txt", "PRN", "AUX", "NUL", "COM1", "LPT9", "COM¹", "CONIN$", + // 调用方 isSafeRemoteSegment 已先过滤分隔符，所以只有直接调用才会走到 + // filepath.Clean 改写这条防御分支；平台函数本身仍必须 fail closed。 + `a/b`, `.\a`, } { if isSafeRemoteSegmentPlatform(name) { t.Errorf("Windows unsafe segment %q must be rejected", name) From 3598586bc0a02e6143c13ee1e23eef33dcfe22cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 20:56:43 +0800 Subject: [PATCH 082/250] fix(cli): block plural id flag normalization --- internal/cli/param_aliases.go | 21 ++- internal/cli/param_aliases_generated.go | 212 ++++++++++++------------ internal/cli/param_aliases_test.go | 53 ++++++ 3 files changed, 171 insertions(+), 115 deletions(-) diff --git a/internal/cli/param_aliases.go b/internal/cli/param_aliases.go index 930a3762..1e35e95c 100644 --- a/internal/cli/param_aliases.go +++ b/internal/cli/param_aliases.go @@ -177,6 +177,7 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc aliasMap := make(map[string]string) blockedSet := make(map[string]bool) excludedSet := make(map[string]bool) + claimedRealSet := make(map[string]bool) pendingReview := ov.Confirm || ov.Investigate for boundFlag, conceptID := range ov.Bind { @@ -218,6 +219,14 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc if len(candidates) == 0 { continue } + for m := range eff { + if _, isReal := realByMorph[m]; isReal { + claimedRealSet[m] = true + } + } + for _, exclude := range concept.Excludes { + excludedSet[cmdutil.Morph(exclude)] = true + } visible := distinctRealNames(candidates, true) var canon string switch len(visible) { @@ -267,19 +276,9 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc } aliasMap[m] = canon } - // Excludes are not passive prose: once this concept is active on a - // reviewed command, a non-real excluded spelling is protected from - // downstream fuzzy correction. A real flag is left alone because it - // already has an independently valid command-local meaning. - for _, exclude := range concept.Excludes { - morphed := cmdutil.Morph(exclude) - if _, isReal := realByMorph[morphed]; !isReal { - excludedSet[morphed] = true - } - } } for excluded := range excludedSet { - if _, isAlias := aliasMap[excluded]; !isAlias { + if _, isAlias := aliasMap[excluded]; !isAlias && !claimedRealSet[excluded] { blockedSet[excluded] = true } } diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index b7e9d366..234e9fb8 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -65,7 +65,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "page"}, + Blocked: []string{"count", "cursor", "page"}, }, { CLIPath: "attendance +check-result", @@ -95,7 +95,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"offset", "page", "time"}, + Blocked: []string{"count", "offset", "page", "time"}, }, { CLIPath: "chat +bot-find", @@ -292,7 +292,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "group", "open-conversation-id": "group", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat +chat-role-list", @@ -362,7 +362,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "group", "open-conversation-id": "group", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat +chat-set-admin", @@ -718,7 +718,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-id": "conversation-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-dingtalk-id", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id", "user-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-dingtalk-id", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id", "user-id"}, }, { CLIPath: "chat +messages-recall-by-bot", @@ -765,7 +765,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-message-id": "ref-msg-id", "ref-message-id": "ref-msg-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group", "group-id", "group-ids", "group-name", "id", "message-id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, }, { CLIPath: "chat +messages-resource-download", @@ -777,7 +777,7 @@ var generatedParamAliases = []ParamAliasEntry{ "msg-id": "message-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "download-dir", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "download-dir", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat +messages-resource-url", @@ -890,7 +890,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat category add-conv", - Blocked: []string{"category-id"}, + Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { @@ -917,7 +917,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat category remove-conv", - Blocked: []string{"category-id"}, + Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { @@ -948,7 +948,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat clear-red-point", @@ -957,7 +957,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat conversation-info", @@ -966,7 +966,7 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "name", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -974,7 +974,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group bots", @@ -995,7 +995,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group get-by-group-id", @@ -1006,7 +1006,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group members", @@ -1083,35 +1083,35 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice edit", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice get", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice list", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group quit", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group rename", @@ -1122,7 +1122,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "id", "open-conversation-id": "id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group set-admin", @@ -1130,14 +1130,14 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "conversation-id", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat group set-history", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group share-invite", @@ -1156,38 +1156,39 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group update-alias", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-icon", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-nick", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-settings", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-mute", + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1195,7 +1196,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "user-ids": "users", }, - Blocked: []string{"at-user-ids", "staff-id", "uid", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1203,14 +1204,14 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role list", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role query-user", @@ -1220,14 +1221,14 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role remove", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role remove-user", @@ -1237,7 +1238,7 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role set-user", @@ -1247,14 +1248,14 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role update", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat hide", @@ -1263,7 +1264,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mark-read", @@ -1274,7 +1275,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-id": "conversation-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat mark-unread", @@ -1283,14 +1284,14 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message add-emoji", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, Ambiguous: []string{"open-message-id"}, }, { @@ -1310,7 +1311,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, Ambiguous: []string{"open-message-id"}, }, { @@ -1335,7 +1336,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "open-conversation-id", "group": "open-conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message forward", @@ -1378,7 +1379,7 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "count", "cursor", "end", "name", "page", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1393,7 +1394,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-time": "start", "time-min": "start", }, - Blocked: []string{"date", "time"}, + Blocked: []string{"date", "end", "time"}, }, { CLIPath: "chat message list-by-ids", @@ -1427,6 +1428,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat message list-mentions", + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1444,7 +1446,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message list-unread-conversations", @@ -1461,7 +1463,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-message-id": "message-id", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat message recall", @@ -1469,14 +1471,14 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message recall-by-bot", Aliases: map[string]string{ "robot": "robot-code", }, - Blocked: []string{"bot-code", "bot-id", "open-bot-id", "robot-id"}, + Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1484,7 +1486,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, Ambiguous: []string{"open-message-id"}, }, { @@ -1504,7 +1506,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "group-id", "group-ids", "open-conversation-ids"}, + Blocked: []string{"conversation-ids", "group-id", "group-ids", "message-ids", "msg-ids", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "src-msg-id", "topic-id"}, Ambiguous: []string{"open-message-id"}, }, { @@ -1520,6 +1522,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat message search", + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1528,7 +1531,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "conversation-ids", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "chat-id", "conversation-id", "group-id", "group-ids", "open-conversation-id", "staff-id", "uid", "userid"}, + Blocked: []string{"at-user-ids", "chat-id", "conversation-id", "group-id", "group-ids", "open-conversation-id", "staff-id", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat message send", @@ -1540,7 +1543,7 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "name", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1550,7 +1553,7 @@ var generatedParamAliases = []ParamAliasEntry{ "robot": "robot-code", "user-ids": "users", }, - Blocked: []string{"bot-code", "bot-id", "open-bot-id", "robot-id", "staff-id", "to-user-id", "uid", "user", "user-id", "userid"}, + Blocked: []string{"at-user-ids", "bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"}, Ambiguous: []string{"at-ids", "chat-id", "open-conversation-id"}, }, { @@ -1561,7 +1564,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat message send-card", - Blocked: []string{"staff-id", "uid", "user", "user-id", "userid"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { @@ -1618,7 +1621,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mute-red-envelope", @@ -1627,7 +1630,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat set-top", @@ -1699,7 +1702,7 @@ var generatedParamAliases = []ParamAliasEntry{ "parent": "dept", "parent-id": "dept", }, - Blocked: []string{"department-ids", "depts", "name", "query"}, + Blocked: []string{"department-ids", "dept-ids", "depts", "name", "query"}, }, { CLIPath: "contact user profile get", @@ -1719,7 +1722,7 @@ var generatedParamAliases = []ParamAliasEntry{ "app-id": "unified-app-id", "application-id": "unified-app-id", }, - Blocked: []string{"agent-id", "app-secret"}, + Blocked: []string{"agent-id", "app-key", "app-secret"}, }, { CLIPath: "devdoc article search", @@ -1852,7 +1855,7 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "url": "node", }, - Blocked: []string{"chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "name", "open-conversation-id", "open-conversation-ids", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc +comment-delete", @@ -1936,7 +1939,7 @@ var generatedParamAliases = []ParamAliasEntry{ "url": "node", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, }, { CLIPath: "doc +create", @@ -1952,7 +1955,7 @@ var generatedParamAliases = []ParamAliasEntry{ "text": "content", "workspace-id": "workspace", }, - Blocked: []string{"content-file", "export-format", "mime-type", "node", "parent-id", "title"}, + Blocked: []string{"content-file", "export-format", "folder", "format", "mime-type", "name", "node", "parent-id", "title"}, }, { CLIPath: "doc +create-from-template", @@ -1969,7 +1972,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"node", "parent-id", "subject", "text", "title"}, + Blocked: []string{"folder", "name", "node", "parent-id", "subject", "text", "title"}, }, { CLIPath: "doc +doc-append", @@ -2028,7 +2031,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-block": "start-block-id", "url": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { @@ -2060,7 +2063,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"folder"}, + Blocked: []string{"folder", "node"}, }, { CLIPath: "doc +history-list", @@ -2111,7 +2114,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space-id": "workspace", "workspace-id": "workspace", }, - Blocked: []string{"node", "parent-id"}, + Blocked: []string{"folder", "node", "parent-id"}, }, { CLIPath: "doc +inspect", @@ -2148,7 +2151,7 @@ var generatedParamAliases = []ParamAliasEntry{ "top": "limit", "workspace-id": "workspace", }, - Blocked: []string{"count", "node", "offset", "page", "parent-id"}, + Blocked: []string{"count", "folder", "node", "offset", "page", "parent-id"}, }, { CLIPath: "doc +media-download", @@ -2207,7 +2210,7 @@ var generatedParamAliases = []ParamAliasEntry{ "url": "node", "workspace-id": "workspace", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version"}, }, { CLIPath: "doc +resource-delete", @@ -2330,7 +2333,7 @@ var generatedParamAliases = []ParamAliasEntry{ "revision": "expected-revision", "url": "node", }, - Blocked: []string{"content-file", "export-format", "mime-type", "version", "version-no", "version-number"}, + Blocked: []string{"content-file", "export-format", "format", "mime-type", "version", "version-no", "version-number"}, }, { CLIPath: "doc +version-list", @@ -2342,7 +2345,7 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"max-result", "max-results", "next-cursor", "next-page-token", "next-token", "per-page", "size", "take", "top"}, }, { @@ -2377,7 +2380,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "index", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "index", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc block insert", @@ -2390,7 +2393,7 @@ var generatedParamAliases = []ParamAliasEntry{ "ref-block-id": "ref-block", "reference-block-id": "ref-block", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { @@ -2399,7 +2402,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc block update", @@ -2409,7 +2412,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment create", @@ -2422,7 +2425,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "comment-id", "comment-key", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment create-inline", @@ -2432,7 +2435,7 @@ var generatedParamAliases = []ParamAliasEntry{ "document-id": "node", "text": "content", }, - Blocked: []string{"comment-id", "comment-key", "folder", "folder-id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment delete", @@ -2441,7 +2444,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment list", @@ -2457,7 +2460,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment reply", @@ -2471,7 +2474,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc comment update", @@ -2485,7 +2488,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "mentioned-open-conversation-id", "text": "content", }, - Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "chat-id", "chat-ids", "conversation-id", "conversation-ids", "folder", "folder-id", "group-id", "group-ids", "id", "job-id", "name", "parent-id", "revision", "task-id", "template-id", "title", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc create", @@ -2496,7 +2499,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space-id": "workspace", "text": "content", }, - Blocked: []string{"export-format", "mime-type", "node"}, + Blocked: []string{"export-format", "folder", "format", "mime-type", "name", "node", "title"}, }, { CLIPath: "doc export", @@ -2504,7 +2507,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc export get", @@ -2519,7 +2522,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space": "workspace", "space-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"folder", "node"}, }, { CLIPath: "doc import", @@ -2527,7 +2530,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space": "workspace", "space-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"folder", "node"}, }, { CLIPath: "doc import get", @@ -2542,7 +2545,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc media download", @@ -2550,7 +2553,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc media insert", @@ -2560,7 +2563,7 @@ var generatedParamAliases = []ParamAliasEntry{ "ref-block-id": "ref-block", "reference-block-id": "ref-block", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-block", "parent-block-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-block", "parent-block-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { @@ -2569,7 +2572,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc read", @@ -2577,7 +2580,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"before-block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-block-id", "parent-id", "ref-block-id", "reference-block-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"block-id"}, }, { @@ -2586,7 +2589,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style background set", @@ -2594,7 +2597,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style cover clear", @@ -2602,7 +2605,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style cover set", @@ -2610,7 +2613,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc style get", @@ -2618,7 +2621,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc template apply", @@ -2626,7 +2629,7 @@ var generatedParamAliases = []ParamAliasEntry{ "space": "workspace", "space-id": "workspace", }, - Blocked: []string{"node"}, + Blocked: []string{"folder", "node"}, }, { CLIPath: "doc template list", @@ -2657,7 +2660,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "offset", "page", "subject", "text", "title"}, + Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, }, { CLIPath: "doc update", @@ -2667,7 +2670,7 @@ var generatedParamAliases = []ParamAliasEntry{ "document-id": "node", "expected-revision": "revision", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "export-format", "folder", "folder-id", "job-id", "mime-type", "parent-id", "task-id", "template-id", "version", "version-no", "version-number", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "export-format", "folder", "folder-id", "format", "id", "job-id", "mime-type", "parent-id", "task-id", "template-id", "version", "version-no", "version-number", "workspace", "workspace-id"}, }, { CLIPath: "doc version list", @@ -2683,7 +2686,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "folder", "folder-id", "id", "job-id", "offset", "page", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc version revert", @@ -2693,7 +2696,7 @@ var generatedParamAliases = []ParamAliasEntry{ "version-no": "version", "version-number": "version", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "workspace", "workspace-id"}, }, { CLIPath: "doc version save", @@ -2701,7 +2704,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "doc whiteboard insert", @@ -2709,7 +2712,7 @@ var generatedParamAliases = []ParamAliasEntry{ "doc": "node", "document-id": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "folder", "folder-id", "id", "job-id", "parent-id", "revision", "task-id", "template-id", "version", "workspace", "workspace-id"}, }, { CLIPath: "drive info", @@ -2718,13 +2721,14 @@ var generatedParamAliases = []ParamAliasEntry{ "workspace": "space-id", "workspace-id": "space-id", }, - Blocked: []string{"folder"}, + Blocked: []string{"folder", "node"}, }, { CLIPath: "drive list", Aliases: map[string]string{ "folder-id": "folder", }, + Blocked: []string{"space-id"}, Ambiguous: []string{"space"}, }, { @@ -2766,7 +2770,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "page"}, + Blocked: []string{"count", "cursor", "page"}, }, { CLIPath: "mail user search", @@ -2789,7 +2793,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "cursor"}, + Blocked: []string{"count", "cursor", "page"}, }, { CLIPath: "oa +search-forms", @@ -2823,7 +2827,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-time": "start", "time-min": "start", }, - Blocked: []string{"date", "time"}, + Blocked: []string{"date", "end", "time"}, }, { CLIPath: "report outbox list", diff --git a/internal/cli/param_aliases_test.go b/internal/cli/param_aliases_test.go index aab959b7..9483bba0 100644 --- a/internal/cli/param_aliases_test.go +++ b/internal/cli/param_aliases_test.go @@ -457,6 +457,19 @@ func TestReduceLeafParamAliasesExcludesProtectFuzzyButDoNotOverrideAnotherConcep } } +func TestReduceLeafParamAliasesExcludesProtectUnclaimedRealFlag(t *testing.T) { + concepts := []Concept{ + {ID: "single_id", Members: []string{"id", "item-id"}, Excludes: []string{"item-ids"}}, + } + entry, problems := reduceLeafParamAliases("demo cmd", realMap(realFlag{name: "id"}, realFlag{name: "item-ids"}), concepts, CommandOverride{}) + if len(problems) != 0 { + t.Fatalf("unexpected problems: %v", problems) + } + if entry == nil || !containsParamAlias(entry.Blocked, "item-ids") { + t.Fatalf("unclaimed real exclude was not blocked: %#v", entry) + } +} + func TestReduceLeafParamAliasesRejectsProtectionOrScopedAliasOnRealFlag(t *testing.T) { real := realMap(realFlag{name: "user-id"}, realFlag{name: "user"}) for name, override := range map[string]CommandOverride{ @@ -472,6 +485,46 @@ func TestReduceLeafParamAliasesRejectsProtectionOrScopedAliasOnRealFlag(t *testi } } +func TestGeneratedParamAliasesBlockPluralListSpellingsOnSingleIDCommands(t *testing.T) { + entries := make(map[string]ParamAliasEntry, len(generatedParamAliases)) + for _, entry := range generatedParamAliases { + entries[entry.CLIPath] = entry + } + assertBlocked := func(path string, names ...string) { + t.Helper() + entry, ok := entries[path] + if !ok { + t.Fatalf("missing generated alias entry for %q", path) + } + for _, name := range names { + if !entry.IsBlocked(cmdutil.Morph(name)) { + t.Fatalf("%s: %q not blocked; entry = %#v", path, name, entry) + } + } + } + + for _, path := range []string{ + "chat message add-emoji", + "chat message remove-emoji", + "chat message add-text-emotion", + "chat message remove-text-emotion", + } { + assertBlocked(path, "msg-ids", "message-ids") + } + for _, path := range []string{ + "chat message send", + "chat conversation-info", + "chat category add-conv", + "chat category remove-conv", + "chat message list", + "chat message list-mentions", + "chat message recall-by-bot", + "chat message search", + } { + assertBlocked(path, "conversation-ids") + } +} + // TestGeneratedParamAliasesAreWellFormed guards the committed generated table // at the Go level, complementing the byte-identity drift gate. func TestGeneratedParamAliasesAreWellFormed(t *testing.T) { From c3ffb9c831d4bce71e6050aab4c1c9c705f03ec0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 20:56:46 +0800 Subject: [PATCH 083/250] fix(chat): validate list-all time defaults --- .changes/973-chat-message-time-defaults.md | 2 +- internal/helpers/chat.go | 13 ++- internal/helpers/chat_command_edges_test.go | 1 + .../helpers/chat_message_pagination_test.go | 83 +++++++++++++------ 4 files changed, 72 insertions(+), 27 deletions(-) diff --git a/.changes/973-chat-message-time-defaults.md b/.changes/973-chat-message-time-defaults.md index fbe6ba2c..09da6854 100644 --- a/.changes/973-chat-message-time-defaults.md +++ b/.changes/973-chat-message-time-defaults.md @@ -2,4 +2,4 @@ category: Fixed --- -- **Chat message time defaults** (#973) — defaults omitted message-query time bounds without creating reversed windows. +- **Chat message time defaults** (#973) — default omitted `chat message list-all` time bounds in `Asia/Shanghai` when emitting timezone-less `yyyy-MM-dd HH:mm:ss` values, matching parsing semantics and rejecting reversed windows. diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 5950772a..0a3a9b27 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -471,6 +471,17 @@ func chatMessageListAllArgs(cmd *cobra.Command) (map[string]any, error) { if err != nil { return nil, err } + startMs, err := parseISOTimeToMillis("start", startRaw) + if err != nil { + return nil, err + } + endMs, err := parseISOTimeToMillis("end", endRaw) + if err != nil { + return nil, err + } + if err := validateTimeRange(startMs, endMs); err != nil { + return nil, err + } cursor, _ := cmd.Flags().GetString("cursor") return map[string]any{ "startTime": startRaw, @@ -631,7 +642,7 @@ func defaultChatMessageTimeRange(cmd *cobra.Command, lookback time.Duration) (st } func formatChatMessageListAllTime(ms int64) string { - return time.UnixMilli(ms).Format("2006-01-02 15:04:05") + return time.UnixMilli(ms).In(shanghaiLocation()).Format("2006-01-02 15:04:05") } func defaultChatMessageListTime() string { diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 93322ff4..a5f0bacd 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -177,6 +177,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"message", "list-all", "--start=not-a-time", "--end=2026-01-02T00:00:00Z"}, {"message", "list-all", "--start=2026-01-01 00:00:00", "--end=bad"}, {"message", "list-all", "--start=2026-01-02 00:00:00", "--end=2026-01-01 00:00:00"}, + {"message", "list-all", "--start=2027-01-01 00:00:00"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-01T00:00:00Z", "--end=bad"}, {"message", "list-by-sender", "--sender-user-id=u1", "--start=2026-01-02T00:00:00Z", "--end=2026-01-01T00:00:00Z"}, diff --git a/internal/helpers/chat_message_pagination_test.go b/internal/helpers/chat_message_pagination_test.go index e444eb5b..e947f489 100644 --- a/internal/helpers/chat_message_pagination_test.go +++ b/internal/helpers/chat_message_pagination_test.go @@ -287,6 +287,40 @@ func TestChatMessagePaginationDefaultsStartFromExplicitEnd(t *testing.T) { } } +func TestChatMessageListAllDefaultStartFromTimezoneLessEndUsesShanghai(t *testing.T) { + previousLocal := time.Local + t.Cleanup(func() { time.Local = previousLocal }) + + for _, loc := range []*time.Location{time.UTC, time.FixedZone("EST", -5*3600)} { + t.Run(loc.String(), func(t *testing.T) { + time.Local = loc + caller := &chatMessagePaginationCaller{} + _, err := executeChatMessagePaginationCommand(t, caller, "message", "list-all", "--end", "2026-03-01 00:00:00") + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one call", caller.calls) + } + got := caller.calls[0] + assertStringArg(t, got.args["endTime"], "2026-03-01 00:00:00") + assertStringArg(t, got.args["startTime"], "2026-02-28 00:00:00") + + startMs, err := parseISOTimeToMillis("start", got.args["startTime"].(string)) + if err != nil { + t.Fatal(err) + } + endMs, err := parseISOTimeToMillis("end", got.args["endTime"].(string)) + if err != nil { + t.Fatal(err) + } + if gotWindow := time.Duration(endMs-startMs) * time.Millisecond; gotWindow != 24*time.Hour { + t.Fatalf("window = %v, want 24h", gotWindow) + } + }) + } +} + func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing.T) { startRaw := "2026-01-01T00:00:00+08:00" startMs, err := parseISOTimeToMillis("start", startRaw) @@ -354,24 +388,26 @@ func TestChatMessagePaginationDefaultsEndFromNowWhenOnlyStartProvided(t *testing } } -func TestChatMessageListAllPassesExplicitTimeBoundsThrough(t *testing.T) { +func TestChatMessageListAllRejectsInvalidTimeBounds(t *testing.T) { tests := []struct { - name string - args []string - wantStart string - wantEnd string + name string + args []string + wantErr string }{ { - name: "invalid start", - args: []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"}, - wantStart: "not-a-time", - wantEnd: "2020-01-01T00:00:00+08:00", + name: "invalid start", + args: []string{"message", "list-all", "--start", "not-a-time", "--end", "2020-01-01T00:00:00+08:00"}, + wantErr: "cannot parse time for --start", }, { - name: "end before start", - args: []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"}, - wantStart: "2021-01-01T00:00:00+08:00", - wantEnd: "2020-01-01T00:00:00+08:00", + name: "end before start", + args: []string{"message", "list-all", "--start", "2021-01-01T00:00:00+08:00", "--end", "2020-01-01T00:00:00+08:00"}, + wantErr: "--end must be after --start", + }, + { + name: "default end before future start", + args: []string{"message", "list-all", "--start", "2027-01-01 00:00:00"}, + wantErr: "--end must be after --start", }, } @@ -379,18 +415,15 @@ func TestChatMessageListAllPassesExplicitTimeBoundsThrough(t *testing.T) { t.Run(tt.name, func(t *testing.T) { caller := &chatMessagePaginationCaller{} _, err := executeChatMessagePaginationCommand(t, caller, tt.args...) - if err != nil { - t.Fatal(err) + if err == nil { + t.Fatal("expected validation error, got nil") } - if len(caller.calls) != 1 { - t.Fatalf("calls = %#v, want one MCP call", caller.calls) + if !strings.Contains(err.Error(), tt.wantErr) { + t.Fatalf("error = %q, want contains %q", err.Error(), tt.wantErr) } - got := caller.calls[0] - if got.tool != "search_messages_by_time_range" { - t.Fatalf("tool = %q, want search_messages_by_time_range", got.tool) + if len(caller.calls) != 0 { + t.Fatalf("calls = %#v, want no MCP call", caller.calls) } - assertStringArg(t, got.args["startTime"], tt.wantStart) - assertStringArg(t, got.args["endTime"], tt.wantEnd) }) } } @@ -437,11 +470,11 @@ func parseChatMessageListAllTimeArg(t *testing.T, value any) time.Time { } return time.UnixMilli(parsedMs) } - parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local) + parsedMs, err := parseISOTimeToMillis("time", raw) if err != nil { t.Fatalf("time arg = %q, parse err = %v", raw, err) } - return parsed + return time.UnixMilli(parsedMs) } func assertChatMessageListAllTimeFormat(t *testing.T, value any) { @@ -453,7 +486,7 @@ func assertChatMessageListAllTimeFormat(t *testing.T, value any) { if strings.Contains(raw, "T") { t.Fatalf("time arg = %q, want yyyy-MM-dd HH:mm:ss without RFC3339 separator", raw) } - if _, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local); err != nil { + if _, err := parseISOTimeToMillis("time", raw); err != nil { t.Fatalf("time arg = %q, parse err = %v", raw, err) } } From 91f0fb7b116b7d090c918f57ea3a7d016fb0f678 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 21:03:03 +0800 Subject: [PATCH 084/250] fix(chat): declare idempotency key alias --- internal/app/root_help_test.go | 7 +++++++ internal/helpers/chat.go | 9 ++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index 79c1c967..2224ad22 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -22,6 +22,7 @@ import ( "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" @@ -377,6 +378,12 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) { if legacyUUID == nil || !legacyUUID.Hidden { t.Fatalf("chat message send --uuid hidden = %#v, want hidden compatibility flag", legacyUUID) } + if got := legacyUUID.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "idempotency-key" { + t.Fatalf("chat message send --uuid alias_of = %#v, want idempotency-key", got) + } + if got := legacyUUID.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("chat message send --uuid alias_origin = %#v, want %s", got, runtimeannotate.FlagAliasOriginCorecmdV1) + } got, err := executeRootCaptureStdout(t, []string{ "chat", "file", "upload", diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 1f8ad37f..19fabba2 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -18,6 +18,7 @@ import ( "unicode/utf8" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" @@ -4386,9 +4387,11 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 _ = chatMessageSendCmd.Flags().MarkHidden("file-type") _ = chatMessageSendCmd.Flags().MarkHidden("file-size") chatMessageSendCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）") - chatMessageSendCmd.Flags().String("idempotency-key", "", "幂等键，相同 key 在 24h 内不会重复发送（可选）") - chatMessageSendCmd.Flags().String("uuid", "", "--idempotency-key 的兼容别名") - _ = chatMessageSendCmd.Flags().MarkHidden("uuid") + corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{ + Name: "idempotency-key", + Usage: "幂等键，相同 key 在 24h 内不会重复发送（可选）", + Aliases: []string{"uuid"}, + }}) cli.AttachRuntimeSchema(chatMessageSendCmd, "chat", "send_personal_message", "hardcoded:chat") cli.AnnotateRuntimeConstraints(chatMessageSendCmd, cli.RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"group", "user", "open-dingtalk-id"}}, From 8c6266f15892ac93cbb0a3ac578507c5e7ef99bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 21:06:44 +0800 Subject: [PATCH 085/250] chore(policy): consume idempotency flag migration --- .../interface-migrations/approved-flag-migrations-v1.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index a89aaea1..ece90440 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -958,7 +958,7 @@ "required": false } }, - "state": "pending", + "state": "consumed", "reason": "保留旧 argv 兼容性，并将幂等参数规范 flag 设为唯一可见入口" }, { From 97b6022017653f68964ac4c12ee82f2fb12d00df Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 21:35:48 +0800 Subject: [PATCH 086/250] test(drive): make pinned-root TOCTOU reproductions runnable on Windows Windows keeps the pinned directory locked while a handle inside it is open (os.Root plus the pull temp file or the upload source), so renaming that directory fails with a sharing violation. Every "pinned root/ancestor was swapped" reproduction in the drive mirror tests relied on such a rename, so 13 tests failed on windows-latest. That, not a coverage shortfall, is why Coverage (Windows) exited 1 before the gate ever ran. Each reproduction now falls back to injecting the equivalent identity change when the rename is refused. pinnedPullRoot.verify() and verifyParent() read current identity only through pullPathStat / pullRootLstat, so pointing those seams at another directory hits the same fail-closed branches. Unix still performs the real move and loses no strength. Assertions that need an actual replacement tree now branch on the helper's return value. forcePinnedFallbackForTest makes the fallback path itself regressible on any platform, and a dedicated test covers it. Verified locally with the fallback forced on: all 13 tests pass and changed code coverage stays at 100%. --- .../drive_pinned_root_identity_test.go | 77 +++++++++++++++++++ .../helpers/drive_pull_plan_coverage_test.go | 11 ++- internal/helpers/drive_pull_toctou_test.go | 56 +++++++++----- internal/helpers/drive_push_toctou_test.go | 46 ++++++++--- 4 files changed, 159 insertions(+), 31 deletions(-) create mode 100644 internal/helpers/drive_pinned_root_identity_test.go diff --git a/internal/helpers/drive_pinned_root_identity_test.go b/internal/helpers/drive_pinned_root_identity_test.go new file mode 100644 index 00000000..1184f9e8 --- /dev/null +++ b/internal/helpers/drive_pinned_root_identity_test.go @@ -0,0 +1,77 @@ +package helpers + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +// Windows 会用已打开的目录句柄锁住目录，把「固定后目录被移走／换成软链」这类 +// TOCTOU 在该平台变成物理不可达：os.Rename 直接 ERROR_SHARING_VIOLATION。 +// 但被测的 fail-closed 分支必须在所有平台都覆盖，所以这里提供与真实替换等价的 +// 身份注入：pinnedPullRoot.verify() 与 verifyParent() 都只通过 pullPathStat / +// pullRootLstat 读取当前身份，让这两个 seam 指向另一个目录即可命中同一分支。 + +// forcePinnedFallbackForTest 打开后，「移走固定目录」的复现手法一律走身份注入降级。 +// 默认 false：Unix 上用真实移动，验证更强。只有 Windows 才会真的走降级分支，所以 +// 下面的注入回归测试会打开它，让那条路径在任何平台都能被验证。 +var forcePinnedFallbackForTest = false + +// swapPinnedRootIdentity 让 absDir 的根身份读数指向另一个目录，使随后的 +// pinnedPullRoot.verify() 判定「本地根目录在同步期间被替换」。 +func swapPinnedRootIdentity(t *testing.T, absDir string) { + t.Helper() + decoy, err := os.Stat(t.TempDir()) + if err != nil { + t.Fatal(err) + } + want := filepath.Clean(absDir) + testseam.Swap(t, &pullPathStat, func(path string) (os.FileInfo, error) { + if filepath.Clean(path) == want { + return decoy, nil + } + return os.Stat(path) + }) +} + +// 降级注入只有 Windows 会真的走到（Unix 的 rename 成功）。这里强制打开开关， +// 确保注入手段本身在任何平台都可回归：不移动目录，但固定根的校验必须随之失败， +// 且原有目录树不得被动过。 +func TestCrossPlatformCoveragePinnedRootFallbackInjectionFailsVerification(t *testing.T) { + testseam.Swap(t, &forcePinnedFallbackForTest, true) + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, "a.txt"), "pinned-original") + root := newPinnedPullRootForCoverage(t, dir) + if err := root.verify(); err != nil { + t.Fatalf("baseline verify: %v", err) + } + + if moved := replacePinnedMirrorRoot(t, dir, filepath.Join(t.TempDir(), "moved")); moved { + t.Fatal("降级路径不应真的移动目录") + } + if err := root.verify(); err == nil || !strings.Contains(err.Error(), "本地根目录在同步期间被替换") { + t.Fatalf("身份注入后校验必须失败，got %v", err) + } + if b, err := os.ReadFile(filepath.Join(dir, "a.txt")); err != nil || string(b) != "pinned-original" { + t.Fatalf("降级必须保持原目录树不变: %q err=%v", string(b), err) + } +} + +// swapPinnedParentIdentity 让固定根下名为 rel 的父目录身份读数指向另一个目录， +// 使随后的 verifyParent() 判定「本地目标目录在下载期间被替换」。 +func swapPinnedParentIdentity(t *testing.T, rel string) { + t.Helper() + decoy, err := os.Lstat(t.TempDir()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &pullRootLstat, func(parent *os.Root, name string) (os.FileInfo, error) { + if filepath.ToSlash(filepath.Clean(name)) == rel { + return decoy, nil + } + return parent.Lstat(name) + }) +} diff --git a/internal/helpers/drive_pull_plan_coverage_test.go b/internal/helpers/drive_pull_plan_coverage_test.go index 0c155338..f78c6877 100644 --- a/internal/helpers/drive_pull_plan_coverage_test.go +++ b/internal/helpers/drive_pull_plan_coverage_test.go @@ -7,6 +7,7 @@ import ( "net/http" "os" "path/filepath" + "runtime" "strings" "testing" "time" @@ -350,9 +351,13 @@ func TestCrossPlatformCoverageDrivePullPlanCallers(t *testing.T) { if name == "a.txt" && !moved { moved = true if renameErr := os.Rename(dir, dir+"-pinned"); renameErr != nil { - t.Fatal(renameErr) - } - if mkdirErr := os.Mkdir(dir, 0o755); mkdirErr != nil { + // Windows 在固定目录上持有句柄时会锁住它，移走于该平台物理 + // 不可达；注入等价的根身份变化，命中同一条二次校验分支。 + if runtime.GOOS != "windows" { + t.Fatal(renameErr) + } + swapPinnedRootIdentity(t, dir) + } else if mkdirErr := os.Mkdir(dir, 0o755); mkdirErr != nil { t.Fatal(mkdirErr) } } diff --git a/internal/helpers/drive_pull_toctou_test.go b/internal/helpers/drive_pull_toctou_test.go index d32f4a6b..ebb74df1 100644 --- a/internal/helpers/drive_pull_toctou_test.go +++ b/internal/helpers/drive_pull_toctou_test.go @@ -8,6 +8,7 @@ import ( "net/http/httptest" "os" "path/filepath" + "runtime" "strings" "testing" @@ -30,8 +31,19 @@ func replacePullAncestorWithOutsideLink(t *testing.T, root, outside string) stri t.Helper() sub := filepath.Join(root, "sub") parked := filepath.Join(root, "sub-pinned") + if forcePinnedFallbackForTest { + swapPinnedParentIdentity(t, "sub") + return sub + } if err := os.Rename(sub, parked); err != nil { - t.Fatal(err) + // Windows 在目录内有已打开的句柄（如 pull 的临时文件）时会锁住该目录， + // 移走再换链于该平台物理不可达。退化为等价的父目录身份注入，命中 + // verifyParent 同一条 fail-closed 分支；原目录未移动，故返回 sub。 + if runtime.GOOS != "windows" { + t.Fatal(err) + } + swapPinnedParentIdentity(t, "sub") + return sub } if err := os.Symlink(outside, sub); err != nil { t.Skipf("平台不支持创建符号链接: %v", err) @@ -39,6 +51,27 @@ func replacePullAncestorWithOutsideLink(t *testing.T, root, outside string) stri return parked } +// replacePullCommandRootWithOutsideLink 把命令根整体移走，并在原名处放置指向根外的 +// 符号链接，复现「固定后命令根被换掉」的场景。Windows 在根目录持有已打开句柄时会 +// 锁住该目录，移走于该平台物理不可达，此时退化为等价的根身份注入。 +func replacePullCommandRootWithOutsideLink(t *testing.T, root, parked, outside string) { + t.Helper() + if forcePinnedFallbackForTest { + swapPinnedRootIdentity(t, root) + return + } + if err := os.Rename(root, parked); err != nil { + if runtime.GOOS != "windows" { + t.Fatal(err) + } + swapPinnedRootIdentity(t, root) + return + } + if err := os.Symlink(outside, root); err != nil { + t.Skipf("symlink unsupported: %v", err) + } +} + func runPullTOCTOUCase(t *testing.T, command string, root string) error { t.Helper() rf := &remoteFile{RelPath: "sub/a.txt", FileID: "F"} @@ -587,12 +620,7 @@ func TestCrossPlatformCoverageDrivePullCommandPinsRootAcrossAllFiles(t *testing. return err } if calls == 1 { - if err := os.Rename(root, parked); err != nil { - t.Fatal(err) - } - if err := os.Symlink(outside, root); err != nil { - t.Skipf("symlink unsupported: %v", err) - } + replacePullCommandRootWithOutsideLink(t, root, parked, outside) } return nil }) @@ -622,12 +650,7 @@ func TestCrossPlatformCoverageDrivePullPlansExistingRootBeforeRemoteRead(t *test if tool != "list_files" { t.Fatalf("root replacement must stop before %s", tool) } - if err := os.Rename(root, parked); err != nil { - t.Fatal(err) - } - if err := os.Symlink(outside, root); err != nil { - t.Skipf("symlink unsupported: %v", err) - } + replacePullCommandRootWithOutsideLink(t, root, parked, outside) return `{"result":{"items":[{"name":"a.txt","type":"file","fileId":"A"}]}}`, nil }} getCalls := 0 @@ -727,12 +750,7 @@ func TestCrossPlatformCoverageDriveSyncCommandPinsRootAcrossAllFiles(t *testing. return err } if calls == 1 { - if err := os.Rename(root, parked); err != nil { - t.Fatal(err) - } - if err := os.Symlink(outside, root); err != nil { - t.Skipf("symlink unsupported: %v", err) - } + replacePullCommandRootWithOutsideLink(t, root, parked, outside) } return nil }) diff --git a/internal/helpers/drive_push_toctou_test.go b/internal/helpers/drive_push_toctou_test.go index cfe0ccd3..876333d6 100644 --- a/internal/helpers/drive_push_toctou_test.go +++ b/internal/helpers/drive_push_toctou_test.go @@ -5,21 +5,37 @@ import ( "io" "os" "path/filepath" + "runtime" "strings" "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) -func replacePinnedMirrorRoot(t *testing.T, root, moved string) { +// replacePinnedMirrorRoot 返回 true 表示原目录被真实移走、原名处已换成另一个目录； +// 返回 false 表示走了 Windows 身份注入降级，原目录仍留在原处。依赖「替代目录内容」 +// 的断言必须按返回值分流。 +func replacePinnedMirrorRoot(t *testing.T, root, moved string) bool { t.Helper() + if forcePinnedFallbackForTest { + swapPinnedRootIdentity(t, root) + return false + } if err := os.Rename(root, moved); err != nil { - t.Fatalf("move pinned root: %v", err) + // Windows 在目录内有已打开的句柄（如上传读取中的源文件）时会锁住该目录， + // 移走固定根于该平台物理不可达。退化为等价的根身份注入，命中同一条 + // fail-closed 分支。 + if runtime.GOOS != "windows" { + t.Fatalf("move pinned root: %v", err) + } + swapPinnedRootIdentity(t, root) + return false } if err := os.Mkdir(root, 0o755); err != nil { t.Fatalf("create replacement root: %v", err) } mustWrite(t, filepath.Join(root, "a.txt"), "outside-replacement") + return true } // 本地扫描完成后、任何 create_folder/get_upload_info/commit_upload 前若命令行根已 @@ -36,10 +52,11 @@ func TestCrossPlatformCoverageDrivePushSyncRejectRootReplacementBeforeRemoteWrit mustWrite(t, filepath.Join(root, "a.txt"), "pinned-original") replaced := false + realMove := false caller := &driveScriptCaller{reply: func(tool string, _ map[string]any, _ int) (string, error) { if tool == "list_files" { if !replaced { - replacePinnedMirrorRoot(t, root, moved) + realMove = replacePinnedMirrorRoot(t, root, moved) replaced = true } return `{"result":{"items":[],"nextToken":""}}`, nil @@ -68,7 +85,12 @@ func TestCrossPlatformCoverageDrivePushSyncRejectRootReplacementBeforeRemoteWrit if putCalls != 0 { t.Fatalf("OSS PUT must not run after root replacement, got %d", putCalls) } - if b, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(b) != "outside-replacement" { + want := "outside-replacement" + if !realMove { + // 身份注入降级：原目录仍在原处，内容同样不得被镜像流程改写。 + want = "pinned-original" + } + if b, err := os.ReadFile(filepath.Join(root, "a.txt")); err != nil || string(b) != want { t.Fatalf("replacement tree changed: %q err=%v", string(b), err) } }) @@ -100,9 +122,10 @@ func TestCrossPlatformCoverageDrivePushSyncUploadReadsPinnedFileHandle(t *testin var uploaded string putCalls := 0 + realMove := false testseam.Swap(t, &pushPutOpenedFile, func(_ context.Context, _ string, _ map[string]string, file *os.File, _ int64) error { putCalls++ - replacePinnedMirrorRoot(t, root, moved) + realMove = replacePinnedMirrorRoot(t, root, moved) body, err := io.ReadAll(file) if err != nil { return err @@ -125,10 +148,15 @@ func TestCrossPlatformCoverageDrivePushSyncUploadReadsPinnedFileHandle(t *testin if commits := caller.callsFor("commit_upload"); len(commits) != 0 { t.Fatalf("root replacement must prevent commit_upload: %v", commits) } - if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "outside-replacement" { - t.Fatalf("replacement file was read or changed: %q err=%v", string(b), readErr) - } - if b, readErr := os.ReadFile(filepath.Join(moved, "a.txt")); readErr != nil || string(b) != "pinned-original" { + if realMove { + if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "outside-replacement" { + t.Fatalf("replacement file was read or changed: %q err=%v", string(b), readErr) + } + if b, readErr := os.ReadFile(filepath.Join(moved, "a.txt")); readErr != nil || string(b) != "pinned-original" { + t.Fatalf("pinned original changed: %q err=%v", string(b), readErr) + } + } else if b, readErr := os.ReadFile(filepath.Join(root, "a.txt")); readErr != nil || string(b) != "pinned-original" { + // 身份注入降级：原目录仍在原处，内容同样不得被上传路径改写。 t.Fatalf("pinned original changed: %q err=%v", string(b), readErr) } }) From 2734e3e1ce427a26c0e9da898c0b234f182b789e Mon Sep 17 00:00:00 2001 From: chichuan Date: Thu, 13 Aug 2026 22:14:05 +0800 Subject: [PATCH 087/250] test(drive): cover fs.WalkDir callback error short-circuit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Windows coverage gate reported changed-code coverage at 99.9360% because drive_push.go:471-473 — the branch that surfaces an error passed to the fs.WalkDir callback as its third argument — was not exercised. macOS runners happen to exercise it via directory-lstat failures, Windows runners do not. Add walk_callback_receives_error under TestCrossPlatformCoverageDrivePushFinalWalkAndCommandGates, which swaps walkPinnedLocalFS to invoke the callback with a non-nil err and asserts the error is bubbled up unchanged. Verified locally that the new subtest hits drive_push.go:471.17,473.4 with count=1. --- .../helpers/drive_push_sync_final_coverage_test.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/internal/helpers/drive_push_sync_final_coverage_test.go b/internal/helpers/drive_push_sync_final_coverage_test.go index ddbe2a8b..13aaf929 100644 --- a/internal/helpers/drive_push_sync_final_coverage_test.go +++ b/internal/helpers/drive_push_sync_final_coverage_test.go @@ -219,6 +219,19 @@ func TestCrossPlatformCoverageDrivePushFinalWalkAndCommandGates(t *testing.T) { } }) + // fs.WalkDir 允许把中途的 lstat 失败通过第三个参数传给回调而不是 DirEntry.Info； + // 该短路分支必须直接原样上抛，不能吞掉底层错误。macOS 上并非每次遍历都会经过它， + // 因此需要一个显式测试固定这条路径。 + t.Run("walk callback receives error", func(t *testing.T) { + _, root, _ := openDriveFinalCoverageRoot(t) + testseam.Swap(t, &walkPinnedLocalFS, func(_ fs.FS, _ string, fn fs.WalkDirFunc) error { + return fn("bad", nil, errTestInfo) + }) + if _, _, err := walkLocalForPushPinned(root); !errors.Is(err, errTestInfo) { + t.Fatalf("walk callback error = %v", err) + } + }) + t.Run("walk final root verification", func(t *testing.T) { rootPath, root, _ := openDriveFinalCoverageRoot(t) moved := filepath.Join(filepath.Dir(rootPath), "moved-after-walk") From 113e084a8d447593d4e5cf04058be0e48a238b42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 22:31:57 +0800 Subject: [PATCH 088/250] fix(chat): align default message time timezone --- internal/helpers/chat.go | 2 +- internal/helpers/chat_message_search_test.go | 112 ++++++++++++++----- 2 files changed, 82 insertions(+), 32 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 0a3a9b27..770e43c9 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -646,7 +646,7 @@ func formatChatMessageListAllTime(ms int64) string { } func defaultChatMessageListTime() string { - return time.Now().Format("2006-01-02 15:04:05") + return time.Now().In(shanghaiLocation()).Format("2006-01-02 15:04:05") } func chatMessageSearchAdvancedArgs(cmd *cobra.Command) (map[string]any, error) { diff --git a/internal/helpers/chat_message_search_test.go b/internal/helpers/chat_message_search_test.go index eeec924e..bdf1da88 100644 --- a/internal/helpers/chat_message_search_test.go +++ b/internal/helpers/chat_message_search_test.go @@ -724,44 +724,94 @@ func TestCrossPlatformCoverageChatMessageListUsesMCPMetadataGroupKey(t *testing. } } -func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesLocalLocation(t *testing.T) { +func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t *testing.T) { previousLocal := time.Local - time.Local = time.UTC t.Cleanup(func() { time.Local = previousLocal }) tests := []struct { - name string - args []string + name string + args []string + wantTool string + wantTarget map[string]any }{ - {name: "group", args: []string{"message", "list", "--group", "cid-1", "--limit", "50"}}, - {name: "direct", args: []string{"message", "list-direct", "--user", "user-1", "--limit", "50"}}, + { + name: "group", + args: []string{"message", "list", "--group", "cid-1", "--limit", "50"}, + wantTool: "list_conversation_message_v2", + wantTarget: map[string]any{"openconversation_id": "cid-1"}, + }, + { + name: "user", + args: []string{"message", "list", "--user", "user-1", "--limit", "50"}, + wantTool: "list_individual_chat_message", + wantTarget: map[string]any{"userId": "user-1"}, + }, + { + name: "user open DingTalk ID fallback", + args: []string{"message", "list", "--user", "D-user", "--limit", "50"}, + wantTool: "list_individual_chat_message", + wantTarget: map[string]any{"openDingTalkId": "D-user"}, + }, + { + name: "open DingTalk ID", + args: []string{"message", "list", "--open-dingtalk-id", "D-open", "--limit", "50"}, + wantTool: "list_individual_chat_message", + wantTarget: map[string]any{"openDingTalkId": "D-open"}, + }, + { + name: "direct user", + args: []string{"message", "list-direct", "--user", "user-1", "--limit", "50"}, + wantTool: "list_individual_chat_message", + wantTarget: map[string]any{"userId": "user-1"}, + }, + { + name: "direct open DingTalk ID", + args: []string{"message", "list-direct", "--open-dingtalk-id", "D-direct", "--limit", "50"}, + wantTool: "list_individual_chat_message", + wantTarget: map[string]any{"openDingTalkId": "D-direct"}, + }, } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - caller := &chatChangedContractCaller{} - before := time.Now() - err := executeChatChangedContract(t, caller, tt.args...) - after := time.Now() - if err != nil { - t.Fatal(err) - } - if len(caller.calls) != 1 { - t.Fatalf("calls = %#v, want one MCP call", caller.calls) - } - raw, ok := caller.calls[0].args["time"].(string) - if !ok || raw == "" { - t.Fatalf("time arg = %#v, want non-empty string", caller.calls[0].args["time"]) - } - got, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.Local) - if err != nil { - t.Fatalf("time arg = %q, parse err = %v", raw, err) - } - if got.Before(before.Add(-time.Second)) || got.After(after.Add(time.Second)) { - t.Fatalf("time arg = %q (%s), want current local time between %s and %s", raw, got, before, after) - } - if caller.calls[0].args["forward"] != false { - t.Fatalf("forward = %#v, want false when --time is omitted", caller.calls[0].args["forward"]) + for _, loc := range []*time.Location{time.UTC, time.FixedZone("EST", -5*3600)} { + t.Run(loc.String(), func(t *testing.T) { + time.Local = loc + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + caller := &chatChangedContractCaller{} + before := time.Now() + err := executeChatChangedContract(t, caller, tt.args...) + after := time.Now() + if err != nil { + t.Fatal(err) + } + if len(caller.calls) != 1 { + t.Fatalf("calls = %#v, want one MCP call", caller.calls) + } + if caller.calls[0].toolName != tt.wantTool { + t.Fatalf("tool = %q, want %q", caller.calls[0].toolName, tt.wantTool) + } + for key, want := range tt.wantTarget { + if got := caller.calls[0].args[key]; got != want { + t.Fatalf("arg %s = %#v, want %#v", key, got, want) + } + } + raw, ok := caller.calls[0].args["time"].(string) + if !ok || raw == "" { + t.Fatalf("time arg = %#v, want non-empty string", caller.calls[0].args["time"]) + } + gotMs, err := parseISOTimeToMillis("time", raw) + if err != nil { + t.Fatalf("time arg = %q, parse err = %v", raw, err) + } + wantMin := before.Add(-time.Second).UnixMilli() + wantMax := after.Add(time.Second).UnixMilli() + if gotMs < wantMin || gotMs > wantMax { + t.Fatalf("time arg = %q (%d), want between %d and %d", raw, gotMs, wantMin, wantMax) + } + if caller.calls[0].args["forward"] != false { + t.Fatalf("forward = %#v, want false when --time is omitted", caller.calls[0].args["forward"]) + } + }) } }) } From d17f50b9de24a0cdd8a6ec47f6c62c99dbcf0ebd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 23:26:08 +0800 Subject: [PATCH 089/250] fix(cli): keep real flags out of alias blocked list --- internal/cli/param_aliases.go | 11 ++- internal/cli/param_aliases_generated.go | 122 ++++++++++++------------ internal/cli/param_aliases_test.go | 39 +++++++- 3 files changed, 106 insertions(+), 66 deletions(-) diff --git a/internal/cli/param_aliases.go b/internal/cli/param_aliases.go index 1e35e95c..2f3ed4e5 100644 --- a/internal/cli/param_aliases.go +++ b/internal/cli/param_aliases.go @@ -278,9 +278,16 @@ func reduceLeafParamAliases(path string, realByMorph map[string][]realFlag, conc } } for excluded := range excludedSet { - if _, isAlias := aliasMap[excluded]; !isAlias && !claimedRealSet[excluded] { - blockedSet[excluded] = true + if _, isAlias := aliasMap[excluded]; isAlias { + continue } + if claimedRealSet[excluded] { + continue + } + if _, isReal := realByMorph[excluded]; isReal { + continue + } + blockedSet[excluded] = true } // (b) Command scoped aliases override concept reductions. diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index e7cb3de7..d1511342 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -65,7 +65,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "cursor", "page"}, + Blocked: []string{"count", "page"}, }, { CLIPath: "attendance +check-result", @@ -95,7 +95,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "offset", "page", "time"}, + Blocked: []string{"offset", "page", "time"}, }, { CLIPath: "chat +bot-find", @@ -292,7 +292,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "group", "open-conversation-id": "group", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat +chat-role-list", @@ -362,7 +362,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "group", "open-conversation-id": "group", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat +chat-set-admin", @@ -718,7 +718,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-id": "conversation-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-dingtalk-id", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id", "user-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-dingtalk-id", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id", "user-id"}, }, { CLIPath: "chat +messages-recall-by-bot", @@ -765,7 +765,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-message-id": "ref-msg-id", "ref-message-id": "ref-msg-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group", "group-id", "group-ids", "group-name", "id", "message-id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, }, { CLIPath: "chat +messages-resource-download", @@ -777,7 +777,7 @@ var generatedParamAliases = []ParamAliasEntry{ "msg-id": "message-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "download-dir", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "download-dir", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat +messages-resource-url", @@ -890,7 +890,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat category add-conv", - Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { @@ -917,7 +917,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat category remove-conv", - Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"category-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat", "chat-id", "open-conversation-id"}, }, { @@ -948,7 +948,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat clear-red-point", @@ -957,7 +957,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat conversation-info", @@ -966,7 +966,7 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -974,7 +974,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group bots", @@ -995,7 +995,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group get-by-group-id", @@ -1006,7 +1006,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group members", @@ -1083,35 +1083,35 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice edit", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice get", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group notice list", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group quit", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group rename", @@ -1122,7 +1122,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "id", "open-conversation-id": "id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group set-admin", @@ -1130,14 +1130,14 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "conversation-id", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, }, { CLIPath: "chat group set-history", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group share-invite", @@ -1156,39 +1156,39 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group update-alias", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-icon", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-nick", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group update-settings", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-mute", - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1196,7 +1196,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "staff-id", "target", "uid", "userid"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1204,14 +1204,14 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role list", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role query-user", @@ -1221,14 +1221,14 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role remove", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat group-role remove-user", @@ -1238,7 +1238,7 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role set-user", @@ -1248,14 +1248,14 @@ var generatedParamAliases = []ParamAliasEntry{ "uid": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, }, { CLIPath: "chat group-role update", Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "open-conversation-ids", "role-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat hide", @@ -1264,7 +1264,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mark-read", @@ -1275,7 +1275,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-id": "conversation-id", "open-message-id": "message-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat mark-unread", @@ -1284,7 +1284,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message add-emoji", @@ -1336,7 +1336,7 @@ var generatedParamAliases = []ParamAliasEntry{ "conversation-id": "open-conversation-id", "group": "open-conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message forward", @@ -1379,7 +1379,7 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "count", "cursor", "dest-conversation-id", "end", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "page", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1394,7 +1394,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-time": "start", "time-min": "start", }, - Blocked: []string{"date", "end", "time"}, + Blocked: []string{"date", "time"}, }, { CLIPath: "chat message list-by-ids", @@ -1428,7 +1428,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat message list-mentions", - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1446,7 +1446,7 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat message list-unread-conversations", @@ -1463,7 +1463,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-message-id": "message-id", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "user", "user-id", "userid"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "topic-id", "uid", "userid"}, }, { CLIPath: "chat message recall", @@ -1471,14 +1471,14 @@ var generatedParamAliases = []ParamAliasEntry{ "chat-id": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "open-task-id", "ref-msg-id", "resource-id", "source", "src-conversation-id", "src-msg-id", "target", "topic-id"}, }, { CLIPath: "chat message recall-by-bot", Aliases: map[string]string{ "robot": "robot-code", }, - Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"}, + Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1522,7 +1522,7 @@ var generatedParamAliases = []ParamAliasEntry{ }, { CLIPath: "chat message search", - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1531,7 +1531,7 @@ var generatedParamAliases = []ParamAliasEntry{ "open-conversation-ids": "conversation-ids", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "chat-id", "conversation-id", "group-id", "group-ids", "open-conversation-id", "staff-id", "uid", "user", "user-id", "userid"}, + Blocked: []string{"at-user-ids", "chat-id", "conversation-id", "group-id", "group-ids", "open-conversation-id", "staff-id", "uid", "userid"}, }, { CLIPath: "chat message send", @@ -1543,7 +1543,7 @@ var generatedParamAliases = []ParamAliasEntry{ "user-id": "user", "userid": "user", }, - Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"}, + Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "user-ids", "users"}, Ambiguous: []string{"chat-id", "open-conversation-id"}, }, { @@ -1553,7 +1553,7 @@ var generatedParamAliases = []ParamAliasEntry{ "robot": "robot-code", "user-ids": "users", }, - Blocked: []string{"at-user-ids", "bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"}, + Blocked: []string{"bot-code", "bot-id", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-bot-id", "open-conversation-ids", "robot-id", "source", "src-conversation-id", "staff-id", "target", "to-user-id", "uid", "user", "user-id", "userid"}, Ambiguous: []string{"at-ids", "chat-id", "open-conversation-id"}, }, { @@ -1621,7 +1621,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat mute-red-envelope", @@ -1630,7 +1630,7 @@ var generatedParamAliases = []ParamAliasEntry{ "group": "conversation-id", "open-conversation-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, }, { CLIPath: "chat set-top", @@ -1702,7 +1702,7 @@ var generatedParamAliases = []ParamAliasEntry{ "parent": "dept", "parent-id": "dept", }, - Blocked: []string{"department-ids", "dept-ids", "depts", "name", "query"}, + Blocked: []string{"department-ids", "depts", "name", "query"}, }, { CLIPath: "contact user profile get", @@ -1722,7 +1722,7 @@ var generatedParamAliases = []ParamAliasEntry{ "app-id": "unified-app-id", "application-id": "unified-app-id", }, - Blocked: []string{"agent-id", "app-key", "app-secret"}, + Blocked: []string{"agent-id", "app-secret"}, }, { CLIPath: "devdoc article search", @@ -2428,7 +2428,7 @@ var generatedParamAliases = []ParamAliasEntry{ "node-id": "node", "url": "node", }, - Blocked: []string{"block-id", "comment-id", "comment-key", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, + Blocked: []string{"block-id", "comment-id", "comment-key", "count", "dentry-id", "folder", "folder-id", "id", "job-id", "name", "offset", "page", "parent-id", "revision", "role", "space-id", "task-id", "template-id", "version", "workspace", "workspace-id"}, Ambiguous: []string{"max-result", "max-results", "next-cursor", "next-page-token", "next-token", "per-page", "size", "take", "top"}, }, { @@ -2777,7 +2777,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, + Blocked: []string{"count", "offset", "page", "subject", "text", "title"}, }, { CLIPath: "doc update", @@ -3871,7 +3871,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "cursor", "page"}, + Blocked: []string{"count", "page"}, }, { CLIPath: "mail user search", @@ -3894,7 +3894,7 @@ var generatedParamAliases = []ParamAliasEntry{ "take": "limit", "top": "limit", }, - Blocked: []string{"count", "cursor", "page"}, + Blocked: []string{"count", "cursor"}, }, { CLIPath: "oa +search-forms", @@ -3928,7 +3928,7 @@ var generatedParamAliases = []ParamAliasEntry{ "start-time": "start", "time-min": "start", }, - Blocked: []string{"date", "end", "time"}, + Blocked: []string{"date", "time"}, }, { CLIPath: "report outbox list", diff --git a/internal/cli/param_aliases_test.go b/internal/cli/param_aliases_test.go index b5b45f6d..40fccad9 100644 --- a/internal/cli/param_aliases_test.go +++ b/internal/cli/param_aliases_test.go @@ -237,6 +237,36 @@ func TestReduceLeafParamAliasesRemainingEdges(t *testing.T) { }) } +func TestCrossPlatformCoverageReduceLeafParamAliasesBindExcludesRealFlags(t *testing.T) { + entry, problems := reduceLeafParamAliases( + "demo cmd", + realMap(realFlag{name: "id"}, realFlag{name: "name"}, realFlag{name: "query"}), + []Concept{ + {ID: "base_id", Members: []string{"base-id", "base-token"}, Excludes: []string{"name", "unsafe"}}, + {ID: "query", Members: []string{"query", "keyword"}}, + }, + CommandOverride{Bind: map[string]string{"id": "base_id"}}, + ) + if len(problems) != 0 { + t.Fatalf("reduceLeafParamAliases() problems = %v", problems) + } + if entry == nil { + t.Fatal("reduceLeafParamAliases() entry = nil") + } + if entry.Aliases["base-id"] != "id" || entry.Aliases["base-token"] != "id" { + t.Fatalf("bound aliases = %#v, want base-id/base-token -> id", entry.Aliases) + } + if entry.Aliases["keyword"] != "query" { + t.Fatalf("query alias = %#v, want keyword -> query", entry.Aliases) + } + if containsParamAlias(entry.Blocked, "name") { + t.Fatalf("real excluded flag entered blocked list: %#v", entry.Blocked) + } + if !containsParamAlias(entry.Blocked, "unsafe") { + t.Fatalf("non-real excluded flag was not blocked: %#v", entry.Blocked) + } +} + func TestParamAliasEntryLookupMethods(t *testing.T) { entry := ParamAliasEntry{ Aliases: map[string]string{"uid": "user"}, @@ -457,7 +487,7 @@ func TestReduceLeafParamAliasesExcludesProtectFuzzyButDoNotOverrideAnotherConcep } } -func TestReduceLeafParamAliasesExcludesProtectUnclaimedRealFlag(t *testing.T) { +func TestReduceLeafParamAliasesExcludesDoNotBlockRealFlag(t *testing.T) { concepts := []Concept{ {ID: "single_id", Members: []string{"id", "item-id"}, Excludes: []string{"item-ids"}}, } @@ -465,8 +495,11 @@ func TestReduceLeafParamAliasesExcludesProtectUnclaimedRealFlag(t *testing.T) { if len(problems) != 0 { t.Fatalf("unexpected problems: %v", problems) } - if entry == nil || !containsParamAlias(entry.Blocked, "item-ids") { - t.Fatalf("unclaimed real exclude was not blocked: %#v", entry) + if entry == nil { + t.Fatal("expected a reduced entry") + } + if containsParamAlias(entry.Blocked, "item-ids") { + t.Fatalf("real exclude was blocked: %#v", entry) } } From 6c78db7467d17035e049ea5794656cd4dc224ec6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Thu, 13 Aug 2026 23:36:53 +0800 Subject: [PATCH 090/250] fix(chat): document Shanghai time message default --- internal/helpers/chat.go | 2 +- internal/helpers/chat_message_help_test.go | 4 ++-- internal/helpers/im_read_result_contract_test.go | 7 ++++--- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 267574de..f36dd104 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -2663,7 +2663,7 @@ func newChatCommand() *cobra.Command { chatMessageListCmd := &cobra.Command{ Use: "list", Short: "拉取会话消息内容", - Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。--time 可选，不传时默认当前时间并向旧消息拉取。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, + Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--group 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。--time 可选，不传时默认上海时间当前时间并向旧消息拉取。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, Example: ` dws chat message list --group dws chat message list --group --time "2025-03-01 00:00:00" dws chat message list --user --time "2025-03-01 00:00:00" --limit 50 diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 6941e2e8..9e528d3c 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -102,8 +102,8 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *te name: "list", args: []string{"message", "list", "--help"}, contains: []string{ - "--time 可选，不传时默认当前时间并向旧消息拉取", - "默认当前时间", + "--time 可选，不传时默认上海时间当前时间并向旧消息拉取", + "默认上海时间当前时间", "未传 --time 时默认 older", }, absent: []string{"开始时间，格式: yyyy-MM-dd HH:mm:ss (必填)"}, diff --git a/internal/helpers/im_read_result_contract_test.go b/internal/helpers/im_read_result_contract_test.go index 0d983925..9494069d 100644 --- a/internal/helpers/im_read_result_contract_test.go +++ b/internal/helpers/im_read_result_contract_test.go @@ -213,11 +213,12 @@ func TestCrossPlatformCoverageChatMessageListProjectsStableFieldsAndPreservesLeg func TestCrossPlatformCoverageChatMessageListDefaultsTimeAndOlderDirection(t *testing.T) { payload := `{"result":{"messages":[],"hasMore":false}}` caller := &imReadResultCaller{responses: map[string]string{"list_conversation_message_v2": payload}} + loc := shanghaiLocation() - before := time.Now() + before := time.Now().In(loc) _, err := executeIMReadCommand(t, caller, []string{"dws", "chat"}, newChatCommand, "message", "list", "--group", "cid-1", "--limit", "50") - after := time.Now() + after := time.Now().In(loc) if err != nil { t.Fatalf("chat message list returned error: %v", err) } @@ -231,7 +232,7 @@ func TestCrossPlatformCoverageChatMessageListDefaultsTimeAndOlderDirection(t *te if !ok || strings.TrimSpace(timeRaw) == "" { t.Fatalf("time arg = %#v, want generated current time", caller.args["time"]) } - gotTime, err := time.ParseInLocation("2006-01-02 15:04:05", timeRaw, time.Local) + gotTime, err := time.ParseInLocation("2006-01-02 15:04:05", timeRaw, loc) if err != nil { t.Fatalf("parse generated time %q: %v", timeRaw, err) } From d0e6aba3198611d4f29ca62d6effda1d512dbfb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Fri, 14 Aug 2026 00:23:18 +0800 Subject: [PATCH 091/250] fix(cli): cover alias exclude guard branches --- internal/cli/param_aliases_test.go | 8 +++++++- internal/helpers/chat.go | 11 ++++------- internal/helpers/chat_message_help_test.go | 6 +++++- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/internal/cli/param_aliases_test.go b/internal/cli/param_aliases_test.go index 40fccad9..950d6ee5 100644 --- a/internal/cli/param_aliases_test.go +++ b/internal/cli/param_aliases_test.go @@ -242,7 +242,7 @@ func TestCrossPlatformCoverageReduceLeafParamAliasesBindExcludesRealFlags(t *tes "demo cmd", realMap(realFlag{name: "id"}, realFlag{name: "name"}, realFlag{name: "query"}), []Concept{ - {ID: "base_id", Members: []string{"base-id", "base-token"}, Excludes: []string{"name", "unsafe"}}, + {ID: "base_id", Members: []string{"base-id", "base-token"}, Excludes: []string{"keyword", "name", "query", "unsafe"}}, {ID: "query", Members: []string{"query", "keyword"}}, }, CommandOverride{Bind: map[string]string{"id": "base_id"}}, @@ -259,9 +259,15 @@ func TestCrossPlatformCoverageReduceLeafParamAliasesBindExcludesRealFlags(t *tes if entry.Aliases["keyword"] != "query" { t.Fatalf("query alias = %#v, want keyword -> query", entry.Aliases) } + if containsParamAlias(entry.Blocked, "keyword") { + t.Fatalf("excluded alias entered blocked list: %#v", entry.Blocked) + } if containsParamAlias(entry.Blocked, "name") { t.Fatalf("real excluded flag entered blocked list: %#v", entry.Blocked) } + if containsParamAlias(entry.Blocked, "query") { + t.Fatalf("claimed real excluded flag entered blocked list: %#v", entry.Blocked) + } if !containsParamAlias(entry.Blocked, "unsafe") { t.Fatalf("non-real excluded flag was not blocked: %#v", entry.Blocked) } diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index 6c0623fc..262964cc 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -2934,19 +2934,16 @@ func newChatCommand() *cobra.Command { chatMessageListCmd := &cobra.Command{ Use: "list", Short: "拉取会话消息内容", - Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--conversation-id 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, + Long: `拉取指定群聊或单聊的会话消息内容。输出顶层 messages，稳定字段为 messageId 和 text；兼容保留 openMessageId 和 content。--conversation-id 指定群聊，--user 指定单聊用户（userId），--open-dingtalk-id 指定单聊用户（openDingTalkId），三者互斥。--time 可选，不传时默认上海时间当前时间并向旧消息拉取。推荐使用 --direction newer/older 控制时间方向：newer 表示从给定时间往现在拉，older 表示从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会返回 quotedMessage 引用上下文；被引用的原消息是合并转发或图片时，对应的类型与内容也会随引用上下文返回。如果返回的会话消息中包含 openConvThreadId 字段，说明是话题消息，可以调用 dws chat message list-topic-replies 拉取话题回复消息列表，openConvThreadId 作为 topic-id 参数。`, Example: ` dws chat message list --conversation-id --time "2025-03-01 00:00:00" dws chat message list --conversation-id dws chat message list --user --time "2025-03-01 00:00:00" --limit 50 dws chat message list --open-dingtalk-id --time "2025-03-01 00:00:00" --limit 50 dws chat message list --conversation-id --time "2025-03-01 00:00:00" --direction older dws chat message list --conversation-id --time "2025-03-01 00:00:00" --jq '.messages[] | {messageId, text}' - # 查询群 ID: dws chat search --query "群名" - # 查询 userId: dws contact user search --query "姓名"`, + # 查询群 ID: dws chat search --query "群名" + # 查询 userId: dws contact user search --query "姓名"`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "time"); err != nil { - return err - } groupID := flagOrFallback(cmd, "conversation-id", "group", "id", "chat") userID, _ := cmd.Flags().GetString("user") openDingTalkID, _ := cmd.Flags().GetString("open-dingtalk-id") @@ -4670,7 +4667,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageListCmd.Flags().String("conversation-id", "", "群聊 openconversation_id（群聊时必填）") chatMessageListCmd.Flags().String("user", "", "单聊用户 userId（单聊时与 --open-dingtalk-id 二选一）") chatMessageListCmd.Flags().String("open-dingtalk-id", "", "单聊用户 openDingTalkId（单聊时与 --user 二选一，适用于无法获取 userId 的场景）") - chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认当前时间）") + chatMessageListCmd.Flags().String("time", "", "开始时间，格式: yyyy-MM-dd HH:mm:ss（可选，默认上海时间当前时间）") chatMessageListCmd.Flags().String("direction", "", "时间方向: newer=从给定时间往现在拉，older=从给定时间往以前拉（未传 --time 时默认 older）") chatMessageListCmd.Flags().String("forward", "true", "true 等价 --direction newer，false 等价 --direction older（未传 --time 时默认 false）") _ = chatMessageListCmd.Flags().MarkHidden("forward") diff --git a/internal/helpers/chat_message_help_test.go b/internal/helpers/chat_message_help_test.go index 9cf8e10f..30f299df 100644 --- a/internal/helpers/chat_message_help_test.go +++ b/internal/helpers/chat_message_help_test.go @@ -245,7 +245,7 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *te var output bytes.Buffer cmd.SetOut(&output) cmd.SetErr(&output) - cmd.SetArgs(test.args) + cmd.SetArgs(test.args) if err := cmd.Execute(); err != nil { t.Fatalf("dws chat %s: %v\n%s", strings.Join(test.args, " "), err, output.String()) } @@ -267,6 +267,10 @@ func TestCrossPlatformCoverageChatMessageHelpDocumentsOptionalTimeDefaults(t *te func TestCrossPlatformCoverageChatReactionHelpKeepsManifestExternalAliasesVisible(t *testing.T) { for _, command := range []string{"add-emoji", "remove-emoji", "add-text-emotion", "remove-text-emotion"} { t.Run(command, func(t *testing.T) { + cmd := newChatCommand() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetErr(&output) cmd.SetArgs([]string{"message", command, "--help"}) if err := cmd.Execute(); err != nil { t.Fatalf("chat message %s --help: %v\n%s", command, err, output.String()) From a5111f486bff48d8fb1cfbe82c7e596225031850 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Thu, 13 Aug 2026 16:13:28 +0800 Subject: [PATCH 092/250] fix(chat): harden openDingTalkId target routing --- .changes/open-dingtalk-id-format-routing.md | 5 + internal/app/param_alias_e2e_test.go | 8 +- .../param_alias_payload_equivalence_test.go | 27 +- internal/helpers/chat.go | 30 +- internal/helpers/chat_coverage_more_test.go | 29 +- internal/helpers/chat_file_path_send_test.go | 8 +- internal/helpers/chat_message_search_test.go | 52 ++-- internal/shortcut/chat/chat.go | 21 +- internal/shortcut/chat/chat_conversation.go | 4 + internal/shortcut/chat/chat_group.go | 3 + internal/shortcut/chat/chat_message.go | 18 ++ .../chat/compatibility_coverage_test.go | 23 +- .../shortcut/chat/coverage_completion_test.go | 32 +- internal/shortcut/chat/gap_fill_test.go | 69 +++-- internal/shortcut/chat/lark_alignment.go | 9 +- internal/shortcut/chat/lark_alignment_test.go | 10 +- .../chat/remaining_read_pagination_test.go | 2 +- internal/shortcut/chat/unified_send.go | 11 + internal/shortcut/smart/chat_messages.go | 270 ++++++++++++++--- internal/shortcut/smart/chat_messages_test.go | 145 ++++++++- .../smart/coverage_completion_test.go | 2 +- .../smart/natural_target_resolution_test.go | 79 ++++- internal/shortcut/smart/search_msg.go | 264 +++++++++++++++-- .../smart/search_msg_execution_test.go | 230 +++++++++++++-- internal/shortcut/targetresolver/resolver.go | 269 +++++++++++++++++ .../shortcut/targetresolver/resolver_test.go | 275 ++++++++++++++++++ test/mock_mcp/mock_mcp_smoke_test.go | 19 +- 27 files changed, 1691 insertions(+), 223 deletions(-) create mode 100644 .changes/open-dingtalk-id-format-routing.md diff --git a/.changes/open-dingtalk-id-format-routing.md b/.changes/open-dingtalk-id-format-routing.md new file mode 100644 index 00000000..10f6f191 --- /dev/null +++ b/.changes/open-dingtalk-id-format-routing.md @@ -0,0 +1,5 @@ +--- +category: Changed +--- + +- **Chat identity routing** — validates explicit `openDingTalkId` inputs and improves name, `userId`, and `openDingTalkId` routing for message shortcuts. diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 25581789..a3eeaf51 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -361,7 +361,7 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) { caller := ¶mAliasCaptureCaller{} ctx, err := executeParamAliasE2E(t, caller, "chat", "message", "send", - "--to-user", "D-recipient", + "--to-user", appFixtureCurrentDOpenID, "--text", "hello alias", "--idempotency-key", "alias-e2e", ) @@ -375,7 +375,7 @@ func TestCrossPlatformCoverageParamAliasWriteCommandFinalPayload(t *testing.T) { t.Fatalf("chat calls = %#v", caller.calls) } payload := caller.calls[0].args - if payload["receiverOpenDingTalkId"] != "D-recipient" || payload["uuid"] != "alias-e2e" || payload["msgType"] != "markdown" { + if payload["receiverOpenDingTalkId"] != appFixtureCurrentDOpenID || payload["uuid"] != "alias-e2e" || payload["msgType"] != "markdown" { t.Fatalf("chat payload identity fields = %#v", payload) } content, _ := payload["content"].(string) @@ -689,11 +689,11 @@ func TestCrossPlatformCoverageSelectedParamAliasesProduceCanonicalEquivalentDryR tool: "send_personal_message", canonicalArgs: []string{ "--dry-run", "chat", "message", "send", - "--user", "D-recipient", "--text", "hello dry-run", "--uuid", "alias-dry-run", + "--user", appFixtureCurrentDOpenID, "--text", "hello dry-run", "--uuid", "alias-dry-run", }, aliasArgs: []string{ "--dry-run", "chat", "message", "send", - "--to-user", "D-recipient", "--text", "hello dry-run", "--uuid", "alias-dry-run", + "--to-user", appFixtureCurrentDOpenID, "--text", "hello dry-run", "--uuid", "alias-dry-run", }, wantCorrections: 1, wantArgKeys: []string{"clawType", "content", "msgType", "receiverOpenDingTalkId", "uuid"}, diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 5d2637c8..ef191e85 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -14,6 +14,11 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline" ) +const ( + appFixtureCurrentDOpenID = "DAAAAAAAAAAAiE" + appFixtureCurrentDOpenID2 = "DAQEBAQEBAQEiE" +) + // paramAliasCompleteCommands is deliberately keyed by the exact reviewed // fixture command path. Every argv is a complete, business-valid invocation: // required companion flags are present, time and enum values are valid, and @@ -34,12 +39,12 @@ var paramAliasCompleteCommands = map[string][]string{ "chat +chat-messages": {"chat", "+chat-messages", "--group", "fixture-conversation"}, "chat +chat-add-bot": {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"}, "chat +chat-audit-join": {"chat", "+chat-audit-join", "--group", "fixture-conversation", "--record-id", "7", "--applicant", "user-1", "--inviter", "user-2", "--status", "AuditApprove", "--yes"}, - "chat +chat-members-get": {"chat", "+chat-members-get", "--id", "fixture-conversation", "--users", "D-user-1,D-user-2"}, + "chat +chat-members-get": {"chat", "+chat-members-get", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2}, "chat +chat-members-list": {"chat", "+chat-members-list", "--conversation-id", "fixture-conversation", "--member-types", "user,bot"}, - "chat +chat-mute-member": {"chat", "+chat-mute-member", "--group", "fixture-conversation", "--users", "D-user-1,D-user-2", "--mute-time", "3600000", "--yes"}, + "chat +chat-mute-member": {"chat", "+chat-mute-member", "--group", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2, "--mute-time", "3600000", "--yes"}, "chat +chat-remove-bot": {"chat", "+chat-remove-bot", "--id", "fixture-conversation", "--bot-id", "bot-1", "--yes"}, - "chat +chat-role-remove-user": {"chat", "+chat-role-remove-user", "--group", "fixture-conversation", "--user", "D-user-1", "--role-ids", "role-1", "--yes"}, - "chat +chat-transfer-owner": {"chat", "+chat-transfer-owner", "--group", "fixture-conversation", "--new-owner", "D-user-1", "--yes"}, + "chat +chat-role-remove-user": {"chat", "+chat-role-remove-user", "--group", "fixture-conversation", "--user", appFixtureCurrentDOpenID, "--role-ids", "role-1", "--yes"}, + "chat +chat-transfer-owner": {"chat", "+chat-transfer-owner", "--group", "fixture-conversation", "--new-owner", appFixtureCurrentDOpenID, "--yes"}, "chat +chat-update": {"chat", "+chat-update", "--group", "fixture-conversation", "--name", "Fixture Renamed Group", "--yes"}, "chat +bot-find": {"chat", "+bot-find", "--query", "fixture", "--limit", "7"}, "chat +bot-search": {"chat", "+bot-search", "--name", "Fixture Bot", "--page", "2", "--size", "7"}, @@ -57,7 +62,7 @@ var paramAliasCompleteCommands = map[string][]string{ "chat +messages-list": {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"}, "chat +messages-list-direct": {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"}, "chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"}, - "chat +messages-reply": {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"}, + "chat +messages-reply": {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"}, "chat +messages-resource-download": {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"}, "chat +messages-set-pin": {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"}, "chat +messages-send-by-webhook": {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"}, @@ -70,10 +75,10 @@ var paramAliasCompleteCommands = map[string][]string{ "chat category create-smart": {"chat", "category", "create-smart", "--name", "Fixture Smart Category", "--keywords", "fixture,priority", "--yes"}, "chat category rename": {"chat", "category", "rename", "--category-id", "7", "--title", "Renamed Cat", "--yes"}, "chat group members": {"chat", "group", "members", "--id", "fixture-conversation"}, - "chat group members add": {"chat", "group", "members", "add", "--id", "fixture-conversation", "--users", "D-user-1"}, + "chat group members add": {"chat", "group", "members", "add", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID}, "chat group members add-bot": {"chat", "group", "members", "add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"}, - "chat group members list-by-ids": {"chat", "group", "members", "list-by-ids", "--id", "fixture-conversation", "--users", "D-user-1,D-user-2"}, - "chat group members remove": {"chat", "group", "members", "remove", "--id", "fixture-conversation", "--users", "D-user-1", "--yes"}, + "chat group members list-by-ids": {"chat", "group", "members", "list-by-ids", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID + "," + appFixtureCurrentDOpenID2}, + "chat group members remove": {"chat", "group", "members", "remove", "--id", "fixture-conversation", "--users", appFixtureCurrentDOpenID, "--yes"}, "chat group members remove-bot": {"chat", "group", "members", "remove-bot", "--id", "fixture-conversation", "--bot-id", "bot-1", "--yes"}, "chat group rename": {"chat", "group", "rename", "--id", "fixture-conversation", "--name", "Fixture Renamed Group", "--yes"}, "chat group set-admin": {"chat", "group", "set-admin", "--group", "fixture-conversation", "--user", "user-1", "--yes"}, @@ -88,9 +93,9 @@ var paramAliasCompleteCommands = map[string][]string{ "chat message list-by-ids": {"chat", "message", "list-by-ids", "--msg-ids", "message-1,message-2"}, "chat message list-unread-conversations": {"chat", "message", "list-unread-conversations", "--count", "7", "--exclude-muted"}, "chat message recall": {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"}, - "chat message reply": {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", "D-sender", "--text", "hello fixture", "--yes"}, + "chat message reply": {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"}, "chat message search-advanced": {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"}, - "chat message send": {"chat", "message", "send", "--user", "D-recipient", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"}, + "chat message send": {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"}, "chat message send-by-bot": {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"}, "chat message send-by-webhook": {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"}, "contact +dept-members": {"contact", "+dept-members", "--dept", "Fixture Dept"}, @@ -211,7 +216,7 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ "user": {"chat", "message", "list", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"}, }, "chat message list-by-sender": { - "sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", "D-sender", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"}, + "sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", appFixtureCurrentDOpenID, "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"}, }, "chat message send": { "group": {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"}, diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index f36dd104..bba9e26c 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -520,6 +520,11 @@ func chatMessageListBySenderArgs(cmd *cobra.Command) (map[string]any, error) { if senderUserID == "" && senderOpenDingTalkID == "" { return nil, fmt.Errorf("--sender-user-id or --sender-open-dingtalk-id is required") } + if senderOpenDingTalkID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--sender-open-dingtalk-id", senderOpenDingTalkID); err != nil { + return nil, err + } + } startRaw, endRaw, err := defaultChatMessageTimeRange(cmd, 7*24*time.Hour) if err != nil { return nil, err @@ -1051,8 +1056,7 @@ func isNumericUserID(value string) bool { } func isOpenDingTalkID(value string) bool { - value = strings.TrimSpace(value) - return len(value) > 0 && (value[0] == 'D' || value[0] == 'd') + return targetresolver.LooksLikeCurrentDOpenDingTalkID(value) } // webhookErrcodeFailure 解析自定义机器人 webhook 的响应，判定是否发送失败。 @@ -2692,6 +2696,11 @@ func newChatCommand() *cobra.Command { if specified == 0 { return fmt.Errorf("--group, --user or --open-dingtalk-id is required") } + if openDingTalkID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil { + return err + } + } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID userID = "" @@ -2784,6 +2793,11 @@ func newChatCommand() *cobra.Command { if userID == "" && openDingTalkID == "" { return fmt.Errorf("--user or --open-dingtalk-id is required") } + if openDingTalkID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil { + return err + } + } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID userID = "" @@ -2913,6 +2927,11 @@ func newChatCommand() *cobra.Command { if specified == 0 { return fmt.Errorf("--group, --user or --open-dingtalk-id is required") } + if openDingTalkID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil { + return err + } + } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID userID = "" @@ -4726,9 +4745,10 @@ chat message edit 或 chat message recall 的 --msg-id 和 --conversation-id。 userID := rawUserID openDingTalkID := rawOpenDingTalkID - if openDingTalkID != "" && !isOpenDingTalkID(openDingTalkID) { - userID = openDingTalkID - openDingTalkID = "" + if openDingTalkID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openDingTalkID); err != nil { + return err + } } if userID != "" && isOpenDingTalkID(userID) { openDingTalkID = userID diff --git a/internal/helpers/chat_coverage_more_test.go b/internal/helpers/chat_coverage_more_test.go index 55510c88..3c9f1ad0 100644 --- a/internal/helpers/chat_coverage_more_test.go +++ b/internal/helpers/chat_coverage_more_test.go @@ -14,6 +14,11 @@ import ( "github.com/spf13/cobra" ) +const ( + helperCurrentDOpenID = "DAAAAAAAAAAAiE" + helperCurrentDOpenID2 = "DAQEBAQEBAQEiE" +) + func newChatFlagTestCommand() *cobra.Command { cmd := &cobra.Command{Use: "chat"} cmd.Flags().String("forward", "", "") @@ -37,6 +42,22 @@ func newChatFlagTestCommand() *cobra.Command { return cmd } +func TestNativeChatIDSplitUsesCurrentDFormat(t *testing.T) { + userIDs, openIDs := splitChatIDValues([]string{ + helperCurrentDOpenID, + "D-prefix-fixture-user", + "d-prefix-fixture-user", + "D-invalid", + "fixture-user-id", + }) + if len(openIDs) != 1 || openIDs[0] != helperCurrentDOpenID { + t.Fatalf("open IDs=%#v", openIDs) + } + if got := strings.Join(userIDs, ","); got != "D-prefix-fixture-user,d-prefix-fixture-user,D-invalid,fixture-user-id" { + t.Fatalf("user IDs=%#v", userIDs) + } +} + func TestCrossPlatformCoverageChatDirectionAndScalarCoverage(t *testing.T) { search := &cobra.Command{Use: "search"} search.Flags().String("nicks", "", "") @@ -151,18 +172,18 @@ func TestCrossPlatformCoverageChatContactMappingCoverage(t *testing.T) { } func TestCrossPlatformCoverageResolveOpenDingTalkIDsCoverage(t *testing.T) { - if id, err := resolveOpenDingTalkID(context.Background(), "D-direct"); err != nil || id != "D-direct" { + if id, err := resolveOpenDingTalkID(context.Background(), helperCurrentDOpenID); err != nil || id != helperCurrentDOpenID { t.Fatalf("direct ID = %q, %v", id, err) } if _, err := resolveOpenDingTalkID(context.Background(), ""); err == nil { t.Fatal("empty ID unexpectedly resolved") } - if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{" D1 ", ""}); err != nil || ids[0] != "D1" { + if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{" " + helperCurrentDOpenID + " ", ""}); err != nil || ids[0] != helperCurrentDOpenID { t.Fatalf("direct IDs = %#v, %v", ids, err) } - caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"D1"}]}`}}} + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[{"userId":"u1","openDingTalkId":"` + helperCurrentDOpenID2 + `"}]}`}}} installScriptedCaller(t, caller) - if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{"u1", "u1"}); err != nil || ids[1] != "D1" { + if ids, err := resolveOpenDingTalkIDs(context.Background(), []string{"u1", "u1"}); err != nil || ids[1] != helperCurrentDOpenID2 { t.Fatalf("resolved IDs = %#v, %v", ids, err) } caller.steps = []scriptedToolStep{{text: `{}`}, {text: `{}`}} diff --git a/internal/helpers/chat_file_path_send_test.go b/internal/helpers/chat_file_path_send_test.go index 005940e7..b828a35d 100644 --- a/internal/helpers/chat_file_path_send_test.go +++ b/internal/helpers/chat_file_path_send_test.go @@ -178,7 +178,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) { caller := &chatFilePathCaller{} commandArgs := []string{ "message", "send", - "--open-dingtalk-id=D-target", + "--open-dingtalk-id=" + helperCurrentDOpenID, "--msg-type=file", "--file-path=" + filePath, } @@ -203,7 +203,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) { server: "im", tool: "init_conversation_file_upload", args: map[string]any{ - "openDingTalkId": "D-target", + "openDingTalkId": helperCurrentDOpenID, "fileName": "report.pdf", "fileSize": int64(len(payload)), "md5": fileMD5, @@ -216,7 +216,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) { server: "im", tool: "commit_conversation_file_upload", args: map[string]any{ - "openDingTalkId": "D-target", + "openDingTalkId": helperCurrentDOpenID, "uploadKey": "upload-key", "fileName": "report.pdf", "fileSize": int64(len(payload)), @@ -231,7 +231,7 @@ func TestChatMessageSendFilePathUsesOpenDingTalkIDTarget(t *testing.T) { if send.server != "chat" || send.tool != "send_personal_message" || send.args["msgType"] != "file" { t.Fatalf("send direct target call = %#v", send) } - if send.args["receiverOpenDingTalkId"] != "D-target" { + if send.args["receiverOpenDingTalkId"] != helperCurrentDOpenID { t.Fatalf("send direct target = %#v", send.args) } if _, ok := send.args["openDingTalkId"]; ok { diff --git a/internal/helpers/chat_message_search_test.go b/internal/helpers/chat_message_search_test.go index bdf1da88..c0bcc370 100644 --- a/internal/helpers/chat_message_search_test.go +++ b/internal/helpers/chat_message_search_test.go @@ -879,11 +879,11 @@ func TestChatSendAndReplyDefaultToAgentProductForIMClawType(t *testing.T) { }{ { name: "send", - args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello"}, + args: []string{"message", "send", "--open-dingtalk-id", helperCurrentDOpenID, "--text", "hello"}, }, { name: "reply", - args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello"}, + args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--text", "hello"}, }, } @@ -912,11 +912,11 @@ func TestChatSendAndReplyDisableAITagWithEmptyClawType(t *testing.T) { }{ { name: "send", - args: []string{"message", "send", "--open-dingtalk-id", "D1", "--text", "hello", "--ai-tag=false"}, + args: []string{"message", "send", "--open-dingtalk-id", helperCurrentDOpenID, "--text", "hello", "--ai-tag=false"}, }, { name: "reply", - args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", "D1", "--text", "hello", "--ai-tag=false"}, + args: []string{"message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--text", "hello", "--ai-tag=false"}, }, } @@ -950,25 +950,25 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) name: "send", args: []string{ "message", "send", "--group", "cid", - "--text", "收到 @D-target 和 <@D-second>", - "--at-open-dingtalk-ids", "D-target,D-second", + "--text", "收到 @" + helperCurrentDOpenID + " 和 <@" + helperCurrentDOpenID2 + ">", + "--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2, "--at-all", }, contentField: "text", - wantContent: "<@all> 收到 <@D-target> 和 <@D-second>", + wantContent: "<@all> 收到 <@" + helperCurrentDOpenID + "> 和 <@" + helperCurrentDOpenID2 + ">", wantAtAll: true, - wantOpenIDs: []string{"D-target", "D-second"}, + wantOpenIDs: []string{helperCurrentDOpenID, helperCurrentDOpenID2}, }, { name: "send keeps missing member placeholders unchanged", args: []string{ "message", "send", "--group", "cid", "--text", "DWS 发消息自测", - "--at-open-dingtalk-ids", "D-target", + "--at-open-dingtalk-ids", helperCurrentDOpenID, }, contentField: "text", wantContent: "DWS 发消息自测", - wantOpenIDs: []string{"D-target"}, + wantOpenIDs: []string{helperCurrentDOpenID}, }, { name: "reply", @@ -976,15 +976,15 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) "message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", - "--ref-sender", "D-sender", - "--text", "收到 @D-target 和 <@D-second>", - "--at-open-dingtalk-ids", "D-target,D-second", + "--ref-sender", helperCurrentDOpenID, + "--text", "收到 @" + helperCurrentDOpenID + " 和 <@" + helperCurrentDOpenID2 + ">", + "--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2, "--at-all", }, contentField: "content", - wantContent: "<@all> 收到 <@D-target> 和 <@D-second>", + wantContent: "<@all> 收到 <@" + helperCurrentDOpenID + "> 和 <@" + helperCurrentDOpenID2 + ">", wantAtAll: true, - wantOpenIDs: []string{"D-target", "D-second"}, + wantOpenIDs: []string{helperCurrentDOpenID, helperCurrentDOpenID2}, }, { name: "reply adds missing member placeholders", @@ -992,13 +992,13 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) "message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", - "--ref-sender", "D-sender", - "--text", "DWS 回复艾特前津（非主用）自测", - "--at-open-dingtalk-ids", "D-target,D-second,D-target", + "--ref-sender", helperCurrentDOpenID, + "--text", "DWS synthetic reply mention test", + "--at-open-dingtalk-ids", helperCurrentDOpenID + "," + helperCurrentDOpenID2 + "," + helperCurrentDOpenID, }, contentField: "content", - wantContent: "<@D-target> <@D-second> DWS 回复艾特前津（非主用）自测", - wantOpenIDs: []string{"D-target", "D-second", "D-target"}, + wantContent: "<@" + helperCurrentDOpenID + "> <@" + helperCurrentDOpenID2 + "> DWS synthetic reply mention test", + wantOpenIDs: []string{helperCurrentDOpenID, helperCurrentDOpenID2, helperCurrentDOpenID}, }, { name: "reply adds missing member placeholders after at-all", @@ -1006,15 +1006,15 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) "message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", - "--ref-sender", "D-sender", + "--ref-sender", helperCurrentDOpenID, "--text", "请大家确认", - "--at-open-dingtalk-ids", "D-target", + "--at-open-dingtalk-ids", helperCurrentDOpenID, "--at-all", }, contentField: "content", - wantContent: "<@all> <@D-target> 请大家确认", + wantContent: "<@all> <@" + helperCurrentDOpenID + "> 请大家确认", wantAtAll: true, - wantOpenIDs: []string{"D-target"}, + wantOpenIDs: []string{helperCurrentDOpenID}, }, { name: "reply at-all preserves alliance word", @@ -1022,7 +1022,7 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) "message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", - "--ref-sender", "D-sender", + "--ref-sender", helperCurrentDOpenID, "--text", "联系 @alliance", "--at-all", }, @@ -1036,7 +1036,7 @@ func TestCrossPlatformCoverageChatCurrentUserSendAndReplyMentions(t *testing.T) "message", "reply", "--conversation-id", "cid", "--ref-msg-id", "mid", - "--ref-sender", "D-sender", + "--ref-sender", helperCurrentDOpenID, "--text", "联系 @alliance", }, contentField: "content", diff --git a/internal/shortcut/chat/chat.go b/internal/shortcut/chat/chat.go index 148a7f38..4a0ed222 100644 --- a/internal/shortcut/chat/chat.go +++ b/internal/shortcut/chat/chat.go @@ -24,13 +24,14 @@ import ( "fmt" "strconv" "strings" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" ) -// isOpenID reports whether value looks like an openDingTalkId (starts with D/d), -// mirroring helpers.isOpenDingTalkID. +// isOpenID classifies mixed userId/openDingTalkId inputs using the canonical +// current-D wire format shared with helpers and smart shortcuts. func isOpenID(v string) bool { - v = strings.TrimSpace(v) - return len(v) > 0 && (v[0] == 'D' || v[0] == 'd') + return targetresolver.LooksLikeCurrentDOpenDingTalkID(v) } // splitIDs partitions a mixed list of userId / openDingTalkId values, mirroring @@ -50,6 +51,18 @@ func splitIDs(vals []string) (userIDs, openIDs []string) { return userIDs, openIDs } +func validateExplicitOpenIDs(flagName string, values []string) error { + for _, value := range values { + if strings.TrimSpace(value) == "" { + continue + } + if err := targetresolver.ValidateExplicitOpenDingTalkID(flagName, value); err != nil { + return err + } + } + return nil +} + // toInt64Slice converts string values to []int64, mirroring helpers.parseCSVInt64. func toInt64Slice(vals []string) ([]int64, error) { out := make([]int64, 0, len(vals)) diff --git a/internal/shortcut/chat/chat_conversation.go b/internal/shortcut/chat/chat_conversation.go index a575f9a2..a5e83752 100644 --- a/internal/shortcut/chat/chat_conversation.go +++ b/internal/shortcut/chat/chat_conversation.go @@ -25,6 +25,7 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" ) // ConversationInfo gets conversation info (get_conversation_info, chat server). @@ -71,6 +72,9 @@ var ConversationInfo = shortcut.Shortcut{ params["openConversationId"] = rt.Str("group") } if rt.Str("open-dingtalk-id") != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", rt.Str("open-dingtalk-id")); err != nil { + return err + } params["openDingTalkId"] = rt.Str("open-dingtalk-id") } if len(params) == 0 { diff --git a/internal/shortcut/chat/chat_group.go b/internal/shortcut/chat/chat_group.go index d9b5d31c..a959874e 100644 --- a/internal/shortcut/chat/chat_group.go +++ b/internal/shortcut/chat/chat_group.go @@ -409,6 +409,9 @@ var ChatMembersGet = shortcut.Shortcut{ }, Tips: []string{`dws chat +chat-members-get --id --users odid1,odid2`}, Execute: func(rt *shortcut.RuntimeContext) error { + if err := validateExplicitOpenIDs("--users", rt.StrSlice("users")); err != nil { + return err + } return rt.CallMCP("list_group_member_by_ids", map[string]any{ "openConversationId": rt.Str("id"), "cid": rt.Str("id"), diff --git a/internal/shortcut/chat/chat_message.go b/internal/shortcut/chat/chat_message.go index 536686e6..553b604c 100644 --- a/internal/shortcut/chat/chat_message.go +++ b/internal/shortcut/chat/chat_message.go @@ -29,6 +29,7 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" ) const directMessagesHardPageLimit = 500 @@ -55,6 +56,9 @@ var MessagesSendByBot = shortcut.Shortcut{ }, Tips: []string{`dws chat +messages-send-by-bot --robot-code --group --title "日报" --text "## 今日完成"`}, Execute: func(rt *shortcut.RuntimeContext) error { + if err := validateExplicitOpenIDs("--at-open-dingtalk-ids", rt.StrSlice("at-open-dingtalk-ids")); err != nil { + return err + } params := map[string]any{ "robotCode": rt.Str("robot-code"), "openConversationId": rt.Str("group"), @@ -93,6 +97,9 @@ var MessagesBatchSendByBot = shortcut.Shortcut{ }, Tips: []string{`dws chat +messages-batch-send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报"`}, Execute: func(rt *shortcut.RuntimeContext) error { + if err := validateExplicitOpenIDs("--open-dingtalk-ids", rt.StrSlice("open-dingtalk-ids")); err != nil { + return err + } params := map[string]any{ "robotCode": rt.Str("robot-code"), "title": rt.Str("title"), @@ -493,6 +500,9 @@ func executeMessagesListDirect(rt *shortcut.RuntimeContext) error { } switch { case rt.Str("open-dingtalk-id") != "": + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", rt.Str("open-dingtalk-id")); err != nil { + return err + } params["openDingTalkId"] = rt.Str("open-dingtalk-id") case rt.Str("user") != "": params["userId"] = rt.Str("user") @@ -1515,6 +1525,14 @@ var MessagesSendCard = shortcut.Shortcut{ `dws chat +messages-send-card --group --at-open-dingtalk-ids --content "任务已完成"`, }, Validate: func(rt *shortcut.RuntimeContext) error { + if receiverOpenID := rt.Str("receiver-open-dingtalk-id"); receiverOpenID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--receiver-open-dingtalk-id", receiverOpenID); err != nil { + return err + } + } + if err := validateExplicitOpenIDs("--at-open-dingtalk-ids", rt.StrSlice("at-open-dingtalk-ids")); err != nil { + return err + } if status := rt.Int("flow-status"); !validCardFlowStatus(status) { return fmt.Errorf("--flow-status 必须在 1-5 之间") } diff --git a/internal/shortcut/chat/compatibility_coverage_test.go b/internal/shortcut/chat/compatibility_coverage_test.go index 82b3defd..43d94d8d 100644 --- a/internal/shortcut/chat/compatibility_coverage_test.go +++ b/internal/shortcut/chat/compatibility_coverage_test.go @@ -26,6 +26,11 @@ import ( "github.com/spf13/cobra" ) +const ( + fixtureCurrentDOpenID = "DAAAAAAAAAAAiE" + fixtureCurrentDOpenID2 = "DAQEBAQEBAQEiE" +) + type platformCoverageCaller struct { product string tool string @@ -53,7 +58,7 @@ func (f *muteMemberResolutionCaller) CallTool(_ context.Context, product, tool s case "contact/get_user_info_by_user_ids": text = `{"result":[{"orgEmployeeModel":{"orgUserId":"user-2","orgUserName":"测试成员"}}]}` case "chat/get_group_members": - text = `{"result":{"hasMore":false,"list":[{"memberEmpName":"测试成员","openDingtalkId":"D-open-2"}]}}` + text = `{"result":{"hasMore":false,"list":[{"memberEmpName":"测试成员","openDingtalkId":"` + fixtureCurrentDOpenID2 + `"}]}}` case "im/set_group_member_mute_list": text = `{"success":true}` default: @@ -235,8 +240,10 @@ func TestCrossPlatformCoverageChatIDHelpers(t *testing.T) { value string want bool }{ - {value: "DingTalk-open-id", want: true}, - {value: " dingtalk-open-id ", want: true}, + {value: "DAAAAAAAAAAAiE", want: true}, + {value: " DAAAAAAAAAAAiE ", want: true}, + {value: "D-prefix-fixture-user", want: false}, + {value: "d-prefix-fixture-user", want: false}, {value: "user-id", want: false}, {value: " ", want: false}, } @@ -248,11 +255,11 @@ func TestCrossPlatformCoverageChatIDHelpers(t *testing.T) { }) t.Run("split mixed IDs", func(t *testing.T) { - userIDs, openIDs := splitIDs([]string{" user-1 ", "", "D-open-1", "d-open-2", "user-2"}) - if want := []string{"user-1", "user-2"}; !reflect.DeepEqual(userIDs, want) { + userIDs, openIDs := splitIDs([]string{" user-1 ", "", "DAAAAAAAAAAAiE", "d-open-2", "D-prefix-fixture-user", "user-2"}) + if want := []string{"user-1", "d-open-2", "D-prefix-fixture-user", "user-2"}; !reflect.DeepEqual(userIDs, want) { t.Fatalf("user IDs = %#v, want %#v", userIDs, want) } - if want := []string{"D-open-1", "d-open-2"}; !reflect.DeepEqual(openIDs, want) { + if want := []string{"DAAAAAAAAAAAiE"}; !reflect.DeepEqual(openIDs, want) { t.Fatalf("open IDs = %#v, want %#v", openIDs, want) } }) @@ -281,7 +288,7 @@ func TestCrossPlatformCoverageChatMuteMemberResolvesUserIDToOpenDingTalkID(t *te root.SetArgs([]string{ "chat", "+chat-mute-member", "--group", "cid-1", - "--users", "user-2,D-open-2", + "--users", "user-2," + fixtureCurrentDOpenID2, "--mute-time", "300000", "--yes", }) @@ -298,7 +305,7 @@ func TestCrossPlatformCoverageChatMuteMemberResolvesUserIDToOpenDingTalkID(t *te if _, ok := final.args["uids"]; ok { t.Fatalf("known-broken uids argument leaked into final call: %#v", final.args) } - if got, want := final.args["openDingTalkIds"], []string{"D-open-2"}; !reflect.DeepEqual(got, want) { + if got, want := final.args["openDingTalkIds"], []string{fixtureCurrentDOpenID2}; !reflect.DeepEqual(got, want) { t.Fatalf("openDingTalkIds = %#v, want %#v", got, want) } } diff --git a/internal/shortcut/chat/coverage_completion_test.go b/internal/shortcut/chat/coverage_completion_test.go index 98d5cb1a..0bdbe1ab 100644 --- a/internal/shortcut/chat/coverage_completion_test.go +++ b/internal/shortcut/chat/coverage_completion_test.go @@ -225,7 +225,7 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) { { name: "reply write", caller: &larkAlignmentCaller{failProductTool: "chat/send_personal_message"}, - args: []string{"chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", "--ref-sender", "D-sender", "--text", "收到", "--yes"}, + args: []string{"chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", "--ref-sender", fixtureCurrentDOpenID, "--text", "收到", "--yes"}, wantError: "fixture lower call failed", }, } @@ -259,7 +259,7 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) { }} helpers.InitDeps(external) root = newPlatformCoverageRoot() - root.SetArgs([]string{"chat", "+chat-create", "--name", "群", "--owner-open-dingtalk-id", "D-owner", "--member-query", "外部联系人", "--yes"}) + root.SetArgs([]string{"chat", "+chat-create", "--name", "群", "--owner-open-dingtalk-id", fixtureCurrentDOpenID, "--member-query", "外部联系人", "--yes"}) if err := root.Execute(); err != nil { t.Fatal(err) } @@ -400,17 +400,17 @@ func TestCrossPlatformCoverageUnifiedSendValidationMatrix(t *testing.T) { cases := [][]string{ {"--identity", "user", "--group", "cid", "--users", "u1", "--text", "x"}, {"--identity", "user", "--text", "x"}, - {"--identity", "user", "--group", "cid", "--open-dingtalk-id", "D1", "--text", "x"}, + {"--identity", "user", "--group", "cid", "--open-dingtalk-id", fixtureCurrentDOpenID, "--text", "x"}, {"--identity", "user", "--group", "cid", "--at-user-ids", "u1", "--text", "x"}, - {"--identity", "user", "--open-dingtalk-id", "D1", "--at-all", "--text", "x"}, + {"--identity", "user", "--open-dingtalk-id", fixtureCurrentDOpenID, "--at-all", "--text", "x"}, {"--identity", "bot", "--group", "cid", "--text", "x"}, {"--identity", "bot", "--robot-code", "r", "--group", "cid", "--users", "u1", "--text", "x"}, - {"--identity", "bot", "--robot-code", "r", "--group", "cid", "--open-dingtalk-id", "D1", "--text", "x"}, + {"--identity", "bot", "--robot-code", "r", "--group", "cid", "--open-dingtalk-id", fixtureCurrentDOpenID, "--text", "x"}, {"--identity", "bot", "--robot-code", "r", "--group", "cid", "--at-mobiles", "13800000000", "--text", "x"}, {"--identity", "bot", "--robot-code", "r", "--users", "u1", "--at-user-ids", "u2", "--text", "x"}, {"--identity", "webhook", "--text", "x"}, {"--identity", "webhook", "--webhook-token", "token", "--group", "cid", "--text", "x"}, - {"--identity", "webhook", "--webhook-token", "token", "--at-open-dingtalk-ids", "D1", "--text", "x"}, + {"--identity", "webhook", "--webhook-token", "token", "--at-open-dingtalk-ids", fixtureCurrentDOpenID, "--text", "x"}, {"--identity", "webhook", "--webhook-token", "token", "--uuid", "key", "--text", "x"}, } for _, tail := range cases { @@ -437,23 +437,23 @@ func TestCrossPlatformCoverageUnifiedSendOptionalArgumentsAndErrors(t *testing.T }{ { name: "user group mentions", - args: []string{"--identity", "user", "--group", "cid", "--text", "x", "--at-open-dingtalk-ids", "D1,D2", "--at-all"}, - want: map[string]any{"atOpenDingTalkIds": []string{"D1", "D2"}, "atAll": true}, + args: []string{"--identity", "user", "--group", "cid", "--text", "x", "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2, "--at-all"}, + want: map[string]any{"atOpenDingTalkIds": []string{fixtureCurrentDOpenID, fixtureCurrentDOpenID2}, "atAll": true}, }, { name: "user direct", - args: []string{"--identity", "user", "--open-dingtalk-id", "D1", "--text", "x"}, - want: map[string]any{"receiverOpenDingTalkId": "D1"}, + args: []string{"--identity", "user", "--open-dingtalk-id", fixtureCurrentDOpenID, "--text", "x"}, + want: map[string]any{"receiverOpenDingTalkId": fixtureCurrentDOpenID}, }, { name: "bot group mentions", - args: []string{"--identity", "bot", "--robot-code", "r", "--group", "cid", "--text", "x", "--at-user-ids", "u1", "--at-open-dingtalk-ids", "D1"}, - want: map[string]any{"atUserIds": []string{"u1"}, "atOpendingtalkIds": []string{"D1"}}, + args: []string{"--identity", "bot", "--robot-code", "r", "--group", "cid", "--text", "x", "--at-user-ids", "u1", "--at-open-dingtalk-ids", fixtureCurrentDOpenID}, + want: map[string]any{"atUserIds": []string{"u1"}, "atOpendingtalkIds": []string{fixtureCurrentDOpenID}}, }, { name: "bot direct targets", - args: []string{"--identity", "bot", "--robot-code", "r", "--users", "u1", "--open-dingtalk-ids", "D1", "--text", "x", "--at-all"}, - want: map[string]any{"userIds": []string{"u1"}, "openDingtalkIds": []string{"D1"}, "isAtAll": "true"}, + args: []string{"--identity", "bot", "--robot-code", "r", "--users", "u1", "--open-dingtalk-ids", fixtureCurrentDOpenID, "--text", "x", "--at-all"}, + want: map[string]any{"userIds": []string{"u1"}, "openDingtalkIds": []string{fixtureCurrentDOpenID}, "isAtAll": "true"}, }, { name: "webhook mentions", @@ -580,7 +580,7 @@ func TestCrossPlatformCoverageUnifiedSendGroupFileAndBatchBoundaries(t *testing. root.SetArgs([]string{ "chat", "+messages-send", "--identity", "bot", "--robot-code", "r", "--groups", "c1,c2", "--text", "x", "--at-user-ids", "u1", - "--at-open-dingtalk-ids", "D1", "--at-all", "--yes", + "--at-open-dingtalk-ids", fixtureCurrentDOpenID, "--at-all", "--yes", }) if err := root.Execute(); err != nil { t.Fatal(err) @@ -590,7 +590,7 @@ func TestCrossPlatformCoverageUnifiedSendGroupFileAndBatchBoundaries(t *testing. } for _, call := range fake.calls { if !reflect.DeepEqual(call.args["atUserIds"], []string{"u1"}) || - !reflect.DeepEqual(call.args["atOpendingtalkIds"], []string{"D1"}) || + !reflect.DeepEqual(call.args["atOpendingtalkIds"], []string{fixtureCurrentDOpenID}) || call.args["isAtAll"] != "true" { t.Fatalf("batch mention args = %#v", call.args) } diff --git a/internal/shortcut/chat/gap_fill_test.go b/internal/shortcut/chat/gap_fill_test.go index ad2d428f..7cd22e11 100644 --- a/internal/shortcut/chat/gap_fill_test.go +++ b/internal/shortcut/chat/gap_fill_test.go @@ -417,8 +417,8 @@ func TestCrossPlatformCoverageChatCreateExplicitOwnerSkipsCurrentProfileAndDedup root := newPlatformCoverageRoot() root.SetOut(&bytes.Buffer{}) root.SetArgs([]string{ - "chat", "+chat-create", "--name", "测试群", "--users", "D-owner,user-1", - "--owner-open-dingtalk-id", "D-owner", "--yes", + "chat", "+chat-create", "--name", "测试群", "--users", fixtureCurrentDOpenID + ",user-1", + "--owner-open-dingtalk-id", fixtureCurrentDOpenID, "--yes", }) if err := root.Execute(); err != nil { t.Fatal(err) @@ -427,24 +427,24 @@ func TestCrossPlatformCoverageChatCreateExplicitOwnerSkipsCurrentProfileAndDedup t.Fatalf("explicit owner calls = %#v", fake.calls) } create := fake.calls[0].args - if create["ownerOpenDingTalkId"] != "D-owner" { + if create["ownerOpenDingTalkId"] != fixtureCurrentDOpenID { t.Fatalf("ownerOpenDingTalkId = %#v", create["ownerOpenDingTalkId"]) } - if got, want := create["groupMembers"], []string{"D-owner", "user-1"}; !reflect.DeepEqual(got, want) { + if got, want := create["groupMembers"], []string{fixtureCurrentDOpenID, "user-1"}; !reflect.DeepEqual(got, want) { t.Fatalf("groupMembers = %#v, want %#v", got, want) } } func TestCrossPlatformCoverageChatCreateOwnerQueryResolvesBeforeSingleCreate(t *testing.T) { fake := &larkAlignmentCaller{responses: map[string]string{ - "contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"owner-user","openDingTalkId":"D-owner"}]}`, + "contact/search_contact_by_key_word": `{"result":[{"name":"测试用户甲","userId":"owner-user","openDingTalkId":"` + fixtureCurrentDOpenID + `"}]}`, }} helpers.InitDeps(fake) root := newPlatformCoverageRoot() root.SetOut(&bytes.Buffer{}) root.SetArgs([]string{ "chat", "+chat-create", "--name", "测试群", "--users", "user-1", - "--owner-query", "张三", "--yes", + "--owner-query", "测试用户甲", "--yes", }) if err := root.Execute(); err != nil { t.Fatal(err) @@ -454,10 +454,10 @@ func TestCrossPlatformCoverageChatCreateOwnerQueryResolvesBeforeSingleCreate(t * t.Fatalf("owner query calls = %#v", fake.calls) } create := fake.calls[1].args - if create["ownerOpenDingTalkId"] != "D-owner" { + if create["ownerOpenDingTalkId"] != fixtureCurrentDOpenID { t.Fatalf("ownerOpenDingTalkId = %#v", create["ownerOpenDingTalkId"]) } - if got, want := create["groupMembers"], []string{"D-owner", "user-1"}; !reflect.DeepEqual(got, want) { + if got, want := create["groupMembers"], []string{fixtureCurrentDOpenID, "user-1"}; !reflect.DeepEqual(got, want) { t.Fatalf("groupMembers = %#v, want %#v", got, want) } } @@ -601,7 +601,7 @@ func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileDryRunAndFailures( root.SetOut(&output) root.SetArgs([]string{ "chat", "+messages-send", - "--open-dingtalk-id", "D-target", + "--open-dingtalk-id", fixtureCurrentDOpenID, "--file", "./fixture.bin", "--dry-run", "--yes", @@ -773,7 +773,7 @@ func TestCrossPlatformCoverageMessagesSendCardOneCallLifecycle(t *testing.T) { root.SetArgs([]string{ "chat", "+messages-send-card", "--group", "cid", - "--at-open-dingtalk-ids", "D-one,D-two,D-one", + "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2 + "," + fixtureCurrentDOpenID, "--at-all", "--content", "完成", "--flow-status", "3", @@ -786,7 +786,7 @@ func TestCrossPlatformCoverageMessagesSendCardOneCallLifecycle(t *testing.T) { fake.calls[1].tool != "update_streaming_card" { t.Fatalf("card calls = %#v", fake.calls) } - if got, want := fake.calls[0].args["atOpenDingTalkIds"], []string{"D-one", "D-two"}; !reflect.DeepEqual(got, want) { + if got, want := fake.calls[0].args["atOpenDingTalkIds"], []string{fixtureCurrentDOpenID, fixtureCurrentDOpenID2}; !reflect.DeepEqual(got, want) { t.Fatalf("card create atOpenDingTalkIds = %#v, want %#v", got, want) } if fake.calls[0].args["atAll"] != true { @@ -842,7 +842,7 @@ func TestCrossPlatformCoverageMessagesSendCardRejectsMissingRequestedAtTag(t *te root.SetArgs([]string{ "chat", "+messages-send-card", "--group", "cid", - "--at-open-dingtalk-ids", "D-mentioned", + "--at-open-dingtalk-ids", fixtureCurrentDOpenID, "--content", "正文", "--yes", }) @@ -891,7 +891,7 @@ func TestCrossPlatformCoverageMessagesSendCardUsesExplicitOpenReceiver(t *testin root := newPlatformCoverageRoot() root.SetArgs([]string{ "chat", "+messages-send-card", - "--receiver-open-dingtalk-id", "D-direct", + "--receiver-open-dingtalk-id", fixtureCurrentDOpenID2, "--yes", }) if err := root.Execute(); err != nil { @@ -902,7 +902,7 @@ func TestCrossPlatformCoverageMessagesSendCardUsesExplicitOpenReceiver(t *testin fake.calls[0].tool != "create_and_send_card" { t.Fatalf("card open receiver calls = %#v", fake.calls) } - if got := fake.calls[0].args["receiverOpenDingTalkId"]; got != "D-direct" { + if got := fake.calls[0].args["receiverOpenDingTalkId"]; got != fixtureCurrentDOpenID2 { t.Fatalf("receiverOpenDingTalkId = %#v, want D-direct", got) } } @@ -969,7 +969,7 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test root.SetArgs([]string{ "chat", "+messages-send-card", "--group", "cid", - "--at-open-dingtalk-ids", "D-mentioned", + "--at-open-dingtalk-ids", fixtureCurrentDOpenID, "--at-all", "--content", "处理中", "--dry-run", @@ -990,7 +990,7 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test createArguments, _ := create["arguments"].(map[string]any) update, _ := actions[1].(map[string]any) updateArguments, _ := update["arguments"].(map[string]any) - if !reflect.DeepEqual(createArguments["atOpenDingTalkIds"], []any{"D-mentioned"}) || createArguments["atAll"] != true { + if !reflect.DeepEqual(createArguments["atOpenDingTalkIds"], []any{fixtureCurrentDOpenID}) || createArguments["atAll"] != true { t.Fatalf("card create dry-run mentions = %#v", createArguments) } if _, exists := updateArguments["atOpenDingTalkIds"]; exists { @@ -1090,10 +1090,10 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test for _, args := range [][]string{ {"--group", "cid", "--content", "x", "--flow-status", "6"}, {"--group", "cid", "--flow-status", "2"}, - {"--group", "cid", "--receiver-open-dingtalk-id", "D-direct"}, - {"--receiver", "user-id", "--receiver-open-dingtalk-id", "D-direct"}, - {"--receiver", "user-id", "--at-open-dingtalk-ids", "D-mentioned"}, - {"--receiver-open-dingtalk-id", "D-direct", "--at-all"}, + {"--group", "cid", "--receiver-open-dingtalk-id", fixtureCurrentDOpenID2}, + {"--receiver", "user-id", "--receiver-open-dingtalk-id", fixtureCurrentDOpenID2}, + {"--receiver", "user-id", "--at-open-dingtalk-ids", fixtureCurrentDOpenID}, + {"--receiver-open-dingtalk-id", fixtureCurrentDOpenID2, "--at-all"}, } { helpers.InitDeps(&larkAlignmentCaller{}) root := newPlatformCoverageRoot() @@ -1104,6 +1104,35 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test } } +func TestCrossPlatformCoverageExplicitOpenIDValidationEdges(t *testing.T) { + if err := validateExplicitOpenIDs("--open-dingtalk-ids", []string{" ", fixtureCurrentDOpenID}); err != nil { + t.Fatalf("blank and valid IDs: %v", err) + } + if err := validateExplicitOpenIDs("--open-dingtalk-ids", []string{fixtureCurrentDOpenID, "not-an-open-id"}); err == nil { + t.Fatal("invalid explicit open ID unexpectedly accepted") + } + + for _, args := range [][]string{ + {"chat", "+messages-send", "--open-dingtalk-id", "not-an-open-id", "--text", "x", "--yes"}, + {"chat", "+messages-send", "--open-dingtalk-ids", "not-an-open-id", "--text", "x", "--yes"}, + {"chat", "+messages-send", "--group", "cid", "--at-open-dingtalk-ids", "not-an-open-id", "--text", "x", "--yes"}, + {"chat", "+messages-send-card", "--receiver-open-dingtalk-id", "not-an-open-id", "--yes"}, + {"chat", "+messages-send-card", "--group", "cid", "--at-open-dingtalk-ids", "not-an-open-id", "--yes"}, + {"chat", "+conversation-info", "--open-dingtalk-id", "not-an-open-id"}, + {"chat", "+chat-members-get", "--id", "cid", "--users", "not-an-open-id"}, + {"chat", "+messages-send-by-bot", "--robot-code", "robot", "--group", "cid", "--title", "title", "--text", "text", "--at-open-dingtalk-ids", "not-an-open-id", "--yes"}, + {"chat", "+messages-batch-send-by-bot", "--robot-code", "robot", "--title", "title", "--text", "text", "--open-dingtalk-ids", "not-an-open-id", "--yes"}, + {"chat", "+messages-list-direct", "--open-dingtalk-id", "not-an-open-id", "--time", "2026-01-01 00:00:00"}, + {"chat", "+chat-create", "--name", "fixture", "--users", "user-1", "--owner-open-dingtalk-id", "not-an-open-id", "--yes"}, + } { + root := newPlatformCoverageRoot() + root.SetArgs(args) + if err := root.Execute(); err == nil { + t.Fatalf("invalid explicit open ID unexpectedly accepted: %v", args) + } + } +} + func TestCrossPlatformCoverageMessagesUpdateCardVerifiesSuccess(t *testing.T) { t.Run("agent shortcut owns confirmation boundary", func(t *testing.T) { fake := &larkAlignmentCaller{responses: map[string]string{ diff --git a/internal/shortcut/chat/lark_alignment.go b/internal/shortcut/chat/lark_alignment.go index f8a7a605..a9f4c4e0 100644 --- a/internal/shortcut/chat/lark_alignment.go +++ b/internal/shortcut/chat/lark_alignment.go @@ -52,6 +52,11 @@ var ChatCreate = shortcut.Shortcut{ `dws chat +chat-create --name "合作群" --member-query "张三,李四" --type EXTERNAL`, }, Execute: func(rt *shortcut.RuntimeContext) error { + if ownerOpenID := rt.Str("owner-open-dingtalk-id"); ownerOpenID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--owner-open-dingtalk-id", ownerOpenID); err != nil { + return err + } + } resolvedMembers, err := targetresolver.ResolveUsers( rt, rt.StrSlice("member-query"), @@ -339,7 +344,7 @@ func findOpenDingTalkID(value any) string { switch typed := value.(type) { case map[string]any: for _, key := range []string{"senderOpenDingTalkId", "senderOpenDingtalkId", "openDingTalkId", "openDingtalkId"} { - if candidate := strings.TrimSpace(fmt.Sprint(typed[key])); isOpenID(candidate) { + if candidate := strings.TrimSpace(fmt.Sprint(typed[key])); candidate != "" && candidate != "" { return candidate } } @@ -374,7 +379,7 @@ func findMessageSenderOpenDingTalkID(message map[string]any) string { "senderOpenDingtalkId", "senderOpenId", } { - if candidate := strings.TrimSpace(fmt.Sprint(message[key])); isOpenID(candidate) { + if candidate := strings.TrimSpace(fmt.Sprint(message[key])); candidate != "" && candidate != "" { return candidate } } diff --git a/internal/shortcut/chat/lark_alignment_test.go b/internal/shortcut/chat/lark_alignment_test.go index 5dbf9f19..cea41825 100644 --- a/internal/shortcut/chat/lark_alignment_test.go +++ b/internal/shortcut/chat/lark_alignment_test.go @@ -289,12 +289,12 @@ func TestCrossPlatformCoverageMessagesSendRoutesIdentitySpecificTransports(t *te }{ { name: "user", - args: []string{"chat", "+messages-send", "--as", "user", "--chat-id", "cid", "--markdown", "hello @D1", "--at-open-dingtalk-ids", "D1", "--at-all", "--idempotency-key", "u1", "--yes"}, + args: []string{"chat", "+messages-send", "--as", "user", "--chat-id", "cid", "--markdown", "hello @" + fixtureCurrentDOpenID, "--at-open-dingtalk-ids", fixtureCurrentDOpenID, "--at-all", "--idempotency-key", "u1", "--yes"}, product: "chat", tool: "send_personal_message", want: map[string]any{"openConversationId": "cid", "msgType": "markdown", "uuid": "u1"}, bodyKey: "content", - body: "<@all> hello <@D1>", + body: "<@all> hello <@" + fixtureCurrentDOpenID + ">", }, { name: "bot", @@ -471,7 +471,7 @@ func TestCrossPlatformCoverageMessagesReplyPublishesPlainTextBoundary(t *testing "chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", - "--ref-sender", "D-sender", + "--ref-sender", fixtureCurrentDOpenID, "--text", "收到", "--idempotency-key", "reply-uuid", "--yes", @@ -494,7 +494,7 @@ func TestCrossPlatformCoverageMessagesReplyPublishesPlainTextBoundary(t *testing t.Fatal(err) } if content["referenceOpenMessageId"] != "msg" || - content["srcMsgSendOpenDingTalkId"] != "D-sender" || + content["srcMsgSendOpenDingTalkId"] != fixtureCurrentDOpenID || content["replyMsgType"] != "text" || content["content"] != "收到" { t.Fatalf("reply content = %#v", content) @@ -525,7 +525,7 @@ func TestCrossPlatformCoverageMessagesReplyDryRunStopsBeforeWrite(t *testing.T) "chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", - "--ref-sender", "D-sender", + "--ref-sender", fixtureCurrentDOpenID, "--text", "收到", "--dry-run", "--yes", diff --git a/internal/shortcut/chat/remaining_read_pagination_test.go b/internal/shortcut/chat/remaining_read_pagination_test.go index d5506dbc..b3e1ea77 100644 --- a/internal/shortcut/chat/remaining_read_pagination_test.go +++ b/internal/shortcut/chat/remaining_read_pagination_test.go @@ -56,7 +56,7 @@ func TestCrossPlatformCoverageDirectMessagesPageAllUsesMillisecondCursor(t *test var output bytes.Buffer root.SetOut(&output) root.SetArgs([]string{ - "chat", "+messages-list-direct", "--open-dingtalk-id", "D-user", + "chat", "+messages-list-direct", "--open-dingtalk-id", fixtureCurrentDOpenID, "--time", "2026-08-05 16:49:00", "--forward=false", "--limit", "1", "--page-all", "--page-limit", "5", }) diff --git a/internal/shortcut/chat/unified_send.go b/internal/shortcut/chat/unified_send.go index 9991d147..1977d077 100644 --- a/internal/shortcut/chat/unified_send.go +++ b/internal/shortcut/chat/unified_send.go @@ -142,6 +142,17 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error { atOpenIDs := uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")) atUserIDs := uniqueShortcutStrings(rt.StrSlice("at-user-ids")) atMobiles := uniqueShortcutStrings(rt.StrSlice("at-mobiles")) + if openID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openID); err != nil { + return err + } + } + if err := validateExplicitOpenIDs("--open-dingtalk-ids", openIDs); err != nil { + return err + } + if err := validateExplicitOpenIDs("--at-open-dingtalk-ids", atOpenIDs); err != nil { + return err + } contentType, err := messagesSendContentType(rt) if err != nil { return err diff --git a/internal/shortcut/smart/chat_messages.go b/internal/shortcut/smart/chat_messages.go index ed03dd4c..83c94868 100644 --- a/internal/shortcut/smart/chat_messages.go +++ b/internal/shortcut/smart/chat_messages.go @@ -57,7 +57,7 @@ var ChatMessages = shortcut.Shortcut{ Command: "+chat-messages", Product: "chat", Description: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；可附带发送者姓名解析，无稳定身份时保留全部消息，唯一解析出稳定身份后按 senderId 筛选同一次读取结果；" + + Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId，唯一解析后按 senderId 筛选同一次读取结果；不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + @@ -83,7 +83,7 @@ var ChatMessages = shortcut.Shortcut{ }, Selection: contract.SelectionSpec{ AgentSummary: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；可附带发送者姓名解析，无稳定身份时保留全部消息，唯一解析出稳定身份后按 senderId 筛选同一次读取结果；" + + UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId，唯一解析后按 senderId 筛选同一次读取结果；不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + @@ -104,7 +104,8 @@ var ChatMessages = shortcut.Shortcut{ {Name: "user", Type: shortcut.FlagString, Desc: "单聊对方的 userId，与 --group 互斥"}, {Name: "user-query", Type: shortcut.FlagString, Desc: "按姓名解析唯一 openDingTalkId 的兼容入口", Hidden: true}, {Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊对方的 openDingTalkId，与 --group/--user 互斥"}, - {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "按姓名唯一解析发送者并筛选同一次会话读取结果（可选，可重复或逗号分隔）"}, + {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；自动唯一解析并筛选同一次会话读取结果"}, + {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析发送者的兼容入口（可选，可重复或逗号分隔）"}, {Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；--time 必须是 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD；省略时从当前时间向前读取最近消息"}, {Name: "start", Type: shortcut.FlagString, Desc: "范围开始时间（可选、包含），支持 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD"}, {Name: "start-time", Type: shortcut.FlagString, Desc: "--start 的 lark-cli 对齐别名（可选、包含）"}, @@ -133,6 +134,7 @@ var ChatMessages = shortcut.Shortcut{ {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"time", "start", "start-time"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"time", "end", "end-time"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"time", "order", "sort"}}, + {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"sender", "sender-query"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"direction", "start", "start-time"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"direction", "end", "end-time"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"direction", "order", "sort"}}, @@ -223,105 +225,267 @@ type chatMessagesRequest struct { } type chatMessagesSenderFilter struct { - requested bool - applied bool - stableIDs map[string]bool - resolutions []targetresolver.UserResolution - failure map[string]any + requested bool + applied bool + inputs []string + inputMode string + stableIDs map[string]bool + hasUserIDs bool + hasOpenIDs bool + resolutions []targetresolver.UserResolution + resolutionFailure map[string]any + resolutionErr error + scopeErr error } -// resolveOptionalChatMessagesSenderFilter is deliberately local to -// +chat-messages. Sender resolution is an optional post-read filter here: an -// unresolved name must not suppress the command's primary conversation-list -// result. +search-msg keeps its stricter semantics because sender identity is -// part of the lower search request there. +// resolveOptionalChatMessagesSenderFilter accepts the same mixed user target +// as +search-msg while retaining --sender-query as a compatibility entry. It +// resolves only explicitly requested senders; it never enumerates every member +// or tries to infer a person from message display names. func resolveOptionalChatMessagesSenderFilter(rt *shortcut.RuntimeContext) chatMessagesSenderFilter { - queries := rt.StrSlice("sender-query") + direct := uniqueChatMessageTargets(rt.StrSlice("sender")) + queries := uniqueChatMessageTargets(rt.StrSlice("sender-query")) + inputs := direct + inputMode := "sender" + if len(inputs) == 0 { + inputs = queries + inputMode = "sender-query" + } filter := chatMessagesSenderFilter{ - requested: len(queries) > 0, + requested: len(inputs) > 0, + inputs: inputs, + inputMode: inputMode, stableIDs: map[string]bool{}, } if !filter.requested { return filter } - resolutions, err := targetresolver.ResolveUsers(rt, queries, targetresolver.IdentityAny) + var resolutions []targetresolver.UserResolution + var err error + if len(direct) > 0 { + for _, value := range direct { + var resolved targetresolver.UserResolution + resolved, err = targetresolver.ResolveSenderTarget(rt, value, targetresolver.IdentityAny) + if err != nil { + break + } + resolutions = append(resolutions, resolved) + } + } else { + resolutions, err = targetresolver.ResolveUsers(rt, queries, targetresolver.IdentityAny) + } if err != nil { failure := map[string]any{ - "stage": "sender_resolution", - "queries": queries, - "error": err.Error(), + "stage": "sender_resolution", + "inputs": inputs, + "mode": inputMode, + "error": err.Error(), } var typed *apperrors.Error if errors.As(err, &typed) { if typed.Reason != "" { failure["reason"] = typed.Reason } + if typed.Hint != "" { + failure["hint"] = typed.Hint + } if len(typed.Details) > 0 { failure["details"] = typed.Details } } - filter.failure = failure + filter.resolutionFailure = failure + filter.resolutionErr = err return filter } filter.resolutions = resolutions - for _, resolution := range resolutions { - for _, identity := range []string{ - resolution.Selected.UserID, - resolution.Selected.OpenDingTalkID, - } { - if identity = strings.TrimSpace(identity); identity != "" { - filter.stableIDs[identity] = true - } - } - } - // ResolveUsers(IdentityAny) only returns users extracted with at least one - // stable userId/openDingTalkId and fails when no resolvable user remains. + filter.hasUserIDs, filter.hasOpenIDs = addChatMessagesResolvedSenderIDs(filter.stableIDs, resolutions) filter.applied = true return filter } -// applyOptionalChatMessagesSenderFilter preserves the unfiltered message list -// when optional resolution fails. Successful resolution filters both the +func uniqueChatMessageTargets(values []string) []string { + seen := map[string]bool{} + result := make([]string, 0, len(values)) + for _, value := range values { + value = strings.TrimSpace(value) + if value == "" || seen[value] { + continue + } + seen[value] = true + result = append(result, value) + } + return result +} + +func addChatMessagesResolvedSenderIDs(ids map[string]bool, resolutions []targetresolver.UserResolution) (bool, bool) { + hasUserIDs := false + hasOpenIDs := false + for _, resolution := range resolutions { + if identity := strings.TrimSpace(resolution.Selected.UserID); identity != "" { + ids[identity] = true + hasUserIDs = true + } + if identity := strings.TrimSpace(resolution.Selected.OpenDingTalkID); identity != "" { + ids[identity] = true + hasOpenIDs = true + } + } + return hasUserIDs, hasOpenIDs +} + +// applyOptionalChatMessagesSenderFilter fails closed when an explicitly +// requested sender cannot be resolved. Successful resolution filters both the // public projection and raw rows so exports and resource downloads cannot // accidentally include messages outside the requested sender set. func applyOptionalChatMessagesSenderFilter( rt *shortcut.RuntimeContext, payload map[string]any, rawItems []map[string]any, - filter chatMessagesSenderFilter, + filter *chatMessagesSenderFilter, ) []map[string]any { - if !filter.requested || payload == nil { + if filter == nil || !filter.requested || payload == nil { return rawItems } if !filter.applied { failures, _ := payload["failures"].([]map[string]any) priorFailures := len(failures) - failures = append(failures, filter.failure) + failure := filter.resolutionFailure + if failure == nil { + failure = map[string]any{ + "stage": "sender_resolution", + "inputs": filter.inputs, + "mode": filter.inputMode, + "error": "无法把发送者目标唯一解析为稳定身份", + } + } + failures = append(failures, failure) payload["failures"] = failures payload["failedCount"] = len(failures) payload["complete"] = false - payload["partial"] = len(rawItems) > 0 + payload["partial"] = false + payload["messages"] = []map[string]any{} + payload["count"] = 0 + payload["senderFilter"] = map[string]any{ + "requested": true, + "inputs": filter.inputs, + "mode": filter.inputMode, + "applied": false, + "status": "resolution_failed", + "suppressedCount": len(rawItems), + } + payload["identityResult"] = map[string]any{ + "status": "resolution_failed", + "nameComparisonAllowed": false, + "stableIdField": "senderId", + "hint": "当前发送者尚未解析为稳定身份，不能根据 sender 展示名判断该人员是否发过消息。请先完成人员解析。", + } if priorFailures == 0 { payload["stopReason"] = "sender_resolution_failed" } - return rawItems + return nil } filtered := make([]map[string]any, 0, len(rawItems)) + unverifiableMessageIDs := make([]string, 0) for _, item := range rawItems { identity := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(item))) - if identity != "" && identity != "" && filter.stableIDs[identity] { - filtered = append(filtered, item) + if identity == "" || identity == "" { + messageID := chatmsg.StableMessageID(item) + if messageID == "" { + messageID = "" + } + unverifiableMessageIDs = append(unverifiableMessageIDs, messageID) + continue } + if filter.stableIDs[identity] { + filtered = append(filtered, item) + continue + } + if targetresolver.LooksLikeCurrentDOpenDingTalkID(identity) { + if !filter.hasOpenIDs { + unverifiableMessageIDs = append(unverifiableMessageIDs, chatMessagesMessageID(item)) + } + } else if !filter.hasUserIDs { + unverifiableMessageIDs = append(unverifiableMessageIDs, chatMessagesMessageID(item)) + } + } + if len(unverifiableMessageIDs) > 0 { + filter.scopeErr = apperrors.NewAPI( + "部分消息缺少 senderId，无法证明发送者过滤范围；已阻止完整成功与导出", + apperrors.WithReason("chat_messages_sender_scope_unverified"), + apperrors.WithRetryable(false), + apperrors.WithHint("请保留 trace_id 并检查消息读取服务是否返回稳定 senderId"), + apperrors.WithDetails(map[string]any{ + "requestedSenders": filter.inputs, + "unverifiableMessageIds": uniqueChatMessageTargets(unverifiableMessageIDs), + }), + ) + failures, _ := payload["failures"].([]map[string]any) + failures = append(failures, map[string]any{ + "stage": "sender_scope_verification", + "error": filter.scopeErr.Error(), + "unverifiableMessageIds": uniqueChatMessageTargets(unverifiableMessageIDs), + }) + payload["failures"] = failures + payload["failedCount"] = len(failures) + payload["complete"] = false + payload["partial"] = len(filtered) > 0 } payload["messages"] = projectChatMessages(filtered, !rt.Bool("no-reactions")) payload["count"] = len(filtered) payload["resolvedFilters"] = map[string]any{"senders": filter.resolutions} + filterStatus := "applied" + if filter.scopeErr != nil { + filterStatus = "scope_unverified" + } + payload["senderFilter"] = map[string]any{ + "requested": true, + "inputs": filter.inputs, + "mode": filter.inputMode, + "applied": true, + "status": filterStatus, + } + identityResult := map[string]any{ + "status": "evaluated", + "nameComparisonAllowed": false, + "negativeConclusionAllowed": true, + "stableIdField": "senderId", + } + if filter.scopeErr != nil { + identityResult["status"] = "scope_unverified" + identityResult["negativeConclusionAllowed"] = false + identityResult["hint"] = "部分消息缺少稳定 senderId，当前结果不能用于断言该人员没有发过消息。" + } + payload["identityResult"] = identityResult return filtered } +func chatMessagesMessageID(item map[string]any) string { + messageID := chatmsg.StableMessageID(item) + if messageID == "" { + return "" + } + return messageID +} + +func attachUnfilteredSenderIdentitySemantics(payload map[string]any, filter chatMessagesSenderFilter) { + if payload == nil || filter.requested { + return + } + payload["senderFilter"] = map[string]any{ + "requested": false, + "applied": false, + "status": "not_requested", + } + payload["identityResult"] = map[string]any{ + "status": "requires_query_check", + "negativeConclusionAllowed": false, + "hint": "若原始任务包含自然人发送者条件，请先将目标人解析为唯一 userId/openDingTalkId，再与 messages[].senderId 比较；禁止直接比较 messages[].sender 展示名。", + } +} + func resolveChatMessagesRequest(rt *shortcut.RuntimeContext) (chatMessagesRequest, error) { groupID := strings.TrimSpace(rt.StrFirst("conversation-id", "id", "open-conversation-id")) userID := rt.Str("user") @@ -331,6 +495,11 @@ func resolveChatMessagesRequest(rt *shortcut.RuntimeContext) (chatMessagesReques "--open-dingtalk-id 收到的是群 openConversationId；群聊请改用 --group（兼容别名 --chat）", ) } + if openID != "" { + if err := targetresolver.ValidateExplicitOpenDingTalkID("--open-dingtalk-id", openID); err != nil { + return chatMessagesRequest{}, err + } + } if groupID == "" && (rt.Str("group") != "" || rt.Str("chat-query") != "") { resolved, err := targetresolver.ResolveChatTarget(rt, rt.Str("group"), rt.Str("chat-query")) if err != nil { @@ -408,7 +577,8 @@ func executeChatMessages(rt *shortcut.RuntimeContext) error { return err } senderFilter := resolveOptionalChatMessagesSenderFilter(rt) - rawItems = applyOptionalChatMessagesSenderFilter(rt, payload, rawItems, senderFilter) + rawItems = applyOptionalChatMessagesSenderFilter(rt, payload, rawItems, &senderFilter) + attachUnfilteredSenderIdentitySemantics(payload, senderFilter) if err != nil { // Full-page collection returns its failure ledger together with a // non-zero error. Publish that ledger for diagnosis, but stop before @@ -420,6 +590,22 @@ func executeChatMessages(rt *shortcut.RuntimeContext) error { } return err } + if senderFilter.requested && !senderFilter.applied { + if payload != nil { + if outputErr := rt.Output(payload); outputErr != nil { + return outputErr + } + } + return senderFilter.resolutionErr + } + if senderFilter.scopeErr != nil { + if payload != nil { + if outputErr := rt.Output(payload); outputErr != nil { + return outputErr + } + } + return senderFilter.scopeErr + } if rt.Bool("download-resources") { chatshortcut.AttachMessageResourceDownloads( payload, diff --git a/internal/shortcut/smart/chat_messages_test.go b/internal/shortcut/smart/chat_messages_test.go index 0c3918c9..66ca0679 100644 --- a/internal/shortcut/smart/chat_messages_test.go +++ b/internal/shortcut/smart/chat_messages_test.go @@ -20,6 +20,7 @@ import ( stderrors "errors" "math" "os" + "reflect" "testing" "time" @@ -546,7 +547,7 @@ func TestCrossPlatformCoverageChatMessagesAdditionalValidationAndHelpers(t *test filter := resolveOptionalChatMessagesSenderFilter(chatMessagesRuntimeForTest(t, map[string]string{ "sender-query": "测试用户甲", })) - if filter.applied || filter.failure == nil { + if filter.applied || filter.resolutionFailure == nil { t.Fatalf("identity-free sender resolution = %#v", filter) } @@ -577,6 +578,148 @@ func TestCrossPlatformCoverageChatMessagesAdditionalValidationAndHelpers(t *test } } +func TestChatMessagesSenderScopeRejectsUnmappedIdentityFamily(t *testing.T) { + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{"DAAAAAAAAAAAiE"}, + inputMode: "sender", + stableIDs: map[string]bool{"DAAAAAAAAAAAiE": true}, + hasOpenIDs: true, + } + payload := map[string]any{ + "complete": true, + "failures": []map[string]any{}, + } + filtered := applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), + payload, + []map[string]any{{"openMessageId": "m-user-family", "senderUserId": "user-1"}}, + &filter, + ) + if len(filtered) != 0 || filter.scopeErr == nil || payload["complete"] != false { + t.Fatalf("filtered=%#v filter=%#v payload=%#v", filtered, filter, payload) + } +} + +func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) { + t.Run("direct resolution stops after first error", func(t *testing.T) { + fake := &platformCoverageCaller{failTool: "contact/search_contact_by_key_word"} + helpers.InitDeps(fake) + filter := resolveOptionalChatMessagesSenderFilter(chatMessagesRuntimeForTest(t, map[string]string{ + "sender": testCurrentDOpenID + ",fixture-name,ignored-name", + })) + if filter.applied || filter.resolutionErr == nil || len(fake.calls) != 1 { + t.Fatalf("filter=%#v calls=%#v", filter, fake.calls) + } + }) + + t.Run("dedupes blanks and repeated values", func(t *testing.T) { + got := uniqueChatMessageTargets([]string{"", " ", "one", "one", " two "}) + if want := []string{"one", "two"}; !reflect.DeepEqual(got, want) { + t.Fatalf("targets=%#v want=%#v", got, want) + } + }) + + t.Run("synthesizes failure when none was supplied", func(t *testing.T) { + payload := map[string]any{"failures": []map[string]any{{"stage": "existing"}}} + filter := chatMessagesSenderFilter{requested: true, inputs: []string{"fixture"}, inputMode: "sender"} + if got := applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), payload, []map[string]any{{"openMessageId": "hidden"}}, &filter, + ); got != nil { + t.Fatalf("filtered=%#v", got) + } + if _, exists := payload["stopReason"]; exists { + t.Fatalf("existing failure should retain stop reason ownership: %#v", payload) + } + }) + + t.Run("rejects missing and unmapped identity families", func(t *testing.T) { + payload := map[string]any{"complete": true, "failures": []map[string]any{}} + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{"fixture"}, + inputMode: "sender", + stableIDs: map[string]bool{"wanted-user": true}, + hasUserIDs: true, + } + filtered := applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), + payload, + []map[string]any{ + {"content": "missing sender and id"}, + {"openMessageId": "wanted", "senderUserId": "wanted-user"}, + {"openMessageId": "open-family", "senderOpenDingTalkId": testCurrentDOpenID}, + }, + &filter, + ) + if len(filtered) != 1 || filter.scopeErr == nil || chatMessagesMessageID(map[string]any{}) != "" || chatMessagesMessageID(filtered[0]) != "wanted" { + t.Fatalf("filtered=%#v filter=%#v payload=%#v", filtered, filter, payload) + } + }) + + t.Run("rejects user identity when only open ids were resolved", func(t *testing.T) { + payload := map[string]any{"complete": true, "failures": []map[string]any{}} + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{testCurrentDOpenID}, + inputMode: "sender", + stableIDs: map[string]bool{testCurrentDOpenID: true}, + hasOpenIDs: true, + } + applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), payload, + []map[string]any{{"senderUserId": "other-user"}}, &filter, + ) + if filter.scopeErr == nil { + t.Fatalf("filter=%#v", filter) + } + }) + + if _, err := resolveChatMessagesRequest(chatMessagesRuntimeForTest(t, map[string]string{ + "open-dingtalk-id": "not-an-open-id", + })); err == nil { + t.Fatal("invalid explicit open ID unexpectedly accepted") + } +} + +func TestCrossPlatformCoverageChatMessagesSenderFailureOutputEdges(t *testing.T) { + for _, tc := range []struct { + name string + sender string + }{ + {name: "resolution", sender: "fixture-name"}, + {name: "scope", sender: testCurrentDOpenID}, + } { + t.Run(tc.name+" returns domain error", func(t *testing.T) { + caller := &chatMessagesPagingCaller{responses: []string{ + `{"result":{"hasMore":false,"messages":[{"openMessageId":"m-without-sender"}]}}`, + }} + helpers.InitDeps(caller) + root := newPlatformCoverageRoot() + root.SetArgs([]string{"chat", "+chat-messages", "--conversation-id", "cid", "--sender", tc.sender}) + if err := root.Execute(); err == nil { + t.Fatal("sender failure unexpectedly succeeded") + } + }) + + t.Run(tc.name+" prioritizes output error", func(t *testing.T) { + caller := &chatMessagesPagingCaller{responses: []string{ + `{"result":{"hasMore":false,"messages":[{"openMessageId":"m-without-sender"}]}}`, + }} + helpers.InitDeps(caller) + root := newPlatformCoverageRoot() + root.SetOut(chatMessagesFailWriter{}) + root.SetArgs([]string{"chat", "+chat-messages", "--conversation-id", "cid", "--sender", tc.sender}) + if err := root.Execute(); err == nil || err.Error() != "fixture output failure" { + t.Fatalf("error=%v", err) + } + }) + } +} + func TestCrossPlatformCoverageChatMessagesAdditionalCollectionEdges(t *testing.T) { runtimeWith := func(t *testing.T, caller *chatMessagesPagingCaller, values map[string]string) *shortcut.RuntimeContext { t.Helper() diff --git a/internal/shortcut/smart/coverage_completion_test.go b/internal/shortcut/smart/coverage_completion_test.go index 4503d79e..61fbe8bc 100644 --- a/internal/shortcut/smart/coverage_completion_test.go +++ b/internal/shortcut/smart/coverage_completion_test.go @@ -105,7 +105,7 @@ func TestCrossPlatformCoverageChatMessagesOpenIDRoute(t *testing.T) { }} helpers.InitDeps(caller) root := newPlatformCoverageRoot() - root.SetArgs([]string{"chat", "+chat-messages", "--open-dingtalk-id", "D-user", "--limit", "1", "--yes"}) + root.SetArgs([]string{"chat", "+chat-messages", "--open-dingtalk-id", testCurrentDOpenID, "--limit", "1", "--yes"}) if err := root.Execute(); err != nil { t.Fatal(err) } diff --git a/internal/shortcut/smart/natural_target_resolution_test.go b/internal/shortcut/smart/natural_target_resolution_test.go index df5bc3ae..f6704eb9 100644 --- a/internal/shortcut/smart/natural_target_resolution_test.go +++ b/internal/shortcut/smart/natural_target_resolution_test.go @@ -22,7 +22,7 @@ func TestCrossPlatformCoverageNaturalSearchAndSenderFlagsStayPublicOptional(t *t want []string }{ {name: "search natural adapters", flags: SearchMsg.Flags, want: []string{"chat-query", "sender-query"}}, - {name: "chat messages natural adapters", flags: ChatMessages.Flags, want: []string{"chat-query", "sender-query"}}, + {name: "chat messages natural adapters", flags: ChatMessages.Flags, want: []string{"chat-query", "sender", "sender-query"}}, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { @@ -160,7 +160,7 @@ func TestCrossPlatformCoverageChatMessagesOptionallyFiltersResolvedSenderByEithe root.SetOut(&output) root.SetArgs([]string{ "chat", "+chat-messages", "--group", "cid-fixture-chat-0001", - "--sender-query", "测试用户甲", "--page-all", + "--sender", "测试用户甲", "--page-all", }) if err := root.Execute(); err != nil { t.Fatal(err) @@ -201,7 +201,64 @@ func TestCrossPlatformCoverageChatMessagesOptionallyFiltersResolvedSenderByEithe } } -func TestCrossPlatformCoverageChatMessagesSenderResolutionFailureKeepsUnfilteredMessages(t *testing.T) { +func TestChatMessagesFormatValidSenderSkipsDirectoryAndFiltersStableID(t *testing.T) { + fake := &platformCoverageCaller{ + chatMessagesResult: `{"result":{"hasMore":false,"messages":[ + {"openMessageId":"wanted","sender":"目标展示名","senderOpenDingTalkId":"DAAAAAAAAAAAiE","content":"保留"}, + {"openMessageId":"other","sender":"其他人","senderOpenDingTalkId":"DAQEBAQEBAQEiE","content":"过滤"} + ]}}`, + } + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) + root.SetArgs([]string{ + "chat", "+chat-messages", "--group", "cid-fixture-chat-0001", + "--sender", "DAAAAAAAAAAAiE", "--page-all", + }) + if err := root.Execute(); err != nil { + t.Fatal(err) + } + if len(fake.calls) != 1 || fake.calls[0].tool != "list_conversation_message_v2" { + t.Fatalf("format-valid sender unexpectedly preflighted: %#v", fake.calls) + } + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatal(err) + } + if payload["count"] != float64(1) || payload["complete"] != true { + t.Fatalf("payload=%#v", payload) + } +} + +func TestChatMessagesWithoutSenderDoesNotResolveEveryMessageIdentity(t *testing.T) { + fake := &platformCoverageCaller{chatMessagesResult: `{"result":{"hasMore":false,"messages":[ + {"openMessageId":"m1","sender":"群昵称一","senderOpenDingTalkId":"D1","content":"一"}, + {"openMessageId":"m2","sender":"群昵称二","senderOpenDingTalkId":"D2","content":"二"} + ]}}`} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) + root.SetArgs([]string{"chat", "+chat-messages", "--group", "cid-fixture-chat-0001", "--page-all"}) + if err := root.Execute(); err != nil { + t.Fatal(err) + } + if len(fake.calls) != 1 || fake.calls[0].tool != "list_conversation_message_v2" { + t.Fatalf("calls=%#v", fake.calls) + } + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatal(err) + } + identity := payload["identityResult"].(map[string]any) + if payload["count"] != float64(2) || identity["status"] != "requires_query_check" || + identity["negativeConclusionAllowed"] != false { + t.Fatalf("payload=%#v", payload) + } +} + +func TestCrossPlatformCoverageChatMessagesSenderResolutionFailureStopsWithoutUnfilteredMessages(t *testing.T) { fake := &platformCoverageCaller{ contactSearchResult: `{"result":[]}`, chatMessagesResult: `{"result":{"hasMore":false,"messages":[ @@ -216,22 +273,26 @@ func TestCrossPlatformCoverageChatMessagesSenderResolutionFailureKeepsUnfiltered "chat", "+chat-messages", "--group", "cid-fixture-chat-0001", "--sender-query", "不存在的人", "--page-all", }) - if err := root.Execute(); err != nil { - t.Fatalf("optional sender failure stopped message read: %v", err) + if err := root.Execute(); err == nil { + t.Fatal("sender resolution failure unexpectedly succeeded") } if len(fake.calls) != 2 || fake.calls[0].tool != "list_conversation_message_v2" || fake.calls[1].tool != "search_contact_by_key_word" { - t.Fatalf("calls = %#v, want message read followed by non-blocking failed resolve", fake.calls) + t.Fatalf("calls = %#v, want message read followed by failed resolve", fake.calls) } var payload map[string]any if err := json.Unmarshal(output.Bytes(), &payload); err != nil { t.Fatalf("decode output: %v\n%s", err, output.String()) } - if payload["count"] != float64(1) || payload["complete"] != false || - payload["partial"] != true || payload["failedCount"] != float64(1) || + if payload["count"] != float64(0) || payload["complete"] != false || + payload["partial"] != false || payload["failedCount"] != float64(1) || payload["stopReason"] != "sender_resolution_failed" { - t.Fatalf("unfiltered fallback payload = %#v", payload) + t.Fatalf("fail-closed payload = %#v", payload) + } + messages, ok := payload["messages"].([]any) + if !ok || len(messages) != 0 { + t.Fatalf("failed resolution leaked unfiltered messages: %#v", payload["messages"]) } if _, exists := payload["resolvedFilters"]; exists { t.Fatalf("failed resolution unexpectedly published resolvedFilters: %#v", payload) diff --git a/internal/shortcut/smart/search_msg.go b/internal/shortcut/smart/search_msg.go index 48b15ec7..2224d542 100644 --- a/internal/shortcut/smart/search_msg.go +++ b/internal/shortcut/smart/search_msg.go @@ -35,7 +35,7 @@ import ( // search hits through list_messages_by_ids in chunks of 50. A later-page or // enrichment failure never turns a partial result into a false success: the // output carries an explicit failure ledger and complete=false. -const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话，会话与发送者过滤使用稳定 ID。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + +const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话。--group/--groups 接受群名或 openConversationId，--sender/--senders 接受姓名、userId 或 openDingTalkId，并统一唯一解析为稳定 ID。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + "显式指定会话时会先验证 CID，再执行有界全局扫描并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID。" + "--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。" + "--download-resources 使用安全本地路径、默认不覆盖和原子落盘。" @@ -70,8 +70,8 @@ var SearchMsg = shortcut.Shortcut{ UseWhen: []string{searchMsgIntent}, AvoidWhen: []string{"只想查看或导出一个指定会话的消息记录、且没有发送者、关键词、@对象或消息类型等主要筛选条件时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"}, Examples: []string{ + "dws chat +search-msg --group \"项目群\" --sender \"测试用户甲\" --page-all", "dws chat +search-msg --query \"周报\" --senders --days 3 --page-all", - "dws chat +search-msg --query \"周报\" --senders --days 3 --page-all --jq '.messages[] | {messageId, text}'", }, }, }, @@ -80,15 +80,15 @@ var SearchMsg = shortcut.Shortcut{ {Name: "keyword", Type: shortcut.FlagString, Desc: "--query 的别名", Hidden: true}, {Name: "text", Type: shortcut.FlagString, Desc: "--query 的兼容别名", Hidden: true}, {Name: "text-query", Type: shortcut.FlagString, Desc: "--query 的兼容别名", Hidden: true}, - {Name: "group", Type: shortcut.FlagString, Desc: "单个会话 openConversationId"}, + {Name: "group", Type: shortcut.FlagString, Desc: "单个群名或 openConversationId；自动唯一解析并校验"}, {Name: "conversation-id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true}, {Name: "id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true}, - {Name: "groups", Type: shortcut.FlagStringSlice, Desc: "多个会话 openConversationId"}, - {Name: "chat-id", Type: shortcut.FlagStringSlice, Desc: "--groups 的 lark-cli 对齐别名"}, - {Name: "chat-query", Type: shortcut.FlagStringSlice, Desc: "按群名唯一解析会话过滤条件（可选，可重复或逗号分隔）"}, - {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "发送者 userId/openDingTalkId 列表"}, - {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "--senders 的 lark-cli 对齐别名"}, - {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "按姓名唯一解析发送者过滤条件（可选，可重复或逗号分隔）"}, + {Name: "groups", Type: shortcut.FlagStringSlice, Desc: "多个群名或 openConversationId；可混合输入并逐项唯一解析"}, + {Name: "chat-id", Type: shortcut.FlagStringSlice, Desc: "--groups 的 lark-cli 对齐别名；只接受 openConversationId"}, + {Name: "chat-query", Type: shortcut.FlagStringSlice, Desc: "显式按群名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, + {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "多个发送者姓名、userId 或 openDingTalkId；可混合输入并逐项唯一解析"}, + {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；--senders 的兼容别名"}, + {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, {Name: "at-me", Type: shortcut.FlagBool, Desc: "只搜索 @我 的消息"}, {Name: "is-at-me", Type: shortcut.FlagBool, Desc: "--at-me 的 lark-cli 对齐别名"}, {Name: "at-ids", Type: shortcut.FlagStringSlice, Desc: "@对象 userId/openDingTalkId 列表"}, @@ -140,6 +140,7 @@ var SearchMsg = shortcut.Shortcut{ {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"cursor", "page-token"}}, }, chatshortcut.MessageResourceDownloadConstraints()...), Tips: []string{ + `dws chat +search-msg --group "项目群" --sender "测试用户甲" --page-all`, `dws chat +search-msg --group --query "changefree"`, `dws chat +search-msg --senders --at-me --days 3 --page-all`, `dws chat +search-msg --group --query "changefree" --jq '.messages[] | {messageId, text}'`, @@ -270,6 +271,13 @@ var SearchMsg = shortcut.Shortcut{ } messages = validatedMessages } + if len(resolvedFilters.Senders) > 0 { + var unverifiableMessageIDs []string + messages, unverifiableMessageIDs = filterSearchSenderScope(messages, resolvedFilters.Senders) + if len(unverifiableMessageIDs) > 0 { + return searchSenderScopeUnverifiedError(resolvedFilters.Senders, unverifiableMessageIDs) + } + } order := strings.ToLower(strings.TrimSpace(rt.StrFirst("order", "sort"))) if order == "" { @@ -293,9 +301,19 @@ var SearchMsg = shortcut.Shortcut{ "failedCount": len(failures), "failures": failures, "queryRange": searchMessageQueryRange(params, order), + "timeCoverage": searchMessageTimeCoverage(rt), + "conclusionGuard": searchMessageConclusionGuard(rt, complete, len(results)), + } + if len(resolvedFilters.Chats) > 0 || len(resolvedFilters.Senders) > 0 { + payload["resolvedFilters"] = resolvedFilters } if len(resolvedFilters.Senders) > 0 { - payload["resolvedFilters"] = resolvedFilters + payload["senderScope"] = map[string]any{ + "targetsResolved": true, + "filterApplied": true, + "filterMode": "server_and_client", + "resultsWithinScope": true, + } } if scopedSearch { payload["scope"] = searchScopePayload(requestedConversationIDs, paginationKnown && !hasMore) @@ -313,6 +331,39 @@ var SearchMsg = shortcut.Shortcut{ }, } +func searchMessageTimeCoverage(rt *shortcut.RuntimeContext) map[string]any { + source := "implicit_default" + if rt.Changed("start") || rt.Changed("start-time") || rt.Changed("end") || rt.Changed("end-time") { + source = "explicit_range" + } else if rt.Changed("days") { + source = "explicit_days" + } + + coverage := map[string]any{ + "source": source, + "allHistory": false, + } + if source != "explicit_range" { + coverage["days"] = rt.Int("days") + } + return coverage +} + +func searchMessageConclusionGuard(rt *shortcut.RuntimeContext, complete bool, resultCount int) map[string]any { + coverage := searchMessageTimeCoverage(rt) + guard := map[string]any{ + "absenceWithinQueryRangeAllowed": complete, + "absenceAcrossAllHistoryAllowed": false, + "allHistoryCountAllowed": false, + "requiredActionForAllHistory": "widen_time_range_or_reuse_complete_message_ledger", + } + if coverage["source"] == "implicit_default" && resultCount == 0 { + guard["requiredAction"] = "widen_time_range_or_reuse_complete_message_ledger" + guard["hint"] = "当前只证明默认 7 天时间窗内没有命中，不能据此判断全部历史没有。若已有完整会话消息，请解析稳定身份后复用现有消息；否则扩大时间范围。" + } + return guard +} + func validateSearchMsgWithResources(rt *shortcut.RuntimeContext) error { if err := validateSearchMsg(rt); err != nil { return err @@ -350,6 +401,39 @@ func validateSearchMsg(rt *shortcut.RuntimeContext) error { if pageLimit := rt.Int("page-limit"); pageLimit < 1 || pageLimit > 40 { return apperrors.NewValidation("--page-limit 必须在 1-40 之间") } + if err := validateSearchMsgStrictConversationAliases(rt); err != nil { + return err + } + return nil +} + +// The conventional --group/--groups flags are intentionally dual-form. Only +// the explicit ID aliases remain strict so scripts that select them retain a +// deterministic contract. +func validateSearchMsgStrictConversationAliases(rt *shortcut.RuntimeContext) error { + values := append([]string{}, rt.StrSlice("chat-id")...) + if value := rt.StrFirst("conversation-id", "id"); value != "" { + values = append(values, value) + } + for _, value := range uniqueSearchStrings(values) { + if strings.HasPrefix(strings.ToLower(value), "cid") { + continue + } + return apperrors.NewValidation( + fmt.Sprintf("显式会话 ID 参数收到非 openConversationId 值 %q；已停止消息搜索", value), + apperrors.WithReason("target_type_mismatch"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("request_validation"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + apperrors.WithHint(fmt.Sprintf("--chat-id/--conversation-id/--id 只接受 cid 开头的 openConversationId；群名请使用 --group %q 或 --groups %q。", value, value)), + apperrors.WithDetails(map[string]any{ + "flags": []string{"chat-id", "conversation-id", "id"}, + "expectedType": "openConversationId", + "providedValue": value, + }), + ) + } return nil } @@ -358,6 +442,7 @@ func validateSearchMsg(rt *shortcut.RuntimeContext) error { // the directory name, so consumers must join the selected stable identity to // each projected message's senderId instead of comparing those two names. type searchResolvedFilters struct { + Chats []targetresolver.ChatResolution `json:"chats,omitempty"` Senders []targetresolver.UserResolution `json:"senders,omitempty"` } @@ -367,41 +452,61 @@ func searchMsgParams(rt *shortcut.RuntimeContext) (map[string]any, searchResolve if value := rt.StrFirst("query", "keyword", "text", "text-query"); value != "" { params["keyword"] = value } - conversationIDs := append([]string{}, rt.StrSlice("groups")...) - conversationIDs = append(conversationIDs, rt.StrSlice("chat-id")...) - if value := rt.StrFirst("group", "conversation-id", "id"); value != "" { + conversationIDs := append([]string{}, rt.StrSlice("chat-id")...) + if value := rt.StrFirst("conversation-id", "id"); value != "" { conversationIDs = append(conversationIDs, value) } + groupTargets := append([]string{}, rt.StrSlice("groups")...) + if value := rt.Str("group"); value != "" { + groupTargets = append(groupTargets, value) + } + for _, target := range uniqueSearchStrings(groupTargets) { + if strings.HasPrefix(strings.ToLower(target), "cid") { + conversationIDs = append(conversationIDs, target) + continue + } + resolved, err := targetresolver.ResolveChatTarget(rt, target, "") + if err != nil { + return nil, searchResolvedFilters{}, err + } + resolvedFilters.Chats = append(resolvedFilters.Chats, resolved) + conversationIDs = append(conversationIDs, resolved.Selected.OpenConversationID) + } if queries := rt.StrSlice("chat-query"); len(queries) > 0 { for _, query := range queries { resolved, err := targetresolver.ResolveChatTarget(rt, "", query) if err != nil { return nil, searchResolvedFilters{}, err } + resolvedFilters.Chats = append(resolvedFilters.Chats, resolved) conversationIDs = append(conversationIDs, resolved.Selected.OpenConversationID) } } if values := uniqueSearchStrings(conversationIDs); len(values) > 0 { params["openConversationIds"] = values } - senders := append([]string{}, rt.StrSlice("senders")...) - senders = append(senders, rt.StrSlice("sender")...) + senderTargets := append([]string{}, rt.StrSlice("senders")...) + senderTargets = append(senderTargets, rt.StrSlice("sender")...) + for _, target := range uniqueSearchStrings(senderTargets) { + resolved, err := targetresolver.ResolveSenderTarget(rt, target, targetresolver.IdentityAny) + if err != nil { + return nil, searchResolvedFilters{}, err + } + resolvedFilters.Senders = append(resolvedFilters.Senders, resolved) + } if queries := rt.StrSlice("sender-query"); len(queries) > 0 { resolvedUsers, err := targetresolver.ResolveUsers(rt, queries, targetresolver.IdentityAny) if err != nil { return nil, searchResolvedFilters{}, err } resolvedFilters.Senders = append(resolvedFilters.Senders, resolvedUsers...) - for _, resolved := range resolvedUsers { - identity := resolved.Selected.OpenDingTalkID - if identity == "" { - identity = resolved.Selected.UserID - } - senders = append(senders, identity) - } } - appendSearchActorIDs(params, senders, "senderUserIds", "senderOpenDingTakIds") - appendSearchActorIDs(params, rt.StrSlice("at-ids"), "atUserIds", "atOpenDingTakIds") + appendResolvedSearchActorIDs(params, resolvedFilters.Senders, "senderUserIds", "senderOpenDingTakIds") + atUsers, err := resolveSearchStableActorTargets(rt, rt.StrSlice("at-ids")) + if err != nil { + return nil, searchResolvedFilters{}, err + } + appendResolvedSearchActorIDs(params, atUsers, "atUserIds", "atOpenDingTakIds") if rt.Bool("at-me") || rt.Bool("is-at-me") { params["atMe"] = true } @@ -439,15 +544,41 @@ func searchMsgParams(rt *shortcut.RuntimeContext) (map[string]any, searchResolve return params, resolvedFilters, nil } -func appendSearchActorIDs(params map[string]any, values []string, userKey, openIDKey string) { - var userIDs, openIDs []string +func resolveSearchStableActorTargets( + rt *shortcut.RuntimeContext, + values []string, +) ([]targetresolver.UserResolution, error) { + resolvedUsers := make([]targetresolver.UserResolution, 0, len(values)) for _, value := range uniqueSearchStrings(values) { - if len(value) > 0 && (value[0] == 'D' || value[0] == 'd') { - openIDs = append(openIDs, value) - } else { - userIDs = append(userIDs, value) + resolved, err := targetresolver.ResolveStableUserTarget(rt, value, targetresolver.IdentityAny) + if err != nil { + return nil, err + } + resolvedUsers = append(resolvedUsers, resolved) + } + return resolvedUsers, nil +} + +// appendResolvedSearchActorIDs prefers openDingTalkId whenever directory +// resolution supplies it because the current message-search backend reliably +// applies the open-ID field but may ignore senderUserIds. +func appendResolvedSearchActorIDs( + params map[string]any, + resolutions []targetresolver.UserResolution, + userKey, openIDKey string, +) { + var userIDs, openIDs []string + for _, resolved := range resolutions { + openID := strings.TrimSpace(resolved.Selected.OpenDingTalkID) + userID := strings.TrimSpace(resolved.Selected.UserID) + if openID != "" { + openIDs = append(openIDs, openID) + } else if userID != "" { + userIDs = append(userIDs, userID) } } + userIDs = uniqueSearchStrings(userIDs) + openIDs = uniqueSearchStrings(openIDs) if len(userIDs) > 0 { params[userKey] = userIDs } @@ -527,6 +658,79 @@ func searchScopePayload(conversationIDs []string, sourceComplete bool) map[strin } } +func filterSearchSenderScope( + messages []map[string]any, + resolutions []targetresolver.UserResolution, +) ([]map[string]any, []string) { + allowed := map[string]bool{} + hasUserIDs := false + hasOpenIDs := false + for _, resolution := range resolutions { + if value := strings.TrimSpace(resolution.Selected.UserID); value != "" { + allowed[value] = true + hasUserIDs = true + } + if value := strings.TrimSpace(resolution.Selected.OpenDingTalkID); value != "" { + allowed[value] = true + hasOpenIDs = true + } + } + + filtered := make([]map[string]any, 0, len(messages)) + unverifiable := make([]string, 0) + for _, message := range messages { + senderID := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(message))) + if senderID == "" || senderID == "" { + messageID := strings.TrimSpace(fmt.Sprint(searchMsgMessageID(message))) + if messageID == "" || messageID == "" { + messageID = "" + } + unverifiable = append(unverifiable, messageID) + continue + } + if allowed[senderID] { + filtered = append(filtered, message) + continue + } + if targetresolver.LooksLikeCurrentDOpenDingTalkID(senderID) { + if !hasOpenIDs { + unverifiable = append(unverifiable, searchScopeMessageID(message)) + } + } else if !hasUserIDs { + unverifiable = append(unverifiable, searchScopeMessageID(message)) + } + } + return filtered, uniqueSearchStrings(unverifiable) +} + +func searchScopeMessageID(message map[string]any) string { + messageID := strings.TrimSpace(fmt.Sprint(searchMsgMessageID(message))) + if messageID == "" || messageID == "" { + return "" + } + return messageID +} + +func searchSenderScopeUnverifiedError( + resolutions []targetresolver.UserResolution, + messageIDs []string, +) error { + queries := make([]string, 0, len(resolutions)) + for _, resolution := range resolutions { + queries = append(queries, resolution.Query) + } + return apperrors.NewAPI( + "搜索结果缺少 senderId，无法证明发送者过滤范围；已停止输出", + apperrors.WithReason("search_sender_scope_unverified"), + apperrors.WithDetails(map[string]any{ + "requestedSenders": uniqueSearchStrings(queries), + "unverifiableMessageIds": messageIDs, + }), + apperrors.WithRetryable(false), + apperrors.WithHint("请保留 trace_id 并检查 IM 搜索服务是否返回稳定 senderId"), + ) +} + func enrichSearchMessages(rt *shortcut.RuntimeContext, messages []map[string]any) ([]map[string]any, int, []map[string]any) { detailsByID := map[string]map[string]any{} failures := make([]map[string]any, 0) diff --git a/internal/shortcut/smart/search_msg_execution_test.go b/internal/shortcut/smart/search_msg_execution_test.go index ec83c2ff..161abe4e 100644 --- a/internal/shortcut/smart/search_msg_execution_test.go +++ b/internal/shortcut/smart/search_msg_execution_test.go @@ -15,25 +15,35 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) type searchMsgExecutionCaller struct { - calls []platformCoverageCall - failSecondPage bool - failEnrichment bool - omitPagination bool - omitMgetItem bool - failPreflight bool - preflightError error - searchResponse string - wrongMgetScope bool - missingMgetCID bool - firstResponse string - mgetResponse string - numericZeroEnd bool + calls []platformCoverageCall + failSecondPage bool + failEnrichment bool + omitPagination bool + omitMgetItem bool + failPreflight bool + preflightError error + searchResponse string + wrongMgetScope bool + missingMgetCID bool + firstResponse string + mgetResponse string + numericZeroEnd bool + contactResponse string + groupResponse string + failContactKeyword string + failGroupKeyword string } +const ( + testCurrentDOpenID = "DAAAAAAAAAAAiE" + testCurrentDOpenID2 = "DAQEBAQEBAQEiE" +) + func (f *searchMsgExecutionCaller) CallTool(_ context.Context, product, tool string, args map[string]any) (*edition.ToolResult, error) { f.calls = append(f.calls, platformCoverageCall{product: product, tool: tool, args: args}) if product == "chat" && tool == "get_conversation_info" { @@ -45,10 +55,28 @@ func (f *searchMsgExecutionCaller) CallTool(_ context.Context, product, tool str } return searchMsgToolResult(`{"result":{"openConversationId":"` + args["openConversationId"].(string) + `"}}`), nil } + if product == "contact" && tool == "search_contact_by_key_word" { + if f.failContactKeyword != "" && args["keyword"] == f.failContactKeyword { + return nil, errors.New("fixture contact failure") + } + if f.contactResponse != "" { + return searchMsgToolResult(f.contactResponse), nil + } + keyword := args["keyword"].(string) + return searchMsgToolResult(`{"result":[{"userId":"user-` + keyword + `","openDingTalkId":"` + testCurrentDOpenID + `","name":"` + keyword + `"}],"hasMore":false}`), nil + } if product != "im" { return nil, errors.New("unexpected product") } switch tool { + case "search_groups": + if f.failGroupKeyword != "" && args["keyword"] == f.failGroupKeyword { + return nil, errors.New("fixture group failure") + } + if f.groupResponse != "" { + return searchMsgToolResult(f.groupResponse), nil + } + return searchMsgToolResult(`{"result":[{"openConversationId":"cid-resolved-group","title":"` + args["keyword"].(string) + `"}],"hasMore":false}`), nil case "search_messages": if f.searchResponse != "" { return searchMsgToolResult(f.searchResponse), nil @@ -63,12 +91,12 @@ func (f *searchMsgExecutionCaller) CallTool(_ context.Context, product, tool str if f.failSecondPage { return nil, errors.New("second page unavailable") } - return searchMsgToolResult(`{"result":{"messages":[{"openMessageId":"m2","openConversationId":"cid-2","content":"sparse-2"}],"hasMore":false}}`), nil + return searchMsgToolResult(`{"result":{"messages":[{"openMessageId":"m2","openConversationId":"cid-2","senderOpenDingTalkId":"` + testCurrentDOpenID + `","content":"sparse-2"}],"hasMore":false}}`), nil } if f.firstResponse != "" { return searchMsgToolResult(f.firstResponse), nil } - return searchMsgToolResult(`{"result":{"messages":[{"openMessageId":"m1","openConversationId":"cid-1","content":"sparse-1"}],"hasMore":true,"nextCursor":"c2"}}`), nil + return searchMsgToolResult(`{"result":{"messages":[{"openMessageId":"m1","openConversationId":"cid-1","senderOpenDingTalkId":"` + testCurrentDOpenID + `","content":"sparse-1"}],"hasMore":true,"nextCursor":"c2"}}`), nil case "list_messages_by_ids": if f.failEnrichment { return nil, errors.New("mget unavailable") @@ -129,13 +157,175 @@ func executeSearchMsgResult(caller *searchMsgExecutionCaller, args ...string) (m return payload, nil } +func TestSearchMsgMixedSenderClassifiesFormatWithoutIDPreflight(t *testing.T) { + tests := []string{"D-prefix-fixture-user", "d-prefix-fixture-user", "测试用户甲", "fixture-user-id"} + for _, target := range tests { + t.Run(target, func(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[],"hasMore":false}}`} + payload := executeSearchMsg(t, caller, "--sender", target, "--no-enrich") + if payload["complete"] != true || len(caller.calls) != 2 { + t.Fatalf("payload=%#v calls=%#v", payload, caller.calls) + } + if caller.calls[0].product != "contact" || caller.calls[0].tool != "search_contact_by_key_word" || + caller.calls[1].tool != "search_messages" { + t.Fatalf("calls=%#v", caller.calls) + } + if got, want := caller.calls[1].args["senderOpenDingTakIds"], []string{testCurrentDOpenID}; !reflect.DeepEqual(got, want) { + t.Fatalf("senderOpenDingTakIds=%#v want=%#v", got, want) + } + }) + } + + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[],"hasMore":false}}`} + executeSearchMsg(t, caller, "--sender", testCurrentDOpenID, "--no-enrich") + if len(caller.calls) != 1 || caller.calls[0].tool != "search_messages" { + t.Fatalf("format-valid ID unexpectedly preflighted: %#v", caller.calls) + } +} + +func TestSearchMsgSenderScopeFiltersBackendOverReturn(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[ + {"openMessageId":"wanted","senderOpenDingTalkId":"DAAAAAAAAAAAiE","content":"keep"}, + {"openMessageId":"other","senderOpenDingTalkId":"DAQEBAQEBAQEiE","content":"drop"} + ],"hasMore":false}}`} + payload := executeSearchMsg(t, caller, "--sender", testCurrentDOpenID, "--no-enrich") + if payload["count"] != float64(1) { + t.Fatalf("payload=%#v", payload) + } + messages := payload["messages"].([]any) + if messages[0].(map[string]any)["messageId"] != "wanted" { + t.Fatalf("messages=%#v", messages) + } +} + +func TestCrossPlatformCoverageSearchMsgSenderScopeRejectsUnmappedIdentityFamily(t *testing.T) { + filtered, unverifiable := filterSearchSenderScope( + []map[string]any{{"openMessageId": "m-user-family", "senderUserId": "user-1"}}, + []targetresolver.UserResolution{{ + Selected: targetresolver.User{OpenDingTalkID: testCurrentDOpenID}, + }}, + ) + if len(filtered) != 0 || !reflect.DeepEqual(unverifiable, []string{"m-user-family"}) { + t.Fatalf("filtered=%#v unverifiable=%#v", filtered, unverifiable) + } +} + +func TestCrossPlatformCoverageSearchMsgResolutionFailureEdges(t *testing.T) { + for _, tc := range []struct { + name string + caller *searchMsgExecutionCaller + args []string + }{ + { + name: "group target", + caller: &searchMsgExecutionCaller{failGroupKeyword: "missing-group"}, + args: []string{"--group", "missing-group", "--no-enrich"}, + }, + { + name: "sender target", + caller: &searchMsgExecutionCaller{failContactKeyword: "missing-sender"}, + args: []string{"--sender", "missing-sender", "--no-enrich"}, + }, + { + name: "sender query", + caller: &searchMsgExecutionCaller{failContactKeyword: "missing-query"}, + args: []string{"--sender-query", "missing-query", "--no-enrich"}, + }, + { + name: "at stable id", + caller: &searchMsgExecutionCaller{failContactKeyword: "missing-at"}, + args: []string{"--at-ids", "missing-at", "--no-enrich"}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + if _, err := executeSearchMsgResult(tc.caller, tc.args...); err == nil { + t.Fatal("resolution failure unexpectedly succeeded") + } + }) + } +} + +func TestCrossPlatformCoverageSearchMsgSenderScopeFailureEdges(t *testing.T) { + t.Run("execute rejects senderless backend rows", func(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[{"content":"missing identity"}],"hasMore":false}}`} + _, err := executeSearchMsgResult(caller, "--sender", testCurrentDOpenID, "--no-enrich") + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "search_sender_scope_unverified" { + t.Fatalf("error=%#v", err) + } + }) + + resolutions := []targetresolver.UserResolution{{ + Query: "fixture-user", + Selected: targetresolver.User{UserID: "wanted-user"}, + }} + filtered, unverifiable := filterSearchSenderScope( + []map[string]any{ + {"content": "missing identity"}, + {"openMessageId": "wanted", "senderUserId": "wanted-user"}, + {"openMessageId": "open-family", "senderOpenDingTalkId": testCurrentDOpenID}, + }, + resolutions, + ) + if len(filtered) != 1 || !reflect.DeepEqual(unverifiable, []string{"", "open-family"}) { + t.Fatalf("filtered=%#v unverifiable=%#v", filtered, unverifiable) + } + if got := searchScopeMessageID(map[string]any{}); got != "" { + t.Fatalf("missing message ID=%q", got) + } + if got := searchScopeMessageID(map[string]any{"openMessageId": "message-1"}); got != "message-1" { + t.Fatalf("message ID=%q", got) + } + err := searchSenderScopeUnverifiedError( + append(resolutions, resolutions...), + []string{"message-1"}, + ) + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "search_sender_scope_unverified" { + t.Fatalf("error=%#v", err) + } +} + +func TestCrossPlatformCoverageSearchMsgExplicitDaysMetadata(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[],"hasMore":false}}`} + payload := executeSearchMsg(t, caller, "--query", "fixture", "--days", "3", "--no-enrich") + coverage := payload["timeCoverage"].(map[string]any) + if coverage["source"] != "explicit_days" || coverage["days"] != float64(3) { + t.Fatalf("coverage=%#v", coverage) + } +} + +func TestCrossPlatformCoverageSearchMsgRejectsNonConversationIDAlias(t *testing.T) { + caller := &searchMsgExecutionCaller{} + _, err := executeSearchMsgResult(caller, "--query", "fixture", "--chat-id", "group-name", "--no-enrich") + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "target_type_mismatch" { + t.Fatalf("error=%#v", err) + } +} + +func TestCrossPlatformCoverageSearchMsgGroupNameAndDefaultWindowMetadata(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[],"hasMore":false}}`} + payload := executeSearchMsg(t, caller, "--group", "项目讨论群", "--no-enrich") + if len(caller.calls) != 3 || caller.calls[0].tool != "search_groups" || + caller.calls[1].tool != "get_conversation_info" || caller.calls[2].tool != "search_messages" { + t.Fatalf("calls=%#v", caller.calls) + } + coverage := payload["timeCoverage"].(map[string]any) + guard := payload["conclusionGuard"].(map[string]any) + if coverage["source"] != "implicit_default" || coverage["days"] != float64(7) || + guard["absenceAcrossAllHistoryAllowed"] != false { + t.Fatalf("coverage=%#v guard=%#v", coverage, guard) + } +} + func TestCrossPlatformCoverageSearchMsgPagesAndEnrichesWithAdvancedFilters(t *testing.T) { caller := &searchMsgExecutionCaller{} payload := executeSearchMsg(t, caller, "--query", "周报", "--chat-id", "cid-1,cid-2", - "--sender", "42,Dsender", - "--at-ids", "43,Dat", + "--sender", testCurrentDOpenID, + "--at-ids", testCurrentDOpenID2, "--is-at-me", "--message-type", "text", "--only-robot", @@ -160,10 +350,8 @@ func TestCrossPlatformCoverageSearchMsgPagesAndEnrichesWithAdvancedFilters(t *te t.Fatalf("first call = %#v", first) } for key, want := range map[string]any{ - "senderUserIds": []string{"42"}, - "senderOpenDingTakIds": []string{"Dsender"}, - "atUserIds": []string{"43"}, - "atOpenDingTakIds": []string{"Dat"}, + "senderOpenDingTakIds": []string{testCurrentDOpenID}, + "atOpenDingTakIds": []string{testCurrentDOpenID2}, "messageType": "text", "onlyRobotMessages": true, "searchConvType": "group", diff --git a/internal/shortcut/targetresolver/resolver.go b/internal/shortcut/targetresolver/resolver.go index f4cf72cd..7dc165b1 100644 --- a/internal/shortcut/targetresolver/resolver.go +++ b/internal/shortcut/targetresolver/resolver.go @@ -9,6 +9,7 @@ package targetresolver import ( + "encoding/base64" stderrors "errors" "fmt" "strings" @@ -105,6 +106,274 @@ func ResolveUser(rt Reader, query string, requirement IdentityRequirement) (User return resolveUserCandidates(ExtractUsers(data), query, requirement) } +// ResolveUserTarget accepts the mixed user target used by public convenience +// flags: a natural name, userId, or current-version openDingTalkId. The local +// format check is deliberately a classifier rather than an existence check. +// Format-valid IDs go directly to the downstream business API; all other +// values use the directory resolver, which can match names and exact userIds. +func ResolveUserTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error) { + value = strings.TrimSpace(value) + if value == "" { + return UserResolution{}, apperrors.NewValidation( + "必须指定用户姓名、userId 或 openDingTalkId", + apperrors.WithReason("missing_target"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("request_validation"), + apperrors.WithExecutionStarted(false), + ) + } + if !LooksLikeCurrentDOpenDingTalkID(value) { + return ResolveUser(rt, value, requirement) + } + if requirement == IdentityUserID { + return UserResolution{}, apperrors.NewValidation( + fmt.Sprintf("用户目标参数类型不匹配：%q 符合当前版本 openDingTalkId 格式，但下游只接受 userId", value), + apperrors.WithReason("target_type_mismatch"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("target_resolution"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + ) + } + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "stable_id", + Selected: User{OpenDingTalkID: value}, + Profile: profilectx.Get(), + }, nil +} + +// ResolveSenderTarget resolves the mixed identity accepted specifically by +// sender convenience flags. Unlike the shared name resolver, it may select a +// unique candidate whose stable userId/openDingTalkId exactly equals the +// supplied value. Natural-name candidates retain the shared fail-closed +// ambiguity behavior. +func ResolveSenderTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error) { + value = strings.TrimSpace(value) + if value == "" || LooksLikeCurrentDOpenDingTalkID(value) { + return ResolveUserTarget(rt, value, requirement) + } + + data, err := rt.CallMCPData("contact", "search_contact_by_key_word", map[string]any{ + "keyword": value, + }) + if err != nil { + return UserResolution{}, err + } + users := filterUsersByIdentity(dedupeUsers(ExtractUsers(data)), requirement) + stableMatches := make([]User, 0, 1) + for _, user := range users { + if strings.TrimSpace(user.UserID) == value || + strings.TrimSpace(user.OpenDingTalkID) == value { + stableMatches = append(stableMatches, user) + } + } + if len(stableMatches) == 1 { + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "stable_id", + Selected: stableMatches[0], + Profile: profilectx.Get(), + }, nil + } + if len(stableMatches) > 1 { + return UserResolution{}, newResolutionError(StatusAmbiguous, "user", value, stableMatches) + } + if cause := incompleteUserSearchCause(data, "通讯录搜索"); cause != "" { + return UserResolution{}, newIncompleteUserResolutionError(value, users, cause) + } + return resolveUserCandidates(users, value, requirement) +} + +// ResolveStableUserTarget accepts only an exact userId or current-version +// openDingTalkId. It is intended for flags whose contract explicitly excludes +// natural names; no unique-name fallback is allowed. +func ResolveStableUserTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error) { + value = strings.TrimSpace(value) + if value == "" { + return UserResolution{}, apperrors.NewValidation( + "必须指定 userId 或 openDingTalkId", + apperrors.WithReason("missing_target"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("request_validation"), + apperrors.WithExecutionStarted(false), + ) + } + if LooksLikeCurrentDOpenDingTalkID(value) { + if requirement == IdentityUserID { + return UserResolution{}, apperrors.NewValidation( + fmt.Sprintf("用户目标参数类型不匹配：%q 是 openDingTalkId，但当前参数只接受 userId", value), + apperrors.WithReason("target_type_mismatch"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("target_resolution"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + ) + } + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "stable_id", + Selected: User{OpenDingTalkID: value}, + Profile: profilectx.Get(), + }, nil + } + + data, err := rt.CallMCPData("contact", "search_contact_by_key_word", map[string]any{ + "keyword": value, + }) + if err != nil { + return UserResolution{}, err + } + users := filterUsersByIdentity(dedupeUsers(ExtractUsers(data)), requirement) + stableMatches := make([]User, 0, 1) + for _, user := range users { + if strings.TrimSpace(user.UserID) == value || + strings.TrimSpace(user.OpenDingTalkID) == value { + stableMatches = append(stableMatches, user) + } + } + if len(stableMatches) == 1 { + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "stable_id", + Selected: stableMatches[0], + Profile: profilectx.Get(), + }, nil + } + if len(stableMatches) > 1 { + return UserResolution{}, newResolutionError(StatusAmbiguous, "user", value, stableMatches) + } + if cause := incompleteUserSearchCause(data, "通讯录搜索"); cause != "" { + return UserResolution{}, newIncompleteUserResolutionError(value, users, cause) + } + return UserResolution{}, apperrors.NewValidation( + fmt.Sprintf("%q 未精确匹配到 userId 或 openDingTalkId", value), + apperrors.WithReason("stable_user_identity_required"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("target_resolution"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + apperrors.WithHint("请先解析目标人员，并传入通讯录结果中原样返回的 userId 或 openDingTalkId"), + apperrors.WithDetails(map[string]any{ + "providedValue": value, + "expectedTypes": []string{"userId", "openDingTalkId"}, + }), + ) +} + +// LooksLikeCurrentDOpenDingTalkID reports whether value has the canonical +// wire format emitted by the current D-version encoder. It does not decrypt +// the value and therefore does not prove that the identity exists or is +// accessible to the current profile. +func LooksLikeCurrentDOpenDingTalkID(value string) bool { + value = strings.TrimSpace(value) + if len(value) < 2 || value[0] != 'D' { + return false + } + + encoded, ok := unescapeCurrentDOpenDingTalkID(value[1:]) + if !ok { + return false + } + ciphertext, err := base64.StdEncoding.Strict().DecodeString(encoded) + if err != nil || len(ciphertext) == 0 || len(ciphertext)%8 != 0 { + return false + } + + // Require the canonical Base64 and escape spelling. This rejects alternate + // but decodable strings and keeps the classifier aligned with the encoder. + canonical := escapeCurrentDOpenDingTalkID(base64.StdEncoding.EncodeToString(ciphertext)) + return canonical == value[1:] +} + +func unescapeCurrentDOpenDingTalkID(value string) (string, bool) { + var decoded strings.Builder + decoded.Grow(len(value)) + for i := 0; i < len(value); i++ { + current := value[i] + if current != 'i' { + if !isASCIIAlphaNumeric(current) { + return "", false + } + decoded.WriteByte(current) + continue + } + if i+1 >= len(value) { + return "", false + } + i++ + switch value[i] { + case 'i': + decoded.WriteByte('i') + case 'P': + decoded.WriteByte('+') + case 'S': + decoded.WriteByte('/') + case 'E': + decoded.WriteByte('=') + default: + return "", false + } + } + return decoded.String(), true +} + +func escapeCurrentDOpenDingTalkID(value string) string { + var encoded strings.Builder + encoded.Grow(len(value)) + for i := 0; i < len(value); i++ { + switch value[i] { + case 'i': + encoded.WriteString("ii") + case '+': + encoded.WriteString("iP") + case '/': + encoded.WriteString("iS") + case '=': + encoded.WriteString("iE") + default: + encoded.WriteByte(value[i]) + } + } + return encoded.String() +} + +func isASCIIAlphaNumeric(value byte) bool { + return value >= '0' && value <= '9' || + value >= 'A' && value <= 'Z' || + value >= 'a' && value <= 'z' +} + +// ValidateExplicitOpenDingTalkID applies the current-version format contract +// to an explicitly typed ID flag. Unlike mixed targets, an invalid explicit ID +// must fail locally instead of falling back to a name or userId lookup. +func ValidateExplicitOpenDingTalkID(flagName, value string) error { + if value == strings.TrimSpace(value) && LooksLikeCurrentDOpenDingTalkID(value) { + return nil + } + return apperrors.NewValidation( + fmt.Sprintf("%s 收到的值不符合当前 D 版本 openDingTalkId 格式", flagName), + apperrors.WithReason("target_type_mismatch"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("request_validation"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + apperrors.WithHint("请传通讯录或消息结果中原样返回的 openDingTalkId；姓名或 userId 请使用对应的混合目标参数"), + apperrors.WithDetails(map[string]any{ + "flag": flagName, + "expectedType": "current_d_openDingTalkId", + }), + ) +} + // ResolveEnterpriseUser resolves an organization member through the same // name-calibrated enterprise search used by `dws aisearch person`. Unlike the // contact search, this source understands organization nicknames and aliases. diff --git a/internal/shortcut/targetresolver/resolver_test.go b/internal/shortcut/targetresolver/resolver_test.go index 4e81b49d..2da5e817 100644 --- a/internal/shortcut/targetresolver/resolver_test.go +++ b/internal/shortcut/targetresolver/resolver_test.go @@ -686,3 +686,278 @@ func TestCrossPlatformCoverageResolverCompletionBranches(t *testing.T) { } }) } + +func TestCrossPlatformCoverageLooksLikeCurrentDOpenDingTalkID(t *testing.T) { + tests := []struct { + name string + value string + want bool + }{ + {name: "canonical current D ciphertext", value: "DAAAAAAAAAAAiE", want: true}, + {name: "synthetic current D ciphertext with escaped plus", value: "DiPiPiPiPiPiPiPiPiPiP8iE", want: true}, + {name: "synthetic current D ciphertext with escaped literal i", value: "DYmJiiYmJiiYmIiE", want: true}, + {name: "surrounding whitespace", value: " DAAAAAAAAAAAiE ", want: true}, + {name: "empty", value: "", want: false}, + {name: "prefix only", value: "D", want: false}, + {name: "lowercase prefix", value: "dAAAAAAAAAAAiE", want: false}, + {name: "natural uppercase D fixture", value: "D-prefix-fixture-user", want: false}, + {name: "natural lowercase d fixture", value: "d-prefix-fixture-user", want: false}, + {name: "invalid escape", value: "DAAAAAiDAAAAAiE", want: false}, + {name: "non alphanumeric body", value: "DAAAAA/AAAAAiE", want: false}, + {name: "invalid base64", value: "Dabc", want: false}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got := LooksLikeCurrentDOpenDingTalkID(tc.value); got != tc.want { + t.Fatalf("LooksLikeCurrentDOpenDingTalkID(%q) = %v, want %v", tc.value, got, tc.want) + } + }) + } +} + +func TestResolveUserTargetUsesFormatClassificationWithoutIDPreflight(t *testing.T) { + const openID = "DAAAAAAAAAAAiE" + calls := 0 + resolved, err := ResolveUserTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + calls++ + return nil, stderrors.New("unexpected remote call") + }), openID, IdentityAny) + if err != nil { + t.Fatal(err) + } + if calls != 0 || resolved.MatchType != "stable_id" || resolved.Selected.OpenDingTalkID != openID { + t.Fatalf("calls=%d resolved=%#v", calls, resolved) + } +} + +func TestCrossPlatformCoverageResolveSenderTargetScopesStableIDPreferenceToSenderInputs(t *testing.T) { + calls := 0 + reader := resolverReaderFunc(func(product, tool string, params map[string]any) (map[string]any, error) { + calls++ + if product != "contact" || tool != "search_contact_by_key_word" { + t.Fatalf("unexpected tool %s/%s", product, tool) + } + query := fmt.Sprint(params["keyword"]) + switch query { + case "D-prefix-fixture-user": + return map[string]any{"result": []any{map[string]any{ + "userId": "fixture-user-d-upper", "openDingTalkId": "D-directory-value", "name": "D-prefix-fixture-user", + }}}, nil + case "d-prefix-fixture-user": + return map[string]any{"result": []any{map[string]any{ + "userId": "fixture-user-d-lower", "openDingTalkId": "D-directory-value-2", "name": "d-prefix-fixture-user", + }}}, nil + case "fixture-user-id": + return map[string]any{"result": []any{ + map[string]any{"userId": "other", "name": "相似候选"}, + map[string]any{"userId": "fixture-user-id", "openDingTalkId": "D-directory-value-3", "name": "测试目标用户"}, + }}, nil + default: + t.Fatalf("unexpected query %q", query) + return nil, nil + } + }) + + for _, query := range []string{"D-prefix-fixture-user", "d-prefix-fixture-user"} { + _, err := ResolveSenderTarget(reader, query, IdentityAny) + if err != nil { + t.Fatalf("%s: %v", query, err) + } + } + + _, err := ResolveUser(reader, "fixture-user-id", IdentityAny) + var ambiguous *apperrors.Error + if !stderrors.As(err, &ambiguous) || ambiguous.Reason != "resolution_ambiguous" { + t.Fatalf("shared name resolver error = %#v, want resolution_ambiguous", err) + } + + resolved, err := ResolveSenderTarget(reader, "fixture-user-id", IdentityAny) + if err != nil { + t.Fatal(err) + } + if resolved.MatchType != "stable_id" || resolved.Selected.UserID != "fixture-user-id" { + t.Fatalf("exact sender userId resolution = %#v", resolved) + } + if calls != 4 { + t.Fatalf("calls=%d", calls) + } +} + +func TestValidateExplicitOpenDingTalkIDNeverFallsBack(t *testing.T) { + if err := ValidateExplicitOpenDingTalkID("--open-dingtalk-id", "DAAAAAAAAAAAiE"); err != nil { + t.Fatalf("valid format: %v", err) + } + err := ValidateExplicitOpenDingTalkID("--open-dingtalk-id", "D-prefix-fixture-user") + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "target_type_mismatch" { + t.Fatalf("error=%#v", err) + } + err = ValidateExplicitOpenDingTalkID("--open-dingtalk-id", " DAAAAAAAAAAAiE ") + if !stderrors.As(err, &typed) || typed.Reason != "target_type_mismatch" { + t.Fatalf("whitespace-wrapped explicit ID error=%#v", err) + } +} + +func TestCrossPlatformCoverageResolveStableUserTargetRejectsNaturalNameButAcceptsExactUserID(t *testing.T) { + reader := resolverReaderFunc(func(product, tool string, params map[string]any) (map[string]any, error) { + if product != "contact" || tool != "search_contact_by_key_word" { + t.Fatalf("unexpected tool %s/%s", product, tool) + } + return map[string]any{"result": []any{ + map[string]any{"userId": "fixture-user-id", "openDingTalkId": "DAAAAAAAAAAAiE", "name": "测试用户甲"}, + }}, nil + }) + + resolved, err := ResolveStableUserTarget(reader, "fixture-user-id", IdentityAny) + if err != nil { + t.Fatal(err) + } + if resolved.MatchType != "stable_id" || resolved.Selected.UserID != "fixture-user-id" { + t.Fatalf("exact userId resolution = %#v", resolved) + } + + _, err = ResolveStableUserTarget(reader, "测试用户甲", IdentityAny) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "stable_user_identity_required" { + t.Fatalf("natural name error = %#v", err) + } +} + +func TestResolveStableUserTargetRoutesCurrentDWithoutDirectoryLookup(t *testing.T) { + const openID = "DAAAAAAAAAAAiE" + calls := 0 + resolved, err := ResolveStableUserTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + calls++ + return nil, stderrors.New("unexpected remote call") + }), openID, IdentityAny) + if err != nil { + t.Fatal(err) + } + if calls != 0 || resolved.Selected.OpenDingTalkID != openID { + t.Fatalf("calls=%d resolved=%#v", calls, resolved) + } +} + +func TestStableIdentityExactMatchWinsEvenWhenDirectoryPageIsIncomplete(t *testing.T) { + reader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{ + "result": []any{ + map[string]any{"userId": "fixture-user-id", "openDingTalkId": "DAAAAAAAAAAAiE", "name": "测试目标用户"}, + map[string]any{"userId": "other", "name": "其他候选"}, + }, + "hasMore": true, + }, nil + }) + for _, resolve := range []struct { + name string + fn func(Reader, string, IdentityRequirement) (UserResolution, error) + }{ + {name: "sender", fn: ResolveSenderTarget}, + {name: "stable-only", fn: ResolveStableUserTarget}, + } { + t.Run(resolve.name, func(t *testing.T) { + resolved, err := resolve.fn(reader, "fixture-user-id", IdentityAny) + if err != nil { + t.Fatal(err) + } + if resolved.MatchType != "stable_id" || resolved.Selected.UserID != "fixture-user-id" { + t.Fatalf("resolved=%#v", resolved) + } + }) + } +} + +func TestCrossPlatformCoverageMixedIdentityResolutionFailureEdges(t *testing.T) { + unexpectedReader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return nil, stderrors.New("directory unavailable") + }) + + for _, tc := range []struct { + name string + resolve func(Reader, string, IdentityRequirement) (UserResolution, error) + value string + requirement IdentityRequirement + wantReason string + }{ + {name: "mixed empty", resolve: ResolveUserTarget, wantReason: "missing_target"}, + {name: "mixed open id requires user id", resolve: ResolveUserTarget, value: "DAAAAAAAAAAAiE", requirement: IdentityUserID, wantReason: "target_type_mismatch"}, + {name: "stable empty", resolve: ResolveStableUserTarget, wantReason: "missing_target"}, + {name: "stable open id requires user id", resolve: ResolveStableUserTarget, value: "DAAAAAAAAAAAiE", requirement: IdentityUserID, wantReason: "target_type_mismatch"}, + } { + t.Run(tc.name, func(t *testing.T) { + _, err := tc.resolve(unexpectedReader, tc.value, tc.requirement) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != tc.wantReason { + t.Fatalf("error=%#v, want reason %q", err, tc.wantReason) + } + }) + } + + if _, err := ResolveUserTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { + t.Fatalf("mixed directory error=%v", err) + } + if _, err := ResolveSenderTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { + t.Fatalf("sender directory error=%v", err) + } + if _, err := ResolveStableUserTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { + t.Fatalf("stable directory error=%v", err) + } +} + +func TestCrossPlatformCoverageStableIdentityAmbiguousAndIncompleteEdges(t *testing.T) { + duplicateReader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{"result": []any{ + map[string]any{"userId": "duplicate", "openDingTalkId": "D-one", "name": "甲"}, + map[string]any{"userId": "other", "openDingTalkId": "duplicate", "name": "乙"}, + }}, nil + }) + for _, resolve := range []struct { + name string + fn func(Reader, string, IdentityRequirement) (UserResolution, error) + }{ + {name: "sender", fn: ResolveSenderTarget}, + {name: "stable", fn: ResolveStableUserTarget}, + } { + t.Run(resolve.name+" ambiguous", func(t *testing.T) { + _, err := resolve.fn(duplicateReader, "duplicate", IdentityAny) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_ambiguous" { + t.Fatalf("error=%#v", err) + } + }) + } + + incompleteReader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{ + "result": []any{map[string]any{"userId": "other", "name": "其他"}}, + "hasMore": true, + }, nil + }) + for _, resolve := range []struct { + name string + fn func(Reader, string, IdentityRequirement) (UserResolution, error) + }{ + {name: "sender", fn: ResolveSenderTarget}, + {name: "stable", fn: ResolveStableUserTarget}, + } { + t.Run(resolve.name+" incomplete", func(t *testing.T) { + _, err := resolve.fn(incompleteReader, "missing", IdentityAny) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_incomplete" { + t.Fatalf("error=%#v", err) + } + }) + } +} + +func TestCrossPlatformCoverageCurrentDCodecEdges(t *testing.T) { + if _, ok := unescapeCurrentDOpenDingTalkID("abcdi"); ok { + t.Fatal("dangling escape unexpectedly accepted") + } + if decoded, ok := unescapeCurrentDOpenDingTalkID("iS"); !ok || decoded != "/" { + t.Fatalf("slash escape decoded=%q ok=%v", decoded, ok) + } + if got := escapeCurrentDOpenDingTalkID("i+/="); got != "iiiPiSiE" { + t.Fatalf("escaped=%q", got) + } +} diff --git a/test/mock_mcp/mock_mcp_smoke_test.go b/test/mock_mcp/mock_mcp_smoke_test.go index 58e5127b..d84e704f 100644 --- a/test/mock_mcp/mock_mcp_smoke_test.go +++ b/test/mock_mcp/mock_mcp_smoke_test.go @@ -33,6 +33,7 @@ import ( const ( mockMCPSmokeHelperEnv = "DWS_MOCK_MCP_SMOKE_HELPER" mockMCPSmokeCAEnv = "DWS_MOCK_MCP_SMOKE_CA_FILE" + mockCurrentDOpenID = "DAAAAAAAAAAAiE" ) type recordedToolCall struct { @@ -293,7 +294,7 @@ func TestMultiIME2E_NaturalTargetsCompletenessAndWriteBoundaries(t *testing.T) { stdout, stderr, err := runCLI(t, env, "--token", "ci-smoke-token", "--format", "json", "chat", "+messages-send", "--as", "user", - "--user-query", "张三", "--text", "你好", "--yes", + "--user-query", "测试用户甲", "--text", "你好", "--yes", ) if err != nil { t.Fatalf("natural send failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr) @@ -302,7 +303,7 @@ func TestMultiIME2E_NaturalTargetsCompletenessAndWriteBoundaries(t *testing.T) { if len(calls) != 2 || calls[0].tool != "search_contact_by_key_word" || calls[1].tool != "send_personal_message" { t.Fatalf("calls = %#v, want resolve + one send", calls) } - if calls[1].arguments["receiverOpenDingTalkId"] != "D-user-1" { + if calls[1].arguments["receiverOpenDingTalkId"] != mockCurrentDOpenID { t.Fatalf("send target = %#v", calls[1].arguments) } assertMultiIMCallsAreLocalAndAuthorized(t, calls) @@ -473,7 +474,7 @@ func TestMultiIME2E_NaturalTargetsCompletenessAndWriteBoundaries(t *testing.T) { t.Fatalf("messages = %#v", payload["messages"]) } message, _ := messages[0].(map[string]any) - if message["messageId"] != "msg-1" || message["senderId"] != "D-sender" || message["senderType"] != "user" { + if message["messageId"] != "msg-1" || message["senderId"] != mockCurrentDOpenID || message["senderType"] != "user" { t.Fatalf("projected message = %#v", message) } }) @@ -483,7 +484,7 @@ func TestMultiIME2E_NaturalTargetsCompletenessAndWriteBoundaries(t *testing.T) { stdout, stderr, err := runCLI(t, env, "--token", "ci-smoke-token", "--format", "json", "chat", "+chat-create", "--name", "新群", - "--member-query", "张三", "--dry-run", "--yes", + "--member-query", "测试用户甲", "--dry-run", "--yes", ) if err != nil { t.Fatalf("chat-create dry-run failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr) @@ -505,7 +506,7 @@ func TestMultiIME2E_NaturalTargetsCompletenessAndWriteBoundaries(t *testing.T) { "--token", "ci-smoke-token", "--format", "json", "chat", "+messages-reply", "--conversation-id", "cid-1", "--message-id", "msg-1", - "--ref-sender", "D-sender", "--text", "收到", + "--ref-sender", mockCurrentDOpenID, "--text", "收到", "--idempotency-key", "reply-key", "--yes", ) if err != nil { @@ -532,7 +533,7 @@ func multiIMMockResponse(tool string, arguments map[string]any, mcpBaseURL, reso if arguments["keyword"] == "同名用户" { return `{"result":[{"name":"同名用户","userId":"u1","openDingTalkId":"D1"},{"name":"同名用户","userId":"u2","openDingTalkId":"D2"}]}` } - return `{"result":[{"name":"张三","userId":"user-1","openDingTalkId":"D-user-1"}]}` + return `{"result":[{"name":"测试用户甲","userId":"user-1","openDingTalkId":"` + mockCurrentDOpenID + `"}]}` case "search_groups": if arguments["keyword"] == "资源群" { return `{"result":[{"title":"资源群","openConversationId":"cid-resources"}]}` @@ -540,9 +541,9 @@ func multiIMMockResponse(tool string, arguments map[string]any, mcpBaseURL, reso return `{"result":[{"title":"项目群","openConversationId":"cid-1"}]}` case "list_conversation_message_v2": if arguments["openconversation_id"] == "cid-resources" { - return `{"result":{"hasMore":false,"messages":[{"openMessageId":"msg-resource","openConversationId":"cid-resources","sender":{"name":"张三","openDingTalkId":"D-sender","senderType":"user"},"msgType":"file","content":"{\"mediaId\":\"@media-1\"}","createTime":"2026-08-03 10:00:00"}]}}` + return `{"result":{"hasMore":false,"messages":[{"openMessageId":"msg-resource","openConversationId":"cid-resources","sender":{"name":"测试用户甲","openDingTalkId":"` + mockCurrentDOpenID + `","senderType":"user"},"msgType":"file","content":"{\"mediaId\":\"@media-1\"}","createTime":"2026-08-03 10:00:00"}]}}` } - return `{"result":{"hasMore":false,"messages":[{"openMessageId":"msg-1","openConversationId":"cid-1","sender":{"name":"张三","openDingTalkId":"D-sender","senderType":"user"},"msgType":"text","content":"进度正常","createTime":"2026-08-03 10:00:00"}]}}` + return `{"result":{"hasMore":false,"messages":[{"openMessageId":"msg-1","openConversationId":"cid-1","sender":{"name":"测试用户甲","openDingTalkId":"` + mockCurrentDOpenID + `","senderType":"user"},"msgType":"text","content":"进度正常","createTime":"2026-08-03 10:00:00"}]}}` case "get_resource_download_url": body, _ := json.Marshal(map[string]any{"result": map[string]any{ "resourceUrl": resourceURL, @@ -561,7 +562,7 @@ func multiIMMockResponse(tool string, arguments map[string]any, mcpBaseURL, reso if arguments["keyword"] == "分页失败" && fmt.Sprint(arguments["cursor"]) == "c2" { return `{"success":false,"code":"MOCK_PAGE_FAILURE","message":"simulated second page failure"}` } - return `{"result":{"messages":[{"openMessageId":"search-msg-1","openConversationId":"cid-1","senderOpenDingTalkId":"D-sender","content":"first page"}],"hasMore":true,"nextCursor":"c2"}}` + return `{"result":{"messages":[{"openMessageId":"search-msg-1","openConversationId":"cid-1","senderOpenDingTalkId":"` + mockCurrentDOpenID + `","content":"first page"}],"hasMore":true,"nextCursor":"c2"}}` case "get_current_user_profile": return `{"result":[{"orgEmployeeModel":{"userId":"self-user"}}]}` case "create_group_conversation": From 12e663269208a1539d7bce39a145cd0dd89e5463 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Fri, 14 Aug 2026 01:00:52 +0800 Subject: [PATCH 093/250] fix(chat): preserve sender identity uncertainty --- internal/shortcut/smart/chat_messages.go | 68 +++++--- internal/shortcut/smart/chat_messages_test.go | 150 ++++++++++++++---- internal/shortcut/smart/search_msg.go | 54 ++++--- .../smart/search_msg_execution_test.go | 125 ++++++++++++--- internal/shortcut/targetresolver/resolver.go | 130 +++++++++------ .../shortcut/targetresolver/resolver_test.go | 148 +++++++++++------ 6 files changed, 480 insertions(+), 195 deletions(-) diff --git a/internal/shortcut/smart/chat_messages.go b/internal/shortcut/smart/chat_messages.go index 83c94868..92ebfbff 100644 --- a/internal/shortcut/smart/chat_messages.go +++ b/internal/shortcut/smart/chat_messages.go @@ -57,7 +57,7 @@ var ChatMessages = shortcut.Shortcut{ Command: "+chat-messages", Product: "chat", Description: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId，唯一解析后按 senderId 筛选同一次读取结果；不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + + Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选，但无稳定 senderId 命中不得作完整否定结论。不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + @@ -83,7 +83,7 @@ var ChatMessages = shortcut.Shortcut{ }, Selection: contract.SelectionSpec{ AgentSummary: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId，唯一解析后按 senderId 筛选同一次读取结果；不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + + UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选，但无稳定 senderId 命中不得作完整否定结论。不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + @@ -104,7 +104,7 @@ var ChatMessages = shortcut.Shortcut{ {Name: "user", Type: shortcut.FlagString, Desc: "单聊对方的 userId，与 --group 互斥"}, {Name: "user-query", Type: shortcut.FlagString, Desc: "按姓名解析唯一 openDingTalkId 的兼容入口", Hidden: true}, {Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊对方的 openDingTalkId，与 --group/--user 互斥"}, - {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；自动唯一解析并筛选同一次会话读取结果"}, + {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录故障不阻断原值 userId 筛选"}, {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析发送者的兼容入口（可选，可重复或逗号分隔）"}, {Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；--time 必须是 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD；省略时从当前时间向前读取最近消息"}, {Name: "start", Type: shortcut.FlagString, Desc: "范围开始时间（可选、包含），支持 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD"}, @@ -230,8 +230,6 @@ type chatMessagesSenderFilter struct { inputs []string inputMode string stableIDs map[string]bool - hasUserIDs bool - hasOpenIDs bool resolutions []targetresolver.UserResolution resolutionFailure map[string]any resolutionErr error @@ -300,7 +298,7 @@ func resolveOptionalChatMessagesSenderFilter(rt *shortcut.RuntimeContext) chatMe } filter.resolutions = resolutions - filter.hasUserIDs, filter.hasOpenIDs = addChatMessagesResolvedSenderIDs(filter.stableIDs, resolutions) + addChatMessagesResolvedSenderIDs(filter.stableIDs, resolutions) filter.applied = true return filter } @@ -319,20 +317,15 @@ func uniqueChatMessageTargets(values []string) []string { return result } -func addChatMessagesResolvedSenderIDs(ids map[string]bool, resolutions []targetresolver.UserResolution) (bool, bool) { - hasUserIDs := false - hasOpenIDs := false +func addChatMessagesResolvedSenderIDs(ids map[string]bool, resolutions []targetresolver.UserResolution) { for _, resolution := range resolutions { if identity := strings.TrimSpace(resolution.Selected.UserID); identity != "" { ids[identity] = true - hasUserIDs = true } if identity := strings.TrimSpace(resolution.Selected.OpenDingTalkID); identity != "" { ids[identity] = true - hasOpenIDs = true } } - return hasUserIDs, hasOpenIDs } // applyOptionalChatMessagesSenderFilter fails closed when an explicitly @@ -401,14 +394,6 @@ func applyOptionalChatMessagesSenderFilter( } if filter.stableIDs[identity] { filtered = append(filtered, item) - continue - } - if targetresolver.LooksLikeCurrentDOpenDingTalkID(identity) { - if !filter.hasOpenIDs { - unverifiableMessageIDs = append(unverifiableMessageIDs, chatMessagesMessageID(item)) - } - } else if !filter.hasUserIDs { - unverifiableMessageIDs = append(unverifiableMessageIDs, chatMessagesMessageID(item)) } } if len(unverifiableMessageIDs) > 0 { @@ -433,12 +418,27 @@ func applyOptionalChatMessagesSenderFilter( payload["complete"] = false payload["partial"] = len(filtered) > 0 } + unverifiedSenderInputs := chatMessagesUnverifiedSenderInputs(filtered, filter.resolutions) + if len(unverifiedSenderInputs) > 0 { + failures, _ := payload["failures"].([]map[string]any) + failures = append(failures, map[string]any{ + "stage": "sender_identity_verification", + "inputs": unverifiedSenderInputs, + "error": "通讯录未能确认这些混合发送者参数是姓名还是 userId；已按精确 userId 过滤，但不能据此作完整否定结论", + }) + payload["failures"] = failures + payload["failedCount"] = len(failures) + payload["complete"] = false + payload["partial"] = len(filtered) > 0 + } payload["messages"] = projectChatMessages(filtered, !rt.Bool("no-reactions")) payload["count"] = len(filtered) payload["resolvedFilters"] = map[string]any{"senders": filter.resolutions} filterStatus := "applied" if filter.scopeErr != nil { filterStatus = "scope_unverified" + } else if len(unverifiedSenderInputs) > 0 { + filterStatus = "identity_unverified" } payload["senderFilter"] = map[string]any{ "requested": true, @@ -447,6 +447,9 @@ func applyOptionalChatMessagesSenderFilter( "applied": true, "status": filterStatus, } + if len(unverifiedSenderInputs) > 0 { + payload["senderFilter"].(map[string]any)["unverifiedInputs"] = unverifiedSenderInputs + } identityResult := map[string]any{ "status": "evaluated", "nameComparisonAllowed": false, @@ -457,17 +460,32 @@ func applyOptionalChatMessagesSenderFilter( identityResult["status"] = "scope_unverified" identityResult["negativeConclusionAllowed"] = false identityResult["hint"] = "部分消息缺少稳定 senderId，当前结果不能用于断言该人员没有发过消息。" + } else if len(unverifiedSenderInputs) > 0 { + identityResult["status"] = "identity_unverified" + identityResult["negativeConclusionAllowed"] = false + identityResult["hint"] = "当前混合发送者参数未能经通讯录确认；已按原值 userId 精确比较，若无命中仍不能断言该人员没有发过消息。" } payload["identityResult"] = identityResult return filtered } -func chatMessagesMessageID(item map[string]any) string { - messageID := chatmsg.StableMessageID(item) - if messageID == "" { - return "" +func chatMessagesUnverifiedSenderInputs( + messages []map[string]any, + resolutions []targetresolver.UserResolution, +) []string { + observed := map[string]bool{} + for _, message := range messages { + if senderID := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(message))); senderID != "" && senderID != "" { + observed[senderID] = true + } } - return messageID + values := make([]string, 0) + for _, resolution := range resolutions { + if targetresolver.IsUnverifiedUserIDResolution(resolution) && !observed[resolution.Selected.UserID] { + values = append(values, resolution.Query) + } + } + return uniqueChatMessageTargets(values) } func attachUnfilteredSenderIdentitySemantics(payload map[string]any, filter chatMessagesSenderFilter) { diff --git a/internal/shortcut/smart/chat_messages_test.go b/internal/shortcut/smart/chat_messages_test.go index 66ca0679..24201f12 100644 --- a/internal/shortcut/smart/chat_messages_test.go +++ b/internal/shortcut/smart/chat_messages_test.go @@ -27,6 +27,7 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) @@ -578,14 +579,13 @@ func TestCrossPlatformCoverageChatMessagesAdditionalValidationAndHelpers(t *test } } -func TestChatMessagesSenderScopeRejectsUnmappedIdentityFamily(t *testing.T) { +func TestChatMessagesSenderScopeIgnoresNonMatchingIdentityFamily(t *testing.T) { filter := chatMessagesSenderFilter{ - requested: true, - applied: true, - inputs: []string{"DAAAAAAAAAAAiE"}, - inputMode: "sender", - stableIDs: map[string]bool{"DAAAAAAAAAAAiE": true}, - hasOpenIDs: true, + requested: true, + applied: true, + inputs: []string{"DAAAAAAAAAAAiE"}, + inputMode: "sender", + stableIDs: map[string]bool{"DAAAAAAAAAAAiE": true}, } payload := map[string]any{ "complete": true, @@ -594,26 +594,106 @@ func TestChatMessagesSenderScopeRejectsUnmappedIdentityFamily(t *testing.T) { filtered := applyOptionalChatMessagesSenderFilter( chatMessagesRuntimeForTest(t, nil), payload, - []map[string]any{{"openMessageId": "m-user-family", "senderUserId": "user-1"}}, + []map[string]any{ + {"openMessageId": "wanted", "senderOpenDingTalkId": "DAAAAAAAAAAAiE"}, + {"openMessageId": "other-family", "senderUserId": "other-user"}, + }, &filter, ) - if len(filtered) != 0 || filter.scopeErr == nil || payload["complete"] != false { + if len(filtered) != 1 || filter.scopeErr != nil || payload["complete"] != true || payload["count"] != 1 { t.Fatalf("filtered=%#v filter=%#v payload=%#v", filtered, filter, payload) } } func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) { - t.Run("direct resolution stops after first error", func(t *testing.T) { + t.Run("unrelated unique directory candidate never replaces the supplied user id", func(t *testing.T) { + fake := &platformCoverageCaller{ + contactSearchResult: `{"result":[{"userId":"other-user","name":"其他用户"}],"hasMore":false}`, + } + helpers.InitDeps(fake) + filter := resolveOptionalChatMessagesSenderFilter(chatMessagesRuntimeForTest(t, map[string]string{ + "sender": "fixture-user-id", + })) + if !filter.applied || !filter.stableIDs["fixture-user-id"] || filter.stableIDs["other-user"] { + t.Fatalf("filter=%#v", filter) + } + }) + + t.Run("direct user ids continue when directory is unavailable", func(t *testing.T) { fake := &platformCoverageCaller{failTool: "contact/search_contact_by_key_word"} helpers.InitDeps(fake) filter := resolveOptionalChatMessagesSenderFilter(chatMessagesRuntimeForTest(t, map[string]string{ "sender": testCurrentDOpenID + ",fixture-name,ignored-name", })) - if filter.applied || filter.resolutionErr == nil || len(fake.calls) != 1 { + if !filter.applied || filter.resolutionErr != nil || len(fake.calls) != 2 || + !filter.stableIDs["fixture-name"] || !filter.stableIDs["ignored-name"] { t.Fatalf("filter=%#v calls=%#v", filter, fake.calls) } }) + t.Run("unverified mixed sender becomes verified by an exact sender id match", func(t *testing.T) { + payload := map[string]any{"complete": true, "failures": []map[string]any{}} + resolution := targetresolver.UserResolution{ + Status: targetresolver.StatusResolved, + EntityType: "user", + Query: "stable-user-id", + MatchType: "unverified_user_id", + Selected: targetresolver.User{UserID: "stable-user-id"}, + } + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{"stable-user-id"}, + inputMode: "sender", + stableIDs: map[string]bool{"stable-user-id": true}, + resolutions: []targetresolver.UserResolution{resolution}, + } + filtered := applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), payload, + []map[string]any{ + {"openMessageId": "wanted", "senderUserId": "stable-user-id"}, + {"openMessageId": "other", "senderUserId": "other-user"}, + }, &filter, + ) + if len(filtered) != 1 || payload["complete"] != true || len(payload["failures"].([]map[string]any)) != 0 { + t.Fatalf("filtered=%#v payload=%#v", filtered, payload) + } + identity := payload["identityResult"].(map[string]any) + if identity["status"] != "evaluated" || identity["negativeConclusionAllowed"] != true { + t.Fatalf("identityResult=%#v", identity) + } + }) + + t.Run("unverified mixed sender without a match blocks complete negative conclusion", func(t *testing.T) { + payload := map[string]any{"complete": true, "failures": []map[string]any{}} + resolution := targetresolver.UserResolution{ + Status: targetresolver.StatusResolved, + EntityType: "user", + Query: "possibly-a-name", + MatchType: "unverified_user_id", + Selected: targetresolver.User{UserID: "possibly-a-name"}, + } + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{"possibly-a-name"}, + inputMode: "sender", + stableIDs: map[string]bool{"possibly-a-name": true}, + resolutions: []targetresolver.UserResolution{resolution}, + } + filtered := applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), payload, + []map[string]any{{"openMessageId": "other", "senderUserId": "other-user"}}, &filter, + ) + if len(filtered) != 0 || payload["complete"] != false || payload["failedCount"] != 1 { + t.Fatalf("filtered=%#v payload=%#v", filtered, payload) + } + identity := payload["identityResult"].(map[string]any) + if identity["status"] != "identity_unverified" || identity["negativeConclusionAllowed"] != false { + t.Fatalf("identityResult=%#v", identity) + } + }) + t.Run("dedupes blanks and repeated values", func(t *testing.T) { got := uniqueChatMessageTargets([]string{"", " ", "one", "one", " two "}) if want := []string{"one", "two"}; !reflect.DeepEqual(got, want) { @@ -634,15 +714,14 @@ func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) } }) - t.Run("rejects missing and unmapped identity families", func(t *testing.T) { + t.Run("rejects only missing identities", func(t *testing.T) { payload := map[string]any{"complete": true, "failures": []map[string]any{}} filter := chatMessagesSenderFilter{ - requested: true, - applied: true, - inputs: []string{"fixture"}, - inputMode: "sender", - stableIDs: map[string]bool{"wanted-user": true}, - hasUserIDs: true, + requested: true, + applied: true, + inputs: []string{"fixture"}, + inputMode: "sender", + stableIDs: map[string]bool{"wanted-user": true}, } filtered := applyOptionalChatMessagesSenderFilter( chatMessagesRuntimeForTest(t, nil), @@ -654,26 +733,43 @@ func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) }, &filter, ) - if len(filtered) != 1 || filter.scopeErr == nil || chatMessagesMessageID(map[string]any{}) != "" || chatMessagesMessageID(filtered[0]) != "wanted" { + if len(filtered) != 1 || filter.scopeErr == nil { t.Fatalf("filtered=%#v filter=%#v payload=%#v", filtered, filter, payload) } }) - t.Run("rejects user identity when only open ids were resolved", func(t *testing.T) { + t.Run("ignores user identity when only open ids were resolved", func(t *testing.T) { payload := map[string]any{"complete": true, "failures": []map[string]any{}} filter := chatMessagesSenderFilter{ - requested: true, - applied: true, - inputs: []string{testCurrentDOpenID}, - inputMode: "sender", - stableIDs: map[string]bool{testCurrentDOpenID: true}, - hasOpenIDs: true, + requested: true, + applied: true, + inputs: []string{testCurrentDOpenID}, + inputMode: "sender", + stableIDs: map[string]bool{testCurrentDOpenID: true}, } applyOptionalChatMessagesSenderFilter( chatMessagesRuntimeForTest(t, nil), payload, []map[string]any{{"senderUserId": "other-user"}}, &filter, ) - if filter.scopeErr == nil { + if filter.scopeErr != nil || payload["complete"] != true { + t.Fatalf("filter=%#v", filter) + } + }) + + t.Run("ignores open identity when only user ids were resolved", func(t *testing.T) { + payload := map[string]any{"complete": true, "failures": []map[string]any{}} + filter := chatMessagesSenderFilter{ + requested: true, + applied: true, + inputs: []string{"wanted-user"}, + inputMode: "sender", + stableIDs: map[string]bool{"wanted-user": true}, + } + applyOptionalChatMessagesSenderFilter( + chatMessagesRuntimeForTest(t, nil), payload, + []map[string]any{{"senderOpenDingTalkId": testCurrentDOpenID}}, &filter, + ) + if filter.scopeErr != nil || payload["complete"] != true { t.Fatalf("filter=%#v", filter) } }) diff --git a/internal/shortcut/smart/search_msg.go b/internal/shortcut/smart/search_msg.go index 2224d542..a3f6c011 100644 --- a/internal/shortcut/smart/search_msg.go +++ b/internal/shortcut/smart/search_msg.go @@ -35,7 +35,7 @@ import ( // search hits through list_messages_by_ids in chunks of 50. A later-page or // enrichment failure never turns a partial result into a false success: the // output carries an explicit failure ledger and complete=false. -const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话。--group/--groups 接受群名或 openConversationId，--sender/--senders 接受姓名、userId 或 openDingTalkId，并统一唯一解析为稳定 ID。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + +const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话。--group/--groups 接受群名或 openConversationId，--sender/--senders 接受姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 执行，但无稳定 senderId 命中不得作完整否定结论。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + "显式指定会话时会先验证 CID，再执行有界全局扫描并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID。" + "--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。" + "--download-resources 使用安全本地路径、默认不覆盖和原子落盘。" @@ -86,8 +86,8 @@ var SearchMsg = shortcut.Shortcut{ {Name: "groups", Type: shortcut.FlagStringSlice, Desc: "多个群名或 openConversationId；可混合输入并逐项唯一解析"}, {Name: "chat-id", Type: shortcut.FlagStringSlice, Desc: "--groups 的 lark-cli 对齐别名；只接受 openConversationId"}, {Name: "chat-query", Type: shortcut.FlagStringSlice, Desc: "显式按群名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, - {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "多个发送者姓名、userId 或 openDingTalkId；可混合输入并逐项唯一解析"}, - {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；--senders 的兼容别名"}, + {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录故障不阻断原值 userId 查询"}, + {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；--senders 的兼容别名，保留同样的三态解析与安全降级语义"}, {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, {Name: "at-me", Type: shortcut.FlagBool, Desc: "只搜索 @我 的消息"}, {Name: "is-at-me", Type: shortcut.FlagBool, Desc: "--at-me 的 lark-cli 对齐别名"}, @@ -278,6 +278,15 @@ var SearchMsg = shortcut.Shortcut{ return searchSenderScopeUnverifiedError(resolvedFilters.Senders, unverifiableMessageIDs) } } + unverifiedSenderInputs := searchUnverifiedSenderInputs(messages, resolvedFilters.Senders) + if len(unverifiedSenderInputs) > 0 { + failures = append(failures, map[string]any{ + "stage": "sender_identity_verification", + "inputs": unverifiedSenderInputs, + "error": "通讯录未能确认这些混合发送者参数是姓名还是 userId；已按精确 userId 执行，但不能据此作完整否定结论", + }) + complete = false + } order := strings.ToLower(strings.TrimSpace(rt.StrFirst("order", "sort"))) if order == "" { @@ -309,11 +318,15 @@ var SearchMsg = shortcut.Shortcut{ } if len(resolvedFilters.Senders) > 0 { payload["senderScope"] = map[string]any{ - "targetsResolved": true, + "targetsResolved": len(unverifiedSenderInputs) == 0, "filterApplied": true, "filterMode": "server_and_client", "resultsWithinScope": true, } + if len(unverifiedSenderInputs) > 0 { + payload["senderScope"].(map[string]any)["status"] = "identity_unverified" + payload["senderScope"].(map[string]any)["unverifiedInputs"] = unverifiedSenderInputs + } } if scopedSearch { payload["scope"] = searchScopePayload(requestedConversationIDs, paginationKnown && !hasMore) @@ -663,16 +676,12 @@ func filterSearchSenderScope( resolutions []targetresolver.UserResolution, ) ([]map[string]any, []string) { allowed := map[string]bool{} - hasUserIDs := false - hasOpenIDs := false for _, resolution := range resolutions { if value := strings.TrimSpace(resolution.Selected.UserID); value != "" { allowed[value] = true - hasUserIDs = true } if value := strings.TrimSpace(resolution.Selected.OpenDingTalkID); value != "" { allowed[value] = true - hasOpenIDs = true } } @@ -690,25 +699,28 @@ func filterSearchSenderScope( } if allowed[senderID] { filtered = append(filtered, message) - continue - } - if targetresolver.LooksLikeCurrentDOpenDingTalkID(senderID) { - if !hasOpenIDs { - unverifiable = append(unverifiable, searchScopeMessageID(message)) - } - } else if !hasUserIDs { - unverifiable = append(unverifiable, searchScopeMessageID(message)) } } return filtered, uniqueSearchStrings(unverifiable) } -func searchScopeMessageID(message map[string]any) string { - messageID := strings.TrimSpace(fmt.Sprint(searchMsgMessageID(message))) - if messageID == "" || messageID == "" { - return "" +func searchUnverifiedSenderInputs( + messages []map[string]any, + resolutions []targetresolver.UserResolution, +) []string { + observed := map[string]bool{} + for _, message := range messages { + if senderID := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(message))); senderID != "" && senderID != "" { + observed[senderID] = true + } } - return messageID + values := make([]string, 0) + for _, resolution := range resolutions { + if targetresolver.IsUnverifiedUserIDResolution(resolution) && !observed[resolution.Selected.UserID] { + values = append(values, resolution.Query) + } + } + return uniqueSearchStrings(values) } func searchSenderScopeUnverifiedError( diff --git a/internal/shortcut/smart/search_msg_execution_test.go b/internal/shortcut/smart/search_msg_execution_test.go index 161abe4e..574042cd 100644 --- a/internal/shortcut/smart/search_msg_execution_test.go +++ b/internal/shortcut/smart/search_msg_execution_test.go @@ -198,15 +198,25 @@ func TestSearchMsgSenderScopeFiltersBackendOverReturn(t *testing.T) { } } -func TestCrossPlatformCoverageSearchMsgSenderScopeRejectsUnmappedIdentityFamily(t *testing.T) { +func TestCrossPlatformCoverageSearchMsgSenderScopeIgnoresNonMatchingIdentityFamily(t *testing.T) { + caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[ + {"openMessageId":"wanted","senderOpenDingTalkId":"DAAAAAAAAAAAiE","content":"keep"}, + {"openMessageId":"other-family","senderUserId":"other-user","content":"drop"} + ],"hasMore":false}}`} + payload := executeSearchMsg(t, caller, "--sender", testCurrentDOpenID, "--no-enrich") + if payload["complete"] != true || payload["count"] != float64(1) || payload["failedCount"] != float64(0) { + t.Fatalf("payload=%#v", payload) + } + filtered, unverifiable := filterSearchSenderScope( - []map[string]any{{"openMessageId": "m-user-family", "senderUserId": "user-1"}}, - []targetresolver.UserResolution{{ - Selected: targetresolver.User{OpenDingTalkID: testCurrentDOpenID}, - }}, + []map[string]any{ + {"openMessageId": "wanted-user", "senderUserId": "wanted-user"}, + {"openMessageId": "other-open-family", "senderOpenDingTalkId": testCurrentDOpenID}, + }, + []targetresolver.UserResolution{{Selected: targetresolver.User{UserID: "wanted-user"}}}, ) - if len(filtered) != 0 || !reflect.DeepEqual(unverifiable, []string{"m-user-family"}) { - t.Fatalf("filtered=%#v unverifiable=%#v", filtered, unverifiable) + if len(filtered) != 1 || len(unverifiable) != 0 { + t.Fatalf("reverse family filtered=%#v unverifiable=%#v", filtered, unverifiable) } } @@ -221,21 +231,11 @@ func TestCrossPlatformCoverageSearchMsgResolutionFailureEdges(t *testing.T) { caller: &searchMsgExecutionCaller{failGroupKeyword: "missing-group"}, args: []string{"--group", "missing-group", "--no-enrich"}, }, - { - name: "sender target", - caller: &searchMsgExecutionCaller{failContactKeyword: "missing-sender"}, - args: []string{"--sender", "missing-sender", "--no-enrich"}, - }, { name: "sender query", caller: &searchMsgExecutionCaller{failContactKeyword: "missing-query"}, args: []string{"--sender-query", "missing-query", "--no-enrich"}, }, - { - name: "at stable id", - caller: &searchMsgExecutionCaller{failContactKeyword: "missing-at"}, - args: []string{"--at-ids", "missing-at", "--no-enrich"}, - }, } { t.Run(tc.name, func(t *testing.T) { if _, err := executeSearchMsgResult(tc.caller, tc.args...); err == nil { @@ -245,6 +245,89 @@ func TestCrossPlatformCoverageSearchMsgResolutionFailureEdges(t *testing.T) { } } +func TestCrossPlatformCoverageSearchMsgStableUserIDContinuesWhenDirectoryIsUnavailable(t *testing.T) { + t.Run("unrelated unique directory candidate never replaces the supplied user id", func(t *testing.T) { + caller := &searchMsgExecutionCaller{ + contactResponse: `{"result":[{"userId":"other-user","name":"其他用户"}],"hasMore":false}`, + searchResponse: `{"result":{"messages":[ + {"openMessageId":"wanted","senderUserId":"fixture-user-id","content":"keep"}, + {"openMessageId":"other","senderUserId":"other-user","content":"drop"} + ],"hasMore":false}}`, + } + payload := executeSearchMsg(t, caller, "--sender", "fixture-user-id", "--no-enrich") + if len(caller.calls) != 2 || caller.calls[0].tool != "search_contact_by_key_word" || + caller.calls[1].tool != "search_messages" { + t.Fatalf("calls=%#v", caller.calls) + } + if got := caller.calls[1].args["senderUserIds"]; !reflect.DeepEqual(got, []string{"fixture-user-id"}) { + t.Fatalf("senderUserIds=%#v args=%#v", got, caller.calls[1].args) + } + if _, exists := caller.calls[1].args["senderOpenDingTakIds"]; exists { + t.Fatalf("unrelated candidate leaked into request: %#v", caller.calls[1].args) + } + if payload["complete"] != true || payload["count"] != float64(1) { + t.Fatalf("payload=%#v", payload) + } + }) + + t.Run("mixed sender preserves positive matches and blocks complete negative conclusion", func(t *testing.T) { + caller := &searchMsgExecutionCaller{ + failContactKeyword: "stable-user-id", + searchResponse: `{"result":{"messages":[ + {"openMessageId":"wanted","senderUserId":"stable-user-id","content":"keep"}, + {"openMessageId":"other","senderUserId":"other-user","content":"drop"} + ],"hasMore":false}}`, + } + payload := executeSearchMsg(t, caller, "--sender", "stable-user-id", "--no-enrich") + if len(caller.calls) != 2 || caller.calls[0].tool != "search_contact_by_key_word" || + caller.calls[1].tool != "search_messages" { + t.Fatalf("calls=%#v", caller.calls) + } + if got := caller.calls[1].args["senderUserIds"]; !reflect.DeepEqual(got, []string{"stable-user-id"}) { + t.Fatalf("senderUserIds=%#v", got) + } + if payload["count"] != float64(1) || payload["complete"] != true || payload["failedCount"] != float64(0) { + t.Fatalf("payload=%#v", payload) + } + scope := payload["senderScope"].(map[string]any) + if _, exists := scope["status"]; exists || scope["targetsResolved"] != true { + t.Fatalf("senderScope=%#v", scope) + } + }) + + t.Run("mixed sender without a stable id match cannot produce a complete negative conclusion", func(t *testing.T) { + caller := &searchMsgExecutionCaller{ + failContactKeyword: "possibly-a-name", + searchResponse: `{"result":{"messages":[],"hasMore":false}}`, + } + payload := executeSearchMsg(t, caller, "--sender", "possibly-a-name", "--no-enrich") + if payload["count"] != float64(0) || payload["complete"] != false || payload["failedCount"] != float64(1) { + t.Fatalf("payload=%#v", payload) + } + scope := payload["senderScope"].(map[string]any) + if scope["status"] != "identity_unverified" || scope["targetsResolved"] != false { + t.Fatalf("senderScope=%#v", scope) + } + }) + + t.Run("id-only at target bypasses directory", func(t *testing.T) { + caller := &searchMsgExecutionCaller{ + failContactKeyword: "stable-at-user-id", + searchResponse: `{"result":{"messages":[],"hasMore":false}}`, + } + payload := executeSearchMsg(t, caller, "--at-ids", "stable-at-user-id", "--no-enrich") + if len(caller.calls) != 1 || caller.calls[0].tool != "search_messages" { + t.Fatalf("calls=%#v", caller.calls) + } + if got := caller.calls[0].args["atUserIds"]; !reflect.DeepEqual(got, []string{"stable-at-user-id"}) { + t.Fatalf("atUserIds=%#v", got) + } + if payload["complete"] != true { + t.Fatalf("payload=%#v", payload) + } + }) +} + func TestCrossPlatformCoverageSearchMsgSenderScopeFailureEdges(t *testing.T) { t.Run("execute rejects senderless backend rows", func(t *testing.T) { caller := &searchMsgExecutionCaller{searchResponse: `{"result":{"messages":[{"content":"missing identity"}],"hasMore":false}}`} @@ -267,15 +350,9 @@ func TestCrossPlatformCoverageSearchMsgSenderScopeFailureEdges(t *testing.T) { }, resolutions, ) - if len(filtered) != 1 || !reflect.DeepEqual(unverifiable, []string{"", "open-family"}) { + if len(filtered) != 1 || !reflect.DeepEqual(unverifiable, []string{""}) { t.Fatalf("filtered=%#v unverifiable=%#v", filtered, unverifiable) } - if got := searchScopeMessageID(map[string]any{}); got != "" { - t.Fatalf("missing message ID=%q", got) - } - if got := searchScopeMessageID(map[string]any{"openMessageId": "message-1"}); got != "message-1" { - t.Fatalf("message ID=%q", got) - } err := searchSenderScopeUnverifiedError( append(resolutions, resolutions...), []string{"message-1"}, diff --git a/internal/shortcut/targetresolver/resolver.go b/internal/shortcut/targetresolver/resolver.go index 7dc165b1..c800e9fe 100644 --- a/internal/shortcut/targetresolver/resolver.go +++ b/internal/shortcut/targetresolver/resolver.go @@ -70,6 +70,16 @@ type UserResolution struct { Profile string `json:"profile,omitempty"` } +const matchTypeUnverifiedUserID = "unverified_user_id" + +// IsUnverifiedUserIDResolution reports a mixed sender value that could not be +// classified by the directory and is therefore being tried as an exact userId. +// Consumers may use positive senderId equality, but must not claim a negative +// result is complete because the original value may instead have been a name. +func IsUnverifiedUserIDResolution(resolution UserResolution) bool { + return resolution.MatchType == matchTypeUnverifiedUserID +} + // Chat is the public identity returned by group resolution. type Chat struct { OpenConversationID string `json:"openConversationId"` @@ -148,8 +158,12 @@ func ResolveUserTarget(rt Reader, value string, requirement IdentityRequirement) // ResolveSenderTarget resolves the mixed identity accepted specifically by // sender convenience flags. Unlike the shared name resolver, it may select a // unique candidate whose stable userId/openDingTalkId exactly equals the -// supplied value. Natural-name candidates retain the shared fail-closed -// ambiguity behavior. +// supplied value. Natural-name resolution accepts only exact names and retains +// fail-closed ambiguity behavior; a lone unrelated directory candidate must +// never replace the supplied value. If the directory cannot classify a value +// and userId is accepted downstream, the original value is retained as an +// unverified userId candidate so a valid stable ID is not blocked by directory +// availability. func ResolveSenderTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error) { value = strings.TrimSpace(value) if value == "" || LooksLikeCurrentDOpenDingTalkID(value) { @@ -160,7 +174,10 @@ func ResolveSenderTarget(rt Reader, value string, requirement IdentityRequiremen "keyword": value, }) if err != nil { - return UserResolution{}, err + if requirement == IdentityOpenDingTalkID { + return UserResolution{}, err + } + return unverifiedSenderUserID(value), nil } users := filterUsersByIdentity(dedupeUsers(ExtractUsers(data)), requirement) stableMatches := make([]User, 0, 1) @@ -184,14 +201,51 @@ func ResolveSenderTarget(rt Reader, value string, requirement IdentityRequiremen return UserResolution{}, newResolutionError(StatusAmbiguous, "user", value, stableMatches) } if cause := incompleteUserSearchCause(data, "通讯录搜索"); cause != "" { - return UserResolution{}, newIncompleteUserResolutionError(value, users, cause) + if requirement == IdentityOpenDingTalkID { + return UserResolution{}, newIncompleteUserResolutionError(value, users, cause) + } + return unverifiedSenderUserID(value), nil } - return resolveUserCandidates(users, value, requirement) + exactNameMatches := make([]User, 0, 1) + for _, user := range users { + if strings.EqualFold(strings.TrimSpace(user.Name), value) { + exactNameMatches = append(exactNameMatches, user) + } + } + if len(exactNameMatches) == 1 { + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "exact", + Selected: exactNameMatches[0], + Profile: profilectx.Get(), + }, nil + } + if len(exactNameMatches) > 1 { + return UserResolution{}, newResolutionError(StatusAmbiguous, "user", value, exactNameMatches) + } + if requirement == IdentityOpenDingTalkID { + return UserResolution{}, newResolutionError(StatusNotFound, "user", value, users) + } + return unverifiedSenderUserID(value), nil } -// ResolveStableUserTarget accepts only an exact userId or current-version -// openDingTalkId. It is intended for flags whose contract explicitly excludes -// natural names; no unique-name fallback is allowed. +func unverifiedSenderUserID(value string) UserResolution { + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: matchTypeUnverifiedUserID, + Selected: User{UserID: value}, + Profile: profilectx.Get(), + } +} + +// ResolveStableUserTarget accepts only a userId or current-version +// openDingTalkId. Because callers use it only for ID-only flags, a non-D value +// is already explicitly typed as userId and can be passed through without a +// directory availability dependency. func ResolveStableUserTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error) { value = strings.TrimSpace(value) if value == "" { @@ -223,50 +277,24 @@ func ResolveStableUserTarget(rt Reader, value string, requirement IdentityRequir Profile: profilectx.Get(), }, nil } - - data, err := rt.CallMCPData("contact", "search_contact_by_key_word", map[string]any{ - "keyword": value, - }) - if err != nil { - return UserResolution{}, err + if requirement == IdentityOpenDingTalkID { + return UserResolution{}, apperrors.NewValidation( + fmt.Sprintf("用户目标参数类型不匹配：%q 是 userId，但当前参数只接受 openDingTalkId", value), + apperrors.WithReason("target_type_mismatch"), + apperrors.WithOrigin("client"), + apperrors.WithFailureStage("target_resolution"), + apperrors.WithExecutionStarted(false), + apperrors.WithRetryable(false), + ) } - users := filterUsersByIdentity(dedupeUsers(ExtractUsers(data)), requirement) - stableMatches := make([]User, 0, 1) - for _, user := range users { - if strings.TrimSpace(user.UserID) == value || - strings.TrimSpace(user.OpenDingTalkID) == value { - stableMatches = append(stableMatches, user) - } - } - if len(stableMatches) == 1 { - return UserResolution{ - Status: StatusResolved, - EntityType: "user", - Query: value, - MatchType: "stable_id", - Selected: stableMatches[0], - Profile: profilectx.Get(), - }, nil - } - if len(stableMatches) > 1 { - return UserResolution{}, newResolutionError(StatusAmbiguous, "user", value, stableMatches) - } - if cause := incompleteUserSearchCause(data, "通讯录搜索"); cause != "" { - return UserResolution{}, newIncompleteUserResolutionError(value, users, cause) - } - return UserResolution{}, apperrors.NewValidation( - fmt.Sprintf("%q 未精确匹配到 userId 或 openDingTalkId", value), - apperrors.WithReason("stable_user_identity_required"), - apperrors.WithOrigin("client"), - apperrors.WithFailureStage("target_resolution"), - apperrors.WithExecutionStarted(false), - apperrors.WithRetryable(false), - apperrors.WithHint("请先解析目标人员，并传入通讯录结果中原样返回的 userId 或 openDingTalkId"), - apperrors.WithDetails(map[string]any{ - "providedValue": value, - "expectedTypes": []string{"userId", "openDingTalkId"}, - }), - ) + return UserResolution{ + Status: StatusResolved, + EntityType: "user", + Query: value, + MatchType: "stable_id", + Selected: User{UserID: value}, + Profile: profilectx.Get(), + }, nil } // LooksLikeCurrentDOpenDingTalkID reports whether value has the canonical diff --git a/internal/shortcut/targetresolver/resolver_test.go b/internal/shortcut/targetresolver/resolver_test.go index 2da5e817..e52a89a3 100644 --- a/internal/shortcut/targetresolver/resolver_test.go +++ b/internal/shortcut/targetresolver/resolver_test.go @@ -783,6 +783,87 @@ func TestCrossPlatformCoverageResolveSenderTargetScopesStableIDPreferenceToSende } } +func TestCrossPlatformCoverageResolveSenderTargetNeverSubstitutesUnrelatedUniqueDirectoryCandidate(t *testing.T) { + resolved, err := ResolveSenderTarget(resolverReaderFunc(func(product, tool string, params map[string]any) (map[string]any, error) { + if product != "contact" || tool != "search_contact_by_key_word" || params["keyword"] != "fixture-user-id" { + t.Fatalf("unexpected call %s/%s %#v", product, tool, params) + } + return map[string]any{ + "result": []any{map[string]any{ + "userId": "other-user", + "name": "其他用户", + }}, + "hasMore": false, + }, nil + }), "fixture-user-id", IdentityAny) + if err != nil { + t.Fatal(err) + } + if !IsUnverifiedUserIDResolution(resolved) || resolved.Selected.UserID != "fixture-user-id" { + t.Fatalf("resolution=%#v", resolved) + } +} + +func TestCrossPlatformCoverageResolveSenderTargetOpenIDFailureEdges(t *testing.T) { + t.Run("directory failure", func(t *testing.T) { + wantErr := stderrors.New("directory unavailable") + _, err := ResolveSenderTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return nil, wantErr + }), "fixture-sender", IdentityOpenDingTalkID) + if !stderrors.Is(err, wantErr) { + t.Fatalf("error=%#v, want directory error", err) + } + }) + + t.Run("incomplete directory result", func(t *testing.T) { + _, err := ResolveSenderTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{ + "result": []any{map[string]any{ + "openDingTalkId": "fixture-open-id-1", + "name": "测试候选用户", + }}, + "hasMore": true, + }, nil + }), "fixture-sender", IdentityOpenDingTalkID) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_incomplete" { + t.Fatalf("error=%#v, want resolution_incomplete", err) + } + }) + + t.Run("multiple exact names remain ambiguous", func(t *testing.T) { + _, err := ResolveSenderTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{ + "result": []any{ + map[string]any{"openDingTalkId": "fixture-open-id-1", "name": "测试同名用户"}, + map[string]any{"openDingTalkId": "fixture-open-id-2", "name": "测试同名用户"}, + }, + "hasMore": false, + }, nil + }), "测试同名用户", IdentityOpenDingTalkID) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_ambiguous" { + t.Fatalf("error=%#v, want resolution_ambiguous", err) + } + }) + + t.Run("no exact open id or name match", func(t *testing.T) { + _, err := ResolveSenderTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + return map[string]any{ + "result": []any{map[string]any{ + "openDingTalkId": "fixture-open-id-1", + "name": "其他测试用户", + }}, + "hasMore": false, + }, nil + }), "fixture-sender", IdentityOpenDingTalkID) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_not_found" { + t.Fatalf("error=%#v, want resolution_not_found", err) + } + }) +} + func TestValidateExplicitOpenDingTalkIDNeverFallsBack(t *testing.T) { if err := ValidateExplicitOpenDingTalkID("--open-dingtalk-id", "DAAAAAAAAAAAiE"); err != nil { t.Fatalf("valid format: %v", err) @@ -798,29 +879,20 @@ func TestValidateExplicitOpenDingTalkIDNeverFallsBack(t *testing.T) { } } -func TestCrossPlatformCoverageResolveStableUserTargetRejectsNaturalNameButAcceptsExactUserID(t *testing.T) { - reader := resolverReaderFunc(func(product, tool string, params map[string]any) (map[string]any, error) { - if product != "contact" || tool != "search_contact_by_key_word" { - t.Fatalf("unexpected tool %s/%s", product, tool) - } - return map[string]any{"result": []any{ - map[string]any{"userId": "fixture-user-id", "openDingTalkId": "DAAAAAAAAAAAiE", "name": "测试用户甲"}, - }}, nil +func TestCrossPlatformCoverageResolveStableUserTargetPassesExplicitUserIDWithoutDirectory(t *testing.T) { + calls := 0 + reader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + calls++ + return nil, stderrors.New("directory unavailable") }) resolved, err := ResolveStableUserTarget(reader, "fixture-user-id", IdentityAny) if err != nil { t.Fatal(err) } - if resolved.MatchType != "stable_id" || resolved.Selected.UserID != "fixture-user-id" { + if calls != 0 || resolved.MatchType != "stable_id" || resolved.Selected.UserID != "fixture-user-id" { t.Fatalf("exact userId resolution = %#v", resolved) } - - _, err = ResolveStableUserTarget(reader, "测试用户甲", IdentityAny) - var typed *apperrors.Error - if !stderrors.As(err, &typed) || typed.Reason != "stable_user_identity_required" { - t.Fatalf("natural name error = %#v", err) - } } func TestResolveStableUserTargetRoutesCurrentDWithoutDirectoryLookup(t *testing.T) { @@ -883,6 +955,7 @@ func TestCrossPlatformCoverageMixedIdentityResolutionFailureEdges(t *testing.T) {name: "mixed open id requires user id", resolve: ResolveUserTarget, value: "DAAAAAAAAAAAiE", requirement: IdentityUserID, wantReason: "target_type_mismatch"}, {name: "stable empty", resolve: ResolveStableUserTarget, wantReason: "missing_target"}, {name: "stable open id requires user id", resolve: ResolveStableUserTarget, value: "DAAAAAAAAAAAiE", requirement: IdentityUserID, wantReason: "target_type_mismatch"}, + {name: "stable user id requires open id", resolve: ResolveStableUserTarget, value: "ordinary-user", requirement: IdentityOpenDingTalkID, wantReason: "target_type_mismatch"}, } { t.Run(tc.name, func(t *testing.T) { _, err := tc.resolve(unexpectedReader, tc.value, tc.requirement) @@ -896,11 +969,13 @@ func TestCrossPlatformCoverageMixedIdentityResolutionFailureEdges(t *testing.T) if _, err := ResolveUserTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { t.Fatalf("mixed directory error=%v", err) } - if _, err := ResolveSenderTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { - t.Fatalf("sender directory error=%v", err) + resolved, err := ResolveSenderTarget(unexpectedReader, "ordinary-user", IdentityAny) + if err != nil || !IsUnverifiedUserIDResolution(resolved) || resolved.Selected.UserID != "ordinary-user" { + t.Fatalf("sender fallback resolution=%#v error=%v", resolved, err) } - if _, err := ResolveStableUserTarget(unexpectedReader, "ordinary-user", IdentityAny); err == nil || err.Error() != "directory unavailable" { - t.Fatalf("stable directory error=%v", err) + resolved, err = ResolveStableUserTarget(unexpectedReader, "ordinary-user", IdentityAny) + if err != nil || resolved.MatchType != "stable_id" || resolved.Selected.UserID != "ordinary-user" { + t.Fatalf("stable passthrough resolution=%#v error=%v", resolved, err) } } @@ -911,20 +986,10 @@ func TestCrossPlatformCoverageStableIdentityAmbiguousAndIncompleteEdges(t *testi map[string]any{"userId": "other", "openDingTalkId": "duplicate", "name": "乙"}, }}, nil }) - for _, resolve := range []struct { - name string - fn func(Reader, string, IdentityRequirement) (UserResolution, error) - }{ - {name: "sender", fn: ResolveSenderTarget}, - {name: "stable", fn: ResolveStableUserTarget}, - } { - t.Run(resolve.name+" ambiguous", func(t *testing.T) { - _, err := resolve.fn(duplicateReader, "duplicate", IdentityAny) - var typed *apperrors.Error - if !stderrors.As(err, &typed) || typed.Reason != "resolution_ambiguous" { - t.Fatalf("error=%#v", err) - } - }) + _, err := ResolveSenderTarget(duplicateReader, "duplicate", IdentityAny) + var typed *apperrors.Error + if !stderrors.As(err, &typed) || typed.Reason != "resolution_ambiguous" { + t.Fatalf("ambiguous sender error=%#v", err) } incompleteReader := resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { @@ -933,20 +998,9 @@ func TestCrossPlatformCoverageStableIdentityAmbiguousAndIncompleteEdges(t *testi "hasMore": true, }, nil }) - for _, resolve := range []struct { - name string - fn func(Reader, string, IdentityRequirement) (UserResolution, error) - }{ - {name: "sender", fn: ResolveSenderTarget}, - {name: "stable", fn: ResolveStableUserTarget}, - } { - t.Run(resolve.name+" incomplete", func(t *testing.T) { - _, err := resolve.fn(incompleteReader, "missing", IdentityAny) - var typed *apperrors.Error - if !stderrors.As(err, &typed) || typed.Reason != "resolution_incomplete" { - t.Fatalf("error=%#v", err) - } - }) + resolved, err := ResolveSenderTarget(incompleteReader, "missing", IdentityAny) + if err != nil || !IsUnverifiedUserIDResolution(resolved) || resolved.Selected.UserID != "missing" { + t.Fatalf("incomplete sender fallback=%#v error=%v", resolved, err) } } From bcd91aca1fdb404b100fa88edcd341dbfcec303f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Fri, 14 Aug 2026 01:10:17 +0800 Subject: [PATCH 094/250] test(chat): align time defaults with current open ID format --- internal/helpers/chat_message_search_test.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/internal/helpers/chat_message_search_test.go b/internal/helpers/chat_message_search_test.go index c0bcc370..2b1d1ccf 100644 --- a/internal/helpers/chat_message_search_test.go +++ b/internal/helpers/chat_message_search_test.go @@ -748,15 +748,15 @@ func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t * }, { name: "user open DingTalk ID fallback", - args: []string{"message", "list", "--user", "D-user", "--limit", "50"}, + args: []string{"message", "list", "--user", helperCurrentDOpenID, "--limit", "50"}, wantTool: "list_individual_chat_message", - wantTarget: map[string]any{"openDingTalkId": "D-user"}, + wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID}, }, { name: "open DingTalk ID", - args: []string{"message", "list", "--open-dingtalk-id", "D-open", "--limit", "50"}, + args: []string{"message", "list", "--open-dingtalk-id", helperCurrentDOpenID, "--limit", "50"}, wantTool: "list_individual_chat_message", - wantTarget: map[string]any{"openDingTalkId": "D-open"}, + wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID}, }, { name: "direct user", @@ -766,9 +766,9 @@ func TestCrossPlatformCoverageChatMessageListDefaultTimeUsesShanghaiLocation(t * }, { name: "direct open DingTalk ID", - args: []string{"message", "list-direct", "--open-dingtalk-id", "D-direct", "--limit", "50"}, + args: []string{"message", "list-direct", "--open-dingtalk-id", helperCurrentDOpenID, "--limit", "50"}, wantTool: "list_individual_chat_message", - wantTarget: map[string]any{"openDingTalkId": "D-direct"}, + wantTarget: map[string]any{"openDingTalkId": helperCurrentDOpenID}, }, } From be001949e40cb5786aefaac334ff444cd8d00c64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Fri, 14 Aug 2026 01:31:16 +0800 Subject: [PATCH 095/250] test(chat): complete sender routing coverage --- internal/shortcut/smart/chat_messages_test.go | 14 +++++++++++++ internal/shortcut/smart/search_msg.go | 16 ++++++-------- .../smart/search_msg_execution_test.go | 12 +++++++++++ .../shortcut/targetresolver/resolver_test.go | 21 ++++++++++++++++--- 4 files changed, 50 insertions(+), 13 deletions(-) diff --git a/internal/shortcut/smart/chat_messages_test.go b/internal/shortcut/smart/chat_messages_test.go index 24201f12..aab4bf87 100644 --- a/internal/shortcut/smart/chat_messages_test.go +++ b/internal/shortcut/smart/chat_messages_test.go @@ -782,6 +782,20 @@ func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) } func TestCrossPlatformCoverageChatMessagesSenderFailureOutputEdges(t *testing.T) { + t.Run("ambiguous direct sender prioritizes output error", func(t *testing.T) { + caller := &platformCoverageCaller{contactSearchResult: `{"result":[ + {"userId":"fixture-user-1","name":"测试同名发送者"}, + {"userId":"fixture-user-2","name":"测试同名发送者"} + ],"hasMore":false}`} + helpers.InitDeps(caller) + root := newPlatformCoverageRoot() + root.SetOut(chatMessagesFailWriter{}) + root.SetArgs([]string{"chat", "+chat-messages", "--conversation-id", "cid", "--sender", "测试同名发送者"}) + if err := root.Execute(); err == nil || err.Error() != "fixture output failure" { + t.Fatalf("error=%v", err) + } + }) + for _, tc := range []struct { name string sender string diff --git a/internal/shortcut/smart/search_msg.go b/internal/shortcut/smart/search_msg.go index a3f6c011..73f8bbc6 100644 --- a/internal/shortcut/smart/search_msg.go +++ b/internal/shortcut/smart/search_msg.go @@ -515,10 +515,7 @@ func searchMsgParams(rt *shortcut.RuntimeContext) (map[string]any, searchResolve resolvedFilters.Senders = append(resolvedFilters.Senders, resolvedUsers...) } appendResolvedSearchActorIDs(params, resolvedFilters.Senders, "senderUserIds", "senderOpenDingTakIds") - atUsers, err := resolveSearchStableActorTargets(rt, rt.StrSlice("at-ids")) - if err != nil { - return nil, searchResolvedFilters{}, err - } + atUsers := resolveSearchStableActorTargets(rt, rt.StrSlice("at-ids")) appendResolvedSearchActorIDs(params, atUsers, "atUserIds", "atOpenDingTakIds") if rt.Bool("at-me") || rt.Bool("is-at-me") { params["atMe"] = true @@ -560,16 +557,15 @@ func searchMsgParams(rt *shortcut.RuntimeContext) (map[string]any, searchResolve func resolveSearchStableActorTargets( rt *shortcut.RuntimeContext, values []string, -) ([]targetresolver.UserResolution, error) { +) []targetresolver.UserResolution { resolvedUsers := make([]targetresolver.UserResolution, 0, len(values)) for _, value := range uniqueSearchStrings(values) { - resolved, err := targetresolver.ResolveStableUserTarget(rt, value, targetresolver.IdentityAny) - if err != nil { - return nil, err - } + // IdentityAny accepts every non-empty value as exactly one stable ID + // family, and uniqueSearchStrings has already removed empty values. + resolved, _ := targetresolver.ResolveStableUserTarget(rt, value, targetresolver.IdentityAny) resolvedUsers = append(resolvedUsers, resolved) } - return resolvedUsers, nil + return resolvedUsers } // appendResolvedSearchActorIDs prefers openDingTalkId whenever directory diff --git a/internal/shortcut/smart/search_msg_execution_test.go b/internal/shortcut/smart/search_msg_execution_test.go index 574042cd..1768c849 100644 --- a/internal/shortcut/smart/search_msg_execution_test.go +++ b/internal/shortcut/smart/search_msg_execution_test.go @@ -245,6 +245,18 @@ func TestCrossPlatformCoverageSearchMsgResolutionFailureEdges(t *testing.T) { } } +func TestCrossPlatformCoverageSearchMsgRejectsAmbiguousDirectSender(t *testing.T) { + caller := &searchMsgExecutionCaller{contactResponse: `{"result":[ + {"userId":"fixture-user-1","name":"测试同名发送者"}, + {"userId":"fixture-user-2","name":"测试同名发送者"} + ],"hasMore":false}`} + _, err := executeSearchMsgResult(caller, "--sender", "测试同名发送者", "--no-enrich") + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "resolution_ambiguous" { + t.Fatalf("error=%#v, want resolution_ambiguous", err) + } +} + func TestCrossPlatformCoverageSearchMsgStableUserIDContinuesWhenDirectoryIsUnavailable(t *testing.T) { t.Run("unrelated unique directory candidate never replaces the supplied user id", func(t *testing.T) { caller := &searchMsgExecutionCaller{ diff --git a/internal/shortcut/targetresolver/resolver_test.go b/internal/shortcut/targetresolver/resolver_test.go index e52a89a3..a1be9b77 100644 --- a/internal/shortcut/targetresolver/resolver_test.go +++ b/internal/shortcut/targetresolver/resolver_test.go @@ -715,7 +715,7 @@ func TestCrossPlatformCoverageLooksLikeCurrentDOpenDingTalkID(t *testing.T) { } } -func TestResolveUserTargetUsesFormatClassificationWithoutIDPreflight(t *testing.T) { +func TestCrossPlatformCoverageResolveUserTargetUsesFormatClassificationWithoutIDPreflight(t *testing.T) { const openID = "DAAAAAAAAAAAiE" calls := 0 resolved, err := ResolveUserTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { @@ -783,6 +783,21 @@ func TestCrossPlatformCoverageResolveSenderTargetScopesStableIDPreferenceToSende } } +func TestCrossPlatformCoverageResolveSenderTargetRoutesCurrentDWithoutDirectoryLookup(t *testing.T) { + const openID = "DAAAAAAAAAAAiE" + calls := 0 + resolved, err := ResolveSenderTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { + calls++ + return nil, stderrors.New("unexpected directory call") + }), openID, IdentityAny) + if err != nil { + t.Fatal(err) + } + if calls != 0 || resolved.MatchType != "stable_id" || resolved.Selected.OpenDingTalkID != openID { + t.Fatalf("calls=%d resolved=%#v", calls, resolved) + } +} + func TestCrossPlatformCoverageResolveSenderTargetNeverSubstitutesUnrelatedUniqueDirectoryCandidate(t *testing.T) { resolved, err := ResolveSenderTarget(resolverReaderFunc(func(product, tool string, params map[string]any) (map[string]any, error) { if product != "contact" || tool != "search_contact_by_key_word" || params["keyword"] != "fixture-user-id" { @@ -864,7 +879,7 @@ func TestCrossPlatformCoverageResolveSenderTargetOpenIDFailureEdges(t *testing.T }) } -func TestValidateExplicitOpenDingTalkIDNeverFallsBack(t *testing.T) { +func TestCrossPlatformCoverageValidateExplicitOpenDingTalkIDNeverFallsBack(t *testing.T) { if err := ValidateExplicitOpenDingTalkID("--open-dingtalk-id", "DAAAAAAAAAAAiE"); err != nil { t.Fatalf("valid format: %v", err) } @@ -895,7 +910,7 @@ func TestCrossPlatformCoverageResolveStableUserTargetPassesExplicitUserIDWithout } } -func TestResolveStableUserTargetRoutesCurrentDWithoutDirectoryLookup(t *testing.T) { +func TestCrossPlatformCoverageResolveStableUserTargetRoutesCurrentDWithoutDirectoryLookup(t *testing.T) { const openID = "DAAAAAAAAAAAiE" calls := 0 resolved, err := ResolveStableUserTarget(resolverReaderFunc(func(string, string, map[string]any) (map[string]any, error) { From c9d47839688a8d6a12cd42b67a0a47cc6e95bd97 Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 10:07:58 +0800 Subject: [PATCH 096/250] fix(drive): recheck source identity after PUT and reject symlink status root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two follow-ups to the latest CR: * push/sync uploads (`pushUploadFilePinned`): the PUT-time check pinned inode, size, and mtime before dispatch but nothing rechecked the source after PUT succeeded — only the root itself. An editor overwrite, truncate-rewrite, or mmap-in-place during transfer would land a mixed old/new byte stream in OSS and still be committed, corrupting the remote file in overwrite/local-wins. Now stat the still-open handle again before `commit_upload`; any change in inode/size/mtime aborts the commit. Post-PUT stat failures also abort. * status root (`walkLocalTree`): `filepath.WalkDir` refuses to follow the root when it is itself a directory symlink and reports it as a non-regular entry, so the walker silently returned an empty local index and status flagged every remote file as `new_remote`. Fail closed before the walk: the root must be a real directory; symlinks and non-directories are rejected with a clear message. A `statusRootLstat` seam keeps the rejection regressible on platforms that cannot create directory symlinks (Windows without admin). Both fixes come with `TestCrossPlatformCoverage*` regressions and take the platform coverage gate from 99.9356% back to 100.0000% (1553 statements). --- internal/helpers/drive_push.go | 13 ++++ .../drive_push_sync_final_coverage_test.go | 78 ++++++++++++++++++- internal/helpers/drive_status.go | 20 ++++- .../helpers/drive_status_coverage_test.go | 45 +++++++++++ 4 files changed, 153 insertions(+), 3 deletions(-) diff --git a/internal/helpers/drive_push.go b/internal/helpers/drive_push.go index 37eaec56..e5e64e25 100644 --- a/internal/helpers/drive_push.go +++ b/internal/helpers/drive_push.go @@ -741,6 +741,19 @@ func pushUploadFilePinned(ctx context.Context, spaceID, parentID, overwriteFileI if err := pushPutOpenedFile(ctx, resourceURL, ossHeaders, file, local.Size); err != nil { return err } + // OSS 传输期间若源文件被原地改写（编辑器覆盖、截断重写、mmap）， + // PUT 里发送的可能是新旧内容的混合体，root.verify() 又不检查文件本身。 + // commit 前对已打开句柄再取一次身份，与 PUT 前的 inode/size/mtime 逐项比对; + // 任一变化都拒绝 commit，避免 overwrite/local-wins 场景把混合内容覆盖到远端。 + after, err := pushStatOpenedFile(file) + if err != nil { + return fmt.Errorf("上传后读取本地上传文件身份失败: %w", err) + } + if !os.SameFile(info, after) || + after.Size() != info.Size() || + after.ModTime().UnixMilli() != info.ModTime().UnixMilli() { + return fmt.Errorf("本地上传目标 %q 在传输期间被修改，已中止提交", local.RelPath) + } // OSS 传输期间若命令行根已被替换，不提交这个上传会话；已发送的字节仍来自 // 固定根内的原文件句柄，不可能读取替代路径或根外内容。 return root.verify() diff --git a/internal/helpers/drive_push_sync_final_coverage_test.go b/internal/helpers/drive_push_sync_final_coverage_test.go index 13aaf929..715e4362 100644 --- a/internal/helpers/drive_push_sync_final_coverage_test.go +++ b/internal/helpers/drive_push_sync_final_coverage_test.go @@ -13,6 +13,7 @@ import ( "path/filepath" "strings" "testing" + "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) @@ -183,9 +184,82 @@ func TestCrossPlatformCoverageDrivePushFinalPinnedUploadGuards(t *testing.T) { t.Fatalf("second verification error=%v", err) } }) -} -func TestCrossPlatformCoverageDrivePushFinalWalkAndCommandGates(t *testing.T) { + // PUT 期间源文件被原地改写（编辑器覆盖、截断重写、mmap）时，PUT 已把混合内容 + // 送到 OSS；如果 commit 只看根身份而不复核文件本身，overwrite/local-wins 会把 + // 半新半旧的字节流覆盖到远端。commit 前必须再取一次源身份，size/mtime/inode + // 任一变化都要拒绝提交。 + for _, mutation := range []struct { + name string + mutate func(t *testing.T, dir string) + }{ + {"size grows during PUT", func(t *testing.T, dir string) { + path := filepath.Join(dir, "a.txt") + if err := os.WriteFile(path, []byte("payload-mutated-mid-transfer"), 0o600); err != nil { + t.Fatal(err) + } + }}, + {"mtime advances during PUT", func(t *testing.T, dir string) { + path := filepath.Join(dir, "a.txt") + future := time.Now().Add(2 * time.Second) + if err := os.Chtimes(path, future, future); err != nil { + t.Fatal(err) + } + }}, + } { + t.Run("mid transfer source modification: "+mutation.name, func(t *testing.T) { + rootPath, root, local := openDriveFinalCoverageRoot(t) + caller := pushOKCaller(nil) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + putCalls := 0 + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + putCalls++ + mutation.mutate(t, rootPath) + return nil + }) + + err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local) + if err == nil || !strings.Contains(err.Error(), "在传输期间被修改") { + t.Fatalf("PUT-time mutation must abort commit, got err=%v", err) + } + if putCalls != 1 { + t.Fatalf("PUT must run exactly once, got %d", putCalls) + } + if commits := caller.callsFor("commit_upload"); len(commits) != 0 { + t.Fatalf("commit_upload must not run after mid-transfer mutation, got %v", commits) + } + }) + // PUT 之后再取源身份可能因文件被移动/删除失败：那也必须拒绝 commit，防止 + // 一个不能被验证的传输被提交到远端。 + t.Run("mid transfer stat failure aborts commit", func(t *testing.T) { + _, root, local := openDriveFinalCoverageRoot(t) + caller := pushOKCaller(nil) + testseam.Swap(t, &deps, &Deps{Caller: caller, Out: &Formatter{w: io.Discard}}) + testseam.Swap(t, &os.Args, []string{"dws", "drive"}) + + calls := 0 + testseam.Swap(t, &pushStatOpenedFile, func(file *os.File) (os.FileInfo, error) { + calls++ + if calls == 1 { + return file.Stat() + } + return nil, errDriveFinalCoverage + }) + testseam.Swap(t, &pushPutOpenedFile, func(context.Context, string, map[string]string, *os.File, int64) error { + return nil + }) + + err := pushUploadFilePinned(context.Background(), "", "P", "", "a.txt", root, local) + if err == nil || !strings.Contains(err.Error(), "上传后读取本地上传文件身份失败") { + t.Fatalf("post-PUT stat failure must abort commit, got %v", err) + } + if commits := caller.callsFor("commit_upload"); len(commits) != 0 { + t.Fatalf("commit_upload must not run after post-PUT stat failure, got %v", commits) + } + }) + } t.Run("command scan errors", func(t *testing.T) { for _, command := range []string{"push", "sync"} { t.Run(command, func(t *testing.T) { diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 4955dccf..586c004c 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -466,14 +466,32 @@ var md5File = func(path string) (string, error) { return base64.StdEncoding.EncodeToString(h.Sum(nil)), nil } +// statusRootLstat 是根类型校验的注入 seam；测试通过 testseam.Swap 注入不同的 +// FileInfo 来复现 Windows 上无法创建的符号链接场景。 +var statusRootLstat = os.Lstat + // walkLocalTree 递归遍历本地目录，只收集常规文件（跳过符号链接、设备文件等）。 // rel_path 统一使用 / 作为分隔符，相对于 root。 // // 这里只记录路径与 mtime，不计算 MD5：本地 hash 采用惰性策略，仅在文件双端 // 都存在且非 quick 模式时，由 compareTrees 按需计算（见 judgeFileMatch）。 func walkLocalTree(root string) (map[string]*localFile, error) { + // filepath.WalkDir 不会跟随根本身的符号链接：若 root 是指向目录的 symlink， + // WalkDir 只以 symlink 身份触发一次回调，随后 !IsRegular 分支静默跳过，最终 + // 返回空索引，让 status 把所有远端文件报成 new_remote。fail-closed 于遍历前： + // 根必须是真实目录，任何其它类型都必须报错。 + info, err := statusRootLstat(root) + if err != nil { + return nil, fmt.Errorf("读取本地根目录身份失败: %w", err) + } + if info.Mode()&os.ModeSymlink != 0 { + return nil, fmt.Errorf("本地根目录 %q 是符号链接，请传入真实目录路径", root) + } + if !info.IsDir() { + return nil, fmt.Errorf("本地根目录 %q 不是目录", root) + } files := make(map[string]*localFile) - err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { return walkLocalTreeEntry(root, path, d, err, files) }) if err != nil { diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index 3e9a3869..afe13dcf 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -10,6 +10,7 @@ import ( "runtime" "strings" "testing" + "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" @@ -300,6 +301,50 @@ func TestCrossPlatformCoverageWalkLocalTree_missingRootErrors(t *testing.T) { } } +// 根路径是指向目录的符号链接时，filepath.WalkDir 只把根本身当成一次 !IsRegular +// 回调静默跳过，结果是空索引，而 status 会把所有远端文件误报为 new_remote。 +// 必须在遍历前 fail-closed。这里通过 seam 注入，兼顾无法真实创建 symlink 的平台。 +func TestCrossPlatformCoverageWalkLocalTree_rejectsSymlinkRootViaSeam(t *testing.T) { + testseam.Swap(t, &statusRootLstat, func(string) (os.FileInfo, error) { + return fakeSymlinkFileInfo{}, nil + }) + if _, err := walkLocalTree(t.TempDir()); err == nil || !strings.Contains(err.Error(), "符号链接") { + t.Fatalf("symlink root must fail closed, got %v", err) + } +} + +// 真实 symlink 复现：非 Windows 平台可以直接创建，进一步保证 seam 与真实语义一致。 +func TestCrossPlatformCoverageWalkLocalTree_rejectsSymlinkRootReal(t *testing.T) { + target := t.TempDir() + link := filepath.Join(t.TempDir(), "root-link") + if err := os.Symlink(target, link); err != nil { + t.Skipf("symlink unsupported: %v", err) + } + if _, err := walkLocalTree(link); err == nil || !strings.Contains(err.Error(), "符号链接") { + t.Fatalf("symlink root must fail closed, got %v", err) + } +} + +// 根路径既非目录也非符号链接（例如普通文件被误传）时，也必须报错而非空索引。 +func TestCrossPlatformCoverageWalkLocalTree_rejectsNonDirectoryRoot(t *testing.T) { + file := filepath.Join(t.TempDir(), "not-a-dir") + mustWrite(t, file, "x") + if _, err := walkLocalTree(file); err == nil || !strings.Contains(err.Error(), "不是目录") { + t.Fatalf("file root must fail closed, got %v", err) + } +} + +// fakeSymlinkFileInfo 是一个 Mode()&os.ModeSymlink != 0 的 os.FileInfo。Windows +// 上创建目录符号链接需要管理员权限，测试通过它绕过创建步骤。 +type fakeSymlinkFileInfo struct{} + +func (fakeSymlinkFileInfo) Name() string { return "root-link" } +func (fakeSymlinkFileInfo) Size() int64 { return 0 } +func (fakeSymlinkFileInfo) Mode() os.FileMode { return os.ModeSymlink | 0o755 } +func (fakeSymlinkFileInfo) ModTime() time.Time { return time.Time{} } +func (fakeSymlinkFileInfo) IsDir() bool { return false } +func (fakeSymlinkFileInfo) Sys() any { return nil } + // 非常规文件（FIFO/符号链接目标缺失等）不计入本地索引。 func TestCrossPlatformCoverageWalkLocalTree_skipsIrregularEntries(t *testing.T) { dir := t.TempDir() From 0c2a9cb2b37d94de2434a6e4b6f11833b28d09d3 Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 10:31:34 +0800 Subject: [PATCH 097/250] test(drive): cover walkLocalTree's WalkDir error path via a seam MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new root-type guard shifted `filepath.WalkDir`'s outer error branch into the diff, and neither the macOS nor the Windows runner reaches it naturally — raising Windows coverage to 99.9365% and blocking the gate. Add a `statusWalkDir` seam and a `TestCrossPlatformCoverage` regression that swaps in a WalkDir returning a sentinel error, asserting it is surfaced unchanged. Verified locally: changed code coverage back to 100.0000%. --- internal/helpers/drive_status.go | 7 ++++++- internal/helpers/drive_status_coverage_test.go | 15 +++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/internal/helpers/drive_status.go b/internal/helpers/drive_status.go index 586c004c..adacdae5 100644 --- a/internal/helpers/drive_status.go +++ b/internal/helpers/drive_status.go @@ -470,6 +470,11 @@ var md5File = func(path string) (string, error) { // FileInfo 来复现 Windows 上无法创建的符号链接场景。 var statusRootLstat = os.Lstat +// statusWalkDir 是本地目录遍历的注入 seam。改造根类型校验后，filepath.WalkDir +// 的错误分支（walkLocalTreeEntry 之外的外层错误）在 macOS/Windows 上都难以自然 +// 触发，需要 seam 让该分支可以确定性回归。 +var statusWalkDir = filepath.WalkDir + // walkLocalTree 递归遍历本地目录，只收集常规文件（跳过符号链接、设备文件等）。 // rel_path 统一使用 / 作为分隔符，相对于 root。 // @@ -491,7 +496,7 @@ func walkLocalTree(root string) (map[string]*localFile, error) { return nil, fmt.Errorf("本地根目录 %q 不是目录", root) } files := make(map[string]*localFile) - err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + err = statusWalkDir(root, func(path string, d fs.DirEntry, err error) error { return walkLocalTreeEntry(root, path, d, err, files) }) if err != nil { diff --git a/internal/helpers/drive_status_coverage_test.go b/internal/helpers/drive_status_coverage_test.go index afe13dcf..c750695d 100644 --- a/internal/helpers/drive_status_coverage_test.go +++ b/internal/helpers/drive_status_coverage_test.go @@ -5,6 +5,7 @@ import ( "encoding/json" "errors" "io" + "io/fs" "os" "path/filepath" "runtime" @@ -325,6 +326,20 @@ func TestCrossPlatformCoverageWalkLocalTree_rejectsSymlinkRootReal(t *testing.T) } } +// 根类型校验通过后 WalkDir 内部返回的错误必须原样上抛，不能被吞掉；根消失或 +// 权限变更之类的情形在 Linux/Windows runner 上都难以稳定复现，用 seam 注入。 +func TestCrossPlatformCoverageWalkLocalTree_propagatesWalkDirError(t *testing.T) { + testseam.Swap(t, &statusWalkDir, func(string, fs.WalkDirFunc) error { + return errWalkDirSentinel + }) + dir := t.TempDir() + if _, err := walkLocalTree(dir); !errors.Is(err, errWalkDirSentinel) { + t.Fatalf("walk dir error must be surfaced, got %v", err) + } +} + +var errWalkDirSentinel = errors.New("simulated walk dir failure") + // 根路径既非目录也非符号链接（例如普通文件被误传）时，也必须报错而非空索引。 func TestCrossPlatformCoverageWalkLocalTree_rejectsNonDirectoryRoot(t *testing.T) { file := filepath.Join(t.TempDir(), "not-a-dir") From 9703a21a2d9ba7a2461be77c9e043952be7221b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Fri, 14 Aug 2026 10:43:50 +0800 Subject: [PATCH 098/250] fix(recruit): normalize connector list response --- internal/helpers/recruit.go | 17 +++++++++++++++++ internal/helpers/recruit_test.go | 29 +++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 73997371..527615b2 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -169,6 +169,17 @@ func recruitListResultData(data any) (any, *output.Meta, error) { if !ok { return nil, nil, fmt.Errorf("list_jobs 返回值必须是 JSON 对象") } + // The recruit Connector returns the ATS service envelope unchanged: + // {success:true,result:{list:[...],hasMore:false,nextCursor:null}}. + // Keep accepting the historical flattened shape as well, but normalize the + // fixed Connector shape before enforcing the public CLI result contract. + if nested, exists := object["result"]; exists { + var nestedOK bool + object, nestedOK = nested.(map[string]any) + if !nestedOK { + return nil, nil, fmt.Errorf("list_jobs 返回值的 result 必须是 JSON 对象") + } + } hasMore, ok := object["hasMore"].(bool) if !ok { return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore") @@ -196,6 +207,12 @@ func recruitListResultData(data any) (any, *output.Meta, error) { clean[key] = value } } + if jobs, exists := clean["list"]; exists { + if _, alreadyNormalized := clean["jobs"]; !alreadyNormalized { + clean["jobs"] = jobs + } + delete(clean, "list") + } pagination := &output.Pagination{EndpointExhausted: !hasMore, NextToken: nextToken, Pages: 1} meta := &output.Meta{Pagination: pagination} if jobs, exists := clean["jobs"].([]any); exists { diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index bfcb3936..d290de21 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -336,6 +336,35 @@ func TestRecruitListResultData(t *testing.T) { if err != nil || !terminal.Pagination.EndpointExhausted || terminal.Pagination.NextToken != "" { t.Fatalf("terminal meta = %#v, err = %v", terminal, err) } + + wrapped, wrappedMeta, err := recruitListResultData(map[string]any{ + "success": true, + "result": map[string]any{ + "list": []any{map[string]any{"jobId": "job-2", "name": "测试工程师"}}, + "hasMore": false, + "nextCursor": nil, + "totalCount": float64(1), + }, + }) + if err != nil { + t.Fatal(err) + } + wrappedData := wrapped.(map[string]any) + jobs, ok := wrappedData["jobs"].([]any) + if !ok || len(jobs) != 1 || wrappedData["totalCount"] != float64(1) { + t.Fatalf("wrapped data = %#v", wrappedData) + } + if _, exists := wrappedData["list"]; exists { + t.Fatalf("wrapped data retained Connector list field: %#v", wrappedData) + } + if wrappedMeta.Count == nil || *wrappedMeta.Count != 1 || !wrappedMeta.Pagination.EndpointExhausted { + t.Fatalf("wrapped meta = %#v", wrappedMeta) + } + + if _, _, err := recruitListResultData(map[string]any{"result": nil}); err == nil || + !strings.Contains(err.Error(), "result 必须是 JSON 对象") { + t.Fatalf("nil result error = %v", err) + } } func TestRecruitResultCallPropagatesMCPError(t *testing.T) { From 4a78e7c1d918a5f6ac05773f5339cbeaab26c776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Fri, 14 Aug 2026 10:56:47 +0800 Subject: [PATCH 099/250] fix(auth): reconcile managed MCP login region --- internal/app/auth_command.go | 82 +++++-- .../app/auth_command_full_coverage_test.go | 2 +- internal/app/auth_command_test.go | 200 ++++++++++++++++-- internal/app/coverage_edges_test.go | 36 ++++ internal/auth/coverage_edges_test.go | 12 +- internal/auth/portable_store.go | 2 +- pkg/config/constants.go | 5 + 7 files changed, 302 insertions(+), 37 deletions(-) diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index d4e0f7c1..33a9c715 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -60,6 +60,14 @@ type authLoginEndpointOverrides struct { MCPURL string } +type authLoginMCPPersistence uint8 + +const ( + authLoginMCPUseDefault authLoginMCPPersistence = iota + authLoginMCPUseManagedRegion + authLoginMCPUseExplicitOverride +) + type authLoginGuideAction string const ( @@ -154,7 +162,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { restoreLoginBaseURL := authpkg.PushLoginBaseURLOverride(preOverrides.LoginURL) defer restoreLoginBaseURL() } - mcpBaseURL, persistMCPURL, err := authLoginMCPBaseURLForConfig(cfg, preOverrides) + mcpBaseURL, mcpPersistence, err := authLoginMCPBaseURLForConfig(cfg, preOverrides) if err != nil { return err } @@ -224,7 +232,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command { } if tokenData != nil { - if err := persistAuthLoginMCPBaseURL(configDir, mcpBaseURL, persistMCPURL); err != nil { + if err := persistAuthLoginMCPBaseURL(configDir, mcpBaseURL, mcpPersistence); err != nil { return apperrors.NewInternal(fmt.Sprintf("failed to persist MCP URL: %v", err)) } } @@ -1019,6 +1027,7 @@ func newAuthResetCommand() *cobra.Command { return apperrors.NewInternal(fmt.Sprintf("failed to reset token data: %v", err)) } _ = authRemove(filepath.Join(configDir, "mcp_url")) + _ = authRemove(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)) _ = authRemove(filepath.Join(configDir, "token")) _ = authDeleteAppConfig(configDir) ResetRuntimeTokenCache() @@ -1362,35 +1371,84 @@ func authLoginEndpointOverridesForPreURL(raw string) (authLoginEndpointOverrides } } -func authLoginMCPBaseURLForConfig(cfg authLoginConfig, preOverrides authLoginEndpointOverrides) (string, bool, error) { +func authLoginMCPBaseURLForConfig(cfg authLoginConfig, preOverrides authLoginEndpointOverrides) (string, authLoginMCPPersistence, error) { if cfg.MCPURL != "" { _, normalized, err := normalizeAuthLoginBaseURL(cfg.MCPURL, "--mcp-url") if err != nil { - return "", false, err + return "", authLoginMCPUseDefault, err } - return normalized, true, nil + return normalized, authLoginMCPUseExplicitOverride, nil } if cfg.PreURL != "" { if preOverrides.MCPURL == "" { var err error preOverrides, err = authLoginEndpointOverridesForPreURL(cfg.PreURL) if err != nil { - return "", false, err + return "", authLoginMCPUseDefault, err } } - return preOverrides.MCPURL, true, nil + return preOverrides.MCPURL, authLoginMCPUseExplicitOverride, nil } if cfg.International { - return authpkg.InternationalMCPBaseURL, true, nil + return authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion, nil } - return authpkg.DefaultMCPBaseURL, false, nil + return authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault, nil } -func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persist bool) error { - if !persist { +func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persistence authLoginMCPPersistence) error { + mcpURLPath := filepath.Join(configDir, "mcp_url") + managedRegionPath := filepath.Join(configDir, config.ManagedMCPURLRegionFileName) + + switch persistence { + case authLoginMCPUseExplicitOverride: + if err := removeAuthLoginManagedMCPRegion(managedRegionPath); err != nil { + return fmt.Errorf("clear managed MCP region: %w", err) + } + if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil { + return fmt.Errorf("save explicit MCP URL: %w", err) + } return nil + case authLoginMCPUseManagedRegion: + if err := authAtomicWrite(managedRegionPath, []byte(mcpBaseURL), config.FilePerm); err != nil { + return fmt.Errorf("save managed MCP region: %w", err) + } + if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil { + _ = authRemove(managedRegionPath) + return fmt.Errorf("save managed MCP URL: %w", err) + } + return nil + case authLoginMCPUseDefault: + managedURL, err := authReadFile(managedRegionPath) + if os.IsNotExist(err) { + return nil + } + if err != nil { + return fmt.Errorf("read managed MCP region: %w", err) + } + currentURL, err := authReadFile(mcpURLPath) + if os.IsNotExist(err) { + return removeAuthLoginManagedMCPRegion(managedRegionPath) + } + if err != nil { + return fmt.Errorf("read MCP URL: %w", err) + } + if strings.TrimSpace(string(currentURL)) != strings.TrimSpace(string(managedURL)) { + return removeAuthLoginManagedMCPRegion(managedRegionPath) + } + if err := authAtomicWrite(mcpURLPath, []byte(mcpBaseURL), config.FilePerm); err != nil { + return fmt.Errorf("restore default MCP URL: %w", err) + } + return removeAuthLoginManagedMCPRegion(managedRegionPath) + default: + return fmt.Errorf("unsupported MCP persistence mode %d", persistence) } - return authpkg.NewManager(configDir, nil).SaveMCPURL(mcpBaseURL) +} + +func removeAuthLoginManagedMCPRegion(path string) error { + if err := authRemove(path); err != nil && !os.IsNotExist(err) { + return err + } + return nil } func normalizeAuthLoginBaseURL(raw, flagName string) (*url.URL, string, error) { diff --git a/internal/app/auth_command_full_coverage_test.go b/internal/app/auth_command_full_coverage_test.go index 4ba58ac3..2afdd00f 100644 --- a/internal/app/auth_command_full_coverage_test.go +++ b/internal/app/auth_command_full_coverage_test.go @@ -1457,7 +1457,7 @@ func TestCrossPlatformCoverageAuthCoveragePortableExchangeAndReset(t *testing.T) authRemove = func(string) error { removed++; return errors.New("ignored") } authDeleteAppConfig = func(string) error { removed++; return errors.New("ignored") } edition.Override(&edition.Hooks{}) - if err := reset.RunE(reset, nil); err != nil || removed != 3 || !strings.Contains(out.String(), "重新登录") { + if err := reset.RunE(reset, nil); err != nil || removed != 4 || !strings.Contains(out.String(), "重新登录") { t.Fatalf("reset = %q, %v, removed=%d", out.String(), err, removed) } edition.Override(&edition.Hooks{IsEmbedded: true}) diff --git a/internal/app/auth_command_test.go b/internal/app/auth_command_test.go index e4707218..e0af82d1 100644 --- a/internal/app/auth_command_test.go +++ b/internal/app/auth_command_test.go @@ -33,6 +33,8 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) @@ -1250,23 +1252,23 @@ func TestCrossPlatformCoverageAuthLoginEndpointOverridesForPreURL(t *testing.T) func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) { tests := []struct { - name string - cfg authLoginConfig - preOverride authLoginEndpointOverrides - wantURL string - wantPersist bool + name string + cfg authLoginConfig + preOverride authLoginEndpointOverrides + wantURL string + wantPersistence authLoginMCPPersistence }{ { - name: "default center login uses com without persisted override", - cfg: authLoginConfig{}, - wantURL: authpkg.DefaultMCPBaseURL, - wantPersist: false, + name: "default center login uses com and resets only managed region", + cfg: authLoginConfig{}, + wantURL: authpkg.DefaultMCPBaseURL, + wantPersistence: authLoginMCPUseDefault, }, { - name: "international login persists io", - cfg: authLoginConfig{International: true}, - wantURL: authpkg.InternationalMCPBaseURL, - wantPersist: true, + name: "international login persists managed io", + cfg: authLoginConfig{International: true}, + wantURL: authpkg.InternationalMCPBaseURL, + wantPersistence: authLoginMCPUseManagedRegion, }, { name: "pre login persists mapped pre mcp", @@ -1275,8 +1277,8 @@ func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) { LoginURL: "https://pre-login.dingtalk.io", MCPURL: "https://pre-mcp.dingtalk.io", }, - wantURL: "https://pre-mcp.dingtalk.io", - wantPersist: true, + wantURL: "https://pre-mcp.dingtalk.io", + wantPersistence: authLoginMCPUseExplicitOverride, }, { name: "explicit mcp url wins over pre url", @@ -1288,19 +1290,19 @@ func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) { LoginURL: "https://pre-login.dingtalk.io", MCPURL: "https://pre-mcp.dingtalk.io", }, - wantURL: "https://custom-mcp.example.com", - wantPersist: true, + wantURL: "https://custom-mcp.example.com", + wantPersistence: authLoginMCPUseExplicitOverride, }, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - gotURL, gotPersist, err := authLoginMCPBaseURLForConfig(tc.cfg, tc.preOverride) + gotURL, gotPersistence, err := authLoginMCPBaseURLForConfig(tc.cfg, tc.preOverride) if err != nil { t.Fatalf("authLoginMCPBaseURLForConfig error = %v", err) } - if gotURL != tc.wantURL || gotPersist != tc.wantPersist { - t.Fatalf("got url=%q persist=%v, want url=%q persist=%v", gotURL, gotPersist, tc.wantURL, tc.wantPersist) + if gotURL != tc.wantURL || gotPersistence != tc.wantPersistence { + t.Fatalf("got url=%q persistence=%v, want url=%q persistence=%v", gotURL, gotPersistence, tc.wantURL, tc.wantPersistence) } }) } @@ -1318,7 +1320,7 @@ func TestCrossPlatformCoverageAuthLoginMCPBaseURLForConfig(t *testing.T) { func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { t.Run("persists selected io mcp url", func(t *testing.T) { configDir := t.TempDir() - if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, true); err != nil { + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err) } data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")) @@ -1328,6 +1330,10 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { if string(data) != authpkg.InternationalMCPBaseURL { t.Fatalf("mcp_url = %q, want %q", string(data), authpkg.InternationalMCPBaseURL) } + managed, err := os.ReadFile(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)) + if err != nil || string(managed) != authpkg.InternationalMCPBaseURL { + t.Fatalf("managed MCP region = %q, %v", string(managed), err) + } }) t.Run("center login preserves previous persisted override", func(t *testing.T) { @@ -1337,7 +1343,7 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { if err := os.WriteFile(mcpURLPath, []byte(customURL), 0o600); err != nil { t.Fatalf("WriteFile(mcp_url) error = %v", err) } - if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, false); err != nil { + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil { t.Fatalf("persistAuthLoginMCPBaseURL error = %v", err) } data, err := os.ReadFile(mcpURLPath) @@ -1348,6 +1354,156 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { t.Fatalf("mcp_url = %q, want preserved override %q", string(data), customURL) } }) + + t.Run("center login resets a managed international URL", func(t *testing.T) { + configDir := t.TempDir() + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { + t.Fatal(err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil { + t.Fatal(err) + } + data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")) + if err != nil || string(data) != authpkg.DefaultMCPBaseURL { + t.Fatalf("mcp_url = %q, %v; want domestic default", string(data), err) + } + if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) { + t.Fatalf("managed region marker remains after domestic login: %v", err) + } + }) + + t.Run("explicit override clears region ownership", func(t *testing.T) { + configDir := t.TempDir() + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { + t.Fatal(err) + } + const customURL = "https://custom-mcp.example.com" + if err := persistAuthLoginMCPBaseURL(configDir, customURL, authLoginMCPUseExplicitOverride); err != nil { + t.Fatal(err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil { + t.Fatal(err) + } + data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")) + if err != nil || string(data) != customURL { + t.Fatalf("explicit mcp_url = %q, %v; want preserved custom URL", string(data), err) + } + }) + + t.Run("stale marker never deletes a different custom URL", func(t *testing.T) { + configDir := t.TempDir() + if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://custom.example.com"), config.FilePerm); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(configDir, config.ManagedMCPURLRegionFileName), []byte(authpkg.InternationalMCPBaseURL), config.FilePerm); err != nil { + t.Fatal(err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil { + t.Fatal(err) + } + data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")) + if err != nil || string(data) != "https://custom.example.com" { + t.Fatalf("custom mcp_url = %q, %v", string(data), err) + } + }) +} + +func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURLErrors(t *testing.T) { + fail := errors.New("persist failure") + + t.Run("explicit marker cleanup", func(t *testing.T) { + testseam.Swap(t, &authRemove, func(string) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), "https://custom.example.com", authLoginMCPUseExplicitOverride); !errors.Is(err, fail) { + t.Fatalf("explicit marker cleanup error = %v", err) + } + }) + + t.Run("explicit URL write", func(t *testing.T) { + testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), "https://custom.example.com", authLoginMCPUseExplicitOverride); !errors.Is(err, fail) { + t.Fatalf("explicit URL write error = %v", err) + } + }) + + t.Run("managed marker write", func(t *testing.T) { + testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) { + t.Fatalf("managed marker write error = %v", err) + } + }) + + t.Run("managed URL write cleans marker", func(t *testing.T) { + writes := 0 + removed := false + testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { + writes++ + if writes == 2 { + return fail + } + return nil + }) + testseam.Swap(t, &authRemove, func(string) error { removed = true; return nil }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) || !removed { + t.Fatalf("managed URL write error = %v, marker removed=%v", err, removed) + } + }) + + t.Run("managed marker read", func(t *testing.T) { + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return nil, fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) { + t.Fatalf("managed marker read error = %v", err) + } + }) + + t.Run("missing MCP URL cleans marker", func(t *testing.T) { + reads := 0 + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { + reads++ + if reads == 1 { + return []byte(authpkg.InternationalMCPBaseURL), nil + } + return nil, os.ErrNotExist + }) + testseam.Swap(t, &authRemove, func(string) error { return nil }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); err != nil { + t.Fatalf("missing MCP URL cleanup error = %v", err) + } + }) + + t.Run("MCP URL read", func(t *testing.T) { + reads := 0 + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { + reads++ + if reads == 1 { + return []byte(authpkg.InternationalMCPBaseURL), nil + } + return nil, fail + }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) { + t.Fatalf("MCP URL read error = %v", err) + } + }) + + t.Run("default URL write", func(t *testing.T) { + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return []byte(authpkg.InternationalMCPBaseURL), nil }) + testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) { + t.Fatalf("default URL write error = %v", err) + } + }) + + t.Run("final marker cleanup", func(t *testing.T) { + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return []byte(authpkg.InternationalMCPBaseURL), nil }) + testseam.Swap(t, &authAtomicWrite, func(string, []byte, os.FileMode) error { return nil }) + testseam.Swap(t, &authRemove, func(string) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) { + t.Fatalf("final marker cleanup error = %v", err) + } + }) + + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPPersistence(255)); err == nil { + t.Fatal("unsupported MCP persistence mode succeeded") + } } func TestCrossPlatformCoverageNormalizeAuthLoginBaseURLTransportSecurity(t *testing.T) { diff --git a/internal/app/coverage_edges_test.go b/internal/app/coverage_edges_test.go index 9d634365..74062171 100644 --- a/internal/app/coverage_edges_test.go +++ b/internal/app/coverage_edges_test.go @@ -36,6 +36,7 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport" upgradepkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes" tea "github.com/charmbracelet/bubbletea" @@ -998,6 +999,41 @@ func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) { }) } + t.Run("international then domestic login restores domestic MCP URL", func(t *testing.T) { + configDir := t.TempDir() + t.Setenv("DWS_CONFIG_DIR", configDir) + runLogin := func(international bool) { + t.Helper() + root := &cobra.Command{Use: "dws"} + root.PersistentFlags().String("format", "table", "") + root.PersistentFlags().Bool("yes", false, "") + root.PersistentFlags().String("profile", "", "") + root.AddCommand(newAuthLoginCommand(nil)) + args := []string{"login", "--token", "manual-token", "--yes"} + if international { + args = append(args, "--intl") + } + root.SetArgs(args) + root.SetOut(io.Discard) + root.SetErr(io.Discard) + if err := root.Execute(); err != nil { + t.Fatalf("international=%v login error = %v", international, err) + } + } + + runLogin(true) + if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != authpkg.InternationalMCPBaseURL { + t.Fatalf("international mcp_url = %q, %v", string(data), err) + } + runLogin(false) + if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != authpkg.DefaultMCPBaseURL { + t.Fatalf("domestic mcp_url = %q, %v", string(data), err) + } + if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) { + t.Fatalf("managed MCP region marker remains: %v", err) + } + }) + for _, hidden := range []bool{false, true} { old := edition.Get() edition.Override(&edition.Hooks{HideAuthLogin: hidden}) diff --git a/internal/auth/coverage_edges_test.go b/internal/auth/coverage_edges_test.go index d850988a..4fa0a166 100644 --- a/internal/auth/coverage_edges_test.go +++ b/internal/auth/coverage_edges_test.go @@ -22,6 +22,7 @@ import ( "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) @@ -1211,7 +1212,13 @@ func TestCrossPlatformCoveragePortableAuthBundleCoverageEdges(t *testing.T) { if err := os.Symlink(filepath.Join(keyDir, "dek"), filepath.Join(keyDir, "link")); err != nil { t.Fatal(err) } - for name, value := range map[string]string{"app.json": "{}", profilesJSONFile: "{}", "mcp_url": "https://mcp.test", "terminal_url": "https://terminal.test"} { + for name, value := range map[string]string{ + "app.json": "{}", + profilesJSONFile: "{}", + "mcp_url": "https://mcp.test", + config.ManagedMCPURLRegionFileName: "https://mcp.test", + "terminal_url": "https://terminal.test", + } { if err := os.WriteFile(filepath.Join(configDir, name), []byte(value), 0o600); err != nil { t.Fatal(err) } @@ -1234,6 +1241,9 @@ func TestCrossPlatformCoveragePortableAuthBundleCoverageEdges(t *testing.T) { if _, err := os.Stat(filepath.Join(importDir, "app.json")); err != nil { t.Fatal("config file was not imported") } + if _, err := os.Stat(filepath.Join(importDir, config.ManagedMCPURLRegionFileName)); err != nil { + t.Fatal("managed MCP region marker was not imported") + } if _, err := os.Stat(filepath.Join(keychain.StorageDir(keychain.Service), keychain.AccountToken+".enc")); err != nil { t.Fatal("encrypted token was not imported") } diff --git a/internal/auth/portable_store.go b/internal/auth/portable_store.go index 3be3f85a..420c9634 100644 --- a/internal/auth/portable_store.go +++ b/internal/auth/portable_store.go @@ -272,7 +272,7 @@ func ImportPortableAuthBundle(configDir string, r io.Reader) (PortableImportRepo func portableConfigFiles(configDir string) ([]string, error) { var files []string - patterns := []string{"app*.json", profilesJSONFile, "mcp_url", "terminal_url"} + patterns := []string{"app*.json", profilesJSONFile, "mcp_url", config.ManagedMCPURLRegionFileName, "terminal_url"} for _, pattern := range patterns { matches, err := portableGlob(filepath.Join(configDir, pattern)) if err != nil { diff --git a/pkg/config/constants.go b/pkg/config/constants.go index 4e7b934b..03b682cf 100644 --- a/pkg/config/constants.go +++ b/pkg/config/constants.go @@ -166,6 +166,11 @@ const ( // Override at runtime via ~/.dws/mcp_url file. DefaultMCPBaseURL = "https://mcp.dingtalk.com" + // ManagedMCPURLRegionFileName records an MCP URL written automatically by + // login region selection, so a later region change does not delete a user's + // explicit MCP override. + ManagedMCPURLRegionFileName = "mcp_url.login_region" + // DefaultTerminalBaseURL is the DingTalk developer platform base URL. // Override at runtime via ~/.dws/terminal_url file. DefaultTerminalBaseURL = "https://open-dev.dingtalk.com" From 0f5ecb609bb990321bfc5a11bdf068eee8fcb6a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Fri, 14 Aug 2026 11:38:26 +0800 Subject: [PATCH 100/250] fix(cli): restore audit join user guard --- .changes/954-chat-im-id-flags.md | 2 +- internal/cli/param_aliases_generated.go | 3 ++- internal/cli/param_aliases_test.go | 12 ++++++++++++ internal/cli/param_concepts.json | 2 ++ 4 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.changes/954-chat-im-id-flags.md b/.changes/954-chat-im-id-flags.md index a64f4369..ae77c7fa 100644 --- a/.changes/954-chat-im-id-flags.md +++ b/.changes/954-chat-im-id-flags.md @@ -4,4 +4,4 @@ category: Changed - **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` for conversation IDs and `--message-id` for message IDs, so help, Schema, and Agent recommendations use the same canonical flags. - **Legacy chat flag compatibility** (#954) — keeps older chat IM ID flags such as `--group`, `--id`, `--chat`, `--open-conversation-id`, `--msg-id`, and `--open-message-id` working as compatibility aliases where applicable, while hiding migrated aliases from recommended help and Schema surfaces. -- **Chat group name flags** (#954) — moves chat commands that accept a group name to the explicit `--group-name` flag, removing the public `--group` ambiguity between group names and conversation IDs on migrated command surfaces. +- **Chat group bots target flag** (#954) — keeps `dws chat group bots` on the visible `--group` flag; this command does not register `--group-name`, and `--group` accepts either an openConversationId or a uniquely resolved group name. diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index d1511342..c7c33ae3 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -974,7 +974,8 @@ var generatedParamAliases = []ParamAliasEntry{ Aliases: map[string]string{ "chat-id": "conversation-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target"}, + Ambiguous: []string{"staff-id", "uid", "user", "user-id", "userid"}, }, { CLIPath: "chat group bots", diff --git a/internal/cli/param_aliases_test.go b/internal/cli/param_aliases_test.go index 950d6ee5..843738f6 100644 --- a/internal/cli/param_aliases_test.go +++ b/internal/cli/param_aliases_test.go @@ -564,6 +564,18 @@ func TestGeneratedParamAliasesBlockPluralListSpellingsOnSingleIDCommands(t *test } } +func TestGeneratedParamAliasesKeepAuditJoinUserRoleAmbiguous(t *testing.T) { + entry, ok := LookupParamAlias("chat group audit-join-validation") + if !ok { + t.Fatal("missing generated alias entry for chat group audit-join-validation") + } + for _, name := range []string{"user", "user-id", "userid", "uid", "staff-id"} { + if !entry.IsAmbiguous(cmdutil.Morph(name)) { + t.Fatalf("%q not ambiguous; entry = %#v", name, entry) + } + } +} + // TestGeneratedParamAliasesAreWellFormed guards the committed generated table // at the Go level, complementing the byte-identity drift gate. func TestGeneratedParamAliasesAreWellFormed(t *testing.T) { diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index fb0fa444..f8297b32 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -146,6 +146,7 @@ "chat +chat-set-admin": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat +messages-read-status": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a mixed userId/openDingTalkId list."}, "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."}, + "chat group audit-join-validation": {"ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "A role-free user identifier cannot choose between the required --applicant and --inviter roles."}, "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."}, "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "ambiguous": ["chat", "chat-id", "open-conversation-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."}, @@ -471,6 +472,7 @@ {"command": "chat +flag-create", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"}, {"command": "chat +chat-add-bot", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"}, {"command": "chat +chat-add-bot", "emitted": "robot", "expect": "robot-code", "via": "concept:robot_code"}, + {"command": "chat group audit-join-validation", "emitted": "user", "expect": "did-you-mean:ambiguous", "via": "guard:applicant-vs-inviter-role"}, {"command": "chat +chat-audit-join", "emitted": "applicant-user-id", "expect": "applicant", "via": "override:scoped-user-role"}, {"command": "chat +chat-audit-join", "emitted": "user-id", "expect": "did-you-mean:ambiguous", "via": "guard:applicant-vs-inviter-role"}, {"command": "chat +chat-create", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list"}, From 4f754133a5577453c43c81a7f216cfd12a455832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Fri, 14 Aug 2026 11:43:39 +0800 Subject: [PATCH 101/250] fix(recruit): align pagination and size contracts --- internal/app/schema_recruit_contract_test.go | 12 +++++++++ .../framework2_changed_lines_coverage_test.go | 7 +++++ internal/helpers/helpers.go | 11 +++++++- internal/helpers/recruit.go | 6 +++-- internal/helpers/recruit_test.go | 27 +++++++++++++++++++ 5 files changed, 60 insertions(+), 3 deletions(-) diff --git a/internal/app/schema_recruit_contract_test.go b/internal/app/schema_recruit_contract_test.go index 6c6c4a2c..ece8ceb9 100644 --- a/internal/app/schema_recruit_contract_test.go +++ b/internal/app/schema_recruit_contract_test.go @@ -54,6 +54,18 @@ func TestRecruitDeliveredSchemaPublishesResultAndPagination(t *testing.T) { if cursor["type"] != "string" || cursor["interface_type"] != "number" { t.Fatalf("cursor contract = %#v, want CLI string converted to MCP number", cursor) } + size, _ := parameters["size"].(map[string]any) + if required, _ := size["required"].(bool); required { + t.Fatalf("size required = true, want false: %#v", size) + } + if size["default"] != "20" { + t.Fatalf("size default = %#v, want 20", size["default"]) + } + compactParameters, _ := compact["parameters"].(map[string]any) + compactSize, _ := compactParameters["size"].(map[string]any) + if compactRequired, _ := compactSize["required"].(bool); compactRequired || compactSize["default"] != "20" { + t.Fatalf("compact size contract = %#v, want required=false default=20", compactSize) + } } else if full["pagination"] != nil || compact["pagination"] != nil { t.Fatalf("non-list pagination must be absent: full=%#v compact=%#v", full["pagination"], compact["pagination"]) } diff --git a/internal/helpers/framework2_changed_lines_coverage_test.go b/internal/helpers/framework2_changed_lines_coverage_test.go index 00053300..b03fdc32 100644 --- a/internal/helpers/framework2_changed_lines_coverage_test.go +++ b/internal/helpers/framework2_changed_lines_coverage_test.go @@ -6,6 +6,7 @@ package helpers import ( "bytes" "context" + "encoding/json" "errors" "os" "path/filepath" @@ -58,6 +59,12 @@ func TestCrossPlatformCoverageFramework2MCPDataEdges(t *testing.T) { t.Fatalf("decoded data=%#v err=%v", data, err) } + InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{"cursor":9223372036854775807}`}}}}) + data, err = CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil) + if err != nil || data.(map[string]any)["cursor"] != json.Number("9223372036854775807") { + t.Fatalf("lossless number data=%#v err=%v", data, err) + } + InitDeps(&coverageErrorCaller{err: errors.New("transport failed")}) if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil { t.Fatal("expected transport error") diff --git a/internal/helpers/helpers.go b/internal/helpers/helpers.go index 384ddf32..14435768 100644 --- a/internal/helpers/helpers.go +++ b/internal/helpers/helpers.go @@ -6,6 +6,7 @@ import ( "context" "encoding/json" "fmt" + "io" "os" "strings" "time" @@ -284,7 +285,15 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg return map[string]any{}, nil } var data any - if err := json.Unmarshal([]byte(text), &data); err != nil { + decoder := json.NewDecoder(strings.NewReader(text)) + decoder.UseNumber() + if err := decoder.Decode(&data); err != nil { + return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", toolName, err)) + } + if err := decoder.Decode(&struct{}{}); err != io.EOF { + if err == nil { + err = fmt.Errorf("存在多个 JSON 值") + } return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", toolName, err)) } return data, nil diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 527615b2..ea0c95e0 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -100,7 +100,7 @@ func newRecruitJobListCommand() *cobra.Command { {Name: "keyword", Usage: "职位搜索关键词", Bind: "keyword", Trim: true, OmitEmpty: true}, {Name: "category", Usage: "职位分类", Bind: "category", Trim: true, OmitEmpty: true}, {Name: "cursor", Usage: "分页游标；首次查询不传，翻页时原样回填返回的 nextCursor", Bind: "cursor", Trim: true, OmitEmpty: true, Transform: transformRecruitCursor}, - {Name: "size", Usage: "分页大小，默认 20", Kind: LeafInt, Bind: "size", ArgDefault: "20"}, + {Name: "size", Usage: "分页大小，默认 20", Kind: LeafInt, Bind: "size", Default: "20", ArgDefault: "20"}, }, Validate: validateRecruitList, ResultCall: recruitResultCall, @@ -189,6 +189,8 @@ func recruitListResultData(data any) (any, *output.Meta, error) { switch value := raw.(type) { case string: nextToken = strings.TrimSpace(value) + case json.Number: + nextToken = string(value) case float64: nextToken = strconv.FormatFloat(value, 'f', -1, 64) default: @@ -299,7 +301,7 @@ func recruitListParamDecls() []contract.ParamDecl { {Name: "keyword", Property: "param.keyword", InterfaceType: "string"}, {Name: "category", Property: "param.category", InterfaceType: "string"}, {Name: "cursor", Property: "cursor", InterfaceType: "number"}, - {Name: "size", Property: "size", Required: boolPtr(true), InterfaceType: "number"}, + {Name: "size", Property: "size", InterfaceType: "number"}, } } diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index d290de21..e81d882e 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -132,6 +132,33 @@ func TestRecruitJobListCursorRoundTrip(t *testing.T) { } } +func TestRecruitJobListResponseCursorRoundTrip(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = `{"result":{"list":[],"hasMore":true,"nextCursor":9223372036854775807}}` + + data, err := CallMCPToolDataOnServer(context.Background(), recruitServerID, recruitListJobsTool, map[string]any{"size": 20}) + if err != nil { + t.Fatal(err) + } + _, meta, err := recruitListResultData(data) + if err != nil { + t.Fatal(err) + } + if got := meta.Pagination.NextToken; got != "9223372036854775807" { + t.Fatalf("next token = %q, want lossless max int64", got) + } + + caller.text = `{"jobs":[],"hasMore":false}` + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + cmd.SetArgs([]string{"--cursor", meta.Pagination.NextToken}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if got := caller.args["cursor"]; got != int64(9223372036854775807) { + t.Fatalf("replayed cursor = %#v (%T), want max int64", got, got) + } +} + func TestRecruitJobListDefaultsAndValidation(t *testing.T) { caller := withRecruitCaller(t) cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) From a7a0a9711500bc92ebbcdef4551e7df0b5792186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=BF=E7=9C=9F?= Date: Fri, 14 Aug 2026 12:25:07 +0800 Subject: [PATCH 102/250] test(chat): align open id fixtures with current format --- internal/helpers/chat_command_edges_test.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/internal/helpers/chat_command_edges_test.go b/internal/helpers/chat_command_edges_test.go index 3d9d63fb..118cc983 100644 --- a/internal/helpers/chat_command_edges_test.go +++ b/internal/helpers/chat_command_edges_test.go @@ -287,6 +287,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {"category", "remove-conv", "--group=cid", "--category-ids=1,2"}, {"message", "list-by-ids", "--msg-ids=" + strings.Repeat("id,", 51) + "last"}, {"group", "transfer-owner", "--group=cid", "--new-owner=D-owner"}, + {"group", "transfer-owner", "--group=cid", "--new-owner=DAAAAAAAAAAAiE"}, {"group", "update-icon", "--group=cid", "--icon-media-id=@valid"}, {"group", "set-history", "--group=cid", "--option=ALL"}, {"group", "audit-join-validation", "--conversation-id=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"}, @@ -435,8 +436,8 @@ func TestCrossPlatformCoverageChatSendCardHiddenAliasesMapToCanonicalPayload(t * }, { name: "receiver alias", - args: []string{"--receiver=D1"}, - want: map[string]any{"receiverOpenDingTalkId": "D1"}, + args: []string{"--receiver=DAAAAAAAAAAAiE"}, + want: map[string]any{"receiverOpenDingTalkId": "DAAAAAAAAAAAiE"}, }, } { t.Run(tc.name, func(t *testing.T) { From 322077be8930f68c74bdc08fbbf6f65481152654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=99=E8=BE=89?= Date: Fri, 14 Aug 2026 13:05:32 +0800 Subject: [PATCH 103/250] fix(auth): preserve explicit MCP override on intl login --- internal/app/auth_command.go | 13 +++++ internal/app/auth_command_test.go | 80 ++++++++++++++++++++++++++++- internal/app/coverage_edges_test.go | 12 +++++ 3 files changed, 104 insertions(+), 1 deletion(-) diff --git a/internal/app/auth_command.go b/internal/app/auth_command.go index 33a9c715..c914d755 100644 --- a/internal/app/auth_command.go +++ b/internal/app/auth_command.go @@ -1409,6 +1409,19 @@ func persistAuthLoginMCPBaseURL(configDir, mcpBaseURL string, persistence authLo } return nil case authLoginMCPUseManagedRegion: + managedURL, managedErr := authReadFile(managedRegionPath) + if managedErr != nil && !os.IsNotExist(managedErr) { + return fmt.Errorf("read managed MCP region: %w", managedErr) + } + currentURL, currentErr := authReadFile(mcpURLPath) + switch { + case currentErr == nil && os.IsNotExist(managedErr): + return nil + case currentErr == nil && strings.TrimSpace(string(currentURL)) != strings.TrimSpace(string(managedURL)): + return removeAuthLoginManagedMCPRegion(managedRegionPath) + case currentErr != nil && !os.IsNotExist(currentErr): + return fmt.Errorf("read MCP URL: %w", currentErr) + } if err := authAtomicWrite(managedRegionPath, []byte(mcpBaseURL), config.FilePerm); err != nil { return fmt.Errorf("save managed MCP region: %w", err) } diff --git a/internal/app/auth_command_test.go b/internal/app/auth_command_test.go index e0af82d1..31371e4a 100644 --- a/internal/app/auth_command_test.go +++ b/internal/app/auth_command_test.go @@ -1355,6 +1355,25 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { } }) + t.Run("international login preserves an unmanaged explicit override", func(t *testing.T) { + configDir := t.TempDir() + mcpURLPath := filepath.Join(configDir, "mcp_url") + const customURL = "https://private-mcp.example.com" + if err := os.WriteFile(mcpURLPath, []byte(customURL), config.FilePerm); err != nil { + t.Fatal(err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { + t.Fatal(err) + } + data, err := os.ReadFile(mcpURLPath) + if err != nil || string(data) != customURL { + t.Fatalf("explicit mcp_url = %q, %v; want preserved custom URL", string(data), err) + } + if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) { + t.Fatalf("unmanaged override acquired a managed marker: %v", err) + } + }) + t.Run("center login resets a managed international URL", func(t *testing.T) { configDir := t.TempDir() if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { @@ -1406,6 +1425,29 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURL(t *testing.T) { t.Fatalf("custom mcp_url = %q, %v", string(data), err) } }) + + t.Run("international login clears a stale marker without changing a custom URL", func(t *testing.T) { + configDir := t.TempDir() + mcpURLPath := filepath.Join(configDir, "mcp_url") + managedRegionPath := filepath.Join(configDir, config.ManagedMCPURLRegionFileName) + const customURL = "https://private-mcp.example.com" + if err := os.WriteFile(mcpURLPath, []byte(customURL), config.FilePerm); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(managedRegionPath, []byte(authpkg.DefaultMCPBaseURL), config.FilePerm); err != nil { + t.Fatal(err) + } + if err := persistAuthLoginMCPBaseURL(configDir, authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); err != nil { + t.Fatal(err) + } + data, err := os.ReadFile(mcpURLPath) + if err != nil || string(data) != customURL { + t.Fatalf("custom mcp_url = %q, %v", string(data), err) + } + if _, err := os.Stat(managedRegionPath); !os.IsNotExist(err) { + t.Fatalf("stale managed marker remains: %v", err) + } + }) } func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURLErrors(t *testing.T) { @@ -1432,6 +1474,42 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURLErrors(t *testing.T) { } }) + t.Run("managed marker read", func(t *testing.T) { + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return nil, fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) { + t.Fatalf("managed marker read error = %v", err) + } + }) + + t.Run("managed MCP URL read", func(t *testing.T) { + reads := 0 + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { + reads++ + if reads == 1 { + return nil, os.ErrNotExist + } + return nil, fail + }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) { + t.Fatalf("managed MCP URL read error = %v", err) + } + }) + + t.Run("managed stale marker cleanup", func(t *testing.T) { + reads := 0 + testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { + reads++ + if reads == 1 { + return []byte(authpkg.DefaultMCPBaseURL), nil + } + return []byte("https://private-mcp.example.com"), nil + }) + testseam.Swap(t, &authRemove, func(string) error { return fail }) + if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.InternationalMCPBaseURL, authLoginMCPUseManagedRegion); !errors.Is(err, fail) { + t.Fatalf("managed stale marker cleanup error = %v", err) + } + }) + t.Run("managed URL write cleans marker", func(t *testing.T) { writes := 0 removed := false @@ -1448,7 +1526,7 @@ func TestCrossPlatformCoveragePersistAuthLoginMCPBaseURLErrors(t *testing.T) { } }) - t.Run("managed marker read", func(t *testing.T) { + t.Run("default managed marker read", func(t *testing.T) { testseam.Swap(t, &authReadFile, func(string) ([]byte, error) { return nil, fail }) if err := persistAuthLoginMCPBaseURL(t.TempDir(), authpkg.DefaultMCPBaseURL, authLoginMCPUseDefault); !errors.Is(err, fail) { t.Fatalf("managed marker read error = %v", err) diff --git a/internal/app/coverage_edges_test.go b/internal/app/coverage_edges_test.go index 74062171..6f93ea55 100644 --- a/internal/app/coverage_edges_test.go +++ b/internal/app/coverage_edges_test.go @@ -1032,6 +1032,18 @@ func TestCrossPlatformCoverageAuthLoginTokenCommandCoverage(t *testing.T) { if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) { t.Fatalf("managed MCP region marker remains: %v", err) } + + const customURL = "https://private-mcp.example.com" + if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte(customURL), config.FilePerm); err != nil { + t.Fatal(err) + } + runLogin(true) + if data, err := os.ReadFile(filepath.Join(configDir, "mcp_url")); err != nil || string(data) != customURL { + t.Fatalf("explicit mcp_url after international login = %q, %v; want preserved custom URL", string(data), err) + } + if _, err := os.Stat(filepath.Join(configDir, config.ManagedMCPURLRegionFileName)); !os.IsNotExist(err) { + t.Fatalf("explicit mcp_url acquired a managed marker: %v", err) + } }) for _, hidden := range []bool{false, true} { From a6f69a06ced798801c586fdef4ae91a15e4e8a9e Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 11:58:18 +0800 Subject: [PATCH 104/250] =?UTF-8?q?fix(drive):=20--latest=20=E6=89=AB?= =?UTF-8?q?=E6=8F=8F=E4=B8=8D=E5=AE=8C=E6=95=B4=E6=97=B6=E6=8B=92=E7=BB=9D?= =?UTF-8?q?=E4=BA=A7=E5=87=BA=20Top-N=20=E5=B9=B6=E6=9D=9C=E7=BB=9D=20sort?= =?UTF-8?q?Time=20=E6=B3=84=E9=9C=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1-a sortTime 泄露进输出契约 —— 采集端无条件写内部排序字段 sortTime，而 emit 仅在单层（reqDepth==1）经 stripDriveDepthDecorations 整体剥离。depth>1 的所有路径都把 sortTime 漏进 stdout；#971 引入的 --type/时间区间过滤同样读该字段，泄露面随之扩大。修法：在 emitDriveDepthResult 尾部无条件 delete，一处覆盖正常 emit / SIGINT 取消 / unrecoverable partial 三条路径。采集端保持不动（内部字段，排序与筛选时才读）。 P1-b 不完整扫描仍以退出码 0 产出「Top-N」 —— 尾部拒绝 guard 只拦全局截断，不拦递归途中目录读取失败；后者把可恢复失败记进 errs[] 后照常 emit，Top-N 落在漏扫子树的不完整集合上却冒充全局最新。修法：guard 扩为 latest>0 && (truncated || len(errs)>0)，走新增 driveLatestIncompleteError（LATEST_SCAN_TRUNCATED / LATEST_SCAN_INCOMPLETE 双 token，二者同真时都带，目录失败详情排在截断之前）；unrecoverable 分支在 latest>0 时不吐 partial，直接回根因错误。 恢复命令必须能原样复现原候选集：driveLatestScope 快照查询域（--workspace / --space-id）、扫描根（--folder）与全部过滤条件（--pattern / --type / --start / --end），缺任一项，用户照抄后就在另一个集合上取 Top-N，看起来成功却答非所问。扫描根取 runDriveListDepth 实际使用的 rootFolderID 而非重读 flag：用户可能传 URL，解析后的 ID 才是真正被扫的目标。「按原范围重跑」原样带回原 --folder，原调用在空间根时不带。 拒绝产出后 errors[] 不再进 stdout，目录名与服务端错误文本从 JSON（编码会转义）挪进纯文本 stderr —— 原样透传会让 ANSI/OSC 序列被终端执行，可清屏、伪造彩色成功、隐藏后续输出、改窗口标题，Agent 场景还会污染上下文。改为复用仓库既有的 output.SanitizeForTerminal（canonical 实现在 pkg/validate），再把它按设计保留的换行与制表符折成空格。Reason 无需处理：它是 classifyDriveDepthReason 的固定三值映射。latest=0 的既有路径仍把原值放进 errors[] JSON，不受影响。 Windows 下恢复命令的注入面：POSIX 单引号在 cmd.exe 里不是引用，--space-id 传入 sp-7 加 & 加 whoami 时，单引号包裹后的片段粘贴进 cmd 仍会执行 whoami；而唯一做真 shell 往返验证的测试被 build tag 排除在 Windows 之外。不采用「按目标 shell 生成引用」的路线：cmd.exe 的双引号挡不住 %VAR% 展开，PowerShell 的内嵌单引号写法又与 POSIX 不同，且生成命令时无法知道用户会粘贴进哪个 shell。改为平台分流 —— POSIX 构建继续单引号内联；Windows 构建只内联全部由白名单字符组成的值，含元字符的值不进命令，降级为占位符加 strconv.Quote 展示行并标注非可执行（与 internal/auth 展示 profile 标识的既有做法同一思路）。安全性由此不再依赖引用是否正确，而依赖「不受信任的值不进入可执行命令」这个更强的不变量。 顺带修掉白名单里的一个漏洞：% 原本免引用（当初为 URL 的 %20），但 cmd.exe 会无条件展开 %VAR%，于是 %PATH% 这类值会被判为安全并原样内联。% 已移除，POSIX 侧只是多一对无害引号；并新增逐字符断言，锁定白名单不含 POSIX sh / PowerShell / cmd.exe 三套元字符，同时作为该缺陷的回归锁。 两条平台策略写成与构建平台无关的纯函数，平台文件只做一行编译期绑定，因此 Windows 形态能在 POSIX 机器上端到端验证 —— 否则该分支在 POSIX 上永不可达，平台覆盖率门禁会直接报未覆盖（第一版实测 97.3451%）。另做了一次本地全量模拟：临时把 POSIX 绑定切到 Windows 策略后跑全部测试，唯一失败的是专门断言绑定的那条，据此确认没有断言会在 Windows runner 误报，并借此修掉两条原本只在 POSIX 下成立的断言。 SIGINT 取消路径刻意不套用该防线：取消由用户主动发起、退出码 130 已明确告知结果不完整，partial 是用户的预期产物。已加注释说明并补测试锁定该契约。 skill 文档（mono/multi 两份 drive.md）原在过滤章节声明「触顶截断 truncated=true、退出码 0」，同章节又说明可与 --latest 组合 —— 组合后该描述不再成立，故补一条拒绝产出的说明，并注明 Windows 下的占位符形态，避免 agent 按旧契约预期退出码或误解析。 测试命名统一 TestCrossPlatformCoverage 前缀：平台覆盖率门禁 run-platform-coverage-gate.sh 只跑匹配 ^(TestAllShortcuts|TestCrossPlatformCoverage) 的测试。本 PR 因新增带平台名的 go:build 文件被判定 platform_sensitive，Coverage (macOS) / (Windows) 由 SKIPPED 转为实跑；不带该前缀时新增语句在平台 profile 里是零覆盖，实测 69.0476%，改名后 100.0000%（当前 114 条语句仍为 100%）。已在测试文件头写明该前缀是门禁约定而非命名风格。 发布说明按 .changes fragment 机制落在 .changes/899-drive-latest-incomplete-scan.md，不改 CHANGELOG.md。 --- .changes/899-drive-latest-incomplete-scan.md | 20 + internal/helpers/drive.go | 2 +- internal/helpers/drive_depth.go | 217 +++++- .../helpers/drive_latest_incomplete_test.go | 731 ++++++++++++++++++ internal/helpers/drive_latest_scope_posix.go | 13 + .../helpers/drive_latest_scope_windows.go | 13 + internal/helpers/shell_quote.go | 85 ++ .../shell_quote_roundtrip_unix_test.go | 76 ++ internal/helpers/shell_quote_test.go | 185 +++++ skills/mono/references/products/drive.md | 6 + .../multi/dingtalk-drive/references/drive.md | 6 + 11 files changed, 1347 insertions(+), 7 deletions(-) create mode 100644 .changes/899-drive-latest-incomplete-scan.md create mode 100644 internal/helpers/drive_latest_incomplete_test.go create mode 100644 internal/helpers/drive_latest_scope_posix.go create mode 100644 internal/helpers/drive_latest_scope_windows.go create mode 100644 internal/helpers/shell_quote.go create mode 100644 internal/helpers/shell_quote_roundtrip_unix_test.go create mode 100644 internal/helpers/shell_quote_test.go diff --git a/.changes/899-drive-latest-incomplete-scan.md b/.changes/899-drive-latest-incomplete-scan.md new file mode 100644 index 00000000..cc16c576 --- /dev/null +++ b/.changes/899-drive-latest-incomplete-scan.md @@ -0,0 +1,20 @@ +--- +category: Fixed +--- + +- **Drive `--latest` refuses incomplete Top-N** (#899) — `dws drive list --latest` used to + exit 0 with a "Top-N" computed over a partially scanned tree whenever a directory read + failed mid-recursion (permission denied, API error), letting an incomplete set pose as the + globally newest files. Truncation at the 2000-item scan cap and mid-recursion directory + failures now both fail closed (`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`), report + the first failing folder with its depth and reason, and emit a recovery command that + reproduces the original candidate set — query domain, `--folder`, `--pattern`, `--type`, + `--start` and `--end` are all carried over. On POSIX shells each user-supplied value is + quoted so a URL query string or a shell metacharacter cannot change how the copied command + parses. On Windows no quoting form is safe for both `cmd.exe` and PowerShell, so values + containing metacharacters are not inlined at all: the command carries a placeholder and the + original value is shown on a separate line marked as data rather than an executable command. + Unrecoverable errors under `--latest` return the root cause instead of a partial result. + Remote-controlled folder names and server error text are stripped of ANSI escapes and + control characters before they reach the plain-text stderr message. The internal `sortTime` + sort key no longer leaks into `drive list --depth` output on any path. diff --git a/internal/helpers/drive.go b/internal/helpers/drive.go index da4509ab..08243328 100644 --- a/internal/helpers/drive.go +++ b/internal/helpers/drive.go @@ -1226,7 +1226,7 @@ func newDriveCommand() *cobra.Command { driveListCmd.Flags().String("node", "", "文件 ID (dentryUuid) 或 URL (--versions 模式下必填)") driveListCmd.Flags().String("pattern", "", "按名称通配过滤结果，如 \"*日报*\" (客户端过滤) (可选)") driveListCmd.Flags().Int("depth", 1, "递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥；与 --workspace 组合时走知识库递归 (可选)") - driveListCmd.Flags().Int("latest", 0, "按修改时间取最新 N 个文件（1~50）；与 --pattern 组合时表示名称匹配的文件中最新 N 个；可与 --workspace/--depth 组合；与 --order-by/--order/--limit/--cursor 互斥 (可选)") + driveListCmd.Flags().Int("latest", 0, "按修改时间取最新 N 个文件（1~50）；与 --pattern 组合时表示名称匹配的文件中最新 N 个；可与 --workspace/--depth 组合；与 --order-by/--order/--limit/--cursor 互斥；扫描触发 2000 条上限或途中目录读取失败时报错，不产出不完整的 Top-N (可选)") driveListCmd.Flags().Bool("quiet", false, "关闭递归进度输出(stderr)，不影响 stdout JSON (--depth>1 或 --latest 多页扫描时有效) (可选)") driveListCmd.Flags().String("type", "", "按节点类型过滤: file|folder（客户端过滤：全量扫描后筛，钉盘/知识库均可用；与 --versions/--cursor/--order-by/--order/--limit 互斥）(可选)") driveListCmd.Flags().String("start", "", "按修改时间过滤·起始: 相对时间如 24h/7d/2w、RFC3339、YYYY-MM-DD（客户端过滤，互斥同 --type）(可选)") diff --git a/internal/helpers/drive_depth.go b/internal/helpers/drive_depth.go index 09432f7c..a10c28bd 100644 --- a/internal/helpers/drive_depth.go +++ b/internal/helpers/drive_depth.go @@ -10,11 +10,14 @@ import ( "os/signal" "path/filepath" "sort" + "strconv" "strings" "time" "github.com/fatih/color" "github.com/spf13/cobra" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" ) // ────────────────────────────────────────────────────────── @@ -296,6 +299,11 @@ bfs: if folderErr != nil { if driveDepthUnrecoverable(folderErr) { + if latest > 0 { + // 不完整集合上的 Top-N 会被误读为全局最新：latest 下不吐 partial， + // 直接回根因错误（auth 过期 / 网络不可达比通用 token 更可操作）。 + return folderErr + } // partial 照吐 stdout，错误详情走 stderr，非零退出 errs = append(errs, newDriveDepthError(folder, folderErr)) if emitErr := emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter); emitErr != nil { @@ -331,17 +339,206 @@ bfs: } } - if truncated && latest > 0 { - return &CLIError{ - Code: CodeContentTruncated, - Message: fmt.Sprintf("LATEST_SCAN_TRUNCATED: 扫描在全局上限 %d 条处截断，未扫描区域可能含更新文件，拒绝输出不完整的 Top-%d", driveDepthMaxItems, latest), - Suggestion: fmt.Sprintf("缩小扫描范围后重试：--folder 指定子目录，或降低 --depth 层数，如 dws drive list --folder <子目录ID> --latest %d", latest), - } + // BFS 序与修改时间无关：截断与递归途中目录失败都让未扫区域可能含更新文件， + // 此时的 Top-N 不是全局最新，两者同属一条防线——拒绝以成功状态产出。 + if latest > 0 && (truncated || len(errs) > 0) { + return driveLatestIncompleteError(latest, truncated, errs, driveLatestScopeFromCmd(cmd, maxDepth, rootFolderID)) } return emitDriveDepthResult(collected, errs, truncated, pattern, latest, maxDepth, route, filter) } +// driveLatestScope 是原调用的完整候选集快照，用于生成不改变候选集的恢复命令。 +// +// 恢复命令若丢掉任何一项，用户照抄后都会在**另一个集合**上拿到一份「看起来对」的 Top-N —— +// 比直接报错更难发现：丢 --workspace/--space-id 会从知识库切到普通钉盘（或反之）；丢 --folder +// 会从子树跳到空间根；丢 --pattern/--type/--start/--end 会把全部条目纳入排序基。 +type driveLatestScope struct { + // domain 是查询域 flag 串（如 "--workspace ws-1" / "--space-id sp-1"），无则空串。 + domain string + // filters 是决定候选集的过滤 flag 串（--pattern/--type/--start/--end），无则空串。 + filters string + // folder 是原调用实际使用的扫描根（已解析的 ID，非用户原始 URL），空则为空间根。 + folder string + // depth 是原调用的 --depth 层数，让「去掉 --latest 重跑」的恢复命令给出确切层数。 + depth int + // notes 收集无法安全内联进可执行命令的原值展示行。POSIX 构建下恒为空（单引号足够）； + // Windows 构建下含元字符的值走这里，命令里只留占位符。 + notes []string + // 以上 domain/filters/folder 里的值全部经 driveLatestScopeValue 渲染：恢复命令是给用户 + // 直接复制到 shell 执行的，而 workspace 的常见形态就是带 & 查询串的 URL，pattern 又天然 + // 含 * 与中文，裸拼接会改变命令解析。 +} + +// driveLatestValueRenderer 把用户值渲染成可内联的命令片段；ok 为 false 表示该值在目标 shell +// 下无法安全内联。取成参数而非直接调用平台绑定函数，是为了让任一平台的测试都能驱动另一平台 +// 的降级分支 —— 否则「Windows 上降级为占位符」这条路在 POSIX 机器上永不可达、无法验证。 +type driveLatestValueRenderer func(string) (string, bool) + +// value 渲染单个用户值供内联。值在目标 shell 下无法安全内联时，登记一条展示行并返回占位符 +// —— 宁可让用户手动粘一次，也不能给出一条粘贴即执行额外命令的「恢复命令」。 +// 展示行用 strconv.Quote 包裹并显式声明非可执行，与 internal/auth 侧展示 profile 标识一致。 +func (s *driveLatestScope) value(render driveLatestValueRenderer, label, v string) string { + if inline, ok := render(v); ok { + return inline + } + s.notes = append(s.notes, fmt.Sprintf("%s 原值（仅作数据展示，不是可执行命令）%s", label, strconv.Quote(v))) + return driveLatestUnsafeValuePlaceholder +} + +// driveLatestUnsafeValuePlaceholder 是不可内联值在命令中的占位符。 +const driveLatestUnsafeValuePlaceholder = "<见下方原值>" + +// driveLatestScopeFromCmd 从原命令抽完整候选集。--workspace 决定路由（知识库 vs 钉盘），判定与 +// drive list 里的路由分支同源（同一个 flagOrFallback(cmd, "workspace", "workspace-id")）； +// 钉盘侧的 --space-id 同样必须保留。目录 flag 名无需按路由切换：--folder 两条路由都接受。 +// +// rootFolder 取 runDriveListDepth 实际使用的扫描根而非重新读 flag：用户可能传的是 URL， +// 解析后的 ID 才是真正被扫描的目标，也是照抄时更精确的形态。 +func driveLatestScopeFromCmd(cmd *cobra.Command, depth int, rootFolder string) driveLatestScope { + return driveLatestScopeFrom(cmd, depth, rootFolder, driveLatestScopeValue) +} + +// driveLatestScopeFrom 是 driveLatestScopeFromCmd 的可注入本体：render 决定用户值以何种形态 +// 进入恢复命令。生产路径固定传平台绑定的 driveLatestScopeValue；测试可传另一平台的策略， +// 从而在单一平台上覆盖两种形态。 +func driveLatestScopeFrom(cmd *cobra.Command, depth int, rootFolder string, render driveLatestValueRenderer) driveLatestScope { + scope := driveLatestScope{depth: depth} + if workspaceID := flagOrFallback(cmd, "workspace", "workspace-id"); workspaceID != "" { + scope.domain = "--workspace " + scope.value(render, "--workspace", workspaceID) + } else if spaceID, _ := cmd.Flags().GetString("space-id"); spaceID != "" { + scope.domain = "--space-id " + scope.value(render, "--space-id", spaceID) + } + if rootFolder != "" { + scope.folder = scope.value(render, "--folder", rootFolder) + } + // 顺序固定为注册顺序，保证同一组入参每次给出同一条恢复命令（便于用户比对与测试断言）。 + filters := make([]string, 0, 4) + for _, name := range []string{"pattern", "type", "start", "end"} { + if v, _ := cmd.Flags().GetString(name); v != "" { + filters = append(filters, "--"+name+" "+scope.value(render, "--"+name, v)) + } + } + scope.filters = strings.Join(filters, " ") + return scope +} + +// command 拼一条保留原候选集的恢复命令：查询域 + 指定的 --folder + 原过滤条件。 +// folderArg 传 "" 表示该条命令不带 --folder（原调用就在空间根时不应凭空塞一个）。 +func (s driveLatestScope) command(folderArg string) string { + parts := make([]string, 0, 4) + parts = append(parts, "dws drive list") + if s.domain != "" { + parts = append(parts, s.domain) + } + if folderArg != "" { + parts = append(parts, "--folder "+folderArg) + } + if s.filters != "" { + parts = append(parts, s.filters) + } + return strings.Join(parts, " ") +} + +// driveLatestIncompleteError 是排序基不完整时的拒绝产出错误。截断与目录失败共用 +// CodeContentTruncated（→ ExitAPI），但 token 分开，便于消费方区分「范围太大」与「读不到」； +// 二者同真时两个 token 都带。拒绝产出后 errors[] 不再进 stdout，失败详情必须落在错误消息里， +// 否则用户完全瞎。调用点已保证 truncated 与 len(errs)>0 至少一真。 +func driveLatestIncompleteError(latest int, truncated bool, errs []driveDepthError, scope driveLatestScope) error { + // 目录失败详情排在截断之前：BFS 可以先记下可恢复目录错误、再在别的目录撞上 2000 上限， + // 此时 permission_denied 这类 reason 是用户唯一能动手修的线索，不能被截断提示吞掉。 + causes := make([]string, 0, 2) + if len(errs) > 0 { + causes = append(causes, driveLatestFolderFailureCause(errs)) + } + if truncated { + causes = append(causes, fmt.Sprintf("LATEST_SCAN_TRUNCATED: 扫描在全局上限 %d 条处截断", driveDepthMaxItems)) + } + return &CLIError{ + Code: CodeContentTruncated, + Message: fmt.Sprintf("%s，未扫描区域可能含更新文件，拒绝输出不完整的 Top-%d", + strings.Join(causes, "；同时 "), latest), + Suggestion: driveLatestIncompleteSuggestion(latest, truncated, len(errs) > 0, scope), + } +} + +// driveLatestFolderFailureCause 组装目录失败详情，含首个失败的 folder/depth/reason。 +// folderName 空回落 folderID，两者都空回落 。 +// +// folderName / folderID / message 三项都是远端可控内容（目录名由共享目录的创建者决定， +// message 是服务端错误文本），必须过 driveLatestSafeRemoteText。Reason 不用过：它是 +// classifyDriveDepthReason 的固定三值映射，与服务端字符串无关。 +func driveLatestFolderFailureCause(errs []driveDepthError) string { + first := errs[0] + folder := first.FolderName + if folder == "" { + folder = first.FolderID + } + if folder == "" { + folder = "" + } + return fmt.Sprintf("LATEST_SCAN_INCOMPLETE: %d 个目录未读全（首个失败 folder=%s depth=%d reason=%s: %s）", + len(errs), driveLatestSafeRemoteText(folder), first.Depth, first.Reason, + driveLatestSafeRemoteText(first.Message)) +} + +// driveLatestSafeRemoteText 把远端可控文本压成可安全嵌进单行 stderr 错误消息的形式。 +// +// 拒绝产出后 errors[] 不再进 stdout，失败详情改走纯文本错误消息 —— 而 JSON 编码会转义的 +// 控制字符在纯文本里会被终端直接执行：ANSI/OSC 序列可以伪造提示、清屏、隐藏后续内容、改窗口 +// 标题，在 AI Agent 场景还会污染上下文窗口。latest=0 的既有路径仍把原值放进 errors[] JSON， +// 不受影响，也不该受影响（消费方需要原始数据）。 +// +// output.SanitizeForTerminal 负责剥 ANSI/OSC、C0 控制字符与危险 Unicode，但按设计保留 \n 与 +// \t；本错误消息是单行叙述，故再把这两者折成空格，避免远端换行把一条错误拆成多行伪造输出。 +func driveLatestSafeRemoteText(s string) string { + s = output.SanitizeForTerminal(s) + s = strings.ReplaceAll(s, "\n", " ") + s = strings.ReplaceAll(s, "\t", " ") + return strings.TrimSpace(s) +} + +// driveLatestIncompleteSuggestion 按实际触发的成因给恢复指引。约束两条： +// 1. 每条示例命令都带原查询域（scope.base()），照抄不会切换查询域； +// 2. 每个子句的示例命令与该子句正文一致——「去掉 --latest」的子句示例不带 --latest， +// 否则照抄复现同一错误。 +func driveLatestIncompleteSuggestion(latest int, truncated, folderFailed bool, scope driveLatestScope) string { + // 「缩小范围」类命令要求用户换一个目录，故 --folder 给占位符；查询域与原过滤条件由 + // command 一并带上，否则照抄后候选集就变了（例如丢掉 --pattern 会对全部条目取 Top-N）。 + narrowed := scope.command("<可读子目录ID>") + clauses := make([]string, 0, 3) + if folderFailed { + clauses = append(clauses, "确认目录权限后重试") + } + switch { + case folderFailed && truncated: + // 两个成因都要解：既要换到可读目录，也要把范围缩到 2000 条以内。 + clauses = append(clauses, fmt.Sprintf("或用 --folder 缩小到可读子目录、并降低 --depth 层数后重取 Top-%d：%s --latest %d", latest, narrowed, latest)) + case folderFailed: + clauses = append(clauses, fmt.Sprintf("或用 --folder 缩小到可读子目录后重取 Top-%d：%s --latest %d", latest, narrowed, latest)) + default: + clauses = append(clauses, fmt.Sprintf("缩小扫描范围后重试：--folder 指定子目录，或降低 --depth 层数，如 %s --latest %d", narrowed, latest)) + } + // partial+errors[] 承诺限定 --depth>1：单层去掉 --latest 会路由回普通单层 list，本就无 + // errors[] 契约，故该子句只在多层时给出，并直接带上原层数。这是唯一一条「按原范围」命令， + // 必须原样带回原 --folder（原调用在空间根时则不带），照抄即复现同一候选集、只是不取 Top-N。 + if folderFailed && scope.depth > 1 { + clauses = append(clauses, fmt.Sprintf("需要看失败明细请去掉 --latest 按原范围重跑（同时输出已扫到的 partial 与 errors[] 明细）：%s --depth %d", scope.command(scope.folder), scope.depth)) + } + // Windows 构建下无法安全引用的值不会进入命令（cmd.exe 不把单引号当引号），原值改在此处以 + // 数据行给出，由用户手动替换占位符 —— 少一次复制粘贴的便利，换掉一条粘贴即执行的命令。 + if len(scope.notes) > 0 { + clauses = append(clauses, fmt.Sprintf("命令中的 %s 请手动替换为 —— %s", + driveLatestUnsafeValuePlaceholder, strings.Join(scope.notes, "、"))) + } + return strings.Join(clauses, "；") +} + +// emitDriveDepthCancelled 处理 SIGINT 取消：吐已扫到的 partial（truncated=true）后回退出码 130。 +// +// 这里刻意**不**套用 latest 的拒绝产出防线（只有 BFS 尾部 guard 与 unrecoverable 分支走）： +// 取消是用户主动发起的，退出码 130 本身已明确告知结果不完整，此时 partial 是用户的预期产物而 +// 非冒充全局最新的误导。sortTime 仍由 emitDriveDepthResult 统一剥除，取消路径不例外。 func emitDriveDepthCancelled(items []map[string]any, errs []driveDepthError, pattern string, latest, reqDepth int, route driveDepthRoute, filter driveListFilter) error { if err := emitDriveDepthResult(items, errs, true, pattern, latest, reqDepth, route, filter); err != nil { return err @@ -389,6 +586,14 @@ func emitDriveDepthResult(items []map[string]any, errs []driveDepthError, trunca maxDepth = d } } + // sortTime 是内部排序字段（applyDriveListLatest 排 Top-N、applyDriveListFilter 筛时间区间 + // 时都已用完），任何输出路径都不得泄露进契约。放在这里一处覆盖三条 emit 路径：正常 emit、 + // SIGINT 取消、unrecoverable partial。 + // depth/parentId/rel_path 不在此处删——它们是 depth>1 的既有输出契约， + // stripDriveDepthDecorations 仅在单层（reqDepth==1）把这套装饰整体剥掉。 + for _, item := range items { + delete(item, "sortTime") + } if (latest > 0 || filter.active()) && reqDepth == 1 { stripDriveDepthDecorations(items) } diff --git a/internal/helpers/drive_latest_incomplete_test.go b/internal/helpers/drive_latest_incomplete_test.go new file mode 100644 index 00000000..f2894056 --- /dev/null +++ b/internal/helpers/drive_latest_incomplete_test.go @@ -0,0 +1,731 @@ +package helpers + +import ( + "errors" + "fmt" + "strconv" + "strings" + "testing" + + "github.com/spf13/cobra" +) + +// 本文件锁定 drive list --latest 的两个 P1 行为，独立于 pr868_*_test.go / drive_depth_test.go： +// +// P1-a：sortTime 是内部排序字段，任何输出路径都不得泄露进契约； +// P1-b：递归途中目录读取失败时，Top-N 建立在不完整集合上，必须拒绝产出而非吐 partial。 +// +// 改代码前这些断言对 origin/main 应为红：main 采集端无条件写 sortTime、emit 仅在单层 +// latest/filter 才剥；main 尾部拒绝 guard 只拦截断、不拦目录失败。 +// +// 另锁定评审反馈的三个边界： +// +// 截断与目录失败同真时，失败详情（permission_denied 等）不得被截断提示吞掉； +// 拒绝产出时给的恢复命令必须保留原查询域（--workspace / --space-id），照抄不会切换查询域； +// 恢复命令里的用户值必须过 argv 引用，URL 查询串与 shell 元字符都不能改变命令解析。 +// +// 关于 TestCrossPlatformCoverage 前缀：这是门禁约定，不是命名风格。平台覆盖率门禁 +// scripts/policy/run-platform-coverage-gate.sh 只跑 +// -run '^(TestAllShortcuts|TestCrossPlatformCoverage)'，本包新增的生产代码若没有带该前缀的 +// 测试覆盖，Coverage (macOS) / (Windows) 会以「changed code coverage 低于 100%」失败 +// （本 PR 改名前实测 69.0476%，84 条可执行语句）。改名务必保留前缀。 + +// assertNoSortTime 断言 stdout 每个 item 都不含内部排序字段 sortTime。 +func assertNoSortTime(t *testing.T, result map[string]any) { + t.Helper() + items, ok := result["items"].([]any) + if !ok { + t.Fatalf("items missing or wrong type: %#v", result["items"]) + } + for i, raw := range items { + item, ok := raw.(map[string]any) + if !ok { + t.Fatalf("item[%d] not an object: %#v", i, raw) + } + if _, leaked := item["sortTime"]; leaked { + t.Fatalf("item[%d] leaked internal sortTime into output contract: %#v", i, item) + } + } +} + +// TestCrossPlatformCoverageDriveLatestNoSortTimeLeak 覆盖 main 的覆盖漏洞：main 的 +// TestCrossPlatformCoverageDriveDepthLatestTruncatedAndSortTime 名字带 SortTime， +// 却只断言 TRUNCATED、从不检查输出无 sortTime。这里把三条泄露路径都钉住。 +func TestCrossPlatformCoverageDriveLatestNoSortTimeLeak(t *testing.T) { + twoFiles := `{"items":[{"fileId":"f1","name":"a.txt","type":"FILE","modifiedTime":1000},{"fileId":"f2","name":"b.txt","type":"FILE","modifiedTime":2000}]}` + + // 场景 A：depth>1 --latest —— 走 applyDriveListLatest（只读 sortTime、不剥），reqDepth>1 不触发 strip。 + t.Run("depth_latest", func(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{}); err != nil { + t.Fatalf("runDriveListDepth: %v", err) + } + assertNoSortTime(t, decodeDepthResult(t, out)) + }) + + // 场景 B：--depth 2 无 latest 无 filter —— 走 else 分支树序排序，同样不触发 strip。 + t.Run("depth_no_latest", func(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{}); err != nil { + t.Fatalf("runDriveListDepth: %v", err) + } + assertNoSortTime(t, decodeDepthResult(t, out)) + }) + + // 场景 C：--depth 2 --type file —— #971 引入的 filter 也读 sortTime（applyDriveListFilter）， + // strip 条件 (latest>0||filter.active()) && reqDepth==1 在多层下依旧不成立，泄露面因此变大。 + t.Run("depth_filter_no_latest", func(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: twoFiles}}} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + if err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 2, "", true, 0, driveListFilter{nodeType: "file"}); err != nil { + t.Fatalf("runDriveListDepth: %v", err) + } + result := decodeDepthResult(t, out) + if len(result["items"].([]any)) != 2 { + t.Fatalf("filter 应保留两个 FILE: %#v", result["items"]) + } + assertNoSortTime(t, result) + }) +} + +// TestCrossPlatformCoverageDriveLatestSigintStillEmitsPartialWithoutSortTime 同时承担两件事： +// 1. P1-a 的第四条路径 —— SIGINT 取消也走 emitDriveDepthResult，同样不得泄露 sortTime； +// 2. SIGINT 契约锁 —— 本次 P1-b 只在 BFS 尾部 guard 与 unrecoverable 分支生效，**不改** +// 取消路径：SIGINT 是用户主动中断、退出码 130 已明确告知不完整，partial 是明确预期。 +// 这条测试防止后续误把 fail-closed 扩到取消路径，也为外部评测用例 +// test_sigint_exits_130_with_partial 提供本地对照。 +func TestCrossPlatformCoverageDriveLatestSigintStillEmitsPartialWithoutSortTime(t *testing.T) { + caller := &scriptedToolCaller{} + out := installDepthCaller(t, caller) + items := []map[string]any{ + {"fileId": "f1", "name": "a.txt", "type": "FILE", "sortTime": int64(2000), "rel_path": "a.txt", "depth": 2}, + } + errs := []driveDepthError{ + {Depth: 1, FolderID: "fid-1", FolderName: "半路目录", Reason: "permission_denied", Message: "denied"}, + } + // latest>0 且 reqDepth>1：main 在此不 strip，sortTime 泄露。 + err := emitDriveDepthCancelled(items, errs, "", 5, 3, newDrivePanDepthRoute(), driveListFilter{}) + var cancelErr *driveDepthCancelledError + if !errors.As(err, &cancelErr) { + t.Fatalf("err = %T %v, want driveDepthCancelledError", err, err) + } + if cancelErr.ExitCode() != 130 { + t.Fatalf("exit code = %d, want 130", cancelErr.ExitCode()) + } + result := decodeDepthResult(t, out) + // partial 契约不变：items 与 errors 都照吐，truncated 标记为真。 + if len(result["items"].([]any)) != 1 { + t.Fatalf("取消路径应保留 partial items: %#v", result["items"]) + } + if len(result["errors"].([]any)) != 1 { + t.Fatalf("取消路径应保留 errors[]: %#v", result["errors"]) + } + if result["truncated"] != true { + t.Fatalf("取消结果 truncated = %#v, want true", result["truncated"]) + } + assertNoSortTime(t, result) +} + +// TestCrossPlatformCoverageDriveLatestRefusesOnFolderFailure 覆盖 P1-b：递归途中一个可恢复目录失败（403/business， +// 非 auth 非限流 → 记 errs[] 跳过），Top-N 落在不完整集合上，必须拒绝产出。 +// 构造：根目录成功产出 FOLDER+FILE（collected>0 且 dirA 入队），子目录返回 forbidden.* → +// recoverable → errs=[1]。旧代码尾部 `if truncated && latest>0` 不触发 → emit 吐 partial（err=nil）； +// 新代码 `len(errs)>0` → LATEST_SCAN_INCOMPLETE 且 stdout 无 items。 +func TestCrossPlatformCoverageDriveLatestRefusesOnFolderFailure(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`}, + {text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`}, + }} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{}) + if err == nil || !strings.Contains(err.Error(), "LATEST_SCAN_INCOMPLETE") { + t.Fatalf("err = %v, want LATEST_SCAN_INCOMPLETE", err) + } + // 拒绝产出：stdout 必须没有 items（不是 partial）。旧代码此处会吐 partial，断言随之失败。 + if out.Len() != 0 { + t.Fatalf("expected no stdout on refusal, got: %s", out.String()) + } +} + +// TestCrossPlatformCoverageDriveLatestRefusesOnTruncationWithFolderFailure 端到端证明「截断 + 目录失败」组合确实可达： +// 根目录出 dirA/dirB 两个子目录 → dirA 权限失败记 errs[] → dirB 返回 2000 条触发全局截断， +// 尾部 guard 拿到 truncated=true 且 len(errs)=1。旧实现在此让 truncated 短路，permission_denied +// 详情整块丢失（评审反馈的阻塞点）；现在两个 token 与失败详情都必须在。 +func TestCrossPlatformCoverageDriveLatestRefusesOnTruncationWithFolderFailure(t *testing.T) { + useDriveDepthArgs(t) + var bulk strings.Builder + bulk.WriteString(`{"items":[`) + for i := 0; i < driveDepthMaxItems; i++ { + if i > 0 { + bulk.WriteString(",") + } + fmt.Fprintf(&bulk, `{"fileId":"f%d","name":"file-%d.txt","type":"FILE","modifiedTime":%d}`, i, i, 1000+i) + } + bulk.WriteString(`]}`) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[{"fileId":"dirA","name":"报表","type":"FOLDER"},{"fileId":"dirB","name":"dirB","type":"FOLDER"}]}`}, + {text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`}, // dirA：可恢复 → 记 errs[] + {text: bulk.String()}, // dirB：撞 2000 上限 → truncated + }} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{}) + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated { + t.Fatalf("err = %T %v, want CodeContentTruncated", err, err) + } + msg := cliErr.Message + if !strings.Contains(msg, "LATEST_SCAN_TRUNCATED") { + t.Fatalf("组合场景缺 TRUNCATED token: %q", msg) + } + // 旧实现在这里丢掉整段目录失败详情。 + if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") || + !strings.Contains(msg, "folder=报表") || + !strings.Contains(msg, "permission_denied") { + t.Fatalf("组合场景丢失目录失败详情: %q", msg) + } + if out.Len() != 0 { + t.Fatalf("expected no stdout on refusal, got: %s", out.String()) + } +} + +// TestCrossPlatformCoverageDriveLatestScopeWiredFromCommand 端到端验证查询域从原命令一路带到恢复命令：单测构造器 +// 拿不到的是 runDriveListDepth 里的接线（driveLatestScopeFromCmd(cmd, maxDepth, rootFolderID)），这里补上。 +func TestCrossPlatformCoverageDriveLatestScopeWiredFromCommand(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`}, + {text: `{"errorCode":"forbidden.noPermission","errorMsg":"denied"}`}, + }} + installDepthCaller(t, caller) + cmd := newDriveListScopeCmd(t, map[string]string{"space-id": "sp-7"}) + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{"spaceId": "sp-7"}, "", 4, "", true, 5, driveListFilter{}) + var cliErr *CLIError + if !errors.As(err, &cliErr) { + t.Fatalf("err = %T %v", err, err) + } + // 恢复命令必须带原 --space-id，且给出原 --depth 层数。 + assertDriveLatestSuggestion(t, cliErr.Suggestion, "--space-id sp-7") + if !strings.Contains(cliErr.Suggestion, "--depth 4") { + t.Fatalf("恢复命令应保留原层数: %q", cliErr.Suggestion) + } +} + +// TestCrossPlatformCoverageDriveLatestRefusesOnUnrecoverableFailure 覆盖 P1-b 的另一半：递归途中遇不可恢复错误 +// （auth 过期 / 网络不可达）且 latest>0 时，不吐 partial，直接回根因错误。 +// 与 latest=0 的既有行为（TestCrossPlatformCoverageRunDriveListDepthUnrecoverable：partial +// + errors[] 进 stdout 后非零退出）对照——latest 下 partial 的 Top-N 会被误读为全局最新， +// 故必须拒绝产出；回根因错误而非 INCOMPLETE token，因为 auth/网络比通用截断提示更可操作。 +func TestCrossPlatformCoverageDriveLatestRefusesOnUnrecoverableFailure(t *testing.T) { + useDriveDepthArgs(t) + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"items":[{"fileId":"dirA","name":"dirA","type":"FOLDER"},{"fileId":"fX","name":"x.txt","type":"FILE","modifiedTime":1000}]}`}, + {text: `{"errorCode":"DWS_SERVICE_UNAUTHORIZED"}`}, + }} + out := installDepthCaller(t, caller) + cmd := &cobra.Command{Use: "list"} + err := runDriveListDepth(cmd, newDrivePanDepthRoute(), map[string]any{}, "", 3, "", true, 5, driveListFilter{}) + // 回根因错误：Code 仍是 auth 过期，不被包装成 LATEST_SCAN_INCOMPLETE。 + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeAuthTokenExpired { + t.Fatalf("err = %T %v, want CodeAuthTokenExpired", err, err) + } + if strings.Contains(cliErr.Message, "LATEST_SCAN_INCOMPLETE") { + t.Fatalf("unrecoverable 应回根因错误而非 INCOMPLETE 包装: %q", cliErr.Message) + } + // 拒绝产出：不吐 partial（对照 latest=0 时会输出 2 条 items + 1 条 errors）。 + if out.Len() != 0 { + t.Fatalf("expected no stdout on refusal, got: %s", out.String()) + } +} + +// TestCrossPlatformCoverageDriveLatestIncompleteErrorBranches 直接单测构造器的各条分支。 +func TestCrossPlatformCoverageDriveLatestIncompleteErrorBranches(t *testing.T) { + // 纯截断分支：errs 为空 → 只有 TRUNCATED。 + t.Run("truncated_only", func(t *testing.T) { + err := driveLatestIncompleteError(5, true, nil, driveLatestScope{depth: 3}) + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated { + t.Fatalf("err = %T %v, want CodeContentTruncated", err, err) + } + if !strings.Contains(cliErr.Message, "LATEST_SCAN_TRUNCATED") { + t.Fatalf("message = %q", cliErr.Message) + } + if strings.Contains(cliErr.Message, "LATEST_SCAN_INCOMPLETE") { + t.Fatalf("无目录失败时不应出现 INCOMPLETE: %q", cliErr.Message) + } + assertDriveLatestSuggestion(t, cliErr.Suggestion, "") + }) + + // 纯目录失败分支：未截断 → 只有 INCOMPLETE，Message 含首个失败的 folder/depth/reason。 + t.Run("folder_failure_only", func(t *testing.T) { + err := driveLatestIncompleteError(3, false, twoDriveDepthErrors(), driveLatestScope{depth: 3}) + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated { + t.Fatalf("err = %T %v, want CodeContentTruncated", err, err) + } + msg := cliErr.Message + if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") || + !strings.Contains(msg, "报表") || + !strings.Contains(msg, "depth=2") || + !strings.Contains(msg, "permission_denied") || + !strings.Contains(msg, "2 个目录未读全") { + t.Fatalf("message = %q", msg) + } + if strings.Contains(msg, "LATEST_SCAN_TRUNCATED") { + t.Fatalf("未截断时不应出现 TRUNCATED: %q", msg) + } + assertDriveLatestSuggestion(t, cliErr.Suggestion, "") + }) + + // 组合分支（评审反馈的阻塞点）：截断与目录失败同真时，旧实现让 truncated 短路、 + // permission_denied 这类目录失败详情整块丢失。现在两个 token 都必须在，且失败详情不得被吞。 + t.Run("truncated_with_folder_failures", func(t *testing.T) { + err := driveLatestIncompleteError(4, true, twoDriveDepthErrors(), driveLatestScope{depth: 3}) + var cliErr *CLIError + if !errors.As(err, &cliErr) || cliErr.Code != CodeContentTruncated { + t.Fatalf("err = %T %v, want CodeContentTruncated", err, err) + } + msg := cliErr.Message + // 两个成因都要可被消费方 token 匹配到。 + if !strings.Contains(msg, "LATEST_SCAN_INCOMPLETE") || !strings.Contains(msg, "LATEST_SCAN_TRUNCATED") { + t.Fatalf("组合场景需同时带两个 token: %q", msg) + } + // 目录失败详情必须完整保留——这是用户唯一能动手修的线索。 + if !strings.Contains(msg, "报表") || + !strings.Contains(msg, "depth=2") || + !strings.Contains(msg, "permission_denied") || + !strings.Contains(msg, "2 个目录未读全") { + t.Fatalf("组合场景丢失目录失败详情: %q", msg) + } + if !strings.Contains(msg, "拒绝输出不完整的 Top-4") { + t.Fatalf("message 缺少拒绝产出结论: %q", msg) + } + assertDriveLatestSuggestion(t, cliErr.Suggestion, "") + // 组合场景的指引要同时覆盖两条补救：换可读目录 + 降层数。 + if !strings.Contains(cliErr.Suggestion, "确认目录权限") || !strings.Contains(cliErr.Suggestion, "--depth") { + t.Fatalf("组合场景 suggestion 需同时给出权限与降层数补救: %q", cliErr.Suggestion) + } + }) + + // folderName 为空回落 folderID；folderID 也空回落 。 + t.Run("folder_fallback", func(t *testing.T) { + byID := driveLatestIncompleteError(1, false, []driveDepthError{{FolderID: "fid-x"}}, driveLatestScope{depth: 2}) + if !strings.Contains(byID.Error(), "folder=fid-x") { + t.Fatalf("fallback to folderID: %v", byID) + } + byRoot := driveLatestIncompleteError(1, false, []driveDepthError{{}}, driveLatestScope{depth: 2}) + if !strings.Contains(byRoot.Error(), "folder=") { + t.Fatalf("fallback to : %v", byRoot) + } + }) +} + +// twoDriveDepthErrors 是两条目录失败样本，首条用于断言「首个失败」详情。 +func twoDriveDepthErrors() []driveDepthError { + return []driveDepthError{ + {Depth: 2, FolderID: "fid-9", FolderName: "报表", Reason: "permission_denied", Message: "denied"}, + {Depth: 1, FolderID: "fid-3", FolderName: "归档", Reason: "api_error", Message: "boom"}, + } +} + +// TestCrossPlatformCoverageDriveLatestScopePreservedInSuggestion 覆盖评审反馈的第二个阻塞点：恢复命令此前固定 +// 生成 `dws drive list --folder ...`，把原调用的 --workspace / --space-id 丢掉。用户照抄后 +// 会从知识库切到普通钉盘（或从指定钉盘空间切到「我的文件」），在另一个查询域里拿到一份 +// 「看起来对」的 Top-N —— 比直接报错更难发现。 +func TestCrossPlatformCoverageDriveLatestScopePreservedInSuggestion(t *testing.T) { + cases := []struct { + name string + flags map[string]string + want string + }{ + // 知识库路由：--workspace 决定路由，丢了就切到普通钉盘。 + {name: "workspace", flags: map[string]string{"workspace": "ws-1"}, want: "--workspace ws-1"}, + // 别名路径：--workspace-id 与 --workspace 同源（flagOrFallback）。 + {name: "workspace_id_alias", flags: map[string]string{"workspace-id": "ws-alias"}, want: "--workspace ws-alias"}, + // 钉盘路由：--space-id 丢了就退回「我的文件」。 + {name: "space_id", flags: map[string]string{"space-id": "sp-7"}, want: "--space-id sp-7"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, tc.flags), 3, "") + // 三条成因组合下的恢复命令都必须带原查询域。 + for _, variant := range []struct { + label string + truncated bool + errs []driveDepthError + }{ + {"truncated_only", true, nil}, + {"folder_failure_only", false, twoDriveDepthErrors()}, + {"both", true, twoDriveDepthErrors()}, + } { + err := driveLatestIncompleteError(5, variant.truncated, variant.errs, scope) + var cliErr *CLIError + if !errors.As(err, &cliErr) { + t.Fatalf("%s: err = %T %v", variant.label, err, err) + } + assertDriveLatestSuggestion(t, cliErr.Suggestion, tc.want) + } + }) + } + + // --workspace 优先于 --space-id：与 drive list 的路由判定同序（先看 workspace 再看 space-id）， + // 否则恢复命令会把知识库查询写成钉盘查询。 + t.Run("workspace_wins_over_space_id", func(t *testing.T) { + scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, map[string]string{ + "workspace": "ws-1", "space-id": "sp-7", + }), 3, "") + err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope) + suggestion := err.(*CLIError).Suggestion + if !strings.Contains(suggestion, "--workspace ws-1") || strings.Contains(suggestion, "--space-id") { + t.Fatalf("workspace 应优先且不混入 space-id: %q", suggestion) + } + }) + + // 无查询域时不得凭空造 flag（原调用就是「我的文件」根，硬塞 scope 同样是改查询域）。 + t.Run("no_scope_adds_nothing", func(t *testing.T) { + scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, nil), 3, "") + err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope) + suggestion := err.(*CLIError).Suggestion + if strings.Contains(suggestion, "--workspace") || strings.Contains(suggestion, "--space-id") { + t.Fatalf("无 scope 时不应凭空造查询域 flag: %q", suggestion) + } + assertDriveLatestSuggestion(t, suggestion, "") + }) + + // depth==1（知识库 --latest 单层）时不给 --depth 1：partial+errors[] 契约只在多层成立， + // 硬塞 --depth 1 会让「去掉 --latest 看明细」的子句自相矛盾。 + t.Run("single_depth_omits_depth_flag", func(t *testing.T) { + err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), driveLatestScope{domain: "--workspace ws-1", depth: 1}) + suggestion := err.(*CLIError).Suggestion + if strings.Contains(suggestion, "--depth") { + t.Fatalf("单层不应出现 --depth: %q", suggestion) + } + }) + + // 多层时给出确切层数，用户无需把 <原层数> 换成数字。 + t.Run("multi_depth_emits_actual_depth", func(t *testing.T) { + err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), driveLatestScope{domain: "--space-id sp-7", depth: 4}) + suggestion := err.(*CLIError).Suggestion + if !strings.Contains(suggestion, "--depth 4") { + t.Fatalf("应给出原层数 --depth 4: %q", suggestion) + } + if strings.Contains(suggestion, "<原层数>") { + t.Fatalf("不应残留占位符: %q", suggestion) + } + }) +} + +// TestCrossPlatformCoverageDriveLatestScopeQuotesHostileValues 覆盖评审的 P1 阻断项：恢复命令是给用户直接复制到 +// shell 里执行的，查询域的值来自用户输入（workspace 常见形态就是带查询串的 URL）。未引用时 +// 一个 `&` 就把命令拆成后台任务，`;` / `$()` 更能执行额外内容。 +// 断言落在「值被完整包在单引号里」而不只是「出现过」——后者对裸拼接也成立，抓不住缺陷。 +func TestCrossPlatformCoverageDriveLatestScopeQuotesHostileValues(t *testing.T) { + cases := []struct { + name string + flag string + value string + want string + }{ + // 合法 workspace URL：& 在裸拼接下直接改变 shell 解析（前半段被丢进后台）。 + {name: "workspace_url", flag: "workspace", value: "https://alidocs.dingtalk.com/i/nodes/abc?spaceId=1&type=doc", + want: `--workspace 'https://alidocs.dingtalk.com/i/nodes/abc?spaceId=1&type=doc'`}, + // 命令替换：裸拼接会在用户复制执行时真的跑起来。 + {name: "command_substitution", flag: "workspace", value: "$(id)", want: `--workspace '$(id)'`}, + // 分号拆语句。 + {name: "semicolon", flag: "space-id", value: "sp-7;id", want: `--space-id 'sp-7;id'`}, + // 空格拆参：裸拼接会让 --folder 收到错误的值。 + {name: "space", flag: "space-id", value: "sp 7", want: `--space-id 'sp 7'`}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + // 显式注入 POSIX 策略：本测试断言的是「危险值被单引号正确包住」这一 POSIX 形态。 + // Windows 策略下这些值根本不内联（见 ...SuggestionNeverInlinesHostileValue）， + // 若走平台绑定，这里在 Windows runner 上会因形态不同而误报。 + scope := driveLatestScopeFrom(newDriveListScopeCmd(t, map[string]string{tc.flag: tc.value}), 3, "", driveLatestPosixScopeValue) + err := driveLatestIncompleteError(5, true, twoDriveDepthErrors(), scope) + suggestion := err.(*CLIError).Suggestion + if !strings.Contains(suggestion, tc.want) { + t.Fatalf("查询域未安全引用\n want substring: %s\n got suggestion: %s", tc.want, suggestion) + } + }) + } +} + +// TestCrossPlatformCoverageDriveLatestScopePreservesFiltersAndFolder 覆盖自动 CR 的 P2： +// --pattern/--type/--start/--end 与 --folder 同样决定 --latest 的候选集合。恢复命令丢掉任一项， +// 用户照抄后就是在**另一个集合**上取 Top-N —— 原调用带 --pattern 时，缺了它的重试命令会对全部 +// 条目排序，结果「看起来成功」却答非所问，比直接报错更难发现。 +func TestCrossPlatformCoverageDriveLatestScopePreservesFiltersAndFolder(t *testing.T) { + cmd := newDriveListScopeCmd(t, map[string]string{ + "workspace": "ws-1", + "pattern": "*日报*", + "type": "file", + "start": "7d", + "end": "2026-08-01", + }) + // 注入 POSIX 策略：`--pattern '*日报*'` 这种引用形态是 POSIX 专属，Windows 下该值会降级为 + // 占位符 + 展示行（见 ...SuggestionNeverInlinesHostileValue）。走平台绑定会在 Windows 误报。 + scope := driveLatestScopeFrom(cmd, 4, "folder-root", driveLatestPosixScopeValue) + err := driveLatestIncompleteError(5, false, twoDriveDepthErrors(), scope) + suggestion := err.(*CLIError).Suggestion + + // 每条示例命令都要带齐查询域与全部过滤条件；pattern 含 * 与中文，必须是引用后的形态。 + for _, want := range []string{ + "--workspace ws-1", + "--pattern '*日报*'", + "--type file", + "--start 7d", + "--end 2026-08-01", + } { + for _, clause := range strings.Split(suggestion, "；") { + cmdText := extractTrailingDwsCommand(clause) + if cmdText == "" { + continue + } + if !strings.Contains(cmdText, want) { + t.Fatalf("恢复命令丢失候选集条件 %q:\n clause: %s", want, cmdText) + } + } + } + + // 「去掉 --latest 按原范围重跑」是唯一的原范围命令，必须原样带回原 --folder 而非占位符， + // 否则它就不是「原范围」。 + var origin string + for _, clause := range strings.Split(suggestion, "；") { + if strings.Contains(clause, "去掉 --latest") { + origin = extractTrailingDwsCommand(clause) + } + } + if origin == "" { + t.Fatalf("多层场景应给出「去掉 --latest 按原范围重跑」子句: %q", suggestion) + } + if !strings.Contains(origin, "--folder folder-root") { + t.Fatalf("原范围命令应保留原 --folder: %q", origin) + } + if strings.Contains(origin, "<可读子目录ID>") { + t.Fatalf("原范围命令不应把原 --folder 换成占位符: %q", origin) + } +} + +// TestCrossPlatformCoverageDriveLatestScopeOmitsFolderAtSpaceRoot 原调用就在空间根时不得凭空 +// 造 --folder：硬塞一个目录同样是改候选集。 +func TestCrossPlatformCoverageDriveLatestScopeOmitsFolderAtSpaceRoot(t *testing.T) { + scope := driveLatestScopeFromCmd(newDriveListScopeCmd(t, map[string]string{"space-id": "sp-7"}), 3, "") + err := driveLatestIncompleteError(2, false, twoDriveDepthErrors(), scope) + suggestion := err.(*CLIError).Suggestion + for _, clause := range strings.Split(suggestion, "；") { + if !strings.Contains(clause, "去掉 --latest") { + continue + } + if strings.Contains(extractTrailingDwsCommand(clause), "--folder") { + t.Fatalf("空间根扫描的原范围命令不应带 --folder: %q", clause) + } + } +} + +// TestCrossPlatformCoverageDriveLatestErrorStripsRemoteControlChars 覆盖自动 CR 的 P2 安全项： +// 拒绝产出后，目录名与服务端错误文本从 JSON（编码时会被转义）挪进了纯文本 stderr。若原样透传， +// 其中的 ANSI/OSC 序列会被终端直接执行 —— 可清屏、伪造彩色「成功」、隐藏后续输出、改窗口标题， +// 在 AI Agent 场景还会污染上下文窗口。目录名对共享目录而言是他人可控输入。 +func TestCrossPlatformCoverageDriveLatestErrorStripsRemoteControlChars(t *testing.T) { + assertNoControlChars := func(t *testing.T, msg string) { + t.Helper() + for name, r := range map[string]rune{"ESC": 0x1b, "BEL": 0x07, "CR": '\r', "LF": '\n', "TAB": '\t'} { + if strings.ContainsRune(msg, r) { + t.Fatalf("错误消息残留 %s 控制字符: %q", name, msg) + } + } + } + + // folderName 路径：CSI 清屏 + 变色，外加 OSC 改标题。 + t.Run("folder_name", func(t *testing.T) { + err := driveLatestIncompleteError(3, false, []driveDepthError{{ + Depth: 2, + FolderName: "报表\x1b[2J\x1b[31m看起来成功\x1b[0m", + Reason: "permission_denied", + Message: "denied\r\n\x1b]0;pwned\x07次行", + }}, driveLatestScope{depth: 2}) + msg := err.(*CLIError).Message + assertNoControlChars(t, msg) + // 清理不能把诊断信息一起抹掉：可读部分必须留下。 + if !strings.Contains(msg, "报表") || !strings.Contains(msg, "denied") || !strings.Contains(msg, "次行") { + t.Fatalf("清理后应保留可读文本: %q", msg) + } + }) + + // folderName 为空时回落到 folderID，该字段同样来自服务端。 + t.Run("folder_id_fallback", func(t *testing.T) { + err := driveLatestIncompleteError(1, true, []driveDepthError{{ + FolderID: "fid\x1b[1m-x", + Reason: "api_error", + Message: "boom", + }}, driveLatestScope{depth: 1}) + msg := err.(*CLIError).Message + assertNoControlChars(t, msg) + if !strings.Contains(msg, "fid-x") { + t.Fatalf("剥离控制序列后 folderID 应连成 fid-x: %q", msg) + } + }) +} + +// TestCrossPlatformCoverageDriveLatestSafeRemoteText 直接钉住清理函数的各条分支：换行/制表符 +// 折成空格（SanitizeForTerminal 按设计保留这两者，但单行错误消息里它们会拆出伪造行）， +// 首尾空白收掉，可打印内容与中文原样保留。 +func TestCrossPlatformCoverageDriveLatestSafeRemoteText(t *testing.T) { + cases := []struct { + name string + in string + want string + }{ + {name: "plain", in: "denied", want: "denied"}, + {name: "cjk", in: "报表目录", want: "报表目录"}, + {name: "csi", in: "a\x1b[31mb", want: "ab"}, + {name: "osc", in: "a\x1b]0;t\x07b", want: "ab"}, + {name: "newline_to_space", in: "a\nb", want: "a b"}, + {name: "tab_to_space", in: "a\tb", want: "a b"}, + {name: "carriage_return_dropped", in: "a\rb", want: "ab"}, + {name: "trim_outer", in: "\n denied \t", want: "denied"}, + {name: "empty", in: "", want: ""}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := driveLatestSafeRemoteText(tc.in); got != tc.want { + t.Fatalf("driveLatestSafeRemoteText(%q) = %q, want %q", tc.in, got, tc.want) + } + }) + } +} + +// TestCrossPlatformCoverageDriveLatestSuggestionNeverInlinesHostileValue 端到端锁定评审提出的 +// Windows 注入阻断项：`--space-id sp-7&whoami` 这种值，在 POSIX 下靠单引号关停，但 cmd.exe +// 不把单引号当引号，粘贴后 `&whoami` 仍会执行。因此不变量必须是「恢复命令里不存在能被目标 +// shell 解释的裸元字符」，两个平台分别用各自的手段满足：POSIX 引用内联，Windows 不内联。 +// +// 两种形态都通过注入渲染策略在本机验证，不依赖当前 GOOS —— 否则「Windows 上降级为占位符」 +// 这条路在 POSIX 机器上永不可达，就成了只有 Windows runner 才跑到的盲区（平台覆盖率门禁也会 +// 因此报未覆盖）。平台绑定本身由 TestCrossPlatformCoverageDriveLatestScopeValueBinding 覆盖。 +func TestCrossPlatformCoverageDriveLatestSuggestionNeverInlinesHostileValue(t *testing.T) { + const hostile = "sp-7&whoami" + newSuggestion := func(t *testing.T, render driveLatestValueRenderer) string { + t.Helper() + scope := driveLatestScopeFrom(newDriveListScopeCmd(t, map[string]string{"space-id": hostile}), 3, "", render) + return driveLatestIncompleteError(5, true, twoDriveDepthErrors(), scope).(*CLIError).Suggestion + } + + t.Run("windows_never_inlines", func(t *testing.T) { + suggestion := newSuggestion(t, driveLatestWindowsScopeValue) + for _, clause := range strings.Split(suggestion, "；") { + cmdText := extractTrailingDwsCommand(clause) + if cmdText == "" { + continue + } + // cmd.exe 里 & 分隔命令，且单引号不是引号，故它压根不能进命令。 + if strings.Contains(cmdText, "&") { + t.Fatalf("windows 形态的命令不得含 &: %s", cmdText) + } + if strings.Contains(cmdText, hostile) { + t.Fatalf("windows 形态的命令不得内联原值: %s", cmdText) + } + } + if !strings.Contains(suggestion, driveLatestUnsafeValuePlaceholder) { + t.Fatalf("应降级为占位符: %s", suggestion) + } + if !strings.Contains(suggestion, strconv.Quote(hostile)) { + t.Fatalf("应在展示行给出原值: %s", suggestion) + } + if !strings.Contains(suggestion, "不是可执行命令") { + t.Fatalf("展示行须显式声明非可执行: %s", suggestion) + } + }) + + t.Run("posix_quotes_inline", func(t *testing.T) { + suggestion := newSuggestion(t, driveLatestPosixScopeValue) + if !strings.Contains(suggestion, "'"+hostile+"'") { + t.Fatalf("posix 形态应单引号内联原值: %s", suggestion) + } + // POSIX 下不该无谓降级 —— 那会白白损失可复制体验。 + if strings.Contains(suggestion, driveLatestUnsafeValuePlaceholder) { + t.Fatalf("posix 形态不应降级为占位符: %s", suggestion) + } + for _, clause := range strings.Split(suggestion, "；") { + cmdText := extractTrailingDwsCommand(clause) + if cmdText == "" { + continue + } + if strings.Contains(cmdText, "&") && !strings.Contains(cmdText, "'"+hostile+"'") { + t.Fatalf("posix 形态出现未引用的元字符: %s", cmdText) + } + } + }) +} + +// newDriveListScopeCmd 造一个带 drive list 查询域与过滤 flag 的命令。flag 名与 newDriveCommand +// 里 driveListCmd 的注册保持一致；workspace-id 是 cross-product 别名，此处显式注册以覆盖别名路径。 +func newDriveListScopeCmd(t *testing.T, flags map[string]string) *cobra.Command { + t.Helper() + cmd := &cobra.Command{Use: "list"} + for _, name := range []string{ + "workspace", "workspace-id", "space-id", // 查询域 + "folder", // 扫描根（scope 从 rootFolder 参数取，注册仅为对齐真实命令） + "pattern", "type", "start", "end", // 决定候选集的过滤条件 + } { + cmd.Flags().String(name, "", "") + } + for name, value := range flags { + if err := cmd.Flags().Set(name, value); err != nil { + t.Fatalf("set --%s=%s: %v", name, value, err) + } + } + return cmd +} + +// assertDriveLatestSuggestion 钉住 Suggestion 的三条约束： +// 1. 每条示例命令都带原查询域 wantScope（空串表示原调用无查询域，此时只跳过该项检查）； +// 2. 含 --latest 的引导子句存在； +// 3. 「去掉 --latest」子句给出的示例命令本身不带 --latest（否则照抄复现同一错误）。 +func assertDriveLatestSuggestion(t *testing.T, suggestion, wantScope string) { + t.Helper() + clauses := strings.Split(suggestion, "；") + sawLatestGuide := false + for _, clause := range clauses { + cmd := extractTrailingDwsCommand(clause) + if cmd == "" { + continue + } + if wantScope != "" && !strings.Contains(cmd, wantScope) { + t.Fatalf("示例命令丢失原查询域 %q（照抄会切换查询域）: %q", wantScope, cmd) + } + if strings.Contains(clause, "去掉 --latest") { + if strings.Contains(cmd, "--latest") { + t.Fatalf("「去掉 --latest」子句的示例命令仍含 --latest: %q", cmd) + } + continue + } + if strings.Contains(cmd, "--latest") { + sawLatestGuide = true + } + } + if !sawLatestGuide { + t.Fatalf("no --latest-bearing guidance clause in suggestion: %q", suggestion) + } +} + +// extractTrailingDwsCommand 抽子句里以 "dws " 开头的尾部命令片段（到子句末），无则空串。 +func extractTrailingDwsCommand(clause string) string { + idx := strings.LastIndex(clause, "dws ") + if idx < 0 { + return "" + } + return clause[idx:] +} diff --git a/internal/helpers/drive_latest_scope_posix.go b/internal/helpers/drive_latest_scope_posix.go new file mode 100644 index 00000000..a92ff0d5 --- /dev/null +++ b/internal/helpers/drive_latest_scope_posix.go @@ -0,0 +1,13 @@ +//go:build !windows + +package helpers + +// driveLatestScopeValue 按**本次构建的目标 shell** 渲染恢复命令里的用户值：返回可内联的片段， +// 第二个返回值为 false 时表示该值不能安全进入可执行命令，调用方须改用占位符。 +// +// 非 Windows 构建面向 POSIX shell，单引号可靠地关闭所有展开，故含元字符的值引用后内联即安全。 +// Windows 构建见 drive_latest_scope_windows.go —— 两个平台的策略本体都是 +// shell_quote.go 里的纯函数，可在任意平台被测试直接调用；本文件只做编译期绑定。 +func driveLatestScopeValue(value string) (string, bool) { + return driveLatestPosixScopeValue(value) +} diff --git a/internal/helpers/drive_latest_scope_windows.go b/internal/helpers/drive_latest_scope_windows.go new file mode 100644 index 00000000..f921a456 --- /dev/null +++ b/internal/helpers/drive_latest_scope_windows.go @@ -0,0 +1,13 @@ +//go:build windows + +package helpers + +// driveLatestScopeValue 按**本次构建的目标 shell** 渲染恢复命令里的用户值：返回可内联的片段， +// 第二个返回值为 false 时表示该值不能安全进入可执行命令，调用方须改用占位符。 +// +// Windows 构建下没有对 cmd.exe 与 PowerShell 同时成立的引用形式（cmd.exe 不认单引号，双引号 +// 又挡不住 %VAR% 展开），故只内联本身就安全的值；理由与取舍详见 +// driveLatestWindowsScopeValue 的注释。POSIX 构建见 drive_latest_scope_posix.go。 +func driveLatestScopeValue(value string) (string, bool) { + return driveLatestWindowsScopeValue(value) +} diff --git a/internal/helpers/shell_quote.go b/internal/helpers/shell_quote.go new file mode 100644 index 00000000..a06f78f5 --- /dev/null +++ b/internal/helpers/shell_quote.go @@ -0,0 +1,85 @@ +package helpers + +import "strings" + +// shellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。 +// +// 为什么需要它：错误提示里的恢复命令是给用户直接复制到 shell 执行的，其中的查询域取自用户 +// 输入（--workspace 的常见形态就是带查询串的 URL）。裸拼接下，合法 URL 里的 `&` 就会把命令 +// 拆成后台任务，空格会拆参，`;` 与 `$()` 还能执行额外内容。 +// +// 为什么不用 strconv.Quote（internal/auth 侧展示 profile 标识的既有做法）：那是 Go 语法引号， +// 产出双引号串，而 shell 双引号内 `$()`、反引号、`$VAR` 仍会展开——正是要防的场景。auth 那处 +// 成立是因为它显式声明「仅作数据展示，不是可执行命令」，本函数的产物恰恰要能执行。 +// +// 策略是「必要时才引用」：全由安全字符组成时原样返回，命令保持可读、在 PowerShell/cmd 下同样 +// 可复制；只要含一个非安全字符就整体单引号包裹——单引号内 POSIX sh 不做任何展开（$ ` \ ! 全部 +// 字面化），是唯一无需逐字符转义的形式。单引号自身无法出现在单引号串内，按 POSIX 标准写法 +// 先闭合、拼一个反斜杠转义的单引号、再重开——即把每个单引号替换成下面这四个字符： +// +// '\'' +// +// 空串必须显式引用成一对空单引号，否则该参数会从 argv 里整个消失，后面的 token 会被前一个 +// flag 吞掉。 +func shellQuoteArg(s string) string { + if s == "" { + return "''" + } + if shellValueIsBare(s) { + return s + } + return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'" +} + +// shellValueIsBare 报告 s 能否原样出现在命令行里而不改变**任何**常见 shell 的解析：非空， +// 且每个字符都落在保守白名单内。这类值在 POSIX sh、PowerShell 与 cmd.exe 下含义一致， +// 无需引用即可内联进可复制命令。 +func shellValueIsBare(s string) bool { + return s != "" && !strings.ContainsFunc(s, shellNeedsQuote) +} + +// driveLatestPosixScopeValue 是 POSIX shell 下把用户值放进可复制命令的策略：单引号内 sh 不做 +// 任何展开，因此含元字符的值引用后即可安全内联。第二个返回值恒为 true。 +func driveLatestPosixScopeValue(value string) (string, bool) { + return shellQuoteArg(value), true +} + +// driveLatestWindowsScopeValue 是 Windows 构建下的策略：只内联本身就安全的值，其余一律不进 +// 命令，由调用方降级为占位符 + 展示行。 +// +// Windows 上不存在「一条命令同时对 cmd.exe 与 PowerShell 都安全」的引用形式： +// - cmd.exe 根本不把单引号当引号，`--space-id 'sp-7&whoami'` 里的 & 仍然分隔命令， +// 粘贴即执行 whoami； +// - cmd.exe 的双引号能挡 & | < >，却挡不住 %VAR% 展开； +// - PowerShell 的单引号是引号，但内嵌单引号写作两个连续单引号，与 POSIX 的 +// 闭合-反斜杠转义-重开写法不兼容。 +// +// 而生成命令时无法知道用户会粘贴进哪个 shell。既然引用不可靠，就不把不受信任的值放进可执行 +// 命令——与 internal/auth 侧「标识仅作数据展示，不是可执行命令」的既有做法同一思路。 +func driveLatestWindowsScopeValue(value string) (string, bool) { + if shellValueIsBare(value) { + return value, true + } + return "", false +} + +// shellNeedsQuote 报告 r 是否落在「无需引用」白名单之外。 +// +// 用白名单而非黑名单：漏掉一个元字符就是一个注入口，而白名单漏一个字符只会多加一对无害的 +// 引号。非 ASCII 一律视为需引用——中文目录名很常见，保守处理不会错。 +// +// 白名单的门槛是「在 POSIX sh、PowerShell、cmd.exe 下含义都一致」，因此 % 被刻意排除： +// cmd.exe 会展开 %VAR%，一个看似普通的值（URL 里的 %20、含 %PATH% 的名字）原样内联后在 +// cmd 里就会变形甚至泄露环境变量。@ 保留：PowerShell 的 splatting 只在 @( 、@{ 与 +// @变量名 形态下生效，而那些字符本身都不在白名单里，且值总出现在 --flag 之后而非语句开头。 +func shellNeedsQuote(r rune) bool { + switch { + case r >= 'a' && r <= 'z': + return false + case r >= 'A' && r <= 'Z': + return false + case r >= '0' && r <= '9': + return false + } + return !strings.ContainsRune("_@+=:,./-", r) +} diff --git a/internal/helpers/shell_quote_roundtrip_unix_test.go b/internal/helpers/shell_quote_roundtrip_unix_test.go new file mode 100644 index 00000000..9afc5213 --- /dev/null +++ b/internal/helpers/shell_quote_roundtrip_unix_test.go @@ -0,0 +1,76 @@ +//go:build !windows + +package helpers + +import ( + "os/exec" + "testing" +) + +// TestCrossPlatformCoverageShellQuoteArgRoundTrip 把引用后的串交给真 /bin/sh 求值，证明它被解析回 +// **恰好一个、且内容完全相同**的参数。上面那条表驱动测试只能证明「我以为的形态」，这条证明 +// 「shell 认的形态」——两者不是一回事，恢复命令是给用户复制到 shell 里跑的，后者才是契约。 +// +// 它同时是注入的负向对照：一旦引用失效，$(id) / `id` 会真的执行、空格与 & 会拆参，argc 或 +// 取回的值必然不等于原值，测试立刻红。用 build tag 排除 Windows（无 POSIX sh），跨平台形态 +// 断言留在 shell_quote_test.go。 +func TestCrossPlatformCoverageShellQuoteArgRoundTrip(t *testing.T) { + sh, err := exec.LookPath("sh") + if err != nil { + t.Skipf("POSIX sh unavailable: %v", err) + } + + values := []string{ + "ws-1", + "https://alidocs.dingtalk.com/i/nodes/x?spaceId=1&type=doc", + "sp 7", + "a;id", + "a&b", + "a|b", + "$(id)", + "`id`", + "$HOME", + "*.txt", + "a>b", + `a\b`, + `a"b`, + "a!b", + "{a,b}", + "(a)", + "~/x", + "a#b", + "it's", + "'", + "a'b'c", + "", + "报表", + "a\tb", + "a\nb", + "--not-a-flag", + } + + for _, want := range values { + t.Run(want, func(t *testing.T) { + quoted := shellQuoteArg(want) + + // 1) 未被拆参也未被吞掉：位置参数个数必须恰好为 1。 + // 引用失效时 "sp 7" 会变 2 个、"" 会变 0 个、$(id) 会变 id 的输出词数。 + argc, err := exec.Command(sh, "-c", "set -- "+quoted+`; printf %s "$#"`).Output() + if err != nil { + t.Fatalf("argc probe failed for %q (quoted %s): %v", want, quoted, err) + } + if string(argc) != "1" { + t.Fatalf("argc = %s, want 1 — %q quoted as %s split or vanished", argc, want, quoted) + } + + // 2) 内容逐字节相同：展开、命令替换、转义都不得改动值。 + got, err := exec.Command(sh, "-c", "set -- "+quoted+`; printf %s "$1"`).Output() + if err != nil { + t.Fatalf("value probe failed for %q (quoted %s): %v", want, quoted, err) + } + if string(got) != want { + t.Fatalf("round-trip mismatch\n input: %q\n quoted: %s\n shell: %q", want, quoted, got) + } + }) + } +} diff --git a/internal/helpers/shell_quote_test.go b/internal/helpers/shell_quote_test.go new file mode 100644 index 00000000..2dacbf7d --- /dev/null +++ b/internal/helpers/shell_quote_test.go @@ -0,0 +1,185 @@ +package helpers + +import ( + "runtime" + "testing" +) + +// TestCrossPlatformCoverageShellQuoteArg 表驱动锁定 argv 引用规则。分两类断言： +// - 安全值原样返回（保持恢复命令可读，且在 PowerShell/cmd 下同样可复制）； +// - 含任何 shell 元字符的值整体单引号包裹，内嵌单引号按 POSIX 标准写法处理 +// （闭合、拼反斜杠转义的单引号、重开）。 +// +// 往返正确性另有 Unix 下用真 sh 求值的对照测试（shell_quote_roundtrip_unix_test.go）。 +// +// TestCrossPlatformCoverage 前缀是门禁约定：平台覆盖率门禁只跑该前缀（与 TestAllShortcuts）的 +// 测试，shell_quote.go 的覆盖全靠这一条，去掉前缀会让 Coverage (macOS)/(Windows) 直接红。 +// 详见 drive_latest_incomplete_test.go 头部说明。 +func TestCrossPlatformCoverageShellQuoteArg(t *testing.T) { + cases := []struct { + name string + in string + want string + }{ + // —— 无需引用：白名单字符 —— + {name: "plain_id", in: "ws-1", want: "ws-1"}, + {name: "digits", in: "1234567890", want: "1234567890"}, + {name: "upper_lower", in: "abcXYZ", want: "abcXYZ"}, + {name: "all_safe_punct", in: "_@+=:,./-", want: "_@+=:,./-"}, + {name: "path_like", in: "/tmp/a.b/c-d_e", want: "/tmp/a.b/c-d_e"}, + + // —— 必须引用：真实业务形态 —— + // workspace 常见形态就是带查询串的 URL：? 与 & 都不在白名单，& 在裸拼接下会拆命令。 + {name: "url_with_query", in: "https://alidocs.dingtalk.com/i/nodes/x?spaceId=1&type=doc", + want: `'https://alidocs.dingtalk.com/i/nodes/x?spaceId=1&type=doc'`}, + + // —— 必须引用：shell 元字符 —— + {name: "space", in: "sp 7", want: `'sp 7'`}, + {name: "tab", in: "a\tb", want: "'a\tb'"}, + {name: "newline", in: "a\nb", want: "'a\nb'"}, + {name: "semicolon", in: "a;id", want: `'a;id'`}, + {name: "ampersand", in: "a&b", want: `'a&b'`}, + {name: "pipe", in: "a|b", want: `'a|b'`}, + {name: "command_substitution", in: "$(id)", want: `'$(id)'`}, + {name: "backtick", in: "`id`", want: "'`id`'"}, + {name: "variable", in: "$HOME", want: `'$HOME'`}, + // % 不在白名单：cmd.exe 会展开 %VAR%，故含 % 的值一律视为需引用。 + {name: "windows_variable", in: "%PATH%", want: `'%PATH%'`}, + {name: "url_percent_escape", in: "a%20b", want: `'a%20b'`}, + {name: "glob", in: "*.txt", want: `'*.txt'`}, + {name: "redirect", in: "a>b", want: `'a>b'`}, + {name: "backslash", in: `a\b`, want: `'a\b'`}, + {name: "double_quote", in: `a"b`, want: `'a"b'`}, + {name: "history_expansion", in: "a!b", want: `'a!b'`}, + {name: "brace", in: "{a,b}", want: `'{a,b}'`}, + {name: "paren", in: "(a)", want: `'(a)'`}, + {name: "tilde", in: "~/x", want: `'~/x'`}, + {name: "hash", in: "a#b", want: `'a#b'`}, + + // —— 单引号：唯一无法直接放进单引号串的字符 —— + {name: "single_quote", in: "it's", want: `'it'\''s'`}, + {name: "only_single_quote", in: "'", want: `''\'''`}, + {name: "two_single_quotes", in: "a'b'c", want: `'a'\''b'\''c'`}, + + // —— 边界 —— + // 空串必须显式成 ''，否则参数会从 argv 里整个消失（--workspace 吞掉下一个 token）。 + {name: "empty", in: "", want: `''`}, + // 非 ASCII 一律引用：保守优于漏字符，中文目录名很常见。 + {name: "cjk", in: "报表", want: `'报表'`}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := shellQuoteArg(tc.in); got != tc.want { + t.Fatalf("shellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want) + } + }) + } +} + +// TestCrossPlatformCoverageDriveLatestScopeValueStrategies 直接测两条平台策略的本体。它们是 +// shell_quote.go 里的纯函数、与构建平台无关，因此**在任一平台都能验证 Windows 侧的行为** —— +// 这一点是刻意设计：真 shell 往返测试只能在 Unix 跑，Windows 的安全属性必须由这里钉住， +// 否则「Windows 上不会把不受信任值放进可执行命令」就成了无人复核的断言。 +func TestCrossPlatformCoverageDriveLatestScopeValueStrategies(t *testing.T) { + // 这些值在至少一种目标 shell 下会改变命令解析。 + hostile := []struct { + name string + value string + }{ + {"cmd_command_separator", "sp-7&whoami"}, // cmd.exe：& 分隔命令，单引号不是引号 + {"cmd_variable", "%PATH%"}, // cmd.exe：无条件展开 + {"workspace_url", "https://x/y?a=1&b=2"}, // 合法 workspace 形态，含 & + {"space", "sp 7"}, + {"pwsh_statement_separator", "a;id"}, // PowerShell：; 分隔语句 + {"posix_substitution", "$(id)"}, + {"backtick", "`id`"}, + {"posix_variable", "$HOME"}, + {"pipe", "a|b"}, + {"redirect", "a>b"}, + {"caret", "a^b"}, // cmd.exe 转义符 + {"single_quote", "it's"}, + {"cjk", "报表"}, + {"empty", ""}, + } + for _, tc := range hostile { + t.Run("hostile/"+tc.name, func(t *testing.T) { + // POSIX：始终可内联，但必须是引用后的形态（不能等于原值）。 + got, ok := driveLatestPosixScopeValue(tc.value) + if !ok { + t.Fatalf("POSIX 策略应始终可内联: %q", tc.value) + } + if got == tc.value { + t.Fatalf("POSIX 策略未引用危险值: %q", tc.value) + } + // Windows：一律拒绝内联 —— 没有对 cmd.exe 与 PowerShell 同时安全的引用形式。 + if inline, ok := driveLatestWindowsScopeValue(tc.value); ok { + t.Fatalf("Windows 策略不得内联危险值 %q（得到 %q）", tc.value, inline) + } + }) + } + + // 安全值：两条策略都原样内联，命令保持可读、跨 shell 可复制。 + for _, v := range []string{"ws-1", "sp-7", "folder-root", "modifyTime", "7d", "2026-08-01", "a.b/c-d_e", "a@b"} { + t.Run("bare/"+v, func(t *testing.T) { + if got, ok := driveLatestPosixScopeValue(v); !ok || got != v { + t.Fatalf("POSIX 应原样内联安全值 %q: got %q ok=%v", v, got, ok) + } + if got, ok := driveLatestWindowsScopeValue(v); !ok || got != v { + t.Fatalf("Windows 应原样内联安全值 %q: got %q ok=%v", v, got, ok) + } + }) + } + + // 空串在 POSIX 下引用成一对空单引号（否则参数会从 argv 消失）；Windows 侧归入不可内联。 + if got, ok := driveLatestPosixScopeValue(""); !ok || got != "''" { + t.Fatalf("POSIX 空串应引用成一对空单引号: got %q ok=%v", got, ok) + } +} + +// TestCrossPlatformCoverageShellBareCharsetHasNoMetacharacters 锁定「安全值可原样内联」的根本 +// 前提：白名单里不能含任何一种目标 shell 会特殊解释的字符。 +// +// 这比「用某个 shell 跑一遍」更本质 —— 内联路径的安全性不来自引用正确，而来自字符集本身无害； +// 而拒绝内联的路径（Windows 侧）连引用都不需要。三套元字符合并检查：POSIX sh、PowerShell、 +// cmd.exe。`%` 曾因 URL 转义（%20）被误列入白名单，而 cmd.exe 会无条件展开 %VAR%，这条测试 +// 同时是该缺陷的回归锁。 +func TestCrossPlatformCoverageShellBareCharsetHasNoMetacharacters(t *testing.T) { + // 逐字符列出，避免用字符串字面量时漏掉转义细节。 + meta := []rune{ + '&', '|', '<', '>', ';', '(', ')', '{', '}', '[', ']', // 分隔/分组 + '$', '`', '"', '\'', '\\', // 引用与替换 + '^', '%', // cmd.exe：转义符与变量展开 + '*', '?', '~', '#', '!', // 通配、家目录、注释、历史/取反 + ' ', '\t', '\n', '\r', // 空白：拆参与换行注入 + } + for _, r := range meta { + if !shellNeedsQuote(r) { + t.Fatalf("shell 元字符 %q 落在「无需引用」白名单内，安全值会被原样内联", string(r)) + } + } + // 反向哨兵：常规标识符字符必须留在白名单内，否则恢复命令会被无谓地全量引用/降级。 + for _, r := range []rune{'a', 'Z', '0', '9', '_', '-', '.', '/', ':', ',', '=', '+', '@'} { + if shellNeedsQuote(r) { + t.Fatalf("常规字符 %q 被判为需引用，会让恢复命令可读性无谓下降", string(r)) + } + } +} + +// TestCrossPlatformCoverageDriveLatestScopeValueBinding 断言当前构建绑定到了正确的策略。 +// 这条测试在每个平台各自成立，把「哪个平台用哪条策略」也纳入 CI（Coverage (Windows) 会跑它）。 +func TestCrossPlatformCoverageDriveLatestScopeValueBinding(t *testing.T) { + const hostile = "sp-7&whoami" + inline, ok := driveLatestScopeValue(hostile) + if runtime.GOOS == "windows" { + if ok { + t.Fatalf("windows 构建不得内联 %q（得到 %q）", hostile, inline) + } + return + } + if !ok { + t.Fatalf("posix 构建应可内联 %q", hostile) + } + if inline != `'sp-7&whoami'` { + t.Fatalf("posix 构建应单引号包裹: %s", inline) + } +} diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 8bed0f87..63f9b30d 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -67,6 +67,12 @@ Flags: - 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 - 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 +- 与 `--latest` 组合时上一条不适用：排序基不完整的 Top-N 不是全局最新，故触顶截断**或**递归途中 + 目录读取失败都拒绝产出并报错（`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`），不会以 + 退出码 0 交出结果；错误消息里带首个失败目录的 folder/depth/reason，以及一条复现原候选集 + （查询域 + `--folder` + `--pattern`/`--type`/`--start`/`--end`）的恢复命令。Windows 构建下， + 若原值含 shell 元字符则命令里只给占位符、原值另起一行以数据形式列出（cmd.exe 与 PowerShell + 没有共同安全的引用形式），照抄时需手动替换。 ### 获取钉盘空间列表 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 8d921447..5da0ba4a 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -61,6 +61,12 @@ Flags: - 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 - 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 +- 与 `--latest` 组合时上一条不适用：排序基不完整的 Top-N 不是全局最新，故触顶截断**或**递归途中 + 目录读取失败都拒绝产出并报错（`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`），不会以 + 退出码 0 交出结果；错误消息里带首个失败目录的 folder/depth/reason，以及一条复现原候选集 + （查询域 + `--folder` + `--pattern`/`--type`/`--start`/`--end`）的恢复命令。Windows 构建下， + 若原值含 shell 元字符则命令里只给占位符、原值另起一行以数据形式列出（cmd.exe 与 PowerShell + 没有共同安全的引用形式），照抄时需手动替换。 ### 获取钉盘空间列表 From d8f8f29062a4fe5a349cf9322cd554f744750f33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Fri, 14 Aug 2026 14:06:08 +0800 Subject: [PATCH 105/250] fix(recruit): unwrap connector result envelopes --- internal/helpers/recruit.go | 70 +++++++++++----- internal/helpers/recruit_test.go | 139 ++++++++++++++++++++++++++++++- 2 files changed, 188 insertions(+), 21 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index ea0c95e0..fae5c5b1 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -151,35 +151,67 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou if err != nil { return nil, err } - if tool != recruitListJobsTool { - return output.Success(data), nil - } - clean, meta, err := recruitListResultData(data) + clean, err := recruitBusinessResultData(data, tool) if err != nil { - return output.Failure(&output.ErrorInfo{ - Type: "api", Subtype: "pagination_inconsistent", Message: err.Error(), - Hint: "保留原始响应并停止翻页；不要把当前页当作完整结果。", - }), nil + return recruitInvalidResponse(err), nil } - return output.Success(clean, output.WithMeta(meta)), nil + if tool != recruitListJobsTool { + return output.Success(clean), nil + } + listData, meta, err := recruitListResultData(clean) + if err != nil { + return recruitInvalidResponse(err), nil + } + return output.Success(listData, output.WithMeta(meta)), nil +} + +func recruitBusinessResultData(data any, tool string) (map[string]any, error) { + object, ok := data.(map[string]any) + if !ok { + return nil, fmt.Errorf("%s 返回值必须是 JSON 对象", tool) + } + successValue, hasSuccess := object["success"] + resultValue, hasResult := object["result"] + if !hasSuccess && !hasResult { + return object, nil + } + if !hasSuccess || !hasResult { + return nil, fmt.Errorf("%s 返回的 Connector 信封必须同时包含 success 和 result", tool) + } + success, ok := successValue.(bool) + if !ok { + return nil, fmt.Errorf("%s 返回的 Connector 信封字段 success 必须是布尔值", tool) + } + if !success { + message, _ := object["message"].(string) + if strings.TrimSpace(message) == "" { + message = "Connector 返回 success=false" + } + return nil, fmt.Errorf("%s 调用失败: %s", tool, message) + } + result, ok := resultValue.(map[string]any) + if !ok { + return nil, fmt.Errorf("%s 返回值的 result 必须是 JSON 对象", tool) + } + return result, nil +} + +func recruitInvalidResponse(err error) output.CommandResult { + return output.Failure(&output.ErrorInfo{ + Type: "api", Subtype: "invalid_response", Message: err.Error(), + Hint: "保留原始响应并停止后续操作；不要依据不完整结果继续处理。", + }) } func recruitListResultData(data any) (any, *output.Meta, error) { - object, ok := data.(map[string]any) - if !ok { - return nil, nil, fmt.Errorf("list_jobs 返回值必须是 JSON 对象") + object, err := recruitBusinessResultData(data, recruitListJobsTool) + if err != nil { + return nil, nil, err } // The recruit Connector returns the ATS service envelope unchanged: // {success:true,result:{list:[...],hasMore:false,nextCursor:null}}. // Keep accepting the historical flattened shape as well, but normalize the // fixed Connector shape before enforcing the public CLI result contract. - if nested, exists := object["result"]; exists { - var nestedOK bool - object, nestedOK = nested.(map[string]any) - if !nestedOK { - return nil, nil, fmt.Errorf("list_jobs 返回值的 result 必须是 JSON 对象") - } - } hasMore, ok := object["hasMore"].(bool) if !ok { return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore") diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index e81d882e..a59b4f75 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -4,6 +4,7 @@ package helpers import ( + "bytes" "context" "encoding/json" stderrors "errors" @@ -134,7 +135,7 @@ func TestRecruitJobListCursorRoundTrip(t *testing.T) { func TestRecruitJobListResponseCursorRoundTrip(t *testing.T) { caller := withRecruitCaller(t) - caller.text = `{"result":{"list":[],"hasMore":true,"nextCursor":9223372036854775807}}` + caller.text = `{"success":true,"result":{"list":[],"hasMore":true,"nextCursor":9223372036854775807}}` data, err := CallMCPToolDataOnServer(context.Background(), recruitServerID, recruitListJobsTool, map[string]any{"size": 20}) if err != nil { @@ -388,7 +389,7 @@ func TestRecruitListResultData(t *testing.T) { t.Fatalf("wrapped meta = %#v", wrappedMeta) } - if _, _, err := recruitListResultData(map[string]any{"result": nil}); err == nil || + if _, _, err := recruitListResultData(map[string]any{"success": true, "result": nil}); err == nil || !strings.Contains(err.Error(), "result 必须是 JSON 对象") { t.Fatalf("nil result error = %v", err) } @@ -403,6 +404,140 @@ func TestRecruitResultCallPropagatesMCPError(t *testing.T) { } } +func TestRecruitResultCallUnwrapsConnectorEnvelopeForGetAndCreate(t *testing.T) { + for _, test := range []struct { + name string + tool string + text string + want map[string]any + }{ + { + name: "get detail", + tool: recruitGetJobTool, + text: `{"success":true,"result":{"jobId":"job-detail","name":"Java 工程师","status":1}}`, + want: map[string]any{"jobId": "job-detail", "name": "Java 工程师", "status": json.Number("1")}, + }, + { + name: "create job", + tool: recruitCreateJobTool, + text: `{"success":true,"result":{"jobId":"job-created"}}`, + want: map[string]any{"jobId": "job-created"}, + }, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = test.text + data, err := CallMCPToolDataOnServer(context.Background(), recruitServerID, test.tool, map[string]any{}) + if err != nil { + t.Fatal(err) + } + clean, err := recruitBusinessResultData(data, test.tool) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(clean, test.want) { + t.Fatalf("normalized data = %#v, want %#v", clean, test.want) + } + if _, hasSuccess := clean["success"]; hasSuccess { + t.Fatalf("normalized data retained Connector envelope: %#v", clean) + } + if _, hasResult := clean["result"]; hasResult { + t.Fatalf("normalized data retained nested result: %#v", clean) + } + }) + } +} + +func TestRecruitCommandsPublishUnwrappedConnectorResult(t *testing.T) { + for _, test := range []struct { + name string + leaf func() *cobra.Command + args func(*testing.T) []string + text string + wantID string + }{ + { + name: "get detail", + leaf: newRecruitJobGetCommand, + args: func(*testing.T) []string { return []string{"--job-id", "job-detail"} }, + text: `{"success":true,"result":{"jobId":"job-detail","name":"Java 工程师","status":1}}`, + wantID: "job-detail", + }, + { + name: "create job", + leaf: newRecruitJobCreateCommand, + args: func(t *testing.T) []string { + path, _ := writeRecruitJobFixture(t) + return []string{"--from", path, "--yes"} + }, + text: `{"success":true,"result":{"jobId":"job-created"}}`, + wantID: "job-created", + }, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = test.text + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) + root.PersistentFlags().String("format", "json", "") + root.PersistentFlags().String("fields", "", "") + root.PersistentFlags().String("jq", "", "") + root.PersistentFlags().Bool("dry-run", false, "") + root.PersistentFlags().Bool("yes", false, "") + root.PersistentPostRunE = func(cmd *cobra.Command, _ []string) error { + _, _, err := output.EmitStoredResult(cmd) + return err + } + leaf := test.leaf() + root.AddCommand(leaf) + var stdout bytes.Buffer + root.SetOut(&stdout) + root.SetArgs(append([]string{leaf.Name()}, test.args(t)...)) + if err := root.Execute(); err != nil { + t.Fatal(err) + } + var envelope struct { + Data map[string]any `json:"data"` + } + if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil { + t.Fatalf("decode output %q: %v", stdout.String(), err) + } + if envelope.Data["jobId"] != test.wantID { + t.Fatalf("data = %#v, want top-level jobId %q", envelope.Data, test.wantID) + } + if _, exists := envelope.Data["success"]; exists { + t.Fatalf("public data retained Connector success: %#v", envelope.Data) + } + if _, exists := envelope.Data["result"]; exists { + t.Fatalf("public data retained Connector result: %#v", envelope.Data) + } + }) + } +} + +func TestRecruitBusinessResultDataRejectsInvalidConnectorEnvelope(t *testing.T) { + for _, test := range []struct { + name string + data any + want string + }{ + {name: "not object", data: []any{}, want: "必须是 JSON 对象"}, + {name: "missing result", data: map[string]any{"success": true}, want: "同时包含 success 和 result"}, + {name: "missing success", data: map[string]any{"result": map[string]any{}}, want: "同时包含 success 和 result"}, + {name: "invalid success", data: map[string]any{"success": "true", "result": map[string]any{}}, want: "success 必须是布尔值"}, + {name: "business failure", data: map[string]any{"success": false, "message": "职位不存在", "result": map[string]any{}}, want: "职位不存在"}, + {name: "business failure without message", data: map[string]any{"success": false, "result": map[string]any{}}, want: "Connector 返回 success=false"}, + {name: "invalid result", data: map[string]any{"success": true, "result": nil}, want: "result 必须是 JSON 对象"}, + } { + t.Run(test.name, func(t *testing.T) { + if _, err := recruitBusinessResultData(test.data, recruitGetJobTool); err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("error = %v, want %q", err, test.want) + } + }) + } +} + func TestRecruitResultCallRejectsInconsistentPagination(t *testing.T) { caller := withRecruitCaller(t) caller.text = `{"jobs":[],"hasMore":true}` From ccbacf84b37d1a29e516716e01d0d40a872e18a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Fri, 14 Aug 2026 14:36:49 +0800 Subject: [PATCH 106/250] test(helpers): cover trailing MCP JSON responses --- .../helpers/framework2_changed_lines_coverage_test.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/internal/helpers/framework2_changed_lines_coverage_test.go b/internal/helpers/framework2_changed_lines_coverage_test.go index b03fdc32..b9488467 100644 --- a/internal/helpers/framework2_changed_lines_coverage_test.go +++ b/internal/helpers/framework2_changed_lines_coverage_test.go @@ -80,6 +80,16 @@ func TestCrossPlatformCoverageFramework2MCPDataEdges(t *testing.T) { if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil { t.Fatal("expected invalid JSON error") } + + InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{} {}`}}}}) + if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil || !strings.Contains(err.Error(), "存在多个 JSON 值") { + t.Fatalf("multiple JSON values error = %v", err) + } + + InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{} {`}}}}) + if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil || !strings.Contains(err.Error(), "解析 get_thing 返回失败") { + t.Fatalf("trailing invalid JSON error = %v", err) + } } func TestCrossPlatformCoverageFramework2LegacyTextAdapter(t *testing.T) { From 5abef59c7c0e9b6f3ec0771fe52b4ca0db4ef78b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=9C=E7=8E=84?= Date: Fri, 14 Aug 2026 14:46:21 +0800 Subject: [PATCH 107/250] feat(aitable): add server-side record statistics --- .changes/aitable-record-stats.md | 9 + internal/helpers/aitable.go | 305 +++++++++++++++++- internal/helpers/aitable_schema.go | 101 ++++++ internal/helpers/aitable_stats_test.go | 181 +++++++++++ skills/mono/references/products/aitable.md | 6 +- .../aitable/aitable-best-practices.md | 6 +- .../aitable/aitable-data-analysis-sop.md | 29 +- .../products/aitable/aitable-formula-guide.md | 2 +- .../products/aitable/aitable-record-stats.md | 59 ++++ .../dingtalk-aitable/references/aitable.md | 6 +- .../aitable/aitable-best-practices.md | 6 +- .../aitable/aitable-data-analysis-sop.md | 29 +- .../aitable/aitable-formula-guide.md | 2 +- .../aitable/aitable-record-stats.md | 59 ++++ 14 files changed, 762 insertions(+), 38 deletions(-) create mode 100644 .changes/aitable-record-stats.md create mode 100644 internal/helpers/aitable_stats_test.go create mode 100644 skills/mono/references/products/aitable/aitable-record-stats.md create mode 100644 skills/multi/dingtalk-aitable/references/aitable/aitable-record-stats.md diff --git a/.changes/aitable-record-stats.md b/.changes/aitable-record-stats.md new file mode 100644 index 00000000..44164d3f --- /dev/null +++ b/.changes/aitable-record-stats.md @@ -0,0 +1,9 @@ +--- +category: Added +--- + +- **AI Table server-side statistics** — adds `dws aitable record stats` for + ungrouped record-set metrics through `query_records_stats`, plus `dws aitable + record group-stats` for grouped, distinct, and advanced aggregation through + `query_stats`; both commands validate their JSON aggregation contracts before + dispatch. diff --git a/internal/helpers/aitable.go b/internal/helpers/aitable.go index f79cca63..f52d40fd 100644 --- a/internal/helpers/aitable.go +++ b/internal/helpers/aitable.go @@ -520,6 +520,99 @@ func normalizeFilters(parsed any) any { } } +type aitableStatsItem struct { + FieldID string `json:"fieldId"` + StatsType string `json:"statsType"` +} + +func aitableStatsValidationf(format string, args ...any) error { + return apperrors.NewValidation(fmt.Sprintf(format, args...)) +} + +func parseAitableStatsItems(raw string, uppercase, uniqueFields bool, maxItems int) ([]map[string]any, error) { + var items []aitableStatsItem + if err := json.Unmarshal([]byte(raw), &items); err != nil { + return nil, aitableStatsValidationf("--stats 必须是 JSON 数组: %v", err) + } + if len(items) == 0 { + return nil, aitableStatsValidationf("--stats 至少需要一个统计项") + } + if maxItems > 0 && len(items) > maxItems { + return nil, aitableStatsValidationf("--stats 单次最多支持 %d 个统计项，got %d", maxItems, len(items)) + } + + seenFields := make(map[string]struct{}, len(items)) + out := make([]map[string]any, 0, len(items)) + for index, item := range items { + item.FieldID = strings.TrimSpace(item.FieldID) + item.StatsType = strings.TrimSpace(item.StatsType) + if item.FieldID == "" || item.StatsType == "" { + return nil, aitableStatsValidationf("--stats[%d] 的 fieldId 和 statsType 均不能为空", index) + } + if uniqueFields { + if _, exists := seenFields[item.FieldID]; exists { + return nil, aitableStatsValidationf("--stats 中 fieldId %q 重复；query_records_stats 要求同一字段的多个统计类型拆成多次调用", item.FieldID) + } + seenFields[item.FieldID] = struct{}{} + } + if uppercase && item.StatsType != strings.ToUpper(item.StatsType) { + return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用大写枚举值，got %q", index, item.StatsType) + } + if !uppercase && item.StatsType != strings.ToLower(item.StatsType) { + return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用小写值，got %q", index, item.StatsType) + } + out = append(out, map[string]any{"fieldId": item.FieldID, "statsType": item.StatsType}) + } + return out, nil +} + +func parseAitableObjectFlag(name, raw string) (map[string]any, error) { + decoder := json.NewDecoder(strings.NewReader(raw)) + decoder.UseNumber() + var value map[string]any + if err := decoder.Decode(&value); err != nil { + return nil, aitableStatsValidationf("--%s 必须是 JSON 对象: %v", name, err) + } + if value == nil { + return nil, aitableStatsValidationf("--%s 必须是 JSON 对象，不能是 null", name) + } + var trailing any + if err := decoder.Decode(&trailing); err != io.EOF { + if err == nil { + return nil, aitableStatsValidationf("--%s 只能包含一个 JSON 对象", name) + } + return nil, aitableStatsValidationf("--%s 包含无效的尾随内容: %v", name, err) + } + return value, nil +} + +func validateAitableStatsFilterRoot(value map[string]any) error { + operator, ok := value["operator"].(string) + if !ok || (strings.ToLower(operator) != "and" && strings.ToLower(operator) != "or") { + return aitableStatsValidationf("--filters 根节点 operator 必须是 and 或 or") + } + if _, ok := value["operands"].([]any); !ok { + return aitableStatsValidationf("--filters 根节点 operands 必须是 JSON 数组") + } + return nil +} + +func validateAitableArrayDSL(name, raw string) error { + var value []any + if err := json.Unmarshal([]byte(raw), &value); err != nil { + return aitableStatsValidationf("--%s 必须是 JSON 数组字符串: %v", name, err) + } + if len(value) == 0 { + return aitableStatsValidationf("--%s 至少需要一个条目", name) + } + for index, item := range value { + if _, ok := item.(map[string]any); !ok { + return aitableStatsValidationf("--%s[%d] 必须是 JSON 对象，got %T", name, index, item) + } + } + return nil +} + // normalizeViewConfigFilter 将 view config 中的 filter 字段规范化为服务端要求的数组格式。 // 服务端 POJO 要求 config.filter 为 []FilterRule（JSON array）。 // 常见错误格式： @@ -1098,7 +1191,7 @@ func newAitableCommand() *cobra.Command { dws aitable base [list|search|get|get-primary-doc-id|create|update|delete|copy] Base 管理 dws aitable table [get|create|update|delete] 数据表管理 dws aitable field [get|create|update|delete|search-options] 字段管理 - dws aitable record [query|create|update|delete] 记录管理 + dws aitable record [query|stats|group-stats|create|update|delete] 记录管理 dws aitable view [get|create|update|delete] 视图管理 dws aitable form [list|delete|update] 表单管理 dws aitable form field [list|update|hide] 表单字段管理 @@ -2245,6 +2338,197 @@ newFieldName、config、aiConfig 至少传入一项。 }, }) + recordStatsCmd := &cobra.Command{ + Use: "stats", + Short: "整表或过滤后的字段聚合统计", + Long: `对单张数据表执行不分组的服务端聚合，底层调用 query_records_stats。 +适用于记录计数、求和、平均值、最大值、最小值、中位数、去重数、完整率等标量统计。 + +--stats 是 JSON 数组，单次最多 20 项；每项必须包含 fieldId 和大写 statsType。 +同一个 fieldId 不能在一次请求中重复，如需对同一字段计算多个指标，请拆成多次调用。 +常用 statsType：COUNT、COUNT_COLUMN、SUM、AVG、MAX、MIN、MEDIAN、STANDARD_DEVIATION、RANGE、 +DISTINCT、DISTINCT_RATIO、EXISTS、UN_EXISTS、EXIST_RATIO、UN_EXIST_RATIO、CHECKED、UN_CHECKED、 +CHECKED_RATIO、UN_CHECKED_RATIO、LATEST_DATE、EARLIEST_DATE、DATE_RANGE、DATE_RANGE_MONTH。 + +需要统计全部匹配记录时不要传 --limit；limit 会改变参与统计的记录范围。 +lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议使用 field get 返回的选项 ID。`, + Example: ` dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldAmount","statsType":"SUM"}]' + dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}' --stats '[{"fieldId":"fldTitle","statsType":"COUNT"}]'`, + RunE: func(cmd *cobra.Command, args []string) error { + if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil { + return err + } + baseID, err := mustFlagOrFallback(cmd, "base-id", "base") + if err != nil { + return err + } + stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), true, true, 20) + if err != nil { + return err + } + toolArgs := map[string]any{ + "baseId": baseID, + "tableId": mustGetFlag(cmd, "table-id"), + "stats": stats, + } + if raw, _ := cmd.Flags().GetString("filters"); raw != "" { + filters, err := parseAitableObjectFlag("filters", raw) + if err != nil { + return err + } + if err := validateAitableStatsFilterRoot(filters); err != nil { + return err + } + toolArgs["filters"] = normalizeFilters(filters) + } + if raw, _ := cmd.Flags().GetString("sort"); raw != "" { + if err := validateAitableArrayDSL("sort", raw); err != nil { + return err + } + toolArgs["sort"] = raw + } + if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") { + if value <= 0 { + return aitableStatsValidationf("--limit 必须大于 0；统计全部匹配记录时请省略该参数") + } + toolArgs["limit"] = value + } + if value, _ := cmd.Flags().GetString("keyword"); value != "" { + toolArgs["keyword"] = value + } + if value, _ := cmd.Flags().GetString("search-field-ids"); value != "" { + toolArgs["searchFieldIds"] = parseCSVValues(value) + } + if value, _ := cmd.Flags().GetString("data-version"); value != "" { + toolArgs["dataVersion"] = value + } + return callAitableTool("query_records_stats", toolArgs) + }, + } + DeclareLeafMetadata(recordStatsCmd, LeafSpec{ + Safety: aitableSafetyRead(), + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "aitable", + Name: "query_records_stats", + CanonicalPath: "aitable.query_records_stats", + CLIPath: "aitable record stats", + PrimaryCLIPath: "aitable record stats", + }, + Description: "对整表或过滤后的记录执行不分组字段聚合。", + Interface: aitableMCPInterface("query_records_stats"), + Selection: contract.SelectionSpec{ + AgentSummary: "对整表或过滤后的记录执行不分组字段聚合。", + UseWhen: []string{"需要记录总数、SUM/AVG/MAX/MIN、中位数、去重数、完整率等标量统计时，优先服务端聚合"}, + AvoidWhen: []string{"需要按字段分组或使用 query_stats 高级聚合时用 record group-stats；需要行级明细时用 record query"}, + Examples: []string{`dws aitable record stats --base-id --table-id --stats '[{"fieldId":"","statsType":"COUNT"}]'`}, + }, + Parameters: []contract.ParamDecl{ + {Name: "base-id", Property: "baseId", Required: boolPtr(true)}, + {Name: "table-id", Property: "tableId", Required: boolPtr(true)}, + {Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"}, + {Name: "filters", Property: "filters", InterfaceType: "object"}, + {Name: "search-field-ids", Property: "searchFieldIds", InterfaceType: "array"}, + {Name: "data-version", Property: "dataVersion"}, + }, + Result: aitableRecordsStatsResultSpec(), + }, + }) + + recordGroupStatsCmd := &cobra.Command{ + Use: "group-stats", + Short: "分组、去重及高级聚合统计", + Long: `对单张数据表执行分组或高级服务端聚合，底层调用 query_stats，最多返回 1000 个分组。 +适用于按一个或多个字段分组、条件唯一实体计数，以及 distinct、distinct_ratio 等高级统计。 + +--stats 是 JSON 数组，每项包含 fieldId 和小写 statsType。基础类型为 sum、avg、count、max、min； +部分后端也支持 median、distinct、distinct_ratio 等高级类型，不支持时服务端会返回明确错误。 +--group 是 JSON 数组编码后的字符串，不分组的 DISTINCT 标量统计可以省略。 +不要依赖服务端 limit 选择 Top N；应在不超过 1000 个分组时获取完整结果后再排序。`, + Example: ` dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --group '[{"fieldId":"fldCategory","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' --stats '[{"fieldId":"fldAmount","statsType":"sum"}]' + dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldStore","statsType":"distinct"}]'`, + RunE: func(cmd *cobra.Command, args []string) error { + if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil { + return err + } + baseID, err := mustFlagOrFallback(cmd, "base-id", "base") + if err != nil { + return err + } + stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), false, false, 0) + if err != nil { + return err + } + toolArgs := map[string]any{ + "baseId": baseID, + "tableId": mustGetFlag(cmd, "table-id"), + "stats": stats, + } + if raw, _ := cmd.Flags().GetString("filters"); raw != "" { + filters, err := parseAitableObjectFlag("filters", raw) + if err != nil { + return err + } + if err := validateAitableStatsFilterRoot(filters); err != nil { + return err + } + toolArgs["filters"] = normalizeFilters(filters) + } + if raw, _ := cmd.Flags().GetString("group"); raw != "" { + if err := validateAitableArrayDSL("group", raw); err != nil { + return err + } + toolArgs["group"] = raw + } + if raw, _ := cmd.Flags().GetString("sort"); raw != "" { + if err := validateAitableArrayDSL("sort", raw); err != nil { + return err + } + toolArgs["sortDsl"] = raw + } + if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") { + if value < 1 || value > 1000 { + return aitableStatsValidationf("--limit 必须在 [1, 1000] 范围内，got %d", value) + } + toolArgs["limit"] = value + } + if value, _ := cmd.Flags().GetString("data-version"); value != "" { + toolArgs["dataVersion"] = value + } + return callAitableTool("query_stats", toolArgs) + }, + } + DeclareLeafMetadata(recordGroupStatsCmd, LeafSpec{ + Safety: aitableSafetyRead(), + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "aitable", + Name: "query_stats", + CanonicalPath: "aitable.query_stats", + CLIPath: "aitable record group-stats", + PrimaryCLIPath: "aitable record group-stats", + }, + Description: "按字段分组，或执行去重等高级聚合统计。", + Interface: aitableMCPInterface("query_stats"), + Selection: contract.SelectionSpec{ + AgentSummary: "按字段分组，或执行去重等高级聚合统计。", + UseWhen: []string{"需要各分类/实体的分组统计，或对满足条件的门店、客户、商品等执行 DISTINCT 唯一计数时"}, + AvoidWhen: []string{"普通不分组 COUNT/SUM/AVG/MAX/MIN 优先用 record stats；原始记录和 Top N 明细用 record query"}, + Examples: []string{`dws aitable record group-stats --base-id --table-id --stats '[{"fieldId":"","statsType":"distinct"}]'`}, + }, + Parameters: []contract.ParamDecl{ + {Name: "base-id", Property: "baseId", Required: boolPtr(true)}, + {Name: "table-id", Property: "tableId", Required: boolPtr(true)}, + {Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"}, + {Name: "filters", Property: "filters", InterfaceType: "object"}, + {Name: "group", Property: "group"}, + {Name: "sort", Property: "sortDsl"}, + {Name: "data-version", Property: "dataVersion"}, + }, + Result: aitableGroupedStatsResultSpec(), + }, + }) + recordCreateCmd := &cobra.Command{ Use: "create", Short: "新增记录", @@ -7230,6 +7514,23 @@ parentSectionId 为空串表示该节点在 Base 根目录下。 recordQueryCmd.Flags().Int("page-limit", 50, "自动翻页最大页数（仅 --all 时生效）。默认 50 页（约 5000 条）；设为 0 表示显式不限页数；超限时错误详情保留已取记录和续传 cursor") recordQueryCmd.Flags().String("view-id", "", "视图 ID（record query 不支持按视图过滤，此参数会被忽略并给出提示）") _ = recordQueryCmd.Flags().MarkHidden("view-id") + recordStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)") + recordStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)") + recordStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"SUM"}]；statsType 必须大写，最多 20 项且 fieldId 不得重复`) + recordStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字") + recordStatsCmd.Flags().String("sort", "", `参与统计记录的排序 DSL（JSON 数组字符串），例如 [{"fieldId":"fldDate","direction":"ASC"}]`) + recordStatsCmd.Flags().Int("limit", 0, "参与统计的最大记录数；省略表示统计全部匹配记录") + recordStatsCmd.Flags().String("keyword", "", "全文关键词，仅匹配的记录参与统计") + recordStatsCmd.Flags().String("search-field-ids", "", "关键词搜索字段 ID 列表，逗号分隔；仅 --keyword 非空时生效") + recordStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本") + recordGroupStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)") + recordGroupStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)") + recordGroupStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"sum"}]；statsType 必须小写`) + recordGroupStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字") + recordGroupStatsCmd.Flags().String("group", "", `分组字段 DSL（JSON 数组字符串）；不分组的 distinct 统计可省略`) + recordGroupStatsCmd.Flags().String("sort", "", "统计结果排序 DSL（JSON 数组字符串），映射到 MCP sortDsl") + recordGroupStatsCmd.Flags().Int("limit", 0, "返回的分组结果数，范围 1-1000；省略表示不额外限制") + recordGroupStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本") recordCreateCmd.Flags().String("base-id", "", "Base ID，可通过 base list 或 base search 获取 (必填)") recordCreateCmd.Flags().String("table-id", "", "Table ID，可通过 base get 获取 (必填)") recordCreateCmd.Flags().String("records", "", "待创建的记录列表 JSON 数组，单次最多 100 条 (必填)") @@ -7294,7 +7595,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。 recordPrimaryDocCreateCmd.Flags().String("record-id", "", "目标 Record ID (必填)") recordCmd.AddCommand( - recordQueryCmd, recordCreateCmd, + recordQueryCmd, recordStatsCmd, recordGroupStatsCmd, recordCreateCmd, recordUpdateCmd, recordDeleteCmd, recordBatchUpdateCmd, recordHistoryListCmd, diff --git a/internal/helpers/aitable_schema.go b/internal/helpers/aitable_schema.go index 857095f9..2257bfbc 100644 --- a/internal/helpers/aitable_schema.go +++ b/internal/helpers/aitable_schema.go @@ -14,6 +14,8 @@ package helpers import ( + "encoding/json" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) @@ -72,3 +74,102 @@ func aitableCompositeInterface(reason string) *contract.InterfaceSpec { Reason: reason, } } + +func aitableRecordsStatsResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"不分组的字段聚合结果", + "properties":{ + "results":{ + "type":"array", + "description":"按数据版本返回的聚合结果批次", + "items":{ + "type":"object", + "properties":{ + "dataVersion":{"description":"参与统计的数据版本"}, + "deltaVersion":{"description":"聚合结果的增量版本"}, + "results":{ + "type":"array", + "description":"请求中各统计项的结果", + "items":{ + "type":"object", + "properties":{ + "fieldId":{"type":"string","description":"被统计的字段 ID"}, + "statsType":{"type":"string","description":"实际执行的统计类型"}, + "value":{"description":"统计值；具体 JSON 类型取决于统计类型和字段类型"} + }, + "required":["fieldId","statsType","value"], + "additionalProperties":true + } + } + }, + "required":["results"], + "additionalProperties":true + } + } + }, + "required":["results"], + "additionalProperties":true +}`), + } +} + +func aitableGroupedStatsResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"分组或高级字段聚合结果", + "properties":{ + "dataVersion":{"description":"参与统计的数据版本"}, + "results":{ + "type":"array", + "description":"每个分组一条结果；未分组时通常只有一条", + "items":{ + "type":"object", + "properties":{ + "groupKeys":{ + "type":"array", + "description":"当前结果的分组键", + "items":{ + "type":"object", + "properties":{ + "fieldId":{"type":"string","description":"分组字段 ID"}, + "value":{"description":"分组值；编码取决于字段类型"}, + "recordCount":{"type":"integer","description":"该分组包含的记录数"} + }, + "additionalProperties":true + } + }, + "fieldStatsMap":{ + "type":"object", + "description":"按字段 ID 索引的聚合值", + "additionalProperties":{ + "type":"object", + "properties":{ + "action":{"type":"string","description":"实际执行的统计动作"}, + "value":{"description":"统计值；具体 JSON 类型取决于统计动作和字段类型"} + }, + "required":["action","value"], + "additionalProperties":true + } + } + }, + "required":["fieldStatsMap"], + "additionalProperties":true + } + } + }, + "required":["results"], + "additionalProperties":true +}`), + } +} diff --git a/internal/helpers/aitable_stats_test.go b/internal/helpers/aitable_stats_test.go new file mode 100644 index 00000000..3ab19337 --- /dev/null +++ b/internal/helpers/aitable_stats_test.go @@ -0,0 +1,181 @@ +// Copyright 2026 Alibaba Group +// SPDX-License-Identifier: Apache-2.0 + +package helpers + +import ( + "encoding/json" + "errors" + "reflect" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" +) + +func runAitableStatsCLI(t *testing.T, args ...string) (*aitableTestCaller, error) { + t.Helper() + caller := &aitableTestCaller{} + installAitableDeps(t, caller) + command := newAitableCommand() + command.SilenceErrors = true + command.SilenceUsage = true + command.SetArgs(args) + return caller, command.Execute() +} + +func TestCrossPlatformCoverageAitableRecordsStatsForwardsValidatedContract(t *testing.T) { + caller, err := runAitableStatsCLI(t, + "record", "stats", + "--base-id", "base-stats", + "--table-id", "table-stats", + "--stats", `[{"fieldId":"fldCount","statsType":"COUNT"},{"fieldId":"fldAmount","statsType":"SUM"}]`, + "--filters", `{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}`, + "--sort", `[{"fieldId":"fldAmount","direction":"DESC"}]`, + "--limit", "500", + "--keyword", "华东", + "--search-field-ids", "fldName,fldRegion", + "--data-version", "42", + ) + if err != nil { + t.Fatalf("record stats returned error: %v", err) + } + if len(caller.calls) != 1 { + t.Fatalf("tool calls = %d, want 1", len(caller.calls)) + } + call := caller.calls[0] + if call.server != "aitable" || call.tool != "query_records_stats" { + t.Fatalf("tool = %s/%s, want aitable/query_records_stats", call.server, call.tool) + } + wantStats := []map[string]any{ + {"fieldId": "fldCount", "statsType": "COUNT"}, + {"fieldId": "fldAmount", "statsType": "SUM"}, + } + if !reflect.DeepEqual(call.args["stats"], wantStats) { + t.Fatalf("stats = %#v, want %#v", call.args["stats"], wantStats) + } + filters := call.args["filters"].(map[string]any) + condition := filters["operands"].([]any)[0].(map[string]any) + if got := condition["operands"].([]any)[1]; got != json.Number("0") { + t.Fatalf("numeric filter value = %#v (%T), want json.Number(0)", got, got) + } + if call.args["sort"] != `[{"fieldId":"fldAmount","direction":"DESC"}]` || + call.args["limit"] != 500 || call.args["keyword"] != "华东" || call.args["dataVersion"] != "42" { + t.Fatalf("forwarded args = %#v", call.args) + } + if !reflect.DeepEqual(call.args["searchFieldIds"], []string{"fldName", "fldRegion"}) { + t.Fatalf("searchFieldIds = %#v", call.args["searchFieldIds"]) + } +} + +func TestCrossPlatformCoverageAitableGroupStatsForwardsStringDSL(t *testing.T) { + group := `[{"fieldId":"fldRegion","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]` + sortDSL := `[{"fieldId":"fldAmount","direction":"DESC"}]` + caller, err := runAitableStatsCLI(t, + "record", "group-stats", + "--base-id", "base-stats", + "--table-id", "table-stats", + "--stats", `[{"fieldId":"fldStore","statsType":"distinct"},{"fieldId":"fldAmount","statsType":"avg"}]`, + "--filters", `{"operator":"OR","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`, + "--group", group, + "--sort", sortDSL, + "--limit", "1000", + "--data-version", "43", + ) + if err != nil { + t.Fatalf("record group-stats returned error: %v", err) + } + if len(caller.calls) != 1 { + t.Fatalf("tool calls = %d, want 1", len(caller.calls)) + } + call := caller.calls[0] + if call.server != "aitable" || call.tool != "query_stats" { + t.Fatalf("tool = %s/%s, want aitable/query_stats", call.server, call.tool) + } + if call.args["group"] != group || call.args["sortDsl"] != sortDSL || call.args["limit"] != 1000 || call.args["dataVersion"] != "43" { + t.Fatalf("forwarded args = %#v", call.args) + } + stats := call.args["stats"].([]map[string]any) + if len(stats) != 2 || stats[0]["statsType"] != "distinct" || stats[1]["statsType"] != "avg" { + t.Fatalf("stats = %#v", stats) + } +} + +func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t *testing.T) { + tests := []struct { + name string + args []string + wantErr string + }{ + { + name: "records stats require uppercase", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`}, + wantErr: "大写", + }, + { + name: "records stats reject duplicate field", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"},{"fieldId":"f","statsType":"SUM"}]`}, + wantErr: "重复", + }, + { + name: "group stats require lowercase", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`}, + wantErr: "小写", + }, + { + name: "group must be array DSL", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--group", `{}`}, + wantErr: "JSON 数组", + }, + { + name: "group limit capped", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--limit", "1001"}, + wantErr: "[1, 1000]", + }, + { + name: "filters require logical root", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"eq","operands":[]}`}, + wantErr: "and 或 or", + }, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller, err := runAitableStatsCLI(t, test.args...) + if err == nil || !strings.Contains(err.Error(), test.wantErr) { + t.Fatalf("error = %v, want containing %q", err, test.wantErr) + } + var structured *apperrors.Error + if !errors.As(err, &structured) || structured.Category != apperrors.CategoryValidation { + t.Fatalf("error = %#v, want structured validation error", err) + } + if len(caller.calls) != 0 { + t.Fatalf("tool calls = %d, want 0", len(caller.calls)) + } + }) + } +} + +func TestCrossPlatformCoverageAitableStatsPublishInterfaceAndResultContracts(t *testing.T) { + root := newAitableCommand() + tests := []struct { + path string + rpc string + }{ + {path: "aitable record stats", rpc: "query_records_stats"}, + {path: "aitable record group-stats", rpc: "query_stats"}, + } + for _, test := range tests { + leaf := findCLIPath(root, test.path) + if leaf == nil { + t.Fatalf("missing leaf %q", test.path) + } + final, ok := contractfinal.RuntimeContractFinal(leaf) + if !ok || final.Interface == nil || final.Interface.Ref == nil || final.Interface.Ref.RPCName != test.rpc { + t.Fatalf("%s interface = %#v", test.path, final.Interface) + } + if final.Result == nil || len(final.Result.Outcomes) == 0 || len(final.Result.DataSchema) == 0 { + t.Fatalf("%s result = %#v", test.path, final.Result) + } + } +} diff --git a/skills/mono/references/products/aitable.md b/skills/mono/references/products/aitable.md index d6792aee..d8c03e00 100644 --- a/skills/mono/references/products/aitable.md +++ b/skills/mono/references/products/aitable.md @@ -55,6 +55,8 @@ | `record query` | 查询/搜索记录 | [aitable-record-query.md](./aitable/aitable-record-query.md) | 先 `table get` 拿 fieldId；`--all` 自动翻页；filters 结构见 reference；`--query`（隐藏别名 `--keyword`）全文搜索 | | `record list` | 获取记录（`record query` 的别名） | [aitable-record-query.md](./aitable/aitable-record-query.md) | 与 `record query` 等价 | | `record get` | 按 ID 取记录（`record query --record-ids` 的窄别名） | [aitable-record-query.md](./aitable/aitable-record-query.md) | 已知 recordId 时首选；必填 `--record-ids`（单次最多 100 条）；未暴露 filters/sort/query/cursor/limit | +| `record stats` | 不分组的服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 大写；最多 20 项，同字段不可重复；全量统计省略 limit | +| `record group-stats` | 分组、去重和高级服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 小写；group 为 JSON 数组字符串；最多 1000 个分组 | | `record query-empty` | 查询完全没填用户字段的空行 | — | `--base-id` `--table-id`；`--limit` 扫描预算 [1,100]，`--cursor` 翻页 | | `record create` | 新增记录 | [aitable-record-create.md](./aitable/aitable-record-create.md) | cells key 必须是 fieldId 不是字段名；单次最多 100 条 | | `record update` | 更新记录 | [aitable-record-update.md](./aitable/aitable-record-update.md) | 需先 query 拿 recordId；只传需改字段；**没有** `--record-id` `--cells` flag | @@ -327,6 +329,8 @@ dws aitable export data --base-id --task-id --timeout-ms 300 用户说"记录/行/数据/row": - 查看/搜索 → `record query`（读 [aitable-record-query.md](./aitable/aitable-record-query.md)） +- 总数/求和/平均值/中位数/完整率等标量统计 → `record stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） +- 分组统计/唯一实体计数/去重率 → `record group-stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） - 已知 recordId 反查字段值 → `record get`（按 ID 取专用，等价 `record query --record-ids`） - 添加/写入 → `record create`（读 [aitable-record-create.md](./aitable/aitable-record-create.md)） - 修改/更新 → `record update`（读 [aitable-record-update.md](./aitable/aitable-record-update.md)） @@ -334,7 +338,7 @@ dws aitable export data --base-id --task-id --timeout-ms 300 用户说"筛选/过滤/filter" → 读 [aitable-filter-sort.md](./aitable/aitable-filter-sort.md) -用户说"统计/分析/聚合/TOP N/全量" → 读 [aitable-data-analysis-sop.md](./aitable/aitable-data-analysis-sop.md) +用户说"统计/分析/聚合/TOP N/全量" → 先读 [aitable-data-analysis-sop.md](./aitable/aitable-data-analysis-sop.md)，聚合参数见 [aitable-record-stats.md](./aitable/aitable-record-stats.md) 用户说"公式/formula/计算字段/派生指标" → 读 [aitable-formula-guide.md](./aitable/aitable-formula-guide.md) diff --git a/skills/mono/references/products/aitable/aitable-best-practices.md b/skills/mono/references/products/aitable/aitable-best-practices.md index a851af83..086d2d80 100644 --- a/skills/mono/references/products/aitable/aitable-best-practices.md +++ b/skills/mono/references/products/aitable/aitable-best-practices.md @@ -12,7 +12,7 @@ ## 2. 查询执行契约 -1. **不要拉全量后在 context 里手动统计** — 优先用 `--filters` 在服务端过滤 +1. **不要拉全量后在 context 里手动统计** — 标量聚合用 `record stats`，分组/去重用 `record group-stats` 2. **has_more=true 时不能做全局结论** — 数据可能不完整 3. **优先用 `--filters` 在服务端过滤** — 不要拉全量后在本地 jq/grep 4. **字段名必须来自 `table get` 真实返回** — 不要猜测 fieldId @@ -23,7 +23,9 @@ | 用户诉求 | 优先方案 | 不要误走 | |---------|----------|----------| | 查看几条数据 | `record query` | 不要用 `--all` | -| 全量拉取/统计 | `record query --all` | 不要手动循环 cursor | +| 全量拉取明细 | `record query --all` | 不要手动循环 cursor | +| 标量统计 | `record stats` | 不要先拉全量再本地计算 | +| 分组/去重统计 | `record group-stats` | 不要先拉全量再本地 groupby | | 全量导出为文件 | `export data` | 不要 `--all` 拉全量再写文件 | | 批量写入 | `record create`（分批 100 条） | 不要一次传超过 100 条 | | 附件上传 | `attachment upload` + `record update` | 不要在 cells 里伪造附件值 | diff --git a/skills/mono/references/products/aitable/aitable-data-analysis-sop.md b/skills/mono/references/products/aitable/aitable-data-analysis-sop.md index 6331944e..ab67ce83 100644 --- a/skills/mono/references/products/aitable/aitable-data-analysis-sop.md +++ b/skills/mono/references/products/aitable/aitable-data-analysis-sop.md @@ -17,16 +17,16 @@ │ → record query --sort '[{"fieldId":"xxx","direction":"desc"}]' --limit 5 │ ├─ 全量统计（如"一共多少条"、"所有记录的总销售额"） -│ → record query --all --field-ids <目标字段> -│ → 本地计算 count / sum / avg +│ → record stats --stats '[{"fieldId":"...","statsType":"COUNT|SUM|AVG|..."}]' │ ├─ 分组统计（如"每个状态各有多少条"） -│ → record query --all --field-ids <分组字段>,<度量字段> -│ → 本地按分组字段 groupby 再聚合 +│ → record group-stats --group '[...]' --stats '[{"fieldId":"...","statsType":"count"}]' +│ +├─ 条件唯一实体数（如"有索赔单的门店共有多少家"） +│ → record group-stats --filters '{...}' --stats '[{"fieldId":"<实体字段>","statsType":"distinct"}]' │ └─ 判断全局结论（如"是否所有记录都满足条件"） - → record query --all（或用 --filters 反向筛选不满足的） - → 基于全量结果判断 + → record stats 对反向过滤结果 COUNT；只有需要行级证据时再 record query ``` ## 2. 核心规则 @@ -50,15 +50,15 @@ | 按日期降序取最新5条 | `--sort '[...]' --limit 5` | `--all` 拉全量再本地 sort + slice | | 模糊搜索标题含"Q1" | `--filters` 用 `contain` 操作符 | 全量拉取再本地 grep | -### 2.3 服务端无法完成时，才用 --all + 本地计算 +### 2.3 聚合必须优先在服务端完成 -以下场景服务端 filters/sort 无法满足，需要 `--all` 后本地处理： +以下场景均有服务端聚合入口，不得先用 `record query --all` 下载全表计算： -- SUM / AVG / COUNT / MAX / MIN 聚合 -- 分组统计（GROUP BY） -- 多字段联合计算（如"销售额 = 单价 × 数量"） -- 去重计数（COUNT DISTINCT） -- 百分比/占比计算 +- `record stats`：不分组的 COUNT / SUM / AVG / MAX / MIN / MEDIAN / DISTINCT / 完整率等 +- `record group-stats`：分组统计，以及不带 group 的条件 DISTINCT 唯一计数 +- 任意条件比率：分别聚合分子与分母，再对齐范围和 `dataVersion` 计算 + +只有用户要求记录明细、少量样本校验、精确分位数输入，或聚合接口明确返回不支持/错误时，才允许使用 `record query`。需要先逐行运算再聚合的指标（例如两个日期相减）必须使用表内已有且可聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能下载全表本地二次计算。 ### 2.4 --all 使用注意 @@ -122,7 +122,8 @@ dws aitable record query \ | 用户诉求 | 优先方案 | 不要误走 | |---------|---------|---------| -| 一次性统计/临时分析 | `record query --all` + 本地聚合 | 不要创建 formula 字段 | +| 一次性标量统计 | `record stats` | 不要 `record query --all` 后本地聚合 | +| 分组/去重统计 | `record group-stats` | 不要下载全表 groupby / 去重 | | 长期展示派生指标 | 创建 formula 字段（见 [formula-guide](./aitable-formula-guide.md)） | 不要每次手算再手动写入 | | 按条件筛选记录 | `record query --filters` | 不要 `--all` 拉全量再本地 filter | | 取最新/最大/前N | `--sort + --limit` | 不要 `--all` 再本地排序取前N | diff --git a/skills/mono/references/products/aitable/aitable-formula-guide.md b/skills/mono/references/products/aitable/aitable-formula-guide.md index 3b3fd853..cb3bca87 100644 --- a/skills/mono/references/products/aitable/aitable-formula-guide.md +++ b/skills/mono/references/products/aitable/aitable-formula-guide.md @@ -9,7 +9,7 @@ | 长期展示在表中的派生值（如"总价=单价×数量"） | ✅ | | | 条件标记（如"超期=IF(截止日期 \ + --table-id \ + --stats '[{"fieldId":"","statsType":"COUNT"}]' \ + --format json +``` + +- `statsType` 必须大写。 +- `--stats` 单次最多 20 项，同一 `fieldId` 不得重复；同字段多个指标拆成多次调用。 +- 支持基础类型 `COUNT`、`COUNT_COLUMN`、`SUM`、`AVG`、`MAX`、`MIN`，以及运行时支持的 `MEDIAN`、`STANDARD_DEVIATION`、`RANGE`、`DISTINCT`、`DISTINCT_RATIO`、完整率、勾选率和日期统计类型。 +- 统计全部匹配记录时省略 `--limit`；传入 limit 会改变统计范围。 +- 可选参数：`--filters`、`--sort`、`--keyword`、`--search-field-ids`、`--data-version`。 + +## 分组或去重统计 + +```bash +dws aitable record group-stats \ + --base-id \ + --table-id \ + --group '[{"fieldId":"","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' \ + --stats '[{"fieldId":"","statsType":"avg"}]' \ + --limit 1000 \ + --format json +``` + +- `statsType` 必须小写；基础类型为 `sum`、`avg`、`count`、`max`、`min`，后端还可能支持 `median`、`distinct`、`distinct_ratio` 等高级类型。 +- `--group` 和 `--sort` 都是 JSON 数组编码后的字符串，CLI 会原样映射到 MCP 的 `group` / `sortDsl`。 +- 分组结果最多 1000 行。不要依赖服务端 limit 选择 Top N；应在基数不超过 1000 时取完整分组结果后排序。 +- 条件唯一实体计数不传 `--group`，对实体字段使用 `distinct`。 + +## 过滤条件 + +```bash +--filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}' +``` + +- 根节点必须是 `and` / `or`。 +- `lt`、`gt`、`lte`、`gte` 的值必须是 JSON 数字，不能写成数字字符串。 +- 单选/多选字段建议使用 `field get` 返回的 option ID。 +- 所有 Base、table、field 和 option ID 都必须从当前目标 Base 的实时元数据取得，不能复用示例或历史 ID。 + +## 降级边界 + +只有用户要求记录明细、少量校验样本、精确分位数输入，或聚合接口明确失败时，才使用 `record query`。需要先逐行运算再聚合的指标必须依赖表内已有且可直接聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能遍历全表本地二次计算。 diff --git a/skills/multi/dingtalk-aitable/references/aitable.md b/skills/multi/dingtalk-aitable/references/aitable.md index 6c1026b5..3b4b4f31 100644 --- a/skills/multi/dingtalk-aitable/references/aitable.md +++ b/skills/multi/dingtalk-aitable/references/aitable.md @@ -79,6 +79,8 @@ Flags: |------|------|----------------|----------| | `record query` | 查询/搜索记录 | [aitable-record-query.md](./aitable/aitable-record-query.md) | 先 `field get` 拿 fieldId；`--all` 自动翻页；filters 结构见 reference | | `record get` | 按 ID 取记录（`record query --record-ids` 的窄别名） | [aitable-record-query.md](./aitable/aitable-record-query.md) | 已知 recordId 时首选；必填 `--record-ids`（单次最多 100 条）；未暴露 filters/sort/query/cursor/limit | +| `record stats` | 不分组的服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 大写；最多 20 项，同字段不可重复；全量统计省略 limit | +| `record group-stats` | 分组、去重和高级服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 小写；group 为 JSON 数组字符串；最多 1000 个分组 | | `record create` | 新增记录 | [aitable-record-create.md](./aitable/aitable-record-create.md) | cells key 必须是 fieldId 不是字段名；单次最多 100 条 | | `record update` | 更新记录（每条独立 cells） | [aitable-record-update.md](./aitable/aitable-record-update.md) | 需先 query 拿 recordId；`cells` key 支持 fieldId 或当前表内唯一字段名，推荐 fieldId；`--records` 是 `[{recordId,cells},...]` 数组 | | `record batch-update` | 批量更新（同一 cells 应用到多条 recordId） | [aitable-record-update.md](./aitable/aitable-record-update.md)、[aitable-cell-value.md](./aitable/aitable-cell-value.md) | 适合"统一标记完成/统一改负责人"等共享 patch 场景；`--cells` 是 JSON object（key=fieldId，value 按字段类型见 cell-value.md），与 record update 的单条 cells 结构完全一致；必填 `--record-ids` `--cells`；单次最多 100 条 | @@ -357,6 +359,8 @@ dws aitable export data --base-id --task-id --timeout-ms 300 用户说"记录/行/数据/row": - 查看/搜索 → `record query`（读 [aitable-record-query.md](./aitable/aitable-record-query.md)） +- 总数/求和/平均值/中位数/完整率等标量统计 → `record stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） +- 分组统计/唯一实体计数/去重率 → `record group-stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） - 找空行 / 没填东西的行 → `record query-empty`（读 [aitable-record-query.md](./aitable/aitable-record-query.md)） - 已知 recordId 反查字段值 → `record get`（按 ID 取专用，等价 `record query --record-ids`） - 添加/写入 → `record create`（读 [aitable-record-create.md](./aitable/aitable-record-create.md)） @@ -388,7 +392,7 @@ dws aitable export data --base-id --task-id --timeout-ms 300 用户说"筛选/过滤/filter" → 读 [aitable-filter-sort.md](./aitable/aitable-filter-sort.md) -用户说"统计/分析/聚合/TOP N/全量" → 读 [aitable-data-analysis-sop.md](./aitable/aitable-data-analysis-sop.md) +用户说"统计/分析/聚合/TOP N/全量" → 先读 [aitable-data-analysis-sop.md](./aitable/aitable-data-analysis-sop.md)，聚合参数见 [aitable-record-stats.md](./aitable/aitable-record-stats.md) 用户说"公式/formula/计算字段/派生指标" → 读 [aitable-formula-guide.md](./aitable/aitable-formula-guide.md) diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-best-practices.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-best-practices.md index 2becd358..249f788e 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-best-practices.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-best-practices.md @@ -12,7 +12,7 @@ ## 2. 查询执行契约 -1. **不要拉全量后在 context 里手动统计** — 优先用 `--filters` 在服务端过滤 +1. **不要拉全量后在 context 里手动统计** — 标量聚合用 `record stats`，分组/去重用 `record group-stats` 2. **has_more=true 时不能做全局结论** — 数据可能不完整 3. **优先用 `--filters` 在服务端过滤** — 不要拉全量后在本地 jq/grep 4. **fieldId 必须来自 `field get` 真实返回** — 不要猜测 fieldId @@ -23,7 +23,9 @@ | 用户诉求 | 优先方案 | 不要误走 | |---------|----------|----------| | 查看几条数据 | `record query` | 不要用 `--all` | -| 全量拉取/统计 | `record query --all` | 不要手动循环 cursor | +| 全量拉取明细 | `record query --all` | 不要手动循环 cursor | +| 标量统计 | `record stats` | 不要先拉全量再本地计算 | +| 分组/去重统计 | `record group-stats` | 不要先拉全量再本地 groupby | | 全量导出为文件 | `export data` | 不要 `--all` 拉全量再写文件 | | 批量写入 | `record create`（分批 100 条） | 不要一次传超过 100 条 | | 附件/图片上传 | `attachment upload` 获取 fileToken → `record create/update` 用 fileToken 写入 | **严禁直接传图片 URL 到附件字段**（服务端同步下载会超时） | diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-data-analysis-sop.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-data-analysis-sop.md index 6331944e..ab67ce83 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-data-analysis-sop.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-data-analysis-sop.md @@ -17,16 +17,16 @@ │ → record query --sort '[{"fieldId":"xxx","direction":"desc"}]' --limit 5 │ ├─ 全量统计（如"一共多少条"、"所有记录的总销售额"） -│ → record query --all --field-ids <目标字段> -│ → 本地计算 count / sum / avg +│ → record stats --stats '[{"fieldId":"...","statsType":"COUNT|SUM|AVG|..."}]' │ ├─ 分组统计（如"每个状态各有多少条"） -│ → record query --all --field-ids <分组字段>,<度量字段> -│ → 本地按分组字段 groupby 再聚合 +│ → record group-stats --group '[...]' --stats '[{"fieldId":"...","statsType":"count"}]' +│ +├─ 条件唯一实体数（如"有索赔单的门店共有多少家"） +│ → record group-stats --filters '{...}' --stats '[{"fieldId":"<实体字段>","statsType":"distinct"}]' │ └─ 判断全局结论（如"是否所有记录都满足条件"） - → record query --all（或用 --filters 反向筛选不满足的） - → 基于全量结果判断 + → record stats 对反向过滤结果 COUNT；只有需要行级证据时再 record query ``` ## 2. 核心规则 @@ -50,15 +50,15 @@ | 按日期降序取最新5条 | `--sort '[...]' --limit 5` | `--all` 拉全量再本地 sort + slice | | 模糊搜索标题含"Q1" | `--filters` 用 `contain` 操作符 | 全量拉取再本地 grep | -### 2.3 服务端无法完成时，才用 --all + 本地计算 +### 2.3 聚合必须优先在服务端完成 -以下场景服务端 filters/sort 无法满足，需要 `--all` 后本地处理： +以下场景均有服务端聚合入口，不得先用 `record query --all` 下载全表计算： -- SUM / AVG / COUNT / MAX / MIN 聚合 -- 分组统计（GROUP BY） -- 多字段联合计算（如"销售额 = 单价 × 数量"） -- 去重计数（COUNT DISTINCT） -- 百分比/占比计算 +- `record stats`：不分组的 COUNT / SUM / AVG / MAX / MIN / MEDIAN / DISTINCT / 完整率等 +- `record group-stats`：分组统计，以及不带 group 的条件 DISTINCT 唯一计数 +- 任意条件比率：分别聚合分子与分母，再对齐范围和 `dataVersion` 计算 + +只有用户要求记录明细、少量样本校验、精确分位数输入，或聚合接口明确返回不支持/错误时，才允许使用 `record query`。需要先逐行运算再聚合的指标（例如两个日期相减）必须使用表内已有且可聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能下载全表本地二次计算。 ### 2.4 --all 使用注意 @@ -122,7 +122,8 @@ dws aitable record query \ | 用户诉求 | 优先方案 | 不要误走 | |---------|---------|---------| -| 一次性统计/临时分析 | `record query --all` + 本地聚合 | 不要创建 formula 字段 | +| 一次性标量统计 | `record stats` | 不要 `record query --all` 后本地聚合 | +| 分组/去重统计 | `record group-stats` | 不要下载全表 groupby / 去重 | | 长期展示派生指标 | 创建 formula 字段（见 [formula-guide](./aitable-formula-guide.md)） | 不要每次手算再手动写入 | | 按条件筛选记录 | `record query --filters` | 不要 `--all` 拉全量再本地 filter | | 取最新/最大/前N | `--sort + --limit` | 不要 `--all` 再本地排序取前N | diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-formula-guide.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-formula-guide.md index 3b3fd853..cb3bca87 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-formula-guide.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-formula-guide.md @@ -9,7 +9,7 @@ | 长期展示在表中的派生值（如"总价=单价×数量"） | ✅ | | | 条件标记（如"超期=IF(截止日期 \ + --table-id \ + --stats '[{"fieldId":"","statsType":"COUNT"}]' \ + --format json +``` + +- `statsType` 必须大写。 +- `--stats` 单次最多 20 项，同一 `fieldId` 不得重复；同字段多个指标拆成多次调用。 +- 支持基础类型 `COUNT`、`COUNT_COLUMN`、`SUM`、`AVG`、`MAX`、`MIN`，以及运行时支持的 `MEDIAN`、`STANDARD_DEVIATION`、`RANGE`、`DISTINCT`、`DISTINCT_RATIO`、完整率、勾选率和日期统计类型。 +- 统计全部匹配记录时省略 `--limit`；传入 limit 会改变统计范围。 +- 可选参数：`--filters`、`--sort`、`--keyword`、`--search-field-ids`、`--data-version`。 + +## 分组或去重统计 + +```bash +dws aitable record group-stats \ + --base-id \ + --table-id \ + --group '[{"fieldId":"","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' \ + --stats '[{"fieldId":"","statsType":"avg"}]' \ + --limit 1000 \ + --format json +``` + +- `statsType` 必须小写；基础类型为 `sum`、`avg`、`count`、`max`、`min`，后端还可能支持 `median`、`distinct`、`distinct_ratio` 等高级类型。 +- `--group` 和 `--sort` 都是 JSON 数组编码后的字符串，CLI 会原样映射到 MCP 的 `group` / `sortDsl`。 +- 分组结果最多 1000 行。不要依赖服务端 limit 选择 Top N；应在基数不超过 1000 时取完整分组结果后排序。 +- 条件唯一实体计数不传 `--group`，对实体字段使用 `distinct`。 + +## 过滤条件 + +```bash +--filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}' +``` + +- 根节点必须是 `and` / `or`。 +- `lt`、`gt`、`lte`、`gte` 的值必须是 JSON 数字，不能写成数字字符串。 +- 单选/多选字段建议使用 `field get` 返回的 option ID。 +- 所有 Base、table、field 和 option ID 都必须从当前目标 Base 的实时元数据取得，不能复用示例或历史 ID。 + +## 降级边界 + +只有用户要求记录明细、少量校验样本、精确分位数输入，或聚合接口明确失败时，才使用 `record query`。需要先逐行运算再聚合的指标必须依赖表内已有且可直接聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能遍历全表本地二次计算。 From 07aa2c883ad08822c96d49be2df55230caa759f1 Mon Sep 17 00:00:00 2001 From: fengbai Date: Fri, 14 Aug 2026 15:10:20 +0800 Subject: [PATCH 108/250] fix(calendar): address CR comments for share-info - Fix Example indentation (tab -> 2 spaces) - Remove unsubstantiated default en-US from --language help/docs - Add test asserting calendarId/language are omitted when only --id is passed --- .changes/calendar-event-share-info.md | 2 +- internal/app/root_help_test.go | 18 ++++++++++++++++++ internal/helpers/calendar.go | 6 +++--- skills/mono/references/products/calendar.md | 4 ++-- .../dingtalk-calendar/references/calendar.md | 4 ++-- 5 files changed, 26 insertions(+), 8 deletions(-) diff --git a/.changes/calendar-event-share-info.md b/.changes/calendar-event-share-info.md index 2ec9f1fa..b1cde315 100644 --- a/.changes/calendar-event-share-info.md +++ b/.changes/calendar-event-share-info.md @@ -2,4 +2,4 @@ category: Added --- -- **Calendar event share-info** — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`. +- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`. diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index 31949cd3..c8bf72b8 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -432,6 +432,24 @@ func TestCalendarEventShareInfoRequiresEventID(t *testing.T) { } } +func TestCalendarEventShareInfoOmitsOptionalArgs(t *testing.T) { + got, err := executeRootCaptureStdout(t, []string{ + "--dry-run", "calendar", "event", "share-info", + "--id", "EVT_001", + }) + if err != nil { + t.Fatalf("calendar event share-info --dry-run with only --id error = %v\n%s", err, got) + } + if !strings.Contains(got, "\"eventId\"") { + t.Fatalf("calendar event share-info dry-run output missing eventId:\n%s", got) + } + for _, unwanted := range []string{"\"calendarId\"", "\"language\""} { + if strings.Contains(got, unwanted) { + t.Fatalf("calendar event share-info dry-run with only --id should not contain %q:\n%s", unwanted, got) + } + } +} + func TestRootKeepsSVIPChatCompatibilityFlags(t *testing.T) { root := NewRootCommand() diff --git a/internal/helpers/calendar.go b/internal/helpers/calendar.go index 71d872f6..b647b48e 100644 --- a/internal/helpers/calendar.go +++ b/internal/helpers/calendar.go @@ -2265,8 +2265,8 @@ func newCalendarCommand() *cobra.Command { Short: "获取日程的分享信息", Long: `根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程。`, Example: ` dws calendar event share-info --id EVENT_ID # 查询 eventId: dws calendar event list - dws calendar event share-info --id EVENT_ID --language zh-CN - dws calendar event share-info --id EVENT_ID --calendar-id primary`, + dws calendar event share-info --id EVENT_ID --language zh-CN + dws calendar event share-info --id EVENT_ID --calendar-id primary`, RunE: func(cmd *cobra.Command, args []string) error { eventID, err := mustFlagOrFallback(cmd, "id", "event", "event-id", "eventId") if err != nil { @@ -2335,7 +2335,7 @@ func newCalendarCommand() *cobra.Command { _ = eventShareInfoCmd.Flags().MarkHidden("calendarId") eventShareInfoCmd.Flags().String("calendar", "", "") _ = eventShareInfoCmd.Flags().MarkHidden("calendar") - eventShareInfoCmd.Flags().String("language", "", "语言代码 (可选，默认 en-US，如 zh-CN)") + eventShareInfoCmd.Flags().String("language", "", "语言代码 (可选，如 zh-CN)") eventShareInfoCmd.Flags().String("lang", "", "") _ = eventShareInfoCmd.Flags().MarkHidden("lang") diff --git a/skills/mono/references/products/calendar.md b/skills/mono/references/products/calendar.md index 4711854b..db2873f9 100644 --- a/skills/mono/references/products/calendar.md +++ b/skills/mono/references/products/calendar.md @@ -173,7 +173,7 @@ Example: Flags: --id string 日程 ID (必填) --calendar-id string 日历 ID (可选，默认 primary 主日历) - --language string 语言代码 (可选，默认 en-US，如 zh-CN) + --language string 语言代码 (可选，如 zh-CN) ``` > **说明**：根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程（如发送到群聊、邮件）。中文内容建议传 `--language zh-CN`。 @@ -738,7 +738,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 - **日历本**：`book list` 返回的 `id` 才是合法 `calendarId`；如无明确说明，`event list` / `event get` 都不要带 `--calendar-id`，让接口默认走 primary 主日历 - **分页查询**：`event list` / `event instances` 均支持 `--limit`（控制每页条数，默认/最大 100）和 `--cursor`（翻页游标）；**首次查询无需传 `--cursor`**，仅当返回体中包含 `nextCursor` 时，将其作为 `--cursor` 传入可获取下一页 - **循环日程实例**：`event instances` 用于按时间范围展开重复日程（SeriesMaster）的每一个实例；**普通非循环日程调用该命令将查不到任何实例信息** -- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（默认 en-US，中文场景传 zh-CN） +- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（中文场景传 zh-CN） - **日程提醒**：`event create` 支持 `--remind-minutes` 设置开始前提醒，逗号分隔多个分钟数（如 `--remind-minutes 5,10,15`），不传则默认15分钟提醒 - **会议室分页**：`room search` 支持 `--limit`（每页条数，默认100，最大100）和 `--page`（分页起始位置，默认0），与 `room list-groups` 分页风格一致 diff --git a/skills/multi/dingtalk-calendar/references/calendar.md b/skills/multi/dingtalk-calendar/references/calendar.md index 4711854b..db2873f9 100644 --- a/skills/multi/dingtalk-calendar/references/calendar.md +++ b/skills/multi/dingtalk-calendar/references/calendar.md @@ -173,7 +173,7 @@ Example: Flags: --id string 日程 ID (必填) --calendar-id string 日历 ID (可选，默认 primary 主日历) - --language string 语言代码 (可选，默认 en-US，如 zh-CN) + --language string 语言代码 (可选，如 zh-CN) ``` > **说明**：根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程（如发送到群聊、邮件）。中文内容建议传 `--language zh-CN`。 @@ -738,7 +738,7 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 - **日历本**：`book list` 返回的 `id` 才是合法 `calendarId`；如无明确说明，`event list` / `event get` 都不要带 `--calendar-id`，让接口默认走 primary 主日历 - **分页查询**：`event list` / `event instances` 均支持 `--limit`（控制每页条数，默认/最大 100）和 `--cursor`（翻页游标）；**首次查询无需传 `--cursor`**，仅当返回体中包含 `nextCursor` 时，将其作为 `--cursor` 传入可获取下一页 - **循环日程实例**：`event instances` 用于按时间范围展开重复日程（SeriesMaster）的每一个实例；**普通非循环日程调用该命令将查不到任何实例信息** -- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（默认 en-US，中文场景传 zh-CN） +- **日程分享**：`event share-info` 获取日程的分享信息（主题、组织人、地点、入会信息等）；`--language` 控制文案语言（中文场景传 zh-CN） - **日程提醒**：`event create` 支持 `--remind-minutes` 设置开始前提醒，逗号分隔多个分钟数（如 `--remind-minutes 5,10,15`），不传则默认15分钟提醒 - **会议室分页**：`room search` 支持 `--limit`（每页条数，默认100，最大100）和 `--page`（分页起始位置，默认0），与 `room list-groups` 分页风格一致 From 90473284b84d3b2b42226b9b6c311c1bedb3da3a Mon Sep 17 00:00:00 2001 From: fengbai Date: Fri, 14 Aug 2026 15:51:20 +0800 Subject: [PATCH 109/250] fix(calendar): remove shell comment from share-info example - Move the eventId lookup hint into Long description - Keep example commands free of shell comments to pass example policy gate --- internal/helpers/calendar.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/helpers/calendar.go b/internal/helpers/calendar.go index b647b48e..5c71ea67 100644 --- a/internal/helpers/calendar.go +++ b/internal/helpers/calendar.go @@ -2263,8 +2263,8 @@ func newCalendarCommand() *cobra.Command { Use: "share-info", Aliases: []string{"share_info"}, Short: "获取日程的分享信息", - Long: `根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程。`, - Example: ` dws calendar event share-info --id EVENT_ID # 查询 eventId: dws calendar event list + Long: `根据日程 ID 获取日程的分享信息，展示日程主题、组织人、地点、入会信息等，用于向他人分享日程。eventId 可通过 dws calendar event list 获取。`, + Example: ` dws calendar event share-info --id EVENT_ID dws calendar event share-info --id EVENT_ID --language zh-CN dws calendar event share-info --id EVENT_ID --calendar-id primary`, RunE: func(cmd *cobra.Command, args []string) error { From a18b1e5fe4a961727cd27c7392dcf0c995409681 Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 16:11:55 +0800 Subject: [PATCH 110/250] docs: seal changelog for v1.0.59-beta.1 --- .../899-drive-latest-incomplete-scan.md | 0 .../1.0.59-beta.1}/942-drive-list-filter.md | 0 .../942-drive-list-pattern-fix.md | 0 .../973-chat-message-time-defaults.md | 0 .../1.0.59-beta.1}/doc-drive-param-aliases.md | 0 .../1.0.59-beta.1}/drive-folder-sync.md | 0 .../1.0.59-beta.1}/global-dingtalk-region.md | 0 .../open-dingtalk-id-format-routing.md | 0 CHANGELOG.md | 64 +++++++++++++++++++ 9 files changed, 64 insertions(+) rename .changes/{ => released/1.0.59-beta.1}/899-drive-latest-incomplete-scan.md (100%) rename .changes/{ => released/1.0.59-beta.1}/942-drive-list-filter.md (100%) rename .changes/{ => released/1.0.59-beta.1}/942-drive-list-pattern-fix.md (100%) rename .changes/{ => released/1.0.59-beta.1}/973-chat-message-time-defaults.md (100%) rename .changes/{ => released/1.0.59-beta.1}/doc-drive-param-aliases.md (100%) rename .changes/{ => released/1.0.59-beta.1}/drive-folder-sync.md (100%) rename .changes/{ => released/1.0.59-beta.1}/global-dingtalk-region.md (100%) rename .changes/{ => released/1.0.59-beta.1}/open-dingtalk-id-format-routing.md (100%) diff --git a/.changes/899-drive-latest-incomplete-scan.md b/.changes/released/1.0.59-beta.1/899-drive-latest-incomplete-scan.md similarity index 100% rename from .changes/899-drive-latest-incomplete-scan.md rename to .changes/released/1.0.59-beta.1/899-drive-latest-incomplete-scan.md diff --git a/.changes/942-drive-list-filter.md b/.changes/released/1.0.59-beta.1/942-drive-list-filter.md similarity index 100% rename from .changes/942-drive-list-filter.md rename to .changes/released/1.0.59-beta.1/942-drive-list-filter.md diff --git a/.changes/942-drive-list-pattern-fix.md b/.changes/released/1.0.59-beta.1/942-drive-list-pattern-fix.md similarity index 100% rename from .changes/942-drive-list-pattern-fix.md rename to .changes/released/1.0.59-beta.1/942-drive-list-pattern-fix.md diff --git a/.changes/973-chat-message-time-defaults.md b/.changes/released/1.0.59-beta.1/973-chat-message-time-defaults.md similarity index 100% rename from .changes/973-chat-message-time-defaults.md rename to .changes/released/1.0.59-beta.1/973-chat-message-time-defaults.md diff --git a/.changes/doc-drive-param-aliases.md b/.changes/released/1.0.59-beta.1/doc-drive-param-aliases.md similarity index 100% rename from .changes/doc-drive-param-aliases.md rename to .changes/released/1.0.59-beta.1/doc-drive-param-aliases.md diff --git a/.changes/drive-folder-sync.md b/.changes/released/1.0.59-beta.1/drive-folder-sync.md similarity index 100% rename from .changes/drive-folder-sync.md rename to .changes/released/1.0.59-beta.1/drive-folder-sync.md diff --git a/.changes/global-dingtalk-region.md b/.changes/released/1.0.59-beta.1/global-dingtalk-region.md similarity index 100% rename from .changes/global-dingtalk-region.md rename to .changes/released/1.0.59-beta.1/global-dingtalk-region.md diff --git a/.changes/open-dingtalk-id-format-routing.md b/.changes/released/1.0.59-beta.1/open-dingtalk-id-format-routing.md similarity index 100% rename from .changes/open-dingtalk-id-format-routing.md rename to .changes/released/1.0.59-beta.1/open-dingtalk-id-format-routing.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0656ba9c..0a1f2dfc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,70 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +## [1.0.59-beta.1] - 2026-08-14 + +### Added + +- **Drive list type/time filtering** (#942) — `dws drive list` gains `--type + file|folder`, `--start`, and `--end` for client-side filtering by node type + and modification time on both the pan and workspace routes. Filtering runs + a bounded full scan of the target directory (2000-entry cap, reported via + `truncated=true`), composes with `--latest`/`--pattern`/`--depth`, and is + mutually exclusive with `--versions`/`--cursor`/`--order-by`/`--order`/ + `--limit`. Time values accept relative forms (`24h`/`7d`/`2w`), RFC 3339, + zone-less ISO 8601 (Asia/Shanghai), or a plain date. + +- **Drive folder synchronization** — adds `dws drive status`, `dws drive pull`, + `dws drive push`, and `dws drive sync` for file-level comparison and transfer + between a local folder and a Drive folder. Differences come from exact MD5 by + default or from modification time with `--quick`; `status` is read-only, `pull` + and `push` are one-directional with `--if-exists skip|smart|overwrite`, and + `sync` is bidirectional with `--on-conflict remote-wins|local-wins|keep-both|ask`. + Only regular files are transferred — online documents and shortcuts are skipped, + neither side deletes extra files, downloads are staged through a temporary file + and committed with an atomic rename, and remote names that would escape + `--local-folder` are reported as failures instead of being written. Every command + prints a structured summary on stdout and exits non-zero when any item fails. + +- **International DingTalk region support** — adds `.io` login and MCP routing, pre-release endpoint overrides, and profile-aware gateway selection while preserving the existing `.com` flow. + +### Changed + +- **Chat identity routing** — validates explicit `openDingTalkId` inputs and improves name, `userId`, and `openDingTalkId` routing for message shortcuts. + +### Fixed + +- **Drive `--latest` refuses incomplete Top-N** (#899) — `dws drive list --latest` used to + exit 0 with a "Top-N" computed over a partially scanned tree whenever a directory read + failed mid-recursion (permission denied, API error), letting an incomplete set pose as the + globally newest files. Truncation at the 2000-item scan cap and mid-recursion directory + failures now both fail closed (`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`), report + the first failing folder with its depth and reason, and emit a recovery command that + reproduces the original candidate set — query domain, `--folder`, `--pattern`, `--type`, + `--start` and `--end` are all carried over. On POSIX shells each user-supplied value is + quoted so a URL query string or a shell metacharacter cannot change how the copied command + parses. On Windows no quoting form is safe for both `cmd.exe` and PowerShell, so values + containing metacharacters are not inlined at all: the command carries a placeholder and the + original value is shown on a separate line marked as data rather than an executable command. + Unrecoverable errors under `--latest` return the root cause instead of a partial result. + Remote-controlled folder names and server error text are stripped of ANSI escapes and + control characters before they reach the plain-text stderr message. The internal `sortTime` + sort key no longer leaks into `drive list --depth` output on any path. + +- **Drive list pattern filtering** (#942) — `dws drive list --pattern` on the + single-layer pan route now filters the returned page by name pattern; the + flag was previously accepted but silently ignored. + +- **Drive list `--type folder --latest` composition** (#942) — `--latest` now + ranks the filtered entries (folders included when `--type folder` is set) + instead of unconditionally dropping folders, so the documented combination + returns the most recently modified folders rather than an empty list. + +- **Chat message time defaults** (#973) — default omitted `chat message list-all` time bounds in `Asia/Shanghai` when emitting timezone-less `yyyy-MM-dd HH:mm:ss` values, matching parsing semantics and rejecting reversed windows. + +- **Doc and Drive parameter aliases** — normalizes reviewed identifier, pagination, path, version, and role synonyms while blocking ambiguous values before dispatch. + + ## [1.0.58] - 2026-08-13 This release promotes the sealed `v1.0.58-beta.6` contents to stable. From 3a3cf00072450fdc4aadefde608faa1162379a1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=9C=E7=8E=84?= Date: Fri, 14 Aug 2026 16:21:09 +0800 Subject: [PATCH 111/250] test(aitable): cover stats validation branches --- internal/helpers/aitable_stats_test.go | 82 ++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/internal/helpers/aitable_stats_test.go b/internal/helpers/aitable_stats_test.go index 3ab19337..9001ee39 100644 --- a/internal/helpers/aitable_stats_test.go +++ b/internal/helpers/aitable_stats_test.go @@ -113,6 +113,33 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`}, wantErr: "大写", }, + { + name: "records stats require at least one item", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[]`}, + wantErr: "至少需要一个统计项", + }, + { + name: "records stats enforce item cap", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[ + {"fieldId":"f01","statsType":"COUNT"},{"fieldId":"f02","statsType":"COUNT"}, + {"fieldId":"f03","statsType":"COUNT"},{"fieldId":"f04","statsType":"COUNT"}, + {"fieldId":"f05","statsType":"COUNT"},{"fieldId":"f06","statsType":"COUNT"}, + {"fieldId":"f07","statsType":"COUNT"},{"fieldId":"f08","statsType":"COUNT"}, + {"fieldId":"f09","statsType":"COUNT"},{"fieldId":"f10","statsType":"COUNT"}, + {"fieldId":"f11","statsType":"COUNT"},{"fieldId":"f12","statsType":"COUNT"}, + {"fieldId":"f13","statsType":"COUNT"},{"fieldId":"f14","statsType":"COUNT"}, + {"fieldId":"f15","statsType":"COUNT"},{"fieldId":"f16","statsType":"COUNT"}, + {"fieldId":"f17","statsType":"COUNT"},{"fieldId":"f18","statsType":"COUNT"}, + {"fieldId":"f19","statsType":"COUNT"},{"fieldId":"f20","statsType":"COUNT"}, + {"fieldId":"f21","statsType":"COUNT"} + ]`}, + wantErr: "单次最多支持 20 个统计项", + }, + { + name: "records stats require item fields", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":" ","statsType":"COUNT"}]`}, + wantErr: "均不能为空", + }, { name: "records stats reject duplicate field", args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"},{"fieldId":"f","statsType":"SUM"}]`}, @@ -138,6 +165,61 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"eq","operands":[]}`}, wantErr: "and 或 or", }, + { + name: "records filters reject malformed JSON", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{`}, + wantErr: "必须是 JSON 对象", + }, + { + name: "records filters reject null", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `null`}, + wantErr: "不能是 null", + }, + { + name: "records filters reject a second JSON value", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} {}`}, + wantErr: "只能包含一个 JSON 对象", + }, + { + name: "records filters reject invalid trailing content", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} trailing`}, + wantErr: "无效的尾随内容", + }, + { + name: "records filters require operand array", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":{}}`}, + wantErr: "operands 必须是 JSON 数组", + }, + { + name: "records sort requires an item", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[]`}, + wantErr: "至少需要一个条目", + }, + { + name: "records sort items must be objects", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[1]`}, + wantErr: "必须是 JSON 对象", + }, + { + name: "records limit must be positive", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--limit", "0"}, + wantErr: "必须大于 0", + }, + { + name: "group filters reject malformed JSON", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{`}, + wantErr: "必须是 JSON 对象", + }, + { + name: "group filters require logical root", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"eq","operands":[]}`}, + wantErr: "and 或 or", + }, + { + name: "group sort rejects invalid DSL", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--sort", `{}`}, + wantErr: "JSON 数组", + }, } for _, test := range tests { t.Run(test.name, func(t *testing.T) { From 3aa06e32fa326eb5932c288e285258047debec58 Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 16:24:00 +0800 Subject: [PATCH 112/250] ci: shard full-suite coverage and cache merge-base profile The Coverage context was the PR critical path (~17 min end to end): coverage-current re-ran the whole suite serially (-p 1, ~13 min) and coverage-baseline re-ran it again at the merge-base (~13 min) although that profile is a pure function of the base commit. - coverage-current now owns only the scoped (standard-tier) profile; full-suite candidate profiles come from a 5-way shard matrix (app/cli/generators/helpers/remaining) that keeps -p 1 inside each shard on isolated runners. scripts/ci/test-packages.sh list-coverage defines the shards and verify proves the union equals the previous single-run package set exactly once. - the aggregate Coverage job reassembles the disjoint shard profiles into coverage.txt before make coverage-gate, failing closed when a shard file is missing, so gate semantics (100% changed-code + scope-matched overall non-regression) are byte-compatible. - coverage-baseline restores the merge-base full-suite profile from an exact-key cache (merge-base SHA + resolved Go version) written by the last green main push; any miss falls back to recomputing in the merge-base worktree. Exact key only - no prefix fallback, a near-miss profile would compare the candidate against the wrong commit. - new contract tests pin the shard matrix, the assembly step, the exact-key cache pair, and the absence of restore-keys; the package plan test also covers the coverage shard partition. --- .github/workflows/ci.yml | 185 ++++++++++++++---- Makefile | 2 +- docs/ci-pr-gates.md | 14 +- scripts/ci/test-packages.sh | 103 ++++++++++ test/scripts/ci_test_package_plan_test.go | 33 ++++ .../coverage_workflow_contract_test.go | 94 +++++++++ 6 files changed, 390 insertions(+), 41 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b8c1007d..cdcdb309 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -911,7 +911,7 @@ jobs: coverage-current: name: Coverage (current) needs: lint - if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' }} + if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite != 'true' }} runs-on: ubuntu-latest timeout-minutes: 20 steps: @@ -926,10 +926,6 @@ jobs: with: go-version-file: go.mod - - name: Install archive tooling - if: needs.lint.outputs.full_suite == 'true' - run: sudo apt-get update && sudo apt-get install -y zip unzip - - name: Resolve authoritative coverage base env: PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} @@ -951,41 +947,33 @@ jobs: - name: Build run: make build - - name: Run current unit tests with coverage + - name: Run scoped unit tests with coverage shell: bash env: DWS_PACKAGE_VERSION: 0.0.0-test - FULL_SUITE: ${{ needs.lint.outputs.full_suite }} run: | set -euo pipefail - if [ "$FULL_SUITE" = true ]; then + changed_output="$( + ./scripts/ci/changed-test-packages.sh \ + changed "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF" + )" + impacted_output="$( + ./scripts/ci/changed-test-packages.sh \ + list "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF" + )" + if [ -z "$changed_output" ] || [ -z "$impacted_output" ]; then + printf 'mode: atomic\n' > coverage.txt + echo "No buildable Go package needs scoped coverage." \ + >> "$GITHUB_STEP_SUMMARY" + else + mapfile -t changed_packages <<< "$changed_output" + mapfile -t impacted_packages <<< "$impacted_output" + coverpkg="$(IFS=,; echo "${changed_packages[*]}")" go test -count=1 -p 1 \ + -coverpkg="$coverpkg" \ -coverprofile=coverage.txt \ -covermode=atomic \ - ./ ./cmd/... ./internal/... ./skills/... - else - changed_output="$( - ./scripts/ci/changed-test-packages.sh \ - changed "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF" - )" - impacted_output="$( - ./scripts/ci/changed-test-packages.sh \ - list "$COVERAGE_BASE_REF" "$COVERAGE_HEAD_REF" - )" - if [ -z "$changed_output" ] || [ -z "$impacted_output" ]; then - printf 'mode: atomic\n' > coverage.txt - echo "No buildable Go package needs scoped coverage." \ - >> "$GITHUB_STEP_SUMMARY" - else - mapfile -t changed_packages <<< "$changed_output" - mapfile -t impacted_packages <<< "$impacted_output" - coverpkg="$(IFS=,; echo "${changed_packages[*]}")" - go test -count=1 -p 1 \ - -coverpkg="$coverpkg" \ - -coverprofile=coverage.txt \ - -covermode=atomic \ - "${impacted_packages[@]}" - fi + "${impacted_packages[@]}" fi if [ "$(wc -l < coverage.txt)" -gt 1 ]; then go tool cover -func=coverage.txt @@ -998,6 +986,66 @@ jobs: path: coverage.txt retention-days: 1 + coverage-current-full: + name: "Coverage (current: ${{ matrix.shard }})" + needs: lint + if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }} + runs-on: ubuntu-latest + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + shard: + - app + - cli + - generators + - helpers + - remaining + steps: + - name: Check out repository + uses: actions/checkout@v4 + with: + ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }} + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version-file: go.mod + + - name: Install archive tooling + run: sudo apt-get update && sudo apt-get install -y zip unzip + + - name: Build + run: make build + + # Each shard keeps -p 1 so the authoritative measurement stays serial + # inside one instrumented process group; shards run on isolated runners, + # and scripts/ci/test-packages.sh verify proves the shard union equals + # the previous single full-suite package set exactly once. + - name: Run current shard tests with coverage + shell: bash + env: + DWS_PACKAGE_VERSION: 0.0.0-test + COVERAGE_SHARD: ${{ matrix.shard }} + run: | + set -euo pipefail + package_output="$(./scripts/ci/test-packages.sh list-coverage "$COVERAGE_SHARD")" + test -n "$package_output" + mapfile -t packages <<< "$package_output" + test "${#packages[@]}" -gt 0 + go test -count=1 -p 1 \ + -coverprofile="coverage-shard-$COVERAGE_SHARD.txt" \ + -covermode=atomic \ + "${packages[@]}" + go tool cover -func="coverage-shard-$COVERAGE_SHARD.txt" | tail -n 1 + + - name: Upload current shard coverage profile + uses: actions/upload-artifact@v4 + with: + name: coverage-current-shard-${{ matrix.shard }} + path: coverage-shard-${{ matrix.shard }}.txt + retention-days: 1 + coverage-supporting: name: Coverage (supporting) needs: lint @@ -1051,14 +1099,11 @@ jobs: ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }} - name: Set up Go + id: setup-go uses: actions/setup-go@v5 with: go-version-file: go.mod - - name: Install archive tooling - if: needs.lint.outputs.full_suite == 'true' - run: sudo apt-get update && sudo apt-get install -y zip unzip - - name: Resolve authoritative coverage base env: PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} @@ -1076,7 +1121,26 @@ jobs: git rev-parse --verify "${base_ref}^{commit}" >/dev/null echo "COVERAGE_BASE_REF=$base_ref" >> "$GITHUB_ENV" + # The merge-base full-suite profile is a pure function of the base + # commit. Reuse the profile published by the last green push run of + # exactly that commit instead of re-running the whole suite; any key + # mismatch falls back to authoritative recomputation. Exact key only, + # never prefix fallback: a near-miss profile would compare the + # candidate against the wrong commit. + - name: Restore cached merge-base coverage profile + id: baseline-cache + if: needs.lint.outputs.full_suite == 'true' + uses: actions/cache/restore@v4 + with: + path: coverage-base.txt + key: dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} + + - name: Install archive tooling + if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true' + run: sudo apt-get update && sudo apt-get install -y zip unzip + - name: Run baseline unit tests with coverage + if: steps.baseline-cache.outputs.cache-hit != 'true' shell: bash env: DWS_PACKAGE_VERSION: 0.0.0-test @@ -1125,6 +1189,13 @@ jobs: fi ) + - name: Save merge-base coverage profile cache + if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: coverage-base.txt + key: dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} + - name: Upload baseline coverage profile uses: actions/upload-artifact@v4 with: @@ -1137,6 +1208,7 @@ jobs: needs: - lint - coverage-current + - coverage-current-full - coverage-supporting - coverage-baseline - coverage-darwin @@ -1152,6 +1224,7 @@ jobs: FULL_SUITE: ${{ needs.lint.outputs.full_suite }} PLATFORM_SENSITIVE: ${{ needs.lint.outputs.platform_sensitive }} CURRENT_RESULT: ${{ needs.coverage-current.result }} + CURRENT_FULL_RESULT: ${{ needs.coverage-current-full.result }} SUPPORTING_RESULT: ${{ needs.coverage-supporting.result }} BASELINE_RESULT: ${{ needs.coverage-baseline.result }} DARWIN_RESULT: ${{ needs.coverage-darwin.result }} @@ -1159,6 +1232,7 @@ jobs: run: | failed=0 current_expected=success + current_full_expected=skipped supporting_expected=skipped baseline_expected=success native_expected=skipped @@ -1166,6 +1240,8 @@ jobs: current_expected=skipped baseline_expected=skipped elif [ "$FULL_SUITE" = true ]; then + current_expected=skipped + current_full_expected=success supporting_expected=success fi if [ "$CHANGELOG_ONLY" != true ] && @@ -1176,6 +1252,7 @@ jobs: for profile in \ "current:$CURRENT_RESULT:$current_expected" \ + "current shards:$CURRENT_FULL_RESULT:$current_full_expected" \ "supporting:$SUPPORTING_RESULT:$supporting_expected" \ "baseline:$BASELINE_RESULT:$baseline_expected" do @@ -1211,6 +1288,7 @@ jobs: ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }} - name: Set up Go + id: setup-go if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' uses: actions/setup-go@v5 with: @@ -1234,11 +1312,12 @@ jobs: git rev-parse --verify "${base_ref}^{commit}" >/dev/null echo "COVERAGE_BASE_REF=$base_ref" >> "$GITHUB_ENV" - - name: Download current coverage profile + - name: Download current coverage profiles if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' uses: actions/download-artifact@v4 with: - name: coverage-current-profile + pattern: coverage-current-* + merge-multiple: true path: . - name: Download supporting coverage profiles @@ -1255,6 +1334,26 @@ jobs: name: coverage-baseline-profile path: . + # Shard profiles cover disjoint package sets, so their block-level + # concatenation is the same candidate profile one serial run produced. + # Every expected shard must be present; a missing shard would silently + # shrink the scope-matched overall comparison. + - name: Assemble full-suite coverage profile + if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' + shell: bash + run: | + set -euo pipefail + test ! -f coverage.txt + for shard in app cli generators helpers remaining; do + profile="coverage-shard-$shard.txt" + test -f "$profile" + test "$(head -n 1 "$profile")" = "mode: atomic" + done + printf 'mode: atomic\n' > coverage.txt + for shard in app cli generators helpers remaining; do + tail -n +2 "coverage-shard-$shard.txt" >> coverage.txt + done + - name: Enforce coverage gate if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' env: @@ -1275,6 +1374,16 @@ jobs: COVERAGE_ADDITIONAL_DIFF_PROFILE="$additional_profile" \ make coverage-gate BASE_REF="$COVERAGE_BASE_REF" + # Publish this push's full-suite profile as the merge-base cache for + # future PRs whose merge-base is exactly this commit. Saved only after + # the gate passed so a broken run never becomes a baseline. + - name: Save push coverage profile as merge-base cache + if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' + uses: actions/cache/save@v4 + with: + path: coverage.txt + key: dws-coverage-full-v1-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }} + - name: Generate coverage report if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' run: | diff --git a/Makefile b/Makefile index 75b4356a..73913b28 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ help: @printf "Available targets:\n" @printf " make build - Build the dws CLI binary\n" @printf " make test - Run the Go test suite\n" - @printf " make test-plan - Verify every default Go package belongs to one CI test shard\n" + @printf " make test-plan - Verify CI test and full-suite coverage package plans cover their scopes exactly once\n" @printf " make test-auth-legacy-compat - Run stable legacy authentication compatibility regressions\n" @printf " make lint - Run formatting checks, go vet, and staticcheck\n" @printf " make format-check - Check all repository Go source files with gofmt\n" diff --git a/docs/ci-pr-gates.md b/docs/ci-pr-gates.md index 5244b214..2141cecf 100644 --- a/docs/ci-pr-gates.md +++ b/docs/ci-pr-gates.md @@ -201,8 +201,18 @@ base_ref=$(git merge-base HEAD origin/main) standard PR, CI derives changed packages and their reverse-dependency test closure, then generates candidate and merge-base profiles with the same test scope and `coverpkg`. High-risk and protected-main runs use the complete -profiles. Supporting and (when platform-selected) native profiles are -generated before the aggregate `Coverage` context evaluates them. The +profiles. The complete candidate profile is produced by disjoint per-shard +helper jobs (`scripts/ci/test-packages.sh list-coverage`, kept serial with +`-p 1` inside each shard; `verify` proves the shard union equals the +full-suite scope exactly once) and concatenated in the aggregate job before +enforcement. The complete merge-base profile is restored from an exact-key +cache written by the last green `main` push of that same commit (key: +merge-base SHA plus resolved Go version); any miss falls back to recomputing +it in a merge-base worktree. Near-miss reuse is forbidden — the caches carry +no prefix restore keys, because a neighbouring commit's profile would compare +the candidate against the wrong baseline. Supporting and (when +platform-selected) native profiles are generated before the aggregate +`Coverage` context evaluates them. The aggregate and native gates require 100% coverage for changed executable Go statements. Overall coverage remains an unrounded, zero-tolerance, scope-matched merge-base non-regression check. Candidate and baseline profiles diff --git a/scripts/ci/test-packages.sh b/scripts/ci/test-packages.sh index 6d57298c..fd36ed46 100755 --- a/scripts/ci/test-packages.sh +++ b/scripts/ci/test-packages.sh @@ -7,6 +7,7 @@ MODULE="$(cd "$ROOT" && go list -m)" usage() { printf '%s\n' \ "usage: $0 list " \ + " $0 list-coverage " \ " $0 verify" >&2 exit 2 } @@ -57,6 +58,52 @@ list_shard() { esac } +# Full-suite coverage measurement shards the same authoritative package set the +# single serial run used: ./ ./cmd/... ./internal/... ./skills/... (pkg/ and +# scripts/ belong to the supporting profile; test/ suites carry no production +# statements for the candidate profile). Shards stay disjoint so their merged +# profile is block-for-block equivalent to one serial invocation. +list_coverage_scope() { + cd "$ROOT" + go list ./ ./cmd/... ./internal/... ./skills/... +} + +list_coverage_shard() { + shard="$1" + cd "$ROOT" + + case "$shard" in + app) + go list ./internal/app/... + ;; + cli) + go list ./internal/cli/... + ;; + generators) + go list ./internal/generator/... + ;; + helpers) + go list ./internal/helpers/... + ;; + remaining) + scope_packages="$(list_coverage_scope)" + printf '%s\n' "$scope_packages" | while IFS= read -r package; do + case "$package" in + "$MODULE/internal/app"|"$MODULE/internal/app/"*) ;; + "$MODULE/internal/cli"|"$MODULE/internal/cli/"*) ;; + "$MODULE/internal/generator"|"$MODULE/internal/generator/"*) ;; + "$MODULE/internal/helpers"|"$MODULE/internal/helpers/"*) ;; + *) printf '%s\n' "$package" ;; + esac + done + ;; + *) + printf 'unknown coverage package shard: %s\n' "$shard" >&2 + exit 2 + ;; + esac +} + verify_plan() { workdir="$(mktemp -d "${TMPDIR:-/tmp}/dws-test-packages.XXXXXX")" trap 'rm -rf "$workdir"' EXIT HUP INT TERM @@ -114,6 +161,58 @@ verify_plan() { package_count="$(wc -l < "$expected" | tr -d ' ')" printf 'test package plan covers %s default packages exactly once\n' "$package_count" + + coverage_expected="$workdir/coverage-expected" + coverage_assigned="$workdir/coverage-assigned" + coverage_unique="$workdir/coverage-unique" + coverage_duplicates="$workdir/coverage-duplicates" + coverage_missing="$workdir/coverage-missing" + coverage_unexpected="$workdir/coverage-unexpected" + + list_coverage_scope > "$workdir/coverage-scope" + LC_ALL=C sort -u "$workdir/coverage-scope" > "$coverage_expected" + : > "$coverage_assigned" + + for shard in app cli generators helpers remaining; do + shard_packages="$workdir/coverage-$shard" + unsorted_shard_packages="$workdir/coverage-$shard.unsorted" + list_coverage_shard "$shard" > "$unsorted_shard_packages" + LC_ALL=C sort "$unsorted_shard_packages" > "$shard_packages" + if [ ! -s "$shard_packages" ]; then + printf 'coverage package shard is empty: %s\n' "$shard" >&2 + exit 1 + fi + cat "$shard_packages" >> "$coverage_assigned" + done + + LC_ALL=C sort "$coverage_assigned" -o "$coverage_assigned" + uniq -d "$coverage_assigned" > "$coverage_duplicates" + LC_ALL=C sort -u "$coverage_assigned" > "$coverage_unique" + comm -23 "$coverage_expected" "$coverage_unique" > "$coverage_missing" + comm -13 "$coverage_expected" "$coverage_unique" > "$coverage_unexpected" + + coverage_failed=0 + if [ -s "$coverage_duplicates" ]; then + printf '%s\n' 'coverage packages assigned to more than one shard:' >&2 + sed 's/^/ /' "$coverage_duplicates" >&2 + coverage_failed=1 + fi + if [ -s "$coverage_missing" ]; then + printf '%s\n' 'full-suite coverage packages missing from the CI coverage plan:' >&2 + sed 's/^/ /' "$coverage_missing" >&2 + coverage_failed=1 + fi + if [ -s "$coverage_unexpected" ]; then + printf '%s\n' 'CI coverage plan contains packages outside its scope:' >&2 + sed 's/^/ /' "$coverage_unexpected" >&2 + coverage_failed=1 + fi + if [ "$coverage_failed" -ne 0 ]; then + exit 1 + fi + + coverage_count="$(wc -l < "$coverage_expected" | tr -d ' ')" + printf 'coverage package plan covers %s full-suite packages exactly once\n' "$coverage_count" } case "${1:-}" in @@ -121,6 +220,10 @@ case "${1:-}" in [ "$#" -eq 2 ] || usage list_shard "$2" ;; + list-coverage) + [ "$#" -eq 2 ] || usage + list_coverage_shard "$2" + ;; verify) [ "$#" -eq 1 ] || usage verify_plan diff --git a/test/scripts/ci_test_package_plan_test.go b/test/scripts/ci_test_package_plan_test.go index 136ce8ec..0d7944f2 100644 --- a/test/scripts/ci_test_package_plan_test.go +++ b/test/scripts/ci_test_package_plan_test.go @@ -14,6 +14,39 @@ func TestCITestPackagePlanCoversDefaultPackagesExactlyOnce(t *testing.T) { if !strings.Contains(output, "default packages exactly once") { t.Fatalf("verify output = %q, want coverage summary", output) } + if !strings.Contains(output, "full-suite packages exactly once") { + t.Fatalf("verify output = %q, want coverage shard plan summary", output) + } +} + +func TestCICoveragePackagePlanRoutesFullSuiteScope(t *testing.T) { + root := testPackagePlanRoot(t) + remaining := strings.Fields(runTestPackagePlan(t, root, "list-coverage", "remaining")) + + for _, suffix := range []string{"/cmd", "/internal/output", "/skills"} { + if !containsPackageSuffix(remaining, suffix) { + t.Errorf("coverage remaining shard does not contain package ending in %q", suffix) + } + } + for _, suffix := range []string{ + "/internal/app", + "/internal/cli", + "/internal/generator", + "/internal/helpers", + "/test/smoke", + "/test/scripts", + "/pkg/cmdutil", + "/scripts/policy/coverage-gate", + } { + if containsPackageSuffix(remaining, suffix) { + t.Errorf("coverage remaining shard unexpectedly contains package ending in %q", suffix) + } + } + + app := strings.Fields(runTestPackagePlan(t, root, "list-coverage", "app")) + if !containsPackageSuffix(app, "/internal/app") { + t.Error("coverage app shard does not contain /internal/app") + } } func TestCITestPackagePlanRoutesPublicTestSuites(t *testing.T) { diff --git a/test/scripts/coverage_workflow_contract_test.go b/test/scripts/coverage_workflow_contract_test.go index a591b93c..84dbb831 100644 --- a/test/scripts/coverage_workflow_contract_test.go +++ b/test/scripts/coverage_workflow_contract_test.go @@ -118,3 +118,97 @@ esac assertDiffProfiles(t, runGate(t, &empty), "coverage.txt") }) } + +// TestCoverageWorkflowShardsAndBaselineCache pins the full-suite coverage +// architecture: the candidate profile is produced by disjoint per-shard +// helper jobs and reassembled before enforcement, and the merge-base profile +// is reused only through an exact-key cache written by a green main push of +// that same commit. Near-miss reuse (restore-keys) would compare the +// candidate against the wrong commit and must never appear. +func TestCoverageWorkflowShardsAndBaselineCache(t *testing.T) { + root, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + t.Fatalf("Abs(repo root) error = %v", err) + } + data, err := os.ReadFile(filepath.Join(root, ".github", "workflows", "ci.yml")) + if err != nil { + t.Fatalf("ReadFile(ci.yml) error = %v", err) + } + admission := string(data) + + currentStart := strings.Index(admission, "\n coverage-current:\n") + fullStart := strings.Index(admission, "\n coverage-current-full:\n") + supportingStart := strings.Index(admission, "\n coverage-supporting:\n") + baselineStart := strings.Index(admission, "\n coverage-baseline:\n") + gateStart := strings.Index(admission, "\n coverage:\n") + policyStart := strings.Index(admission, "\n policy:\n") + if currentStart < 0 || fullStart <= currentStart || supportingStart <= fullStart || + baselineStart <= supportingStart || gateStart <= baselineStart || policyStart <= gateStart { + t.Fatal("CI workflow missing ordered coverage job boundaries") + } + + currentJob := admission[currentStart:fullStart] + if !strings.Contains(currentJob, "needs.lint.outputs.full_suite != 'true'") { + t.Error("coverage-current must be scoped-tier only; the full suite belongs to the shard matrix") + } + if strings.Contains(currentJob, "./ ./cmd/... ./internal/... ./skills/...") { + t.Error("coverage-current must not retain the retired single serial full-suite run") + } + + fullJob := admission[fullStart:supportingStart] + for _, want := range []string{ + "needs.lint.outputs.full_suite == 'true'", + "fail-fast: false", + " - app", + " - cli", + " - generators", + " - helpers", + " - remaining", + `./scripts/ci/test-packages.sh list-coverage "$COVERAGE_SHARD"`, + "go test -count=1 -p 1", + `-coverprofile="coverage-shard-$COVERAGE_SHARD.txt"`, + "-covermode=atomic", + "name: coverage-current-shard-${{ matrix.shard }}", + } { + if !strings.Contains(fullJob, want) { + t.Errorf("coverage-current-full missing shard contract %q", want) + } + } + + baselineJob := admission[baselineStart:gateStart] + baselineKey := "dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }}" + for _, want := range []string{ + "uses: actions/cache/restore@v4", + "uses: actions/cache/save@v4", + "path: coverage-base.txt", + "key: " + baselineKey, + "if: steps.baseline-cache.outputs.cache-hit != 'true'", + } { + if !strings.Contains(baselineJob, want) { + t.Errorf("coverage-baseline missing cache contract %q", want) + } + } + if strings.Count(baselineJob, "key: "+baselineKey) != 2 { + t.Error("coverage-baseline restore and save must use the identical exact cache key") + } + + gateJob := admission[gateStart:policyStart] + for _, want := range []string{ + "pattern: coverage-current-*", + "merge-multiple: true", + "for shard in app cli generators helpers remaining; do", + "test ! -f coverage.txt", + `test "$(head -n 1 "$profile")" = "mode: atomic"`, + "github.event_name == 'push'", + "key: dws-coverage-full-v1-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}", + `"current shards:$CURRENT_FULL_RESULT:$current_full_expected"`, + } { + if !strings.Contains(gateJob, want) { + t.Errorf("coverage gate missing shard assembly contract %q", want) + } + } + + if strings.Contains(admission, "restore-keys") { + t.Error("coverage caches must stay exact-key; prefix restore-keys can resurrect a wrong-commit baseline") + } +} From 42b5004bf890c4077575241b74a5aba89d978379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=9C=E7=8E=84?= Date: Fri, 14 Aug 2026 16:51:52 +0800 Subject: [PATCH 113/250] ci: retrigger pull request checks From ce529c933725f76efbd0e85ac38926ccb8b0bb59 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 14 Aug 2026 09:20:43 +0000 Subject: [PATCH 114/250] chore: update beta formula for v1.0.59-beta.1 [skip ci] --- Formula/dingtalk-workspace-cli-beta.rb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Formula/dingtalk-workspace-cli-beta.rb b/Formula/dingtalk-workspace-cli-beta.rb index 1ee3c02a..98fc206f 100644 --- a/Formula/dingtalk-workspace-cli-beta.rb +++ b/Formula/dingtalk-workspace-cli-beta.rb @@ -1,33 +1,33 @@ class DingtalkWorkspaceCliBeta < Formula desc "Automate DingTalk workspace tasks from the terminal (beta channel)" homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli" - version "1.0.58-beta.6" + version "1.0.59-beta.1" license "Apache-2.0" keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli" on_macos do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-darwin-arm64.tar.gz" - sha256 "8f55497b84113f81b318e087c723016a02eded1cb5784cbd0811fe527d5852ca" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-arm64.tar.gz" + sha256 "36a30f3496e0f759c15c0b09f67dbd23b8ecdfff2eebe572f88125b26485830f" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-darwin-amd64.tar.gz" - sha256 "b1762f1640310fb4100634fe54d9baace46384bb270c59148fe306275554d491" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-amd64.tar.gz" + sha256 "e7a04906380efd8da88cd112e6a512bb6470a3956dc370150037ed6e314db445" end end on_linux do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-arm64.tar.gz" - sha256 "55393310ef0e1f24ea2c0dc22f00c0eb3b343edc2deb18d0db7838cda65af25d" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-arm64.tar.gz" + sha256 "f59ab055f3e841e4cebc964ae3ef969668475548abaaf8bede44afdca9a3e28d" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-linux-amd64.tar.gz" - sha256 "3830f77d09b4da4aa39f0c08d772ff3fa1ffb837eb15bb417f97edbccb073b7d" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-amd64.tar.gz" + sha256 "2c8f919489d958c7d49262615e81faac70a9fbcae2d589ab54a0bb3c5700a057" end end resource "skills" do - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.6/dws-skills.zip" - sha256 "f304a883a4f9e938b26a44692cd5a8d3d8704ba70ee7f33ba7c288434da72b6f" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-skills.zip" + sha256 "25f4a7e1d01fa4d771d79201b34b11ee8a24182bdcdc94bfb98d2bd5845bed3b" end def install From d534ee242c87d5352b3d9a86876aaae5b9027478 Mon Sep 17 00:00:00 2001 From: ruigong Date: Fri, 14 Aug 2026 17:33:54 +0800 Subject: [PATCH 115/250] fix(skill): scope doc/drive descriptions to entity-content vs file management --- .changes/doc-drive-description-scope.md | 5 +++++ skills/multi/dingtalk-doc/SKILL.md | 2 +- skills/multi/dingtalk-drive/SKILL.md | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 .changes/doc-drive-description-scope.md diff --git a/.changes/doc-drive-description-scope.md b/.changes/doc-drive-description-scope.md new file mode 100644 index 00000000..82d47917 --- /dev/null +++ b/.changes/doc-drive-description-scope.md @@ -0,0 +1,5 @@ +--- +category: Changed +--- + +- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior. diff --git a/skills/multi/dingtalk-doc/SKILL.md b/skills/multi/dingtalk-doc/SKILL.md index 7c3b52c6..534cef40 100644 --- a/skills/multi/dingtalk-doc/SKILL.md +++ b/skills/multi/dingtalk-doc/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-doc -description: 钉钉在线文字文档（adoc，「文档空间」里的在线文档）的查找、读取、创建、编辑、块、评论、附件、导入、导出(docx/markdown/pdf)、模板、版本、权限协作及 Markdown/JSONML 写入。文档空间与钉盘的文件管理走 dingtalk-drive（doc 同名原子命令已弃用），知识库空间与空间内节点走 dingtalk-wiki，原生 .md 文件读写走 dingtalk-misc。命令前缀：dws doc。 +description: 钉钉在线文字文档（adoc）本体及其内容的操作：查找、创建、读取、文档信息、编辑、块、评论、附件与媒体、白板卡片、导入、导出(docx/markdown/pdf)、版本、模板、权限、分享及Markdown/JSONML写入。不包括：文档空间与钉盘的文件管理（归 dingtalk-drive，doc 同名原子命令已弃用）、知识库空间与节点管理（归 dingtalk-wiki）、原生 .md 文件读写（归 dingtalk-misc）、电子表格 axls（归 dingtalk-misc）、AI 表格 able（归 dingtalk-aitable）。命令前缀：dws doc。 metadata: cli_version: ">=0.2.14" category: product diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index fb0c3abd..7d2beba4 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-drive -description: 钉钉文件管理（存储层，覆盖钉盘与文档空间两个存储域）。Use when 用户说 钉盘/上传文件/下载文件/文件夹/查文件/找文件/全局搜索文件/复制/移动/重命名/删除/回收站/还原删除文件/权限管理/普通文件下载/本地与钉盘文件夹差异比较/整个文件夹拉到本地/整个文件夹推到钉盘/双向同步；也承接钉钉文档的这些管理动作（doc 侧同名原子命令已弃用）。文档正文编辑与导出 docx/markdown/pdf 走 dingtalk-doc，知识库空间与空间内节点组织走 dingtalk-wiki。命令前缀：dws drive。 +description: 钉钉文件管理（存储层，覆盖钉盘与文档空间两个存储域）。Use when 用户说 钉盘/上传文件/下载文件/文件夹/查文件/找文件/全局搜索文件/最近编辑的文档/复制/移动/重命名/删除/回收站/还原删除文件/文件权限管理/普通文件下载/本地与钉盘文件夹差异比较/整个文件夹拉到本地/整个文件夹推到钉盘/双向同步。对钉钉文档仅处理其作为文件的管理操作，文档本体及其内容操作归 dingtalk-doc；知识库空间与空间内节点组织归 dingtalk-wiki。命令前缀：dws drive。 metadata: cli_version: ">=0.2.14" category: product From 6a2e9dd10e867977846bf1ef3e37febeda2b89f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Fri, 14 Aug 2026 17:41:02 +0800 Subject: [PATCH 116/250] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=AE=A1=E6=89=B9?= =?UTF-8?q?=E9=99=84=E4=BB=B6=E7=9B=B8=E5=85=B3dws=EF=BC=8C=E9=A2=84?= =?UTF-8?q?=E8=A7=88=E6=8E=88=E6=9D=83=E3=80=81=E4=B8=8B=E8=BD=BD=E6=8E=88?= =?UTF-8?q?=E6=9D=83=E3=80=81=E8=8E=B7=E5=8F=96=E4=B8=8B=E8=BD=BD=E9=93=BE?= =?UTF-8?q?=E6=8E=A5=20to=20#666?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...a-attachment-download-url-output-design.md | 55 ++++ .../app/schema_oa_attachment_contract_test.go | 103 +++++++ internal/helpers/oa.go | 9 +- internal/helpers/oa_attachment.go | 268 ++++++++++++++++++ internal/helpers/oa_attachment_test.go | 239 ++++++++++++++++ 5 files changed, 671 insertions(+), 3 deletions(-) create mode 100644 docs/superpowers/specs/2026-08-14-oa-attachment-download-url-output-design.md create mode 100644 internal/app/schema_oa_attachment_contract_test.go create mode 100644 internal/helpers/oa_attachment.go create mode 100644 internal/helpers/oa_attachment_test.go diff --git a/docs/superpowers/specs/2026-08-14-oa-attachment-download-url-output-design.md b/docs/superpowers/specs/2026-08-14-oa-attachment-download-url-output-design.md new file mode 100644 index 00000000..158452fd --- /dev/null +++ b/docs/superpowers/specs/2026-08-14-oa-attachment-download-url-output-design.md @@ -0,0 +1,55 @@ +# OA Attachment Download URL Output Design + +## Goal + +Keep the existing command and MCP request unchanged while making the returned +OSS signed URL directly copyable from JSON output: + +```text +dws oa approval attachment download-url +``` + +## Scope + +Only `oa approval attachment download-url` changes. The other OA attachment +commands and the global JSON formatter retain their current behavior. + +## Design + +The command continues to invoke MCP server `oa`, tool +`get_attachment_download_url`, with the same arguments. Its leaf declaration +provides a command-specific `Call` callback that invokes the existing MCP +dispatcher with HTML escaping disabled when the selected output format is +JSON. This preserves literal `&` separators in `result.downloadUri` instead of +rendering them as `\u0026`. + +For `raw`, `table`, and other non-JSON formats, the callback uses the existing +escaped dispatcher behavior so their current rendering remains unchanged. + +The change does not alter the URL, decode or re-sign it, download the file, or +change global JSON serialization. + +## Error Handling + +Authentication, MCP transport, gateway, PAT, and business errors continue +through the existing dispatcher and retain their current classification and +output behavior. + +## Verification + +Add a `TestCrossPlatformCoverage*` regression test that executes the real Cobra +leaf in explicit JSON mode with a fake MCP result containing a signed URL. It +must verify: + +- the request still targets `oa/get_attachment_download_url`; +- the exact request arguments remain unchanged, including omission of the + optional boolean when the flag was not supplied; +- stdout contains literal `&OSSAccessKeyId=` and `&Signature=`; +- stdout contains no `\u0026` escape. + +The fake caller must report JSON format (or the command must be executed with +`--format json`) so the test fails against the current escaped JSON path rather +than accidentally exercising raw MCP text output. + +Run the focused OA attachment tests, format modified Go files, and rebuild the +CLI. No commit is created. diff --git a/internal/app/schema_oa_attachment_contract_test.go b/internal/app/schema_oa_attachment_contract_test.go new file mode 100644 index 00000000..82d48f04 --- /dev/null +++ b/internal/app/schema_oa_attachment_contract_test.go @@ -0,0 +1,103 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package app + +import ( + "bytes" + "encoding/json" + "strings" + "testing" +) + +func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t *testing.T) { + tests := []struct { + cliPath string + canonical string + rpc string + description string + effect string + }{ + { + cliPath: "oa approval attachment download-url", + canonical: "oa.get_attachment_download_url", + rpc: "get_attachment_download_url", + description: "获取审批附件下载授权并生成临时下载链接", + effect: "read", + }, + { + cliPath: "oa approval attachment authorize-download", + canonical: "oa.auth_download_file", + rpc: "auth_download_file", + description: "批量授权当前用户下载指定的审批钉盘文件", + effect: "write", + }, + { + cliPath: "oa approval attachment authorize-preview", + canonical: "oa.auth_preview_attachment", + rpc: "auth_preview_attachment", + description: "批量授权当前用户预览审批单中的附件", + effect: "write", + }, + } + + root := NewRootCommand() + for _, test := range tests { + t.Run(test.rpc, func(t *testing.T) { + command := exactCommandForTest(root, test.cliPath) + if command == nil { + t.Fatalf("executable command %q is missing", test.cliPath) + } + + var stdout, stderr bytes.Buffer + root.SetOut(&stdout) + root.SetErr(&stderr) + root.SetArgs([]string{"schema", test.cliPath, "--format", "json"}) + if err := root.Execute(); err != nil { + t.Fatalf("execute delivery schema leaf: %v; stderr=%s", err, stderr.String()) + } + + var tool map[string]any + if err := json.Unmarshal(stdout.Bytes(), &tool); err != nil { + t.Fatalf("decode delivery schema leaf: %v", err) + } + if got := schemaContractString(tool["canonical_path"]); got != test.canonical { + t.Fatalf("canonical_path = %q, want %q", got, test.canonical) + } + if got := schemaContractString(tool["primary_cli_path"]); got != test.cliPath { + t.Fatalf("primary_cli_path = %q, want %q", got, test.cliPath) + } + if got := schemaContractString(tool["description"]); !strings.HasPrefix(got, test.description) { + t.Fatalf("description = %q, want prefix %q", got, test.description) + } + if got := schemaContractString(tool["interface_mode"]); got != "mcp" { + t.Fatalf("interface_mode = %q, want mcp", got) + } + if got := schemaContractString(tool["availability"]); got != "available" { + t.Fatalf("availability = %q, want available", got) + } + interfaceRef := schemaInterfaceObject(tool["interface_ref"]) + if got := schemaContractString(interfaceRef["product_id"]); got != "oa" { + t.Fatalf("interface_ref.product_id = %q, want oa", got) + } + if got := schemaContractString(interfaceRef["rpc_name"]); got != test.rpc { + t.Fatalf("interface_ref.rpc_name = %q, want %q", got, test.rpc) + } + if got := schemaContractString(tool["effect"]); got != test.effect { + t.Fatalf("effect = %q, want %q", got, test.effect) + } + if got := schemaContractString(tool["risk"]); got != "low" { + t.Fatalf("risk = %q, want low", got) + } + if got := schemaContractString(tool["confirmation"]); got != "not_required" { + t.Fatalf("confirmation = %q, want not_required", got) + } + if got := schemaContractString(tool["idempotency"]); got != "idempotent" { + t.Fatalf("idempotency = %q, want idempotent", got) + } + if problem := schemaHelpFlagCompletenessProblem(test.canonical, test.cliPath, command, tool); problem != "" { + t.Fatal(problem) + } + }) + } +} diff --git a/internal/helpers/oa.go b/internal/helpers/oa.go index 87413498..3f57cc81 100644 --- a/internal/helpers/oa.go +++ b/internal/helpers/oa.go @@ -49,7 +49,8 @@ func oaFormValues(raw string) ([]map[string]string, error) { // get_processInstance_records, list_initiated_instances, list_pending_tasks, // list_user_visible_process, append_task, search_form, oa_ding_user, revert_task, // get_inst_revert_activities, get_process_schema, forecast_process, -// start_process_instance +// start_process_instance, get_attachment_download_url, auth_download_file, +// auth_preview_attachment // ────────────────────────────────────────────────────────── func newOaCommand() *cobra.Command { @@ -58,9 +59,10 @@ func newOaCommand() *cobra.Command { contract.RegisterProductDecl(contract.ProductDecl{ ID: "oa", Selection: contract.ProductSelectionDecl{ - AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送与评论", + AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送、评论与附件授权", UseWhen: []string{ "查看待审、已办、已发起或抄送审批，并执行同意、拒绝、撤销、转交等审批动作时", + "获取审批附件下载链接，或为当前用户授权下载、预览审批附件时", }, AvoidWhen: []string{ "不要用于普通待办任务或工作日志；需要实时监听未来的审批任务/实例事件时使用 event consume", @@ -70,7 +72,7 @@ func newOaCommand() *cobra.Command { root := &cobra.Command{ Use: "oa", Short: "OA 审批 / 同意 / 拒绝 / 撤销", - Long: `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表。`, + Long: `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表与附件授权。`, RunE: groupRunE, } @@ -1376,6 +1378,7 @@ func newOaCommand() *cobra.Command { approvalForecastCmd, approvalCreateCmd, ) + approvalCmd.AddCommand(newOAAttachmentCommand()) root.AddCommand(approvalCmd) return root diff --git a/internal/helpers/oa_attachment.go b/internal/helpers/oa_attachment.go new file mode 100644 index 00000000..6994d2d6 --- /dev/null +++ b/internal/helpers/oa_attachment.go @@ -0,0 +1,268 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package helpers + +import ( + "encoding/json" + "fmt" + "io" + "strings" + + "github.com/spf13/cobra" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" +) + +func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) { + decoder := json.NewDecoder(strings.NewReader(raw)) + decoder.UseNumber() + var items []map[string]json.RawMessage + if err := decoder.Decode(&items); err != nil { + return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err) + } + if err := rejectTrailingOAAttachmentJSON(decoder); err != nil { + return nil, err + } + if len(items) < 1 || len(items) > 10 { + return nil, fmt.Errorf("--file-infos 必须包含 1 至 10 个文件") + } + + infos := make([]map[string]any, 0, len(items)) + for index, item := range items { + for name := range item { + if name != "spaceId" && name != "fileId" { + return nil, fmt.Errorf("--file-infos 第 %d 项包含未知字段 %q", index+1, name) + } + } + + spaceRaw, ok := item["spaceId"] + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1) + } + spaceDecoder := json.NewDecoder(strings.NewReader(string(spaceRaw))) + spaceDecoder.UseNumber() + var spaceValue any + if err := spaceDecoder.Decode(&spaceValue); err != nil { + return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 不是有效数字: %w", index+1, err) + } + spaceID, ok := spaceValue.(json.Number) + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1) + } + + fileRaw, ok := item["fileId"] + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1) + } + var fileID string + if err := json.Unmarshal(fileRaw, &fileID); err != nil { + return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串: %w", index+1, err) + } + fileID = strings.TrimSpace(fileID) + if fileID == "" { + return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 不能为空", index+1) + } + + infos = append(infos, map[string]any{"spaceId": spaceID, "fileId": fileID}) + } + return infos, nil +} + +func rejectTrailingOAAttachmentJSON(decoder *json.Decoder) error { + var extra any + if err := decoder.Decode(&extra); err != io.EOF { + if err == nil { + return fmt.Errorf("--file-infos JSON 包含多余内容") + } + return fmt.Errorf("--file-infos JSON 解析失败: %w", err) + } + return nil +} + +func validateOAAttachmentFileInfos(cmd *cobra.Command, _ []string) error { + raw, _ := cmd.Flags().GetString("file-infos") + _, err := parseOAAttachmentFileInfos(raw) + return err +} + +func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error { + fileIDs, _ := cmd.Flags().GetStringSlice("file-ids") + if len(fileIDs) > 20 { + return fmt.Errorf("--file-ids 最多包含 20 个附件 ID") + } + for index, fileID := range fileIDs { + if strings.TrimSpace(fileID) == "" { + return fmt.Errorf("--file-ids 第 %d 项不能为空", index+1) + } + } + return nil +} + +func newOAAttachmentCommand() *cobra.Command { + attachmentCmd := &cobra.Command{ + Use: "attachment", + Short: "审批附件授权与下载链接", + RunE: groupRunE, + } + + downloadURLCmd := NewLeafCommand(LeafSpec{ + Use: "download-url", + Short: "获取审批附件下载链接", + Example: " dws oa approval attachment download-url --instance-id --file-id ", + Server: "oa", + Tool: "get_attachment_download_url", + Call: func(_ *cobra.Command, tool string, args map[string]any) error { + jsonOutput := strings.EqualFold(strings.TrimSpace(deps.Caller.Format()), "json") + return callMCPToolInternalOpts("oa", tool, args, jsonOutput) + }, + Flags: []LeafFlag{ + {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, + {Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true}, + {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, + }, + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "get_attachment_download_url", + CanonicalPath: "oa.get_attachment_download_url", + CLIPath: "oa approval attachment download-url", + PrimaryCLIPath: "oa approval attachment download-url", + }, + Description: "获取审批附件下载授权并生成临时下载链接", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_attachment_download_url"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "获取审批实例中指定附件的临时下载链接", + UseWhen: []string{"已从审批详情获得 processInstanceId 和 fileId，需要获取附件下载链接时"}, + AvoidWhen: []string{ + "只需查看审批表单和附件元数据时使用 dws oa approval detail", + "需要将附件真正保存到本地时不要误认为本命令会下载文件；它只返回链接", + }, + Examples: []string{"dws oa approval attachment download-url --instance-id --file-id "}, + }, + Parameters: []contract.ParamDecl{ + {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, + {Name: "file-id", Property: "fileId", InterfaceType: "string"}, + {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, + }, + }, + }) + + authorizeDownloadCmd := NewLeafCommand(LeafSpec{ + Use: "authorize-download", + Short: "授权当前用户下载审批钉盘文件", + Long: "批量授权当前用户下载指定的审批钉盘文件。", + Example: ` dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`, + Server: "oa", + Tool: "auth_download_file", + Flags: []LeafFlag{ + { + Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)", + Bind: "fileInfos", Trim: true, Required: true, MarkRequired: true, + Transform: func(raw string) (any, error) { + return parseOAAttachmentFileInfos(raw) + }, + }, + }, + Constraints: []LeafConstraint{{ + Kind: corecmd.Custom, Flags: []string{"file-infos"}, + Description: "文件信息列表必须包含 1 至 10 项", + }}, + Validate: validateOAAttachmentFileInfos, + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "auth_download_file", + CanonicalPath: "oa.auth_download_file", + CLIPath: "oa approval attachment authorize-download", + PrimaryCLIPath: "oa approval attachment authorize-download", + }, + Description: "批量授权当前用户下载指定的审批钉盘文件", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_download_file"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "使用审批钉盘 spaceId/fileId 批量授权当前用户下载文件", + UseWhen: []string{"已有一个或多个审批钉盘文件的 spaceId 和 fileId，需要为当前用户取得下载权限时"}, + AvoidWhen: []string{ + "需要生成单个审批附件下载链接时使用 attachment download-url", + "需要授权在审批单内预览附件时使用 attachment authorize-preview", + }, + Examples: []string{`dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`}, + }, + Parameters: []contract.ParamDecl{ + {Name: "file-infos", Property: "fileInfos", InterfaceType: "array"}, + }, + }, + }) + + authorizePreviewCmd := NewLeafCommand(LeafSpec{ + Use: "authorize-preview", + Short: "授权当前用户预览审批附件", + Long: "批量授权当前用户预览审批单中的附件。", + Example: " dws oa approval attachment authorize-preview --instance-id --file-ids ,", + Server: "oa", + Tool: "auth_preview_attachment", + Flags: []LeafFlag{ + {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, + {Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true}, + {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, + }, + Constraints: []LeafConstraint{{ + Kind: corecmd.Custom, Flags: []string{"file-ids"}, + Description: "附件 ID 列表最多包含 20 项且每项不能为空", + }}, + Validate: validateOAPreviewFileIDs, + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "auth_preview_attachment", + CanonicalPath: "oa.auth_preview_attachment", + CLIPath: "oa approval attachment authorize-preview", + PrimaryCLIPath: "oa approval attachment authorize-preview", + }, + Description: "批量授权当前用户预览审批单中的附件", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_preview_attachment"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "按审批实例和附件 ID 列表授权当前用户预览附件", + UseWhen: []string{"已有 processInstanceId 和附件 fileId 列表，需要在审批场景中批量取得预览权限时"}, + AvoidWhen: []string{ + "需要下载权限而不是预览权限时使用 attachment authorize-download", + "需要直接获得单个附件临时下载链接时使用 attachment download-url", + }, + Examples: []string{"dws oa approval attachment authorize-preview --instance-id --file-ids ,"}, + }, + Parameters: []contract.ParamDecl{ + {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, + {Name: "file-ids", Property: "fileIdList", InterfaceType: "array"}, + {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, + }, + }, + }) + + attachmentCmd.AddCommand(downloadURLCmd, authorizeDownloadCmd, authorizePreviewCmd) + return attachmentCmd +} diff --git a/internal/helpers/oa_attachment_test.go b/internal/helpers/oa_attachment_test.go new file mode 100644 index 00000000..b17034ef --- /dev/null +++ b/internal/helpers/oa_attachment_test.go @@ -0,0 +1,239 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package helpers + +import ( + "bytes" + "encoding/json" + "io" + "os" + "reflect" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func executeOAAttachmentCommandCapturingOutput(t *testing.T, caller *scriptedToolCaller, args ...string) (string, error) { + t.Helper() + testseam.Protect(t, &deps) + testseam.Swap(t, &os.Args, []string{"dws", "oa"}) + InitDeps(caller) + var stdout bytes.Buffer + deps.Out.w = &stdout + deps.Out.errW = io.Discard + + cmd := newOaCommand() + cmd.PersistentFlags().Bool("yes", false, "跳过确认") + cmd.SilenceErrors = true + cmd.SilenceUsage = true + cmd.SetOut(&stdout) + cmd.SetErr(io.Discard) + cmd.SetArgs(args) + err := cmd.Execute() + return stdout.String(), err +} + +func TestCrossPlatformCoverageOAAttachmentDownloadURLPreservesSignedQuery(t *testing.T) { + const response = `{"result":{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"},"success":true}` + commandArgs := []string{ + "approval", "attachment", "download-url", + "--instance-id", "instance-1", + "--file-id", "file-1", + } + wantArgs := map[string]any{ + "processInstanceId": "instance-1", + "fileId": "file-1", + } + + t.Run("json", func(t *testing.T) { + caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: response}}} + stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...) + if err != nil { + t.Fatalf("execute command: %v", err) + } + if caller.server != "oa" || caller.tool != "get_attachment_download_url" { + t.Fatalf("called %s/%s, want oa/get_attachment_download_url", caller.server, caller.tool) + } + if !reflect.DeepEqual(caller.args, wantArgs) { + t.Fatalf("args = %#v, want %#v", caller.args, wantArgs) + } + if !strings.Contains(stdout, "&OSSAccessKeyId=") || !strings.Contains(stdout, "&Signature=") { + t.Fatalf("stdout does not preserve signed query separators: %q", stdout) + } + if strings.Contains(stdout, `\u0026`) { + t.Fatalf("stdout contains escaped query separator: %q", stdout) + } + }) + + t.Run("raw compatibility", func(t *testing.T) { + caller := &scriptedToolCaller{format: "raw", steps: []scriptedToolStep{{text: response}}} + stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...) + if err != nil { + t.Fatalf("execute command: %v", err) + } + if stdout != response+"\n" { + t.Fatalf("stdout = %q, want %q", stdout, response+"\n") + } + }) +} + +func TestCrossPlatformCoverageOAAttachmentPayloads(t *testing.T) { + tests := []struct { + name string + args []string + wantTool string + check func(*testing.T, map[string]any) + }{ + { + name: "download URL", + args: []string{ + "approval", "attachment", "download-url", + "--instance-id", "instance-1", + "--file-id", "file-1", + "--with-comment-attachment=false", + }, + wantTool: "get_attachment_download_url", + check: func(t *testing.T, got map[string]any) { + t.Helper() + if got["processInstanceId"] != "instance-1" || got["fileId"] != "file-1" { + t.Fatalf("download identifiers = %#v", got) + } + if value, ok := got["withCommentAttachment"].(bool); !ok || value { + t.Fatalf("withCommentAttachment = %#v, want explicit false", got["withCommentAttachment"]) + } + }, + }, + { + name: "download authorization", + args: []string{ + "approval", "attachment", "authorize-download", + "--file-infos", `[{"spaceId":27827223951,"fileId":"file-2"}]`, + }, + wantTool: "auth_download_file", + check: func(t *testing.T, got map[string]any) { + t.Helper() + infos, ok := got["fileInfos"].([]map[string]any) + if !ok || len(infos) != 1 { + t.Fatalf("fileInfos = %#v", got["fileInfos"]) + } + if infos[0]["spaceId"] != json.Number("27827223951") || infos[0]["fileId"] != "file-2" { + t.Fatalf("fileInfos[0] = %#v", infos[0]) + } + }, + }, + { + name: "preview authorization", + args: []string{ + "approval", "attachment", "authorize-preview", + "--instance-id", "instance-2", + "--file-ids", "file-3,file-4", + "--with-comment-attachment", + }, + wantTool: "auth_preview_attachment", + check: func(t *testing.T, got map[string]any) { + t.Helper() + if got["processInstanceId"] != "instance-2" || got["withCommentAttachment"] != true { + t.Fatalf("preview scalar payload = %#v", got) + } + ids, ok := got["fileIdList"].([]string) + if !ok || len(ids) != 2 || ids[0] != "file-3" || ids[1] != "file-4" { + t.Fatalf("fileIdList = %#v", got["fileIdList"]) + } + }, + }, + { + name: "optional boolean omitted", + args: []string{ + "approval", "attachment", "download-url", + "--instance-id", "instance-3", + "--file-id", "file-5", + }, + wantTool: "get_attachment_download_url", + check: func(t *testing.T, got map[string]any) { + t.Helper() + if _, exists := got["withCommentAttachment"]; exists { + t.Fatalf("optional withCommentAttachment should be omitted: %#v", got) + } + }, + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + if err := executeOACommand(t, caller, test.args...); err != nil { + t.Fatalf("execute command: %v", err) + } + if caller.server != "oa" || caller.tool != test.wantTool { + t.Fatalf("called %s/%s, want oa/%s", caller.server, caller.tool, test.wantTool) + } + test.check(t, caller.args) + }) + } +} + +func TestCrossPlatformCoverageOAAttachmentRejectsInvalidFileInfos(t *testing.T) { + valid := `{"spaceId":27827223951,"fileId":"file-1"}` + tests := []struct { + name string + raw string + }{ + {name: "malformed JSON", raw: `[{`}, + {name: "null", raw: `null`}, + {name: "not array", raw: `{}`}, + {name: "empty array", raw: `[]`}, + {name: "more than ten", raw: `[` + strings.Repeat(valid+`,`, 10) + valid + `]`}, + {name: "missing space ID", raw: `[{"fileId":"file-1"}]`}, + {name: "string space ID", raw: `[{"spaceId":"27827223951","fileId":"file-1"}]`}, + {name: "missing file ID", raw: `[{"spaceId":27827223951}]`}, + {name: "blank file ID", raw: `[{"spaceId":27827223951,"fileId":" "}]`}, + {name: "unknown property", raw: `[{"spaceId":27827223951,"fileId":"file-1","extra":true}]`}, + {name: "trailing JSON", raw: `[` + valid + `] {}`}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + err := executeOACommand(t, caller, + "approval", "attachment", "authorize-download", + "--file-infos", test.raw, + ) + if err == nil { + t.Fatalf("fileInfos %q unexpectedly succeeded", test.raw) + } + if caller.calls != 0 { + t.Fatalf("invalid fileInfos made %d MCP call(s)", caller.calls) + } + }) + } +} + +func TestCrossPlatformCoverageOAAttachmentRejectsInvalidPreviewFileIDs(t *testing.T) { + tests := []struct { + name string + raw string + }{ + {name: "separator only", raw: `,`}, + {name: "blank item", raw: `file-1, ,file-2`}, + {name: "more than twenty", raw: strings.Repeat("file,", 20) + "file"}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + err := executeOACommand(t, caller, + "approval", "attachment", "authorize-preview", + "--instance-id", "instance-1", + "--file-ids", test.raw, + ) + if err == nil { + t.Fatalf("file IDs %q unexpectedly succeeded", test.raw) + } + if caller.calls != 0 { + t.Fatalf("invalid file IDs made %d MCP call(s)", caller.calls) + } + }) + } +} From abe512930649ea46a7a93076256674e4d896e6de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Fri, 14 Aug 2026 17:56:51 +0800 Subject: [PATCH 117/250] fix(event): support Windows bus lifecycle --- .changes/windows-event-bus-lifecycle.md | 5 + internal/app/event_command.go | 3 +- internal/app/event_personal_command.go | 2 +- internal/event/bus/coverage_edges_test.go | 11 +- internal/event/bus/daemon.go | 21 ++-- internal/event/bus/daemon_test.go | 61 +++++++++++ internal/event/busctl/discover.go | 5 +- internal/event/busctl/discover_test.go | 5 +- internal/event/busctl/spawn.go | 29 +++--- internal/event/busctl/spawn_test.go | 25 ++++- internal/event/busctl/spawn_unix.go | 7 ++ internal/event/busctl/spawn_windows.go | 87 ++++++++++++++++ internal/event/busctl/spawn_windows_test.go | 108 ++++++++++++++++++++ internal/event/busctl/stop.go | 83 +++++++++++---- internal/event/busctl/stop_test.go | 84 +++++++++++++++ internal/event/busctl/stop_windows.go | 9 +- internal/event/busctl/stop_windows_test.go | 27 +++++ 17 files changed, 517 insertions(+), 55 deletions(-) create mode 100644 .changes/windows-event-bus-lifecycle.md create mode 100644 internal/event/busctl/spawn_windows_test.go create mode 100644 internal/event/busctl/stop_windows_test.go diff --git a/.changes/windows-event-bus-lifecycle.md b/.changes/windows-event-bus-lifecycle.md new file mode 100644 index 00000000..f158d0ad --- /dev/null +++ b/.changes/windows-event-bus-lifecycle.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails. diff --git a/internal/app/event_command.go b/internal/app/event_command.go index 533c95a3..f0cc1e24 100644 --- a/internal/app/event_command.go +++ b/internal/app/event_command.go @@ -1220,7 +1220,8 @@ func newEventStopCommandWithFlags(globalFlags ...*GlobalFlags) *cobra.Command { editionName := editionNameOrDefault() clientIDHash := dwsevent.ClientIDHash(clientID) workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindAppStream, clientIDHash) - if err := eventStopBus(busctl.StopConfig{WorkDir: workDir}); err != nil { + ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindAppStream, clientIDHash) + if err := eventStopBus(busctl.StopConfig{WorkDir: workDir, IPCEndpoint: ipcEndpoint}); err != nil { if errors.Is(err, busctl.ErrNotRunning) { fmt.Fprintln(c.OutOrStdout(), "bus is not running") return nil diff --git a/internal/app/event_personal_command.go b/internal/app/event_personal_command.go index b2b1dc03..20ff6207 100644 --- a/internal/app/event_personal_command.go +++ b/internal/app/event_personal_command.go @@ -1220,7 +1220,7 @@ func runPersonalEventStop(c *cobra.Command, opts personalStopOptions) error { } busState := "personal bus stopped" - if err := personalStopBus(busctl.StopConfig{WorkDir: workDir}); err != nil { + if err := personalStopBus(busctl.StopConfig{WorkDir: workDir, IPCEndpoint: ipcEndpoint}); err != nil { if errors.Is(err, busctl.ErrNotRunning) { busState = "personal bus is not running" } else { diff --git a/internal/event/bus/coverage_edges_test.go b/internal/event/bus/coverage_edges_test.go index 8086e4d7..ea0f9cbb 100644 --- a/internal/event/bus/coverage_edges_test.go +++ b/internal/event/bus/coverage_edges_test.go @@ -361,13 +361,18 @@ func TestCrossPlatformCoverageDaemonMethodEdges(t *testing.T) { } return nil, net.ErrClosed }} - d := &daemon{listener: l, log: logger, hub: NewHub(1), idleStop: make(chan struct{})} + d := &daemon{listener: l, log: logger, hub: NewHub(1), idleStop: make(chan struct{}), stopReq: make(chan string, 1)} d.acceptLoop(context.Background()) d.shuttingDown.Store(true) d.acceptLoop(context.Background()) d.triggerShutdown("test") - if !l.closed { - t.Fatal("trigger did not close listener") + select { + case reason := <-d.stopReq: + if reason != "test" { + t.Fatalf("stop reason = %q", reason) + } + default: + t.Fatal("trigger did not notify lifecycle loop") } d = &daemon{listener: &scriptedListener{accept: func() (net.Conn, error) { return nil, net.ErrClosed }}, log: logger, hub: NewHub(1), idleStop: make(chan struct{})} diff --git a/internal/event/bus/daemon.go b/internal/event/bus/daemon.go index 7fac9aff..0c43d908 100644 --- a/internal/event/bus/daemon.go +++ b/internal/event/bus/daemon.go @@ -186,6 +186,7 @@ func Run(ctx context.Context, cfg Config) error { dedup: dd, started: time.Now().UTC(), idleStop: make(chan struct{}), + stopReq: make(chan string, 1), } // 4. Signal ready BEFORE accepting consumers (avoids a slow-fork @@ -263,6 +264,9 @@ func Run(ctx context.Context, cfg Config) error { } case <-d.idleStop: log.Info("bus: idle timeout reached, shutting down") + case reason := <-d.stopReq: + shutdownReason = reason + log.Info("bus: shutdown requested via IPC", "reason", reason) } // 7. Graceful shutdown — cancel runCtx first so all background @@ -292,6 +296,7 @@ type daemon struct { shutdownMu sync.Mutex shuttingDown atomic.Bool idleStop chan struct{} + stopReq chan string credentialHandoffMu sync.Mutex terminalMu sync.RWMutex @@ -749,15 +754,17 @@ func (d *daemon) idleWatch(ctx context.Context) { } } -// triggerShutdown is called from RPC handlers that want to end the bus. -// It works by closing the listener (which unblocks Run's select via the -// source error path, indirectly). For v1 a full ctx-cancellation hook is -// out of scope; busctl/stop also sends SIGTERM which is the authoritative -// shutdown path. +// triggerShutdown is called from RPC handlers that want to end the bus. The +// buffered request wakes Run's lifecycle select, which then cancels the cloud +// source and performs the same graceful shutdown used for signals and idle +// expiry. It is intentionally non-blocking so repeated stop requests cannot +// strand connection handlers. func (d *daemon) triggerShutdown(reason string) { d.log.Info("bus: shutdown triggered via IPC", "reason", reason) - _ = d.listener.Close() // unblocks Accept(), but doesn't kill Source - // Best-effort: a future version wires a context.CancelFunc here. + select { + case d.stopReq <- reason: + default: + } } // shutdown performs the graceful tear-down sequence: diff --git a/internal/event/bus/daemon_test.go b/internal/event/bus/daemon_test.go index 49a46d20..d99e4aa7 100644 --- a/internal/event/bus/daemon_test.go +++ b/internal/event/bus/daemon_test.go @@ -141,6 +141,67 @@ func TestDaemon_RunStartsAndShutsDownCleanly(t *testing.T) { } } +func TestCrossPlatformCoverageDaemonIPCStopShutsDownCleanly(t *testing.T) { + workDir := shortTempDir(t) + identityHash := dwsevent.IdentityHash(workDir) + endpoint := dwsevent.IPCEndpoint(workDir, "open", dwsevent.SourceKindAppStream, identityHash) + runDone := make(chan error, 1) + go func() { + runDone <- Run(context.Background(), Config{ + WorkDir: workDir, + IPCEndpoint: endpoint, + ClientID: "ding_ipc_stop_test", + Edition: "open", + SourceKind: dwsevent.SourceKindAppStream, + IdentityHash: identityHash, + Source: &fakeSource{}, + }) + }() + + var conn net.Conn + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + var err error + conn, err = transport.Dial(endpoint) + if err == nil { + break + } + time.Sleep(10 * time.Millisecond) + } + if conn == nil { + t.Fatal("bus IPC endpoint did not become ready") + } + w := transport.NewWriter(conn) + r := transport.NewReader(conn) + if err := w.WriteJSON(transport.Hello{ + Type: transport.FrameTypeHello, + ConsumerPID: os.Getpid(), + Role: transport.HelloRoleStop, + }); err != nil { + t.Fatalf("write stop hello: %v", err) + } + var bye transport.Bye + if err := r.ReadJSON(&bye); err != nil { + t.Fatalf("read stop response: %v", err) + } + _ = conn.Close() + if bye.Type != transport.FrameTypeBye || bye.Reason != "stop_request" { + t.Fatalf("stop response = %#v", bye) + } + + select { + case err := <-runDone: + if err != nil { + t.Fatalf("Run returned after IPC stop: %v", err) + } + case <-time.After(3 * time.Second): + t.Fatal("Run did not return after IPC stop") + } + if pid := ReadHolderPID(filepath.Join(workDir, LockFileName)); pid != 0 { + t.Fatalf("bus lock retained pid %d after IPC stop", pid) + } +} + func TestDaemon_ConsumerReceivesEvents(t *testing.T) { skipOnWindows(t, "uses Unix socket dial") workDir := shortTempDir(t) diff --git a/internal/event/busctl/discover.go b/internal/event/busctl/discover.go index 2bbbb863..56fd1c64 100644 --- a/internal/event/busctl/discover.go +++ b/internal/event/busctl/discover.go @@ -112,8 +112,9 @@ func Discover(cfg DiscoverConfig) (net.Conn, error) { return nil, fmt.Errorf("busctl: mkdir workdir: %w", err) } _, spawnErr := cfg.Spawn(SpawnConfig{ - ClientID: cfg.ClientID, - ExtraArgs: cfg.SpawnExtraArgs, + ClientID: cfg.ClientID, + IPCEndpoint: cfg.IPCEndpoint, + ExtraArgs: cfg.SpawnExtraArgs, }) if spawnErr != nil && !errors.Is(spawnErr, ErrSpawnFailed) { // Hard error (couldn't even exec the child). Stop here — no bus diff --git a/internal/event/busctl/discover_test.go b/internal/event/busctl/discover_test.go index a4b42bcb..7e2e2dbc 100644 --- a/internal/event/busctl/discover_test.go +++ b/internal/event/busctl/discover_test.go @@ -122,7 +122,10 @@ func TestDiscover_NoBus_SpawnSucceeds(t *testing.T) { closer() } }) - fakeSpawn := func(SpawnConfig) (int, error) { + fakeSpawn := func(cfg SpawnConfig) (int, error) { + if cfg.IPCEndpoint != sock { + t.Fatalf("spawn IPC endpoint = %q, want %q", cfg.IPCEndpoint, sock) + } closer = startStubBus(t, sock) return 12345, nil } diff --git a/internal/event/busctl/spawn.go b/internal/event/busctl/spawn.go index 5c3c589f..f3b89165 100644 --- a/internal/event/busctl/spawn.go +++ b/internal/event/busctl/spawn.go @@ -43,18 +43,14 @@ var ( spawnPipe = os.Pipe ) -// ErrSpawnFailed is returned when the child reports startup failure via -// the ready pipe ('E' byte). The child's exit error / log file holds the -// actual cause; this sentinel just lets the caller distinguish "ready -// pipe said no" from "ready pipe timed out / closed early". -var ErrSpawnFailed = errors.New("busctl: bus child reported startup failure on ready pipe") +// ErrSpawnFailed is returned when the child reports startup failure through +// the Unix ready pipe or exits before binding the Windows named pipe. +var ErrSpawnFailed = errors.New("busctl: bus child reported startup failure") // ErrSpawnTimeout is returned when ReadyTimeout elapses without any signal. var ErrSpawnTimeout = errors.New("busctl: bus child did not signal readiness within deadline") -// SpawnConfig describes one spawn attempt. ClientID is the only field -// inspected by the child; the rest govern process attributes the parent -// applies before exec. +// SpawnConfig describes one spawn attempt. type SpawnConfig struct { // ExecPath is the dws binary to exec. Default os.Executable(). ExecPath string @@ -62,18 +58,23 @@ type SpawnConfig struct { // ClientID is passed as `--client-id` to `dws event _bus`. Required. ClientID string + // IPCEndpoint is the bus endpoint the child binds. Windows uses the + // existing named pipe as its readiness handshake because os/exec does not + // support ExtraFiles there. Unix keeps the inherited ready-pipe protocol. + IPCEndpoint string + // ExtraArgs are appended after `--client-id`. Empty for normal use; tests // pass `--extra-flag-for-test` etc. ExtraArgs []string - // Env to pass to the child. Defaults to os.Environ(). The ReadyFDEnv - // entry is appended automatically. + // Env to pass to the child. Defaults to os.Environ(). Unix appends the + // ReadyFDEnv entry automatically; Windows removes any inherited copy. Env []string } -// Spawn forks a detached `dws event _bus --client-id ` child process and -// waits for it to signal readiness via the ready pipe. Returns the child's -// PID on success — the caller can then dial the bus IPC endpoint. +// spawnWithReadyPipe is the Unix implementation behind Spawn. It forks a +// detached `dws event _bus --client-id ` child and waits for the inherited +// ready pipe. Windows has a named-pipe implementation in spawn_windows.go. // // stdio detach (plan invariant #7): // - cmd.Stdout / cmd.Stderr set to nil so the child's own writes don't @@ -89,7 +90,7 @@ type SpawnConfig struct { // Parent (this function): // - Holds the read end open until either 1 byte is read or ReadyTimeout // - Returns ErrSpawnFailed for 'E', ErrSpawnTimeout otherwise -func Spawn(cfg SpawnConfig) (pid int, err error) { +func spawnWithReadyPipe(cfg SpawnConfig) (pid int, err error) { if cfg.ClientID == "" { return 0, errors.New("busctl: SpawnConfig.ClientID is required") } diff --git a/internal/event/busctl/spawn_test.go b/internal/event/busctl/spawn_test.go index 42a1c532..dc931700 100644 --- a/internal/event/busctl/spawn_test.go +++ b/internal/event/busctl/spawn_test.go @@ -22,6 +22,8 @@ import ( "strings" "testing" "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport" ) // Test child mode: when DWS_BUSCTL_TEST_CHILD is set, this test binary @@ -35,7 +37,8 @@ import ( // env-marker pattern is what Go's own os/exec tests use and stays // confined to this file. const ( - childEnvMarker = "DWS_BUSCTL_TEST_CHILD" + childEnvMarker = "DWS_BUSCTL_TEST_CHILD" + childEndpointEnv = "DWS_BUSCTL_TEST_ENDPOINT" // values: // "ready" — write 'R' then sleep 30s (parent should see ready) // "fail" — write 'E' then exit (parent should see ErrSpawnFailed) @@ -70,6 +73,26 @@ func TestMain(m *testing.M) { writeReady('R') time.Sleep(30 * time.Second) os.Exit(0) + case "windows-ready": + listener, err := transport.Listen(os.Getenv(childEndpointEnv)) + if err != nil { + os.Exit(3) + } + defer listener.Close() + conn, err := listener.Accept() + if err != nil { + os.Exit(4) + } + _ = conn.Close() + time.Sleep(30 * time.Second) + os.Exit(0) + case "windows-fail": + os.Exit(5) + case "windows-exit": + os.Exit(0) + case "windows-stall": + time.Sleep(30 * time.Second) + os.Exit(0) } os.Exit(m.Run()) } diff --git a/internal/event/busctl/spawn_unix.go b/internal/event/busctl/spawn_unix.go index b568c524..d882808c 100644 --- a/internal/event/busctl/spawn_unix.go +++ b/internal/event/busctl/spawn_unix.go @@ -20,6 +20,13 @@ import ( "syscall" ) +// Spawn starts the detached bus and waits for its inherited ready pipe. +// ExtraFiles is intentionally confined to Unix: Go does not support it on +// Windows. +func Spawn(cfg SpawnConfig) (pid int, err error) { + return spawnWithReadyPipe(cfg) +} + // applyDetach configures the child to live past parent death and not share // the parent's controlling terminal. Setsid puts the child in a new // session, so SIGHUP on the parent's controlling tty (e.g. SSH disconnect) diff --git a/internal/event/busctl/spawn_windows.go b/internal/event/busctl/spawn_windows.go index ee0174b1..1cdf6958 100644 --- a/internal/event/busctl/spawn_windows.go +++ b/internal/event/busctl/spawn_windows.go @@ -16,14 +16,101 @@ package busctl import ( + "fmt" + "os" "os/exec" + "strings" "syscall" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport" ) // CREATE_NEW_PROCESS_GROUP (0x00000200) prevents the child from receiving // the parent's Ctrl+C signal, similar in spirit to Setsid on Unix. const createNewProcessGroup = 0x00000200 +var ( + spawnWindowsDial = transport.Dial + spawnWindowsPollInterval = 25 * time.Millisecond +) + +// Spawn starts a detached Windows bus without cmd.ExtraFiles (unsupported by +// Go on Windows). Readiness is confirmed by dialing the bus's existing named +// pipe. The child is reaped in the background after readiness, while an early +// process exit is surfaced as ErrSpawnFailed. +func Spawn(cfg SpawnConfig) (pid int, err error) { + if strings.TrimSpace(cfg.ClientID) == "" { + return 0, fmt.Errorf("busctl: SpawnConfig.ClientID is required") + } + if strings.TrimSpace(cfg.IPCEndpoint) == "" { + return 0, fmt.Errorf("busctl: SpawnConfig.IPCEndpoint is required on Windows") + } + if cfg.ExecPath == "" { + execPath, err := spawnExecutable() + if err != nil { + return 0, fmt.Errorf("busctl: locate executable: %w", err) + } + cfg.ExecPath = execPath + } + if cfg.Env == nil { + cfg.Env = os.Environ() + } + + args := append([]string{"event", "_bus", "--client-id", cfg.ClientID}, cfg.ExtraArgs...) + cmd := exec.Command(cfg.ExecPath, args...) + cmd.Env = withoutReadyFDEnv(cfg.Env) + cmd.Stdin = nil + cmd.Stdout = nil + cmd.Stderr = nil + applyDetach(cmd) + if err := cmd.Start(); err != nil { + return 0, fmt.Errorf("busctl: start %s: %w", cfg.ExecPath, err) + } + pid = cmd.Process.Pid + + waitDone := make(chan error, 1) + go func() { waitDone <- cmd.Wait() }() + timer := time.NewTimer(ReadyTimeout) + defer timer.Stop() + ticker := time.NewTicker(spawnWindowsPollInterval) + defer ticker.Stop() + + for { + if conn, dialErr := spawnWindowsDial(cfg.IPCEndpoint); dialErr == nil { + _ = conn.Close() + return pid, nil + } + select { + case waitErr := <-waitDone: + if waitErr == nil { + return pid, fmt.Errorf("%w: child exited before binding named pipe", ErrSpawnFailed) + } + return pid, fmt.Errorf("%w: %v", ErrSpawnFailed, waitErr) + case <-timer.C: + _ = cmd.Process.Kill() + select { + case <-waitDone: + case <-time.After(time.Second): + } + return pid, ErrSpawnTimeout + case <-ticker.C: + } + } +} + +func withoutReadyFDEnv(env []string) []string { + prefix := strings.ToUpper(ReadyFDEnv) + "=" + out := make([]string, 0, len(env)) + for _, entry := range env { + if strings.HasPrefix(strings.ToUpper(entry), prefix) { + continue + } + out = append(out, entry) + } + return out +} + func applyDetach(cmd *exec.Cmd) { cmd.SysProcAttr = &syscall.SysProcAttr{ CreationFlags: createNewProcessGroup, diff --git a/internal/event/busctl/spawn_windows_test.go b/internal/event/busctl/spawn_windows_test.go new file mode 100644 index 00000000..1eeafc4a --- /dev/null +++ b/internal/event/busctl/spawn_windows_test.go @@ -0,0 +1,108 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//go:build windows + +package busctl + +import ( + "errors" + "fmt" + "os" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageWindowsSpawnUsesNamedPipeReadiness(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-test-%d-%d`, os.Getpid(), time.Now().UnixNano()) + pid, err := spawnWithMarker(t, "windows-ready", func(cfg *SpawnConfig) { + cfg.IPCEndpoint = endpoint + cfg.Env = append(cfg.Env, childEndpointEnv+"="+endpoint) + }) + if err != nil { + t.Fatalf("Spawn() = %v", err) + } + if pid <= 0 { + t.Fatalf("Spawn() pid = %d", pid) + } + proc, err := os.FindProcess(pid) + if err != nil { + t.Fatal(err) + } + _ = proc.Kill() +} + +func TestCrossPlatformCoverageWindowsSpawnReportsEarlyExit(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-fail-%d-%d`, os.Getpid(), time.Now().UnixNano()) + _, err := spawnWithMarker(t, "windows-fail", func(cfg *SpawnConfig) { + cfg.IPCEndpoint = endpoint + }) + if !errors.Is(err, ErrSpawnFailed) { + t.Fatalf("Spawn() error = %v, want ErrSpawnFailed", err) + } +} + +func TestCrossPlatformCoverageWindowsSpawnReportsCleanEarlyExit(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-exit-%d-%d`, os.Getpid(), time.Now().UnixNano()) + _, err := spawnWithMarker(t, "windows-exit", func(cfg *SpawnConfig) { + cfg.IPCEndpoint = endpoint + }) + if !errors.Is(err, ErrSpawnFailed) { + t.Fatalf("Spawn() error = %v, want ErrSpawnFailed", err) + } +} + +func TestCrossPlatformCoverageWindowsSpawnValidationAndStartErrors(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-errors-%d-%d`, os.Getpid(), time.Now().UnixNano()) + if _, err := Spawn(SpawnConfig{ClientID: "client"}); err == nil { + t.Fatal("missing endpoint unexpectedly succeeded") + } + testseam.Swap(t, &spawnExecutable, func() (string, error) { + return "", errors.New("executable unavailable") + }) + if _, err := Spawn(SpawnConfig{ClientID: "client", IPCEndpoint: endpoint}); err == nil { + t.Fatal("executable lookup unexpectedly succeeded") + } + if _, err := Spawn(SpawnConfig{ + ClientID: "client", + IPCEndpoint: endpoint, + ExecPath: `C:\\definitely-missing-dws.exe`, + }); err == nil { + t.Fatal("missing executable unexpectedly started") + } +} + +func TestCrossPlatformCoverageWindowsSpawnReadyTimeoutTerminatesChild(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-stall-%d-%d`, os.Getpid(), time.Now().UnixNano()) + testseam.Swap(t, &ReadyTimeout, 100*time.Millisecond) + _, err := spawnWithMarker(t, "windows-stall", func(cfg *SpawnConfig) { + cfg.IPCEndpoint = endpoint + }) + if !errors.Is(err, ErrSpawnTimeout) { + t.Fatalf("Spawn() error = %v, want ErrSpawnTimeout", err) + } +} + +func TestCrossPlatformCoverageWindowsSpawnRemovesInheritedReadyFD(t *testing.T) { + env := withoutReadyFDEnv([]string{ + "PATH=C:\\Windows", + ReadyFDEnv + "=3", + strings.ToLower(ReadyFDEnv) + "=4", + }) + if len(env) != 1 || !strings.HasPrefix(env[0], "PATH=") { + t.Fatalf("withoutReadyFDEnv() = %#v", env) + } +} diff --git a/internal/event/busctl/stop.go b/internal/event/busctl/stop.go index 8b9bbdb1..c68ebfcd 100644 --- a/internal/event/busctl/stop.go +++ b/internal/event/busctl/stop.go @@ -17,15 +17,17 @@ import ( "errors" "fmt" "os" + "strings" "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/process" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport" ) -// DefaultStopTimeout is the wall-clock budget Stop waits for the bus to -// exit after the signal is sent. 5s covers the bus's own graceful tear-down -// (broadcast Bye → consumer goroutines drain → cleanup) with margin. +// DefaultStopTimeout is the wall-clock budget Stop waits for each graceful or +// fallback termination phase. 5s covers the bus's own tear-down (broadcast +// Bye → consumer goroutines drain → cleanup) with margin. const DefaultStopTimeout = 5 * time.Second // ErrNotRunning indicates bus.lock either does not exist or its recorded @@ -38,15 +40,19 @@ var ( stopAlive = process.Alive stopFindProcess = os.FindProcess stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) } + stopRequest = requestBusStop ) // StopConfig identifies the target bus and tunes timing. type StopConfig struct { // WorkDir holds bus.lock; Stop reads the PID from there. WorkDir string - // Timeout is the total wall-clock budget for graceful exit. After this, - // Stop returns an error; it does NOT escalate to SIGKILL — leave that - // to the operator. + // IPCEndpoint enables the cross-platform graceful stop RPC. Callers that + // know the bus identity should always provide it. Empty preserves the + // legacy signal-only fallback for compatibility and focused tests. + IPCEndpoint string + // Timeout is the wall-clock budget for graceful exit and, if required, + // the subsequent platform termination fallback. Timeout time.Duration } @@ -54,13 +60,12 @@ type StopConfig struct { // for the process to actually die. Returns ErrNotRunning if no bus is // running for that work dir. // -// Implementation note: on Unix we send SIGTERM. The bus daemon's Run loop -// watches its parent ctx for cancellation; the cobra `event _bus` command -// wires signal.NotifyContext so SIGTERM triggers ctx.Done() → graceful -// shutdown path. On Windows we use os.Process.Signal(os.Interrupt) which -// the Go runtime maps to TerminateProcess for processes outside our -// console group; for v1 that's acceptable (Windows graceful shutdown is -// future work — plan §16 v2). +// Stop first asks the bus to shut down through its owner-only IPC endpoint. +// This is the normal path on every platform and lets the daemon cancel its +// cloud source, notify consumers, and release its lock. If the endpoint is +// unavailable (for example an older bus) or graceful shutdown times out, the +// platform signal is used as a compatibility fallback: SIGTERM on Unix and +// TerminateProcess via os.Kill on Windows. func Stop(cfg StopConfig) error { if cfg.WorkDir == "" { return errors.New("busctl: StopConfig.WorkDir is required") @@ -81,6 +86,12 @@ func Stop(cfg StopConfig) error { if err != nil { return fmt.Errorf("busctl: find process %d: %w", pid, err) } + if strings.TrimSpace(cfg.IPCEndpoint) != "" { + if err := stopRequest(cfg.IPCEndpoint); err == nil && waitForBusExit(pid, cfg.Timeout) { + return nil + } + } + if err := stopSignalProcess(proc, stopSignal()); err != nil { // On many Unix platforms Signal returns "process already finished" // when the bus has just exited on its own — treat that as success. @@ -90,13 +101,45 @@ func Stop(cfg StopConfig) error { return fmt.Errorf("busctl: signal bus pid=%d: %w", pid, err) } - // Poll for actual exit. - deadline := time.Now().Add(cfg.Timeout) - for time.Now().Before(deadline) { - if !stopAlive(pid) { - return nil - } - time.Sleep(50 * time.Millisecond) + if waitForBusExit(pid, cfg.Timeout) { + return nil } return fmt.Errorf("busctl: bus pid=%d did not exit within %s", pid, cfg.Timeout) } + +func requestBusStop(endpoint string) error { + conn, err := transport.Dial(endpoint) + if err != nil { + return fmt.Errorf("busctl: dial bus for stop: %w", err) + } + defer conn.Close() + _ = conn.SetDeadline(time.Now().Add(DefaultStatusRPCTimeout)) + w := transport.NewWriter(conn) + r := transport.NewReader(conn) + if err := w.WriteJSON(transport.Hello{ + Type: transport.FrameTypeHello, + ConsumerPID: os.Getpid(), + Role: transport.HelloRoleStop, + }); err != nil { + return fmt.Errorf("busctl: write stop hello: %w", err) + } + var bye transport.Bye + if err := r.ReadJSON(&bye); err != nil { + return fmt.Errorf("busctl: read stop response: %w", err) + } + if bye.Type != transport.FrameTypeBye || bye.Reason != "stop_request" { + return fmt.Errorf("busctl: unexpected stop response type=%q reason=%q", bye.Type, bye.Reason) + } + return nil +} + +func waitForBusExit(pid int, timeout time.Duration) bool { + deadline := time.Now().Add(timeout) + for time.Now().Before(deadline) { + if !stopAlive(pid) { + return true + } + time.Sleep(50 * time.Millisecond) + } + return !stopAlive(pid) +} diff --git a/internal/event/busctl/stop_test.go b/internal/event/busctl/stop_test.go index e4cd99de..2a80d01e 100644 --- a/internal/event/busctl/stop_test.go +++ b/internal/event/busctl/stop_test.go @@ -23,7 +23,10 @@ import ( "testing" "time" + dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) func TestStop_NotRunningWhenLockMissing(t *testing.T) { @@ -46,6 +49,87 @@ func TestStop_NotRunningWhenPIDDead(t *testing.T) { } } +func TestCrossPlatformCoverageStopPrefersGracefulIPC(t *testing.T) { + const pid = 4242 + stopped := false + signals := 0 + testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid }) + testseam.Swap(t, &stopAlive, func(int) bool { return !stopped }) + proc, err := os.FindProcess(os.Getpid()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil }) + testseam.Swap(t, &stopRequest, func(endpoint string) error { + if endpoint != "test-endpoint" { + t.Fatalf("stop endpoint = %q", endpoint) + } + stopped = true + return nil + }) + testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error { + signals++ + return nil + }) + + if err := Stop(StopConfig{ + WorkDir: "test-workdir", + IPCEndpoint: "test-endpoint", + Timeout: time.Second, + }); err != nil { + t.Fatalf("Stop() = %v", err) + } + if signals != 0 { + t.Fatalf("graceful IPC stop used %d process signals", signals) + } +} + +func TestCrossPlatformCoverageRequestBusStopProtocol(t *testing.T) { + dir := shortTempDir(t) + endpoint := dwsevent.IPCEndpoint( + dir, + "open", + dwsevent.SourceKindAppStream, + dwsevent.IdentityHash(dir), + ) + listener, err := transport.Listen(endpoint) + if err != nil { + t.Fatalf("Listen() = %v", err) + } + defer listener.Close() + serverDone := make(chan error, 1) + go func() { + conn, err := listener.Accept() + if err != nil { + serverDone <- err + return + } + defer conn.Close() + r := transport.NewReader(conn) + w := transport.NewWriter(conn) + var hello transport.Hello + if err := r.ReadJSON(&hello); err != nil { + serverDone <- err + return + } + if hello.Type != transport.FrameTypeHello || hello.Role != transport.HelloRoleStop { + serverDone <- errors.New("unexpected stop hello") + return + } + serverDone <- w.WriteJSON(transport.Bye{ + Type: transport.FrameTypeBye, + Reason: "stop_request", + }) + }() + + if err := requestBusStop(endpoint); err != nil { + t.Fatalf("requestBusStop() = %v", err) + } + if err := <-serverDone; err != nil { + t.Fatalf("stop protocol server = %v", err) + } +} + func TestStop_SignalsLiveProcess(t *testing.T) { skipOnWindows(t) dir := shortTempDir(t) diff --git a/internal/event/busctl/stop_windows.go b/internal/event/busctl/stop_windows.go index 2e7223f6..630ee330 100644 --- a/internal/event/busctl/stop_windows.go +++ b/internal/event/busctl/stop_windows.go @@ -17,8 +17,7 @@ package busctl import "os" -// stopSignal returns the graceful-shutdown signal for Windows. The Go -// runtime maps os.Interrupt to TerminateProcess for non-console-group -// processes — not truly graceful, but acceptable for v1 (Windows graceful -// shutdown via Ctrl+Break is in the v2 backlog, plan §16). -func stopSignal() os.Signal { return os.Interrupt } +// stopSignal is only the fallback after the graceful IPC stop path fails or +// times out. Go maps os.Kill to TerminateProcess on Windows; os.Interrupt is +// unsupported and returns syscall.EWINDOWS. +func stopSignal() os.Signal { return os.Kill } diff --git a/internal/event/busctl/stop_windows_test.go b/internal/event/busctl/stop_windows_test.go new file mode 100644 index 00000000..fcdc94aa --- /dev/null +++ b/internal/event/busctl/stop_windows_test.go @@ -0,0 +1,27 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//go:build windows + +package busctl + +import ( + "os" + "testing" +) + +func TestCrossPlatformCoverageWindowsStopFallbackUsesKill(t *testing.T) { + if stopSignal() != os.Kill { + t.Fatalf("stopSignal() = %v, want os.Kill", stopSignal()) + } +} From f68a11f11db452d34ad8876e8b7e414c63632c6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Fri, 14 Aug 2026 18:05:34 +0800 Subject: [PATCH 118/250] test(event): cover Windows lifecycle edges --- internal/event/busctl/spawn_windows_test.go | 18 ++++++ internal/event/busctl/stop.go | 3 +- internal/event/busctl/stop_test.go | 61 ++++++++++++++++++++- 3 files changed, 80 insertions(+), 2 deletions(-) diff --git a/internal/event/busctl/spawn_windows_test.go b/internal/event/busctl/spawn_windows_test.go index 1eeafc4a..22d38be2 100644 --- a/internal/event/busctl/spawn_windows_test.go +++ b/internal/event/busctl/spawn_windows_test.go @@ -65,6 +65,24 @@ func TestCrossPlatformCoverageWindowsSpawnReportsCleanEarlyExit(t *testing.T) { } } +func TestCrossPlatformCoverageWindowsSpawnResolvesExecutable(t *testing.T) { + endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-resolve-%d-%d`, os.Getpid(), time.Now().UnixNano()) + testseam.Swap(t, &spawnExecutable, func() (string, error) { return os.Args[0], nil }) + pid, err := spawnWithMarker(t, "windows-ready", func(cfg *SpawnConfig) { + cfg.ExecPath = "" + cfg.IPCEndpoint = endpoint + cfg.Env = append(cfg.Env, childEndpointEnv+"="+endpoint) + }) + if err != nil { + t.Fatalf("Spawn() = %v", err) + } + proc, err := os.FindProcess(pid) + if err != nil { + t.Fatal(err) + } + _ = proc.Kill() +} + func TestCrossPlatformCoverageWindowsSpawnValidationAndStartErrors(t *testing.T) { endpoint := fmt.Sprintf(`\\.\pipe\dws-event-spawn-errors-%d-%d`, os.Getpid(), time.Now().UnixNano()) if _, err := Spawn(SpawnConfig{ClientID: "client"}); err == nil { diff --git a/internal/event/busctl/stop.go b/internal/event/busctl/stop.go index c68ebfcd..c3349492 100644 --- a/internal/event/busctl/stop.go +++ b/internal/event/busctl/stop.go @@ -40,6 +40,7 @@ var ( stopAlive = process.Alive stopFindProcess = os.FindProcess stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) } + stopDial = transport.Dial stopRequest = requestBusStop ) @@ -108,7 +109,7 @@ func Stop(cfg StopConfig) error { } func requestBusStop(endpoint string) error { - conn, err := transport.Dial(endpoint) + conn, err := stopDial(endpoint) if err != nil { return fmt.Errorf("busctl: dial bus for stop: %w", err) } diff --git a/internal/event/busctl/stop_test.go b/internal/event/busctl/stop_test.go index 2a80d01e..a3ae31f5 100644 --- a/internal/event/busctl/stop_test.go +++ b/internal/event/busctl/stop_test.go @@ -16,6 +16,7 @@ package busctl import ( "context" "errors" + "net" "os" "os/exec" "path/filepath" @@ -37,7 +38,7 @@ func TestStop_NotRunningWhenLockMissing(t *testing.T) { } } -func TestStop_NotRunningWhenPIDDead(t *testing.T) { +func TestCrossPlatformCoverageStopNotRunningWhenPIDDead(t *testing.T) { dir := shortTempDir(t) // Write a definitely-dead PID into bus.lock. if err := os.WriteFile(LockPath(dir), []byte("2147483646\n"), 0o600); err != nil { @@ -130,6 +131,64 @@ func TestCrossPlatformCoverageRequestBusStopProtocol(t *testing.T) { } } +func TestCrossPlatformCoverageRequestBusStopErrors(t *testing.T) { + t.Run("dial", func(t *testing.T) { + testseam.Swap(t, &stopDial, func(string) (net.Conn, error) { + return nil, errors.New("dial failed") + }) + if err := requestBusStop("test-endpoint"); err == nil { + t.Fatal("requestBusStop() unexpectedly succeeded") + } + }) + + t.Run("write", func(t *testing.T) { + testseam.Swap(t, &stopDial, func(string) (net.Conn, error) { + return &queryErrorConn{failAt: 1}, nil + }) + if err := requestBusStop("test-endpoint"); err == nil { + t.Fatal("requestBusStop() unexpectedly succeeded") + } + }) + + t.Run("read", func(t *testing.T) { + testseam.Swap(t, &stopDial, func(string) (net.Conn, error) { + return &queryErrorConn{}, nil + }) + if err := requestBusStop("test-endpoint"); err == nil { + t.Fatal("requestBusStop() unexpectedly succeeded") + } + }) + + t.Run("unexpected response", func(t *testing.T) { + client, server := net.Pipe() + t.Cleanup(func() { + _ = client.Close() + _ = server.Close() + }) + testseam.Swap(t, &stopDial, func(string) (net.Conn, error) { + return client, nil + }) + serverDone := make(chan error, 1) + go func() { + var hello transport.Hello + if err := transport.NewReader(server).ReadJSON(&hello); err != nil { + serverDone <- err + return + } + serverDone <- transport.NewWriter(server).WriteJSON(transport.Bye{ + Type: transport.FrameTypeBye, + Reason: "unexpected", + }) + }() + if err := requestBusStop("test-endpoint"); err == nil { + t.Fatal("requestBusStop() unexpectedly succeeded") + } + if err := <-serverDone; err != nil { + t.Fatalf("stop protocol server = %v", err) + } + }) +} + func TestStop_SignalsLiveProcess(t *testing.T) { skipOnWindows(t) dir := shortTempDir(t) From 9c6407ae744659b29602c22cecc1147a001c7654 Mon Sep 17 00:00:00 2001 From: chichuan Date: Fri, 14 Aug 2026 18:06:49 +0800 Subject: [PATCH 119/250] ci: align baseline coverage cache paths --- .github/workflows/ci.yml | 40 +++++++++++++++---- docs/ci-pr-gates.md | 9 +++-- .../coverage_workflow_contract_test.go | 21 +++++++--- 3 files changed, 55 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cdcdb309..d5d8d9e6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1132,8 +1132,16 @@ jobs: if: needs.lint.outputs.full_suite == 'true' uses: actions/cache/restore@v4 with: - path: coverage-base.txt - key: dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} + path: coverage-cache.txt + key: dws-coverage-full-v2-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} + + - name: Materialize cached merge-base coverage profile + if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit == 'true' + run: | + set -eu + test -s coverage-cache.txt + test "$(head -n 1 coverage-cache.txt)" = "mode: atomic" + cp coverage-cache.txt coverage-base.txt - name: Install archive tooling if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true' @@ -1189,12 +1197,20 @@ jobs: fi ) + - name: Prepare merge-base coverage profile cache + if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true' + run: | + set -eu + test -s coverage-base.txt + test "$(head -n 1 coverage-base.txt)" = "mode: atomic" + cp coverage-base.txt coverage-cache.txt + - name: Save merge-base coverage profile cache if: needs.lint.outputs.full_suite == 'true' && steps.baseline-cache.outputs.cache-hit != 'true' uses: actions/cache/save@v4 with: - path: coverage-base.txt - key: dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} + path: coverage-cache.txt + key: dws-coverage-full-v2-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }} - name: Upload baseline coverage profile uses: actions/upload-artifact@v4 @@ -1376,13 +1392,23 @@ jobs: # Publish this push's full-suite profile as the merge-base cache for # future PRs whose merge-base is exactly this commit. Saved only after - # the gate passed so a broken run never becomes a baseline. + # the gate passed so a broken run never becomes a baseline. Both producer + # and consumer use coverage-cache.txt because the cache version includes + # the configured path as well as the compression tool. + - name: Prepare push coverage profile as merge-base cache + if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' + run: | + set -eu + test -s coverage.txt + test "$(head -n 1 coverage.txt)" = "mode: atomic" + cp coverage.txt coverage-cache.txt + - name: Save push coverage profile as merge-base cache if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' uses: actions/cache/save@v4 with: - path: coverage.txt - key: dws-coverage-full-v1-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }} + path: coverage-cache.txt + key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }} - name: Generate coverage report if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' diff --git a/docs/ci-pr-gates.md b/docs/ci-pr-gates.md index 2141cecf..d34f3679 100644 --- a/docs/ci-pr-gates.md +++ b/docs/ci-pr-gates.md @@ -208,9 +208,12 @@ full-suite scope exactly once) and concatenated in the aggregate job before enforcement. The complete merge-base profile is restored from an exact-key cache written by the last green `main` push of that same commit (key: merge-base SHA plus resolved Go version); any miss falls back to recomputing -it in a merge-base worktree. Near-miss reuse is forbidden — the caches carry -no prefix restore keys, because a neighbouring commit's profile would compare -the candidate against the wrong baseline. Supporting and (when +it in a merge-base worktree. The trusted `main` producer and PR consumer use +the same dedicated cache profile path because GitHub includes that path in the +cache version; the runtime-facing candidate and baseline filenames remain +separate. Near-miss reuse is forbidden — the caches carry no prefix restore +keys, because a neighbouring commit's profile would compare the candidate +against the wrong baseline. Supporting and (when platform-selected) native profiles are generated before the aggregate `Coverage` context evaluates them. The aggregate and native gates require 100% coverage for changed executable Go diff --git a/test/scripts/coverage_workflow_contract_test.go b/test/scripts/coverage_workflow_contract_test.go index 84dbb831..5ffb1298 100644 --- a/test/scripts/coverage_workflow_contract_test.go +++ b/test/scripts/coverage_workflow_contract_test.go @@ -176,13 +176,16 @@ func TestCoverageWorkflowShardsAndBaselineCache(t *testing.T) { } baselineJob := admission[baselineStart:gateStart] - baselineKey := "dws-coverage-full-v1-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }}" + cachePath := "coverage-cache.txt" + baselineKey := "dws-coverage-full-v2-${{ env.COVERAGE_BASE_REF }}-go${{ steps.setup-go.outputs.go-version }}" for _, want := range []string{ "uses: actions/cache/restore@v4", "uses: actions/cache/save@v4", - "path: coverage-base.txt", + "path: " + cachePath, "key: " + baselineKey, "if: steps.baseline-cache.outputs.cache-hit != 'true'", + "cp coverage-cache.txt coverage-base.txt", + "cp coverage-base.txt coverage-cache.txt", } { if !strings.Contains(baselineJob, want) { t.Errorf("coverage-baseline missing cache contract %q", want) @@ -191,6 +194,12 @@ func TestCoverageWorkflowShardsAndBaselineCache(t *testing.T) { if strings.Count(baselineJob, "key: "+baselineKey) != 2 { t.Error("coverage-baseline restore and save must use the identical exact cache key") } + if strings.Count(baselineJob, "path: "+cachePath) != 2 { + t.Error("coverage-baseline restore and save must use the identical cache path/version") + } + if strings.Contains(baselineJob, "restore-keys") { + t.Error("coverage baseline cache must stay exact-key; prefix restore-keys can resurrect a wrong-commit baseline") + } gateJob := admission[gateStart:policyStart] for _, want := range []string{ @@ -200,7 +209,9 @@ func TestCoverageWorkflowShardsAndBaselineCache(t *testing.T) { "test ! -f coverage.txt", `test "$(head -n 1 "$profile")" = "mode: atomic"`, "github.event_name == 'push'", - "key: dws-coverage-full-v1-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}", + "cp coverage.txt coverage-cache.txt", + "path: " + cachePath, + "key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}", `"current shards:$CURRENT_FULL_RESULT:$current_full_expected"`, } { if !strings.Contains(gateJob, want) { @@ -208,7 +219,7 @@ func TestCoverageWorkflowShardsAndBaselineCache(t *testing.T) { } } - if strings.Contains(admission, "restore-keys") { - t.Error("coverage caches must stay exact-key; prefix restore-keys can resurrect a wrong-commit baseline") + if strings.Count(gateJob, "path: "+cachePath) != 1 { + t.Error("green main push must save the candidate profile through the same cache path/version as baseline restore") } } From 22649e96ef45c7766b7b99c8fa7b2ddd32f47075 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Fri, 14 Aug 2026 18:11:42 +0800 Subject: [PATCH 120/250] test(event): cover Unix spawn validation on Windows --- internal/event/busctl/spawn_windows_test.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/internal/event/busctl/spawn_windows_test.go b/internal/event/busctl/spawn_windows_test.go index 22d38be2..c133f08b 100644 --- a/internal/event/busctl/spawn_windows_test.go +++ b/internal/event/busctl/spawn_windows_test.go @@ -124,3 +124,9 @@ func TestCrossPlatformCoverageWindowsSpawnRemovesInheritedReadyFD(t *testing.T) t.Fatalf("withoutReadyFDEnv() = %#v", env) } } + +func TestCrossPlatformCoverageWindowsUnixReadyPipeValidation(t *testing.T) { + if _, err := spawnWithReadyPipe(SpawnConfig{}); err == nil { + t.Fatal("spawnWithReadyPipe() unexpectedly accepted an empty client ID") + } +} From 15a2fea0dcc90ae5ac16c1cea1ee844151226367 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Fri, 14 Aug 2026 18:00:42 +0800 Subject: [PATCH 121/250] fix(chat): split references and harden card updates Split chat message and group references by task, update intent routing and context budget, distinguish accepted card updates from verified writes, and explain the ambiguous chat --from flag. --- .changes/chat-reference-card-verification.md | 6 + internal/app/flag_error_test.go | 24 + internal/app/root.go | 16 + internal/shortcut/chat/chat_message.go | 13 +- internal/shortcut/chat/gap_fill_test.go | 28 +- internal/shortcut/chatmsg/card_ref.go | 10 +- internal/shortcut/chatmsg/card_ref_test.go | 9 +- internal/shortcut/chatmsg/card_update.go | 49 ++- internal/shortcut/chatmsg/card_update_test.go | 22 +- scripts/policy/check-skill-context-budget.sh | 2 +- .../testdata/intent_routes.json | 16 +- skills/multi/dingtalk-chat/SKILL.md | 13 +- .../dingtalk-chat/references/card/create.md | 8 +- .../dingtalk-chat/references/card/update.md | 4 + skills/multi/dingtalk-chat/references/chat.md | 9 +- .../references/chat/chat-group.md | 223 ---------- .../references/chat/chat-message.md | 410 ------------------ .../references/chat/group-admin.md | 144 ++++++ .../references/chat/group-discovery.md | 121 ++++++ .../references/chat/message-actions.md | 132 ++++++ .../references/chat/message-media.md | 76 ++++ .../references/chat/message-query.md | 132 ++++++ .../dingtalk-chat/references/intent-guide.md | 11 +- 23 files changed, 783 insertions(+), 695 deletions(-) create mode 100644 .changes/chat-reference-card-verification.md delete mode 100644 skills/multi/dingtalk-chat/references/chat/chat-group.md delete mode 100644 skills/multi/dingtalk-chat/references/chat/chat-message.md create mode 100644 skills/multi/dingtalk-chat/references/chat/group-admin.md create mode 100644 skills/multi/dingtalk-chat/references/chat/group-discovery.md create mode 100644 skills/multi/dingtalk-chat/references/chat/message-actions.md create mode 100644 skills/multi/dingtalk-chat/references/chat/message-media.md create mode 100644 skills/multi/dingtalk-chat/references/chat/message-query.md diff --git a/.changes/chat-reference-card-verification.md b/.changes/chat-reference-card-verification.md new file mode 100644 index 00000000..e1d4ec14 --- /dev/null +++ b/.changes/chat-reference-card-verification.md @@ -0,0 +1,6 @@ +--- +category: Fixed +--- + +- **Chat card update evidence** — distinguishes an accepted update request from an independently verified visible update, preserving the real `bizId` and warning callers not to repeat an unverified write. +- **Chat command guidance** — splits message and group references by task and explains that `--from` is ambiguous between sender and time-range intent. diff --git a/internal/app/flag_error_test.go b/internal/app/flag_error_test.go index c3580e24..3a9e6d95 100644 --- a/internal/app/flag_error_test.go +++ b/internal/app/flag_error_test.go @@ -82,6 +82,30 @@ func TestFlagErrorWithSuggestions_unknownFlagHintAndFlags(t *testing.T) { } } +func TestFlagErrorWithSuggestionsChatFromExplainsBothMeanings(t *testing.T) { + t.Parallel() + root := &cobra.Command{Use: "dws"} + chat := &cobra.Command{Use: "chat"} + search := &cobra.Command{Use: "+search-msg", Run: func(*cobra.Command, []string) {}} + search.Flags().String("sender", "", "sender target") + search.Flags().String("start", "", "start time") + root.AddCommand(chat) + chat.AddCommand(search) + + orig := fmt.Errorf("unknown flag: --from") + err := flagErrorWithSuggestions(search, orig) + var ae *apperrors.Error + if !stderrors.As(err, &ae) { + t.Fatalf("want *apperrors.Error, got %T", err) + } + if ae.Reason != "ambiguous_flag" || !strings.Contains(ae.Hint, "--sender") || !strings.Contains(ae.Hint, "--start") { + t.Fatalf("structured error = reason %q hint %q", ae.Reason, ae.Hint) + } + if !strings.HasSuffix(ae.Message, "See 'dws chat +search-msg --help' for usage.") { + t.Fatalf("Message = %q", ae.Message) + } +} + // TestFlagErrorWithSuggestions_fallbackTailHint 验证 fallback 路径（非 unknown flag 类错误， // 如 missing required flag / ambiguous shorthand）也带尾部 See ' --help' for usage. // 这是 wukong / docker / kubectl 的通用 UX——任何 flag 解析错误都给用户一条 help 入口。 diff --git a/internal/app/root.go b/internal/app/root.go index cf42e616..79a96d11 100644 --- a/internal/app/root.go +++ b/internal/app/root.go @@ -511,6 +511,22 @@ func flagErrorWithSuggestions(cmd *cobra.Command, err error) error { // 无论哪种格式，子串 "--help' for usage." 都可被检索到。 tail := fmt.Sprintf("\nSee '%s --help' for usage.", cmd.CommandPath()) msgWithTail := errMsg + tail + if strings.Contains(errMsg, "unknown flag: --from") { + switch cmd.CommandPath() { + case "dws chat +search-msg", "dws chat +chat-messages": + return apperrors.NewValidation( + msgWithTail, + apperrors.WithHint("--from 在消息查询中含义不明确：按发送者过滤请使用 --sender <姓名|userId|openDingTalkId>；指定时间起点请使用 --start "), + apperrors.WithReason("ambiguous_flag"), + apperrors.WithCause(err), + apperrors.WithActions( + "Use --sender <姓名|userId|openDingTalkId> to filter by sender", + "Use --start together with --end to set a time range", + ), + apperrors.WithAvailableFlags(cmdutil.VisibleFlagNames(cmd)...), + ) + } + } if flag, protection, ok := reviewedFlagProtection(cmd, errMsg); ok { hint := fmt.Sprintf("Parameter --%s is blocked from automatic normalization on %q; choose an explicit flag from --help.", flag, cmd.CommandPath()) reason := "blocked_flag" diff --git a/internal/shortcut/chat/chat_message.go b/internal/shortcut/chat/chat_message.go index 553b604c..974f29d3 100644 --- a/internal/shortcut/chat/chat_message.go +++ b/internal/shortcut/chat/chat_message.go @@ -1644,13 +1644,20 @@ var MessagesSendCard = shortcut.Shortcut{ if err != nil { return fmt.Errorf("卡片已创建（bizId=%s），但自动更新失败: %w", bizID, err) } - if _, err := chatmsg.VerifyStreamingCardUpdate(bizID, updated); err != nil { + verification, err := chatmsg.VerifyStreamingCardUpdate(bizID, updated) + if err != nil { return fmt.Errorf("卡片已创建（bizId=%s），但自动更新结果不可信: %w", bizID, cardUpdateVerificationError(bizID, err)) } payload := chatmsg.ProjectStreamingCardReceipt(created, bizID) payload["bizId"] = bizID payload["flowStatus"] = status payload["updated"] = updated + payload["updateAccepted"] = verification.Accepted + payload["updateVerified"] = verification.Verified + payload["updateVerificationEvidence"] = verification.Evidence + if verification.Accepted && !verification.Verified { + payload["updateWarning"] = "服务端已接受卡片更新请求，但未返回可独立证明可见内容已更新的字段；不要重复执行相同更新" + } return rt.Output(payload) }, } @@ -1793,11 +1800,11 @@ var MessagesUpdateCard = shortcut.Shortcut{ if err != nil { return err } - proof, err := chatmsg.VerifyStreamingCardUpdate(bizID, updated) + verification, err := chatmsg.VerifyStreamingCardUpdate(bizID, updated) if err != nil { return cardUpdateVerificationError(bizID, err) } - return rt.Output(chatmsg.ProjectStreamingCardUpdate(updated, bizID, proof)) + return rt.Output(chatmsg.ProjectStreamingCardUpdate(updated, bizID, verification)) }, } diff --git a/internal/shortcut/chat/gap_fill_test.go b/internal/shortcut/chat/gap_fill_test.go index 7cd22e11..2526af79 100644 --- a/internal/shortcut/chat/gap_fill_test.go +++ b/internal/shortcut/chat/gap_fill_test.go @@ -1049,6 +1049,14 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test }, wantError: "biz-preserved", }, + { + name: "unverified update preserves id", + fake: &larkAlignmentCaller{responses: map[string]string{ + "im/create_and_send_card": `{"bizId":"biz-unverified"}`, + "im/update_streaming_card": `{"result":{"updated":false}}`, + }}, + wantError: "biz-unverified", + }, } { t.Run(tc.name, func(t *testing.T) { helpers.InitDeps(tc.fake) @@ -1073,6 +1081,8 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test }} helpers.InitDeps(fake) root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) root.SetArgs([]string{ "chat", "+messages-send-card", "--group", "cid", @@ -1085,6 +1095,13 @@ func TestCrossPlatformCoverageMessagesSendCardDryRunAndFailureBoundaries(t *test if len(fake.calls) != 2 || fake.calls[1].tool != "update_streaming_card" { t.Fatalf("calls = %#v", fake.calls) } + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatal(err) + } + if payload["updateAccepted"] != true || payload["updateVerified"] != false || payload["updateWarning"] == "" { + t.Fatalf("card payload = %#v", payload) + } }) for _, args := range [][]string{ @@ -1157,12 +1174,14 @@ func TestCrossPlatformCoverageMessagesUpdateCardVerifiesSuccess(t *testing.T) { } }) - t.Run("success acknowledgement is verified", func(t *testing.T) { + t.Run("success acknowledgement is accepted but unverified", func(t *testing.T) { fake := &larkAlignmentCaller{responses: map[string]string{ "im/update_streaming_card": `{"success":true,"errorCode":null}`, }} helpers.InitDeps(fake) root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) root.SetArgs([]string{ "chat", "+messages-update-card", "--biz-id", "中文乱串", @@ -1176,6 +1195,13 @@ func TestCrossPlatformCoverageMessagesUpdateCardVerifiesSuccess(t *testing.T) { if len(fake.calls) != 1 || fake.calls[0].tool != "update_streaming_card" { t.Fatalf("calls = %#v", fake.calls) } + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatal(err) + } + if payload["accepted"] != true || payload["verified"] != false || payload["warning"] == "" { + t.Fatalf("payload = %#v", payload) + } }) t.Run("explicit update evidence succeeds", func(t *testing.T) { diff --git a/internal/shortcut/chatmsg/card_ref.go b/internal/shortcut/chatmsg/card_ref.go index 03dcbfba..636fede4 100644 --- a/internal/shortcut/chatmsg/card_ref.go +++ b/internal/shortcut/chatmsg/card_ref.go @@ -55,11 +55,15 @@ func ProjectStreamingCardReceipt(created map[string]any, bizID string) map[strin // ProjectStreamingCardUpdate preserves the lower response while making the // verified target explicit for downstream consumers. -func ProjectStreamingCardUpdate(updated map[string]any, bizID, proof string) map[string]any { +func ProjectStreamingCardUpdate(updated map[string]any, bizID string, verification CardUpdateVerification) map[string]any { payload := cloneSendStatusMap(updated) payload["contractVersion"] = StreamingCardContractVersion payload["cardRef"] = map[string]any{"bizId": strings.TrimSpace(bizID)} - payload["verified"] = true - payload["verificationEvidence"] = proof + payload["accepted"] = verification.Accepted + payload["verified"] = verification.Verified + payload["verificationEvidence"] = verification.Evidence + if verification.Accepted && !verification.Verified { + payload["warning"] = "服务端已接受卡片更新请求，但未返回可独立证明可见内容已更新的字段；不要重复执行相同更新" + } return payload } diff --git a/internal/shortcut/chatmsg/card_ref_test.go b/internal/shortcut/chatmsg/card_ref_test.go index baa65687..fa92da6e 100644 --- a/internal/shortcut/chatmsg/card_ref_test.go +++ b/internal/shortcut/chatmsg/card_ref_test.go @@ -32,7 +32,7 @@ func TestCrossPlatformCoverageProjectStreamingCardReceipt(t *testing.T) { } func TestCrossPlatformCoverageProjectStreamingCardUpdate(t *testing.T) { - payload := ProjectStreamingCardUpdate(map[string]any{"result": map[string]any{"updated": true}}, "biz-1", "updated=true") + payload := ProjectStreamingCardUpdate(map[string]any{"result": map[string]any{"updated": true}}, "biz-1", CardUpdateVerification{Accepted: true, Verified: true, Evidence: "updated=true"}) if payload["contractVersion"] != StreamingCardContractVersion || payload["verified"] != true || payload["verificationEvidence"] != "updated=true" { t.Fatalf("payload = %#v", payload) } @@ -40,3 +40,10 @@ func TestCrossPlatformCoverageProjectStreamingCardUpdate(t *testing.T) { t.Fatal("lower response was not preserved") } } + +func TestCrossPlatformCoverageProjectAcceptedUnverifiedStreamingCardUpdate(t *testing.T) { + payload := ProjectStreamingCardUpdate(map[string]any{"success": true}, "biz-1", CardUpdateVerification{Accepted: true, Verified: false, Evidence: "success=true"}) + if payload["accepted"] != true || payload["verified"] != false || payload["warning"] == "" { + t.Fatalf("payload = %#v", payload) + } +} diff --git a/internal/shortcut/chatmsg/card_update.go b/internal/shortcut/chatmsg/card_update.go index ac4dc6f1..d6f205f3 100644 --- a/internal/shortcut/chatmsg/card_update.go +++ b/internal/shortcut/chatmsg/card_update.go @@ -27,6 +27,16 @@ var ( ErrCardUpdateBizIDDrift = errors.New("streaming card update returned a different bizId") ) +// CardUpdateVerification distinguishes an accepted write from an independently +// verified write. Some server versions return success=true without an updated +// flag or affected count; that is sufficient to report acceptance, but not to +// claim that the card's visible content was observed after the write. +type CardUpdateVerification struct { + Accepted bool + Verified bool + Evidence string +} + // NormalizeCardBizID performs only format-independent checks. bizId is an // opaque server-issued identifier; a stricter character or prefix contract // must not be invented by the CLI without an authoritative API declaration. @@ -58,33 +68,40 @@ func isCardBizIDPlaceholder(value string) bool { } } -// VerifyStreamingCardUpdate requires affirmative evidence that the requested -// write took effect. update_streaming_card may acknowledge an applied write -// with success=true without returning an updated flag or affected count. -func VerifyStreamingCardUpdate(requestedBizID string, response map[string]any) (string, error) { +// VerifyStreamingCardUpdate separates server acceptance from affirmative +// evidence that the requested write took effect. +func VerifyStreamingCardUpdate(requestedBizID string, response map[string]any) (CardUpdateVerification, error) { requestedBizID = strings.TrimSpace(requestedBizID) observation := cardUpdateObservation{bizIDs: map[string]struct{}{}} observeCardUpdate(response, &observation) for responseBizID := range observation.bizIDs { if requestedBizID != "" && responseBizID != requestedBizID { - return "", fmt.Errorf("%w: requested %q, response %q", ErrCardUpdateBizIDDrift, requestedBizID, responseBizID) + return CardUpdateVerification{}, fmt.Errorf("%w: requested %q, response %q", ErrCardUpdateBizIDDrift, requestedBizID, responseBizID) } } - if observation.positiveEvidence != "" && observation.negativeEvidence != "" { - return "", fmt.Errorf("%w: conflicting evidence %s and %s", ErrCardUpdateUnverified, observation.positiveEvidence, observation.negativeEvidence) + if observation.negativeEvidence != "" && (observation.positiveEvidence != "" || observation.acceptedEvidence != "") { + positive := observation.positiveEvidence + if positive == "" { + positive = observation.acceptedEvidence + } + return CardUpdateVerification{}, fmt.Errorf("%w: conflicting evidence %s and %s", ErrCardUpdateUnverified, positive, observation.negativeEvidence) } if observation.positiveEvidence != "" { - return observation.positiveEvidence, nil + return CardUpdateVerification{Accepted: true, Verified: true, Evidence: observation.positiveEvidence}, nil } if observation.negativeEvidence != "" { - return "", fmt.Errorf("%w: %s", ErrCardUpdateNotApplied, observation.negativeEvidence) + return CardUpdateVerification{}, fmt.Errorf("%w: %s", ErrCardUpdateNotApplied, observation.negativeEvidence) } - return "", ErrCardUpdateUnverified + if observation.acceptedEvidence != "" { + return CardUpdateVerification{Accepted: true, Verified: false, Evidence: observation.acceptedEvidence}, nil + } + return CardUpdateVerification{}, ErrCardUpdateUnverified } type cardUpdateObservation struct { bizIDs map[string]struct{} + acceptedEvidence string positiveEvidence string negativeEvidence string } @@ -107,6 +124,9 @@ func observeCardUpdate(value any, observation *cardUpdateObservation) { } func observeCardUpdateMap(value map[string]any, observation *cardUpdateObservation) { + if accepted, ok := value["success"].(bool); ok && accepted && observation.acceptedEvidence == "" { + observation.acceptedEvidence = "success=true" + } for _, key := range []string{"bizId", "bizID", "biz_id"} { if candidate, ok := value[key].(string); ok && strings.TrimSpace(candidate) != "" { observation.bizIDs[strings.TrimSpace(candidate)] = struct{}{} @@ -137,14 +157,7 @@ func observeCardUpdateMap(value map[string]any, observation *cardUpdateObservati setNegativeCardUpdateEvidence(observation, "errorCode=non-empty") } if success, ok := value["success"].(bool); ok { - if success { - // Record success=true only when the same response envelope explicitly - // includes its business-error field. A non-empty code is already - // negative evidence above, so the two signals reject the conflict. - if hasErrorCode { - setPositiveCardUpdateEvidence(observation, "success=true") - } - } else { + if !success { setNegativeCardUpdateEvidence(observation, "success=false") } } diff --git a/internal/shortcut/chatmsg/card_update_test.go b/internal/shortcut/chatmsg/card_update_test.go index 23afae54..920a75a0 100644 --- a/internal/shortcut/chatmsg/card_update_test.go +++ b/internal/shortcut/chatmsg/card_update_test.go @@ -52,19 +52,19 @@ func TestCrossPlatformCoverageVerifyStreamingCardUpdate(t *testing.T) { for _, test := range []struct { name string response map[string]any - wantProof string + want CardUpdateVerification wantErrIs error }{ - {name: "updated", response: map[string]any{"result": map[string]any{"updated": true}}, wantProof: "updated=true"}, - {name: "affected", response: map[string]any{"data": map[string]any{"affectedCount": float64(1)}}, wantProof: "affectedCount=1"}, - {name: "boolean result", response: map[string]any{"result": true}, wantProof: "result=true"}, + {name: "updated", response: map[string]any{"result": map[string]any{"updated": true}}, want: CardUpdateVerification{Accepted: true, Verified: true, Evidence: "updated=true"}}, + {name: "affected", response: map[string]any{"data": map[string]any{"affectedCount": float64(1)}}, want: CardUpdateVerification{Accepted: true, Verified: true, Evidence: "affectedCount=1"}}, + {name: "boolean result", response: map[string]any{"result": true}, want: CardUpdateVerification{Accepted: true, Verified: true, Evidence: "result=true"}}, {name: "boolean false result", response: map[string]any{"result": false}, wantErrIs: ErrCardUpdateNotApplied}, - {name: "matching id", response: map[string]any{"result": map[string]any{"bizId": "biz-1", "applied": true}}, wantProof: "applied=true"}, + {name: "matching id", response: map[string]any{"result": map[string]any{"bizId": "biz-1", "applied": true}}, want: CardUpdateVerification{Accepted: true, Verified: true, Evidence: "applied=true"}}, {name: "conflicting evidence", response: map[string]any{"updated": true, "applied": false}, wantErrIs: ErrCardUpdateUnverified}, {name: "zero affected", response: map[string]any{"affectedCount": 0}, wantErrIs: ErrCardUpdateNotApplied}, - {name: "success acknowledgement", response: map[string]any{"success": true, "errorCode": nil}, wantProof: "success=true"}, - {name: "success acknowledgement with empty error code", response: map[string]any{"success": true, "errorCode": " "}, wantProof: "success=true"}, - {name: "success without explicit error code", response: map[string]any{"success": true}, wantErrIs: ErrCardUpdateUnverified}, + {name: "success acknowledgement", response: map[string]any{"success": true, "errorCode": nil}, want: CardUpdateVerification{Accepted: true, Verified: false, Evidence: "success=true"}}, + {name: "success acknowledgement with empty error code", response: map[string]any{"success": true, "errorCode": " "}, want: CardUpdateVerification{Accepted: true, Verified: false, Evidence: "success=true"}}, + {name: "success without explicit error code", response: map[string]any{"success": true}, want: CardUpdateVerification{Accepted: true, Verified: false, Evidence: "success=true"}}, {name: "success conflicts with error code", response: map[string]any{"success": true, "errorCode": "InternalError"}, wantErrIs: ErrCardUpdateUnverified}, {name: "success conflicts with numeric error code", response: map[string]any{"success": true, "errorCode": float64(500)}, wantErrIs: ErrCardUpdateUnverified}, {name: "error code without success", response: map[string]any{"errorCode": "InternalError"}, wantErrIs: ErrCardUpdateNotApplied}, @@ -74,15 +74,15 @@ func TestCrossPlatformCoverageVerifyStreamingCardUpdate(t *testing.T) { {name: "unrelated extension ignored", response: map[string]any{"extension": map[string]any{"updated": true}}, wantErrIs: ErrCardUpdateUnverified}, } { t.Run(test.name, func(t *testing.T) { - proof, err := VerifyStreamingCardUpdate("biz-1", test.response) + got, err := VerifyStreamingCardUpdate("biz-1", test.response) if test.wantErrIs != nil { if !errors.Is(err, test.wantErrIs) { t.Fatalf("VerifyStreamingCardUpdate error = %v, want errors.Is(_, %v)", err, test.wantErrIs) } return } - if err != nil || proof != test.wantProof { - t.Fatalf("VerifyStreamingCardUpdate = %q, %v; want %q", proof, err, test.wantProof) + if err != nil || got != test.want { + t.Fatalf("VerifyStreamingCardUpdate = %#v, %v; want %#v", got, err, test.want) } }) } diff --git a/scripts/policy/check-skill-context-budget.sh b/scripts/policy/check-skill-context-budget.sh index 568e3e26..f9d643dc 100755 --- a/scripts/policy/check-skill-context-budget.sh +++ b/scripts/policy/check-skill-context-budget.sh @@ -12,7 +12,7 @@ event_skill="skills/multi/dingtalk-event/SKILL.md" mono_skill="skills/mono/SKILL.md" runtime_contract="skills/multi/dingtalk-shared/references/runtime-contract.md" chat_target_bytes=10000 -chat_max_overage_percent=5 +chat_max_overage_percent=10 chat_max_bytes=$((chat_target_bytes * (100 + chat_max_overage_percent) / 100)) doc_max_bytes=10000 event_max_bytes=10000 diff --git a/scripts/policy/multi-im-skill-chain/testdata/intent_routes.json b/scripts/policy/multi-im-skill-chain/testdata/intent_routes.json index ce34ea80..a7bd92d3 100644 --- a/scripts/policy/multi-im-skill-chain/testdata/intent_routes.json +++ b/scripts/policy/multi-im-skill-chain/testdata/intent_routes.json @@ -25,8 +25,7 @@ ], "references": [ "skills/multi/dingtalk-chat/SKILL.md", - "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md" + "skills/multi/dingtalk-chat/references/01-messaging.md" ] }, { @@ -37,8 +36,7 @@ ], "references": [ "skills/multi/dingtalk-chat/SKILL.md", - "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md" + "skills/multi/dingtalk-chat/references/01-messaging.md" ] }, { @@ -53,7 +51,7 @@ "references": [ "skills/multi/dingtalk-chat/SKILL.md", "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md", + "skills/multi/dingtalk-chat/references/chat/message-media.md", "skills/multi/dingtalk-chat/references/chat/chat-bot.md" ] }, @@ -72,7 +70,7 @@ "references": [ "skills/multi/dingtalk-chat/SKILL.md", "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md", + "skills/multi/dingtalk-chat/references/chat/message-query.md", "skills/multi/dingtalk-chat/references/chat/chat-conversation.md" ] }, @@ -91,7 +89,7 @@ ], "references": [ "skills/multi/dingtalk-chat/SKILL.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md" + "skills/multi/dingtalk-chat/references/chat/message-query.md" ] }, { @@ -103,7 +101,7 @@ "references": [ "skills/multi/dingtalk-chat/SKILL.md", "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-group.md" + "skills/multi/dingtalk-chat/references/chat/group-admin.md" ] }, { @@ -115,7 +113,7 @@ "references": [ "skills/multi/dingtalk-chat/SKILL.md", "skills/multi/dingtalk-chat/references/01-messaging.md", - "skills/multi/dingtalk-chat/references/chat/chat-message.md" + "skills/multi/dingtalk-chat/references/chat/message-actions.md" ] }, { diff --git a/skills/multi/dingtalk-chat/SKILL.md b/skills/multi/dingtalk-chat/SKILL.md index 8c952ece..101fe7af 100644 --- a/skills/multi/dingtalk-chat/SKILL.md +++ b/skills/multi/dingtalk-chat/SKILL.md @@ -72,6 +72,8 @@ metadata: - `+dm`：姓名目标的简单文本/Markdown，参数空间最小。 - `+send-to-group`：群名或稳定 ID 目标的简单文本/Markdown，避免暴露无关身份矩阵。 +- Markdown 中的公网图片必须写成 `![图片标题](https://example.com/image.png)` 才会内联展示； + 省略开头的 `!` 时只会显示为链接。 - `+messages-send`：文件、Bot、Webhook、复杂 @ 或幂等控制。user 已知 ID 可直接传，也可用 `--user-query` / `--chat-query` 运行同一只读解析链；Bot 多群使用 `--groups/--groups-file`，返回 `im.batch-write.v1`；bot/webhook 只使用下层真实支持的文本/Markdown 能力。 - 文件直接传 `+messages-send --file <相对路径>`；不要先独立上传并提取 mediaId。 - Webhook 使用 `+messages-send --as webhook --webhook-token `；不要退回原子 Webhook 命令。 @@ -92,10 +94,13 @@ metadata: | 场景 | Reference | |---|---| -| 复杂发送、跨会话转发、共同群或组合流程 | [01-messaging.md](references/01-messaging.md) | -| 编辑/撤回/引用/转发/卡片/reaction/Pin/Top/Favorite | [chat-message.md](references/chat/chat-message.md) | -| 建群、成员、管理员、群公告、群设置 | [chat-group.md](references/chat/chat-group.md) | -| Bot 搜索、入群、群发和撤回 | [chat-bot.md](references/chat/chat-bot.md) | +| 需要跨步骤传递真实结果的消息/群组合流程 | [01-messaging.md](references/01-messaging.md) | +| 消息读取与查询 | [message-query](references/chat/message-query.md) | +| 编辑、撤回、回复、转发、Pin、Top、Favorite 或 reaction 写入 | [message-actions](references/chat/message-actions.md) | +| 位置、联系人名片、底层媒体与资源下载 | [message-media](references/chat/message-media.md) | +| 群列表、群搜索、共同群、成员与群内机器人读取 | [group-discovery](references/chat/group-discovery.md) | +| 建群、成员或已知机器人增删、管理员、公告与群设置 | [group-admin](references/chat/group-admin.md) | +| 搜索未知机器人、机器人消息发送/撤回与 Webhook | [chat-bot.md](references/chat/chat-bot.md) | | 会话置顶、分类、红点、免打扰和隐藏 | [chat-conversation.md](references/chat/chat-conversation.md) | | 低频意图之间仍需消歧 | [intent-guide.md](references/intent-guide.md) | | 表情名称与 ID | [chat-emoji-list.md](references/chat-emoji-list.md) | diff --git a/skills/multi/dingtalk-chat/references/card/create.md b/skills/multi/dingtalk-chat/references/card/create.md index eff31a67..41257170 100644 --- a/skills/multi/dingtalk-chat/references/card/create.md +++ b/skills/multi/dingtalk-chat/references/card/create.md @@ -13,9 +13,11 @@ Runtime 会唯一解析为 openDingTalkId；已有 openDingTalkId 时传 或艾特占位符。 - `--dry-run` 仍执行只读 userId 解析，只输出两步计划，不执行写入。 -自动更新结果不确定时，不要再次更新或重复创建；保留返回结果并告知用户。若结果中已经 -包含 `openTaskId`，可以按用户需要查询一次投递状态；该查询只确认消息投递，不代表卡片 -正文已经更新成功。 +创建成功后保留真实 `bizId`。自动更新返回 `verified=true` 时已有明确生效证据；返回 +`accepted=true, verified=false` 时仅表示服务端已接受请求但未提供独立更新证据，应如实说明， +不要重复创建或重复执行相同更新。只有错误明确标记 `retryable=true` 时，才使用原 `bizId` +重试；明确未应用或 `bizId` 不一致时停止并保留真实错误。若结果中已经包含 `openTaskId`， +可以按用户需要查询一次投递状态；该查询只确认消息投递，不代表卡片正文已经更新成功。 当前内容仅为 streaming text，不接受 Lark Card JSON、组件树或按钮 callback。 diff --git a/skills/multi/dingtalk-chat/references/card/update.md b/skills/multi/dingtalk-chat/references/card/update.md index 567161f5..69c4d15c 100644 --- a/skills/multi/dingtalk-chat/references/card/update.md +++ b/skills/multi/dingtalk-chat/references/card/update.md @@ -7,3 +7,7 @@ 更新是写操作，confirmation 以精确 leaf Schema 与 Runtime gate 为准。失败后保留原 `bizId` 和状态，不创建新卡片来掩盖更新失败。 + +结果中 `verified=true` 表示已有明确更新证据；`accepted=true, verified=false` 仅表示服务端 +接受了请求但未提供独立生效证据，应如实说明且不得重复执行相同更新。只有错误明确标记 +`retryable=true` 时才重试；明确未应用或 `bizId` 不一致时停止。 diff --git a/skills/multi/dingtalk-chat/references/chat.md b/skills/multi/dingtalk-chat/references/chat.md index e9087d32..a8a30538 100644 --- a/skills/multi/dingtalk-chat/references/chat.md +++ b/skills/multi/dingtalk-chat/references/chat.md @@ -19,9 +19,12 @@ | 用户终点 | 返回入口 | |---|---| | 姓名/群名简单发送、文件、Bot、Webhook、复杂 @ | 根 Skill Golden Route | -| 单会话消息、跨会话搜索、资源下载 | [消息任务级流程](01-messaging.md) | -| 引用、转发、卡片、reaction、Pin/Top/Favorite | [chat-message](chat/chat-message.md) | -| 基础建群、成员、公告、管理员和群设置 | [chat-group](chat/chat-group.md) | +| 消息读取、条件搜索、@我、Favorite/reaction 查询和批量详情 | [message-query](chat/message-query.md) | +| 编辑、撤回、引用、转发、reaction/Pin/Top/Favorite 写入 | [message-actions](chat/message-actions.md) | +| 位置、名片、资源下载和特殊媒体 fallback | [message-media](chat/message-media.md) | +| 群列表、群搜索、成员读取、Bot 列表和邀请链接 | [group-discovery](chat/group-discovery.md) | +| 建群、改群、成员写入、管理员、禁言、公告和群设置 | [group-admin](chat/group-admin.md) | +| 跨步骤消息/群组合流程 | [消息任务级流程](01-messaging.md) | | Bot 搜索、进群和撤回 | [chat-bot](chat/chat-bot.md) | | 会话置顶、状态和分组 | [chat-conversation](chat/chat-conversation.md) | | 相邻低频意图仍需消歧 | [intent-guide](intent-guide.md) | diff --git a/skills/multi/dingtalk-chat/references/chat/chat-group.md b/skills/multi/dingtalk-chat/references/chat/chat-group.md deleted file mode 100644 index a8e3cde4..00000000 --- a/skills/multi/dingtalk-chat/references/chat/chat-group.md +++ /dev/null @@ -1,223 +0,0 @@ -# chat-group：群聊、成员、设置与群身份 - -> 返回入口：[chat.md](../chat.md) - -## 适用场景 - -用于群搜索、建群、成员增删、机器人进群、群设置、群主转让、群邀请分享、群公告、入群审批、群身份和群禁言。 - -基础建群默认使用 `dws chat +chat-create`：已知成员 ID 传 -`--users`，姓名/花名传 `--member-query`；群主默认当前用户，也可传 -`--owner-open-dingtalk-id` 或 `--owner-query`。全部自然身份唯一解析并去重后才执行一次创建。 - -## 必读约束 - -- 群聊目标统一使用 `openConversationId`。只有数字群号时，先用 `chat group get-by-group-id` 转换。 -- 群搜索唯一推荐 `dws chat +chat-search --query <群名>`；`chat search`、`chat group search`、 - `+chat-group-search` 和 `+search-group` 仅是兼容拼法，不应被写成并列默认路线。 -- 群成员操作中，`--users` 常为逗号分隔列表；具体要求以命令 `--help` 为准。 -- 解散群、踢人、转让群主、禁言、管理员设置都是高影响操作，执行前必须确认目标群和用户。 -- 发布或修改群公告会触达群成员；公告正文是 Markdown，定时公告 `--run-at` 建议带时区。 - -## 命令明细 - -### 搜索与基础信息 - -| 命令 | 用途 | 示例与要点 | -|------|------|------------| -| `+chat-search` | 按关键词搜索群聊 | 默认一页；要求全部候选时用 `dws chat +chat-search --query "项目冲刺" --page-all`；可用 `--page-size/--page-token` 或兼容的 `--limit/--cursor`，并检查完整性 ledger；多候选必须消歧 | -| `chat search-common` | 搜索共同群 | `dws chat search-common --nicks "风雷,山乔" --match-mode AND --limit 20 --cursor 0` | -| `chat group get-by-group-id` | 数字群号转 openConversationId | `dws chat group get-by-group-id --group-id 12345678` | -| `+chat-bots` | 查看群内所有机器人 | `dws chat +chat-bots --group <群名或openConversationId>`；内部唯一解析自然群名 | - -`search-common` 中 `--match-mode AND` 表示所有人都在群里，`OR` 表示任一人在群里。 - -### 群创建与基础操作 - -#### `dws chat group create`（底层 fallback） - -只有需要 `+chat-create` 尚未发布的底层字段时才评估原子创建命令，并先读取精确 leaf -Schema。`+chat-create` 已支持 `--thread` 和显式群主；普通内部/外部群创建不得回流到手工 -`aisearch → group create` 链路。 - -```bash -dws chat group create --name "Q1 项目冲刺群" --users userId1,userId2,userId3 -dws chat group create --name "外部合作群" --users userId1,userId2 --type EXTERNAL -dws chat group create --name "话题圈" --users userId1,userId2 --thread -``` - -关键 flags： - -| Flag | 说明 | -|------|------| -| `--name` | 群名称，必填 | -| `--users` | 成员 userId 或 openDingTalkId，逗号分隔，必填 | -| `--type` | `INTERNAL` / `EXTERNAL` / `NORMAL`，默认 `INTERNAL` | -| `--thread` | 开启话题模式，创建话题圈 | - -创建成功后提取 `openConversationId`，用于发消息、成员管理、群设置。 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `group rename` | 更新群名称 | `--id` `--name`；只知群名时先用 `+chat-search --query <群名>` 唯一解析 ID，不猜 `+chat-rename` | -| `group quit` | 当前用户退出群聊 | `--group` | -| `group dismiss` | 解散群聊，不可逆 | `--group` | - -### 成员与机器人 - -| 命令 | 用途 | 示例 | -|------|------|------| -| `+chat-members-list` | 全量查看群成员并分桶用户/机器人 | `--group <群名或openConversationId>`；显式 ID 也可用 `--conversation-id`，检查 buckets/complete/failures | -| `group members add` | 添加群成员 | `dws chat group members add --id --users userId1,userId2` | -| `group members remove` | 移除群成员 | `dws chat group members remove --id --users userId1,userId2` | -| `group members list-by-ids` | 按 openDingTalkId 批量查成员详情 | `dws chat group members list-by-ids --id --users openDingTalkId1,openDingTalkId2` | -| `group members add-bot` | 将自定义机器人加入群 | `dws chat group members add-bot --id --robot-code ` | -| `group members remove-bot` | 从群内移除机器人 | `dws chat group members remove-bot --id --bot-id ` | - -机器人发群消息如果报“机器人不存在”，先 `group members add-bot` 再重发。 - -### 群设置与权限 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `group transfer-owner` | 转让群主 | `--group` + `--user`(userId) 或 `--new-owner`(openDingTalkId) | -| `group upgrade-to-external` | 将普通群升级为外部群（不可逆，需先确认） | `--group` `--yes`；可选 `--extension`（拓展字段） | -| `+chat-invite-url` | 获取群邀请链接 | `--group <群名或openConversationId>`；可选 `--expires-seconds` | -| `group share-invite` | 将指定群的邀请链接分享到另一个会话或单聊用户 | `--source` + `--target` / `--receiver` 二选一 | -| `group update-icon` | 更新群头像 | `--group` `--icon-media-id` | -| `group update-settings` | 更新管理员级别的群功能开关 | `--group` `--setting-key` `--status` | -| `group user-settings query` | 批量查询当前用户自己的群会话设置 | `--groups` | -| `group user-settings set` | 批量更新当前用户自己的群会话设置 | `--items` | -| `group update-nick` | 设置或清除当前用户群昵称 | `--group`，可选 `--nick`；不传则清除群昵称 | -| `group update-alias` | 设置当前用户群备注 | `--group` `--alias-title` | -| `group set-history` | 设置新成员可查看历史消息范围 | `--group` `--option` | -| `group get-mute-config` | 查询群用户禁言配置 | `--group` | -| `group-mute` | 全员禁言/解除全员禁言 | `--group`，默认禁言，`--off` 解除 | -| `group-mute-member` | 指定成员禁言/解除禁言 | `--group` `--user`/`--users`；禁言需 `--mute-time` | -| `group set-admin` | 设置/取消管理员 | `--group` `--user`/`--users`；`--off` 取消 | - -`update-settings` 是管理员级别的群功能开关操作，常用 settingKey：`authority`、`joinValidation`、`onlyAdminCanAtAll`、`searchable`、`addFriendForbidden`、`onlyAdminCanDING`、`onlyAdminCanPinMsg`、`onlyAdminCanSendFile`、`groupEmailDisabled`、`groupLiveAuthority`、`groupBillAuthority`。 - -`group user-settings` 是当前登录用户自己的群会话设置批量入口（置顶、免打扰、群昵称、群备注等），不是管理员级别的群功能开关；单个群昵称/群备注仍优先使用 `group update-nick` / `group update-alias`，管理员级别的群功能开关继续使用 `group update-settings`。 - -`group user-settings set --items` 传 JSON 数组，每个元素表示一个群会话的当前用户设置。字段含义： - -| 字段 | 含义 | 值说明 | -|------|------|--------| -| `openConversationId` | 群会话 ID | 必填，来自 `chat search` / `group list-all` 等真实返回 | -| `top` | 当前用户是否置顶该群会话 | `true`=置顶，`false`=取消置顶 | -| `mute` | 当前用户是否开启该群会话免打扰 | `true`=开启免打扰，`false`=关闭免打扰 | -| `groupNick` | 当前用户在该群里的群昵称 | 字符串；空字符串表示清空昵称 | -| `groupAlias` | 当前用户给该群设置的备注 | 字符串；空字符串表示清空备注 | - -只传本次要改的字段；不要补用户没要求修改的字段。批量设置多个群时，`items` 放多个对象。 - -`group-mute-member --mute-time` 单位毫秒，常用值：`300000`、`3600000`、`86400000`、`604800000`、`2592000000`。 - -`group share-invite` 的 `--source` 是被分享群的 `openConversationId`；`--target` 是接收分享消息的会话，`--receiver` 是接收分享消息的单聊用户 `openDingTalkId`，二者必须二选一。 - -```bash -dws chat group share-invite --source --target -dws chat group share-invite --source --receiver -dws chat group share-invite --source --target --expires-seconds 86400 --uuid -dws chat group user-settings query --groups , -dws chat group user-settings set --items '[{"openConversationId":"cid1","top":true,"mute":false}]' -``` - -### 群公告 - -群公告正文使用 Markdown。支持标题、加粗、斜体、删除线、行内代码、链接、代码块、列表、表格、引用、分割线、图片、段落和换行；下划线、字体色、背景色、字号属于编辑器专属能力，无法通过 Markdown 表达。 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `group notice create` | 发布群公告，支持置顶、DING 和定时发布 | `--group` `--content` | -| `group notice edit` | 整体替换指定群公告内容 | `--group` `--notice-id` `--content` | -| `group notice get` | 查询单条群公告详情 | `--group` `--notice-id` | -| `group notice list` | 分页拉取群公告列表 | `--group` | - -```bash -dws chat group notice create --group --content "今晚 22 点系统维护，请提前保存工作内容" -dws chat group notice create --group --content "# 重要通知\n\n请大家查收" --sticky --send-ding -dws chat group notice create --group --content "明早九点例会" --run-at "2026-07-03T09:00:00+08:00" -dws chat group notice list --group --limit 20 --cursor -dws chat group notice get --group --notice-id -dws chat group notice edit --group --notice-id --content "更新后的公告内容" -``` - -注意事项： - -- `notice edit` 会整体替换原公告正文，必须传完整的新内容。 -- `notice list --scheduled` 查询尚未到发布时间的定时公告；默认查询已发布公告。 -- `hasMore=true` 时，用返回的 `nextPageCursor` 继续翻页。 -- `notice get` 返回正文摘要、置顶状态、发布者、已读人数/应收人数、点赞/评论数、是否可编辑、是否已读、是否定时公告等信息。 - -### 群列表与入群审批 - -| 命令 | 用途 | 示例与要点 | -|------|------|------------| -| `group list-my-groups` | 拉取我创建/管理的群 | 可选 `--role OWNER/ADMIN`、`--limit`、`--exclude-muted` | -| `group list-all` | 分页拉取我加入的所有群 | `--limit` 默认 100，最大 200；翻页用 `nextCursor` | -| `group list-join-validations` | 拉取入群验证记录 | 包括自己被拒绝的记录以及作为审批者的记录 | -| `group audit-join-validation` | 审批入群验证 | `--group` `--record-id` `--applicant` `--inviter` `--status` | - -审批动作 `--status`：`AuditApprove`、`AuditDelete`、`AuditIgnore`、`AuditRefuse`、`AuditBlock`。 - -```bash -dws chat group list-join-validations --limit 20 -dws chat group audit-join-validation --group --record-id 123456 --applicant --inviter --status AuditApprove -``` - -### 群身份 - -`chat group-role` 管理群内自定义身份标签。 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `group-role list` | 查看群身份列表 | `--group` | -| `group-role add` | 新增群身份 | `--group` `--name` | -| `group-role update` | 修改群身份名称 | `--group` `--role-id` `--name` | -| `group-role remove` | 删除群身份 | `--group` `--role-id` | -| `group-role set-user` | 覆盖用户全部群身份，空 `--role-ids` 表示清除 | `--group` `--user` `--role-ids` | -| `group-role remove-user` | 移除用户指定群身份 | `--group` `--user` `--role-ids` | -| `group-role query-user` | 查询用户当前群身份 | `--group` `--user` | - -`openRoleId` 来自 `group-role list` 返回。 - -## 常见工作流 - -### 搜索群并发消息 - -```bash -dws chat +send-to-group --group "项目冲刺" --text "请大家看一下最新进展" --format json -``` - -### 建群并拉人 - -```bash -dws chat +chat-create --name "Q1 项目冲刺群" --member-query "张三,李四" --format json -dws chat +chat-create --name "合作群" --member-query "张三,李四" --owner-query "王五" --format json -dws chat group members add --id --users userId3,userId4 --format json -``` - -### 分享群邀请并发布公告 - -```bash -dws chat group share-invite --source --target --format json -dws chat group notice create --group --content "# 项目公告\n\n请大家关注最新安排" --send-ding --format json -``` - -### 设置管理员并禁言成员 - -```bash -dws chat group set-admin --group --users userId1,userId2 --format json -dws chat group-mute-member --group --users userId3 --mute-time 3600000 --format json -``` - -## 常见错误与回退 - -- 只有数字群号：先 `group get-by-group-id`，不要直接当 `--group`。 -- 找不到群：使用 `+chat-search --query` 扩大关键词；零命中或多候选时停止，不臆测 openConversationId。 -- 入群审批缺参数：从 `group list-join-validations` 提取 `record-id`、`applicant`、`inviter`。 -- 机器人进群失败：确认当前用户有群管理权限。 -- 分享群邀请目标不明确：`--target` 和 `--receiver` 只能二选一，先确认是发到群/会话还是发给个人。 -- 修改公告前没有完整新正文：先向用户确认完整公告内容，不要只传增量片段。 diff --git a/skills/multi/dingtalk-chat/references/chat/chat-message.md b/skills/multi/dingtalk-chat/references/chat/chat-message.md deleted file mode 100644 index 29c394f1..00000000 --- a/skills/multi/dingtalk-chat/references/chat/chat-message.md +++ /dev/null @@ -1,410 +0,0 @@ -# chat-message：消息、文件、搜索与卡片 - -> 返回入口：[chat.md](../chat.md) - -## 适用场景 - -用于当前用户发消息、拉消息、搜索消息、撤回、已读状态、文件/图片/音频/视频/位置/名片发送、话题回复、转发、Pin/Top、表情回应、文本翻译和流式卡片。 - -## 默认入口 - -| 用户终点 | 默认入口 | -|---|---| -| 按姓名发送简单文本/Markdown | `dws chat +dm` | -| 按群名发送简单文本/Markdown | `dws chat +send-to-group` | -| 文件、Bot、Webhook、复杂 @、已知 ID 或幂等发送 | `dws chat +messages-send` | -| 读取或导出指定群聊/单聊，可附带发送者姓名 | `dws chat +chat-messages`；姓名用非必填 `--sender-query` | -| 直接按发送者、关键词、@对象或消息类型搜索，可限定单个或跨多个会话 | `dws chat +search-msg` | -| 引用回复已有消息 | `dws chat +messages-reply` | -| 查看指定群内 @我的消息 | `dws chat +at-me --group <群名> --page-all` | -| 撤回当前用户消息 | `dws chat +messages-recall --msg-id ` | - -以下原子命令只用于 Shortcut 未暴露的底层字段、原始响应或精确分页控制。不得把它们重新写成 -上述高频任务的默认路径；写入原子命令若与 Golden Shortcut 的 confirmation 不一致，停止并 -报告交付漂移，不以文档确认代替 Runtime gate。 - -## 必读约束 - -- 发消息前必须核对接收对象、消息内容、@ 对象、附件路径和消息类型；不明确时先问用户。 -- `--group`、`--user`、`--open-dingtalk-id` 通常互斥，群聊用 `--group`，单聊用 `--user` 或 `--open-dingtalk-id`。 -- 发送本地文件、音频、视频默认用 `dws chat +messages-send --as user --file <相对路径>`； - `audio` / `video` 的具体类型以 leaf Schema 为准。只有 Shortcut 未暴露的位置、名片等底层 - 类型才进入本文件的原子 fallback。 -- 发送位置消息前必须确认纬度、经度、地址名称；地图缩略图需先通过旧媒体上传链路拿到 mediaId。 -- 分享联系人名片前必须确认联系人 `openDingTalkId`，不要把 userId 直接当 `--contact-id`。 -- 消息内容按 Markdown 渲染，换行必须是真实换行符；需要换行效果时用空行、行尾两个空格或 `
`。 -- 图文混排 Markdown 中，公网图片 URL 需要写成 `![图片标题](https://example.com/image.png)` 才会以内联图片展示；省略开头的 `!` 时会按链接/URL 展示，不会渲染为图片。 -- 建议发送时带 `--uuid`，失败重试复用同一个值。 -- Bot/Webhook 只支持文本/Markdown；Bot 多群使用 `+messages-send --groups/--groups-file` 的逐项 - ledger。不要把 user 文件/图片能力外推到 Bot。 -- `+at-me` 和 `+messages-list-direct` 要求全量时使用 `--page-all`，并检查 `complete`、 - `hasMore`、`stopReason` 和 `failures`；`+messages-list-direct` 的续页时间来自下层毫秒 - `nextCursor`，不得用只有秒精度的消息展示时间手工拼接。 - -## 原子 fallback 命令明细 - -### 发送消息的底层 fallback - -#### `dws chat message send`（非默认入口） - -以当前用户身份发送群聊或单聊消息。 - -```bash -# 文本/Markdown -dws chat message send --group --text "hello" -dws chat message send --user --text "请查收" -dws chat message send --open-dingtalk-id --text "请查收" -dws chat message send --group --title "周报提醒" --text "请大家本周五前提交周报" --uuid -dws chat message send --group --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' - -# @ 群成员 -dws chat message send --group --at-all "<@all> 请大家注意" -dws chat message send --group --at-open-dingtalk-ids odt1,odt2 "<@odt1> <@odt2> 请查收" - -# 图片/文件/音频/视频，一条命令直发 -dws chat message send --group --msg-type file --file-path ./screenshot.png -dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf -dws chat message send --group --msg-type audio --file-path ./voice.mp3 -dws chat message send --group --msg-type video --file-path ./demo.mp4 - -# 位置/联系人名片 -dws chat message send --group --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --map-thumbnail-url "@mediaId" -dws chat message send --group --msg-type profile --contact-id -``` - -关键 flags： - -| Flag | 说明 | -|------|------| -| `--group` | 群聊 openConversationId；别名 `--id` / `--chat` / `--conversation-id` | -| `--user` | 单聊接收人 userId | -| `--open-dingtalk-id` | 单聊接收人 openDingTalkId | -| `--text` | 消息内容，推荐使用；也支持位置参数 | -| `--title` | 消息标题，未传时使用安全标题 | -| `--at-all` | 群聊 @所有人，正文需含 `<@all>` | -| `--at-open-dingtalk-ids` | 群聊 @指定 openDingTalkId，正文需含 `<@id>` | -| `--msg-type` | `file` / `audio` / `video` / `image` / `location` / `profile`；本地音视频用 `audio` / `video`，底层按 `file` 发送 | -| `--file-path` | 本地文件路径，`msg-type=file/audio/video` 时自动上传并发送 | -| `--media-id` | 旧图片链路 mediaId | -| `--latitude` / `--longitude` / `--location-name` | 位置消息参数 | -| `--map-thumbnail-url` | 位置消息缩略图 mediaId，形如 `@mediaId` | -| `--contact-id` | 联系人名片 openDingTalkId | -| `--uuid` | 幂等 UUID，24h 内相同值不重复投递 | - -当前没有经过验证的 Thread writer。`openConvThreadId` 只用于 `+thread-replies` 读取或 -`+messages-forward-topic` 转发；不要把它作为普通 `--group` 猜测写入。引用回复使用 -`+messages-reply`，但这不等于 Thread 内新增回复。 - -读取话题回复可直接传话题主消息 `--message-id`，CLI 会先通过只读消息详情解析出 -`conversationId/threadId`；也可显式传 `--group` 加 `--thread-id/--topic-id`。前一种模式如果同时传 -`--group`，会校验它与消息解析出的会话一致；解析失败只会报错，不会错误转去查询通讯录。 - -默认只读一页；完整读取必须显式加 `--page-all`。可用 -`--limit/--page-size` 控制每页条数、用 `--page-limit` 限制最大页数；自动续页使用下层返回的 -毫秒级 `nextCursor` 无损生成下一次 `startTime`，不能使用只有秒级精度的回复 `createTime`。 -输出默认 `--order desc`（兼容 `--sort`）。由于下层的 `newer/older` 表示读取方向而不是结果排序， -`asc` 只允许与 `--page-all` 一起使用：完整拉取后对整体结果升序排列，避免把单个“最新页”的本地反转 -伪装为全局升序。结果中的 `orderScope=complete_result` 表示完整结果排序；读取被页数上限或错误截断时为 -`fetched_pages`，并仍须结合完整性 ledger 判断。 -必须检查 `complete`、`hasMore`、`stopReason` 和 -`failures`，`complete=false` 时不得声称已经拿到全部回复。 - -```bash -dws chat +thread-replies --message-id --page-all --order asc -dws chat +thread-replies --group --thread-id --page-all --page-limit 50 -``` - -### 拉取消息的底层 fallback - -默认使用 `dws chat +chat-messages`。群聊的 `--group` 可传群名或 openConversationId； -也可用 `--chat-query` 显式按群名解析、用 `--conversation-id` 显式传稳定 ID。全量读取加 `--page-all`，必要时用 `--page-limit`、 -`--max-results` 控制边界，用 `--output <相对.json>` 原子导出。只有需要原始响应或显式手工 -continuation 时才使用下表；原子 `message list` 不代表自动全量分页。 - -可附带非必填的 `--sender-query <姓名>` 做读取后筛选。未传姓名时正常返回全部；姓名未解析出稳定 ID 时保留全部并记录失败；唯一解析出 userId/openDingTalkId 后按消息 `senderId` 筛选，覆盖最终 `messages/count` 并返回 `resolvedFilters`。该调用已经完成读取、解析与筛选，不要补跑 `+search-msg`。 - -时间范围参数同样公开但非必填：`--start`（包含）、`--end`（不包含）、`--order asc|desc`， -兼容别名为 `--start-time/--end-time/--sort`。范围固定为 `[start,end)`；仅开始时间表示到本次执行当前时间， -仅结束时间只支持 `desc`，`asc` 必须提供开始时间。旧 `--time/--direction` 保持兼容但不能和范围模式混用。 - -```bash -dws chat +chat-messages --group "项目群" --sender-query "测试用户甲" --page-all --format json -dws chat +chat-messages --group "项目群" --start "2026-08-01T00:00:00+08:00" --end "2026-08-02T00:00:00+08:00" --order asc --page-all --format json -``` - -当会话已经确定、任务只需要完整读取结果中可由消息字段判断的子集时，不新增按条件专用的 -Shortcut 参数。在同一次 `+chat-messages` 调用中使用全局 `--jq`，让 Runtime 完成读取后、 -在 stdout 前筛选；表达式必须保留根信封、用筛选结果覆盖 `messages` 并同步重算 `count`， -不得丢失 `complete`、`hasMore`、`failures` 等完整性 ledger。不要先输出全量 JSON，再由 -Agent 或另一条命令二次处理。 - -```bash -# 例：读取完整会话后，只返回存在 reaction 的消息 -dws chat +chat-messages --group "项目群" --page-all --format json \ - --jq '. as $root | [.messages[] | select((.reactions // []) | length > 0)] as $matched | $root | .messages = $matched | .count = ($matched | length)' -``` - -发送者姓名不是普通结果字段条件：仍用 `--sender-query <姓名>` 先解析稳定身份，再按 -`senderId` 筛选，不能用 `--jq` 对展示名做字符串匹配。 - -| 命令 | 用途 | 示例与要点 | -|------|------|------------| -| `message list` | 拉取指定群聊或单聊消息 | `dws chat message list --group --time "2025-03-01 00:00:00" --direction older`；目标三选一，`--direction newer/older` 优先于旧 `--forward` | -| `message list-all` | 时间范围内全部会话消息 | `dws chat message list-all --start --end --limit 100 --cursor 0`；默认一页，完整遍历加 `--page-all`，保留并合并 `result.conversationMessagesList` | -| `message list-by-sender` | 查指定发送者消息 | `--sender-user-id` 与 `--sender-open-dingtalk-id` 二选一，跨单聊+群聊；完整遍历加 `--page-all`，同一会话跨页合并 messages | -| `message list-mentions` | 查 @ 我的消息 | 可传 `--group` 限定群，不传查全部；完整遍历加 `--page-all`，同一会话跨页合并 messages | -| `message list-focused` | 查特别关注人消息 | 零参数可用，可加 `--limit` / `--cursor`；完整遍历加 `--page-all`，cursor 为 int64 | -| `message list-unread-conversations` | 未读会话列表 | 可选 `--count` | -| `message list-topic-replies` | 拉取话题回复 | `--group --topic-id ` | -| `message list-by-ids` | 按消息 ID 批量查询 | `--msg-ids msgId1,msgId2`，最多 50 条 | - -Typed `chat message` 自动翻页只由 `--page-all` 触发；只传 `--page-limit`、`--max-items` 或 `--page-delay` 仍保持默认单页 fallback。`conversationMessagesList` 结构会保留并按 `openConversationId` 合并 messages。分页元数据输出到顶层 `paging`，包含 `truncated`、`hasMore`、`lastCursor`、`pages`、`total`；非第一页失败时会输出 partial 结果和 `failedPage` / `failedCursor` / `pagesFetched` / `itemsFetched`。 - -`message list` 注意事项： - -- `--group`、`--user`、`--open-dingtalk-id` 互斥且必须指定一个。 -- `--time` 格式为 `yyyy-MM-dd HH:mm:ss`。 -- `hasMore=true` 时，用结果中的边界 `createTime` 作为下次 `--time`。 -- 返回 `openConvThreadId` 表示话题消息，完整内容需再拉 `list-topic-replies`。 - -### 搜索消息的底层 fallback - -直接按发送者、关键词、@对象或消息类型检索时优先使用 `dws chat +search-msg`；搜索范围可以是单个、多个或全部会话。若已选择 `+chat-messages` 读取指定会话，可由其非必填 `--sender-query` 在同一次调用完成姓名解析和筛选。 - -- 搜索内容使用公开参数 `--query`。 -- 已知稳定会话 ID 使用 `--group` / `--groups`；已知稳定发送者 ID 使用 `--senders`。 -- 只有群名时使用非必填参数 `--chat-query`，由 CLI 唯一解析会话。 -- 只有发送者姓名时使用非必填参数 `--sender-query`，由 CLI 唯一解析人员。 -- 不要把群名传给只接受稳定 ID 的会话参数，也不要把姓名传给 `--senders`。零命中或多候选时停止，不选择第一项。 -- 不传会话过滤时搜索全部会话；`--page-all` 只翻完当前时间范围内的游标页，默认时间范围是最近 7 天。 -- 精确范围使用成对的 `--start/--end`（兼容 `--start-time/--end-time`）；`--order`（兼容 `--sort`）稳定排列本次实际取得的结果。未 `--page-all` 或 `complete=false` 时不能称为完整范围的全局排序。 - -需要 Shortcut 未暴露的原始过滤字段或响应时，才评估 `message search-advanced`。它是原子 `message search` 的严格超集，但不是 Agent 高频默认入口。 - -```bash -# 单群 + 发送者姓名 -dws chat +search-msg --chat-query "项目群" --sender-query "测试用户甲" --page-all --format json - -# 单群 + 关键词 -dws chat +search-msg --chat-query "项目群" --query "发布计划" --page-all --format json - -# 跨全部会话 + 发送者姓名 -dws chat +search-msg --sender-query "测试用户甲" --page-all --format json -dws chat +search-msg --query "发布计划" --start-time "2026-08-01T00:00:00+08:00" --end-time "2026-08-02T00:00:00+08:00" --sort asc --page-all --format json -``` - -```bash -dws chat message search-advanced --query "周报" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" -dws chat message search-advanced --user --start --end -dws chat message search-advanced --at-me --start --end -dws chat message search-advanced --conversation-ids , --query "合同" --limit 50 --cursor 0 -dws chat message search-advanced --query "周报" --start --end --page-all --max-items 200 -dws chat message search-advanced --message-type file --search-conv-type group_chat --query "附件" -dws chat message search-advanced --only-robot-messages --query "通知" -``` - -| 参数 | 说明 | -|------|------| -| `--query` | 搜索关键词，可选 | -| `--user` / `--users` | 发送者 userId | -| `--sender-ids` | 发送者 openDingTalkId | -| `--at-me` / `--at-ids` | @ 我 / @ 指定 openDingTalkId | -| `--conversation-ids` | 多个群聊或单聊 openConversationId；别名 `--groups` | -| `--message-type` | 按消息类型过滤，例如 `file` | -| `--search-conv-type` | 按会话类型过滤，例如 `group_chat` | -| `--only-robot-messages` | 只搜索机器人消息 | -| `--start` / `--end` | ISO-8601 时间范围 | -| `--cursor` / `--limit` | 分页，翻页用 `nextCursor` | -| `--page-all` / `--page-limit` / `--max-items` / `--page-delay` | 自动翻页；`--page-all` 是唯一触发开关 | - -仅简单关键词搜索时可用： - -```bash -dws chat message search --query "changefree" --start --end --limit 50 --cursor 0 -dws chat message search --query "codereview" --group --start --end -dws chat message search --query "发布计划" --start --end --page-all --page-delay 0 -``` - -### 消息状态与撤回 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `message query-send-status` | 查询当前用户发消息任务状态 | `--open-task-id`，来自 `message send` 返回 | -| `+messages-recall` | 撤回当前用户消息 | `--msg-id`；可选 `--conversation-id`，省略时 CLI 从消息详情补齐；兼容单值 `--message-ids` | -| `message edit` | 编辑已发送消息内容 | `--conversation-id` `--msg-id`，并在 `--text` / `--content` 中二选一；可选 `--title` `--at-all` `--at-open-dingtalk-ids` | -| `message read-status` | 查消息已读/未读状态 | `--group` `--message-id`；可选目标用户 | - -刚由 `message send` 发出的消息会返回 `openTaskId`。先用 `message query-send-status` 查询，成功结果中的 `openMessageId` 和 `openConversationId` 可直接传给 `message edit` 或 `message recall`，无需再按消息内容从列表反查 ID。 - -```bash -# 1. 发送后保留 openTaskId -dws chat message send --group --text "原始内容" -# 2. 查询得到 openMessageId 和 openConversationId -dws chat message query-send-status --open-task-id -# 3. 编辑消息 -dws chat message edit --conversation-id --msg-id --text "更新后的内容" - -# 发送后撤回使用同一 ID 链 -dws chat message send --group --text "待撤回的内容" -dws chat message query-send-status --open-task-id -dws chat message recall --conversation-id --msg-id -``` - -`+messages-recall` 与 `recall-by-bot` 不同：前者使用 `openMessageId`，缺少会话 ID 时先只读查询消息详情；后者撤回机器人消息，需要 `robot-code + processQueryKey`。不要把 `processQueryKey` 当 `openMessageId`。 - -编辑消息使用 `message edit`。推荐传 `--text`，CLI 会生成 markdown content JSON：`{"title":"标题","text":"正文"}`；可选 `--title`，不传时会从正文自动生成标题。高级场景可直接传 `--content`，此时必须是完整 markdown content JSON，且不能同时传 `--text`。 - -@ 规则：`--at-all` 会传 `atAll=true`，正文应包含 `<@all>`，未包含时 CLI 会自动补到开头；`--at-open-dingtalk-ids` 会传 `atOpenDingTalkIds`，正文需包含对应 `<@openDingTalkId>` 占位符，裸 `@openDingTalkId` 会自动补成尖括号格式。 - -```bash -dws chat message edit --conversation-id --msg-id --text "更新后的内容" -dws chat message edit --group --msg-id --title "标题" --text "更新后的内容" -dws chat message edit --group --msg-id --text "<@all> 请查看" --at-all -dws chat message edit --group --msg-id --text "<@openDingTalkId1> 请查看" --at-open-dingtalk-ids -dws chat message edit --group --msg-id --content '{"title":"标题","text":"更新后的内容"}' -``` - -### 回复与转发的底层 fallback - -引用回复默认使用 `dws chat +messages-reply`。以下原子 reply 只保留底层字段 fallback；转发 -仍按各自精确 Shortcut/leaf Schema 选择。 - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `message reply` | 引用回复，单聊/群聊均可；群聊可 @指定成员或 @所有人 | `--conversation-id` `--ref-msg-id` `--ref-sender` `--text`；可选 `--at-open-dingtalk-ids` `--at-all` | -| `message forward` | 转发单条消息，源/目标均支持单聊/群聊 | `--src-conversation-id` `--msg-id` `--dest-conversation-id` | -| `message combine-forward` | 多条消息合并为一条转发 | `--src-conversation-id` `--msg-ids` `--dest-conversation-id`，可选 `--uuid` | -| `message forward-topic` | 转发话题消息 | `--src-msg-id` `--src-conversation-id` `--src-thread-id` `--dest-conversation-id` | - -群聊引用回复使用 `--at-open-dingtalk-ids` 传 `atOpenDingTalkIds`；正文缺少对应 `<@openDingTalkId>` 时自动补齐，已有裸 `@openDingTalkId` 会规范化。`--at-all` 会传 `atAll=true`，正文缺少 `<@all>` 时自动补齐。 - -```bash -dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "请看一下" --at-open-dingtalk-ids -dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "请大家确认" --at-all -``` - -### 话题与卡片 - -话题完整读取流程： - -1. `dws chat message list --group --time ...` 获取话题主消息。 -2. 如果返回 `openConvThreadId`，执行 `dws chat message list-topic-replies --group --topic-id `。 - -流式卡片优先使用公开 Shortcut；创建可选在同一次调用中写入内容： - -```bash -dws chat +messages-send-card --group --at-open-dingtalk-ids --content "开始处理" --flow-status 1 -dws chat +messages-update-card --biz-id --content "更新的卡片内容" --flow-status 2 -dws chat +messages-update-card --biz-id --content "最终内容" --flow-status 3 -``` - -`flow-status`：1=处理中，2=输入中，3=完成，4=执行中，5=错误，Runtime 拒绝范围外值。 -群聊还可传 `--at-all`；两种艾特参数只随创建请求发送。send-card 同时带正文时， -Runtime 会把创建响应的 `atTag` 自动放在正文前；不要自行写 ID 或占位符。 -当前只支持 streaming text；不支持 Card JSON 组件或 action callback。精确边界见 -[card references](../card/schema.md)。 - -### Pin / Top / Favorite - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `message set-pin-msg` / `unset-pin-msg` | 钉住/取消钉住消息 | `--open-conversation-id` `--msg-id` | -| `message list-pin-msg` | 拉取钉住消息列表 | `--open-conversation-id`，可选 `--cursor` `--size` | -| `message set-top-msg` / `unset-top-msg` | 置顶/取消置顶会话内某条消息 | `--open-conversation-id` `--msg-id` | -| `message add-favorite` | 收藏消息 | `--open-message-id` `--open-conversation-id` | -| `message remove-favorite` | 取消收藏消息 | `--open-message-id` `--open-conversation-id` | -| `+flag-list` | 查询收藏消息列表的默认 Shortcut | 默认一页；要求全部时加 `--page-all`；`--page-size/--size` 范围为 1-30，可用 `--page-token` 或兼容的 `--cursor` 续页，检查 `complete` / `failures` | -| `message list-favorites` | typed 收藏消息列表 | 默认一页；完整遍历加 `--page-all`，数字 cursor，聚合 `result.items`；可选 `--cursor` `--size` | - -`+flag-list` 查询钉钉 message favorite，底层使用数字 cursor；它与消息 Pin、消息 Top 和会话置顶属于不同对象层级。 -`message list-favorites --page-all` 仍遵守 `--size` 1-30；`--page-limit` 只控制最多请求页数，`--max-items` 可精确截断输出。 -消息置顶 `set-top-msg` 与会话置顶 `chat set-top` 不同：前者置顶会话内消息，后者置顶整个会话。 - -### 表情回应 - -优先查 [chat-emoji-list.md](../chat-emoji-list.md) 中的默认表情名称。 - -| 命令 | 场景 | 必填参数 | -|------|------|----------| -| `message add-emoji` / `remove-emoji` | 默认表情命中时使用 | `--conversation-id` `--msg-id` `--emoji` | -| `message create-text-emotion` | 默认表情没有合适项时先创建 | `--emotion-name` `--text`，可选 `--background-id` | -| `message add-text-emotion` / `remove-text-emotion` | 添加/移除文字表情 | `--conversation-id` `--msg-id` `--emotion-id` `--emotion-name` `--text` `--background-id` | -| `message update-text-emotion` | 用新的文字表情替换消息上的原回应 | `--conversation-id` `--msg-id` `--old-emotion-id` `--emotion-id` `--emotion-name` `--text` `--background-id` | -| `message list-emotion-replies` | 批量查询消息的表情回复和文字回复 | `--msg-ids` | - -```bash -dws chat message list-emotion-replies --msg-ids msgId1,msgId2,msgId3 -``` - -消息 ID 可通过 `dws chat message list` 获取；该命令用于一次性查看多条消息上的 emoji 回应和文字表情回应。 - -### 文本工具 - -#### `dws chat text translate` - -将指定文本翻译成目标语言。用户只说“翻译这段文字”时使用；不要误走 `message send`。 - -```bash -dws chat text translate --query "你好世界" --to en_US -dws chat text translate --query "Hello World" --to zh_CN -dws chat text translate --query "Bonjour" --to ja_JP -``` - -关键 flags： - -| Flag | 说明 | -|------|------| -| `--query` | 待翻译文本，必填 | -| `--to` | 目标语言代码，必填，默认 `en_US` | - -### 文件与媒体 - -#### `dws chat message download-media` - -```bash -dws chat message download-media --type mediaId --resource-id --message-id --open-conversation-id --output ./downloads/ -``` - -`resource-id` 来自消息内容中的 mediaId，`message-id` 来自 `openMessageId`，会话 ID 来自 `chat search` 或 `conversation-info`。 - -公开 `+messages-resource-download` 使用工作目录内安全相对路径、默认不覆盖、整文件临时落盘后 -原子发布。当前没有 Range/断点续传；失败时保留 ledger 或错误，显式重试整个文件，不拼接残片。 - -## 常见工作流 - -### 群聊发文字与文件 - -```bash -dws chat +send-to-group --group "项目冲刺" --text "请大家本周五前提交周报" --format json -dws chat +messages-send --as user --chat-query "项目冲刺" --file ./report.pdf --uuid --format json -dws chat +messages-send --as user --chat-query "项目冲刺" --msg-type audio --file ./voice.mp3 --uuid --format json -dws chat +messages-send --as user --chat-query "项目冲刺" --msg-type video --file ./demo.mp4 --uuid --format json - -# 仅 Shortcut 尚未覆盖的位置/名片底层类型才使用原子 fallback -dws chat message send --group --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --map-thumbnail-url "@mediaId" --format json -dws chat message send --group --msg-type profile --contact-id --format json -``` - -### 查消息并撤回 - -```bash -dws chat +chat-messages --group --direction older --format json -dws chat +messages-recall --msg-id --format json -``` - -### 多维度搜索 - -```bash -dws chat message search-advanced --query "合同" --conversation-ids , --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 50 --cursor 0 --format json -dws chat message search-advanced --message-type file --search-conv-type group_chat --query "附件" --format json -``` - -## 常见错误与回退 - -- 发送目标不唯一：保留 resolver 返回的候选并让用户消歧；不要退回手工搜索后选择第一项。 -- `unknown flag`：立即执行对应命令 `--help`，不要猜参数。 -- 文件/音视频发送失败：确认本地路径可读；新链路使用 `--msg-type file|audio|video --file-path`。 -- 位置消息参数不完整：先确认经纬度、地址名称和缩略图 mediaId。 -- 名片发送失败：确认 `--contact-id` 是 openDingTalkId，不是 userId。 -- 话题回复缺失：检查是否只拉了主消息，需继续用 `list-topic-replies`。 -- `search-advanced` 无条件：至少提供 query、sender、@、conversation、时间等任一有效过滤条件。 diff --git a/skills/multi/dingtalk-chat/references/chat/group-admin.md b/skills/multi/dingtalk-chat/references/chat/group-admin.md new file mode 100644 index 00000000..1ae09c39 --- /dev/null +++ b/skills/multi/dingtalk-chat/references/chat/group-admin.md @@ -0,0 +1,144 @@ +# group-admin：群创建、成员写入与管理 + +> 返回入口：[DingTalk Chat Skill](../../SKILL.md) + +用于建群、修改群资料、成员增删、邀请卡片分享、群主和管理员、禁言、公告、群设置、 +入群审批、群身份、退出、解散和升级外部群。只读群发现、成员读取和邀请链接使用 +[group-discovery.md](group-discovery.md)。 + +## 安全与目标 + +- 群目标统一使用当前 profile 下真实 `openConversationId`；支持自然群名的 Shortcut 由 CLI + 唯一解析，多候选时停止。 +- 解散群、踢人、转让群主、禁言、管理员和外部群升级都是高影响操作；以最终 Runtime gate + 和精确 leaf Schema 为准确认对象、动作与影响。 +- 所有自然成员和群主必须先完成唯一解析并按稳定 ID 去重，再开始任何写入；不得边解析边 + 产生部分副作用。 +- 群公告会触达成员；`notice edit` 是整体替换，必须有完整新正文。 + +## 建群与基础资料 + +基础建群使用 `dws chat +chat-create`。已知成员 ID 传 `--users`， +姓名/花名传 `--member-query`；群主默认当前用户，也可传 `--owner-open-dingtalk-id` 或 +`--owner-query`。任一自然身份未唯一解析时，创建前整体停止。 + +```bash +dws chat +chat-create --name "项目冲刺群" --member-query "测试用户甲,测试用户乙" --format json +dws chat +chat-create --name "合作群" --member-query "测试用户甲" \ + --owner-query "测试用户乙" --type EXTERNAL --format json +``` + +修改群名称优先使用接受群名或稳定 ID 的 `+chat-update`： + +```bash +dws chat +chat-update --group <群名或openConversationId> --name "新群名" --format json +``` + +群头像和管理员级群开关使用 `+chat-update-icon`、`+chat-update-settings`；只有 Shortcut +尚未发布真实必需字段时才评估原子 `group rename/update-icon/update-settings`。 + +原子 `chat group create` 只用于 `+chat-create` 未发布的真实底层字段，并先读取精确 leaf +Schema。普通内部/外部群、话题群和显式群主已经由 `+chat-create` 覆盖，不回流到手工 +`aisearch → group create` 链路。 + +## 成员与机器人写入 + +| 动作 | 入口与关键参数 | +|---|---| +| 添加成员 | `group members add --id --users ` | +| 移除成员 | `group members remove --id --users ` | +| 添加已知机器人 | `+chat-add-bot` 或精确原子 `group members add-bot` | +| 查看群内机器人 | `+chat-bots --group <群名或cid>` | +| 移除群内机器人 | `+chat-remove-bot` 或精确原子 `group members remove-bot` | + +普通成员增删的 `--users` 只接受组织 `userId`，必须来自真实人员解析结果；不得把 +`+chat-members-list` / `+chat-members-get` 返回的 `openDingTalkId` 直接传入。添加已知机器人 +使用 `robotCode`；移除机器人使用当前群 `+chat-bots` 返回的真实 `openBotId`，两者不能互换。 +缺少 `openBotId` 时在同一流程中先执行 `+chat-bots`，不必额外读取群发现 reference。只有需要 +搜索未知机器人、区分 `bot search` / `bot find`、机器人发送或撤回、Webhook 时，才读取 +[chat-bot.md](chat-bot.md)。 + +## 邀请卡片、群主、管理员与禁言 + +邀请链接只读走 `+chat-invite-url`。实际分享邀请卡片使用 `group share-invite`：`--source` +是被分享群，接收端在 `--target` 会话和 `--receiver` 单聊用户之间二选一。 + +```bash +dws chat group share-invite --source --target --format json +dws chat group share-invite --source --receiver --format json +``` + +| 动作 | 入口与关键参数 | +|---|---| +| 转让群主 | `+chat-transfer-owner --group --new-owner <稳定ID>` | +| 设置/取消管理员 | `group set-admin --group --users [--off]` | +| 全员禁言/解除 | `group-mute --group [--off]` | +| 成员禁言/解除 | `+chat-mute-member` 或 `group-mute-member` | +| 查询禁言配置 | `group get-mute-config --group ` | + +原子 `group-mute-member --mute-time` 单位为毫秒。不要用展示名称代替稳定用户 ID，也不要 +在未确认影响时执行转让、踢人或禁言。 + +## 群设置与当前用户偏好 + +管理员级群开关使用 `+chat-update-settings` 或原子 `group update-settings`。常见 settingKey +包括 `authority`、`joinValidation`、`onlyAdminCanAtAll`、`searchable`、 +`addFriendForbidden`、`onlyAdminCanDING`、`onlyAdminCanPinMsg` 和 +`onlyAdminCanSendFile`、`groupEmailDisabled`、`groupLiveAuthority`、 +`groupBillAuthority`；只修改用户明确要求的字段。 + +新成员历史消息可见范围使用 `group set-history --group --option <值>`；`option` 只取 +精确 leaf Schema 发布值，不按自然语言猜枚举。 + +当前登录用户自己的置顶、免打扰、群昵称和群备注使用 `group user-settings query/set`， +不是管理员群开关。单个群昵称/备注优先 `group update-nick/update-alias`。 + +```bash +dws chat group user-settings query --groups , --format json +dws chat group user-settings set \ + --items '[{"openConversationId":"cid1","top":true,"mute":false}]' --format json +``` + +批量设置只传本次要改的字段；空字符串清除昵称或备注，不补用户未要求的值。 + +## 群公告 + +| 动作 | 原子入口 | +|---|---| +| 发布公告 | `group notice create --group --content <完整Markdown>` | +| 修改公告 | `group notice edit --group --notice-id --content <完整Markdown>` | +| 查询公告 | `group notice get/list` | + +定时公告 `--run-at` 使用带时区时间；`notice list --scheduled` 查询待发布公告。分页时沿真实 +`nextPageCursor` 继续。修改前必须取得完整替换正文，不把增量片段当整篇公告。 + +## 入群审批与群身份 + +先用 `group list-join-validations` 取得真实 `record-id/applicant/inviter`，再执行 +`group audit-join-validation` 或 `+chat-audit-join`。审批状态只使用精确 leaf Schema 发布值。 + +群身份使用 `group-role` / `+chat-role-*`： + +- `list/add/update/remove` 管理身份定义； +- `set-user/remove-user/query-user` 管理成员身份； +- `openRoleId` 必须来自真实身份列表。 + +覆盖或清除成员身份前确认用户、群和完整角色集合，不能用展示名称猜 `openRoleId`。 + +## 退出、解散与外部群升级 + +- 当前用户退出群：`+chat-quit` 或精确原子 `group quit`。 +- 解散群：`group dismiss`，不可逆。 +- 普通群升级外部群：`group upgrade-to-external`，不可逆。 + +这些动作必须以最终 Runtime gate 为准，不把示例中的确认参数当固定事实。 + +## 完成与错误 + +- 创建或更新后保留真实 `openConversationId` 和任务结果；只对查询结果真实返回的字段执行读回验证。 +- 写接口成功但现有查询未返回目标设置时，报告真实写入回执和不可独立读回的边界；不用群名、 + 成员数等其他字段代替验证，也不猜未发布的读回命令。 +- 任一自然目标零命中或多候选时，在写入前整体停止。 +- 逐项写入保留 succeeded/failed/unknown ledger，不用重试抹掉失败项。 +- 分享邀请时 `--target` 与 `--receiver` 只能二选一；接收对象不明确时先确认。 +- 机器人进群失败时确认机器人身份和当前用户管理权限，不连续切换同义原子命令。 diff --git a/skills/multi/dingtalk-chat/references/chat/group-discovery.md b/skills/multi/dingtalk-chat/references/chat/group-discovery.md new file mode 100644 index 00000000..7a091abc --- /dev/null +++ b/skills/multi/dingtalk-chat/references/chat/group-discovery.md @@ -0,0 +1,121 @@ +# group-discovery：群发现、列表与成员读取 + +> 返回入口：[DingTalk Chat Skill](../../SKILL.md) + +用于只读的群列表、群搜索、共同群、群成员、群机器人和邀请链接。建群、改群、成员增删、 +邀请卡片分享、公告、禁言和其他群管理写操作读取 [group-admin.md](group-admin.md)。 + +## 入口选择 + +| 用户终点 | 唯一推荐入口 | +|---|---| +| 我加入的全部群 | `dws chat +my-groups --page-all` | +| 我创建或管理的群 | `dws chat +chat-list-mine` | +| 只看群主群或管理员群 | `+chat-list-mine --role OWNER|ADMIN` | +| 按关键词搜索群 | `dws chat +chat-search --query <关键词>` | +| 查看指定群全部成员 | `dws chat +chat-members-list --group <群名或ID>` | +| 已知成员 openDingTalkId 批量查群内详情 | `dws chat +chat-members-get --id --users ` | +| 获取群邀请链接 | `dws chat +chat-invite-url --group <群名或ID>` | +| 查看群机器人 | `dws chat +chat-bots --group <群名或ID>` | + +“全部群”与“全部会话”不同：`+my-groups` 只列当前用户加入的群； +`+conversation-list --page-all` 可能同时包含单聊和群聊，不能替代群成员关系。 + +## 群列表、分页与角色 + +`+my-groups` 返回当前用户加入的群，包括作为群主、管理员和普通成员加入的群： + +- 要求完整列表时使用 `--page-all`；Runtime 沿真实 `nextCursor` 读取后续页，并按 + `openConversationId` 合并去重，读完后再应用可选 `--type` 本地过滤。 +- `--limit` 是每页数量，不是最终结果上限；`--cursor` 只用于从已有 `nextCursor` 手工续读。 +- `--page-limit` 只与 `--page-all` 一起使用，用于限制最多读取页数。达到上限后仍有下一页时， + 结果不完整。 +- 只有 `complete=true` 且 `hasMore=false` 才能声称已经读取全部；否则保留 `nextCursor`、 + `stopReason` 和 `failures` 并说明结果不完整。 + +```bash +dws chat +my-groups --page-all --page-limit 50 --format json +``` + +`+chat-list-mine` 只返回当前用户作为群主或管理员的群。只要群集合时不传 `--role`， +一次取得 OWNER 和 ADMIN。要求逐项标明身份时，直接分别查询 `--role OWNER` 和 +`--role ADMIN`，不先执行无角色查询或读取 Help；按 `openConversationId` 合并去重后， +再应用一次全局数量上限，不得把两个分支直接拼接。 + +```bash +dws chat +chat-list-mine --limit 20 --format json +dws chat +chat-list-mine --role OWNER --format json +dws chat +chat-list-mine --role ADMIN --exclude-muted --format json +``` + +`+my-groups` 不提供当前用户角色。用户明确要求普通成员群时，使用 +`chat group list-all --limit 200`；返回 `hasMore=true` 时，必须把真实 `nextCursor` +传给下一次调用并继续读取，直到 `hasMore=false`，不得把继续翻页交给用户。读完后按 +`openConversationId` 去重，仅筛选真实返回的 `myRole=普通成员`；不得给 `+my-groups` +编造 `--role MEMBER`，也不得用“全部群减去 OWNER/ADMIN 群”推断。 + +## 群搜索与稳定 ID + +群搜索默认使用 `+chat-search`。要求全部候选时加 `--page-all`；可用 +`--page-size/--page-token` 或兼容 `--limit/--cursor`。零命中或多候选时停止并展示候选， +不要选择第一项。 + +```bash +dws chat +chat-search --query "项目冲刺" --page-all --format json +``` + +只有数字群号时，使用 `chat group get-by-group-id --group-id <数字>` 转换为 +`openConversationId`。需要搜索共同群时使用原子 `chat search-common`；`AND` 表示所有人 +都在群里，`OR` 表示任一人在群里。自然人员必须先解析为当前 profile 的真实身份。 + +```bash +dws chat search-common --nicks "测试用户甲,测试用户乙" --match-mode AND --limit 20 --cursor 0 +``` + +## 群成员 + +`+chat-members-list` 接受群名或 `openConversationId`，唯一解析后全量读取，并把用户与机器人 +分桶。结果必须检查 `buckets/complete/failures`。 + +```bash +dws chat +chat-members-list --group "项目群" --format json +dws chat +chat-members-list --conversation-id --format json +``` + +先检查 `+chat-members-list` 的稳定结果。只有结果未包含用户要求的群昵称、角色或其他群内字段时， +才使用其中的真实 `openDingTalkId` 批量调用： + +```bash +dws chat +chat-members-get --id \ + --users , --format json +``` + +不要为了群内详情默认切换到企业通讯录；只有用户明确要求部门、岗位、直属主管等企业资料时， +才把真实 userId 交给 `dingtalk-contact`。 + +## 邀请链接与机器人 + +`+chat-invite-url` 是只读获取链接，可选 `--expires-seconds`；`group share-invite` 会实际把 +邀请卡片发送给另一个会话或用户，属于 [group-admin.md](group-admin.md)。 + +`+chat-bots` 返回稳定 `bots[]` 和 `openBotId`，供后续移除。搜索可用机器人、机器人发送和 +撤回读取 [chat-bot.md](chat-bot.md)。 + +## 原子 fallback + +| 原子命令 | 仅用于 | +|---|---| +| `chat search` / `search-common` | Shortcut 未发布的搜索字段或共同群 | +| `chat group get-by-group-id` | 数字群号转换 | +| `chat group members` | 需要原始成员分页响应 | +| `chat group members list-by-ids` | 需要原始批量成员详情 | +| `chat group list-all` / `list-my-groups` | 需要 Shortcut 未投影的真实底层字段 | + +使用原子 fallback 前读取精确 leaf Schema；不得把 fallback 写成与 Shortcut 并列的默认路线。 + +## 完成与错误 + +- 分页完成只以真实 `complete/hasMore/nextCursor/failures` 判断，不看过滤后的 `count` 猜测。 +- 所有稳定 ID 必须来自同一 profile 的真实返回。 +- 找不到群或出现多候选时停止，不臆测 `openConversationId`。 +- 任务从只读发现转为写操作时，使用 [group-admin.md](group-admin.md) 的目标和安全规则。 diff --git a/skills/multi/dingtalk-chat/references/chat/message-actions.md b/skills/multi/dingtalk-chat/references/chat/message-actions.md new file mode 100644 index 00000000..dc34498f --- /dev/null +++ b/skills/multi/dingtalk-chat/references/chat/message-actions.md @@ -0,0 +1,132 @@ +# message-actions：消息编辑、撤回、回复与对象操作 + +> 返回入口：[DingTalk Chat Skill](../../SKILL.md) + +用于对真实消息执行编辑、撤回、引用回复、转发、Pin、Top、Favorite 和表情回应写操作， +并包含必要的紧邻验证。需要跨多个阶段传递真实结果的组合流程由 +[01-messaging.md](../01-messaging.md) 说明；本文件不重复完整工作流。 + +## 入口选择 + +| 用户终点 | 推荐入口 | +|---|---| +| 撤回当前用户消息 | `dws chat +messages-recall --msg-id ` | +| 引用回复 | `dws chat +messages-reply` | +| 编辑已发送消息 | `dws chat message edit` | +| 单条/合并/话题转发 | `+messages-forward` / `+messages-combine-forward` / `+messages-forward-topic` | +| Pin / Unpin | `+messages-set-pin` / `+messages-unset-pin` | +| 消息 Top / 取消 Top | `+messages-set-top` / `+messages-unset-top` | +| Favorite / 取消 Favorite | `+flag-create` / `+flag-cancel` | +| 默认 emoji 回应 | `+messages-add-emoji` / `+messages-remove-emoji` | + +所有写操作以最终 Runtime gate 和精确 leaf Schema 为准。确认对象、消息和影响后再执行； +不要因为文档示例自行制造或省略 confirmation。 + +## 稳定 ID 规则 + +- `openTaskId` 是发送任务 ID，不是消息 ID。 +- 撤回、编辑、回复、转发、Pin、Top 和 reaction 使用真实查询结果中的 `messageId`。 +- 同时保留消息的 `conversationId`、thread、发送者和引用上下文。 +- 子消息使用自己的 `messageId`；只在缺会话 ID 时继承父消息 `conversationId`。 +- Bot 撤回使用 `processQueryKey`，不使用本文件的 `openMessageId` 路线。 + +刚由用户身份发送的消息如果只得到 `openTaskId`，先查询发送状态： + +```text ++messages-send 或 message send +→ openTaskId +→ message query-send-status +→ openMessageId + openConversationId +→ 编辑或撤回 +``` + +## 撤回与编辑 + +`+messages-recall` 可只传 `--msg-id`；省略会话 ID 时 CLI 会通过只读消息详情补齐。 +兼容单值 `--message-ids`，但不要把 `processQueryKey` 当消息 ID。 + +```bash +dws chat +messages-recall --msg-id --format json +dws chat +messages-recall --conversation-id --msg-id --format json +``` + +编辑使用 `message edit --conversation-id --msg-id `，并在 `--text` 与 `--content` +中二选一。`--text` 由 CLI 生成 Markdown content；`--content` 必须是完整 content JSON。 + +```bash +dws chat message edit --conversation-id --msg-id --text "更新后的内容" +dws chat message edit --conversation-id --msg-id --content '{"title":"标题","text":"更新后的内容"}' +``` + +群聊 @所有人使用 `--at-all`；指定人员使用 `--at-open-dingtalk-ids`。正文中的占位符以 +Runtime 规范化结果为准，不把裸展示名当稳定身份。 + +## 引用回复与转发 + +引用回复默认使用 `+messages-reply`。`--conversation-id` 和消息 ID 来自真实查询； +`--ref-sender` 可省略时让 CLI 只读补齐，不手工猜发送者身份。 + +```bash +dws chat +messages-reply --conversation-id \ + --message-id --text "收到" --format json +``` + +| 动作 | 入口 | 关键上下文 | +|---|---|---| +| 单条转发 | `+messages-forward` | 源消息 ID、源会话、目标会话 | +| 合并转发 | `+messages-combine-forward` | 多个真实消息 ID、源/目标会话 | +| 话题转发 | `+messages-forward-topic` | 源消息、源会话、源 thread、目标会话 | + +只有 Shortcut 尚未发布真实必需字段时，才评估原子 `message reply`、`forward`、 +`combine-forward` 或 `forward-topic`，并先读取精确 leaf Schema。不要复制正文伪装原生转发。 + +## Pin、Top 与 Favorite + +| 对象 | 写入入口 | 说明 | +|---|---|---| +| 消息 Pin | `+messages-set-pin` / `+messages-unset-pin` | 作用于一条消息 | +| 消息 Top | `+messages-set-top` / `+messages-unset-top` | 作用于会话内一条消息 | +| Favorite | `+flag-create` / `+flag-cancel` | 当前用户收藏 | +| 会话 Top | `+conversation-set-top` | 作用于整个会话，不属于本文件 | + +用户要求确认 Pin 已生效时，使用 `+messages-list-pin` 检查真实结果中的 `messageId`；取消 Pin +后仅在用户要求确认取消结果时再次查询。典型短链为：`+messages-set-pin` → +`+messages-list-pin` → `+messages-unset-pin`。 + +需要原子 fallback 时，消息 Pin 对应 `message set-pin-msg/unset-pin-msg`，消息 Top 对应 +`message set-top-msg/unset-top-msg`，Favorite 对应 `message add-favorite/remove-favorite`。 +四种对象不能互换，即使用户都使用“收藏、钉住、置顶”等自然语言。 + +## 表情回应 + +优先在 [chat-emoji-list.md](../chat-emoji-list.md) 按表情名称查默认 emoji，不必全文理解表格。 + +| 场景 | 入口 | +|---|---| +| 添加/移除默认 emoji | `+messages-add-emoji` / `+messages-remove-emoji` | +| 默认表情无合适项时创建文字表情 | `+messages-create-text-emotion` | +| 添加/移除文字表情 | `+messages-add-text-emotion` / `+messages-remove-text-emotion` | +| 替换文字表情 | `message update-text-emotion` | + +reaction 查询属于 [message-query.md](message-query.md)，不要为了查看回应执行写命令。 + +## 流式卡片与文本工具 + +流式卡片使用根 Skill 直接链接的 [card/create.md](../card/create.md)、 +[card/update.md](../card/update.md) 和 [card/schema.md](../card/schema.md)；本文件不复制卡片参数。 + +纯文本翻译使用： + +```bash +dws chat text translate --query "你好世界" --to en_US +``` + +用户只要求翻译文本时不要误走消息发送。 + +## 完成与错误 + +- 写操作检查任务级结果、投递状态和失败项，不只看退出码。 +- 投递状态 unknown 时保留幂等键，不自动换目标重发。 +- `unknown flag` 时读取精确 leaf Help，最多修正一次。 +- 目标消息不存在、会话不匹配或发送者上下文缺失时停止，不猜 ID。 +- 已知稳定消息 ID 的单一动作及其紧邻验证均在本文件完成。 diff --git a/skills/multi/dingtalk-chat/references/chat/message-media.md b/skills/multi/dingtalk-chat/references/chat/message-media.md new file mode 100644 index 00000000..d2d660f8 --- /dev/null +++ b/skills/multi/dingtalk-chat/references/chat/message-media.md @@ -0,0 +1,76 @@ +# message-media：特殊消息与资源下载 + +> 返回入口：[DingTalk Chat Skill](../../SKILL.md) + +只用于位置、联系人名片、底层 mediaId/fileId 和消息资源下载。普通文本、Markdown、文件、 +图片、音频和视频发送继续按根 Skill 使用 `+dm`、`+send-to-group` 或 `+messages-send --file`， +不读取本文件。 + +## 默认边界 + +- 用户身份普通文件/音视频：`dws chat +messages-send --as user --file <相对路径>`。 +- 已知资源引用单独下载：`dws chat +messages-resource-download`。 +- 从消息中定位并下载资源：在定位消息的 `+chat-messages`、`+search-msg` 或 + `+messages-mget` 同一次调用中加 `--download-resources`。 +- 只有 Shortcut 尚未发布的位置、联系人名片或真实底层媒体字段，才使用原子 fallback。 + +`dws chat +messages-send` 的 user 文件能力不能外推给 Bot/Webhook； +机器人富媒体边界读取 [chat-bot.md](chat-bot.md)，不得静默改成当前用户身份。 + +## 位置与联系人名片 + +位置消息必须确认纬度、经度、地址名称和地图缩略图 mediaId： + +```bash +dws chat message send --group --msg-type location \ + --latitude <纬度> --longitude <经度> --location-name <地址名称> \ + --map-thumbnail-url "@mediaId" +``` + +联系人名片的 `--contact-id` 必须是联系人 `openDingTalkId`，不能把 userId 直接代入： + +```bash +dws chat message send --group \ + --msg-type profile --contact-id +``` + +用户要求真实发送结果时，保留发送返回的 `openTaskId`，再执行： + +```bash +dws chat message query-send-status --open-task-id --format json +``` + +检查真实 `sendStatus`、`openMessageId` 和 `openConversationId`。 + +原子 `message send` 只在 Shortcut 缺少真实必需字段时使用。群聊目标用 `--group`；单聊目标 +用 `--user` 或 `--open-dingtalk-id`，三者通常互斥。发送前核对接收对象、消息类型和资源来源。 + +## 资源下载 + +公开 `+messages-resource-download` 使用工作目录内安全相对路径，默认不覆盖；完整文件先写入 +临时落盘再原子发布。覆盖必须由用户显式传 `--overwrite`，读取和下载不需要 `--yes`。 + +任务要求从某条消息中定位并下载资源时，优先在限定会话、消息或时间范围的查询中加 +`--download-resources --output-dir <目录>`，并检查下载 ledger。`+messages-resource-download` +只用于已经持有完整、真实且属于当前组织/profile 的独立资源引用、无需再定位消息的场景。 +若 `fileId` 返回 `RESOURCE_NOT_FOUND`，不得把同一个 ID 改称 `mediaId` 重试，也不得原样 +重复调用；应回到消息查询并使用 `--download-resources`。 + +底层 fallback： + +```bash +dws chat message download-media --type mediaId --resource-id \ + --message-id --open-conversation-id \ + --output ./downloads/ +``` + +`resource-id`、`message-id` 和会话 ID 必须来自同一 profile 下的真实消息查询结果。 +当前没有 Range/断点续传；失败时保留 ledger 或错误，显式重试整个文件，不拼接残片。 + +## 完成与错误 + +- 查询并下载时同时检查消息完整性和每项下载 ledger；单项失败不抹掉已取得消息。 +- 文件/音视频发送失败先确认工作目录内相对路径可读，不恢复独立上传再提取 mediaId 的旧默认链路。 +- 位置参数不完整时先向用户确认，不猜经纬度或缩略图。 +- 名片发送失败时确认 `--contact-id` 是 openDingTalkId。 +- 下载目标存在时默认停止；只有用户明确允许覆盖时才传 `--overwrite`。 diff --git a/skills/multi/dingtalk-chat/references/chat/message-query.md b/skills/multi/dingtalk-chat/references/chat/message-query.md new file mode 100644 index 00000000..cc35ab04 --- /dev/null +++ b/skills/multi/dingtalk-chat/references/chat/message-query.md @@ -0,0 +1,132 @@ +# message-query：消息读取、搜索与查询 + +> 返回入口：[DingTalk Chat Skill](../../SKILL.md) + +用于浏览或导出指定会话、按条件搜索消息、按消息 ID 读取详情、查看 @我、话题回复、 +Favorite、Pin 和 reaction。只读任务优先使用 Shortcut；只有 Shortcut 未发布所需底层字段、 +原始响应或手工 continuation 时才读取精确原子 leaf Schema。 + +## 入口选择 + +| 用户终点 | 唯一推荐入口 | +|---|---| +| 浏览或导出一个指定群聊/单聊 | `dws chat +chat-messages` | +| 发送者、关键词、@对象或消息类型是主要条件 | `dws chat +search-msg` | +| 已知消息 IDs 读取详情 | `dws chat +messages-mget` | +| 查看 @我的消息 | `dws chat +at-me` | +| 查看 Favorite | `dws chat +flag-list` | +| 已知话题主消息或 thread/topic ID 读取回复 | `dws chat +thread-replies` | + +`+chat-messages` 是指定会话的粗粒度读取；`+search-msg` 是目标条件明确的单/跨会话检索。 +不要先读完整会话再补跑搜索，也不要把群名或姓名直接填入只接受稳定 ID 的参数。 + +## 指定会话读取 + +群聊 `--group` 可传群名或 `openConversationId`；也可用 `--chat-query` 显式解析群名、 +用 `--conversation-id` 显式传稳定 ID。单聊使用 `--user` 或 `--open-dingtalk-id`。 + +```bash +dws chat +chat-messages --group <群名或openConversationId> --format json +dws chat +chat-messages --group --page-all --page-limit 50 --format json +``` + +可附带非必填的 `--sender-query <姓名>`：未传时返回全部消息；未解析出稳定 ID 时保留 +全部消息并记录失败；唯一解析出 userId/openDingTalkId 后，按消息 `senderId` 筛选同一次 +读取结果，覆盖最终 `messages/count` 并返回 `resolvedFilters`。不得用展示名字符串比较否定 +已经成功解析的稳定发送者身份。 + +```bash +dws chat +chat-messages --group "项目群" --sender-query "测试用户甲" --page-all --format json +``` + +时间范围使用公开可选的 `--start`、`--end`、`--order asc|desc`，兼容别名为 +`--start-time/--end-time/--sort`。范围为 `[start,end)`；仅开始时间表示到本次执行当前时间； +仅结束时间只支持 `desc`，`asc` 必须提供开始时间。旧 `--time/--direction` 只用于兼容的 +单边界模式，不能与范围模式混用。 + +```bash +dws chat +chat-messages --group \ + --start "2026-08-01T00:00:00+08:00" --end "2026-08-02T00:00:00+08:00" \ + --order asc --page-all --format json +``` + +完整读取后只需消息字段可判断的子集时，在同一次调用中使用全局 `--jq`，保留根信封并 +同步改写 `messages/count`；不得丢失 `complete`、`hasMore`、`failures` 等 ledger。 +发送者姓名仍使用 `--sender-query` 解析稳定身份，不用 `--jq` 比较展示名。 + +```bash +dws chat +chat-messages --group "项目群" --page-all --format json \ + --jq '. as $root | [.messages[] | select((.reactions // []) | length > 0)] as $matched | $root | .messages = $matched | .count = ($matched | length)' +``` + +要求导出时用 `--output <工作目录内相对.json>` 原子写入；需要资源时在读取命令上加 +`--download-resources`，不要让 Agent 先输出全量 JSON 再手工遍历资源引用。 + +## 多维度搜索 + +- 关键词使用公开 `--query`。 +- 已知稳定会话 ID 使用 `--group` / `--groups`；稳定发送者 ID 使用 `--senders`。 +- 只有群名时使用 `--chat-query`，由 CLI 唯一解析会话。 +- 只有发送者姓名时使用 `--sender-query`，由 CLI 唯一解析人员。 +- 不传会话过滤时搜索全部会话；默认时间范围为最近 7 天。 +- `--page-all` 只翻完当前时间范围内的游标页；精确范围使用成对的 `--start/--end`。 +- `--order` 只稳定排列已经取得的结果；未全量或 `complete=false` 时不得称为完整范围全局排序。 + +```bash +dws chat +search-msg --chat-query "项目群" --sender-query "测试用户甲" --page-all --format json +dws chat +search-msg --chat-query "项目群" --query "发布计划" --page-all --format json +dws chat +search-msg --sender-query "测试用户甲" --page-all --format json +``` + +需要 Shortcut 未发布的原始过滤字段或响应时，才评估 `message search-advanced`。它支持 +发送者、@对象、多个会话、消息类型、会话类型、机器人消息和时间范围，但不是默认入口。 +至少提供一种真实过滤条件，完整遍历只有 `--page-all` 会触发。 + +## 其他查询 + +### 已知消息、@我与话题回复 + +- `+messages-mget --msg-ids `：最多 50 条；结果可直接用于回复、转发、撤回和资源下载。 +- `+at-me [--group <群名或ID>] --page-all`：群内或跨全部会话查看 @我的消息。 +- `+thread-replies --message-id `：自动只读解析 conversation/thread。 +- `+thread-replies --group --thread-id `：显式稳定上下文。 + +话题回复默认 `desc`；`asc` 必须与 `--page-all` 一起使用。自动续页使用下层毫秒级 +`nextCursor`，不得使用只有秒精度的展示时间手工拼 continuation。检查 `complete`、 +`hasMore`、`stopReason` 和 `failures`。 + +### Favorite、Pin 与 reaction 查询 + +| 任务 | 入口 | +|---|---| +| Favorite 列表 | `+flag-list`；要求全部时加 `--page-all`，页大小 1–30 | +| 消息 Pin 列表 | `message list-pin-msg --open-conversation-id ` | +| 批量 reaction/文字回应 | `message list-emotion-replies --msg-ids ` | +| 已读/未读状态 | `message read-status --group --message-id ` | + +Favorite、消息 Pin、消息 Top 和会话 Top 是不同对象。写入或取消这些状态读取 +[message-actions.md](message-actions.md)，这里只负责查询。 + +## 原子 fallback + +| 原子命令 | 仅用于 | +|---|---| +| `message list` | 指定会话原始响应或显式手工 continuation | +| `message list-all` | 时间范围内全部会话的原始分页响应 | +| `message list-by-sender` | 已有稳定发送者 ID 且需要底层原始响应 | +| `message list-mentions` / `list-focused` | @我或特别关注的原始列表 | +| `message search` / `search-advanced` | Shortcut 未发布的真实过滤字段 | +| `message list-topic-replies` | 已知 conversation/thread 的原始话题回复 | +| `message list-by-ids` | 已知消息 ID 的原始详情响应 | + +Typed `chat message` 自动翻页只由 `--page-all` 触发；只传 `--page-limit`、`--max-items` +或 `--page-delay` 仍是单页。非第一页失败时保留 partial 结果、失败页和 continuation，不能 +把 partial result 表述成完整成功。 + +## 完成与错误 + +- 查询必须检查 `complete`、`hasMore`、`stopReason`、`failures` 和下载 ledger。 +- 发送者/群名零命中或多候选时停止，不选择第一项。 +- `unknown flag` 时读取精确 leaf Help，修正后最多重试一次。 +- 子消息优先使用自己的 `messageId`；只在缺会话 ID 时继承父消息的 `conversationId`。 +- 查到真实消息后需要写操作时，使用 [message-actions.md](message-actions.md) 中的稳定 ID 规则。 diff --git a/skills/multi/dingtalk-chat/references/intent-guide.md b/skills/multi/dingtalk-chat/references/intent-guide.md index c6c3feef..04146c60 100644 --- a/skills/multi/dingtalk-chat/references/intent-guide.md +++ b/skills/multi/dingtalk-chat/references/intent-guide.md @@ -22,12 +22,12 @@ | 用户终点 | 对象 | Reference | |---|---|---| -| 收藏或取消收藏 | 当前用户的 Favorite | [chat-message.md](chat/chat-message.md) | -| Pin/Unpin 一条消息 | 消息 Pin | [chat-message.md](chat/chat-message.md) | -| 置顶/取消置顶一条消息 | 消息 Top | [chat-message.md](chat/chat-message.md) | +| 收藏或取消收藏 | 当前用户的 Favorite | [message-actions.md](chat/message-actions.md) | +| Pin/Unpin 一条消息 | 消息 Pin | [message-actions.md](chat/message-actions.md) | +| 置顶/取消置顶一条消息 | 消息 Top | [message-actions.md](chat/message-actions.md) | | 置顶/取消置顶整个会话 | 会话 Top | [chat-conversation.md](chat/chat-conversation.md) | | 查看置顶会话 | 会话列表 | `+conversation-list-top` | -| 标记消息已读 | 消息读取状态 | [chat-message.md](chat/chat-message.md) | +| 标记消息已读 | 消息读取状态 | [message-actions.md](chat/message-actions.md) | | 清红点、标记会话未读 | 会话状态 | [chat-conversation.md](chat/chat-conversation.md) | Favorite、消息 Pin、消息 Top 和会话 Top 不能互换，即使用户都说“收藏/钉住/置顶”。 @@ -37,7 +37,8 @@ Favorite、消息 Pin、消息 Top 和会话 Top 不能互换，即使用户都 | 用户终点 | 选择 | |---|---| | 已有成员 IDs 创建群 | `+chat-create` | -| 加人、踢人、管理员、群公告、群设置 | [chat-group.md](chat/chat-group.md) | +| 查群、查看成员、邀请链接 | [group-discovery.md](chat/group-discovery.md) | +| 加人、踢人、管理员、群公告、群设置 | [group-admin.md](chat/group-admin.md) | | 找可用机器人并取得单聊 ID | `chat bot find`，不是只查自己创建机器人的 `bot search` | | 已知 robotCode 发送 | `+messages-send --as bot` | | 机器人入群、移除、批量群发或撤回 | [chat-bot.md](chat/chat-bot.md) | From b53b84616e13015279a453120e5846a6b60be300 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Fri, 14 Aug 2026 19:32:54 +0800 Subject: [PATCH 122/250] fix(cli): match ambiguous from flag exactly --- internal/app/flag_error_test.go | 16 ++++++++++++++++ internal/app/root.go | 24 ++++++++++++++++-------- 2 files changed, 32 insertions(+), 8 deletions(-) diff --git a/internal/app/flag_error_test.go b/internal/app/flag_error_test.go index 3a9e6d95..9b44eb91 100644 --- a/internal/app/flag_error_test.go +++ b/internal/app/flag_error_test.go @@ -104,6 +104,22 @@ func TestFlagErrorWithSuggestionsChatFromExplainsBothMeanings(t *testing.T) { if !strings.HasSuffix(ae.Message, "See 'dws chat +search-msg --help' for usage.") { t.Fatalf("Message = %q", ae.Message) } + + for _, flag := range []string{"from-file", "from-user"} { + t.Run(flag, func(t *testing.T) { + err := flagErrorWithSuggestions(search, fmt.Errorf("unknown flag: --%s", flag)) + var structured *apperrors.Error + if stderrors.As(err, &structured) && structured.Reason == "ambiguous_flag" { + t.Fatalf("--%s incorrectly used --from ambiguity handling: %#v", flag, structured) + } + if strings.Contains(err.Error(), "--from 在消息查询中含义不明确") { + t.Fatalf("--%s incorrectly received --from ambiguity hint: %v", flag, err) + } + if !strings.Contains(err.Error(), "unknown flag: --"+flag) { + t.Fatalf("error = %q, want original flag --%s", err, flag) + } + }) + } } // TestFlagErrorWithSuggestions_fallbackTailHint 验证 fallback 路径（非 unknown flag 类错误， diff --git a/internal/app/root.go b/internal/app/root.go index 79a96d11..7a41bd53 100644 --- a/internal/app/root.go +++ b/internal/app/root.go @@ -511,7 +511,7 @@ func flagErrorWithSuggestions(cmd *cobra.Command, err error) error { // 无论哪种格式，子串 "--help' for usage." 都可被检索到。 tail := fmt.Sprintf("\nSee '%s --help' for usage.", cmd.CommandPath()) msgWithTail := errMsg + tail - if strings.Contains(errMsg, "unknown flag: --from") { + if flag, ok := unknownFlagName(errMsg); ok && flag == "from" { switch cmd.CommandPath() { case "dws chat +search-msg", "dws chat +chat-messages": return apperrors.NewValidation( @@ -595,15 +595,10 @@ func reviewedFlagProtection(cmd *cobra.Command, errMsg string) (string, pipeline if cmd == nil { return "", "", false } - const prefix = "unknown flag: --" - idx := strings.Index(errMsg, prefix) - if idx < 0 { + flag, ok := unknownFlagName(errMsg) + if !ok { return "", "", false } - flag := strings.TrimSpace(errMsg[idx+len(prefix):]) - if i := strings.IndexAny(flag, " =\n\t"); i >= 0 { - flag = flag[:i] - } entry, ok := cli.LookupParamAlias(cmd.CommandPath()) if !ok { return "", "", false @@ -618,6 +613,19 @@ func reviewedFlagProtection(cmd *cobra.Command, errMsg string) (string, pipeline return "", "", false } +func unknownFlagName(errMsg string) (string, bool) { + const prefix = "unknown flag: --" + idx := strings.Index(errMsg, prefix) + if idx < 0 { + return "", false + } + flag := strings.TrimSpace(errMsg[idx+len(prefix):]) + if i := strings.IndexAny(flag, " =\n\t"); i >= 0 { + flag = flag[:i] + } + return flag, flag != "" +} + func printExecutionError(root *cobra.Command, stdout, stderr io.Writer, err error) error { var raw apperrors.RawStderrError if stderrors.As(err, &raw) { From 596bdce3a11a3e505fe1bb1e165e87693cab53de Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 11:43:20 +0800 Subject: [PATCH 123/250] feat(wiki): align and harden shortcut workflows --- .changes/wiki-shortcut-alignment.md | 8 + docs/shortcut-public-catalog.json | 201 ++++++- docs/wiki-shortcut-business-review.html | 115 ++++ internal/app/schema_shortcut_contract_test.go | 6 +- internal/helpers/wiki.go | 9 +- .../builtin/wiki_semantic_catalog_test.go | 71 +++ internal/shortcut/public_catalog_generated.go | 19 + internal/shortcut/semantic_catalog.go | 4 + internal/shortcut/semantic_catalog_wiki.json | 30 + internal/shortcut/smart/resolve_space.go | 80 ++- internal/shortcut/smart/wiki_new_doc.go | 106 +++- internal/shortcut/wiki/common.go | 274 +++++++++ internal/shortcut/wiki/nodes.go | 254 +++++++++ .../wiki/space_list_projection_test.go | 38 +- internal/shortcut/wiki/wiki.go | 537 +++++++----------- scripts/dev/wiki-shortcut-e2e.py | 179 ++++++ scripts/gen_shortcut_public_catalog.py | 1 + skills/mono/SKILL.md | 2 +- skills/multi/dingtalk-wiki/SKILL.md | 3 +- 19 files changed, 1574 insertions(+), 363 deletions(-) create mode 100644 .changes/wiki-shortcut-alignment.md create mode 100644 docs/wiki-shortcut-business-review.html create mode 100644 internal/shortcut/builtin/wiki_semantic_catalog_test.go create mode 100644 internal/shortcut/semantic_catalog_wiki.json create mode 100644 internal/shortcut/wiki/common.go create mode 100644 internal/shortcut/wiki/nodes.go create mode 100755 scripts/dev/wiki-shortcut-e2e.py diff --git a/.changes/wiki-shortcut-alignment.md b/.changes/wiki-shortcut-alignment.md new file mode 100644 index 00000000..356fb40d --- /dev/null +++ b/.changes/wiki-shortcut-alignment.md @@ -0,0 +1,8 @@ +--- +category: Added +--- + +- **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and + activity shortcuts with strict collection validation, cursor handling, + write read-backs, Lark-compatible task routing, and documented backend + boundaries. diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index 8e025520..eef23b40 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,6 +1,6 @@ { - "generated_at": "2026-08-12T00:10:44.511794", - "count": 399, + "generated_at": "2026-08-14T10:41:08.959563", + "count": 418, "results": [ { "suite": "semantic", @@ -3659,11 +3659,204 @@ "status": "real-ok" }, { - "suite": "read", + "suite": "semantic", + "service": "wiki", + "command": "+delete-space", + "risk": "high-risk-write", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "删除前读取影响目标，经高风险确认后只接受 success=true 终态。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+feed-list", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "补充 Lark Shortcut 缺失的知识库协作动态查询，严格验证 feeds 并保留游标。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+member-add", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "批量授予 Wiki 容器角色，严格校验写终态并读取成员列表验证响应链。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+member-list", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格验证成员数组并公开真实单次上限 50；后端无游标时不伪造 page-all。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+member-remove", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "批量移除容器访问，严格校验写终态并读取成员列表验证响应链。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+member-update", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "补充 Lark Shortcut 缺失的成员角色更新，并执行终态与列表读回校验。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+move", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "同一入口覆盖 Wiki 内移动和我的文档在线节点入 Wiki，并校验目标 workspace/folder。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+move-to-drive", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "同步移动 Wiki 节点到我的文档并读回验证 workspace 变化，免去异步任务轮询。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-copy", + "risk": "high-risk-write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "高风险确认后复制，必须取得新 nodeId 并读回副本，避免空响应被当作成功。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-create", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "支持七种 Wiki 节点类型，创建后要求 nodeId 并读取元数据验证。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-delete", + "risk": "high-risk-write", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "删除前读取并核对 workspace，经高风险确认后要求 success=true 终态证据。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-get", + "risk": "read", + "status": "reviewed_available", + "disposition": "schema_leaf", + "semantic_delta": "统一节点 ID 或在线文档 URL 的元数据读取，补充文档域属性视角。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-list", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格区分显式空目录与假空成功，稳定投影节点并保留 nextCursor/hasMore。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+node-search", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "补充 Lark Wiki Shortcut 缺失的库内关键词和扩展名搜索，并拒绝假空结果。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+resolve-space", + "risk": "read", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "把关键词搜索收敛为唯一 workspaceId；零命中与多命中显式分流，绝不猜测。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+space-create", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "创建后要求 workspaceId 并通过空间详情读回验证真实落库。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+space-get", + "risk": "read", + "status": "reviewed_available", + "disposition": "schema_leaf", + "semantic_delta": "提供 Lark Shortcut 未单列的知识库详情入口，并要求 workspaceId 业务证据。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+space-list", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格区分显式空知识库列表与缺失、畸形或内部错误响应，并保留真实分页证据。", + "availability": "available" + }, + { + "suite": "semantic", "service": "wiki", "command": "+space-search", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "按关键词搜索知识库并拒绝把缺失业务数组误报为零命中。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "wiki", + "command": "+wiki-new-doc", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按空间名精确唯一解析、创建在线文档并读回验证；零命中和歧义均显式失败。", + "availability": "available" } ] } \ No newline at end of file diff --git a/docs/wiki-shortcut-business-review.html b/docs/wiki-shortcut-business-review.html new file mode 100644 index 00000000..4d7c871e --- /dev/null +++ b/docs/wiki-shortcut-business-review.html @@ -0,0 +1,115 @@ + + + + + + DWS Wiki Shortcut 全景评审 + + +
+
+

DWS Wiki Shortcut 全景评审

+

以 lark-cli 1.0.78 的 13 个 Wiki Shortcut 为任务基线，重新审视 DWS 的空间、成员、节点与动态能力。本次不是按命令名凑数：每个入口都要求真实业务证据，缺失数组、畸形响应、空确认或读回不一致一律失败。

+
评审日期 2026-08-14独立 worktree / 独立分支真实组织数据 E2E报告已去标识化
+
+ +
+
20公开 Wiki Shortcuts
+
13/13Lark 用户任务有对应路径
+
7DWS 额外场景
+
20/20真实数据能力已触达
+
+ +
+

结论先行

+
DWS 已形成比“API 快捷别名”更完整的 Wiki 任务层。 Lark 的 13 个用户任务均有对应入口；其中 DWS 额外提供空间搜索/详情/唯一解析、成员角色更新、库内节点搜索、协作动态和按空间名新建文档。创建、复制、移动等关键写能力从“请求发出”升级为“终态 + ID + 读回”成功标准。
+
不能假装完全同构。 DingTalk 成员接口不提供游标，单次真实上限是 50，因此无法诚实实现 Lark 的成员 --page-all；成员身份只接受同组织可用的 userId，不能对齐 Lark 的 email/open_id 等多种 member-id-type；节点创建也没有等价的 origin/shortcut 模式。这些差异保留为明确边界，而不是用本地循环或空结果伪装。
+
+ +
+

Lark 13 项逐条映射

+
+ + + + + + + + + + + + + +
Lark ShortcutDWS 主入口结论DWS 视角与边界
+space-listwiki +space-list完整对齐严格空集合、游标续传、自动翻页、停滞检测；支持组织/我的知识库。
+space-createwiki +space-create超过公开真实 32 字符名称上限；创建后按 workspaceId 读回。
+delete-spacewiki +delete-space超过预读目标、高风险确认、只接受 success=true；兼容 +space-delete。
+member-addwiki +member-add任务对齐支持 1–30 个 userId 与四种角色，读回名单和角色；不支持 email/open_id 等身份类型。
+member-listwiki +member-list任务对齐严格成员数组、角色过滤、真实上限 50；后端无游标，不能提供诚实的 page-all。
+member-removewiki +member-remove任务对齐批量 userId，移除后读回确认成员已消失；身份类型边界同上。
+node-listwiki +node-list完整对齐正确跨域路由 doc/list_nodes，严格空目录、分页与自动翻页。
+node-getwiki +node-get任务对齐支持 DingTalk 节点 ID/在线文档 URL并返回文档域元数据；不接受 Lark 特有 token/type 组合。
+node-createwiki +node-create任务对齐支持 adoc/axls/able/appt/adraw/amind/folder 并读回；无 origin/shortcut 等价接口。
+node-copywiki +node-copy超过确认后要求新 nodeId 并读取副本；底层面向在线节点，不把 .dlink 当独立副本。
+movewiki +move任务对齐同一入口支持 Wiki 内移动和“我的文档”在线节点入 Wiki，读回 workspace/folder；无 Lark apply 权限迁移开关。
+move-to-drivewiki +move-to-drive超过DWS 当前接口同步完成并读回 workspace 变化，无需暴露异步 task 轮询。
+node-deletewiki +node-delete超过预读并核对 workspace，高风险确认，要求删除终态。
+
+ +
+

DWS 可挖掘的 7 个额外场景

+
+

定位与创建链

  • +space-search：严格关键词搜索。
  • +space-get：空间详情与 workspaceId 证据。
  • +resolve-space：唯一命中直出 ID，多命中拒绝猜测。
  • +wiki-new-doc：空间名解析 → 创建 → 文档读回。
+

治理与巡检链

  • +member-update：角色变更后读回。
  • +node-search：库内关键词/扩展名搜索，严格零命中。
  • +feed-list：知识库动态时间线与服务端 exclude-file 过滤。
+
+
+ +
+

隐藏问题与修复

+ + + + + + + +
原问题错误风险本次修复
5 个旧 Wiki Shortcut 可直接执行，但只有 1 个进入公开目录。Help、Schema、Skill 发现链与运行面漂移。20 项统一评审 全部具备 Contract/Safety/Result 与语义目录记录。
列表投影找不到数组或遇到坏元素时返回空 slice。把内部错误、字段漂移误报为“没有数据”。失败关闭 只有响应中真实存在的 [] 才是合法空集合。
节点列表 Shortcut 调错 Wiki MCP 服务。真实后端 success=false，Mock/静态检查看不出。跨域路由 明确调用 doc/list_nodes，并纳入真实 E2E。
成员帮助宣称最大 200。真实接口超过 50 直接参数错误。真实上限 Shortcut 与原子 Help 均改为 50，并在本地提前拒绝。
知识库名称帮助宣称最大 100。真实接口超过 32 失败。真实上限 Help 与 Shortcut 校验统一为 32。
复制/移动/创建只把无异常视为成功。空确认、未知远端效果或移动未到目标仍可能被接受。读回证明 检查 success、业务 ID、workspace/folder/role 等最终状态。
+
+ +
+

真实数据 E2E 证据矩阵

+

测试使用一次性空知识库、临时在线文档与一名同组织内部测试成员；所有对象在 finally 清理。报告不保存对象 ID、成员身份、组织信息、URL、trace 或原始响应。

+
+
+ + + + + + + + + + + + + + + + + + + + +
分组Shortcut实际业务断言状态
空间+space-list真实 count、hasMore、nextCursor；自动翻页返回两页结果。PASS
空间+space-search等待搜索索引后命中一次性 workspaceId。PASS
空间+space-get读回 workspaceId 与创建结果一致。PASS
空间+resolve-space唯一名称解析为同一 workspaceId。PASS
空间+space-createsuccess=true、workspaceId 非空、详情读回一致。PASS
空间+delete-space目标预读、确认、success=true；兼容别名执行 finally 清理。PASS
成员+member-list真实 owner 条目与显式 members 数组，limit=50。PASS
成员+member-add真实内部成员添加后在名单中出现且角色为 READER。PASS
成员+member-update同一成员读回角色变为 EDITOR。PASS
成员+member-remove移除后名单中不再存在该 userId。PASS
节点+node-list空库返回真实 nodes:[]；有数据时验证游标与自动翻页。PASS
节点+node-get读回 nodeId 与请求一致。PASS
节点+node-search等待索引后按标题命中真实 nodeId。PASS
节点+node-create分别创建 folder/adoc，均取得 nodeId 和元数据读回。PASS
节点+node-copy取得不同的新 nodeId，副本元数据可读。PASS
节点+move读回 workspaceId 与 folderId 均等于目标；兼容 +node-move。PASS
节点+move-to-drive移动后读回 workspace 发生变化，再通过 +move 移回。PASS
节点+node-delete目标预读与 workspace 核对后收到 success=true。PASS
节点+wiki-new-doc按唯一空间名创建，nodeId 与文档详情读回一致。PASS
动态+feed-list创建/移动操作后返回真实 feeds 数组，缺字段不会被接受。PASS
+

可复跑入口：make build 后设置临时 DWS_WIKI_E2E_MEMBER_ID，运行 ./scripts/dev/wiki-shortcut-e2e.py。脚本只输出能力标签，不输出业务对象。

+
+ +
+

成功判定与发布门

+

运行时证据层

  1. 传输/MCP 调用成功。
  2. 响应契约存在且类型正确。
  3. 写操作必须有 success=true 与业务 ID。
  4. 创建/复制/移动/成员变更必须读回最终状态。
  5. 集合只有显式数组才允许为空。

交付门

  1. 20/20 语义目录与注册面精确覆盖。
  2. Contract、Safety、Result、统一输出完整。
  3. 生成漂移、Schema、确认真值、全量 Go 测试。
  4. 独立真实数据 E2E 与 finally 清理。
  5. diff PII/密钥/本地绝对路径扫描。
+
+

DWS Wiki Shortcut business review · sanitized engineering artifact

+
+ diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 55950aa0..0e1f6750 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -16,12 +16,12 @@ import ( ) const ( - publicShortcutCount = 399 + publicShortcutCount = 418 // schemaPublishedShortcutCount counts every delivered *.shortcut_* tool, // including the hidden historical minutes.shortcut_minutes_search contract. - schemaPublishedShortcutCount = 401 + schemaPublishedShortcutCount = 420 // publiclyDeliveredShortcutCount is the public-catalog subset of that surface. - publiclyDeliveredShortcutCount = 399 + publiclyDeliveredShortcutCount = 418 ) func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) { diff --git a/internal/helpers/wiki.go b/internal/helpers/wiki.go index 88c0272e..3c8dc9cf 100644 --- a/internal/helpers/wiki.go +++ b/internal/helpers/wiki.go @@ -428,7 +428,7 @@ func newWikiCommand() *cobra.Command { }) // space create flags - spaceCreateCmd.Flags().String("name", "", "知识库名称 (必填，不超过 100 字符)") + spaceCreateCmd.Flags().String("name", "", "知识库名称 (必填，不超过 32 字符)") spaceCreateCmd.Flags().String("desc", "", "知识库描述 (选填，不超过 500 字符)") spaceCreateCmd.Flags().String("icon", "", "知识库图标标识 (选填)") @@ -696,7 +696,7 @@ func newWikiCommand() *cobra.Command { Short: "查询知识库成员列表", Long: `查询指定知识库的成员列表，返回每位成员的 userId、姓名、角色等信息。 -注意：底层不支持游标分页，--limit 仅控制单次返回的最大条数（最大 200）。 +注意：底层不支持游标分页，--limit 仅控制单次返回的最大条数（最大 50）。 若结果被截断（出参 truncated=true），可通过 --filter-role 收窄查询范围； ORG 类型授权不会出现在查询结果中。`, Example: ` dws wiki member list --workspace @@ -717,6 +717,9 @@ ORG 类型授权不会出现在查询结果中。`, limit, _ = cmd.Flags().GetInt("max-results") } if limit > 0 { + if limit > 50 { + return fmt.Errorf("--limit 不能超过 50；底层成员接口不提供游标续页") + } toolArgs["maxResults"] = limit } if v := mustGetFlag(cmd, "filter-role"); v != "" { @@ -762,7 +765,7 @@ ORG 类型授权不会出现在查询结果中。`, }) memberListCmd.Flags().String("workspace", "", "知识库 ID 或 URL (必填)") - memberListCmd.Flags().Int("limit", 30, "返回成员数上限，默认 30，最大 200") + memberListCmd.Flags().Int("limit", 30, "返回成员数上限，默认 30，最大 50；底层不支持游标续页") memberListCmd.Flags().Int("max-results", 0, "") _ = memberListCmd.Flags().MarkHidden("max-results") memberListCmd.Flags().String("filter-role", "", "按角色过滤（逗号分隔）：OWNER / MANAGER / EDITOR / DOWNLOADER / READER") diff --git a/internal/shortcut/builtin/wiki_semantic_catalog_test.go b/internal/shortcut/builtin/wiki_semantic_catalog_test.go new file mode 100644 index 00000000..afe58c14 --- /dev/null +++ b/internal/shortcut/builtin/wiki_semantic_catalog_test.go @@ -0,0 +1,71 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package builtin_test + +import ( + "encoding/json" + "os" + "sort" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +func TestCrossPlatformCoverageWikiSemanticCatalogExactlyCoversRegisteredSurface(t *testing.T) { + raw, err := os.ReadFile("../semantic_catalog_wiki.json") + if err != nil { + t.Fatal(err) + } + var source chatSemanticCatalogFixture + if err := json.Unmarshal(raw, &source); err != nil { + t.Fatal(err) + } + if source.Service != "wiki" { + t.Fatalf("service = %q", source.Service) + } + registered := map[string]shortcut.Shortcut{} + for _, item := range shortcut.All() { + if item.Service == "wiki" { + if _, exists := registered[item.Command]; exists { + t.Fatalf("duplicate %s", item.Command) + } + registered[item.Command] = item + } + } + if len(registered) != 20 || len(source.Shortcuts) != 20 { + t.Fatalf("registered/catalog = %d/%d, want 20/20", len(registered), len(source.Shortcuts)) + } + var missing, stale []string + for command, item := range registered { + record, ok := source.Shortcuts[command] + if !ok { + missing = append(missing, command) + continue + } + if !record.Reviewed || !item.SemanticReviewed || item.Hidden || !record.Public { + t.Errorf("%s: not publicly reviewed", command) + } + if strings.TrimSpace(record.SemanticDelta) == "" || item.SemanticDelta != record.SemanticDelta || item.Disposition != record.Disposition { + t.Errorf("%s: semantic facts drifted", command) + } + if item.Risk != record.Risk { + t.Errorf("%s: risk=%q want=%q", command, item.Risk, record.Risk) + } + if item.Contract.Empty() || item.Contract.Result == nil || strings.TrimSpace(item.Safety.Effect) == "" || item.OutputRollout != output.RolloutUnifiedActive { + t.Errorf("%s: incomplete contract/safety/result/output", command) + } + } + for command := range source.Shortcuts { + if _, ok := registered[command]; !ok { + stale = append(stale, command) + } + } + sort.Strings(missing) + sort.Strings(stale) + if len(missing) > 0 || len(stale) > 0 { + t.Fatalf("catalog mismatch: missing=%v stale=%v", missing, stale) + } +} diff --git a/internal/shortcut/public_catalog_generated.go b/internal/shortcut/public_catalog_generated.go index 67a12d41..4ec9e1b7 100644 --- a/internal/shortcut/public_catalog_generated.go +++ b/internal/shortcut/public_catalog_generated.go @@ -404,6 +404,25 @@ func generatedPublicShortcutCatalog() map[string]struct{} { "todo\u0000+overdue": {}, "todo\u0000+remind": {}, "todo\u0000+todo-done": {}, + "wiki\u0000+delete-space": {}, + "wiki\u0000+feed-list": {}, + "wiki\u0000+member-add": {}, + "wiki\u0000+member-list": {}, + "wiki\u0000+member-remove": {}, + "wiki\u0000+member-update": {}, + "wiki\u0000+move": {}, + "wiki\u0000+move-to-drive": {}, + "wiki\u0000+node-copy": {}, + "wiki\u0000+node-create": {}, + "wiki\u0000+node-delete": {}, + "wiki\u0000+node-get": {}, + "wiki\u0000+node-list": {}, + "wiki\u0000+node-search": {}, + "wiki\u0000+resolve-space": {}, + "wiki\u0000+space-create": {}, + "wiki\u0000+space-get": {}, + "wiki\u0000+space-list": {}, "wiki\u0000+space-search": {}, + "wiki\u0000+wiki-new-doc": {}, } } diff --git a/internal/shortcut/semantic_catalog.go b/internal/shortcut/semantic_catalog.go index 96cb8593..6c04f845 100644 --- a/internal/shortcut/semantic_catalog.go +++ b/internal/shortcut/semantic_catalog.go @@ -25,6 +25,9 @@ var minutesSemanticCatalogJSON []byte //go:embed semantic_catalog_drive.json var driveSemanticCatalogJSON []byte +//go:embed semantic_catalog_wiki.json +var wikiSemanticCatalogJSON []byte + type semanticCatalogFile struct { Version int `json:"version"` Service string `json:"service"` @@ -48,6 +51,7 @@ var reviewedSemanticCatalog = mustLoadSemanticCatalogs( aitableSemanticCatalogJSON, minutesSemanticCatalogJSON, driveSemanticCatalogJSON, + wikiSemanticCatalogJSON, ) func mustLoadSemanticCatalogs(sources ...[]byte) map[string]semanticCatalogRecord { diff --git a/internal/shortcut/semantic_catalog_wiki.json b/internal/shortcut/semantic_catalog_wiki.json new file mode 100644 index 00000000..428438ee --- /dev/null +++ b/internal/shortcut/semantic_catalog_wiki.json @@ -0,0 +1,30 @@ +{ + "version": 1, + "service": "wiki", + "default_availability": "available", + "shortcuts": { + "+space-list": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空知识库列表与缺失、畸形或内部错误响应，并保留真实分页证据。","risk":"read","public":true,"reviewed":true}, + "+space-search": {"disposition":"semantic_adapter","semantic_delta":"按关键词搜索知识库并拒绝把缺失业务数组误报为零命中。","risk":"read","public":true,"reviewed":true}, + "+resolve-space": {"disposition":"primary_smart","semantic_delta":"把关键词搜索收敛为唯一 workspaceId；零命中与多命中显式分流，绝不猜测。","risk":"read","public":true,"reviewed":true}, + "+space-get": {"disposition":"schema_leaf","semantic_delta":"提供 Lark Shortcut 未单列的知识库详情入口，并要求 workspaceId 业务证据。","risk":"read","public":true,"reviewed":true}, + "+space-create": {"disposition":"primary_smart","semantic_delta":"创建后要求 workspaceId 并通过空间详情读回验证真实落库。","risk":"write","public":true,"reviewed":true}, + "+delete-space": {"disposition":"semantic_adapter","semantic_delta":"删除前读取影响目标，经高风险确认后只接受 success=true 终态。","risk":"high-risk-write","public":true,"reviewed":true}, + + "+member-add": {"disposition":"primary_smart","semantic_delta":"批量授予 Wiki 容器角色，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, + "+member-update": {"disposition":"primary_smart","semantic_delta":"补充 Lark Shortcut 缺失的成员角色更新，并执行终态与列表读回校验。","risk":"write","public":true,"reviewed":true}, + "+member-list": {"disposition":"semantic_adapter","semantic_delta":"严格验证成员数组并公开真实单次上限 50；后端无游标时不伪造 page-all。","risk":"read","public":true,"reviewed":true}, + "+member-remove": {"disposition":"primary_smart","semantic_delta":"批量移除容器访问，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, + + "+node-list": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空目录与假空成功，稳定投影节点并保留 nextCursor/hasMore。","risk":"read","public":true,"reviewed":true}, + "+node-get": {"disposition":"schema_leaf","semantic_delta":"统一节点 ID 或在线文档 URL 的元数据读取，补充文档域属性视角。","risk":"read","public":true,"reviewed":true}, + "+node-search": {"disposition":"semantic_adapter","semantic_delta":"补充 Lark Wiki Shortcut 缺失的库内关键词和扩展名搜索，并拒绝假空结果。","risk":"read","public":true,"reviewed":true}, + "+node-create": {"disposition":"primary_smart","semantic_delta":"支持七种 Wiki 节点类型，创建后要求 nodeId 并读取元数据验证。","risk":"write","public":true,"reviewed":true}, + "+node-copy": {"disposition":"primary_smart","semantic_delta":"高风险确认后复制，必须取得新 nodeId 并读回副本，避免空响应被当作成功。","risk":"high-risk-write","public":true,"reviewed":true}, + "+move": {"disposition":"primary_smart","semantic_delta":"同一入口覆盖 Wiki 内移动和我的文档在线节点入 Wiki，并校验目标 workspace/folder。","risk":"write","public":true,"reviewed":true}, + "+move-to-drive": {"disposition":"primary_smart","semantic_delta":"同步移动 Wiki 节点到我的文档并读回验证 workspace 变化，免去异步任务轮询。","risk":"write","public":true,"reviewed":true}, + "+node-delete": {"disposition":"semantic_adapter","semantic_delta":"删除前读取并核对 workspace，经高风险确认后要求 success=true 终态证据。","risk":"high-risk-write","public":true,"reviewed":true}, + + "+feed-list": {"disposition":"semantic_adapter","semantic_delta":"补充 Lark Shortcut 缺失的知识库协作动态查询，严格验证 feeds 并保留游标。","risk":"read","public":true,"reviewed":true}, + "+wiki-new-doc": {"disposition":"primary_smart","semantic_delta":"按空间名精确唯一解析、创建在线文档并读回验证；零命中和歧义均显式失败。","risk":"write","public":true,"reviewed":true} + } +} diff --git a/internal/shortcut/smart/resolve_space.go b/internal/shortcut/smart/resolve_space.go index 496c13c8..0008151c 100644 --- a/internal/shortcut/smart/resolve_space.go +++ b/internal/shortcut/smart/resolve_space.go @@ -14,7 +14,13 @@ package smart import ( + "encoding/json" + "fmt" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -35,15 +41,25 @@ import ( // // dws wiki +resolve-space --name 产品文档 var ResolveSpace = shortcut.Shortcut{ - Service: "wiki", - Command: "+resolve-space", - Product: "wiki", - Description: "按名称搜索知识空间并解析出唯一 spaceId（只读）", + OutputRollout: output.RolloutUnifiedActive, + Service: "wiki", + Command: "+resolve-space", + Product: "wiki", + Description: "按名称搜索知识空间并解析出唯一 spaceId（只读）", Intent: "当你只知道某个知识空间（wiki space）的名称（或名称里的关键词）、想把它解析成可直接用于后续工具的 spaceId 时使用；" + "内部按 --name 关键词调用 search_wikiSpaces 搜索知识空间，再在本地投影出每个候选的 spaceId 和 name。" + "如果只命中一个知识空间就直接返回它的 spaceId；如果命中多个则列出全部候选让你消歧，绝不替你瞎猜；如果一个都没命中则提示未找到。" + "这是纯只读操作，只做搜索与本地投影，不会修改任何知识空间。", - Risk: shortcut.RiskRead, + Risk: shortcut.RiskRead, + Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"}, + Contract: corecmd.ContractDecl{ + Description: "按名称搜索知识空间并解析出唯一 spaceId（只读）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"知识库名称解析结果","properties":{"resolved":{"type":"boolean","description":"是否唯一解析"},"spaceId":{"type":"string","description":"唯一知识库 ID"},"name":{"type":"string","description":"唯一知识库名称"},"count":{"type":"integer","description":"候选数量"},"candidates":{"type":"array","description":"需要消歧的候选知识库","items":{"type":"object","description":"知识库候选","additionalProperties":true}}},"required":["resolved"],"additionalProperties":true}`)}, + Interface: &contract.InterfaceSpec{Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: "Reviewed Wiki resolver: the executable CLI strictly validates search results and refuses to guess when multiple spaces match."}, + Selection: contract.SelectionSpec{AgentSummary: "按名称搜索知识空间并解析出唯一 spaceId（只读）", UseWhen: []string{"当你只知道某个知识空间（wiki space）的名称（或名称里的关键词）、想把它解析成可直接用于后续工具的 spaceId 时使用；内部按 --name 关键词调用 search_wikiSpaces 搜索知识空间，再在本地投影出每个候选的 spaceId 和 name。如果只命中一个知识空间就直接返回它的 spaceId；如果命中多个则列出全部候选让你消歧，绝不替你瞎猜；如果一个都没命中则提示未找到。这是纯只读操作，只做搜索与本地投影，不会修改任何知识空间。"}, AvoidWhen: []string{"只想浏览所有匹配项用 wiki +space-search；已知 workspaceId 时无需解析"}, Examples: []string{`dws wiki +resolve-space --name "产品文档"`}}, + Identity: contract.ToolIdentitySpec{ProductID: "wiki", Name: "shortcut_resolve_space", CanonicalPath: "wiki.shortcut_resolve_space", CLIPath: "wiki +resolve-space", PrimaryCLIPath: "wiki +resolve-space"}, + Parameters: []contract.ParamDecl{{Name: "name", Property: "keyword"}}, + }, Flags: []shortcut.Flag{ {Name: "name", Type: shortcut.FlagString, Desc: "要搜索的知识空间名称关键词（必填）", Required: true}, }, @@ -62,7 +78,10 @@ var ResolveSpace = shortcut.Shortcut{ } // Project candidates to {spaceId, name}, defensively unwrapping the list. - items := resolveSpaceItems(data) + items, err := resolveSpaceItemsStrict(data) + if err != nil { + return err + } candidates := make([]map[string]any, 0, len(items)) for _, s := range items { candidates = append(candidates, map[string]any{ @@ -123,7 +142,7 @@ func resolveSpaceItems(data map[string]any) []map[string]any { // resolveSpaceID reads a space's identifier, tolerating the common id keys. func resolveSpaceID(s map[string]any) string { - for _, key := range []string{"spaceId", "space_id", "id"} { + for _, key := range []string{"workspaceId", "spaceId", "space_id", "id"} { if v, ok := s[key].(string); ok && v != "" { return v } @@ -131,6 +150,53 @@ func resolveSpaceID(s map[string]any) string { return "" } +func resolveSpaceItemsStrict(data map[string]any) ([]map[string]any, error) { + if len(data) == 0 { + return nil, apperrors.NewAPI("search_wikiSpaces 返回空响应，不能当作零命中", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("empty_tool_response")) + } + if success, present := data["success"]; present { + value, ok := success.(bool) + if !ok || !value { + return nil, apperrors.NewAPI("search_wikiSpaces 未成功", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("remote_failure")) + } + } + containers := []map[string]any{data} + for _, wrapper := range []string{"result", "data"} { + if raw, present := data[wrapper]; present { + inner, ok := raw.(map[string]any) + if !ok { + return nil, apperrors.NewAPI("search_wikiSpaces 响应包装不是对象", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_envelope")) + } + containers = append(containers, inner) + } + } + for _, container := range containers { + for _, key := range []string{"wikiSpaces", "spaces", "items", "list", "records"} { + raw, present := container[key] + if !present { + continue + } + list, ok := raw.([]any) + if !ok { + return nil, apperrors.NewAPI("search_wikiSpaces 业务集合不是数组", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection")) + } + out := make([]map[string]any, 0, len(list)) + for index, item := range list { + object, ok := item.(map[string]any) + if !ok { + return nil, apperrors.NewAPI(fmt.Sprintf("search_wikiSpaces 第 %d 项不是对象", index), apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection_item")) + } + if resolveSpaceID(object) == "" || resolveSpaceName(object) == "" { + return nil, apperrors.NewAPI(fmt.Sprintf("search_wikiSpaces 第 %d 项缺少名称或 workspaceId", index), apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection_item")) + } + out = append(out, object) + } + return out, nil + } + } + return nil, apperrors.NewAPI("search_wikiSpaces 缺少 wikiSpaces 数组，不能投影为空", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("missing_collection")) +} + // resolveSpaceName reads a space's display name, tolerating the common name keys. func resolveSpaceName(s map[string]any) string { for _, key := range []string{"name", "spaceName", "title"} { diff --git a/internal/shortcut/smart/wiki_new_doc.go b/internal/shortcut/smart/wiki_new_doc.go index ebac09f6..85bde831 100644 --- a/internal/shortcut/smart/wiki_new_doc.go +++ b/internal/shortcut/smart/wiki_new_doc.go @@ -14,10 +14,14 @@ package smart import ( + "encoding/json" "fmt" "strings" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -33,15 +37,25 @@ import ( // // dws wiki +wiki-new-doc --space "产品文档库" --title "需求评审纪要" var WikiNewDoc = shortcut.Shortcut{ - Service: "wiki", - Command: "+wiki-new-doc", - Product: "wiki", - Description: "在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId）", + OutputRollout: output.RolloutUnifiedActive, + Service: "wiki", + Command: "+wiki-new-doc", + Product: "wiki", + Description: "在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId）", Intent: "当你只知道知识库（知识空间）的名字、想直接在它下面新建一篇文档，却不想先搜索空间、复制 workspaceId 再建节点时使用；" + "内部先按空间名搜索知识库，若唯一命中则拿到它的 workspaceId，再在该库根目录下创建一个在线文档节点。" + "如果这个名字没有匹配到任何知识库，或匹配到多个，会报错让你用更精确的名字，绝不乱猜。" + "这会真实创建一个新的文档节点。", - Risk: shortcut.RiskWrite, + Risk: shortcut.RiskWrite, + Safety: contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "not_required", Idempotency: "non_idempotent"}, + Contract: corecmd.ContractDecl{ + Description: "在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"已验证的新建 Wiki 文档","properties":{"success":{"type":"boolean","description":"是否成功"},"nodeId":{"type":"string","description":"新文档节点 ID"},"space":{"type":"string","description":"请求的知识库名称"},"title":{"type":"string","description":"请求的文档标题"},"document":{"type":"object","description":"读回的文档元数据","additionalProperties":true}},"required":["success","nodeId","space","title","document"],"additionalProperties":true}`)}, + Interface: &contract.InterfaceSpec{Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: "Reviewed Wiki smart Shortcut: the executable CLI strictly resolves one exact space, creates a document, and verifies it through a metadata read-back."}, + Selection: contract.SelectionSpec{AgentSummary: "在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId）", UseWhen: []string{"当你只知道知识库（知识空间）的名字、想直接在它下面新建一篇文档，却不想先搜索空间、复制 workspaceId 再建节点时使用；内部先按空间名搜索知识库，若唯一命中则拿到它的 workspaceId，再在该库根目录下创建一个在线文档节点。如果这个名字没有匹配到任何知识库，或匹配到多个，会报错让你用更精确的名字，绝不乱猜。这会真实创建一个新的文档节点。"}, AvoidWhen: []string{"已知 workspaceId 时用 wiki +node-create；空间名不唯一时先用 wiki +space-search"}, Examples: []string{`dws wiki +wiki-new-doc --space "产品文档库" --title "需求评审纪要"`}}, + Identity: contract.ToolIdentitySpec{ProductID: "wiki", Name: "shortcut_wiki_new_doc", CanonicalPath: "wiki.shortcut_wiki_new_doc", CLIPath: "wiki +wiki-new-doc", PrimaryCLIPath: "wiki +wiki-new-doc"}, + Parameters: []contract.ParamDecl{{Name: "space", Property: "keyword"}, {Name: "title", Property: "name"}}, + }, Flags: []shortcut.Flag{ {Name: "space", Type: shortcut.FlagString, Desc: "知识库（知识空间）名称", Required: true}, {Name: "title", Type: shortcut.FlagString, Desc: "新建文档的标题", Required: true}, @@ -88,7 +102,7 @@ var WikiNewDoc = shortcut.Shortcut{ "wouldCreateIn": workspaceID, }) } - created, err := rt.CallMCPWriteData("doc", "create_file", map[string]any{ + created, err := rt.CallMCPWriteDataStrict("doc", "create_file", map[string]any{ "workspaceId": workspaceID, "name": title, "type": "adoc", @@ -96,13 +110,28 @@ var WikiNewDoc = shortcut.Shortcut{ if err != nil { return err } - // Surface the created doc (id/url in the response) instead of returning - // silently — previously the caller got no confirmation of the new doc. + if success, ok := created["success"].(bool); !ok || !success { + return apperrors.NewAPI("create_file 未返回 success=true，无法证明文档已创建", apperrors.WithOperation("doc/create_file"), apperrors.WithReason("missing_terminal_success")) + } + nodeID := wikiNewDocFirstString(created, "nodeId", "fileId", "id") + if nodeID == "" { + return apperrors.NewAPI("create_file 未返回 nodeId，远端效果未知", apperrors.WithOperation("doc/create_file"), apperrors.WithReason("missing_created_id")) + } + verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": nodeID}) + if err != nil { + return err + } + if success, present := verified["success"]; present { + value, ok := success.(bool) + if !ok || !value { + return apperrors.NewAPI("新建文档读回未成功", apperrors.WithOperation("doc/get_document_info"), apperrors.WithReason("readback_failed")) + } + } + if wikiNewDocFirstString(verified, "nodeId", "fileId", "id") != nodeID { + return apperrors.NewAPI("新建文档读回 nodeId 不一致", apperrors.WithOperation("doc/get_document_info"), apperrors.WithReason("readback_id_mismatch")) + } return rt.Output(map[string]any{ - "created": true, - "space": spaceName, - "title": title, - "result": created, + "success": true, "nodeId": nodeID, "space": spaceName, "title": title, "document": verified, }) }, } @@ -117,7 +146,10 @@ type wikiSpaceCandidate struct { // out of a search_wikiSpaces response and returns its workspaceId. It errors // clearly when nothing matches or when the name is ambiguous, never guessing. func wikiNewDocResolveSpaceID(data map[string]any, spaceName string) (string, error) { - spaces := wikiNewDocExtractSpaces(data) + spaces, err := wikiNewDocExtractSpaces(data) + if err != nil { + return "", err + } if len(spaces) == 0 { return "", apperrors.NewValidation(fmt.Sprintf( "没找到名为 %q 的知识库；换个更完整/精确的空间名再试。", spaceName)) @@ -156,9 +188,15 @@ func wikiNewDocResolveSpaceID(data map[string]any, spaceName string) (string, er // wikiNewDocExtractSpaces flattens the several shapes a search_wikiSpaces // response may take into a list of {id, name} candidates. The gateway wraps the // list under one of several common container keys, so probe them defensively. -func wikiNewDocExtractSpaces(data map[string]any) []wikiSpaceCandidate { +func wikiNewDocExtractSpaces(data map[string]any) ([]wikiSpaceCandidate, error) { if data == nil { - return nil + return nil, apperrors.NewAPI("search_wikiSpaces 返回空响应，不能当作零命中", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("empty_tool_response")) + } + if success, present := data["success"]; present { + value, ok := success.(bool) + if !ok || !value { + return nil, apperrors.NewAPI("search_wikiSpaces 未成功", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("remote_failure")) + } } for _, key := range []string{"result", "data", "list", "wikiSpaces", "spaces", "items", "records"} { switch v := data[key].(type) { @@ -166,21 +204,25 @@ func wikiNewDocExtractSpaces(data map[string]any) []wikiSpaceCandidate { return wikiNewDocToCandidates(v) case map[string]any: for _, k2 := range []string{"list", "wikiSpaces", "spaces", "items", "records", "result"} { - if arr, ok := v[k2].([]any); ok { + if raw, present := v[k2]; present { + arr, ok := raw.([]any) + if !ok { + return nil, apperrors.NewAPI("search_wikiSpaces 业务集合不是数组", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection")) + } return wikiNewDocToCandidates(arr) } } } } - return nil + return nil, apperrors.NewAPI("search_wikiSpaces 缺少 wikiSpaces 数组，不能投影为空", apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("missing_collection")) } -func wikiNewDocToCandidates(arr []any) []wikiSpaceCandidate { +func wikiNewDocToCandidates(arr []any) ([]wikiSpaceCandidate, error) { out := make([]wikiSpaceCandidate, 0, len(arr)) - for _, it := range arr { + for index, it := range arr { m, ok := it.(map[string]any) if !ok { - continue + return nil, apperrors.NewAPI(fmt.Sprintf("search_wikiSpaces 结果第 %d 项不是对象", index), apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection_item")) } id := "" for _, k := range []string{"workspaceId", "spaceId", "id"} { @@ -196,12 +238,30 @@ func wikiNewDocToCandidates(arr []any) []wikiSpaceCandidate { break } } - if id == "" && name == "" { - continue + if id == "" || name == "" { + return nil, apperrors.NewAPI(fmt.Sprintf("search_wikiSpaces 结果第 %d 项缺少名称或 workspaceId", index), apperrors.WithOperation("wiki/search_wikiSpaces"), apperrors.WithReason("malformed_collection_item")) } out = append(out, wikiSpaceCandidate{id: id, name: name}) } - return out + return out, nil +} + +func wikiNewDocFirstString(data map[string]any, keys ...string) string { + for _, key := range keys { + if value, ok := data[key].(string); ok && strings.TrimSpace(value) != "" { + return strings.TrimSpace(value) + } + } + for _, wrapper := range []string{"result", "data"} { + if inner, ok := data[wrapper].(map[string]any); ok { + for _, key := range keys { + if value, ok := inner[key].(string); ok && strings.TrimSpace(value) != "" { + return strings.TrimSpace(value) + } + } + } + } + return "" } func wikiNewDocLabels(spaces []wikiSpaceCandidate) []string { diff --git a/internal/shortcut/wiki/common.go b/internal/shortcut/wiki/common.go new file mode 100644 index 00000000..1479315b --- /dev/null +++ b/internal/shortcut/wiki/common.go @@ -0,0 +1,274 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package wiki + +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +const wikiCompositeReason = "Reviewed Wiki Shortcut composite: the executable CLI owns strict response validation, pagination projection, optional multi-step orchestration, read-back verification, and confirmation; no single MCP interface represents the complete command contract." + +func wikiContract(command, description, useWhen string, avoidWhen, examples []string, result *contract.ResultSpec, pagination *contract.PaginationSpec, params ...contract.ParamDecl) corecmd.ContractDecl { + name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(command, "+"), "-", "_") + cliPath := "wiki " + command + return corecmd.ContractDecl{ + Description: description, Parameters: params, Result: result, Pagination: pagination, + Interface: &contract.InterfaceSpec{Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: wikiCompositeReason}, + Selection: contract.SelectionSpec{AgentSummary: description, UseWhen: []string{useWhen}, AvoidWhen: avoidWhen, Examples: examples}, + Identity: contract.ToolIdentitySpec{ProductID: "wiki", Name: name, CanonicalPath: "wiki." + name, CLIPath: cliPath, PrimaryCLIPath: cliPath}, + } +} + +func wikiObjectResult(description string) *contract.ResultSpec { + return &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(fmt.Sprintf(`{"type":"object","description":%q,"additionalProperties":true}`, description))} +} + +func wikiCollectionResult(collection, description string) *contract.ResultSpec { + return &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"有效结果数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"Wiki 业务条目","additionalProperties":true}},"nextCursor":{"type":"string","description":"下一页游标"},"hasMore":{"type":"boolean","description":"服务端是否仍有下一页"}},"required":["count",%q],"additionalProperties":true}`, + description, collection, description, collection))} +} + +func wikiCursorPagination() *contract.PaginationSpec { + return &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor", MetaPath: contract.PaginationMetaPath, EndpointExhaustedPath: contract.PaginationExhaustedPath, NextTokenPath: contract.PaginationNextTokenPath} +} + +func requireWikiResponse(data map[string]any, operation string) (map[string]any, error) { + if len(data) == 0 { + return nil, wikiResponseError(operation, "empty_tool_response", "服务返回空响应，无法证明操作成功") + } + if value, present := data["success"]; present { + success, ok := value.(bool) + if !ok { + return nil, wikiResponseError(operation, "malformed_success", "响应 success 字段不是布尔值") + } + if !success { + message := firstWikiString(data, "errorMsg", "message", "error") + if message == "" { + message = "服务明确返回 success=false" + } + return nil, wikiResponseError(operation, "remote_failure", message) + } + } + return data, nil +} + +func requireWikiWrite(data map[string]any, operation string) (map[string]any, error) { + data, err := requireWikiResponse(data, operation) + if err != nil { + return nil, err + } + if success, ok := data["success"].(bool); !ok || !success { + return nil, wikiResponseError(operation, "missing_terminal_success", "写操作响应没有 success=true 终态证据") + } + return data, nil +} + +func requireWikiObject(data map[string]any, operation string) (map[string]any, error) { + data, err := requireWikiResponse(data, operation) + if err != nil { + return nil, err + } + for _, wrapper := range []string{"result", "data"} { + if value, present := data[wrapper]; present { + object, ok := value.(map[string]any) + if !ok || len(object) == 0 { + return nil, wikiResponseError(operation, "malformed_object", "响应业务对象缺失或畸形") + } + return object, nil + } + } + if len(data) == 1 { + return nil, wikiResponseError(operation, "missing_business_result", "响应没有可验证的业务对象") + } + return data, nil +} + +func requireWikiCollection(data map[string]any, operation string, keys ...string) ([]any, map[string]any, error) { + data, err := requireWikiResponse(data, operation) + if err != nil { + return nil, nil, err + } + containers := []map[string]any{data} + for _, wrapper := range []string{"result", "data"} { + if value, present := data[wrapper]; present { + inner, ok := value.(map[string]any) + if !ok { + return nil, nil, wikiResponseError(operation, "malformed_envelope", fmt.Sprintf("响应 %s 字段不是对象", wrapper)) + } + containers = append(containers, inner) + } + } + for _, container := range containers { + for _, key := range keys { + value, present := container[key] + if !present { + continue + } + items, ok := value.([]any) + if !ok { + return nil, nil, wikiResponseError(operation, "malformed_collection", fmt.Sprintf("响应 %s 字段不是数组", key)) + } + for index, item := range items { + if _, ok := item.(map[string]any); !ok { + return nil, nil, wikiResponseError(operation, "malformed_collection_item", fmt.Sprintf("响应 %s[%d] 不是对象", key, index)) + } + } + return items, container, nil + } + } + return nil, nil, wikiResponseError(operation, "missing_collection", "响应缺少声明的业务数组；不能把缺字段或内部错误投影成空结果") +} + +func projectWikiRows(items []any, aliases map[string][]string) []map[string]any { + rows := make([]map[string]any, 0, len(items)) + for _, item := range items { + source := item.(map[string]any) + row := make(map[string]any) + for canonical, candidates := range aliases { + for _, candidate := range candidates { + if value, ok := source[candidate]; ok && value != nil { + row[canonical] = value + break + } + } + } + rows = append(rows, row) + } + return rows +} + +func addWikiPagination(out, page map[string]any) { + for _, pair := range [][2]string{{"nextCursor", "nextCursor"}, {"nextToken", "nextCursor"}, {"nextPageToken", "nextCursor"}, {"pageToken", "nextCursor"}, {"hasMore", "hasMore"}, {"truncated", "truncated"}, {"totalCount", "totalCount"}, {"autoPageComplete", "autoPageComplete"}, {"autoPageStopReason", "autoPageStopReason"}, {"pagesFetched", "pagesFetched"}} { + if value, ok := page[pair[0]]; ok && value != nil { + out[pair[1]] = value + } + } +} + +func firstWikiString(data map[string]any, keys ...string) string { + for _, key := range keys { + if value, ok := data[key].(string); ok && strings.TrimSpace(value) != "" { + return strings.TrimSpace(value) + } + } + return "" +} + +func nestedWikiString(data map[string]any, keys ...string) string { + if value := firstWikiString(data, keys...); value != "" { + return value + } + for _, wrapper := range []string{"result", "data"} { + if inner, ok := data[wrapper].(map[string]any); ok { + if value := firstWikiString(inner, keys...); value != "" { + return value + } + } + } + return "" +} + +func wikiResponseError(operation, reason, message string) error { + return apperrors.NewAPI(message, apperrors.WithOperation(operation), apperrors.WithOrigin("mcp"), apperrors.WithFailureStage("response_validation"), apperrors.WithRetryable(false), apperrors.WithReason(reason)) +} + +func wikiReadSafety() contract.SafetySpec { + return contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"} +} +func wikiWriteSafety(confirm bool) contract.SafetySpec { + confirmation := "not_required" + if confirm { + confirmation = "user_required" + } + return contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: confirmation, Idempotency: "unknown"} +} +func wikiDeleteSafety() contract.SafetySpec { + return contract.SafetySpec{Effect: "destructive", Risk: "high", Confirmation: "user_required", Idempotency: "unknown"} +} + +func wikiAutoPageFlags() []shortcut.Flag { + const evidence = "--max-items/--page-delay 仅与 --page-all 一起使用；值必须大于等于 0" + return append([]shortcut.Flag{{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动沿游标取完所有页。" + evidence}, {Name: "page-limit", Type: shortcut.FlagInt, Default: "20", Desc: "自动翻页最多请求页数。" + evidence}}, shortcut.AutoPageControlFlags()...) +} + +func enableWikiAutoPage(item *shortcut.Shortcut) { + item.Flags = append(item.Flags, wikiAutoPageFlags()...) + item.Constraints = append(item.Constraints, shortcut.AutoPageControlConstraints()...) + item.Validate = func(rt *shortcut.RuntimeContext) error { + if err := shortcut.ValidateAutoPageControls(rt); err != nil { + return err + } + if rt.Bool("page-all") && rt.Int("page-limit") < 1 { + return fmt.Errorf("--page-limit 必须大于 0") + } + return nil + } +} + +type wikiPageFetcher func(cursor string, pageSize int) (map[string]any, error) + +func collectWikiPages(rt *shortcut.RuntimeContext, operation string, pageSize int, keys []string, fetch wikiPageFetcher) ([]any, map[string]any, error) { + if !rt.Bool("page-all") { + data, err := fetch(rt.Str("cursor"), pageSize) + if err != nil { + return nil, nil, err + } + return requireWikiCollection(data, operation, keys...) + } + all := make([]any, 0) + cursor := rt.Str("cursor") + lastPage := map[string]any{} + for pageNumber := 1; pageNumber <= rt.Int("page-limit"); pageNumber++ { + requestSize := shortcut.AutoPageRequestSize(rt, pageSize, len(all)) + data, err := fetch(cursor, requestSize) + if err != nil { + return nil, nil, err + } + items, page, err := requireWikiCollection(data, operation, keys...) + if err != nil { + return nil, nil, err + } + all = append(all, items...) + lastPage = page + if maxItems := rt.Int("max-items"); maxItems > 0 && len(all) >= maxItems { + lastPage["autoPageComplete"] = false + lastPage["autoPageStopReason"] = "max_items" + lastPage["pagesFetched"] = pageNumber + return all, lastPage, nil + } + hasMore, present := page["hasMore"] + if !present { + return nil, nil, wikiResponseError(operation, "missing_has_more", "--page-all 要求每页响应提供 hasMore 布尔值") + } + more, ok := hasMore.(bool) + if !ok { + return nil, nil, wikiResponseError(operation, "malformed_has_more", "分页响应 hasMore 不是布尔值") + } + if !more { + lastPage["autoPageComplete"] = true + lastPage["pagesFetched"] = pageNumber + return all, lastPage, nil + } + next := firstWikiString(page, "nextCursor", "nextToken", "nextPageToken", "pageToken") + if next == "" { + return nil, nil, wikiResponseError(operation, "missing_next_cursor", "hasMore=true 但响应缺少下一页游标") + } + if next == cursor { + return nil, nil, wikiResponseError(operation, "stalled_cursor", "下一页游标未变化，已停止以避免死循环") + } + cursor = next + if err := shortcut.WaitAutoPageDelay(rt); err != nil { + return nil, nil, err + } + } + return nil, nil, wikiResponseError(operation, "page_limit_reached", "达到 --page-limit 时服务端仍有下一页；提高页数上限或使用返回游标续传") +} diff --git a/internal/shortcut/wiki/nodes.go b/internal/shortcut/wiki/nodes.go new file mode 100644 index 00000000..0655992c --- /dev/null +++ b/internal/shortcut/wiki/nodes.go @@ -0,0 +1,254 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package wiki + +import ( + "fmt" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +var NodeList = readShortcut("+node-list", "严格分页列出知识库节点", "浏览知识库根目录或指定文件夹；只有显式 nodes:[] 才表示空目录，并完整保留 nextCursor/hasMore。", "nodes", []shortcut.Flag{ + {Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "父节点 ID"}, {Name: "limit", Type: shortcut.FlagInt, Default: "50", Desc: "每页数量 1-50"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, +}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "folder", Property: "folderId"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { + items, page, err := collectWikiPages(rt, "wiki/list_nodes", rt.Int("limit"), []string{"nodes", "items", "list"}, func(cursor string, size int) (map[string]any, error) { + params := map[string]any{"workspaceId": rt.Str("workspace"), "pageSize": size} + if rt.Changed("folder") { + params["folderId"] = rt.Str("folder") + } + if cursor != "" { + params["pageToken"] = cursor + } + return rt.CallMCPData("doc", "list_nodes", params) + }) + if err != nil { + return err + } + nodes := projectWikiRows(items, nodeAliases()) + out := map[string]any{"count": len(nodes), "nodes": nodes} + addWikiPagination(out, page) + return rt.Output(out) +}) + +func nodeAliases() map[string][]string { + return map[string][]string{"nodeId": {"nodeId", "id", "dentryUuid", "fileId"}, "name": {"name", "title", "nodeName", "fileName"}, "type": {"type", "nodeType", "docType", "fileType"}, "contentType": {"contentType"}, "folderId": {"folderId", "parentId"}, "workspaceId": {"workspaceId", "spaceId"}, "url": {"docUrl", "url", "webUrl"}} +} + +var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知节点 ID 或在线文档 URL 时读取元数据；比 Lark Wiki 仅返回节点元数据的视角额外统一文档/文件属性。", "", []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID 或 URL"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { + data, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) + if err != nil { + return err + } + object, err := requireWikiObject(data, "doc/get_document_info") + if err != nil { + return err + } + if firstWikiString(object, "nodeId", "id", "fileId") == "" { + return wikiResponseError("doc/get_document_info", "missing_node_id", "节点详情缺少 nodeId") + } + return rt.Output(object) +}) + +var NodeSearch = readShortcut("+node-search", "严格搜索知识库节点", "在指定知识库内按关键词和扩展名搜索节点；零命中必须来自显式 documents:[]。", "nodes", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "关键词"}, {Name: "extensions", Type: shortcut.FlagStringSlice, Desc: "扩展名过滤"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-30"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceIds"}, {Name: "query", Property: "keyword"}, {Name: "extensions", Property: "extensions"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { + params := map[string]any{"workspaceIds": []string{rt.Str("workspace")}, "keyword": rt.Str("query"), "pageSize": rt.Int("limit")} + if rt.Changed("extensions") { + params["extensions"] = rt.StrSlice("extensions") + } + if rt.Changed("cursor") { + params["pageToken"] = rt.Str("cursor") + } + data, err := rt.CallMCPData("doc", "search_documents", params) + if err != nil { + return err + } + items, page, err := requireWikiCollection(data, "doc/search_documents", "documents", "docs", "nodes", "items", "list") + if err != nil { + return err + } + nodes := projectWikiRows(items, nodeAliases()) + out := map[string]any{"count": len(nodes), "nodes": nodes} + addWikiPagination(out, page) + return rt.Output(out) +}) + +var NodeCreate = writeShortcut("+node-create", "创建知识库节点并读回验证", "在知识库根目录或文件夹中创建文档、表格、白板、脑图或文件夹；取得 nodeId 并读回后才成功。", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "name", Type: shortcut.FlagString, Required: true, Desc: "节点名称"}, {Name: "type", Type: shortcut.FlagString, Default: "adoc", Desc: "节点类型", Enum: []string{"adoc", "axls", "able", "appt", "adraw", "amind", "folder"}}, {Name: "folder", Type: shortcut.FlagString, Desc: "父文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "name", Property: "name"}, {Name: "type", Property: "type"}, {Name: "folder", Property: "folderId"}}, func(rt *shortcut.RuntimeContext) error { + params := map[string]any{"workspaceId": rt.Str("workspace"), "name": rt.Str("name"), "type": rt.Str("type")} + if rt.Changed("folder") { + params["folderId"] = rt.Str("folder") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "doc/create_file", "arguments": params}) + } + written, err := rt.CallMCPWriteDataStrict("doc", "create_file", params) + if err != nil { + return err + } + written, err = requireWikiWrite(written, "doc/create_file") + if err != nil { + return err + } + id := nestedWikiString(written, "nodeId", "fileId", "id") + if id == "" { + return wikiResponseError("doc/create_file", "missing_created_id", "创建响应没有 nodeId；远端效果未知") + } + verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": id}) + if err != nil { + return err + } + verified, err = requireWikiObject(verified, "doc/get_document_info") + if err != nil { + return err + } + if firstWikiString(verified, "nodeId", "id", "fileId") != id { + return wikiResponseError("doc/create_file", "readback_id_mismatch", "创建后读回节点 ID 不一致") + } + return rt.Output(map[string]any{"success": true, "nodeId": id, "node": verified}) +}) + +var NodeCopy = writeShortcut("+node-copy", "复制知识库节点并读回验证", "复制现有在线节点到目标知识库/文件夹；高风险确认后要求新 nodeId 并读取副本元数据。", shortcut.RiskHighWrite, contract.SafetySpec{Effect: "write", Risk: "high", Confirmation: "user_required", Idempotency: "non_idempotent"}, []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "源节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { + params := map[string]any{"workspaceId": rt.Str("workspace"), "nodeId": rt.Str("node")} + if rt.Changed("folder") { + params["targetFolderId"] = rt.Str("folder") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "doc/copy_document", "arguments": params}) + } + written, err := rt.CallMCPWriteDataStrict("doc", "copy_document", params) + if err != nil { + return err + } + written, err = requireWikiWrite(written, "doc/copy_document") + if err != nil { + return err + } + id := nestedWikiString(written, "nodeId", "fileId", "id") + if id == "" { + return wikiResponseError("doc/copy_document", "missing_created_id", "复制响应没有新 nodeId；远端效果未知") + } + verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": id}) + if err != nil { + return err + } + verified, err = requireWikiObject(verified, "doc/get_document_info") + if err != nil { + return err + } + return rt.Output(map[string]any{"success": true, "sourceNodeId": rt.Str("node"), "nodeId": id, "copy": verified}) +}) + +func executeMove(rt *shortcut.RuntimeContext, toDrive bool) error { + preflight, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) + if err != nil { + return err + } + preflight, err = requireWikiObject(preflight, "doc/get_document_info") + if err != nil { + return err + } + beforeWorkspace := firstWikiString(preflight, "workspaceId", "spaceId") + params := map[string]any{"nodeId": rt.Str("node")} + if !toDrive { + params["workspaceId"] = rt.Str("workspace") + } + if rt.Changed("folder") { + params["targetFolderId"] = rt.Str("folder") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "doc/move_document", "arguments": params, "target": preflight}) + } + written, err := rt.CallMCPWriteDataStrict("doc", "move_document", params) + if err != nil { + return err + } + if _, err = requireWikiWrite(written, "doc/move_document"); err != nil { + return err + } + verified, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) + if err != nil { + return err + } + verified, err = requireWikiObject(verified, "doc/get_document_info") + if err != nil { + return err + } + if firstWikiString(verified, "nodeId", "id", "fileId") != rt.Str("node") { + return wikiResponseError("doc/move_document", "readback_id_mismatch", "移动后读回节点 ID 不一致") + } + afterWorkspace := firstWikiString(verified, "workspaceId", "spaceId") + if toDrive { + if beforeWorkspace == "" || afterWorkspace == "" || beforeWorkspace == afterWorkspace { + return wikiResponseError("doc/move_document", "drive_move_not_verified", "移动到我的文档后 workspace 未发生可验证变化") + } + } else if afterWorkspace != rt.Str("workspace") { + return wikiResponseError("doc/move_document", "workspace_readback_mismatch", "移动后读回的目标知识库不一致") + } + if rt.Changed("folder") && firstWikiString(verified, "folderId", "parentId") != rt.Str("folder") { + return wikiResponseError("doc/move_document", "folder_readback_mismatch", "移动后读回的目标文件夹不一致") + } + return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "node": verified}) +} + +var Move = writeShortcut("+move", "移动节点到知识库并读回验证", "将 Wiki 节点或我的文档在线节点移动到目标知识库/文件夹；同时覆盖 Lark 的 Wiki 内移动与 Drive 文档入 Wiki 场景。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, false) }) + +var MoveToDrive = writeShortcut("+move-to-drive", "移动 Wiki 节点到我的文档", "将 Wiki 在线节点同步移动到我的文档或指定文件夹，并以元数据读回替代 Lark 异步任务轮询。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "Wiki 节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "我的文档目标文件夹 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, true) }) + +var NodeDelete = writeShortcut("+node-delete", "删除知识库节点", "明确确认后将节点移入回收站；先读取目标，且删除响应必须提供 success=true 终态证据。", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID，用于确认影响范围"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { + preflight, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) + if err != nil { + return err + } + preflight, err = requireWikiObject(preflight, "doc/get_document_info") + if err != nil { + return err + } + if workspace := firstWikiString(preflight, "workspaceId", "spaceId"); workspace != "" && workspace != rt.Str("workspace") { + return wikiResponseError("doc/delete_document", "workspace_preflight_mismatch", "节点不属于请求确认的知识库") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "doc/delete_document", "target": preflight}) + } + written, err := rt.CallMCPWriteDataStrict("doc", "delete_document", map[string]any{"nodeId": rt.Str("node")}) + if err != nil { + return err + } + if _, err = requireWikiWrite(written, "doc/delete_document"); err != nil { + return err + } + return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "deleted": true}) +}) + +var FeedList = readShortcut("+feed-list", "严格分页列出知识库动态", "查看谁在何时创建、更新或评论了知识库内容；严格验证 feeds 数组并保留游标。", "feeds", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-20"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}, {Name: "exclude-file", Type: shortcut.FlagBool, Desc: "排除普通文件动态"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "cursor", Property: "nextToken"}, {Name: "exclude-file", Property: "excludeFile"}}, func(rt *shortcut.RuntimeContext) error { + items, page, err := collectWikiPages(rt, "wiki/list_workspace_feeds", rt.Int("limit"), []string{"feeds", "items", "list"}, func(cursor string, size int) (map[string]any, error) { + params := map[string]any{"workspaceId": rt.Str("workspace"), "maxResults": size} + if cursor != "" { + params["nextToken"] = cursor + } + if rt.Changed("exclude-file") { + params["excludeFile"] = rt.Bool("exclude-file") + } + return rt.CallMCPData("wiki", "list_workspace_feeds", params) + }) + if err != nil { + return err + } + feeds := projectWikiRows(items, map[string][]string{"id": {"id", "feedId"}, "type": {"type", "feedType", "action"}, "time": {"time", "createTime"}, "name": {"name", "title", "fileName"}, "nodeId": {"nodeId", "fileId"}}) + out := map[string]any{"count": len(feeds), "feeds": feeds} + addWikiPagination(out, page) + return rt.Output(out) +}) + +func init() { + Move.Aliases = []string{"+node-move"} + for _, item := range []*shortcut.Shortcut{&NodeList, &FeedList} { + enableWikiAutoPage(item) + } + for _, item := range []*shortcut.Shortcut{&NodeList, &NodeSearch, &FeedList} { + item.Contract.Pagination = wikiCursorPagination() + } + shortcut.Register(NodeList, NodeGet, NodeSearch, NodeCreate, NodeCopy, Move, MoveToDrive, NodeDelete, FeedList) + _ = fmt.Sprintf + _ = output.RolloutUnifiedActive +} diff --git a/internal/shortcut/wiki/space_list_projection_test.go b/internal/shortcut/wiki/space_list_projection_test.go index da5602f0..69648bf2 100644 --- a/internal/shortcut/wiki/space_list_projection_test.go +++ b/internal/shortcut/wiki/space_list_projection_test.go @@ -18,11 +18,11 @@ import ( "testing" ) -// TestSpaceListProjectWikiSpacesShape guards against projection-data-loss: +// TestCrossPlatformCoverageWikiSpaceListShape guards against projection-data-loss: // list_wikiSpaces / search_wikiSpaces nest the list under result.wikiSpaces; // the resolver must probe "wikiSpaces" or +space-list / +space-search silently // return empty despite the backend returning spaces. -func TestSpaceListProjectWikiSpacesShape(t *testing.T) { +func TestCrossPlatformCoverageWikiSpaceListShape(t *testing.T) { const raw = `{"result":{"hasMore":false,"wikiSpaces":[ {"workspaceId":"w1","name":"R&D wiki"}, {"workspaceId":"w2","name":"product wiki"} @@ -31,19 +31,47 @@ func TestSpaceListProjectWikiSpacesShape(t *testing.T) { if err := json.Unmarshal([]byte(raw), &data); err != nil { t.Fatalf("unmarshal fixture: %v", err) } - if spaces := spaceListProject(data); len(spaces) != 2 { + items, _, err := requireWikiCollection(data, "wiki/list_wikiSpaces", "wikiSpaces") + if err != nil { + t.Fatal(err) + } + spaces := projectWikiRows(items, map[string][]string{"workspaceId": {"workspaceId"}, "name": {"name"}}) + if len(spaces) != 2 { t.Fatalf("lower/upper mismatch: result.wikiSpaces has 2 entries, projection returned %d (%v)", len(spaces), spaces) } } // TestSpaceListProjectTopLevelWikiSpaces covers the already-unwrapped shape. -func TestSpaceListProjectTopLevelWikiSpaces(t *testing.T) { +func TestCrossPlatformCoverageWikiSpaceListTopLevelShape(t *testing.T) { const raw = `{"wikiSpaces":[{"workspaceId":"w1","name":"R&D wiki"}]}` var data map[string]any if err := json.Unmarshal([]byte(raw), &data); err != nil { t.Fatalf("unmarshal fixture: %v", err) } - if spaces := spaceListProject(data); len(spaces) != 1 { + items, _, err := requireWikiCollection(data, "wiki/list_wikiSpaces", "wikiSpaces") + if err != nil { + t.Fatal(err) + } + spaces := projectWikiRows(items, map[string][]string{"workspaceId": {"workspaceId"}, "name": {"name"}}) + if len(spaces) != 1 { t.Fatalf("top-level wikiSpaces: want 1, got %d (%v)", len(spaces), spaces) } } + +func TestCrossPlatformCoverageWikiCollectionsRejectFalseEmptySuccess(t *testing.T) { + for name, data := range map[string]map[string]any{ + "missing": {"success": true, "hasMore": false}, + "malformed": {"success": true, "wikiSpaces": map[string]any{}}, + "bad item": {"success": true, "wikiSpaces": []any{"not-an-object"}}, + } { + t.Run(name, func(t *testing.T) { + if _, _, err := requireWikiCollection(data, "wiki/list_wikiSpaces", "wikiSpaces"); err == nil { + t.Fatal("malformed response was accepted as an empty success") + } + }) + } + items, _, err := requireWikiCollection(map[string]any{"success": true, "wikiSpaces": []any{}}, "wiki/list_wikiSpaces", "wikiSpaces") + if err != nil || len(items) != 0 { + t.Fatalf("explicit empty array must remain valid: items=%v err=%v", items, err) + } +} diff --git a/internal/shortcut/wiki/wiki.go b/internal/shortcut/wiki/wiki.go index 4e8d0990..28012ba8 100644 --- a/internal/shortcut/wiki/wiki.go +++ b/internal/shortcut/wiki/wiki.go @@ -1,344 +1,249 @@ // Copyright 2026 Alibaba Group -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Licensed under the Apache License, Version 2.0 -// Package wiki declares high-fidelity shortcuts for the DingTalk wiki -// (knowledge base) service: space management, member management and node -// management. Tool names and parameters mirror internal/helpers/wiki.go. +// Package wiki declares reviewed, truth-preserving shortcuts for Wiki spaces, +// members, nodes, and activity feeds. package wiki import ( - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "fmt" + "strings" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) -// ── space (知识库) ──────────────────────────────────────────── +var collectionAvoid = []string{"需要原始 MCP 响应或未公开底层参数时改用对应原子命令；缺失业务数组不是合法空结果"} -// SpaceCreate → create_wikiSpace -// SpaceGet → get_wikiSpace -// SpaceList → list_wikiSpaces -var SpaceList = shortcut.Shortcut{ - Service: "wiki", - Command: "+space-list", - Product: "wiki", - Description: "列出组织 / 个人知识库", - Intent: "当你想浏览自己有权限访问的知识库、拿到目标知识库的 workspaceId 却不确定具体名称时使用；可按类型（组织知识库或我的知识库）分页列出，返回知识库列表，是定位知识库的常用入口。", - Risk: shortcut.RiskRead, - Flags: []shortcut.Flag{ - {Name: "type", Type: shortcut.FlagString, Default: "orgWikiSpace", Desc: "知识库类型: orgWikiSpace(默认) / myWikiSpace", Enum: []string{"orgWikiSpace", "myWikiSpace"}}, - {Name: "limit", Type: shortcut.FlagString, Desc: "每页数量 1-50 (默认 20)"}, - {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标 (首页留空)"}, - }, - Tips: []string{ - `dws wiki +space-list`, - `dws wiki +space-list --type myWikiSpace`, - }, - Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{} - if rt.Changed("type") { - params["wikiSpaceType"] = rt.Str("type") +func readShortcut(command, description, intent, collection string, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { + result := wikiObjectResult(description) + if collection != "" { + result = wikiCollectionResult(collection, description) + } + return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: shortcut.RiskRead, Safety: wikiReadSafety(), Contract: wikiContract(command, description, intent, collectionAvoid, []string{"dws wiki " + command + " --format json"}, result, nil, params...), Flags: flags, Execute: execute} +} + +func writeShortcut(command, description, intent string, risk shortcut.Risk, safety contract.SafetySpec, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { + return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: risk, Safety: safety, Contract: wikiContract(command, description, intent, []string{"只需读取或影响范围未确认时不要执行写操作"}, []string{"dws wiki " + command + " --format json"}, wikiObjectResult(description), nil, params...), Flags: flags, Execute: execute} +} + +var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏览有权访问的组织或个人知识库，并保留服务端分页证据；只有显式 wikiSpaces:[] 才是空结果。", "spaces", []shortcut.Flag{ + {Name: "type", Type: shortcut.FlagString, Default: "orgWikiSpace", Desc: "知识库类型", Enum: []string{"orgWikiSpace", "myWikiSpace"}}, + {Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量 1-50"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, +}, []contract.ParamDecl{{Name: "type", Property: "wikiSpaceType"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { + items, page, err := collectWikiPages(rt, "wiki/list_wikiSpaces", rt.Int("limit"), []string{"wikiSpaces", "spaces"}, func(cursor string, size int) (map[string]any, error) { + params := map[string]any{"wikiSpaceType": rt.Str("type"), "pageSize": size} + if cursor != "" { + params["pageToken"] = cursor } - if rt.Changed("limit") { - params["pageSize"] = rt.Str("limit") + return rt.CallMCPData("wiki", "list_wikiSpaces", params) + }) + if err != nil { + return err + } + spaces := projectWikiRows(items, map[string][]string{"workspaceId": {"workspaceId", "spaceId", "id"}, "name": {"name", "spaceName", "title"}, "description": {"description", "desc"}, "createTime": {"createTime", "createdAt"}, "url": {"spaceUrl", "url"}}) + out := map[string]any{"count": len(spaces), "spaces": spaces} + addWikiPagination(out, page) + return rt.Output(out) +}) + +var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", []shortcut.Flag{ + {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "返回数量 1-20"}, +}, []contract.ParamDecl{{Name: "query", Property: "query"}, {Name: "limit", Property: "pageSize"}}, func(rt *shortcut.RuntimeContext) error { + data, err := rt.CallMCPData("wiki", "search_wikiSpaces", map[string]any{"keyword": rt.Str("query"), "pageSize": rt.Int("limit")}) + if err != nil { + return err + } + items, page, err := requireWikiCollection(data, "wiki/search_wikiSpaces", "wikiSpaces", "spaces") + if err != nil { + return err + } + spaces := projectWikiRows(items, map[string][]string{"workspaceId": {"workspaceId", "spaceId", "id"}, "name": {"name", "spaceName", "title"}, "description": {"description", "desc"}, "url": {"spaceUrl", "url"}}) + out := map[string]any{"count": len(spaces), "spaces": spaces} + addWikiPagination(out, page) + return rt.Output(out) +}) + +var SpaceGet = readShortcut("+space-get", "获取知识库详情", "已知 workspace ID 或知识库 URL 时读取并验证空间详情。", "", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { + data, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) + if err != nil { + return err + } + object, err := requireWikiObject(data, "wiki/get_wikiSpace") + if err != nil { + return err + } + if firstWikiString(object, "workspaceId", "spaceId", "id") == "" { + return wikiResponseError("wiki/get_wikiSpace", "missing_workspace_id", "空间详情缺少 workspaceId") + } + return rt.Output(object) +}) + +var SpaceCreate = writeShortcut("+space-create", "创建知识库并读回验证", "创建新的知识库容器；必须取得 workspaceId 并通过详情读回后才报告成功。", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "name", Type: shortcut.FlagString, Required: true, Desc: "知识库名称，不超过 32 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "desc", Type: shortcut.FlagString, Desc: "知识库描述，不超过 500 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "icon", Type: shortcut.FlagString, Desc: "图标标识"}}, []contract.ParamDecl{{Name: "name", Property: "name"}, {Name: "desc", Property: "description"}, {Name: "icon", Property: "icon"}}, func(rt *shortcut.RuntimeContext) error { + params := map[string]any{"name": rt.Str("name")} + if rt.Changed("desc") { + params["description"] = rt.Str("desc") + } + if rt.Changed("icon") { + params["icon"] = rt.Str("icon") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "wiki/create_wikiSpace", "arguments": params}) + } + written, err := rt.CallMCPWriteDataStrict("wiki", "create_wikiSpace", params) + if err != nil { + return err + } + written, err = requireWikiWrite(written, "wiki/create_wikiSpace") + if err != nil { + return err + } + id := nestedWikiString(written, "workspaceId", "spaceId", "id") + if id == "" { + return wikiResponseError("wiki/create_wikiSpace", "missing_created_id", "创建响应没有 workspaceId；远端效果未知") + } + verified, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": id}) + if err != nil { + return err + } + verified, err = requireWikiObject(verified, "wiki/get_wikiSpace") + if err != nil { + return err + } + if firstWikiString(verified, "workspaceId", "spaceId", "id") != id { + return wikiResponseError("wiki/create_wikiSpace", "readback_id_mismatch", "创建后读回的 workspaceId 不一致") + } + return rt.Output(map[string]any{"success": true, "workspaceId": id, "space": verified}) +}) + +var DeleteSpace = writeShortcut("+delete-space", "删除知识库", "用户明确确认后将整个知识库移入回收站；删除前读取目标，删除响应必须有 success=true。", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { + preflight, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) + if err != nil { + return err + } + preflight, err = requireWikiObject(preflight, "wiki/get_wikiSpace") + if err != nil { + return err + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "wiki/delete_wikiSpace", "target": preflight}) + } + written, err := rt.CallMCPWriteDataStrict("wiki", "delete_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) + if err != nil { + return err + } + written, err = requireWikiWrite(written, "wiki/delete_wikiSpace") + if err != nil { + return err + } + return rt.Output(map[string]any{"success": true, "workspaceId": rt.Str("workspace"), "deleted": true}) +}) + +func memberFlags(withRole bool) []shortcut.Flag { + flags := []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "users", Type: shortcut.FlagStringSlice, Required: true, Desc: "用户 userId，最多 30 个", Aliases: []string{"user"}, AliasesVisible: true}} + if withRole { + flags = append(flags, shortcut.Flag{Name: "role", Type: shortcut.FlagString, Required: true, Desc: "角色", Enum: []string{"MANAGER", "EDITOR", "DOWNLOADER", "READER"}}) + } + return flags +} + +func memberWrite(command, tool, description, intent string, withRole bool) shortcut.Shortcut { + params := []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "users", Property: "userIds"}} + if withRole { + params = append(params, contract.ParamDecl{Name: "role", Property: "roleId"}) + } + return writeShortcut(command, description, intent, shortcut.RiskWrite, wikiWriteSafety(false), memberFlags(withRole), params, func(rt *shortcut.RuntimeContext) error { + users := rt.StrSlice("users") + if len(users) == 0 || len(users) > 30 { + return fmt.Errorf("--users 必须包含 1-30 个 userId") } - if rt.Changed("cursor") { - params["pageToken"] = rt.Str("cursor") + args := map[string]any{"workspaceId": rt.Str("workspace"), "userIds": users} + if withRole { + args["roleId"] = strings.ToUpper(rt.Str("role")) } - data, err := rt.CallMCPData("wiki", "list_wikiSpaces", params) + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "wiki/" + tool, "arguments": args}) + } + written, err := rt.CallMCPWriteDataStrict("wiki", tool, args) if err != nil { return err } - spaces := spaceListProject(data) - return rt.Output(map[string]any{"count": len(spaces), "spaces": spaces}) - }, -} - -// spaceListProject reshapes list_wikiSpaces into a clean space list -// ({workspaceId, name, description, createTime}) — output-projection fidelity -// for clean output. The list container and per-item field names are probed defensively -// across candidate keys, so an unrecognized shape yields an empty list. -func spaceListProject(data map[string]any) []map[string]any { - raw := wikiSpaceRawList(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue + written, err = requireWikiWrite(written, "wiki/"+tool) + if err != nil { + return err } - row := map[string]any{} - if v := wikiSpaceFirst(m, "workspaceId", "workspace_id", "spaceId", "space_id", "id"); v != nil { - row["workspaceId"] = v + listed, err := rt.CallMCPData("wiki", "list_member", map[string]any{"workspaceId": rt.Str("workspace"), "maxResults": 50}) + if err != nil { + return err } - if v := wikiSpaceFirst(m, "name", "title", "spaceName"); v != nil { - row["name"] = v + items, _, err := requireWikiCollection(listed, "wiki/list_member", "members") + if err != nil { + return err } - if v := wikiSpaceFirst(m, "description", "desc"); v != nil { - row["description"] = v - } - if v := wikiSpaceFirst(m, "createTime", "create_time", "gmtCreate", "createdAt"); v != nil { - row["createTime"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out -} - -// wikiSpaceRawList locates the space array across candidate container keys, -// tolerating a nested {result|data:{list|items|spaces}} wrapper. -func wikiSpaceRawList(data map[string]any) []any { - // list_wikiSpaces / search_wikiSpaces nest the space list under - // result.wikiSpaces (or a top-level wikiSpaces once unwrapped); "wikiSpaces" - // MUST be probed or +space-list / +space-search silently return empty. - for _, k := range []string{"result", "data", "list", "items", "wikiSpaces", "spaces", "workspaces"} { - if arr, ok := data[k].([]any); ok { - return arr - } - if inner, ok := data[k].(map[string]any); ok { - for _, ik := range []string{"list", "items", "wikiSpaces", "spaces", "workspaces", "result", "data"} { - if arr, ok := inner[ik].([]any); ok { - return arr - } + found := make(map[string]string) + for _, item := range items { + member := item.(map[string]any) + id := firstWikiString(member, "id", "userId") + if id != "" { + found[id] = strings.ToUpper(firstWikiString(member, "role", "roleId")) } } - } - return nil -} - -// wikiSpaceFirst returns the first present value among candidate keys. -func wikiSpaceFirst(m map[string]any, keys ...string) any { - for _, k := range keys { - if v, ok := m[k]; ok { - return v - } - } - return nil -} - -// SpaceSearch → search_wikiSpaces -var SpaceSearch = shortcut.Shortcut{ - Service: "wiki", - Command: "+space-search", - Product: "wiki", - Description: "搜索知识库", - Intent: "当你只记得知识库名称的部分关键词、想快速按名称定位某个知识库时使用；输入关键词返回匹配的知识库列表，比逐页 +space-list 更快找到目标 workspaceId。", - Risk: shortcut.RiskRead, - Safety: contract.SafetySpec{ - Effect: "read", Risk: "low", - Confirmation: "not_required", Idempotency: "idempotent", - }, - Contract: corecmd.ContractDecl{ - Identity: contract.ToolIdentitySpec{ - ProductID: "wiki", - Name: "shortcut_space_search", - CanonicalPath: "wiki.shortcut_space_search", - CLIPath: "wiki +space-search", - PrimaryCLIPath: "wiki +space-search", - }, - Description: "搜索知识库", - Interface: &contract.InterfaceSpec{ - Mode: "composite", - Availability: "available", - Reason: "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.", - }, - Selection: contract.SelectionSpec{ - AgentSummary: "搜索知识库", - UseWhen: []string{"当你只记得知识库名称的部分关键词、想快速按名称定位某个知识库时使用；输入关键词返回匹配的知识库列表，比逐页 +space-list 更快找到目标 workspaceId。"}, - AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws wiki +space-search --query \"产品文档\""}, - }, - }, - Flags: []shortcut.Flag{ - {Name: "query", Type: shortcut.FlagString, Desc: "搜索关键词", Required: true}, - {Name: "limit", Type: shortcut.FlagString, Desc: "返回数量 1-20 (默认 10)"}, - }, - Tips: []string{`dws wiki +space-search --query "产品文档"`}, - Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{"keyword": rt.Str("query")} - if rt.Changed("limit") { - params["pageSize"] = rt.Str("limit") - } - data, err := rt.CallMCPData("wiki", "search_wikiSpaces", params) - if err != nil { - return err - } - spaces := spaceListProject(data) - return rt.Output(map[string]any{"count": len(spaces), "spaces": spaces}) - }, -} - -// SpaceDelete → delete_wikiSpace -// ── member (知识库成员) ─────────────────────────────────────── - -// MemberAdd → add_member -// MemberUpdate → update_member -// MemberList → list_member -// MemberRemove → remove_member -// ── node (知识库节点，路由到 doc MCP server) ────────────────── - -// NodeList → list_nodes (doc) -var NodeList = shortcut.Shortcut{ - Service: "wiki", - Command: "+node-list", - Product: "doc", - Description: "列出知识库节点", - Intent: "当你要浏览某个知识库的目录结构、查看某文件夹下有哪些文档/子文件夹并拿到它们的 nodeId 时使用；输入 workspace（可选父节点 folder），分页返回该层级的节点列表，是逐层进入知识库定位文档的常用方式。", - Risk: shortcut.RiskRead, - Flags: []shortcut.Flag{ - {Name: "workspace", Type: shortcut.FlagString, Desc: "知识库 ID", Required: true}, - {Name: "folder", Type: shortcut.FlagString, Desc: "父节点 nodeId (不传则列出根目录)"}, - {Name: "limit", Type: shortcut.FlagInt, Desc: "每页数量 (默认 50，最大 50)"}, - {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}, - }, - Tips: []string{`dws wiki +node-list --workspace --folder `}, - Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{"workspaceId": rt.Str("workspace")} - if rt.Changed("folder") { - params["folderId"] = rt.Str("folder") - } - if rt.Changed("limit") { - params["pageSize"] = rt.Int("limit") - } - if rt.Changed("cursor") { - params["pageToken"] = rt.Str("cursor") - } - data, err := rt.CallMCPData("wiki", "list_nodes", params) - if err != nil { - return err - } - nodes := nodeListProject(data) - return rt.Output(map[string]any{"count": len(nodes), "nodes": nodes}) - }, -} - -// nodeListProject reshapes list_nodes into a clean node list (name/nodeId/type) -// — clean output projection. Container and field keys are probed -// defensively across candidate aliases; an unrecognized shape yields an empty list. -func nodeListProject(data map[string]any) []map[string]any { - raw := nodeListRawList(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v := nodeListFirst(m, "name", "title", "nodeName"); v != nil { - row["name"] = v - } - if v := nodeListFirst(m, "nodeId", "node_id", "id", "uuid", "dentryUuid"); v != nil { - row["nodeId"] = v - } - if v := nodeListFirst(m, "type", "nodeType", "docType", "fileType"); v != nil { - row["type"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out -} - -// nodeListRawList locates the node array across candidate container keys, -// tolerating a nested {result|data:{list|items|nodes}} wrapper. -func nodeListRawList(data map[string]any) []any { - for _, k := range []string{"result", "data", "list", "items", "nodes"} { - if arr, ok := data[k].([]any); ok { - return arr - } - if inner, ok := data[k].(map[string]any); ok { - for _, ik := range []string{"list", "items", "nodes", "result", "data"} { - if arr, ok := inner[ik].([]any); ok { - return arr - } + for _, user := range users { + role, present := found[user] + if tool == "remove_member" && present { + return wikiResponseError("wiki/"+tool, "readback_member_still_present", "成员移除后仍出现在成员列表中") + } + if tool != "remove_member" && !present { + return wikiResponseError("wiki/"+tool, "readback_member_missing", "成员写入后未出现在成员列表中") + } + if withRole && role != strings.ToUpper(rt.Str("role")) { + return wikiResponseError("wiki/"+tool, "readback_role_mismatch", "成员写入后读回角色与请求不一致") } } + return rt.Output(map[string]any{"success": true, "workspaceId": rt.Str("workspace"), "userCount": len(users), "operation": tool, "verifiedBy": "member_list_readback"}) + }) +} + +var MemberAdd = memberWrite("+member-add", "add_member", "添加知识库成员", "向知识库授予一个或多个用户容器级角色，并用成员列表读回验证响应契约。", true) +var MemberUpdate = memberWrite("+member-update", "update_member", "更新知识库成员角色", "调整已有成员的知识库容器级角色，并用成员列表读回验证响应契约。", true) +var MemberRemove = memberWrite("+member-remove", "remove_member", "移除知识库成员", "移除一个或多个用户的知识库容器级访问，并用成员列表读回验证响应契约。", false) + +var MemberList = readShortcut("+member-list", "严格列出知识库成员", "列出知识库成员及角色；后端不提供可续游标且单次真实上限为 50，不伪造 page-all。", "members", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "30", Desc: "返回上限 1-50"}, {Name: "filter-role", Type: shortcut.FlagStringSlice, Desc: "角色过滤"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "filter-role", Property: "filterRoleIds"}}, func(rt *shortcut.RuntimeContext) error { + if rt.Int("limit") < 1 || rt.Int("limit") > 50 { + return fmt.Errorf("--limit 必须在 1-50 之间；服务端不支持超过 50 或游标续页") } - return nil -} - -// nodeListFirst returns the first present value among candidate keys. -func nodeListFirst(m map[string]any, keys ...string) any { - for _, k := range keys { - if v, ok := m[k]; ok { - return v - } + params := map[string]any{"workspaceId": rt.Str("workspace"), "maxResults": rt.Int("limit")} + if rt.Changed("filter-role") { + params["filterRoleIds"] = rt.StrSlice("filter-role") } - return nil -} + data, err := rt.CallMCPData("wiki", "list_member", params) + if err != nil { + return err + } + items, page, err := requireWikiCollection(data, "wiki/list_member", "members") + if err != nil { + return err + } + members := projectWikiRows(items, map[string][]string{"id": {"id", "userId"}, "name": {"name", "nick"}, "role": {"role", "roleId"}, "type": {"type"}, "outer": {"outer"}}) + out := map[string]any{"count": len(members), "members": members} + addWikiPagination(out, page) + return rt.Output(out) +}) -// NodeCreate → create_file (doc) -// NodeCopy → copy_document (doc) -var NodeCopy = shortcut.Shortcut{ - Service: "wiki", - Command: "+node-copy", - Product: "doc", - Description: "复制知识库节点", - Intent: "当你想基于已有文档/文件夹快速生成一份副本（如用模板起草新文档、留档备份）时使用；指定源 node 和目标 folder，会实际在知识库中复制出一个新节点，原节点保持不变。", - Risk: shortcut.RiskWrite, - Flags: []shortcut.Flag{ - {Name: "workspace", Type: shortcut.FlagString, Desc: "知识库 ID", Required: true}, - {Name: "node", Type: shortcut.FlagString, Desc: "源节点 ID", Required: true}, - {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 nodeId (不传则复制到根目录)"}, - }, - Tips: []string{`dws wiki +node-copy --workspace --node --folder `}, - Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{ - "nodeId": rt.Str("node"), - "workspaceId": rt.Str("workspace"), - } - if rt.Changed("folder") { - params["targetFolderId"] = rt.Str("folder") - } - return rt.CallMCP("copy_document", params) - }, -} - -// NodeMove → move_document (doc) -var NodeMove = shortcut.Shortcut{ - Service: "wiki", - Command: "+node-move", - Product: "doc", - Description: "移动知识库节点", - Intent: "当你要重新整理知识库目录、把某个文档或文件夹从当前位置挪到另一个文件夹（或根目录）下时使用；指定源 node 和目标 folder，会实际改变该节点在知识库中的所属位置。", - Risk: shortcut.RiskWrite, - Flags: []shortcut.Flag{ - {Name: "workspace", Type: shortcut.FlagString, Desc: "知识库 ID", Required: true}, - {Name: "node", Type: shortcut.FlagString, Desc: "源节点 ID", Required: true}, - {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 nodeId (不传则移动到根目录)"}, - }, - Tips: []string{`dws wiki +node-move --workspace --node --folder `}, - Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{ - "nodeId": rt.Str("node"), - "workspaceId": rt.Str("workspace"), - } - if rt.Changed("folder") { - params["targetFolderId"] = rt.Str("folder") - } - return rt.CallMCP("move_document", params) - }, -} - -// NodeDelete → delete_document (doc) -// NodeSearch → search_documents (doc) func init() { - shortcut.Register( - SpaceList, - SpaceSearch, - NodeList, - NodeCopy, - NodeMove, - ) + DeleteSpace.Aliases = []string{"+space-delete"} + SpaceCreate.Validate = func(rt *shortcut.RuntimeContext) error { + if len([]rune(rt.Str("name"))) > 32 { + return fmt.Errorf("--name 不能超过 32 个字符") + } + if len([]rune(rt.Str("desc"))) > 500 { + return fmt.Errorf("--desc 不能超过 500 个字符") + } + return nil + } + SpaceCreate.Constraints = []shortcut.Constraint{{Kind: shortcut.ConstraintCustom, Flags: []string{"name", "desc"}, Description: "--name 不超过 32 个字符；--desc 不超过 500 个字符"}} + enableWikiAutoPage(&SpaceList) + SpaceList.Contract.Pagination = wikiCursorPagination() + shortcut.Register(SpaceList, SpaceSearch, SpaceGet, SpaceCreate, DeleteSpace, MemberAdd, MemberUpdate, MemberList, MemberRemove) } diff --git a/scripts/dev/wiki-shortcut-e2e.py b/scripts/dev/wiki-shortcut-e2e.py new file mode 100755 index 00000000..84ecd391 --- /dev/null +++ b/scripts/dev/wiki-shortcut-e2e.py @@ -0,0 +1,179 @@ +#!/usr/bin/env python3 +"""Run destructive, real-data Wiki Shortcut verification on a disposable space. + +Requires an authenticated `dws` session. Set DWS_WIKI_E2E_MEMBER_ID to a real +internal user ID that may be granted temporary access to the empty fixture. +The script prints capability labels only; business IDs, names, URLs, and raw +responses remain in memory. The disposable Wiki space is deleted in `finally`. +""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +import time +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +DWS = ROOT / "dws" +MEMBER_ID = os.environ.get("DWS_WIKI_E2E_MEMBER_ID", "").strip() + + +class E2EFailure(RuntimeError): + pass + + +def invoke(args: list[str]) -> dict: + process = subprocess.run( + [str(DWS), "wiki", *args, "--format", "json"], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + try: + envelope = json.loads(process.stdout) + except json.JSONDecodeError as exc: + raise E2EFailure(f"non-JSON response (exit {process.returncode})") from exc + if process.returncode != 0 or envelope.get("ok") is not True: + error = envelope.get("error") or {} + reason = error.get("reason") or error.get("category") or "command_failed" + raise E2EFailure(f"{reason} (exit {process.returncode})") + data = envelope.get("data") + if not isinstance(data, dict): + raise E2EFailure("success envelope lacks object data") + return data + + +def check(label: str, condition: bool) -> None: + if not condition: + raise E2EFailure(f"{label}: business assertion failed") + print(f"PASS {label}") + + +def main() -> int: + if not DWS.exists(): + raise E2EFailure("build ./dws first with make build") + if not MEMBER_ID: + raise E2EFailure("set DWS_WIKI_E2E_MEMBER_ID to a temporary internal test member") + + stamp = time.strftime("%m%d%H%M%S") + space_name = f"DWS Wiki E2E {stamp}" # <= 32 characters + workspace = "" + disposable_nodes: list[str] = [] + member_added = False + try: + created = invoke(["+space-create", "--name", space_name, "--desc", "Disposable E2E fixture"]) + workspace = str(created.get("workspaceId") or "") + check("space-create-readback", bool(workspace) and created.get("space", {}).get("workspaceId") == workspace) + + page = invoke(["+space-list", "--limit", "1"]) + check("space-list-cursor", page.get("count") == 1 and isinstance(page.get("hasMore"), bool)) + all_spaces = invoke(["+space-list", "--limit", "1", "--page-all", "--max-items", "2"]) + check("space-list-auto-page", all_spaces.get("count") == 2 and len(all_spaces.get("spaces", [])) == 2) + search_ok = False + for _ in range(8): + searched = invoke(["+space-search", "--query", space_name]) + if any(row.get("workspaceId") == workspace for row in searched.get("spaces", [])): + search_ok = True + break + time.sleep(2) + check("space-search", search_ok) + detail = invoke(["+space-get", "--workspace", workspace]) + check("space-get", detail.get("workspaceId") == workspace) + resolved = invoke(["+resolve-space", "--name", space_name]) + check("resolve-space", resolved.get("resolved") is True and resolved.get("spaceId") == workspace) + + empty_nodes = invoke(["+node-list", "--workspace", workspace]) + check("node-list-explicit-empty", empty_nodes.get("count") == 0 and empty_nodes.get("nodes") == []) + + folder = invoke(["+node-create", "--workspace", workspace, "--name", "E2E Folder", "--type", "folder"]) + folder_id = str(folder.get("nodeId") or "") + disposable_nodes.append(folder_id) + check("node-create-folder-readback", bool(folder_id) and folder.get("node", {}).get("nodeId") == folder_id) + document = invoke(["+node-create", "--workspace", workspace, "--folder", folder_id, "--name", "E2E Document"]) + node_id = str(document.get("nodeId") or "") + disposable_nodes.append(node_id) + check("node-create-document-readback", bool(node_id) and document.get("node", {}).get("nodeId") == node_id) + + listed = invoke(["+node-list", "--workspace", workspace, "--limit", "1"]) + check("node-list-cursor", listed.get("count") == 1 and listed.get("hasMore") is True and bool(listed.get("nextCursor"))) + all_nodes = invoke(["+node-list", "--workspace", workspace, "--limit", "1", "--page-all"]) + check( + "node-list-auto-page", + all_nodes.get("count", 0) >= 1 + and (all_nodes.get("autoPageComplete") is True or all_nodes.get("hasMore") is False), + ) + info = invoke(["+node-get", "--node", node_id]) + check("node-get", info.get("nodeId") == node_id) + + # Search indexing can lag after a create; retry without accepting a + # malformed/missing collection as an empty success. + search_ok = False + for _ in range(6): + found = invoke(["+node-search", "--workspace", workspace, "--query", "E2E Document"]) + if any(row.get("nodeId") == node_id for row in found.get("nodes", [])): + search_ok = True + break + time.sleep(2) + check("node-search", search_ok) + + copied = invoke(["+node-copy", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + copy_id = str(copied.get("nodeId") or "") + disposable_nodes.append(copy_id) + check("node-copy-readback", bool(copy_id) and bool(copied.get("copy"))) + + moved = invoke(["+move", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + check("move-readback", moved.get("node", {}).get("workspaceId") == workspace and moved.get("node", {}).get("folderId") == folder_id) + moved_out = invoke(["+move-to-drive", "--node", node_id, "--yes"]) + check("move-to-drive-readback", moved_out.get("node", {}).get("workspaceId") != workspace) + moved_back = invoke(["+node-move", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + check("node-move-alias-readback", moved_back.get("node", {}).get("workspaceId") == workspace) + + named = invoke(["+wiki-new-doc", "--space", space_name, "--title", "E2E Name Resolved"]) + named_id = str(named.get("nodeId") or "") + disposable_nodes.append(named_id) + check("wiki-new-doc-readback", bool(named_id) and named.get("document", {}).get("nodeId") == named_id) + + members = invoke(["+member-list", "--workspace", workspace, "--limit", "50"]) + check("member-list", members.get("count", 0) >= 1 and isinstance(members.get("members"), list)) + added = invoke(["+member-add", "--workspace", workspace, "--users", MEMBER_ID, "--role", "READER"]) + member_added = True + check("member-add-readback", added.get("success") is True and added.get("verifiedBy") == "member_list_readback") + updated = invoke(["+member-update", "--workspace", workspace, "--users", MEMBER_ID, "--role", "EDITOR"]) + check("member-update-readback", updated.get("success") is True and updated.get("verifiedBy") == "member_list_readback") + removed = invoke(["+member-remove", "--workspace", workspace, "--users", MEMBER_ID]) + member_added = False + check("member-remove-readback", removed.get("success") is True and removed.get("verifiedBy") == "member_list_readback") + + feeds = invoke(["+feed-list", "--workspace", workspace, "--limit", "10"]) + check("feed-list", isinstance(feeds.get("feeds"), list)) + + # Exercise high-risk delete before final whole-space cleanup. + delete_target = disposable_nodes.pop() + deleted = invoke(["+node-delete", "--workspace", workspace, "--node", delete_target, "--yes"]) + check("node-delete-terminal", deleted.get("success") is True and deleted.get("deleted") is True) + return 0 + finally: + if workspace: + if member_added: + try: + invoke(["+member-remove", "--workspace", workspace, "--users", MEMBER_ID]) + except Exception: + pass + try: + deleted = invoke(["+space-delete", "--workspace", workspace, "--yes"]) + check("space-delete-alias-cleanup", deleted.get("success") is True and deleted.get("deleted") is True) + except Exception as exc: + print(f"CLEANUP FAILED: {exc}", file=sys.stderr) + + +if __name__ == "__main__": + try: + raise SystemExit(main()) + except E2EFailure as exc: + print(f"FAIL {exc}", file=sys.stderr) + raise SystemExit(1) diff --git a/scripts/gen_shortcut_public_catalog.py b/scripts/gen_shortcut_public_catalog.py index 4528688b..2bdd2820 100644 --- a/scripts/gen_shortcut_public_catalog.py +++ b/scripts/gen_shortcut_public_catalog.py @@ -24,6 +24,7 @@ SEMANTIC_PATHS = [ ROOT / "internal" / "shortcut" / "semantic_catalog_aitable.json", ROOT / "internal" / "shortcut" / "semantic_catalog_minutes.json", ROOT / "internal" / "shortcut" / "semantic_catalog_drive.json", + ROOT / "internal" / "shortcut" / "semantic_catalog_wiki.json", ] diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index 3d916175..210215b5 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -58,7 +58,7 @@ cli_version: ">=1.0.15" | `report` | 2 | `dingtalk-misc` | | `sheet` | 2 | `dingtalk-misc` | | `todo` | 11 | `dingtalk-todo` | -| `wiki` | 1 | `dingtalk-wiki` | +| `wiki` | 20 | `dingtalk-wiki` | ## 多组织 / 多账号 diff --git a/skills/multi/dingtalk-wiki/SKILL.md b/skills/multi/dingtalk-wiki/SKILL.md index a3dc5da7..320f4f76 100644 --- a/skills/multi/dingtalk-wiki/SKILL.md +++ b/skills/multi/dingtalk-wiki/SKILL.md @@ -24,7 +24,8 @@ metadata: | Shortcut | 风险 | 适用场景 | |---|---|---| -| `dws wiki +space-search` | read | 搜索知识库 | +| `dws wiki +resolve-space` | read | 按名称搜索知识空间并解析出唯一 spaceId（只读） | +| `dws wiki +wiki-new-doc` | write | 在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId） | ## 意图表 From 3488e1112977408f9165576dbf15829012671033 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 12:01:50 +0800 Subject: [PATCH 124/250] docs(wiki): keep review product-neutral --- .changes/wiki-shortcut-alignment.md | 2 +- docs/shortcut-public-catalog.json | 10 +++++----- docs/wiki-shortcut-business-review.html | 16 ++++++++-------- internal/shortcut/semantic_catalog_wiki.json | 8 ++++---- internal/shortcut/wiki/nodes.go | 6 +++--- 5 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.changes/wiki-shortcut-alignment.md b/.changes/wiki-shortcut-alignment.md index 356fb40d..86551e85 100644 --- a/.changes/wiki-shortcut-alignment.md +++ b/.changes/wiki-shortcut-alignment.md @@ -4,5 +4,5 @@ category: Added - **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and activity shortcuts with strict collection validation, cursor handling, - write read-backs, Lark-compatible task routing, and documented backend + write read-backs, task-oriented routing, and documented backend boundaries. diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index eef23b40..b74e3973 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-08-14T10:41:08.959563", + "generated_at": "2026-08-14T11:59:55.882207", "count": 418, "results": [ { @@ -3675,7 +3675,7 @@ "risk": "read", "status": "reviewed_available", "disposition": "semantic_adapter", - "semantic_delta": "补充 Lark Shortcut 缺失的知识库协作动态查询，严格验证 feeds 并保留游标。", + "semantic_delta": "补充知识库协作动态查询，严格验证 feeds 并保留游标。", "availability": "available" }, { @@ -3715,7 +3715,7 @@ "risk": "write", "status": "reviewed_available", "disposition": "primary_smart", - "semantic_delta": "补充 Lark Shortcut 缺失的成员角色更新，并执行终态与列表读回校验。", + "semantic_delta": "补充成员角色更新，并执行终态与列表读回校验。", "availability": "available" }, { @@ -3795,7 +3795,7 @@ "risk": "read", "status": "reviewed_available", "disposition": "semantic_adapter", - "semantic_delta": "补充 Lark Wiki Shortcut 缺失的库内关键词和扩展名搜索，并拒绝假空结果。", + "semantic_delta": "补充库内关键词和扩展名搜索，并拒绝假空结果。", "availability": "available" }, { @@ -3825,7 +3825,7 @@ "risk": "read", "status": "reviewed_available", "disposition": "schema_leaf", - "semantic_delta": "提供 Lark Shortcut 未单列的知识库详情入口，并要求 workspaceId 业务证据。", + "semantic_delta": "补充知识库详情入口，并要求 workspaceId 业务证据。", "availability": "available" }, { diff --git a/docs/wiki-shortcut-business-review.html b/docs/wiki-shortcut-business-review.html index 4d7c871e..59a36df8 100644 --- a/docs/wiki-shortcut-business-review.html +++ b/docs/wiki-shortcut-business-review.html @@ -18,26 +18,26 @@

DWS Wiki Shortcut 全景评审

-

以 lark-cli 1.0.78 的 13 个 Wiki Shortcut 为任务基线，重新审视 DWS 的空间、成员、节点与动态能力。本次不是按命令名凑数：每个入口都要求真实业务证据，缺失数组、畸形响应、空确认或读回不一致一律失败。

+

以 13 项成熟 Wiki 用户任务为基线，重新审视 DWS 的空间、成员、节点与动态能力。本次不是按命令名凑数：每个入口都要求真实业务证据，缺失数组、畸形响应、空确认或读回不一致一律失败。

评审日期 2026-08-14独立 worktree / 独立分支真实组织数据 E2E报告已去标识化
20公开 Wiki Shortcuts
-
13/13Lark 用户任务有对应路径
+
13/13基线用户任务有对应路径
7DWS 额外场景
20/20真实数据能力已触达

结论先行

-
DWS 已形成比“API 快捷别名”更完整的 Wiki 任务层。 Lark 的 13 个用户任务均有对应入口；其中 DWS 额外提供空间搜索/详情/唯一解析、成员角色更新、库内节点搜索、协作动态和按空间名新建文档。创建、复制、移动等关键写能力从“请求发出”升级为“终态 + ID + 读回”成功标准。
-
不能假装完全同构。 DingTalk 成员接口不提供游标，单次真实上限是 50，因此无法诚实实现 Lark 的成员 --page-all；成员身份只接受同组织可用的 userId，不能对齐 Lark 的 email/open_id 等多种 member-id-type；节点创建也没有等价的 origin/shortcut 模式。这些差异保留为明确边界，而不是用本地循环或空结果伪装。
+
DWS 已形成比“API 快捷别名”更完整的 Wiki 任务层。 基线中的 13 个用户任务均有对应入口；DWS 还提供空间搜索/详情/唯一解析、成员角色更新、库内节点搜索、协作动态和按空间名新建文档。创建、复制、移动等关键写能力从“请求发出”升级为“终态 + ID + 读回”成功标准。
+
能力边界必须诚实表达。 DingTalk 成员接口不提供游标，单次真实上限是 50，因此不能实现成员 --page-all；成员身份只接受同组织可用的 userId，无法提供 email/open_id 等多种身份模式；节点创建也没有等价的 origin/shortcut 模式。这些差异保留为明确边界，而不是用本地循环或空结果伪装。
-

Lark 13 项逐条映射

-
+

13 项基线任务逐条映射

+
Lark ShortcutDWS 主入口结论DWS 视角与边界
@@ -45,10 +45,10 @@ - + - +
基线任务DWS 主入口结论DWS 视角与边界
+space-listwiki +space-list完整对齐严格空集合、游标续传、自动翻页、停滞检测；支持组织/我的知识库。
+space-createwiki +space-create超过公开真实 32 字符名称上限；创建后按 workspaceId 读回。
+delete-spacewiki +delete-space超过预读目标、高风险确认、只接受 success=true；兼容 +space-delete。
+member-listwiki +member-list任务对齐严格成员数组、角色过滤、真实上限 50；后端无游标，不能提供诚实的 page-all。
+member-removewiki +member-remove任务对齐批量 userId，移除后读回确认成员已消失；身份类型边界同上。
+node-listwiki +node-list完整对齐正确跨域路由 doc/list_nodes，严格空目录、分页与自动翻页。
+node-getwiki +node-get任务对齐支持 DingTalk 节点 ID/在线文档 URL并返回文档域元数据；不接受 Lark 特有 token/type 组合。
+node-getwiki +node-get任务对齐支持 DingTalk 节点 ID/在线文档 URL 并返回文档域元数据；不接受跨平台专用的 token/type 组合。
+node-createwiki +node-create任务对齐支持 adoc/axls/able/appt/adraw/amind/folder 并读回；无 origin/shortcut 等价接口。
+node-copywiki +node-copy超过确认后要求新 nodeId 并读取副本；底层面向在线节点，不把 .dlink 当独立副本。
+movewiki +move任务对齐同一入口支持 Wiki 内移动和“我的文档”在线节点入 Wiki，读回 workspace/folder；无 Lark apply 权限迁移开关。
+movewiki +move任务对齐同一入口支持 Wiki 内移动和“我的文档”在线节点入 Wiki，读回 workspace/folder；底层接口没有 apply 权限迁移开关。
+move-to-drivewiki +move-to-drive超过DWS 当前接口同步完成并读回 workspace 变化，无需暴露异步 task 轮询。
+node-deletewiki +node-delete超过预读并核对 workspace，高风险确认，要求删除终态。
diff --git a/internal/shortcut/semantic_catalog_wiki.json b/internal/shortcut/semantic_catalog_wiki.json index 428438ee..17a3e4a1 100644 --- a/internal/shortcut/semantic_catalog_wiki.json +++ b/internal/shortcut/semantic_catalog_wiki.json @@ -6,25 +6,25 @@ "+space-list": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空知识库列表与缺失、畸形或内部错误响应，并保留真实分页证据。","risk":"read","public":true,"reviewed":true}, "+space-search": {"disposition":"semantic_adapter","semantic_delta":"按关键词搜索知识库并拒绝把缺失业务数组误报为零命中。","risk":"read","public":true,"reviewed":true}, "+resolve-space": {"disposition":"primary_smart","semantic_delta":"把关键词搜索收敛为唯一 workspaceId；零命中与多命中显式分流，绝不猜测。","risk":"read","public":true,"reviewed":true}, - "+space-get": {"disposition":"schema_leaf","semantic_delta":"提供 Lark Shortcut 未单列的知识库详情入口，并要求 workspaceId 业务证据。","risk":"read","public":true,"reviewed":true}, + "+space-get": {"disposition":"schema_leaf","semantic_delta":"补充知识库详情入口，并要求 workspaceId 业务证据。","risk":"read","public":true,"reviewed":true}, "+space-create": {"disposition":"primary_smart","semantic_delta":"创建后要求 workspaceId 并通过空间详情读回验证真实落库。","risk":"write","public":true,"reviewed":true}, "+delete-space": {"disposition":"semantic_adapter","semantic_delta":"删除前读取影响目标，经高风险确认后只接受 success=true 终态。","risk":"high-risk-write","public":true,"reviewed":true}, "+member-add": {"disposition":"primary_smart","semantic_delta":"批量授予 Wiki 容器角色，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, - "+member-update": {"disposition":"primary_smart","semantic_delta":"补充 Lark Shortcut 缺失的成员角色更新，并执行终态与列表读回校验。","risk":"write","public":true,"reviewed":true}, + "+member-update": {"disposition":"primary_smart","semantic_delta":"补充成员角色更新，并执行终态与列表读回校验。","risk":"write","public":true,"reviewed":true}, "+member-list": {"disposition":"semantic_adapter","semantic_delta":"严格验证成员数组并公开真实单次上限 50；后端无游标时不伪造 page-all。","risk":"read","public":true,"reviewed":true}, "+member-remove": {"disposition":"primary_smart","semantic_delta":"批量移除容器访问，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, "+node-list": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空目录与假空成功，稳定投影节点并保留 nextCursor/hasMore。","risk":"read","public":true,"reviewed":true}, "+node-get": {"disposition":"schema_leaf","semantic_delta":"统一节点 ID 或在线文档 URL 的元数据读取，补充文档域属性视角。","risk":"read","public":true,"reviewed":true}, - "+node-search": {"disposition":"semantic_adapter","semantic_delta":"补充 Lark Wiki Shortcut 缺失的库内关键词和扩展名搜索，并拒绝假空结果。","risk":"read","public":true,"reviewed":true}, + "+node-search": {"disposition":"semantic_adapter","semantic_delta":"补充库内关键词和扩展名搜索，并拒绝假空结果。","risk":"read","public":true,"reviewed":true}, "+node-create": {"disposition":"primary_smart","semantic_delta":"支持七种 Wiki 节点类型，创建后要求 nodeId 并读取元数据验证。","risk":"write","public":true,"reviewed":true}, "+node-copy": {"disposition":"primary_smart","semantic_delta":"高风险确认后复制，必须取得新 nodeId 并读回副本，避免空响应被当作成功。","risk":"high-risk-write","public":true,"reviewed":true}, "+move": {"disposition":"primary_smart","semantic_delta":"同一入口覆盖 Wiki 内移动和我的文档在线节点入 Wiki，并校验目标 workspace/folder。","risk":"write","public":true,"reviewed":true}, "+move-to-drive": {"disposition":"primary_smart","semantic_delta":"同步移动 Wiki 节点到我的文档并读回验证 workspace 变化，免去异步任务轮询。","risk":"write","public":true,"reviewed":true}, "+node-delete": {"disposition":"semantic_adapter","semantic_delta":"删除前读取并核对 workspace，经高风险确认后要求 success=true 终态证据。","risk":"high-risk-write","public":true,"reviewed":true}, - "+feed-list": {"disposition":"semantic_adapter","semantic_delta":"补充 Lark Shortcut 缺失的知识库协作动态查询，严格验证 feeds 并保留游标。","risk":"read","public":true,"reviewed":true}, + "+feed-list": {"disposition":"semantic_adapter","semantic_delta":"补充知识库协作动态查询，严格验证 feeds 并保留游标。","risk":"read","public":true,"reviewed":true}, "+wiki-new-doc": {"disposition":"primary_smart","semantic_delta":"按空间名精确唯一解析、创建在线文档并读回验证；零命中和歧义均显式失败。","risk":"write","public":true,"reviewed":true} } } diff --git a/internal/shortcut/wiki/nodes.go b/internal/shortcut/wiki/nodes.go index 0655992c..c78cc6b8 100644 --- a/internal/shortcut/wiki/nodes.go +++ b/internal/shortcut/wiki/nodes.go @@ -37,7 +37,7 @@ func nodeAliases() map[string][]string { return map[string][]string{"nodeId": {"nodeId", "id", "dentryUuid", "fileId"}, "name": {"name", "title", "nodeName", "fileName"}, "type": {"type", "nodeType", "docType", "fileType"}, "contentType": {"contentType"}, "folderId": {"folderId", "parentId"}, "workspaceId": {"workspaceId", "spaceId"}, "url": {"docUrl", "url", "webUrl"}} } -var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知节点 ID 或在线文档 URL 时读取元数据；比 Lark Wiki 仅返回节点元数据的视角额外统一文档/文件属性。", "", []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID 或 URL"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { +var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知节点 ID 或在线文档 URL 时读取元数据，并在节点信息之外统一返回文档/文件属性。", "", []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID 或 URL"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { data, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) if err != nil { return err @@ -191,9 +191,9 @@ func executeMove(rt *shortcut.RuntimeContext, toDrive bool) error { return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "node": verified}) } -var Move = writeShortcut("+move", "移动节点到知识库并读回验证", "将 Wiki 节点或我的文档在线节点移动到目标知识库/文件夹；同时覆盖 Lark 的 Wiki 内移动与 Drive 文档入 Wiki 场景。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, false) }) +var Move = writeShortcut("+move", "移动节点到知识库并读回验证", "将 Wiki 节点或我的文档在线节点移动到目标知识库/文件夹；同一入口覆盖库内移动与在线文档入库场景。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, false) }) -var MoveToDrive = writeShortcut("+move-to-drive", "移动 Wiki 节点到我的文档", "将 Wiki 在线节点同步移动到我的文档或指定文件夹，并以元数据读回替代 Lark 异步任务轮询。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "Wiki 节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "我的文档目标文件夹 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, true) }) +var MoveToDrive = writeShortcut("+move-to-drive", "移动 Wiki 节点到我的文档", "将 Wiki 在线节点同步移动到我的文档或指定文件夹，并以元数据读回证明任务完成。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "Wiki 节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "我的文档目标文件夹 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, true) }) var NodeDelete = writeShortcut("+node-delete", "删除知识库节点", "明确确认后将节点移入回收站；先读取目标，且删除响应必须提供 success=true 终态证据。", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID，用于确认影响范围"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { preflight, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) From 29b73a7d5e187a49f156f84faffc6c9ad577d095 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 14:33:00 +0800 Subject: [PATCH 125/250] fix(wiki): close shortcut review gaps --- .changes/wiki-shortcut-alignment.md | 3 +- docs/shortcut-public-catalog.json | 14 +- docs/wiki-shortcut-business-review.html | 21 +- internal/app/schema_shortcut_contract_test.go | 14 + internal/shortcut/semantic_catalog_wiki.json | 6 +- .../smart/mail_space_todo_projection_test.go | 5 + .../smart/wiki_workflow_coverage_test.go | 187 +++++ internal/shortcut/wiki/common.go | 30 +- internal/shortcut/wiki/wiki.go | 64 +- .../shortcut/wiki/workflow_coverage_test.go | 638 ++++++++++++++++++ scripts/dev/wiki-shortcut-e2e.py | 19 +- 11 files changed, 937 insertions(+), 64 deletions(-) create mode 100644 internal/shortcut/smart/wiki_workflow_coverage_test.go create mode 100644 internal/shortcut/wiki/workflow_coverage_test.go diff --git a/.changes/wiki-shortcut-alignment.md b/.changes/wiki-shortcut-alignment.md index 86551e85..44a9e6db 100644 --- a/.changes/wiki-shortcut-alignment.md +++ b/.changes/wiki-shortcut-alignment.md @@ -4,5 +4,6 @@ category: Added - **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and activity shortcuts with strict collection validation, cursor handling, - write read-backs, task-oriented routing, and documented backend + write-terminal evidence, safe read-backs where the backend supports them, + task-oriented routing, and documented backend boundaries. diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index b74e3973..7d447fc7 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-08-14T11:59:55.882207", + "generated_at": "2026-08-14T13:50:36.324505", "count": 418, "results": [ { @@ -3684,8 +3684,8 @@ "command": "+member-add", "risk": "write", "status": "reviewed_available", - "disposition": "primary_smart", - "semantic_delta": "批量授予 Wiki 容器角色，严格校验写终态并读取成员列表验证响应链。", + "disposition": "semantic_adapter", + "semantic_delta": "支持 1-30 个 userId 与四类角色；严格要求写接口终态，并明确后端无法提供精确成员读回。", "availability": "available" }, { @@ -3704,8 +3704,8 @@ "command": "+member-remove", "risk": "write", "status": "reviewed_available", - "disposition": "primary_smart", - "semantic_delta": "批量移除容器访问，严格校验写终态并读取成员列表验证响应链。", + "disposition": "semantic_adapter", + "semantic_delta": "支持批量 userId 移除；严格要求写接口终态，并明确后端无法提供精确成员读回。", "availability": "available" }, { @@ -3714,8 +3714,8 @@ "command": "+member-update", "risk": "write", "status": "reviewed_available", - "disposition": "primary_smart", - "semantic_delta": "补充成员角色更新，并执行终态与列表读回校验。", + "disposition": "semantic_adapter", + "semantic_delta": "补充成员角色更新；严格要求写接口终态，并明确后端无法提供精确成员读回。", "availability": "available" }, { diff --git a/docs/wiki-shortcut-business-review.html b/docs/wiki-shortcut-business-review.html index 59a36df8..ce3437cc 100644 --- a/docs/wiki-shortcut-business-review.html +++ b/docs/wiki-shortcut-business-review.html @@ -19,7 +19,7 @@

DWS Wiki Shortcut 全景评审

以 13 项成熟 Wiki 用户任务为基线，重新审视 DWS 的空间、成员、节点与动态能力。本次不是按命令名凑数：每个入口都要求真实业务证据，缺失数组、畸形响应、空确认或读回不一致一律失败。

-
评审日期 2026-08-14独立 worktree / 独立分支真实组织数据 E2E报告已去标识化
+
评审日期 2026-08-14独立 worktree / 独立分支真实组织数据 E2E 28/28报告已去标识化
@@ -41,9 +41,9 @@ +space-listwiki +space-list完整对齐严格空集合、游标续传、自动翻页、停滞检测；支持组织/我的知识库。 +space-createwiki +space-create超过公开真实 32 字符名称上限；创建后按 workspaceId 读回。 +delete-spacewiki +delete-space超过预读目标、高风险确认、只接受 success=true；兼容 +space-delete。 - +member-addwiki +member-add任务对齐支持 1–30 个 userId 与四种角色，读回名单和角色；不支持 email/open_id 等身份类型。 + +member-addwiki +member-add任务对齐支持 1–30 个 userId 与四种角色；以写接口终态作为成功证据，不把最多 50 条的名单误作精确读回。 +member-listwiki +member-list任务对齐严格成员数组、角色过滤、真实上限 50；后端无游标，不能提供诚实的 page-all。 - +member-removewiki +member-remove任务对齐批量 userId，移除后读回确认成员已消失；身份类型边界同上。 + +member-removewiki +member-remove任务对齐支持批量 userId；只接受写接口明确终态，并公开无法进行精确成员读回的边界。 +node-listwiki +node-list完整对齐正确跨域路由 doc/list_nodes，严格空目录、分页与自动翻页。 +node-getwiki +node-get任务对齐支持 DingTalk 节点 ID/在线文档 URL 并返回文档域元数据；不接受跨平台专用的 token/type 组合。 +node-createwiki +node-create任务对齐支持 adoc/axls/able/appt/adraw/amind/folder 并读回；无 origin/shortcut 等价接口。 @@ -58,7 +58,7 @@

DWS 可挖掘的 7 个额外场景

定位与创建链

  • +space-search：严格关键词搜索。
  • +space-get：空间详情与 workspaceId 证据。
  • +resolve-space：唯一命中直出 ID，多命中拒绝猜测。
  • +wiki-new-doc：空间名解析 → 创建 → 文档读回。
-

治理与巡检链

  • +member-update：角色变更后读回。
  • +node-search：库内关键词/扩展名搜索，严格零命中。
  • +feed-list：知识库动态时间线与服务端 exclude-file 过滤。
+

治理与巡检链

  • +member-update：角色变更终态与不可精确读回声明。
  • +node-search：库内关键词/扩展名搜索，严格零命中。
  • +feed-list：知识库动态时间线与服务端 exclude-file 过滤。
@@ -69,14 +69,15 @@ 列表投影找不到数组或遇到坏元素时返回空 slice。把内部错误、字段漂移误报为“没有数据”。失败关闭 只有响应中真实存在的 [] 才是合法空集合。 节点列表 Shortcut 调错 Wiki MCP 服务。真实后端 success=false，Mock/静态检查看不出。跨域路由 明确调用 doc/list_nodes，并纳入真实 E2E。 成员帮助宣称最大 200。真实接口超过 50 直接参数错误。真实上限 Shortcut 与原子 Help 均改为 50，并在本地提前拒绝。 + 成员写操作从最多 50 条、不可分页的名单推断成员存在或缺失。目标在截断部分时会误报写失败，或把未验证的移除报告为已读回。终态证据 只接受写接口 success=true，并在结果中明确 readbackAvailable=false。 知识库名称帮助宣称最大 100。真实接口超过 32 失败。真实上限 Help 与 Shortcut 校验统一为 32。 - 复制/移动/创建只把无异常视为成功。空确认、未知远端效果或移动未到目标仍可能被接受。读回证明 检查 success、业务 ID、workspace/folder/role 等最终状态。 + 复制/移动/创建只把无异常视为成功。空确认、未知远端效果或移动未到目标仍可能被接受。读回证明 在后端具备精确查询能力时检查 success、业务 ID、workspace/folder 等最终状态。

真实数据 E2E 证据矩阵

-

测试使用一次性空知识库、临时在线文档与一名同组织内部测试成员；所有对象在 finally 清理。报告不保存对象 ID、成员身份、组织信息、URL、trace 或原始响应。

+

28 项业务断言全部通过。测试使用一次性空知识库、临时在线文档与一名同组织内部测试成员；所有对象在 finally 清理。报告不保存对象 ID、成员身份、组织信息、URL、trace 或原始响应。

@@ -86,9 +87,9 @@ - - - + + + @@ -105,7 +106,7 @@

成功判定与发布门

-

运行时证据层

  1. 传输/MCP 调用成功。
  2. 响应契约存在且类型正确。
  3. 写操作必须有 success=true 与业务 ID。
  4. 创建/复制/移动/成员变更必须读回最终状态。
  5. 集合只有显式数组才允许为空。

交付门

  1. 20/20 语义目录与注册面精确覆盖。
  2. Contract、Safety、Result、统一输出完整。
  3. 生成漂移、Schema、确认真值、全量 Go 测试。
  4. 独立真实数据 E2E 与 finally 清理。
  5. diff PII/密钥/本地绝对路径扫描。
+

运行时证据层

  1. 传输/MCP 调用成功。
  2. 响应契约存在且类型正确。
  3. 写操作必须有 success=true；创建类操作还必须有业务 ID。
  4. 后端具备精确查询时必须读回；不具备时明确发布不可读回，而非从截断集合推断。
  5. 集合只有显式数组才允许为空。

交付门

  1. 20/20 语义目录与注册面精确覆盖。
  2. Contract、Safety、Result、统一输出完整。
  3. 生成漂移、Schema、确认真值、全量 Go 测试。
  4. 独立真实数据 E2E 与 finally 清理。
  5. diff PII/密钥/本地绝对路径扫描。

DWS Wiki Shortcut business review · sanitized engineering artifact

diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 0e1f6750..f942cb97 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -140,6 +140,20 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T) assertChatCatalogCompleteLeafContracts(t) } +func TestDeliveryWikiSpaceSearchPreservesHistoricalParameterProperties(t *testing.T) { + leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search") + parameters := schemaContractMap(leaf["parameters"]) + for name, want := range map[string]string{"query": "query", "limit": "limit"} { + parameter := parameters[name] + if parameter == nil { + t.Fatalf("wiki +space-search missing --%s parameter: %#v", name, parameters) + } + if got := schemaContractString(parameter["property"]); got != want { + t.Fatalf("wiki +space-search --%s property = %q, want compatibility value %q", name, got, want) + } + } +} + func assertSchemaSummarySafety( t testing.TB, summaries map[string]map[string]any, diff --git a/internal/shortcut/semantic_catalog_wiki.json b/internal/shortcut/semantic_catalog_wiki.json index 17a3e4a1..70481b90 100644 --- a/internal/shortcut/semantic_catalog_wiki.json +++ b/internal/shortcut/semantic_catalog_wiki.json @@ -10,10 +10,10 @@ "+space-create": {"disposition":"primary_smart","semantic_delta":"创建后要求 workspaceId 并通过空间详情读回验证真实落库。","risk":"write","public":true,"reviewed":true}, "+delete-space": {"disposition":"semantic_adapter","semantic_delta":"删除前读取影响目标，经高风险确认后只接受 success=true 终态。","risk":"high-risk-write","public":true,"reviewed":true}, - "+member-add": {"disposition":"primary_smart","semantic_delta":"批量授予 Wiki 容器角色，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, - "+member-update": {"disposition":"primary_smart","semantic_delta":"补充成员角色更新，并执行终态与列表读回校验。","risk":"write","public":true,"reviewed":true}, + "+member-add": {"disposition":"semantic_adapter","semantic_delta":"支持 1-30 个 userId 与四类角色；严格要求写接口终态，并明确后端无法提供精确成员读回。","risk":"write","public":true,"reviewed":true}, + "+member-update": {"disposition":"semantic_adapter","semantic_delta":"补充成员角色更新；严格要求写接口终态，并明确后端无法提供精确成员读回。","risk":"write","public":true,"reviewed":true}, "+member-list": {"disposition":"semantic_adapter","semantic_delta":"严格验证成员数组并公开真实单次上限 50；后端无游标时不伪造 page-all。","risk":"read","public":true,"reviewed":true}, - "+member-remove": {"disposition":"primary_smart","semantic_delta":"批量移除容器访问，严格校验写终态并读取成员列表验证响应链。","risk":"write","public":true,"reviewed":true}, + "+member-remove": {"disposition":"semantic_adapter","semantic_delta":"支持批量 userId 移除；严格要求写接口终态，并明确后端无法提供精确成员读回。","risk":"write","public":true,"reviewed":true}, "+node-list": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空目录与假空成功，稳定投影节点并保留 nextCursor/hasMore。","risk":"read","public":true,"reviewed":true}, "+node-get": {"disposition":"schema_leaf","semantic_delta":"统一节点 ID 或在线文档 URL 的元数据读取，补充文档域属性视角。","risk":"read","public":true,"reviewed":true}, diff --git a/internal/shortcut/smart/mail_space_todo_projection_test.go b/internal/shortcut/smart/mail_space_todo_projection_test.go index e5af1037..80869469 100644 --- a/internal/shortcut/smart/mail_space_todo_projection_test.go +++ b/internal/shortcut/smart/mail_space_todo_projection_test.go @@ -23,6 +23,7 @@ import ( "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" @@ -103,6 +104,8 @@ func runShortcut(t *testing.T, fake *stubMailboxCaller, argv ...string) string { root.PersistentFlags().Bool("yes", false, "") root.PersistentFlags().Bool("dry-run", false, "") root.PersistentFlags().String("format", "json", "") + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) root.AddCommand(shortcut.Commands()...) var buf bytes.Buffer root.SetOut(&buf) @@ -121,6 +124,8 @@ func runShortcutErr(t *testing.T, fake *stubMailboxCaller, argv ...string) error root.PersistentFlags().Bool("yes", false, "") root.PersistentFlags().Bool("dry-run", false, "") root.PersistentFlags().String("format", "json", "") + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) root.AddCommand(shortcut.Commands()...) root.SetOut(io.Discard) root.SetErr(io.Discard) diff --git a/internal/shortcut/smart/wiki_workflow_coverage_test.go b/internal/shortcut/smart/wiki_workflow_coverage_test.go new file mode 100644 index 00000000..06812531 --- /dev/null +++ b/internal/shortcut/smart/wiki_workflow_coverage_test.go @@ -0,0 +1,187 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package smart + +import ( + "strings" + "testing" +) + +func TestCrossPlatformCoverageResolveSpaceStrictContracts(t *testing.T) { + invalid := []map[string]any{ + nil, + {"success": false}, + {"success": "yes"}, + {"result": "bad"}, + {"wikiSpaces": "bad"}, + {"wikiSpaces": []any{"bad"}}, + {"wikiSpaces": []any{map[string]any{"workspaceId": "w"}}}, + {"wikiSpaces": []any{map[string]any{"name": "Docs"}}}, + {"success": true}, + } + for index, data := range invalid { + if _, err := resolveSpaceItemsStrict(data); err == nil { + t.Fatalf("invalid response %d succeeded: %#v", index, data) + } + } + + for _, data := range []map[string]any{ + {"wikiSpaces": []any{}}, + {"spaces": []any{map[string]any{"spaceId": "s", "spaceName": "Docs"}}}, + {"result": map[string]any{"items": []any{map[string]any{"id": "i", "title": "Plan"}}}}, + {"data": map[string]any{"records": []any{map[string]any{"workspaceId": "w", "name": "Roadmap"}}}}, + } { + if _, err := resolveSpaceItemsStrict(data); err != nil { + t.Fatalf("valid response rejected: %#v: %v", data, err) + } + } + + for _, tc := range []struct { + data map[string]any + id string + name string + }{ + {map[string]any{"workspaceId": "w", "name": "N"}, "w", "N"}, + {map[string]any{"spaceId": "s", "spaceName": "S"}, "s", "S"}, + {map[string]any{"space_id": "legacy", "title": "T"}, "legacy", "T"}, + {map[string]any{"id": "i"}, "i", ""}, + {map[string]any{}, "", ""}, + } { + if got := resolveSpaceID(tc.data); got != tc.id { + t.Fatalf("resolveSpaceID(%#v)=%q want %q", tc.data, got, tc.id) + } + if got := resolveSpaceName(tc.data); got != tc.name { + t.Fatalf("resolveSpaceName(%#v)=%q want %q", tc.data, got, tc.name) + } + } +} + +func TestCrossPlatformCoverageResolveSpaceExecution(t *testing.T) { + for _, tc := range []struct { + name string + fake *stubMailboxCaller + ok bool + }{ + {"transport error", &stubMailboxCaller{errTool: "search_wikiSpaces"}, false}, + {"malformed result", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": `{"success":true}`}}, false}, + {"zero result", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": `{"wikiSpaces":[]}`}}, false}, + {"one result", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": `{"wikiSpaces":[{"workspaceId":"w","name":"Docs"}]}`}}, true}, + {"multiple results", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": `{"wikiSpaces":[{"workspaceId":"w1","name":"Docs"},{"workspaceId":"w2","name":"Docs 2"}]}`}}, true}, + } { + t.Run(tc.name, func(t *testing.T) { + err := runShortcutErr(t, tc.fake, "wiki", "+resolve-space", "--name", "Docs", "--format", "json") + if (err == nil) != tc.ok { + t.Fatalf("success=%v want %v; err=%v", err == nil, tc.ok, err) + } + }) + } +} + +func TestCrossPlatformCoverageWikiNewDocParsing(t *testing.T) { + invalid := []map[string]any{ + nil, + {"success": false}, + {"success": "yes"}, + {"result": map[string]any{"wikiSpaces": "bad"}}, + {"wikiSpaces": []any{"bad"}}, + {"wikiSpaces": []any{map[string]any{"workspaceId": "w"}}}, + {"success": true}, + } + for index, data := range invalid { + if _, err := wikiNewDocExtractSpaces(data); err == nil { + t.Fatalf("invalid response %d succeeded: %#v", index, data) + } + } + + for _, data := range []map[string]any{ + {"wikiSpaces": []any{}}, + {"list": []any{map[string]any{"workspaceId": "w", "name": "Docs"}}}, + {"data": map[string]any{"spaces": []any{map[string]any{"spaceId": "s", "spaceName": "Plan"}}}}, + {"result": map[string]any{"result": []any{map[string]any{"id": "i", "title": "Roadmap"}}}}, + } { + if _, err := wikiNewDocExtractSpaces(data); err != nil { + t.Fatalf("valid response rejected: %#v: %v", data, err) + } + } + + if got := wikiNewDocFirstString(map[string]any{"nodeId": " n "}, "nodeId"); got != "n" { + t.Fatalf("direct node id=%q", got) + } + if got := wikiNewDocFirstString(map[string]any{"result": map[string]any{"fileId": " f "}}, "nodeId", "fileId"); got != "f" { + t.Fatalf("nested node id=%q", got) + } + if got := wikiNewDocFirstString(map[string]any{"data": map[string]any{"id": " i "}}, "id"); got != "i" { + t.Fatalf("data node id=%q", got) + } + if got := wikiNewDocFirstString(map[string]any{"id": 1}, "id"); got != "" { + t.Fatalf("invalid node id=%q", got) + } + labels := wikiNewDocLabels([]wikiSpaceCandidate{{id: "w1", name: "Docs"}, {id: "w2", name: "Plan"}}) + if strings.Join(labels, ",") != "Docs(w1),Plan(w2)" { + t.Fatalf("labels=%v", labels) + } +} + +func TestCrossPlatformCoverageWikiNewDocResolution(t *testing.T) { + cases := []struct { + name string + data map[string]any + spaceName string + want string + ok bool + }{ + {"parser error", nil, "Docs", "", false}, + {"zero", map[string]any{"wikiSpaces": []any{}}, "Docs", "", false}, + {"unique exact", map[string]any{"wikiSpaces": []any{map[string]any{"workspaceId": "w1", "name": " docs "}, map[string]any{"workspaceId": "w2", "name": "Plan"}}}, "Docs", "w1", true}, + {"unique fallback", map[string]any{"wikiSpaces": []any{map[string]any{"workspaceId": "w1", "name": "Docs Team"}}}, "Docs", "w1", true}, + {"multiple", map[string]any{"wikiSpaces": []any{map[string]any{"workspaceId": "w1", "name": "Docs 1"}, map[string]any{"workspaceId": "w2", "name": "Docs 2"}}}, "Docs", "", false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, err := wikiNewDocResolveSpaceID(tc.data, tc.spaceName) + if (err == nil) != tc.ok || got != tc.want { + t.Fatalf("got=%q err=%v want=%q ok=%v", got, err, tc.want, tc.ok) + } + }) + } +} + +func TestCrossPlatformCoverageWikiNewDocExecution(t *testing.T) { + if err := runShortcutErr(t, &stubMailboxCaller{}, "wiki", "+wiki-new-doc", "--space", " ", "--title", "Doc"); err == nil { + t.Fatal("blank space succeeded") + } + if err := runShortcutErr(t, &stubMailboxCaller{}, "wiki", "+wiki-new-doc", "--space", "Docs", "--title", " "); err == nil { + t.Fatal("blank title succeeded") + } + + validSearch := `{"wikiSpaces":[{"workspaceId":"w","name":"Docs"}]}` + cases := []struct { + name string + fake *stubMailboxCaller + args []string + ok bool + }{ + {"search error", &stubMailboxCaller{errTool: "search_wikiSpaces"}, nil, false}, + {"resolve error", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": `{"wikiSpaces":[]}`}}, nil, false}, + {"dry run", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch}}, []string{"--dry-run"}, true}, + {"create error", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch}, errTool: "create_file"}, nil, false}, + {"missing terminal success", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"result":{"fileId":"n"}}`}}, nil, false}, + {"missing created id", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true}`}}, nil, false}, + {"readback error", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true,"fileId":"n"}`}, errTool: "get_document_info"}, nil, false}, + {"readback failed", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true,"fileId":"n"}`, "get_document_info": `{"success":false}`}}, nil, false}, + {"readback malformed success", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true,"fileId":"n"}`, "get_document_info": `{"success":"yes"}`}}, nil, false}, + {"readback id mismatch", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true,"fileId":"n"}`, "get_document_info": `{"success":true,"nodeId":"other"}`}}, nil, false}, + {"verified", &stubMailboxCaller{byTool: map[string]string{"search_wikiSpaces": validSearch, "create_file": `{"success":true,"data":{"fileId":"n"}}`, "get_document_info": `{"success":true,"result":{"nodeId":"n"}}`}}, nil, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + args := []string{"wiki", "+wiki-new-doc", "--space", "Docs", "--title", "Doc", "--format", "json"} + args = append(args, tc.args...) + err := runShortcutErr(t, tc.fake, args...) + if (err == nil) != tc.ok { + t.Fatalf("success=%v want %v; err=%v", err == nil, tc.ok, err) + } + }) + } +} diff --git a/internal/shortcut/wiki/common.go b/internal/shortcut/wiki/common.go index 1479315b..708aa21a 100644 --- a/internal/shortcut/wiki/common.go +++ b/internal/shortcut/wiki/common.go @@ -6,6 +6,7 @@ package wiki import ( "encoding/json" "fmt" + "strconv" "strings" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" @@ -177,6 +178,31 @@ func nestedWikiString(data map[string]any, keys ...string) string { return "" } +func wikiStringInt(rt *shortcut.RuntimeContext, name string, fallback, min, max int) (int, error) { + raw := rt.Str(name) + if raw == "" { + return fallback, nil + } + value, err := strconv.Atoi(raw) + if err != nil || value < min || value > max { + return 0, fmt.Errorf("--%s 必须是 %d-%d 之间的整数", name, min, max) + } + return value, nil +} + +func wikiStringSliceFirst(rt *shortcut.RuntimeContext, primary string, aliases ...string) []string { + if rt.Changed(primary) { + return rt.StrSlice(primary) + } + for _, alias := range aliases { + if rt.Changed(alias) { + values, _ := rt.Command().Flags().GetStringSlice(alias) + return values + } + } + return rt.StrSlice(primary) +} + func wikiResponseError(operation, reason, message string) error { return apperrors.NewAPI(message, apperrors.WithOperation(operation), apperrors.WithOrigin("mcp"), apperrors.WithFailureStage("response_validation"), apperrors.WithRetryable(false), apperrors.WithReason(reason)) } @@ -218,14 +244,14 @@ type wikiPageFetcher func(cursor string, pageSize int) (map[string]any, error) func collectWikiPages(rt *shortcut.RuntimeContext, operation string, pageSize int, keys []string, fetch wikiPageFetcher) ([]any, map[string]any, error) { if !rt.Bool("page-all") { - data, err := fetch(rt.Str("cursor"), pageSize) + data, err := fetch(rt.StrFirst("cursor", "page-token"), pageSize) if err != nil { return nil, nil, err } return requireWikiCollection(data, operation, keys...) } all := make([]any, 0) - cursor := rt.Str("cursor") + cursor := rt.StrFirst("cursor", "page-token") lastPage := map[string]any{} for pageNumber := 1; pageNumber <= rt.Int("page-limit"); pageNumber++ { requestSize := shortcut.AutoPageRequestSize(rt, pageSize, len(all)) diff --git a/internal/shortcut/wiki/wiki.go b/internal/shortcut/wiki/wiki.go index 28012ba8..25104fdb 100644 --- a/internal/shortcut/wiki/wiki.go +++ b/internal/shortcut/wiki/wiki.go @@ -30,9 +30,13 @@ func writeShortcut(command, description, intent string, risk shortcut.Risk, safe var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏览有权访问的组织或个人知识库，并保留服务端分页证据；只有显式 wikiSpaces:[] 才是空结果。", "spaces", []shortcut.Flag{ {Name: "type", Type: shortcut.FlagString, Default: "orgWikiSpace", Desc: "知识库类型", Enum: []string{"orgWikiSpace", "myWikiSpace"}}, - {Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量 1-50"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, + {Name: "limit", Type: shortcut.FlagString, Desc: "每页数量 1-50（默认 20）"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, }, []contract.ParamDecl{{Name: "type", Property: "wikiSpaceType"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { - items, page, err := collectWikiPages(rt, "wiki/list_wikiSpaces", rt.Int("limit"), []string{"wikiSpaces", "spaces"}, func(cursor string, size int) (map[string]any, error) { + pageSize, err := wikiStringInt(rt, "limit", 20, 1, 50) + if err != nil { + return err + } + items, page, err := collectWikiPages(rt, "wiki/list_wikiSpaces", pageSize, []string{"wikiSpaces", "spaces"}, func(cursor string, size int) (map[string]any, error) { params := map[string]any{"wikiSpaceType": rt.Str("type"), "pageSize": size} if cursor != "" { params["pageToken"] = cursor @@ -49,9 +53,13 @@ var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏 }) var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", []shortcut.Flag{ - {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "返回数量 1-20"}, -}, []contract.ParamDecl{{Name: "query", Property: "query"}, {Name: "limit", Property: "pageSize"}}, func(rt *shortcut.RuntimeContext) error { - data, err := rt.CallMCPData("wiki", "search_wikiSpaces", map[string]any{"keyword": rt.Str("query"), "pageSize": rt.Int("limit")}) + {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词"}, {Name: "limit", Type: shortcut.FlagString, Desc: "返回数量 1-20（默认 10）"}, +}, []contract.ParamDecl{{Name: "query", Property: "query"}, {Name: "limit", Property: "limit"}}, func(rt *shortcut.RuntimeContext) error { + pageSize, err := wikiStringInt(rt, "limit", 10, 1, 20) + if err != nil { + return err + } + data, err := rt.CallMCPData("wiki", "search_wikiSpaces", map[string]any{"keyword": rt.Str("query"), "pageSize": pageSize}) if err != nil { return err } @@ -154,7 +162,7 @@ func memberWrite(command, tool, description, intent string, withRole bool) short params = append(params, contract.ParamDecl{Name: "role", Property: "roleId"}) } return writeShortcut(command, description, intent, shortcut.RiskWrite, wikiWriteSafety(false), memberFlags(withRole), params, func(rt *shortcut.RuntimeContext) error { - users := rt.StrSlice("users") + users := wikiStringSliceFirst(rt, "users", "user") if len(users) == 0 || len(users) > 30 { return fmt.Errorf("--users 必须包含 1-30 个 userId") } @@ -173,41 +181,21 @@ func memberWrite(command, tool, description, intent string, withRole bool) short if err != nil { return err } - listed, err := rt.CallMCPData("wiki", "list_member", map[string]any{"workspaceId": rt.Str("workspace"), "maxResults": 50}) - if err != nil { - return err - } - items, _, err := requireWikiCollection(listed, "wiki/list_member", "members") - if err != nil { - return err - } - found := make(map[string]string) - for _, item := range items { - member := item.(map[string]any) - id := firstWikiString(member, "id", "userId") - if id != "" { - found[id] = strings.ToUpper(firstWikiString(member, "role", "roleId")) - } - } - for _, user := range users { - role, present := found[user] - if tool == "remove_member" && present { - return wikiResponseError("wiki/"+tool, "readback_member_still_present", "成员移除后仍出现在成员列表中") - } - if tool != "remove_member" && !present { - return wikiResponseError("wiki/"+tool, "readback_member_missing", "成员写入后未出现在成员列表中") - } - if withRole && role != strings.ToUpper(rt.Str("role")) { - return wikiResponseError("wiki/"+tool, "readback_role_mismatch", "成员写入后读回角色与请求不一致") - } - } - return rt.Output(map[string]any{"success": true, "workspaceId": rt.Str("workspace"), "userCount": len(users), "operation": tool, "verifiedBy": "member_list_readback"}) + return rt.Output(map[string]any{ + "success": true, "workspaceId": rt.Str("workspace"), "userCount": len(users), "operation": tool, + "verifiedBy": "write_terminal_success", + "verification": map[string]any{ + "status": "terminal_response_only", + "readbackAvailable": false, + "reason": "member_list_is_capped_and_has_no_cursor", + }, + }) }) } -var MemberAdd = memberWrite("+member-add", "add_member", "添加知识库成员", "向知识库授予一个或多个用户容器级角色，并用成员列表读回验证响应契约。", true) -var MemberUpdate = memberWrite("+member-update", "update_member", "更新知识库成员角色", "调整已有成员的知识库容器级角色，并用成员列表读回验证响应契约。", true) -var MemberRemove = memberWrite("+member-remove", "remove_member", "移除知识库成员", "移除一个或多个用户的知识库容器级访问，并用成员列表读回验证响应契约。", false) +var MemberAdd = memberWrite("+member-add", "add_member", "添加知识库成员", "向知识库授予一个或多个用户容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", true) +var MemberUpdate = memberWrite("+member-update", "update_member", "更新知识库成员角色", "调整已有成员的知识库容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", true) +var MemberRemove = memberWrite("+member-remove", "remove_member", "移除知识库成员", "移除一个或多个用户的知识库容器级访问；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", false) var MemberList = readShortcut("+member-list", "严格列出知识库成员", "列出知识库成员及角色；后端不提供可续游标且单次真实上限为 50，不伪造 page-all。", "members", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "30", Desc: "返回上限 1-50"}, {Name: "filter-role", Type: shortcut.FlagStringSlice, Desc: "角色过滤"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "filter-role", Property: "filterRoleIds"}}, func(rt *shortcut.RuntimeContext) error { if rt.Int("limit") < 1 || rt.Int("limit") > 50 { diff --git a/internal/shortcut/wiki/workflow_coverage_test.go b/internal/shortcut/wiki/workflow_coverage_test.go new file mode 100644 index 00000000..a1d2a8b0 --- /dev/null +++ b/internal/shortcut/wiki/workflow_coverage_test.go @@ -0,0 +1,638 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package wiki + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +type wikiCoverageCall struct { + product string + tool string + args map[string]any +} + +type wikiCoverageCaller struct { + responses map[string][]string + errors map[string][]error + indexes map[string]int + calls []wikiCoverageCall + dryRun bool +} + +func (c *wikiCoverageCaller) CallTool(_ context.Context, product, tool string, args map[string]any) (*edition.ToolResult, error) { + key := product + "/" + tool + c.calls = append(c.calls, wikiCoverageCall{product: product, tool: tool, args: args}) + if c.indexes == nil { + c.indexes = map[string]int{} + } + index := c.indexes[key] + c.indexes[key]++ + if sequence := c.errors[key]; index < len(sequence) && sequence[index] != nil { + return nil, sequence[index] + } + sequence := c.responses[key] + if len(sequence) == 0 { + return nil, fmt.Errorf("unexpected MCP call %s", key) + } + if index >= len(sequence) { + index = len(sequence) - 1 + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: sequence[index]}}}, nil +} + +func (c *wikiCoverageCaller) Format() string { return "json" } +func (c *wikiCoverageCaller) DryRun() bool { return c.dryRun } +func (c *wikiCoverageCaller) Fields() string { return "" } +func (c *wikiCoverageCaller) JQ() string { return "" } + +func runWikiCoverageCLI(t *testing.T, caller *wikiCoverageCaller, args ...string) (map[string]any, error) { + t.Helper() + helpers.InitDepsForTest(t, caller) + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + root.PersistentFlags().Bool("yes", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.PersistentFlags().String("format", "json", "") + root.PersistentFlags().String("jq", "", "") + root.PersistentFlags().String("fields", "", "") + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) + root.AddCommand(shortcut.Commands()...) + stdout := &bytes.Buffer{} + root.SetOut(stdout) + root.SetErr(&bytes.Buffer{}) + root.SetArgs(append([]string{"wiki"}, args...)) + executed, err := root.ExecuteC() + if err == nil { + if _, _, emitErr := output.EmitStoredResult(executed); emitErr != nil { + err = emitErr + } + } + if stdout.Len() == 0 { + return nil, err + } + var payload map[string]any + if decodeErr := json.Unmarshal(stdout.Bytes(), &payload); decodeErr != nil { + t.Fatalf("decode output %q: %v", stdout.String(), decodeErr) + } + if data, ok := payload["data"].(map[string]any); ok { + return data, err + } + return payload, err +} + +func TestCrossPlatformCoverageWikiSpaceWorkflows(t *testing.T) { + t.Run("list default string limit", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_wikiSpaces": {`{"success":true,"result":{"wikiSpaces":[{"workspaceId":"w1","name":"Docs"}],"hasMore":false}}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-list") + if err != nil || out["count"] != float64(1) || caller.calls[0].args["pageSize"] != 20 { + t.Fatalf("list output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("list explicit legacy string limit and cursor", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_wikiSpaces": {`{"wikiSpaces":[],"hasMore":false}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-list", "--type", "myWikiSpace", "--limit", "7", "--page-token", "next") + if err != nil || out["count"] != float64(0) || caller.calls[0].args["pageSize"] != 7 || caller.calls[0].args["pageToken"] != "next" { + t.Fatalf("list output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + for _, value := range []string{"bad", "0", "51"} { + t.Run("list rejects "+value, func(t *testing.T) { + caller := &wikiCoverageCaller{} + if _, err := runWikiCoverageCLI(t, caller, "+space-list", "--limit", value); err == nil || len(caller.calls) != 0 { + t.Fatalf("limit %q err=%v calls=%#v", value, err, caller.calls) + } + }) + } + + t.Run("search parses string limit", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/search_wikiSpaces": {`{"success":true,"wikiSpaces":[{"spaceId":"w2","spaceName":"Plan"}]}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-search", "--query", "Plan", "--limit", "12") + if err != nil || out["count"] != float64(1) || caller.calls[0].args["pageSize"] != 12 { + t.Fatalf("search output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("get requires business id", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"success":true,"result":{"name":"missing id"}}`}}} + if _, err := runWikiCoverageCLI(t, caller, "+space-get", "--workspace", "w"); err == nil { + t.Fatal("space without id succeeded") + } + }) + + t.Run("create dry-run", func(t *testing.T) { + caller := &wikiCoverageCaller{} + out, err := runWikiCoverageCLI(t, caller, "+space-create", "--name", "Docs", "--desc", "D", "--icon", "I", "--dry-run") + if err != nil || out["executed"] != false || len(caller.calls) != 0 { + t.Fatalf("dry-run output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("create and exact readback", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/create_wikiSpace": {`{"success":true,"result":{"workspaceId":"w3"}}`}, + "wiki/get_wikiSpace": {`{"success":true,"data":{"workspaceId":"w3","name":"Docs"}}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-create", "--name", "Docs") + if err != nil || out["workspaceId"] != "w3" || len(caller.calls) != 2 { + t.Fatalf("create output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("delete preflight dry-run and terminal", func(t *testing.T) { + dry := &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"workspaceId":"w4","name":"Docs"}`}}} + out, err := runWikiCoverageCLI(t, dry, "+delete-space", "--workspace", "w4", "--dry-run", "--yes") + if err != nil || out["executed"] != false || len(dry.calls) != 1 { + t.Fatalf("delete dry-run output=%#v err=%v calls=%#v", out, err, dry.calls) + } + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/get_wikiSpace": {`{"workspaceId":"w4","name":"Docs"}`}, + "wiki/delete_wikiSpace": {`{"success":true}`}, + }} + out, err = runWikiCoverageCLI(t, caller, "+space-delete", "--workspace", "w4", "--yes") + if err != nil || out["deleted"] != true || len(caller.calls) != 2 { + t.Fatalf("delete output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + for _, args := range [][]string{{"--name", strings.Repeat("界", 33)}, {"--name", "x", "--desc", strings.Repeat("界", 501)}} { + caller := &wikiCoverageCaller{} + if _, err := runWikiCoverageCLI(t, caller, append([]string{"+space-create"}, args...)...); err == nil || len(caller.calls) != 0 { + t.Fatalf("invalid create args succeeded: %v", args) + } + } +} + +func TestCrossPlatformCoverageWikiMemberWritesUseTerminalEvidenceOnly(t *testing.T) { + for _, tc := range []struct { + command string + tool string + extra []string + }{ + {command: "+member-add", tool: "add_member", extra: []string{"--role", "READER"}}, + {command: "+member-update", tool: "update_member", extra: []string{"--role", "EDITOR"}}, + {command: "+member-remove", tool: "remove_member"}, + } { + t.Run(tc.command, func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/" + tc.tool: {`{"success":true}`}}} + args := append([]string{tc.command, "--workspace", "w", "--users", "u1,u2"}, tc.extra...) + out, err := runWikiCoverageCLI(t, caller, args...) + verification, _ := out["verification"].(map[string]any) + if err != nil || out["verifiedBy"] != "write_terminal_success" || verification["readbackAvailable"] != false || len(caller.calls) != 1 { + t.Fatalf("member output=%#v err=%v calls=%#v", out, err, caller.calls) + } + if caller.calls[0].tool == "list_member" { + t.Fatal("member write used capped list as readback") + } + if tc.tool != "remove_member" && caller.calls[0].args["roleId"] != strings.ToUpper(tc.extra[1]) { + t.Fatalf("role was not normalized: %#v", caller.calls[0].args) + } + }) + } + + t.Run("dry-run has no write", func(t *testing.T) { + caller := &wikiCoverageCaller{} + out, err := runWikiCoverageCLI(t, caller, "+member-add", "--workspace", "w", "--users", "u", "--role", "READER", "--dry-run") + if err != nil || out["executed"] != false || len(caller.calls) != 0 { + t.Fatalf("dry-run output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("rejects missing terminal evidence", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/add_member": {`{"result":{"accepted":true}}`}}} + if _, err := runWikiCoverageCLI(t, caller, "+member-add", "--workspace", "w", "--users", "u", "--role", "READER"); err == nil { + t.Fatal("member write without success=true succeeded") + } + }) + + many := make([]string, 31) + for index := range many { + many[index] = fmt.Sprintf("u%d", index) + } + caller := &wikiCoverageCaller{} + if _, err := runWikiCoverageCLI(t, caller, "+member-remove", "--workspace", "w", "--users", strings.Join(many, ",")); err == nil || len(caller.calls) != 0 { + t.Fatal("more than 30 members reached MCP") + } +} + +func TestCrossPlatformCoverageWikiMemberListContracts(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_member": {`{"success":true,"members":[{"userId":"u1","nick":"A","roleId":"READER","type":"USER","outer":false}],"truncated":false}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+member-list", "--workspace", "w", "--limit", "50", "--filter-role", "READER,EDITOR") + if err != nil || out["count"] != float64(1) || caller.calls[0].args["maxResults"] != 50 { + t.Fatalf("member list output=%#v err=%v calls=%#v", out, err, caller.calls) + } + for _, value := range []string{"0", "51"} { + caller = &wikiCoverageCaller{} + if _, err := runWikiCoverageCLI(t, caller, "+member-list", "--workspace", "w", "--limit", value); err == nil || len(caller.calls) != 0 { + t.Fatalf("invalid member limit %s reached MCP", value) + } + } +} + +func TestCrossPlatformCoverageWikiReadWorkflows(t *testing.T) { + cases := []struct { + name string + args []string + responses map[string][]string + wantTool string + wantCount float64 + }{ + {name: "node list", args: []string{"+node-list", "--workspace", "w", "--folder", "f", "--limit", "2", "--cursor", "c"}, responses: map[string][]string{"doc/list_nodes": {`{"success":true,"nodes":[{"id":"n","title":"Doc","parentId":"f","spaceId":"w"}],"hasMore":false}`}}, wantTool: "list_nodes", wantCount: 1}, + {name: "node search", args: []string{"+node-search", "--workspace", "w", "--query", "Doc", "--extensions", "adoc", "--limit", "2", "--cursor", "c"}, responses: map[string][]string{"doc/search_documents": {`{"success":true,"documents":[],"hasMore":false}`}}, wantTool: "search_documents", wantCount: 0}, + {name: "feed list", args: []string{"+feed-list", "--workspace", "w", "--limit", "2", "--cursor", "c", "--exclude-file"}, responses: map[string][]string{"wiki/list_workspace_feeds": {`{"success":true,"feeds":[{"feedId":"x","feedType":"update","fileId":"n"}],"hasMore":false}`}}, wantTool: "list_workspace_feeds", wantCount: 1}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + caller := &wikiCoverageCaller{responses: tc.responses} + out, err := runWikiCoverageCLI(t, caller, tc.args...) + if err != nil || out["count"] != tc.wantCount || caller.calls[0].tool != tc.wantTool { + t.Fatalf("output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + } + + t.Run("node get", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"success":true,"result":{"nodeId":"n","title":"Doc"}}`}}} + out, err := runWikiCoverageCLI(t, caller, "+node-get", "--node", "n") + if err != nil || out["nodeId"] != "n" { + t.Fatalf("node get output=%#v err=%v", out, err) + } + }) +} + +func TestCrossPlatformCoverageWikiWriteWorkflows(t *testing.T) { + t.Run("node create dry and verified", func(t *testing.T) { + dry := &wikiCoverageCaller{} + out, err := runWikiCoverageCLI(t, dry, "+node-create", "--workspace", "w", "--folder", "f", "--name", "Doc", "--type", "adoc", "--dry-run") + if err != nil || out["executed"] != false || len(dry.calls) != 0 { + t.Fatalf("create dry output=%#v err=%v calls=%#v", out, err, dry.calls) + } + caller := &wikiCoverageCaller{responses: map[string][]string{ + "doc/create_file": {`{"success":true,"data":{"fileId":"n"}}`}, + "doc/get_document_info": {`{"success":true,"nodeId":"n","workspaceId":"w","folderId":"f"}`}, + }} + out, err = runWikiCoverageCLI(t, caller, "+node-create", "--workspace", "w", "--folder", "f", "--name", "Doc") + if err != nil || out["nodeId"] != "n" || len(caller.calls) != 2 { + t.Fatalf("create output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("node copy dry and verified", func(t *testing.T) { + dry := &wikiCoverageCaller{} + out, err := runWikiCoverageCLI(t, dry, "+node-copy", "--workspace", "w", "--folder", "f", "--node", "source", "--dry-run", "--yes") + if err != nil || out["executed"] != false || len(dry.calls) != 0 { + t.Fatalf("copy dry output=%#v err=%v calls=%#v", out, err, dry.calls) + } + caller := &wikiCoverageCaller{responses: map[string][]string{ + "doc/copy_document": {`{"success":true,"nodeId":"copy"}`}, + "doc/get_document_info": {`{"success":true,"nodeId":"copy","workspaceId":"w"}`}, + }} + out, err = runWikiCoverageCLI(t, caller, "+node-copy", "--workspace", "w", "--node", "source", "--yes") + if err != nil || out["nodeId"] != "copy" || len(caller.calls) != 2 { + t.Fatalf("copy output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("move within wiki and to drive", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "doc/get_document_info": {`{"nodeId":"n","workspaceId":"old","folderId":"old-f"}`, `{"nodeId":"n","workspaceId":"target","folderId":"f"}`}, + "doc/move_document": {`{"success":true}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+move", "--workspace", "target", "--folder", "f", "--node", "n", "--yes") + if err != nil || out["nodeId"] != "n" || len(caller.calls) != 3 { + t.Fatalf("move output=%#v err=%v calls=%#v", out, err, caller.calls) + } + caller = &wikiCoverageCaller{responses: map[string][]string{ + "doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`, `{"nodeId":"n","workspaceId":"drive"}`}, + "doc/move_document": {`{"success":true}`}, + }} + out, err = runWikiCoverageCLI(t, caller, "+move-to-drive", "--node", "n", "--yes") + if err != nil || out["nodeId"] != "n" { + t.Fatalf("move-to-drive output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("move dry-run only preflights", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`}}} + out, err := runWikiCoverageCLI(t, caller, "+move", "--workspace", "target", "--node", "n", "--dry-run", "--yes") + if err != nil || out["executed"] != false || len(caller.calls) != 1 { + t.Fatalf("move dry output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("node delete dry and terminal", func(t *testing.T) { + dry := &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"w"}`}}} + out, err := runWikiCoverageCLI(t, dry, "+node-delete", "--workspace", "w", "--node", "n", "--dry-run", "--yes") + if err != nil || out["executed"] != false || len(dry.calls) != 1 { + t.Fatalf("delete dry output=%#v err=%v calls=%#v", out, err, dry.calls) + } + caller := &wikiCoverageCaller{responses: map[string][]string{ + "doc/get_document_info": {`{"nodeId":"n","workspaceId":"w"}`}, + "doc/delete_document": {`{"success":true}`}, + }} + out, err = runWikiCoverageCLI(t, caller, "+node-delete", "--workspace", "w", "--node", "n", "--yes") + if err != nil || out["deleted"] != true || len(caller.calls) != 2 { + t.Fatalf("delete output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) +} + +func TestCrossPlatformCoverageWikiResponseValidationBranches(t *testing.T) { + if _, err := requireWikiResponse(nil, "op"); err == nil { + t.Fatal("empty response accepted") + } + for _, data := range []map[string]any{{"success": "yes"}, {"success": false}, {"success": false, "message": "denied"}} { + if _, err := requireWikiResponse(data, "op"); err == nil { + t.Fatalf("invalid response accepted: %#v", data) + } + } + if _, err := requireWikiWrite(map[string]any{"result": map[string]any{"id": "x"}}, "op"); err == nil { + t.Fatal("write without terminal success accepted") + } + if _, err := requireWikiWrite(map[string]any{"success": false}, "op"); err == nil { + t.Fatal("failed write response accepted") + } + for _, data := range []map[string]any{ + {"success": false}, {"result": "bad"}, {"result": map[string]any{}}, {"only": true}, + } { + if _, err := requireWikiObject(data, "op"); err == nil { + t.Fatalf("invalid object accepted: %#v", data) + } + } + if object, err := requireWikiObject(map[string]any{"success": true, "id": "x"}, "op"); err != nil || object["id"] != "x" { + t.Fatalf("direct object=%#v err=%v", object, err) + } + for _, data := range []map[string]any{ + {"success": false}, {"result": "bad"}, {"result": map[string]any{"items": "bad"}}, {"items": []any{1}}, {"success": true}, + } { + if _, _, err := requireWikiCollection(data, "op", "items"); err == nil { + t.Fatalf("invalid collection accepted: %#v", data) + } + } + if value := nestedWikiString(map[string]any{"data": map[string]any{"id": " nested "}}, "id"); value != "nested" { + t.Fatalf("nested string=%q", value) + } + if value := nestedWikiString(map[string]any{"id": " direct "}, "id"); value != "direct" { + t.Fatalf("direct string=%q", value) + } + if value := nestedWikiString(map[string]any{"id": 1}, "id"); value != "" { + t.Fatalf("non-string=%q", value) + } + + page := map[string]any{"nextToken": "n", "hasMore": true, "truncated": false, "totalCount": 1, "autoPageComplete": true, "autoPageStopReason": "done", "pagesFetched": 2} + out := map[string]any{} + addWikiPagination(out, page) + for _, key := range []string{"nextCursor", "hasMore", "truncated", "totalCount", "autoPageComplete", "autoPageStopReason", "pagesFetched"} { + if _, ok := out[key]; !ok { + t.Fatalf("pagination output missing %s: %#v", key, out) + } + } + rows := projectWikiRows([]any{map[string]any{"legacy": "x", "empty": nil}}, map[string][]string{"value": {"empty", "legacy"}}) + if len(rows) != 1 || rows[0]["value"] != "x" { + t.Fatalf("projected rows=%#v", rows) + } +} + +func TestCrossPlatformCoverageWikiAliasAndCancellationBranches(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/remove_member": {`{"success":true}`}}} + out, err := runWikiCoverageCLI(t, caller, "+member-remove", "--workspace", "w", "--user", "u1") + if err != nil || out["userCount"] != float64(1) { + t.Fatalf("visible member alias output=%#v err=%v calls=%#v", out, err, caller.calls) + } + + cmd := &cobra.Command{Use: "probe"} + cmd.Flags().StringSlice("users", nil, "") + cmd.Flags().StringSlice("user", nil, "") + rt := shortcut.RuntimeContextForTest(cmd, MemberRemove) + if got := wikiStringSliceFirst(rt, "users", "user"); len(got) != 0 { + t.Fatalf("unset string slice=%v", got) + } + + pageCmd := &cobra.Command{Use: "page"} + pageCmd.Flags().Bool("page-all", true, "") + pageCmd.Flags().Int("page-limit", 2, "") + pageCmd.Flags().Int("max-items", 0, "") + pageCmd.Flags().Int("page-delay", 1, "") + pageCmd.Flags().String("cursor", "", "") + pageCmd.Flags().String("page-token", "", "") + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + pageCmd.SetContext(cancelled) + pageRT := shortcut.RuntimeContextForTest(pageCmd, SpaceList) + _, _, err = collectWikiPages(pageRT, "probe", 1, []string{"items"}, func(string, int) (map[string]any, error) { + return map[string]any{"items": []any{}, "hasMore": true, "nextCursor": "next"}, nil + }) + if !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled page delay err=%v", err) + } +} + +func TestCrossPlatformCoverageWikiPaginationFailureModes(t *testing.T) { + t.Run("two pages", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_wikiSpaces": { + `{"wikiSpaces":[{"workspaceId":"w1"}],"hasMore":true,"nextCursor":"next"}`, + `{"wikiSpaces":[{"workspaceId":"w2"}],"hasMore":false}`, + }, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-list", "--limit", "1", "--page-all", "--page-limit", "2") + if err != nil || out["count"] != float64(2) || out["autoPageComplete"] != true { + t.Fatalf("pagination output=%#v err=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("max items", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_wikiSpaces": {`{"wikiSpaces":[{"workspaceId":"w1"}],"hasMore":true,"nextCursor":"next"}`}, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-list", "--limit", "2", "--page-all", "--max-items", "1") + if err != nil || out["autoPageStopReason"] != "max_items" { + t.Fatalf("max-items output=%#v err=%v", out, err) + } + }) + + cases := []struct { + name string + response string + args []string + }{ + {name: "missing has more", response: `{"wikiSpaces":[]}`, args: []string{"--page-all"}}, + {name: "malformed has more", response: `{"wikiSpaces":[],"hasMore":"yes"}`, args: []string{"--page-all"}}, + {name: "missing cursor", response: `{"wikiSpaces":[],"hasMore":true}`, args: []string{"--page-all"}}, + {name: "stalled cursor", response: `{"wikiSpaces":[],"hasMore":true,"nextCursor":"same"}`, args: []string{"--cursor", "same", "--page-all"}}, + {name: "page limit", response: `{"wikiSpaces":[],"hasMore":true,"nextCursor":"next"}`, args: []string{"--page-all", "--page-limit", "1"}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/list_wikiSpaces": {tc.response}}} + if _, err := runWikiCoverageCLI(t, caller, append([]string{"+space-list"}, tc.args...)...); err == nil { + t.Fatalf("pagination failure %s succeeded", tc.name) + } + }) + } + + for _, args := range [][]string{{"--page-limit", "0", "--page-all"}, {"--max-items", "1"}, {"--page-delay", "1"}} { + caller := &wikiCoverageCaller{} + if _, err := runWikiCoverageCLI(t, caller, append([]string{"+space-list"}, args...)...); err == nil || len(caller.calls) != 0 { + t.Fatalf("invalid auto-page controls succeeded: %v", args) + } + } +} + +func TestCrossPlatformCoverageWikiMCPFailuresPropagate(t *testing.T) { + caller := &wikiCoverageCaller{ + responses: map[string][]string{"wiki/list_wikiSpaces": {`{"wikiSpaces":[]}`}}, + errors: map[string][]error{"wiki/list_wikiSpaces": {errors.New("read failed")}}, + } + if _, err := runWikiCoverageCLI(t, caller, "+space-list"); err == nil { + t.Fatal("MCP failure was swallowed") + } +} + +func TestCrossPlatformCoverageWikiSpaceFailureBranches(t *testing.T) { + assertErr := func(name string, caller *wikiCoverageCaller, args ...string) { + t.Helper() + t.Run(name, func(t *testing.T) { + if _, err := runWikiCoverageCLI(t, caller, args...); err == nil { + t.Fatalf("%s unexpectedly succeeded; calls=%#v", name, caller.calls) + } + }) + } + backend := errors.New("backend failed") + assertErr("search invalid limit", &wikiCoverageCaller{}, "+space-search", "--query", "x", "--limit", "bad") + assertErr("search call", &wikiCoverageCaller{errors: map[string][]error{"wiki/search_wikiSpaces": {backend}}}, "+space-search", "--query", "x") + assertErr("search collection", &wikiCoverageCaller{responses: map[string][]string{"wiki/search_wikiSpaces": {`{"success":true}`}}}, "+space-search", "--query", "x") + assertErr("get call", &wikiCoverageCaller{errors: map[string][]error{"wiki/get_wikiSpace": {backend}}}, "+space-get", "--workspace", "w") + assertErr("get object", &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"success":true}`}}}, "+space-get", "--workspace", "w") + caller := &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"workspaceId":"w","name":"Docs"}`}}} + if out, err := runWikiCoverageCLI(t, caller, "+space-get", "--workspace", "w"); err != nil || out["workspaceId"] != "w" { + t.Fatalf("space get output=%#v err=%v", out, err) + } + + assertErr("create write call", &wikiCoverageCaller{errors: map[string][]error{"wiki/create_wikiSpace": {backend}}}, "+space-create", "--name", "Docs") + assertErr("create terminal", &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"result":{"workspaceId":"w"}}`}}}, "+space-create", "--name", "Docs") + assertErr("create id", &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"success":true}`}}}, "+space-create", "--name", "Docs") + assertErr("create readback call", &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"success":true,"workspaceId":"w"}`}}, errors: map[string][]error{"wiki/get_wikiSpace": {backend}}}, "+space-create", "--name", "Docs") + assertErr("create readback object", &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"success":true,"workspaceId":"w"}`}, "wiki/get_wikiSpace": {`{"success":true}`}}}, "+space-create", "--name", "Docs") + assertErr("create readback mismatch", &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"success":true,"workspaceId":"w"}`}, "wiki/get_wikiSpace": {`{"workspaceId":"other"}`}}}, "+space-create", "--name", "Docs") + spaceMismatch := &wikiCoverageCaller{responses: map[string][]string{"wiki/create_wikiSpace": {`{"success":true,"result":{"workspaceId":"w"}}`}, "wiki/get_wikiSpace": {`{"success":true,"data":{"workspaceId":"other"}}`}}} + if _, err := runWikiCoverageCLI(t, spaceMismatch, "+space-create", "--name", "Docs"); err == nil || !strings.Contains(err.Error(), "不一致") { + t.Fatalf("space create mismatch error=%v calls=%#v", err, spaceMismatch.calls) + } + + assertErr("delete preflight call", &wikiCoverageCaller{errors: map[string][]error{"wiki/get_wikiSpace": {backend}}}, "+delete-space", "--workspace", "w", "--yes") + assertErr("delete preflight object", &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"success":true}`}}}, "+delete-space", "--workspace", "w", "--yes") + assertErr("delete write call", &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"workspaceId":"w"}`}}, errors: map[string][]error{"wiki/delete_wikiSpace": {backend}}}, "+delete-space", "--workspace", "w", "--yes") + assertErr("delete terminal", &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"workspaceId":"w"}`}, "wiki/delete_wikiSpace": {`{"result":{}}`}}}, "+delete-space", "--workspace", "w", "--yes") + delWrite := &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"success":true,"result":{"workspaceId":"w"}}`}}, errors: map[string][]error{"wiki/delete_wikiSpace": {backend}}} + if _, err := runWikiCoverageCLI(t, delWrite, "+delete-space", "--workspace", "w", "--yes"); err == nil || !strings.Contains(err.Error(), "backend failed") { + t.Fatalf("delete write error=%v calls=%#v", err, delWrite.calls) + } + delTerminal := &wikiCoverageCaller{responses: map[string][]string{"wiki/get_wikiSpace": {`{"success":true,"result":{"workspaceId":"w"}}`}, "wiki/delete_wikiSpace": {`{"result":{}}`}}} + if _, err := runWikiCoverageCLI(t, delTerminal, "+delete-space", "--workspace", "w", "--yes"); err == nil || !strings.Contains(err.Error(), "success=true") { + t.Fatalf("delete terminal error=%v calls=%#v", err, delTerminal.calls) + } + + assertErr("member list call", &wikiCoverageCaller{errors: map[string][]error{"wiki/list_member": {backend}}}, "+member-list", "--workspace", "w") + assertErr("member list collection", &wikiCoverageCaller{responses: map[string][]string{"wiki/list_member": {`{"success":true}`}}}, "+member-list", "--workspace", "w") + assertErr("member write call", &wikiCoverageCaller{errors: map[string][]error{"wiki/add_member": {backend}}}, "+member-add", "--workspace", "w", "--users", "u", "--role", "READER") +} + +func TestCrossPlatformCoverageWikiNodeFailureBranches(t *testing.T) { + assertErr := func(name string, caller *wikiCoverageCaller, args ...string) { + t.Helper() + t.Run(name, func(t *testing.T) { + if _, err := runWikiCoverageCLI(t, caller, args...); err == nil { + t.Fatalf("%s unexpectedly succeeded; calls=%#v", name, caller.calls) + } + }) + } + backend := errors.New("backend failed") + assertErr("list call", &wikiCoverageCaller{errors: map[string][]error{"doc/list_nodes": {backend}}}, "+node-list", "--workspace", "w") + assertErr("list collection", &wikiCoverageCaller{responses: map[string][]string{"doc/list_nodes": {`{"success":true}`}}}, "+node-list", "--workspace", "w") + assertErr("get call", &wikiCoverageCaller{errors: map[string][]error{"doc/get_document_info": {backend}}}, "+node-get", "--node", "n") + assertErr("get object", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"success":true}`}}}, "+node-get", "--node", "n") + assertErr("get id", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"name":"Doc"}`}}}, "+node-get", "--node", "n") + missingID := &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"success":true,"result":{"name":"Doc"}}`}}} + if _, err := runWikiCoverageCLI(t, missingID, "+node-get", "--node", "n"); err == nil || !strings.Contains(err.Error(), "nodeId") { + t.Fatalf("missing node id error=%v calls=%#v", err, missingID.calls) + } + assertErr("search call", &wikiCoverageCaller{errors: map[string][]error{"doc/search_documents": {backend}}}, "+node-search", "--workspace", "w", "--query", "x") + assertErr("search collection", &wikiCoverageCaller{responses: map[string][]string{"doc/search_documents": {`{"success":true}`}}}, "+node-search", "--workspace", "w", "--query", "x") + + createArgs := []string{"+node-create", "--workspace", "w", "--name", "Doc"} + assertErr("create write", &wikiCoverageCaller{errors: map[string][]error{"doc/create_file": {backend}}}, createArgs...) + assertErr("create terminal", &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"result":{"fileId":"n"}}`}}}, createArgs...) + assertErr("create id", &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"success":true}`}}}, createArgs...) + assertErr("create readback call", &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"success":true,"fileId":"n"}`}}, errors: map[string][]error{"doc/get_document_info": {backend}}}, createArgs...) + assertErr("create readback object", &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"success":true,"fileId":"n"}`}, "doc/get_document_info": {`{"success":true}`}}}, createArgs...) + assertErr("create mismatch", &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"success":true,"fileId":"n"}`}, "doc/get_document_info": {`{"nodeId":"other"}`}}}, createArgs...) + createMismatch := &wikiCoverageCaller{responses: map[string][]string{"doc/create_file": {`{"success":true,"result":{"fileId":"n"}}`}, "doc/get_document_info": {`{"success":true,"result":{"nodeId":"other"}}`}}} + if _, err := runWikiCoverageCLI(t, createMismatch, createArgs...); err == nil || !strings.Contains(err.Error(), "不一致") { + t.Fatalf("create mismatch error=%v calls=%#v", err, createMismatch.calls) + } + + copyArgs := []string{"+node-copy", "--workspace", "w", "--node", "source", "--yes"} + assertErr("copy write", &wikiCoverageCaller{errors: map[string][]error{"doc/copy_document": {backend}}}, copyArgs...) + assertErr("copy terminal", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"result":{"fileId":"n"}}`}}}, copyArgs...) + assertErr("copy id", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true}`}}}, copyArgs...) + assertErr("copy readback call", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true,"fileId":"n"}`}}, errors: map[string][]error{"doc/get_document_info": {backend}}}, copyArgs...) + assertErr("copy readback object", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true,"fileId":"n"}`}, "doc/get_document_info": {`{"success":true}`}}}, copyArgs...) + + moveArgs := []string{"+move", "--workspace", "target", "--node", "n", "--yes"} + assertErr("move preflight call", &wikiCoverageCaller{errors: map[string][]error{"doc/get_document_info": {backend}}}, moveArgs...) + assertErr("move preflight object", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"success":true}`}}}, moveArgs...) + assertErr("move write", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`}}, errors: map[string][]error{"doc/move_document": {backend}}}, moveArgs...) + assertErr("move terminal", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`}, "doc/move_document": {`{"result":{}}`}}}, moveArgs...) + assertErr("move readback call", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`}, "doc/move_document": {`{"success":true}`}}, errors: map[string][]error{"doc/get_document_info": {nil, backend}}}, moveArgs...) + assertErr("move readback object", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`, `{"success":true}`}, "doc/move_document": {`{"success":true}`}}}, moveArgs...) + assertErr("move id mismatch", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`, `{"nodeId":"other","workspaceId":"target"}`}, "doc/move_document": {`{"success":true}`}}}, moveArgs...) + assertErr("move workspace mismatch", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`, `{"nodeId":"n","workspaceId":"other"}`}, "doc/move_document": {`{"success":true}`}}}, moveArgs...) + assertErr("move folder mismatch", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"old"}`, `{"nodeId":"n","workspaceId":"target","folderId":"other"}`}, "doc/move_document": {`{"success":true}`}}}, append(moveArgs, "--folder", "f")...) + assertErr("drive move unchanged", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"same"}`, `{"nodeId":"n","workspaceId":"same"}`}, "doc/move_document": {`{"success":true}`}}}, "+move-to-drive", "--node", "n", "--yes") + + deleteArgs := []string{"+node-delete", "--workspace", "w", "--node", "n", "--yes"} + assertErr("delete preflight call", &wikiCoverageCaller{errors: map[string][]error{"doc/get_document_info": {backend}}}, deleteArgs...) + assertErr("delete preflight object", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"success":true}`}}}, deleteArgs...) + assertErr("delete workspace", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"other"}`}}}, deleteArgs...) + assertErr("delete write", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"w"}`}}, errors: map[string][]error{"doc/delete_document": {backend}}}, deleteArgs...) + assertErr("delete terminal", &wikiCoverageCaller{responses: map[string][]string{"doc/get_document_info": {`{"nodeId":"n","workspaceId":"w"}`}, "doc/delete_document": {`{"result":{}}`}}}, deleteArgs...) + assertErr("feed collection", &wikiCoverageCaller{responses: map[string][]string{"wiki/list_workspace_feeds": {`{"success":true}`}}}, "+feed-list", "--workspace", "w") +} + +func TestCrossPlatformCoverageWikiSecondPageFailures(t *testing.T) { + caller := &wikiCoverageCaller{ + responses: map[string][]string{"wiki/list_wikiSpaces": {`{"wikiSpaces":[],"hasMore":true,"nextCursor":"next"}`}}, + errors: map[string][]error{"wiki/list_wikiSpaces": {nil, errors.New("second page failed")}}, + } + if _, err := runWikiCoverageCLI(t, caller, "+space-list", "--page-all"); err == nil { + t.Fatal("second-page transport error was swallowed") + } + caller = &wikiCoverageCaller{responses: map[string][]string{"wiki/list_wikiSpaces": {`{"wikiSpaces":[],"hasMore":true,"nextCursor":"next"}`, `{"success":true}`}}} + if _, err := runWikiCoverageCLI(t, caller, "+space-list", "--page-all"); err == nil { + t.Fatal("second-page malformed collection was swallowed") + } +} diff --git a/scripts/dev/wiki-shortcut-e2e.py b/scripts/dev/wiki-shortcut-e2e.py index 84ecd391..33b14185 100755 --- a/scripts/dev/wiki-shortcut-e2e.py +++ b/scripts/dev/wiki-shortcut-e2e.py @@ -54,6 +54,13 @@ def check(label: str, condition: bool) -> None: print(f"PASS {label}") +def member_role(data: dict, user_id: str) -> str: + for member in data.get("members", []): + if member.get("id") == user_id: + return str(member.get("role") or "").upper() + return "" + + def main() -> int: if not DWS.exists(): raise E2EFailure("build ./dws first with make build") @@ -142,12 +149,18 @@ def main() -> int: check("member-list", members.get("count", 0) >= 1 and isinstance(members.get("members"), list)) added = invoke(["+member-add", "--workspace", workspace, "--users", MEMBER_ID, "--role", "READER"]) member_added = True - check("member-add-readback", added.get("success") is True and added.get("verifiedBy") == "member_list_readback") + check("member-add-terminal", added.get("success") is True and added.get("verifiedBy") == "write_terminal_success") + after_add = invoke(["+member-list", "--workspace", workspace, "--limit", "50"]) + check("member-add-fixture-readback", after_add.get("truncated") is not True and member_role(after_add, MEMBER_ID) == "READER") updated = invoke(["+member-update", "--workspace", workspace, "--users", MEMBER_ID, "--role", "EDITOR"]) - check("member-update-readback", updated.get("success") is True and updated.get("verifiedBy") == "member_list_readback") + check("member-update-terminal", updated.get("success") is True and updated.get("verifiedBy") == "write_terminal_success") + after_update = invoke(["+member-list", "--workspace", workspace, "--limit", "50"]) + check("member-update-fixture-readback", after_update.get("truncated") is not True and member_role(after_update, MEMBER_ID) == "EDITOR") removed = invoke(["+member-remove", "--workspace", workspace, "--users", MEMBER_ID]) member_added = False - check("member-remove-readback", removed.get("success") is True and removed.get("verifiedBy") == "member_list_readback") + check("member-remove-terminal", removed.get("success") is True and removed.get("verifiedBy") == "write_terminal_success") + after_remove = invoke(["+member-list", "--workspace", workspace, "--limit", "50"]) + check("member-remove-fixture-readback", after_remove.get("truncated") is not True and member_role(after_remove, MEMBER_ID) == "") feeds = invoke(["+feed-list", "--workspace", workspace, "--limit", "10"]) check("feed-list", isinstance(feeds.get("feeds"), list)) From 63a89e68fa76886493bba1cb35d16c9438d4538e Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 16:13:56 +0800 Subject: [PATCH 126/250] test(wiki): lock confirmation before remote calls --- .../shortcut/wiki/workflow_coverage_test.go | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/internal/shortcut/wiki/workflow_coverage_test.go b/internal/shortcut/wiki/workflow_coverage_test.go index a1d2a8b0..e068f38f 100644 --- a/internal/shortcut/wiki/workflow_coverage_test.go +++ b/internal/shortcut/wiki/workflow_coverage_test.go @@ -12,6 +12,7 @@ import ( "strings" "testing" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" @@ -71,6 +72,7 @@ func runWikiCoverageCLI(t *testing.T, caller *wikiCoverageCaller, args ...string ctx, _ := output.WithResultStore(context.Background()) root.SetContext(ctx) root.AddCommand(shortcut.Commands()...) + root.SetIn(strings.NewReader("")) stdout := &bytes.Buffer{} root.SetOut(stdout) root.SetErr(&bytes.Buffer{}) @@ -284,6 +286,31 @@ func TestCrossPlatformCoverageWikiReadWorkflows(t *testing.T) { } func TestCrossPlatformCoverageWikiWriteWorkflows(t *testing.T) { + t.Run("confirmation gates precede every remote call", func(t *testing.T) { + for _, tc := range []struct { + name string + args []string + }{ + {name: "delete space", args: []string{"+delete-space", "--workspace", "w"}}, + {name: "copy node", args: []string{"+node-copy", "--workspace", "w", "--node", "source"}}, + {name: "move node", args: []string{"+move", "--workspace", "target", "--node", "n"}}, + {name: "move node to drive", args: []string{"+move-to-drive", "--node", "n"}}, + {name: "delete node", args: []string{"+node-delete", "--workspace", "w", "--node", "n"}}, + } { + t.Run(tc.name, func(t *testing.T) { + caller := &wikiCoverageCaller{} + _, err := runWikiCoverageCLI(t, caller, tc.args...) + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "confirmation_required" { + t.Fatalf("unconfirmed error = %#v, want confirmation_required", err) + } + if len(caller.calls) != 0 { + t.Fatalf("unconfirmed shortcut reached MCP: %#v", caller.calls) + } + }) + } + }) + t.Run("node create dry and verified", func(t *testing.T) { dry := &wikiCoverageCaller{} out, err := runWikiCoverageCLI(t, dry, "+node-create", "--workspace", "w", "--folder", "f", "--name", "Doc", "--type", "adoc", "--dry-run") From d4daf9525cafa7fdd1fef834ae47b347c02ba617 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 17:11:44 +0800 Subject: [PATCH 127/250] fix(wiki): verify copied node identity --- internal/shortcut/wiki/nodes.go | 3 +++ internal/shortcut/wiki/workflow_coverage_test.go | 4 ++++ 2 files changed, 7 insertions(+) diff --git a/internal/shortcut/wiki/nodes.go b/internal/shortcut/wiki/nodes.go index c78cc6b8..3c95d2b9 100644 --- a/internal/shortcut/wiki/nodes.go +++ b/internal/shortcut/wiki/nodes.go @@ -136,6 +136,9 @@ var NodeCopy = writeShortcut("+node-copy", "复制知识库节点并读回验证 if err != nil { return err } + if firstWikiString(verified, "nodeId", "id", "fileId") != id { + return wikiResponseError("doc/copy_document", "readback_id_mismatch", "复制后读回节点 ID 不一致") + } return rt.Output(map[string]any{"success": true, "sourceNodeId": rt.Str("node"), "nodeId": id, "copy": verified}) }) diff --git a/internal/shortcut/wiki/workflow_coverage_test.go b/internal/shortcut/wiki/workflow_coverage_test.go index e068f38f..ad7f5d8b 100644 --- a/internal/shortcut/wiki/workflow_coverage_test.go +++ b/internal/shortcut/wiki/workflow_coverage_test.go @@ -628,6 +628,10 @@ func TestCrossPlatformCoverageWikiNodeFailureBranches(t *testing.T) { assertErr("copy id", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true}`}}}, copyArgs...) assertErr("copy readback call", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true,"fileId":"n"}`}}, errors: map[string][]error{"doc/get_document_info": {backend}}}, copyArgs...) assertErr("copy readback object", &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true,"fileId":"n"}`}, "doc/get_document_info": {`{"success":true}`}}}, copyArgs...) + copyMismatch := &wikiCoverageCaller{responses: map[string][]string{"doc/copy_document": {`{"success":true,"result":{"fileId":"n"}}`}, "doc/get_document_info": {`{"success":true,"result":{"nodeId":"other"}}`}}} + if _, err := runWikiCoverageCLI(t, copyMismatch, copyArgs...); err == nil || !strings.Contains(err.Error(), "不一致") { + t.Fatalf("copy mismatch error=%v calls=%#v", err, copyMismatch.calls) + } moveArgs := []string{"+move", "--workspace", "target", "--node", "n", "--yes"} assertErr("move preflight call", &wikiCoverageCaller{errors: map[string][]error{"doc/get_document_info": {backend}}}, moveArgs...) From 9ef2a4e652e0e082d022678768c341760f05e418 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 22:15:25 +0800 Subject: [PATCH 128/250] fix(wiki): publish executable shortcut examples --- internal/app/schema_shortcut_contract_test.go | 49 +++++++++++++++++++ internal/shortcut/wiki/nodes.go | 18 +++---- internal/shortcut/wiki/wiki.go | 30 ++++++------ 3 files changed, 73 insertions(+), 24 deletions(-) diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index f942cb97..ff507975 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -154,6 +154,55 @@ func TestDeliveryWikiSpaceSearchPreservesHistoricalParameterProperties(t *testin } } +func TestAllShortcutsWikiSchemaExamplesIncludeRequiredParameters(t *testing.T) { + tools := deliverySchemaAllToolsForHelpFlagTest(t, NewRootCommand()) + checked := 0 + for _, declared := range shortcut.All() { + if declared.Service != "wiki" || declared.UserDefined || !shortcut.InPublicCatalog(declared.Service, declared.Command) { + continue + } + checked++ + canonical := shortcutSchemaCanonical(declared) + tool := tools[canonical] + if tool == nil { + t.Fatalf("delivery schema --all is missing %s", canonical) + } + examples := schemaContractStringSlice(tool["examples"]) + if len(examples) == 0 { + t.Fatalf("%s has no delivered examples", canonical) + } + for _, example := range examples { + argv, err := cli.ParseAgentExampleArgv(example) + if err != nil { + t.Fatalf("%s example %q is not valid argv: %v", canonical, example, err) + } + for _, flag := range declared.Flags { + if !flag.Required { + continue + } + names := append([]string{flag.Name}, flag.Aliases...) + if !schemaExampleHasLongFlag(argv, names...) { + t.Errorf("%s example %q is missing required --%s", canonical, example, flag.Name) + } + } + } + } + if checked != 20 { + t.Fatalf("checked Wiki shortcut examples = %d, want 20", checked) + } +} + +func schemaExampleHasLongFlag(argv []string, names ...string) bool { + for _, argument := range argv { + for _, name := range names { + if argument == "--"+name || strings.HasPrefix(argument, "--"+name+"=") { + return true + } + } + } + return false +} + func assertSchemaSummarySafety( t testing.TB, summaries map[string]map[string]any, diff --git a/internal/shortcut/wiki/nodes.go b/internal/shortcut/wiki/nodes.go index 3c95d2b9..aa893c87 100644 --- a/internal/shortcut/wiki/nodes.go +++ b/internal/shortcut/wiki/nodes.go @@ -11,7 +11,7 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) -var NodeList = readShortcut("+node-list", "严格分页列出知识库节点", "浏览知识库根目录或指定文件夹；只有显式 nodes:[] 才表示空目录，并完整保留 nextCursor/hasMore。", "nodes", []shortcut.Flag{ +var NodeList = readShortcut("+node-list", "严格分页列出知识库节点", "浏览知识库根目录或指定文件夹；只有显式 nodes:[] 才表示空目录，并完整保留 nextCursor/hasMore。", "nodes", "dws wiki +node-list --workspace --format json", []shortcut.Flag{ {Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "父节点 ID"}, {Name: "limit", Type: shortcut.FlagInt, Default: "50", Desc: "每页数量 1-50"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, }, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "folder", Property: "folderId"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { items, page, err := collectWikiPages(rt, "wiki/list_nodes", rt.Int("limit"), []string{"nodes", "items", "list"}, func(cursor string, size int) (map[string]any, error) { @@ -37,7 +37,7 @@ func nodeAliases() map[string][]string { return map[string][]string{"nodeId": {"nodeId", "id", "dentryUuid", "fileId"}, "name": {"name", "title", "nodeName", "fileName"}, "type": {"type", "nodeType", "docType", "fileType"}, "contentType": {"contentType"}, "folderId": {"folderId", "parentId"}, "workspaceId": {"workspaceId", "spaceId"}, "url": {"docUrl", "url", "webUrl"}} } -var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知节点 ID 或在线文档 URL 时读取元数据，并在节点信息之外统一返回文档/文件属性。", "", []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID 或 URL"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { +var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知节点 ID 或在线文档 URL 时读取元数据，并在节点信息之外统一返回文档/文件属性。", "", "dws wiki +node-get --node --format json", []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID 或 URL"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { data, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) if err != nil { return err @@ -52,7 +52,7 @@ var NodeGet = readShortcut("+node-get", "获取知识库节点详情", "已知 return rt.Output(object) }) -var NodeSearch = readShortcut("+node-search", "严格搜索知识库节点", "在指定知识库内按关键词和扩展名搜索节点；零命中必须来自显式 documents:[]。", "nodes", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "关键词"}, {Name: "extensions", Type: shortcut.FlagStringSlice, Desc: "扩展名过滤"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-30"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceIds"}, {Name: "query", Property: "keyword"}, {Name: "extensions", Property: "extensions"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { +var NodeSearch = readShortcut("+node-search", "严格搜索知识库节点", "在指定知识库内按关键词和扩展名搜索节点；零命中必须来自显式 documents:[]。", "nodes", "dws wiki +node-search --workspace --query \"方案\" --format json", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "关键词"}, {Name: "extensions", Type: shortcut.FlagStringSlice, Desc: "扩展名过滤"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-30"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceIds"}, {Name: "query", Property: "keyword"}, {Name: "extensions", Property: "extensions"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { params := map[string]any{"workspaceIds": []string{rt.Str("workspace")}, "keyword": rt.Str("query"), "pageSize": rt.Int("limit")} if rt.Changed("extensions") { params["extensions"] = rt.StrSlice("extensions") @@ -74,7 +74,7 @@ var NodeSearch = readShortcut("+node-search", "严格搜索知识库节点", " return rt.Output(out) }) -var NodeCreate = writeShortcut("+node-create", "创建知识库节点并读回验证", "在知识库根目录或文件夹中创建文档、表格、白板、脑图或文件夹；取得 nodeId 并读回后才成功。", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "name", Type: shortcut.FlagString, Required: true, Desc: "节点名称"}, {Name: "type", Type: shortcut.FlagString, Default: "adoc", Desc: "节点类型", Enum: []string{"adoc", "axls", "able", "appt", "adraw", "amind", "folder"}}, {Name: "folder", Type: shortcut.FlagString, Desc: "父文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "name", Property: "name"}, {Name: "type", Property: "type"}, {Name: "folder", Property: "folderId"}}, func(rt *shortcut.RuntimeContext) error { +var NodeCreate = writeShortcut("+node-create", "创建知识库节点并读回验证", "在知识库根目录或文件夹中创建文档、表格、白板、脑图或文件夹；取得 nodeId 并读回后才成功。", "dws wiki +node-create --workspace --name \"新文档\" --format json", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID"}, {Name: "name", Type: shortcut.FlagString, Required: true, Desc: "节点名称"}, {Name: "type", Type: shortcut.FlagString, Default: "adoc", Desc: "节点类型", Enum: []string{"adoc", "axls", "able", "appt", "adraw", "amind", "folder"}}, {Name: "folder", Type: shortcut.FlagString, Desc: "父文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "name", Property: "name"}, {Name: "type", Property: "type"}, {Name: "folder", Property: "folderId"}}, func(rt *shortcut.RuntimeContext) error { params := map[string]any{"workspaceId": rt.Str("workspace"), "name": rt.Str("name"), "type": rt.Str("type")} if rt.Changed("folder") { params["folderId"] = rt.Str("folder") @@ -108,7 +108,7 @@ var NodeCreate = writeShortcut("+node-create", "创建知识库节点并读回 return rt.Output(map[string]any{"success": true, "nodeId": id, "node": verified}) }) -var NodeCopy = writeShortcut("+node-copy", "复制知识库节点并读回验证", "复制现有在线节点到目标知识库/文件夹；高风险确认后要求新 nodeId 并读取副本元数据。", shortcut.RiskHighWrite, contract.SafetySpec{Effect: "write", Risk: "high", Confirmation: "user_required", Idempotency: "non_idempotent"}, []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "源节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { +var NodeCopy = writeShortcut("+node-copy", "复制知识库节点并读回验证", "复制现有在线节点到目标知识库/文件夹；高风险确认后要求新 nodeId 并读取副本元数据。", "dws wiki +node-copy --workspace --node --format json", shortcut.RiskHighWrite, contract.SafetySpec{Effect: "write", Risk: "high", Confirmation: "user_required", Idempotency: "non_idempotent"}, []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "源节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { params := map[string]any{"workspaceId": rt.Str("workspace"), "nodeId": rt.Str("node")} if rt.Changed("folder") { params["targetFolderId"] = rt.Str("folder") @@ -194,11 +194,11 @@ func executeMove(rt *shortcut.RuntimeContext, toDrive bool) error { return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "node": verified}) } -var Move = writeShortcut("+move", "移动节点到知识库并读回验证", "将 Wiki 节点或我的文档在线节点移动到目标知识库/文件夹；同一入口覆盖库内移动与在线文档入库场景。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, false) }) +var Move = writeShortcut("+move", "移动节点到知识库并读回验证", "将 Wiki 节点或我的文档在线节点移动到目标知识库/文件夹；同一入口覆盖库内移动与在线文档入库场景。", "dws wiki +move --workspace --node --format json", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "目标知识库 ID"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "目标文件夹 ID"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, false) }) -var MoveToDrive = writeShortcut("+move-to-drive", "移动 Wiki 节点到我的文档", "将 Wiki 在线节点同步移动到我的文档或指定文件夹，并以元数据读回证明任务完成。", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "Wiki 节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "我的文档目标文件夹 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, true) }) +var MoveToDrive = writeShortcut("+move-to-drive", "移动 Wiki 节点到我的文档", "将 Wiki 在线节点同步移动到我的文档或指定文件夹，并以元数据读回证明任务完成。", "dws wiki +move-to-drive --node --format json", shortcut.RiskWrite, wikiWriteSafety(true), []shortcut.Flag{{Name: "node", Type: shortcut.FlagString, Required: true, Desc: "Wiki 节点 ID"}, {Name: "folder", Type: shortcut.FlagString, Desc: "我的文档目标文件夹 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}, {Name: "folder", Property: "targetFolderId"}}, func(rt *shortcut.RuntimeContext) error { return executeMove(rt, true) }) -var NodeDelete = writeShortcut("+node-delete", "删除知识库节点", "明确确认后将节点移入回收站；先读取目标，且删除响应必须提供 success=true 终态证据。", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID，用于确认影响范围"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { +var NodeDelete = writeShortcut("+node-delete", "删除知识库节点", "明确确认后将节点移入回收站；先读取目标，且删除响应必须提供 success=true 终态证据。", "dws wiki +node-delete --workspace --node --format json", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID，用于确认影响范围"}, {Name: "node", Type: shortcut.FlagString, Required: true, Desc: "节点 ID"}}, []contract.ParamDecl{{Name: "node", Property: "nodeId"}}, func(rt *shortcut.RuntimeContext) error { preflight, err := rt.CallMCPData("doc", "get_document_info", map[string]any{"nodeId": rt.Str("node")}) if err != nil { return err @@ -223,7 +223,7 @@ var NodeDelete = writeShortcut("+node-delete", "删除知识库节点", "明确 return rt.Output(map[string]any{"success": true, "nodeId": rt.Str("node"), "deleted": true}) }) -var FeedList = readShortcut("+feed-list", "严格分页列出知识库动态", "查看谁在何时创建、更新或评论了知识库内容；严格验证 feeds 数组并保留游标。", "feeds", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-20"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}, {Name: "exclude-file", Type: shortcut.FlagBool, Desc: "排除普通文件动态"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "cursor", Property: "nextToken"}, {Name: "exclude-file", Property: "excludeFile"}}, func(rt *shortcut.RuntimeContext) error { +var FeedList = readShortcut("+feed-list", "严格分页列出知识库动态", "查看谁在何时创建、更新或评论了知识库内容；严格验证 feeds 数组并保留游标。", "feeds", "dws wiki +feed-list --workspace --format json", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量 1-20"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标"}, {Name: "exclude-file", Type: shortcut.FlagBool, Desc: "排除普通文件动态"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "cursor", Property: "nextToken"}, {Name: "exclude-file", Property: "excludeFile"}}, func(rt *shortcut.RuntimeContext) error { items, page, err := collectWikiPages(rt, "wiki/list_workspace_feeds", rt.Int("limit"), []string{"feeds", "items", "list"}, func(cursor string, size int) (map[string]any, error) { params := map[string]any{"workspaceId": rt.Str("workspace"), "maxResults": size} if cursor != "" { diff --git a/internal/shortcut/wiki/wiki.go b/internal/shortcut/wiki/wiki.go index 25104fdb..a6262aa1 100644 --- a/internal/shortcut/wiki/wiki.go +++ b/internal/shortcut/wiki/wiki.go @@ -16,19 +16,19 @@ import ( var collectionAvoid = []string{"需要原始 MCP 响应或未公开底层参数时改用对应原子命令；缺失业务数组不是合法空结果"} -func readShortcut(command, description, intent, collection string, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { +func readShortcut(command, description, intent, collection, example string, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { result := wikiObjectResult(description) if collection != "" { result = wikiCollectionResult(collection, description) } - return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: shortcut.RiskRead, Safety: wikiReadSafety(), Contract: wikiContract(command, description, intent, collectionAvoid, []string{"dws wiki " + command + " --format json"}, result, nil, params...), Flags: flags, Execute: execute} + return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: shortcut.RiskRead, Safety: wikiReadSafety(), Contract: wikiContract(command, description, intent, collectionAvoid, []string{example}, result, nil, params...), Flags: flags, Execute: execute} } -func writeShortcut(command, description, intent string, risk shortcut.Risk, safety contract.SafetySpec, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { - return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: risk, Safety: safety, Contract: wikiContract(command, description, intent, []string{"只需读取或影响范围未确认时不要执行写操作"}, []string{"dws wiki " + command + " --format json"}, wikiObjectResult(description), nil, params...), Flags: flags, Execute: execute} +func writeShortcut(command, description, intent, example string, risk shortcut.Risk, safety contract.SafetySpec, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { + return shortcut.Shortcut{OutputRollout: output.RolloutUnifiedActive, Service: "wiki", Command: command, Product: "wiki", Description: description, Intent: intent, Risk: risk, Safety: safety, Contract: wikiContract(command, description, intent, []string{"只需读取或影响范围未确认时不要执行写操作"}, []string{example}, wikiObjectResult(description), nil, params...), Flags: flags, Execute: execute} } -var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏览有权访问的组织或个人知识库，并保留服务端分页证据；只有显式 wikiSpaces:[] 才是空结果。", "spaces", []shortcut.Flag{ +var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏览有权访问的组织或个人知识库，并保留服务端分页证据；只有显式 wikiSpaces:[] 才是空结果。", "spaces", "dws wiki +space-list --limit 20 --format json", []shortcut.Flag{ {Name: "type", Type: shortcut.FlagString, Default: "orgWikiSpace", Desc: "知识库类型", Enum: []string{"orgWikiSpace", "myWikiSpace"}}, {Name: "limit", Type: shortcut.FlagString, Desc: "每页数量 1-50（默认 20）"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标", Aliases: []string{"page-token"}, AliasesVisible: true}, }, []contract.ParamDecl{{Name: "type", Property: "wikiSpaceType"}, {Name: "limit", Property: "pageSize"}, {Name: "cursor", Property: "pageToken"}}, func(rt *shortcut.RuntimeContext) error { @@ -52,7 +52,7 @@ var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏 return rt.Output(out) }) -var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", []shortcut.Flag{ +var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", "dws wiki +space-search --query \"产品文档\" --format json", []shortcut.Flag{ {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词"}, {Name: "limit", Type: shortcut.FlagString, Desc: "返回数量 1-20（默认 10）"}, }, []contract.ParamDecl{{Name: "query", Property: "query"}, {Name: "limit", Property: "limit"}}, func(rt *shortcut.RuntimeContext) error { pageSize, err := wikiStringInt(rt, "limit", 10, 1, 20) @@ -73,7 +73,7 @@ var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名 return rt.Output(out) }) -var SpaceGet = readShortcut("+space-get", "获取知识库详情", "已知 workspace ID 或知识库 URL 时读取并验证空间详情。", "", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { +var SpaceGet = readShortcut("+space-get", "获取知识库详情", "已知 workspace ID 或知识库 URL 时读取并验证空间详情。", "", "dws wiki +space-get --workspace --format json", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { data, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) if err != nil { return err @@ -88,7 +88,7 @@ var SpaceGet = readShortcut("+space-get", "获取知识库详情", "已知 works return rt.Output(object) }) -var SpaceCreate = writeShortcut("+space-create", "创建知识库并读回验证", "创建新的知识库容器；必须取得 workspaceId 并通过详情读回后才报告成功。", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "name", Type: shortcut.FlagString, Required: true, Desc: "知识库名称，不超过 32 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "desc", Type: shortcut.FlagString, Desc: "知识库描述，不超过 500 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "icon", Type: shortcut.FlagString, Desc: "图标标识"}}, []contract.ParamDecl{{Name: "name", Property: "name"}, {Name: "desc", Property: "description"}, {Name: "icon", Property: "icon"}}, func(rt *shortcut.RuntimeContext) error { +var SpaceCreate = writeShortcut("+space-create", "创建知识库并读回验证", "创建新的知识库容器；必须取得 workspaceId 并通过详情读回后才报告成功。", "dws wiki +space-create --name \"产品文档库\" --format json", shortcut.RiskWrite, wikiWriteSafety(false), []shortcut.Flag{{Name: "name", Type: shortcut.FlagString, Required: true, Desc: "知识库名称，不超过 32 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "desc", Type: shortcut.FlagString, Desc: "知识库描述，不超过 500 个字符。--name 不超过 32 个字符；--desc 不超过 500 个字符"}, {Name: "icon", Type: shortcut.FlagString, Desc: "图标标识"}}, []contract.ParamDecl{{Name: "name", Property: "name"}, {Name: "desc", Property: "description"}, {Name: "icon", Property: "icon"}}, func(rt *shortcut.RuntimeContext) error { params := map[string]any{"name": rt.Str("name")} if rt.Changed("desc") { params["description"] = rt.Str("desc") @@ -125,7 +125,7 @@ var SpaceCreate = writeShortcut("+space-create", "创建知识库并读回验证 return rt.Output(map[string]any{"success": true, "workspaceId": id, "space": verified}) }) -var DeleteSpace = writeShortcut("+delete-space", "删除知识库", "用户明确确认后将整个知识库移入回收站；删除前读取目标，删除响应必须有 success=true。", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { +var DeleteSpace = writeShortcut("+delete-space", "删除知识库", "用户明确确认后将整个知识库移入回收站；删除前读取目标，删除响应必须有 success=true。", "dws wiki +delete-space --workspace --format json", shortcut.RiskHighWrite, wikiDeleteSafety(), []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { preflight, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) if err != nil { return err @@ -156,12 +156,12 @@ func memberFlags(withRole bool) []shortcut.Flag { return flags } -func memberWrite(command, tool, description, intent string, withRole bool) shortcut.Shortcut { +func memberWrite(command, tool, description, intent, example string, withRole bool) shortcut.Shortcut { params := []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "users", Property: "userIds"}} if withRole { params = append(params, contract.ParamDecl{Name: "role", Property: "roleId"}) } - return writeShortcut(command, description, intent, shortcut.RiskWrite, wikiWriteSafety(false), memberFlags(withRole), params, func(rt *shortcut.RuntimeContext) error { + return writeShortcut(command, description, intent, example, shortcut.RiskWrite, wikiWriteSafety(false), memberFlags(withRole), params, func(rt *shortcut.RuntimeContext) error { users := wikiStringSliceFirst(rt, "users", "user") if len(users) == 0 || len(users) > 30 { return fmt.Errorf("--users 必须包含 1-30 个 userId") @@ -193,11 +193,11 @@ func memberWrite(command, tool, description, intent string, withRole bool) short }) } -var MemberAdd = memberWrite("+member-add", "add_member", "添加知识库成员", "向知识库授予一个或多个用户容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", true) -var MemberUpdate = memberWrite("+member-update", "update_member", "更新知识库成员角色", "调整已有成员的知识库容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", true) -var MemberRemove = memberWrite("+member-remove", "remove_member", "移除知识库成员", "移除一个或多个用户的知识库容器级访问；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", false) +var MemberAdd = memberWrite("+member-add", "add_member", "添加知识库成员", "向知识库授予一个或多个用户容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", "dws wiki +member-add --workspace --users --role READER --format json", true) +var MemberUpdate = memberWrite("+member-update", "update_member", "更新知识库成员角色", "调整已有成员的知识库容器级角色；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", "dws wiki +member-update --workspace --users --role EDITOR --format json", true) +var MemberRemove = memberWrite("+member-remove", "remove_member", "移除知识库成员", "移除一个或多个用户的知识库容器级访问；仅以写接口 success=true 作为终态证据，并明确成员列表无法完成精确读回。", "dws wiki +member-remove --workspace --users --format json", false) -var MemberList = readShortcut("+member-list", "严格列出知识库成员", "列出知识库成员及角色；后端不提供可续游标且单次真实上限为 50，不伪造 page-all。", "members", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "30", Desc: "返回上限 1-50"}, {Name: "filter-role", Type: shortcut.FlagStringSlice, Desc: "角色过滤"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "filter-role", Property: "filterRoleIds"}}, func(rt *shortcut.RuntimeContext) error { +var MemberList = readShortcut("+member-list", "严格列出知识库成员", "列出知识库成员及角色；后端不提供可续游标且单次真实上限为 50，不伪造 page-all。", "members", "dws wiki +member-list --workspace --format json", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}, {Name: "limit", Type: shortcut.FlagInt, Default: "30", Desc: "返回上限 1-50"}, {Name: "filter-role", Type: shortcut.FlagStringSlice, Desc: "角色过滤"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}, {Name: "limit", Property: "maxResults"}, {Name: "filter-role", Property: "filterRoleIds"}}, func(rt *shortcut.RuntimeContext) error { if rt.Int("limit") < 1 || rt.Int("limit") > 50 { return fmt.Errorf("--limit 必须在 1-50 之间；服务端不支持超过 50 或游标续页") } From 247926d0fa170e9f21764ebdaa2d345e73fb81d3 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 23:02:59 +0800 Subject: [PATCH 129/250] fix(wiki): enforce auto-page item cap --- internal/shortcut/wiki/common.go | 9 +++++- .../shortcut/wiki/workflow_coverage_test.go | 28 +++++++++++++++++-- 2 files changed, 33 insertions(+), 4 deletions(-) diff --git a/internal/shortcut/wiki/common.go b/internal/shortcut/wiki/common.go index 708aa21a..60250a91 100644 --- a/internal/shortcut/wiki/common.go +++ b/internal/shortcut/wiki/common.go @@ -263,9 +263,16 @@ func collectWikiPages(rt *shortcut.RuntimeContext, operation string, pageSize in if err != nil { return nil, nil, err } + maxItems := rt.Int("max-items") + if maxItems > 0 { + remaining := maxItems - len(all) + if len(items) > remaining { + items = items[:remaining] + } + } all = append(all, items...) lastPage = page - if maxItems := rt.Int("max-items"); maxItems > 0 && len(all) >= maxItems { + if maxItems > 0 && len(all) >= maxItems { lastPage["autoPageComplete"] = false lastPage["autoPageStopReason"] = "max_items" lastPage["pagesFetched"] = pageNumber diff --git a/internal/shortcut/wiki/workflow_coverage_test.go b/internal/shortcut/wiki/workflow_coverage_test.go index ad7f5d8b..aabc82b8 100644 --- a/internal/shortcut/wiki/workflow_coverage_test.go +++ b/internal/shortcut/wiki/workflow_coverage_test.go @@ -491,16 +491,38 @@ func TestCrossPlatformCoverageWikiPaginationFailureModes(t *testing.T) { } }) - t.Run("max items", func(t *testing.T) { + t.Run("max items trims first page", func(t *testing.T) { caller := &wikiCoverageCaller{responses: map[string][]string{ - "wiki/list_wikiSpaces": {`{"wikiSpaces":[{"workspaceId":"w1"}],"hasMore":true,"nextCursor":"next"}`}, + "wiki/list_wikiSpaces": {`{"wikiSpaces":[{"workspaceId":"w1"},{"workspaceId":"w2"}],"hasMore":true,"nextCursor":"next"}`}, }} out, err := runWikiCoverageCLI(t, caller, "+space-list", "--limit", "2", "--page-all", "--max-items", "1") - if err != nil || out["autoPageStopReason"] != "max_items" { + spaces, ok := out["spaces"].([]any) + if err != nil || !ok || out["count"] != float64(1) || len(spaces) != 1 || out["autoPageStopReason"] != "max_items" { t.Fatalf("max-items output=%#v err=%v", out, err) } }) + t.Run("max items trims remaining page", func(t *testing.T) { + caller := &wikiCoverageCaller{responses: map[string][]string{ + "wiki/list_wikiSpaces": { + `{"wikiSpaces":[{"workspaceId":"w1"},{"workspaceId":"w2"}],"hasMore":true,"nextCursor":"next"}`, + `{"wikiSpaces":[{"workspaceId":"w3"},{"workspaceId":"w4"}],"hasMore":false}`, + }, + }} + out, err := runWikiCoverageCLI(t, caller, "+space-list", "--limit", "2", "--page-all", "--page-limit", "2", "--max-items", "3") + spaces, ok := out["spaces"].([]any) + if err != nil || !ok || out["count"] != float64(3) || len(spaces) != 3 || out["autoPageStopReason"] != "max_items" { + t.Fatalf("max-items output=%#v err=%v calls=%#v", out, err, caller.calls) + } + if len(caller.calls) != 2 || caller.calls[1].args["pageSize"] != 1 { + t.Fatalf("remaining page request=%#v, want pageSize=1", caller.calls) + } + third, ok := spaces[2].(map[string]any) + if !ok || third["workspaceId"] != "w3" { + t.Fatalf("trimmed spaces=%#v, want w3 as final item", spaces) + } + }) + cases := []struct { name string response string From 600404abd0681d822cba8ed61687e7c6921f1826 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 23:32:43 +0800 Subject: [PATCH 130/250] fix(wiki): require interactive e2e confirmation --- docs/wiki-shortcut-business-review.html | 2 +- scripts/dev/wiki-shortcut-e2e.py | 44 +++++++++++++++++++------ test/scripts/wiki_shortcut_e2e_test.go | 43 ++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 11 deletions(-) create mode 100644 test/scripts/wiki_shortcut_e2e_test.go diff --git a/docs/wiki-shortcut-business-review.html b/docs/wiki-shortcut-business-review.html index ce3437cc..edb81799 100644 --- a/docs/wiki-shortcut-business-review.html +++ b/docs/wiki-shortcut-business-review.html @@ -101,7 +101,7 @@
分组Shortcut实际业务断言状态
空间+space-list真实 count、hasMore、nextCursor；自动翻页返回两页结果。PASS
空间+space-createsuccess=true、workspaceId 非空、详情读回一致。PASS
空间+delete-space目标预读、确认、success=true；兼容别名执行 finally 清理。PASS
成员+member-list真实 owner 条目与显式 members 数组，limit=50。PASS
成员+member-add真实内部成员添加后在名单中出现且角色为 READER。PASS
成员+member-update同一成员读回角色变为 EDITOR。PASS
成员+member-remove移除后名单中不再存在该 userId。PASS
成员+member-add命令只报告写终态；一次性小规模空间另行确认名单完整且角色为 READER。PASS
成员+member-update命令只报告写终态；一次性小规模空间另行确认角色变为 EDITOR。PASS
成员+member-remove命令只报告写终态；一次性小规模空间另行确认完整名单中不存在该 userId。PASS
节点+node-list空库返回真实 nodes:[]；有数据时验证游标与自动翻页。PASS
节点+node-get读回 nodeId 与请求一致。PASS
节点+node-search等待索引后按标题命中真实 nodeId。PASS
节点+wiki-new-doc按唯一空间名创建，nodeId 与文档详情读回一致。PASS
动态+feed-list创建/移动操作后返回真实 feeds 数组，缺字段不会被接受。PASS
-

可复跑入口：make build 后设置临时 DWS_WIKI_E2E_MEMBER_ID，运行 ./scripts/dev/wiki-shortcut-e2e.py。脚本只输出能力标签，不输出业务对象。

+

可复跑入口：make build 后设置临时 DWS_WIKI_E2E_MEMBER_ID，在交互终端运行 ./scripts/dev/wiki-shortcut-e2e.py。脚本只输出能力标签，不输出业务对象；受保护操作及最终清理均由命令逐项获取终端确认，非交互环境会在创建测试数据前拒绝运行。

diff --git a/scripts/dev/wiki-shortcut-e2e.py b/scripts/dev/wiki-shortcut-e2e.py index 33b14185..454ed3e4 100755 --- a/scripts/dev/wiki-shortcut-e2e.py +++ b/scripts/dev/wiki-shortcut-e2e.py @@ -1,10 +1,11 @@ #!/usr/bin/env python3 -"""Run destructive, real-data Wiki Shortcut verification on a disposable space. +"""Run interactive, real-data Wiki Shortcut verification on a disposable space. Requires an authenticated `dws` session. Set DWS_WIKI_E2E_MEMBER_ID to a real internal user ID that may be granted temporary access to the empty fixture. The script prints capability labels only; business IDs, names, URLs, and raw -responses remain in memory. The disposable Wiki space is deleted in `finally`. +responses remain in memory. Commands that require confirmation use the normal +`dws` terminal prompt, including the disposable-space cleanup in `finally`. """ from __future__ import annotations @@ -26,11 +27,15 @@ class E2EFailure(RuntimeError): pass -def invoke(args: list[str]) -> dict: +def invoke(args: list[str], *, require_confirmation: bool = False) -> dict: process = subprocess.run( [str(DWS), "wiki", *args, "--format", "json"], cwd=ROOT, - capture_output=True, + stdout=subprocess.PIPE, + # Confirmation prompts are written to stderr. Keep that stream on the + # terminal for guarded operations so dws itself obtains the user's + # answer; ordinary calls stay quiet and redact raw backend errors. + stderr=None if require_confirmation else subprocess.PIPE, text=True, check=False, ) @@ -62,6 +67,10 @@ def member_role(data: dict, user_id: str) -> str: def main() -> int: + if not sys.stdin.isatty() or not sys.stderr.isatty(): + raise E2EFailure( + "run in an interactive terminal; guarded operations require an explicit dws confirmation" + ) if not DWS.exists(): raise E2EFailure("build ./dws first with make build") if not MEMBER_ID: @@ -128,16 +137,25 @@ def main() -> int: time.sleep(2) check("node-search", search_ok) - copied = invoke(["+node-copy", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + copied = invoke( + ["+node-copy", "--workspace", workspace, "--folder", folder_id, "--node", node_id], + require_confirmation=True, + ) copy_id = str(copied.get("nodeId") or "") disposable_nodes.append(copy_id) check("node-copy-readback", bool(copy_id) and bool(copied.get("copy"))) - moved = invoke(["+move", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + moved = invoke( + ["+move", "--workspace", workspace, "--folder", folder_id, "--node", node_id], + require_confirmation=True, + ) check("move-readback", moved.get("node", {}).get("workspaceId") == workspace and moved.get("node", {}).get("folderId") == folder_id) - moved_out = invoke(["+move-to-drive", "--node", node_id, "--yes"]) + moved_out = invoke(["+move-to-drive", "--node", node_id], require_confirmation=True) check("move-to-drive-readback", moved_out.get("node", {}).get("workspaceId") != workspace) - moved_back = invoke(["+node-move", "--workspace", workspace, "--folder", folder_id, "--node", node_id, "--yes"]) + moved_back = invoke( + ["+node-move", "--workspace", workspace, "--folder", folder_id, "--node", node_id], + require_confirmation=True, + ) check("node-move-alias-readback", moved_back.get("node", {}).get("workspaceId") == workspace) named = invoke(["+wiki-new-doc", "--space", space_name, "--title", "E2E Name Resolved"]) @@ -167,7 +185,10 @@ def main() -> int: # Exercise high-risk delete before final whole-space cleanup. delete_target = disposable_nodes.pop() - deleted = invoke(["+node-delete", "--workspace", workspace, "--node", delete_target, "--yes"]) + deleted = invoke( + ["+node-delete", "--workspace", workspace, "--node", delete_target], + require_confirmation=True, + ) check("node-delete-terminal", deleted.get("success") is True and deleted.get("deleted") is True) return 0 finally: @@ -178,7 +199,10 @@ def main() -> int: except Exception: pass try: - deleted = invoke(["+space-delete", "--workspace", workspace, "--yes"]) + deleted = invoke( + ["+space-delete", "--workspace", workspace], + require_confirmation=True, + ) check("space-delete-alias-cleanup", deleted.get("success") is True and deleted.get("deleted") is True) except Exception as exc: print(f"CLEANUP FAILED: {exc}", file=sys.stderr) diff --git a/test/scripts/wiki_shortcut_e2e_test.go b/test/scripts/wiki_shortcut_e2e_test.go new file mode 100644 index 00000000..f60aacb9 --- /dev/null +++ b/test/scripts/wiki_shortcut_e2e_test.go @@ -0,0 +1,43 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package scripts_test + +import ( + "bytes" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" +) + +func TestWikiShortcutE2ERequiresInteractiveConfirmation(t *testing.T) { + script := filepath.Join("..", "..", "scripts", "dev", "wiki-shortcut-e2e.py") + source, err := os.ReadFile(script) + if err != nil { + t.Fatal(err) + } + if bytes.Contains(source, []byte("--yes")) { + t.Fatal("real-data Wiki E2E script must not embed confirmation bypass flags") + } + + python, err := exec.LookPath("python3") + if err != nil { + t.Skip("python3 is unavailable") + } + cmd := exec.Command(python, script) + cmd.Stdin = strings.NewReader("") + var stdout, stderr bytes.Buffer + cmd.Stdout = &stdout + cmd.Stderr = &stderr + if err := cmd.Run(); err == nil { + t.Fatal("non-interactive real-data E2E unexpectedly succeeded") + } + if !strings.Contains(stderr.String(), "run in an interactive terminal") { + t.Fatalf("non-interactive failure = %q, want explicit terminal requirement", stderr.String()) + } + if strings.Contains(stdout.String(), "PASS ") { + t.Fatalf("non-interactive E2E performed work before refusing: %q", stdout.String()) + } +} From d5eee82816134759c27eab3a716cbb808bd08ae6 Mon Sep 17 00:00:00 2001 From: Dennis Date: Sat, 15 Aug 2026 00:04:54 +0800 Subject: [PATCH 131/250] fix(wiki): document search parameter adapter --- docs/wiki-shortcut-business-review.html | 1 + internal/app/schema_shortcut_contract_test.go | 11 ++++++++++- internal/shortcut/wiki/common.go | 7 +++++++ internal/shortcut/wiki/wiki.go | 4 ++-- internal/shortcut/wiki/workflow_coverage_test.go | 11 ++++++++++- 5 files changed, 30 insertions(+), 4 deletions(-) diff --git a/docs/wiki-shortcut-business-review.html b/docs/wiki-shortcut-business-review.html index edb81799..9428f968 100644 --- a/docs/wiki-shortcut-business-review.html +++ b/docs/wiki-shortcut-business-review.html @@ -70,6 +70,7 @@ 节点列表 Shortcut 调错 Wiki MCP 服务。真实后端 success=false，Mock/静态检查看不出。跨域路由 明确调用 doc/list_nodes，并纳入真实 E2E。 成员帮助宣称最大 200。真实接口超过 50 直接参数错误。真实上限 Shortcut 与原子 Help 均改为 50，并在本地提前拒绝。 成员写操作从最多 50 条、不可分页的名单推断成员存在或缺失。目标在截断部分时会误报写失败，或把未验证的移除报告为已读回。终态证据 只接受写接口 success=true，并在结果中明确 readbackAvailable=false。 + 空间搜索的稳定工作流属性名与实际请求属性名不同。直接改写已发布的 query/limit 会造成无版本 Schema 破坏；继续隐式转换又会让审计者误以为请求同名透传。显式复合适配 最终 Schema 保留兼容属性并明确声明转换为 keyword/pageSize；回归测试同时锁定最终交付和精确请求参数。 知识库名称帮助宣称最大 100。真实接口超过 32 失败。真实上限 Help 与 Shortcut 校验统一为 32。 复制/移动/创建只把无异常视为成功。空确认、未知远端效果或移动未到目标仍可能被接受。读回证明 在后端具备精确查询能力时检查 success、业务 ID、workspace/folder 等最终状态。 diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index ff507975..7b05cc89 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -140,8 +140,17 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T) assertChatCatalogCompleteLeafContracts(t) } -func TestDeliveryWikiSpaceSearchPreservesHistoricalParameterProperties(t *testing.T) { +func TestDeliveryWikiSpaceSearchDeclaresCompatibilityAdapter(t *testing.T) { leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search") + if got := schemaContractString(leaf["interface_mode"]); got != "composite" { + t.Fatalf("wiki +space-search interface_mode = %q, want composite", got) + } + reason := schemaContractString(leaf["interface_reason"]) + for _, fragment := range []string{"query/limit", "search_wikiSpaces.keyword/pageSize", "versioned Schema migration"} { + if !strings.Contains(reason, fragment) { + t.Fatalf("wiki +space-search interface_reason = %q, want fragment %q", reason, fragment) + } + } parameters := schemaContractMap(leaf["parameters"]) for name, want := range map[string]string{"query": "query", "limit": "limit"} { parameter := parameters[name] diff --git a/internal/shortcut/wiki/common.go b/internal/shortcut/wiki/common.go index 60250a91..ab57746d 100644 --- a/internal/shortcut/wiki/common.go +++ b/internal/shortcut/wiki/common.go @@ -17,6 +17,8 @@ import ( const wikiCompositeReason = "Reviewed Wiki Shortcut composite: the executable CLI owns strict response validation, pagination projection, optional multi-step orchestration, read-back verification, and confirmation; no single MCP interface represents the complete command contract." +const wikiSpaceSearchCompositeReason = "Reviewed Wiki space-search compatibility adapter: the published workflow properties query/limit remain stable while execution translates them to search_wikiSpaces.keyword/pageSize; redirecting an existing non-empty property requires a versioned Schema migration." + func wikiContract(command, description, useWhen string, avoidWhen, examples []string, result *contract.ResultSpec, pagination *contract.PaginationSpec, params ...contract.ParamDecl) corecmd.ContractDecl { name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(command, "+"), "-", "_") cliPath := "wiki " + command @@ -28,6 +30,11 @@ func wikiContract(command, description, useWhen string, avoidWhen, examples []st } } +func wikiWithInterfaceReason(declared shortcut.Shortcut, reason string) shortcut.Shortcut { + declared.Contract.Interface.Reason = reason + return declared +} + func wikiObjectResult(description string) *contract.ResultSpec { return &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(fmt.Sprintf(`{"type":"object","description":%q,"additionalProperties":true}`, description))} } diff --git a/internal/shortcut/wiki/wiki.go b/internal/shortcut/wiki/wiki.go index a6262aa1..a36eb664 100644 --- a/internal/shortcut/wiki/wiki.go +++ b/internal/shortcut/wiki/wiki.go @@ -52,7 +52,7 @@ var SpaceList = readShortcut("+space-list", "严格分页列出知识库", "浏 return rt.Output(out) }) -var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", "dws wiki +space-search --query \"产品文档\" --format json", []shortcut.Flag{ +var SpaceSearch = wikiWithInterfaceReason(readShortcut("+space-search", "严格搜索知识库", "按名称关键词定位知识库；严格验证搜索数组，避免内部异常被误报为零命中。", "spaces", "dws wiki +space-search --query \"产品文档\" --format json", []shortcut.Flag{ {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词"}, {Name: "limit", Type: shortcut.FlagString, Desc: "返回数量 1-20（默认 10）"}, }, []contract.ParamDecl{{Name: "query", Property: "query"}, {Name: "limit", Property: "limit"}}, func(rt *shortcut.RuntimeContext) error { pageSize, err := wikiStringInt(rt, "limit", 10, 1, 20) @@ -71,7 +71,7 @@ var SpaceSearch = readShortcut("+space-search", "严格搜索知识库", "按名 out := map[string]any{"count": len(spaces), "spaces": spaces} addWikiPagination(out, page) return rt.Output(out) -}) +}), wikiSpaceSearchCompositeReason) var SpaceGet = readShortcut("+space-get", "获取知识库详情", "已知 workspace ID 或知识库 URL 时读取并验证空间详情。", "", "dws wiki +space-get --workspace --format json", []shortcut.Flag{{Name: "workspace", Type: shortcut.FlagString, Required: true, Desc: "知识库 ID 或 URL"}}, []contract.ParamDecl{{Name: "workspace", Property: "workspaceId"}}, func(rt *shortcut.RuntimeContext) error { data, err := rt.CallMCPData("wiki", "get_wikiSpace", map[string]any{"workspaceId": rt.Str("workspace")}) diff --git a/internal/shortcut/wiki/workflow_coverage_test.go b/internal/shortcut/wiki/workflow_coverage_test.go index aabc82b8..457ceec9 100644 --- a/internal/shortcut/wiki/workflow_coverage_test.go +++ b/internal/shortcut/wiki/workflow_coverage_test.go @@ -131,9 +131,18 @@ func TestCrossPlatformCoverageWikiSpaceWorkflows(t *testing.T) { "wiki/search_wikiSpaces": {`{"success":true,"wikiSpaces":[{"spaceId":"w2","spaceName":"Plan"}]}`}, }} out, err := runWikiCoverageCLI(t, caller, "+space-search", "--query", "Plan", "--limit", "12") - if err != nil || out["count"] != float64(1) || caller.calls[0].args["pageSize"] != 12 { + if err != nil || out["count"] != float64(1) || len(caller.calls) != 1 { t.Fatalf("search output=%#v err=%v calls=%#v", out, err, caller.calls) } + if got := caller.calls[0]; got.product != "wiki" || got.tool != "search_wikiSpaces" || len(got.args) != 2 || got.args["keyword"] != "Plan" || got.args["pageSize"] != 12 { + t.Fatalf("search call = %#v, want exact keyword/pageSize request", got) + } + if _, exists := caller.calls[0].args["query"]; exists { + t.Fatalf("search request leaked compatibility property query: %#v", caller.calls[0].args) + } + if _, exists := caller.calls[0].args["limit"]; exists { + t.Fatalf("search request leaked compatibility property limit: %#v", caller.calls[0].args) + } }) t.Run("get requires business id", func(t *testing.T) { From 547020f47e8c6c93703f1ec8c605f55f8bf4a5e7 Mon Sep 17 00:00:00 2001 From: Dennis Date: Sat, 15 Aug 2026 01:14:51 +0800 Subject: [PATCH 132/250] ci: shard shortcut reverse dependencies --- .github/workflows/ci.yml | 4 ++++ test/scripts/changelog_pr_gate_test.go | 7 +++++++ 2 files changed, 11 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d5d8d9e6..02e72637 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,6 +151,10 @@ jobs: filename.startsWith('scripts/') || filename.startsWith('verify/') || filename.startsWith('internal/helpers/') || + // Shortcut declarations feed the live command tree and Schema + // assembly. Their reverse dependencies include the expensive + // app and generator packages, which must run in separate shards. + filename.startsWith('internal/shortcut/') || filename.startsWith('internal/generator/') || filename.startsWith('internal/cli/schema') || // Parameter aliases are reduced against the live command tree. diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index b94b25c3..8f6be15a 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -1013,6 +1013,12 @@ if (!isHighRisk("internal/helpers/minutes.go")) { if (isHighRisk("internal/helpersx/minutes.go")) { throw new Error("helper high-risk classification must respect the path boundary"); } +if (!isHighRisk("internal/shortcut/wiki/wiki.go")) { + throw new Error("shortcut changes must use the sharded full suite"); +} +if (isHighRisk("internal/shortcuts/wiki/wiki.go")) { + throw new Error("shortcut high-risk classification must respect the path boundary"); +} for (const filename of [ "internal/cli/param_concepts.json", "internal/cli/param_concepts.schema.json", @@ -1137,6 +1143,7 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { "filename.startsWith('scripts/')", "filename.startsWith('verify/')", "filename.startsWith('internal/helpers/')", + "filename.startsWith('internal/shortcut/')", "filename === 'test/fixtures/cli-interface-baseline.txt'", "filename.startsWith('internal/interfacesnapshot/')", "filename.startsWith('internal/cobracmd/')", From 9a8a41a318336ab88e5d2b87129381900556dd18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 10:46:38 +0800 Subject: [PATCH 133/250] feat(corecmd): support @file / stdin input sources on string flags Port the lark-cli Flag.Input capability: a KindString flag may declare Input sources ("file" for @path, "stdin" for -) and the framework rewrites the explicit token into the payload content before required/enum/constraint/Validate checks. @@value escapes to a literal @value; a single stdin consumer per invocation is enforced; a leading UTF-8 BOM is stripped. Shortcut.Flag gains the same declaration and the adapter maps it through; LeafSpec inherits it via the LeafFlag alias. --- internal/corecmd/corecmd.go | 15 ++ internal/corecmd/input.go | 189 +++++++++++++++++++++++ internal/corecmd/input_test.go | 266 +++++++++++++++++++++++++++++++++ internal/shortcut/adapter.go | 1 + internal/shortcut/types.go | 6 + 5 files changed, 477 insertions(+) create mode 100644 internal/corecmd/input.go create mode 100644 internal/corecmd/input_test.go diff --git a/internal/corecmd/corecmd.go b/internal/corecmd/corecmd.go index 5d0fbe59..04741dce 100644 --- a/internal/corecmd/corecmd.go +++ b/internal/corecmd/corecmd.go @@ -145,6 +145,15 @@ type FlagSpec struct { // alike) and makes a whitespace-only value count as empty in required checks. Trim bool + // Input declares extra input sources for a KindString flag beyond the + // literal command-line value: InputFile enables @path (value replaced by + // the file content), InputStdin enables - (value replaced by stdin). + // "@@value" always escapes to the literal "@value". Only explicit CLI + // tokens are resolved; EnvVar fallback and registration defaults pass + // through unchanged. Resolution runs before required/enum/constraint/ + // Validate checks, so they see the payload content. Empty = flag value only. + Input []string + // Schema parameter final facts (embedded to dws.schema.*; assembly pass-through). Enum []string // accepted values Format string // machine-readable format (e.g. uri) @@ -365,6 +374,7 @@ func New(spec Spec) *cobra.Command { validateDispatchDecl(spec) validateSafetySpec(spec) validateContractDecl(spec) + validateInputSpecs(spec.Use, spec.Flags) // Help prose inherits the declaration when not authored separately: // Selection.Examples (already contract-validated against the real flags) // double as the --help Example block, keeping one authored source. @@ -476,6 +486,11 @@ func runDeclaredPreflight(cmd *cobra.Command, args []string, spec Spec) error { return err } } + // Input resolution rewrites explicit @file / stdin values in place so the + // required/enum/constraint/Validate stages below check the payload content. + if err := resolveInputFlags(cmd, spec.Flags); err != nil { + return err + } if err := ValidateRequired(cmd, spec.Flags); err != nil { return err } diff --git a/internal/corecmd/input.go b/internal/corecmd/input.go new file mode 100644 index 00000000..91c0746b --- /dev/null +++ b/internal/corecmd/input.go @@ -0,0 +1,189 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package corecmd + +import ( + "fmt" + "io" + "os" + "strings" + + "github.com/spf13/cobra" + + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil" +) + +// FlagSpec.Input source constants. They declare extra input sources for a +// KindString flag beyond the literal command-line value, mirroring the +// lark-cli Flag.Input capability so large payloads (markdown, JSON, CSV) +// never need shell quoting. +const ( + // InputFile allows the flag value @path to be replaced by the file content. + InputFile = "file" + // InputStdin allows the flag value - to be replaced by the stdin content. + InputStdin = "stdin" +) + +// utf8BOM is stripped from file/stdin content so a Windows-edited payload +// cannot corrupt the first CSV cell or break JSON parsing downstream. +const utf8BOM = "\ufeff" + +// validateInputSpecs rejects malformed Input declarations at build time. Like +// the other declaration checks this panics: a bad Input spec is a programming +// error every test and startup path should trip immediately. +func validateInputSpecs(use string, flags []FlagSpec) { + for _, flag := range flags { + if len(flag.Input) == 0 { + continue + } + if flag.Kind != KindString { + panic(fmt.Sprintf( + "command %q flag %q: Input is only supported on KindString flags", + use, flag.Name)) + } + seen := map[string]bool{} + for _, source := range flag.Input { + if source != InputFile && source != InputStdin { + panic(fmt.Sprintf( + "command %q flag %q: unknown Input source %q (allowed: %s, %s)", + use, flag.Name, source, InputFile, InputStdin)) + } + if seen[source] { + panic(fmt.Sprintf( + "command %q flag %q: duplicate Input source %q", + use, flag.Name, source)) + } + seen[source] = true + } + } +} + +// inputSupports reports whether the flag declared the given input source. +func inputSupports(flag FlagSpec, source string) bool { + for _, s := range flag.Input { + if s == source { + return true + } + } + return false +} + +// explicitInputFlagName picks the declared name that carries the user's +// explicit token, mirroring rawValue's order: the main flag wins only when +// changed and non-empty, then declared aliases in order. EnvVar fallback and +// registration defaults are never input-resolved — @file only applies to what +// the user literally typed. +func explicitInputFlagName(cmd *cobra.Command, flag FlagSpec) string { + for _, name := range append([]string{flag.Name}, flag.Aliases...) { + if !cmd.Flags().Changed(name) { + continue + } + if strings.TrimSpace(cmdutil.MustGetFlag(cmd, name)) != "" { + return name + } + } + return "" +} + +// resolveInputFlags rewrites the explicit values of Input-declaring flags +// before required/enum/constraint/Validate checks, so every downstream stage +// sees the real payload content. Semantics: +// +// - "-" reads stdin; a process has a single stdin, so a second Input flag +// using "-" in the same invocation is rejected. +// - "@path" reads the named file (leading/trailing whitespace trimmed). +// - "@@value" escapes to the literal "@value" and is not source-resolved. +// +// Resolution runs once per invocation inside runDeclaredPreflight. It +// rewrites the cobra flag value in place (Set keeps Changed=true), so +// fallback-chain readers (EffectiveValue/BuildArgs) observe the content. +// +// Interaction with confirmation: stdin is consumed here, before the Safety +// prompt of a user_required write would read it; such an interactive prompt +// then sees EOF and fails closed with confirmation_required. Write commands +// declaring InputStdin must be invoked with --yes (or --dry-run). +func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error { + stdinConsumed := false + for _, flag := range flags { + if len(flag.Input) == 0 { + continue + } + name := explicitInputFlagName(cmd, flag) + if name == "" { + continue + } + raw := cmdutil.MustGetFlag(cmd, name) + + switch { + case raw == "-": + if !inputSupports(flag, InputStdin) { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 不支持 stdin 输入（-）", flag.Name)) + } + if stdinConsumed { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s：stdin（-）只能被一个参数使用", flag.Name), + apperrors.WithHint(fmt.Sprintf( + "一个进程只有一份 stdin，其余参数请内联传值或用 @文件路径（如 --%s @./payload.json）", + flag.Name))) + } + stdinConsumed = true + data, err := io.ReadAll(cmd.InOrStdin()) + if err != nil { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 读取 stdin 失败：%v", flag.Name, err)) + } + if err := cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)); err != nil { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) + } + + case strings.HasPrefix(raw, "@@"): + // Escape: strip the first @, keep the rest as a literal inline value. + if err := cmd.Flags().Set(name, raw[1:]); err != nil { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) + } + + case strings.HasPrefix(raw, "@"): + if !inputSupports(flag, InputFile) { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 不支持文件输入（@路径）", flag.Name)) + } + path := strings.TrimSpace(raw[1:]) + if path == "" { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s：@ 后的文件路径不能为空", flag.Name)) + } + data, err := os.ReadFile(path) + if err != nil { + verr := apperrors.NewValidation( + fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err)) + if inputSupports(flag, InputStdin) { + verr = apperrors.NewValidation( + fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err), + apperrors.WithHint(fmt.Sprintf( + "该参数也支持 stdin：把文件内容管道进命令并传 --%s -", flag.Name))) + } + return verr + } + if err := cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)); err != nil { + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) + } + } + } + return nil +} diff --git a/internal/corecmd/input_test.go b/internal/corecmd/input_test.go new file mode 100644 index 00000000..94aab0bd --- /dev/null +++ b/internal/corecmd/input_test.go @@ -0,0 +1,266 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package corecmd + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/spf13/cobra" +) + +// newInputCommand builds a Spec whose Invoke captures toolArgs, so tests can +// assert what the full pipeline (resolution → validation → BuildArgs) ships. +func newInputCommand(flags []FlagSpec, captured *map[string]any) *cobra.Command { + return New(Spec{ + Use: "t", + Short: "t", + Flags: flags, + Invoke: func(c *Ctx, toolArgs map[string]any) error { + *captured = toolArgs + return nil + }, + }) +} + +func runInputCommand(t *testing.T, cmd *cobra.Command, args ...string) error { + t.Helper() + cmd.SetArgs(args) + return cmd.Execute() +} + +func writeInputFile(t *testing.T, content string) string { + t.Helper() + path := filepath.Join(t.TempDir(), "payload.txt") + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatalf("write fixture: %v", err) + } + return path +} + +func TestResolveInputFlags_File(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, + }, &got) + path := writeInputFile(t, "# hello\nworld") + + if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "# hello\nworld" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +func TestResolveInputFlags_Stdin(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}}, + }, &got) + cmd.SetIn(strings.NewReader("piped payload")) + + if err := runInputCommand(t, cmd, "--content", "-"); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "piped payload" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +// The @@ escape keeps a literal leading @ inline and must not be treated as a +// source reference even when Input is declared. +func TestResolveInputFlags_EscapedAtStaysInline(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, + }, &got) + + if err := runInputCommand(t, cmd, "--content", "@@literal@x"); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "@literal@x" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +func TestResolveInputFlags_BOMStripped(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, + }, &got) + path := writeInputFile(t, "\ufeff{\"a\":1}") + + if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "{\"a\":1}" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +// Required must be satisfied by the resolved payload, proving resolution runs +// before the required stage. +func TestResolveInputFlags_SatisfiesRequired(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Required: true, Input: []string{InputFile}}, + }, &got) + path := writeInputFile(t, "payload") + + if err := runInputCommand(t, cmd, "--content", "@"+path); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "payload" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +// Enum validation sees the resolved content, not the "@path" token. +func TestResolveInputFlags_EnumValidatesResolvedContent(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "mode", Usage: "M", Bind: "mode", Enum: []string{"asc", "desc"}, Input: []string{InputFile}}, + }, &got) + path := writeInputFile(t, "sideways") + + err := runInputCommand(t, cmd, "--mode", "@"+path) + if err == nil || !strings.Contains(err.Error(), "不合法") { + t.Fatalf("expected enum rejection on resolved content, got %v", err) + } +} + +// A value passed through a declared alias is resolved exactly like the main +// name (fallback-chain parity). +func TestResolveInputFlags_AliasResolved(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}}, + }, &got) + path := writeInputFile(t, "via alias") + + if err := runInputCommand(t, cmd, "--body", "@"+path); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "via alias" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +func TestResolveInputFlags_FileNotSupported(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}}, + }, &got) + + err := runInputCommand(t, cmd, "--content", "@/tmp/whatever.txt") + if err == nil || !strings.Contains(err.Error(), "不支持文件输入") { + t.Fatalf("expected file-input rejection, got %v", err) + } +} + +func TestResolveInputFlags_StdinNotSupported(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, + }, &got) + cmd.SetIn(strings.NewReader("x")) + + err := runInputCommand(t, cmd, "--content", "-") + if err == nil || !strings.Contains(err.Error(), "不支持 stdin") { + t.Fatalf("expected stdin rejection, got %v", err) + } +} + +func TestResolveInputFlags_SingleStdinConsumer(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "first", Usage: "F", Bind: "first", Input: []string{InputStdin}}, + {Name: "second", Usage: "S", Bind: "second", Input: []string{InputStdin}}, + }, &got) + cmd.SetIn(strings.NewReader("x")) + + err := runInputCommand(t, cmd, "--first", "-", "--second", "-") + if err == nil || !strings.Contains(err.Error(), "只能被一个参数使用") { + t.Fatalf("expected single-stdin rejection, got %v", err) + } +} + +func TestResolveInputFlags_FileNotFound(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, + }, &got) + + err := runInputCommand(t, cmd, "--content", "@"+filepath.Join(t.TempDir(), "missing.txt")) + if err == nil || !strings.Contains(err.Error(), "读取文件") { + t.Fatalf("expected read failure, got %v", err) + } +} + +func TestResolveInputFlags_EmptyPathAfterAt(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, + }, &got) + + err := runInputCommand(t, cmd, "--content", "@ ") + if err == nil || !strings.Contains(err.Error(), "文件路径不能为空") { + t.Fatalf("expected empty-path rejection, got %v", err) + } +} + +// A flag without Input keeps its literal value even when it looks like a +// source reference — resolution is strictly opt-in per declaration. +func TestResolveInputFlags_NoInputSpecPassthrough(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "token", Usage: "T", Bind: "token"}, + }, &got) + + if err := runInputCommand(t, cmd, "--token", "@not-a-file"); err != nil { + t.Fatalf("execute: %v", err) + } + if got["token"] != "@not-a-file" { + t.Fatalf("toolArgs[token] = %q", got["token"]) + } +} + +func TestValidateInputSpecs_Panics(t *testing.T) { + cases := []struct { + name string + flag FlagSpec + }{ + {"non-string kind", FlagSpec{Name: "n", Kind: KindInt, Input: []string{InputFile}}}, + {"unknown source", FlagSpec{Name: "s", Input: []string{"url"}}}, + {"duplicate source", FlagSpec{Name: "s", Input: []string{InputFile, InputFile}}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + defer func() { + if recover() == nil { + t.Fatal("expected panic") + } + }() + New(Spec{ + Use: "t", + Short: "t", + Flags: []FlagSpec{tc.flag}, + Invoke: func(c *Ctx, toolArgs map[string]any) error { return nil }, + }) + }) + } +} diff --git a/internal/shortcut/adapter.go b/internal/shortcut/adapter.go index fd1f968d..7b870b83 100644 --- a/internal/shortcut/adapter.go +++ b/internal/shortcut/adapter.go @@ -217,6 +217,7 @@ func fromShortcutFlags(flags []Flag) []corecmd.FlagSpec { RequiredError: fmt.Sprintf("缺少必填参数 --%s：%s", f.Name, f.Desc), Enum: append([]string(nil), f.Enum...), Aliases: append([]string(nil), f.Aliases...), + Input: append([]string(nil), f.Input...), }) } return out diff --git a/internal/shortcut/types.go b/internal/shortcut/types.go index 8e46ec3a..b3545f36 100644 --- a/internal/shortcut/types.go +++ b/internal/shortcut/types.go @@ -107,6 +107,12 @@ type Flag struct { // compatibility escape hatch for aliases that were historically public. Aliases []string `json:"-"` AliasesVisible bool `json:"-"` + // Input declares extra input sources for a string flag beyond the literal + // command-line value: "file" enables @path (value replaced by the file + // content), "stdin" enables - (value replaced by stdin). "@@value" escapes + // to the literal "@value". Resolution happens before Required/Enum/Validate + // checks. Empty = flag value only. + Input []string `json:"input,omitempty"` } // ConstraintKind is a machine-readable cross-parameter or custom validation From 78e6f11d727d00bb4ce46643f1041db31bffd712 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:06:02 +0800 Subject: [PATCH 134/250] =?UTF-8?q?docs(rfc):=20add=20@file=20/=20stdin=20?= =?UTF-8?q?Input=20flag=20usage=20guide=20to=20=C2=A75.3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the landed corecmd.Input transitional form: declaration shape (FlagSpec/LeafFlag/shortcut.Flag), runtime resolution semantics and ordering, author rules (help prose, confirmation interaction with stdin, construction-time validation), and the delta table against the target typed InputSource design. --- docs/rfc-command-framework-convergence.md | 45 +++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/rfc-command-framework-convergence.md b/docs/rfc-command-framework-convergence.md index fd66356d..30d6b7e3 100644 --- a/docs/rfc-command-framework-convergence.md +++ b/docs/rfc-command-framework-convergence.md @@ -673,6 +673,51 @@ func (k Key[T]) Declare(opts ...FlagOption[T]) FlagSpec - 构造时拒绝 `InputSourceInvalid`。 - 当前没有任何 Shortcut 或 Leaf 声明 `Input`，因此 M1 增加能力且零上线表面变化。让现有命令采用它属于 §9 下的用户可见变更。 +`Input` 的框架能力今日已在 `corecmd` 落地（声明即执行的过渡形态，语义与上文目标一致），使用指南： + +**今日声明形态**：`FlagSpec.Input []string`，源常量 `corecmd.InputFile`（`"file"`）/ `corecmd.InputStdin`（`"stdin"`）。`helpers.LeafFlag` 是 `corecmd.FlagSpec` 别名，直接可用；`shortcut.Flag.Input` 同形声明，经 `FromShortcut` 映射到 `FlagSpec`。 + +```go +// LeafSpec / helpers +Flags: []helpers.LeafFlag{ + { + Name: "content", + Usage: "文档内容（支持 @文件路径 或 - 读 stdin）", + Bind: "content", + Input: []string{corecmd.InputFile, corecmd.InputStdin}, + }, +} + +// shortcut +Flags: []shortcut.Flag{ + {Name: "markdown", Desc: "Markdown 内容（支持 @文件路径 或 -）", + Input: []string{"file", "stdin"}}, +} +``` + +**运行时语义**（`resolveInputFlags`，在 `runDeclaredPreflight` 内、required/enum/约束/Validate 之前执行，原地改写 cobra flag 值）： + +- `--flag @path`：文件内容替换取值；`--flag -`：stdin 内容替换取值。 +- `--flag @@value`：转义为字面 `@value`，不做来源解析。 +- 只解析显式 CLI token（主名或别名）；EnvVar 回落与注册默认值透传不解析。 +- 内容前置剥离 UTF-8 BOM；`Trim` 等既有语义照常作用于解析后的值。 +- 读取失败、源不支持、`@` 后空路径都是类型化校验错误（退出码 3）；同时声明两种源而文件读取失败时附 stdin 引导 hint。 + +**作者守则**： + +- 声明即全部能力：required/enum/约束/Validate 校验的已是解析后的真实内容，`Execute`/`Invoke` 无需任何额外代码。 +- `Usage`/`Desc` 必须写明支持 `@路径`/`-`；框架不自动改写 help 文案，今日也不向 Schema 投影（新增投影字段须先过 homology 评审，避免 catalog drift）。 +- `user_required` 确认的写命令若声明 `InputStdin`：stdin 在校验阶段被消费，交互确认将 fail-closed 为 `confirmation_required`，此类调用必须显式 `--yes`（或 `--dry-run`）。 +- 声明在构造期校验（fail-closed panic）：仅限 `KindString`；源值必须是 `file`/`stdin` 且不重复。 + +**今日实现与目标形态的差异**（迁移到本节目标 `FlagSpec` 时收敛）： + +| 维度 | 今日 | 目标 | +|---|---|---| +| 源类型 | `[]string` 常量 | 类型化 `InputSource` | +| 路径边界 | 直接本地文件 IO | 复用 §5.5.2 本地文件 effect 边界 | +| Schema 投影 | 无（靠作者在 Usage 声明） | 声明即最终源，随 Catalog 透传 | + 核心 FlagSpec 故意没有： - `Bind`； From 7a58b0d19a62c6879c35f078e98f6f6c5a98cf24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:11:55 +0800 Subject: [PATCH 135/250] fix(corecmd): align Input prefix check with Trim semantics Self-review fixes: a Trim flag receiving " @path" judged usability on the trimmed value (rawValue) while the source prefix check saw the raw value, so the token would ship as a literal. Trim before the prefix check. Also build the file-read error once with a conditional hint option, and pin the default-value/env passthrough plus Trim edge with regression tests. --- internal/corecmd/input.go | 19 ++++++++++++------- internal/corecmd/input_test.go | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 7 deletions(-) diff --git a/internal/corecmd/input.go b/internal/corecmd/input.go index 91c0746b..e534246b 100644 --- a/internal/corecmd/input.go +++ b/internal/corecmd/input.go @@ -125,6 +125,11 @@ func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error { continue } raw := cmdutil.MustGetFlag(cmd, name) + // Trim flags judge usability on the trimmed value (rawValue), so the + // prefix check must agree or " @path" would slip through unresolved. + if flag.Trim { + raw = strings.TrimSpace(raw) + } switch { case raw == "-": @@ -169,15 +174,15 @@ func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error { } data, err := os.ReadFile(path) if err != nil { - verr := apperrors.NewValidation( - fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err)) + var opts []apperrors.Option if inputSupports(flag, InputStdin) { - verr = apperrors.NewValidation( - fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err), - apperrors.WithHint(fmt.Sprintf( - "该参数也支持 stdin：把文件内容管道进命令并传 --%s -", flag.Name))) + // Rejected @file paths are usually absolute (temp files). + // Steer toward stdin rather than copying the file around. + opts = append(opts, apperrors.WithHint(fmt.Sprintf( + "该参数也支持 stdin：把文件内容管道进命令并传 --%s -", flag.Name))) } - return verr + return apperrors.NewValidation( + fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err), opts...) } if err := cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)); err != nil { return apperrors.NewValidation( diff --git a/internal/corecmd/input_test.go b/internal/corecmd/input_test.go index 94aab0bd..6f7a69bd 100644 --- a/internal/corecmd/input_test.go +++ b/internal/corecmd/input_test.go @@ -239,6 +239,39 @@ func TestResolveInputFlags_NoInputSpecPassthrough(t *testing.T) { } } +// Registration defaults and env fallback are never input-resolved: @file only +// applies to what the user literally typed on the command line. +func TestResolveInputFlags_DefaultNotResolved(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Default: "@not-a-file", Input: []string{InputFile}}, + }, &got) + + if err := runInputCommand(t, cmd); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "@not-a-file" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + +// Trim flags judge usability on the trimmed value (rawValue), so a leading +// whitespace before @ must still resolve instead of shipping as a literal. +func TestResolveInputFlags_TrimmedLeadingSpace(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Trim: true, Input: []string{InputFile}}, + }, &got) + path := writeInputFile(t, "trimmed payload") + + if err := runInputCommand(t, cmd, "--content", " @"+path); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != "trimmed payload" { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + func TestValidateInputSpecs_Panics(t *testing.T) { cases := []struct { name string From e92309f7c47dc73d65893d7279d25685e0cdaa0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:14:10 +0800 Subject: [PATCH 136/250] fix(corecmd): match Input name selection to rawValue usability exactly Second-review fix: explicitInputFlagName judged usability with an unconditional TrimSpace while rawValue only trims when Trim is set. For a non-Trim flag a whitespace main value is usable and shadows a changed alias; the resolver could then rewrite the shadowed alias (and fail on its @path) while the fallback chain still read the main value. Mirror rawValue's usable() exactly and pin the shadow case with a regression test whose alias path does not exist. --- internal/corecmd/input.go | 17 +++++++++++------ internal/corecmd/input_test.go | 20 ++++++++++++++++++++ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/internal/corecmd/input.go b/internal/corecmd/input.go index e534246b..c1909d15 100644 --- a/internal/corecmd/input.go +++ b/internal/corecmd/input.go @@ -81,16 +81,21 @@ func inputSupports(flag FlagSpec, source string) bool { } // explicitInputFlagName picks the declared name that carries the user's -// explicit token, mirroring rawValue's order: the main flag wins only when -// changed and non-empty, then declared aliases in order. EnvVar fallback and +// explicit token, mirroring rawValue's order and usability judgement exactly: +// the main flag wins only when changed and usable (trim-judged only when +// Trim is set), then declared aliases in order. Diverging here could rewrite +// an alias that rawValue would shadow (or vice versa). EnvVar fallback and // registration defaults are never input-resolved — @file only applies to what // the user literally typed. func explicitInputFlagName(cmd *cobra.Command, flag FlagSpec) string { - for _, name := range append([]string{flag.Name}, flag.Aliases...) { - if !cmd.Flags().Changed(name) { - continue + usable := func(v string) bool { + if flag.Trim { + v = strings.TrimSpace(v) } - if strings.TrimSpace(cmdutil.MustGetFlag(cmd, name)) != "" { + return v != "" + } + for _, name := range append([]string{flag.Name}, flag.Aliases...) { + if cmd.Flags().Changed(name) && usable(cmdutil.MustGetFlag(cmd, name)) { return name } } diff --git a/internal/corecmd/input_test.go b/internal/corecmd/input_test.go index 6f7a69bd..984f9598 100644 --- a/internal/corecmd/input_test.go +++ b/internal/corecmd/input_test.go @@ -160,6 +160,26 @@ func TestResolveInputFlags_AliasResolved(t *testing.T) { } } +// When the main flag shadows a changed alias (rawValue usability order), the +// shadowed alias must not be input-resolved: resolution targets exactly the +// name the fallback chain will read. The whitespace main value is usable for +// a non-Trim flag, and the alias path does not exist on purpose — a resolver +// that wrongly picked the alias would fail the read instead of shipping " ". +func TestResolveInputFlags_ShadowedAliasNotResolved(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}}, + }, &got) + missing := filepath.Join(t.TempDir(), "missing.txt") + + if err := runInputCommand(t, cmd, "--content", " ", "--body", "@"+missing); err != nil { + t.Fatalf("execute: %v", err) + } + if got["content"] != " " { + t.Fatalf("toolArgs[content] = %q", got["content"]) + } +} + func TestResolveInputFlags_FileNotSupported(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ From e4daddf9cfe8b17ae002f869ed5a8b2e88a649dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:23:54 +0800 Subject: [PATCH 137/250] test(corecmd): name Input tests for the platform coverage gate Third-review fix for a CI blocker: run-platform-coverage-gate.sh only executes ^(TestAllShortcuts|TestCrossPlatformCoverage) yet enforces 100% coverage of changed production lines, so the TestResolveInputFlags names left every new input.go statement reported as uncovered. Rename them to the gate prefix, drop three unreachable pflag Set error branches that no test could ever cover, and add the reachable stdin read-failure case. Verified: changed code coverage 100.0000% (67 statements). --- internal/corecmd/input.go | 16 +++-------- internal/corecmd/input_test.go | 49 ++++++++++++++++++++++------------ 2 files changed, 36 insertions(+), 29 deletions(-) diff --git a/internal/corecmd/input.go b/internal/corecmd/input.go index c1909d15..a3bbbe18 100644 --- a/internal/corecmd/input.go +++ b/internal/corecmd/input.go @@ -155,17 +155,12 @@ func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error { return apperrors.NewValidation( fmt.Sprintf("参数 --%s 读取 stdin 失败：%v", flag.Name, err)) } - if err := cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)); err != nil { - return apperrors.NewValidation( - fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) - } + // Setting a registered string flag cannot fail. + _ = cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)) case strings.HasPrefix(raw, "@@"): // Escape: strip the first @, keep the rest as a literal inline value. - if err := cmd.Flags().Set(name, raw[1:]); err != nil { - return apperrors.NewValidation( - fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) - } + _ = cmd.Flags().Set(name, raw[1:]) case strings.HasPrefix(raw, "@"): if !inputSupports(flag, InputFile) { @@ -189,10 +184,7 @@ func resolveInputFlags(cmd *cobra.Command, flags []FlagSpec) error { return apperrors.NewValidation( fmt.Sprintf("参数 --%s 读取文件 %q 失败：%v", flag.Name, path, err), opts...) } - if err := cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)); err != nil { - return apperrors.NewValidation( - fmt.Sprintf("参数 --%s 写入解析值失败：%v", flag.Name, err)) - } + _ = cmd.Flags().Set(name, strings.TrimPrefix(string(data), utf8BOM)) } } return nil diff --git a/internal/corecmd/input_test.go b/internal/corecmd/input_test.go index 984f9598..3edab9ab 100644 --- a/internal/corecmd/input_test.go +++ b/internal/corecmd/input_test.go @@ -51,7 +51,7 @@ func writeInputFile(t *testing.T, content string) string { return path } -func TestResolveInputFlags_File(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsFile(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, @@ -66,7 +66,7 @@ func TestResolveInputFlags_File(t *testing.T) { } } -func TestResolveInputFlags_Stdin(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsStdin(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}}, @@ -83,7 +83,7 @@ func TestResolveInputFlags_Stdin(t *testing.T) { // The @@ escape keeps a literal leading @ inline and must not be treated as a // source reference even when Input is declared. -func TestResolveInputFlags_EscapedAtStaysInline(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsEscapedAtStaysInline(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, @@ -97,7 +97,7 @@ func TestResolveInputFlags_EscapedAtStaysInline(t *testing.T) { } } -func TestResolveInputFlags_BOMStripped(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsBOMStripped(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, @@ -114,7 +114,7 @@ func TestResolveInputFlags_BOMStripped(t *testing.T) { // Required must be satisfied by the resolved payload, proving resolution runs // before the required stage. -func TestResolveInputFlags_SatisfiesRequired(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsSatisfiesRequired(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Required: true, Input: []string{InputFile}}, @@ -130,7 +130,7 @@ func TestResolveInputFlags_SatisfiesRequired(t *testing.T) { } // Enum validation sees the resolved content, not the "@path" token. -func TestResolveInputFlags_EnumValidatesResolvedContent(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsEnumValidatesResolvedContent(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "mode", Usage: "M", Bind: "mode", Enum: []string{"asc", "desc"}, Input: []string{InputFile}}, @@ -145,7 +145,7 @@ func TestResolveInputFlags_EnumValidatesResolvedContent(t *testing.T) { // A value passed through a declared alias is resolved exactly like the main // name (fallback-chain parity). -func TestResolveInputFlags_AliasResolved(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsAliasResolved(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}}, @@ -165,7 +165,7 @@ func TestResolveInputFlags_AliasResolved(t *testing.T) { // name the fallback chain will read. The whitespace main value is usable for // a non-Trim flag, and the alias path does not exist on purpose — a resolver // that wrongly picked the alias would fail the read instead of shipping " ". -func TestResolveInputFlags_ShadowedAliasNotResolved(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsShadowedAliasNotResolved(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Aliases: []string{"body"}, Input: []string{InputFile}}, @@ -180,7 +180,7 @@ func TestResolveInputFlags_ShadowedAliasNotResolved(t *testing.T) { } } -func TestResolveInputFlags_FileNotSupported(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsFileNotSupported(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}}, @@ -192,7 +192,7 @@ func TestResolveInputFlags_FileNotSupported(t *testing.T) { } } -func TestResolveInputFlags_StdinNotSupported(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsStdinNotSupported(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, @@ -205,7 +205,7 @@ func TestResolveInputFlags_StdinNotSupported(t *testing.T) { } } -func TestResolveInputFlags_SingleStdinConsumer(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsSingleStdinConsumer(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "first", Usage: "F", Bind: "first", Input: []string{InputStdin}}, @@ -219,7 +219,22 @@ func TestResolveInputFlags_SingleStdinConsumer(t *testing.T) { } } -func TestResolveInputFlags_FileNotFound(t *testing.T) { +// failingReader (corecmd_test.go) fails every read, making the stdin error +// branch reachable. +func TestCrossPlatformCoverageResolveInputFlagsStdinReadFailure(t *testing.T) { + var got map[string]any + cmd := newInputCommand([]FlagSpec{ + {Name: "content", Usage: "C", Bind: "content", Input: []string{InputStdin}}, + }, &got) + cmd.SetIn(failingReader{}) + + err := runInputCommand(t, cmd, "--content", "-") + if err == nil || !strings.Contains(err.Error(), "读取 stdin 失败") { + t.Fatalf("expected stdin read failure, got %v", err) + } +} + +func TestCrossPlatformCoverageResolveInputFlagsFileNotFound(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile, InputStdin}}, @@ -231,7 +246,7 @@ func TestResolveInputFlags_FileNotFound(t *testing.T) { } } -func TestResolveInputFlags_EmptyPathAfterAt(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsEmptyPathAfterAt(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Input: []string{InputFile}}, @@ -245,7 +260,7 @@ func TestResolveInputFlags_EmptyPathAfterAt(t *testing.T) { // A flag without Input keeps its literal value even when it looks like a // source reference — resolution is strictly opt-in per declaration. -func TestResolveInputFlags_NoInputSpecPassthrough(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsNoInputSpecPassthrough(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "token", Usage: "T", Bind: "token"}, @@ -261,7 +276,7 @@ func TestResolveInputFlags_NoInputSpecPassthrough(t *testing.T) { // Registration defaults and env fallback are never input-resolved: @file only // applies to what the user literally typed on the command line. -func TestResolveInputFlags_DefaultNotResolved(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsDefaultNotResolved(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Default: "@not-a-file", Input: []string{InputFile}}, @@ -277,7 +292,7 @@ func TestResolveInputFlags_DefaultNotResolved(t *testing.T) { // Trim flags judge usability on the trimmed value (rawValue), so a leading // whitespace before @ must still resolve instead of shipping as a literal. -func TestResolveInputFlags_TrimmedLeadingSpace(t *testing.T) { +func TestCrossPlatformCoverageResolveInputFlagsTrimmedLeadingSpace(t *testing.T) { var got map[string]any cmd := newInputCommand([]FlagSpec{ {Name: "content", Usage: "C", Bind: "content", Trim: true, Input: []string{InputFile}}, @@ -292,7 +307,7 @@ func TestResolveInputFlags_TrimmedLeadingSpace(t *testing.T) { } } -func TestValidateInputSpecs_Panics(t *testing.T) { +func TestCrossPlatformCoverageValidateInputSpecsPanics(t *testing.T) { cases := []struct { name string flag FlagSpec From bf2c0653ed6681881d2781341d13ba522b0347c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:29:26 +0800 Subject: [PATCH 138/250] docs: record Input in the flag/help/schema homology field table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fourth-review fix: the FlagSpec sub-field table in the homology doc is the named authority for "what each field does and whether it reaches Schema parameters", and RFC §5.0.2 asserts declaration fields embed into dws.schema.*. Input satisfied neither entry, leaving its deliberate non-projection indistinguishable from an oversight. Add the table row and the §5.0.2 exception note so the capability stays a declared fact (Usage prose) rather than inviting an invented annotation. --- docs/flag-help-schema-homology.md | 1 + docs/rfc-command-framework-convergence.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/flag-help-schema-homology.md b/docs/flag-help-schema-homology.md index 47b65466..591d543d 100644 --- a/docs/flag-help-schema-homology.md +++ b/docs/flag-help-schema-homology.md @@ -92,6 +92,7 @@ command/Leaf 不再写 `dws.schema.risk`；SafetySpec 走类型化 Final 载荷 | `Required` / `MarkRequired` | 非空校验 / cobra 硬必填 | 是（`required`） | | `RequiredHint`, `Aliases`, `EnvVar` | 校验提示、隐藏别名、环境回退 | 否（执行细节；别名不上主 parameter 表） | | `ArgDefault`, `Bind`, `OmitEmpty`, `Trim`, `Transform` | toolArgs 装配语义 | 否（载荷细节；`Bind` 可进 property 映射，但不另造 flag） | +| `Input` | 额外取值来源：`@path` 读文件 / `-` 读 stdin，在 required/enum/约束/`Validate` 之前原地解析 | 否（今日：能力由作者写进 `Usage` / `SchemaDescription` 文案，是已声明事实而非推断；不另造 flag。目标形态收敛为类型化投影字段，见 RFC §5.3） | #### 1.2.2 编排 / 执行字段（不算声明） diff --git a/docs/rfc-command-framework-convergence.md b/docs/rfc-command-framework-convergence.md index 30d6b7e3..55aa6646 100644 --- a/docs/rfc-command-framework-convergence.md +++ b/docs/rfc-command-framework-convergence.md @@ -292,7 +292,7 @@ Definition（仅声明；不可编译） 下列字段**是**框架声明面（经 `corecmd.New` 生效并嵌入 `dws.schema.*`）： -- `Flags`（含 Name/Kind/Default/Required/MarkRequired/Usage 等注册面） +- `Flags`（含 Name/Kind/Default/Required/MarkRequired/Usage 等注册面；`Input` 是取值来源声明，经 `corecmd.New` 生效但**不**嵌入 `dws.schema.*`，能力靠 `Usage` 文案声明，见 §5.3） - `Constraints` - **非空** `Risk`（空值 = 运行时当只读确认，且**不**嵌入 `dws.schema.risk`） - `ConstParams`（载荷声明；不上用户 flag 表） From 5ee80cdb97c5487ff079a112a93f6b49b86bf7d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Sat, 15 Aug 2026 12:34:33 +0800 Subject: [PATCH 139/250] docs(rfc): warn about Input value-space collisions Fifth-review addition: declaring InputFile silently claims the whole @-prefixed value space, which matters in this product because at-mention style values are common (--at-user @zhangsan would report a file read failure), and declaring InputStdin makes a literal "-" unreachable. Both are decided at declaration time and cannot be fixed downstream, so record them next to the confirmation rule in the author rules. --- docs/rfc-command-framework-convergence.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/rfc-command-framework-convergence.md b/docs/rfc-command-framework-convergence.md index 55aa6646..cb12c50b 100644 --- a/docs/rfc-command-framework-convergence.md +++ b/docs/rfc-command-framework-convergence.md @@ -708,6 +708,7 @@ Flags: []shortcut.Flag{ - 声明即全部能力：required/enum/约束/Validate 校验的已是解析后的真实内容，`Execute`/`Invoke` 无需任何额外代码。 - `Usage`/`Desc` 必须写明支持 `@路径`/`-`；框架不自动改写 help 文案，今日也不向 Schema 投影（新增投影字段须先过 homology 评审，避免 catalog drift）。 - `user_required` 确认的写命令若声明 `InputStdin`：stdin 在校验阶段被消费，交互确认将 fail-closed 为 `confirmation_required`，此类调用必须显式 `--yes`（或 `--dry-run`）。 +- **声明前先确认取值空间不会被前缀吃掉**：声明 `InputFile` 后，任何以 `@` 开头的合法值都会被当成文件路径（本产品尤其常见的是 at 提及类取值，如 `--at-user @zhangsan` 会报读取文件失败），用户只能改用 `@@` 转义；声明 `InputStdin` 后字面值 `-` 不可达（与 curl 等约定一致）。若该 flag 的正常取值可能命中这两种形态，就不要声明对应来源。 - 声明在构造期校验（fail-closed panic）：仅限 `KindString`；源值必须是 `file`/`stdin` 且不重复。 **今日实现与目标形态的差异**（迁移到本节目标 `FlagSpec` 时收敛）： From 92195a58a346fadbcfdf834e6b86245db39332b4 Mon Sep 17 00:00:00 2001 From: xiatian Date: Sat, 15 Aug 2026 13:40:47 +0800 Subject: [PATCH 140/250] fix(sheet): align SourceRange review contract --- .changes/sheet-source-range-dropdowns.md | 2 +- internal/helpers/sheet_batch.go | 10 ++-- internal/helpers/sheet_dimension.go | 19 +++++-- .../sheet_dropdown_source_range_test.go | 52 +++++++++++++++++++ internal/helpers/sheet_range_ops.go | 2 +- .../products/sheet/sheet-batch-operations.md | 4 +- .../products/sheet/sheet-dropdown.md | 8 +-- .../products/sheet/sheet-read-data.md | 6 +-- .../products/sheet/sheet-write-data.md | 2 +- .../sheet/sheet-batch-operations.md | 4 +- .../references/sheet/sheet-dropdown.md | 8 +-- .../references/sheet/sheet-read-data.md | 6 +-- .../references/sheet/sheet-write-data.md | 2 +- 13 files changed, 97 insertions(+), 28 deletions(-) diff --git a/.changes/sheet-source-range-dropdowns.md b/.changes/sheet-source-range-dropdowns.md index 55d58640..91159e61 100644 --- a/.changes/sheet-source-range-dropdowns.md +++ b/.changes/sheet-source-range-dropdowns.md @@ -2,5 +2,5 @@ category: Added --- -- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. +- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported. - **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads. diff --git a/internal/helpers/sheet_batch.go b/internal/helpers/sheet_batch.go index 664bc4ae..7ce6e17d 100644 --- a/internal/helpers/sheet_batch.go +++ b/internal/helpers/sheet_batch.go @@ -74,10 +74,10 @@ func translateBatchOp(op map[string]any) (map[string]any, error) { func validateBatchSetDropdownInput(input map[string]any) error { if _, exists := input["source-colors"]; exists { - return fmt.Errorf("set-dropdown: SourceRange 颜色写入暂不支持") + return fmt.Errorf("set-dropdown: 顶层 source-colors 不受支持；Inline 颜色请写入 options[].color，SourceRange 颜色写入暂不支持") } if _, exists := input["colors"]; exists { - return fmt.Errorf("set-dropdown: SourceRange 颜色写入暂不支持") + return fmt.Errorf("set-dropdown: 顶层 colors 不受支持；Inline 颜色请写入 options[].color，SourceRange 颜色写入暂不支持") } options, hasOptions := input["options"] @@ -92,7 +92,7 @@ func validateBatchSetDropdownInput(input map[string]any) error { return fmt.Errorf("set-dropdown: source-range 与 source-sheet-id 必须同时指定") } if hasSourceRange { - if err := validateDropdownSourceRangeNotation(sourceRange); err != nil { + if err := validateDropdownSourceRangeInput(sourceSheetID, sourceRange); err != nil { return fmt.Errorf("set-dropdown: %w", err) } } @@ -457,6 +457,8 @@ func newBatchUpdateCmd() *cobra.Command { toolName 使用 CLI 命令名（与原子命令一致），input 的键用 CLI flag 名去掉 --。 CLI 层自动翻译为 MCP toolName + 参数名，无需记忆 MCP 参数名。 +source-range 的语义按 toolName 隔离：set-dropdown 中表示下拉候选项来源， +range fill/copy-to/move-to 中表示待填充、复制或移动的数据源区域。 支持的 CLI 命令名: range clear / range update / merge-cells / unmerge-cells / update-dimension @@ -465,6 +467,8 @@ CLI 层自动翻译为 MCP toolName + 参数名，无需记忆 MCP 参数名。 set-dropdown / delete-dropdown / csv-put / delete-float-image 其中 csv-put 与独立命令语义一致：CSV 字段值以 = 开头时按公式解析， 前加单引号（例如 "'=1+1"）时写入以 = 开头的字面文本。 +set-dropdown 不接受顶层 colors/source-colors；Inline 颜色应写在 options[].color， +SourceRange 颜色写入暂不支持。 注意：batch-update 中 group-dimension 适合默认展开分组；需要 --group-state fold 时请使用独立 dws sheet group-dimension 命令。 diff --git a/internal/helpers/sheet_dimension.go b/internal/helpers/sheet_dimension.go index 1b902cc6..4afaf750 100644 --- a/internal/helpers/sheet_dimension.go +++ b/internal/helpers/sheet_dimension.go @@ -19,7 +19,14 @@ func sizeTypeEnumHint(dimension string) string { return "pixel / standard" } -func validateDropdownSourceRangeNotation(sourceRange string) error { +func validateDropdownSourceRangeInput(sourceSheetID, sourceRange string) error { + if strings.TrimSpace(sourceSheetID) == "" { + return fmt.Errorf("--source-sheet-id 不能为空") + } + sourceRange = strings.TrimSpace(sourceRange) + if sourceRange == "" { + return fmt.Errorf("--source-range 不能为空") + } if strings.Contains(sourceRange, "!") { return fmt.Errorf("--source-range 不能包含工作表前缀；请通过 --source-sheet-id 指定来源工作表") } @@ -801,8 +808,9 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 --source-range 只接受不含工作表前缀的 A1 区域，例如 T1:T3、T:T 或 1:3； 来源工作表由 --source-sheet-id 单独指定。SourceRange 颜色写入暂不支持。 -已知限制：服务端写入的 SourceRange 不会在工作表重命名或行列插入、删除、移动后 -自动更新；执行这些结构操作后应重新写入下拉来源。`, +已验证行为：工作表重命名、在引用前插入行/列、删除引用前的行会自动调整引用并保持 valid； +已验证的 move-dimension 场景会使引用变为 invalid。列删除、删除整个来源区域或来源工作表等未覆盖场景不能预设结果； +结构操作后应先回读 sourceRangeStatus，只有 invalid 时才重新选择来源并写入。`, Example: ` # 设置单选下拉列表 dws sheet set-dropdown --node NODE_ID --sheet-id SHEET_ID --range "A2:A100" \ --options '[{"value":"选项1"},{"value":"选项2"},{"value":"选项3"}]' @@ -862,7 +870,7 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 } toolArgs["options"] = options } else { - if err := validateDropdownSourceRangeNotation(sourceRange); err != nil { + if err := validateDropdownSourceRangeInput(sourceSheetID, sourceRange); err != nil { return err } toolArgs["sourceRange"] = map[string]any{ @@ -930,7 +938,8 @@ sheetId 支持传入工作表 ID 或工作表名称，可通过 sheet list 获 Long: `查询钉钉表格指定范围内的下拉列表配置。 Inline 配置返回 conditionValues 和 options；SourceRange 配置返回 -sourceType/sourceRange/sourceRangeStatus/enableMultiSelect，不展开来源区域的候选值或颜色。 +sourceType/sourceRangeStatus/enableMultiSelect，且仅在 sourceRangeStatus="valid" 时返回 +sourceRange。invalid 结果仍保留配置组，但省略 sourceRange；两种状态都不展开来源区域的候选值或颜色。 如果范围内存在多个不同的下拉列表配置，会分别返回每组配置及其覆盖的单元格列表。 如果范围内没有设置下拉列表，返回空。 diff --git a/internal/helpers/sheet_dropdown_source_range_test.go b/internal/helpers/sheet_dropdown_source_range_test.go index 071e8ba4..086b7da6 100644 --- a/internal/helpers/sheet_dropdown_source_range_test.go +++ b/internal/helpers/sheet_dropdown_source_range_test.go @@ -74,6 +74,8 @@ func TestCrossPlatformCoverageSetDropdownModeConstraints(t *testing.T) { {name: "sheet prefix", args: []string{"--source-sheet-id", "source", "--source-range", "Sheet2!A1:A3"}, want: "不能包含工作表前缀"}, {name: "formula", args: []string{"--source-sheet-id", "source", "--source-range", "=A1:A3"}, want: "必须是单一连续区域"}, {name: "multi region", args: []string{"--source-sheet-id", "source", "--source-range", "A1:A3,C1:C3"}, want: "必须是单一连续区域"}, + {name: "blank source range", args: []string{"--source-sheet-id", "source", "--source-range", " \t "}, want: "--source-range 不能为空"}, + {name: "blank source sheet", args: []string{"--source-sheet-id", " \t ", "--source-range", "A1:A3"}, want: "--source-sheet-id 不能为空"}, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { @@ -169,6 +171,56 @@ func TestCrossPlatformCoverageBatchSetDropdownSourceRange(t *testing.T) { } } +func TestCrossPlatformCoverageBatchSetDropdownValidationGuidance(t *testing.T) { + tests := []struct { + name string + input map[string]any + want string + }{ + { + name: "inline top-level colors", + input: map[string]any{"options": []any{map[string]any{"value": "one"}}, "colors": []any{"#fff"}}, + want: "Inline 颜色请写入 options[].color", + }, + { + name: "source top-level colors", + input: map[string]any{"source-sheet-id": "source", "source-range": "A1:A3", "source-colors": []any{"#fff"}}, + want: "SourceRange 颜色写入暂不支持", + }, + { + name: "blank source range", + input: map[string]any{"source-sheet-id": "source", "source-range": " \t "}, + want: "--source-range 不能为空", + }, + { + name: "blank source sheet", + input: map[string]any{"source-sheet-id": " \t ", "source-range": "A1:A3"}, + want: "--source-sheet-id 不能为空", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + _, err := translateBatchOp(map[string]any{"toolName": "set-dropdown", "input": tc.input}) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want contains %q", err, tc.want) + } + }) + } +} + +func TestCrossPlatformCoverageDropdownHelpDescribesDynamicAndInvalidContracts(t *testing.T) { + setDropdown := dimensionCoverageCommand(t, "set-dropdown") + if !strings.Contains(setDropdown.Long, "会自动调整引用并保持 valid") || + !strings.Contains(setDropdown.Long, "只有 invalid 时才重新选择来源并写入") { + t.Fatalf("set-dropdown help does not describe verified structural behavior:\n%s", setDropdown.Long) + } + getDropdown := dimensionCoverageCommand(t, "get-dropdown") + if !strings.Contains(getDropdown.Long, `仅在 sourceRangeStatus="valid" 时返回`) || + !strings.Contains(getDropdown.Long, "invalid 结果仍保留配置组，但省略 sourceRange") { + t.Fatalf("get-dropdown help does not describe conditional sourceRange readback:\n%s", getDropdown.Long) + } +} + func TestCrossPlatformCoverageValidateSourceRangeDataValidation(t *testing.T) { valid := []any{ map[string]any{"type": "dropdown", "sourceRange": map[string]any{"sheetId": "source", "a1Notation": "T1:T3"}}, diff --git a/internal/helpers/sheet_range_ops.go b/internal/helpers/sheet_range_ops.go index 8bd07dc9..1c3a8fb5 100644 --- a/internal/helpers/sheet_range_ops.go +++ b/internal/helpers/sheet_range_ops.go @@ -184,7 +184,7 @@ dws sheet info --node NODE_ID --sheet-id SHEET_ID --format json，并读取 merg - 只设样式或批量刷整片区域样式请用 dws sheet range set-style；写值同时设置少量 cell 样式可用 cellStyles - 目标范围与已有合并区域冲突时，range update 会返回 MERGED_CELLS_CONFLICT；先用 sheet info 查看 mergedRanges，取消合并后写入，必要时再重新合并 - csv-put 的合并处理不同：目标区域含合并单元格时会打散合并并写入 CSV 值或公式 - - SourceRange 当前不会随工作表重命名或行列结构调整自动更新；执行结构操作后应重新写入 + - SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；move-dimension 及其他未覆盖的删除/移动场景后先回读 sourceRangeStatus，仅 invalid 时重新选源写入 - 同一 cell 的 value/style 已写入但 SourceRange 校验失败时，服务端可返回 success=true，并通过 message 明确下拉未创建；必须检查 message，必要时重新读取确认 - 清空整片区域请用 dws sheet range clear`, Example: ` # 写入文本 diff --git a/skills/mono/references/products/sheet/sheet-batch-operations.md b/skills/mono/references/products/sheet/sheet-batch-operations.md index 4654840f..66fafc90 100644 --- a/skills/mono/references/products/sheet/sheet-batch-operations.md +++ b/skills/mono/references/products/sheet/sheet-batch-operations.md @@ -102,7 +102,9 @@ Notes: - operations 最多 20 条 - 当需要对多个区域执行相同清除时，优先使用 `range batch-clear`（更简洁） - `csv-put` 子操作与独立命令语义一致：CSV 字段值以 `=` 开头时按公式解析；前加单引号时写入以 `=` 开头的字面文本 - - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。SourceRange 颜色写入暂不支持，且不会随 sheet 重命名或行列结构操作自动更新 + - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。顶层 `colors` / `source-colors` 会被拒绝；Inline 颜色写在 `options[].color`，SourceRange 颜色写入暂不支持 + - `set-dropdown` SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读，仅 `invalid` 时重新选源写入 + - `source-range` 按 `toolName` 解释：`set-dropdown` 中是下拉候选项来源；`range fill` / `range copy-to` / `range move-to` 中是待填充、复制或移动的数据源区域 - 典型场景：先插入行列再写入数据、先清除再写入、批量合并+调整行高列宽 - `group-dimension` 在 batch 中只适合默认展开分组；需要 `--group-state fold` 时请使用独立 `dws sheet group-dimension` - `table-put` 不支持放进 batch-update；结构化 table 请用独立 `dws sheet table-put` diff --git a/skills/mono/references/products/sheet/sheet-dropdown.md b/skills/mono/references/products/sheet/sheet-dropdown.md index b6e2e658..05b5f0c0 100644 --- a/skills/mono/references/products/sheet/sheet-dropdown.md +++ b/skills/mono/references/products/sheet/sheet-dropdown.md @@ -48,7 +48,7 @@ Flags: - **用途**：为单元格配置静态选项或区域来源下拉，两种模式都支持多选；颜色仅 Inline 支持。 - **场景**：规范数据输入，如状态选择（完成/进行中/待处理）、优先级（高/中/低）等。 - **注意**：`--options` 与 `--source-range` 必须且只能指定一个。`--source-range` 只写 `T1:T3`、`T:T`、`1:3` 这类 A1 区域，来源工作表通过 `--source-sheet-id` 单独指定；不接受工作表前缀、公式或多区域。SourceRange 颜色写入暂不支持。 -- **静态引用限制**：服务端写入的 SourceRange 不会随工作表重命名或行列插入、删除、移动自动更新；结构操作后应重新写入该下拉来源。 +- **结构操作行为**：已验证的工作表重命名、在引用前插入行/列、删除引用前的行会自动调整引用并保持 `valid`；已验证的 `move-dimension` 场景会使其变为 `invalid`。列删除、删除整个来源区域或来源工作表等场景未覆盖，不能预设结果；结构操作后先回读 `sourceRangeStatus`，仅在 `invalid` 时重新选择来源并写入。 ### 获取下拉列表配置 ``` @@ -66,7 +66,7 @@ Flags: 查询指定范围内的下拉列表配置信息。 - **用途**：查看单元格已设置的下拉列表选项和配置。 - **场景**：在修改下拉列表前先查询现有配置；确认下拉列表是否设置成功。 -- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`sourceRange:{sheetId,a1Notation}`、`enableMultiSelect` 和 `ranges`，不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 +- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组始终返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`enableMultiSelect` 和 `ranges`，仅在 `sourceRangeStatus:"valid"` 时返回 `sourceRange:{sheetId,a1Notation}`。`invalid` 时仍保留配置组，但省略 `sourceRange`，不得依赖旧坐标修复。SourceRange 不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 ### 删除下拉列表 ``` @@ -98,6 +98,6 @@ Flags: - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等） - `set-dropdown` 的 Inline 模式使用 `--options`，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB`）；SourceRange 模式使用 `--source-sheet-id` + `--source-range`。两种模式均可用 `--multi-select`，并会覆盖目标范围已有下拉 -- SourceRange 当前是静态引用，不会随 sheet 重命名或行列结构操作自动调整；颜色写入暂不支持 -- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，不回退展开候选值 +- SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读，仅 `invalid` 时重新选源写入；颜色写入暂不支持 +- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，但省略 `sourceRange`，不回退展开候选值 - `delete-dropdown` 删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。已填写的值不会被清除。目标范围不存在下拉列表时操作仍返回成功 diff --git a/skills/mono/references/products/sheet/sheet-read-data.md b/skills/mono/references/products/sheet/sheet-read-data.md index 4963fc2a..f8008d0e 100644 --- a/skills/mono/references/products/sheet/sheet-read-data.md +++ b/skills/mono/references/products/sheet/sheet-read-data.md @@ -160,11 +160,11 @@ Flags: | `dropdown` Inline | `options: [{value: string, color?: string}]` | 下拉选项列表 | | `dropdown` Inline | `enableMultiSelect: boolean` | 是否允许多选 | | `dropdown` SourceRange | `sourceType: "sourceRange"` | 区域来源模式 | -| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 同一工作簿内的来源工作表和规范化 A1 区域 | -| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置 | +| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 仅 `sourceRangeStatus:"valid"` 时返回的来源工作表和规范化 A1 区域；`invalid` 时省略 | +| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置，但不返回 `sourceRange` | | `checkbox` | `checked: boolean` | 当前勾选状态 | -SourceRange 模式只返回引用元数据，不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。 +SourceRange 模式不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。`invalid` 时只能依赖 `sourceRangeStatus` 判定需要重新选源，不得假定仍能从 `sourceRange` 取回旧坐标。 **hyperlink 结构**： diff --git a/skills/mono/references/products/sheet/sheet-write-data.md b/skills/mono/references/products/sheet/sheet-write-data.md index d2e61e65..9050fb43 100644 --- a/skills/mono/references/products/sheet/sheet-write-data.md +++ b/skills/mono/references/products/sheet/sheet-write-data.md @@ -392,7 +392,7 @@ Flags: - Inline：`options` 为非空 `[{value, color?}]` 数组 - SourceRange：`sourceRange` 为 `{sheetId,a1Notation}`；可引用同一工作簿内其他工作表，支持普通区域、整行和整列。`a1Notation` 不带工作表前缀，不接受公式或多区域；颜色写入暂不支持 - `enableMultiSelect`：可选，是否多选，默认 false -- SourceRange 当前不会随工作表重命名或行列插入、删除、移动自动更新，结构操作后应重新写入 +- SourceRange 在已验证的工作表重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读 `sourceRangeStatus`，仅 `invalid` 时重新选源写入 - 复合 cell 写入中，如果值或样式已成功落盘但 SourceRange 校验失败，服务端可返回 `success:true` 并通过 `message` 说明下拉未创建；必须检查 `message` 并按需回读 **checkbox（复选框）**： diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md b/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md index 4654840f..66fafc90 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-batch-operations.md @@ -102,7 +102,9 @@ Notes: - operations 最多 20 条 - 当需要对多个区域执行相同清除时，优先使用 `range batch-clear`（更简洁） - `csv-put` 子操作与独立命令语义一致：CSV 字段值以 `=` 开头时按公式解析；前加单引号时写入以 `=` 开头的字面文本 - - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。SourceRange 颜色写入暂不支持，且不会随 sheet 重命名或行列结构操作自动更新 + - `set-dropdown` 的 `input` 中，Inline 使用 `options`；SourceRange 使用 `source-sheet-id` + `source-range`，两种模式必须且只能选一个。顶层 `colors` / `source-colors` 会被拒绝；Inline 颜色写在 `options[].color`，SourceRange 颜色写入暂不支持 + - `set-dropdown` SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读，仅 `invalid` 时重新选源写入 + - `source-range` 按 `toolName` 解释：`set-dropdown` 中是下拉候选项来源；`range fill` / `range copy-to` / `range move-to` 中是待填充、复制或移动的数据源区域 - 典型场景：先插入行列再写入数据、先清除再写入、批量合并+调整行高列宽 - `group-dimension` 在 batch 中只适合默认展开分组；需要 `--group-state fold` 时请使用独立 `dws sheet group-dimension` - `table-put` 不支持放进 batch-update；结构化 table 请用独立 `dws sheet table-put` diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md b/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md index b6e2e658..05b5f0c0 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-dropdown.md @@ -48,7 +48,7 @@ Flags: - **用途**：为单元格配置静态选项或区域来源下拉，两种模式都支持多选；颜色仅 Inline 支持。 - **场景**：规范数据输入，如状态选择（完成/进行中/待处理）、优先级（高/中/低）等。 - **注意**：`--options` 与 `--source-range` 必须且只能指定一个。`--source-range` 只写 `T1:T3`、`T:T`、`1:3` 这类 A1 区域，来源工作表通过 `--source-sheet-id` 单独指定；不接受工作表前缀、公式或多区域。SourceRange 颜色写入暂不支持。 -- **静态引用限制**：服务端写入的 SourceRange 不会随工作表重命名或行列插入、删除、移动自动更新；结构操作后应重新写入该下拉来源。 +- **结构操作行为**：已验证的工作表重命名、在引用前插入行/列、删除引用前的行会自动调整引用并保持 `valid`；已验证的 `move-dimension` 场景会使其变为 `invalid`。列删除、删除整个来源区域或来源工作表等场景未覆盖，不能预设结果；结构操作后先回读 `sourceRangeStatus`，仅在 `invalid` 时重新选择来源并写入。 ### 获取下拉列表配置 ``` @@ -66,7 +66,7 @@ Flags: 查询指定范围内的下拉列表配置信息。 - **用途**：查看单元格已设置的下拉列表选项和配置。 - **场景**：在修改下拉列表前先查询现有配置；确认下拉列表是否设置成功。 -- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`sourceRange:{sheetId,a1Notation}`、`enableMultiSelect` 和 `ranges`，不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 +- **返回**：`dataValidations` 数组由底层按配置聚合。Inline 组返回 `sourceType:"inline"`、`conditionValues`、`ranges` 和 `options`；SourceRange 组始终返回 `sourceType:"sourceRange"`、`sourceRangeStatus:"valid"/"invalid"`、`enableMultiSelect` 和 `ranges`，仅在 `sourceRangeStatus:"valid"` 时返回 `sourceRange:{sheetId,a1Notation}`。`invalid` 时仍保留配置组，但省略 `sourceRange`，不得依赖旧坐标修复。SourceRange 不会展开候选值，因此不返回 `conditionValues`、`options` 或颜色。范围内无下拉列表时 `hasDropdown` 为 false。 ### 删除下拉列表 ``` @@ -98,6 +98,6 @@ Flags: - ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等） - `set-dropdown` 的 Inline 模式使用 `--options`，每个元素包含 `value`（必填）和 `color`（可选，`#RRGGBB`）；SourceRange 模式使用 `--source-sheet-id` + `--source-range`。两种模式均可用 `--multi-select`，并会覆盖目标范围已有下拉 -- SourceRange 当前是静态引用，不会随 sheet 重命名或行列结构操作自动调整；颜色写入暂不支持 -- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，不回退展开候选值 +- SourceRange 在已验证的重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读，仅 `invalid` 时重新选源写入；颜色写入暂不支持 +- `get-dropdown` 查询指定范围内的下拉配置，聚合发生在底层服务。SourceRange 即使无效也保留一组并以 `sourceRangeStatus:"invalid"` 表示，但省略 `sourceRange`，不回退展开候选值 - `delete-dropdown` 删除指定范围内的下拉列表配置，单元格恢复为普通文本格式。已填写的值不会被清除。目标范围不存在下拉列表时操作仍返回成功 diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md b/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md index 4963fc2a..f8008d0e 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-read-data.md @@ -160,11 +160,11 @@ Flags: | `dropdown` Inline | `options: [{value: string, color?: string}]` | 下拉选项列表 | | `dropdown` Inline | `enableMultiSelect: boolean` | 是否允许多选 | | `dropdown` SourceRange | `sourceType: "sourceRange"` | 区域来源模式 | -| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 同一工作簿内的来源工作表和规范化 A1 区域 | -| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置 | +| `dropdown` SourceRange | `sourceRange: {sheetId, a1Notation}` | 仅 `sourceRangeStatus:"valid"` 时返回的来源工作表和规范化 A1 区域；`invalid` 时省略 | +| `dropdown` SourceRange | `sourceRangeStatus: "valid" / "invalid"` | 底层引用是否可解析；无效引用仍返回配置，但不返回 `sourceRange` | | `checkbox` | `checked: boolean` | 当前勾选状态 | -SourceRange 模式只返回引用元数据，不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。 +SourceRange 模式不动态拉取或展开来源区域的候选值，因此不返回 `options` 或颜色。`invalid` 时只能依赖 `sourceRangeStatus` 判定需要重新选源，不得假定仍能从 `sourceRange` 取回旧坐标。 **hyperlink 结构**： diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md b/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md index d2e61e65..9050fb43 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-write-data.md @@ -392,7 +392,7 @@ Flags: - Inline：`options` 为非空 `[{value, color?}]` 数组 - SourceRange：`sourceRange` 为 `{sheetId,a1Notation}`；可引用同一工作簿内其他工作表，支持普通区域、整行和整列。`a1Notation` 不带工作表前缀，不接受公式或多区域；颜色写入暂不支持 - `enableMultiSelect`：可选，是否多选，默认 false -- SourceRange 当前不会随工作表重命名或行列插入、删除、移动自动更新，结构操作后应重新写入 +- SourceRange 在已验证的工作表重命名、引用前插入行/列、删除引用前行的场景会自动调整；已验证的 `move-dimension` 会使其变为 `invalid`。其他未覆盖删除/移动场景后先回读 `sourceRangeStatus`，仅 `invalid` 时重新选源写入 - 复合 cell 写入中，如果值或样式已成功落盘但 SourceRange 校验失败，服务端可返回 `success:true` 并通过 `message` 说明下拉未创建；必须检查 `message` 并按需回读 **checkbox（复选框）**： From 8560830d3e1556fd7449061aef17053f1bd3b19e Mon Sep 17 00:00:00 2001 From: zearlin Date: Sat, 15 Aug 2026 15:58:31 +0800 Subject: [PATCH 141/250] feat: add privacy-safe clitrack telemetry (#1009) Co-authored-by: zearlin Co-authored-by: chichuan <30925823+haofeng0705@users.noreply.github.com> --- .changes/1009-clitrack-telemetry.md | 5 + .gitignore | 4 + cmd/main.go | 68 ++++- cmd/main_test.go | 219 +++++++++++++- go.mod | 3 + internal/app/framework_coverage_test.go | 114 +++++++- internal/app/profile_args_test.go | 26 ++ internal/app/root.go | 118 ++++++-- internal/app/root_full_coverage_test.go | 55 +++- .../app/root_lifecycle_regression_test.go | 2 +- internal/app/root_output_atomic_test.go | 13 +- internal/app/root_unified_output_test.go | 2 +- internal/app/signal_test.go | 6 +- internal/app/telemetry_error.go | 143 +++++++++ internal/app/telemetry_error_test.go | 99 +++++++ internal/app/telemetry_identity.go | 86 ++++++ internal/app/telemetry_identity_test.go | 147 ++++++++++ internal/auth/profile_metadata_readonly.go | 70 +++++ .../auth/profile_metadata_readonly_test.go | 97 ++++++ third_party/aem-go-sdk/README.md | 20 ++ third_party/aem-go-sdk/aem/config.go | 264 +++++++++++++++++ third_party/aem-go-sdk/aem/config_test.go | 54 ++++ third_party/aem-go-sdk/aem/event.go | 36 +++ third_party/aem-go-sdk/aem/tracker.go | 173 +++++++++++ third_party/aem-go-sdk/clitrack/capture.go | 37 +++ third_party/aem-go-sdk/clitrack/clitrack.go | 275 ++++++++++++++++++ .../aem-go-sdk/clitrack/clitrack_test.go | 21 ++ third_party/aem-go-sdk/clitrack/doc.go | 51 ++++ third_party/aem-go-sdk/clitrack/fields.go | 44 +++ third_party/aem-go-sdk/go.mod | 3 + .../aem-go-sdk/internal/encoder/gokey.go | 97 ++++++ .../aem-go-sdk/internal/sender/sender.go | 68 +++++ 32 files changed, 2369 insertions(+), 51 deletions(-) create mode 100644 .changes/1009-clitrack-telemetry.md create mode 100644 internal/app/telemetry_error.go create mode 100644 internal/app/telemetry_error_test.go create mode 100644 internal/app/telemetry_identity.go create mode 100644 internal/app/telemetry_identity_test.go create mode 100644 internal/auth/profile_metadata_readonly.go create mode 100644 internal/auth/profile_metadata_readonly_test.go create mode 100644 third_party/aem-go-sdk/README.md create mode 100644 third_party/aem-go-sdk/aem/config.go create mode 100644 third_party/aem-go-sdk/aem/config_test.go create mode 100644 third_party/aem-go-sdk/aem/event.go create mode 100644 third_party/aem-go-sdk/aem/tracker.go create mode 100644 third_party/aem-go-sdk/clitrack/capture.go create mode 100644 third_party/aem-go-sdk/clitrack/clitrack.go create mode 100644 third_party/aem-go-sdk/clitrack/clitrack_test.go create mode 100644 third_party/aem-go-sdk/clitrack/doc.go create mode 100644 third_party/aem-go-sdk/clitrack/fields.go create mode 100644 third_party/aem-go-sdk/go.mod create mode 100644 third_party/aem-go-sdk/internal/encoder/gokey.go create mode 100644 third_party/aem-go-sdk/internal/sender/sender.go diff --git a/.changes/1009-clitrack-telemetry.md b/.changes/1009-clitrack-telemetry.md new file mode 100644 index 00000000..f5289dce --- /dev/null +++ b/.changes/1009-clitrack-telemetry.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **Privacy-safe CLI telemetry** (#1009) — reports reviewed command outcomes and profile identity dimensions while excluding command arguments, output, paths, device fingerprints, and automatic system dimensions; `DO_NOT_TRACK=1` disables reporting. diff --git a/.gitignore b/.gitignore index 2f5bbe69..dfb5ee3d 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,10 @@ test/cli_compat/testdata/ .gitignore .worktrees/ .qoder/ +_logs/ +_docs/ +_output/ +vendor/ # Secrets & credentials .env diff --git a/cmd/main.go b/cmd/main.go index 4ac7a562..f5ed1cc9 100644 --- a/cmd/main.go +++ b/cmd/main.go @@ -15,12 +15,76 @@ package main import ( "os" + "strings" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app" + "gitlab.alibaba-inc.com/aes/aem-go-sdk/clitrack" ) -var exit = os.Exit +var ( + appExecute = app.ExecuteWithTelemetry + resolveTelemetryIdentity = app.ResolveTelemetryIdentity + trackRun = func(cfg clitrack.Config, execute func() error, exitCode func(error) int) { + clitrack.New(cfg).Run(execute, exitCode) + } +) + +// trackedExitError tells clitrack that the command failed without asking it to +// print the error a second time. The already-rendered message is published via +// ExtraFields c5, while app.Execute remains the sole owner of presentation. +type trackedExitError struct{} + +func (trackedExitError) Error() string { return "" } + +func trackerConfig(identity app.TelemetryIdentity, commandPath, errorMessage *string) clitrack.Config { + return clitrack.Config{ + PID: "wcCRwZ", + App: "dws", + Version: app.RawVersion(), + UID: identity.UserID, + Username: identity.UserName, + NoCommandLine: true, + NoCwd: true, + NoAutomaticDimensions: true, + ExtraFields: func() map[string]string { + fields := map[string]string{"c9": *commandPath} + if identity.CorpID != "" { + fields["c10"] = identity.CorpID + } + if *errorMessage != "" { + fields["c5"] = *errorMessage + } + return fields + }, + } +} + +func telemetryOptedOut() bool { + return strings.TrimSpace(os.Getenv("DO_NOT_TRACK")) != "" +} func main() { - exit(app.Execute()) + optedOut := telemetryOptedOut() + identity := app.TelemetryIdentity{} + if !optedOut { + identity = resolveTelemetryIdentity(os.Args[1:]) + } + exitCode := 0 + commandPath := "dws" + errorMessage := "" + cfg := trackerConfig(identity, &commandPath, &errorMessage) + if optedOut { + cfg.PID = "" + } + trackRun( + cfg, + func() error { + exitCode, commandPath, errorMessage = appExecute() + if exitCode != 0 { + return trackedExitError{} + } + return nil + }, + func(error) int { return exitCode }, + ) } diff --git a/cmd/main_test.go b/cmd/main_test.go index 6b9fd350..babd7aae 100644 --- a/cmd/main_test.go +++ b/cmd/main_test.go @@ -1,27 +1,220 @@ package main import ( + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" "os" + "slices" + "sort" + "strings" "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" + "gitlab.alibaba-inc.com/aes/aem-go-sdk/clitrack" ) -func TestCrossPlatformCoverageMainExitsWithSuccessfulVersionCommand(t *testing.T) { - previousExit := exit - previousArgs := os.Args - t.Cleanup(func() { - exit = previousExit - os.Args = previousArgs - }) +func TestCrossPlatformCoverageMainRunsThroughCLITracker(t *testing.T) { + for _, wantCode := range []int{0, 1, 3, 5} { + t.Run(fmt.Sprintf("exit_%d", wantCode), func(t *testing.T) { + t.Setenv("DO_NOT_TRACK", "") + wantError := "" + if wantCode != 0 { + wantError = "synthetic failure" + } + testseam.Swap(t, &os.Args, []string{"dws", "sheet", "read", "--profile", "corp-a"}) + testseam.Swap(t, &resolveTelemetryIdentity, func(args []string) app.TelemetryIdentity { + if strings.Join(args, " ") != "sheet read --profile corp-a" { + t.Fatalf("telemetry identity args = %#v", args) + } + return app.TelemetryIdentity{UserID: "user-1", UserName: "Alice", CorpID: "corp-1"} + }) + testseam.Swap(t, &appExecute, func() (int, string, string) { return wantCode, "sheet read", wantError }) + called := false + testseam.Swap(t, &trackRun, func(cfg clitrack.Config, execute func() error, exitCode func(error) int) { + called = true + if cfg.PID != "wcCRwZ" || cfg.App != "dws" { + t.Fatalf("tracker identity = PID %q App %q", cfg.PID, cfg.App) + } + if cfg.Version != app.RawVersion() { + t.Fatalf("tracker Version = %q, want %q", cfg.Version, app.RawVersion()) + } + if !cfg.NoCommandLine || !cfg.NoCwd || !cfg.NoAutomaticDimensions || cfg.CaptureOutput { + t.Fatalf("tracker privacy config = NoCommandLine %v NoCwd %v NoAutomaticDimensions %v CaptureOutput %v", cfg.NoCommandLine, cfg.NoCwd, cfg.NoAutomaticDimensions, cfg.CaptureOutput) + } + if cfg.Env != "" || cfg.EventID != "" || cfg.Endpoint != "" || cfg.FlushTimeout != 0 || cfg.OutputMaxLen != 0 { + t.Fatalf("tracker SDK defaults were overridden: %#v", cfg) + } + if cfg.UID != "user-1" || cfg.Username != "Alice" || cfg.UserType != "" { + t.Fatalf("tracker user identity = UID %q Username %q UserType %q", cfg.UID, cfg.Username, cfg.UserType) + } + err := execute() + if wantCode == 0 && err != nil { + t.Fatalf("successful tracked execute error = %v", err) + } + if wantCode != 0 && (err == nil || err.Error() != "") { + t.Fatalf("failed tracked execute error = %#v, want empty sentinel", err) + } + if gotCode := exitCode(err); gotCode != wantCode { + t.Fatalf("tracked exit code = %d, want %d", gotCode, wantCode) + } + fields := cfg.ExtraFields() + if fields["c9"] != "sheet read" || fields["c10"] != "corp-1" || fields["c5"] != wantError { + t.Fatalf("tracker extra fields = %#v, want command path, corp ID, and error %q", fields, wantError) + } + if (wantError == "" && len(fields) != 2) || (wantError != "" && len(fields) != 3) { + t.Fatalf("tracker extra field count = %d for error %q", len(fields), wantError) + } + }) + + main() + if !called { + t.Fatalf("trackRun was not called for exit code %d", wantCode) + } + }) + } +} + +func TestCrossPlatformCoverageTrackerConfigOmitsEmptyOrganization(t *testing.T) { + commandPath := "version" + errorMessage := "" + cfg := trackerConfig(app.TelemetryIdentity{}, &commandPath, &errorMessage) + if cfg.UID != "" { + t.Fatalf("empty identity UID = %q", cfg.UID) + } + if cfg.Username != "" { + t.Fatalf("empty identity Username = %q", cfg.Username) + } + if fields := cfg.ExtraFields(); len(fields) != 1 || fields["c9"] != "version" { + t.Fatalf("empty organization fields = %#v", fields) + } +} + +func TestCrossPlatformCoverageDefaultTrackRunNoopTracker(t *testing.T) { called := false - code := -1 - exit = func(value int) { + trackRun(clitrack.Config{}, func() error { called = true - code = value + return nil + }, nil) + if !called { + t.Fatal("default tracker did not execute callback") } - os.Args = []string{"dws", "version"} +} + +func TestCrossPlatformCoverageMainRespectsDoNotTrack(t *testing.T) { + t.Setenv("DO_NOT_TRACK", "1") + testseam.Swap(t, &os.Args, []string{"dws", "version"}) + testseam.Swap(t, &resolveTelemetryIdentity, func([]string) app.TelemetryIdentity { + t.Fatal("DO_NOT_TRACK must skip telemetry identity reads") + return app.TelemetryIdentity{} + }) + testseam.Swap(t, &appExecute, func() (int, string, string) { return 0, "version", "" }) + testseam.Swap(t, &trackRun, func(cfg clitrack.Config, execute func() error, exitCode func(error) int) { + if cfg.PID != "" || cfg.UID != "" || cfg.Username != "" { + t.Fatalf("opted-out tracker config = %#v", cfg) + } + if err := execute(); err != nil { + t.Fatalf("opted-out execution failed: %v", err) + } + if code := exitCode(nil); code != 0 { + t.Fatalf("opted-out exit code = %d, want 0", code) + } + }) + main() - if !called || code != 0 { - t.Fatalf("main exit = called %v, code %d", called, code) +} + +func TestCrossPlatformCoverageTrackerPayloadUsesReviewedFieldWhitelist(t *testing.T) { + testseam.Protect(t, &os.Args) + os.Args = []string{"dws", "sheet", "read", "--access-token", "must-not-leak"} + t.Setenv("SHELL", "/bin/zsh") + t.Setenv("TERM_SESSION_ID", "stable-session") + t.Setenv("TMUX_PANE", "%42") + t.Setenv("LANG", "zh_CN.UTF-8") + t.Setenv("LC_ALL", "zh_CN.UTF-8") + t.Chdir(t.TempDir()) + + requestBody := make(chan []byte, 1) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + body, _ := io.ReadAll(req.Body) + requestBody <- body + w.WriteHeader(http.StatusNoContent) + })) + defer server.Close() + + commandPath := "sheet read" + errorMessage := "" + cfg := trackerConfig(app.TelemetryIdentity{UserID: "user-1", UserName: "Alice", CorpID: "corp-1"}, &commandPath, &errorMessage) + cfg.Endpoint = server.URL + cfg.FlushTimeout = time.Second + clitrack.New(cfg).Run(func() error { return nil }, nil) + + var body []byte + select { + case body = <-requestBody: + case <-time.After(time.Second): + t.Fatal("timed out waiting for telemetry request") + } + var envelope map[string]string + if err := json.Unmarshal(body, &envelope); err != nil { + t.Fatalf("decode telemetry request %q: %v", body, err) + } + decoded, err := url.QueryUnescape(envelope["gokey"]) + if err != nil { + t.Fatalf("decode gokey: %v", err) + } + globalFields, err := url.ParseQuery(decoded) + if err != nil { + t.Fatalf("parse global telemetry fields: %v", err) + } + eventFields, err := url.ParseQuery(globalFields.Get("msg")) + if err != nil { + t.Fatalf("parse event telemetry fields: %v", err) + } + + assertTelemetryKeys(t, globalFields, []string{"app_name", "app_version", "env", "msg", "pid", "platform", "uid", "username", "version"}) + assertTelemetryKeys(t, eventFields, []string{"c1", "c10", "c3", "c4", "c9", "p1", "p4", "ts", "type"}) + for key, want := range map[string]string{ + "app_name": "dws", "app_version": app.RawVersion(), "env": "prod", "pid": "wcCRwZ", + "platform": "cli", "uid": "user-1", "username": "Alice", "version": app.RawVersion(), + } { + if got := globalFields.Get(key); got != want { + t.Fatalf("global telemetry field %s = %q, want %q", key, got, want) + } + } + for key, want := range map[string]string{ + "type": "event", "p1": "cli.exec", "p4": "SYS", "c1": "dws", "c3": "0", "c9": "sheet read", "c10": "corp-1", + } { + if got := eventFields.Get(key); got != want { + t.Fatalf("event telemetry field %s = %q, want %q", key, got, want) + } + } + for _, key := range []string{"device_id", "ext", "os", "os_version", "pv_id", "sdk_version", "sid", "timezone_offset"} { + if globalFields.Has(key) { + t.Fatalf("global telemetry leaked %s: %q", key, decoded) + } + } + for _, key := range []string{"c2", "c5", "c6", "c7", "c8"} { + if eventFields.Has(key) { + t.Fatalf("event telemetry leaked %s: %q", key, globalFields.Get("msg")) + } + } +} + +func assertTelemetryKeys(t *testing.T, fields url.Values, want []string) { + t.Helper() + got := make([]string, 0, len(fields)) + for key := range fields { + got = append(got, key) + } + sort.Strings(got) + if !slices.Equal(got, want) { + t.Fatalf("telemetry keys = %v, want %v", got, want) } } diff --git a/go.mod b/go.mod index c26fe31f..eb74fd55 100644 --- a/go.mod +++ b/go.mod @@ -2,6 +2,8 @@ module github.com/DingTalk-Real-AI/dingtalk-workspace-cli go 1.25.9 +replace gitlab.alibaba-inc.com/aes/aem-go-sdk => ./third_party/aem-go-sdk + require ( github.com/Microsoft/go-winio v0.6.2 github.com/RealAlexandreAI/json-repair v0.0.15 @@ -17,6 +19,7 @@ require ( github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1 github.com/spf13/cobra v1.10.2 github.com/zalando/go-keyring v0.2.8 + gitlab.alibaba-inc.com/aes/aem-go-sdk v0.3.0 golang.org/x/crypto v0.49.0 golang.org/x/sys v0.42.0 golang.org/x/text v0.35.0 diff --git a/internal/app/framework_coverage_test.go b/internal/app/framework_coverage_test.go index 26064c39..d0efe79a 100644 --- a/internal/app/framework_coverage_test.go +++ b/internal/app/framework_coverage_test.go @@ -268,7 +268,7 @@ type frameworkFailWriter struct{} func (frameworkFailWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") } -func TestFrameworkExecutePanicBeforeEmissionUsesUnifiedFailure(t *testing.T) { +func TestCrossPlatformCoverageFrameworkExecutePanicBeforeEmissionUsesUnifiedFailure(t *testing.T) { for _, failWriter := range []bool{false, true} { t.Run(map[bool]string{false: "emits", true: "fallback"}[failWriter], func(t *testing.T) { testseam.Protect(t, &os.Args) @@ -470,6 +470,118 @@ func TestCrossPlatformCoverageFrameworkExecuteRareOutcomeBranches(t *testing.T) }) } +func TestCrossPlatformCoverageExecuteDeterministicInterruptionBranches(t *testing.T) { + install := func(t *testing.T, state *processSignalState, stdout, stderr io.Writer) { + t.Helper() + testseam.Protect(t, &os.Args) + os.Args = []string{"dws"} + testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} }) + testseam.Swap(t, &rootStopAllStdioClients, func() {}) + testseam.Swap(t, &rootInstallProcessSignalContext, func(ctx context.Context, _ *output.ResultStore) (context.Context, *processSignalState, func()) { + return ctx, state, func() {} + }) + testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, _ *pipeline.Engine) *cobra.Command { + cmd := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + output.SetCommandRollout(cmd, output.RolloutUnifiedActive) + cmd.SetContext(ctx) + cmd.SetOut(stdout) + cmd.SetErr(stderr) + return cmd + }) + } + interrupted := func(primaryCompleted bool) *processSignalState { + return &processSignalState{ + interruption: &processInterruption{signal: os.Interrupt}, + primaryCompletedAtSignal: primaryCompleted, + } + } + + t.Run("preparse interruption emits unified failure", func(t *testing.T) { + var stdout bytes.Buffer + install(t, interrupted(false), &stdout, io.Discard) + testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return errors.New("preparse failed") }) + testseam.Swap(t, &rootExecuteCommand, func(*cobra.Command) (*cobra.Command, error) { + t.Fatal("preparse failure reached command execution") + return nil, nil + }) + if code, _, summary := ExecuteWithTelemetry(); code != 130 || summary == "" || !strings.Contains(stdout.String(), `"outcome": "failure"`) { + t.Fatalf("preparse interruption = code %d summary %q stdout %q", code, summary, stdout.String()) + } + }) + + t.Run("interruption before emission becomes primary error", func(t *testing.T) { + var stdout bytes.Buffer + install(t, interrupted(false), &stdout, io.Discard) + testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil }) + testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { return cmd, nil }) + if code, _, summary := ExecuteWithTelemetry(); code != 130 || summary == "" || !strings.Contains(stdout.String(), `"outcome": "failure"`) { + t.Fatalf("pre-emission interruption = code %d summary %q stdout %q", code, summary, stdout.String()) + } + }) + + t.Run("late hook error preserves emitted result", func(t *testing.T) { + install(t, interrupted(true), io.Discard, io.Discard) + testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil }) + testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { + if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil { + t.Fatal(err) + } + if _, _, err := output.EmitStoredResult(cmd); err != nil { + t.Fatal(err) + } + return cmd, errors.New("late hook failed") + }) + if code, _, summary := ExecuteWithTelemetry(); code != 0 || summary != "late hook failed" { + t.Fatalf("late hook result = code %d summary %q", code, summary) + } + }) + + t.Run("interruption after emission preserves emitted result", func(t *testing.T) { + install(t, interrupted(false), io.Discard, io.Discard) + testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil }) + testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { + if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil { + t.Fatal(err) + } + if _, _, err := output.EmitStoredResult(cmd); err != nil { + t.Fatal(err) + } + return cmd, nil + }) + if code, _, summary := ExecuteWithTelemetry(); code != 0 || summary == "" { + t.Fatalf("post-emission interruption = code %d summary %q", code, summary) + } + }) + + t.Run("publication failure replaces unobservable result", func(t *testing.T) { + var original bytes.Buffer + install(t, interrupted(false), io.Discard, io.Discard) + testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil }) + testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { + if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil { + t.Fatal(err) + } + if _, _, err := output.EmitStoredResult(cmd); err != nil { + t.Fatal(err) + } + file, err := os.CreateTemp(t.TempDir(), "finished-output-*") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = file.Close() }) + cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, &outputSinkState{file: file, original: &original, finished: true})) + publicationErr := newOutputPublicationError("publish", errors.New("rename failed")) + if _, handled, emitErr := emitOutputPublicationFailure(cmd, publicationErr); !handled || emitErr != nil { + t.Fatalf("precondition publication failure = handled %v error %v unified %v state %v", handled, emitErr, output.UsesUnifiedResult(cmd), outputSinkForCommand(cmd) != nil) + } + return cmd, publicationErr + }) + if code, _, summary := ExecuteWithTelemetry(); code != 5 || summary == "" { + t.Fatalf("publication failure = code %d summary %q output %q", code, summary, original.String()) + } + }) +} + type frameworkPanicWriter struct{} func (frameworkPanicWriter) Write([]byte) (int, error) { panic("writer panic") } diff --git a/internal/app/profile_args_test.go b/internal/app/profile_args_test.go index 031992df..da9bc645 100644 --- a/internal/app/profile_args_test.go +++ b/internal/app/profile_args_test.go @@ -66,6 +66,32 @@ func TestPreparseProfileFlagUsesNormalizedProfileArgs(t *testing.T) { } } +func TestCrossPlatformCoveragePreparseProfileFlagUsesLastOccurrence(t *testing.T) { + for _, tc := range []struct { + name string + args []string + want string + valid bool + }{ + {name: "space then equals", args: []string{"--profile", "corp-a", "version", "--profile=corp-b"}, want: "corp-b", valid: true}, + {name: "equals then space", args: []string{"--profile=corp-a", "version", "--profile", "corp-b"}, want: "corp-b", valid: true}, + {name: "last multi", args: []string{"--profile=corp-a", "--profile", "corp-b,", "corp-c", "version"}, want: "corp-b,corp-c", valid: true}, + {name: "empty equals clears earlier", args: []string{"--profile=corp-a", "version", "--profile="}}, + {name: "missing value clears earlier", args: []string{"--profile=corp-a", "version", "--profile"}}, + {name: "next flag is not profile value", args: []string{"--profile=corp-a", "--profile", "--debug", "version"}}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := preparseProfileFlag(tc.args); got != tc.want { + t.Fatalf("preparseProfileFlag(%#v) = %q, want %q", tc.args, got, tc.want) + } + _, specified, valid := preparseProfileSelection(tc.args) + if !specified || valid != tc.valid { + t.Fatalf("preparseProfileSelection(%#v) = specified %v valid %v, want true/%v", tc.args, specified, valid, tc.valid) + } + }) + } +} + func TestNormalizeProcessProfileArgsRestoresOriginalArgv(t *testing.T) { oldArgs := os.Args t.Cleanup(func() { os.Args = oldArgs }) diff --git a/internal/app/root.go b/internal/app/root.go index 7a41bd53..c35a2979 100644 --- a/internal/app/root.go +++ b/internal/app/root.go @@ -80,10 +80,19 @@ var ( rootAuthLoadTokenData = authpkg.LoadTokenData rootNewCommandRunnerWithFlags = newCommandRunnerWithFlags rootEmitResult = output.EmitResult + rootInstallProcessSignalContext = installProcessSignalContext ) // Execute runs the root command and returns the process exit code. -func Execute() (exitCode int) { +func Execute() int { + exitCode, _, _ := ExecuteWithTelemetry() + return exitCode +} + +// ExecuteWithTelemetry runs the root command and additionally returns a +// privacy-safe command path and error summary for the official CLI entrypoint. +func ExecuteWithTelemetry() (exitCode int, commandPath string, errorMessage string) { + commandPath = "dws" var ( root *cobra.Command executed *cobra.Command @@ -91,12 +100,16 @@ func Execute() (exitCode int) { ) defer func() { if r := recover(); r != nil { + errorMessage = "internal panic" target := executed if target == nil && root != nil { if found, _, err := root.Find(os.Args[1:]); err == nil { target = found } } + if target != nil { + commandPath = telemetryCommandPath(target) + } if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted { exitCode = code if target != nil { @@ -121,6 +134,7 @@ func Execute() (exitCode int) { CloseFileLogger() if executed != nil { if err := closeOutputSink(executed); err != nil { + errorMessage = telemetryErrorSummary(err) if code, handled, emitErr := emitOutputPublicationFailure(executed, err); handled && emitErr == nil { exitCode = code } else { @@ -144,7 +158,9 @@ func Execute() (exitCode int) { agentMetadata := readAgentMetadataSnapshot() if err := agentMetadata.validationError(); err != nil { emitEarlyAgentMetadataValidationError(err, os.Args[1:]) - return apperrors.ExitCode(err) + errorMessage = telemetryErrorSummary(err) + exitCode = apperrors.ExitCode(err) + return } timing := NewTimingCollector() @@ -162,12 +178,13 @@ func Execute() (exitCode int) { ctx, resultStore = output.WithResultStore(ctx) var signalState *processSignalState var stopSignals func() - ctx, signalState, stopSignals = installProcessSignalContext(ctx, resultStore) + ctx, signalState, stopSignals = rootInstallProcessSignalContext(ctx, resultStore) defer stopSignals() initStart := time.Now() engine := newPipelineEngine() root = rootNewRootCommandWithEngine(ctx, engine) + commandPath = telemetryCommandPath(root) timing.Record("cmd_init", time.Since(initStart)) // Run PreParse handlers on raw argv before Cobra parses flags. @@ -182,15 +199,23 @@ func Execute() (exitCode int) { result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err)) code, emitErr := output.EmitResult(target, result) if emitErr == nil { - return code + errorMessage = telemetryErrorSummary(err) + exitCode = code + return } } _ = printExecutionError(root, os.Stdout, os.Stderr, err) - return apperrors.ExitCode(err) + errorMessage = telemetryErrorSummary(err) + exitCode = apperrors.ExitCode(err) + return } + commandPath = telemetryCommandPathForArgs(root, os.Args[1:]) var err error executed, err = rootExecuteCommand(root) + if executed != nil { + commandPath = telemetryCommandPath(executed) + } // PersistentPostRunE normally commits or aborts the transactional output // sink. Finalize once more at the process boundary so custom execution // seams, embedding callers, or future hook changes cannot leave publication @@ -222,7 +247,9 @@ func Execute() (exitCode int) { // successfully emitted result into a contradictory 130/143 process // status; likewise, a failed publication must retain its internal // error code instead of being relabelled as cancellation. - return code + errorMessage = telemetryErrorSummary(interrupted) + exitCode = code + return } } var publicationErr *outputPublicationError @@ -233,20 +260,26 @@ func Execute() (exitCode int) { if err != nil { if executed == nil { executed = root + commandPath = telemetryCommandPath(root) } if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted { var publicationErr *outputPublicationError if stderrors.As(err, &publicationErr) { + errorMessage = telemetryErrorSummary(publicationErr) if failureCode, handled, emitErr := emitOutputPublicationFailure(executed, publicationErr); handled { if emitErr == nil { - return failureCode + exitCode = failureCode + return } fmt.Fprintf(executed.ErrOrStderr(), "Warning: emit output publication failure: %v\n", emitErr) } - return apperrors.ExitCode(publicationErr) + exitCode = apperrors.ExitCode(publicationErr) + return } fmt.Fprintf(executed.ErrOrStderr(), "Warning: command hook failed after result emission: %v\n", err) - return code + errorMessage = telemetryErrorSummary(err) + exitCode = code + return } err = rewordRequiredFlagError(err) var raw apperrors.RawStderrError @@ -254,7 +287,9 @@ func Execute() (exitCode int) { result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err)) code, emitErr := output.EmitResult(executed, result) if emitErr == nil { - return code + errorMessage = telemetryErrorSummary(err) + exitCode = code + return } err = apperrors.NewInternal("emit failure result: "+emitErr.Error(), apperrors.WithCause(emitErr)) } @@ -264,12 +299,42 @@ func Execute() (exitCode int) { _, _ = fmt.Fprintln(os.Stderr) } _ = printExecutionError(executed, os.Stdout, os.Stderr, err) - return apperrors.ExitCode(err) + errorMessage = telemetryErrorSummary(err) + exitCode = apperrors.ExitCode(err) + return } if code, emitted := output.StoredExitCode(resultStore); emitted { - return code + exitCode = code + return } - return 0 + return +} + +func telemetryCommandPath(command *cobra.Command) string { + if command == nil { + return "dws" + } + path := strings.TrimSpace(command.CommandPath()) + root := command.Root() + rootName := strings.TrimSpace(root.Name()) + if path == rootName { + return rootName + } + if rootName != "" { + path = strings.TrimSpace(strings.TrimPrefix(path, rootName+" ")) + } + return path +} + +func telemetryCommandPathForArgs(root *cobra.Command, args []string) string { + if root == nil { + return "dws" + } + command, _, err := root.Find(args) + if err != nil || command == nil { + return telemetryCommandPath(root) + } + return telemetryCommandPath(command) } // emitEarlyAgentMetadataValidationError preserves each built-in command's @@ -959,17 +1024,36 @@ func installReviewedFlagProtectionHandlers(root *cobra.Command) { } func preparseProfileFlag(args []string) string { + profile, _, valid := preparseProfileSelection(args) + if !valid { + return "" + } + return profile +} + +func preparseProfileSelection(args []string) (profile string, specified, valid bool) { args, _ = normalizeProfileFlagArgs(args) + valid = true for i := 0; i < len(args); i++ { arg := strings.TrimSpace(args[i]) switch { - case arg == "--profile" && i+1 < len(args): - return strings.TrimSpace(args[i+1]) + case arg == "--profile": + specified = true + if i+1 >= len(args) || strings.HasPrefix(strings.TrimSpace(args[i+1]), "-") { + profile = "" + valid = false + continue + } + profile = strings.TrimSpace(args[i+1]) + valid = profile != "" + i++ case strings.HasPrefix(arg, "--profile="): - return strings.TrimSpace(strings.TrimPrefix(arg, "--profile=")) + specified = true + profile = strings.TrimSpace(strings.TrimPrefix(arg, "--profile=")) + valid = profile != "" } } - return "" + return profile, specified, valid } func normalizeProcessProfileArgs() func() { diff --git a/internal/app/root_full_coverage_test.go b/internal/app/root_full_coverage_test.go index a0a0af46..f4c5477a 100644 --- a/internal/app/root_full_coverage_test.go +++ b/internal/app/root_full_coverage_test.go @@ -37,29 +37,64 @@ func TestCrossPlatformCoverageRootExecuteAllBranchesCoverage(t *testing.T) { rootNormalizeProcessProfileArgs = func() func() { return func() {} } rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil } rootStopAllStdioClients = func() {} + var executedLeaf *cobra.Command rootNewRootCommandWithEngine = func(context.Context, *pipeline.Engine) *cobra.Command { - return &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + sheet := &cobra.Command{Use: "sheet"} + executedLeaf = &cobra.Command{Use: "read", Run: func(*cobra.Command, []string) {}} + sheet.AddCommand(executedLeaf) + root.AddCommand(sheet) + return root } - rootExecuteCommand = func(cmd *cobra.Command) (*cobra.Command, error) { return cmd, nil } - if code := Execute(); code != 0 { - t.Fatalf("successful Execute code = %d", code) + rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return executedLeaf, nil } + if code, commandPath, errorMessage := ExecuteWithTelemetry(); code != 0 || commandPath != "sheet read" || errorMessage != "" { + t.Fatalf("successful ExecuteWithTelemetry = code %d path %q error %q", code, commandPath, errorMessage) } rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return errors.New("alias/canonical conflict") } - if code := Execute(); code == 0 { - t.Fatal("pre-parse conflict returned zero") + if code, _, errorMessage := ExecuteWithTelemetry(); code == 0 || errorMessage != "alias/canonical conflict" { + t.Fatalf("pre-parse conflict = code %d error %q", code, errorMessage) } rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil } wantErr := errors.New("unknown command missing") rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return nil, wantErr } - if code := Execute(); code == 0 { - t.Fatal("failed Execute returned zero") + if code, _, errorMessage := ExecuteWithTelemetry(); code == 0 || errorMessage != "unknown command" { + t.Fatalf("failed ExecuteWithTelemetry = code %d error %q", code, errorMessage) } rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { panic("boom") } - if code := Execute(); code != 5 { - t.Fatalf("panic Execute code = %d", code) + os.Args = []string{"dws", "sheet", "read"} + if code, commandPath, errorMessage := ExecuteWithTelemetry(); code != 5 || commandPath != "sheet read" || errorMessage != "internal panic" { + t.Fatalf("panic ExecuteWithTelemetry = code %d path %q error %q", code, commandPath, errorMessage) + } +} + +func TestCrossPlatformCoverageTelemetryCommandPath(t *testing.T) { + if got := telemetryCommandPath(nil); got != "dws" { + t.Fatalf("nil command path = %q, want dws", got) + } + if got := telemetryCommandPathForArgs(nil, nil); got != "dws" { + t.Fatalf("nil root command path = %q, want dws", got) + } + root := &cobra.Command{Use: "dws"} + sheet := &cobra.Command{Use: "sheet"} + read := &cobra.Command{Use: "read "} + sheet.AddCommand(read) + root.AddCommand(sheet) + if got := telemetryCommandPath(root); got != "dws" { + t.Fatalf("root command path = %q, want dws", got) + } + if got := telemetryCommandPath(read); got != "sheet read" { + t.Fatalf("leaf command path = %q, want sheet read", got) + } + root.PersistentFlags().String("profile", "", "") + read.Aliases = []string{"get"} + if got := telemetryCommandPathForArgs(root, []string{"--profile", "corp-a", "sheet", "get", "A1:B2"}); got != "sheet read" { + t.Fatalf("pre-execution command path = %q, want sheet read", got) + } + if got := telemetryCommandPathForArgs(root, []string{"missing"}); got != "dws" { + t.Fatalf("unknown pre-execution command path = %q, want dws", got) } } diff --git a/internal/app/root_lifecycle_regression_test.go b/internal/app/root_lifecycle_regression_test.go index 4f705ac2..51261f0f 100644 --- a/internal/app/root_lifecycle_regression_test.go +++ b/internal/app/root_lifecycle_regression_test.go @@ -181,7 +181,7 @@ func TestPublicRootDirectExecuteClosesSinkOnHandlerError(t *testing.T) { } } -func TestExecutePanicAfterEmissionPreservesSingleResultAndExitCode(t *testing.T) { +func TestCrossPlatformCoverageExecutePanicAfterEmissionPreservesSingleResultAndExitCode(t *testing.T) { oldNormalize := rootNormalizeProcessProfileArgs oldExecute := rootExecuteCommand oldNewRoot := rootNewRootCommandWithEngine diff --git a/internal/app/root_output_atomic_test.go b/internal/app/root_output_atomic_test.go index 83025397..d666a35d 100644 --- a/internal/app/root_output_atomic_test.go +++ b/internal/app/root_output_atomic_test.go @@ -230,13 +230,20 @@ func TestOutputSinkUnifiedPublicationFailureFailsAndLeavesNoFinalFile(t *testing assertNoOutputTemps(t, target) } -func TestExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing.T) { +func TestCrossPlatformCoverageExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing.T) { testseam.Protect(t, &os.Args) dir := t.TempDir() - target := filepath.Join(dir, "result.json") + t.Chdir(dir) + // Keep argv portable: an absolute Windows path contains a volume colon, + // which the CLI intentionally rejects as unsafe user-supplied output. + target := "result.json" if err := os.WriteFile(target, []byte("original"), 0o640); err != nil { t.Fatal(err) } + originalInfo, err := os.Stat(target) + if err != nil { + t.Fatal(err) + } os.Args = []string{"dws", "atomic-output-unified-publication", "--output", target, "--format", "json"} testseam.Swap(t, &rootRenameFile, func(string, string) error { return errors.New("rename failed") }) testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} }) @@ -277,7 +284,7 @@ func TestExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "success"`)); got != 0 { t.Fatalf("rolled-back success leaked to stdout: %s", stdout.String()) } - assertOutputFile(t, target, "original", 0o640) + assertOutputFile(t, target, "original", originalInfo.Mode().Perm()) assertNoOutputTemps(t, target) } diff --git a/internal/app/root_unified_output_test.go b/internal/app/root_unified_output_test.go index d64d4016..67d02061 100644 --- a/internal/app/root_unified_output_test.go +++ b/internal/app/root_unified_output_test.go @@ -27,7 +27,7 @@ import ( "github.com/spf13/cobra" ) -func TestExecuteEmitsStoredUnifiedResultAtSingleRootExit(t *testing.T) { +func TestCrossPlatformCoverageExecuteEmitsStoredUnifiedResultAtSingleRootExit(t *testing.T) { oldNormalize := rootNormalizeProcessProfileArgs oldExecute := rootExecuteCommand oldNewRoot := rootNewRootCommandWithEngine diff --git a/internal/app/signal_test.go b/internal/app/signal_test.go index 3706cbd3..33a544b9 100644 --- a/internal/app/signal_test.go +++ b/internal/app/signal_test.go @@ -103,7 +103,7 @@ func installSignalExecuteSeams(t *testing.T, unified bool, stdout, stderr io.Wri }) } -func TestExecuteSignalEmitsOneTypedUnifiedFailure(t *testing.T) { +func TestCrossPlatformCoverageExecuteSignalEmitsOneTypedUnifiedFailure(t *testing.T) { for _, tc := range []struct { name string signal syscall.Signal @@ -197,7 +197,7 @@ func TestSignalAfterFailedEmissionAttemptPreservesPublicationExitCode(t *testing } } -func TestSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) { +func TestCrossPlatformCoverageSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) { var stdout bytes.Buffer installSignalExecuteSeams(t, true, &stdout, io.Discard) testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { @@ -229,7 +229,7 @@ func TestSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) { } } -func TestSignalAfterCompletedPrimaryPreservesEstablishedOutcome(t *testing.T) { +func TestCrossPlatformCoverageSignalAfterCompletedPrimaryPreservesEstablishedOutcome(t *testing.T) { var stdout bytes.Buffer installSignalExecuteSeams(t, true, &stdout, io.Discard) testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) { diff --git a/internal/app/telemetry_error.go b/internal/app/telemetry_error.go new file mode 100644 index 00000000..6a16e289 --- /dev/null +++ b/internal/app/telemetry_error.go @@ -0,0 +1,143 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package app + +import ( + stderrors "errors" + "fmt" + "regexp" + "strings" + "unicode" + + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" +) + +const maxTelemetryErrorRunes = 200 + +var ( + telemetryUnknownFlagPattern = regexp.MustCompile(`(?i)unknown flag:\s*(--[a-z0-9][a-z0-9-]*)`) + telemetryAuthPattern = regexp.MustCompile(`(?i)\b(?:bearer|basic)\s+[a-z0-9._~+/=-]+`) + telemetrySensitiveFlag = regexp.MustCompile(`(?i)(--(?:access-token|refresh-token|token|client-secret|client-id|password|api-key|authorization|cookie|credential|secret))(?:=|\s+)\S+`) + telemetrySensitiveValue = regexp.MustCompile(`(?i)\b(authorization|client[-_]?secret|client[-_]?id|access[-_]?token|refresh[-_]?token|api[-_]?key|password|cookie|credential|secret|token)\b\s*[:=]\s*[^\s,;]+`) + telemetryURLPattern = regexp.MustCompile(`(?i)\b(?:https?|wss?)://[^\s]+`) + telemetryJSONPattern = regexp.MustCompile(`(?s)[\[{].*[\]}]`) + telemetryUnixPathPattern = regexp.MustCompile(`(^|[\s=:])(?:~/|/)[^\s]+`) + telemetryWindowsPathPattern = regexp.MustCompile(`(?i)(^|[\s=])[a-z]:[\\/][^\s]+`) + telemetryRelativePathPattern = regexp.MustCompile(`(^|[\s=:])\.\.?/[^\s]+`) + telemetryEmailPattern = regexp.MustCompile(`(?i)\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b`) + telemetryPhonePattern = regexp.MustCompile(`\b\+?\d[\d -]{7,}\d\b`) + telemetryOpaqueTokenPattern = regexp.MustCompile(`\b[a-zA-Z0-9_-]{16,}\b`) +) + +func telemetryErrorSummary(err error) string { + if err == nil { + return "" + } + var patError *apperrors.PATError + if stderrors.As(err, &patError) { + return "permission error" + } + var rawError apperrors.RawStderrError + if stderrors.As(err, &rawError) { + return "raw stderr error" + } + if isUnknownCommandError(err) { + return "unknown command" + } + if match := telemetryUnknownFlagPattern.FindStringSubmatch(err.Error()); len(match) == 2 { + return "unknown flag: " + match[1] + } + return sanitizeTelemetryErrorText(err.Error()) +} + +func telemetryPanicMessages(value any) (display, summary string) { + return fmt.Sprintf("internal panic: %v", value), "internal panic" +} + +func sanitizeTelemetryErrorText(message string) string { + message = output.SanitizeForTerminal(message) + message = telemetryAuthPattern.ReplaceAllString(message, "") + message = telemetrySensitiveFlag.ReplaceAllString(message, "$1=") + message = telemetrySensitiveValue.ReplaceAllString(message, "$1=") + message = telemetryURLPattern.ReplaceAllString(message, "") + message = telemetryJSONPattern.ReplaceAllString(message, "") + message = redactTelemetryQuotedText(message) + message = telemetryUnixPathPattern.ReplaceAllString(message, "$1") + message = telemetryWindowsPathPattern.ReplaceAllString(message, "$1") + message = telemetryRelativePathPattern.ReplaceAllString(message, "$1") + message = telemetryEmailPattern.ReplaceAllString(message, "") + message = telemetryPhonePattern.ReplaceAllString(message, "") + message = telemetryOpaqueTokenPattern.ReplaceAllStringFunc(message, func(value string) string { + var hasLetter, hasDigit bool + for _, r := range value { + hasLetter = hasLetter || unicode.IsLetter(r) + hasDigit = hasDigit || unicode.IsDigit(r) + } + if hasLetter && hasDigit { + return "" + } + return value + }) + message = strings.Join(strings.Fields(message), " ") + return truncateTelemetryText(message, maxTelemetryErrorRunes) +} + +func redactTelemetryQuotedText(message string) string { + var result strings.Builder + runes := []rune(message) + for index := 0; index < len(runes); { + quote := runes[index] + if quote != '\'' && quote != '"' && quote != '`' { + result.WriteRune(quote) + index++ + continue + } + result.WriteRune(quote) + result.WriteString("") + index++ + escaped := false + for index < len(runes) { + current := runes[index] + index++ + if escaped { + escaped = false + continue + } + if current == '\\' && quote != '`' { + escaped = true + continue + } + if current == quote { + result.WriteRune(quote) + break + } + } + } + return result.String() +} + +func truncateTelemetryText(message string, maxRunes int) string { + if maxRunes <= 0 { + return "" + } + runes := []rune(message) + if len(runes) <= maxRunes { + return message + } + if maxRunes <= 3 { + return string(runes[:maxRunes]) + } + return string(runes[:maxRunes-3]) + "..." +} diff --git a/internal/app/telemetry_error_test.go b/internal/app/telemetry_error_test.go new file mode 100644 index 00000000..08b411c6 --- /dev/null +++ b/internal/app/telemetry_error_test.go @@ -0,0 +1,99 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package app + +import ( + "errors" + "strings" + "testing" + + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" +) + +type telemetryRawError string + +func (e telemetryRawError) Error() string { return string(e) } +func (e telemetryRawError) RawStderr() string { return string(e) } + +func TestCrossPlatformCoverageTelemetryErrorSummaryFixedFamilies(t *testing.T) { + for _, tc := range []struct { + name string + err error + want string + }{ + {name: "nil", want: ""}, + {name: "PAT", err: &apperrors.PATError{RawJSON: `{"token":"secret"}`}, want: "permission error"}, + {name: "raw stderr", err: telemetryRawError("raw secret"), want: "raw stderr error"}, + {name: "unknown command", err: errors.New(`unknown command "secret-value" for "dws"`), want: "unknown command"}, + {name: "unknown flag", err: errors.New("unknown flag: --token=secret-value"), want: "unknown flag: --token"}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := telemetryErrorSummary(tc.err); got != tc.want { + t.Fatalf("telemetryErrorSummary() = %q, want %q", got, tc.want) + } + }) + } +} + +func TestCrossPlatformCoverageSanitizeTelemetryErrorText(t *testing.T) { + message := "\x1b[31mfailed\x1b[0m " + + "--client-secret very-secret " + + "--access-token access-secret " + + "Authorization: Bearer abcdefghijklmnop1234 " + + "url=https://example.test/path?token=secret " + + `body={"access_token":"secret"} ` + + `user="Alice" email=alice@example.test phone=13800138000 ` + + "path=/Users/alice/private.txt relative=./private/secrets.txt id=abcDEF1234567890XYZ" + got := sanitizeTelemetryErrorText(message) + for _, secret := range []string{ + "very-secret", "access-secret", "abcdefghijklmnop1234", "example.test", "access_token", + "Alice", "alice@example.test", "13800138000", "/Users/alice", "abcDEF1234567890XYZ", "\x1b", + "./private/secrets.txt", + } { + if strings.Contains(got, secret) { + t.Fatalf("sanitized telemetry error leaked %q: %q", secret, got) + } + } + for _, marker := range []string{"failed", "", "", "", "", ""} { + if !strings.Contains(got, marker) { + t.Fatalf("sanitized telemetry error missing %q: %q", marker, got) + } + } +} + +func TestCrossPlatformCoverageTelemetryErrorTruncationAndPanic(t *testing.T) { + message := strings.Repeat("错", maxTelemetryErrorRunes+1) + got := sanitizeTelemetryErrorText(message) + if len([]rune(got)) != maxTelemetryErrorRunes || !strings.HasSuffix(got, "...") { + t.Fatalf("truncated telemetry error rune length = %d suffix = %q", len([]rune(got)), got[len(got)-3:]) + } + display, summary := telemetryPanicMessages("token-secret") + if display != "internal panic: token-secret" || summary != "internal panic" || strings.Contains(summary, "token-secret") { + t.Fatalf("panic messages = display %q summary %q", display, summary) + } + if got := truncateTelemetryText("value", 0); got != "" { + t.Fatalf("zero-limit truncation = %q", got) + } + if got := truncateTelemetryText("value", 3); got != "val" { + t.Fatalf("short-limit truncation = %q", got) + } +} + +func TestCrossPlatformCoverageTelemetryErrorEscapesAndOpaqueWords(t *testing.T) { + const opaqueWord = "abcdefghijklmnop" + got := sanitizeTelemetryErrorText(`failed "quoted \"value" ` + opaqueWord) + if strings.Contains(got, "value") || !strings.Contains(got, opaqueWord) { + t.Fatalf("escaped quote sanitization = %q", got) + } +} diff --git a/internal/app/telemetry_identity.go b/internal/app/telemetry_identity.go new file mode 100644 index 00000000..4ea93a96 --- /dev/null +++ b/internal/app/telemetry_identity.go @@ -0,0 +1,86 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package app + +import ( + "fmt" + "strings" + + authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth" +) + +// TelemetryIdentity is the privacy-reviewed subset of the local authentication +// record that may be attached to a CLI execution event. +type TelemetryIdentity struct { + UserID string + UserName string + CorpID string +} + +var telemetryResolveProfileMetadata = authpkg.ResolveProfileMetadataReadOnly + +// ResolveTelemetryIdentity returns a pre-execution snapshot of the identity +// selected by args. Multi-profile executions are attributed to the current +// default profile. Resolution is deliberately best-effort: telemetry must not +// refresh credentials or change command behavior when local auth data is +// missing, invalid, or unreadable. +func ResolveTelemetryIdentity(args []string) (identity TelemetryIdentity) { + defer func() { + if recover() != nil { + identity = TelemetryIdentity{} + } + }() + + selector, specified, valid := preparseProfileSelection(args) + if specified && !valid { + return TelemetryIdentity{} + } + profile, err := resolveTelemetryProfileMetadata(defaultConfigDir(), selector) + if err != nil || profile == nil { + return TelemetryIdentity{} + } + return TelemetryIdentity{ + UserID: strings.TrimSpace(profile.UserID), + UserName: strings.TrimSpace(profile.UserName), + CorpID: strings.TrimSpace(profile.CorpID), + } +} + +func resolveTelemetryProfileMetadata(configDir, selector string) (*authpkg.ProfileMetadata, error) { + selector = strings.TrimSpace(selector) + if selector == "" || !strings.Contains(selector, ",") { + return telemetryResolveProfileMetadata(configDir, selector) + } + + // A local profile name may itself contain a comma. Match the runtime + // resolver by trying the full selector before interpreting it as CSV. + if profile, err := telemetryResolveProfileMetadata(configDir, selector); err == nil && profile != nil { + return profile, nil + } + + for _, part := range strings.Split(selector, ",") { + part = strings.TrimSpace(part) + if part == "" { + return nil, fmt.Errorf("--profile contains an empty profile selector: %q", selector) + } + profile, err := telemetryResolveProfileMetadata(configDir, part) + if err != nil { + return nil, err + } + if profile == nil { + return nil, fmt.Errorf("profile %q not found", part) + } + } + return telemetryResolveProfileMetadata(configDir, "") +} diff --git a/internal/app/telemetry_identity_test.go b/internal/app/telemetry_identity_test.go new file mode 100644 index 00000000..076fb10a --- /dev/null +++ b/internal/app/telemetry_identity_test.go @@ -0,0 +1,147 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package app + +import ( + "errors" + "reflect" + "strings" + "testing" + + authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageResolveTelemetryIdentityProfileSelection(t *testing.T) { + t.Setenv("DWS_CONFIG_DIR", "/telemetry-config") + profiles := map[string]*authpkg.ProfileMetadata{ + "": {UserID: " default-user ", UserName: " Default User ", CorpID: " default-corp "}, + "corp-a": {UserID: "user-a", UserName: "Alice", CorpID: "corp-a"}, + "corp-b": {UserID: "user-b", UserName: "Bob", CorpID: "corp-b"}, + "alpha,beta": {UserID: "comma-user", UserName: "Comma User", CorpID: "comma-corp"}, + } + + for _, tc := range []struct { + name string + args []string + profiles map[string]*authpkg.ProfileMetadata + wantCalls []string + want TelemetryIdentity + }{ + {name: "default profile", args: []string{"version"}, profiles: profiles, wantCalls: []string{""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}}, + {name: "single profile", args: []string{"--profile", "corp-a", "version"}, profiles: profiles, wantCalls: []string{"corp-a"}, want: TelemetryIdentity{UserID: "user-a", UserName: "Alice", CorpID: "corp-a"}}, + {name: "equals form after command", args: []string{"version", "--profile=corp-b"}, profiles: profiles, wantCalls: []string{"corp-b"}, want: TelemetryIdentity{UserID: "user-b", UserName: "Bob", CorpID: "corp-b"}}, + {name: "last repeated profile", args: []string{"--profile", "corp-a", "version", "--profile=corp-b"}, profiles: profiles, wantCalls: []string{"corp-b"}, want: TelemetryIdentity{UserID: "user-b", UserName: "Bob", CorpID: "corp-b"}}, + {name: "comma profile name", args: []string{"--profile", "alpha,beta", "version"}, profiles: profiles, wantCalls: []string{"alpha,beta"}, want: TelemetryIdentity{UserID: "comma-user", UserName: "Comma User", CorpID: "comma-corp"}}, + {name: "multi profile uses default", args: []string{"--profile", "corp-a,corp-b", "version"}, profiles: profiles, wantCalls: []string{"corp-a,corp-b", "corp-a", "corp-b", ""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}}, + {name: "unquoted multi profile", args: []string{"--profile", "corp-a,", "corp-b", "version"}, profiles: profiles, wantCalls: []string{"corp-a,corp-b", "corp-a", "corp-b", ""}, want: TelemetryIdentity{UserID: "default-user", UserName: "Default User", CorpID: "default-corp"}}, + } { + t.Run(tc.name, func(t *testing.T) { + var calls []string + testseam.Swap(t, &telemetryResolveProfileMetadata, func(configDir, selector string) (*authpkg.ProfileMetadata, error) { + if configDir != "/telemetry-config" { + t.Fatalf("resolver config dir = %q", configDir) + } + calls = append(calls, selector) + profile := tc.profiles[selector] + if profile == nil { + return nil, errors.New("profile not found") + } + clone := *profile + return &clone, nil + }) + + if got := ResolveTelemetryIdentity(tc.args); got != tc.want { + t.Fatalf("ResolveTelemetryIdentity() = %#v, want %#v", got, tc.want) + } + if !reflect.DeepEqual(calls, tc.wantCalls) { + t.Fatalf("metadata selectors = %#v, want %#v", calls, tc.wantCalls) + } + }) + } +} + +func TestCrossPlatformCoverageResolveTelemetryIdentityRejectsMissingProfileValue(t *testing.T) { + for _, args := range [][]string{ + {"version", "--profile"}, + {"--profile=corp-a", "version", "--profile="}, + {"--profile", "--debug", "version"}, + } { + t.Run(strings.Join(args, "_"), func(t *testing.T) { + testseam.Swap(t, &telemetryResolveProfileMetadata, func(string, string) (*authpkg.ProfileMetadata, error) { + t.Fatal("invalid profile syntax attempted metadata resolution") + return nil, nil + }) + if got := ResolveTelemetryIdentity(args); got != (TelemetryIdentity{}) { + t.Fatalf("invalid profile identity = %#v", got) + } + }) + } +} + +func TestCrossPlatformCoverageResolveTelemetryIdentityFailsClosed(t *testing.T) { + t.Setenv("DWS_CONFIG_DIR", "/telemetry-config") + fail := errors.New("metadata unavailable") + + for _, tc := range []struct { + name string + resolve func(string, string) (*authpkg.ProfileMetadata, error) + }{ + {name: "read error", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return nil, fail }}, + {name: "missing profile", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return nil, nil }}, + {name: "empty fields", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { return &authpkg.ProfileMetadata{}, nil }}, + {name: "resolver panic", resolve: func(string, string) (*authpkg.ProfileMetadata, error) { panic("metadata failure") }}, + } { + t.Run(tc.name, func(t *testing.T) { + testseam.Swap(t, &telemetryResolveProfileMetadata, tc.resolve) + if got := ResolveTelemetryIdentity(nil); got != (TelemetryIdentity{}) { + t.Fatalf("failed-closed identity = %#v", got) + } + }) + } +} + +func TestCrossPlatformCoverageResolveTelemetryIdentityRejectsInvalidMultiProfile(t *testing.T) { + t.Setenv("DWS_CONFIG_DIR", "/telemetry-config") + testseam.Swap(t, &telemetryResolveProfileMetadata, func(_ string, selector string) (*authpkg.ProfileMetadata, error) { + if selector == "corp-a" { + return &authpkg.ProfileMetadata{UserID: "user-a", CorpID: "corp-a"}, nil + } + return nil, errors.New("profile not found") + }) + if got := ResolveTelemetryIdentity([]string{"--profile", "corp-a,missing", "version"}); got != (TelemetryIdentity{}) { + t.Fatalf("invalid multi-profile identity = %#v", got) + } +} + +func TestCrossPlatformCoverageResolveTelemetryProfileMetadataRejectsMalformedMulti(t *testing.T) { + testseam.Swap(t, &telemetryResolveProfileMetadata, func(_ string, selector string) (*authpkg.ProfileMetadata, error) { + switch selector { + case "corp-a,,corp-b": + return nil, errors.New("not a literal profile") + case "corp-a": + return &authpkg.ProfileMetadata{UserID: "user-a"}, nil + case "missing": + return nil, nil + default: + return nil, errors.New("unexpected selector") + } + }) + if _, err := resolveTelemetryProfileMetadata("/config", "corp-a,,corp-b"); err == nil || !strings.Contains(err.Error(), "empty profile selector") { + t.Fatalf("empty multi-profile selector error = %v", err) + } + if _, err := resolveTelemetryProfileMetadata("/config", "corp-a,missing"); err == nil || !strings.Contains(err.Error(), "not found") { + t.Fatalf("missing multi-profile selector error = %v", err) + } +} diff --git a/internal/auth/profile_metadata_readonly.go b/internal/auth/profile_metadata_readonly.go new file mode 100644 index 00000000..d6f857f0 --- /dev/null +++ b/internal/auth/profile_metadata_readonly.go @@ -0,0 +1,70 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package auth + +import ( + "encoding/json" + "fmt" + "os" + "strings" +) + +// ProfileMetadata is the minimal, non-sensitive identity projection exposed to +// telemetry callers. It intentionally excludes profile names, client IDs, +// organization names, token material, and credential status. +type ProfileMetadata struct { + UserID string + UserName string + CorpID string +} + +// ResolveProfileMetadataReadOnly resolves one identity exclusively from the +// non-sensitive profiles.json metadata. It deliberately avoids auth locks, +// token stores, Keychain access, migrations, quarantine renames, and writes. +// A missing metadata file or an empty current profile returns (nil, nil). +func ResolveProfileMetadataReadOnly(configDir, selector string) (*ProfileMetadata, error) { + data, err := profilesReadFile(ProfilesPath(configDir)) + if err != nil { + if os.IsNotExist(err) { + return nil, nil + } + return nil, fmt.Errorf("read profile metadata: %w", err) + } + + var cfg ProfilesConfig + if err := json.Unmarshal(data, &cfg); err != nil { + return nil, fmt.Errorf("parse profile metadata: %w", err) + } + if cfg.Version > profilesMaxVersion { + return nil, fmt.Errorf("profile metadata version %d is newer than supported version %d", cfg.Version, profilesMaxVersion) + } + normalizeProfilesConfig(&cfg) + + selector = strings.TrimSpace(selector) + if selector == "" { + selector = strings.TrimSpace(cfg.CurrentProfile) + if selector == "" { + return nil, nil + } + } + profile, _, err := resolveProfileSelection("", &cfg, selector) + if err != nil { + return nil, err + } + return &ProfileMetadata{ + UserID: profile.UserID, + UserName: profile.UserName, + CorpID: profile.CorpID, + }, nil +} diff --git a/internal/auth/profile_metadata_readonly_test.go b/internal/auth/profile_metadata_readonly_test.go new file mode 100644 index 00000000..ca5aa67c --- /dev/null +++ b/internal/auth/profile_metadata_readonly_test.go @@ -0,0 +1,97 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package auth + +import ( + "errors" + "os" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageResolveProfileMetadataReadOnly(t *testing.T) { + const metadata = `{ + "version": 3, + "currentProfile": "corp-a:user-a", + "profiles": [ + {"name":"alpha","corpId":"corp-a","userId":"user-a","userName":"Alice"}, + {"name":"beta","corpId":"corp-b","userId":"user-b","userName":"Bob"} + ] +}` + reads := 0 + testseam.Swap(t, &profilesReadFile, func(path string) ([]byte, error) { + reads++ + if !strings.HasSuffix(path, profilesJSONFile) { + t.Fatalf("metadata path = %q", path) + } + return []byte(metadata), nil + }) + + current, err := ResolveProfileMetadataReadOnly("/config", "") + if err != nil || current == nil || current.UserID != "user-a" || current.UserName != "Alice" || current.CorpID != "corp-a" { + t.Fatalf("current metadata profile = %#v, %v", current, err) + } + explicit, err := ResolveProfileMetadataReadOnly("/config", "beta") + if err != nil || explicit == nil || explicit.UserID != "user-b" || explicit.CorpID != "corp-b" { + t.Fatalf("explicit metadata profile = %#v, %v", explicit, err) + } + if reads != 2 { + t.Fatalf("profile metadata reads = %d, want 2", reads) + } +} + +func TestCrossPlatformCoverageResolveProfileMetadataReadOnlyFailsClosed(t *testing.T) { + fail := errors.New("read failed") + for _, tc := range []struct { + name string + read func(string) ([]byte, error) + wantErr string + }{ + {name: "missing", read: func(string) ([]byte, error) { return nil, os.ErrNotExist }}, + {name: "read error", read: func(string) ([]byte, error) { return nil, fail }, wantErr: "read profile metadata"}, + {name: "corrupt", read: func(string) ([]byte, error) { return []byte("{"), nil }, wantErr: "parse profile metadata"}, + {name: "forward version", read: func(string) ([]byte, error) { return []byte(`{"version":999}`), nil }, wantErr: "newer than supported"}, + {name: "no current", read: func(string) ([]byte, error) { return []byte(`{"version":3,"profiles":[]}`), nil }}, + } { + t.Run(tc.name, func(t *testing.T) { + testseam.Swap(t, &profilesReadFile, tc.read) + testseam.Swap(t, &profilesRename, func(string, string) error { + t.Fatal("read-only metadata resolution attempted a quarantine rename") + return nil + }) + got, err := ResolveProfileMetadataReadOnly("/config", "") + if tc.wantErr == "" { + if err != nil || got != nil { + t.Fatalf("read-only metadata = %#v, %v", got, err) + } + return + } + if err == nil || !strings.Contains(err.Error(), tc.wantErr) || got != nil { + t.Fatalf("read-only metadata = %#v, %v; want %q", got, err, tc.wantErr) + } + }) + } +} + +func TestCrossPlatformCoverageResolveProfileMetadataReadOnlyRejectsUnknownSelector(t *testing.T) { + testseam.Swap(t, &profilesReadFile, func(string) ([]byte, error) { + return []byte(`{"version":3,"currentProfile":"corp-a:user-a","profiles":[{"name":"alpha","corpId":"corp-a","userId":"user-a"}]}`), nil + }) + profile, err := ResolveProfileMetadataReadOnly("/config", "missing") + if err == nil || profile != nil || !strings.Contains(err.Error(), "not found") { + t.Fatalf("unknown read-only profile = %#v, %v", profile, err) + } +} diff --git a/third_party/aem-go-sdk/README.md b/third_party/aem-go-sdk/README.md new file mode 100644 index 00000000..226cb666 --- /dev/null +++ b/third_party/aem-go-sdk/README.md @@ -0,0 +1,20 @@ +# AEM Go SDK offline snapshot + +This directory contains the source packages required by the DWS CLI from the +private AEM Go SDK. The root module uses a local `replace` directive so builds +do not need access to `gitlab.alibaba-inc.com`. + +- Upstream module: `gitlab.alibaba-inc.com/aes/aem-go-sdk` +- Upstream version: `v0.3.0` +- Upstream commit: `2b5103b2f8899fa6e96611389c655e189a107f3b` +- Snapshot packages: `aem`, `clitrack`, `internal/encoder`, `internal/sender` + +DWS carries one reviewed privacy extension on top of the upstream snapshot: +`clitrack.Config.NoAutomaticDimensions` disables the SDK's device, operating +system, locale, session, and other automatic dimensions. The official DWS +entrypoint enables this mode and tests the final encoded payload as an exact +field whitelist. + +The upstream `v0.3.0` source tree did not contain a `LICENSE`, `NOTICE`, or +`COPYING` file. No replacement license text has been invented in this snapshot. +Redistribution authorization is managed by the repository owners. diff --git a/third_party/aem-go-sdk/aem/config.go b/third_party/aem-go-sdk/aem/config.go new file mode 100644 index 00000000..e40fd316 --- /dev/null +++ b/third_party/aem-go-sdk/aem/config.go @@ -0,0 +1,264 @@ +package aem + +import ( + "crypto/md5" + "crypto/rand" + "encoding/hex" + "fmt" + "net" + "os/exec" + "runtime" + "strconv" + "strings" + "time" + + "gitlab.alibaba-inc.com/aes/aem-go-sdk/internal/encoder" +) + +// AES 协议固定常量（不可修改，与 JS @ali/aes-tracker v3.3.18 对齐）。 +const ( + sdkVersion = "3.3.18" + platformGo = "go" + uuidCharset = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXTZabcdefghiklmnopqrstuvwxyz" // 60 字符（缺 Y 和 j） + uuidLength = 20 +) + +const ( + configPID = "pid" + configAppName = "app_name" + configEnv = "env" + configEndpoint = "endpoint" + configVersion = "version" + configAsync = "async" + configQueueSize = "queue_size" + // configDisableAutoDimensions is a local privacy control. It is never + // serialized; callers that enable it receive only explicitly configured + // dimensions plus app_version derived from version. + configDisableAutoDimensions = "disable_auto_dimensions" +) + +// Config 是 SDK 接入参数，key 与 AEM 协议字段保持一致。 +// +// 仅 pid 必填，其余字段为空时由 applyDefaults 填充默认值。Go SDK 会上报 +// 服务端适用的公共维度，例如 app_name、env、version、uid、username、 +// user_type、dim1~dim10、sid、bucket_id、ext。async、queue_size、endpoint +// 是 SDK 本地控制项，不会作为公共维度上报。 +type Config map[string]interface{} + +var supportedSendConfigKeys = map[string]struct{}{ + configPID: {}, + configAppName: {}, + configEnv: {}, + configVersion: {}, + "user_type": {}, + "uid": {}, + "username": {}, + "sid": {}, + "bucket_id": {}, + "ext": {}, + "platform": {}, +} + +func init() { + for i := 1; i <= 10; i++ { + supportedSendConfigKeys[fmt.Sprintf("dim%d", i)] = struct{}{} + } +} + +func cloneConfig(c Config) Config { + cloned := make(Config, len(c)) + for k, v := range c { + cloned[k] = v + } + return cloned +} + +// applyDefaults 为可选字段填充默认值，并返回新的配置副本。 +func applyDefaults(c Config) Config { + cloned := cloneConfig(c) + if stringValue(cloned, configAppName) == "" { + cloned[configAppName] = "unknown" + } + if stringValue(cloned, configEnv) == "" { + cloned[configEnv] = "prod" + } + if stringValue(cloned, configEndpoint) == "" { + cloned[configEndpoint] = "gm.mmstat.com" + } + if stringValue(cloned, configVersion) == "" { + cloned[configVersion] = "unknown" + } + if _, ok := cloned[configAsync]; !ok { + cloned[configAsync] = true + } + if intValue(cloned, configQueueSize) <= 0 { + cloned[configQueueSize] = 1000 + } + return cloned +} + +// buildSendConfig 构建 gokey 编码所需的全局维度 map。 +// +// 默认包含 AES 协议的 sdk_version/platform/device_id/os/os_version/app_name/ +// app_version/pv_id/timezone_offset 自动采集字段，加上用户配置的 pid/env/uid/ +// username/version/user_type/dim1~dim10/sid/bucket_id/ext 等公共维度。启用 +// disable_auto_dimensions 时仅保留显式配置字段和由 version 派生的 app_version。 +// 空值字段不会被写入；page_id、utm_* 等页面/浏览器字段不会在 Go SDK 中上报。 +func buildSendConfig(c Config) map[string]string { + m := make(map[string]string, len(c)+8) + for k, v := range c { + if _, ok := supportedSendConfigKeys[k]; !ok { + continue + } + if s, ok := encoder.ItemToString(v); ok { + m[k] = s + } + } + if boolValue(c, configDisableAutoDimensions) { + if v, ok := m["version"]; ok && v != "" { + m["app_version"] = v + } + return m + } + + m["sdk_version"] = sdkVersion + if _, ok := m["platform"]; !ok { + m["platform"] = platformGo + } + m["device_id"] = getDeviceID() + m["os"] = capitalizeOS() + m["os_version"] = getOSVersion() + if v, ok := m["version"]; ok && v != "" { + m["app_version"] = v + } else { + m["app_version"] = runtime.Version() + } + m["pv_id"] = generateUUID() + m["timezone_offset"] = getTimezoneOffset() + + return m +} + +func stringValue(c Config, key string) string { + if c == nil { + return "" + } + v, ok := c[key] + if !ok { + return "" + } + s, ok := encoder.ItemToString(v) + if !ok { + return "" + } + return s +} + +func boolValue(c Config, key string) bool { + if c == nil { + return false + } + v, ok := c[key] + if !ok { + return false + } + switch val := v.(type) { + case bool: + return val + case string: + b, err := strconv.ParseBool(val) + return err == nil && b + default: + return false + } +} + +func intValue(c Config, key string) int { + s := stringValue(c, key) + if s == "" { + return 0 + } + n, err := strconv.Atoi(s) + if err != nil { + return 0 + } + return n +} + +// getMAC 返回第一个非零的网卡 MAC 地址；获取失败时返回 "00:00:00:00:00:00"。 +func getMAC() string { + ifaces, err := net.Interfaces() + if err != nil { + return "00:00:00:00:00:00" + } + for _, iface := range ifaces { + mac := iface.HardwareAddr + if len(mac) == 0 { + continue + } + macStr := mac.String() + if macStr != "" && macStr != "00:00:00:00:00:00" { + return macStr + } + } + return "00:00:00:00:00:00" +} + +// getDeviceID 用 MAC 地址的 MD5 hex 作为设备指纹。 +func getDeviceID() string { + hash := md5.Sum([]byte(getMAC())) + return hex.EncodeToString(hash[:]) +} + +// getOSVersion 调用系统命令获取内核版本字符串。 +func getOSVersion() string { + switch runtime.GOOS { + case "windows": + out, err := exec.Command("cmd", "/c", "ver").Output() + if err != nil { + return "Windows" + } + return strings.TrimSpace(string(out)) + default: + out, err := exec.Command("uname", "-r").Output() + if err != nil { + return "unknown" + } + return strings.TrimSpace(string(out)) + } +} + +// getTimezoneOffset 对齐 JS Date.getTimezoneOffset()。东八区返回 "-480"。 +func getTimezoneOffset() string { + _, offset := time.Now().Zone() + return fmt.Sprintf("%d", -(offset / 60)) +} + +// capitalizeOS 把 runtime.GOOS 首字母大写（"darwin" → "Darwin"）。 +func capitalizeOS() string { + osName := runtime.GOOS + if len(osName) == 0 { + return osName + } + return strings.ToUpper(osName[:1]) + osName[1:] +} + +// generateUUID 生成 20 字符的随机 ID，字符集与 JS 版严格一致。 +// +// 使用 rejection sampling 保证字符分布均匀（拒绝阈值 240 = 60*4）。 +func generateUUID() string { + charsetLen := len(uuidCharset) // 60 + maxByte := byte(256 - 256%charsetLen) // 240 + result := make([]byte, uuidLength) + buf := make([]byte, 1) + for i := 0; i < uuidLength; i++ { + for { + _, _ = rand.Read(buf) + if buf[0] < maxByte { + result[i] = uuidCharset[buf[0]%byte(charsetLen)] + break + } + } + } + return string(result) +} diff --git a/third_party/aem-go-sdk/aem/config_test.go b/third_party/aem-go-sdk/aem/config_test.go new file mode 100644 index 00000000..7efa54eb --- /dev/null +++ b/third_party/aem-go-sdk/aem/config_test.go @@ -0,0 +1,54 @@ +package aem + +import ( + "slices" + "sort" + "testing" +) + +func TestBuildSendConfigPublishesCLIIdentityAndVersion(t *testing.T) { + got := buildSendConfig(Config{ + "pid": "pid-1", + "app_name": "dws", + "version": "v1.2.3", + "uid": "user-1", + }) + + for key, want := range map[string]string{ + "version": "v1.2.3", + "app_version": "v1.2.3", + "uid": "user-1", + } { + if got[key] != want { + t.Fatalf("send config %s = %q, want %q", key, got[key], want) + } + } +} + +func TestBuildSendConfigCanDisableAutomaticDimensions(t *testing.T) { + got := buildSendConfig(Config{ + "pid": "pid-1", + "app_name": "dws", + "env": "prod", + "version": "v1.2.3", + "platform": "cli", + "uid": "user-1", + "username": "Alice", + configDisableAutoDimensions: true, + }) + + gotKeys := make([]string, 0, len(got)) + for key := range got { + gotKeys = append(gotKeys, key) + } + sort.Strings(gotKeys) + wantKeys := []string{"app_name", "app_version", "env", "pid", "platform", "uid", "username", "version"} + if !slices.Equal(gotKeys, wantKeys) { + t.Fatalf("privacy send config keys = %v, want %v", gotKeys, wantKeys) + } + for _, key := range []string{"device_id", "ext", "os", "os_version", "pv_id", "sdk_version", "sid", "timezone_offset"} { + if _, ok := got[key]; ok { + t.Fatalf("privacy send config contains automatic dimension %q: %#v", key, got) + } + } +} diff --git a/third_party/aem-go-sdk/aem/event.go b/third_party/aem-go-sdk/aem/event.go new file mode 100644 index 00000000..d920bc0a --- /dev/null +++ b/third_party/aem-go-sdk/aem/event.go @@ -0,0 +1,36 @@ +package aem + +// Event 是一次上报的载荷。Type 决定字段语义（api/event 等）， +// Fields 携带 p1~p20、c1~c10、ext 以及 url、status 等业务维度。 +// +// 字段命名约定： +// - 通用字段：type、ts（毫秒） +// - 自定义事件：type=event，p1 为事件 ID，p4 为事件类型（EXP/CLK/SLD/INPUT/SYS/OTHER） +// - 平台保留：p1~p20（不同 type 含义不同，详见 AES 协议文档） +// - 用户自定义：c1~c10 +// - 扩展 JSON：ext +// +// Fields 中值为空字符串的键会在序列化时被自动丢弃。 +type Event struct { + // Type 事件类型，如 "api"、"event"。必填。 + Type string + + // Fields 业务字段。Track 时会补全 ts；其余键的语义由调用方决定。 + Fields map[string]string +} + +// toMap 把 Event 序列化为 SDK 内部使用的 map 形式，过滤空值。 +// +// 注意：返回的 map 是新分配的，调用方修改不会影响原 Event。 +func (e Event) toMap() map[string]string { + m := make(map[string]string, len(e.Fields)+1) + if e.Type != "" { + m["type"] = e.Type + } + for k, v := range e.Fields { + if v != "" { + m[k] = v + } + } + return m +} diff --git a/third_party/aem-go-sdk/aem/tracker.go b/third_party/aem-go-sdk/aem/tracker.go new file mode 100644 index 00000000..efbe8d49 --- /dev/null +++ b/third_party/aem-go-sdk/aem/tracker.go @@ -0,0 +1,173 @@ +// Package aem 提供阿里巴巴 AEM (Application Experience Management) 平台的 Go 上报 SDK。 +// +// 它适用于任何 Go 程序（web server、cron job、library 等），通过 Tracker.Track +// 将埋点事件加入后台队列并异步上报到 AES 后端。 +// +// 简单用法： +// +// tracker := aem.NewTracker(aem.Config{ +// "pid": "your_project_id", +// "app_name": "my-service", +// "env": "prod", +// "version": "1.0.0", +// }) +// defer tracker.Close() +// +// tracker.Track(aem.Event{ +// Type: "api", +// Fields: map[string]string{ +// "url": "/api/user", "status": "200", "duration": "120", +// }, +// }) +package aem + +import ( + "errors" + "fmt" + "sync" + "time" + + "gitlab.alibaba-inc.com/aes/aem-go-sdk/internal/encoder" + "gitlab.alibaba-inc.com/aes/aem-go-sdk/internal/sender" +) + +// ErrQueueFull 表示异步上报队列已满，本次事件没有入队。 +var ErrQueueFull = errors.New("aem: async queue is full") + +// ErrTrackerClosed 表示 Tracker 已关闭，不能再接收新的事件。 +var ErrTrackerClosed = errors.New("aem: tracker is closed") + +// Tracker 是 SDK 的核心入口，封装了配置、全局维度和上报通道。 +// +// 一个进程通常只创建一个 Tracker，并发调用 Track 是安全的。生命周期内 +// sendCfg 只构建一次以降低开销。 +type Tracker struct { + config Config + sendCfg map[string]string + + async bool + queue chan string + workerDone chan struct{} + + mu sync.RWMutex + closed bool + asyncErr error +} + +// NewTracker 创建并初始化一个 Tracker。默认会立刻填充并采集设备维度 +// （MAC、OS、PVID 等）；启用 disable_auto_dimensions 时跳过这些采集。 +func NewTracker(c Config) *Tracker { + cfg := applyDefaults(c) + t := &Tracker{ + config: cfg, + sendCfg: buildSendConfig(cfg), + async: boolValue(cfg, configAsync), + } + if t.async { + t.queue = make(chan string, intValue(cfg, configQueueSize)) + t.workerDone = make(chan struct{}) + go t.runWorker() + } + return t +} + +// Track 上报一个事件，失败时返回 error。 +// +// 如果 Event 没有自带 ts 字段，Track 会自动补 time.Now().UnixMilli()。 +// 默认 async=true 时，Track 只负责把事件写入内存队列，不等待远端 HTTP 请求完成； +// 返回 error 仅表示参数校验、队列已满或 Tracker 已关闭。async=false 时，Track +// 会在当前 goroutine 内同步发送并返回远端发送结果。 +func (t *Tracker) Track(event Event) error { + if stringValue(t.config, configPID) == "" { + return errors.New(`aem: config field "pid" is required`) + } + if event.Type == "" { + return errors.New("aem: Event.Type is required") + } + + fields := event.toMap() + if _, ok := fields["ts"]; !ok { + fields["ts"] = fmt.Sprintf("%d", time.Now().UnixMilli()) + } + + gokey := encoder.ProcessData([]map[string]string{fields}, t.sendCfg) + + if !t.async { + t.mu.RLock() + closed := t.closed + t.mu.RUnlock() + if closed { + return ErrTrackerClosed + } + return t.send(gokey) + } + + t.mu.RLock() + defer t.mu.RUnlock() + if t.closed { + return ErrTrackerClosed + } + select { + case t.queue <- gokey: + return nil + default: + return ErrQueueFull + } +} + +func (t *Tracker) runWorker() { + defer close(t.workerDone) + for gokey := range t.queue { + if err := t.send(gokey); err != nil { + t.asyncErr = err + } + } +} + +// userAgent builds the User-Agent header from config: "app_name/version". +func (t *Tracker) userAgent() string { + name := stringValue(t.config, configAppName) + ver := stringValue(t.config, configVersion) + if name == "" || name == "unknown" { + return "" + } + if ver != "" && ver != "unknown" { + return name + "/" + ver + } + return name +} + +func (t *Tracker) send(gokey string) error { + return sender.Send(stringValue(t.config, configEndpoint), gokey, t.userAgent()) +} + +// Config 返回 Tracker 当前使用的配置（副本）。 +// +// 返回值是副本，修改它不会影响 Tracker 内部配置。 +func (t *Tracker) Config() Config { + return cloneConfig(t.config) +} + +// Close 释放 Tracker 持有的资源。 +// +// async=true 时，Close 会停止接收新事件，并等待队列中已入队的事件发送完成。 +// 如果后台发送发生错误，Close 返回最后一次发送错误。 +func (t *Tracker) Close() error { + if !t.async { + t.mu.Lock() + t.closed = true + t.mu.Unlock() + return nil + } + + t.mu.Lock() + if !t.closed { + t.closed = true + close(t.queue) + } + workerDone := t.workerDone + t.mu.Unlock() + + <-workerDone + return t.asyncErr +} diff --git a/third_party/aem-go-sdk/clitrack/capture.go b/third_party/aem-go-sdk/clitrack/capture.go new file mode 100644 index 00000000..e88ccbef --- /dev/null +++ b/third_party/aem-go-sdk/clitrack/capture.go @@ -0,0 +1,37 @@ +package clitrack + +import ( + "bytes" + "io" + "os" +) + +// captureStdout 拦截 stdout,将 fn 的输出同时写到原 stdout 和 buffer。 +// 返回捕获到的输出内容和 fn 的 error。Pipe 创建失败时降级为不捕获, +// 保证 fn 一定被执行。 +// +// 注意:这会临时替换 os.Stdout,对依赖 TTY 检测、进度条、ANSI 颜色的 CLI +// 可能有副作用——这正是 CaptureOutput 默认关闭的原因。 +func captureStdout(fn func() error) (string, error) { + old := os.Stdout + r, w, err := os.Pipe() + if err != nil { + return "", fn() + } + os.Stdout = w + + var buf bytes.Buffer + done := make(chan struct{}) + go func() { + _, _ = io.Copy(io.MultiWriter(old, &buf), r) + close(done) + }() + + execErr := fn() + + w.Close() + <-done + os.Stdout = old + + return buf.String(), execErr +} diff --git a/third_party/aem-go-sdk/clitrack/clitrack.go b/third_party/aem-go-sdk/clitrack/clitrack.go new file mode 100644 index 00000000..70df9882 --- /dev/null +++ b/third_party/aem-go-sdk/clitrack/clitrack.go @@ -0,0 +1,275 @@ +package clitrack + +import ( + "fmt" + "os" + "strconv" + "time" + + "gitlab.alibaba-inc.com/aes/aem-go-sdk/aem" +) + +// 默认值。 +const ( + defaultEventID = "cli.exec" // p1:AEM 自定义事件 ID + eventTypeSys = "SYS" // p4:AEM 事件类型,系统事件 + defaultOutputLen = 500 // c8 截断长度 + maxErrorLen = 200 // c5 截断长度 +) + +// defaultFlushTimeout 是 CLI 退出前等待异步队列 flush 的最长时间。 +// 到点未发完就放弃上报直接退出——宁可丢这条埋点,也不让用户等。 +const defaultFlushTimeout = 300 * time.Millisecond + +// Config 是 clitrack 接入配置。只有 PID 必填,其余都有合理默认值。 +type Config struct { + // —— 必填 —— + PID string // AEM 项目 ID + + // —— 应用维度 —— + App string // CLI 名称,默认 "unknown" + Env string // 环境:prod/pre/daily,默认 prod + Version string // CLI 版本号(建议用 ldflags 注入) + + // —— 用户维度(可选,接入方自己填,本包不读取任何凭据文件)—— + UID string // 用户 ID,如工号 + Username string // 用户名 + UserType string // 账号类型,如 "14" + + // —— 行为 —— + EventID string // p1 事件 ID,默认 "cli.exec" + Endpoint string // 上报域名,海外站点填 sg.mmstat.com;默认走 SDK 默认 + + // CaptureOutput 控制是否捕获 stdout 到 c8。默认 false。 + // 捕获会用 os.Pipe 劫持 os.Stdout,可能干扰进度条/TTY 检测/颜色输出, + // 仅在确认 CLI 输出适合采集时开启。 + CaptureOutput bool + OutputMaxLen int // c8 截断长度,默认 500;仅在 CaptureOutput 时生效 + + // FlushTimeout 是退出前等待上报完成的最长时间,默认 300ms。 + FlushTimeout time.Duration + + // —— 字段级隐私开关(给接入开发者的编译期选项,默认采集)—— + NoCommandLine bool // 不采 c2 完整命令行(命令行常带敏感参数时设 true) + NoCwd bool // 不采 c7 工作目录 + // NoAutomaticDimensions 只保留接入方显式配置的公共维度，并关闭 + // device_id、os、os_version、timezone_offset、pv_id、sdk_version、sid、 + // ext.language 与 c6 Shell 自动采集。 + NoAutomaticDimensions bool + + // —— 扩展钩子 —— + // ExtraFields 返回的字段会合并进事件,用于补充 c9/c10/ext 等自定义维度。 + // 不要覆盖 c1~c8 的约定语义,否则破坏跨 CLI 聚合。空值字段会被忽略。 + ExtraFields func() map[string]string +} + +// Tracker 是埋点实例,通过 New 创建,通过 Run 执行 CLI 并自动上报。 +type Tracker struct { + inner *aem.Tracker + + eventID string + captureOutput bool + outputMaxLen int + flushTimeout time.Duration + noCommandLine bool + noCwd bool + noAutomaticDimensions bool + extraFields func() map[string]string +} + +// New 根据配置创建 Tracker。 +// +// 如果 PID 为空,返回空实例:Run 仍可正常执行 CLI,只是不上报。这样接入方 +// 在缺少 PID(如本地开发)时无需加任何判断,埋点自动降级为 no-op。 +func New(cfg Config) *Tracker { + if cfg.PID == "" { + return &Tracker{} + } + + env := cfg.Env + if env == "" { + env = "prod" + } + app := cfg.App + if app == "" { + app = "unknown" + } + eventID := cfg.EventID + if eventID == "" { + eventID = defaultEventID + } + outputMaxLen := cfg.OutputMaxLen + if outputMaxLen <= 0 { + outputMaxLen = defaultOutputLen + } + flushTimeout := cfg.FlushTimeout + if flushTimeout <= 0 { + flushTimeout = defaultFlushTimeout + } + + aemCfg := aem.Config{ + "pid": cfg.PID, + "app_name": app, + "env": env, + "version": cfg.Version, + "platform": "cli", + } + if cfg.NoAutomaticDimensions { + aemCfg["disable_auto_dimensions"] = true + } + if cfg.Endpoint != "" { + aemCfg["endpoint"] = cfg.Endpoint + } + if cfg.UID != "" { + aemCfg["uid"] = cfg.UID + } + if cfg.Username != "" { + aemCfg["username"] = cfg.Username + } + if cfg.UserType != "" { + aemCfg["user_type"] = cfg.UserType + } + + if !cfg.NoAutomaticDimensions { + // sid:终端会话 ID,自动从环境变量采集(数据维度,非配置开关)。 + sid := os.Getenv("TERM_SESSION_ID") + if sid == "" { + sid = os.Getenv("TMUX_PANE") + } + if sid != "" { + aemCfg["sid"] = sid + } + + // ext.language:终端 locale,自动采集。 + lang := os.Getenv("LANG") + if lang == "" { + lang = os.Getenv("LC_ALL") + } + if lang != "" { + aemCfg["ext"] = fmt.Sprintf(`{"language":%q}`, lang) + } + } + + return &Tracker{ + inner: aem.NewTracker(aemCfg), + eventID: eventID, + captureOutput: cfg.CaptureOutput, + outputMaxLen: outputMaxLen, + flushTimeout: flushTimeout, + noCommandLine: cfg.NoCommandLine, + noCwd: cfg.NoCwd, + noAutomaticDimensions: cfg.NoAutomaticDimensions, + extraFields: cfg.ExtraFields, + } +} + +// Run 执行 CLI 主函数并自动上报埋点。 +// +// 自动完成:计时、从 os.Args 采集入参、推导退出码、(可选)捕获 stdout、 +// 错误输出到 stderr、best-effort flush(带超时,不阻塞退出)。 +// +// execute CLI 入口,返回 error;cobra 直接传 rootCmd.Execute。 +// exitCode 把 error 映射为退出码;传 nil 用默认映射(nil→0,其余→1)。 +// +// 与现状一致:退出码非 0 时调用 os.Exit;为 0 时正常 return,不调 os.Exit。 +func (t *Tracker) Run(execute func() error, exitCode func(error) int) { + if exitCode == nil { + exitCode = defaultExitCode + } + + start := time.Now() + + var output string + var err error + if t.captureOutput { + output, err = captureStdout(execute) + } else { + err = execute() + } + + code := 0 + var errStr string + if err != nil { + code = exitCode(err) + errStr = err.Error() + if errStr != "" { + fmt.Fprintln(os.Stderr, errStr) + } + } + + t.trackExec(code, time.Since(start), errStr, output) + t.close() + + if code != 0 { + os.Exit(code) + } +} + +// trackExec 上报一次命令执行事件。 +func (t *Tracker) trackExec(exitCode int, duration time.Duration, errMsg, output string) { + if t.inner == nil { + return + } + _ = t.inner.Track(aem.Event{ + Type: "event", + Fields: t.buildFields(exitCode, duration, errMsg, output), + }) +} + +// buildFields 按字段约定组装一次命令执行的事件字段(纯函数,便于测试)。 +func (t *Tracker) buildFields(exitCode int, duration time.Duration, errMsg, output string) map[string]string { + fields := map[string]string{ + "p1": t.eventID, + "p4": eventTypeSys, + "c1": command(), + "c3": strconv.Itoa(exitCode), + "c4": strconv.FormatInt(duration.Milliseconds(), 10), + } + if !t.noAutomaticDimensions { + fields["c6"] = shellType() + } + if !t.noCommandLine { + fields["c2"] = commandLine() + } + if !t.noCwd { + fields["c7"] = cwd() + } + if errMsg != "" { + fields["c5"] = truncate(errMsg, maxErrorLen) + } + if output != "" { + fields["c8"] = truncate(output, t.outputMaxLen) + } + if t.extraFields != nil { + for k, v := range t.extraFields() { + if v != "" { + fields[k] = v + } + } + } + return fields +} + +// close 关闭内部 Tracker,best-effort flush:最多等 flushTimeout,超时即放弃。 +func (t *Tracker) close() { + if t.inner == nil { + return + } + done := make(chan struct{}) + go func() { + _ = t.inner.Close() + close(done) + }() + select { + case <-done: + case <-time.After(t.flushTimeout): + } +} + +// defaultExitCode 是 exitCode 参数为 nil 时的默认映射。 +func defaultExitCode(err error) int { + if err == nil { + return 0 + } + return 1 +} diff --git a/third_party/aem-go-sdk/clitrack/clitrack_test.go b/third_party/aem-go-sdk/clitrack/clitrack_test.go new file mode 100644 index 00000000..92aee86c --- /dev/null +++ b/third_party/aem-go-sdk/clitrack/clitrack_test.go @@ -0,0 +1,21 @@ +package clitrack + +import ( + "testing" + "time" +) + +func TestBuildFieldsKeepsOrganizationDimension(t *testing.T) { + tracker := &Tracker{ + noCommandLine: true, + noCwd: true, + extraFields: func() map[string]string { + return map[string]string{"c9": "version", "c10": "corp-1"} + }, + } + + fields := tracker.buildFields(0, time.Millisecond, "", "") + if fields["c9"] != "version" || fields["c10"] != "corp-1" { + t.Fatalf("custom telemetry fields = %#v", fields) + } +} diff --git a/third_party/aem-go-sdk/clitrack/doc.go b/third_party/aem-go-sdk/clitrack/doc.go new file mode 100644 index 00000000..4c724540 --- /dev/null +++ b/third_party/aem-go-sdk/clitrack/doc.go @@ -0,0 +1,51 @@ +// Package clitrack 在 aem 核心 SDK 之上,为任意 Go CLI 提供零侵入的使用埋点。 +// +// 设计理念:CLI 入口只需一行 clitrack.New(cfg).Run(...),剩下全部自动完成—— +// 从 os.Args 采集原始入参、自动计时、自动推导命令路径和退出码、异步上报。 +// +// 埋点尽力而为,数据可丢,但绝不阻塞 CLI 退出(见 FlushTimeout)。接入方负责 +// 向最终用户披露采集范围并提供符合其产品要求的退出机制。 +// +// 最小接入示例(以 cobra CLI 为例): +// +// func Execute() { +// clitrack.New(clitrack.Config{ +// PID: "your-pid", App: "my-cli", Version: version, +// }).Run(rootCmd.Execute, nil) +// } +// +// 框架无关:Run 只要求一个 func() error 入口,cobra / urfave-cli / 标准库 flag +// 都能套。exitCode 传 nil 时用默认映射(nil→0,其余→1)。 +// +// AEM 字段映射约定(所有接入的 CLI 统一遵守,这是跨 CLI 聚合分析的基础): +// +// Config 维度(初始化时设一次): +// pid → Config.PID AEM 项目 ID(必填) +// app_name → Config.App CLI 名称 +// env → Config.Env 环境 (prod/pre/daily),默认 prod +// version → Config.Version CLI 版本号 +// uid → Config.UID 用户 ID(可选,接入方自己填) +// username → Config.Username 用户名(可选) +// user_type → Config.UserType 账号类型(可选) +// endpoint → Config.Endpoint 上报域名(可选,海外站点填 sg.mmstat.com) +// sid → $TERM_SESSION_ID 终端会话 ID(自动采集,NoAutomaticDimensions 可关) +// ext.language → $LANG 终端 locale(自动采集,NoAutomaticDimensions 可关) +// +// Event 维度(每次命令执行打一条,type = "event"): +// p1 → "cli.exec" AEM 自定义事件 ID(默认值,可用 Config.EventID 覆盖) +// p4 → "SYS" AEM 事件类型:系统事件(固定值) +// c1 → command filepath.Base(os.Args[0])(CLI 二进制名,如 "aem") +// c2 → command_line os.Args[1:] 拼接(完整参数);Config.NoCommandLine 可关 +// c3 → exit_code 退出码 +// c4 → duration_ms 执行耗时(毫秒) +// c5 → error_message 错误摘要,截断 200 字符 +// c6 → shell_type Shell 类型(zsh/bash 等);NoAutomaticDimensions 可关 +// c7 → cwd 当前工作目录;Config.NoCwd 可关 +// c8 → output CLI stdout 输出摘要;默认不采,Config.CaptureOutput 显式开启 +// c9/c10/ext → 自定义 由 Config.ExtraFields 钩子返回 +// +// Config.NoAutomaticDimensions 会关闭设备、操作系统、时区、随机会话、终端会话、 +// locale 和 Shell 等自动维度,只保留接入方显式配置的公共维度和事件字段。本包不读取 +// 产品级退出环境变量;接入应用应在创建 Tracker 前执行自己的退出策略。PID 为空时 +// Tracker 自动降级为 no-op,命令仍正常执行。 +package clitrack diff --git a/third_party/aem-go-sdk/clitrack/fields.go b/third_party/aem-go-sdk/clitrack/fields.go new file mode 100644 index 00000000..55c1c53c --- /dev/null +++ b/third_party/aem-go-sdk/clitrack/fields.go @@ -0,0 +1,44 @@ +package clitrack + +import ( + "os" + "path/filepath" + "strings" +) + +// command 返回 CLI 二进制名(c1),如 "aem"。 +func command() string { + return filepath.Base(os.Args[0]) +} + +// commandLine 返回完整命令行参数(c2),如 "login --env prod"。 +func commandLine() string { + return strings.Join(os.Args[1:], " ") +} + +// shellType 返回当前 Shell 类型(c6),取 $SHELL 的 basename(如 "zsh"、"bash")。 +func shellType() string { + shell := os.Getenv("SHELL") + if shell == "" { + return "" + } + return filepath.Base(shell) +} + +// cwd 返回当前工作目录(c7),失败返回空字符串。 +func cwd() string { + dir, _ := os.Getwd() + return dir +} + +// truncate 按 rune 截断字符串到 maxLen,超出部分用 "..." 替换。 +func truncate(s string, maxLen int) string { + runes := []rune(s) + if len(runes) <= maxLen { + return s + } + if maxLen <= 3 { + return string(runes[:maxLen]) + } + return string(runes[:maxLen-3]) + "..." +} diff --git a/third_party/aem-go-sdk/go.mod b/third_party/aem-go-sdk/go.mod new file mode 100644 index 00000000..6fea714c --- /dev/null +++ b/third_party/aem-go-sdk/go.mod @@ -0,0 +1,3 @@ +module gitlab.alibaba-inc.com/aes/aem-go-sdk + +go 1.25.7 diff --git a/third_party/aem-go-sdk/internal/encoder/gokey.go b/third_party/aem-go-sdk/internal/encoder/gokey.go new file mode 100644 index 00000000..fb7e3173 --- /dev/null +++ b/third_party/aem-go-sdk/internal/encoder/gokey.go @@ -0,0 +1,97 @@ +package encoder + +import ( + "encoding/json" + "fmt" + "net/url" + "sort" + "strings" +) + +func EncodeURIComponent(s string) string { + result := url.QueryEscape(s) + result = strings.ReplaceAll(result, "+", "%20") + result = strings.ReplaceAll(result, "%21", "!") + result = strings.ReplaceAll(result, "%27", "'") + result = strings.ReplaceAll(result, "%28", "(") + result = strings.ReplaceAll(result, "%29", ")") + result = strings.ReplaceAll(result, "%2A", "*") + return result +} + +func ItemToString(v interface{}) (string, bool) { + if v == nil { + return "", false + } + switch val := v.(type) { + case string: + if val == "" { + return "", false + } + return val, true + case float64: + if val == float64(int64(val)) { + return fmt.Sprintf("%d", int64(val)), true + } + return fmt.Sprintf("%g", val), true + case int: + return fmt.Sprintf("%d", val), true + case int64: + return fmt.Sprintf("%d", val), true + case bool: + if val { + return "true", true + } + return "false", true + case json.Number: + return val.String(), true + case map[string]interface{}, []interface{}: + b, err := json.Marshal(val) + if err != nil { + return "", false + } + return string(b), true + default: + return "", false + } +} + +func ObjToQS(m map[string]string) string { + keys := make([]string, 0, len(m)) + for k := range m { + keys = append(keys, k) + } + sort.Strings(keys) + + parts := make([]string, 0, len(m)) + for _, k := range keys { + v := m[k] + if v == "" { + continue + } + parts = append(parts, k+"="+EncodeURIComponent(v)) + } + return strings.Join(parts, "&") +} + +func ToStringMap(data map[string]interface{}) map[string]string { + result := make(map[string]string, len(data)) + for k, v := range data { + if s, ok := ItemToString(v); ok { + result[k] = s + } + } + return result +} + +func ProcessData(logs []map[string]string, config map[string]string) string { + configQS := ObjToQS(config) + + logParts := make([]string, 0, len(logs)) + for _, log := range logs { + logParts = append(logParts, ObjToQS(log)) + } + logsJoined := strings.Join(logParts, "|") + + return configQS + "&msg=" + EncodeURIComponent(logsJoined) +} diff --git a/third_party/aem-go-sdk/internal/sender/sender.go b/third_party/aem-go-sdk/internal/sender/sender.go new file mode 100644 index 00000000..09eb4bad --- /dev/null +++ b/third_party/aem-go-sdk/internal/sender/sender.go @@ -0,0 +1,68 @@ +package sender + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" + "strings" + "time" + + "gitlab.alibaba-inc.com/aes/aem-go-sdk/internal/encoder" +) + +const httpTimeout = 5 * time.Second + +var httpClient = &http.Client{Timeout: httpTimeout} + +// Send 单次 HTTP POST 上报 gokey 到 AES 后端，不重试。 +// +// endpoint 不带 scheme 时默认 https://；以 http:// 或 https:// 开头时按原样使用。 +// 路径固定为 /aes.1.1，请求体为 {"gokey": encodeURIComponent(gokey), "gmkey": "EXP"}。 +func Send(endpoint string, gokey string, userAgent string) error { + u := buildURL(endpoint) + + body, err := json.Marshal(map[string]string{ + "gokey": encoder.EncodeURIComponent(gokey), + "gmkey": "EXP", + }) + if err != nil { + return fmt.Errorf("marshal body: %w", err) + } + + req, err := http.NewRequest("POST", u, bytes.NewReader(body)) + if err != nil { + return fmt.Errorf("create request: %w", err) + } + req.Header.Set("Content-Type", "application/json") + if userAgent != "" { + req.Header.Set("User-Agent", userAgent) + } + + resp, err := httpClient.Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + io.Copy(io.Discard, resp.Body) + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + return fmt.Errorf("HTTP %d", resp.StatusCode) + } + return nil +} + +func buildURL(endpoint string) string { + endpoint = strings.TrimRight(endpoint, "/") + var u string + if strings.HasPrefix(endpoint, "http://") || strings.HasPrefix(endpoint, "https://") { + u = endpoint + } else { + u = fmt.Sprintf("https://%s", endpoint) + } + if strings.HasSuffix(u, "/aes.1.1") { + return u + } + return u + "/aes.1.1" +} From 4d843cf7a4ec0c782567e7c19d5337d0f24f1b6c Mon Sep 17 00:00:00 2001 From: chichuan Date: Sat, 15 Aug 2026 16:23:14 +0800 Subject: [PATCH 142/250] feat: add feedback survey entry to root help MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `dws --help` now closes with a Feedback section that links the user-experience survey form, tagged with source=dws-cli so submissions arriving through the CLI can be told apart from other channels. The entry is deliberately root-only: this CLI is driven mostly by AI agents, and repeating a survey link in every subcommand help would be pure context noise. A guard test pins that boundary. The URL is printed on its own unwrapped line — it is longer than the help rule width, and breaking it would stop terminals from recognizing it as a clickable hyperlink. --- .changes/1019-help-feedback-entry.md | 5 ++++ internal/app/root_help.go | 24 +++++++++++++++++ internal/app/root_help_test.go | 40 ++++++++++++++++++++++++++++ internal/i18n/locales/en.json | 1 + internal/i18n/locales/zh.json | 1 + 5 files changed, 71 insertions(+) create mode 100644 .changes/1019-help-feedback-entry.md diff --git a/.changes/1019-help-feedback-entry.md b/.changes/1019-help-feedback-entry.md new file mode 100644 index 00000000..d0a67d3c --- /dev/null +++ b/.changes/1019-help-feedback-entry.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form, localized for `zh` and `en`. diff --git a/internal/app/root_help.go b/internal/app/root_help.go index 6bbb1a69..047a6f69 100644 --- a/internal/app/root_help.go +++ b/internal/app/root_help.go @@ -2,6 +2,7 @@ package app import ( "fmt" + "io" "strings" "text/tabwriter" @@ -13,6 +14,12 @@ import ( "github.com/spf13/pflag" ) +// feedbackFormURL points at the DingTalk Notable form collecting dws CLI +// user-experience feedback. The source parameter tags submissions that +// originated from the CLI help output so they can be told apart from +// responses arriving through other channels. +const feedbackFormURL = "https://alidocs.dingtalk.com/notable/share/form/v01eLbnj1bw1ELb0laN_dv19yqvsgs3oebp3pcjys_1qX0QQ0?source=dws-cli" + func configureRootHelp(root *cobra.Command) { if root == nil { return @@ -101,6 +108,23 @@ func renderRootHelp(root *cobra.Command) { _, _ = fmt.Fprintln(w) _, _ = fmt.Fprintln(w, tui.Dim(long)) } + + // Keep the feedback entry last: everything above it is operational guidance + // an agent acts on, while the survey is addressed to human readers who + // scroll to the end. + _, _ = fmt.Fprintln(w) + renderRootFeedback(w) +} + +// renderRootFeedback prints the user-experience survey entry. The URL occupies +// its own line and is never wrapped or padded through a tabwriter: it is longer +// than the help rule width, and breaking it would stop terminals from +// recognizing it as a clickable hyperlink. Soft wrapping performed by the +// terminal itself keeps the link intact. +func renderRootFeedback(w io.Writer) { + _, _ = fmt.Fprintln(w, tui.Section("Feedback:")) + _, _ = fmt.Fprintf(w, " %s %s\n", tui.Bullet(), tui.Dim(i18n.T("使用体验反馈问卷（1 分钟）"))) + _, _ = fmt.Fprintf(w, " %s\n", tui.Cyan(feedbackFormURL)) } func renderRootGlobalFlags(root *cobra.Command) { diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index 09fc432e..3a93833b 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -53,6 +53,46 @@ func TestRootHelpHidesCompatibilityOnlyCommands(t *testing.T) { } } +func TestRootHelpShowsFeedbackEntry(t *testing.T) { + cmd := NewRootCommand() + var out bytes.Buffer + cmd.SetOut(&out) + cmd.SetErr(&out) + cmd.SetArgs([]string{"--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("root help: %v\n%s", err, out.String()) + } + help := out.String() + for _, want := range []string{"Feedback:", feedbackFormURL} { + if !strings.Contains(help, want) { + t.Fatalf("root help missing %q:\n%s", want, help) + } + } + // The form URL is longer than the help rule width; it must stay on a + // single unbroken line so terminals keep recognizing it as a hyperlink. + if !strings.Contains(help, "\n "+feedbackFormURL+"\n") { + t.Fatalf("feedback URL must occupy one unwrapped line:\n%s", help) + } +} + +// The feedback entry is deliberately root-only: this CLI is driven mostly by +// AI agents, and repeating a survey link in every subcommand help would be +// pure context noise. Guard the boundary so a future refactor cannot move the +// rendering into the shared subcommand help path unnoticed. +func TestSubcommandHelpOmitsFeedbackEntry(t *testing.T) { + cmd := NewRootCommand() + var out bytes.Buffer + cmd.SetOut(&out) + cmd.SetErr(&out) + cmd.SetArgs([]string{"chat", "--help"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("chat help: %v\n%s", err, out.String()) + } + if help := out.String(); strings.Contains(help, feedbackFormURL) { + t.Fatalf("subcommand help must not carry the feedback URL:\n%s", help) + } +} + func TestCalendarEventCreateHelpKeepsRoomsStringMetavar(t *testing.T) { cmd := NewRootCommand() var out bytes.Buffer diff --git a/internal/i18n/locales/en.json b/internal/i18n/locales/en.json index 81870ac1..42284729 100644 --- a/internal/i18n/locales/en.json +++ b/internal/i18n/locales/en.json @@ -36,6 +36,7 @@ "不是文件: ": "not a file: ", "人才查询": "Talent query", "优先级: 10低/20普通/30较高/40紧急": "Priority: 10=low/20=normal/30=high/40=urgent", + "使用体验反馈问卷（1 分钟）": "Share your feedback (1 min)", "使用授权码换取 Access Token...": "Exchanging authorization code for Access Token...", "保存 token 失败": "Failed to save token", "保存Keyword subscription规则": "Save keyword subscription rule", diff --git a/internal/i18n/locales/zh.json b/internal/i18n/locales/zh.json index 06b04ac5..c6023678 100644 --- a/internal/i18n/locales/zh.json +++ b/internal/i18n/locales/zh.json @@ -36,6 +36,7 @@ "不是文件: ": "不是文件: ", "人才查询": "人才查询", "优先级: 10低/20普通/30较高/40紧急": "优先级: 10低/20普通/30较高/40紧急", + "使用体验反馈问卷（1 分钟）": "使用体验反馈问卷（1 分钟）", "使用授权码换取 Access Token...": "使用授权码换取 Access Token...", "保存 token 失败": "保存 token 失败", "保存Keyword subscription规则": "保存Keyword subscription规则", From 1d02ff805d0b147561efbc85ce2d3dbf057b3565 Mon Sep 17 00:00:00 2001 From: chichuan Date: Sat, 15 Aug 2026 16:38:57 +0800 Subject: [PATCH 143/250] refactor: keep the feedback label out of i18n MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every neighbouring string in the root help listing — service descriptions, utility descriptions, global flag usage — is hardcoded Chinese. Routing only the feedback label through i18n therefore rendered it in English on any host whose LANG is not zh_*, leaving a lone English line inside an otherwise Chinese screen. Hardcode the label and drop the two locale entries it needed. A test assertion now pins the Chinese label so the indirection cannot return unnoticed. --- .changes/1019-help-feedback-entry.md | 2 +- internal/app/root_help.go | 8 +++++++- internal/app/root_help_test.go | 5 ++++- internal/i18n/locales/en.json | 1 - internal/i18n/locales/zh.json | 1 - 5 files changed, 12 insertions(+), 5 deletions(-) diff --git a/.changes/1019-help-feedback-entry.md b/.changes/1019-help-feedback-entry.md index d0a67d3c..72602203 100644 --- a/.changes/1019-help-feedback-entry.md +++ b/.changes/1019-help-feedback-entry.md @@ -2,4 +2,4 @@ category: Added --- -- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form, localized for `zh` and `en`. +- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form. diff --git a/internal/app/root_help.go b/internal/app/root_help.go index 047a6f69..7ce84908 100644 --- a/internal/app/root_help.go +++ b/internal/app/root_help.go @@ -121,9 +121,15 @@ func renderRootHelp(root *cobra.Command) { // than the help rule width, and breaking it would stop terminals from // recognizing it as a clickable hyperlink. Soft wrapping performed by the // terminal itself keeps the link intact. +// +// The label is intentionally not routed through i18n. Everything surrounding it +// in this listing — service descriptions, utility descriptions, global flag +// usage — is hardcoded Chinese, so translating this one line would render it in +// English on any host whose LANG is not zh_*, leaving a single English line +// inside an otherwise Chinese screen. func renderRootFeedback(w io.Writer) { _, _ = fmt.Fprintln(w, tui.Section("Feedback:")) - _, _ = fmt.Fprintf(w, " %s %s\n", tui.Bullet(), tui.Dim(i18n.T("使用体验反馈问卷（1 分钟）"))) + _, _ = fmt.Fprintf(w, " %s %s\n", tui.Bullet(), tui.Dim("使用体验反馈问卷（1 分钟）")) _, _ = fmt.Fprintf(w, " %s\n", tui.Cyan(feedbackFormURL)) } diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index 3a93833b..cce294d9 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -63,7 +63,10 @@ func TestRootHelpShowsFeedbackEntry(t *testing.T) { t.Fatalf("root help: %v\n%s", err, out.String()) } help := out.String() - for _, want := range []string{"Feedback:", feedbackFormURL} { + // The label stays Chinese regardless of the host locale: the rest of this + // listing is hardcoded Chinese, so a translated label would show up as a + // lone English line on any host whose LANG is not zh_*. + for _, want := range []string{"Feedback:", "使用体验反馈问卷", feedbackFormURL} { if !strings.Contains(help, want) { t.Fatalf("root help missing %q:\n%s", want, help) } diff --git a/internal/i18n/locales/en.json b/internal/i18n/locales/en.json index 42284729..81870ac1 100644 --- a/internal/i18n/locales/en.json +++ b/internal/i18n/locales/en.json @@ -36,7 +36,6 @@ "不是文件: ": "not a file: ", "人才查询": "Talent query", "优先级: 10低/20普通/30较高/40紧急": "Priority: 10=low/20=normal/30=high/40=urgent", - "使用体验反馈问卷（1 分钟）": "Share your feedback (1 min)", "使用授权码换取 Access Token...": "Exchanging authorization code for Access Token...", "保存 token 失败": "Failed to save token", "保存Keyword subscription规则": "Save keyword subscription rule", diff --git a/internal/i18n/locales/zh.json b/internal/i18n/locales/zh.json index c6023678..06b04ac5 100644 --- a/internal/i18n/locales/zh.json +++ b/internal/i18n/locales/zh.json @@ -36,7 +36,6 @@ "不是文件: ": "不是文件: ", "人才查询": "人才查询", "优先级: 10低/20普通/30较高/40紧急": "优先级: 10低/20普通/30较高/40紧急", - "使用体验反馈问卷（1 分钟）": "使用体验反馈问卷（1 分钟）", "使用授权码换取 Access Token...": "使用授权码换取 Access Token...", "保存 token 失败": "保存 token 失败", "保存Keyword subscription规则": "保存Keyword subscription规则", From ecce09b355db971ec19fbbb7e09c76cb8b33c7d2 Mon Sep 17 00:00:00 2001 From: chichuan Date: Sat, 15 Aug 2026 22:10:28 +0800 Subject: [PATCH 144/250] fix(ci): shard the focused test job instead of one long-lived run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The focused path tested every impacted package in a single job with a plain `go test -race`, so internal/app ran inside one long-lived process alongside all of its reverse dependencies. That is exactly the shape scripts/ci/run-app-race-tests.sh exists to avoid: a single app test process retains every constructed command tree in framework registries, so the run grows to 900s and the job stays alive long enough to be reclaimed by the runner. Recent focused runs failed with SIGTERM after 9-10 minutes without a single test failure, and one earlier run failed at `internal/app 902.651s`, 2.65s past the package timeout. Fan the same package plan across the shard matrix test-race already uses, and run each shard the way test-race runs it: internal/app through the process-isolating helper, cli/smoke with their wider package budget, release-scripts without race and with archive tooling. changed-test-packages.sh gains `list-shard`, which intersects the impacted set with scripts/ci/test-packages.sh shard membership so shard definitions stay single-sourced — and so an unknown shard name aborts there rather than reporting an empty selection, which would let a mistyped shard skip every test while reporting success. release-scripts is in the matrix on purpose: its dedicated job only runs at full-suite or release-sensitive scope, so omitting it here would stop testing test/scripts changes altogether. A test pins that the shard selections partition the impacted set exactly, so shard-plan drift cannot silently shrink focused coverage. --- .github/workflows/ci.yml | 81 ++++++- scripts/ci/changed-test-packages.sh | 55 ++++- test/scripts/changed_test_packages_test.go | 239 +++++++++++++++++++++ 3 files changed, 357 insertions(+), 18 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 02e72637..9d3fa1e3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -513,11 +513,28 @@ jobs: run: node .github/reviewer-routing.test.js test-focused: - name: Test (changed packages) + name: "Test (focused: ${{ matrix.shard }})" needs: lint if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite != 'true' }} runs-on: ubuntu-latest + # Each shard owns one bounded slice of the impacted set, so no single job + # carries internal/app together with every reverse dependency. The shard + # list and per-shard execution below mirror test-race, which runs the same + # shards at full-suite scope; release-scripts is included because its + # dedicated job only runs at full-suite or release-sensitive scope, and + # dropping it here would stop testing test/scripts changes entirely. timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + shard: + - app + - generators + - helpers + - cli + - smoke + - remaining + - release-scripts steps: - name: Check out repository uses: actions/checkout@v4 @@ -546,23 +563,69 @@ jobs: with: go-version-file: go.mod - - name: Test changed packages and reverse dependencies + - name: Select impacted packages for shard + id: select shell: bash env: - DWS_PACKAGE_VERSION: 0.0.0-test + TEST_SHARD: ${{ matrix.shard }} run: | set -euo pipefail package_output="$( ./scripts/ci/changed-test-packages.sh \ - list "$TEST_BASE_REF" "$TEST_HEAD_REF" + list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF" )" if [ -z "$package_output" ]; then - echo "No buildable Go package is affected by this revision." \ + echo "No buildable Go package in shard $TEST_SHARD is affected by this revision." \ >> "$GITHUB_STEP_SUMMARY" exit 0 fi - mapfile -t packages <<< "$package_output" - go test -v -race -count=1 -timeout=15m "${packages[@]}" + { + echo "packages<> "$GITHUB_OUTPUT" + + - name: Build + if: ${{ matrix.shard == 'remaining' && steps.select.outputs.packages != '' }} + run: make build + + - name: Install archive tooling + if: ${{ matrix.shard == 'release-scripts' && steps.select.outputs.packages != '' }} + run: sudo apt-get update && sudo apt-get install -y zip unzip + + - name: Test shard with Race Detection + if: ${{ steps.select.outputs.packages != '' }} + shell: bash + env: + DWS_PACKAGE_VERSION: 0.0.0-test + TEST_SHARD: ${{ matrix.shard }} + SHARD_PACKAGES: ${{ steps.select.outputs.packages }} + run: | + set -euo pipefail + mapfile -t packages <<< "$SHARD_PACKAGES" + test "${#packages[@]}" -gt 0 + if [ "$TEST_SHARD" = app ]; then + # A single long-lived app test process retains every constructed + # command tree in framework registries. Isolate Schema assembly and + # bounded name ranges so each process releases that state on exit. + test "${#packages[@]}" -eq 1 + ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" + exit 0 + fi + if [ "$TEST_SHARD" = release-scripts ]; then + # Mirror the dedicated release-contract job: these suites shell out + # to archive tooling and are not race-instrumented there. + go test -v -count=1 -timeout=10m "${packages[@]}" + exit 0 + fi + # cli/smoke own heavy NewRootCommand / Schema assembly under -race; + # give them a dedicated package timeout on slower hosted runners. + timeout_budget=12m + if [ "$TEST_SHARD" = cli ] || + [ "$TEST_SHARD" = smoke ]; then + timeout_budget=15m + fi + go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}" test-race: name: "Test (race: ${{ matrix.shard }})" @@ -715,7 +778,7 @@ jobs: failed=0 if [ "$CHANGELOG_ONLY" = true ] || [ "$DOCS_ONLY" = true ]; then for shard in \ - "changed packages:$FOCUSED_RESULT" \ + "focused shards:$FOCUSED_RESULT" \ "race shards:$RACE_RESULT" \ "release scripts:$RELEASE_SCRIPTS_RESULT" \ "cross-platform compile:$CROSS_PLATFORM_RESULT" \ @@ -744,7 +807,7 @@ jobs: release_expected=success fi for shard in \ - "changed packages:$FOCUSED_RESULT:$focused_expected" \ + "focused shards:$FOCUSED_RESULT:$focused_expected" \ "race shards:$RACE_RESULT:$race_expected" \ "release scripts:$RELEASE_SCRIPTS_RESULT:$release_expected" \ "cross-platform compile:$CROSS_PLATFORM_RESULT:success" diff --git a/scripts/ci/changed-test-packages.sh b/scripts/ci/changed-test-packages.sh index 3558b689..37d31e1c 100755 --- a/scripts/ci/changed-test-packages.sh +++ b/scripts/ci/changed-test-packages.sh @@ -7,16 +7,32 @@ set -eu ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)" usage() { - printf '%s\n' "usage: $0 BASE_REF HEAD_REF" >&2 + printf '%s\n' \ + "usage: $0 BASE_REF HEAD_REF" \ + " $0 list-shard SHARD BASE_REF HEAD_REF" >&2 exit 2 } -[ "${1:-}" = changed ] || [ "${1:-}" = list ] || usage -[ "$#" -eq 3 ] || usage - -MODE="$1" -BASE_REF="$2" -HEAD_REF="$3" +# list-shard narrows the impacted set to one test shard so focused CI runs can +# fan the same package plan across the shard matrix instead of testing every +# impacted package in a single long-lived job. +SHARD="" +case "${1:-}" in + changed|list) + [ "$#" -eq 3 ] || usage + MODE="$1" + BASE_REF="$2" + HEAD_REF="$3" + ;; + list-shard) + [ "$#" -eq 4 ] || usage + MODE="$1" + SHARD="$2" + BASE_REF="$3" + HEAD_REF="$4" + ;; + *) usage ;; +esac cd "$ROOT" git rev-parse --verify --quiet "${BASE_REF}^{commit}" >/dev/null || { @@ -116,9 +132,29 @@ while IFS= read -r file; do [ "$embedded_owner_found" = true ] || continue done < "$files" +# emit_selection prints the planned packages, restricted to SHARD when the +# caller asked for one. Restriction reuses scripts/ci/test-packages.sh as the +# single source of shard membership, which also means an unknown shard name +# aborts there instead of being reported as an empty selection: a silently empty +# shard would let a mistyped CI shard name skip every test and still succeed. +emit_selection() { + selection="$1" + if [ -z "$SHARD" ]; then + cat "$selection" + return 0 + fi + shard_packages="$workdir/shard-packages" + "$ROOT/scripts/ci/test-packages.sh" list "$SHARD" > "$shard_packages" + LC_ALL=C sort -u "$shard_packages" -o "$shard_packages" + LC_ALL=C sort -u "$selection" -o "$selection" + # An empty intersection is a normal outcome for a shard no change touched, so + # comm's silence must not be treated as an error. + LC_ALL=C comm -12 "$selection" "$shard_packages" +} + LC_ALL=C sort -u "$changed_packages" -o "$changed_packages" if [ "$MODE" = changed ] || [ ! -s "$changed_packages" ]; then - cat "$changed_packages" + emit_selection "$changed_packages" exit 0 fi @@ -133,4 +169,5 @@ while IFS= read -r package; do done < "$all_packages" > "$impacted_packages" cat "$changed_packages" >> "$impacted_packages" -LC_ALL=C sort -u "$impacted_packages" +LC_ALL=C sort -u "$impacted_packages" -o "$impacted_packages" +emit_selection "$impacted_packages" diff --git a/test/scripts/changed_test_packages_test.go b/test/scripts/changed_test_packages_test.go index 3f228c0a..f696e569 100644 --- a/test/scripts/changed_test_packages_test.go +++ b/test/scripts/changed_test_packages_test.go @@ -129,6 +129,245 @@ func Value() string { } } +// shardChangedPackagesShards mirrors the shard names scripts/ci/test-packages.sh +// asserts complete coverage for in its verify mode. Keeping the list here in +// full is deliberate: the union assertion below fails if a shard is added +// upstream without being selected, and an unknown-shard error fails if one is +// removed, so shard-plan drift cannot silently shrink focused-test coverage. +var shardChangedPackagesShards = []string{ + "app", + "generators", + "helpers", + "cli", + "smoke", + "remaining", + "release-scripts", +} + +func TestChangedTestPackagesShardSelectionCoversEveryImpactedPackageExactlyOnce(t *testing.T) { + repository := newShardChangedPackagesRepository(t) + baseRef := commitChangedTestPackagesFixture(t, repository, "initial shard fixture") + + writeChangedTestPackagesFixture(t, repository, "core/core.go", `package core + +func Value() string { + return "changed" +} +`) + headRef := commitChangedTestPackagesFixture(t, repository, "change core") + + impacted := runChangedTestPackages(t, repository, "list", baseRef, headRef) + if len(impacted) == 0 { + t.Fatal("shard fixture produced no impacted packages") + } + + owner := map[string]string{} + union := make([]string, 0, len(impacted)) + for _, shard := range shardChangedPackagesShards { + for _, pkg := range runChangedTestPackagesShard(t, repository, shard, baseRef, headRef) { + if previous, ok := owner[pkg]; ok { + t.Fatalf("package %q selected by both shard %q and %q", pkg, previous, shard) + } + owner[pkg] = shard + union = append(union, pkg) + } + } + + slices.Sort(union) + if !slices.Equal(union, impacted) { + t.Fatalf("shard selection union = %q, want every impacted package %q", union, impacted) + } +} + +func TestChangedTestPackagesShardSelectionFailsClosedOnUnknownShard(t *testing.T) { + repository := newShardChangedPackagesRepository(t) + baseRef := commitChangedTestPackagesFixture(t, repository, "initial shard fixture") + + writeChangedTestPackagesFixture(t, repository, "core/core.go", `package core + +func Value() string { + return "changed" +} +`) + headRef := commitChangedTestPackagesFixture(t, repository, "change core") + + script := filepath.Join(repository, "scripts", "ci", "changed-test-packages.sh") + command := exec.Command(script, "list-shard", "nonexistent", baseRef, headRef) + command.Dir = repository + output, err := command.CombinedOutput() + if err == nil { + t.Fatalf("unknown shard unexpectedly succeeded:\n%s", output) + } + // An unknown shard must abort rather than report an empty selection: a + // silently empty shard would let a mistyped CI shard name skip every test + // while still reporting success. + if !strings.Contains(string(output), "unknown test package shard") { + t.Fatalf("unknown shard failure = %q, want fail-closed diagnostic", output) + } + if strings.TrimSpace(string(output)) == "" { + t.Fatal("unknown shard produced empty output instead of a diagnostic") + } +} + +func TestChangedTestPackagesShardSelectionIsEmptyForUnaffectedShard(t *testing.T) { + repository := newShardChangedPackagesRepository(t) + baseRef := commitChangedTestPackagesFixture(t, repository, "initial shard fixture") + + writeChangedTestPackagesFixture(t, repository, "internal/helpers/helpers.go", `package helpers + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " helpers changed" +} +`) + headRef := commitChangedTestPackagesFixture(t, repository, "change helpers only") + + if selected := runChangedTestPackagesShard(t, repository, "helpers", baseRef, headRef); len(selected) == 0 { + t.Fatal("helpers shard selected nothing for a helpers-only change") + } + // An unaffected shard is a normal outcome and must exit zero with no + // output so the CI step can no-op instead of failing the job. + if selected := runChangedTestPackagesShard(t, repository, "app", baseRef, headRef); len(selected) != 0 { + t.Fatalf("app shard = %q, want empty for a helpers-only change", selected) + } +} + +func TestChangedTestPackagesShardSelectionRejectsMissingShardArgument(t *testing.T) { + repository := newShardChangedPackagesRepository(t) + baseRef := commitChangedTestPackagesFixture(t, repository, "initial shard fixture") + + script := filepath.Join(repository, "scripts", "ci", "changed-test-packages.sh") + command := exec.Command(script, "list-shard", baseRef, baseRef) + command.Dir = repository + output, err := command.CombinedOutput() + if err == nil { + t.Fatalf("list-shard without a shard argument unexpectedly succeeded:\n%s", output) + } + if !strings.Contains(string(output), "usage:") { + t.Fatalf("missing shard argument failure = %q, want usage diagnostic", output) + } +} + +func runChangedTestPackagesShard(t *testing.T, repository, shard, baseRef, headRef string) []string { + t.Helper() + + output := runChangedTestPackagesCommand( + t, + repository, + filepath.Join(repository, "scripts", "ci", "changed-test-packages.sh"), + "list-shard", + shard, + baseRef, + headRef, + ) + return strings.Fields(output) +} + +// newShardChangedPackagesRepository builds a fixture whose directory layout +// matches every shard scripts/ci/test-packages.sh knows about, so shard +// selection can be exercised without depending on the real repository's working +// tree state. Every package imports core, letting a single core edit mark the +// whole module impacted. +func newShardChangedPackagesRepository(t *testing.T) string { + t.Helper() + + repository := t.TempDir() + for path, contents := range map[string]string{ + "go.mod": `module example.com/shardfixture + +go 1.22 +`, + "core/core.go": `package core + +func Value() string { + return "core" +} +`, + "internal/app/app.go": `package app + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " app" +} +`, + "internal/generator/gen/gen.go": `package gen + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " gen" +} +`, + "internal/helpers/helpers.go": `package helpers + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " helpers" +} +`, + "internal/cli/cli.go": `package cli + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " cli" +} +`, + "test/smoke/smoke.go": `package smoke + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " smoke" +} +`, + "test/scripts/scripts.go": `package scripts + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " scripts" +} +`, + "pkg/extra/extra.go": `package extra + +import "example.com/shardfixture/core" + +func Value() string { + return core.Value() + " extra" +} +`, + } { + writeChangedTestPackagesFixture(t, repository, path, contents) + } + + projectRoot, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + t.Fatalf("resolve project root: %v", err) + } + for _, name := range []string{"changed-test-packages.sh", "test-packages.sh"} { + script, err := os.ReadFile(filepath.Join(projectRoot, "scripts", "ci", name)) + if err != nil { + t.Fatalf("read %s: %v", name, err) + } + scriptPath := filepath.Join(repository, "scripts", "ci", name) + if err := os.MkdirAll(filepath.Dir(scriptPath), 0o755); err != nil { + t.Fatalf("create script directory: %v", err) + } + if err := os.WriteFile(scriptPath, script, 0o755); err != nil { + t.Fatalf("copy %s: %v", name, err) + } + } + + runChangedTestPackagesCommand(t, repository, "git", "init", "-q", "-b", "main") + runChangedTestPackagesCommand(t, repository, "git", "config", "user.name", "DWS CI") + runChangedTestPackagesCommand(t, repository, "git", "config", "user.email", "dws-ci@example.invalid") + return repository +} + func newChangedTestPackagesRepository(t *testing.T) string { t.Helper() From 308e71c7833bc577e3efcf8ba002419715d66b6a Mon Sep 17 00:00:00 2001 From: chichuan Date: Sat, 15 Aug 2026 22:32:39 +0800 Subject: [PATCH 145/250] fix(ci): pass focused shard packages through a file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reading the package list with `mapfile < file` has unambiguous line semantics. Routing it through a step output and a here-string instead would append an extra empty array element if the value ever carried a trailing newline, and that element would reach go test as an empty package argument. The step output now carries only a single-line boolean, and the list travels through RUNNER_TEMP. An explicit empty-entry guard fails closed if the file is ever malformed. This job cannot execute on its own pull request — editing a workflow routes the revision to full_suite, which skips the focused path — so the implementation deliberately avoids depending on platform-specific trailing-newline behavior that local verification cannot observe. --- .github/workflows/ci.yml | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9d3fa1e3..ed9fe4f5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -577,33 +577,41 @@ jobs: if [ -z "$package_output" ]; then echo "No buildable Go package in shard $TEST_SHARD is affected by this revision." \ >> "$GITHUB_STEP_SUMMARY" + echo "affected=false" >> "$GITHUB_OUTPUT" exit 0 fi - { - echo "packages<> "$GITHUB_OUTPUT" + # The package list travels through a file rather than a step output: + # reading it with `mapfile < file` has unambiguous line semantics, + # whereas a here-string over a multi-line output would append an extra + # empty element if the value ever carried a trailing newline, and an + # empty element would reach go test as an empty package argument. + printf '%s\n' "$package_output" > "$RUNNER_TEMP/focused-shard-packages.txt" + echo "affected=true" >> "$GITHUB_OUTPUT" - name: Build - if: ${{ matrix.shard == 'remaining' && steps.select.outputs.packages != '' }} + if: ${{ matrix.shard == 'remaining' && steps.select.outputs.affected == 'true' }} run: make build - name: Install archive tooling - if: ${{ matrix.shard == 'release-scripts' && steps.select.outputs.packages != '' }} + if: ${{ matrix.shard == 'release-scripts' && steps.select.outputs.affected == 'true' }} run: sudo apt-get update && sudo apt-get install -y zip unzip - name: Test shard with Race Detection - if: ${{ steps.select.outputs.packages != '' }} + if: ${{ steps.select.outputs.affected == 'true' }} shell: bash env: DWS_PACKAGE_VERSION: 0.0.0-test TEST_SHARD: ${{ matrix.shard }} - SHARD_PACKAGES: ${{ steps.select.outputs.packages }} run: | set -euo pipefail - mapfile -t packages <<< "$SHARD_PACKAGES" + mapfile -t packages < "$RUNNER_TEMP/focused-shard-packages.txt" test "${#packages[@]}" -gt 0 + for package in "${packages[@]}"; do + test -n "$package" || { + echo "shard package list contains an empty entry" >&2 + exit 1 + } + done if [ "$TEST_SHARD" = app ]; then # A single long-lived app test process retains every constructed # command tree in framework registries. Isolate Schema assembly and From c4f2ab631b4965674dbfee03e891ee00db4e8cd6 Mon Sep 17 00:00:00 2001 From: chichuan Date: Sat, 15 Aug 2026 22:58:30 +0800 Subject: [PATCH 146/250] fix(ci): assert the focused path's shard shape in the workflow contract The workflow contract pinned the focused path by literal: the job name `Test (changed packages)`, the unsharded `list "$TEST_BASE_REF" "$TEST_HEAD_REF"` call, and a single `go test -timeout=15m` line standing in for internal/app's package-level headroom. Sharding the job changed all three literals, so `Test (workflow and release contracts)` failed on this branch even though every shard selection test passed. Each invariant the contract guarded still holds, so the assertions are updated to the new shape rather than relaxed: - the focused job must still exist, now as the matrix job, named the way the contract already names `Test (race: ${{ matrix.shard }})`; - package selection must still derive from the authoritative synthetic merge base/head, now with an explicit shard argument, so pointing it at any other ref still fails the contract; - internal/app's headroom is asserted through the process-isolating helper and the per-shard budgets, mirroring the assertions already applied to test-race. That is stronger than the old single -timeout: it pins the mechanism that keeps the suite inside its budget rather than the number alone. release-scripts membership is asserted too, because its dedicated job only runs at full-suite or release-sensitive scope, so losing it here would silently stop testing test/scripts changes. The shard comparisons in the focused job are quoted so that job reads verbatim like test-race's. Ablating the implementation one change at a time turns the contract red in all five cases: removing the app helper call, dropping release-scripts from the matrix, selecting from HEAD~1, collapsing the matrix back to a single unsharded job, and dropping the cli/smoke timeout budget. --- .github/workflows/ci.yml | 8 +++---- test/scripts/changelog_pr_gate_test.go | 30 ++++++++++++++++++++++---- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed9fe4f5..a4d30325 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -612,7 +612,7 @@ jobs: exit 1 } done - if [ "$TEST_SHARD" = app ]; then + if [ "$TEST_SHARD" = "app" ]; then # A single long-lived app test process retains every constructed # command tree in framework registries. Isolate Schema assembly and # bounded name ranges so each process releases that state on exit. @@ -620,7 +620,7 @@ jobs: ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" exit 0 fi - if [ "$TEST_SHARD" = release-scripts ]; then + if [ "$TEST_SHARD" = "release-scripts" ]; then # Mirror the dedicated release-contract job: these suites shell out # to archive tooling and are not race-instrumented there. go test -v -count=1 -timeout=10m "${packages[@]}" @@ -629,8 +629,8 @@ jobs: # cli/smoke own heavy NewRootCommand / Schema assembly under -race; # give them a dedicated package timeout on slower hosted runners. timeout_budget=12m - if [ "$TEST_SHARD" = cli ] || - [ "$TEST_SHARD" = smoke ]; then + if [ "$TEST_SHARD" = "cli" ] || + [ "$TEST_SHARD" = "smoke" ]; then timeout_budget=15m fi go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}" diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index 8f6be15a..849d9191 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -1151,13 +1151,13 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { "filename.startsWith('pkg/cmdutil/')", "filename === 'skills_embed.go'", "filename.startsWith('test/mock_mcp/')", - "name: Test (changed packages)", + `name: "Test (focused: ${{ matrix.shard }})"`, "changed-test-packages.sh", "Verify authoritative synthetic merge", `test "$(git rev-parse HEAD^1)" = "$PR_BASE_SHA"`, `test "$(git rev-parse HEAD^2)" = "$PR_HEAD_SHA"`, `echo "TEST_HEAD_REF=$(git rev-parse HEAD)"`, - "list \"$TEST_BASE_REF\" \"$TEST_HEAD_REF\"", + `list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF"`, "needs.lint.outputs.full_suite != 'true'", `name: "Test (race: ${{ matrix.shard }})"`, "name: Test (workflow and release contracts)", @@ -1217,8 +1217,30 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { if !strings.Contains(focusedJob, "timeout-minutes: 20") { t.Error("focused test job must allow the scoped race suite up to 20 minutes") } - if !strings.Contains(focusedJob, `go test -v -race -count=1 -timeout=15m "${packages[@]}"`) { - t.Error("focused race tests must retain enough package-level time for internal/app") + // The focused path fans the impacted set across the same shards as test-race + // and runs each shard the way test-race runs it, so no single job carries + // internal/app together with its reverse dependencies. internal/app keeps its + // package-level headroom through the process-isolating helper instead of one + // long -timeout, which is strictly stronger: every process releases the + // framework registries it populated. release-scripts is asserted because its + // dedicated job only runs at full-suite or release-sensitive scope, so losing + // it here would silently stop testing test/scripts changes. + for _, want := range []string{ + `if [ "$TEST_SHARD" = "app" ]; then`, + `test "${#packages[@]}" -eq 1`, + `./scripts/ci/run-app-race-tests.sh run "${packages[0]}"`, + `if [ "$TEST_SHARD" = "release-scripts" ]; then`, + `go test -v -count=1 -timeout=10m "${packages[@]}"`, + "timeout_budget=12m", + `if [ "$TEST_SHARD" = "cli" ] ||`, + `[ "$TEST_SHARD" = "smoke" ]; then`, + "timeout_budget=15m", + `go test -v -race -count=1 -timeout="$timeout_budget" "${packages[@]}"`, + "- release-scripts", + } { + if !strings.Contains(focusedJob, want) { + t.Errorf("focused test job missing shard contract %q", want) + } } raceStart := focusedEnd From 4a33e7e893bb838000c3bbba95fbe036222f5643 Mon Sep 17 00:00:00 2001 From: chichuan Date: Sun, 16 Aug 2026 22:17:14 +0800 Subject: [PATCH 147/250] fix(ci): drop race instrumentation from the app schema partition The schema partition's 52 tests assert structural Schema-to-Cobra contracts over a single goroutine: none of them call t.Parallel or start a goroutine, so the race detector has no concurrent access to observe there. The process-global lazy metadata that does need race coverage (schema_source_root's atomic.Value, the parameter-binding lazy loaders) is exercised by internal/cli's concurrent tests, which stay instrumented. The instrumentation was not free here. The partition shares a single sync.Once Catalog build whose work is allocation-heavy, and -race made it roughly 11x slower: 26s -> 291s locally, and 357s of the app shard's 780s in CI. Within that partition TestFinalSchemaToolsHaveExecutableBaseCommands alone accounted for 262s, not because the test is expensive but because it is the first caller to pay for the shared snapshot; its 1121 subtests together measure 0.00s. run_partition now takes the instrumentation mode explicitly and fails closed on an unrecognized value, so a typo cannot silently drop -race from a partition that is supposed to carry it. --- scripts/ci/run-app-race-tests.sh | 49 +++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 13 deletions(-) diff --git a/scripts/ci/run-app-race-tests.sh b/scripts/ci/run-app-race-tests.sh index 9922e9ab..cdfbe017 100755 --- a/scripts/ci/run-app-race-tests.sh +++ b/scripts/ci/run-app-race-tests.sh @@ -101,26 +101,49 @@ fi run_partition() { name="$1" - run_pattern="$2" - skip_pattern="${3:-}" + instrumentation="$2" + run_pattern="$3" + skip_pattern="${4:-}" - printf 'running internal/app race partition %s\n' "$name" + # Fail closed on an unrecognized mode: a typo must not silently drop race + # instrumentation from a partition that is supposed to carry it. + case "$instrumentation" in + race|no-race) ;; + *) + printf 'unknown instrumentation %s for app partition %s\n' \ + "$instrumentation" "$name" >&2 + exit 1 + ;; + esac + + printf 'running internal/app %s partition %s\n' "$instrumentation" "$name" + set -- -v -count=1 -timeout=15m -run "$run_pattern" if [ -n "$skip_pattern" ]; then - go test -v -race -count=1 -timeout=15m \ - -run "$run_pattern" -skip "$skip_pattern" "$app_package" - else - go test -v -race -count=1 -timeout=15m \ - -run "$run_pattern" "$app_package" + set -- "$@" -skip "$skip_pattern" fi + if [ "$instrumentation" = race ]; then + set -- -race "$@" + fi + go test "$@" "$app_package" } # Schema assembly has the largest transient memory footprint. Run those tests # in a fresh process, then keep each remaining name range in its own process so # command trees retained by process-global registries are released between # partitions. The complementary run/skip patterns preserve the full test set. +# +# The schema partition runs uninstrumented. Its tests assert structural +# Schema-to-Cobra contracts over a single goroutine: none of them call +# t.Parallel or start a goroutine, so the race detector has no concurrent access +# to observe here. The process-global lazy metadata that does need race coverage +# (schema_source_root's atomic.Value, the parameter-binding lazy loaders) is +# exercised by internal/cli's concurrent tests, which stay instrumented. The +# instrumentation is not free on this partition: its shared sync.Once Catalog +# build is allocation-heavy, and -race made the partition roughly 11x slower +# (26s -> 291s locally, 357s in CI) without being able to report anything. schema_pattern='^Test.*Schema' -run_partition schema "$schema_pattern" -run_partition a-b '^Test[A-B]' "$schema_pattern" -run_partition c '^TestC' "$schema_pattern" -run_partition d-r '^Test[D-R]' "$schema_pattern" -run_partition s-z-example-fuzz '^(Test[S-Z]|Example|Fuzz)' "$schema_pattern" +run_partition schema no-race "$schema_pattern" +run_partition a-b race '^Test[A-B]' "$schema_pattern" +run_partition c race '^TestC' "$schema_pattern" +run_partition d-r race '^Test[D-R]' "$schema_pattern" +run_partition s-z-example-fuzz race '^(Test[S-Z]|Example|Fuzz)' "$schema_pattern" From bfd0976b31897c63509853f8494f4cb9034db31d Mon Sep 17 00:00:00 2001 From: chichuan Date: Sun, 16 Aug 2026 22:18:04 +0800 Subject: [PATCH 148/250] fix(ci): run the app test partitions as parallel shards The five internal/app partitions ran end to end inside one job, so the app shard's wall clock was the sum of all five: 780s in CI, of which the schema partition owned 357s. Each partition is now its own matrix shard, so they run concurrently and the shard's wall clock is set by its slowest partition rather than by their total. Every partition shard still selects the same single internal/app package, so the impacted-package query maps the shard name back to app and the partition only chooses which tests run. The helper gains a partition argument and a list-partitions mode. APP_PARTITIONS is the single source of truth for the set, and the discovery pass still runs in every job, so each one independently verifies that the partition patterns cover every top-level test exactly once before running the one it was asked for. Two fail-closed checks guard the split, because the helper's own coverage check can no longer prove the whole package ran once the partitions are separate jobs: - The helper cross-checks APP_PARTITIONS against the coverage counters in both directions, so a counted partition that nothing dispatches and a dispatchable partition with no counter both fail instead of silently skipping tests. - TestCIAppRacePartitionMatrixMatchesHelper pins the workflow's app- shards to list-partitions output in both directions, so a partition cannot lose its job while every job stays green. The discovery loop variable is renamed from partition to spec: it would otherwise shadow the partition requested on the command line, which run mode reads after the discovery pass completes. --- .github/workflows/ci.yml | 85 +++++++++++++++----- scripts/ci/run-app-race-tests.sh | 97 ++++++++++++++++++++--- test/scripts/changelog_pr_gate_test.go | 36 +++++---- test/scripts/ci_test_package_plan_test.go | 68 ++++++++++++++++ 4 files changed, 236 insertions(+), 50 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a4d30325..dc437165 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -523,12 +523,22 @@ jobs: # shards at full-suite scope; release-scripts is included because its # dedicated job only runs at full-suite or release-sensitive scope, and # dropping it here would stop testing test/scripts changes entirely. + # internal/app is carried by one shard per bounded partition rather than a + # single app shard: the partitions used to run end to end inside one job, + # where the Schema partition alone owned most of the wall clock. The + # app- names are pinned to the helper's partition set by + # TestCIAppRacePartitionMatrixMatchesHelper, so a partition can never lose + # its job silently. timeout-minutes: 20 strategy: fail-fast: false matrix: shard: - - app + - app-schema + - app-a-b + - app-c + - app-d-r + - app-s-z-example-fuzz - generators - helpers - cli @@ -570,9 +580,16 @@ jobs: TEST_SHARD: ${{ matrix.shard }} run: | set -euo pipefail + # Every app partition shard tests the same single internal/app + # package, so the impacted-package query uses the base shard name and + # the partition only selects which tests run. + package_shard="$TEST_SHARD" + case "$TEST_SHARD" in + app-*) package_shard=app ;; + esac package_output="$( ./scripts/ci/changed-test-packages.sh \ - list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF" + list-shard "$package_shard" "$TEST_BASE_REF" "$TEST_HEAD_REF" )" if [ -z "$package_output" ]; then echo "No buildable Go package in shard $TEST_SHARD is affected by this revision." \ @@ -612,14 +629,19 @@ jobs: exit 1 } done - if [ "$TEST_SHARD" = "app" ]; then - # A single long-lived app test process retains every constructed - # command tree in framework registries. Isolate Schema assembly and - # bounded name ranges so each process releases that state on exit. - test "${#packages[@]}" -eq 1 - ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" - exit 0 - fi + case "$TEST_SHARD" in + app-*) + # A single long-lived app test process retains every constructed + # command tree in framework registries. Each partition is its own + # job, so that state is released when the process exits and the + # partitions run concurrently instead of end to end. The helper + # still verifies that the partition patterns cover every top-level + # test exactly once before running the one it was asked for. + test "${#packages[@]}" -eq 1 + ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}" + exit 0 + ;; + esac if [ "$TEST_SHARD" = "release-scripts" ]; then # Mirror the dedicated release-contract job: these suites shell out # to archive tooling and are not race-instrumented there. @@ -640,14 +662,21 @@ jobs: needs: lint if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true' }} runs-on: ubuntu-latest - # app runs several independently bounded processes; cli/smoke need headroom - # beyond go test -timeout for setup + assembly. + # internal/app is split across one shard per bounded partition so the + # partitions run concurrently and each releases its framework registries + # when the process exits; cli/smoke need headroom beyond go test -timeout for + # setup + assembly. The app- names are pinned to the helper's + # partition set by TestCIAppRacePartitionMatrixMatchesHelper. timeout-minutes: 20 strategy: fail-fast: false matrix: shard: - - app + - app-schema + - app-a-b + - app-c + - app-d-r + - app-s-z-example-fuzz - generators - helpers - cli @@ -673,18 +702,30 @@ jobs: TEST_SHARD: ${{ matrix.shard }} run: | set -euo pipefail - package_output="$(./scripts/ci/test-packages.sh list "$TEST_SHARD")" + # Every app partition shard tests the same single internal/app + # package, so the package query uses the base shard name and the + # partition only selects which tests run. + package_shard="$TEST_SHARD" + case "$TEST_SHARD" in + app-*) package_shard=app ;; + esac + package_output="$(./scripts/ci/test-packages.sh list "$package_shard")" test -n "$package_output" mapfile -t packages <<< "$package_output" test "${#packages[@]}" -gt 0 - if [ "$TEST_SHARD" = "app" ]; then - # A single long-lived app test process retains every constructed - # command tree in framework registries. Isolate Schema assembly and - # bounded name ranges so each process releases that state on exit. - test "${#packages[@]}" -eq 1 - ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" - exit 0 - fi + case "$TEST_SHARD" in + app-*) + # A single long-lived app test process retains every constructed + # command tree in framework registries. Each partition is its own + # job, so that state is released when the process exits and the + # partitions run concurrently instead of end to end. The helper + # still verifies that the partition patterns cover every top-level + # test exactly once before running the one it was asked for. + test "${#packages[@]}" -eq 1 + ./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}" + exit 0 + ;; + esac # cli/smoke own heavy NewRootCommand / Schema assembly under -race; # give them a dedicated package timeout on slower hosted runners. timeout_budget=12m diff --git a/scripts/ci/run-app-race-tests.sh b/scripts/ci/run-app-race-tests.sh index cdfbe017..3f586dd0 100755 --- a/scripts/ci/run-app-race-tests.sh +++ b/scripts/ci/run-app-race-tests.sh @@ -6,16 +6,35 @@ ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)" usage() { printf '%s\n' \ "usage: $0 verify " \ - " $0 run " >&2 + " $0 run [partition]" \ + " $0 list-partitions" >&2 exit 2 } -[ "$#" -eq 2 ] || usage -mode="$1" -app_package="$2" +# Single source of truth for the partition set. CI runs one job per partition and +# pins its shard names to this list, so a name that appears here without a +# dispatch entry below fails closed rather than silently skipping tests. +APP_PARTITIONS='schema a-b c d-r s-z-example-fuzz' +mode="${1:-}" +partition="" case "$mode" in - verify|run) ;; + list-partitions) + [ "$#" -eq 1 ] || usage + for name in $APP_PARTITIONS; do + printf '%s\n' "$name" + done + exit 0 + ;; + verify) + [ "$#" -eq 2 ] || usage + app_package="$2" + ;; + run) + [ "$#" -eq 2 ] || [ "$#" -eq 3 ] || usage + app_package="$2" + partition="${3:-}" + ;; *) usage ;; esac @@ -70,21 +89,49 @@ if [ "$unmatched_count" -ne 0 ]; then exit 1 fi -for partition in \ +# The loop variable is deliberately not named "partition": that name holds the +# partition requested on the command line, and run mode still executes this +# discovery pass before dispatching. +classified='' +for spec in \ "schema:$schema_count" \ "a-b:$ab_count" \ "c:$c_count" \ "d-r:$dr_count" \ "s-z-example-fuzz:$sz_count" do - name="${partition%%:*}" - count="${partition#*:}" + name="${spec%%:*}" + count="${spec#*:}" + classified="$classified $name" if [ "$count" -eq 0 ]; then printf 'app race partition %s is empty\n' "$name" >&2 exit 1 fi done +# The counters above and APP_PARTITIONS must describe the same set in both +# directions. A counted partition missing from APP_PARTITIONS would never be +# dispatched by any CI job, and a dispatchable partition with no counter would +# escape the exact-coverage check above. +for name in $APP_PARTITIONS; do + case " $classified " in + *" $name "*) ;; + *) + printf 'app partition %s has no coverage counter\n' "$name" >&2 + exit 1 + ;; + esac +done +for name in $classified; do + case " $APP_PARTITIONS " in + *" $name "*) ;; + *) + printf 'counted partition %s is not a dispatchable app partition\n' "$name" >&2 + exit 1 + ;; + esac +done + total_count="$(wc -l < "$tests" | tr -d ' ')" assigned_count=$((schema_count + ab_count + c_count + dr_count + sz_count)) if [ "$assigned_count" -ne "$total_count" ]; then @@ -142,8 +189,32 @@ run_partition() { # build is allocation-heavy, and -race made the partition roughly 11x slower # (26s -> 291s locally, 357s in CI) without being able to report anything. schema_pattern='^Test.*Schema' -run_partition schema no-race "$schema_pattern" -run_partition a-b race '^Test[A-B]' "$schema_pattern" -run_partition c race '^TestC' "$schema_pattern" -run_partition d-r race '^Test[D-R]' "$schema_pattern" -run_partition s-z-example-fuzz race '^(Test[S-Z]|Example|Fuzz)' "$schema_pattern" + +# Dispatch table for the partition set declared in APP_PARTITIONS. CI passes one +# partition per job so they run concurrently; running without a partition keeps +# the original end-to-end behaviour for local use and for any caller that wants +# the whole package in one invocation. +run_named_partition() { + case "$1" in + schema) run_partition schema no-race "$schema_pattern" ;; + a-b) run_partition a-b race '^Test[A-B]' "$schema_pattern" ;; + c) run_partition c race '^TestC' "$schema_pattern" ;; + d-r) run_partition d-r race '^Test[D-R]' "$schema_pattern" ;; + s-z-example-fuzz) + run_partition s-z-example-fuzz race '^(Test[S-Z]|Example|Fuzz)' "$schema_pattern" + ;; + *) + printf 'unknown app partition: %s\n' "$1" >&2 + exit 1 + ;; + esac +} + +if [ -n "$partition" ]; then + run_named_partition "$partition" + exit 0 +fi + +for name in $APP_PARTITIONS; do + run_named_partition "$name" +done diff --git a/test/scripts/changelog_pr_gate_test.go b/test/scripts/changelog_pr_gate_test.go index 849d9191..5d8ef72b 100644 --- a/test/scripts/changelog_pr_gate_test.go +++ b/test/scripts/changelog_pr_gate_test.go @@ -1157,7 +1157,7 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { `test "$(git rev-parse HEAD^1)" = "$PR_BASE_SHA"`, `test "$(git rev-parse HEAD^2)" = "$PR_HEAD_SHA"`, `echo "TEST_HEAD_REF=$(git rev-parse HEAD)"`, - `list-shard "$TEST_SHARD" "$TEST_BASE_REF" "$TEST_HEAD_REF"`, + `list-shard "$package_shard" "$TEST_BASE_REF" "$TEST_HEAD_REF"`, "needs.lint.outputs.full_suite != 'true'", `name: "Test (race: ${{ matrix.shard }})"`, "name: Test (workflow and release contracts)", @@ -1219,16 +1219,20 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { } // The focused path fans the impacted set across the same shards as test-race // and runs each shard the way test-race runs it, so no single job carries - // internal/app together with its reverse dependencies. internal/app keeps its - // package-level headroom through the process-isolating helper instead of one - // long -timeout, which is strictly stronger: every process releases the - // framework registries it populated. release-scripts is asserted because its - // dedicated job only runs at full-suite or release-sensitive scope, so losing - // it here would silently stop testing test/scripts changes. + // internal/app together with its reverse dependencies. internal/app is split + // further into one shard per bounded partition, which keeps its package-level + // headroom through the process-isolating helper instead of one long -timeout + // and is strictly stronger than a single app job: every partition process + // releases the framework registries it populated, and the partitions run + // concurrently rather than end to end. Each partition shard still selects the + // same single internal/app package, so the impacted-package query maps the + // shard name back to app. release-scripts is asserted because its dedicated + // job only runs at full-suite or release-sensitive scope, so losing it here + // would silently stop testing test/scripts changes. for _, want := range []string{ - `if [ "$TEST_SHARD" = "app" ]; then`, + `app-*) package_shard=app ;;`, `test "${#packages[@]}" -eq 1`, - `./scripts/ci/run-app-race-tests.sh run "${packages[0]}"`, + `./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}"`, `if [ "$TEST_SHARD" = "release-scripts" ]; then`, `go test -v -count=1 -timeout=10m "${packages[@]}"`, "timeout_budget=12m", @@ -1249,14 +1253,16 @@ func TestChangelogPRFastPathWorkflowContract(t *testing.T) { t.Fatal("Code Admission workflow missing race test job boundaries") } raceJob := admission[raceStart:raceEnd] - // The app shard uses independently bounded test processes so process-global - // command registries are released before the Schema assembly peak. Other full - // race shards retain the dynamic package timeout: default/floor 12m, with - // cli/smoke raised to 15m on slower hosted runners. + // internal/app is carried by one shard per bounded partition, so process-global + // command registries are released with each partition process and the Schema + // assembly peak no longer sits in front of the other partitions. Each + // partition shard resolves back to the same single internal/app package. + // Other full race shards retain the dynamic package timeout: default/floor + // 12m, with cli/smoke raised to 15m on slower hosted runners. for _, want := range []string{ - `if [ "$TEST_SHARD" = "app" ]; then`, + `app-*) package_shard=app ;;`, `test "${#packages[@]}" -eq 1`, - `./scripts/ci/run-app-race-tests.sh run "${packages[0]}"`, + `./scripts/ci/run-app-race-tests.sh run "${packages[0]}" "${TEST_SHARD#app-}"`, "timeout_budget=12m", `if [ "$TEST_SHARD" = "cli" ] ||`, `[ "$TEST_SHARD" = "smoke" ]; then`, diff --git a/test/scripts/ci_test_package_plan_test.go b/test/scripts/ci_test_package_plan_test.go index 0d7944f2..b8250c19 100644 --- a/test/scripts/ci_test_package_plan_test.go +++ b/test/scripts/ci_test_package_plan_test.go @@ -99,6 +99,74 @@ func TestCIAppRacePartitionsCoverTopLevelTestsExactlyOnce(t *testing.T) { } } +// TestCIAppRacePartitionMatrixMatchesHelper pins the workflow's app partition +// shards to the partition set the helper actually runs. The partitions are +// separate CI jobs now, so the helper's own "covered exactly once" check can no +// longer prove the whole package ran: a partition the helper knows about but no +// matrix shard dispatches would silently stop running while every job stays +// green. Both directions are asserted so a stale matrix shard fails too. +func TestCIAppRacePartitionMatrixMatchesHelper(t *testing.T) { + root := testPackagePlanRoot(t) + script := filepath.Join(root, "scripts", "ci", "run-app-race-tests.sh") + cmd := exec.Command("sh", script, "list-partitions") + cmd.Dir = root + output, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("%s list-partitions failed: %v\n%s", script, err, output) + } + partitions := strings.Fields(string(output)) + if len(partitions) == 0 { + t.Fatalf("list-partitions returned no partitions: %q", output) + } + + workflow, err := os.ReadFile(filepath.Join(root, ".github", "workflows", "ci.yml")) + if err != nil { + t.Fatalf("read ci.yml: %v", err) + } + admission := string(workflow) + + for _, job := range []struct { + name string + startMark string + endMark string + }{ + {"test-focused", "\n test-focused:\n", "\n test-race:\n"}, + {"test-race", "\n test-race:\n", "\n test-release-scripts:\n"}, + } { + start := strings.Index(admission, job.startMark) + end := strings.Index(admission, job.endMark) + if start < 0 || end <= start { + t.Fatalf("ci.yml is missing %s job boundaries", job.name) + } + body := admission[start:end] + + for _, partition := range partitions { + want := "- app-" + partition + if !strings.Contains(body, want) { + t.Errorf("%s matrix is missing shard %q for a partition the helper runs", job.name, want) + } + } + + for _, line := range strings.Split(body, "\n") { + shard := strings.TrimSpace(line) + if !strings.HasPrefix(shard, "- app-") { + continue + } + name := strings.TrimPrefix(shard, "- app-") + matched := false + for _, partition := range partitions { + if partition == name { + matched = true + break + } + } + if !matched { + t.Errorf("%s matrix shard %q has no matching helper partition", job.name, shard) + } + } + } +} + func TestCITestPackagePlanFailsClosedWhenGoListFails(t *testing.T) { root := testPackagePlanRoot(t) fakeBin := t.TempDir() From 55d94d3b58bfbf8f6145be59de409a6ab76cfa00 Mon Sep 17 00:00:00 2001 From: chichuan Date: Sun, 16 Aug 2026 22:21:16 +0800 Subject: [PATCH 149/250] perf: skip redundant JSON validation when projecting typed Schema values typedJSONValue marshaled a typed value and then routed the result through rawJSONValue, which runs json.Valid before decoding. On that path the input is whatever json.Marshal has just produced, so the validation scan can only ever succeed: it re-read every marshaled document for nothing. The decode step is now shared by both entry points. rawJSONValue keeps its json.Valid check, because it still accepts untrusted input, while typedJSONValue decodes what it marshaled directly. Across the 1121-tool set this removes about a third of the Schema Catalog projection work: the internal/app schema suite goes from 26.0s to 17.2s uninstrumented, and from 291.1s to 241.0s under -race. The delivered Catalog is byte-for-byte unchanged. check-generated-drift, check-schema-catalog and check-schema-binary each regenerate the same source_hash sha256:93b8d44eb163bd2898c78397d22af92d378e3dc4e20f56b33277b51e4342e2e6, and the two error contracts are preserved: typedJSONValue still rejects a value json.Marshal cannot encode, and rawJSONValue still rejects invalid JSON. --- .changes/schema-catalog-json-projection.md | 8 ++++++++ internal/cli/schema_contract_model.go | 20 ++++++++++++++++++-- 2 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 .changes/schema-catalog-json-projection.md diff --git a/.changes/schema-catalog-json-projection.md b/.changes/schema-catalog-json-projection.md new file mode 100644 index 00000000..21a5b1a6 --- /dev/null +++ b/.changes/schema-catalog-json-projection.md @@ -0,0 +1,8 @@ +--- +category: Changed +--- + +- **Faster Schema Catalog assembly** — projects typed values into payload JSON + without re-running a validation scan over documents `json.Marshal` has just + produced, cutting roughly a third of the projection work across the full tool + set. Untrusted JSON input keeps its existing validation. diff --git a/internal/cli/schema_contract_model.go b/internal/cli/schema_contract_model.go index 204b3761..e4d0e568 100644 --- a/internal/cli/schema_contract_model.go +++ b/internal/cli/schema_contract_model.go @@ -1127,21 +1127,37 @@ func putRawJSON(payload map[string]any, key string, raw json.RawMessage) error { return nil } +// rawJSONValue decodes a JSON value that may come from an untrusted source, so +// it validates before decoding. Callers holding output that json.Marshal just +// produced should use typedJSONValue instead of paying the validation scan. func rawJSONValue(raw json.RawMessage) (any, error) { if !json.Valid(raw) { return nil, fmt.Errorf("invalid JSON value") } + return decodeValidJSONValue(raw), nil +} + +// decodeValidJSONValue decodes JSON whose validity the caller has already +// established, either by json.Valid or by having just marshaled it. Decode +// errors are unreachable under that precondition and are therefore discarded, +// exactly as this path behaved when the decode was inlined into rawJSONValue. +func decodeValidJSONValue(raw json.RawMessage) any { decoder := json.NewDecoder(bytes.NewReader(raw)) decoder.UseNumber() var value any _ = decoder.Decode(&value) - return value, nil + return value } +// typedJSONValue projects a typed value into the generic JSON shape the payload +// renderers consume. json.Marshal output is valid by construction, so this path +// decodes it directly: routing through rawJSONValue re-scanned every marshaled +// document with json.Valid, which measured ~34% of Schema Catalog assembly time +// across the 1121-tool set (26.0s -> 17.2s for the internal/app schema suite). func typedJSONValue(value any) (any, error) { data, err := json.Marshal(value) if err != nil { return nil, err } - return rawJSONValue(data) + return decodeValidJSONValue(data), nil } From 353454abb28a0ed778ec709b3b6ab559328a316e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Mon, 17 Aug 2026 10:32:04 +0800 Subject: [PATCH 150/250] fix(event): verify bus owner before fallback stop --- internal/event/bus/lockfile.go | 41 ++++++++++++++++ internal/event/bus/lockfile_test.go | 51 ++++++++++++++++++++ internal/event/busctl/coverage_edges_test.go | 3 ++ internal/event/busctl/stop.go | 26 +++++++--- internal/event/busctl/stop_test.go | 37 ++++++++++++++ 5 files changed, 152 insertions(+), 6 deletions(-) diff --git a/internal/event/bus/lockfile.go b/internal/event/bus/lockfile.go index 0349a8c9..40dbaaee 100644 --- a/internal/event/bus/lockfile.go +++ b/internal/event/bus/lockfile.go @@ -114,6 +114,47 @@ func ReadHolderPID(path string) int { return parsePID(b) } +// ValidateHolderOwnership reports whether pid still owns the exclusive lock at +// path. If the lock can be acquired, no daemon owns it: the PID payload is +// stale and is cleared while the probe holds the lock. The PID is read again +// after a busy result so a daemon replacement cannot be mistaken for the +// original owner. +// +// Callers use this immediately before sending a process-level termination +// fallback. A live PID by itself is not proof of ownership because operating +// systems may reuse PIDs after an unclean daemon exit. +func ValidateHolderOwnership(path string, pid int) (bool, error) { + if pid <= 0 || ReadHolderPID(path) != pid { + return false, nil + } + + probe, err := busTryAcquire(path) + if err != nil { + if errors.Is(err, ErrBusy) { + return ReadHolderPID(path) == pid, nil + } + return false, fmt.Errorf("bus: verify lock owner: %w", err) + } + defer probe.Close() + + // We own the lock, so the recorded PID cannot own it. Clear only the PID + // we validated above; a changed payload is left untouched defensively. + f := probe.File() + if _, err := busSeek(f, 0, io.SeekStart); err != nil { + return false, fmt.Errorf("bus: seek stale lock: %w", err) + } + current, err := busReadAll(f) + if err != nil { + return false, fmt.Errorf("bus: read stale lock: %w", err) + } + if parsePID(current) == pid { + if err := truncateAndWritePID(f, 0); err != nil { + return false, fmt.Errorf("bus: clear stale PID: %w", err) + } + } + return false, nil +} + // Close releases the flock and best-effort blanks the PID body so a stale // reader (e.g. `event status` racing our shutdown) does not see our // long-dead PID and try to signal it. The lock file itself is NOT removed diff --git a/internal/event/bus/lockfile_test.go b/internal/event/bus/lockfile_test.go index 6ec4e86d..d36e7e8a 100644 --- a/internal/event/bus/lockfile_test.go +++ b/internal/event/bus/lockfile_test.go @@ -112,6 +112,57 @@ func TestReadHolderPID_MalformedReturnsZero(t *testing.T) { } } +func TestCrossPlatformCoverageValidateHolderOwnershipHeldLock(t *testing.T) { + path := filepath.Join(t.TempDir(), LockFileName) + held, err := busTryAcquire(path) + if err != nil { + t.Fatalf("hold lock: %v", err) + } + defer held.Close() + if err := truncateAndWritePID(held.File(), os.Getpid()); err != nil { + t.Fatalf("write holder PID: %v", err) + } + + owned, err := ValidateHolderOwnership(path, os.Getpid()) + if err != nil { + t.Fatalf("ValidateHolderOwnership: %v", err) + } + if !owned { + t.Fatal("held lock was not attributed to its recorded PID") + } +} + +func TestCrossPlatformCoverageValidateHolderOwnershipClearsReusedPID(t *testing.T) { + path := filepath.Join(t.TempDir(), LockFileName) + // The current PID is alive but deliberately does not hold this lock. This + // models a stale daemon PID that the OS has reassigned to another process. + if err := os.WriteFile(path, []byte(fmt.Sprintf("%d\n", os.Getpid())), 0o600); err != nil { + t.Fatalf("write stale PID: %v", err) + } + + owned, err := ValidateHolderOwnership(path, os.Getpid()) + if err != nil { + t.Fatalf("ValidateHolderOwnership: %v", err) + } + if owned { + t.Fatal("live reused PID without the bus lock was accepted as owner") + } + if got := ReadHolderPID(path); got != 0 { + t.Fatalf("stale PID after validation = %d, want cleared", got) + } +} + +func TestCrossPlatformCoverageValidateHolderOwnershipRejectsMismatch(t *testing.T) { + path := filepath.Join(t.TempDir(), LockFileName) + if err := os.WriteFile(path, []byte("123\n"), 0o600); err != nil { + t.Fatal(err) + } + owned, err := ValidateHolderOwnership(path, 456) + if err != nil || owned { + t.Fatalf("ValidateHolderOwnership mismatch = %v, %v", owned, err) + } +} + func TestAcquire_AfterReleaseReclaimable(t *testing.T) { path := filepath.Join(t.TempDir(), LockFileName) l1, err := Acquire(path) diff --git a/internal/event/busctl/coverage_edges_test.go b/internal/event/busctl/coverage_edges_test.go index f84ed54e..09de121c 100644 --- a/internal/event/busctl/coverage_edges_test.go +++ b/internal/event/busctl/coverage_edges_test.go @@ -284,11 +284,13 @@ func TestCrossPlatformCoverageQueryStatusAndEntryEdges(t *testing.T) { func TestCrossPlatformCoverageStopInjectedEdges(t *testing.T) { origRead := stopReadHolderPID + origValidateOwner := stopValidateHolderOwner origAlive := stopAlive origFind := stopFindProcess origSignal := stopSignalProcess t.Cleanup(func() { stopReadHolderPID = origRead + stopValidateHolderOwner = origValidateOwner stopAlive = origAlive stopFindProcess = origFind stopSignalProcess = origSignal @@ -307,6 +309,7 @@ func TestCrossPlatformCoverageStopInjectedEdges(t *testing.T) { t.Fatal(err) } stopFindProcess = func(int) (*os.Process, error) { return proc, nil } + stopValidateHolderOwner = func(string, int) (bool, error) { return true, nil } stopSignalProcess = func(*os.Process, os.Signal) error { return os.ErrProcessDone } if err := Stop(StopConfig{WorkDir: "x"}); err != nil { t.Fatalf("done signal = %v", err) diff --git a/internal/event/busctl/stop.go b/internal/event/busctl/stop.go index c3349492..6748b516 100644 --- a/internal/event/busctl/stop.go +++ b/internal/event/busctl/stop.go @@ -35,13 +35,19 @@ const DefaultStopTimeout = 5 * time.Second // distinguish "nothing to stop" from "failed to stop". var ErrNotRunning = errors.New("busctl: bus is not running") +// ErrOwnerUnverified indicates the PID from bus.lock is alive but no longer +// owns that lock. Stop refuses to send a process-level signal in this state +// because the operating system may have reused the stale PID. +var ErrOwnerUnverified = errors.New("busctl: bus process ownership could not be verified") + var ( - stopReadHolderPID = bus.ReadHolderPID - stopAlive = process.Alive - stopFindProcess = os.FindProcess - stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) } - stopDial = transport.Dial - stopRequest = requestBusStop + stopReadHolderPID = bus.ReadHolderPID + stopValidateHolderOwner = bus.ValidateHolderOwnership + stopAlive = process.Alive + stopFindProcess = os.FindProcess + stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) } + stopDial = transport.Dial + stopRequest = requestBusStop ) // StopConfig identifies the target bus and tunes timing. @@ -93,6 +99,14 @@ func Stop(cfg StopConfig) error { } } + owner, err := stopValidateHolderOwner(LockPath(cfg.WorkDir), pid) + if err != nil { + return fmt.Errorf("busctl: verify bus pid=%d ownership: %w", pid, err) + } + if !owner { + return fmt.Errorf("%w: pid=%d does not own %s; stale PID was not signalled", ErrOwnerUnverified, pid, LockPath(cfg.WorkDir)) + } + if err := stopSignalProcess(proc, stopSignal()); err != nil { // On many Unix platforms Signal returns "process already finished" // when the bus has just exited on its own — treat that as success. diff --git a/internal/event/busctl/stop_test.go b/internal/event/busctl/stop_test.go index a3ae31f5..10d481f2 100644 --- a/internal/event/busctl/stop_test.go +++ b/internal/event/busctl/stop_test.go @@ -85,6 +85,41 @@ func TestCrossPlatformCoverageStopPrefersGracefulIPC(t *testing.T) { } } +func TestCrossPlatformCoverageStopDoesNotSignalUnverifiedReusedPID(t *testing.T) { + const pid = 4242 + testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid }) + testseam.Swap(t, &stopAlive, func(int) bool { return true }) + proc, err := os.FindProcess(os.Getpid()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil }) + testseam.Swap(t, &stopRequest, func(string) error { return errors.New("stale endpoint") }) + testseam.Swap(t, &stopValidateHolderOwner, func(path string, gotPID int) (bool, error) { + if path != LockPath("test-workdir") || gotPID != pid { + t.Fatalf("ownership check path=%q pid=%d", path, gotPID) + } + return false, nil + }) + signals := 0 + testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error { + signals++ + return nil + }) + + err = Stop(StopConfig{ + WorkDir: "test-workdir", + IPCEndpoint: "stale-endpoint", + Timeout: time.Millisecond, + }) + if !errors.Is(err, ErrOwnerUnverified) { + t.Fatalf("Stop() error = %v, want ErrOwnerUnverified", err) + } + if signals != 0 { + t.Fatalf("unverified reused PID received %d signals", signals) + } +} + func TestCrossPlatformCoverageRequestBusStopProtocol(t *testing.T) { dir := shortTempDir(t) endpoint := dwsevent.IPCEndpoint( @@ -206,6 +241,7 @@ func TestStop_SignalsLiveProcess(t *testing.T) { } }() pid := cmd.Process.Pid + testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { return true, nil }) // Reap the child in background so Wait doesn't leave a zombie. waited := make(chan error, 1) @@ -254,6 +290,7 @@ func TestStop_TimeoutWhenChildIgnoresSignal(t *testing.T) { _, _ = cmd.Process.Wait() }() pid := cmd.Process.Pid + testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { return true, nil }) if err := os.WriteFile(LockPath(dir), []byte(strconv.Itoa(pid)+"\n"), 0o600); err != nil { t.Fatal(err) From e3553fe7a5f0d659d5a8ee04f0689feeebe68ad7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Mon, 17 Aug 2026 10:40:21 +0800 Subject: [PATCH 151/250] test(event): cover bus ownership validation failures --- internal/event/bus/lockfile_test.go | 56 +++++++++++++++++++++++++++++ internal/event/busctl/stop_test.go | 28 +++++++++++++++ 2 files changed, 84 insertions(+) diff --git a/internal/event/bus/lockfile_test.go b/internal/event/bus/lockfile_test.go index d36e7e8a..f5b9a29a 100644 --- a/internal/event/bus/lockfile_test.go +++ b/internal/event/bus/lockfile_test.go @@ -16,9 +16,13 @@ package bus import ( "errors" "fmt" + "io" "os" "path/filepath" "testing" + + eventlock "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/lock" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" ) func TestAcquire_WritesOurPID(t *testing.T) { @@ -163,6 +167,58 @@ func TestCrossPlatformCoverageValidateHolderOwnershipRejectsMismatch(t *testing. } } +func TestCrossPlatformCoverageValidateHolderOwnershipErrors(t *testing.T) { + errInjected := errors.New("injected ownership validation failure") + writeLivePID := func(t *testing.T) string { + t.Helper() + path := filepath.Join(t.TempDir(), LockFileName) + if err := os.WriteFile(path, []byte(fmt.Sprintf("%d\n", os.Getpid())), 0o600); err != nil { + t.Fatal(err) + } + return path + } + + t.Run("probe", func(t *testing.T) { + path := writeLivePID(t) + testseam.Swap(t, &busTryAcquire, func(string) (*eventlock.File, error) { + return nil, errInjected + }) + if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) { + t.Fatalf("probe error = %v", err) + } + }) + + t.Run("seek", func(t *testing.T) { + path := writeLivePID(t) + testseam.Swap(t, &busSeek, func(*os.File, int64, int) (int64, error) { + return 0, errInjected + }) + if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) { + t.Fatalf("seek error = %v", err) + } + }) + + t.Run("read", func(t *testing.T) { + path := writeLivePID(t) + testseam.Swap(t, &busReadAll, func(io.Reader) ([]byte, error) { + return nil, errInjected + }) + if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) { + t.Fatalf("read error = %v", err) + } + }) + + t.Run("clear", func(t *testing.T) { + path := writeLivePID(t) + testseam.Swap(t, &busTruncate, func(*os.File, int64) error { + return errInjected + }) + if _, err := ValidateHolderOwnership(path, os.Getpid()); !errors.Is(err, errInjected) { + t.Fatalf("clear error = %v", err) + } + }) +} + func TestAcquire_AfterReleaseReclaimable(t *testing.T) { path := filepath.Join(t.TempDir(), LockFileName) l1, err := Acquire(path) diff --git a/internal/event/busctl/stop_test.go b/internal/event/busctl/stop_test.go index 10d481f2..5c086c86 100644 --- a/internal/event/busctl/stop_test.go +++ b/internal/event/busctl/stop_test.go @@ -120,6 +120,34 @@ func TestCrossPlatformCoverageStopDoesNotSignalUnverifiedReusedPID(t *testing.T) } } +func TestCrossPlatformCoverageStopReportsOwnershipValidationError(t *testing.T) { + const pid = 4242 + errInjected := errors.New("ownership validation failed") + testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid }) + testseam.Swap(t, &stopAlive, func(int) bool { return true }) + proc, err := os.FindProcess(os.Getpid()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil }) + testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { + return false, errInjected + }) + signals := 0 + testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error { + signals++ + return nil + }) + + err = Stop(StopConfig{WorkDir: "test-workdir"}) + if !errors.Is(err, errInjected) { + t.Fatalf("Stop() error = %v, want injected ownership error", err) + } + if signals != 0 { + t.Fatalf("ownership validation error sent %d signals", signals) + } +} + func TestCrossPlatformCoverageRequestBusStopProtocol(t *testing.T) { dir := shortTempDir(t) endpoint := dwsevent.IPCEndpoint( From 4f9537342073bf5d9390f104a7effd45d0d930b4 Mon Sep 17 00:00:00 2001 From: chichuan Date: Mon, 17 Aug 2026 10:59:11 +0800 Subject: [PATCH 152/250] docs: seal changelog for v1.0.59-beta.2 --- .../1.0.59-beta.2}/1009-clitrack-telemetry.md | 0 .../1019-help-feedback-entry.md | 0 .../1.0.59-beta.2}/954-chat-im-id-flags.md | 0 .../chat-reference-card-verification.md | 0 .../schema-catalog-json-projection.md | 0 .../1.0.59-beta.2}/wiki-shortcut-alignment.md | 0 CHANGELOG.md | 31 +++++++++++++++++++ 7 files changed, 31 insertions(+) rename .changes/{ => released/1.0.59-beta.2}/1009-clitrack-telemetry.md (100%) rename .changes/{ => released/1.0.59-beta.2}/1019-help-feedback-entry.md (100%) rename .changes/{ => released/1.0.59-beta.2}/954-chat-im-id-flags.md (100%) rename .changes/{ => released/1.0.59-beta.2}/chat-reference-card-verification.md (100%) rename .changes/{ => released/1.0.59-beta.2}/schema-catalog-json-projection.md (100%) rename .changes/{ => released/1.0.59-beta.2}/wiki-shortcut-alignment.md (100%) diff --git a/.changes/1009-clitrack-telemetry.md b/.changes/released/1.0.59-beta.2/1009-clitrack-telemetry.md similarity index 100% rename from .changes/1009-clitrack-telemetry.md rename to .changes/released/1.0.59-beta.2/1009-clitrack-telemetry.md diff --git a/.changes/1019-help-feedback-entry.md b/.changes/released/1.0.59-beta.2/1019-help-feedback-entry.md similarity index 100% rename from .changes/1019-help-feedback-entry.md rename to .changes/released/1.0.59-beta.2/1019-help-feedback-entry.md diff --git a/.changes/954-chat-im-id-flags.md b/.changes/released/1.0.59-beta.2/954-chat-im-id-flags.md similarity index 100% rename from .changes/954-chat-im-id-flags.md rename to .changes/released/1.0.59-beta.2/954-chat-im-id-flags.md diff --git a/.changes/chat-reference-card-verification.md b/.changes/released/1.0.59-beta.2/chat-reference-card-verification.md similarity index 100% rename from .changes/chat-reference-card-verification.md rename to .changes/released/1.0.59-beta.2/chat-reference-card-verification.md diff --git a/.changes/schema-catalog-json-projection.md b/.changes/released/1.0.59-beta.2/schema-catalog-json-projection.md similarity index 100% rename from .changes/schema-catalog-json-projection.md rename to .changes/released/1.0.59-beta.2/schema-catalog-json-projection.md diff --git a/.changes/wiki-shortcut-alignment.md b/.changes/released/1.0.59-beta.2/wiki-shortcut-alignment.md similarity index 100% rename from .changes/wiki-shortcut-alignment.md rename to .changes/released/1.0.59-beta.2/wiki-shortcut-alignment.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a1f2dfc..9afe33b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,37 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +## [1.0.59-beta.2] - 2026-08-17 + +### Added + +- **Privacy-safe CLI telemetry** (#1009) — reports reviewed command outcomes and profile identity dimensions while excluding command arguments, output, paths, device fingerprints, and automatic system dimensions; `DO_NOT_TRACK=1` disables reporting. + +- **Feedback survey entry in root help** (#1019) — `dws --help` now closes with a Feedback section linking the user-experience survey form. + +- **Wiki Shortcut workflows** — publishes 20 reviewed space, member, node, and + activity shortcuts with strict collection validation, cursor handling, + write-terminal evidence, safe read-backs where the backend supports them, + task-oriented routing, and documented backend + boundaries. + +### Changed + +- **Chat IM ID flags** (#954) — standardizes chat command entry points on `--conversation-id` for conversation IDs and `--message-id` for message IDs, so help, Schema, and Agent recommendations use the same canonical flags. +- **Legacy chat flag compatibility** (#954) — keeps older chat IM ID flags such as `--group`, `--id`, `--chat`, `--open-conversation-id`, `--msg-id`, and `--open-message-id` working as compatibility aliases where applicable, while hiding migrated aliases from recommended help and Schema surfaces. +- **Chat group bots target flag** (#954) — keeps `dws chat group bots` on the visible `--group` flag; this command does not register `--group-name`, and `--group` accepts either an openConversationId or a uniquely resolved group name. + +- **Faster Schema Catalog assembly** — projects typed values into payload JSON + without re-running a validation scan over documents `json.Marshal` has just + produced, cutting roughly a third of the projection work across the full tool + set. Untrusted JSON input keeps its existing validation. + +### Fixed + +- **Chat card update evidence** — distinguishes an accepted update request from an independently verified visible update, preserving the real `bizId` and warning callers not to repeat an unverified write. +- **Chat command guidance** — splits message and group references by task and explains that `--from` is ambiguous between sender and time-range intent. + + ## [1.0.59-beta.1] - 2026-08-14 ### Added From bfeb9f6af0af6e8f905fe1768540b192bcdb01e3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 17 Aug 2026 03:35:41 +0000 Subject: [PATCH 153/250] chore: update beta formula for v1.0.59-beta.2 [skip ci] --- Formula/dingtalk-workspace-cli-beta.rb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Formula/dingtalk-workspace-cli-beta.rb b/Formula/dingtalk-workspace-cli-beta.rb index 98fc206f..1d76aa1f 100644 --- a/Formula/dingtalk-workspace-cli-beta.rb +++ b/Formula/dingtalk-workspace-cli-beta.rb @@ -1,33 +1,33 @@ class DingtalkWorkspaceCliBeta < Formula desc "Automate DingTalk workspace tasks from the terminal (beta channel)" homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli" - version "1.0.59-beta.1" + version "1.0.59-beta.2" license "Apache-2.0" keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli" on_macos do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-arm64.tar.gz" - sha256 "36a30f3496e0f759c15c0b09f67dbd23b8ecdfff2eebe572f88125b26485830f" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-arm64.tar.gz" + sha256 "7f11218d3222f3e93c3b1e94b3a004c061eb0a297b206447ea95fe6b2b1ec674" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-darwin-amd64.tar.gz" - sha256 "e7a04906380efd8da88cd112e6a512bb6470a3956dc370150037ed6e314db445" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-amd64.tar.gz" + sha256 "72f06a334cf29d23123639fabe13bf2951765066136e47ccc6453667c382f8c2" end end on_linux do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-arm64.tar.gz" - sha256 "f59ab055f3e841e4cebc964ae3ef969668475548abaaf8bede44afdca9a3e28d" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-arm64.tar.gz" + sha256 "3edbfabb7718b53914a2d9efe7b1152e9ebd70765ff0b6f19ad3125e4a2458ed" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-linux-amd64.tar.gz" - sha256 "2c8f919489d958c7d49262615e81faac70a9fbcae2d589ab54a0bb3c5700a057" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-amd64.tar.gz" + sha256 "e1c610070a9c1b3763656cbd53c818290f199097adc07cb9fe629ed765c5e1e0" end end resource "skills" do - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.1/dws-skills.zip" - sha256 "25f4a7e1d01fa4d771d79201b34b11ee8a24182bdcdc94bfb98d2bd5845bed3b" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-skills.zip" + sha256 "aa2854651eaa2c857b526aaec73fd1358d31b11999fe7fd3e99e5060b2522a1f" end def install From 7ad82bbf0a72dac4937d2369ce82d853c98b3608 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Mon, 17 Aug 2026 13:00:07 +0800 Subject: [PATCH 154/250] fix(event): accept bus exit at stop timeout boundary --- internal/event/busctl/stop.go | 17 ++++++++- internal/event/busctl/stop_test.go | 61 ++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 2 deletions(-) diff --git a/internal/event/busctl/stop.go b/internal/event/busctl/stop.go index 6748b516..8779a94f 100644 --- a/internal/event/busctl/stop.go +++ b/internal/event/busctl/stop.go @@ -48,6 +48,7 @@ var ( stopSignalProcess = func(proc *os.Process, signal os.Signal) error { return proc.Signal(signal) } stopDial = transport.Dial stopRequest = requestBusStop + stopWaitForBusExit = waitForBusExit ) // StopConfig identifies the target bus and tunes timing. @@ -94,16 +95,28 @@ func Stop(cfg StopConfig) error { return fmt.Errorf("busctl: find process %d: %w", pid, err) } if strings.TrimSpace(cfg.IPCEndpoint) != "" { - if err := stopRequest(cfg.IPCEndpoint); err == nil && waitForBusExit(pid, cfg.Timeout) { + if err := stopRequest(cfg.IPCEndpoint); err == nil && stopWaitForBusExit(pid, cfg.Timeout) { return nil } } + // The bus may finish shutting down immediately after the graceful wait + // reaches its deadline (or after a failed IPC request). Recheck before + // inspecting ownership so a completed stop is not reported as stale. + if !stopAlive(pid) { + return nil + } owner, err := stopValidateHolderOwner(LockPath(cfg.WorkDir), pid) if err != nil { return fmt.Errorf("busctl: verify bus pid=%d ownership: %w", pid, err) } if !owner { + // ValidateHolderOwnership observes a released lock both for a stale, + // reused PID and for a bus that exits during the ownership probe. Only + // the still-alive case is unsafe to signal. + if !stopAlive(pid) { + return nil + } return fmt.Errorf("%w: pid=%d does not own %s; stale PID was not signalled", ErrOwnerUnverified, pid, LockPath(cfg.WorkDir)) } @@ -116,7 +129,7 @@ func Stop(cfg StopConfig) error { return fmt.Errorf("busctl: signal bus pid=%d: %w", pid, err) } - if waitForBusExit(pid, cfg.Timeout) { + if stopWaitForBusExit(pid, cfg.Timeout) { return nil } return fmt.Errorf("busctl: bus pid=%d did not exit within %s", pid, cfg.Timeout) diff --git a/internal/event/busctl/stop_test.go b/internal/event/busctl/stop_test.go index 5c086c86..8154dd64 100644 --- a/internal/event/busctl/stop_test.go +++ b/internal/event/busctl/stop_test.go @@ -120,6 +120,67 @@ func TestCrossPlatformCoverageStopDoesNotSignalUnverifiedReusedPID(t *testing.T) } } +func TestCrossPlatformCoverageStopAcceptsExitAtGracefulTimeoutBoundary(t *testing.T) { + const pid = 4242 + + t.Run("before ownership validation", func(t *testing.T) { + exited := false + validated := false + testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid }) + testseam.Swap(t, &stopAlive, func(int) bool { return !exited }) + proc, err := os.FindProcess(os.Getpid()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil }) + testseam.Swap(t, &stopRequest, func(string) error { return nil }) + testseam.Swap(t, &stopWaitForBusExit, func(int, time.Duration) bool { + exited = true + return false + }) + testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { + validated = true + return false, nil + }) + + if err := Stop(StopConfig{WorkDir: "test-workdir", IPCEndpoint: "test-endpoint"}); err != nil { + t.Fatalf("Stop() = %v, want success after bus exit", err) + } + if validated { + t.Fatal("ownership was validated after the bus had already exited") + } + }) + + t.Run("during ownership validation", func(t *testing.T) { + exited := false + signals := 0 + testseam.Swap(t, &stopReadHolderPID, func(string) int { return pid }) + testseam.Swap(t, &stopAlive, func(int) bool { return !exited }) + proc, err := os.FindProcess(os.Getpid()) + if err != nil { + t.Fatal(err) + } + testseam.Swap(t, &stopFindProcess, func(int) (*os.Process, error) { return proc, nil }) + testseam.Swap(t, &stopRequest, func(string) error { return nil }) + testseam.Swap(t, &stopWaitForBusExit, func(int, time.Duration) bool { return false }) + testseam.Swap(t, &stopValidateHolderOwner, func(string, int) (bool, error) { + exited = true + return false, nil + }) + testseam.Swap(t, &stopSignalProcess, func(*os.Process, os.Signal) error { + signals++ + return nil + }) + + if err := Stop(StopConfig{WorkDir: "test-workdir", IPCEndpoint: "test-endpoint"}); err != nil { + t.Fatalf("Stop() = %v, want success after exit during ownership validation", err) + } + if signals != 0 { + t.Fatalf("exited bus received %d fallback signals", signals) + } + }) +} + func TestCrossPlatformCoverageStopReportsOwnershipValidationError(t *testing.T) { const pid = 4242 errInjected := errors.New("ownership validation failed") From 857279e076fbc91b0b36585547d04aec18a34a9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Mon, 17 Aug 2026 14:03:42 +0800 Subject: [PATCH 155/250] =?UTF-8?q?=E5=B0=86=E9=99=84=E4=BB=B6=E7=9B=B8?= =?UTF-8?q?=E5=85=B3dws=E8=BF=81=E7=A7=BB=E5=88=B0oa.go=E4=B8=AD=EF=BC=8C?= =?UTF-8?q?=E5=B9=B6=E8=A1=A5=E5=85=85skill=E6=8F=8F=E8=BF=B0=20to=20#666?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- internal/helpers/oa.go | 253 +++++++++++++++++ internal/helpers/oa_attachment.go | 268 ------------------ skills/mono/references/products/oa.md | 54 ++++ skills/multi/dingtalk-misc/references/oa.md | 54 ++++ .../oa_attachment_delivery_policy_test.go | 64 +++++ 5 files changed, 425 insertions(+), 268 deletions(-) delete mode 100644 internal/helpers/oa_attachment.go create mode 100644 test/unit/oa_attachment_delivery_policy_test.go diff --git a/internal/helpers/oa.go b/internal/helpers/oa.go index 3f57cc81..2104ba3a 100644 --- a/internal/helpers/oa.go +++ b/internal/helpers/oa.go @@ -10,6 +10,7 @@ import ( "strings" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" "github.com/spf13/cobra" ) @@ -42,6 +43,258 @@ func oaFormValues(raw string) ([]map[string]string, error) { return result, nil } +func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) { + decoder := json.NewDecoder(strings.NewReader(raw)) + decoder.UseNumber() + var items []map[string]json.RawMessage + if err := decoder.Decode(&items); err != nil { + return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err) + } + if err := rejectTrailingOAAttachmentJSON(decoder); err != nil { + return nil, err + } + if len(items) < 1 || len(items) > 10 { + return nil, fmt.Errorf("--file-infos 必须包含 1 至 10 个文件") + } + + infos := make([]map[string]any, 0, len(items)) + for index, item := range items { + for name := range item { + if name != "spaceId" && name != "fileId" { + return nil, fmt.Errorf("--file-infos 第 %d 项包含未知字段 %q", index+1, name) + } + } + + spaceRaw, ok := item["spaceId"] + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1) + } + spaceDecoder := json.NewDecoder(strings.NewReader(string(spaceRaw))) + spaceDecoder.UseNumber() + var spaceValue any + if err := spaceDecoder.Decode(&spaceValue); err != nil { + return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 不是有效数字: %w", index+1, err) + } + spaceID, ok := spaceValue.(json.Number) + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1) + } + + fileRaw, ok := item["fileId"] + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1) + } + var fileID string + if err := json.Unmarshal(fileRaw, &fileID); err != nil { + return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串: %w", index+1, err) + } + fileID = strings.TrimSpace(fileID) + if fileID == "" { + return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 不能为空", index+1) + } + + infos = append(infos, map[string]any{"spaceId": spaceID, "fileId": fileID}) + } + return infos, nil +} + +func rejectTrailingOAAttachmentJSON(decoder *json.Decoder) error { + var extra any + if err := decoder.Decode(&extra); err != io.EOF { + if err == nil { + return fmt.Errorf("--file-infos JSON 包含多余内容") + } + return fmt.Errorf("--file-infos JSON 解析失败: %w", err) + } + return nil +} + +func validateOAAttachmentFileInfos(cmd *cobra.Command, _ []string) error { + raw, _ := cmd.Flags().GetString("file-infos") + _, err := parseOAAttachmentFileInfos(raw) + return err +} + +func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error { + fileIDs, _ := cmd.Flags().GetStringSlice("file-ids") + if len(fileIDs) > 20 { + return fmt.Errorf("--file-ids 最多包含 20 个附件 ID") + } + for index, fileID := range fileIDs { + if strings.TrimSpace(fileID) == "" { + return fmt.Errorf("--file-ids 第 %d 项不能为空", index+1) + } + } + return nil +} + +func newOAAttachmentCommand() *cobra.Command { + attachmentCmd := &cobra.Command{ + Use: "attachment", + Short: "审批附件授权与下载链接", + RunE: groupRunE, + } + + downloadURLCmd := NewLeafCommand(LeafSpec{ + Use: "download-url", + Short: "获取审批附件下载链接", + Example: " dws oa approval attachment download-url --instance-id --file-id ", + Server: "oa", + Tool: "get_attachment_download_url", + Call: func(_ *cobra.Command, tool string, args map[string]any) error { + jsonOutput := strings.EqualFold(strings.TrimSpace(deps.Caller.Format()), "json") + return callMCPToolInternalOpts("oa", tool, args, jsonOutput) + }, + Flags: []LeafFlag{ + {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, + {Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true}, + {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, + }, + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "get_attachment_download_url", + CanonicalPath: "oa.get_attachment_download_url", + CLIPath: "oa approval attachment download-url", + PrimaryCLIPath: "oa approval attachment download-url", + }, + Description: "获取审批附件下载授权并生成临时下载链接", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_attachment_download_url"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "获取审批实例中指定附件的临时下载链接", + UseWhen: []string{"已从审批详情获得 processInstanceId 和 fileId，需要获取附件下载链接时"}, + AvoidWhen: []string{ + "只需查看审批表单和附件元数据时使用 dws oa approval detail", + "需要将附件真正保存到本地时不要误认为本命令会下载文件；它只返回链接", + }, + Examples: []string{"dws oa approval attachment download-url --instance-id --file-id "}, + }, + Parameters: []contract.ParamDecl{ + {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, + {Name: "file-id", Property: "fileId", InterfaceType: "string"}, + {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, + }, + }, + }) + + authorizeDownloadCmd := NewLeafCommand(LeafSpec{ + Use: "authorize-download", + Short: "授权当前用户下载审批钉盘文件", + Long: "批量授权当前用户下载指定的审批钉盘文件。", + Example: ` dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`, + Server: "oa", + Tool: "auth_download_file", + Flags: []LeafFlag{ + { + Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)", + Bind: "fileInfos", Trim: true, Required: true, MarkRequired: true, + Transform: func(raw string) (any, error) { + return parseOAAttachmentFileInfos(raw) + }, + }, + }, + Constraints: []LeafConstraint{{ + Kind: corecmd.Custom, Flags: []string{"file-infos"}, + Description: "文件信息列表必须包含 1 至 10 项", + }}, + Validate: validateOAAttachmentFileInfos, + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "auth_download_file", + CanonicalPath: "oa.auth_download_file", + CLIPath: "oa approval attachment authorize-download", + PrimaryCLIPath: "oa approval attachment authorize-download", + }, + Description: "批量授权当前用户下载指定的审批钉盘文件", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_download_file"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "使用审批钉盘 spaceId/fileId 批量授权当前用户下载文件", + UseWhen: []string{"已有一个或多个审批钉盘文件的 spaceId 和 fileId，需要为当前用户取得下载权限时"}, + AvoidWhen: []string{ + "需要生成单个审批附件下载链接时使用 attachment download-url", + "需要授权在审批单内预览附件时使用 attachment authorize-preview", + }, + Examples: []string{`dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`}, + }, + Parameters: []contract.ParamDecl{ + {Name: "file-infos", Property: "fileInfos", InterfaceType: "array"}, + }, + }, + }) + + authorizePreviewCmd := NewLeafCommand(LeafSpec{ + Use: "authorize-preview", + Short: "授权当前用户预览审批附件", + Long: "批量授权当前用户预览审批单中的附件。", + Example: " dws oa approval attachment authorize-preview --instance-id --file-ids ,", + Server: "oa", + Tool: "auth_preview_attachment", + Flags: []LeafFlag{ + {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, + {Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true}, + {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, + }, + Constraints: []LeafConstraint{{ + Kind: corecmd.Custom, Flags: []string{"file-ids"}, + Description: "附件 ID 列表最多包含 20 项且每项不能为空", + }}, + Validate: validateOAPreviewFileIDs, + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", + Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: contract.ToolIdentitySpec{ + ProductID: "oa", + Name: "auth_preview_attachment", + CanonicalPath: "oa.auth_preview_attachment", + CLIPath: "oa approval attachment authorize-preview", + PrimaryCLIPath: "oa approval attachment authorize-preview", + }, + Description: "批量授权当前用户预览审批单中的附件", + Interface: &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_preview_attachment"}, + }, + Selection: contract.SelectionSpec{ + AgentSummary: "按审批实例和附件 ID 列表授权当前用户预览附件", + UseWhen: []string{"已有 processInstanceId 和附件 fileId 列表，需要在审批场景中批量取得预览权限时"}, + AvoidWhen: []string{ + "需要下载权限而不是预览权限时使用 attachment authorize-download", + "需要直接获得单个附件临时下载链接时使用 attachment download-url", + }, + Examples: []string{"dws oa approval attachment authorize-preview --instance-id --file-ids ,"}, + }, + Parameters: []contract.ParamDecl{ + {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, + {Name: "file-ids", Property: "fileIdList", InterfaceType: "array"}, + {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, + }, + }, + }) + + attachmentCmd.AddCommand(downloadURLCmd, authorizeDownloadCmd, authorizePreviewCmd) + return attachmentCmd +} + // ────────────────────────────────────────────────────────── // dws oa — OA 审批 // MCP tools（tools/list）: list_pending_approvals, get_processInstance_detail, diff --git a/internal/helpers/oa_attachment.go b/internal/helpers/oa_attachment.go deleted file mode 100644 index 6994d2d6..00000000 --- a/internal/helpers/oa_attachment.go +++ /dev/null @@ -1,268 +0,0 @@ -// Copyright 2026 Alibaba Group -// Licensed under the Apache License, Version 2.0 (the "License"); - -package helpers - -import ( - "encoding/json" - "fmt" - "io" - "strings" - - "github.com/spf13/cobra" - - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" -) - -func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) { - decoder := json.NewDecoder(strings.NewReader(raw)) - decoder.UseNumber() - var items []map[string]json.RawMessage - if err := decoder.Decode(&items); err != nil { - return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err) - } - if err := rejectTrailingOAAttachmentJSON(decoder); err != nil { - return nil, err - } - if len(items) < 1 || len(items) > 10 { - return nil, fmt.Errorf("--file-infos 必须包含 1 至 10 个文件") - } - - infos := make([]map[string]any, 0, len(items)) - for index, item := range items { - for name := range item { - if name != "spaceId" && name != "fileId" { - return nil, fmt.Errorf("--file-infos 第 %d 项包含未知字段 %q", index+1, name) - } - } - - spaceRaw, ok := item["spaceId"] - if !ok { - return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1) - } - spaceDecoder := json.NewDecoder(strings.NewReader(string(spaceRaw))) - spaceDecoder.UseNumber() - var spaceValue any - if err := spaceDecoder.Decode(&spaceValue); err != nil { - return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 不是有效数字: %w", index+1, err) - } - spaceID, ok := spaceValue.(json.Number) - if !ok { - return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1) - } - - fileRaw, ok := item["fileId"] - if !ok { - return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1) - } - var fileID string - if err := json.Unmarshal(fileRaw, &fileID); err != nil { - return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串: %w", index+1, err) - } - fileID = strings.TrimSpace(fileID) - if fileID == "" { - return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 不能为空", index+1) - } - - infos = append(infos, map[string]any{"spaceId": spaceID, "fileId": fileID}) - } - return infos, nil -} - -func rejectTrailingOAAttachmentJSON(decoder *json.Decoder) error { - var extra any - if err := decoder.Decode(&extra); err != io.EOF { - if err == nil { - return fmt.Errorf("--file-infos JSON 包含多余内容") - } - return fmt.Errorf("--file-infos JSON 解析失败: %w", err) - } - return nil -} - -func validateOAAttachmentFileInfos(cmd *cobra.Command, _ []string) error { - raw, _ := cmd.Flags().GetString("file-infos") - _, err := parseOAAttachmentFileInfos(raw) - return err -} - -func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error { - fileIDs, _ := cmd.Flags().GetStringSlice("file-ids") - if len(fileIDs) > 20 { - return fmt.Errorf("--file-ids 最多包含 20 个附件 ID") - } - for index, fileID := range fileIDs { - if strings.TrimSpace(fileID) == "" { - return fmt.Errorf("--file-ids 第 %d 项不能为空", index+1) - } - } - return nil -} - -func newOAAttachmentCommand() *cobra.Command { - attachmentCmd := &cobra.Command{ - Use: "attachment", - Short: "审批附件授权与下载链接", - RunE: groupRunE, - } - - downloadURLCmd := NewLeafCommand(LeafSpec{ - Use: "download-url", - Short: "获取审批附件下载链接", - Example: " dws oa approval attachment download-url --instance-id --file-id ", - Server: "oa", - Tool: "get_attachment_download_url", - Call: func(_ *cobra.Command, tool string, args map[string]any) error { - jsonOutput := strings.EqualFold(strings.TrimSpace(deps.Caller.Format()), "json") - return callMCPToolInternalOpts("oa", tool, args, jsonOutput) - }, - Flags: []LeafFlag{ - {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, - {Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true}, - {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, - }, - Safety: contract.SafetySpec{ - Effect: "read", Risk: "low", - Confirmation: "not_required", Idempotency: "idempotent", - }, - Contract: LeafContract{ - Identity: contract.ToolIdentitySpec{ - ProductID: "oa", - Name: "get_attachment_download_url", - CanonicalPath: "oa.get_attachment_download_url", - CLIPath: "oa approval attachment download-url", - PrimaryCLIPath: "oa approval attachment download-url", - }, - Description: "获取审批附件下载授权并生成临时下载链接", - Interface: &contract.InterfaceSpec{ - Mode: "mcp", - Availability: "available", - Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_attachment_download_url"}, - }, - Selection: contract.SelectionSpec{ - AgentSummary: "获取审批实例中指定附件的临时下载链接", - UseWhen: []string{"已从审批详情获得 processInstanceId 和 fileId，需要获取附件下载链接时"}, - AvoidWhen: []string{ - "只需查看审批表单和附件元数据时使用 dws oa approval detail", - "需要将附件真正保存到本地时不要误认为本命令会下载文件；它只返回链接", - }, - Examples: []string{"dws oa approval attachment download-url --instance-id --file-id "}, - }, - Parameters: []contract.ParamDecl{ - {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, - {Name: "file-id", Property: "fileId", InterfaceType: "string"}, - {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, - }, - }, - }) - - authorizeDownloadCmd := NewLeafCommand(LeafSpec{ - Use: "authorize-download", - Short: "授权当前用户下载审批钉盘文件", - Long: "批量授权当前用户下载指定的审批钉盘文件。", - Example: ` dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`, - Server: "oa", - Tool: "auth_download_file", - Flags: []LeafFlag{ - { - Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)", - Bind: "fileInfos", Trim: true, Required: true, MarkRequired: true, - Transform: func(raw string) (any, error) { - return parseOAAttachmentFileInfos(raw) - }, - }, - }, - Constraints: []LeafConstraint{{ - Kind: corecmd.Custom, Flags: []string{"file-infos"}, - Description: "文件信息列表必须包含 1 至 10 项", - }}, - Validate: validateOAAttachmentFileInfos, - Safety: contract.SafetySpec{ - Effect: "write", Risk: "low", - Confirmation: "not_required", Idempotency: "idempotent", - }, - Contract: LeafContract{ - Identity: contract.ToolIdentitySpec{ - ProductID: "oa", - Name: "auth_download_file", - CanonicalPath: "oa.auth_download_file", - CLIPath: "oa approval attachment authorize-download", - PrimaryCLIPath: "oa approval attachment authorize-download", - }, - Description: "批量授权当前用户下载指定的审批钉盘文件", - Interface: &contract.InterfaceSpec{ - Mode: "mcp", - Availability: "available", - Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_download_file"}, - }, - Selection: contract.SelectionSpec{ - AgentSummary: "使用审批钉盘 spaceId/fileId 批量授权当前用户下载文件", - UseWhen: []string{"已有一个或多个审批钉盘文件的 spaceId 和 fileId，需要为当前用户取得下载权限时"}, - AvoidWhen: []string{ - "需要生成单个审批附件下载链接时使用 attachment download-url", - "需要授权在审批单内预览附件时使用 attachment authorize-preview", - }, - Examples: []string{`dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`}, - }, - Parameters: []contract.ParamDecl{ - {Name: "file-infos", Property: "fileInfos", InterfaceType: "array"}, - }, - }, - }) - - authorizePreviewCmd := NewLeafCommand(LeafSpec{ - Use: "authorize-preview", - Short: "授权当前用户预览审批附件", - Long: "批量授权当前用户预览审批单中的附件。", - Example: " dws oa approval attachment authorize-preview --instance-id --file-ids ,", - Server: "oa", - Tool: "auth_preview_attachment", - Flags: []LeafFlag{ - {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, - {Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true}, - {Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"}, - }, - Constraints: []LeafConstraint{{ - Kind: corecmd.Custom, Flags: []string{"file-ids"}, - Description: "附件 ID 列表最多包含 20 项且每项不能为空", - }}, - Validate: validateOAPreviewFileIDs, - Safety: contract.SafetySpec{ - Effect: "write", Risk: "low", - Confirmation: "not_required", Idempotency: "idempotent", - }, - Contract: LeafContract{ - Identity: contract.ToolIdentitySpec{ - ProductID: "oa", - Name: "auth_preview_attachment", - CanonicalPath: "oa.auth_preview_attachment", - CLIPath: "oa approval attachment authorize-preview", - PrimaryCLIPath: "oa approval attachment authorize-preview", - }, - Description: "批量授权当前用户预览审批单中的附件", - Interface: &contract.InterfaceSpec{ - Mode: "mcp", - Availability: "available", - Ref: &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_preview_attachment"}, - }, - Selection: contract.SelectionSpec{ - AgentSummary: "按审批实例和附件 ID 列表授权当前用户预览附件", - UseWhen: []string{"已有 processInstanceId 和附件 fileId 列表，需要在审批场景中批量取得预览权限时"}, - AvoidWhen: []string{ - "需要下载权限而不是预览权限时使用 attachment authorize-download", - "需要直接获得单个附件临时下载链接时使用 attachment download-url", - }, - Examples: []string{"dws oa approval attachment authorize-preview --instance-id --file-ids ,"}, - }, - Parameters: []contract.ParamDecl{ - {Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"}, - {Name: "file-ids", Property: "fileIdList", InterfaceType: "array"}, - {Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"}, - }, - }, - }) - - attachmentCmd.AddCommand(downloadURLCmd, authorizeDownloadCmd, authorizePreviewCmd) - return attachmentCmd -} diff --git a/skills/mono/references/products/oa.md b/skills/mono/references/products/oa.md index 46c32b36..cc82079f 100644 --- a/skills/mono/references/products/oa.md +++ b/skills/mono/references/products/oa.md @@ -27,6 +27,57 @@ Flags: --instance-id string 审批实例 ID (必填) ``` +### 审批附件授权与下载 + +先从 `approval detail` 的返回中取得审批实例 `processInstanceId`、附件 `fileId`，以及授权下载所需的 `spaceId`。根据目标选择命令： + +- 需要单个附件的临时下载链接：`attachment download-url` +- 已有钉盘 `spaceId/fileId`，需要为当前用户批量开通下载权限：`attachment authorize-download` +- 需要在审批场景内批量预览附件：`attachment authorize-preview` + +#### 获取审批附件临时下载链接 + +``` +Usage: + dws oa approval attachment download-url [flags] +Example: + dws oa approval attachment download-url --instance-id --file-id --format json +Flags: + --instance-id string 审批实例 ID (必填) + --file-id string 审批附件文件 ID (必填) + --with-comment-attachment 是否包含评论中的附件 (可选，默认不包含) +``` + +该命令只返回临时下载链接，不会自动保存文件。链接包含 OSS 签名参数，应在生成后立即使用；JSON 输出中的 `&` 是签名参数分隔符，复制链接时必须完整保留。附件来自审批评论时增加 `--with-comment-attachment`。 + +#### 批量授权下载审批钉盘文件 + +``` +Usage: + dws oa approval attachment authorize-download [flags] +Example: + dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]' --format json +Flags: + --file-infos string 文件信息 JSON 数组 (必填)，每项包含数字类型 spaceId 和字符串类型 fileId，最多 10 项 +``` + +该命令为当前用户开通文件下载权限，但不返回下载链接。需要链接时继续调用 `attachment download-url`。 + +#### 批量授权预览审批附件 + +``` +Usage: + dws oa approval attachment authorize-preview [flags] +Example: + dws oa approval attachment authorize-preview --instance-id --file-ids , --format json +Flags: + --instance-id string 审批实例 ID (必填) + --file-ids strings 附件 ID 列表，逗号分隔 (必填)，最多 20 项 + --with-comment-attachment 是否包含评论中的附件 (可选，默认不包含) +``` + +该命令只授权审批场景内的附件预览，不等同于下载授权。附件来自审批评论时增加 `--with-comment-attachment`。 + ### 同意审批 > **CAUTION:** 审批决策不可撤回 — 执行前必须向用户确认。 @@ -667,6 +718,9 @@ Flags: 用户说"待审批/待处理审批" → `approval list-pending` 用户说"审批详情/看审批" → `approval detail` +用户说"下载审批附件/获取审批附件下载链接" → `approval attachment download-url`（需 --instance-id 和 --file-id；评论附件增加 --with-comment-attachment） +用户说"授权下载审批钉盘文件/批量开通附件下载权限" → `approval attachment authorize-download`（需 --file-infos，最多 10 项） +用户说"预览审批附件/批量授权预览附件" → `approval attachment authorize-preview`（需 --instance-id 和 --file-ids，最多 20 项；评论附件增加 --with-comment-attachment） 用户说"同意审批/批准" → 先 `tasks` 获取 taskId，再 `approve` 用户说"拒绝审批/驳回" → 先 `tasks` 获取 taskId，再 `reject` 用户说"撤回审批/取消审批" → `approval revoke` diff --git a/skills/multi/dingtalk-misc/references/oa.md b/skills/multi/dingtalk-misc/references/oa.md index 4b5e6205..7124e064 100644 --- a/skills/multi/dingtalk-misc/references/oa.md +++ b/skills/multi/dingtalk-misc/references/oa.md @@ -31,6 +31,57 @@ Flags: --instance-id string 审批实例 ID (必填) ``` +### 审批附件授权与下载 + +先从 `approval detail` 的返回中取得审批实例 `processInstanceId`、附件 `fileId`，以及授权下载所需的 `spaceId`。根据目标选择命令： + +- 需要单个附件的临时下载链接：`attachment download-url` +- 已有钉盘 `spaceId/fileId`，需要为当前用户批量开通下载权限：`attachment authorize-download` +- 需要在审批场景内批量预览附件：`attachment authorize-preview` + +#### 获取审批附件临时下载链接 + +``` +Usage: + dws oa approval attachment download-url [flags] +Example: + dws oa approval attachment download-url --instance-id --file-id --format json +Flags: + --instance-id string 审批实例 ID (必填) + --file-id string 审批附件文件 ID (必填) + --with-comment-attachment 是否包含评论中的附件 (可选，默认不包含) +``` + +该命令只返回临时下载链接，不会自动保存文件。链接包含 OSS 签名参数，应在生成后立即使用；JSON 输出中的 `&` 是签名参数分隔符，复制链接时必须完整保留。附件来自审批评论时增加 `--with-comment-attachment`。 + +#### 批量授权下载审批钉盘文件 + +``` +Usage: + dws oa approval attachment authorize-download [flags] +Example: + dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]' --format json +Flags: + --file-infos string 文件信息 JSON 数组 (必填)，每项包含数字类型 spaceId 和字符串类型 fileId，最多 10 项 +``` + +该命令为当前用户开通文件下载权限，但不返回下载链接。需要链接时继续调用 `attachment download-url`。 + +#### 批量授权预览审批附件 + +``` +Usage: + dws oa approval attachment authorize-preview [flags] +Example: + dws oa approval attachment authorize-preview --instance-id --file-ids , --format json +Flags: + --instance-id string 审批实例 ID (必填) + --file-ids strings 附件 ID 列表，逗号分隔 (必填)，最多 20 项 + --with-comment-attachment 是否包含评论中的附件 (可选，默认不包含) +``` + +该命令只授权审批场景内的附件预览，不等同于下载授权。附件来自审批评论时增加 `--with-comment-attachment`。 + ### 同意审批 > **CAUTION:** 审批决策不可撤回 — 执行前必须向用户确认。 @@ -670,6 +721,9 @@ Flags: - 示例："有没有外出申请的审批" → `approval list-pending --query 外出申请` - 示例："待审批"（无关键词）→ `approval list-pending` 用户说"审批详情/看审批" → `approval detail` +用户说"下载审批附件/获取审批附件下载链接" → `approval attachment download-url`（需 --instance-id 和 --file-id；评论附件增加 --with-comment-attachment） +用户说"授权下载审批钉盘文件/批量开通附件下载权限" → `approval attachment authorize-download`（需 --file-infos，最多 10 项） +用户说"预览审批附件/批量授权预览附件" → `approval attachment authorize-preview`（需 --instance-id 和 --file-ids，最多 20 项；评论附件增加 --with-comment-attachment） 用户说"同意审批/批准" → 先 `tasks` 获取 taskId，再 `approve` 用户说"拒绝审批/驳回" → 先 `tasks` 获取 taskId，再 `reject` 用户说"撤回审批/取消审批" → `approval revoke` diff --git a/test/unit/oa_attachment_delivery_policy_test.go b/test/unit/oa_attachment_delivery_policy_test.go new file mode 100644 index 00000000..32af42ec --- /dev/null +++ b/test/unit/oa_attachment_delivery_policy_test.go @@ -0,0 +1,64 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package unit_test + +import ( + "os" + "path/filepath" + "runtime" + "strings" + "testing" +) + +func TestCrossPlatformCoverageOAAttachmentDeliveryPolicy(t *testing.T) { + _, filename, _, ok := runtime.Caller(0) + if !ok { + t.Fatal("runtime.Caller(0) failed") + } + root := filepath.Clean(filepath.Join(filepath.Dir(filename), "..", "..")) + + attachmentFile := filepath.Join(root, "internal", "helpers", "oa_attachment.go") + if _, err := os.Stat(attachmentFile); !os.IsNotExist(err) { + t.Fatalf("OA attachment commands must live in internal/helpers/oa.go; separate file still exists: %s", attachmentFile) + } + + oaSourcePath := filepath.Join(root, "internal", "helpers", "oa.go") + oaSource, err := os.ReadFile(oaSourcePath) + if err != nil { + t.Fatalf("read %s: %v", oaSourcePath, err) + } + for _, required := range []string{ + "func newOAAttachmentCommand()", + `Tool: "get_attachment_download_url"`, + `Tool: "auth_download_file"`, + `Tool: "auth_preview_attachment"`, + } { + if !strings.Contains(string(oaSource), required) { + t.Errorf("%s missing attachment declaration %q", oaSourcePath, required) + } + } + + docPaths := []string{ + filepath.Join(root, "skills", "mono", "references", "products", "oa.md"), + filepath.Join(root, "skills", "multi", "dingtalk-misc", "references", "oa.md"), + } + for _, docPath := range docPaths { + doc, err := os.ReadFile(docPath) + if err != nil { + t.Fatalf("read %s: %v", docPath, err) + } + for _, required := range []string{ + "dws oa approval attachment download-url", + "dws oa approval attachment authorize-download", + "dws oa approval attachment authorize-preview", + "临时下载链接", + "最多 10", + "最多 20", + } { + if !strings.Contains(string(doc), required) { + t.Errorf("%s missing OA attachment Skill guidance %q", docPath, required) + } + } + } +} From 89027aa2e2829bd806fde93a7889ef9a6eb8990e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Mon, 17 Aug 2026 14:05:14 +0800 Subject: [PATCH 156/250] fix(recruit): distinguish business failures and unwrap once to #85340676 --- internal/helpers/recruit.go | 30 +++++++--- internal/helpers/recruit_test.go | 95 +++++++++++++++++++++++++------- 2 files changed, 96 insertions(+), 29 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index fae5c5b1..ec333736 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -5,6 +5,7 @@ package helpers import ( "encoding/json" + "errors" "fmt" "os" "strconv" @@ -153,6 +154,12 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou } clean, err := recruitBusinessResultData(data, tool) if err != nil { + var businessFailure *recruitBusinessFailure + if errors.As(err, &businessFailure) { + return output.Failure(&output.ErrorInfo{ + Type: "api", Message: businessFailure.Error(), + }), nil + } return recruitInvalidResponse(err), nil } if tool != recruitListJobsTool { @@ -165,6 +172,14 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou return output.Success(listData, output.WithMeta(meta)), nil } +type recruitBusinessFailure struct { + message string +} + +func (e *recruitBusinessFailure) Error() string { + return e.message +} + func recruitBusinessResultData(data any, tool string) (map[string]any, error) { object, ok := data.(map[string]any) if !ok { @@ -187,7 +202,7 @@ func recruitBusinessResultData(data any, tool string) (map[string]any, error) { if strings.TrimSpace(message) == "" { message = "Connector 返回 success=false" } - return nil, fmt.Errorf("%s 调用失败: %s", tool, message) + return nil, &recruitBusinessFailure{message: fmt.Sprintf("%s 调用失败: %s", tool, message)} } result, ok := resultValue.(map[string]any) if !ok { @@ -204,14 +219,13 @@ func recruitInvalidResponse(err error) output.CommandResult { } func recruitListResultData(data any) (any, *output.Meta, error) { - object, err := recruitBusinessResultData(data, recruitListJobsTool) - if err != nil { - return nil, nil, err + object, ok := data.(map[string]any) + if !ok { + return nil, nil, fmt.Errorf("%s 返回值必须是 JSON 对象", recruitListJobsTool) } - // The recruit Connector returns the ATS service envelope unchanged: - // {success:true,result:{list:[...],hasMore:false,nextCursor:null}}. - // Keep accepting the historical flattened shape as well, but normalize the - // fixed Connector shape before enforcing the public CLI result contract. + // The Connector envelope has already been removed by recruitResultCall. + // Only normalize the list business payload here so fields named success or + // result inside that payload cannot be mistaken for another envelope. hasMore, ok := object["hasMore"].(bool) if !ok { return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore") diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index a59b4f75..d0492024 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -365,33 +365,32 @@ func TestRecruitListResultData(t *testing.T) { t.Fatalf("terminal meta = %#v, err = %v", terminal, err) } - wrapped, wrappedMeta, err := recruitListResultData(map[string]any{ - "success": true, - "result": map[string]any{ - "list": []any{map[string]any{"jobId": "job-2", "name": "测试工程师"}}, - "hasMore": false, - "nextCursor": nil, - "totalCount": float64(1), - }, + normalized, normalizedMeta, err := recruitListResultData(map[string]any{ + "list": []any{map[string]any{"jobId": "job-2", "name": "测试工程师"}}, + "hasMore": false, + "nextCursor": nil, + "totalCount": float64(1), + "success": true, + "result": map[string]any{"source": "business-payload"}, }) if err != nil { t.Fatal(err) } - wrappedData := wrapped.(map[string]any) - jobs, ok := wrappedData["jobs"].([]any) - if !ok || len(jobs) != 1 || wrappedData["totalCount"] != float64(1) { - t.Fatalf("wrapped data = %#v", wrappedData) + normalizedData := normalized.(map[string]any) + jobs, ok := normalizedData["jobs"].([]any) + if !ok || len(jobs) != 1 || normalizedData["totalCount"] != float64(1) { + t.Fatalf("normalized data = %#v", normalizedData) } - if _, exists := wrappedData["list"]; exists { - t.Fatalf("wrapped data retained Connector list field: %#v", wrappedData) + if _, exists := normalizedData["list"]; exists { + t.Fatalf("normalized data retained Connector list field: %#v", normalizedData) } - if wrappedMeta.Count == nil || *wrappedMeta.Count != 1 || !wrappedMeta.Pagination.EndpointExhausted { - t.Fatalf("wrapped meta = %#v", wrappedMeta) + if normalizedData["success"] != true || !reflect.DeepEqual( + normalizedData["result"], map[string]any{"source": "business-payload"}, + ) { + t.Fatalf("business success/result fields were unwrapped: %#v", normalizedData) } - - if _, _, err := recruitListResultData(map[string]any{"success": true, "result": nil}); err == nil || - !strings.Contains(err.Error(), "result 必须是 JSON 对象") { - t.Fatalf("nil result error = %v", err) + if normalizedMeta.Count == nil || *normalizedMeta.Count != 1 || !normalizedMeta.Pagination.EndpointExhausted { + t.Fatalf("normalized meta = %#v", normalizedMeta) } } @@ -531,9 +530,63 @@ func TestRecruitBusinessResultDataRejectsInvalidConnectorEnvelope(t *testing.T) {name: "invalid result", data: map[string]any{"success": true, "result": nil}, want: "result 必须是 JSON 对象"}, } { t.Run(test.name, func(t *testing.T) { - if _, err := recruitBusinessResultData(test.data, recruitGetJobTool); err == nil || !strings.Contains(err.Error(), test.want) { + _, err := recruitBusinessResultData(test.data, recruitGetJobTool) + if err == nil || !strings.Contains(err.Error(), test.want) { t.Fatalf("error = %v, want %q", err, test.want) } + var businessFailure *recruitBusinessFailure + isBusinessFailure := stderrors.As(err, &businessFailure) + wantBusinessFailure := strings.HasPrefix(test.name, "business failure") + if isBusinessFailure != wantBusinessFailure { + t.Fatalf("business failure classification = %t, want %t", isBusinessFailure, wantBusinessFailure) + } + }) + } +} + +func TestRecruitResultCallClassifiesBusinessAndMalformedFailures(t *testing.T) { + for _, test := range []struct { + name string + text string + wantSubtype string + wantMessage string + wantHint bool + }{ + { + name: "business failure", + text: `{"success":false,"message":"职位不存在","result":{}}`, + wantMessage: "职位不存在", + }, + { + name: "malformed envelope", + text: `{"success":true}`, + wantSubtype: "invalid_response", + wantMessage: "同时包含 success 和 result", + wantHint: true, + }, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = test.text + cmd := prepareRecruitTestCommand(newRecruitJobGetCommand()) + result, err := recruitResultCall(cmd, recruitGetJobTool, map[string]any{"jobId": "job-1"}) + if err != nil { + t.Fatal(err) + } + envelope, err := output.EnvelopeFromResult(result) + if err != nil { + t.Fatal(err) + } + if envelope.Outcome != output.OutcomeFailure || envelope.Error == nil { + t.Fatalf("envelope = %#v", envelope) + } + if envelope.Error.Type != "api" || envelope.Error.Subtype != test.wantSubtype || + !strings.Contains(envelope.Error.Message, test.wantMessage) { + t.Fatalf("error = %#v", envelope.Error) + } + if (envelope.Error.Hint != "") != test.wantHint { + t.Fatalf("hint = %q, want present %t", envelope.Error.Hint, test.wantHint) + } }) } } From fe2f3ca92f92cda08453da4b7bf05e9f5430c4a2 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 11:57:41 +0800 Subject: [PATCH 157/250] fix: harden aitable pagination and minutes unshare --- internal/app/param_alias_e2e_test.go | 2 + internal/shortcut/aitable/aitable.go | 2 +- internal/shortcut/aitable/record_batch.go | 45 +++-- internal/shortcut/aitable/record_query_all.go | 127 +++++++++++++- .../aitable/record_upsert_by_key_e2e_test.go | 164 +++++++++++++++++- internal/shortcut/minutes/workflows.go | 17 +- .../minutes/workflows_coverage_test.go | 21 ++- .../minutesdata/coverage_completion_test.go | 16 ++ internal/shortcut/minutesdata/workflow.go | 55 ++++++ 9 files changed, 432 insertions(+), 17 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 4717d2b1..71298e27 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -52,6 +52,8 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string switch tool { case "list_calendar_events": return `{"result":{"events":[]}}` + case "query_records": + return `{"success":true,"status":"success","error":{},"data":{}}` case "search_mail_users": return `{"users":[{"name":"Fixture User","email":"fixture@example.com","id":"fixture-user"}]}` case "search_dept_by_keyword": diff --git a/internal/shortcut/aitable/aitable.go b/internal/shortcut/aitable/aitable.go index 0077dda9..2d1a9d64 100644 --- a/internal/shortcut/aitable/aitable.go +++ b/internal/shortcut/aitable/aitable.go @@ -733,7 +733,7 @@ var RecordQuery = shortcut.Shortcut{ if rt.Changed("cursor") { params["cursor"] = rt.Str("cursor") } - return rt.CallMCP("query_records", params) + return executeRecordQuery(rt, params) }, } diff --git a/internal/shortcut/aitable/record_batch.go b/internal/shortcut/aitable/record_batch.go index 8c26c3b1..05294ad3 100644 --- a/internal/shortcut/aitable/record_batch.go +++ b/internal/shortcut/aitable/record_batch.go @@ -98,7 +98,7 @@ func executeRecordDeleteBatches(rt *shortcut.RuntimeContext) error { step.Status = "unknown" step.Error = writeErr.Error() } - remaining, verifyErr := queryRecordsByIDs(rt, baseID, tableID, batch) + remaining, verifyErr := queryDeletedRecordsByIDs(rt, baseID, tableID, batch) if verifyErr == nil && len(remaining) > 0 { verifyErr = fmt.Errorf("read-back still contains deleted record IDs: %s", strings.Join(recordIDs(remaining), ",")) } @@ -303,20 +303,43 @@ func verifyUpsertBatch(rt *shortcut.RuntimeContext, baseID, tableID string, batc } func queryRecordsByIDs(rt *shortcut.RuntimeContext, baseID, tableID string, ids []string) ([]map[string]any, error) { - data, err := rt.CallMCPData(serverMain, "query_records", map[string]any{ - "baseId": baseID, "tableId": tableID, "recordIds": ids, "limit": len(ids), - }) + window, err := queryRecordWindow(rt, map[string]any{ + "baseId": baseID, "tableId": tableID, "recordIds": ids, + }, len(ids)) if err != nil { return nil, err } - records, found := findRecords(data) - if !found { - return nil, fmt.Errorf("query_records read-back is missing records") + // Exact-ID verification below compares every requested ID with the returned + // records. The service can publish a continuation even after all requested + // IDs are present, so hasMore is not evidence that this bounded read-back is + // incomplete. + return window.Records, nil +} + +func queryDeletedRecordsByIDs(rt *shortcut.RuntimeContext, baseID, tableID string, ids []string) ([]map[string]any, error) { + remaining := make([]map[string]any, 0) + for offset := 0; offset < len(ids); offset += recordQueryServicePageSize { + end := minInt(offset+recordQueryServicePageSize, len(ids)) + chunk := ids[offset:end] + data, err := rt.CallMCPData(serverMain, "query_records", map[string]any{ + "baseId": baseID, "tableId": tableID, "recordIds": chunk, "limit": len(chunk), + }) + if err != nil { + return nil, err + } + records, found := findRecords(data) + if !found { + if explicitEmptyRecordQuery(data) { + continue + } + return nil, fmt.Errorf("query_records deletion read-back chunk %d is missing records", offset/recordQueryServicePageSize+1) + } + if responseHasMore(data) { + return nil, fmt.Errorf("query_records deletion read-back chunk %d is incomplete", offset/recordQueryServicePageSize+1) + } + remaining = append(remaining, records...) } - if responseHasMore(data) { - return nil, fmt.Errorf("query_records read-back is incomplete") - } - return records, nil + return remaining, nil } func recordIDs(records []map[string]any) []string { diff --git a/internal/shortcut/aitable/record_query_all.go b/internal/shortcut/aitable/record_query_all.go index 0606abba..fa2c2368 100644 --- a/internal/shortcut/aitable/record_query_all.go +++ b/internal/shortcut/aitable/record_query_all.go @@ -10,13 +10,138 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) +// query_records is backed by a service pager whose stable typed-envelope +// boundary is 20 records. Asking that layer to aggregate more than one page can +// drop the envelope fields used by the record projector, turning a successful +// read into an empty collection. Keep every remote request on one service page +// and aggregate only after each page has passed the CLI's shape validation. +const recordQueryServicePageSize = 20 + +type recordQueryWindow struct { + Records []map[string]any + HasMore bool + NextCursor string + Pages int +} + +func queryRecordWindow(rt *shortcut.RuntimeContext, params map[string]any, limit int) (recordQueryWindow, error) { + if limit <= 0 { + return recordQueryWindow{}, fmt.Errorf("record query limit must be positive, got %d", limit) + } + request := cloneAnyMap(params) + cursor, _ := request["cursor"].(string) + cursor = strings.TrimSpace(cursor) + seen := map[string]bool{} + if cursor != "" { + seen[cursor] = true + } + window := recordQueryWindow{Records: make([]map[string]any, 0, limit)} + + for len(window.Records) < limit { + pageSize := minInt(recordQueryServicePageSize, limit-len(window.Records)) + request["limit"] = pageSize + if cursor == "" { + delete(request, "cursor") + } else { + request["cursor"] = cursor + } + data, err := rt.CallMCPData(serverMain, "query_records", request) + if err != nil { + return recordQueryWindow{}, err + } + records, found := findRecords(data) + if !found { + if explicitEmptyRecordQuery(data) { + window.Pages++ + window.HasMore = false + window.NextCursor = "" + return window, nil + } + return recordQueryWindow{}, fmt.Errorf("query_records page %d is missing the records collection", window.Pages+1) + } + window.Records = append(window.Records, records...) + window.Pages++ + + if !responseHasMore(data) { + window.HasMore = false + window.NextCursor = "" + return window, nil + } + next := responseCursor(data) + if next == "" { + return recordQueryWindow{}, fmt.Errorf("query_records page %d reports more data but no next cursor", window.Pages) + } + if seen[next] { + return recordQueryWindow{}, fmt.Errorf("query_records cursor cycle detected at %q", next) + } + seen[next] = true + cursor = next + window.HasMore = true + window.NextCursor = next + } + + return window, nil +} + +// explicitEmptyRecordQuery recognizes the service's reviewed zero-match wire +// shape. It is deliberately stricter than "records is absent": only a complete +// success envelope with an empty data object is accepted as an empty set. +func explicitEmptyRecordQuery(data map[string]any) bool { + if data == nil || data["success"] != true || data["status"] != "success" { + return false + } + payload, ok := data["data"].(map[string]any) + if !ok || len(payload) != 0 { + return false + } + if rawError, exists := data["error"]; exists && rawError != nil { + errorObject, ok := rawError.(map[string]any) + if !ok || len(errorObject) != 0 { + return false + } + } + return true +} + +func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) error { + limit := 100 + if rt.Changed("limit") { + limit = rt.Int("limit") + } + if limit < 1 || limit > recordBatchSize { + return fmt.Errorf("--limit must be in [1,%d], got %d", recordBatchSize, limit) + } + window, err := queryRecordWindow(rt, params, limit) + if err != nil { + return err + } + records := make([]any, 0, len(window.Records)) + for _, record := range window.Records { + records = append(records, record) + } + data := map[string]any{ + "records": records, + "hasMore": window.HasMore, + "page": window.Pages, + "size": len(window.Records), + } + if window.NextCursor != "" { + data["nextCursor"] = window.NextCursor + } + return rt.Output(map[string]any{ + "success": true, + "status": "success", + "data": data, + }) +} + func queryAllRecords(rt *shortcut.RuntimeContext, params map[string]any, maxRecords int) ([]map[string]any, error) { all := make([]map[string]any, 0) cursor := "" seen := map[string]bool{} for page := 0; ; page++ { request := cloneAnyMap(params) - request["limit"] = recordBatchSize + request["limit"] = recordQueryServicePageSize if cursor != "" { request["cursor"] = cursor } diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 64bf759a..4744fbe1 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -265,6 +265,149 @@ func recordListJSON(t *testing.T, records []map[string]any) string { return string(raw) } +func pagedRecordQueryResponse(t *testing.T, records []map[string]any, args map[string]any) string { + t.Helper() + limit, ok := args["limit"].(int) + if !ok || limit < 1 || limit > recordQueryServicePageSize { + t.Fatalf("query_records limit = %#v, want 1..%d", args["limit"], recordQueryServicePageSize) + } + offset := 0 + if cursor, _ := args["cursor"].(string); cursor != "" { + if _, err := fmt.Sscanf(cursor, "offset-%d", &offset); err != nil { + t.Fatalf("invalid test cursor %q: %v", cursor, err) + } + } + end := minInt(offset+limit, len(records)) + pageRecords := records[offset:end] + data := map[string]any{"records": pageRecords, "hasMore": end < len(records)} + if end < len(records) { + data["nextCursor"] = fmt.Sprintf("offset-%d", end) + } + raw, err := json.Marshal(map[string]any{ + "success": true, + "hasMore": end < len(records), + "page": offset/recordQueryServicePageSize + 1, + "size": limit, + "data": data, + }) + if err != nil { + t.Fatal(err) + } + return string(raw) +} + +func runRecordQueryShortcutCLI(t *testing.T, caller *upsertByKeyCaller, limit int) (map[string]any, error) { + t.Helper() + helpers.InitDepsForTest(t, caller) + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + root.PersistentFlags().Bool("yes", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.PersistentFlags().String("format", "json", "") + root.AddCommand(shortcut.Commands()...) + stdout := &bytes.Buffer{} + root.SetOut(stdout) + root.SetErr(&bytes.Buffer{}) + root.SetArgs([]string{"aitable", "+record-query", "--base-id", "base", "--table-id", "table", "--limit", fmt.Sprint(limit)}) + err := root.Execute() + if stdout.Len() == 0 { + return nil, err + } + var payload map[string]any + if decodeErr := json.Unmarshal(stdout.Bytes(), &payload); decodeErr != nil { + t.Fatalf("decode record query output %q: %v", stdout.String(), decodeErr) + } + return payload, err +} + +func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) { + for _, size := range []int{20, 21, 22, 100} { + t.Run(fmt.Sprintf("size_%d", size), func(t *testing.T) { + records := updateFixtureRecords(0, size, "可见") + caller := &upsertByKeyCaller{} + caller.callFn = func(_ int, _, tool string, args map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + return pagedRecordQueryResponse(t, records, args), nil + } + payload, err := runRecordQueryShortcutCLI(t, caller, size) + if err != nil { + t.Fatalf("record query size %d: %v", size, err) + } + data, ok := payload["data"].(map[string]any) + if !ok || payload["success"] != true || data["hasMore"] != false || len(data["records"].([]any)) != size { + t.Fatalf("record query size %d payload = %#v", size, payload) + } + wantCalls := (size + recordQueryServicePageSize - 1) / recordQueryServicePageSize + if len(caller.calls) != wantCalls || data["page"] != float64(wantCalls) || data["size"] != float64(size) { + t.Fatalf("record query size %d calls=%d payload=%#v, want calls=%d", size, len(caller.calls), payload, wantCalls) + } + }) + } +} + +func TestCrossPlatformCoverageRecordWriteReadbackUsesStableServicePagesE2E(t *testing.T) { + for _, operation := range []string{"update", "upsert", "delete"} { + for _, size := range []int{21, 22, 100} { + t.Run(fmt.Sprintf("%s_%d", operation, size), func(t *testing.T) { + records := updateFixtureRecords(0, size, "完成") + caller := &upsertByKeyCaller{} + queryCalls := 0 + caller.callFn = func(_ int, _, tool string, args map[string]any) (string, error) { + if tool != "query_records" { + return `{"success":true}`, nil + } + queryCalls++ + if operation == "delete" { + ids := args["recordIds"].([]string) + empty := make([]map[string]any, len(ids)) + response := pagedRecordQueryResponse(t, empty, args) + var payload map[string]any + if err := json.Unmarshal([]byte(response), &payload); err != nil { + t.Fatal(err) + } + page := payload["data"].(map[string]any) + page["records"] = []any{} + raw, _ := json.Marshal(payload) + return string(raw), nil + } + response := pagedRecordQueryResponse(t, records, args) + var payload map[string]any + if err := json.Unmarshal([]byte(response), &payload); err != nil { + t.Fatal(err) + } + page := payload["data"].(map[string]any) + if len(page["records"].([]any))+recordQueryServicePageSize*(queryCalls-1) >= size { + // The live service can retain a continuation after it has + // returned every requested record ID. Exact-ID verification + // must use ID coverage, not this advisory bit. + page["hasMore"] = true + page["nextCursor"] = "ignored-after-complete-id-set" + payload["hasMore"] = true + } + raw, _ := json.Marshal(payload) + return string(raw), nil + } + + var out string + var err error + if operation == "delete" { + out, err = runRecordDeleteCLI(t, caller, recordIDs(records)) + } else { + out, err = runRecordBatchCLI(t, caller, "+record-"+operation, records) + } + if err != nil || out == "" { + t.Fatalf("%s size %d false negative: output=%q err=%v", operation, size, out, err) + } + wantQueries := (size + recordQueryServicePageSize - 1) / recordQueryServicePageSize + if queryCalls != wantQueries { + t.Fatalf("%s size %d query calls=%d, want %d", operation, size, queryCalls, wantQueries) + } + }) + } + } +} + func TestCrossPlatformCoverageRecordUpdateAutoChunksAndVerifiesE2E(t *testing.T) { records := updateFixtureRecords(0, 101, "完成") caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ @@ -395,6 +538,10 @@ func TestCrossPlatformCoverageRecordDeleteAutoChunksAndProvesAbsenceE2E(t *testi caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ {text: `{"deletedCount":100}`}, {text: `{"data":{"records":[]}}`}, + {text: `{"data":{"records":[]}}`}, + {text: `{"data":{"records":[]}}`}, + {text: `{"data":{"records":[]}}`}, + {text: `{"data":{"records":[]}}`}, {text: `{"deletedCount":1}`}, {text: `{"data":{"records":[]}}`}, }} @@ -407,7 +554,7 @@ func TestCrossPlatformCoverageRecordDeleteAutoChunksAndProvesAbsenceE2E(t *testi t.Fatalf("delete output missing %s: %s", want, out) } } - if len(caller.calls) != 4 || caller.calls[0].tool != "delete_records" || caller.calls[1].tool != "query_records" { + if len(caller.calls) != 8 || caller.calls[0].tool != "delete_records" || caller.calls[1].tool != "query_records" || caller.calls[6].tool != "delete_records" { t.Fatalf("delete call sequence = %#v", caller.calls) } } @@ -421,6 +568,17 @@ func TestCrossPlatformCoverageRecordDeleteEmptyReplyRecoveredOnlyByAbsenceE2E(t } }) + t.Run("explicit service success with empty data proves deletion", func(t *testing.T) { + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: `{"deletedCount":1}`}, + {text: `{"success":true,"status":"success","error":{},"data":{}}`}, + }} + out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) + if err != nil || !strings.Contains(out, `"status": "verified_absent"`) { + t.Fatalf("delete explicit empty success = output:%q err:%v", out, err) + } + }) + t.Run("missing records contract is unknown", func(t *testing.T) { caller := &upsertByKeyCaller{steps: []upsertByKeyStep{{text: `{"deletedCount":1}`}, {text: `{"data":{}}`}}} out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) @@ -450,6 +608,10 @@ func TestCrossPlatformCoverageRecordDeletePartialCheckpointE2E(t *testing.T) { caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ {text: `{"deletedCount":100}`}, {text: `{"records":[]}`}, + {text: `{"records":[]}`}, + {text: `{"records":[]}`}, + {text: `{"records":[]}`}, + {text: `{"records":[]}`}, {text: `{"deletedCount":0}`}, {text: `{"records":[{"recordId":"r100","cells":{}}]}`}, }} diff --git a/internal/shortcut/minutes/workflows.go b/internal/shortcut/minutes/workflows.go index 68c11c8e..e9a44456 100644 --- a/internal/shortcut/minutes/workflows.go +++ b/internal/shortcut/minutes/workflows.go @@ -614,6 +614,17 @@ func executeMinutesShare(rt *shortcut.RuntimeContext) error { } func executeMinutesUnshare(rt *shortcut.RuntimeContext) error { + if !rt.DryRun() { + for _, id := range minutesIDs(rt) { + data, err := rt.CallMCPData("minutes", "get_minutes_basic_info", map[string]any{"taskUuid": id}) + if err != nil { + return fmt.Errorf("minutes unshare preflight for %s: %w", id, err) + } + if _, err := minutesdata.Basic(id, data); err != nil { + return fmt.Errorf("minutes unshare preflight for %s: %w", id, err) + } + } + } return executeMinutesPermissionLedger(rt, "unshare", "remove_member_permission", func(member string) map[string]any { return map[string]any{"uuids": minutesIDs(rt), "memberUids": []string{member}} }) @@ -631,7 +642,11 @@ func executeMinutesPermissionLedger(rt *shortcut.RuntimeContext, operation, tool for index, member := range members { data, err := rt.CallMCPWriteDataStrict("minutes", tool, params(member)) if err == nil { - err = minutesdata.RequireWriteAcknowledgement(operation, data) + if operation == "unshare" { + err = minutesdata.RequirePermissionMutationAcknowledgement(operation, minutesIDs(rt), []string{member}, data) + } else { + err = minutesdata.RequireWriteAcknowledgement(operation, data) + } } if err != nil { failures = append(failures, map[string]any{"memberUid": member, "error": err.Error()}) diff --git a/internal/shortcut/minutes/workflows_coverage_test.go b/internal/shortcut/minutes/workflows_coverage_test.go index aa05eb6d..f94f5e1a 100644 --- a/internal/shortcut/minutes/workflows_coverage_test.go +++ b/internal/shortcut/minutes/workflows_coverage_test.go @@ -323,7 +323,10 @@ func TestCrossPlatformCoverageMinutesPermissionLedgerBranchesE2E(t *testing.T) { if err := runMinutesAlignmentCLIWithWriter(t, &minutesE2ECaller{}, minutesFailWriter{}, "minutes", "+unshare", "--id", "u1", "--member-uids", "m1", "--dry-run"); err == nil { t.Fatal("unshare dry-run output failure accepted") } - unshare := &minutesE2ECaller{responses: map[string][]string{"minutes/remove_member_permission": {`{"success":true,"result":{}}`}}} + unshare := &minutesE2ECaller{responses: map[string][]string{ + "minutes/get_minutes_basic_info": {`{"success":true,"result":{"taskUuid":"u1"}}`}, + "minutes/remove_member_permission": {`{"success":true,"result":{"resultMap":{"u1":["m1"]}}}`}, + }} payload, _, err := runMinutesAlignmentCLI(t, unshare, "minutes", "+unshare", "--id", "u1", "--member-uids", "m1", "--yes") if err != nil || payload["complete"] != true || payload["succeeded"] != float64(1) { t.Fatalf("unshare payload=%#v err=%v", payload, err) @@ -337,11 +340,25 @@ func TestCrossPlatformCoverageMinutesPermissionLedgerBranchesE2E(t *testing.T) { if args["coverPermission"] != "true" || len(args["roleSubResourceIds"].([]string)) != 2 { t.Fatalf("share args=%#v", args) } - continueFailure := &minutesE2ECaller{responses: map[string][]string{"minutes/remove_member_permission": {`{"result":{}}`, `{"success":true,"result":{}}`}}} + continueFailure := &minutesE2ECaller{responses: map[string][]string{ + "minutes/get_minutes_basic_info": {`{"success":true,"result":{"taskUuid":"u1"}}`}, + "minutes/remove_member_permission": { + `{"result":{}}`, + `{"success":true,"result":{"resultMap":{"u1":["m2"]}}}`, + }, + }} payload, output, err := runMinutesAlignmentCLI(t, continueFailure, "minutes", "+unshare", "--id", "u1", "--member-uids", "m1,m2", "--failure-policy", "continue", "--yes") if err == nil || output == "" || payload["failed"] != float64(1) || payload["succeeded"] != float64(1) { t.Fatalf("continue ledger payload=%#v err=%v", payload, err) } + + missing := &minutesE2ECaller{responses: map[string][]string{ + "minutes/get_minutes_basic_info": {`{"success":true,"result":{}}`}, + }} + payload, output, err = runMinutesAlignmentCLI(t, missing, "minutes", "+unshare", "--id", "missing", "--member-uids", "m1", "--yes") + if err == nil || payload != nil || output != "" || missing.counts["minutes/remove_member_permission"] != 0 { + t.Fatalf("missing minutes reached unshare: payload=%#v output=%q err=%v calls=%#v", payload, output, err, missing.counts) + } } func TestCrossPlatformCoverageMinutesArtifactCollectorBranches(t *testing.T) { diff --git a/internal/shortcut/minutesdata/coverage_completion_test.go b/internal/shortcut/minutesdata/coverage_completion_test.go index e4d53737..d8b85dcb 100644 --- a/internal/shortcut/minutesdata/coverage_completion_test.go +++ b/internal/shortcut/minutesdata/coverage_completion_test.go @@ -224,6 +224,22 @@ func TestCrossPlatformCoverageMinutesWorkflowCompletion(t *testing.T) { if err := RequireWriteAcknowledgement("write", map[string]any{"result": map[string]any{"updated": true}}); err != nil { t.Fatal(err) } + if err := RequirePermissionMutationAcknowledgement("unshare", []string{"u1"}, []string{"202397"}, map[string]any{ + "success": true, + "result": map[string]any{"resultMap": map[string]any{"u1": []any{float64(202397)}}}, + }); err != nil { + t.Fatalf("valid permission acknowledgement rejected: %v", err) + } + for _, data := range []map[string]any{ + {"success": true, "result": map[string]any{}}, + {"success": true, "result": map[string]any{"resultMap": map[string]any{}}}, + {"success": true, "result": map[string]any{"resultMap": map[string]any{"other": []any{"202397"}}}}, + {"success": true, "result": map[string]any{"resultMap": map[string]any{"u1": []any{"other"}}}}, + } { + if err := RequirePermissionMutationAcknowledgement("unshare", []string{"u1"}, []string{"202397"}, data); err == nil { + t.Fatalf("invalid permission acknowledgement accepted: %#v", data) + } + } for _, tc := range []struct { cmd, id string data map[string]any diff --git a/internal/shortcut/minutesdata/workflow.go b/internal/shortcut/minutesdata/workflow.go index 6cfd1347..4ffc9a83 100644 --- a/internal/shortcut/minutesdata/workflow.go +++ b/internal/shortcut/minutesdata/workflow.go @@ -30,6 +30,61 @@ func RequireWriteAcknowledgement(operation string, data map[string]any) error { return fmt.Errorf("minutes %s response has no explicit successful acknowledgement", operation) } +// RequirePermissionMutationAcknowledgement validates the target-level payload +// returned by add/remove_member_permission. The backend's top-level +// success=true is not sufficient: historically it also accompanied a +// resultMap that merely echoed nonexistent task UUIDs. +func RequirePermissionMutationAcknowledgement(operation string, taskUUIDs, memberUIDs []string, data map[string]any) error { + if err := validateEnvelope(data); err != nil { + return err + } + if success, ok := data["success"].(bool); !ok || !success { + return fmt.Errorf("minutes %s response has no explicit success=true", operation) + } + result, ok := data["result"].(map[string]any) + if !ok { + return fmt.Errorf("minutes %s response has no result object", operation) + } + resultMap, ok := result["resultMap"].(map[string]any) + if !ok { + return fmt.Errorf("minutes %s response has no result.resultMap object", operation) + } + if len(resultMap) != len(taskUUIDs) { + return fmt.Errorf("minutes %s resultMap covers %d task UUIDs, want %d", operation, len(resultMap), len(taskUUIDs)) + } + wantMembers := make(map[string]bool, len(memberUIDs)) + for _, member := range memberUIDs { + wantMembers[strings.TrimSpace(member)] = true + } + for _, taskUUID := range taskUUIDs { + rawMembers, exists := resultMap[taskUUID] + if !exists { + return fmt.Errorf("minutes %s resultMap is missing task UUID %s", operation, taskUUID) + } + members, ok := rawMembers.([]any) + if !ok { + return fmt.Errorf("minutes %s resultMap[%s] has type %T, want array", operation, taskUUID, rawMembers) + } + gotMembers := make(map[string]bool, len(members)) + for index, member := range members { + value := stringField(map[string]any{"member": member}, "member") + if value == "" { + return fmt.Errorf("minutes %s resultMap[%s][%d] is not a member UID", operation, taskUUID, index) + } + gotMembers[value] = true + } + if len(gotMembers) != len(wantMembers) { + return fmt.Errorf("minutes %s resultMap[%s] member coverage mismatch", operation, taskUUID) + } + for member := range wantMembers { + if !gotMembers[member] { + return fmt.Errorf("minutes %s resultMap[%s] is missing member UID %s", operation, taskUUID, member) + } + } + } + return nil +} + // RecordResult validates the gateway's observed listening-note command result. func RecordResult(expectedCmd, taskUUID string, data map[string]any) (map[string]any, error) { if err := RequireWriteAcknowledgement("record "+expectedCmd, data); err != nil { From e14de2b4c20ad4f9fc1b0a8f566e4d3b34c88395 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 15:41:42 +0800 Subject: [PATCH 158/250] test: close shortcut fix review gates --- ...1006-aitable-pagination-minutes-unshare.md | 9 ++ .../aitable/record_upsert_by_key_e2e_test.go | 111 ++++++++++++++++++ .../minutes/workflows_coverage_test.go | 6 + .../minutesdata/coverage_completion_test.go | 10 ++ 4 files changed, 136 insertions(+) create mode 100644 .changes/1006-aitable-pagination-minutes-unshare.md diff --git a/.changes/1006-aitable-pagination-minutes-unshare.md b/.changes/1006-aitable-pagination-minutes-unshare.md new file mode 100644 index 00000000..8ca97c30 --- /dev/null +++ b/.changes/1006-aitable-pagination-minutes-unshare.md @@ -0,0 +1,9 @@ +--- +category: Fixed +--- + +- **Aitable pagination and Minutes unshare verification** (#1006) — keeps + record queries on the service's 20-record page boundary so multi-page reads + and mutation readbacks no longer report false retryable failures, and rejects + Minutes unshare success until the listening note exists and the service + acknowledges the exact task and member targets. diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 4744fbe1..3a639b6e 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -346,6 +346,117 @@ func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) } } +func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testing.T) { + t.Run("non-positive window limit", func(t *testing.T) { + caller := &upsertByKeyCaller{} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + if _, err := queryRecordWindow(rt, nil, 0); err == nil { + t.Fatal("non-positive record query window limit accepted") + } + }) + + t.Run("initial cursor cycle", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, _ map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + return `{"success":true,"data":{"records":[{"recordId":"r1"}],"hasMore":true,"nextCursor":"seed"}}`, nil + }} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + if _, err := queryRecordWindow(rt, map[string]any{"cursor": " seed "}, 2); err == nil || !strings.Contains(err.Error(), "cursor cycle") { + t.Fatalf("initial cursor cycle error = %v", err) + } + }) + + t.Run("strict explicit empty shape", func(t *testing.T) { + for _, data := range []map[string]any{ + {"success": true, "status": "success", "data": map[string]any{"unexpected": true}}, + {"success": true, "status": "success", "data": map[string]any{}, "error": "bad"}, + } { + if explicitEmptyRecordQuery(data) { + t.Fatalf("invalid empty-query envelope accepted: %#v", data) + } + } + }) + + t.Run("explicit empty page", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, _ string, _ map[string]any) (string, error) { + return `{"success":true,"status":"success","error":{},"data":{}}`, nil + }} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + window, err := queryRecordWindow(rt, map[string]any{}, 1) + if err != nil || len(window.Records) != 0 || window.Pages != 1 || window.HasMore || window.NextCursor != "" { + t.Fatalf("explicit empty window=%#v err=%v", window, err) + } + }) + + t.Run("missing records collection", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, _ string, _ map[string]any) (string, error) { + return `{}`, nil + }} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + if _, err := queryRecordWindow(rt, map[string]any{}, 1); err == nil || !strings.Contains(err.Error(), "missing the records collection") { + t.Fatalf("missing records error = %v", err) + } + }) + + t.Run("invalid shortcut limit", func(t *testing.T) { + caller := &upsertByKeyCaller{} + helpers.InitDepsForTest(t, caller) + cmd := &cobra.Command{Use: "query"} + cmd.Flags().Int("limit", 0, "") + if err := cmd.Flags().Set("limit", "0"); err != nil { + t.Fatal(err) + } + rt := shortcut.RuntimeContextForTest(cmd, RecordQuery) + if err := executeRecordQuery(rt, map[string]any{}); err == nil { + t.Fatal("invalid shortcut limit accepted") + } + }) + + t.Run("shortcut query failure", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, _ string, _ map[string]any) (string, error) { + return "", errors.New("query unavailable") + }} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + if err := executeRecordQuery(rt, map[string]any{}); err == nil || !strings.Contains(err.Error(), "query unavailable") { + t.Fatalf("shortcut query failure = %v", err) + } + }) + + t.Run("bounded continuation is published", func(t *testing.T) { + records := updateFixtureRecords(0, 21, "visible") + caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, args map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + return pagedRecordQueryResponse(t, records, args), nil + }} + payload, err := runRecordQueryShortcutCLI(t, caller, 20) + data, _ := payload["data"].(map[string]any) + if err != nil || data["hasMore"] != true || data["nextCursor"] != "offset-20" { + t.Fatalf("bounded continuation payload=%#v err=%v", payload, err) + } + }) + + t.Run("delete readback rejects continuation", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, _ map[string]any) (string, error) { + if tool == "query_records" { + return `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"unexpected"}}`, nil + } + return `{"deletedCount":1}`, nil + }} + if _, err := runRecordDeleteCLI(t, caller, []string{"r1"}); err == nil || len(caller.calls) != 2 || caller.calls[1].tool != "query_records" { + t.Fatalf("delete continuation error = %v calls=%#v", err, caller.calls) + } + }) +} + func TestCrossPlatformCoverageRecordWriteReadbackUsesStableServicePagesE2E(t *testing.T) { for _, operation := range []string{"update", "upsert", "delete"} { for _, size := range []int{21, 22, 100} { diff --git a/internal/shortcut/minutes/workflows_coverage_test.go b/internal/shortcut/minutes/workflows_coverage_test.go index f94f5e1a..c2d7bf43 100644 --- a/internal/shortcut/minutes/workflows_coverage_test.go +++ b/internal/shortcut/minutes/workflows_coverage_test.go @@ -359,6 +359,12 @@ func TestCrossPlatformCoverageMinutesPermissionLedgerBranchesE2E(t *testing.T) { if err == nil || payload != nil || output != "" || missing.counts["minutes/remove_member_permission"] != 0 { t.Fatalf("missing minutes reached unshare: payload=%#v output=%q err=%v calls=%#v", payload, output, err, missing.counts) } + + preflightFailure := &minutesE2ECaller{failAt: map[string]int{"minutes/get_minutes_basic_info": 1}} + payload, output, err = runMinutesAlignmentCLI(t, preflightFailure, "minutes", "+unshare", "--id", "unavailable", "--member-uids", "m1", "--yes") + if err == nil || payload != nil || output != "" || preflightFailure.counts["minutes/remove_member_permission"] != 0 { + t.Fatalf("failed preflight reached unshare: payload=%#v output=%q err=%v calls=%#v", payload, output, err, preflightFailure.counts) + } } func TestCrossPlatformCoverageMinutesArtifactCollectorBranches(t *testing.T) { diff --git a/internal/shortcut/minutesdata/coverage_completion_test.go b/internal/shortcut/minutesdata/coverage_completion_test.go index d8b85dcb..aa2e3cb4 100644 --- a/internal/shortcut/minutesdata/coverage_completion_test.go +++ b/internal/shortcut/minutesdata/coverage_completion_test.go @@ -231,15 +231,25 @@ func TestCrossPlatformCoverageMinutesWorkflowCompletion(t *testing.T) { t.Fatalf("valid permission acknowledgement rejected: %v", err) } for _, data := range []map[string]any{ + {"success": false, "errorMsg": "denied"}, + {"success": true, "result": "bad"}, {"success": true, "result": map[string]any{}}, {"success": true, "result": map[string]any{"resultMap": map[string]any{}}}, {"success": true, "result": map[string]any{"resultMap": map[string]any{"other": []any{"202397"}}}}, + {"success": true, "result": map[string]any{"resultMap": map[string]any{"u1": "bad"}}}, + {"success": true, "result": map[string]any{"resultMap": map[string]any{"u1": []any{nil}}}}, {"success": true, "result": map[string]any{"resultMap": map[string]any{"u1": []any{"other"}}}}, } { if err := RequirePermissionMutationAcknowledgement("unshare", []string{"u1"}, []string{"202397"}, data); err == nil { t.Fatalf("invalid permission acknowledgement accepted: %#v", data) } } + if err := RequirePermissionMutationAcknowledgement("unshare", []string{"u1"}, []string{"202397", "other"}, map[string]any{ + "success": true, + "result": map[string]any{"resultMap": map[string]any{"u1": []any{"202397"}}}, + }); err == nil { + t.Fatal("incomplete member coverage accepted") + } for _, tc := range []struct { cmd, id string data map[string]any From f486105836fdbbc69163123ec9d6e8edfbf225d2 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 16:39:46 +0800 Subject: [PATCH 159/250] fix: bound empty aitable pagination --- internal/shortcut/aitable/record_query_all.go | 17 +++++++++++++++- .../aitable/record_upsert_by_key_e2e_test.go | 20 +++++++++++++++++++ .../minutesdata/coverage_completion_test.go | 1 + 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/internal/shortcut/aitable/record_query_all.go b/internal/shortcut/aitable/record_query_all.go index fa2c2368..bdaffb41 100644 --- a/internal/shortcut/aitable/record_query_all.go +++ b/internal/shortcut/aitable/record_query_all.go @@ -15,7 +15,10 @@ import ( // drop the envelope fields used by the record projector, turning a successful // read into an empty collection. Keep every remote request on one service page // and aggregate only after each page has passed the CLI's shape validation. -const recordQueryServicePageSize = 20 +const ( + recordQueryServicePageSize = 20 + recordQueryMaxConsecutiveEmptyPages = 3 +) type recordQueryWindow struct { Records []map[string]any @@ -36,6 +39,7 @@ func queryRecordWindow(rt *shortcut.RuntimeContext, params map[string]any, limit seen[cursor] = true } window := recordQueryWindow{Records: make([]map[string]any, 0, limit)} + consecutiveEmptyPages := 0 for len(window.Records) < limit { pageSize := minInt(recordQueryServicePageSize, limit-len(window.Records)) @@ -67,6 +71,17 @@ func queryRecordWindow(rt *shortcut.RuntimeContext, params map[string]any, limit window.NextCursor = "" return window, nil } + if len(records) == 0 { + consecutiveEmptyPages++ + if consecutiveEmptyPages >= recordQueryMaxConsecutiveEmptyPages { + return recordQueryWindow{}, fmt.Errorf( + "query_records made no progress for %d consecutive pages", + consecutiveEmptyPages, + ) + } + } else { + consecutiveEmptyPages = 0 + } next := responseCursor(data) if next == "" { return recordQueryWindow{}, fmt.Errorf("query_records page %d reports more data but no next cursor", window.Pages) diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 3a639b6e..d468901a 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -404,6 +404,26 @@ func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testi } }) + t.Run("changing cursors cannot hide sustained empty pages", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, _ map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + return fmt.Sprintf( + `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"empty-%d"}}`, + call, + ), nil + }} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + if _, err := queryRecordWindow(rt, map[string]any{}, 1); err == nil || !strings.Contains(err.Error(), "no progress") { + t.Fatalf("sustained empty pages error = %v", err) + } + if len(caller.calls) != recordQueryMaxConsecutiveEmptyPages { + t.Fatalf("query calls = %d, want %d", len(caller.calls), recordQueryMaxConsecutiveEmptyPages) + } + }) + t.Run("invalid shortcut limit", func(t *testing.T) { caller := &upsertByKeyCaller{} helpers.InitDepsForTest(t, caller) diff --git a/internal/shortcut/minutesdata/coverage_completion_test.go b/internal/shortcut/minutesdata/coverage_completion_test.go index aa2e3cb4..b0bbcfbc 100644 --- a/internal/shortcut/minutesdata/coverage_completion_test.go +++ b/internal/shortcut/minutesdata/coverage_completion_test.go @@ -232,6 +232,7 @@ func TestCrossPlatformCoverageMinutesWorkflowCompletion(t *testing.T) { } for _, data := range []map[string]any{ {"success": false, "errorMsg": "denied"}, + {"success": "yes"}, {"success": true, "result": "bad"}, {"success": true, "result": map[string]any{}}, {"success": true, "result": map[string]any{"resultMap": map[string]any{}}}, From f0412758118e5abf3e1d8eb43212c85733e7e859 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 22:55:22 +0800 Subject: [PATCH 160/250] fix: make minutes polling portable --- internal/shortcut/minutes/alignment.go | 10 +++------- internal/shortcut/minutes/workflows.go | 19 ++++++++++++++----- .../minutes/workflows_coverage_test.go | 3 +-- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/internal/shortcut/minutes/alignment.go b/internal/shortcut/minutes/alignment.go index 21d35464..7a3d85f1 100644 --- a/internal/shortcut/minutes/alignment.go +++ b/internal/shortcut/minutes/alignment.go @@ -618,15 +618,11 @@ func completeMinutesUpload(rt *shortcut.RuntimeContext, sessionID string, timeou } message := strings.ToLower(err.Error()) retryable := strings.Contains(message, "still uploading") || strings.Contains(message, "wait and retry") || strings.Contains(message, "正在上传") - if !retryable || time.Now().Add(interval).After(deadline) { + if !retryable || minutesPollDeadlineReached(deadline, interval) { return nil, attempts, err } - timer := time.NewTimer(interval) - select { - case <-rt.Command().Context().Done(): - timer.Stop() - return nil, attempts, rt.Command().Context().Err() - case <-timer.C: + if err := waitMinutesInterval(rt, interval); err != nil { + return nil, attempts, err } } } diff --git a/internal/shortcut/minutes/workflows.go b/internal/shortcut/minutes/workflows.go index e9a44456..7ba980d3 100644 --- a/internal/shortcut/minutes/workflows.go +++ b/internal/shortcut/minutes/workflows.go @@ -4,6 +4,7 @@ package minutes import ( + "context" "encoding/json" "fmt" "os" @@ -372,7 +373,7 @@ func runMinutesMindmap(rt *shortcut.RuntimeContext, id string, timeout, interval payload := map[string]any{"operation": "minutes.mindmap", "complete": false, "taskUuid": id, "taskStatus": status, "attempts": attempts, "result": result, "recovery": map[string]any{"taskUuid": id, "nextAction": "inspect source transcript; do not assume an empty mind map"}} return payload, minutesCompositeError("minutes_mindmap_failed", "poll", payload) } - if time.Now().Add(interval).After(deadline) { + if minutesPollDeadlineReached(deadline, interval) { payload := map[string]any{"operation": "minutes.mindmap", "complete": false, "taskUuid": id, "taskStatus": status, "attempts": attempts, "recovery": map[string]any{"taskUuid": id, "nextAction": "dws minutes mind-graph status --id "}} return payload, minutesCompositeError("minutes_mindmap_timeout", "poll", payload) } @@ -422,7 +423,7 @@ func runMinutesSpeakerInsights(rt *shortcut.RuntimeContext, id string, timeout, payload := map[string]any{"operation": "minutes.speaker_insights", "complete": false, "taskUuid": id, "taskId": taskID, "attempts": attempts, "stage": "poll", "recovery": map[string]any{"taskUuid": id, "taskId": taskID, "nextAction": "dws minutes speaker summary get --ids "}} return payload, callErr } - if time.Now().Add(interval).After(deadline) { + if minutesPollDeadlineReached(deadline, interval) { payload := map[string]any{"operation": "minutes.speaker_insights", "complete": false, "taskUuid": id, "taskId": taskID, "attempts": attempts, "stage": "poll", "recovery": map[string]any{"taskUuid": id, "taskId": taskID, "nextAction": "dws minutes speaker summary get --ids "}} return payload, minutesCompositeError("minutes_speaker_insights_timeout", "poll", payload) } @@ -723,7 +724,7 @@ func waitMinutesArtifacts(rt *shortcut.RuntimeContext, id string, artifacts []st for { attempts++ bundle, failures := collectMinutesArtifactsOnce(rt, id, artifacts, pageLimit) - if len(failures) == 0 || time.Now().Add(interval).After(deadline) { + if len(failures) == 0 || minutesPollDeadlineReached(deadline, interval) { return bundle, failures, attempts } if err := waitMinutesInterval(rt, interval); err != nil { @@ -735,14 +736,22 @@ func waitMinutesArtifacts(rt *shortcut.RuntimeContext, id string, artifacts []st func waitMinutesInterval(rt *shortcut.RuntimeContext, interval time.Duration) error { timer := time.NewTimer(interval) defer timer.Stop() + commandContext := rt.Command().Context() + if commandContext == nil { + commandContext = context.Background() + } select { - case <-rt.Command().Context().Done(): - return rt.Command().Context().Err() + case <-commandContext.Done(): + return commandContext.Err() case <-timer.C: return nil } } +func minutesPollDeadlineReached(deadline time.Time, interval time.Duration) bool { + return !time.Now().Add(interval).Before(deadline) +} + func outputWorkflowResult(rt *shortcut.RuntimeContext, payload map[string]any, failed bool, reason, stage string) error { if err := rt.Output(payload); err != nil { return err diff --git a/internal/shortcut/minutes/workflows_coverage_test.go b/internal/shortcut/minutes/workflows_coverage_test.go index c2d7bf43..36ff3ac8 100644 --- a/internal/shortcut/minutes/workflows_coverage_test.go +++ b/internal/shortcut/minutes/workflows_coverage_test.go @@ -442,10 +442,9 @@ func TestCrossPlatformCoverageMinutesArtifactWaitAndOutput(t *testing.T) { t.Fatalf("cancel failures=%#v", failures) } cmd = &cobra.Command{Use: "wait"} - cmd.SetContext(context.Background()) rt = shortcut.RuntimeContextForTest(cmd, ExportPack) if err := waitMinutesInterval(rt, 0); err != nil { - t.Fatalf("timer wait: %v", err) + t.Fatalf("timer wait with unset command context: %v", err) } cmd.SetOut(minutesFailWriter{}) From 2ab8748c4d1a9310841c178562544dc0410009ec Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 23:01:31 +0800 Subject: [PATCH 161/250] test: use native minutes path separators --- internal/shortcut/minutes/workflows_coverage_test.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/internal/shortcut/minutes/workflows_coverage_test.go b/internal/shortcut/minutes/workflows_coverage_test.go index 36ff3ac8..34c47c74 100644 --- a/internal/shortcut/minutes/workflows_coverage_test.go +++ b/internal/shortcut/minutes/workflows_coverage_test.go @@ -586,7 +586,7 @@ func TestCrossPlatformCoverageMinutesExportPackBranchesE2E(t *testing.T) { } func TestCrossPlatformCoverageMinutesExportPathAndJSONFaults(t *testing.T) { - if _, _, _, err := prepareExportTarget("../escape"); err == nil { + if _, _, _, err := prepareExportTarget(filepath.Join("..", "escape")); err == nil { t.Fatal("unsafe target accepted") } for _, test := range []struct { @@ -612,7 +612,7 @@ func TestCrossPlatformCoverageMinutesExportPathAndJSONFaults(t *testing.T) { } }}, {name: "escape", run: func(t *testing.T) { - testseam.Swap(t, &minutesRel, func(string, string) (string, error) { return "../escape", nil }) + testseam.Swap(t, &minutesRel, func(string, string) (string, error) { return filepath.Join("..", "escape"), nil }) if _, _, _, err := prepareExportTarget("pack"); err == nil { t.Fatal("rel escape accepted") } @@ -624,7 +624,7 @@ func TestCrossPlatformCoverageMinutesExportPathAndJSONFaults(t *testing.T) { } }}, {name: "parent", run: func(t *testing.T) { - testseam.Swap(t, &minutesRel, func(string, string) (string, error) { return "parent/pack", nil }) + testseam.Swap(t, &minutesRel, func(string, string) (string, error) { return filepath.Join("parent", "pack"), nil }) testseam.Swap(t, &minutesLstat, func(string) (os.FileInfo, error) { return nil, errors.New("parent") }) if _, _, _, err := prepareExportTarget("pack"); err == nil { t.Fatal("unsafe parent accepted") From 37b9a1dc3166eecdb1cfa743108389c03212ef65 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 23:26:31 +0800 Subject: [PATCH 162/250] fix: bound exact aitable record queries --- internal/shortcut/aitable/record_query_all.go | 63 +++++++++++++++ .../aitable/record_upsert_by_key_e2e_test.go | 78 ++++++++++++++++++- 2 files changed, 139 insertions(+), 2 deletions(-) diff --git a/internal/shortcut/aitable/record_query_all.go b/internal/shortcut/aitable/record_query_all.go index bdaffb41..3e079384 100644 --- a/internal/shortcut/aitable/record_query_all.go +++ b/internal/shortcut/aitable/record_query_all.go @@ -126,10 +126,35 @@ func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) erro if limit < 1 || limit > recordBatchSize { return fmt.Errorf("--limit must be in [1,%d], got %d", recordBatchSize, limit) } + requestedIDs, exactIDQuery, err := recordQueryRequestedIDs(params) + if err != nil { + return err + } + if exactIDQuery { + if len(requestedIDs) > recordBatchSize { + return fmt.Errorf("--record-ids accepts at most %d unique IDs, got %d", recordBatchSize, len(requestedIDs)) + } + params = cloneAnyMap(params) + params["recordIds"] = requestedIDs + limit = minInt(limit, len(requestedIDs)) + } window, err := queryRecordWindow(rt, params, limit) if err != nil { return err } + if exactIDQuery { + complete, err := validateExactRecordQuery(window.Records, requestedIDs) + if err != nil { + return err + } + if complete { + // The service may advertise unrelated continuation after every + // requested ID is already present. Exact-ID completion is stronger + // evidence than that residual pager state. + window.HasMore = false + window.NextCursor = "" + } + } records := make([]any, 0, len(window.Records)) for _, record := range window.Records { records = append(records, record) @@ -150,6 +175,44 @@ func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) erro }) } +func recordQueryRequestedIDs(params map[string]any) ([]string, bool, error) { + raw, exists := params["recordIds"] + if !exists { + return nil, false, nil + } + values, ok := raw.([]string) + if !ok { + return nil, false, fmt.Errorf("recordIds must be a string list, got %T", raw) + } + ids, err := parseRecordIDs(values) + if err != nil { + return nil, false, err + } + return ids, true, nil +} + +func validateExactRecordQuery(records []map[string]any, requestedIDs []string) (bool, error) { + wanted := make(map[string]bool, len(requestedIDs)) + for _, id := range requestedIDs { + wanted[id] = true + } + seen := make(map[string]bool, len(records)) + for index, record := range records { + id := recordID(record) + if id == "" { + return false, fmt.Errorf("query_records exact-ID result %d is missing recordId", index) + } + if !wanted[id] { + return false, fmt.Errorf("query_records exact-ID result contains unexpected recordId %q", id) + } + if seen[id] { + return false, fmt.Errorf("query_records exact-ID result contains duplicate recordId %q", id) + } + seen[id] = true + } + return len(seen) == len(wanted), nil +} + func queryAllRecords(rt *shortcut.RuntimeContext, params map[string]any, maxRecords int) ([]map[string]any, error) { all := make([]map[string]any, 0) cursor := "" diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index d468901a..3a3800d2 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -9,6 +9,7 @@ import ( "encoding/json" "errors" "fmt" + "slices" "strings" "testing" @@ -296,7 +297,7 @@ func pagedRecordQueryResponse(t *testing.T, records []map[string]any, args map[s return string(raw) } -func runRecordQueryShortcutCLI(t *testing.T, caller *upsertByKeyCaller, limit int) (map[string]any, error) { +func runRecordQueryShortcutCLI(t *testing.T, caller *upsertByKeyCaller, limit int, extra ...string) (map[string]any, error) { t.Helper() helpers.InitDepsForTest(t, caller) root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} @@ -307,7 +308,8 @@ func runRecordQueryShortcutCLI(t *testing.T, caller *upsertByKeyCaller, limit in stdout := &bytes.Buffer{} root.SetOut(stdout) root.SetErr(&bytes.Buffer{}) - root.SetArgs([]string{"aitable", "+record-query", "--base-id", "base", "--table-id", "table", "--limit", fmt.Sprint(limit)}) + args := []string{"aitable", "+record-query", "--base-id", "base", "--table-id", "table", "--limit", fmt.Sprint(limit)} + root.SetArgs(append(args, extra...)) err := root.Execute() if stdout.Len() == 0 { return nil, err @@ -346,6 +348,33 @@ func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) } } +func TestCrossPlatformCoverageRecordQueryExactIDsIgnoreResidualContinuationE2E(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, args map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + if call != 0 { + return "", errors.New("exact-ID query followed residual continuation") + } + if args["limit"] != 2 { + t.Fatalf("exact-ID service limit = %#v, want 2", args["limit"]) + } + ids, ok := args["recordIds"].([]string) + if !ok || !slices.Equal(ids, []string{"r1", "r2"}) { + t.Fatalf("exact-ID request IDs = %#v", args["recordIds"]) + } + return `{"success":true,"data":{"records":[{"recordId":"r1"},{"recordId":"r2"}],"hasMore":true,"nextCursor":"residual"}}`, nil + }} + payload, err := runRecordQueryShortcutCLI(t, caller, 100, "--record-ids", "r2,r1,r2") + data, _ := payload["data"].(map[string]any) + if err != nil || len(caller.calls) != 1 || data["hasMore"] != false || data["size"] != float64(2) { + t.Fatalf("exact-ID payload=%#v calls=%d err=%v", payload, len(caller.calls), err) + } + if _, exists := data["nextCursor"]; exists { + t.Fatalf("exact-ID payload retained residual cursor: %#v", payload) + } +} + func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testing.T) { t.Run("non-positive window limit", func(t *testing.T) { caller := &upsertByKeyCaller{} @@ -438,6 +467,51 @@ func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testi } }) + t.Run("invalid exact-ID request", func(t *testing.T) { + for _, testCase := range []struct { + name string + params map[string]any + want string + }{ + {name: "wrong type", params: map[string]any{"recordIds": 1}, want: "string list"}, + {name: "empty", params: map[string]any{"recordIds": []string{" "}}, want: "至少包含一个非空 recordId"}, + {name: "over service limit", params: map[string]any{"recordIds": recordIDFixtures(recordBatchSize + 1)}, want: "at most 100 unique IDs"}, + } { + t.Run(testCase.name, func(t *testing.T) { + caller := &upsertByKeyCaller{} + helpers.InitDepsForTest(t, caller) + rt := shortcut.RuntimeContextForTest(&cobra.Command{Use: "query"}, RecordQuery) + err := executeRecordQuery(rt, testCase.params) + if err == nil || !strings.Contains(err.Error(), testCase.want) { + t.Fatalf("exact-ID request error = %v, want %q", err, testCase.want) + } + if len(caller.calls) != 0 { + t.Fatalf("invalid exact-ID request made %d service calls", len(caller.calls)) + } + }) + } + }) + + t.Run("invalid exact-ID response", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, _ map[string]any) (string, error) { + if tool != "query_records" { + return "", fmt.Errorf("unexpected tool %s", tool) + } + return `{"success":true,"data":{"records":[{"recordId":"other"}]}}`, nil + }} + if _, err := runRecordQueryShortcutCLI(t, caller, 100, "--record-ids", "r1"); err == nil || !strings.Contains(err.Error(), "unexpected recordId") { + t.Fatalf("unexpected exact-ID response error = %v", err) + } + + if _, err := validateExactRecordQuery([]map[string]any{{}}, []string{"r1"}); err == nil || !strings.Contains(err.Error(), "missing recordId") { + t.Fatalf("missing exact-ID response error = %v", err) + } + duplicate := []map[string]any{{"recordId": "r1"}, {"recordId": "r1"}} + if _, err := validateExactRecordQuery(duplicate, []string{"r1", "r2"}); err == nil || !strings.Contains(err.Error(), "duplicate recordId") { + t.Fatalf("duplicate exact-ID response error = %v", err) + } + }) + t.Run("shortcut query failure", func(t *testing.T) { caller := &upsertByKeyCaller{callFn: func(_ int, _, _ string, _ map[string]any) (string, error) { return "", errors.New("query unavailable") From 7aa8240629b49ea383638501db26e07c55b72432 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 09:49:52 +0800 Subject: [PATCH 163/250] fix: preserve record query preview contract --- ...1006-aitable-pagination-minutes-unshare.md | 3 +- internal/shortcut/aitable/record_batch.go | 5 +-- internal/shortcut/aitable/record_query_all.go | 37 +++++++++++++++++-- .../aitable/record_upsert_by_key_e2e_test.go | 27 +++++++++++--- 4 files changed, 59 insertions(+), 13 deletions(-) diff --git a/.changes/1006-aitable-pagination-minutes-unshare.md b/.changes/1006-aitable-pagination-minutes-unshare.md index 8ca97c30..9607d987 100644 --- a/.changes/1006-aitable-pagination-minutes-unshare.md +++ b/.changes/1006-aitable-pagination-minutes-unshare.md @@ -4,6 +4,7 @@ category: Fixed - **Aitable pagination and Minutes unshare verification** (#1006) — keeps record queries on the service's 20-record page boundary so multi-page reads - and mutation readbacks no longer report false retryable failures, and rejects + and mutation readbacks no longer report false retryable failures, preserves + `totalCount` when supplied, keeps `--dry-run` transport-free, and rejects Minutes unshare success until the listening note exists and the service acknowledges the exact task and member targets. diff --git a/internal/shortcut/aitable/record_batch.go b/internal/shortcut/aitable/record_batch.go index 05294ad3..f779b32f 100644 --- a/internal/shortcut/aitable/record_batch.go +++ b/internal/shortcut/aitable/record_batch.go @@ -334,9 +334,8 @@ func queryDeletedRecordsByIDs(rt *shortcut.RuntimeContext, baseID, tableID strin } return nil, fmt.Errorf("query_records deletion read-back chunk %d is missing records", offset/recordQueryServicePageSize+1) } - if responseHasMore(data) { - return nil, fmt.Errorf("query_records deletion read-back chunk %d is incomplete", offset/recordQueryServicePageSize+1) - } + // Exact-ID absence is complete evidence for deletion even when the + // service retains an unrelated continuation marker. remaining = append(remaining, records...) } return remaining, nil diff --git a/internal/shortcut/aitable/record_query_all.go b/internal/shortcut/aitable/record_query_all.go index 3e079384..eadec9f6 100644 --- a/internal/shortcut/aitable/record_query_all.go +++ b/internal/shortcut/aitable/record_query_all.go @@ -21,10 +21,12 @@ const ( ) type recordQueryWindow struct { - Records []map[string]any - HasMore bool - NextCursor string - Pages int + Records []map[string]any + HasMore bool + NextCursor string + Pages int + TotalCount any + HasTotalCount bool } func queryRecordWindow(rt *shortcut.RuntimeContext, params map[string]any, limit int) (recordQueryWindow, error) { @@ -53,6 +55,9 @@ func queryRecordWindow(rt *shortcut.RuntimeContext, params map[string]any, limit if err != nil { return recordQueryWindow{}, err } + if !window.HasTotalCount { + window.TotalCount, window.HasTotalCount = responseTotalCount(data) + } records, found := findRecords(data) if !found { if explicitEmptyRecordQuery(data) { @@ -119,6 +124,14 @@ func explicitEmptyRecordQuery(data map[string]any) bool { } func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) error { + if rt.DryRun() { + return rt.Output(map[string]any{ + "dry_run": true, + "executed": false, + "tool": "query_records", + "arguments": params, + }) + } limit := 100 if rt.Changed("limit") { limit = rt.Int("limit") @@ -168,6 +181,9 @@ func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) erro if window.NextCursor != "" { data["nextCursor"] = window.NextCursor } + if window.HasTotalCount { + data["totalCount"] = window.TotalCount + } return rt.Output(map[string]any{ "success": true, "status": "success", @@ -175,6 +191,19 @@ func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) erro }) } +func responseTotalCount(data map[string]any) (any, bool) { + for { + if totalCount, exists := data["totalCount"]; exists { + return totalCount, true + } + nested, ok := data["data"].(map[string]any) + if !ok { + return nil, false + } + data = nested + } +} + func recordQueryRequestedIDs(params map[string]any) ([]string, bool, error) { raw, exists := params["recordIds"] if !exists { diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 3a3800d2..6af79e58 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -280,7 +280,7 @@ func pagedRecordQueryResponse(t *testing.T, records []map[string]any, args map[s } end := minInt(offset+limit, len(records)) pageRecords := records[offset:end] - data := map[string]any{"records": pageRecords, "hasMore": end < len(records)} + data := map[string]any{"records": pageRecords, "hasMore": end < len(records), "totalCount": len(records)} if end < len(records) { data["nextCursor"] = fmt.Sprintf("offset-%d", end) } @@ -337,7 +337,7 @@ func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) t.Fatalf("record query size %d: %v", size, err) } data, ok := payload["data"].(map[string]any) - if !ok || payload["success"] != true || data["hasMore"] != false || len(data["records"].([]any)) != size { + if !ok || payload["success"] != true || data["hasMore"] != false || data["totalCount"] != float64(size) || len(data["records"].([]any)) != size { t.Fatalf("record query size %d payload = %#v", size, payload) } wantCalls := (size + recordQueryServicePageSize - 1) / recordQueryServicePageSize @@ -348,6 +348,22 @@ func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) } } +func TestCrossPlatformCoverageRecordQueryDryRunStopsBeforeTransportE2E(t *testing.T) { + caller := &upsertByKeyCaller{} + payload, err := runRecordQueryShortcutCLI(t, caller, 5, "--query", "needle", "--dry-run") + if err != nil { + t.Fatalf("record query dry-run error = %v", err) + } + if len(caller.calls) != 0 { + t.Fatalf("record query dry-run crossed transport: %#v", caller.calls) + } + arguments, _ := payload["arguments"].(map[string]any) + if payload["dry_run"] != true || payload["executed"] != false || payload["tool"] != "query_records" || + arguments["baseId"] != "base" || arguments["tableId"] != "table" || arguments["keyword"] != "needle" || arguments["limit"] != float64(5) { + t.Fatalf("record query dry-run payload = %#v", payload) + } +} + func TestCrossPlatformCoverageRecordQueryExactIDsIgnoreResidualContinuationE2E(t *testing.T) { caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, args map[string]any) (string, error) { if tool != "query_records" { @@ -538,15 +554,16 @@ func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testi } }) - t.Run("delete readback rejects continuation", func(t *testing.T) { + t.Run("delete readback ignores residual continuation", func(t *testing.T) { caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, _ map[string]any) (string, error) { if tool == "query_records" { return `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"unexpected"}}`, nil } return `{"deletedCount":1}`, nil }} - if _, err := runRecordDeleteCLI(t, caller, []string{"r1"}); err == nil || len(caller.calls) != 2 || caller.calls[1].tool != "query_records" { - t.Fatalf("delete continuation error = %v calls=%#v", err, caller.calls) + out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) + if err != nil || out == "" || len(caller.calls) != 2 || caller.calls[1].tool != "query_records" { + t.Fatalf("delete residual continuation output=%q error=%v calls=%#v", out, err, caller.calls) } }) } From 5a414999efc37945609687b400ebbc7b848904eb Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 11:34:28 +0800 Subject: [PATCH 164/250] fix: validate record query previews --- internal/shortcut/aitable/record_query_all.go | 16 +++++----- .../aitable/record_upsert_by_key_e2e_test.go | 30 +++++++++++++++++++ 2 files changed, 38 insertions(+), 8 deletions(-) diff --git a/internal/shortcut/aitable/record_query_all.go b/internal/shortcut/aitable/record_query_all.go index eadec9f6..95ef48b4 100644 --- a/internal/shortcut/aitable/record_query_all.go +++ b/internal/shortcut/aitable/record_query_all.go @@ -124,14 +124,6 @@ func explicitEmptyRecordQuery(data map[string]any) bool { } func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) error { - if rt.DryRun() { - return rt.Output(map[string]any{ - "dry_run": true, - "executed": false, - "tool": "query_records", - "arguments": params, - }) - } limit := 100 if rt.Changed("limit") { limit = rt.Int("limit") @@ -151,6 +143,14 @@ func executeRecordQuery(rt *shortcut.RuntimeContext, params map[string]any) erro params["recordIds"] = requestedIDs limit = minInt(limit, len(requestedIDs)) } + if rt.DryRun() { + return rt.Output(map[string]any{ + "dry_run": true, + "executed": false, + "tool": "query_records", + "arguments": params, + }) + } window, err := queryRecordWindow(rt, params, limit) if err != nil { return err diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 6af79e58..41872a71 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -364,6 +364,36 @@ func TestCrossPlatformCoverageRecordQueryDryRunStopsBeforeTransportE2E(t *testin } } +func TestCrossPlatformCoverageRecordQueryDryRunRejectsInvalidLocalPlanE2E(t *testing.T) { + for _, testCase := range []struct { + name string + limit int + extra []string + want string + }{ + {name: "zero limit", limit: 0, extra: []string{"--dry-run"}, want: "--limit must be in [1,100]"}, + {name: "excessive limit", limit: recordBatchSize + 1, extra: []string{"--dry-run"}, want: "--limit must be in [1,100]"}, + {name: "empty record IDs", limit: 100, extra: []string{"--record-ids", " ", "--dry-run"}, want: "至少包含一个非空 recordId"}, + { + name: "excessive record IDs", + limit: 100, + extra: []string{"--record-ids", strings.Join(recordIDFixtures(recordBatchSize+1), ","), "--dry-run"}, + want: "at most 100 unique IDs", + }, + } { + t.Run(testCase.name, func(t *testing.T) { + caller := &upsertByKeyCaller{} + payload, err := runRecordQueryShortcutCLI(t, caller, testCase.limit, testCase.extra...) + if err == nil || !strings.Contains(err.Error(), testCase.want) { + t.Fatalf("record query dry-run error = %v, want %q (payload=%#v)", err, testCase.want, payload) + } + if len(caller.calls) != 0 { + t.Fatalf("invalid record query dry-run crossed transport: %#v", caller.calls) + } + }) + } +} + func TestCrossPlatformCoverageRecordQueryExactIDsIgnoreResidualContinuationE2E(t *testing.T) { caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, args map[string]any) (string, error) { if tool != "query_records" { From c1a549cd64b83f4ae312c342d652b0125fba2547 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 13:46:33 +0800 Subject: [PATCH 165/250] fix: close delete readback continuations --- ...1006-aitable-pagination-minutes-unshare.md | 7 ++- internal/shortcut/aitable/record_batch.go | 17 ++---- .../aitable/record_upsert_by_key_e2e_test.go | 60 ++++++++++++++++--- 3 files changed, 61 insertions(+), 23 deletions(-) diff --git a/.changes/1006-aitable-pagination-minutes-unshare.md b/.changes/1006-aitable-pagination-minutes-unshare.md index 9607d987..3275bd7a 100644 --- a/.changes/1006-aitable-pagination-minutes-unshare.md +++ b/.changes/1006-aitable-pagination-minutes-unshare.md @@ -5,6 +5,7 @@ category: Fixed - **Aitable pagination and Minutes unshare verification** (#1006) — keeps record queries on the service's 20-record page boundary so multi-page reads and mutation readbacks no longer report false retryable failures, preserves - `totalCount` when supplied, keeps `--dry-run` transport-free, and rejects - Minutes unshare success until the listening note exists and the service - acknowledges the exact task and member targets. + `totalCount` when supplied, validates `--dry-run` plans before transport, + follows active deletion readback continuations before proving absence, and + rejects Minutes unshare success until the listening note exists and the + service acknowledges the exact task and member targets. diff --git a/internal/shortcut/aitable/record_batch.go b/internal/shortcut/aitable/record_batch.go index f779b32f..63f7d92f 100644 --- a/internal/shortcut/aitable/record_batch.go +++ b/internal/shortcut/aitable/record_batch.go @@ -321,22 +321,13 @@ func queryDeletedRecordsByIDs(rt *shortcut.RuntimeContext, baseID, tableID strin for offset := 0; offset < len(ids); offset += recordQueryServicePageSize { end := minInt(offset+recordQueryServicePageSize, len(ids)) chunk := ids[offset:end] - data, err := rt.CallMCPData(serverMain, "query_records", map[string]any{ - "baseId": baseID, "tableId": tableID, "recordIds": chunk, "limit": len(chunk), - }) + window, err := queryRecordWindow(rt, map[string]any{ + "baseId": baseID, "tableId": tableID, "recordIds": chunk, + }, len(chunk)) if err != nil { return nil, err } - records, found := findRecords(data) - if !found { - if explicitEmptyRecordQuery(data) { - continue - } - return nil, fmt.Errorf("query_records deletion read-back chunk %d is missing records", offset/recordQueryServicePageSize+1) - } - // Exact-ID absence is complete evidence for deletion even when the - // service retains an unrelated continuation marker. - remaining = append(remaining, records...) + remaining = append(remaining, window.Records...) } return remaining, nil } diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 41872a71..2fc9333f 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -584,16 +584,62 @@ func TestCrossPlatformCoverageRecordQueryFailureAndContinuationBranches(t *testi } }) - t.Run("delete readback ignores residual continuation", func(t *testing.T) { - caller := &upsertByKeyCaller{callFn: func(_ int, _, tool string, _ map[string]any) (string, error) { - if tool == "query_records" { - return `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"unexpected"}}`, nil + t.Run("delete readback follows active continuation to absence", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, args map[string]any) (string, error) { + if tool != "query_records" { + return `{"deletedCount":1}`, nil } - return `{"deletedCount":1}`, nil + if call == 1 { + if _, exists := args["cursor"]; exists { + t.Fatalf("first deletion readback unexpectedly has cursor: %#v", args) + } + return `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"c1"}}`, nil + } + if args["cursor"] != "c1" { + t.Fatalf("continued deletion readback cursor = %#v", args["cursor"]) + } + return `{"success":true,"data":{"records":[],"hasMore":false}}`, nil }} out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) - if err != nil || out == "" || len(caller.calls) != 2 || caller.calls[1].tool != "query_records" { - t.Fatalf("delete residual continuation output=%q error=%v calls=%#v", out, err, caller.calls) + if err != nil || out == "" || len(caller.calls) != 3 { + t.Fatalf("delete continued absence output=%q error=%v calls=%#v", out, err, caller.calls) + } + }) + + t.Run("delete readback follows active continuation to remaining record", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, _ map[string]any) (string, error) { + if tool != "query_records" { + return `{"deletedCount":1}`, nil + } + if call == 1 { + return `{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"c1"}}`, nil + } + return `{"success":true,"data":{"records":[{"recordId":"r1"}],"hasMore":false}}`, nil + }} + out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) + if err == nil || out != "" || len(caller.calls) != 3 { + t.Fatalf("delete continued remaining output=%q error=%v calls=%#v", out, err, caller.calls) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "aitable_composite_unknown" { + t.Fatalf("delete continued remaining error = %#v", err) + } + }) + + t.Run("delete readback fails closed on empty continuation stall", func(t *testing.T) { + caller := &upsertByKeyCaller{callFn: func(call int, _, tool string, _ map[string]any) (string, error) { + if tool != "query_records" { + return `{"deletedCount":1}`, nil + } + return fmt.Sprintf(`{"success":true,"data":{"records":[],"hasMore":true,"nextCursor":"c%d"}}`, call), nil + }} + out, err := runRecordDeleteCLI(t, caller, []string{"r1"}) + if err == nil || out != "" || len(caller.calls) != recordQueryMaxConsecutiveEmptyPages+1 { + t.Fatalf("delete stalled continuation output=%q error=%v calls=%#v", out, err, caller.calls) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "aitable_composite_unknown" { + t.Fatalf("delete stalled continuation error = %#v", err) } }) } From 93dbd768f70ef93b4015e8c01233996c8364fd98 Mon Sep 17 00:00:00 2001 From: ruigong Date: Mon, 17 Aug 2026 14:18:03 +0800 Subject: [PATCH 166/250] fix(skill): add explicit recent-edited route to drive SOP-1 --- skills/multi/dingtalk-drive/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index 7d2beba4..d08e94b5 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -49,9 +49,9 @@ metadata: ### SOP-1 找文件（find-file） -**触发**：找文件/搜文件/我的文件/最近文件/某文档在哪。 +**触发**：找文件/搜文件/我的文件/最近文件/最近编辑的文档/某文档在哪。 -1. **选源（必须）**：最近访问 → `dws drive +recent --limit --format json`（翻页用上次返回的 `nextCursor` 传 `--cursor`）；按内容/名称全局搜 → `dws drive +search --query "<关键词>" --format json`；浏览某目录 → `dws drive +list --folder --format json`。 +1. **选源（必须）**：最近访问 → `dws drive +recent --limit --format json`（翻页用上次返回的 `nextCursor` 传 `--cursor`）；最近编辑 → `dws drive +recent --operate-type 1 --limit --format json`（不传 `--operate-type` 默认为 0 最近访问，会混入仅打开过的文档）；按内容/名称全局搜 → `dws drive +search --query "<关键词>" --format json`；浏览某目录 → `dws drive +list --folder --format json`。 2. **解析（必须）**：取真实 `dentryUuid`（= `id`/`nodeId`）；多候选让用户确认，**禁止**默认取第一个。 3. **下钻（必须）**：根目录没命中时，进入最相关文件夹继续 `drive +list --folder`，必要时 `python scripts/drive_tree_list.py --depth 2` 递归，**禁止**只看根目录就放弃。 4. **回读元数据（必须）**：命中后 `dws drive +inspect --node --format json`，按 `extension` 确认类型。 From 3ee66d4373797ec17c4a2191b2eae3ee4d5b2513 Mon Sep 17 00:00:00 2001 From: Dennis Date: Wed, 12 Aug 2026 10:33:00 +0800 Subject: [PATCH 167/250] fix(doc): harden mutation readback verification --- go.mod | 1 + go.sum | 2 + internal/helpers/doc.go | 184 +++++++++- internal/helpers/doc_command_edges_test.go | 116 +++++- internal/shortcut/doc/content_shortcuts.go | 334 ++++++++++++++++-- .../doc/doc_readback_verification_test.go | 275 ++++++++++++++ internal/shortcut/doc/doc_shortcuts_test.go | 15 +- .../doc/history_template_shortcuts.go | 34 +- 8 files changed, 918 insertions(+), 43 deletions(-) create mode 100644 internal/shortcut/doc/doc_readback_verification_test.go diff --git a/go.mod b/go.mod index eb74fd55..62bec438 100644 --- a/go.mod +++ b/go.mod @@ -18,6 +18,7 @@ require ( github.com/muesli/termenv v0.16.0 github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-beta.1 github.com/spf13/cobra v1.10.2 + github.com/yuin/goldmark v1.8.5 github.com/zalando/go-keyring v0.2.8 gitlab.alibaba-inc.com/aes/aem-go-sdk v0.3.0 golang.org/x/crypto v0.49.0 diff --git a/go.sum b/go.sum index 99e029e0..06a5b621 100644 --- a/go.sum +++ b/go.sum @@ -105,6 +105,8 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM= +github.com/yuin/goldmark v1.8.5 h1:r6N5afV5qj/5S4UTch8agZHJ8UxNCMwX7WjkkJam2NA= +github.com/yuin/goldmark v1.8.5/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg= github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs= github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index 1897aa18..d1c9ce4c 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -492,10 +492,11 @@ func defaultHTTPGetFile(ctx context.Context, url string, headers map[string]stri return nil } -// runMediaInsert implements the three-step flow for inserting an attachment into a document: +// runMediaInsert implements the four-step flow for inserting an attachment into a document: // 1. get_doc_attachment_upload_info → obtain uploadUrl + resourceId // 2. HTTP PUT file content to OSS // 3. insert_document_block with attachment element +// 4. list_document_blocks → prove the uploaded resource is visible in the document func runMediaInsert(cmd *cobra.Command, _ []string) error { nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id") if err != nil { @@ -551,7 +552,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { ctx := cmd.Context() // Step 1: get upload credentials (uploadUrl + resourceId) - deps.Out.PrintInfo(fmt.Sprintf("[1/3] 获取附件上传凭证 (%s, %d bytes)...", fileName, fileSize)) + deps.Out.PrintInfo(fmt.Sprintf("[1/4] 获取附件上传凭证 (%s, %d bytes)...", fileName, fileSize)) credText, err := callMCPToolReturnText(ctx, "get_doc_attachment_upload_info", map[string]any{ "nodeId": nodeID, @@ -569,7 +570,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { } // Step 2: HTTP PUT file to OSS - deps.Out.PrintInfo("[2/3] 上传文件到 OSS...") + deps.Out.PrintInfo("[2/4] 上传文件到 OSS...") ossHeaders := map[string]string{ "Content-Type": mimeType, @@ -592,7 +593,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { } // Step 3: insert block into document - deps.Out.PrintInfo("[3/3] 插入块到文档...") + deps.Out.PrintInfo("[3/4] 插入块到文档...") const maxInlineImageSize = 20 * 1024 * 1024 // 20MB @@ -644,7 +645,8 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { insertArgs["referenceBlockId"] = v } - if err := callMCPTool("insert_document_block", insertArgs); err != nil { + insertText, err := callMCPToolReturnText(ctx, "insert_document_block", insertArgs) + if err != nil { return apperrors.NewAPI( "附件已上传，但正文 block 插入结果未知；请先检查媒体列表，不要重复上传或插入", apperrors.WithOperation("doc.media_insert"), @@ -665,6 +667,23 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { apperrors.WithCause(err), ) } + insertResult := map[string]any{} + if strings.TrimSpace(insertText) != "" { + if err := json.Unmarshal([]byte(insertText), &insertResult); err != nil { + return docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName, + fmt.Errorf("解析 insert_document_block 响应失败: %w", err)) + } + } + insertedBlockID := nestedDocString(insertResult, "blockId", "elementId", "id") + + deps.Out.PrintInfo("[4/4] 回读验证媒体块...") + verifiedBlockID, verifyErr := verifyInsertedDocMedia(ctx, nodeID, insertedBlockID, resourceID, resourceURL) + if verifyErr != nil { + return docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName, verifyErr) + } + if insertedBlockID == "" { + insertedBlockID = verifiedBlockID + } return deps.Out.PrintJSON(map[string]any{ "contractVersion": "doc.operation.v1", @@ -674,16 +693,169 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { "operation": "doc.media_insert", "data": map[string]any{ "nodeId": nodeID, "resourceId": resourceID, "resourceUrl": resourceURL, - "fileName": fileName, "mimeType": mimeType, "sizeBytes": fileSize, "inserted": true, + "blockId": insertedBlockID, "fileName": fileName, "mimeType": mimeType, "sizeBytes": fileSize, + "inserted": true, "verified": true, }, "steps": []map[string]any{ {"name": "resolve_upload", "status": "success"}, {"name": "upload_oss", "status": "success"}, {"name": "insert_block", "status": "success"}, + {"name": "verify", "status": "success"}, }, }) } +func docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName string, cause error) error { + return apperrors.NewAPI( + "附件已上传且插块请求已执行，但回读未能证明媒体块落库；不要直接重试上传或插入", + apperrors.WithOperation("doc.media_insert"), + apperrors.WithReason("doc_media_insert_verification_failed"), + apperrors.WithFailureStage("verify"), + apperrors.WithExecutionStarted(true), + apperrors.WithRetryable(false), + apperrors.WithActions("运行 dws doc +media-list 检查 resourceId", "确认媒体不存在后再决定是否重新执行"), + apperrors.WithDetails(map[string]any{ + "contractVersion": "doc.operation.v1", "status": "partial_success", "nodeId": nodeID, + "resourceId": resourceID, "resourceUrl": resourceURL, "fileName": fileName, "verified": false, + "steps": []map[string]any{ + {"name": "resolve_upload", "status": "success"}, + {"name": "upload_oss", "status": "success"}, + {"name": "insert_block", "status": "success"}, + {"name": "verify", "status": "failed"}, + }, + }), + apperrors.WithCause(cause), + ) +} + +func verifyInsertedDocMedia(ctx context.Context, nodeID, blockID, resourceID, resourceURL string) (string, error) { + delays := []time.Duration{250 * time.Millisecond, 500 * time.Millisecond, time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second} + var lastErr error + for attempt := 0; attempt <= len(delays); attempt++ { + blocks, err := readAllDocBlocksForVerification(ctx, nodeID) + if err != nil { + lastErr = err + } else { + lastErr = nil + if found := findVerifiedMediaBlock(blocks, blockID, resourceID, resourceURL); found != "" { + return found, nil + } + } + if attempt < len(delays) { + helperSleep(delays[attempt]) + } + } + if lastErr != nil { + return "", fmt.Errorf("媒体资源在有界回读窗口内仍无法读取: %w", lastErr) + } + return "", fmt.Errorf("媒体资源在有界回读窗口内仍不可见") +} + +func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, error) { + const pageSize = 50 + const maxItems = 5000 + all := make([]any, 0, pageSize) + seen := map[string]bool{} + for start := 0; start < maxItems; start += pageSize { + text, err := callMCPToolReturnTextOnServer(ctx, "doc", "list_document_blocks", map[string]any{ + "nodeId": nodeID, "format": "element", "startIndex": start, "endIndex": start + pageSize - 1, + }) + if err != nil { + return nil, err + } + var payload map[string]any + if err := json.Unmarshal([]byte(text), &payload); err != nil { + return nil, fmt.Errorf("解析 list_document_blocks 回读失败: %w", err) + } + payload = nestedDocMap(payload) + blocks, ok := payload["blocks"].([]any) + if !ok { + return nil, fmt.Errorf("list_document_blocks 回读缺少 blocks 数组") + } + encoded, _ := json.Marshal(blocks) + key := string(encoded) + if key != "[]" && seen[key] { + return nil, fmt.Errorf("list_document_blocks 分页停滞") + } + seen[key] = true + all = append(all, blocks...) + hasMore, hasMoreKnown := payload["hasMore"].(bool) + if hasMoreKnown && !hasMore { + return all, nil + } + if total, ok := docNumberAsInt(payload["totalCount"]); ok && len(all) >= total { + return all, nil + } + if !hasMoreKnown && len(blocks) < pageSize { + return all, nil + } + if len(blocks) == 0 { + return nil, fmt.Errorf("list_document_blocks 声明仍有下一页但当前页为空") + } + } + return nil, fmt.Errorf("文档块超过安全回读上限") +} + +func nestedDocMap(data map[string]any) map[string]any { + for _, key := range []string{"result", "data"} { + if nested, ok := data[key].(map[string]any); ok { + return nestedDocMap(nested) + } + } + return data +} + +func nestedDocString(value any, keys ...string) string { + switch typed := value.(type) { + case map[string]any: + for _, key := range keys { + if text, ok := typed[key].(string); ok && strings.TrimSpace(text) != "" { + return strings.TrimSpace(text) + } + } + for _, child := range typed { + if text := nestedDocString(child, keys...); text != "" { + return text + } + } + case []any: + for _, child := range typed { + if text := nestedDocString(child, keys...); text != "" { + return text + } + } + } + return "" +} + +func findVerifiedMediaBlock(blocks []any, blockID, resourceID, resourceURL string) string { + for _, value := range blocks { + candidateID := nestedDocString(value, "blockId", "id", "uuid") + if candidateID == "" || (blockID != "" && candidateID != blockID) { + continue + } + if resourceID != "" && nestedDocString(value, "resourceId") == resourceID { + return candidateID + } + if resourceID == "" && resourceURL != "" && nestedDocString(value, "resourceUrl") == resourceURL { + return candidateID + } + } + return "" +} + +func docNumberAsInt(value any) (int, bool) { + switch typed := value.(type) { + case float64: + if typed >= 0 && typed == float64(int(typed)) { + return int(typed), true + } + case int: + return typed, typed >= 0 + } + return 0, false +} + // parseAttachmentUploadInfo extracts uploadUrl, resourceId and resourceUrl from the MCP tool response. func parseAttachmentUploadInfo(text string) (uploadURL, resourceID, resourceURL string, err error) { var data map[string]any diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index d781efed..17ab60ca 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -4,6 +4,7 @@ import ( "bytes" "context" "errors" + "fmt" "io" "net/http" "net/http/httptest" @@ -13,6 +14,7 @@ import ( "testing" "time" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) @@ -74,6 +76,7 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { t.Cleanup(func() { os.Args = oldArgs }) oldPut, oldGet := httpPutFile, httpGetFile t.Cleanup(func() { httpPutFile, httpGetFile = oldPut, oldGet }) + testseam.Swap(t, &helperSleep, func(time.Duration) {}) file := filepath.Join(t.TempDir(), "file.txt") if err := os.WriteFile(file, []byte("content"), 0o600); err != nil { t.Fatal(err) @@ -193,6 +196,16 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { t.Fatal("media insert failure returned nil") } }) + t.Run("media insert response parse failure", func(t *testing.T) { + httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"uploadUrl":"https://upload","resourceId":"resource"}`}, + {text: `{`}, + }} + if err := mediaCommand(t, caller, file, "text/plain"); err == nil { + t.Fatal("invalid media insert response returned nil") + } + }) t.Run("large image becomes attachment", func(t *testing.T) { httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } large := filepath.Join(t.TempDir(), "large.png") @@ -202,7 +215,11 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { if err := os.Truncate(large, 21*1024*1024); err != nil { t.Fatal(err) } - caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`}, {text: `{}`}}} + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`}, + {text: `{}`}, + {text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"resource"}}}],"hasMore":false}`}, + }} if err := mediaCommand(t, caller, large, "image/png"); err != nil { t.Fatal(err) } @@ -240,6 +257,103 @@ func TestCrossPlatformCoverageDefaultDocHTTPTransportEdges(t *testing.T) { } } +func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { + testseam.Swap(t, &helperSleep, func(time.Duration) {}) + ctx := context.Background() + + for _, tc := range []struct { + name string + steps []scriptedToolStep + }{ + {"call failure", []scriptedToolStep{{err: errors.New("read")}}}, + {"invalid json", []scriptedToolStep{{text: `{`}}}, + {"missing blocks", []scriptedToolStep{{text: `{}`}}}, + {"stalled page", []scriptedToolStep{{text: `{"blocks":[{"id":"a"}],"hasMore":true}`}, {text: `{"blocks":[{"id":"a"}],"hasMore":true}`}}}, + {"empty continued page", []scriptedToolStep{{text: `{"blocks":[],"hasMore":true}`}}}, + } { + t.Run(tc.name, func(t *testing.T) { + installScriptedCaller(t, &scriptedToolCaller{steps: tc.steps}) + if _, err := readAllDocBlocksForVerification(ctx, "node"); err == nil { + t.Fatal("defensive readback returned nil") + } + }) + } + + t.Run("total count and nested payload", func(t *testing.T) { + installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"data":{"blocks":[{"id":"a"}],"totalCount":1}}`}}}) + blocks, err := readAllDocBlocksForVerification(ctx, "node") + if err != nil || len(blocks) != 1 { + t.Fatalf("blocks=%#v err=%v", blocks, err) + } + }) + + t.Run("unknown pagination short page", func(t *testing.T) { + installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"id":"a"}]}`}}}) + if blocks, err := readAllDocBlocksForVerification(ctx, "node"); err != nil || len(blocks) != 1 { + t.Fatalf("blocks=%#v err=%v", blocks, err) + } + }) + + t.Run("bounded retry failure", func(t *testing.T) { + installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[],"hasMore":false}`}}}) + if _, err := verifyInsertedDocMedia(ctx, "node", "", "missing", ""); err == nil { + t.Fatal("missing media unexpectedly verified") + } + }) + + t.Run("transient read failure retries", func(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {err: errors.New("temporary read failure")}, + {text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"resource"}}}],"hasMore":false}`}, + }} + installScriptedCaller(t, caller) + blockID, err := verifyInsertedDocMedia(ctx, "node", "media-block", "resource", "") + if err != nil || blockID != "media-block" || caller.calls != 2 { + t.Fatalf("blockID=%q calls=%d err=%v", blockID, caller.calls, err) + } + }) + + t.Run("block identity alone does not verify media", func(t *testing.T) { + installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"blockId":"media-block","element":{"attachment":{"resourceId":"other-resource"}}}],"hasMore":false}`}}}) + if _, err := verifyInsertedDocMedia(ctx, "node", "media-block", "resource", ""); err == nil { + t.Fatal("matching block ID with a different resource unexpectedly verified") + } + }) + + t.Run("block read safety limit", func(t *testing.T) { + steps := make([]scriptedToolStep, 100) + for index := range steps { + steps[index] = scriptedToolStep{text: fmt.Sprintf(`{"blocks":[{"id":"block-%d"}],"hasMore":true}`, index)} + } + installScriptedCaller(t, &scriptedToolCaller{steps: steps}) + if _, err := readAllDocBlocksForVerification(ctx, "node"); err == nil { + t.Fatal("oversized block read returned nil") + } + }) + + if got := nestedDocMap(map[string]any{"result": map[string]any{"data": map[string]any{"ok": true}}}); got["ok"] != true { + t.Fatalf("nested map=%#v", got) + } + if nestedDocString(map[string]any{"x": []any{map[string]any{"id": " nested "}}}, "id") != "nested" || nestedDocString(3, "id") != "" { + t.Fatal("nested string traversal failed") + } + blocks := []any{map[string]any{"id": "block", "resourceId": "rid"}, map[string]any{"id": "url-block", "resourceUrl": "https://media"}} + if findVerifiedMediaBlock(blocks, "block", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "", "https://media") != "url-block" || findVerifiedMediaBlock(blocks, "block", "wrong", "") != "" || findVerifiedMediaBlock(blocks, "", "missing", "") != "" { + t.Fatal("media block matching failed") + } + for _, tc := range []struct { + value any + want bool + }{ + {float64(3), true}, {float64(-1), false}, {1.5, false}, {3, true}, {-1, false}, {"3", false}, + } { + _, ok := docNumberAsInt(tc.value) + if ok != tc.want { + t.Fatalf("docNumberAsInt(%#v) ok=%v want=%v", tc.value, ok, tc.want) + } + } +} + func TestCrossPlatformCoverageDocCreateUpdateAndBlockCommandEdges(t *testing.T) { oldDeps, oldArgs, oldPut, oldGet := deps, os.Args, httpPutFile, httpGetFile t.Cleanup(func() { diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 6d3d781d..1232088e 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -4,8 +4,10 @@ package doc import ( + "bytes" "encoding/json" "fmt" + "io" "os" "path/filepath" "strings" @@ -18,6 +20,9 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/localio" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/docresolver" + "github.com/yuin/goldmark" + "github.com/yuin/goldmark/extension" + "github.com/yuin/goldmark/renderer/html" ) var ( @@ -28,6 +33,21 @@ var ( docMkdirTemp = os.MkdirTemp docRemoveAll = os.RemoveAll docDownload = localio.Download + docVerifySleep = time.Sleep + docVerifyDelays = []time.Duration{250 * time.Millisecond, 500 * time.Millisecond, time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second} + docMarkdown = goldmark.New( + goldmark.WithExtensions(extension.Table), + goldmark.WithRendererOptions(html.WithUnsafe()), + ) + docMarkdownConvert = func(source []byte, writer io.Writer) error { + return docMarkdown.Convert(source, writer) + } +) + +const ( + docBlockReadPageSize = 50 + docBlockReadMaxItems = 5000 + docMarkdownVerifyMax = 2 * 1024 * 1024 ) var Create = shortcut.Shortcut{ @@ -133,7 +153,9 @@ var Create = shortcut.Shortcut{ verifyTool = "get_document_content" verifyParams["format"] = format } - verification, err := rt.CallMCPData(productDoc, verifyTool, verifyParams) + verification, err := readDocVerification(rt, verifyTool, verifyParams, func(data map[string]any) bool { + return content == "" || verifyUpdatedDocumentContent(data, content, "overwrite", format) + }) if err != nil { return docVerificationError("doc.create", "verify", nodeID, err, append(steps, map[string]any{"name": "verify", "status": "failed"})) } @@ -422,7 +444,9 @@ var CheckpointUpdate = shortcut.Shortcut{ append(steps, map[string]any{"name": "update", "status": "failed"}, map[string]any{"name": "verify", "status": "not_started"})) } steps = append(steps, map[string]any{"name": "update", "status": "success"}) - verification, err := rt.CallMCPData(productDoc, "get_document_content", map[string]any{"nodeId": rt.Str("node"), "format": "markdown"}) + verification, err := readDocVerification(rt, "get_document_content", map[string]any{"nodeId": rt.Str("node"), "format": "markdown"}, func(data map[string]any) bool { + return verifyUpdatedDocumentContent(data, content, rt.Str("mode"), "markdown") + }) if err != nil { return checkpointPartialWriteError(rt.Str("node"), checkpoint, "verify", "doc_checkpoint_verification_failed", err, append(steps, map[string]any{"name": "verify", "status": "failed"})) @@ -539,7 +563,7 @@ func executeUpdate(rt *shortcut.RuntimeContext) error { } referenceBlockID := rt.Str("after-block-id") return executeVerifiedDocMutation(rt, "doc.update", "insert_document_block", params, node, - "list_document_blocks", map[string]any{"nodeId": node, "format": verificationFormat}, + "list_document_blocks", map[string]any{"nodeId": node, "format": verificationFormat, "__allBlocks": true}, func(result, data map[string]any) bool { return verifyInsertedBlock(result, data, referenceBlockID, content, rt.Str("doc-format")) }) @@ -553,14 +577,14 @@ func executeUpdate(rt *shortcut.RuntimeContext) error { params["element"] = map[string]any{"blockType": "paragraph", "paragraph": map[string]any{"text": content}} } return executeVerifiedDocMutation(rt, "doc.update", "update_document_block", params, node, - "list_document_blocks", map[string]any{"nodeId": node, "blockId": blockID, "format": verificationFormat}, + "list_document_blocks", map[string]any{"nodeId": node, "format": verificationFormat, "__allBlocks": true}, func(_, data map[string]any) bool { return blockContentEquals(data, blockID, content, rt.Str("doc-format")) }) case "block_delete": blockID := rt.Str("block-id") return executeVerifiedDocMutation(rt, "doc.update", "delete_document_block", map[string]any{"nodeId": node, "blockId": blockID}, node, - "list_document_blocks", map[string]any{"nodeId": node, "format": "element"}, + "list_document_blocks", map[string]any{"nodeId": node, "format": "element", "__allBlocks": true}, func(_, data map[string]any) bool { return findBlock(data, blockID) == nil }) case "str_replace": return executePlainTextReplace(rt, node) @@ -609,7 +633,7 @@ func nestedRevision(value any) (int, bool) { } func executePlainTextReplace(rt *shortcut.RuntimeContext, nodeID string) error { - data, err := rt.CallMCPData(productDoc, "list_document_blocks", map[string]any{"nodeId": nodeID, "format": "element"}) + data, err := readAllDocumentBlocks(rt, map[string]any{"nodeId": nodeID, "format": "element"}) if err != nil { return err } @@ -643,12 +667,12 @@ func executePlainTextReplace(rt *shortcut.RuntimeContext, nodeID string) error { blockID := matches[0].blockID return executeVerifiedDocMutation(rt, "doc.update", "update_document_block", map[string]any{"nodeId": nodeID, "blockId": blockID, "element": map[string]any{"blockType": "paragraph", "paragraph": map[string]any{"text": updated}}}, nodeID, - "list_document_blocks", map[string]any{"nodeId": nodeID, "blockId": blockID, "format": "element"}, + "list_document_blocks", map[string]any{"nodeId": nodeID, "format": "element", "__allBlocks": true}, func(_, data map[string]any) bool { return blockContentEquals(data, blockID, updated, "markdown") }) } func executeBlockCopy(rt *shortcut.RuntimeContext, nodeID string) error { - data, err := rt.CallMCPData(productDoc, "list_document_blocks", map[string]any{"nodeId": nodeID, "blockId": rt.Str("block-id"), "format": "element"}) + data, err := readAllDocumentBlocks(rt, map[string]any{"nodeId": nodeID, "format": "element"}) if err != nil { return err } @@ -664,7 +688,7 @@ func executeBlockCopy(rt *shortcut.RuntimeContext, nodeID string) error { referenceBlockID := rt.Str("after-block-id") return executeVerifiedDocMutation(rt, "doc.update", "insert_document_block", map[string]any{"nodeId": nodeID, "referenceBlockId": referenceBlockID, "where": "after", "element": block}, nodeID, - "list_document_blocks", map[string]any{"nodeId": nodeID, "format": "element"}, + "list_document_blocks", map[string]any{"nodeId": nodeID, "format": "element", "__allBlocks": true}, func(result, data map[string]any) bool { return verifyInsertedCanonicalBlock(result, data, referenceBlockID, expectedContent, "markdown") }) @@ -684,7 +708,9 @@ func executeVerifiedDocMutation( return docUnknownWriteError(operation, tool, nodeID, err) } steps[0]["status"] = "success" - verification, err := rt.CallMCPData(productDoc, verifyTool, verifyParams) + verification, err := readDocVerification(rt, verifyTool, verifyParams, func(data map[string]any) bool { + return verify == nil || verify(result, data) + }) if err != nil { return docVerificationError(operation, "verify", nodeID, err, append(steps, map[string]any{"name": "verify", "status": "failed"})) } @@ -732,7 +758,9 @@ func executeVerifiedDocContentMutation(rt *shortcut.RuntimeContext, firstParams } steps = append(steps, map[string]any{"name": stepName, "status": "success"}) } - verification, err := rt.CallMCPData(productDoc, "get_document_content", map[string]any{"nodeId": nodeID, "format": format}) + verification, err := readDocVerification(rt, "get_document_content", map[string]any{"nodeId": nodeID, "format": format}, func(data map[string]any) bool { + return verifyUpdatedDocumentContent(data, content, mode, format) + }) if err != nil { return docVerificationError("doc.update", "verify", nodeID, err, append(steps, map[string]any{"name": "verify", "status": "failed"})) } @@ -745,6 +773,134 @@ func executeVerifiedDocContentMutation(rt *shortcut.RuntimeContext, firstParams }, steps...)) } +func readDocVerification(rt *shortcut.RuntimeContext, tool string, rawParams map[string]any, verify func(map[string]any) bool) (map[string]any, error) { + params := cloneMap(rawParams) + allBlocks, _ := params["__allBlocks"].(bool) + delete(params, "__allBlocks") + var last map[string]any + var lastErr error + for attempt := 0; attempt <= len(docVerifyDelays); attempt++ { + var data map[string]any + var err error + if allBlocks && tool == "list_document_blocks" { + data, err = readAllDocumentBlocks(rt, params) + } else { + data, err = rt.CallMCPData(productDoc, tool, params) + } + if err != nil { + lastErr = err + } else { + last = data + lastErr = nil + if verify == nil || verify(data) { + return data, nil + } + } + if attempt < len(docVerifyDelays) { + docVerifySleep(docVerifyDelays[attempt]) + } + } + if lastErr != nil { + return nil, lastErr + } + return last, nil +} + +func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (map[string]any, error) { + all := make([]any, 0, docBlockReadPageSize) + seenPages := map[string]bool{} + for start := 0; start < docBlockReadMaxItems; start += docBlockReadPageSize { + params := cloneMap(base) + params["startIndex"] = start + params["endIndex"] = start + docBlockReadPageSize - 1 + page, err := rt.CallMCPData(productDoc, "list_document_blocks", params) + if err != nil { + return nil, err + } + blocks, ok := documentBlockEntries(page) + if !ok { + return nil, fmt.Errorf("list_document_blocks 回读缺少 blocks 数组") + } + encoded, _ := json.Marshal(blocks) + pageKey := string(encoded) + if pageKey != "[]" && seenPages[pageKey] { + return nil, fmt.Errorf("list_document_blocks 分页停滞，无法证明回读完整") + } + seenPages[pageKey] = true + all = append(all, blocks...) + hasMore, known, _ := docPageState(page) + if known && !hasMore { + return map[string]any{"blocks": all, "hasMore": false, "totalCount": len(all)}, nil + } + if total, ok := nestedNonNegativeInt(page, "totalCount", "total_count"); ok && len(all) >= total { + return map[string]any{"blocks": all, "hasMore": false, "totalCount": total}, nil + } + if !known && len(blocks) < docBlockReadPageSize { + return map[string]any{"blocks": all, "hasMore": false, "totalCount": len(all)}, nil + } + if len(blocks) == 0 { + return nil, fmt.Errorf("list_document_blocks 声明仍有下一页但当前页为空，无法证明回读完整") + } + } + return nil, fmt.Errorf("list_document_blocks 超过 %d 个块，无法在安全上限内完成回读", docBlockReadMaxItems) +} + +func documentBlockEntries(value any) ([]any, bool) { + switch typed := value.(type) { + case map[string]any: + for _, key := range []string{"blocks", "items"} { + if blocks, ok := typed[key].([]any); ok { + return blocks, true + } + } + if encoded, ok := typed["jsonml"].(string); ok { + var decoded any + if json.Unmarshal([]byte(encoded), &decoded) == nil { + blocks := orderedJSONMLBlocks(decoded) + values := make([]any, len(blocks)) + for index := range blocks { + values[index] = blocks[index] + } + return values, true + } + } + for _, key := range []string{"result", "data"} { + if nested, ok := typed[key]; ok { + if blocks, found := documentBlockEntries(nested); found { + return blocks, true + } + } + } + } + return nil, false +} + +func nestedNonNegativeInt(value any, keys ...string) (int, bool) { + switch typed := value.(type) { + case map[string]any: + for _, key := range keys { + if raw, ok := typed[key]; ok { + switch number := raw.(type) { + case float64: + if number >= 0 && number == float64(int(number)) { + return int(number), true + } + case int: + if number >= 0 { + return number, true + } + } + } + } + for _, key := range []string{"result", "data"} { + if result, ok := nestedNonNegativeInt(typed[key], keys...); ok { + return result, true + } + } + } + return 0, false +} + func splitDocMarkdown(content string, maxRunes int) []string { if maxRunes <= 0 { return []string{content} @@ -796,11 +952,17 @@ func containsText(value any, needle string) bool { } func verifyUpdatedDocumentContent(value any, expected, mode, format string) bool { - expected = normalizeDocumentContentForVerification(expected, format) + expectedRaw := expected + expected = normalizeDocumentContentForVerification(expectedRaw, format) for _, candidate := range documentContentCandidates(value, format) { - actual := normalizeDocumentContentForVerification(candidate, format) + actualRaw := candidate + actual := normalizeDocumentContentForVerification(actualRaw, format) if mode == "overwrite" { - if actual == expected { + if actual == expected || (format == "markdown" && stripReadbackDocumentTitle(actual) == expected) { + return true + } + if format == "markdown" && (markdownSemanticallyEquivalent(actualRaw, expectedRaw) || + markdownSemanticallyEquivalent(stripReadbackDocumentTitle(actualRaw), expectedRaw)) { return true } continue @@ -808,10 +970,48 @@ func verifyUpdatedDocumentContent(value any, expected, mode, format string) bool if actual == expected || strings.HasSuffix(actual, "\n"+expected) { return true } + if format == "markdown" && markdownSemanticallyEndsWith(actualRaw, expectedRaw) { + return true + } } return false } +func markdownSemanticallyEquivalent(left, right string) bool { + leftFingerprint, leftOK := markdownSemanticFingerprint(left) + rightFingerprint, rightOK := markdownSemanticFingerprint(right) + return leftOK && rightOK && leftFingerprint == rightFingerprint +} + +func markdownSemanticallyEndsWith(content, suffix string) bool { + contentFingerprint, contentOK := markdownSemanticFingerprint(content) + suffixFingerprint, suffixOK := markdownSemanticFingerprint(suffix) + return contentOK && suffixOK && strings.HasSuffix(contentFingerprint, suffixFingerprint) +} + +func markdownSemanticFingerprint(source string) (string, bool) { + if len(source) > docMarkdownVerifyMax { + return "", false + } + var rendered bytes.Buffer + if err := docMarkdownConvert([]byte(source), &rendered); err != nil { + return "", false + } + return rendered.String(), true +} + +func stripReadbackDocumentTitle(content string) string { + lines := strings.Split(content, "\n") + if len(lines) == 0 || !strings.HasPrefix(strings.TrimSpace(lines[0]), "# ") { + return content + } + lines = lines[1:] + for len(lines) > 0 && strings.TrimSpace(lines[0]) == "" { + lines = lines[1:] + } + return strings.Join(lines, "\n") +} + func verifyInsertedBlock(result, data map[string]any, referenceBlockID, expected, format string) bool { return verifyInsertedCanonicalBlock(result, data, referenceBlockID, normalizeDocumentContentForVerification(expected, format), format) } @@ -848,6 +1048,11 @@ func blockContentEquals(data map[string]any, blockID, expected, format string) b } func canonicalBlockContent(value any, format string) string { + if values, ok := value.(map[string]any); ok { + if element, ok := values["element"].(map[string]any); ok { + value = element + } + } if format == "jsonml" { if values, ok := value.(map[string]any); ok { if encoded, ok := values["jsonml"].(string); ok { @@ -871,7 +1076,7 @@ func canonicalBlockContent(value any, format string) string { return } for key, child := range typed { - if key == "id" || key == "blockId" || key == "uuid" { + if key == "id" || key == "blockId" || key == "uuid" || key == "blockType" { continue } walk(child) @@ -1005,6 +1210,10 @@ func orderedDocumentBlocks(value any) []map[string]any { walk = func(current any) { switch typed := current.(type) { case map[string]any: + if element, ok := typed["element"].(map[string]any); ok && blockIdentity(element, "") != "" { + blocks = append(blocks, element) + return + } if blockIdentity(typed, "") != "" { blocks = append(blocks, typed) return @@ -1065,9 +1274,23 @@ func normalizeDocumentContentForVerification(raw, format string) string { func normalizeMarkdownForVerification(raw string) string { raw = strings.ReplaceAll(strings.ReplaceAll(raw, "\r\n", "\n"), "\r", "\n") lines := make([]string, 0, strings.Count(raw, "\n")+1) + inFence := false for _, line := range strings.Split(raw, "\n") { - line = strings.TrimSpace(line) + trimmed := strings.TrimSpace(line) + if strings.HasPrefix(trimmed, "```") || strings.HasPrefix(trimmed, "~~~") { + inFence = !inFence + lines = append(lines, trimmed) + continue + } + if inFence { + lines = append(lines, strings.TrimRight(line, " \t")) + continue + } + line = trimmed if line == "" { + if len(lines) > 0 && lines[len(lines)-1] != "" { + lines = append(lines, "") + } continue } if strings.Contains(line, "|") { @@ -1081,6 +1304,9 @@ func normalizeMarkdownForVerification(raw string) string { } lines = append(lines, line) } + for len(lines) > 0 && lines[len(lines)-1] == "" { + lines = lines[:len(lines)-1] + } return strings.Join(lines, "\n") } @@ -1089,33 +1315,75 @@ func normalizeJSONMLForVerification(raw string) string { if err := json.Unmarshal([]byte(raw), &value); err != nil { return normalizeMarkdownForVerification(raw) } - var tokens []string - var walk func(any) - walk = func(current any) { + var normalize func(any) any + normalize = func(current any) any { switch typed := current.(type) { case []any: - start := 0 - if len(typed) > 0 { - if tag, ok := typed[0].(string); ok { - tokens = append(tokens, "<"+strings.ToLower(strings.TrimSpace(tag))+">") - start = 1 + if len(typed) == 0 { + return []any{} + } + tag, isElement := typed[0].(string) + if !isElement { + out := make([]any, 0, len(typed)) + for _, child := range typed { + out = append(out, normalize(child)) + } + return out + } + start := 1 + attrs := map[string]any{} + if len(typed) > 1 { + if declared, ok := typed[1].(map[string]any); ok { + attrs, _ = normalize(declared).(map[string]any) + start = 2 } } + children := make([]any, 0, len(typed)-start) for _, child := range typed[start:] { - walk(child) + normalized := normalize(child) + if normalized != nil { + children = append(children, normalized) + } } + if strings.EqualFold(tag, "span") && isGeneratedTextSpan(attrs) { + if len(children) == 1 { + return children[0] + } + return children + } + out := []any{strings.ToLower(tag), attrs} + out = append(out, children...) + return out case map[string]any: - // JSONML maps contain element attributes. Server-generated UUIDs and - // default attributes do not change the authored document content. - return - case string: - if text := normalizeMarkdownForVerification(typed); text != "" { - tokens = append(tokens, text) + out := make(map[string]any, len(typed)) + for key, child := range typed { + normalizedKey := strings.ToLower(strings.NewReplacer("_", "", "-", "").Replace(key)) + if normalizedKey == "uuid" || normalizedKey == "blockid" || normalizedKey == "elementid" || normalizedKey == "index" { + continue + } + out[key] = normalize(child) } + return out + case string: + return strings.ReplaceAll(strings.ReplaceAll(typed, "\r\n", "\n"), "\r", "\n") } + return current } - walk(value) - return strings.Join(tokens, "\n") + // normalize only receives values decoded by encoding/json, so the resulting + // tree is always JSON-marshalable. + encoded, _ := json.Marshal(normalize(value)) + return string(encoded) +} + +func isGeneratedTextSpan(attrs map[string]any) bool { + if len(attrs) == 0 { + return true + } + if len(attrs) != 1 { + return false + } + value, ok := attrs["data-type"].(string) + return ok && (value == "text" || value == "leaf") } func executeExport(rt *shortcut.RuntimeContext) error { diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go new file mode 100644 index 00000000..0c5dc10c --- /dev/null +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -0,0 +1,275 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package doc + +import ( + "errors" + "fmt" + "io" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" +) + +func TestCrossPlatformCoverageDocReadbackRetriesStaleContent(t *testing.T) { + testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyDelays, []time.Duration{time.Millisecond}) + caller := &docCoverageCaller{responses: map[string][]map[string]any{ + "get_document_content": {{"markdown": "old"}, {"markdown": "old\nnew"}}, + }} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "append", "--content", "new", "--yes"); err != nil { + t.Fatal(err) + } + reads := 0 + for _, call := range caller.history { + if call.tool == "get_document_content" { + reads++ + } + } + if reads != 2 { + t.Fatalf("readback calls = %d, want 2; history=%#v", reads, caller.history) + } +} + +func TestCrossPlatformCoverageDocDeleteReadbackConsumesEveryPage(t *testing.T) { + testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyDelays, []time.Duration{time.Millisecond}) + firstPage := make([]any, 50) + for index := range firstPage { + firstPage[index] = map[string]any{"id": fmt.Sprintf("block-%d", index), "text": "body"} + } + caller := &docCoverageCaller{responses: map[string][]map[string]any{ + "list_document_blocks": { + {"blocks": firstPage, "hasMore": true, "totalCount": 51}, + {"blocks": []any{map[string]any{"id": "target", "text": "stale"}}, "hasMore": false, "totalCount": 51}, + {"blocks": firstPage, "hasMore": false, "totalCount": 50}, + }, + }} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes"); err != nil { + t.Fatal(err) + } + starts := []int{} + for _, call := range caller.history { + if call.tool == "list_document_blocks" { + starts = append(starts, call.params["startIndex"].(int)) + } + } + if fmt.Sprint(starts) != "[0 50 0]" { + t.Fatalf("pagination starts = %v, want [0 50 0]", starts) + } +} + +func TestCrossPlatformCoverageDocReplacePreflightIsGloballyUnique(t *testing.T) { + firstPage := make([]any, 50) + for index := range firstPage { + text := "body" + if index == 0 { + text = "unique needle" + } + firstPage[index] = map[string]any{"id": fmt.Sprintf("block-%d", index), "text": text} + } + caller := &docCoverageCaller{responses: map[string][]map[string]any{ + "list_document_blocks": { + {"blocks": firstPage, "hasMore": true, "totalCount": 51}, + {"blocks": []any{map[string]any{"id": "block-50", "text": "another needle"}}, "hasMore": false, "totalCount": 51}, + }, + }} + err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "str_replace", "--old", "needle", "--new", "changed", "--yes") + if err == nil { + t.Fatal("str_replace accepted a second match on a later page") + } + for _, call := range caller.history { + if call.tool == "update_document_block" { + t.Fatalf("ambiguous replace executed a write: %#v", caller.history) + } + } +} + +func TestCrossPlatformCoverageDocVerificationPreservesMeaning(t *testing.T) { + expected := "[\"p\",{},\"text\"]" + serverExpanded := "[\"p\",{\"uuid\":\"generated\"},[\"span\",{\"data-type\":\"text\"},[\"span\",{\"data-type\":\"leaf\"},\"text\"]]]" + if normalizeJSONMLForVerification(expected) != normalizeJSONMLForVerification(serverExpanded) { + t.Fatal("generated JSONML text wrappers should not change document meaning") + } + linkA := "[\"a\",{\"href\":\"https://example.com/a\"},\"text\"]" + linkB := "[\"a\",{\"href\":\"https://example.com/b\"},\"text\"]" + if normalizeJSONMLForVerification(linkA) == normalizeJSONMLForVerification(linkB) { + t.Fatal("semantic JSONML attributes were ignored") + } + codeA := "~~~go\n return nil\n~~~" + codeB := "~~~go\nreturn nil\n~~~" + if normalizeMarkdownForVerification(codeA) == normalizeMarkdownForVerification(codeB) { + t.Fatal("fenced code indentation was ignored") + } + if !verifyUpdatedDocumentContent(map[string]any{"markdown": "# Server title\n\nbody"}, "body", "overwrite", "markdown") { + t.Fatal("server-generated document title prevented body verification") + } +} + +func TestCrossPlatformCoverageMarkdownSemanticRoundTrip(t *testing.T) { + input := strings.Join([]string{ + "sales_data.xlsx", + "### 1.", + "+10.22%", + "| name | value |", + "| -------- | -------- |", + "| sales_data.xlsx | +10.22% |", + }, "\n") + server := strings.Join([]string{ + `sales\_data.xlsx`, + `### 1\.`, + `\+10.22%`, + "|name|value|", + "|---|---|", + `|sales\_data.xlsx|\+10.22%|`, + }, "\n") + if !markdownSemanticallyEquivalent(input, server) { + t.Fatal("server Markdown escaping and table delimiter normalization changed the semantic fingerprint") + } + if !verifyUpdatedDocumentContent(map[string]any{"markdown": server}, input, "overwrite", "markdown") { + t.Fatal("equivalent server Markdown failed overwrite verification") + } + if !verifyUpdatedDocumentContent(map[string]any{"markdown": "existing\n\n" + server}, input, "append", "markdown") { + t.Fatal("equivalent server Markdown failed append verification") + } +} + +func TestCrossPlatformCoverageMarkdownSemanticDifferencesRemainStrict(t *testing.T) { + for _, test := range []struct { + name string + left string + right string + }{ + {name: "emphasis", left: `*important*`, right: `\*important\*`}, + {name: "inline code", left: "`sales_data`", right: "`sales\\_data`"}, + {name: "fenced code", left: "```\nsales_data\n```", right: "```\nsales\\_data\n```"}, + {name: "table alignment", left: "|a|\n|---|\n|x|", right: "|a|\n|:---|\n|x|"}, + {name: "table columns", left: "|a|b|\n|---|---|\n|x|y|", right: "|a|\n|---|\n|x|"}, + {name: "table content", left: "|a|\n|---|\n|x|", right: "|a|\n|---|\n|y|"}, + } { + t.Run(test.name, func(t *testing.T) { + if markdownSemanticallyEquivalent(test.left, test.right) { + t.Fatal("meaningful Markdown difference was ignored") + } + }) + } + oversized := strings.Repeat("x", docMarkdownVerifyMax+1) + if _, ok := markdownSemanticFingerprint(oversized); ok { + t.Fatal("oversized Markdown entered semantic verification") + } + testseam.Swap(t, &docMarkdownConvert, func([]byte, io.Writer) error { return errors.New("render") }) + if _, ok := markdownSemanticFingerprint("body"); ok { + t.Fatal("failed Markdown render produced a semantic fingerprint") + } +} + +func TestCrossPlatformCoverageDocElementReadbackUsesNestedElement(t *testing.T) { + wrapper := map[string]any{ + "blockType": "paragraph", + "element": map[string]any{"id": "inserted", "blockType": "paragraph", "paragraph": map[string]any{"text": "body"}}, + } + if got := canonicalBlockContent(wrapper, "markdown"); got != "body" { + t.Fatalf("nested element content = %q, want body", got) + } + blocks := orderedDocumentBlocks(map[string]any{"blocks": []any{wrapper}}) + if len(blocks) != 1 || blockIdentity(blocks[0], "") != "inserted" { + t.Fatalf("nested element blocks = %#v", blocks) + } +} + +func TestCrossPlatformCoverageVersionRevertRequiresTargetEvidence(t *testing.T) { + if revertResultMatchesVersion(map[string]any{"ok": true}, 3) || currentDocumentMatchesRestoredVersion(map[string]any{"version": 99}, 3) { + t.Fatal("readability or an unrelated current version must not prove a revert") + } + if !revertResultMatchesVersion(map[string]any{"revertedToVersion": 3}, 3) { + t.Fatal("explicit target-version acknowledgement was not accepted") + } +} + +func TestCrossPlatformCoverageDocReadbackDefensiveEdges(t *testing.T) { + testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + for _, tc := range []struct { + name string + responses []map[string]any + failAt int + }{ + {"call failure", nil, 1}, + {"missing blocks", []map[string]any{{"ok": true}}, 0}, + {"stalled page", []map[string]any{{"blocks": []any{map[string]any{"id": "a"}}, "hasMore": true}, {"blocks": []any{map[string]any{"id": "a"}}, "hasMore": true}}, 0}, + {"empty continued page", []map[string]any{{"blocks": []any{}, "hasMore": true}}, 0}, + } { + t.Run(tc.name, func(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) + caller := &docCoverageCaller{failAt: tc.failAt, responses: map[string][]map[string]any{"list_document_blocks": tc.responses}} + err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes") + if err == nil { + t.Fatal("defensive readback unexpectedly succeeded") + } + }) + } + + t.Run("total count terminates pagination", func(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) + caller := &docCoverageCaller{responses: map[string][]map[string]any{"list_document_blocks": {{"blocks": []any{map[string]any{"id": "other"}}, "totalCount": 1}}}} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes"); err != nil { + t.Fatal(err) + } + }) + + t.Run("block read safety limit", func(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) + pages := make([]map[string]any, docBlockReadMaxItems/docBlockReadPageSize) + for index := range pages { + pages[index] = map[string]any{"blocks": []any{map[string]any{"id": fmt.Sprintf("block-%d", index)}}, "hasMore": true} + } + caller := &docCoverageCaller{responses: map[string][]map[string]any{"list_document_blocks": pages}} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes"); err == nil { + t.Fatal("oversized block read returned nil") + } + }) + + if blocks, ok := documentBlockEntries(map[string]any{"jsonml": `["root",{},["p",{"uuid":"a"},"x"]]`}); !ok || len(blocks) == 0 { + t.Fatalf("jsonml blocks=%#v ok=%v", blocks, ok) + } + if _, ok := documentBlockEntries(map[string]any{"jsonml": `{`}); ok { + t.Fatal("invalid jsonml produced blocks") + } + if blocks, ok := documentBlockEntries(map[string]any{"data": map[string]any{"items": []any{"x"}}}); !ok || len(blocks) != 1 { + t.Fatalf("nested items=%#v ok=%v", blocks, ok) + } + if _, ok := documentBlockEntries(nil); ok { + t.Fatal("nil produced blocks") + } + + for _, tc := range []struct { + value any + want bool + }{ + {map[string]any{"totalCount": float64(2)}, true}, + {map[string]any{"totalCount": float64(-1)}, false}, + {map[string]any{"totalCount": 2.5}, false}, + {map[string]any{"data": map[string]any{"total_count": 2}}, true}, + {map[string]any{"totalCount": -1}, false}, + {nil, false}, + } { + _, ok := nestedNonNegativeInt(tc.value, "totalCount", "total_count") + if ok != tc.want { + t.Fatalf("nestedNonNegativeInt(%#v) ok=%v want=%v", tc.value, ok, tc.want) + } + } + + for _, raw := range []string{ + `[]`, `[1,["p",{},"x"]]`, `["span",{},"a","b"]`, + `["p",{"block_id":"x","custom":true},"x"]`, `true`, + } { + if normalizeJSONMLForVerification(raw) == "" { + t.Fatalf("empty normalized JSONML for %s", raw) + } + } + if !isGeneratedTextSpan(nil) || isGeneratedTextSpan(map[string]any{"a": 1, "b": 2}) || isGeneratedTextSpan(map[string]any{"data-type": 3}) || isGeneratedTextSpan(map[string]any{"data-type": "other"}) { + t.Fatal("generated span classification failed") + } +} diff --git a/internal/shortcut/doc/doc_shortcuts_test.go b/internal/shortcut/doc/doc_shortcuts_test.go index 0ef06fab..81e2e238 100644 --- a/internal/shortcut/doc/doc_shortcuts_test.go +++ b/internal/shortcut/doc/doc_shortcuts_test.go @@ -15,6 +15,7 @@ import ( "strings" "sync" "testing" + "time" "unicode/utf8" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" @@ -112,6 +113,7 @@ func runDocCoverageInput(t *testing.T, declaration shortcut.Shortcut, caller *do func runDocCoveragePath(t *testing.T, declaration shortcut.Shortcut, caller *docCoverageCaller, input io.Reader, commandPath string, args ...string) error { t.Helper() + testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) helpers.InitDeps(caller) root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} root.PersistentFlags().Bool("yes", false, "") @@ -491,6 +493,7 @@ func TestCrossPlatformCoverageDocUpdateAliasReachesNestedBranches(t *testing.T) } func TestCrossPlatformCoverageDocWritesStopOnUnknownCommitAndRequireVerification(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) unknown := &docCoverageCaller{failAt: 1, responses: map[string][]map[string]any{}} err := runDocCoverage(t, Update, unknown, "--node", "n", "--command", "append", "--content", "x", "--yes") var typed *apperrors.Error @@ -512,6 +515,7 @@ func TestCrossPlatformCoverageDocWritesStopOnUnknownCommitAndRequireVerification } func TestCrossPlatformCoverageDocCreateRejectsSuccessfulMismatchedReadback(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) caller := &docCoverageCaller{responses: map[string][]map[string]any{ "get_document_content": {{"markdown": "truncated"}}, }} @@ -577,8 +581,15 @@ func TestCrossPlatformCoverageDocVersionRevertPaginationAndVerification(t *testi "revert_doc_version": {{}}, "get_document_info": {{"nodeId": "n", "revision": 99.0}}, }} - if err := runDocCoverage(t, VersionRevert, caller, "--node", "n", "--version", "3", "--yes"); err != nil { - t.Fatal(err) + err := runDocCoverage(t, VersionRevert, caller, "--node", "n", "--version", "3", "--yes") + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "doc_history_revert_target_unproven" || typed.FailureStage != "verify" || typed.Details["status"] != "partial_success" { + t.Fatalf("unproven revert error = %#v", err) + } + data, _ := typed.Details["data"].(map[string]any) + steps, _ := typed.Details["steps"].([]map[string]any) + if data["verified"] != false || len(steps) != 3 || steps[2]["status"] != "failed" { + t.Fatalf("unproven revert details = %#v", typed.Details) } }) diff --git a/internal/shortcut/doc/history_template_shortcuts.go b/internal/shortcut/doc/history_template_shortcuts.go index ea9ac94d..048ae9bd 100644 --- a/internal/shortcut/doc/history_template_shortcuts.go +++ b/internal/shortcut/doc/history_template_shortcuts.go @@ -178,15 +178,47 @@ func executeHistoryRevert(rt *shortcut.RuntimeContext) error { map[string]any{"available": false, "reason": "the requested revert completed; verify the current document before any further write"}, ) } + verified := revertResultMatchesVersion(reverted, target) || currentDocumentMatchesRestoredVersion(current, target) + if !verified { + return docPartialWriteError( + "doc.history_revert", "doc_history_revert_target_unproven", "verify", + fmt.Sprintf("版本 %d 的回滚请求已执行且文档可读，但响应没有提供目标版本证据；不要直接重试回滚", target), + fmt.Errorf("回读缺少目标版本 %d 的明确证据", target), + map[string]any{ + "nodeId": nodeID, "version": target, "reverted": true, "verified": false, + "revertResult": reverted, "current": current, + }, + []map[string]any{ + {"name": "preflight", "status": "success"}, + {"name": "revert", "status": "success"}, + {"name": "verify", "status": "failed"}, + }, + map[string]any{"available": false, "reason": "the revert may have completed; inspect version history before any further revert"}, + ) + } return rt.Output(docEnvelope("doc.history_revert", map[string]any{ "version": target, "revertResult": reverted, "current": current, "verified": true, - "verification": "revert_acknowledged_and_document_readable", + "verification": "target_version_proven", }, map[string]any{"name": "preflight", "status": "success"}, map[string]any{"name": "revert", "status": "success"}, map[string]any{"name": "verify", "status": "success"})) } +func revertResultMatchesVersion(value map[string]any, target int) bool { + return versionEvidenceMatches(value, target, map[string]bool{ + "version": true, "targetversion": true, "appliedversion": true, + "restoredversion": true, "revertedversion": true, "revertedtoversion": true, "sourceversion": true, + }) +} + +func currentDocumentMatchesRestoredVersion(value map[string]any, target int) bool { + return versionEvidenceMatches(value, target, map[string]bool{ + "restoredfromversion": true, "revertedfromversion": true, + "sourceversion": true, "appliedversion": true, "targetversion": true, + }) +} + func findHistoryVersion(rt *shortcut.RuntimeContext, nodeID string, target int) (bool, error) { const maxPages = 20 cursor := "" From c6ebe307cd843cefda01448fc3417389cfa62ccd Mon Sep 17 00:00:00 2001 From: Dennis Date: Wed, 12 Aug 2026 19:46:52 +0800 Subject: [PATCH 168/250] fix(doc): verify inline media from jsonml readback --- internal/helpers/doc.go | 23 ++++++++++++++++++--- internal/helpers/doc_command_edges_test.go | 24 ++++++++++++++++++++-- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index d1c9ce4c..9a86e5e5 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -758,7 +758,7 @@ func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, seen := map[string]bool{} for start := 0; start < maxItems; start += pageSize { text, err := callMCPToolReturnTextOnServer(ctx, "doc", "list_document_blocks", map[string]any{ - "nodeId": nodeID, "format": "element", "startIndex": start, "endIndex": start + pageSize - 1, + "nodeId": nodeID, "format": "jsonml", "startIndex": start, "endIndex": start + pageSize - 1, }) if err != nil { return nil, err @@ -834,16 +834,33 @@ func findVerifiedMediaBlock(blocks []any, blockID, resourceID, resourceURL strin if candidateID == "" || (blockID != "" && candidateID != blockID) { continue } - if resourceID != "" && nestedDocString(value, "resourceId") == resourceID { + mediaValue := docMediaReadbackValue(value) + if resourceID != "" && nestedDocString(mediaValue, "resourceId") == resourceID { return candidateID } - if resourceID == "" && resourceURL != "" && nestedDocString(value, "resourceUrl") == resourceURL { + if resourceURL != "" && nestedDocString(mediaValue, "resourceUrl", "src") == resourceURL { return candidateID } } return "" } +func docMediaReadbackValue(value any) any { + block, ok := value.(map[string]any) + if !ok { + return value + } + encoded, ok := block["jsonml"].(string) + if !ok || strings.TrimSpace(encoded) == "" { + return value + } + var decoded any + if json.Unmarshal([]byte(encoded), &decoded) != nil { + return value + } + return decoded +} + func docNumberAsInt(value any) (int, bool) { switch typed := value.(type) { case float64: diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index 17ab60ca..e4c21f25 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -206,6 +206,23 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { t.Fatal("invalid media insert response returned nil") } }) + t.Run("small image verifies src readback when upload also returns resource ID", func(t *testing.T) { + httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`}, + {text: `{"blockId":"media-block"}`}, + {text: `{"blocks":[{"blockId":"media-block","jsonml":"[\"p\",{\"uuid\":\"media-block\"},[\"img\",{\"src\":\"https://image\"}]]"}],"hasMore":false}`}, + }} + if err := mediaCommand(t, caller, file, "image/png"); err != nil { + t.Fatal(err) + } + if caller.calls != 3 { + t.Fatalf("media insert calls = %d, want credential, insert, and one readback", caller.calls) + } + if caller.args["format"] != "jsonml" { + t.Fatalf("media readback format = %#v, want jsonml", caller.args["format"]) + } + }) t.Run("large image becomes attachment", func(t *testing.T) { httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } large := filepath.Join(t.TempDir(), "large.png") @@ -337,10 +354,13 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { if nestedDocString(map[string]any{"x": []any{map[string]any{"id": " nested "}}}, "id") != "nested" || nestedDocString(3, "id") != "" { t.Fatal("nested string traversal failed") } - blocks := []any{map[string]any{"id": "block", "resourceId": "rid"}, map[string]any{"id": "url-block", "resourceUrl": "https://media"}} - if findVerifiedMediaBlock(blocks, "block", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "", "https://media") != "url-block" || findVerifiedMediaBlock(blocks, "block", "wrong", "") != "" || findVerifiedMediaBlock(blocks, "", "missing", "") != "" { + blocks := []any{map[string]any{"id": "block", "resourceId": "rid"}, map[string]any{"id": "url-block", "resourceUrl": "https://media"}, map[string]any{"id": "src-block", "jsonml": `["p",{},["img",{"src":"https://image"}]]`}} + if findVerifiedMediaBlock(blocks, "block", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "", "https://media") != "url-block" || findVerifiedMediaBlock(blocks, "src-block", "upload-resource", "https://image") != "src-block" || findVerifiedMediaBlock(blocks, "other-block", "upload-resource", "https://image") != "" || findVerifiedMediaBlock(blocks, "block", "wrong", "") != "" || findVerifiedMediaBlock(blocks, "", "missing", "") != "" { t.Fatal("media block matching failed") } + if findVerifiedMediaBlock([]any{map[string]any{"id": "bad-jsonml", "jsonml": `[`}}, "bad-jsonml", "", "https://image") != "" { + t.Fatal("invalid JSONML unexpectedly verified") + } for _, tc := range []struct { value any want bool From 1083093cbce1cd3647341e22fa37be7c14ad13c7 Mon Sep 17 00:00:00 2001 From: Dennis Date: Thu, 13 Aug 2026 00:13:27 +0800 Subject: [PATCH 169/250] test(doc): complete readback coverage evidence --- .changes/960-doc-readback-verification.md | 5 +++++ internal/helpers/doc_command_edges_test.go | 3 +++ 2 files changed, 8 insertions(+) create mode 100644 .changes/960-doc-readback-verification.md diff --git a/.changes/960-doc-readback-verification.md b/.changes/960-doc-readback-verification.md new file mode 100644 index 00000000..06467959 --- /dev/null +++ b/.changes/960-doc-readback-verification.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index e4c21f25..a9e775d6 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -361,6 +361,9 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { if findVerifiedMediaBlock([]any{map[string]any{"id": "bad-jsonml", "jsonml": `[`}}, "bad-jsonml", "", "https://image") != "" { t.Fatal("invalid JSONML unexpectedly verified") } + if got := docMediaReadbackValue("plain"); got != "plain" { + t.Fatalf("non-object media readback = %#v, want unchanged value", got) + } for _, tc := range []struct { value any want bool From a62332be9312b467c790b79c6477f0fc189f1c9d Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 10:13:54 +0800 Subject: [PATCH 170/250] fix(doc): trust only explicit inserted block IDs --- internal/helpers/doc.go | 21 ++++++++++++++++++++- internal/helpers/doc_command_edges_test.go | 20 ++++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index 9a86e5e5..815a432d 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -674,7 +674,7 @@ func runMediaInsert(cmd *cobra.Command, _ []string) error { fmt.Errorf("解析 insert_document_block 响应失败: %w", err)) } } - insertedBlockID := nestedDocString(insertResult, "blockId", "elementId", "id") + insertedBlockID := insertedDocBlockID(insertResult) deps.Out.PrintInfo("[4/4] 回读验证媒体块...") verifiedBlockID, verifyErr := verifyInsertedDocMedia(ctx, nodeID, insertedBlockID, resourceID, resourceURL) @@ -828,6 +828,25 @@ func nestedDocString(value any, keys ...string) string { return "" } +// insertedDocBlockID only accepts explicit block IDs from the insert result or +// known response wrappers. Arbitrary IDs may belong to the document, operator, +// or request and must not become a hard constraint for the media readback. +func insertedDocBlockID(data map[string]any) string { + for _, key := range []string{"blockId", "elementId"} { + if text, ok := data[key].(string); ok && strings.TrimSpace(text) != "" { + return strings.TrimSpace(text) + } + } + for _, wrapper := range []string{"result", "data", "content"} { + if inner, ok := data[wrapper].(map[string]any); ok { + if text := insertedDocBlockID(inner); text != "" { + return text + } + } + } + return "" +} + func findVerifiedMediaBlock(blocks []any, blockID, resourceID, resourceURL string) string { for _, value := range blocks { candidateID := nestedDocString(value, "blockId", "id", "uuid") diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index a9e775d6..ef894c38 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -223,6 +223,20 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { t.Fatalf("media readback format = %#v, want jsonml", caller.args["format"]) } }) + t.Run("unrelated insert response IDs do not constrain media readback", func(t *testing.T) { + httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"uploadUrl":"https://upload","resourceId":"resource","resourceUrl":"https://image"}`}, + {text: `{"id":"document-id","operator":{"id":"operator-id"},"data":{"request":{"id":"request-id"}}}`}, + {text: `{"blocks":[{"blockId":"media-block","jsonml":"[\"p\",{\"uuid\":\"media-block\"},[\"img\",{\"src\":\"https://image\"}]]"}],"hasMore":false}`}, + }} + if err := mediaCommand(t, caller, file, "image/png"); err != nil { + t.Fatal(err) + } + if caller.calls != 3 { + t.Fatalf("media insert calls = %d, want credential, insert, and one readback", caller.calls) + } + }) t.Run("large image becomes attachment", func(t *testing.T) { httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } large := filepath.Join(t.TempDir(), "large.png") @@ -354,6 +368,12 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { if nestedDocString(map[string]any{"x": []any{map[string]any{"id": " nested "}}}, "id") != "nested" || nestedDocString(3, "id") != "" { t.Fatal("nested string traversal failed") } + if got := insertedDocBlockID(map[string]any{"id": "document", "result": map[string]any{"data": map[string]any{"blockId": " block "}}}); got != "block" { + t.Fatalf("trusted inserted block ID = %q, want block", got) + } + if got := insertedDocBlockID(map[string]any{"id": "document", "operator": map[string]any{"id": "operator"}, "data": map[string]any{"request": map[string]any{"id": "request"}}}); got != "" { + t.Fatalf("untrusted inserted block ID = %q, want empty", got) + } blocks := []any{map[string]any{"id": "block", "resourceId": "rid"}, map[string]any{"id": "url-block", "resourceUrl": "https://media"}, map[string]any{"id": "src-block", "jsonml": `["p",{},["img",{"src":"https://image"}]]`}} if findVerifiedMediaBlock(blocks, "block", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "rid", "") != "block" || findVerifiedMediaBlock(blocks, "", "", "https://media") != "url-block" || findVerifiedMediaBlock(blocks, "src-block", "upload-resource", "https://image") != "src-block" || findVerifiedMediaBlock(blocks, "other-block", "upload-resource", "https://image") != "" || findVerifiedMediaBlock(blocks, "block", "wrong", "") != "" || findVerifiedMediaBlock(blocks, "", "missing", "") != "" { t.Fatal("media block matching failed") From 2db73a818565845fef0e5deedb5dd997fabcc7ac Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 10:55:00 +0800 Subject: [PATCH 171/250] fix(doc): distinguish identical pagination pages --- internal/helpers/doc.go | 51 +++++++++++++++++-- internal/helpers/doc_command_edges_test.go | 22 ++++++++ internal/shortcut/doc/content_shortcuts.go | 38 ++++++++++++-- .../doc/doc_readback_verification_test.go | 24 +++++++++ 4 files changed, 125 insertions(+), 10 deletions(-) diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index 815a432d..ecad5e5a 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -755,7 +755,7 @@ func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, const pageSize = 50 const maxItems = 5000 all := make([]any, 0, pageSize) - seen := map[string]bool{} + seenPageIdentities := map[string]bool{} for start := 0; start < maxItems; start += pageSize { text, err := callMCPToolReturnTextOnServer(ctx, "doc", "list_document_blocks", map[string]any{ "nodeId": nodeID, "format": "jsonml", "startIndex": start, "endIndex": start + pageSize - 1, @@ -772,12 +772,13 @@ func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, if !ok { return nil, fmt.Errorf("list_document_blocks 回读缺少 blocks 数组") } - encoded, _ := json.Marshal(blocks) - key := string(encoded) - if key != "[]" && seen[key] { + pageIdentity := docBlockPageIdentity(blocks) + if pageIdentity != "" && seenPageIdentities[pageIdentity] { return nil, fmt.Errorf("list_document_blocks 分页停滞") } - seen[key] = true + if pageIdentity != "" { + seenPageIdentities[pageIdentity] = true + } all = append(all, blocks...) hasMore, hasMoreKnown := payload["hasMore"].(bool) if hasMoreKnown && !hasMore { @@ -796,6 +797,46 @@ func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, return nil, fmt.Errorf("文档块超过安全回读上限") } +func docBlockPageIdentity(blocks []any) string { + if len(blocks) == 0 { + return "" + } + ids := make([]string, 0, len(blocks)) + for _, value := range blocks { + id := "" + switch block := value.(type) { + case map[string]any: + id = directDocBlockIdentity(block) + if id == "" { + if element, ok := block["element"].(map[string]any); ok { + id = directDocBlockIdentity(element) + } + } + case []any: + if len(block) > 1 { + if attributes, ok := block[1].(map[string]any); ok { + id = directDocBlockIdentity(attributes) + } + } + } + if id == "" { + return "" + } + ids = append(ids, id) + } + encoded, _ := json.Marshal(ids) + return string(encoded) +} + +func directDocBlockIdentity(block map[string]any) string { + for _, key := range []string{"blockId", "id", "uuid", "elementId"} { + if text, ok := block[key].(string); ok && strings.TrimSpace(text) != "" { + return strings.TrimSpace(text) + } + } + return "" +} + func nestedDocMap(data map[string]any) map[string]any { for _, key := range []string{"result", "data"} { if nested, ok := data[key].(map[string]any); ok { diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index ef894c38..bfd7aec2 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -3,6 +3,7 @@ package helpers import ( "bytes" "context" + "encoding/json" "errors" "fmt" "io" @@ -318,6 +319,27 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { } }) + t.Run("identical adjacent pages advance by requested indexes", func(t *testing.T) { + blocks := make([]any, 50) + for index := range blocks { + blocks[index] = map[string]any{"blockType": "paragraph"} + } + first, err := json.Marshal(map[string]any{"blocks": blocks, "hasMore": true, "totalCount": 100}) + if err != nil { + t.Fatal(err) + } + second, err := json.Marshal(map[string]any{"blocks": blocks, "hasMore": false, "totalCount": 100}) + if err != nil { + t.Fatal(err) + } + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: string(first)}, {text: string(second)}}} + installScriptedCaller(t, caller) + got, err := readAllDocBlocksForVerification(ctx, "node") + if err != nil || len(got) != 100 || caller.calls != 2 { + t.Fatalf("blocks=%d calls=%d err=%v, want 100 blocks from two pages", len(got), caller.calls, err) + } + }) + t.Run("unknown pagination short page", func(t *testing.T) { installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"id":"a"}]}`}}}) if blocks, err := readAllDocBlocksForVerification(ctx, "node"); err != nil || len(blocks) != 1 { diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 1232088e..74ae46bd 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -808,7 +808,7 @@ func readDocVerification(rt *shortcut.RuntimeContext, tool string, rawParams map func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (map[string]any, error) { all := make([]any, 0, docBlockReadPageSize) - seenPages := map[string]bool{} + seenPageIdentities := map[string]bool{} for start := 0; start < docBlockReadMaxItems; start += docBlockReadPageSize { params := cloneMap(base) params["startIndex"] = start @@ -821,12 +821,13 @@ func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (ma if !ok { return nil, fmt.Errorf("list_document_blocks 回读缺少 blocks 数组") } - encoded, _ := json.Marshal(blocks) - pageKey := string(encoded) - if pageKey != "[]" && seenPages[pageKey] { + pageIdentity := documentBlockPageIdentity(blocks) + if pageIdentity != "" && seenPageIdentities[pageIdentity] { return nil, fmt.Errorf("list_document_blocks 分页停滞，无法证明回读完整") } - seenPages[pageKey] = true + if pageIdentity != "" { + seenPageIdentities[pageIdentity] = true + } all = append(all, blocks...) hasMore, known, _ := docPageState(page) if known && !hasMore { @@ -845,6 +846,33 @@ func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (ma return nil, fmt.Errorf("list_document_blocks 超过 %d 个块，无法在安全上限内完成回读", docBlockReadMaxItems) } +func documentBlockPageIdentity(blocks []any) string { + if len(blocks) == 0 { + return "" + } + ids := make([]string, 0, len(blocks)) + for _, value := range blocks { + id := "" + switch block := value.(type) { + case map[string]any: + id = blockIdentity(block, "") + if id == "" { + if element, ok := block["element"].(map[string]any); ok { + id = blockIdentity(element, "") + } + } + case []any: + id = jsonMLBlockIdentity(block) + } + if id == "" { + return "" + } + ids = append(ids, id) + } + encoded, _ := json.Marshal(ids) + return string(encoded) +} + func documentBlockEntries(value any) ([]any, bool) { switch typed := value.(type) { case map[string]any: diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index 0c5dc10c..6f852b4d 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -211,6 +211,30 @@ func TestCrossPlatformCoverageDocReadbackDefensiveEdges(t *testing.T) { }) } + t.Run("identical adjacent pages advance by requested indexes", func(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) + blocks := make([]any, docBlockReadPageSize) + for index := range blocks { + blocks[index] = map[string]any{"blockType": "paragraph"} + } + caller := &docCoverageCaller{responses: map[string][]map[string]any{"list_document_blocks": { + {"blocks": blocks, "hasMore": true, "totalCount": 2 * docBlockReadPageSize}, + {"blocks": blocks, "hasMore": false, "totalCount": 2 * docBlockReadPageSize}, + }}} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes"); err != nil { + t.Fatal(err) + } + starts := []int{} + for _, call := range caller.history { + if call.tool == "list_document_blocks" { + starts = append(starts, call.params["startIndex"].(int)) + } + } + if fmt.Sprint(starts) != "[0 50]" { + t.Fatalf("pagination starts = %v, want [0 50]", starts) + } + }) + t.Run("total count terminates pagination", func(t *testing.T) { testseam.Swap(t, &docVerifyDelays, []time.Duration{}) caller := &docCoverageCaller{responses: map[string][]map[string]any{"list_document_blocks": {{"blocks": []any{map[string]any{"id": "other"}}, "totalCount": 1}}}} From 7ffbbc4a51cad222ddf676fcf2accf568d8c71c8 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 11:21:43 +0800 Subject: [PATCH 172/250] test(doc): cover stable pagination identities --- internal/helpers/doc_command_edges_test.go | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index bfd7aec2..e20d4151 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -340,6 +340,15 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { } }) + t.Run("page identity accepts nested and JSONML block IDs", func(t *testing.T) { + if got := docBlockPageIdentity([]any{map[string]any{"element": map[string]any{"blockId": "nested-block"}}}); got != `["nested-block"]` { + t.Fatalf("nested block page identity = %q", got) + } + if got := docBlockPageIdentity([]any{[]any{"p", map[string]any{"uuid": "jsonml-block"}}}); got != `["jsonml-block"]` { + t.Fatalf("JSONML block page identity = %q", got) + } + }) + t.Run("unknown pagination short page", func(t *testing.T) { installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[{"id":"a"}]}`}}}) if blocks, err := readAllDocBlocksForVerification(ctx, "node"); err != nil || len(blocks) != 1 { From 9ed55978d9c4751b3a738984ec37a6c20ba1892a Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 12:10:17 +0800 Subject: [PATCH 173/250] fix(doc): cancel readback retry waits --- internal/helpers/doc.go | 20 ++++++++++- internal/helpers/doc_command_edges_test.go | 22 ++++++++++++ internal/helpers/doc_coverage_more_test.go | 2 ++ internal/shortcut/doc/content_shortcuts.go | 21 +++++++++-- .../doc/doc_readback_verification_test.go | 36 +++++++++++++++++-- internal/shortcut/doc/doc_shortcuts_test.go | 2 +- 6 files changed, 96 insertions(+), 7 deletions(-) diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index ecad5e5a..4c1380e4 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -728,6 +728,8 @@ func docMediaInsertVerificationError(nodeID, resourceID, resourceURL, fileName s ) } +var docMediaVerifyWait = waitForDocVerification + func verifyInsertedDocMedia(ctx context.Context, nodeID, blockID, resourceID, resourceURL string) (string, error) { delays := []time.Duration{250 * time.Millisecond, 500 * time.Millisecond, time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second} var lastErr error @@ -742,7 +744,9 @@ func verifyInsertedDocMedia(ctx context.Context, nodeID, blockID, resourceID, re } } if attempt < len(delays) { - helperSleep(delays[attempt]) + if err := docMediaVerifyWait(ctx, delays[attempt]); err != nil { + return "", err + } } } if lastErr != nil { @@ -751,6 +755,20 @@ func verifyInsertedDocMedia(ctx context.Context, nodeID, blockID, resourceID, re return "", fmt.Errorf("媒体资源在有界回读窗口内仍不可见") } +func waitForDocVerification(ctx context.Context, delay time.Duration) error { + if ctx == nil { + ctx = context.Background() + } + timer := time.NewTimer(delay) + defer timer.Stop() + select { + case <-ctx.Done(): + return ctx.Err() + case <-timer.C: + return nil + } +} + func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, error) { const pageSize = 50 const maxItems = 5000 diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index e20d4151..7f478518 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -78,6 +78,7 @@ func TestCrossPlatformCoverageDocUploadAndMediaErrorEdges(t *testing.T) { oldPut, oldGet := httpPutFile, httpGetFile t.Cleanup(func() { httpPutFile, httpGetFile = oldPut, oldGet }) testseam.Swap(t, &helperSleep, func(time.Duration) {}) + testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil }) file := filepath.Join(t.TempDir(), "file.txt") if err := os.WriteFile(file, []byte("content"), 0o600); err != nil { t.Fatal(err) @@ -291,6 +292,7 @@ func TestCrossPlatformCoverageDefaultDocHTTPTransportEdges(t *testing.T) { func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { testseam.Swap(t, &helperSleep, func(time.Duration) {}) + testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil }) ctx := context.Background() for _, tc := range []struct { @@ -428,6 +430,26 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { } } +func TestCrossPlatformCoverageDocMediaReadbackStopsOnCancellation(t *testing.T) { + if err := waitForDocVerification(nil, time.Nanosecond); err != nil { + t.Fatalf("completed verification wait = %v", err) + } + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + if err := waitForDocVerification(cancelled, time.Hour); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled verification wait = %v, want context.Canceled", err) + } + + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"blocks":[],"hasMore":false}`}}} + installScriptedCaller(t, caller) + if _, err := verifyInsertedDocMedia(cancelled, "node", "", "missing", ""); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled media verification = %v, want context.Canceled", err) + } + if caller.calls != 1 { + t.Fatalf("cancelled media verification calls = %d, want 1", caller.calls) + } +} + func TestCrossPlatformCoverageDocCreateUpdateAndBlockCommandEdges(t *testing.T) { oldDeps, oldArgs, oldPut, oldGet := deps, os.Args, httpPutFile, httpGetFile t.Cleanup(func() { diff --git a/internal/helpers/doc_coverage_more_test.go b/internal/helpers/doc_coverage_more_test.go index c375ac40..674d74f1 100644 --- a/internal/helpers/doc_coverage_more_test.go +++ b/internal/helpers/doc_coverage_more_test.go @@ -9,6 +9,7 @@ import ( "path/filepath" "strings" "testing" + "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/spf13/cobra" @@ -194,6 +195,7 @@ func TestCrossPlatformCoverageDocDeprecationWrappersCoverage(t *testing.T) { } func TestCrossPlatformCoverageRunDocUploadDownloadAndMediaCoverage(t *testing.T) { + testseam.Swap(t, &docMediaVerifyWait, func(context.Context, time.Duration) error { return nil }) oldArgs := os.Args os.Args = []string{"dws", "doc"} t.Cleanup(func() { os.Args = oldArgs }) diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 74ae46bd..4a054928 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -5,6 +5,7 @@ package doc import ( "bytes" + "context" "encoding/json" "fmt" "io" @@ -33,7 +34,7 @@ var ( docMkdirTemp = os.MkdirTemp docRemoveAll = os.RemoveAll docDownload = localio.Download - docVerifySleep = time.Sleep + docVerifyWait = waitForDocVerification docVerifyDelays = []time.Duration{250 * time.Millisecond, 500 * time.Millisecond, time.Second, 2 * time.Second, 4 * time.Second, 8 * time.Second} docMarkdown = goldmark.New( goldmark.WithExtensions(extension.Table), @@ -797,7 +798,9 @@ func readDocVerification(rt *shortcut.RuntimeContext, tool string, rawParams map } } if attempt < len(docVerifyDelays) { - docVerifySleep(docVerifyDelays[attempt]) + if err := docVerifyWait(rt.Command().Context(), docVerifyDelays[attempt]); err != nil { + return nil, err + } } } if lastErr != nil { @@ -806,6 +809,20 @@ func readDocVerification(rt *shortcut.RuntimeContext, tool string, rawParams map return last, nil } +func waitForDocVerification(ctx context.Context, delay time.Duration) error { + if ctx == nil { + ctx = context.Background() + } + timer := time.NewTimer(delay) + defer timer.Stop() + select { + case <-ctx.Done(): + return ctx.Err() + case <-timer.C: + return nil + } +} + func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (map[string]any, error) { all := make([]any, 0, docBlockReadPageSize) seenPageIdentities := map[string]bool{} diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index 6f852b4d..f1f83361 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -4,6 +4,7 @@ package doc import ( + "context" "errors" "fmt" "io" @@ -11,11 +12,14 @@ import ( "testing" "time" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" + "github.com/spf13/cobra" ) func TestCrossPlatformCoverageDocReadbackRetriesStaleContent(t *testing.T) { - testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyWait, func(context.Context, time.Duration) error { return nil }) testseam.Swap(t, &docVerifyDelays, []time.Duration{time.Millisecond}) caller := &docCoverageCaller{responses: map[string][]map[string]any{ "get_document_content": {{"markdown": "old"}, {"markdown": "old\nnew"}}, @@ -34,8 +38,34 @@ func TestCrossPlatformCoverageDocReadbackRetriesStaleContent(t *testing.T) { } } +func TestCrossPlatformCoverageDocReadbackStopsOnCancellation(t *testing.T) { + if err := waitForDocVerification(nil, time.Nanosecond); err != nil { + t.Fatalf("completed verification wait = %v", err) + } + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + if err := waitForDocVerification(cancelled, time.Hour); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled verification wait = %v, want context.Canceled", err) + } + + cmd := &cobra.Command{Use: "verify"} + cmd.SetContext(cancelled) + caller := &docCoverageCaller{responses: map[string][]map[string]any{ + "get_document_content": {{"markdown": "stale"}}, + }} + helpers.InitDeps(caller) + rt := shortcut.RuntimeContextForTest(cmd, Update) + _, err := readDocVerification(rt, "get_document_content", map[string]any{"nodeId": "n"}, func(map[string]any) bool { return false }) + if !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled document verification = %v, want context.Canceled", err) + } + if len(caller.history) != 1 { + t.Fatalf("cancelled document verification calls = %d, want 1", len(caller.history)) + } +} + func TestCrossPlatformCoverageDocDeleteReadbackConsumesEveryPage(t *testing.T) { - testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyWait, func(context.Context, time.Duration) error { return nil }) testseam.Swap(t, &docVerifyDelays, []time.Duration{time.Millisecond}) firstPage := make([]any, 50) for index := range firstPage { @@ -190,7 +220,7 @@ func TestCrossPlatformCoverageVersionRevertRequiresTargetEvidence(t *testing.T) } func TestCrossPlatformCoverageDocReadbackDefensiveEdges(t *testing.T) { - testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyWait, func(context.Context, time.Duration) error { return nil }) for _, tc := range []struct { name string responses []map[string]any diff --git a/internal/shortcut/doc/doc_shortcuts_test.go b/internal/shortcut/doc/doc_shortcuts_test.go index 81e2e238..7f62ed3a 100644 --- a/internal/shortcut/doc/doc_shortcuts_test.go +++ b/internal/shortcut/doc/doc_shortcuts_test.go @@ -113,7 +113,7 @@ func runDocCoverageInput(t *testing.T, declaration shortcut.Shortcut, caller *do func runDocCoveragePath(t *testing.T, declaration shortcut.Shortcut, caller *docCoverageCaller, input io.Reader, commandPath string, args ...string) error { t.Helper() - testseam.Swap(t, &docVerifySleep, func(time.Duration) {}) + testseam.Swap(t, &docVerifyWait, func(context.Context, time.Duration) error { return nil }) helpers.InitDeps(caller) root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} root.PersistentFlags().Bool("yes", false, "") From e5bf332b051a36b25de6141bd9958d5d3aa037ce Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 15:06:44 +0800 Subject: [PATCH 174/250] fix(doc): address readback review findings --- .changes/960-doc-readback-verification.md | 2 +- internal/helpers/doc.go | 16 +++++++++++---- internal/helpers/doc_command_edges_test.go | 15 ++++++++++++++ internal/shortcut/doc/content_shortcuts.go | 6 ++++-- .../doc/doc_readback_verification_test.go | 20 +++++++++++++++++++ .../references/best_practices/04-document.md | 2 +- 6 files changed, 53 insertions(+), 8 deletions(-) diff --git a/.changes/960-doc-readback-verification.md b/.changes/960-doc-readback-verification.md index 06467959..3dd1f89c 100644 --- a/.changes/960-doc-readback-verification.md +++ b/.changes/960-doc-readback-verification.md @@ -2,4 +2,4 @@ category: Fixed --- -- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. +- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result. diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index 4c1380e4..19c0241e 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -9,6 +9,7 @@ import ( "net/url" "os" "path/filepath" + "sort" "strconv" "strings" "time" @@ -802,8 +803,10 @@ func readAllDocBlocksForVerification(ctx context.Context, nodeID string) ([]any, if hasMoreKnown && !hasMore { return all, nil } - if total, ok := docNumberAsInt(payload["totalCount"]); ok && len(all) >= total { - return all, nil + if !hasMoreKnown { + if total, ok := docNumberAsInt(payload["totalCount"]); ok && len(all) >= total { + return all, nil + } } if !hasMoreKnown && len(blocks) < pageSize { return all, nil @@ -872,8 +875,13 @@ func nestedDocString(value any, keys ...string) string { return strings.TrimSpace(text) } } - for _, child := range typed { - if text := nestedDocString(child, keys...); text != "" { + orderedKeys := make([]string, 0, len(typed)) + for key := range typed { + orderedKeys = append(orderedKeys, key) + } + sort.Strings(orderedKeys) + for _, key := range orderedKeys { + if text := nestedDocString(typed[key], keys...); text != "" { return text } } diff --git a/internal/helpers/doc_command_edges_test.go b/internal/helpers/doc_command_edges_test.go index 7f478518..1d2918c2 100644 --- a/internal/helpers/doc_command_edges_test.go +++ b/internal/helpers/doc_command_edges_test.go @@ -342,6 +342,18 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { } }) + t.Run("explicit has more overrides inconsistent total count", func(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"blocks":[{"id":"first"}],"hasMore":true,"totalCount":1}`}, + {text: `{"blocks":[{"id":"second"}],"hasMore":false,"totalCount":2}`}, + }} + installScriptedCaller(t, caller) + got, err := readAllDocBlocksForVerification(ctx, "node") + if err != nil || len(got) != 2 || caller.calls != 2 { + t.Fatalf("blocks=%d calls=%d err=%v, want both explicitly advertised pages", len(got), caller.calls, err) + } + }) + t.Run("page identity accepts nested and JSONML block IDs", func(t *testing.T) { if got := docBlockPageIdentity([]any{map[string]any{"element": map[string]any{"blockId": "nested-block"}}}); got != `["nested-block"]` { t.Fatalf("nested block page identity = %q", got) @@ -401,6 +413,9 @@ func TestCrossPlatformCoverageDocMediaReadbackDefensiveEdges(t *testing.T) { if nestedDocString(map[string]any{"x": []any{map[string]any{"id": " nested "}}}, "id") != "nested" || nestedDocString(3, "id") != "" { t.Fatal("nested string traversal failed") } + if got := nestedDocString(map[string]any{"z": map[string]any{"id": "last"}, "a": map[string]any{"id": "first"}}, "id"); got != "first" { + t.Fatalf("nested string traversal = %q, want deterministic key order", got) + } if got := insertedDocBlockID(map[string]any{"id": "document", "result": map[string]any{"data": map[string]any{"blockId": " block "}}}); got != "block" { t.Fatalf("trusted inserted block ID = %q, want block", got) } diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 4a054928..8eb9d007 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -850,8 +850,10 @@ func readAllDocumentBlocks(rt *shortcut.RuntimeContext, base map[string]any) (ma if known && !hasMore { return map[string]any{"blocks": all, "hasMore": false, "totalCount": len(all)}, nil } - if total, ok := nestedNonNegativeInt(page, "totalCount", "total_count"); ok && len(all) >= total { - return map[string]any{"blocks": all, "hasMore": false, "totalCount": total}, nil + if !known { + if total, ok := nestedNonNegativeInt(page, "totalCount", "total_count"); ok && len(all) >= total { + return map[string]any{"blocks": all, "hasMore": false, "totalCount": total}, nil + } } if !known && len(blocks) < docBlockReadPageSize { return map[string]any{"blocks": all, "hasMore": false, "totalCount": len(all)}, nil diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index f1f83361..3d4e6775 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -273,6 +273,26 @@ func TestCrossPlatformCoverageDocReadbackDefensiveEdges(t *testing.T) { } }) + t.Run("explicit has more overrides inconsistent total count", func(t *testing.T) { + testseam.Swap(t, &docVerifyDelays, []time.Duration{}) + caller := &docCoverageCaller{responses: map[string][]map[string]any{"list_document_blocks": { + {"blocks": []any{map[string]any{"id": "first"}}, "hasMore": true, "totalCount": 1}, + {"blocks": []any{map[string]any{"id": "second"}}, "hasMore": false, "totalCount": 2}, + }}} + if err := runDocCoverage(t, Update, caller, "--node", "n", "--command", "block_delete", "--block-id", "target", "--yes"); err != nil { + t.Fatal(err) + } + reads := 0 + for _, call := range caller.history { + if call.tool == "list_document_blocks" { + reads++ + } + } + if reads != 2 { + t.Fatalf("read calls = %d, want both explicitly advertised pages", reads) + } + }) + t.Run("block read safety limit", func(t *testing.T) { testseam.Swap(t, &docVerifyDelays, []time.Duration{}) pages := make([]map[string]any, docBlockReadMaxItems/docBlockReadPageSize) diff --git a/skills/mono/references/best_practices/04-document.md b/skills/mono/references/best_practices/04-document.md index c884341e..9985c60d 100644 --- a/skills/mono/references/best_practices/04-document.md +++ b/skills/mono/references/best_practices/04-document.md @@ -14,7 +14,7 @@ | delete-old-doc | 1. `doc search --query "<关键词>"` 或 `doc list --folder ` 取 `nodeId`
2. **必须先向用户展示要删除的文档标题/路径**，等用户确认
3. `doc delete --node --yes`（注意：是 `doc delete`，不是 `doc block delete`；前者删整篇，后者删块）
4. 验证：`doc info --node ` 应返回 not-found | | export-doc-as-docx | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc export --node --output /tmp/.docx --timeout-sec 600`（CLI 内置渐进式退避轮询，**不要自己拼 GET downloadUrl**）
3. 落盘失败兜底：`doc export get --job-id --output /tmp/.docx` 续等
4. （可选）`doc-to-message` 把 docx 路径作为附件发给用户 | | grant-doc-access | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `contact user search --query "<姓名>"` → 取 `userId`（**注意**: doc permission 用 `userId`，不是 `openDingTalkId`）
3. **节点级**授权：`doc permission add --node --user --role EDITOR`
　　role 取值: MANAGER / EDITOR / DOWNLOADER / READER（**不要传 OWNER**）
　　单次最多 30 个 userId
4. 查权限：`doc permission list --node ` 确认
5. **不要混淆**: 给"知识库"加成员用 `wiki member add --workspace`（容器级）；给"单个文档"加权限用 `doc permission add --node`（节点级）| -| insert-image-to-doc | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc media insert --node --file ./image.png`（3 步一体化：获取凭证 → PUT OSS → 插入块；图片 ≤20MB 自动作为内联图片，其他作为附件块）
3. （可选）`doc read --node ` 回读确认
**禁止**: 自己拿 uploadUrl 写 PUT —— 90%+ 会因 Content-Type 未清空触发 SignatureDoesNotMatch | +| insert-image-to-doc | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc media insert --node --file ./image.png`（4 步一体化：获取凭证 → PUT OSS → 插入块 → 自动回读验证；图片 ≤20MB 自动作为内联图片，其他作为附件块）
3. 检查结果中的 `verified=true`；若服务端无法提供明确回读证据，命令会返回 partial success
**禁止**: 自己拿 uploadUrl 写 PUT —— 90%+ 会因 Content-Type 未清空触发 SignatureDoesNotMatch | | download-doc-attachment | 1. `doc block list --node ` → 找到 `blockType=attachment` 的块取 `resourceId`
2. `doc media download --node --resource-id ` → 返回 OSS 临时 URL（**注意 expirationSeconds**）
3. 调用方自行 GET 该 URL 落盘 | --- From 54c2054a5cdb7844bacea530ddad69f9752ec420 Mon Sep 17 00:00:00 2001 From: Dennis Date: Fri, 14 Aug 2026 16:40:15 +0800 Subject: [PATCH 175/250] fix(doc): ignore generated JSONML defaults --- internal/shortcut/doc/content_shortcuts.go | 38 ++++++++++++++++++- .../doc/doc_readback_verification_test.go | 12 +++++- 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/internal/shortcut/doc/content_shortcuts.go b/internal/shortcut/doc/content_shortcuts.go index 8eb9d007..df6fd28e 100644 --- a/internal/shortcut/doc/content_shortcuts.go +++ b/internal/shortcut/doc/content_shortcuts.go @@ -11,6 +11,7 @@ import ( "io" "os" "path/filepath" + "reflect" "strings" "time" "unicode" @@ -1382,6 +1383,7 @@ func normalizeJSONMLForVerification(raw string) string { if len(typed) > 1 { if declared, ok := typed[1].(map[string]any); ok { attrs, _ = normalize(declared).(map[string]any) + attrs = removeGeneratedJSONMLDefaults(tag, attrs) start = 2 } } @@ -1408,7 +1410,7 @@ func normalizeJSONMLForVerification(raw string) string { if normalizedKey == "uuid" || normalizedKey == "blockid" || normalizedKey == "elementid" || normalizedKey == "index" { continue } - out[key] = normalize(child) + out[normalizedKey] = normalize(child) } return out case string: @@ -1422,6 +1424,38 @@ func normalizeJSONMLForVerification(raw string) string { return string(encoded) } +var generatedJSONMLAttributeDefaults = map[string]map[string]any{ + "hr": { + "sz": float64(1), + }, + "tc": { + "colspan": float64(1), "rowspan": float64(1), "valign": "middle", + }, + "code": { + "code": "", "syntax": "plaintext", "theme": "default", + "wrap": true, "showlinenumber": true, "fold": false, + }, +} + +// removeGeneratedJSONMLDefaults drops only defaults declared by the reviewed +// JSONML schema, plus empty server style objects. Other attributes remain part +// of the semantic fingerprint so links, formatting, and table layout stay +// strict. +func removeGeneratedJSONMLDefaults(tag string, attrs map[string]any) map[string]any { + defaults := generatedJSONMLAttributeDefaults[strings.ToLower(tag)] + out := make(map[string]any, len(attrs)) + for key, value := range attrs { + if object, ok := value.(map[string]any); ok && len(object) == 0 { + continue + } + if defaultValue, ok := defaults[key]; ok && reflect.DeepEqual(value, defaultValue) { + continue + } + out[key] = value + } + return out +} + func isGeneratedTextSpan(attrs map[string]any) bool { if len(attrs) == 0 { return true @@ -1429,7 +1463,7 @@ func isGeneratedTextSpan(attrs map[string]any) bool { if len(attrs) != 1 { return false } - value, ok := attrs["data-type"].(string) + value, ok := attrs["datatype"].(string) return ok && (value == "text" || value == "leaf") } diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index 3d4e6775..262771bf 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -120,15 +120,25 @@ func TestCrossPlatformCoverageDocReplacePreflightIsGloballyUnique(t *testing.T) func TestCrossPlatformCoverageDocVerificationPreservesMeaning(t *testing.T) { expected := "[\"p\",{},\"text\"]" - serverExpanded := "[\"p\",{\"uuid\":\"generated\"},[\"span\",{\"data-type\":\"text\"},[\"span\",{\"data-type\":\"leaf\"},\"text\"]]]" + serverExpanded := "[\"p\",{\"uuid\":\"generated\",\"style\":{}},[\"span\",{\"data-type\":\"text\"},[\"span\",{\"data-type\":\"leaf\"},\"text\"]]]" if normalizeJSONMLForVerification(expected) != normalizeJSONMLForVerification(serverExpanded) { t.Fatal("generated JSONML text wrappers should not change document meaning") } + defaultFree := `[["hr",{}],["code",{}],["table",{},["tr",{},["tc",{},["p",{},"cell"]]]]]` + serverDefaulted := `[["hr",{"sz":1}],["code",{"code":"","syntax":"plaintext","theme":"default","wrap":true,"showLineNumber":true,"fold":false}],["table",{},["tr",{},["tc",{"colSpan":1,"rowSpan":1,"vAlign":"middle"},["p",{},"cell"]]]]]` + if !verifyUpdatedDocumentContent(map[string]any{"jsonml": serverDefaulted}, defaultFree, "overwrite", "jsonml") { + t.Fatal("server-generated JSONML schema defaults should not fail readback verification") + } linkA := "[\"a\",{\"href\":\"https://example.com/a\"},\"text\"]" linkB := "[\"a\",{\"href\":\"https://example.com/b\"},\"text\"]" if normalizeJSONMLForVerification(linkA) == normalizeJSONMLForVerification(linkB) { t.Fatal("semantic JSONML attributes were ignored") } + tableA := `[["table",{"jc":"center"},["tr",{},["tc",{},["p",{},"cell"]]]]]` + tableB := `[["table",{"jc":"right"},["tr",{},["tc",{},["p",{},"cell"]]]]]` + if normalizeJSONMLForVerification(tableA) == normalizeJSONMLForVerification(tableB) { + t.Fatal("semantic JSONML table alignment was ignored") + } codeA := "~~~go\n return nil\n~~~" codeB := "~~~go\nreturn nil\n~~~" if normalizeMarkdownForVerification(codeA) == normalizeMarkdownForVerification(codeB) { From 68463264455ac3da33a3904c8c08d3834d168500 Mon Sep 17 00:00:00 2001 From: Dennis Date: Sat, 15 Aug 2026 23:28:00 +0800 Subject: [PATCH 176/250] fix(doc): reject revert request echo evidence --- internal/app/param_alias_e2e_test.go | 2 +- .../doc/doc_readback_verification_test.go | 21 ++++++ internal/shortcut/doc/doc_shortcuts_test.go | 41 ++++++++++- .../doc/history_template_shortcuts.go | 68 ++++++++++++++++++- 4 files changed, 128 insertions(+), 4 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index 71298e27..d1f2df97 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -65,7 +65,7 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string case "list_doc_versions": return `{"result":{"items":[{"version":3}]}}` case "revert_doc_version": - return `{"version":3}` + return `{"revertedToVersion":3}` case "search_doc_templates": return `{"result":[{"templateId":"fixture-template-id"}]}` case "create_document": diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index 262771bf..9252727a 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -224,9 +224,30 @@ func TestCrossPlatformCoverageVersionRevertRequiresTargetEvidence(t *testing.T) if revertResultMatchesVersion(map[string]any{"ok": true}, 3) || currentDocumentMatchesRestoredVersion(map[string]any{"version": 99}, 3) { t.Fatal("readability or an unrelated current version must not prove a revert") } + if revertResultMatchesVersion(map[string]any{"version": 3}, 3) { + t.Fatal("the request version parameter must not prove its own revert") + } + if revertResultMatchesVersion(map[string]any{"data": map[string]any{"request": map[string]any{"targetVersion": 3}}}, 3) { + t.Fatal("request echo containers must not provide version evidence") + } + for _, failed := range []map[string]any{ + {"data": map[string]any{"success": "false", "revertedToVersion": 3}}, + {"data": []any{map[string]any{"error_code": "REVERT_FAILED", "revertedToVersion": 3}}}, + {"data": map[string]any{"errorCode": 500.0, "revertedToVersion": 3}}, + } { + if revertResultMatchesVersion(failed, 3) { + t.Fatalf("explicit failure %#v must override target-version evidence", failed) + } + } if !revertResultMatchesVersion(map[string]any{"revertedToVersion": 3}, 3) { t.Fatal("explicit target-version acknowledgement was not accepted") } + if !revertResultMatchesVersion(map[string]any{"errorCode": "0", "revertedToVersion": 3}, 3) { + t.Fatal("a success error-code sentinel must not suppress target-version evidence") + } + if revertErrorCodeIsFailure(nil) { + t.Fatal("an absent error code must not be treated as an explicit failure") + } } func TestCrossPlatformCoverageDocReadbackDefensiveEdges(t *testing.T) { diff --git a/internal/shortcut/doc/doc_shortcuts_test.go b/internal/shortcut/doc/doc_shortcuts_test.go index 7f62ed3a..aae46f3f 100644 --- a/internal/shortcut/doc/doc_shortcuts_test.go +++ b/internal/shortcut/doc/doc_shortcuts_test.go @@ -58,7 +58,7 @@ func (f *docCoverageCaller) CallTool(_ context.Context, _, tool string, params m } value := docCoveragePayload(tool) if tool == "revert_doc_version" { - value = map[string]any{"version": params["version"]} + value = map[string]any{"revertedToVersion": params["version"]} } if queue := f.responses[tool]; len(queue) > 0 { value = queue[0] @@ -593,6 +593,45 @@ func TestCrossPlatformCoverageDocVersionRevertPaginationAndVerification(t *testi } }) + for _, test := range []struct { + name string + response map[string]any + current map[string]any + wantOK bool + }{ + {name: "explicit server evidence", response: map[string]any{"data": map[string]any{"revertResult": map[string]any{"revertedToVersion": 3}}}, wantOK: true}, + {name: "bare request parameter echo", response: map[string]any{"version": 3}}, + {name: "nested request parameter echo", response: map[string]any{"data": map[string]any{"request": map[string]any{"nodeId": "n", "version": 3}}}}, + {name: "accepted field inside request echo", response: map[string]any{"data": map[string]any{"request": map[string]any{"targetVersion": 3}}}}, + {name: "nested business failure with request echo", response: map[string]any{"data": map[string]any{"success": false, "errorCode": "REVERT_FAILED", "request": map[string]any{"version": 3}}}}, + { + name: "nested business failure overrides all evidence", + response: map[string]any{"data": map[string]any{"success": false, "revertResult": map[string]any{"revertedToVersion": 3}}}, + current: map[string]any{"targetVersion": 3}, + }, + } { + t.Run(test.name, func(t *testing.T) { + responses := map[string][]map[string]any{ + "revert_doc_version": {test.response}, + } + if test.current != nil { + responses["get_document_info"] = []map[string]any{test.current} + } + caller := &docCoverageCaller{responses: responses} + err := runDocCoverage(t, VersionRevert, caller, "--node", "n", "--version", "3", "--yes") + if test.wantOK { + if err != nil { + t.Fatal(err) + } + return + } + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "doc_history_revert_target_unproven" || typed.Details["status"] != "partial_success" { + t.Fatalf("request echo response %#v produced %#v", test.response, err) + } + }) + } + for _, test := range []struct { name string responses []map[string]any diff --git a/internal/shortcut/doc/history_template_shortcuts.go b/internal/shortcut/doc/history_template_shortcuts.go index 048ae9bd..e5086dc2 100644 --- a/internal/shortcut/doc/history_template_shortcuts.go +++ b/internal/shortcut/doc/history_template_shortcuts.go @@ -178,7 +178,8 @@ func executeHistoryRevert(rt *shortcut.RuntimeContext) error { map[string]any{"available": false, "reason": "the requested revert completed; verify the current document before any further write"}, ) } - verified := revertResultMatchesVersion(reverted, target) || currentDocumentMatchesRestoredVersion(current, target) + verified := !revertResponseHasExplicitFailure(reverted) && + (revertResultMatchesVersion(reverted, target) || currentDocumentMatchesRestoredVersion(current, target)) if !verified { return docPartialWriteError( "doc.history_revert", "doc_history_revert_target_unproven", "verify", @@ -206,8 +207,11 @@ func executeHistoryRevert(rt *shortcut.RuntimeContext) error { } func revertResultMatchesVersion(value map[string]any, target int) bool { + if revertResponseHasExplicitFailure(value) { + return false + } return versionEvidenceMatches(value, target, map[string]bool{ - "version": true, "targetversion": true, "appliedversion": true, + "targetversion": true, "appliedversion": true, "restoredversion": true, "revertedversion": true, "revertedtoversion": true, "sourceversion": true, }) } @@ -272,6 +276,9 @@ func versionEvidenceMatches(value any, target int, acceptedKeys map[string]bool) case map[string]any: for key, child := range typed { normalized := strings.ToLower(strings.NewReplacer("_", "", "-", "").Replace(key)) + if versionEvidenceRequestEchoKeys[normalized] { + continue + } if acceptedKeys[normalized] { if versionNumberMatches(child, target) { return true @@ -291,6 +298,63 @@ func versionEvidenceMatches(value any, target int, acceptedKeys map[string]bool) return false } +var versionEvidenceRequestEchoKeys = map[string]bool{ + "args": true, "arguments": true, "input": true, "inputs": true, + "params": true, "parameters": true, "request": true, "requestbody": true, + "requestparams": true, "toolargs": true, "toolarguments": true, +} + +func revertResponseHasExplicitFailure(value any) bool { + switch typed := value.(type) { + case map[string]any: + for key, child := range typed { + normalized := strings.ToLower(strings.NewReplacer("_", "", "-", "").Replace(key)) + if versionEvidenceRequestEchoKeys[normalized] { + continue + } + if normalized == "success" { + if success, ok := child.(bool); ok && !success { + return true + } + if success, ok := child.(string); ok && strings.EqualFold(strings.TrimSpace(success), "false") { + return true + } + } + if normalized == "errorcode" { + if revertErrorCodeIsFailure(child) { + return true + } + } + if revertResponseHasExplicitFailure(child) { + return true + } + } + case []any: + for _, child := range typed { + if revertResponseHasExplicitFailure(child) { + return true + } + } + } + return false +} + +func revertErrorCodeIsFailure(value any) bool { + switch typed := value.(type) { + case string: + switch strings.ToLower(strings.TrimSpace(typed)) { + case "", "0", "ok", "success", "succeed": + return false + default: + return true + } + case float64: + return typed != 0 + default: + return false + } +} + func versionNumberMatches(value any, target int) bool { switch number := value.(type) { case float64: From a82d945f54abdd64bdb5a1611cf57b8889ffaef5 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 14:14:44 +0800 Subject: [PATCH 177/250] fix(doc): reject explicit revert failure states --- .../doc/doc_readback_verification_test.go | 33 +++++++++++++--- internal/shortcut/doc/doc_shortcuts_test.go | 4 +- .../doc/history_template_shortcuts.go | 38 +++++++++++++++---- 3 files changed, 61 insertions(+), 14 deletions(-) diff --git a/internal/shortcut/doc/doc_readback_verification_test.go b/internal/shortcut/doc/doc_readback_verification_test.go index 9252727a..63be4455 100644 --- a/internal/shortcut/doc/doc_readback_verification_test.go +++ b/internal/shortcut/doc/doc_readback_verification_test.go @@ -5,6 +5,7 @@ package doc import ( "context" + "encoding/json" "errors" "fmt" "io" @@ -232,21 +233,41 @@ func TestCrossPlatformCoverageVersionRevertRequiresTargetEvidence(t *testing.T) } for _, failed := range []map[string]any{ {"data": map[string]any{"success": "false", "revertedToVersion": 3}}, + {"data": map[string]any{"ok": false, "revertedToVersion": 3}}, + {"data": map[string]any{"status": "FAILED", "revertedToVersion": 3}}, + {"data": map[string]any{"state": "failure", "revertedToVersion": 3}}, {"data": []any{map[string]any{"error_code": "REVERT_FAILED", "revertedToVersion": 3}}}, {"data": map[string]any{"errorCode": 500.0, "revertedToVersion": 3}}, + {"data": map[string]any{"code": json.Number("500"), "revertedToVersion": 3}}, } { if revertResultMatchesVersion(failed, 3) { t.Fatalf("explicit failure %#v must override target-version evidence", failed) } } - if !revertResultMatchesVersion(map[string]any{"revertedToVersion": 3}, 3) { - t.Fatal("explicit target-version acknowledgement was not accepted") + for _, succeeded := range []map[string]any{ + {"revertedToVersion": 3}, + {"status": "SUCCESS", "revertedToVersion": 3}, + {"state": "succeeded", "revertedToVersion": 3}, + {"errorCode": "0", "revertedToVersion": 3}, + {"code": 200, "revertedToVersion": 3}, + {"code": "204", "revertedToVersion": 3}, + } { + if !revertResultMatchesVersion(succeeded, 3) { + t.Fatalf("explicit success %#v suppressed target-version evidence", succeeded) + } } - if !revertResultMatchesVersion(map[string]any{"errorCode": "0", "revertedToVersion": 3}, 3) { - t.Fatal("a success error-code sentinel must not suppress target-version evidence") + for _, absentOrSuccess := range []any{nil, "", "OK", "SUCCESS", json.Number("0"), json.Number("200"), 0.0, 201.0, 0, 202} { + if revertErrorCodeIsFailure(absentOrSuccess) { + t.Fatalf("success code %#v was treated as an explicit failure", absentOrSuccess) + } } - if revertErrorCodeIsFailure(nil) { - t.Fatal("an absent error code must not be treated as an explicit failure") + for _, failedCode := range []any{json.Number("bad"), json.Number("500"), 1.0, 500.0, 1, 500} { + if !revertErrorCodeIsFailure(failedCode) { + t.Fatalf("failure code %#v was not treated as an explicit failure", failedCode) + } + } + if revertStatusIsFailure(500) || revertStatusIsFailure("PROCESSING") { + t.Fatal("non-failure status was treated as an explicit failure") } } diff --git a/internal/shortcut/doc/doc_shortcuts_test.go b/internal/shortcut/doc/doc_shortcuts_test.go index aae46f3f..8b3da279 100644 --- a/internal/shortcut/doc/doc_shortcuts_test.go +++ b/internal/shortcut/doc/doc_shortcuts_test.go @@ -604,9 +604,11 @@ func TestCrossPlatformCoverageDocVersionRevertPaginationAndVerification(t *testi {name: "nested request parameter echo", response: map[string]any{"data": map[string]any{"request": map[string]any{"nodeId": "n", "version": 3}}}}, {name: "accepted field inside request echo", response: map[string]any{"data": map[string]any{"request": map[string]any{"targetVersion": 3}}}}, {name: "nested business failure with request echo", response: map[string]any{"data": map[string]any{"success": false, "errorCode": "REVERT_FAILED", "request": map[string]any{"version": 3}}}}, + {name: "failed status overrides target evidence", response: map[string]any{"data": map[string]any{"status": "FAILED", "revertResult": map[string]any{"revertedToVersion": 3}}}}, + {name: "failed code overrides target evidence", response: map[string]any{"data": map[string]any{"code": "REVERT_FAILED", "revertResult": map[string]any{"revertedToVersion": 3}}}}, { name: "nested business failure overrides all evidence", - response: map[string]any{"data": map[string]any{"success": false, "revertResult": map[string]any{"revertedToVersion": 3}}}, + response: map[string]any{"data": map[string]any{"state": "FAILURE", "revertResult": map[string]any{"revertedToVersion": 3}}}, current: map[string]any{"targetVersion": 3}, }, } { diff --git a/internal/shortcut/doc/history_template_shortcuts.go b/internal/shortcut/doc/history_template_shortcuts.go index e5086dc2..10a88eb7 100644 --- a/internal/shortcut/doc/history_template_shortcuts.go +++ b/internal/shortcut/doc/history_template_shortcuts.go @@ -312,7 +312,7 @@ func revertResponseHasExplicitFailure(value any) bool { if versionEvidenceRequestEchoKeys[normalized] { continue } - if normalized == "success" { + if normalized == "success" || normalized == "ok" { if success, ok := child.(bool); ok && !success { return true } @@ -320,7 +320,10 @@ func revertResponseHasExplicitFailure(value any) bool { return true } } - if normalized == "errorcode" { + if (normalized == "status" || normalized == "state") && revertStatusIsFailure(child) { + return true + } + if normalized == "errorcode" || normalized == "code" { if revertErrorCodeIsFailure(child) { return true } @@ -339,17 +342,38 @@ func revertResponseHasExplicitFailure(value any) bool { return false } +func revertStatusIsFailure(value any) bool { + status, ok := value.(string) + if !ok { + return false + } + switch strings.ToLower(strings.TrimSpace(status)) { + case "fail", "failed", "failure", "error", "errored", "reject", "rejected", "deny", "denied", "cancel", "cancelled", "canceled", "abort", "aborted": + return true + default: + return false + } +} + func revertErrorCodeIsFailure(value any) bool { switch typed := value.(type) { case string: - switch strings.ToLower(strings.TrimSpace(typed)) { - case "", "0", "ok", "success", "succeed": + normalized := strings.ToLower(strings.TrimSpace(typed)) + switch normalized { + case "", "ok", "success", "succeed", "succeeded": return false - default: - return true } + if parsed, err := strconv.Atoi(normalized); err == nil { + return parsed != 0 && (parsed < 200 || parsed >= 300) + } + return true case float64: - return typed != 0 + return typed != 0 && (typed < 200 || typed >= 300) + case json.Number: + parsed, err := typed.Int64() + return err != nil || (parsed != 0 && (parsed < 200 || parsed >= 300)) + case int: + return typed != 0 && (typed < 200 || typed >= 300) default: return false } From b7a07abcb15612b152eebdd1d3931af37ada2328 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Mon, 17 Aug 2026 15:14:22 +0800 Subject: [PATCH 178/250] test(recruit): cover cursor through response pipeline to #85340676 --- internal/helpers/recruit.go | 18 +++++++++++------- internal/helpers/recruit_test.go | 23 +++++++++++++++-------- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index ec333736..97a76415 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -154,13 +154,7 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou } clean, err := recruitBusinessResultData(data, tool) if err != nil { - var businessFailure *recruitBusinessFailure - if errors.As(err, &businessFailure) { - return output.Failure(&output.ErrorInfo{ - Type: "api", Message: businessFailure.Error(), - }), nil - } - return recruitInvalidResponse(err), nil + return recruitResponseFailure(err), nil } if tool != recruitListJobsTool { return output.Success(clean), nil @@ -172,6 +166,16 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou return output.Success(listData, output.WithMeta(meta)), nil } +func recruitResponseFailure(err error) output.CommandResult { + var businessFailure *recruitBusinessFailure + if errors.As(err, &businessFailure) { + return output.Failure(&output.ErrorInfo{ + Type: "api", Message: businessFailure.Error(), + }) + } + return recruitInvalidResponse(err) +} + type recruitBusinessFailure struct { message string } diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index d0492024..a51ddb90 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -137,20 +137,25 @@ func TestRecruitJobListResponseCursorRoundTrip(t *testing.T) { caller := withRecruitCaller(t) caller.text = `{"success":true,"result":{"list":[],"hasMore":true,"nextCursor":9223372036854775807}}` - data, err := CallMCPToolDataOnServer(context.Background(), recruitServerID, recruitListJobsTool, map[string]any{"size": 20}) + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + result, err := recruitResultCall(cmd, recruitListJobsTool, map[string]any{"size": 20}) if err != nil { t.Fatal(err) } - _, meta, err := recruitListResultData(data) + envelope, err := output.EnvelopeFromResult(result) if err != nil { t.Fatal(err) } + if envelope.Outcome != output.OutcomeSuccess || envelope.Meta == nil || envelope.Meta.Pagination == nil { + t.Fatalf("envelope = %#v", envelope) + } + meta := envelope.Meta if got := meta.Pagination.NextToken; got != "9223372036854775807" { t.Fatalf("next token = %q, want lossless max int64", got) } caller.text = `{"jobs":[],"hasMore":false}` - cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + cmd = prepareRecruitTestCommand(newRecruitJobListCommand()) cmd.SetArgs([]string{"--cursor", meta.Pagination.NextToken}) if err := cmd.Execute(); err != nil { t.Fatal(err) @@ -566,13 +571,15 @@ func TestRecruitResultCallClassifiesBusinessAndMalformedFailures(t *testing.T) { }, } { t.Run(test.name, func(t *testing.T) { - caller := withRecruitCaller(t) - caller.text = test.text - cmd := prepareRecruitTestCommand(newRecruitJobGetCommand()) - result, err := recruitResultCall(cmd, recruitGetJobTool, map[string]any{"jobId": "job-1"}) - if err != nil { + var payload any + if err := json.Unmarshal([]byte(test.text), &payload); err != nil { t.Fatal(err) } + _, responseErr := recruitBusinessResultData(payload, recruitGetJobTool) + if responseErr == nil { + t.Fatal("expected response error") + } + result := recruitResponseFailure(responseErr) envelope, err := output.EnvelopeFromResult(result) if err != nil { t.Fatal(err) From 9d8b338833401ea959bd8fc9751c438089baf6e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=9C=E7=8E=84?= Date: Mon, 17 Aug 2026 15:21:45 +0800 Subject: [PATCH 179/250] fix(aitable): validate stats filters consistently --- internal/helpers/aitable.go | 23 ++++++++++++++--------- internal/helpers/aitable_stats_test.go | 23 +++++++++++++++++++---- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/internal/helpers/aitable.go b/internal/helpers/aitable.go index f52d40fd..0342fe81 100644 --- a/internal/helpers/aitable.go +++ b/internal/helpers/aitable.go @@ -534,6 +534,13 @@ func parseAitableStatsItems(raw string, uppercase, uniqueFields bool, maxItems i if err := json.Unmarshal([]byte(raw), &items); err != nil { return nil, aitableStatsValidationf("--stats 必须是 JSON 数组: %v", err) } + var strictItems []aitableStatsItem + decoder := json.NewDecoder(strings.NewReader(raw)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&strictItems); err != nil { + return nil, aitableStatsValidationf("--stats 包含不支持的字段: %v", err) + } + items = strictItems if len(items) == 0 { return nil, aitableStatsValidationf("--stats 至少需要一个统计项") } @@ -586,13 +593,9 @@ func parseAitableObjectFlag(name, raw string) (map[string]any, error) { return value, nil } -func validateAitableStatsFilterRoot(value map[string]any) error { - operator, ok := value["operator"].(string) - if !ok || (strings.ToLower(operator) != "and" && strings.ToLower(operator) != "or") { - return aitableStatsValidationf("--filters 根节点 operator 必须是 and 或 or") - } - if _, ok := value["operands"].([]any); !ok { - return aitableStatsValidationf("--filters 根节点 operands 必须是 JSON 数组") +func validateAitableStatsFilters(value map[string]any, rawJSON string) error { + if err := validateFiltersStructure(value, rawJSON); err != nil { + return aitableStatsValidationf("%v", err) } return nil } @@ -2376,7 +2379,7 @@ lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议 if err != nil { return err } - if err := validateAitableStatsFilterRoot(filters); err != nil { + if err := validateAitableStatsFilters(filters, raw); err != nil { return err } toolArgs["filters"] = normalizeFilters(filters) @@ -2385,6 +2388,8 @@ lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议 if err := validateAitableArrayDSL("sort", raw); err != nil { return err } + // query_records_stats 的 MCP Schema 将 sort 定义为 JSON 数组编码后的字符串， + // 与 query_records 使用的数组类型不同。 toolArgs["sort"] = raw } if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") { @@ -2469,7 +2474,7 @@ lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议 if err != nil { return err } - if err := validateAitableStatsFilterRoot(filters); err != nil { + if err := validateAitableStatsFilters(filters, raw); err != nil { return err } toolArgs["filters"] = normalizeFilters(filters) diff --git a/internal/helpers/aitable_stats_test.go b/internal/helpers/aitable_stats_test.go index 9001ee39..3df972d5 100644 --- a/internal/helpers/aitable_stats_test.go +++ b/internal/helpers/aitable_stats_test.go @@ -77,7 +77,7 @@ func TestCrossPlatformCoverageAitableGroupStatsForwardsStringDSL(t *testing.T) { "--base-id", "base-stats", "--table-id", "table-stats", "--stats", `[{"fieldId":"fldStore","statsType":"distinct"},{"fieldId":"fldAmount","statsType":"avg"}]`, - "--filters", `{"operator":"OR","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`, + "--filters", `{"operator":"OR","operands":[{"operator":"not_before","operands":["fldDate","2026-01-01"]}]}`, "--group", group, "--sort", sortDSL, "--limit", "1000", @@ -140,6 +140,11 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":" ","statsType":"COUNT"}]`}, wantErr: "均不能为空", }, + { + name: "records stats reject unknown item fields", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT","unknownKey":123}]`}, + wantErr: "不支持的字段", + }, { name: "records stats reject duplicate field", args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"},{"fieldId":"f","statsType":"SUM"}]`}, @@ -163,7 +168,7 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t { name: "filters require logical root", args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"eq","operands":[]}`}, - wantErr: "and 或 or", + wantErr: `root "operator" must be "and" or "or"`, }, { name: "records filters reject malformed JSON", @@ -188,7 +193,12 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t { name: "records filters require operand array", args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":{}}`}, - wantErr: "operands 必须是 JSON 数组", + wantErr: `"operands" must be an array`, + }, + { + name: "records filters reject silently unsupported operators", + args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`}, + wantErr: `unsupported filter operator "date_between"`, }, { name: "records sort requires an item", @@ -213,7 +223,12 @@ func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t { name: "group filters require logical root", args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"eq","operands":[]}`}, - wantErr: "and 或 or", + wantErr: `root "operator" must be "and" or "or"`, + }, + { + name: "group filters reject silently unsupported operators", + args: []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`}, + wantErr: `unsupported filter operator "date_between"`, }, { name: "group sort rejects invalid DSL", From 5425d1565f9bc6168d798de9bdd4a8ae5f1c2f08 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 16:01:14 +0800 Subject: [PATCH 180/250] feat(shortcut): align calendar and todo workflows --- .changes/calendar-todo-shortcut-alignment.md | 16 + ...alendar-todo-shortcut-business-review.html | 82 +++ docs/shortcut-public-catalog.json | 391 +++++++++-- internal/app/schema_shortcut_contract_test.go | 6 +- internal/shortcut/calendar/calendar.go | 423 ++++++----- .../calendar_cross_platform_coverage_test.go | 167 +++++ internal/shortcut/calendar/common.go | 490 +++++++++++++ internal/shortcut/calendar/event_shortcuts.go | 604 ++++++++++++++++ .../calendar/room_groups_projection_test.go | 8 +- internal/shortcut/public_catalog_generated.go | 17 + internal/shortcut/semantic_catalog.go | 8 + .../shortcut/semantic_catalog_calendar.json | 39 ++ internal/shortcut/semantic_catalog_todo.json | 29 + internal/shortcut/smart/assign.go | 30 +- internal/shortcut/smart/assign_multi.go | 28 +- internal/shortcut/smart/book.go | 158 +++-- internal/shortcut/smart/calendar_shared.go | 483 ++++++++++++- ...dar_strict_cross_platform_coverage_test.go | 341 +++++++++ internal/shortcut/smart/cancel_event.go | 75 +- .../smart/compatibility_coverage_test.go | 7 + internal/shortcut/smart/conflicts.go | 35 +- internal/shortcut/smart/created_todos.go | 13 +- internal/shortcut/smart/due_today.go | 45 +- internal/shortcut/smart/free_slots.go | 6 +- internal/shortcut/smart/freebusy.go | 31 +- internal/shortcut/smart/invite.go | 52 +- .../smart/mail_space_todo_projection_test.go | 11 +- internal/shortcut/smart/my_free.go | 10 +- internal/shortcut/smart/next_event.go | 56 +- internal/shortcut/smart/overdue.go | 12 +- internal/shortcut/smart/related_tasks.go | 41 +- internal/shortcut/smart/remind.go | 29 +- .../shortcut/smart/remind_contract_test.go | 7 +- internal/shortcut/smart/reschedule.go | 47 +- internal/shortcut/smart/suggest_time.go | 46 +- internal/shortcut/smart/today.go | 6 +- internal/shortcut/smart/todo_done.go | 25 +- internal/shortcut/smart/todo_shared.go | 76 +- internal/shortcut/smart/todo_strict_test.go | 58 ++ internal/shortcut/smart/tomorrow.go | 6 +- internal/shortcut/smart/week.go | 6 +- internal/shortcut/todo/common.go | 347 +++++++++ internal/shortcut/todo/lifecycle.go | 459 ++++++++++++ internal/shortcut/todo/todo.go | 249 +++++-- internal/shortcut/todo/todo_contract_test.go | 72 ++ scripts/dev/calendar-todo-shortcut-e2e.py | 659 ++++++++++++++++++ scripts/gen_shortcut_public_catalog.py | 2 + skills/mono/SKILL.md | 4 +- skills/multi/dingtalk-calendar/SKILL.md | 1 + skills/multi/dingtalk-todo/SKILL.md | 7 + 50 files changed, 5195 insertions(+), 625 deletions(-) create mode 100644 .changes/calendar-todo-shortcut-alignment.md create mode 100644 docs/calendar-todo-shortcut-business-review.html create mode 100644 internal/shortcut/calendar/calendar_cross_platform_coverage_test.go create mode 100644 internal/shortcut/calendar/common.go create mode 100644 internal/shortcut/calendar/event_shortcuts.go create mode 100644 internal/shortcut/semantic_catalog_calendar.json create mode 100644 internal/shortcut/semantic_catalog_todo.json create mode 100644 internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go create mode 100644 internal/shortcut/smart/todo_strict_test.go create mode 100644 internal/shortcut/todo/common.go create mode 100644 internal/shortcut/todo/lifecycle.go create mode 100644 internal/shortcut/todo/todo_contract_test.go create mode 100755 scripts/dev/calendar-todo-shortcut-e2e.py diff --git a/.changes/calendar-todo-shortcut-alignment.md b/.changes/calendar-todo-shortcut-alignment.md new file mode 100644 index 00000000..70fecb96 --- /dev/null +++ b/.changes/calendar-todo-shortcut-alignment.md @@ -0,0 +1,16 @@ +--- +type: feature +scope: shortcut +--- + +Align Calendar and Todo shortcuts with the corresponding lark-cli user tasks, +while preserving DingTalk-specific workflows and compatibility names. The new +shortcut contracts reject malformed or missing collections instead of +reporting false empty success, retain bounded pagination evidence, and require +stable business identifiers plus read-back or explicit terminal receipts for +writes. + +Add deterministic contract tests, a PII-safe real-data E2E runner, and a +sanitized HTML capability review that records supported, partial, and +platform-unavailable mappings. Product Skill content is intentionally +unchanged. diff --git a/docs/calendar-todo-shortcut-business-review.html b/docs/calendar-todo-shortcut-business-review.html new file mode 100644 index 00000000..d27cb884 --- /dev/null +++ b/docs/calendar-todo-shortcut-business-review.html @@ -0,0 +1,82 @@ + + + + + + + Calendar × Todo Shortcut 全景评审 + + + +
+

Business Review · Calendar × Todo

Shortcut
一次性全景交付

以 lark-cli 用户任务为基线，逐项补齐 Calendar 与 Todo；同时把缺字段、错类型、坏元素、分页停滞和未读回写入全部从“看似成功”改为失败关闭。

真实账号 E2E：44 PASS / 3 BLOCKED / 0 FAIL47 个公开主入口Shortcut 主体 · Skill 仅生成索引已移除 PII / 凭证 / 业务正文
+
27Calendar 公开 Shortcut
20Todo 公开 Shortcut
10 + 17lark-cli 1.0.87 基线逐项审查
100%公开叶子 Result / Safety 声明
+
+ + + +
+

Executive summary

能力增加，但成功条件更窄、更可信

基线为本机最新 lark-cli 1.0.87；代码基于独立 worktree 的 104eb715 开发。报告只描述 shortcut、runtime contract、测试和平台边界。

+
结论：Calendar 形成 27 个公开入口，Todo 形成 20 个公开入口；44 个入口使用真实组织数据完整执行通过。剩余 3 个 Calendar 入口没有被伪装为 PASS：会议室可用性与 RSVP 收到稳定上游拒绝码，会议室名称搜索缺少可安全证明“已知非空”的 fixture。
+
Calendar scorecard
27公开主入口；另保留 2 个非公开 deprecated 兼容名
24exact shortcut 真实数据 PASS
3fixture / tenant 受限，明确 BLOCKED
18超过 lark-cli 同名基线的额外任务入口
+
Todo scorecard
20公开主入口；兼容名不重复计数
20exact shortcut 真实数据全部 PASS
0公开入口 FAIL / BLOCKED
10超过 lark-cli 同名基线的额外任务入口
+
+ +

Golden routes & ownership

按用户任务组织，而不是按 API 数量组织

Calendar 与 Todo 可以在工作流中相邻，但资源所有权不同：日程中的 action item 不会自动变为 Todo，Todo 的截止时间也不会伪装为日历占用。

+
09

日程发现

日/周视图、下一场、搜索、详情、冲突与空档；完整分页或明确 continuation。

+agenda · +today · +search-event · +conflicts
08

日程协作

创建、更新、邀请、RSVP、取消和重排；写后绑定同一 eventId。

+create · +book · +invite · +reschedule
06

闲忙与会议室

个人/多人闲忙、共同建议、房间分组、名称定位和时间可用性。

+freebusy · +suggest-time · +room-find
04

日历本与参会人

日历本发现、名称搜索和参会人可见状态；不伪造后端未返回的身份字段。

+book-list · +book-search · +attendee-list
+
08

Todo 生命周期

创建、详情、更新、完成、重开、按标题唯一完成和子任务读取。

+create · +get · +update · +complete
06

Todo 发现

与我相关、我创建、今日到期、逾期和全分页搜索，拒绝 Top-N 冒充全量。

+get-my-tasks · +search · +overdue
04

协作与内容

单人/多人指派、评论、附件/评论列表，稳定对象读回。

+assign · +assign-multi · +comment
02

提醒

规则写入与“创建给自己的提醒任务”分开；不可读回的规则明确 terminal-only。

+reminder · +remind
+
边界：calendar 管理时间占用、参会人和会议室；todo 管理任务状态、协作者和截止时间。跨产品站会摘要属于上层 workflow，本次没有扩展任何 Skill 逻辑；仅按仓库强制生成规则同步公开 shortcut 的计数和清单。
+
+ +

Lark alignment

27 个 lark-cli 任务逐项判定

“覆盖”要求业务语义与证据链成立，不以同名为充分条件；“不可对齐”必须有底层能力或兼容性原因。

+
Calendar：10 项基线

7 · 真实 PASS

agenda、create、freebusy、get、search-event、suggestion、update。

2 · 已实现但 BLOCKED

room-find 在当前租户被上游拒绝；rsvp 缺少安全可控的受邀参与者 fixture。

1 · 平台缺口

meeting 需要日程到视频会议/会议纪要的稳定关联，当前 DingTalk 下层没有等价接口。

+ +
Lark 任务DWS 主入口结论差异与证据
+agendacalendar +agenda覆盖严格 events 数组与 cursor；真实已知非空和合法空均验证。
+createcalendar +create超过eventId、时间与标题精确详情读回；异常创建不能以 request echo 成功。
+freebusycalendar +freebusy覆盖用户/会议室目标约束，busy 段严格投影。
+getcalendar +get覆盖对象必须存在并绑定请求 eventId。
+meeting无等价不可对齐缺少 event→VC / 纪要稳定关联；不以标题搜索猜测。
+room-findcalendar +room-findBLOCKED单时段/group/name/page 已实现；真实租户返回稳定上游拒绝码。也不具备 Lark 的城市、楼宇、楼层、容量、多时段与循环过滤。
+rsvpcalendar +rsvpBLOCKED响应动作与终态读回已实现；组织者自测不是合法受邀参与者，真实调用被上游拒绝。
+search-eventcalendar +search-event有限对齐当前服务只支持页内标题/描述/地点过滤并公开 continuation；不会把单页零命中宣称为全局无结果。
+suggestioncalendar +suggestion覆盖显式 recommendEventTimes 数组；缺失字段与空数组严格区分。
+updatecalendar +update超过字段与参会人分阶段更新，输出非事务步骤账本，逐项读回。
+ +
Todo：17 项基线

9 · 覆盖

comment、complete、create、get-my-tasks、get-related-tasks、reminder、reopen、search、update。

1 · 兼容性部分对齐

DWS 历史 +assign 是“按姓名创建并指派”，不能静默改成修改既有任务协作者。

7 · 下层缺口 / 安全路由

followers、set-ancestor、4 项 tasklist 与 upload-attachment shortcut。

+ +
Lark 任务DWS 主入口结论差异与证据
+assigntodo +assign部分保留“姓名解析→创建并指派”已发布语义；既有任务协作者变更没有同名假对齐。
+commenttodo +comment超过写回本身无 commentId；通过写前/写后完整评论集合差异，精确锁定唯一新 commentId 和正文。
+completetodo +complete超过幂等预读，必要时写入，最终 isDone=true 精确读回。
+createtodo +create超过稳定 taskId 与 todoDetailModel 标题读回。
+followers无等价不可对齐DingTalk Todo 下层没有 follower 管理原语，不能用 executor/participant 替代。
+get-my-taskstodo +get-my-tasks覆盖todoCards + page/size/hasMore 严格校验，支持有界全量分页。
+get-related-taskstodo +get-related-tasks超过三种角色全分页合并并按 taskId 去重；旧 +related-tasks 仅兼容。
+remindertodo +reminder终态覆盖上游不支持提醒规则读回，只接受 success=true 终态，并固定 verified=false。
+reopentodo +reopen超过幂等预读与 isDone=false 读回。
+searchtodo +search超过遍历全部分页后按标题筛选；页上限未耗尽时非零失败。
+set-ancestor无等价不可对齐下层无任务 reparent / clear ancestor 原语。
+tasklist-create无等价不可对齐当前 Todo 对象模型无任务清单创建能力。
+tasklist-members无等价不可对齐无 tasklist member 读写接口。
+tasklist-search无等价不可对齐无 tasklist 目录/检索接口。
+tasklist-task-add无等价不可对齐无将任务加入清单的下层原语。
+updatetodo +update超过只更新显式字段，并按同一 taskId 逐字段读回。
+upload-attachmenttodo task add-attachmentShortcut 不可用原子上传事务真实 PASS；Shortcut runtime 不能安全复用上传凭证/OSS PUT，注册为 unavailable 而非复制敏感事务。
+
+ +

Beyond parity

DWS 可主推的额外场景

超过 Lark 的视角主要来自组合任务、正确性和钉钉对象模型，不来自制造同义命令。

自然人协作链

+book、+invite、+free、+suggest-time 先唯一解析姓名，再绑定同一事件或时间窗。

ambiguous / zero target fail closed

个人日程视图

+today、+tomorrow、+week、+next-event 提供可直接消费的时间视图。

dynamic timezone-aware ranges

空档与冲突

+conflicts、+free-slots、+my-free 在完整日程页上计算，而非只看首屏。

bounded full pagination

日历本发现

+book-list、+book-search 严格区分协议错误和零命中。

stable calendarId projection

多角色任务视图

+get-related-tasks、+created-todos 合并角色分页并去重。

creator / executor / participant

时间驱动 Todo

+due-today 与 +overdue 使用本地日历日和当前时间，避免固定日期示例过期。

runtime date windows

自然标题完成

+todo-done 跨全部分页唯一定位标题；多命中不猜测。

exact target before write

现有内容读取

+list-sub、+list-comment、+list-attachment 将隐藏读取面升级为严格公开入口。

explicit collection + stable ID
+ +

Hidden failures fixed

这次真正修掉的“假成功”

问题来自真实 wire shape、分页和写后证据；mock 成功或空环境不能发现这些风险。

+ +
原问题错误风险修复与回归
缺失集合、错型集合或坏元素被投影为 []内部报错/协议漂移被误报为“无日程/无任务”。失败关闭 只有成功 envelope 内显式存在且类型正确的空数组才是合法空。
Calendar 事件列表真实字段是 result.events，稳定键是 id容错 projector 可能静默丢失真实事件。严格读取 wrapper，并将 id 规范化为 eventId。
Todo 列表真实字段是 todoCards，详情嵌套在 todoDetailModel错误 wrapper 使真实任务看似空结果或读回错对象。列表/详情分别建立严格 parser，详情必须绑定请求 taskId。
hasMore=true 时缺 cursor、重复 cursor 或只读首屏Top-N 被宣称为全量；空页可能提前结束。自动分页要求 token 前进；停滞、缺证据、超页上限均非零失败。
Calendar 删除后对象仍可读仅以“还能 get”判定删除失败，或仅凭 ack 判定成功。精确接受 absence 或同 eventId 的 cancelled/canceled/deleted tombstone，拒绝活动对象。
Todo 评论写回返回 result:{}从空 ack 伪造 commentId，或把请求正文当读回。完整读取写前/写后评论，要求唯一新增 ID 且正文精确一致。
Calendar attendee 真实项不含稳定 userId把 displayName 当 ID，发布无法兑现的身份合同。只投影 displayName、responseStatus、self；自身邀请通过当前 profile 与 self=true 绑定。
Calendar smart 写命令只看 ack 或 request echo创建、邀请、重排、取消的远端效果未知仍返回 0。create/update/invite 精确读回；cancel 验证 tombstone/absence；book 邀请失败时回滚并验证缺席。
Todo reminder 没有规则读回接口把 terminal success 伪装成 verified readback。结果固定标注 terminalReceipt=true、verified=false，报告公开边界。
live 清理最初遗漏子任务 ID能力全绿但测试数据仍残留。子任务进入反向清理账本；最终全量 marker 审计作为独立发布门，真实结果零残留。
+ +

Truthful execution

空结果与写成功的统一判定

这套合同同时落在 runtime、Result/Pagination 声明、负向回归和 live E2E，不只是报告规则。

读取 / 分页

1
外层与业务层都成功非零退出、success=false、空 body、malformed JSON 立即失败。
2
预期字段显式存在缺集合、null、非数组、坏 item 都不是合法空。
3
分页证据完整hasMore 必须配非空且前进的 token；上限未耗尽必须 incomplete/nonzero。
4
零命中与已知非空都验证只在空环境跑一次不能证明 projector 正确。

写入 / 读回

1
确认前零调用用户确认驱动 Runtime gate；存储示例不带 --yes。
2
明确终态与稳定 ID空 ack、无异常、request echo 均不是创建成功证据。
3
绑定同一对象读回ID、目标父级和关键字段必须与请求一致。
4
不可读回时降低声明明确 terminal-only / verified=false；不从截断列表或同名对象推断。
+ +

Complete public catalog

47 个公开主入口与 live 状态

兼容名 calendar +find-room、calendar +respond-event、todo +related-tasks 不重复计为主能力；unavailable 的 upload shortcut 也不计入公开 20 项。

47 / 47
+
+ + +
产品Shortcut用户任务 / 严格证据风险真实 E2E
Calendar+agenda范围日程；events + cursor 严格完整。READPASS
Calendar+attendee-list参会人可见信息；displayName/status/self，缺失稳定 ID 不伪造。READPASS
Calendar+book按姓名创建并邀请；详情读回，邀请失败回滚并验缺席。WRITE · CONFIRMPASS
Calendar+book-list日历本列表；显式 calendars 与稳定 calendarId。READPASS
Calendar+book-search按名称搜索日历本；已知非空 fixture。READPASS
Calendar+cancel-event取消日程；预读、确认、tombstone/absence 终态。HIGH · CONFIRMPASS
Calendar+conflicts完整页分析重叠日程并输出冲突对。READ · SMARTPASS
Calendar+create创建日程；eventId、时间、标题详情读回。WRITE · CONFIRMPASS
Calendar+free姓名解析后查参与者闲忙。READ · SMARTPASS
Calendar+free-slots工作时段空档；完整事件页、时长过滤。READ · SMARTPASS
Calendar+freebusy用户/房间闲忙；严格 busy 段和目标约束。READPASS
Calendar+get按 eventId 获取同一对象。READPASS
Calendar+invite姓名唯一解析后邀请；参会人读回。WRITE · CONFIRMPASS
Calendar+my-free当前用户在区间内是否空闲。READ · SMARTPASS
Calendar+next-event完整未来窗口定位最近下一场。READ · SMARTPASS
Calendar+reschedule重排同一事件；完整起止时间读回。WRITE · CONFIRMPASS
Calendar+room-find指定时段可用会议室；实现完成，当前租户稳定上游拒绝。READBLOCKED
Calendar+room-groups会议室分组；真实字段 groupList 严格投影。READPASS
Calendar+room-search名称定位而非可用性；合法零命中，缺安全已知非空 fixture。READBLOCKED
Calendar+rsvp受邀人响应与终态读回；自组织 fixture 被上游拒绝。WRITE · CONFIRMBLOCKED
Calendar+search-event页内条件搜索并保留 continuation，不谎报全局零命中。READPASS
Calendar+suggest-time姓名解析后查共同建议时段。READ · SMARTPASS
Calendar+suggestion按 ID 查询建议时段；显式数组。READPASS
Calendar+today时区感知的今日日程完整视图。READ · SMARTPASS
Calendar+tomorrow时区感知的明日日程完整视图。READ · SMARTPASS
Calendar+update字段/参会人分阶段更新与精确读回。WRITE · CONFIRMPASS
Calendar+week本周日程按日期整理，完整分页。READ · SMARTPASS
Todo+assign按姓名创建并指派单人任务；稳定 taskId 读回。WRITE · CONFIRMPASS
Todo+assign-multi全部姓名唯一解析后只创建一次。WRITE · CONFIRMPASS
Todo+comment写前/写后评论差分，唯一 commentId 与正文读回。WRITE · CONFIRMPASS
Todo+complete幂等完成并读回 isDone=true。WRITE · CONFIRMPASS
Todo+create创建并按 taskId 读回标题。WRITE · CONFIRMPASS
Todo+created-todos创建者角色全分页。READ · SMARTPASS
Todo+due-today本地日历日截止窗口，全分页命中 fixture。READ · SMARTPASS
Todo+gettodoDetailModel 必须绑定请求 taskId。READPASS
Todo+get-my-taskstodoCards 与 page/size/hasMore 完整。READPASS
Todo+get-related-tasks三角色全分页去重。READ · SMARTPASS
Todo+list-attachment显式 attachments 与稳定附件 ID；真实上传后读取。READPASS
Todo+list-comment显式 comments 与稳定 commentId。READPASS
Todo+list-sub显式 subTasks 与稳定 taskId。READPASS
Todo+overdue执行者角色全分页后按当前时间筛选。READ · SMARTPASS
Todo+remind解析当前用户后创建给自己的提醒任务。WRITE · CONFIRMPASS
Todo+reminder提醒规则终态 success；明确 verified=false。WRITE · CONFIRMPASS
Todo+reopen幂等重开并读回 isDone=false。WRITE · CONFIRMPASS
Todo+search全分页标题搜索；已知非空与合法零命中。READ · SMARTPASS
Todo+todo-done跨全部分页按标题唯一定位并完成。WRITE · CONFIRMPASS
Todo+update只改显式字段，同 taskId 逐字段读回。WRITE · CONFIRMPASS
+
+ +

Live evidence

真实数据矩阵：44 PASS / 3 BLOCKED / 0 FAIL

每个公开主入口都 exact 执行；raw 原始 JSON 只在内存解析，终端与报告只保留能力标签、聚合计数和稳定原因类别。

24 / 27

Calendar exact shortcut PASS：创建→读回→搜索/视图→更新/邀请→取消终态等完整链。

20 / 20

Todo exact shortcut PASS：生命周期、角色视图、评论、附件、提醒、子任务和清理。

3

BLOCKED：room-find 上游拒绝、room-search 缺安全非空 fixture、rsvp 缺安全受邀 fixture。

0

FAIL；最终资源审计 PASS，当前随机 marker 的活动 Calendar/Todo 残留均为零。

+
BLOCKED 不是 PASS：+room-search 的合法空数组只证明“零命中语义正确”，没有证明真实非空投影；+room-find 与 +rsvp 实际调用了 exact shortcut，但当前安全 fixture/租户收到上游拒绝。三项实现和确定性负向回归已完成，发布状态保留真实限制。
+

Calendar 实际断言

  • 未来 RFC3339 + 显式时区，start<end，读回时间一致。
  • create/get/agenda/search/update/cancel 全部绑定同一 eventId。
  • 分页、busy、suggestion、attendees 的坏元素均非零失败。
  • 取消接受真实 tombstone；book 回滚后验证对象缺席。

Todo 实际断言

  • create/get/list/update/complete/reopen/delete 全部绑定同一 taskId。
  • 子任务、评论、附件均在真实父任务中创建并读取。
  • all-page 角色视图、今日、逾期和搜索命中已知 fixture。
  • 清理按子→父反向执行，最后再次搜索确认零残留。
+
+ +

Release gates

工程、范围与脱敏门

报告不保存 profile、组织、成员、日历/事件/任务/评论/附件/会议室 ID、URL、标题正文、精确真实日程、trace、token 或本地绝对路径。

门结果说明
Build / focused testsPASSCalendar、Todo、smart 严格回归与跨平台覆盖通过。
Schema assembly / catalog / driftPASS27 products / 1138 tools；组装 deterministic，生成漂移为零。
Result / Safety coveragePASSCalendar 27 与 Todo 21 个 Schema shortcut leaves 均有 Result/Safety；Todo 计入 1 个 hidden unavailable。
Runtime confirmation truthPASS声明与真实确认 gate 同源；写能力未以元数据绕过确认。
Agent examplesPASS1403 个示例合同门通过；未向存储示例注入 --yes。
Full Go suitePASSDWS_PACKAGE_VERSION=0.0.0-test go test ./...。
Live exact E2EPASS44 capability PASS / 3 disclosed BLOCKED / 0 FAIL；cleanup audit PASS。
ScopePASS业务实现限定为 Shortcut；Skill 手写逻辑零改动，仅同步 3 个强制生成的发现区块。
PII / secret / history scanPASS最终树与提交差异只含脱敏工程事实，无 live 原始日志。
+
REVIEW 01

接受诚实的 3 个 BLOCKED

是否同意在没有安全 fixture/租户权限时保留明确原因，而不以 mock 或空数组提升为 PASS。

REVIEW 02

保持 assign 兼容

是否同意不破坏 DWS 历史“创建并指派”语义；未来如增加协作者管理，应使用新命令名。

REVIEW 03

上传保留原子路由

是否同意在 shortcut runtime 尚不能复用安全上传事务时维持 unavailable，避免复制凭证链。

+
+
DWS Calendar × Todo Shortcut business review · 2026-08-17 · sanitized engineering artifact
+
+ + + diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index 7d447fc7..c391663b 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,6 +1,6 @@ { - "generated_at": "2026-08-14T13:50:36.324505", - "count": 418, + "generated_at": "2026-08-17T15:52:13.675461", + "count": 435, "results": [ { "suite": "semantic", @@ -1056,144 +1056,274 @@ "status": "real-ok" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+agenda", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格验证 result.events 与分页证据，稳定投影 id 为 eventId；显式空数组才是空日程。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+attendee-list", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格验证参会人数组并投影显示名、响应状态和 self；真实后端不返回稳定参会人 userId，因此不伪造身份字段。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", "service": "calendar", "command": "+book", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按参会人姓名解析后创建日程，并在多步骤路径提供失败回滚与详情读回。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+book-list", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格验证日历本数组并稳定投影 calendarId，缺失数组不再误报为空。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+book-search", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "按日历本名称搜索并严格区分零命中与协议错误。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", "service": "calendar", "command": "+cancel-event", "risk": "high-risk-write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "删除前读取并展示目标，经高风险确认后取消指定日程。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+conflicts", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "在指定范围分析重叠日程并输出冲突对，避免人工逐项比对。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "calendar", + "command": "+create", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "创建响应必须给出 eventId/id，且标题和起止时间通过详情读回后才成功。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+free", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按姓名解析参与者后查询闲忙，省去手工 userId 解析。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+free-slots", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "从已有日程计算工作时段内空档，并显式输出满足时长的候选区间。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+freebusy", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "统一按用户或会议室 ID 查询指定范围闲忙，并声明至少一类目标约束。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", + "service": "calendar", + "command": "+get", + "risk": "read", + "status": "reviewed_available", + "disposition": "schema_leaf", + "semantic_delta": "严格读取日程对象并把稳定 id 规范化为 eventId，拒绝空响应和对象漂移。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+invite", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按姓名唯一解析用户后邀请到已有日程。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+my-free", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "以当前用户身份查询一个时间段是否空闲。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+next-event", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "在未来时间窗内定位最近的下一场日程。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", "service": "calendar", "command": "+reschedule", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "修改前读取目标日程，再更新完整起止时间。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "calendar", + "command": "+room-find", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "按单个未来时间段严格查询可用会议室，公开真实 page/pageSize/hasMore 证据和后端筛选边界。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+room-groups", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格读取 result.groupList，避免会议室分组被响应 wrapper 漂移静默清空。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+room-search", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "按名称查询会议室但不声称检查时间可用性；缺失会议室数组直接失败。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "calendar", + "command": "+rsvp", + "risk": "write", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "把直白 RSVP 动作映射为 responseStatus，拒绝空 ack，并在写后读取日程终态。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "calendar", + "command": "+search-event", + "risk": "read", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "在服务端日程当前页按标题、描述和地点过滤，同时保留 hasMore/nextCursor，绝不把单页零命中当全局未找到。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+suggest-time", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按姓名逐个唯一解析参与者，再查询大家共同可用的建议时间。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "calendar", + "command": "+suggestion", + "risk": "read", + "status": "reviewed_available", + "disposition": "schema_leaf", + "semantic_delta": "直接按 userId 查询建议时段，严格区分显式空 recommendEventTimes 与缺失或畸形响应。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+today", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "查询并整理今天的日程视图。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "calendar", "command": "+tomorrow", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "查询并整理明天的日程视图。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "calendar", + "command": "+update", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "组合字段与参会人分阶段更新，明确非事务步骤并以详情和参会人列表读回验证。", + "availability": "available" + }, + { + "suite": "semantic", "service": "calendar", "command": "+week", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "查询并按日期整理本周日程。", + "availability": "available" }, { "suite": "semantic", @@ -3582,81 +3712,214 @@ "status": "real-ok" }, { - "suite": "write", + "suite": "semantic", "service": "todo", "command": "+assign", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "保留历史按姓名解析后创建并指派的新任务语义，避免同名破坏性变更。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", "service": "todo", "command": "+assign-multi", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "全部姓名唯一解析后才创建一次，并以单一统一结果输出稳定 taskId。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "todo", + "command": "+comment", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "新增评论必须取得稳定 commentId，并分页读回验证内容。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "todo", + "command": "+complete", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "先读当前状态避免重复写，必要时完成后再读回核验。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "todo", + "command": "+create", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "创建后要求稳定 taskId，并读取 todoDetailModel 验证标题。", + "availability": "available" + }, + { + "suite": "semantic", "service": "todo", "command": "+created-todos", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "遍历创建者角色的全部分页后投影。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "todo", + "command": "+due-today", + "risk": "read", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "按本地日历日构造服务端截止窗口并遍历全部分页。", + "availability": "available" + }, + { + "suite": "semantic", "service": "todo", "command": "+get", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格绑定 todoDetailModel.taskId，缺失或错绑均失败。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "todo", "command": "+get-my-tasks", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格识别 todoCards/hasMore/page/size；显式空数组才是空结果，并支持有界全量分页。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", + "service": "todo", + "command": "+get-related-tasks", + "risk": "read", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "遍历与我相关三种角色的全部分页并按 taskId 去重。", + "availability": "available" + }, + { + "suite": "semantic", "service": "todo", "command": "+list-attachment", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格区分显式空附件与缺失容器，并要求每项稳定附件 ID。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "todo", "command": "+list-comment", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格区分显式空评论与缺失容器，并要求每项稳定 commentId。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "todo", "command": "+list-sub", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格校验子待办容器、对象元素和稳定 taskId。", + "availability": "available" }, { - "suite": "read", + "suite": "semantic", "service": "todo", "command": "+overdue", "risk": "read", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "遍历执行者角色的全部分页并按当前时间筛选逾期项。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", + "service": "todo", + "command": "+related-tasks", + "risk": "read", + "status": "reviewed_available", + "disposition": "alias_internal", + "semantic_delta": "保留旧命令拼写，新的 Agent 路由统一使用 +get-related-tasks。", + "availability": "available" + }, + { + "suite": "semantic", "service": "todo", "command": "+remind", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "解析当前用户后创建给自己的待办；该命令不是独立提醒规则。", + "availability": "available" }, { - "suite": "write", + "suite": "semantic", + "service": "todo", + "command": "+reminder", + "risk": "write", + "status": "reviewed_available", + "disposition": "semantic_adapter", + "semantic_delta": "严格验证提醒参数和 success=true 终端回执；上游不能读回规则，固定 verified=false。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "todo", + "command": "+reopen", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "先读当前状态避免重复写，必要时重开后再读回核验。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "todo", + "command": "+search", + "risk": "read", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "遍历全部 hasMore 分页并按标题匹配；达到页上限仍未耗尽时失败。", + "availability": "available" + }, + { + "suite": "semantic", "service": "todo", "command": "+todo-done", "risk": "write", - "status": "real-ok" + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "跨全部分页按标题唯一定位后完成任务。", + "availability": "available" + }, + { + "suite": "semantic", + "service": "todo", + "command": "+update", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "更新指定字段后读取详情逐字段核验。", + "availability": "available" }, { "suite": "semantic", diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 7b05cc89..6fc37da5 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -16,12 +16,12 @@ import ( ) const ( - publicShortcutCount = 418 + publicShortcutCount = 434 // schemaPublishedShortcutCount counts every delivered *.shortcut_* tool, // including the hidden historical minutes.shortcut_minutes_search contract. - schemaPublishedShortcutCount = 420 + schemaPublishedShortcutCount = 437 // publiclyDeliveredShortcutCount is the public-catalog subset of that surface. - publiclyDeliveredShortcutCount = 418 + publiclyDeliveredShortcutCount = 434 ) func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) { diff --git a/internal/shortcut/calendar/calendar.go b/internal/shortcut/calendar/calendar.go index 21ba0220..5817e6eb 100644 --- a/internal/shortcut/calendar/calendar.go +++ b/internal/shortcut/calendar/calendar.go @@ -78,11 +78,11 @@ var EventList = shortcut.Shortcut{ }, }, Flags: []shortcut.Flag{ - {Name: "start", Type: shortcut.FlagString, Desc: "开始时间 ISO-8601 (例如 2026-03-10T00:00:00+08:00)，默认今天 00:00"}, - {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601，默认今天 23:59"}, + {Name: "start", Type: shortcut.FlagString, Desc: "开始时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start；默认今天 00:00"}, + {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start；默认今天 23:59"}, {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID (默认 primary 主日历)"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标 (上一次返回的 nextCursor)"}, - {Name: "limit", Type: shortcut.FlagInt, Desc: "每页返回条数 (默认 100，最大 100)"}, + {Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页返回条数；limit 必须在 1-100 之间"}, }, Tips: []string{ `dws calendar +agenda`, @@ -118,12 +118,19 @@ var EventList = shortcut.Shortcut{ if rt.Changed("limit") { params["limit"] = rt.Int("limit") } + if params["endTime"].(int64) <= params["startTime"].(int64) { + return fmt.Errorf("--end 必须晚于 --start") + } data, err := rt.CallMCPData("calendar", "list_calendar_events", params) if err != nil { return err } - events := eventListProject(data) - return rt.Output(map[string]any{"count": len(events), "events": events}) + events, page, err := eventListProject(data) + if err != nil { + return err + } + out := map[string]any{"count": len(events), "events": events} + return outputCalendarPage(rt, out, page) }, } @@ -132,41 +139,27 @@ var EventList = shortcut.Shortcut{ // the clean output projection applied to every list command. The // list container and each field are probed defensively across candidate keys, // since event payloads may nest under result/data/list/items with aliases. -func eventListProject(data map[string]any) []map[string]any { - if data == nil { - return []map[string]any{} +func eventListProject(data map[string]any) ([]map[string]any, calendarPageEvidence, error) { + items, container, err := requireCalendarCollection(data, "calendar/list_calendar_events", "events") + if err != nil { + return nil, calendarPageEvidence{}, err } - raw := eventListContainer(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v, ok := eventListFirst(m, "eventId", "event_id", "id"); ok { - row["eventId"] = v - } - if v, ok := eventListFirst(m, "summary", "title", "name"); ok { - row["summary"] = v - } - if v, ok := eventListFirst(m, "start", "startTime", "start_time", "startDateTime", "start_date_time"); ok { - row["start"] = v - } - if v, ok := eventListFirst(m, "end", "endTime", "end_time", "endDateTime", "end_date_time"); ok { - row["end"] = v - } - if v, ok := eventListFirst(m, "status", "eventStatus", "event_status", "responseStatus", "response_status"); ok { - row["status"] = v - } - if v, ok := eventListFirst(m, "location", "locationName", "location_name"); ok { - row["location"] = v - } - if len(row) > 0 { - out = append(out, row) - } + rows, err := projectCalendarRows(items, "calendar/list_calendar_events", map[string][]string{ + "eventId": {"eventId", "event_id", "id"}, + "summary": {"summary", "title", "name"}, + "start": {"start", "startTime", "start_time", "startDateTime", "start_date_time"}, + "end": {"end", "endTime", "end_time", "endDateTime", "end_date_time"}, + "status": {"status", "eventStatus", "event_status", "responseStatus", "response_status"}, + "location": {"location", "locationName", "location_name"}, + }, "eventId") + if err != nil { + return nil, calendarPageEvidence{}, err } - return out + page, err := calendarPagination(container, "calendar/list_calendar_events") + if err == nil && !page.Known { + err = calendarResponseError("calendar/list_calendar_events", "missing_pagination", "日程列表响应缺少 hasMore/nextCursor 分页证据，不能判断结果是否完整") + } + return rows, page, err } // eventListContainer locates the event slice across candidate wrapper keys, @@ -257,7 +250,10 @@ var AttendeeList = shortcut.Shortcut{ if err != nil { return err } - attendees := attendeeListProject(data) + attendees, err := attendeeListProject(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(attendees), "attendees": attendees}) }, } @@ -267,32 +263,17 @@ var AttendeeList = shortcut.Shortcut{ // the clean output projection applied to every list command. // The list container and each field are probed defensively across candidate keys, // since participant payloads may nest under result/data/list/items with aliases. -func attendeeListProject(data map[string]any) []map[string]any { - if data == nil { - return []map[string]any{} +func attendeeListProject(data map[string]any) ([]map[string]any, error) { + items, _, err := requireCalendarCollection(data, "calendar/get_calendar_participants", "attendees", "participants", "items", "list") + if err != nil { + return nil, err } - raw := attendeeListContainer(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v, ok := attendeeFirst(m, "displayName", "display_name", "name", "userName", "user_name", "nick", "nickName"); ok { - row["displayName"] = v - } - if v, ok := attendeeFirst(m, "userId", "user_id", "id", "staffId", "staff_id", "unionId", "union_id"); ok { - row["userId"] = v - } - if v, ok := attendeeFirst(m, "responseStatus", "response_status", "status", "attendeeStatus", "attendee_status", "responseType", "response"); ok { - row["responseStatus"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out + return projectCalendarRows(items, "calendar/get_calendar_participants", map[string][]string{ + "displayName": {"displayName", "display_name", "name", "userName", "user_name", "nick", "nickName"}, + "userId": {"userId", "user_id", "id", "staffId", "staff_id", "unionId", "union_id"}, + "responseStatus": {"responseStatus", "response_status", "status", "attendeeStatus", "attendee_status", "responseType", "response"}, + "self": {"self"}, + }, "displayName") } // attendeeListContainer locates the participant slice across candidate wrapper @@ -375,7 +356,10 @@ var RoomSearch = shortcut.Shortcut{ if err != nil { return err } - rooms := roomSearchProject(data) + rooms, err := roomSearchProject(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(rooms), "rooms": rooms}) }, } @@ -385,35 +369,17 @@ var RoomSearch = shortcut.Shortcut{ // the framework applies to every list command. The list container and each field // are probed defensively across candidate keys, since room payloads may nest // under result/data/list/items with aliases. -func roomSearchProject(data map[string]any) []map[string]any { - if data == nil { - return []map[string]any{} +func roomSearchProject(data map[string]any) ([]map[string]any, error) { + items, _, err := requireCalendarCollection(data, "calendar/search_rooms", "rooms", "roomList", "meetingRooms", "items", "list") + if err != nil { + return nil, err } - raw := roomSearchContainer(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v, ok := roomSearchFirst(m, "roomId", "room_id", "id"); ok { - row["roomId"] = v - } - if v, ok := roomSearchFirst(m, "roomName", "room_name", "name", "summary"); ok { - row["roomName"] = v - } - if v, ok := roomSearchFirst(m, "capacity", "seats", "seatCount", "seat_count"); ok { - row["capacity"] = v - } - if v, ok := roomSearchFirst(m, "location", "floor", "building", "address"); ok { - row["location"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out + return projectCalendarRows(items, "calendar/search_rooms", map[string][]string{ + "roomId": {"roomId", "room_id", "id"}, + "roomName": {"roomName", "room_name", "name", "summary"}, + "capacity": {"capacity", "seats", "seatCount", "seat_count"}, + "location": {"location", "floor", "building", "address"}, + }, "roomId") } // roomSearchContainer locates the room slice across candidate wrapper keys, @@ -455,16 +421,43 @@ var RoomFind = shortcut.Shortcut{ Command: "+room-find", Product: "calendar", Description: "按时间段搜索可用会议室（不传时间默认当前起 1 小时）", - Intent: "当你要在某个时间段找一间空闲会议室开会时使用；传入 --start/--end 时间段（须为未来时间，缺省为当前起 1 小时），可加 --available 只看空闲、--group-id/--room-name 缩小范围，返回该时段的会议室及其可用性和 roomId，便于据此 +room-add 预定。", + Intent: "当你要在一个未来时间段寻找当前可预定的会议室时使用；--group-id/--room-name 可缩小范围，显式返回当前页和页码信息。该命令只查询单个时间段，后端不支持 Lark 风格多 slot、城市/楼宇/容量联合筛选。", Risk: shortcut.RiskRead, + Safety: calendarReadSafety(), + Contract: calendarContract( + "+room-find", "按时间段严格搜索可用会议室", + "需要按一个明确的未来时间段查询可用会议室，并保留真实页码信息时使用。", + []string{"只按名称查会议室而不检查可用性时改用 calendar +room-search", "要预订会议室时先取得 roomId，再使用原子 room add"}, + []string{`dws calendar +room-find --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"`}, + calendarCollectionResult("rooms", "严格校验的可用会议室当前页"), nil, + contract.ParamDecl{Name: "start", Property: "startTime"}, + contract.ParamDecl{Name: "end", Property: "endTime"}, + contract.ParamDecl{Name: "group-id", Property: "groupId"}, + contract.ParamDecl{Name: "room-name", Property: "roomName"}, + contract.ParamDecl{Name: "limit", Property: "pageSize"}, + contract.ParamDecl{Name: "page", Property: "pageIndex"}, + ), Flags: []shortcut.Flag{ - {Name: "start", Type: shortcut.FlagString, Desc: "开始时间 ISO-8601 (必须是未来时间)"}, - {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601"}, - {Name: "available", Type: shortcut.FlagBool, Desc: "仅返回可用会议室"}, + {Name: "start", Type: shortcut.FlagString, Desc: "开始时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, + {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, + {Name: "available", Type: shortcut.FlagBool, Hidden: true, Desc: "兼容旧调用；该命令本身始终只返回可用会议室"}, {Name: "group-id", Type: shortcut.FlagString, Desc: "会议室分组 ID"}, {Name: "room-name", Type: shortcut.FlagString, Desc: "会议室名称过滤"}, - {Name: "limit", Type: shortcut.FlagString, Desc: "每页条数 (pageSize)"}, - {Name: "page", Type: shortcut.FlagString, Desc: "页码 (pageIndex，从 0 开始)"}, + {Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "pageSize；limit 必须在 1-100 之间，page 不能小于 0"}, + {Name: "page", Type: shortcut.FlagInt, Default: "0", Desc: "pageIndex；limit 必须在 1-100 之间，page 不能小于 0"}, + }, + Validate: func(rt *shortcut.RuntimeContext) error { + if err := rt.RangeInt("limit", 1, 100); err != nil { + return err + } + if rt.Int("page") < 0 { + return fmt.Errorf("--page 不能小于 0") + } + return nil + }, + Constraints: []shortcut.Constraint{ + {Kind: shortcut.ConstraintCustom, Flags: []string{"start", "end"}, Description: "起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, + {Kind: shortcut.ConstraintCustom, Flags: []string{"limit", "page"}, Description: "limit 必须在 1-100 之间，page 不能小于 0"}, }, Tips: []string{ `dws calendar +room-find --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"`, @@ -487,12 +480,14 @@ var RoomFind = shortcut.Shortcut{ if err != nil { return err } + if endMs <= startMs { + return fmt.Errorf("--end 必须晚于 --start") + } params := map[string]any{ "startTime": startMs, "endTime": endMs, - } - if rt.Bool("available") { - params["needAvailable"] = true + "pageSize": fmt.Sprint(rt.Int("limit")), + "pageIndex": fmt.Sprint(rt.Int("page")), } if rt.Changed("group-id") { params["groupId"] = rt.Str("group-id") @@ -500,13 +495,34 @@ var RoomFind = shortcut.Shortcut{ if rt.Changed("room-name") { params["roomName"] = strings.TrimSpace(rt.Str("room-name")) } - if rt.Changed("limit") { - params["pageSize"] = rt.Str("limit") + data, err := rt.CallMCPData("calendar", "query_available_meeting_room", params) + if err != nil { + return err } - if rt.Changed("page") { - params["pageIndex"] = rt.Str("page") + items, container, err := requireCalendarCollection(data, "calendar/query_available_meeting_room", "rooms", "roomList", "meetingRoomList", "meetingRooms", "items", "list") + if err != nil { + return err } - return rt.CallMCP("query_available_meeting_room", params) + rooms, err := projectCalendarRows(items, "calendar/query_available_meeting_room", map[string][]string{ + "roomId": {"roomId", "room_id", "id"}, + "roomName": {"roomName", "room_name", "name", "summary"}, + "capacity": {"capacity", "maxCapacity", "seatCount", "seats"}, + "groupId": {"groupId", "group_id"}, + "supportRecurring": {"supportRecurring"}, + }, "roomId") + if err != nil { + return err + } + out := map[string]any{"count": len(rooms), "rooms": rooms, "page": rt.Int("page"), "pageSize": rt.Int("limit"), "complete": false} + for _, key := range []string{"hasMore", "totalCount", "total", "pageIndex", "pageSize"} { + if value, ok := container[key]; ok && value != nil { + out[key] = value + } + } + if hasMore, ok := out["hasMore"].(bool); ok { + out["complete"] = !hasMore + } + return rt.Output(out) }, } @@ -562,7 +578,10 @@ var RoomGroups = shortcut.Shortcut{ if err != nil { return err } - groups := roomGroupsProject(data) + groups, err := roomGroupsProject(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(groups), "groups": groups}) }, } @@ -572,29 +591,15 @@ var RoomGroups = shortcut.Shortcut{ // the framework applies to every list command. The list container and each field // are probed defensively across candidate keys, since group payloads may nest // under result/data/list/items with aliases. -func roomGroupsProject(data map[string]any) []map[string]any { - if data == nil { - return []map[string]any{} +func roomGroupsProject(data map[string]any) ([]map[string]any, error) { + items, _, err := requireCalendarCollection(data, "calendar/list_meeting_room_groups", "groupList", "groups", "items", "list") + if err != nil { + return nil, err } - raw := roomGroupsContainer(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v, ok := roomGroupsFirst(m, "groupId", "group_id", "id"); ok { - row["groupId"] = v - } - if v, ok := roomGroupsFirst(m, "groupName", "group_name", "name", "summary"); ok { - row["groupName"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out + return projectCalendarRows(items, "calendar/list_meeting_room_groups", map[string][]string{ + "groupId": {"groupId", "group_id", "id"}, + "groupName": {"groupName", "group_name", "name", "summary"}, + }, "groupId") } // roomGroupsContainer locates the group slice across candidate wrapper keys, @@ -699,10 +704,62 @@ var BusySearch = shortcut.Shortcut{ if len(rt.StrSlice("rooms")) > 0 { params["roomIds"] = rt.StrSlice("rooms") } - return rt.CallMCP("query_busy_status", params) + data, err := rt.CallMCPData("calendar", "query_busy_status", params) + if err != nil { + return err + } + busy, err := busySearchProject(data) + if err != nil { + return err + } + return rt.Output(map[string]any{"count": len(busy), "busy": busy, "free": len(busy) == 0, "complete": true}) }, } +func busySearchProject(data map[string]any) ([]map[string]any, error) { + entries, _, err := requireCalendarCollection(data, "calendar/query_busy_status", "busy", "entries") + if err != nil { + return nil, err + } + out := make([]map[string]any, 0) + for entryIndex, rawEntry := range entries { + entry := rawEntry.(map[string]any) + rawItems, present := entry["scheduleItems"] + if !present { + return nil, calendarResponseError("calendar/query_busy_status", "missing_schedule_items", fmt.Sprintf("result[%d] 缺少 scheduleItems", entryIndex)) + } + items, ok := rawItems.([]any) + if !ok { + return nil, calendarResponseError("calendar/query_busy_status", "malformed_schedule_items", fmt.Sprintf("result[%d].scheduleItems 不是数组", entryIndex)) + } + if err := validateCalendarCollectionItems(items, "calendar/query_busy_status", "scheduleItems"); err != nil { + return nil, err + } + for itemIndex, rawItem := range items { + item := rawItem.(map[string]any) + start := calendarBusyDateTime(item["start"]) + end := calendarBusyDateTime(item["end"]) + if calendarEmptyValue(start) || calendarEmptyValue(end) { + return nil, calendarResponseError("calendar/query_busy_status", "malformed_schedule_time", fmt.Sprintf("scheduleItems[%d] 缺少开始或结束时间", itemIndex)) + } + out = append(out, map[string]any{"start": start, "end": end}) + } + } + return out, nil +} + +func calendarBusyDateTime(value any) any { + if object, ok := value.(map[string]any); ok { + if dateTime, present := object["dateTime"]; present { + return dateTime + } + if date, present := object["date"]; present { + return date + } + } + return value +} + // ── attachment: 附件 ────────────────────────────────────────── // AttachmentAdd → add_attachments @@ -752,35 +809,28 @@ var BookList = shortcut.Shortcut{ if err != nil { return err } - books := bookListProject(data) + books, err := bookListProject(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(books), "calendars": books}) }, } // bookListProject reshapes list_calendars into a clean calendar-book list // (calendarId/summary/privilege/type) — clean output projection. -func bookListProject(data map[string]any) []map[string]any { - raw, ok := data["result"].([]any) - if !ok { - return []map[string]any{} +func bookListProject(data map[string]any) ([]map[string]any, error) { + items, _, err := requireCalendarCollection(data, "calendar/list_calendars", "calendars", "calendarList", "items", "list") + if err != nil { + return nil, err } - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - for _, k := range []string{"calendarId", "summary", "privilege", "type", "description"} { - if v, ok := m[k]; ok { - row[k] = v - } - } - if len(row) > 0 { - out = append(out, row) - } - } - return out + return projectCalendarRows(items, "calendar/list_calendars", map[string][]string{ + "calendarId": {"calendarId", "calendar_id", "id"}, + "summary": {"summary", "name", "title"}, + "privilege": {"privilege", "role", "accessRole"}, + "type": {"type", "calendarType", "calendar_type"}, + "description": {"description", "desc"}, + }, "calendarId") } // BookGet → get_calendar @@ -826,7 +876,10 @@ var BookSearch = shortcut.Shortcut{ if err != nil { return err } - calendars := bookSearchProject(data) + calendars, err := bookSearchProject(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(calendars), "calendars": calendars}) }, } @@ -835,35 +888,17 @@ var BookSearch = shortcut.Shortcut{ // stable calendar-book list (calendarId/summary/privilege/type) — output-projection // clean output projection. The list container and each field are probed defensively // across candidate keys, tolerating nesting under result/data/list/items. -func bookSearchProject(data map[string]any) []map[string]any { - if data == nil { - return []map[string]any{} +func bookSearchProject(data map[string]any) ([]map[string]any, error) { + items, _, err := requireCalendarCollection(data, "calendar/search_calendar", "calendars", "calendarList", "items", "list") + if err != nil { + return nil, err } - raw := bookSearchContainer(data) - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - m, ok := item.(map[string]any) - if !ok { - continue - } - row := map[string]any{} - if v, ok := bookSearchFirst(m, "calendarId", "calendar_id", "id"); ok { - row["calendarId"] = v - } - if v, ok := bookSearchFirst(m, "summary", "name", "title"); ok { - row["summary"] = v - } - if v, ok := bookSearchFirst(m, "privilege", "role", "accessRole"); ok { - row["privilege"] = v - } - if v, ok := bookSearchFirst(m, "type", "calendarType", "calendar_type"); ok { - row["type"] = v - } - if len(row) > 0 { - out = append(out, row) - } - } - return out + return projectCalendarRows(items, "calendar/search_calendar", map[string][]string{ + "calendarId": {"calendarId", "calendar_id", "id"}, + "summary": {"summary", "name", "title"}, + "privilege": {"privilege", "role", "accessRole"}, + "type": {"type", "calendarType", "calendar_type"}, + }, "calendarId") } // bookSearchContainer locates the calendar slice across candidate wrapper keys, @@ -901,8 +936,32 @@ func bookSearchFirst(m map[string]any, keys ...string) (any, bool) { // BookUpdate → update_calendar func init() { + EventList.Contract.Parameters = []contract.ParamDecl{ + {Name: "start", Property: "startTime"}, {Name: "end", Property: "endTime"}, + {Name: "calendar-id", Property: "calendarId"}, {Name: "cursor", Property: "cursor"}, {Name: "limit", Property: "limit"}, + } + EventList.Validate = func(rt *shortcut.RuntimeContext) error { return rt.RangeInt("limit", 1, 100) } + EventList.Constraints = []shortcut.Constraint{ + {Kind: shortcut.ConstraintCustom, Flags: []string{"start", "end"}, Description: "起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, + {Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "limit 必须在 1-100 之间"}, + } + finalizeCalendarShortcut(&EventList, calendarCollectionResult("events", "严格校验并保留分页证据的日程当前页"), calendarCursorPagination()) + finalizeCalendarShortcut(&AttendeeList, calendarObjectResult("严格校验的日程参会人列表"), nil) + finalizeCalendarShortcut(&RoomSearch, calendarObjectResult("严格校验的按名会议室列表"), nil) + finalizeCalendarShortcut(&RoomFind, RoomFind.Contract.Result, nil) + finalizeCalendarShortcut(&RoomGroups, calendarObjectResult("严格校验的会议室分组当前页"), nil) + finalizeCalendarShortcut(&BusySearch, calendarObjectResult("用户或会议室忙闲结果"), nil) + finalizeCalendarShortcut(&BookList, calendarObjectResult("严格校验的日历本列表"), nil) + finalizeCalendarShortcut(&BookSearch, calendarObjectResult("严格校验的日历本搜索结果"), nil) + EventSearch.Contract.Pagination = calendarCursorPagination() shortcut.Register( EventList, + EventGet, + EventCreate, + EventUpdate, + RSVP, + EventSearch, + Suggestion, AttendeeList, RoomSearch, RoomFind, diff --git a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go new file mode 100644 index 00000000..5517b031 --- /dev/null +++ b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go @@ -0,0 +1,167 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package calendar + +import ( + "context" + "encoding/json" + "errors" + "io" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +type calendarCoverageCaller struct { + responses map[string][]string + history []string + arguments []map[string]any +} + +func (caller *calendarCoverageCaller) CallTool(_ context.Context, _, tool string, arguments map[string]any) (*edition.ToolResult, error) { + caller.history = append(caller.history, tool) + caller.arguments = append(caller.arguments, arguments) + queue := caller.responses[tool] + if len(queue) == 0 { + return nil, errors.New("missing fake response for " + tool) + } + caller.responses[tool] = queue[1:] + if queue[0] == "__ERROR__" { + return nil, errors.New("injected calendar failure") + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: queue[0]}}}, nil +} + +func (*calendarCoverageCaller) Format() string { return "json" } +func (*calendarCoverageCaller) DryRun() bool { return false } +func (*calendarCoverageCaller) Fields() string { return "" } +func (*calendarCoverageCaller) JQ() string { return "" } + +func runCalendarCoverage(t *testing.T, declaration shortcut.Shortcut, caller *calendarCoverageCaller, args ...string) error { + t.Helper() + helpers.InitDepsForTest(t, caller) + declaration.OutputRollout = output.RolloutLegacyOnly + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + root.PersistentFlags().Bool("yes", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.PersistentFlags().String("format", "json", "") + service := &cobra.Command{Use: "calendar"} + service.AddCommand(corecmd.New(shortcut.FromShortcut(declaration))) + root.AddCommand(service) + root.SetOut(io.Discard) + root.SetErr(io.Discard) + root.SetArgs(append([]string{"calendar", declaration.Command}, args...)) + return root.Execute() +} + +func TestCrossPlatformCoverageCalendarListRequiresExplicitCollectionAndPagination(t *testing.T) { + var explicitEmpty map[string]any + if err := json.Unmarshal([]byte(`{"success":true,"result":{"events":[],"hasMore":false}}`), &explicitEmpty); err != nil { + t.Fatal(err) + } + events, page, err := eventListProject(explicitEmpty) + if err != nil || len(events) != 0 || !page.Known || page.HasMore { + t.Fatalf("explicit empty: events=%v page=%+v err=%v", events, page, err) + } + + for name, payload := range map[string]string{ + "missing collection": `{"success":true,"result":{"hasMore":false}}`, + "bad collection": `{"success":true,"result":{"events":{}}}`, + "bad item": `{"success":true,"result":{"events":["bad"],"hasMore":false}}`, + "empty item": `{"success":true,"result":{"events":[{}],"hasMore":false}}`, + "missing pagination": `{"success":true,"result":{"events":[]}}`, + "missing next cursor": `{"success":true,"result":{"events":[],"hasMore":true}}`, + } { + t.Run(name, func(t *testing.T) { + var data map[string]any + if err := json.Unmarshal([]byte(payload), &data); err != nil { + t.Fatal(err) + } + if _, _, err := eventListProject(data); err == nil { + t.Fatalf("payload unexpectedly accepted: %s", payload) + } + }) + } + + var nextPage map[string]any + if err := json.Unmarshal([]byte(`{"success":true,"result":{"events":[{"id":"event-1","summary":"review"}],"hasMore":true,"nextCursor":"cursor-2"}}`), &nextPage); err != nil { + t.Fatal(err) + } + events, page, err = eventListProject(nextPage) + if err != nil || len(events) != 1 || events[0]["eventId"] != "event-1" || !page.HasMore || page.NextCursor != "cursor-2" { + t.Fatalf("next page projection: events=%#v page=%+v err=%v", events, page, err) + } +} + +func TestCrossPlatformCoverageCalendarObjectsAndWritesFailClosed(t *testing.T) { + for name, payload := range map[string]map[string]any{ + "empty": {}, + "success false": {"success": false, "errorMsg": "denied"}, + "nonterminal receipt": {"result": map[string]any{"id": "event-1"}}, + } { + t.Run(name, func(t *testing.T) { + if _, err := requireCalendarWriteResponse(payload, "calendar/write"); err == nil { + t.Fatalf("payload unexpectedly accepted: %#v", payload) + } + }) + } + if _, err := requireCalendarWriteResponse(map[string]any{"success": true, "result": map[string]any{"id": "event-1"}}, "calendar/write"); err != nil { + t.Fatalf("terminal write rejected: %v", err) + } + event, err := requireCalendarEvent(map[string]any{"success": true, "result": map[string]any{"id": "event-1", "summary": "review"}}, "calendar/get_calendar_detail", "event-1") + if err != nil || normalizeCalendarEvent(event)["eventId"] != "event-1" { + t.Fatalf("event normalization: event=%#v err=%v", event, err) + } + if _, err := requireCalendarEvent(map[string]any{"success": true, "result": map[string]any{"summary": "missing id"}}, "calendar/get_calendar_detail", "event-1"); err == nil { + t.Fatal("event without id unexpectedly accepted") + } +} + +func TestCrossPlatformCoverageCalendarCreateReadsBackTerminalState(t *testing.T) { + caller := &calendarCoverageCaller{responses: map[string][]string{ + "create_calendar_event": {`{"success":true,"result":{"id":"event-1"}}`}, + "get_calendar_detail": {`{"success":true,"result":{"id":"event-1","summary":"review","start":{"dateTime":"2026-03-10T14:00:00+08:00"},"end":{"dateTime":"2026-03-10T15:00:00+08:00"}}}`}, + }} + err := runCalendarCoverage(t, EventCreate, caller, + "--title", "review", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T15:00:00+08:00", "--yes") + if err != nil { + t.Fatal(err) + } + if got := strings.Join(caller.history, ","); got != "create_calendar_event,get_calendar_detail" { + t.Fatalf("history=%s", got) + } + + noReceipt := &calendarCoverageCaller{responses: map[string][]string{"create_calendar_event": {`{"result":{"id":"event-2"}}`}}} + err = runCalendarCoverage(t, EventCreate, noReceipt, + "--title", "review", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T15:00:00+08:00", "--yes") + if err == nil || !strings.Contains(err.Error(), "success=true") { + t.Fatalf("non-terminal create error=%v", err) + } +} + +func TestCrossPlatformCoverageCalendarAlignedContracts(t *testing.T) { + for _, declaration := range []shortcut.Shortcut{EventGet, EventCreate, EventUpdate, RSVP, EventSearch, Suggestion, RoomFind} { + if declaration.Contract.Empty() || declaration.Contract.Result == nil { + t.Errorf("%s missing contract/result", declaration.Command) + } + if strings.TrimSpace(declaration.Safety.Effect) == "" || strings.TrimSpace(declaration.Safety.Confirmation) == "" { + t.Errorf("%s missing safety", declaration.Command) + } + if declaration.OutputRollout != output.RolloutUnifiedActive { + t.Errorf("%s output rollout=%q", declaration.Command, declaration.OutputRollout) + } + } + if EventSearch.Contract.Pagination == nil || EventList.Contract.Pagination == nil { + t.Fatal("cursor commands must publish pagination contracts") + } + if EventCreate.Safety.Confirmation != "user_required" || EventUpdate.Safety.Confirmation != "user_required" || RSVP.Safety.Confirmation != "user_required" { + t.Fatal("calendar writes must require confirmation") + } +} diff --git a/internal/shortcut/calendar/common.go b/internal/shortcut/calendar/common.go new file mode 100644 index 00000000..988f7fdd --- /dev/null +++ b/internal/shortcut/calendar/common.go @@ -0,0 +1,490 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package calendar + +import ( + "encoding/json" + "fmt" + "math" + "strconv" + "strings" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +const calendarCompositeReason = "Reviewed Calendar Shortcut composite: the executable CLI owns strict response validation, truthful pagination, optional multi-step writes, read-back verification, and confirmation; no single MCP interface represents the complete command contract." + +func calendarContract(command, description, useWhen string, avoidWhen, examples []string, result *contract.ResultSpec, pagination *contract.PaginationSpec, params ...contract.ParamDecl) corecmd.ContractDecl { + name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(command, "+"), "-", "_") + cliPath := "calendar " + command + return corecmd.ContractDecl{ + Description: description, + Parameters: params, + Result: result, + Pagination: pagination, + Interface: &contract.InterfaceSpec{ + Mode: contract.InterfaceModeComposite, + Availability: contract.InterfaceAvailable, + Reason: calendarCompositeReason, + }, + Selection: contract.SelectionSpec{ + AgentSummary: description, + UseWhen: []string{useWhen}, + AvoidWhen: avoidWhen, + Examples: examples, + }, + Identity: contract.ToolIdentitySpec{ + ProductID: "calendar", + Name: name, + CanonicalPath: "calendar." + name, + CLIPath: cliPath, + PrimaryCLIPath: cliPath, + }, + } +} + +func calendarObjectResult(description string, outcomes ...contract.ResultOutcome) *contract.ResultSpec { + if len(outcomes) == 0 { + outcomes = []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure} + } + return &contract.ResultSpec{ + Outcomes: outcomes, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"additionalProperties":true}`, + description, + )), + } +} + +func calendarCollectionResult(collection, description string) *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"本页有效业务记录数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"Calendar 业务条目","additionalProperties":true}},"complete":{"type":"boolean","description":"服务端分页证据是否证明结果已完整"},"hasMore":{"type":"boolean","description":"服务端是否明确仍有后续页"},"nextCursor":{"type":"string","description":"服务端返回的下一页游标"}},"required":["count",%q,"complete"],"additionalProperties":true}`, + description, collection, description, collection, + )), + } +} + +func calendarCursorPagination() *contract.PaginationSpec { + return &contract.PaginationSpec{ + Kind: contract.PaginationKindCursor, + CursorParameter: "cursor", + MetaPath: contract.PaginationMetaPath, + EndpointExhaustedPath: contract.PaginationExhaustedPath, + NextTokenPath: contract.PaginationNextTokenPath, + } +} + +func calendarReadSafety() contract.SafetySpec { + return contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"} +} + +func calendarWriteSafety() contract.SafetySpec { + return contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "unknown"} +} + +func calendarResponseError(operation, reason, message string) error { + return apperrors.NewAPI(message, + apperrors.WithOperation(operation), + apperrors.WithOrigin("mcp"), + apperrors.WithFailureStage("response_validation"), + apperrors.WithRetryable(false), + apperrors.WithReason(reason), + ) +} + +func requireCalendarResponse(data map[string]any, operation string) (map[string]any, error) { + if len(data) == 0 { + return nil, calendarResponseError(operation, "empty_tool_response", "服务返回空响应，无法证明操作成功或结果确实为空") + } + for _, candidate := range calendarContainers(data) { + value, present := candidate["success"] + if !present { + continue + } + success, ok := value.(bool) + if !ok { + return nil, calendarResponseError(operation, "malformed_success", "响应 success 字段不是布尔值") + } + if !success { + message := firstCalendarString(candidate, "errorMsg", "errorMessage", "message", "error") + if message == "" { + message = "服务明确返回 success=false" + } + return nil, calendarResponseError(operation, "remote_failure", message) + } + } + return data, nil +} + +func requireCalendarWriteResponse(data map[string]any, operation string) (map[string]any, error) { + data, err := requireCalendarResponse(data, operation) + if err != nil { + return nil, err + } + for _, candidate := range calendarContainers(data) { + if success, ok := candidate["success"].(bool); ok && success { + return data, nil + } + } + return nil, calendarResponseError(operation, "missing_terminal_success", "写操作响应没有 success=true 终态证据；远端效果未知") +} + +func calendarContainers(data map[string]any) []map[string]any { + if data == nil { + return nil + } + containers := []map[string]any{data} + seen := map[mapIdentity]bool{} + for depth, index := 0, 0; index < len(containers) && depth < 12; index, depth = index+1, depth+1 { + candidate := containers[index] + for _, key := range []string{"content", "result", "data", "event"} { + if nested, ok := candidate[key].(map[string]any); ok { + identity := mapIdentity{parent: index, key: key} + if !seen[identity] { + seen[identity] = true + containers = append(containers, nested) + } + } + } + } + return containers +} + +type mapIdentity struct { + parent int + key string +} + +func requireCalendarObject(data map[string]any, operation string) (map[string]any, error) { + data, err := requireCalendarResponse(data, operation) + if err != nil { + return nil, err + } + containers := calendarContainers(data) + for index := len(containers) - 1; index >= 0; index-- { + candidate := containers[index] + if len(candidate) == 0 || calendarOnlyEnvelopeFields(candidate) { + continue + } + return candidate, nil + } + return nil, calendarResponseError(operation, "missing_business_result", "响应没有可验证的业务对象") +} + +func calendarOnlyEnvelopeFields(candidate map[string]any) bool { + for key := range candidate { + switch key { + case "success", "result", "data", "content", "message", "errorMsg", "errorMessage": + default: + return false + } + } + return true +} + +func requireCalendarCollection(data map[string]any, operation string, keys ...string) ([]any, map[string]any, error) { + data, err := requireCalendarResponse(data, operation) + if err != nil { + return nil, nil, err + } + for _, container := range calendarContainers(data) { + for _, key := range keys { + value, present := container[key] + if !present { + continue + } + items, ok := value.([]any) + if !ok { + return nil, nil, calendarResponseError(operation, "malformed_collection", fmt.Sprintf("响应 %s 字段不是数组", key)) + } + if err := validateCalendarCollectionItems(items, operation, key); err != nil { + return nil, nil, err + } + return items, container, nil + } + } + for _, wrapper := range []string{"result", "data"} { + if value, present := data[wrapper]; present { + if items, ok := value.([]any); ok { + if err := validateCalendarCollectionItems(items, operation, wrapper); err != nil { + return nil, nil, err + } + return items, data, nil + } + } + } + return nil, nil, calendarResponseError(operation, "missing_collection", "响应缺少声明的业务数组；不能把缺字段、内部错误或协议漂移投影成空结果") +} + +func validateCalendarCollectionItems(items []any, operation, key string) error { + for index, item := range items { + object, ok := item.(map[string]any) + if !ok || len(object) == 0 { + return calendarResponseError(operation, "malformed_collection_item", fmt.Sprintf("响应 %s[%d] 不是非空对象", key, index)) + } + } + return nil +} + +func projectCalendarRows(items []any, operation string, aliases map[string][]string, requiredAny ...string) ([]map[string]any, error) { + rows := make([]map[string]any, 0, len(items)) + for index, item := range items { + source := item.(map[string]any) + row := make(map[string]any) + for canonical, candidates := range aliases { + for _, candidate := range candidates { + if value, ok := source[candidate]; ok && value != nil { + row[canonical] = value + break + } + } + } + valid := len(requiredAny) == 0 && len(row) > 0 + for _, required := range requiredAny { + if value, ok := row[required]; ok && !calendarEmptyValue(value) { + valid = true + break + } + } + if !valid { + return nil, calendarResponseError(operation, "malformed_collection_item", fmt.Sprintf("业务数组第 %d 项缺少可识别的标识或时间字段", index)) + } + rows = append(rows, row) + } + return rows, nil +} + +func calendarEmptyValue(value any) bool { + if value == nil { + return true + } + if text, ok := value.(string); ok { + return strings.TrimSpace(text) == "" + } + return false +} + +type calendarPageEvidence struct { + Known bool + HasMore bool + NextCursor string +} + +func calendarPagination(container map[string]any, operation string) (calendarPageEvidence, error) { + page := calendarPageEvidence{} + if container == nil { + return page, nil + } + if raw, present := container["hasMore"]; present { + value, ok := raw.(bool) + if !ok { + return page, calendarResponseError(operation, "malformed_pagination", "响应 hasMore 字段不是布尔值") + } + page.Known = true + page.HasMore = value + } + for _, key := range []string{"nextCursor", "nextToken", "pageToken"} { + raw, present := container[key] + if !present || raw == nil { + continue + } + value, ok := raw.(string) + if !ok { + return page, calendarResponseError(operation, "malformed_pagination", fmt.Sprintf("响应 %s 字段不是字符串", key)) + } + page.Known = true + page.NextCursor = strings.TrimSpace(value) + break + } + if page.HasMore && page.NextCursor == "" { + return page, calendarResponseError(operation, "missing_next_cursor", "服务端返回 hasMore=true 但没有可续用的 nextCursor，结果不完整") + } + if page.Known && !page.HasMore && page.NextCursor != "" { + return page, calendarResponseError(operation, "inconsistent_pagination", "服务端返回 hasMore=false 但仍携带非空 nextCursor") + } + if page.NextCursor != "" { + page.HasMore = true + } + return page, nil +} + +func addCalendarPagination(out map[string]any, page calendarPageEvidence) { + out["complete"] = page.Known && !page.HasMore + if page.Known { + out["hasMore"] = page.HasMore + } + if page.NextCursor != "" { + out["nextCursor"] = page.NextCursor + } +} + +// outputCalendarPage keeps legacy JSON compatibility while honoring the +// unified Result contract: cursor controls move to meta.pagination and are not +// duplicated into business data. +func outputCalendarPage(rt *shortcut.RuntimeContext, payload map[string]any, page calendarPageEvidence) error { + if !page.Known { + return calendarResponseError("calendar/pagination", "missing_pagination", "响应缺少分页终态证据") + } + addCalendarPagination(payload, page) + if !output.UsesUnifiedResult(rt.Command()) { + return rt.Output(payload) + } + pagination, err := output.NewPagination(!page.HasMore, page.NextCursor) + if err != nil { + return calendarResponseError("calendar/pagination", "invalid_pagination", err.Error()) + } + business := make(map[string]any, len(payload)) + for key, value := range payload { + switch key { + case "hasMore", "nextCursor": + default: + business[key] = value + } + } + meta := &output.Meta{Pagination: pagination} + if count, ok := payload["count"].(int); ok { + meta.Count = output.NewCount(count) + } + return output.StoreResult(rt.Command().Context(), output.Success(business, output.WithMeta(meta))) +} + +func firstCalendarString(data map[string]any, keys ...string) string { + for _, key := range keys { + if value, ok := data[key].(string); ok && strings.TrimSpace(value) != "" { + return strings.TrimSpace(value) + } + } + return "" +} + +func nestedCalendarString(data map[string]any, keys ...string) string { + for _, candidate := range calendarContainers(data) { + if value := firstCalendarString(candidate, keys...); value != "" { + return value + } + } + return "" +} + +func validateCalendarRange(startName, startValue, endName, endValue string) (time.Time, time.Time, error) { + start, err := time.Parse(time.RFC3339, strings.TrimSpace(startValue)) + if err != nil { + return time.Time{}, time.Time{}, apperrors.NewValidation(fmt.Sprintf("--%s 时间格式无效，请使用 RFC3339/ISO-8601", startName)) + } + end, err := time.Parse(time.RFC3339, strings.TrimSpace(endValue)) + if err != nil { + return time.Time{}, time.Time{}, apperrors.NewValidation(fmt.Sprintf("--%s 时间格式无效，请使用 RFC3339/ISO-8601", endName)) + } + if !end.After(start) { + return time.Time{}, time.Time{}, apperrors.NewValidation(fmt.Sprintf("--%s 必须晚于 --%s", endName, startName)) + } + return start, end, nil +} + +func calendarStringList(values []string) []string { + out := make([]string, 0, len(values)) + seen := map[string]bool{} + for _, value := range values { + value = strings.TrimSpace(value) + if value != "" && !seen[value] { + seen[value] = true + out = append(out, value) + } + } + return out +} + +func calendarEventID(event map[string]any) string { + return firstCalendarString(event, "eventId", "event_id", "id") +} + +func calendarTimeEquivalent(actual any, expected string) bool { + want, err := time.Parse(time.RFC3339, expected) + if err != nil { + return false + } + if object, ok := actual.(map[string]any); ok { + for _, key := range []string{"dateTime", "date_time", "value", "timestamp"} { + if nested, exists := object[key]; exists { + return calendarTimeEquivalent(nested, expected) + } + } + } + switch value := actual.(type) { + case string: + if parsed, err := time.Parse(time.RFC3339, strings.TrimSpace(value)); err == nil { + return parsed.Equal(want) + } + millis, err := strconv.ParseInt(strings.TrimSpace(value), 10, 64) + return err == nil && time.UnixMilli(millis).Equal(want) + case float64: + return !math.IsNaN(value) && !math.IsInf(value, 0) && value == math.Trunc(value) && time.UnixMilli(int64(value)).Equal(want) + case int64: + return time.UnixMilli(value).Equal(want) + case int: + return time.UnixMilli(int64(value)).Equal(want) + default: + return false + } +} + +func verifyCalendarEvent(event map[string]any, eventID string, requested map[string]any) error { + if got := calendarEventID(event); got == "" || got != eventID { + return calendarResponseError("calendar/get_calendar_detail", "readback_id_mismatch", "写后读回的 eventId 缺失或不一致") + } + aliases := map[string][]string{ + "summary": {"summary", "title", "name"}, + "description": {"description", "desc"}, + "startDateTime": {"startDateTime", "start_time", "startTime", "start"}, + "endDateTime": {"endDateTime", "end_time", "endTime", "end"}, + "timeZone": {"timeZone", "timezone", "time_zone"}, + "location": {"location", "locationName", "location_name"}, + "freeBusy": {"freeBusy", "free_busy"}, + } + for property, expected := range requested { + candidates := aliases[property] + if len(candidates) == 0 { + continue + } + var actual any + var present bool + for _, candidate := range candidates { + actual, present = event[candidate] + if present { + break + } + } + if !present { + return calendarResponseError("calendar/get_calendar_detail", "readback_field_missing", fmt.Sprintf("写后读回缺少字段 %s", property)) + } + if property == "startDateTime" || property == "endDateTime" { + if !calendarTimeEquivalent(actual, fmt.Sprint(expected)) { + return calendarResponseError("calendar/get_calendar_detail", "readback_field_mismatch", fmt.Sprintf("写后读回字段 %s 与请求不一致", property)) + } + continue + } + if strings.TrimSpace(fmt.Sprint(actual)) != strings.TrimSpace(fmt.Sprint(expected)) { + return calendarResponseError("calendar/get_calendar_detail", "readback_field_mismatch", fmt.Sprintf("写后读回字段 %s 与请求不一致", property)) + } + } + return nil +} + +func finalizeCalendarShortcut(item *shortcut.Shortcut, result *contract.ResultSpec, pagination *contract.PaginationSpec) { + item.OutputRollout = output.RolloutUnifiedActive + item.Contract.Result = result + item.Contract.Pagination = pagination + item.Contract.Selection.AgentSummary = item.Description + item.Contract.Selection.UseWhen = []string{item.Intent} + if item.Contract.Interface == nil { + item.Contract.Interface = &contract.InterfaceSpec{Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: calendarCompositeReason} + } +} diff --git a/internal/shortcut/calendar/event_shortcuts.go b/internal/shortcut/calendar/event_shortcuts.go new file mode 100644 index 00000000..449e7979 --- /dev/null +++ b/internal/shortcut/calendar/event_shortcuts.go @@ -0,0 +1,604 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package calendar + +import ( + "fmt" + "strings" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +func calendarReadShortcut(command, description, intent, collection string, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { + result := calendarObjectResult(description) + if collection != "" { + result = calendarCollectionResult(collection, description) + } + return shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "calendar", + Command: command, + Product: "calendar", + Description: description, + Intent: intent, + Risk: shortcut.RiskRead, + Safety: calendarReadSafety(), + Contract: calendarContract(command, description, intent, + []string{"需要未公开底层参数或原始 MCP 响应时改用对应原子命令；缺失业务对象或数组不是合法空结果"}, + []string{calendarExample(command)}, result, nil, params...), + Flags: flags, + Execute: execute, + } +} + +func calendarWriteShortcut(command, description, intent, example string, flags []shortcut.Flag, params []contract.ParamDecl, execute func(*shortcut.RuntimeContext) error) shortcut.Shortcut { + return shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "calendar", + Command: command, + Product: "calendar", + Description: description, + Intent: intent, + Risk: shortcut.RiskWrite, + Safety: calendarWriteSafety(), + Contract: calendarContract(command, description, intent, + []string{"只需查看日程或尚未确认目标 eventId/影响范围时不要执行写操作"}, + []string{example}, calendarObjectResult(description, contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure), nil, params...), + Flags: flags, + Execute: execute, + } +} + +func calendarExample(command string) string { + switch command { + case "+get": + return "dws calendar +get --event --format json" + case "+search-event": + return `dws calendar +search-event --query "评审" --format json` + case "+suggestion": + return "dws calendar +suggestion --users --duration 30 --format json" + default: + return "dws calendar " + command + " --format json" + } +} + +// EventGet is the strict shortcut counterpart of calendar event get. A missing +// result object and a result object without an id are protocol failures. +var EventGet = calendarReadShortcut( + "+get", "严格获取日程详情", + "已知 eventId 时读取完整日程；把后端稳定 id 规范化为 eventId，并拒绝空响应、缺失对象或错误对象。", + "", + []shortcut.Flag{ + {Name: "event", Type: shortcut.FlagString, Required: true, Desc: "日程 eventId"}, + {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID（默认 primary）"}, + }, + []contract.ParamDecl{{Name: "event", Property: "eventId"}, {Name: "calendar-id", Property: "calendarId"}}, + func(rt *shortcut.RuntimeContext) error { + params := calendarEventTarget(rt) + data, err := rt.CallMCPData("calendar", "get_calendar_detail", params) + if err != nil { + return err + } + event, err := requireCalendarEvent(data, "calendar/get_calendar_detail", rt.Str("event")) + if err != nil { + return err + } + return rt.Output(map[string]any{"event": normalizeCalendarEvent(event)}) + }, +) + +// EventCreate creates one event and requires an event id plus a successful +// get_calendar_detail read-back before reporting success. +var EventCreate = calendarWriteShortcut( + "+create", "创建日程并读回验证", + "创建单次日程，可同时传 userId 参会人和 roomId；只有创建响应给出 eventId 且详情读回与标题、起止时间一致时才报告成功。", + `dws calendar +create --title "项目评审" --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --format json`, + []shortcut.Flag{ + {Name: "title", Type: shortcut.FlagString, Required: true, Desc: "日程标题，最多 2048 字符"}, + {Name: "start", Type: shortcut.FlagString, Required: true, Desc: "开始时间 RFC3339/ISO-8601"}, + {Name: "end", Type: shortcut.FlagString, Required: true, Desc: "结束时间 RFC3339/ISO-8601"}, + {Name: "desc", Type: shortcut.FlagString, Desc: "日程描述，最多 5000 字符"}, + {Name: "attendees", Type: shortcut.FlagStringSlice, Desc: "参会人 userId，最多 500 个"}, + {Name: "rooms", Type: shortcut.FlagStringSlice, Desc: "会议室 roomId"}, + {Name: "timezone", Type: shortcut.FlagString, Desc: "IANA 时区，如 Asia/Shanghai"}, + {Name: "location", Type: shortcut.FlagString, Desc: "地点文本"}, + {Name: "free-busy", Type: shortcut.FlagString, Desc: "忙闲状态", Enum: []string{"busy", "free"}}, + {Name: "calendar-id", Type: shortcut.FlagString, Desc: "目标日历 ID（默认 primary）"}, + }, + []contract.ParamDecl{ + {Name: "title", Property: "summary"}, {Name: "start", Property: "startDateTime"}, {Name: "end", Property: "endDateTime"}, + {Name: "desc", Property: "description"}, {Name: "attendees", Property: "attendees"}, {Name: "rooms", Property: "roomIds"}, + {Name: "timezone", Property: "timeZone"}, {Name: "location", Property: "location"}, {Name: "free-busy", Property: "freeBusy"}, + {Name: "calendar-id", Property: "calendarId"}, + }, + func(rt *shortcut.RuntimeContext) error { + params, verify, err := calendarCreateParams(rt) + if err != nil { + return err + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "calendar/create_calendar_event", "arguments": params}) + } + written, err := rt.CallMCPWriteDataStrict("calendar", "create_calendar_event", params) + if err != nil { + return err + } + written, err = requireCalendarWriteResponse(written, "calendar/create_calendar_event") + if err != nil { + return err + } + eventID := nestedCalendarString(written, "eventId", "event_id", "id") + if eventID == "" { + return calendarResponseError("calendar/create_calendar_event", "missing_created_id", "创建响应没有 eventId/id；远端效果未知") + } + readParams := map[string]any{"eventId": eventID} + if calendarID := rt.Str("calendar-id"); calendarID != "" { + readParams["calendarId"] = calendarID + } + readback, err := rt.CallMCPData("calendar", "get_calendar_detail", readParams) + if err != nil { + return err + } + event, err := requireCalendarEvent(readback, "calendar/get_calendar_detail", eventID) + if err != nil { + return err + } + if err := verifyCalendarEvent(event, eventID, verify); err != nil { + return err + } + return rt.Output(map[string]any{"success": true, "eventId": eventID, "verified": true, "event": normalizeCalendarEvent(event)}) + }, +) + +// EventUpdate applies event fields and attendee changes as explicit stages. +// It never rolls back or hides a later-stage failure; errors name completed +// stages so callers can safely inspect state before retrying. +var EventUpdate = calendarWriteShortcut( + "+update", "分阶段更新日程并读回验证", + "已知 eventId 时更新标题、描述、完整起止时间或参会人；多阶段写不是事务，任一步失败都会列出已经完成的步骤，成功则读回字段和参会人集合。", + `dws calendar +update --event --title "新标题" --format json`, + []shortcut.Flag{ + {Name: "event", Type: shortcut.FlagString, Required: true, Desc: "日程 eventId"}, + {Name: "title", Type: shortcut.FlagString, Desc: "新标题"}, + {Name: "desc", Type: shortcut.FlagString, Desc: "新描述"}, + {Name: "start", Type: shortcut.FlagString, Desc: "新开始时间；必须与 --end 同时传"}, + {Name: "end", Type: shortcut.FlagString, Desc: "新结束时间；必须与 --start 同时传"}, + {Name: "timezone", Type: shortcut.FlagString, Desc: "IANA 时区"}, + {Name: "location", Type: shortcut.FlagString, Desc: "新地点文本"}, + {Name: "free-busy", Type: shortcut.FlagString, Desc: "忙闲状态", Enum: []string{"busy", "free"}}, + {Name: "add-attendees", Type: shortcut.FlagStringSlice, Desc: "新增参会人 userId"}, + {Name: "remove-attendees", Type: shortcut.FlagStringSlice, Desc: "移除参会人 userId"}, + {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID（默认 primary）"}, + }, + []contract.ParamDecl{ + {Name: "event", Property: "eventId"}, {Name: "title", Property: "summary"}, {Name: "desc", Property: "description"}, + {Name: "start", Property: "startDateTime"}, {Name: "end", Property: "endDateTime"}, {Name: "timezone", Property: "timeZone"}, + {Name: "location", Property: "location"}, {Name: "free-busy", Property: "freeBusy"}, + {Name: "add-attendees", Property: "attendeesToAdd"}, {Name: "remove-attendees", Property: "attendeesToRemove"}, + {Name: "calendar-id", Property: "calendarId"}, + }, + func(rt *shortcut.RuntimeContext) error { + fields, add, remove, err := calendarUpdateParams(rt) + if err != nil { + return err + } + target := calendarEventTarget(rt) + preflight, err := rt.CallMCPData("calendar", "get_calendar_detail", target) + if err != nil { + return err + } + if _, err := requireCalendarEvent(preflight, "calendar/get_calendar_detail", rt.Str("event")); err != nil { + return err + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "calendar/update", "eventId": rt.Str("event"), "fields": fields, "addAttendees": add, "removeAttendees": remove}) + } + completed := make([]string, 0, 3) + if len(fields) > 0 { + params := calendarEventTarget(rt) + for key, value := range fields { + params[key] = value + } + written, callErr := rt.CallMCPWriteDataStrict("calendar", "update_calendar_event", params) + if callErr != nil { + return calendarStageError("update_event", completed, callErr) + } + if _, callErr = requireCalendarWriteResponse(written, "calendar/update_calendar_event"); callErr != nil { + return calendarStageError("update_event", completed, callErr) + } + completed = append(completed, "update_event") + } + if len(remove) > 0 { + params := calendarEventTarget(rt) + params["attendeesToRemove"] = remove + written, callErr := rt.CallMCPWriteDataStrict("calendar", "remove_calendar_participant", params) + if callErr != nil { + return calendarStageError("remove_attendees", completed, callErr) + } + if _, callErr = requireCalendarWriteResponse(written, "calendar/remove_calendar_participant"); callErr != nil { + return calendarStageError("remove_attendees", completed, callErr) + } + completed = append(completed, "remove_attendees") + } + if len(add) > 0 { + params := calendarEventTarget(rt) + params["attendeesToAdd"] = add + written, callErr := rt.CallMCPWriteDataStrict("calendar", "add_calendar_participant", params) + if callErr != nil { + return calendarStageError("add_attendees", completed, callErr) + } + if _, callErr = requireCalendarWriteResponse(written, "calendar/add_calendar_participant"); callErr != nil { + return calendarStageError("add_attendees", completed, callErr) + } + completed = append(completed, "add_attendees") + } + readback, err := rt.CallMCPData("calendar", "get_calendar_detail", target) + if err != nil { + return calendarStageError("verify_event", completed, err) + } + event, err := requireCalendarEvent(readback, "calendar/get_calendar_detail", rt.Str("event")) + if err != nil { + return calendarStageError("verify_event", completed, err) + } + if err := verifyCalendarEvent(event, rt.Str("event"), fields); err != nil { + return calendarStageError("verify_event", completed, err) + } + if len(add)+len(remove) > 0 { + participants, callErr := rt.CallMCPData("calendar", "get_calendar_participants", target) + if callErr != nil { + return calendarStageError("verify_attendees", completed, callErr) + } + rows, callErr := attendeeListProject(participants) + if callErr != nil { + return calendarStageError("verify_attendees", completed, callErr) + } + if callErr := verifyCalendarAttendees(rows, add, remove); callErr != nil { + return calendarStageError("verify_attendees", completed, callErr) + } + } + return rt.Output(map[string]any{"success": true, "eventId": rt.Str("event"), "completedSteps": completed, "verified": true, "event": normalizeCalendarEvent(event)}) + }, +) + +// RSVP maps familiar verbs onto the DingTalk responseStatus values. It always +// reads the event after the write; responseStatus is verified when the backend +// exposes it, otherwise success is explicitly labelled terminal-response-only. +var RSVP = calendarWriteShortcut( + "+rsvp", "响应日程邀请并读取终态", + "作为当前参会人接受、拒绝或暂定一个日程邀请；写响应必须非空且非失败，并在写后读取日程，绝不把空 ack 当成功。", + "dws calendar +rsvp --event --status accept --format json", + []shortcut.Flag{ + {Name: "event", Type: shortcut.FlagString, Required: true, Desc: "日程 eventId"}, + {Name: "status", Type: shortcut.FlagString, Required: true, Desc: "响应动作", Enum: []string{"accept", "decline", "tentative", "needs-action"}}, + {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID（默认 primary）"}, + }, + []contract.ParamDecl{{Name: "event", Property: "eventId"}, {Name: "status", Property: "responseStatus"}, {Name: "calendar-id", Property: "calendarId"}}, + func(rt *shortcut.RuntimeContext) error { + status := map[string]string{"accept": "accepted", "decline": "declined", "tentative": "tentative", "needs-action": "needsAction"}[rt.Str("status")] + target := calendarEventTarget(rt) + preflight, err := rt.CallMCPData("calendar", "get_calendar_detail", target) + if err != nil { + return err + } + if _, err := requireCalendarEvent(preflight, "calendar/get_calendar_detail", rt.Str("event")); err != nil { + return err + } + params := calendarEventTarget(rt) + params["responseStatus"] = status + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "calendar/respond", "arguments": params}) + } + written, err := rt.CallMCPWriteDataStrict("calendar", "respond", params) + if err != nil { + return err + } + written, err = requireCalendarWriteResponse(written, "calendar/respond") + if err != nil { + return err + } + readback, err := rt.CallMCPData("calendar", "get_calendar_detail", target) + if err != nil { + return err + } + event, err := requireCalendarEvent(readback, "calendar/get_calendar_detail", rt.Str("event")) + if err != nil { + return err + } + readStatus := firstCalendarString(event, "responseStatus", "response_status") + verified := readStatus == status + if readStatus != "" && !verified { + return calendarResponseError("calendar/respond", "readback_status_mismatch", "响应日程后读回的 responseStatus 与请求不一致") + } + if !verified { + writeStatus := nestedCalendarString(written, "responseStatus", "response_status", "status") + if writeStatus != "" && writeStatus != status { + return calendarResponseError("calendar/respond", "terminal_status_mismatch", "响应接口返回的状态与请求不一致") + } + if writeStatus == status { + verified = true + } + } + return rt.Output(map[string]any{"success": true, "eventId": rt.Str("event"), "responseStatus": status, "verified": verified, "verification": map[string]any{"eventReadback": true, "statusReadback": readStatus != ""}}) + }, +) + +// EventSearch is an explicitly page-local client-side search. It returns the +// upstream cursor and complete=false whenever another page may exist. +var EventSearch = calendarReadShortcut( + "+search-event", "在一个日程页内严格搜索事件", + "DingTalk 没有专用日程全文搜索接口；该命令在 list_calendar_events 当前页按标题、描述和地点过滤，并原样保留 nextCursor/hasMore，绝不把单页零命中说成全局未找到。", + "events", + []shortcut.Flag{ + {Name: "query", Type: shortcut.FlagString, Required: true, Desc: "标题、描述或地点关键词"}, + {Name: "start", Type: shortcut.FlagString, Desc: "开始时间，默认今天 00:00"}, + {Name: "end", Type: shortcut.FlagString, Desc: "结束时间，默认今天 23:59:59"}, + {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID（默认 primary）"}, + {Name: "cursor", Type: shortcut.FlagString, Desc: "上一页 nextCursor"}, + {Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "单页条数 1-100"}, + }, + []contract.ParamDecl{{Name: "start", Property: "startTime"}, {Name: "end", Property: "endTime"}, {Name: "calendar-id", Property: "calendarId"}, {Name: "cursor", Property: "cursor"}, {Name: "limit", Property: "limit"}}, + func(rt *shortcut.RuntimeContext) error { + params, err := calendarListParams(rt) + if err != nil { + return err + } + data, err := rt.CallMCPData("calendar", "list_calendar_events", params) + if err != nil { + return err + } + items, container, err := requireCalendarCollection(data, "calendar/list_calendar_events", "events") + if err != nil { + return err + } + query := strings.ToLower(rt.Str("query")) + matched := make([]any, 0) + for _, item := range items { + object := item.(map[string]any) + text := strings.ToLower(strings.Join([]string{ + firstCalendarString(object, "summary", "title", "name"), + firstCalendarString(object, "description", "desc"), + firstCalendarString(object, "location", "locationName", "location_name"), + }, "\n")) + if strings.Contains(text, query) { + matched = append(matched, item) + } + } + events, err := projectCalendarRows(matched, "calendar/list_calendar_events", map[string][]string{ + "eventId": {"eventId", "event_id", "id"}, "summary": {"summary", "title", "name"}, + "start": {"start", "startTime", "startDateTime"}, "end": {"end", "endTime", "endDateTime"}, + "status": {"status", "eventStatus"}, "location": {"location", "locationName"}, + }, "eventId") + if err != nil { + return err + } + page, err := calendarPagination(container, "calendar/list_calendar_events") + if err != nil { + return err + } + if !page.Known { + return calendarResponseError("calendar/list_calendar_events", "missing_pagination", "日程搜索响应缺少 hasMore/nextCursor 分页证据，不能把当前页当作完整搜索结果") + } + out := map[string]any{"count": len(events), "events": events, "query": rt.Str("query")} + return outputCalendarPage(rt, out, page) + }, +) + +// Suggestion exposes the direct-user-id suggested-time route. Name resolution +// remains the distinct +suggest-time shortcut. +var Suggestion = calendarReadShortcut( + "+suggestion", "按 userId 严格推荐共同空闲时间", + "已经知道参与者 userId 时直接查询共同可用时间；显式 recommendEventTimes:[] 才表示没有建议，缺字段或坏元素会失败。按姓名解析请用 +suggest-time。", + "suggestions", + []shortcut.Flag{ + {Name: "users", Type: shortcut.FlagStringSlice, Required: true, Desc: "参与者 userId"}, + {Name: "duration", Type: shortcut.FlagInt, Default: "30", Desc: "会议时长分钟数 1-1440"}, + {Name: "start", Type: shortcut.FlagString, Desc: "推荐范围开始；与 --end 同时传"}, + {Name: "end", Type: shortcut.FlagString, Desc: "推荐范围结束；与 --start 同时传"}, + {Name: "timezone", Type: shortcut.FlagString, Desc: "IANA 时区"}, + }, + []contract.ParamDecl{{Name: "users", Property: "attendeeUserIds"}, {Name: "duration", Property: "durationMinutes"}, {Name: "start", Property: "start"}, {Name: "end", Property: "end"}, {Name: "timezone", Property: "timeZone"}}, + func(rt *shortcut.RuntimeContext) error { + users := calendarStringList(rt.StrSlice("users")) + if len(users) == 0 { + return apperrors.NewValidation("--users 至少包含一个非空 userId") + } + if rt.Int("duration") < 1 || rt.Int("duration") > 1440 { + return apperrors.NewValidation("--duration 必须在 1-1440 分钟之间") + } + if rt.Changed("start") != rt.Changed("end") { + return apperrors.NewValidation("--start 与 --end 必须同时传入") + } + params := map[string]any{"attendeeUserIds": users, "durationMinutes": fmt.Sprint(rt.Int("duration"))} + if rt.Changed("start") { + if _, _, err := validateCalendarRange("start", rt.Str("start"), "end", rt.Str("end")); err != nil { + return err + } + params["start"] = rt.Str("start") + params["end"] = rt.Str("end") + } + if rt.Changed("timezone") { + params["timeZone"] = rt.Str("timezone") + } + data, err := rt.CallMCPData("calendar", "list_suggested_event_times", params) + if err != nil { + return err + } + items, _, err := requireCalendarCollection(data, "calendar/list_suggested_event_times", "recommendEventTimes", "suggestions") + if err != nil { + return err + } + suggestions, err := projectCalendarRows(items, "calendar/list_suggested_event_times", map[string][]string{ + "start": {"startTime", "start", "startDateTime"}, "end": {"endTime", "end", "endDateTime"}, + "conflicts": {"timeConflictAttendees", "conflicts"}, + }, "start") + if err != nil { + return err + } + for index, suggestion := range suggestions { + if calendarEmptyValue(suggestion["end"]) { + return calendarResponseError("calendar/list_suggested_event_times", "malformed_collection_item", fmt.Sprintf("建议时段第 %d 项缺少结束时间", index)) + } + } + return rt.Output(map[string]any{"count": len(suggestions), "suggestions": suggestions, "complete": true}) + }, +) + +func calendarEventTarget(rt *shortcut.RuntimeContext) map[string]any { + params := map[string]any{"eventId": rt.Str("event")} + if calendarID := rt.Str("calendar-id"); calendarID != "" { + params["calendarId"] = calendarID + } + return params +} + +func requireCalendarEvent(data map[string]any, operation, expectedID string) (map[string]any, error) { + event, err := requireCalendarObject(data, operation) + if err != nil { + return nil, err + } + eventID := calendarEventID(event) + if eventID == "" { + return nil, calendarResponseError(operation, "missing_event_id", "日程对象缺少 id/eventId") + } + if expectedID != "" && eventID != expectedID { + return nil, calendarResponseError(operation, "event_id_mismatch", "日程对象 id 与请求 eventId 不一致") + } + return event, nil +} + +func normalizeCalendarEvent(event map[string]any) map[string]any { + out := make(map[string]any, len(event)+1) + for key, value := range event { + out[key] = value + } + out["eventId"] = calendarEventID(event) + return out +} + +func calendarCreateParams(rt *shortcut.RuntimeContext) (map[string]any, map[string]any, error) { + if len([]rune(rt.Str("title"))) > 2048 { + return nil, nil, apperrors.NewValidation("--title 不能超过 2048 个字符") + } + if len([]rune(rt.Str("desc"))) > 5000 { + return nil, nil, apperrors.NewValidation("--desc 不能超过 5000 个字符") + } + if _, _, err := validateCalendarRange("start", rt.Str("start"), "end", rt.Str("end")); err != nil { + return nil, nil, err + } + attendees := calendarStringList(rt.StrSlice("attendees")) + if len(attendees) > 500 { + return nil, nil, apperrors.NewValidation("--attendees 最多 500 个 userId") + } + params := map[string]any{"summary": rt.Str("title"), "startDateTime": rt.Str("start"), "endDateTime": rt.Str("end")} + verify := map[string]any{"summary": rt.Str("title"), "startDateTime": rt.Str("start"), "endDateTime": rt.Str("end")} + for _, pair := range [][2]string{{"desc", "description"}, {"timezone", "timeZone"}, {"location", "location"}, {"free-busy", "freeBusy"}, {"calendar-id", "calendarId"}} { + if rt.Changed(pair[0]) { + params[pair[1]] = rt.Str(pair[0]) + if pair[1] != "calendarId" { + verify[pair[1]] = rt.Str(pair[0]) + } + } + } + if len(attendees) > 0 { + params["attendees"] = attendees + } + if rooms := calendarStringList(rt.StrSlice("rooms")); len(rooms) > 0 { + params["roomIds"] = rooms + } + return params, verify, nil +} + +func calendarUpdateParams(rt *shortcut.RuntimeContext) (map[string]any, []string, []string, error) { + if rt.Changed("start") != rt.Changed("end") { + return nil, nil, nil, apperrors.NewValidation("--start 与 --end 必须同时传入") + } + if rt.Changed("start") { + if _, _, err := validateCalendarRange("start", rt.Str("start"), "end", rt.Str("end")); err != nil { + return nil, nil, nil, err + } + } + fields := map[string]any{} + for _, pair := range [][2]string{{"title", "summary"}, {"desc", "description"}, {"start", "startDateTime"}, {"end", "endDateTime"}, {"timezone", "timeZone"}, {"location", "location"}, {"free-busy", "freeBusy"}} { + if rt.Changed(pair[0]) { + fields[pair[1]] = rt.Str(pair[0]) + } + } + add := calendarStringList(rt.StrSlice("add-attendees")) + remove := calendarStringList(rt.StrSlice("remove-attendees")) + if len(fields)+len(add)+len(remove) == 0 { + return nil, nil, nil, apperrors.NewValidation("至少提供一个要更新的字段或参会人变更") + } + removeSet := map[string]bool{} + for _, id := range remove { + removeSet[id] = true + } + for _, id := range add { + if removeSet[id] { + return nil, nil, nil, apperrors.NewValidation("同一 userId 不能同时出现在 --add-attendees 与 --remove-attendees") + } + } + return fields, add, remove, nil +} + +func verifyCalendarAttendees(rows []map[string]any, added, removed []string) error { + present := map[string]bool{} + for _, row := range rows { + if id := strings.TrimSpace(fmt.Sprint(row["userId"])); id != "" { + present[id] = true + } + } + for _, id := range added { + if !present[id] { + return calendarResponseError("calendar/get_calendar_participants", "readback_attendee_missing", "写后读回未找到新增参会人") + } + } + for _, id := range removed { + if present[id] { + return calendarResponseError("calendar/get_calendar_participants", "readback_attendee_present", "写后读回仍包含已移除参会人") + } + } + return nil +} + +func calendarStageError(stage string, completed []string, cause error) error { + message := fmt.Sprintf("日程更新在步骤 %s 失败", stage) + if len(completed) > 0 { + message += "；此前已完成且不会自动回滚的步骤: " + strings.Join(completed, ",") + } + if cause != nil { + message += ": " + cause.Error() + } + return calendarResponseError("calendar/update", "partial_or_unknown_effect", message) +} + +func calendarListParams(rt *shortcut.RuntimeContext) (map[string]any, error) { + if rt.Int("limit") < 1 || rt.Int("limit") > 100 { + return nil, apperrors.NewValidation("--limit 必须在 1-100 之间") + } + now := time.Now() + start := rt.Str("start") + end := rt.Str("end") + if start == "" { + start = time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()).Format(time.RFC3339) + } + if end == "" { + end = time.Date(now.Year(), now.Month(), now.Day(), 23, 59, 59, 0, now.Location()).Format(time.RFC3339) + } + startTime, endTime, err := validateCalendarRange("start", start, "end", end) + if err != nil { + return nil, err + } + params := map[string]any{"startTime": startTime.UnixMilli(), "endTime": endTime.UnixMilli(), "limit": rt.Int("limit")} + if value := rt.Str("calendar-id"); value != "" { + params["calendarId"] = value + } + if value := rt.Str("cursor"); value != "" { + params["cursor"] = value + } + return params, nil +} diff --git a/internal/shortcut/calendar/room_groups_projection_test.go b/internal/shortcut/calendar/room_groups_projection_test.go index 19a94244..85c3ffd7 100644 --- a/internal/shortcut/calendar/room_groups_projection_test.go +++ b/internal/shortcut/calendar/room_groups_projection_test.go @@ -22,7 +22,7 @@ import ( // list_meeting_room_groups nests the groups under result.groupList; the resolver // must probe "groupList" or +room-groups silently returns empty despite the // backend returning meeting-room groups. -func TestRoomGroupsProjectGroupListShape(t *testing.T) { +func TestCrossPlatformCoverageRoomGroupsProjectGroupListShape(t *testing.T) { const raw = `{"result":{"groupList":[ {"groupId":"g1","groupName":"north rooms"}, {"groupId":"g2","groupName":"south rooms"} @@ -31,7 +31,11 @@ func TestRoomGroupsProjectGroupListShape(t *testing.T) { if err := json.Unmarshal([]byte(raw), &data); err != nil { t.Fatalf("unmarshal fixture: %v", err) } - if got := roomGroupsProject(data); len(got) != 2 { + got, err := roomGroupsProject(data) + if err != nil { + t.Fatalf("projection: %v", err) + } + if len(got) != 2 { t.Fatalf("lower/upper mismatch: result.groupList has 2 entries, projection returned %d", len(got)) } } diff --git a/internal/shortcut/public_catalog_generated.go b/internal/shortcut/public_catalog_generated.go index 4ec9e1b7..6bb77e11 100644 --- a/internal/shortcut/public_catalog_generated.go +++ b/internal/shortcut/public_catalog_generated.go @@ -124,18 +124,25 @@ func generatedPublicShortcutCatalog() map[string]struct{} { "calendar\u0000+book-search": {}, "calendar\u0000+cancel-event": {}, "calendar\u0000+conflicts": {}, + "calendar\u0000+create": {}, "calendar\u0000+free": {}, "calendar\u0000+free-slots": {}, "calendar\u0000+freebusy": {}, + "calendar\u0000+get": {}, "calendar\u0000+invite": {}, "calendar\u0000+my-free": {}, "calendar\u0000+next-event": {}, "calendar\u0000+reschedule": {}, + "calendar\u0000+room-find": {}, "calendar\u0000+room-groups": {}, "calendar\u0000+room-search": {}, + "calendar\u0000+rsvp": {}, + "calendar\u0000+search-event": {}, "calendar\u0000+suggest-time": {}, + "calendar\u0000+suggestion": {}, "calendar\u0000+today": {}, "calendar\u0000+tomorrow": {}, + "calendar\u0000+update": {}, "calendar\u0000+week": {}, "chat\u0000+at-me": {}, "chat\u0000+bot-find": {}, @@ -395,15 +402,25 @@ func generatedPublicShortcutCatalog() map[string]struct{} { "sheet\u0000+read": {}, "todo\u0000+assign": {}, "todo\u0000+assign-multi": {}, + "todo\u0000+comment": {}, + "todo\u0000+complete": {}, + "todo\u0000+create": {}, "todo\u0000+created-todos": {}, + "todo\u0000+due-today": {}, "todo\u0000+get": {}, "todo\u0000+get-my-tasks": {}, + "todo\u0000+get-related-tasks": {}, "todo\u0000+list-attachment": {}, "todo\u0000+list-comment": {}, "todo\u0000+list-sub": {}, "todo\u0000+overdue": {}, + "todo\u0000+related-tasks": {}, "todo\u0000+remind": {}, + "todo\u0000+reminder": {}, + "todo\u0000+reopen": {}, + "todo\u0000+search": {}, "todo\u0000+todo-done": {}, + "todo\u0000+update": {}, "wiki\u0000+delete-space": {}, "wiki\u0000+feed-list": {}, "wiki\u0000+member-add": {}, diff --git a/internal/shortcut/semantic_catalog.go b/internal/shortcut/semantic_catalog.go index 6c04f845..fbb5b312 100644 --- a/internal/shortcut/semantic_catalog.go +++ b/internal/shortcut/semantic_catalog.go @@ -28,6 +28,12 @@ var driveSemanticCatalogJSON []byte //go:embed semantic_catalog_wiki.json var wikiSemanticCatalogJSON []byte +//go:embed semantic_catalog_calendar.json +var calendarSemanticCatalogJSON []byte + +//go:embed semantic_catalog_todo.json +var todoSemanticCatalogJSON []byte + type semanticCatalogFile struct { Version int `json:"version"` Service string `json:"service"` @@ -52,6 +58,8 @@ var reviewedSemanticCatalog = mustLoadSemanticCatalogs( minutesSemanticCatalogJSON, driveSemanticCatalogJSON, wikiSemanticCatalogJSON, + calendarSemanticCatalogJSON, + todoSemanticCatalogJSON, ) func mustLoadSemanticCatalogs(sources ...[]byte) map[string]semanticCatalogRecord { diff --git a/internal/shortcut/semantic_catalog_calendar.json b/internal/shortcut/semantic_catalog_calendar.json new file mode 100644 index 00000000..dc78072b --- /dev/null +++ b/internal/shortcut/semantic_catalog_calendar.json @@ -0,0 +1,39 @@ +{ + "version": 1, + "service": "calendar", + "default_availability": "available", + "shortcuts": { + "+agenda": {"disposition":"semantic_adapter","semantic_delta":"严格验证 result.events 与分页证据，稳定投影 id 为 eventId；显式空数组才是空日程。","risk":"read","public":true,"reviewed":true}, + "+get": {"disposition":"schema_leaf","semantic_delta":"严格读取日程对象并把稳定 id 规范化为 eventId，拒绝空响应和对象漂移。","risk":"read","public":true,"reviewed":true}, + "+create": {"disposition":"primary_smart","semantic_delta":"创建响应必须给出 eventId/id，且标题和起止时间通过详情读回后才成功。","risk":"write","public":true,"reviewed":true}, + "+update": {"disposition":"primary_smart","semantic_delta":"组合字段与参会人分阶段更新，明确非事务步骤并以详情和参会人列表读回验证。","risk":"write","public":true,"reviewed":true}, + "+rsvp": {"disposition":"semantic_adapter","semantic_delta":"把直白 RSVP 动作映射为 responseStatus，拒绝空 ack，并在写后读取日程终态。","risk":"write","public":true,"reviewed":true}, + "+search-event": {"disposition":"semantic_adapter","semantic_delta":"在服务端日程当前页按标题、描述和地点过滤，同时保留 hasMore/nextCursor，绝不把单页零命中当全局未找到。","risk":"read","public":true,"reviewed":true}, + "+suggestion": {"disposition":"schema_leaf","semantic_delta":"直接按 userId 查询建议时段，严格区分显式空 recommendEventTimes 与缺失或畸形响应。","risk":"read","public":true,"reviewed":true}, + + "+attendee-list": {"disposition":"semantic_adapter","semantic_delta":"严格验证参会人数组并投影显示名、响应状态和 self；真实后端不返回稳定参会人 userId，因此不伪造身份字段。","risk":"read","public":true,"reviewed":true}, + "+room-search": {"disposition":"semantic_adapter","semantic_delta":"按名称查询会议室但不声称检查时间可用性；缺失会议室数组直接失败。","risk":"read","public":true,"reviewed":true}, + "+room-find": {"disposition":"semantic_adapter","semantic_delta":"按单个未来时间段严格查询可用会议室，公开真实 page/pageSize/hasMore 证据和后端筛选边界。","risk":"read","public":true,"reviewed":true}, + "+room-groups": {"disposition":"semantic_adapter","semantic_delta":"严格读取 result.groupList，避免会议室分组被响应 wrapper 漂移静默清空。","risk":"read","public":true,"reviewed":true}, + "+freebusy": {"disposition":"semantic_adapter","semantic_delta":"统一按用户或会议室 ID 查询指定范围闲忙，并声明至少一类目标约束。","risk":"read","public":true,"reviewed":true}, + "+book-list": {"disposition":"semantic_adapter","semantic_delta":"严格验证日历本数组并稳定投影 calendarId，缺失数组不再误报为空。","risk":"read","public":true,"reviewed":true}, + "+book-search": {"disposition":"semantic_adapter","semantic_delta":"按日历本名称搜索并严格区分零命中与协议错误。","risk":"read","public":true,"reviewed":true}, + + "+book": {"disposition":"primary_smart","semantic_delta":"按参会人姓名解析后创建日程，并在多步骤路径提供失败回滚与详情读回。","risk":"write","public":true,"reviewed":true}, + "+cancel-event": {"disposition":"primary_smart","semantic_delta":"删除前读取并展示目标，经高风险确认后取消指定日程。","risk":"high-risk-write","public":true,"reviewed":true}, + "+conflicts": {"disposition":"primary_smart","semantic_delta":"在指定范围分析重叠日程并输出冲突对，避免人工逐项比对。","risk":"read","public":true,"reviewed":true}, + "+free": {"disposition":"primary_smart","semantic_delta":"按姓名解析参与者后查询闲忙，省去手工 userId 解析。","risk":"read","public":true,"reviewed":true}, + "+free-slots": {"disposition":"primary_smart","semantic_delta":"从已有日程计算工作时段内空档，并显式输出满足时长的候选区间。","risk":"read","public":true,"reviewed":true}, + "+invite": {"disposition":"primary_smart","semantic_delta":"按姓名唯一解析用户后邀请到已有日程。","risk":"write","public":true,"reviewed":true}, + "+my-free": {"disposition":"primary_smart","semantic_delta":"以当前用户身份查询一个时间段是否空闲。","risk":"read","public":true,"reviewed":true}, + "+next-event": {"disposition":"primary_smart","semantic_delta":"在未来时间窗内定位最近的下一场日程。","risk":"read","public":true,"reviewed":true}, + "+reschedule": {"disposition":"primary_smart","semantic_delta":"修改前读取目标日程，再更新完整起止时间。","risk":"write","public":true,"reviewed":true}, + "+suggest-time": {"disposition":"primary_smart","semantic_delta":"按姓名逐个唯一解析参与者，再查询大家共同可用的建议时间。","risk":"read","public":true,"reviewed":true}, + "+today": {"disposition":"primary_smart","semantic_delta":"查询并整理今天的日程视图。","risk":"read","public":true,"reviewed":true}, + "+tomorrow": {"disposition":"primary_smart","semantic_delta":"查询并整理明天的日程视图。","risk":"read","public":true,"reviewed":true}, + "+week": {"disposition":"primary_smart","semantic_delta":"查询并按日期整理本周日程。","risk":"read","public":true,"reviewed":true}, + + "+find-room": {"disposition":"alias_internal","semantic_delta":"兼容旧的双时间参数会议室查询入口；新调用统一使用 +room-find。","risk":"read","availability":"deprecated","primary":"+room-find","public":false,"reviewed":true}, + "+respond-event": {"disposition":"alias_internal","semantic_delta":"兼容旧的 accept/decline/tentative 响应入口；新调用统一使用 +rsvp。","risk":"write","availability":"deprecated","primary":"+rsvp","public":false,"reviewed":true} + } +} diff --git a/internal/shortcut/semantic_catalog_todo.json b/internal/shortcut/semantic_catalog_todo.json new file mode 100644 index 00000000..64c0ed7d --- /dev/null +++ b/internal/shortcut/semantic_catalog_todo.json @@ -0,0 +1,29 @@ +{ + "version": 1, + "service": "todo", + "default_availability": "available", + "shortcuts": { + "+get-my-tasks": {"disposition":"semantic_adapter","semantic_delta":"严格识别 todoCards/hasMore/page/size；显式空数组才是空结果，并支持有界全量分页。","risk":"read","public":true,"reviewed":true}, + "+list-sub": {"disposition":"semantic_adapter","semantic_delta":"严格校验子待办容器、对象元素和稳定 taskId。","risk":"read","public":true,"reviewed":true}, + "+get": {"disposition":"semantic_adapter","semantic_delta":"严格绑定 todoDetailModel.taskId，缺失或错绑均失败。","risk":"read","public":true,"reviewed":true}, + "+list-attachment": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空附件与缺失容器，并要求每项稳定附件 ID。","risk":"read","public":true,"reviewed":true}, + "+list-comment": {"disposition":"semantic_adapter","semantic_delta":"严格区分显式空评论与缺失容器，并要求每项稳定 commentId。","risk":"read","public":true,"reviewed":true}, + "+create": {"disposition":"primary_smart","semantic_delta":"创建后要求稳定 taskId，并读取 todoDetailModel 验证标题。","risk":"write","public":true,"reviewed":true}, + "+update": {"disposition":"primary_smart","semantic_delta":"更新指定字段后读取详情逐字段核验。","risk":"write","public":true,"reviewed":true}, + "+complete": {"disposition":"primary_smart","semantic_delta":"先读当前状态避免重复写，必要时完成后再读回核验。","risk":"write","public":true,"reviewed":true}, + "+reopen": {"disposition":"primary_smart","semantic_delta":"先读当前状态避免重复写，必要时重开后再读回核验。","risk":"write","public":true,"reviewed":true}, + "+search": {"disposition":"primary_smart","semantic_delta":"遍历全部 hasMore 分页并按标题匹配；达到页上限仍未耗尽时失败。","risk":"read","public":true,"reviewed":true}, + "+comment": {"disposition":"primary_smart","semantic_delta":"新增评论必须取得稳定 commentId，并分页读回验证内容。","risk":"write","public":true,"reviewed":true}, + "+upload-attachment": {"disposition":"primary_smart","semantic_delta":"路由到现有原子上传事务；Shortcut 层不复制凭证和带头 OSS PUT 实现。","risk":"write","availability":"unavailable","public":false,"reviewed":true}, + "+reminder": {"disposition":"semantic_adapter","semantic_delta":"严格验证提醒参数和 success=true 终端回执；上游不能读回规则，固定 verified=false。","risk":"write","public":true,"reviewed":true}, + "+get-related-tasks": {"disposition":"primary_smart","semantic_delta":"遍历与我相关三种角色的全部分页并按 taskId 去重。","risk":"read","public":true,"reviewed":true}, + "+related-tasks": {"disposition":"alias_internal","semantic_delta":"保留旧命令拼写，新的 Agent 路由统一使用 +get-related-tasks。","risk":"read","primary":"+get-related-tasks","public":true,"reviewed":true}, + "+due-today": {"disposition":"primary_smart","semantic_delta":"按本地日历日构造服务端截止窗口并遍历全部分页。","risk":"read","public":true,"reviewed":true}, + "+assign": {"disposition":"primary_smart","semantic_delta":"保留历史按姓名解析后创建并指派的新任务语义，避免同名破坏性变更。","risk":"write","public":true,"reviewed":true}, + "+assign-multi": {"disposition":"primary_smart","semantic_delta":"全部姓名唯一解析后才创建一次，并以单一统一结果输出稳定 taskId。","risk":"write","public":true,"reviewed":true}, + "+created-todos": {"disposition":"primary_smart","semantic_delta":"遍历创建者角色的全部分页后投影。","risk":"read","public":true,"reviewed":true}, + "+overdue": {"disposition":"primary_smart","semantic_delta":"遍历执行者角色的全部分页并按当前时间筛选逾期项。","risk":"read","public":true,"reviewed":true}, + "+remind": {"disposition":"primary_smart","semantic_delta":"解析当前用户后创建给自己的待办；该命令不是独立提醒规则。","risk":"write","public":true,"reviewed":true}, + "+todo-done": {"disposition":"primary_smart","semantic_delta":"跨全部分页按标题唯一定位后完成任务。","risk":"write","public":true,"reviewed":true} + } +} diff --git a/internal/shortcut/smart/assign.go b/internal/shortcut/smart/assign.go index d64e6cf0..3bbf7f5d 100644 --- a/internal/shortcut/smart/assign.go +++ b/internal/shortcut/smart/assign.go @@ -14,9 +14,13 @@ package smart import ( + "encoding/json" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + todoshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/todo" ) // Assign: create a todo AND assign it to a person by NAME, in one command. @@ -27,10 +31,11 @@ import ( // // dws todo +assign --to 张三 --task "整理周报" var Assign = shortcut.Shortcut{ - Service: "todo", - Command: "+assign", - Product: "todo", - Description: "按姓名给某人创建并指派一条待办（自动解析 userId）", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+assign", + Product: "todo", + Description: "按姓名给某人创建并指派一条待办（自动解析 userId）", Intent: "当你想把一件事指派给某位同事、但只知道对方姓名不想先查 userId 时使用；" + "内部先按姓名解析出唯一 userId，再创建待办并把 TA 设为执行人。会真实创建待办。", Risk: shortcut.RiskWrite, @@ -47,6 +52,7 @@ var Assign = shortcut.Shortcut{ PrimaryCLIPath: "todo +assign", }, Description: "按姓名给某人创建并指派一条待办（自动解析 userId）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"已验证的单人指派待办","properties":{"taskId":{"type":"string","description":"新待办稳定 taskId"},"subject":{"type":"string","description":"待办标题"},"executorId":{"type":"string","description":"解析出的执行人 userId"},"verified":{"type":"boolean","description":"是否完成详情读回核验"}},"required":["taskId","subject","executorId","verified"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -88,9 +94,21 @@ var Assign = shortcut.Shortcut{ } vo["dueTime"] = ms } - return rt.CallMCP("create_personal_todo", map[string]any{ + params := map[string]any{ "PersonalTodoCreateVO": vo, - }) + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "subject": rt.Str("task")}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "create_personal_todo", params) + if err != nil { + return err + } + taskID, _, err := todoshortcut.VerifyCreatedTodo(rt, data, "todo/create_personal_todo", rt.Str("task")) + if err != nil { + return err + } + return rt.Output(map[string]any{"taskId": taskID, "subject": rt.Str("task"), "executorId": user.userID, "verified": true}) }, } diff --git a/internal/shortcut/smart/assign_multi.go b/internal/shortcut/smart/assign_multi.go index 50d7aa5f..aea4e9ac 100644 --- a/internal/shortcut/smart/assign_multi.go +++ b/internal/shortcut/smart/assign_multi.go @@ -14,6 +14,7 @@ package smart import ( + "encoding/json" "fmt" "strings" @@ -21,7 +22,9 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + todoshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/todo" ) // AssignMulti: create ONE personal todo and assign it to SEVERAL people at once, @@ -41,10 +44,11 @@ import ( // // dws todo +assign-multi --to "张三,李四,王五" --task "周五前提交排期" var AssignMulti = shortcut.Shortcut{ - Service: "todo", - Command: "+assign-multi", - Product: "todo", - Description: "把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId）", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+assign-multi", + Product: "todo", + Description: "把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId）", Intent: "当你想把同一条待办同时指派给好几个同事、但手上只有他们的姓名而不是 userId 时使用；" + "内部会把 --to 里的每个姓名逐个解析成唯一 userId，只要有任何一个姓名查不到或者重名有歧义，" + "就把这些问题一次性汇总报错、并且完全不创建待办（不会建出只指派了一半人的残缺待办）。" + @@ -63,6 +67,7 @@ var AssignMulti = shortcut.Shortcut{ PrimaryCLIPath: "todo +assign-multi", }, Description: "把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"已验证的多人指派待办","properties":{"taskId":{"type":"string","description":"新待办稳定 taskId"},"subject":{"type":"string","description":"待办标题"},"executors":{"type":"array","description":"已解析执行人摘要","items":{"type":"string"}},"count":{"type":"integer","description":"执行人数"},"verified":{"type":"boolean","description":"是否完成详情读回核验"}},"required":["taskId","subject","executors","count","verified"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -126,19 +131,30 @@ var AssignMulti = shortcut.Shortcut{ // Create the todo once, assigning all resolved executors. Params mirror the // todo helper's `task create` call site verbatim. - if err := rt.CallMCP("create_personal_todo", map[string]any{ + params := map[string]any{ "PersonalTodoCreateVO": map[string]any{ "subject": task, "executorIds": executorIDs, }, - }); err != nil { + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "subject": task, "count": len(executorIDs)}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "create_personal_todo", params) + if err != nil { + return err + } + taskID, _, err := todoshortcut.VerifyCreatedTodo(rt, data, "todo/create_personal_todo", task) + if err != nil { return err } return rt.Output(map[string]any{ + "taskId": taskID, "subject": task, "executors": resolved, "count": len(executorIDs), + "verified": true, }) }, } diff --git a/internal/shortcut/smart/book.go b/internal/shortcut/smart/book.go index ca27df7d..04cc7d99 100644 --- a/internal/shortcut/smart/book.go +++ b/internal/shortcut/smart/book.go @@ -85,112 +85,130 @@ var Book = shortcut.Shortcut{ `dws calendar +book --title "Q1 复盘会" --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --with 张三,李四`, }, Execute: func(rt *shortcut.RuntimeContext) error { + start := rt.Str("start") + end := rt.Str("end") + if err := calendarSmartValidateRange(start, end); err != nil { + return err + } // create_calendar_event params copied verbatim from the helper's create // call site: summary + startDateTime/endDateTime (ISO strings, not millis). createArgs := map[string]any{ "summary": rt.Str("title"), - "startDateTime": rt.Str("start"), - "endDateTime": rt.Str("end"), - } - - // Fast path: no participants → create and print in one step. - if !rt.Changed("with") || strings.TrimSpace(rt.Str("with")) == "" { - return rt.CallMCP("create_calendar_event", createArgs) + "startDateTime": start, + "endDateTime": end, } // Step 1 — resolve every participant name to a unique userId BEFORE // creating the event, so an unknown/ambiguous name fails cheaply without // leaving a dangling event behind. var userIDs []string - for _, name := range strings.Split(rt.Str("with"), ",") { - name = strings.TrimSpace(name) - if name == "" { - continue + var userNames []string + withPeople := rt.Changed("with") && strings.TrimSpace(rt.Str("with")) != "" + if withPeople { + for _, name := range strings.Split(rt.Str("with"), ",") { + name = strings.TrimSpace(name) + if name == "" { + continue + } + user, err := resolveUser(rt, name) + if err != nil { + return err + } + userIDs = append(userIDs, user.userID) + userNames = append(userNames, user.name) } - user, err := resolveUser(rt, name) - if err != nil { - return err + if len(userIDs) == 0 { + return apperrors.NewValidation("--with 需要至少一个有效的参会人姓名") } - userIDs = append(userIDs, user.userID) - } - if len(userIDs) == 0 { - return apperrors.NewValidation("--with 需要至少一个有效的参会人姓名") } // Under --dry-run we resolved names (reads) to validate them, but must not // create the event or send invites. Preview what would happen and return. if rt.DryRun() { return rt.Output(map[string]any{ - "dryRun": true, - "wouldCreate": createArgs, - "wouldInvite": userIDs, + "success": true, + "dryRun": true, + "executed": false, + "wouldCreate": createArgs, + "inviteeCount": len(userIDs), }) } - // Step 2 — create the event and pull the eventId from the response. - created, err := rt.CallMCPWriteData("calendar", "create_calendar_event", createArgs) + // Step 2 — create the event and require an explicit terminal receipt plus + // a stable id. Empty/unknown write acknowledgements are never success. + created, err := rt.CallMCPWriteDataStrict("calendar", "create_calendar_event", createArgs) if err != nil { return err } - eventID := shortcutExtractEventID(created) + if err := calendarSmartWriteReceipt(created, "calendar/create_calendar_event"); err != nil { + return err + } + eventID := calendarSmartEventID(created) if eventID == "" { - return apperrors.NewValidation("日程创建成功但无法从返回结果中解析 eventId，已跳过邀请参会人") + return calendarSmartError("calendar/create_calendar_event", "missing_event_id", "创建回执缺少稳定日程 id，远端效果未知") } // Step 3 — add all participants in one batch. attendeesToAdd copied // verbatim from the helper's `attendee add` call site. - if _, err := rt.CallMCPWriteData("calendar", "add_calendar_participant", map[string]any{ - "eventId": eventID, - "attendeesToAdd": userIDs, - }); err != nil { - // Rollback: delete the just-created event so we never leave a - // half-built event without its intended attendees. - _, delErr := rt.CallMCPWriteData("calendar", "delete_calendar_event", map[string]any{ - "eventId": eventID, + if len(userIDs) > 0 { + added, addErr := rt.CallMCPWriteDataStrict("calendar", "add_calendar_participant", map[string]any{ + "eventId": eventID, + "attendeesToAdd": userIDs, }) - if delErr != nil { - return apperrors.NewValidation(fmt.Sprintf( - "添加参会人失败：%v；且回滚删除日程 %s 也失败：%v（请手动删除该日程）", - err, eventID, delErr)) + if addErr == nil { + addErr = calendarSmartWriteReceipt(added, "calendar/add_calendar_participant") + } + if addErr != nil { + // Rollback itself is not enough: verify the newly-created event is + // absent before saying rollback succeeded. + if rollbackErr := calendarSmartDeleteAndVerify(rt, eventID); rollbackErr != nil { + return apperrors.NewValidation(fmt.Sprintf( + "添加参会人失败：%v；回滚删除或删除后验证失败：%v，请人工核查日程状态", + addErr, rollbackErr)) + } + return apperrors.NewValidation(fmt.Sprintf("添加参会人失败：%v；新建日程已回滚并验证不存在", addErr)) } - return apperrors.NewValidation(fmt.Sprintf( - "添加参会人失败：%v；已回滚删除日程 %s", err, eventID)) } - // Step 4 — success: print the final event detail (eventId + attendees). - return rt.CallMCP("get_calendar_detail", map[string]any{"eventId": eventID}) + // Step 4 — prove the final state before returning one composed result. + readback, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + event, err := calendarSmartRequireEvent(readback, "calendar/get_calendar_detail", eventID) + if err != nil { + return err + } + if err := calendarSmartVerifyCreatedEvent(event, eventID, rt.Str("title"), start, end); err != nil { + return err + } + if len(userIDs) > 0 { + participants, err := rt.CallMCPData("calendar", "get_calendar_participants", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + present, err := calendarSmartAttendees(participants) + if err != nil { + return err + } + currentUserID, err := calendarSmartCurrentUserID(rt, present) + if err != nil { + return err + } + if err := calendarSmartVerifyAttendees(present, userIDs, userNames, currentUserID); err != nil { + return err + } + } + return rt.Output(map[string]any{ + "success": true, + "eventId": eventID, + "verified": true, + "event": event, + }) }, } -// shortcutExtractEventID digs the eventId out of a create_calendar_event -// response, tolerating the common shapes ({eventId}, {id}, {result:{...}}, -// {event:{...}}) since the exact envelope is not guaranteed. -func shortcutExtractEventID(data map[string]any) string { - if data == nil { - return "" - } - if id := shortcutPickID(data); id != "" { - return id - } - for _, key := range []string{"result", "event", "data"} { - if nested, ok := data[key].(map[string]any); ok { - if id := shortcutPickID(nested); id != "" { - return id - } - } - } - return "" -} - -func shortcutPickID(m map[string]any) string { - for _, k := range []string{"eventId", "id"} { - if v, ok := m[k].(string); ok && strings.TrimSpace(v) != "" { - return v - } - } - return "" -} - func init() { + finalizeCalendarSmart(&Book, "已创建并通过精确读回验证的日程") shortcut.Register(Book) } diff --git a/internal/shortcut/smart/calendar_shared.go b/internal/shortcut/smart/calendar_shared.go index 15be0f12..9066ce28 100644 --- a/internal/shortcut/smart/calendar_shared.go +++ b/internal/shortcut/smart/calendar_shared.go @@ -14,10 +14,19 @@ package smart import ( + "encoding/json" + "fmt" "strings" "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) +const calendarSmartMaxPages = 20 + // calendarDayRange returns the [00:00, next-day 00:00) window for "today plus // offsetDays" in the local timezone. Shared by the day-scoped calendar // shortcuts (+today offset 0, +tomorrow offset 1, +conflicts --in-days). @@ -28,16 +37,474 @@ func calendarDayRange(offsetDays int) (time.Time, time.Time) { } // calendarProjectEvents lists and projects the events in a list_calendar_events -// response into clean {title,start,end,location,eventId} items, skipping events -// that carry no id. Shared by +today / +tomorrow / +week so the projection lives -// in exactly one place (reuses shortcutNextEventProject). -func calendarProjectEvents(data map[string]any) []map[string]any { +// response into clean {title,start,end,location,eventId} items. The strict page +// parser has already required stable ids and valid time boundaries. +func calendarProjectEvents(raw []map[string]any) []map[string]any { events := make([]map[string]any, 0) - for _, e := range shortcutNextEventList(data) { - if id, _ := e["id"].(string); strings.TrimSpace(id) == "" { - continue - } + for _, e := range raw { events = append(events, shortcutNextEventProject(e)) } return events } + +func calendarSmartResult(description string) *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"additionalProperties":true}`, + description, + )), + } +} + +func finalizeCalendarSmart(item *shortcut.Shortcut, description string) { + item.OutputRollout = output.RolloutUnifiedActive + item.Contract.Result = calendarSmartResult(description) +} + +func calendarSmartError(operation, reason, message string) error { + return apperrors.NewAPI(message, + apperrors.WithOperation(operation), + apperrors.WithOrigin("mcp"), + apperrors.WithFailureStage("response_validation"), + apperrors.WithRetryable(false), + apperrors.WithReason(reason), + ) +} + +func calendarSmartRequireSuccess(data map[string]any, operation string) (map[string]any, error) { + if len(data) == 0 { + return nil, calendarSmartError(operation, "empty_tool_response", "服务返回空响应，无法证明成功或合法空结果") + } + raw, present := data["success"] + if !present { + return nil, calendarSmartError(operation, "missing_success", "响应缺少 success 终态字段") + } + success, ok := raw.(bool) + if !ok { + return nil, calendarSmartError(operation, "malformed_success", "响应 success 字段不是布尔值") + } + if !success { + message := calendarSmartFirstString(data, "errorMsg", "errorMessage", "message", "error") + if message == "" { + message = "服务明确返回 success=false" + } + return nil, calendarSmartError(operation, "remote_failure", message) + } + return data, nil +} + +func calendarSmartRequireEvent(data map[string]any, operation, expectedID string) (map[string]any, error) { + data, err := calendarSmartRequireSuccess(data, operation) + if err != nil { + return nil, err + } + event, ok := data["result"].(map[string]any) + if !ok || len(event) == 0 { + return nil, calendarSmartError(operation, "missing_event", "响应 result 不是非空日程对象") + } + id := calendarSmartFirstString(event, "id", "eventId", "event_id") + if id == "" { + return nil, calendarSmartError(operation, "missing_event_id", "日程对象缺少稳定 id") + } + if expectedID != "" && id != expectedID { + return nil, calendarSmartError(operation, "event_id_mismatch", "读回日程 id 与请求 eventId 不一致") + } + return event, nil +} + +func calendarSmartFirstString(data map[string]any, keys ...string) string { + for _, key := range keys { + if value, ok := data[key].(string); ok && strings.TrimSpace(value) != "" { + return strings.TrimSpace(value) + } + } + return "" +} + +func calendarSmartEventID(data map[string]any) string { + if value := calendarSmartFirstString(data, "id", "eventId", "event_id"); value != "" { + return value + } + for _, key := range []string{"result", "event", "data"} { + if nested, ok := data[key].(map[string]any); ok { + if value := calendarSmartFirstString(nested, "id", "eventId", "event_id"); value != "" { + return value + } + } + } + return "" +} + +func calendarSmartListAll(rt *shortcut.RuntimeContext, params map[string]any) ([]map[string]any, error) { + all := make([]map[string]any, 0) + seenIDs := map[string]bool{} + cursor := "" + for page := 1; page <= calendarSmartMaxPages; page++ { + request := make(map[string]any, len(params)+2) + for key, value := range params { + request[key] = value + } + request["limit"] = 100 + if cursor != "" { + request["cursor"] = cursor + } + data, err := rt.CallMCPData("calendar", "list_calendar_events", request) + if err != nil { + return nil, err + } + items, hasMore, next, err := calendarSmartEventPage(data) + if err != nil { + return nil, err + } + for _, event := range items { + id := calendarSmartFirstString(event, "id", "eventId", "event_id") + if !seenIDs[id] { + seenIDs[id] = true + all = append(all, event) + } + } + if !hasMore { + return all, nil + } + if next == cursor { + return nil, calendarSmartError("calendar/list_calendar_events", "stalled_cursor", "服务端 nextCursor 未前进，不能证明列表完整") + } + cursor = next + } + return nil, calendarSmartError("calendar/list_calendar_events", "page_limit", fmt.Sprintf("自动翻页达到 %d 页上限，拒绝基于不完整事件集给出结论", calendarSmartMaxPages)) +} + +func calendarSmartEventPage(data map[string]any) ([]map[string]any, bool, string, error) { + data, err := calendarSmartRequireSuccess(data, "calendar/list_calendar_events") + if err != nil { + return nil, false, "", err + } + result, ok := data["result"].(map[string]any) + if !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "missing_result", "响应 result 不是对象") + } + rawEvents, present := result["events"] + if !present { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "missing_events", "响应缺少显式 events 数组") + } + list, ok := rawEvents.([]any) + if !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_events", "响应 events 字段不是数组") + } + rawHasMore, present := result["hasMore"] + if !present { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "missing_pagination", "响应缺少 hasMore 分页终态") + } + hasMore, ok := rawHasMore.(bool) + if !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_pagination", "响应 hasMore 字段不是布尔值") + } + next := "" + if raw, present := result["nextCursor"]; present && raw != nil { + var ok bool + next, ok = raw.(string) + if !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_pagination", "响应 nextCursor 字段不是字符串") + } + next = strings.TrimSpace(next) + } + if hasMore && next == "" { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "missing_next_cursor", "服务端返回 hasMore=true 但 nextCursor 为空") + } + if !hasMore && next != "" { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "inconsistent_pagination", "服务端返回 hasMore=false 但 nextCursor 非空") + } + events := make([]map[string]any, 0, len(list)) + for index, item := range list { + event, ok := item.(map[string]any) + if !ok || len(event) == 0 { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_event", fmt.Sprintf("events[%d] 不是非空对象", index)) + } + if calendarSmartFirstString(event, "id", "eventId", "event_id") == "" { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "missing_event_id", fmt.Sprintf("events[%d] 缺少稳定 id", index)) + } + if _, ok := shortcutNextEventStart(event); !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_event_start", fmt.Sprintf("events[%d] 缺少合法开始时间", index)) + } + if _, ok := conflictsEndTime(event); !ok { + return nil, false, "", calendarSmartError("calendar/list_calendar_events", "malformed_event_end", fmt.Sprintf("events[%d] 缺少合法结束时间", index)) + } + events = append(events, event) + } + return events, hasMore, next, nil +} + +func calendarSmartBusySlots(data map[string]any) ([]map[string]any, error) { + data, err := calendarSmartRequireSuccess(data, "calendar/query_busy_status") + if err != nil { + return nil, err + } + entries, ok := data["result"].([]any) + if !ok { + return nil, calendarSmartError("calendar/query_busy_status", "missing_result", "响应 result 不是显式忙闲数组") + } + out := make([]map[string]any, 0) + for entryIndex, entry := range entries { + object, ok := entry.(map[string]any) + if !ok || len(object) == 0 { + return nil, calendarSmartError("calendar/query_busy_status", "malformed_result_item", fmt.Sprintf("result[%d] 不是非空对象", entryIndex)) + } + rawItems, present := object["scheduleItems"] + if !present { + return nil, calendarSmartError("calendar/query_busy_status", "missing_schedule_items", fmt.Sprintf("result[%d] 缺少 scheduleItems", entryIndex)) + } + items, ok := rawItems.([]any) + if !ok { + return nil, calendarSmartError("calendar/query_busy_status", "malformed_schedule_items", fmt.Sprintf("result[%d].scheduleItems 不是数组", entryIndex)) + } + for itemIndex, item := range items { + schedule, ok := item.(map[string]any) + if !ok || len(schedule) == 0 { + return nil, calendarSmartError("calendar/query_busy_status", "malformed_schedule_item", fmt.Sprintf("scheduleItems[%d] 不是非空对象", itemIndex)) + } + start := freebusyDateTime(schedule["start"]) + end := freebusyDateTime(schedule["end"]) + if start == nil || end == nil || strings.TrimSpace(fmt.Sprint(start)) == "" || strings.TrimSpace(fmt.Sprint(end)) == "" { + return nil, calendarSmartError("calendar/query_busy_status", "malformed_schedule_time", "忙闲条目缺少开始或结束时间") + } + out = append(out, map[string]any{"start": start, "end": end}) + } + } + return out, nil +} + +func calendarSmartSuggestedSlots(data map[string]any) ([]map[string]any, error) { + data, err := calendarSmartRequireSuccess(data, "calendar/list_suggested_event_times") + if err != nil { + return nil, err + } + result, ok := data["result"].(map[string]any) + if !ok { + return nil, calendarSmartError("calendar/list_suggested_event_times", "missing_result", "响应 result 不是对象") + } + rawSlots, present := result["recommendEventTimes"] + if !present { + return nil, calendarSmartError("calendar/list_suggested_event_times", "missing_suggestions", "响应缺少显式 recommendEventTimes 数组") + } + slots, ok := rawSlots.([]any) + if !ok { + return nil, calendarSmartError("calendar/list_suggested_event_times", "malformed_suggestions", "recommendEventTimes 不是数组") + } + out := make([]map[string]any, 0, len(slots)) + for index, item := range slots { + slot, ok := item.(map[string]any) + if !ok || len(slot) == 0 { + return nil, calendarSmartError("calendar/list_suggested_event_times", "malformed_suggestion", fmt.Sprintf("recommendEventTimes[%d] 不是非空对象", index)) + } + start := slot["startTime"] + end := slot["endTime"] + if start == nil || end == nil { + return nil, calendarSmartError("calendar/list_suggested_event_times", "malformed_suggestion_time", fmt.Sprintf("recommendEventTimes[%d] 缺少 startTime/endTime", index)) + } + row := map[string]any{"start": start, "end": end} + if raw, ok := slot["timeConflictAttendees"].([]any); ok { + conflicts := make([]any, 0, len(raw)) + for _, value := range raw { + if value != nil { + conflicts = append(conflicts, value) + } + } + if len(conflicts) > 0 { + row["conflicts"] = conflicts + } + } + out = append(out, row) + } + return out, nil +} + +func calendarSmartAttendees(data map[string]any) (map[string]bool, error) { + data, err := calendarSmartRequireSuccess(data, "calendar/get_calendar_participants") + if err != nil { + return nil, err + } + var raw any + result, present := data["result"] + if !present { + return nil, calendarSmartError("calendar/get_calendar_participants", "missing_result", "参会人响应缺少 result") + } + switch typed := result.(type) { + case []any: + raw = typed + case map[string]any: + found := false + for _, key := range []string{"attendees", "participants", "items", "list"} { + if raw, found = typed[key]; found { + break + } + } + if !found { + return nil, calendarSmartError("calendar/get_calendar_participants", "missing_attendees", "响应缺少显式参会人数组") + } + default: + return nil, calendarSmartError("calendar/get_calendar_participants", "malformed_result", "参会人响应 result 既不是数组也不是含参会人数组的对象") + } + items, ok := raw.([]any) + if !ok { + return nil, calendarSmartError("calendar/get_calendar_participants", "malformed_attendees", "参会人字段不是数组") + } + identities := map[string]bool{} + for index, item := range items { + attendee, ok := item.(map[string]any) + if !ok || len(attendee) == 0 { + return nil, calendarSmartError("calendar/get_calendar_participants", "malformed_attendee", fmt.Sprintf("参会人第 %d 项不是非空对象", index)) + } + id := calendarSmartFirstString(attendee, "userId", "user_id", "id", "staffId") + name := calendarSmartFirstString(attendee, "displayName", "display_name", "name", "userName") + if id == "" && name == "" { + return nil, calendarSmartError("calendar/get_calendar_participants", "missing_attendee_identity", fmt.Sprintf("参会人第 %d 项既无 userId 也无 displayName", index)) + } + if id != "" { + identities[id] = true + } + if name != "" { + identities[name] = true + } + if rawSelf, present := attendee["self"]; present { + isSelf, ok := rawSelf.(bool) + if !ok { + return nil, calendarSmartError("calendar/get_calendar_participants", "malformed_attendee_self", fmt.Sprintf("参会人第 %d 项 self 不是布尔值", index)) + } + if isSelf { + identities["__self__"] = true + } + } + } + return identities, nil +} + +func calendarSmartVerifyEventTimes(event map[string]any, start, end string) error { + startValue, startOK := calendarSmartEventTime(event["start"]) + if !startOK { + startValue, startOK = calendarSmartEventTime(event["startDateTime"]) + } + endValue, endOK := calendarSmartEventTime(event["end"]) + if !endOK { + endValue, endOK = calendarSmartEventTime(event["endDateTime"]) + } + wantStart, startErr := time.Parse(time.RFC3339, start) + wantEnd, endErr := time.Parse(time.RFC3339, end) + if startErr != nil || endErr != nil || !startOK || !endOK || !startValue.Equal(wantStart) || !endValue.Equal(wantEnd) { + return calendarSmartError("calendar/get_calendar_detail", "readback_time_mismatch", "写后读回的开始/结束时间与请求不一致") + } + return nil +} + +func calendarSmartEventTime(value any) (time.Time, bool) { + if object, ok := value.(map[string]any); ok { + value = object["dateTime"] + } + text, ok := value.(string) + if !ok || strings.TrimSpace(text) == "" { + return time.Time{}, false + } + parsed, err := time.Parse(time.RFC3339, text) + return parsed, err == nil +} + +func calendarSmartNotFound(err error) bool { + if err == nil { + return false + } + message := strings.ToLower(err.Error()) + for _, marker := range []string{"not found", "not_found", "不存在", "未找到", "404"} { + if strings.Contains(message, marker) { + return true + } + } + return false +} + +func calendarSmartValidateRange(start, end string) error { + startTime, startErr := time.Parse(time.RFC3339, strings.TrimSpace(start)) + if startErr != nil { + return apperrors.NewValidation("--start 时间格式无效，请使用 RFC3339/ISO8601") + } + endTime, endErr := time.Parse(time.RFC3339, strings.TrimSpace(end)) + if endErr != nil { + return apperrors.NewValidation("--end 时间格式无效，请使用 RFC3339/ISO8601") + } + if !endTime.After(startTime) { + return apperrors.NewValidation("--end 必须晚于 --start") + } + return nil +} + +func calendarSmartWriteReceipt(data map[string]any, operation string) error { + _, err := calendarSmartRequireSuccess(data, operation) + return err +} + +func calendarSmartVerifyCreatedEvent(event map[string]any, eventID, title, start, end string) error { + if id := calendarSmartFirstString(event, "id", "eventId", "event_id"); id != eventID { + return calendarSmartError("calendar/get_calendar_detail", "readback_event_id_mismatch", "创建后读回的日程 id 与创建回执不一致") + } + if got := calendarSmartFirstString(event, "summary", "title"); got != strings.TrimSpace(title) { + return calendarSmartError("calendar/get_calendar_detail", "readback_title_mismatch", "创建后读回的日程标题与请求不一致") + } + return calendarSmartVerifyEventTimes(event, start, end) +} + +func calendarSmartVerifyAttendees(present map[string]bool, expectedIDs, expectedNames []string, currentUserID string) error { + for index, id := range expectedIDs { + name := "" + if index < len(expectedNames) { + name = expectedNames[index] + } + isCurrentUser := currentUserID != "" && id == currentUserID && present["__self__"] + if !present[id] && (name == "" || !present[name]) && !isCurrentUser { + return calendarSmartError("calendar/get_calendar_participants", "readback_attendee_missing", "写后读回未找到请求添加的参会人") + } + } + return nil +} + +func calendarSmartCurrentUserID(rt *shortcut.RuntimeContext, attendees map[string]bool) (string, error) { + if !attendees["__self__"] { + return "", nil + } + profile, err := rt.CallMCPData("contact", "get_current_user_profile", nil) + if err != nil { + return "", err + } + userID := myAttendanceCurrentUserID(profile) + if userID == "" { + return "", calendarSmartError("contact/get_current_user_profile", "missing_current_user_id", "参会人读回只标记 self，但无法解析当前用户 userId") + } + return userID, nil +} + +func calendarSmartDeleteAndVerify(rt *shortcut.RuntimeContext, eventID string) error { + written, err := rt.CallMCPWriteDataStrict("calendar", "delete_calendar_event", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + if err := calendarSmartWriteReceipt(written, "calendar/delete_calendar_event"); err != nil { + return err + } + data, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{"eventId": eventID}) + if err != nil { + if calendarSmartNotFound(err) { + return nil + } + return calendarSmartError("calendar/get_calendar_detail", "delete_readback_unknown", "删除后读回失败，无法证明日程已不存在") + } + event, err := calendarSmartRequireEvent(data, "calendar/get_calendar_detail", eventID) + if err != nil { + if calendarSmartNotFound(err) { + return nil + } + return err + } + status := strings.ToLower(calendarSmartFirstString(event, "status", "eventStatus", "event_status")) + if status == "cancelled" || status == "canceled" || status == "deleted" { + return nil + } + return calendarSmartError("calendar/get_calendar_detail", "delete_readback_present", "删除后读回日程仍然存在") +} diff --git a/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go b/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go new file mode 100644 index 00000000..a4cc0f65 --- /dev/null +++ b/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go @@ -0,0 +1,341 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package smart + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "io" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" +) + +type calendarSmartTestStep struct { + text string + err error +} + +type calendarSmartTestCall struct { + key string + args map[string]any +} + +type calendarSmartTestCaller struct { + steps map[string][]calendarSmartTestStep + counts map[string]int + calls []calendarSmartTestCall +} + +func (c *calendarSmartTestCaller) CallTool(_ context.Context, product, tool string, args map[string]any) (*edition.ToolResult, error) { + if c.counts == nil { + c.counts = map[string]int{} + } + key := product + "/" + tool + c.counts[key]++ + c.calls = append(c.calls, calendarSmartTestCall{key: key, args: args}) + steps := c.steps[key] + index := c.counts[key] - 1 + if index >= len(steps) { + return nil, errors.New("unexpected fixture call: " + key) + } + step := steps[index] + if step.err != nil { + return nil, step.err + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: step.text}}}, nil +} + +func (c *calendarSmartTestCaller) CallReadTool(ctx context.Context, product, tool string, args map[string]any) (*edition.ToolResult, error) { + return c.CallTool(ctx, product, tool, args) +} + +func (*calendarSmartTestCaller) Format() string { return "json" } +func (*calendarSmartTestCaller) DryRun() bool { return false } +func (*calendarSmartTestCaller) Fields() string { return "" } +func (*calendarSmartTestCaller) JQ() string { return "" } + +func runCalendarSmartCLI(t *testing.T, caller edition.ToolCaller, args ...string) (map[string]any, string, error) { + t.Helper() + helpers.InitDepsForTest(t, caller) + root := newPlatformCoverageRoot() + var stdout bytes.Buffer + root.SetOut(&stdout) + root.SetErr(io.Discard) + root.SetArgs(args) + executed, err := root.ExecuteC() + if err == nil { + if _, _, emitErr := output.EmitStoredResult(executed); emitErr != nil { + err = emitErr + } + } + if stdout.Len() == 0 { + return nil, "", err + } + var payload map[string]any + if decodeErr := json.Unmarshal(stdout.Bytes(), &payload); decodeErr != nil { + t.Fatalf("calendar output is not exactly one JSON value: %q: %v", stdout.String(), decodeErr) + } + if data, ok := payload["data"].(map[string]any); ok { + return data, stdout.String(), err + } + return payload, stdout.String(), err +} + +func calendarSmartTestEvent(id string) map[string]any { + return map[string]any{ + "id": id, + "summary": "fixture event", + "start": map[string]any{"dateTime": "2026-08-17T09:00:00+08:00"}, + "end": map[string]any{"dateTime": "2026-08-17T10:00:00+08:00"}, + } +} + +func TestCrossPlatformCoverageCalendarSmartResultContracts(t *testing.T) { + shortcuts := []struct { + name string + rollout output.RolloutState + result bool + }{ + {"today", Today.OutputRollout, Today.Contract.Result != nil}, + {"tomorrow", Tomorrow.OutputRollout, Tomorrow.Contract.Result != nil}, + {"week", Week.OutputRollout, Week.Contract.Result != nil}, + {"next-event", NextEvent.OutputRollout, NextEvent.Contract.Result != nil}, + {"conflicts", Conflicts.OutputRollout, Conflicts.Contract.Result != nil}, + {"free-slots", FreeSlots.OutputRollout, FreeSlots.Contract.Result != nil}, + {"suggest-time", SuggestTime.OutputRollout, SuggestTime.Contract.Result != nil}, + {"book", Book.OutputRollout, Book.Contract.Result != nil}, + {"cancel-event", CancelEvent.OutputRollout, CancelEvent.Contract.Result != nil}, + {"invite", Invite.OutputRollout, Invite.Contract.Result != nil}, + {"reschedule", Reschedule.OutputRollout, Reschedule.Contract.Result != nil}, + {"free", FreeBusy.OutputRollout, FreeBusy.Contract.Result != nil}, + {"my-free", MyFree.OutputRollout, MyFree.Contract.Result != nil}, + } + for _, item := range shortcuts { + if item.rollout != output.RolloutUnifiedActive || !item.result { + t.Errorf("%s rollout=%q result=%v", item.name, item.rollout, item.result) + } + } +} + +func TestCrossPlatformCoverageCalendarSmartStrictCollections(t *testing.T) { + valid := calendarSmartTestEvent("event-placeholder") + items, hasMore, next, err := calendarSmartEventPage(map[string]any{ + "success": true, + "result": map[string]any{ + "events": []any{valid}, + "hasMore": true, + "nextCursor": "cursor-placeholder", + }, + }) + if err != nil || len(items) != 1 || !hasMore || next != "cursor-placeholder" { + t.Fatalf("valid page items=%#v hasMore=%v next=%q err=%v", items, hasMore, next, err) + } + items, hasMore, next, err = calendarSmartEventPage(map[string]any{ + "success": true, + "result": map[string]any{"events": []any{}, "hasMore": false}, + }) + if err != nil || items == nil || len(items) != 0 || hasMore || next != "" { + t.Fatalf("explicit empty page items=%#v hasMore=%v next=%q err=%v", items, hasMore, next, err) + } + + invalidPages := []map[string]any{ + {}, + {"success": false, "result": map[string]any{"events": []any{}, "hasMore": false}}, + {"success": true, "result": map[string]any{"hasMore": false}}, + {"success": true, "result": map[string]any{"events": map[string]any{}, "hasMore": false}}, + {"success": true, "result": map[string]any{"events": []any{}, "hasMore": true}}, + {"success": true, "result": map[string]any{"events": []any{}, "hasMore": false, "nextCursor": "unexpected"}}, + {"success": true, "result": map[string]any{"events": []any{map[string]any{"id": "event-placeholder"}}, "hasMore": false}}, + {"success": true, "result": map[string]any{"events": []any{"bad-item"}, "hasMore": false}}, + } + for index, page := range invalidPages { + if _, _, _, err := calendarSmartEventPage(page); err == nil { + t.Errorf("invalid page %d accepted: %#v", index, page) + } + } + + allDay := map[string]any{ + "id": "all-day-placeholder", + "start": map[string]any{"date": "2026-08-17"}, + "end": map[string]any{"date": "2026-08-18"}, + } + if _, _, _, err := calendarSmartEventPage(map[string]any{ + "success": true, + "result": map[string]any{"events": []any{allDay}, "hasMore": false}, + }); err != nil { + t.Fatalf("legitimate all-day event rejected: %v", err) + } + + if slots, err := calendarSmartBusySlots(map[string]any{"success": true, "result": []any{}}); err != nil || slots == nil || len(slots) != 0 { + t.Fatalf("explicit empty busy slots=%#v err=%v", slots, err) + } + if _, err := calendarSmartBusySlots(map[string]any{"success": true, "result": []any{map[string]any{}}}); err == nil { + t.Fatal("busy result item without scheduleItems accepted") + } + if slots, err := calendarSmartSuggestedSlots(map[string]any{"success": true, "result": map[string]any{"recommendEventTimes": []any{}}}); err != nil || slots == nil || len(slots) != 0 { + t.Fatalf("explicit empty suggestions=%#v err=%v", slots, err) + } + if _, err := calendarSmartSuggestedSlots(map[string]any{"success": true, "result": map[string]any{}}); err == nil { + t.Fatal("missing recommendEventTimes accepted") + } + if _, err := calendarSmartSuggestedSlots(map[string]any{"success": true, "result": map[string]any{"recommendEventTimes": []any{map[string]any{"startTime": "x"}}}}); err == nil { + t.Fatal("suggestion without endTime accepted") + } +} + +func TestCrossPlatformCoverageCalendarSmartPaginationIsCompleteOrFails(t *testing.T) { + eventJSON := `{"id":"event-placeholder","summary":"fixture","start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"}}` + caller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/list_calendar_events": { + {text: `{"success":true,"result":{"events":[` + eventJSON + `],"hasMore":true,"nextCursor":"cursor-placeholder"}}`}, + {text: `{"success":true,"result":{"events":[],"hasMore":false}}`}, + }, + }} + payload, _, err := runCalendarSmartCLI(t, caller, "calendar", "+today") + if err != nil || payload["complete"] != true || payload["count"] != float64(1) { + t.Fatalf("today payload=%#v err=%v", payload, err) + } + if caller.counts["calendar/list_calendar_events"] != 2 { + t.Fatalf("list calls=%#v", caller.counts) + } + if got := caller.calls[1].args["cursor"]; got != "cursor-placeholder" { + t.Fatalf("second-page cursor=%#v calls=%#v", got, caller.calls) + } + + for name, responses := range map[string][]calendarSmartTestStep{ + "missing pagination": {{text: `{"success":true,"result":{"events":[]}}`}}, + "stalled cursor": { + {text: `{"success":true,"result":{"events":[],"hasMore":true,"nextCursor":"cursor-placeholder"}}`}, + {text: `{"success":true,"result":{"events":[],"hasMore":true,"nextCursor":"cursor-placeholder"}}`}, + }, + } { + t.Run(name, func(t *testing.T) { + bad := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/list_calendar_events": responses}} + payload, outputText, err := runCalendarSmartCLI(t, bad, "calendar", "+today") + if err == nil || payload != nil || outputText != "" { + t.Fatalf("incomplete list accepted payload=%#v output=%q err=%v", payload, outputText, err) + } + }) + } +} + +func TestCrossPlatformCoverageCalendarSmartWriteReceiptsAndReadback(t *testing.T) { + const start = "2026-08-17T09:00:00+08:00" + const end = "2026-08-17T10:00:00+08:00" + const eventID = "event-placeholder" + + book := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"` + eventID + `"}}`}}, + "calendar/get_calendar_detail": {{text: `{"success":true,"result":{"id":"` + eventID + `","summary":"fixture title","start":{"dateTime":"` + start + `"},"end":{"dateTime":"` + end + `"}}}`}}, + }} + payload, _, err := runCalendarSmartCLI(t, book, "calendar", "+book", "--title", "fixture title", "--start", start, "--end", end, "--yes") + if err != nil || payload["success"] != true || payload["verified"] != true || payload["eventId"] != eventID { + t.Fatalf("book payload=%#v err=%v", payload, err) + } + + unknownWrite := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/create_calendar_event": {{text: `{"result":{"id":"` + eventID + `"}}`}}, + }} + payload, outputText, err := runCalendarSmartCLI(t, unknownWrite, "calendar", "+book", "--title", "fixture title", "--start", start, "--end", end, "--yes") + if err == nil || payload != nil || outputText != "" || unknownWrite.counts["calendar/get_calendar_detail"] != 0 { + t.Fatalf("unknown create receipt accepted payload=%#v output=%q err=%v counts=%#v", payload, outputText, err, unknownWrite.counts) + } + + reschedule := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/get_calendar_detail": { + {text: `{"success":true,"result":{"id":"` + eventID + `"}}`}, + {text: `{"success":true,"result":{"id":"` + eventID + `","start":{"dateTime":"` + start + `"},"end":{"dateTime":"` + end + `"}}}`}, + }, + "calendar/update_calendar_event": {{text: `{"success":true}`}}, + }} + payload, _, err = runCalendarSmartCLI(t, reschedule, "calendar", "+reschedule", "--event", eventID, "--start", start, "--end", end, "--yes") + if err != nil || payload["success"] != true || payload["verified"] != true { + t.Fatalf("reschedule payload=%#v err=%v", payload, err) + } + updates := reschedule.calls + var updateArgs map[string]any + for _, call := range updates { + if call.key == "calendar/update_calendar_event" { + updateArgs = call.args + } + } + if updateArgs["eventId"] != eventID || updateArgs["startDateTime"] != start || updateArgs["endDateTime"] != end { + t.Fatalf("reschedule request=%#v", updateArgs) + } + + invite := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: `{"result":[{"userId":"user-placeholder","name":"fixture person"}]}`}}, + "calendar/get_calendar_detail": {{text: `{"success":true,"result":{"id":"` + eventID + `"}}`}}, + "calendar/add_calendar_participant": {{text: `{"success":true}`}}, + "calendar/get_calendar_participants": {{text: `{"success":true,"result":[{"userId":"user-placeholder"}]}`}}, + }} + payload, _, err = runCalendarSmartCLI(t, invite, "calendar", "+invite", "--event", eventID, "--with", "fixture person", "--yes") + if err != nil || payload["success"] != true || payload["verified"] != true || payload["invitedCount"] != float64(1) { + t.Fatalf("invite payload=%#v err=%v", payload, err) + } +} + +func TestCrossPlatformCoverageCalendarSmartDeleteAndRollbackVerifyAbsence(t *testing.T) { + const eventID = "event-placeholder" + const sensitiveTitle = "fixture-sensitive-title" + cancel := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/get_calendar_detail": { + {text: `{"success":true,"result":{"id":"` + eventID + `","summary":"` + sensitiveTitle + `"}}`}, + {err: errors.New("event not found")}, + }, + "calendar/delete_calendar_event": {{text: `{"success":true}`}}, + }} + payload, outputText, err := runCalendarSmartCLI(t, cancel, "calendar", "+cancel-event", "--event", eventID, "--yes") + if err != nil || payload["success"] != true || payload["deleted"] != true || payload["verified"] != true { + t.Fatalf("cancel payload=%#v err=%v", payload, err) + } + if strings.Contains(outputText, sensitiveTitle) { + t.Fatalf("pre-delete PII leaked into output: %q", outputText) + } + if cancel.counts["calendar/get_calendar_detail"] != 2 { + t.Fatalf("cancel did not verify absence: %#v", cancel.counts) + } + + tombstone := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/get_calendar_detail": { + {text: `{"success":true,"result":{"id":"` + eventID + `"}}`}, + {text: `{"success":true,"result":{"id":"` + eventID + `","status":"cancelled"}}`}, + }, + "calendar/delete_calendar_event": {{text: `{"success":true}`}}, + }} + payload, _, err = runCalendarSmartCLI(t, tombstone, "calendar", "+cancel-event", "--event", eventID, "--yes") + if err != nil || payload["success"] != true || payload["verified"] != true { + t.Fatalf("cancel tombstone payload=%#v err=%v", payload, err) + } + + unknownReadback := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "calendar/get_calendar_detail": { + {text: `{"success":true,"result":{"id":"` + eventID + `"}}`}, + {err: errors.New("temporary readback failure")}, + }, + "calendar/delete_calendar_event": {{text: `{"success":true}`}}, + }} + payload, outputText, err = runCalendarSmartCLI(t, unknownReadback, "calendar", "+cancel-event", "--event", eventID, "--yes") + if err == nil || payload != nil || outputText != "" { + t.Fatalf("unknown delete readback accepted payload=%#v output=%q err=%v", payload, outputText, err) + } + + rollback := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: `{"result":[{"userId":"user-placeholder","name":"fixture person"}]}`}}, + "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"` + eventID + `"}}`}}, + "calendar/add_calendar_participant": {{text: `{"success":false,"message":"fixture rejection"}`}}, + "calendar/delete_calendar_event": {{text: `{"success":true}`}}, + "calendar/get_calendar_detail": {{err: errors.New("event not found")}}, + }} + payload, outputText, err = runCalendarSmartCLI(t, rollback, "calendar", "+book", "--title", "fixture title", "--start", "2026-08-17T09:00:00+08:00", "--end", "2026-08-17T10:00:00+08:00", "--with", "fixture person", "--yes") + if err == nil || payload != nil || outputText != "" || rollback.counts["calendar/delete_calendar_event"] != 1 || rollback.counts["calendar/get_calendar_detail"] != 1 { + t.Fatalf("rollback was not verified payload=%#v output=%q err=%v counts=%#v", payload, outputText, err, rollback.counts) + } +} diff --git a/internal/shortcut/smart/cancel_event.go b/internal/shortcut/smart/cancel_event.go index 9d0337dd..45aec6a2 100644 --- a/internal/shortcut/smart/cancel_event.go +++ b/internal/shortcut/smart/cancel_event.go @@ -27,8 +27,8 @@ import ( // confirm-before-delete safety net so you never wipe the wrong eventId. // // Steps: first pull the event's detail via get_calendar_detail (so a bad or -// stale eventId fails clearly before any destructive write, and the title is -// surfaced back to the user). Then delete it via delete_calendar_event. +// stale eventId fails clearly before any destructive write). Then delete it via +// delete_calendar_event and verify the event is absent. // Replaces `calendar event get --id` (verify it's the right one) → // `calendar event delete --id` (destroy it). // @@ -43,7 +43,7 @@ var CancelEvent = shortcut.Shortcut{ Product: "calendar", Description: "取消（删除）一个已有日程（删除前先确认它真实存在）", Intent: "当你想取消/删除一个已经存在的日程时使用；" + - "内部先用 eventId 拉一次日程详情确认它真实存在并回显标题，再执行删除，" + + "内部先用 eventId 拉一次日程详情确认它真实存在，再执行删除并验证它已不存在，" + "避免因 eventId 写错而误删别的日程。" + "如果 eventId 查不到会直接报错，不会盲目删除。" + "这是高危写操作，会真实删除该日程，框架会二次确认。", @@ -68,7 +68,7 @@ var CancelEvent = shortcut.Shortcut{ }, Selection: contract.SelectionSpec{ AgentSummary: "取消（删除）一个已有日程（删除前先确认它真实存在）", - UseWhen: []string{"当你想取消/删除一个已经存在的日程时使用；内部先用 eventId 拉一次日程详情确认它真实存在并回显标题，再执行删除，避免因 eventId 写错而误删别的日程。如果 eventId 查不到会直接报错，不会盲目删除。这是高危写操作，会真实删除该日程，框架会二次确认。"}, + UseWhen: []string{"当你想取消/删除一个已经存在的日程时使用；内部先用 eventId 拉一次日程详情确认它真实存在，再执行删除并验证它已不存在，避免因 eventId 写错而误删别的日程。如果 eventId 查不到会直接报错，不会盲目删除。这是高危写操作，会真实删除该日程，框架会二次确认。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, Examples: []string{"dws calendar +cancel-event --event EVENT_ID"}, }, @@ -92,60 +92,35 @@ var CancelEvent = shortcut.Shortcut{ if err != nil { return err } + if _, err := calendarSmartRequireEvent(detail, "calendar/get_calendar_detail", eventID); err != nil { + return err + } - // Defensively surface the event title so the user can see what is about to - // be cancelled. Structure is unknown, so probe several candidate fields at - // both the top level and under a nested detail/event/data wrapper; if none - // match we simply skip the projection and proceed to delete. - title := cancelEventExtractTitle(detail) - if title != "" { - _ = rt.Output(map[string]any{ - "eventId": eventID, - "title": title, - "action": "about_to_cancel", + // Never print the pre-delete event detail: it may carry title, attendee, + // location, or meeting-room PII and would also create a second JSON value. + if rt.DryRun() { + return rt.Output(map[string]any{ + "success": true, + "dryRun": true, + "executed": false, + "eventId": eventID, }) } - // Step 2 — delete the event. eventId param copied verbatim from the - // helper's `event delete` call site (delete_calendar_event). - return rt.CallMCP("delete_calendar_event", map[string]any{ - "eventId": eventID, + // Step 2 — require a terminal delete receipt and then prove absence. + if err := calendarSmartDeleteAndVerify(rt, eventID); err != nil { + return err + } + return rt.Output(map[string]any{ + "success": true, + "eventId": eventID, + "deleted": true, + "verified": true, }) }, } -// cancelEventExtractTitle defensively digs a human-readable event title out of -// a get_calendar_detail response. It checks common title-ish keys at the top -// level and inside a single nested wrapper (detail/event/data/result), and -// returns "" when nothing usable is found. -func cancelEventExtractTitle(data map[string]any) string { - if data == nil { - return "" - } - if t := cancelEventTitleFromMap(data); t != "" { - return t - } - for _, k := range []string{"detail", "event", "data", "result"} { - if nested, ok := data[k].(map[string]any); ok { - if t := cancelEventTitleFromMap(nested); t != "" { - return t - } - } - } - return "" -} - -func cancelEventTitleFromMap(m map[string]any) string { - for _, k := range []string{"summary", "title", "subject", "name"} { - if v, ok := m[k].(string); ok { - if s := strings.TrimSpace(v); s != "" { - return s - } - } - } - return "" -} - func init() { + finalizeCalendarSmart(&CancelEvent, "已删除并通过缺席读回验证的日程") shortcut.Register(CancelEvent) } diff --git a/internal/shortcut/smart/compatibility_coverage_test.go b/internal/shortcut/smart/compatibility_coverage_test.go index 06bc299d..7d3afda1 100644 --- a/internal/shortcut/smart/compatibility_coverage_test.go +++ b/internal/shortcut/smart/compatibility_coverage_test.go @@ -24,6 +24,7 @@ import ( "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" @@ -65,6 +66,10 @@ func (f *platformCoverageCaller) CallTool(_ context.Context, product, tool strin } case "contact/get_current_user_profile": text = `{"result":{"userId":"u1"}}` + case "todo/create_personal_todo": + text = `{"success":true,"result":{"taskId":"todo-created"}}` + case "todo/get_todo_detail": + text = `{"success":true,"result":{"todoDetailModel":{"taskId":"todo-created","subject":"交周报","isDone":false}}}` case "im/search_groups": text = `{"result":[{"openConversationId":"cid-1","title":"项目冲刺"}]}` case "chat/list_conversation_message_v2": @@ -112,6 +117,8 @@ func (f *platformCoverageCaller) JQ() string { return "" } func newPlatformCoverageRoot() *cobra.Command { root := &cobra.Command{Use: "dws", SilenceUsage: true, SilenceErrors: true} + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) root.SetOut(io.Discard) root.SetErr(io.Discard) root.PersistentFlags().Bool("yes", false, "") diff --git a/internal/shortcut/smart/conflicts.go b/internal/shortcut/smart/conflicts.go index 2aacda13..6cc565a2 100644 --- a/internal/shortcut/smart/conflicts.go +++ b/internal/shortcut/smart/conflicts.go @@ -83,7 +83,7 @@ var Conflicts = shortcut.Shortcut{ // Target day window in local time. dayStart, dayEnd := calendarDayRange(rt.Int("in-days")) - data, err := rt.CallMCPData("calendar", "list_calendar_events", map[string]any{ + events, err := calendarSmartListAll(rt, map[string]any{ "startTime": dayStart.UnixMilli(), "endTime": dayEnd.UnixMilli(), "calendarId": "primary", @@ -100,7 +100,7 @@ var Conflicts = shortcut.Shortcut{ end time.Time } var evs []ev - for _, e := range shortcutNextEventList(data) { + for _, e := range events { start, ok := shortcutNextEventStart(e) if !ok { continue @@ -139,25 +139,33 @@ var Conflicts = shortcut.Shortcut{ "conflictCount": len(conflicts), "hasConflict": len(conflicts) > 0, "conflicts": conflicts, + "complete": true, }) }, } -// conflictsEndTime parses an event's end time from end.dateTime (RFC3339). +// conflictsEndTime parses a timed event or a legitimate all-day event. func conflictsEndTime(e map[string]any) (time.Time, bool) { end, ok := e["end"].(map[string]any) - if !ok { - return time.Time{}, false + if ok { + if dt, ok := end["dateTime"].(string); ok && dt != "" { + t, err := time.Parse(time.RFC3339, dt) + return t, err == nil + } + if date, ok := end["date"].(string); ok && date != "" { + t, err := time.ParseInLocation("2006-01-02", date, time.Local) + return t, err == nil + } } - dt, ok := end["dateTime"].(string) - if !ok || dt == "" { - return time.Time{}, false + for _, key := range []string{"endTime", "endDateTime"} { + if dt, ok := e[key].(string); ok && dt != "" { + t, err := time.Parse(time.RFC3339, dt) + if err == nil { + return t, true + } + } } - t, err := time.Parse(time.RFC3339, dt) - if err != nil { - return time.Time{}, false - } - return t, true + return time.Time{}, false } func conflictsLabel(title string, start, end time.Time) string { @@ -179,5 +187,6 @@ func conflictsMin(a, b time.Time) time.Time { } func init() { + finalizeCalendarSmart(&Conflicts, "完整事件集上的时间冲突分析") shortcut.Register(Conflicts) } diff --git a/internal/shortcut/smart/created_todos.go b/internal/shortcut/smart/created_todos.go index 4f9cba6e..3c5ac69a 100644 --- a/internal/shortcut/smart/created_todos.go +++ b/internal/shortcut/smart/created_todos.go @@ -14,8 +14,11 @@ package smart import ( + "encoding/json" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -39,10 +42,11 @@ import ( // // dws todo +created-todos var CreatedTodos = shortcut.Shortcut{ - Service: "todo", - Command: "+created-todos", - Product: "todo", - Description: "列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的）", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+created-todos", + Product: "todo", + Description: "列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的）", Intent: "当你想快速看清『哪些待办是我自己创建/发起的』，而不是别人指派给我执行的待办时使用；" + "内部拉取你当前组织下角色为创建人(creator)的待办列表（roleTypes=[\"creator\"]，" + "creator 是待办列表支持的角色枚举之一），再在本地把每条待办投影成标题(subject)、" + @@ -62,6 +66,7 @@ var CreatedTodos = shortcut.Shortcut{ PrimaryCLIPath: "todo +created-todos", }, Description: "列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"我创建的全部待办","properties":{"created":{"type":"array","description":"创建人角色待办","items":{"type":"object","description":"待办条目","additionalProperties":true}}},"required":["created"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", diff --git a/internal/shortcut/smart/due_today.go b/internal/shortcut/smart/due_today.go index ed2e907c..cb1343b8 100644 --- a/internal/shortcut/smart/due_today.go +++ b/internal/shortcut/smart/due_today.go @@ -14,9 +14,12 @@ package smart import ( + "encoding/json" "time" - apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -45,16 +48,32 @@ import ( // // dws todo +due-today var DueToday = shortcut.Shortcut{ - Service: "todo", - Command: "+due-today", - Product: "todo", - Description: "列出我今天到期的待办", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+due-today", + Product: "todo", + Description: "列出我今天到期的待办", Intent: "当你想快速看清自己今天（planFinishDate 落在今天 00:00 到次日 00:00 之间）到期的待办、方便安排一天的工作时使用；" + "内部按今天的本地时间窗，把 planFinishDateStart=今天0点、planFinishDateEnd=次日0点（毫秒时间戳）传给 get_user_todos_in_current_org 做服务端过滤，" + "默认拉取你作为执行人(executor)的待办，可用 --role-types 覆盖角色范围，最后只打印这些今天到期待办的标题、状态、优先级、创建人、到期时间和任务 ID。" + "这与 +overdue（已过期）不同：+overdue 看的是已经过了截止时间的待办，本命令看的是今天当天到期的待办。" + "这是纯只读操作，只做列表与投影，不会修改或完成任何待办；若今天没有到期的待办则返回错误提示。", Risk: shortcut.RiskRead, + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: corecmd.ContractDecl{ + Identity: contract.ToolIdentitySpec{ProductID: "todo", Name: "shortcut_due_today", CanonicalPath: "todo.shortcut_due_today", CLIPath: "todo +due-today", PrimaryCLIPath: "todo +due-today"}, + Description: "列出我今天到期的待办", + Interface: &contract.InterfaceSpec{Mode: "composite", Availability: "available", Reason: "Reviewed Todo composite: local-day window construction, strict full pagination and projection are owned by the executable shortcut."}, + Selection: contract.SelectionSpec{ + AgentSummary: "列出我今天到期的待办", + UseWhen: []string{"需要查看本地日历日今天到期的待办时"}, + AvoidWhen: []string{"查看已经逾期的任务时使用 todo +overdue"}, + Examples: []string{"dws todo +due-today"}, + }, + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"今天到期的待办","properties":{"count":{"type":"integer","description":"任务数量"},"tasks":{"type":"array","description":"今天到期的任务","items":{"type":"object","description":"待办条目","additionalProperties":true}}},"required":["count","tasks"],"additionalProperties":false}`)}, + }, Flags: []shortcut.Flag{ { Name: "role-types", @@ -108,24 +127,24 @@ var DueToday = shortcut.Shortcut{ // leaks outside [startMs, endMs). results := make([]map[string]any, 0, len(cards)) for _, m := range cards { - if due, ok := shortcutOverdueDueTime(m); ok { // reused from overdue.go - if due < startMs || due >= endMs { - continue - } + due, ok := shortcutOverdueDueTime(m) + if !ok { + return shortcutTodoResponseError("malformed_due_time", "今天到期结果缺少可解析的 dueTime") + } + if due < startMs || due >= endMs { + continue } taskID := shortcutRelatedTaskID(m) // reused from related_tasks.go results = append(results, shortcutRelatedProject(m, taskID)) // reused from related_tasks.go } - if len(results) == 0 { - return apperrors.NewValidation("今天没有到期的待办") - } - // Step 4 — print the projected list. return rt.Output(map[string]any{"count": len(results), "tasks": results}) }, } func init() { + DueToday.Contract.Selection.AgentSummary = DueToday.Description + DueToday.Contract.Selection.UseWhen = []string{DueToday.Intent} shortcut.Register(DueToday) } diff --git a/internal/shortcut/smart/free_slots.go b/internal/shortcut/smart/free_slots.go index cdad5b1b..ad6a249c 100644 --- a/internal/shortcut/smart/free_slots.go +++ b/internal/shortcut/smart/free_slots.go @@ -102,7 +102,7 @@ var FreeSlots = shortcut.Shortcut{ // List the day's events (a little wider than the work window so events // spanning the edges are captured). - data, err := rt.CallMCPData("calendar", "list_calendar_events", map[string]any{ + events, err := calendarSmartListAll(rt, map[string]any{ "startTime": day.UnixMilli(), "endTime": day.AddDate(0, 0, 1).UnixMilli(), "calendarId": "primary", @@ -114,7 +114,7 @@ var FreeSlots = shortcut.Shortcut{ // Collect and clip busy intervals to the work window. type interval struct{ start, end time.Time } var busy []interval - for _, e := range shortcutNextEventList(data) { + for _, e := range events { s, ok := shortcutNextEventStart(e) if !ok { continue @@ -156,6 +156,7 @@ var FreeSlots = shortcut.Shortcut{ "slotCount": len(free), "freeSlots": free, "allBusy": len(free) == 0, + "complete": true, }) }, } @@ -170,5 +171,6 @@ func freeSlotEntry(start, end time.Time) map[string]any { } func init() { + finalizeCalendarSmart(&FreeSlots, "完整事件集上计算的工作时段空档") shortcut.Register(FreeSlots) } diff --git a/internal/shortcut/smart/freebusy.go b/internal/shortcut/smart/freebusy.go index dac45a48..7be04dc6 100644 --- a/internal/shortcut/smart/freebusy.go +++ b/internal/shortcut/smart/freebusy.go @@ -102,7 +102,10 @@ var FreeBusy = shortcut.Shortcut{ if err != nil { return err } - busy := freebusySlots(data) + busy, err := calendarSmartBusySlots(data) + if err != nil { + return err + } return rt.Output(map[string]any{ "who": user.name, "userId": user.userID, @@ -112,31 +115,6 @@ var FreeBusy = shortcut.Shortcut{ }, } -// freebusySlots flattens a query_busy_status response (result[] → scheduleItems[] -// → {start,end}.dateTime) into a flat list of {start,end} busy slots. -func freebusySlots(data map[string]any) []map[string]any { - out := []map[string]any{} - entries, _ := data["result"].([]any) - for _, e := range entries { - em, ok := e.(map[string]any) - if !ok { - continue - } - items, _ := em["scheduleItems"].([]any) - for _, it := range items { - im, ok := it.(map[string]any) - if !ok { - continue - } - out = append(out, map[string]any{ - "start": freebusyDateTime(im["start"]), - "end": freebusyDateTime(im["end"]), - }) - } - } - return out -} - // freebusyDateTime pulls the readable timestamp out of a {date,dateTime,timeZone} // object, falling back to the raw value. func freebusyDateTime(v any) any { @@ -163,5 +141,6 @@ func freebusyParseMillis(flag, value string) (int64, error) { } func init() { + finalizeCalendarSmart(&FreeBusy, "严格校验的指定用户忙闲时段") shortcut.Register(FreeBusy) } diff --git a/internal/shortcut/smart/invite.go b/internal/shortcut/smart/invite.go index 6fb007df..e7ab195d 100644 --- a/internal/shortcut/smart/invite.go +++ b/internal/shortcut/smart/invite.go @@ -84,6 +84,7 @@ var Invite = shortcut.Shortcut{ // Resolve every participant name to a unique userId first, so an // unknown/ambiguous name fails before we touch the event. var userIDs []string + var userNames []string for _, name := range strings.Split(rt.Str("with"), ",") { name = strings.TrimSpace(name) if name == "" { @@ -94,20 +95,65 @@ var Invite = shortcut.Shortcut{ return err } userIDs = append(userIDs, user.userID) + userNames = append(userNames, user.name) } if len(userIDs) == 0 { return apperrors.NewValidation("--with 需要至少一个有效的参会人姓名") } - // Batch-add all participants. eventId + attendeesToAdd copied verbatim - // from the helper's `attendee add` call site (add_calendar_participant). - return rt.CallMCP("add_calendar_participant", map[string]any{ + preflight, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + if _, err := calendarSmartRequireEvent(preflight, "calendar/get_calendar_detail", eventID); err != nil { + return err + } + if rt.DryRun() { + return rt.Output(map[string]any{ + "success": true, + "dryRun": true, + "executed": false, + "eventId": eventID, + "inviteeCount": len(userIDs), + }) + } + + // Batch-add all participants and require explicit success. + written, err := rt.CallMCPWriteDataStrict("calendar", "add_calendar_participant", map[string]any{ "eventId": eventID, "attendeesToAdd": userIDs, }) + if err != nil { + return err + } + if err := calendarSmartWriteReceipt(written, "calendar/add_calendar_participant"); err != nil { + return err + } + participants, err := rt.CallMCPData("calendar", "get_calendar_participants", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + present, err := calendarSmartAttendees(participants) + if err != nil { + return err + } + currentUserID, err := calendarSmartCurrentUserID(rt, present) + if err != nil { + return err + } + if err := calendarSmartVerifyAttendees(present, userIDs, userNames, currentUserID); err != nil { + return err + } + return rt.Output(map[string]any{ + "success": true, + "eventId": eventID, + "invitedCount": len(userIDs), + "verified": true, + }) }, } func init() { + finalizeCalendarSmart(&Invite, "已添加并通过参会人读回验证的邀请") shortcut.Register(Invite) } diff --git a/internal/shortcut/smart/mail_space_todo_projection_test.go b/internal/shortcut/smart/mail_space_todo_projection_test.go index 80869469..ba41a90c 100644 --- a/internal/shortcut/smart/mail_space_todo_projection_test.go +++ b/internal/shortcut/smart/mail_space_todo_projection_test.go @@ -111,9 +111,13 @@ func runShortcut(t *testing.T, fake *stubMailboxCaller, argv ...string) string { root.SetOut(&buf) root.SetErr(io.Discard) root.SetArgs(argv) - if err := root.Execute(); err != nil { + executed, err := root.ExecuteC() + if err != nil { t.Fatalf("execute %v: %v", argv, err) } + if _, _, err := output.EmitStoredResult(executed); err != nil { + t.Fatalf("emit %v: %v", argv, err) + } return buf.String() } @@ -173,14 +177,15 @@ func TestCreatedTodosProjectsCards(t *testing.T) { "get_user_todos_in_current_org": `{"result":{"todoCards":[ {"subject":"todoA","taskId":"111","dueTime":1784686500000}, {"subject":"todoB","taskId":"222"} - ]}}`, + ],"hasMore":false}}`, }} out := runShortcut(t, fake, "todo", "+created-todos", "--format", "json") var d map[string]any if err := json.Unmarshal([]byte(out), &d); err != nil { t.Fatalf("output not json: %q", out) } - created, _ := d["created"].([]any) + payload, _ := d["data"].(map[string]any) + created, _ := payload["created"].([]any) if len(created) != 2 { t.Fatalf("lower/upper mismatch: 2 todos in backend, projection created=%d (%s)", len(created), out) } diff --git a/internal/shortcut/smart/my_free.go b/internal/shortcut/smart/my_free.go index 0ae772aa..5ec777bb 100644 --- a/internal/shortcut/smart/my_free.go +++ b/internal/shortcut/smart/my_free.go @@ -33,7 +33,7 @@ import ( // // 2. query_busy_status for [start,end] (defaults to today 00:00→tomorrow 00:00 // in local time), then project result[].scheduleItems[] to a flat -// {start,end} busy list (reusing freebusySlots). +// {start,end} busy list through the shared strict busy-response parser. // // dws calendar +my-free // dws calendar +my-free --start 2026-07-10T09:00:00+08:00 --end 2026-07-10T18:00:00+08:00 @@ -118,7 +118,7 @@ var MyFree = shortcut.Shortcut{ return apperrors.NewValidation("--end 必须晚于 --start") } - // Step 3 — query and project busy slots (reuse freebusySlots). + // Step 3 — query and strictly project busy slots. data, err := rt.CallMCPData("calendar", "query_busy_status", map[string]any{ "startTime": startMillis, "endTime": endMillis, @@ -127,7 +127,10 @@ var MyFree = shortcut.Shortcut{ if err != nil { return err } - busy := freebusySlots(data) + busy, err := calendarSmartBusySlots(data) + if err != nil { + return err + } return rt.Output(map[string]any{ "userId": userID, "busy": busy, @@ -137,5 +140,6 @@ var MyFree = shortcut.Shortcut{ } func init() { + finalizeCalendarSmart(&MyFree, "严格校验的当前用户忙闲时段") shortcut.Register(MyFree) } diff --git a/internal/shortcut/smart/next_event.go b/internal/shortcut/smart/next_event.go index a31b133d..72147a52 100644 --- a/internal/shortcut/smart/next_event.go +++ b/internal/shortcut/smart/next_event.go @@ -82,20 +82,20 @@ var NextEvent = shortcut.Shortcut{ "endTime": now.Add(7 * 24 * time.Hour).UnixMilli(), } - data, err := rt.CallMCPData("calendar", "list_calendar_events", params) + events, err := calendarSmartListAll(rt, params) if err != nil { return err } - event := shortcutNextEventPick(data, now) + event := shortcutNextEventPick(events, now) if event == nil { - return rt.Output(map[string]any{"event": nil, "message": "近 7 天无日程"}) + return rt.Output(map[string]any{"event": nil, "message": "近 7 天无日程", "complete": true}) } // Emit a structured event via rt.Output so it honours // --format/--jq/--fields (previously it printed a fixed text line and // ignored the output flags, unlike +today/+week). - return rt.Output(map[string]any{"event": shortcutNextEventProject(event)}) + return rt.Output(map[string]any{"event": shortcutNextEventProject(event), "complete": true}) }, } @@ -103,10 +103,10 @@ var NextEvent = shortcut.Shortcut{ // events (must carry an id) whose start time is at or after `now`, and returns // the one that starts soonest. Field access is fully defensive because the // response envelope and per-event shape are not guaranteed. -func shortcutNextEventPick(data map[string]any, now time.Time) map[string]any { +func shortcutNextEventPick(events []map[string]any, now time.Time) map[string]any { var best map[string]any var bestStart time.Time - for _, e := range shortcutNextEventList(data) { + for _, e := range events { id, _ := e["id"].(string) if strings.TrimSpace(id) == "" { continue @@ -126,35 +126,7 @@ func shortcutNextEventPick(data map[string]any, now time.Time) map[string]any { return best } -// shortcutNextEventList flattens the events slice out of the common response -// shapes ({result:{events:[...]}}, {events:[...]}, or a bare [...] under -// result/data). -func shortcutNextEventList(data map[string]any) []map[string]any { - if data == nil { - return nil - } - var raw []any - if result, ok := data["result"].(map[string]any); ok { - if ev, ok := result["events"].([]any); ok { - raw = ev - } - } - if raw == nil { - if ev, ok := data["events"].([]any); ok { - raw = ev - } - } - out := make([]map[string]any, 0, len(raw)) - for _, item := range raw { - if m, ok := item.(map[string]any); ok { - out = append(out, m) - } - } - return out -} - -// shortcutNextEventStart pulls an event's start time as a time.Time, tolerating -// either the nested {start:{dateTime: RFC3339}} shape or a flat string field. +// shortcutNextEventStart parses a timed event or a legitimate all-day event. func shortcutNextEventStart(event map[string]any) (time.Time, bool) { if start, ok := event["start"].(map[string]any); ok { if dt, ok := start["dateTime"].(string); ok && dt != "" { @@ -162,6 +134,11 @@ func shortcutNextEventStart(event map[string]any) (time.Time, bool) { return t, true } } + if date, ok := start["date"].(string); ok && date != "" { + if t, err := time.ParseInLocation("2006-01-02", date, time.Local); err == nil { + return t, true + } + } } for _, k := range []string{"startTime", "startDateTime"} { if dt, ok := event[k].(string); ok && dt != "" { @@ -188,12 +165,8 @@ func shortcutNextEventProject(event map[string]any) map[string]any { if start, ok := shortcutNextEventStart(event); ok { item["start"] = start.Format("2006-01-02 15:04") } - if end, ok := event["end"].(map[string]any); ok { - if dt, ok := end["dateTime"].(string); ok && dt != "" { - if t, err := time.Parse(time.RFC3339, dt); err == nil { - item["end"] = t.Format("2006-01-02 15:04") - } - } + if end, ok := conflictsEndTime(event); ok { + item["end"] = end.Format("2006-01-02 15:04") } if loc, ok := event["location"].(string); ok && strings.TrimSpace(loc) != "" { item["location"] = loc @@ -202,5 +175,6 @@ func shortcutNextEventProject(event map[string]any) map[string]any { } func init() { + finalizeCalendarSmart(&NextEvent, "完整翻页后选出的最近日程或明确空结果") shortcut.Register(NextEvent) } diff --git a/internal/shortcut/smart/overdue.go b/internal/shortcut/smart/overdue.go index c5b5d1ba..d1342c77 100644 --- a/internal/shortcut/smart/overdue.go +++ b/internal/shortcut/smart/overdue.go @@ -14,12 +14,14 @@ package smart import ( + "encoding/json" "strings" "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -41,10 +43,11 @@ import ( // // dws todo +overdue var Overdue = shortcut.Shortcut{ - Service: "todo", - Command: "+overdue", - Product: "todo", - Description: "列出我已过期未完成的待办", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+overdue", + Product: "todo", + Description: "列出我已过期未完成的待办", Intent: "当你想快速看清自己有哪些待办已经过了截止时间却还没做完、方便优先处理时使用；" + "内部先拉取你当前组织下作为执行人(executor)的待办列表，再在本地按「有截止时间(dueTime) 且早于当前时刻 且尚未完成」的条件筛选，" + "最后只打印这些逾期待办的标题(subject)、截止时间(dueTime) 和任务 ID(taskId)。" + @@ -63,6 +66,7 @@ var Overdue = shortcut.Shortcut{ PrimaryCLIPath: "todo +overdue", }, Description: "列出我已过期未完成的待办", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"逾期未完成待办","properties":{"overdue":{"type":"array","description":"逾期未完成任务","items":{"type":"object","description":"待办条目","additionalProperties":true}}},"required":["overdue"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", diff --git a/internal/shortcut/smart/related_tasks.go b/internal/shortcut/smart/related_tasks.go index 5b28645d..937ddb1d 100644 --- a/internal/shortcut/smart/related_tasks.go +++ b/internal/shortcut/smart/related_tasks.go @@ -14,10 +14,14 @@ package smart import ( + "encoding/json" "fmt" "strings" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -46,16 +50,33 @@ import ( // // dws todo +related-tasks var RelatedTasks = shortcut.Shortcut{ - Service: "todo", - Command: "+related-tasks", - Product: "todo", - Description: "一次性列出与我相关的全部待办（我作为创建人/执行人/参与人三种角色的并集，按 taskId 去重）", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+get-related-tasks", + Aliases: []string{"+related-tasks"}, + Product: "todo", + Description: "一次性列出与我相关的全部待办（我作为创建人/执行人/参与人三种角色的并集，按 taskId 去重）", Intent: "当你想一次看清『所有和我有关的待办』——不管是我创建(creator)的、指派给我执行(executor)的、还是我作为参与人(participant)协作的——时使用；" + "内部默认拉取你当前组织下 roleTypes=[\"creator\",\"executor\",\"participant\"] 三种角色的待办并集（这三个值正是待办列表支持的角色枚举），" + "再在本地按任务 ID(taskId) 去重（同一条待办可能因多角色重复出现），把每条投影成标题、状态、优先级、创建人、计划完成时间和 taskId 打印出来。" + "可用 --role-types 以逗号分隔覆盖默认角色（取值 creator/executor/participant），可用 --status 透传 todoStatus 过滤状态。" + "这是纯只读操作，只做列表、去重与投影，不会创建或修改任何待办；若没有与你相关的待办则返回空列表。", Risk: shortcut.RiskRead, + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: corecmd.ContractDecl{ + Identity: contract.ToolIdentitySpec{ProductID: "todo", Name: "shortcut_get_related_tasks", CanonicalPath: "todo.shortcut_get_related_tasks", CLIPath: "todo +get-related-tasks", PrimaryCLIPath: "todo +get-related-tasks", Aliases: []string{"todo +related-tasks"}}, + Description: "一次性列出与我相关的全部待办（创建人/执行人/参与人并集）", + Interface: &contract.InterfaceSpec{Mode: "composite", Availability: "available", Reason: "Reviewed Todo composite: strict full pagination, role union, deduplication and projection are owned by the executable shortcut."}, + Selection: contract.SelectionSpec{ + AgentSummary: "列出与我相关的全部待办", + UseWhen: []string{"需要查看我作为创建人、执行人或参与人的全部待办并集时"}, + AvoidWhen: []string{"只需默认执行人视角列表时使用 todo +get-my-tasks"}, + Examples: []string{"dws todo +get-related-tasks"}, + }, + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"与当前用户相关的待办并集","properties":{"count":{"type":"integer","description":"去重后的任务数量"},"tasks":{"type":"array","description":"按 taskId 去重的任务","items":{"type":"object","description":"待办条目","additionalProperties":true}}},"required":["count","tasks"],"additionalProperties":false}`)}, + }, Flags: []shortcut.Flag{ { Name: "role-types", @@ -69,9 +90,9 @@ var RelatedTasks = shortcut.Shortcut{ }, }, Tips: []string{ - `dws todo +related-tasks`, - `dws todo +related-tasks --role-types creator,executor`, - `dws todo +related-tasks --status TODO`, + `dws todo +get-related-tasks`, + `dws todo +get-related-tasks --role-types creator,executor`, + `dws todo +get-related-tasks --status TODO`, }, Execute: func(rt *shortcut.RuntimeContext) error { // Step 1 — build params. roleTypes defaults to the three-role union; @@ -117,10 +138,6 @@ var RelatedTasks = shortcut.Shortcut{ results = append(results, shortcutRelatedProject(m, taskID)) } - if len(results) == 0 { - return apperrors.NewValidation("没有与你相关的待办（creator/executor/participant 三种角色下均为空）") - } - // Step 3 — print the deduped, projected list. return rt.Output(map[string]any{"tasks": results, "count": len(results)}) }, @@ -203,5 +220,7 @@ func shortcutRelatedStr(m map[string]any, keys ...string) string { } func init() { + RelatedTasks.Contract.Selection.AgentSummary = RelatedTasks.Description + RelatedTasks.Contract.Selection.UseWhen = []string{RelatedTasks.Intent} shortcut.Register(RelatedTasks) } diff --git a/internal/shortcut/smart/remind.go b/internal/shortcut/smart/remind.go index d5a8639b..5ca685a2 100644 --- a/internal/shortcut/smart/remind.go +++ b/internal/shortcut/smart/remind.go @@ -14,6 +14,7 @@ package smart import ( + "encoding/json" "fmt" "time" @@ -21,7 +22,9 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + todoshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/todo" ) // Remind: create a personal todo for YOURSELF with an optional due time, @@ -35,10 +38,11 @@ import ( // // dws todo +remind --task "交周报" --at 2026-03-10T18:00:00+08:00 var Remind = shortcut.Shortcut{ - Service: "todo", - Command: "+remind", - Product: "todo", - Description: "给自己创建一条带可选截止时间的待办", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+remind", + Product: "todo", + Description: "给自己创建一条带可选截止时间的待办", Intent: "当你想给自己记一件事、并（可选）设一个截止时间，又不想先查自己的 userId 时使用；" + "内部先解析当前登录用户的 userId，再显式设置 executorIds，--at 只会按 ISO8601 写入截止时间 dueTime，不会创建独立提醒规则。会真实创建待办。", Risk: shortcut.RiskWrite, @@ -55,6 +59,7 @@ var Remind = shortcut.Shortcut{ PrimaryCLIPath: "todo +remind", }, Description: "给自己创建一条带可选截止时间的待办", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"已验证的自用待办","properties":{"taskId":{"type":"string","description":"新待办稳定 taskId"},"subject":{"type":"string","description":"待办标题"},"verified":{"type":"boolean","description":"是否完成详情读回核验"}},"required":["taskId","subject","verified"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -101,9 +106,21 @@ var Remind = shortcut.Shortcut{ vo["dueTime"] = ms } - return rt.CallMCP("create_personal_todo", map[string]any{ + params := map[string]any{ "PersonalTodoCreateVO": vo, - }) + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "subject": rt.Str("task")}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "create_personal_todo", params) + if err != nil { + return err + } + taskID, _, err := todoshortcut.VerifyCreatedTodo(rt, data, "todo/create_personal_todo", rt.Str("task")) + if err != nil { + return err + } + return rt.Output(map[string]any{"taskId": taskID, "subject": rt.Str("task"), "verified": true}) }, } diff --git a/internal/shortcut/smart/remind_contract_test.go b/internal/shortcut/smart/remind_contract_test.go index d18c3514..0059f877 100644 --- a/internal/shortcut/smart/remind_contract_test.go +++ b/internal/shortcut/smart/remind_contract_test.go @@ -34,8 +34,8 @@ func TestRemindShortcutWritesAtOnlyAsDueTime(t *testing.T) { if err := root.Execute(); err != nil { t.Fatalf("execute +remind: %v", err) } - if len(fake.calls) != 2 { - t.Fatalf("tool calls = %#v, want profile read plus todo create", fake.calls) + if len(fake.calls) != 3 { + t.Fatalf("tool calls = %#v, want profile read, todo create and detail verification", fake.calls) } call := fake.calls[1] if call.product != "todo" || call.tool != "create_personal_todo" { @@ -51,6 +51,9 @@ func TestRemindShortcutWritesAtOnlyAsDueTime(t *testing.T) { if _, exists := request["reminderRules"]; exists { t.Fatalf("unexpected reminderRules in %#v", request) } + if got := fake.calls[2].tool; got != "get_todo_detail" { + t.Fatalf("verification call = %q, want get_todo_detail", got) + } } func TestRemindShortcutRejectsInvalidAtBeforeTodoCreate(t *testing.T) { diff --git a/internal/shortcut/smart/reschedule.go b/internal/shortcut/smart/reschedule.go index 1b779676..94f58583 100644 --- a/internal/shortcut/smart/reschedule.go +++ b/internal/shortcut/smart/reschedule.go @@ -87,27 +87,68 @@ var Reschedule = shortcut.Shortcut{ if start == "" || end == "" { return apperrors.NewValidation("--start 与 --end 都必须提供（ISO8601 时间字符串）") } + if err := calendarSmartValidateRange(start, end); err != nil { + return err + } // Step 1 — confirm the event exists. eventId param copied verbatim from the // helper's `event get` call site (get_calendar_detail). - if _, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{ + preflight, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{ "eventId": eventID, - }); err != nil { + }) + if err != nil { return err } + if _, err := calendarSmartRequireEvent(preflight, "calendar/get_calendar_detail", eventID); err != nil { + return err + } + if rt.DryRun() { + return rt.Output(map[string]any{ + "success": true, + "dryRun": true, + "executed": false, + "eventId": eventID, + "start": start, + "end": end, + }) + } // Step 2 — update ONLY the time. eventId + startDateTime/endDateTime (ISO // strings, not millis) copied verbatim from the helper's `event update` // call site (update_calendar_event). No other field is passed, so nothing // else on the event is changed. - return rt.CallMCP("update_calendar_event", map[string]any{ + written, err := rt.CallMCPWriteDataStrict("calendar", "update_calendar_event", map[string]any{ "eventId": eventID, "startDateTime": start, "endDateTime": end, }) + if err != nil { + return err + } + if err := calendarSmartWriteReceipt(written, "calendar/update_calendar_event"); err != nil { + return err + } + readback, err := rt.CallMCPData("calendar", "get_calendar_detail", map[string]any{"eventId": eventID}) + if err != nil { + return err + } + event, err := calendarSmartRequireEvent(readback, "calendar/get_calendar_detail", eventID) + if err != nil { + return err + } + if err := calendarSmartVerifyEventTimes(event, start, end); err != nil { + return err + } + return rt.Output(map[string]any{ + "success": true, + "eventId": eventID, + "verified": true, + "event": event, + }) }, } func init() { + finalizeCalendarSmart(&Reschedule, "已改期并通过精确时间读回验证的日程") shortcut.Register(Reschedule) } diff --git a/internal/shortcut/smart/suggest_time.go b/internal/shortcut/smart/suggest_time.go index eeb2b56f..d8954b96 100644 --- a/internal/shortcut/smart/suggest_time.go +++ b/internal/shortcut/smart/suggest_time.go @@ -80,6 +80,9 @@ var SuggestTime = shortcut.Shortcut{ `dws calendar +suggest-time --with 张三,李四,王五 --start "2026-03-10T09:00:00+08:00" --end "2026-03-10T18:00:00+08:00" --duration 30`, }, Execute: func(rt *shortcut.RuntimeContext) error { + if err := calendarSmartValidateRange(rt.Str("start"), rt.Str("end")); err != nil { + return err + } // Step 1 — resolve every participant name to a unique userId. names := rt.StrSlice("with") if len(names) == 0 { @@ -127,46 +130,15 @@ var SuggestTime = shortcut.Shortcut{ if err != nil { return err } - return rt.Output(map[string]any{"suggestions": suggestTimeSlots(data)}) + suggestions, err := calendarSmartSuggestedSlots(data) + if err != nil { + return err + } + return rt.Output(map[string]any{"count": len(suggestions), "suggestions": suggestions, "complete": true}) }, } -// suggestTimeSlots flattens a list_suggested_event_times response -// (result.recommendEventTimes[]) into a clean {start,end,conflicts} list. Null -// entries in timeConflictAttendees are dropped so "conflicts" only appears when -// there is a real conflicting attendee. -func suggestTimeSlots(data map[string]any) []map[string]any { - out := []map[string]any{} - root, ok := data["result"].(map[string]any) - if !ok { - root = data - } - slots, _ := root["recommendEventTimes"].([]any) - for _, s := range slots { - sm, ok := s.(map[string]any) - if !ok { - continue - } - row := map[string]any{ - "start": sm["startTime"], - "end": sm["endTime"], - } - if raw, ok := sm["timeConflictAttendees"].([]any); ok { - conflicts := []any{} - for _, c := range raw { - if c != nil { - conflicts = append(conflicts, c) - } - } - if len(conflicts) > 0 { - row["conflicts"] = conflicts - } - } - out = append(out, row) - } - return out -} - func init() { + finalizeCalendarSmart(&SuggestTime, "严格校验的共同空闲建议时段") shortcut.Register(SuggestTime) } diff --git a/internal/shortcut/smart/today.go b/internal/shortcut/smart/today.go index 638f97b8..f9366c75 100644 --- a/internal/shortcut/smart/today.go +++ b/internal/shortcut/smart/today.go @@ -84,14 +84,16 @@ var Today = shortcut.Shortcut{ // Project each event to {title, start, end, location, eventId} via the // shared calendarProjectEvents (same output as +tomorrow/+week) instead // of dumping the raw 17-field event objects. - data, err := rt.CallMCPData("calendar", "list_calendar_events", toolArgs) + events, err := calendarSmartListAll(rt, toolArgs) if err != nil { return err } - return rt.Output(map[string]any{"events": calendarProjectEvents(data)}) + projected := calendarProjectEvents(events) + return rt.Output(map[string]any{"count": len(projected), "events": projected, "complete": true}) }, } func init() { + finalizeCalendarSmart(&Today, "完整翻页并严格校验的今日日程") shortcut.Register(Today) } diff --git a/internal/shortcut/smart/todo_done.go b/internal/shortcut/smart/todo_done.go index c9f21eb2..cd454b15 100644 --- a/internal/shortcut/smart/todo_done.go +++ b/internal/shortcut/smart/todo_done.go @@ -14,6 +14,7 @@ package smart import ( + "encoding/json" "fmt" "strings" @@ -21,7 +22,9 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + todoshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/todo" ) // TodoDone: mark one of MY todos complete by matching a keyword in its title. @@ -40,10 +43,11 @@ import ( // // dws todo +todo-done --task 周报 var TodoDone = shortcut.Shortcut{ - Service: "todo", - Command: "+todo-done", - Product: "todo", - Description: "按标题关键词把我的某条待办标记完成（自动定位 taskId）", + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+todo-done", + Product: "todo", + Description: "按标题关键词把我的某条待办标记完成（自动定位 taskId）", Intent: "当你只记得某条待办的标题关键词、想直接把它标记完成，却不想先翻列表复制 taskId 时使用；" + "内部先拉取你当前组织下作为执行人的待办列表，按标题(subject)包含关键词匹配：没匹配到会提示「没找到匹配待办」，" + "匹配到多条会列出候选(标题+taskId)让你写得更精确，唯一命中时才把它标记为已完成。这会真实修改待办完成状态。", @@ -61,6 +65,7 @@ var TodoDone = shortcut.Shortcut{ PrimaryCLIPath: "todo +todo-done", }, Description: "按标题关键词把我的某条待办标记完成（自动定位 taskId）", + Result: &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object","description":"已验证的完成结果","properties":{"taskId":{"type":"string","description":"已完成待办 taskId"},"subject":{"type":"string","description":"已完成待办标题"},"verified":{"type":"boolean","description":"是否完成详情读回核验"}},"required":["taskId","subject","verified"],"additionalProperties":false}`)}, Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -106,10 +111,20 @@ var TodoDone = shortcut.Shortcut{ // Step 3 — mark it done. taskId + isDone mirror helpers `todo task done` // (update_todo_done_status, isDone passed as a string). - return rt.CallMCP("update_todo_done_status", map[string]any{ + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "taskId": matches[0].taskID}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "update_todo_done_status", map[string]any{ "taskId": matches[0].taskID, "isDone": "true", }) + if err != nil { + return err + } + if err := todoshortcut.VerifyDoneStatus(rt, data, matches[0].taskID, true); err != nil { + return err + } + return rt.Output(map[string]any{"taskId": matches[0].taskID, "subject": matches[0].subject, "verified": true}) }, } diff --git a/internal/shortcut/smart/todo_shared.go b/internal/shortcut/smart/todo_shared.go index 81d4d8ef..6dfde1c9 100644 --- a/internal/shortcut/smart/todo_shared.go +++ b/internal/shortcut/smart/todo_shared.go @@ -14,8 +14,10 @@ package smart import ( + "fmt" "strconv" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -46,15 +48,79 @@ func shortcutListAllTodoCards(rt *shortcut.RuntimeContext, base map[string]any) params["pageNum"] = strconv.Itoa(page) params["pageSize"] = strconv.Itoa(todoPageSize) - data, err := rt.CallMCPData("todo", "get_user_todos_in_current_org", params) + data, err := rt.CallMCPReadData("todo", "get_user_todos_in_current_org", params) + if err != nil { + return nil, err + } + cards, hasMore, err := shortcutTodoCardsStrict(data) if err != nil { return nil, err } - cards := shortcutTodoCards(data) all = append(all, cards...) - if len(cards) < todoPageSize { - break + if !hasMore { + return all, nil } } - return all, nil + return nil, shortcutTodoResponseError("pagination_limit_reached", fmt.Sprintf("连续 %d 页仍返回 hasMore=true，拒绝把不完整列表当作完整结果", todoMaxPages)) +} + +func shortcutTodoCardsStrict(data map[string]any) ([]map[string]any, bool, error) { + if len(data) == 0 { + return nil, false, shortcutTodoResponseError("empty_tool_response", "服务返回空响应") + } + if raw, ok := data["success"]; ok { + success, valid := raw.(bool) + if !valid || !success { + return nil, false, shortcutTodoResponseError("remote_failure", "响应 success 不是明确的 true") + } + } + container := data + for depth := 0; depth < 5; depth++ { + if raw, ok := container["todoCards"]; ok { + items, valid := raw.([]any) + if !valid { + return nil, false, shortcutTodoResponseError("malformed_collection", "todoCards 不是数组") + } + rawMore, exists := container["hasMore"] + hasMore, valid := rawMore.(bool) + if !exists || !valid { + return nil, false, shortcutTodoResponseError("malformed_has_more", "响应缺少布尔 hasMore") + } + cards := make([]map[string]any, 0, len(items)) + for i, item := range items { + card, valid := item.(map[string]any) + if !valid { + return nil, false, shortcutTodoResponseError("malformed_item", fmt.Sprintf("todoCards 第 %d 项不是对象", i)) + } + if shortcutTodoTaskID(card) == "" { + return nil, false, shortcutTodoResponseError("missing_stable_id", fmt.Sprintf("todoCards 第 %d 项缺少稳定 taskId", i)) + } + cards = append(cards, card) + } + return cards, hasMore, nil + } + raw, ok := container["result"] + if !ok { + raw, ok = container["data"] + } + if !ok { + return nil, false, shortcutTodoResponseError("missing_collection", "响应缺少 todoCards 容器") + } + child, valid := raw.(map[string]any) + if !valid { + return nil, false, shortcutTodoResponseError("malformed_wrapper", "result/data 包装层不是对象") + } + container = child + } + return nil, false, shortcutTodoResponseError("missing_collection", "响应包装过深或缺少 todoCards") +} + +func shortcutTodoResponseError(reason, message string) error { + return apperrors.NewAPI(message, + apperrors.WithOperation("todo/get_user_todos_in_current_org"), + apperrors.WithOrigin("mcp"), + apperrors.WithFailureStage("response_validation"), + apperrors.WithRetryable(false), + apperrors.WithReason(reason), + ) } diff --git a/internal/shortcut/smart/todo_strict_test.go b/internal/shortcut/smart/todo_strict_test.go new file mode 100644 index 00000000..695cb0d9 --- /dev/null +++ b/internal/shortcut/smart/todo_strict_test.go @@ -0,0 +1,58 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package smart + +import ( + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" +) + +func TestCrossPlatformCoverageTodoSmartPagerRequiresHasMoreAndStableItems(t *testing.T) { + valid := map[string]any{"success": true, "result": map[string]any{"todoCards": []any{}, "hasMore": false, "page": float64(1), "size": float64(20)}} + items, hasMore, err := shortcutTodoCardsStrict(valid) + if err != nil || hasMore || len(items) != 0 { + t.Fatalf("valid empty page = %#v, %v, %v", items, hasMore, err) + } + for name, response := range map[string]map[string]any{ + "missing cards": {"success": true, "result": map[string]any{"hasMore": false}}, + "missing hasMore": {"success": true, "result": map[string]any{"todoCards": []any{}}}, + "bad element": {"success": true, "result": map[string]any{"todoCards": []any{"bad"}, "hasMore": false}}, + "missing id": {"success": true, "result": map[string]any{"todoCards": []any{map[string]any{"subject": "x"}}, "hasMore": false}}, + } { + t.Run(name, func(t *testing.T) { + if _, _, err := shortcutTodoCardsStrict(response); err == nil { + t.Fatalf("malformed response accepted: %#v", response) + } + }) + } +} + +func TestAllShortcutsTodoSmartContractsAndRelatedAlias(t *testing.T) { + if RelatedTasks.Command != "+get-related-tasks" || len(RelatedTasks.Aliases) != 1 || RelatedTasks.Aliases[0] != "+related-tasks" { + t.Fatalf("related command/alias = %q / %#v", RelatedTasks.Command, RelatedTasks.Aliases) + } + for _, item := range []struct { + name string + rollout output.RolloutState + result bool + }{ + {"related", RelatedTasks.OutputRollout, RelatedTasks.Contract.Result != nil}, + {"due-today", DueToday.OutputRollout, DueToday.Contract.Result != nil}, + {"assign", Assign.OutputRollout, Assign.Contract.Result != nil}, + {"assign-multi", AssignMulti.OutputRollout, AssignMulti.Contract.Result != nil}, + {"created", CreatedTodos.OutputRollout, CreatedTodos.Contract.Result != nil}, + {"overdue", Overdue.OutputRollout, Overdue.Contract.Result != nil}, + {"todo-done", TodoDone.OutputRollout, TodoDone.Contract.Result != nil}, + {"remind", Remind.OutputRollout, Remind.Contract.Result != nil}, + } { + if item.rollout != output.RolloutUnifiedActive || !item.result { + t.Errorf("%s missing unified Result contract", item.name) + } + } + if !strings.Contains(Assign.Intent, "创建") { + t.Fatal("legacy +assign semantics must remain create-and-assign") + } +} diff --git a/internal/shortcut/smart/tomorrow.go b/internal/shortcut/smart/tomorrow.go index b4eea779..ad5a1f3c 100644 --- a/internal/shortcut/smart/tomorrow.go +++ b/internal/shortcut/smart/tomorrow.go @@ -81,14 +81,16 @@ var Tomorrow = shortcut.Shortcut{ } // Same {title,start,end,location,eventId} projection as +today/+week. - data, err := rt.CallMCPData("calendar", "list_calendar_events", toolArgs) + events, err := calendarSmartListAll(rt, toolArgs) if err != nil { return err } - return rt.Output(map[string]any{"events": calendarProjectEvents(data)}) + projected := calendarProjectEvents(events) + return rt.Output(map[string]any{"count": len(projected), "events": projected, "complete": true}) }, } func init() { + finalizeCalendarSmart(&Tomorrow, "完整翻页并严格校验的明日日程") shortcut.Register(Tomorrow) } diff --git a/internal/shortcut/smart/week.go b/internal/shortcut/smart/week.go index afa4cccf..7950868d 100644 --- a/internal/shortcut/smart/week.go +++ b/internal/shortcut/smart/week.go @@ -98,16 +98,18 @@ var Week = shortcut.Shortcut{ "endTime": startOfNextWeek.UnixMilli(), } - data, err := rt.CallMCPData("calendar", "list_calendar_events", params) + events, err := calendarSmartListAll(rt, params) if err != nil { return err } // Same {title,start,end,location,eventId} projection as +today/+tomorrow. - return rt.Output(map[string]any{"events": calendarProjectEvents(data)}) + projected := calendarProjectEvents(events) + return rt.Output(map[string]any{"count": len(projected), "events": projected, "complete": true}) }, } func init() { + finalizeCalendarSmart(&Week, "完整翻页并严格校验的本周日程") shortcut.Register(Week) } diff --git a/internal/shortcut/todo/common.go b/internal/shortcut/todo/common.go new file mode 100644 index 00000000..177f7303 --- /dev/null +++ b/internal/shortcut/todo/common.go @@ -0,0 +1,347 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package todo + +import ( + "encoding/json" + "fmt" + "strconv" + "strings" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +const ( + todoPageSize = 20 + todoMaxPages = 40 +) + +func todoObjectResult(description string) *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"additionalProperties":true}`, + description, + )), + } +} + +func todoCollectionResult(collection, description string) *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"结果数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"待办结果条目","additionalProperties":true}}},"required":["count",%q],"additionalProperties":true}`, + description, collection, description, collection, + )), + } +} + +func todoPagedCollectionResult(collection, description string) *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, + DataSchema: json.RawMessage(fmt.Sprintf( + `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"结果数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"待办结果条目","additionalProperties":true}},"page":{"type":"integer","description":"当前页码；全量模式省略"},"size":{"type":"integer","description":"当前页大小；全量模式省略"},"hasMore":{"type":"boolean","description":"服务端是否仍有下一页；全量模式省略"},"complete":{"type":"boolean","description":"全量模式是否确认遍历耗尽"}},"required":["count",%q],"additionalProperties":false}`, + description, collection, description, collection, + )), + } +} + +func requireTodoResponse(data map[string]any, operation string) (map[string]any, error) { + if len(data) == 0 { + return nil, todoResponseError(operation, "empty_tool_response", "服务返回空响应，无法证明请求成功") + } + if raw, ok := data["success"]; ok { + success, valid := raw.(bool) + if !valid { + return nil, todoResponseError(operation, "malformed_success", "响应 success 字段不是布尔值") + } + if !success { + return nil, todoResponseError(operation, "remote_failure", "服务明确返回 success=false") + } + } + return data, nil +} + +func requireTodoWriteReceipt(data map[string]any, operation string) error { + data, err := requireTodoResponse(data, operation) + if err != nil { + return err + } + success, ok := data["success"].(bool) + if !ok || !success { + return todoResponseError(operation, "missing_success_receipt", "写响应没有明确的 success=true 回执") + } + return nil +} + +func requireTodoCollection(data map[string]any, operation string, keys ...string) ([]map[string]any, error) { + data, err := requireTodoResponse(data, operation) + if err != nil { + return nil, err + } + raw, found, err := findTodoCollection(data, keys, 0) + if err != nil { + return nil, todoResponseError(operation, "malformed_collection", err.Error()) + } + if !found { + return nil, todoResponseError(operation, "missing_collection", "响应缺少预期列表容器") + } + out := make([]map[string]any, 0, len(raw)) + for i, item := range raw { + m, ok := item.(map[string]any) + if !ok { + return nil, todoResponseError(operation, "malformed_item", fmt.Sprintf("列表第 %d 项不是对象", i)) + } + out = append(out, m) + } + return out, nil +} + +func todoHasMore(data map[string]any) (bool, error) { + return findTodoHasMore(data, 0) +} + +func findTodoHasMore(m map[string]any, depth int) (bool, error) { + if depth > 4 { + return false, todoResponseError("todo/pagination", "missing_has_more", "响应缺少 hasMore，无法证明分页已完成") + } + if raw, ok := m["hasMore"]; ok { + value, valid := raw.(bool) + if !valid { + return false, todoResponseError("todo/pagination", "malformed_has_more", "响应 hasMore 字段不是布尔值") + } + return value, nil + } + for _, key := range []string{"result", "data"} { + if raw, ok := m[key]; ok { + child, valid := raw.(map[string]any) + if !valid { + return false, todoResponseError("todo/pagination", "malformed_wrapper", key+" 包装层不是对象") + } + return findTodoHasMore(child, depth+1) + } + } + return false, todoResponseError("todo/pagination", "missing_has_more", "响应缺少 hasMore，无法证明分页已完成") +} + +func listAllTodoCards(rt *shortcut.RuntimeContext, base map[string]any, maxPages int) ([]map[string]any, error) { + all := make([]map[string]any, 0) + for page := 1; page <= maxPages; page++ { + params := make(map[string]any, len(base)+2) + for key, value := range base { + params[key] = value + } + params["pageNum"] = strconv.Itoa(page) + params["pageSize"] = strconv.Itoa(todoPageSize) + data, err := rt.CallMCPReadData("todo", "get_user_todos_in_current_org", params) + if err != nil { + return nil, err + } + pageItems, err := getMyTasksProjectStrict(data) + if err != nil { + return nil, err + } + hasMore, err := todoHasMore(data) + if err != nil { + return nil, err + } + all = append(all, pageItems...) + if !hasMore { + return all, nil + } + } + return nil, todoResponseError("todo/get_user_todos_in_current_org", "pagination_limit_reached", fmt.Sprintf("连续 %d 页仍返回 hasMore=true，拒绝把不完整结果当作完整结果", maxPages)) +} + +func findTodoCollection(m map[string]any, keys []string, depth int) ([]any, bool, error) { + if depth > 4 { + return nil, false, nil + } + for _, key := range keys { + if raw, ok := m[key]; ok { + arr, valid := raw.([]any) + if !valid { + return nil, false, fmt.Errorf("%s 容器不是数组", key) + } + return arr, true, nil + } + } + for _, key := range []string{"result", "data"} { + raw, ok := m[key] + if !ok { + continue + } + if arr, valid := raw.([]any); valid { + return arr, true, nil + } + child, valid := raw.(map[string]any) + if !valid { + return nil, false, fmt.Errorf("%s 包装层既不是对象也不是数组", key) + } + if arr, found, err := findTodoCollection(child, keys, depth+1); found || err != nil { + return arr, found, err + } + } + return nil, false, nil +} + +func requireTodoDetail(data map[string]any, operation, expectedTaskID string) (map[string]any, error) { + data, err := requireTodoResponse(data, operation) + if err != nil { + return nil, err + } + detail, found, err := findTodoObject(data, []string{"todoDetailModel", "todo", "task"}, 0) + if err != nil { + return nil, todoResponseError(operation, "malformed_detail", err.Error()) + } + if !found { + // Some deployments return the detail itself under result/data. + if result, ok := data["result"].(map[string]any); ok && todoStableString(result, "taskId", "todoId", "id") != "" { + detail, found = result, true + } else if todoStableString(data, "taskId", "todoId", "id") != "" { + detail, found = data, true + } + } + if !found || len(detail) == 0 { + return nil, todoResponseError(operation, "missing_detail", "响应缺少有效待办详情对象") + } + actual := todoStableString(detail, "taskId", "todoId", "id") + if actual == "" { + return nil, todoResponseError(operation, "missing_stable_id", "待办详情缺少稳定 taskId") + } + if expectedTaskID != "" && actual != expectedTaskID { + return nil, todoResponseError(operation, "identity_mismatch", "读回的 taskId 与请求不一致") + } + return detail, nil +} + +func findTodoObject(m map[string]any, keys []string, depth int) (map[string]any, bool, error) { + if depth > 4 { + return nil, false, nil + } + for _, key := range keys { + if raw, ok := m[key]; ok { + object, valid := raw.(map[string]any) + if !valid { + return nil, false, fmt.Errorf("%s 容器不是对象", key) + } + return object, true, nil + } + } + for _, key := range []string{"result", "data"} { + raw, ok := m[key] + if !ok { + continue + } + child, valid := raw.(map[string]any) + if !valid { + return nil, false, fmt.Errorf("%s 包装层不是对象", key) + } + if object, found, err := findTodoObject(child, keys, depth+1); found || err != nil { + return object, found, err + } + } + return nil, false, nil +} + +func todoCreatedTaskID(data map[string]any) string { + return findTodoStableString(data, []string{"taskId", "todoId", "id"}, 0) +} + +func findTodoStableString(m map[string]any, keys []string, depth int) string { + if depth > 5 { + return "" + } + if value := todoStableString(m, keys...); value != "" { + return value + } + for _, key := range []string{"result", "data", "todoDetailModel", "todo", "task"} { + if child, ok := m[key].(map[string]any); ok { + if value := findTodoStableString(child, keys, depth+1); value != "" { + return value + } + } + } + return "" +} + +func todoStableString(m map[string]any, keys ...string) string { + for _, key := range keys { + switch value := m[key].(type) { + case string: + if value = strings.TrimSpace(value); value != "" { + return value + } + case json.Number: + return value.String() + case float64: + if value == float64(int64(value)) { + return strconv.FormatInt(int64(value), 10) + } + case int: + return strconv.Itoa(value) + case int64: + return strconv.FormatInt(value, 10) + } + } + return "" +} + +func readTodoDetail(rt *shortcut.RuntimeContext, taskID string) (map[string]any, error) { + data, err := rt.CallMCPReadData("todo", "get_todo_detail", map[string]any{"taskId": taskID}) + if err != nil { + return nil, err + } + return requireTodoDetail(data, "todo/get_todo_detail", taskID) +} + +// VerifyCreatedTodo is shared by Todo-owned smart shortcuts that create a +// personal todo. It requires a terminal receipt, a stable taskId and a detail +// read-back bound to that exact ID. +func VerifyCreatedTodo(rt *shortcut.RuntimeContext, data map[string]any, operation, expectedSubject string) (string, map[string]any, error) { + if err := requireTodoWriteReceipt(data, operation); err != nil { + return "", nil, err + } + taskID := todoCreatedTaskID(data) + if taskID == "" { + return "", nil, todoResponseError(operation, "missing_stable_id", "创建响应缺少稳定 taskId；远端效果未知") + } + detail, err := readTodoDetail(rt, taskID) + if err != nil { + return "", nil, err + } + if subject, _ := detail["subject"].(string); expectedSubject != "" && subject != expectedSubject { + return "", nil, todoResponseError(operation, "verification_mismatch", "创建后读回的标题不一致") + } + return taskID, detail, nil +} + +// VerifyDoneStatus requires a terminal write receipt and verifies isDone on a +// detail read bound to the same taskId. +func VerifyDoneStatus(rt *shortcut.RuntimeContext, data map[string]any, taskID string, expected bool) error { + if err := requireTodoWriteReceipt(data, "todo/update_todo_done_status"); err != nil { + return err + } + detail, err := readTodoDetail(rt, taskID) + if err != nil { + return err + } + actual, ok := detail["isDone"].(bool) + if !ok || actual != expected { + return todoResponseError("todo/update_todo_done_status", "verification_mismatch", "写后读回 isDone 不一致或缺失") + } + return nil +} + +func todoResponseError(operation, reason, message string) error { + return apperrors.NewAPI(message, + apperrors.WithOperation(operation), + apperrors.WithOrigin("mcp"), + apperrors.WithFailureStage("response_validation"), + apperrors.WithRetryable(false), + apperrors.WithReason(reason), + ) +} diff --git a/internal/shortcut/todo/lifecycle.go b/internal/shortcut/todo/lifecycle.go new file mode 100644 index 00000000..8d7529bf --- /dev/null +++ b/internal/shortcut/todo/lifecycle.go @@ -0,0 +1,459 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package todo + +import ( + "encoding/json" + "fmt" + "strconv" + "strings" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +const todoCompositeReason = "Reviewed Todo Shortcut composite: the executable CLI owns strict response validation, pagination, write/read-back verification, output projection, and confirmation; no single MCP interface represents the complete command contract." + +func todoContract(command, description, useWhen string, result *contract.ResultSpec, examples ...string) corecmd.ContractDecl { + name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(command, "+"), "-", "_") + cliPath := "todo " + command + return corecmd.ContractDecl{ + Description: description, + Result: result, + Identity: contract.ToolIdentitySpec{ + ProductID: "todo", Name: name, CanonicalPath: "todo." + name, + CLIPath: cliPath, PrimaryCLIPath: cliPath, + }, + Interface: &contract.InterfaceSpec{Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: todoCompositeReason}, + Selection: contract.SelectionSpec{ + AgentSummary: description, + UseWhen: []string{useWhen}, + AvoidWhen: []string{"需要底层未公开参数或原始响应时改用对应原子命令"}, + Examples: examples, + }, + } +} + +func todoWriteSafety(idempotency string) contract.SafetySpec { + return contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: idempotency} +} + +func todoReadSafety() contract.SafetySpec { + return contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"} +} + +func parseTodoMillis(flag, value string) (int64, error) { + parsed, err := time.Parse(time.RFC3339, strings.TrimSpace(value)) + if err != nil { + return 0, apperrors.NewValidation(fmt.Sprintf("--%s 必须是 ISO8601 时间", flag)) + } + return parsed.UnixMilli(), nil +} + +func createTodo(rt *shortcut.RuntimeContext) error { + title := rt.Str("title") + executors := nonEmptyStrings(rt.StrSlice("executors")) + if title == "" || len(executors) == 0 { + return apperrors.NewValidation("--title 与至少一个 --executors 均为必填") + } + vo := map[string]any{"subject": title, "executorIds": executors} + if rt.Changed("due") { + millis, err := parseTodoMillis("due", rt.Str("due")) + if err != nil { + return err + } + vo["dueTime"] = millis + } + if rt.Changed("priority") { + priority := rt.Int("priority") + if priority != 10 && priority != 20 && priority != 30 && priority != 40 { + return apperrors.NewValidation("--priority 仅接受 10/20/30/40") + } + vo["priority"] = priority + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "create", "subject": title}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "create_personal_todo", map[string]any{"PersonalTodoCreateVO": vo}) + if err != nil { + return err + } + if err := requireTodoWriteReceipt(data, "todo/create_personal_todo"); err != nil { + return err + } + taskID := todoCreatedTaskID(data) + if taskID == "" { + return todoResponseError("todo/create_personal_todo", "missing_stable_id", "创建响应缺少稳定 taskId；远端效果未知") + } + detail, err := readTodoDetail(rt, taskID) + if err != nil { + return err + } + if subject, _ := detail["subject"].(string); subject != title { + return todoResponseError("todo/create_personal_todo", "verification_mismatch", "创建后读回的标题不一致") + } + return rt.Output(map[string]any{"taskId": taskID, "verified": true, "todo": detail}) +} + +var Create = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: "+create", Product: "todo", + Description: "创建待办并读回验证", Intent: "创建一条个人待办；只有取得稳定 taskId 且详情读回一致才报告成功。", + Risk: shortcut.RiskWrite, Safety: todoWriteSafety("non_idempotent"), + Contract: todoContract("+create", "创建待办并读回验证", "标题和执行人已确定，需要创建待办时使用", todoObjectResult("已验证的新建待办"), `dws todo +create --title "提交报告" --executors `), + Flags: []shortcut.Flag{ + {Name: "title", Type: shortcut.FlagString, Desc: "待办标题", Required: true}, + {Name: "executors", Type: shortcut.FlagStringSlice, Desc: "执行人 userId", Required: true}, + {Name: "due", Type: shortcut.FlagString, Desc: "截止时间（ISO8601）"}, + {Name: "priority", Type: shortcut.FlagInt, Desc: "优先级 10/20/30/40"}, + }, + Execute: createTodo, +} + +func updateTodo(rt *shortcut.RuntimeContext) error { + if !rt.Changed("title") && !rt.Changed("due") && !rt.Changed("priority") { + return apperrors.NewValidation("至少指定 --title、--due、--priority 之一") + } + taskID := rt.Str("task-id") + request := map[string]any{"taskId": taskID} + if rt.Changed("title") { + if rt.Str("title") == "" { + return apperrors.NewValidation("--title 不能为空") + } + request["subject"] = rt.Str("title") + } + if rt.Changed("due") { + millis, err := parseTodoMillis("due", rt.Str("due")) + if err != nil { + return err + } + request["dueTime"] = millis + } + if rt.Changed("priority") { + priority := rt.Int("priority") + if priority != 10 && priority != 20 && priority != 30 && priority != 40 { + return apperrors.NewValidation("--priority 仅接受 10/20/30/40") + } + request["priority"] = priority + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "operation": "update", "taskId": taskID}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "update_todo_task", map[string]any{"TodoUpdateRequest": request}) + if err != nil { + return err + } + if err := requireTodoWriteReceipt(data, "todo/update_todo_task"); err != nil { + return err + } + detail, err := readTodoDetail(rt, taskID) + if err != nil { + return err + } + for key, expected := range request { + if key == "taskId" { + continue + } + if fmt.Sprint(detail[key]) != fmt.Sprint(expected) { + return todoResponseError("todo/update_todo_task", "verification_mismatch", "更新后读回字段 "+key+" 不一致") + } + } + return rt.Output(map[string]any{"taskId": taskID, "verified": true, "todo": detail}) +} + +var Update = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: "+update", Product: "todo", + Description: "更新待办并读回验证", Intent: "按 taskId 修改标题、截止时间或优先级，并严格读回核验。", + Risk: shortcut.RiskWrite, Safety: todoWriteSafety("idempotent"), + Contract: todoContract("+update", "更新待办并读回验证", "已知 taskId 且需要修改待办字段时使用", todoObjectResult("已验证的更新结果"), `dws todo +update --task-id --title "新标题"`), + Flags: []shortcut.Flag{ + {Name: "task-id", Type: shortcut.FlagString, Desc: "待办 taskId", Required: true}, + {Name: "title", Type: shortcut.FlagString, Desc: "新标题"}, + {Name: "due", Type: shortcut.FlagString, Desc: "新截止时间（ISO8601）"}, + {Name: "priority", Type: shortcut.FlagInt, Desc: "新优先级 10/20/30/40"}, + }, + Execute: updateTodo, +} + +func setTodoDone(rt *shortcut.RuntimeContext, target bool) error { + taskID := rt.Str("task-id") + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "taskId": taskID, "isDone": target}) + } + before, err := readTodoDetail(rt, taskID) + if err != nil { + return err + } + current, ok := before["isDone"].(bool) + if !ok { + return todoResponseError("todo/get_todo_detail", "malformed_done_status", "待办详情缺少布尔 isDone，拒绝盲目写状态") + } + if current == target { + return rt.Output(map[string]any{"taskId": taskID, "isDone": target, "verified": true, "alreadyInTargetState": true}) + } + data, err := rt.CallMCPWriteDataStrict("todo", "update_todo_done_status", map[string]any{"taskId": taskID, "isDone": strconv.FormatBool(target)}) + if err != nil { + return err + } + if err := requireTodoWriteReceipt(data, "todo/update_todo_done_status"); err != nil { + return err + } + detail, err := readTodoDetail(rt, taskID) + if err != nil { + return err + } + done, ok := detail["isDone"].(bool) + if !ok || done != target { + return todoResponseError("todo/update_todo_done_status", "verification_mismatch", "完成状态读回不一致或缺失") + } + return rt.Output(map[string]any{"taskId": taskID, "isDone": target, "verified": true, "alreadyInTargetState": false}) +} + +func doneShortcut(command string, target bool) shortcut.Shortcut { + description := "完成待办并读回验证" + if !target { + description = "重新打开待办并读回验证" + } + return shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: command, Product: "todo", Description: description, Intent: description, + Risk: shortcut.RiskWrite, Safety: todoWriteSafety("idempotent"), + Contract: todoContract(command, description, "已知 taskId 且需要改变完成状态时使用", todoObjectResult("已验证的待办状态"), "dws todo "+command+" --task-id "), + Flags: []shortcut.Flag{{Name: "task-id", Type: shortcut.FlagString, Desc: "待办 taskId", Required: true}}, + Execute: func(rt *shortcut.RuntimeContext) error { return setTodoDone(rt, target) }, + } +} + +var Complete = doneShortcut("+complete", true) +var Reopen = doneShortcut("+reopen", false) + +var Search = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: "+search", Product: "todo", + Description: "搜索与我相关的全部待办", Intent: "分页遍历当前组织下与我相关的待办并按标题关键词匹配。", + Risk: shortcut.RiskRead, Safety: todoReadSafety(), + Contract: todoContract("+search", "搜索与我相关的全部待办", "需要按标题关键词跨全部分页搜索待办时使用", todoCollectionResult("todos", "待办搜索结果"), `dws todo +search --query "周报"`), + Flags: []shortcut.Flag{ + {Name: "query", Type: shortcut.FlagString, Desc: "标题关键词", Required: true}, + {Name: "status", Type: shortcut.FlagString, Enum: []string{"true", "false"}, Desc: "完成状态"}, + {Name: "max-pages", Type: shortcut.FlagInt, Default: "40", Desc: "最大遍历页数（1-40）"}, + }, + Execute: func(rt *shortcut.RuntimeContext) error { + query := strings.ToLower(rt.Str("query")) + if query == "" { + return apperrors.NewValidation("--query 不能为空") + } + maxPages := rt.Int("max-pages") + if maxPages < 1 || maxPages > todoMaxPages { + return apperrors.NewValidation("--max-pages 必须是 1 到 40") + } + base := map[string]any{"roleTypes": []string{"creator", "executor", "participant"}} + if rt.Changed("status") { + base["todoStatus"] = rt.Str("status") + } + cards, err := listAllTodoCards(rt, base, maxPages) + if err != nil { + return err + } + matches := make([]map[string]any, 0) + for _, card := range cards { + subject, ok := card["subject"].(string) + if !ok { + return todoResponseError("todo/+search", "malformed_subject", "待办条目缺少字符串 subject") + } + if strings.Contains(strings.ToLower(subject), query) { + matches = append(matches, card) + } + } + return rt.Output(map[string]any{"count": len(matches), "todos": matches, "complete": true}) + }, +} + +var Comment = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: "+comment", Product: "todo", + Description: "添加待办评论并读回验证", Intent: "向指定待办添加评论；取得稳定 commentId 并从评论列表读回才报告成功。", + Risk: shortcut.RiskWrite, Safety: todoWriteSafety("non_idempotent"), + Contract: todoContract("+comment", "添加待办评论并读回验证", "已知 taskId 且需要发表明确评论时使用", todoObjectResult("已验证的新评论"), `dws todo +comment --task-id --content "已处理"`), + Flags: []shortcut.Flag{ + {Name: "task-id", Type: shortcut.FlagString, Desc: "待办 taskId", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "评论内容", Required: true}, + }, + Execute: func(rt *shortcut.RuntimeContext) error { + taskID, content := rt.Str("task-id"), rt.Str("content") + if content == "" { + return apperrors.NewValidation("--content 不能为空") + } + if rt.DryRun() { + return rt.Output(map[string]any{"dryRun": true, "executed": false, "taskId": taskID}) + } + before, err := listAllTodoComments(rt, taskID) + if err != nil { + return err + } + beforeIDs := make(map[string]bool, len(before)) + for _, comment := range before { + beforeIDs[todoStableString(comment, "commentId", "id")] = true + } + data, err := rt.CallMCPWriteDataStrict("todo", "add_todo_comment", map[string]any{"taskId": taskID, "content": content}) + if err != nil { + return err + } + if err := requireTodoWriteReceipt(data, "todo/add_todo_comment"); err != nil { + return err + } + after, err := listAllTodoComments(rt, taskID) + if err != nil { + return err + } + matches := make([]map[string]any, 0, 1) + for _, comment := range after { + id := todoStableString(comment, "commentId", "id") + text, _ := comment["content"].(string) + if id != "" && !beforeIDs[id] && text == content { + matches = append(matches, comment) + } + } + if len(matches) != 1 { + return todoResponseError("todo/add_todo_comment", "verification_ambiguous", "评论写入后无法在完整列表中唯一识别新增评论") + } + commentID := todoStableString(matches[0], "commentId", "id") + return rt.Output(map[string]any{"taskId": taskID, "commentId": commentID, "content": content, "verified": true}) + }, +} + +func listAllTodoComments(rt *shortcut.RuntimeContext, taskID string) ([]map[string]any, error) { + all := make([]map[string]any, 0) + for page := 1; page <= todoMaxPages; page++ { + data, err := rt.CallMCPReadData("todo", "list_todo_comment", map[string]any{ + "taskId": taskID, "page": strconv.Itoa(page), "pageSize": strconv.Itoa(todoPageSize), + }) + if err != nil { + return nil, err + } + comments, err := listCommentProjectStrict(data) + if err != nil { + return nil, err + } + hasMore, err := todoHasMore(data) + if err != nil { + return nil, err + } + all = append(all, comments...) + if !hasMore { + return all, nil + } + } + return nil, todoResponseError("todo/list_todo_comment", "pagination_limit_reached", "评论列表达到 40 页仍未耗尽，拒绝把不完整列表用于写后验证") +} + +var Reminder = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", Command: "+reminder", Product: "todo", + Description: "设置或清除待办提醒（仅终端回执）", Intent: "设置或清除提醒；上游无提醒读接口，结果固定 verified=false。", + Risk: shortcut.RiskWrite, Safety: todoWriteSafety("unknown"), + Contract: todoContract("+reminder", "设置或清除待办提醒（仅终端回执）", "接受无法读回核验且需要设置/清除提醒时使用", &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}, + DataSchema: json.RawMessage(`{"type":"object","description":"提醒写入终端回执","properties":{"taskId":{"type":"string","description":"待办 taskId"},"action":{"type":"string","description":"set 或 clear"},"terminalReceipt":{"type":"boolean","description":"是否取得终端成功回执"},"verified":{"type":"boolean","description":"固定 false；上游无法读回提醒规则"}},"required":["taskId","action","terminalReceipt","verified"],"additionalProperties":false}`), + }, `dws todo +reminder --task-id --base-time dueTime --due-date-offset -30`), + Flags: []shortcut.Flag{ + {Name: "task-id", Type: shortcut.FlagString, Desc: "待办 taskId", Required: true}, + {Name: "clear", Type: shortcut.FlagBool, Desc: "清除全部提醒规则"}, + {Name: "base-time", Type: shortcut.FlagString, Enum: []string{"dueTime", "customTime"}, Desc: "提醒基准"}, + {Name: "due-date-offset", Type: shortcut.FlagInt, Desc: "相对截止时间的分钟偏移"}, + {Name: "at", Type: shortcut.FlagString, Desc: "customTime 的 ISO8601 时间"}, + }, + Execute: func(rt *shortcut.RuntimeContext) error { + taskID := rt.Str("task-id") + clear := rt.Bool("clear") + baseTime := rt.Str("base-time") + if clear == (baseTime != "") { + return apperrors.NewValidation("必须且只能选择 --clear 或 --base-time") + } + tool := "reset_todo_reminder" + params := map[string]any{"todoReminderUpdateRequest": map[string]any{"taskId": taskID, "reminderRules": []any{}}} + action := "clear" + if !clear { + request := map[string]any{"taskId": taskID, "baseTime": baseTime} + if baseTime == "dueTime" { + if !rt.Changed("due-date-offset") { + return apperrors.NewValidation("--base-time=dueTime 要求 --due-date-offset") + } + request["dueDateOffset"] = strconv.Itoa(rt.Int("due-date-offset")) + } else { + if !rt.Changed("at") { + return apperrors.NewValidation("--base-time=customTime 要求 --at") + } + millis, err := parseTodoMillis("at", rt.Str("at")) + if err != nil { + return err + } + request["reminderTimeStamp"] = millis + } + tool = "add_todo_reminder" + params = map[string]any{"todoReminderAddRequest": request} + action = "set" + } + if rt.DryRun() { + return rt.Output(map[string]any{"taskId": taskID, "action": action, "terminalReceipt": false, "verified": false, "dryRun": true}) + } + data, err := rt.CallMCPWriteDataStrict("todo", tool, params) + if err != nil { + return err + } + if err := requireTodoWriteReceipt(data, "todo/"+tool); err != nil { + return err + } + return rt.Output(map[string]any{"taskId": taskID, "action": action, "terminalReceipt": true, "verified": false}) + }, +} + +var UploadAttachment = shortcut.Shortcut{ + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+upload-attachment", + Product: "todo", + Description: "上传待办附件（当前请使用原子命令）", + Intent: "当前 Shortcut 运行时不能安全复用原子命令的带请求头上传事务，因此明确路由到 todo task add-attachment。", + Risk: shortcut.RiskWrite, + Safety: todoWriteSafety("unknown"), + Contract: todoContract( + "+upload-attachment", + "上传待办附件（当前请使用原子命令）", + "需要上传本地文件为待办附件时，使用公开的原子命令完成完整上传事务", + todoObjectResult("附件上传结果"), + `dws todo +upload-attachment --task-id --file-path ./report.pdf`, + ), + Flags: []shortcut.Flag{ + {Name: "task-id", Type: shortcut.FlagString, Desc: "待办 taskId", Required: true}, + {Name: "file-path", Type: shortcut.FlagString, Desc: "本地文件路径", Required: true}, + }, + Execute: func(*shortcut.RuntimeContext) error { + return apperrors.NewValidation("+upload-attachment 暂不复制原子上传事务；请使用 dws todo task add-attachment --task-id --file-path ") + }, +} + +func nonEmptyStrings(values []string) []string { + out := make([]string, 0, len(values)) + for _, value := range values { + if value = strings.TrimSpace(value); value != "" { + out = append(out, value) + } + } + return out +} + +func init() { + items := []*shortcut.Shortcut{&Create, &Update, &Complete, &Reopen, &Search, &Comment, &UploadAttachment, &Reminder} + for _, item := range items { + item.Contract.Selection.AgentSummary = item.Description + item.Contract.Selection.UseWhen = []string{item.Intent} + } + shortcut.Register(Create, Update, Complete, Reopen, Search, Comment, UploadAttachment, Reminder) +} diff --git a/internal/shortcut/todo/todo.go b/internal/shortcut/todo/todo.go index ac8981cd..9049ccea 100644 --- a/internal/shortcut/todo/todo.go +++ b/internal/shortcut/todo/todo.go @@ -22,6 +22,7 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) @@ -29,12 +30,13 @@ import ( // CreateSub maps helper `create_personal_sub_todo`. // GetMyTasks maps helper `get_user_todos_in_current_org`. var GetMyTasks = shortcut.Shortcut{ - Service: "todo", - Command: "+get-my-tasks", - Product: "todo", - Description: "查询当前组织下我的待办列表", - Intent: "当你想查看自己在当前组织下的待办清单、盘点未完成事项或按条件筛选任务时使用；可按完成状态、优先级、角色（创建者/执行者/参与者）和截止时间范围过滤并分页，返回匹配的待办列表。", - Risk: shortcut.RiskRead, + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+get-my-tasks", + Product: "todo", + Description: "查询当前组织下我的待办列表", + Intent: "当你想查看自己在当前组织下的待办清单、盘点未完成事项或按条件筛选任务时使用；可按完成状态、优先级、角色（创建者/执行者/参与者）和截止时间范围过滤并分页，返回匹配的待办列表。", + Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", @@ -48,6 +50,7 @@ var GetMyTasks = shortcut.Shortcut{ PrimaryCLIPath: "todo +get-my-tasks", }, Description: "查询当前组织下我的待办列表", + Result: todoPagedCollectionResult("todos", "当前组织下我的待办列表"), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -68,12 +71,22 @@ var GetMyTasks = shortcut.Shortcut{ {Name: "role-types", Type: shortcut.FlagStringSlice, Default: "executor", Desc: "角色类型: creator/executor/participant"}, {Name: "plan-finish-start", Type: shortcut.FlagInt, Desc: "截止时间范围开始（Unix 毫秒时间戳）"}, {Name: "plan-finish-end", Type: shortcut.FlagInt, Desc: "截止时间范围结束（Unix 毫秒时间戳）"}, + {Name: "all", Type: shortcut.FlagBool, Desc: "遍历全部分页；达到安全页数上限仍有下一页时失败"}, + {Name: "max-pages", Type: shortcut.FlagInt, Default: "40", Desc: "--all 的最大页数（1-40）"}, }, Tips: []string{`dws todo +get-my-tasks --status false --priority 40,30`}, Execute: func(rt *shortcut.RuntimeContext) error { + page, err := strconv.Atoi(rt.Str("page")) + if err != nil || page < 1 { + return todoResponseError("todo/+get-my-tasks", "invalid_page", "--page 必须是大于 0 的整数") + } + size, err := strconv.Atoi(rt.Str("size")) + if err != nil || size < 1 || size > 20 { + return todoResponseError("todo/+get-my-tasks", "invalid_page_size", "--size 必须是 1 到 20 的整数；后端已知不支持更大值") + } params := map[string]any{ - "pageNum": rt.Str("page"), - "pageSize": rt.Str("size"), + "pageNum": strconv.Itoa(page), + "pageSize": strconv.Itoa(size), } if rt.Changed("status") { params["todoStatus"] = rt.Str("status") @@ -81,9 +94,11 @@ var GetMyTasks = shortcut.Shortcut{ if rt.Changed("priority") { var ps []int for _, p := range rt.StrSlice("priority") { - if n, err := strconv.Atoi(p); err == nil { - ps = append(ps, n) + n, err := strconv.Atoi(p) + if err != nil || (n != 10 && n != 20 && n != 30 && n != 40) { + return todoResponseError("todo/+get-my-tasks", "invalid_priority", "--priority 仅接受 10/20/30/40") } + ps = append(ps, n) } if ps != nil { params["priorityList"] = ps @@ -94,21 +109,71 @@ var GetMyTasks = shortcut.Shortcut{ roles = []string{"executor"} } params["roleTypes"] = roles + for _, role := range roles { + if role != "creator" && role != "executor" && role != "participant" { + return todoResponseError("todo/+get-my-tasks", "invalid_role_type", "--role-types 仅接受 creator/executor/participant") + } + } if rt.Changed("plan-finish-start") { params["planFinishDateStart"] = rt.Int("plan-finish-start") } if rt.Changed("plan-finish-end") { params["planFinishDateEnd"] = rt.Int("plan-finish-end") } - data, err := rt.CallMCPData("todo", "get_user_todos_in_current_org", params) + if rt.Bool("all") { + maxPages := rt.Int("max-pages") + if maxPages < 1 || maxPages > todoMaxPages { + return todoResponseError("todo/+get-my-tasks", "invalid_page_limit", "--max-pages 必须是 1 到 40") + } + delete(params, "pageNum") + delete(params, "pageSize") + cards, err := listAllTodoCards(rt, params, maxPages) + if err != nil { + return err + } + return rt.Output(map[string]any{"count": len(cards), "todos": cards, "complete": true}) + } + data, err := rt.CallMCPReadData("todo", "get_user_todos_in_current_org", params) if err != nil { return err } - cards := getMyTasksProject(data) - return rt.Output(map[string]any{"count": len(cards), "todos": cards}) + cards, err := getMyTasksProjectStrict(data) + if err != nil { + return err + } + hasMore, err := todoHasMore(data) + if err != nil { + return err + } + return rt.Output(map[string]any{"count": len(cards), "todos": cards, "page": page, "size": size, "hasMore": hasMore}) }, } +func getMyTasksProjectStrict(data map[string]any) ([]map[string]any, error) { + raw, err := requireTodoCollection(data, "todo/get_user_todos_in_current_org", "todoCards") + if err != nil { + return nil, err + } + out := make([]map[string]any, 0, len(raw)) + for i, m := range raw { + if todoStableString(m, "taskId", "todoId", "id") == "" { + return nil, todoResponseError("todo/get_user_todos_in_current_org", "missing_stable_id", "待办列表第 "+strconv.Itoa(i)+" 项缺少稳定 taskId") + } + out = append(out, projectTodoCard(m)) + } + return out, nil +} + +func projectTodoCard(m map[string]any) map[string]any { + row := map[string]any{"taskId": todoStableString(m, "taskId", "todoId", "id")} + for _, k := range []string{"subject", "dueTime", "priority", "finalStatusStage", "creatorId"} { + if v, ok := m[k]; ok { + row[k] = v + } + } + return row +} + // getMyTasksProject reshapes get_user_todos_in_current_org into a clean todo // list (subject/taskId/dueTime/priority/done) — clean output projection. // The card list lives under result.todoCards; fields are probed defensively. @@ -142,12 +207,13 @@ func getMyTasksProject(data map[string]any) []map[string]any { // ListSub maps helper `list_sub_tasks`. var ListSub = shortcut.Shortcut{ - Service: "todo", - Command: "+list-sub", - Product: "todo", - Description: "查询子待办列表", - Intent: "当你已知某个待办任务 ID、想了解它被拆解出的所有子任务时使用；输入父任务 ID，返回其下的子待办列表。", - Risk: shortcut.RiskRead, + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+list-sub", + Product: "todo", + Description: "查询子待办列表", + Intent: "当你已知某个待办任务 ID、想了解它被拆解出的所有子任务时使用；输入父任务 ID，返回其下的子待办列表。", + Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", @@ -161,6 +227,7 @@ var ListSub = shortcut.Shortcut{ PrimaryCLIPath: "todo +list-sub", }, Description: "查询子待办列表", + Result: todoCollectionResult("subTasks", "指定父待办的子待办列表"), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -186,11 +253,37 @@ var ListSub = shortcut.Shortcut{ if err != nil { return err } - subs := listSubProject(data) + subs, err := listSubProjectStrict(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(subs), "subTasks": subs}) }, } +func listSubProjectStrict(data map[string]any) ([]map[string]any, error) { + raw, err := requireTodoCollection(data, "todo/list_sub_tasks", "list", "items", "subTasks", "subTaskList") + if err != nil { + return nil, err + } + out := make([]map[string]any, 0, len(raw)) + for i, m := range raw { + id := todoStableString(m, "taskId", "id", "subTaskId") + if id == "" { + return nil, todoResponseError("todo/list_sub_tasks", "missing_stable_id", "子待办列表第 "+strconv.Itoa(i)+" 项缺少稳定 taskId") + } + row := map[string]any{"taskId": id} + if v := listSubFirst(m, "subject", "title", "name", "content"); v != nil { + row["subject"] = v + } + if v := listSubFirst(m, "dueTime", "dueDate", "deadline"); v != nil { + row["dueTime"] = v + } + out = append(out, row) + } + return out, nil +} + // listSubProject reshapes list_sub_tasks into a clean sub-todo list // (subject/taskId/dueTime) — clean output projection. The list // container and field names are probed defensively across candidate keys. @@ -259,12 +352,13 @@ func listSubFirst(m map[string]any, keys ...string) any { // Complete maps helper `update_todo_done_status`. // Get maps helper `get_todo_detail`. var Get = shortcut.Shortcut{ - Service: "todo", - Command: "+get", - Product: "todo", - Description: "查询待办详情", - Intent: "当你已知某条待办的任务 ID、想查看它的完整信息（标题、执行者、截止时间、优先级、状态等）时使用；输入任务 ID，返回该待办的详细内容。", - Risk: shortcut.RiskRead, + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+get", + Product: "todo", + Description: "查询待办详情", + Intent: "当你已知某条待办的任务 ID、想查看它的完整信息（标题、执行者、截止时间、优先级、状态等）时使用；输入任务 ID，返回该待办的详细内容。", + Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", @@ -278,6 +372,7 @@ var Get = shortcut.Shortcut{ PrimaryCLIPath: "todo +get", }, Description: "查询待办详情", + Result: todoObjectResult("待办详情"), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -295,9 +390,11 @@ var Get = shortcut.Shortcut{ }, Tips: []string{`dws todo +get --task-id `}, Execute: func(rt *shortcut.RuntimeContext) error { - return rt.CallMCP("get_todo_detail", map[string]any{ - "taskId": rt.Str("task-id"), - }) + detail, err := readTodoDetail(rt, rt.Str("task-id")) + if err != nil { + return err + } + return rt.Output(detail) }, } @@ -309,12 +406,13 @@ var Get = shortcut.Shortcut{ // AddReminder maps helper `add_todo_reminder`. // ListAttachment maps helper `list_todo_attachment`. var ListAttachment = shortcut.Shortcut{ - Service: "todo", - Command: "+list-attachment", - Product: "todo", - Description: "查询待办任务的附件列表", - Intent: "当你想查看某条待办上挂了哪些附件、或需要拿到附件 ID 以便后续删除时使用；输入任务 ID，返回该待办的附件列表。", - Risk: shortcut.RiskRead, + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+list-attachment", + Product: "todo", + Description: "查询待办任务的附件列表", + Intent: "当你想查看某条待办上挂了哪些附件、或需要拿到附件 ID 以便后续删除时使用；输入任务 ID，返回该待办的附件列表。", + Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", @@ -328,6 +426,7 @@ var ListAttachment = shortcut.Shortcut{ PrimaryCLIPath: "todo +list-attachment", }, Description: "查询待办任务的附件列表", + Result: todoCollectionResult("attachments", "待办附件列表"), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -353,11 +452,36 @@ var ListAttachment = shortcut.Shortcut{ if err != nil { return err } - atts := listAttachmentProject(data) + atts, err := listAttachmentProjectStrict(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(atts), "attachments": atts}) }, } +func listAttachmentProjectStrict(data map[string]any) ([]map[string]any, error) { + raw, err := requireTodoCollection(data, "todo/list_todo_attachment", "list", "items", "attachments", "attachmentList") + if err != nil { + return nil, err + } + out := make([]map[string]any, 0, len(raw)) + for i, m := range raw { + id := todoStableString(m, "attachmentId", "id", "fileId", "dentryId") + if id == "" { + return nil, todoResponseError("todo/list_todo_attachment", "missing_stable_id", "附件列表第 "+strconv.Itoa(i)+" 项缺少稳定 ID") + } + row := map[string]any{"attachmentId": id} + for _, pair := range [][2]string{{"fileName", "name"}, {"fileSize", "size"}, {"fileType", "type"}} { + if v := listAttachmentFirst(m, pair[0], pair[1]); v != nil { + row[pair[0]] = v + } + } + out = append(out, row) + } + return out, nil +} + // listAttachmentProject reshapes list_todo_attachment into a clean attachment // list (attachmentId/fileName/fileSize/fileType) — output-projection fidelity // for clean output. The list container and field names are probed defensively across @@ -428,12 +552,13 @@ func listAttachmentFirst(m map[string]any, keys ...string) any { // AddComment maps helper `add_todo_comment`. // ListComment maps helper `list_todo_comment`. var ListComment = shortcut.Shortcut{ - Service: "todo", - Command: "+list-comment", - Product: "todo", - Description: "查询待办评论列表", - Intent: "当你想查看某条待办下的讨论记录、了解协作沟通历史或获取评论 ID 以便删除时使用；输入任务 ID 并可分页，返回该待办的评论列表。", - Risk: shortcut.RiskRead, + OutputRollout: output.RolloutUnifiedActive, + Service: "todo", + Command: "+list-comment", + Product: "todo", + Description: "查询待办评论列表", + Intent: "当你想查看某条待办下的讨论记录、了解协作沟通历史或获取评论 ID 以便删除时使用；输入任务 ID 并可分页，返回该待办的评论列表。", + Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", @@ -447,6 +572,7 @@ var ListComment = shortcut.Shortcut{ PrimaryCLIPath: "todo +list-comment", }, Description: "查询待办评论列表", + Result: todoCollectionResult("comments", "待办评论列表"), Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", @@ -466,19 +592,52 @@ var ListComment = shortcut.Shortcut{ }, Tips: []string{`dws todo +list-comment --task-id `}, Execute: func(rt *shortcut.RuntimeContext) error { + page, err := strconv.Atoi(rt.Str("page")) + if err != nil || page < 1 { + return todoResponseError("todo/+list-comment", "invalid_page", "--page 必须是大于 0 的整数") + } + size, err := strconv.Atoi(rt.Str("size")) + if err != nil || size < 1 || size > todoPageSize { + return todoResponseError("todo/+list-comment", "invalid_page_size", "--size 必须是 1 到 20 的整数") + } data, err := rt.CallMCPData("todo", "list_todo_comment", map[string]any{ "taskId": rt.Str("task-id"), - "page": rt.Str("page"), - "pageSize": rt.Str("size"), + "page": strconv.Itoa(page), + "pageSize": strconv.Itoa(size), }) if err != nil { return err } - comments := listCommentProject(data) + comments, err := listCommentProjectStrict(data) + if err != nil { + return err + } return rt.Output(map[string]any{"count": len(comments), "comments": comments}) }, } +func listCommentProjectStrict(data map[string]any) ([]map[string]any, error) { + raw, err := requireTodoCollection(data, "todo/list_todo_comment", "list", "items", "comments", "commentList") + if err != nil { + return nil, err + } + out := make([]map[string]any, 0, len(raw)) + for i, m := range raw { + id := todoStableString(m, "commentId", "id") + if id == "" { + return nil, todoResponseError("todo/list_todo_comment", "missing_stable_id", "评论列表第 "+strconv.Itoa(i)+" 项缺少稳定 commentId") + } + row := map[string]any{"commentId": id} + for _, pair := range [][2]string{{"content", "text"}, {"creatorId", "userId"}, {"createTime", "createdTime"}} { + if v := listCommentFirst(m, pair[0], pair[1]); v != nil { + row[pair[0]] = v + } + } + out = append(out, row) + } + return out, nil +} + // listCommentProject reshapes list_todo_comment into a clean comment list // (commentId/content/creatorId/createTime) — clean output projection. // The list container and field names are probed defensively across diff --git a/internal/shortcut/todo/todo_contract_test.go b/internal/shortcut/todo/todo_contract_test.go new file mode 100644 index 00000000..567afcc9 --- /dev/null +++ b/internal/shortcut/todo/todo_contract_test.go @@ -0,0 +1,72 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package todo + +import ( + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" +) + +func TestCrossPlatformCoverageTodoStrictCollectionsDistinguishEmptyFromMalformed(t *testing.T) { + empty := map[string]any{"success": true, "result": map[string]any{"todoCards": []any{}, "hasMore": false, "page": float64(1), "size": float64(20)}} + items, err := getMyTasksProjectStrict(empty) + if err != nil || len(items) != 0 { + t.Fatalf("explicit empty todoCards = %#v, %v; want legal empty", items, err) + } + if _, err := getMyTasksProjectStrict(map[string]any{"success": true, "result": map[string]any{"hasMore": false}}); err == nil || !strings.Contains(err.Error(), "列表容器") { + t.Fatalf("missing collection error = %v", err) + } + if _, err := getMyTasksProjectStrict(map[string]any{"success": true, "result": map[string]any{"todoCards": []any{"bad"}, "hasMore": false}}); err == nil || !strings.Contains(err.Error(), "不是对象") { + t.Fatalf("malformed item error = %v", err) + } + if _, err := getMyTasksProjectStrict(map[string]any{"success": true, "result": map[string]any{"todoCards": []any{map[string]any{"subject": "missing id"}}, "hasMore": false}}); err == nil || !strings.Contains(err.Error(), "taskId") { + t.Fatalf("missing taskId error = %v", err) + } +} + +func TestCrossPlatformCoverageTodoDetailBindsRequestedTaskID(t *testing.T) { + response := map[string]any{"success": true, "result": map[string]any{"todoDetailModel": map[string]any{"taskId": "task-a", "subject": "A"}}} + detail, err := requireTodoDetail(response, "todo/get_todo_detail", "task-a") + if err != nil || detail["subject"] != "A" { + t.Fatalf("detail = %#v, %v", detail, err) + } + if _, err := requireTodoDetail(response, "todo/get_todo_detail", "task-b"); err == nil || !strings.Contains(err.Error(), "不一致") { + t.Fatalf("identity mismatch error = %v", err) + } + if _, err := requireTodoDetail(map[string]any{"success": true, "result": map[string]any{}}, "todo/get_todo_detail", "task-a"); err == nil { + t.Fatal("missing todoDetailModel unexpectedly accepted") + } +} + +func TestAllShortcutsTodoLifecycleContractsAreComplete(t *testing.T) { + for _, item := range []struct { + name string + rollout output.RolloutState + result bool + safety string + }{ + {"create", Create.OutputRollout, Create.Contract.Result != nil, Create.Safety.Confirmation}, + {"update", Update.OutputRollout, Update.Contract.Result != nil, Update.Safety.Confirmation}, + {"complete", Complete.OutputRollout, Complete.Contract.Result != nil, Complete.Safety.Confirmation}, + {"reopen", Reopen.OutputRollout, Reopen.Contract.Result != nil, Reopen.Safety.Confirmation}, + {"search", Search.OutputRollout, Search.Contract.Result != nil, Search.Safety.Confirmation}, + {"comment", Comment.OutputRollout, Comment.Contract.Result != nil, Comment.Safety.Confirmation}, + {"upload-attachment", UploadAttachment.OutputRollout, UploadAttachment.Contract.Result != nil, UploadAttachment.Safety.Confirmation}, + {"reminder", Reminder.OutputRollout, Reminder.Contract.Result != nil, Reminder.Safety.Confirmation}, + {"get-my-tasks", GetMyTasks.OutputRollout, GetMyTasks.Contract.Result != nil, GetMyTasks.Safety.Confirmation}, + {"list-sub", ListSub.OutputRollout, ListSub.Contract.Result != nil, ListSub.Safety.Confirmation}, + {"get", Get.OutputRollout, Get.Contract.Result != nil, Get.Safety.Confirmation}, + {"list-attachment", ListAttachment.OutputRollout, ListAttachment.Contract.Result != nil, ListAttachment.Safety.Confirmation}, + {"list-comment", ListComment.OutputRollout, ListComment.Contract.Result != nil, ListComment.Safety.Confirmation}, + } { + if item.rollout != output.RolloutUnifiedActive || !item.result || item.safety == "" { + t.Errorf("%s contract incomplete: rollout=%q result=%v safety=%q", item.name, item.rollout, item.result, item.safety) + } + } + if text := string(Reminder.Contract.Result.DataSchema); !strings.Contains(text, `"verified"`) || !strings.Contains(Reminder.Intent, "verified=false") { + t.Fatalf("reminder must publish terminal-only verification boundary: %s / %s", text, Reminder.Intent) + } +} diff --git a/scripts/dev/calendar-todo-shortcut-e2e.py b/scripts/dev/calendar-todo-shortcut-e2e.py new file mode 100755 index 00000000..1494669b --- /dev/null +++ b/scripts/dev/calendar-todo-shortcut-e2e.py @@ -0,0 +1,659 @@ +#!/usr/bin/env python3 +"""PII-safe live E2E for the public Calendar and Todo shortcut surfaces. + +Raw command responses are kept in memory. The script prints only stable +capability labels and reason codes; it never prints identities, resource IDs, +titles, room names, response bodies, traces, or local paths. +""" + +from __future__ import annotations + +import json +import os +import secrets +import subprocess +import sys +import tempfile +from datetime import datetime, timedelta +from pathlib import Path +from typing import Any, Callable + + +ROOT = Path(__file__).resolve().parents[2] +BIN = Path(os.environ.get("DWS_E2E_BIN", ROOT / "dws")) + +CALENDAR_CASES = { + "+agenda", "+attendee-list", "+book", "+book-list", "+book-search", + "+cancel-event", "+conflicts", "+create", "+free", "+free-slots", + "+freebusy", "+get", "+invite", "+my-free", "+next-event", + "+reschedule", "+room-find", "+room-groups", "+room-search", "+rsvp", + "+search-event", "+suggest-time", "+suggestion", "+today", "+tomorrow", + "+update", "+week", +} +TODO_CASES = { + "+assign", "+assign-multi", "+comment", "+complete", "+create", + "+created-todos", "+due-today", "+get", "+get-my-tasks", + "+get-related-tasks", "+list-attachment", "+list-comment", "+list-sub", + "+overdue", "+remind", "+reminder", "+reopen", "+search", + "+todo-done", "+update", +} + + +class E2EError(RuntimeError): + def __init__(self, reason: str): + super().__init__(reason) + self.reason = reason + + +results: dict[str, tuple[str, str]] = {} + + +def record(product: str, command: str, status: str, reason: str = "") -> None: + results[f"{product}/{command}"] = (status, reason) + + +def run_case(product: str, command: str, fn: Callable[[], None], *, blocked_ok: bool = False) -> None: + try: + fn() + except E2EError as exc: + record(product, command, "BLOCKED" if blocked_ok else "FAIL", exc.reason) + except Exception: + record(product, command, "FAIL", "unexpected_exception") + else: + record(product, command, "PASS") + + +def invoke(args: list[str], *, confirm: bool = False, expect_success: bool = True) -> Any: + command = [str(BIN), *args] + if "--format" not in command: + command.extend(["--format", "json"]) + try: + proc = subprocess.run( + command, + cwd=ROOT, + input="yes\n" if confirm else "", + text=True, + capture_output=True, + timeout=90, + env={**os.environ, "NO_COLOR": "1"}, + ) + except subprocess.TimeoutExpired as exc: + raise E2EError("command_timeout") from exc + if expect_success and proc.returncode != 0: + failure = None + for raw in (proc.stdout, proc.stderr): + try: + candidate = json.loads(raw) + except (json.JSONDecodeError, TypeError): + continue + if isinstance(candidate, dict) and isinstance(candidate.get("error"), dict): + failure = candidate["error"] + break + if failure: + code = failure.get("upstream_code") or failure.get("server_error_code") + if isinstance(code, (str, int)) and str(code).isalnum(): + raise E2EError("upstream_" + str(code)) + subtype = failure.get("subtype") or failure.get("reason") + if isinstance(subtype, str) and subtype.replace("_", "").isalnum(): + raise E2EError(subtype) + raise E2EError("nonzero_exit") + if not expect_success: + if proc.returncode == 0: + raise E2EError("unexpected_zero_exit") + return None + if not proc.stdout.strip(): + raise E2EError("empty_stdout") + try: + payload = json.loads(proc.stdout) + except json.JSONDecodeError as exc: + raise E2EError("malformed_json") from exc + if isinstance(payload, dict) and "ok" in payload: + if payload.get("ok") is not True or payload.get("outcome") != "success": + raise E2EError("non_success_envelope") + if "data" not in payload: + raise E2EError("missing_data") + return payload + + +def business(payload: Any) -> Any: + if isinstance(payload, dict) and payload.get("ok") is True and "data" in payload: + return payload["data"] + return payload + + +def dictionaries(value: Any): + if isinstance(value, dict): + yield value + for nested in value.values(): + yield from dictionaries(nested) + elif isinstance(value, list): + for nested in value: + yield from dictionaries(nested) + + +def stable_string(value: Any, keys: tuple[str, ...]) -> str: + for item in dictionaries(value): + for key in keys: + candidate = item.get(key) + if isinstance(candidate, str) and candidate.strip(): + return candidate.strip() + raise E2EError("missing_stable_id") + + +def explicit_list(value: Any, key: str) -> list[Any]: + for item in dictionaries(value): + if key not in item: + continue + candidate = item[key] + if not isinstance(candidate, list): + raise E2EError("malformed_collection") + if any(not isinstance(entry, dict) or not entry for entry in candidate): + raise E2EError("malformed_collection_item") + return candidate + raise E2EError("missing_collection") + + +def require_boolean(value: Any, key: str, expected: bool | None = None) -> bool: + for item in dictionaries(value): + if key in item: + candidate = item[key] + if not isinstance(candidate, bool): + raise E2EError("malformed_boolean") + if expected is not None and candidate is not expected: + raise E2EError("boolean_mismatch") + return candidate + raise E2EError("missing_boolean") + + +def list_contains_id(value: Any, key: str, expected: str, id_keys: tuple[str, ...]) -> None: + rows = explicit_list(business(value), key) + for row in rows: + for id_key in id_keys: + if row.get(id_key) == expected: + return + raise E2EError("fixture_not_found") + + +def list_contains_text(value: Any, key: str, expected: str, text_keys: tuple[str, ...]) -> None: + rows = explicit_list(business(value), key) + for row in rows: + if any(row.get(text_key) == expected for text_key in text_keys): + return + raise E2EError("fixture_not_found") + + +def iso(value: datetime) -> str: + return value.isoformat(timespec="seconds") + + +def cleanup_calendar(event_ids: list[str]) -> int: + failures = 0 + for event_id in reversed(event_ids): + try: + invoke(["calendar", "event", "delete", "--id", event_id, "--yes"]) + except E2EError: + failures += 1 + return failures + + +def cleanup_todo(task_ids: list[str]) -> int: + failures = 0 + for task_id in reversed(task_ids): + try: + invoke(["todo", "task", "delete", "--task-id", task_id, "--yes"]) + except E2EError: + failures += 1 + return failures + + +def audit_cleanup(marker: str, start: datetime, end: datetime) -> None: + cursor = "" + for _ in range(20): + args = [ + "calendar", "+agenda", "--start", iso(start), "--end", iso(end), + "--limit", "100", + ] + if cursor: + args.extend(["--cursor", cursor]) + payload = invoke(args) + for event in explicit_list(business(payload), "events"): + title = event.get("summary") + status = str(event.get("status", "")).lower() + if isinstance(title, str) and title.startswith(marker) and status not in {"cancelled", "canceled", "deleted"}: + raise E2EError("calendar_cleanup_residual") + pagination = (payload.get("meta") or {}).get("pagination") if isinstance(payload, dict) else None + if not isinstance(pagination, dict): + raise E2EError("cleanup_pagination_missing") + if pagination.get("endpoint_exhausted") is True: + break + next_cursor = pagination.get("next_token") + if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor: + raise E2EError("cleanup_pagination_stalled") + cursor = next_cursor + else: + raise E2EError("cleanup_page_limit") + + todos = explicit_list(business(invoke(["todo", "+search", "--query", marker])), "todos") + if any(isinstance(item.get("subject"), str) and item["subject"].startswith(marker) for item in todos): + raise E2EError("todo_cleanup_residual") + + +def main() -> int: + if not BIN.is_file(): + print("FAIL preflight binary_missing") + return 1 + + marker = "DWS-E2E-" + secrets.token_hex(6).upper() + profile = business(invoke(["contact", "+me"])) + self_id = stable_string(profile, ("userId",)) + self_name = stable_string(profile, ("name",)) + + now = datetime.now().astimezone().replace(microsecond=0) + event_start = now + timedelta(minutes=45) + event_end = event_start + timedelta(minutes=40) + overlap_start = event_start + timedelta(minutes=10) + overlap_end = event_end + timedelta(minutes=10) + tomorrow = (now + timedelta(days=1)).replace(hour=15, minute=0, second=0) + tomorrow_end = tomorrow + timedelta(minutes=30) + room_start = (now + timedelta(days=60)).replace(hour=15, minute=0, second=0) + room_end = room_start + timedelta(minutes=30) + today_start = now.replace(hour=0, minute=0, second=0) + today_end = today_start + timedelta(days=1) + week_end = now + timedelta(days=7) + + event_ids: list[str] = [] + task_ids: list[str] = [] + primary_event = "" + overlap_event = "" + book_event = "" + primary_task = "" + primary_task_title = marker + "-TODO-UPD" + + try: + def create_primary_event() -> None: + nonlocal primary_event + payload = invoke([ + "calendar", "+create", "--title", marker + "-CAL-A", + "--start", iso(event_start), "--end", iso(event_end), + "--attendees", self_id, + ], confirm=True) + primary_event = stable_string(business(payload), ("eventId",)) + event_ids.append(primary_event) + require_boolean(business(payload), "verified", True) + run_case("calendar", "+create", create_primary_event) + if not primary_event: + raise E2EError("calendar_fixture_create_failed") + + def create_overlap() -> None: + nonlocal overlap_event + payload = invoke([ + "calendar", "+create", "--title", marker + "-CAL-B", + "--start", iso(overlap_start), "--end", iso(overlap_end), + ], confirm=True) + overlap_event = stable_string(business(payload), ("eventId",)) + event_ids.append(overlap_event) + create_overlap() + + run_case("calendar", "+get", lambda: stable_string( + business(invoke(["calendar", "+get", "--event", primary_event])), ("eventId",) + )) + + def update_event() -> None: + payload = invoke([ + "calendar", "+update", "--event", primary_event, + "--title", marker + "-CAL-A-UPD", + ], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("calendar", "+update", update_event) + + def agenda() -> None: + payload = invoke([ + "calendar", "+agenda", "--start", iso(today_start), + "--end", iso(today_end), "--limit", "100", + ]) + list_contains_id(payload, "events", primary_event, ("eventId", "id")) + run_case("calendar", "+agenda", agenda) + + def search_event() -> None: + payload = invoke([ + "calendar", "+search-event", "--query", marker, + "--start", iso(today_start), "--end", iso(today_end), "--limit", "100", + ]) + list_contains_id(payload, "events", primary_event, ("eventId", "id")) + run_case("calendar", "+search-event", search_event) + + def attendee_list() -> None: + payload = invoke(["calendar", "+attendee-list", "--event", primary_event]) + rows = explicit_list(business(payload), "attendees") + if not any(row.get("self") is True for row in rows): + raise E2EError("self_attendee_not_found") + run_case("calendar", "+attendee-list", attendee_list) + + def rsvp() -> None: + payload = invoke([ + "calendar", "+rsvp", "--event", primary_event, "--status", "accept", + ], confirm=True) + require_boolean(business(payload), "success", True) + run_case("calendar", "+rsvp", rsvp, blocked_ok=True) + + def invite() -> None: + payload = invoke([ + "calendar", "+invite", "--event", overlap_event, "--with", self_name, + ], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("calendar", "+invite", invite) + + def conflicts() -> None: + payload = invoke(["calendar", "+conflicts"]) + rows = explicit_list(business(payload), "conflicts") + if not rows: + raise E2EError("known_overlap_not_reported") + run_case("calendar", "+conflicts", conflicts) + + run_case("calendar", "+today", lambda: list_contains_id( + invoke(["calendar", "+today"]), "events", primary_event, ("eventId", "id") + )) + run_case("calendar", "+week", lambda: list_contains_id( + invoke(["calendar", "+week"]), "events", primary_event, ("eventId", "id") + )) + + def next_event() -> None: + payload = business(invoke(["calendar", "+next-event"])) + if not isinstance(payload, dict) or not isinstance(payload.get("event"), dict): + raise E2EError("missing_next_event") + run_case("calendar", "+next-event", next_event) + + def free_slots() -> None: + payload = business(invoke(["calendar", "+free-slots", "--from", "0", "--to", "24"])) + explicit_list(payload, "freeSlots") + require_boolean(payload, "complete", True) + run_case("calendar", "+free-slots", free_slots) + + def freebusy() -> None: + payload = business(invoke([ + "calendar", "+freebusy", "--users", self_id, + "--start", iso(event_start - timedelta(minutes=5)), + "--end", iso(event_end + timedelta(minutes=5)), + ])) + explicit_list(payload, "busy") + run_case("calendar", "+freebusy", freebusy) + + run_case("calendar", "+free", lambda: explicit_list(business(invoke([ + "calendar", "+free", "--who", self_name, + "--start", iso(event_start - timedelta(minutes=5)), + "--end", iso(event_end + timedelta(minutes=5)), + ])), "busy")) + + def my_free() -> None: + payload = business(invoke([ + "calendar", "+my-free", "--start", iso(event_start - timedelta(minutes=5)), + "--end", iso(event_end + timedelta(minutes=5)), + ])) + require_boolean(payload, "free") + run_case("calendar", "+my-free", my_free) + + run_case("calendar", "+suggestion", lambda: explicit_list(business(invoke([ + "calendar", "+suggestion", "--users", self_id, "--duration", "30", + "--start", iso(room_start), "--end", iso(room_start + timedelta(hours=4)), + ])), "suggestions")) + run_case("calendar", "+suggest-time", lambda: explicit_list(business(invoke([ + "calendar", "+suggest-time", "--with", self_name, "--duration", "30", + "--start", iso(room_start), "--end", iso(room_start + timedelta(hours=4)), + ])), "suggestions")) + + def book() -> None: + nonlocal book_event + payload = invoke([ + "calendar", "+book", "--title", marker + "-CAL-TOMORROW", + "--start", iso(tomorrow), "--end", iso(tomorrow_end), "--with", self_name, + ], confirm=True) + book_event = stable_string(business(payload), ("eventId", "id")) + event_ids.append(book_event) + require_boolean(business(payload), "verified", True) + run_case("calendar", "+book", book) + if book_event: + run_case("calendar", "+tomorrow", lambda: list_contains_id( + invoke(["calendar", "+tomorrow"]), "events", book_event, ("eventId", "id") + )) + + def reschedule() -> None: + payload = invoke([ + "calendar", "+reschedule", "--event", book_event, + "--start", iso(tomorrow + timedelta(hours=1)), + "--end", iso(tomorrow_end + timedelta(hours=1)), + ], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("calendar", "+reschedule", reschedule) + + def cancel_event() -> None: + payload = business(invoke(["calendar", "+cancel-event", "--event", book_event], confirm=True)) + require_boolean(payload, "verified", True) + tombstone = business(invoke(["calendar", "+get", "--event", book_event])) + status = stable_string(tombstone, ("status", "eventStatus", "event_status")).lower() + if status not in {"cancelled", "canceled", "deleted"}: + raise E2EError("delete_tombstone_missing") + event_ids.remove(book_event) + run_case("calendar", "+cancel-event", cancel_event) + else: + for command in ("+tomorrow", "+reschedule", "+cancel-event"): + record("calendar", command, "BLOCKED", "book_fixture_unavailable") + + run_case("calendar", "+room-groups", lambda: explicit_list( + business(invoke(["calendar", "+room-groups", "--page", "0", "--limit", "20"])), + "groups", + ), blocked_ok=True) + + room_payload: Any = None + def room_find() -> None: + nonlocal room_payload + room_payload = invoke([ + "calendar", "+room-find", "--start", iso(room_start), "--end", iso(room_end), + "--page", "0", "--limit", "100", + ]) + rows = explicit_list(business(room_payload), "rooms") + if not rows: + raise E2EError("safe_room_fixture_empty") + run_case("calendar", "+room-find", room_find, blocked_ok=True) + + room_name = "" + if room_payload is not None: + try: + room_name = stable_string(explicit_list(business(room_payload), "rooms"), ("roomName", "name")) + except E2EError: + room_name = "" + if room_name: + run_case("calendar", "+room-search", lambda: explicit_list( + business(invoke(["calendar", "+room-search", "--room-name", room_name])), "rooms" + ), blocked_ok=True) + else: + try: + explicit_list( + business(invoke(["calendar", "+room-search", "--room-name", marker])), + "rooms", + ) + except E2EError as exc: + record("calendar", "+room-search", "FAIL", exc.reason) + else: + record("calendar", "+room-search", "BLOCKED", "nonempty_room_fixture_unavailable") + + def book_list() -> None: + payload = business(invoke(["calendar", "+book-list"])) + rows = explicit_list(payload, "calendars") + if not rows: + raise E2EError("calendar_book_fixture_empty") + run_case("calendar", "+book-list", book_list) + + book_list_payload = invoke(["calendar", "+book-list"]) + try: + book_name = stable_string(explicit_list(business(book_list_payload), "calendars"), ("name", "summary", "title")) + run_case("calendar", "+book-search", lambda: explicit_list( + business(invoke(["calendar", "+book-search", "--query", book_name])), "calendars" + )) + except E2EError as exc: + record("calendar", "+book-search", "FAIL", exc.reason) + + def create_primary_todo() -> None: + nonlocal primary_task + payload = invoke([ + "todo", "+create", "--title", marker + "-TODO", + "--executors", self_id, "--due", iso(now + timedelta(hours=3)), + "--priority", "20", + ], confirm=True) + primary_task = stable_string(business(payload), ("taskId",)) + task_ids.append(primary_task) + require_boolean(business(payload), "verified", True) + run_case("todo", "+create", create_primary_todo) + if not primary_task: + raise E2EError("todo_fixture_create_failed") + + run_case("todo", "+get", lambda: stable_string( + business(invoke(["todo", "+get", "--task-id", primary_task])), ("taskId",) + )) + + def update_todo() -> None: + payload = invoke([ + "todo", "+update", "--task-id", primary_task, + "--title", primary_task_title, "--priority", "30", + ], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("todo", "+update", update_todo) + + run_case("todo", "+get-my-tasks", lambda: list_contains_id( + invoke(["todo", "+get-my-tasks", "--all", "--max-pages", "40"]), + "todos", primary_task, ("taskId", "id") + )) + run_case("todo", "+get-related-tasks", lambda: list_contains_id( + invoke(["todo", "+get-related-tasks"]), "tasks", primary_task, ("taskId", "id") + )) + run_case("todo", "+search", lambda: list_contains_id( + invoke(["todo", "+search", "--query", marker]), "todos", primary_task, ("taskId", "id") + )) + run_case("todo", "+created-todos", lambda: list_contains_id( + invoke(["todo", "+created-todos"]), "created", primary_task, ("taskId", "id") + )) + run_case("todo", "+due-today", lambda: list_contains_id( + invoke(["todo", "+due-today"]), "tasks", primary_task, ("taskId", "id") + )) + + def add_comment() -> None: + payload = invoke([ + "todo", "+comment", "--task-id", primary_task, "--content", marker + "-COMMENT", + ], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("todo", "+comment", add_comment) + run_case("todo", "+list-comment", lambda: explicit_list( + business(invoke(["todo", "+list-comment", "--task-id", primary_task])), "comments" + )) + + def reminder() -> None: + first = invoke([ + "todo", "+reminder", "--task-id", primary_task, + "--base-time", "dueTime", "--due-date-offset", "-30", + ], confirm=True) + require_boolean(business(first), "terminalReceipt", True) + require_boolean(business(first), "verified", False) + second = invoke([ + "todo", "+reminder", "--task-id", primary_task, "--clear", + ], confirm=True) + require_boolean(business(second), "terminalReceipt", True) + run_case("todo", "+reminder", reminder) + + def create_sub_fixture() -> None: + payload = invoke([ + "todo", "task", "create-sub", "--parent-id", primary_task, + "--title", marker + "-SUB", "--executors", self_id, + ], confirm=True) + task_ids.append(stable_string(business(payload), ("taskId", "id"))) + create_sub_fixture() + run_case("todo", "+list-sub", lambda: explicit_list( + business(invoke(["todo", "+list-sub", "--task-id", primary_task])), "subTasks" + )) + + with tempfile.TemporaryDirectory(prefix="dws-ct-e2e-") as tmp: + attachment = Path(tmp) / "fixture.txt" + attachment.write_text(marker + "\n", encoding="utf-8") + invoke([ + "todo", "task", "add-attachment", "--task-id", primary_task, + "--file-path", str(attachment), + ], confirm=True) + run_case("todo", "+list-attachment", lambda: explicit_list( + business(invoke(["todo", "+list-attachment", "--task-id", primary_task])), "attachments" + )) + + def complete() -> None: + payload = invoke(["todo", "+complete", "--task-id", primary_task], confirm=True) + require_boolean(business(payload), "verified", True) + require_boolean(business(payload), "isDone", True) + run_case("todo", "+complete", complete) + + def reopen() -> None: + payload = invoke(["todo", "+reopen", "--task-id", primary_task], confirm=True) + require_boolean(business(payload), "verified", True) + require_boolean(business(payload), "isDone", False) + run_case("todo", "+reopen", reopen) + + def assigned(command: str, args: list[str]) -> None: + payload = invoke(["todo", command, *args], confirm=True) + task_id = stable_string(business(payload), ("taskId",)) + task_ids.append(task_id) + require_boolean(business(payload), "verified", True) + + run_case("todo", "+assign", lambda: assigned( + "+assign", ["--task", marker + "-ASSIGN", "--to", self_name, "--due", iso(now + timedelta(hours=4))] + )) + run_case("todo", "+assign-multi", lambda: assigned( + "+assign-multi", ["--task", marker + "-ASSIGN-MULTI", "--to", self_name] + )) + run_case("todo", "+remind", lambda: assigned( + "+remind", ["--task", marker + "-REMIND", "--at", iso(now + timedelta(hours=5))] + )) + + overdue_task = stable_string(business(invoke([ + "todo", "+create", "--title", marker + "-OVERDUE", "--executors", self_id, + "--due", iso(now - timedelta(hours=2)), + ], confirm=True)), ("taskId",)) + task_ids.append(overdue_task) + run_case("todo", "+overdue", lambda: list_contains_id( + invoke(["todo", "+overdue"]), "overdue", overdue_task, ("taskId", "id") + )) + + def todo_done() -> None: + payload = invoke(["todo", "+todo-done", "--task", primary_task_title], confirm=True) + require_boolean(business(payload), "verified", True) + run_case("todo", "+todo-done", todo_done) + + invoke(["todo", "+upload-attachment", "--task-id", primary_task, "--file-path", "fixture"], expect_success=False) + + except E2EError as exc: + record("preflight", "flow", "FAIL", exc.reason) + finally: + cleanup_failures = cleanup_calendar(event_ids) + cleanup_todo(task_ids) + try: + audit_cleanup(marker, now - timedelta(days=1), now + timedelta(days=70)) + except E2EError as exc: + record("cleanup", "resource-audit", "FAIL", exc.reason) + else: + if cleanup_failures: + record("cleanup", "resource-audit", "FAIL", "cleanup_command_failed") + else: + record("cleanup", "resource-audit", "PASS") + + for command in sorted(CALENDAR_CASES): + results.setdefault(f"calendar/{command}", ("FAIL", "case_not_executed")) + for command in sorted(TODO_CASES): + results.setdefault(f"todo/{command}", ("FAIL", "case_not_executed")) + + failed = False + for label in sorted(results): + status, reason = results[label] + if status == "FAIL": + failed = True + suffix = f" {reason}" if reason else "" + print(f"{status} {label}{suffix}") + counts = {status: sum(1 for value in results.values() if value[0] == status) for status in ("PASS", "BLOCKED", "FAIL")} + print(f"SUMMARY pass={counts['PASS']} blocked={counts['BLOCKED']} fail={counts['FAIL']}") + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/gen_shortcut_public_catalog.py b/scripts/gen_shortcut_public_catalog.py index 2bdd2820..0b37827d 100644 --- a/scripts/gen_shortcut_public_catalog.py +++ b/scripts/gen_shortcut_public_catalog.py @@ -25,6 +25,8 @@ SEMANTIC_PATHS = [ ROOT / "internal" / "shortcut" / "semantic_catalog_minutes.json", ROOT / "internal" / "shortcut" / "semantic_catalog_drive.json", ROOT / "internal" / "shortcut" / "semantic_catalog_wiki.json", + ROOT / "internal" / "shortcut" / "semantic_catalog_calendar.json", + ROOT / "internal" / "shortcut" / "semantic_catalog_todo.json", ] diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index 210215b5..e935f590 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -45,7 +45,7 @@ cli_version: ">=1.0.15" |---|---:|---| | `aitable` | 92 | `dingtalk-aitable` | | `attendance` | 19 | `dingtalk-misc` | -| `calendar` | 20 | `dingtalk-calendar` | +| `calendar` | 27 | `dingtalk-calendar` | | `chat` | 98 | `dingtalk-chat` | | `contact` | 14 | `dingtalk-contact` | | `devapp` | 19 | `dingtalk-misc` | @@ -57,7 +57,7 @@ cli_version: ">=1.0.15" | `oa` | 7 | `dingtalk-misc` | | `report` | 2 | `dingtalk-misc` | | `sheet` | 2 | `dingtalk-misc` | -| `todo` | 11 | `dingtalk-todo` | +| `todo` | 21 | `dingtalk-todo` | | `wiki` | 20 | `dingtalk-wiki` | diff --git a/skills/multi/dingtalk-calendar/SKILL.md b/skills/multi/dingtalk-calendar/SKILL.md index 14af9235..a06431bd 100644 --- a/skills/multi/dingtalk-calendar/SKILL.md +++ b/skills/multi/dingtalk-calendar/SKILL.md @@ -38,6 +38,7 @@ metadata: | `dws calendar +my-free` | read | 查我自己在某时间段的忙闲（默认今天，无需输入姓名） | | `dws calendar +next-event` | read | 查看接下来最近的一个日程（默认扫描未来 7 天） | | `dws calendar +reschedule` | write | 改一个已有日程的时间（只动开始/结束时间，其他字段不变） | +| `dws calendar +room-find` | read | 按时间段搜索可用会议室（不传时间默认当前起 1 小时） | | `dws calendar +room-groups` | read | 会议室分组列表 | | `dws calendar +room-search` | read | 按名称模糊搜索会议室（不检查可用性） | | `dws calendar +suggest-time` | read | 按姓名解析多位参与者，推荐大家都有空的可开会时间段（自动解析 userId） | diff --git a/skills/multi/dingtalk-todo/SKILL.md b/skills/multi/dingtalk-todo/SKILL.md index afb8d6d4..ab19e5b5 100644 --- a/skills/multi/dingtalk-todo/SKILL.md +++ b/skills/multi/dingtalk-todo/SKILL.md @@ -26,15 +26,22 @@ metadata: |---|---|---| | `dws todo +assign` | write | 按姓名给某人创建并指派一条待办（自动解析 userId） | | `dws todo +assign-multi` | write | 把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId） | +| `dws todo +comment` | write | 添加待办评论并读回验证 | +| `dws todo +create` | write | 创建待办并读回验证 | | `dws todo +created-todos` | read | 列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的） | +| `dws todo +due-today` | read | 列出我今天到期的待办 | | `dws todo +get` | read | 查询待办详情 | | `dws todo +get-my-tasks` | read | 查询当前组织下我的待办列表 | +| `dws todo +get-related-tasks` | read | 一次性列出与我相关的全部待办（我作为创建人/执行人/参与人三种角色的并集，按 taskId 去重） | | `dws todo +list-attachment` | read | 查询待办任务的附件列表 | | `dws todo +list-comment` | read | 查询待办评论列表 | | `dws todo +list-sub` | read | 查询子待办列表 | | `dws todo +overdue` | read | 列出我已过期未完成的待办 | | `dws todo +remind` | write | 给自己创建一条带可选截止时间的待办 | +| `dws todo +reminder` | write | 设置或清除待办提醒（仅终端回执） | +| `dws todo +search` | read | 搜索与我相关的全部待办 | | `dws todo +todo-done` | write | 按标题关键词把我的某条待办标记完成（自动定位 taskId） | +| `dws todo +update` | write | 更新待办并读回验证 | ## 意图表 From 5947016cc11e5b40e9e43b93c18d97a1e87d34b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=89=8D=E6=B4=A5?= Date: Mon, 17 Aug 2026 16:09:08 +0800 Subject: [PATCH 181/250] feat(chat): support bot group message replies --- .changes/928-chat-bot-group-reply.md | 5 + internal/app/schema_contract_test.go | 14 +++ internal/helpers/chat.go | 62 ++++++++++-- internal/helpers/chat_coverage_more_test.go | 94 +++++++++++++++++++ skills/mono/references/products/chat.md | 19 ++-- skills/multi/dingtalk-chat/SKILL.md | 2 +- skills/multi/dingtalk-chat/references/chat.md | 4 +- .../dingtalk-chat/references/chat/chat-bot.md | 17 +++- 8 files changed, 194 insertions(+), 23 deletions(-) create mode 100644 .changes/928-chat-bot-group-reply.md diff --git a/.changes/928-chat-bot-group-reply.md b/.changes/928-chat-bot-group-reply.md new file mode 100644 index 00000000..18f19049 --- /dev/null +++ b/.changes/928-chat-bot-group-reply.md @@ -0,0 +1,5 @@ +--- +category: Added +--- + +- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message. diff --git a/internal/app/schema_contract_test.go b/internal/app/schema_contract_test.go index 8a83b1ab..b1330000 100644 --- a/internal/app/schema_contract_test.go +++ b/internal/app/schema_contract_test.go @@ -400,6 +400,7 @@ func schemaContractPayloadForBoundCanonicals(t *testing.T, root *cobra.Command, func TestChatSchemaSeparatesSendAndReply(t *testing.T) { snapshot := schemaContractPayloadForBoundCanonicals(t, NewRootCommand(), "chat.send_personal_message", + "chat.send_robot_message", "chat.reply_personal_message", ) @@ -418,6 +419,19 @@ func TestChatSchemaSeparatesSendAndReply(t *testing.T) { if _, exists := snapshot.Tools["chat.upload_conversation_file"]; exists { t.Fatal("downlined chat file upload must not be advertised in Schema") } + + botReply := snapshot.Tools["chat.send_robot_message"] + botParams := schemaContractMap(botReply["parameters"]) + if got := schemaContractString(botParams["reply"]["property"]); got != "referenceOpenMessageId" { + t.Fatalf("bot --reply property = %q", got) + } + if got := schemaContractString(botParams["ref-sender"]["property"]); got != "srcMsgSendOpenDingTalkId" { + t.Fatalf("bot --ref-sender property = %q", got) + } + if got, ok := botParams["title"]["required"].(bool); !ok || got { + t.Fatalf("bot --title required = %#v, want false for conditional Markdown input", botParams["title"]["required"]) + } + assertSchemaContractConstraintGroup(t, botReply, "require_together", []string{"reply", "ref-sender"}) } func TestCalendarAttendeeDeleteSchemaMatchesRuntimeGate(t *testing.T) { diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index bd52518f..b2cbdf17 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -3413,10 +3413,11 @@ func newChatCommand() *cobra.Command { chatMessageSendByBotCmd := &cobra.Command{ Use: "send-by-bot", Short: "机器人发送消息（--conversation-id 群聊 / --users 单聊）", - Long: `群聊：传 --conversation-id 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --conversation-id 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。 + Long: `群聊：传 --conversation-id 指定群；单聊：传 --users 或 --open-dingtalk-ids 指定用户列表，与 --conversation-id 只能选其一，不能同时指定。省略 --msg-type 时发送 Markdown；图片使用 --msg-type image --image-url；本地文件使用 --msg-type file --file-path，CLI 完成上传后发送。机器人引用回复仅支持群聊 Markdown，同时传 --reply（原消息 openMessageId）和 --ref-sender（原消息发送者 openDingTalkId）；回复可省略 --title，CLI 会从正文生成标题。 ⚠️ 重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。`, Example: ` dws chat message send-by-bot --robot-code --conversation-id --title "日报" --text "## 今日完成..." + dws chat message send-by-bot --robot-code --conversation-id --reply --ref-sender --text "收到" dws chat message send-by-bot --robot-code --conversation-id --msg-type image --image-url "https://example.com/image.png" dws chat message send-by-bot --robot-code --conversation-id --msg-type file --file-path ./report.pdf dws chat message send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报" @@ -3433,10 +3434,17 @@ func newChatCommand() *cobra.Command { text := mustGetFlag(cmd, "text") imageURL := strings.TrimSpace(mustGetFlag(cmd, "image-url")) filePath := mustGetFlag(cmd, "file-path") + referenceOpenMessageID := strings.TrimSpace(mustGetFlag(cmd, "reply")) + refSender := strings.TrimSpace(mustGetFlag(cmd, "ref-sender")) + replyChanged := cmd.Flags().Changed("reply") + refSenderChanged := cmd.Flags().Changed("ref-sender") if err := validateRequiredFlags(cmd, "robot-code"); err != nil { return err } + if replyChanged != refSenderChanged || (replyChanged && (referenceOpenMessageID == "" || refSender == "")) { + return fmt.Errorf("--reply and --ref-sender must be specified together") + } if msgType == "" { if imageURL != "" { return fmt.Errorf("--msg-type image is required when using --image-url") @@ -3448,8 +3456,17 @@ func newChatCommand() *cobra.Command { } switch msgType { case "markdown": - if err := validateRequiredFlags(cmd, "title", "text"); err != nil { - return err + if referenceOpenMessageID != "" { + if err := validateRequiredFlags(cmd, "text"); err != nil { + return err + } + if title == "" { + title = sanitizeTitleFromText(text) + } + } else { + if err := validateRequiredFlags(cmd, "title", "text"); err != nil { + return err + } } case "image": if imageURL == "" { @@ -3475,6 +3492,22 @@ func newChatCommand() *cobra.Command { return fmt.Errorf("--conversation-id or --users/--open-dingtalk-ids is required") } + if referenceOpenMessageID != "" { + if chatID == "" { + return fmt.Errorf("--reply and --ref-sender are only supported with --conversation-id") + } + if msgType != "markdown" { + return fmt.Errorf("--reply and --ref-sender only support Markdown group messages") + } + if !isOpenDingTalkID(refSender) { + resolved, err := resolveOpenDingTalkID(cmd.Context(), refSender) + if err != nil { + return err + } + refSender = resolved + } + } + userIDs := splitCommaList(usersStr) openDingTalkIDs := splitCommaList(openDingtalkIdsStr) fileURL := "" @@ -3540,6 +3573,10 @@ func newChatCommand() *cobra.Command { toolArgs["msgKey"] = "sampleMarkdownDX" } toolArgs["openConversationId"] = chatID + if referenceOpenMessageID != "" { + toolArgs["referenceOpenMessageId"] = referenceOpenMessageID + toolArgs["srcMsgSendOpenDingTalkId"] = refSender + } if len(atUserIds) > 0 { toolArgs["atUserIds"] = atUserIds } @@ -3586,17 +3623,20 @@ func newChatCommand() *cobra.Command { CLIPath: "chat message send-by-bot", PrimaryCLIPath: "chat message send-by-bot", }, - Description: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊", + Description: "以应用机器人身份发送 Markdown、图片或文件群消息、群聊引用回复或批量单聊", Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", Reason: "命令包含多个 RPC、条件分派或本地 HTTP/文件步骤，不能绑定为单一 interface_ref", }, Selection: contract.SelectionSpec{ - AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息或批量单聊", - UseWhen: []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时"}, + AgentSummary: "以应用机器人身份发送 Markdown、图片或文件群消息、群聊引用回复或批量单聊", + UseWhen: []string{"已有 robotCode 且需要机器人身份投递 Markdown、图片或文件时", "需要机器人在群聊中引用回复一条已有消息时"}, AvoidWhen: []string{"个人身份发送或自定义 Webhook 告警不要使用"}, - Examples: []string{"dws chat message send-by-bot --robot-code --group --title \"日报\" --text \"今日进展\""}, + Examples: []string{ + "dws chat message send-by-bot --robot-code --group --title \"日报\" --text \"今日进展\"", + "dws chat message send-by-bot --robot-code --group --reply --ref-sender --text \"收到\"", + }, }, // Keep title/text required_when out of Schema: the runtime switch above // enforces Markdown inputs, while adding it breaks merge-base compatibility. @@ -3605,6 +3645,8 @@ func newChatCommand() *cobra.Command { {Name: "msg-type", RequiredWhen: "image-url or file-path is provided", Enum: []string{"markdown", "image", "file"}}, {Name: "image-url", RequiredWhen: "msg-type is image"}, {Name: "file-path", RequiredWhen: "msg-type is file"}, + {Name: "reply", Property: "referenceOpenMessageId", RequiredWhen: "ref-sender is provided", InterfaceType: "string"}, + {Name: "ref-sender", Property: "srcMsgSendOpenDingTalkId", RequiredWhen: "reply is provided", InterfaceType: "string"}, }, }, }) @@ -4768,7 +4810,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendByBotCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时必填）") chatMessageSendByBotCmd.Flags().String("users", "", "用户 userId 列表，逗号分隔，最多20个（单聊时必填）") chatMessageSendByBotCmd.Flags().String("msg-type", "", "消息类型: markdown/image/file（省略时为 markdown；图片使用 image --image-url；本地文件使用 file --file-path）") - chatMessageSendByBotCmd.Flags().String("title", "", "Markdown 消息标题（发送 Markdown 时必填）") + chatMessageSendByBotCmd.Flags().String("title", "", "Markdown 消息标题（发送普通 Markdown 时必填；引用回复省略时从正文生成）") chatMessageSendByBotCmd.Flags().String("text", "", "Markdown 消息内容（发送 Markdown 时必填；稳定换行用空行，转义形式写 \\n\\n，不要只写 \\n）") chatMessageSendByBotCmd.Flags().String("image-url", "", "公网图片 URL（msgType=image 时必填）") chatMessageSendByBotCmd.Flags().String("file-path", "", "本地文件路径（msgType=file 时直接上传并按 file 消息发送）") @@ -4776,9 +4818,13 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendByBotCmd.Flags().String("open-dingtalk-ids", "", "用户 openDingtalkId 列表，逗号分隔（单聊时可替代 --users，可选）") chatMessageSendByBotCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingtalkId 列表，逗号分隔（仅群聊时生效，可选）") chatMessageSendByBotCmd.Flags().Bool("at-all", false, "@所有人（可选），服务端接收字符串 true/false") + chatMessageSendByBotCmd.Flags().String("reply", "", "被引用消息的 openMessageId（仅群聊 Markdown；必须与 --ref-sender 同时使用）") + chatMessageSendByBotCmd.Flags().String("ref-sender", "", "被引用消息发送者的 openDingTalkId（仅群聊 Markdown；必须与 --reply 同时使用）") + chatMessageSendByBotCmd.MarkFlagsRequiredTogether("reply", "ref-sender") cli.AnnotateRuntimeConstraints(chatMessageSendByBotCmd, cli.RuntimeSchemaConstraints{ MutuallyExclusive: [][]string{{"group", "users"}}, RequireOneOf: [][]string{{"group", "users"}}, + RequireTogether: [][]string{{"reply", "ref-sender"}}, }) cli.AnnotateRuntimeFlagFormat(chatMessageSendByBotCmd, "file-path", "file-path") diff --git a/internal/helpers/chat_coverage_more_test.go b/internal/helpers/chat_coverage_more_test.go index 3c9f1ad0..532aa64e 100644 --- a/internal/helpers/chat_coverage_more_test.go +++ b/internal/helpers/chat_coverage_more_test.go @@ -446,6 +446,100 @@ func TestCrossPlatformCoverageChatBotRichMediaCoverage(t *testing.T) { if caller.tool != "batch_send_robot_msg_to_users" || caller.args["msgType"] != "sampleMarkdownDX" { t.Fatalf("direct markdown call = %s %#v", caller.tool, caller.args) } + if _, exists := caller.args["referenceOpenMessageId"]; exists { + t.Fatalf("ordinary direct message unexpectedly contains reply fields: %#v", caller.args) + } + }) + + t.Run("group Markdown reference reply", func(t *testing.T) { + const senderOpenDingTalkID = "DAAAAAAAAAAAiE" + caller := &scriptedToolCaller{} + if err := runChatCoverageCommand(t, caller, + "message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group", + "--reply", "message-id", "--ref-sender", senderOpenDingTalkID, + "--text", "received", + ); err != nil { + t.Fatal(err) + } + if caller.tool != "send_robot_group_message" || + caller.args["referenceOpenMessageId"] != "message-id" || + caller.args["srcMsgSendOpenDingTalkId"] != senderOpenDingTalkID || + caller.args["title"] != "received" { + t.Fatalf("group reference reply call = %s %#v", caller.tool, caller.args) + } + }) + + t.Run("group reference reply resolves sender user ID", func(t *testing.T) { + caller := &scriptedToolCaller{steps: []scriptedToolStep{ + {text: `{"result":[{"userId":"sender-user","openDingTalkId":"D-sender"}]}`}, + {text: `{}`}, + }} + if err := runChatCoverageCommand(t, caller, + "message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group", + "--reply", "message-id", "--ref-sender", "sender-user", + "--title", "reply", "--text", "received", + ); err != nil { + t.Fatal(err) + } + if caller.tool != "send_robot_group_message" || caller.args["srcMsgSendOpenDingTalkId"] != "D-sender" { + t.Fatalf("resolved group reference reply = %s %#v", caller.tool, caller.args) + } + }) + + t.Run("direct RunE enforces paired reply flags", func(t *testing.T) { + err := runChatCoverageDirect(t, []string{"message", "send-by-bot"}, map[string]string{ + "robot-code": "robot", + "conversation-id": "group", + "reply": "message-id", + "title": "reply", + "text": "received", + }) + if err == nil || !strings.Contains(err.Error(), "must be specified together") { + t.Fatalf("direct RunE paired reply flags error = %v", err) + } + }) + + for _, tc := range []struct { + name string + args []string + want string + }{ + {name: "reply requires sender", args: []string{"--reply", "message-id"}, want: "ref-sender"}, + {name: "sender requires reply", args: []string{"--ref-sender", "D-sender"}, want: "reply"}, + {name: "paired reply flags reject empty values", args: []string{"--reply=", "--ref-sender="}, want: "specified together"}, + } { + t.Run(tc.name, func(t *testing.T) { + args := []string{ + "message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group", + "--title", "reply", "--text", "received", + } + err := runChatCoverageCommand(t, &scriptedToolCaller{}, append(args, tc.args...)...) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("paired reply flags error = %v, want %q", err, tc.want) + } + }) + } + + t.Run("reference reply is group only", func(t *testing.T) { + err := runChatCoverageCommand(t, &scriptedToolCaller{}, + "message", "send-by-bot", "--robot-code", "robot", "--users", "user", + "--reply", "message-id", "--ref-sender", "D-sender", + "--title", "reply", "--text", "received", + ) + if err == nil || !strings.Contains(err.Error(), "only supported with --conversation-id") { + t.Fatalf("direct reference reply error = %v", err) + } + }) + + t.Run("reference reply rejects rich media", func(t *testing.T) { + err := runChatCoverageCommand(t, &scriptedToolCaller{}, + "message", "send-by-bot", "--robot-code", "robot", "--conversation-id", "group", + "--reply", "message-id", "--ref-sender", "D-sender", + "--msg-type", "image", "--image-url", "https://example.test/image.png", + ) + if err == nil || !strings.Contains(err.Error(), "only support Markdown") { + t.Fatalf("rich-media reference reply error = %v", err) + } }) t.Run("direct image", func(t *testing.T) { diff --git a/skills/mono/references/products/chat.md b/skills/mono/references/products/chat.md index 7dae1b1e..24b322b9 100644 --- a/skills/mono/references/products/chat.md +++ b/skills/mono/references/products/chat.md @@ -738,7 +738,7 @@ Flags: **重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。** -群聊传 --group；单聊可传 --users、--open-dingtalk-ids 或两者组合。--group 不能与单聊目标同时指定。默认发送 Markdown，必须同时使用 --title 和 --text；公网图片 URL 使用 --msg-type image --image-url <图片 URL>；本地图片和其他本地文件一样使用 --msg-type file --file-path <本地路径>，CLI 会完成上传并按文件附件发送。群聊时可选 --at-user-ids 或 --at-open-dingtalk-ids @指定成员。 +群聊传 --conversation-id；单聊可传 --users、--open-dingtalk-ids 或两者组合。--conversation-id 不能与单聊目标同时指定。默认发送 Markdown，普通发送必须同时使用 --title 和 --text；公网图片 URL 使用 --msg-type image --image-url <图片 URL>；本地图片和其他本地文件一样使用 --msg-type file --file-path <本地路径>，CLI 会完成上传并按文件附件发送。群聊时可选 --at-user-ids 或 --at-open-dingtalk-ids @指定成员。机器人群聊 Markdown 引用回复同时传 --reply 和 --ref-sender ，可省略 --title 由 CLI 从正文生成；单聊、图片和文件不支持引用回复。 如果用户明确要求"用机器人/机器人身份/robot"发送，必须使用本命令，严禁改用 `chat message send` 以当前用户身份发送。 **重要**：机器人发群消息前，必须确认该机器人已在目标群中。若机器人不在群内会报错"机器人不存在"，需先执行 `dws chat group members add-bot --id --robot-code ` 将机器人加入群聊后再发送。 @@ -746,7 +746,8 @@ Flags: Usage: dws chat message send-by-bot [flags] Example: - dws chat message send-by-bot --robot-code --group --title "日报" --text "## 今日完成..." + dws chat message send-by-bot --robot-code --conversation-id --title "日报" --text "## 今日完成..." + dws chat message send-by-bot --robot-code --conversation-id --reply --ref-sender --text "收到" dws chat message send-by-bot --robot-code --group --msg-type image --image-url "https://example.com/image.png" dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./report.pdf dws chat message send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报" @@ -755,10 +756,10 @@ Example: dws chat message send-by-bot --robot-code --group --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" dws chat message send-by-bot --robot-code --group --at-all --title "通知" --text "请所有人注意" Flags: - --group string 群聊 openConversationId（群聊时必填） + --conversation-id string 群聊 openConversationId（群聊时必填；兼容别名 --group） --robot-code string 机器人 Code (必填) --msg-type string 消息类型：markdown、image 或 file；省略时为 markdown；公网图片使用 image --image-url；本地图片和文件使用 file --file-path - --title string Markdown 消息标题（Markdown 时必填） + --title string Markdown 消息标题（普通 Markdown 必填；引用回复省略时从正文生成） --text string Markdown 消息内容（Markdown 时必填） --image-url string 公网图片 URL（msgType=image 时必填） --file-path string 本地图片或文件路径（msgType=file 时上传并按文件附件发送） @@ -767,6 +768,8 @@ Flags: --at-user-ids string @指定成员的 userId 列表，逗号分隔（仅群聊时生效，可选） --at-open-dingtalk-ids string @指定成员的 openDingtalkId 列表，逗号分隔（仅群聊时生效，可选） --at-all @所有人（可选），服务端接收字符串 true/false + --reply string 被引用消息的 openMessageId（仅群聊 Markdown；必须与 --ref-sender 同时使用） + --ref-sender string 被引用消息发送者的 openDingTalkId（仅群聊 Markdown；必须与 --reply 同时使用） 注意: - 用户明确要求机器人发送时，必须使用 `chat message send-by-bot`；严禁使用 `chat message send` 以用户身份代发 @@ -776,6 +779,7 @@ Flags: - --at-user-ids 仅在 --group 群聊时生效，单聊时无效；设置时 --text 中需包含 @userId 对应文本 - --at-open-dingtalk-ids 仅在 --group 群聊时生效，单聊时无效；设置时 --text 中需包含 @openDingtalkId 对应文本 - --at-all @所有人，仅群聊时生效；只需带上 --at-all flag 即可，服务端会自动处理 + - --reply 与 --ref-sender 必须成对使用；CLI 在普通群消息参数顶层透传 referenceOpenMessageId 与 srcMsgSendOpenDingTalkId，不设置 msgType=reply - userId 获取方式：`dws contact user search --query "姓名"` 搜人获取 userId - **换行符**：--text 按 Markdown 渲染，换行规则同 `chat message send`： 1. 必须使用**真实换行符**（`U+000A`），而非字面量 `\n`，否则全部内容会渲染在同一行 @@ -2146,6 +2150,7 @@ Flags: 用户说"入群验证记录/谁申请进群" → `chat group list-join-validations` 用户说"审批入群/通过入群申请/拒绝入群申请" → `chat group audit-join-validation` 用户说"引用回复/回复消息/引用消息回复" → `chat message reply` +用户说"机器人引用回复/让机器人回复这条群消息" → `chat message send-by-bot --conversation-id --reply --ref-sender --text <内容>` 用户说"转发消息/转发一条消息/把消息转发到另一个群" → `chat message forward` 用户说"合并转发/批量转发/合并转发多条消息" → `chat message combine-forward` 用户说"转发话题/转发话题消息" → `chat message forward-topic` @@ -2183,7 +2188,7 @@ Flags: - `chat message send` — 以当前用户身份发消息（群聊或单聊），text 为位置参数；本地图片/文件/音视频统一用 `--msg-type file --file-path`，其中图片显示为可下载附件而非内联图片；`--msg-type image --media-id` 只用于上游已经提供有效 mediaId 的场景，DWS CLI 不能从本地文件生成 mediaId - `chat message search` — 按关键词搜索消息内容（跨所有会话，可选指定群） - `chat search-common` — 搜索共同群，查询指定人共同所在的群聊（AND=所有人都在，OR=任一人在） -- `chat message send-by-bot` — 以**机器人**身份发消息（群聊或单聊）；Markdown 使用 `--text`，公网图片使用 `--msg-type image --image-url`，本地图片和文件使用 `--msg-type file --file-path` +- `chat message send-by-bot` — 以**机器人**身份发消息（群聊或单聊）；Markdown 使用 `--text`，公网图片使用 `--msg-type image --image-url`，本地图片和文件使用 `--msg-type file --file-path`；群聊 Markdown 引用回复成对使用 `--reply` / `--ref-sender` - `chat message send-by-webhook` — 通过**自定义机器人 Webhook** 发群消息 - `chat message recall-by-bot` — 通过**机器人接口**撤回机器人发出的消息，需要 `--robot-code` + `--keys`（发送时返回的 processQueryKey）；传 `--group` 为群聊撤回，不传为单聊撤回 - `chat message recall` — 通过 **IM 接口**撤回当前用户自己发出的消息，需要 `--conversation-id`（openConversationId）+ `--msg-id`（openMessageId，可通过 `chat message list` 获取）；群聊单聊均通过 `--conversation-id` 区分 @@ -2456,7 +2461,7 @@ Flags: | `chat category list` | `categoryId` | category list-conversations 的 --category-id | | `chat group get-by-group-id` | `openConversationId` | 同 chat search，将群号转为 openConversationId | | `chat message send-card` | `bizId` | update-card 的 --biz-id | -| `chat message list` | `openMessageId` | message reply 的 --ref-msg-id、message forward 的 --msg-id | +| `chat message list` | `openMessageId` | message reply 的 --ref-msg-id、send-by-bot 机器人群聊引用回复的 --reply、message forward 的 --msg-id | | `chat search` | `openConversationId` | set-top 的 --conversation-id、group-mute / group-mute-member 的 --group | ## 注意事项 @@ -2485,7 +2490,7 @@ Flags: - `--user` 和 `--open-dingtalk-id` 本质上都是发起单聊操作，只是用户标识格式不同：userId 为企业内部应用常用标识，openDingTalkId 为三方应用或跨组织场景下的用户标识，服务端对两种 ID 的解析逻辑不同 - `--time` 格式: `yyyy-MM-dd HH:mm:ss`，为拉取消息的起始时间点；`--direction` 控制方向（newer=从给定时间往现在拉，older=从给定时间往以前拉），`--limit` 控制数量 - `chat search` 挂在 `chat` 下（非 `chat group` 下），路径为 `dws chat search` -- `send-by-bot` 群聊传 `--group`，单聊传 `--users` 或 `--open-dingtalk-ids`，与 `--group` 互斥且必选其一；群聊时可选 `--at-user-ids` @指定成员（传 userId 列表）或 `--at-open-dingtalk-ids` @指定成员（传 openDingtalkId 列表），content 中需包含对应 @标识；`--at-all` @所有人；群聊场景如果返回"机器人不存在"错误，需先通过 `chat group members add-bot --group --robot-code ` 将机器人邀请进群后再发送 +- `send-by-bot` 群聊传 `--conversation-id`，单聊传 `--users` 或 `--open-dingtalk-ids`，与群目标互斥且必选其一；机器人群聊 Markdown 引用回复必须同时传 `--reply ` 与 `--ref-sender `，单聊、图片和文件不支持引用回复；群聊时可选 `--at-user-ids` @指定成员（传 userId 列表）或 `--at-open-dingtalk-ids` @指定成员（传 openDingTalkId 列表），content 中需包含对应 @标识；`--at-all` @所有人；群聊场景如果返回"机器人不存在"错误，需先通过 `chat group members add-bot --conversation-id --robot-code ` 将机器人邀请进群后再发送 - `recall-by-bot` 群聊传 `--group` + `--keys`，单聊仅传 `--keys`（不传 `--group` 即为单聊撤回） - `send-by-webhook` 支持 `--at-all`、`--at-mobiles`、`--at-users` 进行 @ 操作，但需在 `--text` 中包含 `@userId` 或 `@手机号` 才能生效；`--at-all` @所有人时需在 `--text` 中包含 `@10` - `chat group-role` 系列命令用于管理群的自定义身份标签：`list` 查列表，`add` 创建，`update` 改名，`remove` 删除；`set-user` 覆盖某人全部身份（传空 --role-ids 则清除），`remove-user` 仅移除指定身份，`query-user` 查询某人当前身份；用户用 `--user ` diff --git a/skills/multi/dingtalk-chat/SKILL.md b/skills/multi/dingtalk-chat/SKILL.md index 101fe7af..27cb6a61 100644 --- a/skills/multi/dingtalk-chat/SKILL.md +++ b/skills/multi/dingtalk-chat/SKILL.md @@ -62,7 +62,7 @@ metadata: | 已知资源引用单独下载 | `dws chat +messages-resource-download` | | 按关键词搜索群 | `dws chat +chat-search` | | 查看消息收藏 | `dws chat +flag-list` | -| 引用回复 | `dws chat +messages-reply`；成功结果保留新消息/会话/投递与原消息来源上下文 | +| 引用回复 | 人：`dws chat +messages-reply`；成功结果保留新消息/会话/投递与原消息来源上下文。Bot 群：`dws chat message send-by-bot --conversation-id --reply --ref-sender ` | | 撤回当前用户消息 | `dws chat +messages-recall --msg-id `；可省略会话 ID，由 CLI 只读补齐；兼容单值 `--message-ids` | | 已知话题主消息 ID 或 thread/topic ID 读取回复 | `dws chat +thread-replies` | | 按成员 ID 或姓名创建群聊 | `dws chat +chat-create`；成员/群主均可自然解析，任一歧义都会在创建前整体停止 | diff --git a/skills/multi/dingtalk-chat/references/chat.md b/skills/multi/dingtalk-chat/references/chat.md index a8a30538..cb46df88 100644 --- a/skills/multi/dingtalk-chat/references/chat.md +++ b/skills/multi/dingtalk-chat/references/chat.md @@ -92,7 +92,7 @@ Favorite、消息 Pin、消息 Top 与会话 Top 是四种对象，不能互换 |---|---| | `chat bot search` | 搜索当前用户创建的机器人并取得 `robotCode` | | `chat bot find` | 搜索可用机器人并取得机器人 `openDingTalkId` | -| `chat message send-by-bot` | `+messages-send --as bot` 未发布的真实底层字段 | +| `chat message send-by-bot` | `+messages-send --as bot` 未发布的真实底层字段，包括机器人群聊引用回复的 `--reply` / `--ref-sender` | | `chat message recall-by-bot` | 使用 `processQueryKey` 撤回机器人消息 | | `chat message send-by-webhook` | `+messages-send --as webhook` 未发布的真实底层字段 | @@ -124,7 +124,7 @@ Favorite、消息 Pin、消息 Top 与会话 Top 是四种对象，不能互换 | `+messages-send` | `openTaskId` 查询投递状态；它不是消息 ID | | `+chat-messages` / `+search-msg` / `+messages-mget` | 回复、转发、撤回、资源操作使用的真实消息/会话/thread ID | | `chat bot search` | `robotCode`；不能当机器人 `openDingTalkId` | -| `chat message send-by-bot` | `processQueryKey`，仅用于机器人撤回 | +| `chat message send-by-bot` | `processQueryKey` 用于机器人撤回；群聊引用回复还需消息查询返回的 `openMessageId` 与原发送者 `openDingTalkId` | 显式稳定 ID 当前不携带可验证的 profile provenance；调用方必须保证来源，不得宣称所有 跨 profile 误用都会在本地写入前被拦截。 diff --git a/skills/multi/dingtalk-chat/references/chat/chat-bot.md b/skills/multi/dingtalk-chat/references/chat/chat-bot.md index d238cb0e..8b246d26 100644 --- a/skills/multi/dingtalk-chat/references/chat/chat-bot.md +++ b/skills/multi/dingtalk-chat/references/chat/chat-bot.md @@ -16,6 +16,7 @@ - `chat bot search` 只返回我创建的机器人，没有 `openDingTalkId`；给机器人发单聊必须用 `chat bot find`。 - 机器人发群消息前需确认机器人已在群中；报“机器人不存在”时先 `group members add-bot`。 - `send-by-bot` 支持 Markdown、图片 URL 和文件，具体参数见下方消息类型路由。 +- 机器人在群聊中引用回复已有消息时，使用原子命令 `send-by-bot --reply --ref-sender`；该能力仅支持 Markdown，不走 `+messages-reply` 的当前用户身份。 - 公网图片 URL 使用 `--msg-type image --image-url`，按图片消息发送。 - 本地图片和其他本地文件一样使用 `--msg-type file --file-path`，由 CLI 上传并按文件附件发送。 - 群聊传 `--group`；单聊可传 `--users`、`--open-dingtalk-ids` 或两者组合。 @@ -63,9 +64,10 @@ dws chat +messages-send --as bot --robot-code \ ```bash # 群聊 -dws chat message send-by-bot --robot-code --group --title "日报" --text "## 今日完成\n\n- 事项 A\n\n- 事项 B" -dws chat message send-by-bot --robot-code --group --msg-type image --image-url "https://example.com/image.png" -dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./report.pdf +dws chat message send-by-bot --robot-code --conversation-id --title "日报" --text "## 今日完成\n\n- 事项 A\n\n- 事项 B" +dws chat message send-by-bot --robot-code --conversation-id --reply --ref-sender --text "收到" +dws chat message send-by-bot --robot-code --conversation-id --msg-type image --image-url "https://example.com/image.png" +dws chat message send-by-bot --robot-code --conversation-id --msg-type file --file-path ./report.pdf # 单聊 userId dws chat message send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报" @@ -84,16 +86,20 @@ dws chat message send-by-bot --robot-code --group --group Date: Mon, 17 Aug 2026 16:09:19 +0800 Subject: [PATCH 182/250] fix(release): format shortcut change fragment --- .changes/calendar-todo-shortcut-alignment.md | 21 ++++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/.changes/calendar-todo-shortcut-alignment.md b/.changes/calendar-todo-shortcut-alignment.md index 70fecb96..100f6153 100644 --- a/.changes/calendar-todo-shortcut-alignment.md +++ b/.changes/calendar-todo-shortcut-alignment.md @@ -1,16 +1,11 @@ --- -type: feature -scope: shortcut +category: Added --- -Align Calendar and Todo shortcuts with the corresponding lark-cli user tasks, -while preserving DingTalk-specific workflows and compatibility names. The new -shortcut contracts reject malformed or missing collections instead of -reporting false empty success, retain bounded pagination evidence, and require -stable business identifiers plus read-back or explicit terminal receipts for -writes. - -Add deterministic contract tests, a PII-safe real-data E2E runner, and a -sanitized HTML capability review that records supported, partial, and -platform-unavailable mappings. Product Skill content is intentionally -unchanged. +- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented + entries with lark-cli where the DingTalk backend supports equivalent + semantics, rejects malformed or missing collections instead of returning + false empty success, preserves truthful pagination, and requires stable + identifiers plus read-back or explicit terminal receipts for writes. Adds + deterministic contract coverage, a PII-safe live E2E runner, and a sanitized + capability review with documented platform boundaries. From 2cea069f555156c8e6eff0fa2ce7be1dbf470659 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Mon, 17 Aug 2026 16:09:43 +0800 Subject: [PATCH 183/250] fix(recruit): scope lossless number decoding to #85340676 --- .../framework2_changed_lines_coverage_test.go | 7 ++-- internal/helpers/helpers.go | 1 - internal/helpers/recruit.go | 27 +++++++++++++- internal/helpers/recruit_test.go | 37 ++++++++++++++++++- 4 files changed, 65 insertions(+), 7 deletions(-) diff --git a/internal/helpers/framework2_changed_lines_coverage_test.go b/internal/helpers/framework2_changed_lines_coverage_test.go index b9488467..a80a0751 100644 --- a/internal/helpers/framework2_changed_lines_coverage_test.go +++ b/internal/helpers/framework2_changed_lines_coverage_test.go @@ -6,7 +6,6 @@ package helpers import ( "bytes" "context" - "encoding/json" "errors" "os" "path/filepath" @@ -59,10 +58,10 @@ func TestCrossPlatformCoverageFramework2MCPDataEdges(t *testing.T) { t.Fatalf("decoded data=%#v err=%v", data, err) } - InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{"cursor":9223372036854775807}`}}}}) + InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{"count":7}`}}}}) data, err = CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil) - if err != nil || data.(map[string]any)["cursor"] != json.Number("9223372036854775807") { - t.Fatalf("lossless number data=%#v err=%v", data, err) + if err != nil || data.(map[string]any)["count"] != float64(7) { + t.Fatalf("legacy float64 number data=%#v err=%v", data, err) } InitDeps(&coverageErrorCaller{err: errors.New("transport failed")}) diff --git a/internal/helpers/helpers.go b/internal/helpers/helpers.go index 14435768..f982a153 100644 --- a/internal/helpers/helpers.go +++ b/internal/helpers/helpers.go @@ -286,7 +286,6 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg } var data any decoder := json.NewDecoder(strings.NewReader(text)) - decoder.UseNumber() if err := decoder.Decode(&data); err != nil { return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", toolName, err)) } diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 97a76415..bc9551bc 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -4,9 +4,11 @@ package helpers import ( + "context" "encoding/json" "errors" "fmt" + "io" "os" "strconv" "strings" @@ -148,7 +150,7 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou "tool": tool, "arguments": toolArgs, "executed": false, }, output.WithDryRun()), nil } - data, err := CallMCPToolDataOnServer(cmd.Context(), recruitServerID, tool, toolArgs) + data, err := callRecruitMCPToolData(cmd.Context(), tool, toolArgs) if err != nil { return nil, err } @@ -166,6 +168,29 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou return output.Success(listData, output.WithMeta(meta)), nil } +func callRecruitMCPToolData(ctx context.Context, tool string, args map[string]any) (any, error) { + text, err := callMCPToolReturnTextOnServer(ctx, recruitServerID, tool, args) + if err != nil { + return nil, err + } + if strings.TrimSpace(text) == "" { + return map[string]any{}, nil + } + var data any + decoder := json.NewDecoder(strings.NewReader(text)) + decoder.UseNumber() + if err := decoder.Decode(&data); err != nil { + return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err)) + } + if err := decoder.Decode(&struct{}{}); err != io.EOF { + if err == nil { + err = fmt.Errorf("存在多个 JSON 值") + } + return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err)) + } + return data, nil +} + func recruitResponseFailure(err error) output.CommandResult { var businessFailure *recruitBusinessFailure if errors.As(err, &businessFailure) { diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index a51ddb90..fb90cd52 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -408,6 +408,41 @@ func TestRecruitResultCallPropagatesMCPError(t *testing.T) { } } +func TestRecruitMCPDataDecoderIsLosslessAndStrict(t *testing.T) { + for _, test := range []struct { + name string + text string + wantErr string + }{ + {name: "empty", text: " "}, + {name: "invalid JSON", text: "{", wantErr: "解析 list_jobs 返回失败"}, + {name: "multiple values", text: `{} {}`, wantErr: "存在多个 JSON 值"}, + {name: "invalid trailing value", text: `{} {`, wantErr: "解析 list_jobs 返回失败"}, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = test.text + data, err := callRecruitMCPToolData(context.Background(), recruitListJobsTool, map[string]any{}) + if test.wantErr != "" { + if err == nil || !strings.Contains(err.Error(), test.wantErr) { + t.Fatalf("error = %v, want %q", err, test.wantErr) + } + return + } + if err != nil || len(data.(map[string]any)) != 0 { + t.Fatalf("empty response data = %#v, err = %v", data, err) + } + }) + } + + caller := withRecruitCaller(t) + caller.text = `{"nextCursor":9223372036854775807}` + data, err := callRecruitMCPToolData(context.Background(), recruitListJobsTool, map[string]any{}) + if err != nil || data.(map[string]any)["nextCursor"] != json.Number("9223372036854775807") { + t.Fatalf("lossless recruit number data = %#v, err = %v", data, err) + } +} + func TestRecruitResultCallUnwrapsConnectorEnvelopeForGetAndCreate(t *testing.T) { for _, test := range []struct { name string @@ -431,7 +466,7 @@ func TestRecruitResultCallUnwrapsConnectorEnvelopeForGetAndCreate(t *testing.T) t.Run(test.name, func(t *testing.T) { caller := withRecruitCaller(t) caller.text = test.text - data, err := CallMCPToolDataOnServer(context.Background(), recruitServerID, test.tool, map[string]any{}) + data, err := callRecruitMCPToolData(context.Background(), test.tool, map[string]any{}) if err != nil { t.Fatal(err) } From dc2aec769651c406427ba4ac098561365d3aa121 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 16:44:06 +0800 Subject: [PATCH 184/250] fix(calendar): preserve room-find flag compatibility --- internal/shortcut/calendar/calendar.go | 49 +++++++++++++------ .../calendar_cross_platform_coverage_test.go | 41 ++++++++++++++++ 2 files changed, 76 insertions(+), 14 deletions(-) diff --git a/internal/shortcut/calendar/calendar.go b/internal/shortcut/calendar/calendar.go index 5817e6eb..5ee5c1a9 100644 --- a/internal/shortcut/calendar/calendar.go +++ b/internal/shortcut/calendar/calendar.go @@ -19,6 +19,7 @@ package calendar import ( "fmt" + "strconv" "strings" "time" @@ -440,29 +441,29 @@ var RoomFind = shortcut.Shortcut{ Flags: []shortcut.Flag{ {Name: "start", Type: shortcut.FlagString, Desc: "开始时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, - {Name: "available", Type: shortcut.FlagBool, Hidden: true, Desc: "兼容旧调用；该命令本身始终只返回可用会议室"}, + {Name: "available", Type: shortcut.FlagBool, Desc: "仅返回可用会议室；保留已发布参数兼容性"}, {Name: "group-id", Type: shortcut.FlagString, Desc: "会议室分组 ID"}, {Name: "room-name", Type: shortcut.FlagString, Desc: "会议室名称过滤"}, - {Name: "limit", Type: shortcut.FlagInt, Default: "20", Desc: "pageSize；limit 必须在 1-100 之间，page 不能小于 0"}, - {Name: "page", Type: shortcut.FlagInt, Default: "0", Desc: "pageIndex；limit 必须在 1-100 之间，page 不能小于 0"}, + {Name: "limit", Type: shortcut.FlagString, Desc: "每页条数 (pageSize)；保留 string 类型兼容性；limit 必须在 1-100 之间"}, + {Name: "page", Type: shortcut.FlagString, Desc: "页码 (pageIndex，从 0 开始)；保留 string 类型兼容性；page 不能小于 0"}, }, Validate: func(rt *shortcut.RuntimeContext) error { - if err := rt.RangeInt("limit", 1, 100); err != nil { - return err - } - if rt.Int("page") < 0 { - return fmt.Errorf("--page 不能小于 0") - } - return nil + _, _, err := roomFindPageValues(rt) + return err }, Constraints: []shortcut.Constraint{ {Kind: shortcut.ConstraintCustom, Flags: []string{"start", "end"}, Description: "起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, - {Kind: shortcut.ConstraintCustom, Flags: []string{"limit", "page"}, Description: "limit 必须在 1-100 之间，page 不能小于 0"}, + {Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "limit 必须在 1-100 之间"}, + {Kind: shortcut.ConstraintCustom, Flags: []string{"page"}, Description: "page 不能小于 0"}, }, Tips: []string{ `dws calendar +room-find --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00"`, }, Execute: func(rt *shortcut.RuntimeContext) error { + pageSize, pageIndex, err := roomFindPageValues(rt) + if err != nil { + return err + } now := time.Now() startStr := rt.Str("start") endStr := rt.Str("end") @@ -486,8 +487,11 @@ var RoomFind = shortcut.Shortcut{ params := map[string]any{ "startTime": startMs, "endTime": endMs, - "pageSize": fmt.Sprint(rt.Int("limit")), - "pageIndex": fmt.Sprint(rt.Int("page")), + "pageSize": strconv.Itoa(pageSize), + "pageIndex": strconv.Itoa(pageIndex), + } + if rt.Bool("available") { + params["needAvailable"] = true } if rt.Changed("group-id") { params["groupId"] = rt.Str("group-id") @@ -513,7 +517,7 @@ var RoomFind = shortcut.Shortcut{ if err != nil { return err } - out := map[string]any{"count": len(rooms), "rooms": rooms, "page": rt.Int("page"), "pageSize": rt.Int("limit"), "complete": false} + out := map[string]any{"count": len(rooms), "rooms": rooms, "page": pageIndex, "pageSize": pageSize, "complete": false} for _, key := range []string{"hasMore", "totalCount", "total", "pageIndex", "pageSize"} { if value, ok := container[key]; ok && value != nil { out[key] = value @@ -526,6 +530,23 @@ var RoomFind = shortcut.Shortcut{ }, } +func roomFindPageValues(rt *shortcut.RuntimeContext) (pageSize int, pageIndex int, err error) { + pageSize = 20 + if rt.Changed("limit") { + pageSize, err = strconv.Atoi(strings.TrimSpace(rt.Str("limit"))) + if err != nil || pageSize < 1 || pageSize > 100 { + return 0, 0, fmt.Errorf("--limit 必须是 1-100 之间的整数") + } + } + if rt.Changed("page") { + pageIndex, err = strconv.Atoi(strings.TrimSpace(rt.Str("page"))) + if err != nil || pageIndex < 0 { + return 0, 0, fmt.Errorf("--page 必须是大于或等于 0 的整数") + } + } + return pageSize, pageIndex, nil +} + // RoomAdd → add_meeting_room // RoomRemove → delete_meeting_room // RoomGroups → list_meeting_room_groups diff --git a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go index 5517b031..7077686c 100644 --- a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go +++ b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go @@ -165,3 +165,44 @@ func TestCrossPlatformCoverageCalendarAlignedContracts(t *testing.T) { t.Fatal("calendar writes must require confirmation") } } + +func TestCrossPlatformCoverageCalendarRoomFindPreservesPublishedFlags(t *testing.T) { + flags := make(map[string]shortcut.Flag, len(RoomFind.Flags)) + for _, flag := range RoomFind.Flags { + flags[flag.Name] = flag + } + if flag := flags["available"]; flag.Type != shortcut.FlagBool || flag.Hidden { + t.Fatalf("available flag=%+v, want visible bool", flag) + } + for _, name := range []string{"limit", "page"} { + if flag := flags[name]; flag.Type != shortcut.FlagString || flag.Hidden { + t.Fatalf("%s flag=%+v, want visible string", name, flag) + } + } + + caller := &calendarCoverageCaller{responses: map[string][]string{ + "query_available_meeting_room": {`{"success":true,"result":{"rooms":[],"hasMore":false}}`}, + }} + err := runCalendarCoverage(t, RoomFind, caller, + "--start", "2026-03-10T14:00:00+08:00", + "--end", "2026-03-10T15:00:00+08:00", + "--available", "--limit", "25", "--page", "2") + if err != nil { + t.Fatal(err) + } + if len(caller.arguments) != 1 { + t.Fatalf("calls=%d, want 1", len(caller.arguments)) + } + arguments := caller.arguments[0] + if arguments["pageSize"] != "25" || arguments["pageIndex"] != "2" || arguments["needAvailable"] != true { + t.Fatalf("arguments=%#v", arguments) + } + + invalid := &calendarCoverageCaller{responses: map[string][]string{}} + if err := runCalendarCoverage(t, RoomFind, invalid, "--limit", "101"); err == nil || !strings.Contains(err.Error(), "1-100") { + t.Fatalf("invalid limit error=%v", err) + } + if len(invalid.history) != 0 { + t.Fatalf("invalid input made calls: %v", invalid.history) + } +} From 8db297fe4b65a4c325c2f2de2e791054112c4965 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 16:53:07 +0800 Subject: [PATCH 185/250] fix(calendar): preserve agenda schema compatibility --- internal/shortcut/calendar/calendar.go | 11 ++++-- .../calendar_cross_platform_coverage_test.go | 36 +++++++++++++++++++ 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/internal/shortcut/calendar/calendar.go b/internal/shortcut/calendar/calendar.go index 5ee5c1a9..7559d07e 100644 --- a/internal/shortcut/calendar/calendar.go +++ b/internal/shortcut/calendar/calendar.go @@ -83,7 +83,7 @@ var EventList = shortcut.Shortcut{ {Name: "end", Type: shortcut.FlagString, Desc: "结束时间 ISO-8601；起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start；默认今天 23:59"}, {Name: "calendar-id", Type: shortcut.FlagString, Desc: "日历 ID (默认 primary 主日历)"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标 (上一次返回的 nextCursor)"}, - {Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页返回条数；limit 必须在 1-100 之间"}, + {Name: "limit", Type: shortcut.FlagInt, Desc: "每页返回条数（服务端默认 100）；limit 必须在 1-100 之间"}, }, Tips: []string{ `dws calendar +agenda`, @@ -958,10 +958,15 @@ func bookSearchFirst(m map[string]any, keys ...string) (any, bool) { // BookUpdate → update_calendar func init() { EventList.Contract.Parameters = []contract.ParamDecl{ - {Name: "start", Property: "startTime"}, {Name: "end", Property: "endTime"}, + {Name: "start", Property: "start"}, {Name: "end", Property: "end"}, {Name: "calendar-id", Property: "calendarId"}, {Name: "cursor", Property: "cursor"}, {Name: "limit", Property: "limit"}, } - EventList.Validate = func(rt *shortcut.RuntimeContext) error { return rt.RangeInt("limit", 1, 100) } + EventList.Validate = func(rt *shortcut.RuntimeContext) error { + if !rt.Changed("limit") { + return nil + } + return rt.RangeInt("limit", 1, 100) + } EventList.Constraints = []shortcut.Constraint{ {Kind: shortcut.ConstraintCustom, Flags: []string{"start", "end"}, Description: "起止时间必须是 RFC3339/ISO-8601，且 end 晚于 start"}, {Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "limit 必须在 1-100 之间"}, diff --git a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go index 7077686c..21a81470 100644 --- a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go +++ b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go @@ -206,3 +206,39 @@ func TestCrossPlatformCoverageCalendarRoomFindPreservesPublishedFlags(t *testing t.Fatalf("invalid input made calls: %v", invalid.history) } } + +func TestCrossPlatformCoverageCalendarAgendaPreservesPublishedSchema(t *testing.T) { + properties := make(map[string]string, len(EventList.Contract.Parameters)) + for _, parameter := range EventList.Contract.Parameters { + properties[parameter.Name] = parameter.Property + } + if properties["start"] != "start" || properties["end"] != "end" { + t.Fatalf("agenda time properties=%#v", properties) + } + for _, flag := range EventList.Flags { + if flag.Name == "limit" && flag.Default != "" { + t.Fatalf("agenda limit default=%q, want published empty default", flag.Default) + } + } + + caller := &calendarCoverageCaller{responses: map[string][]string{ + "list_calendar_events": {`{"success":true,"result":{"events":[],"hasMore":false}}`}, + }} + if err := runCalendarCoverage(t, EventList, caller); err != nil { + t.Fatal(err) + } + if len(caller.arguments) != 1 { + t.Fatalf("calls=%d, want 1", len(caller.arguments)) + } + if _, ok := caller.arguments[0]["limit"]; ok { + t.Fatalf("unset limit unexpectedly sent: %#v", caller.arguments[0]) + } + + invalid := &calendarCoverageCaller{responses: map[string][]string{}} + if err := runCalendarCoverage(t, EventList, invalid, "--limit", "101"); err == nil || !strings.Contains(err.Error(), "1") { + t.Fatalf("invalid limit error=%v", err) + } + if len(invalid.history) != 0 { + t.Fatalf("invalid input made calls: %v", invalid.history) + } +} From f319906f29976382936aad0726d54756bd1d7ebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Mon, 17 Aug 2026 17:17:29 +0800 Subject: [PATCH 186/250] fix(oa): close attachment coverage gaps to #666 --- internal/helpers/oa.go | 18 ++++++------------ internal/helpers/oa_attachment_test.go | 2 ++ 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/internal/helpers/oa.go b/internal/helpers/oa.go index 2104ba3a..68a73ae0 100644 --- a/internal/helpers/oa.go +++ b/internal/helpers/oa.go @@ -46,7 +46,7 @@ func oaFormValues(raw string) ([]map[string]string, error) { func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) { decoder := json.NewDecoder(strings.NewReader(raw)) decoder.UseNumber() - var items []map[string]json.RawMessage + var items []map[string]any if err := decoder.Decode(&items); err != nil { return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err) } @@ -65,28 +65,22 @@ func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) { } } - spaceRaw, ok := item["spaceId"] + spaceValue, ok := item["spaceId"] if !ok { return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1) } - spaceDecoder := json.NewDecoder(strings.NewReader(string(spaceRaw))) - spaceDecoder.UseNumber() - var spaceValue any - if err := spaceDecoder.Decode(&spaceValue); err != nil { - return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 不是有效数字: %w", index+1, err) - } spaceID, ok := spaceValue.(json.Number) if !ok { return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1) } - fileRaw, ok := item["fileId"] + fileValue, ok := item["fileId"] if !ok { return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1) } - var fileID string - if err := json.Unmarshal(fileRaw, &fileID); err != nil { - return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串: %w", index+1, err) + fileID, ok := fileValue.(string) + if !ok { + return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串", index+1) } fileID = strings.TrimSpace(fileID) if fileID == "" { diff --git a/internal/helpers/oa_attachment_test.go b/internal/helpers/oa_attachment_test.go index b17034ef..b32ec111 100644 --- a/internal/helpers/oa_attachment_test.go +++ b/internal/helpers/oa_attachment_test.go @@ -188,9 +188,11 @@ func TestCrossPlatformCoverageOAAttachmentRejectsInvalidFileInfos(t *testing.T) {name: "missing space ID", raw: `[{"fileId":"file-1"}]`}, {name: "string space ID", raw: `[{"spaceId":"27827223951","fileId":"file-1"}]`}, {name: "missing file ID", raw: `[{"spaceId":27827223951}]`}, + {name: "numeric file ID", raw: `[{"spaceId":27827223951,"fileId":232271651278}]`}, {name: "blank file ID", raw: `[{"spaceId":27827223951,"fileId":" "}]`}, {name: "unknown property", raw: `[{"spaceId":27827223951,"fileId":"file-1","extra":true}]`}, {name: "trailing JSON", raw: `[` + valid + `] {}`}, + {name: "malformed trailing JSON", raw: `[` + valid + `] {`}, } for _, test := range tests { From 3dce49020e4d043401b848f947eaff945d8344b3 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 17:21:53 +0800 Subject: [PATCH 187/250] docs(shortcut): refresh integrated gate counts --- docs/calendar-todo-shortcut-business-review.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/calendar-todo-shortcut-business-review.html b/docs/calendar-todo-shortcut-business-review.html index d27cb884..5f844b2f 100644 --- a/docs/calendar-todo-shortcut-business-review.html +++ b/docs/calendar-todo-shortcut-business-review.html @@ -68,7 +68,7 @@

Calendar 实际断言

  • 未来 RFC3339 + 显式时区，start<end，读回时间一致。
  • create/get/agenda/search/update/cancel 全部绑定同一 eventId。
  • 分页、busy、suggestion、attendees 的坏元素均非零失败。
  • 取消接受真实 tombstone；book 回滚后验证对象缺席。

Todo 实际断言

  • create/get/list/update/complete/reopen/delete 全部绑定同一 taskId。
  • 子任务、评论、附件均在真实父任务中创建并读取。
  • all-page 角色视图、今日、逾期和搜索命中已知 fixture。
  • 清理按子→父反向执行，最后再次搜索确认零残留。
-

Release gates

工程、范围与脱敏门

报告不保存 profile、组织、成员、日历/事件/任务/评论/附件/会议室 ID、URL、标题正文、精确真实日程、trace、token 或本地绝对路径。

门结果说明
Build / focused testsPASSCalendar、Todo、smart 严格回归与跨平台覆盖通过。
Schema assembly / catalog / driftPASS27 products / 1138 tools；组装 deterministic，生成漂移为零。
Result / Safety coveragePASSCalendar 27 与 Todo 21 个 Schema shortcut leaves 均有 Result/Safety；Todo 计入 1 个 hidden unavailable。
Runtime confirmation truthPASS声明与真实确认 gate 同源；写能力未以元数据绕过确认。
Agent examplesPASS1403 个示例合同门通过；未向存储示例注入 --yes。
Full Go suitePASSDWS_PACKAGE_VERSION=0.0.0-test go test ./...。
Live exact E2EPASS44 capability PASS / 3 disclosed BLOCKED / 0 FAIL；cleanup audit PASS。
ScopePASS业务实现限定为 Shortcut；Skill 手写逻辑零改动，仅同步 3 个强制生成的发现区块。
PII / secret / history scanPASS最终树与提交差异只含脱敏工程事实，无 live 原始日志。
+

Release gates

工程、范围与脱敏门

报告不保存 profile、组织、成员、日历/事件/任务/评论/附件/会议室 ID、URL、标题正文、精确真实日程、trace、token 或本地绝对路径。

门结果说明
Build / focused testsPASSCalendar、Todo、smart 严格回归与跨平台覆盖通过。
Schema assembly / catalog / driftPASS27 products / 1139 tools；组装 deterministic，生成漂移为零。
Result / Safety coveragePASSCalendar 27 与 Todo 21 个 Schema shortcut leaves 均有 Result/Safety；Todo 计入 1 个 hidden unavailable。
Runtime confirmation truthPASS声明与真实确认 gate 同源；写能力未以元数据绕过确认。
Agent examplesPASS1405 个示例合同门通过；未向存储示例注入 --yes。
Full Go suitePASSDWS_PACKAGE_VERSION=0.0.0-test go test ./...。
Live exact E2EPASS44 capability PASS / 3 disclosed BLOCKED / 0 FAIL；cleanup audit PASS。
ScopePASS业务实现限定为 Shortcut；Skill 手写逻辑零改动，仅同步 3 个强制生成的发现区块。
PII / secret / history scanPASS最终树与提交差异只含脱敏工程事实，无 live 原始日志。
REVIEW 01

接受诚实的 3 个 BLOCKED

是否同意在没有安全 fixture/租户权限时保留明确原因，而不以 mock 或空数组提升为 PASS。

REVIEW 02

保持 assign 兼容

是否同意不破坏 DWS 历史“创建并指派”语义；未来如增加协作者管理，应使用新命令名。

REVIEW 03

上传保留原子路由

是否同意在 shortcut runtime 尚不能复用安全上传事务时维持 unavailable，避免复制凭证链。

DWS Calendar × Todo Shortcut business review · 2026-08-17 · sanitized engineering artifact
From 021da02474bc02393a151704b5a3a7c51a420fad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Mon, 17 Aug 2026 15:07:03 +0800 Subject: [PATCH 188/250] fix(chat): preserve unverified sender identity semantics --- .changes/chat-sender-identity-contract.md | 5 +++++ internal/shortcut/smart/chat_messages.go | 17 +++++------------ internal/shortcut/smart/chat_messages_test.go | 11 ++++++++--- internal/shortcut/smart/search_msg.go | 15 ++++----------- .../shortcut/smart/search_msg_execution_test.go | 11 ++++++++--- .../dingtalk-chat/references/01-messaging.md | 2 +- .../references/chat/chat-conversation.md | 4 +++- .../references/chat/message-query.md | 12 ++++++++---- .../dingtalk-chat/references/intent-guide.md | 2 +- 9 files changed, 43 insertions(+), 36 deletions(-) create mode 100644 .changes/chat-sender-identity-contract.md diff --git a/.changes/chat-sender-identity-contract.md b/.changes/chat-sender-identity-contract.md new file mode 100644 index 00000000..216ffbf2 --- /dev/null +++ b/.changes/chat-sender-identity-contract.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior. diff --git a/internal/shortcut/smart/chat_messages.go b/internal/shortcut/smart/chat_messages.go index 92ebfbff..28ec97ac 100644 --- a/internal/shortcut/smart/chat_messages.go +++ b/internal/shortcut/smart/chat_messages.go @@ -83,7 +83,7 @@ var ChatMessages = shortcut.Shortcut{ }, Selection: contract.SelectionSpec{ AgentSummary: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选，但无稳定 senderId 命中不得作完整否定结论。不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + + UseWhen: []string{"当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选的姓名、userId 或 openDingTalkId 混合入口：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选并保留 identity_unverified，可交付精确命中但不能把原值升级为已验证身份或作完整否定结论。--sender-query 只按姓名唯一解析，解析失败会抑制未过滤消息并返回错误。不传发送者条件时原样读取会话且不查询发送者身份。sender 展示名不参与身份比较；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + @@ -104,8 +104,8 @@ var ChatMessages = shortcut.Shortcut{ {Name: "user", Type: shortcut.FlagString, Desc: "单聊对方的 userId，与 --group 互斥"}, {Name: "user-query", Type: shortcut.FlagString, Desc: "按姓名解析唯一 openDingTalkId 的兼容入口", Hidden: true}, {Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊对方的 openDingTalkId，与 --group/--user 互斥"}, - {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录故障不阻断原值 userId 筛选"}, - {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析发送者的兼容入口（可选，可重复或逗号分隔）"}, + {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录无法分类时按原值 userId 筛选并保留身份未验证状态"}, + {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析发送者的兼容入口；解析失败时抑制未过滤消息并返回错误（可选，可重复或逗号分隔）"}, {Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；--time 必须是 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD；省略时从当前时间向前读取最近消息"}, {Name: "start", Type: shortcut.FlagString, Desc: "范围开始时间（可选、包含），支持 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD"}, {Name: "start-time", Type: shortcut.FlagString, Desc: "--start 的 lark-cli 对齐别名（可选、包含）"}, @@ -418,7 +418,7 @@ func applyOptionalChatMessagesSenderFilter( payload["complete"] = false payload["partial"] = len(filtered) > 0 } - unverifiedSenderInputs := chatMessagesUnverifiedSenderInputs(filtered, filter.resolutions) + unverifiedSenderInputs := chatMessagesUnverifiedSenderInputs(filter.resolutions) if len(unverifiedSenderInputs) > 0 { failures, _ := payload["failures"].([]map[string]any) failures = append(failures, map[string]any{ @@ -470,18 +470,11 @@ func applyOptionalChatMessagesSenderFilter( } func chatMessagesUnverifiedSenderInputs( - messages []map[string]any, resolutions []targetresolver.UserResolution, ) []string { - observed := map[string]bool{} - for _, message := range messages { - if senderID := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(message))); senderID != "" && senderID != "" { - observed[senderID] = true - } - } values := make([]string, 0) for _, resolution := range resolutions { - if targetresolver.IsUnverifiedUserIDResolution(resolution) && !observed[resolution.Selected.UserID] { + if targetresolver.IsUnverifiedUserIDResolution(resolution) { values = append(values, resolution.Query) } } diff --git a/internal/shortcut/smart/chat_messages_test.go b/internal/shortcut/smart/chat_messages_test.go index aab4bf87..c00585f2 100644 --- a/internal/shortcut/smart/chat_messages_test.go +++ b/internal/shortcut/smart/chat_messages_test.go @@ -631,7 +631,7 @@ func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) } }) - t.Run("unverified mixed sender becomes verified by an exact sender id match", func(t *testing.T) { + t.Run("unverified mixed sender remains unverified after an exact sender id match", func(t *testing.T) { payload := map[string]any{"complete": true, "failures": []map[string]any{}} resolution := targetresolver.UserResolution{ Status: targetresolver.StatusResolved, @@ -655,13 +655,18 @@ func TestCrossPlatformCoverageChatMessagesSenderFilterFailureEdges(t *testing.T) {"openMessageId": "other", "senderUserId": "other-user"}, }, &filter, ) - if len(filtered) != 1 || payload["complete"] != true || len(payload["failures"].([]map[string]any)) != 0 { + if len(filtered) != 1 || payload["complete"] != false || payload["partial"] != true || + payload["failedCount"] != 1 || len(payload["failures"].([]map[string]any)) != 1 { t.Fatalf("filtered=%#v payload=%#v", filtered, payload) } identity := payload["identityResult"].(map[string]any) - if identity["status"] != "evaluated" || identity["negativeConclusionAllowed"] != true { + if identity["status"] != "identity_unverified" || identity["negativeConclusionAllowed"] != false { t.Fatalf("identityResult=%#v", identity) } + filterResult := payload["senderFilter"].(map[string]any) + if filterResult["status"] != "identity_unverified" { + t.Fatalf("senderFilter=%#v", filterResult) + } }) t.Run("unverified mixed sender without a match blocks complete negative conclusion", func(t *testing.T) { diff --git a/internal/shortcut/smart/search_msg.go b/internal/shortcut/smart/search_msg.go index 73f8bbc6..9f83793a 100644 --- a/internal/shortcut/smart/search_msg.go +++ b/internal/shortcut/smart/search_msg.go @@ -35,7 +35,7 @@ import ( // search hits through list_messages_by_ids in chunks of 50. A later-page or // enrichment failure never turns a partial result into a false success: the // output carries an explicit failure ledger and complete=false. -const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话。--group/--groups 接受群名或 openConversationId，--sender/--senders 接受姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 执行，但无稳定 senderId 命中不得作完整否定结论。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + +const searchMsgIntent = "当你要按关键词、发送者、@对象、消息类型、机器人来源或会话范围组合搜索 IM 消息时使用；可搜索单个、多个或全部会话。--group/--groups 接受群名或 openConversationId，--sender/--senders 接受姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 执行并保留 identity_unverified，可交付精确命中但不能把原值升级为已验证身份或作完整否定结论。默认查询近 7 天，也可指定精确起止时间和输出顺序。" + "显式指定会话时会先验证 CID，再执行有界全局扫描并在本地精确过滤，避免下层忽略非法 CID 或群聊 CID。" + "--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。" + "--download-resources 使用安全本地路径、默认不覆盖和原子落盘。" @@ -86,7 +86,7 @@ var SearchMsg = shortcut.Shortcut{ {Name: "groups", Type: shortcut.FlagStringSlice, Desc: "多个群名或 openConversationId；可混合输入并逐项唯一解析"}, {Name: "chat-id", Type: shortcut.FlagStringSlice, Desc: "--groups 的 lark-cli 对齐别名；只接受 openConversationId"}, {Name: "chat-query", Type: shortcut.FlagStringSlice, Desc: "显式按群名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, - {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录故障不阻断原值 userId 查询"}, + {Name: "senders", Type: shortcut.FlagStringSlice, Desc: "多个发送者姓名、userId 或 openDingTalkId；姓名唯一解析，稳定 ID 精确路由，通讯录无法分类时按原值 userId 查询并保留身份未验证状态"}, {Name: "sender", Type: shortcut.FlagStringSlice, Desc: "单个或多个发送者姓名、userId 或 openDingTalkId；--senders 的兼容别名，保留同样的三态解析与安全降级语义"}, {Name: "sender-query", Type: shortcut.FlagStringSlice, Desc: "显式按姓名唯一解析的兼容入口（可选，可重复或逗号分隔）"}, {Name: "at-me", Type: shortcut.FlagBool, Desc: "只搜索 @我 的消息"}, @@ -278,7 +278,7 @@ var SearchMsg = shortcut.Shortcut{ return searchSenderScopeUnverifiedError(resolvedFilters.Senders, unverifiableMessageIDs) } } - unverifiedSenderInputs := searchUnverifiedSenderInputs(messages, resolvedFilters.Senders) + unverifiedSenderInputs := searchUnverifiedSenderInputs(resolvedFilters.Senders) if len(unverifiedSenderInputs) > 0 { failures = append(failures, map[string]any{ "stage": "sender_identity_verification", @@ -701,18 +701,11 @@ func filterSearchSenderScope( } func searchUnverifiedSenderInputs( - messages []map[string]any, resolutions []targetresolver.UserResolution, ) []string { - observed := map[string]bool{} - for _, message := range messages { - if senderID := strings.TrimSpace(fmt.Sprint(chatmsg.SenderID(message))); senderID != "" && senderID != "" { - observed[senderID] = true - } - } values := make([]string, 0) for _, resolution := range resolutions { - if targetresolver.IsUnverifiedUserIDResolution(resolution) && !observed[resolution.Selected.UserID] { + if targetresolver.IsUnverifiedUserIDResolution(resolution) { values = append(values, resolution.Query) } } diff --git a/internal/shortcut/smart/search_msg_execution_test.go b/internal/shortcut/smart/search_msg_execution_test.go index 1768c849..418aec31 100644 --- a/internal/shortcut/smart/search_msg_execution_test.go +++ b/internal/shortcut/smart/search_msg_execution_test.go @@ -277,9 +277,14 @@ func TestCrossPlatformCoverageSearchMsgStableUserIDContinuesWhenDirectoryIsUnava if _, exists := caller.calls[1].args["senderOpenDingTakIds"]; exists { t.Fatalf("unrelated candidate leaked into request: %#v", caller.calls[1].args) } - if payload["complete"] != true || payload["count"] != float64(1) { + if payload["complete"] != false || payload["count"] != float64(1) || + payload["failedCount"] != float64(1) { t.Fatalf("payload=%#v", payload) } + scope := payload["senderScope"].(map[string]any) + if scope["status"] != "identity_unverified" || scope["targetsResolved"] != false { + t.Fatalf("senderScope=%#v", scope) + } }) t.Run("mixed sender preserves positive matches and blocks complete negative conclusion", func(t *testing.T) { @@ -298,11 +303,11 @@ func TestCrossPlatformCoverageSearchMsgStableUserIDContinuesWhenDirectoryIsUnava if got := caller.calls[1].args["senderUserIds"]; !reflect.DeepEqual(got, []string{"stable-user-id"}) { t.Fatalf("senderUserIds=%#v", got) } - if payload["count"] != float64(1) || payload["complete"] != true || payload["failedCount"] != float64(0) { + if payload["count"] != float64(1) || payload["complete"] != false || payload["failedCount"] != float64(1) { t.Fatalf("payload=%#v", payload) } scope := payload["senderScope"].(map[string]any) - if _, exists := scope["status"]; exists || scope["targetsResolved"] != true { + if scope["status"] != "identity_unverified" || scope["targetsResolved"] != false { t.Fatalf("senderScope=%#v", scope) } }) diff --git a/skills/multi/dingtalk-chat/references/01-messaging.md b/skills/multi/dingtalk-chat/references/01-messaging.md index d5b304ee..baa755a1 100644 --- a/skills/multi/dingtalk-chat/references/01-messaging.md +++ b/skills/multi/dingtalk-chat/references/01-messaging.md @@ -11,7 +11,7 @@ ## 群聊消息 -读取或导出指定群聊/单聊的消息记录时使用 `dws chat +chat-messages`。可附带非必填的 `--sender-query <姓名>`：没有稳定 ID 时保留全部消息，唯一解析成功后按 userId/openDingTalkId 筛选同一次读取结果并返回 `resolvedFilters`，不要补跑 `+search-msg`。 +读取或导出指定群聊/单聊的消息记录时使用 `dws chat +chat-messages`。可附带非必填的 `--sender-query <姓名>`：唯一解析成功后按稳定 `senderId` 筛选同一次读取结果并返回 `resolvedFilters`；解析失败、不完整或存在歧义时抑制未过滤消息并返回 `sender_resolution_failed`，不要补跑 `+search-msg`。混合姓名/ID 入口 `--sender` 无法经通讯录确认类型时可按原值 userId 精确过滤，但必须保留 `identity_unverified`。 用户以发送者、关键词、@对象或消息类型为主要条件直接检索时优先使用 `+search-msg`；范围可以是单个、多个或全部会话。 diff --git a/skills/multi/dingtalk-chat/references/chat/chat-conversation.md b/skills/multi/dingtalk-chat/references/chat/chat-conversation.md index ffc296cf..0e981be9 100644 --- a/skills/multi/dingtalk-chat/references/chat/chat-conversation.md +++ b/skills/multi/dingtalk-chat/references/chat/chat-conversation.md @@ -9,7 +9,9 @@ - 查看置顶会话默认使用 `dws chat +conversation-list-top`； 原子 `list-top-conversations` 只在需要原始响应时作为 fallback。 - 取得目标会话后读取或导出消息记录，默认使用 `dws chat +chat-messages`； - 可附带非必填的 `--sender-query` 解析姓名：无稳定 ID 返回全部，唯一解析成功后按 `senderId` 筛选同一次读取结果。不要回到原子 `message list`，也不要补跑 `+search-msg`。直接条件检索优先使用 `+search-msg`。 + 可附带非必填的 `--sender-query` 解析姓名：唯一解析成功后按 `senderId` 筛选同一次读取结果； + 解析失败、不完整或存在歧义时抑制未过滤消息并返回 `sender_resolution_failed`。不要回到原子 + `message list`，也不要补跑 `+search-msg`。直接条件检索优先使用 `+search-msg`。 ## 必读约束 diff --git a/skills/multi/dingtalk-chat/references/chat/message-query.md b/skills/multi/dingtalk-chat/references/chat/message-query.md index cc35ab04..4a4155ff 100644 --- a/skills/multi/dingtalk-chat/references/chat/message-query.md +++ b/skills/multi/dingtalk-chat/references/chat/message-query.md @@ -30,10 +30,14 @@ dws chat +chat-messages --group <群名或openConversationId> --format json dws chat +chat-messages --group --page-all --page-limit 50 --format json ``` -可附带非必填的 `--sender-query <姓名>`：未传时返回全部消息；未解析出稳定 ID 时保留 -全部消息并记录失败；唯一解析出 userId/openDingTalkId 后，按消息 `senderId` 筛选同一次 -读取结果，覆盖最终 `messages/count` 并返回 `resolvedFilters`。不得用展示名字符串比较否定 -已经成功解析的稳定发送者身份。 +可附带非必填的 `--sender-query <姓名>`：未传时返回全部消息；唯一解析出 +userId/openDingTalkId 后，按消息 `senderId` 筛选同一次读取结果，覆盖最终 +`messages/count` 并返回 `resolvedFilters`。解析失败、不完整或存在歧义时抑制未过滤消息， +返回 `sender_resolution_failed`，不得把全量消息当作发送者筛选结果。 + +`--sender` 是姓名、userId 或 openDingTalkId 的混合入口。通讯录无法确认输入类型时，可按 +原值 userId 精确过滤并交付命中消息，但结果必须保留 `identity_unverified`，不得把字符串命中 +升级为已验证身份，也不得据此作完整否定结论。 ```bash dws chat +chat-messages --group "项目群" --sender-query "测试用户甲" --page-all --format json diff --git a/skills/multi/dingtalk-chat/references/intent-guide.md b/skills/multi/dingtalk-chat/references/intent-guide.md index 04146c60..ead039ac 100644 --- a/skills/multi/dingtalk-chat/references/intent-guide.md +++ b/skills/multi/dingtalk-chat/references/intent-guide.md @@ -9,7 +9,7 @@ | 给姓名发简单文本 | `+dm` | 先查人再原子发送 | | 给群名发简单文本 | `+send-to-group` | 先搜群再原子发送 | | 文件、Bot、Webhook、复杂 @、幂等 | `+messages-send` | 为不同身份各走一套原子入口 | -| 读取或导出指定会话，可附带发送者姓名 | `+chat-messages`；姓名用非必填 `--sender-query` | 无稳定 ID 返回全部，有则读后筛选；不补跑搜索 | +| 读取或导出指定会话，可附带发送者姓名 | `+chat-messages`；姓名用非必填 `--sender-query` | 解析成功后读后筛选；解析失败抑制未过滤消息并返回错误；不补跑搜索 | | 直接按发送者、关键词、@对象或消息类型搜索 | `+search-msg` | 条件检索优先，可限定单个或跨多个会话 | | 已知消息 IDs 取详情 | `+messages-mget` | 重新搜索关键词 | | @我的消息 | `+at-me` | 全量消息后本地猜测 @ | From fc05976d3328b19c983984cb379c3e5c1f913590 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A0=A9=E6=9C=9D?= Date: Mon, 17 Aug 2026 17:05:18 +0800 Subject: [PATCH 189/250] fix(chat): align chat message selection intent --- internal/shortcut/smart/chat_messages.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/shortcut/smart/chat_messages.go b/internal/shortcut/smart/chat_messages.go index 28ec97ac..52afd7f4 100644 --- a/internal/shortcut/smart/chat_messages.go +++ b/internal/shortcut/smart/chat_messages.go @@ -57,7 +57,7 @@ var ChatMessages = shortcut.Shortcut{ Command: "+chat-messages", Product: "chat", Description: "读取指定群聊或单聊的消息记录，支持有界全量分页与原子 JSON 导出", - Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选过滤条件，可传姓名、userId 或 openDingTalkId：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选，但无稳定 senderId 命中不得作完整否定结论。不传时原样读取会话且不查询发送者身份。sender 仅是展示名，身份只比较稳定 senderId；" + + Intent: "当你要读取或导出一个指定群聊或单聊的消息记录时使用；--sender 是可选的姓名、userId 或 openDingTalkId 混合入口：姓名优先唯一解析，稳定 ID 精确路由；通讯录无法分类时仍按原值 userId 筛选并保留 identity_unverified，可交付精确命中但不能把原值升级为已验证身份或作完整否定结论。--sender-query 只按姓名唯一解析，解析失败会抑制未过滤消息并返回错误。不传发送者条件时原样读取会话且不查询发送者身份。sender 展示名不参与身份比较；" + "群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" + "省略时间参数时默认从当前时间向前读取最近消息；兼容模式可用 --time/--direction，范围模式可用公开可选的 --start/--end/--order（兼容 --start-time/--end-time/--sort），范围语义为 [start,end)。" + "全量读取用 --page-all，并由 --page-limit/--max-items 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" + From caf81b7984eb4a22f5b40758d20542b456d60b29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B9=8B=E6=A1=90?= <1241839690@qq.com> Date: Mon, 17 Aug 2026 15:30:20 +0800 Subject: [PATCH 190/250] feat(comments): add doc and sheet lifecycle commands --- .changes/doc-sheet-comment-lifecycle.md | 10 + internal/helpers/comment_base.go | 328 ++++++++++++++++++++++++ internal/helpers/comment_base_test.go | 174 +++++++++++++ internal/helpers/doc.go | 1 + internal/helpers/sheet_comment.go | 1 + 5 files changed, 514 insertions(+) create mode 100644 .changes/doc-sheet-comment-lifecycle.md create mode 100644 internal/helpers/comment_base.go create mode 100644 internal/helpers/comment_base_test.go diff --git a/.changes/doc-sheet-comment-lifecycle.md b/.changes/doc-sheet-comment-lifecycle.md new file mode 100644 index 00000000..bd76c1f2 --- /dev/null +++ b/.changes/doc-sheet-comment-lifecycle.md @@ -0,0 +1,10 @@ +--- +category: Added +--- + +- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`, + `comment resolve`, `comment restore`, and the lightweight + `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share + the same `doc-comment` MCP capabilities; batch queries preserve input order + for repeated `topicId:commentKey` references, while reaction replies require + DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji. diff --git a/internal/helpers/comment_base.go b/internal/helpers/comment_base.go new file mode 100644 index 00000000..81f0c8e3 --- /dev/null +++ b/internal/helpers/comment_base.go @@ -0,0 +1,328 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package helpers + +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + "github.com/spf13/cobra" +) + +const commentServer = "doc-comment" + +var commentBatchResultSchema = json.RawMessage(`{ + "type":"object", + "description":"按请求顺序返回的评论详情", + "properties":{ + "commentList":{ + "type":"array", + "description":"与请求 comments 顺序一致的评论详情列表", + "items":{ + "type":"object", + "description":"单条评论查询结果；不存在时 found=false", + "properties":{ + "topicId":{"type":"string","description":"评论主题 ID"}, + "commentKey":{"type":"string","description":"评论唯一标识"}, + "found":{"type":"boolean","description":"该 topicId/commentKey 是否存在"}, + "content":{"type":["string","null"],"description":"纯文本评论内容"}, + "quote":{"type":["string","null"],"description":"划词评论引用内容"}, + "creatorId":{"type":["string","null"],"description":"创建者用户 ID"}, + "createTime":{"type":["integer","null"],"description":"创建时间，毫秒时间戳"}, + "updateTime":{"type":["integer","null"],"description":"更新时间，毫秒时间戳"}, + "isSolved":{"type":["boolean","null"],"description":"是否已解决"}, + "isEmoji":{"type":["boolean","null"],"description":"是否为表情回复"}, + "replyCommentKey":{"type":["string","null"],"description":"被回复评论的标识"} + }, + "required":["topicId","commentKey","found"], + "additionalProperties":true + } + } + }, + "required":["commentList"], + "additionalProperties":true +}`) + +var commentStatusResultSchema = json.RawMessage(`{ + "type":"object", + "description":"评论解决状态更新结果", + "properties":{ + "commentKey":{"type":"string","description":"评论唯一标识"}, + "resolved":{"type":"boolean","description":"更新后的解决状态"}, + "message":{"type":"string","description":"操作结果消息"} + }, + "required":["commentKey","resolved"], + "additionalProperties":true +}`) + +var commentReactionResultSchema = json.RawMessage(`{ + "type":"object", + "description":"表情回复创建结果", + "properties":{ + "commentKey":{"type":"string","description":"新建表情回复的评论标识"}, + "message":{"type":"string","description":"操作结果消息"} + }, + "required":["commentKey"], + "additionalProperties":true +}`) + +// newCommentBaseCommands returns the base comment commands shared by Doc and Sheet. +// Both resource domains call the same comment MCP tools; only CLI identity and +// guidance differ. +func newCommentBaseCommands(surface string) []*cobra.Command { + batchCmd := newCommentBatchQueryCommand(surface) + resolveCmd := newCommentStatusCommand(surface, true) + restoreCmd := newCommentStatusCommand(surface, false) + reactCmd := newCommentReactionCommand(surface) + commands := []*cobra.Command{batchCmd, resolveCmd, restoreCmd, reactCmd} + for _, cmd := range commands { + addCommentNodeAliases(cmd) + } + return commands +} + +func newCommentBatchQueryCommand(surface string) *cobra.Command { + resourceName := commentResourceName(surface) + cmd := &cobra.Command{ + Use: "batch-query", + Aliases: []string{"batch-query-comments", "batch"}, + Short: "按 topicId + commentKey 批量查询评论详情", + Long: `批量查询同一文档或表格中的评论详情，单次最多 100 条。 + +--comment-ref 可重复传入，格式为 topicId:commentKey。topicId 和 commentKey +均可从 comment list 的返回结果中获得。结果严格保持输入顺序；不存在的评论 +会返回 found=false 的占位项。`, + Example: fmt.Sprintf(" dws %s comment batch-query --node --comment-ref global: --comment-ref : --format json", surface), + RunE: func(cmd *cobra.Command, args []string) error { + nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id") + if err != nil { + return err + } + rawRefs, _ := cmd.Flags().GetStringSlice("comment-ref") + refs, err := parseCommentRefs(rawRefs) + if err != nil { + return err + } + return callMCPToolOnServer(commentServer, "batch_query_comments", map[string]any{ + "nodeId": nodeID, + "comments": refs, + }) + }, + } + DeclareLeafMetadata(cmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: commentIdentity(surface, "batch_query_comments", "batch-query"), + Description: "按 topicId + commentKey 批量查询评论详情，保持输入顺序并显式标记缺失项", + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: commentBatchResultSchema, + }, + Interface: commentInterface("batch_query_comments"), + Selection: contract.SelectionSpec{ + AgentSummary: "已知多组 topicId/commentKey 时，一次获取完整评论详情", + UseWhen: []string{fmt.Sprintf("需要回查%s comment list 结果中的多条评论详情，或批量核对评论是否仍存在时", resourceName)}, + AvoidWhen: []string{fmt.Sprintf("尚未取得%s评论的 topicId/commentKey 时先使用 comment list", resourceName)}, + Examples: []string{fmt.Sprintf("dws %s comment batch-query --node --comment-ref : --format json", surface)}, + }, + Parameters: []contract.ParamDecl{ + {Name: "node", Property: "nodeId"}, + {Name: "comment-ref", Property: "comments", InterfaceType: "array"}, + }, + }, + }) + cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)") + cmd.Flags().StringSlice("comment-ref", nil, "评论引用 topicId:commentKey，可重复；最多 100 条 (必填)") + return cmd +} + +func newCommentStatusCommand(surface string, resolve bool) *cobra.Command { + resourceName := commentResourceName(surface) + use := "restore" + rpc := "restore_comment" + short := "将已解决评论恢复为未解决" + resolved := false + if resolve { + use = "resolve" + rpc = "resolve_comment" + short = "将评论标记为已解决" + resolved = true + } + cmd := &cobra.Command{ + Use: use, + Aliases: []string{use + "-comment"}, + Short: short, + Example: fmt.Sprintf(" dws %s comment %s --node --comment-key --format json", surface, use), + RunE: func(cmd *cobra.Command, args []string) error { + nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id") + if err != nil { + return err + } + if err := validateRequiredFlags(cmd, "comment-key"); err != nil { + return err + } + return callMCPToolOnServer(commentServer, rpc, map[string]any{ + "nodeId": nodeID, + "commentKey": mustGetFlag(cmd, "comment-key"), + }) + }, + } + DeclareLeafMetadata(cmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent", + }, + Contract: LeafContract{ + Identity: commentIdentity(surface, rpc, use), + Description: short, + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: commentStatusResultSchema, + }, + Interface: commentInterface(rpc), + Selection: contract.SelectionSpec{ + AgentSummary: short, + UseWhen: []string{fmt.Sprintf("用户明确要求把%s中的某条评论标记为%s时", resourceName, map[bool]string{true: "已解决", false: "未解决"}[resolved])}, + AvoidWhen: []string{fmt.Sprintf("永久删除%s评论使用 comment delete；修改文字使用 comment update", resourceName)}, + Examples: []string{fmt.Sprintf("dws %s comment %s --node --comment-key --format json", surface, use)}, + }, + Parameters: []contract.ParamDecl{ + {Name: "node", Property: "nodeId"}, + {Name: "comment-key", Property: "commentKey"}, + }, + }, + }) + cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)") + cmd.Flags().String("comment-key", "", "目标评论的 commentKey (必填)") + return cmd +} + +func newCommentReactionCommand(surface string) *cobra.Command { + resourceName := commentResourceName(surface) + cmd := &cobra.Command{ + Use: "react-reply", + Short: "创建一条表情回复", + Long: `创建表情回复的便捷命令。底层复用 reply_comment，并固定传入 emoji=true。 + +与 comment reply --emoji 一致，--reaction 必须填写钉钉表情名称，不要直接传 +Unicode Emoji。例如用户要求 😄 时传“憨笑”，要求 👏 时传“鼓掌”。 + +当前轻量版仅支持创建，不包含删除或聚合能力。`, + Example: fmt.Sprintf(" dws %s comment react-reply --node --comment-key --reaction \"憨笑\" --format json", surface), + RunE: func(cmd *cobra.Command, args []string) error { + nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id") + if err != nil { + return err + } + if err := validateRequiredFlags(cmd, "comment-key", "reaction"); err != nil { + return err + } + return callMCPToolOnServer(commentServer, "reply_comment", map[string]any{ + "nodeId": nodeID, + "replyCommentKey": mustGetFlag(cmd, "comment-key"), + "content": mustGetFlag(cmd, "reaction"), + "emoji": true, + }) + }, + } + DeclareLeafMetadata(cmd, LeafSpec{ + Safety: contract.SafetySpec{ + Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "non_idempotent", + }, + Contract: LeafContract{ + Identity: commentIdentity(surface, "react_reply", "react-reply"), + Description: "为指定评论创建表情回复（轻量版）", + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: commentReactionResultSchema, + }, + Interface: commentInterface("reply_comment"), + Selection: contract.SelectionSpec{ + AgentSummary: "使用钉钉表情名称为指定评论创建表情回复", + UseWhen: []string{fmt.Sprintf("用户要用表情回应%s中的某条评论时；先将 Unicode Emoji 转为钉钉表情名称，例如 😄 转为憨笑、👏 转为鼓掌", resourceName)}, + AvoidWhen: []string{fmt.Sprintf("%s评论的普通文字回复使用 comment reply；当前轻量版不支持删除 reaction", resourceName)}, + Examples: []string{fmt.Sprintf("dws %s comment react-reply --node --comment-key --reaction \"憨笑\" --format json", surface)}, + }, + Parameters: []contract.ParamDecl{ + {Name: "node", Property: "nodeId"}, + {Name: "comment-key", Property: "replyCommentKey"}, + {Name: "reaction", Property: "content"}, + }, + }, + }) + cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)") + cmd.Flags().String("comment-key", "", "被回应评论的 commentKey (必填)") + cmd.Flags().String("reaction", "", "钉钉表情名称，不是 Unicode Emoji；例如 😄=憨笑、👏=鼓掌 (必填)") + return cmd +} + +func parseCommentRefs(rawRefs []string) ([]map[string]any, error) { + if len(rawRefs) == 0 { + return nil, fmt.Errorf("missing required flag(s): --comment-ref") + } + if len(rawRefs) > 100 { + return nil, fmt.Errorf("--comment-ref 最多可传 100 条，当前为 %d 条", len(rawRefs)) + } + refs := make([]map[string]any, 0, len(rawRefs)) + for index, raw := range rawRefs { + parts := strings.SplitN(strings.TrimSpace(raw), ":", 2) + if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || strings.TrimSpace(parts[1]) == "" { + return nil, fmt.Errorf("invalid --comment-ref[%d] %q: expected topicId:commentKey", index, raw) + } + refs = append(refs, map[string]any{ + "topicId": strings.TrimSpace(parts[0]), + "commentKey": strings.TrimSpace(parts[1]), + }) + } + return refs, nil +} + +func addCommentNodeAliases(cmd *cobra.Command) { + cmd.Flags().String("url", "", "") + cmd.Flags().String("id", "", "") + cmd.Flags().String("node-id", "", "") + cmd.Flags().String("doc-id", "", "") + cmd.Flags().String("file-id", "", "") + for _, name := range []string{"url", "id", "node-id", "doc-id", "file-id"} { + _ = cmd.Flags().MarkHidden(name) + } +} + +func commentIdentity(surface, name, cliLeaf string) contract.ToolIdentitySpec { + return contract.ToolIdentitySpec{ + ProductID: surface, + Name: name, + CanonicalPath: surface + "." + name, + CLIPath: surface + " comment " + cliLeaf, + PrimaryCLIPath: surface + " comment " + cliLeaf, + } +} + +func commentResourceName(surface string) string { + if surface == "sheet" { + return "表格" + } + return "文档" +} + +func commentInterface(rpc string) *contract.InterfaceSpec { + return &contract.InterfaceSpec{ + Mode: "mcp", + Availability: "available", + Ref: &contract.InterfaceRefSpec{ProductID: commentServer, RPCName: rpc}, + } +} diff --git a/internal/helpers/comment_base_test.go b/internal/helpers/comment_base_test.go new file mode 100644 index 00000000..2d6e8638 --- /dev/null +++ b/internal/helpers/comment_base_test.go @@ -0,0 +1,174 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package helpers + +import ( + "io" + "os" + "reflect" + "strings" + "testing" + + "github.com/spf13/cobra" +) + +func executeCommentBaseCommand(t *testing.T, caller *docCommentMutationCaller, surface string, args ...string) error { + t.Helper() + previousDeps := deps + previousArgs := os.Args + t.Cleanup(func() { + deps = previousDeps + os.Args = previousArgs + }) + + InitDeps(caller) + deps.Out.w = io.Discard + os.Args = []string{"dws", surface} + var cmd *cobra.Command + if surface == "sheet" { + cmd = newSheetCommand() + } else { + cmd = newDocCommand() + } + cmd.PersistentFlags().Bool("yes", false, "skip confirmation") + cmd.SilenceErrors = true + cmd.SilenceUsage = true + cmd.SetArgs(args) + return cmd.Execute() +} + +func TestCrossPlatformCoverageCommentBaseCommandsRegisteredForDocAndSheet(t *testing.T) { + for _, surface := range []struct { + name string + cmd *cobra.Command + }{ + {name: "doc", cmd: newDocCommand()}, + {name: "sheet", cmd: newSheetCommand()}, + } { + for _, leaf := range []string{"batch-query", "resolve", "restore", "react-reply"} { + cmd, remaining, err := surface.cmd.Find([]string{"comment", leaf}) + if err != nil || len(remaining) != 0 { + t.Fatalf("dws %s comment %s not registered: cmd=%v remaining=%v err=%v", + surface.name, leaf, cmd, remaining, err) + } + } + } +} + +func TestCrossPlatformCoverageDocCommentBatchQueryMapsStructuredRefs(t *testing.T) { + caller := &docCommentMutationCaller{} + err := executeCommentBaseCommand(t, caller, "doc", + "comment", "batch-query", "--node", "doc-1", + "--comment-ref", "global:comment-1", "--comment-ref", "topic-2:comment-2") + if err != nil { + t.Fatal(err) + } + want := docCommentMutationCall{ + productID: commentServer, + toolName: "batch_query_comments", + args: map[string]any{ + "nodeId": "doc-1", + "comments": []map[string]any{ + {"topicId": "global", "commentKey": "comment-1"}, + {"topicId": "topic-2", "commentKey": "comment-2"}, + }, + }, + } + if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) { + t.Fatalf("calls = %#v, want %#v", caller.calls, want) + } +} + +func TestCrossPlatformCoverageSheetCommentResolveAndRestoreUseSharedRPCs(t *testing.T) { + caller := &docCommentMutationCaller{} + if err := executeCommentBaseCommand(t, caller, "sheet", + "comment", "resolve", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil { + t.Fatal(err) + } + if err := executeCommentBaseCommand(t, caller, "sheet", + "comment", "restore", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil { + t.Fatal(err) + } + if len(caller.calls) != 2 { + t.Fatalf("calls = %#v", caller.calls) + } + if caller.calls[0].toolName != "resolve_comment" || caller.calls[1].toolName != "restore_comment" { + t.Fatalf("tools = %q, %q", caller.calls[0].toolName, caller.calls[1].toolName) + } + wantArgs := map[string]any{"nodeId": "sheet-1", "commentKey": "comment-1"} + if !reflect.DeepEqual(caller.calls[0].args, wantArgs) || !reflect.DeepEqual(caller.calls[1].args, wantArgs) { + t.Fatalf("calls = %#v, want args %#v", caller.calls, wantArgs) + } +} + +func TestCrossPlatformCoverageCommentReactReplyForcesEmojiTrue(t *testing.T) { + caller := &docCommentMutationCaller{} + err := executeCommentBaseCommand(t, caller, "doc", + "comment", "react-reply", "--file-id", "doc-1", + "--comment-key", "comment-1", "--reaction", "鼓掌") + if err != nil { + t.Fatal(err) + } + want := docCommentMutationCall{ + productID: commentServer, + toolName: "reply_comment", + args: map[string]any{ + "nodeId": "doc-1", + "replyCommentKey": "comment-1", + "content": "鼓掌", + "emoji": true, + }, + } + if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) { + t.Fatalf("calls = %#v, want %#v", caller.calls, want) + } +} + +func TestCrossPlatformCoverageCommentReactReplyGuidesDingTalkEmojiNames(t *testing.T) { + for _, surface := range []struct { + name string + cmd *cobra.Command + }{ + {name: "doc", cmd: newDocCommand()}, + {name: "sheet", cmd: newSheetCommand()}, + } { + cmd, remaining, err := surface.cmd.Find([]string{"comment", "react-reply"}) + if err != nil || len(remaining) != 0 { + t.Fatalf("dws %s comment react-reply lookup: remaining=%v err=%v", surface.name, remaining, err) + } + reaction := cmd.Flags().Lookup("reaction") + if reaction == nil || !strings.Contains(reaction.Usage, "不是 Unicode Emoji") || !strings.Contains(reaction.Usage, "😄=憨笑") { + t.Fatalf("dws %s reaction guidance = %#v", surface.name, reaction) + } + if !strings.Contains(cmd.Long, "不要直接传") || !strings.Contains(cmd.Example, `--reaction "憨笑"`) { + t.Fatalf("dws %s react-reply help missing DingTalk emoji-name guidance", surface.name) + } + } +} + +func TestCrossPlatformCoverageParseCommentRefsRejectsInvalidShapeAndLimit(t *testing.T) { + if _, err := parseCommentRefs(nil); err == nil { + t.Fatal("missing refs returned nil error") + } + if _, err := parseCommentRefs([]string{"missing-separator"}); err == nil { + t.Fatal("invalid ref returned nil error") + } + tooMany := make([]string, 101) + for index := range tooMany { + tooMany[index] = "global:comment" + } + if _, err := parseCommentRefs(tooMany); err == nil { + t.Fatal("101 refs returned nil error") + } +} diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index 19c0241e..c1740468 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -3517,6 +3517,7 @@ commentKey可从 dws doc comment create 或 dws doc comment list 返回结果中 } commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd, commentCreateInlineCmd) + commentCmd.AddCommand(newCommentBaseCommands("doc")...) // ── permission (文档协作权限) ──────────────────────────── permissionCmd := &cobra.Command{ diff --git a/internal/helpers/sheet_comment.go b/internal/helpers/sheet_comment.go index dc6f0710..c0b62612 100644 --- a/internal/helpers/sheet_comment.go +++ b/internal/helpers/sheet_comment.go @@ -304,5 +304,6 @@ func newSheetCommentCmd() *cobra.Command { } commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd) + commentCmd.AddCommand(newCommentBaseCommands("sheet")...) return commentCmd } From b20055a0b54122d31017fe3024f20408f85f5c75 Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 18:48:39 +0800 Subject: [PATCH 191/250] test(shortcut): close calendar todo coverage gaps --- ...additional_cross_platform_coverage_test.go | 482 ++++++++++++++ .../calendar_cross_platform_coverage_test.go | 3 +- internal/shortcut/smart/calendar_shared.go | 3 - ...dar_strict_cross_platform_coverage_test.go | 206 ++++++ ...additional_cross_platform_coverage_test.go | 288 +++++++++ ...additional_cross_platform_coverage_test.go | 610 ++++++++++++++++++ 6 files changed, 1588 insertions(+), 4 deletions(-) create mode 100644 internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go create mode 100644 internal/shortcut/smart/shortcut_additional_cross_platform_coverage_test.go create mode 100644 internal/shortcut/todo/todo_additional_cross_platform_coverage_test.go diff --git a/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go new file mode 100644 index 00000000..840fc61e --- /dev/null +++ b/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go @@ -0,0 +1,482 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package calendar + +import ( + "math" + "strconv" + "strings" + "testing" + "time" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +const ( + calendarCoverageStart = "2026-08-17T09:00:00+08:00" + calendarCoverageEnd = "2026-08-17T10:00:00+08:00" + calendarCoverageEvent = `{"success":true,"result":{"id":"event-1","summary":"updated","description":"description","start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"},"timeZone":"Asia/Shanghai","location":"room","freeBusy":"busy"}}` +) + +func calendarRuntimeForTest(t *testing.T, declaration shortcut.Shortcut, values map[string]string) *shortcut.RuntimeContext { + t.Helper() + cmd := corecmd.New(shortcut.FromShortcut(declaration)) + for name, value := range values { + if err := cmd.Flags().Set(name, value); err != nil { + t.Fatalf("set --%s: %v", name, err) + } + } + return shortcut.RuntimeContextForTest(cmd, declaration) +} + +func TestCrossPlatformCoverageCalendarCommonBranches(t *testing.T) { + if got := calendarExample("+unknown"); !strings.Contains(got, "+unknown") { + t.Fatalf("default example=%q", got) + } + if calendarReadShortcut("+x", "x", "x", "items", nil, nil, nil).Contract.Result == nil { + t.Fatal("collection read shortcut did not build a result") + } + if calendarWriteShortcut("+x", "x", "x", "dws calendar +x", nil, nil, nil).Safety.Confirmation != "user_required" { + t.Fatal("write shortcut did not build safety") + } + + badResponses := []map[string]any{ + {"success": "yes"}, + {"success": false}, + {"result": map[string]any{}}, + } + for _, response := range badResponses { + if _, err := requireCalendarObject(response, "calendar/test"); err == nil { + t.Fatalf("bad object accepted: %#v", response) + } + } + if got := calendarContainers(nil); got != nil { + t.Fatalf("nil containers=%#v", got) + } + if !calendarOnlyEnvelopeFields(map[string]any{"success": true, "result": map[string]any{}}) || calendarOnlyEnvelopeFields(map[string]any{"id": "x"}) { + t.Fatal("envelope field classification drift") + } + + if _, _, err := requireCalendarCollection(map[string]any{"success": false}, "calendar/test", "items"); err == nil { + t.Fatal("failed response accepted as collection") + } + if _, _, err := requireCalendarCollection(map[string]any{"success": true, "result": []any{"bad"}}, "calendar/test", "items"); err == nil { + t.Fatal("bad wrapper array accepted") + } + items, _, err := requireCalendarCollection(map[string]any{"success": true, "result": []any{map[string]any{"id": "x"}}}, "calendar/test", "items") + if err != nil || len(items) != 1 { + t.Fatalf("wrapper array rejected: %#v %v", items, err) + } + if _, err := projectCalendarRows([]any{map[string]any{"ignored": "x"}}, "calendar/test", map[string][]string{"id": {"id"}}, "id"); err == nil { + t.Fatal("unidentifiable projected row accepted") + } + if !calendarEmptyValue(nil) || !calendarEmptyValue(" ") || calendarEmptyValue(1) { + t.Fatal("calendarEmptyValue classification drift") + } + + if page, err := calendarPagination(nil, "calendar/test"); err != nil || page.Known { + t.Fatalf("nil pagination=%+v %v", page, err) + } + for _, container := range []map[string]any{ + {"hasMore": "yes"}, + {"hasMore": true, "nextCursor": 1}, + {"hasMore": false, "nextCursor": "cursor"}, + } { + if _, err := calendarPagination(container, "calendar/test"); err == nil { + t.Fatalf("bad pagination accepted: %#v", container) + } + } + if _, err := calendarPagination(map[string]any{"nextToken": "cursor"}, "calendar/test"); err == nil { + t.Fatal("cursor without hasMore accepted") + } + page, err := calendarPagination(map[string]any{"hasMore": true, "nextToken": "cursor"}, "calendar/test") + if err != nil || !page.Known || !page.HasMore || page.NextCursor != "cursor" { + t.Fatalf("cursor-only pagination=%+v %v", page, err) + } + out := map[string]any{} + addCalendarPagination(out, page) + if out["nextCursor"] != "cursor" || out["hasMore"] != true { + t.Fatalf("pagination output=%#v", out) + } + + if _, _, err := validateCalendarRange("start", "bad", "end", calendarCoverageEnd); err == nil { + t.Fatal("bad start accepted") + } + if _, _, err := validateCalendarRange("start", calendarCoverageStart, "end", "bad"); err == nil { + t.Fatal("bad end accepted") + } + if _, _, err := validateCalendarRange("start", calendarCoverageEnd, "end", calendarCoverageStart); err == nil { + t.Fatal("reversed range accepted") + } + if got := calendarStringList([]string{" a ", "", "a", "b"}); len(got) != 2 { + t.Fatalf("deduplicated list=%#v", got) + } + + want := time.Date(2026, 8, 17, 1, 0, 0, 0, time.UTC) + millis := want.UnixMilli() + for _, actual := range []any{ + map[string]any{"value": calendarCoverageStart}, + calendarCoverageStart, + strconv.FormatInt(millis, 10), + float64(millis), int64(millis), int(millis), + } { + if !calendarTimeEquivalent(actual, calendarCoverageStart) { + t.Fatalf("equivalent time rejected: %#v", actual) + } + } + for _, actual := range []any{math.NaN(), math.Inf(1), 1.5, struct{}{}} { + if calendarTimeEquivalent(actual, calendarCoverageStart) { + t.Fatalf("bad time accepted: %#v", actual) + } + } + if calendarTimeEquivalent(calendarCoverageStart, "bad") { + t.Fatal("bad expected time accepted") + } + + base := map[string]any{"id": "event-1", "summary": "updated", "start": map[string]any{"dateTime": calendarCoverageStart}} + if err := verifyCalendarEvent(base, "wrong", nil); err == nil { + t.Fatal("wrong event id accepted") + } + if err := verifyCalendarEvent(base, "event-1", map[string]any{"unknown": "ignored"}); err != nil { + t.Fatalf("unknown verification field rejected: %v", err) + } + if err := verifyCalendarEvent(base, "event-1", map[string]any{"description": "x"}); err == nil { + t.Fatal("missing readback field accepted") + } + if err := verifyCalendarEvent(base, "event-1", map[string]any{"summary": "wrong"}); err == nil { + t.Fatal("mismatched readback field accepted") + } + if err := verifyCalendarEvent(base, "event-1", map[string]any{"startDateTime": calendarCoverageEnd}); err == nil { + t.Fatal("mismatched readback time accepted") + } + item := shortcut.Shortcut{Description: "description", Intent: "intent"} + finalizeCalendarShortcut(&item, calendarObjectResult("result"), calendarCursorPagination()) + if item.Contract.Interface == nil || item.Contract.Result == nil || item.Contract.Pagination == nil { + t.Fatalf("finalized shortcut=%#v", item) + } + pageShortcut := EventGet + pageShortcut.Execute = func(rt *shortcut.RuntimeContext) error { + return outputCalendarPage(rt, map[string]any{"count": 0}, calendarPageEvidence{}) + } + if err := runCalendarCoverage(t, pageShortcut, &calendarCoverageCaller{responses: map[string][]string{}}, "--event", "event-1"); err == nil { + t.Fatal("unknown pagination was emitted") + } + pageShortcut.Execute = func(rt *shortcut.RuntimeContext) error { + return outputCalendarPage(rt, map[string]any{"count": 0}, calendarPageEvidence{Known: true, NextCursor: "cursor"}) + } + if err := runCalendarCoverage(t, pageShortcut, &calendarCoverageCaller{responses: map[string][]string{}}, "--event", "event-1"); err == nil { + t.Fatal("inconsistent pagination was emitted") + } + legacyPage := EventGet + legacyPage.OutputRollout = output.RolloutLegacyOnly + legacyPage.Execute = func(rt *shortcut.RuntimeContext) error { + return outputCalendarPage(rt, map[string]any{"count": 0}, calendarPageEvidence{Known: true}) + } + if err := runCalendarCoverage(t, legacyPage, &calendarCoverageCaller{responses: map[string][]string{}}, "--event", "event-1"); err != nil { + t.Fatalf("legacy pagination output: %v", err) + } +} + +func TestCrossPlatformCoverageCalendarEventGetSearchAndSuggestion(t *testing.T) { + get := &calendarCoverageCaller{responses: map[string][]string{"get_calendar_detail": {`{"success":true,"result":{"id":"event-1"}}`}}} + if err := runCalendarCoverage(t, EventGet, get, "--event", "event-1", "--calendar-id", "primary"); err != nil { + t.Fatal(err) + } + getFailure := &calendarCoverageCaller{responses: map[string][]string{"get_calendar_detail": {"__ERROR__"}}} + if err := runCalendarCoverage(t, EventGet, getFailure, "--event", "event-1"); err == nil { + t.Fatal("get transport failure accepted") + } + + search := &calendarCoverageCaller{responses: map[string][]string{"list_calendar_events": {`{"success":true,"result":{"events":[{"id":"event-1","summary":"Needle","description":"body","location":"room"},{"id":"event-2","summary":"other"}],"hasMore":true,"nextCursor":"next"}}`}}} + if err := runCalendarCoverage(t, EventSearch, search, "--query", "needle", "--start", calendarCoverageStart, "--end", calendarCoverageEnd, "--calendar-id", "primary", "--cursor", "cursor", "--limit", "2"); err != nil { + t.Fatal(err) + } + for name, response := range map[string]string{ + "call": "__ERROR__", + "collection": `{"success":true,"result":{"hasMore":false}}`, + "item": `{"success":true,"result":{"events":[{"summary":"x"}],"hasMore":false}}`, + "pagination-bad": `{"success":true,"result":{"events":[],"hasMore":"bad"}}`, + "pagination": `{"success":true,"result":{"events":[]}}`, + } { + t.Run("search-"+name, func(t *testing.T) { + caller := &calendarCoverageCaller{responses: map[string][]string{"list_calendar_events": {response}}} + if err := runCalendarCoverage(t, EventSearch, caller, "--query", "x"); err == nil { + t.Fatal("bad search response accepted") + } + }) + } + + suggestion := &calendarCoverageCaller{responses: map[string][]string{"list_suggested_event_times": {`{"success":true,"result":{"recommendEventTimes":[{"startTime":"2026-08-17T09:00:00+08:00","endTime":"2026-08-17T10:00:00+08:00"}]}}`}}} + if err := runCalendarCoverage(t, Suggestion, suggestion, "--users", " user-1,user-1 ", "--duration", "30", "--start", calendarCoverageStart, "--end", calendarCoverageEnd, "--timezone", "Asia/Shanghai"); err != nil { + t.Fatal(err) + } + for name, args := range map[string][]string{ + "duration": {"--users", "u", "--duration", "0"}, + "range-pair": {"--users", "u", "--start", calendarCoverageStart}, + "range-order": {"--users", "u", "--start", calendarCoverageEnd, "--end", calendarCoverageStart}, + } { + t.Run("suggestion-"+name, func(t *testing.T) { + if err := runCalendarCoverage(t, Suggestion, &calendarCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad suggestion arguments accepted") + } + }) + } + emptyUsers := Suggestion + for index := range emptyUsers.Flags { + if emptyUsers.Flags[index].Name == "users" { + emptyUsers.Flags[index].Required = false + } + } + if err := runCalendarCoverage(t, emptyUsers, &calendarCoverageCaller{responses: map[string][]string{}}); err == nil { + t.Fatal("empty suggestion users accepted") + } + for name, response := range map[string]string{ + "call": "__ERROR__", + "collection": `{"success":true,"result":{}}`, + "projection": `{"success":true,"result":{"recommendEventTimes":[{"endTime":"x"}]}}`, + "missing-end": `{"success":true,"result":{"recommendEventTimes":[{"startTime":"x"}]}}`, + } { + t.Run("suggestion-response-"+name, func(t *testing.T) { + caller := &calendarCoverageCaller{responses: map[string][]string{"list_suggested_event_times": {response}}} + if err := runCalendarCoverage(t, Suggestion, caller, "--users", "u"); err == nil { + t.Fatal("bad suggestion response accepted") + } + }) + } +} + +func TestCrossPlatformCoverageCalendarCreateAndRSVPBranches(t *testing.T) { + attendees := make([]string, 501) + for index := range attendees { + attendees[index] = "u" + strconv.Itoa(index) + } + for name, args := range map[string][]string{ + "title": {"--title", strings.Repeat("x", 2049), "--start", calendarCoverageStart, "--end", calendarCoverageEnd}, + "desc": {"--title", "x", "--desc", strings.Repeat("x", 5001), "--start", calendarCoverageStart, "--end", calendarCoverageEnd}, + "range": {"--title", "x", "--start", calendarCoverageEnd, "--end", calendarCoverageStart}, + "attendees": {"--title", "x", "--attendees", strings.Join(attendees, ","), "--start", calendarCoverageStart, "--end", calendarCoverageEnd}, + } { + t.Run("create-args-"+name, func(t *testing.T) { + if err := runCalendarCoverage(t, EventCreate, &calendarCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad create args accepted") + } + }) + } + directCases := []map[string]string{ + {"title": strings.Repeat("x", 2049), "start": calendarCoverageStart, "end": calendarCoverageEnd}, + {"title": "x", "desc": strings.Repeat("x", 5001), "start": calendarCoverageStart, "end": calendarCoverageEnd}, + {"title": "x", "start": calendarCoverageEnd, "end": calendarCoverageStart}, + {"title": "x", "attendees": strings.Join(attendees, ","), "start": calendarCoverageStart, "end": calendarCoverageEnd}, + } + for index, values := range directCases { + rt := calendarRuntimeForTest(t, EventCreate, values) + if _, _, err := calendarCreateParams(rt); err == nil { + t.Fatalf("direct invalid create case %d accepted", index) + } + } + if err := EventCreate.Execute(calendarRuntimeForTest(t, EventCreate, directCases[0])); err == nil { + t.Fatal("create execute accepted invalid params") + } + if err := runCalendarCoverage(t, EventCreate, &calendarCoverageCaller{responses: map[string][]string{}}, "--title", "x", "--start", calendarCoverageStart, "--end", calendarCoverageEnd, "--dry-run", "--yes"); err != nil { + t.Fatalf("create dry-run: %v", err) + } + for name, responses := range map[string]map[string][]string{ + "write-call": {"create_calendar_event": {"__ERROR__"}}, + "write-shape": {"create_calendar_event": {`{"result":{"id":"event-1"}}`}}, + "missing-id": {"create_calendar_event": {`{"success":true,"result":{}}`}}, + "read-call": {"create_calendar_event": {`{"success":true,"result":{"id":"event-1"}}`}, "get_calendar_detail": {"__ERROR__"}}, + "read-shape": {"create_calendar_event": {`{"success":true,"result":{"id":"event-1"}}`}, "get_calendar_detail": {`{"success":true,"result":{}}`}}, + "read-mismatch": {"create_calendar_event": {`{"success":true,"result":{"id":"event-1"}}`}, "get_calendar_detail": {`{"success":true,"result":{"id":"event-1","summary":"wrong","start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"}}}`}}, + } { + t.Run("create-"+name, func(t *testing.T) { + caller := &calendarCoverageCaller{responses: responses} + if err := runCalendarCoverage(t, EventCreate, caller, "--title", "x", "--start", calendarCoverageStart, "--end", calendarCoverageEnd, "--calendar-id", "primary", "--yes"); err == nil { + t.Fatal("bad create path accepted") + } + }) + } + + preflight := `{"success":true,"result":{"id":"event-1"}}` + if err := runCalendarCoverage(t, RSVP, &calendarCoverageCaller{responses: map[string][]string{"get_calendar_detail": {preflight}}}, "--event", "event-1", "--status", "accept", "--dry-run", "--yes"); err != nil { + t.Fatalf("rsvp dry-run: %v", err) + } + for name, responses := range map[string]map[string][]string{ + "preflight-call": {"get_calendar_detail": {"__ERROR__"}}, + "preflight-shape": {"get_calendar_detail": {`{"success":true,"result":{}}`}}, + "write-call": {"get_calendar_detail": {preflight}, "respond": {"__ERROR__"}}, + "write-shape": {"get_calendar_detail": {preflight}, "respond": {`{"result":{}}`}}, + "read-call": {"get_calendar_detail": {preflight, "__ERROR__"}, "respond": {`{"success":true}`}}, + "read-shape": {"get_calendar_detail": {preflight, `{"success":true,"result":{}}`}, "respond": {`{"success":true}`}}, + "read-mismatch": {"get_calendar_detail": {preflight, `{"success":true,"result":{"id":"event-1","responseStatus":"declined"}}`}, "respond": {`{"success":true}`}}, + "write-mismatch": {"get_calendar_detail": {preflight, preflight}, "respond": {`{"success":true,"result":{"status":"declined"}}`}}, + } { + t.Run("rsvp-"+name, func(t *testing.T) { + if err := runCalendarCoverage(t, RSVP, &calendarCoverageCaller{responses: responses}, "--event", "event-1", "--status", "accept", "--calendar-id", "primary", "--yes"); err == nil { + t.Fatal("bad RSVP path accepted") + } + }) + } + for name, write := range map[string]string{"readback": `{"success":true}`, "terminal": `{"success":true,"result":{"status":"accepted"}}`} { + t.Run("rsvp-success-"+name, func(t *testing.T) { + read := preflight + if name == "readback" { + read = `{"success":true,"result":{"id":"event-1","responseStatus":"accepted"}}` + } + caller := &calendarCoverageCaller{responses: map[string][]string{"get_calendar_detail": {preflight, read}, "respond": {write}}} + if err := runCalendarCoverage(t, RSVP, caller, "--event", "event-1", "--status", "accept", "--yes"); err != nil { + t.Fatal(err) + } + }) + } +} + +func TestCrossPlatformCoverageCalendarUpdateStages(t *testing.T) { + for name, args := range map[string][]string{ + "none": {"--event", "event-1", "--yes"}, + "pair": {"--event", "event-1", "--start", calendarCoverageStart, "--yes"}, + "range": {"--event", "event-1", "--start", calendarCoverageEnd, "--end", calendarCoverageStart, "--yes"}, + "overlap": {"--event", "event-1", "--add-attendees", "u", "--remove-attendees", "u", "--yes"}, + } { + t.Run("args-"+name, func(t *testing.T) { + if err := runCalendarCoverage(t, EventUpdate, &calendarCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad update args accepted") + } + }) + } + + preflight := `{"success":true,"result":{"id":"event-1"}}` + if err := runCalendarCoverage(t, EventUpdate, &calendarCoverageCaller{responses: map[string][]string{"get_calendar_detail": {preflight}}}, "--event", "event-1", "--title", "updated", "--add-attendees", "u-add", "--remove-attendees", "u-remove", "--dry-run", "--yes"); err != nil { + t.Fatalf("update dry-run: %v", err) + } + success := map[string][]string{ + "get_calendar_detail": {preflight, calendarCoverageEvent}, + "update_calendar_event": {`{"success":true}`}, + "remove_calendar_participant": {`{"success":true}`}, + "add_calendar_participant": {`{"success":true}`}, + "get_calendar_participants": {`{"success":true,"result":{"attendees":[{"displayName":"added","userId":"u-add"}]}}`}, + } + if err := runCalendarCoverage(t, EventUpdate, &calendarCoverageCaller{responses: success}, "--event", "event-1", "--title", "updated", "--desc", "description", "--start", calendarCoverageStart, "--end", calendarCoverageEnd, "--timezone", "Asia/Shanghai", "--location", "room", "--free-busy", "busy", "--add-attendees", "u-add", "--remove-attendees", "u-remove", "--calendar-id", "primary", "--yes"); err != nil { + t.Fatalf("full update: %v", err) + } + + type updateFailure struct { + name string + responses map[string][]string + args []string + } + baseArgs := []string{"--event", "event-1", "--title", "updated", "--yes"} + cases := []updateFailure{ + {"preflight-call", map[string][]string{"get_calendar_detail": {"__ERROR__"}}, baseArgs}, + {"preflight-shape", map[string][]string{"get_calendar_detail": {`{"success":true,"result":{}}`}}, baseArgs}, + {"update-call", map[string][]string{"get_calendar_detail": {preflight}, "update_calendar_event": {"__ERROR__"}}, baseArgs}, + {"update-shape", map[string][]string{"get_calendar_detail": {preflight}, "update_calendar_event": {`{"result":{}}`}}, baseArgs}, + {"remove-call", map[string][]string{"get_calendar_detail": {preflight}, "remove_calendar_participant": {"__ERROR__"}}, []string{"--event", "event-1", "--remove-attendees", "u", "--yes"}}, + {"remove-shape", map[string][]string{"get_calendar_detail": {preflight}, "remove_calendar_participant": {`{"result":{}}`}}, []string{"--event", "event-1", "--remove-attendees", "u", "--yes"}}, + {"add-call", map[string][]string{"get_calendar_detail": {preflight}, "add_calendar_participant": {"__ERROR__"}}, []string{"--event", "event-1", "--add-attendees", "u", "--yes"}}, + {"add-shape", map[string][]string{"get_calendar_detail": {preflight}, "add_calendar_participant": {`{"result":{}}`}}, []string{"--event", "event-1", "--add-attendees", "u", "--yes"}}, + {"verify-call", map[string][]string{"get_calendar_detail": {preflight, "__ERROR__"}, "update_calendar_event": {`{"success":true}`}}, baseArgs}, + {"verify-shape", map[string][]string{"get_calendar_detail": {preflight, `{"success":true,"result":{}}`}, "update_calendar_event": {`{"success":true}`}}, baseArgs}, + {"verify-field", map[string][]string{"get_calendar_detail": {preflight, `{"success":true,"result":{"id":"event-1","summary":"wrong"}}`}, "update_calendar_event": {`{"success":true}`}}, baseArgs}, + {"attendee-call", map[string][]string{"get_calendar_detail": {preflight, preflight}, "add_calendar_participant": {`{"success":true}`}, "get_calendar_participants": {"__ERROR__"}}, []string{"--event", "event-1", "--add-attendees", "u", "--yes"}}, + {"attendee-shape", map[string][]string{"get_calendar_detail": {preflight, preflight}, "add_calendar_participant": {`{"success":true}`}, "get_calendar_participants": {`{"success":true,"result":{}}`}}, []string{"--event", "event-1", "--add-attendees", "u", "--yes"}}, + {"attendee-missing", map[string][]string{"get_calendar_detail": {preflight, preflight}, "add_calendar_participant": {`{"success":true}`}, "get_calendar_participants": {`{"success":true,"result":{"attendees":[]}}`}}, []string{"--event", "event-1", "--add-attendees", "u", "--yes"}}, + {"attendee-present", map[string][]string{"get_calendar_detail": {preflight, preflight}, "remove_calendar_participant": {`{"success":true}`}, "get_calendar_participants": {`{"success":true,"result":{"attendees":[{"displayName":"still","userId":"u"}]}}`}}, []string{"--event", "event-1", "--remove-attendees", "u", "--yes"}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if err := runCalendarCoverage(t, EventUpdate, &calendarCoverageCaller{responses: tc.responses}, tc.args...); err == nil { + t.Fatal("bad update path accepted") + } + }) + } + if err := calendarStageError("stage", []string{"done"}, nil); err == nil || !strings.Contains(err.Error(), "done") { + t.Fatalf("stage error missing ledger: %v", err) + } +} + +func TestCrossPlatformCoverageCalendarLegacyStrictBranches(t *testing.T) { + for name, args := range map[string][]string{ + "agenda-order": {"--start", calendarCoverageEnd, "--end", calendarCoverageStart}, + "room-limit": {"--limit", "bad"}, + "room-page": {"--page", "-1"}, + "room-start": {"--start", "bad"}, + "room-end": {"--start", calendarCoverageStart, "--end", "bad"}, + "room-order": {"--start", calendarCoverageEnd, "--end", calendarCoverageStart}, + } { + t.Run(name, func(t *testing.T) { + declaration := EventList + if strings.HasPrefix(name, "room-") { + declaration = RoomFind + } + if err := runCalendarCoverage(t, declaration, &calendarCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad input accepted") + } + }) + } + roomExecuteValidation := RoomFind + roomExecuteValidation.Validate = nil + if err := runCalendarCoverage(t, roomExecuteValidation, &calendarCoverageCaller{responses: map[string][]string{}}, "--limit", "bad"); err == nil { + t.Fatal("room execute validation accepted bad limit") + } + if err := runCalendarCoverage(t, EventSearch, &calendarCoverageCaller{responses: map[string][]string{}}, "--query", "x", "--limit", "0"); err == nil { + t.Fatal("search accepted bad limit") + } + if err := runCalendarCoverage(t, EventSearch, &calendarCoverageCaller{responses: map[string][]string{}}, "--query", "x", "--start", calendarCoverageEnd, "--end", calendarCoverageStart); err == nil { + t.Fatal("search accepted reversed range") + } + for name, declarationAndTool := range map[string]struct { + declaration shortcut.Shortcut + tool string + args []string + }{ + "agenda": {EventList, "list_calendar_events", nil}, + "room": {RoomFind, "query_available_meeting_room", []string{"--start", calendarCoverageStart, "--end", calendarCoverageEnd}}, + "busy": {BusySearch, "query_busy_status", []string{"--users", "u", "--start", calendarCoverageStart, "--end", calendarCoverageEnd}}, + } { + t.Run(name+"-call", func(t *testing.T) { + caller := &calendarCoverageCaller{responses: map[string][]string{declarationAndTool.tool: {"__ERROR__"}}} + if err := runCalendarCoverage(t, declarationAndTool.declaration, caller, declarationAndTool.args...); err == nil { + t.Fatal("transport failure accepted") + } + }) + } + + room := &calendarCoverageCaller{responses: map[string][]string{"query_available_meeting_room": {`{"success":true,"result":{"rooms":[{"id":"room-1","name":"room"}],"hasMore":true,"totalCount":1,"pageIndex":0,"pageSize":20}}`}}} + if err := runCalendarCoverage(t, RoomFind, room, "--group-id", "g", "--room-name", " room ", "--available"); err != nil { + t.Fatal(err) + } + for _, response := range []string{`{"success":true,"result":{}}`, `{"success":true,"result":{"rooms":[{"name":"missing id"}]}}`} { + caller := &calendarCoverageCaller{responses: map[string][]string{"query_available_meeting_room": {response}}} + if err := runCalendarCoverage(t, RoomFind, caller); err == nil { + t.Fatal("malformed room response accepted") + } + } + agendaProjection := &calendarCoverageCaller{responses: map[string][]string{"list_calendar_events": {`{"success":true,"result":{"events":[{"summary":"missing id"}],"hasMore":false}}`}}} + if err := runCalendarCoverage(t, EventList, agendaProjection); err == nil { + t.Fatal("agenda item without id accepted") + } + + for name, response := range map[string]string{ + "missing": `{"success":true,"result":{"busy":[{}]}}`, + "bad-list": `{"success":true,"result":{"busy":[{"scheduleItems":{}}]}}`, + "bad-item": `{"success":true,"result":{"busy":[{"scheduleItems":["bad"]}]}}`, + "bad-time": `{"success":true,"result":{"busy":[{"scheduleItems":[{"start":{"date":"2026-08-17"}}]}]}}`, + } { + t.Run("busy-"+name, func(t *testing.T) { + caller := &calendarCoverageCaller{responses: map[string][]string{"query_busy_status": {response}}} + if err := runCalendarCoverage(t, BusySearch, caller, "--users", "u", "--rooms", "r", "--start", calendarCoverageStart, "--end", calendarCoverageEnd); err == nil { + t.Fatal("bad busy response accepted") + } + }) + } + validBusy := &calendarCoverageCaller{responses: map[string][]string{"query_busy_status": {`{"success":true,"result":{"busy":[{"scheduleItems":[{"start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"date":"2026-08-17"}}]}]}}`}}} + if err := runCalendarCoverage(t, BusySearch, validBusy, "--users", "u", "--rooms", "r", "--start", calendarCoverageStart, "--end", calendarCoverageEnd); err != nil { + t.Fatal(err) + } + if calendarBusyDateTime("raw") != "raw" { + t.Fatal("raw busy time was not preserved") + } +} diff --git a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go index 21a81470..933e4316 100644 --- a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go +++ b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go @@ -47,11 +47,12 @@ func (*calendarCoverageCaller) JQ() string { return "" } func runCalendarCoverage(t *testing.T, declaration shortcut.Shortcut, caller *calendarCoverageCaller, args ...string) error { t.Helper() helpers.InitDepsForTest(t, caller) - declaration.OutputRollout = output.RolloutLegacyOnly root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} root.PersistentFlags().Bool("yes", false, "") root.PersistentFlags().Bool("dry-run", false, "") root.PersistentFlags().String("format", "json", "") + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) service := &cobra.Command{Use: "calendar"} service.AddCommand(corecmd.New(shortcut.FromShortcut(declaration))) root.AddCommand(service) diff --git a/internal/shortcut/smart/calendar_shared.go b/internal/shortcut/smart/calendar_shared.go index 9066ce28..a50709cf 100644 --- a/internal/shortcut/smart/calendar_shared.go +++ b/internal/shortcut/smart/calendar_shared.go @@ -497,9 +497,6 @@ func calendarSmartDeleteAndVerify(rt *shortcut.RuntimeContext, eventID string) e } event, err := calendarSmartRequireEvent(data, "calendar/get_calendar_detail", eventID) if err != nil { - if calendarSmartNotFound(err) { - return nil - } return err } status := strings.ToLower(calendarSmartFirstString(event, "status", "eventStatus", "event_status")) diff --git a/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go b/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go index a4cc0f65..a5b989cf 100644 --- a/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go +++ b/internal/shortcut/smart/calendar_strict_cross_platform_coverage_test.go @@ -8,13 +8,17 @@ import ( "context" "encoding/json" "errors" + "fmt" "io" "strings" "testing" + "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" ) type calendarSmartTestStep struct { @@ -339,3 +343,205 @@ func TestCrossPlatformCoverageCalendarSmartDeleteAndRollbackVerifyAbsence(t *tes t.Fatalf("rollback was not verified payload=%#v output=%q err=%v counts=%#v", payload, outputText, err, rollback.counts) } } + +func TestCrossPlatformCoverageCalendarSmartSharedFailureBranches(t *testing.T) { + for _, response := range []map[string]any{{}, {"success": "yes"}, {"success": false}} { + if _, err := calendarSmartRequireSuccess(response, "calendar/test"); err == nil { + t.Fatalf("bad success envelope accepted: %#v", response) + } + } + for _, response := range []map[string]any{ + {"success": true}, + {"success": true, "result": map[string]any{}}, + {"success": true, "result": map[string]any{"summary": "missing id"}}, + {"success": true, "result": map[string]any{"id": "wrong"}}, + } { + if _, err := calendarSmartRequireEvent(response, "calendar/get", "event-1"); err == nil { + t.Fatalf("bad event accepted: %#v", response) + } + } + if event, err := calendarSmartRequireEvent(map[string]any{"success": true, "result": map[string]any{"id": "event-1"}}, "calendar/get", "event-1"); err != nil || event["id"] != "event-1" { + t.Fatalf("valid event=%#v %v", event, err) + } + if calendarSmartEventID(map[string]any{"eventId": "direct"}) != "direct" || calendarSmartEventID(map[string]any{"data": map[string]any{"id": "nested"}}) != "nested" || calendarSmartEventID(map[string]any{}) != "" { + t.Fatal("event id discovery drift") + } + + invalidPages := []map[string]any{ + {"success": true, "result": []any{}}, + {"success": true, "result": map[string]any{"events": []any{}, "hasMore": "bad"}}, + {"success": true, "result": map[string]any{"events": []any{}, "hasMore": true, "nextCursor": 1}}, + {"success": true, "result": map[string]any{"events": []any{map[string]any{"summary": "no id", "start": map[string]any{"dateTime": "2026-08-17T09:00:00+08:00"}, "end": map[string]any{"dateTime": "2026-08-17T10:00:00+08:00"}}}, "hasMore": false}}, + {"success": true, "result": map[string]any{"events": []any{map[string]any{"id": "x", "end": map[string]any{"dateTime": "2026-08-17T10:00:00+08:00"}}}, "hasMore": false}}, + {"success": true, "result": map[string]any{"events": []any{map[string]any{"id": "x", "start": map[string]any{"dateTime": "2026-08-17T09:00:00+08:00"}}}, "hasMore": false}}, + } + for index, response := range invalidPages { + if _, _, _, err := calendarSmartEventPage(response); err == nil { + t.Fatalf("bad page %d accepted", index) + } + } + + for _, response := range []map[string]any{ + {"success": true, "result": map[string]any{}}, + {"success": true, "result": []any{"bad"}}, + {"success": true, "result": []any{map[string]any{"other": true}}}, + {"success": true, "result": []any{map[string]any{"scheduleItems": map[string]any{}}}}, + {"success": true, "result": []any{map[string]any{"scheduleItems": []any{"bad"}}}}, + {"success": true, "result": []any{map[string]any{"scheduleItems": []any{map[string]any{"start": ""}}}}}, + } { + if _, err := calendarSmartBusySlots(response); err == nil { + t.Fatalf("bad busy slots accepted: %#v", response) + } + } + busy, err := calendarSmartBusySlots(map[string]any{"success": true, "result": []any{map[string]any{"scheduleItems": []any{map[string]any{"start": map[string]any{"dateTime": "s"}, "end": map[string]any{"date": "e"}}}}}}) + if err != nil || len(busy) != 1 { + t.Fatalf("busy slots=%#v %v", busy, err) + } + + for _, response := range []map[string]any{ + {"success": true, "result": []any{}}, + {"success": true, "result": map[string]any{"recommendEventTimes": map[string]any{}}}, + {"success": true, "result": map[string]any{"recommendEventTimes": []any{"bad"}}}, + } { + if _, err := calendarSmartSuggestedSlots(response); err == nil { + t.Fatalf("bad suggested slots accepted: %#v", response) + } + } + slots, err := calendarSmartSuggestedSlots(map[string]any{"success": true, "result": map[string]any{"recommendEventTimes": []any{map[string]any{"startTime": "s", "endTime": "e", "timeConflictAttendees": []any{nil, "u"}}}}}) + if err != nil || len(slots) != 1 || len(slots[0]["conflicts"].([]any)) != 1 { + t.Fatalf("suggested slots=%#v %v", slots, err) + } + + for _, response := range []map[string]any{ + {"success": false}, + {"success": true}, + {"success": true, "result": map[string]any{}}, + {"success": true, "result": "bad"}, + {"success": true, "result": map[string]any{"attendees": map[string]any{}}}, + {"success": true, "result": []any{"bad"}}, + {"success": true, "result": []any{map[string]any{"role": "none"}}}, + {"success": true, "result": []any{map[string]any{"userId": "u", "self": "yes"}}}, + } { + if _, err := calendarSmartAttendees(response); err == nil { + t.Fatalf("bad attendees accepted: %#v", response) + } + } + attendees, err := calendarSmartAttendees(map[string]any{"success": true, "result": map[string]any{"participants": []any{map[string]any{"userId": "u", "displayName": "name", "self": true}}}}) + if err != nil || !attendees["u"] || !attendees["name"] || !attendees["__self__"] { + t.Fatalf("attendees=%#v %v", attendees, err) + } + + event := map[string]any{"startDateTime": "2026-08-17T09:00:00+08:00", "endDateTime": "2026-08-17T10:00:00+08:00"} + if err := calendarSmartVerifyEventTimes(event, "2026-08-17T09:00:00+08:00", "2026-08-17T10:00:00+08:00"); err != nil { + t.Fatal(err) + } + if err := calendarSmartVerifyEventTimes(event, "bad", "2026-08-17T10:00:00+08:00"); err == nil { + t.Fatal("bad expected event time accepted") + } + if _, ok := calendarSmartEventTime(1); ok { + t.Fatal("non-string event time accepted") + } + if _, ok := calendarSmartEventTime("bad"); ok { + t.Fatal("bad event time accepted") + } + if calendarSmartNotFound(nil) || !calendarSmartNotFound(errors.New("404 not found")) || calendarSmartNotFound(errors.New("temporary")) { + t.Fatal("not-found classification drift") + } + for _, pair := range [][2]string{{"bad", "2026-08-17T10:00:00+08:00"}, {"2026-08-17T09:00:00+08:00", "bad"}, {"2026-08-17T10:00:00+08:00", "2026-08-17T09:00:00+08:00"}} { + if err := calendarSmartValidateRange(pair[0], pair[1]); err == nil { + t.Fatalf("bad range accepted: %#v", pair) + } + } + if err := calendarSmartVerifyCreatedEvent(map[string]any{"id": "wrong", "summary": "title"}, "event-1", "title", "s", "e"); err == nil { + t.Fatal("wrong created event id accepted") + } + if err := calendarSmartVerifyCreatedEvent(map[string]any{"id": "event-1", "summary": "wrong"}, "event-1", "title", "s", "e"); err == nil { + t.Fatal("wrong created event title accepted") + } + if err := calendarSmartVerifyAttendees(map[string]bool{}, []string{"u"}, nil, ""); err == nil { + t.Fatal("missing attendee accepted") + } + if err := calendarSmartVerifyAttendees(map[string]bool{"name": true}, []string{"u"}, []string{"name"}, ""); err != nil { + t.Fatal(err) + } + if err := calendarSmartVerifyAttendees(map[string]bool{"__self__": true}, []string{"u"}, nil, "u"); err != nil { + t.Fatal(err) + } +} + +func calendarSmartRuntimeForTest(t *testing.T, caller edition.ToolCaller) *shortcut.RuntimeContext { + t.Helper() + helpers.InitDepsForTest(t, caller) + cmd := &cobra.Command{Use: "calendar-test"} + ctx, _ := output.WithResultStore(context.Background()) + cmd.SetContext(ctx) + return shortcut.RuntimeContextForTest(cmd, shortcut.Shortcut{Service: "calendar", Product: "calendar"}) +} + +func TestCrossPlatformCoverageCalendarSmartCurrentUserDeleteAndPageCap(t *testing.T) { + for name, steps := range map[string][]calendarSmartTestStep{ + "call": {{err: errors.New("profile failure")}}, + "missing": {{text: `{"success":true,"result":{}}`}}, + "success": {{text: `{"success":true,"result":{"userId":"user-placeholder"}}`}}, + } { + t.Run("profile-"+name, func(t *testing.T) { + caller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/get_current_user_profile": steps}} + id, err := calendarSmartCurrentUserID(calendarSmartRuntimeForTest(t, caller), map[string]bool{"__self__": true}) + if name == "success" { + if err != nil || id == "" { + t.Fatalf("id=%q err=%v", id, err) + } + } else if err == nil { + t.Fatal("bad profile accepted") + } + }) + } + if id, err := calendarSmartCurrentUserID(calendarSmartRuntimeForTest(t, &calendarSmartTestCaller{}), map[string]bool{}); err != nil || id != "" { + t.Fatalf("profile unnecessarily called: id=%q err=%v", id, err) + } + + deleteCases := map[string]*calendarSmartTestCaller{ + "write-call": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{err: errors.New("write")}}}}, + "receipt": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"result":{}}`}}}}, + "read-unknown": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{err: errors.New("temporary")}}}}, + "read-malformed": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: `{"success":true,"result":{}}`}}}}, + "read-not-found-response": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: `{"success":false,"message":"not found"}`}}}}, + "present": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: `{"success":true,"result":{"id":"event-placeholder","status":"active"}}`}}}}, + "tombstone": {steps: map[string][]calendarSmartTestStep{"calendar/delete_calendar_event": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: `{"success":true,"result":{"id":"event-placeholder","status":"deleted"}}`}}}}, + } + for name, caller := range deleteCases { + t.Run("delete-"+name, func(t *testing.T) { + err := calendarSmartDeleteAndVerify(calendarSmartRuntimeForTest(t, caller), "event-placeholder") + if name == "tombstone" || name == "read-not-found-response" { + if err != nil { + t.Fatal(err) + } + } else if err == nil { + t.Fatal("bad delete path accepted") + } + }) + } + + steps := make([]calendarSmartTestStep, calendarSmartMaxPages) + for index := range steps { + steps[index] = calendarSmartTestStep{text: fmt.Sprintf(`{"success":true,"result":{"events":[],"hasMore":true,"nextCursor":"cursor-%d"}}`, index+1)} + } + capCaller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/list_calendar_events": steps}} + if _, err := calendarSmartListAll(calendarSmartRuntimeForTest(t, capCaller), map[string]any{}); err == nil { + t.Fatal("calendar page cap accepted incomplete events") + } + callFailure := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/list_calendar_events": {{err: errors.New("list")}}}} + if _, err := calendarSmartListAll(calendarSmartRuntimeForTest(t, callFailure), map[string]any{}); err == nil { + t.Fatal("calendar list transport failure accepted") + } + _ = calendarProjectEvents([]map[string]any{calendarSmartTestEvent("event-placeholder")}) + item := shortcut.Shortcut{} + finalizeCalendarSmart(&item, "description") + if item.Contract.Result == nil { + t.Fatal("finalized smart shortcut missing result") + } + start, end := calendarDayRange(0) + if !end.After(start) || end.Sub(start) < 23*time.Hour { + t.Fatalf("day range=%v..%v", start, end) + } +} diff --git a/internal/shortcut/smart/shortcut_additional_cross_platform_coverage_test.go b/internal/shortcut/smart/shortcut_additional_cross_platform_coverage_test.go new file mode 100644 index 00000000..5b924a1c --- /dev/null +++ b/internal/shortcut/smart/shortcut_additional_cross_platform_coverage_test.go @@ -0,0 +1,288 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package smart + +import ( + "errors" + "strconv" + "strings" + "testing" + "time" +) + +const ( + smartCoverageStart = "2026-08-17T09:00:00+08:00" + smartCoverageEnd = "2026-08-17T10:00:00+08:00" + smartCoverageEvent = `{"success":true,"result":{"id":"event-placeholder","summary":"fixture title","start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"}}}` + smartTodoPageEmpty = `{"success":true,"result":{"todoCards":[],"hasMore":false}}` +) + +func smartContact() calendarSmartTestStep { + return calendarSmartTestStep{text: `{"result":[{"userId":"user-placeholder","name":"fixture person"}]}`} +} + +func TestCrossPlatformCoverageCalendarSmartBookBranches(t *testing.T) { + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{}, "calendar", "+book", "--title", "x", "--start", smartCoverageEnd, "--end", smartCoverageStart, "--yes"); err == nil { + t.Fatal("book accepted reversed range") + } + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{}, "calendar", "+book", "--title", "x", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + blankWith := &calendarSmartTestCaller{} + if _, _, err := runCalendarSmartCLI(t, blankWith, "calendar", "+book", "--title", "x", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--with", " , ", "--yes"); err == nil { + t.Fatal("blank invitee list accepted") + } + + for name, caller := range map[string]*calendarSmartTestCaller{ + "create-call": {steps: map[string][]calendarSmartTestStep{"calendar/create_calendar_event": {{err: errors.New("create")}}}}, + "missing-id": {steps: map[string][]calendarSmartTestStep{"calendar/create_calendar_event": {{text: `{"success":true,"result":{}}`}}}}, + "read-call": {steps: map[string][]calendarSmartTestStep{"calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/get_calendar_detail": {{err: errors.New("read")}}}}, + "read-shape": {steps: map[string][]calendarSmartTestStep{"calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/get_calendar_detail": {{text: `{"success":true,"result":{}}`}}}}, + "read-verify": {steps: map[string][]calendarSmartTestStep{"calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/get_calendar_detail": {{text: strings.Replace(smartCoverageEvent, "fixture title", "wrong", 1)}}}}, + } { + t.Run(name, func(t *testing.T) { + if _, _, err := runCalendarSmartCLI(t, caller, "calendar", "+book", "--title", "fixture title", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--yes"); err == nil { + t.Fatal("bad book path accepted") + } + }) + } + + rollbackFailure := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, + "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, + "calendar/add_calendar_participant": {{text: `{"success":false}`}}, + "calendar/delete_calendar_event": {{err: errors.New("rollback")}}, + }} + if _, _, err := runCalendarSmartCLI(t, rollbackFailure, "calendar", "+book", "--title", "fixture title", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--with", "fixture person", "--yes"); err == nil { + t.Fatal("failed rollback accepted") + } + + participantCases := map[string]*calendarSmartTestCaller{ + "call": {steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: smartCoverageEvent}}, "calendar/get_calendar_participants": {{err: errors.New("participants")}}, + }}, + "shape": {steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: smartCoverageEvent}}, "calendar/get_calendar_participants": {{text: `{"success":true}`}}, + }}, + "profile": {steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: smartCoverageEvent}}, "calendar/get_calendar_participants": {{text: `{"success":true,"result":[{"displayName":"fixture person","self":true}]}`}}, "contact/get_current_user_profile": {{err: errors.New("profile")}}, + }}, + "missing": {steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/create_calendar_event": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_detail": {{text: smartCoverageEvent}}, "calendar/get_calendar_participants": {{text: `{"success":true,"result":[{"userId":"other"}]}`}}, + }}, + } + for name, caller := range participantCases { + t.Run("participants-"+name, func(t *testing.T) { + if _, _, err := runCalendarSmartCLI(t, caller, "calendar", "+book", "--title", "fixture title", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--with", "fixture person", "--yes"); err == nil { + t.Fatal("bad participant verification accepted") + } + }) + } +} + +func TestCrossPlatformCoverageCalendarSmartInviteAndRescheduleBranches(t *testing.T) { + preflight := `{"success":true,"result":{"id":"event-placeholder"}}` + inviteDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}}} + if _, _, err := runCalendarSmartCLI(t, inviteDry, "calendar", "+invite", "--event", "event-placeholder", "--with", "fixture person", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + for name, caller := range map[string]*calendarSmartTestCaller{ + "preflight-call": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{err: errors.New("preflight")}}}}, + "write-call": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{err: errors.New("write")}}}}, + "receipt": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{text: `{"result":{}}`}}}}, + "participants-call": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_participants": {{err: errors.New("participants")}}}}, + "participants-shape": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_participants": {{text: `{"success":true}`}}}}, + "profile": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_participants": {{text: `{"success":true,"result":[{"displayName":"fixture person","self":true}]}`}}, "contact/get_current_user_profile": {{err: errors.New("profile")}}}}, + "missing": {steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "calendar/get_calendar_detail": {{text: preflight}}, "calendar/add_calendar_participant": {{text: `{"success":true}`}}, "calendar/get_calendar_participants": {{text: `{"success":true,"result":[{"userId":"other"}]}`}}}}, + } { + t.Run("invite-"+name, func(t *testing.T) { + if _, _, err := runCalendarSmartCLI(t, caller, "calendar", "+invite", "--event", "event-placeholder", "--with", "fixture person", "--yes"); err == nil { + t.Fatal("bad invite path accepted") + } + }) + } + + rescheduleDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}}}} + if _, _, err := runCalendarSmartCLI(t, rescheduleDry, "calendar", "+reschedule", "--event", "event-placeholder", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{}, "calendar", "+reschedule", "--event", "event-placeholder", "--start", smartCoverageEnd, "--end", smartCoverageStart, "--yes"); err == nil { + t.Fatal("reschedule accepted reversed range") + } + for name, caller := range map[string]*calendarSmartTestCaller{ + "preflight": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{err: errors.New("preflight")}}}}, + "write": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}}, "calendar/update_calendar_event": {{err: errors.New("write")}}}}, + "receipt": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}}, "calendar/update_calendar_event": {{text: `{"result":{}}`}}}}, + "read": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}, {err: errors.New("read")}}, "calendar/update_calendar_event": {{text: `{"success":true}`}}}}, + "shape": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}, {text: `{"success":true,"result":{}}`}}, "calendar/update_calendar_event": {{text: `{"success":true}`}}}}, + "times": {steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: preflight}, {text: `{"success":true,"result":{"id":"event-placeholder","start":{"dateTime":"2026-08-17T08:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"}}}`}}, "calendar/update_calendar_event": {{text: `{"success":true}`}}}}, + } { + t.Run("reschedule-"+name, func(t *testing.T) { + if _, _, err := runCalendarSmartCLI(t, caller, "calendar", "+reschedule", "--event", "event-placeholder", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--yes"); err == nil { + t.Fatal("bad reschedule path accepted") + } + }) + } +} + +func TestCrossPlatformCoverageCalendarSmartReadCommands(t *testing.T) { + if _, ok := conflictsEndTime(map[string]any{"endTime": smartCoverageEnd}); !ok { + t.Fatal("top-level endTime was not parsed") + } + conflictEvents := `{"success":true,"result":{"events":[{"id":"a","summary":"","start":{"dateTime":"2026-08-17T09:00:00+08:00"},"end":{"dateTime":"2026-08-17T10:00:00+08:00"}},{"id":"b","summary":"B","start":{"dateTime":"2026-08-17T09:30:00+08:00"},"end":{"dateTime":"2026-08-17T10:30:00+08:00"}}],"hasMore":false}}` + for _, command := range []string{"+conflicts", "+free-slots", "+tomorrow", "+week"} { + caller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/list_calendar_events": {{text: conflictEvents}}}} + args := []string{"calendar", command} + if command == "+free-slots" { + args = append(args, "--from", "0", "--to", "24") + } + if _, _, err := runCalendarSmartCLI(t, caller, args...); err != nil { + t.Fatalf("%s: %v", command, err) + } + } + for name, response := range map[string]string{ + "empty": smartTodoPageEmpty, + "future": `{"success":true,"result":{"events":[{"id":"future","summary":"future","start":{"dateTime":"2099-08-17T09:00:00+08:00"},"end":{"dateTime":"2099-08-17T10:00:00+08:00"}}],"hasMore":false}}`, + } { + t.Run("next-"+name, func(t *testing.T) { + if name == "empty" { + response = `{"success":true,"result":{"events":[],"hasMore":false}}` + } + caller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/list_calendar_events": {{text: response}}}} + if _, _, err := runCalendarSmartCLI(t, caller, "calendar", "+next-event"); err != nil { + t.Fatal(err) + } + }) + } + if got := shortcutNextEventPick([]map[string]any{{"id": ""}, {"id": "x", "start": "bad"}}, time.Now()); got != nil { + t.Fatalf("invalid next event picked: %#v", got) + } + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{}, "calendar", "+free-slots", "--from", "24", "--to", "1"); err == nil { + t.Fatal("bad free-slot window accepted") + } + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{}, "calendar", "+suggest-time", "--with", "fixture person", "--start", smartCoverageEnd, "--end", smartCoverageStart); err == nil { + t.Fatal("suggest-time accepted reversed range") + } + suggest := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "contact/search_contact_by_key_word": {{text: smartContact().text}}, + "calendar/list_suggested_event_times": {{text: `{"success":true,"result":{"recommendEventTimes":[]}}`}}, + }} + if _, _, err := runCalendarSmartCLI(t, suggest, "calendar", "+suggest-time", "--with", "fixture person", "--start", smartCoverageStart, "--end", smartCoverageEnd, "--duration", "30"); err != nil { + t.Fatal(err) + } + if _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"calendar/get_calendar_detail": {{text: `{"success":true,"result":{"id":"event-placeholder"}}`}}}}, "calendar", "+cancel-event", "--event", "event-placeholder", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } +} + +func TestCrossPlatformCoverageTodoSmartWriteBranches(t *testing.T) { + assignDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}}} + if _, _, err := runCalendarSmartCLI(t, assignDry, "todo", "+assign", "--task", "task", "--to", "fixture person", "--due", smartCoverageEnd, "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + for name, responses := range map[string]map[string][]calendarSmartTestStep{ + "call": {"contact/search_contact_by_key_word": {{text: smartContact().text}}, "todo/create_personal_todo": {{err: errors.New("write")}}}, + "verify": {"contact/search_contact_by_key_word": {{text: smartContact().text}}, "todo/create_personal_todo": {{text: `{"result":{}}`}}}, + "success": {"contact/search_contact_by_key_word": {{text: smartContact().text}}, "todo/create_personal_todo": {{text: `{"success":true,"result":{"taskId":"task-placeholder"}}`}}, "todo/get_todo_detail": {{text: `{"success":true,"result":{"todoDetailModel":{"taskId":"task-placeholder","subject":"task"}}}`}}}, + } { + t.Run("assign-"+name, func(t *testing.T) { + _, _, err := runCalendarSmartCLI(t, &calendarSmartTestCaller{steps: responses}, "todo", "+assign", "--task", "task", "--to", "fixture person", "--yes") + if name == "success" { + if err != nil { + t.Fatal(err) + } + } else if err == nil { + t.Fatal("bad assign path accepted") + } + }) + } + + multiDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}}} + if _, _, err := runCalendarSmartCLI(t, multiDry, "todo", "+assign-multi", "--task", "task", "--to", "fixture person", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + multiSuccess := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "todo/create_personal_todo": {{text: `{"success":true,"result":{"taskId":"task-placeholder"}}`}}, "todo/get_todo_detail": {{text: `{"success":true,"result":{"todoDetailModel":{"taskId":"task-placeholder","subject":"task"}}}`}}}} + if _, _, err := runCalendarSmartCLI(t, multiSuccess, "todo", "+assign-multi", "--task", "task", "--to", "fixture person", "--yes"); err != nil { + t.Fatal(err) + } + multiFailure := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/search_contact_by_key_word": {{text: smartContact().text}}, "todo/create_personal_todo": {{err: errors.New("write")}}}} + if _, _, err := runCalendarSmartCLI(t, multiFailure, "todo", "+assign-multi", "--task", "task", "--to", "fixture person", "--yes"); err == nil { + t.Fatal("assign-multi write failure accepted") + } + + doneDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"needle"}],"hasMore":false}}`}}}} + if _, _, err := runCalendarSmartCLI(t, doneDry, "todo", "+todo-done", "--task", "needle", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + doneSuccess := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"needle"}],"hasMore":false}}`}}, "todo/update_todo_done_status": {{text: `{"success":true}`}}, "todo/get_todo_detail": {{text: `{"success":true,"result":{"todoDetailModel":{"taskId":"task-placeholder","isDone":true}}}`}}}} + if _, _, err := runCalendarSmartCLI(t, doneSuccess, "todo", "+todo-done", "--task", "needle", "--yes"); err != nil { + t.Fatal(err) + } + doneCall := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"needle"}],"hasMore":false}}`}}, "todo/update_todo_done_status": {{err: errors.New("write")}}}} + if _, _, err := runCalendarSmartCLI(t, doneCall, "todo", "+todo-done", "--task", "needle", "--yes"); err == nil { + t.Fatal("todo-done write failure accepted") + } + doneVerify := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"needle"}],"hasMore":false}}`}}, "todo/update_todo_done_status": {{text: `{"result":{}}`}}}} + if _, _, err := runCalendarSmartCLI(t, doneVerify, "todo", "+todo-done", "--task", "needle", "--yes"); err == nil { + t.Fatal("todo-done unverifiable write accepted") + } + + remindDry := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/get_current_user_profile": {{text: `{"result":{"userId":"user-placeholder"}}`}}}} + if _, _, err := runCalendarSmartCLI(t, remindDry, "todo", "+remind", "--task", "task", "--at", smartCoverageEnd, "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + remindSuccess := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"contact/get_current_user_profile": {{text: `{"result":{"userId":"user-placeholder"}}`}}, "todo/create_personal_todo": {{text: `{"success":true,"result":{"taskId":"task-placeholder"}}`}}, "todo/get_todo_detail": {{text: `{"success":true,"result":{"todoDetailModel":{"taskId":"task-placeholder","subject":"task"}}}`}}}} + if _, _, err := runCalendarSmartCLI(t, remindSuccess, "todo", "+remind", "--task", "task", "--yes"); err != nil { + t.Fatal(err) + } + for name, step := range map[string]calendarSmartTestStep{ + "call": {err: errors.New("write")}, + "receipt": {text: `{"result":{}}`}, + } { + t.Run("remind-"+name, func(t *testing.T) { + caller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{ + "contact/get_current_user_profile": {{text: `{"result":{"userId":"user-placeholder"}}`}}, + "todo/create_personal_todo": {step}, + }} + if _, _, err := runCalendarSmartCLI(t, caller, "todo", "+remind", "--task", "task", "--yes"); err == nil { + t.Fatal("bad remind write accepted") + } + }) + } +} + +func TestCrossPlatformCoverageTodoSmartReadAndSharedBranches(t *testing.T) { + for _, response := range []map[string]any{{}, {"success": false}, {"result": "bad"}, {"result": map[string]any{"todoCards": map[string]any{}}}} { + if _, _, err := shortcutTodoCardsStrict(response); err == nil { + t.Fatalf("bad todo cards accepted: %#v", response) + } + } + deep := map[string]any{"result": map[string]any{"result": map[string]any{"result": map[string]any{"result": map[string]any{"result": map[string]any{"result": map[string]any{}}}}}}} + if _, _, err := shortcutTodoCardsStrict(deep); err == nil { + t.Fatal("over-deep todo wrapper accepted") + } + steps := make([]calendarSmartTestStep, todoMaxPages) + for index := range steps { + steps[index] = calendarSmartTestStep{text: `{"success":true,"result":{"todoCards":[],"hasMore":true}}`} + } + capCaller := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": steps}} + if _, _, err := runCalendarSmartCLI(t, capCaller, "todo", "+created-todos"); err == nil { + t.Fatal("todo page cap accepted incomplete data") + } + + dayStart, dayEnd := calendarDayRange(0) + dueMillis := dayStart.Add(time.Hour).UnixMilli() + due := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"inside","dueTime":` + fmtInt64(dueMillis) + `},{"taskId":"task-out","subject":"outside","dueTime":` + fmtInt64(dayEnd.UnixMilli()) + `}],"hasMore":false}}`}}}} + if _, _, err := runCalendarSmartCLI(t, due, "todo", "+due-today"); err != nil { + t.Fatal(err) + } + badDue := &calendarSmartTestCaller{steps: map[string][]calendarSmartTestStep{"todo/get_user_todos_in_current_org": {{text: `{"success":true,"result":{"todoCards":[{"taskId":"task-placeholder","subject":"bad"}],"hasMore":false}}`}}}} + if _, _, err := runCalendarSmartCLI(t, badDue, "todo", "+due-today"); err == nil { + t.Fatal("due-today accepted missing due time") + } +} + +func fmtInt64(value int64) string { + return strconv.FormatInt(value, 10) +} diff --git a/internal/shortcut/todo/todo_additional_cross_platform_coverage_test.go b/internal/shortcut/todo/todo_additional_cross_platform_coverage_test.go new file mode 100644 index 00000000..47d46685 --- /dev/null +++ b/internal/shortcut/todo/todo_additional_cross_platform_coverage_test.go @@ -0,0 +1,610 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 + +package todo + +import ( + "context" + "encoding/json" + "errors" + "io" + "strconv" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +const todoCoverageTime = "2026-08-17T10:00:00+08:00" + +type todoCoverageCaller struct { + responses map[string][]string + history []string + arguments []map[string]any +} + +func (caller *todoCoverageCaller) CallTool(_ context.Context, _, tool string, arguments map[string]any) (*edition.ToolResult, error) { + caller.history = append(caller.history, tool) + caller.arguments = append(caller.arguments, arguments) + queue := caller.responses[tool] + if len(queue) == 0 { + return nil, errors.New("missing fake response for " + tool) + } + caller.responses[tool] = queue[1:] + if queue[0] == "__ERROR__" { + return nil, errors.New("injected todo failure") + } + return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: queue[0]}}}, nil +} + +func (caller *todoCoverageCaller) CallReadTool(ctx context.Context, product, tool string, arguments map[string]any) (*edition.ToolResult, error) { + return caller.CallTool(ctx, product, tool, arguments) +} + +func (*todoCoverageCaller) Format() string { return "json" } +func (*todoCoverageCaller) DryRun() bool { return false } +func (*todoCoverageCaller) Fields() string { return "" } +func (*todoCoverageCaller) JQ() string { return "" } + +func runTodoCoverage(t *testing.T, declaration shortcut.Shortcut, caller *todoCoverageCaller, args ...string) error { + t.Helper() + helpers.InitDepsForTest(t, caller) + root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true} + root.PersistentFlags().Bool("yes", false, "") + root.PersistentFlags().Bool("dry-run", false, "") + root.PersistentFlags().String("format", "json", "") + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) + service := &cobra.Command{Use: "todo"} + service.AddCommand(corecmd.New(shortcut.FromShortcut(declaration))) + root.AddCommand(service) + root.SetOut(io.Discard) + root.SetErr(io.Discard) + root.SetArgs(append([]string{"todo", declaration.Command}, args...)) + return root.Execute() +} + +func todoRuntimeForTest(t *testing.T, declaration shortcut.Shortcut, values map[string]string) *shortcut.RuntimeContext { + t.Helper() + cmd := corecmd.New(shortcut.FromShortcut(declaration)) + ctx, _ := output.WithResultStore(context.Background()) + cmd.SetContext(ctx) + for name, value := range values { + if err := cmd.Flags().Set(name, value); err != nil { + t.Fatalf("set --%s: %v", name, err) + } + } + return shortcut.RuntimeContextForTest(cmd, declaration) +} + +func TestCrossPlatformCoverageTodoCommonStrictBranches(t *testing.T) { + for _, response := range []map[string]any{{}, {"success": "yes"}, {"success": false}} { + if _, err := requireTodoResponse(response, "todo/test"); err == nil { + t.Fatalf("bad response accepted: %#v", response) + } + } + if _, err := requireTodoResponse(map[string]any{"result": map[string]any{}}, "todo/test"); err != nil { + t.Fatalf("response without optional success rejected: %v", err) + } + for _, response := range []map[string]any{{}, {"result": map[string]any{}}, {"success": false}} { + if err := requireTodoWriteReceipt(response, "todo/test"); err == nil { + t.Fatalf("bad receipt accepted: %#v", response) + } + } + if err := requireTodoWriteReceipt(map[string]any{"success": true}, "todo/test"); err != nil { + t.Fatal(err) + } + + for _, response := range []map[string]any{ + {"success": false}, + {"success": true, "result": map[string]any{"items": map[string]any{}}}, + {"success": true, "result": map[string]any{}}, + {"success": true, "result": map[string]any{"items": []any{"bad"}}}, + } { + if _, err := requireTodoCollection(response, "todo/test", "items"); err == nil { + t.Fatalf("bad collection accepted: %#v", response) + } + } + items, err := requireTodoCollection(map[string]any{"success": true, "result": []any{map[string]any{"id": "x"}}}, "todo/test", "items") + if err != nil || len(items) != 1 { + t.Fatalf("direct wrapper collection=%#v %v", items, err) + } + + if _, err := findTodoHasMore(map[string]any{}, 5); err == nil { + t.Fatal("deep pagination accepted") + } + for _, response := range []map[string]any{ + {"hasMore": "bad"}, + {"result": []any{}}, + {}, + } { + if _, err := todoHasMore(response); err == nil { + t.Fatalf("bad pagination accepted: %#v", response) + } + } + if more, err := todoHasMore(map[string]any{"result": map[string]any{"data": map[string]any{"hasMore": true}}}); err != nil || !more { + t.Fatalf("nested pagination=%v %v", more, err) + } + + if raw, found, err := findTodoCollection(map[string]any{}, []string{"items"}, 5); err != nil || found || raw != nil { + t.Fatalf("deep collection=%#v %v %v", raw, found, err) + } + for _, response := range []map[string]any{ + {"items": map[string]any{}}, + {"result": "bad"}, + } { + if _, _, err := findTodoCollection(response, []string{"items"}, 0); err == nil { + t.Fatalf("bad collection wrapper accepted: %#v", response) + } + } + if raw, found, err := findTodoCollection(map[string]any{"data": []any{}}, []string{"items"}, 0); err != nil || !found || raw == nil { + t.Fatalf("direct array wrapper=%#v %v %v", raw, found, err) + } + + for _, response := range []map[string]any{ + {"success": false}, + {"success": true, "result": map[string]any{"todoDetailModel": []any{}}}, + {"success": true, "result": map[string]any{}}, + {"success": true, "result": map[string]any{"todoDetailModel": map[string]any{"subject": "no id"}}}, + } { + if _, err := requireTodoDetail(response, "todo/test", ""); err == nil { + t.Fatalf("bad detail accepted: %#v", response) + } + } + for _, response := range []map[string]any{ + {"success": true, "result": map[string]any{"taskId": "task-1"}}, + {"success": true, "taskId": "task-1"}, + } { + if detail, err := requireTodoDetail(response, "todo/test", "task-1"); err != nil || todoStableString(detail, "taskId") != "task-1" { + t.Fatalf("fallback detail=%#v %v", detail, err) + } + } + if object, found, err := findTodoObject(map[string]any{}, []string{"todo"}, 5); err != nil || found || object != nil { + t.Fatalf("deep object=%#v %v %v", object, found, err) + } + for _, response := range []map[string]any{{"todo": []any{}}, {"result": []any{}}} { + if _, _, err := findTodoObject(response, []string{"todo"}, 0); err == nil { + t.Fatalf("bad object wrapper accepted: %#v", response) + } + } + + if got := findTodoStableString(map[string]any{}, []string{"id"}, 6); got != "" { + t.Fatalf("deep stable string=%q", got) + } + for _, tc := range []struct { + value any + want string + }{ + {" id ", "id"}, + {json.Number("12"), "12"}, + {float64(13), "13"}, + {float64(13.5), ""}, + {14, "14"}, + {int64(15), "15"}, + } { + if got := todoStableString(map[string]any{"id": tc.value}, "id"); got != tc.want { + t.Fatalf("stable %#v=%q want %q", tc.value, got, tc.want) + } + } + if got := findTodoStableString(map[string]any{"result": map[string]any{"data": map[string]any{"id": "nested"}}}, []string{"id"}, 0); got != "nested" { + t.Fatalf("nested stable string=%q", got) + } +} + +func TestCrossPlatformCoverageTodoProjectionBranches(t *testing.T) { + for name, project := range map[string]func(map[string]any) error{ + "sub": func(data map[string]any) error { _, err := listSubProjectStrict(data); return err }, + "attachment": func(data map[string]any) error { _, err := listAttachmentProjectStrict(data); return err }, + "comment": func(data map[string]any) error { _, err := listCommentProjectStrict(data); return err }, + } { + t.Run(name, func(t *testing.T) { + if err := project(map[string]any{"success": true, "result": map[string]any{"list": []any{map[string]any{"name": "missing id"}}, "hasMore": false}}); err == nil { + t.Fatal("item without stable id accepted") + } + }) + } + subs, err := listSubProjectStrict(map[string]any{"success": true, "result": map[string]any{"list": []any{map[string]any{"id": "sub-1", "title": "title", "deadline": 1}}}}) + if err != nil || len(subs) != 1 || subs[0]["subject"] != "title" || subs[0]["dueTime"] != 1 { + t.Fatalf("sub projection=%#v %v", subs, err) + } + attachments, err := listAttachmentProjectStrict(map[string]any{"success": true, "result": map[string]any{"items": []any{map[string]any{"id": "a-1", "name": "file", "size": 1, "type": "text"}}}}) + if err != nil || len(attachments) != 1 { + t.Fatalf("attachment projection=%#v %v", attachments, err) + } + comments, err := listCommentProjectStrict(map[string]any{"success": true, "result": map[string]any{"comments": []any{map[string]any{"id": "c-1", "text": "body", "userId": "u", "createdTime": 1}}}}) + if err != nil || len(comments) != 1 { + t.Fatalf("comment projection=%#v %v", comments, err) + } + + _ = listSubProject(map[string]any{"result": []any{"bad", map[string]any{}, map[string]any{"title": "x", "id": "s", "deadline": 1}}}) + _ = listAttachmentProject(map[string]any{"data": []any{"bad", map[string]any{}, map[string]any{"id": "a", "name": "n", "size": 1, "type": "t"}}}) + _ = listCommentProject(map[string]any{"result": []any{"bad", map[string]any{}, map[string]any{"id": "c", "text": "x", "creator": "u", "gmtCreate": 1}}}) + if listSubFirst(map[string]any{}, "x") != nil || listAttachmentFirst(map[string]any{}, "x") != nil || listCommentFirst(map[string]any{}, "x") != nil { + t.Fatal("missing projection fields were invented") + } +} + +func TestCrossPlatformCoverageTodoLifecycleCore(t *testing.T) { + if _, err := parseTodoMillis("due", "bad"); err == nil { + t.Fatal("bad due time accepted") + } + if millis, err := parseTodoMillis("due", todoCoverageTime); err != nil || millis == 0 { + t.Fatalf("due millis=%d %v", millis, err) + } + if got := nonEmptyStrings([]string{" a ", "", " b "}); strings.Join(got, ",") != "a,b" { + t.Fatalf("non-empty strings=%#v", got) + } + if err := runTodoCoverage(t, UploadAttachment, &todoCoverageCaller{responses: map[string][]string{}}, "--task-id", "t", "--file-path", "file", "--yes"); err == nil { + t.Fatal("unavailable upload shortcut executed") + } + if got := strconv.Itoa(todoPageSize); got != "20" { + t.Fatal(got) + } +} + +func TestCrossPlatformCoverageTodoCreateAndUpdate(t *testing.T) { + for name, values := range map[string]map[string]string{ + "create-required": {"title": "", "executors": ""}, + "create-due": {"title": "x", "executors": "u", "due": "bad"}, + "create-priority": {"title": "x", "executors": "u", "priority": "11"}, + "update-none": {"task-id": "task-1"}, + "update-title": {"task-id": "task-1", "title": ""}, + "update-due": {"task-id": "task-1", "due": "bad"}, + "update-priority": {"task-id": "task-1", "priority": "11"}, + } { + t.Run(name, func(t *testing.T) { + declaration, execute := Create, createTodo + if strings.HasPrefix(name, "update-") { + declaration, execute = Update, updateTodo + } + if err := execute(todoRuntimeForTest(t, declaration, values)); err == nil { + t.Fatal("invalid lifecycle values accepted") + } + }) + } + if err := runTodoCoverage(t, Create, &todoCoverageCaller{responses: map[string][]string{}}, "--title", "x", "--executors", "u", "--due", todoCoverageTime, "--priority", "40", "--dry-run", "--yes"); err != nil { + t.Fatalf("create dry-run: %v", err) + } + if err := runTodoCoverage(t, Update, &todoCoverageCaller{responses: map[string][]string{}}, "--task-id", "task-1", "--title", "x", "--due", todoCoverageTime, "--priority", "40", "--dry-run", "--yes"); err != nil { + t.Fatalf("update dry-run: %v", err) + } + + createCases := map[string]map[string][]string{ + "call": {"create_personal_todo": {"__ERROR__"}}, + "receipt": {"create_personal_todo": {`{"result":{}}`}}, + "id": {"create_personal_todo": {`{"success":true,"result":{}}`}}, + "read-call": {"create_personal_todo": {`{"success":true,"result":{"taskId":"task-1"}}`}, "get_todo_detail": {"__ERROR__"}}, + "read-shape": {"create_personal_todo": {`{"success":true,"result":{"taskId":"task-1"}}`}, "get_todo_detail": {`{"success":true,"result":{}}`}}, + "mismatch": {"create_personal_todo": {`{"success":true,"result":{"taskId":"task-1"}}`}, "get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"wrong"}}}`}}, + } + for name, responses := range createCases { + t.Run("create-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, Create, &todoCoverageCaller{responses: responses}, "--title", "x", "--executors", "u", "--yes"); err == nil { + t.Fatal("bad create path accepted") + } + }) + } + createSuccess := &todoCoverageCaller{responses: map[string][]string{ + "create_personal_todo": {`{"success":true,"result":{"taskId":"task-1"}}`}, + "get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"x"}}}`}, + }} + if err := runTodoCoverage(t, Create, createSuccess, "--title", "x", "--executors", "u", "--yes"); err != nil { + t.Fatal(err) + } + + updateCases := map[string]map[string][]string{ + "call": {"update_todo_task": {"__ERROR__"}}, + "receipt": {"update_todo_task": {`{"result":{}}`}}, + "read-call": {"update_todo_task": {`{"success":true}`}, "get_todo_detail": {"__ERROR__"}}, + "read-shape": {"update_todo_task": {`{"success":true}`}, "get_todo_detail": {`{"success":true,"result":{}}`}}, + "mismatch": {"update_todo_task": {`{"success":true}`}, "get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"wrong"}}}`}}, + } + for name, responses := range updateCases { + t.Run("update-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, Update, &todoCoverageCaller{responses: responses}, "--task-id", "task-1", "--title", "x", "--yes"); err == nil { + t.Fatal("bad update path accepted") + } + }) + } + updateSuccess := &todoCoverageCaller{responses: map[string][]string{ + "update_todo_task": {`{"success":true}`}, + "get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"x","priority":40}}}`}, + }} + if err := runTodoCoverage(t, Update, updateSuccess, "--task-id", "task-1", "--title", "x", "--priority", "40", "--yes"); err != nil { + t.Fatal(err) + } +} + +func TestCrossPlatformCoverageTodoDoneBranches(t *testing.T) { + if err := runTodoCoverage(t, Complete, &todoCoverageCaller{responses: map[string][]string{}}, "--task-id", "task-1", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + for name, responses := range map[string]map[string][]string{ + "before-call": {"get_todo_detail": {"__ERROR__"}}, + "before-shape": {"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1"}}}`}}, + "write-call": {"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`}, "update_todo_done_status": {"__ERROR__"}}, + "receipt": {"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`}, "update_todo_done_status": {`{"result":{}}`}}, + "read-call": {"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`, "__ERROR__"}, "update_todo_done_status": {`{"success":true}`}}, + "read-mismatch": {"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`}, "update_todo_done_status": {`{"success":true}`}}, + } { + t.Run(name, func(t *testing.T) { + if err := runTodoCoverage(t, Complete, &todoCoverageCaller{responses: responses}, "--task-id", "task-1", "--yes"); err == nil { + t.Fatal("bad done path accepted") + } + }) + } + already := &todoCoverageCaller{responses: map[string][]string{"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":true}}}`}}} + if err := runTodoCoverage(t, Complete, already, "--task-id", "task-1", "--yes"); err != nil { + t.Fatal(err) + } + success := &todoCoverageCaller{responses: map[string][]string{ + "get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":true}}}`}, + "update_todo_done_status": {`{"success":true}`}, + }} + if err := runTodoCoverage(t, Complete, success, "--task-id", "task-1", "--yes"); err != nil { + t.Fatal(err) + } + if reopen := doneShortcut("+reopen-test", false); !strings.Contains(reopen.Description, "重新") { + t.Fatalf("reopen description=%q", reopen.Description) + } +} + +func TestCrossPlatformCoverageTodoSearchAndPagination(t *testing.T) { + searchNoQuery := Search + for index := range searchNoQuery.Flags { + if searchNoQuery.Flags[index].Name == "query" { + searchNoQuery.Flags[index].Required = false + } + } + if err := Search.Execute(todoRuntimeForTest(t, searchNoQuery, map[string]string{})); err == nil { + t.Fatal("empty search accepted") + } + if err := runTodoCoverage(t, Search, &todoCoverageCaller{responses: map[string][]string{}}, "--query", "x", "--max-pages", "0"); err == nil { + t.Fatal("bad max-pages accepted") + } + for name, response := range map[string]string{ + "call": "__ERROR__", + "collection": `{"success":true,"result":{"hasMore":false}}`, + "pagination": `{"success":true,"result":{"todoCards":[]}}`, + "subject": `{"success":true,"result":{"todoCards":[{"taskId":"task-1"}],"hasMore":false}}`, + } { + t.Run(name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {response}}} + if err := runTodoCoverage(t, Search, caller, "--query", "x", "--status", "false", "--max-pages", "1"); err == nil { + t.Fatal("bad search page accepted") + } + }) + } + limit := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {`{"success":true,"result":{"todoCards":[],"hasMore":true}}`}}} + if err := runTodoCoverage(t, Search, limit, "--query", "x", "--max-pages", "1"); err == nil { + t.Fatal("incomplete search accepted") + } + success := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": { + `{"success":true,"result":{"todoCards":[{"taskId":"task-1","subject":"Needle"}],"hasMore":true}}`, + `{"success":true,"result":{"todoCards":[{"taskId":"task-2","subject":"other"}],"hasMore":false}}`, + }}} + if err := runTodoCoverage(t, Search, success, "--query", "needle", "--max-pages", "2"); err != nil { + t.Fatal(err) + } +} + +func TestCrossPlatformCoverageTodoCommentAndReminder(t *testing.T) { + commentNoContent := Comment + for index := range commentNoContent.Flags { + if commentNoContent.Flags[index].Name == "content" { + commentNoContent.Flags[index].Required = false + } + } + if err := Comment.Execute(todoRuntimeForTest(t, commentNoContent, map[string]string{"task-id": "task-1"})); err == nil { + t.Fatal("empty comment accepted") + } + if err := runTodoCoverage(t, Comment, &todoCoverageCaller{responses: map[string][]string{}}, "--task-id", "task-1", "--content", "body", "--dry-run", "--yes"); err != nil { + t.Fatal(err) + } + emptyPage := `{"success":true,"result":{"comments":[],"hasMore":false}}` + for name, responses := range map[string]map[string][]string{ + "before-call": {"list_todo_comment": {"__ERROR__"}}, + "before-shape": {"list_todo_comment": {`{"success":true,"result":{}}`}}, + "before-pagination": {"list_todo_comment": {`{"success":true,"result":{"comments":[]}}`}}, + "write-call": {"list_todo_comment": {emptyPage}, "add_todo_comment": {"__ERROR__"}}, + "receipt": {"list_todo_comment": {emptyPage}, "add_todo_comment": {`{"result":{}}`}}, + "after-call": {"list_todo_comment": {emptyPage, "__ERROR__"}, "add_todo_comment": {`{"success":true}`}}, + "ambiguous": {"list_todo_comment": {emptyPage, emptyPage}, "add_todo_comment": {`{"success":true}`}}, + } { + t.Run("comment-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, Comment, &todoCoverageCaller{responses: responses}, "--task-id", "task-1", "--content", "body", "--yes"); err == nil { + t.Fatal("bad comment path accepted") + } + }) + } + commentSuccess := &todoCoverageCaller{responses: map[string][]string{ + "list_todo_comment": {`{"success":true,"result":{"comments":[{"commentId":"old","content":"old"}],"hasMore":false}}`, `{"success":true,"result":{"comments":[{"commentId":"old","content":"old"},{"commentId":"new","content":"body"}],"hasMore":false}}`}, + "add_todo_comment": {`{"success":true,"result":{}}`}, + }} + if err := runTodoCoverage(t, Comment, commentSuccess, "--task-id", "task-1", "--content", "body", "--yes"); err != nil { + t.Fatal(err) + } + + for name, args := range map[string][]string{ + "none": {"--task-id", "task-1", "--yes"}, + "both": {"--task-id", "task-1", "--clear", "--base-time", "dueTime", "--yes"}, + "due-offset": {"--task-id", "task-1", "--base-time", "dueTime", "--yes"}, + "custom-at": {"--task-id", "task-1", "--base-time", "customTime", "--yes"}, + "custom-value": {"--task-id", "task-1", "--base-time", "customTime", "--at", "bad", "--yes"}, + } { + t.Run("reminder-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, Reminder, &todoCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad reminder arguments accepted") + } + }) + } + for name, args := range map[string][]string{ + "clear": {"--task-id", "task-1", "--clear", "--dry-run", "--yes"}, + "due": {"--task-id", "task-1", "--base-time", "dueTime", "--due-date-offset", "-30", "--dry-run", "--yes"}, + "at": {"--task-id", "task-1", "--base-time", "customTime", "--at", todoCoverageTime, "--dry-run", "--yes"}, + } { + t.Run("reminder-dry-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, Reminder, &todoCoverageCaller{responses: map[string][]string{}}, args...); err != nil { + t.Fatal(err) + } + }) + } + for _, tc := range []struct { + name string + tool string + args []string + }{ + {"clear", "reset_todo_reminder", []string{"--task-id", "task-1", "--clear", "--yes"}}, + {"due", "add_todo_reminder", []string{"--task-id", "task-1", "--base-time", "dueTime", "--due-date-offset", "-30", "--yes"}}, + {"at", "add_todo_reminder", []string{"--task-id", "task-1", "--base-time", "customTime", "--at", todoCoverageTime, "--yes"}}, + } { + t.Run("reminder-success-"+tc.name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{tc.tool: {`{"success":true}`}}} + if err := runTodoCoverage(t, Reminder, caller, tc.args...); err != nil { + t.Fatal(err) + } + }) + } + for name, response := range map[string]string{"call": "__ERROR__", "receipt": `{"result":{}}`} { + t.Run("reminder-remote-"+name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{"reset_todo_reminder": {response}}} + if err := runTodoCoverage(t, Reminder, caller, "--task-id", "task-1", "--clear", "--yes"); err == nil { + t.Fatal("bad reminder response accepted") + } + }) + } + pages := make([]string, todoMaxPages) + for index := range pages { + pages[index] = `{"success":true,"result":{"comments":[],"hasMore":true}}` + } + capCaller := &todoCoverageCaller{responses: map[string][]string{"list_todo_comment": pages}} + helpers.InitDepsForTest(t, capCaller) + if _, err := listAllTodoComments(todoRuntimeForTest(t, Comment, map[string]string{"task-id": "task-1", "content": "x"}), "task-1"); err == nil { + t.Fatal("comment pagination cap accepted incomplete data") + } +} + +func TestCrossPlatformCoverageTodoVerificationHelpers(t *testing.T) { + type createdCase struct { + name string + response map[string]any + read string + expected string + wantError bool + } + for _, tc := range []createdCase{ + {"receipt", map[string]any{}, "", "x", true}, + {"id", map[string]any{"success": true}, "", "x", true}, + {"read", map[string]any{"success": true, "taskId": "task-1"}, "__ERROR__", "x", true}, + {"mismatch", map[string]any{"success": true, "taskId": "task-1"}, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"wrong"}}}`, "x", true}, + {"success", map[string]any{"success": true, "taskId": "task-1"}, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","subject":"x"}}}`, "x", false}, + } { + t.Run("created-"+tc.name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{}} + if tc.read != "" { + caller.responses["get_todo_detail"] = []string{tc.read} + } + helpers.InitDepsForTest(t, caller) + _, _, err := VerifyCreatedTodo(todoRuntimeForTest(t, Get, map[string]string{"task-id": "task-1"}), tc.response, "todo/create", tc.expected) + if (err != nil) != tc.wantError { + t.Fatalf("error=%v wantError=%v", err, tc.wantError) + } + }) + } + for name, fixture := range map[string]struct { + response map[string]any + read string + wantErr bool + }{ + "receipt": {map[string]any{}, "", true}, + "read": {map[string]any{"success": true}, "__ERROR__", true}, + "mismatch": {map[string]any{"success": true}, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":false}}}`, true}, + "success": {map[string]any{"success": true}, `{"success":true,"result":{"todoDetailModel":{"taskId":"task-1","isDone":true}}}`, false}, + } { + t.Run("done-"+name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{}} + if fixture.read != "" { + caller.responses["get_todo_detail"] = []string{fixture.read} + } + helpers.InitDepsForTest(t, caller) + err := VerifyDoneStatus(todoRuntimeForTest(t, Get, map[string]string{"task-id": "task-1"}), fixture.response, "task-1", true) + if (err != nil) != fixture.wantErr { + t.Fatalf("error=%v wantError=%v", err, fixture.wantErr) + } + }) + } +} + +func TestCrossPlatformCoverageTodoGetMyTasksAndListLeaves(t *testing.T) { + for name, args := range map[string][]string{ + "page": {"--page", "0"}, + "size": {"--size", "21"}, + "priority": {"--priority", "11"}, + "role": {"--role-types", "owner"}, + "max": {"--all", "--max-pages", "0"}, + } { + t.Run(name, func(t *testing.T) { + if err := runTodoCoverage(t, GetMyTasks, &todoCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad list arguments accepted") + } + }) + } + for name, response := range map[string]string{ + "call": "__ERROR__", + "collection": `{"success":true,"result":{"hasMore":false}}`, + "pagination": `{"success":true,"result":{"todoCards":[]}}`, + } { + t.Run("list-"+name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {response}}} + if err := runTodoCoverage(t, GetMyTasks, caller); err == nil { + t.Fatal("bad list response accepted") + } + }) + } + normal := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {`{"success":true,"result":{"todoCards":[{"taskId":"task-1","subject":"x"}],"hasMore":true}}`}}} + if err := runTodoCoverage(t, GetMyTasks, normal, "--status", "false", "--priority", "40,30", "--role-types", "creator,participant", "--plan-finish-start", "1", "--plan-finish-end", "2"); err != nil { + t.Fatal(err) + } + allFailure := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {"__ERROR__"}}} + if err := runTodoCoverage(t, GetMyTasks, allFailure, "--all", "--max-pages", "1"); err == nil { + t.Fatal("all-pages transport failure accepted") + } + allSuccess := &todoCoverageCaller{responses: map[string][]string{"get_user_todos_in_current_org": {`{"success":true,"result":{"todoCards":[],"hasMore":false}}`}}} + if err := runTodoCoverage(t, GetMyTasks, allSuccess, "--all", "--max-pages", "1", "--role-types", ""); err != nil { + t.Fatal(err) + } + + getFailure := &todoCoverageCaller{responses: map[string][]string{"get_todo_detail": {"__ERROR__"}}} + if err := runTodoCoverage(t, Get, getFailure, "--task-id", "task-1"); err == nil { + t.Fatal("get transport failure accepted") + } + getSuccess := &todoCoverageCaller{responses: map[string][]string{"get_todo_detail": {`{"success":true,"result":{"todoDetailModel":{"taskId":"task-1"}}}`}}} + if err := runTodoCoverage(t, Get, getSuccess, "--task-id", "task-1"); err != nil { + t.Fatal(err) + } + + for name, args := range map[string][]string{"page": {"--task-id", "task-1", "--page", "0"}, "size": {"--task-id", "task-1", "--size", "21"}} { + t.Run("comments-"+name, func(t *testing.T) { + if err := runTodoCoverage(t, ListComment, &todoCoverageCaller{responses: map[string][]string{}}, args...); err == nil { + t.Fatal("bad comment list args accepted") + } + }) + } + for name, response := range map[string]string{"call": "__ERROR__", "shape": `{"success":true,"result":{}}`} { + t.Run("comments-"+name, func(t *testing.T) { + caller := &todoCoverageCaller{responses: map[string][]string{"list_todo_comment": {response}}} + if err := runTodoCoverage(t, ListComment, caller, "--task-id", "task-1"); err == nil { + t.Fatal("bad comment list response accepted") + } + }) + } + comments := &todoCoverageCaller{responses: map[string][]string{"list_todo_comment": {`{"success":true,"result":{"comments":[{"commentId":"c-1","content":"x"}]}}`}}} + if err := runTodoCoverage(t, ListComment, comments, "--task-id", "task-1", "--page", "2", "--size", "10"); err != nil { + t.Fatal(err) + } +} From 9f983be1acbba52e8de5caec2df3799c4fdb1d66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Mon, 17 Aug 2026 19:55:12 +0800 Subject: [PATCH 192/250] fix(recruit): validate job response identity to #85340676 --- internal/helpers/recruit.go | 35 ++++++++++-- internal/helpers/recruit_test.go | 95 ++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+), 5 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index bc9551bc..a64c7de4 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -158,14 +158,39 @@ func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (ou if err != nil { return recruitResponseFailure(err), nil } - if tool != recruitListJobsTool { + switch tool { + case recruitListJobsTool: + listData, meta, err := recruitListResultData(clean) + if err != nil { + return recruitInvalidResponse(err), nil + } + return output.Success(listData, output.WithMeta(meta)), nil + case recruitGetJobTool, recruitCreateJobTool: + if err := validateRecruitJobResult(clean, tool, args); err != nil { + return recruitInvalidResponse(err), nil + } return output.Success(clean), nil + default: + return recruitInvalidResponse(fmt.Errorf("不支持校验 %s 的业务结果", tool)), nil } - listData, meta, err := recruitListResultData(clean) - if err != nil { - return recruitInvalidResponse(err), nil +} + +func validateRecruitJobResult(data map[string]any, tool string, args map[string]any) error { + jobID, ok := data["jobId"].(string) + if !ok || strings.TrimSpace(jobID) == "" { + return fmt.Errorf("%s 返回值缺少非空字符串字段 jobId", tool) } - return output.Success(listData, output.WithMeta(meta)), nil + if tool != recruitGetJobTool { + return nil + } + requestedJobID, ok := args["jobId"].(string) + if !ok || strings.TrimSpace(requestedJobID) == "" { + return fmt.Errorf("%s 请求缺少非空字符串字段 jobId", tool) + } + if strings.TrimSpace(jobID) != strings.TrimSpace(requestedJobID) { + return fmt.Errorf("%s 返回的 jobId %q 与请求的 jobId %q 不一致", tool, jobID, requestedJobID) + } + return nil } func callRecruitMCPToolData(ctx context.Context, tool string, args map[string]any) (any, error) { diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index fb90cd52..41b9efe5 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -646,6 +646,101 @@ func TestRecruitResultCallRejectsInconsistentPagination(t *testing.T) { } } +func TestRecruitResultCallRejectsInvalidJobResults(t *testing.T) { + for _, test := range []struct { + name string + tool string + args map[string]any + text string + wantMessage string + }{ + { + name: "create empty response", + tool: recruitCreateJobTool, + text: " ", + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "create empty object", + tool: recruitCreateJobTool, + text: `{}`, + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "create envelope missing job id", + tool: recruitCreateJobTool, + text: `{"success":true,"result":{}}`, + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "create empty job id", + tool: recruitCreateJobTool, + text: `{"success":true,"result":{"jobId":" "}}`, + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "create non-string job id", + tool: recruitCreateJobTool, + text: `{"success":true,"result":{"jobId":123}}`, + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "get missing job id", + tool: recruitGetJobTool, + args: map[string]any{"jobId": "job-requested"}, + text: `{"success":true,"result":{"name":"Java 工程师"}}`, + wantMessage: "缺少非空字符串字段 jobId", + }, + { + name: "get mismatched job id", + tool: recruitGetJobTool, + args: map[string]any{"jobId": "job-requested"}, + text: `{"success":true,"result":{"jobId":"job-other"}}`, + wantMessage: "与请求的 jobId", + }, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = test.text + result, err := recruitResultCall(prepareRecruitTestCommand(&cobra.Command{}), test.tool, test.args) + if err != nil { + t.Fatal(err) + } + envelope, err := output.EnvelopeFromResult(result) + if err != nil { + t.Fatal(err) + } + if envelope.Outcome != output.OutcomeFailure || envelope.Error == nil { + t.Fatalf("envelope = %#v, want failure", envelope) + } + if envelope.Error.Type != "api" || envelope.Error.Subtype != "invalid_response" || + !strings.Contains(envelope.Error.Message, test.wantMessage) { + t.Fatalf("error = %#v, want invalid_response containing %q", envelope.Error, test.wantMessage) + } + if len(caller.calls) != 1 { + t.Fatalf("MCP calls = %d, want exactly one", len(caller.calls)) + } + }) + } +} + +func TestRecruitResultCallRejectsToolWithoutResultValidator(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = `{"jobId":"job-created"}` + result, err := recruitResultCall(prepareRecruitTestCommand(&cobra.Command{}), "future_write_tool", nil) + if err != nil { + t.Fatal(err) + } + envelope, err := output.EnvelopeFromResult(result) + if err != nil { + t.Fatal(err) + } + if envelope.Outcome != output.OutcomeFailure || envelope.Error == nil || + envelope.Error.Subtype != "invalid_response" || !strings.Contains(envelope.Error.Message, "不支持校验") { + t.Fatalf("envelope = %#v, want unsupported validator failure", envelope) + } +} + func TestRecruitResultCallDryRun(t *testing.T) { caller := withRecruitCaller(t) caller.dryRun = true From 07b14aa72a6a8d0cb1cfd0e9f5ccc951905f798f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Mon, 17 Aug 2026 20:39:24 +0800 Subject: [PATCH 193/250] feat(cli): expand AITable parameter alias normalization --- .changes/aitable-param-aliases.md | 5 + internal/app/param_alias_e2e_test.go | 2 + .../param_alias_payload_equivalence_test.go | 31 + internal/cli/param_aliases_generated.go | 1708 ++++++++++++++++- internal/cli/param_concepts.json | 51 +- 5 files changed, 1783 insertions(+), 14 deletions(-) create mode 100644 .changes/aitable-param-aliases.md diff --git a/.changes/aitable-param-aliases.md b/.changes/aitable-param-aliases.md new file mode 100644 index 00000000..374f4989 --- /dev/null +++ b/.changes/aitable-param-aliases.md @@ -0,0 +1,5 @@ +--- +category: Changed +--- + +- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked. diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index d1f2df97..fed2527b 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -68,6 +68,8 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string return `{"revertedToVersion":3}` case "search_doc_templates": return `{"result":[{"templateId":"fixture-template-id"}]}` + case "list_workflows": + return `{"workflows":[]}` case "create_document": return `{"nodeId":"fixture-node"}` case "list_files": diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index ef191e85..e27f8644 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -27,12 +27,23 @@ const ( // its spelling while holding every other input constant. var paramAliasCompleteCommands = map[string][]string{ "aitable +base-search": {"aitable", "+base-search", "--query", "fixture"}, + "aitable +export-data": {"aitable", "+export-data", "--base-id", "base-1", "--scope", "all", "--format", "excel"}, "aitable +field-get": {"aitable", "+field-get", "--base-id", "base-1", "--table-id", "table-1"}, + "aitable +find-record": {"aitable", "+find-record", "--base", "base-1", "--table", "table-1", "--query", "fixture"}, "aitable +list-tables": {"aitable", "+list-tables", "--base", "base-1"}, "aitable +record-query": {"aitable", "+record-query", "--base-id", "base-1", "--table-id", "table-1", "--query", "fixture"}, + "aitable +record-share-links": {"aitable", "+record-share-links", "--base", "base-1", "--table", "table-1", "--record-ids", "record-1"}, "aitable +record-share-url": {"aitable", "+record-share-url", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1"}, "aitable +table-get": {"aitable", "+table-get", "--base-id", "base-1"}, + "aitable +workflow-list": {"aitable", "+workflow-list", "--base-id", "base-1", "--limit", "7"}, + "aitable attachment upload": {"aitable", "attachment", "upload", "--base-id", "base-1", "--file-name", "fixture.txt", "--size", "7", "--yes"}, + "aitable base list": {"aitable", "base", "list", "--cursor", "cursor-1", "--limit", "7"}, + "aitable base update": {"aitable", "base", "update", "--base-id", "base-1", "--name", "Fixture Base", "--desc", "fixture description", "--yes"}, + "aitable field search-options": {"aitable", "field", "search-options", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--keyword", "fixture", "--limit", "7"}, "aitable record query": {"aitable", "record", "query", "--base-id", "base-1", "--table-id", "table-1", "--limit", "7"}, + "aitable workflow get": {"aitable", "workflow", "get", "--base-id", "base-1", "--workflow-id", "workflow-1"}, + "aitable workflow history": {"aitable", "workflow", "history", "--base-id", "base-1", "--workflow-id", "workflow-1", "--after-time", "1000", "--before-time", "2000", "--page", "2", "--size", "25"}, + "aitable workflow run": {"aitable", "workflow", "run", "--base-id", "base-1", "--workflow-id", "workflow-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"}, "attendance check result": {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"}, "attendance +check-result": {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"}, "calendar event list": {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, @@ -402,7 +413,27 @@ var paramAliasNewDriveConfirmationCases = []struct { // That duplicated command construction was enough to push the pre-existing // macOS app suite beyond its package-level 10-minute timeout. var paramAliasRepresentativePayloadCases = map[string]bool{ + paramAliasPayloadCaseKey("aitable +export-data", "export-format"): true, // shortcut-local export format keeps the final payload + paramAliasPayloadCaseKey("aitable +find-record", "base-id"): true, // shortcut Base ID compatibility + paramAliasPayloadCaseKey("aitable +find-record", "table-id"): true, // shortcut Table ID compatibility paramAliasPayloadCaseKey("aitable +record-query", "base"): true, // concept alias on a shortcut read + paramAliasPayloadCaseKey("aitable +record-share-links", "base-id"): true, // observed experiment Base ID spelling + paramAliasPayloadCaseKey("aitable +record-share-links", "table-id"): true, // observed experiment Table ID spelling + paramAliasPayloadCaseKey("aitable +workflow-list", "max-results"): true, // shortcut pagination-size alias + paramAliasPayloadCaseKey("aitable attachment upload", "file-size"): true, // byte-size command override + paramAliasPayloadCaseKey("aitable base list", "next-cursor"): true, // cursor concept alias + paramAliasPayloadCaseKey("aitable base update", "description"): true, // plain description alias on a write command + paramAliasPayloadCaseKey("aitable field search-options", "query"): true, // search keyword concept alias + paramAliasPayloadCaseKey("aitable workflow get", "flow-id"): true, // workflow ID concept alias + paramAliasPayloadCaseKey("aitable workflow history", "base-token"): true, // Base ID concept alias + paramAliasPayloadCaseKey("aitable workflow history", "end-time"): true, // upper time-bound override + paramAliasPayloadCaseKey("aitable workflow history", "flow-id"): true, // workflow ID concept alias + paramAliasPayloadCaseKey("aitable workflow history", "page-index"): true, // zero-based page override + paramAliasPayloadCaseKey("aitable workflow history", "page-size"): true, // page-size concept alias + paramAliasPayloadCaseKey("aitable workflow history", "start-time"): true, // lower time-bound override + paramAliasPayloadCaseKey("aitable workflow run", "base-token"): true, // Base ID concept alias on a confirmed write + paramAliasPayloadCaseKey("aitable workflow run", "flow-id"): true, // workflow ID concept alias on a confirmed write + paramAliasPayloadCaseKey("aitable workflow run", "table"): true, // Table ID concept alias on a confirmed write paramAliasPayloadCaseKey("attendance check result", "user-ids"): true, // list-valued concept alias paramAliasPayloadCaseKey("calendar event list", "date"): true, // time concept alias paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"): true, // scoped IM identifier alias diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index c7c33ae3..fc5b2840 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -10,21 +10,336 @@ package cli // generatedParamAliases is the per-command parameter-alias table reduced from // the reviewed concept dictionary. Each entry binds one runnable Cobra leaf. var generatedParamAliases = []ParamAliasEntry{ + { + CLIPath: "aitable +advperm-disable", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +advperm-enable", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +attachment-put", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +attachment-remove", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +attachment-upload", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "file-size": "size", + }, + }, + { + CLIPath: "aitable +base-copy", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +base-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +base-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +base-get-primary-doc-id", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +base-list", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + }, + { + CLIPath: "aitable +base-schema-snapshot", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, { CLIPath: "aitable +base-search", Aliases: map[string]string{ - "keyword": "query", - "keywords": "query", - "q": "query", - "search-word": "query", + "keyword": "query", + "keywords": "query", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-token": "cursor", + "q": "query", + "search-word": "query", }, - Blocked: []string{"name", "subject", "text", "title"}, + Blocked: []string{"name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable +base-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "description": "desc", + }, + Blocked: []string{"config", "field-description"}, + }, + { + CLIPath: "aitable +chart-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +chart-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +chart-share-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +chart-share-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +chart-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-arrange", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-share-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-share-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +dashboard-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +export-data", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "export-format": "format", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +field-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, }, { CLIPath: "aitable +field-get", Aliases: map[string]string{ "base": "base-id", "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +field-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +find-record", + Aliases: map[string]string{ + "base-id": "base", + "base-token": "base", + "keyword": "query", + "keywords": "query", + "q": "query", + "search-word": "query", + "table-id": "table", + }, + Blocked: []string{"name", "source-table-id", "subject", "table-ids", "target-table-id", "text", "title"}, + }, + { + CLIPath: "aitable +form-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-field-hide", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-field-list", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-field-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-list", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-share-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-share-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +form-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "desc": "description", + "table": "table-id", + }, + Blocked: []string{"config", "field-description", "name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +import-data", + Aliases: map[string]string{ + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +import-upload", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "size": "file-size", }, }, { @@ -35,18 +350,256 @@ var generatedParamAliases = []ParamAliasEntry{ }, }, { - CLIPath: "aitable +record-query", + CLIPath: "aitable +record-bulk-patch", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "keyword": "query", + "keywords": "query", + "q": "query", + "search-word": "query", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "subject", "table-ids", "target-table-id", "text", "title"}, + }, + { + CLIPath: "aitable +record-delete", Aliases: map[string]string{ "base": "base-id", "base-token": "base-id", + "table": "table-id", }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-history-list", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "name", "page", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-primary-doc-create", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-primary-doc-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-query", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "source-table-id", "subject", "table-ids", "target-table-id", "text", "title"}, + }, + { + CLIPath: "aitable +record-query-empty", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-share-links", + Aliases: map[string]string{ + "base-id": "base", + "base-token": "base", + "table-id": "table", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, }, { CLIPath: "aitable +record-share-url", Aliases: map[string]string{ "base": "base-id", "base-token": "base-id", + "table": "table-id", }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-upsert", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +record-upsert-by-key", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +resolve-table", + Aliases: map[string]string{ + "base-id": "base", + "base-token": "base", + }, + }, + { + CLIPath: "aitable +role-create", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +role-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +role-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +role-list", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +role-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-create", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-list-empty", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-list-nodes", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-move-node", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-rename", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +section-reorder", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable +table-copy", + Aliases: map[string]string{ + "table-id": "source-table-id", + }, + Ambiguous: []string{"base", "base-id", "base-token"}, + }, + { + CLIPath: "aitable +table-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, }, { CLIPath: "aitable +table-get", @@ -56,16 +609,1155 @@ var generatedParamAliases = []ParamAliasEntry{ }, }, { - CLIPath: "aitable record query", + CLIPath: "aitable +table-update", Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "desc": "description", + "table": "table-id", + }, + Blocked: []string{"config", "field-description", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +template-search", + Aliases: map[string]string{ + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable +view-delete", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-duplicate", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-get-frozen-cols", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-get-lock", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-get-row-height", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-lock", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-preset-apply", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-set-fill-color-rule", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-set-frozen-cols", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-set-row-height", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +view-update", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable +workflow-deploy", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable +workflow-disable", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable +workflow-enable", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable +workflow-get", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable +workflow-list", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", "max-result": "limit", "max-results": "limit", + "page-size": "limit", "per-page": "limit", "size": "limit", "take": "limit", "top": "limit", }, - Blocked: []string{"count", "page"}, + Blocked: []string{"count", "cursor", "page"}, + }, + { + CLIPath: "aitable advperm disable", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm enable", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm role-create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm role-delete", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm role-get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm role-list", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable advperm role-update", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable attachment upload", + Aliases: map[string]string{ + "base-token": "base-id", + "file-size": "size", + }, + }, + { + CLIPath: "aitable base copy", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable base delete", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable base get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable base get-primary-doc-id", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable base list", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + }, + { + CLIPath: "aitable base search", + Aliases: map[string]string{ + "keywords": "query", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-token": "cursor", + "q": "query", + "search-word": "query", + }, + Blocked: []string{"name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable base update", + Aliases: map[string]string{ + "base-token": "base-id", + "description": "desc", + }, + Blocked: []string{"config", "field-description"}, + }, + { + CLIPath: "aitable chart create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable chart delete", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable chart get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable chart share get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable chart share update", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable chart update", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard arrange", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard delete", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard share get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard share update", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable dashboard update", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable export data", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable field create", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable field delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable field get", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable field list", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable field search-options", + Aliases: map[string]string{ + "base-token": "base-id", + "keywords": "keyword", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "q": "keyword", + "query": "keyword", + "search-word": "keyword", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "name", "page", "source-table-id", "subject", "table-ids", "target-table-id", "text", "title"}, + }, + { + CLIPath: "aitable field update", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form create", + Aliases: map[string]string{ + "base-token": "base-id", + "desc": "description", + "table": "table-id", + }, + Blocked: []string{"config", "field-description", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form field hide", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form field list", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form field update", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form get", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form list", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form questions create", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form questions delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form share get", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form share update", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable form update", + Aliases: map[string]string{ + "base-token": "base-id", + "desc": "description", + "table": "table-id", + }, + Blocked: []string{"config", "field-description", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable import data", + Aliases: map[string]string{ + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable import upload", + Aliases: map[string]string{ + "base-token": "base-id", + "size": "file-size", + }, + }, + { + CLIPath: "aitable info", + Aliases: map[string]string{ + "base": "base-id", + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable list", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "offset", "page"}, + }, + { + CLIPath: "aitable record batch-update", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record create", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record get", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record history-list", + Aliases: map[string]string{ + "base-token": "base-id", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "name", "page", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record list", + Aliases: map[string]string{ + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable record primary-doc-create", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record primary-doc-get", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record query", + Aliases: map[string]string{ + "base-token": "base-id", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "source-table-id", "subject", "table-ids", "target-table-id", "text", "title"}, + }, + { + CLIPath: "aitable record query-empty", + Aliases: map[string]string{ + "base-token": "base-id", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "size": "limit", + "table": "table-id", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record share-url", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record update", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable record upsert", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable search", + Aliases: map[string]string{ + "keywords": "query", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-token": "cursor", + "q": "query", + "search-word": "query", + }, + Blocked: []string{"name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable section create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section delete", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section list-empty", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section list-nodes", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section move-node", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section rename", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable section reorder", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable table create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable table delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable table get", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable table list", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable table update", + Aliases: map[string]string{ + "base-token": "base-id", + "desc": "description", + "table": "table-id", + }, + Blocked: []string{"config", "field-description", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable template search", + Aliases: map[string]string{ + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search-word": "query", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "name", "offset", "page", "subject", "text", "title"}, + }, + { + CLIPath: "aitable view create", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view delete", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view duplicate", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get aggregate", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get card", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get field-widths", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get fill-color-rule", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get filter", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get frozen-cols", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get group", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get lock", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get row-height", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get sort", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get timebar", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view get visible-fields", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view list", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view lock", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update aggregate", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update card", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update field-widths", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update fill-color-rule", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update filter", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update frozen-cols", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update group", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update name", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update row-height", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update sort", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update timebar", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable view update visible-fields", + Aliases: map[string]string{ + "base-token": "base-id", + "table": "table-id", + }, + Blocked: []string{"name", "source-table-id", "table-ids", "target-table-id"}, + }, + { + CLIPath: "aitable workflow create", + Aliases: map[string]string{ + "base-token": "base-id", + }, + }, + { + CLIPath: "aitable workflow disable", + Aliases: map[string]string{ + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable workflow enable", + Aliases: map[string]string{ + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable workflow get", + Aliases: map[string]string{ + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, + }, + { + CLIPath: "aitable workflow history", + Aliases: map[string]string{ + "base-token": "base-id", + "end-time": "before-time", + "flow-id": "workflow-id", + "limit": "size", + "max-result": "size", + "max-results": "size", + "page-index": "page", + "page-size": "size", + "per-page": "size", + "start-time": "after-time", + "take": "size", + "top": "size", + }, + Blocked: []string{"count", "current-page", "cursor", "id", "next-cursor", "next-token", "offset", "page-no", "page-number", "page-token", "task-id"}, + }, + { + CLIPath: "aitable workflow list", + Aliases: map[string]string{ + "base-token": "base-id", + "max-result": "limit", + "max-results": "limit", + "page-size": "limit", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "page"}, + }, + { + CLIPath: "aitable workflow run", + Aliases: map[string]string{ + "base-token": "base-id", + "flow-id": "workflow-id", + "table": "table-id", + }, + Blocked: []string{"id", "name", "record-id", "source-table-id", "table-ids", "target-table-id", "task-id"}, + }, + { + CLIPath: "aitable workflow update", + Aliases: map[string]string{ + "base-token": "base-id", + "flow-id": "workflow-id", + }, + Blocked: []string{"id", "task-id"}, }, { CLIPath: "attendance +check-result", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index f8297b32..2ea26e92 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -10,14 +10,17 @@ }, "concepts": { - "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "drive +find-file", "drive +search", "drive +search-docs", "drive search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"}, - "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +search-docs", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive permission list", "drive recent", "drive recycle list", "drive search", "drive star list", "mail thread list", "oa +list-executed"], "risk": "green"}, + "search_query": {"denotes":"search keyword string","canonical_hint":"query","members":["query","keyword","keywords","q","search-word"],"excludes":["name","subject","text","title"],"commands":["aitable +base-search","aitable +find-record","aitable +record-bulk-patch","aitable +record-query","aitable +template-search","aitable base search","aitable field search-options","aitable record list","aitable record query","aitable search","aitable template search","contact +dept-members","contact +resolve-dept","contact +search-user","doc +create-from-template","doc +find-doc","doc +search","doc +template-search","doc template search","drive +find-file","drive +search","drive +search-docs","drive search","mail +find-mail-user","mail user search","oa +search-forms","oa approval search-forms"],"risk":"green"}, + "pagination_size": {"denotes":"returned item count upper bound","canonical_hint":"limit","members":["limit","size","page-size","max-results","max-result","take","top","per-page"],"excludes":["count","page","cursor"],"commands":["aitable +base-list","aitable +record-history-list","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable +workflow-list","aitable base list","aitable field search-options","aitable list","aitable record history-list","aitable record list","aitable record query","aitable record query-empty","aitable template search","aitable workflow history","aitable workflow list","calendar event list","chat message list","devdoc article search","doc +comment-list","doc +find-doc","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +search-docs","drive +star-list","drive +version-history","drive list","drive list-spaces","drive permission list","drive recent","drive recycle list","drive search","drive star list","mail thread list","oa +list-executed"],"risk":"green"}, "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"}, - "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "drive +list", "drive +recent", "drive +recycle-list", "drive +search", "drive +star-list", "drive +version-history", "drive list", "drive list-spaces", "drive recent", "drive recycle list", "drive search", "drive star list"], "risk": "green"}, + "page_cursor": {"denotes":"pagination cursor/token","canonical_hint":"cursor","members":["cursor","next-cursor","page-token","next-token","next-page-token"],"excludes":["page","offset"],"commands":["aitable +base-list","aitable +base-search","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable base list","aitable base search","aitable list","aitable record list","aitable record query","aitable record query-empty","aitable search","aitable template search","calendar event list","doc +comment-list","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +star-list","drive +version-history","drive list","drive list-spaces","drive recent","drive recycle list","drive search","drive star list"],"risk":"green"}, "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc +checkpoint-update", "doc +comment-create", "doc +comment-reply", "doc +comment-update", "doc +create", "doc +doc-append", "doc block insert", "doc block update", "doc comment create", "doc comment create-inline", "doc comment reply", "doc comment update", "doc create"], "risk": "green"}, "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"}, "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"}, - "base_id": {"denotes": "multi-dimensional table Base id", "canonical_hint": "base-id", "members": ["base", "base-id", "base-token"], "excludes": [], "commands": ["aitable +field-get", "aitable +list-tables", "aitable +record-query", "aitable +record-share-url", "aitable +table-get"], "risk": "green"}, + "base_id": {"denotes":"multi-dimensional table Base id","canonical_hint":"base-id","members":["base","base-id","base-token"],"excludes":[],"commands":["aitable +advperm-disable","aitable +advperm-enable","aitable +attachment-put","aitable +attachment-remove","aitable +attachment-upload","aitable +base-copy","aitable +base-delete","aitable +base-get","aitable +base-get-primary-doc-id","aitable +base-schema-snapshot","aitable +base-update","aitable +chart-delete","aitable +chart-get","aitable +chart-share-get","aitable +chart-share-update","aitable +chart-update","aitable +dashboard-arrange","aitable +dashboard-delete","aitable +dashboard-get","aitable +dashboard-share-get","aitable +dashboard-share-update","aitable +dashboard-update","aitable +export-data","aitable +field-delete","aitable +field-get","aitable +field-update","aitable +find-record","aitable +form-delete","aitable +form-field-hide","aitable +form-field-list","aitable +form-field-update","aitable +form-list","aitable +form-share-get","aitable +form-share-update","aitable +form-update","aitable +import-upload","aitable +list-tables","aitable +record-bulk-patch","aitable +record-delete","aitable +record-history-list","aitable +record-primary-doc-create","aitable +record-primary-doc-get","aitable +record-query","aitable +record-query-empty","aitable +record-share-links","aitable +record-share-url","aitable +record-update","aitable +record-upsert","aitable +record-upsert-by-key","aitable +resolve-table","aitable +role-create","aitable +role-delete","aitable +role-get","aitable +role-list","aitable +role-update","aitable +section-create","aitable +section-delete","aitable +section-list-empty","aitable +section-list-nodes","aitable +section-move-node","aitable +section-rename","aitable +section-reorder","aitable +table-delete","aitable +table-get","aitable +table-update","aitable +view-delete","aitable +view-duplicate","aitable +view-get","aitable +view-get-frozen-cols","aitable +view-get-lock","aitable +view-get-row-height","aitable +view-lock","aitable +view-preset-apply","aitable +view-set-fill-color-rule","aitable +view-set-frozen-cols","aitable +view-set-row-height","aitable +view-update","aitable +workflow-deploy","aitable +workflow-disable","aitable +workflow-enable","aitable +workflow-get","aitable +workflow-list","aitable advperm disable","aitable advperm enable","aitable advperm role-create","aitable advperm role-delete","aitable advperm role-get","aitable advperm role-list","aitable advperm role-update","aitable attachment upload","aitable base copy","aitable base delete","aitable base get","aitable base get-primary-doc-id","aitable base update","aitable chart create","aitable chart delete","aitable chart get","aitable chart share get","aitable chart share update","aitable chart update","aitable dashboard arrange","aitable dashboard create","aitable dashboard delete","aitable dashboard get","aitable dashboard share get","aitable dashboard share update","aitable dashboard update","aitable export data","aitable field create","aitable field delete","aitable field get","aitable field list","aitable field search-options","aitable field update","aitable form create","aitable form delete","aitable form field hide","aitable form field list","aitable form field update","aitable form get","aitable form list","aitable form questions create","aitable form questions delete","aitable form share get","aitable form share update","aitable form update","aitable import upload","aitable info","aitable record batch-update","aitable record create","aitable record delete","aitable record get","aitable record history-list","aitable record primary-doc-create","aitable record primary-doc-get","aitable record query","aitable record query-empty","aitable record share-url","aitable record update","aitable record upsert","aitable section create","aitable section delete","aitable section list-empty","aitable section list-nodes","aitable section move-node","aitable section rename","aitable section reorder","aitable table create","aitable table delete","aitable table get","aitable table list","aitable table update","aitable view create","aitable view delete","aitable view duplicate","aitable view get aggregate","aitable view get card","aitable view get field-widths","aitable view get fill-color-rule","aitable view get filter","aitable view get frozen-cols","aitable view get group","aitable view get lock","aitable view get row-height","aitable view get sort","aitable view get timebar","aitable view get visible-fields","aitable view list","aitable view lock","aitable view update aggregate","aitable view update card","aitable view update field-widths","aitable view update fill-color-rule","aitable view update filter","aitable view update frozen-cols","aitable view update group","aitable view update name","aitable view update row-height","aitable view update sort","aitable view update timebar","aitable view update visible-fields","aitable workflow create","aitable workflow disable","aitable workflow enable","aitable workflow get","aitable workflow history","aitable workflow list","aitable workflow run","aitable workflow update"],"risk":"green"}, + "table_id": {"denotes":"single AI Table data-table Table ID","canonical_hint":"table-id","members":["table","table-id"],"excludes":["table-ids","source-table-id","target-table-id","name"],"commands":["aitable +attachment-put","aitable +attachment-remove","aitable +base-get-primary-doc-id","aitable +export-data","aitable +field-delete","aitable +field-get","aitable +field-update","aitable +find-record","aitable +form-delete","aitable +form-field-hide","aitable +form-field-list","aitable +form-field-update","aitable +form-list","aitable +form-share-get","aitable +form-share-update","aitable +form-update","aitable +import-data","aitable +record-bulk-patch","aitable +record-delete","aitable +record-history-list","aitable +record-primary-doc-create","aitable +record-primary-doc-get","aitable +record-query","aitable +record-query-empty","aitable +record-share-links","aitable +record-share-url","aitable +record-update","aitable +record-upsert","aitable +record-upsert-by-key","aitable +table-delete","aitable +table-update","aitable +view-delete","aitable +view-duplicate","aitable +view-get","aitable +view-get-frozen-cols","aitable +view-get-lock","aitable +view-get-row-height","aitable +view-lock","aitable +view-preset-apply","aitable +view-set-fill-color-rule","aitable +view-set-frozen-cols","aitable +view-set-row-height","aitable +view-update","aitable base get-primary-doc-id","aitable export data","aitable field create","aitable field delete","aitable field get","aitable field list","aitable field search-options","aitable field update","aitable form create","aitable form delete","aitable form field hide","aitable form field list","aitable form field update","aitable form get","aitable form list","aitable form questions create","aitable form questions delete","aitable form share get","aitable form share update","aitable form update","aitable import data","aitable record batch-update","aitable record create","aitable record delete","aitable record get","aitable record history-list","aitable record primary-doc-create","aitable record primary-doc-get","aitable record query","aitable record query-empty","aitable record share-url","aitable record update","aitable record upsert","aitable table delete","aitable table update","aitable view create","aitable view delete","aitable view duplicate","aitable view get aggregate","aitable view get card","aitable view get field-widths","aitable view get fill-color-rule","aitable view get filter","aitable view get frozen-cols","aitable view get group","aitable view get lock","aitable view get row-height","aitable view get sort","aitable view get timebar","aitable view get visible-fields","aitable view list","aitable view lock","aitable view update aggregate","aitable view update card","aitable view update field-widths","aitable view update fill-color-rule","aitable view update filter","aitable view update frozen-cols","aitable view update group","aitable view update name","aitable view update row-height","aitable view update sort","aitable view update timebar","aitable view update visible-fields","aitable workflow run"],"risk":"green"}, + "plain_description": {"denotes":"plain-text description or remark with unchanged value","canonical_hint":"description","members":["description","desc"],"excludes":["field-description","config"],"commands":["aitable +base-update","aitable +form-update","aitable +table-update","aitable base update","aitable form create","aitable form update","aitable table update"],"risk":"green"}, + "workflow_id": {"denotes":"single AI Table workflow identifier; service flowId and CLI workflow-id carry the same value","canonical_hint":"workflow-id","members":["workflow-id","flow-id"],"excludes":["id","task-id"],"commands":["aitable +workflow-deploy","aitable +workflow-disable","aitable +workflow-enable","aitable +workflow-get","aitable workflow disable","aitable workflow enable","aitable workflow get","aitable workflow history","aitable workflow run","aitable workflow update"],"risk":"green"}, "dept_id": {"denotes": "single department id", "canonical_hint": "dept", "members": ["dept", "dept-id", "department", "department-id", "parent", "parent-id"], "excludes": ["depts", "dept-ids", "department-ids", "name", "query"], "commands": ["contact +list-sub-depts", "contact dept list-children"], "risk": "yellow"}, "dept_ids": {"denotes": "department id list", "canonical_hint": "dept-ids", "members": ["depts", "dept-ids", "department-ids"], "excludes": ["dept", "dept-id", "department-id", "name", "query"], "commands": ["contact +list-dept-members"], "risk": "yellow"}, "group_id": {"denotes": "single DingTalk numeric groupId", "canonical_hint": "group-id", "members": ["group-id"], "excludes": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id", "conversation-ids", "open-conversation-ids", "group-name", "name", "id"], "commands": ["chat +chat-get-by-id", "chat group get-by-group-id"], "risk": "yellow"}, @@ -254,7 +257,15 @@ "drive recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."}, "drive +recent": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "Creator type, operation type, and file type filters are distinct and keep their enum/list forms."}, "drive +star-list": {"ambiguous": ["type", "types"], "scope_strict": true, "note": "The shortcut exposes only the API contentTypes filter. Generic type spellings may denote file extensions or node/resource types, so the current name-only layer must not guess the value domain."}, - "drive +upload": {"ambiguous": ["destination-id", "space", "target-id"], "scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "overwrite-node-id": "node", "directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "target-folder-id": "folder", "source-file": "file", "local-file": "file", "file-path": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id", "output-path"], "scope_strict": true, "note": "Local source path, remote display name, MIME type, parent folder, numeric storage space and optional overwrite node are distinct roles. ID-suffixed file/node spellings denote the overwrite target; the shortcut does not expose a knowledge-base workspace route."} + "drive +upload": {"ambiguous": ["destination-id", "space", "target-id"], "scoped_aliases": {"dentry-uuid": "node", "file-id": "node", "node-id": "node", "overwrite-node-id": "node", "directory-id": "folder", "parent-directory-id": "folder", "parent-folder-id": "folder", "target-folder-id": "folder", "source-file": "file", "local-file": "file", "file-path": "file", "content-type": "mime-type", "filename": "file-name", "name": "file-name", "display-name": "file-name", "upload-name": "file-name"}, "block": ["dentry-id", "document-url", "knowledge-base-id", "wiki-workspace-id", "workspace", "workspace-id", "output-path"], "scope_strict": true, "note": "Local source path, remote display name, MIME type, parent folder, numeric storage space and optional overwrite node are distinct roles. ID-suffixed file/node spellings denote the overwrite target; the shortcut does not expose a knowledge-base workspace route."}, +"aitable +export-data": {"scoped_aliases":{"export-format":"format"},"scope_strict":true,"note":"The shortcut's local --format is the export file format, unlike the root output-format flag; only the explicit --export-format spelling is mapped here."}, + "aitable attachment upload": {"scoped_aliases":{"file-size":"size"},"scope_strict":true,"note":"On this upload command --size is the local file size in bytes; the mapping is command-local because size is a pagination synonym elsewhere."}, + "aitable +attachment-upload": {"scoped_aliases":{"file-size":"size"},"scope_strict":true,"note":"On this upload command --size is the local file size in bytes; the mapping is command-local because size is a pagination synonym elsewhere."}, + "aitable import upload": {"scoped_aliases":{"size":"file-size"},"scope_strict":true,"note":"On this import-upload command --file-size is the local file size in bytes; the mapping is command-local because size is a pagination synonym elsewhere."}, + "aitable +import-upload": {"scoped_aliases":{"size":"file-size"},"scope_strict":true,"note":"On this import-upload command --file-size is the local file size in bytes; the mapping is command-local because size is a pagination synonym elsewhere."}, + "aitable +table-copy": {"scoped_aliases":{"table-id":"source-table-id"},"ambiguous":["base","base-id","base-token"],"scope_strict":true,"note":"The only existing table role is the source table, while an unqualified Base spelling cannot choose between source-base-id and target-base-id."}, + "aitable workflow run": {"block":["record-id"],"note":"The command accepts a list of one to five record IDs. A singular --record-id is deliberately blocked instead of relying on edit-distance correction; --table-id and --record-ids must remain paired for record-triggered workflows."}, + "aitable workflow history": {"scoped_aliases":{"start-time":"after-time","end-time":"before-time","page-index":"page"},"block":["cursor","offset","page-token","next-cursor","next-token","page-no","page-number","current-page"],"scope_strict":true,"note":"This endpoint uses a zero-based page plus per-page size, not cursor/offset pagination. Time-bound aliases preserve the required Unix-millisecond value unchanged."} }, "validation_fixture": { @@ -655,7 +666,35 @@ {"command": "drive +star-add", "emitted": "url", "expect": "node", "via": "override:existing-command-parity"}, {"command": "drive +star-remove", "emitted": "doc-id", "expect": "node", "via": "override:existing-command-parity"}, {"command": "drive +stats", "emitted": "document-url", "expect": "node", "via": "override:existing-command-parity"}, - {"command": "drive +upload", "emitted": "file-id", "expect": "node", "via": "override:overwrite-node-id-role"} + {"command": "drive +upload", "emitted": "file-id", "expect": "node", "via": "override:overwrite-node-id-role"}, + {"command":"aitable +find-record","emitted":"base-id","expect":"base","via":"concept:base_id"}, + {"command":"aitable record query","emitted":"base-token","expect":"base-id","via":"concept:base_id"}, + {"command":"aitable +find-record","emitted":"table-id","expect":"table","via":"concept:table_id"}, + {"command":"aitable +record-share-links","emitted":"base-id","expect":"base","via":"concept:base_id+experiment"}, + {"command":"aitable +record-share-links","emitted":"table-id","expect":"table","via":"concept:table_id+experiment"}, + {"command":"aitable record query","emitted":"table","expect":"table-id","via":"concept:table_id"}, + {"command":"aitable field search-options","emitted":"query","expect":"keyword","via":"concept:search_query"}, + {"command":"aitable +workflow-list","emitted":"max-results","expect":"limit","via":"concept:pagination_size"}, + {"command":"aitable base list","emitted":"next-cursor","expect":"cursor","via":"concept:page_cursor"}, + {"command":"aitable base update","emitted":"description","expect":"desc","via":"concept:plain_description"}, + {"command":"aitable attachment upload","emitted":"file-size","expect":"size","via":"override:scoped(file-size-bytes)"}, + {"command":"aitable workflow get","emitted":"flow-id","expect":"workflow-id","via":"concept:workflow_id"}, + {"command":"aitable +export-data","emitted":"export-format","expect":"format","via":"override:scoped"}, + {"command":"aitable +table-copy","emitted":"base-id","expect":"did-you-mean:ambiguous","via":"guard:source-vs-target-base"}, + {"command":"aitable workflow run","emitted":"base-token","expect":"base-id","via":"concept:base_id"}, + {"command":"aitable workflow run","emitted":"flow-id","expect":"workflow-id","via":"concept:workflow_id"}, + {"command":"aitable workflow run","emitted":"table","expect":"table-id","via":"concept:table_id"}, + {"command":"aitable workflow run","emitted":"record-id","expect":"did-you-mean:blocked","via":"guard:single-vs-list"}, + {"command":"aitable workflow run","emitted":"id","expect":"did-you-mean:blocked","via":"guard:generic-id-multiple-roles"}, + {"command":"aitable workflow history","emitted":"base-token","expect":"base-id","via":"concept:base_id"}, + {"command":"aitable workflow history","emitted":"flow-id","expect":"workflow-id","via":"concept:workflow_id"}, + {"command":"aitable workflow history","emitted":"page-size","expect":"size","via":"concept:pagination_size"}, + {"command":"aitable workflow history","emitted":"start-time","expect":"after-time","via":"override:scoped-time-bound"}, + {"command":"aitable workflow history","emitted":"end-time","expect":"before-time","via":"override:scoped-time-bound"}, + {"command":"aitable workflow history","emitted":"page-index","expect":"page","via":"override:scoped-zero-based-page"}, + {"command":"aitable workflow history","emitted":"cursor","expect":"did-you-mean:blocked","via":"guard:page-vs-cursor-model"}, + {"command":"aitable workflow history","emitted":"offset","expect":"did-you-mean:blocked","via":"guard:page-vs-offset-model"}, + {"command":"aitable workflow history","emitted":"page-number","expect":"did-you-mean:blocked","via":"guard:zero-vs-one-based-page"} ] } } From b199fd29cb78c32e365a1696c9458a2c5775c034 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Mon, 17 Aug 2026 20:53:32 +0800 Subject: [PATCH 194/250] test(recruit): cover missing request job id --- internal/helpers/recruit_test.go | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 41b9efe5..0222d08c 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -691,6 +691,13 @@ func TestRecruitResultCallRejectsInvalidJobResults(t *testing.T) { text: `{"success":true,"result":{"name":"Java 工程师"}}`, wantMessage: "缺少非空字符串字段 jobId", }, + { + name: "get request missing job id", + tool: recruitGetJobTool, + args: map[string]any{}, + text: `{"success":true,"result":{"jobId":"job-returned"}}`, + wantMessage: "请求缺少非空字符串字段 jobId", + }, { name: "get mismatched job id", tool: recruitGetJobTool, From 70ed89c6bf3cda14174837155fdaf8f0a10041d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Mon, 17 Aug 2026 21:28:01 +0800 Subject: [PATCH 195/250] test(cli): preserve AITable confirmation gates --- .../param_alias_payload_equivalence_test.go | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index e27f8644..33adae66 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -36,9 +36,9 @@ var paramAliasCompleteCommands = map[string][]string{ "aitable +record-share-url": {"aitable", "+record-share-url", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1"}, "aitable +table-get": {"aitable", "+table-get", "--base-id", "base-1"}, "aitable +workflow-list": {"aitable", "+workflow-list", "--base-id", "base-1", "--limit", "7"}, - "aitable attachment upload": {"aitable", "attachment", "upload", "--base-id", "base-1", "--file-name", "fixture.txt", "--size", "7", "--yes"}, + "aitable attachment upload": {"aitable", "attachment", "upload", "--base-id", "base-1", "--file-name", "fixture.txt", "--size", "7"}, "aitable base list": {"aitable", "base", "list", "--cursor", "cursor-1", "--limit", "7"}, - "aitable base update": {"aitable", "base", "update", "--base-id", "base-1", "--name", "Fixture Base", "--desc", "fixture description", "--yes"}, + "aitable base update": {"aitable", "base", "update", "--base-id", "base-1", "--name", "Fixture Base", "--desc", "fixture description"}, "aitable field search-options": {"aitable", "field", "search-options", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--keyword", "fixture", "--limit", "7"}, "aitable record query": {"aitable", "record", "query", "--base-id", "base-1", "--table-id", "table-1", "--limit", "7"}, "aitable workflow get": {"aitable", "workflow", "get", "--base-id", "base-1", "--workflow-id", "workflow-1"}, @@ -383,16 +383,19 @@ var paramAliasNewDriveCases = []struct { {command: "drive +upload", emitted: "file-id", canonical: "node"}, } -// paramAliasNewDriveConfirmationCases selects one newly reviewed alias for -// every Drive command in the expansion whose declared runtime safety requires -// confirmation. The full matrix below proves all spellings preserve the -// confirmed payload; this smaller matrix proves aliases cannot cross the -// confirmation boundary before any transport call is made. -var paramAliasNewDriveConfirmationCases = []struct { +// paramAliasNewConfirmationCases selects newly reviewed aliases for commands +// whose declared runtime safety requires confirmation. The full matrix below +// proves all spellings preserve the confirmed payload; this smaller matrix +// proves aliases cannot cross the confirmation boundary before any transport +// call is made. +var paramAliasNewConfirmationCases = []struct { command string emitted string canonical string }{ + {command: "aitable workflow run", emitted: "base-token", canonical: "base-id"}, + {command: "aitable workflow run", emitted: "flow-id", canonical: "workflow-id"}, + {command: "aitable workflow run", emitted: "table", canonical: "table-id"}, {command: "drive +delete", emitted: "file-id", canonical: "node"}, {command: "drive +publish-unset", emitted: "document-url", canonical: "node"}, {command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"}, @@ -660,13 +663,13 @@ func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalP } } -func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *testing.T) { - for _, test := range paramAliasNewDriveConfirmationCases { +func TestCrossPlatformCoverageNewParamAliasesCannotBypassConfirmation(t *testing.T) { + for _, test := range paramAliasNewConfirmationCases { test := test t.Run(test.command+"/"+test.emitted, func(t *testing.T) { complete, ok := paramAliasCompleteCommand(test.command, test.canonical) if !ok { - t.Fatal("reviewed Drive confirmation alias has no complete-command E2E template") + t.Fatal("reviewed confirmation alias has no complete-command E2E template") } aliasArgs, replacements := replaceLongFlag(complete, test.canonical, test.emitted) if replacements != 1 { @@ -680,7 +683,7 @@ func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *te entry, exists := cli.LookupParamAlias(test.command) target, active := entry.ResolveAlias(test.emitted) if !exists || !active || target != test.canonical { - t.Fatalf("reviewed Drive alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical) + t.Fatalf("reviewed confirmation alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical) } caller := ¶mAliasCaptureCaller{} From 92c80f81f96e9744a22c5d500377018e37e1e10f Mon Sep 17 00:00:00 2001 From: Dennis Date: Mon, 17 Aug 2026 21:19:36 +0800 Subject: [PATCH 196/250] fix(calendar): align attendee and agenda contracts --- .../schema_calendar_shortcut_contract_test.go | 31 +++++++ internal/shortcut/calendar/calendar.go | 75 +++++++++------- .../calendar_cross_platform_coverage_test.go | 88 ++++++++++++++++++- 3 files changed, 160 insertions(+), 34 deletions(-) create mode 100644 internal/app/schema_calendar_shortcut_contract_test.go diff --git a/internal/app/schema_calendar_shortcut_contract_test.go b/internal/app/schema_calendar_shortcut_contract_test.go new file mode 100644 index 00000000..bd39b780 --- /dev/null +++ b/internal/app/schema_calendar_shortcut_contract_test.go @@ -0,0 +1,31 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. + +package app + +import "testing" + +func TestCrossPlatformCoverageCalendarAgendaFinalSchemaPreservesCompositeProperties(t *testing.T) { + snapshot := fullSchemaSnapshotForTest(t) + tool := snapshot.Tools["calendar.shortcut_agenda"] + if tool == nil { + t.Fatal("calendar.shortcut_agenda is missing from final Schema") + } + parameters := schemaContractMap(tool["parameters"]) + for flag, want := range map[string]string{ + "start": "start", + "end": "end", + } { + parameter := parameters[flag] + if parameter == nil { + t.Fatalf("calendar.shortcut_agenda --%s is missing from final Schema", flag) + } + if got := schemaContractString(parameter["property"]); got != want { + t.Errorf("calendar.shortcut_agenda --%s property=%q, want %q", flag, got, want) + } + } + if got := schemaContractString(tool["interface_mode"]); got != "composite" { + t.Fatalf("calendar.shortcut_agenda interface_mode=%q, want composite", got) + } +} diff --git a/internal/shortcut/calendar/calendar.go b/internal/shortcut/calendar/calendar.go index 7559d07e..7645603a 100644 --- a/internal/shortcut/calendar/calendar.go +++ b/internal/shortcut/calendar/calendar.go @@ -90,37 +90,9 @@ var EventList = shortcut.Shortcut{ `dws calendar +agenda --start "2026-03-10T00:00:00+08:00" --end "2026-03-31T23:59:59+08:00" --limit 50`, }, Execute: func(rt *shortcut.RuntimeContext) error { - params := map[string]any{} - now := time.Now() - if rt.Changed("start") { - ms, err := parseMillis("start", rt.Str("start")) - if err != nil { - return err - } - params["startTime"] = ms - } else { - params["startTime"] = time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()).UnixMilli() - } - if rt.Changed("end") { - ms, err := parseMillis("end", rt.Str("end")) - if err != nil { - return err - } - params["endTime"] = ms - } else { - params["endTime"] = time.Date(now.Year(), now.Month(), now.Day(), 23, 59, 59, 0, now.Location()).UnixMilli() - } - if rt.Changed("calendar-id") { - params["calendarId"] = rt.Str("calendar-id") - } - if rt.Changed("cursor") { - params["cursor"] = rt.Str("cursor") - } - if rt.Changed("limit") { - params["limit"] = rt.Int("limit") - } - if params["endTime"].(int64) <= params["startTime"].(int64) { - return fmt.Errorf("--end 必须晚于 --start") + params, err := calendarAgendaParams(rt, time.Now()) + if err != nil { + return err } data, err := rt.CallMCPData("calendar", "list_calendar_events", params) if err != nil { @@ -135,6 +107,45 @@ var EventList = shortcut.Shortcut{ }, } +// calendarAgendaParams is the explicit adapter from the published composite +// Shortcut properties (start/end) to list_calendar_events RPC properties +// (startTime/endTime). The public Schema property names predate this adapter +// and remain stable for backwards compatibility. +func calendarAgendaParams(rt *shortcut.RuntimeContext, now time.Time) (map[string]any, error) { + params := map[string]any{} + if rt.Changed("start") { + ms, err := parseMillis("start", rt.Str("start")) + if err != nil { + return nil, err + } + params["startTime"] = ms + } else { + params["startTime"] = time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()).UnixMilli() + } + if rt.Changed("end") { + ms, err := parseMillis("end", rt.Str("end")) + if err != nil { + return nil, err + } + params["endTime"] = ms + } else { + params["endTime"] = time.Date(now.Year(), now.Month(), now.Day(), 23, 59, 59, 0, now.Location()).UnixMilli() + } + if rt.Changed("calendar-id") { + params["calendarId"] = rt.Str("calendar-id") + } + if rt.Changed("cursor") { + params["cursor"] = rt.Str("cursor") + } + if rt.Changed("limit") { + params["limit"] = rt.Int("limit") + } + if params["endTime"].(int64) <= params["startTime"].(int64) { + return nil, fmt.Errorf("--end 必须晚于 --start") + } + return params, nil +} + // eventListProject reshapes the raw list_calendar_events response into a clean, // stable event list (eventId/summary/start/end/status/location) — the // the clean output projection applied to every list command. The @@ -274,7 +285,7 @@ func attendeeListProject(data map[string]any) ([]map[string]any, error) { "userId": {"userId", "user_id", "id", "staffId", "staff_id", "unionId", "union_id"}, "responseStatus": {"responseStatus", "response_status", "status", "attendeeStatus", "attendee_status", "responseType", "response"}, "self": {"self"}, - }, "displayName") + }, "displayName", "userId") } // attendeeListContainer locates the participant slice across candidate wrapper diff --git a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go index 933e4316..e3f2ec4a 100644 --- a/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go +++ b/internal/shortcut/calendar/calendar_cross_platform_coverage_test.go @@ -10,6 +10,7 @@ import ( "io" "strings" "testing" + "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" @@ -206,9 +207,45 @@ func TestCrossPlatformCoverageCalendarRoomFindPreservesPublishedFlags(t *testing if len(invalid.history) != 0 { t.Fatalf("invalid input made calls: %v", invalid.history) } + + fixedNow := time.Date(2026, time.August, 17, 12, 0, 0, 0, time.FixedZone("UTC+8", 8*60*60)) + defaultParams, err := calendarAgendaParams(calendarRuntimeForTest(t, EventList, nil), fixedNow) + if err != nil { + t.Fatal(err) + } + if defaultParams["startTime"] != time.Date(2026, time.August, 17, 0, 0, 0, 0, fixedNow.Location()).UnixMilli() || + defaultParams["endTime"] != time.Date(2026, time.August, 17, 23, 59, 59, 0, fixedNow.Location()).UnixMilli() { + t.Fatalf("agenda default adapter arguments=%#v", defaultParams) + } + + allParams, err := calendarAgendaParams(calendarRuntimeForTest(t, EventList, map[string]string{ + "start": calendarCoverageStart, + "end": calendarCoverageEnd, + "calendar-id": "primary", + "cursor": "cursor-1", + "limit": "7", + }), fixedNow) + if err != nil { + t.Fatal(err) + } + if allParams["calendarId"] != "primary" || allParams["cursor"] != "cursor-1" || allParams["limit"] != 7 { + t.Fatalf("agenda optional adapter arguments=%#v", allParams) + } + + for name, values := range map[string]map[string]string{ + "invalid-start": {"start": "bad"}, + "invalid-end": {"end": "bad"}, + "reversed": {"start": calendarCoverageEnd, "end": calendarCoverageStart}, + } { + t.Run(name, func(t *testing.T) { + if _, err := calendarAgendaParams(calendarRuntimeForTest(t, EventList, values), fixedNow); err == nil { + t.Fatal("invalid agenda adapter input was accepted") + } + }) + } } -func TestCrossPlatformCoverageCalendarAgendaPreservesPublishedSchema(t *testing.T) { +func TestCrossPlatformCoverageCalendarAgendaSchemaUsesExplicitRuntimeAdapter(t *testing.T) { properties := make(map[string]string, len(EventList.Contract.Parameters)) for _, parameter := range EventList.Contract.Parameters { properties[parameter.Name] = parameter.Property @@ -225,7 +262,10 @@ func TestCrossPlatformCoverageCalendarAgendaPreservesPublishedSchema(t *testing. caller := &calendarCoverageCaller{responses: map[string][]string{ "list_calendar_events": {`{"success":true,"result":{"events":[],"hasMore":false}}`}, }} - if err := runCalendarCoverage(t, EventList, caller); err != nil { + if err := runCalendarCoverage(t, EventList, caller, + "--start", calendarCoverageStart, + "--end", calendarCoverageEnd, + ); err != nil { t.Fatal(err) } if len(caller.arguments) != 1 { @@ -234,6 +274,23 @@ func TestCrossPlatformCoverageCalendarAgendaPreservesPublishedSchema(t *testing. if _, ok := caller.arguments[0]["limit"]; ok { t.Fatalf("unset limit unexpectedly sent: %#v", caller.arguments[0]) } + start, err := parseMillis("start", calendarCoverageStart) + if err != nil { + t.Fatal(err) + } + end, err := parseMillis("end", calendarCoverageEnd) + if err != nil { + t.Fatal(err) + } + if caller.arguments[0]["startTime"] != start || caller.arguments[0]["endTime"] != end { + t.Fatalf("agenda adapter arguments=%#v, published properties=%#v", caller.arguments[0], properties) + } + if _, leaked := caller.arguments[0][properties["start"]]; leaked { + t.Fatalf("published composite property leaked into RPC arguments: %#v", caller.arguments[0]) + } + if _, leaked := caller.arguments[0][properties["end"]]; leaked { + t.Fatalf("published composite property leaked into RPC arguments: %#v", caller.arguments[0]) + } invalid := &calendarCoverageCaller{responses: map[string][]string{}} if err := runCalendarCoverage(t, EventList, invalid, "--limit", "101"); err == nil || !strings.Contains(err.Error(), "1") { @@ -243,3 +300,30 @@ func TestCrossPlatformCoverageCalendarAgendaPreservesPublishedSchema(t *testing. t.Fatalf("invalid input made calls: %v", invalid.history) } } + +func TestCrossPlatformCoverageCalendarAttendeeProjectionAcceptsStableUserID(t *testing.T) { + attendees, err := attendeeListProject(map[string]any{ + "success": true, + "result": map[string]any{ + "attendees": []any{map[string]any{ + "userId": "user-1", + "responseStatus": "accepted", + }}, + }, + }) + if err != nil { + t.Fatalf("userId-only attendee rejected: %v", err) + } + if len(attendees) != 1 || attendees[0]["userId"] != "user-1" { + t.Fatalf("attendees=%#v", attendees) + } + + if _, err := attendeeListProject(map[string]any{ + "success": true, + "result": map[string]any{ + "attendees": []any{map[string]any{"responseStatus": "accepted"}}, + }, + }); err == nil { + t.Fatal("attendee without displayName or userId was accepted") + } +} From ea18feb0a83f10650572ca08edd3fa79b320e9d7 Mon Sep 17 00:00:00 2001 From: Dennis Date: Tue, 18 Aug 2026 00:41:34 +0800 Subject: [PATCH 197/250] fix(calendar): keep pagination out of result data --- .../schema_calendar_shortcut_contract_test.go | 18 ++++++ ...additional_cross_platform_coverage_test.go | 56 +++++++++++++++++++ internal/shortcut/calendar/common.go | 2 +- 3 files changed, 75 insertions(+), 1 deletion(-) diff --git a/internal/app/schema_calendar_shortcut_contract_test.go b/internal/app/schema_calendar_shortcut_contract_test.go index bd39b780..6e93fea2 100644 --- a/internal/app/schema_calendar_shortcut_contract_test.go +++ b/internal/app/schema_calendar_shortcut_contract_test.go @@ -28,4 +28,22 @@ func TestCrossPlatformCoverageCalendarAgendaFinalSchemaPreservesCompositePropert if got := schemaContractString(tool["interface_mode"]); got != "composite" { t.Fatalf("calendar.shortcut_agenda interface_mode=%q, want composite", got) } + result := schemaContractMap(tool["result"]) + dataSchema := schemaContractMap(result["data_schema"]) + properties := schemaContractMap(dataSchema["properties"]) + for _, field := range []string{"hasMore", "nextCursor"} { + if _, exists := properties[field]; exists { + t.Fatalf("calendar.shortcut_agenda Result data_schema leaked pagination field %q", field) + } + } + if properties["complete"] == nil { + t.Fatal("calendar.shortcut_agenda Result data_schema is missing complete") + } + pagination, ok := tool["pagination"].(map[string]any) + if !ok { + t.Fatalf("calendar.shortcut_agenda pagination=%T, want object", tool["pagination"]) + } + if got := schemaContractString(pagination["meta_path"]); got != "meta.pagination" { + t.Fatalf("calendar.shortcut_agenda pagination meta_path=%q, want meta.pagination", got) + } } diff --git a/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go b/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go index 840fc61e..e728844d 100644 --- a/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go +++ b/internal/shortcut/calendar/calendar_additional_cross_platform_coverage_test.go @@ -4,6 +4,9 @@ package calendar import ( + "bytes" + "context" + "encoding/json" "math" "strconv" "strings" @@ -39,6 +42,21 @@ func TestCrossPlatformCoverageCalendarCommonBranches(t *testing.T) { if calendarReadShortcut("+x", "x", "x", "items", nil, nil, nil).Contract.Result == nil { t.Fatal("collection read shortcut did not build a result") } + collectionResult := calendarCollectionResult("items", "items") + var collectionSchema struct { + Properties map[string]json.RawMessage `json:"properties"` + } + if err := json.Unmarshal(collectionResult.DataSchema, &collectionSchema); err != nil { + t.Fatalf("decode collection result schema: %v", err) + } + for _, field := range []string{"hasMore", "nextCursor"} { + if _, exists := collectionSchema.Properties[field]; exists { + t.Fatalf("pagination field %q leaked into business Result schema", field) + } + } + if _, exists := collectionSchema.Properties["complete"]; !exists { + t.Fatal("collection Result schema lost business completeness evidence") + } if calendarWriteShortcut("+x", "x", "x", "dws calendar +x", nil, nil, nil).Safety.Confirmation != "user_required" { t.Fatal("write shortcut did not build safety") } @@ -178,6 +196,44 @@ func TestCrossPlatformCoverageCalendarCommonBranches(t *testing.T) { if err := runCalendarCoverage(t, legacyPage, &calendarCoverageCaller{responses: map[string][]string{}}, "--event", "event-1"); err != nil { t.Fatalf("legacy pagination output: %v", err) } + + unifiedPage := EventGet + unifiedPage.OutputRollout = output.RolloutUnifiedActive + cmd := corecmd.New(shortcut.FromShortcut(unifiedPage)) + ctx, _ := output.WithResultStore(context.Background()) + cmd.SetContext(ctx) + var stdout bytes.Buffer + cmd.SetOut(&stdout) + rt := shortcut.RuntimeContextForTest(cmd, unifiedPage) + if err := outputCalendarPage(rt, map[string]any{"count": 1, "items": []any{map[string]any{"id": "item-1"}}}, calendarPageEvidence{Known: true, HasMore: true, NextCursor: "cursor-2"}); err != nil { + t.Fatalf("store unified pagination result: %v", err) + } + if code, emitted, err := output.EmitStoredResult(cmd); err != nil || !emitted || code != 0 { + t.Fatalf("emit unified pagination result: code=%d emitted=%v err=%v", code, emitted, err) + } + var envelope struct { + Data map[string]any `json:"data"` + Meta struct { + Pagination *struct { + EndpointExhausted bool `json:"endpoint_exhausted"` + NextToken string `json:"next_token"` + } `json:"pagination"` + } `json:"meta"` + } + if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil { + t.Fatalf("decode unified pagination output: %v\n%s", err, stdout.String()) + } + for _, field := range []string{"hasMore", "nextCursor"} { + if _, exists := envelope.Data[field]; exists { + t.Fatalf("pagination field %q leaked into business data: %s", field, stdout.String()) + } + } + if envelope.Data["complete"] != false { + t.Fatalf("business completeness=%#v, want false: %s", envelope.Data["complete"], stdout.String()) + } + if envelope.Meta.Pagination == nil || envelope.Meta.Pagination.EndpointExhausted || envelope.Meta.Pagination.NextToken != "cursor-2" { + t.Fatalf("pagination meta=%+v: %s", envelope.Meta.Pagination, stdout.String()) + } } func TestCrossPlatformCoverageCalendarEventGetSearchAndSuggestion(t *testing.T) { diff --git a/internal/shortcut/calendar/common.go b/internal/shortcut/calendar/common.go index 988f7fdd..e0d7c27f 100644 --- a/internal/shortcut/calendar/common.go +++ b/internal/shortcut/calendar/common.go @@ -66,7 +66,7 @@ func calendarCollectionResult(collection, description string) *contract.ResultSp return &contract.ResultSpec{ Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, DataSchema: json.RawMessage(fmt.Sprintf( - `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"本页有效业务记录数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"Calendar 业务条目","additionalProperties":true}},"complete":{"type":"boolean","description":"服务端分页证据是否证明结果已完整"},"hasMore":{"type":"boolean","description":"服务端是否明确仍有后续页"},"nextCursor":{"type":"string","description":"服务端返回的下一页游标"}},"required":["count",%q,"complete"],"additionalProperties":true}`, + `{"type":"object","description":%q,"properties":{"count":{"type":"integer","description":"本页有效业务记录数量"},%q:{"type":"array","description":%q,"items":{"type":"object","description":"Calendar 业务条目","additionalProperties":true}},"complete":{"type":"boolean","description":"服务端分页证据是否证明结果已完整"}},"required":["count",%q,"complete"],"additionalProperties":true}`, description, collection, description, collection, )), } From b7bc0acb146e7ea61b5e5ec64cfbb5ffdba5a7e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Tue, 18 Aug 2026 09:44:42 +0800 Subject: [PATCH 198/250] test(cli): cover AITable destructive alias gates --- .../param_alias_payload_equivalence_test.go | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 33adae66..dad32b74 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -383,6 +383,100 @@ var paramAliasNewDriveCases = []struct { {command: "drive +upload", emitted: "file-id", canonical: "node"}, } +// paramAliasAITableDeleteDisableCompleteCommands contains complete invocations +// for every AITable delete/disable command whose confirmation boundary is +// reached by aliases introduced in the AITable expansion. These templates are +// intentionally separate from paramAliasCompleteCommands: that map mirrors +// the reviewed validation fixture one-for-one, while this matrix exhaustively +// proves the safety boundary for generated aliases beyond the fixture sample. +var paramAliasAITableDeleteDisableCompleteCommands = map[string][]string{ + "aitable +advperm-disable": {"aitable", "+advperm-disable", "--base-id", "base-1", "--yes"}, + "aitable +base-delete": {"aitable", "+base-delete", "--base-id", "base-1", "--yes"}, + "aitable +chart-delete": {"aitable", "+chart-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"}, + "aitable +dashboard-delete": {"aitable", "+dashboard-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"}, + "aitable +field-delete": {"aitable", "+field-delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"}, + "aitable +form-delete": {"aitable", "+form-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"}, + "aitable +record-delete": {"aitable", "+record-delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"}, + "aitable +role-delete": {"aitable", "+role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"}, + "aitable +section-delete": {"aitable", "+section-delete", "--base-id", "base-1", "--section-id", "section-1", "--yes"}, + "aitable +table-delete": {"aitable", "+table-delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"}, + "aitable +view-delete": {"aitable", "+view-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"}, + "aitable +workflow-disable": {"aitable", "+workflow-disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"}, + "aitable advperm disable": {"aitable", "advperm", "disable", "--base-id", "base-1", "--yes"}, + "aitable advperm role-delete": {"aitable", "advperm", "role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"}, + "aitable base delete": {"aitable", "base", "delete", "--base-id", "base-1", "--yes"}, + "aitable chart delete": {"aitable", "chart", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"}, + "aitable dashboard delete": {"aitable", "dashboard", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"}, + "aitable field delete": {"aitable", "field", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"}, + "aitable form delete": {"aitable", "form", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"}, + "aitable form questions delete": {"aitable", "form", "questions", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"}, + "aitable record delete": {"aitable", "record", "delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"}, + "aitable table delete": {"aitable", "table", "delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"}, + "aitable view delete": {"aitable", "view", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"}, + "aitable workflow disable": {"aitable", "workflow", "disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"}, +} + +// paramAliasNewAITableDeleteDisableCases is the exhaustive set of alias +// tuples newly introduced by this change on AITable delete/disable commands +// that require confirmation. Every tuple must remain on both sides of the +// confirmation gate: rejected with zero calls before --yes, and exactly +// payload-equivalent to its canonical spelling after --yes. +var paramAliasNewAITableDeleteDisableCases = []struct { + command string + emitted string + canonical string +}{ + {command: "aitable +advperm-disable", emitted: "base", canonical: "base-id"}, + {command: "aitable +advperm-disable", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +base-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +base-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +chart-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +chart-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +dashboard-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +dashboard-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +field-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +field-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +field-delete", emitted: "table", canonical: "table-id"}, + {command: "aitable +form-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +form-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +form-delete", emitted: "table", canonical: "table-id"}, + {command: "aitable +record-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +record-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +record-delete", emitted: "table", canonical: "table-id"}, + {command: "aitable +role-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +role-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +section-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +section-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +table-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +table-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +table-delete", emitted: "table", canonical: "table-id"}, + {command: "aitable +view-delete", emitted: "base", canonical: "base-id"}, + {command: "aitable +view-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +view-delete", emitted: "table", canonical: "table-id"}, + {command: "aitable +workflow-disable", emitted: "base", canonical: "base-id"}, + {command: "aitable +workflow-disable", emitted: "base-token", canonical: "base-id"}, + {command: "aitable +workflow-disable", emitted: "flow-id", canonical: "workflow-id"}, + {command: "aitable advperm disable", emitted: "base-token", canonical: "base-id"}, + {command: "aitable advperm role-delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable base delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable chart delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable dashboard delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable field delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable field delete", emitted: "table", canonical: "table-id"}, + {command: "aitable form delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable form delete", emitted: "table", canonical: "table-id"}, + {command: "aitable form questions delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable form questions delete", emitted: "table", canonical: "table-id"}, + {command: "aitable record delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable record delete", emitted: "table", canonical: "table-id"}, + {command: "aitable table delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable table delete", emitted: "table", canonical: "table-id"}, + {command: "aitable view delete", emitted: "base-token", canonical: "base-id"}, + {command: "aitable view delete", emitted: "table", canonical: "table-id"}, + {command: "aitable workflow disable", emitted: "base-token", canonical: "base-id"}, + {command: "aitable workflow disable", emitted: "flow-id", canonical: "workflow-id"}, +} + // paramAliasNewConfirmationCases selects newly reviewed aliases for commands // whose declared runtime safety requires confirmation. The full matrix below // proves all spellings preserve the confirmed payload; this smaller matrix @@ -663,6 +757,109 @@ func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalP } } +func TestCrossPlatformCoverageNewAITableDeleteDisableAliasesPreserveConfirmationAndPayload(t *testing.T) { + coveredCommands := make(map[string]bool) + reviewedAliases := make(map[string]string, len(paramAliasNewAITableDeleteDisableCases)) + for _, test := range paramAliasNewAITableDeleteDisableCases { + test := test + caseKey := paramAliasPayloadCaseKey(test.command, test.emitted) + if previous, duplicate := reviewedAliases[caseKey]; duplicate { + t.Fatalf("duplicate AITable delete/disable alias case %q: --%s and --%s", caseKey, previous, test.canonical) + } + reviewedAliases[caseKey] = test.canonical + t.Run(test.command+"/"+test.emitted, func(t *testing.T) { + complete, ok := paramAliasAITableDeleteDisableCompleteCommands[test.command] + if !ok { + t.Fatal("reviewed AITable delete/disable alias has no complete safety template") + } + coveredCommands[test.command] = true + + canonicalArgs := append([]string(nil), complete...) + aliasArgs, replacements := replaceLongFlag(canonicalArgs, test.canonical, test.emitted) + if replacements != 1 { + t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, canonicalArgs) + } + unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes") + if removals != 1 { + t.Fatalf("safety template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs) + } + + entry, exists := cli.LookupParamAlias(test.command) + target, active := entry.ResolveAlias(test.emitted) + if !exists || !active || target != test.canonical { + t.Fatalf("reviewed AITable alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical) + } + + unconfirmedCaller := ¶mAliasCaptureCaller{} + ctx, unconfirmedErr := executeParamAliasPayloadE2E(t, unconfirmedCaller, unconfirmedArgs...) + if ctx == nil { + t.Fatal("unconfirmed AITable alias command skipped PreParse") + } + var appErr *apperrors.Error + if !errors.As(unconfirmedErr, &appErr) || appErr.Reason != "confirmation_required" { + t.Fatalf("unconfirmed AITable alias command error = %#v, want confirmation_required\nargs=%v", unconfirmedErr, unconfirmedArgs) + } + if len(unconfirmedCaller.calls) != 0 { + t.Fatalf("unconfirmed AITable alias crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, unconfirmedCaller.calls) + } + + canonicalCaller := ¶mAliasCaptureCaller{} + _, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...) + if canonicalErr != nil { + t.Fatalf("confirmed canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls) + } + if len(canonicalCaller.calls) == 0 { + t.Fatalf("confirmed canonical command reached no final transport payload: args=%v", canonicalArgs) + } + + aliasCaller := ¶mAliasCaptureCaller{} + aliasCtx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...) + if aliasErr != nil { + t.Fatalf("confirmed alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls) + } + if aliasCtx == nil { + t.Fatal("confirmed AITable alias command skipped PreParse") + } + if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) { + t.Fatalf("confirmed final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls) + } + }) + } + + for command := range paramAliasAITableDeleteDisableCompleteCommands { + if !coveredCommands[command] { + t.Errorf("AITable delete/disable safety template %q has no reviewed alias case", command) + } + } + if len(coveredCommands) != len(paramAliasAITableDeleteDisableCompleteCommands) { + t.Fatalf("AITable delete/disable safety coverage = %d commands, want %d", len(coveredCommands), len(paramAliasAITableDeleteDisableCompleteCommands)) + } + + activeAliases := 0 + for command := range paramAliasAITableDeleteDisableCompleteCommands { + entry, exists := cli.LookupParamAlias(command) + if !exists { + t.Errorf("AITable delete/disable safety command %q has no generated alias entry", command) + continue + } + for emitted, canonical := range entry.Aliases { + activeAliases++ + caseKey := paramAliasPayloadCaseKey(command, emitted) + reviewedCanonical, reviewed := reviewedAliases[caseKey] + if !reviewed { + t.Errorf("active AITable delete/disable alias %q --%s -> --%s has no confirmation/payload case", command, emitted, canonical) + continue + } + if reviewedCanonical != canonical { + t.Errorf("reviewed AITable delete/disable alias %q --%s target = --%s, generated --%s", command, emitted, reviewedCanonical, canonical) + } + } + } + if activeAliases != len(reviewedAliases) { + t.Fatalf("AITable delete/disable generated alias coverage = %d, want %d reviewed cases", activeAliases, len(reviewedAliases)) + } +} + func TestCrossPlatformCoverageNewParamAliasesCannotBypassConfirmation(t *testing.T) { for _, test := range paramAliasNewConfirmationCases { test := test From edbb175d4e72883a22409c34098a44389ec15388 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 09:49:00 +0800 Subject: [PATCH 199/250] docs(skills): optimize drive and wiki routes --- skills/multi/dingtalk-drive/SKILL.md | 154 +-- .../multi/dingtalk-drive/references/drive.md | 1073 +---------------- .../dingtalk-drive/references/folder-sync.md | 40 + .../dingtalk-drive/references/intent-guide.md | 33 +- .../dingtalk-drive/references/lite-recipes.md | 53 +- skills/multi/dingtalk-wiki/SKILL.md | 130 +- .../dingtalk-wiki/references/wiki-members.md | 24 + .../dingtalk-wiki/references/wiki-node-ops.md | 45 + skills/multi/dingtalk-wiki/references/wiki.md | 540 +-------- 9 files changed, 411 insertions(+), 1681 deletions(-) create mode 100644 skills/multi/dingtalk-drive/references/folder-sync.md create mode 100644 skills/multi/dingtalk-wiki/references/wiki-members.md create mode 100644 skills/multi/dingtalk-wiki/references/wiki-node-ops.md diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index d08e94b5..609d89cc 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-drive -description: 钉钉文件管理（存储层，覆盖钉盘与文档空间两个存储域）。Use when 用户说 钉盘/上传文件/下载文件/文件夹/查文件/找文件/全局搜索文件/最近编辑的文档/复制/移动/重命名/删除/回收站/还原删除文件/文件权限管理/普通文件下载/本地与钉盘文件夹差异比较/整个文件夹拉到本地/整个文件夹推到钉盘/双向同步。对钉钉文档仅处理其作为文件的管理操作，文档本体及其内容操作归 dingtalk-doc；知识库空间与空间内节点组织归 dingtalk-wiki。命令前缀：dws drive。 +description: 钉钉文件管理（存储层，覆盖钉盘与文档空间）。Use when 用户说 钉盘/文档空间/我的文档中的普通文件或文件夹、查找/上传/下载/复制/移动/重命名/删除/回收站/权限/元信息，或本地与钉盘文件夹比较、拉取、推送、双向同步；也承接在线文档节点的存储管理。文档正文编辑与导出走 dingtalk-doc；明确的知识库空间及空间内节点组织走 dingtalk-wiki。命令前缀：dws drive。 metadata: cli_version: ">=0.2.14" category: product @@ -9,13 +9,21 @@ metadata: - dws --- -# 钉盘 Skill +# 钉盘 -## 前置条件 — 执行操作前必读 + +## 最小 DWS 执行契约 -> **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。 - -> 命令参考：[drive.md](references/drive.md)。 +- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。 +- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。 +- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。 +- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。 +- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。 +- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。 +- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。 +- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。 +- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。 + ## Shortcut 发现（按需） @@ -25,88 +33,88 @@ metadata: 仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service drive --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。 -## 意图表 +## Golden Route -| 用户说 | 命令 | -|--------|------| -| "看钉盘文件 / 文件夹列表" | `dws drive +list [--folder ]` | -| "钉盘目录树" | `python scripts/drive_tree_list.py --depth 2` | -| "查文件元数据/统计/公开状态/封面" | `dws drive +inspect --node [--include-stats/--include-publish/--include-cover]` | -| "搜文件 / 找文件" | `dws drive +search --query "<关键词>"` | -| "下载文件" | `dws drive +download --node --output <工作目录内相对路径>` | -| "上传文件" | `dws drive +upload --file <工作目录内相对路径> [--folder ]` | -| "建钉盘文件夹 / 建快捷方式" | `dws drive +create-folder ...` / `dws drive +create-shortcut ...` | -| "复制/移动/重命名/删除" | `dws drive +copy/+move/+rename/+delete ...` | -| "回收站 / 还原删除的文件" | `dws drive +recycle-list` / `dws drive +recycle-restore --id ` | -| "收藏 / 取消收藏 / 收藏列表" | `dws drive +star-add/+star-remove/+star-list ...` | -| "查/关互联网公开" | `dws drive +publish-get/+publish-unset ...`；开启公开当前无已验证 eligible 节点，不推荐 Agent 调用 | -| "普通文件历史版本" | `dws drive +version-history/+version-get/+version-download/+version-revert ...` | -| "在线文档评论/导入导出/权限" | 切到 `dws doc +comment-* / +import / +export / +access-*` | +| 用户意图 | 唯一推荐入口 | 关键边界 | +|---|---|---| +| 全局按名称或关键词找文件 | `dws drive +search --query <关键词>` | 多候选停止；在线文档正文搜索走 `doc +search` | +| 浏览根目录或已知文件夹 | `dws drive +list [--folder ]` | 默认一页，处理 nextCursor | +| 查看最近访问/编辑 | `dws drive +recent [--operate-type 1] --limit ` | 1=最近编辑；默认最近访问 | +| 查看节点类型和元数据 | `dws drive +inspect --node ` | 按需加 stats/publish/cover，不为普通列表强制调用 | +| 下载普通文件 | `dws drive +download --node --output <相对路径>` | 当前 shortcut 接受 ID；在线文档用 `doc +export` | +| 上传新文件或覆盖普通文件 | `dws drive +upload --file <相对路径>` | 新建可加 folder；覆盖改加 node，二者互斥 | +| 创建文件夹 | `dws drive +create-folder --name <名称> [--folder ]` | Shortcut 已提交并读回 | +| 复制在线文档节点 | `dws drive +copy --node [--folder <目标ID>]` | 普通钉盘文件会被拒绝；Base 结构复制走 AITable `+base-copy --base-id --target-folder-id <真实ID> --only-struct` | +| 移动节点 | `dws drive +move --node --folder <目标ID>` | 破坏性变更，按 Runtime confirmation | +| 重命名节点 | `dws drive +rename --node --name <新名称>` | 写后检查最终名称 | +| 比较本地与钉盘文件夹 | `dws drive status --local-folder <绝对路径> --remote-folder ` | 只读；默认精确 MD5，不先拉取或推送 | +| 钉盘文件夹拉到本地 | `dws drive pull --local-folder <绝对路径> --remote-folder --if-exists smart` | 先以相同参数 `--dry-run`，再按确认执行 | +| 本地文件夹推到钉盘 | `dws drive push --local-folder <绝对路径> --remote-folder --if-exists smart` | 先 dry-run；不会删除远端多余文件 | +| 双向补齐文件夹 | `dws drive sync --local-folder <绝对路径> --remote-folder --on-conflict skip` | 先 dry-run；冲突策略必须显式保留 | -## 标准 SOP（必遵流程） +### 低频入口 -> 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 dentryUuid/nodeId。每条命令必须带 `--format json`。破坏性操作（删除/移动/覆盖/公开）**必须**先与用户确认。 +- 删除/恢复：`+delete/+recycle-list/+recycle-restore`；版本：`+version-history/+version-get/+version-download/+version-revert`。 +- 收藏：`+star-*`；公开状态：`+publish-get/+publish-unset`（`+publish-set` 不进入 Agent 路由）；统计/封面用 `+inspect`；快捷方式用 `+create-shortcut`。 +- 目录树只用有界 `+list` 逐层遍历。 -### SOP-1 找文件（find-file） +兼容别名不选路：`+info`→`+inspect`，`+find-file`→`+search`，`+search-docs`→`doc +search`。 -**触发**：找文件/搜文件/我的文件/最近文件/最近编辑的文档/某文档在哪。 +## 当前最短路径 -1. **选源（必须）**：最近访问 → `dws drive +recent --limit --format json`（翻页用上次返回的 `nextCursor` 传 `--cursor`）；最近编辑 → `dws drive +recent --operate-type 1 --limit --format json`（不传 `--operate-type` 默认为 0 最近访问，会混入仅打开过的文档）；按内容/名称全局搜 → `dws drive +search --query "<关键词>" --format json`；浏览某目录 → `dws drive +list --folder --format json`。 -2. **解析（必须）**：取真实 `dentryUuid`（= `id`/`nodeId`）；多候选让用户确认，**禁止**默认取第一个。 -3. **下钻（必须）**：根目录没命中时，进入最相关文件夹继续 `drive +list --folder`，必要时 `python scripts/drive_tree_list.py --depth 2` 递归，**禁止**只看根目录就放弃。 -4. **回读元数据（必须）**：命中后 `dws drive +inspect --node --format json`，按 `extension` 确认类型。 +- 已知 dentryUuid：直接执行 inspect/download/list/move/rename，禁止先 search；仅确认是受支持的在线文档节点后才执行 copy。 +- 只有名称：`+search` → 唯一候选的 nodeId → 目标命令；不得自动选择第一项。 +- 只有文件夹层级：从最近的已知 folder ID 开始 `+list`，不要从根目录无界递归。 +- 上传新文件：单条 `+upload`；不要退回 upload-info + 手写 HTTP + commit。 +- copy/move/rename/create-folder 已内置写后读取时，不再由 Agent重复执行 `+inspect`。 +- 文件夹方向已明确时直接 `status/pull/push/sync`，不先 status；写操作先用完全相同参数 dry-run，再正式执行。 +- 搜索结果 `type=able` 后按业务动词重路由：结构复制/删除/Base 内操作走 AITable。结构复制按当前 leaf 提供源 Base ID 和真实 `--target-folder-id`；缺少目标 ID 时停止，不猜根 ID或发明 `--target-root`。 +- `+inspect/+download/+list` 只保证 dentryUuid；只有 URL 时先用 `dws drive info --node --format json` 解析并核对 nodeId。 -**禁止**：编造 dentryUuid、只看根目录放弃、用 `drive +list` 替代 `drive +search` 做全局查找。 +最短路径不省略类型检查、确认、传输验证或写后校验。 -### SOP-2 上传 / 下载（upload-download） +## 关键结果语义 -**触发**：上传文件/下载文件/传到钉盘/用本地文件覆盖已有文件。 +- `+list/+search/+recent` 检查集合、hasMore 和 nextCursor；缺少集合不能当空结果，多候选禁止默认第一项。 +- `+download` 验证相对路径存在且 sizeBytes > 0；`+upload` 检查最终 nodeId、名称、类型和大小。 +- copy/move/rename/create-folder 检查 `ok/outcome` 和读回；`partial_success` 不是完成。 +- status 检查分类集合；pull/push/sync 检查 summary 和逐项结果，failed/unknown 必须保留。 +- 分页未结束时返回 continuation；目录树或大列表必须有最大深度、页数和条目数。 +- 未知写入效果先 inspect/list 回读，不盲目重放写操作。 -1. **上传（必须）**：先把文件暂存到工作目录，再执行 `dws drive +upload --file <相对路径> [--folder ] --format json`；shortcut 内部已提交并回读远端元数据，返回取 `data.nodeId`。 -2. **覆盖（必须）**：先 `dws drive +inspect --node --format json`，记录真实 `extension` 和原 `name`。`extension=md` 切 `dingtalk-misc` 的 `references/markdown.md`；其他普通文件在用户确认后执行 `dws drive +upload --node --file <相对路径> --file-name "<原name>" --format json`。`adoc` / `axls` / `able` 切对应内容 skill/reference，不按普通文件覆盖。 -3. **下载（必须）**：先 `dws drive +inspect --node --format json` 判断类型——`extension=adoc` 切 `dingtalk-doc` 用 `doc +export`；普通文件执行 `dws drive +download --node --output <工作目录内相对路径> --format json`，并校验 `data.sizeBytes > 0` 和本地文件真实存在。 +## 参数与安全边界 -**禁止**：对在线文档用 `drive +download`（会失败）、普通文件覆盖时省略 `--file-name` 导致隐式重命名、只看退出码而不检查统一结果。 +- `--node`、`--folder` 使用 dentryUuid/fileId，不使用数字型 dentryId；回收站 restore 使用 recycleItemId。 +- `+list --limit` 最大 50，`+search --limit` 最大 30；超过时分页，不以非法参数反复试错。 +- 写操作只按精确 leaf Runtime 判定确认；已明确授权具体对象、动作与影响时，首次正式执行直接带 `--yes`，否则先确认。预览不带，参数变化重新确认；禁止用缺少 `--yes` 的失败探测。 +- 普通文件覆盖前确认真实类型和原名称；adoc/axls/able 不按普通文件覆盖。 +- 单文件 Shortcut 的本地输入输出使用 cwd 相对路径且禁止 `..`；文件夹 `status/pull/push/sync` 按 leaf 契约使用绝对 `--local-folder`。 +- 文件夹同步默认精确 MD5；仅在用户接受时间戳近似时用 `--quick`，且不会删除任一侧多余文件。 +- 参数不确定时只查一次精确 leaf Schema；禁止产品级 Schema。 -### SOP-3 文件夹 / 复制 / 移动 / 重命名（folder-ops） +## 按需加载 -**触发**：建文件夹/复制/移动/重命名。 +Golden Route 参数足够时禁止读取 reference。其余最多读取一个精确 reference： -1. **执行（必须）**：建钉盘文件夹 `dws drive +create-folder --name "<名称>" [--folder ]`；复制 `drive +copy --node --folder <目标>`；移动 `drive +move --node --folder <目标>`；重命名 `drive +rename --node --name "<新名>"`。全部加 `--format json`。 -2. **验证（必须）**：这些 shortcut 内部已经读回；调用方仍须检查 `ok=true`、`outcome=success` 和 `data` 中的 nodeId/对象，不能只看进程退出码。 +| 触发条件 | Reference | +|---|---| +| URL、文件类型或跨产品边界 | [intent-guide](references/intent-guide.md) | +| 文件夹比较、拉取、推送或双向同步 | [folder-sync](references/folder-sync.md) | +| 低频权限、版本、回收站、公开状态 | [drive reference](references/drive.md) 的对应章节 | +| 文档查询、导入和模板保形流程 | [lite-recipes](references/lite-recipes.md) | -**禁止**：未确认就移动/覆盖他人文件、跳过回读。 +## 错误最短路径 -### SOP-4 回收站（recycle） +1. 零/多候选、类型不明或分页不完整：停止写入，返回候选或 continuation。 +2. `unknown flag`：只查一次当前 leaf Help；`unknown command`：只查一次 Drive shortcut 清单。 +3. 普通下载遇到在线文档类型：切 `doc +export`，不重复尝试 Drive download。 +4. 传输中断：保留本地临时状态或 checkpoint；先判断能否续传。 +5. 写入效果未知：按 nodeId 回读；无法证明时报告 unknown。 +6. 普通文件 `+copy` 被拒绝时不要重试或伪装成功；独立副本改走经用户授权的 download→upload。AITable 结构复制缺少或无法验证目标文件夹时停止，不猜 ID或创建测试文件夹。 -**触发**：删文件/回收站/还原。 +## 跨产品边界 -1. **删除（必须）**：`dws drive +delete --node --format json`（**必须**先与用户确认，再由执行层添加 `--yes`）。 -2. **还原（必须）**：`dws drive +recycle-list --format json` 按 `originalName/originalPath` 确认目标并取 `recycleItemId` → 用户确认后执行 `dws drive +recycle-restore --id --format json`；成功时 Shortcut 会用服务返回的 nodeId 读回。 - -**禁止**：未确认就删除、把 `dentryUuid` 当 `recycleItemId` 传给 restore。 - -### SOP-5 互联网公开（publish） - -**触发**：互联网公开/取消公开/查公开状态。 - -1. **执行（必须）**：查状态 `dws drive +publish-get --node --format json`；用户确认后关闭公开 `dws drive +publish-unset --node --format json`。`+publish-set` 在普通文件和在线文档真实夹具上均返回 `operation.notSupported`，当前不进入 Agent 公开入口；只有未来先找到服务端明确支持的 eligible 节点并通过真实 set→get→unset 闭环后才能启用。 -2. **边界（必须）**：对外公开前**必须**与用户确认边界与后果。 - -**禁止**：未确认就改变公开状态；把 `operation.notSupported` 当成功；在没有 eligible 节点真实闭环的情况下启用 `+publish-set`。 - -## 高频硬约束 - -- 查找文件不要只看根目录后放弃；根目录没命中时，进入最相关的目标文件夹继续 `drive +list --folder `，必要时用目录树脚本递归到合理深度。 -- `drive +list` 默认 `--limit 20`，自动化场景里保守使用 `--limit 50` 以内并处理 `nextCursor` 翻页；不要因为参数边界报错反复重试。 -- 全局找文件优先 `drive +search --query`；指定目录浏览用 `drive +list`，命中后必须 `drive +inspect --node --format json` 回读元数据。 -- 删除、覆盖、移动等破坏性操作必须确认；上传、创建文件夹、下载后要读回或列目录验证。 -- 所有 `dws drive` 命令加 `--format json`。 - -## 跨产品协作 - -- 文件内容编辑（钉钉文档）→ 切到 `dingtalk-doc` -- 知识库空间 → 切到 `dingtalk-wiki` -## 局部意图与短流程 - -- [局部意图消歧](references/intent-guide.md)；[短流程](references/lite-recipes.md)。 +- 普通文件/文件夹及在线文档节点的存储管理 → Drive；正文/内容分别走 Doc、Sheet、AITable。 +- able 外层移动/重命名走 Drive；结构复制、Base 删除（`+base-delete`）及 Base 内操作走 AITable。 +- 明确知识库 workspace 层级 → Wiki；泛称“文档空间/我的文档”仍走 Drive。 +- Word/Markdown/Text 转在线文档用 `doc +import`；Drive upload 只保留原文件。 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 5da0ba4a..ca7d1d6c 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -1,1038 +1,91 @@ -# 钉盘 (drive) 命令参考 +# Drive 低频能力参考 -## 查询命令帮助 +仅在根 Skill 的 Golden Route 不足时读取本文件的一个相关章节。高频搜索、列表、检查、单文件传输和文件夹同步直接按根 Skill 执行。 -当你不确定某个命令的具体参数、格式或可选项时，**优先执行 `--help` 查询**，不要猜测参数名或凭记忆编造。 +## 身份与目标位置 + +- `--node`、`--folder`、`--remote-folder` 使用 dentryUuid/fileId；数字 dentryId 不能替代。 +- 回收站恢复使用 `recycleItemId`，不能复用删除前的 nodeId。 +- URL 类型不明时只执行一次 `dws drive info --node --format json`，按真实 nodeId/nodeType 分流。 +- 普通文件夹目标使用 `--folder`；明确知识库 workspace 才使用 `--workspace`。零命中、多候选或类型不明时停止。 + +## Runtime 确认与首次执行 + +- 先解析唯一目标，再以精确 leaf Schema 和 Runtime gate 判断是否需要确认；不要通过一次缺少 `--yes` 的失败调用探测确认要求。 +- Runtime 要求确认且当前请求已明确授权具体节点/文件夹、动作与影响时，首次正式远端写调用直接追加 `--yes`。诸如“整理一下”“处理这些文件”不能视为对删除、覆盖、移动或公开状态变更的精确授权。 +- Runtime 不要求确认时不添加 `--yes`。对象、范围或影响不完整时先询问；确认后必须保持同一 profile、目标、动作、范围和关键参数，任一项变化都要重新确认。 +- `--dry-run`、差异预览和只读检查不加 `--yes`；预览结果符合授权范围后，正式执行才追加。收到 `confirmation_required` 仅表示尚未通过预执行门禁，不代表业务写入成功，也不能据此盲目重放。 + +## 高级目录列表 + +普通浏览优先 `+list`。需要递归、名称模式、节点类型或修改时间过滤时使用 managed leaf： ```bash -# 查看 drive 下所有子命令 -dws drive --help - -# 查看具体命令的完整参数说明 -dws drive list --help -dws drive search --help -dws drive upload --help -dws drive download --help +dws drive list --folder --depth 2 --pattern "*周报*" --format json +dws drive list --folder --type file --start 7d --format json ``` -规则： -- 参数名不确定时 → 先 `--help`，再调用 -- 报错 "unknown flag" 时 → `--help` 确认正确的 flag 名称 -- 不确定某个功能是否存在时 → `dws drive --help` 查看命令列表 +- `--depth` 最大 5；递归总量上限以结果中的 `truncated/errors` 为准。 +- `--type file|folder` 是节点类型；`search --file-types` 是内容类型，二者不同。 +- `--start/--end` 接受 `24h/7d/2w`、日期或 RFC3339，按修改时间过滤。 +- 过滤模式是客户端有界扫描；`truncated=true` 不能声称全量。需要关键词检索时改用 `+search`。 +- `--latest` 遇到截断或目录读取失败会拒绝给出不完整 Top-N，按错误中的目录和恢复命令缩小范围。 -## 命令总览 - -### 获取文件/文件夹列表 - -``` -Usage: - dws drive list [flags] -Example: - dws drive list --limit 20 - dws drive list --limit 20 --folder --order-by name --order asc - dws drive list --folder --type file --start 7d -Flags: - --limit int 每页返回数量，默认 20，最大 50 (可选) - --cursor string 分页游标，首次不传 (可选) - --order string 排序方向: asc|desc，默认 desc (可选) - --order-by string 排序字段: createTime|modifyTime|name (可选) - --folder string 父节点 ID (dentryUuid)，不传则列出空间根目录 (可选) - --space-id string 空间 ID，不传则使用「我的文件」对应 spaceId (可选) - --workspace string 文档空间/知识库 ID (加密 string 或 URL)，传入则路由到文档空间 (可选) - --thumbnail 是否返回缩略图信息 (可选) - --pattern string 按名称通配过滤结果，如 "*日报*"（客户端过滤，无通配符时按子串匹配）(可选) - --depth int 递归列出子目录层级，默认 1(仅当前层)，最大 5；与 --cursor/--limit 互斥 (可选) - --type string 按节点类型过滤: file|folder（客户端过滤，见下节）(可选) - --start string 按修改时间过滤·起始，如 7d / 2026-08-01 / RFC3339 (可选) - --end string 按修改时间过滤·截止，语法同 --start (可选) -``` - -类型/时间过滤（`--type` / `--start` / `--end`）： -- 语义：`--type` 按节点类型（file=文件 / folder=文件夹）；`--start`/`--end` 按**修改时间**圈定区间。 - 注意与 `dws drive search` 的 `--modified-from/--modified-to` 区分：那两个收毫秒时间戳，这里收字符串语法； - `--type`（节点类型）与 search 的 `--file-types`（内容类型 alidoc/image/...）也不是一回事。 -- 时间语法：相对时间 `24h`/`7d`/`2w`（小时/天/周，按本机时钟换算）、RFC3339（`2026-08-01T00:00:00+08:00`）、 - 无时区 ISO8601（`2026-08-01 08:00:00`，默认 Asia/Shanghai）、仅日期（`2026-08-01`）； - 不支持毫秒时间戳，不支持 `m` 单位。 -- 执行方式：钉盘与知识库（--workspace）两路由统一为**客户端过滤**——全量扫描当前目录后在进程内筛选； - 与 `--depth>1` 组合时递归扫描后筛（被滤掉的条目仍占 2000 条全局上限）。 -- 互斥：与 `--versions`/`--cursor`/`--order-by`/`--order`/`--limit` 不能同时使用（过滤模式为全量扫描， - 无游标与服务端排序语义）；可与 `--latest`/`--pattern`/`--depth` 组合，`--latest` 表示「符合条件的条目中最新 N 个」。 -- 输出形态：带过滤时输出从单页透传变为聚合形态 `{items, maxDepth, truncated, errors}`。 -- 已知代价：大目录（>2000 条）触顶截断时 `truncated=true`（退出码 0，结果每条都正确但没扫完）； - 建议用 `--folder` 指定子目录缩小扫描范围；带关键词的过滤场景改用 `dws drive search`。 -- 与 `--latest` 组合时上一条不适用：排序基不完整的 Top-N 不是全局最新，故触顶截断**或**递归途中 - 目录读取失败都拒绝产出并报错（`LATEST_SCAN_TRUNCATED` / `LATEST_SCAN_INCOMPLETE`），不会以 - 退出码 0 交出结果；错误消息里带首个失败目录的 folder/depth/reason，以及一条复现原候选集 - （查询域 + `--folder` + `--pattern`/`--type`/`--start`/`--end`）的恢复命令。Windows 构建下， - 若原值含 shell 元字符则命令里只给占位符、原值另起一行以数据形式列出（cmd.exe 与 PowerShell - 没有共同安全的引用形式），照抄时需手动替换。 - -### 获取钉盘空间列表 - -``` -Usage: - dws drive list-spaces [flags] -Example: - dws drive list-spaces - dws drive list-spaces --space-type mySpace - dws drive list-spaces --space-type orgSpace --limit 20 --cursor -Flags: - --space-type string 空间类型: orgSpace=企业空间(默认), mySpace=我的文件 (可选) - --limit int 每页返回数量 (默认 20，最大 50)，仅 spaceType 为 orgSpace 时有效 - --cursor string 分页游标，仅企业空间支持分页 (可选) -``` - -spaceType 筛选规则： -- `orgSpace`（默认/不传）：返回企业空间列表，支持 `nextToken` 分页 -- `mySpace`：返回用户的"我的文件"个人空间（单个，不支持分页） - -返回字段说明： -- `spaceId` — 空间 ID，用于 `list`/`info`/`upload` 等命令的 `--space-id` -- `spaceName` — 空间名称（如"全员文件夹"、"我的文件"） -- `rootFolderId` — 空间根目录的 dentryUuid，可作为 `doc copy/move` 的 `--folder` 参数 -- `spaceType` — 空间类型（如 `orgSpace`） -- `nextToken` — 若不为空，表示还有更多空间可查询（仅企业空间） - -### 搜索文件/文件夹/空间 - -按关键词搜索文件、文件夹或团队空间。不同于 `list`（需要明确的 spaceId/parentId 逐层遍历），`search` 用于不知道具体位置、只记得名称/关键词的场景。 - -``` -Usage: - dws drive search [flags] -Example: - dws drive search --query "季度汇报" - dws drive search --query "合同" --target file --extensions pdf,docx - dws drive search --query "项目" --target space - dws drive search --query "方案" --created-from 1700000000000 --created-to 1710000000000 - dws drive search --query "周报" --creator-uids 012345 - dws drive search --query "报告" --limit 30 --cursor -Flags: - --query string 搜索关键词 (必填) - --target string 搜索目标: all(默认) | file | space (可选) - --file-types strings 按文件内容类型过滤，逗号分隔: alidoc,document,image,video,audio,archive (仅 target=file/all 生效) - --extensions strings 按文件扩展名过滤，不含点号，逗号分隔 (如 pdf,docx,adoc) - --creator-uids strings 按创建者用户 ID 过滤，逗号分隔 - --created-from int 创建时间起始 (毫秒时间戳，含) - --created-to int 创建时间截止 (毫秒时间戳，含) - --modified-from int 修改时间起始 (毫秒时间戳，含) - --modified-to int 修改时间截止 (毫秒时间戳，含) - --limit int 每页返回数量（默认 10，最大 30） - --cursor string 分页游标，从上次返回的 nextCursor 获取 (可选) -``` - -搜索目标 (`--target`) 选择规则： -- `all`（默认）：同时搜文件与空间，返回混合结果 — 不确定目标是文件还是空间时使用 -- `file`：只搜文件 / 文件夹，支持 `--file-types` / `--extensions` 过滤 — 明确是找文件时使用 -- `space`：只搜团队空间 — 明确知道空间名、需快速定位空间 spaceId/rootFolderId 时使用 - -返回结果中 `type` 字段区分：`SPACE`（空间）、`FILE`（普通文件）、`FOLDER`（文件夹）、`ALIDOC`（钉钉在线文档）。 - -> **提示**：结果按相关性排序，首页未命中时优先调整关键词 / 补充 `--file-types`/`--extensions` 缩小范围 / 加上时间范围，而非反复翻页。 - -### 获取最近访问/编辑的文档列表 - -``` -Usage: - dws drive recent [flags] -Example: - dws drive recent - dws drive recent --operate-type 1 - dws drive recent --creator-type 1 --limit 10 - dws drive recent --file-types 0,1 --operate-type 0 -Flags: - --file-types ints 按文档类型过滤，逗号分隔 (参考 RecentAccessType 枚举) (可选) - --operate-type ints 按操作类型过滤: 0=最近访问(默认), 1=最近编辑; 不传默认仅返回最近访问(0) (可选) - --creator-type int 按创建人过滤: 0=全部(默认), 1=我创建, 2=他人创建 (可选) - --org-ids ints 按资源所属组织 ID 过滤，逗号分隔 (可选) - --limit int 每页数量 (默认 20，最大 20) (可选) - --cursor string 分页游标，从上次返回的 nextCursor 获取 (可选) -``` - -返回字段说明： -- `recentItems[]` — 最近访问/编辑的文档列表 - - `nodeId` — 文档节点 ID，可用于 `doc read/info/update` 的 `--node` - - `name` — 文档名称 - - `contentType` — 内容类型（如 ALIDOC） - - `extension` — 扩展名（如 adoc、axls、able） - - `docUrl` — 文档在线访问 URL - - `operateType` — 操作类型：LAUNCH=访问，EDIT=编辑 - - `accessTime` — 最近访问时间 - - `createTime` / `updateTime` — 创建/更新时间 -- `nextCursor` — 翻页游标，传入 `--cursor` 获取下一页 -- `hasMore` — 是否还有更多数据 - -### 获取文件元数据信息 - -``` -Usage: - dws drive info [flags] -Example: - dws drive info --node -Flags: - --node string 节点 ID (dentryUuid) (必填) - --space-id string 节点所属空间 ID (可选) -``` - -### 文件内容获取路由规则 - -> 当用户请求"分析/查看/读取某个文件内容"时，**必须先调用 `dws drive info` 获取文件元数据**，再根据返回的 `extension` 字段选择对应链路。 -> 注意：若检测到钉钉文档类型（adoc/axls/amind/adraw），会自动跟进调用 `doc info` 返回更准确的文档信息。 - -| extension | 文件类型 | 操作 | 命令 | -|-----------|---------|------|------| -| adoc | 在线文档 | 在线获取 Markdown 内容 | `dws doc read --node ` | -| axls | 在线表格 | 在线读取表格数据 | `dws sheet list --node ` → `dws sheet range read --node --sheet-id --range ` | -| able | 多维表格 | 在线查询记录 | `dws aitable table list --base-id ` → `dws aitable record query --base-id --table-id ` | -| md | Markdown 文件 | 读内容 / 创建 / 覆盖 / 局部替换 | `dws markdown fetch` / `dws markdown create` / `dws markdown overwrite` / `dws markdown patch` | -| 其他（pdf/docx/txt/png 等） | 普通文件 | **不支持在线分析**，需用户主动下载后本地查看 | `dws drive download` | - -### 下载文件到本地 - -下载流程一步到位：获取下载 URL → HTTP GET 下载文件二进制内容到本地。 - -``` -Usage: - dws drive download [flags] -Example: - dws drive download --node --output ./report.pdf - dws drive download --node --output ~/downloads/ - dws drive download --node --output ./big.zip --part-size 32MB --parallel 8 -Flags: - --node string 文件 ID (dentryUuid) (必填) - --output string 本地保存路径 (文件路径或目录，不传则保存到当前目录)；如果指定目录，文件名从下载 URL 中自动推断 (可选) - --space-id string 文件所属空间 ID (可选) - --part-size string 分片下载的分片大小，支持 KB/MB/GB 单位，范围 1MB-1GB (默认 16MB) - --parallel int 分片下载并发数，范围 1-8 (默认 4) - --no-resume 关闭断点续传，忽略历史下载进度从头下载 (默认开启续传) -``` - -> **提示**：`--output` 为可选参数，不传则保存到当前目录，文件名从下载 URL 中自动推断。 - -> **大文件分片下载**： -> - 大文件自动分片并发下载，小文件整流下载，行为对用户透明，无需任何额外操作。 -> - 断点续传默认开启：下载中断后重跑同一命令会自动跳过已完成部分继续下载（`<目标文件>.dwspart` 为临时进度文件，下载完成后自动清理）；不需要续传时加 `--no-resume`。 -> - 下载凭证过期会自动刷新并继续下载，已完成的部分不会重下；单个分片失败会自动重试，无需手动处理。 - -### 创建文件夹 - -``` -Usage: - dws drive mkdir [flags] -Example: - dws drive mkdir --name "项目资料" - dws drive mkdir --name "子目录" --folder -Flags: - --name string 文件夹名称，最长 50 字符 (必填) - --folder string 父节点 ID (dentryUuid)，不传则在空间根目录下创建 (可选) - --space-id string 目标空间 ID，不传则使用「我的文件」 (可选) -``` - -### 上传本地文件到钉盘 - -> **注意：** 上传文件必须使用 `dws drive upload` 命令，禁止使用 `upload-info` + `curl` + `commit` 三步流程。 - -``` -Usage: - dws drive upload [flags] -Example: - dws drive upload --file ./report.pdf - dws drive upload --file ./slides.pptx --file-name "Q1汇报.pptx" - dws drive upload --file ./data.xlsx --folder - dws drive upload --file ./updated.pdf --node --file-name "<原文件名.pdf>" -Flags: - --file string 本地文件路径 (必填) - --file-name string 文件显示名称 (默认使用文件名) - --space-id string 目标空间 ID，不传则使用「我的文件」 (可选) - --mime-type string 文件 MIME 类型，不传则自动推断 (可选) - --folder string 父节点 ID (dentryUuid)，不传则上传到空间根目录 (可选，与 --node 互斥) - --node string 覆盖目标文件 ID，传入即覆盖已有文件（透明模式：钉盘路径映射 overwriteFileId，知识库路径映射 overwriteNodeId）(可选，与 --folder 互斥) -``` - -`upload` 命令内部自动完成三步流程（获取凭证 → OSS PUT → 提交入库），无需手动分步操作。 - -> **覆盖保名规则（实测）**：使用 `--node` 覆盖普通文件前，先执行 -> `dws drive info --node --format json` 记录原 `name`，再把该值原样传给 -> `--file-name`。省略 `--file-name` 会采用本地文件名，并同时重命名远端目标。 -> `extension=md` 不走本命令，切到 `dws markdown overwrite` 保留 Markdown diff -> 预览；`adoc` / `axls` / `able` 切对应内容产品。 - -### 删除文件/文件夹到回收站 - -> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。 - -``` -Usage: - dws drive delete [flags] -Example: - dws drive delete --node --format json # 查询 fileId: dws drive list -Flags: - --node string 文件/文件夹 ID (dentryUuid)，即 drive list 返回的 fileId (必填) -``` - -注意：`--node` 使用的是 `drive list` 返回结果中的 `fileId` 字段（即 `dentryUuid`），**不是** `dentryId` 字段。 - -### 查看回收站文件列表 - -``` -Usage: - dws drive recycle list [flags] -Example: - dws drive recycle list - dws drive recycle list --space-id 12345 --limit 10 -Flags: - --space-id string 钉盘空间 ID (选填，不传则返回所有空间) - --limit int 返回条数上限 (默认 20，最大 50) - --cursor string 分页游标 (选填) -``` - -### 还原回收站文件 - -``` -Usage: - dws drive recycle restore [flags] -Example: - dws drive recycle restore --id -Flags: - --id string 回收项 ID (必填，从 recycle list 获取) -``` - -> **注意**：还原操作可能是异步的（返回 `async=true` 和 `taskId`）。 - -### 收藏文档 - -``` -Usage: - dws drive star add [flags] -Example: - dws drive star add --node -Flags: - --node string 文档 ID 或 URL (必填) -``` - -### 取消收藏文档 - -``` -Usage: - dws drive star remove [flags] -Example: - dws drive star remove --node -Flags: - --node string 文档 ID 或 URL (必填) -``` - -### 获取收藏列表 - -``` -Usage: - dws drive star list [flags] -Example: - dws drive star list - dws drive star list --content-types doc,sheet - dws drive star list --resource-types DENTRY --limit 10 - dws drive star list --order-by createTime --sort desc --cursor -Flags: - --limit int 每页条数 (默认 20，最大 20) - --cursor string 分页游标，从上次返回的 nextCursor 获取 - --order-by string 排序字段: createTime (可选) - --sort string 排序方向: asc|desc (可选，默认 desc) - --resource-types strings 资源大类筛选，逗号分隔: DENTRY, TEAM, WORKSPACE - --content-types strings 内容类型筛选，逗号分隔: doc,sheet,ppt,whiteboard,mind,notable,pdf,other,folder -``` - -返回字段说明： -- `starList[]` — 收藏项数组，每项包含： - - `resourceType` — 资源类型: DENTRY / TEAM / WORKSPACE - - `nodeId` — 文档节点 ID（仅 DENTRY） - - `name` — 资源名称 - - `url` — 资源访问链接 - - `contentType` — 内容类型: ALIDOC / DOCUMENT / IMAGE / VIDEO / AUDIO / ARCHIVE / OTHER（仅 DENTRY） - - `extension` — 文件扩展名（仅 DENTRY） - - `dentryType` — 节点类型: file / folder（仅 DENTRY） - - `starTime` — 收藏时间（RFC 3339 格式） - - `id` — 资源唯一标识（仅 TEAM / WORKSPACE） - - `spaceType` — 知识库类型: 1=知识库, 2=我的文档（仅 WORKSPACE） -- `hasMore` — 是否有更多数据 -- `nextCursor` — 下次分页游标 - -### 比较本地文件夹与钉盘文件夹的差异 - -只读命令：比较本地文件夹与钉盘文件夹的差异——本地取 `--local-folder`（**绝对路径**），钉盘取 `--remote-folder`（文件夹 dentryUuid，**必传**）指向的文件夹，按精确 MD5（默认）或快速 modified_time（`--quick`）逐文件比对。两侧各自递归遍历，`rel_path` 相对各自根目录。 - -``` -Usage: - dws drive status [flags] -Example: - dws drive status --local-folder /abs/path/repo --remote-folder - dws drive status --local-folder /abs/path/repo --remote-folder --space-id xxxx - dws drive status --local-folder /abs/path/repo --remote-folder --quick -Flags: - --local-folder string 本地文件夹绝对路径 (必填) - --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) - --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) -``` - -输出五类差异（`rel_path` 始终以 `/` 分隔、相对各自根目录）： - -| 字段 | 含义 | -|------|------| -| `new_local` | 仅本地存在 | -| `new_remote` | 仅钉盘存在 | -| `modified` | 两侧都存在且本次检测判定为已变更（exact 比 MD5，quick 比 modified_time） | -| `unchanged` | 两侧都存在且本次检测判定为未变更 | -| `unknown` | 两侧都存在，但 exact 模式下**远端未返回可靠 MD5**、无法核对内容——既不判 unchanged 也不判 modified，如实归入此类（quick 模式不会产生 unknown） | - -输出 schema： - -```json -{ - "detection": "exact", - "new_local": [{"rel_path": "..."}], - "new_remote": [{"rel_path": "..."}], - "modified": [{"rel_path": "..."}], - "unchanged": [{"rel_path": "..."}], - "unknown": [{"rel_path": "..."}] -} -``` - -注意事项： - -- 默认 `detection=exact`（比较 MD5）；传 `--quick` 后 `detection=quick`（只比较 modified_time，best-effort）。 -- exact 模式**只在能拿到远端 MD5 时才判定 unchanged/modified**；远端缺失 MD5 的文件一律进入 `unknown`，绝不会因大小 / mtime 恰好相同而被误报为 unchanged。当前 `list_files` 通常不返回 MD5，因此这类文件多会落在 `unknown`——请据此决定是否用 `pull`/`push` 强制对齐。 -- 本地 hash 仅在文件双端都存在、远端有 MD5、且非 `--quick` 模式时才按需计算。 -- 远端文件或文件夹名称若无法安全、无歧义地映射到本地路径（如 `..`、路径分隔符、盘符或目标平台保留名），命令会中止整棵远端树并返回失败；不会静默跳过后继续报告不完整结果。 -- 只比对钉盘 `type=file` 的二进制文件；在线文档（docx/sheet/bitable/mindnote/slides）与快捷方式（shortcut）会被跳过。本地只比对常规文件（符号链接、设备文件忽略）。 -- `--local-folder` 必须是绝对路径（相对路径会被直接拒绝）；`--remote-folder` 必传，是钉盘侧待比对文件夹的 dentryUuid（可用 `dws drive list` 查到）。 - -### 把钉盘文件夹拉取（镜像）到本地 - -只写本地命令：把 `--remote-folder` 指向的钉盘文件夹**单向、文件级**镜像到本地 `--local-folder`（Drive → 本地）。递归下载所有 `type=file` 的文件，子目录自动创建。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。** - -``` -Usage: - dws drive pull [flags] -Example: - dws drive pull --local-folder /abs/path/repo --remote-folder - dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive pull --local-folder /abs/path/repo --remote-folder --space-id xxxx -Flags: - --local-folder string 本地文件夹绝对路径 (必填) - --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) - --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 本地文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写本地，执行需确认) -``` - -`--if-exists` 策略： - -| 值 | 行为 | -|----|------| -| `skip`（默认） | 本地已存在则保持不动，只新增 | -| `smart`（推荐增量同步） | 本地 `modified_time` 已 ≥ 远端 `modified_time` 则跳过；时间戳缺失/非法时退回安全路径继续下载 | -| `overwrite` | 总是下载覆盖（Drive 作为权威源） | - -输出 schema： - -```json -{ - "summary": {"downloaded": 0, "skipped": 0, "failed": 0}, - "items": [ - {"rel_path": "sub/a.txt", "action": "downloaded"}, - {"rel_path": "b.txt", "action": "skipped"}, - {"rel_path": "c.bin", "action": "failed", "error": "..."} - ] -} -``` - -注意事项： - -- 只下载钉盘 `type=file` 的二进制文件；在线文档与快捷方式会被跳过。`rel_path` 始终以 `/` 分隔。 -- 下载目标始终被约束在 `--local-folder` 之内：远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时，命令会在下载前中止整棵远端树；拼接后仍逃逸出根目录的路径记为 `failed`、不会落盘。 -- 镜像采用跨平台一致的路径等价规则：远端树中若出现 `A/a`、Unicode NFC/NFD 异写，或等价目录前缀下的不同子树，会在任何下载前整批失败，避免不同文件系统得到不一致结果。 -- 下载成功后本地文件 mtime 会对齐到远端 `modified_time`，便于后续 `--if-exists smart` 增量同步跳过。 -- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，stderr 只保留简短失败说明。脚本/agent 直接看 exit code 即可判断成败。 - -### 把本地文件夹推送（镜像）到钉盘 - -只写远端命令：把本地 `--local-folder` **单向、文件级**镜像到钉盘 `--remote-folder` 文件夹（本地 → Drive）。递归遍历本地文件与子目录（含空目录），缺失的远端目录按需创建（已存在则复用、不重建），文件按 `--if-exists` 新建/覆盖/跳过。**执行前必须获得用户确认；非交互环境先用 `--dry-run` 预览，确认后再加 `--yes`。只新增/覆盖，不删除远端多余文件。** - -``` -Usage: - dws drive push [flags] -Example: - dws drive push --local-folder /abs/path/repo --remote-folder - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart - dws drive push --local-folder /abs/path/repo --remote-folder --if-exists overwrite -Flags: - --local-folder string 本地文件夹绝对路径 (必填) - --remote-folder string 钉盘目标文件夹 ID (dentryUuid) (必填) - --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --if-exists string 远端文件已存在时的策略: skip|smart|overwrite (默认 skip；命令写钉盘，执行需确认) -``` - -`--if-exists` 策略（与 pull 一样默认 `skip`，避免未显式选择时覆盖既有文件）： - -| 值 | 行为 | -|----|------| -| `skip`（默认） | 远端已存在则保持不动，只新增 | -| `smart` | 增量同步：远端 `modified_time` 已 ≥ 本地则跳过，否则走覆盖路径 | -| `overwrite` | 覆盖远端同名文件（原地覆盖，保留 fileId，不产生重名副本） | - -输出 schema（`action`：`uploaded` / `overwritten` / `skipped` / `folder_created` / `failed`）： - -```json -{ - "summary": {"uploaded": 0, "skipped": 0, "failed": 0, "aborted": false}, - "items": [ - {"rel_path": "sub", "action": "folder_created"}, - {"rel_path": "a.txt", "action": "uploaded", "size_bytes": 11}, - {"rel_path": "b.txt", "action": "overwritten", "size_bytes": 8}, - {"rel_path": "c.txt", "action": "skipped", "size_bytes": 5}, - {"rel_path": "d.bin", "action": "failed", "size_bytes": 0, "error": "..."} - ] -} -``` - -注意事项： - -- 只上传/覆盖 `type=file`；`summary.uploaded` 同时统计新建与覆盖，**不含目录**。 -- `overwrite` / `smart` 命中覆盖分支时走**覆盖上传**（`get_upload_info` 与 `commit_upload` 两阶段都携带远端 `overwriteFileId`、不传 `parentId`），在原文件上原地覆盖、保留 fileId，不会在同目录新建重名副本。 -- 本地子目录（含空目录）整体镜像：缺失的按需 `create_folder`（以 `folder_created` 留痕），已存在的远端目录复用其 fileId、不重建、不出现在 `items[]`。 -- 本地名称若含反斜杠、控制字符等无法安全映射到钉盘的成分，或双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义，命令会在任何创建或上传前整批失败；不会只跳过冲突项后继续写入。 -- `summary.failed > 0` 时命令以**非零退出码**退出；结构化 `summary + items` 仍打印在 stdout 上，脚本/agent 直接看 exit code 判断成败。 - -### 本地文件夹与钉盘文件夹双向同步 - -读写命令：把本地 `--local-folder` 与钉盘 `--remote-folder` 做**文件级双向同步**。**这是写操作，非交互环境下必须显式加 `--yes`；先用 `--dry-run` 看清将发生什么。**先按 `status` 同源逻辑算出五类差异，再分别处理：`new_remote` 下载到本地、`new_local` 上传到钉盘、两侧都变更的 `modified` 按 `--on-conflict` 策略消解；`unchanged` 与 `unknown` 一律跳过、不动。**只新增/覆盖，两侧都不删除多余文件。** - -``` -Usage: - dws drive sync [flags] -Example: - dws drive sync --local-folder /abs/path/repo --remote-folder - dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict local-wins - dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both - dws drive sync --local-folder /abs/path/repo --remote-folder --quick -Flags: - --local-folder string 本地文件夹绝对路径 (必填) - --remote-folder string 钉盘文件夹 ID (dentryUuid) (必填) - --space-id string 钉盘空间 ID，不传则使用「我的文件」(可选) - --on-conflict string 两侧都变更时的策略: skip|remote-wins|local-wins|keep-both|ask (默认 skip；命令写双端，执行需确认) - --quick 快速模式：只比较 modified_time，不计算 MD5 (可选) -``` - -`--on-conflict` 仅作用于 `modified`（两侧都存在且都变更）的文件： - -| 值 | 行为 | -|----|------| -| `skip`（默认） | 两侧都不动，两边内容都保留，计入 `skipped` | -| `remote-wins` | 下载远端覆盖本地（需 `--yes`） | -| `local-wins` | 覆盖上传本地到远端（原地覆盖、保留 fileId；需 `--yes`） | -| `keep-both` | 先在同一目录以不覆盖的原子硬链接保留本地副本（`名.conflict-.扩展名`），再把远端拉到原名；拉取失败时原文件与候选副本都保留并报告失败，不做可能误伤并发文件的回滚 | -| `ask` | 逐个交互询问；`--dry-run` 或非交互环境下等价于跳过 | - -输出 schema（`action`：`downloaded` / `uploaded` / `overwritten` / `folder_created` / `renamed_local` / `skipped` / `failed`；其中 `renamed_local` 是兼容动作名，表示已成功保留本地冲突副本；`direction`：`pull` / `push` / `conflict`）： - -```json -{ - "detection": "exact", - "diff": { - "new_local": [{"rel_path": "a.txt"}], - "new_remote": [{"rel_path": "b.txt"}], - "modified": [{"rel_path": "c.txt"}], - "unchanged": [], - "unknown": [] - }, - "summary": {"pulled": 1, "pushed": 1, "skipped": 0, "failed": 0}, - "items": [ - {"rel_path": "b.txt", "action": "downloaded", "direction": "pull"}, - {"rel_path": "a.txt", "action": "uploaded", "direction": "push"}, - {"rel_path": "c.txt", "action": "overwritten", "direction": "conflict"} - ] -} -``` - -注意事项： - -- 复用 `status`/`pull`/`push` 的全部安全约束：只处理 `type=file`（在线文档、快捷方式跳过）；远端名称含 `..`、路径分隔符、盘符或目标平台保留名等不可安全映射成分时会在任何同步写入前中止整棵远端树，拼接后逃逸出 `--local-folder` 的路径记为 `failed` 不落盘；下载走「先写临时文件、成功才原子 rename」，失败绝不破坏本地原文件。 -- `--dry-run` 只算差异并输出独立 JSON 预览对象，不触发任何下载/上传/改名/落盘；差异位于顶层预览对象的 `plan.diff`（同时包含 `dry_run=true`、`executed=false` 与 `preview_kind=plan`）。 -- 双端存在 `A/a`、Unicode NFC/NFD、等价祖先前缀或文件/目录类型歧义时，`sync` 会在任何一侧写入前整批失败；本地无法安全映射到钉盘的名称同样 fail-closed。 -- `unknown`（exact 模式远端无可靠 MD5）一律计入 `skipped`、不做任何写操作；需要强制对齐时改用单向的 `pull`/`push`。 -- `summary.failed > 0` 时命令以**非零退出码**退出，结构化结果仍打印在 stdout 上。 - -## 意图判断 - -用户说"我的文件/钉盘/网盘/云盘" → `list` -用户说"最近访问/最近打开/最近编辑/最近文档" → `recent`（默认仅最近访问，`--operate-type 1` 仅最近编辑，`--operate-type 0,1` 全部） -用户说"钉盘空间/团队文件/有哪些空间/空间列表/团队文件列表" → `list-spaces` -用户说"搜索钉盘文件/钉盘里找个文件/查找某个钉盘文件/钉盘中搜索" → `search` -用户说"文件详情/文件信息" → `info` -用户说"下载文件" → `download` -用户说"新建文件夹/创建目录" → `mkdir`（钉盘空间）/ `folder create`（文档空间） -用户说"上传文件/传文件到钉盘" → `upload`（必须使用此命令，自动完成三步流程） -用户说"复制文件/移动文件/搬到/移到" → `copy` / `move` -用户说"创建快捷方式/创建链接/放个快捷方式/引用到其他位置" → `shortcut` -用户说"阅读量/查看次数/多少人看过/点赞数/评论数/下载次数/文档统计/数据统计" → `stats` -用户说"封面/封面图/缩略图/预览图/节点封面" → `cover` -用户说"历史版本/版本列表/文件版本/有哪些版本/版本记录" → `list --versions --node ` -用户说"下载历史版本/下载旧版本/恢复历史版本到本地" → `download --version ` -用户说"回滚版本/恢复到某个版本/还原到旧版本/版本回退" → `revert`（危险操作，需确认） -用户说"重命名/改名" → `rename` -用户说"删除文件/删除文件夹/移到回收站" → `delete`（危险操作，需确认） -用户说"回收站/查看回收站/回收站列表/回收站里有什么" → `recycle list` -用户说"恢复文件/还原删除的文件/从回收站恢复/还原回收站文件" → `recycle restore` -用户说"收藏文档/收藏这个文件/加个收藏/标星" → `star add` -用户说"取消收藏/去掉收藏/不收藏了" → `star remove` -用户说"我的收藏/收藏列表/收藏了哪些文档/看看收藏" → `star list` -用户说"给文档授权/分享权限" → `permission add` -用户说"打不开/没权限/申请权限/我要编辑权限/找谁审批/申请访问权限" → 先 `permission apply-info` 查可申请角色与审批人 → 再 `permission apply` 发起申请 -用户说"公开文件/互联网公开/设置公开/让互联网所有人可访问" → `publish set` -用户说"关闭公开/取消公开/取消互联网访问" → `publish unset` -用户说"查看公开状态/是否公开/发布状态" → `publish get` -用户说"比较本地和云盘/看哪些文件变了/同步差异/diff" → `status` -用户说"把钉盘文件夹拉到本地/下载整个文件夹/镜像/同步到本地/pull" → `pull` -用户说"把本地文件夹传到钉盘/推送整个文件夹/上传目录/同步到云端/push" → `push` -用户说"双向同步/两边同步/本地和云盘互相同步/让两边一致/sync" → `sync`（默认两侧都变更时跳过；要覆盖须显式给 `--on-conflict` 并加 `--yes`） -用户说"查任务状态/导出好了没/任务进度/导入状态" → 文档导出用 `dws doc export get --job-id `，导入用 `dws doc import get --task-id ` - -关键区分: drive(文件管理) vs doc(文档内容读写) vs wiki(空间管理) - -**drive search vs wiki node search**: 用户提到"钉盘/网盘/我的文件里搜" → `drive search`；提到"知识库/文档空间/workspace 里搜" → `wiki node search`；未明确目标时优先问明。 - -**drive upload**: 新文件上传统一走 `drive upload`。覆盖普通文件时先 `drive info` 取原 `name`，再用 `drive upload --node --file --file-name "<原name>" --format json`；省略 `--file-name` 会隐式重命名。上传到知识库/文档空间时加 `--workspace` 参数。 - -**drive permission vs wiki member**: "给某篇文档/文件授权" → `drive permission add`（节点级）；"给某个知识库整体加成员" → `wiki member add`（空间级） - -**创建在线文档/表格/脑图**: drive 不支持创建文件，需走 `wiki node create --type `（创建空节点）或 `doc create`（创建并写入内容）。 - -**导出文档/导出为Word**: 导出是内容层操作，走 `doc export`，不属于 drive。超时后的状态查询用 `dws doc export get --job-id `。 - -**版本管理**: 当前 CLI 仅支持钉钉在线文档（adoc）的版本管理（`dws doc version list/save/revert`）；普通文件的历史版本列出/下载/回滚暂不支持。 - -**.md 文件的内容操作路由**: 当 `drive info` 返回 `extension=md` 时，文件管理操作（移动/重命名/删除/下载文件）留在 `drive`，但**读取或改写原文内容必须切换到 `markdown` 产品**： -- 用户说"读取/看一下 markdown 内容/获取 .md 原文" → `dws markdown fetch --node `（非 `drive download`） -- 详见 `dingtalk-misc` 的 [markdown.md](../../dingtalk-misc/references/markdown.md) - -## 核心工作流 +## 回收站 ```bash -# 1. 浏览「我的文件」根目录 -dws drive list --limit 20 --format json - -# 2. 进入子目录 — 提取 dentryUuid 作为 folder -dws drive list --limit 20 --folder --format json - -# 3. 查看文件元数据 -dws drive info --node --format json - -# 4. 下载文件到本地 -dws drive download --node --output /tmp/ --format json - -# 5. 创建文件夹 -dws drive mkdir --name "项目资料" --format json - -# 6. 上传文件（必须使用 upload 命令，禁止手动分步操作） -dws drive upload --file ./报告.pdf --format json -dws drive upload --file ./报告.pdf --folder --format json - -# 7. 删除文件/文件夹到回收站（危险操作：必须先向用户确认，用户同意后才加 --yes 执行） -# 正确流程：1.向用户展示"即将删除「文件名」到回收站" → 2.等用户确认 → 3.执行下面命令 -dws drive delete --node --yes --format json - -# 8. 查看回收站并还原文件 -dws drive recycle list --format json -dws drive recycle restore --id --format json - -# 9. 收藏 / 取消收藏 / 查看收藏列表 -dws drive star add --node --format json -dws drive star remove --node --format json -dws drive star list --format json -dws drive star list --content-types doc,sheet --limit 10 --format json - -# 10. 比较本地文件夹与钉盘文件夹的差异（只读；remote-folder 必传，用 list 查 dentryUuid） -dws drive status --local-folder /abs/path/repo --remote-folder --format json -dws drive status --local-folder /abs/path/repo --remote-folder --space-id --format json -dws drive status --local-folder /abs/path/repo --remote-folder --quick --format json - -# 11. 把钉盘文件夹镜像到本地（Drive → 本地；smart 为推荐的增量同步） -dws drive pull --local-folder /abs/path/repo --remote-folder --format json -dws drive pull --local-folder /abs/path/repo --remote-folder --if-exists smart --format json - -# 12. 把本地文件夹镜像到钉盘（本地 → Drive；默认 skip 只新增，smart 增量，overwrite 覆盖） -dws drive push --local-folder /abs/path/repo --remote-folder --format json -dws drive push --local-folder /abs/path/repo --remote-folder --if-exists smart --format json - -# 13. 本地与钉盘双向同步（默认 --on-conflict=skip 两侧都不动；要覆盖须显式选策略并加 --yes） -dws drive sync --local-folder /abs/path/repo --remote-folder --format json -dws drive sync --local-folder /abs/path/repo --remote-folder --on-conflict keep-both --format json +dws drive +delete --node +dws drive +recycle-list --limit 20 +dws drive +recycle-restore --id ``` -## 无权限引导申请工作流 +删除前核对名称、类型和 ID；恢复从列表真实返回取 `id`。恢复后使用返回的新 nodeId，不沿用旧 ID。 -当 Agent 执行文档操作（如 `doc read` / `drive info` / `drive download`）遇到权限拒绝错误时，按以下流程引导用户申请权限： +## 普通文件历史版本 -> **CAUTION（红线）：`apply` 会真实通知审批人，属于有副作用操作。Agent 严禁自行提交申请。必须先向用户逐项回显确认「资源 / 角色 / 审批人 / 理由」，得到用户明确同意后，才能执行 `apply`。用户未明确同意前，只能停在确认环节，不得调用 `apply`。** +| 意图 | 入口 | 完成证据 | +|---|---|---| +| 列版本 | `+version-history` | 版本集合与分页字段 | +| 查看版本 | `+version-get` | 请求的 version | +| 下载版本 | `+version-download` | 相对路径存在且 sizeBytes > 0 | +| 回滚版本 | `+version-revert` | Runtime 确认后读回最新版本 | -``` -1. 识别错误 → 询问用户「该文档你暂无权限，是否申请？」 -2. 用户确认申请 → 查可申请角色与审批人： - dws drive permission apply-info --node <节点ID或URL> --format json -3. 向用户展示 availableRoles / approvers，询问「申请哪个角色？发给哪位审批人？」 -4. 用户选择 role + 审批人（可选填 reason） -5. Agent 回显确认「资源 / 角色 / 审批人 / 理由」→ 等待用户明确同意（这是提交前的强制关卡，不可跳过） -6. 仅在用户明确同意后，才发起申请： - dws drive permission apply --node <节点ID或URL> --role --users <审批人userId> [--reason "..."] -7. 展示 applyResult / applyResultDesc -``` +这些入口只用于普通文件。adoc 版本走 Doc，axls 版本走 Sheet。 -要点： -- `apply-info` 的 `availableRoles[].roleId` → `apply --role`；`approvers[].userId` → `apply --users` -- **`apply` 严禁自动/静默调用**：必须由用户在看到确认信息后明确同意（如回复"确认/同意/提交"）才可执行；Agent 不得替用户决定或跳过确认 -- `applyResult` 含义：NORMAL(已提交)/HAS_PERMISSION_ALREADY(已拥有)/APPLYING(审批中)/APPLYING_BUT_REAPPLY(已重新提交) +## 收藏、统计与封面 -## 文档空间管理命令 +- 收藏列表：`+star-list`；收藏/取消：`+star-add` / `+star-remove`。 +- 节点统计和封面优先并入 `+inspect --include-stats` / `--include-cover`；只取单项才用 `+stats` / `+cover`。 +- 收藏是个人状态，不代表共享或权限变化。 -> 以下命令操作的是**文档空间**（知识库 / 我的文档），底层路由到 doc MCP server。 -> 与钉盘命令（list / mkdir / upload 等）的区别：钉盘命令操作钉盘空间（spaceId 纯数字），文档空间命令操作知识库/我的文档（workspaceId 加密 string）。 - -### 复制/移动/重命名文件 - -``` -Usage: - dws drive copy --node [--folder ] [--workspace ] - dws drive move --node [--folder ] [--workspace ] - dws drive rename --node --name "新名称" -Flags: - --node string 文档/文件 ID 或 URL (必填) - --folder string 目标文件夹 nodeId - --workspace string 目标知识库 ID - --name string 新名称 (仅 rename 必填) -``` - -> **字段选择**：`drive list` 返回中有 `dentryId`（数字格式）和 `fileId`（UUID 格式），**必须使用 `fileId`（UUID 格式）**作为 `--node` 和 `--folder` 参数值。 - -### 获取节点统计信息 - -获取指定节点的统计数据（阅读人数、阅读次数、编辑次数、评论数、点赞数、预览次数、下载次数等）。 - -``` -Usage: - dws drive stats [flags] -Example: - dws drive stats --node - dws drive stats --node https://alidocs.dingtalk.com/i/nodes/ -Flags: - --node string 节点 ID (dentryUuid) 或文档 URL (必填) -``` - -> **统计维度因文件类型而异**： -> - 钉钉在线文档（adoc）：阅读人数、阅读次数、编辑次数、评论数、点赞数、预览次数等 -> - 普通文件：仅阅读次数、下载次数 -> - 点赞数（likeCount）仅在线文档（adoc）有效 - -### 获取节点封面地址 - -获取指定节点的封面图片地址。 - -``` -Usage: - dws drive cover [flags] -Example: - dws drive cover --node - dws drive cover --node https://alidocs.dingtalk.com/i/nodes/ -Flags: - --node string 节点 ID (dentryUuid) 或文档 URL (必填) -``` - -> **封面因文件类型而异**： -> - 钉钉在线文档（adoc）：文档首图/预览封面 -> - 图片文件：图片缩略图地址 -> - 其他文件：文件类型图标地址（如有） - -### 文件历史版本管理 - -获取文件历史版本列表、下载历史版本。 - -> **适用范围**：仅适用于普通文件（如 pdf、docx、xlsx、png 等）。 -> - 钉钉在线文档（adoc）请使用 `dws doc version list` -> - 钉钉在线表格（axls）请使用 `dws sheet version list` -> - 命令会自动检测文件类型，若为在线文档会提示使用对应服务命令 - -#### 获取文件历史版本列表 - -``` -Usage: - dws drive list --versions [flags] -Example: - dws drive list --node --versions --format json - dws drive list --node --versions --limit 20 --format json -Flags: - --node string 文件 ID (dentryUuid) 或 URL (必填) - --limit int 每页最大数量 (默认 20，最大 50) - --cursor string 分页游标 (从上次返回结果获取，首次不传) -``` - -#### 下载文件历史版本 - -``` -Usage: - dws drive download-version [flags] -Example: - dws drive download-version --node --version 3 --output ./report_v3.pdf --format json - dws drive download-version --node --version 3 --output --format json -Flags: - --node string 文件 ID (dentryUuid) 或 URL (必填) - --version int 历史版本号 (必填，正整数，从 list --versions 获取) - --output string 本地保存路径 (文件路径或目录，必填) -``` - -> **两步下载流程**：先调用 MCP 工具获取历史版本下载 URL 和签名头，再 HTTP GET 下载文件内容到本地。 -> `--output` 指定目录时，优先从文件信息中获取原始文件名，获取不到时从下载 URL 推断。 -> 历史版本下载同样支持 `--part-size` / `--parallel` / `--no-resume` 分片下载参数，行为与最新版下载一致。 - -#### 回滚文件到指定历史版本 - -> **CAUTION:** 危险操作 — 执行前必须向用户确认。 - -``` -Usage: - dws drive revert [flags] -Example: - dws drive revert --node --version 3 --yes --format json -Flags: - --node string 文件 ID (dentryUuid) 或 URL (必填) - --version int 要回滚到的历史版本号 (必填，正整数) - --yes 跳过确认提示 -``` - -回滚成功后，系统会基于目标版本生成一份新的最新版本（内容与目标版本一致），原有历史版本不会丢失。 -仅支持普通文件（Word、Excel、PDF、图片等）的历史版本回滚。在线文档的版本回滚请用 `dws doc version revert`，在线表格请用 `dws sheet version revert`。 -需要当前用户对该文件具备编辑权限。 - -### 创建快捷方式 - -为指定的源节点创建快捷方式（链接），放置到目标位置。 - -``` -Usage: - dws drive shortcut [flags] -Example: - dws drive shortcut --node - dws drive shortcut --node --folder - dws drive shortcut --node --workspace -Flags: - --node string 源节点 ID (dentryUuid) 或文档 URL (必填) - --folder string 目标文件夹 nodeId，不传则放到知识库/我的文档根目录 (可选) - --workspace string 目标知识库 ID (可选) -``` - -> **目标位置规则**：`--folder` 和 `--workspace` 都不传时默认放置到「我的文档」根目录；同时传入时以 `--folder` 为准，`--workspace` 仅用于一致性校验。 -> **权限要求**：对源节点有“可查看”权限，对目标文件夹有“编辑”权限。 -> **目标位置限制**：若目标位置不支持在其下创建子节点（如快捷方式节点、非文件夹），会返回错误，请改指定一个文件夹作为目标位置。 - -### 创建文件夹（文档空间） - -``` -Usage: - dws drive folder create --name "文件夹名" -Flags: - --name string 名称 (必填) - --folder string 父文件夹 nodeId - --workspace string 目标知识库 ID -``` - -### 权限管理（文档节点级） - -``` -Usage: - dws drive permission add --node --users uid1,uid2 --role READER - dws drive permission update --node --users uid1 --role EDITOR - dws drive permission list --node - dws drive permission remove --node --users uid1 - dws drive permission transfer-owner --node --new-owner - dws drive permission transfer-owner --workspace --new-owner - dws drive permission transfer-owner --node --new-owner --reserve-role EDITOR --recursive=false --yes -Flags: - --node string 目标节点 ID 或 URL (必填) - --users string 用户 userId 列表，逗号分隔 - --role string 角色: MANAGER / EDITOR / DOWNLOADER / READER - --limit int 返回成员数上限 (仅 list，默认 30，最大 200) - --filter-role string 按角色过滤 (仅 list) - --workspace string 目标知识库 ID 或 URL (仅 transfer-owner，与 --node 二选一) - --new-owner string 新所有者的用户 userId (仅 transfer-owner，必填) - --reserve-role string 转交后原所有者保留角色: MANAGER / EDITOR / DOWNLOADER / READER / NONE(移除权限) (仅 transfer-owner) - --recursive bool 是否递归变更所有子节点的所有者 (仅 transfer-owner) -``` - -> **`transfer-owner` 为 [危险] 操作，执行前需要确认。** -> -> - 交互模式下会依次提示选择原所有者保留角色、是否递归变更子节点，然后显示操作摘要等待确认 -> - 使用 `--yes` 跳过确认时，`--reserve-role` 和 `--recursive` 必须显式指定（禁止静默默认值） -> - `--reserve-role NONE` 表示移除原所有者的所有权限 -> - 当前用户需为该节点/知识库的所有者才能执行转交 - -> ** Agent 行为约束（必须遵守）** -> -> `--reserve-role` 和 `--recursive` 属于高风险操作的核心决策参数，**必须由用户明确指定**，Agent 不得自行选择默认值（如 `NONE` / `false`）代替用户决策。 -> -> 执行 `transfer-owner` 前，Agent **必须**先通过对话向用户询问以下两个问题，只有在用户明确回答后才构造命令执行： -> -> 1. **"转交后原所有者保留什么角色？"** 选项： -> - `MANAGER`（管理者） -> - `EDITOR`（编辑者） -> - `DOWNLOADER`（下载者） -> - `READER`（只读者） -> - `NONE`（移除原所有者权限） -> 2. **"是否递归变更所有子节点的所有者？"** 选项： -> - `true`（是） -> - `false`（否） -> -> 正确流程：1.向用户询问上述两个问题 → 2.根据用户选择构造 `--reserve-role <用户选择> --recursive=<用户选择> --yes` → 3.执行命令 -> -> **禁止**在未获得用户明确回答的情况下直接执行命令。 - -### 权限申请（无权限时发起申请） - -> 当你对文档/知识库暂无访问权限时，可查询可申请的角色与审批人，并向审批人发起权限申请。 - -``` -Usage: - dws drive permission apply-info --node - dws drive permission apply --node --role --users <审批人userId...> -Example: - dws drive permission apply-info --node - dws drive permission apply --node --role READER --users uid1 - dws drive permission apply --node --role EDITOR --users uid1,uid2 --reason "需要编辑该文档" -Flags: - --node string 目标节点 ID 或 URL (必填) - --role string 申请的角色: EDITOR / DOWNLOADER / READER (仅 apply 必填) - --users string 审批人 userId 列表，逗号分隔 (仅 apply 必填) - --notify-mode string 通知方式: DEFAULT / MSG_ACCOUNT / SINGLE_CHAT (仅 apply 可选) - --reason string 申请理由，最长 200 字符 (仅 apply 可选) -``` - -子命令说明： -- `apply-info` — 查询节点可申请的角色列表 (availableRoles) 与审批人列表 (approvers) -- `apply` — 向审批人发起权限申请 - -返回字段说明： -- `apply-info`： - - `availableRoles[].roleId` — 可申请角色 (EDITOR/DOWNLOADER/READER)，用作 `apply --role` - - `availableRoles[].name` / `desc` — 角色名称/描述 - - `approvers[].userId` — 审批人 userId，用作 `apply --users` - - `approvers[].userName` — 审批人名称 - - `approvers[].isResourceCreator` — 是否为资源创建者 -- `apply`： - - `applyResult` — 申请结果：NORMAL(已提交申请)/HAS_PERMISSION_ALREADY(已拥有该权限)/APPLYING(已有待审批申请)/APPLYING_BUT_REAPPLY(已重新提交申请) - - `applyResultDesc` — 结果的人类可读描述 - -> **重要（Agent 编排）**：`apply` 会向审批人发送通知，属副作用操作。Agent 必须在调用 `apply` 前，向用户回显「资源 / 申请角色 / 审批人 / 理由」并取得用户确认后再执行。 - -### 文件互联网公开发布 - -管理文件的互联网公开发布状态。公开后任何人通过链接即可访问，无需登录钉钉。操作者需要是文件的管理员或拥有者。 - -> **`publish set` 和 `publish unset` 为 [危险] 操作，执行前需要确认。必须传入 `--yes` 跳过交互式确认。** - -``` -Usage: - dws drive publish set --node [--permission READER|DOWNLOADER|EDITOR] - dws drive publish unset --node - dws drive publish get --node -Example: - dws drive publish set --node - dws drive publish set --node --permission READER - dws drive publish get --node - dws drive publish unset --node -Flags: - --node string 目标文件 ID (dentryUuid) 或 URL (必填) - --permission string 公开后的权限: READER(仅可查看) / DOWNLOADER(可查看和下载，默认) / EDITOR(可编辑)，仅 set 有效 -``` - -子命令说明： -- `publish set` — [危险] 设置文件为互联网公开，可选指定公开权限 -- `publish unset` — [危险] 关闭文件互联网公开 -- `publish get`（别名 `status`）— 查询文件当前的公开发布状态 - -返回字段说明： -- `published` — true=已公开，false=未公开 -- `publishPermission` — 当前公开权限（READER/DOWNLOADER/EDITOR） -- `pendingApproval` — true=已提交审批待生效，false/null=无需审批或已直接生效 -- `docUrl` — 文件访问链接 - -> **注意**：`drive export` 不存在。导出仅对自研文档 (adoc) 有意义，属于内容层操作，应使用 `doc export`。 - -### 目标位置参数规则 - -| 目标位置 | 参数传递方式 | 前置步骤 | -|---------|-----------|---------| -| 未指定目标（默认） | `--folder ` | 先 `dws drive list-spaces --space-type mySpace` 获取「我的文件」的 `rootFolderId` | -| 知识库空间根目录 | `--workspace ` | 无需额外步骤 | -| 钉盘 space 根目录 | `--folder ` | 先 `dws drive list-spaces` 获取目标 space 的 `rootFolderId` | -| 钉盘 space 下的子文件夹 | `--folder ` | 先 `dws drive list --space-id ` 逐层浏览 | - -### 工作流示例 +## 公开状态 ```bash -# ── 场景 默认: 复制/移动到「我的文件」根目录 ── -dws drive list --space-id --format json -dws drive list-spaces --space-type mySpace --format json -dws drive copy --node <源文件dentryUuid> --folder <我的文件rootFolderId> --format json - -# ── 场景 A: 复制到知识库空间根目录 ── -dws drive copy --node <源文件dentryUuid> --workspace --format json - -# ── 场景 B: 移动到另一个钉盘 space 根目录 ── -dws drive list-spaces --format json -dws drive move --node <源文件dentryUuid> --folder <目标space的rootFolderId> --format json - -# ── 场景 C: 复制到钉盘子文件夹 ── -dws drive list --space-id --format json -dws drive copy --node <源文件dentryUuid> --folder <目标文件夹fileId> --format json +dws drive +publish-get --node +dws drive +publish-unset --node ``` -## 上下文传递表 +`+publish-get` 只读；`+publish-unset` 为高风险写。公开 catalog 没有 `+publish-set`；明确要求开启公开时只查询一次 `drive publish set` 精确 leaf，并按 Runtime confirmation 执行，不猜造 Shortcut。 -| 操作 | 从返回中提取 | 用于 | -| ------------- | ---------------------------- | -------------------------------------------------------- | -| `list` | **`fileId`**（UUID 格式，注意：不是 `dentryId`） | info / download / mkdir / delete / stats / shortcut / cover 的 --node 或 --folder；`drive copy/move` 的 --node 或 --folder | -| `list` | `spaceId` | info / download / mkdir / commit 的 --space-id | -| `list-spaces` | `rootFolderId` | `drive copy/move` 的 --folder（复制/移动到钉盘 space 根目录时） | -| `list-spaces` | `spaceId` | list / info / download / mkdir / upload 的 --space-id | -| `search` | **`fileId`**（文件/文件夹结果） | info / download / delete 的 --node；list 的 --folder | -| `search` | `spaceId` / `rootFolderId`（空间结果） | list 的 --space-id；`drive copy/move` 的 --folder | -| `search` | `nextCursor` | search 的 --cursor（翻页） | -| `mkdir` | `fileId`（UUID 格式） | list 的 --folder | -| `recycle list` | `id`（回收项 ID） | recycle restore 的 --id | -| `recycle list` | `name`（原始文件名） | 供用户确认还原目标 | -| `recent` | `recentItems[].nodeId` / `docUrl` | doc read / info / update / block 操作的 --node | -| `recent` | `nextCursor` | recent 的 --cursor（翻页） | -| `permission apply-info` | `availableRoles[].roleId` | `permission apply` 的 --role | -| `permission apply-info` | `approvers[].userId` | `permission apply` 的 --users | -| `star list` | `starList[].nodeId` | star remove 的 --node；info / download 的 --node | -| `star list` | `nextCursor` | star list 的 --cursor（翻页） | +## 权限 -> **重要**：`drive list` 返回结果中同时包含 `dentryId` 和 `fileId` 两个字段。所有需要传 `--node` 的命令（info / download / delete）必须使用 `fileId`（即 dentryUuid），**不要使用** `dentryId`。 +| 意图 | managed leaf | +|---|---| +| 查看成员权限 | `drive permission list` | +| 添加、修改、移除成员 | `permission add` / `update` / `remove` | +| 转移所有者 | `permission transfer-owner` | +| 查看可申请权限和审批人 | `permission apply-info` | +| 发起权限申请 | `permission apply` | -## 注意事项 +只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。 -- 不传 `--space-id` 时默认使用「我的文件」空间 -- 不传 `--folder` 时默认操作空间根目录 -- `--folder` 只能使用父文件夹的 `dentryUuid`。不要把 `drive info` 返回的数字型 `dentryId` 当作父目录；`dentryId` 只用于 `chat message send --dentry-id` -- **`--limit` 最大值为 50**，禁止传入超过 50 的值（如 `--limit 100`）。用户要求超过 50 条时，应使用 `--limit 50` 配合 `--cursor` 分页查询，不要直接传大于 50 的值 -- `--order-by` 支持: `createTime`、`modifyTime`、`name` -- **上传文件必须使用 `dws drive upload` 命令**，禁止使用 `upload-info` + `curl` + `commit` 三步手动流程 -- `--file-name` 必须包含扩展名（如 `report.pdf`） +## 快捷方式节点 -## 自动化脚本 +`+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接；需要独立副本使用 `+copy`。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。 -| 脚本 | 场景 | 用法 | -| ------------------------------------------------------ | ----------- | ------------------------------------- | -| [drive_tree_list.py](../scripts/drive_tree_list.py) | 递归列出钉盘目录树结构 | `python drive_tree_list.py --depth 2` | +## 错误恢复 -## 相关产品 - -- [doc](../../dingtalk-doc/references/doc.md) — 文档内容读写/知识库空间，不是文件存储 -- [markdown](../../dingtalk-misc/references/markdown.md) — `.md` 文件的内容读取（fetch），非文件管理 -- [chat](../../dingtalk-chat/references/chat.md) — 上传文件到 drive 后可通过 Markdown 语法发送图片/文件消息 +1. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Drive Shortcut 清单。 +2. 分页、递归或过滤未完成时保留 cursor/truncated/errors，不包装成全量成功。 +3. 写入超时或响应丢失先按 nodeId、名称、路径和大小回读，不能盲目重放。 +4. 在线文档误入普通下载/覆盖时切 Doc、Sheet 或 AITable；不要用 Drive 重试改变内容。 diff --git a/skills/multi/dingtalk-drive/references/folder-sync.md b/skills/multi/dingtalk-drive/references/folder-sync.md new file mode 100644 index 00000000..8922dfeb --- /dev/null +++ b/skills/multi/dingtalk-drive/references/folder-sync.md @@ -0,0 +1,40 @@ +# Drive 文件夹比较与同步 + +仅用于本地目录与钉盘普通文件夹之间的递归文件级比较或镜像。单个文件使用根 Skill 的 `+download/+upload`。 + +## 选择入口 + +| 目标 | 唯一入口 | +|---|---| +| 只比较，不写任何一侧 | `dws drive status` | +| 钉盘 → 本地 | `dws drive pull` | +| 本地 → 钉盘 | `dws drive push` | +| 两侧互相补齐 | `dws drive sync` | + +四个入口都要求 `--local-folder <绝对路径> --remote-folder `；`--space-id` 可选。动作已经明确时直接进入对应命令，不先重复执行 status。 + +## 安全流程 + +`status` 只读，可直接执行。`pull/push/sync` 会写本地或钉盘，先使用相同参数 `--dry-run` 查看计划；确认目标、方向和冲突策略后，再按 Runtime confirmation 执行。 + +```bash +dws drive status --local-folder /abs/local --remote-folder --format json +dws drive pull --local-folder /abs/local --remote-folder --if-exists smart --dry-run --format json +dws drive push --local-folder /abs/local --remote-folder --if-exists smart --dry-run --format json +dws drive sync --local-folder /abs/local --remote-folder --on-conflict skip --dry-run --format json +``` + +## 策略 + +- pull/push `--if-exists`: `skip` 最保守；`smart` 按修改时间做增量；`overwrite` 以来源侧覆盖目标侧。 +- sync `--on-conflict`: `skip` 默认保留两侧；`remote-wins` 覆盖本地；`local-wins` 覆盖远端；`keep-both` 先改名本地再拉远端；`ask` 需要交互。 +- 默认 exact 通过 MD5 比较；远端缺少可靠 MD5 时进入 `unknown` 并跳过。只有用户接受时间戳近似时才加 `--quick`。 +- 这些命令只处理普通 `type=file` 和目录；在线文档、快捷方式不会按普通二进制同步。 +- 文件级镜像只新增或覆盖，不删除任一侧多余文件。 + +## 结果与恢复 + +- status 检查 `new_local/new_remote/modified/unchanged/unknown`。 +- pull/push/sync 检查 summary 与逐条 items；任何 failed/unknown 必须保留，不把部分结果称为成功。 +- 下载先写临时文件再原子替换；失败时保留原目标。上传失败按远端路径、名称和大小读回，不能直接重放可能已提交项。 +- dry-run 与正式执行必须使用同一 local-folder、remote-folder、space-id 和策略；不要在确认后静默改变方向或冲突策略。 diff --git a/skills/multi/dingtalk-drive/references/intent-guide.md b/skills/multi/dingtalk-drive/references/intent-guide.md index 12d7380a..a09c4ca3 100644 --- a/skills/multi/dingtalk-drive/references/intent-guide.md +++ b/skills/multi/dingtalk-drive/references/intent-guide.md @@ -1,17 +1,20 @@ -# drive 局部意图消歧 +# Drive 局部意图消歧 -本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。 +| 用户表达 | 应用 | 不应用 | 理由 | +|---|---|---|---| +| 全局找文件、最近文件、我的文件/文档空间目录 | Drive | Wiki | 未限定知识库 workspace，属于普通存储域 | +| 明确知识库内列节点、移动节点、搜索节点 | Wiki | Drive | workspace 内层级由 Wiki 管理 | +| 普通文件或文件夹移动、重命名、删除 | Drive | Doc | 节点存储动作不修改正文 | +| 普通文件创建独立副本 | Drive download→upload | Drive `+copy` | 当前 `+copy` 会拒绝普通钉盘文件，避免把 `.dlink` 快捷方式伪装成副本 | +| adoc 正文读取、编辑或导出 | Doc | Drive download | Drive 只管理节点；在线文档需要格式转换 | +| 本地 xlsx/xls/csv 节点下载后分析 | Drive + 本地工具 | Sheet range read | 上传的普通文件不是 axls 在线表格 | +| axls 在线表格导出为 xlsx | Sheet export | Drive download | export 执行格式转换 | +| able 记录、字段、视图 | AITable | Drive | 表内业务数据不属于存储节点动作 | +| able 仅复制结构、删除 Base | AITable `+base-copy --base-id --target-folder-id <真实ID> --only-struct` / `+base-delete --base-id ` | Drive copy/delete | 当前 main 要求真实目标文件夹 ID；缺少时停止，禁止发明 `--target-root`、完整复制后逐表删数据或用 Drive 猜根 ID | +| Base 内 Table/Dashboard/Section 节点操作 | AITable `+table-*` / `+section-*` | Drive | nsheet 节点不是独立 Drive dentry | +| 整个 Base 移到普通文件夹、外层存储重命名 | Drive | AITable 表内命令 | 这是 Base 外层存储位置/名称动作 | +| Word/Markdown/Text 转在线文档 | Doc `+import` | Drive upload | import 会创建在线文档；upload 只保留原文件 | +| “上传文件”但未指定目标 | Drive `+upload` | — | 默认按普通文件上传到钉盘 | +| “照这个文档做一份同样格式的” | Drive `+copy` + `+rename`，再由 Doc 局部更新副本 | 读取后重建 | 先复制可保留在线文档版式 | -| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 | -|---|---|---|---|---| -| "参照这个生成同样的 / 按模板生成 / 复刻 X / 同样的模板 X 月份的" + 已有 alidocs URL | 模板保形生成同形态变体 | `drive copy + drive rename + doc block update` → 见 [best_practices/04-document.md `template-based-generation`](../../dingtalk-doc/references/04-document.md#template-based-generation) | `doc read + doc create`（重写链） | adoc → markdown 是有损投影，read+create 会丢行高/单元格背景色/字号；copy 在 adoc 层保形复制后只在副本上局部修改 | -| "读一下这个 xlsx 的数据" / xlsx 节点链接 | 下载本地表格文件 | `dws drive +download --node --output <相对路径>` | `sheet range read` | xlsx / xls / xlsm / csv 是上传的本地文件（`contentType=DOCUMENT`），sheet 命令只支持在线表格；Shortcut 会验证真实本地字节 | -| "把这个在线表格导出为 xlsx 文件" | 在线表格格式转换 | `dws sheet export` | `dws drive download` | `export` 是 axls → xlsx 的导出转换；`download` 只能下载已有的 xlsx 节点 | -| "帮我把这个文件传到网盘" | 钉盘上传 | `drive +upload` | — | 文件上传是存储层操作，归 drive；Shortcut 负责提交和读回 | -| "上传文件到钉盘/我的文件" | 钉盘上传 | `drive +upload` | — | 提到"钉盘/网盘/我的文件"→ drive | -| "上传文件"（未指定目标） | 默认钉盘 | `drive +upload` | — | 未明确目标时默认上传到钉盘 | -| "帮我看看知识库里的文件" | 知识库节点列表 | `wiki node list --workspace` | `drive list` | 明确"知识库"上下文 → wiki node list | -| "列出钉盘团队空间" | 列出钉盘空间 | `wiki space list --type orgSpace` | `drive list-spaces` | 空间管理归 wiki，drive list-spaces 已 deprecated | -| "在知识库里搜方案" | 空间内搜索 | `wiki node search --workspace` | `drive search` | 指定了空间上下文 → wiki node search | -| "搜一下有没有叫XX的文件" | 全局搜索 | `drive +search` | `wiki node search` | 未指定空间 → Drive Shortcut 严格搜索 | -| "整理一下XX项目的所有讨论" | 跨源主题归档 | #5 generate-topic-report | #4 write-doc | #4 侧重单篇文档创作；按主题跨听记/群消息汇总属于工作汇报 | +URL 本身不能证明产品类型。当前 Drive shortcut 的公开参数主要接受 ID；只有 URL 时先用 `dws drive info --node --format json` 预检并取真实 nodeId/nodeType。 diff --git a/skills/multi/dingtalk-drive/references/lite-recipes.md b/skills/multi/dingtalk-drive/references/lite-recipes.md index 47352249..14815207 100644 --- a/skills/multi/dingtalk-drive/references/lite-recipes.md +++ b/skills/multi/dingtalk-drive/references/lite-recipes.md @@ -1,44 +1,39 @@ -# drive Lite Recipe +# Drive 精简流程 -本文件从单 Skill `lite-recipes.md` 拆分而来，仅保留与本产品相关的轻量流程。 +只在跨 Drive/Doc/Wiki 的组合任务命中时读取。单一 Drive 操作直接按根 Skill 执行。 -## #4 文档知识 +## 查找并读取在线文档 -### query-doc +1. 未指定空间：`dws drive +search --query "<关键词>" --format json`。 +2. 明确知识库：用 Wiki 在指定 workspace 搜索。 +3. 唯一确定 nodeId 后切 Doc `+fetch` 读取正文；大文档按返回 continuation 继续。 -1. 钉盘全局搜索：`drive +search --query "<关键词>"` → `nodeId`；在线文档统一使用 `doc +search` -2. 空间内搜索：`wiki node search --workspace --query "<关键词>"` → `nodeId` -3. `doc read --node `（按需；大文档只抽章节） +Drive search 找的是节点；正文全文检索优先用 Doc `+search`。 -### list-folder-docs +## 列出目录中的文档 -`wiki node list --workspace `；普通钉盘目录使用 `drive +list --folder ` +- 普通钉盘目录：`dws drive +list --folder --format json` +- 知识库目录：切 Wiki，用 workspace + parent node 定位 -### import-file +处理 nextCursor，并设置最大页数/条目数。不要从根目录无界递归。 -将本地文件导入为钉钉在线文档。**一条命令完成上传+格式转换+创建**，无需先读取文件内容。 +## 导入为在线文档 ```bash -dws doc import --file ./report.docx --format json +dws doc +import --file ./report.docx --format json ``` -1. 确认文件路径（用户提供的本地文件路径） -2. 执行：`dws doc import --file <文件路径> --format json`（可选 `--folder <文件夹ID>` / `--workspace <知识库ID>` / `--name "文档名"`） -3. 从返回中提取 `documentUrl`，告知用户导入完成并提供链接 -4. 超时或中断时 CLI 返回 `taskId`，用 `dws doc import get --task-id --format json` 手动查询 +- `.doc/.docx/.md/.txt` 通常导入为在线文字文档；`.xls/.xlsx` 导入为在线表格，最终类型以真实返回为准。 +- 目标是“保留原文件”时使用 Drive `+upload`，不是 Doc import。 +- 用户给目标文件夹 URL 时，若命令契约不保证 URL 直传，先用 `dws drive info --node ` 验证它是 folder，并复用当前节点 nodeId；不要误用其父 folderId。 +- 导入超时或返回 task/checkpoint 时按 Doc 返回的 continuation 恢复，不重复创建。 -**`--folder` 参数传值规则**： -- 首选路径：用户提供 alidocs URL 时，直接将完整 URL 传入 `--folder`，无需先调 `drive info` -- 预检路径：若需确认 URL 指向的是文件夹，可先调 `dws drive info --node `： - - `nodeType == "folder"` → 使用 `nodeId` 或原始 URL 作为 `--folder` 值 - - `nodeType` 不是 folder → 提示用户：该链接指向的不是文件夹 -- 禁止：不得使用 `drive info` 返回的 `folderId` 字段作为 `--folder` 的值（`folderId` 是父文件夹 ID，非当前节点 ID） +## 模板保形生成 -格式与文档类型映射： -- `.docx` / `.doc` → 文字文档（DOC） -- `.xlsx` / `.xls` → 电子表格（SHEET） -- `.xmind` / `.mark` → 脑图（MIND） -- `.md` / `.txt` → 文字文档（DOC） +1. `dws drive +copy --node <源nodeId> --folder <目标folderId>` 保形复制。 +2. 用返回的新 nodeId 执行 `dws drive +rename`。 +3. 切 Doc，只对副本执行局部正文更新。 -> **禁止先 Read 文件再 `doc create` + `doc update`**。`doc import` 是服务端格式转换，客户端无需解析文件内容。 -> 详见 [./doc/doc-import.md](../../dingtalk-doc/references/doc/doc-import.md)。 +不要用“读取 Markdown → 新建文档”替代复制；该路径会丢失在线文档的版式属性。 + +本剧本只适用于 `+copy` 支持的在线文档节点（如 adoc）；普通钉盘文件创建独立副本应改走经用户授权的 download→upload。若源节点是 `able` 且用户要“只复制结构”，切 AITable，按当前 leaf 执行 `+base-copy --base-id --target-folder-id <真实ID> --only-struct`。只有根目录意图但没有真实目标文件夹 ID 时停止；禁止发明 `--target-root`、用 Drive 完整复制后逐表删记录或自建测试文件夹。 diff --git a/skills/multi/dingtalk-wiki/SKILL.md b/skills/multi/dingtalk-wiki/SKILL.md index 320f4f76..46565777 100644 --- a/skills/multi/dingtalk-wiki/SKILL.md +++ b/skills/multi/dingtalk-wiki/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-wiki -description: 钉钉知识库与空间管理。Use when 用户说 知识库/wiki/创建知识库/搜索知识库空间/我的文档/团队空间/空间成员/在指定知识库内的节点创建/列出/搜索/复制/移动/删除/知识库动态。知识库空间与空间内节点管理走本 skill（节点操作需 workspace）；未指定空间的全局文件管理与搜索走 dingtalk-drive，空间内单文档内容读写先用本 skill 定位再切到 dingtalk-doc。命令前缀：dws wiki。 +description: 钉钉知识库与空间管理。Use when 用户明确说 知识库/wiki/创建、查找或列出知识库/命名的团队知识空间/个人知识库/知识库成员/库内节点创建、列表、搜索、复制、移动、删除或知识库动态。仅说“文档空间/我的文档”不触发：普通存储管理与全局文件搜索走 dingtalk-drive；节点正文读写走 dingtalk-doc。命令前缀：dws wiki。 metadata: cli_version: ">=0.2.14" category: product @@ -11,11 +11,19 @@ metadata: # 钉钉知识库 Skill -## 前置条件 — 执行操作前必读 + +## 最小 DWS 执行契约 -> **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。 - -> 命令参考：[wiki.md](references/wiki.md)。 +- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。 +- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。 +- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。 +- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。 +- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。 +- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。 +- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。 +- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。 +- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。 + ## Shortcuts（无专用脚本/recipe 时优先） @@ -28,74 +36,72 @@ metadata: | `dws wiki +wiki-new-doc` | write | 在指定名称的知识库下新建一个文档节点（自动按空间名解析 workspaceId） | -## 意图表 +## Golden Route -| 用户说 | 命令 | -|--------|------| -| "创建知识库" | `dws wiki space create --name "<名称>" [--desc "<描述>"]` | -| "搜索组织知识库空间" | `dws wiki space search --type orgWikiSpace --query "<关键词>"` | -| "我的文档 / 个人知识库" | `dws wiki space search --type myWikiSpace` | -| "列出知识库" | `dws wiki space list` | -| "列出我的文档空间" | `dws wiki space list --type myWikiSpace` | -| "列出知识库里的文件/节点" | `dws wiki node list --workspace ` | -| "在知识库里搜" | `dws wiki node search --workspace --query "<关键词>"` | -| "在知识库里创建文档节点" | `dws wiki node create --workspace --type adoc --name "<名称>"` | -| "知识库动态 / 最近有什么更新 / 谁改了什么" | `dws wiki feed list --workspace ` | +| 用户意图 | 唯一推荐入口 | 关键边界 | +|---|---|---| +| 按名称解析唯一知识库 | `dws wiki +resolve-space --name <名称>` | 0 条或多条停止；只想看候选用 `+space-search` | +| 搜索或列出知识库 | `+space-search --query <关键词>` / `+space-list [--type orgWikiSpace\|myWikiSpace]` | 用户要求全部时加 `--page-all`；个人知识库必须明确语义 | +| 已知 workspace 查看详情 | `dws wiki +space-get --workspace ` | 已知 ID 不重复搜索 | +| 创建或删除知识库 | `+space-create --name <名称>` / `+delete-space --workspace ` | 创建会读回；删除整个空间是高风险操作 | +| 浏览或搜索库内节点 | `+node-list --workspace [--folder ]` / `+node-search --workspace --query <词>` | 列目录与关键词搜索分开；全量列表加 `--page-all` | +| 查看节点元数据 | `dws wiki +node-get --node ` | 正文读写随后切 Doc | +| 已知 workspace 创建节点 | `+node-create --workspace --name <名称> [--type <类型>]` | 支持 adoc/axls/able/appt/adraw/amind/folder；创建后读回 | +| 只有知识库名称时新建空文档 | `+wiki-new-doc --space <名称> --title <标题>` | 内部唯一解析空间；正文另走 Doc | +| 复制、移入知识库或移出到我的文档 | `+node-copy` / `+move` / `+move-to-drive` | 使用真实 nodeId/workspaceId/folderId；按 Runtime confirmation | +| 删除库内节点 | `+node-delete --workspace --node ` | 删除前核对归属并确认 | +| 列出或修改知识库成员 | `+member-list` / `+member-add` / `+member-update` / `+member-remove` | userId 1-30 个；角色必须显式 | +| 查看知识库动态 | `+feed-list --workspace ` | 要全部动态加 `--page-all`，否则只是一页 | -## 标准 SOP（必遵流程） +## 当前最短路径 -> 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 workspaceId/nodeId。每条命令必须带 `--format json`。`workspaceId`/`nodeId` 一律先查后用。 +- 已知 workspaceId：直接执行 space/node/member/feed 目标命令，不再 resolve。 +- 只有知识库名称：需要唯一 ID 用 `+resolve-space`；只需创建空 adoc 用 `+wiki-new-doc`；需要候选列表用 `+space-search`。 +- 已知 nodeId/URL：元数据直接 `+node-get`；正文直接切 Doc，不先 list/search。 +- 创建节点后返回的 nodeId 直接传给 Doc；不通过同名搜索重新定位。 +- move/copy/delete 已含预检或读回时，不由 Agent 重复拼装原子命令。 +- 普通“文档空间/我的文档”不先调用 Wiki 获取默认位置，按存储意图走 Drive。 -### SOP-1 找知识库（find-space） +## 关键结果语义 -**触发**：找知识库/列表空间/某知识库在哪。 +- `+space-list/+node-list/+feed-list` 默认单页；全量请求显式加 `--page-all`，并检查 `autoPageComplete/autoPageStopReason/pagesFetched` 与分页元数据。 +- `+space-search/+node-search` 缺少业务数组不是零命中；只有显式空数组才可报告空结果。 +- `+resolve-space` 只有 `resolved=true` 才提供唯一空间；多候选必须返回候选让用户消歧。 +- 创建空间/节点和复制节点必须取得新 ID 并读回；移动必须验证 workspace/folder；删除必须有 `success=true`。 +- 成员列表服务端没有续页游标且最多 50，不能把上限内结果宣称为全量；成员写只具备终态响应证据，不虚构精确读回。 +- `partial_failure`、分页未完成或写入效果未知都不是成功。 -1. **执行（必须）**：`dws wiki space list --format json`（列所有知识库/钉盘空间）；按名称找 `dws wiki space search --type orgWikiSpace --query "<名称>" --format json`。 -2. **解析（必须）**：取真实 `workspaceId`；多候选让用户确认，**禁止**默认取第一个。`hasMore=true` 用 `nextPageToken` 翻页。 +## 参数与安全边界 -**禁止**：编造 workspaceId、把空间名当 ID。 +- workspaceId、nodeId、folderId、userId 不互相替代；名称不能当 ID。 +- 写操作只按精确 leaf Runtime 判定确认；已明确授权具体空间/节点/成员、动作与影响时，首次正式执行直接带 `--yes`，否则先确认。参数变化重新确认；禁止用缺少 `--yes` 的失败探测。 +- `+member-list --limit` 为 1-50；成员写 `--users` 为 1-30 个，角色仅 `MANAGER|EDITOR|DOWNLOADER|READER`。 +- `+node-create --type` 决定内容产品；建好后 adoc→Doc、axls→Sheet、able→AITable。 +- Profile/组织在空间解析、节点操作和验证期间保持一致。 -### SOP-2 浏览 / 查节点（list-nodes） +## 按需加载 -**触发**：知识库里有哪些文档/列节点/看某节点。 +Golden Route 参数足够时不读 reference；否则最多读取一个： -1. **前置（必须）**：先按 SOP-1 拿 `workspaceId`。 -2. **执行（必须）**：`dws wiki node list --workspace --format json`（按需 `--folder ` 看子节点）；按内容找 `dws wiki node search --workspace --query "<关键词>" --format json`。 -3. **解析（必须）**：取真实 `nodeId` + `nodeType`/`type`；锁定目标后按需切 `dingtalk-doc` 读写节点内容。 +| 触发条件 | Reference | +|---|---| +| 文档空间、知识库、Drive/Doc 边界不明 | [intent-guide](references/intent-guide.md) | +| 节点类型、复制、移动、移出或删除细节 | [node-ops](references/wiki-node-ops.md) | +| 成员角色、上限与验证语义 | [members](references/wiki-members.md) | +| 分页、空间、动态及低频错误 | [wiki reference](references/wiki.md) | +| 跨产品创建/写正文短流程 | [lite-recipes](references/lite-recipes.md) | -**禁止**：跳过 SOP-1 直接猜 workspaceId、用 `node list` 替代 `node search` 做关键词查找。 +## 错误最短路径 -### SOP-3 建节点（create-node） +1. 空响应、缺失集合、零/多候选或分页不完整：停止后续写入并返回证据，不把异常投影为空成功。 +2. workspace/node 归属不一致：停止，不尝试换一个 ID 或 profile。 +3. 写响应缺少新 ID 或 `success=true`：效果未知，按名称/ID定向回读，不盲目重放。 +4. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Wiki Shortcut 清单。 +5. 正文、普通存储或 Base 记录误路由时切回对应产品，不在 Wiki 内试探近似命令。 -**触发**：在知识库建文档/页面。 +## 跨产品边界 -1. **执行（必须）**：`dws wiki node create --workspace --type adoc --name "<名称>" --format json`（按需 `--parent-id <父节点>`）；返回取 `nodeId`。 -2. **写内容（必须）**：节点内容编辑切 `dingtalk-doc`，用 `dws doc update --node --mode overwrite|append --content-file --yes`；写后 `doc read` 回读。 -3. **验证（必须）**：`dws wiki node list --workspace --format json` 复核节点已建。 - -**禁止**：在 wiki 内直接拼内容（应切 doc 写）、建后不回读。 - -### SOP-4 移动 / 复制 / 删节点（mutate-node） - -**触发**：移动节点/复制节点/删节点。 - -1. **执行（必须）**：移动 `dws wiki node move --workspace --node --folder <目标文件夹nodeId> --format json`；复制 `dws wiki node copy --workspace --node --folder <目标文件夹nodeId> --format json`；删除 `dws wiki node delete --workspace --node `（**必须**先与用户确认，再加 `--yes`）。 -2. **验证（必须）**：移动/复制后执行 `dws wiki node list --workspace --folder <目标文件夹nodeId> --format json`，从真实返回确认目标节点；删除后回查确认节点已不存在或进入回收站。 - -**禁止**：未确认就删除、编造 nodeId/folder、把 `--node-id` / `--target-parent-id` 当作公开参数。 - -## 高频硬约束 - -- `space search` 用 `--query`，不要用 `--keyword`；组织知识库显式加 `--type orgWikiSpace`。 -- 用户说"我的文档/个人空间/my workspace"时必须用 `dws wiki space search --type myWikiSpace --format json`；该模式不需要 keyword。 -- 用户给空关键词时，不要构造空 `--query ""`；若语义是我的文档则用 `--type myWikiSpace`，否则请用户补关键词。 -- 搜到空间后复用返回的 `workspaceId/id`；空间内节点创建/列表/搜索用 `wiki node`，具体文档内容读写切到 `dingtalk-doc`，复制/移动切到 `dingtalk-drive`。 -- 所有 `dws wiki` 命令加 `--format json`。 - -## 跨产品协作 - -- 知识库内具体文档读写 → 切到 `dingtalk-doc` -- 普通钉盘文件存储及复制移动 → 切到 `dingtalk-drive` -## 局部意图与短流程 - -- [局部意图消歧](references/intent-guide.md)；[短流程](references/lite-recipes.md)。 +- 明确知识库容器、成员、库内层级与动态 → Wiki。 +- 锁定库内 adoc 节点后的正文读写/导出 → Doc；axls 内容 → Sheet；able 记录/字段 → AITable。 +- 普通文件、文件夹、“我的文档/文档空间”的存储搜索、传输和整理 → Drive。 +- Wiki 节点移入/移出使用 `+move/+move-to-drive`；不要把 workspaceId 当普通 Drive folderId。 diff --git a/skills/multi/dingtalk-wiki/references/wiki-members.md b/skills/multi/dingtalk-wiki/references/wiki-members.md new file mode 100644 index 00000000..39023ff3 --- /dev/null +++ b/skills/multi/dingtalk-wiki/references/wiki-members.md @@ -0,0 +1,24 @@ +# Wiki 成员管理 + +## 入口 + +```bash +dws wiki +member-list --workspace --limit 30 --format json +dws wiki +member-add --workspace --users --role READER --format json +dws wiki +member-update --workspace --users --role EDITOR --format json +dws wiki +member-remove --workspace --users --format json +``` + +- `--users` 接受 1-30 个真实 userId；姓名先由联系人/人员搜索产品解析，不能直接当 userId。 +- 角色仅 `MANAGER|EDITOR|DOWNLOADER|READER`，修改前必须由用户明确角色。 +- workspaceId 来自当前 profile 下真实知识库；不能跨组织复用。 + +## 列表完整性 + +`+member-list` 的服务端单次上限为 50，且没有可续游标。结果能证明“本次返回的成员”，不能据此断言大型知识库的完整成员全集。不要伪造 `--page-all` 或不断提高 limit。 + +## 写入验证 + +成员 add/update/remove 当前只能以写接口 `success=true` 作为终态证据，并显式返回 `verification.status=terminal_response_only`；成员列表受上限限制，不能被包装成精确读回验证。 + +若写响应丢失，先用 `+member-list --filter-role` 做有限核对；仍无法证明时报告未知效果，不自动重放批量成员写入。 diff --git a/skills/multi/dingtalk-wiki/references/wiki-node-ops.md b/skills/multi/dingtalk-wiki/references/wiki-node-ops.md new file mode 100644 index 00000000..43e48461 --- /dev/null +++ b/skills/multi/dingtalk-wiki/references/wiki-node-ops.md @@ -0,0 +1,45 @@ +# Wiki 节点操作 + +## 创建与内容交接 + +```bash +dws wiki +node-create --workspace --name "新文档" --type adoc --format json +``` + +`--type` 可用 `adoc|axls|able|appt|adraw|amind|folder`，父目录加 `--folder `。创建成功从结果取新 nodeId，并按类型交给 Doc/Sheet/AITable；不要靠同名搜索重新定位。 + +只有空间名称且只创建空 adoc 时用 `+wiki-new-doc --space <名称> --title <标题>`。它会唯一解析空间并验证节点，但不写正文；正文仍切 Doc。 + +## 读取、搜索与列表 + +- 已知 nodeId/URL：`+node-get --node <值>`。 +- 浏览目录：`+node-list --workspace [--folder ]`；全量加 `--page-all`。 +- 关键词检索：`+node-search --workspace --query <词>`；不拿 list 代替 search。 + +## 复制与移动 + +```bash +dws wiki +node-copy --workspace <目标库ID> --node <源nodeId> [--folder <目标folderId>] +dws wiki +move --workspace <目标库ID> --node [--folder <目标folderId>] +dws wiki +move-to-drive --node [--folder <我的文档folderId>] +``` + +- copy 产生新 nodeId，必须读回副本；源 ID 不能当新 ID。 +- move 保持 nodeId，但必须验证目标 workspace/folder。 +- move-to-drive 必须验证 workspace 已改变；workspaceId 不能当普通 folderId。 +- 这些命令按 Runtime confirmation 执行；dry-run 与正式执行使用同一目标。 + +## 删除 + +```bash +dws wiki +node-delete --workspace --node +``` + +删除前读取节点并核对其 workspace；不匹配立即停止。确认后只接受 `success=true`，不因列表暂时未刷新而重复删除。 + +## 恢复原则 + +- create/copy 缺少新 ID：提交效果未知，先按目标库和精确名称定向查询。 +- move 响应异常：按原 nodeId 读回 workspace/folder 决定终态。 +- delete 响应异常：检查节点详情或回收状态；不能盲重放。 +- 读回与请求不一致时返回结构化失败并保留真实目标信息。 diff --git a/skills/multi/dingtalk-wiki/references/wiki.md b/skills/multi/dingtalk-wiki/references/wiki.md index c02e6fec..1daad159 100644 --- a/skills/multi/dingtalk-wiki/references/wiki.md +++ b/skills/multi/dingtalk-wiki/references/wiki.md @@ -1,506 +1,62 @@ -# 知识库 (wiki) 命令参考 +# Wiki 空间、分页与动态参考 -## 查询命令帮助 +只在根 Skill 的 Golden Route 不足时读取相关章节。节点写操作和成员管理分别读取对应 operation reference。 -当你不确定某个命令的具体参数、格式或可选项时，**优先执行 `--help` 查询**，不要猜测参数名或凭记忆编造。 +## 空间定位 + +| 已知条件 | 入口 | +|---|---| +| 精确 workspaceId 或知识库 URL | `+space-get --workspace <值>` | +| 名称且必须得到唯一 ID | `+resolve-space --name <名称>` | +| 关键词且需要浏览候选 | `+space-search --query <关键词>` | +| 明确要列出组织/个人知识库 | `+space-list --type orgWikiSpace|myWikiSpace` | + +`+resolve-space` 返回多候选时停止；不要改用列表第一项。空关键词不能构造 `--query ""`。 + +## Runtime 确认与首次执行 + +- 先唯一解析 workspace、node、目标父节点或成员，再以精确 leaf Schema 和 Runtime gate 判断是否需要确认；不要通过一次缺少 `--yes` 的失败调用探测确认要求。 +- Runtime 要求确认且当前请求已明确授权具体空间/节点/成员、动作、目标位置或角色及影响时，首次正式远端写调用直接追加 `--yes`。只有“整理知识库”“调整成员”等宽泛意图时必须先补齐范围。 +- Runtime 不要求确认时不添加 `--yes`。需要询问时，确认后必须保持同一 profile、对象、动作、范围和关键参数；移动目标、成员列表、角色或其他影响范围变化时重新确认。 +- 只读定位和检查不加 `--yes`。收到 `confirmation_required` 仅表示尚未通过预执行门禁，不代表业务写入成功，也不能据此盲目重放。 + +## 全量分页 + +`+space-list`、`+node-list`、`+feed-list` 支持自动翻页： ```bash -# 查看 wiki 下所有子命令 -dws wiki --help - -# 查看具体命令的完整参数说明 -dws wiki space get --help -dws wiki member add --help - -# 查看子命令组下的所有命令 -dws wiki space --help -dws wiki member --help +dws wiki +space-list --page-all --page-limit 20 --format json +dws wiki +node-list --workspace --page-all --max-items 500 --format json +dws wiki +feed-list --workspace --page-all --format json ``` -规则： -- 参数名不确定时 → 先 `--help`，再调用 -- 报错 "unknown flag" 时 → `--help` 确认正确的 flag 名称 -- 不确定某个功能是否存在时 → `dws wiki --help` 查看命令列表 +- `--page-all` 才启用自动翻页；`--page-limit/--max-items/--page-delay` 不能单独使用。 +- `autoPageComplete=true` 且 endpoint exhausted 才表示端点取完；达到 page/items 上限必须保留 continuation/stop reason。 +- 游标缺失、停滞、循环或后续页失败均不能返回“全部”。 +- `+node-search` 当前保留服务端单页 cursor；需要续页时使用真实 `nextCursor`，不手工猜 token。 -## 命令总览 - -### 创建知识库 -``` -Usage: - dws wiki space create [flags] -Example: - dws wiki space create --name "产品文档库" --format json - dws wiki space create --name "技术方案" --desc "团队技术方案归档" --format json -Flags: - --name string 知识库名称 (必填，不超过 100 字符) - --desc string 知识库描述 (选填，不超过 500 字符) - --icon string 知识库图标标识 (选填) -``` - -### 删除知识库 - -> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。 - -``` -Usage: - dws wiki space delete [flags] -Example: - dws wiki space delete --workspace - dws wiki space delete --workspace "https://alidocs.dingtalk.com/i/spaces/xxx/overview" -Flags: - --workspace string 知识库 ID 或 URL (必填) -``` - -将指定知识库移入回收站。删除后知识库会进入回收站，可在回收站中恢复。 - -> **重要约束**： -> - 操作者必须具备知识库的 OWNER 角色。 -> - 删除操作不可逆（从回收站恢复除外），请确认后再执行。 - -### 查看知识库详情 -``` -Usage: - dws wiki space get [flags] -Example: - dws wiki space get --workspace --format json - dws wiki space get --workspace "https://alidocs.dingtalk.com/i/spaces/xxx/overview" --format json -Flags: - --workspace string 知识库 ID 或 URL (必填) -``` - -支持传入知识库 ID 或知识库 URL，系统自动识别。 -知识库 URL 格式：`https://alidocs.dingtalk.com/i/spaces/{workspaceId}/overview` - -### 列出知识库 -``` -Usage: - dws wiki space list [flags] -Example: - dws wiki space list --format json - dws wiki space list --type myWikiSpace --format json - dws wiki space list --type orgWikiSpace --limit 50 --format json -Flags: - --type string 知识库类型: myWikiSpace / orgWikiSpace (默认 orgWikiSpace) - --limit string 每页数量 1-50 (默认 20) - --cursor string 分页游标 (首页留空) -``` - -- `myWikiSpace`：返回当前用户的「我的文档」个人空间（固定 1 条，不支持分页） -- `orgWikiSpace`（默认）：返回组织内有权访问的知识库列表，支持分页 - -### 搜索知识库 -``` -Usage: - dws wiki space search [flags] -Example: - dws wiki space search --query "产品文档" --format json - dws wiki space search --query "技术方案" --limit 20 --format json - dws wiki space search --type myWikiSpace --format json -Flags: - --query string 搜索关键词 (--type myWikiSpace 时可省略) - --type string 知识库类型: myWikiSpace 时直接返回「我的文档」，省略则搜索组织知识库 - --limit string 返回数量 1-20 (默认 10) -``` - -当 `--type myWikiSpace` 时，忽略 `--query`，直接返回「我的文档」个人空间。 - -### 添加知识库成员（容器级授权） -``` -Usage: - dws wiki member add [flags] -Example: - dws wiki member add --workspace --users uid1 --role READER - dws wiki member add --workspace --users uid1,uid2 --role EDITOR - dws wiki member add --workspace "https://alidocs.dingtalk.com/i/spaces//overview" --users uid1 --role MANAGER -Flags: - --workspace string 目标知识库 ID 或 URL (必填) - --users strings 被加入的用户 userId 列表，逗号分隔 (必填，单次最多 30 个) - --role string 授予的角色 (必填，大小写敏感，必须全大写): MANAGER (管理者) / EDITOR (可编辑) / DOWNLOADER (可下载) / READER (可阅读) -``` - -> **重要约束**： -> - 仅支持 USER 类型。 -> - 角色枚举严格大写：MANAGER / EDITOR / DOWNLOADER / READER（OWNER 不可通过此接口添加，知识库创建者默认为所有者）。 -> - 操作者需具备知识库的 OWNER 或 MANAGER 权限。 -> - 「我的文档」(myWikiSpace) 是个人空间，**不支持容器级成员管理**；后端会直接拒绝。如果你的目标只是把某篇文档分享给别人，请改用 `dws drive permission add` 在节点级别授权。 - -### 移除知识库成员 -``` -Usage: - dws wiki member remove [flags] -Example: - dws wiki member remove --workspace --users uid1 - dws wiki member remove --workspace --users uid1,uid2 -Flags: - --workspace string 目标知识库 ID 或 URL (必填) - --users strings 被移除的用户 userId 列表，逗号分隔 (必填，单次最多 30 个) -``` - -> **重要约束**： -> - OWNER 角色不可通过此接口移除。 -> - 操作者需具备知识库的 OWNER 或 MANAGER 权限。 -> - 移除后相关用户将无法访问该知识库下的内容（除非通过节点级权限另行授权）。 -> - 「我的文档」(myWikiSpace) 是个人空间，**不支持容器级成员管理**。 - -### 修改知识库成员角色 -``` -Usage: - dws wiki member update [flags] -Example: - dws wiki member update --workspace --users uid1 --role EDITOR - dws wiki member update --workspace --users uid1,uid2 --role READER -Flags: - --workspace string 目标知识库 ID 或 URL (必填) - --users strings 目标用户 userId 列表，逗号分隔 (必填，单次最多 30 个) - --role string 新角色 (必填，大小写敏感，必须全大写): MANAGER / EDITOR / DOWNLOADER / READER -``` - -### 列出知识库成员 -``` -Usage: - dws wiki member list [flags] -Example: - dws wiki member list --workspace - dws wiki member list --workspace --limit 100 - dws wiki member list --workspace --filter-role EDITOR -Flags: - --workspace string 目标知识库 ID 或 URL (必填) - --limit int 返回数量上限，最大 200 (默认 50) - --filter-role string 按角色过滤: MANAGER / EDITOR / DOWNLOADER / READER (选填) -``` - -> 接口不支持游标分页，使用 `--limit` 一次性拉取。 - -### 查询知识库动态 -``` -Usage: - dws wiki feed list [flags] -Aliases: - list, ls -Example: - dws wiki feed list --workspace --format json - dws wiki feed list --workspace --limit 10 --format json - dws wiki feed list --workspace --exclude-file --format json - dws wiki feed list --workspace --limit 10 --cursor --format json -Flags: - --workspace string 知识库 ID 或 URL (必填) - --limit int 每页数量 (默认 10，最大 20)。用户未明确要求条数时禁止加此 flag，让服务端走默认 10 - --cursor string 分页游标 (首页留空) - --exclude-file 排除普通文件、媒体文件、文件夹及 Office 文件动态，仅保留在线文档操作 (默认 false) -``` - -查询指定知识库的动态，返回谁在什么时间进行了更新、上传、评论等操作。 -支持传入知识库 ID 或知识库 URL，系统自动识别。 -支持分页，通过 `--cursor` 传入上次返回的 nextToken 获取下一页；出参 `hasMore` 指示是否还有下一页。 - -> **权限要求**：调用者需具备知识库的成员权限，非成员会被拒绝访问。 - -**动态类型 `type` 枚举（严格按此映射展示，禁止猜测）**： - -| type | 含义 | -|------|------| -| 0 | 创建文档 | -| 1 | 更新文档 | -| 2 | 评论文档 | -| 3 | 点赞文档 | -| 4 | 加入团队空间 | -| 5 | 表格选区数据变更 | -| 6 | 更新 office 文件 | -| 7 | 上传普通文件（非媒体文件） | -| 8 | 上传媒体文件（图片/视频） | -| 9 | 上传文件夹 | -| 10 | 上传文件夹 V2 | -| 11 | 加入团队 | -| 12 | 创建知识库 | - -> **重要 — 展示规则（必须严格遵守）**： -> 1. **typeLabel 字段**：CLI 已自动将 `type` 数字映射为 `typeLabel` 中文标签（如 `更新文档`、`创建文档`），**直接使用 `typeLabel` 展示即可**，无需自行查表映射。 -> 2. **timeFormatted 字段**：已是北京时间字符串（格式如 `2026-07-30 08:00`），直接展示即可，无需任何转换。原始毫秒时间戳保存在 `time` 字段中（数字类型）。 - -### 列出知识库节点 -``` -Usage: - dws wiki node list [flags] -Aliases: - list, ls -Example: - dws wiki node list --workspace --format json - dws wiki node list --workspace --folder --format json - dws wiki node list --workspace --limit 20 --cursor --format json -Flags: - --workspace string 知识库 ID (必填) - --folder string 父节点 nodeId (选填，不传则列出根目录) - --limit int 每页数量 (默认 50，最大 50) - --cursor string 分页游标 -``` - -### 在知识库中创建节点 -``` -Usage: - dws wiki node create [flags] -Example: - dws wiki node create --workspace --name "新文档" --format json - dws wiki node create --workspace --name "方案目录" --type folder --format json - dws wiki node create --workspace --name "数据表" --type asheet --folder --format json -Flags: - --workspace string 知识库 ID (必填) - --name string 节点名称 (必填) - --type string 节点类型: adoc / asheet / folder / axls (默认 adoc) - --folder string 父节点 nodeId (选填，不传则在根目录创建) -``` - -### 复制知识库节点 -``` -Usage: - dws wiki node copy [flags] -Example: - dws wiki node copy --workspace --node --format json - dws wiki node copy --workspace --node --folder --format json -Flags: - --workspace string 知识库 ID (必填) - --node string 源节点 ID (必填) - --folder string 目标文件夹 nodeId (选填) -``` - -### 移动知识库节点 -``` -Usage: - dws wiki node move [flags] -Example: - dws wiki node move --workspace --node --folder --format json - dws wiki node move --workspace --node --format json -Flags: - --workspace string 知识库 ID (必填) - --node string 源节点 ID (必填) - --folder string 目标文件夹 nodeId (选填) -``` - -### 删除知识库节点 - -> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。 - -``` -Usage: - dws wiki node delete [flags] -Example: - dws wiki node delete --workspace --node - dws wiki node delete --workspace --node --yes -Flags: - --workspace string 知识库 ID (必填，用于权限校验) - --node string 节点 ID (必填) -``` - -将知识库中的节点移入回收站。权限要求: 对节点有"管理"权限。 - -### 在知识库中搜索节点 -``` -Usage: - dws wiki node search [flags] -Example: - dws wiki node search --workspace --query "方案" --format json - dws wiki node search --workspace --query "周报" --limit 10 --format json - dws wiki node search --workspace --query "设计" --extensions adoc,asheet --format json -Flags: - --workspace string 知识库 ID (必填) - --query string 搜索关键词 (必填) - --extensions string 按文件类型过滤，逗号分隔: adoc,asheet 等 (选填) - --limit int 每页数量 (选填) - --cursor string 分页游标 (选填) -``` - -在指定知识库空间内搜索节点。与 `drive search` 的区别： -- `wiki node search` — 限定在某个知识库空间内搜索（需要 `--workspace`） -- `drive search` — 全局搜索，聚合钉盘 + 文档空间结果 - -### 列出空间（支持钉盘空间类型） - -`wiki space list` 除了支持知识库类型（`orgWikiSpace` / `myWikiSpace`），还支持钉盘空间类型： - -``` -Usage: - dws wiki space list --type orgSpace --format json # 钉盘企业空间 - dws wiki space list --type mySpace --format json # 钉盘「我的文件」 - dws wiki space list --type orgWikiSpace --format json # 知识库（默认） - dws wiki space list --type myWikiSpace --format json # 我的文档 -Flags: - --type string 空间类型: - orgWikiSpace (默认) — 组织知识库 - myWikiSpace — 我的文档个人空间 - orgSpace — 钉盘企业空间 - mySpace — 钉盘「我的文件」 - --limit string 每页数量 1-50 (默认 20) - --cursor string 分页游标 (首页留空) -``` - -> 钉盘空间类型（`orgSpace` / `mySpace`）会自动路由到钉盘 MCP 服务，等同于原 `drive list-spaces`（已 deprecated）。 - -## 意图判断 - -- 用户说"创建知识库/新建知识库" → `space create` -- 用户说"查看知识库/知识库详情" → `space get` -- 用户说"我的知识库/知识库列表/有哪些知识库" → `space list` -- 用户说"列出钉盘空间/钉盘团队空间" → `space list --type orgSpace` -- 用户说"搜索知识库/找知识库" → `space search` -- 用户说"我的文档/个人空间" → `space list --type myWikiSpace` -- 用户说"知识库下的文件/知识库里有哪些文档/浏览知识库内容" → `node list`（需 `--workspace`） -- 用户说"在知识库里搜文档/空间内搜索" → `node search`（需 `--workspace` + `--query`） -- 用户说"在知识库里创建文档/新建文件夹" → `node create`（需 `--workspace` + `--name`） -- 用户说"复制知识库里的文档" → `node copy`（需 `--workspace` + `--node`） -- 用户说"移动知识库里的文档" → `node move`（需 `--workspace` + `--node`） -- 用户说"删除知识库里的文档/节点" → `node delete`（需 `--workspace` + `--node`） -- 用户说"把知识库分享给某人/给某人加入知识库/邀请进知识库" → `member add`（需 `--workspace` + `--user` + `--role`） -- 用户说"修改某人在知识库的权限/调整成员角色" → `member update` -- 用户说"移除知识库成员/把某人从知识库移除/删除知识库成员" → `member remove`（需 `--workspace` + `--users`） -- 用户说"知识库有哪些成员/查看知识库成员" → `member list` -- 用户说"知识库动态/最近有什么更新/谁改了什么/知识库活动" → `feed list`（需 `--workspace`） -- 用户说"知识库最近的评论/更新记录/操作日志" → `feed list`（需 `--workspace`） -- 用户说"删除知识库/移除知识库/把知识库删了" → `space delete`（需 `--workspace`） -- 用户说"排除文件/只看创建文档/只看更新文档/只看文档操作/不要上传文件的记录/过滤掉文件动态/只看文档变更" → `feed list --exclude-file`（**必须带 flag，禁止客户端自行过滤**） - -> **重要 — `--exclude-file` 使用规则**： -> 当用户意图排除文件类动态（上传文件、更新 office 文件等）或只看文档操作时，**必须在命令中带上 `--exclude-file`**，由后端完成过滤。禁止先拉全量数据再用 Python/jq 等工具在客户端过滤，那样既浪费带宽又可能因分页遗漏数据。 - -> **跨产品路由说明**：知识库节点的**内容操作**（读取/编辑/块级操作）仍由 `dws doc` 承担： ->- 用户说"读某个知识库里的某篇文档" → 先 `node list` 拿到 nodeId，再走 **`dws doc read --node `** ->- 用户说"搜文件"（不指定空间） → 走 **`dws drive search`**（全局聚合搜索） - -关键区分（两层模型）： -- **wiki node**（空间管理层：节点的列出/创建/复制/移动/删除/搜索）vs **doc**（内容层：读写/编辑/块级/评论/导出）vs **drive**（存储层：文件上传/下载/搜索/权限，不关心格式） -- **wiki node search**（空间内搜索，需 `--workspace`）vs **drive search**（全局搜索，聚合钉盘+文档空间） -- **wiki node create**（在空间中创建空文件实体）vs **doc create**（创建文档并写入内容） -- **wiki member**（容器级，授权整个知识库）vs **doc permission / drive permission**（节点级，授权单篇文档） - - 「我的文档」**只能用** `doc permission` / `drive permission`，不能用 `wiki member` -- **wiki space list --type orgSpace/mySpace**（列出钉盘空间）vs **wiki space list**（默认列出知识库） - -## 核心工作流 +## 空间创建与删除 ```bash -# 列出我有权访问的组织知识库 -dws wiki space list --format json - -# 获取「我的文档」个人空间 -dws wiki space list --type myWikiSpace --format json - -# 搜索知识库 -dws wiki space search --query "产品" --format json - -# 创建知识库 -dws wiki space create --name "新项目文档" --desc "项目相关文档归档" --format json - -# 查看知识库详情 -dws wiki space get --workspace --format json - -# ── 工作流: 浏览知识库内容 ── - -# 1. 获取知识库 ID -dws wiki space list --format json - -# 2. 列出根目录节点 -dws wiki node list --workspace --format json - -# 3. 进入子目录 -dws wiki node list --workspace --folder --format json - -# 4. 读取文档内容（跨到 doc） -dws doc read --node --format json - -# ── 工作流: 在知识库中创建文档 ── - -# 1. 创建文档节点 -dws wiki node create --workspace --name "新方案" --format json - -# 2. 创建文件夹 -dws wiki node create --workspace --name "方案归档" --type folder --format json - -# 3. 在指定文件夹下创建 -dws wiki node create --workspace --name "子文档" --folder --format json - -# ── 工作流: 在知识库中搜索 ── - -# 在指定知识库内搜索 -dws wiki node search --workspace --query "方案" --format json - -# 按文件类型过滤 -dws wiki node search --workspace --query "周报" --extensions adoc --format json - -# ── 工作流: 列出钉盘空间 ── - -# 列出钉盘企业空间 -dws wiki space list --type orgSpace --format json - -# 获取钉盘「我的文件」 -dws wiki space list --type mySpace --format json - -# ── 工作流: 复制/移动节点 ── - -# 复制节点到另一个文件夹 -dws wiki node copy --workspace --node --folder --format json - -# 移动节点到另一个文件夹 -dws wiki node move --workspace --node --folder --format json - -# ── 工作流: 删除知识库节点 ── - -# 删除节点（会要求确认） -dws wiki node delete --workspace --node - -# ── 工作流: 查询知识库动态 ── - -# 1. 获取知识库 ID -dws wiki space list --format json - -# 2. 查询知识库动态 -dws wiki feed list --workspace --format json - -# 3. 排除文件动态，只看文档操作 -dws wiki feed list --workspace --exclude-file --format json - -# 4. 翻页（cursor 取上一页返回的 nextToken） -dws wiki feed list --workspace --cursor --format json - -# ── 工作流: 给知识库加成员 ── - -# 1. 先确认知识库 ID（避免授权到「我的文档」） -dws wiki space list --format json # 注意：不要 --type myWikiSpace - -# 2. 添加成员 -dws wiki member add --workspace --users --role EDITOR --format json - -# 3. 查看当前成员 -dws wiki member list --workspace --format json - -# ── 工作流: 移除知识库成员 ── - -# 1. 查看当前成员 -dws wiki member list --workspace --format json - -# 2. 移除成员 -dws wiki member remove --workspace --users --format json - -# ── 工作流: 删除知识库 ── - -# 1. 确认知识库信息 -dws wiki space get --workspace --format json - -# 2. 删除知识库 -dws wiki space delete --workspace --format json +dws wiki +space-create --name "产品文档库" --desc "团队资料" --format json +dws wiki +delete-space --workspace --format json ``` -## 上下文传递表 +- 名称最多 32 字符，描述最多 500 字符；本地校验失败不能产生远端调用。 +- 创建必须返回 workspaceId，并通过 `get_wikiSpace` 读回同一 ID。 +- 删除整个知识库前先读取目标，经 Runtime 确认后只接受 `success=true`。 -| 操作 | 从返回中提取 | 用于 | -|------|-------------|------| -| `space create` | `workspaceId` | node list / member add 的 --workspace | -| `space list` | `workspaceId` | node list / member add 的 --workspace | -| `space search` | `workspaceId` | node list / member add 的 --workspace | -| `space get` | `spaceUrl` | 分享给用户 | -| `node list` | `nodeId` | node copy/move/delete 的 --node / `dws doc read` 的 --node | -| `node search` | `nodeId` | node copy/move/delete 的 --node / `dws doc read` 的 --node | -| `node create` | `nodeId` | node copy/move/delete 的 --node / `dws doc read` 的 --node | -| `feed list` | `nextToken` | feed list 的 --cursor（翻页，`hasMore` 为 true 时继续）| -| `member list` | `userId` | member update 的 --users / member remove 的 --users | +## 知识库动态 -## 相关产品 +```bash +dws wiki +feed-list --workspace --limit 20 --format json +``` -- [doc](../../dingtalk-doc/references/doc.md) — 内容层：文档读写/编辑/块级操作/评论/导出（仅对自研文档有意义） -- [drive](../../dingtalk-drive/references/drive.md) — 存储层：文件列出/搜索/上传/下载/复制/移动/重命名/删除/权限（不关心文件格式） +动态用于回答“谁在何时创建、更新或评论了什么”。需要排除普通文件时加 `--exclude-file`；需要完整范围时加 `--page-all`。节点正文或历史版本不从 feed 推断，锁定 nodeId 后切 Doc。 + +## 响应与错误 + +- 空响应、`success=false`、畸形 wrapper、缺失业务数组都属于失败，不是零条数据。 +- 集合结果检查 `count` 与对应 `spaces/nodes/feeds`；分页检查 `nextCursor/hasMore` 及 meta.pagination。 +- 读写始终保持同一 profile。权限失败不能通过切换账号或退回 Drive 猜测解决。 +- 写入提交后连接中断时先用返回/已知 ID 读取；无法证明是否提交则报告未知效果，不自动重试非幂等创建。 From cfbe5b9b0d21871c76b39d308cf463bcb832b4af Mon Sep 17 00:00:00 2001 From: Dennis Date: Tue, 18 Aug 2026 09:54:21 +0800 Subject: [PATCH 200/250] docs: remove calendar todo shortcut review --- ...alendar-todo-shortcut-business-review.html | 82 ------------------- 1 file changed, 82 deletions(-) delete mode 100644 docs/calendar-todo-shortcut-business-review.html diff --git a/docs/calendar-todo-shortcut-business-review.html b/docs/calendar-todo-shortcut-business-review.html deleted file mode 100644 index 5f844b2f..00000000 --- a/docs/calendar-todo-shortcut-business-review.html +++ /dev/null @@ -1,82 +0,0 @@ - - - - - - - Calendar × Todo Shortcut 全景评审 - - - -
-

Business Review · Calendar × Todo

Shortcut
一次性全景交付

以 lark-cli 用户任务为基线，逐项补齐 Calendar 与 Todo；同时把缺字段、错类型、坏元素、分页停滞和未读回写入全部从“看似成功”改为失败关闭。

真实账号 E2E：44 PASS / 3 BLOCKED / 0 FAIL47 个公开主入口Shortcut 主体 · Skill 仅生成索引已移除 PII / 凭证 / 业务正文
-
27Calendar 公开 Shortcut
20Todo 公开 Shortcut
10 + 17lark-cli 1.0.87 基线逐项审查
100%公开叶子 Result / Safety 声明
-
- - - -
-

Executive summary

能力增加，但成功条件更窄、更可信

基线为本机最新 lark-cli 1.0.87；代码基于独立 worktree 的 104eb715 开发。报告只描述 shortcut、runtime contract、测试和平台边界。

-
结论：Calendar 形成 27 个公开入口，Todo 形成 20 个公开入口；44 个入口使用真实组织数据完整执行通过。剩余 3 个 Calendar 入口没有被伪装为 PASS：会议室可用性与 RSVP 收到稳定上游拒绝码，会议室名称搜索缺少可安全证明“已知非空”的 fixture。
-
Calendar scorecard
27公开主入口；另保留 2 个非公开 deprecated 兼容名
24exact shortcut 真实数据 PASS
3fixture / tenant 受限，明确 BLOCKED
18超过 lark-cli 同名基线的额外任务入口
-
Todo scorecard
20公开主入口；兼容名不重复计数
20exact shortcut 真实数据全部 PASS
0公开入口 FAIL / BLOCKED
10超过 lark-cli 同名基线的额外任务入口
-
- -

Golden routes & ownership

按用户任务组织，而不是按 API 数量组织

Calendar 与 Todo 可以在工作流中相邻，但资源所有权不同：日程中的 action item 不会自动变为 Todo，Todo 的截止时间也不会伪装为日历占用。

-
09

日程发现

日/周视图、下一场、搜索、详情、冲突与空档；完整分页或明确 continuation。

+agenda · +today · +search-event · +conflicts
08

日程协作

创建、更新、邀请、RSVP、取消和重排；写后绑定同一 eventId。

+create · +book · +invite · +reschedule
06

闲忙与会议室

个人/多人闲忙、共同建议、房间分组、名称定位和时间可用性。

+freebusy · +suggest-time · +room-find
04

日历本与参会人

日历本发现、名称搜索和参会人可见状态；不伪造后端未返回的身份字段。

+book-list · +book-search · +attendee-list
-
08

Todo 生命周期

创建、详情、更新、完成、重开、按标题唯一完成和子任务读取。

+create · +get · +update · +complete
06

Todo 发现

与我相关、我创建、今日到期、逾期和全分页搜索，拒绝 Top-N 冒充全量。

+get-my-tasks · +search · +overdue
04

协作与内容

单人/多人指派、评论、附件/评论列表，稳定对象读回。

+assign · +assign-multi · +comment
02

提醒

规则写入与“创建给自己的提醒任务”分开；不可读回的规则明确 terminal-only。

+reminder · +remind
-
边界：calendar 管理时间占用、参会人和会议室；todo 管理任务状态、协作者和截止时间。跨产品站会摘要属于上层 workflow，本次没有扩展任何 Skill 逻辑；仅按仓库强制生成规则同步公开 shortcut 的计数和清单。
-
- -

Lark alignment

27 个 lark-cli 任务逐项判定

“覆盖”要求业务语义与证据链成立，不以同名为充分条件；“不可对齐”必须有底层能力或兼容性原因。

-
Calendar：10 项基线

7 · 真实 PASS

agenda、create、freebusy、get、search-event、suggestion、update。

2 · 已实现但 BLOCKED

room-find 在当前租户被上游拒绝；rsvp 缺少安全可控的受邀参与者 fixture。

1 · 平台缺口

meeting 需要日程到视频会议/会议纪要的稳定关联，当前 DingTalk 下层没有等价接口。

- -
Lark 任务DWS 主入口结论差异与证据
+agendacalendar +agenda覆盖严格 events 数组与 cursor；真实已知非空和合法空均验证。
+createcalendar +create超过eventId、时间与标题精确详情读回；异常创建不能以 request echo 成功。
+freebusycalendar +freebusy覆盖用户/会议室目标约束，busy 段严格投影。
+getcalendar +get覆盖对象必须存在并绑定请求 eventId。
+meeting无等价不可对齐缺少 event→VC / 纪要稳定关联；不以标题搜索猜测。
+room-findcalendar +room-findBLOCKED单时段/group/name/page 已实现；真实租户返回稳定上游拒绝码。也不具备 Lark 的城市、楼宇、楼层、容量、多时段与循环过滤。
+rsvpcalendar +rsvpBLOCKED响应动作与终态读回已实现；组织者自测不是合法受邀参与者，真实调用被上游拒绝。
+search-eventcalendar +search-event有限对齐当前服务只支持页内标题/描述/地点过滤并公开 continuation；不会把单页零命中宣称为全局无结果。
+suggestioncalendar +suggestion覆盖显式 recommendEventTimes 数组；缺失字段与空数组严格区分。
+updatecalendar +update超过字段与参会人分阶段更新，输出非事务步骤账本，逐项读回。
- -
Todo：17 项基线

9 · 覆盖

comment、complete、create、get-my-tasks、get-related-tasks、reminder、reopen、search、update。

1 · 兼容性部分对齐

DWS 历史 +assign 是“按姓名创建并指派”，不能静默改成修改既有任务协作者。

7 · 下层缺口 / 安全路由

followers、set-ancestor、4 项 tasklist 与 upload-attachment shortcut。

- -
Lark 任务DWS 主入口结论差异与证据
+assigntodo +assign部分保留“姓名解析→创建并指派”已发布语义；既有任务协作者变更没有同名假对齐。
+commenttodo +comment超过写回本身无 commentId；通过写前/写后完整评论集合差异，精确锁定唯一新 commentId 和正文。
+completetodo +complete超过幂等预读，必要时写入，最终 isDone=true 精确读回。
+createtodo +create超过稳定 taskId 与 todoDetailModel 标题读回。
+followers无等价不可对齐DingTalk Todo 下层没有 follower 管理原语，不能用 executor/participant 替代。
+get-my-taskstodo +get-my-tasks覆盖todoCards + page/size/hasMore 严格校验，支持有界全量分页。
+get-related-taskstodo +get-related-tasks超过三种角色全分页合并并按 taskId 去重；旧 +related-tasks 仅兼容。
+remindertodo +reminder终态覆盖上游不支持提醒规则读回，只接受 success=true 终态，并固定 verified=false。
+reopentodo +reopen超过幂等预读与 isDone=false 读回。
+searchtodo +search超过遍历全部分页后按标题筛选；页上限未耗尽时非零失败。
+set-ancestor无等价不可对齐下层无任务 reparent / clear ancestor 原语。
+tasklist-create无等价不可对齐当前 Todo 对象模型无任务清单创建能力。
+tasklist-members无等价不可对齐无 tasklist member 读写接口。
+tasklist-search无等价不可对齐无 tasklist 目录/检索接口。
+tasklist-task-add无等价不可对齐无将任务加入清单的下层原语。
+updatetodo +update超过只更新显式字段，并按同一 taskId 逐字段读回。
+upload-attachmenttodo task add-attachmentShortcut 不可用原子上传事务真实 PASS；Shortcut runtime 不能安全复用上传凭证/OSS PUT，注册为 unavailable 而非复制敏感事务。
-
- -

Beyond parity

DWS 可主推的额外场景

超过 Lark 的视角主要来自组合任务、正确性和钉钉对象模型，不来自制造同义命令。

自然人协作链

+book、+invite、+free、+suggest-time 先唯一解析姓名，再绑定同一事件或时间窗。

ambiguous / zero target fail closed

个人日程视图

+today、+tomorrow、+week、+next-event 提供可直接消费的时间视图。

dynamic timezone-aware ranges

空档与冲突

+conflicts、+free-slots、+my-free 在完整日程页上计算，而非只看首屏。

bounded full pagination

日历本发现

+book-list、+book-search 严格区分协议错误和零命中。

stable calendarId projection

多角色任务视图

+get-related-tasks、+created-todos 合并角色分页并去重。

creator / executor / participant

时间驱动 Todo

+due-today 与 +overdue 使用本地日历日和当前时间，避免固定日期示例过期。

runtime date windows

自然标题完成

+todo-done 跨全部分页唯一定位标题；多命中不猜测。

exact target before write

现有内容读取

+list-sub、+list-comment、+list-attachment 将隐藏读取面升级为严格公开入口。

explicit collection + stable ID
- -

Hidden failures fixed

这次真正修掉的“假成功”

问题来自真实 wire shape、分页和写后证据；mock 成功或空环境不能发现这些风险。

- -
原问题错误风险修复与回归
缺失集合、错型集合或坏元素被投影为 []内部报错/协议漂移被误报为“无日程/无任务”。失败关闭 只有成功 envelope 内显式存在且类型正确的空数组才是合法空。
Calendar 事件列表真实字段是 result.events，稳定键是 id容错 projector 可能静默丢失真实事件。严格读取 wrapper，并将 id 规范化为 eventId。
Todo 列表真实字段是 todoCards，详情嵌套在 todoDetailModel错误 wrapper 使真实任务看似空结果或读回错对象。列表/详情分别建立严格 parser，详情必须绑定请求 taskId。
hasMore=true 时缺 cursor、重复 cursor 或只读首屏Top-N 被宣称为全量；空页可能提前结束。自动分页要求 token 前进；停滞、缺证据、超页上限均非零失败。
Calendar 删除后对象仍可读仅以“还能 get”判定删除失败，或仅凭 ack 判定成功。精确接受 absence 或同 eventId 的 cancelled/canceled/deleted tombstone，拒绝活动对象。
Todo 评论写回返回 result:{}从空 ack 伪造 commentId，或把请求正文当读回。完整读取写前/写后评论，要求唯一新增 ID 且正文精确一致。
Calendar attendee 真实项不含稳定 userId把 displayName 当 ID，发布无法兑现的身份合同。只投影 displayName、responseStatus、self；自身邀请通过当前 profile 与 self=true 绑定。
Calendar smart 写命令只看 ack 或 request echo创建、邀请、重排、取消的远端效果未知仍返回 0。create/update/invite 精确读回；cancel 验证 tombstone/absence；book 邀请失败时回滚并验证缺席。
Todo reminder 没有规则读回接口把 terminal success 伪装成 verified readback。结果固定标注 terminalReceipt=true、verified=false，报告公开边界。
live 清理最初遗漏子任务 ID能力全绿但测试数据仍残留。子任务进入反向清理账本；最终全量 marker 审计作为独立发布门，真实结果零残留。
- -

Truthful execution

空结果与写成功的统一判定

这套合同同时落在 runtime、Result/Pagination 声明、负向回归和 live E2E，不只是报告规则。

读取 / 分页

1
外层与业务层都成功非零退出、success=false、空 body、malformed JSON 立即失败。
2
预期字段显式存在缺集合、null、非数组、坏 item 都不是合法空。
3
分页证据完整hasMore 必须配非空且前进的 token；上限未耗尽必须 incomplete/nonzero。
4
零命中与已知非空都验证只在空环境跑一次不能证明 projector 正确。

写入 / 读回

1
确认前零调用用户确认驱动 Runtime gate；存储示例不带 --yes。
2
明确终态与稳定 ID空 ack、无异常、request echo 均不是创建成功证据。
3
绑定同一对象读回ID、目标父级和关键字段必须与请求一致。
4
不可读回时降低声明明确 terminal-only / verified=false；不从截断列表或同名对象推断。
- -

Complete public catalog

47 个公开主入口与 live 状态

兼容名 calendar +find-room、calendar +respond-event、todo +related-tasks 不重复计为主能力；unavailable 的 upload shortcut 也不计入公开 20 项。

47 / 47
-
- - -
产品Shortcut用户任务 / 严格证据风险真实 E2E
Calendar+agenda范围日程；events + cursor 严格完整。READPASS
Calendar+attendee-list参会人可见信息；displayName/status/self，缺失稳定 ID 不伪造。READPASS
Calendar+book按姓名创建并邀请；详情读回，邀请失败回滚并验缺席。WRITE · CONFIRMPASS
Calendar+book-list日历本列表；显式 calendars 与稳定 calendarId。READPASS
Calendar+book-search按名称搜索日历本；已知非空 fixture。READPASS
Calendar+cancel-event取消日程；预读、确认、tombstone/absence 终态。HIGH · CONFIRMPASS
Calendar+conflicts完整页分析重叠日程并输出冲突对。READ · SMARTPASS
Calendar+create创建日程；eventId、时间、标题详情读回。WRITE · CONFIRMPASS
Calendar+free姓名解析后查参与者闲忙。READ · SMARTPASS
Calendar+free-slots工作时段空档；完整事件页、时长过滤。READ · SMARTPASS
Calendar+freebusy用户/房间闲忙；严格 busy 段和目标约束。READPASS
Calendar+get按 eventId 获取同一对象。READPASS
Calendar+invite姓名唯一解析后邀请；参会人读回。WRITE · CONFIRMPASS
Calendar+my-free当前用户在区间内是否空闲。READ · SMARTPASS
Calendar+next-event完整未来窗口定位最近下一场。READ · SMARTPASS
Calendar+reschedule重排同一事件；完整起止时间读回。WRITE · CONFIRMPASS
Calendar+room-find指定时段可用会议室；实现完成，当前租户稳定上游拒绝。READBLOCKED
Calendar+room-groups会议室分组；真实字段 groupList 严格投影。READPASS
Calendar+room-search名称定位而非可用性；合法零命中，缺安全已知非空 fixture。READBLOCKED
Calendar+rsvp受邀人响应与终态读回；自组织 fixture 被上游拒绝。WRITE · CONFIRMBLOCKED
Calendar+search-event页内条件搜索并保留 continuation，不谎报全局零命中。READPASS
Calendar+suggest-time姓名解析后查共同建议时段。READ · SMARTPASS
Calendar+suggestion按 ID 查询建议时段；显式数组。READPASS
Calendar+today时区感知的今日日程完整视图。READ · SMARTPASS
Calendar+tomorrow时区感知的明日日程完整视图。READ · SMARTPASS
Calendar+update字段/参会人分阶段更新与精确读回。WRITE · CONFIRMPASS
Calendar+week本周日程按日期整理，完整分页。READ · SMARTPASS
Todo+assign按姓名创建并指派单人任务；稳定 taskId 读回。WRITE · CONFIRMPASS
Todo+assign-multi全部姓名唯一解析后只创建一次。WRITE · CONFIRMPASS
Todo+comment写前/写后评论差分，唯一 commentId 与正文读回。WRITE · CONFIRMPASS
Todo+complete幂等完成并读回 isDone=true。WRITE · CONFIRMPASS
Todo+create创建并按 taskId 读回标题。WRITE · CONFIRMPASS
Todo+created-todos创建者角色全分页。READ · SMARTPASS
Todo+due-today本地日历日截止窗口，全分页命中 fixture。READ · SMARTPASS
Todo+gettodoDetailModel 必须绑定请求 taskId。READPASS
Todo+get-my-taskstodoCards 与 page/size/hasMore 完整。READPASS
Todo+get-related-tasks三角色全分页去重。READ · SMARTPASS
Todo+list-attachment显式 attachments 与稳定附件 ID；真实上传后读取。READPASS
Todo+list-comment显式 comments 与稳定 commentId。READPASS
Todo+list-sub显式 subTasks 与稳定 taskId。READPASS
Todo+overdue执行者角色全分页后按当前时间筛选。READ · SMARTPASS
Todo+remind解析当前用户后创建给自己的提醒任务。WRITE · CONFIRMPASS
Todo+reminder提醒规则终态 success；明确 verified=false。WRITE · CONFIRMPASS
Todo+reopen幂等重开并读回 isDone=false。WRITE · CONFIRMPASS
Todo+search全分页标题搜索；已知非空与合法零命中。READ · SMARTPASS
Todo+todo-done跨全部分页按标题唯一定位并完成。WRITE · CONFIRMPASS
Todo+update只改显式字段，同 taskId 逐字段读回。WRITE · CONFIRMPASS
-
- -

Live evidence

真实数据矩阵：44 PASS / 3 BLOCKED / 0 FAIL

每个公开主入口都 exact 执行；raw 原始 JSON 只在内存解析，终端与报告只保留能力标签、聚合计数和稳定原因类别。

24 / 27

Calendar exact shortcut PASS：创建→读回→搜索/视图→更新/邀请→取消终态等完整链。

20 / 20

Todo exact shortcut PASS：生命周期、角色视图、评论、附件、提醒、子任务和清理。

3

BLOCKED：room-find 上游拒绝、room-search 缺安全非空 fixture、rsvp 缺安全受邀 fixture。

0

FAIL；最终资源审计 PASS，当前随机 marker 的活动 Calendar/Todo 残留均为零。

-
BLOCKED 不是 PASS：+room-search 的合法空数组只证明“零命中语义正确”，没有证明真实非空投影；+room-find 与 +rsvp 实际调用了 exact shortcut，但当前安全 fixture/租户收到上游拒绝。三项实现和确定性负向回归已完成，发布状态保留真实限制。
-

Calendar 实际断言

  • 未来 RFC3339 + 显式时区，start<end，读回时间一致。
  • create/get/agenda/search/update/cancel 全部绑定同一 eventId。
  • 分页、busy、suggestion、attendees 的坏元素均非零失败。
  • 取消接受真实 tombstone；book 回滚后验证对象缺席。

Todo 实际断言

  • create/get/list/update/complete/reopen/delete 全部绑定同一 taskId。
  • 子任务、评论、附件均在真实父任务中创建并读取。
  • all-page 角色视图、今日、逾期和搜索命中已知 fixture。
  • 清理按子→父反向执行，最后再次搜索确认零残留。
-
- -

Release gates

工程、范围与脱敏门

报告不保存 profile、组织、成员、日历/事件/任务/评论/附件/会议室 ID、URL、标题正文、精确真实日程、trace、token 或本地绝对路径。

门结果说明
Build / focused testsPASSCalendar、Todo、smart 严格回归与跨平台覆盖通过。
Schema assembly / catalog / driftPASS27 products / 1139 tools；组装 deterministic，生成漂移为零。
Result / Safety coveragePASSCalendar 27 与 Todo 21 个 Schema shortcut leaves 均有 Result/Safety；Todo 计入 1 个 hidden unavailable。
Runtime confirmation truthPASS声明与真实确认 gate 同源；写能力未以元数据绕过确认。
Agent examplesPASS1405 个示例合同门通过；未向存储示例注入 --yes。
Full Go suitePASSDWS_PACKAGE_VERSION=0.0.0-test go test ./...。
Live exact E2EPASS44 capability PASS / 3 disclosed BLOCKED / 0 FAIL；cleanup audit PASS。
ScopePASS业务实现限定为 Shortcut；Skill 手写逻辑零改动，仅同步 3 个强制生成的发现区块。
PII / secret / history scanPASS最终树与提交差异只含脱敏工程事实，无 live 原始日志。
-
REVIEW 01

接受诚实的 3 个 BLOCKED

是否同意在没有安全 fixture/租户权限时保留明确原因，而不以 mock 或空数组提升为 PASS。

REVIEW 02

保持 assign 兼容

是否同意不破坏 DWS 历史“创建并指派”语义；未来如增加协作者管理，应使用新命令名。

REVIEW 03

上传保留原子路由

是否同意在 shortcut runtime 尚不能复用安全上传事务时维持 unavailable，避免复制凭证链。

-
-
DWS Calendar × Todo Shortcut business review · 2026-08-17 · sanitized engineering artifact
-
- - - From 33d8cd7e36319b70c8938a73f9d034afd49409bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 10:08:01 +0800 Subject: [PATCH 201/250] docs(skills): clarify drive copy routing --- skills/multi/dingtalk-drive/references/drive.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index ca7d1d6c..9b51c551 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -81,7 +81,7 @@ dws drive +publish-unset --node ## 快捷方式节点 -`+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接；需要独立副本使用 `+copy`。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。 +`+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接。在线文档节点需要保留版式的独立副本时使用 `+copy`；普通钉盘文件的独立副本必须经用户授权后走 download→upload，因为当前 `+copy` 会拒绝普通文件。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。 ## 错误恢复 From 721a40b05e3d4c60180866e74eee3ebfae0df43b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Tue, 18 Aug 2026 10:41:21 +0800 Subject: [PATCH 202/250] fix(oa): declare attachment result contracts - add success and failure outcomes for three attachment commands - define business data schemas and mark downloadUri as sensitive - migrate attachment commands to unified result output - verify compact and full Schema result projections - cover success, malformed response, and tool error paths to #666 --- .../app/schema_oa_attachment_contract_test.go | 75 ++++++++++++- internal/helpers/oa.go | 75 +++++++++---- internal/helpers/oa_attachment_test.go | 106 +++++++++++++++++- 3 files changed, 225 insertions(+), 31 deletions(-) diff --git a/internal/app/schema_oa_attachment_contract_test.go b/internal/app/schema_oa_attachment_contract_test.go index 82d48f04..75d40694 100644 --- a/internal/app/schema_oa_attachment_contract_test.go +++ b/internal/app/schema_oa_attachment_contract_test.go @@ -6,17 +6,21 @@ package app import ( "bytes" "encoding/json" + "reflect" "strings" "testing" ) func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t *testing.T) { tests := []struct { - cliPath string - canonical string - rpc string - description string - effect string + cliPath string + canonical string + rpc string + description string + effect string + resultType string + resultFields map[string]string + sensitivePaths []string }{ { cliPath: "oa approval attachment download-url", @@ -24,6 +28,12 @@ func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t rpc: "get_attachment_download_url", description: "获取审批附件下载授权并生成临时下载链接", effect: "read", + resultType: "object", + resultFields: map[string]string{ + "spaceId": "integer", "agentId": "integer", "downloadUri": "string", + "class": "string", "fileId": "string", + }, + sensitivePaths: []string{"downloadUri"}, }, { cliPath: "oa approval attachment authorize-download", @@ -31,6 +41,7 @@ func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t rpc: "auth_download_file", description: "批量授权当前用户下载指定的审批钉盘文件", effect: "write", + resultType: "boolean", }, { cliPath: "oa approval attachment authorize-preview", @@ -38,12 +49,16 @@ func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t rpc: "auth_preview_attachment", description: "批量授权当前用户预览审批单中的附件", effect: "write", + resultType: "object", + resultFields: map[string]string{ + "spaceId": "integer", "agentId": "integer", "class": "string", + }, }, } - root := NewRootCommand() for _, test := range tests { t.Run(test.rpc, func(t *testing.T) { + root := NewRootCommand() command := exactCommandForTest(root, test.cliPath) if command == nil { t.Fatalf("executable command %q is missing", test.cliPath) @@ -95,9 +110,57 @@ func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t if got := schemaContractString(tool["idempotency"]); got != "idempotent" { t.Fatalf("idempotency = %q, want idempotent", got) } + fullResult := oaAttachmentResultContract(t, tool, test.resultType, test.resultFields, test.sensitivePaths) + + stdout.Reset() + stderr.Reset() + root.SetArgs([]string{"schema", test.cliPath, "--compact", "--format", "json"}) + if err := root.Execute(); err != nil { + t.Fatalf("execute compact delivery schema leaf: %v; stderr=%s", err, stderr.String()) + } + var compactTool map[string]any + if err := json.Unmarshal(stdout.Bytes(), &compactTool); err != nil { + t.Fatalf("decode compact delivery schema leaf: %v", err) + } + compactResult, ok := compactTool["result"].(map[string]any) + if !ok { + t.Fatalf("compact result = %#v, want object", compactTool["result"]) + } + if !reflect.DeepEqual(compactResult, fullResult) { + t.Fatalf("compact/full result projection differs\ncompact: %#v\nfull: %#v", compactResult, fullResult) + } if problem := schemaHelpFlagCompletenessProblem(test.canonical, test.cliPath, command, tool); problem != "" { t.Fatal(problem) } }) } } + +func oaAttachmentResultContract(t *testing.T, tool map[string]any, resultType string, fields map[string]string, sensitivePaths []string) map[string]any { + t.Helper() + result, ok := tool["result"].(map[string]any) + if !ok { + t.Fatalf("full result = %#v, want object", tool["result"]) + } + if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !reflect.DeepEqual(got, want) { + t.Fatalf("result.outcomes = %#v, want %#v", got, want) + } + if got := schemaContractStringSlice(result["sensitive_paths"]); !reflect.DeepEqual(got, sensitivePaths) { + t.Fatalf("result.sensitive_paths = %#v, want %#v", got, sensitivePaths) + } + dataSchema, ok := result["data_schema"].(map[string]any) + if !ok || schemaContractString(dataSchema["type"]) != resultType { + t.Fatalf("result.data_schema = %#v, want type %q", result["data_schema"], resultType) + } + properties, _ := dataSchema["properties"].(map[string]any) + if len(properties) != len(fields) { + t.Fatalf("result.data_schema.properties = %#v, want fields %#v", properties, fields) + } + for name, fieldType := range fields { + property, ok := properties[name].(map[string]any) + if !ok || schemaContractString(property["type"]) != fieldType { + t.Fatalf("result.data_schema.properties.%s = %#v, want type %q", name, properties[name], fieldType) + } + } + return result +} diff --git a/internal/helpers/oa.go b/internal/helpers/oa.go index 68a73ae0..8dfe47b5 100644 --- a/internal/helpers/oa.go +++ b/internal/helpers/oa.go @@ -12,6 +12,8 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/spf13/cobra" ) @@ -122,6 +124,22 @@ func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error { return nil } +func callOAAttachmentResult(cmd *cobra.Command, tool string, args map[string]any) (output.CommandResult, error) { + data, err := CallMCPToolDataOnServer(cmd.Context(), "oa", tool, args) + if err != nil { + return nil, err + } + response, ok := data.(map[string]any) + if !ok { + return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值不是 JSON 对象", tool)) + } + result, ok := response["result"] + if !ok { + return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值缺少 result", tool)) + } + return output.Success(result), nil +} + func newOAAttachmentCommand() *cobra.Command { attachmentCmd := &cobra.Command{ Use: "attachment", @@ -130,15 +148,13 @@ func newOAAttachmentCommand() *cobra.Command { } downloadURLCmd := NewLeafCommand(LeafSpec{ - Use: "download-url", - Short: "获取审批附件下载链接", - Example: " dws oa approval attachment download-url --instance-id --file-id ", - Server: "oa", - Tool: "get_attachment_download_url", - Call: func(_ *cobra.Command, tool string, args map[string]any) error { - jsonOutput := strings.EqualFold(strings.TrimSpace(deps.Caller.Format()), "json") - return callMCPToolInternalOpts("oa", tool, args, jsonOutput) - }, + Use: "download-url", + Short: "获取审批附件下载链接", + Example: " dws oa approval attachment download-url --instance-id --file-id ", + Server: "oa", + Tool: "get_attachment_download_url", + OutputRollout: output.RolloutUnifiedActive, + ResultCall: callOAAttachmentResult, Flags: []LeafFlag{ {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, {Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true}, @@ -157,6 +173,11 @@ func newOAAttachmentCommand() *cobra.Command { PrimaryCLIPath: "oa approval attachment download-url", }, Description: "获取审批附件下载授权并生成临时下载链接", + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"object","description":"审批附件临时下载信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"downloadUri":{"type":"string","description":"带临时授权签名的附件下载链接"},"class":{"type":"string","description":"服务端响应类型标识"},"fileId":{"type":"string","description":"审批附件文件 ID"}},"required":["spaceId","agentId","downloadUri","fileId"],"additionalProperties":true}`), + SensitivePaths: []string{"downloadUri"}, + }, Interface: &contract.InterfaceSpec{ Mode: "mcp", Availability: "available", @@ -180,12 +201,14 @@ func newOAAttachmentCommand() *cobra.Command { }) authorizeDownloadCmd := NewLeafCommand(LeafSpec{ - Use: "authorize-download", - Short: "授权当前用户下载审批钉盘文件", - Long: "批量授权当前用户下载指定的审批钉盘文件。", - Example: ` dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`, - Server: "oa", - Tool: "auth_download_file", + Use: "authorize-download", + Short: "授权当前用户下载审批钉盘文件", + Long: "批量授权当前用户下载指定的审批钉盘文件。", + Example: ` dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`, + Server: "oa", + Tool: "auth_download_file", + OutputRollout: output.RolloutUnifiedActive, + ResultCall: callOAAttachmentResult, Flags: []LeafFlag{ { Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)", @@ -213,6 +236,10 @@ func newOAAttachmentCommand() *cobra.Command { PrimaryCLIPath: "oa approval attachment authorize-download", }, Description: "批量授权当前用户下载指定的审批钉盘文件", + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"boolean","description":"是否成功为当前用户授予审批钉盘文件下载权限"}`), + }, Interface: &contract.InterfaceSpec{ Mode: "mcp", Availability: "available", @@ -234,12 +261,14 @@ func newOAAttachmentCommand() *cobra.Command { }) authorizePreviewCmd := NewLeafCommand(LeafSpec{ - Use: "authorize-preview", - Short: "授权当前用户预览审批附件", - Long: "批量授权当前用户预览审批单中的附件。", - Example: " dws oa approval attachment authorize-preview --instance-id --file-ids ,", - Server: "oa", - Tool: "auth_preview_attachment", + Use: "authorize-preview", + Short: "授权当前用户预览审批附件", + Long: "批量授权当前用户预览审批单中的附件。", + Example: " dws oa approval attachment authorize-preview --instance-id --file-ids ,", + Server: "oa", + Tool: "auth_preview_attachment", + OutputRollout: output.RolloutUnifiedActive, + ResultCall: callOAAttachmentResult, Flags: []LeafFlag{ {Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true}, {Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true}, @@ -263,6 +292,10 @@ func newOAAttachmentCommand() *cobra.Command { PrimaryCLIPath: "oa approval attachment authorize-preview", }, Description: "批量授权当前用户预览审批单中的附件", + Result: &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}, + DataSchema: json.RawMessage(`{"type":"object","description":"审批附件预览授权信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"class":{"type":"string","description":"服务端响应类型标识"}},"required":["spaceId","agentId"],"additionalProperties":true}`), + }, Interface: &contract.InterfaceSpec{ Mode: "mcp", Availability: "available", diff --git a/internal/helpers/oa_attachment_test.go b/internal/helpers/oa_attachment_test.go index b32ec111..230e9021 100644 --- a/internal/helpers/oa_attachment_test.go +++ b/internal/helpers/oa_attachment_test.go @@ -5,14 +5,18 @@ package helpers import ( "bytes" + "context" "encoding/json" + "errors" "io" "os" "reflect" "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" + "github.com/spf13/cobra" ) func executeOAAttachmentCommandCapturingOutput(t *testing.T, caller *scriptedToolCaller, args ...string) (string, error) { @@ -26,6 +30,13 @@ func executeOAAttachmentCommandCapturingOutput(t *testing.T, caller *scriptedToo cmd := newOaCommand() cmd.PersistentFlags().Bool("yes", false, "跳过确认") + cmd.PersistentFlags().String("format", caller.Format(), "输出格式") + ctx, _ := output.WithResultStore(context.Background()) + cmd.SetContext(ctx) + cmd.PersistentPostRunE = func(executed *cobra.Command, _ []string) error { + _, _, err := output.EmitStoredResult(executed) + return err + } cmd.SilenceErrors = true cmd.SilenceUsage = true cmd.SetOut(&stdout) @@ -65,6 +76,17 @@ func TestCrossPlatformCoverageOAAttachmentDownloadURLPreservesSignedQuery(t *tes if strings.Contains(stdout, `\u0026`) { t.Fatalf("stdout contains escaped query separator: %q", stdout) } + var envelope map[string]any + if err := json.Unmarshal([]byte(stdout), &envelope); err != nil { + t.Fatalf("decode unified output: %v", err) + } + if envelope["ok"] != true || envelope["outcome"] != "success" { + t.Fatalf("unified envelope = %#v", envelope) + } + data, ok := envelope["data"].(map[string]any) + if !ok || !strings.Contains(data["downloadUri"].(string), "&Signature=") { + t.Fatalf("unified data = %#v", envelope["data"]) + } }) t.Run("raw compatibility", func(t *testing.T) { @@ -73,12 +95,88 @@ func TestCrossPlatformCoverageOAAttachmentDownloadURLPreservesSignedQuery(t *tes if err != nil { t.Fatalf("execute command: %v", err) } - if stdout != response+"\n" { - t.Fatalf("stdout = %q, want %q", stdout, response+"\n") + const want = `{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"}` + "\n" + if stdout != want { + t.Fatalf("stdout = %q, want %q", stdout, want) } }) } +func TestCrossPlatformCoverageOAAttachmentProjectsUnifiedBusinessData(t *testing.T) { + tests := []struct { + name string + args []string + response string + wantData any + }{ + { + name: "download authorization", + args: []string{"approval", "attachment", "authorize-download", "--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`}, + response: `{"result":true,"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`, + wantData: true, + }, + { + name: "preview authorization", + args: []string{"approval", "attachment", "authorize-preview", "--instance-id", "instance-1", "--file-ids", "file-1"}, + response: `{"result":{"spaceId":27827223951,"agentId":4115627346,"class":"com.dingtalk.bpms.oapi.vo.AppSpaceResponse"},"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`, + wantData: map[string]any{ + "spaceId": float64(27827223951), "agentId": float64(4115627346), + "class": "com.dingtalk.bpms.oapi.vo.AppSpaceResponse", + }, + }, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: test.response}}} + stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...) + if err != nil { + t.Fatalf("execute command: %v", err) + } + var envelope map[string]any + if err := json.Unmarshal([]byte(stdout), &envelope); err != nil { + t.Fatalf("decode unified output: %v", err) + } + if envelope["ok"] != true || envelope["outcome"] != "success" || !reflect.DeepEqual(envelope["data"], test.wantData) { + t.Fatalf("unified envelope = %#v, want data %#v", envelope, test.wantData) + } + }) + } +} + +func TestCrossPlatformCoverageOAAttachmentRejectsSuccessWithoutResult(t *testing.T) { + caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: `{"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`}}} + _, err := executeOAAttachmentCommandCapturingOutput(t, caller, + "approval", "attachment", "authorize-download", + "--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`, + ) + if err == nil || !strings.Contains(err.Error(), "缺少 result") { + t.Fatalf("execute error = %v, want missing result", err) + } +} + +func TestCrossPlatformCoverageOAAttachmentRejectsInvalidToolResult(t *testing.T) { + tests := []struct { + name string + step scriptedToolStep + want string + }{ + {name: "non-object response", step: scriptedToolStep{text: `[]`}, want: "不是 JSON 对象"}, + {name: "tool error", step: scriptedToolStep{err: errors.New("tool unavailable")}, want: "tool unavailable"}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{test.step}} + _, err := executeOAAttachmentCommandCapturingOutput(t, caller, + "approval", "attachment", "authorize-download", + "--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`, + ) + if err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("execute error = %v, want %q", err, test.want) + } + }) + } +} + func TestCrossPlatformCoverageOAAttachmentPayloads(t *testing.T) { tests := []struct { name string @@ -162,8 +260,8 @@ func TestCrossPlatformCoverageOAAttachmentPayloads(t *testing.T) { for _, test := range tests { t.Run(test.name, func(t *testing.T) { - caller := &scriptedToolCaller{} - if err := executeOACommand(t, caller, test.args...); err != nil { + caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":{},"success":true}`}}} + if _, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...); err != nil { t.Fatalf("execute command: %v", err) } if caller.server != "oa" || caller.tool != test.wantTool { From 6ddfa59a28a9d049036bba5345a7cebd9b563bf6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 10:41:29 +0800 Subject: [PATCH 203/250] docs(skills): fix wiki member verification example --- skills/multi/dingtalk-wiki/references/wiki-members.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/multi/dingtalk-wiki/references/wiki-members.md b/skills/multi/dingtalk-wiki/references/wiki-members.md index 39023ff3..3ac09fe3 100644 --- a/skills/multi/dingtalk-wiki/references/wiki-members.md +++ b/skills/multi/dingtalk-wiki/references/wiki-members.md @@ -21,4 +21,4 @@ dws wiki +member-remove --workspace --users --format json 成员 add/update/remove 当前只能以写接口 `success=true` 作为终态证据，并显式返回 `verification.status=terminal_response_only`；成员列表受上限限制，不能被包装成精确读回验证。 -若写响应丢失，先用 `+member-list --filter-role` 做有限核对；仍无法证明时报告未知效果，不自动重放批量成员写入。 +若 add/update 写响应丢失，先用 `dws wiki +member-list --workspace --filter-role --limit 50 --format json` 做有限核对；remove 按写前已知的原角色过滤，原角色不确定时省略 `--filter-role`。成员列表仍不能证明完整结果；无法证明时报告未知效果，不自动重放批量成员写入。 From b7a6abb7807a01323e2e5fded2acb8ca4f30a5e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=9C=E7=8E=84?= Date: Tue, 18 Aug 2026 11:07:16 +0800 Subject: [PATCH 204/250] ci: retry cancelled coverage supporting job From dac4f6c029e93002926076abef46d4bb8ca84514 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 11:15:11 +0800 Subject: [PATCH 205/250] docs(skills): fail closed on wiki space pagination --- skills/multi/dingtalk-wiki/SKILL.md | 12 +++++++----- .../multi/dingtalk-wiki/references/wiki-node-ops.md | 2 +- skills/multi/dingtalk-wiki/references/wiki.md | 7 +++++-- 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/skills/multi/dingtalk-wiki/SKILL.md b/skills/multi/dingtalk-wiki/SKILL.md index 46565777..317cf5ba 100644 --- a/skills/multi/dingtalk-wiki/SKILL.md +++ b/skills/multi/dingtalk-wiki/SKILL.md @@ -40,14 +40,14 @@ metadata: | 用户意图 | 唯一推荐入口 | 关键边界 | |---|---|---| -| 按名称解析唯一知识库 | `dws wiki +resolve-space --name <名称>` | 0 条或多条停止；只想看候选用 `+space-search` | +| 按名称解析唯一知识库 | `+space-list --type --limit 50 --page-all` 后精确匹配名称 | 先明确组织/个人范围；仅 `autoPageComplete=true` 且全量中恰好一个同名项时取 workspaceId | | 搜索或列出知识库 | `+space-search --query <关键词>` / `+space-list [--type orgWikiSpace\|myWikiSpace]` | 用户要求全部时加 `--page-all`；个人知识库必须明确语义 | | 已知 workspace 查看详情 | `dws wiki +space-get --workspace ` | 已知 ID 不重复搜索 | | 创建或删除知识库 | `+space-create --name <名称>` / `+delete-space --workspace ` | 创建会读回；删除整个空间是高风险操作 | | 浏览或搜索库内节点 | `+node-list --workspace [--folder ]` / `+node-search --workspace --query <词>` | 列目录与关键词搜索分开；全量列表加 `--page-all` | | 查看节点元数据 | `dws wiki +node-get --node ` | 正文读写随后切 Doc | | 已知 workspace 创建节点 | `+node-create --workspace --name <名称> [--type <类型>]` | 支持 adoc/axls/able/appt/adraw/amind/folder；创建后读回 | -| 只有知识库名称时新建空文档 | `+wiki-new-doc --space <名称> --title <标题>` | 内部唯一解析空间；正文另走 Doc | +| 只有知识库名称时新建空文档 | 先按全量 `+space-list` 唯一解析，再 `+node-create --workspace --name <标题> --type adoc` | 不用单页 `+wiki-new-doc` 猜空间；正文另走 Doc | | 复制、移入知识库或移出到我的文档 | `+node-copy` / `+move` / `+move-to-drive` | 使用真实 nodeId/workspaceId/folderId；按 Runtime confirmation | | 删除库内节点 | `+node-delete --workspace --node ` | 删除前核对归属并确认 | | 列出或修改知识库成员 | `+member-list` / `+member-add` / `+member-update` / `+member-remove` | userId 1-30 个；角色必须显式 | @@ -56,7 +56,8 @@ metadata: ## 当前最短路径 - 已知 workspaceId：直接执行 space/node/member/feed 目标命令，不再 resolve。 -- 只有知识库名称：需要唯一 ID 用 `+resolve-space`；只需创建空 adoc 用 `+wiki-new-doc`；需要候选列表用 `+space-search`。 +- 只有知识库名称：先明确组织/个人范围，用 `+space-list --limit 50 --page-all` 取完该范围后按完整名称唯一匹配；未知范围先消歧，不同时扫描两个范围并猜测。 +- `+space-search` 只用于快速浏览候选；当前 `+resolve-space/+wiki-new-doc` 不暴露名称搜索的分页完成证据，不作为权威唯一解析或写入 Golden Route。 - 已知 nodeId/URL：元数据直接 `+node-get`；正文直接切 Doc，不先 list/search。 - 创建节点后返回的 nodeId 直接传给 Doc；不通过同名搜索重新定位。 - move/copy/delete 已含预检或读回时，不由 Agent 重复拼装原子命令。 @@ -66,7 +67,8 @@ metadata: - `+space-list/+node-list/+feed-list` 默认单页；全量请求显式加 `--page-all`，并检查 `autoPageComplete/autoPageStopReason/pagesFetched` 与分页元数据。 - `+space-search/+node-search` 缺少业务数组不是零命中；只有显式空数组才可报告空结果。 -- `+resolve-space` 只有 `resolved=true` 才提供唯一空间；多候选必须返回候选让用户消歧。 +- 名称解析只有在 scoped `+space-list` 返回 `autoPageComplete=true` 且全量中恰好一个精确同名项时才成立；0 条、多条或分页未完成都停止。 +- `+space-search`、`+resolve-space` 的单页结果不能证明全局唯一；不得把首页唯一候选直接用于写入。 - 创建空间/节点和复制节点必须取得新 ID 并读回；移动必须验证 workspace/folder；删除必须有 `success=true`。 - 成员列表服务端没有续页游标且最多 50，不能把上限内结果宣称为全量；成员写只具备终态响应证据，不虚构精确读回。 - `partial_failure`、分页未完成或写入效果未知都不是成功。 @@ -93,7 +95,7 @@ Golden Route 参数足够时不读 reference；否则最多读取一个： ## 错误最短路径 -1. 空响应、缺失集合、零/多候选或分页不完整：停止后续写入并返回证据，不把异常投影为空成功。 +1. 空响应、缺失集合、零/多候选或分页不完整：停止后续写入并返回证据；`+resolve-space resolved=true` 也不能替代完整空间列表的分页完成证据。 2. workspace/node 归属不一致：停止，不尝试换一个 ID 或 profile。 3. 写响应缺少新 ID 或 `success=true`：效果未知，按名称/ID定向回读，不盲目重放。 4. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Wiki Shortcut 清单。 diff --git a/skills/multi/dingtalk-wiki/references/wiki-node-ops.md b/skills/multi/dingtalk-wiki/references/wiki-node-ops.md index 43e48461..32c2a39b 100644 --- a/skills/multi/dingtalk-wiki/references/wiki-node-ops.md +++ b/skills/multi/dingtalk-wiki/references/wiki-node-ops.md @@ -8,7 +8,7 @@ dws wiki +node-create --workspace --name "新文档" --type adoc - `--type` 可用 `adoc|axls|able|appt|adraw|amind|folder`，父目录加 `--folder `。创建成功从结果取新 nodeId，并按类型交给 Doc/Sheet/AITable；不要靠同名搜索重新定位。 -只有空间名称且只创建空 adoc 时用 `+wiki-new-doc --space <名称> --title <标题>`。它会唯一解析空间并验证节点，但不写正文；正文仍切 Doc。 +只有空间名称时，先明确组织/个人范围，用 `+space-list --type --limit 50 --page-all` 取完并按完整名称唯一匹配；再将真实 workspaceId 传给 `+node-create`。当前不要用 `+wiki-new-doc` 直接写入，因为其内部名称搜索不暴露分页完成证据。正文仍切 Doc。 ## 读取、搜索与列表 diff --git a/skills/multi/dingtalk-wiki/references/wiki.md b/skills/multi/dingtalk-wiki/references/wiki.md index 1daad159..9ddd7343 100644 --- a/skills/multi/dingtalk-wiki/references/wiki.md +++ b/skills/multi/dingtalk-wiki/references/wiki.md @@ -7,11 +7,13 @@ | 已知条件 | 入口 | |---|---| | 精确 workspaceId 或知识库 URL | `+space-get --workspace <值>` | -| 名称且必须得到唯一 ID | `+resolve-space --name <名称>` | +| 名称且必须得到唯一 ID | `+space-list --type --limit 50 --page-all` 后按完整名称精确匹配 | | 关键词且需要浏览候选 | `+space-search --query <关键词>` | | 明确要列出组织/个人知识库 | `+space-list --type orgWikiSpace|myWikiSpace` | -`+resolve-space` 返回多候选时停止；不要改用列表第一项。空关键词不能构造 `--query ""`。 +名称解析前先明确组织知识库还是个人知识库；范围未知时向用户消歧。只有 `+space-list` 返回 `autoPageComplete=true`，并且完整结果中恰好一个名称精确相等的空间时，才可把其 workspaceId 交给后续写操作。0 条、多条、分页未完成都停止，不选择第一项。 + +`+space-search` 用于候选发现，但当前没有可执行的续页 flag；`+resolve-space` 和 `+wiki-new-doc` 的内部名称搜索也不暴露分页完成证据。因此这三个入口的单页结果都不能证明全局唯一，当前不用于写入前的权威身份解析。空关键词不能构造 `--query ""`。 ## Runtime 确认与首次执行 @@ -26,6 +28,7 @@ ```bash dws wiki +space-list --page-all --page-limit 20 --format json +dws wiki +space-list --type orgWikiSpace --limit 50 --page-all --format json dws wiki +node-list --workspace --page-all --max-items 500 --format json dws wiki +feed-list --workspace --page-all --format json ``` From 5b9234d8fed7d280216e17bce13e5d45ac3d9af2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Tue, 18 Aug 2026 11:16:04 +0800 Subject: [PATCH 206/250] fix(recruit): align job creation contract --- .../app/schema_agent_examples_dry_run_test.go | 2 +- internal/helpers/recruit.go | 173 +++++++++++++++++- internal/helpers/recruit_test.go | 106 ++++++++++- skills/mono/references/products/recruit.md | 15 +- .../multi/dingtalk-misc/references/recruit.md | 42 ++++- 5 files changed, 311 insertions(+), 27 deletions(-) diff --git a/internal/app/schema_agent_examples_dry_run_test.go b/internal/app/schema_agent_examples_dry_run_test.go index 5497810d..6458979e 100644 --- a/internal/app/schema_agent_examples_dry_run_test.go +++ b/internal/app/schema_agent_examples_dry_run_test.go @@ -291,7 +291,7 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles { markdown: []byte("# Agent dry-run fixture\n\nNo business call is allowed.\n"), jsonFile: []byte(`[{"content":"Agent dry-run fixture","sort":"0","key":"fixture","contentType":"markdown","type":"1"}]`), batch: []byte(`[{"sheetId":"Sheet1","range":"A1:B2","fontWeight":"bold"}]`), - job: []byte(`{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL_TIME","requiredEdu":1,"minSalary":20000,"maxSalary":35000}`), + job: []byte(`{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL-TIME","requiredEdu":6,"minSalary":20000,"maxSalary":35000,"extData":{"headCount":1,"fullTimeExtData":{"salaryMonth":12}},"creatorUserId":"creator-user-id","ownerUserIds":["owner-user-id"]}`), binary: []byte("%PDF-1.4\n%%EOF\n"), image: {0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'}, } { diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index a64c7de4..8152d7a7 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -379,11 +379,11 @@ func newRecruitJobCreateCommand() *cobra.Command { Interface: recruitMCPInterface(recruitCreateJobTool), Selection: contract.SelectionSpec{ AgentSummary: "使用结构化 JSON 创建招聘职位", - UseWhen: []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、minSalary、maxSalary"}, + UseWhen: []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、extData；jobNature 固定为 FULL-TIME；创建人和负责人分别使用真实 creatorUserId 与 ownerUserIds"}, AvoidWhen: []string{"仅查询职位时使用 recruit job list 或 recruit job get"}, Examples: []string{"dws recruit job create --from ./job.json --dry-run --format json"}, }, - Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 读取后作为 atsAddJobParam 对象发送"}}, + Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 校验后原样作为 atsAddJobParam 对象发送；creatorUserId 为创建人 userId，ownerUserIds 为负责人 userId 字符串数组"}}, }, }) } @@ -479,7 +479,7 @@ func loadRecruitJobFile(path string) (any, error) { } func validateRecruitJob(job map[string]any) error { - for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "minSalary", "maxSalary"} { + for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "extData"} { value, ok := job[name] if !ok || value == nil || (isString(value) && strings.TrimSpace(value.(string)) == "") { return apperrors.NewValidation(fmt.Sprintf("职位 JSON 缺少必填字段 %s", name)) @@ -490,13 +490,170 @@ func validateRecruitJob(job map[string]any) error { return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是字符串", name)) } } - for _, name := range []string{"requiredEdu", "minSalary", "maxSalary"} { - if _, ok := job[name].(float64); !ok { - return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是数字", name)) + if job["jobNature"].(string) != "FULL-TIME" { + return apperrors.NewValidation("职位 JSON 字段 jobNature 当前仅支持 FULL-TIME") + } + requiredEdu, ok := job["requiredEdu"].(float64) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 requiredEdu 必须是数字") + } + if requiredEdu < 1 || requiredEdu > 9 || requiredEdu != float64(int(requiredEdu)) { + return apperrors.NewValidation("职位 JSON 字段 requiredEdu 必须是 1 到 9 的整数") + } + + minSalary, hasMinSalary, err := optionalRecruitNumber(job, "minSalary") + if err != nil { + return err + } + maxSalary, hasMaxSalary, err := optionalRecruitNumber(job, "maxSalary") + if err != nil { + return err + } + if hasMinSalary && hasMaxSalary && minSalary > maxSalary { + return apperrors.NewValidation("职位 JSON 中 minSalary 不能大于 maxSalary") + } + + for _, name := range []string{"province", "city", "district", "category"} { + if value, exists := job[name]; exists && value != nil && !isString(value) { + return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是字符串", name)) } } - if job["minSalary"].(float64) > job["maxSalary"].(float64) { - return apperrors.NewValidation("职位 JSON 中 minSalary 不能大于 maxSalary") + if value, exists := job["campus"]; exists && value != nil { + if _, ok := value.(bool); !ok { + return apperrors.NewValidation("职位 JSON 字段 campus 必须是布尔值") + } + } + if err := validateRecruitIdentityFields(job); err != nil { + return err + } + if err := validateRecruitAddress(job); err != nil { + return err + } + extData, ok := job["extData"].(map[string]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 extData 必须是对象") + } + if err := validateRecruitExtData(extData); err != nil { + return err + } + return nil +} + +func optionalRecruitNumber(values map[string]any, name string) (float64, bool, error) { + value, exists := values[name] + if !exists || value == nil { + return 0, false, nil + } + number, ok := value.(float64) + if !ok { + return 0, false, apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是数字", name)) + } + return number, true, nil +} + +func validateRecruitIdentityFields(job map[string]any) error { + if value, exists := job["creatorUserId"]; exists && value != nil { + creatorUserID, ok := value.(string) + if !ok || strings.TrimSpace(creatorUserID) == "" { + return apperrors.NewValidation("职位 JSON 字段 creatorUserId 必须是非空字符串") + } + } + if value, exists := job["ownerUserIds"]; exists && value != nil { + ownerUserIDs, ok := value.([]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 ownerUserIds 必须是字符串数组") + } + for _, owner := range ownerUserIDs { + ownerUserID, ok := owner.(string) + if !ok || strings.TrimSpace(ownerUserID) == "" { + return apperrors.NewValidation("职位 JSON 字段 ownerUserIds 只能包含非空字符串") + } + } + } + return nil +} + +func validateRecruitAddress(job map[string]any) error { + value, exists := job["address"] + if !exists || value == nil { + return nil + } + address, ok := value.(map[string]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 address 必须是对象") + } + for _, name := range []string{"name", "detail", "longitude", "latitude"} { + field, exists := address[name] + text, ok := field.(string) + if !exists || !ok || strings.TrimSpace(text) == "" { + return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 address.%s 必须是非空字符串", name)) + } + } + return nil +} + +func validateRecruitExtData(extData map[string]any) error { + if value, exists := extData["headCount"]; exists && value != nil { + headCount, ok := value.(float64) + if !ok || headCount < 1 || headCount > 999 || headCount != float64(int(headCount)) { + return apperrors.NewValidation("职位 JSON 字段 extData.headCount 必须是 1 到 999 的整数") + } + } + if value, exists := extData["source"]; exists && value != nil && !isString(value) { + return apperrors.NewValidation("职位 JSON 字段 extData.source 必须是字符串") + } + if value, exists := extData["fullTimeExtData"]; exists && value != nil { + fullTime, ok := value.(map[string]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData 必须是对象") + } + if err := validateRecruitFullTimeExtData(fullTime); err != nil { + return err + } + } + if value, exists := extData["tags"]; exists && value != nil { + tags, ok := value.([]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 extData.tags 必须是数组") + } + for _, value := range tags { + tag, ok := value.(map[string]any) + if !ok { + return apperrors.NewValidation("职位 JSON 字段 extData.tags 只能包含对象") + } + name, ok := tag["name"].(string) + if !ok || strings.TrimSpace(name) == "" { + return apperrors.NewValidation("职位 JSON 字段 extData.tags[].name 必须是非空字符串") + } + } + } + return nil +} + +func validateRecruitFullTimeExtData(fullTime map[string]any) error { + salaryMonth, hasSalaryMonth, err := optionalRecruitNumber(fullTime, "salaryMonth") + if err != nil { + return err + } + if hasSalaryMonth && (salaryMonth < 12 || salaryMonth > 24 || salaryMonth != float64(int(salaryMonth))) { + return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.salaryMonth 必须是 12 到 24 的整数") + } + minExperience, hasMinExperience, err := optionalRecruitNumber(fullTime, "minJobExperience") + if err != nil { + return err + } + maxExperience, hasMaxExperience, err := optionalRecruitNumber(fullTime, "maxJobExperience") + if err != nil { + return err + } + if hasMinExperience && minExperience < 0 { + return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.minJobExperience 不能小于 0") + } + if hasMaxExperience && maxExperience < 0 { + return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.maxJobExperience 不能小于 0") + } + if hasMinExperience && hasMaxExperience && minExperience > maxExperience { + return apperrors.NewValidation("职位 JSON 中 minJobExperience 不能大于 maxJobExperience") } return nil } diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 0222d08c..e7632c28 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -207,8 +207,13 @@ func writeRecruitJobFixture(t *testing.T) (string, map[string]any) { t.Helper() path := filepath.Join(t.TempDir(), "job.json") job := map[string]any{ - "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", - "requiredEdu": 1, "minSalary": 20000, "maxSalary": 35000, + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL-TIME", + "requiredEdu": 6, "minSalary": 20000, "maxSalary": 35000, + "creatorUserId": "creator-user-id", "ownerUserIds": []string{"owner-user-id-1", "owner-user-id-2"}, + "extData": map[string]any{ + "headCount": 1, + "fullTimeExtData": map[string]any{"salaryMonth": 12, "minJobExperience": 1, "maxJobExperience": 3}, + }, } data, err := json.Marshal(job) if err != nil { @@ -254,8 +259,13 @@ func TestRecruitJobCreateCallsRemoteOnceWhenConfirmed(t *testing.T) { t.Fatalf("dispatch = %s/%s, want %s/%s", call.productID, call.tool, recruitServerID, recruitCreateJobTool) } wantArgs := map[string]any{"atsAddJobParam": map[string]any{ - "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", - "requiredEdu": float64(1), "minSalary": float64(20000), "maxSalary": float64(35000), + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL-TIME", + "requiredEdu": float64(6), "minSalary": float64(20000), "maxSalary": float64(35000), + "creatorUserId": "creator-user-id", "ownerUserIds": []any{"owner-user-id-1", "owner-user-id-2"}, + "extData": map[string]any{ + "headCount": float64(1), + "fullTimeExtData": map[string]any{"salaryMonth": float64(12), "minJobExperience": float64(1), "maxJobExperience": float64(3)}, + }, }} if !reflect.DeepEqual(call.args, wantArgs) { t.Fatalf("args = %#v, want %#v", call.args, wantArgs) @@ -307,8 +317,13 @@ func TestRecruitValidationBranches(t *testing.T) { } base := map[string]any{ - "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL_TIME", - "requiredEdu": float64(1), "minSalary": float64(20000), "maxSalary": float64(35000), + "name": "Java 工程师", "description": "服务端开发", "jobNature": "FULL-TIME", + "requiredEdu": float64(6), "minSalary": float64(20000), "maxSalary": float64(35000), + "creatorUserId": "creator-user-id", "ownerUserIds": []any{"owner-user-id"}, + "extData": map[string]any{ + "headCount": float64(1), + "fullTimeExtData": map[string]any{"salaryMonth": float64(12), "minJobExperience": float64(1), "maxJobExperience": float64(3)}, + }, } for _, test := range []struct { name string @@ -317,7 +332,61 @@ func TestRecruitValidationBranches(t *testing.T) { }{ {name: "string type", mutate: func(job map[string]any) { job["name"] = 1 }, want: "name 必须是字符串"}, {name: "number type", mutate: func(job map[string]any) { job["requiredEdu"] = "本科" }, want: "requiredEdu 必须是数字"}, + {name: "missing ext data", mutate: func(job map[string]any) { delete(job, "extData") }, want: "缺少必填字段 extData"}, + {name: "ext data type", mutate: func(job map[string]any) { job["extData"] = "invalid" }, want: "extData 必须是对象"}, + {name: "job nature enum", mutate: func(job map[string]any) { job["jobNature"] = "FULL_TIME" }, want: "仅支持 FULL-TIME"}, + {name: "education range", mutate: func(job map[string]any) { job["requiredEdu"] = float64(10) }, want: "1 到 9 的整数"}, {name: "salary range", mutate: func(job map[string]any) { job["minSalary"] = float64(40000) }, want: "minSalary 不能大于 maxSalary"}, + {name: "min salary type", mutate: func(job map[string]any) { job["minSalary"] = "20000" }, want: "minSalary 必须是数字"}, + {name: "salary type", mutate: func(job map[string]any) { job["maxSalary"] = "35000" }, want: "maxSalary 必须是数字"}, + {name: "creator type", mutate: func(job map[string]any) { job["creatorUserId"] = " " }, want: "creatorUserId 必须是非空字符串"}, + {name: "owners type", mutate: func(job map[string]any) { job["ownerUserIds"] = "owner-user-id" }, want: "ownerUserIds 必须是字符串数组"}, + {name: "owner item", mutate: func(job map[string]any) { job["ownerUserIds"] = []any{""} }, want: "ownerUserIds 只能包含非空字符串"}, + {name: "campus type", mutate: func(job map[string]any) { job["campus"] = "false" }, want: "campus 必须是布尔值"}, + {name: "region type", mutate: func(job map[string]any) { job["city"] = 330100 }, want: "city 必须是字符串"}, + {name: "address type", mutate: func(job map[string]any) { job["address"] = "杭州" }, want: "address 必须是对象"}, + {name: "address required field", mutate: func(job map[string]any) { + job["address"] = map[string]any{"name": "亲橙Park", "detail": "杭州市余杭区", "longitude": "120.0"} + }, want: "address.latitude 必须是非空字符串"}, + {name: "head count range", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"headCount": float64(0)} + }, want: "headCount 必须是 1 到 999 的整数"}, + {name: "source type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"source": true} + }, want: "extData.source 必须是字符串"}, + {name: "full time ext data type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": "invalid"} + }, want: "fullTimeExtData 必须是对象"}, + {name: "salary month range", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"salaryMonth": float64(25)}} + }, want: "salaryMonth 必须是 12 到 24 的整数"}, + {name: "salary month type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"salaryMonth": "12"}} + }, want: "salaryMonth 必须是数字"}, + {name: "min experience type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"minJobExperience": "1"}} + }, want: "minJobExperience 必须是数字"}, + {name: "max experience type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"maxJobExperience": "3"}} + }, want: "maxJobExperience 必须是数字"}, + {name: "negative min experience", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"minJobExperience": float64(-1)}} + }, want: "minJobExperience 不能小于 0"}, + {name: "negative max experience", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"maxJobExperience": float64(-1)}} + }, want: "maxJobExperience 不能小于 0"}, + {name: "experience range", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"fullTimeExtData": map[string]any{"minJobExperience": float64(5), "maxJobExperience": float64(3)}} + }, want: "minJobExperience 不能大于 maxJobExperience"}, + {name: "tags type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"tags": "五险一金"} + }, want: "extData.tags 必须是数组"}, + {name: "tag item type", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"tags": []any{"五险一金"}} + }, want: "extData.tags 只能包含对象"}, + {name: "tag name", mutate: func(job map[string]any) { + job["extData"] = map[string]any{"tags": []any{map[string]any{"name": ""}}} + }, want: "tags[].name 必须是非空字符串"}, } { t.Run(test.name, func(t *testing.T) { job := make(map[string]any, len(base)) @@ -330,6 +399,31 @@ func TestRecruitValidationBranches(t *testing.T) { } }) } + + withoutSalary := make(map[string]any, len(base)) + for key, value := range base { + withoutSalary[key] = value + } + delete(withoutSalary, "minSalary") + delete(withoutSalary, "maxSalary") + if err := validateRecruitJob(withoutSalary); err != nil { + t.Fatalf("optional salary validation error = %v, want nil", err) + } + + completeAddress := make(map[string]any, len(base)+1) + for key, value := range base { + completeAddress[key] = value + } + completeAddress["address"] = map[string]any{ + "name": "亲橙Park", "detail": "浙江省杭州市余杭区", "longitude": "120.008822", "latitude": "30.270739", + } + completeAddress["campus"] = false + completeAddress["province"] = "330000" + completeAddress["city"] = "330100" + completeAddress["district"] = "330110" + if err := validateRecruitJob(completeAddress); err != nil { + t.Fatalf("complete job validation error = %v, want nil", err) + } } func TestRecruitListResultData(t *testing.T) { diff --git a/skills/mono/references/products/recruit.md b/skills/mono/references/products/recruit.md index 6c2b48f8..2e035201 100644 --- a/skills/mono/references/products/recruit.md +++ b/skills/mono/references/products/recruit.md @@ -24,6 +24,15 @@ dws recruit job create --from ./job.json --dry-run --format json dws recruit job create --from ./job.json --format json ``` -JSON 必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、 -`minSalary`、`maxSalary`。后三者为数字，且最低薪资不得大于最高薪资。文件只写 -职位对象，不要添加 MCP 信封字段 `atsAddJobParam`。 +JSON 必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`。 +`jobNature` 当前固定为 `FULL-TIME`；学历枚举为 1小学、2初中、3高中、4中专、 +5大专、6本科、7硕士、8博士、9其他。`minSalary`、`maxSalary` 可选；两者同时 +提供时最低薪资不得高于最高薪资。 + +职位对象应显式包含真实的 `creatorUserId` 和 `ownerUserIds`；前者是当前创建人 +userId，后者是负责人 userId 的 JSON 字符串数组。所有 userId 必须来自同一 profile +下的真实通讯录结果，禁止猜测。`extData.headCount` 范围 1–999，薪资月份范围 +12–24；提供地址时必须包含地点名、详细地址和可信的经纬度。 + +文件只写职位对象，不要添加 MCP 信封字段 `atsAddJobParam`、`corpId`、`bizCode` +或 `opUserId`；这些字段由 CLI 或 Connector 处理。 diff --git a/skills/multi/dingtalk-misc/references/recruit.md b/skills/multi/dingtalk-misc/references/recruit.md index d6209be9..36827e56 100644 --- a/skills/multi/dingtalk-misc/references/recruit.md +++ b/skills/multi/dingtalk-misc/references/recruit.md @@ -37,8 +37,14 @@ dws recruit job get --job-id JOB_ID --format json ## 创建职位 创建是非幂等远端写入。先准备只包含职位对象的 UTF-8 JSON 文件，并用 -`--dry-run` 检查完整调用；向用户展示职位名称、性质、薪资和负责人，取得明确 -确认后，交由 CLI 的确认流程执行实际创建。不要在存储示例中加入确认绕过参数。 +`--dry-run` 检查完整调用；向用户展示职位名称、性质、薪资、创建人和负责人，取得 +明确确认后，交由 CLI 的确认流程执行实际创建。不要在存储示例中加入确认绕过参数。 + +创建人和负责人必须来自同一 profile 下的真实通讯录结果，不得猜测或复用其他组织的 +userId。`creatorUserId` 使用当前操作者的 userId；`ownerUserIds` 是负责人 userId 的 +JSON 字符串数组。用户说“负责人是我”时先运行 +`dws contact user get-self --format json` 取得当前 userId；用户指定其他负责人时按 +通讯录 Skill 解析唯一 userId。未指定负责人时先向用户确认，不要静默省略或默认选人。 ```bash dws recruit job create --from ./job.json --dry-run --format json @@ -51,14 +57,32 @@ dws recruit job create --from ./job.json --format json { "name": "Java 开发工程师", "description": "负责服务端系统开发", - "jobNature": "FULL_TIME", - "requiredEdu": 1, + "jobNature": "FULL-TIME", + "requiredEdu": 6, "minSalary": 20000, - "maxSalary": 35000 + "maxSalary": 35000, + "extData": { + "headCount": 1, + "fullTimeExtData": { + "salaryMonth": 12 + } + }, + "creatorUserId": "CURRENT_USER_ID", + "ownerUserIds": ["OWNER_USER_ID"] } ``` -六个字段均为必填；`requiredEdu`、`minSalary`、`maxSalary` 必须为数字，且 -`minSalary` 不得大于 `maxSalary`。可选字段以当前 -`dws recruit job create --help` 和 leaf Schema 为准；不要把 MCP 信封字段 -`atsAddJobParam` 写进文件，CLI 会自动包装。 +必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`。 +`jobNature` 当前固定为 `FULL-TIME`；`requiredEdu` 为 1–9 的整数（1小学、2初中、 +3高中、4中专、5大专、6本科、7硕士、8博士、9其他）。`minSalary` 与 +`maxSalary` 可选；两者同时提供时最低薪资不得高于最高薪资。 + +`extData.headCount` 范围 1–999；`extData.fullTimeExtData.salaryMonth` 范围 +12–24；最高工作年限不得小于最低工作年限。提供 `address` 时必须同时包含 +`name`、`detail`、`longitude`、`latitude`，经纬度只能来自地图选点或可信地址解析， +不得猜测。`source` 可省略，由 Connector 默认补充为 `manual`；不传 `category` 时 +Connector 会设置 `checkJobCategory=false`。 + +可选字段以当前 `dws recruit job create --help` 和 leaf Schema 为准。不要把 MCP +信封字段 `atsAddJobParam`、`corpId`、`bizCode` 或 `opUserId` 写进文件；CLI 与 +Connector 会负责包装和身份注入。 From 606f712a52014739195bc95dab30503fb8f841c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 11:19:22 +0800 Subject: [PATCH 207/250] docs(skills): align wiki storage intent routes --- skills/multi/dingtalk-wiki/references/intent-guide.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/skills/multi/dingtalk-wiki/references/intent-guide.md b/skills/multi/dingtalk-wiki/references/intent-guide.md index 62e83b7a..a4b9e203 100644 --- a/skills/multi/dingtalk-wiki/references/intent-guide.md +++ b/skills/multi/dingtalk-wiki/references/intent-guide.md @@ -4,9 +4,10 @@ | 用户说... | 真实意图 | 应该用 | 不要用 | 理由 | |---|---|---|---|---| -| "帮我看看知识库里的文件" | 知识库节点列表 | `wiki node list --workspace` | `drive list` | 明确"知识库"上下文 → wiki node list | -| "列出钉盘团队空间" | 列出钉盘空间 | `wiki space list --type orgSpace` | `drive list-spaces` | 空间管理归 wiki，drive list-spaces 已 deprecated | -| "在知识库里搜方案" | 空间内搜索 | `wiki node search --workspace` | `drive search` | 指定了空间上下文 → wiki node search | -| "搜一下有没有叫XX的文件" | 全局搜索 | `drive search` | `wiki node search` | 未指定空间 → drive search 全局聚合搜索 | -| "在知识库里创建一个文档" | 创建空文件实体 | `wiki node create --type adoc` | `doc create` | 空间内创建节点归 wiki；doc create 是向已有文档写入内容，不是创建文件节点 | +| "帮我看看知识库里的文件" | 知识库节点列表 | `dws wiki +node-list --workspace ` | `dws drive +list` | 明确“知识库”上下文，使用 Wiki 层级 | +| "列出钉盘/文档空间" | 普通存储根目录 | `dws drive +list` | `dws wiki +space-list` | 未明确知识库，属于 Drive 存储域 | +| "列出组织知识库" | 列出组织知识库容器 | `dws wiki +space-list --type orgWikiSpace --page-all` | `dws drive +list` | 明确知识库容器，使用当前 Wiki 类型枚举 | +| "在知识库里搜方案" | 空间内搜索 | `dws wiki +node-search --workspace --query <词>` | `dws drive +search` | 指定知识库上下文，使用 Wiki 节点搜索 | +| "搜一下有没有叫XX的文件" | 全局搜索 | `dws drive +search --query <词>` | `dws wiki +node-search` | 未指定知识库，使用 Drive 全局聚合搜索 | +| "在知识库里创建一个文档" | 创建空文件实体 | `dws wiki +node-create --workspace --name <名称> --type adoc` | `dws doc create` | 空间内创建节点归 Wiki；正文写入才切 Doc | | "整理一下XX项目的所有讨论" | 跨源主题归档 | #5 generate-topic-report | #4 write-doc | #4 侧重单篇文档创作；按主题跨听记/群消息汇总属于工作汇报 | From 7c76e4fc03dc4bc148f1c20b61bdcc7a5c54db52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Tue, 18 Aug 2026 11:23:51 +0800 Subject: [PATCH 208/250] test(oa): harden attachment delivery policy checks to #666 --- .../oa_attachment_delivery_policy_test.go | 75 ++++++++++++++++--- 1 file changed, 65 insertions(+), 10 deletions(-) diff --git a/test/unit/oa_attachment_delivery_policy_test.go b/test/unit/oa_attachment_delivery_policy_test.go index 32af42ec..cd5f7cd7 100644 --- a/test/unit/oa_attachment_delivery_policy_test.go +++ b/test/unit/oa_attachment_delivery_policy_test.go @@ -4,9 +4,14 @@ package unit_test import ( + "go/ast" + "go/parser" + "go/token" "os" "path/filepath" + "reflect" "runtime" + "strconv" "strings" "testing" ) @@ -24,19 +29,40 @@ func TestCrossPlatformCoverageOAAttachmentDeliveryPolicy(t *testing.T) { } oaSourcePath := filepath.Join(root, "internal", "helpers", "oa.go") - oaSource, err := os.ReadFile(oaSourcePath) + oaFile, err := parser.ParseFile(token.NewFileSet(), oaSourcePath, nil, 0) if err != nil { - t.Fatalf("read %s: %v", oaSourcePath, err) + t.Fatalf("parse %s: %v", oaSourcePath, err) } - for _, required := range []string{ - "func newOAAttachmentCommand()", - `Tool: "get_attachment_download_url"`, - `Tool: "auth_download_file"`, - `Tool: "auth_preview_attachment"`, - } { - if !strings.Contains(string(oaSource), required) { - t.Errorf("%s missing attachment declaration %q", oaSourcePath, required) + wantTools := map[string]string{ + "download-url": "get_attachment_download_url", + "authorize-download": "auth_download_file", + "authorize-preview": "auth_preview_attachment", + } + gotTools := make(map[string]string, len(wantTools)) + foundConstructor := false + for _, declaration := range oaFile.Decls { + function, ok := declaration.(*ast.FuncDecl) + if !ok || function.Name.Name != "newOAAttachmentCommand" { + continue } + foundConstructor = true + ast.Inspect(function.Body, func(node ast.Node) bool { + literal, ok := node.(*ast.CompositeLit) + if !ok || !isOAAttachmentLeafSpec(literal) { + return true + } + use := oaAttachmentLeafStringField(t, literal, "Use") + if _, expected := wantTools[use]; expected { + gotTools[use] = oaAttachmentLeafStringField(t, literal, "Tool") + } + return true + }) + } + if !foundConstructor { + t.Fatalf("%s missing newOAAttachmentCommand", oaSourcePath) + } + if !reflect.DeepEqual(gotTools, wantTools) { + t.Fatalf("%s attachment Use/Tool declarations = %#v, want %#v", oaSourcePath, gotTools, wantTools) } docPaths := []string{ @@ -62,3 +88,32 @@ func TestCrossPlatformCoverageOAAttachmentDeliveryPolicy(t *testing.T) { } } } + +func isOAAttachmentLeafSpec(literal *ast.CompositeLit) bool { + identifier, ok := literal.Type.(*ast.Ident) + return ok && identifier.Name == "LeafSpec" +} + +func oaAttachmentLeafStringField(t *testing.T, literal *ast.CompositeLit, fieldName string) string { + t.Helper() + for _, element := range literal.Elts { + keyValue, ok := element.(*ast.KeyValueExpr) + if !ok { + continue + } + key, ok := keyValue.Key.(*ast.Ident) + if !ok || key.Name != fieldName { + continue + } + value, ok := keyValue.Value.(*ast.BasicLit) + if !ok || value.Kind != token.STRING { + t.Fatalf("LeafSpec.%s must be a string literal", fieldName) + } + decoded, err := strconv.Unquote(value.Value) + if err != nil { + t.Fatalf("decode LeafSpec.%s: %v", fieldName, err) + } + return decoded + } + return "" +} From 6aaa15be3c171b4c218fd3baa13b9d526bec317d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 11:34:54 +0800 Subject: [PATCH 209/250] docs(skills): clarify drive transfer evidence --- skills/multi/dingtalk-drive/SKILL.md | 2 +- skills/multi/dingtalk-drive/references/folder-sync.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index 609d89cc..33ff87c4 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -76,7 +76,7 @@ metadata: ## 关键结果语义 - `+list/+search/+recent` 检查集合、hasMore 和 nextCursor；缺少集合不能当空结果，多候选禁止默认第一项。 -- `+download` 验证相对路径存在且 sizeBytes > 0；`+upload` 检查最终 nodeId、名称、类型和大小。 +- `+download` 验证相对路径存在且 sizeBytes > 0；`+upload` 检查最终 nodeId、名称、类型和大小。只有源端与结果都提供可比哈希时才核对 checksum；缺失时保留现有证据，不虚构端到端校验和。 - copy/move/rename/create-folder 检查 `ok/outcome` 和读回；`partial_success` 不是完成。 - status 检查分类集合；pull/push/sync 检查 summary 和逐项结果，failed/unknown 必须保留。 - 分页未结束时返回 continuation；目录树或大列表必须有最大深度、页数和条目数。 diff --git a/skills/multi/dingtalk-drive/references/folder-sync.md b/skills/multi/dingtalk-drive/references/folder-sync.md index 8922dfeb..b0dd5a4e 100644 --- a/skills/multi/dingtalk-drive/references/folder-sync.md +++ b/skills/multi/dingtalk-drive/references/folder-sync.md @@ -36,5 +36,5 @@ dws drive sync --local-folder /abs/local --remote-folder --on-conflic - status 检查 `new_local/new_remote/modified/unchanged/unknown`。 - pull/push/sync 检查 summary 与逐条 items；任何 failed/unknown 必须保留，不把部分结果称为成功。 -- 下载先写临时文件再原子替换；失败时保留原目标。上传失败按远端路径、名称和大小读回，不能直接重放可能已提交项。 +- 下载先写临时文件再原子替换；失败时保留原目标。上传在提交前明确失败时直接返回；只有提交后超时、连接中断或响应丢失等效果未知时，才按远端路径、名称和大小读回，不能直接重放可能已提交项。服务未同时提供源端与结果的可比哈希时，不虚构 checksum 验证。 - dry-run 与正式执行必须使用同一 local-folder、remote-folder、space-id 和策略；不要在确认后静默改变方向或冲突策略。 From a3a96a6bd430ef77cc78f11f796d1619b62a2f08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 12:38:09 +0800 Subject: [PATCH 210/250] ci: retry cancelled coverage check From 4da2f382ec2308846f6c099844e0e64f3733fc69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 12:43:20 +0800 Subject: [PATCH 211/250] docs(drive): clarify commit unknown recovery --- skills/multi/dingtalk-drive/references/folder-sync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/multi/dingtalk-drive/references/folder-sync.md b/skills/multi/dingtalk-drive/references/folder-sync.md index b0dd5a4e..21499ad8 100644 --- a/skills/multi/dingtalk-drive/references/folder-sync.md +++ b/skills/multi/dingtalk-drive/references/folder-sync.md @@ -36,5 +36,5 @@ dws drive sync --local-folder /abs/local --remote-folder --on-conflic - status 检查 `new_local/new_remote/modified/unchanged/unknown`。 - pull/push/sync 检查 summary 与逐条 items；任何 failed/unknown 必须保留，不把部分结果称为成功。 -- 下载先写临时文件再原子替换；失败时保留原目标。上传在提交前明确失败时直接返回；只有提交后超时、连接中断或响应丢失等效果未知时，才按远端路径、名称和大小读回，不能直接重放可能已提交项。服务未同时提供源端与结果的可比哈希时，不虚构 checksum 验证。 +- 下载先写临时文件再原子替换；失败时保留原目标。上传在提交前明确失败时直接返回。`push/sync` Runtime 遇到 `commit_upload` 超时、连接中断、空响应或畸形响应会直接返回错误，不会自动恢复，也不能据此断言未提交；Agent 必须把该项保留为 `unknown`，再用只读 list/inspect 按远端路径、名称和大小有限核对，无法证明时报告未知，不能直接重放可能已提交项。服务未同时提供源端与结果的可比哈希时，不虚构 checksum 验证。 - dry-run 与正式执行必须使用同一 local-folder、remote-folder、space-id 和策略；不要在确认后静默改变方向或冲突策略。 From 149a2481f49f25c025b18aa33a3a0ff36af896b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 13:02:07 +0800 Subject: [PATCH 212/250] docs(drive): restore high-risk permission guards --- skills/multi/dingtalk-drive/references/drive.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 9b51c551..2106cded 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -65,7 +65,7 @@ dws drive +publish-get --node dws drive +publish-unset --node ``` -`+publish-get` 只读；`+publish-unset` 为高风险写。公开 catalog 没有 `+publish-set`；明确要求开启公开时只查询一次 `drive publish set` 精确 leaf，并按 Runtime confirmation 执行，不猜造 Shortcut。 +`+publish-get` 只读；`+publish-unset` 为高风险写。公开 catalog 没有 `+publish-set`，且当前普通文件和在线文档都没有经过验证的开启公开闭环。用户明确要求开启公开时，说明当前 Agent 路由不支持并停止；不要查询或执行 `drive publish set`。只有补齐受支持节点上的真实 set→get→unset 闭环证据并更新 Runtime 路由后，才重新开放该能力。 ## 权限 @@ -77,7 +77,7 @@ dws drive +publish-unset --node | 查看可申请权限和审批人 | `permission apply-info` | | 发起权限申请 | `permission apply` | -只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。 +只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。转移所有者时，在构造最终命令前必须让用户分别明确决定 `--reserve-role ` 和 `--recursive=`；Agent 不得根据默认值、对象类型或便捷性自行选择任一项。两项决策与目标、新所有者均明确后，才按 Runtime confirmation 构造首次正式调用。 ## 快捷方式节点 From 2969fb3c217e86268c84e13d481b736a3bd8a2fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 13:04:37 +0800 Subject: [PATCH 213/250] docs(drive): align publish guard with runtime --- skills/multi/dingtalk-drive/references/drive.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 2106cded..6a50617a 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -65,7 +65,7 @@ dws drive +publish-get --node dws drive +publish-unset --node ``` -`+publish-get` 只读；`+publish-unset` 为高风险写。公开 catalog 没有 `+publish-set`，且当前普通文件和在线文档都没有经过验证的开启公开闭环。用户明确要求开启公开时，说明当前 Agent 路由不支持并停止；不要查询或执行 `drive publish set`。只有补齐受支持节点上的真实 set→get→unset 闭环证据并更新 Runtime 路由后，才重新开放该能力。 +`+publish-get` 只读；`+publish-unset` 为高风险写。Runtime 虽注册了 `+publish-set`，但当前普通文件和在线文档都没有经过验证的开启公开闭环，因此根 Skill 明确不将它开放给 Agent。用户要求开启公开时，说明当前 Agent 路由不支持并停止；不要查询或执行 `+publish-set`、`drive publish set` 或其他替代写入口。只有补齐受支持节点上的真实 set→get→unset 闭环证据并更新 Agent 路由后，才重新开放该能力。 ## 权限 From 9c202c7eaec0c6f0cad758c8119d151140033f43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 13:12:33 +0800 Subject: [PATCH 214/250] docs(skills): restore compressed safety and space routes --- skills/multi/dingtalk-drive/SKILL.md | 7 +++++-- skills/multi/dingtalk-drive/references/drive.md | 2 ++ skills/multi/dingtalk-drive/references/folder-sync.md | 6 +++--- skills/multi/dingtalk-drive/references/intent-guide.md | 3 ++- skills/multi/dingtalk-wiki/SKILL.md | 4 +++- skills/multi/dingtalk-wiki/references/intent-guide.md | 3 ++- skills/multi/dingtalk-wiki/references/wiki-members.md | 3 +++ 7 files changed, 20 insertions(+), 8 deletions(-) diff --git a/skills/multi/dingtalk-drive/SKILL.md b/skills/multi/dingtalk-drive/SKILL.md index 33ff87c4..a7127ae5 100644 --- a/skills/multi/dingtalk-drive/SKILL.md +++ b/skills/multi/dingtalk-drive/SKILL.md @@ -39,6 +39,7 @@ metadata: |---|---|---| | 全局按名称或关键词找文件 | `dws drive +search --query <关键词>` | 多候选停止；在线文档正文搜索走 `doc +search` | | 浏览根目录或已知文件夹 | `dws drive +list [--folder ]` | 默认一页，处理 nextCursor | +| 发现钉盘企业空间或“我的文件”空间 | `dws wiki space list --type --format json` | Drive 只读前置；orgSpace 按 nextToken 续页，取 spaceId/rootFolderId 后回到 Drive | | 查看最近访问/编辑 | `dws drive +recent [--operate-type 1] --limit ` | 1=最近编辑；默认最近访问 | | 查看节点类型和元数据 | `dws drive +inspect --node ` | 按需加 stats/publish/cover，不为普通列表强制调用 | | 下载普通文件 | `dws drive +download --node --output <相对路径>` | 当前 shortcut 接受 ID；在线文档用 `doc +export` | @@ -48,8 +49,8 @@ metadata: | 移动节点 | `dws drive +move --node --folder <目标ID>` | 破坏性变更，按 Runtime confirmation | | 重命名节点 | `dws drive +rename --node --name <新名称>` | 写后检查最终名称 | | 比较本地与钉盘文件夹 | `dws drive status --local-folder <绝对路径> --remote-folder ` | 只读；默认精确 MD5，不先拉取或推送 | -| 钉盘文件夹拉到本地 | `dws drive pull --local-folder <绝对路径> --remote-folder --if-exists smart` | 先以相同参数 `--dry-run`，再按确认执行 | -| 本地文件夹推到钉盘 | `dws drive push --local-folder <绝对路径> --remote-folder --if-exists smart` | 先 dry-run；不会删除远端多余文件 | +| 钉盘文件夹拉到本地 | `dws drive pull --local-folder <绝对路径> --remote-folder --if-exists skip` | 安全默认不覆盖；先以相同参数 `--dry-run`，再按确认执行 | +| 本地文件夹推到钉盘 | `dws drive push --local-folder <绝对路径> --remote-folder --if-exists skip` | 安全默认不覆盖；先 dry-run；不会删除远端多余文件 | | 双向补齐文件夹 | `dws drive sync --local-folder <绝对路径> --remote-folder --on-conflict skip` | 先 dry-run；冲突策略必须显式保留 | ### 低频入口 @@ -63,6 +64,7 @@ metadata: ## 当前最短路径 - 已知 dentryUuid：直接执行 inspect/download/list/move/rename，禁止先 search；仅确认是受支持的在线文档节点后才执行 copy。 +- 目标 Drive 空间未知：先明确企业空间 `orgSpace` 或“我的文件”`mySpace`，用 `dws wiki space list --type <类型> --format json` 发现空间；`orgSpace` 在 `nextToken` 非空时以 `--cursor ` 续页，`mySpace` 固定单条且不分页。按后续命令取真实 spaceId 或 rootFolderId 后立即回到 Drive；已知这些 ID 时不做空间发现。 - 只有名称：`+search` → 唯一候选的 nodeId → 目标命令；不得自动选择第一项。 - 只有文件夹层级：从最近的已知 folder ID 开始 `+list`，不要从根目录无界递归。 - 上传新文件：单条 `+upload`；不要退回 upload-info + 手写 HTTP + commit。 @@ -117,4 +119,5 @@ Golden Route 参数足够时禁止读取 reference。其余最多读取一个精 - 普通文件/文件夹及在线文档节点的存储管理 → Drive；正文/内容分别走 Doc、Sheet、AITable。 - able 外层移动/重命名走 Drive；结构复制、Base 删除（`+base-delete`）及 Base 内操作走 AITable。 - 明确知识库 workspace 层级 → Wiki；泛称“文档空间/我的文档”仍走 Drive。 +- 钉盘存储空间发现例外地复用 managed `dws wiki space list --type orgSpace|mySpace`；只取真实 spaceId/rootFolderId 后回到 Drive。spaceId 用于空间参数，rootFolderId 才可作为空间根目录 folder；`orgWikiSpace/myWikiSpace` 返回 workspaceId，不能混入 Drive 参数。 - Word/Markdown/Text 转在线文档用 `doc +import`；Drive upload 只保留原文件。 diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 6a50617a..61d7aecc 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -79,6 +79,8 @@ dws drive +publish-unset --node 只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。转移所有者时，在构造最终命令前必须让用户分别明确决定 `--reserve-role ` 和 `--recursive=`；Agent 不得根据默认值、对象类型或便捷性自行选择任一项。两项决策与目标、新所有者均明确后，才按 Runtime confirmation 构造首次正式调用。 +发起权限申请先只读执行 `permission apply-info`。正式 `permission apply` 会通知审批人；调用前必须向用户逐项回显并确认资源、申请角色、审批人和理由。Agent 不得默认选择第一位审批人、最高/最低角色或代写申请理由；用户未明确同意完整申请内容时停在确认环节。 + ## 快捷方式节点 `+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接。在线文档节点需要保留版式的独立副本时使用 `+copy`；普通钉盘文件的独立副本必须经用户授权后走 download→upload，因为当前 `+copy` 会拒绝普通文件。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。 diff --git a/skills/multi/dingtalk-drive/references/folder-sync.md b/skills/multi/dingtalk-drive/references/folder-sync.md index 21499ad8..8f763dc2 100644 --- a/skills/multi/dingtalk-drive/references/folder-sync.md +++ b/skills/multi/dingtalk-drive/references/folder-sync.md @@ -19,14 +19,14 @@ ```bash dws drive status --local-folder /abs/local --remote-folder --format json -dws drive pull --local-folder /abs/local --remote-folder --if-exists smart --dry-run --format json -dws drive push --local-folder /abs/local --remote-folder --if-exists smart --dry-run --format json +dws drive pull --local-folder /abs/local --remote-folder --if-exists skip --dry-run --format json +dws drive push --local-folder /abs/local --remote-folder --if-exists skip --dry-run --format json dws drive sync --local-folder /abs/local --remote-folder --on-conflict skip --dry-run --format json ``` ## 策略 -- pull/push `--if-exists`: `skip` 最保守；`smart` 按修改时间做增量；`overwrite` 以来源侧覆盖目标侧。 +- pull/push `--if-exists`: `skip` 是不覆盖的安全默认；`smart` 按修改时间做增量；`overwrite` 以来源侧覆盖目标侧。用户未明确选择覆盖策略时，Agent 必须保留 `skip`，不得代选 `smart/overwrite`；只有回显 dry-run 的覆盖项并得到明确授权后，才使用后两者。 - sync `--on-conflict`: `skip` 默认保留两侧；`remote-wins` 覆盖本地；`local-wins` 覆盖远端；`keep-both` 先改名本地再拉远端；`ask` 需要交互。 - 默认 exact 通过 MD5 比较；远端缺少可靠 MD5 时进入 `unknown` 并跳过。只有用户接受时间戳近似时才加 `--quick`。 - 这些命令只处理普通 `type=file` 和目录；在线文档、快捷方式不会按普通二进制同步。 diff --git a/skills/multi/dingtalk-drive/references/intent-guide.md b/skills/multi/dingtalk-drive/references/intent-guide.md index a09c4ca3..fb105176 100644 --- a/skills/multi/dingtalk-drive/references/intent-guide.md +++ b/skills/multi/dingtalk-drive/references/intent-guide.md @@ -2,7 +2,8 @@ | 用户表达 | 应用 | 不应用 | 理由 | |---|---|---|---| -| 全局找文件、最近文件、我的文件/文档空间目录 | Drive | Wiki | 未限定知识库 workspace，属于普通存储域 | +| 全局找文件、最近文件、浏览已知“我的文件”/文档空间目录 | Drive | Wiki node | 未限定知识库 workspace，属于普通存储域 | +| 列出/发现钉盘企业空间或“我的文件”空间 | managed `dws wiki space list --type orgSpace|mySpace` 发现 spaceId/rootFolderId 后回 Drive | `wiki +space-list` 的 orgWikiSpace/myWikiSpace | Drive 存储空间前置；spaceId、rootFolderId 与知识库 workspaceId 不可互换 | | 明确知识库内列节点、移动节点、搜索节点 | Wiki | Drive | workspace 内层级由 Wiki 管理 | | 普通文件或文件夹移动、重命名、删除 | Drive | Doc | 节点存储动作不修改正文 | | 普通文件创建独立副本 | Drive download→upload | Drive `+copy` | 当前 `+copy` 会拒绝普通钉盘文件，避免把 `.dlink` 快捷方式伪装成副本 | diff --git a/skills/multi/dingtalk-wiki/SKILL.md b/skills/multi/dingtalk-wiki/SKILL.md index 317cf5ba..15229697 100644 --- a/skills/multi/dingtalk-wiki/SKILL.md +++ b/skills/multi/dingtalk-wiki/SKILL.md @@ -42,6 +42,7 @@ metadata: |---|---|---| | 按名称解析唯一知识库 | `+space-list --type --limit 50 --page-all` 后精确匹配名称 | 先明确组织/个人范围；仅 `autoPageComplete=true` 且全量中恰好一个同名项时取 workspaceId | | 搜索或列出知识库 | `+space-search --query <关键词>` / `+space-list [--type orgWikiSpace\|myWikiSpace]` | 用户要求全部时加 `--page-all`；个人知识库必须明确语义 | +| 为 Drive 发现钉盘存储空间 | `dws wiki space list --type --format json` | managed 只读前置；返回 spaceId/rootFolderId 后切回 Drive，不进入 Wiki node/member 路由 | | 已知 workspace 查看详情 | `dws wiki +space-get --workspace ` | 已知 ID 不重复搜索 | | 创建或删除知识库 | `+space-create --name <名称>` / `+delete-space --workspace ` | 创建会读回；删除整个空间是高风险操作 | | 浏览或搜索库内节点 | `+node-list --workspace [--folder ]` / `+node-search --workspace --query <词>` | 列目录与关键词搜索分开；全量列表加 `--page-all` | @@ -61,7 +62,7 @@ metadata: - 已知 nodeId/URL：元数据直接 `+node-get`；正文直接切 Doc，不先 list/search。 - 创建节点后返回的 nodeId 直接传给 Doc；不通过同名搜索重新定位。 - move/copy/delete 已含预检或读回时，不由 Agent 重复拼装原子命令。 -- 普通“文档空间/我的文档”不先调用 Wiki 获取默认位置，按存储意图走 Drive。 +- 普通“文档空间/我的文档”的文件操作按存储意图走 Drive；仅当缺少 Drive spaceId/rootFolderId、需要发现 `orgSpace/mySpace` 时调用 managed `wiki space list`。`orgSpace` 以返回的 nextToken 续页，`mySpace` 不分页；取 ID 后立即回到 Drive。 ## 关键结果语义 @@ -106,4 +107,5 @@ Golden Route 参数足够时不读 reference；否则最多读取一个： - 明确知识库容器、成员、库内层级与动态 → Wiki。 - 锁定库内 adoc 节点后的正文读写/导出 → Doc；axls 内容 → Sheet；able 记录/字段 → AITable。 - 普通文件、文件夹、“我的文档/文档空间”的存储搜索、传输和整理 → Drive。 +- Drive 存储空间发现可复用 managed `wiki space list --type orgSpace|mySpace`；结果是 spaceId/rootFolderId，不能交给 Wiki node/member。知识库 `orgWikiSpace/myWikiSpace` 仍返回 workspaceId。 - Wiki 节点移入/移出使用 `+move/+move-to-drive`；不要把 workspaceId 当普通 Drive folderId。 diff --git a/skills/multi/dingtalk-wiki/references/intent-guide.md b/skills/multi/dingtalk-wiki/references/intent-guide.md index a4b9e203..85ec59b5 100644 --- a/skills/multi/dingtalk-wiki/references/intent-guide.md +++ b/skills/multi/dingtalk-wiki/references/intent-guide.md @@ -5,7 +5,8 @@ | 用户说... | 真实意图 | 应该用 | 不要用 | 理由 | |---|---|---|---|---| | "帮我看看知识库里的文件" | 知识库节点列表 | `dws wiki +node-list --workspace ` | `dws drive +list` | 明确“知识库”上下文，使用 Wiki 层级 | -| "列出钉盘/文档空间" | 普通存储根目录 | `dws drive +list` | `dws wiki +space-list` | 未明确知识库，属于 Drive 存储域 | +| "浏览已知钉盘/文档空间目录" | 普通存储目录 | `dws drive +list` | `dws wiki +node-list` | 已有 space/folder 目标，文件层级属于 Drive | +| "列出/发现钉盘企业空间或我的文件空间" | Drive 存储空间发现 | `dws wiki space list --type orgSpace|mySpace`，取 spaceId/rootFolderId 后回 Drive | `dws wiki +space-list --type orgWikiSpace|myWikiSpace` | managed Wiki leaf 兼容存储空间发现；Drive ID 不能当 workspaceId | | "列出组织知识库" | 列出组织知识库容器 | `dws wiki +space-list --type orgWikiSpace --page-all` | `dws drive +list` | 明确知识库容器，使用当前 Wiki 类型枚举 | | "在知识库里搜方案" | 空间内搜索 | `dws wiki +node-search --workspace --query <词>` | `dws drive +search` | 指定知识库上下文，使用 Wiki 节点搜索 | | "搜一下有没有叫XX的文件" | 全局搜索 | `dws drive +search --query <词>` | `dws wiki +node-search` | 未指定知识库，使用 Drive 全局聚合搜索 | diff --git a/skills/multi/dingtalk-wiki/references/wiki-members.md b/skills/multi/dingtalk-wiki/references/wiki-members.md index 3ac09fe3..ee571769 100644 --- a/skills/multi/dingtalk-wiki/references/wiki-members.md +++ b/skills/multi/dingtalk-wiki/references/wiki-members.md @@ -12,6 +12,9 @@ dws wiki +member-remove --workspace --users --format json - `--users` 接受 1-30 个真实 userId；姓名先由联系人/人员搜索产品解析，不能直接当 userId。 - 角色仅 `MANAGER|EDITOR|DOWNLOADER|READER`，修改前必须由用户明确角色。 - workspaceId 来自当前 profile 下真实知识库；不能跨组织复用。 +- 成员接口仅用于组织知识库。`myWikiSpace` 是个人空间，不支持容器级成员管理；若用户只想分享其中某个节点，改走 Drive 节点级权限。 +- `OWNER` 不在成员角色枚举中，不能通过 add/update/remove 创建、降级或移除所有者；所有权变更必须走对应所有者转移能力并遵守其独立确认约束。 +- 调用者需要知识库 OWNER 或 MANAGER 权限；权限不足时如实返回，不切账号或改用节点权限绕过容器规则。 ## 列表完整性 From 089c5491ecd9fe84962d2b2aeebc46600e2a74ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 14:25:59 +0800 Subject: [PATCH 215/250] feat(aitable): streamline agent routes and table setup --- docs/shortcut-public-catalog.json | 14 +- internal/app/schema_shortcut_contract_test.go | 6 +- internal/shortcut/aitable/aitable.go | 1 + internal/shortcut/aitable/base_composite.go | 29 +- .../aitable/base_composite_e2e_test.go | 19 + internal/shortcut/aitable/composite_output.go | 26 +- internal/shortcut/aitable/table_bootstrap.go | 159 +++++ .../aitable/table_bootstrap_e2e_test.go | 159 +++++ .../builtin/aitable_semantic_catalog_test.go | 4 +- internal/shortcut/public_catalog_generated.go | 1 + .../shortcut/semantic_catalog_aitable.json | 1 + scripts/gen_skill_shortcut_sections.py | 2 +- skills/mono/SKILL.md | 2 +- skills/multi/dingtalk-aitable/SKILL.md | 261 +++----- .../references/aitable-record-ops.md | 154 ++--- .../references/aitable-section.md | 28 + .../dingtalk-aitable/references/aitable.md | 564 +++--------------- .../aitable/aitable-dashboard-chart.md | 13 +- .../references/aitable/aitable-primary-doc.md | 9 +- .../references/aitable/aitable-view-config.md | 20 +- .../references/intent-guide.md | 22 +- 21 files changed, 686 insertions(+), 808 deletions(-) create mode 100644 internal/shortcut/aitable/table_bootstrap.go create mode 100644 internal/shortcut/aitable/table_bootstrap_e2e_test.go create mode 100644 skills/multi/dingtalk-aitable/references/aitable-section.md diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index c391663b..88a1e7ec 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,6 +1,6 @@ { - "generated_at": "2026-08-17T15:52:13.675461", - "count": 435, + "generated_at": "2026-08-18T14:20:44.224405", + "count": 436, "results": [ { "suite": "semantic", @@ -692,6 +692,16 @@ "semantic_delta": "按当前父目录语义调整文件夹展示顺序。", "availability": "available" }, + { + "suite": "semantic", + "service": "aitable", + "command": "+table-bootstrap", + "risk": "write", + "status": "reviewed_available", + "disposition": "primary_smart", + "semantic_delta": "在已有 Base 中声明式创建一张表和字段，字段自动分片，逐层读回验证并发布可恢复检查点。", + "availability": "available" + }, { "suite": "semantic", "service": "aitable", diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 6fc37da5..55818b10 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -16,12 +16,12 @@ import ( ) const ( - publicShortcutCount = 434 + publicShortcutCount = 435 // schemaPublishedShortcutCount counts every delivered *.shortcut_* tool, // including the hidden historical minutes.shortcut_minutes_search contract. - schemaPublishedShortcutCount = 437 + schemaPublishedShortcutCount = 438 // publiclyDeliveredShortcutCount is the public-catalog subset of that surface. - publiclyDeliveredShortcutCount = 434 + publiclyDeliveredShortcutCount = 435 ) func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) { diff --git a/internal/shortcut/aitable/aitable.go b/internal/shortcut/aitable/aitable.go index 2d1a9d64..d36cd18c 100644 --- a/internal/shortcut/aitable/aitable.go +++ b/internal/shortcut/aitable/aitable.go @@ -3110,6 +3110,7 @@ func init() { BaseSchemaSnapshot, BaseBootstrap, TableGet, + TableBootstrap, TableCopy, TableUpdate, TableDelete, diff --git a/internal/shortcut/aitable/base_composite.go b/internal/shortcut/aitable/base_composite.go index bcbae88e..fd40a21f 100644 --- a/internal/shortcut/aitable/base_composite.go +++ b/internal/shortcut/aitable/base_composite.go @@ -50,7 +50,7 @@ var BaseBootstrap = shortcut.Shortcut{ "+base-bootstrap", "一次创建 Base、数据表和字段，逐层读回验证并在中断时报告已知副作用", "当你已有声明式 tables JSON、想一次搭好一套 AI 表格结构时使用；表内字段自动按 15 个拆批，每次创建都读回验证。", - "已有 Base 只需新增一张表时用 table create；复制现有 Base 用 base copy；不要对失败请求盲目重试", + "已有 Base 只需新增一张表时用 +table-bootstrap；复制现有 Base 用 +base-copy；不要对失败请求盲目重试", `dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[]}]'`, ), Flags: []shortcut.Flag{ @@ -73,25 +73,25 @@ type bootstrapTable struct { func parseBootstrapTables(raw string) ([]bootstrapTable, error) { value, err := parseJSONAny("tables", raw) if err != nil { - return nil, err + return nil, baseBootstrapValidation(fmt.Sprintf("--tables 不是合法 JSON 数组：%v", err)) } items, ok := value.([]any) if !ok || len(items) == 0 { - return nil, apperrors.NewValidation("--tables 必须是非空 JSON 数组") + return nil, baseBootstrapValidation("--tables 必须是非空 JSON 数组") } if len(items) > 100 { - return nil, apperrors.NewValidation("--tables 最多接受 100 张表") + return nil, baseBootstrapValidation("--tables 最多接受 100 张表") } seen := map[string]bool{} out := make([]bootstrapTable, 0, len(items)) for index, item := range items { object, ok := item.(map[string]any) if !ok { - return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index)) + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index)) } name := strings.TrimSpace(stringValue(object, "name")) if name == "" || seen[name] { - return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index)) + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index)) } seen[name] = true fields := []any{} @@ -99,13 +99,13 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) { var fieldsOK bool fields, fieldsOK = rawFields.([]any) if !fieldsOK { - return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index)) + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index)) } } for fieldIndex, field := range fields { object, ok := field.(map[string]any) if !ok || strings.TrimSpace(stringValue(object, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(object, "type")) == "" { - return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex)) + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex)) } } out = append(out, bootstrapTable{Name: name, Fields: fields}) @@ -113,6 +113,14 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) { return out, nil } +func baseBootstrapValidation(message string) error { + return apperrors.NewValidation(message, + apperrors.WithHint("tables 使用 [{\"name\":\"任务\",\"fields\":[{\"fieldName\":\"标题\",\"type\":\"text\"}]}]；已知参数时不要先调用 --help"), + apperrors.WithActions(`dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[{"fieldName":"标题","type":"text"}]}]'`), + apperrors.WithAvailableFlags("name", "folder-id", "template-id", "tables"), + ) +} + func executeBaseSchemaSnapshot(rt *shortcut.RuntimeContext) error { baseID := rt.Str("base-id") base, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID}) @@ -196,6 +204,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { result.Status = "unknown" result.FailedCount = len(tables) result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying"} + result.NextCommand = fmt.Sprintf("dws aitable +base-search --query %q --format json", rt.Str("name")) return compositeError(result, err, false) } baseID := findStringByKeys(baseData, "baseId") @@ -203,9 +212,11 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { result.Status = "unknown" result.Result = baseData result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying"} + result.NextCommand = fmt.Sprintf("dws aitable +base-search --query %q --format json", rt.Str("name")) return compositeError(result, fmt.Errorf("create_base response is missing baseId"), false) } result.Resolved = map[string]any{"baseId": baseID} + result.NextCommand = fmt.Sprintf("dws aitable +base-get --base-id %s --format json", baseID) result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_base", "baseId": baseID}) result.CompletedSteps = append(result.CompletedSteps, compositeStep{Index: 1, Name: "create base", Tool: "create_base", Status: "completed", Result: baseData}) baseRead, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID}) @@ -237,6 +248,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { return compositeError(result, createErr, false) } result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": tableID, "name": spec.Name}) + result.NextCommand = fmt.Sprintf("dws aitable +table-get --base-id %s --table-id %s --format json", baseID, tableID) for offset := initialEnd; offset < len(spec.Fields); offset += 15 { end := minInt(offset+15, len(spec.Fields)) _, fieldErr := rt.CallMCPWriteDataStrict(serverMain, "create_fields", map[string]any{ @@ -275,6 +287,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { } result.Verification = map[string]any{"status": "verified", "baseId": baseID, "tableCount": len(createdTables)} result.Result = map[string]any{"baseId": baseID, "tables": createdTables} + result.NextCommand = "" return rt.Output(result) } diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index 1cef390e..ee1f00a2 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -238,6 +238,10 @@ func TestCrossPlatformCoverageBaseBootstrapExecuteRejectsInvalidTablesE2E(t *tes if err == nil || out != "" { t.Fatalf("invalid bootstrap tables = output:%q err:%v", out, err) } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 || len(typed.AvailableFlags) != 4 { + t.Fatalf("invalid bootstrap recovery = %#v", err) + } } func TestCrossPlatformCoverageBaseBootstrapFailureStagesE2E(t *testing.T) { @@ -275,6 +279,21 @@ func TestCrossPlatformCoverageBaseBootstrapFailureStagesE2E(t *testing.T) { } } +func TestCrossPlatformCoverageBaseBootstrapFailurePublishesExactRecovery(t *testing.T) { + out, err := runAITableCompositeCLI(t, &upsertByKeyCaller{steps: []upsertByKeyStep{{text: `{}`}}}, + "+base-bootstrap", "--name", "Project", "--tables", marshalBootstrapTables(t, nil), "--yes") + if out != "" || err == nil { + t.Fatalf("bootstrap recovery = output:%q err:%v", out, err) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 || len(typed.AvailableFlags) != 4 { + t.Fatalf("bootstrap typed recovery = %#v", err) + } + if typed.Actions[0] != `dws aitable +base-search --query "Project" --format json` { + t.Fatalf("bootstrap next command = %#v", typed.Actions) + } +} + func TestCrossPlatformCoverageBaseBootstrapRecoversFieldCallErrorE2E(t *testing.T) { fields := bootstrapFields(16) caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ diff --git a/internal/shortcut/aitable/composite_output.go b/internal/shortcut/aitable/composite_output.go index d67d4e45..a1b91d5a 100644 --- a/internal/shortcut/aitable/composite_output.go +++ b/internal/shortcut/aitable/composite_output.go @@ -57,15 +57,33 @@ func compositeError(result compositeResult, cause error, retryable bool) error { if result.Status == "success" { result.Status = "unknown" } - return apperrors.NewAPI(fmt.Sprintf("AI Table composite %s ended with status %s", result.Operation, result.Status), - apperrors.WithOperation("aitable."+result.Operation), + options := []apperrors.Option{ + apperrors.WithOperation("aitable." + result.Operation), apperrors.WithOrigin("mcp"), apperrors.WithFailureStage("composite_execution"), apperrors.WithExecutionStarted(result.Executed), apperrors.WithRetryable(retryable), - apperrors.WithReason("aitable_composite_"+result.Status), + apperrors.WithReason("aitable_composite_" + result.Status), apperrors.WithHint("inspect error.details.result before retrying; unknown means the remote effect could not be proven"), apperrors.WithDetails(map[string]any{"result": result}), apperrors.WithCause(cause), - ) + } + if result.NextCommand != "" { + options = append(options, apperrors.WithActions(result.NextCommand)) + } + if flags := compositeRecoveryFlags(result.Operation); len(flags) > 0 { + options = append(options, apperrors.WithAvailableFlags(flags...)) + } + return apperrors.NewAPI(fmt.Sprintf("AI Table composite %s ended with status %s", result.Operation, result.Status), options...) +} + +func compositeRecoveryFlags(operation string) []string { + switch operation { + case "base_bootstrap": + return []string{"name", "folder-id", "template-id", "tables"} + case "table_bootstrap": + return []string{"base-id", "name", "fields"} + default: + return nil + } } diff --git a/internal/shortcut/aitable/table_bootstrap.go b/internal/shortcut/aitable/table_bootstrap.go new file mode 100644 index 00000000..c06b9e71 --- /dev/null +++ b/internal/shortcut/aitable/table_bootstrap.go @@ -0,0 +1,159 @@ +// Copyright 2026 Alibaba Group +// SPDX-License-Identifier: Apache-2.0 + +package aitable + +import ( + "fmt" + "strings" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +var TableBootstrap = shortcut.Shortcut{ + Service: "aitable", + Command: "+table-bootstrap", + Product: serverMain, + Description: "在已有 Base 中一次创建数据表和字段，自动分片并读回验证", + Intent: "当你已有 baseId、需要新增一张带完整字段结构的数据表时使用；替代 table create 后连续 field create 和手工验证。", + Risk: shortcut.RiskWrite, + Safety: contract.SafetySpec{ + Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "non_idempotent", + }, + Contract: aitableCompositeContract( + "+table-bootstrap", + "在已有 Base 中一次创建数据表和字段，自动分片并读回验证", + "当你已有 baseId、需要新增一张带完整字段结构的数据表时使用；替代 table create 后连续 field create 和手工验证。", + "需要同时新建 Base 用 +base-bootstrap；复制现有表用 +table-copy；只补字段用 field create", + `dws aitable +table-bootstrap --base-id BASE_ID --name "任务" --fields '[{"fieldName":"标题","type":"text"}]'`, + ), + Flags: []shortcut.Flag{ + {Name: "base-id", Type: shortcut.FlagString, Desc: "目标 Base ID", Required: true}, + {Name: "name", Type: shortcut.FlagString, Desc: "新数据表名称", Required: true}, + {Name: "fields", Type: shortcut.FlagString, Desc: "字段结构 JSON 数组；字段对象使用 fieldName/type/config", Required: true}, + }, + Tips: []string{ + `dws aitable +table-bootstrap --base-id BASE_ID --name "任务" --fields '[{"fieldName":"标题","type":"text"}]'`, + }, + Execute: func(rt *shortcut.RuntimeContext) error { + return executeTableBootstrap(rt) + }, +} + +type createdTableStructure struct { + TableID string + Fields []map[string]any + Warnings []string +} + +func parseBootstrapFields(raw string) ([]any, error) { + value, err := parseJSONAny("fields", raw) + if err != nil { + return nil, tableBootstrapValidation(fmt.Sprintf("--fields 不是合法 JSON 数组：%v", err)) + } + fields, ok := value.([]any) + if !ok { + return nil, tableBootstrapValidation("--fields 必须是 JSON 数组") + } + if len(fields) > 100 { + return nil, tableBootstrapValidation("--fields 最多接受 100 个字段") + } + for index, rawField := range fields { + field, ok := rawField.(map[string]any) + if !ok || strings.TrimSpace(stringValue(field, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(field, "type")) == "" { + return nil, tableBootstrapValidation(fmt.Sprintf("--fields[%d] 必须包含 fieldName 和 type", index)) + } + } + return fields, nil +} + +func tableBootstrapValidation(message string) error { + return apperrors.NewValidation(message, + apperrors.WithHint("字段对象使用 fieldName/type/config；已知参数时直接执行，不需要先调用 --help"), + apperrors.WithActions(`dws aitable +table-bootstrap --base-id BASE_ID --name "任务" --fields '[{"fieldName":"标题","type":"text"}]'`), + apperrors.WithAvailableFlags("base-id", "name", "fields"), + ) +} + +func executeTableBootstrap(rt *shortcut.RuntimeContext) error { + fields, err := parseBootstrapFields(rt.Str("fields")) + if err != nil { + return err + } + baseID, tableName := rt.Str("base-id"), rt.Str("name") + result := newCompositeResult("table_bootstrap") + result.RequestedCount = len(fields) + result.Resolved = map[string]any{"baseId": baseID, "tableName": tableName} + result.Plan = []compositeStep{{Index: 1, Name: "create and verify table", Tool: "create_table", Status: "planned", Count: len(fields)}} + if rt.DryRun() { + result.Status = "planned" + result.Executed = false + return rt.Output(result) + } + + created, err := createAndVerifyTableStructure(rt, baseID, tableName, fields) + result.Warnings = append(result.Warnings, created.Warnings...) + if created.TableID != "" { + result.Resolved["tableId"] = created.TableID + result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": created.TableID, "name": tableName}) + result.NextCommand = fmt.Sprintf("dws aitable +table-get --base-id %s --table-id %s --format json", baseID, created.TableID) + } + if err != nil { + if created.TableID == "" { + result.Status = "unknown" + result.Checkpoint = map[string]any{"step": "resolve table by exact name before retrying", "baseId": baseID, "tableName": tableName} + } else { + result.Status = "partial_success" + result.Checkpoint = map[string]any{"step": "verify or repair table fields", "baseId": baseID, "tableId": created.TableID} + } + return compositeError(result, err, false) + } + + result.CompletedCount = len(fields) + result.CompletedSteps = []compositeStep{{Index: 1, Name: "create and verify table", Tool: "create_table", Status: "completed", Count: len(fields), Result: map[string]any{"tableId": created.TableID, "fieldCount": len(created.Fields)}}} + result.Verification = map[string]any{"status": "verified", "baseId": baseID, "tableId": created.TableID, "fieldCount": len(created.Fields)} + result.Result = map[string]any{"baseId": baseID, "tableId": created.TableID, "tableName": tableName, "fields": created.Fields} + result.NextCommand = "" + return rt.Output(result) +} + +func createAndVerifyTableStructure(rt *shortcut.RuntimeContext, baseID, tableName string, fields []any) (createdTableStructure, error) { + created := createdTableStructure{} + initialEnd := minInt(15, len(fields)) + createData, err := rt.CallMCPWriteDataStrict(serverMain, "create_table", map[string]any{ + "baseId": baseID, "tableName": tableName, "fields": fields[:initialEnd], + }) + created.TableID = findStringByKeys(createData, "tableId", "sheetId") + if err != nil || created.TableID == "" { + if err == nil { + err = fmt.Errorf("create_table response is missing tableId") + } + return created, err + } + for offset := initialEnd; offset < len(fields); offset += 15 { + end := minInt(offset+15, len(fields)) + if _, fieldErr := rt.CallMCPWriteDataStrict(serverMain, "create_fields", map[string]any{ + "baseId": baseID, "tableId": created.TableID, "fields": fields[offset:end], + }); fieldErr != nil { + created.Warnings = append(created.Warnings, fmt.Sprintf("create_fields offset %d returned an error; final read-back decides success: %v", offset, fieldErr)) + } + } + detail, err := rt.CallMCPData(serverMain, "get_tables", map[string]any{"baseId": baseID, "tableIds": []string{created.TableID}}) + if err != nil || !deepContainsString(detail, created.TableID) { + if err == nil { + err = fmt.Errorf("get_tables does not identify created tableId %s", created.TableID) + } + return created, err + } + fieldsData, err := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": baseID, "tableId": created.TableID}) + created.Fields, _ = findNamedObjectList(fieldsData, "fields", "fieldList") + if err != nil || created.Fields == nil || !containsAllFieldNames(created.Fields, fields) { + if err == nil { + err = fmt.Errorf("field read-back for table %s does not contain the declared field set", created.TableID) + } + return created, err + } + return created, nil +} diff --git a/internal/shortcut/aitable/table_bootstrap_e2e_test.go b/internal/shortcut/aitable/table_bootstrap_e2e_test.go new file mode 100644 index 00000000..140f3d2f --- /dev/null +++ b/internal/shortcut/aitable/table_bootstrap_e2e_test.go @@ -0,0 +1,159 @@ +// Copyright 2026 Alibaba Group +// SPDX-License-Identifier: Apache-2.0 + +package aitable + +import ( + "encoding/json" + "errors" + "strings" + "testing" + + apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" +) + +func TestCrossPlatformCoverageTableBootstrapCreatesChunksAndVerifies(t *testing.T) { + fields := bootstrapFields(16) + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: `{"data":{"tableId":"table-new"}}`}, + {text: `{"data":{"createdFields":[{"fieldId":"f16"}]}}`}, + {text: `{"data":{"tables":[{"tableId":"table-new","tableName":"任务"}]}}`}, + {text: fieldReadBackJSON(t, fields)}, + }} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", mustJSON(t, fields), "--yes") + if err != nil { + t.Fatalf("table bootstrap error = %v", err) + } + for _, want := range []string{`"operation": "table_bootstrap"`, `"tableId": "table-new"`, `"status": "verified"`} { + if !strings.Contains(out, want) { + t.Fatalf("table bootstrap output missing %s: %s", want, out) + } + } + if got := len(caller.calls); got != 4 { + t.Fatalf("table bootstrap calls = %d, want 4: %#v", got, caller.calls) + } + if caller.calls[0].tool != "create_table" || caller.calls[1].tool != "create_fields" || caller.calls[2].tool != "get_tables" || caller.calls[3].tool != "get_fields" { + t.Fatalf("table bootstrap call order = %#v", caller.calls) + } + if got := len(caller.calls[0].args["fields"].([]any)); got != 15 { + t.Fatalf("initial fields = %d, want 15", got) + } + if got := len(caller.calls[1].args["fields"].([]any)); got != 1 { + t.Fatalf("remaining fields = %d, want 1", got) + } +} + +func TestCrossPlatformCoverageTableBootstrapValidationPublishesRecovery(t *testing.T) { + caller := &upsertByKeyCaller{} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", `{}`, "--yes") + if out != "" || err == nil || len(caller.calls) != 0 { + t.Fatalf("validation = output:%q err:%v calls:%#v", out, err, caller.calls) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 || len(typed.AvailableFlags) != 3 { + t.Fatalf("typed validation recovery = %#v", err) + } +} + +func TestCrossPlatformCoverageTableBootstrapInputValidation(t *testing.T) { + tooMany := bootstrapFields(101) + cases := map[string]string{ + "invalid JSON": `{`, + "not an array": `{}`, + "too many fields": mustJSON(t, tooMany), + "non-object field": `[1]`, + "field missing type": `[{"fieldName":"标题"}]`, + } + for name, raw := range cases { + t.Run(name, func(t *testing.T) { + fields, err := parseBootstrapFields(raw) + if err == nil || fields != nil { + t.Fatalf("parseBootstrapFields(%q) = %#v, %v", raw, fields, err) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 || len(typed.AvailableFlags) != 3 { + t.Fatalf("typed validation recovery = %#v", err) + } + }) + } +} + +func TestCrossPlatformCoverageTableBootstrapDryRun(t *testing.T) { + caller := &upsertByKeyCaller{dryRun: true} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", `[]`, "--dry-run") + if err != nil || len(caller.calls) != 0 || !strings.Contains(out, `"status": "planned"`) { + t.Fatalf("table bootstrap dry run = output:%q err:%v calls:%#v", out, err, caller.calls) + } +} + +func TestCrossPlatformCoverageTableBootstrapFailureStages(t *testing.T) { + oneField := bootstrapFields(1) + cases := []struct { + name string + fields []any + steps []upsertByKeyStep + }{ + {name: "create table error", fields: oneField, steps: []upsertByKeyStep{{err: errors.New("create table failed")}}}, + {name: "create table missing id", fields: oneField, steps: []upsertByKeyStep{{text: `{}`}}}, + {name: "get tables error", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {err: errors.New("get tables failed")}}}, + {name: "get tables wrong id", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"other"}]}`}}}, + {name: "get fields error", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {err: errors.New("get fields failed")}}}, + {name: "get fields missing collection", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{}`}}}, + {name: "get fields mismatch", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{"fields":[]}`}}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + caller := &upsertByKeyCaller{steps: tc.steps} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", mustJSON(t, tc.fields), "--yes") + if out != "" || err == nil { + t.Fatalf("table bootstrap failure = output:%q err:%v calls:%#v", out, err, caller.calls) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Retryable { + t.Fatalf("typed table bootstrap failure = %#v", err) + } + }) + } +} + +func TestCrossPlatformCoverageTableBootstrapRecoversFieldCallError(t *testing.T) { + fields := bootstrapFields(16) + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: `{"tableId":"table-new"}`}, + {err: errors.New("create fields reply failed")}, + {text: `{"tables":[{"tableId":"table-new"}]}`}, + {text: fieldReadBackJSON(t, fields)}, + }} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", mustJSON(t, fields), "--yes") + if err != nil || !strings.Contains(out, `"status": "success"`) || !strings.Contains(out, "create_fields offset") { + t.Fatalf("field recovery = output:%q err:%v calls:%#v", out, err, caller.calls) + } +} + +func TestCrossPlatformCoverageCompositeRecoveryFlags(t *testing.T) { + cases := map[string][]string{ + "base_bootstrap": {"name", "folder-id", "template-id", "tables"}, + "table_bootstrap": {"base-id", "name", "fields"}, + "base_schema_snapshot_unmapped": nil, + } + for operation, want := range cases { + got := compositeRecoveryFlags(operation) + if mustJSON(t, got) != mustJSON(t, want) { + t.Fatalf("compositeRecoveryFlags(%q) = %#v, want %#v", operation, got, want) + } + } +} + +func mustJSON(t *testing.T, value any) string { + t.Helper() + raw, err := json.Marshal(value) + if err != nil { + t.Fatal(err) + } + return string(raw) +} diff --git a/internal/shortcut/builtin/aitable_semantic_catalog_test.go b/internal/shortcut/builtin/aitable_semantic_catalog_test.go index f1010075..9f29f8aa 100644 --- a/internal/shortcut/builtin/aitable_semantic_catalog_test.go +++ b/internal/shortcut/builtin/aitable_semantic_catalog_test.go @@ -36,8 +36,8 @@ func TestCrossPlatformCoverageAITableSemanticCatalogExactlyCoversRegisteredSurfa } registered[item.Command] = item } - if len(registered) != 92 || len(source.Shortcuts) != 92 { - t.Fatalf("registered/catalog = %d/%d, want 92/92", len(registered), len(source.Shortcuts)) + if len(registered) != 93 || len(source.Shortcuts) != 93 { + t.Fatalf("registered/catalog = %d/%d, want 93/93", len(registered), len(source.Shortcuts)) } var missing, stale []string diff --git a/internal/shortcut/public_catalog_generated.go b/internal/shortcut/public_catalog_generated.go index 6bb77e11..0aba731a 100644 --- a/internal/shortcut/public_catalog_generated.go +++ b/internal/shortcut/public_catalog_generated.go @@ -75,6 +75,7 @@ func generatedPublicShortcutCatalog() map[string]struct{} { "aitable\u0000+section-move-node": {}, "aitable\u0000+section-rename": {}, "aitable\u0000+section-reorder": {}, + "aitable\u0000+table-bootstrap": {}, "aitable\u0000+table-copy": {}, "aitable\u0000+table-delete": {}, "aitable\u0000+table-get": {}, diff --git a/internal/shortcut/semantic_catalog_aitable.json b/internal/shortcut/semantic_catalog_aitable.json index f824e8c8..007c4f82 100644 --- a/internal/shortcut/semantic_catalog_aitable.json +++ b/internal/shortcut/semantic_catalog_aitable.json @@ -15,6 +15,7 @@ "+url-resolve": {"disposition":"primary_smart","semantic_delta":"严格解析 alidocs AI 表格 URL 的 base/table/view/record ID，并可通过最深层只读接口验证目标存在。","risk":"read","public":true,"reviewed":true}, "+table-get": {"disposition":"semantic_adapter","semantic_delta":"批量读取表级信息、字段和视图目录，为后续 Schema 与记录操作提供 ID。","risk":"read","public":true,"reviewed":true}, + "+table-bootstrap": {"disposition":"primary_smart","semantic_delta":"在已有 Base 中声明式创建一张表和字段，字段自动分片，逐层读回验证并发布可恢复检查点。","risk":"write","public":true,"reviewed":true}, "+table-copy": {"disposition":"primary_smart","semantic_delta":"在没有服务端 table-copy task 的情况下，本地重建安全字段、映射 fieldId，并可分片复制及读回验证全部记录。","risk":"write","public":true,"reviewed":true}, "+table-update": {"disposition":"schema_leaf","semantic_delta":"统一表名、备注和行命名规则的 PATCH 风格更新。","risk":"write","public":true,"reviewed":true}, "+table-delete": {"disposition":"schema_leaf","semantic_delta":"不可逆删除数据表的一对一入口，显式发布高风险确认事实。","risk":"high-risk-write","public":true,"reviewed":true}, diff --git a/scripts/gen_skill_shortcut_sections.py b/scripts/gen_skill_shortcut_sections.py index c3567160..1df63b03 100644 --- a/scripts/gen_skill_shortcut_sections.py +++ b/scripts/gen_skill_shortcut_sections.py @@ -59,7 +59,7 @@ RUNTIME_CONTRACT_END = "" # here only after verifying that the product skill has its own reviewed routing # section and intent table; compacting a sparse skill without an alternative # route would make its shortcuts harder to discover. -COMPACT_PRODUCT_SERVICES = {"chat", "doc", "drive"} +COMPACT_PRODUCT_SERVICES = {"aitable", "chat", "doc", "drive"} def md_escape(value: Any) -> str: diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index e935f590..189ffbad 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -43,7 +43,7 @@ cli_version: ">=1.0.15" | 服务 | shortcut 数 | multi skill | |---|---:|---| -| `aitable` | 92 | `dingtalk-aitable` | +| `aitable` | 93 | `dingtalk-aitable` | | `attendance` | 19 | `dingtalk-misc` | | `calendar` | 27 | `dingtalk-calendar` | | `chat` | 98 | `dingtalk-chat` | diff --git a/skills/multi/dingtalk-aitable/SKILL.md b/skills/multi/dingtalk-aitable/SKILL.md index 29b50eb5..b5ab7e79 100644 --- a/skills/multi/dingtalk-aitable/SKILL.md +++ b/skills/multi/dingtalk-aitable/SKILL.md @@ -11,213 +11,104 @@ metadata: # 钉钉 AI 表格 Skill -## 前置条件 — 执行操作前必读 + +## 最小 DWS 执行契约 -> **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。 - -> 命令参考：[aitable.md](references/aitable.md)；复杂命令按需加载 `references/aitable/*.md`；剧本：[06-data-analytics.md](references/06-data-analytics.md)。 +- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。 +- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。 +- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。 +- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。 +- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。 +- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。 +- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。 +- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。 +- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。 + -## Shortcuts（无专用脚本/recipe 时优先） +## Shortcut 发现（按需） -以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "aitable +" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws aitable --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service aitable --format json` 批量发现。 +`aitable` 当前有 93 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图直接使用下方的优先路由、意图表或任务 reference；命令已选中时直接执行，只在参数/安全语义不确定时读取 leaf Schema，在当前 Cobra flags 不确定时读取 leaf Help。 -| Shortcut | 风险 | 适用场景 | -|---|---|---| -| `dws aitable +advperm-disable` | high-risk-write | 关闭指定 Base 的高级权限总开关（所有自定义角色失效） | -| `dws aitable +advperm-enable` | write | 开启指定 Base 的高级权限总开关 | -| `dws aitable +attachment-put` | write | 准备凭证、实际 PUT 本地文件、写入 attachment 单元格并读回验证 | -| `dws aitable +attachment-remove` | high-risk-write | 从 attachment 字段清空全部或按文件名移除，写前确保剩余项具有可重写 fileToken，并读回验证 | -| `dws aitable +attachment-upload` | write | 为 attachment 字段申请 OSS 直传地址（uploadUrl / fileToken） | -| `dws aitable +base-bootstrap` | write | 一次创建 Base、数据表和字段，逐层读回验证并在中断时报告已知副作用 | -| `dws aitable +base-copy` | write | 复制 AI 表格到指定目录（可仅复制结构） | -| `dws aitable +base-delete` | high-risk-write | 删除指定 Base（不可逆） | -| `dws aitable +base-get` | read | 获取指定 Base 的目录信息（tables / dashboards summary） | -| `dws aitable +base-get-primary-doc-id` | read | 根据 baseId/tableId/recordId 获取主键文档的 dentryUuid | -| `dws aitable +base-list` | read | 获取当前用户可访问的 AI 表格 Base 列表（最近访问，支持游标分页） | -| `dws aitable +base-schema-snapshot` | read | 读取 Base、全部数据表、字段和视图的可复用结构快照，并严格校验每层响应 | -| `dws aitable +base-search` | read | 按名称关键词搜索 AI 表格 Base | -| `dws aitable +base-update` | write | 更新 Base 名称（可选备注） | -| `dws aitable +chart-delete` | high-risk-write | 删除指定 chart 及其布局项（不可逆） | -| `dws aitable +chart-get` | read | 获取指定 chart 的详细信息 | -| `dws aitable +chart-share-get` | read | 查询 chart 的分享配置 | -| `dws aitable +chart-share-update` | write | 开启/关闭 chart 分享并可设置分享类型 | -| `dws aitable +chart-update` | write | 更新指定 chart 的配置或布局（--config 必填） | -| `dws aitable +chart-widgets-example` | read | 获取所有图表类型的 widget config 示例 | -| `dws aitable +dashboard-arrange` | write | 对指定仪表盘做服务端智能布局重排 | -| `dws aitable +dashboard-config-example` | read | 获取 dashboard config 的结构示例 | -| `dws aitable +dashboard-delete` | high-risk-write | 删除指定 dashboard（级联删除其 chart，不可逆） | -| `dws aitable +dashboard-get` | read | 获取指定 dashboard 的详细信息（含 charts summary） | -| `dws aitable +dashboard-share-get` | read | 查询 dashboard 的分享配置 | -| `dws aitable +dashboard-share-update` | write | 开启/关闭 dashboard 分享并可设置分享类型 | -| `dws aitable +dashboard-update` | write | 更新指定 dashboard 的配置 | -| `dws aitable +export-data` | read | 导出 AI 表格数据（创建导出任务或按 taskId 续等） | -| `dws aitable +field-delete` | high-risk-write | 删除指定字段（不可逆） | -| `dws aitable +field-get` | read | 批量获取字段详情（含类型相关完整配置） | -| `dws aitable +field-update` | write | 更新字段名称 / 配置 / AI 配置（类型不可改） | -| `dws aitable +find-record` | read | 在指定多维表里按关键词查记录（只读） | -| `dws aitable +form-delete` | high-risk-write | 删除指定表单视图（不可逆） | -| `dws aitable +form-field-hide` | write | 切换表单字段的隐藏/显示状态 | -| `dws aitable +form-field-list` | read | 列出表单视图当前可见的字段及其配置 | -| `dws aitable +form-field-update` | write | 更新表单字段的必填状态或描述 | -| `dws aitable +form-list` | read | 列出指定数据表下的所有表单视图 | -| `dws aitable +form-share-get` | read | 读取视图当前的分享表单配置 | -| `dws aitable +form-share-update` | write | 开启或关闭指定视图的分享表单 | -| `dws aitable +form-update` | write | 更新表单标题 / 描述 | -| `dws aitable +import-data` | write | 将已上传文件导入 AI 表格（新建表或追加到已有表） | -| `dws aitable +import-upload` | write | 为导入任务申请 OSS 直传地址（uploadUrl / importId） | -| `dws aitable +list-tables` | read | 列出某个多维表(base)里的所有数据表（只读，投影 tableId/tableName） | -| `dws aitable +record-bulk-patch` | high-risk-write | 完整查询目标记录后批量合并同一组 cells，自动分片并逐条读回验证 | -| `dws aitable +record-delete` | high-risk-write | 批量删除记录（不可逆），自动按 100 条分片并逐批确认记录已不存在 | -| `dws aitable +record-history-list` | read | 按 recordId 查询单条记录的变更历史 | -| `dws aitable +record-primary-doc-create` | write | 为记录创建主键文档（幂等），fieldId 须为 primaryDoc 类型 | -| `dws aitable +record-primary-doc-get` | read | 查询记录关联的主键文档 nodeId | -| `dws aitable +record-query` | read | 查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页） | -| `dws aitable +record-query-empty` | read | 扫描并过滤出完全没填用户字段的空行 | -| `dws aitable +record-share-links` | read | 批量（可 >20 条）获取多维表记录分享链接：去重+分片+合并 | -| `dws aitable +record-share-url` | read | 按 recordId 批量获取记录分享链接，单次最多 20 条 | -| `dws aitable +record-update` | write | 批量更新记录，自动按 100 条分片并逐批读回验证 | -| `dws aitable +record-upsert` | write | 按 recordId 自动拆分 create/update，按 100 条分片并读回验证 | -| `dws aitable +record-upsert-by-key` | write | 按唯一字段值有则更新、无则创建记录，并读回验证 | -| `dws aitable +resolve-base` | read | 按名称搜索多维表 Base 并解析出唯一 baseId（只读） | -| `dws aitable +resolve-table` | read | 在某个多维表 Base 内按名称解析出唯一的数据表 tableId（只读） | -| `dws aitable +role-create` | write | 在指定 Base 下创建自定义角色 | -| `dws aitable +role-delete` | high-risk-write | 删除 Base 下指定的自定义角色（不可逆） | -| `dws aitable +role-get` | read | 获取单个角色的完整配置 | -| `dws aitable +role-list` | read | 列出指定 Base 下的全部角色 | -| `dws aitable +role-update` | write | 按 PATCH 语义增量更新自定义角色 | -| `dws aitable +section-create` | write | 在指定 Base 下创建文件夹（组织 table / dashboard） | -| `dws aitable +section-delete` | high-risk-write | 删除指定文件夹（不可逆） | -| `dws aitable +section-list-empty` | read | 列出指定 Base 下所有没有子节点的空文件夹 | -| `dws aitable +section-list-nodes` | read | 列出指定 Base 当前版本下的全部 nsheet 节点 | -| `dws aitable +section-move-node` | write | 把任意 nsheet 节点移动到目标文件夹下（可选调整位置） | -| `dws aitable +section-rename` | write | 重命名指定文件夹 | -| `dws aitable +section-reorder` | write | 在当前父文件夹下调整文件夹的展示顺序 | -| `dws aitable +table-copy` | write | 跨 Base 同步复制一张表的可创建字段结构，并可同步复制全部记录 | -| `dws aitable +table-delete` | high-risk-write | 删除指定数据表（不可逆） | -| `dws aitable +table-get` | read | 批量获取指定数据表的表级信息、字段目录与视图目录 | -| `dws aitable +table-update` | write | 更新数据表名称 / 备注 / 行命名规则 | -| `dws aitable +template-search` | read | 按名称关键词搜索 AI 表格模板 | -| `dws aitable +url-resolve` | read | 解析 AI 表格 URL 中的 baseId/tableId/viewId/recordId | -| `dws aitable +view-delete` | high-risk-write | 删除指定视图（不可逆） | -| `dws aitable +view-duplicate` | write | 复制视图，生成配置相同的新视图 | -| `dws aitable +view-get` | read | 获取视图完整信息（列顺序、筛选、排序、分组等） | -| `dws aitable +view-get-frozen-cols` | read | 获取视图当前冻结的左侧列数 | -| `dws aitable +view-get-lock` | read | 获取视图锁定状态 | -| `dws aitable +view-get-row-height` | read | 获取视图单元格行高（像素） | -| `dws aitable +view-lock` | write | 锁定视图（默认）或解锁（--off） | -| `dws aitable +view-preset-apply` | write | 按视图精确名称幂等创建或更新预设，并读回校验类型和 config | -| `dws aitable +view-set-fill-color-rule` | write | 全量覆盖 Grid 视图的条件填色规则（传 '[]' 清空） | -| `dws aitable +view-set-frozen-cols` | write | 设置视图冻结列数（0 表示取消冻结） | -| `dws aitable +view-set-row-height` | write | 设置视图单元格行高（像素，合法档位 32/56/88/128） | -| `dws aitable +view-update` | write | 更新视图名称 / 描述 / 配置（visibleFieldIds、filter、sort、group 等） | -| `dws aitable +workflow-deploy` | write | 创建或更新完整 workflow-dsl/v1，强制检查 valid/flowId，并可启用后验证 RUNNING 状态 | -| `dws aitable +workflow-disable` | high-risk-write | 禁用指定 Base 中的自动化工作流（影响业务自动化） | -| `dws aitable +workflow-enable` | write | 启用指定 Base 中的自动化工作流 | -| `dws aitable +workflow-get` | read | 获取单个自动化工作流的详细信息 | -| `dws aitable +workflow-list` | read | 列出指定 Base 中的自动化工作流（分页） | +仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service aitable --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。 -## 意图表 +## Golden Route -| 用户说 | 命令 | -|--------|------| -| "搜表格 / 找一个 base" | `dws aitable base search --query "<名>"` | -| "创建 AI 表格 / 多维表" | `dws aitable base create --name "<名称>" [--template-id ]` | -| "查数据表 / 建数据表" | `dws aitable table get --base-id ` / `dws aitable table create --base-id --name "<表名>" --fields '[...]'` | -| "查字段 / 字段类型" | `dws aitable field get --base-id --table-id ` | -| "查记录 / 搜索记录" | `dws aitable record query --base-id --table-id [--filters '...']` | -| "写记录 / 更新记录 / 删除记录" | `dws aitable record create/update/delete --base-id --table-id ...` | -| "筛选 / 排序 / 公式 / 跨表引用" | 先读 `references/aitable/aitable-filter-sort.md` / `aitable-formula-guide.md` | -| "批量导入 JSON / CSV" | `python scripts/import_records.py data.csv\|data.json` | -| "批量加字段" | `python scripts/bulk_add_fields.py --base-id --table-id --fields fields.json` | -| "导入 / 导出表格" | 先读 `references/aitable/aitable-export-import.md`；导出优先 `python scripts/aitable_export_via_task.py --scope table --table-id ` | -| "仪表盘 / 图表" | 先读 `references/aitable/aitable-dashboard-chart.md` | -| "上传附件到记录" | 先读 `references/aitable/aitable-attachment.md`；可用 `python scripts/upload_attachment.py --base-id --file ` | +已有 ID 直接使用；完整 URL 先解析；名称先唯一解析为稳定 ID。零命中或多候选时停止，不默认选第一项。 -## 标准 SOP（必遵流程） +| 用户意图 | 唯一推荐入口 | 关键边界 | +|---|---|---| +| 从 URL 解析稳定 ID | `dws aitable +url-resolve --url ` | 只解析 URL 中已有的 baseId/tableId/viewId/recordId，不做远端名称搜索 | +| 按名称定位 Base/Table | `dws aitable +resolve-base --name <名称>` → `dws aitable +resolve-table --base --name <表名>` | 默认精确匹配；只有用户明确接受模糊匹配时才加 `--fuzzy` | +| 浏览 Base 下的数据表 | `dws aitable +list-tables --base ` | 只返回 tableId/tableName，不加载字段 | +| 搜索 Base | `dws aitable +base-search --query <关键词>` | 单次返回；不要将 `+base-list`（最近访问）声称为全量目录 | +| 新建 Base 与整套表字段 | `+base-bootstrap` | 高频准确 flags 与 JSON 形状见唯一执行 Reference；不要先调用 Help | +| 已有 Base 新建一张表与字段 | `+table-bootstrap` | 自动按 15 个字段分片并读回验证；替代 `table create` 后连续 `field create` | +| 查询、筛选、排序或分页 | `dws aitable +record-query --base-id --table-id ` | 单页/精确 ID 优先；明确要求全量时改用原子 `record query --all --page-limit ` | +| 新增单条或批量记录 | `dws aitable record create --base-id --table-id --records ` | 当前无 `+record-create`；写前取字段定义，写后按新 ID 回读 | +| 更新已知 recordId | `dws aitable +record-update --base-id --table-id --records ` | 自动分片并读回；只传需修改字段 | +| 按业务唯一键同步 | `dws aitable +record-upsert-by-key --base-id --table-id --key-field-id --key-value <值> --cells ` | 0 条创建、1 条更新、多条停止；非字符串键改用 `--key-value-json` | +| 按条件批量修改 | `dws aitable +record-bulk-patch --base-id --table-id --query <关键词> --patch --max-matches ` | 也可用 filters/record-ids 选范围；禁止无边界整表写 | +| 删除整个 Base | `dws aitable +base-delete --base-id ` | 先通过只读命令确认真实 ID；按 Runtime confirmation 执行，不用 Drive 删除同名节点 | +| 删除字段 | `dws aitable +field-delete --base-id --table-id --field-id ` | 先读取字段目录并确认非主字段；按 Runtime confirmation 执行 | +| 查询/创建记录主键文档 | `dws aitable +record-primary-doc-get|+record-primary-doc-create ...` | create 必须传 primaryDoc 类型的 `--field-id`；正文操作切到 Doc | +| 创建 View / Dashboard / Chart 或导入文件 | 对应 leaf / `+import-*` | 高频准确 flags 见唯一执行 Reference；已有参数直接执行，不调用 Help | +| 调整视图列顺序 | `dws aitable view update visible-fields --base-id --table-id --view-id --field-ids <完整有序IDs>` | 先读取字段和当前完整列数组，固定主字段在首位，写后回读精确校验 | +| 创建/修改图表前取配置 | `dws aitable +chart-widgets-example` | 命令返回所有图表类型示例；已有合法 config 时直接 create/update | +| Base 内 Section/节点移动 | `dws aitable +section-*` | Table/Dashboard/Section 是 Base 内 nsheet 节点，不是独立 Drive 节点 | -> 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 flag/ID。每条命令必须带 `--format json`，执行后必须按"解析"步取真实字段，不得凭返回结构猜测。`baseId`/`tableId`/`fieldId`/`recordId` 一律先查后用，**禁止默认/编造**。 +### 低频入口 -### SOP-1 定位 Base 与 Table（list / search → table get） +字段配置用 `+field-*`；删记录用 `+record-delete`；附件用 `+attachment-*`。批量分享记录用 `+record-share-links --base --table --record-ids `。其余能力使用同名前缀 leaf。 -**触发**：找/打开某张 AI 表格、不知 baseId 或 tableId。 +## 当前最短路径 -1. **选源（必须）**：有名称/关键词 → `dws aitable base search --query "<名称>"`；列最近访问 → `dws aitable base list`。`base list` 仅返回最近访问，不是全部，**禁止**当作全量清单。 -2. **执行（必须）**：`dws aitable base search --query "<完整名>" --format json`（或 `dws aitable base list --format json`）。 -3. **解析（必须）**：从 JSON 取真实 `baseId`；**多候选必须输出让用户选，禁止默认取第一个**。 -4. **取 tableId（必须）**：`dws aitable table get --base-id --format json` → 从 `data.tables[].tableId` 取目标表 ID，并记录 `views[]`。枚举模式不返回 `fields[]`；需要字段目录时必须继续执行 SOP-2 的 `field get`。若只核对某张表，可显式加 `--table-ids ` 控制返回体。 -5. **失败（必须）**：`base list` 为空或不命中 → 换 `base search --query` 关键词重试一次；仍无果**必须如实告知**，禁止臆造 baseId/tableId。 +- 已有 ID 直接使用；URL 只解析一次；名称用 `+resolve-base` / `+resolve-table` 唯一解析。filters/sort 缺 fieldId 时才读取字段目录。 +- 高频 Base/Table/Field/View/Dashboard/Chart/Import 先读一次 [执行 Reference](references/aitable.md)，其中已有准确 flags；不要再调用 Help。 +- Shortcut 已含分片或验证时不重复拆步；已有 Base 新建完整表结构直接用 `+table-bootstrap`。 +- 预计不超过 5 条命令的任务直接执行，不创建 TodoWrite/任务计划；复杂任务也只保留必要检查点。 -**禁止**：跳过 `table get` 直接用字段名写记录、用模糊名匹配当 baseId、用旧会话里的 ID 不再校验。 +## 记录输入与结果 -### SOP-2 拿字段定义（field get，写记录/改字段前置） +- `cells` key 用当前 fieldId；大 JSON 用相对 `--records-file`。filters 顶层为 `and|or`，sort 使用 `direction`；复杂条件读 [filter-sort](references/aitable/aitable-filter-sort.md)。 +- 按真实字段类型写值，只读字段不得写入。 +- 新建从 `data.newRecordIds[]` 取 ID，再用 `+record-query --record-ids` 回读。 +- 批量结果检查 completed/failed、verification、checkpoint；`partial_success` 不是完成。全量查询使用原子 `record query --all` 并检查 `hasMore`；只有 `hasMore=false`，或按指定 ID 全命中时，才声称结果完整。 +- 写入效果未知时回读，不重放成功批次。 -**触发**：建/改/写记录、改字段名或 options、按字段类型拼写入参前。 +## 安全边界 -1. **前置（必须）**：先按 SOP-1 拿到 `baseId` + `tableId`。 -2. **执行（必须）**：`dws aitable field get --base-id --table-id --format json`（仅展开需要的字段时加 `--field-ids fld1,fld2`，单次最多 10 个）。 -3. **解析（必须）**：取每个目标字段的 `fieldId`、`type`、`config`（如 singleSelect/multipleSelect 的 `options[].id|name`）；写入 cells 的 key **必须用 `fieldId`**，不是字段中文名；select 字段过滤/写入传**选项名称字面量**，不传 option ID。 -4. **衔接（必须）**：拿到字段定义 → 进入 SOP-3 写记录、或 `dws aitable field update --field-id --name <新名>|--config --format json` 改字段。 -5. **失败（必须）**：字段不存在或类型不符 → 重新 `field get` 核对，**禁止**凭旧名称/旧类型继续写入。 +- 删除不可逆，按 Runtime confirmation 核对真实目标；`base list` 只是最近访问。字段零/多候选、类型不明时停止；多批写保留已完成批次和续跑位置。 -**禁止**：用字段中文名当 cells key、跳过 `field get` 直接 `record create/update`、对 select 字段传 option ID 当写入值。 +## 按需加载 -### SOP-3 写/批量写记录（record create） +Golden Route 参数足够时不读 reference；否则最多读取一个： -**触发**：新增记录、批量加数据、CSV/JSON 入表。 +| 触发条件 | Reference | +|---|---| +| 高频 Golden Route 的准确 flags、JSON 形状与错误恢复 | [执行 Reference](references/aitable.md) | +| 记录 CRUD、字段值格式 | [record-ops](references/aitable-record-ops.md) | +| 记录主键文档 | [primary-doc](references/aitable/aitable-primary-doc.md) | +| filters/sort/date 操作符 | [filter-sort](references/aitable/aitable-filter-sort.md) | +| 字段创建或复杂配置 | [field](references/aitable/aitable-field.md) | +| 导入导出任务恢复 | [export-import](references/aitable/aitable-export-import.md) | +| 视图列顺序、筛选、排序、冻结 | [view-config](references/aitable/aitable-view-config.md) | +| Base 内 Section/节点移动或清理 | [section](references/aitable-section.md) | +| 图表配置 | [dashboard-chart](references/aitable/aitable-dashboard-chart.md) | +| 附件、表单、工作流 | 读取 `references/aitable/` 下对应的一个精确文件 | +| 产品边界不明确 | [intent-guide](references/intent-guide.md) | -1. **前置（必须）**：SOP-1 取 `baseId`/`tableId` + SOP-2 取 `fieldId`/类型。 -2. **执行（必须）**：`dws aitable record create --base-id --table-id --records '[{"cells":{"":<值>}}]' --format json`；单次最多 100 条，超长用 `--records-file ./data.json`。 -3. **写入格式（必须）**：按 `record create --help` 类型表严格传值（text→字符串、number→数值、singleSelect→"选项名"、date→RFC3339、url→`{"text","link"}`、group→`{"cid"}` 等）；`filterUp`/`lookup` 字段只读不可写。 -4. **解析与验证（必须）**：从返回 `data.newRecordIds[]` 取全部新记录 ID；不要读取不存在的标量 `recordId`。立即执行 `dws aitable record query --base-id --table-id --record-ids --format json` 回读写入值。 -5. **失败（必须）**：类型/格式错误按返回报错修正后重试，**禁止**降级丢弃字段；不确定格式先 `field get` 复核 config。 +不连读 reference；低频能力按意图加载。 -**禁止**：编造 fieldId/recordId、跳过 `field get` 凭中文名写、把 URL 字符串直接塞给 url 字段。 +## 错误最短路径 -### SOP-4 查/筛/排记录（record query） +1. 零/多候选、字段歧义或分页不完整：停止并返回证据；需要后续页时只透传真实 `nextCursor`。 +2. 类型错误只复核目标字段，不删字段或丢输入；`partial_success` 从 checkpoint 续跑，未知写入先回读。 +3. 错误包含 `actions` / `available_flags` 时只执行其中的 `next_command`；`retryable=false` 时停止，不换猜测 ID 或相似 flag 试参。 -**触发**：查记录、按条件筛选、排序、取关联记录、定位待改/待删的 recordId。 +## 跨产品边界 -1. **前置（必须）**：SOP-1 拿 `baseId`/`tableId`。 -2. **执行（必须）**：`dws aitable record query --base-id --table-id --format json`；已知 ID 直取加 `--record-ids rec1,rec2`（忽略 filters/sort，单次≤100）。 -3. **筛选/排序（必须）**：`--filters` 最外层必须 `{"operator":"and|or","operands":[...]}`，select 字段值传**选项名字面量**；日期只能用 `date_eq/before/after/not_before/not_after`，范围用 `not_before`+`not_after` 组合，**禁止** `eq`/区间/相对时间。`--sort` 用 `[{"fieldId":"..","direction":"asc|desc"}]`（**必须用 `direction`**）。公式/引用/关联字段默认不返回，需显式 `--field-ids` 指定。 -4. **解析（必须）**：取真实 `recordId` 与字段值；分页用 `--cursor`，全表用 `--all --page-limit N`。 -5. **衔接（必须）**：拿到 recordId → SOP-5 更新、`record delete --record-ids --yes` 删除（删前确认）。 - -**禁止**：用字段名做 filter/sort key、对日期用 `eq`、漏掉 `direction` 用旧 `order` 字段、用本地过滤替代服务端 filter。 - -### SOP-5 更新记录（record update） - -**触发**：改记录字段值、批量更新状态、单字段重命名需求之外的记录改动。 - -1. **前置（必须）**：SOP-1 拿 `baseId`/`tableId`；SOP-2 拿字段类型；SOP-4 拿目标 `recordId`。 -2. **执行（必须）**：`dws aitable record update --base-id --table-id --records '[{"recordId":"recXXX","cells":{"":<新值>}}]' --format json`（每条必含 `recordId`+`cells`，单次≤100；超长用 `--records-file`）；只传需改字段，未传保持原值。 -3. **解析与验证（必须）**：写入格式同 SOP-3；从返回 `data.recordIds[]` 取实际更新的记录 ID。更新响应不返回“受影响字段”，必须立即用 `record query --record-ids --format json` 回读目标字段确认。 -4. **失败（必须）**：recordId 不存在或类型不符 → 回 SOP-4 重新定位，**禁止**编造 ID 强写。 - -**禁止**：省略 `recordId`、用字段中文名当 cells key、凭空猜测 recordId 直接 update。 - -## 危险操作 - -`base delete` / `table delete` / `field delete` / `record delete` 不可逆，必须先向用户确认再加 `--yes`。 - -## 高频硬约束 - -- 创建/改字段/写记录是多轮连续任务时，不能在"让我执行/先获取 ID"后停下；必须实际调用对应 `dws aitable` 命令并验证结果。 -- 字段重命名使用 `dws aitable field update --base-id --table-id --field-id --name "<新名称>" --format json`；先 `field get` 找真实 `fieldId`，不要猜字段名能直接更新。 -- 写记录前必须 `field get` 获取 `fieldId` 与类型；`record create/update` 的 `cells` key 用 `fieldId`，不是字段中文名。长 JSON 使用 `--records-file`。 -- 表或字段创建返回名称被系统自动加后缀时，后续必须使用返回的真实 `tableId`/`fieldId`，不要继续按原名称猜。 -- `record update/delete` 先 `record query/list` 定位 `recordId`；删除必须确认，普通新增/更新按用户明确要求可直接执行后读回验证。 -- `record query/create/update/delete`、`field create`、导入导出、图表和附件场景必须先读对应 `references/aitable/*.md`，不要凭旧单文件参数猜 flag。 - -## 字段类型规则 - -详见本 skill 的 [field-rules.md](references/field-rules.md)。 - -## 跨产品协作 - -- 单元格 / 工作表 / 公式 → 切到 `dingtalk-misc`（`references/sheet.md`，命令前缀：`dws sheet`） -## 局部意图 - -- [局部意图消歧](references/intent-guide.md)。 +- Excel 式单元格、区域和公式操作 → `dingtalk-misc` 的 Sheet。 +- Base 作为整体在普通文件夹间移动或做外层存储重命名 → Drive；Base 结构复制/删除，以及 Base 内 Table、Dashboard、Section 的创建、复制、移动、重命名、删除 → AITable。 +- 记录主键文档正文 → 取得真实 nodeId 后切 `dingtalk-doc`。 diff --git a/skills/multi/dingtalk-aitable/references/aitable-record-ops.md b/skills/multi/dingtalk-aitable/references/aitable-record-ops.md index 48bfab14..6e32ce50 100644 --- a/skills/multi/dingtalk-aitable/references/aitable-record-ops.md +++ b/skills/multi/dingtalk-aitable/references/aitable-record-ops.md @@ -1,137 +1,73 @@ -# 记录操作详细指南 +# AI 表格记录操作 -## 查询记录 +仅在根 Skill 的记录 Golden Route 参数不足，或需要字段值格式、删除、历史、分享、附件细节时读取。本文件不负责 Base/Table 选路。 + +## 查询 ```bash -dws aitable record query --base-id --table-id --format json +dws aitable +record-query --base-id --table-id --record-ids +dws aitable +record-query --base-id --table-id --query "关键词" --limit 100 +dws aitable +record-query --base-id --table-id --filters '' --sort '' +dws aitable record query --base-id --table-id --filters '' --all --page-limit 50 ``` -返回: -```json -{ - "data": { - "records": [ - {"recordId": "rec001", "cells": {"fldABC": "完成设计", "fldDEF": {"id":"opt1","name":"进行中"}}}, - {"recordId": "rec002", "cells": {"fldABC": "编写文档", "fldDEF": {"id":"opt2","name":"待开始"}}} - ] - } -} -``` +- `record-ids` 用于稳定 ID 精确读取；`query` 用于全文搜索；复杂条件用 `filters`。 +- filters 使用 `{"operator":"and|or","operands":[...]}`，字段引用使用 fieldId；完整操作符只读 [filter-sort](aitable/aitable-filter-sort.md)。 +- `+record-query` 必须传真实 `base-id` 和 `table-id`。URL 先用 `+url-resolve`；名称先用 `+resolve-base` / `+resolve-table` 唯一解析，禁止自动选第一项。 +- 单页 `limit` 为 1-100。返回 `data.records`、`data.hasMore`，存在后续页时还会返回 `data.nextCursor`；把该值原样传给下一次 `--cursor`。 +- `+record-query` 不提供 `--all`；明确要求全量时改用原子 `record query --all --page-limit `。达到页上限后仍有 `hasMore=true` 代表截断，应从返回 cursor 续跑；只有 `hasMore=false`，或按 `record-ids` 查询且所有请求 ID 均已返回时，才能声称结果完整。 -按条件查询 (`--filters` 结构极易出错，请**强制**套用以下模板) -```bash -# 最外层必须是 "and" 或 "or"，单选字段传文本名称。 -# 示例：基础条件查询模板（可改内部 operator 为 contain 等） -dws aitable record query --base-id --table-id \ - --filters '{"operator":"and","operands":[{"operator":"eq","operands":["fld_state","进行中"]}]}' \ - --format json +## 新增 -# 关键词搜索 -dws aitable record query --base-id --table-id --keyword "设计" --format json - -# 按 ID 查询 -dws aitable record query --base-id --table-id --record-ids rec001,rec002 --format json - -# 游标分页 -dws aitable record query --base-id --table-id --limit 50 --cursor --format json -``` - -## 添加记录 - -**必须先执行 `field get` 获取 fieldId，再写入。cells 的 key 必须是 fieldId（如 fldXXX），不是字段名。** +当前没有 `+record-create`，使用原子命令： ```bash -# 单条 -dws aitable record create --base-id --table-id \ - --records '[{"cells":{"fldABC":"完成设计","fldDEF":"进行中"}}]' \ - --format json - -# 多条 -dws aitable record create --base-id --table-id \ - --records '[ - {"cells":{"fldABC":"任务A","fldDEF":"待开始"}}, - {"cells":{"fldABC":"任务B","fldDEF":"进行中"}} - ]' --format json +dws aitable record create --base-id --table-id \ + --records '[{"cells":{"fldText":"内容"}}]' --format json ``` -返回: -```json -{"data": {"newRecordIds": ["rec-new-001", "rec-new-002"]}} -``` +长 JSON 写到 cwd 内相对文件后使用 `--records-file ./records.json`。从真实返回的 `data.newRecordIds[]` 取 recordId，再用 `+record-query --record-ids` 回读。不要从输入顺序、名称或行号推断 ID。 -从 `data.newRecordIds[]` 提取新记录 ID，并立即执行 `record query --record-ids ` 回读写入结果；不要只看命令退出码。 +## 更新、同步与批量修改 -### --records 格式常见错误 +已知 recordId： ```bash -# 正确: 参数名是 --records，cells key 是 fieldId ---records '[{"cells":{"fldABC":"值"}}]' - -# 错误： 参数名写成 --data ---data '[{"cells":{"fldABC":"值"}}]' - -# 错误： cells key 用了字段名而非 fieldId ---records '[{"cells":{"任务名称":"值"}}]' - -# 错误： 用 fields 而非 cells ---records '[{"fields":{"fldABC":"值"}}]' +dws aitable +record-update --base-id --table-id \ + --records '[{"recordId":"","cells":{"fldStatus":"完成"}}]' ``` -## 更新记录 +`+record-update` 自动按 100 条分片并逐批回读；该 shortcut 只接受 `--records`。超长文件输入需要改用原子 `record update --records-file`，不要给 shortcut 猜造 flag。 -`--records` 中每条记录必须包含 `recordId`（从 `record query` 获取）: +按业务唯一键同步使用 `+record-upsert-by-key`：0 条创建、1 条更新、多条冲突停止。按条件批改使用 `+record-bulk-patch`，必须提供 filters/query/record-ids 中至少一种选择条件，或显式 `--all`，并设置合理 `--max-matches`。 + +## 删除 ```bash -dws aitable record update --base-id --table-id \ - --records '[{"recordId":"rec001","cells":{"fldDEF":"已完成"}}]' \ - --format json +dws aitable +record-delete --base-id --table-id --record-ids ``` -更新响应中的成功记录 ID 位于 `data.recordIds[]`。只需传入需修改的字段，未传入的保持原值；响应不返回“受影响字段”，必须再执行 `record query --record-ids ` 回读确认。 +删除不可逆。只使用已确认的真实 recordId；shortcut 自动分片并验证记录已不存在。未知结果按 recordId 回读，不重放已完成批次。 -## 删除记录 +## 常用字段值 -```bash -dws aitable record delete --base-id --table-id \ - --record-ids rec001,rec002 --yes --format json -``` +| 字段类型 | 写入值 | +|---|---| +| 文本、单选 | 字符串；单选使用已有选项名称 | +| 多选 | 选项名称数组 | +| 数字、评分 | JSON number | +| 复选框 | boolean | +| 日期 | 按字段配置要求的时间值；不凭展示文本猜格式 | +| URL | 按当前字段 Schema 要求的对象或字符串 | +| 人员、关联记录 | 使用真实 userId/recordId，不用姓名代替 | +| 附件 | 先用 `+attachment-put` 获得 AITable 附件 token，再写字段 | - 不可逆操作。调用前建议先 `record query` 确认目标记录。 +公式、查找引用、创建人/时间、修改人/时间等只读字段不得写入。字段类型不明时只读取目标字段配置一次。 -## 附件上传 +## 历史、分享与主键文档 -> **不要使用钉盘 (drive) 上传！** 钉盘 fileId 无法写入 attachment 字段。 +- 记录历史：`+record-history-list` +- 记录分享：`+record-share-links` / `+record-share-url` +- 主键文档：`+record-primary-doc-get` / `+record-primary-doc-create` -使用 `upload_attachment.py` 脚本（内部自动完成 prepare + PUT to OSS），**2 步**完成： - -```bash -# 步骤 1: 一键上传文件 -python3 scripts/upload_attachment.py /path/to/report.pdf -# 输出: { "fileToken": "ft_xxx", "fileName": "report.pdf", "size": 204800 } - -# 步骤 2: 在 record create/update 中使用 fileToken 写入附件字段 -dws aitable record create --base-id --table-id \ - --records '[{"cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json -``` - -> attachment 字段值必须是数组 `[{"fileToken":"ft_xxx"}]`，支持多个附件。 - -## 字段类型写入规则 - -| 类型 | 写入格式 | 读取返回格式 | -|------|----------|-------------| -| text | `"fldXXX":"文本值"` | `"fldXXX":"文本值"` | -| number | `"fldXXX":123` | `"fldXXX":"123"` | -| singleSelect | `"fldXXX":"选项名"` | `"fldXXX":{"id":"xxx","name":"选项名"}` | -| multipleSelect | `"fldXXX":["选项1","选项2"]` | `"fldXXX":[{"id":"xxx","name":"选项1"}]` | -| date | `"fldXXX":"2026-03-04"` | ISO 日期字符串 | -| user | `"fldXXX":[{"userId":"123"}]` | `"fldXXX":[{"corpId":"x","userId":"123"}]` | -| attachment | `"fldXXX":[{"fileToken":"ft_xxx"}]`需先用脚本上传 | `"fldXXX":[{"url":"...","filename":"..."}]` | - -### 只读字段（不要写入） - -- 创建时间、修改时间、创建人、修改人 -- 公式字段、引用字段 -- 自动编号字段 - -执行 `field get` 后识别字段类型，跳过只读字段。 +创建主键文档必须显式传 primaryDoc 类型的 `--field-id`；字段类型不明时先读取目标字段。正文读写切到 Doc；这里仅管理记录与文档关联。 diff --git a/skills/multi/dingtalk-aitable/references/aitable-section.md b/skills/multi/dingtalk-aitable/references/aitable-section.md new file mode 100644 index 00000000..be7bda7b --- /dev/null +++ b/skills/multi/dingtalk-aitable/references/aitable-section.md @@ -0,0 +1,28 @@ +# AI 表格 Section 与内部节点 + +只在用户操作 Base 内文件夹（Section）或把 Table/Dashboard 移入、移出 Section 时读取。这里的节点是 nsheet 业务节点，不是独立 Drive dentry；不要加载 Drive Skill 或尝试 Drive move。 + +## 高频闭环 + +创建 Section 并移动节点： + +```bash +dws aitable +section-create --base-id --name "归档区" --format json +dws aitable +section-move-node --base-id --node-id --new-parent-section-id --format json +dws aitable +section-list-nodes --base-id --format json +``` + +移动回 Base 根目录时显式传空字符串，不能省略该参数或改用 Drive： + +```bash +dws aitable +section-move-node --base-id --node-id --new-parent-section-id '' --format json +``` + +## 删除空 Section + +1. 用 `+section-list-nodes` 核对目标 Section 内节点；需要移出的节点逐个 `+section-move-node`。 +2. 用 `+section-list-empty --base-id ` 验证目标 sectionId 确实为空。 +3. 执行 `+section-delete --base-id --section-id `；按 Runtime confirmation 处理。 +4. 再次 `+section-list-nodes` 或 `+section-list-empty`，确认 Section 已不存在且被移动节点仍在预期父级。 + +Table 本身的创建、复制、改名、删除分别使用 `+table-*`；Section 只管理 Base 内目录关系。 diff --git a/skills/multi/dingtalk-aitable/references/aitable.md b/skills/multi/dingtalk-aitable/references/aitable.md index 3b4b4f31..dc2604cf 100644 --- a/skills/multi/dingtalk-aitable/references/aitable.md +++ b/skills/multi/dingtalk-aitable/references/aitable.md @@ -1,495 +1,111 @@ -# AI表格 (aitable) 命令参考 +# AI 表格执行 Reference -> **渐进式文档**：本文件为路由层（索引 + 意图判断），各命令的详细参数、示例和踩坑说明在 [aitable/](./aitable/) 目录下按需加载。 +根 Skill 只负责选路；高频命令的准确 flags、JSON 形状与失败恢复集中在本文件。命中下列路径后直接执行，不再调用 `--help`，也不加载产品级 Catalog。 -## 文档地址 (URI) - -| 资源 | URI 格式 | -|------|----------| -| Base 文档 | `https://alidocs.dingtalk.com/i/nodes/{baseId}` | -| 指定数据表 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}` | -| 指定数据表+视图 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}%26viewId%3D{viewId}` | -| 模板预览 | `https://docs.dingtalk.com/table/template/{templateId}` | - -> **操作后请返回文档 URI**：返回链接时必须带上当前操作的数据表 tableId，让用户点击后直接看到目标数据表，而不是落在空白的默认表。 -> - 已知 tableId + viewId 时（view create 返回、view get 中提取）：拼接 `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}%26viewId%3D{viewId}` -> - 已知 tableId 时（table create 返回、base get 中提取、record 操作所用的 tableId）：拼接 `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}` -> - 仅有 baseId、无明确 tableId 时（如 base list/search）：拼接 `https://alidocs.dingtalk.com/i/nodes/{baseId}` -> -> 补充：如果 URL 不是来自 `aitable` 命令返回，而是用户直接贴的原始 `alidocs` URL，先按 [链接规范](url-patterns.md#alidocs-url-类型探测流程) probe，确认是 `able` 后再按 AI 表格处理。 - -## 命令索引表 - -### base (Base 管理) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `base list` | 列出最近访问的 Base | — | 仅返回最近访问过的，优先用 `base search` | -| `base search` | 按名称搜索 Base | `--query` | 关键词 ≥2 字符 | -| `base get` | 获取 Base 信息（含 tables 列表） | `--base-id` | 用户给 URL 时提取末尾 ID | -| `base create` | 创建 Base | `--name` | 创建后直接用返回的 baseId；**默认新建的 base 自带一个空白「数据表」（含 3 行空记录）和一个空白仪表盘**，如需干净的空 base，传 `--template-id 1743` | -| `base update` | 更新 Base 名称 | `--base-id` `--name` | — | -| `base delete` | 删除 Base | `--base-id` | 不可逆 | - -### table (数据表管理) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `table get` | 获取数据表/视图目录 | `--base-id` | 不传 `--table-ids` 枚举全部表，但不返回字段；字段目录使用 `field get` | -| `table create` | 创建数据表 | `--base-id` `--name` `--fields` | fields 为 JSON 数组，至少 1 个 | -| `table update` | 修改表名 / 备注 / 行命名规则 | `--base-id` `--table-id` + 三选一(`--name` / `--description` / `--record-name-key`) | `--record-name-key` 是固定枚举（如 task/project/event/customer/ji_lu 等），非字段 ID | -| `table delete` | 删除表 | `--base-id` `--table-id` | 不可逆 | - -### field (字段管理) → 详见 [aitable-field.md](./aitable/aitable-field.md)、[field-properties](./aitable/aitable-field-properties.md) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `field get` | 获取字段完整配置 | `--base-id` `--table-id` | 按需展开少量字段 | -| `field create` | 创建字段 | `--base-id` `--table-id` + (`--name --type` 或 `--fields`) | 单字段/批量两种模式严格互斥；单字段配置传 `--config`，批量配置写入 `--fields` 每个元素的 `config` | -| `field update` | 更新字段名/配置 | `--base-id` `--table-id` `--field-id` | 不可变更字段类型 | -| `field delete` | 删除字段 | `--base-id` `--table-id` `--field-id` | 不可逆 | - -#### 搜索字段选项 -``` -Usage: - dws aitable field search-options [flags] -Example: - dws aitable field search-options --base-id --table-id --field-id - dws aitable field search-options --base-id --table-id --field-id --keyword 已完成 - dws aitable field search-options --base-id --table-id --field-id --limit 100 -Flags: - --base-id string Base ID (必填) - --field-id string 目标字段 ID，必须是 singleSelect / multipleSelect 类型 (必填) - --keyword string 模糊搜索关键词，大小写不敏感、contains 匹配 option name；不传返回全部 - --limit int 返回的最大 option 数量，默认 3000（全量），最大 3000 - --table-id string Table ID (必填) -``` - -仅适用于 **singleSelect / multipleSelect** 字段。其他类型（text/number/date/...）调用会返回错误。 - -适用场景： -- options 较多，只想要含某关键词的子集（避免 `field get` 拉取整个字段配置带回所有 options）。 -- 写入 record 前预览选项 id ↔ name 的映射，确认要使用的选项确实存在。 - -> **写 record 时**：`record create / update` 对 singleSelect/multipleSelect 可直接传 option **name**，不需要用本命令。本命令主要用于 **filter** 写法（filters 优先用 option **id**）或选项较多需要精确定位时。 - -### record (记录管理) - -| 命令 | 用途 | 必读 reference | 路由提醒 | -|------|------|----------------|----------| -| `record query` | 查询/搜索记录 | [aitable-record-query.md](./aitable/aitable-record-query.md) | 先 `field get` 拿 fieldId；`--all` 自动翻页；filters 结构见 reference | -| `record get` | 按 ID 取记录（`record query --record-ids` 的窄别名） | [aitable-record-query.md](./aitable/aitable-record-query.md) | 已知 recordId 时首选；必填 `--record-ids`（单次最多 100 条）；未暴露 filters/sort/query/cursor/limit | -| `record stats` | 不分组的服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 大写；最多 20 项，同字段不可重复；全量统计省略 limit | -| `record group-stats` | 分组、去重和高级服务端聚合 | [aitable-record-stats.md](./aitable/aitable-record-stats.md) | statsType 小写；group 为 JSON 数组字符串；最多 1000 个分组 | -| `record create` | 新增记录 | [aitable-record-create.md](./aitable/aitable-record-create.md) | cells key 必须是 fieldId 不是字段名；单次最多 100 条 | -| `record update` | 更新记录（每条独立 cells） | [aitable-record-update.md](./aitable/aitable-record-update.md) | 需先 query 拿 recordId；`cells` key 支持 fieldId 或当前表内唯一字段名，推荐 fieldId；`--records` 是 `[{recordId,cells},...]` 数组 | -| `record batch-update` | 批量更新（同一 cells 应用到多条 recordId） | [aitable-record-update.md](./aitable/aitable-record-update.md)、[aitable-cell-value.md](./aitable/aitable-cell-value.md) | 适合"统一标记完成/统一改负责人"等共享 patch 场景；`--cells` 是 JSON object（key=fieldId，value 按字段类型见 cell-value.md），与 record update 的单条 cells 结构完全一致；必填 `--record-ids` `--cells`；单次最多 100 条 | -| `record delete` | 删除记录 | [aitable-record-delete.md](./aitable/aitable-record-delete.md) | 不可逆，需先 query 确认 | -| `record history-list` | 查询单条记录的变更历史 | [aitable-record-history.md](./aitable/aitable-record-history.md) | 必填 `--record-id`；分页 `--offset --limit`，limit 范围 [1,50] 默认 20 | -| `record query-empty` | 查询完全没填用户字段的空行 | [aitable-record-query.md](./aitable/aitable-record-query.md) | 一页扫描 `--limit` [1,100] 默认 100；扫完前需用 `--cursor` 翻页（nextCursor 为空才表扫完） | -| `record share-url` | 批量获取记录分享链接 | [aitable-record-share.md](./aitable/aitable-record-share.md) | 必填 `--record-ids`（CSV，单次最多 20 条）；可选 `--view-id` 带视图上下文 | -| `record upsert` | 批量创建或更新（按 recordId 是否存在自动拆分） | [aitable-record-upsert.md](./aitable/aitable-record-upsert.md) | --records 同 record update 格式；带 recordId 走 update，不带走 create；单次最多 100 | -| `record primary-doc-get` | 查询记录的主键文档 nodeId | [aitable-primary-doc.md](./aitable/aitable-primary-doc.md) | 返回的 nodeId 可直接用于 `dws doc read/update --node` | -| `record primary-doc-create` | 为记录创建主键文档（幂等） | [aitable-primary-doc.md](./aitable/aitable-primary-doc.md) | fieldId 必须是 primaryDoc 类型；已存在则返回已有 nodeId | - -### view (视图管理) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `view get` | 获取视图配置（不传子命令） | `--base-id` `--table-id` | 不传 `--view-ids` 返回全部视图 | -| `view get ` | 获取视图某个属性 | `--view-id` | 12 个：card/timebar/aggregate/filter/sort/group/visible-fields/field-widths（详见 [aitable-view-config.md](./aitable/aitable-view-config.md)）+ lock/frozen-cols/row-height/fill-color-rule（详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md)） | -| `view list` | 列出全部视图（`view get` 的别名） | `--base-id` `--table-id` | 与 `view get` 完全等价 | -| `view create` | 创建视图 | `--base-id` `--table-id` `--view-type` | 类型: Grid/Kanban/Gantt/Calendar/Gallery/FormDesigner；用 `--config` 传 visibleFieldIds/filter/sort/group；**Gantt 创建后必须 `view update timebar` 绑定日期字段** | -| `view update` | 整体更新视图 / 多属性合并更新 | `--base-id` `--table-id` `--view-id` | 可传 `--name --desc --config '{...}'`，**`--config` 路径继续保留** | -| `view update ` | 按属性局部更新（推荐）| `--view-id` + typed flag / `--json` | 12 个：card/timebar/aggregate/field-widths/visible-fields/filter/sort/group/name + frozen-cols/row-height/fill-color-rule | -| `view lock [--off]` | 锁定/解锁视图 | `--base-id` `--table-id` `--view-id` | 默认锁定；`--off` 解锁。详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) | -| `view duplicate` | 复制视图 | `--base-id` `--table-id` `--view-id` | 可选 `--new-name`；保留源视图全部配置。详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) | -| `view delete` | 删除视图 | `--base-id` `--table-id` `--view-id` | 不可删最后一个/锁定视图 | - -> **优先用 `view get ` / `view update ` 子命令**：每个属性独立命令，typed flag 友好，agent 不必拼 JSON。**`view update --config '{...}'` 仍可用**，适合一次性多属性更新或脚本场景。 - -> **属性按 attr 分类，决定该读哪份子文档**： -> - card / timebar / aggregate / filter / sort / group / visible-fields / field-widths → [aitable-view-config.md](./aitable/aitable-view-config.md) -> - lock / frozen-cols / row-height / fill-color-rule / duplicate → [aitable-view-extras.md](./aitable/aitable-view-extras.md) -> 后一类**不能**塞进 `view update --config '{...}'`，必须用各自专属子命令；如果错传 `flags` / `frozenColCount` / `cellHeight` / `conditionalFormats` 等 key 进 `--config`，CLI 会在 stderr 提示应改用的命令。 - -> **`view update --config` 支持的 9 个 key**： -> `visibleFieldIds` / `filter` / `sort` / `group` / `fieldWidths`(Grid) / `aggregate`(Grid) / `kanbanCard`(Kanban) / `ganttTimebar`(Gantt) / `galleryCard`(Gallery)。 -> filter/sort/group 必须传**数组**格式（与 `record query --filters` 的对象格式不同；CLI 会自动容错）。其他 key 会被服务端忽略并打 warning。 - -### form (表单管理) → 详见 [aitable-form.md](./aitable/aitable-form.md) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `form list` | 列出表单视图 | `--base-id` `--table-id` | 详情见 [aitable-form.md](./aitable/aitable-form.md) | -| `form get` | 按 viewId 取单个表单详情 | `--base-id` `--table-id` `--view-id` | — | -| `form create` | 创建表单视图 | `--base-id` `--table-id` `--name` | — | -| `form update` | 更新表单配置 | `--base-id` `--table-id` `--view-id` | title/name/description 至少一项 | -| `form delete` | 删除表单 | `--base-id` `--table-id` `--view-id` | 不可逆 | -| `form field list/update/hide` | 表单字段管理 | — | 详情见子文档 | -| `form questions create/delete` | 题目管理（=field create/delete） | — | 详情见子文档 | -| `form share get/update` | 表单分享配置 | — | 详情见子文档 | - -> **创建表单**有两种等价方式：`form create --name "..."`（推荐）或 `view create --view-type FormDesigner --name "..."`。 - -### workflow (自动化工作流) → 详见 [aitable-workflow.md](./aitable/aitable-workflow.md) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `workflow edit-example` | 获取编辑文档与 DSL 示例 | 无 | create/update 前优先调用，内容由服务端提供 | -| `workflow create` | 创建并发布自动化工作流 | `--base-id` `--dsl` | 按子文档 Demo 组装 DSL；必须检查返回的 `data.valid` / `issues`；create 不自动重试 | -| `workflow update` | 更新并发布已有自动化工作流 | `--base-id` `--workflow-id` `--dsl` | 先 get 留底；提交完整目标 DSL；必须检查 `data.valid` / `issues` | -| `workflow list` | 列出 Base 下所有工作流 | `--base-id` | 支持 `--limit [1,100]` / `--offset >=0`；list 出参字段叫 `flowId` | -| `workflow get` | 获取单个工作流详情（含 flowSchema） | `--base-id` `--workflow-id` | `--workflow-id` 接受 list 里的 `flowId`（同值） | -| `workflow enable` | 启用工作流 | `--base-id` `--workflow-id` | 返回 `{enabled: true}` 是动作确认；要确认真启用看 list 的 `status` | -| `workflow disable` | 禁用工作流（高危） | `--base-id` `--workflow-id` `--yes` | 影响业务自动化，建议二次确认；status 变 STOP | -| `workflow run` | 立即执行工作流（需确认） | `--base-id` `--workflow-id`；记录触发另需 `--table-id` `--record-ids` | 返回 `executionId`；不确定时先用 history 核对，避免重复执行 | -| `workflow history` | 查询工作流执行历史 | `--base-id` `--workflow-id` | 支持 status、Unix 毫秒时间范围和 page/size；`instanceId` 对应 run 的 `executionId` | - -> 创建/更新的 `--dsl` 使用钉钉 AI 表格 `workflow-dsl/v1`；完整格式和最小 Demo 见 [aitable-workflow.md](./aitable/aitable-workflow.md)。删除工作流暂未开放。 - -### dashboard & chart → 详见 [aitable-dashboard-chart.md](./aitable/aitable-dashboard-chart.md) - -| 命令 | 用途 | -|------|------| -| `dashboard get/create/update/delete` | 仪表盘管理 | -| `dashboard config-example` | 查看仪表盘配置模板 | -| `dashboard arrange` | 自动重排仪表盘图表布局（智能填满网格，避免空缺） | -| `chart get/create/update/delete` | 图表管理 | -| `chart widgets-example` | 查看图表 widgets 配置模板 | - -### export & import → 详见 [aitable-export-import.md](./aitable/aitable-export-import.md) - -| 命令 | 用途 | -|------|------| -| `export data` | 导出数据（异步两阶段轮询） | -| `import upload` | 申请文件导入上传凭证 | -| `import data` | 触发导入 | - -### attachment → 详见 [aitable-attachment.md](./aitable/aitable-attachment.md) - -| 命令 | 用途 | 路由提醒 | -|------|------|----------| -| `attachment upload` | 准备附件上传凭证 | 不要用钉盘 drive 上传！ | - -### template (模板搜索) - -| 命令 | 用途 | 必填参数 | -|------|------|----------| -| `template search` | 搜索模板 | `--query` | - -### advperm (高级权限/自定义角色) → 详见 [aitable-advperm.md](./aitable/aitable-advperm.md) - -| 命令 | 用途 | 必填参数 | 路由提醒 | -|------|------|----------|----------| -| `advperm enable` | 开启 Base 高级权限总开关 | `--base-id` | 不开启时角色规则不生效 | -| `advperm disable` | 关闭 Base 高级权限总开关（高危） | `--base-id` `--yes` | 关闭后全员回退默认权限 | -| `advperm role-list` | 列出 Base 下所有角色 | `--base-id` | 同时返回自定义角色和系统角色；`roleType == "custom"` 是自定义，前缀 `system_` 是系统角色 | -| `advperm role-get` | 获取单角色完整配置 | `--base-id` `--role-id` | 含 subRoles 与字段/行级规则 | -| `advperm role-create` | 创建自定义角色 | `--base-id` `--name` | 可选 `--sub-roles` 同时指定子角色权限规则 | -| `advperm role-update` | 增量更新自定义角色（PATCH） | `--base-id` `--role-id` | 未传字段不变；`--sub-roles` 按 (targetId,targetType) 合并 | -| `advperm role-delete` | 删除自定义角色 | `--base-id` `--role-id` `--yes` | 不可逆；系统角色禁删；**调用者必须是该 AI 表格的管理员/Owner**，非管理员会得到 401 AUTH_ERROR | - -> **角色 CRUD 已全支持**：create/get/list/update/delete 都可走 CLI。 -> 所有写命令（enable/disable/role-create/role-update/role-delete）需要 Base 管理员权限；非管理员只能调 `role-list` / `role-get`（只读）。 -> "角色 ↔ 成员"绑定当前 CLI 不支持，仍需在 AI 表格 Web 端 → Base 设置 → 高级权限面板手动完成。 - -### section (文件夹与节点管理) - -> 用于在 Base 的导航树中组织 table / dashboard / 表单视图 / 文档等节点（类似文件夹）。 -> 操作前建议先用 `section list-nodes` 拿到 nodeId / sectionId 与父级关系。 - -#### 创建文件夹 -``` -Usage: - dws aitable section create [flags] -Example: - dws aitable section create --base-id --name 我的文件夹 - dws aitable section create --base-id --name 子文件夹 --parent-section-id --index 0 -Flags: - --base-id string Base ID (必填) - --name string 文件夹名称 (必填) - --parent-section-id string 父文件夹 ID；不传或空字符串表示创建在 Base 根目录下 - --index int 在父文件夹下的目标位置（0-based）；不传则追加到末尾 -``` - -返回 `data.sectionId` 与 `data.name`。 - -#### 重命名文件夹 -``` -Usage: - dws aitable section rename [flags] -Example: - dws aitable section rename --base-id --section-id --new-name 新名称 -Flags: - --base-id string Base ID (必填) - --section-id string 目标文件夹 ID (必填) - --new-name string 新的文件夹名称 (必填) -``` - -#### 删除文件夹 -``` -Usage: - dws aitable section delete [flags] -Example: - dws aitable section delete --base-id --section-id -Flags: - --base-id string Base ID (必填) - --section-id string 目标文件夹 ID (必填) -``` - -> **注意**：删除不可逆；删除前可先用 `section list-empty` 确认是否为空文件夹。 - -#### 调整文件夹顺序 -``` -Usage: - dws aitable section reorder [flags] -Example: - dws aitable section reorder --base-id --section-id --target-index 0 -Flags: - --base-id string Base ID (必填) - --section-id string 目标文件夹 ID (必填) - --target-index int 目标位置（0-based）(必填) -``` - -> 在**当前父文件夹下**调整展示顺序。跨父级移动请用 `section move-node`。 - -#### 列出空文件夹 -``` -Usage: - dws aitable section list-empty [flags] -Example: - dws aitable section list-empty --base-id -Flags: - --base-id string Base ID (必填) -``` - -返回 `data.items: [{sectionId, name, parentSectionId}]` 与 `data.total`，用于清理或诊断导航树（parentSectionId 为空串表示在根目录下）。 - -#### 列出全部节点 -``` -Usage: - dws aitable section list-nodes [flags] -Example: - dws aitable section list-nodes --base-id -Flags: - --base-id string Base ID (必填) -``` - -返回 `data.items: [{nodeId, nodeType, parentSectionId, name?}]` 与 `data.total`，涵盖文件夹 / AI 表格 / 表单视图 / 仪表盘 / 文档 / 查询视图。 - -> **与其他命令的关联**：是 `section move-node` / `section reorder` 的前置定位命令——先用它拿到 nodeId 与 parentSectionId。 - -#### 移动节点 -``` -Usage: - dws aitable section move-node [flags] -Example: - dws aitable section move-node --base-id --node-id --new-parent-section-id - dws aitable section move-node --base-id --node-id --new-parent-section-id "" --target-index 0 -Flags: - --base-id string Base ID (必填) - --node-id string 要移动的节点 ID（文件夹/AI表格/表单视图/仪表盘/文档/查询视图）(必填) - --new-parent-section-id string 目标父文件夹 ID；空字符串表示移到 Base 根目录 (必填) - --target-index int Base 内节点的全局位置（0-based）；不传则不调整 -``` - -> 服务端自动识别节点类型，无需区分文件夹与非文件夹。返回 `data.nodeId / newParentSectionId / nodeType`。 -> 对文件夹节点带 `--target-index` 时会先 move 再 reorder，中间失败会返回 `MOVE_OK_REORDER_FAILED`，可用 `section reorder` 重试。 - -## 复杂操作 - -### 仪表盘 / 图表（建议顺序） +## 高频 Golden Route（准确 flags） ```bash -# 1) 先看配置模板（JSONC） -dws aitable dashboard config-example --format json -dws aitable chart widgets-example --format json +# 新建 Base 和整套表字段；tables 必须是非空数组 +dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[{"fieldName":"标题","type":"text"}]}]' -# 2) 先拿 dashboard，再拿 chart 详情 -dws aitable dashboard get --base-id --dashboard-id --format json -dws aitable chart get --base-id --dashboard-id --chart-id --format json +# 只新建空 Base；folder-id / template-id 均为可选 +dws aitable base create --name "项目管理" +dws aitable base create --name "项目管理" --folder-id +dws aitable base create --name "项目管理" --template-id + +# 已有 Base 新建一张完整表；超过 15 个字段由 shortcut 自动分片 +dws aitable +table-bootstrap --base-id --name "任务" --fields '[{"fieldName":"标题","type":"text"}]' + +# 只补字段；单字段与批量字段二选一，单次最多 15 个 +dws aitable field create --base-id --table-id --name "状态" --type singleSelect --config '{"options":[{"name":"待办"},{"name":"完成"}]}' +dws aitable field create --base-id --table-id --fields '[{"fieldName":"状态","type":"singleSelect","config":{"options":[{"name":"待办"}]}}]' + +# 创建视图；view-type 合法值：Grid/FormDesigner/Gantt/Calendar/Kanban/Gallery +dws aitable view create --base-id --table-id --view-type Grid --name "默认表格" +# Gantt 必须再绑定日期字段，否则只是空壳 +dws aitable view update timebar --base-id --table-id --view-id --start-field + +# 创建仪表盘和图表；chart 的 config/layout 都必填 +dws aitable dashboard create --base-id --name "运营看板" +dws aitable chart create --base-id --dashboard-id --config '' --layout '{"x":0,"y":0,"w":12,"h":4}' + +# 查询记录；选择器按意图传一个，不猜 flag +dws aitable +record-query --base-id --table-id +dws aitable +record-query --base-id --table-id --record-ids +dws aitable +record-query --base-id --table-id --filters '' +dws aitable +record-query --base-id --table-id --query "关键词" + +# 文件导入：先申请凭证并上传，再用真实 importId 导入 +dws aitable +import-upload --base-id --file-name data.xlsx --file-size +curl -X PUT "" -H "Content-Type:" --data-binary @data.xlsx +dws aitable +import-data --import-id +dws aitable +import-data --import-id --table-id ``` -要点： +写命令是否追加 `--yes` 只以 Runtime confirmation 为准，不把 `--yes` 固化进示例。字段对象统一使用 `fieldName` / `type` / 可选 `config`；不要改写成相似的 `field-name`、`field-type` 或 `table-name`。建表时第一个字段会成为主字段，应优先使用 `text`；传空字段数组时由服务自动补标题主字段。导入 OSS PUT 的 `Content-Type` 必须显式置空，否则可能返回 403。 -- `dashboard get` 返回的 `charts[].chartId` 可直接给 `chart get` 使用。 -- `dashboard share get` 可能返回 `404`（资源不存在或未开通），需按可重试错误处理，不要误判为参数拼错。 -- `chart share get` 可正常返回 `enabled/shareUrl`，用于分享状态判断。 +## 错误恢复 -### 导出数据（两阶段轮询） +- 结构化错误存在 `actions` / `available_flags` 时，`actions` 中的完整命令就是唯一下一步；不要试相似 ID 或 flag。 +- `partial_success`：保留 `knownSideEffects` 与 `checkpoint`，只执行返回的 `nextCommand` 检查或恢复，不重放已成功批次。 +- `unknown`：先按 `nextCommand` 或业务唯一名称确认远端效果；未确认前不得重试非幂等创建。 +- `retryable=false`：停止。目标文件夹无效时只用返回的 `dws drive +info --node --format json` 核对，不把其他类型 ID 轮流代入。 +- 验证成功必须看到 `verification.status=verified`；退出码为 0 或写接口空回包本身不构成成功。 -`export data` 常见为异步任务：首次调用可能只返回 `taskId`，需要继续轮询。 +## 加载规则 -```bash -# 第一步：创建任务（按 scope 传必要参数） -dws aitable export data --base-id --scope table --table-id --format excel --timeout-ms 1000 +- 先根据用户意图定位下表中的唯一命令族，再读取至多一个对应 leaf reference。 +- 已知命令但参数不确定，只读一次该 leaf Schema；不要加载产品级 Schema 或完整 Catalog。 +- 命令清单只在本索引仍无法定位时用 `dws shortcut list --service aitable --format json` 回退。 +- 不使用 Python recipe 绕过已有 shortcut；不根据命令名猜 flag。 -# 第二步：拿 taskId 继续轮询，直到返回 downloadUrl -dws aitable export data --base-id --task-id --timeout-ms 3000 -``` +## 目标与 ID -参数约束 +| 已有信息 | 最短入口 | 输出复用 | +|---|---|---| +| AI 表格 URL | `dws aitable +url-resolve --url ` | 解析 URL 中已有的 baseId/tableId/viewId/recordId；不做远端名称搜索 | +| 已知 Base/Table ID | 直接传给最终命令 | 不重复解析 | +| Base 精确名称或关键词 | `dws aitable +resolve-base --name <名称>` | 默认精确匹配；明确需要模糊匹配时加 `--fuzzy`，零/多候选均停止 | +| Base ID + Table 名称 | `dws aitable +resolve-table --base --name ` | 默认精确匹配；明确需要模糊匹配时加 `--fuzzy` | +| Base ID，只需目录 | `dws aitable +list-tables --base ` | 只投影 tableId/tableName，不额外读取字段 | +| 需要字段或视图目录 | `dws aitable +field-get ...` / `dws aitable +view-get ...` | 只读取当前任务需要的目标范围 | -- `scope=all`：只需 `base-id` -- `scope=table`：必须 `table-id` -- `scope=view`：必须同时 `table-id + view-id` +`+record-query` 只接受真实 `base-id` / `table-id`，因此 URL 或名称须先按上表解析。`+base-list` 只表示最近访问，不是组织内全量 Base；`+base-search --query ` 是单次搜索。名称匹配零命中或多候选时停止，不选第一项。 -## 意图判断 +## 低频命令族 -用户说"表格/多维表/AI表格": -- 查看/查找/列表 → `base search`（优先）或 `base list`（仅浏览最近访问） -- 详情 → `base get` -- 创建 → `base create` -- 修改 → `base update` -- 删除 → `base delete` +| 意图 | 推荐 shortcut | 精确 reference | +|---|---|---| +| Base 新建整套结构 | `+base-bootstrap` | 使用本文上方准确 flags | +| Base 查看、搜索、复制、改名、删除、快照 | `+base-get` / `+base-search` / `+base-copy` / `+base-update` / `+base-delete` / `+base-schema-snapshot` | 对应 leaf Schema | +| Table 新建、查看、复制、改名、删除 | `+table-bootstrap` / `+table-get` / `+table-copy` / `+table-update` / `+table-delete` | 新建使用本文上方准确 flags；其余对应 leaf Schema | +| Field 完整配置、修改、删除 | `+field-get` / `+field-update` / `+field-delete` | [field](aitable/aitable-field.md)；属性细节才读 [field-properties](aitable/aitable-field-properties.md) | +| Record 历史、空行、分享、主键文档 | `+record-history-list` / `+record-query-empty` / `+record-share-*` / `+record-primary-doc-*` | [record-ops](aitable-record-ops.md) | +| Record 统计、分组聚合和去重率 | `record stats` / `record group-stats` | [record-stats](aitable/aitable-record-stats.md) | +| Filter、sort、日期操作符 | `+record-query` / `+record-bulk-patch` | [filter-sort](aitable/aitable-filter-sort.md) | +| View 配置、复制、锁定、冻结列、行高、填色 | 对应 `+view-*` | [view-config](aitable/aitable-view-config.md)；冻结列/行高/填色才读 [view-extras](aitable/aitable-view-extras.md) | +| Form 字段、分享、修改、删除 | 对应 `+form-*` | [form](aitable/aitable-form.md) | +| Dashboard 与 Chart | 对应 `+dashboard-*` / `+chart-*` | [dashboard-chart](aitable/aitable-dashboard-chart.md) | +| 导入、导出和任务恢复 | `+import-upload` / `+import-data` / `+export-data` | [export-import](aitable/aitable-export-import.md) | +| 上传或移除附件 | `+attachment-put` / `+attachment-remove` | [attachment](aitable/aitable-attachment.md) | +| 自动化工作流 | 对应 `+workflow-*` | [workflow](aitable/aitable-workflow.md) | +| 普通角色和高级权限 | 对应 `+role-*` / `+advperm-*` | [advperm](aitable/aitable-advperm.md) | +| AI 表格内部 Section/节点 | 对应 `+section-*` | [section](aitable-section.md) | +| 模板检索 | `+template-search` | leaf Schema 足够，不再读其他 reference | -用户说"数据表/子表/table": -- 查看 → `table get` -- 创建 → `table create` -- 重命名 / 改备注 / 改行命名规则 → `table update`（三选一：`--name` / `--description` / `--record-name-key`） -- 用户说"行命名规则/记录别名/卡片显示成 task/project/event 这种" → `table update --record-name-key <枚举键>`，**中文 → 枚举键**对照见 [aitable-record-name-key.md](./aitable/aitable-record-name-key.md) -- 删除 → `table delete` +## 写操作通用约束 -用户说"字段/列/column": -- 查看 → `field get` -- 添加 → `field create`（读 [aitable-field.md](./aitable/aitable-field.md)） -- 修改 → `field update` -- 删除 → `field delete` +- 创建/更新记录前只读取目标 Table 或目标 Field 的真实配置；`cells` key 优先使用 fieldId。 +- 只读字段（公式、查找引用、创建/修改信息等）不写入。 +- 删除 Base/Table/Field/Record、停用工作流、删除附件和关闭高级权限均按 Runtime confirmation 执行。 +- 批量操作检查 completed/failed/checkpoint/nextCommand；`partial_success` 不等于成功。 +- 写入效果未知时按返回的稳定 ID 或业务唯一键回读，不能整批盲目重放。 -用户说"记录/行/数据/row": -- 查看/搜索 → `record query`（读 [aitable-record-query.md](./aitable/aitable-record-query.md)） -- 总数/求和/平均值/中位数/完整率等标量统计 → `record stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） -- 分组统计/唯一实体计数/去重率 → `record group-stats`（读 [aitable-record-stats.md](./aitable/aitable-record-stats.md)） -- 找空行 / 没填东西的行 → `record query-empty`（读 [aitable-record-query.md](./aitable/aitable-record-query.md)） -- 已知 recordId 反查字段值 → `record get`（按 ID 取专用，等价 `record query --record-ids`） -- 添加/写入 → `record create`（读 [aitable-record-create.md](./aitable/aitable-record-create.md)） -- 修改/更新（每条独立 cells） → `record update`（读 [aitable-record-update.md](./aitable/aitable-record-update.md)） -- **批量更新同一字段值**（统一标记/统一改值） → `record batch-update --record-ids ... --cells '{...}'` -- 删除 → `record delete` -- **查记录的字段变更历史 / 操作审计** → `record history-list`（读 [aitable-record-history.md](./aitable/aitable-record-history.md)） -- **取记录分享链接 / 把这行发给同事** → `record share-url`（读 [aitable-record-share.md](./aitable/aitable-record-share.md)） -- **不知道有没有 → 有就改、没有就建** → `record upsert`（读 [aitable-record-upsert.md](./aitable/aitable-record-upsert.md)） +兼容包仍包含 `scripts/aitable_export_via_task.py` 与 `scripts/bulk_add_fields.py`；当前主路径分别是 `+export-data` 与 `+table-bootstrap` / `field create`，只有旧版运行时缺少对应命令时才使用脚本。 -用户说"视图/view": -- 列出/查看全部视图 → `view list`（或 `view get` 不传 --view-ids，二者等价） -- 看某个视图详情 → `view get --view-ids ` -- 创建 → `view create` -- 修改（含"调整字段顺序/隐藏字段"） → `view update --config '{"visibleFieldIds":[...]}'` -- 修改某一项配置（filter/sort/group/card/timebar/aggregate 等）→ `view update `（读 [aitable-view-config.md](./aitable/aitable-view-config.md)） -- 锁定 / 冻结列 / 行高 / 数据高亮规则 / 复制视图 → 读 [aitable-view-extras.md](./aitable/aitable-view-extras.md) -- 删除 → `view delete` +## 跨产品边界 -用户说"锁定视图/解锁视图/lock view" → `view lock` / `view lock --off`，详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) - -用户说"冻结列/冻结首列/frozen columns" → `view update frozen-cols --count N`，详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) - -用户说"行高/单元格高度/紧凑模式/cell height" → `view update row-height --cell-height N`（合法档位 32/56/88/128），详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) - -用户说"数据高亮/条件格式/单元格上色/fill color rule" → `view update fill-color-rule --json '[...]'`，详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) - -用户说"复制视图/duplicate view" → `view duplicate --view-id ... [--new-name ...]`，详见 [aitable-view-extras.md](./aitable/aitable-view-extras.md) - -用户说"筛选/过滤/filter" → 读 [aitable-filter-sort.md](./aitable/aitable-filter-sort.md) - -用户说"统计/分析/聚合/TOP N/全量" → 先读 [aitable-data-analysis-sop.md](./aitable/aitable-data-analysis-sop.md)，聚合参数见 [aitable-record-stats.md](./aitable/aitable-record-stats.md) - -用户说"公式/formula/计算字段/派生指标" → 读 [aitable-formula-guide.md](./aitable/aitable-formula-guide.md) - -用户说"查找引用/lookup/filterUp/跨表" → 读 [aitable-formula-guide.md](./aitable/aitable-formula-guide.md)（§5.4 跨表引用） - -用户说"表单/form/收集表/问卷/催办填写" → 读 [aitable-form.md](./aitable/aitable-form.md) - -用户说"自动化/工作流/流程/触发/automation/workflow" → 读 [aitable-workflow.md](./aitable/aitable-workflow.md) -- 新建自动化 → 按子文档的最小 Demo 组装完整 DSL，再 `workflow create --dsl @file` -- 修改自动化 → `workflow get` 留底，按最新 DSL 文档生成完整目标 DSL，再 `workflow update --dsl @file` -- 看 Base 里有哪些流程 / 哪些在跑 → `workflow list`（看 `recordCount` / `runningCount`） -- 看某个流程具体配置（触发条件、动作步骤） → `workflow get` -- 启用流程 → `workflow enable` -- 临时停掉流程（调试 / 数据迁移）→ `workflow disable --yes` -- 删除流程：当前不支持，引导用户到 AI 表格 Web 端 → 数据表 → 自动化 面板手动完成 - -用户说"仪表盘/图表/chart" → 读 [aitable-dashboard-chart.md](./aitable/aitable-dashboard-chart.md) - -用户说"仪表盘排版乱了/图表对不齐/重新排布/自动布局/美化仪表盘" → `dashboard arrange`（读 [aitable-dashboard-chart.md](./aitable/aitable-dashboard-chart.md)） - -用户说"附件/上传文件" → 读 [aitable-attachment.md](./aitable/aitable-attachment.md) - -用户说"导入/导出/import/export" → 读 [aitable-export-import.md](./aitable/aitable-export-import.md) - -用户说"模板" → `template search` - -用户说"高级权限/角色/权限控制/谁能看/谁能改" → 读 [aitable-advperm.md](./aitable/aitable-advperm.md) -- 开/关高级权限 → `advperm enable` / `advperm disable --yes` -- 看角色配置 → `advperm role-list` 或 `advperm role-get` -- 建角色（可同时指定子角色权限） → `advperm role-create --name ... --sub-roles '[...]'` -- 改角色名 / 改子角色权限（PATCH 语义，未传字段不变） → `advperm role-update --role-id ... [--name ...] [--sub-roles '[...]']` -- 删角色 → `advperm role-delete --yes` -- **角色 ↔ 成员绑定**：当前 CLI 不支持，仍需在 AI 表格 Web 端面板手动完成 - -命令报错/操作失败 → 读 [aitable-error-recovery.md](./aitable/aitable-error-recovery.md) - -**关键区分**: base=表格文件, table=数据表, field=列, record=行 - -## 核心工作流 - -```bash -# 1. 搜索/列出 Base — 提取 baseId -dws aitable base search --query "项目" --format json - -# 2. 获取 Base 信息 — 提取 tableId -dws aitable base get --base-id --format json - -# 3. 获取字段目录 — 提取 fieldId -dws aitable field get --base-id --table-id --format json - -# 4. 查询记录 -dws aitable record query --base-id --table-id --format json - -# 5. 新增记录 (cells 用 fieldId 作 key) -dws aitable record create --base-id --table-id \ - --records '[{"cells":{"fldXXX":"值"}}]' --format json -``` - -## 上下文传递表 - -| 操作 | 从返回中提取 | 用于 | -|------|-------------|------| -| `base list/search` | `baseId` | 所有后续命令的 --base-id，拼接文档 URI | -| `base create` | `baseId` | 后续命令 + 文档 URI | -| `base get` | `tables[].tableId` | --table-id，拼接指定数据表 URI | -| `table create` | `tableId` | 后续命令 + 拼接指定数据表 URI | -| `table get` | `tables[].tableId`、视图目录 | 定位数据表和视图；字段需继续调用 `field get` | -| `field get` | `fields[].fieldId` | record 操作的 cells key, field update/delete | -| `record query` | `recordId` | record update/delete；按 ID 反查字段值用 `record get` | -| `template search` | `templateId` | base create --template-id，拼接模板预览 URI | - -## URL → baseId 提取 - -用户提供 `https://alidocs.dingtalk.com/i/nodes/{baseId}` 链接时： -1. 提取 `/nodes/` 后的路径段作为 `baseId` -2. 去掉尾部的查询参数（`?` 及其后内容） -3. 传入 `--base-id` 参数 - -> 如果该 URL 来自 `dws aitable` 返回或已在当前链路 probe 过，可直接复用； -> 如果是用户直接提供的原始 `alidocs` URL，则先按 [链接规范](url-patterns.md#alidocs-url-类型探测流程) probe，确认 `extension=able` 后再继续。 - -## 注意事项 - -- 所有操作使用 ID（baseId/tableId/fieldId/recordId），不使用名称 -- records 的 cells key 是 fieldId，不是字段名称 -- cells 写入/读取格式见 [aitable-cell-value.md](./aitable/aitable-cell-value.md) -- 最佳实践见 [aitable-best-practices.md](./aitable/aitable-best-practices.md) - -## 自动化脚本 - -| 脚本 | 场景 | -|------|------| -| [bulk_add_fields.py](../scripts/bulk_add_fields.py) | 批量添加字段 | -| [import_records.py](../scripts/import_records.py) | 从 JSON/CSV 批量导入记录 | -| [aitable_export_via_task.py](../scripts/aitable_export_via_task.py) | 文件导出（export_data 轮询 + 下载） | -| [upload_attachment.py](../scripts/upload_attachment.py) | 上传附件到 AI 表格记录 | - -## 相关产品 - -- [doc](../../dingtalk-doc/references/doc.md) — 富文本文档编辑，不是结构化数据表格 +- AI 表格记录、字段、视图和自动化留在 AITable。 +- Base 结构复制/删除与 Base 内 Table、Dashboard、Section 操作走 AITable；只有整个 Base 的普通文件夹位置移动或外层存储重命名走 Drive。 +- 记录主键文档正文拿到真实 nodeId 后走 Doc。 +- Excel 式单元格、区域和公式操作走 Sheet，而不是 AITable。 diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md index 94d576e2..e8089b34 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md @@ -3,9 +3,9 @@ ## 建议操作顺序 ```bash -# 1) 先看配置模板（JSONC） +# 1) 只在缺少配置结构时读取模板 dws aitable dashboard config-example --format json -dws aitable chart widgets-example --format json +dws aitable +chart-widgets-example --format json # 2) 先拿 dashboard，再拿 chart 详情 dws aitable dashboard get --base-id --dashboard-id --format json @@ -15,6 +15,7 @@ dws aitable chart get --base-id --dashboard-id --chart- ## 要点 - `dashboard get` 返回的 `charts[].chartId` 可直接给 `chart get` 使用 +- 删除 dashboard 会级联删除其全部 chart；确认前必须说明该影响 - `dashboard share get` 可能返回 `404`（资源不存在或未开通），需按可重试错误处理，不要误判为参数拼错 - `chart share get` 可正常返回 `enabled/shareUrl`，用于分享状态判断 @@ -25,7 +26,7 @@ dws aitable chart get --base-id --dashboard-id --chart- | `dashboard get` | 获取仪表盘详情（含 charts 列表） | `--base-id` `--dashboard-id` | — | | `dashboard create` | 创建仪表盘 | `--base-id` + (`--config` 或 `--name`) | `--name` 简化版创建空看板；`--config` 传完整 JSON | | `dashboard update` | 更新仪表盘 | `--base-id` `--dashboard-id` + (`--config` 或 `--name`) | `--name` 仅改名；`--config` 更新完整配置 | -| `dashboard delete` | 删除仪表盘 | `--base-id` `--dashboard-id` `--yes` | — | +| `dashboard delete` | 删除仪表盘 | `--base-id` `--dashboard-id` `--yes` | 级联删除全部 chart，不可逆 | | `dashboard config-example` | 查看仪表盘配置模板 | 无 | 创建前先调此命令了解 config 结构 | | `dashboard arrange` | 自动重排图表布局 | `--base-id` `--dashboard-id` | 把图表按行铺满网格，避免某行只占半幅、留下大片空白；返回 `{totalColumns, layout, alignedChartCount}` | @@ -34,11 +35,11 @@ dws aitable chart get --base-id --dashboard-id --chart- | 命令 | 用途 | 必填参数 | |------|------|----------| | `chart get` | 获取图表详情 | `--base-id` `--dashboard-id` `--chart-id` | -| `chart create` | 创建图表 | `--base-id` `--dashboard-id` `--config` | +| `chart create` | 创建图表 | `--base-id` `--dashboard-id` `--config` `--layout` | | `chart update` | 更新图表配置 | `--base-id` `--dashboard-id` `--chart-id` `--config` | | `chart delete` | 删除图表 | `--base-id` `--dashboard-id` `--chart-id` `--yes` | -| `chart widgets-example` | 查看图表 widgets 配置模板 | 无 | +| `+chart-widgets-example` | 查看所有图表类型的 widgets 模板 | 无 | ## 配置获取流程 -创建图表前，必须先调用 `chart widgets-example` 查看配置模板，了解每种图表类型需要的字段结构，然后根据实际 tableId 和 fieldId 填充配置。 +已有符合当前 leaf Schema 的合法 config 时直接创建/更新，不读取模板。只有缺少结构时调用一次 `+chart-widgets-example`；该命令当前返回所有图表类型示例，随后只使用目标类型，并按真实 tableId/fieldId 填充后执行。 diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-primary-doc.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-primary-doc.md index ff9bd738..bb3ba46e 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-primary-doc.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-primary-doc.md @@ -9,7 +9,7 @@ ### 查询主键文档 ```bash -dws aitable record primary-doc-get --base-id BASE_ID --table-id TABLE_ID --record-id RECORD_ID +dws aitable +record-primary-doc-get --base-id BASE_ID --table-id TABLE_ID --record-id RECORD_ID ``` **参数：** @@ -22,7 +22,7 @@ dws aitable record primary-doc-get --base-id BASE_ID --table-id TABLE_ID --recor ### 创建主键文档 ```bash -dws aitable record primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID +dws aitable +record-primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID ``` **参数：** @@ -38,6 +38,7 @@ dws aitable record primary-doc-create --base-id BASE_ID --table-id TABLE_ID --fi ## 注意事项 - `fieldId` 必须是 primaryDoc 类型，否则返回 `INVALID_FIELD_TYPE` 错误 +- `primaryDoc` 是建表时的首字段能力，不能在已有普通首字段之后补建，也不能把普通字段改成 primaryDoc。需要该能力时应新建以 primaryDoc 为首字段的数据表并迁移数据；未经用户明确授权不要自动迁移。 - 传入不存在的 `recordId` 会返回 `RECORD_NOT_FOUND` 错误 - 创建后可通过 `dws doc update --node ` 写入文档内容，或 `dws doc read --node ` 读取 @@ -47,8 +48,8 @@ dws aitable record primary-doc-create --base-id BASE_ID --table-id TABLE_ID --fi # 1. 查询字段目录，拿到 primaryDoc 字段的 fieldId dws aitable field get --base-id BASE_ID --table-id TABLE_ID -# 2. 为某条记录创建主键文档 -dws aitable record primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID +# 2. 为记录创建主键文档 +dws aitable +record-primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID # 3. 拿到返回的 nodeId，用 dws doc 写入内容 dws doc update --node --content "# 项目方案\n\n文档正文内容..." diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-view-config.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-view-config.md index b133ac08..996347eb 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-view-config.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-view-config.md @@ -130,7 +130,7 @@ dws aitable view update field-widths --view-id GRID_ID --json '{"fldA":120,"fldB ### view update visible-fields（通用） -整组替换可见字段列表与顺序。首列字段（primaryDoc）必须保留在数组第一位。 +整组替换可见字段列表与顺序。`field get` 返回的第一个字段是系统行索引/主字段；无论它显示为 text 还是 primaryDoc，都必须保留在数组第一位，且不能隐藏。不要仅凭字段类型猜主字段。 > ⚠️ 注意：服务端**只接受 reorder，不接受真"隐藏字段"**——如果传入的列表比当前 columns 短，缺失的字段不会被隐藏。需要真正隐藏字段请到 AI 表格 Web UI。 @@ -144,6 +144,24 @@ dws aitable view update visible-fields --view-id VIEW_ID --field-ids fldPrimary, dws aitable view update visible-fields --view-id VIEW_ID --json '["fldPrimary","fldA","fldB"]' ``` +### 列顺序最短闭环 + +用户说“客户名称最左、状态在金额前”时，不要用通用 `+view-update --config` 探索： + +1. `dws aitable field get --base-id --table-id --format json` 取字段有序列表；第一个 fieldId 固定为数组第 1 项。目标 viewId 从真实上下文或 `view get` 返回中取得。 +2. `dws aitable view get visible-fields ...` 取当前完整列数组；必须保留全部现有字段，因为该接口只支持 reorder，不是真隐藏。 +3. 只重排目标：`[主字段, 客户名称, ..., 状态, 金额, ...]`，其他字段保持相对顺序；一次执行 `view update visible-fields`。 +4. 再次 `view get visible-fields`，数组完全一致才算完成。遇到 `PRIMARY_FIELD_CANNOT_BE_MOVED/HIDDEN` 立即停止，重新按步骤 1 构造一次；禁止继续猜排列。 + +“固定/冻结左侧列”与“放到最左边”不是同一操作。只有 Grid 支持冻结；若要冻结主字段后的目标列，需要冻结前 N 列（例如目标位于第 2 列则 count=2）： + +```bash +dws aitable +view-set-frozen-cols --base-id --table-id --view-id --count +dws aitable +view-get-frozen-cols --base-id --table-id --view-id +``` + +Kanban/Gallery 等视图只调整列顺序，不尝试冻结。 + ### view update filter / sort / group（通用，纯 --json） ```bash diff --git a/skills/multi/dingtalk-aitable/references/intent-guide.md b/skills/multi/dingtalk-aitable/references/intent-guide.md index a1428eaf..da159a00 100644 --- a/skills/multi/dingtalk-aitable/references/intent-guide.md +++ b/skills/multi/dingtalk-aitable/references/intent-guide.md @@ -1,10 +1,16 @@ -# aitable 局部意图消歧 +# AITable 局部意图消歧 -本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。 +| 用户表达 | 归属 | 理由 | +|---|---|---| +| AI 表格、多维表、Base、Table、字段、记录、视图、表单、仪表盘、自动化 | AITable | 操作 AITable 的业务数据与配置 | +| 表格链接，需要读取记录 | AITable | 先用 `+url-resolve` 取稳定 ID，再用 `+record-query` | +| 只有 Base/Table 名称，需要读取记录 | AITable | 先用 `+resolve-base` / `+resolve-table` 唯一解析，再查询记录 | +| 只复制 Base 结构、删除整个 Base | AITable | 复制到已知文档文件夹用 `+base-copy --target-folder-id ... --only-struct`；删除用真实 baseId。不要 Drive 完整复制后逐表删数据 | +| Base 整体移动到普通文件夹、外层存储重命名 | Drive | 这是 Base 作为单个存储节点的外层位置/名称动作 | +| Base 内 Table、Dashboard、Section 的复制/移动/重命名/删除 | AITable | 这些是 Base 内 nsheet/业务结构，不是独立 Drive dentry | +| Base 角色、高级权限 | AITable | `+role-*` / `+advperm-*`；仅普通文件 ACL 才走 Drive | +| 记录主键文档正文 | Doc | AITable 只取/建关联，正文由 Doc 处理 | +| Excel 式单元格、区域、工作表、公式 | Sheet（dingtalk-misc） | 二维电子表格，不是多维表记录模型 | +| CSV/JSON 数据进入现有 AI 表格 | AITable import 或 record create | 需要保留导入任务语义时用 import；已映射字段时直接写记录 | -| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 | -|---|---|---|---|---| -| "帮我建一个项目跟踪表" | 创建数据表格 | `aitable` | `doc` / `sheet` | 涉及结构化数据/行列操作，不是富文本文档或电子表格 | -| "帮我写个项目周报" | 创建钉钉文档 | `doc` | `aitable` | 富文本内容创作，不是数据表 | -| "创建一个电子表格" | 创建表格文档 | `sheet` | `aitable` | Excel 式表格/单元格操作，不是多维表记录 | -| "帮我读一下表格 A1:D10 的数据" | 读取单元格数据 | `sheet` | `aitable` | 按单元格区域读写，不是按记录查询 | +若链接类型不明确，先做 URL 类型预检；不要仅凭 URL 文本猜产品。明确是 AI 表格后才加载本 Skill。 From 5aaf22782c6c51c787c0c630d8c594537a08b3da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 15:04:22 +0800 Subject: [PATCH 216/250] fix(skills): remove obsolete drive tree helper --- .../dingtalk-drive/scripts/drive_tree_list.py | 130 ------------------ 1 file changed, 130 deletions(-) delete mode 100644 skills/multi/dingtalk-drive/scripts/drive_tree_list.py diff --git a/skills/multi/dingtalk-drive/scripts/drive_tree_list.py b/skills/multi/dingtalk-drive/scripts/drive_tree_list.py deleted file mode 100644 index a7e3439b..00000000 --- a/skills/multi/dingtalk-drive/scripts/drive_tree_list.py +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env python3 -""" -递归列出钉盘目录树结构（可指定深度） - -用法: - python drive_tree_list.py # 列出根目录 - python drive_tree_list.py --depth 2 # 递归 2 层 - python drive_tree_list.py --parent-id # 指定目录 - python drive_tree_list.py --dry-run -""" - -import sys -import json -import subprocess -import argparse -from typing import List, Any, Optional - - -def run_dws( - args: List[str], dry_run: bool = False, -) -> Optional[Any]: - cmd = ['dws'] + args - if dry_run: - print(f"[dry-run] {' '.join(cmd)}") - return None - try: - result = subprocess.run( - cmd, capture_output=True, text=True, timeout=60 - ) - if result.returncode != 0: - print(f"错误：{result.stderr.strip()}", file=sys.stderr) - return None - return json.loads(result.stdout) - except (subprocess.TimeoutExpired, json.JSONDecodeError, - FileNotFoundError) as e: - print(f"错误：{e}", file=sys.stderr) - return None - - -def list_dir( - parent_id: str = '', dry_run: bool = False, -) -> list: - cmd_args = [ - 'drive', 'list', '--max', '50', '--format', 'json', - ] - if parent_id: - cmd_args.extend(['--parent-id', parent_id]) - data = run_dws(cmd_args, dry_run=dry_run) - if not data: - return [] - if isinstance(data, list): - return data - if isinstance(data, dict): - inner = data.get('result', data) - if isinstance(inner, dict): - return inner.get('items', inner.get('dentryList', [])) - if isinstance(inner, list): - return inner - return [] - - -def print_tree( - items: list, depth: int, max_depth: int, - prefix: str = '', dry_run: bool = False, -): - for i, item in enumerate(items): - is_last = (i == len(items) - 1) - connector = '└── ' if is_last else '├── ' - name = item.get('name') or item.get('fileName', '?') - item_type = item.get('type') or item.get('dentryType', '') - is_dir = str(item_type).lower() in ( - 'folder', 'directory', '1', 'FOLDER' - ) - icon = '📁' if is_dir else '📄' - size_str = '' - size = item.get('size') or item.get('fileSize') - if size and not is_dir: - size = int(size) - if size > 1024 * 1024: - size_str = f" ({size / 1024 / 1024:.1f}MB)" - elif size > 1024: - size_str = f" ({size / 1024:.1f}KB)" - else: - size_str = f" ({size}B)" - - print(f"{prefix}{connector}{icon} {name}{size_str}") - - if is_dir and depth < max_depth: - child_prefix = prefix + (' ' if is_last else '│ ') - dentry_id = (item.get('dentryUuid') - or item.get('id', '')) - if dentry_id: - children = list_dir(dentry_id, dry_run=dry_run) - print_tree( - children, depth + 1, max_depth, - child_prefix, dry_run, - ) - - -def main(): - parser = argparse.ArgumentParser( - description='递归列出钉盘目录树' - ) - parser.add_argument( - '--parent-id', default='', help='起始目录 ID' - ) - parser.add_argument( - '--depth', type=int, default=1, - help='递归深度 (默认 1, 最大 5)', - ) - parser.add_argument('--dry-run', action='store_true') - args = parser.parse_args() - args.depth = min(args.depth, 5) - - root_name = args.parent_id or '我的文件' - print(f"📁 {root_name}") - - items = list_dir(args.parent_id, dry_run=args.dry_run) - if args.dry_run: - return - if not items: - print(' (空目录)') - return - - print_tree(items, 0, args.depth, '', args.dry_run) - print(f"\n共 {len(items)} 个项目 (根目录)") - - -if __name__ == '__main__': - main() From b334794168967efce657ce99f6c65cdde7652398 Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 22:08:20 +0800 Subject: [PATCH 217/250] chore: approve primary flag migrations to #85349380 --- docs/cli-interface-flag-migrations.md | 2 +- .../approved-flag-migrations-v1.json | 315 ++++++++++++++++++ 2 files changed, 316 insertions(+), 1 deletion(-) diff --git a/docs/cli-interface-flag-migrations.md b/docs/cli-interface-flag-migrations.md index 76d11608..d4a50124 100644 --- a/docs/cli-interface-flag-migrations.md +++ b/docs/cli-interface-flag-migrations.md @@ -41,7 +41,7 @@ PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁 scripts/policy/interface-migrations/approved-flag-migrations-v1.json ``` -清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。当前清单登记了 IM ID rename 的 `pending` 记录；`pending` 只记录已评审计划，候选与 merge-base 仍必须精确匹配 `before`，因此本治理 PR **不授权 PR #904 或任何产品接口变化**。 +清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。清单中的 `pending` 记录只记录已评审计划，并授权其精确列出的后续产品迁移；候选与 merge-base 仍必须精确匹配 `before`，不能授权同一个提交中的接口变化，也不能作为其他命令或参数的通配豁免。 ## 两阶段迁移与回执清理 diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index 7d5ed345..fc66b357 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -1158,6 +1158,321 @@ }, "state": "pending", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" + }, + { + "command": "dws aisearch", + "legacy": { + "name": "keyword", + "before": {"present": true, "type": "string", "shorthand": "w", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "shorthand": "w", "scope": "local", "alias_of": "query"} + }, + "canonical": { + "name": "query", + "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws aisearch person", + "legacy": { + "name": "keyword", + "before": {"present": true, "type": "string", "shorthand": "w", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "shorthand": "w", "scope": "local", "alias_of": "query"} + }, + "canonical": { + "name": "query", + "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +broadcast", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +dm", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +messages-batch-send-by-bot", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +messages-reply", + "legacy": { + "name": "conversation-id", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "group"} + }, + "canonical": { + "name": "group", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +messages-reply", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +messages-send-by-bot", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +messages-send-by-webhook", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat +send-to-group", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message reply", + "legacy": { + "name": "conversation-id", + "before": {"present": true, "type": "string", "required": true, "scope": "local"}, + "after": {"present": true, "type": "string", "required": false, "hidden": true, "scope": "local", "alias_of": "group"} + }, + "canonical": { + "name": "group", + "before": {"present": false}, + "after": {"present": true, "type": "string", "required": true, "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message reply", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "required": true, "scope": "local"}, + "after": {"present": true, "type": "string", "required": false, "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "required": true, "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message send", + "legacy": { + "name": "file-path", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "file"} + }, + "canonical": { + "name": "file", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message send", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message send-by-bot", + "legacy": { + "name": "file-path", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "file"} + }, + "canonical": { + "name": "file", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message send-by-bot", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws chat message send-by-webhook", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "required": true, "scope": "local"}, + "after": {"present": true, "type": "string", "required": false, "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "required": true, "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws doc +doc-append", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws doc block insert", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws doc block update", + "legacy": { + "name": "text", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "content"} + }, + "canonical": { + "name": "content", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." + }, + { + "command": "dws todo task add-attachment", + "legacy": { + "name": "file-path", + "before": {"present": true, "type": "string", "scope": "local"}, + "after": {"present": true, "type": "string", "hidden": true, "scope": "local", "alias_of": "file"} + }, + "canonical": { + "name": "file", + "before": {"present": false}, + "after": {"present": true, "type": "string", "scope": "local"} + }, + "state": "pending", + "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." } ] } From 9dc7f64b8795f7d27b8cbbf2a8e43c93d834e3d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 15:18:29 +0800 Subject: [PATCH 218/250] test(aitable): cover table bootstrap confirmation --- .../aitable/table_bootstrap_e2e_test.go | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/internal/shortcut/aitable/table_bootstrap_e2e_test.go b/internal/shortcut/aitable/table_bootstrap_e2e_test.go index 140f3d2f..d6f6b410 100644 --- a/internal/shortcut/aitable/table_bootstrap_e2e_test.go +++ b/internal/shortcut/aitable/table_bootstrap_e2e_test.go @@ -33,6 +33,14 @@ func TestCrossPlatformCoverageTableBootstrapCreatesChunksAndVerifies(t *testing. if got := len(caller.calls); got != 4 { t.Fatalf("table bootstrap calls = %d, want 4: %#v", got, caller.calls) } + wantFirstArgs := map[string]any{ + "baseId": "base", + "tableName": "任务", + "fields": fields[:15], + } + if caller.calls[0].product != serverMain || caller.calls[0].tool != "create_table" || mustJSON(t, caller.calls[0].args) != mustJSON(t, wantFirstArgs) { + t.Fatalf("table bootstrap first call = %#v, want product:%q tool:create_table args:%s", caller.calls[0], serverMain, mustJSON(t, wantFirstArgs)) + } if caller.calls[0].tool != "create_table" || caller.calls[1].tool != "create_fields" || caller.calls[2].tool != "get_tables" || caller.calls[3].tool != "get_fields" { t.Fatalf("table bootstrap call order = %#v", caller.calls) } @@ -44,6 +52,22 @@ func TestCrossPlatformCoverageTableBootstrapCreatesChunksAndVerifies(t *testing. } } +func TestCrossPlatformCoverageTableBootstrapRequiresConfirmationBeforeMCP(t *testing.T) { + caller := &upsertByKeyCaller{} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", mustJSON(t, bootstrapFields(1))) + if out != "" { + t.Fatalf("unconfirmed table bootstrap output = %q, want empty", out) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || typed.Reason != "confirmation_required" { + t.Fatalf("unconfirmed table bootstrap error = %#v, want confirmation_required", err) + } + if len(caller.calls) != 0 { + t.Fatalf("unconfirmed table bootstrap calls = %#v, want none", caller.calls) + } +} + func TestCrossPlatformCoverageTableBootstrapValidationPublishesRecovery(t *testing.T) { caller := &upsertByKeyCaller{} out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", From f57d9a51f4b2661dad28904af7145b1bae08e8e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 15:59:59 +0800 Subject: [PATCH 219/250] fix(aitable): secure recovery commands --- internal/helpers/shell_quote.go | 6 +- .../shell_quote_roundtrip_unix_test.go | 2 +- internal/helpers/shell_quote_test.go | 4 +- internal/shortcut/aitable/base_composite.go | 8 +-- .../aitable/base_composite_e2e_test.go | 64 ++++++++++++++++++- internal/shortcut/aitable/composite_output.go | 10 +++ internal/shortcut/aitable/table_bootstrap.go | 2 +- .../aitable/aitable-dashboard-chart.md | 4 +- 8 files changed, 86 insertions(+), 14 deletions(-) diff --git a/internal/helpers/shell_quote.go b/internal/helpers/shell_quote.go index a06f78f5..d3b064ab 100644 --- a/internal/helpers/shell_quote.go +++ b/internal/helpers/shell_quote.go @@ -2,7 +2,7 @@ package helpers import "strings" -// shellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。 +// ShellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。 // // 为什么需要它：错误提示里的恢复命令是给用户直接复制到 shell 执行的，其中的查询域取自用户 // 输入（--workspace 的常见形态就是带查询串的 URL）。裸拼接下，合法 URL 里的 `&` 就会把命令 @@ -21,7 +21,7 @@ import "strings" // // 空串必须显式引用成一对空单引号，否则该参数会从 argv 里整个消失，后面的 token 会被前一个 // flag 吞掉。 -func shellQuoteArg(s string) string { +func ShellQuoteArg(s string) string { if s == "" { return "''" } @@ -41,7 +41,7 @@ func shellValueIsBare(s string) bool { // driveLatestPosixScopeValue 是 POSIX shell 下把用户值放进可复制命令的策略：单引号内 sh 不做 // 任何展开，因此含元字符的值引用后即可安全内联。第二个返回值恒为 true。 func driveLatestPosixScopeValue(value string) (string, bool) { - return shellQuoteArg(value), true + return ShellQuoteArg(value), true } // driveLatestWindowsScopeValue 是 Windows 构建下的策略：只内联本身就安全的值，其余一律不进 diff --git a/internal/helpers/shell_quote_roundtrip_unix_test.go b/internal/helpers/shell_quote_roundtrip_unix_test.go index 9afc5213..daa2edab 100644 --- a/internal/helpers/shell_quote_roundtrip_unix_test.go +++ b/internal/helpers/shell_quote_roundtrip_unix_test.go @@ -51,7 +51,7 @@ func TestCrossPlatformCoverageShellQuoteArgRoundTrip(t *testing.T) { for _, want := range values { t.Run(want, func(t *testing.T) { - quoted := shellQuoteArg(want) + quoted := ShellQuoteArg(want) // 1) 未被拆参也未被吞掉：位置参数个数必须恰好为 1。 // 引用失效时 "sp 7" 会变 2 个、"" 会变 0 个、$(id) 会变 id 的输出词数。 diff --git a/internal/helpers/shell_quote_test.go b/internal/helpers/shell_quote_test.go index 2dacbf7d..158f32a5 100644 --- a/internal/helpers/shell_quote_test.go +++ b/internal/helpers/shell_quote_test.go @@ -69,8 +69,8 @@ func TestCrossPlatformCoverageShellQuoteArg(t *testing.T) { } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { - if got := shellQuoteArg(tc.in); got != tc.want { - t.Fatalf("shellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want) + if got := ShellQuoteArg(tc.in); got != tc.want { + t.Fatalf("ShellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want) } }) } diff --git a/internal/shortcut/aitable/base_composite.go b/internal/shortcut/aitable/base_composite.go index fd40a21f..c5dcbaa4 100644 --- a/internal/shortcut/aitable/base_composite.go +++ b/internal/shortcut/aitable/base_composite.go @@ -204,7 +204,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { result.Status = "unknown" result.FailedCount = len(tables) result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying"} - result.NextCommand = fmt.Sprintf("dws aitable +base-search --query %q --format json", rt.Str("name")) + result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json") return compositeError(result, err, false) } baseID := findStringByKeys(baseData, "baseId") @@ -212,11 +212,11 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { result.Status = "unknown" result.Result = baseData result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying"} - result.NextCommand = fmt.Sprintf("dws aitable +base-search --query %q --format json", rt.Str("name")) + result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json") return compositeError(result, fmt.Errorf("create_base response is missing baseId"), false) } result.Resolved = map[string]any{"baseId": baseID} - result.NextCommand = fmt.Sprintf("dws aitable +base-get --base-id %s --format json", baseID) + result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-get", "--base-id", baseID, "--format", "json") result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_base", "baseId": baseID}) result.CompletedSteps = append(result.CompletedSteps, compositeStep{Index: 1, Name: "create base", Tool: "create_base", Status: "completed", Result: baseData}) baseRead, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID}) @@ -248,7 +248,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { return compositeError(result, createErr, false) } result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": tableID, "name": spec.Name}) - result.NextCommand = fmt.Sprintf("dws aitable +table-get --base-id %s --table-id %s --format json", baseID, tableID) + result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+table-get", "--base-id", baseID, "--table-id", tableID, "--format", "json") for offset := initialEnd; offset < len(spec.Fields); offset += 15 { end := minInt(offset+15, len(spec.Fields)) _, fieldErr := rt.CallMCPWriteDataStrict(serverMain, "create_fields", map[string]any{ diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index ee1f00a2..52f5bfc6 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -289,11 +289,73 @@ func TestCrossPlatformCoverageBaseBootstrapFailurePublishesExactRecovery(t *test if !errors.As(err, &typed) || len(typed.Actions) != 1 || len(typed.AvailableFlags) != 4 { t.Fatalf("bootstrap typed recovery = %#v", err) } - if typed.Actions[0] != `dws aitable +base-search --query "Project" --format json` { + if typed.Actions[0] != `dws aitable +base-search --query Project --format json` { t.Fatalf("bootstrap next command = %#v", typed.Actions) } } +func TestCrossPlatformCoverageAITableRecoveryCommandsQuoteUntrustedValues(t *testing.T) { + t.Run("base name", func(t *testing.T) { + name := `项目 $(touch /tmp/pwn) 'Q'` + out, err := runAITableCompositeCLI(t, &upsertByKeyCaller{steps: []upsertByKeyStep{{text: `{}`}}}, + "+base-bootstrap", "--name", name, "--tables", marshalBootstrapTables(t, nil), "--yes") + if out != "" || err == nil { + t.Fatalf("hostile base name recovery = output:%q err:%v", out, err) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 { + t.Fatalf("hostile base name error = %#v", err) + } + want := `dws aitable +base-search --query '项目 $(touch /tmp/pwn) '\''Q'\''' --format json` + if typed.Actions[0] != want { + t.Fatalf("base name recovery = %q, want %q", typed.Actions[0], want) + } + }) + + t.Run("base id", func(t *testing.T) { + baseID := `base;printf hacked` + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: mustJSON(t, map[string]any{"baseId": baseID})}, + {err: errors.New("verify base failed")}, + }} + out, err := runAITableCompositeCLI(t, caller, "+base-bootstrap", + "--name", "Project", "--tables", marshalBootstrapTables(t, nil), "--yes") + if out != "" || err == nil { + t.Fatalf("hostile base id recovery = output:%q err:%v", out, err) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 { + t.Fatalf("hostile base id error = %#v", err) + } + want := `dws aitable +base-get --base-id 'base;printf hacked' --format json` + if typed.Actions[0] != want { + t.Fatalf("base id recovery = %q, want %q", typed.Actions[0], want) + } + }) + + t.Run("base and table ids", func(t *testing.T) { + baseID := `base id;exit 1` + tableID := "table`uname`'x" + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: mustJSON(t, map[string]any{"tableId": tableID})}, + {err: errors.New("verify table failed")}, + }} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", baseID, "--name", "任务", "--fields", `[]`, "--yes") + if out != "" || err == nil { + t.Fatalf("hostile table ids recovery = output:%q err:%v", out, err) + } + var typed *apperrors.Error + if !errors.As(err, &typed) || len(typed.Actions) != 1 { + t.Fatalf("hostile table ids error = %#v", err) + } + want := `dws aitable +table-get --base-id 'base id;exit 1' --table-id 'table` + "`uname`" + `'\''x' --format json` + if typed.Actions[0] != want { + t.Fatalf("table ids recovery = %q, want %q", typed.Actions[0], want) + } + }) +} + func TestCrossPlatformCoverageBaseBootstrapRecoversFieldCallErrorE2E(t *testing.T) { fields := bootstrapFields(16) caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ diff --git a/internal/shortcut/aitable/composite_output.go b/internal/shortcut/aitable/composite_output.go index a1b91d5a..751a5ada 100644 --- a/internal/shortcut/aitable/composite_output.go +++ b/internal/shortcut/aitable/composite_output.go @@ -5,8 +5,10 @@ package aitable import ( "fmt" + "strings" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" ) const aitableCompositeContractVersion = "aitable.composite.v1" @@ -52,6 +54,14 @@ func newCompositeResult(operation string) compositeResult { } } +func aitableRecoveryCommand(argv ...string) string { + quoted := make([]string, len(argv)) + for index, arg := range argv { + quoted[index] = helpers.ShellQuoteArg(arg) + } + return strings.Join(quoted, " ") +} + func compositeError(result compositeResult, cause error, retryable bool) error { result.Retryable = retryable if result.Status == "success" { diff --git a/internal/shortcut/aitable/table_bootstrap.go b/internal/shortcut/aitable/table_bootstrap.go index c06b9e71..0252ad1b 100644 --- a/internal/shortcut/aitable/table_bootstrap.go +++ b/internal/shortcut/aitable/table_bootstrap.go @@ -98,7 +98,7 @@ func executeTableBootstrap(rt *shortcut.RuntimeContext) error { if created.TableID != "" { result.Resolved["tableId"] = created.TableID result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": created.TableID, "name": tableName}) - result.NextCommand = fmt.Sprintf("dws aitable +table-get --base-id %s --table-id %s --format json", baseID, created.TableID) + result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+table-get", "--base-id", baseID, "--table-id", created.TableID, "--format", "json") } if err != nil { if created.TableID == "" { diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md index e8089b34..3396a90e 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md @@ -26,7 +26,7 @@ dws aitable chart get --base-id --dashboard-id --chart- | `dashboard get` | 获取仪表盘详情（含 charts 列表） | `--base-id` `--dashboard-id` | — | | `dashboard create` | 创建仪表盘 | `--base-id` + (`--config` 或 `--name`) | `--name` 简化版创建空看板；`--config` 传完整 JSON | | `dashboard update` | 更新仪表盘 | `--base-id` `--dashboard-id` + (`--config` 或 `--name`) | `--name` 仅改名；`--config` 更新完整配置 | -| `dashboard delete` | 删除仪表盘 | `--base-id` `--dashboard-id` `--yes` | 级联删除全部 chart，不可逆 | +| `dashboard delete` | 删除仪表盘 | `--base-id` `--dashboard-id` | 级联删除全部 chart，不可逆；由 Runtime 请求确认，Reference 不携带确认绕过参数 | | `dashboard config-example` | 查看仪表盘配置模板 | 无 | 创建前先调此命令了解 config 结构 | | `dashboard arrange` | 自动重排图表布局 | `--base-id` `--dashboard-id` | 把图表按行铺满网格，避免某行只占半幅、留下大片空白；返回 `{totalColumns, layout, alignedChartCount}` | @@ -37,7 +37,7 @@ dws aitable chart get --base-id --dashboard-id --chart- | `chart get` | 获取图表详情 | `--base-id` `--dashboard-id` `--chart-id` | | `chart create` | 创建图表 | `--base-id` `--dashboard-id` `--config` `--layout` | | `chart update` | 更新图表配置 | `--base-id` `--dashboard-id` `--chart-id` `--config` | -| `chart delete` | 删除图表 | `--base-id` `--dashboard-id` `--chart-id` `--yes` | +| `chart delete` | 删除图表 | `--base-id` `--dashboard-id` `--chart-id` | 不可逆；由 Runtime 请求确认，Reference 不携带确认绕过参数 | | `+chart-widgets-example` | 查看所有图表类型的 widgets 模板 | 无 | ## 配置获取流程 From 176a55635545cfe1d066a3e46100f7fe5bc3defa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 17:12:15 +0800 Subject: [PATCH 220/250] fix(aitable): verify declared field structures --- internal/shortcut/aitable/base_composite.go | 100 +++++++++++++++--- .../aitable/base_composite_e2e_test.go | 17 ++- internal/shortcut/aitable/table_bootstrap.go | 24 ++++- .../aitable/table_bootstrap_e2e_test.go | 35 ++++++ internal/shortcut/aitable/table_copy.go | 11 +- .../aitable/table_copy_coverage_gap_test.go | 5 + 6 files changed, 168 insertions(+), 24 deletions(-) diff --git a/internal/shortcut/aitable/base_composite.go b/internal/shortcut/aitable/base_composite.go index c5dcbaa4..91cca852 100644 --- a/internal/shortcut/aitable/base_composite.go +++ b/internal/shortcut/aitable/base_composite.go @@ -5,6 +5,7 @@ package aitable import ( "fmt" + "reflect" "strings" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" @@ -102,11 +103,22 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) { return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index)) } } + fieldNames := map[string]bool{} for fieldIndex, field := range fields { object, ok := field.(map[string]any) - if !ok || strings.TrimSpace(stringValue(object, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(object, "type")) == "" { + fieldName := strings.TrimSpace(stringValue(object, "fieldName", "name")) + if !ok || fieldName == "" || strings.TrimSpace(stringValue(object, "type")) == "" { return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex)) } + if fieldNames[fieldName] { + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].fieldName %q 不能重复", index, fieldIndex, fieldName)) + } + fieldNames[fieldName] = true + if config, exists := object["config"]; exists { + if _, ok := config.(map[string]any); !ok { + return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].config 必须是 JSON 对象", index, fieldIndex)) + } + } } out = append(out, bootstrapTable{Name: name, Fields: fields}) } @@ -271,10 +283,13 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { } fieldsData, verifyErr := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": baseID, "tableId": tableID}) fields, found := findNamedObjectList(fieldsData, "fields", "fieldList") - if verifyErr != nil || !found || !containsAllFieldNames(fields, spec.Fields) { - if verifyErr == nil { - verifyErr = fmt.Errorf("field read-back for table %s does not contain the declared field set", tableID) - } + if verifyErr == nil && !found { + verifyErr = fmt.Errorf("field read-back for table %s is missing the fields collection", tableID) + } + if verifyErr == nil { + verifyErr = verifyDeclaredFieldStructures(fields, spec.Fields) + } + if verifyErr != nil { result.Status = "partial_success" result.CompletedCount = index result.FailedCount = len(tables) - index @@ -391,16 +406,73 @@ func deepContainsString(value any, expected string) bool { return false } -func containsAllFieldNames(actual []map[string]any, expected []any) bool { - names := map[string]bool{} +func verifyDeclaredFieldStructures(actual []map[string]any, expected []any) error { + actualByName := map[string][]map[string]any{} for _, field := range actual { - names[stringValue(field, "fieldName", "name")] = true - } - for _, raw := range expected { - field, _ := raw.(map[string]any) - if !names[stringValue(field, "fieldName", "name")] { - return false + name := strings.TrimSpace(stringValue(field, "fieldName", "name")) + if name != "" { + actualByName[name] = append(actualByName[name], field) } } - return true + for index, raw := range expected { + field, ok := raw.(map[string]any) + if !ok { + return fmt.Errorf("declared field at index %d is not an object", index) + } + name := strings.TrimSpace(stringValue(field, "fieldName", "name")) + matches := actualByName[name] + if len(matches) == 0 { + return fmt.Errorf("field read-back is missing declared field %q", name) + } + if len(matches) != 1 { + return fmt.Errorf("field read-back contains %d fields named %q", len(matches), name) + } + actualField := matches[0] + expectedType := strings.TrimSpace(stringValue(field, "type")) + actualType := strings.TrimSpace(stringValue(actualField, "type", "fieldType")) + if actualType != expectedType { + return fmt.Errorf("field %q type mismatch: got %q, want %q", name, actualType, expectedType) + } + for _, key := range []string{"config", "aiConfig"} { + expectedConfig, declared := field[key] + if !declared { + continue + } + actualConfig, found := actualField[key] + if !found || !declaredValueMatches(actualConfig, expectedConfig) { + return fmt.Errorf("field %q %s mismatch", name, key) + } + } + } + return nil +} + +func declaredValueMatches(actual, expected any) bool { + switch expectedValue := expected.(type) { + case map[string]any: + actualValue, ok := actual.(map[string]any) + if !ok { + return false + } + for key, expectedChild := range expectedValue { + actualChild, found := actualValue[key] + if !found || !declaredValueMatches(actualChild, expectedChild) { + return false + } + } + return true + case []any: + actualValue, ok := actual.([]any) + if !ok || len(actualValue) != len(expectedValue) { + return false + } + for index := range expectedValue { + if !declaredValueMatches(actualValue[index], expectedValue[index]) { + return false + } + } + return true + default: + return reflect.DeepEqual(actual, expected) + } } diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index 52f5bfc6..ea031a98 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -197,6 +197,8 @@ func TestCrossPlatformCoverageBaseBootstrapInputValidation(t *testing.T) { "fields not array": `[{"name":"T","fields":{}}]`, "field not object": `[{"name":"T","fields":[1]}]`, "field missing type": `[{"name":"T","fields":[{"fieldName":"F"}]}]`, + "duplicate field": `[{"name":"T","fields":[{"fieldName":"F","type":"text"},{"fieldName":" F ","type":"number"}]}]`, + "field config array": `[{"name":"T","fields":[{"fieldName":"F","type":"text","config":[]}]}]`, } for name, raw := range cases { t.Run(name, func(t *testing.T) { @@ -260,6 +262,7 @@ func TestCrossPlatformCoverageBaseBootstrapFailureStagesE2E(t *testing.T) { {name: "verify table error", steps: []upsertByKeyStep{{text: `{"baseId":"b"}`}, {text: `{"baseId":"b"}`}, {text: `{"tableId":"t"}`}, {err: errors.New("verify table failed")}}}, {name: "verify table wrong id", steps: []upsertByKeyStep{{text: `{"baseId":"b"}`}, {text: `{"baseId":"b"}`}, {text: `{"tableId":"t"}`}, {text: `{"tables":[]}`}}}, {name: "verify fields error", steps: []upsertByKeyStep{{text: `{"baseId":"b"}`}, {text: `{"baseId":"b"}`}, {text: `{"tableId":"t"}`}, {text: `{"tables":[{"tableId":"t"}]}`}, {err: errors.New("verify fields failed")}}}, + {name: "verify fields missing collection", steps: []upsertByKeyStep{{text: `{"baseId":"b"}`}, {text: `{"baseId":"b"}`}, {text: `{"tableId":"t"}`}, {text: `{"tables":[{"tableId":"t"}]}`}, {text: `{}`}}}, {name: "verify fields mismatch", steps: []upsertByKeyStep{{text: `{"baseId":"b"}`}, {text: `{"baseId":"b"}`}, {text: `{"tableId":"t"}`}, {text: `{"tables":[{"tableId":"t"}]}`}, {text: `{"fields":[]}`}}, extra: []string{"--folder-id", "folder", "--template-id", "template"}, withField: true}, } for _, tc := range cases { @@ -383,9 +386,21 @@ func TestCrossPlatformCoverageBaseCompositeShapeHelpers(t *testing.T) { if _, ok := findNamedObjectList(map[string]any{"tables": []any{"bad"}}, "tables"); ok { t.Fatal("non-object list item must fail") } - if containsAllFieldNames([]map[string]any{{"fieldName": "A"}}, []any{map[string]any{"fieldName": "B"}}) { + if err := verifyDeclaredFieldStructures([]map[string]any{{"fieldName": "A", "fieldType": "text"}}, []any{map[string]any{"fieldName": "B", "type": "text"}}); err == nil { t.Fatal("missing field name must fail") } + if err := verifyDeclaredFieldStructures(nil, []any{"bad"}); err == nil { + t.Fatal("non-object declaration must fail") + } + if declaredValueMatches("bad", map[string]any{"x": 1}) { + t.Fatal("object declaration must not match a scalar") + } + if declaredValueMatches("bad", []any{}) || declaredValueMatches([]any{}, []any{1}) { + t.Fatal("array declaration must require an array of equal length") + } + if declaredValueMatches([]any{1}, []any{2}) { + t.Fatal("array declaration must compare each item") + } if got := findStringByKeys(map[string]any{"items": []any{map[string]any{"nested": " value "}}}, "nested"); got != "value" { t.Fatalf("nested array string = %q", got) } diff --git a/internal/shortcut/aitable/table_bootstrap.go b/internal/shortcut/aitable/table_bootstrap.go index 0252ad1b..010faf78 100644 --- a/internal/shortcut/aitable/table_bootstrap.go +++ b/internal/shortcut/aitable/table_bootstrap.go @@ -60,11 +60,22 @@ func parseBootstrapFields(raw string) ([]any, error) { if len(fields) > 100 { return nil, tableBootstrapValidation("--fields 最多接受 100 个字段") } + seen := map[string]bool{} for index, rawField := range fields { field, ok := rawField.(map[string]any) - if !ok || strings.TrimSpace(stringValue(field, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(field, "type")) == "" { + name := strings.TrimSpace(stringValue(field, "fieldName", "name")) + if !ok || name == "" || strings.TrimSpace(stringValue(field, "type")) == "" { return nil, tableBootstrapValidation(fmt.Sprintf("--fields[%d] 必须包含 fieldName 和 type", index)) } + if seen[name] { + return nil, tableBootstrapValidation(fmt.Sprintf("--fields[%d].fieldName %q 不能重复", index, name)) + } + seen[name] = true + if config, exists := field["config"]; exists { + if _, ok := config.(map[string]any); !ok { + return nil, tableBootstrapValidation(fmt.Sprintf("--fields[%d].config 必须是 JSON 对象", index)) + } + } } return fields, nil } @@ -149,10 +160,13 @@ func createAndVerifyTableStructure(rt *shortcut.RuntimeContext, baseID, tableNam } fieldsData, err := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": baseID, "tableId": created.TableID}) created.Fields, _ = findNamedObjectList(fieldsData, "fields", "fieldList") - if err != nil || created.Fields == nil || !containsAllFieldNames(created.Fields, fields) { - if err == nil { - err = fmt.Errorf("field read-back for table %s does not contain the declared field set", created.TableID) - } + if err == nil && created.Fields == nil { + err = fmt.Errorf("field read-back for table %s is missing the fields collection", created.TableID) + } + if err == nil { + err = verifyDeclaredFieldStructures(created.Fields, fields) + } + if err != nil { return created, err } return created, nil diff --git a/internal/shortcut/aitable/table_bootstrap_e2e_test.go b/internal/shortcut/aitable/table_bootstrap_e2e_test.go index d6f6b410..9941dc71 100644 --- a/internal/shortcut/aitable/table_bootstrap_e2e_test.go +++ b/internal/shortcut/aitable/table_bootstrap_e2e_test.go @@ -89,6 +89,8 @@ func TestCrossPlatformCoverageTableBootstrapInputValidation(t *testing.T) { "too many fields": mustJSON(t, tooMany), "non-object field": `[1]`, "field missing type": `[{"fieldName":"标题"}]`, + "duplicate name": `[{"fieldName":"标题","type":"text"},{"fieldName":" 标题 ","type":"number"}]`, + "config not object": `[{"fieldName":"标题","type":"text","config":[]}]`, } for name, raw := range cases { t.Run(name, func(t *testing.T) { @@ -104,6 +106,36 @@ func TestCrossPlatformCoverageTableBootstrapInputValidation(t *testing.T) { } } +func TestCrossPlatformCoverageTableBootstrapRejectsDuplicateFieldsBeforeMCP(t *testing.T) { + caller := &upsertByKeyCaller{} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", + "--fields", `[{"fieldName":"标题","type":"text"},{"fieldName":"标题","type":"number"}]`, "--yes") + if out != "" || err == nil || len(caller.calls) != 0 { + t.Fatalf("duplicate field validation = output:%q err:%v calls:%#v", out, err, caller.calls) + } +} + +func TestCrossPlatformCoverageTableBootstrapVerifiesTypeAndDeclaredConfig(t *testing.T) { + fields := []any{map[string]any{ + "fieldName": "状态", + "type": "singleSelect", + "config": map[string]any{ + "options": []any{map[string]any{"name": "待办"}}, + }, + }} + caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ + {text: `{"tableId":"table-new"}`}, + {text: `{"tables":[{"tableId":"table-new"}]}`}, + {text: `{"fields":[{"fieldId":"field-1","fieldName":"状态","fieldType":"singleSelect","config":{"options":[{"name":"待办","optionId":"option-1"}],"extra":true}}]}`}, + }} + out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", + "--base-id", "base", "--name", "任务", "--fields", mustJSON(t, fields), "--yes") + if err != nil || !strings.Contains(out, `"status": "verified"`) { + t.Fatalf("typed config verification = output:%q err:%v", out, err) + } +} + func TestCrossPlatformCoverageTableBootstrapDryRun(t *testing.T) { caller := &upsertByKeyCaller{dryRun: true} out, err := runAITableCompositeCLI(t, caller, "+table-bootstrap", @@ -127,6 +159,9 @@ func TestCrossPlatformCoverageTableBootstrapFailureStages(t *testing.T) { {name: "get fields error", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {err: errors.New("get fields failed")}}}, {name: "get fields missing collection", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{}`}}}, {name: "get fields mismatch", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{"fields":[]}`}}}, + {name: "get fields type mismatch", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{"fields":[{"fieldName":"F00","fieldType":"number"}]}`}}}, + {name: "get fields config mismatch", fields: []any{map[string]any{"fieldName": "状态", "type": "singleSelect", "config": map[string]any{"multiple": false}}}, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{"fields":[{"fieldName":"状态","fieldType":"singleSelect","config":{"multiple":true}}]}`}}}, + {name: "get fields duplicate name", fields: oneField, steps: []upsertByKeyStep{{text: `{"tableId":"table-new"}`}, {text: `{"tables":[{"tableId":"table-new"}]}`}, {text: `{"fields":[{"fieldName":"F00","fieldType":"text"},{"fieldName":"F00","fieldType":"text"}]}`}}}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { diff --git a/internal/shortcut/aitable/table_copy.go b/internal/shortcut/aitable/table_copy.go index 05df6c78..7046d2e5 100644 --- a/internal/shortcut/aitable/table_copy.go +++ b/internal/shortcut/aitable/table_copy.go @@ -136,10 +136,13 @@ func executeTableCopy(rt *shortcut.RuntimeContext) error { } targetFieldsData, err := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": targetBase, "tableId": targetTable}) targetFields, found := findNamedObjectList(targetFieldsData, "fields", "fieldList") - if err != nil || !found || !containsAllFieldNames(targetFields, createFields) { - if err == nil { - err = fmt.Errorf("target field read-back does not contain the copied field set") - } + if err == nil && !found { + err = fmt.Errorf("target field read-back is missing the fields collection") + } + if err == nil { + err = verifyDeclaredFieldStructures(targetFields, createFields) + } + if err != nil { result.Status = "partial_success" result.Checkpoint = map[string]any{"targetTableId": targetTable, "step": "repair target fields"} return compositeError(result, err, false) diff --git a/internal/shortcut/aitable/table_copy_coverage_gap_test.go b/internal/shortcut/aitable/table_copy_coverage_gap_test.go index c051befc..88b915c2 100644 --- a/internal/shortcut/aitable/table_copy_coverage_gap_test.go +++ b/internal/shortcut/aitable/table_copy_coverage_gap_test.go @@ -88,11 +88,16 @@ func TestCrossPlatformCoverageTableCopySchemaFailureStagesE2E(t *testing.T) { steps []upsertByKeyStep }{ {name: "target fields error", steps: []upsertByKeyStep{{text: source}, {text: `{"tableId":"target"}`}, {err: errors.New("target fields failed")}}}, + {name: "target fields missing collection", steps: []upsertByKeyStep{{text: source}, {text: `{"tableId":"target"}`}, {text: `{}`}}}, {name: "target fields mismatch", steps: []upsertByKeyStep{{text: source}, {text: `{"tableId":"target"}`}, {text: `{"fields":[]}`}}}, {name: "target mapping duplicate", steps: []upsertByKeyStep{ {text: source}, {text: `{"tableId":"target"}`}, {text: `{"fields":[{"fieldId":"t1","fieldName":"F0","type":"text"},{"fieldId":"t2","fieldName":"F0","type":"text"}]}`}, }}, + {name: "target mapping missing id", steps: []upsertByKeyStep{ + {text: source}, {text: `{"tableId":"target"}`}, + {text: `{"fields":[{"fieldName":"F0","type":"text"}]}`}, + }}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { From c53e1f465d5c31748861ccd9b37cc542ea09fcda Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 18 Aug 2026 17:23:33 +0800 Subject: [PATCH 221/250] ci: retain legacy Drive tree helper to #85349380 --- skills/content-qa/mono-multi-coverage.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/skills/content-qa/mono-multi-coverage.yaml b/skills/content-qa/mono-multi-coverage.yaml index 440c149e..5a1e458f 100644 --- a/skills/content-qa/mono-multi-coverage.yaml +++ b/skills/content-qa/mono-multi-coverage.yaml @@ -170,6 +170,9 @@ orphan_scripts_allowlist: - path: dingtalk-aitable/scripts/aitable_import_via_task.py disposition: defer reason: "helper referenced indirectly / pending doc" + - path: dingtalk-drive/scripts/drive_tree_list.py + disposition: defer + reason: "legacy helper retained for compatibility; multi Drive uses bounded +list until the helper is revalidated" - path: dingtalk-minutes/scripts/minutes_list_parse.py disposition: defer reason: "pending doc reference" From f290a2101e8d8bf15a082f0fa502a760d6ac10e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=AD=E9=80=B8?= Date: Tue, 18 Aug 2026 19:06:01 +0800 Subject: [PATCH 222/250] fix drive.md to #666 --- skills/multi/dingtalk-drive/references/drive.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/skills/multi/dingtalk-drive/references/drive.md b/skills/multi/dingtalk-drive/references/drive.md index 61d7aecc..113beb05 100644 --- a/skills/multi/dingtalk-drive/references/drive.md +++ b/skills/multi/dingtalk-drive/references/drive.md @@ -91,3 +91,7 @@ dws drive +publish-unset --node 2. 分页、递归或过滤未完成时保留 cursor/truncated/errors，不包装成全量成功。 3. 写入超时或响应丢失先按 nodeId、名称、路径和大小回读，不能盲目重放。 4. 在线文档误入普通下载/覆盖时切 Doc、Sheet 或 AITable；不要用 Drive 重试改变内容。 + +## 辅助脚本 + +- [drive_tree_list.py](../scripts/drive_tree_list.py)：递归列出钉盘目录树；普通浏览仍优先使用 `dws drive +list`。 From 9fb61f8e99d5ffb3a58bce19807c238c4b43ff4f Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 23:31:07 +0800 Subject: [PATCH 223/250] feat: migrate aisearch query primary to #85349380 --- internal/helpers/aisearch.go | 78 +++++++++++++++++++------------ internal/helpers/aisearch_test.go | 66 +++++++++++++++++++++++++- 2 files changed, 111 insertions(+), 33 deletions(-) diff --git a/internal/helpers/aisearch.go b/internal/helpers/aisearch.go index 00e11a35..92cbe0a6 100644 --- a/internal/helpers/aisearch.go +++ b/internal/helpers/aisearch.go @@ -3,18 +3,21 @@ package helpers import ( "strings" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/spf13/cobra" - - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) // boolPtr returns a pointer to v, for ParamDecl.Required declarations. func boolPtr(v bool) *bool { return &v } -// aisearchKeywordAliases 是 --keyword flag 的同义瞎猜兜底列表。 -// 模型可能写 --name / --q / --query / --text，这些都被识别为 keyword。 -var aisearchKeywordAliases = []string{"name", "q", "query", "text"} +// 这些是原有的宽松兜底名，不属于本次 Primary 迁移；保持原生 hidden +// 注册，不给它们新增 alias_of/origin 元数据。 +var aisearchPersonGuessFlags = []string{"name", "q", "text"} + +// 历史解析优先级必须独立于新旧 Primary：双传时旧 --keyword 始终获胜。 +var aisearchQueryResolutionOrder = []string{"keyword", "name", "q", "query", "text"} // flagValue 安全地读取 flag 值：先查 local，再查自身 PersistentFlags， // 再查 parents 的 PersistentFlags。比 cmd.Flags().GetString 更鲁棒， @@ -58,14 +61,11 @@ func aisearchFlagOrDefault(cmd *cobra.Command, primary, def string, aliases ...s return def } -// resolveAisearchKeyword 从命令的 flag 中解析 keyword：优先 --keyword， -// 否则 fallback 到 aisearchKeywordAliases 中的任一同义 flag。 +// resolveAisearchKeyword 按历史顺序解析人员搜索词。虽然公开 Primary 已改为 +// --query，但兼容期内显式旧 --keyword 的值仍优先。 func resolveAisearchKeyword(cmd *cobra.Command) string { - if v := flagValue(cmd, "keyword"); v != "" { - return v - } - for _, alias := range aisearchKeywordAliases { - if v := flagValue(cmd, alias); v != "" { + for _, name := range aisearchQueryResolutionOrder { + if v := flagValue(cmd, name); v != "" { return v } } @@ -73,9 +73,23 @@ func resolveAisearchKeyword(cmd *cobra.Command) string { } func addAisearchPersonFlags(cmd *cobra.Command) { - cmd.Flags().StringP("keyword", "w", "", "搜索关键词 (必填，如人名、技能关键词等)") + // Alias evidence must be emitted by corecmd.FlagSpec.Aliases. Build the pair + // on a temporary declaration command so the legacy alias can retain its + // historical -w shorthand without extending the global alias mechanism or + // assigning that shorthand to the new --query Primary. + declaration := &cobra.Command{Use: "aisearch-query-flags"} + corecmd.RegisterFlags(declaration, []corecmd.FlagSpec{{ + Name: "query", + Usage: "搜索关键词 (必填，如人名、技能关键词等)", + Aliases: []string{"keyword"}, + }}) + queryFlag := declaration.Flags().Lookup("query") + keywordFlag := declaration.Flags().Lookup("keyword") + keywordFlag.Shorthand = "w" + cmd.Flags().AddFlag(queryFlag) + cmd.Flags().AddFlag(keywordFlag) cmd.Flags().StringP("dimension", "d", "all", "查询维度: all/name/department/position/duty/supervisor/subordinate/phone/jobNumber，多个用逗号分隔") - for _, alias := range aisearchKeywordAliases { + for _, alias := range aisearchPersonGuessFlags { cmd.Flags().String(alias, "", "") _ = cmd.Flags().MarkHidden(alias) } @@ -98,8 +112,7 @@ func runAisearchPerson(cmd *cobra.Command, _ []string) error { } keyword := resolveAisearchKeyword(cmd) if keyword == "" { - // 复用原有报错文案（"keyword is required"） - return validateRequiredFlags(cmd, "keyword") + return validateRequiredFlags(cmd, "query") } dimensions := parseDimensions(flagValue(cmd, "dimension")) return callMCPTool("enterprise_person_search", map[string]any{ @@ -188,8 +201,8 @@ func newAisearchCommand() *cobra.Command { Use: "aisearch", Short: "AI 搜问", Long: `AI 搜问：搜索企业人员信息、企业内部知识内容与企业内部行为记录。`, - // 智能 root：模型常漏 person 子命令直接 dws aisearch --keyword xxx， - // 检测到 keyword 就自动等价于 person；否则退回 group help。 + // 智能 root：模型常漏 person 子命令直接 dws aisearch --query xxx， + // 检测到 query 就自动等价于 person；否则退回 group help。 RunE: func(cmd *cobra.Command, args []string) error { if resolveAisearchKeyword(cmd) != "" { return runAisearchPerson(cmd, args) @@ -199,9 +212,9 @@ func newAisearchCommand() *cobra.Command { } // root 和 person 各自定义同一组本地 flag，这样： - // - dws aisearch --keyword xxx ← root 自己能解析 - // - dws aisearch person --keyword xxx ← person 本地 flag - // - dws aisearch search --keyword xxx ← search 是 person 的 alias + // - dws aisearch --query xxx ← root 自己能解析 + // - dws aisearch person --query xxx ← person 本地 flag + // - dws aisearch search --query xxx ← search 是 person 的 alias // 不能放在 product PersistentFlags：否则 enterprise/behavior 会公开接受 // 它们不拥有的 person-only dimension，破坏 Help ↔ Schema 完整性。 addAisearchPersonFlags(root) @@ -219,7 +232,7 @@ func newAisearchCommand() *cobra.Command { "query", "people", "ask", "find", "lookup", "contact", }, - // 显式声明允许任意位置参数：模型可能写 dws aisearch person search --keyword xxx， + // 显式声明允许任意位置参数：模型可能写 dws aisearch person search --query xxx， // 此时 "search" 会作为 positional arg 被忽略，不报错。 Args: cobra.ArbitraryArgs, Short: "搜索企业人员", @@ -237,13 +250,13 @@ func newAisearchCommand() *cobra.Command { jobNumber 工号 多个维度用逗号分隔。`, - Example: ` dws aisearch person --keyword "张三" --dimension department - dws aisearch person --keyword "产品部" --dimension department - dws aisearch person --keyword "五道" --dimension supervisor - dws aisearch person --keyword "AI搜问" --dimension duty - dws aisearch person --keyword "李四" --dimension name,department - dws aisearch person --keyword "13800138000" --dimension phone - dws aisearch person --keyword "W12345" --dimension jobNumber`, + Example: ` dws aisearch person --query "张三" --dimension department + dws aisearch person --query "产品部" --dimension department + dws aisearch person --query "五道" --dimension supervisor + dws aisearch person --query "AI搜问" --dimension duty + dws aisearch person --query "李四" --dimension name,department + dws aisearch person --query "13800138000" --dimension phone + dws aisearch person --query "W12345" --dimension jobNumber`, RunE: runAisearchPerson, } DeclareLeafMetadata(personCmd, LeafSpec{ @@ -277,10 +290,13 @@ func newAisearchCommand() *cobra.Command { "搜企业知识内容时用 aisearch enterprise；搜行为记录时用 aisearch behavior", }, Examples: []string{ - "dws aisearch person --keyword \"张三\" --dimension name --format json", - "dws aisearch person --keyword \"五道\" --dimension supervisor --format json", + "dws aisearch person --query \"张三\" --dimension name --format json", + "dws aisearch person --query \"五道\" --dimension supervisor --format json", }, }, + Parameters: []contract.ParamDecl{ + {Name: "query", Property: "keyword", Required: boolPtr(true)}, + }, }, }) addAisearchPersonFlags(personCmd) diff --git a/internal/helpers/aisearch_test.go b/internal/helpers/aisearch_test.go index 44c07205..e7303d15 100644 --- a/internal/helpers/aisearch_test.go +++ b/internal/helpers/aisearch_test.go @@ -4,7 +4,12 @@ package helpers -import "testing" +import ( + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" +) func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) { root := newAisearchCommand() @@ -12,12 +17,34 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) { if err != nil { t.Fatal(err) } - for _, name := range []string{"keyword", "dimension"} { + for _, name := range []string{"query", "dimension"} { flag := person.Flags().Lookup(name) if flag == nil || flag.Hidden { t.Fatalf("person --%s = %#v, want visible local flag", name, flag) } } + if person.Flags().Lookup("query").Shorthand != "" { + t.Fatal("new Primary --query must not acquire a shorthand") + } + keyword := person.Flags().Lookup("keyword") + if keyword == nil || !keyword.Hidden || keyword.Shorthand != "w" { + t.Fatalf("person --keyword = %#v, want hidden legacy flag with -w", keyword) + } + if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "query" { + t.Fatalf("person --keyword alias_of = %#v, want query", got) + } + if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("person --keyword alias_origin = %#v, want %q", got, runtimeannotate.FlagAliasOriginCorecmdV1) + } + for _, name := range []string{"name", "q", "text"} { + flag := person.Flags().Lookup(name) + if flag == nil || !flag.Hidden { + t.Fatalf("person --%s = %#v, want preserved hidden guess flag", name, flag) + } + if got := flag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 0 { + t.Fatalf("person --%s unexpectedly gained alias_of metadata: %#v", name, got) + } + } for _, path := range []string{"enterprise", "behavior"} { cmd, _, err := root.Find([]string{path}) @@ -35,3 +62,38 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) { } } } + +func TestAisearchPersonQueryPrimaryCompatibility(t *testing.T) { + tests := []struct { + name string + args []string + want string + }{ + {name: "root new", args: []string{"--query", "new"}, want: "new"}, + {name: "root old", args: []string{"--keyword", "old"}, want: "old"}, + {name: "root old shorthand", args: []string{"-w", "old-short"}, want: "old-short"}, + {name: "root both old wins", args: []string{"--query", "new", "--keyword", "old"}, want: "old"}, + {name: "person new", args: []string{"person", "--query", "new"}, want: "new"}, + {name: "person old", args: []string{"person", "--keyword", "old"}, want: "old"}, + {name: "person old shorthand", args: []string{"person", "-w", "old-short"}, want: "old-short"}, + {name: "person both old wins", args: []string{"person", "--query", "new", "--keyword", "old"}, want: "old"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + caller := &scriptedToolCaller{} + installScriptedCaller(t, caller) + if err := executeFilterCoverage(t, newAisearchCommand(), tc.args...); err != nil { + t.Fatal(err) + } + if caller.tool != "enterprise_person_search" || caller.args["keyword"] != tc.want { + t.Fatalf("call = %s %#v, want backend keyword %q", caller.tool, caller.args, tc.want) + } + }) + } + + installScriptedCaller(t, &scriptedToolCaller{}) + err := executeFilterCoverage(t, newAisearchCommand(), "person") + if err == nil || !strings.Contains(err.Error(), "--query") || strings.Contains(err.Error(), "--keyword") { + t.Fatalf("missing query error = %v, want only new Primary", err) + } +} From 7fbe7593c8bfb27c50211f85426476c08a4030af Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 23:31:35 +0800 Subject: [PATCH 224/250] feat: migrate chat primary parameters to #85349380 --- internal/helpers/chat.go | 165 +++++---- internal/helpers/chat_media_upload.go | 10 +- .../chat_media_upload_coverage_more_test.go | 2 +- internal/helpers/connect_stream.go | 2 +- internal/shortcut/chat/chat_message.go | 20 +- internal/shortcut/chat/lark_alignment.go | 18 +- .../chat/primary_param_migration_test.go | 327 ++++++++++++++++++ internal/shortcut/chat/schema_contracts.go | 42 ++- internal/shortcut/smart/broadcast.go | 11 +- internal/shortcut/smart/dm.go | 11 +- .../shortcut/smart/primary_param_contract.go | 28 ++ internal/shortcut/smart/send_to_group.go | 11 +- 12 files changed, 542 insertions(+), 105 deletions(-) create mode 100644 internal/shortcut/chat/primary_param_migration_test.go create mode 100644 internal/shortcut/smart/primary_param_contract.go diff --git a/internal/helpers/chat.go b/internal/helpers/chat.go index b2cbdf17..af6b16b1 100644 --- a/internal/helpers/chat.go +++ b/internal/helpers/chat.go @@ -19,15 +19,29 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" - - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) +// promoteLegacyChatString copies an explicitly supplied legacy flag into the +// new canonical flag. Cobra validates MarkFlagRequired after PreRunE, and the +// overwrite also preserves the migration rule that a legacy value wins when +// both spellings are present. +func promoteLegacyChatString(cmd *cobra.Command, canonical, legacy string) error { + if !cmd.Flags().Changed(legacy) { + return nil + } + value, err := cmd.Flags().GetString(legacy) + if err != nil { + return err + } + return cmd.Flags().Set(canonical, value) +} + func callProjectedChatMessages(cmd *cobra.Command, toolName string, args map[string]any, search bool) error { if deps.Caller.DryRun() { return callMCPToolOnServer("chat", toolName, args) @@ -3144,7 +3158,7 @@ func newChatCommand() *cobra.Command { --open-dingtalk-id 单聊接收人 openDingTalkId 纯文本 / Markdown 消息（默认）： - 无需指定 --msg-type，直接传消息内容即可。推荐使用 --text flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。 + 无需指定 --msg-type，直接传消息内容即可。推荐使用 --content flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。 图文混排时，公网图片 URL 需要写成 Markdown 图片语法：![图片标题](https://example.com/image.png)，才会以内联图片展示。 如果省略开头的 !，例如 [图片标题](https://example.com/image.png)，将按链接/URL 展示，不会渲染为图片。 @@ -3154,24 +3168,24 @@ func newChatCommand() *cobra.Command { 获取 openMessageId 和 openConversationId，无需再按消息内容反查。 本地图片 / 文件消息： - 统一使用 --msg-type file --file-path <本地路径>。CLI 会完成上传并按 file 消息发送； + 统一使用 --msg-type file --file <本地路径>。CLI 会完成上传并按 file 消息发送； .png/.jpg 也会显示为可下载的文件附件，不会生成 mediaId 或渲染成内联图片。 旧版内联图片消息： 仅当上游已经提供有效 mediaId 时，使用 --msg-type image --media-id。 当前 CLI 不提供本地文件到 mediaId 的上传能力。`, - Example: ` dws chat message send --conversation-id "hello" - dws chat message send --user "请查收" - dws chat message send --open-dingtalk-id "请查收" - dws chat message send --conversation-id --title "周报提醒" "请大家本周五前提交周报" + Example: ` dws chat message send --conversation-id --content "hello" + dws chat message send --user --content "请查收" + dws chat message send --open-dingtalk-id --content "请查收" + dws chat message send --conversation-id --title "周报提醒" --content "请大家本周五前提交周报" # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示 - dws chat message send --conversation-id --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' + dws chat message send --conversation-id --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' # 发送本地图片或文件（图片会作为可下载的 file 附件发送） - dws chat message send --conversation-id --msg-type file --file-path ./screenshot.png - dws chat message send --conversation-id --msg-type file --file-path ./report.pdf + dws chat message send --conversation-id --msg-type file --file ./screenshot.png + dws chat message send --conversation-id --msg-type file --file ./report.pdf # 发送本地音频/视频（audio/video 是 file 的语义别名） - dws chat message send --conversation-id --msg-type audio --file-path ./recording.mp3 - dws chat message send --conversation-id --msg-type video --file-path ./demo.mp4 + dws chat message send --conversation-id --msg-type audio --file ./recording.mp3 + dws chat message send --conversation-id --msg-type video --file ./demo.mp4 # 旧版内联图片：仅当上游已经持有有效 mediaId 时使用 dws chat message send --conversation-id --msg-type image --media-id # 查询群 ID: dws chat search --query "群名" @@ -3250,7 +3264,7 @@ func newChatCommand() *cobra.Command { contentJSON = fmt.Sprintf(`{"mediaId":"%s"}`, mediaId) case "file", "audio", "video": serviceMsgType = "file" - filePath, _ := cmd.Flags().GetString("file-path") + filePath := flagOrFallback(cmd, "file-path", "file") dentryId, _ := cmd.Flags().GetInt64("dentry-id") spaceId, _ := cmd.Flags().GetInt64("space-id") if (dentryId == 0) != (spaceId == 0) { @@ -3281,7 +3295,7 @@ func newChatCommand() *cobra.Command { } contentJSON, _ = buildConversationFileContent(dentryId, spaceId, meta) } else if dentryId == 0 || spaceId == 0 { - return fmt.Errorf("--file-path must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err) + return fmt.Errorf("--file must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err) } } if contentJSON == "" { @@ -3289,7 +3303,7 @@ func newChatCommand() *cobra.Command { fileType, _ := cmd.Flags().GetString("file-type") fileSize, _ := cmd.Flags().GetInt64("file-size") if dentryId == 0 || spaceId == 0 || fileName == "" { - return fmt.Errorf("readable local --file-path is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported") + return fmt.Errorf("readable local --file is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported") } contentJSON = fmt.Sprintf(`{"dentryId":%d,"spaceId":%d,"fileName":"%s","fileType":"%s","filePath":"%s","fileSize":%d}`, dentryId, spaceId, fileName, fileType, filePath, fileSize) @@ -3335,7 +3349,7 @@ func newChatCommand() *cobra.Command { text = args[0] } if text == "" { - return fmt.Errorf("message content required (use --text or positional arg, or --media-id for image)") + return fmt.Errorf("message content required (use --content or positional arg, or --media-id for image)") } title, _ := cmd.Flags().GetString("title") if title == "" { @@ -3395,7 +3409,7 @@ func newChatCommand() *cobra.Command { AgentSummary: "以当前用户身份发送群聊或单聊消息", UseWhen: []string{"用户明确要以个人身份发送文本或媒体消息时；响应返回 openTaskId 后用 chat message query-send-status 确认投递并取得后续操作所需的消息 ID"}, AvoidWhen: []string{"机器人身份或 Webhook 发送应使用对应命令"}, - Examples: []string{"dws chat message send --group \"项目已更新\""}, + Examples: []string{"dws chat message send --group --content \"项目已更新\""}, }, Parameters: []contract.ParamDecl{ {Name: "ai-tag", Property: "clawType", InterfaceType: "string"}, @@ -3716,19 +3730,25 @@ func newChatCommand() *cobra.Command { chatMessageSendByWebhookCmd := &cobra.Command{ Use: "send-by-webhook", Short: "自定义机器人 Webhook 发送群消息", - Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --text 中包含 @userId 或 @手机号，否则 @ 不生效。 + Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --content 中包含 @userId 或 @手机号，否则 @ 不生效。 ⚠️ 重要：该接口会真实发送消息到目标群聊，不可用于测试或试探性调用。调用前必须确认消息内容无误。`, - Example: ` dws chat message send-by-webhook --token --title "告警" --text "CPU 超 90%" --at-all - dws chat message send-by-webhook --token --title "test" --text "hi @118785" --at-users 118785`, + Example: ` dws chat message send-by-webhook --token --title "告警" --content "CPU 超 90%" --at-all + dws chat message send-by-webhook --token --title "test" --content "hi @118785" --at-users 118785`, + PreRunE: func(cmd *cobra.Command, args []string) error { + return promoteLegacyChatString(cmd, "content", "text") + }, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "token", "title", "text"); err != nil { + if err := promoteLegacyChatString(cmd, "content", "text"); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "token", "title", "content"); err != nil { return err } toolArgs := map[string]any{ "robotToken": mustGetFlag(cmd, "token"), "title": mustGetFlag(cmd, "title"), - "text": mustGetFlag(cmd, "text"), + "text": mustGetFlag(cmd, "content"), } if v, _ := cmd.Flags().GetBool("at-all"); v { toolArgs["isAtAll"] = true @@ -3803,11 +3823,12 @@ func newChatCommand() *cobra.Command { "使用企业机器人 robot-code 发消息时用 chat message send-by-bot", "以个人身份发消息时用 chat message send", }, - Examples: []string{"dws chat message send-by-webhook --token --title \"告警\" --text \"CPU 超 90%\" --at-all"}, + Examples: []string{"dws chat message send-by-webhook --token --title \"告警\" --content \"CPU 超 90%\" --at-all"}, }, Parameters: []contract.ParamDecl{ {Name: "at-all", Property: "isAtAll"}, {Name: "at-users", Property: "atUserIds"}, + {Name: "content", Property: "text"}, {Name: "token", Property: "robotToken"}, }, }, @@ -4356,7 +4377,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Example: ` dws chat message recall --conversation-id --message-id # 发送后撤回：send -> query-send-status -> recall - dws chat message send --conversation-id --text "待撤回的内容" + dws chat message send --conversation-id --content "待撤回的内容" dws chat message query-send-status --open-task-id <上一步返回的openTaskId> dws chat message recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>`, RunE: func(cmd *cobra.Command, args []string) error { @@ -4417,7 +4438,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Example: ` dws chat message edit --conversation-id --message-id --text "更新后的内容" # 发送后编辑：send -> query-send-status -> edit - dws chat message send --conversation-id --text "原始内容" + dws chat message send --conversation-id --content "原始内容" dws chat message query-send-status --open-task-id <上一步返回的openTaskId> dws chat message edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId> --text "更新后的内容" @@ -4753,21 +4774,19 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendCmd.Flags().String("user", "", "单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一）") chatMessageSendCmd.Flags().String("open-dingtalk-id", "", "单聊接收人 openDingTalkId（单聊时与 --user 二选一）") chatMessageSendCmd.Flags().String("title", "", "消息标题，显示在消息列表（可选，未指定时使用消息内容）") - // 别名注册: --text/--content/--body/--message/--markdown → 位置参数 - chatMessageSendCmd.Flags().String("text", "", "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）") - chatMessageSendCmd.Flags().String("content", "", "--text 的别名") - chatMessageSendCmd.Flags().String("body", "", "--text 的别名") - chatMessageSendCmd.Flags().String("message", "", "--text 的别名") - chatMessageSendCmd.Flags().String("markdown", "", "--text 的别名") - // --text 不再隐藏，作为首选传参方式展示在 help 中 - _ = chatMessageSendCmd.Flags().MarkHidden("content") - _ = chatMessageSendCmd.Flags().MarkHidden("body") - _ = chatMessageSendCmd.Flags().MarkHidden("message") - _ = chatMessageSendCmd.Flags().MarkHidden("markdown") + corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{ + Name: "content", + Usage: "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）", + Aliases: []string{"text"}, + }}) + for _, alias := range []string{"body", "message", "markdown"} { + chatMessageSendCmd.Flags().String(alias, "", "--content 的兼容别名") + _ = chatMessageSendCmd.Flags().MarkHidden(alias) + } chatMessageSendCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效，可选）,设置时，消息内容中一定要包含对应的占位符<@all>") chatMessageSendCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingTalkId 列表，逗号分隔（仅群聊时生效，可选）,设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时，消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2>") chatMessageSendCmd.Flags().String("media-id", "", "上游已提供的图片 mediaId（仅旧版 msgType=image；CLI 不提供本地上传到 mediaId）") - chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file-path；image 仅接受已有 mediaId）") + chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file；image 仅接受已有 mediaId）") chatMessageSendCmd.Flags().String("latitude", "", "位置消息纬度（msgType=location 时必填）") chatMessageSendCmd.Flags().String("longitude", "", "位置消息经度（msgType=location 时必填）") chatMessageSendCmd.Flags().String("location-name", "", "位置消息地址名称（msgType=location 时必填）") @@ -4777,7 +4796,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id chatMessageSendCmd.Flags().Int64("space-id", 0, "空间 ID（与 --dentry-id 成对传入时跳过自动上传）") chatMessageSendCmd.Flags().String("file-name", "", "文件名") chatMessageSendCmd.Flags().String("file-type", "", "文件类型/扩展名") - chatMessageSendCmd.Flags().String("file-path", "", "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）") + corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{ + Name: "file", + Usage: "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）", + Aliases: []string{"file-path"}, + }}) chatMessageSendCmd.Flags().Int64("file-size", 0, "文件大小，单位字节") _ = chatMessageSendCmd.Flags().MarkHidden("dentry-id") _ = chatMessageSendCmd.Flags().MarkHidden("space-id") @@ -4798,12 +4821,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id cli.AnnotateRuntimePositionals(chatMessageSendCmd, contract.RuntimeSchemaPositional{ Name: "content", Type: "string", - Description: "消息内容（也可使用 --text；富媒体消息可省略）", + Description: "消息内容（也可使用 --content；富媒体消息可省略）", Required: false, Index: 0, }) cli.AnnotateRuntimeFlagEnum(chatMessageSendCmd, "msg-type", "image", "file", "audio", "video") - cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file-path", "file-path") + cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file", "file-path") chatMessageSendByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)") _ = chatMessageSendByBotCmd.MarkFlagRequired("robot-code") @@ -4838,8 +4861,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id _ = chatMessageSendByWebhookCmd.MarkFlagRequired("token") chatMessageSendByWebhookCmd.Flags().String("title", "", "消息标题 (必填)") _ = chatMessageSendByWebhookCmd.MarkFlagRequired("title") - chatMessageSendByWebhookCmd.Flags().String("text", "", "消息内容 (必填)") - _ = chatMessageSendByWebhookCmd.MarkFlagRequired("text") + corecmd.RegisterFlags(chatMessageSendByWebhookCmd, []corecmd.FlagSpec{{ + Name: "content", + Usage: "消息内容 (必填)", + Aliases: []string{"text"}, + }}) + _ = chatMessageSendByWebhookCmd.MarkFlagRequired("content") chatMessageSendByWebhookCmd.Flags().Bool("at-all", false, "@ 所有人") chatMessageSendByWebhookCmd.Flags().String("at-mobiles", "", "@ 指定手机号，逗号分隔") chatMessageSendByWebhookCmd.Flags().String("at-users", "", "@ 指定用户，逗号分隔") @@ -5049,7 +5076,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Use: "conversation-info", Short: "获取会话基础信息", Long: `获取指定会话的基础信息。 -发送本地文件消息请优先使用 dws chat message send --msg-type file --file-path <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`, +发送本地文件消息请优先使用 dws chat message send --msg-type file --file <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`, Example: ` dws chat conversation-info --conversation-id --format json dws chat conversation-info --user --format json dws chat conversation-info --open-dingtalk-id --format json`, @@ -5164,11 +5191,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id Hidden: true, Long: `chat file upload 已下线，不再调用 chat/upload_conversation_file_by_url。 -发送本地文件消息请改用 chat message send --msg-type file --file-path；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`, - Example: ` dws chat message send --conversation-id --msg-type file --file-path ./report.pdf --format json - dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf --format json`, +发送本地文件消息请改用 chat message send --msg-type file --file；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`, + Example: ` dws chat message send --conversation-id --msg-type file --file ./report.pdf --format json + dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json`, RunE: func(cmd *cobra.Command, args []string) error { - return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file-path <本地路径>") + return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file <本地路径>") }, } chatFileUploadCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时使用）") @@ -6934,10 +6961,22 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 - 群聊：dws chat search --query "群名" - 单聊：dws chat conversation-info --open-dingtalk-id （人员信息可通过 dws contact user search --keyword "姓名" --format json 获取）`, - Example: ` dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "收到，马上处理" - dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "请看一下" --at-open-dingtalk-ids `, + Example: ` dws chat message reply --group --ref-msg-id --ref-sender --content "收到，马上处理" + dws chat message reply --group --ref-msg-id --ref-sender --content "请看一下" --at-open-dingtalk-ids `, + PreRunE: func(cmd *cobra.Command, args []string) error { + if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil { + return err + } + return promoteLegacyChatString(cmd, "content", "text") + }, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "conversation-id", "ref-msg-id", "ref-sender", "text"); err != nil { + if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil { + return err + } + if err := promoteLegacyChatString(cmd, "content", "text"); err != nil { + return err + } + if err := validateRequiredFlags(cmd, "group", "ref-msg-id", "ref-sender", "content"); err != nil { return err } refSender := mustGetFlag(cmd, "ref-sender") @@ -6954,7 +6993,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 clawType = edition.ClawType() } toolArgs := map[string]any{ - "openConversationId": mustGetFlag(cmd, "conversation-id"), + "openConversationId": mustGetFlag(cmd, "group"), "msgType": "reply", "clawType": clawType, } @@ -6962,7 +7001,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 atOpenIDs := mustGetFlag(cmd, "at-open-dingtalk-ids") replyText := applyCurrentUserGroupMentions( toolArgs, - mustGetFlag(cmd, "text"), + mustGetFlag(cmd, "content"), atOpenIDs, atAll, ) @@ -7004,24 +7043,32 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成 AgentSummary: "引用指定消息发送个人回复", UseWhen: []string{"用户要针对某条已有消息进行引用回复时"}, AvoidWhen: []string{"无需引用上下文的普通消息使用 chat message send"}, - Examples: []string{"dws chat message reply --conversation-id --ref-msg-id --ref-sender --text \"收到\""}, + Examples: []string{"dws chat message reply --group --ref-msg-id --ref-sender --content \"收到\""}, }, Parameters: []contract.ParamDecl{ {Name: "ai-tag", Property: "clawType", InterfaceType: "string"}, {Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"}, {Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds", Required: boolPtr(false), InterfaceType: "array"}, - {Name: "conversation-id", Property: "openConversationId"}, + {Name: "group", Property: "openConversationId"}, }, }, }) - chatMessageReplyCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填，支持单聊/群聊)") - _ = chatMessageReplyCmd.MarkFlagRequired("conversation-id") + corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{ + Name: "group", + Usage: "会话 openConversationId (必填，支持单聊/群聊)", + Aliases: []string{"conversation-id"}, + }}) + _ = chatMessageReplyCmd.MarkFlagRequired("group") chatMessageReplyCmd.Flags().String("ref-msg-id", "", "被引用的消息 openMessageId (必填)") _ = chatMessageReplyCmd.MarkFlagRequired("ref-msg-id") chatMessageReplyCmd.Flags().String("ref-sender", "", "被引用消息的发送者 openDingTalkId (必填)") _ = chatMessageReplyCmd.MarkFlagRequired("ref-sender") - chatMessageReplyCmd.Flags().String("text", "", "回复内容 (必填)") - _ = chatMessageReplyCmd.MarkFlagRequired("text") + corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{ + Name: "content", + Usage: "回复内容 (必填)", + Aliases: []string{"text"}, + }}) + _ = chatMessageReplyCmd.MarkFlagRequired("content") chatMessageReplyCmd.Flags().String("uuid", "", "幂等键（可选）") chatMessageReplyCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）") chatMessageReplyCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效；正文缺少 <@all> 时自动补齐）") diff --git a/internal/helpers/chat_media_upload.go b/internal/helpers/chat_media_upload.go index 80e26cc9..5bd34c26 100644 --- a/internal/helpers/chat_media_upload.go +++ b/internal/helpers/chat_media_upload.go @@ -18,7 +18,7 @@ import ( "github.com/spf13/cobra" ) -const chatMediaUploadReplacement = "dws chat message send --msg-type file --file-path <本地路径>" +const chatMediaUploadReplacement = "dws chat message send --msg-type file --file <本地路径>" func newChatMediaGroup() *cobra.Command { media := &cobra.Command{ @@ -43,11 +43,11 @@ func newChatMediaUploadCommand() *cobra.Command { Deprecated: "请改用 " + chatMediaUploadReplacement, Long: `此命令仅为 1.x 命令行兼容保留，不再读取应用凭证或调用旧版媒体上传接口。 -发送本地图片或文件时，请使用 chat message send --msg-type file --file-path。 +发送本地图片或文件时，请使用 chat message send --msg-type file --file。 该路径会把图片作为可下载的 file 消息发送，不会生成 mediaId，也不会渲染成内联 image 消息。 如果上游已经提供 mediaId，仍可使用 chat message send --msg-type image --media-id。`, - Example: " dws chat message send --group --msg-type file --file-path ./screenshot.png\n" + - " dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf", + Example: " dws chat message send --group --msg-type file --file ./screenshot.png\n" + + " dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf", Args: cobra.NoArgs, DisableAutoGenTag: true, RunE: func(*cobra.Command, []string) error { @@ -56,7 +56,7 @@ func newChatMediaUploadCommand() *cobra.Command { } // Keep the historical flags so existing argv remains parseable while the // 1.x compatibility command returns an actionable migration error. - cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file-path") + cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file") cmd.Flags().String("type", "image", "旧版兼容参数；不再执行媒体上传") return cmd } diff --git a/internal/helpers/chat_media_upload_coverage_more_test.go b/internal/helpers/chat_media_upload_coverage_more_test.go index 298fcbc6..8a057b16 100644 --- a/internal/helpers/chat_media_upload_coverage_more_test.go +++ b/internal/helpers/chat_media_upload_coverage_more_test.go @@ -28,7 +28,7 @@ func TestCrossPlatformCoverageChatMediaUploadIsDeprecatedCompatibilityStub(t *te if err == nil { t.Fatal("deprecated media upload returned nil error") } - for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file-path", "--media-id"} { + for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file", "--media-id"} { if !strings.Contains(err.Error(), want) { t.Fatalf("media upload migration error missing %q: %v", want, err) } diff --git a/internal/helpers/connect_stream.go b/internal/helpers/connect_stream.go index 5a4da321..2b3a61ae 100644 --- a/internal/helpers/connect_stream.go +++ b/internal/helpers/connect_stream.go @@ -1259,7 +1259,7 @@ func runStreamConnector(ctx context.Context, channel, clientID, clientSecret str } // Structured-text fallback: DingTalk leaves data.Text.Content blank on // markdown / richText callbacks (the body ships in data.Content). Without - // this, `dws chat message send --group ... --text ...` — which defaults + // this, `dws chat message send --group ... --content ...` — which defaults // to msgType=markdown — hits the drop branch below and the bot looks // dead to the sender. if text == "" { diff --git a/internal/shortcut/chat/chat_message.go b/internal/shortcut/chat/chat_message.go index 974f29d3..6f4d53f0 100644 --- a/internal/shortcut/chat/chat_message.go +++ b/internal/shortcut/chat/chat_message.go @@ -49,12 +49,12 @@ var MessagesSendByBot = shortcut.Shortcut{ {Name: "robot-code", Type: shortcut.FlagString, Desc: "机器人 Code", Required: true}, {Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId", Required: true}, {Name: "title", Type: shortcut.FlagString, Desc: "消息标题", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "Markdown 正文", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "Markdown 正文", Required: true, Aliases: []string{"text"}}, {Name: "at-user-ids", Type: shortcut.FlagStringSlice, Desc: "@ 的 userId 列表"}, {Name: "at-open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "@ 的 openDingTalkId 列表"}, {Name: "at-all", Type: shortcut.FlagBool, Desc: "@ 所有人"}, }, - Tips: []string{`dws chat +messages-send-by-bot --robot-code --group --title "日报" --text "## 今日完成"`}, + Tips: []string{`dws chat +messages-send-by-bot --robot-code --group --title "日报" --content "## 今日完成"`}, Execute: func(rt *shortcut.RuntimeContext) error { if err := validateExplicitOpenIDs("--at-open-dingtalk-ids", rt.StrSlice("at-open-dingtalk-ids")); err != nil { return err @@ -63,7 +63,7 @@ var MessagesSendByBot = shortcut.Shortcut{ "robotCode": rt.Str("robot-code"), "openConversationId": rt.Str("group"), "title": rt.Str("title"), - "markdown": rt.Str("text"), + "markdown": rt.StrFirst("text", "content"), } if v := rt.StrSlice("at-user-ids"); len(v) > 0 { params["atUserIds"] = v @@ -90,12 +90,12 @@ var MessagesBatchSendByBot = shortcut.Shortcut{ Flags: []shortcut.Flag{ {Name: "robot-code", Type: shortcut.FlagString, Desc: "机器人 Code", Required: true}, {Name: "title", Type: shortcut.FlagString, Desc: "消息标题", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "Markdown 正文", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "Markdown 正文", Required: true, Aliases: []string{"text"}}, {Name: "users", Type: shortcut.FlagStringSlice, Desc: "接收人 userId 列表"}, {Name: "open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "接收人 openDingTalkId 列表"}, {Name: "at-all", Type: shortcut.FlagBool, Desc: "@ 所有人"}, }, - Tips: []string{`dws chat +messages-batch-send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报"`}, + Tips: []string{`dws chat +messages-batch-send-by-bot --robot-code --users userId1,userId2 --title "提醒" --content "请提交周报"`}, Execute: func(rt *shortcut.RuntimeContext) error { if err := validateExplicitOpenIDs("--open-dingtalk-ids", rt.StrSlice("open-dingtalk-ids")); err != nil { return err @@ -103,7 +103,7 @@ var MessagesBatchSendByBot = shortcut.Shortcut{ params := map[string]any{ "robotCode": rt.Str("robot-code"), "title": rt.Str("title"), - "markdown": rt.Str("text"), + "markdown": rt.StrFirst("text", "content"), } if v := rt.StrSlice("users"); len(v) > 0 { params["userIds"] = v @@ -148,23 +148,23 @@ var MessagesSendByWebhook = shortcut.Shortcut{ AgentSummary: "兼容旧入口的自定义机器人 Webhook 群消息发送", UseWhen: []string{"只有既有自动化明确依赖 +messages-send-by-webhook 兼容路径、暂时不能迁移统一身份入口时使用"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws chat +messages-send-by-webhook --token --title \"告警\" --text \"CPU 超 90%\" --at-all"}, + Examples: []string{"dws chat +messages-send-by-webhook --token --title \"告警\" --content \"CPU 超 90%\" --at-all"}, }, }, Flags: []shortcut.Flag{ {Name: "token", Type: shortcut.FlagString, Desc: "Webhook token", Required: true}, {Name: "title", Type: shortcut.FlagString, Desc: "消息标题", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "消息正文", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "消息正文", Required: true, Aliases: []string{"text"}}, {Name: "at-all", Type: shortcut.FlagBool, Desc: "@ 所有人"}, {Name: "at-mobiles", Type: shortcut.FlagStringSlice, Desc: "@ 的手机号列表"}, {Name: "at-users", Type: shortcut.FlagStringSlice, Desc: "@ 的 userId 列表"}, }, - Tips: []string{`dws chat +messages-send-by-webhook --token --title "告警" --text "CPU 超 90%" --at-all`}, + Tips: []string{`dws chat +messages-send-by-webhook --token --title "告警" --content "CPU 超 90%" --at-all`}, Execute: func(rt *shortcut.RuntimeContext) error { params := map[string]any{ "robotToken": rt.Str("token"), "title": rt.Str("title"), - "text": rt.Str("text"), + "text": rt.StrFirst("text", "content"), } if rt.Bool("at-all") { params["isAtAll"] = true diff --git a/internal/shortcut/chat/lark_alignment.go b/internal/shortcut/chat/lark_alignment.go index a9f4c4e0..c5863370 100644 --- a/internal/shortcut/chat/lark_alignment.go +++ b/internal/shortcut/chat/lark_alignment.go @@ -200,11 +200,11 @@ var MessagesReply = shortcut.Shortcut{ Intent: "当你要以当前用户身份对一条已有消息发送纯文本引用回复时使用；传会话和原消息 ID，CLI 会先读取原发送者，也可显式传 --ref-sender。成功结果在保留下层响应的同时增量返回 messageId（下层提供时）、conversationId、threadId（适用时）、deliveryStatus、idempotencyKey 和 referencedMessage 来源上下文。", Risk: shortcut.RiskWrite, Flags: []shortcut.Flag{ - {Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true}, + {Name: "group", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true, Aliases: []string{"conversation-id"}}, {Name: "ref-msg-id", Type: shortcut.FlagString, Desc: "被引用消息 openMessageId"}, {Name: "message-id", Type: shortcut.FlagString, Desc: "--ref-msg-id 的 lark-cli 对齐别名"}, {Name: "ref-sender", Type: shortcut.FlagString, Desc: "原消息发送者 openDingTalkId/userId（userId 通过通讯录搜索精确匹配；不传则自动读取）"}, - {Name: "text", Type: shortcut.FlagString, Desc: "纯文本回复内容", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "纯文本回复内容", Required: true, Aliases: []string{"text"}}, {Name: "uuid", Type: shortcut.FlagString, Desc: "幂等键（可选）"}, {Name: "idempotency-key", Type: shortcut.FlagString, Desc: "--uuid 的 lark-cli 对齐别名"}, shortcut.AIMessageTagFlag(), @@ -213,7 +213,7 @@ var MessagesReply = shortcut.Shortcut{ {Kind: shortcut.ConstraintExactlyOne, Flags: []string{"ref-msg-id", "message-id"}}, {Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"uuid", "idempotency-key"}}, }, - Tips: []string{`dws chat +messages-reply --conversation-id --message-id --text "收到" --idempotency-key `}, + Tips: []string{`dws chat +messages-reply --group --message-id --content "收到" --idempotency-key `}, Execute: func(rt *shortcut.RuntimeContext) error { refSender, err := resolveReplySender(rt) if err != nil { @@ -223,10 +223,10 @@ var MessagesReply = shortcut.Shortcut{ "referenceOpenMessageId": replyMessageID(rt), "srcMsgSendOpenDingTalkId": refSender, "replyMsgType": "text", - "content": rt.Str("text"), + "content": rt.StrFirst("text", "content"), }) params := rt.AddAIMessageTag(map[string]any{ - "openConversationId": rt.Str("conversation-id"), + "openConversationId": replyConversationID(rt), "msgType": "reply", "content": string(content), }) @@ -240,7 +240,7 @@ var MessagesReply = shortcut.Shortcut{ "willSend": false, "transport": "chat/send_personal_message", "arguments": params, - "conversationId": rt.Str("conversation-id"), + "conversationId": replyConversationID(rt), "referencedMessage": map[string]any{ "messageId": replyMessageID(rt), "senderOpenDingTalkId": refSender, @@ -256,9 +256,13 @@ var MessagesReply = shortcut.Shortcut{ }, } +func replyConversationID(rt *shortcut.RuntimeContext) string { + return rt.StrFirst("conversation-id", "group") +} + func enrichReplyResult(data map[string]any, rt *shortcut.RuntimeContext, refSender string) { data["contractVersion"] = "im.message-reply.v1" - data["conversationId"] = rt.Str("conversation-id") + data["conversationId"] = replyConversationID(rt) data["referencedMessage"] = map[string]any{ "messageId": replyMessageID(rt), "senderOpenDingTalkId": refSender, diff --git a/internal/shortcut/chat/primary_param_migration_test.go b/internal/shortcut/chat/primary_param_migration_test.go new file mode 100644 index 00000000..822d833e --- /dev/null +++ b/internal/shortcut/chat/primary_param_migration_test.go @@ -0,0 +1,327 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package chat + +import ( + "bytes" + "encoding/json" + "reflect" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +func TestPrimaryParamMigrationChatContentPayloadCompatibility(t *testing.T) { + commands := []struct { + command string + baseArgs []string + wantProduct string + wantTool string + payloadKey string + }{ + { + command: "+messages-send-by-bot", + baseArgs: []string{"--robot-code", "robot", "--group", "cid", "--title", "title"}, + wantProduct: "bot", + wantTool: "send_robot_group_message", + payloadKey: "markdown", + }, + { + command: "+messages-batch-send-by-bot", + baseArgs: []string{"--robot-code", "robot", "--users", "u1", "--title", "title"}, + wantProduct: "bot", + wantTool: "batch_send_robot_msg_to_users", + payloadKey: "markdown", + }, + { + command: "+messages-send-by-webhook", + baseArgs: []string{"--token", "token", "--title", "title"}, + wantProduct: "bot", + wantTool: "send_message_by_custom_robot", + payloadKey: "text", + }, + } + spellings := []struct { + name string + args []string + wantValue string + }{ + {name: "old-only", args: []string{"--text", "legacy-value"}, wantValue: "legacy-value"}, + {name: "new-only", args: []string{"--content", "legacy-value"}, wantValue: "legacy-value"}, + { + name: "both-different-old-wins", + args: []string{"--text", "legacy-value", "--content", "canonical-value"}, + wantValue: "legacy-value", + }, + } + + for _, command := range commands { + payloads := make(map[string]map[string]any, len(spellings)) + for _, spelling := range spellings { + t.Run(command.command+"/"+spelling.name, func(t *testing.T) { + fake := &larkAlignmentCaller{} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + args := append([]string{"chat", command.command}, command.baseArgs...) + args = append(args, spelling.args...) + args = append(args, "--yes") + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatalf("execute %v: %v", args, err) + } + if len(fake.calls) != 1 { + t.Fatalf("calls = %#v, want one", fake.calls) + } + call := fake.calls[0] + if call.product != command.wantProduct || call.tool != command.wantTool { + t.Fatalf("call = %s/%s, want %s/%s", call.product, call.tool, command.wantProduct, command.wantTool) + } + if got := call.args[command.payloadKey]; got != spelling.wantValue { + t.Fatalf("%s = %#v, want %q; args=%#v", command.payloadKey, got, spelling.wantValue, call.args) + } + payloads[spelling.name] = call.args + }) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["new-only"]) { + t.Errorf("%s old/new payloads differ: old=%#v new=%#v", command.command, payloads["old-only"], payloads["new-only"]) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["both-different-old-wins"]) { + t.Errorf("%s old/both payloads differ: old=%#v both=%#v", command.command, payloads["old-only"], payloads["both-different-old-wins"]) + } + } +} + +func TestPrimaryParamMigrationMessagesReplyPayloadCompatibility(t *testing.T) { + spellings := []struct { + name string + args []string + wantConversation string + wantContent string + }{ + { + name: "old-only", + args: []string{"--conversation-id", "legacy-cid", "--text", "legacy-body"}, + wantConversation: "legacy-cid", + wantContent: "legacy-body", + }, + { + name: "new-only", + args: []string{"--group", "legacy-cid", "--content", "legacy-body"}, + wantConversation: "legacy-cid", + wantContent: "legacy-body", + }, + { + name: "both-different-old-wins", + args: []string{ + "--conversation-id", "legacy-cid", "--group", "canonical-cid", + "--text", "legacy-body", "--content", "canonical-body", + }, + wantConversation: "legacy-cid", + wantContent: "legacy-body", + }, + } + + payloads := make(map[string]map[string]any, len(spellings)) + for _, spelling := range spellings { + t.Run(spelling.name, func(t *testing.T) { + fake := &larkAlignmentCaller{responses: map[string]string{ + "chat/send_personal_message": `{"result":{"openMessageId":"new-msg"}}`, + }} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) + args := []string{ + "chat", "+messages-reply", "--message-id", "msg", + "--ref-sender", "D-sender", + } + args = append(args, spelling.args...) + args = append(args, "--yes") + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatalf("execute %v: %v", args, err) + } + if len(fake.calls) != 1 { + t.Fatalf("calls = %#v, want one", fake.calls) + } + call := fake.calls[0] + if call.product != "chat" || call.tool != "send_personal_message" { + t.Fatalf("reply call = %#v", call) + } + assertReplyPrimaryPayload(t, call.args, spelling.wantConversation, spelling.wantContent) + payloads[spelling.name] = call.args + + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatalf("decode reply output %q: %v", output.String(), err) + } + if got := payload["conversationId"]; got != spelling.wantConversation { + t.Fatalf("result conversationId = %#v, want %q; payload=%#v", got, spelling.wantConversation, payload) + } + }) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["new-only"]) { + t.Errorf("reply old/new payloads differ: old=%#v new=%#v", payloads["old-only"], payloads["new-only"]) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["both-different-old-wins"]) { + t.Errorf("reply old/both payloads differ: old=%#v both=%#v", payloads["old-only"], payloads["both-different-old-wins"]) + } + + t.Run("dry-run-both-different-old-wins", func(t *testing.T) { + fake := &larkAlignmentCaller{} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) + root.SetArgs([]string{ + "chat", "+messages-reply", "--message-id", "msg", "--ref-sender", "D-sender", + "--conversation-id", "legacy-cid", "--group", "canonical-cid", + "--text", "legacy-body", "--content", "canonical-body", + "--dry-run", "--yes", + }) + if err := root.Execute(); err != nil { + t.Fatal(err) + } + if len(fake.calls) != 0 { + t.Fatalf("dry-run reached transport: %#v", fake.calls) + } + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatalf("decode dry-run output %q: %v", output.String(), err) + } + if got := payload["conversationId"]; got != "legacy-cid" { + t.Fatalf("dry-run conversationId = %#v, want legacy-cid", got) + } + arguments, _ := payload["arguments"].(map[string]any) + assertReplyPrimaryPayload(t, arguments, "legacy-cid", "legacy-body") + }) +} + +func assertReplyPrimaryPayload(t *testing.T, args map[string]any, wantConversation, wantContent string) { + t.Helper() + if got := args["openConversationId"]; got != wantConversation { + t.Fatalf("openConversationId = %#v, want %q; args=%#v", got, wantConversation, args) + } + contentText, _ := args["content"].(string) + var content map[string]string + if err := json.Unmarshal([]byte(contentText), &content); err != nil { + t.Fatalf("decode reply content %q: %v", contentText, err) + } + if got := content["content"]; got != wantContent { + t.Fatalf("reply content = %q, want %q; payload=%#v", got, wantContent, content) + } +} + +func TestPrimaryParamMigrationChatSurfaceAndContract(t *testing.T) { + tests := []struct { + command string + params []chatPrimaryParamExpectation + }{ + { + command: "+messages-send-by-bot", + params: []chatPrimaryParamExpectation{{name: "content", legacy: "text", property: "text"}}, + }, + { + command: "+messages-batch-send-by-bot", + params: []chatPrimaryParamExpectation{{name: "content", legacy: "text", property: "text"}}, + }, + { + command: "+messages-send-by-webhook", + params: []chatPrimaryParamExpectation{{name: "content", legacy: "text", property: "text"}}, + }, + { + command: "+messages-reply", + params: []chatPrimaryParamExpectation{ + {name: "group", legacy: "conversation-id", property: "conversationId"}, + {name: "content", legacy: "text", property: "text"}, + }, + }, + } + + for _, test := range tests { + t.Run(test.command, func(t *testing.T) { + root := newPlatformCoverageRoot() + cmd, _, err := root.Find([]string{"chat", test.command}) + if err != nil || cmd == nil { + t.Fatalf("find command: %v", err) + } + for _, param := range test.params { + canonical := cmd.Flags().Lookup(param.name) + if canonical == nil || canonical.Hidden { + t.Fatalf("canonical --%s = %#v, want visible", param.name, canonical) + } + legacy := cmd.Flags().Lookup(param.legacy) + if legacy == nil || !legacy.Hidden { + t.Fatalf("legacy --%s = %#v, want hidden", param.legacy, legacy) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != param.name { + t.Fatalf("--%s alias_of = %#v, want %s", param.legacy, got, param.name) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("--%s alias origin = %#v", param.legacy, got) + } + } + + var help bytes.Buffer + cmd.SetOut(&help) + if err := cmd.Help(); err != nil { + t.Fatal(err) + } + for _, param := range test.params { + if !strings.Contains(help.String(), "--"+param.name) || strings.Contains(help.String(), "--"+param.legacy) { + t.Fatalf("help does not expose only --%s (legacy --%s):\n%s", param.name, param.legacy, help.String()) + } + } + + spec := chatRegisteredShortcut(t, test.command) + if len(spec.Contract.Parameters) != len(test.params) { + t.Fatalf("ParamDecls = %#v, want %d", spec.Contract.Parameters, len(test.params)) + } + for i, want := range test.params { + param := spec.Contract.Parameters[i] + if param.Name != want.name || param.Property != want.property || + param.Required == nil || !*param.Required || param.InterfaceType != "" { + t.Fatalf("ParamDecl[%d] = %#v, want %#v", i, param, want) + } + } + for _, example := range append(append([]string(nil), spec.Tips...), spec.Contract.Selection.Examples...) { + for _, param := range test.params { + if strings.Contains(example, "--"+param.legacy) || !strings.Contains(example, "--"+param.name) { + t.Fatalf("example does not recommend only --%s: %q", param.name, example) + } + } + } + }) + } +} + +type chatPrimaryParamExpectation struct { + name string + legacy string + property string +} + +func chatRegisteredShortcut(t *testing.T, command string) shortcut.Shortcut { + t.Helper() + for _, spec := range shortcut.All() { + if spec.Service == "chat" && spec.Command == command { + return spec + } + } + t.Fatalf("registered shortcut chat %s not found", command) + return shortcut.Shortcut{} +} diff --git a/internal/shortcut/chat/schema_contracts.go b/internal/shortcut/chat/schema_contracts.go index 6b9d7074..77c59763 100644 --- a/internal/shortcut/chat/schema_contracts.go +++ b/internal/shortcut/chat/schema_contracts.go @@ -87,18 +87,46 @@ func withReviewedChatShortcutContracts(values ...shortcut.Shortcut) []shortcut.S out := make([]shortcut.Shortcut, len(values)) for i, value := range values { out[i] = value - if !value.Contract.Empty() { - continue + if value.Contract.Empty() { + if _, reviewed := reviewedChatShortcutContractCommands[value.Command]; reviewed { + out[i].Safety = reviewedChatShortcutSafety(value.Risk) + out[i].Contract = reviewedChatShortcutContract(value) + } } - if _, reviewed := reviewedChatShortcutContractCommands[value.Command]; !reviewed { - continue - } - out[i].Safety = reviewedChatShortcutSafety(value.Risk) - out[i].Contract = reviewedChatShortcutContract(value) + out[i].Contract.Parameters = append( + out[i].Contract.Parameters, + reviewedChatPrimaryParamDecls(value.Command)..., + ) } return out } +func reviewedChatPrimaryParamDecls(command string) []contract.ParamDecl { + switch command { + case "+messages-send-by-bot", "+messages-batch-send-by-bot", "+messages-send-by-webhook": + return []contract.ParamDecl{renamedRequiredChatParam("content", "text")} + case "+messages-reply": + return []contract.ParamDecl{ + renamedRequiredChatParam("group", "conversationId"), + renamedRequiredChatParam("content", "text"), + } + default: + return nil + } +} + +// renamedRequiredChatParam preserves the pre-rename Schema property and +// requiredness. InterfaceType stays unset because these Shortcut parameters +// historically published only their Cobra string type. +func renamedRequiredChatParam(name, property string) contract.ParamDecl { + required := true + return contract.ParamDecl{ + Name: name, + Property: property, + Required: &required, + } +} + func reviewedChatShortcutSafety(risk shortcut.Risk) contract.SafetySpec { switch risk { case shortcut.RiskWrite: diff --git a/internal/shortcut/smart/broadcast.go b/internal/shortcut/smart/broadcast.go index 6c9852f8..664031d4 100644 --- a/internal/shortcut/smart/broadcast.go +++ b/internal/shortcut/smart/broadcast.go @@ -34,7 +34,7 @@ import ( // without aborting delivery to the others. Replaces manually running // `chat +dm` once per recipient. // -// dws chat +broadcast --to "张三,李四,王五" --text "今晚 8 点上线，请留意群公告" +// dws chat +broadcast --to "张三,李四,王五" --content "今晚 8 点上线，请留意群公告" var Broadcast = shortcut.Shortcut{ Service: "chat", Command: "+broadcast", @@ -66,17 +66,18 @@ var Broadcast = shortcut.Shortcut{ AgentSummary: "按姓名逐一给多个人群发同一条单聊消息（自动解析 userId、逐个发送）", UseWhen: []string{"当你想把同一条通知一次性单聊发给多位同事、但只知道他们的姓名不想逐个查 userId 时使用；内部把姓名列表逐个解析成唯一用户后，用 openDingTalkId 对每个人单独发一条单聊消息，并汇总成功/失败人数。某个姓名匹配不到人或匹配到多人时，会跳过该人并在结尾报出，不影响其他人收到消息。会真实发出多条消息。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws chat +broadcast --to \"张三,李四,王五\" --text \"今晚 8 点上线，请留意\""}, + Examples: []string{"dws chat +broadcast --to \"张三,李四,王五\" --content \"今晚 8 点上线，请留意\""}, }, + Parameters: []contract.ParamDecl{renamedRequiredParam("content", "text")}, }, Flags: []shortcut.Flag{ {Name: "to", Type: shortcut.FlagStringSlice, Desc: "收件人姓名/花名，逗号分隔的多个人", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown），所有人收到同一条", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown），所有人收到同一条", Required: true, Aliases: []string{"text"}}, shortcut.AIMessageTagFlag(), }, - Tips: []string{`dws chat +broadcast --to "张三,李四,王五" --text "今晚 8 点上线，请留意"`}, + Tips: []string{`dws chat +broadcast --to "张三,李四,王五" --content "今晚 8 点上线，请留意"`}, Execute: func(rt *shortcut.RuntimeContext) error { - text := rt.Str("text") + text := rt.StrFirst("text", "content") names := rt.StrSlice("to") if len(names) == 0 { return apperrors.NewValidation("--to 至少要包含一个姓名") diff --git a/internal/shortcut/smart/dm.go b/internal/shortcut/smart/dm.go index 1a7ef16a..2037507e 100644 --- a/internal/shortcut/smart/dm.go +++ b/internal/shortcut/smart/dm.go @@ -31,7 +31,7 @@ import ( // a single-chat message via openDingTalkId. Replaces `contact +search-user` // (copy openDingTalkId) → `chat +messages-send --open-dingtalk-id `. // -// dws chat +dm --to 张三 --text "周报发我一下" +// dws chat +dm --to 张三 --content "周报发我一下" var DM = shortcut.Shortcut{ Service: "chat", Command: "+dm", @@ -62,17 +62,18 @@ var DM = shortcut.Shortcut{ AgentSummary: "按姓名直接给某人发单聊消息（自动解析唯一 openDingTalkId）", UseWhen: []string{"当你只知道对方姓名、想直接发一条单聊消息而不想先查 userId 时使用；内部先按姓名搜通讯录解析出唯一用户，并用其 openDingTalkId 发送，姓名匹配到多人时会列出候选让你区分。会真实发出消息。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws chat +dm --to 张三 --text \"周报发我一下\""}, + Examples: []string{"dws chat +dm --to 张三 --content \"周报发我一下\""}, }, + Parameters: []contract.ParamDecl{renamedRequiredParam("content", "text")}, }, Flags: []shortcut.Flag{ {Name: "to", Type: shortcut.FlagString, Desc: "收件人姓名/花名", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown）", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown）", Required: true, Aliases: []string{"text"}}, shortcut.AIMessageTagFlag(), }, - Tips: []string{`dws chat +dm --to 张三 --text "周报发我一下"`}, + Tips: []string{`dws chat +dm --to 张三 --content "周报发我一下"`}, Execute: func(rt *shortcut.RuntimeContext) error { - text := rt.Str("text") + text := rt.StrFirst("text", "content") resolved, err := targetresolver.ResolveUser( rt, diff --git a/internal/shortcut/smart/primary_param_contract.go b/internal/shortcut/smart/primary_param_contract.go new file mode 100644 index 00000000..889fbc1e --- /dev/null +++ b/internal/shortcut/smart/primary_param_contract.go @@ -0,0 +1,28 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package smart + +import "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" + +// renamedRequiredParam preserves the pre-rename Schema property and +// requiredness. InterfaceType intentionally remains unset because these +// Shortcut parameters historically published only their Cobra string type. +func renamedRequiredParam(name, property string) contract.ParamDecl { + required := true + return contract.ParamDecl{ + Name: name, + Property: property, + Required: &required, + } +} diff --git a/internal/shortcut/smart/send_to_group.go b/internal/shortcut/smart/send_to_group.go index 0232ba52..e23903f7 100644 --- a/internal/shortcut/smart/send_to_group.go +++ b/internal/shortcut/smart/send_to_group.go @@ -33,7 +33,7 @@ import ( // group NAMES) — NOT `search_common_groups`, which searches by member nicknames // and cannot locate a group by its title. // -// dws chat +send-to-group --group 项目冲刺 --text "今天 5 点前提交进度" +// dws chat +send-to-group --group 项目冲刺 --content "今天 5 点前提交进度" var SendToGroup = shortcut.Shortcut{ Service: "chat", Command: "+send-to-group", @@ -63,18 +63,19 @@ var SendToGroup = shortcut.Shortcut{ AgentSummary: "按群名或 openConversationId 直接给群发消息", UseWhen: []string{"当你有群名或 openConversationId、想直接往该群发送简单文本或 Markdown 时使用；稳定 ID 不进入搜索，群名则必须唯一解析，零命中或多候选都会在发送前停止。会真实发出群消息。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws chat +send-to-group --group 项目冲刺 --text \"今天 5 点前提交进度\""}, + Examples: []string{"dws chat +send-to-group --group 项目冲刺 --content \"今天 5 点前提交进度\""}, }, + Parameters: []contract.ParamDecl{renamedRequiredParam("content", "text")}, }, Flags: []shortcut.Flag{ {Name: "group", Type: shortcut.FlagString, Desc: "群名称或 openConversationId", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown）", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "消息内容（支持 Markdown）", Required: true, Aliases: []string{"text"}}, shortcut.AIMessageTagFlag(), }, - Tips: []string{`dws chat +send-to-group --group 项目冲刺 --text "今天 5 点前提交进度"`}, + Tips: []string{`dws chat +send-to-group --group 项目冲刺 --content "今天 5 点前提交进度"`}, Execute: func(rt *shortcut.RuntimeContext) error { groupName := rt.Str("group") - text := rt.Str("text") + text := rt.StrFirst("text", "content") resolved, err := targetresolver.ResolveChatTarget(rt, groupName, "") if err != nil { From 290f39ecb8fcb07ce8fd77c77ffd9e54330c5efb Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 23:31:39 +0800 Subject: [PATCH 225/250] feat: migrate doc and todo primary parameters to #85349380 --- internal/helpers/doc.go | 38 ++-- internal/helpers/todo.go | 30 ++- internal/shortcut/smart/doc_append.go | 17 +- .../smart/primary_param_migration_test.go | 197 ++++++++++++++++++ 4 files changed, 249 insertions(+), 33 deletions(-) create mode 100644 internal/shortcut/smart/primary_param_migration_test.go diff --git a/internal/helpers/doc.go b/internal/helpers/doc.go index c1740468..177f2976 100644 --- a/internal/helpers/doc.go +++ b/internal/helpers/doc.go @@ -15,10 +15,10 @@ import ( "time" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/spf13/cobra" - - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) // ────────────────────────────────────────────────────────── @@ -1018,7 +1018,7 @@ func inferMimeType(fileName string) string { } // buildBlockElement 从 flags 构建块元素 JSON 对象。 -// 优先级: --element (原始 JSON) > --heading > --text +// 优先级: --element (原始 JSON) > --heading > --text (旧名) > --content func buildBlockElement(cmd *cobra.Command) (any, error) { if raw, _ := cmd.Flags().GetString("element"); raw != "" { var obj any @@ -1037,13 +1037,13 @@ func buildBlockElement(cmd *cobra.Command) (any, error) { "heading": map[string]any{"text": h, "level": level}, }, nil } - if t, _ := cmd.Flags().GetString("text"); t != "" { + if t := flagOrFallback(cmd, "text", "content"); t != "" { return map[string]any{ "blockType": "paragraph", "paragraph": map[string]any{"text": t}, }, nil } - return nil, fmt.Errorf("block content required: --text / --heading / --element") + return nil, fmt.Errorf("block content required: --content / --heading / --element") } // buildNodeTransferRunE creates a RunE handler for copy/move commands. @@ -2127,12 +2127,12 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 Use: "insert", Short: "插入块元素", Long: `向文档插入块元素。通过 --element 传入 JSON 格式的块元素。 -可用 --text 快速插入段落，--heading + --level 快速插入标题。 +可用 --content 快速插入段落，--heading + --level 快速插入标题。 块类型: paragraph, heading, blockquote, callout, columns, orderedList, unorderedList, table, sheet, attachment, slot`, Example: ` # 快捷插入段落 - dws doc block insert --node DOC_ID --text "这是一段文字" + dws doc block insert --node DOC_ID --content "这是一段文字" # 快捷插入标题 dws doc block insert --node DOC_ID --heading "二级标题" --level 2 @@ -2155,7 +2155,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 dws doc block insert --node DOC_ID --element '{"blockType":"unorderedList","unorderedList":{"list":{"listId":"list-2"}},"children":[{"text":"第二项"}]}' # 在指定位置之前插入 - dws doc block insert --node DOC_ID --text "插入内容" --ref-block BLOCK_ID --where before`, + dws doc block insert --node DOC_ID --content "插入内容" --ref-block BLOCK_ID --where before`, RunE: func(cmd *cobra.Command, args []string) error { nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id") if err != nil { @@ -2241,14 +2241,14 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 }, Selection: contract.SelectionSpec{ AgentSummary: "向文档插入块元素", - UseWhen: []string{"在文档中插入新块（段落/标题等）；简单场景用 --text/--heading，复杂块用 --element JSON"}, + UseWhen: []string{"在文档中插入新块（段落/标题等）；简单场景用 --content/--heading，复杂块用 --element JSON"}, AvoidWhen: []string{ "整篇追加 Markdown 优先 doc update --mode append", "插入本地文件附件优先 doc media insert", "删块用 block delete；改已有块用 block update", }, Examples: []string{ - "dws doc block insert --node --text \"这是一段文字\" --format json", + "dws doc block insert --node --content \"这是一段文字\" --format json", "dws doc block insert --node --heading \"二级标题\" --level 2 --format json", }, }, @@ -2265,8 +2265,8 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 Use: "update", Short: "更新块元素", Long: `更新文档中指定块的内容或样式。需提供 --block-id 和块元素内容。 -可用 --text 快速更新为段落，--heading + --level 快速更新为标题。`, - Example: ` dws doc block update --node DOC_ID --block-id BLOCK_ID --text "新内容" # 查询 nodeId: dws doc search --query "..." 或 dws doc list # 查询 blockId: dws doc block list --node +可用 --content 快速更新为段落，--heading + --level 快速更新为标题。`, + Example: ` dws doc block update --node DOC_ID --block-id BLOCK_ID --content "新内容" # 查询 nodeId: dws doc search --query "..." 或 dws doc list # 查询 blockId: dws doc block list --node dws doc block update --node DOC_ID --block-id BLOCK_ID --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}'`, RunE: func(cmd *cobra.Command, args []string) error { if err := validateRequiredFlags(cmd, "block-id"); err != nil { @@ -2338,7 +2338,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 "插入新块用 block insert；删除用 block delete", "改文档显示名用 rename；整篇覆盖用 update overwrite", }, - Examples: []string{"dws doc block update --node --block-id --text \"新内容\" --format json"}, + Examples: []string{"dws doc block update --node --block-id --content \"新内容\" --format json"}, }, Parameters: []contract.ParamDecl{ {Name: "content-format", Property: "format"}, @@ -2748,7 +2748,6 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 // block insert blockInsertCmd.Flags().String("node", "", "文档 ID 或 URL (必填)") - blockInsertCmd.Flags().String("text", "", "快捷: 段落文本内容") blockInsertCmd.Flags().String("heading", "", "快捷: 标题文本") blockInsertCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)") blockInsertCmd.Flags().String("element", "", "块元素 JSON (高级)") @@ -2762,7 +2761,6 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。 // block update blockUpdateCmd.Flags().String("node", "", "文档 ID 或 URL (必填)") blockUpdateCmd.Flags().String("block-id", "", "目标块 ID (必填)") - blockUpdateCmd.Flags().String("text", "", "快捷: 段落文本内容") blockUpdateCmd.Flags().String("heading", "", "快捷: 标题文本") blockUpdateCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)") blockUpdateCmd.Flags().String("element", "", "块元素 JSON (高级)") @@ -4644,6 +4642,16 @@ CLI 内部自动完成全部流程: RegisterCrossProductAliases(child) } } + // Register the block content Primary after the cross-product pass. Registering + // --content earlier would make the global content/markdown group expand a new + // --markdown alias onto these commands, which is outside this migration. + for _, cmd := range []*cobra.Command{blockInsertCmd, blockUpdateCmd} { + corecmd.RegisterFlags(cmd, []corecmd.FlagSpec{{ + Name: "content", + Usage: "快捷: 段落文本内容", + Aliases: []string{"text"}, + }}) + } // ── deprecated 标记：文件管理命令已迁移到 drive ── deprecatedDocToDrive := map[*cobra.Command]string{ diff --git a/internal/helpers/todo.go b/internal/helpers/todo.go index 5c62d390..5332513a 100644 --- a/internal/helpers/todo.go +++ b/internal/helpers/todo.go @@ -11,11 +11,11 @@ import ( "strings" "time" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/fatih/color" "github.com/spf13/cobra" - - "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) // ────────────────────────────────────────────────────────── @@ -1017,14 +1017,20 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作 Short: "上传待办附件", Long: `上传待办附件 ⚠️ 重要：该接口会上传文件到附件，不可用于测试或试探性调用。调用前必须确认待办存在。`, - Example: ` dws todo task add-attachment --task-id --file-path + Example: ` dws todo task add-attachment --task-id --file # 查询 taskId: dws todo task list`, RunE: func(cmd *cobra.Command, args []string) error { - if err := validateRequiredFlags(cmd, "task-id", "file-path"); err != nil { - return err + filePath := flagOrFallback(cmd, "file-path", "file") + taskID := mustGetFlag(cmd, "task-id") + if taskID == "" && filePath == "" { + return validateRequiredFlags(cmd, "task-id", "file") + } + if taskID == "" { + return validateRequiredFlags(cmd, "task-id") + } + if filePath == "" { + return validateRequiredFlags(cmd, "file") } - - filePath, _ := cmd.Flags().GetString("file-path") meta, err := buildTodoLocalFileMeta(filePath, "", "") if err != nil { return err @@ -1092,8 +1098,8 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作 "要添加执行人/参与人/提醒时改用对应 add 命令", }, Examples: []string{ - "dws todo task add-attachment --task-id --file-path /path/to/file.pdf", - "dws todo task add-attachment --task-id --file-path /path/to/file.pdf --format json", + "dws todo task add-attachment --task-id --file /path/to/file.pdf", + "dws todo task add-attachment --task-id --file /path/to/file.pdf --format json", }, }, Parameters: []contract.ParamDecl{ @@ -1247,7 +1253,11 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作 todoTaskListSubCmd.Flags().String("task-id", "", "待办任务 ID (必填)") todoTaskListAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)") todoTaskAddAttachment.Flags().String("task-id", "", "待办任务 ID (必填)") - todoTaskAddAttachment.Flags().String("file-path", "", "本地文件路径（必填）") + corecmd.RegisterFlags(todoTaskAddAttachment, []corecmd.FlagSpec{{ + Name: "file", + Usage: "本地文件路径（必填）", + Aliases: []string{"file-path"}, + }}) todoTaskRemoveAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)") todoTaskRemoveAttachmentCmd.Flags().String("attachment-id", "", "待办附件 ID（必填）") diff --git a/internal/shortcut/smart/doc_append.go b/internal/shortcut/smart/doc_append.go index e00f526a..1629e0b6 100644 --- a/internal/shortcut/smart/doc_append.go +++ b/internal/shortcut/smart/doc_append.go @@ -33,7 +33,7 @@ import ( // touching existing content. Params (nodeId/markdown/mode) are copied verbatim // from the update_document append call site in internal/helpers/doc.go. // -// dws doc +doc-append --doc DOC_ID --text "今天的会议结论：下周一上线。" +// dws doc +doc-append --doc DOC_ID --content "今天的会议结论：下周一上线。" var DocAppend = shortcut.Shortcut{ Service: "doc", Command: "+doc-append", @@ -67,27 +67,28 @@ var DocAppend = shortcut.Shortcut{ UseWhen: []string{"当你只想往一篇钉钉文档的最后面补一段文字、又不想动原有内容时使用；内部用文档更新的“追加(append)”模式，把你给的文本安全地拼到文档末尾，不需要你先去查文档块列表、算末尾位置或手工拼块结构。会真实写入文档内容。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, Examples: []string{ - "dws doc +doc-append --doc DOC_ID --text \"补充说明：本方案已评审通过。\"", - "dws doc +doc-append --doc \"https://alidocs.dingtalk.com/i/nodes/\" --text \"追加一行备注\"", + "dws doc +doc-append --doc DOC_ID --content \"补充说明：本方案已评审通过。\"", + "dws doc +doc-append --doc \"https://alidocs.dingtalk.com/i/nodes/\" --content \"追加一行备注\"", }, }, + Parameters: []contract.ParamDecl{renamedRequiredParam("content", "text")}, }, Flags: []shortcut.Flag{ {Name: "doc", Type: shortcut.FlagString, Desc: "文档 documentId / nodeId（或文档 URL/token）", Required: true}, - {Name: "text", Type: shortcut.FlagString, Desc: "要追加到文档末尾的文本", Required: true}, + {Name: "content", Type: shortcut.FlagString, Desc: "要追加到文档末尾的文本", Required: true, Aliases: []string{"text"}}, }, Tips: []string{ - `dws doc +doc-append --doc DOC_ID --text "补充说明：本方案已评审通过。"`, - `dws doc +doc-append --doc "https://alidocs.dingtalk.com/i/nodes/" --text "追加一行备注"`, + `dws doc +doc-append --doc DOC_ID --content "补充说明：本方案已评审通过。"`, + `dws doc +doc-append --doc "https://alidocs.dingtalk.com/i/nodes/" --content "追加一行备注"`, }, Execute: func(rt *shortcut.RuntimeContext) error { nodeID := strings.TrimSpace(rt.Str("doc")) if nodeID == "" { return apperrors.NewValidation("--doc 不能为空，请提供文档 documentId/nodeId 或文档 URL") } - text := rt.Str("text") + text := rt.StrFirst("text", "content") if strings.TrimSpace(text) == "" { - return apperrors.NewValidation("--text 不能为空，请提供要追加的文本") + return apperrors.NewValidation("--content 不能为空，请提供要追加的文本") } // update_document append: params copied verbatim from the helper's diff --git a/internal/shortcut/smart/primary_param_migration_test.go b/internal/shortcut/smart/primary_param_migration_test.go new file mode 100644 index 00000000..9c6832cf --- /dev/null +++ b/internal/shortcut/smart/primary_param_migration_test.go @@ -0,0 +1,197 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package smart + +import ( + "bytes" + "encoding/json" + "reflect" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" +) + +func TestPrimaryParamMigrationSmartPayloadCompatibility(t *testing.T) { + commands := []struct { + name string + baseArgs []string + wantProduct string + wantTool string + payloadKey string + }{ + { + name: "broadcast", + baseArgs: []string{"chat", "+broadcast", "--to", "张三"}, + wantProduct: "chat", + wantTool: "send_personal_message", + payloadKey: "content", + }, + { + name: "dm", + baseArgs: []string{"chat", "+dm", "--to", "张三"}, + wantProduct: "chat", + wantTool: "send_personal_message", + payloadKey: "content", + }, + { + name: "send-to-group", + baseArgs: []string{"chat", "+send-to-group", "--group", "项目冲刺"}, + wantProduct: "chat", + wantTool: "send_personal_message", + payloadKey: "content", + }, + { + name: "doc-append", + baseArgs: []string{"doc", "+doc-append", "--doc", "doc-1"}, + wantProduct: "doc", + wantTool: "update_document", + payloadKey: "markdown", + }, + } + spellings := []struct { + name string + args []string + wantValue string + }{ + {name: "old-only", args: []string{"--text", "legacy-value"}, wantValue: "legacy-value"}, + {name: "new-only", args: []string{"--content", "legacy-value"}, wantValue: "legacy-value"}, + { + name: "both-different-old-wins", + args: []string{"--text", "legacy-value", "--content", "canonical-value"}, + wantValue: "legacy-value", + }, + } + + for _, command := range commands { + payloads := make(map[string]map[string]any, len(spellings)) + for _, spelling := range spellings { + t.Run(command.name+"/"+spelling.name, func(t *testing.T) { + fake := &platformCoverageCaller{} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + args := append([]string(nil), command.baseArgs...) + args = append(args, spelling.args...) + args = append(args, "--yes") + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatalf("execute %v: %v", args, err) + } + if len(fake.calls) == 0 { + t.Fatal("shortcut made no MCP call") + } + call := fake.calls[len(fake.calls)-1] + if call.product != command.wantProduct || call.tool != command.wantTool { + t.Fatalf("last call = %s/%s, want %s/%s", call.product, call.tool, command.wantProduct, command.wantTool) + } + if got := smartPrimaryPayloadValue(t, call.args, command.payloadKey); got != spelling.wantValue { + t.Fatalf("payload value = %q, want %q; args=%#v", got, spelling.wantValue, call.args) + } + payloads[spelling.name] = call.args + }) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["new-only"]) { + t.Errorf("%s old/new payloads differ: old=%#v new=%#v", command.name, payloads["old-only"], payloads["new-only"]) + } + if !reflect.DeepEqual(payloads["old-only"], payloads["both-different-old-wins"]) { + t.Errorf("%s old/both payloads differ: old=%#v both=%#v", command.name, payloads["old-only"], payloads["both-different-old-wins"]) + } + } +} + +func smartPrimaryPayloadValue(t *testing.T, args map[string]any, key string) string { + t.Helper() + value, _ := args[key].(string) + if key == "markdown" { + return value + } + var content map[string]string + if err := json.Unmarshal([]byte(value), &content); err != nil { + t.Fatalf("decode markdown content %q: %v", value, err) + } + return content["text"] +} + +func TestPrimaryParamMigrationSmartSurfaceAndContract(t *testing.T) { + tests := []struct { + service string + command string + }{ + {service: "chat", command: "+broadcast"}, + {service: "chat", command: "+dm"}, + {service: "chat", command: "+send-to-group"}, + {service: "doc", command: "+doc-append"}, + } + + root := newPlatformCoverageRoot() + for _, test := range tests { + t.Run(test.service+"/"+test.command, func(t *testing.T) { + cmd, _, err := root.Find([]string{test.service, test.command}) + if err != nil || cmd == nil { + t.Fatalf("find command: %v", err) + } + canonical := cmd.Flags().Lookup("content") + if canonical == nil || canonical.Hidden { + t.Fatalf("canonical --content = %#v, want visible", canonical) + } + legacy := cmd.Flags().Lookup("text") + if legacy == nil || !legacy.Hidden { + t.Fatalf("legacy --text = %#v, want hidden", legacy) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "content" { + t.Fatalf("--text alias_of = %#v, want content", got) + } + if got := legacy.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("--text alias origin = %#v", got) + } + + var help bytes.Buffer + cmd.SetOut(&help) + if err := cmd.Help(); err != nil { + t.Fatal(err) + } + if !strings.Contains(help.String(), "--content") || strings.Contains(help.String(), "--text") { + t.Fatalf("help does not expose only the new Primary:\n%s", help.String()) + } + + spec := smartRegisteredShortcut(t, test.service, test.command) + if len(spec.Contract.Parameters) != 1 { + t.Fatalf("ParamDecls = %#v, want one", spec.Contract.Parameters) + } + param := spec.Contract.Parameters[0] + if param.Name != "content" || param.Property != "text" || + param.Required == nil || !*param.Required || param.InterfaceType != "" { + t.Fatalf("content ParamDecl = %#v", param) + } + for _, example := range append(append([]string(nil), spec.Tips...), spec.Contract.Selection.Examples...) { + if strings.Contains(example, "--text") || !strings.Contains(example, "--content") { + t.Fatalf("example does not recommend only --content: %q", example) + } + } + }) + } +} + +func smartRegisteredShortcut(t *testing.T, service, command string) shortcut.Shortcut { + t.Helper() + for _, spec := range shortcut.All() { + if spec.Service == service && spec.Command == command { + return spec + } + } + t.Fatalf("registered shortcut %s %s not found", service, command) + return shortcut.Shortcut{} +} From a3b06befbc0faa212184905c6415736772cba6db Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 23:31:50 +0800 Subject: [PATCH 226/250] test: enforce primary parameter compatibility to #85349380 --- .../param_alias_payload_equivalence_test.go | 33 +- internal/app/root_help_test.go | 4 +- internal/cli/param_aliases_generated.go | 25 +- internal/cli/param_concepts.json | 17 +- .../primary_param_schema_governance_test.go | 242 ++++++++++ internal/cli/schema_constraints_runtime.go | 4 +- .../cli/schema_parameter_mapping_ledger.go | 12 +- internal/cli/schema_parameters_runtime.go | 6 +- .../primary_param_native_compat_test.go | 434 ++++++++++++++++++ .../approved-flag-migrations-v1.json | 38 +- 10 files changed, 745 insertions(+), 70 deletions(-) create mode 100644 internal/cli/primary_param_schema_governance_test.go create mode 100644 internal/helpers/primary_param_native_compat_test.go diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index dad32b74..6d83f718 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -73,12 +73,12 @@ var paramAliasCompleteCommands = map[string][]string{ "chat +messages-list": {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"}, "chat +messages-list-direct": {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"}, "chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"}, - "chat +messages-reply": {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"}, + "chat +messages-reply": {"chat", "+messages-reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"}, "chat +messages-resource-download": {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"}, "chat +messages-set-pin": {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"}, - "chat +messages-send-by-webhook": {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"}, + "chat +messages-send-by-webhook": {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"}, "chat +search-msg": {"chat", "+search-msg", "--group", "fixture-conversation", "--query", "fixture", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--no-enrich"}, - "chat +send-to-group": {"chat", "+send-to-group", "--group", "Fixture Group", "--text", "hello fixture", "--yes"}, + "chat +send-to-group": {"chat", "+send-to-group", "--group", "Fixture Group", "--content", "hello fixture", "--yes"}, "chat +unread-chats": {"chat", "+unread-chats", "--count", "7", "--exclude-muted"}, "chat bot find": {"chat", "bot", "find", "--query", "fixture", "--limit", "7"}, "chat bot search": {"chat", "bot", "search", "--name", "Fixture Bot", "--page", "2", "--size", "7"}, @@ -104,11 +104,11 @@ var paramAliasCompleteCommands = map[string][]string{ "chat message list-by-ids": {"chat", "message", "list-by-ids", "--msg-ids", "message-1,message-2"}, "chat message list-unread-conversations": {"chat", "message", "list-unread-conversations", "--count", "7", "--exclude-muted"}, "chat message recall": {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"}, - "chat message reply": {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"}, + "chat message reply": {"chat", "message", "reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"}, "chat message search-advanced": {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"}, - "chat message send": {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"}, + "chat message send": {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"}, "chat message send-by-bot": {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"}, - "chat message send-by-webhook": {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"}, + "chat message send-by-webhook": {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"}, "contact +dept-members": {"contact", "+dept-members", "--dept", "Fixture Dept"}, "contact +list-sub-depts": {"contact", "+list-sub-depts", "--dept", "1"}, "contact +resolve-dept": {"contact", "+resolve-dept", "--name", "Fixture Dept"}, @@ -127,7 +127,7 @@ var paramAliasCompleteCommands = map[string][]string{ "doc +copy": {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"}, "doc +create": {"doc", "+create", "--name", "Fixture Document", "--content", "fixture body", "--doc-format", "markdown"}, "doc +create-from-template": {"doc", "+create-from-template", "--query", "fixture template", "--name", "Fixture From Template", "--folder", "folder-1", "--workspace", "workspace-1"}, - "doc +doc-append": {"doc", "+doc-append", "--doc", "node-1", "--text", "fixture appendix", "--yes"}, + "doc +doc-append": {"doc", "+doc-append", "--doc", "node-1", "--content", "fixture appendix", "--yes"}, "doc +export-submit": {"doc", "+export-submit", "--node", "node-1", "--export-format", "docx"}, "doc +fetch": {"doc", "+fetch", "--node", "node-1", "--scope", "section", "--start-block-id", "block-1"}, "doc +find-doc": {"doc", "+find-doc", "--query", "fixture", "--limit", "7"}, @@ -143,8 +143,8 @@ var paramAliasCompleteCommands = map[string][]string{ "doc +version-save": {"doc", "+version-save", "--node", "node-1", "--yes"}, "doc +update": {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"}, "doc +export": {"doc", "+export", "--node", "node-1", "--export-format", "docx", "--output", "exports/fixture.docx"}, - "doc block insert": {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"}, - "doc block update": {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"}, + "doc block insert": {"doc", "block", "insert", "--node", "node-1", "--content", "fixture paragraph", "--yes"}, + "doc block update": {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--content", "fixture paragraph", "--yes"}, "doc comment create": {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"}, "doc comment create-inline": {"doc", "comment", "create-inline", "--node", "node-1", "--block-id", "block-1", "--start", "0", "--end", "7", "--content", "fixture comment", "--yes"}, "doc comment delete": {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"}, @@ -207,7 +207,7 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ "workspace": {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"}, }, "doc block insert": { - "parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"}, + "parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--content", "fixture paragraph", "--yes"}, }, "doc +inspect": { "include-permissions": {"doc", "+inspect", "--node", "node-1", "--include-permissions"}, @@ -230,8 +230,8 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{ "sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", appFixtureCurrentDOpenID, "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"}, }, "chat message send": { - "group": {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"}, - "file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"}, + "group": {"chat", "message", "send", "--group", "fixture-conversation", "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"}, + "file": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"}, }, "chat +conversation-set-top": { "conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"}, @@ -271,7 +271,6 @@ var paramAliasNewIMCases = []struct { {command: "chat message list-favorites", emitted: "limit", canonical: "size"}, {command: "chat message list-unread-conversations", emitted: "limit", canonical: "count"}, {command: "chat message list-unread-conversations", emitted: "size", canonical: "count"}, - {command: "chat message send", emitted: "file", canonical: "file-path"}, {command: "chat message send-by-bot", emitted: "at-users", canonical: "at-user-ids"}, {command: "chat message send-by-webhook", emitted: "at-user-ids", canonical: "at-users"}, {command: "chat +chat-update", emitted: "chat-id", canonical: "group"}, @@ -289,7 +288,7 @@ var paramAliasNewIMCases = []struct { {command: "chat +chat-members-get", emitted: "chat", canonical: "id"}, {command: "chat +messages-list", emitted: "start", canonical: "time"}, {command: "chat +messages-reply", emitted: "msg-id", canonical: "ref-msg-id"}, - {command: "chat +messages-reply", emitted: "chat", canonical: "conversation-id"}, + {command: "chat +messages-reply", emitted: "chat", canonical: "group"}, {command: "chat +flag-cancel", emitted: "group", canonical: "conversation-id"}, {command: "chat +flag-cancel", emitted: "chat", canonical: "conversation-id"}, {command: "chat +flag-create", emitted: "group", canonical: "conversation-id"}, @@ -554,7 +553,11 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("doc +update", "revision"): true, // optimistic edit revision alias paramAliasPayloadCaseKey("doc +access-grant", "doc-id"): true, // permission write keeps document identity paramAliasPayloadCaseKey("doc +version-revert", "version-number"): true, // high-write version role with canonical confirmation - paramAliasPayloadCaseKey("doc block insert", "content"): true, // block write content alias + paramAliasPayloadCaseKey("chat +messages-reply", "conversation-id"): true, // renamed conversation Primary keeps final reply payload + paramAliasPayloadCaseKey("chat message send", "file-path"): true, // renamed local-file Primary reaches the same final payload + paramAliasPayloadCaseKey("doc +doc-append", "text"): true, // shortcut content rename keeps append payload + paramAliasPayloadCaseKey("doc block insert", "text"): true, // block write content compatibility alias + paramAliasPayloadCaseKey("doc block update", "text"): true, // update uses the same typed compatibility path paramAliasPayloadCaseKey("doc block insert", "parent-block-id"): true, // scoped block-role alias paramAliasPayloadCaseKey("doc comment delete", "comment-id"): true, // destructive comment-key alias paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role diff --git a/internal/app/root_help_test.go b/internal/app/root_help_test.go index 0f1b2045..f688c984 100644 --- a/internal/app/root_help_test.go +++ b/internal/app/root_help_test.go @@ -264,7 +264,7 @@ func TestRootChatMediaUploadWithoutAppCredentialsReturnsMigrationValidation(t *t } got := output.String() + "\n" + err.Error() - for _, want := range []string{"已下线", "chat message send --msg-type file --file-path"} { + for _, want := range []string{"已下线", "chat message send --msg-type file --file"} { if !strings.Contains(got, want) { t.Fatalf("chat media upload migration output missing %q:\n%s", want, got) } @@ -439,7 +439,7 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) { t.Fatalf("chat file upload error = nil, want downline error\n%s", got) } got = got + "\n" + err.Error() - for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file-path"} { + for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file"} { if !strings.Contains(got, want) { t.Fatalf("chat file upload output missing %q:\n%s", want, got) } diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index fc5b2840..ad82e6db 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -2450,14 +2450,14 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat +messages-reply", Aliases: map[string]string{ - "chat": "conversation-id", - "chat-id": "conversation-id", + "chat": "group", + "chat-id": "group", "msg-id": "ref-msg-id", - "open-conversation-id": "conversation-id", + "open-conversation-id": "group", "open-message-id": "ref-msg-id", "ref-message-id": "ref-msg-id", }, - Blocked: []string{"conversation-ids", "dest-conversation-id", "group", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, + Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-ids", "msg-ids", "name", "open-conversation-ids", "open-message-ids", "source", "src-conversation-id", "src-msg-id", "target"}, }, { CLIPath: "chat +messages-resource-download", @@ -3205,10 +3205,9 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message reply", Aliases: map[string]string{ - "chat": "conversation-id", - "chat-id": "conversation-id", - "group": "conversation-id", - "open-conversation-id": "conversation-id", + "chat": "group", + "chat-id": "group", + "open-conversation-id": "group", "ref-message-id": "ref-msg-id", }, Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "message-id", "msg-id", "msg-ids", "name", "open-conversation-ids", "open-message-id", "source", "src-conversation-id", "src-msg-id", "staff-id", "target", "uid", "user", "user-id", "userid"}, @@ -3229,7 +3228,6 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "chat message send", Aliases: map[string]string{ - "file": "file-path", "staff-id": "user", "to-user": "user", "uid": "user", @@ -3701,8 +3699,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc +doc-append", Aliases: map[string]string{ - "body": "text", - "content": "text", + "body": "content", "dentry-uuid": "doc", "doc-id": "doc", "document-id": "doc", @@ -4164,8 +4161,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc block insert", Aliases: map[string]string{ - "body": "text", - "content": "text", + "body": "content", "dentry-uuid": "node", "doc": "node", "document-id": "node", @@ -4188,8 +4184,7 @@ var generatedParamAliases = []ParamAliasEntry{ { CLIPath: "doc block update", Aliases: map[string]string{ - "body": "text", - "content": "text", + "body": "content", "dentry-uuid": "node", "doc": "node", "document-id": "node", diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 2ea26e92..90570a9e 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -98,7 +98,7 @@ "contact +resolve-dept": {"bind": {"name": "search_query"}, "note": "The real --name is a department-name search keyword and carries the search_query concept on this shortcut."}, "contact +list-sub-depts": {"block": ["name", "query"], "note": "--dept is an integer department id; names and search queries require a separate resolution command"}, "contact +dept-members": {"bind": {"dept": "search_query"}, "scoped_aliases": {"name": "dept"}, "note": "The real --dept is a department-name search keyword; search spellings come from search_query, while --name remains command-scoped."}, - "chat message send": {"scoped_aliases": {"to-user": "user", "file": "file-path"}, "ambiguous": ["chat-id", "open-conversation-id"], "note": "Recipient and local-file-path aliases are exact to this command; obsolete file metadata flags remain unsupported. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, + "chat message send": {"scoped_aliases": {"to-user": "user"}, "ambiguous": ["chat-id", "open-conversation-id"], "note": "The recipient alias remains exact to this command. --file is the visible Primary and --file-path remains a command-owned typed compatibility alias; obsolete file metadata flags remain unsupported. Visible --conversation-id and legacy --group both remain executable outside the approved hidden-alias migration set."}, "chat +group-members": {"bind": {"group": "group_name"}, "note": "The real --group is a group-name search keyword on this shortcut, not an identifier."}, "chat +category-create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact shortcut."}, "chat category create": {"scoped_aliases": {"name": "title"}, "scope_strict": true, "note": "The reviewed name/title mapping preserves the category display-name value on this exact command."}, @@ -176,7 +176,7 @@ "chat +messages-forward-topic": {"scoped_aliases": {"src-open-conversation-id": "src-conversation-id", "source-conversation-id": "src-conversation-id", "dest-open-conversation-id": "dest-conversation-id", "target-conversation-id": "dest-conversation-id", "destination-conversation-id": "dest-conversation-id", "src-open-message-id": "src-msg-id", "source-message-id": "src-msg-id"}, "block": ["group-id", "group-ids", "msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "ambiguous": ["conversation-id", "open-conversation-id", "group", "chat", "chat-id", "id"], "scope_strict": true, "note": "Source and destination conversation roles and the source-message role remain explicit; role-free message IDs and list cardinality are not inferred."}, "chat +messages-list": {"scoped_aliases": {"start": "time"}, "block": ["before", "before-time", "end", "direction", "page-all", "count", "max", "max-results", "max-size", "page-size"], "scope_strict": true, "note": "start preserves the same boundary value; before/direction require multi-parameter or value transforms and page-all requires iteration. Native --conversation-id/--id/--size remain native."}, "chat +messages-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values, not openMessageId values."}, - "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["group", "msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The observed --group spelling carried a natural group name and is blocked. The only message role is the referenced message; plural IDs are not accepted, while --chat remains a CID alias and native --message-id stays native."}, + "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The visible --group carries the openConversationId; --conversation-id remains its command-owned typed compatibility alias, while the reviewed command-scoped concept preserves --chat/--chat-id/--open-conversation-id compatibility. The only message role is the referenced message, plural IDs are not accepted, and native --message-id stays native."}, "chat +messages-resource-download": {"block": ["download-dir"], "note": "--output may be a file or directory under workspace safety rules; a download directory cannot be assumed equivalent."}, "doc +access-change": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "scope_strict": true, "note": "Command-scoped compatibility published before the workspace/storage-space concept split: these spellings keep passing their value unchanged to this Doc command's --workspace flag and do not establish global equivalence with a numeric DingDrive storage space."}, "doc +access-grant": {"scoped_aliases": {"space": "workspace", "space-id": "workspace"}, "block": ["target-user-id", "target-user-ids", "user-id", "user-ids"], "ambiguous": ["target-user", "user", "users"], "scope_strict": true, "note": "The real --to accepts collaborator names and resolves them before granting access. Explicit ID spellings cannot be passed through unchanged, while role-free user spellings do not prove whether their values are names or IDs. The command-scoped --space/--space-id aliases preserve previously published Doc workspace compatibility without making workspace and numeric DingDrive storage-space values globally equivalent."}, @@ -276,7 +276,7 @@ {"command": "aitable +field-get", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8}, {"command": "aitable +record-query", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8}, {"command": "aitable +table-get", "emitted": "base", "expect": "base-id", "via": "concept:base_id+morph", "occ": 8}, - {"command": "doc block update", "emitted": "content", "expect": "text", "via": "concept:content_text", "occ": 6}, + {"command": "doc block update", "emitted": "text", "expect": "content", "via": "native:reviewed-compatibility-alias", "occ": 6}, {"command": "contact +resolve-dept", "emitted": "query", "expect": "name", "via": "concept:search_query+bind", "occ": 4}, {"command": "devdoc article search", "emitted": "limit", "expect": "size", "via": "concept:pagination_size", "occ": 2}, {"command": "devdoc article search", "emitted": "page-size", "expect": "size", "via": "concept:pagination_size", "occ": 2}, @@ -296,7 +296,7 @@ {"command": "chat message list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size", "occ": 2}, {"command": "chat message list-by-sender", "emitted": "time", "expect": "did-you-mean:blocked", "via": "guard:time-format-boundary", "occ": 2}, {"command": "doc +template-search", "emitted": "keyword", "expect": "query", "via": "concept:search_query", "occ": 2}, - {"command": "doc block insert", "emitted": "content", "expect": "text", "via": "concept:content_text", "occ": 2}, + {"command": "doc block insert", "emitted": "text", "expect": "content", "via": "native:reviewed-compatibility-alias", "occ": 2}, {"command": "drive list", "emitted": "folder-id", "expect": "folder", "via": "concept:folder_id+morph", "occ": 2}, {"command": "mail thread list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size", "occ": 2}, {"command": "mail user search", "emitted": "query", "expect": "keyword", "via": "concept:search_query", "occ": 2}, @@ -394,7 +394,7 @@ {"command": "chat message list-by-sender", "emitted": "open-dingtalk-id", "expect": "sender-open-dingtalk-id", "via": "override:scoped-role"}, {"command": "chat category create-smart", "emitted": "title", "expect": "name", "via": "override:scoped"}, {"command": "chat category create", "emitted": "name", "expect": "title", "via": "override:scoped"}, - {"command": "chat message send", "emitted": "file", "expect": "file-path", "via": "override:scoped"}, + {"command": "chat message send", "emitted": "file-path", "expect": "file", "via": "native:reviewed-compatibility-alias"}, {"command": "chat category add-conv", "emitted": "category-id", "expect": "did-you-mean:blocked", "via": "override:block-cardinality"}, {"command": "chat category rename", "emitted": "category-ids", "expect": "did-you-mean:blocked", "via": "override:block-cardinality"}, {"command": "chat group-role set-user", "emitted": "role-id", "expect": "did-you-mean:blocked", "via": "override:block-cardinality"}, @@ -436,7 +436,7 @@ {"command": "doc update", "emitted": "version", "expect": "did-you-mean:blocked", "via": "guard:historical-version-vs-edit-revision"}, {"command": "doc +share-doc", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"}, {"command": "doc +comment-create", "emitted": "body", "expect": "content", "via": "concept:content_text"}, - {"command": "doc +doc-append", "emitted": "content", "expect": "text", "via": "concept:content_text"}, + {"command": "doc +doc-append", "emitted": "text", "expect": "content", "via": "native:reviewed-compatibility-alias"}, {"command": "doc +export-submit", "emitted": "doc-id", "expect": "node", "via": "concept:doc_node_id"}, {"command": "doc +move", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"}, {"command": "doc +template-list", "emitted": "next-token", "expect": "cursor", "via": "concept:page_cursor"}, @@ -476,8 +476,9 @@ {"command": "chat +messages-list", "emitted": "max-results", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"}, {"command": "chat +messages-list", "emitted": "page-all", "expect": "did-you-mean:blocked", "via": "guard:requires-pagination-loop"}, {"command": "chat +messages-reply", "emitted": "msg-id", "expect": "ref-msg-id", "via": "override:scoped-reference-message"}, - {"command": "chat +messages-reply", "emitted": "group", "expect": "did-you-mean:blocked", "via": "guard:group-name-vs-open-conversation-id"}, - {"command": "chat +messages-reply", "emitted": "chat", "expect": "conversation-id", "via": "concept:open_conversation_id"}, + {"command": "chat +messages-reply", "emitted": "conversation-id", "expect": "group", "via": "native:reviewed-compatibility-alias"}, + {"command": "chat +messages-reply", "emitted": "chat", "expect": "group", "via": "concept:open_conversation_id"}, + {"command": "chat +messages-reply", "emitted": "open-conversation-id", "expect": "group", "via": "concept:open_conversation_id"}, {"command": "chat +flag-cancel", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"}, {"command": "chat +flag-cancel", "emitted": "chat", "expect": "conversation-id", "via": "concept:open_conversation_id"}, {"command": "chat +flag-create", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"}, diff --git a/internal/cli/primary_param_schema_governance_test.go b/internal/cli/primary_param_schema_governance_test.go new file mode 100644 index 00000000..f63f5c85 --- /dev/null +++ b/internal/cli/primary_param_schema_governance_test.go @@ -0,0 +1,242 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); + +package cli + +import "testing" + +func TestPrimaryParamMigrationKeepsConceptDirectionCommandScoped(t *testing.T) { + concepts, err := LoadParamConcepts() + if err != nil { + t.Fatalf("LoadParamConcepts() error = %v", err) + } + if got := concepts.ByConcept["content_text"].CanonicalHint; got != "text" { + t.Fatalf("content_text canonical hint = %q, want unchanged global hint text", got) + } + if got := concepts.ByConcept["open_conversation_id"].CanonicalHint; got != "conversation-id" { + t.Fatalf("open_conversation_id canonical hint = %q, want unchanged global hint conversation-id", got) + } + + content := concepts.ByConcept["content_text"] + docNode := concepts.ByConcept["doc_node_id"] + docAppend, problems := reduceLeafParamAliases( + "doc +doc-append", + realMap( + realFlag{name: "content"}, + realFlag{name: "text", hidden: true}, + realFlag{name: "doc"}, + ), + []Concept{content, docNode}, + CommandOverride{}, + ) + if len(problems) != 0 { + t.Fatalf("doc +doc-append reduction problems = %v", problems) + } + assertPrimaryParamAlias(t, docAppend, "body", "content") + assertPrimaryParamAlias(t, docAppend, "node", "doc") + + insertOverride := primaryParamOverride(t, concepts, "doc block insert") + docInsert, problems := reduceLeafParamAliases( + "doc block insert", + realMap( + realFlag{name: "content"}, + realFlag{name: "text", hidden: true}, + realFlag{name: "parent-block"}, + realFlag{name: "ref-block"}, + ), + []Concept{content}, + insertOverride, + ) + if len(problems) != 0 { + t.Fatalf("doc block insert reduction problems = %v", problems) + } + assertPrimaryParamAlias(t, docInsert, "body", "content") + + docUpdate, problems := reduceLeafParamAliases( + "doc block update", + realMap(realFlag{name: "content"}, realFlag{name: "text", hidden: true}), + []Concept{content}, + CommandOverride{}, + ) + if len(problems) != 0 { + t.Fatalf("doc block update reduction problems = %v", problems) + } + assertPrimaryParamAlias(t, docUpdate, "body", "content") + + replyOverride := primaryParamOverride(t, concepts, "chat +messages-reply") + chatReply, problems := reduceLeafParamAliases( + "chat +messages-reply", + realMap( + realFlag{name: "group"}, + realFlag{name: "conversation-id", hidden: true}, + realFlag{name: "ref-msg-id"}, + ), + []Concept{concepts.ByConcept["open_conversation_id"]}, + replyOverride, + ) + if len(problems) != 0 { + t.Fatalf("chat +messages-reply reduction problems = %v", problems) + } + for _, emitted := range []string{"chat", "chat-id", "open-conversation-id"} { + assertPrimaryParamAlias(t, chatReply, emitted, "group") + } + assertPrimaryParamAlias(t, chatReply, "msg-id", "ref-msg-id") + if chatReply.IsBlocked("group") { + t.Fatal("chat +messages-reply canonical --group must not remain blocked") + } +} + +func TestPrimaryParamMigrationUpdatesReviewedFixturesAndMappingKeys(t *testing.T) { + concepts, err := LoadParamConcepts() + if err != nil { + t.Fatalf("LoadParamConcepts() error = %v", err) + } + fixtures := []ParamFixtureCase{ + {Command: "doc +doc-append", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias"}, + {Command: "doc +doc-append", Emitted: "node", Expect: "doc", Via: "concept:doc_node_id"}, + {Command: "doc block insert", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 2}, + {Command: "doc block update", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 6}, + {Command: "chat message send", Emitted: "file-path", Expect: "file", Via: "native:reviewed-compatibility-alias"}, + {Command: "chat +messages-reply", Emitted: "conversation-id", Expect: "group", Via: "native:reviewed-compatibility-alias"}, + {Command: "chat +messages-reply", Emitted: "chat", Expect: "group", Via: "concept:open_conversation_id"}, + {Command: "chat +messages-reply", Emitted: "open-conversation-id", Expect: "group", Via: "concept:open_conversation_id"}, + } + for _, want := range fixtures { + found := false + for _, got := range concepts.Fixture { + if got == want { + found = true + break + } + } + if !found { + t.Errorf("reviewed fixture missing %#v", want) + } + } + + tests := []struct { + oldKey string + newKey string + reason string + }{ + {"chat.reply_personal_message --text", "chat.reply_personal_message --content", "serialized into the aggregate content JSON string"}, + {"chat.send_personal_message --file-path", "chat.send_personal_message --file", "local upload/preprocessing input"}, + {"chat.send_personal_message --text", "chat.send_personal_message --content", "serialized into the aggregate content payload"}, + {"doc.insert_document_block --text", "doc.insert_document_block --content", "aggregate convenience input used to build element"}, + {"doc.update_document_block --text", "doc.update_document_block --content", "aggregate convenience input used to build element"}, + {"todo.add_todo_attachment --file-path", "todo.add_todo_attachment --file", "local upload input used to construct attachmentList"}, + } + for _, test := range tests { + if _, exists := reviewedSchemaParameterMappingExclusions[test.oldKey]; exists { + t.Errorf("stale mapping exclusion remains at %q", test.oldKey) + } + if got := reviewedSchemaParameterMappingExclusions[test.newKey]; got != test.reason { + t.Errorf("mapping exclusion %q reason = %q, want %q", test.newKey, got, test.reason) + } + } +} + +func TestPrimaryParamMigrationPreservesDeliverySchemaSignatures(t *testing.T) { + tests := []struct { + path string + primary string + legacy string + required bool + cliRequired bool + property string + propertyFrom string + format string + requiredWhen string + requiredWhenFrom string + }{ + {path: "aisearch person", primary: "query", legacy: "keyword", required: true, property: "keyword", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat message reply", primary: "content", legacy: "text", required: true, cliRequired: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"}, + {path: "chat message send", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"}, + {path: "chat message send", primary: "file", legacy: "file-path", propertyFrom: "reviewed_mapping_exclusion", format: "file-path", requiredWhen: "msg-type is file or audio or video", requiredWhenFrom: "typed_parameter_metadata"}, + {path: "chat message send-by-webhook", primary: "content", legacy: "text", required: true, cliRequired: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +broadcast", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +dm", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +send-to-group", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +messages-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +messages-batch-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +messages-send-by-webhook", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +messages-reply", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "chat +messages-reply", primary: "group", legacy: "conversation-id", required: true, property: "conversationId", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "doc +doc-append", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"}, + {path: "doc block insert", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"}, + {path: "doc block update", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"}, + {path: "todo task add-attachment", primary: "file", legacy: "file-path", required: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"}, + } + for _, test := range tests { + t.Run(test.path+"/"+test.primary, func(t *testing.T) { + leaf, err := queryDeliverySchemaPayload([]string{test.path}) + if err != nil { + t.Fatal(err) + } + parameters := schemaMap(leaf["parameters"]) + parameter, exists := parameters[test.primary] + if !exists { + t.Fatalf("%s missing visible Primary --%s", test.path, test.primary) + } + if _, exists := parameters[test.legacy]; exists { + t.Fatalf("%s unexpectedly publishes hidden legacy --%s", test.path, test.legacy) + } + if got := parameter["type"]; got != "string" { + t.Errorf("%s --%s type = %#v, want string", test.path, test.primary, got) + } + if got := parameter["required"]; got != test.required { + t.Errorf("%s --%s required = %#v, want %v", test.path, test.primary, got, test.required) + } + if got, _ := parameter["cli_required"].(bool); got != test.cliRequired { + t.Errorf("%s --%s cli_required = %#v, want %v", test.path, test.primary, parameter["cli_required"], test.cliRequired) + } + if got, _ := parameter["property"].(string); got != test.property { + t.Errorf("%s --%s property = %q, want %q", test.path, test.primary, got, test.property) + } + if got := parameter["interface_type"]; got != nil && got != "" { + t.Errorf("%s --%s interface_type = %#v, want omitted/empty", test.path, test.primary, got) + } + if got, _ := parameter["format"].(string); got != test.format { + t.Errorf("%s --%s format = %q, want %q", test.path, test.primary, got, test.format) + } + if got, _ := parameter["required_when"].(string); got != test.requiredWhen { + t.Errorf("%s --%s required_when = %q, want %q", test.path, test.primary, got, test.requiredWhen) + } + + provenance := schemaMap(parameter["field_provenance"]) + propertyProvenance := provenance["property"] + if got := propertyProvenance["source"]; got != test.propertyFrom { + t.Errorf("%s --%s property source = %#v, want %s", test.path, test.primary, got, test.propertyFrom) + } + typeProvenance := provenance["type"] + if got := typeProvenance["source"]; got != "cobra_flag_type" { + t.Errorf("%s --%s type source = %#v, want cobra_flag_type", test.path, test.primary, got) + } + requiredWhenProvenance := provenance["required_when"] + if got := requiredWhenProvenance["source"]; got != test.requiredWhenFrom { + t.Errorf("%s --%s required_when source = %#v, want %s", test.path, test.primary, got, test.requiredWhenFrom) + } + }) + } +} + +func primaryParamOverride(t *testing.T, concepts ParamConcepts, path string) CommandOverride { + t.Helper() + for _, override := range concepts.Overrides { + if override.CommandPath == path { + return override + } + } + t.Fatalf("command override %q not found", path) + return CommandOverride{} +} + +func assertPrimaryParamAlias(t *testing.T, entry *ParamAliasEntry, emitted, want string) { + t.Helper() + if entry == nil { + t.Fatalf("alias entry is nil; want %s -> %s", emitted, want) + } + if got, ok := entry.ResolveAlias(emitted); !ok || got != want { + t.Fatalf("ResolveAlias(%q) = %q (ok=%v), want %q", emitted, got, ok, want) + } +} diff --git a/internal/cli/schema_constraints_runtime.go b/internal/cli/schema_constraints_runtime.go index 397a6708..423528d6 100644 --- a/internal/cli/schema_constraints_runtime.go +++ b/internal/cli/schema_constraints_runtime.go @@ -68,9 +68,9 @@ func init() { registerRequireOneOf("devdoc.search_open_platform_docs_rag", "query", "keyword") registerRequireOneOf("event.consume", "event_key", "subscribe-id") registerExclusiveOneOf("event.stop", "all", "subscribe_id") - registerRequireOneOf("doc.insert_document_block", "text", "heading", "element") + registerRequireOneOf("doc.insert_document_block", "content", "heading", "element") registerExclusiveOneOf("doc.update_document", "content", "content-file") - registerRequireOneOf("doc.update_document_block", "text", "heading", "element") + registerRequireOneOf("doc.update_document_block", "content", "heading", "element") registerRequireOneOf("pat.batch_grant", "scope", "product", "products", "domain", "domains", "recommend") registerRequireOneOf("mail.search_mail_users", "keyword", "employee-no") // --body is a hidden compatibility alias for the public --content flag. diff --git a/internal/cli/schema_parameter_mapping_ledger.go b/internal/cli/schema_parameter_mapping_ledger.go index a68844f7..b9e0263a 100644 --- a/internal/cli/schema_parameter_mapping_ledger.go +++ b/internal/cli/schema_parameter_mapping_ledger.go @@ -269,20 +269,20 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "chat.update_text_emotion --conversation-id": "Reviewed unpinned adapter: chat.update_text_emotion has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.", "chat.reply_personal_message --ref-msg-id": "serialized into the aggregate content JSON string", "chat.reply_personal_message --ref-sender": "resolved then serialized into the aggregate content JSON string", - "chat.reply_personal_message --text": "serialized into the aggregate content JSON string", + "chat.reply_personal_message --content": "serialized into the aggregate content JSON string", "chat.search_groups --cursor": "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.", "chat.search_groups --exclude-muted": "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --exclude-muted is a CLI wrapper input and does not publish a direct interface property.", "chat.search_groups --limit": "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.", "chat.search_messages --user": "conditional wrapper: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag", "chat.search_messages --users": "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag", "chat.send_personal_message --contact-id": "serialized into the aggregate content payload", - "chat.send_personal_message --file-path": "local upload/preprocessing input", + "chat.send_personal_message --file": "local upload/preprocessing input", "chat.send_personal_message --latitude": "serialized into the aggregate content payload", "chat.send_personal_message --location-name": "serialized into the aggregate content payload", "chat.send_personal_message --longitude": "serialized into the aggregate content payload", "chat.send_personal_message --map-thumbnail-url": "serialized into the aggregate content payload", "chat.send_personal_message --media-id": "serialized into the aggregate content payload", - "chat.send_personal_message --text": "serialized into the aggregate content payload", + "chat.send_personal_message --content": "serialized into the aggregate content payload", "chat.send_personal_message --title": "serialized into the aggregate content payload", "chat.send_personal_message --user": "resolves a userId to receiverOpenDingTalkId when possible and otherwise uses the unpinned receiverUserId compatibility property", "chat.set_group_member_mute_list --user": "conditional wrapper/alias of --users: userIds are remotely resolved to openDingTalkIds outside dry-run and otherwise may be sent as uids; openDingTalkId inputs are sent as openDingTalkIds, so one exact property would misdescribe execution", @@ -406,7 +406,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "doc.insert_document_block --fix-jsonml": "local JSONML normalization control", "doc.insert_document_block --heading": "aggregate convenience input used to build element", "doc.insert_document_block --level": "aggregate convenience input used to build element", - "doc.insert_document_block --text": "aggregate convenience input used to build element", + "doc.insert_document_block --content": "aggregate convenience input used to build element", "doc.list_document_blocks --block-id": "runtime extension sends blockId, which is absent from the pinned list_document_blocks metadata", "doc.reply_comment --mentioned-open-conversation-id": "Runtime extension sends mentionedOpenConversationIds, which is absent from the immutable pinned reply_comment metadata at its declared source revision.", "doc.style_background_clear --node": "Reviewed unpinned adapter: doc.style_background_clear has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.", @@ -438,7 +438,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "doc.update_document_block --fix-jsonml": "local JSONML normalization control", "doc.update_document_block --heading": "aggregate convenience input used to build element", "doc.update_document_block --level": "aggregate convenience input used to build element", - "doc.update_document_block --text": "aggregate convenience input used to build element", + "doc.update_document_block --content": "aggregate convenience input used to build element", "doc.version_list --cursor": "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.", "doc.version_list --limit": "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.", "doc.version_list --node": "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.", @@ -659,7 +659,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{ "sheet.write_image --file": "local upload input used to obtain resourceId/resourceUrl", "sheet.write_image --mime-type": "local upload metadata", "sheet.write_image --name": "local upload metadata", - "todo.add_todo_attachment --file-path": "local upload input used to construct attachmentList", + "todo.add_todo_attachment --file": "local upload input used to construct attachmentList", "todo.get_user_todos_in_current_org --query-all": "Local route selector: the default path calls get_user_todos_in_current_org, while --query-all switches to get_user_todos; it is not a property of the pinned default RPC.", "todo.list_todo_attachment --task-id": "Reviewed unpinned adapter: --task-id is nested under todoAttachmentListRequest at runtime, while the immutable pinned MCP snapshot has no interface_ref for todo.list_todo_attachment.", "wiki.create_wikiSpace --icon": "runtime extension sends icon, which is absent from the pinned create_wikiSpace metadata", diff --git a/internal/cli/schema_parameters_runtime.go b/internal/cli/schema_parameters_runtime.go index 9f7ab19b..ff8d4b8c 100644 --- a/internal/cli/schema_parameters_runtime.go +++ b/internal/cli/schema_parameters_runtime.go @@ -77,7 +77,7 @@ func cloneRuntimeSchemaStringMap(source map[string]string) map[string]string { func init() { RegisterRuntimeSchemaParameterMetadata("aisearch.enterprise_person_search", RuntimeSchemaParameterMetadata{ - Required: []string{"keyword"}, + Required: []string{"query"}, }) RegisterRuntimeSchemaParameterMetadata("aitable.export_data", RuntimeSchemaParameterMetadata{ RequiredWhen: map[string]string{ @@ -146,8 +146,8 @@ func init() { }) RegisterRuntimeSchemaParameterMetadata("chat.send_personal_message", RuntimeSchemaParameterMetadata{ RequiredWhen: map[string]string{ - "media-id": "msg-type is image", - "file-path": "msg-type is file or audio or video", + "media-id": "msg-type is image", + "file": "msg-type is file or audio or video", }, Examples: map[string]string{"media-id": "@lADP_schema_smoke"}, }) diff --git a/internal/helpers/primary_param_native_compat_test.go b/internal/helpers/primary_param_native_compat_test.go new file mode 100644 index 00000000..8ea171a3 --- /dev/null +++ b/internal/helpers/primary_param_native_compat_test.go @@ -0,0 +1,434 @@ +// Copyright 2026 Alibaba Group +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. + +package helpers + +import ( + "context" + "encoding/json" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" + "github.com/spf13/cobra" +) + +type nativePrimaryParamCall struct { + server string + tool string + args map[string]any +} + +type nativePrimaryParamCaller struct { + calls []nativePrimaryParamCall +} + +func (c *nativePrimaryParamCaller) CallTool(_ context.Context, server, tool string, args map[string]any) (*edition.ToolResult, error) { + copied := make(map[string]any, len(args)) + for key, value := range args { + copied[key] = value + } + c.calls = append(c.calls, nativePrimaryParamCall{server: server, tool: tool, args: copied}) + + switch tool { + case "init_conversation_file_upload", "init_todo_file_upload": + return textToolResult(`{"resourceUrl":"https://upload.invalid/file","uploadKey":"upload-key"}`), nil + case "commit_conversation_file_upload": + fileName, _ := args["fileName"].(string) + payload, _ := json.Marshal(map[string]any{ + "dentryId": 123, + "spaceId": 456, + "downloadUrl": "https://download.invalid/" + fileName, + }) + return textToolResult(string(payload)), nil + case "commit_todo_file_upload": + return textToolResult(`{"dentryId":123,"spaceId":456}`), nil + default: + return textToolResult(`{}`), nil + } +} + +func (*nativePrimaryParamCaller) Format() string { return "json" } +func (*nativePrimaryParamCaller) DryRun() bool { return false } +func (*nativePrimaryParamCaller) Fields() string { return "" } +func (*nativePrimaryParamCaller) JQ() string { return "" } + +func (c *nativePrimaryParamCaller) lastCall(t *testing.T, tool string) nativePrimaryParamCall { + t.Helper() + for i := len(c.calls) - 1; i >= 0; i-- { + if c.calls[i].tool == tool { + return c.calls[i] + } + } + t.Fatalf("tool %q not called; calls = %#v", tool, c.calls) + return nativePrimaryParamCall{} +} + +func executeNativePrimaryTodo(t *testing.T, caller edition.ToolCaller, args ...string) error { + t.Helper() + previousDeps, previousArgs := deps, os.Args + os.Args = []string{"dws", "todo"} + InitDeps(caller) + deps.Out.w = io.Discard + deps.Out.errW = io.Discard + t.Cleanup(func() { + deps = previousDeps + os.Args = previousArgs + }) + + cmd := newTodoCommand() + if cmd.PersistentFlags().Lookup("yes") == nil { + cmd.PersistentFlags().Bool("yes", false, "confirm execution") + } + if cmd.PersistentFlags().Lookup("dry-run") == nil { + cmd.PersistentFlags().Bool("dry-run", false, "preview without executing") + } + cmd.SilenceErrors = true + cmd.SilenceUsage = true + cmd.SetOut(io.Discard) + cmd.SetErr(io.Discard) + cmd.SetArgs(args) + return cmd.ExecuteContext(context.Background()) +} + +func findNativePrimaryLeaf(t *testing.T, root *cobra.Command, path ...string) *cobra.Command { + t.Helper() + leaf, remaining, err := root.Find(path) + if err != nil { + t.Fatalf("find %v: %v", path, err) + } + if len(remaining) != 0 { + t.Fatalf("find %v left arguments %v", path, remaining) + } + return leaf +} + +func assertNativePrimaryFlagPair(t *testing.T, cmd *cobra.Command, primary, legacy string) { + t.Helper() + primaryFlag := cmd.Flags().Lookup(primary) + if primaryFlag == nil || primaryFlag.Hidden { + t.Fatalf("%s --%s = %#v, want visible Primary", cmd.CommandPath(), primary, primaryFlag) + } + legacyFlag := cmd.Flags().Lookup(legacy) + if legacyFlag == nil || !legacyFlag.Hidden { + t.Fatalf("%s --%s = %#v, want hidden compatibility alias", cmd.CommandPath(), legacy, legacyFlag) + } + if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != primary { + t.Fatalf("%s --%s alias_of = %#v, want %q", cmd.CommandPath(), legacy, got, primary) + } + if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 { + t.Fatalf("%s --%s alias_origin = %#v, want %q", cmd.CommandPath(), legacy, got, runtimeannotate.FlagAliasOriginCorecmdV1) + } +} + +func TestNativePrimaryParamFlagSurfaces(t *testing.T) { + aisearch := newAisearchCommand() + assertNativePrimaryFlagPair(t, aisearch, "query", "keyword") + person := findNativePrimaryLeaf(t, aisearch, "person") + assertNativePrimaryFlagPair(t, person, "query", "keyword") + for _, cmd := range []*cobra.Command{aisearch, person} { + if got := cmd.Flags().Lookup("keyword").Shorthand; got != "w" { + t.Fatalf("%s --keyword shorthand = %q, want preserved -w", cmd.CommandPath(), got) + } + if got := cmd.Flags().Lookup("query").Shorthand; got != "" { + t.Fatalf("%s --query shorthand = %q, want none", cmd.CommandPath(), got) + } + } + + chat := newChatCommand() + send := findNativePrimaryLeaf(t, chat, "message", "send") + assertNativePrimaryFlagPair(t, send, "content", "text") + assertNativePrimaryFlagPair(t, send, "file", "file-path") + sendByWebhook := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook") + assertNativePrimaryFlagPair(t, sendByWebhook, "content", "text") + reply := findNativePrimaryLeaf(t, chat, "message", "reply") + assertNativePrimaryFlagPair(t, reply, "group", "conversation-id") + assertNativePrimaryFlagPair(t, reply, "content", "text") + + doc := newDocCommand() + assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "insert"), "content", "text") + assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "update"), "content", "text") + + todo := newTodoCommand() + assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, todo, "task", "add-attachment"), "file", "file-path") +} + +type nativePrimaryParamSpelling struct { + name string + args []string + want string +} + +func nativePrimaryParamSpellings(primary, legacy string) []nativePrimaryParamSpelling { + return []nativePrimaryParamSpelling{ + {name: "legacy only", args: []string{"--" + legacy, "legacy-value"}, want: "legacy-value"}, + {name: "primary only", args: []string{"--" + primary, "primary-value"}, want: "primary-value"}, + {name: "both legacy wins", args: []string{"--" + primary, "primary-value", "--" + legacy, "legacy-value"}, want: "legacy-value"}, + } +} + +func nativePrimaryJSONField(t *testing.T, raw any, field string) string { + t.Helper() + encoded, ok := raw.(string) + if !ok { + t.Fatalf("payload = %#v, want JSON string", raw) + } + var payload map[string]any + if err := json.Unmarshal([]byte(encoded), &payload); err != nil { + t.Fatalf("decode payload %q: %v", encoded, err) + } + value, _ := payload[field].(string) + return value +} + +func nativePrimaryParagraphText(t *testing.T, call nativePrimaryParamCall) string { + t.Helper() + element, ok := call.args["element"].(map[string]any) + if !ok { + t.Fatalf("%s element = %#v", call.tool, call.args["element"]) + } + paragraph, ok := element["paragraph"].(map[string]any) + if !ok { + t.Fatalf("%s paragraph = %#v", call.tool, element["paragraph"]) + } + text, _ := paragraph["text"].(string) + return text +} + +func TestNativePrimaryParamTextPayloadCompatibility(t *testing.T) { + previousDeps, previousArgs := deps, os.Args + os.Args = []string{"dws", "chat"} + t.Cleanup(func() { + deps = previousDeps + os.Args = previousArgs + }) + + t.Run("chat message send text to content", func(t *testing.T) { + for _, spelling := range nativePrimaryParamSpellings("content", "text") { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"message", "send", "--group", "cid", "--title", "fixed-title"} + args = append(args, spelling.args...) + if err := runChatCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "send_personal_message") + if got := nativePrimaryJSONField(t, call.args["content"], "text"); got != spelling.want { + t.Fatalf("content.text = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + + t.Run("chat message send-by-webhook text to content", func(t *testing.T) { + for _, spelling := range nativePrimaryParamSpellings("content", "text") { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"message", "send-by-webhook", "--token", "token", "--title", "fixed-title"} + args = append(args, spelling.args...) + if err := runChatCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "send_message_by_custom_robot") + if got, _ := call.args["text"].(string); got != spelling.want { + t.Fatalf("text = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + + t.Run("chat message reply conversation-id to group", func(t *testing.T) { + for _, spelling := range nativePrimaryParamSpellings("group", "conversation-id") { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"message", "reply", "--ref-msg-id", "mid", "--ref-sender", "D-sender", "--content", "fixed-content"} + args = append(args, spelling.args...) + if err := runChatCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "send_personal_message") + if got, _ := call.args["openConversationId"].(string); got != spelling.want { + t.Fatalf("openConversationId = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + + t.Run("chat message reply text to content", func(t *testing.T) { + for _, spelling := range nativePrimaryParamSpellings("content", "text") { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", "D-sender"} + args = append(args, spelling.args...) + if err := runChatCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "send_personal_message") + if got := nativePrimaryJSONField(t, call.args["content"], "content"); got != spelling.want { + t.Fatalf("reply content = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + + for _, command := range []struct { + name string + path []string + tool string + }{ + {name: "doc block insert text to content", path: []string{"block", "insert", "--node", "node"}, tool: "insert_document_block"}, + {name: "doc block update text to content", path: []string{"block", "update", "--node", "node", "--block-id", "block"}, tool: "update_document_block"}, + } { + command := command + t.Run(command.name, func(t *testing.T) { + for _, spelling := range nativePrimaryParamSpellings("content", "text") { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := append(append([]string(nil), command.path...), spelling.args...) + if err := runDocCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, command.tool) + if got := nativePrimaryParagraphText(t, call); got != spelling.want { + t.Fatalf("paragraph text = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + } +} + +func TestNativePrimaryParamFilePayloadCompatibility(t *testing.T) { + previousDeps, previousPut, previousArgs := deps, httpPutFile, os.Args + t.Cleanup(func() { + deps = previousDeps + httpPutFile = previousPut + os.Args = previousArgs + }) + httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil } + + dir := t.TempDir() + legacyPath := filepath.Join(dir, "legacy-file.txt") + primaryPath := filepath.Join(dir, "primary-file.txt") + if err := os.WriteFile(legacyPath, []byte("legacy"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(primaryPath, []byte("primary"), 0o600); err != nil { + t.Fatal(err) + } + spellings := []nativePrimaryParamSpelling{ + {name: "legacy only", args: []string{"--file-path", legacyPath}, want: filepath.Base(legacyPath)}, + {name: "primary only", args: []string{"--file", primaryPath}, want: filepath.Base(primaryPath)}, + {name: "both legacy wins", args: []string{"--file", primaryPath, "--file-path", legacyPath}, want: filepath.Base(legacyPath)}, + } + + t.Run("chat message send file-path to file", func(t *testing.T) { + os.Args = []string{"dws", "chat"} + for _, spelling := range spellings { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"message", "send", "--group", "cid", "--msg-type", "file"} + args = append(args, spelling.args...) + if err := runChatCoverageCommand(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "send_personal_message") + if got := nativePrimaryJSONField(t, call.args["content"], "fileName"); got != spelling.want { + t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) + + t.Run("todo task add-attachment file-path to file", func(t *testing.T) { + os.Args = []string{"dws", "todo"} + for _, spelling := range spellings { + t.Run(spelling.name, func(t *testing.T) { + caller := &nativePrimaryParamCaller{} + args := []string{"task", "add-attachment", "--task-id", "42"} + args = append(args, spelling.args...) + if err := executeNativePrimaryTodo(t, caller, args...); err != nil { + t.Fatal(err) + } + call := caller.lastCall(t, "add_todo_attachment") + request, ok := call.args["todoAttachmentAddRequest"].(map[string]any) + if !ok { + t.Fatalf("request = %#v", call.args) + } + attachments, ok := request["attachmentList"].([]any) + if !ok || len(attachments) != 1 { + t.Fatalf("attachments = %#v", request["attachmentList"]) + } + attachment, ok := attachments[0].(map[string]any) + if !ok { + t.Fatalf("attachment = %#v", attachments[0]) + } + if got, _ := attachment["fileName"].(string); got != spelling.want { + t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args) + } + }) + } + }) +} + +func nativePrimaryErrorMentionsFlag(message, name string) bool { + return strings.Contains(message, "--"+name) || strings.Contains(message, fmt.Sprintf("%q", name)) +} + +func assertNativePrimaryErrorHint(t *testing.T, err error, primary, legacy string) { + t.Helper() + if err == nil { + t.Fatalf("missing --%s returned nil", primary) + } + message := err.Error() + if !nativePrimaryErrorMentionsFlag(message, primary) { + t.Fatalf("error %q does not recommend --%s", message, primary) + } + if nativePrimaryErrorMentionsFlag(message, legacy) { + t.Fatalf("error %q still recommends legacy --%s", message, legacy) + } +} + +func TestNativePrimaryParamMissingErrorsRecommendPrimaryOnly(t *testing.T) { + previousDeps, previousArgs := deps, os.Args + t.Cleanup(func() { + deps = previousDeps + os.Args = previousArgs + }) + + installScriptedCaller(t, &scriptedToolCaller{}) + assertNativePrimaryErrorHint(t, executeFilterCoverage(t, newAisearchCommand(), "person"), "query", "keyword") + + os.Args = []string{"dws", "chat"} + assertNativePrimaryErrorHint(t, + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send", "--group", "cid"), + "content", "text") + assertNativePrimaryErrorHint(t, + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send-by-webhook", "--token", "token", "--title", "title"), + "content", "text") + assertNativePrimaryErrorHint(t, + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--ref-msg-id", "mid", "--ref-sender", "D-sender", "--content", "body"), + "group", "conversation-id") + assertNativePrimaryErrorHint(t, + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", "D-sender"), + "content", "text") + + os.Args = []string{"dws", "doc"} + assertNativePrimaryErrorHint(t, + runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "insert", "--node", "node"), + "content", "text") + assertNativePrimaryErrorHint(t, + runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "update", "--node", "node", "--block-id", "block"), + "content", "text") + + os.Args = []string{"dws", "todo"} + assertNativePrimaryErrorHint(t, + executeTodoEdge(t, &scriptedToolCaller{}, "task", "add-attachment", "--task-id", "42"), + "file", "file-path") +} diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index fc66b357..6ddbafb7 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -1171,7 +1171,7 @@ "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1186,7 +1186,7 @@ "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1201,7 +1201,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1216,7 +1216,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1231,7 +1231,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1246,7 +1246,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1261,7 +1261,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1276,7 +1276,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1291,7 +1291,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1306,7 +1306,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1321,7 +1321,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "required": true, "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1336,7 +1336,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "required": true, "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1351,7 +1351,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1366,7 +1366,7 @@ "before": {"present": true, "type": "string", "hidden": true, "scope": "local"}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1411,7 +1411,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "required": true, "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1426,7 +1426,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1441,7 +1441,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1456,7 +1456,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." }, { @@ -1471,7 +1471,7 @@ "before": {"present": false}, "after": {"present": true, "type": "string", "scope": "local"} }, - "state": "pending", + "state": "consumed", "reason": "Preserve legacy argv compatibility while making the canonical flag the only visible parameter." } ] From 4fd67c52dca3ef927f6f5ff95e34ce5b7a3ca107 Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 11 Aug 2026 23:31:58 +0800 Subject: [PATCH 227/250] docs: update primary parameter guidance to #85349380 --- docs/shortcut-report.html | 2 +- docs/shortcut-report.md | 8 +- scripts/policy/check-skill-context-budget.sh | 1 + .../mono/references/best_practices/02-task.md | 4 +- .../references/best_practices/03-meeting.md | 2 +- .../references/best_practices/04-document.md | 6 +- .../references/best_practices/07-minutes.md | 4 +- .../10-minutes-speaker-match.md | 4 +- .../references/best_practices/lite-recipes.md | 8 +- skills/mono/references/intent-guide.md | 16 +-- skills/mono/references/products/aisearch.md | 18 +-- .../references/products/attendance-report.md | 2 +- .../products/attendance-schedule.md | 10 +- .../products/attendance-vacation.md | 4 +- skills/mono/references/products/calendar.md | 2 +- skills/mono/references/products/chat.md | 120 +++++++++--------- skills/mono/references/products/contact.md | 2 +- skills/mono/references/products/doc.md | 16 +-- .../mono/references/products/doc/doc-block.md | 18 +-- .../products/doc/style/doc-update-workflow.md | 2 +- skills/mono/references/products/drive.md | 4 +- skills/mono/references/products/mail.md | 6 +- skills/mono/references/products/oa.md | 18 +-- .../products/oa/oa-form-components.md | 2 +- .../products/oa/oa-process-nodes.md | 6 +- .../products/sheet/sheet-comment.md | 4 +- skills/mono/references/products/todo.md | 6 +- skills/multi/dingtalk-aisearch/SKILL.md | 18 +-- .../dingtalk-aisearch/references/aisearch.md | 18 +-- .../references/lite-recipes.md | 4 +- skills/multi/dingtalk-calendar/SKILL.md | 4 +- .../references/03-meeting.md | 2 +- .../dingtalk-calendar/references/calendar.md | 2 +- .../references/lite-recipes.md | 2 +- skills/multi/dingtalk-chat/SKILL.md | 4 +- .../dingtalk-chat/references/chat/chat-bot.md | 14 +- .../references/chat/chat-conversation.md | 6 +- .../references/chat/message-actions.md | 6 +- .../references/chat/message-media.md | 6 +- skills/multi/dingtalk-contact/SKILL.md | 6 +- .../references/08-directory.md | 4 +- .../dingtalk-contact/references/contact.md | 2 +- .../references/lite-recipes.md | 4 +- .../doc/style/doc-update-workflow.md | 2 +- skills/multi/dingtalk-mail/references/mail.md | 6 +- .../dingtalk-minutes/references/07-minutes.md | 6 +- .../references/10-minutes-speaker-match.md | 4 +- .../references/11-minutes-speaker-correct.md | 4 +- .../references/lite-recipes.md | 4 +- .../dingtalk-minutes/references/minutes.md | 24 ++-- .../dingtalk-misc/references/05-reporting.md | 2 +- .../references/attendance-report.md | 2 +- .../references/attendance-schedule.md | 10 +- .../references/attendance-vacation.md | 4 +- skills/multi/dingtalk-misc/references/ding.md | 10 +- skills/multi/dingtalk-misc/references/oa.md | 18 +-- .../references/oa/oa-form-components.md | 2 +- .../references/oa/oa-process-nodes.md | 6 +- .../references/report-lite-recipes.md | 2 +- .../multi/dingtalk-misc/references/report.md | 8 +- .../references/sheet/sheet-comment.md | 4 +- .../references/intent-guide.md | 20 +-- .../references/recipes/lite-catalog.md | 14 +- skills/multi/dingtalk-todo/SKILL.md | 2 +- .../multi/dingtalk-todo/references/02-task.md | 4 +- .../dingtalk-todo/references/lite-recipes.md | 6 +- skills/multi/dingtalk-todo/references/todo.md | 8 +- test/skill_tests.md | 20 +-- test/skill_tests_results.md | 8 +- 69 files changed, 299 insertions(+), 298 deletions(-) diff --git a/docs/shortcut-report.html b/docs/shortcut-report.html index 4905f9bf..92955672 100644 --- a/docs/shortcut-report.html +++ b/docs/shortcut-report.html @@ -102,7 +102,7 @@ minutes +latest-minutes列妙记→取最新一条详情编译/挂载 minutes +action-items列妙记→取最新→取其待办编译/挂载 wiki +wiki-new-doc --space <名>按名搜知识空间→建文档（跨 doc server 路由）编译/挂载 - doc +doc-append --doc --text文档末尾追加文本编译/挂载 + doc +doc-append --doc --content文档末尾追加文本编译/挂载 doc +share-doc --to <名> --url解析人→把文档链接私信 TA（跨服务）编译/挂载 diff --git a/docs/shortcut-report.md b/docs/shortcut-report.md index f516eac5..7a10da8b 100644 --- a/docs/shortcut-report.md +++ b/docs/shortcut-report.md @@ -56,13 +56,13 @@ | shortcut | 多步/智能逻辑 | 验证 | |----------|--------------|------| -| `chat +dm --to <姓名> --text` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 | +| `chat +dm --to <姓名> --content` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 | | `contact +lookup --name <姓名>` | 搜人→解析 userId→取完整资料 | ✅ **真机端到端** | | `todo +assign --to <姓名> --task` | 解析人→建待办并把 TA 设为执行人 | ✅ dry-run 真机 | -| `chat +send-to-group --group <群名> --text` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 | +| `chat +send-to-group --group <群名> --content` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 | | `calendar +book --title --start --end [--with <姓名CSV>]` | 建日程→按名加参与者→**失败回滚删日程**（对标 lark `calendar +create`） | ✅ dry-run 真机 | | `calendar +free --who <姓名> --start --end` | 解析人→查其时段忙闲 | ✅ **真机端到端**（解析 202397→查忙闲） | -| `chat +broadcast --to <姓名CSV> --text` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 | +| `chat +broadcast --to <姓名CSV> --content` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 | | `minutes +latest-minutes` | 列妙记→取最新一条详情 | ✅ 编译/挂载 | | `chat +group-members --group <群名>` | 按群名搜群→列群成员 | ✅ 编译/挂载 | | `contact +org --name <姓名>` | 解析人→取详情拿 deptId→查部门详情 | ✅ **真机端到端**（3 步：董鑫阳→模型算法/16人） | @@ -76,7 +76,7 @@ | `todo +todo-done --task <关键词>` | 列我的待办→按标题匹配→标记完成 | ✅ 编译/挂载 | | `calendar +reschedule --event ` | 查日程详情→改时间（查→改机械多步） | ✅ 编译/挂载 | | `wiki +wiki-new-doc --space <名>` | 按名搜知识空间→在其下建文档（跨 doc server 路由） | ✅ 编译/挂载 | -| `doc +doc-append --doc --text` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 | +| `doc +doc-append --doc --content` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 | | `minutes +action-items` | 列妙记→取最新→取其待办事项 | ✅ 编译/挂载 | | `minutes +detail --id ` | 一条命令聚合听记 basic/summary/keywords/transcript/todos，partial-failure 容错 | ✅ 全量测试 | | `minutes +replace-batch --id --pair "原文=>替换"…` | 多组批量替换文字，去重校验+逐组结果聚合 | ✅ 全量测试 | diff --git a/scripts/policy/check-skill-context-budget.sh b/scripts/policy/check-skill-context-budget.sh index f9d643dc..01d3ac5c 100755 --- a/scripts/policy/check-skill-context-budget.sh +++ b/scripts/policy/check-skill-context-budget.sh @@ -168,6 +168,7 @@ done for forbidden_route in \ "## 标准 SOP" \ "dws aisearch person --keyword" \ + "dws aisearch person --query" \ "dws chat message send-by-webhook" \ "dt_media_upload" \ "MUST 先用 Read" diff --git a/skills/mono/references/best_practices/02-task.md b/skills/mono/references/best_practices/02-task.md index 82aaf106..d4696485 100644 --- a/skills/mono/references/best_practices/02-task.md +++ b/skills/mono/references/best_practices/02-task.md @@ -15,5 +15,5 @@ | Recipe | 行动指南（固定路线） | |--------|---------------------| | generate-progress-report | 1. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行
2. 交叉比对各源数据
3. `doc create --name "<报告名>" --content "<报告内容>"` | -| batch-create-todo | 1. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --keyword "<姓名>" --dimension name` → 取 `userId`
3. **优先**：将待办写入 `todos.json`（格式见 [todo_batch_create.py](../../scripts/todo_batch_create.py)），执行 `python scripts/todo_batch_create.py todos.json`
备选：逐条 `todo task create --title "<标题>" --executors ` → 汇总回显
**单批超 30 条须用户确认** | -| assign-and-notify | 1. `aisearch person --keyword "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors ` → 取 `taskId`
3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --text "<通知内容>"` 通知 | +| batch-create-todo | 1. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --query "<姓名>" --dimension name` → 取 `userId`
3. **优先**：将待办写入 `todos.json`（格式见 [todo_batch_create.py](../../scripts/todo_batch_create.py)），执行 `python scripts/todo_batch_create.py todos.json`
备选：逐条 `todo task create --title "<标题>" --executors ` → 汇总回显
**单批超 30 条须用户确认** | +| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors ` → 取 `taskId`
3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<通知内容>"` 通知 | diff --git a/skills/mono/references/best_practices/03-meeting.md b/skills/mono/references/best_practices/03-meeting.md index 8f226029..2508f61a 100644 --- a/skills/mono/references/best_practices/03-meeting.md +++ b/skills/mono/references/best_practices/03-meeting.md @@ -53,4 +53,4 @@ | Recipe | 行动指南（固定路线） | | ------------------ | ------------------- | | schedule-meeting | **见上文「两准则」**、**「搜房失败硬门禁」**。**未给时段且仅说「发起/开个会」**→ 不走本 recipe；当前 CLI 不支持实时视频会议，告知用户请在钉钉客户端操作。**未给时段但有预约意图**（"安排""约""定"等词）：追问具体开始/结束时间。**已有时段后**，按固定顺序执行：1. `dws calendar event create` 建日程；2. 有参会人则 `dws calendar participant add`；3. 再处理会议室。**无明确会议室范围**：可直接 `python scripts/calendar_schedule_meeting.py --title "<主题>" --start "<起始>" --end "<结束>" [--users ] [--book-room] [--dry-run]`。**有明确范围（某楼/层）**：先 `dws calendar room list-groups`，锁定该地点**最相关的承载 group**；若只有一个地点，`--room-group-id` 应只传这个最相关 group，**不要**把同楼内多个楼层 group 打包传入碰运气。只有用户明确给出多个允许地点时，才把这些 `group-id` 一并传给 `python scripts/calendar_schedule_meeting.py ... --book-room --room-group-id ""`。**用户点名具体会议室**：须手工 `dws calendar room search --start "" --end "" --group-id [--available] --format json`（**无** `--query`），在 JSON 中匹配名称取 **`rooms[].roomId` 唯一真值** → `dws calendar room add --event --rooms `；**不得**把用户输入的会议室名当 `roomId`。**一旦连续 2 次空结果 / 任意一次 `roomId invalid`**：**必须回读本节并立即收束判断**；若整园/限定范围内搜尽仍无 roomId 或无空房 → **下一条消息必须直接向用户汇报失败结论**；否则只能向用户确认是否放宽范围/改时间。**禁止**假设 roomId、禁止无 ID 调用 `room add`、禁止用日程详情绕路、禁止继续猜测 Mock/测试环境。细则见「会议室搜索早停」。 | -| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --text "<变更通知>"` 通知变更 | +| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<变更通知>"` 通知变更 | diff --git a/skills/mono/references/best_practices/04-document.md b/skills/mono/references/best_practices/04-document.md index 9985c60d..51af2a2e 100644 --- a/skills/mono/references/best_practices/04-document.md +++ b/skills/mono/references/best_practices/04-document.md @@ -8,9 +8,9 @@ | search-docs-and-share | 1. `doc search --query "<关键词>"` → 取 `nodeId` + 标题建索引（不读全文）
2. `doc read --node `（追问按需，最多 2 篇） | | create-knowledge-base | 1. 创建知识库空间取 `WS_ID`
2. `doc create --name "<文档名>" --workspace ` → 取 `nodeId`
3. `doc list --workspace ` 确认 | | migrate-doc | 1. `doc read --node <源nodeId>` → 取正文并写入临时文件 `.md`
2. `doc create --name "<文档名>" --folder --content-file .md` → 取新 `nodeId`（`--folder` 只传文档文件夹 nodeId / alidocs 文件夹 URL，不传数字 dentryId；正文 <200KB 单步到位）
2a. 若正文 >200KB：**必须先向用户提示截断风险**（详见下方「分块 append 截断风险提示」），用户确认后再执行：`doc create --name "<文档名>" --folder ` → `nodeId` → 按段落切片 → 每片 `doc update --node --content-file --mode append`
3. **回读校验**：`doc read --node ` 校验内容完整性 | -| update-doc-section | **优先块级精修（保形）**：1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc block list --node --format json` 定位目标块取 `blockId`
3. `doc block update --node --block-id --text "<替换内容>" --format json` 局部修改（不破坏富格式）
4. **回读校验**：`doc read --node ` 确认目标章节已更新
**兜底**：仅当无法定位块且用户确认整篇替换时，先 `doc update --node --content-file .md --mode overwrite --dry-run` 预览，再加 `--yes` 执行；overwrite 会丢富格式（颜色/字号/合并单元格等），详见下方 template-based-generation §"为什么避免 overwrite" | +| update-doc-section | **优先块级精修（保形）**：1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc block list --node --format json` 定位目标块取 `blockId`
3. `doc block update --node --block-id --content "<替换内容>" --format json` 局部修改（不破坏富格式）
4. **回读校验**：`doc read --node ` 确认目标章节已更新
**兜底**：仅当无法定位块且用户确认整篇替换时，先 `doc update --node --content-file .md --mode overwrite --dry-run` 预览，再加 `--yes` 执行；overwrite 会丢富格式（颜色/字号/合并单元格等），详见下方 template-based-generation §"为什么避免 overwrite" | | template-based-generation | **触发**：用户给已有 alidocs URL + "参照/按模板/复刻/同样模板生成 X 月份的" → **保形复制，禁止重写**。固定走下方 [template-based-generation](#template-based-generation) 章节：`doc copy` 保形复制 → `doc rename` → `doc block list/update` 局部改副本。禁止 `doc read + doc create` 重写链。 | -| doc-to-message | 1. `doc read --node ` → 取正文（大文档只摘要+链接）
2. `contact user search --query "<姓名>"` → 取 `openDingTalkId`（推荐）；或 `chat search --query "<群名>"` → 取 `openConversationId`
3. `chat message send --open-dingtalk-id --text "<内容>"`（推荐）或 `--group --text "<内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| doc-to-message | 1. `doc read --node ` → 取正文（大文档只摘要+链接）
2. `contact user search --query "<姓名>"` → 取 `openDingTalkId`（推荐）；或 `chat search --query "<群名>"` → 取 `openConversationId`
3. `chat message send --open-dingtalk-id --content "<内容>"`（推荐）或 `--group --content "<内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | delete-old-doc | 1. `doc search --query "<关键词>"` 或 `doc list --folder ` 取 `nodeId`
2. **必须先向用户展示要删除的文档标题/路径**，等用户确认
3. `doc delete --node --yes`（注意：是 `doc delete`，不是 `doc block delete`；前者删整篇，后者删块）
4. 验证：`doc info --node ` 应返回 not-found | | export-doc-as-docx | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc export --node --output /tmp/.docx --timeout-sec 600`（CLI 内置渐进式退避轮询，**不要自己拼 GET downloadUrl**）
3. 落盘失败兜底：`doc export get --job-id --output /tmp/.docx` 续等
4. （可选）`doc-to-message` 把 docx 路径作为附件发给用户 | | grant-doc-access | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `contact user search --query "<姓名>"` → 取 `userId`（**注意**: doc permission 用 `userId`，不是 `openDingTalkId`）
3. **节点级**授权：`doc permission add --node --user --role EDITOR`
　　role 取值: MANAGER / EDITOR / DOWNLOADER / READER（**不要传 OWNER**）
　　单次最多 30 个 userId
4. 查权限：`doc permission list --node ` 确认
5. **不要混淆**: 给"知识库"加成员用 `wiki member add --workspace`（容器级）；给"单个文档"加权限用 `doc permission add --node`（节点级）| @@ -54,7 +54,7 @@ dws doc block list --node <副本nodeId> --format json # → 记录 blockId 和现有文本 # 5. 逐块局部改写（只改月份/日期/姓名/指标等局部变量，不动结构） -dws doc block update --node <副本nodeId> --block-id --text "<新内容>" --format json +dws doc block update --node <副本nodeId> --block-id --content "<新内容>" --format json # 6. 回读确认 dws doc read --node <副本nodeId> diff --git a/skills/mono/references/best_practices/07-minutes.md b/skills/mono/references/best_practices/07-minutes.md index 655ee8f1..816ef2d1 100644 --- a/skills/mono/references/best_practices/07-minutes.md +++ b/skills/mono/references/best_practices/07-minutes.md @@ -27,8 +27,8 @@ dws minutes list mine --limit 5 --format json | Recipe | 行动指南（固定路线） | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| meeting-followup | 1. **提取待办优先**：`minutes_extract_todos.py`（开源版未引入；可手动用 `dws minutes get todos --id ` 拼装） → 获取行动项列表 无脚本时按[「多源并行采集」](./_common/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --keyword "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors `（每条行动项；批量时可写 JSON 调 `python scripts/todo_batch_create.py todos.json`） 4. `chat message send --group --text "<通知内容>"` 通知已创建 | -| share-minutes | **拉摘要优先**：`minutes_recent_summary.py`（开源版未引入；可手动用 `dws minutes list` + `dws minutes get summary --id ` 组合） → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`contact user search --query "<姓名>"` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --text "<摘要内容>"`（推荐）；群聊：`--group --text "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| meeting-followup | 1. **提取待办优先**：`minutes_extract_todos.py`（开源版未引入；可手动用 `dws minutes get todos --id ` 拼装） → 获取行动项列表 无脚本时按[「多源并行采集」](./_common/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors `（每条行动项；批量时可写 JSON 调 `python scripts/todo_batch_create.py todos.json`） 4. `chat message send --group --content "<通知内容>"` 通知已创建 | +| share-minutes | **拉摘要优先**：`minutes_recent_summary.py`（开源版未引入；可手动用 `dws minutes list` + `dws minutes get summary --id ` 组合） → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`contact user search --query "<姓名>"` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--group --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | browse-minutes | 1. `minutes list all --query "<关键词>" --limit ` → 取全量 `taskUuid`（翻页直至无更多；无主题筛选用 `minutes list mine`；**有时间范围时加 `--start`/`--end` 服务端过滤**，如 `--start "2026-04-01T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00"`） 2. **详情/元数据优先** `minutes get batch --ids `（仅 API 上限时拆多批）；**摘要专项**且无 batch 字段时再用并行 `get summary` 或 `**python scripts/minutes_recent_summary.py --limit `** 3. 汇总展示；**同一用户诉求下避免**「半截 list → 再 list 剩余」「拆 4 条一批 summary 连跑多轮」等无必要拆分 | | minutes-detail | 1. 确定 `taskUuid`：用户已提供 → 直接用；未提供 → `minutes list mine --limit 5` 让用户选（**有时间线索时加 `--start`/`--end`**，如「上周五的会」→ `--start "2026-05-23T00:00:00+08:00" --end "2026-05-23T23:59:59+08:00"`） 2. 并行拉取四维信息：`minutes get info --id ` `&` `minutes get summary --id ` `&` `minutes get keywords --id ` `&` `minutes get todos --id ` `& wait` 3. 整合输出：基础信息（标题、时间、参与人）→ AI 摘要 → 关键字 → 行动项/待办 4. **展示发言人列表**：从转写/info 提取所有发言人（含已标注姓名和匿名编号），列出每位发言人的发言次数和时长占比，引导用户：「是否需要查看某位发言人的详细内容总结？请输入姓名或编号」→ 用户选定 → 进入 `minutes-speaker-summarize` recipe 5.（可选）用户要求看原文 → `minutes get transcription --id ` | | minutes-speaker-summarize | 1. 读取转写 → `minutes get transcription --id ` 2. 声纹标注检查：已标注 → 跳 Step 6；匿名编号 → 继续 3. 转写原文推断（称呼/自我介绍/上下文指代）→ 高置信度跳 Step 6 4. 并发身份推断：`calendar event list` + `participant list` 取日程参与人（最高优先） & `aisearch person` & `chat message list` & `doc search` `& wait`；未找到同时段日程 → 引导用户提供日程链接或参会人名单；两路以上一致才下结论 5. 置信度判断：>70% 直接输出；≤70% 展示 TOP3 候选让用户选（最多一次） 6. 结构化总结输出（核心观点 + 问题 + Action Item + 立场）→ 追问是否替换发言人标注。详见 [10-minutes-speaker-match.md](./10-minutes-speaker-match.md) | diff --git a/skills/mono/references/best_practices/10-minutes-speaker-match.md b/skills/mono/references/best_practices/10-minutes-speaker-match.md index 56d4b57d..53ab90c5 100644 --- a/skills/mono/references/best_practices/10-minutes-speaker-match.md +++ b/skills/mono/references/best_practices/10-minutes-speaker-match.md @@ -5,7 +5,7 @@ | Recipe | 行动指南（固定路线） | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| minutes-speaker-summarize | 1. **读取转写**：有 URL → 提取 `taskUuid` → `minutes get transcription --id `；有时间/关键词 → `minutes list all` 筛选 → 获取转写；无信息 → 必须询问 2. **声纹标注检查**：已标注真实姓名 → 直接跳 Step 6；仅匿名编号（发言人1/2/3）→ 继续 3. **转写原文推断**：利用称呼、自我介绍、上下文指代、发言顺序推断，高置信度 → 跳 Step 6；无法确定 → 继续 4. **并发身份推断**：`aisearch person --keyword "<姓名>" --dimension name` & `chat message list` 取近期 IM & `doc search --keyword "<姓名>"` 前 3 篇 `& wait`；两路以上一致才下结论 5. **置信度判断**：>70% → 直接输出；≤70% → 展示 TOP3 候选音频片段让用户选（最多一次，"都不是"则终止） 6. **结构化总结输出**：核心观点 + 问题/关注点 + Action Item + 立场态度；输出后追问是否替换发言人标注 | +| minutes-speaker-summarize | 1. **读取转写**：有 URL → 提取 `taskUuid` → `minutes get transcription --id `；有时间/关键词 → `minutes list all` 筛选 → 获取转写；无信息 → 必须询问 2. **声纹标注检查**：已标注真实姓名 → 直接跳 Step 6；仅匿名编号（发言人1/2/3）→ 继续 3. **转写原文推断**：利用称呼、自我介绍、上下文指代、发言顺序推断，高置信度 → 跳 Step 6；无法确定 → 继续 4. **并发身份推断**：`aisearch person --query "<姓名>" --dimension name` & `chat message list` 取近期 IM & `doc search --query "<姓名>"` 前 3 篇 `& wait`；两路以上一致才下结论 5. **置信度判断**：>70% → 直接输出；≤70% → 展示 TOP3 候选音频片段让用户选（最多一次，"都不是"则终止） 6. **结构化总结输出**：核心观点 + 问题/关注点 + Action Item + 立场态度；输出后追问是否替换发言人标注 | --- @@ -47,7 +47,7 @@ | 优先级 | 路径 | 做什么 | | ------ | ------------------ | ---------------------------------------------------------------------------------------------------- | | ① 最高 | 日程参与人 | 从听记 info 提取会议时间 → `dws calendar event list --start <会议开始-30min> --end <会议结束+30min>` → 匹配同时段日程 → `dws calendar participant list --event ` → 获取参与人姓名列表，与转写中匿名发言人做数量/顺序对照 | -| ② 高 | 通讯录 + 组织架构 | `dws aisearch person --keyword <姓名> --dimension name` → 部门/职级/上级/汇报关系 | +| ② 高 | 通讯录 + 组织架构 | `dws aisearch person --query <姓名> --dimension name` → 部门/职级/上级/汇报关系 | | ③ 高 | 聊天记录 | `dws chat message list` 获取与目标人的近期 IM 消息 → 工作内容/语言风格/职责线索 | | ④ 兜底 | 本人文档 | `dws doc search --keyword <姓名>` 取前 3 篇标题+摘要 → 角色精确信号 | diff --git a/skills/mono/references/best_practices/lite-recipes.md b/skills/mono/references/best_practices/lite-recipes.md index 0d4fa85e..cd33c7d8 100644 --- a/skills/mono/references/best_practices/lite-recipes.md +++ b/skills/mono/references/best_practices/lite-recipes.md @@ -11,7 +11,7 @@ ### create-todo -1. 确定执行者：指定姓名 → `aisearch person --keyword "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 +1. 确定执行者：指定姓名 → `aisearch person --query "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 2. 创建：`todo task create --title "<标题>" --executors [,...]`（可选 `--due "<截止ISO>"`）→ `todoTaskId` ### todo-query-ops @@ -32,7 +32,7 @@ 查询多人在某时段内的闲忙（**busy**，不是用 `event list` 扫日程）： -1. 解析用户：对每个姓名执行 `aisearch person --keyword "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 [calendar.md](../products/calendar.md) `busy search` 要求）。 +1. 解析用户：对每个姓名执行 `aisearch person --query "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 [calendar.md](../products/calendar.md) `busy search` 要求）。 2. 确认时段：用户须给出或可收敛为明确的 `--start` / `--end`（ISO-8601）；若未给出，**先追问**起止时间，禁止用任意默认全天窗口代替用户意图。 3. 执行：`dws calendar busy search --users --start "" --end "" --format json` @@ -213,7 +213,7 @@ query 未提"听记"但任务产出依赖会议讨论内容时（报告/总结/ **搜人首选入口**。凡是“找人/搜人/找同事/谁负责/上级/下级/负责人/团队成员”均优先用 `aisearch person`： 1. 从用户问题中提取 keyword（人名/业务关键词）和 dimension（维度），规则见 `aisearch`（开源版未引入，悟空内部产品）。 -2. `aisearch person --keyword "<关键词>" --dimension <维度>` +2. `aisearch person --query "<关键词>" --dimension <维度>` 3. 结果中提取 `userId` 和 `title`（姓名）展示给用户。 4. 若需要 userId 做后续操作（发消息/建待办），可直接使用结果中的 `userId`。 5. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](./08-directory.md)「多命中」。 @@ -225,7 +225,7 @@ query 未提"听记"但任务产出依赖会议讨论内容时（报告/总结/ - 需要获取 userId 给其他产品使用（发消息/建待办/约日程） - 已有 userId 需查完整详情（`contact user get --ids`） -1. `aisearch person --keyword "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 +1. `aisearch person --query "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 2. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](./08-directory.md)「多命中」。 3. 需详情时：`contact user get --ids `（多人可 `--ids id1,id2,...`） diff --git a/skills/mono/references/intent-guide.md b/skills/mono/references/intent-guide.md index c8b48011..31eda376 100644 --- a/skills/mono/references/intent-guide.md +++ b/skills/mono/references/intent-guide.md @@ -277,7 +277,7 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}` - 已有 userId 时直接使用 `--user`；已有 openDingTalkId 时使用 `--open-dingtalk-id` - `+messages-send --user` 对所有内容类型都会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；无需手动预查，`--dry-run` 也会执行这次只读解析 - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析 -- "发本地图片/文件/语音/视频到群里" — `dws chat message send ... --msg-type file --file-path <本地路径>`，CLI 内部自动上传并发送；png/jpg/pdf/mp4/zip 等任意扩展名都走这条，接收方看到的是可下载的文件附件。图片不会内联渲染，也不会生成 mediaId +- "发本地图片/文件/语音/视频到群里" — `dws chat message send ... --msg-type file --file <本地路径>`，CLI 内部自动上传并发送；png/jpg/pdf/mp4/zip 等任意扩展名都走这条，接收方看到的是可下载的文件附件。图片不会内联渲染，也不会生成 mediaId - "用已有 mediaId 发内联图片" — 仅当上游已经提供有效 mediaId 时，使用 `dws chat message send ... --msg-type image --media-id `；DWS CLI 不能把本地图片转换成 mediaId - "发图片+文字说明" — 不要硬塞进一条命令；先发图片/文件消息再补一条 `--text "..."` 即可 @@ -413,7 +413,7 @@ dws chat +messages-send --as user --open-dingtalk-id --msg-type ```bash # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 用 userId 查详情获取 email dws contact user get --ids --format json @@ -433,7 +433,7 @@ dws mail message send --from my@company.com --to zhangsan@company.com \ ```bash # 手动流程（脚本不可用时）: # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 创建日程 dws calendar event create --title "会议" \ @@ -449,7 +449,7 @@ dws calendar attendee add --event --attendees --format json ```bash # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 创建待办 dws todo task create --title "任务内容" --executors --format json @@ -465,10 +465,10 @@ dws todo task create --title "任务内容" --executors --format json ```bash # 群聊 -dws chat message send --group --msg-type file --file-path <本地路径> --format json +dws chat message send --group --msg-type file --file <本地路径> --format json # 单聊（推荐 --open-dingtalk-id；--user 也支持） -dws chat message send --open-dingtalk-id --msg-type file --file-path <本地路径> --format json +dws chat message send --open-dingtalk-id --msg-type file --file <本地路径> --format json ``` 支持任意扩展名（`.png/.jpg/.gif/.bmp/.webp/.pdf/.doc/.xls/.zip/.mp3/.wav/.mp4/.avi` …），CLI 自动完成上传与发送，不需要任何前置工具调用。图片文件同样作为可下载的 file 附件发送，不会内联渲染，也不会生成 mediaId。 @@ -478,8 +478,8 @@ dws chat message send --open-dingtalk-id --msg-type file --file 不要把文字塞进 `--msg-type file` 命令（该命令不读 `--text`）。先发文件再补一条文本消息即可： ```bash -dws chat message send --open-dingtalk-id --msg-type file --file-path ./screenshot.png --format json -dws chat message send --open-dingtalk-id --text "这是本周数据汇总" --format json +dws chat message send --open-dingtalk-id --msg-type file --file ./screenshot.png --format json +dws chat message send --open-dingtalk-id --content "这是本周数据汇总" --format json ``` ### 上游 mediaId — 仅兼容场景 diff --git a/skills/mono/references/products/aisearch.md b/skills/mono/references/products/aisearch.md index 417bfbda..8a041423 100644 --- a/skills/mono/references/products/aisearch.md +++ b/skills/mono/references/products/aisearch.md @@ -4,7 +4,7 @@ > > **搜人容错说明**（无需主动使用）：CLI 兼容下列 alias 兜底，模型偶尔写 `search` / `find` / `query` / `contact` / `people` 等也能跑通——但**搜人输出和文档以 `person` 为准**。 > -> 搜人的 keyword flag 同样兼容 `--name` / `--q` / `--query` / `--text` 兜底，规范用法是 `--keyword`。 +> 搜人的规范参数是 `--query`；旧 `--keyword`（含 `-w`）及历史隐藏参数 `--name` / `--q` / `--text` 继续兼容，新的示例统一使用 `--query`。 ## 企业人员搜索 @@ -14,15 +14,15 @@ Usage: dws aisearch person [flags] Example: - dws aisearch person --keyword "张三" --dimension name --format json - dws aisearch person --keyword "产品部" --dimension department --format json - dws aisearch person --keyword "五道" --dimension supervisor --format json - dws aisearch person --keyword "AI搜问" --dimension duty --format json - dws aisearch person --keyword "李四" --dimension name,department --format json - dws aisearch person --keyword "13800138000" --dimension phone --format json - dws aisearch person --keyword "W12345" --dimension jobNumber --format json + dws aisearch person --query "张三" --dimension name --format json + dws aisearch person --query "产品部" --dimension department --format json + dws aisearch person --query "五道" --dimension supervisor --format json + dws aisearch person --query "AI搜问" --dimension duty --format json + dws aisearch person --query "李四" --dimension name,department --format json + dws aisearch person --query "13800138000" --dimension phone --format json + dws aisearch person --query "W12345" --dimension jobNumber --format json Flags: - --keyword string 搜索关键词 (必填，如人名、技能关键词等) + --query string 搜索关键词 (必填，如人名、技能关键词等) --dimension string 查询维度，多个用逗号分隔 (默认 "all") ``` diff --git a/skills/mono/references/products/attendance-report.md b/skills/mono/references/products/attendance-report.md index 43d54547..5a9ac42a 100644 --- a/skills/mono/references/products/attendance-report.md +++ b/skills/mono/references/products/attendance-report.md @@ -126,7 +126,7 @@ Agent 解析用户意图（报表类型、人员范围、时间范围、关注 **场景 A — 指定员工姓名**: ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**: diff --git a/skills/mono/references/products/attendance-schedule.md b/skills/mono/references/products/attendance-schedule.md index 05bcc8a3..182d84d8 100644 --- a/skills/mono/references/products/attendance-schedule.md +++ b/skills/mono/references/products/attendance-schedule.md @@ -224,7 +224,7 @@ dws attendance group search --query "<考勤组名称>" --type TURN --format jso **场景 A — 指定员工姓名**： ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**： @@ -450,7 +450,7 @@ dws attendance group get --group-id --format json # ⚠️ 禁止用 class search 全局搜索班次 # 2. 获取员工 userId -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 3. 回显确认（Agent 向用户展示排班表格） # ... 用户确认 ... @@ -473,7 +473,7 @@ dws attendance group get --group-id --format json # → 确认是排班制（TURN） # 2. 获取员工 userId -dws aisearch person --keyword "李四" --dimension name --format json +dws aisearch person --query "李四" --dimension name --format json # 3. 回显确认 → 用户确认 → 执行 python scripts/attendance_schedule_import.py \ @@ -579,8 +579,8 @@ python scripts/attendance_schedule_export.py \ ```bash # 1. 获取 userId -dws aisearch person --keyword "张三" --dimension name --format json -dws aisearch person --keyword "李四" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json +dws aisearch person --query "李四" --dimension name --format json # 2. 调用脚本导出 python scripts/attendance_schedule_export.py \ diff --git a/skills/mono/references/products/attendance-vacation.md b/skills/mono/references/products/attendance-vacation.md index 6c59e739..c7cc4c85 100644 --- a/skills/mono/references/products/attendance-vacation.md +++ b/skills/mono/references/products/attendance-vacation.md @@ -63,7 +63,7 @@ Agent 只负责解析人员范围并获取 userId 列表；假期规则查询、 ### 阶段 0：参数解析 1. 识别人员范围： - - 指定员工姓名：用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取 userId + - 指定员工姓名：用 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取 userId - 指定部门：用 `dws contact dept search --query "<部门名>" --format json`，再用 `dws contact dept list-members --ids --format json` 获取成员 - 已提供 userId：直接使用 2. 识别假期列范围： @@ -74,7 +74,7 @@ Agent 只负责解析人员范围并获取 userId 列表；假期规则查询、 **场景 A — 指定员工姓名**: ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**: diff --git a/skills/mono/references/products/calendar.md b/skills/mono/references/products/calendar.md index db2873f9..f6517dbf 100644 --- a/skills/mono/references/products/calendar.md +++ b/skills/mono/references/products/calendar.md @@ -26,7 +26,7 @@ 日程实例（event instance）：日程的具体时间实例，可以通过event list指令查询时间段内的所有实例。1个普通日程和对应1个Instance，而1个重复性日程(SeriesMaster)对应N个Instance（同属一个日程序列）。 - 同一个日程序列具有相同的iCalUid，并且重复性日程，其eventId和iCalUid的值相同。因此可以通过重复性日程实例的iCalUid得到重复性日程(SeriesMaster)的eventId 重复规则（recurrence rule）：定义重复性日程的重复规则。 -参会人（attendee）：日程的参与者。按姓名统一使用 `dws aisearch person --keyword "姓名" --dimension name --format json` 查询 userId。 +参会人（attendee）：日程的参与者。按姓名统一使用 `dws aisearch person --query "姓名" --dimension name --format json` 查询 userId。 响应状态（response）：参会人对日程的回应，包括：未响应、接受、待定、拒绝。 忙闲时间（busy）：查询用户在指定时间段的忙闲状态，查询会议室在指定时间段的预定状态，用于会议时间协调。 会议室（room）：room是 会议室 ，room可视为日程的资源类参会人，需要加入日程完成预订。注意和location区分，location只是地点，和room不同。 diff --git a/skills/mono/references/products/chat.md b/skills/mono/references/products/chat.md index 24b322b9..2ddc7ca6 100644 --- a/skills/mono/references/products/chat.md +++ b/skills/mono/references/products/chat.md @@ -139,7 +139,7 @@ Example: dws chat group transfer-owner --group --new-owner dws chat group transfer-owner --group --user # 查询群 ID: dws chat search --query "群名" - # 查询人员: dws aisearch person --keyword "姓名" --dimension name + # 查询人员: dws aisearch person --query "姓名" --dimension name Flags: --group string 群聊 openConversationId (必填) --new-owner string 新群主 openDingTalkId @@ -443,7 +443,7 @@ Usage: dws chat group-role set-user [flags] Example: dws chat group-role set-user --group --user --role-ids roleId1,roleId2 - # 查询人员: dws aisearch person --keyword "姓名" --dimension name + # 查询人员: dws aisearch person --query "姓名" --dimension name # 查询 role-id: dws chat group-role list --group Flags: --group string 群聊 openConversationId (必填) @@ -564,43 +564,43 @@ Flags: **重要：该接口会真实发送消息到目标会话，不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。** ---group 指定群聊 openConversationId 发群消息；--user 指定用户 userId 发单聊；--open-dingtalk-id 指定用户 openDingTalkId 发单聊。三者只能选其一，不能同时指定。纯文本/Markdown 单聊传 --user 时直接走 userId 发送能力，不需要先手动查询 openDingTalkId。推荐使用 --text flag 传递消息内容（也支持位置参数）。可选 --title 作为消息标题。 +--group 指定群聊 openConversationId 发群消息；--user 指定用户 userId 发单聊；--open-dingtalk-id 指定用户 openDingTalkId 发单聊。三者只能选其一，不能同时指定。纯文本/Markdown 单聊传 --user 时直接走 userId 发送能力，不需要先手动查询 openDingTalkId。推荐使用 --content flag 传递消息内容（也支持位置参数）。可选 --title 作为消息标题。 图文混排 Markdown 中，公网图片 URL 需要写成 `![图片标题](https://example.com/image.png)` 才会以内联图片展示；省略开头的 `!` 时会按链接/URL 展示，不会渲染为图片。 若用户只提供了数字群号而非 openConversationId，需先调用 `chat group get-by-group-id` 将群号转为 openConversationId，再传入 --group。 --群聊时可选 --at-all @所有人，或 --at-open-dingtalk-ids 指定成员（仅群聊时生效）。 ---本地图片、文件、音频或视频统一用 --msg-type file --file-path；图片会作为可下载的文件附件发送。--msg-type image --media-id 仅用于上游已经提供有效 mediaId 的场景。 +--本地图片、文件、音频或视频统一用 --msg-type file --file；图片会作为可下载的文件附件发送。--msg-type image --media-id 仅用于上游已经提供有效 mediaId 的场景。 ``` Usage: dws chat message send [flags] [] 富媒体消息路由: 场景 → msgType → 发送参数 - 本地图片/文件/音频/视频 → file → --file-path <本地路径> + 本地图片/文件/音频/视频 → file → --file <本地路径> 上游已提供有效 mediaId 的内联图片 → image → --media-id 注意：本地 .png/.jpg 也按 file 发送，接收方看到的是可下载附件；DWS CLI 不能把本地文件转换成 mediaId。 Example: - dws chat message send --group --text "hello" - dws chat message send --user --text "请查收" - dws chat message send --open-dingtalk-id --text "请查收" + dws chat message send --group --content "hello" + dws chat message send --user --content "请查收" + dws chat message send --open-dingtalk-id --content "请查收" dws chat message send --group "hello" - dws chat message send --group --title "周报提醒" --text "请大家本周五前提交周报" + dws chat message send --group --title "周报提醒" --content "请大家本周五前提交周报" # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示 - dws chat message send --group --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' + dws chat message send --group --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' # 幂等发送（24h 内相同 uuid 不重复投递） - dws chat message send --group --text "hello" --uuid "unique-id-123" + dws chat message send --group --content "hello" --uuid "unique-id-123" dws chat message send --group --at-all "<@all> 请大家注意" dws chat message send --group --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 "<@openDingTalkId1> <@openDingTalkId2> 请查收" # 本地图片/文件/音频/视频统一作为 file 附件发送 - dws chat message send --group --msg-type file --file-path ./screenshot.png - dws chat message send --group --msg-type file --file-path ./report.pdf - dws chat message send --group --msg-type file --file-path ./recording.mp3 - dws chat message send --group --msg-type file --file-path ./demo.mp4 + dws chat message send --group --msg-type file --file ./screenshot.png + dws chat message send --group --msg-type file --file ./report.pdf + dws chat message send --group --msg-type file --file ./recording.mp3 + dws chat message send --group --msg-type file --file ./demo.mp4 # 仅当上游已有有效 mediaId 时发送内联图片 dws chat message send --group --msg-type image --media-id Flags: - --text string 消息内容（推荐使用，也可用位置参数） + --content string 消息内容（推荐使用，也可用位置参数） --group string 群聊 openconversation_id（群聊时必填） --user string 单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一） --open-dingtalk-id string 单聊接收人 openDingTalkId（单聊时与 --user 二选一） @@ -613,13 +613,13 @@ Flags: --space-id int64 已有钉盘文件空间 ID（元数据兼容模式） --file-name string 已有钉盘文件名（元数据兼容模式） --file-type string 已有钉盘文件类型/扩展名（元数据兼容模式） - --file-path string 本地文件路径（本地图片/文件/音视频配合 msgType=file 使用） + --file string 本地文件路径（本地图片/文件/音视频配合 msgType=file 使用） --file-size int64 已有钉盘文件大小，单位字节（元数据兼容模式） --uuid string 幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选） --ai-tag 消息是否带 AI 发送角标（可选，默认 true） 注意: - - --text 和位置参数二选一，--text 优先 + - --content 和位置参数二选一，--content 优先 - --group、--user、--open-dingtalk-id 三者互斥，只需指定其一：群聊用 --group，单聊用 --user 或 --open-dingtalk-id - 纯文本/Markdown 单聊发送时 `--user` 和 `--open-dingtalk-id` 都可用；传 `--user` 时直接走 userId 发送能力 - --group 的别名: --id, --chat, --conversation-id (均可替代 --group) @@ -628,13 +628,13 @@ Flags: 1. 必须使用**真实换行符**（Unicode `U+000A`），而非字面量字符串 `\n`（反斜杠 + 字母 n）。程序或大模型构造参数时，须确保已正确反转义；否则全部内容会渲染在同一行 2. Markdown 规范下**单个换行不产生换行效果**。需要换行时请使用：段落分隔（连续两个真实换行符 `\n\n`）、行尾两个空格 + 真实换行符（硬换行 `
`），或直接写 HTML 的 `
` 标签 - **图文混排**：公网图片 URL 需要写成 `![图片标题](https://example.com/image.png)` 才会以内联图片展示；如果省略开头的 `!`，例如 `[图片标题](https://example.com/image.png)`，将按链接/URL 展示，不会渲染为图片 - - 本地图片、文档、压缩包、音频和视频统一使用 `--msg-type file --file-path <本地路径>`；图片会成为可下载的 file 附件，不会内联渲染，也不会生成 mediaId + - 本地图片、文档、压缩包、音频和视频统一使用 `--msg-type file --file <本地路径>`；图片会成为可下载的 file 附件，不会内联渲染，也不会生成 mediaId - `--msg-type image --media-id` 仅接受上游已经提供的有效 mediaId；DWS CLI 不提供本地文件到 mediaId 的上传或转换能力 - - audio/video 仍是兼容的 file 语义别名，但本地文件的推荐路径保持为 `--msg-type file --file-path` + - audio/video 仍是兼容的 file 语义别名，但本地文件的推荐路径保持为 `--msg-type file --file` - dentryId/spaceId 等参数仅用于调用方已经持有钉盘文件元数据的兼容场景，不是发送本地文件的前置步骤 - --uuid 用于幂等发送，传入相同 uuid 在 24h 内不会重复投递消息（可选，群聊和单聊均支持） - 富媒体消息的单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析成 openDingTalkId 后发送 - - 发送文字 + 文件时，先发送 `--msg-type file --file-path` 文件消息，再补一条文本或 Markdown 说明；这是两条独立消息 + - 发送文字 + 文件时，先发送 `--msg-type file --file` 文件消息，再补一条文本或 Markdown 说明；这是两条独立消息 ``` ### file (会话文件上传，已下线) @@ -645,13 +645,13 @@ Flags: 发送本地文件消息仍然支持，统一使用： ``` -dws chat message send --group --msg-type file --file-path ./report.pdf --format json -dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf --format json +dws chat message send --group --msg-type file --file ./report.pdf --format json +dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json ``` 注意: - 不要再构造 `dws chat file upload --url ...`，该路径会直接返回下线提示 - - 常规发图/发文件/发音视频都走 `chat message send --msg-type file --file-path <本地路径>` + - 常规发图/发文件/发音视频都走 `chat message send --msg-type file --file <本地路径>` - 若需要“文字 + 文件”双消息，先发送文件消息，再补一条文本或 Markdown 消息说明 #### 查询消息发送状态 — 查询以当前用户身份发送的消息的发送状态 @@ -679,14 +679,14 @@ Flags: ```bash # 1. 发送后保留 openTaskId -dws chat message send --group --text "原始内容" +dws chat message send --group --content "原始内容" # 2. 查询得到 openMessageId 和 openConversationId dws chat message query-send-status --open-task-id # 3. 编辑消息 dws chat message edit --conversation-id --msg-id --text "更新后的内容" # 发送后撤回使用同一 ID 链 -dws chat message send --group --text "待撤回的内容" +dws chat message send --group --content "待撤回的内容" dws chat message query-send-status --open-task-id dws chat message recall --conversation-id --msg-id ``` @@ -803,23 +803,23 @@ Flags: #### 自定义机器人 Webhook 发送群消息 -@ 人时需在 --text 中包含 @userId 或 @手机号，否则 @ 不生效；@所有人时需在 --text 中包含 @10 并带上 --at-all。 +@ 人时需在 --content 中包含 @userId 或 @手机号，否则 @ 不生效；@所有人时需在 --content 中包含 @10 并带上 --at-all。 ``` Usage: dws chat message send-by-webhook [flags] Example: - dws chat message send-by-webhook --token --title "告警" --text "CPU 超 90% @10" --at-all - dws chat message send-by-webhook --token --title "test" --text "hi @118785" --at-users 118785 + dws chat message send-by-webhook --token --title "告警" --content "CPU 超 90% @10" --at-all + dws chat message send-by-webhook --token --title "test" --content "hi @118785" --at-users 118785 Flags: - --at-all @ 所有人（需在 --text 中包含 @10） + --at-all @ 所有人（需在 --content 中包含 @10） --at-mobiles string @ 指定手机号，逗号分隔 - --at-users string @ 指定用户，逗号分隔（需在 text 中包含 @userId） - --text string 消息内容 (必填) + --at-users string @ 指定用户，逗号分隔（需在 content 中包含 @userId） + --content string 消息内容 (必填) --title string 消息标题 (必填) --token string Webhook Token (必填) 注意: - - **换行符**：--text 按 Markdown 渲染，换行规则同 `chat message send`： + - **换行符**：--content 按 Markdown 渲染，换行规则同 `chat message send`： 1. 必须使用**真实换行符**（`U+000A`），而非字面量 `\n`，否则全部内容会渲染在同一行 2. 单个换行不产生换行效果，需用空行（`\n\n`）做段落分隔，或行尾两空格 + 换行/`
` 做硬换行 ``` @@ -1058,7 +1058,7 @@ Example: dws chat message search-advanced --conversation-ids <单聊openConversationId> --query "合同" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" # 查询群 ID: dws chat search --query "群名" # 查询单聊会话 ID: dws chat conversation-info --user - # 查询人员: dws aisearch person --keyword "姓名" --dimension name + # 查询人员: dws aisearch person --query "姓名" --dimension name Flags: --query string 搜索关键词（可选） --user string 发送者 userId，支持逗号分隔（可选） @@ -1287,7 +1287,7 @@ Flags: #### 获取会话基础信息 — 含会话关联的钉盘共享空间 ID -获取指定会话的基础信息，包含会话关联的钉盘共享空间 ID (newCSpaceIdIM)。该 ID 可用于独立的钉盘存储操作；发送本地图片或文件到聊天不需要先调用本命令，直接使用 `chat message send --msg-type file --file-path`。 +获取指定会话的基础信息，包含会话关联的钉盘共享空间 ID (newCSpaceIdIM)。该 ID 可用于独立的钉盘存储操作；发送本地图片或文件到聊天不需要先调用本命令，直接使用 `chat message send --msg-type file --file`。 ``` Usage: dws chat conversation-info [flags] @@ -1304,7 +1304,7 @@ Flags: - --group、--user、--open-dingtalk-id 互斥，必须且只能指定其一 - --group 的别名: --id, --chat, --conversation-id (均可替代 --group) - 返回值中的 newCSpaceIdIM 为会话共享空间 ID，可用于调用方明确需要的钉盘存储流程 - - 该 ID 不是发送本地聊天附件的前置条件；本地附件直接走 `chat message send --msg-type file --file-path` + - 该 ID 不是发送本地聊天附件的前置条件；本地附件直接走 `chat message send --msg-type file --file` ``` #### 引用回复消息 — 引用某条消息并回复文字（单聊/群聊均可） @@ -1312,16 +1312,16 @@ Flags: Usage: dws chat message reply [flags] Example: - dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "收到，马上处理" - dws chat message reply --conversation-id --ref-msg-id --ref-sender --text "请看一下" --at-open-dingtalk-ids + dws chat message reply --group --ref-msg-id --ref-sender --content "收到，马上处理" + dws chat message reply --group --ref-msg-id --ref-sender --content "请看一下" --at-open-dingtalk-ids # 被引用消息的 openMessageId、发送者 openDingTalkId 通过 dws chat message list 获取 Flags: --at-all @所有人（仅群聊时生效；正文缺少 <@all> 时自动补齐） --at-open-dingtalk-ids string @指定成员的 openDingTalkId 列表，逗号分隔（仅群聊时生效；正文缺少对应 <@id> 时自动补齐） - --conversation-id string 会话 openConversationId (必填，支持单聊/群聊) + --group string 会话 openConversationId (必填，支持单聊/群聊) --ref-msg-id string 被引用的消息 openMessageId (必填) --ref-sender string 被引用消息的发送者 openDingTalkId (必填) - --text string 回复内容 (必填) + --content string 回复内容 (必填) --ai-tag 消息是否带 AI 发送角标（可选，默认 true） --uuid string 幂等键（可选） @@ -2156,7 +2156,7 @@ Flags: 用户说"转发话题/转发话题消息" → `chat message forward-topic` 用户说"置顶消息/把消息置顶" → `chat message set-top-msg` 用户说"取消置顶消息/撤销消息置顶" → `chat message unset-top-msg` -用户说"发送/上传本地图片或媒体到聊天" → `chat message send --msg-type file --file-path <本地路径>` +用户说"发送/上传本地图片或媒体到聊天" → `chat message send --msg-type file --file <本地路径>` 用户明确要求机器人发送公网图片 URL → `chat message send-by-bot --msg-type image --image-url <图片 URL>` 用户明确要求机器人发送本地图片或文件 → `chat message send-by-bot --msg-type file --file-path <本地路径>`，按文件附件发送 用户明确只要 mediaId → DWS CLI 当前不提供本地上传入口；仅在上游已有有效 mediaId 时使用 `chat message send --msg-type image --media-id` @@ -2185,7 +2185,7 @@ Flags: - `chat message list-topic-replies` — 拉取群话题的回复消息列表 - `chat message list-focused` — 拉取特别关注人的消息，cursor 分页 - `chat list-top-conversations` — 拉取置顶会话列表（用户询问"置顶会话"或"置顶消息"时路由到此），cursor 分页 -- `chat message send` — 以当前用户身份发消息（群聊或单聊），text 为位置参数；本地图片/文件/音视频统一用 `--msg-type file --file-path`，其中图片显示为可下载附件而非内联图片；`--msg-type image --media-id` 只用于上游已经提供有效 mediaId 的场景，DWS CLI 不能从本地文件生成 mediaId +- `chat message send` — 以当前用户身份发消息（群聊或单聊），正文可用 `--content` 或位置参数；本地图片/文件/音视频统一用 `--msg-type file --file`，其中图片显示为可下载附件而非内联图片；`--msg-type image --media-id` 只用于上游已经提供有效 mediaId 的场景，DWS CLI 不能从本地文件生成 mediaId - `chat message search` — 按关键词搜索消息内容（跨所有会话，可选指定群） - `chat search-common` — 搜索共同群，查询指定人共同所在的群聊（AND=所有人都在，OR=任一人在） - `chat message send-by-bot` — 以**机器人**身份发消息（群聊或单聊）；Markdown 使用 `--text`，公网图片使用 `--msg-type image --image-url`，本地图片和文件使用 `--msg-type file --file-path`；群聊 Markdown 引用回复成对使用 `--reply` / `--ref-sender` @@ -2213,7 +2213,7 @@ Flags: - `chat clear-messages` — 清空当前用户视角下指定会话的聊天记录（不影响其他成员） - `chat group list-all` — 分页拉取当前用户加入的所有群（list-my-groups 仅返回群主/管理员的群） - `chat group list-join-validations` / `chat group audit-join-validation` — 拉取入群验证记录 / 审批入群验证（通过/拒绝/删除/忽略/拉黑） -- `chat file upload` — 已下线；不要调用 `chat/upload_conversation_file_by_url`，本地文件发送改用 `chat message send --msg-type file --file-path` +- `chat file upload` — 已下线；不要调用 `chat/upload_conversation_file_by_url`，本地文件发送改用 `chat message send --msg-type file --file` - `chat group transfer-owner` — 转让群主 - `chat group upgrade-to-external` — 将普通群不可逆升级为外部群（仅群主，需确认） - `chat group update-nick` — 设置群昵称；省略 `--nick` 时清除 @@ -2268,7 +2268,7 @@ dws chat message send-by-bot --robot-code \ # 7. Webhook 发告警 dws chat message send-by-webhook --token \ - --title "告警" --text "CPU 超 90% @10" --at-all --format json + --title "告警" --content "CPU 超 90% @10" --at-all --format json ``` ## 复合工作流 @@ -2319,12 +2319,12 @@ dws chat message send-by-bot --robot-code --group --text "你好" --format json +dws chat message send --open-dingtalk-id --content "你好" --format json ``` ### 机器人 @指定人发群消息 -通过 `--at-user-ids` 传入 userId 列表或 `--at-open-dingtalk-ids` 传入 openDingtalkId 列表来 @指定成员，多个用逗号分隔。`--text` 中需包含 `@userId` 或 `@openDingtalkId` 文本（不要用尖括号，不要用姓名）。通过 `--at-all` @所有人。 +通过 `--at-user-ids` 传入 userId 列表或 `--at-open-dingtalk-ids` 传入 openDingtalkId 列表来 @指定成员，多个用逗号分隔。`--content` 中需包含 `@userId` 或 `@openDingtalkId` 文本（不要用尖括号，不要用姓名）。通过 `--at-all` @所有人。 ```bash # Step 1: 搜人获取 userId @@ -2348,12 +2348,12 @@ dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./screenshot.png --format json -dws chat message send --group --text "这是本周的数据汇总" --format json +dws chat message send --group --msg-type file --file ./screenshot.png --format json +dws chat message send --group --content "这是本周的数据汇总" --format json ``` 机器人身份发送文件及说明： @@ -2374,17 +2374,17 @@ dws chat message send-by-bot --robot-code --group --group --msg-type image --image-url "https://example.com/image.png" --format json # 当前用户发送文件 -dws chat message send --group --msg-type file --file-path ./report.pdf --format json +dws chat message send --group --msg-type file --file ./report.pdf --format json # 机器人发送文件 dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./report.pdf --format json ``` -**带文字说明**：在上一步发完文件后，再补一条文本消息即可。不要尝试把文字塞进 `--msg-type file` 命令（该命令不读 `--text`）。 +**带文字说明**：在上一步发完文件后，再补一条文本消息即可。不要尝试把文字塞进 `--msg-type file` 命令（该命令不读 `--content`）。 ```bash -dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf --format json -dws chat message send --open-dingtalk-id --text "这是本周数据汇总" --format json +dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json +dws chat message send --open-dingtalk-id --content "这是本周数据汇总" --format json ``` **已有 mediaId（仅当上游已经提供有效 mediaId 时才用）**： @@ -2408,7 +2408,7 @@ Example: dws chat message send-card --group --at-all dws chat message send-card --receiver # 查询群 ID: dws chat search --query "群名" - # 查询人员: dws aisearch person --keyword "姓名" --dimension name + # 查询人员: dws aisearch person --query "姓名" --dimension name Flags: --at-all 群聊创建卡片时 @ 所有人（仅与 --group 一起使用） --at-open-dingtalk-ids string 群聊创建卡片时 @ 的 openDingTalkId 列表，逗号分隔（仅与 --group 一起使用） @@ -2454,7 +2454,7 @@ Flags: | `chat message search-advanced` | `nextCursor` | 下次 message search-advanced 的 --cursor | | `chat search-common` | `openConversationId` | message send/list 等的 --group | | `chat conversation-info` | `newCSpaceIdIM` | 独立钉盘存储流程的共享空间 ID；不是发送本地聊天附件的前置条件 | -| `chat file upload` | 无（已下线） | 不要调用；常规发图/发文件用 `chat message send --msg-type file --file-path` | +| `chat file upload` | 无（已下线） | 不要调用；常规发图/发文件用 `chat message send --msg-type file --file` | | `chat message list` | `openMsgId` | message read-status 的 --message-id | | `chat group-role list` | `openRoleId` | group-role update/remove/set-user/remove-user 的 --role-id | | `chat message create-text-emotion` | `emotionId` | add-text-emotion 的 --emotion-id | @@ -2477,7 +2477,7 @@ Flags: - 如果不传 `--uuid`，每次调用都视为新消息，重试可能导致消息重复发送 - 此参数适用于 `chat message send`（群聊和单聊均支持） - `--group` 为群聊会话 ID (openconversation_id)，可从群搜索或群聊信息中获取 -- `chat message send` 的 text 是位置参数（恰好 1 个），非 flag；群聊用 `--group`，单聊用 `--user`（userId）或 `--open-dingtalk-id`（openDingTalkId），三者互斥；纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力；`--at-all`、`--at-open-dingtalk-ids` 仅在 `--group` 群聊时生效；本地图片/文件/音视频统一用 `--msg-type file --file-path`，其中图片是可下载附件；`--msg-type image --media-id` 仅用于上游已经提供有效 mediaId 的内联图片 +- `chat message send` 的正文可用 `--content` 或位置参数（恰好 1 个）；群聊用 `--group`，单聊用 `--user`（userId）或 `--open-dingtalk-id`（openDingTalkId），三者互斥；纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力；`--at-all`、`--at-open-dingtalk-ids` 仅在 `--group` 群聊时生效；本地图片/文件/音视频统一用 `--msg-type file --file`，其中图片是可下载附件；`--msg-type image --media-id` 仅用于上游已经提供有效 mediaId 的内联图片 - `chat message list-all` 的四个参数（--start、--end、--limit、--cursor）每次请求都必须传递；翻页时用响应中的 nextCursor 值作为下次 --cursor - `chat message list` 的 `--group`、`--user`、`--open-dingtalk-id` 三者互斥，必须且只能指定其一 - `chat message list-by-sender` 不需要指定单聊/群聊，返回结果自带会话类型标识；`--sender-user-id`（userId）与 `--sender-open-dingtalk-id`（openDingTalkId）二选一；时间用 `--start`/`--end`（ISO-8601），分页用 `--limit`/`--cursor` @@ -2492,9 +2492,9 @@ Flags: - `chat search` 挂在 `chat` 下（非 `chat group` 下），路径为 `dws chat search` - `send-by-bot` 群聊传 `--conversation-id`，单聊传 `--users` 或 `--open-dingtalk-ids`，与群目标互斥且必选其一；机器人群聊 Markdown 引用回复必须同时传 `--reply ` 与 `--ref-sender `，单聊、图片和文件不支持引用回复；群聊时可选 `--at-user-ids` @指定成员（传 userId 列表）或 `--at-open-dingtalk-ids` @指定成员（传 openDingTalkId 列表），content 中需包含对应 @标识；`--at-all` @所有人；群聊场景如果返回"机器人不存在"错误，需先通过 `chat group members add-bot --conversation-id --robot-code ` 将机器人邀请进群后再发送 - `recall-by-bot` 群聊传 `--group` + `--keys`，单聊仅传 `--keys`（不传 `--group` 即为单聊撤回） -- `send-by-webhook` 支持 `--at-all`、`--at-mobiles`、`--at-users` 进行 @ 操作，但需在 `--text` 中包含 `@userId` 或 `@手机号` 才能生效；`--at-all` @所有人时需在 `--text` 中包含 `@10` +- `send-by-webhook` 支持 `--at-all`、`--at-mobiles`、`--at-users` 进行 @ 操作，但需在 `--content` 中包含 `@userId` 或 `@手机号` 才能生效；`--at-all` @所有人时需在 `--content` 中包含 `@10` - `chat group-role` 系列命令用于管理群的自定义身份标签：`list` 查列表，`add` 创建，`update` 改名，`remove` 删除；`set-user` 覆盖某人全部身份（传空 --role-ids 则清除），`remove-user` 仅移除指定身份，`query-user` 查询某人当前身份；用户用 `--user ` -- 消息**换行符**（`send` / `send-by-bot` / `send-by-webhook` 的 `--text`）有两层要求：(1) 必须是**真实换行符** `U+000A`，不是字面量 `\n`；(2) Markdown 规范下单换行不生效，需用空行 `\n\n`（段落分隔）或行尾两空格 + 换行 / `
`（硬换行） +- 消息**换行符**（`send` / `send-by-webhook` 使用 `--content`，`send-by-bot` 使用 `--text`）有两层要求：(1) 必须是**真实换行符** `U+000A`，不是字面量 `\n`；(2) Markdown 规范下单换行不生效，需用空行 `\n\n`（段落分隔）或行尾两空格 + 换行 / `
`（硬换行） - `chat group transfer-owner` 转让群主，需传 --group（openConversationId）；新群主 userId 用 `--user`，openDingTalkId 用 `--new-owner` - `chat group invite-url` 获取群邀请链接，需传 --group（openConversationId），可选 --expires-seconds 指定有效期（秒，0=永久） - `chat group quit` 退出群聊，需传 --group（openConversationId） @@ -2511,13 +2511,13 @@ Flags: - `chat hide` 隐藏会话，需传 --conversation-id（openConversationId，支持单聊/群聊），隐藏后不显示在列表中，收到新消息时重新出现 - `chat mute-at-all` 关闭/开启 @所有人消息提醒，需传 --conversation-id（openConversationId），默认关闭通知，传 --off 恢复接收；调用前需先开启总免打扰 - `chat mute-red-envelope` 关闭/开启红包消息提醒，需传 --conversation-id（openConversationId），默认关闭通知，传 --off 恢复接收；调用前需先开启总免打扰 -- `chat message reply` 引用回复消息（**单聊/群聊均可**），需传 --conversation-id（openConversationId，单聊与群聊使用同一字段）、--ref-msg-id（被引用消息 openMessageId）、--ref-sender（被引用消息发送者 openDingTalkId）、--text（回复内容）；目前回复类型仅支持 text +- `chat message reply` 引用回复消息（**单聊/群聊均可**），需传 --group（openConversationId，单聊与群聊使用同一字段）、--ref-msg-id（被引用消息 openMessageId）、--ref-sender（被引用消息发送者 openDingTalkId）、--content（回复内容）；目前回复类型仅支持 text - `chat message forward` 转发单条消息（**源/目标会话均支持单聊/群聊**，常见组合：群→群、群→单、单→群、单→单），需传 --src-conversation-id（源会话 openConversationId）、--msg-id（源消息 openMessageId）、--dest-conversation-id（目标会话 openConversationId） - `chat set-top` 设置/取消会话置顶（**单聊/群聊均可**），需传 --conversation-id（openConversationId，单聊与群聊使用同一字段），默认置顶，传 --off 取消 - `chat message reply` 以当前用户身份引用回复，与 `chat message send` 的用户身份发送语义一致 - **如何获取 openConversationId**（如果上层已有则直接使用，不必再查）： - 群聊：`dws chat search --query "群名"` - - 单聊：`dws chat conversation-info --user ` 或 `dws chat conversation-info --open-dingtalk-id `（人员信息可通过 `dws aisearch person --keyword "姓名" --dimension name` 获取） + - 单聊：`dws chat conversation-info --user ` 或 `dws chat conversation-info --open-dingtalk-id `（人员信息可通过 `dws aisearch person --query "姓名" --dimension name` 获取） - `chat group-mute` 全员禁言/取消全员禁言，需传 --group（openConversationId），默认禁言，传 --off 取消 - `chat group-mute-member` 指定群成员禁言，需传 --group、--user/--users（userId，逗号分隔）、--mute-time（毫秒，仅禁言时必填，支持 300000/3600000/86400000/604800000/2592000000），传 --off 解除禁言；CLI 会自动把 userId 解析成 openDingTalkId 再调用，直接传 userId 即可；禁言群主会被服务端拒绝 - `chat group set-admin` 设置/取消群管理员，需传 --group（openConversationId）、--user/--users（userId，逗号分隔），默认设为管理员，传 --off 取消 diff --git a/skills/mono/references/products/contact.md b/skills/mono/references/products/contact.md index c18fef5c..15b97854 100644 --- a/skills/mono/references/products/contact.md +++ b/skills/mono/references/products/contact.md @@ -11,7 +11,7 @@ > > **CRITICAL — 根部门**：钉钉根部门 `deptId=1`。`dept` 系列命令查根部门统一传 `--dept 1` 或 `--depts 1`，不要传 `self / me / root / 0`。 > -> **CRITICAL — 搜人首选 aisearch**：凡是"找人/搜人/谁负责 XX/某事项/某项目的人/上级/下级/团队成员"——**第一反应**是 `dws aisearch person`（详见 [aisearch.md](./aisearch.md)），不是 `contact user search`，**更不是反问用户要文档链接**。典型反例：用户说"查询集团推进事项"= 问"集团推进事项这个职责/项目下的人是谁"，正确做法是 `dws aisearch person --keyword "集团推进事项" --dimension duty --format json`。 +> **CRITICAL — 搜人首选 aisearch**：凡是"找人/搜人/谁负责 XX/某事项/某项目的人/上级/下级/团队成员"——**第一反应**是 `dws aisearch person`（详见 [aisearch.md](./aisearch.md)），不是 `contact user search`，**更不是反问用户要文档链接**。典型反例：用户说"查询集团推进事项"= 问"集团推进事项这个职责/项目下的人是谁"，正确做法是 `dws aisearch person --query "集团推进事项" --dimension duty --format json`。 ## 命令总览 diff --git a/skills/mono/references/products/doc.md b/skills/mono/references/products/doc.md index f7d2769c..9f6cbf97 100644 --- a/skills/mono/references/products/doc.md +++ b/skills/mono/references/products/doc.md @@ -232,13 +232,13 @@ Flags: Usage: dws doc block insert [flags] Example: - dws doc block insert --node --text "这是一段文字" + dws doc block insert --node --content "这是一段文字" dws doc block insert --node --heading "二级标题" --level 2 dws doc block insert --node --element '{"blockType":"paragraph","paragraph":{"text":"内容"}}' - dws doc block insert --node --text "在此处之前插入" --ref-block --where before + dws doc block insert --node --content "在此处之前插入" --ref-block --where before Flags: --node string 文档 ID 或 URL (必填) - --text string 快捷: 段落文本内容 + --content string 快捷: 段落文本内容 --heading string 快捷: 标题文本 --level int 标题级别 1-6 (配合 --heading，默认 1) --element string 块元素 JSON (高级) @@ -252,12 +252,12 @@ Flags: Usage: dws doc block update [flags] Example: - dws doc block update --node --block-id --text "新内容" + dws doc block update --node --block-id --content "新内容" dws doc block update --node --block-id --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}' Flags: --node string 文档 ID 或 URL (必填) --block-id string 目标块 ID (必填) - --text string 快捷: 段落文本内容 + --content string 快捷: 段落文本内容 --heading string 快捷: 标题文本 --level int 标题级别 1-6 (配合 --heading，默认 1) --element string 块元素 JSON (高级) @@ -863,13 +863,13 @@ dws doc media insert --node --file ./timeline.xlsx --name "项目时间 dws doc block list --node --format json # 2. 在文档末尾插入段落 -dws doc block insert --node --text "新增内容" +dws doc block insert --node --content "新增内容" # 3. 在指定块之前插入标题 dws doc block insert --node --heading "新章节" --level 2 --ref-block --where before # 4. 更新某个块的内容 -dws doc block update --node --block-id --text "修改后的内容" +dws doc block update --node --block-id --content "修改后的内容" # 5. 删除块 dws doc block delete --node --block-id --yes @@ -1044,7 +1044,7 @@ EOF - `create` 不传 `--folder` 和 `--workspace` 时，默认创建在"我的文档"根目录 - `create` 只能建"文档"（adoc）；要建表格/脑图/白板/多维表/演示，用 `dws wiki node create --workspace --type `（`doc file create` 已弃用）；建普通文件夹用 `dws drive mkdir` - `block list/insert/update/delete` 是块级精细编辑，适合结构化修改；简单内容追加建议用 `update --mode append` -- `block insert` 优先使用 `--text` 或 `--heading` 快捷方式；复杂块类型 (table, callout 等) 使用 `--element` JSON +- `block insert` 优先使用 `--content` 或 `--heading` 快捷方式；复杂块类型 (table, callout 等) 使用 `--element` JSON - `--content` 参数中的换行必须使用**真实换行符**（即实际的换行字符，Unicode `U+000A`），而不是字面量字符串 `\n`（反斜杠加字母 n）。在通过程序或大模型构造此参数时，请确保字符串在发送前已正确反转义。如果传入的是两个字符的字面量 `\n`，所有内容将渲染在同一行，导致标题、段落和表格格式全部错乱。**含多行/表格/长文本时优先用 `--content-file path.md` 或 `--content -`（stdin），不经过 shell escape，换行和表格都保持原样**（详见下方「长 Markdown 写入」）。 - 块类型包括: paragraph, heading, blockquote, callout, columns, orderedList, unorderedList, table, sheet, attachment, slot - 关键区分: doc(文档内容级操作) vs wiki(知识库空间级管理) vs aitable(数据表格操作) vs drive(钉盘文件管理) diff --git a/skills/mono/references/products/doc/doc-block.md b/skills/mono/references/products/doc/doc-block.md index 04e97ac2..d1a3c44e 100644 --- a/skills/mono/references/products/doc/doc-block.md +++ b/skills/mono/references/products/doc/doc-block.md @@ -58,10 +58,10 @@ Flags: Usage: dws doc block insert [flags] Example: - dws doc block insert --node --text "这是一段文字" + dws doc block insert --node --content "这是一段文字" dws doc block insert --node --heading "二级标题" --level 2 dws doc block insert --node --element '{"blockType":"paragraph","paragraph":{"text":"内容"}}' - dws doc block insert --node --text "在此处之前插入" --ref-block --where before + dws doc block insert --node --content "在此处之前插入" --ref-block --where before dws doc block insert --node --content-format jsonml --element '["p",{"uuid":"..."},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"新段落"]]]' # 插入引用块(blockquote) @@ -83,7 +83,7 @@ Example: dws doc update --node --content "---" --mode append Flags: --node string 文档 ID 或 URL (必填) - --text string 快捷: 段落文本内容 + --content string 快捷: 段落文本内容 --heading string 快捷: 标题文本 --level int 标题级别 1-6 (配合 --heading，默认 1) --element string 块元素 JSON (高级)；content-format=jsonml 时为 JSONML 数组字符串 @@ -104,13 +104,13 @@ Flags: Usage: dws doc block update [flags] Example: - dws doc block update --node --block-id --text "新内容" + dws doc block update --node --block-id --content "新内容" dws doc block update --node --block-id --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}' dws doc block update --node --block-id --content-format jsonml --element '["h1",{"uuid":""},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"新标题"]]]' Flags: --node string 文档 ID 或 URL (必填) --block-id string 目标块 ID (必填) - --text string 快捷: 段落文本内容 + --content string 快捷: 段落文本内容 --heading string 快捷: 标题文本 --level int 标题级别 1-6 (配合 --heading，默认 1) --element string 块元素 JSON (高级)；content-format=jsonml 时为 JSONML 数组字符串 @@ -172,7 +172,7 @@ dws doc block delete --node DOC_ID --block-id UUID ## 关键说明 - **块类型**：paragraph、heading、blockquote、callout、columns、orderedList、unorderedList、table、sheet、attachment、slot。 -- **快捷 vs --element**：`block insert` 优先使用 `--text` 或 `--heading` 快捷方式；复杂块类型（table、callout、columns 等）使用 `--element` JSON 或 `--content-format jsonml`。 +- **快捷 vs --element**：`block insert` 优先使用 `--content` 或 `--heading` 快捷方式；复杂块类型（table、callout、columns 等）使用 `--element` JSON 或 `--content-format jsonml`。 - **简单内容追加**：建议用 [`./doc-update.md`](./doc-update.md) `--mode append`，不必走 block insert。 - **JSONML validator**（写入端默认行为）： - 裸字符串、缺 uuid 等结构错误会被 validator 抦下并返回带 path 的错误（如 `$[2][2]: paragraph child must be span wrapper, got raw string.`）。 @@ -195,7 +195,7 @@ dws doc block delete --node DOC_ID --block-id UUID # ── element JSON 形态（次选，老接口）── # 文本段落 -dws doc block insert --node --text "这是段落文字" --content-format element +dws doc block insert --node --content "这是段落文字" --content-format element # 标题（level 1-6） dws doc block insert --node --heading "二级标题" --level 2 --content-format element @@ -217,10 +217,10 @@ dws doc block insert --node --content-format element \ --element '{"blockType":"callout","callout":{"emoji":"⚠️","bgColor":"#FDE2E0","content":[{"text":"高风险操作，先备份"}]}}' # 在指定 block 之前插入 -dws doc block insert --node --text "在此之前" --ref-block --where before --content-format element +dws doc block insert --node --content "在此之前" --ref-block --where before --content-format element # 修改某块文本 -dws doc block update --node --block-id --text "修改后" --content-format element +dws doc block update --node --block-id --content "修改后" --content-format element # 修改标题 dws doc block update --node --block-id --content-format element \ diff --git a/skills/mono/references/products/doc/style/doc-update-workflow.md b/skills/mono/references/products/doc/style/doc-update-workflow.md index 45d1cb88..3df0f498 100644 --- a/skills/mono/references/products/doc/style/doc-update-workflow.md +++ b/skills/mono/references/products/doc/style/doc-update-workflow.md @@ -143,7 +143,7 @@ dws doc update --node --content-file /tmp/-append.md --mode appen dws doc block list --node # 改一个 block 的文本 -dws doc block update --node --block-id --text "替换后的内容" --content-format element +dws doc block update --node --block-id --content "替换后的内容" --content-format element # 在某个 block 后插入 dws doc block insert --node --ref-block --where after --heading "补充说明" --level 2 --content-format element diff --git a/skills/mono/references/products/drive.md b/skills/mono/references/products/drive.md index 63f9b30d..f03372b6 100644 --- a/skills/mono/references/products/drive.md +++ b/skills/mono/references/products/drive.md @@ -614,7 +614,7 @@ Flags: **导出文档/导出为Word**: 导出是内容层操作，走 `doc export`，不属于 drive。 -把图片/文件发到群里一般直接用 `chat message send --msg-type file --file-path <本地路径>`（见 [chat.md](./chat.md)），无需先经 drive 上传。 +把图片/文件发到群里一般直接用 `chat message send --msg-type file --file <本地路径>`（见 [chat.md](./chat.md)），无需先经 drive 上传。 ## 核心工作流 @@ -834,4 +834,4 @@ dws drive copy --node <源文件dentryUuid> --folder <目标文件夹fileId> --f - [doc](./doc.md) — 文档内容读写（Markdown/块级编辑/导出），不是文件存储 - [markdown](./markdown.md) — 钉盘或文档空间中原生 `.md` 文件的读取、创建、覆盖与局部替换 - [wiki](./wiki.md) — 知识库/空间管理层（空间列表、节点创建、空间内搜索、成员管理） -- [chat](./chat.md) — 发送图片/文件消息用 `chat message send --msg-type file --file-path` +- [chat](./chat.md) — 发送图片/文件消息用 `chat message send --msg-type file --file` diff --git a/skills/mono/references/products/mail.md b/skills/mono/references/products/mail.md index bea9ebdb..718b8e70 100644 --- a/skills/mono/references/products/mail.md +++ b/skills/mono/references/products/mail.md @@ -136,7 +136,7 @@ Flags: ```bash # 同时发起以下三路，取最先返回有效邮箱的结果 # 路径 1：aisearch + contact user get -dws aisearch person --keyword "姓名" --dimension name --format json +dws aisearch person --query "姓名" --dimension name --format json # → 取 userId，再执行： dws contact user get --ids --format json # → 提取 orgAuthEmail 字段 @@ -1630,7 +1630,7 @@ Flags: 用户说"发邮件/写邮件" → 先 `mailbox list` 获取发件地址，再 `message send` 用户说“给(某人名字)发邮件” / “查询某人发给我的邮件” / “查询发给某人的邮件” / 任何涉及按人名查找邮箱的场景 → **第一步**：并发同时发起以下三路查询，取最先返回有效邮箱的结果；若三路均无有效邮箱，ask_human 请用户提供，禁止臆测： - 1. `aisearch person --keyword <姓名>` → `contact user get --ids `，提取 `orgAuthEmail` + 1. `aisearch person --query <姓名>` → `contact user get --ids `，提取 `orgAuthEmail` 2. `mail user search --email <当前邮箱> --keyword <姓名>`，提取 `users[].email`（仅企业邮箱可用） 3. `contact user search --keyword <姓名>`，提取用户邮箱字段 **第二步**：用获得的目标邮箱拼入 KQL（如 `from:` 或 `to:`）执行 `message search`，或用于 `message send` @@ -1801,7 +1801,7 @@ dws mail thread get --email user@company.com --id --select mess - KQL 查询支持 AND/OR/NOT 组合，字段值含空格时需用双引号 - `--cc` 抄送人支持多人，逗号分隔 - 收件人邮箱获取：用户只知道同事名字时，**并发**同时执行以下三路查询，取最先返回有效邮箱的结果，无需等待其他路完成： - 1. `dws aisearch person --keyword "名字" --dimension name` → `dws contact user get --ids `，提取 `orgAuthEmail` + 1. `dws aisearch person --query "名字" --dimension name` → `dws contact user get --ids `，提取 `orgAuthEmail` 2. `dws mail user search --email <发件人邮箱> --keyword "名字"`，提取 `users[].email`（仅企业邮箱账号可调用，个人 @dingtalk.com 邮箱会报权限错误可忽略） 3. `dws contact user search --keyword "名字"`，提取用户邮箱字段 若三路均无有效邮箱，必须 ask_human 请用户手动提供收件人邮箱，严禁臆测和假设 diff --git a/skills/mono/references/products/oa.md b/skills/mono/references/products/oa.md index cc82079f..332d8649 100644 --- a/skills/mono/references/products/oa.md +++ b/skills/mono/references/products/oa.md @@ -251,7 +251,7 @@ Flags: a. 向用户展示每个节点的名称、类型、已指定处理人 b. 若 targetSelect == true： - 提示用户"节点「{activityName}」需要您自选{actorType}人" - - 使用 dws aisearch person --keyword "<姓名>" --dimension name --format json 帮用户查找并选人 + - 使用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户查找并选人 - 记录 activityId 和用户选择的 userIds 3. 将自选结果组装为 targetSelectActioners，传入 create-instance 高级模式 --request ``` @@ -285,7 +285,7 @@ Flags: - **如果用户明确给出 `processCode`，固定走 `form-schema` → 收集表单值 → `forecast-process` → 自选节点选人 → `create-instance`**，不要跳过 `form-schema` 直接拼请求。 - **`form-schema` 返回的 `content` 不是创建 payload 的原样模板。** 它主要用于识别控件 `label`（即 name）、`id`、控件类型（componentName）和选项值范围；真正的 `formComponentValues` 中 `value` 结构以本文的控件值格式表为准。 - **`forecast-process` 返回的自选节点必须在发起前让用户选人。** 若 `workflowActivityRuleVOs` 中有 `targetSelect: true` 的节点，必须提示用户选择处理人，并将结果通过 `targetSelectActioners` 传入 `create-instance`。 -- **所有人员类参数使用 userId。** 若用户给的是姓名，先用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 解析成 userId。**严禁把姓名直接写进** `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。 +- **所有人员类参数使用 userId。** 若用户给的是姓名，先用 `dws aisearch person --query "<姓名>" --dimension name --format json` 解析成 userId。**严禁把姓名直接写进** `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。 - **创建实例前一次性汇总确认。** `create-instance` 是写操作，执行前一次性展示模板、表单值、流程预测结果和审批人/抄送人供用户确认。 #### 严禁行为 @@ -294,7 +294,7 @@ Flags: - **严禁复用旧的 Schema 结果。** 每次发起实例前都必须重新调用 `form-schema`，模板可能已被修改。 - **严禁在存在不支持必填控件时强行发起。** 若 `form-schema` 返回的必填控件中有不支持类型（如附件等），直接告知用户不支持通过 CLI 发起。 - **严禁把 `form-schema` 返回的 `content` 当成可直接提交的 payload 模板。** -- **严禁把姓名直接写进 `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。** 必须先通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 转成 userId。 +- **严禁把姓名直接写进 `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。** 必须先通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 转成 userId。 - **严禁在未得到用户确认前直接执行真实提单。** - **严禁猜测控件名称或选项值。** 必须从 `form-schema` 返回中提取。 - **严禁跳过 `forecast-process` 中的自选节点选人。** 若预测返回 `targetSelect: true` 的节点，必须让用户选人后再发起。 @@ -307,7 +307,7 @@ Flags: | 已拿到 `processCode` | 直接 `form-schema --process-code ` | | 已拿到 Schema | 向用户展示控件列表，收集表单值 | | 已收集表单值 | `forecast-process` 预测流程走向 | -| 预测返回有 `targetSelect: true` 节点 | 让用户为自选节点选人（`dws aisearch person --keyword "<姓名>" --dimension name --format json` 解析姓名） | +| 预测返回有 `targetSelect: true` 节点 | 让用户为自选节点选人（`dws aisearch person --query "<姓名>" --dimension name --format json` 解析姓名） | | 预测完成，自选节点已选人 | 汇总确认后 `create-instance --yes` | | 用户明确说"不走模板流程，直接指定审批人" | 使用 `directAppointedApprovers`（高级模式） | @@ -319,7 +319,7 @@ Flags: 3. 检查 Schema 中是否有不支持的必填控件 → 若有则直接告知用户不支持发起 4. 收集表单值 → 向用户展示控件列表，收集用户填写的表单值 5. forecast-process → 根据表单值预测流程走向，识别自选节点 -6. 自选节点选人 → 若预测返回 targetSelect=true 的节点，让用户选人（用 dws aisearch person --keyword "<姓名>" --dimension name --format json 解析姓名） +6. 自选节点选人 → 若预测返回 targetSelect=true 的节点，让用户选人（用 dws aisearch person --query "<姓名>" --dimension name --format json 解析姓名） 7. 汇总确认后 create-instance --yes → 展示完整信息（表单值 + 流程路径 + 审批人），用户确认后执行发起 ``` @@ -334,7 +334,7 @@ Flags: 2. **流程预测后再选自选审批人（步骤 5→6）：** `forecast-process` 返回流程路径和自选节点后： - 先向用户展示完整的流程路径（经过哪些节点、各节点处理人） - 对 `targetSelect: true` 的节点，提示用户"节点「{activityName}」需要您自选{actorType}人" - - 用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 帮用户查找并选人 + - 用 `dws aisearch person --query "<姓名>" --dimension name --format json` 帮用户查找并选人 - 若有多个自选节点，一次性收集所有自选节点的选人结果 3. **单次汇总确认（步骤 7）：** 发起前一次性展示完整信息供用户确认： @@ -385,7 +385,7 @@ Flags: - 先用 `form-schema` 识别有哪些控件、每个控件的 `label`（name）、`componentName`（type）、选项值范围以及明细子控件结构。 - **`form-schema` 返回的 `content` 不是可直接提交的原样模板。** 它提供控件定义，`value` 结构须按下方控件值格式表组装。 - 提交时必须保证每个控件的 `name`（即 label）与 Schema 中的 `props.label` **完全一致**。 -- 如果用户提供的是人员信息，先用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 转成 userId 后再写入对应控件。 +- 如果用户提供的是人员信息，先用 `dws aisearch person --query "<姓名>" --dimension name --format json` 转成 userId 后再写入对应控件。 - 单选/多选控件提交的是选项文本（option value），该值从 `form-schema` 返回的选项定义中取得。 - `InnerContactField`、`DepartmentField`、`TableField`、`DDDateRangeField`、`DDAttachment` 等控件的 `value` 结构各不相同，必须按下方格式表单独组装，不要套用文本控件的写法。 - `TextNote`（文字说明）不收集数据，**不要**出现在 `formComponentValues` 中。 @@ -468,7 +468,7 @@ Flags: } ] ``` -- `staffIds`：审批人 userId 列表（必须通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取，严禁填姓名） +- `staffIds`：审批人 userId 列表（必须通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取，严禁填姓名） - `taskActionType`：`NONE`（单人审批）/ `AND`（会签）/ `OR`（或签） **targetSelectActioners（模板有自选审批节点时使用）：** @@ -811,7 +811,7 @@ dws oa approval form-schema --process-code --format json # 18c. 收集表单值（向用户展示控件列表，用户填写后组装 form-values） # 18d. 流程预测（根据表单值预测审批走向，识别自选审批人节点；processCode/deptId/formValues 必填，userId 由登录态自动填充） dws oa approval forecast-process --process-code --dept-id -1 --form-values '{"单行输入框":"测试内容"}' --format json -# 18e. 若 forecast 返回 targetSelect=true 的节点，用 dws aisearch person --keyword "<姓名>" --dimension name --format json 帮用户选人 +# 18e. 若 forecast 返回 targetSelect=true 的节点，用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户选人 # 18f. 发起审批实例（form-values 的 key 须与 Schema 中控件 label 一致） dws oa approval create-instance --process-code --form-values '{"单行输入框":"测试内容"}' --yes --format json # 18g. 发起并指定审批人和抄送人 diff --git a/skills/mono/references/products/oa/oa-form-components.md b/skills/mono/references/products/oa/oa-form-components.md index 9deb57d3..5e795ce4 100644 --- a/skills/mono/references/products/oa/oa-form-components.md +++ b/skills/mono/references/products/oa/oa-form-components.md @@ -193,7 +193,7 @@ { "name": "项目负责人", "value": "[\"userId1\",\"userId2\"]" } ``` -> **严禁直接写姓名。** 必须先通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 查询获取 userId；多结果时须让用户消歧确认。 +> **严禁直接写姓名。** 必须先通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 查询获取 userId；多结果时须让用户消歧确认。 ### DepartmentField（部门控件） diff --git a/skills/mono/references/products/oa/oa-process-nodes.md b/skills/mono/references/products/oa/oa-process-nodes.md index b3a93ce9..c7fe5264 100644 --- a/skills/mono/references/products/oa/oa-process-nodes.md +++ b/skills/mono/references/products/oa/oa-process-nodes.md @@ -127,7 +127,7 @@ } ``` -- `workNo` 必须通过 `dws aisearch person --keyword "<工号>" --dimension jobNumber --format json` 获取，**严禁编造** +- `workNo` 必须通过 `dws aisearch person --query "<工号>" --dimension jobNumber --format json` 获取，**严禁编造** - 在 `create-instance` 中对应 `directAppointedApprovers` 的 `staffIds` ### 2. 直属主管（target_formula / reportLineManager） @@ -337,7 +337,7 @@ | 字段 | 说明 | |------|------| -| `staffIds` | 审批人 userId 列表（通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取；多结果须消歧） | +| `staffIds` | 审批人 userId 列表（通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取；多结果须消歧） | | `taskActionType` | `NONE`（单人）/ `AND`（会签）/ `OR`（或签） | | `staffId` | 留空字符串 | @@ -369,6 +369,6 @@ 2. 根据节点中的 `activityType` 和 `targetSelect` 判断是否需要传入 `directAppointedApprovers` 或 `targetSelectActioners` 3. 如果预测返回 `targetSelect: true` 的自选节点，`targetSelectActioners` 必填 4. 如果用户要求覆盖默认流程，使用 `directAppointedApprovers` -5. **所有 userId 必须通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取，严禁填姓名；多结果须消歧** +5. **所有 userId 必须通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取，严禁填姓名；多结果须消歧** > **交互优化：** 若用户在 `forecast-process` 前已指定审批人/抄送人姓名，`forecast-process` 返回自选节点后应自动映射，仅对未覆盖的自选节点追问，不要重复询问。详见 [oa.md](../oa.md) 交互优化原则。 diff --git a/skills/mono/references/products/sheet/sheet-comment.md b/skills/mono/references/products/sheet/sheet-comment.md index 985e9813..13a614f4 100644 --- a/skills/mono/references/products/sheet/sheet-comment.md +++ b/skills/mono/references/products/sheet/sheet-comment.md @@ -111,7 +111,7 @@ Flags: ## 关键说明 -- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --keyword "<姓名>" --dimension name` 拿到 userId。 +- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --query "<姓名>" --dimension name` 拿到 userId。 - `--comment-key` 是 13 位毫秒时间戳 + 32 位 UUID 的拼接字符串，从 `list` / `create` 返回中提取，用于 `reply` / `update` / `delete`。 - `create` / `list`（按单元格过滤）的 `--sheet-id` 是工作表 ID 或名称；未知时先 `dws sheet list` 确认，禁止臆测。 - `reply` 加 `--emoji` 时 `--content` 填表情名称（如 `比心`、`赞`），不是文字内容。 @@ -143,7 +143,7 @@ dws sheet list --node --format json dws sheet comment create --node --sheet-id Sheet1 --range A2 --content "这个数字有问题" --format json # 创建评论 + @人（先 aisearch person 拿 userId） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json dws sheet comment create --node --sheet-id Sheet1 --range A2 --content "请确认" --mention , --format json # 文字回复 diff --git a/skills/mono/references/products/todo.md b/skills/mono/references/products/todo.md index 263efb5e..bae90499 100644 --- a/skills/mono/references/products/todo.md +++ b/skills/mono/references/products/todo.md @@ -201,9 +201,9 @@ Flags: Usage: dws todo task add-attachment [flags] Example: - dws todo task add-attachment --task-id --file-path /path/to/file.pdf + dws todo task add-attachment --task-id --file /path/to/file.pdf Flags: - --file-path string 本地文件路径 (必填) + --file string 本地文件路径 (必填) --task-id string 待办任务 ID (必填) ``` @@ -433,7 +433,7 @@ dws todo task reset-reminder --task-id --format json dws todo task reset-reminder --task-id --reminder-rules '' --format json # 18. 上传附件（真实上传，先确认待办存在）— 从返回 result.attachmentIds 取 attachmentId -dws todo task add-attachment --task-id --file-path /path/to/file.pdf --format json +dws todo task add-attachment --task-id --file /path/to/file.pdf --format json # 19. 查询附件列表 — 从返回 attachments[].attachmentId 取 ID dws todo task list-attachment --task-id --format json # 20. 删除附件（用户确认后加 --yes；删完可 list-attachment 复查为空） diff --git a/skills/multi/dingtalk-aisearch/SKILL.md b/skills/multi/dingtalk-aisearch/SKILL.md index a116b8a4..2e2b6daf 100644 --- a/skills/multi/dingtalk-aisearch/SKILL.md +++ b/skills/multi/dingtalk-aisearch/SKILL.md @@ -21,12 +21,12 @@ metadata: | 用户说 | 命令 | |--------|------| -| "找张三 / 张三是谁" | `dws aisearch person --keyword "张三" --dimension name` | -| "谁负责 XX / XX 负责人是谁" | `dws aisearch person --keyword "" --dimension duty` | -| "张三的上级 / 下级" | `dws aisearch person --keyword "张三" --dimension supervisor`（或 `subordinate`） | -| "X 部门有哪些人" | `dws aisearch person --keyword "<部门>" --dimension department` | -| "工号 12345 是谁" | `dws aisearch person --keyword "<工号>" --dimension jobNumber` | -| "按手机号线索语义搜人" | `dws aisearch person --keyword "<手机号线索>" --dimension phone` | +| "找张三 / 张三是谁" | `dws aisearch person --query "张三" --dimension name` | +| "谁负责 XX / XX 负责人是谁" | `dws aisearch person --query "" --dimension duty` | +| "张三的上级 / 下级" | `dws aisearch person --query "张三" --dimension supervisor`（或 `subordinate`） | +| "X 部门有哪些人" | `dws aisearch person --query "<部门>" --dimension department` | +| "工号 12345 是谁" | `dws aisearch person --query "<工号>" --dimension jobNumber` | +| "按手机号线索语义搜人" | `dws aisearch person --query "<手机号线索>" --dimension phone` | | "完整手机号精确反查" | `dws contact user search-mobile --mobile "<完整手机号>"` | | "最近 OKR 相关邮件 / 项目相关文档" | `dws aisearch enterprise --queries "<主题>" --types mail/document --time-range "<时间>"` | | "我发过/创建过/分享过/收到过什么" | `dws aisearch behavior --queries "<主题>" --behavior-type <动作> --direction <方向>` | @@ -39,8 +39,8 @@ metadata: **触发**：姓名模糊找人/谁负责/查上下级/部门成员/工号反查/手机号线索语义搜人。 -1. **定维度（必须）**：姓名→`name`、"谁负责 XX"→`duty`、部门成员→`department`、上级/下级→`supervisor`/`subordinate`、工号→`jobNumber`、手机号语义线索→`phone`；完整手机号精确反查切到 `dingtalk-contact` 的 `user search-mobile`；不确定→`all`。`--keyword` 必须按用户原文**完整保真**，切勿截断、改昵称、扩同音字。 -2. **执行（必须）**：`dws aisearch person --keyword "<完整值>" --dimension <维度> --format json`。 +1. **定维度（必须）**：姓名→`name`、"谁负责 XX"→`duty`、部门成员→`department`、上级/下级→`supervisor`/`subordinate`、工号→`jobNumber`、手机号语义线索→`phone`；完整手机号精确反查切到 `dingtalk-contact` 的 `user search-mobile`；不确定→`all`。`--query` 必须按用户原文**完整保真**，切勿截断、改昵称、扩同音字。 +2. **执行（必须）**：`dws aisearch person --query "<完整值>" --dimension <维度> --format json`。 3. **解析（必须）**：从 JSON 取 `userId` / `openDingTalkId`；**多候选必须输出让用户选，禁止默认取第一个、禁止编造**未返回的人员字段。 4. **衔接（必须）**：要邮箱/部门/职位/主管等详情 → 切 `dingtalk-contact` 执行 `dws contact user get --ids --format json`；发消息 → `dingtalk-chat`；发 DING → `dingtalk-misc`（`references/ding.md`）。 5. **失败（必须）**：未命中最多换 1 个维度重试一次（如 `name`→`department`/`jobNumber`/`phone`），仍保留完整目标值；仍无果**必须如实告知**。 @@ -67,7 +67,7 @@ metadata: ## 高频硬约束 -- 搜索目标必须完整保真：姓名、工号、手机号、部门名按用户原文完整传入 `--keyword`，严禁自行截断、拆字、改昵称或扩展同音字。 +- 搜索目标必须完整保真：姓名、工号、手机号、部门名按用户原文完整传入 `--query`，严禁自行截断、拆字、改昵称或扩展同音字。 - 首次未命中时最多换维度重试一次（如 name → department/jobNumber/phone），仍必须保留完整目标值；不要用半截姓名扩大搜索。 - 找到候选后，如用户要邮箱、部门、职位、主管等详情，必须切到 `dingtalk-contact` 执行 `contact user get --ids --format json` 补全。 - 多候选且无法唯一判断时输出候选并询问；不要默认取第一个，也不要编造未返回的人员信息。 diff --git a/skills/multi/dingtalk-aisearch/references/aisearch.md b/skills/multi/dingtalk-aisearch/references/aisearch.md index d211c93f..5deb161d 100644 --- a/skills/multi/dingtalk-aisearch/references/aisearch.md +++ b/skills/multi/dingtalk-aisearch/references/aisearch.md @@ -4,7 +4,7 @@ > > **搜人容错说明**（无需主动使用）：CLI 兼容下列 alias 兜底，模型偶尔写 `search` / `find` / `query` / `contact` / `people` 等也能跑通——但**搜人输出和文档以 `person` 为准**。 > -> 搜人的 keyword flag 同样兼容 `--name` / `--q` / `--query` / `--text` 兜底，规范用法是 `--keyword`。 +> 搜人的规范参数是 `--query`；旧 `--keyword`（含 `-w`）及历史隐藏参数 `--name` / `--q` / `--text` 继续兼容，新的示例统一使用 `--query`。 ## 企业人员搜索 @@ -14,15 +14,15 @@ Usage: dws aisearch person [flags] Example: - dws aisearch person --keyword "张三" --dimension name --format json - dws aisearch person --keyword "产品部" --dimension department --format json - dws aisearch person --keyword "五道" --dimension supervisor --format json - dws aisearch person --keyword "AI搜问" --dimension duty --format json - dws aisearch person --keyword "李四" --dimension name,department --format json - dws aisearch person --keyword "<手机号线索>" --dimension phone --format json - dws aisearch person --keyword "W12345" --dimension jobNumber --format json + dws aisearch person --query "张三" --dimension name --format json + dws aisearch person --query "产品部" --dimension department --format json + dws aisearch person --query "五道" --dimension supervisor --format json + dws aisearch person --query "AI搜问" --dimension duty --format json + dws aisearch person --query "李四" --dimension name,department --format json + dws aisearch person --query "<手机号线索>" --dimension phone --format json + dws aisearch person --query "W12345" --dimension jobNumber --format json Flags: - --keyword string 搜索关键词 (必填，如人名、技能关键词等) + --query string 搜索关键词 (必填，如人名、技能关键词等) --dimension string 查询维度，多个用逗号分隔 (默认 "all") ``` diff --git a/skills/multi/dingtalk-aisearch/references/lite-recipes.md b/skills/multi/dingtalk-aisearch/references/lite-recipes.md index 00f85340..298d421e 100644 --- a/skills/multi/dingtalk-aisearch/references/lite-recipes.md +++ b/skills/multi/dingtalk-aisearch/references/lite-recipes.md @@ -13,7 +13,7 @@ **搜人首选入口**。凡是“找人/搜人/找同事/谁负责/上级/下级/负责人/团队成员”均优先用 `aisearch person`： 1. 从用户问题中提取 keyword（人名/业务关键词）和 dimension（维度），规则见 [aisearch.md](./aisearch.md)。 -2. `aisearch person --keyword "<关键词>" --dimension <维度>` +2. `aisearch person --query "<关键词>" --dimension <维度>` 3. 结果中提取 `userId` 和 `title`（姓名）展示给用户。 4. 若需要 userId 做后续操作（发消息/建待办），可直接使用结果中的 `userId`。 5. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](../../dingtalk-contact/references/08-directory.md)「多命中」。 @@ -26,6 +26,6 @@ - 已有 userId 需查完整详情（`contact user get --ids`） - 完整手机号精确反查（`contact user search-mobile --mobile`） -1. 完整手机号精确反查：`contact user search-mobile --mobile "<手机号>"`；其他搜人：`aisearch person --keyword "<关键词>" --dimension <维度>`。 +1. 完整手机号精确反查：`contact user search-mobile --mobile "<手机号>"`；其他搜人：`aisearch person --query "<关键词>" --dimension <维度>`。 2. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](../../dingtalk-contact/references/08-directory.md)「多命中」。 3. 需详情时：`contact user get --ids `（多人可 `--ids id1,id2,...`）。 diff --git a/skills/multi/dingtalk-calendar/SKILL.md b/skills/multi/dingtalk-calendar/SKILL.md index a06431bd..51cd2453 100644 --- a/skills/multi/dingtalk-calendar/SKILL.md +++ b/skills/multi/dingtalk-calendar/SKILL.md @@ -75,7 +75,7 @@ metadata: **触发**：建日程/约会议/加日程。 -1. **解析与会人（必须）**：对每个姓名 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId`，多人逗号拼接。 +1. **解析与会人（必须）**：对每个姓名 `dws aisearch person --query "<姓名>" --dimension name --format json` 取 `userId`，多人逗号拼接。 2. **执行（必须）**：`dws calendar event create --title "<主题>" --start "" --end "" --attendees --format json`（按需加 `--location`/`--desc`/`--rooms`）。 3. **验证（必须）**：从返回 `result.id` 取日程 ID（下游参数语义称 `eventId`），再执行 `dws calendar event list --start "" --end "" --format json` 复核标题、描述和时段。 @@ -85,7 +85,7 @@ metadata: **触发**：某人/会议室是否有空/找空闲时段/避免冲突。 -1. **解析对象（必须）**：姓名 → `dws aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId`；会议室用 `roomId`。 +1. **解析对象（必须）**：姓名 → `dws aisearch person --query "<姓名>" --dimension name --format json` 取 `userId`；会议室用 `roomId`。 2. **收敛时段（必须）**：`--start`/`--end` **必须**由用户给出或明确收敛；时段不明确**必须先追问**，**禁止**默认全天窗口。 3. **执行（必须）**：`dws calendar busy search --users --start "" --end "" --format json`（查会议室换 `--rooms `，可同时传）。**禁止**用 `event list` 扫日程替代闲忙查询。 4. **空闲时段（必须）**：找共同空闲用 `python scripts/calendar_free_slot_finder.py`。 diff --git a/skills/multi/dingtalk-calendar/references/03-meeting.md b/skills/multi/dingtalk-calendar/references/03-meeting.md index 29f5f1d3..dc432c11 100644 --- a/skills/multi/dingtalk-calendar/references/03-meeting.md +++ b/skills/multi/dingtalk-calendar/references/03-meeting.md @@ -53,4 +53,4 @@ | Recipe | 行动指南（固定路线） | | ------------------ | ------------------- | | schedule-meeting | **见上文「两准则」**、**「搜房失败硬门禁」**。**未给时段且仅说「发起/开个会」**→ 不走本 recipe；当前 CLI 不支持实时视频会议，告知用户请在钉钉客户端操作。**未给时段但有预约意图**（"安排""约""定"等词）：追问具体开始/结束时间。**已有时段后**，按固定顺序执行：1. `dws calendar event create` 建日程；2. 有参会人则 `dws calendar participant add`；3. 再处理会议室。**无明确会议室范围**：可直接 `python scripts/calendar_schedule_meeting.py --title "<主题>" --start "<起始>" --end "<结束>" [--users ] [--book-room] [--dry-run]`。**有明确范围（某楼/层）**：先 `dws calendar room list-groups`，锁定该地点**最相关的承载 group**；若只有一个地点，`--room-group-id` 应只传这个最相关 group，**不要**把同楼内多个楼层 group 打包传入碰运气。只有用户明确给出多个允许地点时，才把这些 `group-id` 一并传给 `python scripts/calendar_schedule_meeting.py ... --book-room --room-group-id ""`。**用户点名具体会议室**：须手工 `dws calendar room search --start "" --end "" --group-id [--available] --format json`（**无** `--query`），在 JSON 中匹配名称取 **`rooms[].roomId` 唯一真值** → `dws calendar room add --event --rooms `；**不得**把用户输入的会议室名当 `roomId`。**一旦连续 2 次空结果 / 任意一次 `roomId invalid`**：**必须回读本节并立即收束判断**；若整园/限定范围内搜尽仍无 roomId 或无空房 → **下一条消息必须直接向用户汇报失败结论**；否则只能向用户确认是否放宽范围/改时间。**禁止**假设 roomId、禁止无 ID 调用 `room add`、禁止用日程详情绕路、禁止继续猜测 Mock/测试环境。细则见「会议室搜索早停」。 | -| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --text "<变更通知>"` 通知变更 | +| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<变更通知>"` 通知变更 | diff --git a/skills/multi/dingtalk-calendar/references/calendar.md b/skills/multi/dingtalk-calendar/references/calendar.md index db2873f9..f6517dbf 100644 --- a/skills/multi/dingtalk-calendar/references/calendar.md +++ b/skills/multi/dingtalk-calendar/references/calendar.md @@ -26,7 +26,7 @@ 日程实例（event instance）：日程的具体时间实例，可以通过event list指令查询时间段内的所有实例。1个普通日程和对应1个Instance，而1个重复性日程(SeriesMaster)对应N个Instance（同属一个日程序列）。 - 同一个日程序列具有相同的iCalUid，并且重复性日程，其eventId和iCalUid的值相同。因此可以通过重复性日程实例的iCalUid得到重复性日程(SeriesMaster)的eventId 重复规则（recurrence rule）：定义重复性日程的重复规则。 -参会人（attendee）：日程的参与者。按姓名统一使用 `dws aisearch person --keyword "姓名" --dimension name --format json` 查询 userId。 +参会人（attendee）：日程的参与者。按姓名统一使用 `dws aisearch person --query "姓名" --dimension name --format json` 查询 userId。 响应状态（response）：参会人对日程的回应，包括：未响应、接受、待定、拒绝。 忙闲时间（busy）：查询用户在指定时间段的忙闲状态，查询会议室在指定时间段的预定状态，用于会议时间协调。 会议室（room）：room是 会议室 ，room可视为日程的资源类参会人，需要加入日程完成预订。注意和location区分，location只是地点，和room不同。 diff --git a/skills/multi/dingtalk-calendar/references/lite-recipes.md b/skills/multi/dingtalk-calendar/references/lite-recipes.md index d538a1b6..f685a26f 100644 --- a/skills/multi/dingtalk-calendar/references/lite-recipes.md +++ b/skills/multi/dingtalk-calendar/references/lite-recipes.md @@ -13,7 +13,7 @@ 查询多人在某时段内的闲忙（**busy**，不是用 `event list` 扫日程）： -1. 解析用户：对每个姓名执行 `aisearch person --keyword "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 [calendar.md](./calendar.md) `busy search` 要求）。 +1. 解析用户：对每个姓名执行 `aisearch person --query "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 [calendar.md](./calendar.md) `busy search` 要求）。 2. 确认时段：用户须给出或可收敛为明确的 `--start` / `--end`（ISO-8601）；若未给出，**先追问**起止时间，禁止用任意默认全天窗口代替用户意图。 3. 执行：`dws calendar busy search --users --start "" --end "" --format json` diff --git a/skills/multi/dingtalk-chat/SKILL.md b/skills/multi/dingtalk-chat/SKILL.md index 27cb6a61..d1e62ea1 100644 --- a/skills/multi/dingtalk-chat/SKILL.md +++ b/skills/multi/dingtalk-chat/SKILL.md @@ -39,8 +39,8 @@ metadata: | 用户意图 | 唯一推荐入口 | 关键边界 | |---|---|---| -| 按姓名发简单文本或 Markdown | `dws chat +dm --to <姓名> --text <内容>` | CLI 解析唯一用户；多候选时停止，不先手工查 ID | -| 按群名或 ID 发简单文本或 Markdown | `dws chat +send-to-group --group <群名或ID> --text <内容>` | 稳定 ID 直接使用；群名多候选时停止 | +| 按姓名发简单文本或 Markdown | `dws chat +dm --to <姓名> --content <内容>` | CLI 解析唯一用户；多候选时停止，不先手工查 ID | +| 按群名或 ID 发简单文本或 Markdown | `dws chat +send-to-group --group <群名或ID> --content <内容>` | 稳定 ID 直接使用；群名多候选时停止 | | 文件、Bot、Webhook、复杂 @ 或高级发送 | `dws chat +messages-send` | Bot 多群用 `--groups/--groups-file` 并检查逐项 ledger | | 读取指定会话、返回较多消息 | `dws chat +chat-messages` | 粗粒度读取；目标条件明确时优先 `+search-msg` | | 多维度条件搜索（发送者/关键词/@/类型，单/跨会话） | `dws chat +search-msg` | 目标条件明确时使用 | diff --git a/skills/multi/dingtalk-chat/references/chat/chat-bot.md b/skills/multi/dingtalk-chat/references/chat/chat-bot.md index 8b246d26..ba5b201d 100644 --- a/skills/multi/dingtalk-chat/references/chat/chat-bot.md +++ b/skills/multi/dingtalk-chat/references/chat/chat-bot.md @@ -121,15 +121,15 @@ dws chat +messages-send --as webhook --webhook-token --title " 以下是底层 fallback，不作为默认选路： ```bash -dws chat message send-by-webhook --token --title "告警" --text "CPU 超 90% @10" --at-all -dws chat message send-by-webhook --token --title "test" --text "hi @118785" --at-users 118785 +dws chat message send-by-webhook --token --title "告警" --content "CPU 超 90% @10" --at-all +dws chat message send-by-webhook --token --title "test" --content "hi @118785" --at-users 118785 ``` 关键规则： -- `--token`、`--title`、`--text` 必填。 -- `--at-all` 时 `--text` 中需包含 `@10`。 -- `--at-users` 或 `--at-mobiles` 时，`--text` 中需包含对应 `@userId` 或 `@手机号`，否则 @ 不生效。 +- `--token`、`--title`、`--content` 必填。 +- `--at-all` 时 `--content` 中需包含 `@10`。 +- `--at-users` 或 `--at-mobiles` 时，`--content` 中需包含对应 `@userId` 或 `@手机号`，否则 @ 不生效。 ### 机器人进群 @@ -167,13 +167,13 @@ dws chat +messages-send --as bot --robot-code --group --text "你好" --format json +dws chat message send --open-dingtalk-id --content "你好" --format json ``` ### 机器人 @ 指定人 ```bash -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json dws chat +messages-send --as bot --robot-code --group --at-user-ids userId1 --title "提醒" --text "@userId1 请查收" --format json ``` diff --git a/skills/multi/dingtalk-chat/references/chat/chat-conversation.md b/skills/multi/dingtalk-chat/references/chat/chat-conversation.md index 0e981be9..10740a5f 100644 --- a/skills/multi/dingtalk-chat/references/chat/chat-conversation.md +++ b/skills/multi/dingtalk-chat/references/chat/chat-conversation.md @@ -30,7 +30,7 @@ dws chat conversation-info --user --format json dws chat conversation-info --open-dingtalk-id --format json ``` -`--group`、`--user`、`--open-dingtalk-id` 互斥且必须指定一个。文件/音视频发送不再依赖调用方读取 spaceId；直接用 `message send --msg-type file|audio|video --file-path`。 +`--group`、`--user`、`--open-dingtalk-id` 互斥且必须指定一个。文件/音视频发送不再依赖调用方读取 spaceId；直接用 `message send --msg-type file|audio|video --file`。 ### 会话列表与红点 @@ -114,7 +114,7 @@ dws chat category add-conv --group --category-ids 123,456 ### 获取单聊会话 ID 后置顶 ```bash -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json dws chat conversation-info --user --format json dws chat set-top --conversation-id --format json ``` @@ -139,7 +139,7 @@ dws chat category list-conversations --category-id --format json ### 智能会话分组 ```bash -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json dws chat category create-smart --name "项目组" --keywords "项目,开发" --format json dws chat category create-smart --name "团队群" --members openDingTalkId1,openDingTalkId2 --format json dws chat category create-smart --name "重点群" --keywords "重点" --members openDingTalkId1 --format json diff --git a/skills/multi/dingtalk-chat/references/chat/message-actions.md b/skills/multi/dingtalk-chat/references/chat/message-actions.md index dc34498f..ffb8a91f 100644 --- a/skills/multi/dingtalk-chat/references/chat/message-actions.md +++ b/skills/multi/dingtalk-chat/references/chat/message-actions.md @@ -63,12 +63,12 @@ Runtime 规范化结果为准，不把裸展示名当稳定身份。 ## 引用回复与转发 -引用回复默认使用 `+messages-reply`。`--conversation-id` 和消息 ID 来自真实查询； +引用回复默认使用 `+messages-reply`。`--group` 和消息 ID 来自真实查询； `--ref-sender` 可省略时让 CLI 只读补齐，不手工猜发送者身份。 ```bash -dws chat +messages-reply --conversation-id \ - --message-id --text "收到" --format json +dws chat +messages-reply --group \ + --message-id --content "收到" --format json ``` | 动作 | 入口 | 关键上下文 | diff --git a/skills/multi/dingtalk-chat/references/chat/message-media.md b/skills/multi/dingtalk-chat/references/chat/message-media.md index d2d660f8..139af2fe 100644 --- a/skills/multi/dingtalk-chat/references/chat/message-media.md +++ b/skills/multi/dingtalk-chat/references/chat/message-media.md @@ -22,7 +22,7 @@ 位置消息必须确认纬度、经度、地址名称和地图缩略图 mediaId： ```bash -dws chat message send --group --msg-type location \ +dws chat message send --conversation-id --msg-type location \ --latitude <纬度> --longitude <经度> --location-name <地址名称> \ --map-thumbnail-url "@mediaId" ``` @@ -30,7 +30,7 @@ dws chat message send --group --msg-type location \ 联系人名片的 `--contact-id` 必须是联系人 `openDingTalkId`，不能把 userId 直接代入： ```bash -dws chat message send --group \ +dws chat message send --conversation-id \ --msg-type profile --contact-id ``` @@ -42,7 +42,7 @@ dws chat message query-send-status --open-task-id --format json 检查真实 `sendStatus`、`openMessageId` 和 `openConversationId`。 -原子 `message send` 只在 Shortcut 缺少真实必需字段时使用。群聊目标用 `--group`；单聊目标 +原子 `message send` 只在 Shortcut 缺少真实必需字段时使用。群聊目标用 `--conversation-id`；单聊目标 用 `--user` 或 `--open-dingtalk-id`，三者通常互斥。发送前核对接收对象、消息类型和资源来源。 ## 资源下载 diff --git a/skills/multi/dingtalk-contact/SKILL.md b/skills/multi/dingtalk-contact/SKILL.md index c3e7b250..76c52aac 100644 --- a/skills/multi/dingtalk-contact/SKILL.md +++ b/skills/multi/dingtalk-contact/SKILL.md @@ -62,7 +62,7 @@ metadata: **触发**：按姓名/工号/部门/职责/上下级找人，或用手机号线索做语义搜索。 -1. **切 aisearch（必须）**：`dws aisearch person --keyword "<关键词>" --dimension <维度> --format json`（姓名→`name`、工号→`jobNumber`、手机号语义线索→`phone`、负责人→`duty`、部门→`department`、上下级→`supervisor`/`subordinate`）。 +1. **切 aisearch（必须）**：`dws aisearch person --query "<关键词>" --dimension <维度> --format json`（姓名→`name`、工号→`jobNumber`、手机号语义线索→`phone`、负责人→`duty`、部门→`department`、上下级→`supervisor`/`subordinate`）。 2. **解析（必须）**：从结果取 `userId`、`title`；**多人同名禁止默认选第一个**，必须批量 `dws contact user get --ids --format json` 拿部门/职位后让用户确认。 3. **补详情（必须）**：要完整部门/职位/邮箱/主管时 `dws contact user get --ids --format json`。 @@ -81,7 +81,7 @@ metadata: **触发**：已有 userId 要查完整详情，或要拿 userId 给下游（发消息/建待办/约日程）。 -1. **拿 userId（必须）**：`dws aisearch person --keyword "<姓名>" --dimension name --format json` → `userId`；多命中必须列候选请用户确认。 +1. **拿 userId（必须）**：`dws aisearch person --query "<姓名>" --dimension name --format json` → `userId`；多命中必须列候选请用户确认。 2. **查详情（必须）**：`dws contact user get --ids --format json`，按返回字段（`orgEmployeeModel` 下部门/职位/邮箱）答复。 **禁止**：用模糊关键词直接调 `contact user search` 凑数、编造未返回字段。 @@ -108,7 +108,7 @@ metadata: - 通讯录问题必须调用 `dws contact` 或 `dws aisearch` 获取实时结果；严禁只读 `USER.md`、环境身份或静态上下文后直接回答。 - 查自己用 `dws contact user get-self --format json`，不要把 `me/self/current` 当作 `userId` 传给 `user get`。 - 姓名模糊搜索、工号反查、职责或上下级搜索走 `dws aisearch person`；完整手机号精确反查走 `dws contact user search-mobile --mobile "<手机号>" --format json`。拿到 `userId` 后按需 `dws contact user get --ids --format json` 补部门/职位/邮箱。 -- 查询直属主管/上下级时，如果 `contact user get` 没返回明确主管字段，必须继续 `dws aisearch person --keyword "<完整姓名或工号>" --dimension supervisor --format json`，不要停在"可能需要进一步查询"。 +- 查询直属主管/上下级时，如果 `contact user get` 没返回明确主管字段，必须继续 `dws aisearch person --query "<完整姓名或工号>" --dimension supervisor --format json`，不要停在"可能需要进一步查询"。 - 多个同名候选时，批量 `contact user get --ids id1,id2,... --format json` 获取部门/职位后再消歧；不要默认取第一个。 - 用户查询企业角色、角色ID、角色成员，或“管理员/财务/HR/主管”等角色类型人员时，走 `contact label list/get/list-members`；不要用 `dept list-members` 筛字段替代。 diff --git a/skills/multi/dingtalk-contact/references/08-directory.md b/skills/multi/dingtalk-contact/references/08-directory.md index b2433676..09363675 100644 --- a/skills/multi/dingtalk-contact/references/08-directory.md +++ b/skills/multi/dingtalk-contact/references/08-directory.md @@ -47,5 +47,5 @@ | explore-subdepts-and-members | 1. 取父部门 `deptId`：用户给了 ID 直接用；只给名字则 `contact dept search --query "<父部门名>"` → 父 `deptId`（多命中先消歧）
2. **优先** `contact dept list-children --dept <父deptId>` 拿到全部直属子 `deptId` 列表；若用户只点名了部分子部门，则改为对每个子部门名 `contact dept search --query "<子部门名>"`
3. 对子 `deptId`：`contact dept list-members --ids ,,...`（多部门按 conventions **并行/批量**）
4. 若还要成员详情：汇总 `userId` → `contact user get --ids …`（≤30 条/批，超出分批 + 用户确认） | | verify-user-in-dept | 同速查表 `verify-user-dept`；多轮对话中用户追加「是否在某部门」时叠加本路线 | | cross-level-dept-members | 1. `contact dept search --query "<父部门关键词>"` → 父 `deptId`
2. **优先** `contact dept list-children --dept <父deptId>` 枚举全部直属子 `deptId`；用户已点名的子部门则用 `dept search` 精确命中
3. 需要逐层下钻时，对上一步拿到的子 `deptId` 继续 `dept list-children` 递归（注意控制深度，避免一次拉太多）
4. `contact dept list-members --ids ` → 按需 `user get` | -| user-detail-organization | 1. `aisearch person --keyword "<关键词>" --dimension <维度>` → `userId`（多结果先消歧）
2. **必须** `contact user get --ids `
3. 若用户同时给出部门语境：叠加 `verify-user-dept` | -| batch-users-by-keyword | 1. `aisearch person --keyword "<职位或技能关键词>" --dimension position,duty` → 多条
2. 提取 `userId`（≤30）→ `contact user get --ids …`
3. 结果过多时汇总或请用户收窄 | +| user-detail-organization | 1. `aisearch person --query "<关键词>" --dimension <维度>` → `userId`（多结果先消歧）
2. **必须** `contact user get --ids `
3. 若用户同时给出部门语境：叠加 `verify-user-dept` | +| batch-users-by-keyword | 1. `aisearch person --query "<职位或技能关键词>" --dimension position,duty` → 多条
2. 提取 `userId`（≤30）→ `contact user get --ids …`
3. 结果过多时汇总或请用户收窄 | diff --git a/skills/multi/dingtalk-contact/references/contact.md b/skills/multi/dingtalk-contact/references/contact.md index 7bf26e5f..b1de47d4 100644 --- a/skills/multi/dingtalk-contact/references/contact.md +++ b/skills/multi/dingtalk-contact/references/contact.md @@ -470,7 +470,7 @@ Notes: dws contact user get-self --format json # 2. 按名字搜索人员 — 统一从 AI 搜问取得 userId/openDingTalkId -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 3. 查看部门结构 — 提取 deptId dws contact dept search --query "技术部" --format json diff --git a/skills/multi/dingtalk-contact/references/lite-recipes.md b/skills/multi/dingtalk-contact/references/lite-recipes.md index 032ed75d..5bfb3ec9 100644 --- a/skills/multi/dingtalk-contact/references/lite-recipes.md +++ b/skills/multi/dingtalk-contact/references/lite-recipes.md @@ -13,7 +13,7 @@ **搜人首选入口**。凡是“找人/搜人/找同事/谁负责/上级/下级/负责人/团队成员”均优先用 `aisearch person`： 1. 从用户问题中提取 keyword（人名/业务关键词）和 dimension（维度），规则见 [aisearch.md](../../dingtalk-aisearch/references/aisearch.md)。 -2. `aisearch person --keyword "<关键词>" --dimension <维度>` +2. `aisearch person --query "<关键词>" --dimension <维度>` 3. 结果中提取 `userId` 和 `title`（姓名）展示给用户。 4. 若需要 userId 做后续操作（发消息/建待办），可直接使用结果中的 `userId`。 5. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](../../dingtalk-contact/references/08-directory.md)「多命中」。 @@ -25,6 +25,6 @@ - 需要获取 userId 给其他产品使用（发消息/建待办/约日程） - 已有 userId 需查完整详情（`contact user get --ids`） -1. `aisearch person --keyword "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 +1. `aisearch person --query "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 2. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 [08-directory.md](../../dingtalk-contact/references/08-directory.md)「多命中」。 3. 需详情时：`contact user get --ids `（多人可 `--ids id1,id2,...`） diff --git a/skills/multi/dingtalk-doc/references/doc/style/doc-update-workflow.md b/skills/multi/dingtalk-doc/references/doc/style/doc-update-workflow.md index 059efe2d..8d9edbd0 100644 --- a/skills/multi/dingtalk-doc/references/doc/style/doc-update-workflow.md +++ b/skills/multi/dingtalk-doc/references/doc/style/doc-update-workflow.md @@ -143,7 +143,7 @@ dws doc +update --node --command append --content @./drafts/-appe dws doc block list --node # 改一个 block 的文本 -dws doc block update --node --block-id --text "替换后的内容" --content-format element +dws doc block update --node --block-id --content "替换后的内容" --content-format element # 在某个 block 后插入 dws doc block insert --node --ref-block --where after --heading "补充说明" --level 2 --content-format element diff --git a/skills/multi/dingtalk-mail/references/mail.md b/skills/multi/dingtalk-mail/references/mail.md index cbcfabd4..4856e9e4 100644 --- a/skills/multi/dingtalk-mail/references/mail.md +++ b/skills/multi/dingtalk-mail/references/mail.md @@ -139,7 +139,7 @@ Flags: ```bash # 主路径：aisearch + contact user get -dws aisearch person --keyword "姓名" --dimension name --format json +dws aisearch person --query "姓名" --dimension name --format json # → 取 userId，再执行： dws contact user get --ids --format json # → 提取 orgAuthEmail 字段 @@ -1725,7 +1725,7 @@ Flags: 用户说"看邮件/打开邮件/邮件内容" → 先 `message search` 获取 messageId，再 `message get` 用户说"发邮件/写邮件" → 先 `mailbox list` 获取发件地址，再 `message send` 用户说“给(某人名字)发邮件” / “查询某人发给我的邮件” / “查询发给某人的邮件” / 任何涉及按人名查找邮箱的场景 → - **第一步**：`aisearch person --keyword <姓名> --dimension name` → `contact user get --ids `，提取 `orgAuthEmail`；为空时再用 `mail user search --email <当前邮箱> --keyword <姓名>` 补查。仍无有效邮箱则 ask_human 请用户提供，禁止臆测。 + **第一步**：`aisearch person --query <姓名> --dimension name` → `contact user get --ids `，提取 `orgAuthEmail`；为空时再用 `mail user search --email <当前邮箱> --query <姓名>` 补查。仍无有效邮箱则 ask_human 请用户提供，禁止臆测。 **第二步**：用获得的目标邮箱拼入 KQL（如 `from:` 或 `to:`）执行 `message search`，或用于 `message send` 用户说"发带附件的邮件/发邮件附件" → 先 `mailbox list` 获取发件地址，再 `message send --attachment <文件路径>` 用户说"给(某人名字)发邮件" → 先 `aisearch person` 获取 userId，再 `contact user get` 获取收件人邮箱，再 `message send` @@ -1880,7 +1880,7 @@ dws mail thread get --email user@company.com --id --format json - `message search` 返回邮件 ID 和元信息（不含正文），需 `message get` 获取完整内容 - KQL 查询支持 AND/OR/NOT 组合，字段值含空格时需用双引号 - `--cc` 抄送人支持多人，逗号分隔 -- 收件人邮箱获取：用户只知道同事名字时，先 `dws aisearch person --keyword "名字" --dimension name` 取得 userId，再 `dws contact user get --ids ` 提取 `orgAuthEmail`。该字段为空时，可用 `dws mail user search --email <发件人邮箱> --keyword "名字"` 补查（仅企业邮箱账号可调用；若已知工号，可改用 `--employee-no <工号>`）。仍无有效邮箱时必须 ask_human，严禁臆测和假设 +- 收件人邮箱获取：用户只知道同事名字时，先 `dws aisearch person --query "名字" --dimension name` 取得 userId，再 `dws contact user get --ids ` 提取 `orgAuthEmail`。该字段为空时，可用 `dws mail user search --email <发件人邮箱> --query "名字"` 补查（仅企业邮箱账号可调用；若已知工号，可改用 `--employee-no <工号>`）。仍无有效邮箱时必须 ask_human，严禁臆测和假设 - `thread list --folder` 的值必须是文件夹 ID，不是文件夹显示名称；不知道文件夹 ID 时，先调用 `folder list` 查 `folders[].id` - `thread get/update/trash/batch-update/batch-trash` 使用的是会话 ID（conversationId），不是邮件 ID；会话 ID 可来自 `thread list` 的 `conversations[].id`，也可来自 `message search` 或 `message get` 返回的 `conversationId` - `thread update` / `thread batch-update` 仅支持 `markRead`、`markUnread`、`addTags`、`removeTags`；标签操作必须传 `--tag-ids` diff --git a/skills/multi/dingtalk-minutes/references/07-minutes.md b/skills/multi/dingtalk-minutes/references/07-minutes.md index df937adc..6b8751e1 100644 --- a/skills/multi/dingtalk-minutes/references/07-minutes.md +++ b/skills/multi/dingtalk-minutes/references/07-minutes.md @@ -27,14 +27,14 @@ dws minutes list mine --limit 5 --format json | Recipe | 行动指南（固定路线） | | ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| meeting-followup | 1. **提取待办优先**：`python scripts/minutes_extract_todos.py [--id ] [--limit N]` → 获取行动项列表 无脚本时按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --keyword "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors --priority <10/20/30/40>`（每条行动项；批量时切到 `dingtalk-todo` 的 batch-create-todo recipe，批量脚本只在该 sub-skill 内可用） 4. `chat message send --group --text "<通知内容>"` 通知已创建 | -| share-minutes | **拉摘要优先**：`python scripts/minutes_recent_summary.py [--limit N] [--output summary.md]` → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`aisearch person --keyword "<姓名>" --dimension name` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --text "<摘要内容>"`（推荐）；群聊：`--group --text "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| meeting-followup | 1. **提取待办优先**：`python scripts/minutes_extract_todos.py [--id ] [--limit N]` → 获取行动项列表 无脚本时按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors --priority <10/20/30/40>`（每条行动项；批量时切到 `dingtalk-todo` 的 batch-create-todo recipe，批量脚本只在该 sub-skill 内可用） 4. `chat message send --group --content "<通知内容>"` 通知已创建 | +| share-minutes | **拉摘要优先**：`python scripts/minutes_recent_summary.py [--limit N] [--output summary.md]` → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`aisearch person --query "<姓名>" --dimension name` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--group --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | browse-minutes | 1. `minutes list all --query "<关键词>" --limit ` → 取全量 `taskUuid`（翻页直至无更多；无主题筛选用 `minutes list mine`；**有时间范围时加 `--start`/`--end` 服务端过滤**，如 `--start "2026-04-01T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00"`） 2. **详情/元数据优先** `minutes get batch --ids `（仅 API 上限时拆多批）；**摘要专项**且无 batch 字段时再用并行 `get summary` 或 `**python scripts/minutes_recent_summary.py --limit `** 3. 汇总展示；**同一用户诉求下避免**「半截 list → 再 list 剩余」「拆 4 条一批 summary 连跑多轮」等无必要拆分 | | minutes-raw-export | 适用"下载/导出最近一周听记原文/逐字稿/转写内容/完整记录"：1. 按用户时间词计算 `--start` / `--end`（最近一周示例：7 天前 00:00:00+08:00 到今天 23:59:59+08:00） 2. `minutes list all --start "" --end "" --format json` 获取范围内所有可见听记；为空时直接说明无相关数据 3. 对列表中每个 `taskUuid` 逐一 `minutes get transcription --id --format json`，如返回 `cursor` / `nextToken` / `nextCursor`，继续用 `--cursor ` 拉完后续页 4. 交付文件或最终回复必须包含各听记的真实转写段落，可附标题/时间/组织，禁止只交 summary 或让用户再选某一条 | | minutes-detail | 1. 确定 `taskUuid`：用户已提供 → 直接用；未提供 → `minutes list mine --limit 5` 让用户选（**有时间线索时加 `--start`/`--end`**，如「上周五的会」→ `--start "2026-05-23T00:00:00+08:00" --end "2026-05-23T23:59:59+08:00"`） 2. 并行拉取四维信息：`minutes get info --id ` `&` `minutes get summary --id ` `&` `minutes get keywords --id ` `&` `minutes get todos --id ` `& wait` 3. 整合输出：基础信息（标题、时间、参与人）→ AI 摘要 → 关键字 → 行动项/待办 4. **展示发言人列表**：从转写/info 提取所有发言人（含已标注姓名和匿名编号），列出每位发言人的发言次数和时长占比，引导用户：「是否需要查看某位发言人的详细内容总结？请输入姓名或编号」→ 用户选定 → 进入 `minutes-speaker-summarize` recipe 5.（可选）用户要求看原文 → `minutes get transcription --id ` | | minutes-speaker-summarize | 1. 读取转写 → `minutes get transcription --id ` 2. 声纹标注检查：已标注 → 跳 Step 6；匿名编号 → 继续 3. 转写原文推断（称呼/自我介绍/上下文指代）→ 高置信度跳 Step 6 4. 并发身份推断：`calendar event list` + `participant list` 取日程参与人（最高优先） & `aisearch person` & `chat message list` & `drive search` `& wait`；未找到同时段日程 → 引导用户提供日程链接或参会人名单；两路以上一致才下结论 5. 置信度判断：>70% 直接输出；≤70% 展示 TOP3 候选让用户选（最多一次） 6. 结构化总结输出（核心观点 + 问题 + Action Item + 立场）→ 追问是否替换发言人标注。详见 [10-minutes-speaker-match.md](./10-minutes-speaker-match.md) | | browse-by-tag | 1. `minutes tag list` → 获取用户标签/分组列表（含 tagId 和名称） 2. 按用户指定的标签名称匹配 tagId（若用户直接提供 tagId 则跳过 Step 1） 3. `minutes tag query --tag-id ` → 返回该标签下的听记列表（支持 `--limit`/`--cursor` 分页） 4. 展示结果，按需调用 `get summary`/`get info` 获取详情 | -| speaker-correct | 1. **查同时段日程**：从听记元数据获取录音开始时间 → `calendar event list`（前后 30 分钟内）→ 若匹配到日程则提取参会人名单并展示 2. **展示发言人状态表格**：列出所有发言人及标注状态（已识别 / 未标注 / 未标注，发言较少） 3. **让用户选择识别方式**：听音识人（裁剪代表性音频片段让用户辨认）/ 手动设置（用户直接告知对应关系）/ 智能匹配（结合参会人名单和发言内容推断） 4. **执行替换**：确认对应关系后统一搜人获取 dingUid → `dws aisearch person --keyword "<姓名>" --dimension name --format json` → 取 userId（长整型）→ `dws minutes speaker replace --id --from "发言人X" --to "<姓名>" --target-uid --format json`；多个匹配时列出候选让用户选；无匹配时执行不带 `--target-uid` 的替换 5. 替换成功后追问「还有其他发言人需要帮你识别和替换吗？」详见 [11-minutes-speaker-correct.md](./11-minutes-speaker-correct.md) | +| speaker-correct | 1. **查同时段日程**：从听记元数据获取录音开始时间 → `calendar event list`（前后 30 分钟内）→ 若匹配到日程则提取参会人名单并展示 2. **展示发言人状态表格**：列出所有发言人及标注状态（已识别 / 未标注 / 未标注，发言较少） 3. **让用户选择识别方式**：听音识人（裁剪代表性音频片段让用户辨认）/ 手动设置（用户直接告知对应关系）/ 智能匹配（结合参会人名单和发言内容推断） 4. **执行替换**：确认对应关系后统一搜人获取 dingUid → `dws aisearch person --query "<姓名>" --dimension name --format json` → 取 userId（长整型）→ `dws minutes speaker replace --id --from "发言人X" --to "<姓名>" --target-uid --format json`；多个匹配时列出候选让用户选；无匹配时执行不带 `--target-uid` 的替换 5. 替换成功后追问「还有其他发言人需要帮你识别和替换吗？」详见 [11-minutes-speaker-correct.md](./11-minutes-speaker-correct.md) | --- diff --git a/skills/multi/dingtalk-minutes/references/10-minutes-speaker-match.md b/skills/multi/dingtalk-minutes/references/10-minutes-speaker-match.md index 671041c6..439c1e79 100644 --- a/skills/multi/dingtalk-minutes/references/10-minutes-speaker-match.md +++ b/skills/multi/dingtalk-minutes/references/10-minutes-speaker-match.md @@ -5,7 +5,7 @@ | Recipe | 行动指南（固定路线） | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| minutes-speaker-summarize | 1. **读取转写**：有 URL → 提取 `taskUuid` → `minutes get transcription --id `；有时间/关键词 → `minutes list all` 筛选 → 获取转写；无信息 → 必须询问 2. **声纹标注检查**：已标注真实姓名 → 直接跳 Step 6；仅匿名编号（发言人1/2/3）→ 继续 3. **转写原文推断**：利用称呼、自我介绍、上下文指代、发言顺序推断，高置信度 → 跳 Step 6；无法确定 → 继续 4. **并发身份推断**：`aisearch person --keyword "<姓名>" --dimension name` & `chat message list` 取近期 IM & `drive search --query "<姓名>"` 前 3 篇 `& wait`；两路以上一致才下结论 5. **置信度判断**：>70% → 直接输出；≤70% → 展示 TOP3 候选音频片段让用户选（最多一次，"都不是"则终止） 6. **结构化总结输出**：核心观点 + 问题/关注点 + Action Item + 立场态度；输出后追问是否替换发言人标注 | +| minutes-speaker-summarize | 1. **读取转写**：有 URL → 提取 `taskUuid` → `minutes get transcription --id `；有时间/关键词 → `minutes list all` 筛选 → 获取转写；无信息 → 必须询问 2. **声纹标注检查**：已标注真实姓名 → 直接跳 Step 6；仅匿名编号（发言人1/2/3）→ 继续 3. **转写原文推断**：利用称呼、自我介绍、上下文指代、发言顺序推断，高置信度 → 跳 Step 6；无法确定 → 继续 4. **并发身份推断**：`aisearch person --query "<姓名>" --dimension name` & `chat message list` 取近期 IM & `drive search --query "<姓名>"` 前 3 篇 `& wait`；两路以上一致才下结论 5. **置信度判断**：>70% → 直接输出；≤70% → 展示 TOP3 候选音频片段让用户选（最多一次，"都不是"则终止） 6. **结构化总结输出**：核心观点 + 问题/关注点 + Action Item + 立场态度；输出后追问是否替换发言人标注 | --- @@ -47,7 +47,7 @@ | 优先级 | 路径 | 做什么 | | ------ | ------------------ | ---------------------------------------------------------------------------------------------------- | | ① 最高 | 日程参与人 | 从听记 info 提取会议时间 → `dws calendar event list --start <会议开始-30min> --end <会议结束+30min>` → 匹配同时段日程 → `dws calendar participant list --event ` → 获取参与人姓名列表，与转写中匿名发言人做数量/顺序对照 | -| ② 高 | 人员 + 组织架构 | `dws aisearch person --keyword <姓名> --dimension name --format json` → userId，再 `dws contact user get --ids ` 补详情 | +| ② 高 | 人员 + 组织架构 | `dws aisearch person --query <姓名> --dimension name --format json` → userId，再 `dws contact user get --ids ` 补详情 | | ③ 高 | 聊天记录 | `dws chat message list` 获取与目标人的近期 IM 消息 → 工作内容/语言风格/职责线索 | | ④ 兜底 | 本人文档 | `dws drive search --query <姓名>` 取前 3 篇标题+摘要 → 角色精确信号 | diff --git a/skills/multi/dingtalk-minutes/references/11-minutes-speaker-correct.md b/skills/multi/dingtalk-minutes/references/11-minutes-speaker-correct.md index 0d21e734..cddf806d 100644 --- a/skills/multi/dingtalk-minutes/references/11-minutes-speaker-correct.md +++ b/skills/multi/dingtalk-minutes/references/11-minutes-speaker-correct.md @@ -83,7 +83,7 @@ ffmpeg -y -ss 465 -i audio.mp3 -t 10 -c copy tmp/发言人3_片段.mp3 -loglevel | 优先级 | 路径 | 做什么 | |--------|------|--------| -| ① 最高 | 人员 + 组织架构 | `dws aisearch person --keyword <姓名> --dimension name` → userId，再 `dws contact user get --ids ` 补部门/职级等详情 | +| ① 最高 | 人员 + 组织架构 | `dws aisearch person --query <姓名> --dimension name` → userId，再 `dws contact user get --ids ` 补部门/职级等详情 | | ② 高 | 聊天记录 | `dws chat message list` 获取与目标人的近期 IM 消息 → 工作内容/语言风格/职责线索 | | ③ 兜底 | 本人文档 | `dws drive search --query <姓名>` 取前 3 篇标题+摘要 → 角色精确信号 | @@ -112,7 +112,7 @@ ffmpeg -y -ss 465 -i audio.mp3 -t 10 -c copy tmp/发言人3_片段.mp3 -loglevel 确认对应关系后，**必须先查询通讯录获取 dingUid**： -1. 调用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` +1. 调用 `dws aisearch person --query "<姓名>" --dimension name --format json` 2. 从返回结果提取 `userId`（长整型数字，即 dingUid） 3. 根据匹配结果执行替换： diff --git a/skills/multi/dingtalk-minutes/references/lite-recipes.md b/skills/multi/dingtalk-minutes/references/lite-recipes.md index c5ffd820..215e01c3 100644 --- a/skills/multi/dingtalk-minutes/references/lite-recipes.md +++ b/skills/multi/dingtalk-minutes/references/lite-recipes.md @@ -67,7 +67,7 @@ dws minutes list shared --query "ROI" --format json - 执行前检查特殊字符（引号/书名号/括号等），若包含先提示用户确认去除 - 替换成功后追问是否加热词：`minutes hot-word add --words "新文字"` - **替换发言人**：先统一搜人取得 dingUid → `minutes speaker replace --id --from "发言人X" --to "姓名" --target-uid ` - - 查询 dingUid：`aisearch person --keyword "姓名" --dimension name --format json` → 取 `userId` + - 查询 dingUid：`aisearch person --query "姓名" --dimension name --format json` → 取 `userId` - 多个匹配 → 列出候选让用户选；无匹配 → 不带 `--target-uid` 执行 - **修改标题**：`minutes update title --id --title "新标题"` - **修改摘要**：`minutes update summary --id --content "新内容"` @@ -88,7 +88,7 @@ dws minutes list shared --query "ROI" --format json ### minutes-permission（权限管理） - 添加成员：`minutes permission add --ids --member-uids --policy 4` - - 需先通过 `aisearch person --keyword "<姓名>" --dimension name` 获取目标 userId + - 需先通过 `aisearch person --query "<姓名>" --dimension name` 获取目标 userId - policy：0=不可见 / 1=仅查看 / 2=查看+下载 / 3=查看+下载+编辑 / 4=全部权限 - 移除成员：`minutes permission remove --ids --member-uids ` diff --git a/skills/multi/dingtalk-minutes/references/minutes.md b/skills/multi/dingtalk-minutes/references/minutes.md index 538e940e..0a7a38f5 100644 --- a/skills/multi/dingtalk-minutes/references/minutes.md +++ b/skills/multi/dingtalk-minutes/references/minutes.md @@ -524,7 +524,7 @@ Flags: > 4. **跳过** — 暂不处理发言人识别 根据用户选择分别处理： - - 选 1 → 进入 `minutes-speaker-summarize` recipe 的智能推断流程（见 [10-minutes-speaker-match.md](10-minutes-speaker-match.md)）。**智能匹配核心：同时发起三路查询、不串行等待**：① 人员+组织架构 `dws aisearch person --keyword <姓名> --dimension name` → userId，再用 `dws contact user get --ids ` 补部门/职级；② 聊天记录 `dws chat message list` → 工作内容/语言风格/职责线索；③ 本人文档 `dws doc search --keyword <姓名>` 前 3 篇 → 角色精确信号。**判定**：通讯录+聊天两路一致即可确认角色（通常无需查文档），仅一路或矛盾时补查文档兜底、两路以上一致才下结论；部门名 ≠ 角色。**文档角色对照**：PRD/需求/商业化方案→产品经理，视觉规范/原型/交互评审→产品设计师，技术方案/架构→研发，分析报告/底表→数据分析师。**置信度分支**：> 70% 输出匹配结果并执行替换，< 70% 不输出、请用户补充信息或改用手动设置 + - 选 1 → 进入 `minutes-speaker-summarize` recipe 的智能推断流程（见 [10-minutes-speaker-match.md](10-minutes-speaker-match.md)）。**智能匹配核心：同时发起三路查询、不串行等待**：① 人员+组织架构 `dws aisearch person --query <姓名> --dimension name` → userId，再用 `dws contact user get --ids ` 补部门/职级；② 聊天记录 `dws chat message list` → 工作内容/语言风格/职责线索；③ 本人文档 `dws doc search --query <姓名>` 前 3 篇 → 角色精确信号。**判定**：通讯录+聊天两路一致即可确认角色（通常无需查文档），仅一路或矛盾时补查文档兜底、两路以上一致才下结论；部门名 ≠ 角色。**文档角色对照**：PRD/需求/商业化方案→产品经理，视觉规范/原型/交互评审→产品设计师，技术方案/架构→研发，分析报告/底表→数据分析师。**置信度分支**：> 70% 输出匹配结果并执行替换，< 70% 不输出、请用户补充信息或改用手动设置 - 选 2 → 请用户提供日程链接或参会人姓名列表： - 有日程链接 → 从链接提取 eventId → `dws calendar participant list --event ` 获取参与人 → 与转写发言人数量/顺序对照匹配 → 展示匹配结果请用户确认 → 确认后逐条执行 `speaker replace` - 有参会人名单（用户直接列出姓名）→ 与转写中匿名发言人做数量对照 → 结合发言内容/角色推断匹配 → 展示匹配结果请用户确认 → 确认后逐条执行 `speaker replace` @@ -811,7 +811,7 @@ Step 7: 引导用户替换发言人（调用 speaker replace 写回听记） | 路径 | 命令 | 得到什么 | |------|------|----------| -| ① 人员与组织架构 | `dws aisearch person --keyword "目标人名" --dimension name` → userId，再用 `dws contact user get --ids ` 补详情 | 职能大类（技术/产品/设计/管理）+ 是否存在该人 | +| ① 人员与组织架构 | `dws aisearch person --query "目标人名" --dimension name` → userId，再用 `dws contact user get --ids ` 补详情 | 职能大类（技术/产品/设计/管理）+ 是否存在该人 | | ② 本人创建的文档 | `dws doc search --keyword "目标人名/真名"` 至少获取 3 篇标题 | 角色精确信号（PM写PRD、研发写技术方案、设计师写视觉规范）| | ③ 近期日程类型 | `dws calendar event list` | 职能边界（参加什么类型的会）| | ④ 聊天记录 | `dws chat message list` 获取与目标人的近期 IM 消息 | 语言风格/工作内容/职责线索 | @@ -887,7 +887,7 @@ Step 7: 引导用户替换发言人（调用 speaker replace 写回听记） > "目前这篇听记中 [人名] 的发言仍显示为『发言人X』。要我帮你把听记里的『发言人X』全部替换为『[人名]』吗？替换后纪要和待办中的发言人也会同步更新。 > 确认后我会执行：`dws minutes speaker replace --id --from "发言人X" --to "[人名]"`" -- 用户确认 → **先统一搜人** `dws aisearch person --keyword "[人名]" --dimension name --format json` 获取该人员的 userId（长整型 dingUid）： +- 用户确认 → **先统一搜人** `dws aisearch person --query "[人名]" --dimension name --format json` 获取该人员的 userId（长整型 dingUid）： - 唯一匹配 → 告知用户匹配结果，确认后执行 `dws minutes speaker replace --id --from "发言人X" --to "[人名]" --target-uid --format json` - 多个匹配 → 列出候选（姓名+部门+userId）让用户选择后执行 - 无匹配 → 提示用户未在通讯录中找到此人，执行不带 `--target-uid` 的替换：`dws minutes speaker replace --id --from "发言人X" --to "[人名]" --format json` @@ -1490,7 +1490,7 @@ tagId 可通过 `dws minutes tag list` 获取。 1. 用户提供目标姓名（如"张三"）后，**AI 主动调用通讯录模糊查询**： ``` - dws aisearch person --keyword "张三" --dimension name --format json + dws aisearch person --query "张三" --dimension name --format json ``` 2. 从返回结果中提取匹配的人员列表，每条包含 `userId`（长整型数字，即 dingUid）和姓名： - **唯一匹配** → 直接向用户确认："通讯录中找到『张三（userId: 123456789）』，确认将发言人替换为此人并关联通讯录身份？" @@ -1521,7 +1521,7 @@ tagId 可通过 `dws minutes tag list` 获取。 **AI 识别到上述模式时，必须执行以下流程：** 1. **解析映射关系**：提取所有 `源发言人 → 目标姓名` 的配对 -2. **批量人员查询**：对每个目标姓名调用 `dws aisearch person --keyword "<姓名>" --dimension name --format json`，获取 userId（dingUid）。将查询结果汇总后一并向用户确认 +2. **批量人员查询**：对每个目标姓名调用 `dws aisearch person --query "<姓名>" --dimension name --format json`，获取 userId（dingUid）。将查询结果汇总后一并向用户确认 3. **向用户确认**：展示解析结果（含通讯录匹配）并请求确认，格式如下： > 我识别到以下发言人对应关系，并已从通讯录中匹配到对应人员： @@ -1771,11 +1771,11 @@ tagId 可通过 `dws minutes tag list` 获取。 - 用户提到"移除/取消/删除/不让...看"等移除权限语义 → `permission remove` - 用户提到"我没权限/打不开/帮我申请/申请查看权限/申请编辑权限"等**为自己申请**语义 → `permission apply`（只需 `--id` + `--policy`；**不需要也不接受 `--member-uids`**，当前用户身份由系统自动识别；未说明权限等级时先与用户确认要 2（可编辑）/ 3（可查看下载）/ 4（仅查看）） - `permission add` 的 `--policy` 是必填参数，没有默认值。用户未指定权限类型时，先确认要 0（管理员）/ 1（所有者）/ 2（可编辑）/ 3（可查看下载）/ 4（仅查看）；即使确认选择 4，命令中仍必须显式传入 `--policy 4` -- `permission add` / `permission remove` 需要目标成员的钉钉 UID：如果用户未提供 member-uids，需要先引导用户提供（可通过 `dws aisearch person --keyword "姓名" --dimension name` 查询）；`permission apply` 不适用这一条 +- `permission add` / `permission remove` 需要目标成员的钉钉 UID：如果用户未提供 member-uids，需要先引导用户提供（可通过 `dws aisearch person --query "姓名" --dimension name` 查询）；`permission apply` 不适用这一条 **典型执行链路：** 1. 用户说"把张三加到这个听记中" → AI 需获取张三的 UID -2. 调用 `dws aisearch person --keyword "张三" --dimension name --format json` 获取 UID +2. 调用 `dws aisearch person --query "张三" --dimension name --format json` 获取 UID 3. 调用 `dws minutes permission add --ids --member-uids --policy 4 --format json` ### 听记标签/分组查询 @@ -2305,7 +2305,7 @@ https://shanji.dingtalk.com/app/transcribes/76327569643231383535353939365f343638 5. 用户确认 → **Step 6 结构化总结输出**：提取发言人2 的全部发言，输出张三的核心观点、关键决策、待办等 6. **Step 7 引导替换发言人**（必须执行）： > "目前这篇听记中张三的发言仍显示为『发言人2』。要我帮你把听记里的『发言人2』全部替换为『张三』吗？替换后纪要和待办中的发言人也会同步更新。" -7. 用户确认 → **先统一搜人获取 dingUid**：调用 `dws aisearch person --keyword "张三" --dimension name --format json` +7. 用户确认 → **先统一搜人获取 dingUid**：调用 `dws aisearch person --query "张三" --dimension name --format json` - 唯一匹配（如返回 userId=123456789）→ 执行 `dws minutes speaker replace --id --from "发言人2" --to "张三" --target-uid 123456789 --format json` - 多个匹配 → 列出候选（姓名+部门+userId）让用户选择后执行 - 无匹配 → 提示用户通讯录未找到，执行不带 `--target-uid` 的替换：`dws minutes speaker replace --id --from "发言人2" --to "张三" --format json` @@ -2350,7 +2350,7 @@ https://shanji.dingtalk.com/app/transcribes/ 分析下木兰讲了什 | 路径 | 命令 | 结果 | |------|------|------| -| ① 人员与组织架构 | `dws aisearch person --keyword "木兰" --dimension name` → `dws contact user get --ids ` | 木兰 = **王佳明**，X 事业群-X 事业部-X-X-**产品设计部**，上级临渊（王临一）| +| ① 人员与组织架构 | `dws aisearch person --query "木兰" --dimension name` → `dws contact user get --ids ` | 木兰 = **王佳明**，X 事业群-X 事业部-X-X-**产品设计部**，上级临渊（王临一）| | ② 文档产出 | `dws drive search --query "王佳明"`（按需）| 多为设计稿/原型，进一步印证设计师角色 | **Step 5：定向匹配 + 置信度判断** @@ -2455,7 +2455,7 @@ Step 2 **[禁止]** 看到全是匿名编号 → 没有继续走 Step 3-4，反 |--------|------------|------| | 在转写文本里 grep "木兰" 字符串作为存在性判断 | 铁律 1 | 99% 听记的发言人都是匿名编号，搜不到字面是默认场景，根本不构成"没参会"的证据 | | 用 AI 摘要的"参与人=拾光"推断"木兰没参会" | 铁律 2 | AI 摘要"参与人"字段只截取最显著的 1-2 人，**不是**完整参会名册 | -| 全程没调用过一次 `dws aisearch person --keyword "木兰" --dimension name` | 铁律 3 | 人员搜索是 Step 4 的必跑项，拿到 userId 后再由 contact 补详情 | +| 全程没调用过一次 `dws aisearch person --query "木兰" --dimension name` | 铁律 3 | 人员搜索是 Step 4 的必跑项，拿到 userId 后再由 contact 补详情 | | 一旦字面搜不到就放弃身份推断，把任务甩给用户 | 铁律 4 | 这恰恰把发言人识别功能的核心价值（把匿名编号映射到真实人）完全抹掉了 | **[正确] 应该这样执行（与案例 6 一致）：** @@ -2463,7 +2463,7 @@ Step 2 **[禁止]** 看到全是匿名编号 → 没有继续走 Step 3-4，反 1. **Step 1**：从 URL 提取 taskUuid → `dws minutes get transcription` 自动翻页拉全部 2. **Step 2**：检查 `speakerNick` 字段是否含"木兰"——发现全是匿名编号 → **不要在转写文本里 grep "木兰"，立即并发触发 Step 3 + Step 4 ①** 3. **Step 3**（与 Step 4 ① 并发）：在转写里做发言人画像（每位发言人的发言量、主题、互斥线索） -4. **Step 4 ①**（与 Step 3 并发，必跑）：`dws aisearch person --keyword "木兰" --dimension name` → userId，再 `dws contact user get --ids ` 补部门等详情 +4. **Step 4 ①**（与 Step 3 并发，必跑）：`dws aisearch person --query "木兰" --dimension name` → userId，再 `dws contact user get --ids ` 补部门等详情 5. **Step 5**：把"产品设计部 + 设计师角色"信号回投到画像 → 锁定发言人1（UI/交互设计视角高度匹配）+ 与拾光的同部门协作信号 → 置信度 ≈ 75% → 走分支 A 6. **Step 5 用户确认**：展示发言人1 的代表性片段请用户确认 7. **Step 6**：四段式结构化总结（核心观点/关注点/Action Item/立场态度） @@ -2478,7 +2478,7 @@ Step 2 **[禁止]** 看到全是匿名编号 → 没有继续走 Step 3-4，反 3. **`dws aisearch person` 是 Step 4 ① 的必跑项**：先找到人员并取得 userId，再用 `dws contact user get` 补部门等详情；拿到"木兰=王佳明，产品设计部"后，Step 5 的角色匹配才有可靠锚点。 4. **想说"找不到 X"前的四个自检问题**（任何一个回答"没"都禁止给"找不到"结论）： - - 人员搜了吗？(`dws aisearch person --keyword "X" --dimension name`) + - 人员搜了吗？(`dws aisearch person --query "X" --dimension name`) - 文档查了吗？(`dws drive search --query "X"`) - 聊天记录查了吗？(`dws chat message list`) - 基于角色在转写里做模式匹配了吗？（设计师 vs 研发 vs 管理者的发言特征） diff --git a/skills/multi/dingtalk-misc/references/05-reporting.md b/skills/multi/dingtalk-misc/references/05-reporting.md index 503d4b52..a3997286 100644 --- a/skills/multi/dingtalk-misc/references/05-reporting.md +++ b/skills/multi/dingtalk-misc/references/05-reporting.md @@ -21,7 +21,7 @@ | Recipe | 行动指南（固定路线） | |--------|-------------------| -| query-report | **0. 前置判定**：query 含「查日志 / 看日志 / 我发过的日志 / 收到的日志 / 日志详情」且语义指向钉钉日志 OA 应用？是 → 直接走 `dws report`；CSV 附件、群聊导出日志、系统日志或聊天记录核验不属于 OA 日志，应转到文件/群聊/表格相关 skill；其余歧义先按 doc/report 分歧澄清
1. 第一条有效查询必须按视角选择新命令：用户说「我发过 / 我创建 / 已发送」→ `report outbox list --cursor 0 --size 20 --format json`；用户说「收到 / 收件箱 / 别人发给我 / 最近收到」→ `report inbox list --start "" --end "" --cursor 0 --size 20 --format json`；不要先生成 `report list` / `report sent` 等 deprecated alias，也不要用 inbox 代替 outbox
2. 时间 flag 只允许 `--start` / `--end`；裸日期必须展开完整 ISO + `+08:00`；禁止 `--start-date` / `--end-date` / `--date`、UTC `Z`、`date -u`；用户只说「最近 / 近期 / 最近收到 / 最近一周」默认最近 7 天；`--size` 最大 20，更多结果按 `cursor` 分页，禁止传 50/100
3. 按发件人查收件箱时，先 `aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId/staffId`，再给 `inbox list` 加 `--sender-user-ids `；如果列表中找不到目标发件人或目标标记日志，必须说明不可见 / 未找到，不得改选其他发件人或其他日志
4. 从列表返回中取 `reportId` 留给内部后续调用；如果用户已直接提供 `reportId`，跳过列表；面向用户展示列表时基于 `result[]` 拼 Markdown 表：`日期 | 标题 | 发送人 | 状态 | 钉钉链接`，不要把日志 ID 作为主列，缺失字段不编造
5. 用户要正文、详情、汇总、总结多篇日志或检查内容时，必须对选中的每篇日志逐条执行 `report entry get --report-id --format json`；例如“总结最近收到的 5 篇”应先 list 取前 5 篇（不足 5 篇按实际数量说明），再执行相同数量的 `entry get`；用户要统计 / 已读情况时执行 `report entry stats --report-id --format json`
**不要把 inbox list/outbox list 当正文接口**；查询正文必须补 `entry get`
**不要再生成** `report list` / `report sent` / `report detail` / `report stats`（deprecated alias，仍能跑但会打 stderr 警告） | +| query-report | **0. 前置判定**：query 含「查日志 / 看日志 / 我发过的日志 / 收到的日志 / 日志详情」且语义指向钉钉日志 OA 应用？是 → 直接走 `dws report`；CSV 附件、群聊导出日志、系统日志或聊天记录核验不属于 OA 日志，应转到文件/群聊/表格相关 skill；其余歧义先按 doc/report 分歧澄清
1. 第一条有效查询必须按视角选择新命令：用户说「我发过 / 我创建 / 已发送」→ `report outbox list --cursor 0 --size 20 --format json`；用户说「收到 / 收件箱 / 别人发给我 / 最近收到」→ `report inbox list --start "" --end "" --cursor 0 --size 20 --format json`；不要先生成 `report list` / `report sent` 等 deprecated alias，也不要用 inbox 代替 outbox
2. 时间 flag 只允许 `--start` / `--end`；裸日期必须展开完整 ISO + `+08:00`；禁止 `--start-date` / `--end-date` / `--date`、UTC `Z`、`date -u`；用户只说「最近 / 近期 / 最近收到 / 最近一周」默认最近 7 天；`--size` 最大 20，更多结果按 `cursor` 分页，禁止传 50/100
3. 按发件人查收件箱时，先 `aisearch person --query "<姓名>" --dimension name --format json` 取 `userId/staffId`，再给 `inbox list` 加 `--sender-user-ids `；如果列表中找不到目标发件人或目标标记日志，必须说明不可见 / 未找到，不得改选其他发件人或其他日志
4. 从列表返回中取 `reportId` 留给内部后续调用；如果用户已直接提供 `reportId`，跳过列表；面向用户展示列表时基于 `result[]` 拼 Markdown 表：`日期 | 标题 | 发送人 | 状态 | 钉钉链接`，不要把日志 ID 作为主列，缺失字段不编造
5. 用户要正文、详情、汇总、总结多篇日志或检查内容时，必须对选中的每篇日志逐条执行 `report entry get --report-id --format json`；例如“总结最近收到的 5 篇”应先 list 取前 5 篇（不足 5 篇按实际数量说明），再执行相同数量的 `entry get`；用户要统计 / 已读情况时执行 `report entry stats --report-id --format json`
**不要把 inbox list/outbox list 当正文接口**；查询正文必须补 `entry get`
**不要再生成** `report list` / `report sent` / `report detail` / `report stats`（deprecated alias，仍能跑但会打 stderr 警告） | | generate-daily-report | 1. 按[「多源并行采集」](./report-conventions.md#多源并行采集公共模式)执行（时间=今日）
2. 交叉汇总并把日报内容写入临时文件 `.md`（UTF-8，真实换行）
3. **创建文档**：`doc create --name "<日报名>" --content-file .md`（> 200KB 按 write-doc 兜底（见 `dingtalk-doc/references/04-document.md`） 走 create 空 → 循环 update） | | generate-weekly-report | 1. 按[「多源并行采集」](./report-conventions.md#多源并行采集公共模式)执行（时间=本周）
2. 交叉对比并把周报内容写入临时文件 `.md`
3. **创建文档**：`doc create --name "<周报名>" --content-file .md`（兜底同上） | | submit-report | **0. 前置判定**：query 含「钉钉日志 / OA 周报模板 / 我的钉钉日志」等强信号？是 → 继续；否 → 切换到 `generate-weekly-report` 或 `generate-daily-report`（走 dws doc）
1. 按[「多源并行采集」](./report-conventions.md#多源并行采集公共模式)执行（时间=当日）
2. `report template list --format json` → 取 `report_template_id`
3. `report template get --name "<模版名>" --format json` → 取 `result.report_template_fields[]`，每项含 `field_name`/`field_sort`/`field_type`
4. **把 contents 写入临时文件**（避免 shell 引号问题）：每项含 `key`/`sort`/`content`/`contentType`/`type` 五个字段，**严格映射** `field_name → key`、`field_sort → sort`、`field_type → type`，再填 `content` 与 `contentType`
5. `report entry submit --template-id --contents-file .json --format json` → CLI 会在提交成功后自动反查详情并追加 `dingtalkOpenMarkdownLink` / `dingtalkOpenUrl` / `dingtalkOpenLink` 字段；取返回的 `reportId` 与钉钉打开链接
6. final reply 优先直接使用 `dingtalkOpenMarkdownLink`，让用户点击跳转钉钉客户端查看 / 修改；仅当 submit 返回中缺少 `dingtalkOpenUrl` 时，才手动执行 `report entry get --report-id --format json` 补取 `result.url`，再包装成 `[在钉钉中查看日志](result.url)`
**不要走 doc 写文档**；**禁止跳过 2/3 步**直接 submit；**禁止把 raw `dingtalk://...` URL 直接粘到回复**，必须包成 markdown link
**不要再生成** `report template detail` / `report create`（deprecated alias，仍能跑但会打 stderr 警告） | diff --git a/skills/multi/dingtalk-misc/references/attendance-report.md b/skills/multi/dingtalk-misc/references/attendance-report.md index bbfc5cbf..7acbc610 100644 --- a/skills/multi/dingtalk-misc/references/attendance-report.md +++ b/skills/multi/dingtalk-misc/references/attendance-report.md @@ -126,7 +126,7 @@ Agent 解析用户意图（报表类型、人员范围、时间范围、关注 **场景 A — 指定员工姓名**: ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**: diff --git a/skills/multi/dingtalk-misc/references/attendance-schedule.md b/skills/multi/dingtalk-misc/references/attendance-schedule.md index 9175261a..86c19ad0 100644 --- a/skills/multi/dingtalk-misc/references/attendance-schedule.md +++ b/skills/multi/dingtalk-misc/references/attendance-schedule.md @@ -224,7 +224,7 @@ dws attendance group search --query "<考勤组名称>" --type TURN --format jso **场景 A — 指定员工姓名**： ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**： @@ -450,7 +450,7 @@ dws attendance group get --group-id --format json # ⚠️ 禁止用 class search 全局搜索班次 # 2. 获取员工 userId -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 3. 回显确认（Agent 向用户展示排班表格） # ... 用户确认 ... @@ -473,7 +473,7 @@ dws attendance group get --group-id --format json # → 确认是排班制（TURN） # 2. 获取员工 userId -dws aisearch person --keyword "李四" --dimension name --format json +dws aisearch person --query "李四" --dimension name --format json # 3. 回显确认 → 用户确认 → 执行 python scripts/attendance_schedule_import.py \ @@ -579,8 +579,8 @@ python scripts/attendance_schedule_export.py \ ```bash # 1. 获取 userId -dws aisearch person --keyword "张三" --dimension name --format json -dws aisearch person --keyword "李四" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json +dws aisearch person --query "李四" --dimension name --format json # 2. 调用脚本导出 python scripts/attendance_schedule_export.py \ diff --git a/skills/multi/dingtalk-misc/references/attendance-vacation.md b/skills/multi/dingtalk-misc/references/attendance-vacation.md index afeee1eb..c20c2b58 100644 --- a/skills/multi/dingtalk-misc/references/attendance-vacation.md +++ b/skills/multi/dingtalk-misc/references/attendance-vacation.md @@ -63,7 +63,7 @@ Agent 只负责解析人员范围并获取 userId 列表；假期规则查询、 ### 阶段 0：参数解析 1. 识别人员范围： - - 指定员工姓名：用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取 userId + - 指定员工姓名：用 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取 userId - 指定部门：用 `dws contact dept search --query "<部门名>" --format json`，再用 `dws contact dept list-members --ids --format json` 获取成员 - 已提供 userId：直接使用 2. 识别假期列范围： @@ -74,7 +74,7 @@ Agent 只负责解析人员范围并获取 userId 列表；假期规则查询、 **场景 A — 指定员工姓名**: ```bash -dws aisearch person --keyword "<员工姓名>" --dimension name --format json +dws aisearch person --query "<员工姓名>" --dimension name --format json ``` **场景 B — 按部门查询**: diff --git a/skills/multi/dingtalk-misc/references/ding.md b/skills/multi/dingtalk-misc/references/ding.md index b2de0b28..5cce1ce6 100644 --- a/skills/multi/dingtalk-misc/references/ding.md +++ b/skills/multi/dingtalk-misc/references/ding.md @@ -57,7 +57,7 @@ Usage: Example: dws ding message send-personal --users openDingTalkId1,openDingTalkId2 --content "请查看" dws ding message send-personal --type call --users openDingTalkId1 --content "紧急告警" - # 查询 openDingTalkId: dws aisearch person --keyword "姓名" --dimension name + # 查询 openDingTalkId: dws aisearch person --query "姓名" --dimension name Flags: --users string 接收者 openDingTalkId 列表，逗号分隔 (必填) --content string DING 内容 (必填) @@ -66,7 +66,7 @@ Flags: 注意: - 与 `ding message send`（机器人身份）不同：send-personal 以当前用户身份发送，无需 --robot-code - - 接收者使用 openDingTalkId（非 userId），可通过 `dws aisearch person --keyword "姓名" --dimension name` 获取 + - 接收者使用 openDingTalkId（非 userId），可通过 `dws aisearch person --query "姓名" --dimension name` 获取 - sms/call 类型有通信费用，使用前需和用户确认 ``` @@ -92,7 +92,7 @@ Usage: Example: dws ding message send-by-message --group --message-id --users id1,id2 dws ding message send-by-message --group --message-id --users id1 --type sms - # 查询 openDingTalkId: dws aisearch person --keyword "姓名" --dimension name + # 查询 openDingTalkId: dws aisearch person --query "姓名" --dimension name # 查询 openConversationId: dws chat search --keyword "群名" Flags: --group string 原消息所在会话 openConversationId (必填) @@ -103,7 +103,7 @@ Flags: 注意: - 与 `send-personal` 不同: send-by-message 是将已有聊天消息转发为 DING，需要指定原消息的会话和消息 ID - - 接收者使用 openDingTalkId，可通过 `dws aisearch person --keyword "姓名" --dimension name` 获取 + - 接收者使用 openDingTalkId，可通过 `dws aisearch person --query "姓名" --dimension name` 获取 - sms/call 类型有通信费用，使用前需和用户确认 ``` @@ -157,7 +157,7 @@ dws ding message recall-personal --id --format json ## 注意事项 - `--robot-code` 从钉钉开放平台 应用管理 → 机器人 中获取，也可设环境变量 `DINGTALK_DING_ROBOT_CODE` - `send` / `recall` 是机器人身份，需要 --robot-code；`send-personal` / `recall-personal` / `send-by-message` 是用户身份，无需 robot-code -- `send` 接收者使用 userId；`send-personal` / `send-by-message` 接收者使用 openDingTalkId（可通过 `dws aisearch person --keyword "姓名" --dimension name` 获取） +- `send` 接收者使用 userId；`send-personal` / `send-by-message` 接收者使用 openDingTalkId（可通过 `dws aisearch person --query "姓名" --dimension name` 获取） - `send-by-message` 是将已有聊天消息转发为 DING，需指定 --group 和 --message-id - sms/call 类型有通信费用，使用前需和用户确认 - 默认 `--type app` 为应用内 DING（免费） diff --git a/skills/multi/dingtalk-misc/references/oa.md b/skills/multi/dingtalk-misc/references/oa.md index 7124e064..0f218814 100644 --- a/skills/multi/dingtalk-misc/references/oa.md +++ b/skills/multi/dingtalk-misc/references/oa.md @@ -254,7 +254,7 @@ Flags: a. 向用户展示每个节点的名称、类型、已指定处理人 b. 若 targetSelect == true： - 提示用户"节点「{activityName}」需要您自选{actorType}人" - - 使用 dws aisearch person --keyword "<姓名>" --dimension name --format json 帮用户查找并选人 + - 使用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户查找并选人 - 记录 activityId 和用户选择的 userIds 3. 将自选结果组装为 targetSelectActioners，传入 create-instance 高级模式 --request ``` @@ -288,7 +288,7 @@ Flags: - **如果用户明确给出 `processCode`，固定走 `form-schema` → 收集表单值 → `forecast-process` → 自选节点选人 → `create-instance`**，不要跳过 `form-schema` 直接拼请求。 - **`form-schema` 返回的 `content` 不是创建 payload 的原样模板。** 它主要用于识别控件 `label`（即 name）、`id`、控件类型（componentName）和选项值范围；真正的 `formComponentValues` 中 `value` 结构以本文的控件值格式表为准。 - **`forecast-process` 返回的自选节点必须在发起前让用户选人。** 若 `workflowActivityRuleVOs` 中有 `targetSelect: true` 的节点，必须提示用户选择处理人，并将结果通过 `targetSelectActioners` 传入 `create-instance`。 -- **所有人员类参数使用 userId。** 若用户给的是姓名，先用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 解析成 userId。**严禁把姓名直接写进** `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。 +- **所有人员类参数使用 userId。** 若用户给的是姓名，先用 `dws aisearch person --query "<姓名>" --dimension name --format json` 解析成 userId。**严禁把姓名直接写进** `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。 - **创建实例前一次性汇总确认。** `create-instance` 是写操作，执行前一次性展示模板、表单值、流程预测结果和审批人/抄送人供用户确认。 #### 严禁行为 @@ -297,7 +297,7 @@ Flags: - **严禁复用旧的 Schema 结果。** 每次发起实例前都必须重新调用 `form-schema`，模板可能已被修改。 - **严禁在存在不支持必填控件时强行发起。** 若 `form-schema` 返回的必填控件中有不支持类型（如附件等），直接告知用户不支持通过 CLI 发起。 - **严禁把 `form-schema` 返回的 `content` 当成可直接提交的 payload 模板。** -- **严禁把姓名直接写进 `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。** 必须先通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 转成 userId。 +- **严禁把姓名直接写进 `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。** 必须先通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 转成 userId。 - **严禁在未得到用户确认前直接执行真实提单。** - **严禁猜测控件名称或选项值。** 必须从 `form-schema` 返回中提取。 - **严禁跳过 `forecast-process` 中的自选节点选人。** 若预测返回 `targetSelect: true` 的节点，必须让用户选人后再发起。 @@ -310,7 +310,7 @@ Flags: | 已拿到 `processCode` | 直接 `form-schema --process-code ` | | 已拿到 Schema | 向用户展示控件列表，收集表单值 | | 已收集表单值 | `forecast-process` 预测流程走向 | -| 预测返回有 `targetSelect: true` 节点 | 让用户为自选节点选人（`dws aisearch person --keyword "<姓名>" --dimension name --format json` 解析姓名） | +| 预测返回有 `targetSelect: true` 节点 | 让用户为自选节点选人（`dws aisearch person --query "<姓名>" --dimension name --format json` 解析姓名） | | 预测完成，自选节点已选人 | 汇总确认后 `create-instance --yes` | | 用户明确说"不走模板流程，直接指定审批人" | 使用 `directAppointedApprovers`（高级模式） | @@ -322,7 +322,7 @@ Flags: 3. 检查 Schema 中是否有不支持的必填控件 → 若有则直接告知用户不支持发起 4. 收集表单值 → 向用户展示控件列表，收集用户填写的表单值 5. forecast-process → 根据表单值预测流程走向，识别自选节点 -6. 自选节点选人 → 若预测返回 targetSelect=true 的节点，让用户选人（用 dws aisearch person --keyword "<姓名>" --dimension name --format json 解析姓名） +6. 自选节点选人 → 若预测返回 targetSelect=true 的节点，让用户选人（用 dws aisearch person --query "<姓名>" --dimension name --format json 解析姓名） 7. 汇总确认后 create-instance --yes → 展示完整信息（表单值 + 流程路径 + 审批人），用户确认后执行发起 ``` @@ -337,7 +337,7 @@ Flags: 2. **流程预测后再选自选审批人（步骤 5→6）：** `forecast-process` 返回流程路径和自选节点后： - 先向用户展示完整的流程路径（经过哪些节点、各节点处理人） - 对 `targetSelect: true` 的节点，提示用户"节点「{activityName}」需要您自选{actorType}人" - - 用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 帮用户查找并选人 + - 用 `dws aisearch person --query "<姓名>" --dimension name --format json` 帮用户查找并选人 - 若有多个自选节点，一次性收集所有自选节点的选人结果 3. **单次汇总确认（步骤 7）：** 发起前一次性展示完整信息供用户确认： @@ -388,7 +388,7 @@ Flags: - 先用 `form-schema` 识别有哪些控件、每个控件的 `label`（name）、`componentName`（type）、选项值范围以及明细子控件结构。 - **`form-schema` 返回的 `content` 不是可直接提交的原样模板。** 它提供控件定义，`value` 结构须按下方控件值格式表组装。 - 提交时必须保证每个控件的 `name`（即 label）与 Schema 中的 `props.label` **完全一致**。 -- 如果用户提供的是人员信息，先用 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 转成 userId 后再写入对应控件。 +- 如果用户提供的是人员信息，先用 `dws aisearch person --query "<姓名>" --dimension name --format json` 转成 userId 后再写入对应控件。 - 单选/多选控件提交的是选项文本（option value），该值从 `form-schema` 返回的选项定义中取得。 - `InnerContactField`、`DepartmentField`、`TableField`、`DDDateRangeField`、`DDAttachment` 等控件的 `value` 结构各不相同，必须按下方格式表单独组装，不要套用文本控件的写法。 - `TextNote`（文字说明）不收集数据，**不要**出现在 `formComponentValues` 中。 @@ -471,7 +471,7 @@ Flags: } ] ``` -- `staffIds`：审批人 userId 列表（必须通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取，严禁填姓名） +- `staffIds`：审批人 userId 列表（必须通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取，严禁填姓名） - `taskActionType`：`NONE`（单人审批）/ `AND`（会签）/ `OR`（或签） **targetSelectActioners（模板有自选审批节点时使用）：** @@ -854,7 +854,7 @@ dws oa approval form-schema --process-code --format json # 18c. 收集表单值（向用户展示控件列表，用户填写后组装 form-values） # 18d. 流程预测（根据表单值预测审批走向，识别自选审批人节点；processCode/deptId/formValues 必填，userId 由登录态自动填充） dws oa approval forecast-process --process-code --dept-id -1 --form-values '{"单行输入框":"测试内容"}' --format json -# 18e. 若 forecast 返回 targetSelect=true 的节点，用 dws aisearch person --keyword "<姓名>" --dimension name --format json 帮用户选人 +# 18e. 若 forecast 返回 targetSelect=true 的节点，用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户选人 # 18f. 发起审批实例（form-values 的 key 须与 Schema 中控件 label 一致） dws oa approval create-instance --process-code --form-values '{"单行输入框":"测试内容"}' --yes --format json # 18g. 发起并指定审批人和抄送人 diff --git a/skills/multi/dingtalk-misc/references/oa/oa-form-components.md b/skills/multi/dingtalk-misc/references/oa/oa-form-components.md index e92d79a5..79e7ae5c 100644 --- a/skills/multi/dingtalk-misc/references/oa/oa-form-components.md +++ b/skills/multi/dingtalk-misc/references/oa/oa-form-components.md @@ -193,7 +193,7 @@ { "name": "项目负责人", "value": "[\"userId1\",\"userId2\"]" } ``` -> **严禁直接写姓名。** 必须先通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 查询获取 userId；多结果时须让用户消歧确认。 +> **严禁直接写姓名。** 必须先通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 查询获取 userId；多结果时须让用户消歧确认。 ### DepartmentField（部门控件） diff --git a/skills/multi/dingtalk-misc/references/oa/oa-process-nodes.md b/skills/multi/dingtalk-misc/references/oa/oa-process-nodes.md index b3a93ce9..c7fe5264 100644 --- a/skills/multi/dingtalk-misc/references/oa/oa-process-nodes.md +++ b/skills/multi/dingtalk-misc/references/oa/oa-process-nodes.md @@ -127,7 +127,7 @@ } ``` -- `workNo` 必须通过 `dws aisearch person --keyword "<工号>" --dimension jobNumber --format json` 获取，**严禁编造** +- `workNo` 必须通过 `dws aisearch person --query "<工号>" --dimension jobNumber --format json` 获取，**严禁编造** - 在 `create-instance` 中对应 `directAppointedApprovers` 的 `staffIds` ### 2. 直属主管（target_formula / reportLineManager） @@ -337,7 +337,7 @@ | 字段 | 说明 | |------|------| -| `staffIds` | 审批人 userId 列表（通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取；多结果须消歧） | +| `staffIds` | 审批人 userId 列表（通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取；多结果须消歧） | | `taskActionType` | `NONE`（单人）/ `AND`（会签）/ `OR`（或签） | | `staffId` | 留空字符串 | @@ -369,6 +369,6 @@ 2. 根据节点中的 `activityType` 和 `targetSelect` 判断是否需要传入 `directAppointedApprovers` 或 `targetSelectActioners` 3. 如果预测返回 `targetSelect: true` 的自选节点，`targetSelectActioners` 必填 4. 如果用户要求覆盖默认流程，使用 `directAppointedApprovers` -5. **所有 userId 必须通过 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 获取，严禁填姓名；多结果须消歧** +5. **所有 userId 必须通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取，严禁填姓名；多结果须消歧** > **交互优化：** 若用户在 `forecast-process` 前已指定审批人/抄送人姓名，`forecast-process` 返回自选节点后应自动映射，仅对未覆盖的自选节点追问，不要重复询问。详见 [oa.md](../oa.md) 交互优化原则。 diff --git a/skills/multi/dingtalk-misc/references/report-lite-recipes.md b/skills/multi/dingtalk-misc/references/report-lite-recipes.md index 0931801a..ff0cb864 100644 --- a/skills/multi/dingtalk-misc/references/report-lite-recipes.md +++ b/skills/multi/dingtalk-misc/references/report-lite-recipes.md @@ -8,7 +8,7 @@ 1. 收到的日志：先把用户时间词转成起止时间，再执行 `report inbox list --start "" --end "" --cursor 0 --size 20 --format json`。用户只说“最近/近期/最近收到”时默认最近 7 天。 2. 我发过/我创建的日志：首条查询必须用 `report outbox list --cursor 0 --size 20 --format json`；如用户指定时间，补 `--start "" --end ""`。 -3. 按发件人过滤收件箱：先 `aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId/staffId`，再加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 +3. 按发件人过滤收件箱：先 `aisearch person --query "<姓名>" --dimension name --format json` 取 `userId/staffId`，再加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 4. 面向用户时必须基于 `result[]` 拼 Markdown 表，表头固定为 `日期 | 标题 | 发送人 | 状态 | 钉钉链接`；每条 `result[]` 都会带这五个中文字段，不要把 `reportId` / `日志ID` 作为主列。 5. 用户要正文、详情、统计、汇总或总结多篇日志时，必须用内部保留的 `reportId` 逐篇执行 `report entry get --report-id --format json` 或 `report entry stats --report-id --format json`；选前 5 篇时调用次数应等于实际选中篇数。 diff --git a/skills/multi/dingtalk-misc/references/report.md b/skills/multi/dingtalk-misc/references/report.md index 8211baed..9ff940e9 100644 --- a/skills/multi/dingtalk-misc/references/report.md +++ b/skills/multi/dingtalk-misc/references/report.md @@ -32,7 +32,7 @@ |----------|----------------|----------| | 查我发过的日志 / 我创建的日志 | `dws report outbox list --cursor 0 --size 20 --format json` | 从返回里取 `reportId`，再执行 `dws report entry get --report-id --format json` | | 查我收到的日志 / 别人发给我的日志 | `dws report inbox list --start "" --end "" --cursor 0 --size 20 --format json` | 必须先按用户时间词补齐完整 ISO 起止时间；用户只说“最近/近期/最近收到”时默认最近 7 天；取 `reportId` 后调用 `entry get` | -| 按发件人查收到的日志 | 先 `dws aisearch person --keyword "<姓名>" --dimension name --format json`，再 `dws report inbox list ... --sender-user-ids --format json` | 只能在收件箱中过滤发件人；没有匹配时说明未找到，不得改选其他发件人 | +| 按发件人查收到的日志 | 先 `dws aisearch person --query "<姓名>" --dimension name --format json`，再 `dws report inbox list ... --sender-user-ids --format json` | 只能在收件箱中过滤发件人；没有匹配时说明未找到，不得改选其他发件人 | | 查看某条日志正文 / 日志详情 | `dws report entry get --report-id --format json` | 如果用户没给 `reportId`，先用 `outbox list` 或 `inbox list` 找候选 | | 总结最近收到的日志 / 汇总多篇日志内容 | 先 `dws report inbox list ... --size 20 --format json`，选前 5 篇或实际返回数量，再对每个 `reportId` 逐条执行 `dws report entry get --report-id --format json` | 不得只调用一次 list 后直接总结；不得把多篇合并成一次 detail 调用 | | 查某条日志统计 / 已读统计 | `dws report entry stats --report-id --format json` | 如果用户没给 `reportId`，先用 `outbox list` 或 `inbox list` 找候选 | @@ -46,7 +46,7 @@ | "有哪些日志模板 / 日报模板 / 模板列表 / 有什么模板可以用" | `dws report template list --format json` | 禁止 ai-seek / enterprise_search 等通用搜索代理绕行 | | "日报模板 / 周报模板"（指定类型） | 先 `dws report template list --format json`，再从返回结果中按名称包含「日报」或「周报」筛选 | 不得虚构模板；不得跳过 `template list` 直接编造模板名 | | "今天收到的日志 / 最近收到的日志 / 别人发我的日志" | `dws report inbox list --start ... --end ... --cursor 0 --size 20 --format json`；“最近/近期/最近收到”默认最近 7 天 | 禁止 grep_search / session_search / ai-seek 替代 | -| "过山发给我的日志 / 按发件人查收件箱" | 先 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 取 ID，再 `dws report inbox list ... --sender-user-ids --format json` | 禁止用 `outbox list --user-id` 查他人已发日志；禁止返回其他发件人的日志 | +| "过山发给我的日志 / 按发件人查收件箱" | 先 `dws aisearch person --query "<姓名>" --dimension name --format json` 取 ID，再 `dws report inbox list ... --sender-user-ids --format json` | 禁止用 `outbox list --user-id` 查他人已发日志；禁止返回其他发件人的日志 | | "总结最近收到的 5 篇日志 / 合并多篇日志内容" | 先 `inbox list` 获取候选，再对选中的每个 `reportId` 逐条 `dws report entry get --report-id --format json` | 禁止停在 skill 激活或反问时间范围；不足 5 篇按实际数量总结并说明 | | "日志模板详情 / 模板具体结构 / 模板有哪些字段" | 两步：① `dws report template list --format json` 获取模板名 → ② `dws report template get --name "<模版名>" --format json` | 禁止跳过第①步直接猜模板名调 `template get` | | "日志ID xxx 详情 / 查一下日志编号 xxx" | 直接 `dws report entry get --report-id --format json` | 禁止反问用户确认 ID 是否正确；返回不存在则如实告知，不得虚构 | @@ -99,7 +99,7 @@ dws report inbox list --start "" --end " --format json # 按发件人过滤收件箱 -dws aisearch person --keyword "<姓名>" --dimension name --format json +dws aisearch person --query "<姓名>" --dimension name --format json dws report inbox list --start "" --end "" --sender-user-ids --cursor 0 --size 20 --format json # 总结最近收到的多篇日志 @@ -471,7 +471,7 @@ dws report outbox list --cursor 0 --size 20 --format json 1. 收到的日志：把用户时间词转换为 Asia/Shanghai 的完整 ISO 起止时间，再执行 `dws report inbox list --start "" --end "" --cursor 0 --size 20 --format json`；用户只说“最近 / 近期 / 最近收到 / 最近一周”时默认最近 7 天。 2. 我发过 / 我创建 / 已发送：第一条查询必须用 `dws report outbox list --cursor 0 --size 20 --format json`；有时间范围时补 `--start` / `--end`。 -3. 按发件人过滤收件箱：先 `dws aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId/staffId`，再给 `inbox list` 加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 +3. 按发件人过滤收件箱：先 `dws aisearch person --query "<姓名>" --dimension name --format json` 取 `userId/staffId`，再给 `inbox list` 加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 4. 用户要正文、详情、汇总或总结多篇日志时，对选中的每篇日志逐条执行 `dws report entry get --report-id --format json`；不足 5 篇按实际数量说明。 ### check-report-read-status diff --git a/skills/multi/dingtalk-misc/references/sheet/sheet-comment.md b/skills/multi/dingtalk-misc/references/sheet/sheet-comment.md index 985e9813..13a614f4 100644 --- a/skills/multi/dingtalk-misc/references/sheet/sheet-comment.md +++ b/skills/multi/dingtalk-misc/references/sheet/sheet-comment.md @@ -111,7 +111,7 @@ Flags: ## 关键说明 -- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --keyword "<姓名>" --dimension name` 拿到 userId。 +- `--mention` 接受 `userId` 列表（逗号分隔），需要先用 `dws aisearch person --query "<姓名>" --dimension name` 拿到 userId。 - `--comment-key` 是 13 位毫秒时间戳 + 32 位 UUID 的拼接字符串，从 `list` / `create` 返回中提取，用于 `reply` / `update` / `delete`。 - `create` / `list`（按单元格过滤）的 `--sheet-id` 是工作表 ID 或名称；未知时先 `dws sheet list` 确认，禁止臆测。 - `reply` 加 `--emoji` 时 `--content` 填表情名称（如 `比心`、`赞`），不是文字内容。 @@ -143,7 +143,7 @@ dws sheet list --node --format json dws sheet comment create --node --sheet-id Sheet1 --range A2 --content "这个数字有问题" --format json # 创建评论 + @人（先 aisearch person 拿 userId） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json dws sheet comment create --node --sheet-id Sheet1 --range A2 --content "请确认" --mention , --format json # 文字回复 diff --git a/skills/multi/dingtalk-shared/references/intent-guide.md b/skills/multi/dingtalk-shared/references/intent-guide.md index b19f854e..a2afb092 100644 --- a/skills/multi/dingtalk-shared/references/intent-guide.md +++ b/skills/multi/dingtalk-shared/references/intent-guide.md @@ -290,12 +290,12 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}` - 已有 userId 时直接使用 `--user`；已有 openDingTalkId 时使用 `--open-dingtalk-id` - `+messages-send --user` 对所有内容类型都会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；无需手动预查，`--dry-run` 也会执行这次只读解析 - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析 -- "发张图片/截图/语音/视频/文件到群里" / "发张图给某某" — **统一一条命令**：`dws chat message send ... --msg-type file --file-path <本地路径>`，CLI 内部自动上传并发送，**任意扩展名（png/jpg/pdf/mp4/zip…）都走这条** +- "发张图片/截图/语音/视频/文件到群里" / "发张图给某某" — **统一一条命令**：`dws chat message send ... --msg-type file --file <本地路径>`，CLI 内部自动上传并发送，**任意扩展名（png/jpg/pdf/mp4/zip…）都走这条** - "发图片+文字说明" — 不要硬塞进一条命令；先发文件消息再补一条 `--text "..."` 即可 ```bash -dws chat message send --group --msg-type file --file-path ./screenshot.png --format json -dws chat message send --open-dingtalk-id --msg-type file --file-path ./report.pdf --format json +dws chat message send --group --msg-type file --file ./screenshot.png --format json +dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json ``` > ❌ 反模式：调 `dt_media_upload` / `extract_media_id.py` / `drive upload` / `drive download` 等前置工具再 `--msg-type image --media-id`。这是**旧链路**，仅当上游已持有 mediaId 才用；新场景一律 `--file-path` 直发，避免长链路与“空白图”现象。 @@ -436,7 +436,7 @@ dws chat message send --group --msg-type location --latitud ```bash # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 用 userId 查详情获取 email dws contact user get --ids --format json @@ -456,7 +456,7 @@ dws mail message send --from my@company.com --to zhangsan@company.com \ ```bash # 手动流程（脚本不可用时）: # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 创建日程 dws calendar event create --title "会议" \ @@ -472,7 +472,7 @@ dws calendar participant add --event --users --format json ```bash # 1. 搜人获取 userId（多人同名须 contact user get 消歧，禁止默认选第一个，详见 08-directory.md「多命中」） -dws aisearch person --keyword "张三" --dimension name --format json +dws aisearch person --query "张三" --dimension name --format json # 2. 创建待办 dws todo task create --title "任务内容" --executors --format json @@ -510,10 +510,10 @@ dws todo task create --title "任务内容" --executors --format json ```bash # 群聊 -dws chat message send --group --msg-type file --file-path <本地路径> --format json +dws chat message send --group --msg-type file --file <本地路径> --format json # 单聊（推荐 --open-dingtalk-id；--user 也支持） -dws chat message send --open-dingtalk-id --msg-type file --file-path <本地路径> --format json +dws chat message send --open-dingtalk-id --msg-type file --file <本地路径> --format json ``` 支持任意扩展名（`.png/.jpg/.gif/.bmp/.webp/.pdf/.doc/.xls/.zip/.mp3/.wav/.mp4/.avi` …），CLI 自动识别并处理。**无需** `dt_media_upload` / `extract_media_id.py` / `drive upload` / `drive download` / `chat conversation-info` / `chat file upload` 等任何前置工具调用。 @@ -523,8 +523,8 @@ dws chat message send --open-dingtalk-id --msg-type file --file 不要把文字塞进 `--msg-type file` 命令（该命令不读 `--text`）。先发文件再补一条文本消息即可： ```bash -dws chat message send --open-dingtalk-id --msg-type file --file-path ./screenshot.png --format json -dws chat message send --open-dingtalk-id --text "这是本周数据汇总" --format json +dws chat message send --open-dingtalk-id --msg-type file --file ./screenshot.png --format json +dws chat message send --open-dingtalk-id --content "这是本周数据汇总" --format json ``` ### 旧链路（mediaId）— 仅兼容场景 diff --git a/skills/multi/dingtalk-shared/references/recipes/lite-catalog.md b/skills/multi/dingtalk-shared/references/recipes/lite-catalog.md index 26c6df75..2e130adf 100644 --- a/skills/multi/dingtalk-shared/references/recipes/lite-catalog.md +++ b/skills/multi/dingtalk-shared/references/recipes/lite-catalog.md @@ -11,7 +11,7 @@ ### create-todo -1. 确定执行者：指定姓名 → `aisearch person --keyword "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 +1. 确定执行者：指定姓名 → `aisearch person --query "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 2. 创建：`todo task create --title "<标题>" --executors [,...] --priority <优先级>`（可选 `--due "<截止ISO>"`）→ `todoTaskId` ### todo-query-ops @@ -32,7 +32,7 @@ 查询多人在某时段内的闲忙（**busy**，不是用 `event list` 扫日程）： -1. 解析用户：对每个姓名执行 `aisearch person --keyword "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 `dingtalk-calendar` `busy search` 要求）。 +1. 解析用户：对每个姓名执行 `aisearch person --query "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 `dingtalk-calendar` `busy search` 要求）。 2. 确认时段：用户须给出或可收敛为明确的 `--start` / `--end`（ISO-8601）；若未给出，**先追问**起止时间，禁止用任意默认全天窗口代替用户意图。 3. 执行：`dws calendar busy search --users --start "" --end "" --format json` @@ -56,7 +56,7 @@ 1. 收到的日志：先把用户时间词转成起止时间，再执行 `report inbox list --start "" --end "" --cursor 0 --size 20 --format json`。用户只说“最近/近期/最近收到”时默认最近 7 天。 2. 我发过/我创建的日志：首条查询必须用 `report outbox list --cursor 0 --size 20 --format json`；如用户指定时间，补 `--start "" --end ""`。 -3. 按发件人过滤收件箱：先 `aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId/staffId`，再加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 +3. 按发件人过滤收件箱：先 `aisearch person --query "<姓名>" --dimension name --format json` 取 `userId/staffId`，再加 `--sender-user-ids `；空结果必须说明未找到该发件人的日志，不得改选其他人。 4. 面向用户时必须基于 `result[]` 拼 Markdown 表，表头固定为 `日期 | 标题 | 发送人 | 状态 | 钉钉链接`；每条 `result[]` 都会带这五个中文字段，不要把 `reportId` / `日志ID` 作为主列。 5. 用户要正文、详情、统计、汇总或总结多篇日志时，必须用内部保留的 `reportId` 逐篇执行 `report entry get --report-id --format json` 或 `report entry stats --report-id --format json`；选前 5 篇时调用次数应等于实际选中篇数。 @@ -137,7 +137,7 @@ dws minutes list shared --query "ROI" --format json - 执行前检查特殊字符（引号/书名号/括号等），若包含先提示用户确认去除 - 替换成功后追问是否加热词：`minutes hot-word add --words "新文字"` - **替换发言人**：先统一搜人取得 dingUid → `minutes speaker replace --id --from "发言人X" --to "姓名" --target-uid ` - - 查询 dingUid：`aisearch person --keyword "姓名" --dimension name --format json` → 取 `userId` + - 查询 dingUid：`aisearch person --query "姓名" --dimension name --format json` → 取 `userId` - 多个匹配 → 列出候选让用户选；无匹配 → 不带 `--target-uid` 执行 - **修改标题**：`minutes update title --id --title "新标题"` - **修改摘要**：`minutes update summary --id --content "新内容"` @@ -158,7 +158,7 @@ dws minutes list shared --query "ROI" --format json ### minutes-permission（权限管理） - 添加成员：`minutes permission add --ids --member-uids --policy 4` - - 需先通过 `aisearch person --keyword "<姓名>" --dimension name` 获取目标 userId + - 需先通过 `aisearch person --query "<姓名>" --dimension name` 获取目标 userId - policy：0=不可见 / 1=仅查看 / 2=查看+下载 / 3=查看+下载+编辑 / 4=全部权限 - 移除成员：`minutes permission remove --ids --member-uids ` @@ -216,7 +216,7 @@ query 未提"听记"但任务产出依赖会议讨论内容时（报告/总结/ **搜人首选入口**。凡是“找人/搜人/找同事/谁负责/上级/下级/负责人/团队成员”均优先用 `aisearch person`： 1. 从用户问题中提取 keyword（人名/业务关键词）和 dimension（维度），规则见 `dingtalk-aisearch`。 -2. `aisearch person --keyword "<关键词>" --dimension <维度>` +2. `aisearch person --query "<关键词>" --dimension <维度>` 3. 结果中提取 `userId` 和 `title`（姓名）展示给用户。 4. 若需要 userId 做后续操作（发消息/建待办），可直接使用结果中的 `userId`。 5. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 `dingtalk-contact/references/08-directory.md`「多命中」。 @@ -228,7 +228,7 @@ query 未提"听记"但任务产出依赖会议讨论内容时（报告/总结/ - 需要获取 userId 给其他产品使用（发消息/建待办/约日程） - 已有 userId 需查完整详情（`contact user get --ids`） -1. `aisearch person --keyword "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 +1. `aisearch person --query "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。 2. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 `dingtalk-contact/references/08-directory.md`「多命中」。 3. 需详情时：`contact user get --ids `（多人可 `--ids id1,id2,...`） diff --git a/skills/multi/dingtalk-todo/SKILL.md b/skills/multi/dingtalk-todo/SKILL.md index ab19e5b5..d925ac11 100644 --- a/skills/multi/dingtalk-todo/SKILL.md +++ b/skills/multi/dingtalk-todo/SKILL.md @@ -67,7 +67,7 @@ metadata: **触发**：建待办/任务提醒/指派任务/TODO。 -1. **解析执行者（必须）**：指定姓名 → `dws aisearch person --keyword "<姓名>" --dimension name --format json` 取 `userId`；未指定 → `dws contact user get-self --format json` 取当前用户 `userId`；多人逐个搜索后英文逗号拼接。 +1. **解析执行者（必须）**：指定姓名 → `dws aisearch person --query "<姓名>" --dimension name --format json` 取 `userId`；未指定 → `dws contact user get-self --format json` 取当前用户 `userId`；多人逐个搜索后英文逗号拼接。 2. **执行（必须）**：`dws todo task create --title "<标题>" --executors [,...] --priority <10/20/30/40> --format json`；有截止时间加 `--due ""`；循环待办加 `--due "<首次截止ISO>" --recurrence "DTSTART:\nRRULE:FREQ=DAILY;INTERVAL=1"`。 3. **验证（必须）**：从返回取 `taskId`/`todoTaskId`，立即 `dws todo task get --task-id --format json` 回读。 diff --git a/skills/multi/dingtalk-todo/references/02-task.md b/skills/multi/dingtalk-todo/references/02-task.md index 594fc609..6ce36df4 100644 --- a/skills/multi/dingtalk-todo/references/02-task.md +++ b/skills/multi/dingtalk-todo/references/02-task.md @@ -15,5 +15,5 @@ | Recipe | 行动指南（固定路线） | |--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | generate-progress-report | 1. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行
2. 交叉比对各源数据
3. `doc create --name "<报告名>" --content "<报告内容>"` | -| batch-create-todo | 1. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --keyword "<姓名>" --dimension name` → 取真实 `userId`；同名时先消歧
3. 逐条执行 `todo task create --title "<标题>" --executors --priority <10/20/30/40>`，从每次响应收集真实 `todoTaskId`；单批超 30 条须用户确认
4. 对全部 `todoTaskId` 并行执行 `todo task get --task-id `，逐项核对标题、执行者、优先级和截止时间；不能只以退出码或创建响应作为成功证据 | -| assign-and-notify | 1. `aisearch person --keyword "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors --priority <10/20/30/40>` → 取 `todoTaskId`
3. `todo task get --task-id ` 回读任务，确认无误后再通知
4. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --text "<通知内容>"` | +| batch-create-todo | 1. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --query "<姓名>" --dimension name` → 取真实 `userId`；同名时先消歧
3. 逐条执行 `todo task create --title "<标题>" --executors --priority <10/20/30/40>`，从每次响应收集真实 `todoTaskId`；单批超 30 条须用户确认
4. 对全部 `todoTaskId` 并行执行 `todo task get --task-id `，逐项核对标题、执行者、优先级和截止时间；不能只以退出码或创建响应作为成功证据 | +| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors --priority <10/20/30/40>` → 取 `todoTaskId`
3. `todo task get --task-id ` 回读任务，确认无误后再通知
4. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<通知内容>"` | diff --git a/skills/multi/dingtalk-todo/references/lite-recipes.md b/skills/multi/dingtalk-todo/references/lite-recipes.md index 40a7959e..5cf26452 100644 --- a/skills/multi/dingtalk-todo/references/lite-recipes.md +++ b/skills/multi/dingtalk-todo/references/lite-recipes.md @@ -6,7 +6,7 @@ ### create-todo -1. 确定执行者：指定姓名 → `aisearch person --keyword "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 +1. 确定执行者：指定姓名 → `aisearch person --query "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。 2. 创建：`todo task create --title "<标题>" --executors [,...] --priority <优先级>`（可选 `--due "<截止ISO>"`）→ `todoTaskId` ### todo-query-ops @@ -82,7 +82,7 @@ dws minutes list shared --query "ROI" --format json - 执行前检查特殊字符（引号/书名号/括号等），若包含先提示用户确认去除 - 替换成功后追问是否加热词：`minutes hot-word add --words "新文字"` - **替换发言人**：先统一搜人取得 dingUid → `minutes speaker replace --id --from "发言人X" --to "姓名" --target-uid ` - - 查询 dingUid：`aisearch person --keyword "姓名" --dimension name --format json` → 取 `userId` + - 查询 dingUid：`aisearch person --query "姓名" --dimension name --format json` → 取 `userId` - 多个匹配 → 列出候选让用户选；无匹配 → 不带 `--target-uid` 执行 - **修改标题**：`minutes update title --id --title "新标题"` - **修改摘要**：`minutes update summary --id --content "新内容"` @@ -103,7 +103,7 @@ dws minutes list shared --query "ROI" --format json ### minutes-permission（权限管理） - 添加成员：`minutes permission add --ids --member-uids --policy 4` - - 需先通过 `aisearch person --keyword "<姓名>" --dimension name` 获取目标 userId + - 需先通过 `aisearch person --query "<姓名>" --dimension name` 获取目标 userId - policy：0=不可见 / 1=仅查看 / 2=查看+下载 / 3=查看+下载+编辑 / 4=全部权限 - 移除成员：`minutes permission remove --ids --member-uids ` diff --git a/skills/multi/dingtalk-todo/references/todo.md b/skills/multi/dingtalk-todo/references/todo.md index 57adbfed..7cd81ab4 100644 --- a/skills/multi/dingtalk-todo/references/todo.md +++ b/skills/multi/dingtalk-todo/references/todo.md @@ -212,9 +212,9 @@ Flags: Usage: dws todo task add-attachment [flags] Example: - dws todo task add-attachment --task-id --file-path /path/to/file.pdf + dws todo task add-attachment --task-id --file /path/to/file.pdf Flags: - --file-path string 本地文件路径 (必填) + --file string 本地文件路径 (必填) --task-id string 待办任务 ID (必填) ``` @@ -442,7 +442,7 @@ dws todo task reset-reminder --task-id --reminder-rules ' --format json # 19. 上传待办附件 -dws todo task add-attachment --task-id --file-path /path/to/file.pdf --format json +dws todo task add-attachment --task-id --file /path/to/file.pdf --format json # 20. 查询待办附件列表 dws todo task list-attachment --task-id --format json # 21. 删除待办附件 @@ -494,7 +494,7 @@ dws todo tag delete --tag-codes code1,code2 --yes --format json - `task add-reminder` 用于为待办添加提醒，`--base-time` 支持 `dueTime`（基于截止时间偏移，待办必须有截止时间）和 `customTime`（自定义时间戳）两种模式 - `task reset-reminder` 用于重置待办提醒规则，不传 `--reminder-rules` 则清除所有提醒 - `task list-sub` 用于查询指定待办的子待办列表，需通过 `task list` 或 `task create` 获取父待办 ID -- `task add-attachment` 用于上传本地文件作为待办附件，`--file-path` 为本地文件绝对路径；该操作不可逆，调用前必须确认待办存在 +- `task add-attachment` 用于上传本地文件作为待办附件，`--file` 为本地文件绝对路径；该操作不可逆，调用前必须确认待办存在 - `task list-attachment` 用于查询指定待办的附件列表 - `task remove-attachment` 用于删除待办附件，为不可逆操作，执行前需用户确认；`--attachment-id` 可通过 `task list-attachment` 获取 - `tag list` 用于查询当前用户已有的标签列表，返回的 `tagCode` 可用于 `tag add` / `tag update` / `tag delete` diff --git a/test/skill_tests.md b/test/skill_tests.md index e9f4607b..1cc8db02 100644 --- a/test/skill_tests.md +++ b/test/skill_tests.md @@ -701,34 +701,34 @@ Agent 安装 dws skill 后，仅依据 skill 提供的参考文档，将自然 **chat_chat_message_send_by_bot_001** - Prompt: 机器人发送群聊消息，text 为 ## 今日完成..., title 为 日报 - Expected: `dws chat message send-by-bot --group --robot-code --text "## 今日完成..." --title 日报 --format json` -- Flags: `--group` = ``, `--robot-code` = ``, `--text` = `## 今日完成...`, `--title` = `日报` +- Flags: `--text` = `## 今日完成...`, `--group` = ``, `--robot-code` = ``, `--title` = `日报` **chat_chat_message_send_by_bot_002** - Prompt: 用机器人myBot给userId1和userId2发私聊消息，标题是通知，内容是请查收周报 - Expected: `dws chat message send-by-bot --robot-code myBot --users userId1,userId2 --title "通知" --text "请查收周报" --format json` -- Flags: `--robot-code` = `myBot`, `--text` = `请查收周报`, `--title` = `通知`, `--users` = `userId1,userId2` +- Flags: `--text` = `请查收周报`, `--robot-code` = `myBot`, `--title` = `通知`, `--users` = `userId1,userId2` #### `dws chat message send-by-webhook` **chat_chat_message_send_by_webhook_001** - Prompt: 通过 Webhook token1 发一条告警消息：CPU 超 90% -- Expected: `dws chat message send-by-webhook --text "CPU 超 90%" --title 告警 --token token1 --format json` -- Flags: `--text` = `CPU 超 90%`, `--title` = `告警`, `--token` = `token1` +- Expected: `dws chat message send-by-webhook --content "CPU 超 90%" --title 告警 --token token1 --format json` +- Flags: `--content` = `CPU 超 90%`, `--title` = `告警`, `--token` = `token1` **chat_chat_message_send_by_webhook_002** - Prompt: 通过webhook发群消息，token是tokenABC，标题告警，内容CPU使用率超过90%，@所有人 -- Expected: `dws chat message send-by-webhook --token tokenABC --title "告警" --text "CPU使用率超过90%" --at-all --format json` -- Flags: `--at-all`, `--text` = `CPU使用率超过90%`, `--title` = `告警`, `--token` = `tokenABC` +- Expected: `dws chat message send-by-webhook --token tokenABC --title "告警" --content "CPU使用率超过90%" --at-all --format json` +- Flags: `--at-all`, `--content` = `CPU使用率超过90%`, `--title` = `告警`, `--token` = `tokenABC` **chat_chat_message_send_by_webhook_003** - Prompt: 用 Webhook tokenXYZ 发消息，标题是「审批提醒」，内容是「请及时审批」，并@用户 user001 和 user002 -- Expected: `dws chat message send-by-webhook --token tokenXYZ --title "审批提醒" --text "@user001 @user002 请及时审批" --at-users user001,user002 --format json` -- Flags: `--at-users` = `user001,user002`, `--text` = `@user001 @user002 请及时审批`, `--title` = `审批提醒`, `--token` = `tokenXYZ` +- Expected: `dws chat message send-by-webhook --token tokenXYZ --title "审批提醒" --content "@user001 @user002 请及时审批" --at-users user001,user002 --format json` +- Flags: `--at-users` = `user001,user002`, `--content` = `@user001 @user002 请及时审批`, `--title` = `审批提醒`, `--token` = `tokenXYZ` **chat_chat_message_send_by_webhook_004** - Prompt: 用 Webhook tokenDEF 发通知，标题是「会议通知」，内容是「请参加今日下午的会议」，并@手机号 13800138000 和 13900139000 -- Expected: `dws chat message send-by-webhook --token tokenDEF --title "会议通知" --text "@13800138000 @13900139000 请参加今日下午的会议" --at-mobiles 13800138000,13900139000 --format json` -- Flags: `--at-mobiles` = `13800138000,13900139000`, `--text` = `@13800138000 @13900139000 请参加今日下午的会议`, `--title` = `会议通知`, `--token` = `tokenDEF` +- Expected: `dws chat message send-by-webhook --token tokenDEF --title "会议通知" --content "@13800138000 @13900139000 请参加今日下午的会议" --at-mobiles 13800138000,13900139000 --format json` +- Flags: `--at-mobiles` = `13800138000,13900139000`, `--content` = `@13800138000 @13900139000 请参加今日下午的会议`, `--title` = `会议通知`, `--token` = `tokenDEF` #### `dws chat search` diff --git a/test/skill_tests_results.md b/test/skill_tests_results.md index eb561066..9d60bb28 100644 --- a/test/skill_tests_results.md +++ b/test/skill_tests_results.md @@ -927,7 +927,7 @@ **chat_chat_message_send_by_webhook_001** ✅ PASS - Prompt: 通过 Webhook token1 发一条告警消息：CPU 超 90% -- Expected: `dws chat message send-by-webhook --text "CPU 超 90%" --title 告警 --token token1 --format json` +- Expected: `dws chat message send-by-webhook --content "CPU 超 90%" --title 告警 --token token1 --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send-by-webhook) - Flags: PASS (3 flags validated) @@ -935,7 +935,7 @@ **chat_chat_message_send_by_webhook_002** ✅ PASS - Prompt: 通过webhook发群消息，token是tokenABC，标题告警，内容CPU使用率超过90%，@所有人 -- Expected: `dws chat message send-by-webhook --token tokenABC --title "告警" --text "CPU使用率超过90%" --at-all --format json` +- Expected: `dws chat message send-by-webhook --token tokenABC --title "告警" --content "CPU使用率超过90%" --at-all --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send-by-webhook) - Flags: PASS (4 flags validated) @@ -943,7 +943,7 @@ **chat_chat_message_send_by_webhook_003** ✅ PASS - Prompt: 用 Webhook tokenXYZ 发消息，标题是「审批提醒」，内容是「请及时审批」，并@用户 user001 和 user002 -- Expected: `dws chat message send-by-webhook --token tokenXYZ --title "审批提醒" --text "@user001 @user002 请及时审批" --at-users user001,user002 --format json` +- Expected: `dws chat message send-by-webhook --token tokenXYZ --title "审批提醒" --content "@user001 @user002 请及时审批" --at-users user001,user002 --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send-by-webhook) - Flags: PASS (4 flags validated) @@ -951,7 +951,7 @@ **chat_chat_message_send_by_webhook_004** ✅ PASS - Prompt: 用 Webhook tokenDEF 发通知，标题是「会议通知」，内容是「请参加今日下午的会议」，并@手机号 13800138000 和 13900139000 -- Expected: `dws chat message send-by-webhook --token tokenDEF --title "会议通知" --text "@13800138000 @13900139000 请参加今日下午的会议" --at-mobiles 13800138000,13900139000 --format json` +- Expected: `dws chat message send-by-webhook --token tokenDEF --title "会议通知" --content "@13800138000 @13900139000 请参加今日下午的会议" --at-mobiles 13800138000,13900139000 --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send-by-webhook) - Flags: PASS (4 flags validated) From 4f4ea43549c349158f102d7a821ad6a62df9a8f9 Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 18 Aug 2026 15:39:21 +0800 Subject: [PATCH 228/250] fix: reconcile primary migration with current main #85349380 --- internal/helpers/chat_media_upload.go | 2 +- internal/helpers/connect_media_test.go | 2 +- internal/helpers/connect_stream.go | 2 +- .../primary_param_native_compat_test.go | 20 ++++-- .../chat/primary_param_migration_test.go | 4 +- internal/shortcut/todo/lifecycle.go | 2 +- .../mono/references/best_practices/02-task.md | 2 +- .../references/best_practices/03-meeting.md | 2 +- .../references/best_practices/04-document.md | 2 +- .../references/best_practices/07-minutes.md | 5 +- skills/mono/references/intent-guide.md | 8 +-- skills/mono/references/products/chat.md | 69 ++++++++++--------- .../references/03-meeting.md | 2 +- .../dingtalk-minutes/references/07-minutes.md | 4 +- .../references/intent-guide.md | 14 ++-- .../multi/dingtalk-todo/references/02-task.md | 2 +- test/skill_tests.md | 8 +-- test/skill_tests_results.md | 4 +- 18 files changed, 83 insertions(+), 71 deletions(-) diff --git a/internal/helpers/chat_media_upload.go b/internal/helpers/chat_media_upload.go index 5bd34c26..0c0f5c03 100644 --- a/internal/helpers/chat_media_upload.go +++ b/internal/helpers/chat_media_upload.go @@ -46,7 +46,7 @@ func newChatMediaUploadCommand() *cobra.Command { 发送本地图片或文件时，请使用 chat message send --msg-type file --file。 该路径会把图片作为可下载的 file 消息发送，不会生成 mediaId，也不会渲染成内联 image 消息。 如果上游已经提供 mediaId，仍可使用 chat message send --msg-type image --media-id。`, - Example: " dws chat message send --group --msg-type file --file ./screenshot.png\n" + + Example: " dws chat message send --conversation-id --msg-type file --file ./screenshot.png\n" + " dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf", Args: cobra.NoArgs, DisableAutoGenTag: true, diff --git a/internal/helpers/connect_media_test.go b/internal/helpers/connect_media_test.go index d8238ca8..a42054fd 100644 --- a/internal/helpers/connect_media_test.go +++ b/internal/helpers/connect_media_test.go @@ -96,7 +96,7 @@ func TestCallbackInboundMediaPreservesFutureRichTextAttachment(t *testing.T) { // TestExtractCallbackText covers the markdown / richText fallback path used // when SDK data.Text.Content is empty. This is the recovery path for -// `dws chat message send --group ... --text ...` (defaults to msgType=markdown) +// `dws chat message send --conversation-id ... --content ...` (defaults to msgType=markdown) // which otherwise gets silently dropped by the connector. func TestExtractCallbackText(t *testing.T) { cases := []struct { diff --git a/internal/helpers/connect_stream.go b/internal/helpers/connect_stream.go index 2b3a61ae..4357069b 100644 --- a/internal/helpers/connect_stream.go +++ b/internal/helpers/connect_stream.go @@ -1259,7 +1259,7 @@ func runStreamConnector(ctx context.Context, channel, clientID, clientSecret str } // Structured-text fallback: DingTalk leaves data.Text.Content blank on // markdown / richText callbacks (the body ships in data.Content). Without - // this, `dws chat message send --group ... --content ...` — which defaults + // this, `dws chat message send --conversation-id ... --content ...` — which defaults // to msgType=markdown — hits the drop branch below and the bot looks // dead to the sender. if text == "" { diff --git a/internal/helpers/primary_param_native_compat_test.go b/internal/helpers/primary_param_native_compat_test.go index 8ea171a3..4163760b 100644 --- a/internal/helpers/primary_param_native_compat_test.go +++ b/internal/helpers/primary_param_native_compat_test.go @@ -147,6 +147,18 @@ func TestNativePrimaryParamFlagSurfaces(t *testing.T) { assertNativePrimaryFlagPair(t, send, "file", "file-path") sendByWebhook := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook") assertNativePrimaryFlagPair(t, sendByWebhook, "content", "text") + sendByBot := findNativePrimaryLeaf(t, chat, "message", "send-by-bot") + for _, name := range []string{"text", "file-path"} { + flag := sendByBot.Flags().Lookup(name) + if flag == nil || flag.Hidden { + t.Fatalf("%s --%s = %#v, want unchanged visible Primary", sendByBot.CommandPath(), name, flag) + } + } + for _, name := range []string{"content", "file"} { + if flag := sendByBot.Flags().Lookup(name); flag != nil && !flag.Hidden { + t.Fatalf("%s --%s = %#v, pending migration must not become visible", sendByBot.CommandPath(), name, flag) + } + } reply := findNativePrimaryLeaf(t, chat, "message", "reply") assertNativePrimaryFlagPair(t, reply, "group", "conversation-id") assertNativePrimaryFlagPair(t, reply, "content", "text") @@ -247,7 +259,7 @@ func TestNativePrimaryParamTextPayloadCompatibility(t *testing.T) { for _, spelling := range nativePrimaryParamSpellings("group", "conversation-id") { t.Run(spelling.name, func(t *testing.T) { caller := &nativePrimaryParamCaller{} - args := []string{"message", "reply", "--ref-msg-id", "mid", "--ref-sender", "D-sender", "--content", "fixed-content"} + args := []string{"message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "fixed-content"} args = append(args, spelling.args...) if err := runChatCoverageCommand(t, caller, args...); err != nil { t.Fatal(err) @@ -264,7 +276,7 @@ func TestNativePrimaryParamTextPayloadCompatibility(t *testing.T) { for _, spelling := range nativePrimaryParamSpellings("content", "text") { t.Run(spelling.name, func(t *testing.T) { caller := &nativePrimaryParamCaller{} - args := []string{"message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", "D-sender"} + args := []string{"message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID} args = append(args, spelling.args...) if err := runChatCoverageCommand(t, caller, args...); err != nil { t.Fatal(err) @@ -413,10 +425,10 @@ func TestNativePrimaryParamMissingErrorsRecommendPrimaryOnly(t *testing.T) { runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send-by-webhook", "--token", "token", "--title", "title"), "content", "text") assertNativePrimaryErrorHint(t, - runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--ref-msg-id", "mid", "--ref-sender", "D-sender", "--content", "body"), + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "body"), "group", "conversation-id") assertNativePrimaryErrorHint(t, - runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", "D-sender"), + runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID), "content", "text") os.Args = []string{"dws", "doc"} diff --git a/internal/shortcut/chat/primary_param_migration_test.go b/internal/shortcut/chat/primary_param_migration_test.go index 822d833e..27acdc14 100644 --- a/internal/shortcut/chat/primary_param_migration_test.go +++ b/internal/shortcut/chat/primary_param_migration_test.go @@ -147,7 +147,7 @@ func TestPrimaryParamMigrationMessagesReplyPayloadCompatibility(t *testing.T) { root.SetOut(&output) args := []string{ "chat", "+messages-reply", "--message-id", "msg", - "--ref-sender", "D-sender", + "--ref-sender", fixtureCurrentDOpenID, } args = append(args, spelling.args...) args = append(args, "--yes") @@ -188,7 +188,7 @@ func TestPrimaryParamMigrationMessagesReplyPayloadCompatibility(t *testing.T) { var output bytes.Buffer root.SetOut(&output) root.SetArgs([]string{ - "chat", "+messages-reply", "--message-id", "msg", "--ref-sender", "D-sender", + "chat", "+messages-reply", "--message-id", "msg", "--ref-sender", fixtureCurrentDOpenID, "--conversation-id", "legacy-cid", "--group", "canonical-cid", "--text", "legacy-body", "--content", "canonical-body", "--dry-run", "--yes", diff --git a/internal/shortcut/todo/lifecycle.go b/internal/shortcut/todo/lifecycle.go index 8d7529bf..e517fd05 100644 --- a/internal/shortcut/todo/lifecycle.go +++ b/internal/shortcut/todo/lifecycle.go @@ -435,7 +435,7 @@ var UploadAttachment = shortcut.Shortcut{ {Name: "file-path", Type: shortcut.FlagString, Desc: "本地文件路径", Required: true}, }, Execute: func(*shortcut.RuntimeContext) error { - return apperrors.NewValidation("+upload-attachment 暂不复制原子上传事务；请使用 dws todo task add-attachment --task-id --file-path ") + return apperrors.NewValidation("+upload-attachment 暂不复制原子上传事务；请使用 dws todo task add-attachment --task-id --file ") }, } diff --git a/skills/mono/references/best_practices/02-task.md b/skills/mono/references/best_practices/02-task.md index d4696485..ef6ae12c 100644 --- a/skills/mono/references/best_practices/02-task.md +++ b/skills/mono/references/best_practices/02-task.md @@ -16,4 +16,4 @@ |--------|---------------------| | generate-progress-report | 1. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行
2. 交叉比对各源数据
3. `doc create --name "<报告名>" --content "<报告内容>"` | | batch-create-todo | 1. 按[「多源并行采集」](_common/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --query "<姓名>" --dimension name` → 取 `userId`
3. **优先**：将待办写入 `todos.json`（格式见 [todo_batch_create.py](../../scripts/todo_batch_create.py)），执行 `python scripts/todo_batch_create.py todos.json`
备选：逐条 `todo task create --title "<标题>" --executors ` → 汇总回显
**单批超 30 条须用户确认** | -| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors ` → 取 `taskId`
3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<通知内容>"` 通知 | +| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors ` → 取 `taskId`
3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --conversation-id --content "<通知内容>"` 通知 | diff --git a/skills/mono/references/best_practices/03-meeting.md b/skills/mono/references/best_practices/03-meeting.md index 2508f61a..39ac43a2 100644 --- a/skills/mono/references/best_practices/03-meeting.md +++ b/skills/mono/references/best_practices/03-meeting.md @@ -53,4 +53,4 @@ | Recipe | 行动指南（固定路线） | | ------------------ | ------------------- | | schedule-meeting | **见上文「两准则」**、**「搜房失败硬门禁」**。**未给时段且仅说「发起/开个会」**→ 不走本 recipe；当前 CLI 不支持实时视频会议，告知用户请在钉钉客户端操作。**未给时段但有预约意图**（"安排""约""定"等词）：追问具体开始/结束时间。**已有时段后**，按固定顺序执行：1. `dws calendar event create` 建日程；2. 有参会人则 `dws calendar participant add`；3. 再处理会议室。**无明确会议室范围**：可直接 `python scripts/calendar_schedule_meeting.py --title "<主题>" --start "<起始>" --end "<结束>" [--users ] [--book-room] [--dry-run]`。**有明确范围（某楼/层）**：先 `dws calendar room list-groups`，锁定该地点**最相关的承载 group**；若只有一个地点，`--room-group-id` 应只传这个最相关 group，**不要**把同楼内多个楼层 group 打包传入碰运气。只有用户明确给出多个允许地点时，才把这些 `group-id` 一并传给 `python scripts/calendar_schedule_meeting.py ... --book-room --room-group-id ""`。**用户点名具体会议室**：须手工 `dws calendar room search --start "" --end "" --group-id [--available] --format json`（**无** `--query`），在 JSON 中匹配名称取 **`rooms[].roomId` 唯一真值** → `dws calendar room add --event --rooms `；**不得**把用户输入的会议室名当 `roomId`。**一旦连续 2 次空结果 / 任意一次 `roomId invalid`**：**必须回读本节并立即收束判断**；若整园/限定范围内搜尽仍无 roomId 或无空房 → **下一条消息必须直接向用户汇报失败结论**；否则只能向用户确认是否放宽范围/改时间。**禁止**假设 roomId、禁止无 ID 调用 `room add`、禁止用日程详情绕路、禁止继续猜测 Mock/测试环境。细则见「会议室搜索早停」。 | -| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<变更通知>"` 通知变更 | +| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --conversation-id --content "<变更通知>"` 通知变更 | diff --git a/skills/mono/references/best_practices/04-document.md b/skills/mono/references/best_practices/04-document.md index 51af2a2e..b72255dd 100644 --- a/skills/mono/references/best_practices/04-document.md +++ b/skills/mono/references/best_practices/04-document.md @@ -10,7 +10,7 @@ | migrate-doc | 1. `doc read --node <源nodeId>` → 取正文并写入临时文件 `.md`
2. `doc create --name "<文档名>" --folder --content-file .md` → 取新 `nodeId`（`--folder` 只传文档文件夹 nodeId / alidocs 文件夹 URL，不传数字 dentryId；正文 <200KB 单步到位）
2a. 若正文 >200KB：**必须先向用户提示截断风险**（详见下方「分块 append 截断风险提示」），用户确认后再执行：`doc create --name "<文档名>" --folder ` → `nodeId` → 按段落切片 → 每片 `doc update --node --content-file --mode append`
3. **回读校验**：`doc read --node ` 校验内容完整性 | | update-doc-section | **优先块级精修（保形）**：1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc block list --node --format json` 定位目标块取 `blockId`
3. `doc block update --node --block-id --content "<替换内容>" --format json` 局部修改（不破坏富格式）
4. **回读校验**：`doc read --node ` 确认目标章节已更新
**兜底**：仅当无法定位块且用户确认整篇替换时，先 `doc update --node --content-file .md --mode overwrite --dry-run` 预览，再加 `--yes` 执行；overwrite 会丢富格式（颜色/字号/合并单元格等），详见下方 template-based-generation §"为什么避免 overwrite" | | template-based-generation | **触发**：用户给已有 alidocs URL + "参照/按模板/复刻/同样模板生成 X 月份的" → **保形复制，禁止重写**。固定走下方 [template-based-generation](#template-based-generation) 章节：`doc copy` 保形复制 → `doc rename` → `doc block list/update` 局部改副本。禁止 `doc read + doc create` 重写链。 | -| doc-to-message | 1. `doc read --node ` → 取正文（大文档只摘要+链接）
2. `contact user search --query "<姓名>"` → 取 `openDingTalkId`（推荐）；或 `chat search --query "<群名>"` → 取 `openConversationId`
3. `chat message send --open-dingtalk-id --content "<内容>"`（推荐）或 `--group --content "<内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| doc-to-message | 1. `doc read --node ` → 取正文（大文档只摘要+链接）
2. `contact user search --query "<姓名>"` → 取 `openDingTalkId`（推荐）；或 `chat search --query "<群名>"` → 取 `openConversationId`
3. `chat message send --open-dingtalk-id --content "<内容>"`（推荐）或 `--conversation-id --content "<内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | delete-old-doc | 1. `doc search --query "<关键词>"` 或 `doc list --folder ` 取 `nodeId`
2. **必须先向用户展示要删除的文档标题/路径**，等用户确认
3. `doc delete --node --yes`（注意：是 `doc delete`，不是 `doc block delete`；前者删整篇，后者删块）
4. 验证：`doc info --node ` 应返回 not-found | | export-doc-as-docx | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `doc export --node --output /tmp/.docx --timeout-sec 600`（CLI 内置渐进式退避轮询，**不要自己拼 GET downloadUrl**）
3. 落盘失败兜底：`doc export get --job-id --output /tmp/.docx` 续等
4. （可选）`doc-to-message` 把 docx 路径作为附件发给用户 | | grant-doc-access | 1. `doc search --query "<关键词>"` → 取 `nodeId`
2. `contact user search --query "<姓名>"` → 取 `userId`（**注意**: doc permission 用 `userId`，不是 `openDingTalkId`）
3. **节点级**授权：`doc permission add --node --user --role EDITOR`
　　role 取值: MANAGER / EDITOR / DOWNLOADER / READER（**不要传 OWNER**）
　　单次最多 30 个 userId
4. 查权限：`doc permission list --node ` 确认
5. **不要混淆**: 给"知识库"加成员用 `wiki member add --workspace`（容器级）；给"单个文档"加权限用 `doc permission add --node`（节点级）| diff --git a/skills/mono/references/best_practices/07-minutes.md b/skills/mono/references/best_practices/07-minutes.md index 816ef2d1..ae779012 100644 --- a/skills/mono/references/best_practices/07-minutes.md +++ b/skills/mono/references/best_practices/07-minutes.md @@ -27,10 +27,9 @@ dws minutes list mine --limit 5 --format json | Recipe | 行动指南（固定路线） | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| meeting-followup | 1. **提取待办优先**：`minutes_extract_todos.py`（开源版未引入；可手动用 `dws minutes get todos --id ` 拼装） → 获取行动项列表 无脚本时按[「多源并行采集」](./_common/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors `（每条行动项；批量时可写 JSON 调 `python scripts/todo_batch_create.py todos.json`） 4. `chat message send --group --content "<通知内容>"` 通知已创建 | -| share-minutes | **拉摘要优先**：`minutes_recent_summary.py`（开源版未引入；可手动用 `dws minutes list` + `dws minutes get summary --id ` 组合） → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`contact user search --query "<姓名>"` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--group --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| meeting-followup | 1. **提取待办优先**：`minutes_extract_todos.py`（开源版未引入；可手动用 `dws minutes get todos --id ` 拼装） → 获取行动项列表 无脚本时按[「多源并行采集」](./_common/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors `（每条行动项；批量时可写 JSON 调 `python scripts/todo_batch_create.py todos.json`） 4. `chat message send --conversation-id --content "<通知内容>"` 通知已创建 | +| share-minutes | **拉摘要优先**：`minutes_recent_summary.py`（开源版未引入；可手动用 `dws minutes list` + `dws minutes get summary --id ` 组合） → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`contact user search --query "<姓名>"` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--conversation-id --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | browse-minutes | 1. `minutes list all --query "<关键词>" --limit ` → 取全量 `taskUuid`（翻页直至无更多；无主题筛选用 `minutes list mine`；**有时间范围时加 `--start`/`--end` 服务端过滤**，如 `--start "2026-04-01T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00"`） 2. **详情/元数据优先** `minutes get batch --ids `（仅 API 上限时拆多批）；**摘要专项**且无 batch 字段时再用并行 `get summary` 或 `**python scripts/minutes_recent_summary.py --limit `** 3. 汇总展示；**同一用户诉求下避免**「半截 list → 再 list 剩余」「拆 4 条一批 summary 连跑多轮」等无必要拆分 | | minutes-detail | 1. 确定 `taskUuid`：用户已提供 → 直接用；未提供 → `minutes list mine --limit 5` 让用户选（**有时间线索时加 `--start`/`--end`**，如「上周五的会」→ `--start "2026-05-23T00:00:00+08:00" --end "2026-05-23T23:59:59+08:00"`） 2. 并行拉取四维信息：`minutes get info --id ` `&` `minutes get summary --id ` `&` `minutes get keywords --id ` `&` `minutes get todos --id ` `& wait` 3. 整合输出：基础信息（标题、时间、参与人）→ AI 摘要 → 关键字 → 行动项/待办 4. **展示发言人列表**：从转写/info 提取所有发言人（含已标注姓名和匿名编号），列出每位发言人的发言次数和时长占比，引导用户：「是否需要查看某位发言人的详细内容总结？请输入姓名或编号」→ 用户选定 → 进入 `minutes-speaker-summarize` recipe 5.（可选）用户要求看原文 → `minutes get transcription --id ` | | minutes-speaker-summarize | 1. 读取转写 → `minutes get transcription --id ` 2. 声纹标注检查：已标注 → 跳 Step 6；匿名编号 → 继续 3. 转写原文推断（称呼/自我介绍/上下文指代）→ 高置信度跳 Step 6 4. 并发身份推断：`calendar event list` + `participant list` 取日程参与人（最高优先） & `aisearch person` & `chat message list` & `doc search` `& wait`；未找到同时段日程 → 引导用户提供日程链接或参会人名单；两路以上一致才下结论 5. 置信度判断：>70% 直接输出；≤70% 展示 TOP3 候选让用户选（最多一次） 6. 结构化总结输出（核心观点 + 问题 + Action Item + 立场）→ 追问是否替换发言人标注。详见 [10-minutes-speaker-match.md](./10-minutes-speaker-match.md) | | speaker-correct | 1. **查同时段日程**：从听记元数据获取录音开始时间 → `calendar event list`（前后 30 分钟内）→ 若匹配到日程则提取参会人名单并展示 2. **展示发言人状态表格**：列出所有发言人及标注状态（已识别 / 未标注 / 未标注，发言较少） 3. **让用户选择识别方式**：听音识人（裁剪代表性音频片段让用户辨认）/ 手动设置（用户直接告知对应关系）/ 智能匹配（结合参会人名单和发言内容推断） 4. **执行替换**：确认对应关系后，通讯录查询获取 dingUid → `dws contact user search --query "<姓名>" --format json` → 取 userId（长整型）→ `dws minutes speaker replace --id --from "发言人X" --to "<姓名>" --target-uid --format json`；多个匹配时列出候选让用户选；无匹配时执行不带 `--target-uid` 的替换 5. 替换成功后追问「还有其他发言人需要帮你识别和替换吗？」详见 [11-minutes-speaker-correct.md](./11-minutes-speaker-correct.md) | - diff --git a/skills/mono/references/intent-guide.md b/skills/mono/references/intent-guide.md index 31eda376..03668d30 100644 --- a/skills/mono/references/intent-guide.md +++ b/skills/mono/references/intent-guide.md @@ -279,7 +279,7 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}` - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析 - "发本地图片/文件/语音/视频到群里" — `dws chat message send ... --msg-type file --file <本地路径>`，CLI 内部自动上传并发送；png/jpg/pdf/mp4/zip 等任意扩展名都走这条，接收方看到的是可下载的文件附件。图片不会内联渲染，也不会生成 mediaId - "用已有 mediaId 发内联图片" — 仅当上游已经提供有效 mediaId 时，使用 `dws chat message send ... --msg-type image --media-id `；DWS CLI 不能把本地图片转换成 mediaId -- "发图片+文字说明" — 不要硬塞进一条命令；先发图片/文件消息再补一条 `--text "..."` 即可 +- "发图片+文字说明" — 不要硬塞进一条命令；先发图片/文件消息再补一条 `--content "..."` 即可 ```bash dws chat +messages-send --as user --chat-id --msg-type file --file ./screenshot.png --idempotency-key --format json @@ -465,7 +465,7 @@ dws todo task create --title "任务内容" --executors --format json ```bash # 群聊 -dws chat message send --group --msg-type file --file <本地路径> --format json +dws chat message send --conversation-id --msg-type file --file <本地路径> --format json # 单聊（推荐 --open-dingtalk-id；--user 也支持） dws chat message send --open-dingtalk-id --msg-type file --file <本地路径> --format json @@ -475,7 +475,7 @@ dws chat message send --open-dingtalk-id --msg-type file --file ### 图片/文件 + 文字说明 -不要把文字塞进 `--msg-type file` 命令（该命令不读 `--text`）。先发文件再补一条文本消息即可： +不要把文字塞进 `--msg-type file` 命令（该命令不读 `--content`）。先发文件再补一条文本消息即可： ```bash dws chat message send --open-dingtalk-id --msg-type file --file ./screenshot.png --format json @@ -487,5 +487,5 @@ dws chat message send --open-dingtalk-id --content "这是本 仅当上游已经提供有效的 `@lQL...` 形式 mediaId 时使用；DWS CLI 不提供本地文件到 mediaId 的转换能力： ```bash -dws chat message send --group --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json +dws chat message send --conversation-id --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json ``` diff --git a/skills/mono/references/products/chat.md b/skills/mono/references/products/chat.md index 2ddc7ca6..5fbff337 100644 --- a/skills/mono/references/products/chat.md +++ b/skills/mono/references/products/chat.md @@ -571,7 +571,7 @@ Flags: --本地图片、文件、音频或视频统一用 --msg-type file --file；图片会作为可下载的文件附件发送。--msg-type image --media-id 仅用于上游已经提供有效 mediaId 的场景。 ``` Usage: - dws chat message send [flags] [] + dws chat message send [flags] [] 富媒体消息路由: 场景 → msgType → 发送参数 @@ -581,27 +581,28 @@ Usage: 注意：本地 .png/.jpg 也按 file 发送，接收方看到的是可下载附件；DWS CLI 不能把本地文件转换成 mediaId。 Example: - dws chat message send --group --content "hello" + dws chat message send --conversation-id --content "hello" dws chat message send --user --content "请查收" dws chat message send --open-dingtalk-id --content "请查收" - dws chat message send --group "hello" - dws chat message send --group --title "周报提醒" --content "请大家本周五前提交周报" + dws chat message send --conversation-id "hello" + dws chat message send --conversation-id --title "周报提醒" --content "请大家本周五前提交周报" # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示 - dws chat message send --group --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' - # 幂等发送（24h 内相同 uuid 不重复投递） - dws chat message send --group --content "hello" --uuid "unique-id-123" - dws chat message send --group --at-all "<@all> 请大家注意" - dws chat message send --group --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 "<@openDingTalkId1> <@openDingTalkId2> 请查收" + dws chat message send --conversation-id --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)' + # 幂等发送（24h 内相同 idempotency key 不重复投递） + dws chat message send --conversation-id --content "hello" --idempotency-key "unique-id-123" + dws chat message send --conversation-id --at-all "<@all> 请大家注意" + dws chat message send --conversation-id --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 "<@openDingTalkId1> <@openDingTalkId2> 请查收" # 本地图片/文件/音频/视频统一作为 file 附件发送 - dws chat message send --group --msg-type file --file ./screenshot.png - dws chat message send --group --msg-type file --file ./report.pdf - dws chat message send --group --msg-type file --file ./recording.mp3 - dws chat message send --group --msg-type file --file ./demo.mp4 + dws chat message send --conversation-id --msg-type file --file ./screenshot.png + dws chat message send --conversation-id --msg-type file --file ./report.pdf + dws chat message send --conversation-id --msg-type file --file ./recording.mp3 + dws chat message send --conversation-id --msg-type file --file ./demo.mp4 # 仅当上游已有有效 mediaId 时发送内联图片 - dws chat message send --group --msg-type image --media-id + dws chat message send --conversation-id --msg-type image --media-id Flags: --content string 消息内容（推荐使用，也可用位置参数） - --group string 群聊 openconversation_id（群聊时必填） + --conversation-id string 群聊 openconversation_id（群聊时必填） + --group string --conversation-id 的兼容别名 --user string 单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一） --open-dingtalk-id string 单聊接收人 openDingTalkId（单聊时与 --user 二选一） --title string 消息标题（可选，默认「消息」） @@ -615,15 +616,15 @@ Flags: --file-type string 已有钉盘文件类型/扩展名（元数据兼容模式） --file string 本地文件路径（本地图片/文件/音视频配合 msgType=file 使用） --file-size int64 已有钉盘文件大小，单位字节（元数据兼容模式） - --uuid string 幂等 UUID，相同 uuid 在 24h 内不会重复发送（可选） + --idempotency-key string 幂等键，相同 key 在 24h 内不会重复发送（可选） --ai-tag 消息是否带 AI 发送角标（可选，默认 true） 注意: - --content 和位置参数二选一，--content 优先 - - --group、--user、--open-dingtalk-id 三者互斥，只需指定其一：群聊用 --group，单聊用 --user 或 --open-dingtalk-id + - --conversation-id、--user、--open-dingtalk-id 三者互斥，只需指定其一：群聊用 --conversation-id，单聊用 --user 或 --open-dingtalk-id - 纯文本/Markdown 单聊发送时 `--user` 和 `--open-dingtalk-id` 都可用；传 `--user` 时直接走 userId 发送能力 - - --group 的别名: --id, --chat, --conversation-id (均可替代 --group) - - --at-all 和 --at-open-dingtalk-ids 仅在 --group 群聊时生效，单聊时无效；当设置--at-all时，消息内容中一定要包含对应的占位符<@all>;当设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时，消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2> + - --conversation-id 的兼容别名: --group, --id, --chat + - --at-all 和 --at-open-dingtalk-ids 仅在 --conversation-id 群聊时生效，单聊时无效；当设置--at-all时，消息内容中一定要包含对应的占位符<@all>;当设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时，消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2> - **换行符**：消息内容按 Markdown 渲染，换行有两层要求，缺一不可： 1. 必须使用**真实换行符**（Unicode `U+000A`），而非字面量字符串 `\n`（反斜杠 + 字母 n）。程序或大模型构造参数时，须确保已正确反转义；否则全部内容会渲染在同一行 2. Markdown 规范下**单个换行不产生换行效果**。需要换行时请使用：段落分隔（连续两个真实换行符 `\n\n`）、行尾两个空格 + 真实换行符（硬换行 `
`），或直接写 HTML 的 `
` 标签 @@ -632,7 +633,7 @@ Flags: - `--msg-type image --media-id` 仅接受上游已经提供的有效 mediaId；DWS CLI 不提供本地文件到 mediaId 的上传或转换能力 - audio/video 仍是兼容的 file 语义别名，但本地文件的推荐路径保持为 `--msg-type file --file` - dentryId/spaceId 等参数仅用于调用方已经持有钉盘文件元数据的兼容场景，不是发送本地文件的前置步骤 - - --uuid 用于幂等发送，传入相同 uuid 在 24h 内不会重复投递消息（可选，群聊和单聊均支持） + - --idempotency-key 用于幂等发送，传入相同 key 在 24h 内不会重复投递消息；旧参数 --uuid 保留兼容（可选，群聊和单聊均支持） - 富媒体消息的单聊优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会尝试解析成 openDingTalkId 后发送 - 发送文字 + 文件时，先发送 `--msg-type file --file` 文件消息，再补一条文本或 Markdown 说明；这是两条独立消息 ``` @@ -645,7 +646,7 @@ Flags: 发送本地文件消息仍然支持，统一使用： ``` -dws chat message send --group --msg-type file --file ./report.pdf --format json +dws chat message send --conversation-id --msg-type file --file ./report.pdf --format json dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json ``` @@ -679,14 +680,14 @@ Flags: ```bash # 1. 发送后保留 openTaskId -dws chat message send --group --content "原始内容" +dws chat message send --conversation-id --content "原始内容" # 2. 查询得到 openMessageId 和 openConversationId dws chat message query-send-status --open-task-id # 3. 编辑消息 dws chat message edit --conversation-id --msg-id --text "更新后的内容" # 发送后撤回使用同一 ID 链 -dws chat message send --group --content "待撤回的内容" +dws chat message send --conversation-id --content "待撤回的内容" dws chat message query-send-status --open-task-id dws chat message recall --conversation-id --msg-id ``` @@ -2087,7 +2088,7 @@ Flags: 用户说"拉取和某人的单聊记录/单聊消息" → `chat message list --user`（用户明确说"单聊"时使用） 用户说"@我的消息/at我的/提及我的" → `chat message list-mentions` 用户说"未读消息会话/未读会话列表/我的未读会话" → `chat message list-unread-conversations` -用户说"发群消息(以个人身份)" → `chat message send --group` +用户说"发群消息(以个人身份)" → `chat message send --conversation-id` 用户说"发单聊消息(以个人身份)" → `chat message send --user`（有 userId 时）或 `chat message send --open-dingtalk-id`（有 openDingTalkId 时） 用户说"机器人发消息/机器人群发" → `chat message send-by-bot` 用户说"撤回我发的消息/撤回消息" → `chat message recall`（通过 IM 接口撤回当前用户自己发出的消息，需要 openConversationId + openMessageId） @@ -2250,7 +2251,7 @@ dws chat message list --group --time "2025-03-01 00:00:00" dws chat message list-unread-conversations --count 20 --format json # 3. 以个人身份发送群消息 -dws chat message send --group --title "周报提醒" "请大家本周五前提交周报" --format json +dws chat message send --conversation-id --title "周报提醒" "请大家本周五前提交周报" --format json # 4. 以个人身份单聊（通过 userId） dws chat message send --user "你好" --format json @@ -2352,8 +2353,8 @@ dws chat message send-by-bot --robot-code --group --msg-type file --file ./screenshot.png --format json -dws chat message send --group --content "这是本周的数据汇总" --format json +dws chat message send --conversation-id --msg-type file --file ./screenshot.png --format json +dws chat message send --conversation-id --content "这是本周的数据汇总" --format json ``` 机器人身份发送文件及说明： @@ -2374,7 +2375,7 @@ dws chat message send-by-bot --robot-code --group --group --msg-type image --image-url "https://example.com/image.png" --format json # 当前用户发送文件 -dws chat message send --group --msg-type file --file ./report.pdf --format json +dws chat message send --conversation-id --msg-type file --file ./report.pdf --format json # 机器人发送文件 dws chat message send-by-bot --robot-code --group --msg-type file --file-path ./report.pdf --format json @@ -2390,7 +2391,7 @@ dws chat message send --open-dingtalk-id --content "这是本 **已有 mediaId（仅当上游已经提供有效 mediaId 时才用）**： ```bash -dws chat message send --group --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json +dws chat message send --conversation-id --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json ``` #### 创建并推送流式卡片 — 向群聊或单聊发送流式卡片消息 @@ -2471,13 +2472,13 @@ Flags: - 审查方式：将即将发送的**全部参数**（收件人/群、消息内容、@对象、消息类型等）与用户的**原始需求**逐一对比，确认每个参数都能从原始需求中找到明确依据 - 如果存在任何不明确、有歧义或原始需求中未提及的参数（例如：用户没说发给谁、没说发到哪个群、消息内容与用户意图有出入、不确定是否需要 @某人等），**必须先向用户确认**，严禁自行假设或补全 - 典型需要确认的场景：用户只说了"发个消息"但没指定群/人；用户的描述可匹配多个群或多个联系人；消息文本由 agent 组织而非用户原文提供时需确认措辞 -- uuid 幂等参数（发消息最佳实践）： - - 发消息时建议始终带上 `--uuid` 参数，传入用户自行生成的唯一标识（如 UUID v4），用于幂等控制 - - 如果发送失败需要重试，重试时 `--uuid` 必须与首次发送保持一致，服务端据此去重，避免重复发消息 - - 如果不传 `--uuid`，每次调用都视为新消息，重试可能导致消息重复发送 +- idempotency key 幂等参数（发消息最佳实践）： + - 发消息时建议始终带上 `--idempotency-key` 参数，传入用户自行生成的唯一标识（如 UUID v4），用于幂等控制 + - 如果发送失败需要重试，重试时 `--idempotency-key` 必须与首次发送保持一致，服务端据此去重，避免重复发消息 + - 如果不传 `--idempotency-key`，每次调用都视为新消息，重试可能导致消息重复发送 - 此参数适用于 `chat message send`（群聊和单聊均支持） - `--group` 为群聊会话 ID (openconversation_id)，可从群搜索或群聊信息中获取 -- `chat message send` 的正文可用 `--content` 或位置参数（恰好 1 个）；群聊用 `--group`，单聊用 `--user`（userId）或 `--open-dingtalk-id`（openDingTalkId），三者互斥；纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力；`--at-all`、`--at-open-dingtalk-ids` 仅在 `--group` 群聊时生效；本地图片/文件/音视频统一用 `--msg-type file --file`，其中图片是可下载附件；`--msg-type image --media-id` 仅用于上游已经提供有效 mediaId 的内联图片 +- `chat message send` 的正文可用 `--content` 或位置参数（恰好 1 个）；群聊用 `--conversation-id`，单聊用 `--user`（userId）或 `--open-dingtalk-id`（openDingTalkId），三者互斥；纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力；`--at-all`、`--at-open-dingtalk-ids` 仅在 `--conversation-id` 群聊时生效；本地图片/文件/音视频统一用 `--msg-type file --file`，其中图片是可下载附件；`--msg-type image --media-id` 仅用于上游已经提供有效 mediaId 的内联图片 - `chat message list-all` 的四个参数（--start、--end、--limit、--cursor）每次请求都必须传递；翻页时用响应中的 nextCursor 值作为下次 --cursor - `chat message list` 的 `--group`、`--user`、`--open-dingtalk-id` 三者互斥，必须且只能指定其一 - `chat message list-by-sender` 不需要指定单聊/群聊，返回结果自带会话类型标识；`--sender-user-id`（userId）与 `--sender-open-dingtalk-id`（openDingTalkId）二选一；时间用 `--start`/`--end`（ISO-8601），分页用 `--limit`/`--cursor` diff --git a/skills/multi/dingtalk-calendar/references/03-meeting.md b/skills/multi/dingtalk-calendar/references/03-meeting.md index dc432c11..e65770e9 100644 --- a/skills/multi/dingtalk-calendar/references/03-meeting.md +++ b/skills/multi/dingtalk-calendar/references/03-meeting.md @@ -53,4 +53,4 @@ | Recipe | 行动指南（固定路线） | | ------------------ | ------------------- | | schedule-meeting | **见上文「两准则」**、**「搜房失败硬门禁」**。**未给时段且仅说「发起/开个会」**→ 不走本 recipe；当前 CLI 不支持实时视频会议，告知用户请在钉钉客户端操作。**未给时段但有预约意图**（"安排""约""定"等词）：追问具体开始/结束时间。**已有时段后**，按固定顺序执行：1. `dws calendar event create` 建日程；2. 有参会人则 `dws calendar participant add`；3. 再处理会议室。**无明确会议室范围**：可直接 `python scripts/calendar_schedule_meeting.py --title "<主题>" --start "<起始>" --end "<结束>" [--users ] [--book-room] [--dry-run]`。**有明确范围（某楼/层）**：先 `dws calendar room list-groups`，锁定该地点**最相关的承载 group**；若只有一个地点，`--room-group-id` 应只传这个最相关 group，**不要**把同楼内多个楼层 group 打包传入碰运气。只有用户明确给出多个允许地点时，才把这些 `group-id` 一并传给 `python scripts/calendar_schedule_meeting.py ... --book-room --room-group-id ""`。**用户点名具体会议室**：须手工 `dws calendar room search --start "" --end "" --group-id [--available] --format json`（**无** `--query`），在 JSON 中匹配名称取 **`rooms[].roomId` 唯一真值** → `dws calendar room add --event --rooms `；**不得**把用户输入的会议室名当 `roomId`。**一旦连续 2 次空结果 / 任意一次 `roomId invalid`**：**必须回读本节并立即收束判断**；若整园/限定范围内搜尽仍无 roomId 或无空房 → **下一条消息必须直接向用户汇报失败结论**；否则只能向用户确认是否放宽范围/改时间。**禁止**假设 roomId、禁止无 ID 调用 `room add`、禁止用日程详情绕路、禁止继续猜测 Mock/测试环境。细则见「会议室搜索早停」。 | -| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<变更通知>"` 通知变更 | +| reschedule-meeting | 1. `calendar event list --start "<起始ISO>" --end "<结束ISO>"` → 取 `eventId` 2. `calendar event update --id --start "<新起始ISO>" --end "<新结束ISO>"` 更新时间 3. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --conversation-id --content "<变更通知>"` 通知变更 | diff --git a/skills/multi/dingtalk-minutes/references/07-minutes.md b/skills/multi/dingtalk-minutes/references/07-minutes.md index 6b8751e1..3f81a910 100644 --- a/skills/multi/dingtalk-minutes/references/07-minutes.md +++ b/skills/multi/dingtalk-minutes/references/07-minutes.md @@ -27,8 +27,8 @@ dws minutes list mine --limit 5 --format json | Recipe | 行动指南（固定路线） | | ---------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| meeting-followup | 1. **提取待办优先**：`python scripts/minutes_extract_todos.py [--id ] [--limit N]` → 获取行动项列表 无脚本时按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors --priority <10/20/30/40>`（每条行动项；批量时切到 `dingtalk-todo` 的 batch-create-todo recipe，批量脚本只在该 sub-skill 内可用） 4. `chat message send --group --content "<通知内容>"` 通知已创建 | -| share-minutes | **拉摘要优先**：`python scripts/minutes_recent_summary.py [--limit N] [--output summary.md]` → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`aisearch person --query "<姓名>" --dimension name` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--group --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | +| meeting-followup | 1. **提取待办优先**：`python scripts/minutes_extract_todos.py [--id ] [--limit N]` → 获取行动项列表 无脚本时按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 2. 提取行动项 3. `aisearch person --query "<姓名>" --dimension name` → 取 `userId` → `todo task create --title "<行动项>" --executors --priority <10/20/30/40>`（每条行动项；批量时切到 `dingtalk-todo` 的 batch-create-todo recipe，批量脚本只在该 sub-skill 内可用） 4. `chat message send --conversation-id --content "<通知内容>"` 通知已创建 | +| share-minutes | **拉摘要优先**：`python scripts/minutes_recent_summary.py [--limit N] [--output summary.md]` → 获取近期听记摘要 备选手动：1. `minutes list mine` → 取 `taskUuid` 2. 用户选定 3. `minutes get summary --id ` → 取摘要 4. 单聊：`aisearch person --query "<姓名>" --dimension name` → 取 `openDingTalkId` → `chat message send --open-dingtalk-id --content "<摘要内容>"`（推荐）；群聊：`--conversation-id --content "<摘要内容>"` 发送。仅当无法获取 openDingTalkId 时才用 `--user `（备选） | | browse-minutes | 1. `minutes list all --query "<关键词>" --limit ` → 取全量 `taskUuid`（翻页直至无更多；无主题筛选用 `minutes list mine`；**有时间范围时加 `--start`/`--end` 服务端过滤**，如 `--start "2026-04-01T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00"`） 2. **详情/元数据优先** `minutes get batch --ids `（仅 API 上限时拆多批）；**摘要专项**且无 batch 字段时再用并行 `get summary` 或 `**python scripts/minutes_recent_summary.py --limit `** 3. 汇总展示；**同一用户诉求下避免**「半截 list → 再 list 剩余」「拆 4 条一批 summary 连跑多轮」等无必要拆分 | | minutes-raw-export | 适用"下载/导出最近一周听记原文/逐字稿/转写内容/完整记录"：1. 按用户时间词计算 `--start` / `--end`（最近一周示例：7 天前 00:00:00+08:00 到今天 23:59:59+08:00） 2. `minutes list all --start "" --end "" --format json` 获取范围内所有可见听记；为空时直接说明无相关数据 3. 对列表中每个 `taskUuid` 逐一 `minutes get transcription --id --format json`，如返回 `cursor` / `nextToken` / `nextCursor`，继续用 `--cursor ` 拉完后续页 4. 交付文件或最终回复必须包含各听记的真实转写段落，可附标题/时间/组织，禁止只交 summary 或让用户再选某一条 | | minutes-detail | 1. 确定 `taskUuid`：用户已提供 → 直接用；未提供 → `minutes list mine --limit 5` 让用户选（**有时间线索时加 `--start`/`--end`**，如「上周五的会」→ `--start "2026-05-23T00:00:00+08:00" --end "2026-05-23T23:59:59+08:00"`） 2. 并行拉取四维信息：`minutes get info --id ` `&` `minutes get summary --id ` `&` `minutes get keywords --id ` `&` `minutes get todos --id ` `& wait` 3. 整合输出：基础信息（标题、时间、参与人）→ AI 摘要 → 关键字 → 行动项/待办 4. **展示发言人列表**：从转写/info 提取所有发言人（含已标注姓名和匿名编号），列出每位发言人的发言次数和时长占比，引导用户：「是否需要查看某位发言人的详细内容总结？请输入姓名或编号」→ 用户选定 → 进入 `minutes-speaker-summarize` recipe 5.（可选）用户要求看原文 → `minutes get transcription --id ` | diff --git a/skills/multi/dingtalk-shared/references/intent-guide.md b/skills/multi/dingtalk-shared/references/intent-guide.md index a2afb092..a1ae3a14 100644 --- a/skills/multi/dingtalk-shared/references/intent-guide.md +++ b/skills/multi/dingtalk-shared/references/intent-guide.md @@ -291,14 +291,14 @@ alidocs 链接表面长得一样（`https://alidocs.dingtalk.com/i/nodes/{id}` - `+messages-send --user` 对所有内容类型都会通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId；无需手动预查，`--dry-run` 也会执行这次只读解析 - 已持有 openDingTalkId 时优先使用显式 `--open-dingtalk-id`，避免额外解析 - "发张图片/截图/语音/视频/文件到群里" / "发张图给某某" — **统一一条命令**：`dws chat message send ... --msg-type file --file <本地路径>`，CLI 内部自动上传并发送，**任意扩展名（png/jpg/pdf/mp4/zip…）都走这条** -- "发图片+文字说明" — 不要硬塞进一条命令；先发文件消息再补一条 `--text "..."` 即可 +- "发图片+文字说明" — 不要硬塞进一条命令；先发文件消息再补一条 `--content "..."` 即可 ```bash -dws chat message send --group --msg-type file --file ./screenshot.png --format json +dws chat message send --conversation-id --msg-type file --file ./screenshot.png --format json dws chat message send --open-dingtalk-id --msg-type file --file ./report.pdf --format json ``` -> ❌ 反模式：调 `dt_media_upload` / `extract_media_id.py` / `drive upload` / `drive download` 等前置工具再 `--msg-type image --media-id`。这是**旧链路**，仅当上游已持有 mediaId 才用；新场景一律 `--file-path` 直发，避免长链路与“空白图”现象。 +> ❌ 反模式：调 `dt_media_upload` / `extract_media_id.py` / `drive upload` / `drive download` 等前置工具再 `--msg-type image --media-id`。这是**旧链路**，仅当上游已持有 mediaId 才用；新场景一律 `--file` 直发，避免长链路与“空白图”现象。 > 单聊已持有 openDingTalkId 时优先使用 `--open-dingtalk-id`；传 `--user` 时 CLI 会通过通讯录关键词搜索做 userId 精确匹配后发送。 **用 `chat +messages-send-card` 的场景**： @@ -310,7 +310,7 @@ dws chat message send --open-dingtalk-id --msg-type file --file - "发送位置/坐标/地址到群里" / "发个位置给某某" — `dws chat message send ... --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --map-thumbnail-url @mediaId`；地图缩略图需先通过 `dt_media_upload` 上传获取 mediaId ```bash -dws chat message send --group --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --format json +dws chat message send --conversation-id --msg-type location --latitude <纬度> --longitude <经度> --location-name <地址名称> --format json ``` **用 `chat message send-by-bot` 的场景**： @@ -510,7 +510,7 @@ dws todo task create --title "任务内容" --executors --format json ```bash # 群聊 -dws chat message send --group --msg-type file --file <本地路径> --format json +dws chat message send --conversation-id --msg-type file --file <本地路径> --format json # 单聊（推荐 --open-dingtalk-id；--user 也支持） dws chat message send --open-dingtalk-id --msg-type file --file <本地路径> --format json @@ -520,7 +520,7 @@ dws chat message send --open-dingtalk-id --msg-type file --file ### 图片/文件 + 文字说明 -不要把文字塞进 `--msg-type file` 命令（该命令不读 `--text`）。先发文件再补一条文本消息即可： +不要把文字塞进 `--msg-type file` 命令（该命令不读 `--content`）。先发文件再补一条文本消息即可： ```bash dws chat message send --open-dingtalk-id --msg-type file --file ./screenshot.png --format json @@ -532,5 +532,5 @@ dws chat message send --open-dingtalk-id --content "这是本 仅当上游已经通过 `dt_media_upload` 拿到 `@lQL...` 形式的 mediaId 时使用： ```bash -dws chat message send --group --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json +dws chat message send --conversation-id --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json ``` diff --git a/skills/multi/dingtalk-todo/references/02-task.md b/skills/multi/dingtalk-todo/references/02-task.md index 6ce36df4..ef5bd98a 100644 --- a/skills/multi/dingtalk-todo/references/02-task.md +++ b/skills/multi/dingtalk-todo/references/02-task.md @@ -16,4 +16,4 @@ |--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | generate-progress-report | 1. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行
2. 交叉比对各源数据
3. `doc create --name "<报告名>" --content "<报告内容>"` | | batch-create-todo | 1. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 → 从结果提取任务条目
2. 每条：`aisearch person --query "<姓名>" --dimension name` → 取真实 `userId`；同名时先消歧
3. 逐条执行 `todo task create --title "<标题>" --executors --priority <10/20/30/40>`，从每次响应收集真实 `todoTaskId`；单批超 30 条须用户确认
4. 对全部 `todoTaskId` 并行执行 `todo task get --task-id `，逐项核对标题、执行者、优先级和截止时间；不能只以退出码或创建响应作为成功证据 | -| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors --priority <10/20/30/40>` → 取 `todoTaskId`
3. `todo task get --task-id ` 回读任务，确认无误后再通知
4. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --group --content "<通知内容>"` | +| assign-and-notify | 1. `aisearch person --query "<姓名>" --dimension name` → 取 `userId`
2. `todo task create --title "<标题>" --executors --priority <10/20/30/40>` → 取 `todoTaskId`
3. `todo task get --task-id ` 回读任务，确认无误后再通知
4. `chat search --query "<群名>"` → 取 `openConversationId` → `chat message send --conversation-id --content "<通知内容>"` | diff --git a/test/skill_tests.md b/test/skill_tests.md index 1cc8db02..8c1b6c4e 100644 --- a/test/skill_tests.md +++ b/test/skill_tests.md @@ -683,8 +683,8 @@ Agent 安装 dws skill 后，仅依据 skill 提供的参考文档，将自然 **chat_chat_message_send_001** - Prompt: 在群 openConvABC 发一条消息：大家好 -- Expected: `dws chat message send --group openConvABC "大家好" --format json` -- Flags: `--group` = `openConvABC` +- Expected: `dws chat message send --conversation-id openConvABC "大家好" --format json` +- Flags: `--conversation-id` = `openConvABC` **chat_chat_message_send_002** - Prompt: 给userId123发一条私聊消息，标题是提醒，内容是请查收报告 @@ -693,8 +693,8 @@ Agent 安装 dws skill 后，仅依据 skill 提供的参考文档，将自然 **chat_chat_message_send_003** - Prompt: 在群 groupId456 发一条带标题的通知：周报提醒，请大家本周五前提交周报 -- Expected: `dws chat message send --group groupId456 --title "周报提醒" "请大家本周五前提交周报" --format json` -- Flags: `--group` = `groupId456`, `--title` = `周报提醒` +- Expected: `dws chat message send --conversation-id groupId456 --title "周报提醒" "请大家本周五前提交周报" --format json` +- Flags: `--conversation-id` = `groupId456`, `--title` = `周报提醒` #### `dws chat message send-by-bot` diff --git a/test/skill_tests_results.md b/test/skill_tests_results.md index 9d60bb28..799f5c8c 100644 --- a/test/skill_tests_results.md +++ b/test/skill_tests_results.md @@ -887,7 +887,7 @@ **chat_chat_message_send_001** ✅ PASS - Prompt: 在群 openConvABC 发一条消息：大家好 -- Expected: `dws chat message send --group openConvABC "大家好" --format json` +- Expected: `dws chat message send --conversation-id openConvABC "大家好" --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send) - Flags: PASS (1 flags validated) @@ -903,7 +903,7 @@ **chat_chat_message_send_003** ✅ PASS - Prompt: 在群 groupId456 发一条带标题的通知：周报提醒，请大家本周五前提交周报 -- Expected: `dws chat message send --group groupId456 --title "周报提醒" "请大家本周五前提交周报" --format json` +- Expected: `dws chat message send --conversation-id groupId456 --title "周报提醒" "请大家本周五前提交周报" --format json` - Skill Reference: references/products/chat.md - Command path: PASS (chat message send) - Flags: PASS (2 flags validated) From 1ab8f113a506b6437a57cf3109708b8b530e44dc Mon Sep 17 00:00:00 2001 From: wxianfeng Date: Tue, 18 Aug 2026 16:55:37 +0800 Subject: [PATCH 229/250] test: close primary migration coverage gaps to #85349380 --- .../primary_param_native_compat_test.go | 53 +++++++++++++++++++ .../smart/primary_param_migration_test.go | 18 +++++++ 2 files changed, 71 insertions(+) diff --git a/internal/helpers/primary_param_native_compat_test.go b/internal/helpers/primary_param_native_compat_test.go index 4163760b..14e927f8 100644 --- a/internal/helpers/primary_param_native_compat_test.go +++ b/internal/helpers/primary_param_native_compat_test.go @@ -444,3 +444,56 @@ func TestNativePrimaryParamMissingErrorsRecommendPrimaryOnly(t *testing.T) { executeTodoEdge(t, &scriptedToolCaller{}, "task", "add-attachment", "--task-id", "42"), "file", "file-path") } + +func TestNativePrimaryParamPromotionErrorsPropagate(t *testing.T) { + chat := newChatCommand() + assertPromotionError := func(t *testing.T, err error) { + t.Helper() + if err == nil || !strings.Contains(err.Error(), "trying to get string value of flag of type bool") { + t.Fatalf("promotion error = %v", err) + } + } + + t.Run("webhook RunE", func(t *testing.T) { + target := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook") + cmd := &cobra.Command{} + cmd.Flags().String("content", "", "") + cmd.Flags().Bool("text", false, "") + if err := cmd.Flags().Set("text", "true"); err != nil { + t.Fatal(err) + } + assertPromotionError(t, target.RunE(cmd, nil)) + }) + + reply := findNativePrimaryLeaf(t, chat, "message", "reply") + newInvalidGroupCommand := func(t *testing.T) *cobra.Command { + t.Helper() + cmd := &cobra.Command{} + cmd.Flags().String("group", "", "") + cmd.Flags().Bool("conversation-id", false, "") + if err := cmd.Flags().Set("conversation-id", "true"); err != nil { + t.Fatal(err) + } + return cmd + } + + t.Run("reply PreRunE group", func(t *testing.T) { + assertPromotionError(t, reply.PreRunE(newInvalidGroupCommand(t), nil)) + }) + + t.Run("reply RunE group", func(t *testing.T) { + assertPromotionError(t, reply.RunE(newInvalidGroupCommand(t), nil)) + }) + + t.Run("reply RunE content", func(t *testing.T) { + cmd := &cobra.Command{} + cmd.Flags().String("group", "cid", "") + cmd.Flags().String("conversation-id", "", "") + cmd.Flags().String("content", "", "") + cmd.Flags().Bool("text", false, "") + if err := cmd.Flags().Set("text", "true"); err != nil { + t.Fatal(err) + } + assertPromotionError(t, reply.RunE(cmd, nil)) + }) +} diff --git a/internal/shortcut/smart/primary_param_migration_test.go b/internal/shortcut/smart/primary_param_migration_test.go index 9c6832cf..37144cb7 100644 --- a/internal/shortcut/smart/primary_param_migration_test.go +++ b/internal/shortcut/smart/primary_param_migration_test.go @@ -23,6 +23,7 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" + "github.com/spf13/cobra" ) func TestPrimaryParamMigrationSmartPayloadCompatibility(t *testing.T) { @@ -185,6 +186,23 @@ func TestPrimaryParamMigrationSmartSurfaceAndContract(t *testing.T) { } } +func TestPrimaryParamMigrationDocAppendRejectsBlankContent(t *testing.T) { + cmd := &cobra.Command{} + cmd.Flags().String("doc", "", "") + cmd.Flags().String("content", "", "") + cmd.Flags().String("text", "", "") + if err := cmd.Flags().Set("doc", "doc-1"); err != nil { + t.Fatal(err) + } + if err := cmd.Flags().Set("content", " "); err != nil { + t.Fatal(err) + } + err := DocAppend.Execute(shortcut.RuntimeContextForTest(cmd, DocAppend)) + if err == nil || !strings.Contains(err.Error(), "--content 不能为空") { + t.Fatalf("blank --content error = %v", err) + } +} + func smartRegisteredShortcut(t *testing.T, service, command string) shortcut.Shortcut { t.Helper() for _, spec := range shortcut.All() { From ede8e3c5550bff20888fe08111bca56a091c72f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 20:04:59 +0800 Subject: [PATCH 230/250] fix(skills): remove stale drive orphan allowlist --- skills/content-qa/mono-multi-coverage.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/skills/content-qa/mono-multi-coverage.yaml b/skills/content-qa/mono-multi-coverage.yaml index 5a1e458f..440c149e 100644 --- a/skills/content-qa/mono-multi-coverage.yaml +++ b/skills/content-qa/mono-multi-coverage.yaml @@ -170,9 +170,6 @@ orphan_scripts_allowlist: - path: dingtalk-aitable/scripts/aitable_import_via_task.py disposition: defer reason: "helper referenced indirectly / pending doc" - - path: dingtalk-drive/scripts/drive_tree_list.py - disposition: defer - reason: "legacy helper retained for compatibility; multi Drive uses bounded +list until the helper is revalidated" - path: dingtalk-minutes/scripts/minutes_list_parse.py disposition: defer reason: "pending doc reference" From f4cb8aa282d38c675680d1e876c7cd12da8e5e63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 20:59:39 +0800 Subject: [PATCH 231/250] fix(aitable): harden agent routes and composite contracts --- docs/shortcut-public-catalog.json | 4 +- internal/app/schema_shortcut_contract_test.go | 19 +++++++ internal/helpers/aitable.go | 17 +++++- .../helpers/aitable_command_edges_test.go | 54 ++++++++++++++++++ internal/helpers/helpers.go | 48 ++++++++++++++-- internal/helpers/helpers_core_test.go | 56 ++++++++++++++++++ internal/shortcut/aitable/aitable.go | 20 ++++--- .../aitable/base_composite_e2e_test.go | 11 +++- .../shortcut/aitable/composite_contract.go | 41 +++++++++++++ .../aitable/record_upsert_by_key_e2e_test.go | 27 +++++++++ internal/shortcut/aitable/table_bootstrap.go | 17 +++--- .../aitable/table_bootstrap_e2e_test.go | 27 +++++++++ internal/shortcut/runner.go | 20 +++++-- internal/shortcut/runner_coverage_test.go | 57 +++++++++++++++++++ .../shortcut/semantic_catalog_aitable.json | 2 +- skills/multi/dingtalk-aitable/SKILL.md | 40 ++++++++----- .../references/aitable-record-ops.md | 13 +++-- .../dingtalk-aitable/references/aitable.md | 10 ++-- .../aitable/aitable-dashboard-chart.md | 10 ++++ .../references/aitable/aitable-form.md | 10 ++++ .../references/intent-guide.md | 1 + 21 files changed, 450 insertions(+), 54 deletions(-) diff --git a/docs/shortcut-public-catalog.json b/docs/shortcut-public-catalog.json index 88a1e7ec..30bfa1d6 100644 --- a/docs/shortcut-public-catalog.json +++ b/docs/shortcut-public-catalog.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-08-18T14:20:44.224405", + "generated_at": "2026-08-18T17:38:50.904696", "count": 436, "results": [ { @@ -489,7 +489,7 @@ "risk": "read", "status": "reviewed_available", "disposition": "semantic_adapter", - "semantic_delta": "统一 ID、筛选、关键词和分页查询，并投影稳定的 records/count/cursor 结果。", + "semantic_delta": "统一 ID、筛选、关键词、字段投影和分页查询；fieldIds 只返回用户要求的列，并投影稳定的 records/count/cursor 结果。", "availability": "available" }, { diff --git a/internal/app/schema_shortcut_contract_test.go b/internal/app/schema_shortcut_contract_test.go index 55818b10..a4c5d83e 100644 --- a/internal/app/schema_shortcut_contract_test.go +++ b/internal/app/schema_shortcut_contract_test.go @@ -140,6 +140,25 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T) assertChatCatalogCompleteLeafContracts(t) } +func TestCrossPlatformCoverageAITableTableBootstrapPublishesResultContract(t *testing.T) { + leaf := executeShortcutSchemaQuery(t, "--cli-path", "aitable +table-bootstrap") + result, _ := leaf["result"].(map[string]any) + if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !schemaContractJSONEqual(got, want) { + t.Fatalf("aitable +table-bootstrap outcomes = %#v, want %#v", got, want) + } + dataSchema, _ := result["data_schema"].(map[string]any) + properties := schemaContractMap(dataSchema["properties"]) + status := properties["status"] + if got, want := schemaContractStringSlice(status["enum"]), []string{"success", "planned", "partial_success", "unknown"}; !schemaContractJSONEqual(got, want) { + t.Fatalf("aitable +table-bootstrap status enum = %#v, want %#v", got, want) + } + for _, property := range []string{"contractVersion", "operation", "executed", "retryable", "plan", "completedSteps", "verification", "checkpoint", "knownSideEffects", "result"} { + if properties[property] == nil { + t.Errorf("aitable +table-bootstrap final Result data_schema is missing %q", property) + } + } +} + func TestDeliveryWikiSpaceSearchDeclaresCompatibilityAdapter(t *testing.T) { leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search") if got := schemaContractString(leaf["interface_mode"]); got != "composite" { diff --git a/internal/helpers/aitable.go b/internal/helpers/aitable.go index 0342fe81..31e99fa9 100644 --- a/internal/helpers/aitable.go +++ b/internal/helpers/aitable.go @@ -791,15 +791,28 @@ const aitableMaxRetries = 3 // callAitableTool 是 aitable 专用的 MCP 调用入口，带自动重试。 // 替代直接调用 callMCPTool，对网络抖动和服务端瞬态错误进行透明重试。 func callAitableTool(toolName string, args map[string]any) error { + return callAitableToolContext(context.Background(), toolName, args) +} + +func callAitableToolContext(ctx context.Context, toolName string, args map[string]any) error { + if ctx == nil { + ctx = context.Background() + } var lastErr error for attempt := 0; attempt <= aitableMaxRetries; attempt++ { + if err := ctx.Err(); err != nil { + return err + } if attempt > 0 { backoff := time.Duration(1<<(attempt-1)) * time.Second // 1s, 2s, 4s fmt.Fprintf(os.Stderr, "[aitable retry %d/%d] %s after %v...\n", attempt, aitableMaxRetries, toolName, backoff) helperSleep(backoff) + if err := ctx.Err(); err != nil { + return err + } } - err := callMCPTool(toolName, args) + err := callMCPToolContext(ctx, toolName, args) if err == nil { return nil } @@ -1877,7 +1890,7 @@ config 结构参考： if v, _ := cmd.Flags().GetString("field-ids"); v != "" { toolArgs["fieldIds"] = parseCSVValues(v) } - return callAitableTool("get_fields", toolArgs) + return callAitableToolContext(cmd.Context(), "get_fields", toolArgs) }, } DeclareLeafMetadata(fieldGetCmd, LeafSpec{ diff --git a/internal/helpers/aitable_command_edges_test.go b/internal/helpers/aitable_command_edges_test.go index 986dc6fd..816232f2 100644 --- a/internal/helpers/aitable_command_edges_test.go +++ b/internal/helpers/aitable_command_edges_test.go @@ -18,6 +18,22 @@ type aitableCommandCoverageCaller struct { response map[string]string } +type aitableCommandContextKey struct{} + +type aitableCommandContextCaller struct { + value any +} + +func (c *aitableCommandContextCaller) CallTool(ctx context.Context, _, _ string, _ map[string]any) (*edition.ToolResult, error) { + c.value = ctx.Value(aitableCommandContextKey{}) + return nil, context.Canceled +} + +func (*aitableCommandContextCaller) Format() string { return "json" } +func (*aitableCommandContextCaller) DryRun() bool { return false } +func (*aitableCommandContextCaller) Fields() string { return "" } +func (*aitableCommandContextCaller) JQ() string { return "" } + func (c *aitableCommandCoverageCaller) CallTool(_ context.Context, _, tool string, _ map[string]any) (*edition.ToolResult, error) { if c.err != nil { return nil, c.err @@ -86,6 +102,44 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T if err := callAitableHelperTool("retry", nil); err == nil { t.Fatal("exhausted helper retries returned nil") } + + caller = &aitableTestCaller{} + installAitableDeps(t, caller) + if err := callAitableToolContext(nil, "nil-context", nil); err != nil { + t.Fatalf("nil context was not normalized: %v", err) + } + + caller = &aitableTestCaller{errors: []error{retryable}} + installAitableDeps(t, caller) + ctx, cancel := context.WithCancel(context.Background()) + helperSleep = func(time.Duration) { cancel() } + if err := callAitableToolContext(ctx, "cancel-during-backoff", nil); err != context.Canceled { + t.Fatalf("cancel during retry backoff = %v, want %v", err, context.Canceled) + } +} + +func TestCrossPlatformCoverageAitableFieldListPreservesCommandContext(t *testing.T) { + old := deps + t.Cleanup(func() { deps = old }) + caller := &aitableCommandContextCaller{} + InitDeps(caller) + deps.Out.w = io.Discard + deps.Out.errW = io.Discard + + root := newAitableCommand() + installExampleGlobalFlags(root) + root.SilenceErrors = true + root.SilenceUsage = true + root.SetOut(io.Discard) + root.SetErr(io.Discard) + root.SetArgs([]string{"field", "list", "--base-id=b", "--table-id=t"}) + ctx := context.WithValue(context.Background(), aitableCommandContextKey{}, "field-list-context") + if err := root.ExecuteContext(ctx); err == nil { + t.Fatal("field list context probe unexpectedly succeeded") + } + if caller.value != "field-list-context" { + t.Fatalf("field list caller context value = %#v", caller.value) + } } func TestCrossPlatformCoverageAitableCommandValidationEdges(t *testing.T) { diff --git a/internal/helpers/helpers.go b/internal/helpers/helpers.go index 384ddf32..be92c38e 100644 --- a/internal/helpers/helpers.go +++ b/internal/helpers/helpers.go @@ -155,7 +155,18 @@ func callMCPToolReturnTextOnServer(ctx context.Context, serverID, toolName strin // ReadToolCaller capability; if unavailable, it fails closed instead of // returning a synthetic dry-run envelope that looks like business data. func CallMCPReadToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) { - return callMCPReadToolReturnTextOnServer(context.Background(), serverID, toolName, args) + return CallMCPReadToolTextOnServerContext(context.Background(), serverID, toolName, args) +} + +// CallMCPReadToolTextOnServerContext is the cancellable form used by Cobra +// commands and composite shortcuts. Keeping the caller context attached to the +// transport lets SIGTERM/parent deadlines stop an in-flight MCP read and return +// a structured error instead of leaving the CLI silent until the host kills it. +func CallMCPReadToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) { + if ctx == nil { + ctx = context.Background() + } + return callMCPReadToolReturnTextOnServer(ctx, serverID, toolName, args) } func callMCPReadToolReturnTextOnServer(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) { @@ -266,7 +277,17 @@ func parseMCPToolTextResult(serverID, toolName string, result *edition.ToolResul // print path. Exported for the shortcut layer's multi-step ("smart") shortcuts, // which chain several tool calls and need each intermediate result as data. func CallMCPToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) { - return callMCPToolReturnTextOnServer(context.Background(), serverID, toolName, args) + return CallMCPToolTextOnServerContext(context.Background(), serverID, toolName, args) +} + +// CallMCPToolTextOnServerContext invokes one MCP tool while preserving the +// command's cancellation and deadline. Legacy callers may continue using +// CallMCPToolTextOnServer, which intentionally retains background context. +func CallMCPToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) { + if ctx == nil { + ctx = context.Background() + } + return callMCPToolReturnTextOnServer(ctx, serverID, toolName, args) } // CallMCPToolDataOnServer invokes one tool without printing and decodes its @@ -293,7 +314,11 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg // callMCPTool 是通用的 MCP 工具调用入口：自动路由 → 调用 → 格式化输出。 // 通过 resolveProductID() 自动确定目标 MCP Server，JSON 输出使用默认的 HTML 转义。 func callMCPTool(toolName string, args map[string]any) error { - return callMCPToolInternalOpts("", toolName, args, false) + return callMCPToolContext(context.Background(), toolName, args) +} + +func callMCPToolContext(ctx context.Context, toolName string, args map[string]any) error { + return callMCPToolInternalOptsContext(ctx, "", toolName, args, false) } // callMCPToolUnescaped 与 callMCPTool 功能相同，但 JSON 输出禁用 HTML 转义。 @@ -306,7 +331,7 @@ func callMCPToolUnescaped(toolName string, args map[string]any) error { // callMCPToolOnServer 在指定的 MCP Server 上调用工具，跳过 resolveProductID() 的自动路由。 // 用于需要显式指定 serverID 的场景（如 credit 等多 server 产品）。 func callMCPToolOnServer(serverID, toolName string, args map[string]any) error { - return callMCPToolInternalOpts(serverID, toolName, args, false) + return callMCPToolInternalOptsContext(context.Background(), serverID, toolName, args, false) } // CallMCPToolOnServer is the exported version of callMCPToolOnServer for use @@ -315,6 +340,13 @@ func CallMCPToolOnServer(serverID, toolName string, args map[string]any) error { return callMCPToolOnServer(serverID, toolName, args) } +// CallMCPToolOnServerContext is the cancellable print-path variant for +// Shortcut execution. It preserves the same output and error projection as the +// legacy wrapper while allowing the root signal context to abort transport. +func CallMCPToolOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) error { + return callMCPToolInternalOptsContext(ctx, serverID, toolName, args, false) +} + // GroupRunE is the exported version of groupRunE for use by extension packages. func GroupRunE(cmd *cobra.Command, args []string) error { return groupRunE(cmd, args) @@ -343,7 +375,13 @@ func MustGetStringFlag(cmd *cobra.Command, name string) string { // 3. 错误分类：网关错误 → 未登录 → PAT 错误 → 业务错误 // 4. 根据 --format 标志选择输出格式（json / table / raw） func callMCPToolInternalOpts(explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error { - ctx := context.Background() + return callMCPToolInternalOptsContext(context.Background(), explicitServerID, toolName, args, unescapeHTML) +} + +func callMCPToolInternalOptsContext(ctx context.Context, explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error { + if ctx == nil { + ctx = context.Background() + } // DryRun 模式：仅预览工具名和参数，不实际调用 MCP Server if deps.Caller.DryRun() { diff --git a/internal/helpers/helpers_core_test.go b/internal/helpers/helpers_core_test.go index 19ee7b29..1d823083 100644 --- a/internal/helpers/helpers_core_test.go +++ b/internal/helpers/helpers_core_test.go @@ -39,6 +39,20 @@ type helpersReadCaller struct { readCalls int } +type helpersContextCaller struct { + *helpersCoreCaller + seenErr error +} + +func (c *helpersContextCaller) CallTool(ctx context.Context, _ string, _ string, _ map[string]any) (*edition.ToolResult, error) { + c.calls++ + c.seenErr = ctx.Err() + if c.seenErr != nil { + return nil, c.seenErr + } + return nil, errors.New("stop after context capture") +} + func (c *helpersReadCaller) CallReadTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) { c.readCalls++ return c.readResult, c.readErr @@ -128,6 +142,48 @@ func TestCrossPlatformCoverageReadLookupInitializationAndRegularExecution(t *tes } } +func TestCrossPlatformCoverageMCPContextWrappersPreserveCancellation(t *testing.T) { + caller := &helpersContextCaller{helpersCoreCaller: &helpersCoreCaller{format: "json"}} + installHelpersCoreDeps(t, caller) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + + if _, err := CallMCPToolTextOnServerContext(ctx, "aitable", "get_fields", nil); err == nil { + t.Fatal("cancelled text call unexpectedly succeeded") + } + if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 1 { + t.Fatalf("text call context/calls = %v, %d", caller.seenErr, caller.calls) + } + + if err := CallMCPToolOnServerContext(ctx, "aitable", "get_fields", nil); err == nil { + t.Fatal("cancelled print call unexpectedly succeeded") + } + if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 2 { + t.Fatalf("print call context/calls = %v, %d", caller.seenErr, caller.calls) + } + + // Public context-aware wrappers intentionally accept nil for compatibility, + // but must normalize it before crossing the transport boundary. + if _, err := CallMCPToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil { + t.Fatal("nil-context text call unexpectedly succeeded with a nil result") + } + if caller.seenErr != nil || caller.calls != 3 { + t.Fatalf("nil-context text call context/calls = %v, %d", caller.seenErr, caller.calls) + } + if _, err := CallMCPReadToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil { + t.Fatal("nil-context read call unexpectedly succeeded with a nil result") + } + if caller.seenErr != nil || caller.calls != 4 { + t.Fatalf("nil-context read call context/calls = %v, %d", caller.seenErr, caller.calls) + } + if err := CallMCPToolOnServerContext(nil, "aitable", "get_fields", nil); err == nil { + t.Fatal("nil-context print call unexpectedly succeeded with a nil result") + } + if caller.seenErr != nil || caller.calls != 5 { + t.Fatalf("nil-context print call context/calls = %v, %d", caller.seenErr, caller.calls) + } +} + func TestCrossPlatformCoverageSharedDependenciesRoutingAndWrappers(t *testing.T) { oldDeps := deps deps = nil diff --git a/internal/shortcut/aitable/aitable.go b/internal/shortcut/aitable/aitable.go index d36cd18c..ac7443da 100644 --- a/internal/shortcut/aitable/aitable.go +++ b/internal/shortcut/aitable/aitable.go @@ -659,8 +659,8 @@ var RecordQuery = shortcut.Shortcut{ Service: "aitable", Command: "+record-query", Product: serverMain, - Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）", - Intent: "当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。", + Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）", + Intent: "读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。", Risk: shortcut.RiskRead, Safety: contract.SafetySpec{ Effect: "read", Risk: "low", @@ -674,17 +674,20 @@ var RecordQuery = shortcut.Shortcut{ CLIPath: "aitable +record-query", PrimaryCLIPath: "aitable +record-query", }, - Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）", + Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）", Interface: &contract.InterfaceSpec{ Mode: "composite", Availability: "available", Reason: "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.", }, Selection: contract.SelectionSpec{ - AgentSummary: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）", - UseWhen: []string{"当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。"}, + AgentSummary: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）", + UseWhen: []string{"读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。"}, AvoidWhen: []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"}, - Examples: []string{"dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50"}, + Examples: []string{ + "dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50", + "dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS", + }, }, }, Flags: []shortcut.Flag{ @@ -698,7 +701,10 @@ var RecordQuery = shortcut.Shortcut{ {Name: "limit", Type: shortcut.FlagInt, Desc: "单次最大记录数，默认 100（可选）"}, {Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标（可选）"}, }, - Tips: []string{`dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`}, + Tips: []string{ + `dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`, + `dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS`, + }, Execute: func(rt *shortcut.RuntimeContext) error { params := map[string]any{ "baseId": rt.Str("base-id"), diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index ea031a98..d436371e 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -5,6 +5,7 @@ package aitable import ( "bytes" + "context" "encoding/json" "errors" "fmt" @@ -13,6 +14,7 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/spf13/cobra" ) @@ -25,11 +27,18 @@ func runAITableCompositeCLI(t *testing.T, caller *upsertByKeyCaller, command str root.PersistentFlags().Bool("dry-run", false, "") root.PersistentFlags().String("format", "json", "") root.AddCommand(shortcut.Commands()...) + ctx, _ := output.WithResultStore(context.Background()) + root.SetContext(ctx) stdout := &bytes.Buffer{} root.SetOut(stdout) root.SetErr(&bytes.Buffer{}) root.SetArgs(append([]string{"aitable", command}, args...)) - err := root.Execute() + executed, err := root.ExecuteC() + if err == nil && output.UsesUnifiedResult(executed) { + if _, _, emitErr := output.EmitStoredResult(executed); emitErr != nil { + return stdout.String(), emitErr + } + } return stdout.String(), err } diff --git a/internal/shortcut/aitable/composite_contract.go b/internal/shortcut/aitable/composite_contract.go index 1e100eee..64f9312d 100644 --- a/internal/shortcut/aitable/composite_contract.go +++ b/internal/shortcut/aitable/composite_contract.go @@ -4,12 +4,53 @@ package aitable import ( + "encoding/json" "strings" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" ) +func aitableCompositeContractWithResult(command, description, useWhen, avoidWhen, example string, result *contract.ResultSpec) corecmd.ContractDecl { + declaration := aitableCompositeContract(command, description, useWhen, avoidWhen, example) + declaration.Result = result + return declaration +} + +func aitableTableBootstrapResultSpec() *contract.ResultSpec { + return &contract.ResultSpec{ + Outcomes: []contract.ResultOutcome{ + contract.ResultOutcomeSuccess, + contract.ResultOutcomeFailure, + }, + DataSchema: json.RawMessage(`{ + "type":"object", + "description":"AI Table 数据表初始化的执行计划、进度、验证证据和恢复信息", + "properties":{ + "contractVersion":{"type":"string","description":"复合操作业务回执版本","const":"aitable.composite.v1"}, + "operation":{"type":"string","description":"复合操作标识","const":"table_bootstrap"}, + "status":{"type":"string","description":"业务执行状态；失败时同结构位于 error.details.result","enum":["success","planned","partial_success","unknown"]}, + "executed":{"type":"boolean","description":"是否已开始执行远端操作"}, + "retryable":{"type":"boolean","description":"当前回执是否允许直接重试"}, + "requestedCount":{"type":"integer","description":"请求创建的字段数量","minimum":0}, + "completedCount":{"type":"integer","description":"已完成并验证的字段数量","minimum":0}, + "failedCount":{"type":"integer","description":"已确认失败的字段数量","minimum":0}, + "resolved":{"type":"object","description":"已解析的 Base、数据表名称和稳定 ID","additionalProperties":true}, + "plan":{"type":"array","description":"dry-run 或执行前生成的有序操作计划","items":{"type":"object","description":"一个计划步骤","properties":{"index":{"type":"integer","description":"步骤序号"},"name":{"type":"string","description":"步骤名称"},"tool":{"type":"string","description":"步骤使用的 MCP 工具"},"status":{"type":"string","description":"步骤状态"},"offset":{"type":"integer","description":"分片起始偏移"},"count":{"type":"integer","description":"步骤处理数量"},"arguments":{"type":"object","description":"步骤参数摘要","additionalProperties":true},"result":{"type":"object","description":"步骤结果摘要","additionalProperties":true},"error":{"type":"string","description":"步骤错误摘要"}},"required":["index","name","status"],"additionalProperties":false}}, + "completedSteps":{"type":"array","description":"已完成步骤及其验证摘要","items":{"type":"object","description":"一个已完成步骤","properties":{"index":{"type":"integer","description":"步骤序号"},"name":{"type":"string","description":"步骤名称"},"tool":{"type":"string","description":"步骤使用的 MCP 工具"},"status":{"type":"string","description":"步骤状态"},"offset":{"type":"integer","description":"分片起始偏移"},"count":{"type":"integer","description":"步骤处理数量"},"arguments":{"type":"object","description":"步骤参数摘要","additionalProperties":true},"result":{"type":"object","description":"步骤结果摘要","additionalProperties":true},"error":{"type":"string","description":"步骤错误摘要"}},"required":["index","name","status"],"additionalProperties":false}}, + "verification":{"type":"object","description":"创建后读回验证证据","additionalProperties":true}, + "checkpoint":{"type":"object","description":"失败或部分成功后的恢复检查点","additionalProperties":true}, + "nextCommand":{"type":"string","description":"用于核验或恢复的下一条可执行命令"}, + "knownSideEffects":{"type":"array","description":"已确认发生的远端副作用","items":{"type":"object","description":"一个已确认副作用","additionalProperties":true}}, + "warnings":{"type":"array","description":"不阻断最终验证的警告信息","items":{"type":"string"}}, + "result":{"type":"object","description":"成功时创建并验证的数据表结构","properties":{"baseId":{"type":"string","description":"目标 Base ID"},"tableId":{"type":"string","description":"新数据表稳定 ID"},"tableName":{"type":"string","description":"新数据表名称"},"fields":{"type":"array","description":"读回验证后的字段结构","items":{"type":"object","description":"一个已验证字段","additionalProperties":true}}},"required":["baseId","tableId","tableName","fields"],"additionalProperties":true} + }, + "required":["contractVersion","operation","status","executed","retryable"], + "additionalProperties":false + }`), + } +} + func aitableCompositeContract(command, description, useWhen, avoidWhen, example string) corecmd.ContractDecl { name := strings.TrimPrefix(command, "+") name = strings.ReplaceAll(name, "-", "_") diff --git a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go index 2fc9333f..2304cf6c 100644 --- a/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go +++ b/internal/shortcut/aitable/record_upsert_by_key_e2e_test.go @@ -321,6 +321,33 @@ func runRecordQueryShortcutCLI(t *testing.T, caller *upsertByKeyCaller, limit in return payload, err } +func TestCrossPlatformCoverageRecordQueryProjectsRequestedFieldsE2E(t *testing.T) { + caller := &upsertByKeyCaller{} + caller.callFn = func(_ int, product, tool string, args map[string]any) (string, error) { + if product != serverMain || tool != "query_records" { + t.Fatalf("record projection call = %s/%s", product, tool) + } + recordIDs, _ := args["recordIds"].([]string) + fieldIDs, _ := args["fieldIds"].([]string) + if !slices.Equal(recordIDs, []string{"r1", "r2"}) || !slices.Equal(fieldIDs, []string{"fldName", "fldStatus"}) { + t.Fatalf("record projection args = %#v", args) + } + return pagedRecordQueryResponse(t, []map[string]any{ + {"recordId": "r1", "cells": map[string]any{"fldName": "青云制造", "fldStatus": "跟进中"}}, + {"recordId": "r2", "cells": map[string]any{"fldName": "远海物流", "fldStatus": "已成交"}}, + }, args), nil + } + payload, err := runRecordQueryShortcutCLI(t, caller, 2, + "--record-ids", "r1,r2", "--field-ids", "fldName,fldStatus") + if err != nil || payload["success"] != true || len(caller.calls) != 1 { + t.Fatalf("record projection = payload:%#v err:%v calls:%#v", payload, err, caller.calls) + } + raw, err := json.Marshal(payload) + if err != nil || bytes.Contains(raw, []byte("fldAmount")) { + t.Fatalf("record projection leaked an unrequested field: %s (err=%v)", raw, err) + } +} + func TestCrossPlatformCoverageRecordQueryServicePageBoundariesE2E(t *testing.T) { for _, size := range []int{20, 21, 22, 100} { t.Run(fmt.Sprintf("size_%d", size), func(t *testing.T) { diff --git a/internal/shortcut/aitable/table_bootstrap.go b/internal/shortcut/aitable/table_bootstrap.go index 010faf78..6843be9c 100644 --- a/internal/shortcut/aitable/table_bootstrap.go +++ b/internal/shortcut/aitable/table_bootstrap.go @@ -9,25 +9,28 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" ) var TableBootstrap = shortcut.Shortcut{ - Service: "aitable", - Command: "+table-bootstrap", - Product: serverMain, - Description: "在已有 Base 中一次创建数据表和字段，自动分片并读回验证", - Intent: "当你已有 baseId、需要新增一张带完整字段结构的数据表时使用；替代 table create 后连续 field create 和手工验证。", - Risk: shortcut.RiskWrite, + OutputRollout: output.RolloutUnifiedActive, + Service: "aitable", + Command: "+table-bootstrap", + Product: serverMain, + Description: "在已有 Base 中一次创建数据表和字段，自动分片并读回验证", + Intent: "当你已有 baseId、需要新增一张带完整字段结构的数据表时使用；替代 table create 后连续 field create 和手工验证。", + Risk: shortcut.RiskWrite, Safety: contract.SafetySpec{ Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "non_idempotent", }, - Contract: aitableCompositeContract( + Contract: aitableCompositeContractWithResult( "+table-bootstrap", "在已有 Base 中一次创建数据表和字段，自动分片并读回验证", "当你已有 baseId、需要新增一张带完整字段结构的数据表时使用；替代 table create 后连续 field create 和手工验证。", "需要同时新建 Base 用 +base-bootstrap；复制现有表用 +table-copy；只补字段用 field create", `dws aitable +table-bootstrap --base-id BASE_ID --name "任务" --fields '[{"fieldName":"标题","type":"text"}]'`, + aitableTableBootstrapResultSpec(), ), Flags: []shortcut.Flag{ {Name: "base-id", Type: shortcut.FlagString, Desc: "目标 Base ID", Required: true}, diff --git a/internal/shortcut/aitable/table_bootstrap_e2e_test.go b/internal/shortcut/aitable/table_bootstrap_e2e_test.go index 9941dc71..c7cb9e1f 100644 --- a/internal/shortcut/aitable/table_bootstrap_e2e_test.go +++ b/internal/shortcut/aitable/table_bootstrap_e2e_test.go @@ -6,12 +6,39 @@ package aitable import ( "encoding/json" "errors" + "reflect" "strings" "testing" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" ) +func TestCrossPlatformCoverageTableBootstrapPublishesResultContract(t *testing.T) { + result, err := contract.NormalizeResultSpec(TableBootstrap.Contract.Result, "aitable.shortcut_table_bootstrap") + if err != nil { + t.Fatalf("normalize table bootstrap Result: %v", err) + } + wantOutcomes := []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure} + if result == nil || !reflect.DeepEqual(result.Outcomes, wantOutcomes) { + t.Fatalf("table bootstrap outcomes = %#v, want %#v", result, wantOutcomes) + } + var schema map[string]any + if err := json.Unmarshal(result.DataSchema, &schema); err != nil { + t.Fatalf("decode table bootstrap data_schema: %v", err) + } + properties, _ := schema["properties"].(map[string]any) + status, _ := properties["status"].(map[string]any) + if got, want := mustJSON(t, status["enum"]), `["success","planned","partial_success","unknown"]`; got != want { + t.Fatalf("table bootstrap status enum = %s, want %s", got, want) + } + for _, property := range []string{"contractVersion", "operation", "executed", "retryable", "plan", "completedSteps", "verification", "checkpoint", "knownSideEffects", "result"} { + if properties[property] == nil { + t.Errorf("table bootstrap data_schema is missing %q", property) + } + } +} + func TestCrossPlatformCoverageTableBootstrapCreatesChunksAndVerifies(t *testing.T) { fields := bootstrapFields(16) caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ diff --git a/internal/shortcut/runner.go b/internal/shortcut/runner.go index ce7d6260..f265ce60 100644 --- a/internal/shortcut/runner.go +++ b/internal/shortcut/runner.go @@ -14,6 +14,7 @@ package shortcut import ( + "context" "encoding/json" "fmt" "strings" @@ -160,9 +161,9 @@ func (rt *RuntimeContext) CallMCP(tool string, params map[string]any) error { // The legacy caller owns dry-run presentation (including its human // preview for non-JSON formats) and does not cross the business-call // boundary. Keep using it so dual validation changes no bytes. - return helpers.CallMCPToolOnServer(rt.shortcut.product(), tool, params) + return helpers.CallMCPToolOnServerContext(rt.commandContext(), rt.shortcut.product(), tool, params) } - text, err := helpers.CallMCPToolTextOnServer(rt.shortcut.product(), tool, params) + text, err := helpers.CallMCPToolTextOnServerContext(rt.commandContext(), rt.shortcut.product(), tool, params) if err != nil { return err } @@ -175,7 +176,7 @@ func (rt *RuntimeContext) CallMCP(tool string, params map[string]any) error { // shadow unified result. return helpers.RenderLegacyMCPText(tool, text) } - return helpers.CallMCPToolOnServer(rt.shortcut.product(), tool, params) + return helpers.CallMCPToolOnServerContext(rt.commandContext(), rt.shortcut.product(), tool, params) } func legacyMCPPayload(text string) any { @@ -256,7 +257,7 @@ func (rt *RuntimeContext) callMCPData(product, tool string, params map[string]an if params == nil { params = map[string]any{} } - text, err := helpers.CallMCPToolTextOnServer(product, tool, params) + text, err := helpers.CallMCPToolTextOnServerContext(rt.commandContext(), product, tool, params) if err != nil { return nil, err } @@ -274,7 +275,7 @@ func (rt *RuntimeContext) callMCPReadData(product, tool string, params map[strin if params == nil { params = map[string]any{} } - text, err := helpers.CallMCPReadToolTextOnServer(product, tool, params) + text, err := helpers.CallMCPReadToolTextOnServerContext(rt.commandContext(), product, tool, params) if err != nil { return nil, err } @@ -292,7 +293,7 @@ func (rt *RuntimeContext) callMCPWriteData(product, tool string, params map[stri if params == nil { params = map[string]any{} } - text, err := helpers.CallMCPToolTextOnServer(product, tool, params) + text, err := helpers.CallMCPToolTextOnServerContext(rt.commandContext(), product, tool, params) if err != nil { return nil, err } @@ -312,6 +313,13 @@ func (rt *RuntimeContext) callMCPWriteData(product, tool string, params map[stri return out, nil } +func (rt *RuntimeContext) commandContext() context.Context { + if rt != nil && rt.cmd != nil && rt.cmd.Context() != nil { + return rt.cmd.Context() + } + return context.Background() +} + // Output prints a (typically reshaped/projected) payload honouring the root // --format/--jq/--fields flags. Multi-step shortcuts use it to emit a clean, // composed result instead of the raw MCP response — the output-projection diff --git a/internal/shortcut/runner_coverage_test.go b/internal/shortcut/runner_coverage_test.go index e70d6f72..bb83d228 100644 --- a/internal/shortcut/runner_coverage_test.go +++ b/internal/shortcut/runner_coverage_test.go @@ -14,9 +14,26 @@ import ( apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" "github.com/spf13/cobra" ) +type runtimeContextKey struct{} + +type runtimeContextCaller struct { + value any +} + +func (c *runtimeContextCaller) CallTool(ctx context.Context, _ string, _ string, _ map[string]any) (*edition.ToolResult, error) { + c.value = ctx.Value(runtimeContextKey{}) + return nil, errors.New("stop after context capture") +} + +func (*runtimeContextCaller) Format() string { return "json" } +func (*runtimeContextCaller) DryRun() bool { return false } +func (*runtimeContextCaller) Fields() string { return "" } +func (*runtimeContextCaller) JQ() string { return "" } + func TestCrossPlatformCoverageRuntimeContextForTest(t *testing.T) { cmd := &cobra.Command{Use: "run"} rt := RuntimeContextForTest(cmd, Shortcut{Service: "sample", Command: "run"}) @@ -25,6 +42,46 @@ func TestCrossPlatformCoverageRuntimeContextForTest(t *testing.T) { } } +func TestCrossPlatformCoverageRuntimeMCPCallsPreserveCommandContext(t *testing.T) { + caller := &runtimeContextCaller{} + old := helpers.GetCaller() + t.Cleanup(func() { helpers.InitDeps(old) }) + helpers.InitDeps(caller) + + ctx := context.WithValue(context.Background(), runtimeContextKey{}, "command-context") + cmd := &cobra.Command{Use: "+write"} + cmd.SetContext(ctx) + output.SetCommandRollout(cmd, output.RolloutDualValidate) + rt := RuntimeContextForTest(cmd, Shortcut{Service: "aitable", Command: "+write"}) + if err := rt.CallMCP("update_records", map[string]any{"id": "r1"}); err == nil { + t.Fatal("dual-validate context capture unexpectedly succeeded") + } + if caller.value != "command-context" { + t.Fatalf("dual-validate caller context value = %#v", caller.value) + } + if _, err := rt.CallMCPWriteDataStrict("aitable", "update_records", map[string]any{"id": "r1"}); err == nil { + t.Fatal("capture caller unexpectedly succeeded") + } + if caller.value != "command-context" { + t.Fatalf("caller context value = %#v", caller.value) + } + + dryCaller := &dualValidateCaller{format: "json", dryRun: true} + helpers.InitDeps(dryCaller) + dryCmd := &cobra.Command{Use: "+read"} + dryCmd.Flags().Bool("dry-run", true, "") + output.SetCommandRollout(dryCmd, output.RolloutDualValidate) + var dryOut bytes.Buffer + helpers.GetFormatter().SetWriters(&dryOut, &dryOut) + dryRT := RuntimeContextForTest(dryCmd, Shortcut{Service: "aitable", Command: "+read"}) + if err := dryRT.CallMCP("get_fields", map[string]any{"baseId": "b"}); err != nil { + t.Fatalf("dual-validate dry-run call = %v", err) + } + if !strings.Contains(dryOut.String(), `"dry_run": true`) { + t.Fatalf("dual-validate dry-run output = %q", dryOut.String()) + } +} + func TestShortcutCommandResultRejectsStringSuccess(t *testing.T) { result := shortcutCommandResult(map[string]any{"success": "false"}) env, err := output.EnvelopeFromResult(result) diff --git a/internal/shortcut/semantic_catalog_aitable.json b/internal/shortcut/semantic_catalog_aitable.json index 007c4f82..e4afda87 100644 --- a/internal/shortcut/semantic_catalog_aitable.json +++ b/internal/shortcut/semantic_catalog_aitable.json @@ -24,7 +24,7 @@ "+field-update": {"disposition":"semantic_adapter","semantic_delta":"统一字段名称、类型配置和 AI 配置的增量更新输入。","risk":"write","public":true,"reviewed":true}, "+field-delete": {"disposition":"schema_leaf","semantic_delta":"不可逆删除字段的一对一入口，显式发布数据丢失风险。","risk":"high-risk-write","public":true,"reviewed":true}, - "+record-query": {"disposition":"semantic_adapter","semantic_delta":"统一 ID、筛选、关键词和分页查询，并投影稳定的 records/count/cursor 结果。","risk":"read","public":true,"reviewed":true}, + "+record-query": {"disposition":"semantic_adapter","semantic_delta":"统一 ID、筛选、关键词、字段投影和分页查询；fieldIds 只返回用户要求的列，并投影稳定的 records/count/cursor 结果。","risk":"read","public":true,"reviewed":true}, "+record-update": {"disposition":"primary_smart","semantic_delta":"自动按 100 条分片更新并逐条读回验证；失败返回可续跑的 nextOffset。","risk":"write","public":true,"reviewed":true}, "+record-delete": {"disposition":"primary_smart","semantic_delta":"自动按 100 条分片删除；每批仅在所有目标 recordId 读回均不存在时成功，失败提供 nextOffset。","risk":"high-risk-write","public":true,"reviewed":true}, "+record-query-empty": {"disposition":"semantic_adapter","semantic_delta":"扫描记录并按用户字段为空的语义过滤空行，避免调用方手工判断 cells。","risk":"read","public":true,"reviewed":true}, diff --git a/skills/multi/dingtalk-aitable/SKILL.md b/skills/multi/dingtalk-aitable/SKILL.md index b5ab7e79..3e38f5ce 100644 --- a/skills/multi/dingtalk-aitable/SKILL.md +++ b/skills/multi/dingtalk-aitable/SKILL.md @@ -19,7 +19,7 @@ metadata: - 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。 - 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。 - 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。 -- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。 +- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；本轮用户已明确要求执行、目标与影响无歧义的非破坏性写操作时，该明确指令就是本次确认，首次调用直接携带 Runtime 所需的 `--yes`，不先制造 `confirmation_required`。删除、停用自动化等破坏性或高风险动作仍须先说明对象、动作与影响并取得独立确认。 - 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。 - 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。 - 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。 @@ -40,12 +40,14 @@ metadata: | 用户意图 | 唯一推荐入口 | 关键边界 | |---|---|---| | 从 URL 解析稳定 ID | `dws aitable +url-resolve --url ` | 只解析 URL 中已有的 baseId/tableId/viewId/recordId，不做远端名称搜索 | -| 按名称定位 Base/Table | `dws aitable +resolve-base --name <名称>` → `dws aitable +resolve-table --base --name <表名>` | 默认精确匹配；只有用户明确接受模糊匹配时才加 `--fuzzy` | +| 按名称唯一定位并操作 Base/Table | `dws aitable +resolve-base --name <名称>` → `dws aitable +resolve-table --base --name <表名>` | 默认精确匹配；只有用户明确接受模糊匹配时才加 `--fuzzy` | | 浏览 Base 下的数据表 | `dws aitable +list-tables --base ` | 只返回 tableId/tableName，不加载字段 | -| 搜索 Base | `dws aitable +base-search --query <关键词>` | 单次返回；不要将 `+base-list`（最近访问）声称为全量目录 | -| 新建 Base 与整套表字段 | `+base-bootstrap` | 高频准确 flags 与 JSON 形状见唯一执行 Reference；不要先调用 Help | -| 已有 Base 新建一张表与字段 | `+table-bootstrap` | 自动按 15 个字段分片并读回验证；替代 `table create` 后连续 `field create` | -| 查询、筛选、排序或分页 | `dws aitable +record-query --base-id --table-id ` | 单页/精确 ID 优先；明确要求全量时改用原子 `record query --all --page-limit ` | +| 搜索 Base 候选或检查是否存在 | `dws aitable +base-search --query <关键词>` | 用户说“搜索/找一下/候选/如果没有就创建”时直接走本入口，不先调用 `+resolve-base`；AITable 上下文中的 Base 名称不得路由到 `dws aisearch person` | +| 新建 Base 与整套表字段 | `dws aitable +base-bootstrap --name <名称> --tables '[{"name":"<表名>","fields":[{"fieldName":"<字段名>","type":"text"}]}]'` | 表对象键必须是 `name`，不是 `tableName`；字段使用 `fieldName/type/config`；参数已足够时直接执行，不读 Reference 或 Help | +| 已有 Base 新建一张表与字段 | `dws aitable +table-bootstrap --base-id --name <表名> --fields ''` | 字段使用 `fieldName/type/config`；自动按 15 个字段分片并读回验证 | +| 读取字段目录或完整配置 | `dws aitable field list --base-id --table-id ` / `dws aitable +field-get --base-id --table-id ` | 只需 fieldId/name/type 用 `field list`；需要 config 用 `+field-get`；不存在 `+field-list` 或 `+list-fields` | +| 查询、筛选、排序或字段投影 | `dws aitable +record-query --base-id --table-id [--record-ids ] [--field-ids ] [--filters ] [--sort ] [--query <关键词>]` | 用户要求“只返回/仅查看”指定字段时必须传对应 `--field-ids`，不能只在最终文本删列；明确要求全量时改用原子 `record query --all --page-limit ` | +| 查询一条记录的变更历史 | `dws aitable +record-history-list --base-id --table-id --record-id ` | 已知 recordId 时直接执行；不要调用 Help、产品 Catalog 或全量 Schema 寻找 history 命令 | | 新增单条或批量记录 | `dws aitable record create --base-id --table-id --records ` | 当前无 `+record-create`；写前取字段定义，写后按新 ID 回读 | | 更新已知 recordId | `dws aitable +record-update --base-id --table-id --records ` | 自动分片并读回；只传需修改字段 | | 按业务唯一键同步 | `dws aitable +record-upsert-by-key --base-id --table-id --key-field-id --key-value <值> --cells ` | 0 条创建、1 条更新、多条停止；非字符串键改用 `--key-value-json` | @@ -53,27 +55,36 @@ metadata: | 删除整个 Base | `dws aitable +base-delete --base-id ` | 先通过只读命令确认真实 ID；按 Runtime confirmation 执行，不用 Drive 删除同名节点 | | 删除字段 | `dws aitable +field-delete --base-id --table-id --field-id ` | 先读取字段目录并确认非主字段；按 Runtime confirmation 执行 | | 查询/创建记录主键文档 | `dws aitable +record-primary-doc-get|+record-primary-doc-create ...` | create 必须传 primaryDoc 类型的 `--field-id`；正文操作切到 Doc | -| 创建 View / Dashboard / Chart 或导入文件 | 对应 leaf / `+import-*` | 高频准确 flags 见唯一执行 Reference；已有参数直接执行，不调用 Help | +| 生成记录分享链接并发送给联系人 | `dws aitable +record-share-links --base --table --record-ids ` → `dws chat +dm --to <姓名> --text <完整链接文本>` | AITable 只生成链接；用户要求“发送”时必须加载 `dingtalk-chat` 并对每位收件人完成真实发送，不能停在联系人解析 | +| 创建 View / Dashboard / Chart 或导入文件 | 对应 leaf / `+import-*` | 根 Skill 参数足够则直接执行；复杂配置最多读取一个对应操作 Reference，不读取通用索引 | | 调整视图列顺序 | `dws aitable view update visible-fields --base-id --table-id --view-id --field-ids <完整有序IDs>` | 先读取字段和当前完整列数组，固定主字段在首位，写后回读精确校验 | | 创建/修改图表前取配置 | `dws aitable +chart-widgets-example` | 命令返回所有图表类型示例；已有合法 config 时直接 create/update | | Base 内 Section/节点移动 | `dws aitable +section-*` | Table/Dashboard/Section 是 Base 内 nsheet 节点，不是独立 Drive 节点 | +### 常用 leaf 直达 + +参数已知时直接执行，不探测 Help/Catalog：Base 查看/改名用 `+base-get` / `+base-update`；模板搜索用 `+template-search`，再把真实 templateId 交给 `base create --template-id`；Table 查看/更新用 `+table-get` / `+table-update`；视图创建/复制用 `view create` / `+view-duplicate`；仪表盘创建/更新/读回用 `dashboard create` / `+dashboard-update` / `+dashboard-get`；表单分享用 `+form-share-update` / `+form-share-get`；查看自动化用 `+workflow-list`。 + ### 低频入口 字段配置用 `+field-*`；删记录用 `+record-delete`；附件用 `+attachment-*`。批量分享记录用 `+record-share-links --base --table --record-ids `。其余能力使用同名前缀 leaf。 ## 当前最短路径 -- 已有 ID 直接使用；URL 只解析一次；名称用 `+resolve-base` / `+resolve-table` 唯一解析。filters/sort 缺 fieldId 时才读取字段目录。 -- 高频 Base/Table/Field/View/Dashboard/Chart/Import 先读一次 [执行 Reference](references/aitable.md)，其中已有准确 flags；不要再调用 Help。 +- 已有 ID 直接使用；URL 只解析一次；“唯一定位并操作”用 `+resolve-base` / `+resolve-table`，“搜索候选/存在性检查”直接用 `+base-search`，两条路径不要串行探测。filters/sort 缺 fieldId 时才读取字段目录。 +- Golden Route 已给出准确命令和参数时直接执行；不预读或默认读取通用 `references/aitable.md`。只有操作参数、JSON 结构或恢复语义确实缺失时，才读取下方一个精确操作 Reference。 - Shortcut 已含分片或验证时不重复拆步；已有 Base 新建完整表结构直接用 `+table-bootstrap`。 -- 预计不超过 5 条命令的任务直接执行，不创建 TodoWrite/任务计划；复杂任务也只保留必要检查点。 +- 单产品线性任务直接执行，不创建 TodoWrite；只有跨产品或多个独立分支的长任务才建计划，并且只在阶段切换时更新，不在每条 CLI 后刷新状态。 +- 用户要求资源名带当前时间戳时只取一次并在 Base、Table、Dashboard 等名称中复用同一值；不要为每个资源分别取时间。 +- JSON 已返回所需字段时立即复用；不得为寻找同一字段改用 `--verbose`、`raw`、`pretty` 重复请求。 ## 记录输入与结果 - `cells` key 用当前 fieldId；大 JSON 用相对 `--records-file`。filters 顶层为 `and|or`，sort 使用 `direction`；复杂条件读 [filter-sort](references/aitable/aitable-filter-sort.md)。 +- 建表字段类型使用真实枚举：单选为 `singleSelect`；人民币货币字段使用 `type:"currency"` 和 `config:{"currencyType":"CNY","formatter":"FLOAT_2"}`，不要猜 `select` 或 `config.symbol`。 +- 用户限定返回字段时，先复用当前字段目录中的真实 fieldId，最终 `+record-query` 必须带 `--field-ids `；工具层投影是业务要求和 token 控制的一部分，不能用最终答复二次过滤替代。 - 按真实字段类型写值，只读字段不得写入。 -- 新建从 `data.newRecordIds[]` 取 ID，再用 `+record-query --record-ids` 回读。 +- 新建从 `data.newRecordIds[]` 取 ID，再用 `+record-query --record-ids` 回读；若用户同时限定列，回读命令一并传 `--field-ids`。 - 批量结果检查 completed/failed、verification、checkpoint；`partial_success` 不是完成。全量查询使用原子 `record query --all` 并检查 `hasMore`；只有 `hasMore=false`，或按指定 ID 全命中时，才声称结果完整。 - 写入效果未知时回读，不重放成功批次。 @@ -83,11 +94,10 @@ metadata: ## 按需加载 -Golden Route 参数足够时不读 reference；否则最多读取一个： +每个 Case 最多读取一个操作 Reference。Golden Route 参数足够时读取零个并直接执行；一旦读取了一个 Reference，本 Case 不再读取第二个 Reference、通用 `aitable.md`、产品级 Catalog 或 Help。 | 触发条件 | Reference | |---|---| -| 高频 Golden Route 的准确 flags、JSON 形状与错误恢复 | [执行 Reference](references/aitable.md) | | 记录 CRUD、字段值格式 | [record-ops](references/aitable-record-ops.md) | | 记录主键文档 | [primary-doc](references/aitable/aitable-primary-doc.md) | | filters/sort/date 操作符 | [filter-sort](references/aitable/aitable-filter-sort.md) | @@ -99,13 +109,13 @@ Golden Route 参数足够时不读 reference；否则最多读取一个： | 附件、表单、工作流 | 读取 `references/aitable/` 下对应的一个精确文件 | | 产品边界不明确 | [intent-guide](references/intent-guide.md) | -不连读 reference；低频能力按意图加载。 +通用 `references/aitable.md` 仅保留为兼容索引，不是默认入口；正常 Case 不预读。低频能力按意图选择一个最精确的 Reference，禁止连读。 ## 错误最短路径 1. 零/多候选、字段歧义或分页不完整：停止并返回证据；需要后续页时只透传真实 `nextCursor`。 2. 类型错误只复核目标字段，不删字段或丢输入；`partial_success` 从 checkpoint 续跑，未知写入先回读。 -3. 错误包含 `actions` / `available_flags` 时只执行其中的 `next_command`；`retryable=false` 时停止，不换猜测 ID 或相似 flag 试参。 +3. 错误包含 `actions` / `available_flags` 时只执行其中的 `next_command`；同一操作最多做一次有证据的参数修正。`retryable=false` 或目标 ID 类型不符时停止，不把 Drive/Wiki/Space/子节点 ID 轮流代入试错。 ## 跨产品边界 diff --git a/skills/multi/dingtalk-aitable/references/aitable-record-ops.md b/skills/multi/dingtalk-aitable/references/aitable-record-ops.md index 6e32ce50..d4a257f7 100644 --- a/skills/multi/dingtalk-aitable/references/aitable-record-ops.md +++ b/skills/multi/dingtalk-aitable/references/aitable-record-ops.md @@ -6,13 +6,15 @@ ```bash dws aitable +record-query --base-id --table-id --record-ids +dws aitable +record-query --base-id --table-id --record-ids --field-ids dws aitable +record-query --base-id --table-id --query "关键词" --limit 100 dws aitable +record-query --base-id --table-id --filters '' --sort '' dws aitable record query --base-id --table-id --filters '' --all --page-limit 50 ``` - `record-ids` 用于稳定 ID 精确读取；`query` 用于全文搜索；复杂条件用 `filters`。 -- filters 使用 `{"operator":"and|or","operands":[...]}`，字段引用使用 fieldId；完整操作符只读 [filter-sort](aitable/aitable-filter-sort.md)。 +- 用户要求“只返回/仅查看”指定列时，查询必须在工具层传 `--field-ids `。不要先拉取全部字段再只在最终答复中删列；字段投影既是结果契约，也是降低响应 token 的手段。 +- filters 使用 `{"operator":"and|or","operands":[...]}`，字段引用使用 fieldId。若 Case 明确需要复杂操作符，应一开始把 [filter-sort](aitable/aitable-filter-sort.md) 选为唯一 Reference，而不是先读本文件后继续加载。 - `+record-query` 必须传真实 `base-id` 和 `table-id`。URL 先用 `+url-resolve`；名称先用 `+resolve-base` / `+resolve-table` 唯一解析，禁止自动选第一项。 - 单页 `limit` 为 1-100。返回 `data.records`、`data.hasMore`，存在后续页时还会返回 `data.nextCursor`；把该值原样传给下一次 `--cursor`。 - `+record-query` 不提供 `--all`；明确要求全量时改用原子 `record query --all --page-limit `。达到页上限后仍有 `hasMore=true` 代表截断，应从返回 cursor 续跑；只有 `hasMore=false`，或按 `record-ids` 查询且所有请求 ID 均已返回时，才能声称结果完整。 @@ -26,7 +28,7 @@ dws aitable record create --base-id --table-id \ --records '[{"cells":{"fldText":"内容"}}]' --format json ``` -长 JSON 写到 cwd 内相对文件后使用 `--records-file ./records.json`。从真实返回的 `data.newRecordIds[]` 取 recordId，再用 `+record-query --record-ids` 回读。不要从输入顺序、名称或行号推断 ID。 +长 JSON 写到 cwd 内相对文件后使用 `--records-file ./records.json`。从真实返回的 `data.newRecordIds[]` 取 recordId，再用 `+record-query --record-ids` 回读；用户限定返回列时同时传 `--field-ids`。不要从输入顺序、名称或行号推断 ID。 ## 更新、同步与批量修改 @@ -39,6 +41,8 @@ dws aitable +record-update --base-id --table-id \ `+record-update` 自动按 100 条分片并逐批回读；该 shortcut 只接受 `--records`。超长文件输入需要改用原子 `record update --records-file`，不要给 shortcut 猜造 flag。 +单选、多选等字段的写入值可能是名称字符串，读回则是 `{id,name}` 或对象数组。若 shortcut 因原始类型不同返回 commit-unknown/read-back mismatch，禁止重放更新；只按返回的 recordId 做一次 `+record-query`，把单选按 `name`、多选按名称集合归一化比较。归一化后与目标一致时，按“独立读回已确认写入”报告，并保留 shortcut 的误报信息供排障。 + 按业务唯一键同步使用 `+record-upsert-by-key`：0 条创建、1 条更新、多条冲突停止。按条件批改使用 `+record-bulk-patch`，必须提供 filters/query/record-ids 中至少一种选择条件，或显式 `--all`，并设置合理 `--max-matches`。 ## 删除 @@ -66,8 +70,9 @@ dws aitable +record-delete --base-id --table-id --record-ids ## 历史、分享与主键文档 -- 记录历史：`+record-history-list` -- 记录分享：`+record-share-links` / `+record-share-url` +- 记录历史：`dws aitable +record-history-list --base-id --table-id --record-id `。已有真实 recordId 直接执行，不扫描 Help 或产品 Catalog。 +- 批量记录分享：`dws aitable +record-share-links --base --table --record-ids `；单条也可用 `+record-share-url`。 +- 用户要求把分享链接“发给”联系人时，AITable 的职责在链接生成后结束；随后加载 `dingtalk-chat`，用 `dws chat +dm --to <姓名> --text <包含全部链接的文本>` 对每位收件人分别发送并检查真实回执。只解析联系人或只生成 URL 都不算完成。 - 主键文档：`+record-primary-doc-get` / `+record-primary-doc-create` 创建主键文档必须显式传 primaryDoc 类型的 `--field-id`；字段类型不明时先读取目标字段。正文读写切到 Doc；这里仅管理记录与文档关联。 diff --git a/skills/multi/dingtalk-aitable/references/aitable.md b/skills/multi/dingtalk-aitable/references/aitable.md index dc2604cf..eef2adcc 100644 --- a/skills/multi/dingtalk-aitable/references/aitable.md +++ b/skills/multi/dingtalk-aitable/references/aitable.md @@ -1,6 +1,6 @@ -# AI 表格执行 Reference +# AI 表格执行 Reference（兼容索引，非默认入口） -根 Skill 只负责选路；高频命令的准确 flags、JSON 形状与失败恢复集中在本文件。命中下列路径后直接执行，不再调用 `--help`，也不加载产品级 Catalog。 +根 Skill 已包含高频 Golden Route 的准确参数，参数足够时直接执行，不读取本文件。本文件仅作兼容索引：只有根 Skill 与精确操作 Reference 都无法覆盖时，才可把它作为该 Case 唯一读取的 Reference；读取后不再加载第二个 Reference、`--help` 或产品级 Catalog。 ## 高频 Golden Route（准确 flags） @@ -32,6 +32,7 @@ dws aitable chart create --base-id --dashboard-id --con # 查询记录；选择器按意图传一个，不猜 flag dws aitable +record-query --base-id --table-id dws aitable +record-query --base-id --table-id --record-ids +dws aitable +record-query --base-id --table-id --record-ids --field-ids dws aitable +record-query --base-id --table-id --filters '' dws aitable +record-query --base-id --table-id --query "关键词" @@ -65,12 +66,13 @@ dws aitable +import-data --import-id --table-id |---|---|---| | AI 表格 URL | `dws aitable +url-resolve --url ` | 解析 URL 中已有的 baseId/tableId/viewId/recordId；不做远端名称搜索 | | 已知 Base/Table ID | 直接传给最终命令 | 不重复解析 | -| Base 精确名称或关键词 | `dws aitable +resolve-base --name <名称>` | 默认精确匹配；明确需要模糊匹配时加 `--fuzzy`，零/多候选均停止 | +| Base 精确名称，且要唯一定位后操作 | `dws aitable +resolve-base --name <名称>` | 默认精确匹配；明确需要模糊匹配时加 `--fuzzy`，零/多候选均停止 | +| 搜索 Base 候选、关键词查找或存在性检查 | `dws aitable +base-search --query <关键词>` | 直接检查返回候选，不先执行 `+resolve-base`；对象明确为 Base 时不得改走人员搜索 | | Base ID + Table 名称 | `dws aitable +resolve-table --base --name ` | 默认精确匹配；明确需要模糊匹配时加 `--fuzzy` | | Base ID，只需目录 | `dws aitable +list-tables --base ` | 只投影 tableId/tableName，不额外读取字段 | | 需要字段或视图目录 | `dws aitable +field-get ...` / `dws aitable +view-get ...` | 只读取当前任务需要的目标范围 | -`+record-query` 只接受真实 `base-id` / `table-id`，因此 URL 或名称须先按上表解析。`+base-list` 只表示最近访问，不是组织内全量 Base；`+base-search --query ` 是单次搜索。名称匹配零命中或多候选时停止，不选第一项。 +`+record-query` 只接受真实 `base-id` / `table-id`，因此 URL 或名称须先按上表解析。`+base-list` 只表示最近访问，不是组织内全量 Base；`+base-search --query ` 是单次搜索。唯一操作目标零命中或多候选时停止，不选第一项；“搜索候选/如果没有就创建”不要再串行调用 resolver 和 search。 ## 低频命令族 diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md index 3396a90e..cfb3f558 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md @@ -12,6 +12,16 @@ dws aitable dashboard get --base-id --dashboard-id --fo dws aitable chart get --base-id --dashboard-id --chart-id --format json ``` +只按名称创建、改名并确认时，不需要读取配置示例或 Help： + +```bash +dws aitable dashboard create --base-id --name <名称> --format json +dws aitable +dashboard-update --base-id --dashboard-id --name <新名称> --format json +dws aitable +dashboard-get --base-id --dashboard-id --format json +``` + +部分服务端更新回执可能仍回显更新前名称；只做一次 `+dashboard-get` 读回，以该后续权威读回为最终状态。读回已是目标名称时判定更新完成，不重放写操作，也不因旧回执继续探测 Help。 + ## 要点 - `dashboard get` 返回的 `charts[].chartId` 可直接给 `chart get` 使用 diff --git a/skills/multi/dingtalk-aitable/references/aitable/aitable-form.md b/skills/multi/dingtalk-aitable/references/aitable/aitable-form.md index 2b126d8f..e454c1fa 100644 --- a/skills/multi/dingtalk-aitable/references/aitable/aitable-form.md +++ b/skills/multi/dingtalk-aitable/references/aitable/aitable-form.md @@ -33,6 +33,16 @@ dws aitable form field list --base-id BASE_ID --table-id TABLE_ID --view-id VIEW dws aitable form share get --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json ``` +开启并取得可发送链接的最短闭环使用 canonical shortcut： + +```bash +dws aitable form create --base-id BASE_ID --table-id TABLE_ID --name "表单名" --format json +dws aitable +form-share-update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --enabled true --format json +dws aitable +form-share-get --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json +``` + +从最后一次返回直接读取 `data.shareFormUuid`，分享地址为 `https://alidocs.dingtalk.com/i/form/{shareFormUuid}`。字段已存在时不要再调用 Help、Catalog、`form get`，也不要换 `--verbose`、`raw`、`pretty` 重复请求。用户还要求发送时，把该完整 URL 交给 Chat 的发送命令并检查真实发送回执。 + ## 要点 - **创建表单**有两种等价方式： diff --git a/skills/multi/dingtalk-aitable/references/intent-guide.md b/skills/multi/dingtalk-aitable/references/intent-guide.md index da159a00..8ae3da9d 100644 --- a/skills/multi/dingtalk-aitable/references/intent-guide.md +++ b/skills/multi/dingtalk-aitable/references/intent-guide.md @@ -3,6 +3,7 @@ | 用户表达 | 归属 | 理由 | |---|---|---| | AI 表格、多维表、Base、Table、字段、记录、视图、表单、仪表盘、自动化 | AITable | 操作 AITable 的业务数据与配置 | +| 搜索 Base 候选、按关键词找 Base、检查某 Base 是否存在 | AITable | 直接使用 `+base-search --query`；即使关键词像人名，只要对象是 Base，也不得改走 `aisearch person` | | 表格链接，需要读取记录 | AITable | 先用 `+url-resolve` 取稳定 ID，再用 `+record-query` | | 只有 Base/Table 名称，需要读取记录 | AITable | 先用 `+resolve-base` / `+resolve-table` 唯一解析，再查询记录 | | 只复制 Base 结构、删除整个 Base | AITable | 复制到已知文档文件夹用 `+base-copy --target-folder-id ... --only-struct`；删除用真实 baseId。不要 Drive 完整复制后逐表删数据 | From 75f08da1973d113f39046dcda3d6130289985bb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Tue, 18 Aug 2026 22:10:23 +0800 Subject: [PATCH 232/250] feat(calendar): expand parameter alias normalization --- internal/app/param_alias_e2e_test.go | 68 ++- .../param_alias_payload_equivalence_test.go | 106 ++++ internal/cli/param_aliases_generated.go | 481 ++++++++++++++++++ internal/cli/param_concepts.json | 165 +++++- 4 files changed, 810 insertions(+), 10 deletions(-) diff --git a/internal/app/param_alias_e2e_test.go b/internal/app/param_alias_e2e_test.go index fed2527b..cca79f8e 100644 --- a/internal/app/param_alias_e2e_test.go +++ b/internal/app/param_alias_e2e_test.go @@ -51,7 +51,38 @@ func (c *paramAliasCaptureCaller) CallTool(_ context.Context, server, tool strin func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string { switch tool { case "list_calendar_events": - return `{"result":{"events":[]}}` + return `{"success":true,"result":{"events":[],"hasMore":false,"nextCursor":""}}` + case "get_calendar_detail": + return c.paramAliasCalendarDetailResponse() + case "get_calendar_participants": + return `{"success":true,"result":{"participants":[{"userId":"fixture-user","displayName":"Fixture User"},{"userId":"user-2","displayName":"User Two"}]}}` + case "search_calendar": + return `{"success":true,"result":{"calendars":[]}}` + case "search_rooms": + return `{"success":true,"result":{"rooms":[]}}` + case "query_available_meeting_room": + return `{"success":true,"result":{"rooms":[],"hasMore":false}}` + case "list_meeting_room_groups": + return `{"success":true,"result":{"groups":[]}}` + case "query_busy_status": + return `{"success":true,"result":[]}` + case "list_suggested_event_times": + return `{"success":true,"result":{"recommendEventTimes":[]}}` + case "create_calendar_event": + return `{"success":true,"result":{"eventId":"event-1"}}` + case "update_calendar_event", "delete_calendar_event", "add_calendar_participant", "remove_calendar_participant": + return `{"success":true}` + case "respond": + status := "accepted" + if call := c.lastParamAliasCall(); call != nil { + if value, ok := call.args["responseStatus"].(string); ok && value != "" { + status = value + } + } + encoded, _ := json.Marshal(map[string]any{"success": true, "result": map[string]any{"responseStatus": status}}) + return string(encoded) + case "get_current_user_profile": + return `{"success":true,"result":{"userId":"user-1","name":"Fixture Current User"}}` case "query_records": return `{"success":true,"status":"success","error":{},"data":{}}` case "search_mail_users": @@ -127,6 +158,41 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string } } +func (c *paramAliasCaptureCaller) lastParamAliasCall() *paramAliasToolCall { + if len(c.calls) == 0 { + return nil + } + return &c.calls[len(c.calls)-1] +} + +func (c *paramAliasCaptureCaller) paramAliasCalendarDetailResponse() string { + event := map[string]any{ + "eventId": "event-1", + "summary": "Fixture Meeting", + "description": "fixture description", + "startDateTime": "2026-03-10T09:00:00+08:00", + "endDateTime": "2026-03-10T10:00:00+08:00", + } + for _, call := range c.calls { + switch call.tool { + case "create_calendar_event", "update_calendar_event": + for _, key := range []string{"eventId", "summary", "description", "startDateTime", "endDateTime", "timeZone", "location", "freeBusy"} { + if value, ok := call.args[key]; ok { + event[key] = value + } + } + case "respond": + if value, ok := call.args["responseStatus"]; ok { + event["responseStatus"] = value + } + case "delete_calendar_event": + event["status"] = "cancelled" + } + } + encoded, _ := json.Marshal(map[string]any{"success": true, "result": event}) + return string(encoded) +} + func (*paramAliasCaptureCaller) Format() string { return "json" } func (*paramAliasCaptureCaller) DryRun() bool { return false } func (*paramAliasCaptureCaller) Fields() string { return "" } diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 6d83f718..cfe5224c 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -46,7 +46,37 @@ var paramAliasCompleteCommands = map[string][]string{ "aitable workflow run": {"aitable", "workflow", "run", "--base-id", "base-1", "--workflow-id", "workflow-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"}, "attendance check result": {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"}, "attendance +check-result": {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"}, + "calendar +agenda": {"calendar", "+agenda", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, + "calendar +attendee-list": {"calendar", "+attendee-list", "--event", "event-1", "--calendar-id", "primary"}, + "calendar +book": {"calendar", "+book", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--with", "Fixture User", "--yes"}, + "calendar +book-search": {"calendar", "+book-search", "--query", "fixture"}, + "calendar +cancel-event": {"calendar", "+cancel-event", "--event", "event-1", "--yes"}, + "calendar +conflicts": {"calendar", "+conflicts", "--in-days", "1"}, + "calendar +create": {"calendar", "+create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--desc", "fixture description", "--attendees", "user-1,user-2", "--rooms", "room-1,room-2", "--calendar-id", "primary", "--yes"}, + "calendar +free": {"calendar", "+free", "--who", "Fixture User", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, + "calendar +free-slots": {"calendar", "+free-slots", "--from", "9", "--to", "18", "--in-days", "1"}, + "calendar +freebusy": {"calendar", "+freebusy", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, + "calendar +get": {"calendar", "+get", "--event", "event-1", "--calendar-id", "primary"}, + "calendar +invite": {"calendar", "+invite", "--event", "event-1", "--with", "Fixture User", "--yes"}, + "calendar +my-free": {"calendar", "+my-free", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, + "calendar +reschedule": {"calendar", "+reschedule", "--event", "event-1", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--yes"}, + "calendar +room-find": {"calendar", "+room-find", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--room-name", "Fixture Room", "--group-id", "group-1", "--page", "1", "--limit", "7"}, + "calendar +room-groups": {"calendar", "+room-groups", "--page", "1", "--limit", "7"}, + "calendar +room-search": {"calendar", "+room-search", "--room-name", "Fixture Room"}, + "calendar +rsvp": {"calendar", "+rsvp", "--event", "event-1", "--status", "accept", "--calendar-id", "primary", "--yes"}, + "calendar +search-event": {"calendar", "+search-event", "--query", "fixture", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, + "calendar +suggest-time": {"calendar", "+suggest-time", "--with", "Fixture User", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, + "calendar +suggestion": {"calendar", "+suggestion", "--users", "user-1,user-2", "--duration", "30", "--timezone", "Asia/Shanghai"}, + "calendar +update": {"calendar", "+update", "--event", "event-1", "--title", "Fixture Updated Meeting", "--desc", "fixture updated description", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--add-attendees", "user-2", "--remove-attendees", "user-1", "--yes"}, + "calendar busy search": {"calendar", "busy", "search", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, + "calendar event create": {"calendar", "event", "create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--remind-minutes", "15", "--timezone", "Asia/Shanghai", "--rooms", "room-1,room-2", "--yes"}, "calendar event list": {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, + "calendar event respond": {"calendar", "event", "respond", "--id", "event-1", "--status", "accepted", "--yes"}, + "calendar event suggest": {"calendar", "event", "suggest", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"}, + "calendar event update": {"calendar", "event", "update", "--id", "event-1", "--timezone", "Asia/Shanghai", "--yes"}, + "calendar room add": {"calendar", "room", "add", "--event", "event-1", "--rooms", "room-1,room-2", "--yes"}, + "calendar room delete": {"calendar", "room", "delete", "--event", "event-1", "--rooms", "room-1,room-2", "--yes"}, + "calendar room search": {"calendar", "room", "search", "--room-name", "Fixture Room", "--group-id", "group-1", "--start", "2027-03-10T09:00:00+08:00", "--end", "2027-03-10T10:00:00+08:00", "--page", "1", "--limit", "7"}, "chat +chat-messages": {"chat", "+chat-messages", "--group", "fixture-conversation"}, "chat +chat-add-bot": {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"}, "chat +chat-audit-join": {"chat", "+chat-audit-join", "--group", "fixture-conversation", "--record-id", "7", "--applicant", "user-1", "--inviter", "user-2", "--status", "AuditApprove", "--yes"}, @@ -532,6 +562,82 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("aitable workflow run", "table"): true, // Table ID concept alias on a confirmed write paramAliasPayloadCaseKey("attendance check result", "user-ids"): true, // list-valued concept alias paramAliasPayloadCaseKey("calendar event list", "date"): true, // time concept alias + paramAliasPayloadCaseKey("calendar +agenda", "from"): true, + paramAliasPayloadCaseKey("calendar +agenda", "to"): true, + paramAliasPayloadCaseKey("calendar +agenda", "max-results"): true, + paramAliasPayloadCaseKey("calendar +agenda", "next-cursor"): true, + paramAliasPayloadCaseKey("calendar +agenda", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +attendee-list", "event-id"): true, + paramAliasPayloadCaseKey("calendar +attendee-list", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +book", "summary"): true, + paramAliasPayloadCaseKey("calendar +book", "attendee-names"): true, + paramAliasPayloadCaseKey("calendar +book-search", "keyword"): true, + paramAliasPayloadCaseKey("calendar +book-search", "search"): true, + paramAliasPayloadCaseKey("calendar +book-search", "name"): true, + paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"): true, + paramAliasPayloadCaseKey("calendar +cancel-event", "id"): true, + paramAliasPayloadCaseKey("calendar +free", "name"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "start-hour"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "end-hour"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "day-offset"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "room-ids"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "room-id"): true, + paramAliasPayloadCaseKey("calendar +my-free", "from"): true, + paramAliasPayloadCaseKey("calendar +my-free", "to"): true, + paramAliasPayloadCaseKey("calendar +invite", "id"): true, + paramAliasPayloadCaseKey("calendar +invite", "participant-names"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "id"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "from"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "to"): true, + paramAliasPayloadCaseKey("calendar +room-groups", "page-size"): true, + paramAliasPayloadCaseKey("calendar +room-groups", "page-index"): true, + paramAliasPayloadCaseKey("calendar +room-search", "query"): true, + paramAliasPayloadCaseKey("calendar +suggest-time", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar +suggest-time", "attendee-names"): true, + paramAliasPayloadCaseKey("calendar +conflicts", "day-offset"): true, + paramAliasPayloadCaseKey("calendar busy search", "room-id"): true, + paramAliasPayloadCaseKey("calendar event create", "reminder-minutes"): true, + paramAliasPayloadCaseKey("calendar event create", "tz"): true, + paramAliasPayloadCaseKey("calendar event create", "room-id"): true, + paramAliasPayloadCaseKey("calendar event respond", "response-status"): true, + paramAliasPayloadCaseKey("calendar event suggest", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar event update", "tz"): true, + paramAliasPayloadCaseKey("calendar room add", "room-id"): true, + paramAliasPayloadCaseKey("calendar room delete", "room-id"): true, + paramAliasPayloadCaseKey("calendar room search", "room-group-id"): true, + paramAliasPayloadCaseKey("calendar +create", "summary"): true, + paramAliasPayloadCaseKey("calendar +create", "description"): true, + paramAliasPayloadCaseKey("calendar +create", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +create", "room-ids"): true, + paramAliasPayloadCaseKey("calendar +create", "room-id"): true, + paramAliasPayloadCaseKey("calendar +create", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +create", "to"): true, + paramAliasPayloadCaseKey("calendar +create", "from"): true, + paramAliasPayloadCaseKey("calendar +get", "event-id"): true, + paramAliasPayloadCaseKey("calendar +get", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +room-find", "from"): true, + paramAliasPayloadCaseKey("calendar +room-find", "to"): true, + paramAliasPayloadCaseKey("calendar +room-find", "page-size"): true, + paramAliasPayloadCaseKey("calendar +room-find", "page-index"): true, + paramAliasPayloadCaseKey("calendar +room-find", "room-group-id"): true, + paramAliasPayloadCaseKey("calendar +room-find", "query"): true, + paramAliasPayloadCaseKey("calendar +rsvp", "event-id"): true, + paramAliasPayloadCaseKey("calendar +rsvp", "response-status"): true, + paramAliasPayloadCaseKey("calendar +search-event", "keyword"): true, + paramAliasPayloadCaseKey("calendar +search-event", "from"): true, + paramAliasPayloadCaseKey("calendar +search-event", "to"): true, + paramAliasPayloadCaseKey("calendar +search-event", "next-cursor"): true, + paramAliasPayloadCaseKey("calendar +search-event", "max-results"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "tz"): true, + paramAliasPayloadCaseKey("calendar +update", "event-id"): true, + paramAliasPayloadCaseKey("calendar +update", "from"): true, + paramAliasPayloadCaseKey("calendar +update", "summary"): true, + paramAliasPayloadCaseKey("calendar +update", "description"): true, + paramAliasPayloadCaseKey("calendar +update", "add-user-ids"): true, + paramAliasPayloadCaseKey("calendar +update", "remove-user-ids"): true, paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"): true, // scoped IM identifier alias paramAliasPayloadCaseKey("contact user profile get", "user-id"): true, // native compatibility flag paramAliasPayloadCaseKey("devdoc article search", "current-page"): true, // command override diff --git a/internal/cli/param_aliases_generated.go b/internal/cli/param_aliases_generated.go index ad82e6db..4b5b93c9 100644 --- a/internal/cli/param_aliases_generated.go +++ b/internal/cli/param_aliases_generated.go @@ -1773,6 +1773,439 @@ var generatedParamAliases = []ParamAliasEntry{ }, Blocked: []string{"at-user-ids", "staff-id", "uid", "user", "user-id", "userid"}, }, + { + CLIPath: "calendar +agenda", + Aliases: map[string]string{ + "begin": "start", + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-result": "limit", + "max-results": "limit", + "max-time": "end", + "min-time": "start", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "since": "start", + "size": "limit", + "start-date": "start", + "start-time": "start", + "take": "limit", + "time-max": "end", + "time-min": "start", + "to": "end", + "top": "limit", + }, + Blocked: []string{"acl-id", "count", "date", "event", "event-id", "id", "offset", "page", "room-id", "time"}, + }, + { + CLIPath: "calendar +attendee-list", + Aliases: map[string]string{ + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "calendar-event-id": "event", + "event-id": "event", + }, + Blocked: []string{"acl-id", "room-id"}, + Ambiguous: []string{"id"}, + }, + { + CLIPath: "calendar +book", + Aliases: map[string]string{ + "attendee-names": "with", + "begin": "start", + "end-time": "end", + "from": "start", + "names": "with", + "participant-names": "with", + "start-time": "start", + "subject": "title", + "summary": "title", + "to": "end", + }, + Blocked: []string{"attendees", "calendar-id", "calendar-name", "date", "end-date", "name", "open-dingtalk-ids", "participants", "room-id", "room-ids", "room-name", "rooms", "start-date", "time", "time-max", "time-min", "user", "user-id", "user-ids", "users"}, + }, + { + CLIPath: "calendar +book-search", + Aliases: map[string]string{ + "keyword": "query", + "keywords": "query", + "name": "query", + "q": "query", + "search": "query", + "search-word": "query", + }, + Blocked: []string{"subject", "text", "title"}, + }, + { + CLIPath: "calendar +cancel-event", + Aliases: map[string]string{ + "calendar-event-id": "event", + "event-id": "event", + "id": "event", + }, + Blocked: []string{"acl-id", "calendar-book-id", "calendar-id", "room-id"}, + }, + { + CLIPath: "calendar +conflicts", + Aliases: map[string]string{ + "day-offset": "in-days", + "days-from-today": "in-days", + }, + Blocked: []string{"days", "duration", "end", "from", "start", "to"}, + }, + { + CLIPath: "calendar +create", + Aliases: map[string]string{ + "attendee-ids": "attendees", + "begin": "start", + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "description": "desc", + "end-time": "end", + "freebusy": "free-busy", + "from": "start", + "room-id": "rooms", + "room-ids": "rooms", + "start-time": "start", + "subject": "title", + "summary": "title", + "time-zone": "timezone", + "to": "end", + "tz": "timezone", + "user-ids": "attendees", + "users": "attendees", + }, + Blocked: []string{"acl-id", "attendee-name", "attendee-names", "calendar-name", "config", "date", "end-date", "event", "event-id", "field-description", "group-id", "id", "locale", "name", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "rich-text-desc", "room", "room-name", "start-date", "time", "time-max", "time-min", "utc-offset", "who", "with"}, + }, + { + CLIPath: "calendar +free", + Aliases: map[string]string{ + "begin": "start", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-time": "end", + "min-time": "start", + "name": "who", + "person": "who", + "person-name": "who", + "since": "start", + "start-date": "start", + "start-time": "start", + "time-max": "end", + "time-min": "start", + "to": "end", + }, + Blocked: []string{"date", "time", "user", "user-id", "user-ids", "users", "with"}, + }, + { + CLIPath: "calendar +free-slots", + Aliases: map[string]string{ + "day-offset": "in-days", + "days-from-today": "in-days", + "end-hour": "to", + "start-hour": "from", + }, + Blocked: []string{"days", "duration", "end", "end-time", "start", "start-time", "time-max", "time-min"}, + }, + { + CLIPath: "calendar +freebusy", + Aliases: map[string]string{ + "begin": "start", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-time": "end", + "min-time": "start", + "room-id": "rooms", + "room-ids": "rooms", + "since": "start", + "start-date": "start", + "start-time": "start", + "time-max": "end", + "time-min": "start", + "to": "end", + "user-ids": "users", + }, + Blocked: []string{"at-user-ids", "attendee-names", "date", "group-id", "location", "name", "names", "participant-names", "room", "room-name", "staff-id", "time", "uid", "user", "user-id", "userid", "who", "with"}, + }, + { + CLIPath: "calendar +get", + Aliases: map[string]string{ + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "calendar-event-id": "event", + "event-id": "event", + }, + Blocked: []string{"acl-id", "room-id"}, + Ambiguous: []string{"id"}, + }, + { + CLIPath: "calendar +invite", + Aliases: map[string]string{ + "attendee-names": "with", + "calendar-event-id": "event", + "event-id": "event", + "id": "event", + "names": "with", + "participant-names": "with", + }, + Blocked: []string{"acl-id", "attendees", "calendar-book-id", "calendar-id", "open-dingtalk-ids", "participants", "room-id", "user", "user-id", "user-ids", "users"}, + }, + { + CLIPath: "calendar +my-free", + Aliases: map[string]string{ + "begin": "start", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-time": "end", + "min-time": "start", + "since": "start", + "start-date": "start", + "start-time": "start", + "time-max": "end", + "time-min": "start", + "to": "end", + }, + Blocked: []string{"date", "time"}, + }, + { + CLIPath: "calendar +reschedule", + Aliases: map[string]string{ + "begin": "start", + "calendar-event-id": "event", + "end-time": "end", + "event-id": "event", + "from": "start", + "id": "event", + "start-time": "start", + "to": "end", + }, + Blocked: []string{"acl-id", "calendar-book-id", "calendar-id", "date", "end-date", "room-id", "start-date", "time", "time-max", "time-min"}, + }, + { + CLIPath: "calendar +room-find", + Aliases: map[string]string{ + "begin": "start", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "group": "group-id", + "max-result": "limit", + "max-results": "limit", + "max-time": "end", + "min-time": "start", + "name": "room-name", + "page-index": "page", + "page-size": "limit", + "per-page": "limit", + "query": "room-name", + "room-group-id": "group-id", + "since": "start", + "size": "limit", + "start-date": "start", + "start-time": "start", + "take": "limit", + "time-max": "end", + "time-min": "start", + "to": "end", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "date", "location", "next-cursor", "page-token", "room", "room-id", "room-ids", "rooms", "time"}, + }, + { + CLIPath: "calendar +room-groups", + Aliases: map[string]string{ + "max-result": "limit", + "max-results": "limit", + "page-index": "page", + "page-size": "limit", + "per-page": "limit", + "size": "limit", + "take": "limit", + "top": "limit", + }, + Blocked: []string{"count", "cursor", "page-token"}, + }, + { + CLIPath: "calendar +room-search", + Aliases: map[string]string{ + "name": "room-name", + "query": "room-name", + }, + Blocked: []string{"group-id", "location", "room", "room-id", "room-ids", "rooms"}, + }, + { + CLIPath: "calendar +rsvp", + Aliases: map[string]string{ + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "calendar-event-id": "event", + "event-id": "event", + "response": "status", + "response-status": "status", + }, + Blocked: []string{"acl-id", "availability", "done", "free-busy", "room-id", "state"}, + Ambiguous: []string{"id"}, + }, + { + CLIPath: "calendar +search-event", + Aliases: map[string]string{ + "begin": "start", + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "keyword": "query", + "keywords": "query", + "max-result": "limit", + "max-results": "limit", + "max-time": "end", + "min-time": "start", + "next-cursor": "cursor", + "next-page-token": "cursor", + "next-token": "cursor", + "page-size": "limit", + "page-token": "cursor", + "per-page": "limit", + "q": "query", + "search": "query", + "search-word": "query", + "since": "start", + "size": "limit", + "start-date": "start", + "start-time": "start", + "take": "limit", + "time-max": "end", + "time-min": "start", + "to": "end", + "top": "limit", + }, + Blocked: []string{"acl-id", "count", "date", "event", "event-id", "id", "name", "offset", "page", "page-index", "room-id", "subject", "text", "time", "title"}, + }, + { + CLIPath: "calendar +suggest-time", + Aliases: map[string]string{ + "attendee-names": "with", + "begin": "start", + "duration-minutes": "duration", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-time": "end", + "meeting-duration-minutes": "duration", + "min-time": "start", + "names": "with", + "participant-names": "with", + "since": "start", + "start-date": "start", + "start-time": "start", + "time-max": "end", + "time-min": "start", + "to": "end", + }, + Blocked: []string{"attendees", "date", "open-dingtalk-ids", "participants", "remind-minutes", "time", "user", "user-id", "user-ids", "users"}, + }, + { + CLIPath: "calendar +suggestion", + Aliases: map[string]string{ + "begin": "start", + "duration-minutes": "duration", + "end-date": "end", + "end-time": "end", + "from": "start", + "from-date": "start", + "max-time": "end", + "meeting-duration-minutes": "duration", + "min-time": "start", + "since": "start", + "start-date": "start", + "start-time": "start", + "time-max": "end", + "time-min": "start", + "time-zone": "timezone", + "to": "end", + "tz": "timezone", + "user-ids": "users", + }, + Blocked: []string{"at-user-ids", "attendee-name", "attendee-names", "date", "locale", "name", "names", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "remind-minutes", "room-id", "room-ids", "room-name", "rooms", "staff-id", "time", "uid", "user", "user-id", "userid", "utc-offset", "who", "with"}, + }, + { + CLIPath: "calendar +update", + Aliases: map[string]string{ + "add-user-ids": "add-attendees", + "add-users": "add-attendees", + "begin": "start", + "calendar": "calendar-id", + "calendar-book-id": "calendar-id", + "calendar-event-id": "event", + "description": "desc", + "end-time": "end", + "event-id": "event", + "freebusy": "free-busy", + "from": "start", + "remove-user-ids": "remove-attendees", + "remove-users": "remove-attendees", + "start-time": "start", + "subject": "title", + "summary": "title", + "time-zone": "timezone", + "to": "end", + "tz": "timezone", + }, + Blocked: []string{"acl-id", "attendee-name", "attendee-names", "calendar-name", "config", "date", "end-date", "field-description", "group-id", "locale", "name", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "remind-minutes", "reminder-minutes", "rich-text-desc", "room-id", "room-ids", "room-name", "rooms", "start-date", "time", "time-max", "time-min", "utc-offset", "who", "with"}, + Ambiguous: []string{"attendees", "id", "user-ids", "users"}, + }, + { + CLIPath: "calendar acl delete", + Blocked: []string{"calendar-book-id", "calendar-id", "event", "event-id", "room-id", "user-id"}, + }, + { + CLIPath: "calendar attachment add", + Blocked: []string{"attachments", "file", "file-id", "file-ids"}, + }, + { + CLIPath: "calendar attendee add", + Blocked: []string{"attendee-name", "attendee-names", "open-dingtalk-ids", "participant-name", "participant-names", "who", "with"}, + }, + { + CLIPath: "calendar attendee delete", + Blocked: []string{"attendee-name", "attendee-names", "open-dingtalk-ids", "participant-name", "participant-names", "who", "with"}, + }, + { + CLIPath: "calendar busy search", + Aliases: map[string]string{ + "room-id": "rooms", + }, + Blocked: []string{"attendee-name", "attendee-names", "group-id", "location", "name", "names", "participant-names", "room", "room-name", "who", "with"}, + }, + { + CLIPath: "calendar event create", + Aliases: map[string]string{ + "reminder-minutes": "remind-minutes", + "reminder-offset-minutes": "remind-minutes", + "room-id": "rooms", + "time-zone": "timezone", + "tz": "timezone", + }, + Blocked: []string{"at", "attendee-name", "attendee-names", "due", "duration", "group-id", "locale", "offset", "participant-name", "participant-names", "remind-at", "reminder-time", "room", "room-name", "utc-offset", "who", "with"}, + }, { CLIPath: "calendar event list", Aliases: map[string]string{ @@ -1789,6 +2222,54 @@ var generatedParamAliases = []ParamAliasEntry{ }, Blocked: []string{"offset", "page", "time"}, }, + { + CLIPath: "calendar event respond", + Aliases: map[string]string{ + "response": "status", + "response-status": "status", + }, + Blocked: []string{"availability", "done", "free-busy", "state"}, + }, + { + CLIPath: "calendar event suggest", + Aliases: map[string]string{ + "duration-minutes": "duration", + "meeting-duration-minutes": "duration", + "time-zone": "timezone", + "tz": "timezone", + }, + Blocked: []string{"attendee-name", "attendee-names", "from", "locale", "name", "names", "offset", "open-dingtalk-ids", "participant-names", "remind-minutes", "to", "utc-offset", "who", "with"}, + }, + { + CLIPath: "calendar event update", + Aliases: map[string]string{ + "time-zone": "timezone", + "tz": "timezone", + }, + Blocked: []string{"attendees", "group-id", "locale", "offset", "participants", "remind-minutes", "reminder-minutes", "room-id", "room-ids", "room-name", "rooms", "utc-offset"}, + }, + { + CLIPath: "calendar room add", + Aliases: map[string]string{ + "room-id": "rooms", + }, + Blocked: []string{"group-id", "location", "room", "room-name"}, + }, + { + CLIPath: "calendar room delete", + Aliases: map[string]string{ + "room-id": "rooms", + }, + Blocked: []string{"group-id", "location", "room", "room-name"}, + }, + { + CLIPath: "calendar room search", + Aliases: map[string]string{ + "group": "group-id", + "room-group-id": "group-id", + }, + Blocked: []string{"location", "room", "room-id", "room-ids", "rooms"}, + }, { CLIPath: "chat +bot-find", Aliases: map[string]string{ diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 90570a9e..6aae2d0e 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -10,16 +10,16 @@ }, "concepts": { - "search_query": {"denotes":"search keyword string","canonical_hint":"query","members":["query","keyword","keywords","q","search-word"],"excludes":["name","subject","text","title"],"commands":["aitable +base-search","aitable +find-record","aitable +record-bulk-patch","aitable +record-query","aitable +template-search","aitable base search","aitable field search-options","aitable record list","aitable record query","aitable search","aitable template search","contact +dept-members","contact +resolve-dept","contact +search-user","doc +create-from-template","doc +find-doc","doc +search","doc +template-search","doc template search","drive +find-file","drive +search","drive +search-docs","drive search","mail +find-mail-user","mail user search","oa +search-forms","oa approval search-forms"],"risk":"green"}, - "pagination_size": {"denotes":"returned item count upper bound","canonical_hint":"limit","members":["limit","size","page-size","max-results","max-result","take","top","per-page"],"excludes":["count","page","cursor"],"commands":["aitable +base-list","aitable +record-history-list","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable +workflow-list","aitable base list","aitable field search-options","aitable list","aitable record history-list","aitable record list","aitable record query","aitable record query-empty","aitable template search","aitable workflow history","aitable workflow list","calendar event list","chat message list","devdoc article search","doc +comment-list","doc +find-doc","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +search-docs","drive +star-list","drive +version-history","drive list","drive list-spaces","drive permission list","drive recent","drive recycle list","drive search","drive star list","mail thread list","oa +list-executed"],"risk":"green"}, + "search_query": {"denotes":"search keyword string","canonical_hint":"query","members":["query","keyword","keywords","q","search-word"],"excludes":["name","subject","text","title"],"commands":["aitable +base-search","aitable +find-record","aitable +record-bulk-patch","aitable +record-query","aitable +template-search","aitable base search","aitable field search-options","aitable record list","aitable record query","aitable search","aitable template search","contact +dept-members","contact +resolve-dept","contact +search-user","doc +create-from-template","doc +find-doc","doc +search","doc +template-search","doc template search","drive +find-file","drive +search","drive +search-docs","drive search","mail +find-mail-user","mail user search","oa +search-forms","oa approval search-forms","calendar +book-search","calendar +search-event"],"risk":"green"}, + "pagination_size": {"denotes":"returned item count upper bound","canonical_hint":"limit","members":["limit","size","page-size","max-results","max-result","take","top","per-page"],"excludes":["count","page","cursor"],"commands":["aitable +base-list","aitable +record-history-list","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable +workflow-list","aitable base list","aitable field search-options","aitable list","aitable record history-list","aitable record list","aitable record query","aitable record query-empty","aitable template search","aitable workflow history","aitable workflow list","calendar event list","chat message list","devdoc article search","doc +comment-list","doc +find-doc","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +search-docs","drive +star-list","drive +version-history","drive list","drive list-spaces","drive permission list","drive recent","drive recycle list","drive search","drive star list","mail thread list","oa +list-executed","calendar +agenda","calendar +room-groups","calendar +room-find","calendar +search-event"],"risk":"green"}, "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"}, - "page_cursor": {"denotes":"pagination cursor/token","canonical_hint":"cursor","members":["cursor","next-cursor","page-token","next-token","next-page-token"],"excludes":["page","offset"],"commands":["aitable +base-list","aitable +base-search","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable base list","aitable base search","aitable list","aitable record list","aitable record query","aitable record query-empty","aitable search","aitable template search","calendar event list","doc +comment-list","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +star-list","drive +version-history","drive list","drive list-spaces","drive recent","drive recycle list","drive search","drive star list"],"risk":"green"}, + "page_cursor": {"denotes":"pagination cursor/token","canonical_hint":"cursor","members":["cursor","next-cursor","page-token","next-token","next-page-token"],"excludes":["page","offset"],"commands":["aitable +base-list","aitable +base-search","aitable +record-query","aitable +record-query-empty","aitable +template-search","aitable base list","aitable base search","aitable list","aitable record list","aitable record query","aitable record query-empty","aitable search","aitable template search","calendar event list","doc +comment-list","doc +list","doc +search","doc +template-list","doc +template-search","doc +version-list","doc comment list","doc template list","doc template search","doc version list","drive +list","drive +recent","drive +recycle-list","drive +search","drive +star-list","drive +version-history","drive list","drive list-spaces","drive recent","drive recycle list","drive search","drive star list","calendar +agenda","calendar +search-event"],"risk":"green"}, "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc +checkpoint-update", "doc +comment-create", "doc +comment-reply", "doc +comment-update", "doc +create", "doc +doc-append", "doc block insert", "doc block update", "doc comment create", "doc comment create-inline", "doc comment reply", "doc comment update", "doc create"], "risk": "green"}, - "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"}, - "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"}, + "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list", "calendar +agenda", "calendar +free", "calendar +freebusy", "calendar +my-free", "calendar +suggest-time", "calendar +room-find", "calendar +search-event", "calendar +suggestion"], "risk": "yellow"}, + "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list", "calendar +agenda", "calendar +free", "calendar +freebusy", "calendar +my-free", "calendar +suggest-time", "calendar +room-find", "calendar +search-event", "calendar +suggestion"], "risk": "yellow"}, "base_id": {"denotes":"multi-dimensional table Base id","canonical_hint":"base-id","members":["base","base-id","base-token"],"excludes":[],"commands":["aitable +advperm-disable","aitable +advperm-enable","aitable +attachment-put","aitable +attachment-remove","aitable +attachment-upload","aitable +base-copy","aitable +base-delete","aitable +base-get","aitable +base-get-primary-doc-id","aitable +base-schema-snapshot","aitable +base-update","aitable +chart-delete","aitable +chart-get","aitable +chart-share-get","aitable +chart-share-update","aitable +chart-update","aitable +dashboard-arrange","aitable +dashboard-delete","aitable +dashboard-get","aitable +dashboard-share-get","aitable +dashboard-share-update","aitable +dashboard-update","aitable +export-data","aitable +field-delete","aitable +field-get","aitable +field-update","aitable +find-record","aitable +form-delete","aitable +form-field-hide","aitable +form-field-list","aitable +form-field-update","aitable +form-list","aitable +form-share-get","aitable +form-share-update","aitable +form-update","aitable +import-upload","aitable +list-tables","aitable +record-bulk-patch","aitable +record-delete","aitable +record-history-list","aitable +record-primary-doc-create","aitable +record-primary-doc-get","aitable +record-query","aitable +record-query-empty","aitable +record-share-links","aitable +record-share-url","aitable +record-update","aitable +record-upsert","aitable +record-upsert-by-key","aitable +resolve-table","aitable +role-create","aitable +role-delete","aitable +role-get","aitable +role-list","aitable +role-update","aitable +section-create","aitable +section-delete","aitable +section-list-empty","aitable +section-list-nodes","aitable +section-move-node","aitable +section-rename","aitable +section-reorder","aitable +table-delete","aitable +table-get","aitable +table-update","aitable +view-delete","aitable +view-duplicate","aitable +view-get","aitable +view-get-frozen-cols","aitable +view-get-lock","aitable +view-get-row-height","aitable +view-lock","aitable +view-preset-apply","aitable +view-set-fill-color-rule","aitable +view-set-frozen-cols","aitable +view-set-row-height","aitable +view-update","aitable +workflow-deploy","aitable +workflow-disable","aitable +workflow-enable","aitable +workflow-get","aitable +workflow-list","aitable advperm disable","aitable advperm enable","aitable advperm role-create","aitable advperm role-delete","aitable advperm role-get","aitable advperm role-list","aitable advperm role-update","aitable attachment upload","aitable base copy","aitable base delete","aitable base get","aitable base get-primary-doc-id","aitable base update","aitable chart create","aitable chart delete","aitable chart get","aitable chart share get","aitable chart share update","aitable chart update","aitable dashboard arrange","aitable dashboard create","aitable dashboard delete","aitable dashboard get","aitable dashboard share get","aitable dashboard share update","aitable dashboard update","aitable export data","aitable field create","aitable field delete","aitable field get","aitable field list","aitable field search-options","aitable field update","aitable form create","aitable form delete","aitable form field hide","aitable form field list","aitable form field update","aitable form get","aitable form list","aitable form questions create","aitable form questions delete","aitable form share get","aitable form share update","aitable form update","aitable import upload","aitable info","aitable record batch-update","aitable record create","aitable record delete","aitable record get","aitable record history-list","aitable record primary-doc-create","aitable record primary-doc-get","aitable record query","aitable record query-empty","aitable record share-url","aitable record update","aitable record upsert","aitable section create","aitable section delete","aitable section list-empty","aitable section list-nodes","aitable section move-node","aitable section rename","aitable section reorder","aitable table create","aitable table delete","aitable table get","aitable table list","aitable table update","aitable view create","aitable view delete","aitable view duplicate","aitable view get aggregate","aitable view get card","aitable view get field-widths","aitable view get fill-color-rule","aitable view get filter","aitable view get frozen-cols","aitable view get group","aitable view get lock","aitable view get row-height","aitable view get sort","aitable view get timebar","aitable view get visible-fields","aitable view list","aitable view lock","aitable view update aggregate","aitable view update card","aitable view update field-widths","aitable view update fill-color-rule","aitable view update filter","aitable view update frozen-cols","aitable view update group","aitable view update name","aitable view update row-height","aitable view update sort","aitable view update timebar","aitable view update visible-fields","aitable workflow create","aitable workflow disable","aitable workflow enable","aitable workflow get","aitable workflow history","aitable workflow list","aitable workflow run","aitable workflow update"],"risk":"green"}, "table_id": {"denotes":"single AI Table data-table Table ID","canonical_hint":"table-id","members":["table","table-id"],"excludes":["table-ids","source-table-id","target-table-id","name"],"commands":["aitable +attachment-put","aitable +attachment-remove","aitable +base-get-primary-doc-id","aitable +export-data","aitable +field-delete","aitable +field-get","aitable +field-update","aitable +find-record","aitable +form-delete","aitable +form-field-hide","aitable +form-field-list","aitable +form-field-update","aitable +form-list","aitable +form-share-get","aitable +form-share-update","aitable +form-update","aitable +import-data","aitable +record-bulk-patch","aitable +record-delete","aitable +record-history-list","aitable +record-primary-doc-create","aitable +record-primary-doc-get","aitable +record-query","aitable +record-query-empty","aitable +record-share-links","aitable +record-share-url","aitable +record-update","aitable +record-upsert","aitable +record-upsert-by-key","aitable +table-delete","aitable +table-update","aitable +view-delete","aitable +view-duplicate","aitable +view-get","aitable +view-get-frozen-cols","aitable +view-get-lock","aitable +view-get-row-height","aitable +view-lock","aitable +view-preset-apply","aitable +view-set-fill-color-rule","aitable +view-set-frozen-cols","aitable +view-set-row-height","aitable +view-update","aitable base get-primary-doc-id","aitable export data","aitable field create","aitable field delete","aitable field get","aitable field list","aitable field search-options","aitable field update","aitable form create","aitable form delete","aitable form field hide","aitable form field list","aitable form field update","aitable form get","aitable form list","aitable form questions create","aitable form questions delete","aitable form share get","aitable form share update","aitable form update","aitable import data","aitable record batch-update","aitable record create","aitable record delete","aitable record get","aitable record history-list","aitable record primary-doc-create","aitable record primary-doc-get","aitable record query","aitable record query-empty","aitable record share-url","aitable record update","aitable record upsert","aitable table delete","aitable table update","aitable view create","aitable view delete","aitable view duplicate","aitable view get aggregate","aitable view get card","aitable view get field-widths","aitable view get fill-color-rule","aitable view get filter","aitable view get frozen-cols","aitable view get group","aitable view get lock","aitable view get row-height","aitable view get sort","aitable view get timebar","aitable view get visible-fields","aitable view list","aitable view lock","aitable view update aggregate","aitable view update card","aitable view update field-widths","aitable view update fill-color-rule","aitable view update filter","aitable view update frozen-cols","aitable view update group","aitable view update name","aitable view update row-height","aitable view update sort","aitable view update timebar","aitable view update visible-fields","aitable workflow run"],"risk":"green"}, - "plain_description": {"denotes":"plain-text description or remark with unchanged value","canonical_hint":"description","members":["description","desc"],"excludes":["field-description","config"],"commands":["aitable +base-update","aitable +form-update","aitable +table-update","aitable base update","aitable form create","aitable form update","aitable table update"],"risk":"green"}, + "plain_description": {"denotes":"plain-text description or remark with unchanged value","canonical_hint":"description","members":["description","desc"],"excludes":["field-description","config"],"commands":["aitable +base-update","aitable +form-update","aitable +table-update","aitable base update","aitable form create","aitable form update","aitable table update","calendar +create","calendar +update"],"risk":"green"}, "workflow_id": {"denotes":"single AI Table workflow identifier; service flowId and CLI workflow-id carry the same value","canonical_hint":"workflow-id","members":["workflow-id","flow-id"],"excludes":["id","task-id"],"commands":["aitable +workflow-deploy","aitable +workflow-disable","aitable +workflow-enable","aitable +workflow-get","aitable workflow disable","aitable workflow enable","aitable workflow get","aitable workflow history","aitable workflow run","aitable workflow update"],"risk":"green"}, "dept_id": {"denotes": "single department id", "canonical_hint": "dept", "members": ["dept", "dept-id", "department", "department-id", "parent", "parent-id"], "excludes": ["depts", "dept-ids", "department-ids", "name", "query"], "commands": ["contact +list-sub-depts", "contact dept list-children"], "risk": "yellow"}, "dept_ids": {"denotes": "department id list", "canonical_hint": "dept-ids", "members": ["depts", "dept-ids", "department-ids"], "excludes": ["dept", "dept-id", "department-id", "name", "query"], "commands": ["contact +list-dept-members"], "risk": "yellow"}, @@ -31,7 +31,7 @@ "open_message_ids": {"denotes": "DingTalk openMessageId list with unchanged element values", "canonical_hint": "msg-ids", "members": ["msg-ids", "message-ids", "open-message-ids"], "excludes": ["msg-id", "message-id", "open-message-id", "ref-msg-id", "src-msg-id"], "commands": ["chat +flag-cancel", "chat +flag-create", "chat +messages-combine-forward", "chat +messages-mget", "chat message combine-forward", "chat message list-by-ids", "chat message list-emotion-replies"], "risk": "yellow"}, "referenced_open_message_id": {"denotes": "referenced DingTalk openMessageId in a reply", "canonical_hint": "ref-msg-id", "members": ["ref-msg-id", "ref-message-id"], "excludes": ["msg-id", "message-id", "open-message-id", "msg-ids", "src-msg-id"], "commands": ["chat +messages-reply", "chat message reply"], "risk": "yellow"}, "user_id": {"denotes": "single user id", "canonical_hint": "user-id", "members": ["user", "user-id", "userid", "uid", "staff-id"], "excludes": ["at-user-ids", "to-user", "users", "user-ids", "name"], "commands": ["chat +chat-role-query-user", "chat +chat-role-set-user", "chat +messages-list-direct", "chat chmod", "chat conversation-info", "chat group transfer-owner", "chat group-role query-user", "chat group-role remove-user", "chat group-role set-user", "chat message list", "chat message send", "contact user profile get"], "risk": "yellow"}, - "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat +messages-batch-send-by-bot", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot"], "risk": "yellow"}, + "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat +messages-batch-send-by-bot", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot", "calendar +freebusy", "calendar +suggestion"], "risk": "yellow"}, "open_dingtalk_ids": {"denotes": "DingTalk openDingTalkId list with unchanged element values", "canonical_hint": "open-dingtalk-ids", "members": ["open-dingtalk-ids"], "excludes": ["user", "user-id", "user-ids", "staff-id", "users"], "commands": ["chat +chat-members-get", "chat category create-smart", "chat group members list-by-ids", "chat message send-by-bot"], "risk": "yellow"}, "ding_id": {"denotes": "DING id", "canonical_hint": "ding-id", "members": ["ding-id", "open-ding-id"], "excludes": ["id"], "commands": ["ding message receiver-status"], "risk": "yellow"}, "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive +copy", "drive +create-folder", "drive +create-shortcut", "drive +list", "drive +move", "drive +upload", "drive commit", "drive copy", "drive list", "drive mkdir", "drive move", "drive shortcut", "drive upload", "drive upload-info", "mail folder update"], "risk": "green"}, @@ -54,7 +54,14 @@ "created_time_end": {"denotes": "Doc/Drive search created-time upper bound in unchanged millisecond timestamp unit", "canonical_hint": "created-to", "members": ["created-to", "created-before", "create-time-to", "created-time-end", "create-time-end"], "excludes": ["created-from", "modified-from", "modified-to", "end", "to"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, "document_permission_role": {"denotes": "direct document-space permission role on grant/apply/update, passed unchanged", "canonical_hint": "role", "members": ["role", "permission-role", "access-role", "member-role"], "excludes": ["filter-role", "reserve-role", "permission", "public-permission"], "commands": ["doc +access-change", "doc +access-grant", "doc +grant-and-share", "drive permission add", "drive permission apply", "drive permission update"], "risk": "yellow"}, "creator_user_ids": {"denotes": "creator userId list used to filter Doc/Drive search results, passed unchanged", "canonical_hint": "creator-uids", "members": ["creator-uids", "creator-user-ids", "creator-ids", "created-by-user-ids"], "excludes": ["user", "user-id", "user-ids", "users", "owner-id", "modifier-uids"], "commands": ["doc +search", "drive +search", "drive search"], "risk": "yellow"}, - "local_output_path": {"denotes": "local destination file or directory path for a download/export result, passed unchanged", "canonical_hint": "output", "members": ["output", "output-path", "destination-path", "save-path"], "excludes": ["file", "file-path", "folder", "folder-id", "content-file"], "commands": ["doc +export", "doc +export-get", "doc +media-download", "doc +resource-download", "doc read", "drive +download", "drive +version-download", "drive download", "drive download-version"], "risk": "green"} + "local_output_path": {"denotes": "local destination file or directory path for a download/export result, passed unchanged", "canonical_hint": "output", "members": ["output", "output-path", "destination-path", "save-path"], "excludes": ["file", "file-path", "folder", "folder-id", "content-file"], "commands": ["doc +export", "doc +export-get", "doc +media-download", "doc +resource-download", "doc read", "drive +download", "drive +version-download", "drive download", "drive download-version"], "risk": "green"}, + "calendar_event_id": {"denotes":"single calendar eventId in the target-event role","canonical_hint":"event","members":["event","event-id","calendar-event-id"],"excludes":["id","calendar-id","calendar-book-id","acl-id","room-id"],"commands":["calendar +attendee-list","calendar +cancel-event","calendar +invite","calendar +reschedule","calendar +get","calendar +rsvp","calendar +update"],"risk":"yellow"}, + "calendar_book_id": {"denotes":"single calendar container calendarId, not an eventId","canonical_hint":"calendar-id","members":["calendar-id","calendar","calendar-book-id"],"excludes":["id","event","event-id","acl-id","room-id"],"commands":["calendar +agenda","calendar +attendee-list","calendar +create","calendar +get","calendar +rsvp","calendar +search-event","calendar +update"],"risk":"yellow"}, + "calendar_event_title": {"denotes":"calendar event title text","canonical_hint":"title","members":["title","summary","subject"],"excludes":["name","room-name","calendar-name"],"commands":["calendar +book","calendar +create","calendar +update"],"risk":"green"}, + "calendar_person_name_list": {"denotes":"comma-separated DingTalk person names resolved by the shortcut","canonical_hint":"with","members":["with","names","attendee-names","participant-names"],"excludes":["user","user-id","user-ids","users","attendees","participants","open-dingtalk-ids"],"commands":["calendar +book","calendar +invite","calendar +suggest-time"],"risk":"yellow"}, + "calendar_room_ids": {"denotes":"calendar meeting roomId list with unchanged element values; one roomId is a one-element list","canonical_hint":"rooms","members":["rooms","room-id","room-ids"],"excludes":["room","room-name","group-id","location"],"commands":["calendar event create","calendar room add","calendar room delete","calendar busy search","calendar +create","calendar +freebusy"],"risk":"yellow"}, + "calendar_duration_minutes": {"denotes":"meeting duration in minutes with unchanged numeric text","canonical_hint":"duration","members":["duration","duration-minutes","meeting-duration-minutes"],"excludes":["remind-minutes","start","end","from","to"],"commands":["calendar event suggest","calendar +suggest-time","calendar +suggestion"],"risk":"green"}, + "calendar_timezone": {"denotes":"IANA timezone string with unchanged value","canonical_hint":"timezone","members":["timezone","time-zone","tz"],"excludes":["offset","utc-offset","locale"],"commands":["calendar event create","calendar event suggest","calendar event update","calendar +create","calendar +suggestion","calendar +update"],"risk":"green"} }, "command_overrides": { @@ -82,6 +89,40 @@ "mail folder update": {"bind": {"id": "folder_id"}, "note": "this command's --id is the folder id; --folder-id reduces to --id"}, "mail message search": {"scoped_aliases": {"subject": "query"}, "scope_strict": true, "note": "never globalize: mail template create has a real and different --subject"}, "calendar event list": {"scoped_aliases": {"date": "start"}, "note": "reviewed against ParseISOTimeToMillis and final list_calendar_events payload; --date is normalized centrally while the command's existing hidden compatibility flags remain native fallbacks"}, + "calendar +agenda": {"block":["id"],"note":"calendarId aliases stay role-specific; bare --id could be an eventId and must not be silently treated as a calendarId. On this exact command, --to is an unchanged ISO end timestamp and normalizes to --end.","scoped_aliases":{"to":"end"},"scope_strict":true}, + "calendar +attendee-list": {"ambiguous":["id"],"note":"This command carries both an eventId and an optional calendarId; bare --id cannot safely choose the role."}, + "calendar +book": {"block":["user","user-id","user-ids","users","attendees","participants","open-dingtalk-ids","calendar-id","rooms","room-id","room-ids","date","time","start-date","end-date","time-min","time-max"],"note":"--with carries names resolved by the shortcut; identifier spellings and room booking inputs cannot be supplied by name-only normalization. Only explicit event-time spellings are mapped; range-bound or date-only spellings remain blocked.","scoped_aliases":{"from":"start","begin":"start","start-time":"start","to":"end","end-time":"end"},"scope_strict":true}, + "calendar +book-search": {"scoped_aliases":{"search":"query","name":"query"},"scope_strict":true,"note":"On this exact calendar-book search, --search, --name, and --query carry the same calendar-name keyword."}, + "calendar +cancel-event": {"scoped_aliases":{"id":"event"},"block":["calendar-id","calendar-book-id","acl-id","room-id"],"scope_strict":true,"note":"The only identifier role is the eventId to cancel; other calendar resource IDs are rejected."}, + "calendar +conflicts": {"scoped_aliases":{"day-offset":"in-days","days-from-today":"in-days"},"block":["days","duration","start","end","from","to"],"scope_strict":true,"note":"--in-days is an integer offset from today. Exact day-offset spellings preserve the value; generic duration and absolute/range time names are different roles."}, + "calendar +free": {"block":["user","user-id","user-ids","users","with"],"note":"--who carries one person name for runtime resolution, so exact name/person spellings are command-scoped while stable user identifiers stay blocked. On this exact command, --to is an unchanged ISO end timestamp and normalizes to --end.","scoped_aliases":{"to":"end","name":"who","person":"who","person-name":"who"},"scope_strict":true}, + "calendar +free-slots": {"scoped_aliases":{"start-hour":"from","end-hour":"to","day-offset":"in-days","days-from-today":"in-days"},"block":["start","end","start-time","end-time","time-min","time-max","days","duration"],"scope_strict":true,"note":"--from/--to are integer hours and --in-days is a relative day offset; exact unit-preserving spellings are command-scoped while ISO timestamp and generic duration names stay blocked."}, + "calendar +freebusy": {"block":["who","with","name","names","attendee-names","participant-names","room-name","group-id"],"note":"This shortcut accepts stable userId/roomId lists; singular --room-id is one list element and normalizes safely, while names and room-search filters require different commands. On this exact command, --to is an unchanged ISO end timestamp and normalizes to --end.","scoped_aliases":{"to":"end"},"scope_strict":true}, + "calendar +invite": {"scoped_aliases":{"id":"event"},"block":["user","user-id","user-ids","users","attendees","participants","open-dingtalk-ids","calendar-id"],"scope_strict":true,"note":"--with is a name list resolved by the shortcut; stable person identifiers are not renamed into names."}, + "calendar +reschedule": {"scoped_aliases":{"id":"event","from":"start","begin":"start","start-time":"start","to":"end","end-time":"end"},"block":["calendar-id","calendar-book-id","acl-id","date","time","start-date","end-date","time-min","time-max"],"scope_strict":true,"note":"The only identifier role is the eventId being rescheduled. Only explicit new-event-time spellings are mapped; range-bound or date-only spellings remain blocked."}, + "calendar +room-groups": {"scoped_aliases":{"page-index":"page"},"block":["cursor","page-token"],"scope_strict":true,"note":"This endpoint uses a zero-based pageIndex; cursor pagination cannot be converted to it."}, + "calendar +room-search": {"scoped_aliases":{"query":"room-name","name":"room-name"},"block":["room","room-id","room-ids","rooms","group-id","location"],"scope_strict":true,"note":"This shortcut accepts a room display-name keyword and returns roomId; identifier/location inputs are different roles."}, + "calendar +suggest-time": {"block":["user","user-id","user-ids","users","attendees","participants","open-dingtalk-ids"],"note":"--with carries names resolved by the shortcut; stable identifier lists belong to event suggest/freebusy. On this exact command, --to is an unchanged ISO end timestamp and normalizes to --end.","scoped_aliases":{"to":"end"},"scope_strict":true}, + "calendar acl delete": {"block":["calendar-id","calendar-book-id","event","event-id","room-id","user-id"],"note":"--acl-id identifies one access-control grant, not a calendar, event, room, or user."}, + "calendar attachment add": {"block":["file","file-id","file-ids","attachments"],"note":"--files requires : elements; a bare file identifier cannot be wrapped or named by the alias layer."}, + "calendar attendee add": {"block":["attendee-name","attendee-names","participant-name","participant-names","with","who","open-dingtalk-ids"],"note":"--attendees carries a userId list; names require a resolver shortcut and openDingTalkIds are a distinct value domain."}, + "calendar attendee delete": {"block":["attendee-name","attendee-names","participant-name","participant-names","with","who","open-dingtalk-ids"],"note":"--attendees carries a userId list; names require a resolver shortcut and openDingTalkIds are a distinct value domain."}, + "calendar busy search": {"block":["who","with","name","names","attendee-name","attendee-names","participant-names","room-name"],"note":"--users/--rooms are stable ID lists; singular --room-id safely denotes one list element, the existing hidden --room-ids compatibility stays native, and names require a resolver or room search."}, + "calendar event create": {"scoped_aliases":{"reminder-minutes":"remind-minutes","reminder-offset-minutes":"remind-minutes"},"block":["attendee-name","attendee-names","participant-name","participant-names","with","who","room-name","group-id","reminder-time","remind-at","at","due","duration"],"scope_strict":true,"note":"Creation accepts stable attendee/room identifiers and minute offsets; singular --room-id safely denotes one list element and the existing hidden --room-ids compatibility stays native. Reminder aliases are exact to this command; names, room search criteria, absolute reminder times, and generic duration need separate resolution or value transforms."}, + "calendar event respond": {"scoped_aliases":{"response-status":"status","response":"status"},"block":["state","done","free-busy","availability"],"scope_strict":true,"note":"The response/status flag-name aliases are exact to this command. --status still uses this leaf's own attendee-response enum; values are not translated, and busy/free state or boolean completion names stay blocked."}, + "calendar event suggest": {"block":["who","with","name","names","attendee-name","attendee-names","participant-names","open-dingtalk-ids"],"note":"--users carries stable userIds; name resolution belongs to +suggest-time."}, + "calendar event update": {"block":["attendees","participants","rooms","room-id","room-ids","room-name","group-id","remind-minutes","reminder-minutes"],"note":"The command's existing hidden --freebusy compatibility flag remains native. Attendee, room, and reminder changes require dedicated commands or are unsupported by update."}, + "calendar room add": {"block":["room","room-name","group-id","location"],"note":"--rooms is a roomId list returned by room search; singular --room-id safely denotes one list element and the existing hidden --room-ids compatibility stays native, while generic room, name, group, and location roles are not promoted automatically."}, + "calendar room delete": {"block":["room","room-name","group-id","location"],"note":"--rooms is a roomId list returned by room search; singular --room-id safely denotes one list element and the existing hidden --room-ids compatibility stays native, while generic room, name, group, and location roles are not promoted automatically."}, + "calendar room search": {"scoped_aliases":{"room-group-id":"group-id","group":"group-id"},"block":["room","room-id","room-ids","rooms","location"],"scope_strict":true,"note":"On this exact command, room-group-id/group denote the meeting-room group filter; search consumes room name/group/time filters and returns roomId, while existing room identifiers and free-text event location are different roles."}, + "calendar +my-free": {"scoped_aliases":{"to":"end"},"scope_strict":true,"note":"On this exact command, --to is an unchanged ISO end timestamp and normalizes to --end."}, + "calendar +create": {"scoped_aliases":{"from":"start","begin":"start","start-time":"start","to":"end","end-time":"end","freebusy":"free-busy","user-ids":"attendees","users":"attendees","attendee-ids":"attendees"},"block":["id","event","event-id","who","with","attendee-name","attendee-names","participant-name","participant-names","open-dingtalk-ids","room-name","group-id","rich-text-desc","date","time","start-date","end-date","time-min","time-max"],"scope_strict":true,"note":"The shortcut accepts stable attendee userId and roomId lists plus one calendarId; singular --room-id is one list element and normalizes safely. Names, openDingTalkIds, event identifiers, room-search filters, and HTML rich text are different roles; --to and --freebusy are exact value-preserving spellings on this command."}, + "calendar +get": {"ambiguous":["id"],"note":"The command carries one required eventId and one optional calendarId, so bare --id cannot safely select a role."}, + "calendar +room-find": {"scoped_aliases":{"to":"end","page-index":"page","room-group-id":"group-id","group":"group-id","query":"room-name","name":"room-name"},"block":["cursor","page-token","next-cursor","room","room-id","room-ids","rooms","location"],"scope_strict":true,"note":"This shortcut combines ISO time bounds, a zero-based pageIndex, and room-name/group filters. Cursor pagination and existing room identifiers cannot be converted to these filter roles."}, + "calendar +rsvp": {"scoped_aliases":{"response-status":"status","response":"status"},"ambiguous":["id"],"block":["state","done","free-busy","availability"],"scope_strict":true,"note":"The command carries eventId and calendarId together; bare --id is ambiguous. Response/status aliases are exact to this leaf, but --status still uses +rsvp's own enum values; values are never translated, and busy/free state names stay blocked."}, + "calendar +search-event": {"scoped_aliases":{"to":"end","search":"query"},"block":["id","event","event-id","page","page-index","offset"],"scope_strict":true,"note":"The query searches title, description, and location within one calendar page. This route uses cursor pagination; event identifiers and page-index/offset models are different roles."}, + "calendar +suggestion": {"scoped_aliases":{"to":"end"},"block":["who","with","name","names","attendee-name","attendee-names","participant-name","participant-names","open-dingtalk-ids","room-name","room-id","room-ids","rooms"],"scope_strict":true,"note":"This shortcut accepts stable userId values. Person names belong to +suggest-time, openDingTalkIds are a different value domain, and room availability is a different query."}, + "calendar +update": {"scoped_aliases":{"from":"start","begin":"start","start-time":"start","to":"end","end-time":"end","freebusy":"free-busy","add-users":"add-attendees","add-user-ids":"add-attendees","remove-users":"remove-attendees","remove-user-ids":"remove-attendees"},"ambiguous":["id","attendees","users","user-ids"],"block":["who","with","attendee-name","attendee-names","participant-name","participant-names","open-dingtalk-ids","rooms","room-id","room-ids","room-name","group-id","rich-text-desc","remind-minutes","reminder-minutes","date","time","start-date","end-date","time-min","time-max"],"scope_strict":true,"note":"Bare --id cannot choose eventId versus calendarId, and a generic attendee list cannot choose add versus remove. Directional userId aliases are safe; names, openDingTalkIds, room changes, rich text, and reminders require different commands or capabilities."}, "chat +bot-find": {"scoped_aliases": {"name": "query"}, "scope_strict": true, "note": "On this exact bot-search shortcut, --name and --query denote the same search keyword; --name must not become a global search alias."}, "chat +chat-messages": {"scoped_aliases": {"chat": "group"}, "scope_strict": true, "note": "Evaluation compatibility: --chat carries one stable openConversationId and normalizes to the existing --group identifier route."}, "chat +search-msg": {"scoped_aliases": {"chat": "group"}, "scope_strict": true, "note": "Evaluation compatibility: scalar --chat carries one stable openConversationId and normalizes to the existing scalar --group filter."}, @@ -695,7 +736,113 @@ {"command":"aitable workflow history","emitted":"page-index","expect":"page","via":"override:scoped-zero-based-page"}, {"command":"aitable workflow history","emitted":"cursor","expect":"did-you-mean:blocked","via":"guard:page-vs-cursor-model"}, {"command":"aitable workflow history","emitted":"offset","expect":"did-you-mean:blocked","via":"guard:page-vs-offset-model"}, - {"command":"aitable workflow history","emitted":"page-number","expect":"did-you-mean:blocked","via":"guard:zero-vs-one-based-page"} + {"command":"aitable workflow history","emitted":"page-number","expect":"did-you-mean:blocked","via":"guard:zero-vs-one-based-page"}, + {"command":"calendar +agenda","emitted":"from","expect":"start","via":"concept:time_start"}, + {"command":"calendar +agenda","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +agenda","emitted":"max-results","expect":"limit","via":"concept:pagination_size"}, + {"command":"calendar +agenda","emitted":"next-cursor","expect":"cursor","via":"concept:page_cursor"}, + {"command":"calendar +agenda","emitted":"calendar-book-id","expect":"calendar-id","via":"concept:calendar_book_id"}, + {"command":"calendar +agenda","emitted":"id","expect":"did-you-mean:blocked","via":"guard:calendar-id-vs-event-id"}, + {"command":"calendar +attendee-list","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, + {"command":"calendar +attendee-list","emitted":"calendar-book-id","expect":"calendar-id","via":"concept:calendar_book_id"}, + {"command":"calendar +attendee-list","emitted":"id","expect":"did-you-mean:ambiguous","via":"guard:event-id-vs-calendar-id"}, + {"command":"calendar +book","emitted":"summary","expect":"title","via":"concept:calendar_event_title"}, + {"command":"calendar +book","emitted":"attendee-names","expect":"with","via":"concept:calendar_person_name_list"}, + {"command":"calendar +book","emitted":"user-ids","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +book-search","emitted":"keyword","expect":"query","via":"concept:search_query"}, + {"command":"calendar +book-search","emitted":"search","expect":"query","via":"override:scoped_strict"}, + {"command":"calendar +book-search","emitted":"name","expect":"query","via":"override:scoped_strict"}, + {"command":"calendar +cancel-event","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, + {"command":"calendar +cancel-event","emitted":"id","expect":"event","via":"override:scoped_strict"}, + {"command":"calendar +cancel-event","emitted":"calendar-id","expect":"did-you-mean:blocked","via":"guard:event-id-vs-calendar-id"}, + {"command":"calendar +free","emitted":"name","expect":"who","via":"override:scoped_strict"}, + {"command":"calendar +free","emitted":"user-id","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +free-slots","emitted":"start-hour","expect":"from","via":"override:scoped_strict"}, + {"command":"calendar +free-slots","emitted":"end-hour","expect":"to","via":"override:scoped_strict"}, + {"command":"calendar +free-slots","emitted":"day-offset","expect":"in-days","via":"override:scoped_strict"}, + {"command":"calendar +free-slots","emitted":"start","expect":"did-you-mean:blocked","via":"guard:hour-vs-iso-time"}, + {"command":"calendar +freebusy","emitted":"user-ids","expect":"users","via":"concept:user_ids"}, + {"command":"calendar +freebusy","emitted":"room-ids","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar +freebusy","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar +freebusy","emitted":"with","expect":"did-you-mean:blocked","via":"guard:id-list-vs-name-list"}, + {"command":"calendar +my-free","emitted":"from","expect":"start","via":"concept:time_start"}, + {"command":"calendar +my-free","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +invite","emitted":"id","expect":"event","via":"override:scoped_strict"}, + {"command":"calendar +invite","emitted":"participant-names","expect":"with","via":"concept:calendar_person_name_list"}, + {"command":"calendar +invite","emitted":"user-ids","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +reschedule","emitted":"id","expect":"event","via":"override:scoped_strict"}, + {"command":"calendar +reschedule","emitted":"from","expect":"start","via":"override:scoped_strict"}, + {"command":"calendar +reschedule","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +room-groups","emitted":"page-size","expect":"limit","via":"concept:pagination_size"}, + {"command":"calendar +room-groups","emitted":"page-index","expect":"page","via":"override:scoped_strict"}, + {"command":"calendar +room-groups","emitted":"cursor","expect":"did-you-mean:blocked","via":"guard:cursor-vs-page-index"}, + {"command":"calendar +room-search","emitted":"query","expect":"room-name","via":"override:scoped_strict"}, + {"command":"calendar +room-search","emitted":"room-id","expect":"did-you-mean:blocked","via":"guard:room-name-vs-room-id"}, + {"command":"calendar +suggest-time","emitted":"duration-minutes","expect":"duration","via":"concept:calendar_duration_minutes"}, + {"command":"calendar +suggest-time","emitted":"attendee-names","expect":"with","via":"concept:calendar_person_name_list"}, + {"command":"calendar +suggest-time","emitted":"user-ids","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +conflicts","emitted":"day-offset","expect":"in-days","via":"override:scoped_strict"}, + {"command":"calendar attachment add","emitted":"file-id","expect":"did-you-mean:blocked","via":"guard:structured-file-list"}, + {"command":"calendar attendee add","emitted":"attendee-name","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar busy search","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar busy search","emitted":"room-name","expect":"did-you-mean:blocked","via":"guard:room-name-vs-room-id"}, + {"command":"calendar event create","emitted":"reminder-minutes","expect":"remind-minutes","via":"override:scoped_strict"}, + {"command":"calendar event create","emitted":"tz","expect":"timezone","via":"concept:calendar_timezone"}, + {"command":"calendar event create","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar event create","emitted":"room-name","expect":"did-you-mean:blocked","via":"guard:room-name-vs-room-id"}, + {"command":"calendar event respond","emitted":"response-status","expect":"status","via":"override:scoped_strict"}, + {"command":"calendar event respond","emitted":"free-busy","expect":"did-you-mean:blocked","via":"guard:response-vs-busy-state"}, + {"command":"calendar event suggest","emitted":"duration-minutes","expect":"duration","via":"concept:calendar_duration_minutes"}, + {"command":"calendar event suggest","emitted":"attendee-names","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar event update","emitted":"tz","expect":"timezone","via":"concept:calendar_timezone"}, + {"command":"calendar event update","emitted":"rooms","expect":"did-you-mean:blocked","via":"guard:dedicated-room-command"}, + {"command":"calendar room add","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar room delete","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar room search","emitted":"room-group-id","expect":"group-id","via":"override:scoped_strict"}, + {"command":"calendar room search","emitted":"room-id","expect":"did-you-mean:blocked","via":"guard:room-filter-vs-room-id"}, + {"command":"calendar acl delete","emitted":"calendar-id","expect":"did-you-mean:blocked","via":"guard:acl-id-vs-calendar-id"}, + {"command":"calendar +create","emitted":"summary","expect":"title","via":"concept:calendar_event_title"}, + {"command":"calendar +create","emitted":"description","expect":"desc","via":"concept:plain_description"}, + {"command":"calendar +create","emitted":"user-ids","expect":"attendees","via":"override:scoped_strict"}, + {"command":"calendar +create","emitted":"room-ids","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar +create","emitted":"room-id","expect":"rooms","via":"concept:calendar_room_ids"}, + {"command":"calendar +create","emitted":"calendar-book-id","expect":"calendar-id","via":"concept:calendar_book_id"}, + {"command":"calendar +create","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +create","emitted":"from","expect":"start","via":"override:scoped_strict"}, + {"command":"calendar +create","emitted":"attendee-names","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +get","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, + {"command":"calendar +get","emitted":"calendar-book-id","expect":"calendar-id","via":"concept:calendar_book_id"}, + {"command":"calendar +get","emitted":"id","expect":"did-you-mean:ambiguous","via":"guard:event-id-vs-calendar-id"}, + {"command":"calendar +room-find","emitted":"from","expect":"start","via":"concept:time_start"}, + {"command":"calendar +room-find","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +room-find","emitted":"page-size","expect":"limit","via":"concept:pagination_size"}, + {"command":"calendar +room-find","emitted":"page-index","expect":"page","via":"override:scoped_strict"}, + {"command":"calendar +room-find","emitted":"room-group-id","expect":"group-id","via":"override:scoped_strict"}, + {"command":"calendar +room-find","emitted":"query","expect":"room-name","via":"override:scoped_strict"}, + {"command":"calendar +room-find","emitted":"cursor","expect":"did-you-mean:blocked","via":"guard:page-index-vs-cursor"}, + {"command":"calendar +rsvp","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, + {"command":"calendar +rsvp","emitted":"response-status","expect":"status","via":"override:scoped_strict"}, + {"command":"calendar +rsvp","emitted":"id","expect":"did-you-mean:ambiguous","via":"guard:event-id-vs-calendar-id"}, + {"command":"calendar +rsvp","emitted":"free-busy","expect":"did-you-mean:blocked","via":"guard:response-vs-busy-state"}, + {"command":"calendar +search-event","emitted":"keyword","expect":"query","via":"concept:search_query"}, + {"command":"calendar +search-event","emitted":"from","expect":"start","via":"concept:time_start"}, + {"command":"calendar +search-event","emitted":"to","expect":"end","via":"override:scoped_strict"}, + {"command":"calendar +search-event","emitted":"next-cursor","expect":"cursor","via":"concept:page_cursor"}, + {"command":"calendar +search-event","emitted":"max-results","expect":"limit","via":"concept:pagination_size"}, + {"command":"calendar +search-event","emitted":"page","expect":"did-you-mean:blocked","via":"guard:cursor-vs-page-index"}, + {"command":"calendar +suggestion","emitted":"user-ids","expect":"users","via":"concept:user_ids"}, + {"command":"calendar +suggestion","emitted":"duration-minutes","expect":"duration","via":"concept:calendar_duration_minutes"}, + {"command":"calendar +suggestion","emitted":"tz","expect":"timezone","via":"concept:calendar_timezone"}, + {"command":"calendar +suggestion","emitted":"attendee-names","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, + {"command":"calendar +update","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, + {"command":"calendar +update","emitted":"from","expect":"start","via":"override:scoped_strict"}, + {"command":"calendar +update","emitted":"summary","expect":"title","via":"concept:calendar_event_title"}, + {"command":"calendar +update","emitted":"description","expect":"desc","via":"concept:plain_description"}, + {"command":"calendar +update","emitted":"add-user-ids","expect":"add-attendees","via":"override:scoped_strict"}, + {"command":"calendar +update","emitted":"remove-user-ids","expect":"remove-attendees","via":"override:scoped_strict"}, + {"command":"calendar +update","emitted":"id","expect":"did-you-mean:ambiguous","via":"guard:event-id-vs-calendar-id"}, + {"command":"calendar +update","emitted":"attendees","expect":"did-you-mean:ambiguous","via":"guard:add-vs-remove-role"}, + {"command":"calendar +update","emitted":"room-ids","expect":"did-you-mean:blocked","via":"guard:dedicated-room-command"} ] } } From a325ca80d8c2407f8f4426b9691dd8e0f076fd62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 22:43:42 +0800 Subject: [PATCH 233/250] fix(aitable): harden recovery and retry cancellation --- internal/helpers/aitable.go | 7 ++-- .../helpers/aitable_command_edges_test.go | 12 +++++- internal/shortcut/aitable/base_composite.go | 4 +- .../aitable/base_composite_e2e_test.go | 42 +++++++++++++++++++ internal/shortcut/aitable/composite_output.go | 25 +++++++++++ 5 files changed, 84 insertions(+), 6 deletions(-) diff --git a/internal/helpers/aitable.go b/internal/helpers/aitable.go index 31e99fa9..f981d7cd 100644 --- a/internal/helpers/aitable.go +++ b/internal/helpers/aitable.go @@ -806,9 +806,10 @@ func callAitableToolContext(ctx context.Context, toolName string, args map[strin if attempt > 0 { backoff := time.Duration(1<<(attempt-1)) * time.Second // 1s, 2s, 4s fmt.Fprintf(os.Stderr, "[aitable retry %d/%d] %s after %v...\n", attempt, aitableMaxRetries, toolName, backoff) - helperSleep(backoff) - if err := ctx.Err(); err != nil { - return err + select { + case <-ctx.Done(): + return ctx.Err() + case <-helperAfter(backoff): } } diff --git a/internal/helpers/aitable_command_edges_test.go b/internal/helpers/aitable_command_edges_test.go index 816232f2..e821023c 100644 --- a/internal/helpers/aitable_command_edges_test.go +++ b/internal/helpers/aitable_command_edges_test.go @@ -9,6 +9,7 @@ import ( "testing" "time" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition" ) @@ -83,6 +84,11 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T oldDeps, oldSleep := deps, helperSleep t.Cleanup(func() { deps, helperSleep = oldDeps, oldSleep }) helperSleep = func(time.Duration) {} + testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time { + ready := make(chan time.Time, 1) + ready <- time.Time{} + return ready + }) retryable := fmt.Errorf("timeout: retryable: true") caller := &aitableTestCaller{errors: []error{retryable, retryable, retryable, retryable}} @@ -112,7 +118,11 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T caller = &aitableTestCaller{errors: []error{retryable}} installAitableDeps(t, caller) ctx, cancel := context.WithCancel(context.Background()) - helperSleep = func(time.Duration) { cancel() } + backoffPending := make(chan time.Time) + testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time { + cancel() + return backoffPending + }) if err := callAitableToolContext(ctx, "cancel-during-backoff", nil); err != context.Canceled { t.Fatalf("cancel during retry backoff = %v, want %v", err, context.Canceled) } diff --git a/internal/shortcut/aitable/base_composite.go b/internal/shortcut/aitable/base_composite.go index 91cca852..3b242be8 100644 --- a/internal/shortcut/aitable/base_composite.go +++ b/internal/shortcut/aitable/base_composite.go @@ -215,7 +215,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { if err != nil { result.Status = "unknown" result.FailedCount = len(tables) - result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying"} + result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying", "name": rt.Str("name")} result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json") return compositeError(result, err, false) } @@ -223,7 +223,7 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error { if baseID == "" { result.Status = "unknown" result.Result = baseData - result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying"} + result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying", "name": rt.Str("name")} result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json") return compositeError(result, fmt.Errorf("create_base response is missing baseId"), false) } diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index d436371e..0295c47f 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -368,6 +368,48 @@ func TestCrossPlatformCoverageAITableRecoveryCommandsQuoteUntrustedValues(t *tes }) } +func TestCrossPlatformCoverageAITableRecoveryCommandsUseWindowsPlaceholders(t *testing.T) { + tests := []struct { + name string + argv []string + want string + }{ + { + name: "query ampersand", + argv: []string{"dws", "aitable", "+base-search", "--query", "x&calc", "--format", "json"}, + want: "dws aitable +base-search --query REPLACE_QUERY --format json", + }, + { + name: "base id pipe", + argv: []string{"dws", "aitable", "+base-get", "--base-id", "base|whoami", "--format", "json"}, + want: "dws aitable +base-get --base-id REPLACE_BASE_ID --format json", + }, + { + name: "table id variable expansion", + argv: []string{"dws", "aitable", "+table-get", "--base-id", "base", "--table-id", "%PATH%", "--format", "json"}, + want: "dws aitable +table-get --base-id base --table-id REPLACE_TABLE_ID --format json", + }, + { + name: "portable values stay inline", + argv: []string{"dws", "aitable", "+table-get", "--base-id", "base-1", "--table-id", "table_2", "--format", "json"}, + want: "dws aitable +table-get --base-id base-1 --table-id table_2 --format json", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := aitableRecoveryCommandForPlatform("windows", tc.argv...) + if got != tc.want { + t.Fatalf("windows recovery = %q, want %q", got, tc.want) + } + for _, hostile := range []string{"&", "|", "%PATH%"} { + if strings.Contains(got, hostile) { + t.Fatalf("windows recovery contains hostile token %q: %s", hostile, got) + } + } + }) + } +} + func TestCrossPlatformCoverageBaseBootstrapRecoversFieldCallErrorE2E(t *testing.T) { fields := bootstrapFields(16) caller := &upsertByKeyCaller{steps: []upsertByKeyStep{ diff --git a/internal/shortcut/aitable/composite_output.go b/internal/shortcut/aitable/composite_output.go index 751a5ada..603992a5 100644 --- a/internal/shortcut/aitable/composite_output.go +++ b/internal/shortcut/aitable/composite_output.go @@ -5,6 +5,7 @@ package aitable import ( "fmt" + "runtime" "strings" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" @@ -55,13 +56,37 @@ func newCompositeResult(operation string) compositeResult { } func aitableRecoveryCommand(argv ...string) string { + return aitableRecoveryCommandForPlatform(runtime.GOOS, argv...) +} + +func aitableRecoveryCommandForPlatform(goos string, argv ...string) string { quoted := make([]string, len(argv)) for index, arg := range argv { + // POSIX 单引号不能保护 cmd.exe；Windows 下只允许跨 shell 均可裸放的 + // 保守白名单值进入可复制命令，其余值改成不含 shell 元字符的占位符。 + if goos == "windows" && helpers.ShellQuoteArg(arg) != arg { + quoted[index] = aitableRecoveryPlaceholder(argv, index) + continue + } quoted[index] = helpers.ShellQuoteArg(arg) } return strings.Join(quoted, " ") } +func aitableRecoveryPlaceholder(argv []string, index int) string { + if index > 0 { + switch argv[index-1] { + case "--query": + return "REPLACE_QUERY" + case "--base-id": + return "REPLACE_BASE_ID" + case "--table-id": + return "REPLACE_TABLE_ID" + } + } + return "REPLACE_VALUE" +} + func compositeError(result compositeResult, cause error, retryable bool) error { result.Retryable = retryable if result.Status == "success" { From 39d9a656162e36d94e68643a9faef6361469ead7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=8F=E6=99=BA?= Date: Tue, 18 Aug 2026 23:03:05 +0800 Subject: [PATCH 234/250] test(aitable): cover platform recovery behavior --- .../shortcut/aitable/base_composite_e2e_test.go | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/internal/shortcut/aitable/base_composite_e2e_test.go b/internal/shortcut/aitable/base_composite_e2e_test.go index 0295c47f..20c6965d 100644 --- a/internal/shortcut/aitable/base_composite_e2e_test.go +++ b/internal/shortcut/aitable/base_composite_e2e_test.go @@ -9,6 +9,7 @@ import ( "encoding/json" "errors" "fmt" + "runtime" "strings" "testing" @@ -319,6 +320,9 @@ func TestCrossPlatformCoverageAITableRecoveryCommandsQuoteUntrustedValues(t *tes t.Fatalf("hostile base name error = %#v", err) } want := `dws aitable +base-search --query '项目 $(touch /tmp/pwn) '\''Q'\''' --format json` + if runtime.GOOS == "windows" { + want = `dws aitable +base-search --query REPLACE_QUERY --format json` + } if typed.Actions[0] != want { t.Fatalf("base name recovery = %q, want %q", typed.Actions[0], want) } @@ -340,6 +344,9 @@ func TestCrossPlatformCoverageAITableRecoveryCommandsQuoteUntrustedValues(t *tes t.Fatalf("hostile base id error = %#v", err) } want := `dws aitable +base-get --base-id 'base;printf hacked' --format json` + if runtime.GOOS == "windows" { + want = `dws aitable +base-get --base-id REPLACE_BASE_ID --format json` + } if typed.Actions[0] != want { t.Fatalf("base id recovery = %q, want %q", typed.Actions[0], want) } @@ -362,6 +369,9 @@ func TestCrossPlatformCoverageAITableRecoveryCommandsQuoteUntrustedValues(t *tes t.Fatalf("hostile table ids error = %#v", err) } want := `dws aitable +table-get --base-id 'base id;exit 1' --table-id 'table` + "`uname`" + `'\''x' --format json` + if runtime.GOOS == "windows" { + want = `dws aitable +table-get --base-id REPLACE_BASE_ID --table-id REPLACE_TABLE_ID --format json` + } if typed.Actions[0] != want { t.Fatalf("table ids recovery = %q, want %q", typed.Actions[0], want) } @@ -394,6 +404,11 @@ func TestCrossPlatformCoverageAITableRecoveryCommandsUseWindowsPlaceholders(t *t argv: []string{"dws", "aitable", "+table-get", "--base-id", "base-1", "--table-id", "table_2", "--format", "json"}, want: "dws aitable +table-get --base-id base-1 --table-id table_2 --format json", }, + { + name: "unknown argument fallback", + argv: []string{"dws", "aitable", "unsafe value"}, + want: "dws aitable REPLACE_VALUE", + }, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { From 510b120630c24311fb8942148ff9ccce14ad3503 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 19 Aug 2026 09:31:26 +0800 Subject: [PATCH 235/250] fix(recruit): require job creator identity --- internal/helpers/recruit.go | 13 ++-- internal/helpers/recruit_test.go | 63 ++++++++++++++++++- skills/mono/references/products/recruit.md | 9 +-- .../multi/dingtalk-misc/references/recruit.md | 13 ++-- 4 files changed, 79 insertions(+), 19 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 8152d7a7..aec76b1a 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -379,11 +379,11 @@ func newRecruitJobCreateCommand() *cobra.Command { Interface: recruitMCPInterface(recruitCreateJobTool), Selection: contract.SelectionSpec{ AgentSummary: "使用结构化 JSON 创建招聘职位", - UseWhen: []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、extData；jobNature 固定为 FULL-TIME；创建人和负责人分别使用真实 creatorUserId 与 ownerUserIds"}, + UseWhen: []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、extData、creatorUserId；jobNature 固定为 FULL-TIME；creatorUserId 必须使用真实创建人 userId；ownerUserIds 可选"}, AvoidWhen: []string{"仅查询职位时使用 recruit job list 或 recruit job get"}, Examples: []string{"dws recruit job create --from ./job.json --dry-run --format json"}, }, - Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 校验后原样作为 atsAddJobParam 对象发送；creatorUserId 为创建人 userId，ownerUserIds 为负责人 userId 字符串数组"}}, + Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 校验后原样作为 atsAddJobParam 对象发送；creatorUserId 为必填的创建人 userId，ownerUserIds 为可选的负责人 userId 字符串数组"}}, }, }) } @@ -479,7 +479,7 @@ func loadRecruitJobFile(path string) (any, error) { } func validateRecruitJob(job map[string]any) error { - for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "extData"} { + for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "extData", "creatorUserId"} { value, ok := job[name] if !ok || value == nil || (isString(value) && strings.TrimSpace(value.(string)) == "") { return apperrors.NewValidation(fmt.Sprintf("职位 JSON 缺少必填字段 %s", name)) @@ -552,11 +552,8 @@ func optionalRecruitNumber(values map[string]any, name string) (float64, bool, e } func validateRecruitIdentityFields(job map[string]any) error { - if value, exists := job["creatorUserId"]; exists && value != nil { - creatorUserID, ok := value.(string) - if !ok || strings.TrimSpace(creatorUserID) == "" { - return apperrors.NewValidation("职位 JSON 字段 creatorUserId 必须是非空字符串") - } + if _, ok := job["creatorUserId"].(string); !ok { + return apperrors.NewValidation("职位 JSON 字段 creatorUserId 必须是非空字符串") } if value, exists := job["ownerUserIds"]; exists && value != nil { ownerUserIDs, ok := value.([]any) diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index e7632c28..8c3fd948 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -286,6 +286,64 @@ func TestRecruitCreateValidatesJobFile(t *testing.T) { } } +func TestRecruitCreateRejectsInvalidCreatorBeforeRemoteCall(t *testing.T) { + for _, test := range []struct { + name string + creator string + }{ + {name: "missing", creator: ""}, + {name: "null", creator: `,"creatorUserId":null`}, + {name: "blank", creator: `,"creatorUserId":" "`}, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + path := filepath.Join(t.TempDir(), "job.json") + payload := `{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL-TIME","requiredEdu":6,"extData":{}` + test.creator + `}` + if err := os.WriteFile(path, []byte(payload), 0o600); err != nil { + t.Fatal(err) + } + cmd := prepareRecruitTestCommand(newRecruitJobCreateCommand()) + cmd.Flags().Bool("yes", false, "确认创建") + cmd.SetArgs([]string{"--from", path, "--yes"}) + if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "creatorUserId") { + t.Fatalf("creator validation error = %v, want creatorUserId error", err) + } + if len(caller.calls) != 0 { + t.Fatalf("MCP calls with invalid creator = %d, want 0", len(caller.calls)) + } + }) + } +} + +func TestRecruitCreateAllowsOptionalOwners(t *testing.T) { + for _, test := range []struct { + name string + owner string + }{ + {name: "missing"}, + {name: "null", owner: `,"ownerUserIds":null`}, + {name: "empty array", owner: `,"ownerUserIds":[]`}, + } { + t.Run(test.name, func(t *testing.T) { + caller := withRecruitCaller(t) + path := filepath.Join(t.TempDir(), "job.json") + payload := `{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL-TIME","requiredEdu":6,"extData":{},"creatorUserId":"creator-user-id"` + test.owner + `}` + if err := os.WriteFile(path, []byte(payload), 0o600); err != nil { + t.Fatal(err) + } + cmd := prepareRecruitTestCommand(newRecruitJobCreateCommand()) + cmd.Flags().Bool("yes", false, "确认创建") + cmd.SetArgs([]string{"--from", path, "--yes"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("optional owner create error = %v, want nil", err) + } + if len(caller.calls) != 1 { + t.Fatalf("MCP calls with optional owner = %d, want 1", len(caller.calls)) + } + }) + } +} + func TestRecruitValidationBranches(t *testing.T) { statuses, err := transformRecruitStatuses(" open, ,open,closed ") if err != nil || !reflect.DeepEqual(statuses, []int{1, 3}) { @@ -333,13 +391,16 @@ func TestRecruitValidationBranches(t *testing.T) { {name: "string type", mutate: func(job map[string]any) { job["name"] = 1 }, want: "name 必须是字符串"}, {name: "number type", mutate: func(job map[string]any) { job["requiredEdu"] = "本科" }, want: "requiredEdu 必须是数字"}, {name: "missing ext data", mutate: func(job map[string]any) { delete(job, "extData") }, want: "缺少必填字段 extData"}, + {name: "missing creator", mutate: func(job map[string]any) { delete(job, "creatorUserId") }, want: "缺少必填字段 creatorUserId"}, + {name: "null creator", mutate: func(job map[string]any) { job["creatorUserId"] = nil }, want: "缺少必填字段 creatorUserId"}, {name: "ext data type", mutate: func(job map[string]any) { job["extData"] = "invalid" }, want: "extData 必须是对象"}, {name: "job nature enum", mutate: func(job map[string]any) { job["jobNature"] = "FULL_TIME" }, want: "仅支持 FULL-TIME"}, {name: "education range", mutate: func(job map[string]any) { job["requiredEdu"] = float64(10) }, want: "1 到 9 的整数"}, {name: "salary range", mutate: func(job map[string]any) { job["minSalary"] = float64(40000) }, want: "minSalary 不能大于 maxSalary"}, {name: "min salary type", mutate: func(job map[string]any) { job["minSalary"] = "20000" }, want: "minSalary 必须是数字"}, {name: "salary type", mutate: func(job map[string]any) { job["maxSalary"] = "35000" }, want: "maxSalary 必须是数字"}, - {name: "creator type", mutate: func(job map[string]any) { job["creatorUserId"] = " " }, want: "creatorUserId 必须是非空字符串"}, + {name: "creator type", mutate: func(job map[string]any) { job["creatorUserId"] = " " }, want: "缺少必填字段 creatorUserId"}, + {name: "creator non-string", mutate: func(job map[string]any) { job["creatorUserId"] = float64(123) }, want: "creatorUserId 必须是非空字符串"}, {name: "owners type", mutate: func(job map[string]any) { job["ownerUserIds"] = "owner-user-id" }, want: "ownerUserIds 必须是字符串数组"}, {name: "owner item", mutate: func(job map[string]any) { job["ownerUserIds"] = []any{""} }, want: "ownerUserIds 只能包含非空字符串"}, {name: "campus type", mutate: func(job map[string]any) { job["campus"] = "false" }, want: "campus 必须是布尔值"}, diff --git a/skills/mono/references/products/recruit.md b/skills/mono/references/products/recruit.md index 2e035201..93502d4c 100644 --- a/skills/mono/references/products/recruit.md +++ b/skills/mono/references/products/recruit.md @@ -24,14 +24,15 @@ dws recruit job create --from ./job.json --dry-run --format json dws recruit job create --from ./job.json --format json ``` -JSON 必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`。 +JSON 必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`、 +`creatorUserId`。 `jobNature` 当前固定为 `FULL-TIME`；学历枚举为 1小学、2初中、3高中、4中专、 5大专、6本科、7硕士、8博士、9其他。`minSalary`、`maxSalary` 可选；两者同时 提供时最低薪资不得高于最高薪资。 -职位对象应显式包含真实的 `creatorUserId` 和 `ownerUserIds`；前者是当前创建人 -userId，后者是负责人 userId 的 JSON 字符串数组。所有 userId 必须来自同一 profile -下的真实通讯录结果，禁止猜测。`extData.headCount` 范围 1–999，薪资月份范围 +`creatorUserId` 是当前创建人 userId，必须来自同一 profile 下的真实通讯录结果。 +`ownerUserIds` 可选；提供时是负责人 userId 的 JSON 字符串数组，也必须使用真实 +通讯录结果。禁止猜测任何 userId。`extData.headCount` 范围 1–999，薪资月份范围 12–24；提供地址时必须包含地点名、详细地址和可信的经纬度。 文件只写职位对象，不要添加 MCP 信封字段 `atsAddJobParam`、`corpId`、`bizCode` diff --git a/skills/multi/dingtalk-misc/references/recruit.md b/skills/multi/dingtalk-misc/references/recruit.md index 36827e56..2ed44b96 100644 --- a/skills/multi/dingtalk-misc/references/recruit.md +++ b/skills/multi/dingtalk-misc/references/recruit.md @@ -37,14 +37,14 @@ dws recruit job get --job-id JOB_ID --format json ## 创建职位 创建是非幂等远端写入。先准备只包含职位对象的 UTF-8 JSON 文件，并用 -`--dry-run` 检查完整调用；向用户展示职位名称、性质、薪资、创建人和负责人，取得 +`--dry-run` 检查完整调用；向用户展示职位名称、性质、薪资、创建人和负责人（如有），取得 明确确认后，交由 CLI 的确认流程执行实际创建。不要在存储示例中加入确认绕过参数。 -创建人和负责人必须来自同一 profile 下的真实通讯录结果，不得猜测或复用其他组织的 -userId。`creatorUserId` 使用当前操作者的 userId；`ownerUserIds` 是负责人 userId 的 -JSON 字符串数组。用户说“负责人是我”时先运行 +`creatorUserId` 是必填字段，必须使用同一 profile 下当前操作者的真实 userId，不得 +猜测或复用其他组织的 userId。`ownerUserIds` 是可选的负责人 userId JSON 字符串数组； +提供负责人时同样必须使用真实通讯录结果。用户说“负责人是我”时先运行 `dws contact user get-self --format json` 取得当前 userId；用户指定其他负责人时按 -通讯录 Skill 解析唯一 userId。未指定负责人时先向用户确认，不要静默省略或默认选人。 +通讯录 Skill 解析唯一 userId。未指定负责人时允许省略 `ownerUserIds`，不要默认选人。 ```bash dws recruit job create --from ./job.json --dry-run --format json @@ -72,7 +72,8 @@ dws recruit job create --from ./job.json --format json } ``` -必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`。 +必填字段为 `name`、`description`、`jobNature`、`requiredEdu`、`extData`、 +`creatorUserId`；`ownerUserIds` 可选。 `jobNature` 当前固定为 `FULL-TIME`；`requiredEdu` 为 1–9 的整数（1小学、2初中、 3高中、4中专、5大专、6本科、7硕士、8博士、9其他）。`minSalary` 与 `maxSalary` 可选；两者同时提供时最低薪资不得高于最高薪资。 From 0793238d47a5641ab49a6e5036128b9c474b57a1 Mon Sep 17 00:00:00 2001 From: chichuan Date: Wed, 19 Aug 2026 09:58:00 +0800 Subject: [PATCH 236/250] docs: seal changelog for v1.0.59-beta.3 --- ...1006-aitable-pagination-minutes-unshare.md | 0 .../928-chat-bot-group-reply.md | 0 .../960-doc-readback-verification.md | 0 .../1.0.59-beta.3}/aitable-param-aliases.md | 0 .../1.0.59-beta.3}/aitable-record-stats.md | 0 .../calendar-event-share-info.md | 0 .../calendar-todo-shortcut-alignment.md | 0 .../chat-sender-identity-contract.md | 0 .../doc-drive-description-scope.md | 0 .../doc-sheet-comment-lifecycle.md | 0 .../sheet-source-range-dropdowns.md | 0 .../windows-event-bus-lifecycle.md | 0 CHANGELOG.md | 55 +++++++++++++++++++ 13 files changed, 55 insertions(+) rename .changes/{ => released/1.0.59-beta.3}/1006-aitable-pagination-minutes-unshare.md (100%) rename .changes/{ => released/1.0.59-beta.3}/928-chat-bot-group-reply.md (100%) rename .changes/{ => released/1.0.59-beta.3}/960-doc-readback-verification.md (100%) rename .changes/{ => released/1.0.59-beta.3}/aitable-param-aliases.md (100%) rename .changes/{ => released/1.0.59-beta.3}/aitable-record-stats.md (100%) rename .changes/{ => released/1.0.59-beta.3}/calendar-event-share-info.md (100%) rename .changes/{ => released/1.0.59-beta.3}/calendar-todo-shortcut-alignment.md (100%) rename .changes/{ => released/1.0.59-beta.3}/chat-sender-identity-contract.md (100%) rename .changes/{ => released/1.0.59-beta.3}/doc-drive-description-scope.md (100%) rename .changes/{ => released/1.0.59-beta.3}/doc-sheet-comment-lifecycle.md (100%) rename .changes/{ => released/1.0.59-beta.3}/sheet-source-range-dropdowns.md (100%) rename .changes/{ => released/1.0.59-beta.3}/windows-event-bus-lifecycle.md (100%) diff --git a/.changes/1006-aitable-pagination-minutes-unshare.md b/.changes/released/1.0.59-beta.3/1006-aitable-pagination-minutes-unshare.md similarity index 100% rename from .changes/1006-aitable-pagination-minutes-unshare.md rename to .changes/released/1.0.59-beta.3/1006-aitable-pagination-minutes-unshare.md diff --git a/.changes/928-chat-bot-group-reply.md b/.changes/released/1.0.59-beta.3/928-chat-bot-group-reply.md similarity index 100% rename from .changes/928-chat-bot-group-reply.md rename to .changes/released/1.0.59-beta.3/928-chat-bot-group-reply.md diff --git a/.changes/960-doc-readback-verification.md b/.changes/released/1.0.59-beta.3/960-doc-readback-verification.md similarity index 100% rename from .changes/960-doc-readback-verification.md rename to .changes/released/1.0.59-beta.3/960-doc-readback-verification.md diff --git a/.changes/aitable-param-aliases.md b/.changes/released/1.0.59-beta.3/aitable-param-aliases.md similarity index 100% rename from .changes/aitable-param-aliases.md rename to .changes/released/1.0.59-beta.3/aitable-param-aliases.md diff --git a/.changes/aitable-record-stats.md b/.changes/released/1.0.59-beta.3/aitable-record-stats.md similarity index 100% rename from .changes/aitable-record-stats.md rename to .changes/released/1.0.59-beta.3/aitable-record-stats.md diff --git a/.changes/calendar-event-share-info.md b/.changes/released/1.0.59-beta.3/calendar-event-share-info.md similarity index 100% rename from .changes/calendar-event-share-info.md rename to .changes/released/1.0.59-beta.3/calendar-event-share-info.md diff --git a/.changes/calendar-todo-shortcut-alignment.md b/.changes/released/1.0.59-beta.3/calendar-todo-shortcut-alignment.md similarity index 100% rename from .changes/calendar-todo-shortcut-alignment.md rename to .changes/released/1.0.59-beta.3/calendar-todo-shortcut-alignment.md diff --git a/.changes/chat-sender-identity-contract.md b/.changes/released/1.0.59-beta.3/chat-sender-identity-contract.md similarity index 100% rename from .changes/chat-sender-identity-contract.md rename to .changes/released/1.0.59-beta.3/chat-sender-identity-contract.md diff --git a/.changes/doc-drive-description-scope.md b/.changes/released/1.0.59-beta.3/doc-drive-description-scope.md similarity index 100% rename from .changes/doc-drive-description-scope.md rename to .changes/released/1.0.59-beta.3/doc-drive-description-scope.md diff --git a/.changes/doc-sheet-comment-lifecycle.md b/.changes/released/1.0.59-beta.3/doc-sheet-comment-lifecycle.md similarity index 100% rename from .changes/doc-sheet-comment-lifecycle.md rename to .changes/released/1.0.59-beta.3/doc-sheet-comment-lifecycle.md diff --git a/.changes/sheet-source-range-dropdowns.md b/.changes/released/1.0.59-beta.3/sheet-source-range-dropdowns.md similarity index 100% rename from .changes/sheet-source-range-dropdowns.md rename to .changes/released/1.0.59-beta.3/sheet-source-range-dropdowns.md diff --git a/.changes/windows-event-bus-lifecycle.md b/.changes/released/1.0.59-beta.3/windows-event-bus-lifecycle.md similarity index 100% rename from .changes/windows-event-bus-lifecycle.md rename to .changes/released/1.0.59-beta.3/windows-event-bus-lifecycle.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9afe33b3..728d8f7b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,61 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +## [1.0.59-beta.3] - 2026-08-19 + +### Added + +- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message. + +- **AI Table server-side statistics** — adds `dws aitable record stats` for + ungrouped record-set metrics through `query_records_stats`, plus `dws aitable + record group-stats` for grouped, distinct, and advanced aggregation through + `query_stats`; both commands validate their JSON aggregation contracts before + dispatch. + +- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`. + +- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented + entries with lark-cli where the DingTalk backend supports equivalent + semantics, rejects malformed or missing collections instead of returning + false empty success, preserves truthful pagination, and requires stable + identifiers plus read-back or explicit terminal receipts for writes. Adds + deterministic contract coverage, a PII-safe live E2E runner, and a sanitized + capability review with documented platform boundaries. + +- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`, + `comment resolve`, `comment restore`, and the lightweight + `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share + the same `doc-comment` MCP capabilities; batch queries preserve input order + for repeated `topicId:commentKey` references, while reaction replies require + DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji. + +- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported. +- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads. + +### Changed + +- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked. + +- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior. + +### Fixed + +- **Aitable pagination and Minutes unshare verification** (#1006) — keeps + record queries on the service's 20-record page boundary so multi-page reads + and mutation readbacks no longer report false retryable failures, preserves + `totalCount` when supplied, validates `--dry-run` plans before transport, + follows active deletion readback continuations before proving absence, and + rejects Minutes unshare success until the listening note exists and the + service acknowledges the exact task and member targets. + +- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result. + +- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior. + +- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails. + + ## [1.0.59-beta.2] - 2026-08-17 ### Added From d70e6b85b6ec54e5cca02aadc1ab7efe96cdf2e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 10:09:37 +0800 Subject: [PATCH 237/250] test(calendar): isolate exhaustive alias payload coverage --- .../param_alias_payload_equivalence_test.go | 266 +++++++++++------- 1 file changed, 168 insertions(+), 98 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index cfe5224c..d4272e40 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -5,6 +5,8 @@ package app import ( "errors" + "os" + "os/exec" "reflect" "strings" "testing" @@ -17,6 +19,8 @@ import ( const ( appFixtureCurrentDOpenID = "DAAAAAAAAAAAiE" appFixtureCurrentDOpenID2 = "DAQEBAQEBAQEiE" + + paramAliasCalendarPayloadChildEnv = "DWS_TEST_CALENDAR_PARAM_ALIAS_PAYLOAD_CHILD" ) // paramAliasCompleteCommands is deliberately keyed by the exact reviewed @@ -562,82 +566,6 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("aitable workflow run", "table"): true, // Table ID concept alias on a confirmed write paramAliasPayloadCaseKey("attendance check result", "user-ids"): true, // list-valued concept alias paramAliasPayloadCaseKey("calendar event list", "date"): true, // time concept alias - paramAliasPayloadCaseKey("calendar +agenda", "from"): true, - paramAliasPayloadCaseKey("calendar +agenda", "to"): true, - paramAliasPayloadCaseKey("calendar +agenda", "max-results"): true, - paramAliasPayloadCaseKey("calendar +agenda", "next-cursor"): true, - paramAliasPayloadCaseKey("calendar +agenda", "calendar-book-id"): true, - paramAliasPayloadCaseKey("calendar +attendee-list", "event-id"): true, - paramAliasPayloadCaseKey("calendar +attendee-list", "calendar-book-id"): true, - paramAliasPayloadCaseKey("calendar +book", "summary"): true, - paramAliasPayloadCaseKey("calendar +book", "attendee-names"): true, - paramAliasPayloadCaseKey("calendar +book-search", "keyword"): true, - paramAliasPayloadCaseKey("calendar +book-search", "search"): true, - paramAliasPayloadCaseKey("calendar +book-search", "name"): true, - paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"): true, - paramAliasPayloadCaseKey("calendar +cancel-event", "id"): true, - paramAliasPayloadCaseKey("calendar +free", "name"): true, - paramAliasPayloadCaseKey("calendar +free-slots", "start-hour"): true, - paramAliasPayloadCaseKey("calendar +free-slots", "end-hour"): true, - paramAliasPayloadCaseKey("calendar +free-slots", "day-offset"): true, - paramAliasPayloadCaseKey("calendar +freebusy", "user-ids"): true, - paramAliasPayloadCaseKey("calendar +freebusy", "room-ids"): true, - paramAliasPayloadCaseKey("calendar +freebusy", "room-id"): true, - paramAliasPayloadCaseKey("calendar +my-free", "from"): true, - paramAliasPayloadCaseKey("calendar +my-free", "to"): true, - paramAliasPayloadCaseKey("calendar +invite", "id"): true, - paramAliasPayloadCaseKey("calendar +invite", "participant-names"): true, - paramAliasPayloadCaseKey("calendar +reschedule", "id"): true, - paramAliasPayloadCaseKey("calendar +reschedule", "from"): true, - paramAliasPayloadCaseKey("calendar +reschedule", "to"): true, - paramAliasPayloadCaseKey("calendar +room-groups", "page-size"): true, - paramAliasPayloadCaseKey("calendar +room-groups", "page-index"): true, - paramAliasPayloadCaseKey("calendar +room-search", "query"): true, - paramAliasPayloadCaseKey("calendar +suggest-time", "duration-minutes"): true, - paramAliasPayloadCaseKey("calendar +suggest-time", "attendee-names"): true, - paramAliasPayloadCaseKey("calendar +conflicts", "day-offset"): true, - paramAliasPayloadCaseKey("calendar busy search", "room-id"): true, - paramAliasPayloadCaseKey("calendar event create", "reminder-minutes"): true, - paramAliasPayloadCaseKey("calendar event create", "tz"): true, - paramAliasPayloadCaseKey("calendar event create", "room-id"): true, - paramAliasPayloadCaseKey("calendar event respond", "response-status"): true, - paramAliasPayloadCaseKey("calendar event suggest", "duration-minutes"): true, - paramAliasPayloadCaseKey("calendar event update", "tz"): true, - paramAliasPayloadCaseKey("calendar room add", "room-id"): true, - paramAliasPayloadCaseKey("calendar room delete", "room-id"): true, - paramAliasPayloadCaseKey("calendar room search", "room-group-id"): true, - paramAliasPayloadCaseKey("calendar +create", "summary"): true, - paramAliasPayloadCaseKey("calendar +create", "description"): true, - paramAliasPayloadCaseKey("calendar +create", "user-ids"): true, - paramAliasPayloadCaseKey("calendar +create", "room-ids"): true, - paramAliasPayloadCaseKey("calendar +create", "room-id"): true, - paramAliasPayloadCaseKey("calendar +create", "calendar-book-id"): true, - paramAliasPayloadCaseKey("calendar +create", "to"): true, - paramAliasPayloadCaseKey("calendar +create", "from"): true, - paramAliasPayloadCaseKey("calendar +get", "event-id"): true, - paramAliasPayloadCaseKey("calendar +get", "calendar-book-id"): true, - paramAliasPayloadCaseKey("calendar +room-find", "from"): true, - paramAliasPayloadCaseKey("calendar +room-find", "to"): true, - paramAliasPayloadCaseKey("calendar +room-find", "page-size"): true, - paramAliasPayloadCaseKey("calendar +room-find", "page-index"): true, - paramAliasPayloadCaseKey("calendar +room-find", "room-group-id"): true, - paramAliasPayloadCaseKey("calendar +room-find", "query"): true, - paramAliasPayloadCaseKey("calendar +rsvp", "event-id"): true, - paramAliasPayloadCaseKey("calendar +rsvp", "response-status"): true, - paramAliasPayloadCaseKey("calendar +search-event", "keyword"): true, - paramAliasPayloadCaseKey("calendar +search-event", "from"): true, - paramAliasPayloadCaseKey("calendar +search-event", "to"): true, - paramAliasPayloadCaseKey("calendar +search-event", "next-cursor"): true, - paramAliasPayloadCaseKey("calendar +search-event", "max-results"): true, - paramAliasPayloadCaseKey("calendar +suggestion", "user-ids"): true, - paramAliasPayloadCaseKey("calendar +suggestion", "duration-minutes"): true, - paramAliasPayloadCaseKey("calendar +suggestion", "tz"): true, - paramAliasPayloadCaseKey("calendar +update", "event-id"): true, - paramAliasPayloadCaseKey("calendar +update", "from"): true, - paramAliasPayloadCaseKey("calendar +update", "summary"): true, - paramAliasPayloadCaseKey("calendar +update", "description"): true, - paramAliasPayloadCaseKey("calendar +update", "add-user-ids"): true, - paramAliasPayloadCaseKey("calendar +update", "remove-user-ids"): true, paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"): true, // scoped IM identifier alias paramAliasPayloadCaseKey("contact user profile get", "user-id"): true, // native compatibility flag paramAliasPayloadCaseKey("devdoc article search", "current-page"): true, // command override @@ -672,6 +600,91 @@ var paramAliasRepresentativePayloadCases = map[string]bool{ paramAliasPayloadCaseKey("report list", "from-date"): true, // date-range concept alias } +// paramAliasCalendarPayloadCases keeps the full reviewed Calendar expansion +// separate from the long-lived app-c race process. Each case still executes +// both canonical and alias argv through the real PreParse/Cobra path and +// compares the final captured transport calls; the owning top-level test runs +// these allocations in a short-lived race-instrumented subprocess so all Root +// registrations are released together when that process exits. +var paramAliasCalendarPayloadCases = map[string]bool{ + paramAliasPayloadCaseKey("calendar +agenda", "from"): true, + paramAliasPayloadCaseKey("calendar +agenda", "to"): true, + paramAliasPayloadCaseKey("calendar +agenda", "max-results"): true, + paramAliasPayloadCaseKey("calendar +agenda", "next-cursor"): true, + paramAliasPayloadCaseKey("calendar +agenda", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +attendee-list", "event-id"): true, + paramAliasPayloadCaseKey("calendar +attendee-list", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +book", "summary"): true, + paramAliasPayloadCaseKey("calendar +book", "attendee-names"): true, + paramAliasPayloadCaseKey("calendar +book-search", "keyword"): true, + paramAliasPayloadCaseKey("calendar +book-search", "search"): true, + paramAliasPayloadCaseKey("calendar +book-search", "name"): true, + paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"): true, + paramAliasPayloadCaseKey("calendar +cancel-event", "id"): true, + paramAliasPayloadCaseKey("calendar +free", "name"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "start-hour"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "end-hour"): true, + paramAliasPayloadCaseKey("calendar +free-slots", "day-offset"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "room-ids"): true, + paramAliasPayloadCaseKey("calendar +freebusy", "room-id"): true, + paramAliasPayloadCaseKey("calendar +my-free", "from"): true, + paramAliasPayloadCaseKey("calendar +my-free", "to"): true, + paramAliasPayloadCaseKey("calendar +invite", "id"): true, + paramAliasPayloadCaseKey("calendar +invite", "participant-names"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "id"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "from"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "to"): true, + paramAliasPayloadCaseKey("calendar +room-groups", "page-size"): true, + paramAliasPayloadCaseKey("calendar +room-groups", "page-index"): true, + paramAliasPayloadCaseKey("calendar +room-search", "query"): true, + paramAliasPayloadCaseKey("calendar +suggest-time", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar +suggest-time", "attendee-names"): true, + paramAliasPayloadCaseKey("calendar +conflicts", "day-offset"): true, + paramAliasPayloadCaseKey("calendar busy search", "room-id"): true, + paramAliasPayloadCaseKey("calendar event create", "reminder-minutes"): true, + paramAliasPayloadCaseKey("calendar event create", "tz"): true, + paramAliasPayloadCaseKey("calendar event create", "room-id"): true, + paramAliasPayloadCaseKey("calendar event respond", "response-status"): true, + paramAliasPayloadCaseKey("calendar event suggest", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar event update", "tz"): true, + paramAliasPayloadCaseKey("calendar room add", "room-id"): true, + paramAliasPayloadCaseKey("calendar room delete", "room-id"): true, + paramAliasPayloadCaseKey("calendar room search", "room-group-id"): true, + paramAliasPayloadCaseKey("calendar +create", "summary"): true, + paramAliasPayloadCaseKey("calendar +create", "description"): true, + paramAliasPayloadCaseKey("calendar +create", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +create", "room-ids"): true, + paramAliasPayloadCaseKey("calendar +create", "room-id"): true, + paramAliasPayloadCaseKey("calendar +create", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +create", "to"): true, + paramAliasPayloadCaseKey("calendar +create", "from"): true, + paramAliasPayloadCaseKey("calendar +get", "event-id"): true, + paramAliasPayloadCaseKey("calendar +get", "calendar-book-id"): true, + paramAliasPayloadCaseKey("calendar +room-find", "from"): true, + paramAliasPayloadCaseKey("calendar +room-find", "to"): true, + paramAliasPayloadCaseKey("calendar +room-find", "page-size"): true, + paramAliasPayloadCaseKey("calendar +room-find", "page-index"): true, + paramAliasPayloadCaseKey("calendar +room-find", "room-group-id"): true, + paramAliasPayloadCaseKey("calendar +room-find", "query"): true, + paramAliasPayloadCaseKey("calendar +rsvp", "event-id"): true, + paramAliasPayloadCaseKey("calendar +rsvp", "response-status"): true, + paramAliasPayloadCaseKey("calendar +search-event", "keyword"): true, + paramAliasPayloadCaseKey("calendar +search-event", "from"): true, + paramAliasPayloadCaseKey("calendar +search-event", "to"): true, + paramAliasPayloadCaseKey("calendar +search-event", "next-cursor"): true, + paramAliasPayloadCaseKey("calendar +search-event", "max-results"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "user-ids"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "tz"): true, + paramAliasPayloadCaseKey("calendar +update", "event-id"): true, + paramAliasPayloadCaseKey("calendar +update", "from"): true, + paramAliasPayloadCaseKey("calendar +update", "summary"): true, + paramAliasPayloadCaseKey("calendar +update", "description"): true, + paramAliasPayloadCaseKey("calendar +update", "add-user-ids"): true, + paramAliasPayloadCaseKey("calendar +update", "remove-user-ids"): true, +} + func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) { concepts, err := cli.LoadParamConcepts() if err != nil { @@ -705,28 +718,7 @@ func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepres } executedRepresentatives[caseKey] = true t.Run(fixture.Command+"/"+fixture.Emitted, func(t *testing.T) { - - canonicalCaller := ¶mAliasCaptureCaller{} - _, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...) - if canonicalErr != nil { - t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls) - } - if len(canonicalCaller.calls) == 0 { - t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs) - } - - aliasCaller := ¶mAliasCaptureCaller{} - ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...) - if aliasErr != nil { - t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls) - } - if ctx == nil { - t.Fatal("complete alias command skipped PreParse") - } - normalizeParamAliasVolatileDefaults(fixture.Command, canonicalCaller, aliasCaller) - if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) { - t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls) - } + assertParamAliasFinalPayloadEquivalent(t, fixture.Command, canonicalArgs, aliasArgs) }) } @@ -756,6 +748,84 @@ func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepres } } +func TestReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) { + if os.Getenv(paramAliasCalendarPayloadChildEnv) != "1" { + command := exec.Command( + os.Args[0], + "-test.run=^TestReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads$", + "-test.count=1", + "-test.timeout=5m", + ) + command.Env = append(os.Environ(), paramAliasCalendarPayloadChildEnv+"=1") + output, err := command.CombinedOutput() + if err != nil { + t.Fatalf("Calendar param-alias payload subprocess failed: %v\n%s", err, strings.TrimSpace(string(output))) + } + return + } + + concepts, err := cli.LoadParamConcepts() + if err != nil { + t.Fatalf("LoadParamConcepts() error = %v", err) + } + + executed := make(map[string]bool) + for _, fixture := range concepts.Fixture { + caseKey := paramAliasPayloadCaseKey(fixture.Command, fixture.Emitted) + if !paramAliasCalendarPayloadCases[caseKey] { + continue + } + executed[caseKey] = true + fixture := fixture + t.Run(fixture.Command+"/"+fixture.Emitted, func(t *testing.T) { + complete, ok := paramAliasCompleteCommand(fixture.Command, fixture.Expect) + if !ok { + t.Fatal("reviewed Calendar alias has no complete-command E2E template") + } + canonicalArgs := append([]string(nil), complete...) + aliasArgs, replacements := replaceLongFlag(canonicalArgs, fixture.Expect, fixture.Emitted) + if replacements != 1 { + t.Fatalf("complete Calendar command must contain canonical --%s exactly once; replacements=%d args=%v", fixture.Expect, replacements, canonicalArgs) + } + assertParamAliasFinalPayloadEquivalent(t, fixture.Command, canonicalArgs, aliasArgs) + }) + } + + for caseKey := range paramAliasCalendarPayloadCases { + if !executed[caseKey] { + t.Errorf("Calendar final-payload case %q has no active reviewed fixture", caseKey) + } + } + if len(executed) != len(paramAliasCalendarPayloadCases) { + t.Fatalf("Calendar final-payload coverage = %d, want %d", len(executed), len(paramAliasCalendarPayloadCases)) + } +} + +func assertParamAliasFinalPayloadEquivalent(t *testing.T, command string, canonicalArgs, aliasArgs []string) { + t.Helper() + canonicalCaller := ¶mAliasCaptureCaller{} + _, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...) + if canonicalErr != nil { + t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls) + } + if len(canonicalCaller.calls) == 0 { + t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs) + } + + aliasCaller := ¶mAliasCaptureCaller{} + ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...) + if aliasErr != nil { + t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls) + } + if ctx == nil { + t.Fatal("complete alias command skipped PreParse") + } + normalizeParamAliasVolatileDefaults(command, canonicalCaller, aliasCaller) + if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) { + t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls) + } +} + func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) { activeAliases := 0 for _, test := range paramAliasNewIMCases { From 6c895c23ed63b667c5e21b846624a41464c0cfb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 19 Aug 2026 10:17:18 +0800 Subject: [PATCH 238/250] fix(recruit): validate pagination cursor responses --- internal/helpers/recruit.go | 45 ++++++++++++++++++++------------ internal/helpers/recruit_test.go | 42 ++++++++++++++++++++++------- 2 files changed, 62 insertions(+), 25 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index aec76b1a..b8f68115 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -285,23 +285,17 @@ func recruitListResultData(data any) (any, *output.Meta, error) { return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore") } nextToken := "" - if raw, exists := object["nextCursor"]; exists && raw != nil { - switch value := raw.(type) { - case string: - nextToken = strings.TrimSpace(value) - case json.Number: - nextToken = string(value) - case float64: - nextToken = strconv.FormatFloat(value, 'f', -1, 64) - default: - return nil, nil, fmt.Errorf("list_jobs 的 nextCursor 必须是字符串或数字") + if hasMore { + if raw, exists := object["nextCursor"]; exists && raw != nil { + var err error + nextToken, err = normalizeRecruitNextCursor(raw) + if err != nil { + return nil, nil, err + } + } + if nextToken == "" { + return nil, nil, fmt.Errorf("list_jobs 返回 hasMore=true 但缺少 nextCursor") } - } - if hasMore && nextToken == "" { - return nil, nil, fmt.Errorf("list_jobs 返回 hasMore=true 但缺少 nextCursor") - } - if !hasMore { - nextToken = "" } clean := make(map[string]any, len(object)-2) for key, value := range object { @@ -324,6 +318,25 @@ func recruitListResultData(data any) (any, *output.Meta, error) { return clean, meta, nil } +func normalizeRecruitNextCursor(raw any) (string, error) { + var value string + switch cursor := raw.(type) { + case string: + value = strings.TrimSpace(cursor) + case json.Number: + value = string(cursor) + case float64: + value = strconv.FormatFloat(cursor, 'f', -1, 64) + default: + return "", fmt.Errorf("list_jobs 的 nextCursor 必须是字符串或数字") + } + parsed, err := strconv.ParseInt(value, 10, 64) + if err != nil || parsed < 0 { + return "", fmt.Errorf("list_jobs 的 nextCursor 必须是可回填的非负十进制 int64 游标") + } + return strconv.FormatInt(parsed, 10), nil +} + func newRecruitJobGetCommand() *cobra.Command { return NewLeafCommand(LeafSpec{ Use: "get", diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 8c3fd948..83b17f15 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -497,6 +497,9 @@ func TestRecruitListResultData(t *testing.T) { {name: "missing hasMore", data: map[string]any{}, want: "缺少布尔字段 hasMore"}, {name: "invalid cursor", data: map[string]any{"hasMore": true, "nextCursor": true}, want: "必须是字符串或数字"}, {name: "missing cursor", data: map[string]any{"hasMore": true}, want: "缺少 nextCursor"}, + {name: "exponent cursor", data: map[string]any{"hasMore": true, "nextCursor": json.Number("1e3")}, want: "非负十进制 int64"}, + {name: "decimal cursor", data: map[string]any{"hasMore": true, "nextCursor": json.Number("1.5")}, want: "非负十进制 int64"}, + {name: "overflow cursor", data: map[string]any{"hasMore": true, "nextCursor": json.Number("9223372036854775808")}, want: "非负十进制 int64"}, } { t.Run(test.name, func(t *testing.T) { if _, _, err := recruitListResultData(test.data); err == nil || !strings.Contains(err.Error(), test.want) { @@ -520,6 +523,13 @@ func TestRecruitListResultData(t *testing.T) { t.Fatalf("clean data = %#v", clean) } + _, normalizedCursor, err := recruitListResultData(map[string]any{ + "jobs": []any{}, "hasMore": true, "nextCursor": "00012", + }) + if err != nil || normalizedCursor.Pagination.NextToken != "12" { + t.Fatalf("normalized cursor meta = %#v, err = %v", normalizedCursor, err) + } + _, terminal, err := recruitListResultData(map[string]any{"jobs": []any{}, "hasMore": false, "nextCursor": "ignored"}) if err != nil || !terminal.Pagination.EndpointExhausted || terminal.Pagination.NextToken != "" { t.Fatalf("terminal meta = %#v, err = %v", terminal, err) @@ -789,15 +799,29 @@ func TestRecruitResultCallClassifiesBusinessAndMalformedFailures(t *testing.T) { } func TestRecruitResultCallRejectsInconsistentPagination(t *testing.T) { - caller := withRecruitCaller(t) - caller.text = `{"jobs":[],"hasMore":true}` - cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) - result, err := recruitResultCall(cmd, recruitListJobsTool, map[string]any{"size": 20}) - if err != nil { - t.Fatal(err) - } - if result.Outcome() != output.OutcomeFailure { - t.Fatalf("outcome = %s, want failure", result.Outcome()) + for _, response := range []string{ + `{"jobs":[],"hasMore":true}`, + `{"jobs":[],"hasMore":true,"nextCursor":1e3}`, + `{"jobs":[],"hasMore":true,"nextCursor":1.5}`, + `{"jobs":[],"hasMore":true,"nextCursor":9223372036854775808}`, + } { + t.Run(response, func(t *testing.T) { + caller := withRecruitCaller(t) + caller.text = response + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + result, err := recruitResultCall(cmd, recruitListJobsTool, map[string]any{"size": 20}) + if err != nil { + t.Fatal(err) + } + envelope, err := output.EnvelopeFromResult(result) + if err != nil { + t.Fatal(err) + } + if envelope.Outcome != output.OutcomeFailure || envelope.Error == nil || + envelope.Error.Subtype != "invalid_response" { + t.Fatalf("envelope = %#v, want invalid_response failure", envelope) + } + }) } } From 66516755e6c4fbf127545e30d1fb3fa98f485436 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 19 Aug 2026 02:39:35 +0000 Subject: [PATCH 239/250] chore: update beta formula for v1.0.59-beta.3 [skip ci] --- Formula/dingtalk-workspace-cli-beta.rb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Formula/dingtalk-workspace-cli-beta.rb b/Formula/dingtalk-workspace-cli-beta.rb index 1d76aa1f..90ab9635 100644 --- a/Formula/dingtalk-workspace-cli-beta.rb +++ b/Formula/dingtalk-workspace-cli-beta.rb @@ -1,33 +1,33 @@ class DingtalkWorkspaceCliBeta < Formula desc "Automate DingTalk workspace tasks from the terminal (beta channel)" homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli" - version "1.0.59-beta.2" + version "1.0.59-beta.3" license "Apache-2.0" keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli" on_macos do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-arm64.tar.gz" - sha256 "7f11218d3222f3e93c3b1e94b3a004c061eb0a297b206447ea95fe6b2b1ec674" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-arm64.tar.gz" + sha256 "9c99adcefd9104368eb443f0a1b4af8e7aceaa1ffdd4462e486854c1692bb6ce" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-amd64.tar.gz" - sha256 "72f06a334cf29d23123639fabe13bf2951765066136e47ccc6453667c382f8c2" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-amd64.tar.gz" + sha256 "f5cc8efb1f982d68ae549190fd683292359c2ab542b532fa52bb35e6b5c049af" end end on_linux do if Hardware::CPU.arm? - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-arm64.tar.gz" - sha256 "3edbfabb7718b53914a2d9efe7b1152e9ebd70765ff0b6f19ad3125e4a2458ed" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-arm64.tar.gz" + sha256 "7a4efd04b417ce8013b1e431274b396179958da244164f59974358ba327ff093" else - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-amd64.tar.gz" - sha256 "e1c610070a9c1b3763656cbd53c818290f199097adc07cb9fe629ed765c5e1e0" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-amd64.tar.gz" + sha256 "90181e8f2e9010c1943a5773c3d45d7d3ac85d6bc93e18a9aaa7c69909e553d7" end end resource "skills" do - url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-skills.zip" - sha256 "aa2854651eaa2c857b526aaec73fd1358d31b11999fe7fd3e99e5060b2522a1f" + url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-skills.zip" + sha256 "e7028914a4a826af9b18ed4922d68fa8f279473817fed4f305465bc8a7aad363" end def install From 502317db68fbd81b678766b24c9ea43641c8ea52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 10:47:50 +0800 Subject: [PATCH 240/250] test(calendar): cover suggestion time aliases --- internal/app/param_alias_payload_equivalence_test.go | 4 +++- internal/cli/param_concepts.json | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index d4272e40..c212ccb3 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -70,7 +70,7 @@ var paramAliasCompleteCommands = map[string][]string{ "calendar +rsvp": {"calendar", "+rsvp", "--event", "event-1", "--status", "accept", "--calendar-id", "primary", "--yes"}, "calendar +search-event": {"calendar", "+search-event", "--query", "fixture", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, "calendar +suggest-time": {"calendar", "+suggest-time", "--with", "Fixture User", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, - "calendar +suggestion": {"calendar", "+suggestion", "--users", "user-1,user-2", "--duration", "30", "--timezone", "Asia/Shanghai"}, + "calendar +suggestion": {"calendar", "+suggestion", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"}, "calendar +update": {"calendar", "+update", "--event", "event-1", "--title", "Fixture Updated Meeting", "--desc", "fixture updated description", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--add-attendees", "user-2", "--remove-attendees", "user-1", "--yes"}, "calendar busy search": {"calendar", "busy", "search", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, "calendar event create": {"calendar", "event", "create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--remind-minutes", "15", "--timezone", "Asia/Shanghai", "--rooms", "room-1,room-2", "--yes"}, @@ -676,6 +676,8 @@ var paramAliasCalendarPayloadCases = map[string]bool{ paramAliasPayloadCaseKey("calendar +search-event", "max-results"): true, paramAliasPayloadCaseKey("calendar +suggestion", "user-ids"): true, paramAliasPayloadCaseKey("calendar +suggestion", "duration-minutes"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "from"): true, + paramAliasPayloadCaseKey("calendar +suggestion", "to"): true, paramAliasPayloadCaseKey("calendar +suggestion", "tz"): true, paramAliasPayloadCaseKey("calendar +update", "event-id"): true, paramAliasPayloadCaseKey("calendar +update", "from"): true, diff --git a/internal/cli/param_concepts.json b/internal/cli/param_concepts.json index 6aae2d0e..3a2f9a8b 100644 --- a/internal/cli/param_concepts.json +++ b/internal/cli/param_concepts.json @@ -832,6 +832,8 @@ {"command":"calendar +search-event","emitted":"page","expect":"did-you-mean:blocked","via":"guard:cursor-vs-page-index"}, {"command":"calendar +suggestion","emitted":"user-ids","expect":"users","via":"concept:user_ids"}, {"command":"calendar +suggestion","emitted":"duration-minutes","expect":"duration","via":"concept:calendar_duration_minutes"}, + {"command":"calendar +suggestion","emitted":"from","expect":"start","via":"concept:time_start"}, + {"command":"calendar +suggestion","emitted":"to","expect":"end","via":"override:scoped_strict"}, {"command":"calendar +suggestion","emitted":"tz","expect":"timezone","via":"concept:calendar_timezone"}, {"command":"calendar +suggestion","emitted":"attendee-names","expect":"did-you-mean:blocked","via":"guard:name-vs-user-id"}, {"command":"calendar +update","emitted":"event-id","expect":"event","via":"concept:calendar_event_id"}, From 58ff0248b627ad9a181525fdbb1d8ce7d3ee67b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 19 Aug 2026 11:05:29 +0800 Subject: [PATCH 241/250] fix(recruit): handle minimal terminal pages --- internal/helpers/recruit.go | 2 +- internal/helpers/recruit_test.go | 34 ++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index b8f68115..62e271ff 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -297,7 +297,7 @@ func recruitListResultData(data any) (any, *output.Meta, error) { return nil, nil, fmt.Errorf("list_jobs 返回 hasMore=true 但缺少 nextCursor") } } - clean := make(map[string]any, len(object)-2) + clean := make(map[string]any, len(object)) for key, value := range object { if key != "hasMore" && key != "nextCursor" { clean[key] = value diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index 83b17f15..da320b23 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -564,6 +564,40 @@ func TestRecruitListResultData(t *testing.T) { } } +func TestRecruitListResultDataAcceptsMinimalTerminalPage(t *testing.T) { + data, meta, err := recruitListResultData(map[string]any{"hasMore": false}) + if err != nil { + t.Fatal(err) + } + clean, ok := data.(map[string]any) + if !ok || len(clean) != 0 { + t.Fatalf("data = %#v, want empty object", data) + } + if meta == nil || meta.Pagination == nil || !meta.Pagination.EndpointExhausted || + meta.Pagination.NextToken != "" || meta.Pagination.Pages != 1 || meta.Pagination.Items != 0 { + t.Fatalf("meta = %#v, want exhausted terminal page", meta) + } + if meta.Count != nil { + t.Fatalf("count = %#v, want nil when jobs is absent", meta.Count) + } + + caller := withRecruitCaller(t) + caller.text = `{"success":true,"result":{"hasMore":false}}` + cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) + result, err := recruitResultCall(cmd, recruitListJobsTool, map[string]any{"size": 20}) + if err != nil { + t.Fatal(err) + } + envelope, err := output.EnvelopeFromResult(result) + if err != nil { + t.Fatal(err) + } + if envelope.Outcome != output.OutcomeSuccess || envelope.Meta == nil || + envelope.Meta.Pagination == nil || !envelope.Meta.Pagination.EndpointExhausted { + t.Fatalf("envelope = %#v, want successful exhausted terminal page", envelope) + } +} + func TestRecruitResultCallPropagatesMCPError(t *testing.T) { caller := withRecruitCaller(t) caller.err = stderrors.New("transport failed") From 2ffddbd5a0ae511b4f4521aa2362eecc108eec9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=82=B3=E6=98=B1?= Date: Mon, 10 Aug 2026 21:28:20 +0800 Subject: [PATCH 242/250] feat(event): support OA approval CC events --- README.md | 5 ++-- README_zh.md | 5 ++-- internal/app/event_command.go | 2 +- internal/app/event_personal_attempts_test.go | 4 +-- internal/app/event_personal_oa_test.go | 9 ++++++ internal/event/personal/client_test.go | 1 + internal/event/personal/output.go | 29 +++++++++++++++++++ internal/event/personal/output_test.go | 18 ++++++++++++ internal/event/personal/registry.go | 12 ++++++++ internal/event/personal/registry_test.go | 12 ++++++++ skills/mono/SKILL.md | 2 +- skills/mono/references/products/event.md | 13 ++++++--- skills/multi/dingtalk-event/SKILL.md | 10 +++---- .../dingtalk-event/references/event-oa.md | 22 +++++++++----- test/skill_tests.md | 4 +++ test/unit/skill_docs_policy_test.go | 5 ++-- 16 files changed, 126 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ec3e7416..0c6af0bb 100644 --- a/README.md +++ b/README.md @@ -482,7 +482,7 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
Personal Event Subscription — real-time DingTalk messages for event-driven agents -`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, and six OA approval task/instance events. +`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, and seven OA approval task/instance events. The default `ndjson`, `json`, and `pretty` output preserves the transport envelope (`type`, `event_type`, string `data`, and `headers`) for existing scripts; `compact` retains its existing processor. Add `--flatten` to emit the stable top-level business fields used by Agent workflows. `--format` controls JSON serialization; `--flatten` controls the data structure and cannot be combined with `-f raw` or `--debug-raw-events`. @@ -530,12 +530,13 @@ dws event consume user_im_group_disbanded --group --flatten dws event +listen-im --kind sender --user \ --events message,read,recall -f ndjson -# Listen for all six public OA approval events in one process +# Listen for all seven public OA approval events in one process dws event consume \ user_oa_approval_task_created \ user_oa_approval_task_finished \ user_oa_approval_task_redirected \ user_oa_approval_instance_started \ + user_oa_approval_instance_cc \ user_oa_approval_instance_terminated \ user_oa_approval_instance_finished \ --flatten -f ndjson diff --git a/README_zh.md b/README_zh.md index e47544a4..b2a5763f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -476,7 +476,7 @@ multi setup 或 upgrade 后，DWS 会把官方 bundle 快照和统一所有权
个人事件订阅 — 实时接收钉钉消息，驱动事件触发的 Agent -`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期，以及六个 OA 审批任务/实例事件。 +`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期，以及七个 OA 审批任务/实例事件。 默认 `ndjson`、`json`、`pretty` 输出保留兼容 transport envelope（`type`、`event_type`、字符串 `data`、`headers`），`compact` 继续沿用原 processor。Agent 或新脚本显式加 `--flatten` 后，输出稳定的顶层业务字段。`--format` 控制 JSON 序列化，`--flatten` 控制数据结构，且不能与 `-f raw` 或 `--debug-raw-events` 同时使用。 @@ -524,12 +524,13 @@ dws event consume user_im_group_disbanded --group --flatten dws event +listen-im --kind sender --user \ --events message,read,recall -f ndjson -# 一个进程监听全部六个公开 OA 审批事件 +# 一个进程监听全部七个公开 OA 审批事件 dws event consume \ user_oa_approval_task_created \ user_oa_approval_task_finished \ user_oa_approval_task_redirected \ user_oa_approval_instance_started \ + user_oa_approval_instance_cc \ user_oa_approval_instance_terminated \ user_oa_approval_instance_finished \ --flatten -f ndjson diff --git a/internal/app/event_command.go b/internal/app/event_command.go index f0cc1e24..ef727259 100644 --- a/internal/app/event_command.go +++ b/internal/app/event_command.go @@ -403,7 +403,7 @@ SIGTERM、关 stdin，或先用 dws event stop --dry-run 预览 Selection: contract.SelectionSpec{ AgentSummary: "消费 OA、群生命周期或需要底层控制的个人事件流；Agent 通常使用 --flatten 输出 NDJSON", UseWhen: []string{ - "需要监听六个公开 OA 审批任务/实例 EventKey 中的一个或多个事件", + "需要监听七个公开 OA 审批任务/实例 EventKey 中的一个或多个事件", "需要监听指定群的标题变更、成员进退群或群解散事件", "用户显式给出原始 EventKey、Filter DSL、subscribe_id，要求原始 transport envelope，或需要普通 IM facade 不提供的高级多事件控制", }, diff --git a/internal/app/event_personal_attempts_test.go b/internal/app/event_personal_attempts_test.go index 1acdea27..913086bb 100644 --- a/internal/app/event_personal_attempts_test.go +++ b/internal/app/event_personal_attempts_test.go @@ -152,8 +152,8 @@ func TestCrossPlatformCoveragePersonalSubscriptionProtectionCoversAllPublicEvent } } - if publicCount != 22 { - t.Fatalf("public personal events = %d, want 22 (16 IM + 6 OA)", publicCount) + if publicCount != 23 { + t.Fatalf("public personal events = %d, want 23 (16 IM + 7 OA)", publicCount) } for _, ruleType := range []string{"at", "all", "singleChat", "sender", "group"} { if !ruleTypes[ruleType] { diff --git a/internal/app/event_personal_oa_test.go b/internal/app/event_personal_oa_test.go index 11f8dbe4..9defa152 100644 --- a/internal/app/event_personal_oa_test.go +++ b/internal/app/event_personal_oa_test.go @@ -61,6 +61,13 @@ func TestPersonalOAEventListAndSchemaCommands(t *testing.T) { "process_code", "title", "status", "create_time", "event_time", }, }, + { + eventKey: personal.EventOAApprovalInstanceCC, + properties: []string{ + "type", "event_id", "timestamp", "subscribe_id", "process_instance_id", + "process_code", "title", "status", "create_time", "event_time", + }, + }, { eventKey: personal.EventOAApprovalInstanceTerminated, properties: []string{ @@ -161,6 +168,7 @@ func TestPersonalOAEventConsumeDryRunAndValidation(t *testing.T) { personal.EventOAApprovalTaskFinished, personal.EventOAApprovalTaskRedirected, personal.EventOAApprovalInstanceStarted, + personal.EventOAApprovalInstanceCC, personal.EventOAApprovalInstanceTerminated, personal.EventOAApprovalInstanceFinished, } @@ -414,6 +422,7 @@ func TestPersonalOAMultiConsumeCreatesIndependentAllSubscriptionsOnSharedBus(t * personal.EventOAApprovalTaskFinished, personal.EventOAApprovalTaskRedirected, personal.EventOAApprovalInstanceStarted, + personal.EventOAApprovalInstanceCC, personal.EventOAApprovalInstanceTerminated, personal.EventOAApprovalInstanceFinished, } diff --git a/internal/event/personal/client_test.go b/internal/event/personal/client_test.go index e7ffe3af..9dfc12bd 100644 --- a/internal/event/personal/client_test.go +++ b/internal/event/personal/client_test.go @@ -132,6 +132,7 @@ func TestClientCreateRuleBasedSubscriptionsUsesDocumentedRuleParam(t *testing.T) {"oa_approval_task_finished", EventOAApprovalTaskFinished, RuleOptions{}, map[string]any{}}, {"oa_approval_task_redirected", EventOAApprovalTaskRedirected, RuleOptions{}, map[string]any{}}, {"oa_approval_instance_started", EventOAApprovalInstanceStarted, RuleOptions{}, map[string]any{}}, + {"oa_approval_instance_cc", EventOAApprovalInstanceCC, RuleOptions{}, map[string]any{}}, {"oa_approval_instance_terminated", EventOAApprovalInstanceTerminated, RuleOptions{}, map[string]any{}}, {"oa_approval_instance_finished", EventOAApprovalInstanceFinished, RuleOptions{}, map[string]any{}}, {"read_group", EventReadGroup, RuleOptions{GroupID: "cid-1"}, map[string]any{"openConversationId": "cid-1"}}, diff --git a/internal/event/personal/output.go b/internal/event/personal/output.go index 00d81a01..e42d1b45 100644 --- a/internal/event/personal/output.go +++ b/internal/event/personal/output.go @@ -180,6 +180,19 @@ type OAApprovalInstanceStartedOutput struct { EventTime int64 `json:"event_time" description:"审批实例事件业务时间" format:"timestamp_ms"` } +type OAApprovalInstanceCCOutput struct { + Type string `json:"type" description:"事件类型，固定为当前 event_key"` + EventID string `json:"event_id" description:"事件 ID，可用于去重"` + Timestamp int64 `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"` + SubscribeID string `json:"subscribe_id" description:"订阅 ID"` + ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"` + ProcessCode string `json:"process_code" description:"审批流程模板编码"` + Title string `json:"title" description:"审批标题"` + Status string `json:"status" description:"审批实例到达抄送节点时的状态"` + CreateTime int64 `json:"create_time" description:"审批实例创建时间" format:"timestamp_ms"` + EventTime int64 `json:"event_time" description:"审批抄送事件业务时间" format:"timestamp_ms"` +} + type OAApprovalInstanceTerminatedOutput struct { Type string `json:"type" description:"事件类型，固定为当前 event_key"` EventID string `json:"event_id" description:"事件 ID，可用于去重"` @@ -667,6 +680,19 @@ func projectOAApprovalEvent(ev transport.Event, base baseEventOutput, raw json.R CreateTime: payload.Body.CreateTime, EventTime: payload.EventTime, }, nil + case EventOAApprovalInstanceCC: + return OAApprovalInstanceCCOutput{ + Type: base.Type, + EventID: base.EventID, + Timestamp: base.Timestamp, + SubscribeID: base.SubscribeID, + ProcessInstanceID: payload.Body.ProcessInstanceID, + ProcessCode: payload.Body.ProcessCode, + Title: payload.Body.Title, + Status: payload.Body.Status, + CreateTime: payload.Body.CreateTime, + EventTime: payload.EventTime, + }, nil case EventOAApprovalInstanceTerminated: return OAApprovalInstanceTerminatedOutput{ Type: base.Type, @@ -871,6 +897,8 @@ func outputTypeForEvent(eventKey string) reflect.Type { return reflect.TypeOf(OAApprovalTaskRedirectedOutput{}) case eventKey == EventOAApprovalInstanceStarted: return reflect.TypeOf(OAApprovalInstanceStartedOutput{}) + case eventKey == EventOAApprovalInstanceCC: + return reflect.TypeOf(OAApprovalInstanceCCOutput{}) case eventKey == EventOAApprovalInstanceTerminated: return reflect.TypeOf(OAApprovalInstanceTerminatedOutput{}) case eventKey == EventOAApprovalInstanceFinished: @@ -906,6 +934,7 @@ func isOAEvent(eventKey string) bool { eventKey == EventOAApprovalTaskFinished || eventKey == EventOAApprovalTaskRedirected || eventKey == EventOAApprovalInstanceStarted || + eventKey == EventOAApprovalInstanceCC || eventKey == EventOAApprovalInstanceTerminated || eventKey == EventOAApprovalInstanceFinished } diff --git a/internal/event/personal/output_test.go b/internal/event/personal/output_test.go index 326caf67..e9de2e00 100644 --- a/internal/event/personal/output_test.go +++ b/internal/event/personal/output_test.go @@ -173,6 +173,8 @@ func personalOAData(eventKey string) string { body["finishTime"] = int64(1785229199000) case EventOAApprovalInstanceStarted: body["status"] = "RUNNING" + case EventOAApprovalInstanceCC: + body["status"] = "RUNNING" case EventOAApprovalInstanceTerminated: body["status"] = "TERMINATED" body["finishTime"] = int64(1785229199000) @@ -521,6 +523,21 @@ func TestCrossPlatformCoverageProjectOutputOAEvents(t *testing.T) { EventTime: 1785229199000, }, }, + { + eventKey: EventOAApprovalInstanceCC, + want: OAApprovalInstanceCCOutput{ + Type: EventOAApprovalInstanceCC, + EventID: "oa-event", + Timestamp: 1785229200123, + SubscribeID: "outer-sub", + ProcessInstanceID: "process-instance-1", + ProcessCode: "PROC-TEST-1", + Title: "测试审批", + Status: "RUNNING", + CreateTime: 1785229100000, + EventTime: 1785229199000, + }, + }, { eventKey: EventOAApprovalInstanceTerminated, want: OAApprovalInstanceTerminatedOutput{ @@ -785,6 +802,7 @@ func TestCrossPlatformCoverageProjectOutputRejectsInvalidOAPayloads(t *testing.T EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, } { diff --git a/internal/event/personal/registry.go b/internal/event/personal/registry.go index bffb7918..50e3ce03 100644 --- a/internal/event/personal/registry.go +++ b/internal/event/personal/registry.go @@ -43,6 +43,7 @@ const ( EventOAApprovalTaskFinished = "user_oa_approval_task_finished" EventOAApprovalTaskRedirected = "user_oa_approval_task_redirected" EventOAApprovalInstanceStarted = "user_oa_approval_instance_started" + EventOAApprovalInstanceCC = "user_oa_approval_instance_cc" EventOAApprovalInstanceTerminated = "user_oa_approval_instance_terminated" EventOAApprovalInstanceFinished = "user_oa_approval_instance_finished" ) @@ -323,6 +324,17 @@ var definitions = []Definition{ Auth: map[string]any{"identity": "user"}, Public: true, }, + { + EventKey: EventOAApprovalInstanceCC, + DisplayName: "审批单抄送", + Description: "审批实例到达抄送节点，发送给被抄送人", + Category: "oa", + RuleType: "all", + Status: StatusEnabled, + RequiredParams: nil, + Auth: map[string]any{"identity": "user"}, + Public: true, + }, { EventKey: EventOAApprovalInstanceTerminated, DisplayName: "审批单终止", diff --git a/internal/event/personal/registry_test.go b/internal/event/personal/registry_test.go index fb01a3b3..1b80fa82 100644 --- a/internal/event/personal/registry_test.go +++ b/internal/event/personal/registry_test.go @@ -50,6 +50,7 @@ func TestCatalogEnabledEvents(t *testing.T) { EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, } @@ -65,6 +66,7 @@ func TestOAEventCatalogDefinitions(t *testing.T) { EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, } @@ -158,6 +160,7 @@ func TestSchemaDocumentsDefaultToTransportEnvelope(t *testing.T) { EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, } { @@ -509,6 +512,13 @@ func TestOAEventSchemaDocumentsMatchOutputDTO(t *testing.T) { "process_code", "title", "status", "create_time", "event_time", }, }, + { + eventKey: EventOAApprovalInstanceCC, + properties: []string{ + "type", "event_id", "timestamp", "subscribe_id", "process_instance_id", + "process_code", "title", "status", "create_time", "event_time", + }, + }, { eventKey: EventOAApprovalInstanceTerminated, properties: []string{ @@ -633,6 +643,7 @@ func TestBuildRuleParamAllEvents(t *testing.T) { EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, } { @@ -845,6 +856,7 @@ func TestSupportsMessageFilter(t *testing.T) { EventOAApprovalTaskFinished, EventOAApprovalTaskRedirected, EventOAApprovalInstanceStarted, + EventOAApprovalInstanceCC, EventOAApprovalInstanceTerminated, EventOAApprovalInstanceFinished, "unknown_event", diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index 189ffbad..2fb8cb3d 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -1,6 +1,6 @@ --- name: dws -description: 管理钉钉产品能力(AI表格/AI搜问/日历/通讯录/群聊与机器人/待办/审批/考勤/日志/DING消息/开放平台文档/钉钉文档/钉钉云盘/原生Markdown文件/AI听记/邮箱/在线电子表格/知识库等)。当用户需要操作表格数据、管理日程会议、模糊找人/查谁负责某事项、查询通讯录、管理群聊、机器人发消息、创建待办、提交审批、查看考勤、提交日报周报（钉钉日志模版）、读写钉钉文档、上传下载云盘文件、读取或修改原生.md文件、查询听记纪要、收发邮件、读写在线电子表格(axls)、管理钉钉知识库，或订阅个人 IM 事件或 OA 审批事件、实时监听群成员加入、群成员退出、群改名和群解散、审批实例发起/终止/完成，以及审批任务创建/完成/转交时使用。 +description: 管理钉钉产品能力(AI表格/AI搜问/日历/通讯录/群聊与机器人/待办/审批/考勤/日志/DING消息/开放平台文档/钉钉文档/钉钉云盘/原生Markdown文件/AI听记/邮箱/在线电子表格/知识库等)。当用户需要操作表格数据、管理日程会议、模糊找人/查谁负责某事项、查询通讯录、管理群聊、机器人发消息、创建待办、提交审批、查看考勤、提交日报周报（钉钉日志模版）、读写钉钉文档、上传下载云盘文件、读取或修改原生.md文件、查询听记纪要、收发邮件、读写在线电子表格(axls)、管理钉钉知识库，或订阅个人 IM 事件或 OA 审批事件、实时监听群成员加入、群成员退出、群改名和群解散、审批实例发起/抄送/终止/完成，以及审批任务创建/完成/转交时使用。 cli_version: ">=1.0.15" --- diff --git a/skills/mono/references/products/event.md b/skills/mono/references/products/event.md index f9b82c95..15178398 100644 --- a/skills/mono/references/products/event.md +++ b/skills/mono/references/products/event.md @@ -47,10 +47,11 @@ | `user_oa_approval_task_finished` | 审批任务已完成 | 无 | | `user_oa_approval_task_redirected` | 审批任务已转交 | 无 | | `user_oa_approval_instance_started` | 审批实例已发起 | 无 | +| `user_oa_approval_instance_cc` | 审批实例到达抄送节点，发送给被抄送人 | 无 | | `user_oa_approval_instance_terminated` | 审批实例已终止 | 无 | | `user_oa_approval_instance_finished` | 审批实例完成，发送给审批单发起人 | 无 | -只承认上表 22 个事件码。默认身份就是当前用户，使用当前用户 OAuth 登录态，不要额外加身份切换 flag。六个 OA 事件订阅当前用户相关的全部审批事件，规则均为 `all`、空 `filterRule`，不需要目标参数。 +只承认上表 23 个事件码。默认身份就是当前用户，使用当前用户 OAuth 登录态，不要额外加身份切换 flag。七个 OA 事件订阅当前用户相关的全部审批事件，规则均为 `all`、空 `filterRule`，不需要目标参数。 ## Intent mapping @@ -76,9 +77,10 @@ | "审批任务完成时通知我" | `event consume`，事件码 `user_oa_approval_task_finished`，参数 `--flatten -f ndjson` | | "审批任务被转交时通知我" | `event consume`，事件码 `user_oa_approval_task_redirected`，参数 `--flatten -f ndjson` | | "有审批单发起时通知我" | `event consume`，事件码 `user_oa_approval_instance_started`，参数 `--flatten -f ndjson` | +| "有审批抄送给我时通知我" | `event consume`，事件码 `user_oa_approval_instance_cc`，参数 `--flatten -f ndjson` | | "有审批单终止时通知我" | `event consume`，事件码 `user_oa_approval_instance_terminated`，参数 `--flatten -f ndjson` | | "监听我发起的审批何时完成" / "审批实例完成时通知我" | `event consume`，事件码 `user_oa_approval_instance_finished`，参数 `--flatten -f ndjson` | -| "同时监听全部已公开 OA 事件" | 一个 consume 放入六个 OA event key，不加目标或消息过滤参数 | +| "同时监听全部已公开 OA 事件" | 一个 consume 放入七个 OA event key，不加目标或消息过滤参数 | | "查看个人事件 schema" | `dws event schema --flatten` | | "看个人事件订阅状态" | `dws event status --event ` | | "停止这个个人事件订阅" | `dws event stop --dry-run`，确认后改用 `--yes` | @@ -130,6 +132,7 @@ dws event schema user_oa_approval_task_created --flatten dws event schema user_oa_approval_task_finished --flatten dws event schema user_oa_approval_task_redirected --flatten dws event schema user_oa_approval_instance_started --flatten +dws event schema user_oa_approval_instance_cc --flatten dws event schema user_oa_approval_instance_terminated --flatten dws event schema user_oa_approval_instance_finished --flatten ``` @@ -157,6 +160,7 @@ dws event consume user_oa_approval_task_created --flatten -f ndjson dws event consume user_oa_approval_task_finished --flatten -f ndjson dws event consume user_oa_approval_task_redirected --flatten -f ndjson dws event consume user_oa_approval_instance_started --flatten -f ndjson +dws event consume user_oa_approval_instance_cc --flatten -f ndjson dws event consume user_oa_approval_instance_terminated --flatten -f ndjson dws event consume user_oa_approval_instance_finished --flatten -f ndjson ``` @@ -185,13 +189,14 @@ dws event consume \ user_oa_approval_task_finished \ user_oa_approval_task_redirected \ user_oa_approval_instance_started \ + user_oa_approval_instance_cc \ user_oa_approval_instance_terminated \ user_oa_approval_instance_finished \ --flatten \ -f ndjson ``` -用户类事件共享 `--user` 或 `--open-dingtalk-id`，群类事件共享 `--group`，无目标 IM 事件可加入任一组合。用户类与群类、不同目标或不同过滤条件要拆成多个进程。六个 OA 事件可以同进程消费并共享 personal bus，但各自建立独立订阅。多事件共享 `--query` / `--filter-json` 时，所选事件必须全部是 IM 消息接收事件；OA 事件单独或组合消费都禁止使用这两个消息过滤参数。 +用户类事件共享 `--user` 或 `--open-dingtalk-id`，群类事件共享 `--group`，无目标 IM 事件可加入任一组合。用户类与群类、不同目标或不同过滤条件要拆成多个进程。七个 OA 事件可以同进程消费并共享 personal bus，但各自建立独立订阅。多事件共享 `--query` / `--filter-json` 时，所选事件必须全部是 IM 消息接收事件；OA 事件单独或组合消费都禁止使用这两个消息过滤参数。 上述所有 `*_o2o` 命令和 `user_im_message_receive_user` 都可将 `--user ` 替换为 `--open-dingtalk-id `，但两个参数不能同时使用。 @@ -216,7 +221,7 @@ dws event stop --all --yes ## 订阅创建失败与重试预算 -以下约束适用于上表全部 22 个公开个人事件（16 个 IM + 6 个 OA）以及多事件命令中的每一项，只治理 `[event] ready` 之前的订阅创建；ready 之后的 Stream 断线由长连接重连机制处理。 +以下约束适用于上表全部 23 个公开个人事件（16 个 IM + 7 个 OA）以及多事件命令中的每一项，只治理 `[event] ready` 之前的订阅创建；ready 之后的 Stream 断线由长连接重连机制处理。 - `0/2/1` 是 **Agent/host 编排约束**，不是 CLI 持久化硬总次数上限。每次 `dws event consume` 调用对每个逻辑订阅最多发送一次订阅创建 HTTP 请求，进程内不会自动重试。CLI 本地状态只持久化 `in_flight`、`cooldown`、`terminal_hold` 三种保护状态，不持久化或计算跨调用的 Agent/host 尝试次数。 - 解析人名或群名、执行 `event consume` 以及后续 `event status/stop` 必须使用同一个 `--profile`。不得把其它 profile 下解析出的 userId、openDingtalkId 或 openConversationId 直接带入当前 profile 的订阅。 diff --git a/skills/multi/dingtalk-event/SKILL.md b/skills/multi/dingtalk-event/SKILL.md index 4fdd75a9..719c3d64 100644 --- a/skills/multi/dingtalk-event/SKILL.md +++ b/skills/multi/dingtalk-event/SKILL.md @@ -1,6 +1,6 @@ --- name: dingtalk-event -description: 钉钉个人 IM 与 OA 审批事件长连接监听。Use when 用户说监听消息/@我/某人/某群/全部消息、已读/撤回/reaction、群成员加入/群成员退出/群状态变化，或监听审批任务创建/完成/转交、审批实例发起/终止/完成。命令前缀：dws event。 +description: 钉钉个人 IM 与 OA 审批事件长连接监听。Use when 用户说监听消息/@我/某人/某群/全部消息、已读/撤回/reaction、群成员加入/群成员退出/群状态变化，或监听审批任务创建/完成/转交、审批实例发起/抄送/终止/完成。命令前缀：dws event。 metadata: cli_version: ">=0.2.14" category: product @@ -45,7 +45,7 @@ metadata: - `group` 必须且只能传 `--chat-id` 或 `--chat-query` 之一。 - `--query` 只用于纯 `message` 监听；混入 reaction/read/recall 时不得使用。 -OA 事件不进入 `+listen-im`。六个公开 OA EventKey 都订阅当前 OAuth 用户相关的全部审批事件，使用 `ruleType=all`、`filterRule={}`；不接受 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。六项可放入同一个 consume，每项建立独立订阅并共享 bus。 +OA 事件不进入 `+listen-im`。七个公开 OA EventKey 都订阅当前 OAuth 用户相关的全部审批事件，使用 `ruleType=all`、`filterRule={}`；不接受 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。七项可放入同一个 consume，每项建立独立订阅并共享 bus。 自然姓名和群名由 CLI 内部唯一解析：零命中或多候选返回结构化失败，在创建任何订阅前停止。`--dry-run` 走同一解析链。解析、监听、状态和停止必须使用同一个 `--profile`，不得跨组织搬运 ID。 @@ -65,7 +65,7 @@ user_im_group_member_added user_im_group_member_exited user_im_group_disbanded ``` -六个 OA EventKey 及其输出字段见 [OA 事件参考](references/event-oa.md)。 +七个 OA EventKey 及其输出字段见 [OA 事件参考](references/event-oa.md)。 用户类事件传 `--user` 或 `--open-dingtalk-id`，群类事件传 `--group`。群生命周期输出可含 `operator_open_dingtalk_id` 和 `members`；成员项使用 `open_dingtalk_id`。精确组合、兼容性和 Filter 规则见 reference。 @@ -98,7 +98,7 @@ kind + events + target - `event stop` 会取消订阅并影响本地 consumer：先 `--dry-run`，用户确认后再加 `--yes`。 - 多事件属于一次原始操作；任一订阅启动失败时 Runtime 回滚本次已创建项，不拆成新命令绕过重试预算。 -- 这套 `0/2/1` 是 **Agent/host** 编排预算，适用于全部 22 个公开个人 EventKey（16 个 IM + 6 个 OA）：`retryable=false` 对应 `max_additional_attempts=0`；`retryable=true` 对应 `max_additional_attempts=2`；`retryable=unknown` 对应 `max_additional_attempts=1`。它不是 CLI 持久化硬总次数上限；每次调用最多创建一次，进程内不会自动重试，CLI 也不持久化或计算跨调用的 Agent/host 尝试次数。 +- 这套 `0/2/1` 是 **Agent/host** 编排预算，适用于全部 23 个公开个人 EventKey（16 个 IM + 7 个 OA）：`retryable=false` 对应 `max_additional_attempts=0`；`retryable=true` 对应 `max_additional_attempts=2`；`retryable=unknown` 对应 `max_additional_attempts=1`。它不是 CLI 持久化硬总次数上限；每次调用最多创建一次，进程内不会自动重试，CLI 也不持久化或计算跨调用的 Agent/host 尝试次数。 - 重试必须遵守 `retry_after_seconds` / `next_retry_at`。遇到 `in_flight`、`cooldown`、`terminal_hold` 不并发或递归重启同一逻辑订阅，也不换 `subscribe_id` / `trace_id` 绕过保护。 - 认证、profile、订阅保护状态和 bus 排障按失败类型读取 [订阅运维](references/event-im-operations.md)，不要在正常路径预加载完整运维手册。 @@ -125,4 +125,4 @@ kind + events + target | ready、bounded consume 与退出清理 | [event-im-lifecycle.md](references/event-im-lifecycle.md) | 启动/托管/关闭 consumer | | 扁平字段与事件到 Chat 交接 | [event-im-output.md](references/event-im-output.md) | 解析事件或自动回复 | | Filter、status/stop、重试与排障 | [event-im-operations.md](references/event-im-operations.md) | 订阅控制或失败恢复 | -| OA 审批事件 | [event-oa.md](references/event-oa.md) | 选择六个 OA EventKey、组合消费或解析审批字段 | +| OA 审批事件 | [event-oa.md](references/event-oa.md) | 选择七个 OA EventKey、组合消费或解析审批字段 | diff --git a/skills/multi/dingtalk-event/references/event-oa.md b/skills/multi/dingtalk-event/references/event-oa.md index 6d7ec4e2..e8af0108 100644 --- a/skills/multi/dingtalk-event/references/event-oa.md +++ b/skills/multi/dingtalk-event/references/event-oa.md @@ -1,6 +1,6 @@ # OA 个人审批事件 -先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、调用流和子进程契约。本参考覆盖当前公开的六个 OA 个人事件：审批实例发起、终止和完成，以及审批任务创建、完成和转交。 +先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、调用流和子进程契约。本参考覆盖当前公开的七个 OA 个人事件：审批实例发起、抄送、终止和完成，以及审批任务创建、完成和转交。 实时监听审批事件必须使用 `dws event consume` 长连接，不要轮询 OA 待办或审批实例列表来模拟事件。 @@ -22,10 +22,11 @@ dws auth login | `user_oa_approval_task_finished` | `all` | 审批任务已完成 | 无 | | `user_oa_approval_task_redirected` | `all` | 审批任务已转交 | 无 | | `user_oa_approval_instance_started` | `all` | 审批实例已发起 | 无 | +| `user_oa_approval_instance_cc` | `all` | 审批实例到达抄送节点，发送给被抄送人 | 无 | | `user_oa_approval_instance_terminated` | `all` | 审批实例已终止 | 无 | | `user_oa_approval_instance_finished` | `all` | 审批实例完成，发送给审批单发起人 | 无 | -只承认上表 6 个 OA 事件码。CLI 为每个事件发送 `ruleType=all`、`filterRule={}` 的独立订阅请求；不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。 +只承认上表 7 个 OA 事件码。CLI 为每个事件发送 `ruleType=all`、`filterRule={}` 的独立订阅请求；不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。 ## Intent mapping @@ -35,13 +36,14 @@ dws auth login | “审批任务完成时通知我” | `dws event consume user_oa_approval_task_finished --flatten -f ndjson` | | “审批任务被转交时通知我” | `dws event consume user_oa_approval_task_redirected --flatten -f ndjson` | | “有审批单发起时通知我” | `dws event consume user_oa_approval_instance_started --flatten -f ndjson` | +| “有审批抄送给我时通知我” | `dws event consume user_oa_approval_instance_cc --flatten -f ndjson` | | “有审批单终止时通知我” | `dws event consume user_oa_approval_instance_terminated --flatten -f ndjson` | | “监听我发起的审批何时完成” / “审批实例完成时通知我” | `dws event consume user_oa_approval_instance_finished --flatten -f ndjson` | -| “同时监听全部已公开 OA 事件” | 一个 consume 放入六个 OA event key，不加目标或过滤参数 | +| “同时监听全部已公开 OA 事件” | 一个 consume 放入七个 OA event key，不加目标或过滤参数 | | “查看 OA 事件目录” | `dws event list --category oa` | | “查看 OA 事件输出字段” | 对对应事件运行 `dws event schema --flatten` | -三个审批任务事件分别表达任务已创建、已完成和已转交；三个审批实例事件分别表达实例已发起、已终止和已完成。扁平字段来自六类事件的预发联调样本；`status` 和 `result` 保留服务端原值，不把当前样本值推断为完整枚举。 +三个审批任务事件分别表达任务已创建、已完成和已转交；四个审批实例事件分别表达实例已发起、到达抄送节点、已终止和已完成。`status` 和 `result` 保留服务端原值，不把当前样本值推断为完整枚举。 ## Commands @@ -52,6 +54,7 @@ dws event schema user_oa_approval_task_created --flatten dws event schema user_oa_approval_task_finished --flatten dws event schema user_oa_approval_task_redirected --flatten dws event schema user_oa_approval_instance_started --flatten +dws event schema user_oa_approval_instance_cc --flatten dws event schema user_oa_approval_instance_terminated --flatten dws event schema user_oa_approval_instance_finished --flatten ``` @@ -63,11 +66,12 @@ dws event consume user_oa_approval_task_created --flatten -f ndjson dws event consume user_oa_approval_task_finished --flatten -f ndjson dws event consume user_oa_approval_task_redirected --flatten -f ndjson dws event consume user_oa_approval_instance_started --flatten -f ndjson +dws event consume user_oa_approval_instance_cc --flatten -f ndjson dws event consume user_oa_approval_instance_terminated --flatten -f ndjson dws event consume user_oa_approval_instance_finished --flatten -f ndjson ``` -同时监听六种事件： +同时监听七种事件： ```bash dws event consume \ @@ -75,13 +79,14 @@ dws event consume \ user_oa_approval_task_finished \ user_oa_approval_task_redirected \ user_oa_approval_instance_started \ + user_oa_approval_instance_cc \ user_oa_approval_instance_terminated \ user_oa_approval_instance_finished \ --flatten \ -f ndjson ``` -多事件 consume 会为六个 event key 分别创建订阅和逻辑 consumer，并共享当前组织的 personal bus、远程连接、stdout 和生命周期。不要给 OA 命令加 `--query` 或 `--filter-json`；这两个 flag 只用于兼容的 IM 消息接收事件。 +多事件 consume 会为七个 event key 分别创建订阅和逻辑 consumer，并共享当前组织的 personal bus、远程连接、stdout 和生命周期。不要给 OA 命令加 `--query` 或 `--filter-json`；这两个 flag 只用于兼容的 IM 消息接收事件。 ## Output contract @@ -105,7 +110,7 @@ dws event consume \ - `type` 是当前 event key；`event_id` 可用于去重；`timestamp` 是 transport 事件发生时间；`subscribe_id` 标识对应的独立订阅。 - `process_instance_id` 是审批实例 ID，可传给 OA 审批命令的 `--instance-id`；`process_code` 是审批流程模板编码。 - `create_time`、`finish_time` 和 `event_time` 都是毫秒时间戳。`event_time` 是审批业务事件时间，`timestamp` 是 transport 事件时间。 -- 六类事件的额外字段如下；具体事件始终以 `dws event schema --flatten` 为准。 +- 七类事件的额外字段如下；具体事件始终以 `dws event schema --flatten` 为准。 | 事件 | 额外顶层字段 | |---|---| @@ -113,6 +118,7 @@ dws event consume \ | `user_oa_approval_task_finished` | `task_id`、`result`、`finish_time` | | `user_oa_approval_task_redirected` | `task_id`、`result`、`finish_time` | | `user_oa_approval_instance_started` | 无 | +| `user_oa_approval_instance_cc` | 无 | | `user_oa_approval_instance_terminated` | `finish_time` | | `user_oa_approval_instance_finished` | `result`、`finish_time` | @@ -144,6 +150,6 @@ dws event consume \ ## Lifecycle - 单事件等待 `[event] ready event_key= bus_pid= subscribe_id=`。 -- 六事件先保存六条 `[event] subscription event_key= subscribe_id=`，再等待 `[event] ready event_count=6 bus_pid=`。 +- 七事件先保存七条 `[event] subscription event_key= subscribe_id=`，再等待 `[event] ready event_count=7 bus_pid=`。 - 临时验证使用 `--max-events 1` 或 `--duration 10m`；任务完成后优雅结束 consume，本次新建的订阅会自动取消。 - 外部停止已有订阅时先运行 `dws event stop --dry-run`，确认后再加 `--yes`。不要 `kill -9`，否则会跳过自动退订。 diff --git a/test/skill_tests.md b/test/skill_tests.md index 8c1b6c4e..2325e43d 100644 --- a/test/skill_tests.md +++ b/test/skill_tests.md @@ -1190,6 +1190,10 @@ Agent 安装 dws skill 后，仅依据 skill 提供的参考文档，将自然 - Prompt: 有和我相关的审批实例发起时实时通知我 - Expected: `dws event consume user_oa_approval_instance_started --flatten -f ndjson` +**event_event_consume_oa_instance_cc_001** +- Prompt: 有审批实例抄送给我时实时通知我 +- Expected: `dws event consume user_oa_approval_instance_cc --flatten -f ndjson` + **event_event_consume_oa_instance_terminated_001** - Prompt: 和我相关的审批实例终止时实时通知我 - Expected: `dws event consume user_oa_approval_instance_terminated --flatten -f ndjson` diff --git a/test/unit/skill_docs_policy_test.go b/test/unit/skill_docs_policy_test.go index 45877f26..d5c36cf1 100644 --- a/test/unit/skill_docs_policy_test.go +++ b/test/unit/skill_docs_policy_test.go @@ -280,7 +280,7 @@ func TestEventSkillFrontmatterAdvertisesGroupMemberLifecycle(t *testing.T) { "群成员加入", "群成员退出", "审批任务创建/完成/转交", - "审批实例发起/终止/完成", + "审批实例发起/抄送/终止/完成", } { if !strings.Contains(frontmatter, required) { t.Errorf("%s frontmatter missing event discovery trigger %q", path, required) @@ -306,7 +306,7 @@ func TestStandaloneEventSkillOwnsAllPersonalEventContracts(t *testing.T) { "", "", "16 个 EventKey", - "22 个公开个人 EventKey", + "23 个公开个人 EventKey", } { if !strings.Contains(string(skillContent), required) { t.Errorf("%s missing standalone event contract %q", skillPath, required) @@ -360,6 +360,7 @@ func TestStandaloneEventSkillOwnsAllPersonalEventContracts(t *testing.T) { "user_oa_approval_task_finished", "user_oa_approval_task_redirected", "user_oa_approval_instance_started", + "user_oa_approval_instance_cc", "user_oa_approval_instance_terminated", "user_oa_approval_instance_finished", } From ec59cf80659a243025a45ef581cdb5de3deb7acb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 12:14:05 +0800 Subject: [PATCH 243/250] test(calendar): run alias payloads in platform gate --- internal/app/param_alias_payload_equivalence_test.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index c212ccb3..60a46a00 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -750,11 +750,11 @@ func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepres } } -func TestReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) { +func TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) { if os.Getenv(paramAliasCalendarPayloadChildEnv) != "1" { command := exec.Command( os.Args[0], - "-test.run=^TestReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads$", + "-test.run=^TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads$", "-test.count=1", "-test.timeout=5m", ) From 4c6db326f5a1248d4e443b180f4c310a1508c4d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 13:30:40 +0800 Subject: [PATCH 244/250] fix(chat): preserve and validate user mention tokens --- .../shortcut/chat/coverage_completion_test.go | 59 +++++++++++- internal/shortcut/chat/lark_alignment_test.go | 10 +- internal/shortcut/chat/unified_send.go | 93 ++++++++++++++++++- 3 files changed, 159 insertions(+), 3 deletions(-) diff --git a/internal/shortcut/chat/coverage_completion_test.go b/internal/shortcut/chat/coverage_completion_test.go index 0bdbe1ab..490e48ab 100644 --- a/internal/shortcut/chat/coverage_completion_test.go +++ b/internal/shortcut/chat/coverage_completion_test.go @@ -437,7 +437,7 @@ func TestCrossPlatformCoverageUnifiedSendOptionalArgumentsAndErrors(t *testing.T }{ { name: "user group mentions", - args: []string{"--identity", "user", "--group", "cid", "--text", "x", "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2, "--at-all"}, + args: []string{"--identity", "user", "--group", "cid", "--text", "@" + fixtureCurrentDOpenID + " <@" + fixtureCurrentDOpenID2 + "> x", "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2, "--at-all"}, want: map[string]any{"atOpenDingTalkIds": []string{fixtureCurrentDOpenID, fixtureCurrentDOpenID2}, "atAll": true}, }, { @@ -505,6 +505,63 @@ func TestCrossPlatformCoverageUnifiedSendOptionalArgumentsAndErrors(t *testing.T } } +func TestCrossPlatformCoverageMessagesSendRejectsMismatchedCurrentUserMentions(t *testing.T) { + tests := []struct { + name string + body string + atIDs string + atAll bool + wantErr string + }{ + { + name: "declared member missing from body", + body: "请查收", + atIDs: fixtureCurrentDOpenID, + wantErr: "必须在正文中使用对应", + }, + { + name: "body member missing from declaration", + body: "<@" + fixtureCurrentDOpenID + "> 请查收", + wantErr: "必须同时通过 --at-open-dingtalk-ids 声明", + }, + { + name: "body at-all missing from declaration", + body: "<@all> 请查收", + wantErr: "必须同时指定 --at-all", + }, + { + name: "bare body member missing from declaration", + body: "@" + fixtureCurrentDOpenID + " 请查收", + wantErr: "必须同时通过 --at-open-dingtalk-ids 声明", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + fake := &larkAlignmentCaller{} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + args := []string{ + "chat", "+messages-send", "--identity", "user", + "--group", "cid", "--markdown", tt.body, "--yes", + } + if tt.atIDs != "" { + args = append(args, "--at-open-dingtalk-ids", tt.atIDs) + } + if tt.atAll { + args = append(args, "--at-all") + } + root.SetArgs(args) + err := root.Execute() + if err == nil || !strings.Contains(err.Error(), tt.wantErr) { + t.Fatalf("error = %v, want %q", err, tt.wantErr) + } + if len(fake.calls) != 0 { + t.Fatalf("invalid mention contract reached lower service: %#v", fake.calls) + } + }) + } +} + func TestCrossPlatformCoverageUnifiedSendUnsupportedIdentityGuard(t *testing.T) { flags := append([]shortcut.Flag(nil), MessagesSend.Flags...) for i := range flags { diff --git a/internal/shortcut/chat/lark_alignment_test.go b/internal/shortcut/chat/lark_alignment_test.go index cea41825..18ba4296 100644 --- a/internal/shortcut/chat/lark_alignment_test.go +++ b/internal/shortcut/chat/lark_alignment_test.go @@ -10,6 +10,7 @@ import ( "encoding/json" "errors" "reflect" + "strings" "testing" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" @@ -337,8 +338,15 @@ func TestCrossPlatformCoverageMessagesSendRoutesIdentitySpecificTransports(t *te } } if tt.bodyKey == "content" { + rawContent := call.args[tt.bodyKey].(string) + if strings.Contains(rawContent, `\u003c`) || strings.Contains(rawContent, `\u003e`) { + t.Errorf("content = %q; current-user mention tokens must remain literal", rawContent) + } + if !strings.Contains(rawContent, "<@"+fixtureCurrentDOpenID+">") { + t.Errorf("content = %q; missing literal current-user mention token", rawContent) + } var content map[string]string - if err := json.Unmarshal([]byte(call.args[tt.bodyKey].(string)), &content); err != nil { + if err := json.Unmarshal([]byte(rawContent), &content); err != nil { t.Fatal(err) } if content["text"] != tt.body { diff --git a/internal/shortcut/chat/unified_send.go b/internal/shortcut/chat/unified_send.go index 1977d077..bd3c66d9 100644 --- a/internal/shortcut/chat/unified_send.go +++ b/internal/shortcut/chat/unified_send.go @@ -11,6 +11,7 @@ import ( "os" "strings" "time" + "unicode" "unicode/utf8" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd" @@ -18,6 +19,7 @@ import ( "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract" apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers" + "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg" "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver" @@ -181,6 +183,12 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error { if contentType != "text" && contentType != "markdown" && (len(atOpenIDs) > 0 || rt.Bool("at-all")) { return apperrors.NewValidation("user image/file/audio/video 当前不接受 @ 参数") } + if (group != "" || chatQuery != "") && (contentType == "text" || contentType == "markdown") { + if err := validateCurrentUserMentionConsistency( + messagesSendBody(rt), atOpenIDs, rt.Bool("at-all")); err != nil { + return err + } + } case "bot": if chatQuery != "" || userQuery != "" { return apperrors.NewValidation("--identity bot 当前不接受 --chat-query 或 --user-query；请传真实群 ID 或批量用户 ID") @@ -234,6 +242,89 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error { return nil } +func validateCurrentUserMentionConsistency(body string, atOpenIDs []string, atAll bool) error { + declared := make(map[string]struct{}, len(atOpenIDs)) + for _, id := range atOpenIDs { + declared[id] = struct{}{} + } + + missingPlaceholders := make([]string, 0) + for _, id := range atOpenIDs { + if !containsCurrentUserMentionToken(body, id) { + missingPlaceholders = append(missingPlaceholders, id) + } + } + if len(missingPlaceholders) > 0 { + return apperrors.NewValidation(fmt.Sprintf( + "--at-open-dingtalk-ids 中的成员必须在正文中使用对应 <@openDingTalkId> 占位符；缺少: %s", + strings.Join(missingPlaceholders, ","), + )) + } + + undeclared := make([]string, 0) + for _, id := range currentUserMentionBodyIDs(body) { + if _, ok := declared[id]; !ok { + undeclared = append(undeclared, id) + } + } + if len(undeclared) > 0 { + return apperrors.NewValidation(fmt.Sprintf( + "正文中的成员 <@openDingTalkId> 占位符必须同时通过 --at-open-dingtalk-ids 声明；未声明: %s", + strings.Join(undeclared, ","), + )) + } + if !atAll && containsCurrentUserMentionToken(body, "all") { + return apperrors.NewValidation("正文中的 <@all> 占位符必须同时指定 --at-all") + } + return nil +} + +func containsCurrentUserMentionToken(body, id string) bool { + placeholder := "@" + id + for searchFrom := 0; ; { + offset := strings.Index(body[searchFrom:], placeholder) + if offset < 0 { + return false + } + end := searchFrom + offset + len(placeholder) + if end == len(body) { + return true + } + next, _ := utf8.DecodeRuneInString(body[end:]) + if !unicode.IsLetter(next) && !unicode.IsDigit(next) && next != '_' && next != '-' { + return true + } + searchFrom = end + } +} + +func currentUserMentionBodyIDs(body string) []string { + ids := make([]string, 0) + for searchFrom := 0; ; { + offset := strings.IndexByte(body[searchFrom:], '@') + if offset < 0 { + break + } + start := searchFrom + offset + 1 + end := start + for end < len(body) { + current := body[end] + if (current < 'a' || current > 'z') && + (current < 'A' || current > 'Z') && + (current < '0' || current > '9') { + break + } + end++ + } + id := body[start:end] + if targetresolver.LooksLikeCurrentDOpenDingTalkID(id) { + ids = appendUniqueShortcutString(ids, id) + } + searchFrom = end + } + return ids +} + func executeMessagesSend(rt *shortcut.RuntimeContext) error { identity := messagesSendIdentity(rt) body := messagesSendBody(rt) @@ -499,7 +590,7 @@ func resolvedUserMarkdownParams( if target.GroupID != "" { body = helpers.NormalizeMessageMentions(body, atOpenIDs, atAll, true) } - content, _ := json.Marshal(map[string]string{"title": title, "text": body}) + content, _ := jsonutil.Marshal(map[string]string{"title": title, "text": body}) params := rt.AddAIMessageTag(map[string]any{ "msgType": "markdown", "content": string(content), From 00ca448aa24f9b6cde51f8730ddcc4c00a35cf4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 13:34:45 +0800 Subject: [PATCH 245/250] docs(release): add chat mention fix fragment --- .changes/chat-user-mention-tokens.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changes/chat-user-mention-tokens.md diff --git a/.changes/chat-user-mention-tokens.md b/.changes/chat-user-mention-tokens.md new file mode 100644 index 00000000..3f070b7b --- /dev/null +++ b/.changes/chat-user-mention-tokens.md @@ -0,0 +1,5 @@ +--- +category: Fixed +--- + +- **Chat user mentions** — preserves literal `<@openDingTalkId>` tokens in current-user Markdown messages and rejects mismatches between message-body mentions and mention flags before sending. From f3b0fcdc4c86b1da4ac83256daaf82d2d781b93c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 13:53:59 +0800 Subject: [PATCH 246/250] test(calendar): verify aliases preserve confirmation --- .../param_alias_payload_equivalence_test.go | 59 +++++++++++++++++-- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/internal/app/param_alias_payload_equivalence_test.go b/internal/app/param_alias_payload_equivalence_test.go index 60a46a00..542c9b8a 100644 --- a/internal/app/param_alias_payload_equivalence_test.go +++ b/internal/app/param_alias_payload_equivalence_test.go @@ -73,13 +73,13 @@ var paramAliasCompleteCommands = map[string][]string{ "calendar +suggestion": {"calendar", "+suggestion", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"}, "calendar +update": {"calendar", "+update", "--event", "event-1", "--title", "Fixture Updated Meeting", "--desc", "fixture updated description", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--add-attendees", "user-2", "--remove-attendees", "user-1", "--yes"}, "calendar busy search": {"calendar", "busy", "search", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"}, - "calendar event create": {"calendar", "event", "create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--remind-minutes", "15", "--timezone", "Asia/Shanghai", "--rooms", "room-1,room-2", "--yes"}, + "calendar event create": {"calendar", "event", "create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--remind-minutes", "15", "--timezone", "Asia/Shanghai", "--rooms", "room-1,room-2"}, "calendar event list": {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"}, - "calendar event respond": {"calendar", "event", "respond", "--id", "event-1", "--status", "accepted", "--yes"}, + "calendar event respond": {"calendar", "event", "respond", "--id", "event-1", "--status", "accepted"}, "calendar event suggest": {"calendar", "event", "suggest", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"}, - "calendar event update": {"calendar", "event", "update", "--id", "event-1", "--timezone", "Asia/Shanghai", "--yes"}, - "calendar room add": {"calendar", "room", "add", "--event", "event-1", "--rooms", "room-1,room-2", "--yes"}, - "calendar room delete": {"calendar", "room", "delete", "--event", "event-1", "--rooms", "room-1,room-2", "--yes"}, + "calendar event update": {"calendar", "event", "update", "--id", "event-1", "--timezone", "Asia/Shanghai"}, + "calendar room add": {"calendar", "room", "add", "--event", "event-1", "--rooms", "room-1,room-2"}, + "calendar room delete": {"calendar", "room", "delete", "--event", "event-1", "--rooms", "room-1,room-2"}, "calendar room search": {"calendar", "room", "search", "--room-name", "Fixture Room", "--group-id", "group-1", "--start", "2027-03-10T09:00:00+08:00", "--end", "2027-03-10T10:00:00+08:00", "--page", "1", "--limit", "7"}, "chat +chat-messages": {"chat", "+chat-messages", "--group", "fixture-conversation"}, "chat +chat-add-bot": {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"}, @@ -687,6 +687,21 @@ var paramAliasCalendarPayloadCases = map[string]bool{ paramAliasPayloadCaseKey("calendar +update", "remove-user-ids"): true, } +// paramAliasCalendarConfirmationCases selects one newly reviewed alias for +// every Calendar Shortcut whose runtime contract requires user confirmation. +// The complete Calendar matrix proves confirmed canonical/alias payload +// equality; these representatives additionally prove semantic normalization +// cannot cross the confirmation boundary before the first transport call. +var paramAliasCalendarConfirmationCases = map[string]bool{ + paramAliasPayloadCaseKey("calendar +book", "summary"): true, + paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"): true, + paramAliasPayloadCaseKey("calendar +create", "summary"): true, + paramAliasPayloadCaseKey("calendar +invite", "id"): true, + paramAliasPayloadCaseKey("calendar +reschedule", "from"): true, + paramAliasPayloadCaseKey("calendar +rsvp", "response-status"): true, + paramAliasPayloadCaseKey("calendar +update", "event-id"): true, +} + func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) { concepts, err := cli.LoadParamConcepts() if err != nil { @@ -772,6 +787,7 @@ func TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivale } executed := make(map[string]bool) + executedConfirmation := make(map[string]bool) for _, fixture := range concepts.Fixture { caseKey := paramAliasPayloadCaseKey(fixture.Command, fixture.Emitted) if !paramAliasCalendarPayloadCases[caseKey] { @@ -790,6 +806,10 @@ func TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivale t.Fatalf("complete Calendar command must contain canonical --%s exactly once; replacements=%d args=%v", fixture.Expect, replacements, canonicalArgs) } assertParamAliasFinalPayloadEquivalent(t, fixture.Command, canonicalArgs, aliasArgs) + if paramAliasCalendarConfirmationCases[caseKey] { + executedConfirmation[caseKey] = true + assertParamAliasCannotBypassConfirmation(t, aliasArgs) + } }) } @@ -801,6 +821,35 @@ func TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivale if len(executed) != len(paramAliasCalendarPayloadCases) { t.Fatalf("Calendar final-payload coverage = %d, want %d", len(executed), len(paramAliasCalendarPayloadCases)) } + for caseKey := range paramAliasCalendarConfirmationCases { + if !executedConfirmation[caseKey] { + t.Errorf("Calendar confirmation case %q has no active reviewed fixture", caseKey) + } + } + if len(executedConfirmation) != len(paramAliasCalendarConfirmationCases) { + t.Fatalf("Calendar confirmation coverage = %d, want %d", len(executedConfirmation), len(paramAliasCalendarConfirmationCases)) + } +} + +func assertParamAliasCannotBypassConfirmation(t *testing.T, aliasArgs []string) { + t.Helper() + unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes") + if removals != 1 { + t.Fatalf("confirmation template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs) + } + + caller := ¶mAliasCaptureCaller{} + ctx, err := executeParamAliasPayloadE2E(t, caller, unconfirmedArgs...) + if ctx == nil { + t.Fatal("unconfirmed Calendar alias command skipped PreParse") + } + var appErr *apperrors.Error + if !errors.As(err, &appErr) || appErr.Reason != "confirmation_required" { + t.Fatalf("unconfirmed Calendar alias command error = %#v, want confirmation_required\nargs=%v", err, unconfirmedArgs) + } + if len(caller.calls) != 0 { + t.Fatalf("unconfirmed Calendar alias crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, caller.calls) + } } func assertParamAliasFinalPayloadEquivalent(t *testing.T, command string, canonicalArgs, aliasArgs []string) { From 63854705fdd7d6628215617fb76715f94b831f80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=8B=E8=B0=A8?= <2940480744@qq.com> Date: Wed, 19 Aug 2026 14:22:02 +0800 Subject: [PATCH 247/250] fix(chat): route direct media upload targets --- .changes/chat-user-mention-tokens.md | 1 + .../shortcut/chat/coverage_completion_test.go | 6 + internal/shortcut/chat/gap_fill_test.go | 113 ++++++++++++++++++ internal/shortcut/chat/unified_send.go | 19 ++- 4 files changed, 135 insertions(+), 4 deletions(-) diff --git a/.changes/chat-user-mention-tokens.md b/.changes/chat-user-mention-tokens.md index 3f070b7b..166f6708 100644 --- a/.changes/chat-user-mention-tokens.md +++ b/.changes/chat-user-mention-tokens.md @@ -3,3 +3,4 @@ category: Fixed --- - **Chat user mentions** — preserves literal `<@openDingTalkId>` tokens in current-user Markdown messages and rejects mismatches between message-body mentions and mention flags before sending. +- **Chat direct media** — uses the IM upload target field for current-user direct file, audio, and video uploads, then uses the Chat receiver field for final message delivery. diff --git a/internal/shortcut/chat/coverage_completion_test.go b/internal/shortcut/chat/coverage_completion_test.go index 490e48ab..2ea6714a 100644 --- a/internal/shortcut/chat/coverage_completion_test.go +++ b/internal/shortcut/chat/coverage_completion_test.go @@ -519,6 +519,12 @@ func TestCrossPlatformCoverageMessagesSendRejectsMismatchedCurrentUserMentions(t atIDs: fixtureCurrentDOpenID, wantErr: "必须在正文中使用对应", }, + { + name: "declared member only appears as a longer token prefix", + body: "@" + fixtureCurrentDOpenID + "_suffix 请查收", + atIDs: fixtureCurrentDOpenID, + wantErr: "必须在正文中使用对应", + }, { name: "body member missing from declaration", body: "<@" + fixtureCurrentDOpenID + "> 请查收", diff --git a/internal/shortcut/chat/gap_fill_test.go b/internal/shortcut/chat/gap_fill_test.go index 2526af79..0946632c 100644 --- a/internal/shortcut/chat/gap_fill_test.go +++ b/internal/shortcut/chat/gap_fill_test.go @@ -585,6 +585,119 @@ func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileFlow(t *testing.T) } } +func TestCrossPlatformCoverageMessagesSendCurrentUserDirectLocalFileUsesTransportSpecificTargets(t *testing.T) { + t.Chdir(t.TempDir()) + if err := os.WriteFile("direct.bin", []byte("direct-file"), 0o600); err != nil { + t.Fatal(err) + } + uploadServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPut { + t.Errorf("upload method = %s", r.Method) + } + if _, err := io.Copy(io.Discard, r.Body); err != nil { + t.Error(err) + } + w.WriteHeader(http.StatusOK) + })) + t.Cleanup(uploadServer.Close) + + tests := []struct { + name string + targetArgs []string + requestedType string + wantOpenID string + wantUserResolve bool + }{ + { + name: "explicit open id file", + targetArgs: []string{"--open-dingtalk-id", fixtureCurrentDOpenID}, + requestedType: "file", + wantOpenID: fixtureCurrentDOpenID, + }, + { + name: "resolved user audio", + targetArgs: []string{"--user", "user-id"}, + requestedType: "audio", + wantOpenID: "D-resolved", + wantUserResolve: true, + }, + { + name: "explicit open id video", + targetArgs: []string{"--open-dingtalk-id", fixtureCurrentDOpenID2}, + requestedType: "video", + wantOpenID: fixtureCurrentDOpenID2, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + fake := &larkAlignmentCaller{responses: map[string]string{ + "im/init_conversation_file_upload": `{"resourceUrl":"` + uploadServer.URL + `","uploadKey":"upload-key"}`, + "im/commit_conversation_file_upload": `{"result":{"dentryId":31,"spaceId":41}}`, + "chat/send_personal_message": `{"result":{"openMessageId":"sent-direct-file"}}`, + }} + helpers.InitDeps(fake) + root := newPlatformCoverageRoot() + var output bytes.Buffer + root.SetOut(&output) + args := []string{ + "chat", "+messages-send", "--identity", "user", + "--msg-type", tt.requestedType, + "--file", "./direct.bin", + "--idempotency-key", "direct-" + tt.requestedType, + "--yes", + } + args = append(args, tt.targetArgs...) + root.SetArgs(args) + if err := root.Execute(); err != nil { + t.Fatal(err) + } + + callOffset := 0 + if tt.wantUserResolve { + if len(fake.calls) == 0 || fake.calls[0].product != "contact" || + fake.calls[0].tool != "search_contact_by_key_word" { + t.Fatalf("resolution call = %#v", fake.calls) + } + callOffset = 1 + } + if len(fake.calls) != callOffset+3 { + t.Fatalf("calls = %#v, want resolution plus init, commit, send", fake.calls) + } + initCall := fake.calls[callOffset] + commitCall := fake.calls[callOffset+1] + sendCall := fake.calls[callOffset+2] + for _, call := range []larkAlignmentCall{initCall, commitCall} { + if call.product != "im" || call.args["openDingTalkId"] != tt.wantOpenID { + t.Fatalf("upload call = %#v, want openDingTalkId %q", call, tt.wantOpenID) + } + if _, exists := call.args["receiverOpenDingTalkId"]; exists { + t.Fatalf("send-only receiver field leaked into upload call: %#v", call.args) + } + } + if initCall.tool != "init_conversation_file_upload" || + commitCall.tool != "commit_conversation_file_upload" { + t.Fatalf("upload calls = %#v, %#v", initCall, commitCall) + } + if sendCall.product != "chat" || sendCall.tool != "send_personal_message" || + sendCall.args["receiverOpenDingTalkId"] != tt.wantOpenID { + t.Fatalf("send call = %#v, want receiverOpenDingTalkId %q", sendCall, tt.wantOpenID) + } + if _, exists := sendCall.args["openDingTalkId"]; exists { + t.Fatalf("upload-only target field leaked into send call: %#v", sendCall.args) + } + + var payload map[string]any + if err := json.Unmarshal(output.Bytes(), &payload); err != nil { + t.Fatal(err) + } + if payload["requestedMessageType"] != tt.requestedType || + payload["effectiveMessageType"] != "file" { + t.Fatalf("output = %#v", payload) + } + }) + } +} + func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileDryRunAndFailures(t *testing.T) { t.Chdir(t.TempDir()) if err := os.WriteFile("fixture.bin", []byte("x"), 0o600); err != nil { diff --git a/internal/shortcut/chat/unified_send.go b/internal/shortcut/chat/unified_send.go index bd3c66d9..670ae6e8 100644 --- a/internal/shortcut/chat/unified_send.go +++ b/internal/shortcut/chat/unified_send.go @@ -664,8 +664,10 @@ func executeMessagesSendUserFile( if err != nil { return err } - targetArgs := map[string]any{} - addMessagesSendUserTarget(targetArgs, group, openID) + uploadTargetArgs := map[string]any{} + addMessagesSendUserUploadTarget(uploadTargetArgs, group, openID) + sendTargetArgs := map[string]any{} + addMessagesSendUserTarget(sendTargetArgs, group, openID) idempotencyKey := messagesSendIdempotencyKey(rt) if rt.DryRun() { return rt.Output(map[string]any{ @@ -678,6 +680,7 @@ func executeMessagesSendUserFile( { "identity": "user", "tool": "init/commit_conversation_file_upload", + "target": uploadTargetArgs, "file": map[string]any{ "path": rawPath, "name": meta.FileName, @@ -689,7 +692,7 @@ func executeMessagesSendUserFile( "tool": "send_personal_message", "requestedMessageType": requestedType, "effectiveMessageType": "file", - "target": targetArgs, + "target": sendTargetArgs, }, }, }) @@ -698,7 +701,7 @@ func executeMessagesSendUserFile( rt.Command().Context(), messagesSendFileUploadTimeout) defer cancelUpload() commitText, err := helpers.UploadConversationLocalFile( - uploadContext, targetArgs, meta, idempotencyKey) + uploadContext, uploadTargetArgs, meta, idempotencyKey) if err != nil { return err } @@ -744,6 +747,14 @@ func addMessagesSendUserTarget(params map[string]any, group, openID string) { params["receiverOpenDingTalkId"] = openID } +func addMessagesSendUserUploadTarget(params map[string]any, group, openID string) { + if group != "" { + params["openConversationId"] = group + return + } + params["openDingTalkId"] = openID +} + func nonEmptyStringCount(values ...string) int { count := 0 for _, value := range values { From e217901a6bc21e76346a3025ddbd8d34a31a4dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 19 Aug 2026 14:37:22 +0800 Subject: [PATCH 248/250] fix(recruit): validate education list filter --- internal/helpers/recruit.go | 4 ++++ internal/helpers/recruit_test.go | 18 ++++++++++++++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/internal/helpers/recruit.go b/internal/helpers/recruit.go index 62e271ff..cb2979c9 100644 --- a/internal/helpers/recruit.go +++ b/internal/helpers/recruit.go @@ -470,6 +470,10 @@ func validateRecruitList(cmd *cobra.Command, _ []string) error { if cmd.Flags().Changed("size") && (size < 1 || size > 100) { return apperrors.NewValidation("--size 必须在 1 到 100 之间") } + requiredEdu, _ := cmd.Flags().GetInt("required-edu") + if cmd.Flags().Changed("required-edu") && (requiredEdu < 1 || requiredEdu > 9) { + return apperrors.NewValidation("--required-edu 必须在 1 到 9 之间") + } return nil } diff --git a/internal/helpers/recruit_test.go b/internal/helpers/recruit_test.go index da320b23..bb8879b4 100644 --- a/internal/helpers/recruit_test.go +++ b/internal/helpers/recruit_test.go @@ -85,7 +85,7 @@ func TestRecruitJobListWrapsQueryParameters(t *testing.T) { cmd := prepareRecruitTestCommand(newRecruitJobListCommand()) cmd.SetArgs([]string{ "--keyword", "Java", "--status", "open,draft", "--creator-user-ids", "u1,u2", - "--campus=false", "--cursor", "10", "--size", "30", + "--campus=false", "--required-edu", "9", "--cursor", "10", "--size", "30", }) if err := cmd.Execute(); err != nil { t.Fatal(err) @@ -100,7 +100,7 @@ func TestRecruitJobListWrapsQueryParameters(t *testing.T) { if !ok { t.Fatalf("param = %#v, want object", caller.args["param"]) } - if param["keyword"] != "Java" || param["campus"] != false { + if param["keyword"] != "Java" || param["campus"] != false || param["requiredEdu"] != 9 { t.Fatalf("param = %#v", param) } statuses, ok := param["statusList"].([]int) @@ -189,6 +189,20 @@ func TestRecruitJobListDefaultsAndValidation(t *testing.T) { if err := badSize.Execute(); err == nil || !strings.Contains(err.Error(), "1 到 100") { t.Fatalf("invalid size error = %v", err) } + + for _, requiredEdu := range []string{"0", "10"} { + t.Run("required edu "+requiredEdu, func(t *testing.T) { + caller := withRecruitCaller(t) + invalid := prepareRecruitTestCommand(newRecruitJobListCommand()) + invalid.SetArgs([]string{"--required-edu", requiredEdu}) + if err := invalid.Execute(); err == nil || !strings.Contains(err.Error(), "1 到 9") { + t.Fatalf("required edu %s error = %v", requiredEdu, err) + } + if len(caller.calls) != 0 { + t.Fatalf("MCP calls with invalid required edu = %d, want 0", len(caller.calls)) + } + }) + } } func TestRecruitJobGetDispatchesJobID(t *testing.T) { From ed1ebe5d03a5650f4aa2cb7c3622e4d661f32a56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=81=8B=E5=B7=9D?= Date: Wed, 19 Aug 2026 16:11:24 +0800 Subject: [PATCH 249/250] chore: retrigger CI From 6240584ae23c498019a8b4a5ca3e8502cee05a02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=89=8D=E6=B4=A5?= Date: Wed, 19 Aug 2026 19:13:40 +0800 Subject: [PATCH 250/250] chore(policy): approve group role flag migration --- .../approved-flag-migrations-v1.json | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json index 6ddbafb7..700f46d0 100644 --- a/scripts/policy/interface-migrations/approved-flag-migrations-v1.json +++ b/scripts/policy/interface-migrations/approved-flag-migrations-v1.json @@ -760,6 +760,39 @@ "state": "consumed", "reason": "保留旧 argv 兼容性，并将 IM ID 规范 flag 设为唯一可见入口" }, + { + "command": "dws chat group-role set-user", + "legacy": { + "name": "role-ids", + "before": { + "present": true, + "type": "string", + "scope": "local", + "required": true + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "hidden": true, + "alias_of": "role-id" + } + }, + "canonical": { + "name": "role-id", + "before": { + "present": false + }, + "after": { + "present": true, + "type": "string", + "scope": "local", + "required": true + } + }, + "state": "pending", + "reason": "保留旧 argv 兼容性，并将单值群身份 flag 设为唯一可见入口" + }, { "command": "dws chat group-role update", "legacy": {