feat(cli): add agent-first affordance — envelope, exit-10, --dry-run

Borrows the lark-cli agent-affordance model
(https://github.com/larksuite/cli/blob/main/AGENTS.md +
skills/lark-shared/SKILL.md) so weknora is designed to be agent-friendly:
error messages, output format, and flag design follow conventions agents
can rely on.

cli/AGENTS.md (operational reference for LLM agents invoking weknora):
  Public document covering envelope schema, exit-code protocol
  (0/1/2/10/130), stdout/stderr separation, and behavioral rules.
  Sensitive commands (\`context use\`, \`kb delete\`, \`doc delete\`, \`init\`)
  gain "AI agents:" paragraphs in their cobra Long descriptions so
  guidance shows in --help.

format.Envelope schema additions:
  Risk    per-operation classification (read / write / high-risk-write +
          action description), populated by write commands on both success
          and failure paths.
  Notice  system advisories (CLI update available, server-CLI version
          skew); type defined, emit sites land in v0.3.
  DryRun  marker for envelopes returned from --dry-run preview paths.

  RiskLevel constants realigned to lark's taxonomy: read / write /
  high-risk-write (was: read / mutating / destructive — not yet wired by
  any command).

  cmdutil.Error gains OperationRisk; PrintErrorEnvelope auto-attaches it
  to envelope.Risk so destructive failure paths surface uniformly.

Exit-10 confirmation protocol:
  New ErrorCode \`input.confirmation_required\` mapped to exit code 10 in
  cmdutil.ExitCode. ConfirmDestructive now returns this code (with
  OperationRisk attached) when stdout is non-TTY or --json was set, with
  -y/--yes absent. Previous behavior — silent proceed in non-TTY — was
  unsafe: scripts and agents could delete resources with no explicit
  approval. Three test cases re-pinned around the new contract.

  This is a wire-contract change for any caller who relied on silent
  proceed; v0.0/v0.1 had no destructive commands, so the blast radius is
  contained to v0.2 itself.

--dry-run global flag:
  cmd write paths (kb create/delete, doc upload/delete, api POST/PUT/PATCH/
  DELETE) check cmdutil.IsDryRun(cmd) and skip the SDK call, emitting an
  envelope with dry_run=true plus a Risk classification. Read commands
  ignore --dry-run by design (no side effect to preview). Human-mode
  prints \`[dry-run] would <action>\` to stdout.

Command discovery: agents introspect via the existing \`--help\` surface
(consistent with gh / kubectl / aws / gcloud / terraform — none of them
ship a CLI-tree self-description command). An earlier draft added a
\`weknora schema\` reflection command; dropped after a mainstream survey
found it has no stable analog (lark-cli's schema describes Lark API
methods, not its own CLI tree).

Tests: 27 cli packages pass at this commit. Added two new tests covering
envelope.risk and envelope._notice serialization.
This commit is contained in:
nullkey
2026-05-11 02:44:34 +08:00
committed by lyingbug
parent 9d2e740753
commit da9faa9e07
38 changed files with 634 additions and 104 deletions
+37 -13
View File
@@ -8,16 +8,19 @@ import (
"github.com/Tencent/WeKnora/cli/internal/format"
)
// ExitCode maps an error to the documented CLI exit code (spec §2.4).
// Mirrors gh / Stripe convention:
// - 0 success
// - 1 generic / unknown
// - 2 flag / argument problem
// - 3 auth.*
// - 4 resource.not_found
// - 5 input.*
// - 6 server.rate_limited
// - 7 server.* (other) / network.*
// ExitCode maps an error to the documented CLI exit code (spec §2.4 + ADR-3).
// Mirrors gh / Stripe / lark-cli convention:
// - 0 success
// - 1 generic / unknown typed error
// - 2 flag / argument problem
// - 3 auth.*
// - 4 resource.not_found
// - 5 input.* (other than confirmation_required)
// - 6 server.rate_limited
// - 7 server.* (other) / network.*
// - 10 input.confirmation_required — high-risk write needs explicit -y
// (lark-cli skill protocol; see cli/AGENTS.md)
// - 130 SIGINT (handled by Go runtime, not this function)
func ExitCode(err error) int {
if err == nil {
return 0
@@ -29,6 +32,9 @@ func ExitCode(err error) int {
if errors.Is(err, SilentError) {
return 1
}
if matchCode(err, CodeInputConfirmationRequired) {
return 10
}
if IsAuthError(err) {
return 3
}
@@ -72,12 +78,28 @@ func PrintError(w io.Writer, err error) {
}
// PrintErrorEnvelope writes err as a JSON envelope on w. Used in agent mode /
// --json / --format=json output so failures stay machine-parseable.
// --json / --format=json output so failures stay machine-parseable. When the
// error carries an OperationRisk (destructive write paths), it's surfaced as
// the envelope-level Risk field so agents can decide whether to surface the
// failure differently to the user.
func PrintErrorEnvelope(w io.Writer, err error) {
if err == nil || errors.Is(err, SilentError) {
return
}
_ = format.WriteEnvelope(w, format.Failure(ToErrorBody(err)))
env := format.Failure(ToErrorBody(err))
if r := operationRiskOf(err); r != nil {
env.Risk = &format.Risk{Level: format.RiskLevel(r.Level), Action: r.Action}
}
_ = format.WriteEnvelope(w, env)
}
// operationRiskOf extracts an OperationRisk from a typed *Error chain, or nil.
func operationRiskOf(err error) *OperationRisk {
var typed *Error
if errors.As(err, &typed) {
return typed.OperationRisk
}
return nil
}
// ToErrorBody projects err into the canonical envelope ErrorBody. Exposed so
@@ -145,6 +167,8 @@ func defaultHint(code ErrorCode) string {
return "verify the resource ID; list available with `weknora kb list`"
case CodeInputInvalidArgument, CodeInputMissingFlag:
return "see `weknora <command> --help` for valid usage"
case CodeInputConfirmationRequired:
return "high-risk write — re-run with -y/--yes after the user explicitly approves"
case CodeLocalKeychainDenied:
return "verify keyring access; falls back to file storage"
case CodeLocalConfigCorrupt:
@@ -160,7 +184,7 @@ func defaultHint(code ErrorCode) string {
case CodeProjectLinkCorrupt:
return "remove .weknora/project.yaml and run `weknora init` again"
case CodeUserAborted:
return "no action taken; pass --force to skip the confirmation prompt"
return "no action taken; pass -y/--yes to skip the confirmation prompt"
case CodeUploadFileNotFound:
return "verify the path is correct and readable"
case CodeSSEStreamAborted: