WeKnora/docs
qilifan 9afb8b7b68 feat(im,datasource): support Lark, Feishu's international edition
Lark and Feishu are the same product deployed on two isolated clouds
(open.larksuite.com and open.feishu.cn). WeKnora touches both from two
places — the IM bot and the Wiki data-source connector — and this brings
Lark to parity across both. Neither API surface differs, so rather than
duplicate either implementation, each is parametrized by a Region and
registered twice.

IM (internal/im/feishu):
  Every API call routes through a.api(), which prefixes the region's
  host, and the WebSocket client passes larkws.WithDomain — the SDK
  defaults to open.feishu.cn, so Lark long connections would otherwise
  fail to authenticate.

Data source (internal/datasource/connector/feishu):
  Lark was half-supported: the client honoured a base_url override and a
  LarkBaseURL constant existed, but the connector registered only as
  "feishu" and the UI never exposed base_url, so Lark wikis could not be
  configured at all. Lark is now its own connector type. base_url is kept
  as an explicit override so data sources that pointed a "feishu"
  connector at open.larksuite.com keep working.

Bugs found and fixed along the way:

- Wiki resource links were hardcoded to https://feishu.cn/wiki/{token} in
  four places, so a Lark wiki linked into the wrong cloud entirely.
- Bot identity is now platform-prefixed (feishu:cli_x vs lark:cli_x).
  BotIdentity carries a unique index, so without this a Lark channel
  would be rejected as a duplicate of an unrelated Feishu bot sharing an
  app_id.
- The card image cache is now keyed by app_id. image_keys are issued per
  app on one cloud; a Feishu key handed to a Lark app fails the card
  update with code=200570.
- The datasource doc claimed Lark "adapts automatically" — it could not,
  since the UI had no way to reach base_url.

Permissions are where the clouds genuinely diverge. Identical APIs do not
mean identical permission catalogues: aily:file:read, aily:file:write and
corehr:file:download exist on Feishu but not on Lark, so pasting Feishu's
scope JSON into Lark fails to import. That JSON is also over-broad (it
covers products WeKnora never calls) and simultaneously incomplete (it
omits the drive:*/docx:* scopes the connector needs). Lark therefore gets
its own list, derived from the 17 endpoints the code actually calls and
checked identifier-by-identifier against Lark's own API reference, plus a
full Feishu→Lark mapping table marking each scope verified, unverified,
or absent. Both features use tenant_access_token only — no user_access_
token exists anywhere in the repo — so the user dimension stays empty.

Known limitation: Region.ThinkingText makes Lark's initial card
placeholder English, but once streaming starts the think-block headers
come from the shared MarkdownThinkStyle and are Chinese on every platform
(Lark, Slack, Telegram, Mattermost alike). Fixing that means threading a
locale through FormatIMDisplayContent, which has no platform context — a
cross-platform change, not a Lark one. Documented as such.

The channel-creation 400 message is now derived from validIMPlatforms so
the list cannot drift as platforms are added.

Tests: region invariants and per-region URL construction on both sides,
the Feishu/Lark bot-identity split, platform-to-channel mapping, base_url
override precedence, an end-to-end SendReply against a fake Open Platform
(token fetch, reply, thread-unsupported fallback, hard-error surfacing),
and a ListResources drive asserting wiki links never leak the other
cloud's host.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-17 11:05:54 +08:00
..
api feat(storage): add storage backend management API and UI enhancements 2026-07-15 14:54:39 +08:00
cloud-image docs(cloud-image): add cloud-agnostic image packaging scripts 2026-05-11 12:25:19 +08:00
dev fix: validate vector store connection addresses against SSRF policy 2026-06-04 15:26:56 +08:00
images docs: release v0.6.3 notes and polish architecture diagram 2026-06-26 14:59:09 +08:00
wiki feat(im,datasource): support Lark, Feishu's international edition 2026-07-17 11:05:54 +08:00
zh refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
BUILTIN_MCP_SERVICES.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
BUILTIN_MODELS.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
CHUNKING.md fix(chunking): post-review polish — error surfacing + doc accuracy 2026-05-06 17:17:07 +08:00
IM集成开发文档.md feat(im,datasource): support Lark, Feishu's international edition 2026-07-17 11:05:54 +08:00
KnowledgeGraph.md docs: 更新多语言文档,新增知识图谱与MCP配置指南及目录结构 2025-11-19 16:56:49 +08:00
LITE.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
Langfuse集成.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
MCP功能使用说明.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
OIDC认证调用流程.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
QA.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
RBAC说明.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
ROADMAP.md feat(roadmap): update progress on document parsing and IM integration 2026-03-31 20:22:34 +08:00
agent-skills.md feat: adjust sandbox setting of agentConfig 2026-02-04 20:08:49 +08:00
docs.go feat(agent): enhance suggested questions API with tag scopes 2026-07-17 10:19:43 +08:00
embed-secure-mode.md feat(embed): add widget, visitor chat, and management UI (#1657) 2026-06-12 23:10:39 +08:00
embed-subdomain.md feat(embed): add widget, visitor chat, and management UI (#1657) 2026-06-12 23:10:39 +08:00
migration-troubleshooting.md feat(system-info): surface DB migration errors with troubleshooting links 2026-05-14 16:34:50 +08:00
swagger.json feat(agent): enhance suggested questions API with tag scopes 2026-07-17 10:19:43 +08:00
swagger.yaml feat(agent): enhance suggested questions API with tag scopes 2026-07-17 10:19:43 +08:00
worker-pool-governance.md feat(worker): replace aggregate asynq concurrency with per-pool governance 2026-07-13 15:51:06 +08:00
使用其他向量数据库.md feat(retriever): configure Tencent VectorDB replicas via env 2026-06-22 20:21:25 +08:00
共享空间说明.md refactor(terminology): rename user-facing tenant labels to workspace 2026-07-14 16:14:43 +08:00
开发指南.md fix: update dev script checks and Air docs 2026-07-01 11:52:42 +08:00
开启知识图谱功能.md feat: Update VLM configuration in knowledge base and API documentation 2025-11-20 20:08:24 +08:00
快速开发模式说明.md docs: update Air installation command from cosmtrek/air to air-verse/air 2026-02-04 19:27:44 +08:00
数据源导入开发文档.md feat(im,datasource): support Lark, Feishu's international edition 2026-07-17 11:05:54 +08:00
日志配置.md refactor(logger): support LOG_FORMAT template and harden level coloring 2026-05-22 20:31:54 +08:00
添加新的网络搜索引擎.md feat(web-search): refactor web search provider 2026-03-31 20:22:34 +08:00