feat(cli): agent-first WeKnora CLI

The `weknora` command-line client for the WeKnora RAG server. Full command
surface: kb / doc / chunk / session / message / agent / model / search / chat /
auth / profile / link / api / mcp / skills / config / doctor / schema /
exit-codes.

Agent-first wire contract: JSON envelope by default, typed error codes mapped to
stable exit codes, error.retry_argv / retryable / partial-failure status,
global --dry-run preview, the exit-10 confirmation protocol for writes, and
control/ANSI/Bidi input hygiene. Stateless env-credential auth
(WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use.
A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills
(`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
nullkey
2026-06-26 20:40:59 +08:00
committed by lyingbug
parent 445a4330fa
commit 6f8b825f5f
151 changed files with 7305 additions and 733 deletions
+23 -12
View File
@@ -26,12 +26,17 @@ var docCreateFields = []string{
// CreateOptions holds CLI flag values for `doc create`.
type CreateOptions struct {
Text string // --text (required): document text content (Markdown)
Name string // --name: document title
Title string // --title: document title (preferred; matches `doc update --title`)
Name string // --name: deprecated alias for --title
TagID string // --tag-id: associate with a tag
Channel string // --channel: ingestion-channel tag (default "api")
DryRun bool
}
// title returns the resolved document title, preferring --title over the
// deprecated --name alias.
func (o *CreateOptions) title() string { return cmp.Or(o.Title, o.Name) }
// CreateService is the narrow SDK surface for `doc create`.
// *sdk.Client satisfies it.
type CreateService interface {
@@ -54,12 +59,12 @@ don't require a file upload or remote URL. KB resolution follows the standard
4-level chain: --kb flag > WEKNORA_KB_ID env > .weknora/project.yaml > error.
--text <content> Document text in Markdown format (required).
--name <title> Display title stored with the entry.
--title <title> Display title stored with the entry (matches doc update --title).
--tag-id <id> Associate the new entry with a tag.
--channel <name> Override the ingestion-channel tag (default "api").`,
Example: ` weknora doc create --text "# Meeting Notes\n\nAction items: ..."
weknora doc create --text "$(cat notes.md)" --name "Sprint Notes" --kb my-kb
weknora doc create --text "API usage guide" --name "API Guide" --tag-id tag_abc`,
weknora doc create --text "$(cat notes.md)" --title "Sprint Notes" --kb my-kb
weknora doc create --text "API usage guide" --title "API Guide" --tag-id tag_abc`,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, _ []string) error {
fopts, err := cmdutil.CheckFormatFlag(c)
@@ -78,9 +83,9 @@ don't require a file upload or remote URL. KB resolution follows the standard
if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{
Action: "doc.create",
Args: map[string]any{
"text": opts.Text,
"name": opts.Name,
"kb": kbID,
"text": opts.Text,
"title": opts.title(),
"kb": kbID,
},
}); handled {
return err
@@ -100,7 +105,9 @@ don't require a file upload or remote URL. KB resolution follows the standard
}
cmdutil.AddKBFlag(cmd)
cmd.Flags().StringVar(&opts.Text, "text", "", "Document text content in Markdown format (required)")
cmd.Flags().StringVar(&opts.Name, "name", "", "Document title")
cmd.Flags().StringVar(&opts.Title, "title", "", "Document title")
cmd.Flags().StringVar(&opts.Name, "name", "", "Document title (deprecated: use --title)")
_ = cmd.Flags().MarkDeprecated("name", "use --title instead")
cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Tag id to associate with the new entry")
cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")")
_ = cmd.MarkFlagRequired("text")
@@ -108,8 +115,12 @@ don't require a file upload or remote URL. KB resolution follows the standard
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "Create a knowledge entry from inline Markdown text. KB resolved via --kb flag, WEKNORA_KB_ID env, or project link. Emits the created Knowledge object with its id.",
RequiredFlags: []string{"--text"},
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, title, parse_status",
RequiredFlags: []string{"--text", "--kb (or WEKNORA_KB_ID / project link)"},
Examples: []string{
`weknora doc create --kb kb_eng --text "# Runbook\n\nRestart steps: ..."`,
`weknora doc create --kb kb_eng --text "$(cat notes.md)" --title "Sprint Notes"`,
},
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, title, parse_status",
})
return cmd
}
@@ -123,7 +134,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
return cmdutil.NewFlagError(fmt.Errorf("--text is required"))
}
req := &sdk.CreateManualKnowledgeRequest{
Title: opts.Name,
Title: opts.title(),
Content: opts.Text,
TagID: opts.TagID,
Channel: cmp.Or(opts.Channel, uploadChannel),
@@ -135,7 +146,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, k, nil)
}
displayed := opts.Name
displayed := opts.title()
if displayed == "" {
displayed = k.Title
}