Add note shortcuts for note detail and unified transcript retrieval, route vc note detail parsing through the note domain, and update note/vc/minutes skill guidance for normal versus unified transcript handling.
Includes dry-run E2E coverage for the new note shortcuts and documents the remaining live E2E fixture gap.
* feat: add fullstack app-type and --message to apps +create (#1)
* feat: accept fullstack app-type and require --message for it
* feat: inject message into fullstack create request body
* refactor: align fullstack message injection with existing body-build style
* docs: document fullstack app-type and --message for apps +create
* docs: keep scene numbering consistent in lark-apps-create reference
* docs: add HTML/fullstack intent routing to lark-apps SKILL.md
* docs: cover fullstack in lark-apps skill description and clarify HTML flow step
* test: assert fullstack in allow-list error and reject wrong-cased fullstack
* feat: drop --message from apps +create (#4)
* feat: drop --message from apps +create
* docs: drop --message and document agent-generated name/description for apps +create
* feat: add apps local key-value file storage (#5)
* feat: add Miaoda app git credential support (#9)
* fix: remove APIError detail field dependency
* docs(apps): expand lark-apps skill for local-dev & cloud-chat workflows (#3)
Reframe lark-apps from an HTML-publish skill into a full Miaoda app dev
tool covering three paths: local fullstack dev, HTML hosting, and cloud
session dev. Builds on the fullstack create change already on this branch.
- SKILL.md: 3-path routing table; mental models (code via native git,
develop/main branch model, DB via +db-* through Miaoda, env auto-pulled
by `npm dev run`, auto-managed credentials); command index for the new
verbs; ambiguous-input fallback (infer app type from need, ask local vs
cloud instead of assuming; default HTML when no signal)
- add local-dev and cloud-dev playbooks
- create: keep HTML/fullstack + required --message; add local/cloud scene
routing and --enable-multi-env-db
- list: usable by agents with --filter; app_id resolution order
(user-provided / .spark/meta.json / +list --filter)
Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>
Co-authored-by: raistlin042 <lvxinsheng@bytedance.com>
* feat(apps): add 4 db CLI commands (table-list / table-schema / sql / dev-init)
妙搭 data CLI 4 条命令，复用存量 OpenAPI URL + 1 个新增 dev-init：
- +db-table-list → GET /apps/{id}/tables（游标分页，AppTable 含预估行数/占用空间）
- +db-table-schema → GET /apps/{id}/tables/{name}（默认结构化 schema；--format pretty 出建表 DDL）
- +db-sql → POST /apps/{id}/sql_commands（?transactional=false DBA 模式）
- +db-dev-init → POST /apps/{id}/db_dev_init（单库→online/dev，不可逆，high-risk-write）
要点：
- sql result 兼容两种 wire 形态（结构化 [{sql_type,data,record_count}] 与 legacy ["rows-json"]）
- 多语句失败：server 返 code:0 + ERROR 哨兵，CLI 升级成 typed api_error（exit 非 0），
detail 带 statement_index/completed/rolled_back，防止 agent 误判 ok:true 假成功
- pretty 渲染对齐 miaoda：列间两空格、CJK 双宽、size 友好格式（KB/MB/GB）
- 单测 + e2e dry-run 全覆盖；BOE 真机 e2e 验证通过（25 PASS）
- SKILL.md 注册 4 条命令 + 4 篇 reference
注：内含的 BOE 联调专用 env 覆盖（LARK_CLI_OPEN_API_BASE / LARK_CLI_X_TT_ENV，
internal/cmdutil + internal/envvars）未包含在本次提交，仅本地联调用。
Change-Id: I0fe4458086708a93941e2dee852fa6a10b53bd4a
* docs(lark-apps): db 能力补进 SKILL.md description 的 WHEN 段
按 skill 质量规范（description 三段式 WHAT+WHEN+NOT，加载前唯一可见信息），
原 WHEN 仅"连数据库调试"含糊覆盖 db。补成「查看或操作应用数据库（看表结构 /
跑 SQL / 初始化 dev 环境）」，让 +db-table-schema / +db-sql / +db-dev-init
类查询能精确触发，净增 ~12 字无膨胀。
Change-Id: Id52819fa7d6b8ed0c1f174bf5946d55da7b893d7
* Feat/apps env pull (#11)
* feat: add apps env-pull shortcut
* fix: support array env_vars response in apps env-pull
* fix(apps): improve env-pull merge and expiry output
* feat: add keyword/scope/app-type query to apps +list and unhide it (#8)
* feat: switch apps +create --app-type enum to lowercase html/full_stack
* feat: add keyword/scope/app-type query to apps +list and unhide it
* docs: document apps +list query params and lowercase app_type enum
* test: update apps cli_e2e dry-run tests for lowercase app_type and +list filters
* docs: trim redundant app_type case-sensitivity note in create skill
* docs: single-source apps +list usage contract to SKILL.md
* feat: add apps publish shortcuts (publish/status/history/error-log) (#12)
* feat: add apps publish shared guard and NodeStatus mapping
* test: cover json.Number path in injectStatusName
* feat: add apps +publish shortcut
Implements the `apps +publish` command with dry-run preview (upstream
PSM path shown) and an Execute gated by ensurePublishWired() per the
not-yet-deployed OpenAPI gateway constraint (publishAPIWired=false).
* refactor: make apps publish path placeholders var to satisfy go vet
Declare the four publishXxxPath constants as var instead of const so
go vet's printf analyzer skips them while they are empty placeholders.
Revert the Execute path-build in apps_publish.go from strings.Replace
back to fmt.Sprintf (now safe because the format string is a var).
* feat: add apps +publish-history shortcut
* feat: add apps +publish-status shortcut
* feat: add apps +publish-error-log shortcut
* feat: register apps publish shortcuts
Add AppsPublish, AppsPublishHistory, AppsPublishStatus, AppsPublishErrorLog
to Shortcuts() and update count test from 6 → 10.
* docs: add skill references for apps publish shortcuts
* docs: surface apps publish shortcuts in lark-apps SKILL.md
* docs: clarify publish instance id is not an approval instance
* docs: nudge agent to run apps +publish --dry-run for release requests
* feat: update apps publish shortcuts to v1.0.381 release protocol
Rename concept instance→release across all 4 publish shortcuts and their
tests: NodeStatus→ReleaseStatus enum, --instance-id→--release-id flag,
pipelineTaskID→releaseID response field, errorJobs→errorLogs, and
upstream HTTP path consts→RPC method name consts (PSM lark.apaas.devops
v1.0.381). Dry-run now shows psm+rpc_method instead of an HTTP path.
* docs: update apps publish skill docs to v1.0.381 release protocol
* fix: soften apps publish unavailable hint to user-facing language
* feat: update apps publish to v1.0.385 string status + --status filter
- Remove obsolete int-enum machinery (releaseStatusName/toInt/injectStatusName)
and their encoding/json + fmt imports from apps_publish_common.go
- +publish Execute now returns status string alongside release_id
- +publish-history gains --status Enum flag (publishing/finished/failed);
buildHistoryBody gains status param, table column status_name→status
- +publish-status Execute drops injectStatusName, pretty prints out["status"]
- +publish-error-log shapeErrorLog is string passthrough (no status_name)
- Unit tests updated: delete 3 obsolete common tests, update history/error-log
* docs: update apps publish docs to v1.0.385 string status + --status filter
* feat: wire apps publish shortcuts to final gateway paths (guard stays until deploy)
Replace RPC-name placeholders with real OpenAPI paths (publishCreate/Get/ErrorLog/ListPath consts). Switch DryRun to idiomatic HTTP form (POST/GET + real URL + body/params). Fix body/query placement: publish body has no app_id (path-only); history switches from POST body to GET query with snake page_token. Fix Execute response reads to snake_case fields (release_id, created_at, updated_at, error_logs). publishAPIWired stays false; 1-line flip activates live calls.
* docs: update apps publish docs to final gateway paths
Replace RPC/PSM dry-run example with real HTTP form (POST/GET /open-apis/spark/v1/apps/:app_id/releases[/:release_id[/error_logs]]).
Fix all response field names to snake_case (release_id, created_at, updated_at, error_log).
Note --status/--limit/--page-token as HTTP query params in publish-history.
* feat: enable apps publish gateway calls (remove not-deployed guard)
* docs: remove not-deployed transition notes from apps publish docs
* feat: use spark:app:publish scope for apps +publish
* feat(apps): add +init shortcut to initialize Miaoda app repo (#6)
* feat(apps): add command runner and credential redaction for +init
* fix(apps): make credential redaction scheme matching case-insensitive
* feat(apps): add +init shortcut declaration, validation, and dry-run
* feat(apps): implement +init orchestration (credential-init, clone, checkout, conditional push)
* fix(apps): redact full userinfo when repo URL contains literal @
* docs(apps): add +init skill reference
* fix(apps): declare explicit empty Scopes on +init shortcut
* fix(apps): consume repository_url from +git-credential-init in +init
* feat(apps): add +init template flag and absolute-path dir resolution
* refactor(apps): use shared charcheck for +init --dir validation
* feat(apps): add meta.json, steering, and empty-repo helpers for +init
* feat(apps): add +init npx scaffold orchestration (init/upgrade branches)
* feat(apps): wire +init scaffold, already-initialized short-circuit, npx dep check
* docs(apps): document +init npx scaffold, --template, --dir, already-initialized
* docs(apps): correct stale +git-credential-init unreleased note in +init ref
* fix(apps): reject all control chars in +init --dir
* feat(apps): add +init progress logging and optional --template resolver
* refactor(apps): inline constant in +init scaffold progress log
* docs(apps): document +init optional --template and stderr progress contract
* feat(apps): treat README-only repo as empty and commit with --no-verify in +init
* docs(apps): explain README-seed match and --no-verify rationale in +init
* docs(apps): document README-seed empty detection and commit --no-verify
* feat(apps): add session conversation lifecycle shortcuts (#13)
* feat(apps): add +session-create shortcut
* fix(apps): remove unused sessionPath helper, assert empty +session-create body
* feat(apps): add +session-list shortcut
* feat(apps): add +session-read shortcut
* feat(apps): add +session-stop shortcut
* feat(apps): add +chat shortcut
* feat(apps): register session lifecycle shortcuts
* docs(apps): add session conversation skill reference
* docs(apps): clarify fullstack session_id source and fallback
* style(apps): gofmt apps_session_create.go
* docs(apps): add conversation/session triggers to skill routing description
* docs(apps): add conversation flow guidance (when to reuse vs new session, per-step user prompts)
* docs(apps): slim session reference per skill quality standard (4047->1726 tok)
* docs(apps): tighten session additions in SKILL.md (4394->4145 tok)
* fix(apps): align +chat with v7.8 contract (async, no turn_id in response)
* fix(apps): update +chat path to .../sessions/{id}/chat (backend endpoint change)
* docs(apps): align SKILL.md session command shape with v7.8 contract
* style(apps): gofmt apps_db_table_schema_dryrun_test.go
Go 1.19+ gofmt 文档注释列表缩进新规则（普通缩进 → tab 对齐），
修复 fast-gate CI 的 gofmt 卡点。
Change-Id: Ic246a659e016d9d6216182199ef300ae6f00ef9d
* feat(apps): split +init commit, plainer wording, align skill branches (#14)
* refactor(apps): plainer +init progress/help wording, keep scaffold key
* refactor(apps): add porcelain change classifier for +init commit split
* feat(apps): split +init empty-repo commit into code + config, reword subjects
* refactor(apps): scaffold-kind constants and pathspec assertions for +init split
* docs(apps): use +init in Path A; align app-repo branch to sprint/default
* docs(apps): align local-dev playbook to sprint/default + origin remote
* docs(apps): document +init two-commit split and plainer init wording
* docs(apps): require asking clone dir before +init, no assumed path
* fix(apps): stage +init commits by exact paths to avoid gitignore error
* refactor(apps): lowercase miaoda in +init commit subjects
* test(apps): cover +init upgrade path with real git
* fix: harden app git credential handling (#16)
* fix: harden git credential refresh fallback (#18)
* fix(apps): validate env-pull key names before writing to .env.local (#17)
* fix(apps): validate env-pull key names before writing to .env.local
S2 (medium-low) from security review: env-pull wrote server-returned
env KEYs to .env.local without validation. A compromised or MITM'd
backend could inject arbitrary lines via keys containing newlines.
- Add envKeyPattern regex to validate keys match [A-Za-z_][A-Za-z0-9_]*
- extractEnvPullVars now returns skippedKeys for invalid key names
- Invalid keys are skipped (not hard-fail) so remaining valid keys
are still pulled
- writeEnvPullPretty prints a warning listing skipped keys
* fix(skills): correct npm script syntax from 'npm dev run' to 'npm run dev'
* fix(skills): align env-pull guidance with implementation
🤖 Generated with [Aiden x Claude Code]
* test(apps): cover storage/git-credential error paths and fix tz-flaky env-pull tests (#19)
The coverage and unit-test CI jobs failed on two timezone-dependent
assertions in apps_env_pull_test.go: the code renders the database
expiry via time.Local() while the tests hard-coded a CST literal, so
they failed under CI's UTC. Compute the expected string from the same
timestamp with Local() instead, making the assertions timezone-agnostic.
Also add unit tests for the error branches codecov flagged as uncovered,
taking storage.go and git_credential.go to 100%:
- storage Read/Write/Delete/List filesystem-error paths
- +git-credential-remove ConfigWarning output (pretty and JSON)
- gitCredentialLocalError nil passthrough
* fix(apps): silence +init forbidigo, npx app sync -y --prefer-online (#20)
* fix(apps): add Subtype to env-pull error literals (#21)
typed_error_completeness lint requires all errs.XxxError literals to
set Problem.Subtype. Add the missing field to 11 error constructions:
- ValidationError (user input checks): SubtypeInvalidArgument
- ValidationError (API response parsing): SubtypeInvalidResponse
- InternalError (filesystem ops): SubtypeUnknown
* feat(apps): inject FORCE_DB_BRANCH=dev in env-pull output (#23)
* feat(apps): inject FORCE_DB_BRANCH=dev in env-pull output
Always write FORCE_DB_BRANCH="dev" into the resolved .env.local after
extracting upstream env_vars, so downstream tooling pinning the dev
database branch does not need a separate manual edit. Existing local
values are overwritten in place via the canonical merge path.
* docs(skills): document apps +env-pull in lark-apps skill
Add the env-pull entry to the lark-apps SKILL index and ship the
matching reference doc covering args, merge semantics, return shape,
error envelope subtypes, and dry-run behavior so AI agents can route
to it without reading the Go source.
* feat(apps): surface is_published and online_url in +list pretty view (#22)
* docs: refactor lark-apps skill per quality spec (#24)
Slim SKILL.md and references against the lark-cli skill quality spec
while preserving domain knowledge and safety guardrails.
- Compress SKILL.md (drop the MUST-read prelude, full command-index
tables, and content already owned by lark-shared: auth, scope,
exit-10, risk policy, _notice); add version field; zero CRITICAL
markers.
- Defer flag enumeration in references to `--help`; convert
narration-inducing prohibitions into positive defaults; de-duplicate
the per-file error.hint relay into a single resident SKILL.md rule.
- Fix stale facts found against shortcuts/apps source: drop the
non-existent +create --message and --enable-multi-env-db flags,
+list --filter (now --keyword), +db-multi-env-init (now
+db-dev-init), and the removed html-publish cwd hard-reject.
- Keep all safety guardrails: db-dev-init irreversibility/exit-10,
db-sql non-transactional multi-statement, git-credential token
handling, html-publish credential scan, access-scope confirmation.
- Restore intent lost during slimming: release_id is not an approval
instance (do not route to lark-approval); resolve access-scope
targets via contact/im; ask the user before publishing as a
side-effect; distinguish developing an existing app locally
(+init) from creating a new one (+create).
* test(apps): supplement shortcuts/apps unit-test coverage to 88% (#25)
* test(apps): cover db-table-list numeric/byte formatting helpers
* test(apps): cover db-sql cell/code/dml/error render helpers
* test(apps): cover env-pull newline/expiry/extract-vars helpers
* test(apps): cover db-sql render branches and env-pull expiry edge case
* test(apps): cover init empty-dir/meta/ls-files error branches
* test(apps): cover env-pull target/read/parent-dir error branches
* test(apps): cover stage-and-commit and commit-push error branches
* test(apps): cover access-scope target split and JSON validation
* test(apps): cover html-publish decode error and scaffold sync failure
* test(apps): cover apps-update body field combinations
* test(apps): cover access-scope body build branches
* feat(apps): pass --local to npx skills sync in +init (#26)
* feat(apps): pass --local to all npx miaoda-cli calls in +init
* feat(apps): pass --local only to npx skills sync in +init
* docs(apps): surface +publish and +init dir-choice in local-dev flow (#27)
* docs(apps): surface +publish as deploy action in skill routing
* docs(apps): add explicit deploy-after-local-edit section to local-dev
* docs(apps): promote +init dir-choice instruction to a domain rule
* docs(apps): make dev-method a signal-driven entry gate before routing (#28)
* docs(apps): restore three-path overview line in apps skill intro (#29)
* feat(apps): add executable Examples to shortcut --help and error hints (#30)
* test(apps): guard every shortcut has a help Example and no PII
* feat(apps): add help Examples to all 24 apps shortcuts
* feat(apps): add actionable hints to high-impact error paths
* test(apps): cover withAppsHint set-if-empty hint behavior
* feat(apps): use concrete enum value in access-scope-set Example
* docs(apps): clarify db-sql/db-table-list json default output behavior
两处仅补充注释，不改逻辑：
- +db-sql: data.results 在 json 默认路径原样透出全部行，CLI 不二次截断；
server 对单条 SELECT 有 1000 行硬上限、超出直接返报错，非无界 token 黑洞。
- +db-table-list: json 默认透出含每表完整 columns[] 系产品设计（list 接口本就
返回列定义，json 消费方一次拿全量、免逐表再调 +db-table-schema），pretty 仅摘计数。
Change-Id: I1a49de8defc4428bfe1e774e4fd7adb45e59e3af
* feat(apps): command-layer AI-friendliness governance (P0+P1) (#32)
* fix(apps): normalize --app-type case to align with server
* refactor(apps): migrate CallAPI to CallAPITyped for typed errors and retryable
* feat(apps): trim icon_url and created_at from +list default output
* feat(apps): add actionable hints to high-impact error paths
* feat(apps): add 2-3 help Examples to +chat and +access-scope-set
* docs(apps): add --jq filter tips to list/db commands
* docs(apps): sync +list reference with trimmed output fields
* test(apps): assert error hints and messages carry no secrets or PII
* fix(apps): prefix --jq tips with .data. so they run against the response envelope
* test(apps): expect --app-type uppercase normalization in create dry-run E2E (#33)
* fix(apps): scaffold via @latest miaoda-cli instead of @alpha (#34)
* feat(apps): rework lark-apps triggering, routing & confirm policy (#35)
* feat(apps): results-oriented triggering, pre-auth floors, terminal URL
Widen description WHEN to cover app-building openers (CRM/审批/HTML page)
with no Miaoda signal word, WHAT still anchored to 妙搭应用开发与托管.
Add a pre-authorization rule (auth words skip confirm) with two non-exempt
floors: destructive DDL (DROP/TRUNCATE/ALTER drop|modify column) dry-run,
and first public-URL publish (+publish/+html-publish) when no auth word.
Exempt html app_type from the local-vs-cloud dev-method gate, and scope
that gate to new-app creation only (existing-app ops route directly).
Require an accessible URL as the end-to-end terminal step.
* feat(apps): apply eval-fix behavior contracts across reference docs
init/local-dev: end-to-end default-directory escape hatch; end-to-end
new-build starts with +create. db-sql: additive DDL direct-exec when
authorized, destructive DDL stays dry-run. local-dev/publish-status:
return online_url via +list as the full_stack publish terminal step.
cloud-dev: generation != shareable URL, +publish handoff, background
until-poll snippet (sleep N && cmd intercepted; deprecate ScheduleWakeup),
multi-turn publish precondition. publish/publish-error-log: transient
failure (EAI_AGAIN/ETIMEDOUT/registry) discrimination, retry cap 2,
honest receipt. env-pull: first-launch fallback. local-dev/db-dev-init:
new full_stack ships dual DB, skip +db-dev-init.
* refactor(apps): apply review feedback — semantic criteria, drop overfit/unverified content
Per line-by-line review of the eval-fix changes:
- Entry routing reframed to objective/semantic criteria (new-vs-existing =
'can an existing app be identified'; dev-method = who-writes-code
preference), replacing keyword/example matching.
- db-sql DDL gate restated by effect (data-loss / reversibility), not a
keyword list.
- Pre-authorization judged by expressed intent (not a word list); single
non-exempt floor (destructive/irreversible DB dry-run); confirm policy in
its own section, error.hint in 'failure handling'.
- init.md slimmed to command facts (directory choice owned by local-dev,
no init<->local-dev cycle); local-dev defers new-vs-existing to the entry.
- Reverted unverified/redundant/runtime-coupled additions: cloud-dev
session-read preview-URL claim + background-poll snippet + queued_count
precondition; publish transient-retry/ScheduleWakeup; env-pull first-launch;
db-dev-init positive restatement; SKILL terminal-URL mandate.
- Fixed dangling section references after the rename.
* fix(apps): scope pre-authorization to hands-off intent, not 'wants a result' (#36)
Follow-up to #35. The merged pre-authorization rule treated 'wanting the
final result' as authorization, so '先在本地跑起来让我看看' was read as
pre-authorized and the agent silently picked a clone directory without
asking. Re-state the criterion as the user's hands-off intent (explicit
waiver, or an end-to-end directive), judged uniformly across the flow
(directory/clone, publish) — not a per-decision carve-out. Merely wanting
a result or asking to review is not authorization.
* docs: clarify apps cloud dev publish state
* fix(apps): require commit+push before publish, clarify deploy flow (#38)
* fix(apps): require committing changes before publish in local-dev flow
* fix(apps): make commit+push mandatory before publish in agent rules
* fix(apps): scope selective-add caveat to incremental deploy, not new-app flow
* fix(apps): make pre-publish commit conditional on local changes
* fix(apps): tighten pre-publish commit wording in agent rules
* fix(apps): cloud-dev does not auto-deploy, add explicit publish step
* docs(apps): document +chat init vs incremental turn cost (#39)
First +chat on a not-initialized app runs full design+gen server-side
(~20-50 min); chat on an already-initialized app is incremental and
finishes in minutes. Surface this in the +chat Go comment as a pointer
and put the init-state check + matching polling cadence (5-10s vs
60-120s) in the lark-apps cloud-dev skill reference as the canonical
source. Cloud-side init check uses +session-read committed-version
info or +list is_published:true.
* docs(apps): document +chat init vs incremental turn cost (#40)
First +chat on a not-initialized app runs full design+gen server-side
(~20-50 min); chat on an already-initialized app is incremental and
finishes in minutes. Surface this in the +chat Go comment as a pointer
and put the init-state check + matching polling cadence (5-10s vs
60-120s) in the lark-apps cloud-dev skill reference as the canonical
source. Cloud-side init check uses +session-read committed-version
info or +list is_published:true.
* feat(apps): surface online_url/error_logs in +publish-status output (#41)
* refactor(apps): extract shared release error-log table helper
* fix(apps): keep error-log table byte-identical for null error_logs
* feat(apps): surface online_url/error_logs in +publish-status output
* docs(apps): read online_url/error_logs from +publish-status in publish flow
* docs(apps): align local/cloud dev publish flow with +publish-status fields
* refactor(apps): rename +db-dev-init→+db-env-create, trim db-table-list columns
- +db-env-create（原 +db-dev-init）：新增 --env 参数（调用方传入，目前只支持 dev），
--sync-data 改为 true/false 取值；服务端 URL 仍走 db_dev_init。
- +db-table-list：json 默认用白名单投影（dbTableListItem）只输出产品要求字段，
每表 columns[] 折算成 column_count、不再透出完整列定义（与 +db-table-schema 重复且放大
token）；要完整列定义/索引/约束用 +db-table-schema。
- 同步对齐 db 相关 skill 文档（命令名、column_count、env-create 参数）。
- 单测 + cli_e2e dry-run 全绿。
Change-Id: I116ab11807679f8f06ed18221f705bab426d015c
* refactor(apps): rename +db-table-schema → +db-table-get
动词对齐 +db-table-list（list/get）。仅命令名 + 标识符 + 文档改名，行为/输出/URL 不变：
- AppsDBTableSchema→AppsDBTableGet，文件/测试/cli_e2e test 重命名
- buildDBTableSchemaParams→buildDBTableGetParams
- +db-sql / +db-table-list 里的交叉引用 hint、skill 文档同步
Change-Id: I36dfb8fd0d2613492a57dc7815bc58414c145480
* feat: auto-pull env vars after apps +init (#42)
* test: route apps +env-pull to its own fake-runner key
* feat(apps): add +env-pull envelope parsers for +init
* feat(apps): add pullEnv helper invoking sibling +env-pull
* feat(apps): +init auto-runs +env-pull after push (non-fatal)
* docs(apps): clarify db-sql --query @path is relative-only, use stdin for absolute paths
@path 受 lark-cli 全局文件安全策略约束，只接受 cwd 内相对路径；绝对路径 / cwd 不固定
场景改用 stdin（--query - < /abs/file.sql），无需先 cd。
Change-Id: Ib3453810cfc9303d72b4facf3493ad9688eeffd3
* docs(apps): refine db-sql --query path guidance wording
以 agent 视角重写：@ 仅接受工作目录内相对路径，绝对路径/越界路径被拒（CLI 文件访问统一约束）；
工作目录外的文件经 stdin 传入。
Change-Id: Ic7db00934b3571368eb704451f4ce1776463806d
* feat(apps): make +db-sql high-risk-write (require --yes)
+db-sql 可含 DML/DDL，统一升级为 high-risk-write：框架对所有执行强制 --yes 确认关卡
（--dry-run 预览豁免），无 --yes 返 confirmation_required / exit 10。
- Risk: write → high-risk-write（去掉自定义门禁，直接用框架机制）
- skill 文档：命令骨架标注 --yes 要求；Agent 规则改为「执行需 --yes，只读可直接带、
破坏性先 dry-run 确认再带」
- 单测所有执行调用补 --yes
Change-Id: I57e78832b35fa170a485774e6fb7289109d678c3
* docs(apps): clarify app_ (Miaoda) vs cli_ (Feishu) app id (#46)
* 优化云端开发skill，明确执行模型，参数解释 (#44)
Co-authored-by: fushengdong.1 <fushengdong.1@bytedance.com>
* refactor: rename apps publish commands to release and session-get (#45)
* refactor(apps): drop +publish-error-log, rename release path constants
* refactor(apps): rename +publish to +release-create
* refactor(apps): rename +publish-history to +release-list, unify pagination to --page-size
* refactor(apps): rename +publish-status to +release-get
Renames apps +publish-status → +release-get (AppsPublishStatus → AppsReleaseGet),
updates --release-id desc to reference +release-create, and fixes the Execute
error hint to point at +release-list instead of +publish-history.
* refactor(apps): rename +session-read to +session-get
* docs(apps): rename publish references to release, +session-read to +session-get
* refactor(apps): clean up residual publish/session-read references
Fix six leftover references missed in Tasks 1-6: +publish-history in
jq-tip test wantCmds map and common_test hint fixture (×3), +session-read
in apps_chat.go comment+output string (×2), apps_session_stop.go flag
desc (×1), apps_chat_test.go comment (×1), and +publish-status in
lark-apps-list.md agent rule prose (×1).
* docs(apps): clarify release-get link contract and session-get vs session-list
* docs(apps): generalize release-list page-size rule to N records
* feat(apps): rename +list --scope flag to --ownership (#47)
* feat(apps): rename +list --scope flag to --ownership
* test(apps): update +list cli_e2e dry-run for --ownership rename
* docs(apps): document +list --ownership flag
* feat(apps): align +release commands with new release API format (#48)
* feat(apps): align +release-create scope to spark:app:write
* feat(apps): raise +release-list --page-size documented max to 500
* feat(apps): show commit_id in +release-get pretty output
* docs(apps): update release reference docs for page-size 500 and commit_id
* test(apps): cover empty commit_id in +release-get pretty output
* docs: align lark apps cloud dev release flow
* feat(apps): redesign +db-sql → +db-execute (--sql/--file, default env dev)
按 db 子域命令最终设计重做执行入口：
- 命令 +db-sql → +db-execute（动词收尾，对齐 +db-table-list/-get）
- --query 拆为 --sql（内联/stdin）与 --file（.sql 文件路径），二选一互斥；
--file 在 Validate 阶段读出归一化到 --sql
- 默认 --env online → dev（打生产库需显式 --env online）
- 文件/标识符/注册/测试/cli_e2e/skill 文档全部对齐重命名
- 新增测试：--sql/--file 互斥、--file 读取、默认 env=dev
不在本次范围：--transaction/--no-transaction（服务端 transactional 实为路径切换、
非真事务，需 dataloom 侧先支持真事务开关）、--max-rows/--timeout 等后续项。
Change-Id: I50c06faf83527471446e2a6651ccb51f6eedd6ff
* docs(apps): clearer --env online wording for +db-execute
把口语化的「打生产库需显式」改为「需要操作线上环境数据库时，显式指定 --env online」；
flag desc 同步去掉 hit production 措辞。
Change-Id: Iee82fccf17e08bddb4b760c3970a416746b10c4c
* docs(apps): drop 'ad-hoc' jargon from +db-execute description
中文文档/英文 description 去掉术语 ad-hoc；SELECT/DML/DDL 已表意，含义不丢。
Change-Id: Ie2cccc5fc3491fe5f57190a87b93ecd70405b156
* docs(apps): trim +db-execute when-to-use and --file path wording
- 何时用去掉「（查询 / 临时数据修复 / 应急 DDL）」枚举
- --file 路径说明去掉 .. /符号链接/统一约束 的技术化描述，改为「相对路径，
否则用 --sql - < 文件路径」的产品化口吻
Change-Id: Ie70e57895c78650230b6942b03d90a2d95c937f2
* docs(apps): note --file rejects absolute/cwd-escaping paths
简短补回 --file 的路径约束（绝对路径 / 经 ..、符号链接越界会被拒），去掉冗余评注。
Change-Id: I549893c82cafbe97529e08dcbc3ee5496927da18
* fix(apps): replace t.Chdir with os.Chdir in db-execute test (Go 1.23 compat)
t.Chdir 是 Go 1.24 API，但 go.mod 为 go 1.23.0，CI（Go 1.23）报
"t.Chdir undefined"。改用 os.Chdir + t.Cleanup 还原，1.23 兼容。
Change-Id: I550611773e5088275be1c4344d4f8269610ce74a
* feat(apps): refine +init description and refresh env on re-init
* fix(apps): treat accessible-link requests as publish intent (#53)
* refactor(apps): +db-env-create --sync-data string-enum → Type:bool
原实现用 string + Enum["true","false"] + == "true" 模拟 bool，啰嗦且非惯用。
改为 Type:bool（rctx.Bool）：传 --sync-data 即开启、省略为 false。
同步更新测试、cli_e2e dry-run、skill 文档。
Change-Id: I3068e0577fa20a7cbaf414ca9af3d197f6ae8049
* fix(apps): declare --app-type as strict lowercase enum (#55)
* docs(apps): front-load routing, dedupe, and trim lark-apps skill (#56)
* docs(apps): front-load intent-routing table and dedupe skill body
* docs(apps): dedupe publish guardrail and polling rules in cloud-dev
* docs(apps): trim env-pull implementation detail to behavior contract
* docs(apps): add +env-pull routing entry in SKILL.md
* docs(apps): fix create.md cross-ref to actual SKILL.md section name
* feat(apps): add error.hint to command failures and a consistency gate (#57)
* feat(apps): add appIDListHint const and wrap 4 pure app-id command failure paths
Adds shared `appIDListHint` recovery hint to common.go and wraps the
CallAPITyped failure branch of session-create, session-list, update, and
release-list to surface an actionable next-step hint on 4xx errors.
Includes httpmock unit tests in apps_hints_more_test.go (TDD: red→green).
* feat(apps): add sessionStopHint and createHint for session-stop and create commands
Adds per-command recovery hints with specific guidance: sessionStopHint
points at +session-list and +session-get; createHint explains valid
--app-type values and permission failure. Wraps the CallAPITyped failure
branch in both commands.
* feat(apps): add recovery hints for db-env-create, db-table-get, db-table-list
Adds dbEnvCreateHint, dbTableGetHint, and dbTableListHint with actionable
cross-command guidance (e.g. pointing at +db-table-list for env conflicts,
+db-env-create for missing dev env). Wraps only the CallAPITyped failure
branch; requireAppID validation errors are left untouched.
* refactor(apps): make session-stop hint runnable and align hint test names
* test(apps): guard withAppsHint upstream-wins contract and new hint leak safety
* test(apps): add help-skill command consistency gate
---------
Co-authored-by: linchao5102 <linchao.5102@bytedance.com>
Co-authored-by: Wang <wangjiangwen@bytedance.com>
Co-authored-by: wangjiangwen-gif <286006750+wangjiangwen-gif@users.noreply.github.com>
Co-authored-by: 陈兴炀 <chenxingyang.1019@bytedance.com>
Co-authored-by: aihao-git <aihao.0331@bytedance.com>
Co-authored-by: bali <bali@bytedance.com>
Co-authored-by: hunnnnngry <chenxi.xichen@bytedance.com>
Co-authored-by: shengdongyc <1135978761fsd@gmail.com>
Co-authored-by: fushengdong.1 <fushengdong.1@bytedance.com>
Block 1 — field completion: audio renders <audio key="..." duration="Xs"/>
(falls back to [Voice: Xs]/[Voice]); post renders emotion -> :emoji_type:,
applies text.style (bold/italic/underline/lineThrough), passes through md;
sticker unchanged.
Block 2 — opt-in --download-resources (default off) on +chat-messages-list,
+messages-mget, +threads-messages-list: extract downloadable resource refs
during formatting (image/file/audio/video/media + post-embedded; sticker
excluded; merge_forward sub-items carry the top-level container message_id,
since the resources endpoint rejects sub-item ids with "234003 File not in
msg" and can only fetch a forwarded resource through the container; thread
replies get their own block), then download each distinct (message_id,
file_key) once into ./lark-im-resources/ with bounded concurrency (3), filling
back local_path/size_bytes; single-resource failures are isolated (error:true +
stderr warning). Path safety reuses normalizeDownloadOutputPath +
ResolveSavePath.
Batch download keys each file on disk by its unique file_key basename and only
appends an extension (from the Content-Disposition filename or MIME type) —
it does NOT substitute the server's Content-Disposition filename. Otherwise two
resources whose servers return the same filename (e.g. download.bin) would
resolve to the same ./lark-im-resources/ path and clobber each other
concurrently. The friendly "adopt the server filename" behavior is kept only
for an explicit +messages-resources-download with no --output.
Resource ref extraction guards against self-referential / cyclic merge_forward
prefetch maps (a real API sub-item list can include the container's own id or a
back-pointing merge_forward) via a visited set, so extraction terminates instead
of overflowing the stack. The container message_id is threaded through nested
merge_forwards as the download owner.
Also: document the feature (including the im:message:readonly scope requirement)
in skills/lark-im — SKILL.md is generated from skill-template/domains/im.md
(edit the source), plus the hand-written message-enrichment + 3 command
references.
Change-Id: I3a71d7d1b193130f551aaa2ec180ac1500d59ac4
Meego: https://meego.larkoffice.com/5e96d7bff4e7c525510f9156/story/detail/7331555925
Replace every command-facing error path in the event domain — the
consume/schema command layer, the +subscribe shortcut, EventKey
definitions, and the consume orchestration — with typed errs.*
envelopes, so consumers get stable type, subtype, param, hint, and
missing_scopes metadata for classification and recovery instead of
free-form message text.
- Input validation (--jq, --param, --output-dir, --filter, --route,
unknown EventKey, EventKey params) reports validation /
invalid_argument with the offending flag in param and an actionable
hint.
- Scope preflight reports authorization / missing_scope with the
machine-readable missing_scopes list; console-subscription and
single-bus preconditions report failed_precondition with recovery
hints.
- The consume API boundary passes already-typed errors through and
classifies transport, non-JSON HTTP, and unparsable responses; the
vc note-detail retry now matches the not-found code on typed errors
(it silently never fired against the legacy envelope shape).
- Previously-bare failures exited 1 with a plain-text "Error:" line
and now exit with their category code (validation 2, auth 3,
network 4, internal 5) alongside the typed stderr envelope.
- forbidigo and errscontract guards now cover the event paths so
regressions fail lint; AGENTS.md and the lark-event skill document
the typed contract for agent consumers.
Validation: make unit-test (race) green; event unit and e2e suites
assert category/subtype/param/hint and cause preservation against the
real binary; errscontract and golangci lint clean.
Adds feed shortcut management to the im domain: pin chats to the user's feed sidebar, list pinned entries, and unpin them. Three new shortcuts wrap the im/v2/feed_shortcuts OpenAPI routes, which currently expose CHAT-type entries only and accept user identity only.
When triaging a public/shared mailbox, downstream AI consumers (e.g.
mail +message) need the mailbox_id to construct correct API paths.
Previously the triage output only included message_id, causing
/user_mailboxes/me/messages/{id} lookups that fail for public mailboxes.
- Add mailbox_id field to every normalized message in structured output
- Add mailbox_id to top-level JSON/data output envelope
- Add mailbox_id to table rows when mailbox is not "me"
- Update stderr next-step tip to include --mailbox for non-me mailboxes
- Update next-page hint to include --mailbox for non-me mailboxes
- Add unit tests covering list, search, and public mailbox paths
- Update triage skill docs to show mailbox_id in output examples
* feat(base): add base block shortcuts
* fix(base): use block scopes for base block shortcuts
* fix(base): split base block shortcut scopes
* docs(base): consolidate base block help
* docs(base): simplify block help wording
* test(base): cover base block shortcut execution
* feat(base): filter base block list by type
* docs(base): clarify base block ids
* docs(base): simplify docx block help
* docs(base): refine base block agent help
Drive-domain errors now leave the CLI as typed, machine-branchable
envelopes — a stable `type` plus `subtype` and named fields (param,
params, retryable, log_id, hint) — so scripts and AI agents can branch on
structure and act on a recovery hint instead of parsing prose.
Changes:
- Every error produced in the drive domain — validation, file I/O, and the
failures returned from its Lark API calls — is emitted as a typed errs.*
error; the exit code is derived from the error category. Drive's API calls
now go through a shared typed classifier, so failures carry subtype,
troubleshooter, a recovery hint, and the request's log_id whether the
server returns it in the response body or the x-tt-logid header; an
already-typed network/auth error is never downgraded into a generic API
error.
- Known API conditions (resource conflict, cross-tenant, cross-brand, ...)
carry a recovery hint keyed by their error class; a command can refine
that hint with command-specific guidance.
- Batch partial failures (+push / +pull / +sync, where some items succeed
and some fail) now report an honest ok:false multi-status result on
stdout — the summary and every per-item outcome stay machine-readable —
and exit non-zero, instead of a misleading ok:true success envelope.
- Duplicate rel_path conflicts report each colliding path as a structured
params entry (RFC 7807 invalid-params style).
- Static guards lock the drive path so legacy error construction — direct
envelopes or the auto-classifying API helpers — cannot be reintroduced,
making drive the template for the remaining domains.
Output changes worth noting for consumers:
- Error envelopes now carry typed type/subtype and named fields; exit
codes follow the error category (malformed or incomplete API responses
are reported as internal errors rather than generic API errors).
- Batch partial failures (+push / +pull / +sync) emit an ok:false result
envelope on stdout (summary + per-item items[]) and exit non-zero; the
per-item results stay on stdout rather than in a stderr error envelope.
Errors surfaced through shared cross-domain helpers (scope precheck, media
import upload, metadata lookup, save-path resolution) are not yet typed;
they migrate with the shared layer in a follow-up change.
Every failure on the authentication, authorization, and configuration
path now surfaces as a typed structured error instead of an ad-hoc
envelope. Users and scripts that consume CLI output get:
- a fixed nine-category taxonomy on the wire, each mapped to a
stable shell exit code (authentication/authorization/config = 3,
network = 4, internal = 5, policy = 6, confirmation = 10)
- identity-aware detail fields (missing_scopes, requested_scopes,
granted_scopes, console_url, log_id, retryable, hint) carried
uniformly on the envelope
- a single canonical policy envelope at exit 6; the legacy
auth_error carve-out is retired
- per-subtype canonical message + hint that preserves Lark's
diagnostic phrasing and routes recovery to the right actor:
app developer (app_scope_not_applied), user (missing_scope,
token_scope_insufficient, user_unauthorized), or tenant admin
(app_unavailable, app_disabled)
- wrong app credentials classify as config/invalid_client whether
surfaced by the Open API endpoint (99991543) or the tenant
access-token mint endpoint (10003 / 10014), instead of
collapsing to a transport error or api/unknown
- local shortcut scope preflight emits the same
authorization/missing_scope envelope (identity + deterministic
missing-scope set) used by the post-call permission path, so AI
consumers read the same structured shape from precheck and from
server-returned permission denial
- streaming download/upload failures keep the same network subtype
split (timeout / TLS / DNS / transport) as the non-stream path
instead of collapsing every cause to a generic transport failure
- console_url is carried only on the bot-perspective
app_scope_not_applied envelope (where the recovery action is
"developer applies the scope at the developer console"); the
user-perspective missing_scope envelope drops the field, since
the only actionable user recovery is `lark-cli auth login --scope`
and pointing an end user at a console they cannot modify is
misleading
- bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic
Type tags to wire 'config' with the original module name kept
as a metric label
All 10 typed errors are cause-bearing, nil-safe on .Error() and
.Unwrap(), and defensively clone slice setter inputs. Four lint
rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry
/ CheckBuildAPIErrorArms) lock these invariants on migrated paths.
Add `lark-cli mail +draft-send` shortcut that takes one or more existing
draft IDs and sends each via POST /drafts/:draft_id/send sequentially.
Per-draft failures are isolated and aggregated into a structured output;
fatal failures (auth, permission, network, mailbox quota) abort the
entire batch immediately while recoverable failures honor --stop-on-error.
Also extend internal/output with six mail-send-specific errno constants
(LarkErrMailboxNotFound=4013, LarkErrMailSendQuota{User,UserExt,TenantExt},
LarkErrMailQuota, LarkErrTenantStorageLimit) consumed by isFatalSendErr.
Risk is "high-risk-write" so the framework's --yes gate applies; the
shortcut declares only the minimal mail:user_mailbox.message:send scope
to avoid asking users for permissions it does not need.
Introduce a typed error contract framework for lark-cli so in-process
Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts,
AI agents, and protocol adapters can branch on stable JSON type/subtype
fields instead of regex-parsing free-form messages.
Adds:
- Canonical taxonomy under errs/ (9 categories + typed Error structs
embedding a shared Problem, RFC 7807-aligned)
- Centralized Lark code metadata + identity-aware BuildAPIError dispatch
- Typed JSON envelope writer alongside the legacy envelope writer
- MCP / OAuth (RFC 6750 Bearer) projection adapters
- Five CI lint guards preventing ad-hoc taxonomy drift
Backward compatibility: legacy *output.ExitError producers (ErrAPI,
ErrWithHint, Errorf, ErrBare) and business shortcuts that use them
continue to render the legacy envelope unchanged. SecurityPolicyError
wire format and exit code are preserved via a carve-out; taxonomy
migration is deferred to PR 2. Domain-specific business migration is
staged across PR 3+.
Framework-direct paths now return typed *errs.*Error: ErrAuth /
ErrValidation / ErrNetwork emit category literals on the wire
(authentication / validation / network), *core.ConfigError is promoted
at the cmd/root boundary with exit code aligned from 2 to 3, and Lark
API permission denials classified by BuildAPIError exit 3.
At the SDK boundary, WrapDoAPIError preserves any already-classified
error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth
from missing credentials surfaces with the auth category and exit 3
intact instead of being downgraded to a network error. Policy responses
classified by BuildAPIError (codes 21000 / 21001) extract challenge_url
and the canonical hint from the response body, matching what the
auth transport already surfaces at the HTTP layer; non-https
challenge URLs are dropped.
First PR in the feat/error-contract-* series.
* feat(apps): replace +html-publish cwd hard-reject with credential-file scan
The previous --path == "." block was a coarse heuristic: it caught the
common foot-gun of publishing a repo root, but also rejected legitimate
clean cwds, and let a ./dist with a forgotten .env ship the secret
through anyway (the sensitive-paths scanner was advisory and never ran
on the Execute path).
Move the gate from path shape to path content:
- Validate now walks --path candidates and rejects publishes that
include well-known credential files (.env / .env.* / .npmrc / .netrc
/ .git-credentials / .aws/credentials / .gcloud/credentials* /
.docker/config.json / .kube/config). Living in Validate (not DryRun)
means dry-run returns non-zero on hit too, so the dry-run preview
matches Execute.
- Narrow the credential pattern set. .git/, SSH private keys, *.pem
and *.key are out of scope -- they're not env-token files and the
false-positive rate (public certs, docs about key formats) is high.
- Add --allow-sensitive as the escape hatch for legitimate cases
(e.g. a docs site shipping .env.example on purpose). DryRun surfaces
the waived list in sensitive_waived so the caller can relay it.
- Drop the cwd defense-in-depth in runHTMLPublish. A clean cwd is now
a valid publish target.
The lark-apps skill and the html-publish reference are updated to
describe the new gate, the override flag, and the patterns now
explicitly out of scope.
* feat(apps): drop .gcloud/* from credential-file scan
The .gcloud/credentials pattern matched a non-existent path: gcloud's
actual config dir is ~/.config/gcloud/ (XDG-based), and the real
credential files there are credentials.db / access_tokens.db /
application_default_credentials.json -- none of which would land under
a .gcloud/ segment in a publish payload.
Drop the rule rather than fix it: the realistic gcloud foot-gun would
require recognizing the .config/gcloud/* tree by file basename, which
is a broader change than the targeted env/cred scan in this PR. The
remaining 7 patterns (.env / .env.* / .npmrc / .netrc /
.git-credentials / .aws/credentials / .docker/config.json /
.kube/config) cover the common Node/Python/CLI-tooling foot-guns.
* fix(apps): close credential-scan bypass when --path is the parent dir itself
isSensitiveRelPath anchors cloud-SDK matchers on adjacent parent/file
segments (.aws/credentials, .docker/config.json, .kube/config), but
walker strips that parent via filepath.Rel when --path is the conventional
parent dir (e.g. ./.aws), yielding a bare RelPath="credentials" that
slipped through silently. Same bypass for the single-file form
--path ./.aws/credentials (walker sets RelPath = Base(rootPath)).
Wrap the scan in isSensitiveCandidate: keep the fast RelPath scan, and
on miss fall back to filepath.Abs(AbsPath) so the parent segment is
visible again. isSensitiveRelPath itself is unchanged; existing tests
still pin its pure-function contract.
* fix(apps): drop filepath.Abs from sensitive scan to satisfy forbidigo lint
The previous fix called filepath.Abs(c.AbsPath) — banned by the repo's
forbidigo rule because shortcuts must not reach into the filesystem for
path resolution.
Reframe the same fix without fs access: re-prepend the root's basename
(or, for the single-file form, the parent dir's basename of rootPath)
to RelPath and re-scan only the parent-anchored credential pairs
(.aws/credentials, .docker/config.json, .kube/config). Leaf matchers
(.env / .npmrc / ...) stay scoped to RelPath — incidentally closing a
latent false-positive where --path /home/alice/.env/dist would have
flagged every file under it just because .env appeared in the
absolute path.
When creating wiki nodes under the same parent concurrently, the API
returns error code 131009 (lock contention) ~5-15% of the time. This
adds automatic retry with exponential backoff (250ms, 500ms; max 2
retries) so callers no longer need to implement retry logic themselves.
- Retry loop in runWikiNodeCreate: only retries on code 131009, respects
context cancellation, prints progress to stderr
- wrapWikiNodeCreateRetryError preserves Err/Raw/Detail.Code in ExitError
- 6 unit tests covering retry success, exhaustion, non-contention error,
single-retry success, context cancellation, no-retry on success
- 8 dry-run E2E tests for wiki +node-create request shape and validation
Switch `drive +export --file-extension markdown` from the legacy V1
GET /open-apis/docs/v1/content API to the V2
POST /open-apis/docs_ai/v1/documents/{token}/fetch API for
higher-quality Lark-flavored Markdown output.
- Update DryRun and Execute paths to use V2 endpoint with JSON body
- Add docx:document:readonly scope for the new API
- Validate V2 response structure (fail fast on missing document/content)
- Encode token in URL path via validate.EncodePathSegment
- Update unit tests and add V2 response validation error path tests
- Add E2E dry-run test for markdown export path
- Update skill documentation
* feat(drive): add +inspect shortcut for document URL inspection with wiki unwrapping
Implements #662: `lark-cli drive +inspect --url <url>` inspects any
Lark/Feishu document URL to get its type, title, and canonical token,
with automatic wiki URL unwrapping via get_node API.
- Add ParseResourceURL (inverse of BuildResourceURL) in common
- Extract FetchDriveMetaTitle as public shared helper
- Add drive +inspect shortcut with wiki unwrapping support
- Add skill reference docs and update SKILL.md
- Dry-run E2E tests for docx URL, wiki URL, and bare token
* refactor: move host validation from ParseResourceURL to +inspect
ParseResourceURL is a general-purpose URL parser that should not
hardcode domain lists — future Lark domains would silently break.
Move isLarkHost/larkHostSuffixes to drive_inspect.go where host
validation is a business decision of the +inspect command.
Add E2E test for non-Lark host with Lark-like path.
* refactor: remove host validation from +inspect
Lark supports custom enterprise domains, so a hardcoded suffix list
can never be exhaustive and would falsely reject valid URLs.
Path-based matching in ParseResourceURL is sufficient; invalid URLs
will fail naturally at the API call stage.
Bidirectional sync between a local directory and a Drive folder with
diff detection (new_local, new_remote, modified, unchanged) and
conflict resolution strategies (--on-conflict: remote-wins, local-wins,
keep-both, ask).
Key behaviors:
- Type conflict detection: hard-fail when local file vs remote non-file
or local directory vs remote file
- Keep-both: rename local with __lark_<hash> suffix, then pull remote;
occupied map includes localDirs to prevent suffix collision
- Local-wins partial-success: prefer returned file_token on upload failure
- Empty directory mirroring: pre-create local dirs on Drive via
drivePushWalkLocal before scope preflight
- Structured errors throughout (output.Errorf / output.ErrWithHint)
Includes unit tests and E2E tests (dry-run + live workflow).
* fix(drive): preserve parent token on nested overwrite
Ensure drive +push overwrite requests for nested files keep parent_node aligned with the actual remote parent folder and report parent resolution failures explicitly.
* test(drive): cover nested overwrite push workflow
Add a live drive +push workflow case for overwriting a nested remote file so the PR parent-token fix is exercised against the real backend and verified to converge via +status.
Introduce three new wiki shortcuts that wrap the corresponding raw APIs
with structured flags, formatted output, my_library alias handling, and
unified envelope shape, replacing the bare `lark-cli wiki spaces list`
/ `wiki nodes list` / `wiki nodes copy` flows for the common cases.
Shortcuts
- wiki +space-list (read, scopes: wiki:space:retrieve):
lists wiki spaces. Default fetches a single page; --page-all walks
every page capped by --page-limit (default 10, 0 = unlimited).
Supports --page-size / --page-token / --format json|pretty|table|csv|ndjson.
Output: {spaces, has_more, page_token} + Meta.Count. Pretty mode
distinguishes "no spaces" from "empty page with has_more" and hints
the caller to resume.
- wiki +node-list (read, scopes: wiki:node:retrieve):
lists nodes in a space or under a parent. Same pagination + format
story as +space-list. Accepts the my_library alias for --space-id
with --as user (resolved via a shared resolveMyLibrarySpaceID helper
extracted from +node-create); rejects my_library upfront for --as bot.
- wiki +node-copy (high-risk-write, scopes: wiki:node:copy):
copies a node into a target space or parent. --target-space-id and
--target-parent-node-token are mutually exclusive. Risk is marked
high-risk-write to match the upstream API's danger: true flag, so the
framework requires --yes. Source is preserved; subtree is copied.
Both list shortcuts pick the narrowest scope the upstream API accepts.
The framework's preflight (internal/auth/scope.go MissingScopes) does
exact-string scope matching, so declaring the broader wiki:wiki:readonly
form would wrongly reject tokens that carry only the per-API scope —
which the API itself accepts — and emit a misleading missing-scope hint.
Shared changes
- shortcuts/wiki/wiki_node_create.go: factor out resolveMyLibrarySpaceID
so +node-list and +node-create share one my_library resolution path.
- shortcuts/wiki/shortcuts.go: register the three new shortcuts.
- skills/lark-wiki/SKILL.md and references/lark-wiki-{space,node-list,
node-copy}.md: documentation for the new shortcuts.
Tooling
- scripts/check-doc-tokens.sh + Makefile gitleaks target:
pre-commit check that scans skill reference docs for realistic-looking
Lark token values without the _EXAMPLE_TOKEN placeholder convention,
preventing gitleaks false positives.
- .gitleaks.toml: allowlist tuning.
- .gitignore: ignore .tmp/.
Tests
- shortcuts/wiki/wiki_list_copy_test.go: unit tests covering registry
membership, declared-narrow-scope pinning, flag validation (page-size
range, page-limit >= 0, target flag exclusivity, my_library + bot
rejection), auto-pagination merging, --page-limit truncation
surfacing next cursor, --page-token single-page mode, empty-slice
serialisation, has_more hint pretty rendering, my_library user-path
resolution, +node-copy copy-to-space / copy-to-parent + body shape,
pretty rendering, and the high-risk-write --yes gate.
- tests/cli_e2e/wiki/wiki_shortcut_workflow_test.go: live end-to-end
workflow exercising the shortcut layer against a real tenant.
Reuses an existing my_library node as a host so the test never adds
to the top-layer quota; the copy is placed under the same host node.
- tests/cli_e2e/wiki/coverage.md: shortcut coverage entries added.
Minor cleanups
- skills/lark-doc/references/lark-doc-search.md and
skills/lark-minutes/references/lark-minutes-search.md: replace
realistic-looking example ou_ tokens with _EXAMPLE_ placeholders so
scripts/check-doc-tokens.sh passes.
Change-Id: I9efb0557f477d369d7f26a09c1e154d4ab15b253
Co-authored-by: liujinkun <liujinkun@bytedance.com>
