feat: add citation framework for read-command envelopes

[chenjinxiong03-bit]

Summary

AI-agent hosts need read commands to return uniform citation entries so rendered answers can link back to their sources. This PR adds a framework-level citation capability: a citations array on the top-level JSON success envelope, gated by the LARKSUITE_CLI_CITATION=1 environment variable (default off, byte-identical output when off), with declaration entry points for both the legacy and typed shortcut paths and two pilot commands. Stacked on feat/typed-shortcut-help-integration (the typed path integrates with common.Define).

Changes

• Add internal/citation domain package: Citation wire type, SourceType enum, exact-match Enabled() gate, Normalize() (drops URL-less entries), and Time() RFC3339 normalization with explicit offsets
• Register LARKSUITE_CLI_CITATION in internal/envvars/envvars.go
• Carry lazy citations on the success envelope: Envelope.Citations + EmitOptions.Citations closure invoked only inside emitEnvelope (internal/output/envelope.go, internal/output/emitter.go); table/csv/ndjson/pretty/stream paths structurally never build citations
• Add shared declaration and runtime validation in shortcuts/common/citation.go: CitationDefinition, registration-time checks (explicit read risk, allocated source types), per-entry runtime validation (declared source type, absolute https URL) with drop-and-warn semantics that never fail the command
• Wire the legacy path: Shortcut.Citation declaration, citationProvider on Out/OutRaw/OutFormat/OutFormatRaw, mount-time panic on invalid declarations (shortcuts/common/types.go, shortcuts/common/runner.go)
• Wire the typed path: Output.Citation + Hooks.BuildCitation, compile-time checks inside Define, lazy closure threaded through emitTypedResult, and a _meta.citation schema projection (shortcuts/common/typed_*.go)
• Pilot commands: wiki +node-get (typed, applink URL built from the brand endpoint resolver) and im +chat-messages-list (legacy, per-message citations; also exposes the resolved chat_id in data as a generally useful additive key)
• Guard test banning int literal source types under shortcuts/ (internal/citation/literal_guard_test.go)

Test Plan

• build, go vet, and unit tests passed (go test ./cmd/... ./internal/... ./shortcuts/...)
• gate-off byte-identical output covered by contract tests; non-envelope formats proven lazy via panic-probe tests
• skipped: integration suite has one failure in tests/plugin_e2e (TestConcealedForkProjectsRetainedSchemaCatalog) that reproduces identically on the base branch commit and is unrelated to this change
• containerized E2E suite passed (2/2 test functions covering 11 scenarios: gate on/off byte-identical data, per-message citations, table/jq/dry-run/page-all boundaries)
• offline acceptance checks passed (5/5 scenarios: gate independence, error paths, non-envelope formats, gate strictness, jq filtering)
• manual verification: LARKSUITE_CLI_CITATION=1 ./lark-cli wiki +node-get --node-token <token> --dry-run and --format table runs confirmed no citations and byte-identical data against the gate-off runs

Related Issues

N/A

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 92d9bbcd-07a9-4cbc-a255-d3007b08d0bb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}