Support auto-resolving the correct profile for read-only resource URLs

Summary

Named profiles are supported now, but users and AI agents still need to know which profile matches a given Lark/Feishu resource URL.

For users who work across multiple Feishu organizations, this is easy to get wrong: a Docs/Wiki URL may be readable by one configured profile, while the current default profile returns a permission error. In an AI agent workflow, the user usually provides only the URL, not the intended profile.

This is related to, but different from, #271. Named profiles solve manual switching; this issue is about resolving the correct profile for a specific read-only resource URL.

Problem

When multiple profiles exist locally, lark-cli currently behaves like this:

lark-cli docs +fetch --api-version v2 --doc "<wiki-url>"

If the current/default profile is wrong, the command returns errors such as:

No permission to operate on this document: the current user lacks view or edit access

or, when trying user identity:

need_user_authorization

However, another configured profile may already be able to read the same document successfully, for example:

lark-cli --profile org-b docs +fetch --api-version v2 --as bot --doc "<wiki-url>"

From the user's perspective, this looks like a document permission problem. The real issue is that the command used the wrong profile.

Reproduction scenario

Sanitized real-world setup:

• lark-cli version: 1.0.40
• Multiple profiles configured in ~/.lark-cli/config.json
• Profile org-a is the current/default profile
• Profile org-b has access to a Wiki document
• Running docs +fetch with the default profile returns permission denied
• Running the same command with --profile org-b --as bot succeeds

Expected behavior would be either:

• the CLI can auto-resolve the readable profile for read-only commands, or
• the permission error can point users toward profile mismatch diagnosis.

Proposed solution

1. Add read-only profile auto-resolution

Example:

lark-cli docs +fetch --api-version v2 --profile auto --doc "<feishu-doc-or-wiki-url>"

Behavior:

• Only enabled by default for read-only commands.
• Iterate configured profiles.
• Try eligible identities, such as bot and already-authorized user.
• Select the first profile/identity that can read the resource.
• Include the selected profile, appId, and identity in JSON output.
• Do not mutate existing profile config.
• Do not initiate OAuth automatically during auto-resolution.

2. Add an explicit resolver command

Example:

lark-cli profile resolve --url "<feishu-doc-or-wiki-url>" --service docs --format json

Possible output:

{
  "ok": true,
  "matches": [
    {
      "profile": "org-a",
      "identity": "bot",
      "status": "permission_denied"
    },
    {
      "profile": "org-a",
      "identity": "user",
      "status": "needs_user_authorization"
    },
    {
      "profile": "org-b",
      "identity": "bot",
      "status": "readable"
    }
  ],
  "recommended": {
    "profile": "org-b",
    "identity": "bot"
  }
}

3. Improve diagnostics on permission errors

If the current profile fails and other profiles are configured, the error could include a hint:

Current profile "org-a" cannot access this document.
Other profiles are configured. Try:
  lark-cli profile resolve --url "<url>" --service docs

If safe probing is available, the CLI could provide a stronger hint:

Profile "org-b" can read this document as bot.
Retry with:
  lark-cli --profile org-b docs +fetch ...

Safety constraints

• Auto-resolution should be read-only by default.
• Write commands should require an explicit profile, or require a separate confirmation flow.
• Auto-resolution should not silently trigger OAuth login.
• JSON output should expose the selected profile and identity so agents can reuse them for follow-up read operations.

Why this matters for AI agents

AI agents often receive a Docs/Wiki/Base URL from the user and need to read it immediately. They generally cannot infer the correct Feishu organization from the URL alone, especially when the same person has accounts in multiple organizations.

Without profile resolution, agents either:

• use the current default profile and fail,
• ask users to manually identify the organization,
• or brute-force profiles outside the CLI.

A first-class resolver would make multi-org agent workflows much more reliable.

Temporary workaround

I implemented a small local wrapper that:

• reads profiles from ~/.lark-cli/config.json
• tries docs +fetch --api-version v2 across profiles
• tries bot and user identities
• returns the first readable profile and identity

This works for the scenario above, but it would be better as a native CLI feature because the CLI owns profile metadata, identity state, command risk classification, and structured errors.

Start by tracing the existing docs +fetch command, profile handling, identity selection, and structured error output; the issue also identifies ~/.lark-cli/config.json as the profile source. Compare the proposed --profile auto behavior with the explicit profile resolve --url command and define how read-only probing, authorization status, JSON results, and write-command safeguards should work. Done means readable profiles can be reported without mutating configuration or triggering OAuth, with diagnostics for mismatches.