2026-08-06 10:22:10 +00:00
|
|
|
|
# API 参考:IM、Embed 与文件服务
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
管理 IM 和网页嵌入渠道,并提供渠道回调、访客会话与文件访问接口。管理端、IM 平台回调和 Embed 访客使用各自的认证方式。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
## IM 回调(免全局认证)
|
|
|
|
|
|
|
|
|
|
|
|
### GET|POST /api/v1/im/callback/:channel_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:IM 平台(WeChat/Feishu/Slack/Telegram/DingTalk/QQBot/云之家等)事件回调与 URL 验证。注册在认证中间件之前,使用各平台自身的签名验证;验签失败 403,渠道不存在 404。收到消息立即 ACK,异步处理。Handler: `internal/handler/im.go`
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}` 或平台要求的 ACK 格式。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/im/callback/ch-1 -H 'Content-Type: application/json' -d '{"event":"..."}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## IM 渠道管理(需认证)
|
|
|
|
|
|
|
|
|
|
|
|
API key:`manage_channels`/full。IM 渠道携带外部 bot 凭证:列表 Viewer+,变更/开关/扫码登录 Admin+。
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
飞书/Lark credentials.api_base_url 同时影响 HTTP API 和 WebSocket bootstrap;云之家支持 session_mode=thread。配置示例及网络要求见[IM 集成](../03-features/12-im-integration.md)。IM/Embed 的记忆偏好来自绑定 Agent 的 config.memory_enabled,当前渠道接口没有单独的 memory_enabled 参数。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### POST /api/v1/agents/:id/im-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:为 Agent 创建 IM 渠道。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `platform` | string | 是 | `wecom/feishu/lark/slack/telegram/dingtalk/mattermost/wechat/qqbot/yunzhijia` |
|
|
|
|
|
|
| `name` | string | 否 | 显示名 |
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
| `mode` | string | 否 | `websocket`(默认;mattermost/yunzhijia 默认 `webhook`)/`webhook`/`longpoll`(wechat 强制 longpoll) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `output_mode` | string | 否 | `stream`(默认)/`full`(wechat 强制 full) |
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
| `locale` | string | 否 | 回复语言:`zh-CN`/`en-US`/`ja-JP`/`ko-KR`/`ru-RU`;空(默认)使用部署默认语言(`WEKNORA_LANGUAGE`,未设置为 `zh-CN`);其他值 400 |
|
|
|
|
|
|
| `session_mode` | string | 否 | `user`(默认)/`thread` |
|
|
|
|
|
|
| `knowledge_base_id` | string | 否 | 附件额外入库的 KB,须属于本空间,否则 400 |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `credentials` | object | 否 | 平台凭证 |
|
|
|
|
|
|
| `enabled` | bool | 否 | 默认 true |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":{IMChannel}}`;同渠道 bot 已存在返回 409。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/agents/agent-1/im-channels -H "Authorization: Bearer $TOKEN" \
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
-H 'Content-Type: application/json' -d '{"platform":"feishu","name":"飞书客服","locale":"en-US"}'
|
2026-08-06 10:22:10 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/agents/:id/im-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:某 Agent 的 IM 渠道列表(摘要)。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":[IMChannel]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/agents/agent-1/im-channels -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/im-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:全空间 IM 渠道总览(不含凭证)。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":[IMChannel]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/im-channels -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/im-channels/:id
|
|
|
|
|
|
|
2026-09-26 06:57:16 +00:00
|
|
|
|
用途:更新渠道(局部更新:`name/mode/output_mode/locale/session_mode/knowledge_base_id/credentials/enabled/agent_id` 均可选;`knowledge_base_id` 传空字符串解除关联,`locale` 传空字符串恢复默认语言)。权限:Admin+。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":{IMChannel}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/im-channels/ch-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"enabled":false}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/im-channels/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除渠道。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/im-channels/ch-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/im-channels/:id/toggle
|
|
|
|
|
|
|
|
|
|
|
|
用途:启停切换。权限:Admin+。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":{IMChannel}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/im-channels/ch-1/toggle -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/wechat/qrcode
|
|
|
|
|
|
|
|
|
|
|
|
用途:生成 WeChat 登录二维码(绑定个人微信到空间)。权限:Admin+。无请求体。Handler: `internal/handler/wechat_qrcode.go`
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":{"qrcode_url","qrcode"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/wechat/qrcode -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/wechat/qrcode/status
|
|
|
|
|
|
|
|
|
|
|
|
用途:轮询扫码状态;确认后返回凭证。权限:Admin+。请求体:`{"qrcode":"<标识>"}`(必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"data":{"status":"pending|scanned|confirmed|expired","credentials":{bot_token,ilink_bot_id,ilink_user_id,baseurl}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/wechat/qrcode/status -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"qrcode":"qr-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Embed 渠道管理(需认证)
|
|
|
|
|
|
|
|
|
|
|
|
API key:`manage_channels`/full。Handler: `internal/handler/embed_channel.go`
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/agents/:id/embed-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:为 Agent 创建 Web 嵌入渠道。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 否 | 名称 |
|
|
|
|
|
|
| `enabled` | bool | 否 | 默认 true |
|
|
|
|
|
|
| `allowed_origins` | []string | 是 | 至少一个来源(精确 URL / `*.domain`;生产禁止 `*`) |
|
|
|
|
|
|
| `welcome_message` | string | 否 | 欢迎语 |
|
|
|
|
|
|
| `rate_limit_per_minute` | int | 否 | 每 IP/分钟,默认 30 |
|
|
|
|
|
|
| `rate_limit_per_day` | int | 否 | 渠道/天,默认 10000 |
|
|
|
|
|
|
| `primary_color` / `page_title` / `widget_position` | string | 否 | 外观(position: `bottom-right` 默认等四角) |
|
|
|
|
|
|
| `header_title_mode` | string | 否 | `channel`(默认)/`session` |
|
|
|
|
|
|
| `show_suggested_questions` | bool | 否 | 默认 true |
|
|
|
|
|
|
| `allow_web_search` / `allow_file_upload` | bool | 否 | 默认 false |
|
feat(i18n): add Japanese (ja-JP) locale support (#3080)
* feat(i18n): add Japanese (ja-JP) locale support
Add a complete Japanese UI locale for the admin frontend and the web
embed widget, and register it everywhere the supported-locale list is
enumerated.
- frontend/src/i18n/locales/ja-JP.ts: full bundle (5,600+ keys) aligned
with en-US/zh-CN key structure; verified by the locale key audit
- frontend/src/i18n/embed.ts: ja-JP block for the embed widget, plus
`ja*` normalisation in normalizeEmbedLocale
- Register ja-JP in i18n index, SUPPORTED_LOCALES, localeKeyAudit
bundles/order, TDesign locale map (ja_JP), login language picker,
general settings dropdown and embed default-locale options
- Add `language.jaJP` key to every locale so the settings dropdown can
use $t like its siblings
- Accept ja-JP as an embed channel default_locale on the backend and as
DEFAULT_LOCALE in the frontend docker entrypoint
- Extend locale-enumerating tests and update accepted-value lists in
.env.example, public/config.js, widget script and website-docs
* feat(i18n): add ja-JP names and descriptions for prompt templates
Add a ja-JP block to the i18n map of all 32 prompt templates
(system_prompt, context_template, rewrite, fallback, intent_prompts,
agent_system_prompt) so the template picker shows Japanese labels when
the UI locale is ja-JP instead of falling back to the Chinese names.
Prompt content is unchanged.
* feat(i18n): add ja-JP strings for the CLI integration page
main gained the CLI setup page (#3081) with 18 new integrations.cli.* /
integrations.tabs.cli keys; add their Japanese translations so the
locale key audit stays green after rebasing onto main.
* style(i18n): unify ja-JP spacing and long-vowel conventions
- Remove spaces between Latin tokens and adjacent Japanese text
(e.g. "MCP サービス" -> "MCPサービス"), matching the majority style
already used in the bundle
- Drop the trailing long-vowel mark on common technical katakana terms
(サーバ, ユーザ, フォルダ, プロバイダ, パラメータ, ヘッダ, クラスタ, ...)
so the whole locale follows one convention
* feat(i18n): add ja-JP labels for agent type presets
config/agent_type_presets.yaml carried default / zh-CN / zh-TW labels
only, so the agent editor showed English preset names in the Japanese
UI. Add a ja-JP label and description to all five presets.
2026-09-07 11:20:41 +00:00
|
|
|
|
| `default_locale` | string | 否 | `zh-CN/en-US/ko-KR/ja-JP/ru-RU`/空(跟随浏览器) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `webhook_url` / `webhook_secret` | string | 否 | 访客事件 webhook |
|
|
|
|
|
|
| `agent_id` | string | 否 | 绑定 Agent |
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{embedChannelResponse 含 publish_token}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/agents/agent-1/embed-channels -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"官网客服","allowed_origins":["https://example.com"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/agents/:id/embed-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:某 Agent 的嵌入渠道列表。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[embedChannelResponse]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/agents/agent-1/embed-channels -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed-channels
|
|
|
|
|
|
|
|
|
|
|
|
用途:全空间嵌入渠道列表(不含 publish token)。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[embedChannelResponse]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed-channels -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed-channels/:channel_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:渠道详情(含 publish token,用于复制部署代码)。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{embedChannelResponse}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed-channels/ec-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/embed-channels/:channel_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新渠道(字段同创建,均可选)。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{embedChannelResponse}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/embed-channels/ec-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"enabled":false}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/embed-channels/:channel_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除渠道。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/embed-channels/ec-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed-channels/:channel_id/rotate-token
|
|
|
|
|
|
|
|
|
|
|
|
用途:轮换 publish token(旧 token 失效)。权限:Admin+。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{embedChannelResponse 含新 publish_token}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed-channels/ec-1/rotate-token -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed-channels/:channel_id/preview-session
|
|
|
|
|
|
|
|
|
|
|
|
用途:签发管理端预览用短时效 session token(无需 publish token)。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"session_token","expires_in"}}`;渠道禁用 403。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed-channels/ec-1/preview-session -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed-channels/:channel_id/stats
|
|
|
|
|
|
|
|
|
|
|
|
用途:渠道用量统计。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"session_count":N}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed-channels/ec-1/stats -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
## Embed 嵌入页框架策略
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed-frame-policy
|
|
|
|
|
|
|
|
|
|
|
|
用途:供 Nginx `auth_request` 子请求在返回 `/embed/:channel_id` 页面前获取该渠道的 `Content-Security-Policy: frame-ancestors`。免 token,只返回策略头,不返回渠道配置;响应 `Cache-Control: no-store`。
|
|
|
|
|
|
|
|
|
|
|
|
| 请求头 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
|
| `X-Embed-Page-URI` | 是 | 嵌入页的相对 URI,如 `/embed/<channel_id>` |
|
|
|
|
|
|
|
|
|
|
|
|
响应:204 并带 CSP 头;渠道不存在、已停用、路径非法或白名单为空时 403。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -i $BASE/api/v1/embed-frame-policy -H "X-Embed-Page-URI: /embed/ec-1"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
## Embed 公开路由(/api/v1/embed/:channel_id,EmbedAuth)
|
|
|
|
|
|
|
|
|
|
|
|
认证:`Authorization: Embed <publish_token|session_token>`;会话级操作附加 `X-Embed-Session: <sig>`。限流与 Origin 校验见总览。Handler: `internal/handler/embed_channel.go`;中间件:`internal/middleware/embed_auth.go`
|
|
|
|
|
|
|
|
|
|
|
|
以下 `$ET` 表示 Embed token 头:`-H "Authorization: Embed $EMBED_TOKEN"`。
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/exchange
|
|
|
|
|
|
|
|
|
|
|
|
用途:用 publish token 换取短时效 session token(session token 不可再次 exchange)。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"session_token","expires_in"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/exchange -H "Authorization: Embed $PUBLISH_TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed/:channel_id/config
|
|
|
|
|
|
|
|
|
|
|
|
用途:渠道公开配置(无密钥)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{channel_id,name,display_title,knowledge_base_ids,agent_id,agent_name,welcome_message,primary_color,widget_position,allow_web_search,allow_file_upload,default_locale,...}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed/ec-1/config -H "Authorization: Embed $EMBED_TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed/:channel_id/suggested-questions
|
|
|
|
|
|
|
|
|
|
|
|
用途:起始建议问题。查询参数:`limit`(≤12)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"questions":[...]}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/embed/ec-1/suggested-questions?limit=6" -H "Authorization: Embed $EMBED_TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed/:channel_id/chunks/:chunk_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:查看引用分块(内容脱敏;越权 403)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{chunk}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed/ec-1/chunks/c-1 -H "Authorization: Embed $EMBED_TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/sessions
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建访客会话,返回会话 ID 与签名句柄。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{"id":"<session_id>","sig":"<签名>"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/sessions -H "Authorization: Embed $EMBED_TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/knowledge-chat/:session_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:访客知识问答(SSE;payload 会被渠道约束改写后委托给 KnowledgeQA)。需 `X-Embed-Session`。请求体同 `/knowledge-chat`(`query` 必填)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -N -X POST $BASE/api/v1/embed/ec-1/knowledge-chat/s-1 \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"query":"营业时间?"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/agent-chat/:session_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:访客 Agent 问答(SSE)。需 `X-Embed-Session`。请求体同上。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -N -X POST $BASE/api/v1/embed/ec-1/agent-chat/s-1 \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"query":"帮我下单"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed/:channel_id/messages/:session_id/load
|
|
|
|
|
|
|
|
|
|
|
|
用途:加载访客会话消息(委托 `LoadMessages`,查询参数 `limit/before_time`)。需 `X-Embed-Session`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[Message]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/embed/ec-1/messages/s-1/load?limit=20" \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/sessions/:session_id/stop
|
|
|
|
|
|
|
|
|
|
|
|
用途:停止生成(委托 StopSession;请求体 `{"message_id":"..."}`)。需 `X-Embed-Session`。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/sessions/s-1/stop \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"message_id":"m-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET|POST /api/v1/embed/:channel_id/sessions/:session_id/messages/:message_id/suggestions
|
|
|
|
|
|
|
|
|
|
|
|
用途:读取 / 触发生成消息建议(渠道关闭建议时返回 `suppressed`)。需 `X-Embed-Session`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"status","questions":[...]}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/embed/ec-1/sessions/s-1/messages/m-1/suggestions \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/sessions/:session_id/suggestion-events
|
|
|
|
|
|
|
|
|
|
|
|
用途:上报建议交互事件(委托 RecordEvent,字段同认证版)。需 `X-Embed-Session`。响应:204。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/sessions/s-1/suggestion-events \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"suggestion_set_id":"ss-1","event_type":"impression"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/embed/:channel_id/sessions/:session_id/events
|
|
|
|
|
|
|
|
|
|
|
|
用途:转发访客事件到渠道 webhook。需 `X-Embed-Session`。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `type` | string | 是 | `message_sent` / `message_received` |
|
|
|
|
|
|
| `query` / `content` | string | 否 | 用户问题 / 机器人回复 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`;不支持的类型 400。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/sessions/s-1/events \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"type":"message_sent","query":"你好"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### MCP OAuth 与工具审批(访客侧)
|
|
|
|
|
|
|
|
|
|
|
|
以下路由均需 `X-Embed-Session`,委托到对应认证版 handler(`internal/handler/mcp_oauth.go`、`internal/handler/mcp_service.go`):
|
|
|
|
|
|
|
|
|
|
|
|
| 方法+路径 | 用途 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `POST /api/v1/embed/:channel_id/sessions/:session_id/mcp-oauth-resolutions/:pending_id` | 恢复 OAuth 暂停的运行(体:`service_id` 必填,`decision` 可选) |
|
|
|
|
|
|
| `POST /api/v1/embed/:channel_id/sessions/:session_id/mcp-oauth-resolutions/:pending_id/cancel` | 取消 OAuth 流程 |
|
|
|
|
|
|
| `POST /api/v1/embed/:channel_id/sessions/:session_id/mcp-services/:id/oauth/authorize-url` | 生成授权 URL(体:`redirect_uri` 必填) |
|
|
|
|
|
|
| `GET /api/v1/embed/:channel_id/sessions/:session_id/mcp-services/:id/oauth/status` | 查询授权状态 |
|
|
|
|
|
|
| `POST /api/v1/embed/:channel_id/sessions/:session_id/tool-approvals/:pending_id` | 工具审批(体:`decision` 必填) |
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/embed/ec-1/sessions/s-1/tool-approvals/p-1 \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -H "X-Embed-Session: $SIG" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"decision":"approve"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/embed/:channel_id/files
|
|
|
|
|
|
|
|
|
|
|
|
用途:访客侧图片代理(机器人回复内嵌图片;EmbedAuth 注入渠道空间,handler 强制同空间路径)。查询参数:`file_path`(必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/embed/ec-1/files?file_path=local://1/exports/chart.png" \
|
|
|
|
|
|
-H "Authorization: Embed $EMBED_TOKEN" -o chart.png
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 文件服务
|
|
|
|
|
|
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
实现于 `internal/router/files.go`(非 handler 包)。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
### GET /files
|
|
|
|
|
|
|
|
|
|
|
|
用途:认证后的统一文件代理(本地/MinIO/COS/TOS 等)。权限:任意已认证空间成员;API key 需非 KB 受限(full-access 或全空间 retrieve,`middleware.AllowFileServeAPIKey()`);路径强制同空间(`ValidateStoragePathTenant`)。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file_path` | string | 是 | `provider://...` 路径(禁止 `..`;跨空间 403) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流(`X-Content-Type-Options: nosniff`;非白名单类型强制 `Content-Disposition: attachment`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/files?file_path=local://1/docs/a.png" -H "Authorization: Bearer $TOKEN" -o a.png
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET|HEAD /api/v1/files/presigned
|
|
|
|
|
|
|
|
|
|
|
|
用途:HMAC 签名 URL 文件访问(IM 平台内嵌图片;免认证,验签+过期校验,`SYSTEM_AES_KEY` 参与签名)。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file_path` | string | 是 | 存储路径 |
|
|
|
|
|
|
| `tenant_id` | uint64 | 是 | 空间 ID |
|
|
|
|
|
|
| `expires` | string | 是 | Unix 过期时间 |
|
|
|
|
|
|
| `sig` | string | 是 | HMAC 签名 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流(HEAD 仅返回头);签名无效/过期 403。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/files/presigned?file_path=local://1/x.png&tenant_id=1&expires=1790000000&sig=abc" -o x.png
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/files/presigned-preview
|
|
|
|
|
|
|
|
|
|
|
|
用途:诊断端点:返回给定路径将生成的预签名 HTTP URL。权限:Admin+,显式拒绝 API key(`DenyAPIKeyPrincipal`)。查询参数:`file_path`(必填)。
|
|
|
|
|
|
|
fix(security): close cross-workspace access paths in shared spaces (#3408)
* fix(security): close cross-workspace access paths in shared spaces
A review of how shared-space (organization) members reach each other's
resources found six paths that bypass the org-share permission model:
- presigned-preview signed any resource handle or storage path, turning a
known resource:// handle into an anonymous /r/ URL that outlives share
revocation. It now requires the path to belong to the caller's tenant,
like /files.
- POST /initialization/initialize let a shared-KB editor rewrite the owner
workspace's models (base URL, API key) in place. Only the KB's own
workspace may call it, and rewriting a stored model needs the same
authority as PUT /models/:id.
- KB JSON carried the legacy inline credentials (storage_config
secret_id/secret_key, which initialization fills with the MinIO env
keys, and vlm_config api_key) to every share receiver. They are withheld
from JSON; their DB columns are unchanged.
- A chat without agent_source_tenant_id resolved shares before the
caller's own agent, so a member sharing a same-ID built-in agent took
over other workspaces' default agent. Own agents now win, built-in
agents can no longer be shared (existing such shares no longer resolve),
and embed channels drop a visitor-supplied source workspace.
- Any org-admin tenant (even a tenant Viewer inside it) could raise another
workspace's KB share to editor/admin, and the route guard was bypassable
via an unrelated :id. Share management is now: the sharer from the source
tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's
Admin+ that may only remove or lower. share_id must belong to :id.
- Wiki write tools were registered for every wiki KB in the search targets,
which only need read access, so a viewer share (e.g. via the built-in
wiki fixer) could edit or delete another workspace's wiki pages. They now
act only on KBs the caller may edit.
* fix(security): close the KB settings path and owner details for share receivers
Follow-up to the shared-space review:
- PUT /initialization/config shares the route guard that admits share
editors, so an editor could still rebind the owner's KB models, chunking
and storage, and storage backends resolved against the caller's workspace
let it bind the owner's KB to its own backend. Another workspace now needs
an admin share (the only share level the frontend offers settings to) and
may not change the storage binding at all.
- GET /initialization/config showed model base URLs and bucket locations to
any admin of the caller's own workspace, including share receivers. They
now only see whether credentials are configured.
- Wiki write tools on the caller's own KBs had no role floor, so a tenant
Viewer (and the IM, embed and MCP endpoint principals that run as Viewer)
could write through an agent what the HTTP routes deny. Writes now need
Contributor+, or the ingest capability for a scoped API key, following
the RBAC rollout switch.
- resolveAgent logs the share lookup error instead of a nil own-agent error
when a shared selector fails.
* fix(security): close the medium shared-space access findings
Follow-up to the high-risk fixes, from the same review:
- Wiki fixer moved into a shared KB's workspace ran with the caller's own
config there: an unset MCP mode registered all of the owner's MCP
services, and an "all" KB scope reached the owner's other KBs. The scoped
run now uses the built-in config pinned to that one KB, without MCP,
skills, sandbox or web search, and falls back to the KB's own model.
- An unset MCP mode means "all" at runtime but is shown as none in the share
scope; shared runs now treat it as none.
- Quick-answer mode used the request's web_search_enabled alone, so a
receiver could turn on search the agent disables and spend the owner's
provider quota. It now requires the agent setting too, as agent mode does.
- summary_model_id picked any model of the workspace a run executes in. It
is ignored for shared agents and the relocated wiki fixer.
- A workspace that left or was removed from an organization kept sharing its
KBs and agents. Its shares are revoked on departure, and share queries and
permission checks require the source workspace's membership and a live
organization, which also covers rows left behind earlier.
- Sharing an agent exposes its KB scope to all members, so a Contributor
could share colleagues' KBs (or "all") through an agent. The sharer must
now be able to share each KB directly (creator or Admin+; "all" needs
Admin+), also when a shared agent's scope is widened later.
- A scoped API key with manage_channels could mint an MCP endpoint token
wider than itself. Endpoints it creates, updates or rotates must stay
within its KB allow-list and capabilities.
- A shared agent's run indexed the receiver's Q&A into the owner's chat
history KB; indexing now uses the session owner's configuration.
- Sharing an agent with skills keeps injecting the owner's skill
environment values (product decision); the share panel now warns that
members can read them. Preview of originals through read-only shares is
kept as designed and documented.
2026-09-18 14:00:02 +00:00
|
|
|
|
`file_path` 必须属于当前空间,与 `/files` 相同:`resource://` 句柄要求资源归属本空间,存储路径要求租户段为本空间 ID;否则 403,不会签发任何 URL。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
响应:200 `{"file_path","provider","url","rewritten":bool,"hint"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/files/presigned-preview?file_path=local://1/x.png" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET|HEAD /r/:token
|
|
|
|
|
|
|
|
|
|
|
|
用途:短时效资源授权 URL(IM 等无法携带认证头的客户端)。免认证,token 即能力凭证;无效/过期 404。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流(`Cache-Control: private, max-age=300`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/r/abc123 -o file.png
|
|
|
|
|
|
```
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
## 实现参考
|
|
|
|
|
|
|
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)
* docs: sync website-docs with changes since v0.8.0
Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.
- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
toolbox, conversation steer/fork/rewind and reasoning effort, the
artifacts library, sandbox terminal and desktop, the Lite host sandbox,
the rebuilt model catalog (including a protocol-compat field reference),
Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
locale, whitelist-only outbound, admin user creation, new configuration
variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
search params, FAQ match_count cap, Notion credentials), tenant deletion
semantics, default timeouts, parser engine claims, removed tables and
commands, stale navigation paths, and route locations after the router
split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.
* fix(frontend): link the protocol-compat field to its documentation
The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.
* feat(website): showcase v0.8.2 on the homepage
- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
MCP Server and conversation control, and turn the v0.8.0 release block
into a standing skills & sandbox topic with the sandbox desktop and
terminal.
- Replace the three-up galleries with a feature list beside one large
screenshot: every item's text stays visible, clicking an item or one of
its views switches the image with a cross-fade, and the list plays itself
while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
failing, since the Screenshot component renders a placeholder for them.
* docs(changelog): add v0.8.2 release notes
* docs(website): add per-version release notes pages
Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.
The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.
* feat(website): let the site image listen on a configurable port
The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.
test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.
* fix(website): namespace the nginx listen port variable
* fix(website): support bash-wrapped container startup
* fix(website): align nginx startup with frontend entrypoint
* fix(website): pin nginx runtime for older host compatibility
* fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
|
|
|
|
路由注册:`internal/router/routes_agent.go` 的 `RegisterIMRoutes`、`RegisterIMChannelRoutes`、`RegisterEmbedChannelRoutes`、`RegisterEmbedPublicRoutes`;`internal/router/files.go` 的 `serveFilesWithResources`、`servePresignedFiles`、`servePresignedPreview`、`serveResourceGrants`。Handler:`internal/handler/im.go`、`internal/handler/wechat_qrcode.go`、`internal/handler/embed_channel.go`。
|