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
+6 -8
View File
@@ -1,4 +1,4 @@
// Package chat implements `weknora chat <text>` — the streaming RAG answer
// Package chat implements `weknora chat <text>` - the streaming RAG answer
// entry point.
//
// Two output modes share a single SDK call:
@@ -27,7 +27,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"
@@ -116,7 +115,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, chatFields)
aiclient.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} object is emitted once at completion (no partial chunks). Pass --session to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.")
return cmd
}
@@ -161,7 +159,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !jsonOut
// Surface the auto-created session ID up-front so a user who hits ^C
// mid-stream still has the pointer to resume — no need to scroll back
// mid-stream still has the pointer to resume - no need to scroll back
// past tokens. Skipped in JSON mode (it ends up in the data object) and
// when the caller already supplied --session.
if autoCreated && !jsonOut {
@@ -193,7 +191,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
// Re-surface the auto-created session id on failure so a user who
// missed the start-of-stream notice (it scrolls past mid-stream
// tokens, especially on ^C) can still recover with --session.
// Skipped in JSON mode — the data object carries it in .session_id.
// Skipped in JSON mode - the data object carries it in .session_id.
if autoCreated && !jsonOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session %s)\n", sessionID, sessionID)
}
@@ -212,11 +210,11 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
return cmdutil.WrapHTTP(streamErr, "knowledge qa stream")
}
// SDK returned nil but we never saw a Done event — server closed the
// SDK returned nil but we never saw a Done event - server closed the
// connection cleanly mid-stream. Treat as aborted so the user sees the
// truncation rather than a silent partial answer. Includes the empty-body
// case (Done frame never arrived AND no content): better to surface the
// abort than emit ok=true with answer="" — agents can't distinguish the
// abort than emit ok=true with answer="" - agents can't distinguish the
// model genuinely had nothing to say from the stream getting cut.
if !acc.Done() {
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
@@ -227,7 +225,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
if jsonOut {
// Prefer the SDK-echoed session id (acc.SessionID) but fall back to
// our local sessionID — agents must always see a usable pointer.
// our local sessionID - agents must always see a usable pointer.
sid := acc.SessionID
if sid == "" {
sid = sessionID