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
+5 -5
View File
@@ -1,11 +1,11 @@
// Package agent handles AI agent integration: env-based detection (used to
// trigger AGENT-targeted help text) and per-command help annotations.
//
// v0.2: removed the omnibus `--agent` flag + ApplyAgentSugar mode-switch
// (audited as over-design — see docs/superpowers/specs/2026-05-09 ADR-3).
// Mainstream CLIs (gh / kubectl / aws / docker / flyctl) deliberately don't
// have a single mode-switch flag; per-command --json + TTY auto-detect cover
// 95% of cases. WeKnora now follows that convention.
// v0.2 ADR-3: removed the omnibus `--agent` flag + ApplyAgentSugar
// mode-switch as over-design. Mainstream CLIs (gh / kubectl / aws / docker /
// flyctl) deliberately don't have a single mode-switch flag; per-command
// --json + TTY auto-detect cover 95% of cases. WeKnora now follows that
// convention. See cli/AGENTS.md for the full agent contract.
//
// What remains here: a small env-detect for known coding agents, used purely
// to render the AGENT-targeted help section (no behavior change). Patterned
+31 -16
View File
@@ -1,35 +1,50 @@
package cmdutil
import (
"errors"
"fmt"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/prompt"
)
// ConfirmDestructive prompts the user to confirm a destructive operation
// (e.g. delete) when the call is interactive, and proceeds without
// prompting otherwise. Behavior matrix:
// ConfirmDestructive guards a destructive operation (delete, force-overwrite)
// behind explicit user approval. Behavior matrix:
//
// yes=true → proceed (skip prompt; explicit user opt-in via -y)
// non-TTY stdout → proceed (no UI to ask; safer to follow the call
// than to break scripts/CI that don't pass
// -y every time)
// jsonOut=true → proceed (envelope mode is by definition scripted,
// a prompt would deadlock the consumer)
// yes=true → proceed (explicit user opt-in via -y/--yes)
// non-TTY OR jsonOut → return CodeInputConfirmationRequired (exit 10);
// no UI to prompt, agent/CI must re-invoke with -y
// after the human explicitly approves
// TTY + interactive → prompt; user-yes proceeds, user-no returns
// CodeUserAborted ("Aborted." to stderr)
// prompter error → returns CodeInputMissingFlag (rare; AgentPrompter
// path or stdin closed mid-prompt)
// prompter error → returns CodeInputMissingFlag (rare; stdin closed
// mid-prompt)
//
// `yes` should be sourced from the persistent global -y/--yes flag (see
// addGlobalFlags in cli/cmd/root.go). Mirrors gh's `--yes` semantics on
// destructive commands: gh repo delete --yes
// (https://cli.github.com/manual/gh_repo_delete).
// The non-TTY branch is the lark-cli skill protocol: high-risk writes
// always require explicit confirmation in scripted contexts, never silent
// proceed. See cli/AGENTS.md "Exit codes" and
// https://github.com/larksuite/cli/blob/main/skills/lark-shared/SKILL.md.
//
// `yes` should be sourced from the persistent global -y/--yes flag.
//
// On exit-10 path, the returned *Error carries OperationRisk so the envelope
// printer attaches `risk: {level: "high-risk-write", action: ...}`.
func ConfirmDestructive(p prompt.Prompter, yes, jsonOut bool, what, id string) error {
if yes || !iostreams.IO.IsStdoutTTY() || jsonOut {
if yes {
return nil
}
risk := &OperationRisk{Level: "high-risk-write", Action: fmt.Sprintf("delete %s %s", what, id)}
if !iostreams.IO.IsStdoutTTY() || jsonOut {
e := NewError(
CodeInputConfirmationRequired,
fmt.Sprintf("delete %s %s requires explicit confirmation: re-run with -y/--yes", what, id),
)
var typed *Error
if errors.As(e, &typed) {
typed.OperationRisk = risk
}
return e
}
ok, err := p.Confirm(fmt.Sprintf("Delete %s %s? This cannot be undone.", what, id), false)
if err != nil {
return Wrapf(CodeInputMissingFlag, err, "confirm delete")
+45
View File
@@ -0,0 +1,45 @@
package cmdutil
import (
"fmt"
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
)
// IsDryRun reports whether the global --dry-run flag was set on cmd or any
// of its parents. Write commands check this and skip the SDK call, returning
// an envelope with dry_run=true that describes the action that would have
// run. Read commands ignore --dry-run (no side effect to preview).
//
// Pattern from lark-cli's `--dry-run` (cmd/api/api.go DryRun field).
func IsDryRun(cmd *cobra.Command) bool {
if cmd == nil {
return false
}
v, _ := cmd.Flags().GetBool("dry-run")
return v
}
// EmitDryRun writes the canonical preview envelope for a write command. JSON
// mode emits SuccessWithRisk + DryRun=true; human mode prints the
// `[dry-run] would <risk.Action>` line to stdout, with " (high-risk)"
// appended automatically when risk.Level == RiskHighRiskWrite. Centralized
// so wire shape stays identical across kb create/delete, doc upload/delete,
// api, and any future write command.
func EmitDryRun(jsonOut bool, data any, meta *format.Meta, risk *format.Risk) error {
out := iostreams.IO.Out
if jsonOut {
env := format.SuccessWithRisk(data, meta, risk)
env.DryRun = true
return format.WriteEnvelope(out, env)
}
line := risk.Action
if risk.Level == format.RiskHighRiskWrite {
line += " (high-risk)"
}
_, err := fmt.Fprintf(out, "[dry-run] would %s\n", line)
return err
}
+22 -3
View File
@@ -29,8 +29,14 @@ const (
CodeResourceLocked ErrorCode = "resource.locked"
// input.* — flag and argument validation
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
CodeInputMissingFlag ErrorCode = "input.missing_flag"
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
CodeInputMissingFlag ErrorCode = "input.missing_flag"
// CodeInputConfirmationRequired marks a high-risk write that has no
// interactive UI (non-TTY or --json) and was invoked without -y/--yes.
// Mapped to exit code 10 (lark-cli skill protocol — see cli/AGENTS.md).
// Agents must surface the envelope to the user and only retry with -y
// after explicit human approval; never auto-retry.
CodeInputConfirmationRequired ErrorCode = "input.confirmation_required"
// server.* / network.*
CodeServerError ErrorCode = "server.error"
@@ -84,6 +90,19 @@ type Error struct {
Cause error
Retryable bool
HTTPStatus int
// Risk classifies the operation that produced this error. Set by callers
// invoking destructive write paths so envelope.risk surfaces to agents.
// Stored as the format.Risk JSON shape via OperationRisk to avoid an
// import cycle with internal/format.
OperationRisk *OperationRisk
}
// OperationRisk mirrors format.Risk in the cmdutil layer (avoiding a circular
// import). cmdutil → format is OK; the inverse is not, so cmdutil owns its
// own type and ToErrorBody / PrintErrorEnvelope translate.
type OperationRisk struct {
Level string // "read" | "write" | "high-risk-write"
Action string
}
func (e *Error) Error() string {
@@ -229,7 +248,7 @@ func AllCodes() []ErrorCode {
// resource
CodeResourceNotFound, CodeResourceAlreadyExists, CodeResourceLocked,
// input
CodeInputInvalidArgument, CodeInputMissingFlag,
CodeInputInvalidArgument, CodeInputMissingFlag, CodeInputConfirmationRequired,
// server / network
CodeServerError, CodeServerTimeout, CodeServerRateLimited,
CodeServerIncompatibleVersion, CodeNetworkError,
+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:
+1 -1
View File
@@ -17,7 +17,7 @@ import (
)
// Factory is the dependency container injected at command construction. Each
// closure is lazy: --help / completion / `weknora schema` must NOT trigger
// closure is lazy: --help / completion / `weknora version` must NOT trigger
// HTTP, keyring access, or filesystem I/O beyond the bare minimum.
//
// Four closures (ADR-4):
+68 -13
View File
@@ -10,11 +10,57 @@ import (
)
// Envelope is the canonical success/failure shape returned by every command.
//
// v0.2 ADR-3 added Notice / Risk / DryRun, borrowed from lark-cli's envelope
// (https://github.com/larksuite/cli/blob/main/internal/output/envelope.go).
// All three are absent on read-only commands; write commands populate Risk
// even on success so agents can record what action ran.
type Envelope struct {
OK bool `json:"ok"`
Data any `json:"data,omitempty"`
Error *ErrorBody `json:"error,omitempty"`
Meta *Meta `json:"_meta,omitempty"`
OK bool `json:"ok"`
Data any `json:"data,omitempty"`
Error *ErrorBody `json:"error,omitempty"`
Meta *Meta `json:"_meta,omitempty"`
Notice *Notice `json:"_notice,omitempty"`
Risk *Risk `json:"risk,omitempty"`
// DryRun is intentionally NOT omitempty: AGENTS.md documents
// `dry_run: false` as the literal default in the schema example, so
// agents that pin the field's presence aren't surprised by it
// disappearing on non-dry-run envelopes.
DryRun bool `json:"dry_run"`
}
// Notice carries system-level advisories independent of the command outcome:
// CLI update available, server-CLI version skew, etc. Agents read these to
// surface upgrade prompts to users without polluting `data`.
type Notice struct {
Update *UpdateNotice `json:"update,omitempty"`
VersionSkew *VersionSkewNotice `json:"version_skew,omitempty"`
}
// UpdateNotice indicates a newer CLI version is available.
type UpdateNotice struct {
Available bool `json:"available"`
Current string `json:"current"`
Latest string `json:"latest,omitempty"`
}
// VersionSkewNotice indicates the server is behind the CLI within the compat
// window. `Level` mirrors doctor's status semantics: "warn" (degraded but
// functional) or "error" (out of compat).
type VersionSkewNotice struct {
Client string `json:"client"`
Server string `json:"server"`
Level string `json:"level"`
}
// Risk classifies the operation the user is performing — not the error.
// Agents inspect this on every envelope. When Level == RiskHighRiskWrite and
// the operation requires confirmation (no -y), the CLI exits 10. See
// cli/AGENTS.md "Exit codes" and lark-cli's
// skills/lark-shared/SKILL.md.
type Risk struct {
Level RiskLevel `json:"level"`
Action string `json:"action,omitempty"`
}
// Meta carries non-payload context fields useful to agents and observability.
@@ -29,26 +75,27 @@ type Meta struct {
AppliedFilters []string `json:"applied_filters,omitempty"`
}
// RiskLevel classifies an error by the kind of operation that produced it.
// Agents use this to decide whether to retry, escalate, or stop.
// RiskLevel classifies an operation. Agents use this to decide whether to
// retry, require explicit user approval, or stop. Values are aligned with
// lark-cli's risk taxonomy
// (https://github.com/larksuite/cli/blob/main/internal/output/envelope.go).
type RiskLevel string
const (
RiskRead RiskLevel = "read"
RiskMutating RiskLevel = "mutating"
RiskDestructive RiskLevel = "destructive"
RiskRead RiskLevel = "read"
RiskWrite RiskLevel = "write"
RiskHighRiskWrite RiskLevel = "high-risk-write"
)
// ErrorBody is the failure shape. `code` is a stable namespaced ID (e.g.
// "auth.unauthenticated"); `hint` is an actionable next step; `risk` flags
// destructive intent for agent self-governance.
// "auth.unauthenticated"); `hint` is an actionable next step. Operation-level
// risk lives at the envelope level (Envelope.Risk), not here.
type ErrorBody struct {
Code string `json:"code"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
RequestID string `json:"request_id,omitempty"`
Context string `json:"context,omitempty"`
Risk RiskLevel `json:"risk,omitempty"`
Retryable bool `json:"retryable,omitempty"`
ConsoleURL string `json:"console_url,omitempty"`
Details map[string]any `json:"details,omitempty"`
@@ -56,7 +103,7 @@ type ErrorBody struct {
// WriteEnvelope serializes env as one-line JSON to w. Used for non-TTY output
// and for `--json` per-command mode (the omnibus `--agent` mode-switch was
// removed in v0.2 ADR-3; see docs/superpowers/specs/2026-05-09).
// removed in v0.2 ADR-3; see cli/AGENTS.md for the agent contract).
func WriteEnvelope(w io.Writer, env Envelope) error {
enc := json.NewEncoder(w)
enc.SetEscapeHTML(false)
@@ -68,6 +115,14 @@ func Success(data any, meta *Meta) Envelope {
return Envelope{OK: true, Data: data, Meta: meta}
}
// SuccessWithRisk is Success + a per-operation Risk classification. Used by
// every write command (kb create/delete, doc upload/delete, api POST/PUT/
// DELETE, ...) so an agent reading any envelope can tell what kind of
// operation produced it without parsing the data shape.
func SuccessWithRisk(data any, meta *Meta, risk *Risk) Envelope {
return Envelope{OK: true, Data: data, Meta: meta, Risk: risk}
}
// Failure constructs a failure envelope.
func Failure(err *ErrorBody) Envelope {
return Envelope{OK: false, Error: err}
+17 -2
View File
@@ -26,7 +26,6 @@ func TestFailureEnvelope(t *testing.T) {
Code: "auth.unauthenticated",
Message: "no creds",
Hint: "run weknora auth login",
Risk: RiskRead,
Retryable: false,
})
var buf bytes.Buffer
@@ -37,7 +36,23 @@ func TestFailureEnvelope(t *testing.T) {
errBody := got["error"].(map[string]any)
assert.Equal(t, "auth.unauthenticated", errBody["code"])
assert.Equal(t, "run weknora auth login", errBody["hint"])
assert.Equal(t, "read", errBody["risk"])
}
func TestEnvelope_RiskAndNotice(t *testing.T) {
env := Success(map[string]string{"id": "kb_x"}, nil)
env.Risk = &Risk{Level: RiskHighRiskWrite, Action: "delete kb_x"}
env.Notice = &Notice{Update: &UpdateNotice{Available: true, Current: "0.2.0", Latest: "0.3.0"}}
var buf bytes.Buffer
require.NoError(t, WriteEnvelope(&buf, env))
var got map[string]any
require.NoError(t, json.Unmarshal(buf.Bytes(), &got))
risk := got["risk"].(map[string]any)
assert.Equal(t, "high-risk-write", risk["level"])
assert.Equal(t, "delete kb_x", risk["action"])
notice := got["_notice"].(map[string]any)
upd := notice["update"].(map[string]any)
assert.Equal(t, true, upd["available"])
assert.Equal(t, "0.3.0", upd["latest"])
}
func TestEnvelope_NoEscapeHTML(t *testing.T) {