nullkey
567d7ac74e
Adds the structured-output and agent-help surface plus root-level signal
handling so AI agents (and humans working through pipes) get a stable
wire contract.
* --format text|json|ndjson flag, registered per-command on outputs that
need it; default text on TTY, json on pipe. --jq <expr> pairs with json
/ ndjson to filter or project. FormatOptions absorbs JQ; WantsJSON()
helper for the JSON dispatch.
* WriteNDJSON helper in internal/format/ (per ndjson.org: one JSON value
per line, arrays split element-per-line, empty slice → zero bytes).
* chat / agent invoke wire --format ndjson via SDK StreamResponse /
AgentStreamResponse 1:1 passthrough. Both commands detect ctx.Cancelled
in every stream + session-create path and emit a stable
"operation.cancelled" code on Ctrl-C / SIGTERM.
* main.go wires signal.NotifyContext(SIGINT, SIGTERM) into the root
context so long-running commands run their cancellation cleanup
(re-emit auto-created session id, etc); the process exits 130 when
the context was signal-cancelled, matching Unix convention.
* MCP chat / agent_invoke output schemas extended with thinking /
tool_calls / assistant_message_id (server-side accumulated; MCP
tools/call has no standard partial-response). doc_view and doc_download
now use doc_id (not knowledge_id) so agents see a single id naming
convention across all tools — matches the chunk_list / search_chunks
schemas and the CLI's <doc-id> positional.
* SetAgentHelp(cmd, AgentHelp{...}) — opt-in machine-friendly --help
payload activated by WEKNORA_AGENT_HELP=1. Applied to chat / kb list.
* kb create --storage-provider <local|minio|cos|tos|s3|oss|ks3> — sets
the new KB's storage_provider_config.provider at creation time (server
does not expose it on update). Required on self-hosted deployments
where the server-side default doesn't pre-populate a provider —
without it, subsequent doc upload returns a misleading "kb not found".
52 lines
1.6 KiB
Go
52 lines
1.6 KiB
Go
// Package-level note:
|
|
//
|
|
// SetAgentHelp wires structured agent-targeted help onto a cobra command.
|
|
// Current coverage: chat, kb list. Adding it to another command requires
|
|
// touching only that command's NewCmd (a 5-line copy of the existing call
|
|
// sites).
|
|
package cmdutil
|
|
|
|
import (
|
|
"encoding/json"
|
|
"io"
|
|
"os"
|
|
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
// AgentHelp is the structured help blob emitted when an agent invokes
|
|
// `weknora <command> --help` with WEKNORA_AGENT_HELP=1. Distinct from
|
|
// cobra's human help text — agent-readable JSON keyed by stable fields
|
|
// so an LLM doesn't need to scrape the human help table.
|
|
type AgentHelp struct {
|
|
UsedFor string `json:"used_for"`
|
|
RequiredFlags []string `json:"required_flags,omitempty"`
|
|
Examples []string `json:"examples,omitempty"`
|
|
Output string `json:"output,omitempty"`
|
|
}
|
|
|
|
// SetAgentHelp attaches agent-targeted help metadata to a command. The
|
|
// original HelpFunc is preserved for the human path; the agent path
|
|
// activates only when WEKNORA_AGENT_HELP=1 (so human `--help` is
|
|
// unaffected).
|
|
//
|
|
// Currently applied to a small set of representative commands (chat,
|
|
// kb list); extend by calling SetAgentHelp in each command's NewCmd.
|
|
func SetAgentHelp(cmd *cobra.Command, ah AgentHelp) {
|
|
origHelp := cmd.HelpFunc()
|
|
cmd.SetHelpFunc(func(c *cobra.Command, args []string) {
|
|
if os.Getenv("WEKNORA_AGENT_HELP") == "1" {
|
|
emitAgentHelp(c.OutOrStdout(), ah)
|
|
return
|
|
}
|
|
origHelp(c, args)
|
|
})
|
|
}
|
|
|
|
func emitAgentHelp(w io.Writer, ah AgentHelp) {
|
|
enc := json.NewEncoder(w)
|
|
enc.SetEscapeHTML(false)
|
|
enc.SetIndent("", " ")
|
|
_ = enc.Encode(ah)
|
|
}
|