WeKnora/website-docs/04-api/02-api-org.md

452 lines
16 KiB
Markdown
Raw Normal View History

# API 参考:组织与共享
管理组织成员以及知识库和智能体的共享关系。组织以工作空间为成员单位。
组织(Organization)以“空间(tenant)”为成员单位。组织组路由的 API key 策略为 `manage_spaces` 或 full-access;KB/Agent 分享管理仅 full-access key 可用。
## 组织管理(/api/v1/organizations)
### POST /api/v1/organizations
用途:创建组织。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 组织名称 |
| `description` | string | 否 | 描述 |
| `avatar` | string | 否 | 头像 URL |
| `searchable` | bool | 否 | 是否可被搜索发现 |
| `require_approval` | bool | 否 | 加入是否需审批 |
| `member_limit` | int | 否 | 成员空间数上限 |
| `invite_code_validity_days` | int | 否 | 邀请码有效期(天) |
响应:201 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"研发组织"}'
```
### GET /api/v1/organizations
用途:列出我所在的组织。权限:Viewer+。
响应:200 `{"success":true,"data":{"organizations":[...],"total":N,"resource_counts":{"knowledge_bases":{"by_organization":{}},"agents":{"by_organization":{}}}}}`
```bash
curl $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/preview/:code
用途:按邀请码预览组织(不加入)。权限:Viewer+。路径参数:`code` 邀请码。
响应:200 `{"success":true,"data":{id,name,description,avatar,member_count,share_count,agent_share_count,is_already_member,require_approval,created_at}}`
```bash
curl $BASE/api/v1/organizations/preview/ABC123 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/join
用途:凭邀请码加入组织。权限:Admin+。请求体:`{"invite_code":"..."}`(必填)。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations/join -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123"}'
```
### POST /api/v1/organizations/join-request
用途:提交加入申请(需审批的组织)。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `invite_code` | string | 是 | 邀请码 |
| `message` | string | 否 | 申请附言 |
| `role` | string | 否 | 期望角色 |
响应:200 `{"success":true,"data":{JoinRequest}}`
```bash
curl -X POST $BASE/api/v1/organizations/join-request -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123","message":"申请加入"}'
```
### GET /api/v1/organizations/search
用途:搜索可发现(searchable)的组织。权限:Viewer+。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 否 | 关键字 |
| `limit` | int | 否 | 默认 20,上限 100 |
响应:200 `{"success":true,"data":[SearchableOrganization],"total":N}`
```bash
curl "$BASE/api/v1/organizations/search?q=研发" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/join-by-id
用途:按组织 ID 加入可发现组织(无需邀请码)。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 ID |
| `message` | string | 否 | 附言 |
| `role` | string | 否 | 期望角色 |
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X POST $BASE/api/v1/organizations/join-by-id -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1"}'
```
### GET /api/v1/organizations/:id
用途:组织详情。权限:Viewer+。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
用途:更新组织(服务层校验调用者空间是组织 admin,不限于 owner)。权限:Admin+。请求体字段同创建(均可选)。
响应:200 `{"success":true,"data":{OrganizationResponse}}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"description":"更新描述"}'
```
### DELETE /api/v1/organizations/:id
用途:删除组织。权限:Admin+(服务层要求组织 owner)。
响应:200 `{"success":true,"message":"Organization deleted successfully"}`
```bash
curl -X DELETE $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/leave
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
用途:本空间退出组织。权限:Admin+。无请求体。本空间分享进该组织的知识库和 Agent 会被一并撤销。
响应:200 `{"success":true,"message":"Left organization successfully"}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/leave -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/request-upgrade
用途:申请提升本空间在组织内的角色。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `requested_role` | string | 是 | 期望的组织角色(`viewer/editor/admin`) |
| `message` | string | 否 | 附言 |
响应:200 `{"success":true,"data":{JoinRequest}}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/request-upgrade -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"requested_role":"editor"}'
```
### POST /api/v1/organizations/:id/invite-code
用途:生成组织邀请码。权限:Admin+(服务层要求组织 admin)。无请求体。
响应:200 `{"success":true,"data":{"invite_code":"..."}}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/search-tenants
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
用途:按空间 ID 解析可邀请的空间。权限:Admin+,且调用者空间须为组织 admin。自 v0.8.2 起只接受完整的空间 ID,不再按空间名称跨空间搜索,`limit` 参数已移除。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
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
| `q` | string | 是 | 完整的空间 ID |
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
响应:200 `{"success":true,"data":[{"tenant_id","tenant_name"}]}`。`q` 不是有效 ID、空间不存在或已是组织成员时返回空数组,否则返回唯一候选。
```bash
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
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=10002" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/search-users
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
用途:已废弃别名,行为同 `search-tenants`。权限:Admin+。参数同上。
```bash
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
curl "$BASE/api/v1/organizations/org-1/search-users?q=10002" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/invite
用途:直接邀请空间加入组织。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tenant_id` | uint64 | 二选一 | 目标空间 ID(推荐) |
| `user_id` | string | 二选一 | 兼容路径:用户 ID(解析为其空间) |
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
| `representative_user_id` | string | 否 | 已忽略,仅为兼容保留:直接添加的空间不挂代表用户,避免邀请方指定对方空间里哪位用户的信息出现在成员列表中 |
| `role` | string | 是 | 组织内角色 |
响应:200 `{"success":true,"message":"Member added successfully"}`
```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"tenant_id":2,"role":"viewer"}'
```
### GET /api/v1/organizations/:id/members
fix(security): close the low-severity shared-space findings (#3416) * fix(security): close the low-severity shared-space findings Verified and fixed from the shared-space permission review: - Embed channels kept knowledge_ids, tag_ids, mentioned_items, skill_names and summary_model_id from anonymous visitors. Mentions are only scoped for shared agents, so a visitor could query any KB (and pick any model) of the channel workspace by ID. The payload now drops them; the widget never sends them. - PUT /knowledgebase/:kb_id/wiki/issues/:issue_id/status updated any issue by ID. The update is now scoped to the path's KB (404 otherwise). - A direct org invite let the inviter attach any user of the target workspace (or any user by ID) as its representative, whose username and email the roster then showed to all members. Direct adds attach no representative, and the roster returns emails only for the caller's own workspace. - COS and KS3 dropped the bucket (and COS the region) segment when turning a path into an object key, while the tenant check scans every segment: cos://42/<region>/prefix/7/... passed as tenant 42 and read tenant 7's object from a shared bucket. Both must now match the service's config. - Shared agent listings returned the full agent to receivers. Prompts and the creator's user ID are withheld; capabilities and scope stay visible. - Temporary document uploads let the caller pick the parser engine (and its credentials) of a shared agent's workspace; only the agent's rules choose one there now. - Suggested questions used request / message-snapshot knowledge_ids without a permission check. Each document is now resolved to its KB and checked like KB IDs, including a shared agent's scope. - IM channels accepted any knowledge_base_id (and any agent ID on create). Both must belong to the channel's workspace, the KB also to a restricted API key's allow-list. - KB-restricted API keys could list org-shared KBs outside their allow-list in the organization views; those listings are now filtered. - With enable_rbac=false, RequireKBAccess let cross-workspace denials through. That switch is for roles inside a workspace; the guard now always denies another workspace's KB, since handlers behind it load by ID without a tenant filter. - The org member limit was counted before and enforced apart from the insert; it is now checked in the insert's transaction with the organization row locked (SQLite serializes writers instead). - The UpdateOrganization route comment and API doc said owner-only; the service and UI allow org admins. Comment and doc corrected. Documented, not changed: issued /r/ and presigned links stay valid until they expire after a share is revoked. * fix(security): address review of the low-severity shared-space fixes - Embed payloads also drop question_origin. It selects a KB like an @mention for agents that retrieve only when mentioned, and the widget never sends it; the selection stays inside the agent's scope, but an anonymous visitor should not pick among its KBs. suggestion_attribution is kept (the widget sends it and it is validated). - The receiver view of a shared agent also withholds the follow-up suggestion instruction, a prompt like the others. Starter questions are shown to receivers anyway, and the sharer's name is displayed by design. - Follow-up suggestion generation moves into the agent's workspace with types.WithExecutionTenant instead of a bare tenant rewrite, so the caller is pinned before the document permission check runs. The auth middleware and the shared run already pinned it; this removes the dependency on that. - KS3 CopyFile copies only from the service's own bucket (as COS and S3 do); another bucket's path is a cross-backend copy. Tests cover the dropped question_origin, the follow-up instruction and the /shared-agents listing, a follow-up context with the tenant switched, a repeated wiki issue status update, and the KS3 copy source.
2026-09-18 14:58:46 +00:00
用途:组织成员(空间)列表。权限:Viewer+。`email` 只对调用方自己空间那一行返回,其他空间只返回用户名和头像。
响应:200 `{"success":true,"data":{"members":[{id,user_id,representative_user_id,role,tenant_id,tenant_name,username,email,avatar,joined_at}],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/members -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id/members/:tenant_id
用途:修改成员空间的组织角色。权限:Admin+。路径参数 `tenant_id` 为成员空间 ID。请求体:`{"role":"editor"}`(必填,`viewer/editor/admin`)。
响应:200 `{"success":true,"message":"Member role updated successfully"}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"role":"editor"}'
```
### DELETE /api/v1/organizations/:id/members/:tenant_id
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
用途:移除成员空间(含自移除)。权限:Admin+。被移除空间分享进该组织的知识库和 Agent 会被一并撤销。
响应:200 `{"success":true,"message":"Member removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/join-requests
用途:加入申请队列。权限:Admin+。
响应:200 `{"success":true,"data":{"requests":[{id,user_id,username,email,message,request_type,prev_role,requested_role,status,created_at,reviewed_at}],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/join-requests -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/organizations/:id/join-requests/:request_id/review
用途:审批加入/升级申请。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `approved` | bool | 是 | 通过/拒绝 |
| `message` | string | 否 | 审批意见 |
| `role` | string | 否 | 通过时授予的角色 |
响应:200 `{"success":true,"message":"Review completed"}`
```bash
curl -X PUT $BASE/api/v1/organizations/org-1/join-requests/req-1/review \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"approved":true}'
```
### GET /api/v1/organizations/:id/shares
用途:查看共享到该组织的 KB 列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/shares -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/agent-shares
用途:查看共享到该组织的 Agent 列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/organizations/org-1/agent-shares -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/shared-knowledge-bases
用途:组织空间视图:组织内全部共享 KB(含我自己的)。权限:Viewer+。
响应:200 `{"success":true,"data":[...含 is_mine、source_from_agent 标记...],"total":N}`
```bash
curl $BASE/api/v1/organizations/org-1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/shared-agents
用途:组织空间视图:组织内全部共享 Agent。权限:Viewer+。
响应:200 `{"success":true,"data":[SharedAgentInfo],"total":N}`
```bash
curl $BASE/api/v1/organizations/org-1/shared-agents -H "Authorization: Bearer $TOKEN"
```
## KB 分享(/api/v1/knowledge-bases/:id/shares)
API key:仅 full-access。Handler: `internal/handler/organization.go`
### POST /api/v1/knowledge-bases/:id/shares
用途:把 KB 分享到组织。权限:KB 创建者 OR Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 |
| `permission` | string | 是 | 共享权限(组织角色语义,如 `viewer/editor`) |
响应:201 `{"success":true,"data":{KBShare}}`
```bash
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```
### GET /api/v1/knowledge-bases/:id/shares
用途:查看该 KB 的分享列表。权限:Viewer+。
响应:200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/knowledge-bases/:id/shares/:share_id
用途:修改分享权限。权限:KB 创建者 OR Admin+。请求体:`{"permission":"editor"}`(必填)。
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
服务层规则(与取消分享共用):
- 原分享人需在 KB 所属空间内操作,且空间角色为 Contributor+;
- KB 所属空间的 Admin+ 可以管理本空间的全部分享;
- 目标组织中角色为 admin 的空间,其 Admin+ 用户只能**降低**权限或取消分享,不能把权限提升到超过当前值。
`share_id` 必须属于路径中的 KB,否则 404。
响应:200 `{"success":true,"message":"Share permission updated successfully"}`
```bash
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"permission":"editor"}'
```
### DELETE /api/v1/knowledge-bases/:id/shares/:share_id
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
用途:取消分享。权限:KB 创建者 OR Admin+,服务层规则同上。`share_id` 必须属于路径中的 KB,否则 404。
响应:200 `{"success":true,"message":"Share removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```
## Agent 分享(/api/v1/agents/:id/shares)
API key:仅 full-access。Handler: `internal/handler/organization.go`
### POST /api/v1/agents/:id/shares
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
用途:把 Agent 分享到组织。权限:Agent 创建者 OR Admin+。请求体同 KB 分享(`organization_id` + `permission`,必填)。内置智能体不能分享(400):每个空间都有同 ID 的内置智能体,分享后接收方无法区分。Agent 的知识库范围会开放给组织成员,因此调用者必须有权直接分享其中每个知识库(知识库创建者或 Admin+),`kb_selection_mode: all` 只有 Admin+ 可以分享,否则 403。
响应:201 `{"success":true,"data":{AgentShare}}`
```bash
curl -X POST $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```
### GET /api/v1/agents/:id/shares
用途:查看该 Agent 的分享列表。权限:Agent 创建者 OR Admin+。
响应:200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`
```bash
curl $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN"
```
### DELETE /api/v1/agents/:id/shares/:share_id
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
用途:取消 Agent 分享。权限:Agent 创建者 OR Admin+,服务层规则同 KB 取消分享。`share_id` 必须属于路径中的 Agent,否则 404。
响应:200 `{"success":true,"message":"Share removed successfully"}`
```bash
curl -X DELETE $BASE/api/v1/agents/agent-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```
## 共享资源聚合视图
### GET /api/v1/shared-knowledge-bases
用途:列出通过组织共享给我的 KB(去除属主侧向量库元数据)。权限:Viewer+;API key 需 `manage_spaces` 或 full-access。
响应:200 `{"success":true,"data":[...],"total":N}`
```bash
curl $BASE/api/v1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/shared-agents
用途:列出通过组织共享给我的 Agent。权限:Viewer+;API key 同上。
响应:200 `{"success":true,"data":[SharedAgentInfo],"total":N}`。`SharedAgentInfo` 含 `source_tenant_id`(来源空间)、`org_name`、`shared_by_username`、`permission`,以及 `web_search_ready`——只返回「来源空间的联网搜索是否可用」这一个布尔位,不下发来源空间的 provider 配置(会泄露配置),也不拿接收方空间的 provider ID 去比对(会误报不可用)。
使用共享 Agent 调用其它接口时,若同名 Agent 被多个空间共享,可带 `agent_source_tenant_id` 指明来源空间;该值会与共享关系逐一校验,非法或无权限时直接报错,不会静默回退到别的来源。
```bash
curl $BASE/api/v1/shared-agents -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/shared-agents/disabled
用途:设置“本空间禁用某共享 Agent”(影响整个空间的会话下拉)。权限:Admin+;API key 同上。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 是(`binding:"required"`) | 共享 Agent ID |
| `disabled` | bool | 否 | 是否禁用(默认 false) |
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/shared-agents/disabled -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"agent_id":"agent-1","disabled":true}'
```
## 实现参考
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` 的 `RegisterOrganizationRoutes`。Handler:`internal/handler/organization.go`。