feat: support URL rewriting and manifest-based updates

cmd/build.go

@@ -374,6 +374,7 @@ func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext,
 	// mechanically unchanged.
 	var hasConcealedCommands bool
 	runtime.surface, hasConcealedCommands = applyDistributionPresentation(rootCmd, cfg.presentation, denied)
+	rootCmd.SetUsageTemplate(rewrittenRootUsageTemplate(runtime.surface))
 
 	// Resolve skill assets and canonical references before installing hooks.
 	// A declared customization is a build-integrity boundary: failure must

cmd/doctor/doctor.go

@@ -241,24 +241,24 @@
 	return nil
 }
 
-// checkCLIUpdate actively queries the npm registry for the latest version.
+// checkCLIUpdate actively queries the configured source for its target version.
 // Unlike the root-level async check, this does a synchronous fetch with timeout
 // and works regardless of build version (dev builds included).
 func checkCLIUpdate() []checkResult {
-	latest, err := fetchLatestForDoctor()
+	target, err := fetchLatestForDoctor()
 	if err != nil {
 		return []checkResult{warn("cli_update", "check failed: "+err.Error(), "")}
 	}
 	current := build.Version
-	if update.IsNewer(latest, current) {
+	if target.Available(current) {
 		return []checkResult{warn("cli_update",
-			fmt.Sprintf("%s → %s available", current, latest),
+			fmt.Sprintf("%s → %s available", current, target.Version),
 			"run: lark-cli update")}
 	}
-	return []checkResult{pass("cli_update", latest+" (up to date)")}
+	return []checkResult{pass("cli_update", target.Version+" (up to date)")}
 }
 
-var fetchLatestForDoctor = update.FetchLatest
+var fetchLatestForDoctor = update.FetchTarget
 
 func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 	allOK := true

cmd/doctor/doctor_test.go

@@ -7,20 +7,61 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
+	"net/http/httptest"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
 	extcred "github.com/larksuite/cli/extension/credential"
+	exttransport "github.com/larksuite/cli/extension/transport"
+	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/distribution"
 	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/surface"
+	"github.com/larksuite/cli/internal/update"
 )
 
+type doctorManifestProvider struct{ manifestURL string }
+
+func (doctorManifestProvider) Name() string { return "doctor-manifest-test" }
+func (doctorManifestProvider) ResolveInterceptor(context.Context) exttransport.Interceptor {
+	return nil
+}
+func (p doctorManifestProvider) ResolveManifestURL(context.Context) string {
+	return p.manifestURL
+}
+
+func TestCheckCLIUpdateReportsDifferentOpaqueManifestTarget(t *testing.T) {
+	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = fmt.Fprintf(w, `{"schema":1,"version":"older-channel","artifacts":{"skills":{"url":"https://distribution.example/skills.zip","checksum":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},%q:{"url":"https://distribution.example/cli.zip","checksum":"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}}`, distribution.CurrentPlatformKey())
+	}))
+	defer server.Close()
+	previousProvider := exttransport.GetProvider()
+	previousFetch := fetchLatestForDoctor
+	previousClient := distribution.DefaultClient
+	previousVersion := build.Version
+	exttransport.Register(doctorManifestProvider{manifestURL: server.URL})
+	distribution.DefaultClient = server.Client()
+	fetchLatestForDoctor = update.FetchTarget
+	build.Version = "newer-channel"
+	t.Cleanup(func() {
+		exttransport.Register(previousProvider)
+		fetchLatestForDoctor = previousFetch
+		distribution.DefaultClient = previousClient
+		build.Version = previousVersion
+	})
+	checks := checkCLIUpdate()
+	if len(checks) != 1 || checks[0].Status != "warn" || !strings.Contains(checks[0].Message, "older-channel") {
+		t.Fatalf("checks = %#v", checks)
+	}
+}
+
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -109,9 +150,9 @@ func TestDoctorRunDoesNotFetchUpdateWhenCommandIsConcealed(t *testing.T) {
 	t.Cleanup(func() { fetchLatestForDoctor = oldFetch })
 
 	fetches := 0
-	fetchLatestForDoctor = func() (string, error) {
+	fetchLatestForDoctor = func() (update.Target, error) {
 		fetches++
-		return "9.9.9", nil
+		return update.Target{Version: "9.9.9"}, nil
 	}
 	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
 		surface.CommandUpdate: surface.CommandConcealed,

cmd/event/console_url.go

@@ -12,6 +12,7 @@
 
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/urlrewrite"
 )
 
 // Landing-page contract for the scan-to-enable deep link, verified against the
@@ -73,13 +74,13 @@
 		return "", err
 	}
 	host := core.ResolveEndpoints(brand).Open
-	return fmt.Sprintf("%s%s?%s=%s&addons=%s", host, addonsLandingPath, addonsClientIDParam, appID, encoded), nil
+	return urlrewrite.Rewrite(fmt.Sprintf("%s%s?%s=%s&addons=%s", host, addonsLandingPath, addonsClientIDParam, appID, encoded)), nil
 }
 
 // consoleLandingURL is the bare landing page (no addons) — fallback when encoding fails.
 func consoleLandingURL(brand core.LarkBrand, appID string) string {
 	host := core.ResolveEndpoints(brand).Open
-	return fmt.Sprintf("%s%s?%s=%s", host, addonsLandingPath, addonsClientIDParam, appID)
+	return urlrewrite.Rewrite(fmt.Sprintf("%s%s?%s=%s", host, addonsLandingPath, addonsClientIDParam, appID))
 }
 
 // addonsHintURL returns the scan URL, degrading to the bare landing page on encode error.

cmd/root.go

@@ -21,6 +21,7 @@
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/deprecation"
+	"github.com/larksuite/cli/internal/distribution"
 	"github.com/larksuite/cli/internal/flagalias"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/output"
@@ -142,7 +143,13 @@
 var (
 	checkCachedUpdate     = update.CheckCached
 	refreshUpdateCache    = update.RefreshCache
-	initializeSkillsCheck = skillscheck.Init
+	initializeSkillsCheck = func(version string) {
+		sourceIdentity := skillscheck.OfficialSourceIdentity
+		if manifestURL, enabled, err := distribution.ResolveManifestURL(context.Background()); err == nil && enabled {
+			sourceIdentity = distribution.ManifestSourceIdentity(manifestURL)
+		}
+		skillscheck.InitForSource(version, sourceIdentity)
+	}
 )
 
 // setupNotices wires both the binary update notice and the skills

cmd/root_help.go

@@ -4,9 +4,11 @@
 package cmd
 
 import (
+	"fmt"
 	"strings"
 
 	"github.com/larksuite/cli/internal/surface"
+	"github.com/larksuite/cli/internal/urlrewrite"
 )
 
 // rootHelpFragment is one framework-owned root-help fragment. A fragment with
@@ -142,13 +144,24 @@ Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://
 var rootUsageTemplate = renderRootUsageTemplate(nil)
 
 func renderRootUsageTemplate(plan *surface.Plan) string {
+	return renderRootUsageTemplateWithSkillsURL(plan, "https://github.com/larksuite/cli#agent-skills")
+}
+
+func renderRootUsageTemplateWithSkillsURL(plan *surface.Plan, skillsURL string) string {
 	var b strings.Builder
 	b.WriteString(rootUsageTemplatePrefix)
 	b.WriteString(renderRootHelpFragments(rootUsageSynopsis, plan))
 	b.WriteString(rootUsageTemplateSuffix)
 	if plan.CanReference(surface.CommandSkillsRead) {
-		b.WriteString(skillsSetupFooter)
+		b.WriteString(fmt.Sprintf(`{{if not .HasParent}}
+
+Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — %s{{end}}`, skillsURL))
 	}
 	b.WriteByte('\n')
 	return b.String()
 }
+
+func rewrittenRootUsageTemplate(plan *surface.Plan) string {
+	return renderRootUsageTemplateWithSkillsURL(plan,
+		urlrewrite.Rewrite("https://github.com/larksuite/cli#agent-skills"))
+}

cmd/root_test.go

@@ -5,6 +5,7 @@ package cmd
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -28,6 +29,7 @@ import (
 	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/surface"
+	testurlrewrite "github.com/larksuite/cli/internal/testutil/urlrewrite"
 )
 
 // TestPersistentPreRunE_AuthCheckDisabledAnnotations verifies that
@@ -90,6 +92,17 @@ func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 	}
 }
 
+func TestBuildRewritesRootSkillsHelpURLAfterProviderRegistration(t *testing.T) {
+	testurlrewrite.Register(t, func(rawURL string) string {
+		return strings.Replace(rawURL, "github.com", "mirror.example.test", 1)
+	})
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t), WithoutPlugins())
+	if got := root.UsageTemplate(); !strings.Contains(got, "https://mirror.example.test/larksuite/cli#agent-skills") {
+		t.Fatalf("root help URL was not rewritten:\n%s", got)
+	}
+}
+
 func TestConfigureFlagCompletions(t *testing.T) {
 	t.Cleanup(func() { cmdutil.SetFlagCompletionsEnabled(false) })
 

cmd/update/manifest.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdupdate
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/distribution"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func runManifestUpdate(ctx context.Context, opts *UpdateOptions, manifestURL string) error {
+	streams := opts.Factory.IOStreams
+	current := currentVersion()
+	manifest, err := distribution.FetchManifest(ctx, manifestURL)
+	if err != nil {
+		return reportDistributionError(opts, err)
+	}
+	target := manifest.Version
+	if opts.Check {
+		return reportManifestStatus(opts, current, target, true)
+	}
+	if !opts.Force && target == current {
+		return reportManifestStatus(opts, current, target, false)
+	}
+	if !opts.JSON {
+		fmt.Fprintf(streams.ErrOut, "Updating lark-cli %s %s %s from the configured distribution ...\n", current, symArrow(), target)
+	}
+	if err := distribution.Install(ctx, manifest, distribution.InstallOptions{}); err != nil {
+		return reportDistributionError(opts, err)
+	}
+	if opts.JSON {
+		output.PrintJson(streams.Out, map[string]interface{}{
+			"ok": true, "source": "manifest",
+			"previous_version": current, "current_version": target, "target_version": target,
+			"action": "updated", "skills_action": "synced",
+			"message": fmt.Sprintf("lark-cli updated from %s to %s", current, target),
+		})
+		return nil
+	}
+	fmt.Fprintf(streams.ErrOut, "\n%s Successfully updated lark-cli and Skills from %s to %s\n", symOK(), current, target)
+	return nil
+}
+
+func reportManifestStatus(opts *UpdateOptions, current, target string, check bool) error {
+	streams := opts.Factory.IOStreams
+	action := "already_up_to_date"
+	message := fmt.Sprintf("lark-cli %s matches the configured target", current)
+	if current != target {
+		action = "update_available"
+		message = fmt.Sprintf("lark-cli %s %s configured target %s", current, symArrow(), target)
+	}
+	if opts.JSON {
+		result := map[string]interface{}{
+			"ok": true, "source": "manifest",
+			"previous_version": current, "current_version": current, "target_version": target,
+			"action": action, "message": message,
+		}
+		if check {
+			result["auto_update"] = true
+		}
+		output.PrintJson(streams.Out, result)
+		return nil
+	}
+	if current == target {
+		fmt.Fprintf(streams.ErrOut, "%s %s\n", symOK(), message)
+	} else {
+		fmt.Fprintf(streams.ErrOut, "Configured target: %s %s %s\n\nRun `lark-cli update` to install.\n", current, symArrow(), target)
+	}
+	return nil
+}
+
+func reportDistributionError(opts *UpdateOptions, typed errs.TypedError) error {
+	errType := "update_error"
+	if problem, ok := errs.ProblemOf(typed); ok && problem.Category == errs.CategoryNetwork {
+		errType = "network"
+	}
+	return reportError(opts, opts.Factory.IOStreams, errType, typed)
+}