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:
nullkey
2026-05-15 02:16:45 +08:00
committed by lyingbug
parent a0dd989c81
commit f2e8e3f56c
111 changed files with 575 additions and 908 deletions
+7 -17
View File
@@ -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() },
}
+5 -7
View File
@@ -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 {
+2 -4
View File
@@ -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)
+2 -4
View File
@@ -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
}