refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws, azure, gcloud, openai/codex, github-copilot-cli) showed env-gated per-command --help blurbs are a Stripe-only pattern; gh uses env detect for telemetry only, and lark relies on installed agent Skills + MCP. Our cmd/mcp/serve already covers the dominant 2025/26 path, so internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden without precedent. - Drop internal/aiclient/ entirely (annotations + detect + tests) - Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc wiring in cmd/root.go - Migrate 4 command-level rules to standard Long help (visible to all, not env-gated): doc upload mode mutex, kb edit at-least-one, kb pin idempotent, search chunks channel mutex - Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines): audience preamble + Build / Architecture / Command Structure / Testing / Code Style / Error Handling. Drops sections absent in surveyed projects (Commit & PR Conventions, Who Uses This CLI) - Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments and docs that pointed at docs/superpowers/ — that directory is local-only / uncommitted, so refs are dead for outside readers - Drop forward-looking "once v0.2 ships" from README
This commit is contained in:
+7
-17
@@ -1,18 +1,13 @@
|
||||
// Package agentcmd holds the `weknora agent` command tree:
|
||||
// list / view / invoke. The directory is named `agent/` (matches cobra
|
||||
// noun-verb convention) but the Go package is `agentcmd` to avoid
|
||||
// shadowing cli/internal/agent (which owns SetAgentHelp + agent-aware
|
||||
// help rendering for AI coding agents — a distinct concept from
|
||||
// WeKnora's first-class custom-agent resources).
|
||||
// colliding with cobra's *cobra.Command identifier.
|
||||
//
|
||||
// Disambiguation in cli/AGENTS.md: "agent" in this subtree refers to
|
||||
// WeKnora's user-defined Custom Agents (server resource: GET/POST
|
||||
// /agents/...). The CLI's `agent invoke` calls /agent-chat/:session_id
|
||||
// which dispatches the agent's configured workflow (system prompt,
|
||||
// allowed tools, KB scope, retrieval thresholds, etc.). This is
|
||||
// orthogonal to AGENTS.md / SetAgentHelp, which exists so AI coding
|
||||
// agents (Claude Code, Cursor) consuming the CLI can read structured
|
||||
// hints from --help.
|
||||
// "agent" in this subtree refers to WeKnora's user-defined Custom
|
||||
// Agents (server resource: GET/POST /agents/...). The CLI's
|
||||
// `agent invoke` calls /agent-chat/:session_id which dispatches the
|
||||
// agent's configured workflow (system prompt, allowed tools, KB scope,
|
||||
// retrieval thresholds).
|
||||
package agentcmd
|
||||
|
||||
import (
|
||||
@@ -29,12 +24,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
Short: "Manage and invoke custom agents",
|
||||
Long: `Custom Agents bundle a system prompt, model, tool allow-list, and KB
|
||||
scope into an addressable resource. List visible agents, view a single
|
||||
agent's configuration, or invoke an agent against a query.
|
||||
|
||||
Distinct from the per-CLI ` + "`AGENTS.md`" + ` reference: that file documents the
|
||||
contract for AI coding agents (Claude Code / Cursor) running ` + "`weknora`" + `
|
||||
on a user's behalf. This subtree manages WeKnora's first-class custom-agent
|
||||
resources stored on the server.`,
|
||||
agent's configuration, or invoke an agent against a query.`,
|
||||
Args: cobra.NoArgs,
|
||||
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
|
||||
}
|
||||
|
||||
@@ -9,7 +9,6 @@ import (
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/aiclient"
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/format"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
@@ -18,7 +17,7 @@ import (
|
||||
)
|
||||
|
||||
// agentInvokeFields enumerates fields surfaced for `--json` discovery on
|
||||
// `agent invoke`. Matches invokeData below — the single-shot result
|
||||
// `agent invoke`. Matches invokeData below - the single-shot result
|
||||
// object with the agent's final answer plus the trace (references,
|
||||
// tool events).
|
||||
var agentInvokeFields = []string{
|
||||
@@ -36,7 +35,7 @@ type InvokeOptions struct {
|
||||
|
||||
// InvokeService is the narrow SDK surface this command depends on.
|
||||
//
|
||||
// CreateSession is called when --session is omitted — sessions are
|
||||
// CreateSession is called when --session is omitted - sessions are
|
||||
// agent-agnostic at creation (verified against
|
||||
// internal/handler/session/handler.go CreateSession, which only persists
|
||||
// {title, description}). The agent ID is supplied per-request via
|
||||
@@ -68,7 +67,7 @@ func NewCmdInvoke(f *cmdutil.Factory) *cobra.Command {
|
||||
tools, KB scope, retrieval thresholds) over SSE. By default a fresh session
|
||||
is auto-created; pass --session to continue an existing conversation. The
|
||||
agent picks the model, retrieval params, and tool surface from its own
|
||||
config — agent invoke is the thin shim that streams the result.
|
||||
config - agent invoke is the thin shim that streams the result.
|
||||
|
||||
Modes:
|
||||
TTY (default): live answer streaming + tool-trace footer
|
||||
@@ -94,7 +93,6 @@ Modes:
|
||||
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
|
||||
cmd.Flags().BoolVar(&opts.NoStream, "no-stream", false, "Buffer the full answer before printing (forces accumulate mode)")
|
||||
cmdutil.AddJSONFlags(cmd, agentInvokeFields)
|
||||
aiclient.SetAgentHelp(cmd, "Streams an agent's answer over SSE. Pass --json (or run non-TTY) to receive a single completed {answer, references, tool_events, …} JSON object instead of partial chunks. Errors: resource.not_found (unknown agent_id) / server.session_create_failed (auto-create) / local.sse_stream_aborted (mid-stream).")
|
||||
return cmd
|
||||
}
|
||||
|
||||
@@ -167,7 +165,7 @@ func runInvoke(ctx context.Context, opts *InvokeOptions, jopts *cmdutil.JSONOpti
|
||||
return cmdutil.WrapHTTP(streamErr, "agent-chat stream")
|
||||
}
|
||||
|
||||
// Server closed cleanly but never sent a Done event — treat as aborted
|
||||
// Server closed cleanly but never sent a Done event - treat as aborted
|
||||
// so agents don't silently emit a truncated answer as ok=true.
|
||||
if !acc.Done() {
|
||||
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
|
||||
@@ -204,7 +202,7 @@ func runInvoke(ctx context.Context, opts *InvokeOptions, jopts *cmdutil.JSONOpti
|
||||
}
|
||||
|
||||
// renderToolTrace prints a compact tool-event footer in human mode.
|
||||
// Skipped when the agent emitted no tool events — silent beats an empty
|
||||
// Skipped when the agent emitted no tool events - silent beats an empty
|
||||
// banner.
|
||||
func renderToolTrace(w io.Writer, events []sse.AgentToolEvent) {
|
||||
if len(events) == 0 {
|
||||
|
||||
@@ -9,7 +9,6 @@ import (
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/aiclient"
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/text"
|
||||
@@ -17,7 +16,7 @@ import (
|
||||
)
|
||||
|
||||
// agentListFields enumerates the fields surfaced for `--json` discovery
|
||||
// on `agent list`. Mirrors the json tags on sdk.Agent — nested Config is
|
||||
// on `agent list`. Mirrors the json tags on sdk.Agent - nested Config is
|
||||
// omitted because its sub-fields make filtering noisy (use `--jq` instead).
|
||||
var agentListFields = []string{
|
||||
"id", "name", "description", "avatar",
|
||||
@@ -59,7 +58,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return (0 = no cap, 1..10000 = explicit)")
|
||||
cmdutil.AddJSONFlags(cmd, agentListFields)
|
||||
aiclient.SetAgentHelp(cmd, "Lists tenant-visible agents (built-in + custom) as a bare JSON array of Agent objects (empty `[]` when none). --limit caps the returned slice. Use `--json=id,name` to project fields, `--jq` for arbitrary reshape.")
|
||||
return cmd
|
||||
}
|
||||
|
||||
@@ -80,7 +78,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
|
||||
if items == nil {
|
||||
items = []sdk.Agent{} // ensure JSON [] not null
|
||||
}
|
||||
// Default sort: updated_at desc — most recently-edited agents surface
|
||||
// Default sort: updated_at desc - most recently-edited agents surface
|
||||
// first. Mirrors kb list / doc list behavior.
|
||||
sort.Slice(items, func(i, j int) bool {
|
||||
return items[i].UpdatedAt.After(items[j].UpdatedAt)
|
||||
|
||||
@@ -7,7 +7,6 @@ import (
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/aiclient"
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
@@ -15,7 +14,7 @@ import (
|
||||
|
||||
// agentViewFields enumerates fields surfaced for `--json` discovery on
|
||||
// `agent view`. Filter applies to the bare Agent object. Config sub-fields
|
||||
// are intentionally omitted — too granular for naked projection; use
|
||||
// are intentionally omitted - too granular for naked projection; use
|
||||
// `--jq '.config'` to reach them.
|
||||
var agentViewFields = []string{
|
||||
"id", "name", "description", "avatar",
|
||||
@@ -36,7 +35,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
|
||||
Long: `Renders the agent's metadata (id / name / description / created-by /
|
||||
timestamps) plus a compact config summary (mode, model, allowed tools, KB
|
||||
scope). Pass --json for the full Agent object including the nested config
|
||||
struct — or --jq '.config' to extract just the config.`,
|
||||
struct - or --jq '.config' to extract just the config.`,
|
||||
Example: ` weknora agent view ag_abc
|
||||
weknora agent view ag_abc --json | jq '.config.allowed_tools'`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
@@ -53,7 +52,6 @@ struct — or --jq '.config' to extract just the config.`,
|
||||
},
|
||||
}
|
||||
cmdutil.AddJSONFlags(cmd, agentViewFields)
|
||||
aiclient.SetAgentHelp(cmd, "Fetches an agent by ID. Returns the full sdk.Agent (with nested config) as a bare JSON object. Errors: resource.not_found when the agent ID does not exist or is not visible to the active tenant.")
|
||||
return cmd
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user