fix: update ppe request headers

Change-Id: I7ea680f3f553646b41b0591b701eb14057f6c11d

.gitignore

@@ -36,7 +36,6 @@ tests/mail/reports/
 .hammer/
 .lark-slides/
 internal/registry/meta_data.json
-internal/registry/metastatic/meta_data_gen.go
 cmd/api/download.bin
 app.log
 /sidecar-server-demo

.goreleaser.yml

@@ -2,8 +2,6 @@ version: 2
 
 before:
   hooks:
-    # fetch_meta.py also regenerates the static Go registry (meta_data_gen.go),
-    # the sole source of the embedded command tree.
     - python3 scripts/fetch_meta.py
 
 builds:

Makefile

@@ -12,9 +12,6 @@ PREFIX   ?= /usr/local
 
 all: test
 
-# fetch_meta fetches meta_data.json AND regenerates the static Go registry
-# (internal/registry/metastatic/meta_data_gen.go) — the sole build-time source
-# of the embedded command tree. Both are gitignored; build/vet/test depend on it.
 fetch_meta:
 	python3 scripts/fetch_meta.py
 

cmd/auth/login.go

@@ -72,12 +72,10 @@ to generate QR codes (supports ASCII and PNG formats).`,
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
-	// Brand only — never decrypt the app secret just to build help text
-	// (avoids a keychain read on every `auth login --help` / completion).
 	var helpBrand core.LarkBrand
-	if f != nil && f.ConfigBrand != nil {
-		if b, ok := f.ConfigBrand(); ok {
-			helpBrand = b
+	if f != nil && f.Config != nil {
+		if cfg, err := f.Config(); err == nil && cfg != nil {
+			helpBrand = cfg.Brand
 		}
 	}
 	available := sortedKnownDomains(helpBrand)

cmd/command_tree_dump_test.go

@@ -1,87 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Tree-dump tool: dumps the full command tree (paths, flags, descriptions,
-// annotations) in a canonical, line-stable form so two builds can be diffed
-// byte-for-byte (e.g. before/after a registry change). Set LARK_TREE_DUMP=<path>
-// to write the dump; otherwise the test is a no-op. Not a committed golden — the
-// meta data is fetched/gitignored and drifts.
-package cmd_test
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"sort"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/cmd"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-)
-
-func esc(s string) string {
-	s = strings.ReplaceAll(s, "\\", "\\\\")
-	s = strings.ReplaceAll(s, "\n", "\\n")
-	s = strings.ReplaceAll(s, "\t", "\\t")
-	s = strings.ReplaceAll(s, "\r", "\\r")
-	return s
-}
-
-func dumpCommandTree(root *cobra.Command) string {
-	var lines []string
-	var walk func(c *cobra.Command)
-	walk = func(c *cobra.Command) {
-		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
-		head := fmt.Sprintf("CMD %q use=%q short=%q long=%q runnable=%t hidden=%t",
-			path, esc(c.Use), esc(c.Short), esc(c.Long), c.Runnable(), c.Hidden)
-		lines = append(lines, head)
-
-		if len(c.Annotations) > 0 {
-			keys := make([]string, 0, len(c.Annotations))
-			for k := range c.Annotations {
-				keys = append(keys, k)
-			}
-			sort.Strings(keys)
-			for _, k := range keys {
-				lines = append(lines, fmt.Sprintf("  ann %s=%q", k, esc(c.Annotations[k])))
-			}
-		}
-
-		var flags []string
-		c.Flags().VisitAll(func(f *pflag.Flag) {
-			flags = append(flags, fmt.Sprintf("  flag --%s -%s type=%s def=%q usage=%q",
-				f.Name, f.Shorthand, f.Value.Type(), esc(f.DefValue), esc(f.Usage)))
-		})
-		sort.Strings(flags)
-		lines = append(lines, flags...)
-
-		subs := c.Commands()
-		sort.Slice(subs, func(i, j int) bool { return subs[i].Name() < subs[j].Name() })
-		for _, sub := range subs {
-			walk(sub)
-		}
-	}
-	walk(root)
-	return strings.Join(lines, "\n") + "\n"
-}
-
-func TestDumpCommandTree(t *testing.T) {
-	out := os.Getenv("LARK_TREE_DUMP")
-	if out == "" {
-		t.Skip("set LARK_TREE_DUMP=<path> to dump the command tree")
-	}
-	// Deterministic: embedded meta only (no remote cache), empty config dir so
-	// strict-mode/plugins/policy cannot reshape the tree.
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
-	dump := dumpCommandTree(root)
-	if err := os.WriteFile(out, []byte(dump), 0644); err != nil {
-		t.Fatal(err)
-	}
-	t.Logf("wrote %d bytes, %d lines to %s", len(dump), strings.Count(dump, "\n"), out)
-}

cmd/service/service.go

@@ -18,7 +18,6 @@ import (
 	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/internal/registry/metaschema"
 	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -31,56 +30,74 @@ func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
 }
 
 func RegisterServiceCommandsWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
-	for _, spec := range registry.TypedServices() {
-		if spec.Name == "" || spec.ServicePath == "" || len(spec.Resources) == 0 {
+	for _, project := range registry.ListFromMetaProjects() {
+		spec := registry.LoadFromMeta(project)
+		if spec == nil {
 			continue
 		}
-		registerServiceWithContext(ctx, parent, spec, f)
+		specName := registry.GetStrFromMap(spec, "name")
+		servicePath := registry.GetStrFromMap(spec, "servicePath")
+		if specName == "" || servicePath == "" {
+			continue
+		}
+		resources, _ := spec["resources"].(map[string]interface{})
+		if resources == nil {
+			continue
+		}
+		registerServiceWithContext(ctx, parent, spec, resources, f)
 	}
 }
 
 func registerService(parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
-	svc := registry.MapToService(spec)
-	svc.Resources = registry.MapToResources(resources)
-	registerServiceWithContext(context.Background(), parent, svc, f)
+	registerServiceWithContext(context.Background(), parent, spec, resources, f)
 }
 
-func registerServiceWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, f *cmdutil.Factory) {
-	specDesc := registry.GetServiceDescription(spec.Name, "en")
+func registerServiceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, resources map[string]interface{}, f *cmdutil.Factory) {
+	specName := registry.GetStrFromMap(spec, "name")
+	specDesc := registry.GetServiceDescription(specName, "en")
 	if specDesc == "" {
-		specDesc = spec.Description
+		specDesc = registry.GetStrFromMap(spec, "description")
 	}
 
 	// Find existing service command or create one
 	var svc *cobra.Command
 	for _, c := range parent.Commands() {
-		if c.Name() == spec.Name {
+		if c.Name() == specName {
 			svc = c
 			break
 		}
 	}
 	if svc == nil {
 		svc = &cobra.Command{
-			Use:   spec.Name,
+			Use:   specName,
 			Short: specDesc,
 		}
 		parent.AddCommand(svc)
 	}
 
-	for _, resource := range spec.Resources {
-		registerResourceWithContext(ctx, svc, spec, resource, f)
+	for resName, resource := range resources {
+		resMap, _ := resource.(map[string]interface{})
+		if resMap == nil {
+			continue
+		}
+		registerResourceWithContext(ctx, svc, spec, resName, resMap, f)
 	}
 }
 
-func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, resource metaschema.Resource, f *cmdutil.Factory) {
+func registerResourceWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, name string, resource map[string]interface{}, f *cmdutil.Factory) {
 	res := &cobra.Command{
-		Use:   resource.Name,
-		Short: resource.Name + " operations",
+		Use:   name,
+		Short: name + " operations",
 	}
 	parent.AddCommand(res)
 
-	for _, method := range resource.Methods {
-		registerMethodWithContext(ctx, res, spec, method, method.Name, resource.Name, f)
+	methods, _ := resource["methods"].(map[string]interface{})
+	for methodName, method := range methods {
+		methodMap, _ := method.(map[string]interface{})
+		if methodMap == nil {
+			continue
+		}
+		registerMethodWithContext(ctx, res, spec, methodMap, methodName, name, f)
 	}
 }
 
@@ -108,36 +125,31 @@ type ServiceMethodOptions struct {
 	FileFields []string // auto-detected file field names from metadata
 }
 
-// detectFileFieldsTyped returns the names of file-type fields in the method's
-// request body (used to decide whether to register --file).
-func detectFileFieldsTyped(m metaschema.Method) []string {
-	var fields []string
-	for _, fld := range m.RequestBody {
-		if fld.Type == "file" {
-			fields = append(fields, fld.Name)
-		}
-	}
-	return fields
+// detectFileFields delegates to the shared cmdutil.DetectFileFields helper.
+func detectFileFields(method map[string]interface{}) []string {
+	return cmdutil.DetectFileFields(method)
 }
 
-func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec metaschema.Service, method metaschema.Method, name string, resName string, f *cmdutil.Factory) {
+func registerMethodWithContext(ctx context.Context, parent *cobra.Command, spec map[string]interface{}, method map[string]interface{}, name string, resName string, f *cmdutil.Factory) {
 	parent.AddCommand(NewCmdServiceMethodWithContext(ctx, f, spec, method, name, resName, nil))
 }
 
-// NewCmdServiceMethod creates a command for a dynamically registered service
-// method from map specs (kept for tests; converts to typed internally).
+// NewCmdServiceMethod creates a command for a dynamically registered service method.
 func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
-	return NewCmdServiceMethodWithContext(context.Background(), f, registry.MapToService(spec), registry.MapToMethod(name, method), name, resName, runF)
+	return NewCmdServiceMethodWithContext(context.Background(), f, spec, method, name, resName, runF)
 }
 
-func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec metaschema.Service, method metaschema.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
-	desc := method.Description
-	httpMethod := method.HTTPMethod
-	risk := method.Risk
-	schemaPath := fmt.Sprintf("%s.%s.%s", spec.Name, resName, name)
+func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	desc := registry.GetStrFromMap(method, "description")
+	httpMethod := registry.GetStrFromMap(method, "httpMethod")
+	risk := registry.GetStrFromMap(method, "risk")
+	specName := registry.GetStrFromMap(spec, "name")
+	schemaPath := fmt.Sprintf("%s.%s.%s", specName, resName, name)
 
 	opts := &ServiceMethodOptions{
 		Factory:    f,
+		Spec:       spec,
+		Method:     method,
 		SchemaPath: schemaPath,
 	}
 	var asStr string
@@ -147,10 +159,6 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 		Short: desc,
 		Long:  fmt.Sprintf("%s\n\nView parameter definitions before calling:\n  lark-cli schema %s", desc, schemaPath),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			// Materialize the maps the execution path still reads lazily — only
-			// when THIS command actually runs, never at startup.
-			opts.Spec = registry.ServiceToMap(spec)
-			opts.Method = registry.MethodToMap(method)
 			opts.Cmd = cmd
 			opts.Ctx = cmd.Context()
 			opts.As = core.Identity(asStr)
@@ -180,7 +188,7 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 	}
 
 	// Conditionally register --file for methods with file-type fields.
-	fileFields := detectFileFieldsTyped(method)
+	fileFields := detectFileFields(method)
 	opts.FileFields = fileFields
 	if len(fileFields) > 0 {
 		switch httpMethod {
@@ -192,15 +200,10 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
 	})
 
-	// meta_data.json carries no per-method tips; SetTips(nil) matches prior behavior.
-	cmdutil.SetTips(cmd, nil)
+	cmdutil.SetTips(cmd, registry.GetStrSliceFromMap(method, "tips"))
 	cmdutil.SetRisk(cmd, risk)
-	if len(method.AccessTokens) > 0 {
-		toks := make([]interface{}, len(method.AccessTokens))
-		for i, t := range method.AccessTokens {
-			toks[i] = t
-		}
-		cmdutil.SetSupportedIdentities(cmd, cmdutil.AccessTokensToIdentities(toks))
+	if tokens, ok := method["accessTokens"].([]interface{}); ok && len(tokens) > 0 {
+		cmdutil.SetSupportedIdentities(cmd, cmdutil.AccessTokensToIdentities(tokens))
 	}
 
 	return cmd

cmd/service/service_test.go

@@ -11,7 +11,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/registry"
 	"github.com/spf13/cobra"
 )
 
@@ -753,7 +752,7 @@ func TestDetectFileFields(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := detectFileFieldsTyped(registry.MapToMethod("", tt.method))
+			got := detectFileFields(tt.method)
 			if len(got) != len(tt.want) {
 				t.Errorf("detectFileFields() = %v, want %v", got, tt.want)
 				return

internal/client/client.go

@@ -153,9 +153,79 @@ func (c *APIClient) DoSDKRequest(ctx context.Context, req *larkcore.ApiReq, as c
 	if err != nil {
 		return nil, WrapDoAPIError(err)
 	}
+	c.logAPIResponse(req, resp)
 	return resp, nil
 }
 
+func (c *APIClient) logAPIResponse(req *larkcore.ApiReq, resp *larkcore.ApiResp) {
+	if resp == nil {
+		return
+	}
+	logID := strings.TrimSpace(resp.LogId())
+	if logID == "" {
+		return
+	}
+	method, path := apiReqLogFields(req, "")
+	fmt.Fprintf(c.errOut(), "[lark-cli] api-response: method=%s path=%s status=%d log_id=%s\n", method, path, resp.StatusCode, logID)
+}
+
+func (c *APIClient) logStreamResponse(req *larkcore.ApiReq, requestURL string, resp *http.Response) {
+	if resp == nil {
+		return
+	}
+	logID := streamLogID(resp.Header)
+	if logID == "" {
+		return
+	}
+	method, path := apiReqLogFields(req, requestURL)
+	fmt.Fprintf(c.errOut(), "[lark-cli] api-response: method=%s path=%s status=%d log_id=%s\n", method, path, resp.StatusCode, logID)
+}
+
+func (c *APIClient) errOut() io.Writer {
+	if c != nil && c.ErrOut != nil {
+		return c.ErrOut
+	}
+	return io.Discard
+}
+
+func apiReqLogFields(req *larkcore.ApiReq, fallbackURL string) (string, string) {
+	method := ""
+	path := ""
+	if req != nil {
+		method = req.HttpMethod
+		path = req.ApiPath
+	}
+	method = strings.ToUpper(strings.TrimSpace(method))
+	if method == "" {
+		method = "UNKNOWN"
+	}
+	path = requestLogPath(path)
+	if path == "missing" {
+		path = requestLogPath(fallbackURL)
+	}
+	return method, path
+}
+
+func requestLogPath(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "missing"
+	}
+	if u, err := url.Parse(raw); err == nil && u.IsAbs() {
+		if u.EscapedPath() != "" {
+			return u.EscapedPath()
+		}
+		return "/"
+	}
+	if i := strings.Index(raw, "?"); i >= 0 {
+		raw = raw[:i]
+	}
+	if raw == "" {
+		return "missing"
+	}
+	return raw
+}
+
 // DoStream executes a streaming HTTP request against the Lark OpenAPI endpoint.
 // Unlike DoSDKRequest (which buffers the full body via the SDK), DoStream returns
 // a live *http.Response whose Body is an io.Reader for streaming consumption.
@@ -224,6 +294,7 @@ func (c *APIClient) DoStream(ctx context.Context, req *larkcore.ApiReq, as core.
 		return nil, errs.NewNetworkError(classifyNetworkSubtype(err), "stream request failed: %s", err).WithCause(err)
 	}
 	resp.Body = &cancelOnCloseBody{ReadCloser: resp.Body, cancel: cancel}
+	c.logStreamResponse(req, requestURL, resp)
 
 	// Handle HTTP errors internally
 	if resp.StatusCode >= 400 {

internal/client/client_test.go

@@ -464,6 +464,48 @@ func TestDoStream_TransportFailureSplitsSubtype(t *testing.T) {
 	}
 }
 
+func TestDoStream_LogsLogIDToErrOut(t *testing.T) {
+	errBuf := &bytes.Buffer{}
+	rt := roundTripFunc(func(_ *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header: http.Header{
+				"Content-Type":              []string{"application/octet-stream"},
+				larkcore.HttpHeaderKeyLogId: []string{"stream-log-123"},
+			},
+			Body: io.NopCloser(strings.NewReader("ok")),
+		}, nil
+	})
+	ac := &APIClient{
+		HTTP:       &http.Client{Transport: rt},
+		ErrOut:     errBuf,
+		Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
+		Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
+	}
+
+	resp, err := ac.DoStream(context.Background(), &larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    "/open-apis/drive/v1/medias/file_token/download",
+	}, core.AsBot)
+	if err != nil {
+		t.Fatalf("DoStream() error = %v", err)
+	}
+	defer resp.Body.Close()
+
+	got := errBuf.String()
+	for _, want := range []string{
+		"[lark-cli] api-response:",
+		"method=GET",
+		"path=/open-apis/drive/v1/medias/file_token/download",
+		"status=200",
+		"log_id=stream-log-123",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("log missing %q; got:\n%s", want, got)
+		}
+	}
+}
+
 // failingTokenResolver always returns TokenUnavailableError, exercising the
 // auth/credential failure path through resolveAccessToken.
 type failingTokenResolver struct{}
@@ -618,6 +660,41 @@ func TestDoSDKRequest_TransportFailureWrapsAsNetwork(t *testing.T) {
 	}
 }
 
+func TestDoSDKRequest_LogsLogIDToErrOut(t *testing.T) {
+	rt := roundTripFunc(func(_ *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header: http.Header{
+				"Content-Type":              []string{"application/json"},
+				larkcore.HttpHeaderKeyLogId: []string{"sdk-log-123"},
+			},
+			Body: io.NopCloser(strings.NewReader(`{"code":0,"msg":"ok","data":{}}`)),
+		}, nil
+	})
+	ac, errBuf := newTestAPIClient(t, rt)
+
+	_, err := ac.DoSDKRequest(context.Background(), &larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    "/open-apis/contact/v3/users/me",
+	}, core.AsBot)
+	if err != nil {
+		t.Fatalf("DoSDKRequest() error = %v", err)
+	}
+
+	got := errBuf.String()
+	for _, want := range []string{
+		"[lark-cli] api-response:",
+		"method=GET",
+		"path=/open-apis/contact/v3/users/me",
+		"status=200",
+		"log_id=sdk-log-123",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("log missing %q; got:\n%s", want, got)
+		}
+	}
+}
+
 // TestCallAPI_ParseJSONFailureWrapsAsAPI pins the typed-envelope contract for
 // malformed JSON response bodies: WrapJSONResponseParseError emits
 // *errs.InternalError{Subtype: invalid_response} with the rawAPIJSONHint

internal/cmdutil/factory.go

@@ -30,11 +30,10 @@ type InvocationContext struct {
 }
 
 type Factory struct {
-	Config      func() (*core.CliConfig, error) // lazily loads app config from Credential
-	ConfigBrand func() (core.LarkBrand, bool)   // brand only, no secret decryption — for startup help/registration (avoids keychain)
-	HttpClient  func() (*http.Client, error)    // HTTP client for non-Lark API calls (with retry and security headers)
-	LarkClient  func() (*lark.Client, error)    // Lark SDK client for all Open API calls
-	IOStreams   *IOStreams                      // stdin/stdout/stderr streams
+	Config     func() (*core.CliConfig, error) // lazily loads app config from Credential
+	HttpClient func() (*http.Client, error)    // HTTP client for non-Lark API calls (with retry and security headers)
+	LarkClient func() (*lark.Client, error)    // Lark SDK client for all Open API calls
+	IOStreams  *IOStreams                      // stdin/stdout/stderr streams
 
 	Invocation           InvocationContext       // Immutable call context; do not mutate after Factory construction.
 	Keychain             keychain.KeychainAccess // secret storage (real keychain in prod, mock in tests)
@@ -152,14 +151,11 @@ func (f *Factory) ResolveStrictMode(ctx context.Context) core.StrictMode {
 	if f.Credential == nil {
 		return core.StrictModeOff
 	}
-	// Strict mode is plain config metadata; resolve it WITHOUT decrypting the
-	// app secret so identity-flag registration at startup never touches the
-	// keychain (ResolveStrictMode is called per command during Build).
-	_, supported, ok := f.Credential.ResolveMeta(ctx)
-	if !ok {
+	acct, err := f.Credential.ResolveAccount(ctx)
+	if err != nil || acct == nil {
 		return core.StrictModeOff
 	}
-	ids := extcred.IdentitySupport(supported)
+	ids := extcred.IdentitySupport(acct.SupportedIdentities)
 	switch {
 	case ids.BotOnly():
 		return core.StrictModeBot

internal/cmdutil/factory_default.go

@@ -78,18 +78,6 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		return cfg, nil
 	})
 
-	// ConfigBrand resolves just the brand without decrypting the app secret, so
-	// brand-aware help and shortcut registration at startup do not touch the
-	// keychain. It still initializes the registry with the resolved brand — the
-	// same side effect Config has, minus the secret.
-	f.ConfigBrand = sync.OnceValues(func() (core.LarkBrand, bool) {
-		brand, _, ok := f.Credential.ResolveMeta(context.Background())
-		if ok {
-			registry.InitWithBrand(brand)
-		}
-		return brand, ok
-	})
-
 	// Phase 4: LarkClient from Credential (placeholder AppSecret)
 	f.LarkClient = cachedLarkClientFunc(f)
 

internal/cmdutil/secheader.go

@@ -28,8 +28,14 @@ const (
 	HeaderShortcut    = "X-Cli-Shortcut"
 	HeaderExecutionId = "X-Cli-Execution-Id"
 	HeaderAgentTrace  = "X-Agent-Trace"
+	HeaderTTEnv       = "X-Tt-Env"
+	HeaderUsePPE      = "X-Use-Ppe"
+	HeaderRPCAppID    = "Rpc-Persist-Cli-Req-App-Id"
 
 	SourceValue = "lark-cli"
+	TTEnvValue  = "ppe_doubao_office_local"
+	UsePPEValue = "1"
+	RPCAppID    = "497858"
 
 	HeaderUserAgent = "User-Agent"
 
@@ -75,6 +81,9 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
+	h.Set(HeaderTTEnv, TTEnvValue)
+	h.Set(HeaderUsePPE, UsePPEValue)
+	h.Set(HeaderRPCAppID, RPCAppID)
 	if v := AgentTraceValue(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}

internal/cmdutil/secheader_test.go

@@ -256,13 +256,26 @@ func TestBaseSecurityHeaders_IncludesBuildHeader(t *testing.T) {
 
 func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 	h := BaseSecurityHeaders()
-	for _, key := range []string{HeaderSource, HeaderVersion, HeaderBuild, HeaderUserAgent} {
+	for _, key := range []string{HeaderSource, HeaderVersion, HeaderBuild, HeaderUserAgent, HeaderTTEnv, HeaderUsePPE, HeaderRPCAppID} {
 		if h.Get(key) == "" {
 			t.Errorf("BaseSecurityHeaders missing %s", key)
 		}
 	}
 }
 
+func TestBaseSecurityHeaders_IncludesPersistentRequestHeaders(t *testing.T) {
+	h := BaseSecurityHeaders()
+	if got := h.Get(HeaderTTEnv); got != TTEnvValue {
+		t.Fatalf("BaseSecurityHeaders()[%s] = %q, want %q", HeaderTTEnv, got, TTEnvValue)
+	}
+	if got := h.Get(HeaderUsePPE); got != UsePPEValue {
+		t.Fatalf("BaseSecurityHeaders()[%s] = %q, want %q", HeaderUsePPE, got, UsePPEValue)
+	}
+	if got := h.Get(HeaderRPCAppID); got != RPCAppID {
+		t.Fatalf("BaseSecurityHeaders()[%s] = %q, want %q", HeaderRPCAppID, got, RPCAppID)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // AgentTraceValue / HeaderAgentTrace
 // ---------------------------------------------------------------------------

internal/cmdutil/testing.go

@@ -65,13 +65,7 @@ func TestFactory(t *testing.T, config *core.CliConfig) (*Factory, *bytes.Buffer,
 	)
 
 	f := &Factory{
-		Config: func() (*core.CliConfig, error) { return config, nil },
-		ConfigBrand: func() (core.LarkBrand, bool) {
-			if config != nil {
-				return config.Brand, true
-			}
-			return "", false
-		},
+		Config:         func() (*core.CliConfig, error) { return config, nil },
 		HttpClient:     func() (*http.Client, error) { return mockClient, nil },
 		LarkClient:     func() (*lark.Client, error) { return testLarkClient, nil },
 		IOStreams:      &IOStreams{In: nil, Out: stdoutBuf, ErrOut: stderrBuf},

internal/credential/credential_provider.go

@@ -21,14 +21,6 @@ type DefaultAccountResolver interface {
 	ResolveAccount(ctx context.Context) (*Account, error)
 }
 
-// metaResolver is an optional capability: resolve config metadata (brand +
-// strict-mode identity support) without resolving the app secret (no keychain
-// access). Providers that don't implement it fall back to ResolveAccount inside
-// CredentialProvider.ResolveMeta.
-type metaResolver interface {
-	ResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool)
-}
-
 // DefaultTokenResolver is implemented by the default token provider.
 type DefaultTokenResolver interface {
 	ResolveToken(ctx context.Context, req TokenSpec) (*TokenResult, error)
@@ -149,11 +141,6 @@ type CredentialProvider struct {
 	accountErr     error
 	selectedSource credentialSource
 
-	metaOnce   sync.Once
-	metaBrand  core.LarkBrand
-	metaIdents uint8
-	metaOK     bool
-
 	hintOnce sync.Once
 	hint     *IdentityHint
 	hintErr  error
@@ -185,44 +172,6 @@ func (p *CredentialProvider) ResolveAccount(ctx context.Context) (*Account, erro
 	return p.account, p.accountErr
 }
 
-// ResolveMeta resolves config metadata — brand and strict-mode identity support
-// — cheaply, WITHOUT decrypting the app secret for the default
-// (config.json/keychain) provider. It mirrors doResolveAccount's provider
-// selection: external providers (env/sidecar) are asked first via ResolveAccount
-// (they do not touch the keychain), then the default provider's keychain-free
-// metaResolver path. Cached after first call. Best-effort: returns ok=false when
-// nothing is configured, so callers keep their defaults. Used for brand-aware
-// help text, shortcut registration, and strict-mode checks at startup, where
-// decrypting the secret would be wasteful.
-func (p *CredentialProvider) ResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool) {
-	p.metaOnce.Do(func() {
-		p.metaBrand, p.metaIdents, p.metaOK = p.doResolveMeta(ctx)
-	})
-	return p.metaBrand, p.metaIdents, p.metaOK
-}
-
-func (p *CredentialProvider) doResolveMeta(ctx context.Context) (core.LarkBrand, uint8, bool) {
-	for _, prov := range p.providers {
-		acct, err := prov.ResolveAccount(ctx)
-		if err != nil {
-			return "", 0, false
-		}
-		if acct != nil {
-			internal := convertAccount(acct)
-			return internal.Brand, internal.SupportedIdentities, true
-		}
-	}
-	if p.defaultAcct != nil {
-		if mr, ok := p.defaultAcct.(metaResolver); ok {
-			return mr.ResolveMeta(ctx)
-		}
-		if acct, err := p.defaultAcct.ResolveAccount(ctx); err == nil && acct != nil {
-			return acct.Brand, acct.SupportedIdentities, true
-		}
-	}
-	return "", 0, false
-}
-
 func (p *CredentialProvider) doResolveAccount(ctx context.Context) (*Account, error) {
 	for _, prov := range p.providers {
 		acct, err := prov.ResolveAccount(ctx)

internal/credential/default_provider.go

@@ -76,23 +76,6 @@ func (p *DefaultAccountProvider) ResolveAccount(ctx context.Context) (*Account,
 	return AccountFromCliConfig(cfg), nil
 }
 
-// ResolveMeta returns config metadata — brand and the strict-mode identity
-// support — from config.json WITHOUT resolving the app secret (no keychain
-// access). Both are plain config fields, so brand-aware help, shortcut
-// registration, and strict-mode checks at startup need not decrypt the secret.
-// Returns ok=false when no config exists, so callers keep their defaults.
-func (p *DefaultAccountProvider) ResolveMeta(_ context.Context) (core.LarkBrand, uint8, bool) {
-	multi, err := core.LoadMultiAppConfig()
-	if err != nil {
-		return "", 0, false
-	}
-	app := multi.CurrentAppConfig(p.profile)
-	if app == nil {
-		return "", 0, false
-	}
-	return app.Brand, strictModeToIdentitySupport(multi, p.profile), true
-}
-
 // strictModeToIdentitySupport maps the config-level strict mode to
 // the SupportedIdentities bitflag using an already-loaded MultiAppConfig.
 func strictModeToIdentitySupport(multi *core.MultiAppConfig, profileOverride string) uint8 {

internal/registry/loader.go

@@ -19,32 +19,72 @@ import (
 //go:embed scope_priorities.json scope_overrides.json
 var registryFS embed.FS
 
-// EmbeddedSpec returns the embedded baseline spec for one service as a map, or
-// nil if the service is unknown. It reads the static compile-time registry
-// (metastatic.Registry) and bypasses the remote overlay, so envelope output is
-// deterministic across machines.
-func EmbeddedSpec(serviceName string) map[string]interface{} {
-	if svc, ok := baselineServiceByName(serviceName); ok {
-		return ServiceToMap(svc)
-	}
-	return nil
+// embeddedMetaJSON is set by loader_embedded.go when meta_data.json is compiled in.
+var embeddedMetaJSON []byte
+
+// EmbeddedMetaJSON returns the raw embedded meta_data.json bytes for callers
+// that need to parse key order or other JSON-level structure not exposed by
+// LoadFromMeta (which loses map insertion order).
+func EmbeddedMetaJSON() []byte {
+	return embeddedMetaJSON
 }
 
-// EmbeddedServiceNames returns the embedded baseline service names, sorted
-// (no remote overlay).
+var (
+	embeddedServicesMap  map[string]map[string]interface{} // service name -> spec
+	embeddedServiceNames []string                          // sorted
+	embeddedParseOnce    sync.Once
+)
+
+// parseEmbeddedServices parses embeddedMetaJSON into a service name → spec map
+// without touching mergedServices. Safe to call multiple times (sync.Once).
+func parseEmbeddedServices() {
+	embeddedParseOnce.Do(func() {
+		embeddedServicesMap = make(map[string]map[string]interface{})
+		if len(embeddedMetaJSON) == 0 {
+			return
+		}
+		var wrapper struct {
+			Services []map[string]interface{} `json:"services"`
+		}
+		if err := json.Unmarshal(embeddedMetaJSON, &wrapper); err != nil {
+			return
+		}
+		for _, svc := range wrapper.Services {
+			name, _ := svc["name"].(string)
+			if name == "" {
+				continue
+			}
+			embeddedServicesMap[name] = svc
+		}
+		embeddedServiceNames = make([]string, 0, len(embeddedServicesMap))
+		for name := range embeddedServicesMap {
+			embeddedServiceNames = append(embeddedServiceNames, name)
+		}
+		sort.Strings(embeddedServiceNames)
+	})
+}
+
+// EmbeddedSpec returns the embedded spec for one service, or nil if unknown.
+// Bypasses remote overlay — used for deterministic envelope output.
+func EmbeddedSpec(serviceName string) map[string]interface{} {
+	parseEmbeddedServices()
+	return embeddedServicesMap[serviceName]
+}
+
+// EmbeddedServiceNames returns sorted embedded service names (no overlay).
+// Returns a defensive copy — callers must not mutate the package-level slice.
 func EmbeddedServiceNames() []string {
-	svcs := baselineServices()
-	out := make([]string, 0, len(svcs))
-	for _, s := range svcs {
-		out = append(out, s.Name)
-	}
-	sort.Strings(out)
+	parseEmbeddedServices()
+	out := make([]string, len(embeddedServiceNames))
+	copy(out, embeddedServiceNames)
 	return out
 }
 
 var (
-	embeddedVersion string // baseline data version (from the static registry)
-	initOnce        sync.Once
+	mergedServices    = make(map[string]map[string]interface{}) // project name → parsed spec
+	mergedProjectList []string                                  // sorted project names
+	embeddedVersion   string                                    // version from embedded meta_data.json
+	initOnce          sync.Once
 )
 
 // Init initializes the registry with default brand (feishu).
@@ -61,27 +101,55 @@ func Init() {
 func InitWithBrand(brand core.LarkBrand) {
 	initOnce.Do(func() {
 		configuredBrand = brand
-		// 1. Baseline version: the static compile-time registry (metastatic).
-		embeddedVersion = baselineVersion()
-		// 2. Remote overlay — still fetched/refreshed at runtime, decoded into
-		//    the same typed shape and merged over the baseline.
+		// 1. Load embedded meta_data.json as baseline (no-op if not compiled in)
+		loadEmbeddedIntoMerged()
+		// 2. Remote overlay
 		if remoteEnabled() && cacheWritable() {
+			// Check if brand changed since last cache
 			meta, metaErr := loadCacheMeta()
 			brandChanged := metaErr == nil && meta.Brand != "" && meta.Brand != string(brand)
 
 			if !brandChanged {
-				_ = loadCachedTyped()
+				if cached, err := loadCachedMerged(); err == nil {
+					overlayMergedServices(cached)
+				}
 			}
-			if !hasTypedData() || brandChanged {
-				// No data at all (e.g. stub build, no cache) or brand changed.
+			if len(mergedServices) == 0 || brandChanged {
+				// No data at all or brand changed — must sync fetch
 				doSyncFetch()
 			} else if shouldRefresh(meta) || metaErr != nil {
+				// Have embedded/cached data; refresh in background if TTL expired or first run
 				triggerBackgroundRefresh()
 			}
 		}
+		// 3. Build sorted project list
+		rebuildProjectList()
 	})
 }
 
+// loadEmbeddedIntoMerged parses the embedded meta_data.json and populates
+// mergedServices. No-op if meta_data.json is not compiled in.
+func loadEmbeddedIntoMerged() {
+	if len(embeddedMetaJSON) == 0 {
+		return
+	}
+	var reg MergedRegistry
+	if err := json.Unmarshal(embeddedMetaJSON, &reg); err != nil {
+		return
+	}
+	embeddedVersion = reg.Version
+	overlayMergedServices(&reg)
+}
+
+// rebuildProjectList rebuilds the sorted list of project names from mergedServices.
+func rebuildProjectList() {
+	mergedProjectList = make([]string, 0, len(mergedServices))
+	for name := range mergedServices {
+		mergedProjectList = append(mergedProjectList, name)
+	}
+	sort.Strings(mergedProjectList)
+}
+
 var cachedAllScopes map[string][]string
 
 // CollectAllScopesFromMeta collects all unique scopes from from_meta/*.json
@@ -158,11 +226,7 @@ func CollectAllScopesFromMeta(identity string) []string {
 // It returns data from the merged registry (embedded + cached remote overlay).
 func LoadFromMeta(project string) map[string]interface{} {
 	Init()
-	svc, ok := typedServiceByName(project)
-	if !ok {
-		return nil
-	}
-	return ServiceToMap(svc)
+	return mergedServices[project]
 }
 
 // ListFromMetaProjects lists available service project names (sorted).
@@ -170,7 +234,7 @@ func LoadFromMeta(project string) map[string]interface{} {
 //go:noinline
 func ListFromMetaProjects() []string {
 	Init()
-	return typedServiceNames()
+	return mergedProjectList
 }
 
 // DefaultScopeScore is the score assigned to scopes not in the priorities table.

internal/registry/loader_embedded.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import "embed"
+
+//go:embed meta_data*.json
+var metaFS embed.FS
+
+//go:embed meta_data_default.json
+var embeddedMetaDataDefaultJSON []byte
+
+func init() {
+	if data, err := metaFS.ReadFile("meta_data.json"); err == nil && len(data) > 0 {
+		embeddedMetaJSON = data
+	} else {
+		embeddedMetaJSON = embeddedMetaDataDefaultJSON
+	}
+}

internal/registry/meta_data_default.json

@@ -0,0 +1 @@
+{"version":"0.0.0","services":[]}

internal/registry/metaschema/types.go

@@ -1,99 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package metaschema defines the typed shape of the command-spec registry
-// (meta_data.json). The embedded baseline is emitted as static Go data in
-// package metastatic (no runtime JSON parse, no startup allocation); the remote
-// overlay is decoded into these same types at runtime.
-//
-// All container fields are slices (never maps): a package-level slice literal is
-// laid out in the binary's data section and costs zero heap allocation at
-// startup, whereas a map literal builds an hmap at init time. Map keys from the
-// JSON (resource/method/field names) are preserved in the Name field.
-package metaschema
-
-// Registry is the top level of meta_data.json: {version, services:[...]}.
-type Registry struct {
-	Version  string
-	Services []Service
-}
-
-// Service is one API domain (e.g. "im", "calendar").
-type Service struct {
-	Name        string
-	Version     string
-	Title       string
-	Description string
-	ServicePath string
-	Resources   []Resource // JSON "resources" map, keyed by Resource.Name
-}
-
-// Resource groups methods under a service (e.g. "messages").
-type Resource struct {
-	Name    string
-	Methods []Method // JSON "methods" map, keyed by Method.Name
-}
-
-// Method is a single API call.
-type Method struct {
-	Name           string // JSON map key
-	ID             string
-	Path           string
-	HTTPMethod     string
-	Description    string
-	Risk           string
-	DocURL         string
-	Danger         bool
-	Scopes         []string
-	AccessTokens   []string
-	ParameterOrder []string
-	RequiredScopes []string
-	Parameters     []Field     // JSON "parameters" map, keyed by Field.Name
-	RequestBody    []Field     // JSON "requestBody" map
-	ResponseBody   []Field     // JSON "responseBody" map
-	Affordance     *Affordance // optional AI-facing usage overlay; nil on most methods
-}
-
-// Field is one parameter / request-body / response-body entry. Nested object
-// fields recurse via Properties.
-type Field struct {
-	Name        string // JSON map key
-	Type        string
-	Location    string
-	Description string
-	Default     string
-	Example     string
-	EnumName    string
-	Min         string
-	Max         string
-	Ref         string
-	Required    bool
-	Options     []Option
-	Enum        []string
-	Annotations []string
-	Properties  []Field
-}
-
-// Option is one allowed value for a field with an enum-like option list.
-type Option struct {
-	Value       string
-	Description string
-}
-
-// Affordance is the optional AI-facing usage overlay for a method, surfaced in
-// the schema envelope as _meta.affordance. Absent (nil) on most methods; it is
-// authored upstream in registry-config.yaml and merged into meta_data.json.
-type Affordance struct {
-	UseWhen       []string
-	DoNotUseWhen  []string
-	Prerequisites []string
-	Examples      []AffordanceExample
-	Related       []string
-}
-
-// AffordanceExample is one ready-to-run example: a one-line description plus a
-// complete lark-cli command string.
-type AffordanceExample struct {
-	Description string
-	Command     string
-}

internal/registry/metastatic/gen.go

@@ -1,255 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build ignore
-
-// Command gen reads internal/registry/meta_data.json and emits
-// meta_data_gen.go: the embedded command spec as a single static
-// metaschema.Registry literal (zero runtime JSON parse, zero startup heap
-// allocation). Run via: go run internal/registry/metastatic/gen.go
-//
-// Maps in the JSON (resources/methods/fields) are emitted as slices sorted by
-// key so generation is deterministic.
-package main
-
-import (
-	"encoding/json"
-	"fmt"
-	"go/format"
-	"os"
-	"sort"
-	"strings"
-)
-
-const (
-	inPath  = "internal/registry/meta_data.json"
-	outPath = "internal/registry/metastatic/meta_data_gen.go"
-)
-
-func gs(m map[string]any, k string) string {
-	if v, ok := m[k].(string); ok {
-		return v
-	}
-	return ""
-}
-func gb(m map[string]any, k string) bool {
-	if v, ok := m[k].(bool); ok {
-		return v
-	}
-	return false
-}
-func gss(m map[string]any, k string) []string {
-	raw, _ := m[k].([]any)
-	out := make([]string, 0, len(raw))
-	for _, e := range raw {
-		if s, ok := e.(string); ok {
-			out = append(out, s)
-		}
-	}
-	return out
-}
-func gm(m map[string]any, k string) map[string]any {
-	if v, ok := m[k].(map[string]any); ok {
-		return v
-	}
-	return nil
-}
-func sortedKeys(m map[string]any) []string {
-	ks := make([]string, 0, len(m))
-	for k := range m {
-		ks = append(ks, k)
-	}
-	sort.Strings(ks)
-	return ks
-}
-
-func emitStrSlice(b *strings.Builder, name string, vs []string) {
-	if len(vs) == 0 {
-		return
-	}
-	fmt.Fprintf(b, "%s: []string{", name)
-	for _, v := range vs {
-		fmt.Fprintf(b, "%q, ", v)
-	}
-	b.WriteString("},\n")
-}
-
-func emitOptions(b *strings.Builder, raw []any) {
-	if len(raw) == 0 {
-		return
-	}
-	b.WriteString("Options: []metaschema.Option{")
-	for _, e := range raw {
-		o, _ := e.(map[string]any)
-		fmt.Fprintf(b, "{Value: %q, Description: %q}, ", gs(o, "value"), gs(o, "description"))
-	}
-	b.WriteString("},\n")
-}
-
-// emitFields emits a metaschema.Field slice from a JSON map[fieldName]fieldSpec.
-func emitFields(b *strings.Builder, label string, fm map[string]any) {
-	if len(fm) == 0 {
-		return
-	}
-	fmt.Fprintf(b, "%s: []metaschema.Field{\n", label)
-	for _, name := range sortedKeys(fm) {
-		f, _ := fm[name].(map[string]any)
-		if f == nil {
-			continue
-		}
-		b.WriteString("{")
-		fmt.Fprintf(b, "Name: %q, ", name)
-		for _, kv := range []struct{ k, field string }{
-			{"type", "Type"}, {"location", "Location"}, {"description", "Description"},
-			{"default", "Default"}, {"example", "Example"}, {"enumName", "EnumName"},
-			{"min", "Min"}, {"max", "Max"}, {"ref", "Ref"},
-		} {
-			if v := gs(f, kv.k); v != "" {
-				fmt.Fprintf(b, "%s: %q, ", kv.field, v)
-			}
-		}
-		if gb(f, "required") {
-			b.WriteString("Required: true, ")
-		}
-		emitStrSlice(b, "Enum", gss(f, "enum"))
-		emitStrSlice(b, "Annotations", gss(f, "annotations"))
-		if opts, ok := f["options"].([]any); ok {
-			emitOptions(b, opts)
-		}
-		if props := gm(f, "properties"); props != nil {
-			emitFields(b, "Properties", props)
-		}
-		b.WriteString("},\n")
-	}
-	b.WriteString("},\n")
-}
-
-// emitAffordance emits a metaschema.Affordance literal from a method's
-// "affordance" JSON object, or nothing when absent/empty.
-func emitAffordance(b *strings.Builder, raw map[string]any) {
-	if raw == nil {
-		return
-	}
-	useWhen := gss(raw, "use_when")
-	doNot := gss(raw, "do_not_use_when")
-	prereq := gss(raw, "prerequisites")
-	related := gss(raw, "related")
-	examples, _ := raw["examples"].([]any)
-	if len(useWhen) == 0 && len(doNot) == 0 && len(prereq) == 0 && len(related) == 0 && len(examples) == 0 {
-		return
-	}
-	b.WriteString("Affordance: &metaschema.Affordance{")
-	emitStrSlice(b, "UseWhen", useWhen)
-	emitStrSlice(b, "DoNotUseWhen", doNot)
-	emitStrSlice(b, "Prerequisites", prereq)
-	if len(examples) > 0 {
-		b.WriteString("Examples: []metaschema.AffordanceExample{")
-		for _, e := range examples {
-			ex, _ := e.(map[string]any)
-			fmt.Fprintf(b, "{Description: %q, Command: %q}, ", gs(ex, "description"), gs(ex, "command"))
-		}
-		b.WriteString("},\n")
-	}
-	emitStrSlice(b, "Related", related)
-	b.WriteString("},\n")
-}
-
-func emitMethods(b *strings.Builder, mm map[string]any) {
-	b.WriteString("Methods: []metaschema.Method{\n")
-	for _, name := range sortedKeys(mm) {
-		m, _ := mm[name].(map[string]any)
-		if m == nil {
-			continue
-		}
-		b.WriteString("{")
-		fmt.Fprintf(b, "Name: %q, ID: %q, Path: %q, HTTPMethod: %q, Description: %q, ",
-			name, gs(m, "id"), gs(m, "path"), gs(m, "httpMethod"), gs(m, "description"))
-		if v := gs(m, "risk"); v != "" {
-			fmt.Fprintf(b, "Risk: %q, ", v)
-		}
-		if v := gs(m, "docUrl"); v != "" {
-			fmt.Fprintf(b, "DocURL: %q, ", v)
-		}
-		if gb(m, "danger") {
-			b.WriteString("Danger: true, ")
-		}
-		b.WriteString("\n")
-		emitStrSlice(b, "Scopes", gss(m, "scopes"))
-		emitStrSlice(b, "AccessTokens", gss(m, "accessTokens"))
-		emitStrSlice(b, "ParameterOrder", gss(m, "parameterOrder"))
-		emitStrSlice(b, "RequiredScopes", gss(m, "requiredScopes"))
-		emitFields(b, "Parameters", gm(m, "parameters"))
-		emitFields(b, "RequestBody", gm(m, "requestBody"))
-		emitFields(b, "ResponseBody", gm(m, "responseBody"))
-		emitAffordance(b, gm(m, "affordance"))
-		b.WriteString("},\n")
-	}
-	b.WriteString("},\n")
-}
-
-func main() {
-	data, err := os.ReadFile(inPath)
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "read:", err)
-		os.Exit(1)
-	}
-	var reg map[string]any
-	if err := json.Unmarshal(data, &reg); err != nil {
-		fmt.Fprintln(os.Stderr, "unmarshal:", err)
-		os.Exit(1)
-	}
-
-	var b strings.Builder
-	b.WriteString("// Code generated from meta_data.json by gen.go. DO NOT EDIT.\n")
-	b.WriteString("// Gitignored; produced at build time by `make fetch_meta`.\n\n")
-	b.WriteString("package metastatic\n\n")
-	b.WriteString("import \"github.com/larksuite/cli/internal/registry/metaschema\"\n\n")
-	b.WriteString("// registryData holds the command spec as static Go data. It is a\n")
-	b.WriteString("// package-level var, so its backing arrays live in the binary's static\n")
-	b.WriteString("// section (zero heap alloc on read). init() wires it into the Registry\n")
-	b.WriteString("// declared by stub.go with a single struct-header copy. No build tag is\n")
-	b.WriteString("// needed: when this generated file is absent (fresh checkout) stub.go's\n")
-	b.WriteString("// empty Registry stands alone; when present, init() augments it.\n")
-	b.WriteString("var registryData = metaschema.Registry{\n")
-	fmt.Fprintf(&b, "Version: %q,\n", gs(reg, "version"))
-	b.WriteString("Services: []metaschema.Service{\n")
-	svcs, _ := reg["services"].([]any)
-	for _, sv := range svcs {
-		s, _ := sv.(map[string]any)
-		if s == nil {
-			continue
-		}
-		b.WriteString("{")
-		fmt.Fprintf(&b, "Name: %q, Version: %q, Title: %q, Description: %q, ServicePath: %q,\n",
-			gs(s, "name"), gs(s, "version"), gs(s, "title"), gs(s, "description"), gs(s, "servicePath"))
-		b.WriteString("Resources: []metaschema.Resource{\n")
-		res := gm(s, "resources")
-		for _, rname := range sortedKeys(res) {
-			r, _ := res[rname].(map[string]any)
-			if r == nil {
-				continue
-			}
-			fmt.Fprintf(&b, "{Name: %q,\n", rname)
-			emitMethods(&b, gm(r, "methods"))
-			b.WriteString("},\n")
-		}
-		b.WriteString("},\n") // Resources
-		b.WriteString("},\n") // Service
-	}
-	b.WriteString("},\n")  // Services
-	b.WriteString("}\n\n") // registryData literal
-	b.WriteString("func init() { Registry = registryData }\n")
-
-	src, err := format.Source([]byte(b.String()))
-	if err != nil {
-		// Write unformatted for debugging, then fail.
-		_ = os.WriteFile(outPath+".broken", []byte(b.String()), 0644)
-		fmt.Fprintln(os.Stderr, "gofmt:", err)
-		os.Exit(1)
-	}
-	if err := os.WriteFile(outPath, src, 0644); err != nil {
-		fmt.Fprintln(os.Stderr, "write:", err)
-		os.Exit(1)
-	}
-	fmt.Printf("wrote %s (%d services, %d bytes)\n", outPath, len(svcs), len(src))
-}

internal/registry/metastatic/stub.go

@@ -1,15 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package metastatic
-
-import "github.com/larksuite/cli/internal/registry/metaschema"
-
-// Registry is the command spec as static Go data. It is declared here (zero
-// value) so the package always compiles, and populated by meta_data_gen.go's
-// init() when that generated file is present. On a fresh checkout the generated
-// file is absent — it is gitignored and produced at build time by
-// `make gen_meta` — so Registry stays empty. This keeps the "heavy spec is
-// never committed, only generated" model, now without a build tag: the
-// generated file augments this one rather than replacing it under a tag.
-var Registry = metaschema.Registry{}

internal/registry/metastatic_validate_test.go

@@ -1,90 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Validation for the static-meta registry: the generated metastatic.Registry is
-// the sole embedded baseline (no JSON parsed at runtime), and a deep read of it
-// allocates nothing. The data is generated from meta_data.json at build time
-// (`make fetch_meta`) and is gitignored, so these tests skip on a bare checkout
-// where it has not been generated yet.
-package registry
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/registry/metaschema"
-	"github.com/larksuite/cli/internal/registry/metastatic"
-)
-
-func countFieldsStatic(fs []metaschema.Field) int {
-	n := 0
-	for _, f := range fs {
-		n++
-		n += countFieldsStatic(f.Properties)
-	}
-	return n
-}
-
-func countStatic() (svc, res, meth, fld int) {
-	svc = len(metastatic.Registry.Services)
-	for _, s := range metastatic.Registry.Services {
-		for _, r := range s.Resources {
-			res++
-			for _, m := range r.Methods {
-				meth++
-				fld += countFieldsStatic(m.Parameters) + countFieldsStatic(m.RequestBody) + countFieldsStatic(m.ResponseBody)
-			}
-		}
-	}
-	return
-}
-
-// TestStaticRegistryPopulated checks the generated registry carries data. It
-// skips on a bare checkout where meta_data_gen.go has not been generated yet.
-func TestStaticRegistryPopulated(t *testing.T) {
-	if len(metastatic.Registry.Services) == 0 {
-		t.Skip("static registry empty; run `make fetch_meta` to generate it")
-	}
-	svc, res, meth, fld := countStatic()
-	t.Logf("static: services=%d resources=%d methods=%d fields=%d", svc, res, meth, fld)
-	if svc == 0 || res == 0 || meth == 0 || fld == 0 {
-		t.Fatalf("static registry incomplete: svc=%d res=%d meth=%d fld=%d", svc, res, meth, fld)
-	}
-	if metastatic.Registry.Version == "" {
-		t.Error("static registry has empty Version")
-	}
-}
-
-var sinkInt int
-
-// --- zero-alloc: a deep read of the static registry must allocate nothing ---
-
-func deepReadStatic() int {
-	n := 0
-	for _, s := range metastatic.Registry.Services {
-		n += len(s.Name)
-		for _, r := range s.Resources {
-			for _, m := range r.Methods {
-				n += len(m.ID) + len(m.Scopes) + countFieldsStatic(m.Parameters) + countFieldsStatic(m.ResponseBody)
-			}
-		}
-	}
-	return n
-}
-
-func TestStaticReadZeroAlloc(t *testing.T) {
-	if len(metastatic.Registry.Services) == 0 {
-		t.Skip("static registry empty; run `make fetch_meta` to generate it")
-	}
-	avg := testing.AllocsPerRun(50, func() { sinkInt = deepReadStatic() })
-	t.Logf("static deep-read: %.1f allocs/op", avg)
-	if avg > 0 {
-		t.Errorf("static read allocates %.1f/op, want 0 (data should be in the binary, not heap)", avg)
-	}
-}
-
-func BenchmarkReadStaticRegistry(b *testing.B) {
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		sinkInt = deepReadStatic()
-	}
-}

internal/registry/remote.go

@@ -147,6 +147,22 @@ func saveCacheMeta(meta CacheMeta) error {
 	return validate.AtomicWrite(cacheMetaPath(), data, 0644)
 }
 
+func loadCachedMerged() (*MergedRegistry, error) {
+	path := cachePath()
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var reg MergedRegistry
+	if err := json.Unmarshal(data, &reg); err != nil {
+		// Cache corrupted — remove it so next run triggers a fresh fetch
+		vfs.Remove(path)
+		vfs.Remove(cacheMetaPath())
+		return nil, err
+	}
+	return &reg, nil
+}
+
 func saveCachedMerged(data []byte, meta CacheMeta) error {
 	if err := vfs.MkdirAll(cacheDir(), 0700); err != nil {
 		return err
@@ -237,7 +253,7 @@ func doSyncFetch() {
 		Brand:       string(configuredBrand),
 	}
 	_ = saveCachedMerged(data, meta)
-	_ = loadCachedTyped()
+	overlayMergedServices(reg)
 }
 
 // --- background refresh ---
@@ -292,3 +308,15 @@ func shouldRefresh(meta CacheMeta) bool {
 	}
 	return time.Since(time.Unix(meta.LastCheckAt, 0)) > metaTTL()
 }
+
+// overlayMergedServices merges remote services into the in-memory map.
+// Remote entries override embedded entries with the same name.
+func overlayMergedServices(reg *MergedRegistry) {
+	for _, svc := range reg.Services {
+		name, ok := svc["name"].(string)
+		if !ok || name == "" {
+			continue
+		}
+		mergedServices[name] = svc
+	}
+}

internal/registry/remote_test.go

@@ -15,8 +15,6 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/registry/metaschema"
-	"github.com/larksuite/cli/internal/registry/metastatic"
 )
 
 // waitBackgroundRefresh blocks until any in-flight background refresh started by
@@ -32,7 +30,8 @@ func resetInit() {
 	// reads globals this function mutates (see CI race: TestComputeMinimumScopeSet → Tenant).
 	waitBackgroundRefresh()
 	initOnce = sync.Once{}
-	resetTyped()
+	mergedServices = make(map[string]map[string]interface{})
+	mergedProjectList = nil
 	embeddedVersion = ""
 	cachedAllScopes = nil
 	cachedScopePriorities = nil
@@ -56,10 +55,16 @@ func TestResetInitClearsEmbeddedVersion(t *testing.T) {
 	}
 }
 
-// hasEmbeddedServices returns true if the static registry has services compiled
-// in (generated from meta_data.json at build time).
+// hasEmbeddedServices returns true if meta_data.json with real services is compiled in.
 func hasEmbeddedServices() bool {
-	return len(metastatic.Registry.Services) > 0
+	if len(embeddedMetaJSON) == 0 {
+		return false
+	}
+	var reg MergedRegistry
+	if err := json.Unmarshal(embeddedMetaJSON, &reg); err != nil {
+		return false
+	}
+	return len(reg.Services) > 0
 }
 
 // testRegistry returns a minimal MergedRegistry with one service.
@@ -297,36 +302,50 @@ func TestMetaTTL(t *testing.T) {
 	}
 }
 
-func TestRemoteOverlayTyped(t *testing.T) {
+func TestOverlayMergedServices(t *testing.T) {
 	resetInit()
-	setRemoteOverrides([]metaschema.Service{
-		{Name: "existing", Version: "v2"},
-		{Name: "brand_new", Version: "v1"},
-	})
+	mergedServices = make(map[string]map[string]interface{})
+	mergedServices["existing"] = map[string]interface{}{"name": "existing", "version": "v1"}
 
-	// override present
-	if s, ok := typedServiceByName("existing"); !ok || s.Version != "v2" {
-		t.Errorf("expected existing override v2, got %+v ok=%v", s, ok)
+	reg := &MergedRegistry{
+		Services: []map[string]interface{}{
+			{"name": "existing", "version": "v2"},
+			{"name": "brand_new", "version": "v1"},
+		},
 	}
-	// new service added
-	if _, ok := typedServiceByName("brand_new"); !ok {
+	overlayMergedServices(reg)
+
+	// existing should be overridden
+	if v := mergedServices["existing"]["version"].(string); v != "v2" {
+		t.Errorf("expected existing to be overridden to v2, got %s", v)
+	}
+	// brand_new should be added
+	if _, ok := mergedServices["brand_new"]; !ok {
 		t.Error("expected brand_new to be added")
 	}
 }
 
-func TestRemoteOverlayDoesNotPolluteFollowingInit(t *testing.T) {
+func TestOverlayMergedServicesDoesNotPolluteFollowingInit(t *testing.T) {
 	resetInit()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
 
-	const leaked = "test_isolation_overlay_sentinel"
-	setRemoteOverrides([]metaschema.Service{{Name: leaked, Version: "v1"}})
+	const leakedExisting = "test_isolation_existing_sentinel"
+	const leakedOverlay = "test_isolation_overlay_sentinel"
+
+	mergedServices = map[string]map[string]interface{}{
+		leakedExisting: {"name": leakedExisting, "version": "v1"},
+	}
+	overlayMergedServices(&MergedRegistry{Services: []map[string]interface{}{{"name": leakedOverlay, "version": "v1"}}})
 
 	resetInit()
 	Init()
 
-	if spec := LoadFromMeta(leaked); spec != nil {
-		t.Fatalf("polluted service %q survived resetInit", leaked)
+	if spec := LoadFromMeta(leakedExisting); spec != nil {
+		t.Fatalf("polluted service %q survived resetInit", leakedExisting)
+	}
+	if spec := LoadFromMeta(leakedOverlay); spec != nil {
+		t.Fatalf("polluted service %q survived resetInit", leakedOverlay)
 	}
 }
 
@@ -406,8 +425,8 @@ func TestCorruptedCache_SelfHeals(t *testing.T) {
 	metaData, _ := json.Marshal(meta)
 	os.WriteFile(filepath.Join(cDir, "remote_meta.meta.json"), metaData, 0644)
 
-	// loadCachedTyped should fail and remove the corrupted files
-	err := loadCachedTyped()
+	// loadCachedMerged should fail and remove the corrupted files
+	_, err := loadCachedMerged()
 	if err == nil {
 		t.Fatal("expected error for corrupted cache")
 	}

internal/registry/typed.go

@@ -1,579 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package registry
-
-import (
-	"encoding/json"
-	"sort"
-	"sync"
-
-	"github.com/larksuite/cli/internal/registry/metaschema"
-	"github.com/larksuite/cli/internal/registry/metastatic"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// This file is the typed registry layer for the static-meta migration.
-//
-//   - The embedded baseline is metastatic.Registry: static Go data laid out in
-//     the binary at compile time (zero startup cost). It is empty on a fresh
-//     checkout (stub.go) until the generated meta_data_gen.go is produced by
-//     `make fetch_meta`; no build tag is involved.
-//   - The remote overlay (~/.lark-cli/cache/remote_meta.json) is still fetched
-//     and refreshed at runtime, decoded into the same typed shape, and merged
-//     over the baseline as per-service overrides.
-//
-// Startup (command-tree build) reads these typed structs directly. Execution-
-// path consumers that still expect map[string]interface{} go through
-// ServiceToMap, which rebuilds one service's map lazily, on demand — never the
-// whole spec at startup.
-
-var (
-	typedMu         sync.RWMutex
-	remoteOverrides map[string]metaschema.Service // service name -> remote override
-	typedNamesCache []string
-)
-
-// resetTyped clears the typed overlay state (test/teardown helper).
-func resetTyped() {
-	typedMu.Lock()
-	defer typedMu.Unlock()
-	remoteOverrides = nil
-	typedNamesCache = nil
-}
-
-// baselineServices returns the embedded baseline service specs: the static
-// compile-time data in metastatic.Registry (zero parse, zero alloc). It is
-// empty only on a fresh checkout where meta_data_gen.go has not been generated
-// yet (see stub.go).
-var (
-	baselineOnce sync.Once
-	baselineSvcs []metaschema.Service
-	baselineVer  string
-)
-
-func loadBaseline() {
-	baselineOnce.Do(func() {
-		baselineSvcs = metastatic.Registry.Services
-		baselineVer = metastatic.Registry.Version
-	})
-}
-
-func baselineServices() []metaschema.Service {
-	loadBaseline()
-	return baselineSvcs
-}
-
-func baselineVersion() string {
-	loadBaseline()
-	return baselineVer
-}
-
-// baselineServiceByName returns the embedded baseline service spec by name.
-func baselineServiceByName(name string) (metaschema.Service, bool) {
-	svcs := baselineServices()
-	for i := range svcs {
-		if svcs[i].Name == name {
-			return svcs[i], true
-		}
-	}
-	return metaschema.Service{}, false
-}
-
-// typedServiceByName returns the effective typed spec for a service: the remote
-// override if present, otherwise the static baseline.
-func typedServiceByName(name string) (metaschema.Service, bool) {
-	typedMu.RLock()
-	if s, ok := remoteOverrides[name]; ok {
-		typedMu.RUnlock()
-		return s, true
-	}
-	typedMu.RUnlock()
-	return baselineServiceByName(name)
-}
-
-// typedServiceNames returns all effective service names (baseline + remote
-// additions), sorted. Cached until the overlay changes.
-func typedServiceNames() []string {
-	typedMu.RLock()
-	if typedNamesCache != nil {
-		out := typedNamesCache
-		typedMu.RUnlock()
-		return out
-	}
-	typedMu.RUnlock()
-
-	seen := make(map[string]bool)
-	for _, s := range baselineServices() {
-		seen[s.Name] = true
-	}
-	typedMu.RLock()
-	for name := range remoteOverrides {
-		seen[name] = true
-	}
-	typedMu.RUnlock()
-
-	names := make([]string, 0, len(seen))
-	for n := range seen {
-		names = append(names, n)
-	}
-	sort.Strings(names)
-
-	typedMu.Lock()
-	typedNamesCache = names
-	typedMu.Unlock()
-	return names
-}
-
-// setRemoteOverrides installs the parsed remote overlay (called from Init).
-func setRemoteOverrides(svcs []metaschema.Service) {
-	typedMu.Lock()
-	defer typedMu.Unlock()
-	if remoteOverrides == nil {
-		remoteOverrides = make(map[string]metaschema.Service, len(svcs))
-	}
-	for _, s := range svcs {
-		remoteOverrides[s.Name] = s
-	}
-	typedNamesCache = nil
-}
-
-// TypedService returns the effective typed spec for a service (remote override
-// or static baseline). Public accessor for the command-tree builder.
-func TypedService(name string) (metaschema.Service, bool) {
-	Init()
-	return typedServiceByName(name)
-}
-
-// TypedServices returns all effective service specs, sorted by name. Reading
-// these builds nothing on the heap (static data); the remote overlay, if any,
-// was allocated once at Init.
-func TypedServices() []metaschema.Service {
-	Init()
-	names := typedServiceNames()
-	out := make([]metaschema.Service, 0, len(names))
-	for _, n := range names {
-		if s, ok := typedServiceByName(n); ok {
-			out = append(out, s)
-		}
-	}
-	return out
-}
-
-// hasTypedData reports whether any typed spec is available (static baseline or
-// remote overlay). False only when the static registry has not been generated
-// (fresh checkout) and there is no cache.
-func hasTypedData() bool {
-	if len(baselineServices()) > 0 {
-		return true
-	}
-	typedMu.RLock()
-	defer typedMu.RUnlock()
-	return len(remoteOverrides) > 0
-}
-
-// loadCachedTyped reads the on-disk remote cache, decodes it into the typed
-// shape, and installs it as the remote overlay (typed replacement for the old
-// map-based loadCachedMerged + overlay).
-func loadCachedTyped() error {
-	data, err := vfs.ReadFile(cachePath())
-	if err != nil {
-		return err
-	}
-	var reg wireRegistry
-	if err := json.Unmarshal(data, &reg); err != nil {
-		// Cache corrupted — remove it so the next run triggers a fresh fetch.
-		_ = vfs.Remove(cachePath())
-		_ = vfs.Remove(cacheMetaPath())
-		return err
-	}
-	svcs := make([]metaschema.Service, 0, len(reg.Services))
-	for _, ws := range reg.Services {
-		svcs = append(svcs, wireToService(ws))
-	}
-	setRemoteOverrides(svcs)
-	return nil
-}
-
-// --- typed -> map[string]interface{} shim (lazy, per service, execution-path) ---
-
-func strList(ss []string) []interface{} {
-	if len(ss) == 0 {
-		return nil
-	}
-	out := make([]interface{}, len(ss))
-	for i, s := range ss {
-		out[i] = s
-	}
-	return out
-}
-
-func fieldToMap(f metaschema.Field) map[string]interface{} {
-	m := map[string]interface{}{}
-	put := func(k, v string) {
-		if v != "" {
-			m[k] = v
-		}
-	}
-	put("type", f.Type)
-	put("location", f.Location)
-	put("description", f.Description)
-	put("default", f.Default)
-	put("example", f.Example)
-	put("enumName", f.EnumName)
-	put("min", f.Min)
-	put("max", f.Max)
-	put("ref", f.Ref)
-	if f.Required {
-		m["required"] = true
-	}
-	if v := strList(f.Enum); v != nil {
-		m["enum"] = v
-	}
-	if v := strList(f.Annotations); v != nil {
-		m["annotations"] = v
-	}
-	if len(f.Options) > 0 {
-		opts := make([]interface{}, len(f.Options))
-		for i, o := range f.Options {
-			opts[i] = map[string]interface{}{"value": o.Value, "description": o.Description}
-		}
-		m["options"] = opts
-	}
-	if len(f.Properties) > 0 {
-		m["properties"] = fieldsToMap(f.Properties)
-	}
-	return m
-}
-
-func fieldsToMap(fs []metaschema.Field) map[string]interface{} {
-	if len(fs) == 0 {
-		return nil
-	}
-	m := make(map[string]interface{}, len(fs))
-	for _, f := range fs {
-		m[f.Name] = fieldToMap(f)
-	}
-	return m
-}
-
-// affordanceToMap rebuilds the JSON-shaped affordance object (snake_case keys)
-// so the schema assembler's parseAffordance(method["affordance"]) keeps working
-// through the typed registry. Returns nil when the overlay carries nothing.
-func affordanceToMap(a *metaschema.Affordance) map[string]interface{} {
-	m := map[string]interface{}{}
-	if v := strList(a.UseWhen); v != nil {
-		m["use_when"] = v
-	}
-	if v := strList(a.DoNotUseWhen); v != nil {
-		m["do_not_use_when"] = v
-	}
-	if v := strList(a.Prerequisites); v != nil {
-		m["prerequisites"] = v
-	}
-	if len(a.Examples) > 0 {
-		ex := make([]interface{}, len(a.Examples))
-		for i, e := range a.Examples {
-			ex[i] = map[string]interface{}{"description": e.Description, "command": e.Command}
-		}
-		m["examples"] = ex
-	}
-	if v := strList(a.Related); v != nil {
-		m["related"] = v
-	}
-	if len(m) == 0 {
-		return nil
-	}
-	return m
-}
-
-func MethodToMap(mth metaschema.Method) map[string]interface{} {
-	m := map[string]interface{}{
-		"id":          mth.ID,
-		"path":        mth.Path,
-		"httpMethod":  mth.HTTPMethod,
-		"description": mth.Description,
-	}
-	if mth.Risk != "" {
-		m["risk"] = mth.Risk
-	}
-	if mth.DocURL != "" {
-		m["docUrl"] = mth.DocURL
-	}
-	if mth.Danger {
-		m["danger"] = true
-	}
-	if v := strList(mth.Scopes); v != nil {
-		m["scopes"] = v
-	}
-	if v := strList(mth.AccessTokens); v != nil {
-		m["accessTokens"] = v
-	}
-	if v := strList(mth.ParameterOrder); v != nil {
-		m["parameterOrder"] = v
-	}
-	if v := strList(mth.RequiredScopes); v != nil {
-		m["requiredScopes"] = v
-	}
-	if v := fieldsToMap(mth.Parameters); v != nil {
-		m["parameters"] = v
-	}
-	if v := fieldsToMap(mth.RequestBody); v != nil {
-		m["requestBody"] = v
-	}
-	if v := fieldsToMap(mth.ResponseBody); v != nil {
-		m["responseBody"] = v
-	}
-	if mth.Affordance != nil {
-		if am := affordanceToMap(mth.Affordance); am != nil {
-			m["affordance"] = am
-		}
-	}
-	return m
-}
-
-// ServiceToMap rebuilds the JSON-shaped map[string]interface{} for one service,
-// so execution-path consumers (and method RunE) keep working unchanged.
-func ServiceToMap(s metaschema.Service) map[string]interface{} {
-	resources := make(map[string]interface{}, len(s.Resources))
-	for _, r := range s.Resources {
-		methods := make(map[string]interface{}, len(r.Methods))
-		for _, mth := range r.Methods {
-			methods[mth.Name] = MethodToMap(mth)
-		}
-		resources[r.Name] = map[string]interface{}{"methods": methods}
-	}
-	return map[string]interface{}{
-		"name":        s.Name,
-		"version":     s.Version,
-		"title":       s.Title,
-		"description": s.Description,
-		"servicePath": s.ServicePath,
-		"resources":   resources,
-	}
-}
-
-// --- map[string]interface{} -> typed (for the map-based wrappers still used by
-// tests; production builds from typed directly) ---
-
-func ifaceStrs(v interface{}) []string {
-	raw, _ := v.([]interface{})
-	if len(raw) == 0 {
-		return nil
-	}
-	out := make([]string, 0, len(raw))
-	for _, e := range raw {
-		if s, ok := e.(string); ok {
-			out = append(out, s)
-		}
-	}
-	return out
-}
-
-func sortedMapKeys(m map[string]interface{}) []string {
-	ks := make([]string, 0, len(m))
-	for k := range m {
-		ks = append(ks, k)
-	}
-	sort.Strings(ks)
-	return ks
-}
-
-func mapToField(name string, m map[string]interface{}) metaschema.Field {
-	f := metaschema.Field{
-		Name: name, Type: GetStrFromMap(m, "type"), Location: GetStrFromMap(m, "location"),
-		Description: GetStrFromMap(m, "description"), Default: GetStrFromMap(m, "default"),
-		Example: GetStrFromMap(m, "example"), EnumName: GetStrFromMap(m, "enumName"),
-		Min: GetStrFromMap(m, "min"), Max: GetStrFromMap(m, "max"), Ref: GetStrFromMap(m, "ref"),
-		Enum: ifaceStrs(m["enum"]), Annotations: ifaceStrs(m["annotations"]),
-	}
-	if b, ok := m["required"].(bool); ok {
-		f.Required = b
-	}
-	if opts, ok := m["options"].([]interface{}); ok {
-		for _, o := range opts {
-			om, _ := o.(map[string]interface{})
-			f.Options = append(f.Options, metaschema.Option{Value: GetStrFromMap(om, "value"), Description: GetStrFromMap(om, "description")})
-		}
-	}
-	f.Properties = mapToFields(m["properties"])
-	return f
-}
-
-func mapToFields(v interface{}) []metaschema.Field {
-	fm, _ := v.(map[string]interface{})
-	if len(fm) == 0 {
-		return nil
-	}
-	out := make([]metaschema.Field, 0, len(fm))
-	for _, k := range sortedMapKeys(fm) {
-		em, _ := fm[k].(map[string]interface{})
-		out = append(out, mapToField(k, em))
-	}
-	return out
-}
-
-func MapToMethod(name string, m map[string]interface{}) metaschema.Method {
-	return metaschema.Method{
-		Name: name, ID: GetStrFromMap(m, "id"), Path: GetStrFromMap(m, "path"),
-		HTTPMethod: GetStrFromMap(m, "httpMethod"), Description: GetStrFromMap(m, "description"),
-		Risk: GetStrFromMap(m, "risk"), DocURL: GetStrFromMap(m, "docUrl"),
-		Danger:         boolFromMap(m, "danger"),
-		Scopes:         ifaceStrs(m["scopes"]),
-		AccessTokens:   ifaceStrs(m["accessTokens"]),
-		ParameterOrder: ifaceStrs(m["parameterOrder"]),
-		RequiredScopes: ifaceStrs(m["requiredScopes"]),
-		Parameters:     mapToFields(m["parameters"]),
-		RequestBody:    mapToFields(m["requestBody"]),
-		ResponseBody:   mapToFields(m["responseBody"]),
-	}
-}
-
-func boolFromMap(m map[string]interface{}, k string) bool {
-	b, _ := m[k].(bool)
-	return b
-}
-
-func MapToResources(v interface{}) []metaschema.Resource {
-	rm, _ := v.(map[string]interface{})
-	if len(rm) == 0 {
-		return nil
-	}
-	out := make([]metaschema.Resource, 0, len(rm))
-	for _, rk := range sortedMapKeys(rm) {
-		res, _ := rm[rk].(map[string]interface{})
-		mm, _ := res["methods"].(map[string]interface{})
-		methods := make([]metaschema.Method, 0, len(mm))
-		for _, mk := range sortedMapKeys(mm) {
-			methodMap, _ := mm[mk].(map[string]interface{})
-			methods = append(methods, MapToMethod(mk, methodMap))
-		}
-		out = append(out, metaschema.Resource{Name: rk, Methods: methods})
-	}
-	return out
-}
-
-// MapToService converts a JSON-shaped service spec (with embedded "resources")
-// into the typed form.
-func MapToService(spec map[string]interface{}) metaschema.Service {
-	return metaschema.Service{
-		Name: GetStrFromMap(spec, "name"), Version: GetStrFromMap(spec, "version"),
-		Title: GetStrFromMap(spec, "title"), Description: GetStrFromMap(spec, "description"),
-		ServicePath: GetStrFromMap(spec, "servicePath"), Resources: MapToResources(spec["resources"]),
-	}
-}
-
-// --- remote JSON (wire) -> typed ---
-
-type wireRegistry struct {
-	Version  string        `json:"version"`
-	Services []wireService `json:"services"`
-}
-
-type wireService struct {
-	Name        string                  `json:"name"`
-	Version     string                  `json:"version"`
-	Title       string                  `json:"title"`
-	Description string                  `json:"description"`
-	ServicePath string                  `json:"servicePath"`
-	Resources   map[string]wireResource `json:"resources"`
-}
-
-type wireResource struct {
-	Methods map[string]wireMethod `json:"methods"`
-}
-
-type wireMethod struct {
-	ID             string               `json:"id"`
-	Path           string               `json:"path"`
-	HTTPMethod     string               `json:"httpMethod"`
-	Description    string               `json:"description"`
-	Risk           string               `json:"risk"`
-	DocURL         string               `json:"docUrl"`
-	Danger         bool                 `json:"danger"`
-	Scopes         []string             `json:"scopes"`
-	AccessTokens   []string             `json:"accessTokens"`
-	ParameterOrder []string             `json:"parameterOrder"`
-	RequiredScopes []string             `json:"requiredScopes"`
-	Parameters     map[string]wireField `json:"parameters"`
-	RequestBody    map[string]wireField `json:"requestBody"`
-	ResponseBody   map[string]wireField `json:"responseBody"`
-}
-
-type wireField struct {
-	Type        string               `json:"type"`
-	Location    string               `json:"location"`
-	Description string               `json:"description"`
-	Default     string               `json:"default"`
-	Example     string               `json:"example"`
-	EnumName    string               `json:"enumName"`
-	Min         string               `json:"min"`
-	Max         string               `json:"max"`
-	Ref         string               `json:"ref"`
-	Required    bool                 `json:"required"`
-	Options     []metaschema.Option  `json:"options"`
-	Enum        []string             `json:"enum"`
-	Annotations []string             `json:"annotations"`
-	Properties  map[string]wireField `json:"properties"`
-}
-
-func sortedFieldKeys(m map[string]wireField) []string {
-	ks := make([]string, 0, len(m))
-	for k := range m {
-		ks = append(ks, k)
-	}
-	sort.Strings(ks)
-	return ks
-}
-
-func wireFields(m map[string]wireField) []metaschema.Field {
-	if len(m) == 0 {
-		return nil
-	}
-	out := make([]metaschema.Field, 0, len(m))
-	for _, name := range sortedFieldKeys(m) {
-		wf := m[name]
-		out = append(out, metaschema.Field{
-			Name: name, Type: wf.Type, Location: wf.Location, Description: wf.Description,
-			Default: wf.Default, Example: wf.Example, EnumName: wf.EnumName,
-			Min: wf.Min, Max: wf.Max, Ref: wf.Ref, Required: wf.Required,
-			Options: wf.Options, Enum: wf.Enum, Annotations: wf.Annotations,
-			Properties: wireFields(wf.Properties),
-		})
-	}
-	return out
-}
-
-func wireToService(ws wireService) metaschema.Service {
-	resKeys := make([]string, 0, len(ws.Resources))
-	for k := range ws.Resources {
-		resKeys = append(resKeys, k)
-	}
-	sort.Strings(resKeys)
-	resources := make([]metaschema.Resource, 0, len(resKeys))
-	for _, rk := range resKeys {
-		wr := ws.Resources[rk]
-		methKeys := make([]string, 0, len(wr.Methods))
-		for k := range wr.Methods {
-			methKeys = append(methKeys, k)
-		}
-		sort.Strings(methKeys)
-		methods := make([]metaschema.Method, 0, len(methKeys))
-		for _, mk := range methKeys {
-			wm := wr.Methods[mk]
-			methods = append(methods, metaschema.Method{
-				Name: mk, ID: wm.ID, Path: wm.Path, HTTPMethod: wm.HTTPMethod,
-				Description: wm.Description, Risk: wm.Risk, DocURL: wm.DocURL, Danger: wm.Danger,
-				Scopes: wm.Scopes, AccessTokens: wm.AccessTokens,
-				ParameterOrder: wm.ParameterOrder, RequiredScopes: wm.RequiredScopes,
-				Parameters: wireFields(wm.Parameters), RequestBody: wireFields(wm.RequestBody),
-				ResponseBody: wireFields(wm.ResponseBody),
-			})
-		}
-		resources = append(resources, metaschema.Resource{Name: rk, Methods: methods})
-	}
-	return metaschema.Service{
-		Name: ws.Name, Version: ws.Version, Title: ws.Title,
-		Description: ws.Description, ServicePath: ws.ServicePath, Resources: resources,
-	}
-}

internal/schema/assembler.go

@@ -4,14 +4,290 @@
 package schema
 
 import (
+	"bytes"
 	"encoding/json"
 	"sort"
 	"strconv"
+	"sync"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/registry"
 )
 
+// MethodKeyOrder records the natural meta_data.json key order for one method's
+// parameters / requestBody / responseBody. Nested object key orders are stored
+// under NestedKeys, keyed by dotted path from the method root
+// (e.g. "responseBody.items.properties").
+type MethodKeyOrder struct {
+	Parameters   []string
+	RequestBody  []string
+	ResponseBody []string
+	NestedKeys   map[string][]string
+}
+
+var (
+	keyOrderIndex    map[string]*MethodKeyOrder // dottedPath -> order
+	keyOrderInitOnce sync.Once
+)
+
+// lookupKeyOrder returns the key-order record for service.resourcePath.method,
+// or nil if the method is not in the embedded data (e.g. remote-cached).
+func lookupKeyOrder(service string, resourcePath []string, method string) *MethodKeyOrder {
+	keyOrderInitOnce.Do(buildKeyOrderIndex)
+	if keyOrderIndex == nil {
+		return nil
+	}
+	dotted := dottedPath(service, resourcePath, method)
+	return keyOrderIndex[dotted]
+}
+
+func dottedPath(service string, resourcePath []string, method string) string {
+	var buf bytes.Buffer
+	buf.WriteString(service)
+	for _, r := range resourcePath {
+		buf.WriteByte('.')
+		buf.WriteString(r)
+	}
+	buf.WriteByte('.')
+	buf.WriteString(method)
+	return buf.String()
+}
+
+// buildKeyOrderIndex parses the embedded meta_data.json bytes once at init,
+// walking services -> resources -> methods -> {parameters,requestBody,responseBody}
+// and recording each map's key insertion order via json.Decoder.Token().
+func buildKeyOrderIndex() {
+	raw := registry.EmbeddedMetaJSON()
+	if len(raw) == 0 {
+		return
+	}
+	keyOrderIndex = make(map[string]*MethodKeyOrder)
+
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	// Top-level: { "services": [...], "version": "..." }
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		if key != "services" {
+			skipValue(dec)
+			continue
+		}
+		if !expectDelim(dec, '[') {
+			return
+		}
+		for dec.More() {
+			parseService(dec)
+		}
+		// closing ]
+		_, _ = dec.Token()
+	}
+}
+
+// parseService consumes one service object inside services[].
+// meta_data.json may emit "resources" before "name", so we first capture both
+// raw fields, then walk resources with the resolved service name.
+func parseService(dec *json.Decoder) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	var serviceName string
+	var resourcesRaw json.RawMessage
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "name":
+			tok, _ := dec.Token()
+			if s, ok := tok.(string); ok {
+				serviceName = s
+			}
+		case "resources":
+			if err := dec.Decode(&resourcesRaw); err != nil {
+				skipValue(dec)
+			}
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token() // closing }
+	if serviceName != "" && len(resourcesRaw) > 0 {
+		subDec := json.NewDecoder(bytes.NewReader(resourcesRaw))
+		parseResources(subDec, serviceName, nil)
+	}
+}
+
+// parseResources walks a resources map (resName -> resource object).
+// resourcePath is the accumulated path of parent resources (for nested resources).
+func parseResources(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		resName, _ := readKey(dec)
+		parseResourceObj(dec, service, append(resourcePath, resName))
+	}
+	_, _ = dec.Token()
+}
+
+// parseResourceObj consumes one resource value: { methods: {...}, ... } and may
+// recurse into nested resources via "resources" key if present.
+func parseResourceObj(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "methods":
+			parseMethods(dec, service, resourcePath)
+		case "resources":
+			parseResources(dec, service, resourcePath)
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+}
+
+// parseMethods consumes the methods map (methodName -> method object).
+func parseMethods(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		methodName, _ := readKey(dec)
+		mko := parseMethod(dec)
+		dotted := dottedPath(service, resourcePath, methodName)
+		keyOrderIndex[dotted] = mko
+	}
+	_, _ = dec.Token()
+}
+
+// parseMethod consumes one method object and records key orders.
+func parseMethod(dec *json.Decoder) *MethodKeyOrder {
+	mko := &MethodKeyOrder{NestedKeys: make(map[string][]string)}
+	if !expectDelim(dec, '{') {
+		return mko
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "parameters":
+			mko.Parameters = recordObjectKeysRecursive(dec, "parameters", mko.NestedKeys)
+		case "requestBody":
+			mko.RequestBody = recordObjectKeysRecursive(dec, "requestBody", mko.NestedKeys)
+		case "responseBody":
+			mko.ResponseBody = recordObjectKeysRecursive(dec, "responseBody", mko.NestedKeys)
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+	return mko
+}
+
+// recordObjectKeysRecursive consumes an object and records the top-level key
+// order. It also recurses into each child's "properties" submap, recording
+// nested orders under prefix.subpath in nestedKeys. Returns the top-level keys
+// in order.
+func recordObjectKeysRecursive(dec *json.Decoder, prefix string, nestedKeys map[string][]string) []string {
+	if !expectDelim(dec, '{') {
+		return nil
+	}
+	var order []string
+	for dec.More() {
+		key, _ := readKey(dec)
+		order = append(order, key)
+		// Each child value is itself an object; we want its nested "properties" order if present.
+		consumeFieldRecursive(dec, prefix+"."+key, nestedKeys)
+	}
+	_, _ = dec.Token()
+	if prefix != "" && len(order) > 0 {
+		nestedKeys[prefix] = order
+	}
+	return order
+}
+
+// consumeFieldRecursive consumes a field object (e.g. one parameter spec) and,
+// if it contains "properties": {...}, recursively records that submap's order.
+func consumeFieldRecursive(dec *json.Decoder, path string, nestedKeys map[string][]string) {
+	tok, err := dec.Token()
+	if err != nil {
+		return
+	}
+	delim, ok := tok.(json.Delim)
+	if !ok || delim != '{' {
+		// Not an object — skip the rest of the value
+		skipValueAfterToken(dec, tok)
+		return
+	}
+	for dec.More() {
+		fieldKey, _ := readKey(dec)
+		if fieldKey == "properties" {
+			recordObjectKeysRecursive(dec, path+".properties", nestedKeys)
+		} else {
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+}
+
+// --- json.Decoder helpers ---
+
+func expectDelim(dec *json.Decoder, want json.Delim) bool {
+	tok, err := dec.Token()
+	if err != nil {
+		return false
+	}
+	delim, ok := tok.(json.Delim)
+	return ok && delim == want
+}
+
+func readKey(dec *json.Decoder) (string, error) {
+	tok, err := dec.Token()
+	if err != nil {
+		return "", err
+	}
+	s, _ := tok.(string)
+	return s, nil
+}
+
+// skipValue consumes the next complete value (scalar, object, or array).
+func skipValue(dec *json.Decoder) {
+	tok, err := dec.Token()
+	if err != nil {
+		return
+	}
+	skipValueAfterToken(dec, tok)
+}
+
+func skipValueAfterToken(dec *json.Decoder, tok json.Token) {
+	delim, ok := tok.(json.Delim)
+	if !ok {
+		return
+	}
+	// We started inside a container of type `delim` ({ or [) and must eat
+	// tokens until that container closes, tracking nested containers of any
+	// kind. depth counts how many open containers we are currently inside.
+	_ = delim
+	depth := 1
+	for depth > 0 {
+		t, err := dec.Token()
+		if err != nil {
+			return
+		}
+		if d, ok := t.(json.Delim); ok {
+			switch d {
+			case '{', '[':
+				depth++
+			case '}', ']':
+				depth--
+			}
+		}
+	}
+}
+
 // coerceLiteral converts a meta_data literal (default / enum / example) to
 // the JSON Schema type declared by the field (integer/number/boolean/string).
 // meta_data stores every literal as a string, so without coercion an
@@ -225,6 +501,10 @@ func buildOrderedProps(raw map[string]interface{}, nestedPath string) (*OrderedP
 	return op, required
 }
 
+// currentMethodOrder is the per-method key-order context used by orderedKeys.
+// It is set inside AssembleEnvelope (under assembleMu) and reset on return.
+var currentMethodOrder *MethodKeyOrder
+
 // parseAffordance lifts the affordance overlay from a method's raw meta_data.json
 // entry into a typed *Affordance. Returns nil when the field is absent, malformed,
 // or carries no populated subfields.
@@ -331,6 +611,8 @@ func buildMeta(method map[string]interface{}) *Meta {
 // The params / data wrapping mirrors the CLI's actual flag layout:
 // path+query → --params JSON, body → --data JSON, file → --file. AI consumers
 // can pluck inputSchema.properties.params and pass it verbatim to --params.
+//
+// Caller must set currentMethodOrder for property-order preservation.
 func buildInputSchema(method map[string]interface{}) *InputSchema {
 	is := &InputSchema{
 		Type:       "object",
@@ -456,11 +738,27 @@ func buildOutputSchema(method map[string]interface{}) *OutputSchema {
 	return os
 }
 
+// assembleMu serializes AssembleEnvelope calls so that the package-level
+// currentMethodOrder pointer is safe for concurrent callers.
+var assembleMu sync.Mutex
+
 // AssembleEnvelope is the main entry point: takes a service / resource path /
 // method name plus its meta_data spec, and produces a fully assembled MCP
 // envelope. Output is fully determined by inputs (same arguments → same
-// envelope).
+// envelope), but assembly briefly publishes the per-method key-order context
+// through the package-level currentMethodOrder so orderedKeys can reach it
+// without threading it through every helper. assembleMu serializes that
+// publish, which is why concurrent callers are still safe — they queue
+// rather than run in parallel.
+//
+// If parallelism becomes a bottleneck, replace currentMethodOrder with an
+// assembler struct or pass *MethodKeyOrder explicitly down the call chain.
 func AssembleEnvelope(serviceName string, resourcePath []string, methodName string, method map[string]interface{}) Envelope {
+	assembleMu.Lock()
+	defer assembleMu.Unlock()
+	currentMethodOrder = lookupKeyOrder(serviceName, resourcePath, methodName)
+	defer func() { currentMethodOrder = nil }()
+
 	name := serviceName
 	for _, r := range resourcePath {
 		name += " " + r
@@ -538,10 +836,35 @@ func walkMethods(resources map[string]interface{}, parentPath []string,
 	}
 }
 
-// orderedKeys returns the keys of raw in alphabetical order. Field display
-// order is not preserved: the schema envelope is consumed as a JSON Schema (MCP
-// tool spec), where object property order carries no meaning.
-func orderedKeys(raw map[string]interface{}, _ string) []string {
+// orderedKeys returns the keys of raw in their meta_data natural order if
+// the current per-method key-order context has them recorded; otherwise
+// alphabetical fallback.
+func orderedKeys(raw map[string]interface{}, nestedPath string) []string {
+	if currentMethodOrder != nil && nestedPath != "" {
+		if order, ok := currentMethodOrder.NestedKeys[nestedPath]; ok {
+			// Filter to keys that actually exist in raw (defensive)
+			out := make([]string, 0, len(order))
+			seen := make(map[string]bool)
+			for _, k := range order {
+				if _, ok := raw[k]; ok {
+					out = append(out, k)
+					seen[k] = true
+				}
+			}
+			// Append any keys present in raw but missing from order (defensive),
+			// alphabetically for determinism.
+			var extra []string
+			for k := range raw {
+				if !seen[k] {
+					extra = append(extra, k)
+				}
+			}
+			sort.Strings(extra)
+			out = append(out, extra...)
+			return out
+		}
+	}
+	// Fallback: alphabetical
 	keys := make([]string, 0, len(raw))
 	for k := range raw {
 		keys = append(keys, k)

internal/schema/assembler_test.go

@@ -7,12 +7,10 @@ import (
 	"encoding/json"
 	"os"
 	"reflect"
-	"sort"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/internal/registry/metaschema"
 )
 
 // TestMain isolates registry-backed tests from any host ~/.lark-cli cache so
@@ -37,6 +35,58 @@ func TestMain(m *testing.M) {
 	os.Exit(code)
 }
 
+func TestKeyOrderIndex_ImReactionsList(t *testing.T) {
+	// We only assert key-set membership, not absolute order — the upstream
+	// meta_data API does not guarantee a stable JSON key sequence across
+	// fetches, so hard-coding the order makes CI flaky. Order preservation
+	// from input to output is tested separately in TestBuildInputSchema_*.
+	order := lookupKeyOrder("im", []string{"reactions"}, "list")
+	if order == nil {
+		t.Fatal("expected key order for im.reactions.list, got nil")
+	}
+	wantParams := map[string]bool{
+		"message_id": true, "reaction_type": true, "page_token": true,
+		"page_size": true, "user_id_type": true,
+	}
+	if got, want := len(order.Parameters), len(wantParams); got != want {
+		t.Errorf("parameters count = %d, want %d (got %v)", got, want, order.Parameters)
+	}
+	for _, k := range order.Parameters {
+		if !wantParams[k] {
+			t.Errorf("unexpected parameter key %q", k)
+		}
+	}
+	// im.reactions.list 是 GET，没有 requestBody
+	if len(order.RequestBody) != 0 {
+		t.Errorf("expected empty RequestBody, got %v", order.RequestBody)
+	}
+}
+
+func TestKeyOrderIndex_ImImagesCreate(t *testing.T) {
+	// Membership-only assertion; see comment on TestKeyOrderIndex_ImReactionsList.
+	order := lookupKeyOrder("im", []string{"images"}, "create")
+	if order == nil {
+		t.Fatal("expected key order for im.images.create, got nil")
+	}
+	wantBody := map[string]bool{"image_type": true, "image": true}
+	if got, want := len(order.RequestBody), len(wantBody); got != want {
+		t.Errorf("requestBody count = %d, want %d (got %v)", got, want, order.RequestBody)
+	}
+	for _, k := range order.RequestBody {
+		if !wantBody[k] {
+			t.Errorf("unexpected requestBody key %q", k)
+		}
+	}
+}
+
+func TestKeyOrderIndex_UnknownPath(t *testing.T) {
+	// 远端缓存的命令（不在 embedded 内）查不到 key order，返回 nil 走字母序兜底
+	order := lookupKeyOrder("nonexistent_service", []string{"foo"}, "bar")
+	if order != nil {
+		t.Errorf("expected nil for unknown path, got %+v", order)
+	}
+}
+
 func TestConvertProperty_BasicTypes(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -238,6 +288,9 @@ func TestConvertProperty_DescriptionDefaultExample(t *testing.T) {
 
 func TestBuildInputSchema_ReactionsList(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 
@@ -260,15 +313,16 @@ func TestBuildInputSchema_ReactionsList(t *testing.T) {
 	if !reflect.DeepEqual(params.Required, []string{"message_id"}) {
 		t.Errorf("params.Required = %v, want [message_id]", params.Required)
 	}
-	// Property order is alphabetical now: the envelope is a JSON Schema (MCP
-	// tool spec) where object property order carries no meaning.
-	if !sort.StringsAreSorted(params.Properties.Order) {
-		t.Errorf("params.properties order not alphabetical: %v", params.Properties.Order)
+	if !reflect.DeepEqual(params.Properties.Order, mko.Parameters) {
+		t.Errorf("params.properties order = %v, want (from key index) %v",
+			params.Properties.Order, mko.Parameters)
 	}
 }
 
 func TestBuildInputSchema_ImagesCreate_FileAndBody(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"images"}, "create")
+	currentMethodOrder = lookupKeyOrder("im", []string{"images"}, "create")
+	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 
@@ -328,6 +382,9 @@ func TestBuildInputSchema_HighRiskWriteInjectsYes(t *testing.T) {
 			},
 		},
 	}
+	currentMethodOrder = nil
+	defer func() { currentMethodOrder = nil }()
+
 	is := buildInputSchema(method)
 
 	// yes lives at inputSchema.properties.yes (sibling of params/data)
@@ -356,6 +413,9 @@ func TestBuildInputSchema_HighRiskWriteInjectsYes(t *testing.T) {
 
 func TestBuildInputSchema_NoYesForReadRisk(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
 
 	is := buildInputSchema(method)
 	if _, ok := is.Properties.Map["yes"]; ok {
@@ -365,6 +425,9 @@ func TestBuildInputSchema_NoYesForReadRisk(t *testing.T) {
 
 func TestBuildOutputSchema_ReactionsList(t *testing.T) {
 	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
 
 	os := buildOutputSchema(method)
 
@@ -550,45 +613,6 @@ func TestBuildMeta_AffordanceFromMethod(t *testing.T) {
 	}
 }
 
-// TestBuildMeta_AffordanceThroughTypedRegistry guards the static-registry path:
-// a method's affordance must survive metaschema.Method -> registry.MethodToMap
-// -> buildMeta, so `schema --format json` keeps emitting _meta.affordance after
-// the embedded-JSON-to-typed-registry migration. Without typed-side support the
-// overlay is silently stripped whenever meta_data.json carries affordance.
-func TestBuildMeta_AffordanceThroughTypedRegistry(t *testing.T) {
-	mth := metaschema.Method{
-		Name: "primary",
-		Affordance: &metaschema.Affordance{
-			UseWhen:       []string{"用户想拿到自己默认日历的 ID"},
-			DoNotUseWhen:  []string{"已经知道某个具体日历的 ID"},
-			Prerequisites: []string{"user 身份登录"},
-			Examples: []metaschema.AffordanceExample{
-				{Description: "取主日历", Command: "lark-cli calendar calendars primary"},
-			},
-			Related: []string{"calendars.list", "calendars.get"},
-		},
-	}
-	method := registry.MethodToMap(mth)
-	m := buildMeta(method)
-	if m.Affordance == nil {
-		t.Fatal("affordance dropped through the typed registry (MethodToMap -> buildMeta)")
-	}
-	a := m.Affordance
-	if len(a.UseWhen) != 1 || a.UseWhen[0] != "用户想拿到自己默认日历的 ID" {
-		t.Errorf("UseWhen = %v", a.UseWhen)
-	}
-	if len(a.DoNotUseWhen) != 1 || len(a.Prerequisites) != 1 {
-		t.Errorf("DoNotUseWhen=%v Prerequisites=%v", a.DoNotUseWhen, a.Prerequisites)
-	}
-	if len(a.Examples) != 1 || a.Examples[0].Description != "取主日历" ||
-		a.Examples[0].Command != "lark-cli calendar calendars primary" {
-		t.Errorf("Examples = %+v", a.Examples)
-	}
-	if len(a.Related) != 2 {
-		t.Errorf("Related = %v", a.Related)
-	}
-}
-
 func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
 	method := map[string]interface{}{
 		"scopes":       []interface{}{"x"},
@@ -610,6 +634,7 @@ func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
 func TestBuildOutputSchema_EmptyResponseBody(t *testing.T) {
 	// 装配器对空 responseBody 应生成 properties = {} （不 nil）
 	method := map[string]interface{}{}
+	currentMethodOrder = nil
 	os := buildOutputSchema(method)
 	if os.Type != "object" {
 		t.Errorf("Type = %q, want \"object\"", os.Type)

internal/schema/types.go

@@ -83,13 +83,9 @@ type AffordanceCase struct {
 	Command     string `json:"command"`
 }
 
-// OrderedProps is map[string]Property that emits its keys in Order on
-// MarshalJSON. Order is now populated alphabetically (see orderedKeys): the
-// schema envelope is an MCP tool spec / JSON Schema, where object property
-// order carries no meaning. The machinery that once preserved meta_data.json's
-// natural field order was removed with the static-registry migration; Order is
-// retained so MarshalJSON has one stable key sequence (and callers that leave
-// it empty fall back to alphabetical over Map).
+// OrderedProps is map[string]Property with preserved key order on MarshalJSON.
+// It is used wherever JSON output must reflect meta_data.json's natural field
+// order rather than Go's default alphabetical map encoding.
 type OrderedProps struct {
 	Order []string
 	Map   map[string]Property

scripts/build-pkg-pr-new.sh

@@ -6,7 +6,6 @@ OUT_DIR="$ROOT_DIR/.pkg-pr-new"
 
 cd "$ROOT_DIR"
 
-# fetch_meta.py also regenerates the static Go registry (meta_data_gen.go).
 python3 scripts/fetch_meta.py
 
 rm -rf "$OUT_DIR"

scripts/fetch_meta.py

@@ -63,19 +63,6 @@ def fetch_remote(brand):
     return data
 
 
-def run_gen():
-    """Regenerate the static Go registry (metastatic/meta_data_gen.go) from
-    meta_data.json. Run after every fetch so any caller that fetches also
-    produces the sole build-time source of the embedded command tree — no build
-    tag, no JSON embedded in the binary. Output is gitignored."""
-    print("fetch-meta: generating static Go registry (metastatic/meta_data_gen.go)", file=sys.stderr)
-    subprocess.run(
-        ["go", "run", "internal/registry/metastatic/gen.go"],
-        cwd=ROOT,
-        check=True,
-    )
-
-
 def main():
     parser = argparse.ArgumentParser(description="Fetch meta_data.json for build-time embedding")
     parser.add_argument("--brand", default="feishu", choices=["feishu", "lark"],
@@ -84,29 +71,27 @@ def main():
                         help="force refresh from remote even if local file exists")
     args = parser.parse_args()
 
-    have_valid = False
-    if os.path.isfile(OUT_PATH) and not args.force:
-        try:
-            with open(OUT_PATH, "r", encoding="utf-8") as fp:
-                local = json.load(fp)
-            have_valid = bool(local.get("services"))
-        except (OSError, json.JSONDecodeError):
-            have_valid = False
+    if os.path.exists(OUT_PATH) and not args.force:
+        if os.path.isfile(OUT_PATH):
+            try:
+                with open(OUT_PATH, "r", encoding="utf-8") as fp:
+                    local = json.load(fp)
+                if local.get("services"):
+                    print(f"fetch-meta: {OUT_PATH} already exists, skipping (use --force to re-fetch)", file=sys.stderr)
+                    return
+                print(f"fetch-meta: {OUT_PATH} has no services, re-fetching", file=sys.stderr)
+            except (OSError, json.JSONDecodeError):
+                print(f"fetch-meta: {OUT_PATH} is invalid JSON, re-fetching", file=sys.stderr)
+        else:
+            print(f"fetch-meta: {OUT_PATH} is not a file, re-fetching", file=sys.stderr)
 
-    if have_valid:
-        print(f"fetch-meta: {OUT_PATH} already exists, skipping fetch (use --force to re-fetch)", file=sys.stderr)
-    else:
-        data = fetch_remote(args.brand)
-        count = len(data.get("services", []))
-        print(f"fetch-meta: OK, {count} services from remote API", file=sys.stderr)
-        with open(OUT_PATH, "w") as fp:
-            json.dump(data, fp, ensure_ascii=False, indent=2)
-            fp.write("\n")
+    data = fetch_remote(args.brand)
+    count = len(data.get("services", []))
+    print(f"fetch-meta: OK, {count} services from remote API", file=sys.stderr)
 
-    # Always (re)generate the static Go registry so every fetch also produces
-    # the embedded command tree — the build-time replacement for the old
-    # embedded meta_data.json.
-    run_gen()
+    with open(OUT_PATH, "w") as fp:
+        json.dump(data, fp, ensure_ascii=False, indent=2)
+        fp.write("\n")
 
 
 if __name__ == "__main__":

shortcuts/register.go

@@ -97,13 +97,11 @@ func RegisterShortcuts(program *cobra.Command, f *cmdutil.Factory) {
 }
 
 func RegisterShortcutsWithContext(ctx context.Context, program *cobra.Command, f *cmdutil.Factory) {
-	// Brand only — never decrypt the app secret at registration time (avoids a
-	// keychain read on every invocation). ConfigBrand may be nil in tests that
-	// pass a zero-value factory.
+	// Factory.Config may be nil in tests that pass a zero-value factory.
 	var brand core.LarkBrand
-	if f != nil && f.ConfigBrand != nil {
-		if b, ok := f.ConfigBrand(); ok {
-			brand = b
+	if f != nil && f.Config != nil {
+		if cfg, err := f.Config(); err == nil && cfg != nil {
+			brand = cfg.Brand
 		}
 	}
 

shortcuts/register_brand_guard_test.go

@@ -20,10 +20,6 @@ func newFactoryWithBrand(brand core.LarkBrand) *cmdutil.Factory {
 		Config: func() (*core.CliConfig, error) {
 			return &core.CliConfig{Brand: brand}, nil
 		},
-		// Registration reads the brand via ConfigBrand (no secret decryption).
-		ConfigBrand: func() (core.LarkBrand, bool) {
-			return brand, true
-		},
 	}
 }