319 lines
9.8 KiB
Go
319 lines
9.8 KiB
Go
// 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 (
|
|
stderrors "errors"
|
|
"strconv"
|
|
"strings"
|
|
|
|
"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
|
|
apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
|
|
"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
const (
|
|
devdocArticleSearchTool = "search_open_platform_docs_rag"
|
|
devdocArticleSearchLegacyTool = "search_open_platform_docs"
|
|
devdocErrorDiagnoseTool = "search_open_error_code_rag"
|
|
)
|
|
|
|
func init() {
|
|
RegisterPublic(func() Handler {
|
|
return devdocHandler{}
|
|
})
|
|
}
|
|
|
|
type devdocHandler struct{}
|
|
|
|
func (devdocHandler) Name() string {
|
|
return "devdoc"
|
|
}
|
|
|
|
func (devdocHandler) Command(runner executor.Runner) *cobra.Command {
|
|
root := &cobra.Command{
|
|
Use: "devdoc",
|
|
Short: "开放平台文档搜索",
|
|
Args: cobra.NoArgs,
|
|
TraverseChildren: true,
|
|
DisableAutoGenTag: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
return cmd.Help()
|
|
},
|
|
}
|
|
article := &cobra.Command{
|
|
Use: "article",
|
|
Short: "文档文章",
|
|
Args: cobra.NoArgs,
|
|
TraverseChildren: true,
|
|
DisableAutoGenTag: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
return cmd.Help()
|
|
},
|
|
}
|
|
article.AddCommand(newDevdocArticleSearchCommand(runner))
|
|
root.AddCommand(article)
|
|
errs := &cobra.Command{
|
|
Use: "error",
|
|
Short: "错误排查",
|
|
Args: cobra.NoArgs,
|
|
TraverseChildren: true,
|
|
DisableAutoGenTag: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
return cmd.Help()
|
|
},
|
|
}
|
|
errs.AddCommand(newDevdocErrorDiagnoseCommand(runner))
|
|
root.AddCommand(errs)
|
|
return root
|
|
}
|
|
|
|
func newDevdocArticleSearchCommand(runner executor.Runner) *cobra.Command {
|
|
cmd := &cobra.Command{
|
|
Use: "search [keyword]",
|
|
Short: "搜索开放平台文档",
|
|
Args: cobra.MaximumNArgs(1),
|
|
DisableAutoGenTag: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
keyword := devdocFlagOrFallback(cmd, "query", "keyword")
|
|
if keyword == "" && len(args) > 0 {
|
|
keyword = strings.TrimSpace(args[0])
|
|
}
|
|
if keyword == "" {
|
|
return apperrors.NewValidation("--query is required")
|
|
}
|
|
page, _ := cmd.Flags().GetInt("page")
|
|
if page < 1 {
|
|
page = 1
|
|
}
|
|
size, _ := cmd.Flags().GetInt("size")
|
|
if size < 1 {
|
|
size = 10
|
|
}
|
|
cursor := devdocFlagOrFallback(cmd, "cursor")
|
|
return runDevdocToolWithFallback(cmd, runner, devdocArticleSearchTool,
|
|
devdocSearchParams(keyword, page, size, cursor),
|
|
devdocArticleSearchLegacyTool,
|
|
devdocLegacySearchParams(keyword, page, size, cursor))
|
|
},
|
|
}
|
|
preferLegacyLeaf(cmd)
|
|
cmd.Flags().String("query", "", "搜索关键词 (必填)")
|
|
addDevdocHiddenStringFlag(cmd, "keyword", "--query 的悟空兼容别名")
|
|
cmd.Flags().Int("page", 1, "分页页码 (从 1 开始，默认 1)")
|
|
cmd.Flags().String("cursor", "", "分页游标，翻页传上次返回的 nextCursor；传入后不再使用 --page")
|
|
cmd.Flags().Int("size", 10, "分页大小 (默认 10)")
|
|
return cmd
|
|
}
|
|
|
|
func newDevdocErrorDiagnoseCommand(runner executor.Runner) *cobra.Command {
|
|
cmd := &cobra.Command{
|
|
Use: "diagnose",
|
|
Aliases: []string{"troubleshoot"},
|
|
Short: "排查开放平台调用错误",
|
|
Args: cobra.NoArgs,
|
|
DisableAutoGenTag: true,
|
|
RunE: func(cmd *cobra.Command, args []string) error {
|
|
errorCode := devdocFlagOrFallback(cmd, "error-code")
|
|
errorMessage := devdocFlagOrFallback(cmd, "error-message")
|
|
api := devdocFlagOrFallback(cmd, "api")
|
|
contextText := devdocFlagOrFallback(cmd, "context")
|
|
requestID := devdocFlagOrFallback(cmd, "request-id")
|
|
query := devdocFlagOrFallback(cmd, "query")
|
|
|
|
parts := make([]string, 0, 4)
|
|
for _, part := range []string{query, errorMessage, api, contextText} {
|
|
if trimmed := strings.TrimSpace(part); trimmed != "" {
|
|
parts = append(parts, trimmed)
|
|
}
|
|
}
|
|
query = strings.Join(parts, " ")
|
|
if errorCode == "" && requestID == "" && query == "" {
|
|
return apperrors.NewValidation("--query, --error-code, or --request-id is required")
|
|
}
|
|
page, _ := cmd.Flags().GetInt("page")
|
|
if page < 1 {
|
|
page = 1
|
|
}
|
|
size, _ := cmd.Flags().GetInt("size")
|
|
if size < 1 {
|
|
size = 10
|
|
}
|
|
cursor := devdocFlagOrFallback(cmd, "cursor")
|
|
|
|
params := map[string]any{
|
|
"size": size,
|
|
}
|
|
if cursor != "" {
|
|
params["cursor"] = cursor
|
|
} else {
|
|
params["page"] = page
|
|
}
|
|
if errorCode != "" {
|
|
params["errorCode"] = errorCode
|
|
}
|
|
if query != "" {
|
|
params["query"] = query
|
|
}
|
|
if requestID != "" {
|
|
params["requestId"] = requestID
|
|
}
|
|
|
|
fallbackQuery := strings.TrimSpace(strings.Join([]string{errorCode, query, requestID}, " "))
|
|
return runDevdocToolWithFallbacks(cmd, runner, devdocErrorDiagnoseTool, params, []devdocFallbackTool{
|
|
{tool: devdocArticleSearchTool, params: devdocSearchParams(fallbackQuery, page, size, cursor)},
|
|
{tool: devdocArticleSearchLegacyTool, params: devdocLegacySearchParams(fallbackQuery, page, size, cursor)},
|
|
})
|
|
},
|
|
}
|
|
cmd.Flags().String("query", "", "原始排查问题")
|
|
cmd.Flags().String("error-code", "", "错误码")
|
|
cmd.Flags().String("error-message", "", "错误描述，会合并进原始问题")
|
|
cmd.Flags().String("api", "", "API 名称，会合并进原始问题作为补充检索词")
|
|
cmd.Flags().String("context", "", "额外排查上下文，会合并进原始问题")
|
|
cmd.Flags().String("request-id", "", "开放平台 requestId")
|
|
cmd.Flags().Int("page", 1, "分页页码 (从 1 开始，默认 1)")
|
|
cmd.Flags().String("cursor", "", "分页游标，翻页传上次返回的 nextCursor；传入后不再使用 --page")
|
|
cmd.Flags().Int("size", 10, "分页大小 (默认 10)")
|
|
return cmd
|
|
}
|
|
|
|
func devdocSearchParams(keyword string, page int, size int, cursor string) map[string]any {
|
|
params := map[string]any{
|
|
"keyword": keyword,
|
|
"size": size,
|
|
}
|
|
if cursor != "" {
|
|
params["cursor"] = cursor
|
|
} else {
|
|
params["page"] = page
|
|
}
|
|
return params
|
|
}
|
|
|
|
func devdocLegacySearchParams(keyword string, page int, size int, cursor string) map[string]any {
|
|
return map[string]any{
|
|
"keyword": keyword,
|
|
"page": devdocPageFromCursor(page, cursor),
|
|
"size": size,
|
|
}
|
|
}
|
|
|
|
func devdocPageFromCursor(page int, cursor string) int {
|
|
if cursor == "" {
|
|
return page
|
|
}
|
|
cursorPage, err := strconv.Atoi(cursor)
|
|
if err == nil && cursorPage > 0 {
|
|
return cursorPage
|
|
}
|
|
return page
|
|
}
|
|
|
|
func runDevdocTool(cmd *cobra.Command, runner executor.Runner, tool string, params map[string]any) error {
|
|
return runDevdocToolWithFallback(cmd, runner, tool, params, "", nil)
|
|
}
|
|
|
|
type devdocFallbackTool struct {
|
|
tool string
|
|
params map[string]any
|
|
}
|
|
|
|
func runDevdocToolWithFallback(cmd *cobra.Command, runner executor.Runner, tool string, params map[string]any, fallbackTool string, fallbackParams map[string]any) error {
|
|
var fallbacks []devdocFallbackTool
|
|
if fallbackTool != "" {
|
|
fallbacks = append(fallbacks, devdocFallbackTool{tool: fallbackTool, params: fallbackParams})
|
|
}
|
|
return runDevdocToolWithFallbacks(cmd, runner, tool, params, fallbacks)
|
|
}
|
|
|
|
func runDevdocToolWithFallbacks(cmd *cobra.Command, runner executor.Runner, tool string, params map[string]any, fallbacks []devdocFallbackTool) error {
|
|
invocation := executor.NewHelperInvocation(
|
|
cobracmd.LegacyCommandPath(cmd),
|
|
"devdoc",
|
|
tool,
|
|
params,
|
|
)
|
|
if commandDryRun(cmd) {
|
|
return writeCommandPayload(cmd, invocation)
|
|
}
|
|
result, err := runner.Run(cmd.Context(), invocation)
|
|
for _, fallback := range fallbacks {
|
|
if err == nil || !isDevdocToolNotFoundError(err) {
|
|
break
|
|
}
|
|
if fallback.tool == "" {
|
|
continue
|
|
}
|
|
fallbackParams := fallback.params
|
|
if fallbackParams == nil {
|
|
fallbackParams = params
|
|
}
|
|
fallbackInvocation := executor.NewHelperInvocation(
|
|
cobracmd.LegacyCommandPath(cmd),
|
|
"devdoc",
|
|
fallback.tool,
|
|
fallbackParams,
|
|
)
|
|
result, err = runner.Run(cmd.Context(), fallbackInvocation)
|
|
}
|
|
if err != nil {
|
|
return err
|
|
}
|
|
return writeCommandPayload(cmd, result)
|
|
}
|
|
|
|
func isDevdocToolNotFoundError(err error) bool {
|
|
if err == nil {
|
|
return false
|
|
}
|
|
msg := normalizedDevdocErrorText(err)
|
|
return strings.Contains(msg, "tool not found") ||
|
|
strings.Contains(msg, "unknown tool") ||
|
|
strings.Contains(msg, "mcp_tool_not_found") ||
|
|
strings.Contains(msg, "tool metadata api error") ||
|
|
strings.Contains(msg, "未找到指定工具")
|
|
}
|
|
|
|
func normalizedDevdocErrorText(err error) string {
|
|
parts := []string{strings.ToLower(err.Error())}
|
|
var typed *apperrors.Error
|
|
if stderrors.As(err, &typed) && typed != nil {
|
|
parts = append(parts,
|
|
strings.ToLower(typed.Reason),
|
|
strings.ToLower(typed.ServerDiag.ServerErrorCode),
|
|
strings.ToLower(typed.ServerDiag.TechnicalDetail),
|
|
strings.ToLower(typed.Hint),
|
|
)
|
|
}
|
|
return strings.Join(parts, " ")
|
|
}
|
|
|
|
func devdocFlagOrFallback(cmd *cobra.Command, primary string, aliases ...string) string {
|
|
names := append([]string{primary}, aliases...)
|
|
for _, name := range names {
|
|
value, err := cmd.Flags().GetString(name)
|
|
if err == nil && strings.TrimSpace(value) != "" {
|
|
return strings.TrimSpace(value)
|
|
}
|
|
}
|
|
return ""
|
|
}
|
|
|
|
func addDevdocHiddenStringFlag(cmd *cobra.Command, name, usage string) {
|
|
cmd.Flags().String(name, "", usage)
|
|
_ = cmd.Flags().MarkHidden(name)
|
|
}
|