空间即应用：站点发布

将工作空间中的静态页面或 HTTP 服务发布为独立站点

站点发布

站点发布用于把工作空间中的页面或服务发布为可访问的独立站点。发布后系统会自动生成站点地址，适合分享文档、Demo 页面、原型页面、预览服务或内部工具。

静态 HTML：从工作空间文件系统读取 HTML、CSS、JS、图片等文件。
HTTP 服务：发布工作空间内正在运行的 Web 应用或接口服务。

站点默认仅空间成员可见，发布者也可以按需要调整为组织内可见。未发布、草稿或已下线站点不会对外访问。

适用场景

将工作空间中的静态页面快速分享给团队成员查看。
把正在开发的前端应用、后端服务或全栈 Demo 以站点形式对外预览。
发布需要登录访问的内部工具，并明确告知访问者站点会读取哪些个人数据。
在本地执行机或云端运行环境中调试 Web 服务访问效果。

静态 HTML

静态模式需要配置站点根目录和入口文件。根路径访问会返回入口文件，子路径会映射到站点根目录下的同名资源。

静态资源支持相对路径加载，例如 ./main.js、main.js、css/style.css。HTML 中以 / 开头的绝对路径不会自动改写到站点路径下，建议静态站点使用相对路径。

文件读取统一通过工作空间文件适配器完成，因此云端 workspace 和本地执行机 workspace 都使用同一套访问规则。

HTTP 服务

HTTP 服务发布面向需要进程持续运行的 Web 应用，例如开发服务器、后端接口服务或全栈框架应用。

发布 HTTP 服务时，需要填写应用监听端口，并可补充服务启动说明、健康检查路径、基础路径等高级配置。服务启动说明用于帮助发布者或协作者在服务停止后快速恢复运行。

访问站点时，后端会根据工作空间当前执行模式解析目标：

云端 sandbox：如果容器已停止，会自动唤起容器。
本地执行机：如果本地执行机离线，会返回不可用状态，不会回退到云端 sandbox。

系统会记录服务恢复状态，便于发布者判断服务是否已恢复成功。

访问地址

站点优先使用自动生成的独立站点地址访问。独立地址可以让页面资源、接口请求、Cookie 和前端路由更接近真实部署方式。

发布者可以在创建站点时选填独立域名前缀；留空时系统自动生成。站点创建后也可以在编辑页修改前缀。系统会检查前缀格式和全局占用情况，避免不同站点使用同一个独立站点地址。修改前缀只改变访问地址，不会重新创建站点，也不会清除访问者已经对该站点完成的授权。

系统也保留平台内兼容访问入口，便于从工作空间设置、文件预览等位置跳转和调试。

系统管理员可以在平台管理后台按站点禁用独立站点域名访问。禁用后，站点不会被删除，发布配置仍然保留；访问该独立站点地址时会显示临时不可用提示，用于异常流量、故障排查或稳定性保护场景。

Chat / Agent 维护站点

在工作空间 Chat 中，Agent 可以使用会话注入的 JAVIS_FRONTEND_BASE_URL 和 JAVIS_AUTH_TOKEN 直接调用站点维护 API，完成查询、创建、更新、发布、下线、删除、HTTP 服务恢复和用户授权管理。

这些接口代表当前会话用户执行，不会提升权限。调用者必须是目标工作空间管理员；使用 PAT 时，PAT 还需要具备对应工作空间写入能力和资源范围。

调用方式

curl "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/sites" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN"

维护接口清单

操作	方法	API
查询默认站点	GET	`/api/v1/workspaces/{workspaceId}/site`
查询站点列表	GET	`/api/v1/workspaces/{workspaceId}/sites`
创建站点	POST	`/api/v1/workspaces/{workspaceId}/site`
更新默认站点	PATCH	`/api/v1/workspaces/{workspaceId}/site`
更新指定站点	PATCH	`/api/v1/workspaces/{workspaceId}/sites/{siteId}`
删除指定站点	DELETE	`/api/v1/workspaces/{workspaceId}/sites/{siteId}`
恢复 HTTP 服务站点	POST	`/api/v1/workspaces/{workspaceId}/sites/{siteId}/restore`
查询 HTTP 站点用户授权	GET	`/api/v1/workspaces/{workspaceId}/sites/{siteId}/user-grants`
查询可授权用户	GET	`/api/v1/workspaces/{workspaceId}/sites/{siteId}/grantable-users`
给用户授权 HTTP 站点	POST	`/api/v1/workspaces/{workspaceId}/sites/{siteId}/user-grants`
撤销用户授权	DELETE	`/api/v1/workspaces/{workspaceId}/sites/{siteId}/user-grants/{userId}`

站点删除只支持按 siteId 删除。系统不提供按 workspace 一次删除全部站点的 API；删除前应先查询站点列表确认目标站点。

接口响应遵循统一响应格式：站点对象位于 data，站点列表位于 data 数组，用户授权列表位于 data.list。

创建静态站点

静态站点需要指定 mode: "STATIC"、站点根目录和入口文件。站点创建后默认为草稿状态，需要再将状态更新为 PUBLISHED 才会对外访问。

curl -X POST "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/site" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "项目首页",
    "mode": "STATIC",
    "visibility": "PRIVATE",
    "appRootPath": "site",
    "appEntryPath": "index.html"
  }'

创建 HTTP 服务站点

HTTP 服务站点需要指定 mode: "SANDBOX_HTTP" 和应用监听端口。可补充启动命令、健康检查路径、基础路径和恢复说明，便于服务停止后由协作者或 Agent 恢复。

curl -X POST "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/site" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "开发预览",
    "mode": "SANDBOX_HTTP",
    "visibility": "PRIVATE",
    "sandboxPort": 3000,
    "sandboxHealthPath": "/",
    "sandboxStartCommand": "npm run dev -- --host 0.0.0.0"
  }'

发布、下线与删除

发布或下线通过 PATCH 更新 status 完成。可用值包括 DRAFT、PUBLISHED、UNPUBLISHED。

curl -X PATCH "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/sites/$SITE_ID" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"PUBLISHED"}'

删除站点会移除站点配置及相关授权数据。删除前建议先查询站点列表确认 siteId。

curl -X DELETE "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/sites/$SITE_ID" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN"

HTTP 站点用户授权

HTTP 服务站点可以由工作空间管理员给组织内指定用户授权。授权范围限定为当前站点所属工作空间。

curl -X POST "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/sites/$SITE_ID/user-grants" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_xxx"}'

撤销授权：

curl -X DELETE "$JAVIS_FRONTEND_BASE_URL/api/v1/workspaces/$JAVIS_WORKSPACE_ID/sites/$SITE_ID/user-grants/user_xxx" \
  -H "Authorization: Bearer $JAVIS_AUTH_TOKEN"

授权数据

发布站点时，发布者需要声明站点会读取哪些访问者数据。访问者首次打开站点时，会看到对应的授权确认页面；同意后，该授权只对当前站点生效，不会被其他站点复用。

当前产品界面按 API 能力分类声明授权，而不是按权限等级打包授权。发布者可以选择基础访问、个人信息、个人组织信息、组织管理信息、工作空间读取、工作空间写入、空间知识目录读取、空间知识目录写入、插件读取、插件写入、AI / Chat 调用、会话历史与元数据管理等分类。

涉及组织或工作空间的能力需要访问者选择资源范围。组织管理信息授权时只记录用户同意和组织范围；实际读取组织成员等管理员接口时，后端会再次校验访问者当前是否为组织管理员。工作空间写入用于创建或修改工作空间元信息，空间知识目录写入用于创建、更新或删除工作空间知识目录文件，二者需要分别授权。会话历史与元数据管理按工作空间范围统一授权，授权后站点可访问所选工作空间下的所有会话。任务写入是任务协作能力，访问者是工作空间 viewer 时也可以授权并通过站点 API 创建、修改或删除任务。站点授权 API 前缀和后台 PAT 调用规则见下方说明，通用平台接口详情见常用 API。

访问者授权后，可以在个人设置的“站点授权”中查看站点已获得的权限，并可以打开站点、调整授权范围或撤销授权。撤销后，再次访问该站点时需要重新确认授权。

能力模块

能力模块按站点可申请的业务能力划分。同一个工作空间资源范围下，工作空间元信息写入、知识库文件写入、插件操作和任务写入是不同概念，应按实际用途分别授权。

站点授权 API 统一使用 /.well-known/knodo-site-auth 前缀。站点页面或站点后台调用平台 API 时，在原平台 API 路径前加该前缀。例如 /api/v1/auth/me 对应 /.well-known/knodo-site-auth/api/v1/auth/me。

后端会先校验 knodo_site_access，再判断目标接口是否开放给站点授权调用以及能力范围是否满足；没有开放或授权不足的接口不能调用。

模块	风险	资源范围	说明
基础访问	低	无	获取当前站点授权摘要
个人信息	低	无	读取访问者姓名、头像等基础资料
个人组织信息	中	组织	读取访问者相关组织摘要
组织管理信息	高	管理员组织	读取组织成员列表、角色等管理员信息
工作空间读取	中	工作空间	读取工作空间元信息
工作空间写入	高	可写工作空间	创建或修改工作空间元信息，不等同于知识库文件写入
空间知识目录读取	中	工作空间	读取工作空间知识目录和文件内容
空间知识目录写入	高	可写工作空间	创建、更新、删除工作空间知识目录文件
AI / Chat 调用	高	工作空间或 Bot	发起 AI 调用或继续对话
会话历史与元数据管理	高	工作空间	读取所选工作空间下的所有会话历史，管理标签、标题、摘要等元数据
插件读取	中	组织或工作空间	读取可见插件、插件详情或工作空间绑定关系
插件写入	高	组织或可写工作空间	上传、修改插件或变更工作空间插件绑定
任务读取	中	工作空间	读取工作空间任务
任务写入	高	有任务访问资格的工作空间	创建、修改或删除工作空间任务；viewer 也可以授权和使用

站点 API 调用

站点前端使用站点域名下的授权 API 前缀，统一前缀为 /.well-known/knodo-site-auth。浏览器会自动携带 knodo_site_access Cookie，避免跨域，也不需要在前端保存 Token。

const response = await fetch("/.well-known/knodo-site-auth/api/v1/auth/me");
const auth = await response.json();

站点后台也可以转发 knodo_site_access 调用同一前缀下的 API：

curl "https://<site-domain>/.well-known/knodo-site-auth/api/v1/auth/me" \
  -H "Cookie: knodo_site_access=jvs_site_xxx"

如果站点后台要调用通用平台 API，应使用 Knodo 平台域名下的 /api/v1/...，并通过 PAT 认证。PAT 的认证方式和常用接口详情见常用 API。

已开放给站点授权前缀的接口如下。调用时把“平台 API”前面加上 /.well-known/knodo-site-auth 即可。

模块	方法	平台 API
基础访问	GET	`/api/v1/auth/me`
工作空间读取	GET	`/api/v1/workspaces`
工作空间读取	GET	`/api/v1/workspaces/{id}`
工作空间写入	POST	`/api/v1/workspaces`
工作空间写入	PATCH	`/api/v1/workspaces/{id}`
空间知识目录读取	GET	`/api/v1/workspaces/{workspaceId}/files`
空间知识目录读取	GET	`/api/v1/workspaces/{workspaceId}/files/tree`
空间知识目录读取	GET	`/api/v1/workspaces/{workspaceId}/files/content`
空间知识目录写入	POST	`/api/v1/workspaces/{workspaceId}/files/upload`
空间知识目录写入	PUT	`/api/v1/workspaces/{workspaceId}/files/text-file`
空间知识目录写入	DELETE	`/api/v1/workspaces/{workspaceId}/files/delete`
插件读取	GET	`/api/v1/plugins`
插件读取	GET	`/api/v1/plugins/{id}`
插件读取	GET	`/api/v1/workspaces/{workspaceId}/plugins`
插件读取	GET	`/api/v1/workspaces/{workspaceId}/plugins/available`
插件写入	POST	`/api/v1/plugins/upload`
插件写入	PUT	`/api/v1/plugins/{id}/reupload`
插件写入	PATCH	`/api/v1/plugins/{id}/status`
插件写入	POST	`/api/v1/workspaces/{workspaceId}/plugins`
插件写入	DELETE	`/api/v1/workspaces/{workspaceId}/plugins/{pluginId}`
任务读取	GET	`/api/v1/workspaces/{workspaceId}/task-items`
任务读取	GET	`/api/v1/workspaces/{workspaceId}/task-items/{taskId}`
任务写入	POST	`/api/v1/workspaces/{workspaceId}/task-items`
任务写入	PATCH	`/api/v1/workspaces/{workspaceId}/task-items/{taskId}`
任务写入	DELETE	`/api/v1/workspaces/{workspaceId}/task-items/{taskId}`
AI / Chat 调用	POST	`/api/v1/workspaces/{workspaceId}/chat/submit`
AI / Chat 调用	POST	`/api/v1/bots/{botId}/chat/completions`
会话历史与元数据管理	GET	`/api/v1/workspaces/{workspaceId}/chat/conversations`
会话历史与元数据管理	GET	`/api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}/messages`
会话历史与元数据管理	GET	`/api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}/status`
会话历史与元数据管理	PATCH	`/api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}`
会话历史与元数据管理	DELETE	`/api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}`

限制说明：站点授权前缀目前不开放 GET /api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}/stream 这类 SSE 流式接口；Bot Chat 的 stream=true 也不通过站点授权前缀开放。需要流式能力时，建议由独立站点后台使用 PAT 调用平台 API，再按站点自身协议返回给前端。

修改工作空间基本信息使用 PATCH /api/v1/workspaces/{id}。请求体里缺失的 key 不会修改对应字段；只有显式传入的字段才会更新。

权限

站点权限分为两层：站点可见性控制“谁可以打开站点”，授权数据控制“站点打开后可以代表访问者读取或写入哪些数据”。

站点可见性支持：

组织内可见：同组织登录用户可访问。
空间成员可见：仅工作空间成员可访问。

授权数据按能力模块控制：

基础访问、个人信息等无资源范围的能力，只确认能力本身。
组织管理信息授权时不要求访问者是组织管理员；调用组织成员等管理员接口时才校验当前管理员身份。
工作空间读取、空间知识目录读取、空间知识目录写入、AI / Chat 调用等能力需要选择具体工作空间范围；其中空间知识目录写入需要工作空间 admin/editor。
任务写入按任务协作权限处理，工作空间 viewer 也可以授权和使用，不按知识库或插件写入的 admin/editor 规则处理。
会话历史与元数据管理需要选择工作空间范围；授权会话即授权所选工作空间下的所有会话。
插件读取、插件写入、任务读取、任务写入属于站点声明的高阶业务能力，需要按组织或工作空间范围单独授权。

两层权限互不替代：即使用户可以打开站点，站点读取个人资料、访问工作空间内容或写入知识库前，仍需要用户确认对应能力和资源范围。用户撤销站点授权后，站点可见性不变，但站点不能再调用已撤销的授权数据。