chore: release v1.0.57 (#1553)

* fix: reject +init into a different app's project directory

* fix: reject single HTML files larger than 10MB in +html-publish

* docs: clarify publish visibility, domain routing, and role/permission boundary

.github/workflows/semantic-review.yml

@@ -47,10 +47,13 @@ jobs:
               throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
             }
             let prNumber = Number(runPRs[0]?.number || 0);
-            let eventBaseSha = runPRs[0]?.base?.sha || "";
+            const eventBaseSha = runPRs[0]?.base?.sha || "";
             const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = eventHeadSha || run.head_sha;
+            const targetHeadSha = run.head_sha;
             if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
+            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
+              core.notice("PR quality summary using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
+            }
 
             const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
             const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
@@ -71,11 +74,11 @@ jobs:
               if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
                 artifactError = "facts artifact head sha does not match verified PR head sha";
                 factsArtifactName = "";
-              } else if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                artifactError = "facts artifact base sha does not match workflow_run pull request base sha";
-                factsArtifactName = "";
               } else {
                 artifactBaseSha = parsedBaseSha;
+                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
+                  core.notice("PR quality summary using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
+                }
               }
             }
             if (!prNumber) {
@@ -123,7 +126,7 @@ jobs:
               core.setOutput("stale", "true");
               return;
             }
-            const baseSha = eventBaseSha || artifactBaseSha || pr.base.sha;
+            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
             if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
             if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
               core.notice("PR quality summary skipped: workflow_run is stale for this PR base");
@@ -255,10 +258,13 @@ jobs:
               throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
             }
             let prNumber = Number(runPRs[0]?.number || 0);
-            let eventBaseSha = runPRs[0]?.base?.sha || "";
+            const eventBaseSha = runPRs[0]?.base?.sha || "";
             const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = eventHeadSha || run.head_sha;
+            const targetHeadSha = run.head_sha;
             if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
+            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
+              core.notice("semantic review using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
+            }
 
             const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
             const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
@@ -279,11 +285,11 @@ jobs:
               if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
                 artifactError = "facts artifact head sha does not match verified PR head sha";
                 factsArtifactName = "";
-              } else if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                artifactError = "facts artifact base sha does not match workflow_run pull request base sha";
-                factsArtifactName = "";
               } else {
                 artifactBaseSha = parsedBaseSha;
+                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
+                  core.notice("semantic review using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
+                }
               }
             }
             if (!prNumber) {
@@ -331,7 +337,7 @@ jobs:
               core.setOutput("stale", "true");
               return;
             }
-            const baseSha = eventBaseSha || artifactBaseSha || pr.base.sha;
+            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
             if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
             if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
               core.notice("semantic review skipped: workflow_run is stale for this PR base");

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.57] - 2026-06-23
+
+### Features
+
+- **slides**: Add `+screenshot` to capture slide page images (or render a single `<slide>` XML snippet), returning the local file path instead of Base64 (#1358)
+- **base**: Support record comments (#1043)
+- **search**: Surface search API notices (#1413)
+
+### Bug Fixes
+
+- **mail**: Resolve folder/label filter once per `+triage list` call (#1512)
+- **meta**: Backfill enum value descriptions from options (#1541)
+- **cli**: Add missing CLI headers for git credential helper (#1539)
+
+### Documentation
+
+- **doc**: Refine rich block, path, and block ID guidance (#1508)
+- **mail**: Trim lark-mail skill context (#1527)
+- **drive**: Add permission governance workflow guidance (#1292)
+
+### Build
+
+- **ci**: Bind semantic review to workflow run head (#1551)
+
 ## [v1.0.56] - 2026-06-18
 
 ### Features
@@ -1212,6 +1236,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.57]: https://github.com/larksuite/cli/releases/tag/v1.0.57
 [v1.0.56]: https://github.com/larksuite/cli/releases/tag/v1.0.56
 [v1.0.55]: https://github.com/larksuite/cli/releases/tag/v1.0.55
 [v1.0.54]: https://github.com/larksuite/cli/releases/tag/v1.0.54

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

scripts/semantic-review-workflow.test.sh

@@ -179,7 +179,10 @@ fi
 require_in_step "$summary_verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "PR quality summary must verify the triggering workflow path"
 require_in_step "$summary_verify_step" 'run.event !== "pull_request"' "PR quality summary must only handle pull_request workflow_run events"
 require_in_step "$summary_verify_step" 'run.repository.id !== context.payload.repository.id' "PR quality summary must verify workflow_run repository id"
+require_in_step "$summary_verify_step" 'const targetHeadSha = run.head_sha' "PR quality summary must use the CI run head SHA as the verified PR head"
+require_in_step "$summary_verify_step" 'eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()' "PR quality summary should tolerate mutable workflow_run PR head metadata"
 require_in_step "$summary_verify_step" 'factsArtifactPattern' "PR quality summary should use the base-bound facts artifact name when available"
+require_in_step "$summary_verify_step" 'const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha' "PR quality summary must prefer the CI-time artifact base SHA"
 require_in_step "$summary_verify_step" 'core.setOutput("artifact_error"' "PR quality summary must expose artifact binding failures"
 require_in_step "$summary_artifact_step" 'factsArtifactName' "PR quality summary artifact step must use the verified facts artifact binding"
 require_in_step "$summary_extract_facts_step" 'SEMANTIC_REVIEW_DECISION_OUT' "PR quality summary artifact verifier must write an infrastructure decision on verifier failure"
@@ -198,8 +201,9 @@ require_in_step "$verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "se
 require_in_step "$verify_step" 'run.repository.id !== context.payload.repository.id' "semantic-review must verify workflow_run repository id"
 require_in_step "$verify_step" 'run.event !== "pull_request"' "semantic-review must only handle pull_request workflow_run events"
 require_in_step "$verify_step" 'run.conclusion !== "success"' "semantic-review must only consume successful CI runs"
-require_in_step "$verify_step" 'const eventHeadSha = runPRs[0]?.head?.sha || ""' "semantic-review must prefer workflow_run PR head when GitHub provides it"
-require_in_step "$verify_step" 'const targetHeadSha = eventHeadSha || run.head_sha' "semantic-review target PR head must come from the workflow_run event"
+require_in_step "$verify_step" 'const eventHeadSha = runPRs[0]?.head?.sha || ""' "semantic-review should inspect workflow_run PR head metadata"
+require_in_step "$verify_step" 'const targetHeadSha = run.head_sha' "semantic-review target PR head must come from the completed CI run"
+require_in_step "$verify_step" 'eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()' "semantic-review should tolerate mutable workflow_run PR head metadata"
 require_in_step "$verify_step" 'factsArtifactPattern' "semantic-review must use a base-bound facts artifact name"
 require_in_step "$verify_step" 'listWorkflowRunArtifacts' "semantic-review must read the workflow_run artifacts before resolving fallback base SHA"
 require_in_step "$verify_step" 'artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()' "semantic-review must not let the artifact choose a different PR head"
@@ -210,8 +214,8 @@ require_in_step "$verify_step" 'commit_sha: targetHeadSha' "semantic-review fall
 require_in_step "$verify_step" 'github.rest.pulls.list' "semantic-review must have a pull-list fallback when commit association is empty"
 require_in_step "$verify_step" 'candidatePRs.length > 1' "semantic-review must fail closed when commit-to-PR fallback is ambiguous"
 require_in_step "$verify_step" 'pr.head.sha !== targetHeadSha' "semantic-review must skip stale PR heads"
-require_in_step "$verify_step" 'eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()' "semantic-review must reject mismatched event and artifact base SHAs"
-require_in_step "$verify_step" 'const baseSha = eventBaseSha || artifactBaseSha' "semantic-review fallback must use the CI-time artifact base SHA"
+require_in_step "$verify_step" 'eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()' "semantic-review should tolerate mutable workflow_run PR base metadata"
+require_in_step "$verify_step" 'const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha' "semantic-review must prefer the CI-time artifact base SHA"
 require_in_step "$verify_step" 'pr.base.sha !== baseSha' "semantic-review must skip stale PR bases"
 require_in_step "$verify_step" 'core.setOutput("run_id"' "semantic-review must pass verified workflow run id to publisher"
 require_in_step "$verify_step" 'core.setOutput("head_repo_id"' "semantic-review must pass verified head repo id"

shortcuts/apps/apps_html_publish.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"path/filepath"
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
@@ -84,6 +85,9 @@ var AppsHTMLPublish = common.Shortcut{
 			// for dry-run "advisory preview" semantics).
 			dry.Set("validation_error", err.Error())
 		}
+		if hits := oversizeHTMLFiles(candidates); len(hits) > 0 {
+			dry.Set("oversize_html", hits)
+		}
 		dry.Set("file_count", len(candidates))
 		var totalSize int64
 		names := make([]string, 0, len(candidates))
@@ -140,18 +144,22 @@ type appsHTMLPublishSpec struct {
 // per-environment .env.* files for every stage).
 const maxSensitiveListInError = 5
 
+// truncatedJoin joins items with ", ", capping at max entries and appending
+// "(and N more)" for the remainder, so an inline error list stays readable when
+// a payload has many hits.
+func truncatedJoin(items []string, max int) string {
+	if len(items) <= max {
+		return strings.Join(items, ", ")
+	}
+	return strings.Join(items[:max], ", ") + fmt.Sprintf(" (and %d more)", len(items)-max)
+}
+
 // sensitiveCandidatesError builds the Validate-time rejection when --path
 // contains credential files and --allow-sensitive was not set.
 func sensitiveCandidatesError(hits []string) error {
-	var sample string
-	if len(hits) <= maxSensitiveListInError {
-		sample = strings.Join(hits, ", ")
-	} else {
-		sample = strings.Join(hits[:maxSensitiveListInError], ", ") +
-			fmt.Sprintf(" (and %d more)", len(hits)-maxSensitiveListInError)
-	}
 	return appsValidationParamError("--path",
-		"--path contains %d credential file(s) that should not be published: %s", len(hits), sample).
+		"--path contains %d credential file(s) that should not be published: %s",
+		len(hits), truncatedJoin(hits, maxSensitiveListInError)).
 		WithHint("remove these files from the publish payload, OR pass --allow-sensitive if shipping them is intentional (e.g. a docs site demoing credential-file formats)")
 }
 
@@ -168,6 +176,30 @@ var maxHTMLPublishTarballBytes int64 = 20 * 1024 * 1024
 // Mutable for tests.
 var maxHTMLPublishRawBytes int64 = 200 * 1024 * 1024
 
+// maxHTMLPublishSingleHTMLFileBytes 单个 .html 文件上限，对齐妙搭服务端 10MB 约束。
+// 用 var 而非 const，便于单测调小覆盖拦截路径。
+var maxHTMLPublishSingleHTMLFileBytes int64 = 10 * 1024 * 1024
+
+// oversizeHTMLFiles 返回 candidates 中扩展名为 .html（大小写不敏感）且单个 Size 超过
+// maxHTMLPublishSingleHTMLFileBytes 的 RelPath 列表。只针对 .html 文件，不波及图片/字体/JS。
+func oversizeHTMLFiles(candidates []htmlPublishCandidate) []string {
+	var hits []string
+	for _, c := range candidates {
+		if strings.EqualFold(filepath.Ext(c.RelPath), ".html") && c.Size > maxHTMLPublishSingleHTMLFileBytes {
+			hits = append(hits, c.RelPath)
+		}
+	}
+	return hits
+}
+
+// oversizeHTMLFilesError 构造单文件超限的 Validate 风格拒绝。
+func oversizeHTMLFilesError(hits []string) error {
+	return appsValidationParamError("--path",
+		"--path contains %d HTML file(s) exceeding the %d bytes (10MB) per-file limit: %s",
+		len(hits), maxHTMLPublishSingleHTMLFileBytes, truncatedJoin(hits, maxSensitiveListInError)).
+		WithHint("split or trim oversized HTML file(s); the 10MB cap applies to each single .html file")
+}
+
 // ensureIndexHTML 要求 walker 抓到的 candidates 里必须含 index.html。
 // 目录形态：根目录下必须有 index.html。
 // 单文件形态：文件名必须就是 index.html。
@@ -190,6 +222,9 @@ func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPu
 	if err := ensureIndexHTML(candidates); err != nil {
 		return nil, err
 	}
+	if hits := oversizeHTMLFiles(candidates); len(hits) > 0 {
+		return nil, oversizeHTMLFilesError(hits)
+	}
 	var rawTotal int64
 	for _, c := range candidates {
 		rawTotal += c.Size

shortcuts/apps/apps_html_publish_test.go

@@ -503,3 +503,82 @@ func TestRunHTMLPublish_RejectsOversizeRawCandidates(t *testing.T) {
 		t.Fatalf("client must not be called when raw cap hit")
 	}
 }
+
+func TestOversizeHTMLFiles(t *testing.T) {
+	orig := maxHTMLPublishSingleHTMLFileBytes
+	maxHTMLPublishSingleHTMLFileBytes = 100
+	defer func() { maxHTMLPublishSingleHTMLFileBytes = orig }()
+
+	cands := []htmlPublishCandidate{
+		{RelPath: "index.html", Size: 50},
+		{RelPath: "big.html", Size: 4096},
+		{RelPath: "BIG.HTML", Size: 4096}, // 大小写不敏感
+		{RelPath: "huge.png", Size: 9000}, // 非 .html，忽略
+	}
+	hits := oversizeHTMLFiles(cands)
+	if len(hits) != 2 {
+		t.Fatalf("hits=%v, want [big.html BIG.HTML]", hits)
+	}
+	for _, h := range hits {
+		if h == "huge.png" || h == "index.html" {
+			t.Fatalf("unexpected hit %q", h)
+		}
+	}
+}
+
+func TestMaxHTMLPublishSingleHTMLFileBytes_Default(t *testing.T) {
+	if maxHTMLPublishSingleHTMLFileBytes != 10*1024*1024 {
+		t.Fatalf("default=%d, want %d (10MiB)", maxHTMLPublishSingleHTMLFileBytes, 10*1024*1024)
+	}
+}
+
+func TestRunHTMLPublish_RejectsOversizeHTMLFile(t *testing.T) {
+	orig := maxHTMLPublishSingleHTMLFileBytes
+	maxHTMLPublishSingleHTMLFileBytes = 100
+	defer func() { maxHTMLPublishSingleHTMLFileBytes = orig }()
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "index.html"), []byte("<html></html>"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "big.html"), []byte(strings.Repeat("x", 4096)), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	fake := &fakeAppsHTMLPublishClient{}
+	_, err := runHTMLPublish(context.Background(), newTestFIO(), fake, appsHTMLPublishSpec{AppID: "app_x", Path: dir})
+	if err == nil {
+		t.Fatalf("expected per-file oversize error")
+	}
+	problem := requireAppsValidationProblem(t, err)
+	if !strings.Contains(problem.Message, "big.html") || !strings.Contains(problem.Message, "10MB") {
+		t.Fatalf("message=%q, want contains 'big.html' and '10MB'", problem.Message)
+	}
+	if problem.Hint == "" {
+		t.Fatalf("expected non-empty hint")
+	}
+	if len(fake.calls) != 0 {
+		t.Fatalf("client must not be called when an HTML file is oversize")
+	}
+}
+
+func TestRunHTMLPublish_IgnoresOversizeNonHTML(t *testing.T) {
+	// 单 .html 上限调小，但超限文件是 .png → 不被本护栏拦截，正常发布。
+	orig := maxHTMLPublishSingleHTMLFileBytes
+	maxHTMLPublishSingleHTMLFileBytes = 100
+	defer func() { maxHTMLPublishSingleHTMLFileBytes = orig }()
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "index.html"), []byte("<html></html>"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "big.png"), []byte(strings.Repeat("x", 4096)), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	fake := &fakeAppsHTMLPublishClient{resp: &htmlPublishResponse{URL: "https://miaoda/app_x"}}
+	if _, err := runHTMLPublish(context.Background(), newTestFIO(), fake, appsHTMLPublishSpec{AppID: "app_x", Path: dir}); err != nil {
+		t.Fatalf("non-html oversize must not be blocked by the .html cap: %v", err)
+	}
+	if len(fake.calls) != 1 {
+		t.Fatalf("client should be called; calls=%v", fake.calls)
+	}
+}

shortcuts/apps/apps_init.go

@@ -99,7 +99,14 @@ var AppsInit = common.Shortcut{
 			dry.Set("dir_error", err.Error())
 			dir = defaultCloneDir(appID)
 		} else if isAlreadyInitialized(dir) {
-			dry.Set("already_initialized", true)
+			if existing, e := ensureInitDirMatchesApp(dir, appID); e != nil {
+				if existing != "" {
+					dry.Set("app_id_mismatch", existing)
+				}
+				dry.Set("dir_error", e.Error())
+			} else {
+				dry.Set("already_initialized", true)
+			}
 		} else if e := ensureEmptyDir(dir); e != nil {
 			dry.Set("dir_error", e.Error())
 		}
@@ -199,6 +206,61 @@ func isAlreadyInitialized(dir string) bool {
 	return err == nil && !info.IsDir()
 }
 
+// readMetaAppID 读取 <dir>/.spark/meta.json 的 app_id，用于判断目标目录是否同一个妙搭应用。
+// 返回 (appID, isSparkProject, err)：
+//   - meta.json 不存在             → ("", false, nil)   非妙搭工程
+//   - 读取/解析失败（损坏/不可读）  → ("", false, err)   无法确认是否妙搭工程
+//   - 解析成功                     → (trim 后的 app_id, true, nil)（app_id 缺失/为空时为 ""）
+func readMetaAppID(dir string) (string, bool, error) {
+	b, err := os.ReadFile(filepath.Join(dir, metaRelPath)) //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); path is under the validated clone dir, and FileIO.Open rejects absolute paths.
+	if os.IsNotExist(err) {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, appsFileIOError(err, "read %s failed: %v", metaRelPath, err)
+	}
+	var m struct {
+		AppID string `json:"app_id"`
+	}
+	if err := json.Unmarshal(b, &m); err != nil {
+		return "", false, appsFileIOError(err, "parse %s failed: %v", metaRelPath, err)
+	}
+	return strings.TrimSpace(m.AppID), true, nil
+}
+
+// ensureInitDirMatchesApp 校验「已存在的目标目录」能否被 appID 安全复用：
+//   - 不是妙搭工程（无 meta.json）        → nil（交给 ensureEmptyDir 判空/非空）
+//   - 是妙搭工程且 app_id 与 appID 一致    → nil（走已初始化短路，复用本地代码）
+//   - 是妙搭工程但 app_id 不一致（含为空）  → 报错，提示换目录
+//   - meta.json 损坏/不可读，无法确认      → 报错（fail closed），提示换目录
+//
+// 返回值 existing 是目录里已存在的 app_id（仅"已是另一个 app"的拒绝场景非空），供调用方在
+// dry-run 里回填 app_id_mismatch，避免二次读 meta.json。
+func ensureInitDirMatchesApp(dir, appID string) (existing string, err error) {
+	existing, isSpark, readErr := readMetaAppID(dir)
+	if readErr != nil {
+		return "", appsValidationParamError("--dir",
+			"target directory %q already exists but its %s is unreadable or corrupted; cannot confirm it belongs to app %s, refusing to use it",
+			dir, metaRelPath, appID).
+			WithHint("choose a different --dir, or repair/remove the directory, before running +init").
+			WithCause(readErr)
+	}
+	if !isSpark || existing == appID {
+		return existing, nil
+	}
+	if existing == "" {
+		// meta 存在但缺 app_id：更可能是同一应用上次 +init 中断留下的半成品，而非另一个 app。
+		return "", appsValidationParamError("--dir",
+			"target directory %q has a %s without an app_id; cannot confirm it belongs to app %s, refusing to use it",
+			dir, metaRelPath, appID).
+			WithHint("remove the directory and re-run +init, or choose a different --dir")
+	}
+	return existing, appsValidationParamError("--dir",
+		"target directory %q is already initialized for a different app (%s); refusing to initialize app %s into it",
+		dir, existing, appID).
+		WithHint("choose a different --dir (or cd into the matching project) before running +init")
+}
+
 // ensureMetaAppID patches <dir>/.spark/meta.json to include app_id when the file
 // exists but lacks (or has an empty) app_id. Other fields are preserved. When
 // the file does not exist, this is a no-op (we never create it).
@@ -378,6 +440,11 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 		return err
 	}
 
+	// 异 app 目录护栏：拒绝把当前 app 初始化进另一个 app 的已初始化工程。
+	if _, err := ensureInitDirMatchesApp(dir, appID); err != nil {
+		return err
+	}
+
 	// Already-initialized short-circuit: a dir containing .spark/meta.json is an
 	// initialized app repo -> skip clone/scaffold/commit, but still refresh
 	// the local env so a re-run picks up the latest startup env vars.

shortcuts/apps/apps_init_test.go

@@ -363,7 +363,7 @@ func TestAppsInit_AlreadyInitialized_ShortCircuit(t *testing.T) {
 	if err := os.MkdirAll(filepath.Join(dir, ".spark"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(dir, metaRelPath), []byte(`{"app_id":"whatever"}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(dir, metaRelPath), []byte(`{"app_id":"app_x"}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	f := &fakeCommandRunner{results: map[string]fakeCallResult{"env-pull": envPullOK(filepath.Join(abs, ".env.local"))}}
@@ -394,6 +394,40 @@ func TestAppsInit_AlreadyInitialized_ShortCircuit(t *testing.T) {
 	}
 }
 
+func TestAppsInit_AlreadyInitialized_AppIDMismatch(t *testing.T) {
+	dir := relCloneDir(t)
+	if err := os.MkdirAll(filepath.Join(dir, ".spark"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// 目录是 app_other 的工程，却用 --app-id app_x 初始化 → 必须报错且不拉 env。
+	if err := os.WriteFile(filepath.Join(dir, metaRelPath), []byte(`{"app_id":"app_other"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	f := &fakeCommandRunner{}
+	withFakeRunner(t, f)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_x", "--dir", dir, "--as", "user"}, factory, stdout)
+	if err == nil {
+		t.Fatal("mismatched app_id must error")
+	}
+	problem := requireAppsValidationProblem(t, err)
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype=%q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--dir" {
+		t.Fatalf("expected *errs.ValidationError with Param=--dir, got %T param=%v", err, ve)
+	}
+	if !strings.Contains(problem.Message, "different app") {
+		t.Fatalf("message=%q, want 'different app'", problem.Message)
+	}
+	for _, c := range f.calls {
+		if containsAll(c, "+env-pull") || containsAll(c, "git", "clone") {
+			t.Errorf("mismatch must not run env-pull/clone; got %v", f.calls)
+		}
+	}
+}
+
 func TestAppsInit_HappyPathCleanTree(t *testing.T) {
 	f := &fakeCommandRunner{results: map[string]fakeCallResult{
 		"credential-init": credInitOK("http://u:t@h/app_x.git"),
@@ -1468,6 +1502,125 @@ func TestAppsInit_Description_IsAboutCode(t *testing.T) {
 	}
 }
 
+func TestReadMetaAppID(t *testing.T) {
+	writeMeta := func(t *testing.T, content string) string {
+		t.Helper()
+		dir := t.TempDir()
+		if err := os.MkdirAll(filepath.Join(dir, ".spark"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, metaRelPath), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return dir
+	}
+
+	// 不存在 meta.json → ("", false, nil)
+	if got, ok, err := readMetaAppID(t.TempDir()); ok || got != "" || err != nil {
+		t.Fatalf("no meta: got (%q,%v,%v), want (\"\",false,nil)", got, ok, err)
+	}
+	// 存在且有 app_id → (app_id, true, nil)
+	if got, ok, err := readMetaAppID(writeMeta(t, `{"app_id":"app_a"}`)); !ok || got != "app_a" || err != nil {
+		t.Fatalf("with app_id: got (%q,%v,%v), want (\"app_a\",true,nil)", got, ok, err)
+	}
+	// 存在但 app_id 空 → ("", true, nil)
+	if got, ok, err := readMetaAppID(writeMeta(t, `{"name":"x"}`)); !ok || got != "" || err != nil {
+		t.Fatalf("empty app_id: got (%q,%v,%v), want (\"\",true,nil)", got, ok, err)
+	}
+	// 存在但坏 JSON → ("", false, err)（无法确认）
+	if got, ok, err := readMetaAppID(writeMeta(t, `{not json`)); ok || got != "" || err == nil {
+		t.Fatalf("bad json: got (%q,%v,err=%v), want (\"\",false,non-nil)", got, ok, err)
+	}
+}
+
+func TestEnsureInitDirMatchesApp(t *testing.T) {
+	writeMeta := func(t *testing.T, content string) string {
+		t.Helper()
+		dir := t.TempDir()
+		if err := os.MkdirAll(filepath.Join(dir, ".spark"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, metaRelPath), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return dir
+	}
+
+	// 无 meta（非妙搭工程）→ nil（交给 ensureEmptyDir）
+	if _, err := ensureInitDirMatchesApp(t.TempDir(), "app_x"); err != nil {
+		t.Fatalf("no meta should pass: %v", err)
+	}
+	// 同 app_id → (app_id, nil)（走已初始化短路）
+	if existing, err := ensureInitDirMatchesApp(writeMeta(t, `{"app_id":"app_x"}`), "app_x"); err != nil || existing != "app_x" {
+		t.Fatalf("same app should pass: existing=%q err=%v", existing, err)
+	}
+
+	// 不同 app_id → error（换目录），返回 existing=app_other；断言 typed metadata（subtype/param）
+	existing, errMismatch := ensureInitDirMatchesApp(writeMeta(t, `{"app_id":"app_other"}`), "app_x")
+	if errMismatch == nil {
+		t.Fatal("different app should error")
+	}
+	if existing != "app_other" {
+		t.Fatalf("mismatch should return existing app_id, got %q", existing)
+	}
+	problem := requireAppsValidationProblem(t, errMismatch) // 已校验 Category==Validation
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype=%q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(errMismatch, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", errMismatch)
+	}
+	if ve.Param != "--dir" {
+		t.Fatalf("param=%q, want --dir", ve.Param)
+	}
+	if !strings.Contains(problem.Message, "different app") || !strings.Contains(problem.Message, "app_other") {
+		t.Fatalf("message=%q, want 'different app' and 'app_other'", problem.Message)
+	}
+	if !strings.Contains(problem.Hint, "different --dir") {
+		t.Fatalf("hint=%q, want 'different --dir'", problem.Hint)
+	}
+
+	// 空 app_id（缺 app_id 标记的半成品）→ error，独立文案（非 "different app"），返回 existing=""
+	emptyExisting, errEmpty := ensureInitDirMatchesApp(writeMeta(t, `{"name":"x"}`), "app_x")
+	if errEmpty == nil {
+		t.Fatal("empty meta app_id should error (cannot confirm same app)")
+	}
+	if emptyExisting != "" {
+		t.Fatalf("empty app_id should return existing=\"\", got %q", emptyExisting)
+	}
+	pEmpty := requireAppsValidationProblem(t, errEmpty)
+	if pEmpty.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("empty subtype=%q, want %q", pEmpty.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !strings.Contains(pEmpty.Message, "without an app_id") {
+		t.Fatalf("empty app_id should have its own message, msg=%q", pEmpty.Message)
+	}
+	if strings.Contains(pEmpty.Message, "different app") {
+		t.Fatalf("empty app_id must not reuse the different-app wording, msg=%q", pEmpty.Message)
+	}
+
+	// meta 损坏/不可读 → error（fail closed），返回 existing=""
+	badExisting, errBad := ensureInitDirMatchesApp(writeMeta(t, `{not json`), "app_x")
+	if errBad == nil {
+		t.Fatal("corrupted meta should fail closed")
+	}
+	if badExisting != "" {
+		t.Fatalf("corrupted should return existing=\"\", got %q", badExisting)
+	}
+	pBad := requireAppsValidationProblem(t, errBad)
+	if pBad.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("corrupted subtype=%q, want %q", pBad.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !strings.Contains(pBad.Message, "unreadable or corrupted") {
+		t.Fatalf("corrupted meta msg=%q, want 'unreadable or corrupted'", pBad.Message)
+	}
+	var veBad *errs.ValidationError
+	if !errors.As(errBad, &veBad) || veBad.Param != "--dir" {
+		t.Fatalf("corrupted: expected ValidationError Param=--dir, got %T param=%v", errBad, veBad)
+	}
+}
+
 // TestRunScaffold_SubprocessFailureIsExternalTool pins the typed
 // classification of an external-tool failure: a failing git subprocess
 // surfaces as internal/external_tool with the cause preserved.

shortcuts/mail/mail_triage.go

@@ -770,13 +770,7 @@ func buildListParams(runtime *common.RuntimeContext, mailboxID string, f triageF
 				params["folder_id"] = folderIDFromFilter
 			}
 		} else {
-			resolved, err := resolveFolderID(runtime, mailboxID, folderIDFromFilter)
-			if err != nil {
-				return nil, err
-			}
-			if resolved != "" {
-				params["folder_id"] = resolved
-			}
+			params["folder_id"] = folderIDFromFilter
 		}
 	} else if folderFromFilter != "" {
 		if dryRun {
@@ -786,13 +780,7 @@ func buildListParams(runtime *common.RuntimeContext, mailboxID string, f triageF
 				params["folder_id"] = folderFromFilter
 			}
 		} else {
-			resolved, err := resolveFolderName(runtime, mailboxID, folderFromFilter)
-			if err != nil {
-				return nil, err
-			}
-			if resolved != "" {
-				params["folder_id"] = resolved
-			}
+			params["folder_id"] = folderFromFilter
 		}
 	}
 
@@ -811,13 +799,7 @@ func buildListParams(runtime *common.RuntimeContext, mailboxID string, f triageF
 				params["label_id"] = labelIDFromFilter
 			}
 		} else {
-			resolved, err := resolveLabelID(runtime, mailboxID, labelIDFromFilter)
-			if err != nil {
-				return nil, err
-			}
-			if resolved != "" {
-				params["label_id"] = resolved
-			}
+			params["label_id"] = labelIDFromFilter
 		}
 	} else if labelFromFilter != "" {
 		if dryRun {
@@ -827,13 +809,7 @@ func buildListParams(runtime *common.RuntimeContext, mailboxID string, f triageF
 				params["label_id"] = labelFromFilter
 			}
 		} else {
-			resolved, err := resolveLabelName(runtime, mailboxID, labelFromFilter)
-			if err != nil {
-				return nil, err
-			}
-			if resolved != "" {
-				params["label_id"] = resolved
-			}
+			params["label_id"] = labelFromFilter
 		}
 	}
 

shortcuts/mail/mail_triage_test.go

@@ -12,6 +12,7 @@ import (
 	"testing"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -974,7 +975,11 @@ func TestBuildListParamsDryRunOnlyUnread(t *testing.T) {
 func TestBuildListParamsDryRunFolderAlias(t *testing.T) {
 	rt := runtimeForMailTriageTest(t, nil)
 	f := triageFilter{Folder: "sent"}
-	got, err := buildListParams(rt, "me", f, 20, "", true)
+	resolved, err := resolveListFilter(rt, "me", f, true)
+	if err != nil {
+		t.Fatalf("resolveListFilter: %v", err)
+	}
+	got, err := buildListParams(rt, "me", resolved, 20, "", true)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -983,10 +988,30 @@ func TestBuildListParamsDryRunFolderAlias(t *testing.T) {
 	}
 }
 
+func TestBuildListParamsDryRunCustomFolderPreservesInput(t *testing.T) {
+	rt := runtimeForMailTriageTest(t, nil)
+	f := triageFilter{Folder: "team-folder"}
+	resolved, err := resolveListFilter(rt, "me", f, true)
+	if err != nil {
+		t.Fatalf("resolveListFilter: %v", err)
+	}
+	got, err := buildListParams(rt, "me", resolved, 20, "", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["folder_id"] != "team-folder" {
+		t.Fatalf("expected dry-run folder_id=team-folder, got %v", got["folder_id"])
+	}
+}
+
 func TestBuildListParamsDryRunLabelAlias(t *testing.T) {
 	rt := runtimeForMailTriageTest(t, nil)
 	f := triageFilter{Label: "flagged"}
-	got, err := buildListParams(rt, "me", f, 10, "", true)
+	resolved, err := resolveListFilter(rt, "me", f, true)
+	if err != nil {
+		t.Fatalf("resolveListFilter: %v", err)
+	}
+	got, err := buildListParams(rt, "me", resolved, 10, "", true)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -995,6 +1020,25 @@ func TestBuildListParamsDryRunLabelAlias(t *testing.T) {
 	}
 }
 
+func TestBuildListParamsDryRunCustomLabelPreservesInput(t *testing.T) {
+	rt := runtimeForMailTriageTest(t, nil)
+	f := triageFilter{Label: "custom-label"}
+	resolved, err := resolveListFilter(rt, "me", f, true)
+	if err != nil {
+		t.Fatalf("resolveListFilter: %v", err)
+	}
+	got, err := buildListParams(rt, "me", resolved, 10, "", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := got["folder_id"]; ok {
+		t.Fatalf("folder_id should not be set when label is specified, got %v", got["folder_id"])
+	}
+	if got["label_id"] != "custom-label" {
+		t.Fatalf("expected dry-run label_id=custom-label, got %v", got["label_id"])
+	}
+}
+
 // --- buildSearchParams additional coverage ---
 
 func TestBuildSearchParamsAllFilterFields(t *testing.T) {
@@ -1791,3 +1835,137 @@ func mailTriageSearchItem(messageID, subject string) map[string]interface{} {
 		},
 	}
 }
+
+// registerMailTriageFoldersListStub registers a NON-reusable stub for the
+// mailbox folders list API. Because it is non-reusable, any second hit returns
+// "httpmock: no stub for GET .../folders" — which is exactly the assertion we
+// use to prove resolveListFilter runs once and buildListParams does NOT
+// re-resolve. folderID/folderName is the single custom folder the API reports.
+func registerMailTriageFoldersListStub(reg *httpmock.Registry, mailbox, folderID, folderName string) {
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    mailboxPath(mailbox, "folders"),
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"id":   folderID,
+						"name": folderName,
+					},
+				},
+			},
+		},
+	})
+}
+
+// registerMailTriageListPageStub registers one page of the messages list API,
+// disambiguated from sibling pages by a URL substring unique to that page
+// (e.g. "page_size=5" for page 1 vs "page_size=2" for page 2). The substring
+// must NOT depend on query-param ordering: map iteration makes param order
+// nondeterministic, so prefer a value-only token like "page_size=N" (the N
+// differs per page because pageSize = maxCount - fetched_so_far). Non-reusable
+// so reg.Verify catches under- or over-consumption.
+func registerMailTriageListPageStub(reg *httpmock.Registry, urlSubstring string, items []string, hasMore bool, pageToken string) {
+	data := map[string]interface{}{
+		"items":    items,
+		"has_more": hasMore,
+	}
+	if pageToken != "" {
+		data["page_token"] = pageToken
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    urlSubstring,
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": data,
+		},
+	})
+}
+
+// TestMailTriageCustomFolderResolvesOnceAcrossListPages is the regression test
+// for the bug where buildListParams re-called resolveFolderID on every list
+// page, turning "resolve once" into "1 + page_count" folder-list API calls and
+// easily tripping rate limits.
+//
+// Setup: a custom folder filter that forces resolveListFilter to hit the
+// folders list API once (to map folder name "team-folder" to folder_id), then two
+// messages-list pages. The folders list stub is non-reusable, so if
+// buildListParams re-resolves, the second hit fails with "no stub". The
+// messages-list stubs are page-specific (disambiguated by page_size in the
+// URL), so both pages are served and Verify asserts each fired exactly once.
+func TestMailTriageCustomFolderResolvesOnceAcrossListPages(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	defer reg.Verify(t)
+
+	// listMailboxFolders (called once by resolveListFilter) gates on the
+	// mail:user_mailbox.folder:read scope, which the default test token does
+	// not carry. Re-store the token with that scope appended so the folders
+	// API call is actually exercised (and thus the non-reusable folders stub
+	// is the load-bearing "exactly once" assertion).
+	const folderScope = "mail:user_mailbox.folder:read"
+	cfg := mailTestConfig()
+	if stored := auth.GetStoredToken(cfg.AppID, cfg.UserOpenId); stored != nil {
+		if !strings.Contains(stored.Scope, folderScope) {
+			stored.Scope = stored.Scope + " " + folderScope
+			if err := auth.SetStoredToken(stored); err != nil {
+				t.Fatalf("re-store token with folder scope: %v", err)
+			}
+		}
+	}
+
+	const (
+		mailbox    = "me"
+		folderName = "team-folder"
+		folderID   = "fld_custom_team"
+		page2Token = "tok_page2"
+	)
+	// --max 5 with listPageMax=20 → pageSize = 5-0 = 5 on page 1, then 5-3 = 2
+	// on page 2. The page_size query value disambiguates the two list stubs.
+	page1IDs := []string{"msg_a", "msg_b", "msg_c"}
+	page2IDs := []string{"msg_d", "msg_e"}
+
+	// Folders list: registered exactly once, non-reusable. Any second folder
+	// lookup (the bug) fails the test with "no stub for GET .../folders".
+	registerMailTriageFoldersListStub(reg, mailbox, folderID, folderName)
+	// Messages list, page 1: 3 ids, has_more, hands off a page-2 token. The
+	// page_size value (5 = maxCount - 0) is unique to page 1; page 2 uses 2.
+	registerMailTriageListPageStub(reg, "page_size=5", page1IDs, true, page2Token)
+	// Messages list, page 2: 2 ids, terminal.
+	registerMailTriageListPageStub(reg, "page_size=2", page2IDs, false, "")
+	// Batch metadata fetch for all 5 ids.
+	registerMailTriageBatchStub(reg, mailbox, []map[string]interface{}{
+		mailTriageBatchMessage("msg_a", "Subject A"),
+		mailTriageBatchMessage("msg_b", "Subject B"),
+		mailTriageBatchMessage("msg_c", "Subject C"),
+		mailTriageBatchMessage("msg_d", "Subject D"),
+		mailTriageBatchMessage("msg_e", "Subject E"),
+	})
+
+	args := []string{
+		"+triage",
+		"--as", "user",
+		"--mailbox", mailbox,
+		"--filter", `{"folder":"` + folderName + `"}`,
+		"--max", "5",
+		"--format", "json",
+	}
+	if err := runMountedMailShortcut(t, MailTriage, args, f, stdout); err != nil {
+		t.Fatalf("unexpected error running +triage (likely a second folders API call — the bug): %v", err)
+	}
+
+	data := decodeMailTriageJSONOutput(t, stdout)
+	messages := mailTriageMessagesFromOutput(t, data)
+	if len(messages) != 5 {
+		t.Fatalf("expected 5 messages across 2 pages, got %d (stdout=%s)", len(messages), stdout.String())
+	}
+	if got := data["has_more"]; got != false {
+		t.Fatalf("expected has_more=false after exhausting pages, got %v", got)
+	}
+	// All registered stubs (1 folders + 2 list pages + 1 batch_get) are
+	// non-reusable; reg.Verify (deferred above) asserts each was matched
+	// exactly once. Combined with the non-reusable folders stub, this is the
+	// proof that the folders list API was called exactly once across both
+	// pages — the core invariant the fix restores.
+}

skills/lark-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-apps
 version: 1.0.0
-description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站给人看，或提到妙搭/Spark/Miaoda、应用数据库、可见范围时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、可见范围时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -48,8 +48,14 @@ metadata:
 
 - **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。
 - 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。
-- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}` 仅进编辑态，不能顶替发布当分享链接。
+- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`：进应用编辑/开发态、管理与继续开发应用的入口。发布成功后，连同发布态链接一并提供给用户（说明"管理 / 继续开发去这里"）；但它仅进编辑态，**不能**顶替发布态链接当分享链接。
 - 发布态链接来源：html → `+html-publish` 的 `data.url`；全栈 → `+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`。
+- **可见范围**：发布态链接（html 的 `data.url`、全栈的 `online_url`）默认仅**创建者可见**，发给他人对方会无权限打不开。当可分享链接交付给用户前，先告知当前仅本人可见，再询问是否用 `+access-scope-set`（`tenant`/`public`/`specific`）放开（可先 `+access-scope-get` 查当前范围）。
+
+## 能力边界
+
+- lark-cli **不支持**配置应用的权限（应用内 RBAC、成员角色、协作者权限）/ 自动化 / 插件。`+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限。
+- 用户要配置权限 / 自动化 / 插件时，引导其使用开发态连接前往云端开发（妙搭 web）处理。
 
 ## app_id 获取
 
@@ -69,4 +75,4 @@ metadata:
 ## 高影响动作：确认与预授权
 
 - **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
-- **不豁免底线**：会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）即便已预授权，也先 `--dry-run` 确认。
+- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项。

skills/lark-apps/references/lark-apps-html-publish.md

@@ -11,7 +11,7 @@
 - 必填：`--app-id`、`--path`。
 - `--path` 可以是单个文件或目录；入口必须是 `index.html`。
 - 可选：`--allow-sensitive`，跳过凭据文件扫描。
-- 客户端会打包 tar.gz 并上传发布；压缩包上限当前为 20MB，未压缩候选文件总量也有保护上限。
+- 客户端打包 tar.gz 上传发布。三条硬性大小限制，任一超限即被客户端拒绝、无法发布：单个 `.html` 文件 ≤ 10MB、打包后 tar.gz ≤ 20MB、未压缩候选文件总量 ≤ 200MB。
 
 ## 示例
 
@@ -33,12 +33,19 @@ lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
 - 发布态访问链接以本命令成功返回的 `data.url` 为准。
 - 重新发布前，`+list` 的 `is_published=true` 只能说明历史上发布过，不代表当前本地产物已经部署。
 
+## 发布前置门（第一步，先于任何其他动作）
+
+收到发布意图后，第一个动作是量三个尺寸，不是读文件内容、不是打包：
+1. 单个 `.html` ≤ 10MB / tar.gz ≤ 20MB / 未压缩总量 ≤ 200MB。
+2. 任一超限 → 立即 STOP，把超限数字转述给用户，交还决定权。
+3. 三项都通过 → 才进入下面的命令骨架。
+
 ## 预览与发布边界
 
 - 用户只说“用 HTML 写个 PPT/页面给我看看”时，先生成本地文件或目录，返回路径并问是否发布到妙搭分享；不要默认创建应用或部署。
 - 用户明确说“部署出去/发链接/可分享”时，才创建 `html` 应用并用 `+html-publish`。
 - 用户要发布但没有 app_id 时，先 `+create --app-type html` 创建应用；应用名可从页面/站点主题生成，不要让用户手动提供 app_id。
-- 若产物首页不是 `index.html`，发布前改名或复制为 `index.html`；目录发布时只传干净产物目录，例如 `./dist`。`.git` 目录会被自动排除，不会进入压缩包；`node_modules`、源码缓存等仍建议手动精简以控制包体。
+- 若产物首页不是 `index.html`，发布前改名或复制为 `index.html`；目录发布时只传干净产物目录，例如 `./dist`。`.git` 目录会被自动排除，不会进入压缩包。
 - 重新部署同一个 HTML 应用时复用原 `app_id`，只重新执行 `+html-publish --app-id <id> --path <dir-or-index.html>`。
 
 ## 安全规则
@@ -48,4 +55,3 @@ lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
 ## 常见失败
 
 - 缺少 `index.html`：目录根放置 `index.html`，或单文件路径直接指向名为 `index.html` 的文件。
-- 包体过大：让用户精简 `--path`，不要把源码、依赖目录、构建缓存一起发布。

skills/lark-apps/references/lark-apps-init.md

@@ -31,6 +31,7 @@ lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
 
 ## Agent 规则
 
-- 目标目录必须不存在、为空目录，或已含 `.spark/meta.json` 的已初始化仓库。
+- 目标目录必须不存在、为空目录，或已含 `.spark/meta.json` 且其 app_id 与 `--app-id` 一致的已初始化仓库。
 - 目标目录已含 `.spark/meta.json` 时，`+init` 会跳过 clone/scaffold，但仍执行一次 env-pull 刷新本地环境变量；告知用户“仓库已初始化，本地环境变量已刷新，可直接开发”，不要误报失败或重复 clone。
 - `+init` 输出没有必要原样复述；告诉用户 clone path、分支和下一步即可。
+- 新建应用做本地初始化时，若选定的目标目录已存在，不要复用，改用一个不冲突的目录名（已预授权”放手做”时自动追加后缀如 `-2`；否则向用户确认目录名）。

skills/lark-doc/SKILL.md

@@ -26,7 +26,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
 2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
-3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
+3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
 4. **需要使用 callout、grid、table、whiteboard 等富 block 时** → 参考 [`lark-doc-style.md`](references/style/lark-doc-style.md) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。
 
 **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
@@ -36,11 +36,9 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
 
 ## 快速决策
-- 用户需要“某个 block 的直达链接 / 锚点链接”时：返回 `文档基础 URL#block_id`。如果当前只有文档 URL 没有 block_id，先用 `docs +fetch --detail with-ids` 拿到目标 block 的 id
-- 例：
-  - 已知文档 URL = `https://xxx.feishu.cn/docx/doxcn123`
-  - 已知 block_id = `blkcn456`
-  - 应返回 `https://xxx.feishu.cn/docx/doxcn123#blkcn456`
+- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
+- block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
+- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
 - 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入

skills/lark-doc/references/lark-doc-create.md

@@ -4,7 +4,7 @@
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
 > 2. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
 >
-> **需要使用 callout、grid、table、whiteboard 等富 block，或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。该文件是表达组件参考，不是固定模板。**
+> **需要富 block 或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。**
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
@@ -74,7 +74,7 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 ## 最佳实践
 
 - 文档标题从内容中自动提取：XML 使用 `<title>`；Markdown 使用文档开头唯一的一级标题（`# 标题`），正文从 `##` 开始。不要在内容开头重复写标题，也不要在 Markdown 正文中使用多个一级标题。
-- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
+- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容。
 - **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
 
 ## 参考

skills/lark-doc/references/lark-doc-update.md

@@ -5,7 +5,7 @@
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
 > 2. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
 >
-> **需要使用 callout、grid、table、whiteboard 等富 block，或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。该文件是表达组件参考，不是固定模板。**
+> **需要富 block 或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。**
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
@@ -44,6 +44,15 @@
 | `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
 | `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
 
+## Block ID 生命周期
+
+写操作后不要默认复用之前 fetch 到的 block ID：
+
+- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前重新 fetch
+- `block_insert_after` / `append` / `block_copy_insert_after`：锚点 / 源 ID 通常保留，新内容是新 ID；要操作新内容先重新 fetch
+- `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch
+- `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch
+
 ## 指令示例
 
 ### str_replace — 全文文本替换
@@ -114,8 +123,6 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace
   --content '<p>替换后的段落内容</p>'
 ```
 
-> `block_replace` 由服务端执行整块替换，目标 block 的 ID 不保证在替换后继续可用。后续如果还要在替换后的块附近继续 `block_insert_after`、`range` 或其他 block 级操作，先重新 `docs +fetch --detail with-ids` 获取最新 block ID，不要复用旧 ID。
-
 ### block_delete — 删除指定 block
 
 ```bash
@@ -237,7 +244,6 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
 - **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
 - **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
 - **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
-- **block_replace 后重新获取 ID**：`block_replace` 成功后旧 block ID 不保证继续可用；继续做相邻块操作前，重新 `docs +fetch --detail with-ids`
 - **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
 - **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：
   1. 用 `block_insert_after` 在目标位置插入新的富文本结构

skills/lark-doc/references/lark-doc-whiteboard.md

@@ -9,11 +9,11 @@
 | `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
 | `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
 
-## 画板优先规则
+## 画板适用规则
 
-写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。
+写文档时，核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，如果图示能明显降低理解成本，可以规划为画板；结构简单或文字更清楚的内容不必强行画板化。
 
-同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。
+同一篇文档可以有多个画板。确有多个独立图示点时，可拆成多个聚焦画板，而不是把所有信息塞进一张大图。
 
 ## 文档与画板协同流程
 

skills/lark-doc/references/style/lark-doc-create-workflow.md

@@ -43,7 +43,7 @@
 8. **优先处理步骤三识别出的画板需求**：
    参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
 9. Spawn 内容改写 Agent 定向润色：
-   - 文字密集且不易读的章节可转为 `<table>`/`<grid>`/`<callout>`，也可以拆段、改列表或保留纯文本
+   - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `<table>` / `<grid>` / `<callout>`
    - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用
    - 本地图片使用 `docs +media-insert` 插入
 

skills/lark-doc/references/style/lark-doc-style.md

@@ -10,18 +10,18 @@
 2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件
 3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠
 4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式
-5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
+5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达
 
 ## 二、元素选择指南
 
 需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
 
-| 场景                                         | 推荐方案                                  |
+| 场景                                         | 可选表达方式                                |
 |--------------------------------------------|---------------------------------------|
-| 需要突出的一小段结论 / 摘要 / 注意事项                    | `<callout>`；是否使用 emoji 和颜色由文档语气决定 |
-| 方案对比 / 优劣势 / Before vs After                | `<grid>` 2 列分栏、`<table>` 或画板，按复杂度选择 |
+| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒          | 需要视觉提醒时可用 `<callout>`；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 |
+| 方案对比 / 优劣势 / Before vs After                | 简短对比可用段落、列表或 `<grid>`；维度较多且需要逐项比较时再考虑 `<table>` 或画板 |
 | 简短低风险对比                                    | `<grid>` 2 列分栏                        |
-| 3+ 属性的结构化数据 / 指标表                          | `<table>` + 表头背景色                     |
+| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期           | 可用 `<table>`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 |
 | 任务清单 / 检查项                                 | `<checkbox>`                          |
 | 代码片段                                       | `<pre lang="x" caption="说明">`         |
 | 引用 / 公式                                    | `<blockquote>` / `<latex>`            |

skills/lark-doc/references/style/lark-doc-update-workflow.md

@@ -34,7 +34,7 @@
    参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
 6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：
    - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
-   - 可以通过重写段落、调整标题、拆分列表、补表格/分栏/callout 等方式提升可读性
+   - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性
    - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步
 
 ### 步骤三：验证（串行）