devdoc

var SearchDocs = shortcut.Shortcut{
	OutputRollout: output.RolloutUnifiedActive,
	Service:       "devdoc",
	Command:       "+search-docs",
	Product:       "devdoc",
	Description:   "审计钉钉开放平台语义文档搜索结果",
	Intent:        "需要语义搜索钉钉开放平台文档且明确接受无法证明 query zero-match 时才使用；当前 Shortcut 保持 unavailable，请路由到 raw `devdoc article search`。",
	Risk:          shortcut.RiskRead,
	Hidden:        true,
	Availability:  shortcut.AvailabilityUnavailable,
	Safety: contract.SafetySpec{
		Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
	},
	Contract: corecmd.ContractDecl{
		Identity: contract.ToolIdentitySpec{
			ProductID: "devdoc", Name: "shortcut_search_docs", CanonicalPath: "devdoc.shortcut_search_docs",
			CLIPath: "devdoc +search-docs", PrimaryCLIPath: "devdoc +search-docs",
		},
		Description: "审计钉钉开放平台语义文档搜索结果",
		Interface: &contract.InterfaceSpec{
			Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceUnavailable, Reason: devdocCompositeReason,
		},
		Selection: contract.SelectionSpec{
			AgentSummary: "审计钉钉开放平台语义文档搜索结果",
			UseWhen:      []string{"需要语义搜索钉钉开放平台文档且明确接受无法证明 query zero-match 时才使用；当前 Shortcut 保持 unavailable，请路由到 raw `devdoc article search`。"},
			AvoidWhen:    []string{"需要精确匹配或保证零命中时不要使用；搜索用户业务文档时使用 drive/wiki/doc"},
			Examples:     []string{`dws devdoc +search-docs --query "OAuth2 接入" --size 10 --format json`},
		},
		Parameters: []contract.ParamDecl{
			{Name: "query", Property: "keyword"},
			{Name: "page", Property: "page", InterfaceType: "number"},
			{Name: "size", Property: "size", InterfaceType: "number"},
		},
		Result:     devdocSearchResult(),
		Pagination: devdocPagination(),
	},
	Flags: []shortcut.Flag{
		{Name: "query", Type: shortcut.FlagString, Required: true, Desc: "搜索关键词去除空白后必须非空"},
		{Name: "page", Type: shortcut.FlagInt, Default: "1", Desc: "页码必须大于 0"},
		{Name: "size", Type: shortcut.FlagInt, Default: "10", Desc: "每页数量必须在 1 到 50 之间"},
	},
	Constraints: []shortcut.Constraint{
		{Kind: shortcut.ConstraintCustom, Flags: []string{"query"}, Description: "搜索关键词去除空白后必须非空"},
		{Kind: shortcut.ConstraintCustom, Flags: []string{"page"}, Description: "页码必须大于 0"},
		{Kind: shortcut.ConstraintCustom, Flags: []string{"size"}, Description: "每页数量必须在 1 到 50 之间"},
	},
	Tips: []string{`dws devdoc +search-docs --query "OAuth2 接入" --size 10 --format json`},
	Validate: func(rt *shortcut.RuntimeContext) error {
		if strings.TrimSpace(rt.Str("query")) == "" {
			return apperrors.NewValidation("--query 不能为空")
		}
		if rt.Int("page") < 1 {
			return apperrors.NewValidation("--page 必须大于 0")
		}
		if size := rt.Int("size"); size < 1 || size > 50 {
			return apperrors.NewValidation("--size 必须在 1 到 50 之间")
		}
		return nil
	},
	Execute: executeSearchDocs,
}