fix(slides): local XML precheck, 99991400 backoff, quota code registration

Lands the four agreed fixes from the 2026-06-08 slides write-path
telemetry analysis:

1. Local XML well-formedness precheck (shortcuts/slides/)
   - checkXMLWellFormed: pure syntax validation via stdlib encoding/xml
     (same parser family as the backend, false-positive risk ~0);
     explicitly rejects <?xml ?> declarations; deliberately allows
     multiple top-level elements (legal in block_insert fragments)
   - wired into +create --slides (at Validate, so a bad slide no longer
     leaves a half-built deck) and +replace-slide --parts
     replacement/insertion; errors carry line numbers + escaping
     guidance, rejected locally with zero API calls

2. 99991400 rate-limit backoff (retryOnRateLimit)
   - the code was registered Retryable:true but no slides loop actually
     retried, so one frequency-window hit aborted the whole batch
   - up to 2 retries with 1s/2s backoff, announced on stderr,
     context-cancellable; wired into the +create slide POST loop and
     uploadSlidesMedia (+media-upload and the placeholder upload loop)
   - upload switched to UploadDriveMediaAllTyped (retry match requires
     typed errors; aligns with the slides typed migration)

3. Quota codes 90003086/87/88 registered (internal/errclass + output)
   - cloud-space explorer billing codes passed through as HTTP 200 with
     body code!=0; previously fell to SubtypeUnknown
   - now CategoryAPI + quota_exceeded, not retryable, with per-code
     hints (upgrade plan / free quota / ask admin to enable the module)

4. lark-slides skill tag-whitelist ban (skills/lark-slides/)
   - quick-ref: never write tags outside the whitelist, name the six
     confirmed-rejected tags (audio/video/timeline/animation/trigger/
     header), substitution table, escaping rules
   - removed <?xml ?> declarations from all examples (contradicted
     backend behavior and the new precheck)

Tested with unit + httpmock integration tests, plus live verification
against the real feishu.cn API: all precheck negatives rejected locally,
no false positives on real create/replace, and 18 concurrent uploads hit
3 real 99991400 responses which all retried and succeeded (18/18).

Author: ViperCai

internal/errclass/codemeta_drive.go

@@ -12,6 +12,19 @@ import "github.com/larksuite/cli/errs"
 var driveCodeMeta = map[int]CodeMeta{
 	1061044: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},          // parent folder does not exist (upload)
 	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // comment endpoint "Invalid or missing parameters"
+
+	// Commercial plan codes returned by the cloud-space explorer service
+	// and passed through verbatim by document backends (observed via
+	// slides_ai create — engine log "A2 create quota exceeded, code=90003087"
+	// — and drive/v1/import_tasks, both as HTTP 200 with body code≠0).
+	// Plan/billing limits: retrying can never succeed. 90003086/90003087 are
+	// plan creation-count quotas (upgrade the plan or free quota); 90003088 is
+	// not a quota at all — the tenant has not purchased/enabled the docs
+	// module, so it maps to FailedPrecondition (admin must enable the module)
+	// rather than QuotaExceeded, whose default hint suggests freeing quota.
+	90003086: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},      // premium plan creation count limit reached
+	90003087: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},      // A2 plan creation count limit reached
+	90003088: {Category: errs.CategoryAPI, Subtype: errs.SubtypeFailedPrecondition}, // unbundle: tenant has not purchased / been granted the docs module
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_drive_test.go

@@ -27,6 +27,14 @@ func TestLookupCodeMeta_DriveCodes(t *testing.T) {
 		// 1069302: comment endpoint's opaque "Invalid or missing parameters"
 		// (shortcuts/drive/drive_add_comment.go) → API-side parameter rejection.
 		{1069302, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		// 9000308x: cloud-space explorer commercial plan codes, passed
+		// through by document backends (slides_ai create, drive import_tasks)
+		// as HTTP 200 with body code≠0. Billing limits → never retryable.
+		// 86/87 are plan creation-count quotas; 88 is "docs module not
+		// purchased/enabled" — a precondition, not a quota.
+		{90003086, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
+		{90003087, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
+		{90003088, errs.CategoryAPI, errs.SubtypeFailedPrecondition, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {

internal/output/lark_errors.go

@@ -84,6 +84,14 @@ const (
 	LarkErrMailSendQuotaTenantExt = 1236009 // tenant daily external recipient count exceeded
 	LarkErrMailQuota              = 1236010 // mail quota limit
 	LarkErrTenantStorageLimit     = 1236013 // tenant storage limit exceeded
+
+	// Docs/slides commercial plan quota codes from the cloud-space explorer
+	// service, passed through verbatim by document backends as HTTP 200 with
+	// body code≠0 (observed on slides_ai create and drive/v1/import_tasks).
+	// Not retryable: these are billing-plan limits.
+	LarkErrDocsCreatePremiumQuota = 90003086 // premium plan document creation count limit reached
+	LarkErrDocsCreateA2Quota      = 90003087 // A2 plan document creation count limit reached
+	LarkErrDocsModuleUnbundled    = 90003088 // tenant has not purchased / enabled the docs module
 )
 
 // legacyHints supplies the per-code actionable hint string for the legacy
@@ -118,6 +126,10 @@ var legacyHints = map[int]string{
 		"width/height must be >= 20 px; offsets must be >= 0 and less than the anchor cell's width/height",
 	LarkErrDrivePermApplyRateLimit:     "permission-apply quota reached: each user may request access on the same document at most 5 times per day; wait or ask the owner directly",
 	LarkErrDrivePermApplyNotApplicable: "this document does not accept a permission-apply request (common causes: the document is configured to disallow access requests, the caller already holds the permission, or the target type does not support apply); contact the owner directly",
+
+	LarkErrDocsCreatePremiumQuota: "document creation quota of the current plan reached: upgrade the plan or delete documents you no longer need to free quota; retrying will not help",
+	LarkErrDocsCreateA2Quota:      "document creation quota of the current plan reached: upgrade the plan or delete documents you no longer need to free quota; retrying will not help",
+	LarkErrDocsModuleUnbundled:    "the tenant has not purchased or enabled the docs module; ask the tenant admin to enable it before creating documents",
 }
 
 // ClassifyLarkError maps a Lark API error code + message to the legacy

shortcuts/slides/helpers.go

@@ -4,15 +4,67 @@
 package slides
 
 import (
+	"context"
+	"encoding/xml"
 	"fmt"
+	"io"
 	"net/url"
 	"regexp"
 	"strings"
+	"time"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+const (
+	// slidesRateLimitMaxRetries is the number of automatic retries (beyond the
+	// initial request) when the API answers 99991400 "request trigger frequency
+	// limit". The slides batch paths (+create slide loop, placeholder image
+	// uploads) fire consecutive POSTs and are the dominant 99991400 producers
+	// in telemetry; a short backoff absorbs the per-second window without
+	// masking a genuinely saturated tenant.
+	slidesRateLimitMaxRetries = 2
+)
+
+// slidesRateLimitBaseDelay is the initial backoff delay; subsequent retries
+// double it (1s, 2s). Mirrors the wiki +node-create lock-contention pattern
+// but with a larger base because frequency limits are per-second windows, not
+// sub-second lock races. var (not const) only so tests can shrink it.
+var slidesRateLimitBaseDelay = 1 * time.Second
+
+// isRateLimitedErr reports whether err is a typed retryable rate-limit error
+// (e.g. 99991400), as classified by errclass.BuildAPIError.
+func isRateLimitedErr(err error) bool {
+	p, ok := errs.ProblemOf(err)
+	return ok && p.Subtype == errs.SubtypeRateLimit && p.Retryable
+}
+
+// retryOnRateLimit runs fn, retrying with exponential backoff (1s, 2s) when it
+// returns a retryable rate-limit error. Any other outcome — success or a
+// different error — is returned immediately. Progress is announced on errOut
+// so a user watching a batch upload understands the pause.
+func retryOnRateLimit(ctx context.Context, errOut io.Writer, fn func() error) error {
+	var lastErr error
+	for attempt := 0; attempt <= slidesRateLimitMaxRetries; attempt++ {
+		if attempt > 0 {
+			delay := slidesRateLimitBaseDelay << uint(attempt-1)
+			fmt.Fprintf(errOut, "Rate limited by the API (99991400), retrying (attempt %d/%d) in %v...\n",
+				attempt, slidesRateLimitMaxRetries, delay)
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(delay):
+			}
+		}
+		lastErr = fn()
+		if lastErr == nil || !isRateLimitedErr(lastErr) {
+			return lastErr
+		}
+	}
+	return lastErr
+}
+
 // presentationRef holds a parsed --presentation input.
 //
 // Slides shortcuts accept three input shapes:
@@ -280,6 +332,47 @@ func ensureShapeHasContent(xmlFragment string) string {
 	return xmlFragment[:m[1]] + "<content/>" + afterOpen
 }
 
+// checkXMLWellFormed verifies that fragment parses as well-formed XML, using
+// the same parser family as the backend (Go encoding/xml). Syntax only —
+// element names and attributes are NOT checked against the SML schema, so
+// anything passing here can still be rejected server-side for semantic
+// reasons; conversely nothing rejected here could ever have succeeded, which
+// keeps the false-positive risk at zero.
+//
+// The backend reports these failures as an opaque 3350001/4001000
+// "invalid param" with no position info; catching them locally turns the
+// dominant real-world causes (bare & in text, unclosed tags, attribute
+// quoting) into actionable messages with a line number.
+//
+// An <?xml ?> declaration is rejected explicitly: the rendering backend does
+// not accept processing instructions on slide fragments (rejects with
+// "?xml not provide the implement"). encoding/xml surfaces it as a regular
+// ProcInst token, so it needs its own check.
+//
+// Multiple top-level elements are deliberately allowed — insertion fragments
+// may legitimately carry sibling elements.
+func checkXMLWellFormed(fragment string) error {
+	dec := xml.NewDecoder(strings.NewReader(fragment))
+	for {
+		tok, err := dec.Token()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			if syn, ok := err.(*xml.SyntaxError); ok {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"XML not well-formed at line %d: %s (escape literal & as &amp; and < as &lt; in text)",
+					syn.Line, syn.Msg)
+			}
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "XML not well-formed: %v", err)
+		}
+		if pi, ok := tok.(xml.ProcInst); ok && strings.EqualFold(pi.Target, "xml") {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"XML must not contain an <?xml ?> declaration (the slides backend rejects it); remove it and start at the root element")
+		}
+	}
+}
+
 // replaceImagePlaceholders rewrites <img src="@path"> occurrences in the input
 // XML by looking up each path in tokens. Paths missing from the map are left
 // untouched (callers should ensure the map is complete).

shortcuts/slides/helpers_test.go

@@ -4,9 +4,15 @@
 package slides
 
 import (
+	"bytes"
+	"context"
+	"errors"
 	"reflect"
 	"strings"
 	"testing"
+	"time"
+
+	"github.com/larksuite/cli/errs"
 )
 
 func TestParsePresentationRef(t *testing.T) {
@@ -413,3 +419,145 @@ func TestEnsureXMLRootID(t *testing.T) {
 		})
 	}
 }
+
+func TestCheckXMLWellFormed(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		in      string
+		wantErr string
+	}{
+		{name: "simple element", in: `<shape type="rect"><content/></shape>`},
+		{name: "nested with attributes", in: `<slide><shape type="text"><content><p>hi</p></content></shape></slide>`},
+		// Insertion fragments may carry sibling top-level elements; the decoder
+		// must not enforce a single document element.
+		{name: "multiple top-level elements", in: `<p>a</p><p>b</p>`},
+		{name: "escaped entities", in: `<p>A &amp; B &lt;tag&gt; &quot;q&quot;</p>`},
+		{name: "CDATA with raw ampersand", in: `<p><![CDATA[a & b < c]]></p>`},
+		{name: "comment", in: `<!-- note --><shape/>`},
+		{name: "img placeholder attr", in: `<img src="@./local.png" width="100"/>`},
+		{name: "unicode text", in: `<p>项目汇报 🎯</p>`},
+
+		// Top CLI-path failure cause in engine logs: bare & in text.
+		{name: "bare ampersand", in: `<p>Q & A</p>`, wantErr: "line 1"},
+		{name: "bare ampersand multiline", in: "<slide>\n<p>R&D</p>\n</slide>", wantErr: "line 2"},
+		{name: "unclosed tag", in: `<shape><content></shape>`, wantErr: "not well-formed"},
+		{name: "unquoted attribute", in: `<shape type=rect/>`, wantErr: "not well-formed"},
+		{name: "stray closing tag", in: `<p>hi</p></div>`, wantErr: "not well-formed"},
+		{name: "undefined entity", in: `<p>a&nbsp;b</p>`, wantErr: "not well-formed"},
+
+		// nodeserver rejects processing instructions ("?xml not provide the
+		// implement"); reject the declaration locally regardless of position.
+		{name: "xml declaration", in: `<?xml version="1.0"?><shape/>`, wantErr: "declaration"},
+		{name: "xml declaration with encoding", in: `<?xml version="1.0" encoding="UTF-8"?><slide/>`, wantErr: "declaration"},
+		{name: "uppercase xml declaration", in: `<?XML version="1.0"?><shape/>`, wantErr: "declaration"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			err := checkXMLWellFormed(tt.in)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("unexpected err: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("want error containing %q, got nil", tt.wantErr)
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("want error containing %q, got %q", tt.wantErr, err.Error())
+			}
+		})
+	}
+}
+
+// TestRetryOnRateLimit verifies the 99991400 backoff helper: retryable
+// rate-limit errors are retried with backoff, anything else returns
+// immediately, and exhaustion surfaces the last rate-limit error.
+//
+// Not parallel: shrinks the package-level slidesRateLimitBaseDelay.
+func TestRetryOnRateLimit(t *testing.T) {
+	restore := slidesRateLimitBaseDelay
+	slidesRateLimitBaseDelay = time.Millisecond
+	t.Cleanup(func() { slidesRateLimitBaseDelay = restore })
+
+	rateLimitErr := func() error {
+		return errs.NewAPIError(errs.SubtypeRateLimit, "request trigger frequency limit").WithRetryable()
+	}
+
+	t.Run("success without retry", func(t *testing.T) {
+		var errOut bytes.Buffer
+		calls := 0
+		err := retryOnRateLimit(context.Background(), &errOut, func() error {
+			calls++
+			return nil
+		})
+		if err != nil || calls != 1 {
+			t.Fatalf("err=%v calls=%d, want nil/1", err, calls)
+		}
+		if errOut.Len() != 0 {
+			t.Fatalf("no retry message expected, got: %s", errOut.String())
+		}
+	})
+
+	t.Run("succeeds after transient rate limit", func(t *testing.T) {
+		var errOut bytes.Buffer
+		calls := 0
+		err := retryOnRateLimit(context.Background(), &errOut, func() error {
+			calls++
+			if calls <= 2 {
+				return rateLimitErr()
+			}
+			return nil
+		})
+		if err != nil || calls != 3 {
+			t.Fatalf("err=%v calls=%d, want nil/3", err, calls)
+		}
+		if !strings.Contains(errOut.String(), "retrying") {
+			t.Fatalf("expected retry announcement, got: %s", errOut.String())
+		}
+	})
+
+	t.Run("exhaustion returns last rate-limit error", func(t *testing.T) {
+		var errOut bytes.Buffer
+		calls := 0
+		err := retryOnRateLimit(context.Background(), &errOut, func() error {
+			calls++
+			return rateLimitErr()
+		})
+		if err == nil || !isRateLimitedErr(err) {
+			t.Fatalf("want rate-limit error after exhaustion, got: %v", err)
+		}
+		if calls != slidesRateLimitMaxRetries+1 {
+			t.Fatalf("calls=%d, want %d", calls, slidesRateLimitMaxRetries+1)
+		}
+	})
+
+	t.Run("non-rate-limit error returns immediately", func(t *testing.T) {
+		var errOut bytes.Buffer
+		calls := 0
+		boom := errs.NewAPIError(errs.SubtypeNotFound, "not found")
+		err := retryOnRateLimit(context.Background(), &errOut, func() error {
+			calls++
+			return boom
+		})
+		if !errors.Is(err, boom) || calls != 1 {
+			t.Fatalf("err=%v calls=%d, want boom/1", err, calls)
+		}
+	})
+
+	t.Run("cancelled context aborts the backoff wait", func(t *testing.T) {
+		var errOut bytes.Buffer
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		err := retryOnRateLimit(ctx, &errOut, func() error {
+			return rateLimitErr()
+		})
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("want context.Canceled, got: %v", err)
+		}
+	})
+}

shortcuts/slides/slides_create.go

@@ -50,6 +50,15 @@ var SlidesCreate = common.Shortcut{
 			if len(slides) > maxSlidesPerCreate {
 				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides array exceeds maximum of %d slides; create the presentation first, then add slides via xml_presentation.slide.create", maxSlidesPerCreate).WithParam("--slides")
 			}
+			// Well-formedness precheck before any API call: a syntax error in
+			// slide N would otherwise create the presentation and then fail on
+			// the slide POST with an opaque backend "invalid param", leaving a
+			// partially-built deck behind.
+			for i, slideXML := range slides {
+				if err := checkXMLWellFormed(slideXML); err != nil {
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slides[%d]: %v", i, err).WithParam("--slides").WithCause(err)
+				}
+			}
 			// Validate placeholder paths up front so we don't create a presentation
 			// only to fail mid-way on a missing local file.
 			for _, path := range extractImagePlaceholderPaths(slides) {
@@ -183,14 +192,22 @@ var SlidesCreate = common.Shortcut{
 
 				var slideIDs []string
 				for i, slideXML := range slides {
-					slideData, err := runtime.CallAPITyped(
-						"POST",
-						slideURL,
-						map[string]interface{}{"revision_id": -1},
-						map[string]interface{}{
-							"slide": map[string]interface{}{"content": slideXML},
-						},
-					)
+					var slideData map[string]interface{}
+					// Consecutive slide POSTs are the main 99991400 producer in
+					// telemetry; absorb the per-second frequency window with a
+					// short backoff instead of aborting the whole batch.
+					err := retryOnRateLimit(ctx, runtime.IO().ErrOut, func() error {
+						var callErr error
+						slideData, callErr = runtime.CallAPITyped(
+							"POST",
+							slideURL,
+							map[string]interface{}{"revision_id": -1},
+							map[string]interface{}{
+								"slide": map[string]interface{}{"content": slideXML},
+							},
+						)
+						return callErr
+					})
 					if err != nil {
 						return appendSlidesProgressHint(err, fmt.Sprintf("adding slide %d/%d failed; presentation %s was created, %d slide(s) added before failure", i+1, len(slides), presentationID, i))
 					}