From 240decbdcaff980d506da1c8f4deea73156a0197 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 23:43:44 +0000 Subject: [PATCH 1/2] docs(i18n): zh-Hans for the Resources glossary and FAQ Translate the glossary (each heading keeps the English term in parentheses) and the FAQ. Stamped; zh-Hant regenerated; headings keep the English ids. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QsR2jTxGkQdrLm4E6n23Ub --- content/docs/resources/faq.zh-Hans.mdx | 248 ++++++++++++++++++ content/docs/resources/faq.zh-Hant.mdx | 249 ++++++++++++++++++ content/docs/resources/glossary.zh-Hans.mdx | 274 +++++++++++++++++++ content/docs/resources/glossary.zh-Hant.mdx | 275 ++++++++++++++++++++ 4 files changed, 1046 insertions(+) create mode 100644 content/docs/resources/faq.zh-Hans.mdx create mode 100644 content/docs/resources/faq.zh-Hant.mdx create mode 100644 content/docs/resources/glossary.zh-Hans.mdx create mode 100644 content/docs/resources/glossary.zh-Hant.mdx diff --git a/content/docs/resources/faq.zh-Hans.mdx b/content/docs/resources/faq.zh-Hans.mdx new file mode 100644 index 00000000..da20d042 --- /dev/null +++ b/content/docs/resources/faq.zh-Hans.mdx @@ -0,0 +1,248 @@ +--- +title: 常见问题 +seoTitle: "常见问题：上手、多租户、定价和许可" +description: 关于 ObjectOS 的常见问题 —— 上手、数据库与多租户、迁移、权限、集成、运维、定价和许可。 +editions: [community, cloud, enterprise] +translation: + source_sha: a04083fa1854e4094b8d7487ba533efd4b0fdc6a14425451ab84b21f739465d7 + guide_rev: 1 + mode: auto +--- + +## 上手 [#getting-started] + +### 试用 ObjectOS 最快的方式是什么？ [#whats-the-absolute-fastest-way-to-try-objectos] + +登录 [ObjectOS Cloud](https://www.objectos.ai) —— 托管在浏览器中，无需安装任何东西。 +如果要改为在你自己的机器上运行开源的 ObjectStack 运行时，运行 +`npm i -g @objectstack/cli && os start`，然后打开 http://localhost:3000。参见 +[在本地运行 ObjectOS Community](/docs/start/community)。 + +### 我需要 Docker 吗？ [#do-i-need-docker] + +不需要。ObjectOS Cloud 不需要安装任何东西。对于开放的运行时，Node 22+ 和 CLI 就 +足够了；Docker 是自管理生产部署的推荐形态。 + +### 我需要数据库吗？ [#do-i-need-a-database] + +不需要，至少开始时不需要 —— ObjectOS Cloud 由我们为你管理，开放的运行时默认使用 +本地 SQLite。自管理的部署在进入生产环境时换用 Postgres / MySQL / Turso / Mongo。 + +### 我需要账户 / 云服务吗？ [#do-i-need-an-account--cloud-service] + +ObjectOS Cloud *就是*账户：登录即可构建。ObjectOS Enterprise 是自管理的，运行时 +不需要任何云服务 —— 把它连接到控制平面是可选的。开源的 ObjectStack 运行时则完全 +不需要账户。 + +## 本体 [#the-ontology] + +### ObjectOS 所说的本体是什么意思？ [#what-does-objectos-mean-by-ontology] + +你的应用的定义：它的对象和字段、关系、动作、权限、流程，以及 Agent 和工具的定义， +作为一个由运行时运行的、带类型且有版本的 ObjectStack 元数据整体。视图、仪表盘、 +应用和翻译是它的投影，而不是它的一部分。它是可执行的 —— 先校验，再运行 —— 而不是 +带有继承、公理和推理机的知识本体。参见[ObjectOS 中你的本体](/docs/ontology)。 + +### ObjectOS 是语义层吗？ [#is-objectos-a-semantic-layer] + +不是。语义层映射已经存在的系统，以便查询它们；它描述业务，却不运行业务。ObjectOS +运行你的本体：数据库、REST API、UI 和 Agent 工具都由它推导而来。你可以把一个已在 +运行的数据库连接为外部数据源 —— 默认只读，且仍处于早期阶段 —— 那个记录系统会留在 +原处。参见[扩展现有系统](/docs/build/extend-existing-systems)，以及并排比较的 +[How ObjectStack compares](https://objectstack.ai/docs/concepts/compare)。 + +## 架构 [#architecture] + +### 我可以使用 Postgres / MySQL / MongoDB 吗？ [#can-i-use-postgres--mysql--mongodb] + +可以 —— Postgres、MySQL、SQLite、Turso/libSQL 和 MongoDB 都是受支持的驱动。参见 +[运行时配置](/docs/configure/runtime)。 + +### 我可以禁用 UI / Account 门户，只使用 REST API 吗？ [#can-i-disable-the-ui--account-portals-and-use-only-the-rest-api] + +可以。运行 `os start --no-ui` 或设置相应的参数。无论是否挂载 UI，REST API 都是 +一样的。 + +### 我可以用自己的前端代替生成的 UI 吗？ [#can-i-use-my-own-front-end-instead-of-the-generated-ui] + +可以。生成的 UI 使用的就是你会在自己代码中调用的 `/api/v1/*` 端点。使用 +`@objectstack/client` SDK 或任何 HTTP 客户端即可。 + +### ObjectOS 支持 GraphQL 吗？ [#does-objectos-support-graphql] + +不支持。REST 是 API 界面。GraphQL 端点已在 ObjectStack 17.0 中移除 —— 它在路由 +背后从未被实现过，`/graphql` 现在返回 404。请使用生成的 REST API 配合 +[ObjectQL](/docs/reference/objectql) 查询语言（通过 `?filter=` / `?sort=` / +`?expand=`），它覆盖了同样的场景。说 GraphQL 的第三方系统不受影响：`graphql` 仍是 +*外部*数据源的有效协议，那是对别人的 API 的客户端，而不是 ObjectOS 提供的界面。 + +### 多租户是如何处理的？ [#how-is-multi-tenancy-handled] + +一个部署针对一个数据库提供一个应用 —— 参见[架构](/docs/architecture)。多个组织可以 +共享这个部署：**隔离墙式**租户姿态（`OS_TENANCY_POSTURE`）会竖起按组织隔离的 +隔离墙，它是一项需许可证的能力，没有许可证时运行时会拒绝启动。隔离墙隔开的是各组织 +的数据和成员资格，而不是元数据 —— 模式的作用域是部署，而不是组织，这就是为什么 +隔离墙式部署还必须声明挂载哪些 AI Agent。比隔离墙更强的隔离就是部署分离：必须拥有 +自己数据库的客户，就得到自己的部署。参见 +[多组织部署](/docs/reference/environment-variables#multi-organization-deployments)。 + +### ObjectOS 能在 serverless / Lambda 环境中运行吗？ [#can-objectos-run-in-a-serverless--lambda-environment] + +运行时是一个长期运行的 Node 进程 —— 为容器或虚拟机设计，而不是无状态函数。内核在 +启动时构建，进程在那之后才报告就绪；这种预热的进程内状态以及 Better Auth 的会话 +模型，正是按调用执行的函数无法保留的。 + +### 它能水平扩展吗？ [#does-it-scale-horizontally] + +可以。在负载均衡器后面运行多个实例。会话存放在数据库中（而不是内存中），所以任何 +实例都能处理任何请求。如果你启用了共享速率限制和队列能力，请使用 Redis。 + +## 数据与迁移 [#data--migrations] + +### 模式迁移是如何处理的？ [#how-are-schema-migrations-handled] + +驱动在启动时把数据库模式同步到你声明的对象。对于 Postgres，就是 `CREATE TABLE` / +`ALTER TABLE` 语句。对于受监管环境中需要受控的迁移，设置 `OS_SKIP_SCHEMA_SYNC=1` +并自行管理 DDL。 + +### 重命名字段时数据会怎样？ [#what-happens-to-data-when-i-rename-a-field] + +重命名在数据层是一种破坏性变更（看起来像"删除旧列、添加新列"）。用 `os diff` 检测 +它，并添加一个迁移步骤（在部署新产物之前在数据库中重命名列）。 + +### 我可以从 CSV / Excel / Salesforce 导入数据吗？ [#can-i-import-data-from-csv--excel--salesforce] + +CSV：可以，通过循环调用 `os data create`，或使用 UI 中的批量上传。Salesforce：目前 +最好的路径是导出为 CSV 再导入。原生连接器已在路线图上。 + +### 升级 ObjectOS 会丢失我的数据吗？ [#will-upgrading-objectos-lose-my-data] + +不会。补丁和次版本升级是非破坏性的。主版本升级（例如 4 → 5）会明确记录所需的 +迁移。先备份 —— [备份与灾难恢复](/docs/operate/backup)。 + +## 权限与多租户 [#permissions--multi-tenancy] + +### 如何实现行级安全？ [#how-do-i-do-row-level-security] + +在对象的 `recordAccess` 配置上声明一条共享规则（声明式的，类似 Salesforce）或一个 +CEL 谓词。安全插件会在每个查询上注入相应的过滤条件。参见 +[权限](/docs/configure/permissions)。 + +### 我可以让某些字段对特定用户不可见吗？ [#can-i-make-some-fields-invisible-to-certain-users] + +可以 —— 使用权限集中的字段级安全。按字段、按权限集设为隐藏或只读。在 REST、 +ObjectQL 和 UI 中统一强制执行。参见[权限集](/docs/configure/permissions/permission-sets)。 + +### 如何集成 Okta / Entra / Keycloak？ [#how-do-i-integrate-okta--entra--keycloak] + +使用 OIDC。在 **Setup → Authentication** 中（或通过环境变量）配置发现 URL + 客户端 +id/密钥。提供商回调 URL 为 `/api/v1/auth/oauth2/callback/`。参见 +[认证](/docs/configure/authentication)。 + +## 集成 [#integrations] + +### 我可以发送 webhook 吗？ [#can-i-send-webhooks] + +可以 —— 在 `requires` 中启用 `webhooks`。ObjectOS 使用带 HMAC-SHA256 签名的持久化 +发件箱。参见 [Webhook](/docs/configure/webhooks)。 + +### 我可以与 Zapier / Make / n8n 集成吗？ [#can-i-integrate-with-zapier--make--n8n] + +可以 —— 出站用 webhook，入站用 REST API + API 密钥。面向常用 iPaaS 工具的原生连接 +器已在路线图上。 + +### AI Agent 可以调用我的 ObjectOS 吗？ [#can-ai-agents-call-my-objectos] + +可以。每个 ObjectOS 部署都是位于 `/api/v1/mcp` 的 MCP 服务器，默认开启：每个对象都 +是一个工具，其作者暴露给 AI（`ai.exposed`）的每个动作也是。Claude Code、Claude +Desktop、IDE 或任何其他 MCP 客户端都以某个用户的身份连接，每次调用都以该用户的身份 +运行，受与人相同的权限和审计约束。开源的 ObjectStack 运行时提供同样的 MCP 界面， +使用你自己的模型；ObjectOS 增加了产品内 AI —— AI Builder 以及与你的用户对话的 +助手。参见[接入 AI 工具（MCP）](/docs/configure/mcp)。 + +## 定制 [#customization] + +### 我可以编写自定义插件吗？ [#can-i-write-custom-plugins] + +可以 —— 插件遵循简单的 DI + 生命周期模式（`init → start → destroy`）。示例参见 +GitHub 上的 `@objectstack/plugin-*` 包。 + +### 我可以定制 ObjectOS 的外观吗？ [#can-i-customize-how-objectos-looks] + +品牌（logo、强调色、默认主题）位于 **Setup → System Settings**。深度的 UI 定制意味着 +fork `@objectstack/client-react`，或基于 REST API 构建你自己的前端。 + +### 我可以添加英语以外的语言吗？ [#can-i-add-languages-other-than-english] + +可以 —— i18n 是一等功能。使用 `os i18n extract` / `os i18n check`，并发布一个翻译包。 + +## 运维 [#operations] + +### 推荐的生产部署是什么？ [#whats-the-recommended-production-deployment] + +Docker（多 Pod 时用 Kubernetes）+ 托管的 Postgres + 用于文件的 S3 或 R2 + 存放 +`OS_AUTH_SECRET` 的密钥管理器。参见[生产就绪](/docs/operate/production)。 + +### ObjectOS 有状态页吗？ [#does-objectos-have-a-status-page] + +对于自管理（Enterprise）部署，状态由你负责 —— 把你的监控指向 `/api/v1/health` 做 +存活检查，指向 `/api/v1/ready` 做就绪检查，也就是 [Docker](/docs/deploy/docker) 和 +[Kubernetes](/docs/deploy/kubernetes) 所接好的那一对端点。托管服务参见 +[status.objectstack.ai](https://status.objectstack.ai)。 + +### 我应该监控哪些指标？ [#what-metrics-should-i-monitor] + +5xx 比率、p95 延迟、就绪状态（`/api/v1/ready`）。没有可以监控的认证失败指标 —— 请改 +为在 Setup 的 `Auth` 审计视图中审查登录活动。最简的 Prometheus 示例见 +[可观测性](/docs/operate/observability)。 + +### 如何做备份？ [#how-do-i-take-a-backup] + +备份**数据库**和**存储桶** —— 它们保存着所有客户数据。ObjectOS 本身是无状态的。参见 +[备份](/docs/operate/backup)。 + +## 定价与法律 [#pricing--legal] + +### ObjectOS 免费吗？ [#is-objectos-free] + +**ObjectOS Community** 是免费的：开源的运行时和 Console，构建在 +**[ObjectStack 框架](https://github.com/objectstack-ai/objectstack)**（Apache-2.0） +之上 —— 没有席位，没有用量档位，没有许可证服务器 —— 通过 MCP 使用 AI（自带你自己的 +模型）。**ObjectOS Cloud**（有免费档位可以起步）和 **ObjectOS Enterprise** 增加了 +嵌入式的 **UI 内 AI** + 治理以及官方运维，而你只需为 **AI 席位**付费（查看者和不使用 +AI 的用户免费）。参见[版本](/docs/editions/license#editions)。 + +### 我可以在我出售的商业产品中使用它吗？ [#can-i-use-it-in-a-commercial-product-i-sell] + +**ObjectStack 框架**和 **ObjectOS Community** —— 可以，Apache-2.0 允许商业使用， +无需支付版税。再分发 **ObjectOS Cloud 或 Enterprise**，或任何以 ObjectOS 名义的构建， +需要 OEM 协议。参见[许可证与定价](/docs/editions/license)。 + +### 你们收集遥测数据吗？ [#do-you-collect-telemetry] + +除非你自己配置（OIDC、邮件、AI、webhook），ObjectOS Community 不会发起任何出站调用。 +ObjectOS Enterprise 在线校验其许可证；企业版物理隔离许可证在离线状态下校验。参见 +[安全与合规](/docs/reference/security#data-residency)。 + +### ObjectOS 符合 SOC 2 / ISO 27001 / HIPAA / GDPR 吗？ [#is-objectos-soc-2--iso-27001--hipaa--gdpr-compliant] + +ObjectOS 提供每个框架都要求的**原语**（RBAC、审计、可加密、数据驻留）。认证是你的 +**部署**的属性，而不是二进制文件的属性。许多 ObjectOS 部署已经通过认证。参见 +[安全与合规](/docs/reference/security#compliance-frameworks)。 + +## 摆脱困境 [#getting-unstuck] + +### 出问题了 —— 我从哪里开始？ [#somethings-broken--where-do-i-start] + +`os doctor`。它自己就能捕获 80% 的错误配置。之后再看[故障排查](/docs/operate/troubleshooting)。 + +### 我在哪里报告缺陷？ [#where-do-i-report-a-bug] + +[GitHub Issues](https://github.com/objectstack-ai/objectstack/issues) —— 唯一的公开 +问题跟踪器，适用于每个 ObjectOS 版本。请附上 `os doctor` 的输出。安全问题： +**security@objectstack.ai**。 + +### 我在哪里能得到真人的帮助？ [#where-do-i-get-help-from-humans] + +[GitHub Issues](https://github.com/objectstack-ai/objectstack/issues)、社区 Discord， +或者联系 **sales@objectstack.ai** 获取商业支持。 diff --git a/content/docs/resources/faq.zh-Hant.mdx b/content/docs/resources/faq.zh-Hant.mdx new file mode 100644 index 00000000..d5285fa3 --- /dev/null +++ b/content/docs/resources/faq.zh-Hant.mdx @@ -0,0 +1,249 @@ +--- +# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant +title: 常見問題 +seoTitle: "常見問題：上手、多租戶、定價和許可" +description: 關於 ObjectOS 的常見問題 —— 上手、資料庫與多租戶、遷移、許可權、整合、運維、定價和許可。 +editions: [community, cloud, enterprise] +translation: + source_sha: a04083fa1854e4094b8d7487ba533efd4b0fdc6a14425451ab84b21f739465d7 + guide_rev: 1 + mode: auto +--- + +## 上手 [#getting-started] + +### 試用 ObjectOS 最快的方式是什麼？ [#whats-the-absolute-fastest-way-to-try-objectos] + +登入 [ObjectOS Cloud](https://www.objectos.ai) —— 託管在瀏覽器中，無需安裝任何東西。 +如果要改為在你自己的機器上執行開源的 ObjectStack 執行時，執行 +`npm i -g @objectstack/cli && os start`，然後開啟 http://localhost:3000。參見 +[在本地執行 ObjectOS Community](/docs/start/community)。 + +### 我需要 Docker 嗎？ [#do-i-need-docker] + +不需要。ObjectOS Cloud 不需要安裝任何東西。對於開放的執行時，Node 22+ 和 CLI 就 +足夠了；Docker 是自管理生產部署的推薦形態。 + +### 我需要資料庫嗎？ [#do-i-need-a-database] + +不需要，至少開始時不需要 —— ObjectOS Cloud 由我們為你管理，開放的執行時預設使用 +本地 SQLite。自管理的部署在進入生產環境時換用 Postgres / MySQL / Turso / Mongo。 + +### 我需要賬戶 / 雲服務嗎？ [#do-i-need-an-account--cloud-service] + +ObjectOS Cloud *就是*賬戶：登入即可構建。ObjectOS Enterprise 是自管理的，執行時 +不需要任何雲服務 —— 把它連線到控制平面是可選的。開源的 ObjectStack 執行時則完全 +不需要賬戶。 + +## 本體 [#the-ontology] + +### ObjectOS 所說的本體是什麼意思？ [#what-does-objectos-mean-by-ontology] + +你的應用的定義：它的物件和欄位、關係、動作、許可權、流程，以及 Agent 和工具的定義， +作為一個由執行時執行的、帶型別且有版本的 ObjectStack 後設資料整體。檢視、儀表盤、 +應用和翻譯是它的投影，而不是它的一部分。它是可執行的 —— 先校驗，再執行 —— 而不是 +帶有繼承、公理和推理機的知識本體。參見[ObjectOS 中你的本體](/docs/ontology)。 + +### ObjectOS 是語義層嗎？ [#is-objectos-a-semantic-layer] + +不是。語義層對映已經存在的系統，以便查詢它們；它描述業務，卻不執行業務。ObjectOS +執行你的本體：資料庫、REST API、UI 和 Agent 工具都由它推導而來。你可以把一個已在 +執行的資料庫連線為外部資料來源 —— 預設只讀，且仍處於早期階段 —— 那個記錄系統會留在 +原處。參見[擴充套件現有系統](/docs/build/extend-existing-systems)，以及並排比較的 +[How ObjectStack compares](https://objectstack.ai/docs/concepts/compare)。 + +## 架構 [#architecture] + +### 我可以使用 Postgres / MySQL / MongoDB 嗎？ [#can-i-use-postgres--mysql--mongodb] + +可以 —— Postgres、MySQL、SQLite、Turso/libSQL 和 MongoDB 都是受支援的驅動。參見 +[執行時配置](/docs/configure/runtime)。 + +### 我可以停用 UI / Account 門戶，只使用 REST API 嗎？ [#can-i-disable-the-ui--account-portals-and-use-only-the-rest-api] + +可以。執行 `os start --no-ui` 或設定相應的引數。無論是否掛載 UI，REST API 都是 +一樣的。 + +### 我可以用自己的前端代替生成的 UI 嗎？ [#can-i-use-my-own-front-end-instead-of-the-generated-ui] + +可以。生成的 UI 使用的就是你會在自己程式碼中呼叫的 `/api/v1/*` 端點。使用 +`@objectstack/client` SDK 或任何 HTTP 客戶端即可。 + +### ObjectOS 支援 GraphQL 嗎？ [#does-objectos-support-graphql] + +不支援。REST 是 API 介面。GraphQL 端點已在 ObjectStack 17.0 中移除 —— 它在路由 +背後從未被實現過，`/graphql` 現在返回 404。請使用生成的 REST API 配合 +[ObjectQL](/docs/reference/objectql) 查詢語言（通過 `?filter=` / `?sort=` / +`?expand=`），它覆蓋了同樣的場景。說 GraphQL 的第三方系統不受影響：`graphql` 仍是 +*外部*資料來源的有效協議，那是對別人的 API 的客戶端，而不是 ObjectOS 提供的介面。 + +### 多租戶是如何處理的？ [#how-is-multi-tenancy-handled] + +一個部署針對一個數據庫提供一個應用 —— 參見[架構](/docs/architecture)。多個組織可以 +共享這個部署：**隔離牆式**租戶姿態（`OS_TENANCY_POSTURE`）會豎起按組織隔離的 +隔離牆，它是一項需許可證的能力，沒有許可證時執行時會拒絕啟動。隔離牆隔開的是各組織 +的資料和成員資格，而不是後設資料 —— 模式的作用域是部署，而不是組織，這就是為什麼 +隔離牆式部署還必須宣告掛載哪些 AI Agent。比隔離牆更強的隔離就是部署分離：必須擁有 +自己資料庫的客戶，就得到自己的部署。參見 +[多組織部署](/docs/reference/environment-variables#multi-organization-deployments)。 + +### ObjectOS 能在 serverless / Lambda 環境中執行嗎？ [#can-objectos-run-in-a-serverless--lambda-environment] + +執行時是一個長期執行的 Node 程序 —— 為容器或虛擬機器設計，而不是無狀態函式。核心在 +啟動時構建，程序在那之後才報告就緒；這種預熱的程序內狀態以及 Better Auth 的會話 +模型，正是按呼叫執行的函式無法保留的。 + +### 它能水平擴充套件嗎？ [#does-it-scale-horizontally] + +可以。在負載均衡器後面執行多個例項。會話存放在資料庫中（而不是記憶體中），所以任何 +例項都能處理任何請求。如果你啟用了共享速率限制和佇列能力，請使用 Redis。 + +## 資料與遷移 [#data--migrations] + +### 模式遷移是如何處理的？ [#how-are-schema-migrations-handled] + +驅動在啟動時把資料庫模式同步到你宣告的物件。對於 Postgres，就是 `CREATE TABLE` / +`ALTER TABLE` 語句。對於受監管環境中需要受控的遷移，設定 `OS_SKIP_SCHEMA_SYNC=1` +並自行管理 DDL。 + +### 重新命名欄位時資料會怎樣？ [#what-happens-to-data-when-i-rename-a-field] + +重新命名在資料層是一種破壞性變更（看起來像"刪除舊列、新增新列"）。用 `os diff` 檢測 +它，並新增一個遷移步驟（在部署新產物之前在資料庫中重新命名列）。 + +### 我可以從 CSV / Excel / Salesforce 匯入資料嗎？ [#can-i-import-data-from-csv--excel--salesforce] + +CSV：可以，通過迴圈呼叫 `os data create`，或使用 UI 中的批次上傳。Salesforce：目前 +最好的路徑是匯出為 CSV 再匯入。原生聯結器已在路線圖上。 + +### 升級 ObjectOS 會丟失我的資料嗎？ [#will-upgrading-objectos-lose-my-data] + +不會。補丁和次版本升級是非破壞性的。主版本升級（例如 4 → 5）會明確記錄所需的 +遷移。先備份 —— [備份與災難恢復](/docs/operate/backup)。 + +## 許可權與多租戶 [#permissions--multi-tenancy] + +### 如何實現行級安全？ [#how-do-i-do-row-level-security] + +在物件的 `recordAccess` 配置上宣告一條共享規則（宣告式的，類似 Salesforce）或一個 +CEL 謂詞。安全外掛會在每個查詢上注入相應的過濾條件。參見 +[許可權](/docs/configure/permissions)。 + +### 我可以讓某些欄位對特定使用者不可見嗎？ [#can-i-make-some-fields-invisible-to-certain-users] + +可以 —— 使用許可權集中的欄位級安全。按欄位、按許可權集設為隱藏或只讀。在 REST、 +ObjectQL 和 UI 中統一強制執行。參見[許可權集](/docs/configure/permissions/permission-sets)。 + +### 如何整合 Okta / Entra / Keycloak？ [#how-do-i-integrate-okta--entra--keycloak] + +使用 OIDC。在 **Setup → Authentication** 中（或通過環境變數）配置發現 URL + 客戶端 +id/金鑰。提供商回撥 URL 為 `/api/v1/auth/oauth2/callback/`。參見 +[認證](/docs/configure/authentication)。 + +## 整合 [#integrations] + +### 我可以傳送 webhook 嗎？ [#can-i-send-webhooks] + +可以 —— 在 `requires` 中啟用 `webhooks`。ObjectOS 使用帶 HMAC-SHA256 簽名的持久化 +發件箱。參見 [Webhook](/docs/configure/webhooks)。 + +### 我可以與 Zapier / Make / n8n 整合嗎？ [#can-i-integrate-with-zapier--make--n8n] + +可以 —— 出站用 webhook，入站用 REST API + API 金鑰。面向常用 iPaaS 工具的原生連線 +器已在路線圖上。 + +### AI Agent 可以呼叫我的 ObjectOS 嗎？ [#can-ai-agents-call-my-objectos] + +可以。每個 ObjectOS 部署都是位於 `/api/v1/mcp` 的 MCP 伺服器，預設開啟：每個物件都 +是一個工具，其作者暴露給 AI（`ai.exposed`）的每個動作也是。Claude Code、Claude +Desktop、IDE 或任何其他 MCP 客戶端都以某個使用者的身份連線，每次呼叫都以該使用者的身份 +執行，受與人相同的許可權和審計約束。開源的 ObjectStack 執行時提供同樣的 MCP 介面， +使用你自己的模型；ObjectOS 增加了產品內 AI —— AI Builder 以及與你的使用者對話的 +助手。參見[接入 AI 工具（MCP）](/docs/configure/mcp)。 + +## 定製 [#customization] + +### 我可以編寫自定義外掛嗎？ [#can-i-write-custom-plugins] + +可以 —— 外掛遵循簡單的 DI + 生命週期模式（`init → start → destroy`）。示例參見 +GitHub 上的 `@objectstack/plugin-*` 包。 + +### 我可以定製 ObjectOS 的外觀嗎？ [#can-i-customize-how-objectos-looks] + +品牌（logo、強調色、預設主題）位於 **Setup → System Settings**。深度的 UI 定製意味著 +fork `@objectstack/client-react`，或基於 REST API 構建你自己的前端。 + +### 我可以新增英語以外的語言嗎？ [#can-i-add-languages-other-than-english] + +可以 —— i18n 是一等功能。使用 `os i18n extract` / `os i18n check`，併發佈一個翻譯包。 + +## 運維 [#operations] + +### 推薦的生產部署是什麼？ [#whats-the-recommended-production-deployment] + +Docker（多 Pod 時用 Kubernetes）+ 託管的 Postgres + 用於檔案的 S3 或 R2 + 存放 +`OS_AUTH_SECRET` 的金鑰管理器。參見[生產就緒](/docs/operate/production)。 + +### ObjectOS 有狀態頁嗎？ [#does-objectos-have-a-status-page] + +對於自管理（Enterprise）部署，狀態由你負責 —— 把你的監控指向 `/api/v1/health` 做 +存活檢查，指向 `/api/v1/ready` 做就緒檢查，也就是 [Docker](/docs/deploy/docker) 和 +[Kubernetes](/docs/deploy/kubernetes) 所接好的那一對端點。託管服務參見 +[status.objectstack.ai](https://status.objectstack.ai)。 + +### 我應該監控哪些指標？ [#what-metrics-should-i-monitor] + +5xx 比率、p95 延遲、就緒狀態（`/api/v1/ready`）。沒有可以監控的認證失敗指標 —— 請改 +為在 Setup 的 `Auth` 審計檢視中審查登入活動。最簡的 Prometheus 示例見 +[可觀測性](/docs/operate/observability)。 + +### 如何做備份？ [#how-do-i-take-a-backup] + +備份**資料庫**和**儲存桶** —— 它們儲存著所有客戶資料。ObjectOS 本身是無狀態的。參見 +[備份](/docs/operate/backup)。 + +## 定價與法律 [#pricing--legal] + +### ObjectOS 免費嗎？ [#is-objectos-free] + +**ObjectOS Community** 是免費的：開源的執行時和 Console，構建在 +**[ObjectStack 框架](https://github.com/objectstack-ai/objectstack)**（Apache-2.0） +之上 —— 沒有席位，沒有用量檔位，沒有許可證伺服器 —— 通過 MCP 使用 AI（自帶你自己的 +模型）。**ObjectOS Cloud**（有免費檔位可以起步）和 **ObjectOS Enterprise** 增加了 +嵌入式的 **UI 內 AI** + 治理以及官方運維，而你只需為 **AI 席位**付費（檢視者和不使用 +AI 的使用者免費）。參見[版本](/docs/editions/license#editions)。 + +### 我可以在我出售的商業產品中使用它嗎？ [#can-i-use-it-in-a-commercial-product-i-sell] + +**ObjectStack 框架**和 **ObjectOS Community** —— 可以，Apache-2.0 允許商業使用， +無需支付版稅。再分發 **ObjectOS Cloud 或 Enterprise**，或任何以 ObjectOS 名義的構建， +需要 OEM 協議。參見[許可證與定價](/docs/editions/license)。 + +### 你們收集遙測資料嗎？ [#do-you-collect-telemetry] + +除非你自己配置（OIDC、郵件、AI、webhook），ObjectOS Community 不會發起任何出站呼叫。 +ObjectOS Enterprise 線上校驗其許可證；企業版物理隔離許可證在離線狀態下校驗。參見 +[安全與合規](/docs/reference/security#data-residency)。 + +### ObjectOS 符合 SOC 2 / ISO 27001 / HIPAA / GDPR 嗎？ [#is-objectos-soc-2--iso-27001--hipaa--gdpr-compliant] + +ObjectOS 提供每個框架都要求的**原語**（RBAC、審計、可加密、資料駐留）。認證是你的 +**部署**的屬性，而不是二進位制檔案的屬性。許多 ObjectOS 部署已經通過認證。參見 +[安全與合規](/docs/reference/security#compliance-frameworks)。 + +## 擺脫困境 [#getting-unstuck] + +### 出問題了 —— 我從哪裡開始？ [#somethings-broken--where-do-i-start] + +`os doctor`。它自己就能捕獲 80% 的錯誤配置。之後再看[故障排查](/docs/operate/troubleshooting)。 + +### 我在哪裡報告缺陷？ [#where-do-i-report-a-bug] + +[GitHub Issues](https://github.com/objectstack-ai/objectstack/issues) —— 唯一的公開 +問題跟蹤器，適用於每個 ObjectOS 版本。請附上 `os doctor` 的輸出。安全問題： +**security@objectstack.ai**。 + +### 我在哪裡能得到真人的幫助？ [#where-do-i-get-help-from-humans] + +[GitHub Issues](https://github.com/objectstack-ai/objectstack/issues)、社群 Discord， +或者聯絡 **sales@objectstack.ai** 獲取商業支援。 diff --git a/content/docs/resources/glossary.zh-Hans.mdx b/content/docs/resources/glossary.zh-Hans.mdx new file mode 100644 index 00000000..d30db347 --- /dev/null +++ b/content/docs/resources/glossary.zh-Hans.mdx @@ -0,0 +1,274 @@ +--- +title: 术语表 +seoTitle: "术语表：平台术语，各有一个定义" +description: ObjectOS 和 ObjectStack 中使用的词汇 —— 每个术语一个定义。 +editions: [community, cloud, enterprise] +translation: + source_sha: 926190d46d41bff6cbbc425cf9ccf45e6fb26dfadfb12a7d791e2606e71163c2 + guide_rev: 1 + mode: auto +--- + +本文档中使用的每个术语都有唯一的规范定义。 + +### 动作（Action） [#action] + +在元数据中声明的具名操作，可以通过 REST（`/api/v1/actions//`）、 +UI 中的按钮调用，并且 —— 一旦其作者把它暴露给 AI（`ai.exposed`）—— 也可以由 Agent +调用。调用者能否调用它，以调用者的身份检查；随后 `script` 主体作为可信的应用代码 +运行。参见[动作](/docs/build/interface/actions)。 + +### 适配器（Adapter） [#adapter] + +把 ObjectStack 与宿主运行时集成的框架包 —— Express、Fastify、Hono、Next.js、 +Nuxt、SvelteKit、NestJS。大多数 ObjectOS 部署不需要它；ObjectOS 自带 HTTP 服务器。 + +### AI 席位（AI seat） [#ai-seat] + +ObjectOS 的计价单位，也是每个版本中唯一计费的席位。查看者、不使用产品内 AI 的应用 +用户，以及通过 MCP 构建的开发者都是免费的。参见 +[许可证与定价](/docs/editions/license#editions)。 + +### 应用（App） [#app] + +一组对象 + 视图 + 权限，呈现为一个可导航的应用。一个运行时中可以并存多个应用（例如 +CRM + Helpdesk + Setup）。 + +### 产物（Artifact） [#artifact] + +一个编译后的 `objectstack.json` 文件。对应用的自包含、不可变的描述 —— 清单、对象、 +视图、应用、流程、权限、翻译。由 `os compile` 产出。ObjectOS 实际执行的就是它。 + +### Better Auth [#better-auth] + +驱动 `@objectstack/plugin-auth` 的认证库。你不需要直接配置 Better Auth；插件封装 +了它。 + +### 业务本体（Business ontology） [#business-ontology] + +你的应用的定义 —— 对象和字段、关系、动作、权限、流程，以及 Agent 和工具的定义 —— +作为一个可执行、有版本的整体：以带类型的 ObjectStack 元数据编写，经过校验而不是 +推理，并由运行时运行，运行时从中推导出数据库、REST API、UI 和 MCP 工具。视图、 +仪表盘、应用和翻译是它的[投影](#projection)，而不是它的一部分。 + +它是可执行的，而不是知识本体：没有对象继承，没有公理，没有推理机。它也不是语义层 +—— 那是覆盖在现有系统之上的只读映射，描述业务却不运行业务。无论在哪个 ObjectOS +版本上它都属于你：导出它，就能在开源的 ObjectStack 运行时上运行。在本站参见 +[ObjectOS 中你的本体](/docs/ontology)；完整的阐述见 ObjectStack 文档中的 +[Business Ontology](https://objectstack.ai/docs/concepts/ontology)。 + +### 能力（Capability） [#capability] + +产物在其 `requires` 列表中声明的可选运行时功能。对应一个包 —— 例如 `audit` → +`@objectstack/plugin-audit`。由 ObjectOS 按需加载。参见 +[运行时能力](/docs/reference/runtime-capabilities)。 + +### CEL [#cel] + +[Common Expression Language](https://github.com/google/cel-spec) —— Google 的 +安全、沙箱化的表达式语法。用于公式、验证规则、权限谓词、共享规则和流程条件。 + +### 控制平面（Control Plane） [#control-plane] + +一项可选服务，向 ObjectOS 实例发布有版本的产物。以 ObjectOS Cloud 的形式托管，或 +自托管。大多数部署不需要它 —— 基于文件的模式足以支撑单应用的生产环境。 + +### 驱动（Driver） [#driver] + +数据后端的实现：`driver-sql`（Postgres、MySQL、SQLite、Turso/libSQL）、 +`driver-mongodb`、`driver-memory`。在启动时通过数据库 URL 选定。 + +### 嵌入器（Embedder） [#embedder] + +为 RAG / 语义搜索把文本转换为向量的服务。可在多个提供商之间插拔（OpenAI、Azure、 +硅基流动、Ollama……）。参见 [AI 服务](/docs/configure/ai)。 + +### 环境（Environment） [#environment] + +部署自身的身份 —— 它以 `OS_ENVIRONMENT_ID` 报告的 id，在云绑定完成后持久保存。 +自管理的 ObjectOS 是一个**单环境**运行时：一个进程、一个环境、一个应用。持有多个 +环境，并为每个环境发布一个产物，是控制平面做的事。参见 +[环境变量](/docs/reference/environment-variables)。 + +### 字段（Field） [#field] + +对象上的带类型属性。约 48 种内置类型：`text`、`select`、`lookup`、`markdown`、 +`file`、`formula`、`summary` 等。参见[数据模型](/docs/build/data)。 + +### 流程（Flow） [#flow] + +声明式的业务逻辑 —— 自动启动（记录触发）、定时（cron）或手动（按钮 / API）。以带有 +条件/循环/重试/并行原语的 DAG 形式执行。参见 +[流程与自动化](/docs/build/automation/flows)。 + +### 公式字段（Formula field） [#formula-field] + +一种计算字段，其值是在读取时求值的 CEL 表达式。不存储。 + +### 钩子（Hook） [#hook] + +注入到对象生命周期中的函数（`beforeInsert`、`afterUpdate`……）。用 TypeScript +编写。与流程不同：钩子是一等的代码；流程是元数据。 + +### 内核（Kernel） [#kernel] + +ObjectOS 内部的微内核，负责加载插件、持有 DI 容器、分发事件，并提供部署的元数据。 +一个进程在启动时构建一个内核，在构建完成之前不会报告[就绪](/docs/deploy/docker) +—— 所以不会有任何按请求的逻辑去决定提供哪份元数据。 + +### 清单（Manifest） [#manifest] + +位于产物开头的顶层元数据：`id`、`namespace`、`version`、`type`（`app` / `plugin` / +`service`）、`name`、`description`、`requires` 列表。 + +### 市场（Marketplace） [#marketplace] + +内置的可安装应用目录。由可配置的包注册表支撑。参见[市场](/docs/build/marketplace)。 + +### MCP（Model Context Protocol） [#mcp-model-context-protocol] + +一个让 AI Agent 发现和调用工具的开放协议。每个 ObjectOS 部署都是位于 `/api/v1/mcp` +的 MCP 服务器，默认开启：每个对象都是一个工具，其作者暴露给 AI（`ai.exposed`）的 +每个动作也是。每次调用都以调用者的身份运行。参见 +[接入 AI 工具（MCP）](/docs/configure/mcp)。 + +### 对象（Object） [#object] + +一个带类型的业务实体 —— `task`、`account`、`invoice`。以 TypeScript schema 声明； +自动生成 REST API、视图、审计条目和 RBAC 检查点。参见[数据模型](/docs/build/data)。 + +### ObjectOS [#objectos] + +构建在 ObjectStack 之上的运行环境，一个产品、三个版本：**ObjectOS Community** —— +开源的运行时和 Console，在 Apache-2.0 下免费，在 objectstack 仓库中开发； +**ObjectOS Cloud** —— 托管在浏览器中，无需安装任何东西；以及 **ObjectOS +Enterprise** —— 需许可证，在你自己的基础设施上自管理。Cloud 和 Enterprise 按 AI +席位计价，无论在哪个版本上，你都可以导出你的本体并在开放的运行时上运行它。 +**本文档站点是关于 ObjectOS 的。** + +### ObjectQL [#objectql] + +数据层协议和查询引擎。把声明式查询编译为原生的 SQL / Mongo 查询。REST 端点、UI、 +流程都使用它 —— 全部是同一个引擎。 + +### ObjectStack [#objectstack] + +开放的技术栈，Apache-2.0：执行业务本体的协议、微内核、SDK、CLI 和生产运行时 —— +即 `@objectstack/*` npm 包和运行时镜像。ObjectOS 是构建在它之上的运行环境： +ObjectOS Community 就是这个开放的运行时和 Console，采用同样的 Apache-2.0 许可， +而 ObjectOS Cloud 和 ObjectOS Enterprise 是建立在其上的商业版本。 + +### ObjectUI [#objectui] + +视图层协议 —— 应用、视图、页面、仪表盘、动作、图表、导航。ObjectOS 渲染 ObjectUI +声明。 + +### 权限集（Permission Set） [#permission-set] + +一组授权 —— 对象权限、字段权限、系统权限。直接附加到用户，或通过岗位附加。是主要的 +授权单元。参见[权限](/docs/configure/permissions)。 + +### 插件（Plugin） [#plugin] + +用一项能力扩展运行时的框架包 —— `plugin-auth`、`plugin-security`、 +`plugin-audit`、`plugin-webhooks`、`mcp` 等。通过 DI + 生命周期钩子 +（`init → start → destroy`）激活。 + +### 岗位（Position） [#position] + +用户所担任的职能 —— "Sales Manager"、"Support Agent"、"Auditor"。从 ObjectStack +13 起唯一的人员分组概念，并且有意设计为扁平的：汇报结构改为放在业务单元树上。岗位 +把应用和标签页定向到某个受众、指定审批人，并把权限集分配给担任它的每个人。参见 +[岗位](/docs/configure/permissions/positions)。 + +### 项目（Project） [#project] + +**环境**的旧名称。它仍保留在继承来的配置和框架内部的标识符中；ObjectOS 文档使用 +*环境*。 + +### 投影（Projection） [#projection] + +视图、仪表盘、应用或翻译：与[业务本体](#business-ontology)并列编写、经过同一道 +[校验关卡](#validation-gate)检查的元数据，但不是本体的一部分。投影呈现核心 —— 网格 +上的对象字段、图表上对对象的查询、某个语言区域中的每个标签。修改核心，它的投影会 +随之变化；移除一个投影，它所展示的业务不会改变。参见 +[ObjectOS 中你的本体](/docs/ontology#the-projections)。 + +### 记录共享（Record Share） [#record-share] + +针对特定记录、授予一个接收方的直接访问 —— 一个用户（`user`）、一个团队（`team`）、 +一个岗位（`position`）、一个业务单元（`business_unit`），或者一个业务单元连同其下 +的每个单元（`unit_and_subordinates`）。存储为 `sys_record_share` 行，其 +`recipient_type` 列恰好取这五个值。不同于共享规则（声明式条件）。 + +### Setup [#setup] + +内置的管理应用，位于 `/_console/` 所提供的 UI 中的 `/apps/setup`，由 `setup.access` +权限门控。管理用户、业务单元、团队、岗位、权限集、共享规则、记录共享和 API 密钥， +以及配置、诊断和集成。参见[配置](/docs/configure)。 + +### 共享规则（Sharing Rule） [#sharing-rule] + +一种基于条件授予记录访问的声明式规则（"区域经理可以看到其所在区域的记录"）。在查询 +时求值，编译为行级过滤条件。**没有**条件而存储的规则什么都不共享 —— 它并不匹配 +全部。参见[记录访问](/docs/configure/permissions/record-access#both-switches-fail-closed)。 + +### Studio [#studio] + +内置的元数据编写界面，位于 `/_console/` 所提供的 UI 中的 `/studio`，由 +`studio.access` 权限门控。元数据本身在这里被*设计* —— 包、对象、应用、流程和权限集 +—— 每次一个包，分为四个支柱：Data、Automations、Interfaces、Access。它与 **Setup** +并列，而不是 Setup 的一部分：Setup 运营一个运行中的部署（它的人员、他们的授权、它的 +配置），Studio 编写这个部署所运行的内容 —— 因此**权限在 Studio 中设计，在 Setup 中 +分配**。与 Setup 不同，它不是 `/apps/` 下的应用；UI 把它作为独立的路由子树提供。 +参见[配置](/docs/configure#setup-and-studio)。 + +### 界面入口（Surface） [#surface] + +运行中的 ObjectOS 暴露的 HTTP 入口之一：`/`（REST API）和 `/_console/`（UI）。是 +两个，不是三个 —— 账户**不是**一个独立的入口。登录、注册和账户自助服务都是 UI 内部 +的路由： + +| 账户界面 | 位于 | +|---|---| +| 登录 | `/_console/login` —— 你未登录时，每个受保护的页面都会把你送到这里 | +| 注册 | `/_console/register` —— 除非部署禁用了自助注册 | +| 账户自助服务 | `/_console/apps/account` —— Account 应用，与位于 `/_console/apps/setup` 的 Setup 并列 | + +没有 `/_account/` 入口。独立的账户门户被移除时，它也随之退役，这些 URL 现在返回 404。 + +### 系统上下文（System Context） [#system-context] + +插件、钩子和种子脚本在需要绕过安全检查时使用的内部执行模式。可审计；不暴露给用户 +代码。 + +### 租户（Tenant） [#tenant] + +共享同一个部署的各组织之间的隔离边界。隔离墙式租户姿态会竖起这道墙，它是一项需 +许可证的能力。这些组织仍然共享部署的应用、数据库和元数据，所以这道墙隔开的是它们的 +数据和成员资格，而不是它们的模式。参见 +[多组织部署](/docs/reference/environment-variables#multi-organization-deployments)。 + +### 触发器（Trigger） [#trigger] + +触发流程的条件 —— 记录事件（`after_insert`）、定时（cron）或手动调用。 + +### 校验关卡（Validation gate） [#validation-gate] + +所有元数据在运行之前都要通过的同一套检查：`@objectstack/spec` 的 schema，以及那些 +捕获能通过类型检查、却会在运行时静默失败的问题的编写规则 —— 错误的 CEL 谓词、对 +不存在之物的引用。`os validate` 和 `os compile` 在仓库源码上运行它，运行时也会对每 +一次上线的元数据写入应用同一道关卡，无论它来自 AI Builder、Studio 还是元数据 API。 +参见 ObjectStack 文档中的 +[Validating Metadata](https://objectstack.ai/docs/deployment/validating-metadata)。 + +### 视图（View） [#view] + +声明式的 UI 配置 —— 列表、表单、看板、日历、甘特图 —— 附加在对象上。ObjectOS 渲染 +它；你不需要编写组件。 + +### Zod schema [#zod-schema] + +`@objectstack/spec` 使用的运行时 + 编译时类型系统。每个对象、字段、视图、应用、流程 +都由一个 Zod schema 解析和校验。JSON Schema、TypeScript 类型和 REST 请求校验器都 +派生自同一组 Zod 定义。 diff --git a/content/docs/resources/glossary.zh-Hant.mdx b/content/docs/resources/glossary.zh-Hant.mdx new file mode 100644 index 00000000..093d1209 --- /dev/null +++ b/content/docs/resources/glossary.zh-Hant.mdx @@ -0,0 +1,275 @@ +--- +# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant +title: 術語表 +seoTitle: "術語表：平臺術語，各有一個定義" +description: ObjectOS 和 ObjectStack 中使用的詞彙 —— 每個術語一個定義。 +editions: [community, cloud, enterprise] +translation: + source_sha: 926190d46d41bff6cbbc425cf9ccf45e6fb26dfadfb12a7d791e2606e71163c2 + guide_rev: 1 + mode: auto +--- + +本文件中使用的每個術語都有唯一的規範定義。 + +### 動作（Action） [#action] + +在後設資料中宣告的具名操作，可以通過 REST（`/api/v1/actions//`）、 +UI 中的按鈕呼叫，並且 —— 一旦其作者把它暴露給 AI（`ai.exposed`）—— 也可以由 Agent +呼叫。呼叫者能否呼叫它，以呼叫者的身份檢查；隨後 `script` 主體作為可信的應用程式碼 +執行。參見[動作](/docs/build/interface/actions)。 + +### 介面卡（Adapter） [#adapter] + +把 ObjectStack 與宿主執行時整合的框架包 —— Express、Fastify、Hono、Next.js、 +Nuxt、SvelteKit、NestJS。大多數 ObjectOS 部署不需要它；ObjectOS 自帶 HTTP 伺服器。 + +### AI 席位（AI seat） [#ai-seat] + +ObjectOS 的計價單位，也是每個版本中唯一計費的席位。檢視者、不使用產品內 AI 的應用 +使用者，以及通過 MCP 構建的開發者都是免費的。參見 +[許可證與定價](/docs/editions/license#editions)。 + +### 應用（App） [#app] + +一組物件 + 檢視 + 許可權，呈現為一個可導航的應用。一個執行時中可以並存多個應用（例如 +CRM + Helpdesk + Setup）。 + +### 產物（Artifact） [#artifact] + +一個編譯後的 `objectstack.json` 檔案。對應用的自包含、不可變的描述 —— 清單、物件、 +檢視、應用、流程、許可權、翻譯。由 `os compile` 產出。ObjectOS 實際執行的就是它。 + +### Better Auth [#better-auth] + +驅動 `@objectstack/plugin-auth` 的認證庫。你不需要直接配置 Better Auth；外掛封裝 +了它。 + +### 業務本體（Business ontology） [#business-ontology] + +你的應用的定義 —— 物件和欄位、關係、動作、許可權、流程，以及 Agent 和工具的定義 —— +作為一個可執行、有版本的整體：以帶型別的 ObjectStack 後設資料編寫，經過校驗而不是 +推理，並由執行時執行，執行時從中推匯出資料庫、REST API、UI 和 MCP 工具。檢視、 +儀表盤、應用和翻譯是它的[投影](#projection)，而不是它的一部分。 + +它是可執行的，而不是知識本體：沒有物件繼承，沒有公理，沒有推理機。它也不是語義層 +—— 那是覆蓋在現有系統之上的只讀對映，描述業務卻不執行業務。無論在哪個 ObjectOS +版本上它都屬於你：匯出它，就能在開源的 ObjectStack 執行時上執行。在本站參見 +[ObjectOS 中你的本體](/docs/ontology)；完整的闡述見 ObjectStack 文件中的 +[Business Ontology](https://objectstack.ai/docs/concepts/ontology)。 + +### 能力（Capability） [#capability] + +產物在其 `requires` 列表中宣告的可選執行時功能。對應一個包 —— 例如 `audit` → +`@objectstack/plugin-audit`。由 ObjectOS 按需載入。參見 +[執行時能力](/docs/reference/runtime-capabilities)。 + +### CEL [#cel] + +[Common Expression Language](https://github.com/google/cel-spec) —— Google 的 +安全、沙箱化的表示式語法。用於公式、驗證規則、許可權謂詞、共享規則和流程條件。 + +### 控制平面（Control Plane） [#control-plane] + +一項可選服務，向 ObjectOS 例項釋出有版本的產物。以 ObjectOS Cloud 的形式託管，或 +自託管。大多數部署不需要它 —— 基於檔案的模式足以支撐單應用的生產環境。 + +### 驅動（Driver） [#driver] + +資料後端的實現：`driver-sql`（Postgres、MySQL、SQLite、Turso/libSQL）、 +`driver-mongodb`、`driver-memory`。在啟動時通過資料庫 URL 選定。 + +### 嵌入器（Embedder） [#embedder] + +為 RAG / 語義搜尋把文本轉換為向量的服務。可在多個提供商之間插拔（OpenAI、Azure、 +矽基流動、Ollama……）。參見 [AI 服務](/docs/configure/ai)。 + +### 環境（Environment） [#environment] + +部署自身的身份 —— 它以 `OS_ENVIRONMENT_ID` 報告的 id，在雲繫結完成後持久儲存。 +自管理的 ObjectOS 是一個**單環境**執行時：一個程序、一個環境、一個應用。持有多個 +環境，併為每個環境釋出一個產物，是控制平面做的事。參見 +[環境變數](/docs/reference/environment-variables)。 + +### 欄位（Field） [#field] + +物件上的帶型別屬性。約 48 種內建型別：`text`、`select`、`lookup`、`markdown`、 +`file`、`formula`、`summary` 等。參見[資料模型](/docs/build/data)。 + +### 流程（Flow） [#flow] + +宣告式的業務邏輯 —— 自動啟動（記錄觸發）、定時（cron）或手動（按鈕 / API）。以帶有 +條件/迴圈/重試/並行原語的 DAG 形式執行。參見 +[流程與自動化](/docs/build/automation/flows)。 + +### 公式欄位（Formula field） [#formula-field] + +一種計算欄位，其值是在讀取時求值的 CEL 表示式。不儲存。 + +### 鉤子（Hook） [#hook] + +注入到物件生命週期中的函式（`beforeInsert`、`afterUpdate`……）。用 TypeScript +編寫。與流程不同：鉤子是一等的程式碼；流程是後設資料。 + +### 核心（Kernel） [#kernel] + +ObjectOS 內部的微核心，負責載入外掛、持有 DI 容器、分發事件，並提供部署的後設資料。 +一個程序在啟動時構建一個核心，在構建完成之前不會報告[就緒](/docs/deploy/docker) +—— 所以不會有任何按請求的邏輯去決定提供哪份後設資料。 + +### 清單（Manifest） [#manifest] + +位於產物開頭的頂層後設資料：`id`、`namespace`、`version`、`type`（`app` / `plugin` / +`service`）、`name`、`description`、`requires` 列表。 + +### 市場（Marketplace） [#marketplace] + +內建的可安裝應用目錄。由可配置的包登錄檔支撐。參見[市場](/docs/build/marketplace)。 + +### MCP（Model Context Protocol） [#mcp-model-context-protocol] + +一個讓 AI Agent 發現和呼叫工具的開放協議。每個 ObjectOS 部署都是位於 `/api/v1/mcp` +的 MCP 伺服器，預設開啟：每個物件都是一個工具，其作者暴露給 AI（`ai.exposed`）的 +每個動作也是。每次呼叫都以呼叫者的身份執行。參見 +[接入 AI 工具（MCP）](/docs/configure/mcp)。 + +### 物件（Object） [#object] + +一個帶型別的業務實體 —— `task`、`account`、`invoice`。以 TypeScript schema 宣告； +自動生成 REST API、檢視、審計條目和 RBAC 檢查點。參見[資料模型](/docs/build/data)。 + +### ObjectOS [#objectos] + +構建在 ObjectStack 之上的執行環境，一個產品、三個版本：**ObjectOS Community** —— +開源的執行時和 Console，在 Apache-2.0 下免費，在 objectstack 倉庫中開發； +**ObjectOS Cloud** —— 託管在瀏覽器中，無需安裝任何東西；以及 **ObjectOS +Enterprise** —— 需許可證，在你自己的基礎設施上自管理。Cloud 和 Enterprise 按 AI +席位計價，無論在哪個版本上，你都可以匯出你的本體並在開放的執行時上執行它。 +**本文件站點是關於 ObjectOS 的。** + +### ObjectQL [#objectql] + +資料層協議和查詢引擎。把宣告式查詢編譯為原生的 SQL / Mongo 查詢。REST 端點、UI、 +流程都使用它 —— 全部是同一個引擎。 + +### ObjectStack [#objectstack] + +開放的技術棧，Apache-2.0：執行業務本體的協議、微核心、SDK、CLI 和生產執行時 —— +即 `@objectstack/*` npm 包和執行時映象。ObjectOS 是構建在它之上的執行環境： +ObjectOS Community 就是這個開放的執行時和 Console，採用同樣的 Apache-2.0 許可， +而 ObjectOS Cloud 和 ObjectOS Enterprise 是建立在其上的商業版本。 + +### ObjectUI [#objectui] + +檢視層協議 —— 應用、檢視、頁面、儀表盤、動作、圖表、導航。ObjectOS 渲染 ObjectUI +宣告。 + +### 許可權集（Permission Set） [#permission-set] + +一組授權 —— 物件許可權、欄位許可權、系統許可權。直接附加到使用者，或通過崗位附加。是主要的 +授權單元。參見[許可權](/docs/configure/permissions)。 + +### 外掛（Plugin） [#plugin] + +用一項能力擴充套件執行時的框架包 —— `plugin-auth`、`plugin-security`、 +`plugin-audit`、`plugin-webhooks`、`mcp` 等。通過 DI + 生命週期鉤子 +（`init → start → destroy`）啟用。 + +### 崗位（Position） [#position] + +使用者所擔任的職能 —— "Sales Manager"、"Support Agent"、"Auditor"。從 ObjectStack +13 起唯一的人員分組概念，並且有意設計為扁平的：彙報結構改為放在業務單元樹上。崗位 +把應用和標籤頁定向到某個受眾、指定審批人，並把許可權集分配給擔任它的每個人。參見 +[崗位](/docs/configure/permissions/positions)。 + +### 專案（Project） [#project] + +**環境**的舊名稱。它仍保留在繼承來的配置和框架內部的識別符號中；ObjectOS 文件使用 +*環境*。 + +### 投影（Projection） [#projection] + +檢視、儀表盤、應用或翻譯：與[業務本體](#business-ontology)並列編寫、經過同一道 +[校驗關卡](#validation-gate)檢查的後設資料，但不是本體的一部分。投影呈現核心 —— 網格 +上的物件欄位、圖表上對物件的查詢、某個語言區域中的每個標籤。修改核心，它的投影會 +隨之變化；移除一個投影，它所展示的業務不會改變。參見 +[ObjectOS 中你的本體](/docs/ontology#the-projections)。 + +### 記錄共享（Record Share） [#record-share] + +針對特定記錄、授予一個接收方的直接訪問 —— 一個使用者（`user`）、一個團隊（`team`）、 +一個崗位（`position`）、一個業務單元（`business_unit`），或者一個業務單元連同其下 +的每個單元（`unit_and_subordinates`）。儲存為 `sys_record_share` 行，其 +`recipient_type` 列恰好取這五個值。不同於共享規則（宣告式條件）。 + +### Setup [#setup] + +內建的管理應用，位於 `/_console/` 所提供的 UI 中的 `/apps/setup`，由 `setup.access` +許可權門控。管理使用者、業務單元、團隊、崗位、許可權集、共享規則、記錄共享和 API 金鑰， +以及配置、診斷和整合。參見[配置](/docs/configure)。 + +### 共享規則（Sharing Rule） [#sharing-rule] + +一種基於條件授予記錄訪問的宣告式規則（"區域經理可以看到其所在區域的記錄"）。在查詢 +時求值，編譯為行級過濾條件。**沒有**條件而儲存的規則什麼都不共享 —— 它並不匹配 +全部。參見[記錄訪問](/docs/configure/permissions/record-access#both-switches-fail-closed)。 + +### Studio [#studio] + +內建的後設資料編寫介面，位於 `/_console/` 所提供的 UI 中的 `/studio`，由 +`studio.access` 許可權門控。後設資料本身在這裡被*設計* —— 包、物件、應用、流程和許可權集 +—— 每次一個包，分為四個支柱：Data、Automations、Interfaces、Access。它與 **Setup** +並列，而不是 Setup 的一部分：Setup 運營一個執行中的部署（它的人員、他們的授權、它的 +配置），Studio 編寫這個部署所執行的內容 —— 因此**許可權在 Studio 中設計，在 Setup 中 +分配**。與 Setup 不同，它不是 `/apps/` 下的應用；UI 把它作為獨立的路由子樹提供。 +參見[配置](/docs/configure#setup-and-studio)。 + +### 介面入口（Surface） [#surface] + +執行中的 ObjectOS 暴露的 HTTP 入口之一：`/`（REST API）和 `/_console/`（UI）。是 +兩個，不是三個 —— 賬戶**不是**一個獨立的入口。登入、註冊和賬戶自助服務都是 UI 內部 +的路由： + +| 賬戶介面 | 位於 | +|---|---| +| 登入 | `/_console/login` —— 你未登入時，每個受保護的頁面都會把你送到這裡 | +| 註冊 | `/_console/register` —— 除非部署停用了自助註冊 | +| 賬戶自助服務 | `/_console/apps/account` —— Account 應用，與位於 `/_console/apps/setup` 的 Setup 並列 | + +沒有 `/_account/` 入口。獨立的賬戶門戶被移除時，它也隨之退役，這些 URL 現在返回 404。 + +### 系統上下文（System Context） [#system-context] + +外掛、鉤子和種子指令碼在需要繞過安全檢查時使用的內部執行模式。可審計；不暴露給使用者 +程式碼。 + +### 租戶（Tenant） [#tenant] + +共享同一個部署的各組織之間的隔離邊界。隔離牆式租戶姿態會豎起這道牆，它是一項需 +許可證的能力。這些組織仍然共享部署的應用、資料庫和後設資料，所以這道牆隔開的是它們的 +資料和成員資格，而不是它們的模式。參見 +[多組織部署](/docs/reference/environment-variables#multi-organization-deployments)。 + +### 觸發器（Trigger） [#trigger] + +觸發流程的條件 —— 記錄事件（`after_insert`）、定時（cron）或手動呼叫。 + +### 校驗關卡（Validation gate） [#validation-gate] + +所有後設資料在執行之前都要通過的同一套檢查：`@objectstack/spec` 的 schema，以及那些 +捕獲能通過型別檢查、卻會在執行時靜默失敗的問題的編寫規則 —— 錯誤的 CEL 謂詞、對 +不存在之物的引用。`os validate` 和 `os compile` 在倉庫原始碼上執行它，執行時也會對每 +一次上線的後設資料寫入應用同一道關卡，無論它來自 AI Builder、Studio 還是後設資料 API。 +參見 ObjectStack 文件中的 +[Validating Metadata](https://objectstack.ai/docs/deployment/validating-metadata)。 + +### 檢視（View） [#view] + +宣告式的 UI 配置 —— 列表、表單、看板、日曆、甘特圖 —— 附加在物件上。ObjectOS 渲染 +它；你不需要編寫元件。 + +### Zod schema [#zod-schema] + +`@objectstack/spec` 使用的執行時 + 編譯時型別系統。每個物件、欄位、檢視、應用、流程 +都由一個 Zod schema 解析和校驗。JSON Schema、TypeScript 型別和 REST 請求校驗器都 +派生自同一組 Zod 定義。 From 14de03519591b2c4b36937f9e238e05809765a1c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 23:47:51 +0000 Subject: [PATCH 2/2] docs(i18n): zh-Hans for the Resources changelog Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QsR2jTxGkQdrLm4E6n23Ub --- content/docs/resources/changelog.zh-Hans.mdx | 584 ++++++++++++++++++ content/docs/resources/changelog.zh-Hant.mdx | 585 +++++++++++++++++++ 2 files changed, 1169 insertions(+) create mode 100644 content/docs/resources/changelog.zh-Hans.mdx create mode 100644 content/docs/resources/changelog.zh-Hant.mdx diff --git a/content/docs/resources/changelog.zh-Hans.mdx b/content/docs/resources/changelog.zh-Hans.mdx new file mode 100644 index 00000000..394be8d7 --- /dev/null +++ b/content/docs/resources/changelog.zh-Hans.mdx @@ -0,0 +1,584 @@ +--- +title: 更新日志与版本管理 +description: ObjectOS 如何进行版本管理、版本之间有哪些变化，以及支持哪些版本。 +editions: [community, cloud, enterprise] +translation: + source_sha: 323046628fabcce6da190adf852a2f76c7c2b603056f600290b8dbf3ef64dfd3 + guide_rev: 1 + mode: auto +--- + +## 版本管理策略 [#versioning-policy] + +ObjectOS 版本采用 **[语义化版本](https://semver.org/)** 的形式 `MAJOR.MINOR.PATCH`， +但有一个例外，如下表所述：在 v17 线上，次版本也可能包含破坏性变更。 + +| 版本变化 | 含义 | 你要做什么 | +|---|---|---| +| **补丁版本**（`14.7.0 → 14.7.1`） | 缺陷修复，没有行为变化 | 直接升级，无需修改应用 | +| **次版本**（`17.4 → 17.5`） | 新功能 —— 在 v17 线上还包括破坏性的修正。每个 17.x 版本的发布说明都用同样的话说明这一点：它是"按版本号而言的次版本，而不是按影响范围而言" | 在升级之前，阅读该版本的升级检查清单和[特定版本步骤](/docs/operate/upgrade#version-specific-steps) | +| **主版本**（`13 → 14`） | 在发布说明中记录的破坏性变更 | 升级前阅读迁移指南 | + +所有 `@objectstack/*` 包以同步的版本号一起发布 —— 它们作为一个矩阵一起测试，而不是 +各自独立测试。 + +## 兼容性矩阵 [#compatibility-matrix] + +| 组件 | 兼容规则 | +|---|---| +| ObjectOS 镜像 ↔ 编译后的产物 | 相同的次版本。14.7.x 镜像运行 14.7.x 产物；14.7 产物可能使用 14.0 镜像中不可用的功能。协议握手（`PROTOCOL_VERSION`，12.0+）会在安装时拒绝不兼容的包。 | +| ObjectOS ↔ CLI | 推荐使用相同的次版本。通过 `npm i -g` 安装的 CLI 会生成固定在它自身版本上的脚手架。 | +| ObjectOS ↔ 数据库驱动 | 驱动由镜像构建固定；需确认 Postgres ≥ 13 / MongoDB ≥ 5 / Turso（任何当前版本）。 | +| Node.js | **22 或更新** —— 从 17.0 起，每个已发布的 `@objectstack/*` 包的 `engines.node` 都是 `>=22.0.0`。Node 20 已于 2026-04-30 结束生命周期。 | + +## 支持窗口 [#support-windows] + +支持是**相对于当前主版本**定义的，而不是针对固定的日历： + +| 分支 | 状态 | +|---|---| +| 当前主版本（目前为 17.x） | 活跃开发；新功能和修复 | +| 上一个主版本（目前为 16.x） | 仅安全修复 | +| 更早的主版本 | 不再支持 | + +关键的安全修复会向后移植到当前和上一个主版本。其他所有修复都落在 `main` 上。与某个 +具体主版本相关的日期，会随该主版本的[发布说明](https://objectstack.ai/docs/releases) +一起公布。 + +## 发布说明 [#release-notes] + +已发布的 ObjectOS 版本及其 CHANGELOG 条目发布在： + +- **npm**：[`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) +- **GitHub**：[github.com/objectstack-ai/objectstack/releases](https://github.com/objectstack-ai/objectstack/releases) +- **源码 CHANGELOG**：[`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) +- **长篇发布说明**：每个版本一页，附带其升级检查清单，位于 [objectstack.ai/docs/releases](https://objectstack.ai/docs/releases) —— v17 线见 [v17](https://objectstack.ai/docs/releases/v17) + +要接收通知，请在 GitHub 上 watch +[github.com/objectstack-ai/objectstack](https://github.com/objectstack-ai/objectstack) +→ Releases。 + +## 近期要点 [#recent-highlights] + +下面的每个 17.x 次版本都会改变运行中部署的行为。每份升级检查清单中属于运维人员的 +部分，见[升级与回滚 → 特定版本步骤](/docs/operate/upgrade#version-specific-steps)。 + +### 17.7 [#177] + +`@objectstack` **17.7.0**（发布于 2026-10-06）是 v17 线的当前版本。它把凭据从此前 +被复制进去的副本中移出，并让一行你看不到的数据表现得像一行不存在的数据。完整说明： +[objectstack.ai/docs/releases/v17/17-7](https://objectstack.ai/docs/releases/v17/17-7)。 + +> **警告：**升级之后，请轮换每个流程密钥和 JWT 签名密钥，并重新签发私密的分享链接： +> 升级之前制作的副本仍留在审计轨迹中。在 17.7 上设置的密钥，更早的版本无法读取， +> 所以规划回滚时要考虑到这一点。参见 +> [升级与回滚 → 17.7](/docs/operate/upgrade#objectstack-177)。 + +变化了什么： + +- **凭据不再随副本传播**（安全）—— 流程的入站 `secret` 和 `http` 节点的 + `signingSecret` 迁移到一个只写存储中，审计轨迹不再记录凭据字段，凭据字段在每个 + 写入响应、记录事件、webhook 正文和流程触发记录中都会被掩码。 +- **公开表单只在显式开关打开时才公开**（破坏性）—— 只有当表单的 `sharing` 在 + `allowAnonymous` 和 `publicLink` 之外还设置了 `enabled: true` 时，才会匿名提供该 + 表单。只设置了后两者的表单会返回 `404 FORM_NOT_FOUND`。参见 + [视图](/docs/build/interface/views#public-forms)。 +- **你无法读取的行就是不存在的** —— 对调用者无法读取的行按 id 更新或删除，会返回 + `404 RECORD_NOT_FOUND`，按过滤条件更新或删除只会触及可读的行。 +- **读取和写入只返回已声明的字段** —— 没有任何元数据声明的列，例如已退役字段的残留 + 列，不再被返回；转换可用 `os migrate unmapped-columns` 读取它。参见 + [CLI](/docs/reference/cli#database-migrations--os-migrate)。 +- **应用代码只能通过元数据 API 访问存储的元数据** —— 钩子、动作和作业的代码不再 + 直接读写 `sys_metadata`，写入它的流程节点会被拒绝。 +- **日期、时间和数字跟随语言** —— 四项格式设置已退役，点名其中之一的设置写入会返回 + `400`。参见[本地化](/docs/configure/localization)。 +- **内存引擎不再能作为启动存储**，外部登录也不再自行关联到邮箱未验证的本地账户。 +- **Console（Studio）** —— 五次 objectui 固定版本移动；第一次修复了 17.6 中四个已知 + 的 console 问题。 + +### 17.6 [#176] + +`@objectstack` **17.6.0**（发布于 2026-10-02）在每一扇门上以同样的方式判定访问： +没有权限集的调用者什么都得不到，字段级安全覆盖每一个查询。完整说明： +[objectstack.ai/docs/releases/v17/17-6](https://objectstack.ai/docs/releases/v17/17-6)。 + +变化了什么： + +- **解析不到任何权限集的调用者对每个对象都会被拒绝**（破坏性，安全）—— 过去它会 + 被准入每一个没有任何权限集授予的对象。应用声明的匿名端点（`authRequired: false`） + 不能再读写对象，也没有任何受支持的渠道会给匿名调用者授予权限集。公开表单继续正常 + 工作。 +- **字段级安全覆盖每一个查询入口** —— 跨字段比较、活动流、审计轨迹、审批快照和 + 分析。审计轨迹和活动流只向非系统读者（包括管理员）显示关于该读者能读取的记录的行； + 17.7 的 `view_all_audit_log` 能力（平台管理员默认持有）把删除和登出轨迹还给了他们。 + 参见[审计日志](/docs/operate/audit-logs)。 +- **打包的流程拥有它的名称** —— 在部署中以打包流程的名称保存的流程会停止运行，开/关 + 切换只作用于打包的流程。参见[流程](/docs/build/automation/flows#visual-builder)。 +- **存储的元数据正文在每一处副本中都会被脱敏** —— 对静态存储的副本运行 + `os migrate audit-metadata-bodies --apply`。`/api/v1/meta` 上的数据源元数据需要 + `manage_platform_settings`。 +- **「is empty」也会匹配 `''` 和 `[]`**，在共享规则和视图中，作用于文本和多值字段。 +- **日期在每一扇门上都遵循同一条规则** —— `datetime` 的年份必须在 1000 到 9999 之间， + 导入只按 ISO 8601、导出自身的格式或年份在前的格式读取日期单元格。 +- **共享选项列表** —— 一种新的 `picklist` 元数据类型，字段按名称引用它，其他包可以 + 扩展它。 + +### 17.5 [#175] + +`@objectstack` **17.5.0**（发布于 2026-09-29）把若干默认值转向安全的一侧：定时任务 +在部署要求之前保持关闭，行级安全、分析和记录写入会拒绝它们无法兑现的内容。完整说明： +[objectstack.ai/docs/releases/v17/17-5](https://objectstack.ai/docs/releases/v17/17-5)。 + +> **警告：**一个升级后什么都不做的部署，不会运行任何定时流程，也不会运行任何打包的 +> cron 作业；隔离墙式部署在 `OS_PLATFORM_OWNER_EMAIL` 指定管理员之前没有任何平台 +> 管理员。参见[升级与回滚 → 17.5](/docs/operate/upgrade#objectstack-175)。 + +变化了什么： + +- **定时任务在部署开启之前保持关闭**（破坏性）—— + `OS_AUTOMATION_SCHEDULED_WORK_ENABLED` 门控每一个时间触发的流程和打包的 cron + 作业。参见[环境变量](/docs/reference/environment-variables#runtime-services)。 +- **隔离墙式部署只从 `OS_PLATFORM_OWNER_EMAIL` 获取平台管理员身份**（破坏性）—— + `admin_full_access` 授权不再赋予这一身份。 +- **已保存报表的整套机制被移除**（破坏性）—— `/api/v1/reports` 和定时报表投递， + 没有后继者。`report` 元数据类型、数据集和分析保持不变。参见 + [REST API](/docs/reference/rest-api#reports)。 +- **行级安全在遇到无法强制执行的谓词时失败即关闭**，没有 `check` 的策略现在会用它的 + `using` 约束插入和更新。 +- **分析只回答可以读取该对象的调用者** —— 其他人会被以 `403` 拒绝，与 `/data` 上 + 相同。 +- **决策节点走第一个匹配的分支** —— `mode: 'inclusive'` 会运行每一个为真的分支。从 + Studio 存储的决策节点在升级后采用新的含义。参见 + [流程](/docs/build/automation/flows#conditions-and-branches)。 +- **写入的值必须符合其声明的类型** —— `date` 为 `YYYY-MM-DD`，`datetime` 为 + ISO 8601，数字为其 JSON 写法；其他任何形式都是 `400 VALIDATION_FAILED`。 +- **验证规则可以通过查找读取一跳之外的记录**，CEL 增加了 + `current_user.can(object, verb)`。参见 + [验证规则](/docs/build/data/validation-rules#reading-a-related-record)和 + [CEL](/docs/reference/cel#permission-checks)。 +- **没有声明页大小的视图显示 50 行**，而不是 25 行。 + +### 17.4 [#174] + +`@objectstack` **17.4.0**（发布于 2026-09-09）把每个时长键重命名为带有其单位，并关闭 +了两条悄无声息的写入路径。完整说明： +[objectstack.ai/docs/releases/v17/17-4](https://objectstack.ai/docs/releases/v17/17-4)。 + +变化了什么： + +- **只读字段会从非系统的创建中剥离**，而不只是从更新中剥离 —— 在 `droppedFields` + 中报告。要预置这样的字段，请以系统身份进行。参见 + [验证规则](/docs/build/data/validation-rules)。 +- **每个时长键的名称都带有其单位**（破坏性）—— `timeout` 变为 `timeoutMs`， + `refreshInterval` 变为 `refreshIntervalSeconds`，依此类推，没有别名：旧写法会在 + 解析时被拒绝，并点名该键。 +- **会话上的 `positions` 是安全维度** —— 按岗位收窄的 Console 门控现在会为担任该 + 岗位的人生效。 +- **流程可以带着理由拒绝** —— 一个 `outcome: 'refused'` 的 `end` 节点，加上按记录 + 的 `message`。参见 + [流程](/docs/build/automation/flows#ending-a-run-completed-or-refused)。 +- **分析的日期范围是一个封闭的词汇表** —— 一个声明的预设或一对 `[start, end]`； + 其他任何形式都是 `400`。 +- **多组织运行时开源了** —— `@objectstack/organizations` 是一个已发布的包。 + +### 17.3 [#173] + +`@objectstack` **17.3.0**（发布于 2026-09-04）是 v17 线上最大的一个版本。完整说明： +[objectstack.ai/docs/releases/v17/17-3](https://objectstack.ai/docs/releases/v17/17-3)。 + +变化了什么： + +- **开放的自助注册必须声明**（破坏性）—— 没有声明受众姿态的应用只接受邀请，没有 + 待处理邀请的注册会以 `403 SELF_REGISTRATION_CLOSED` 被拒绝（全新安装上的第一个 + 账户不受此限）。 +- **共享授权按租户划定范围** —— 17.3 之前写入的 `sys_record_share` 行需要由运维人员 + 运行回填。参见[升级与回滚 → 17.3](/docs/operate/upgrade#objectstack-173)。 +- **权限存储故障会明确地失败**（`503`），而不是被解析为一个没有任何能力的用户。 +- **自动编号在每个组织内唯一**，现有的重复项会阻止新索引的建立：先运行 + `os migrate duplicates`。 +- **复合元数据寻址已退役** —— `/api/v1/meta/:type/:section/:name` 返回 + `404 ROUTE_NOT_FOUND`。参见[REST API](/docs/reference/rest-api#metadata--apiv1meta)。 +- **开关流程需要 `manage_metadata`。** +- **SDK** —— `client.projects.*` 变为 `client.environments.*`，没有别名。 + +### 17.2 [#172] + +`@objectstack` **17.2.0**（发布于 2026-08-23）不再让那些声明了一个无人求值的条件的 +写入看起来像条件写入。完整说明： +[objectstack.ai/docs/releases/v17/17-2](https://objectstack.ai/docs/releases/v17/17-2)。 + +变化了什么： + +- **按 id 写入不再丢弃谓词**（破坏性）—— 如果按 id 更新或删除的 `where` 点名了 + `id` 之外的内容，除非声明了 `multi: true`，否则会被拒绝；`data.id` 与 `where.id` + 不一致的写入会返回 `400 UPDATE_ID_MISMATCH`。 +- **`http_request_errors_total` 已退役** —— 基于它的面板读数恒为零；请使用 + `http_requests_total{status=~"5.."}`。 +- **外部数据源路由需要一项能力** —— `manage_platform_settings` 或 + `manage_metadata`。 +- **`os g agent` 已退役** —— 改为编写 Skill。 + +### 17.1 [#171] + +`@objectstack` **17.1.0**（发布于 2026-08-20）是 v17 线的第一个次版本。17.0 让*可编写的 +表面*变得响亮，17.1 则让运行时的回答变得响亮：承诺撤销访问权限的标志现在真的会撤销， +失败的读取不再被当作空读取返回，从未派发的流程不再被报告为一次失败的运行，从来不应 +可读的凭据也不再被返回。完整说明： +[objectstack.ai/docs/releases/v17/17-1](https://objectstack.ai/docs/releases/v17/17-1)。 + +> **警告：**17.1.0 按版本号而言是次版本，按影响范围而言却不是。它的若干安全修正会 +> 改变现有部署上谁能读、谁能写，而且没有任何迁移步骤来提醒你。前滚之前，请逐项完成 +> 完整说明中的 17.1.0 升级检查清单。 + +变化了什么： + +- **停用一个权限集或岗位，现在真的会停止授予访问权限**（安全）—— 这两种对象都带有 + 一个停用动作，其对话框承诺访问会停止，但从来没有任何东西读取这一列：一个以 + `active: false` 预置的岗位仍会授予它的权限集，一个以 `active: false` 预置的权限集 + 仍会返回平台管理员姿态。共享规则通过第二条路径触达用户，而这条路径从不经过那个 + 检查点，所以一条把记录共享给已停用岗位的规则会继续共享 —— 这些共享会在下一次 + 协调时被撤销。`active` 列缺失或为 NULL 的行不受影响。如果一个部署曾以为这个开关 + 不起作用而使用它，那么这是对线上数据的一次真实撤销，所以请先审核你已停用的行。 + 参见[权限集](/docs/configure/permissions/permission-sets)。 +- **随附的管理员权限集不再在 `*` 通配符上授予导出**（破坏性）—— `admin_full_access`、 + `organization_admin` 以及派生出的 `organization_admin_no_bypass` 带有 + `objects['*'].allowExport: true`，这让 17.0 的导出维度无法被拒绝：应用可以声明某个 + 对象谁都不能导出，平台却照样导出。导出现在按对象授予，写在应用自己的权限集中； + 我们有意不提供自动替代。读取不受影响 —— 这只收窄了批量外流。 +- **部分字段脱敏** —— `FieldSchema` 声明 `maskingRule`：封闭的预设枚举 `phone` / + `id_card` / `bank_account` / `email` / `name`，外加一个 `{ keepHead, keepTail }` 的 + 兜底写法。声明了规则的字段会以脱敏但仍可辨认的形式（`138****5678`）返回给每个非 + 系统调用方，字段的 `requiredPermissions` 就是解除脱敏的门槛。脱敏走唯一的运行时 + 通道，所以 API 调用方、浏览器用户和 CSV/XLSX 导出路由看到的是同一个值；被脱敏的 + 调用方无法在该字段上筛选、排序、分组或聚合。参见 + [字段级安全](/docs/configure/permissions/field-level-security)。 +- **两项 ObjectOS 不暴露的开放运行时能力** —— 17.1 新增了记录查看审计 + （`sys_audit_log` 中的 `read` 动作），以及一个只读层级，让记录的读者能看到它的审批 + 请求。两者都只能通过构造函数选项开启 —— `AuditPlugin` 的 `readAudit`、审批服务的 + `recordReaderVisibleObjects` —— 而 ObjectOS 运行时没有设置它们，所以在 ObjectOS + 部署上两者都不可用。 +- **三个流程入口共用一张如实的状态表** —— 被拒绝的派发不再被报告为一次失败的运行： + `404` 未找到，`409` `FLOW_DISABLED`，`422` `FLOW_NO_START_NODE`，`400` + `FLOW_FAILED` 则表示一次确实运行了但被拒绝的运行。自动化的 `trigger` 路由、动作 + 入口，以及声明为 `type: 'flow'` 的端点，现在读取同一份共享定义，而不是三份各自的 + 副本，`outputMapping` 也不再应用于失败的结果。调用方应根据 HTTP 状态分支，而不是 + 根据内部的 `success` 标志。参见[流程](/docs/build/automation/flows)。 +- **`error.code` 在每个入口都是封闭词汇** —— 抛出的代码如果不在平台的标准集合中， + 就不再进入 `error.code`；它改由新的可选字段 `declaredCode` 承载，这样应用自己的 + 拼写得以保留，而不会扩大平台的词汇。 +- **失败的读取不再读作空读取** —— 这是在元数据协议、汇总索引，以及级联删除和注册表 + 探测中一并关闭的一类反复出现的问题：一次*失败*的读取过去与一次确实什么都没找到的 + 读取无法区分，于是 upsert 的预加载会把每次更新都变成插入，而"删除这个会破坏什么" + 的回答是"什么都不会"。没有移除任何 `catch` —— 每一个都按错误类型加以区分，所以 + 尚未开通的表仍是无害的，其他一切都会暴露出来。 +- **编写时的门控延伸到运行时发布入口** —— 过去只有 `os build` / `os validate` 执行的 + 规则，现在也会判定运行时写入，所以 Studio 和元数据 API 无法写入 CLI 拒绝的内容。 + 升级之后请重新运行 `os build` / `os validate`：若干新的拒绝可能会让在 17.0 上 + 构建干净的 stack 失败，包括未知的 stack 顶层键、目标不是已声明页面的仪表盘页头 + `modal` 动作，以及点名了公式字段或根本没有点名字段的列表视图 `sort`。 +- **Console（Studio）** —— 两次 objectui 固定版本移动，带来了仪表盘组件的重新键控、 + 动作上结构化 `confirm` 对象的退役、指标小部件上的 `I18nLabel`，以及为挂载在子路径 + 下的控制台由宿主执行的 `submitBehavior.url` 重定向。 + +### 17.0 [#170] + +`@objectstack` **17.0.0**（发布于 2026-08-14）是一个说真话的版本：16.0 让*已声明的 +元数据*变得诚实，17.0 则对它周围的表面做了同样的事。完整说明： +[objectstack.ai/docs/releases/v17/17-0](https://objectstack.ai/docs/releases/v17/17-0)。 +变化了什么： + +- **Node.js 22 是下限**（破坏性）—— 在全部 50 个已发布的清单中，`engines.node` 从 + `>=18.0.0` 改为 `>=22.0.0`。CI、发布流水线和每个随附的 Docker 镜像本来就运行在 22 + 上；现在承诺与事实一致了。在 Node 22+ 上没有任何变化。如果你的 CI 固定了 Node + 版本，请把它固定为 22。 +- **批量导出是一项独立的特权**（破坏性）—— `allowExport` 未设置过去表示"继承读取"； + 现在它表示**拒绝**，`viewAllRecords` / `modifyAllRecords` 也不再授予它。包随附的 + 权限集会在升级时重新预置，所以 `admin_full_access` 和 `organization_admin` 仍能导出 + —— **在环境中编写的权限集则不会**。请为其用户需要导出的每个自定义权限集添加 + `allowExport: true`。参见[权限集](/docs/configure/permissions/permission-sets)。 +- **文件是一条记录，而不是列中的一个 blob** —— 媒体字段 + （`file`/`image`/`avatar`/`video`/`audio`）存储一个不透明的 `sys_file` id； + `{ url, name, size, … }` 对象变为*读取*（展开）形式。由于字节由平台掌管， + `accept` / `maxSize` 可以声明**并由服务器强制执行**，而不只是浏览器端的提示。 + `os migrate files-to-references` 执行这一转换。参见 + [字段类型](/docs/reference/field-types#media)。 +- **GraphQL 表面已移除**（破坏性）—— 它从第一天起就只有 schema：由于该服务从未被 + 分配，处理程序无条件返回 501。`/graphql` 现在返回 404。不受影响的是：把 `graphql` + 作为**外部**数据源的协议，那是别人的 API，而不是 ObjectOS 提供的 API。 +- **没有条件的共享规则什么都不共享，被停用的 RLS 策略就是停用的**（破坏性，安全）—— + 一条没有条件的已存储规则过去会被求值为*该对象的每一条记录*，而一个用 + `enabled: false` 关闭的 RLS 策略仍会贡献它的 OR 分支授权。现在两者都会失败关闭。 + 参见[记录访问](/docs/configure/permissions/record-access)。 +- **审批请求对其参与者可见**（安全）—— `getRequest` / `listRequests` / + `countRequests` 只应用了可见性规则中的租户那一半，所以任何已认证用户都能读取其租户 + 中的任何请求：载荷快照、决策历史和附件。 +- **审批人可以动态路由** —— 审批节点新增 `expression` 审批人（基于 `current.*` / + `trigger.*` / `vars.*` 的 CEL）、节点级的 `onEmptyApprovers` 策略，以及作者声明的 + 决策输出，它们会以 `.` 流程变量的形式恢复运行。参见 + [审批](/docs/build/automation/approvals)。 +- **出问题的数据源会在启动时大声报错** —— 有对象绑定的数据源必须连接成功，否则启动 + 失败；`objectql.init()` 拒绝在失效的数据驱动上启动；当某个数据源不再响应时， + `/api/v1/ready` 返回 503。过去这样的启动会干净地完成、以零退出，然后让绑定对象的 + 每一次读写都失败。 +- **`enable.apiMethods` 缩减为六个原语**（破坏性）—— 可编写的枚举正好是 `get`、 + `list`、`create`、`update`、`delete`、`bulk`。八个旧值是*派生的*有效操作；已存储 + 的旧值会在解析时被剔除，并给出一条点名其替代项的警告。 +- **失效元数据的清理仍在继续**（破坏性）—— `object.enable.trash` 和 `enable.mru`、 + `tool.requiresConfirmation`、`agent.tools[]`、`agent.knowledge`、 + `SkillSchema.permissions`、报表的 `aria` / `performance`、`flow.active`，以及一长串 + 被解析却被忽略的键都已移除。每一个都会在解析时拒绝，并给出升级处方，而不是被悄悄 + 剔除。运行 `os migrate meta --from 16` 来重写你的源文件。 +- **可编写的表面已封闭** —— 现在每一种可编写的元数据类型都会以点名的处方拒绝未知键， + 在解析路径上也是如此，而不只是在 `create()` 中。一个拼写错误会成为一个定位明确的 + 错误，而不是一个悄悄从未生效的设置。 + +### 16.0 [#160] + +`@objectstack` **16.0.0** 收拢了开发者表面，并让已声明的元数据变得诚实：调用方组织 +只有一个认可的名字，真正的多审批人治理，真正会触发的相对时间自动化，以及一次全平台的 +清理，把被悄悄忽略的元数据变成编写时的响亮错误。完整说明： +[objectstack.ai/docs/releases](https://objectstack.ai/docs/releases)。 +变化了什么： + +- **钩子/动作 `ctx` 上的 `tenantId` 别名已移除**（16.0，破坏性）—— 在每个 + `*.hook.ts` / `*.action.ts` 主体中，以 `ctx.user.organizationId` / + `ctx.session.organizationId` 读取调用方的组织（值不变；对于系统写入，`ctx.user` 为 + `undefined`）。驱动层的租户维度（`ExecutionContext.tenantId`）是一个不同的概念， + 不受影响。 +- **审批：法定人数、按组会签，以及元数据驱动的收件箱** —— 审批步骤支持 M-of-N 法定 + 人数（`minApprovals`），以及每组各需一位审批人的步骤，依据开启时的快照计票，并支持 + 外出（OOO）替代；一次驳回仍然一票否决，阈值会被钳制，因此错误配置永远不会造成死锁。 + 决策可以携带文件附件，进度（"2 of 3 · finance pending"）在服务端计算，而批准 / + 驳回 / 转派 / 退回 / 要求补充信息 / 催办 / 撤回 / 重新提交都是 + `sys_approval_request` 上声明的 `type:'api'` 动作 —— 审批收件箱通过其通用动作 + 运行时来渲染它们，而不是靠手写的按钮。 +- **相对时间自动化** —— 流程开始节点可以声明 `timeRelative`（`offsetDays: [60, 30, 7]` + 或 `withinDays`）；每日扫描会为每条匹配的记录启动一次流程，所以"在合同结束前 60 天 + 提醒我"终于可以直接实现 —— 不再需要只有在碰巧编辑时才会触发的日期相等条件。 +- **带筛选的汇总** —— `summaryOperations.filter` 让父记录的合计只聚合匹配的子行，并在 + 子行进入或离开该谓词时重新聚合。 +- **严格的仪表盘小部件**（16.0，破坏性）—— `DashboardWidgetSchema` 是 `.strict()`： + 未声明的键（拼写错误或已移除的内联分析键）会成为一个解析错误，点名该键并指向数据集 + 形态（`dataset` + `dimensions` + `values`），而不是悄悄地什么都不渲染。 +- **MCP：stdio 有了身份，Agent 有了检查器** —— stdio 自动启动改由独立的 + `OS_MCP_STDIO_ENABLED` 开关控制（默认关闭），并需要一个 `OS_MCP_STDIO_API_KEY=osk_...` + 主体，失败关闭，经过与 HTTP 相同的授权链解析（RLS/FLS/租户都会应用；没有 `system` + 绕过）。新的 `validate_expression` 工具让 Agent 在保存公式之前，先对照真实的对象 + schema 检查它。 +- **强制执行或移除的清理**（16.0，破坏性）—— 已声明却未强制执行的元数据现在会大声 + 报错：失效的字段/对象/Agent 属性被移除，或被标记为墓碑并附带指引；钩子事件从 18 个 + 合并为 8 个；验证规则失去了从未被求值的 `'delete'` 事件；webhook 的 `undelete` / + `api` 触发器被移除；未知的 `requires` 能力标记会在编写时被拒绝（`aiStudio` / + `aiSeat` 别名已不复存在 —— 请使用 kebab-case 的 `ai-studio` / `ai-seat`）。 +- **引擎掌管的系统行通过通用数据 API 只读**（ADR-0103）—— 作业、通知、审批运行时行、 + 共享行、审计轨迹、机密等都被锁定为 `get`/`list`，一个失败关闭的守卫会拒绝通过 + `/data` 进行的用户上下文写入。确实需要接受用户写入的第三方 `system` 对象必须声明 + `userActions`。 +- **日期逻辑不再说谎** —— `record.due_date == today()` 现在能够匹配（时间相等比较会被 + 改写，以强制转换字段操作数），而公式中的日期*算术*（`end - start + 1`、 + `today() + 30`）变为构建时错误，并指向 `daysBetween` / `daysFromNow` / `addDays` / + `addMonths` —— 那些表达式在运行时本来就总是出错并得到 `null`。 +- **批量导入用户默认使用 `passwordPolicy: 'auto'`** —— 有可送达渠道的行（真实邮箱 + + 已接入的邮件服务，或手机号 + 短信邀请路径）会收到邀请；只有无法触达的行才会得到一个 + 一次性临时密码（`must_change_password`）。如需旧的仅身份行为，请显式传入 + `passwordPolicy: 'none'`；每行的结果见 `rows[].delivery`。 + +### 14.x [#14x] + +ObjectOS One 和捆绑的服务器基于 `@objectstack` **14.7.0** 发布。运行时的启动契约没有 +变化 —— `createStandaloneStack` 接受同样的产物、环境和数据库设置 —— 但 13.0 和 14.0 +都在授权词汇上带来了破坏性变更，所以**从 ≤ 12.x 前滚之前，请审查你的权限元数据**。 +完整说明：[objectstack.ai/docs/releases](https://objectstack.ai/docs/releases)。 +14.x 中变化了什么： + +- **ADR-0090 词汇收拢完成**（14.0，破坏性）—— `book.audience` 以 + `{ permissionSet }` 门控（原为 `{ profile }`），`PortalSchema.profiles` → + `positions`，`RLSUserContextSchema.role` → `positions`（字符串数组）， + `sys_record_share.recipient_type: 'role'` → `'position'`。 +- **对象能力标志得到强制执行**（14.0，近乎破坏性）—— `enable.*` 标志从被解析却不使用 + 变成了真正的门控。`activities` 和 `feeds` 是默认开启、可以关闭的（默认 `true`； + `feeds: false` 会以 403 `FEEDS_DISABLED` 拒绝评论），`trackHistory` 驱动"历史" + 选项卡，`files` 需要主动开启（在 `enable: { files: true }` 之前返回 403 + `FILES_DISABLED`）。 +- **成员基线失去了删除权限**（14.2，破坏性）—— `member_default` 不再授予记录删除；请 + 通过按岗位分配的权限集，逐个对象重新授予。 +- **管理员用户管理与手机认证**（14.3）—— 直接创建用户 + （`POST /api/v1/auth/admin/create-user`，一次性密码并强制轮换）、批量导入 + （行/CSV/XLSX，试运行，upsert）、通过 `@objectstack/plugin-sms`（阿里云 / Twilio） + 以短信 OTP 进行的可选手机登录，以及一个 `sms` 通知渠道。 +- **数据生命周期契约**（14.4，ADR-0057）—— 对象声明 `lifecycle`（类别、保留、轮转、 + 归档）；默认开启的 LifecycleService 会清理、轮转和归档平台数据（`sys_activity` 14 + 天，`sys_audit_log` 热存储 90 天）。用 `OS_LIFECYCLE_DISABLED=1` 关闭；通过 + `lifecycle.retention_overrides` 调整。14.5 移除了各插件的 `retentionDays` / + `retentionSweepMs` 选项（`JobRunRetention`、`NotificationRetention`），改用 + 生命周期声明，并把带有生命周期类别的系统数据拆分到一个专用的遥测数据源 + （`OS_TELEMETRY_DB`）；`os db clean` 可回收 SQLite 空间。 +- **按生效日期的授权与委派**（14.4，ADR-0091）—— 岗位和权限集分配支持 + `valid_from` / `valid_until` 时间窗口（失败关闭，没有后台作业），`delegatable` + 岗位允许担任者在有限的时间窗口内自行委派（≤ 30 天，需要填写原因，绝不包括管理员 + 范围）。 +- **MCP 范围上限**（14.5，ADR-0090 D10）—— 通过 OAuth 连接的 Agent 以 + `effective_permission = scope_ceiling ∩ user_grants` 运行（`data:read` / + `data:write` / `actions:execute`），失败关闭。 +- **安全修复**（14.4–14.5）—— FLS 键必须带对象限定（裸键会悄悄地什么都匹配不到；现在 + 会被检查拒绝并提供自动修复）；设置和分享链接路由不再信任可伪造的 `x-user-id` 一类 + 请求头；分析查询的范围限定在调用方的读取筛选器之内。 + +### 13.x —— 权限模型 v2 [#13x--permission-model-v2] + +`@objectstack` **13.0** 重构了授权（ADR-0090）。破坏性变更： + +- **角色和简档收拢为岗位** —— `sys_role*` 表、`RoleSchema` / `defineRole`、元数据 + 种类 `role` / `profile`，以及 `ExecutionContext.roles[]` 都已不复存在；岗位是扁平 + 的，层级移到了业务单元树上。共享接收方已重命名（`role` → `position`， + `role_and_subordinates` → `unit_and_subordinates`）。 +- **自定义对象默认私有** —— 一个带有所有者、却没有显式 `sharingModel` 的对象现在是 + 私有的；`read` / `read_write` / `full` 这几个 OWD 别名已移除。声明 `sharingModel: + 'public_read_write'` 可恢复之前的行为。 +- **RBAC 关联表的写入受到门控** —— 对 `sys_user_position`、 + `sys_position_permission_set`、`sys_user_permission_set` 和 `sys_permission_set` + 的写入需要租户管理员或委派管理范围。 + +新增的还有：`everyone` / `guest` 受众锚点、委派管理（`PermissionSet.adminScope`）、 +带有逐层归因的 `explain()` 引擎、`os compile` 的访问矩阵快照门控、面向 MCP 客户端的 +自助 OAuth 2.1、编写时的安全检查（`validateSecurityPosture`）、按操作划分的 +`Object.requiredPermissions` 映射，以及包命名空间前缀的强制执行。从未被强制执行的 +schema（合规 / 脱敏 / 全局 RLS 配置）被直接移除。 + +### 12.x [#12x] + +`@objectstack` **12.0** 加固了 API 的默认姿态： + +- **默认拒绝匿名数据访问**（破坏性）—— `api.requireAuth` 现在默认为 `true`；匿名的 + `/data/*` 请求会得到 401。提供公开数据的部署必须用 `api: { requireAuth: false }` + 显式退出（启动时会有警告）。分享链接、公开表单、`/auth` 和 `/health` 不受影响。 +- **强制执行的协议握手** —— `PROTOCOL_VERSION` + `checkProtocolCompat()` 会在安装时 + 拒绝不兼容的包。 +- **自适应的记录界面** —— 记录根据字段复杂度推导出以页面还是以模态框/抽屉显示； + `FormField.span` 变为响应式（`'auto'` / `'full'`）；相关列表获得 `'primary'` + 选项卡提升。 +- **包随附的权限** —— 包声明默认权限集，它们在启动时实体化，并带有来源追踪。 +- **构建时检查** —— `lint-view-refs`、`validateListViewMode`、`validateFormLayout` + 以及破坏性操作的 RBAC 映射会对编译进行门控。 + +### 10.x [#10x] + +10.x 系列基于 `@objectstack` **10.0 – 10.2** 发布。每一项破坏性变更都落在多组织租户层， +所以单租户的 ObjectOS 部署无需任何配置变更即可从 9.x 前滚。变化了什么： + +- **行级组织范围拆分为独立插件**（10.0，破坏性）—— `organization_id` 自动标记、按组织 + 重放种子数据以及默认组织引导，从 `@objectstack/plugin-security` 移到了需主动启用的 + [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping)。 + 单组织部署更精简（不再需要在每次查询时剥离通配 RLS），而 `OS_MULTI_TENANT=true` + 仍会把该插件自动注册在 `plugin-security` 之前，所以由 CLI 驱动的项目无需修改代码。 + 按照 ADR-0002，*租户*是物理隔离（一个环境 = 一个数据库）；`organization_id` 是同一 + 数据库内的*逻辑*范围划分，所以它值得拥有自己的插件。 +- **不再自动创建个人工作区**（10.0，破坏性）—— `plugin-security` 不再为每个新用户创建 + 一个"`'s Workspace`"组织。用户现在要接受邀请，或显式创建自己的第一个组织 + （Slack / Linear / GitHub-Orgs 的模式）。第一个注册的用户 —— 会被自动提升为平台 + 管理员 —— 在多租户模式下仍会得到一个 `Default Organization`，以便其会话能够解析 + RLS；单租户部署不会创建任何组织。 +- **`record` 表单字段类型**（ADR-0014）—— `Record` 属性（例如对象的 + `fields` 映射）现在可以在 Studio 中作为一等表单字段编辑，而不是以原始 JSON 的形式 + 泄露出来，对象预览窗格也会挂载真正的 `ObjectGrid` 渲染器 —— 你预览到的就是将要 + 交付的。 +- **通过 `IEmbedder` 实现可插拔的嵌入** —— 一个新的嵌入器协议，外加 + [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai)； + 知识库 / RAG 适配器现在使用 `IEmbedder`，并被重命名以去掉 `plugin-` 前缀。 +- **公开表单** —— 在 `/f/:slug` 提供的匿名 Web-to-Lead / Web-to-Case 表单，一个统一的 + FormPage（公开的 `/f/:slug` + 内部的 `/forms/:name`），一个 `type: 'form'` 动作 + 变体，以及 `ObjectSchema` 上的 `defaultDetailForm`。 +- **云端身份拆分** —— `os cloud login` 现在与 `os login` 分开，云端控制平面移到了一个 + 私有仓库（开源运行时因此更精简），`objectstack init` 生成的项目又能构建和启动了。 + +### 9.x [#9x] + +9.x 系列在 10.0 切换之前运行于 `@objectstack` **9.0 – 9.11**。运行时的启动契约与 8.0 +相同 —— `createStandaloneStack` 仍接受同样的产物、环境和数据库设置 —— 所以 8.0 部署 +无需修改配置即可前滚。变化的是面向作者的表面： + +- **分析数据集是唯一的作者表面**（9.0，破坏性）—— 仪表盘小部件、报表和列表图表现在 + 绑定一个语义化的 `dataset`（`defineDataset(...)`），并**按名称**选择维度/度量。旧的 + 内联查询字段（小部件上的 `object`/`valueField`/`aggregate`，报表上的 + `objectName`/`columns`/`groupingsDown`，列表图表上的 `xAxisField`/`yAxisFields`） + 已被移除。迁移方法：把内联查询移入一个 `defineDataset`，并按名称引用它。 + `ChartTypeSchema` 还去掉了 8 个只会按其基础类型渲染的变体类型 + （`stacked-bar`→`bar`、`spline`→`line`、`bubble`→`scatter`，……）。 +- **更严格的构建时验证**（9.6–9.7）—— `os compile` 现在遇到裸字段引用（用 `amount` + 而不是 `record.amount`）、未知的 CEL 函数和错误的流程值插值语法时会**失败**，并 + 各自附带"你是不是想写"的提示。过去"能构建但悄悄出错"的 stack 现在会大声失败 —— + 升级后请重新运行 `os compile` 并修复它标出的问题。 +- **数字字段公式能计算混合算术**（9.7）—— `record.amount / 100` 和 + `record.price * 2` 现在会求值，而不是悄悄得到 `null`；不再需要 `/ 100.0` 这种浮点 + 字面量的变通写法。 +- **对象级 REST 门控，现已强制执行**（ADR-0049）—— 对象的 `apiEnabled: false` 会把它 + 从 REST 表面移除，`apiMethods` 白名单则限制可以访问哪些操作。此前这些会被解析， + 但不会被强制执行。 +- **包文档即元数据 + `book` 导航**（9.3–9.6）—— `src/docs/*.md` 注册为 `doc` 元数据； + `book` 元素（ADR-0046）声明一条按派生成员关系组织的导航主干，在 + `GET /api/v1/meta/book/:name/tree` 提供，并带有受众门控。 +- **`os package install`**（9.3）—— 从目录 id 或内联的物理隔离产物向运行中的运行时 + 安装包，用 `--email` / `--password` 进行认证。 +- **审批**（9.3）—— 退回修改（`maxRevisions`，默认 3）、由作业支撑的 SLA 自动升级、 + 列表搜索/分页，以及无需会话的双语批准/驳回确认链接。 +- **入站 webhook 流程触发器**（9.3）—— `type: 'api'` 流程会挂载一个经 HMAC 验证的 + `POST /api/v1/automation/hooks/:flowName/:hookId` 端点，提供幂等的、由队列支撑的 + 接收。 +- **通知保留默认开启**（9.5）—— 通知历史在 **90 天**后自动清理；把消息模块的 + `retentionDays` 设为 `0` 可永久保留历史。 +- **CLI 捆绑 AI 提供商 SDK**（9.0）—— 兼容 OpenAI 的提供商（DeepSeek、DashScope、 + SiliconFlow、OpenRouter、Cloudflare）在全局安装的 CLI 上开箱即用。 + +需要注意一项流程编写行为的变化：`create_record` 节点的 `outputVariable` 现在保存的是 +**创建出的记录对象**（原为单纯的 id），所以请把期望得到 id 的 `{var}` 引用更新为 +`{var.id}`。 + +### 8.0.x [#80x] + +ObjectOS One 和捆绑的服务器基于 `@objectstack` **8.0.1** 发布。 + +- **基于 Streamable HTTP 的 MCP** —— 每个部署都可以充当一个可通过网络访问的 + [Model Context Protocol](https://modelcontextprotocol.io) 服务器。用 + `OS_MCP_SERVER_ENABLED=true` 开启；端点位于 `/api/v1/mcp`，认证失败关闭（匿名请求 + 会被拒绝）。插件由 `@objectstack/plugin-mcp-server` 重命名为 `@objectstack/mcp`。 +- **自助 API 密钥** —— `POST /api/v1/keys` 会生成一个只显示一次的 `sys_api_key`。 + REST 数据和元数据 API（`/api/v1/data`、`/api/v1/meta`）现在通过与 MCP 相同的验证器 + 认证 API 密钥，并以密钥所有者的权限和记录级安全运行。 +- **字段级条件规则** —— `visibleWhen`、`readonlyWhen` 和 `requiredWhen` 由 ObjectQL + 在服务端强制执行，而不只是在表单界面中。 +- **可复用的 RLS 读取筛选器** —— `security.getReadFilter(object, context)` 暴露了 + 记录访问的读取范围；分析数据集、仪表盘和报表都桥接到它，并在无法应用该范围时失败 + 关闭。 +- **独立宿主 stack** —— 运行时随附一个单租户的 `createStandaloneStack` 宿主；7.x 中 + 连接云端、按主机名路由的 `createObjectOSStack` 包装器已被移除。从那时起，运行单独 + 发布的应用的部署通过 **URL** 指定那个产物。如今负责这件事的变量，以及不再起作用的 + 已退役拼写，参见[环境变量](/docs/reference/environment-variables#retired-names)。 + +### 5.0 —— `project` → `environment` 重命名（已发布） [#50--project--environment-rename-shipped] + +原先称为*项目*的运行时概念已被全面重命名为*环境*。受影响的有： + +- CLI 标志：`--environment` / `-e` +- HTTP 路径：`/api/v1/environments/:environmentId/...` +- 请求头：`X-Environment-Id` +- 环境变量：`OS_ENVIRONMENT_ID`（`OS_PROJECT_ID` 当时作为已弃用的别名保留；现在已不再 + 读取） +- 数据库列：`environment_id` +- JSON schema：`EnvironmentArtifact` + +## 升级 [#upgrading] + +机械步骤参见[升级与回滚](/docs/operate/upgrade)，你跨越的每个版本参见它的 +[特定版本步骤](/docs/operate/upgrade#version-specific-steps)。升级前的检查： + +1. 阅读从当前版本到目标版本之间每个次版本的 CHANGELOG 条目。 +2. 运行 `os diff `，找出破坏性的 schema 变更。 +3. 针对目标版本运行 `os doctor`。 +4. 在滚动整个集群之前，先启动一个金丝雀实例。 +5. 为镜像标签和产物版本都准备好回滚计划（两者独立滚动）。 + +## 报告回归问题 [#reporting-regressions] + +如果某个补丁版本或次版本破坏了原本正常的功能，请在 +[github.com/objectstack-ai/objectstack/issues](https://github.com/objectstack-ai/objectstack/issues) +提交缺陷，并写明你从哪个版本升级到哪个版本。我们把回归问题视为最高优先级的缺陷类别。 diff --git a/content/docs/resources/changelog.zh-Hant.mdx b/content/docs/resources/changelog.zh-Hant.mdx new file mode 100644 index 00000000..8a6d75b7 --- /dev/null +++ b/content/docs/resources/changelog.zh-Hant.mdx @@ -0,0 +1,585 @@ +--- +# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant +title: 更新日誌與版本管理 +description: ObjectOS 如何進行版本管理、版本之間有哪些變化，以及支援哪些版本。 +editions: [community, cloud, enterprise] +translation: + source_sha: 323046628fabcce6da190adf852a2f76c7c2b603056f600290b8dbf3ef64dfd3 + guide_rev: 1 + mode: auto +--- + +## 版本管理策略 [#versioning-policy] + +ObjectOS 版本採用 **[語義化版本](https://semver.org/)** 的形式 `MAJOR.MINOR.PATCH`， +但有一個例外，如下表所述：在 v17 線上，次版本也可能包含破壞性變更。 + +| 版本變化 | 含義 | 你要做什麼 | +|---|---|---| +| **補丁版本**（`14.7.0 → 14.7.1`） | 缺陷修復，沒有行為變化 | 直接升級，無需修改應用 | +| **次版本**（`17.4 → 17.5`） | 新功能 —— 在 v17 線上還包括破壞性的修正。每個 17.x 版本的釋出說明都用同樣的話說明這一點：它是"按版本號而言的次版本，而不是按影響範圍而言" | 在升級之前，閱讀該版本的升級檢查清單和[特定版本步驟](/docs/operate/upgrade#version-specific-steps) | +| **主版本**（`13 → 14`） | 在釋出說明中記錄的破壞性變更 | 升級前閱讀遷移指南 | + +所有 `@objectstack/*` 包以同步的版本號一起釋出 —— 它們作為一個矩陣一起測試，而不是 +各自獨立測試。 + +## 相容性矩陣 [#compatibility-matrix] + +| 元件 | 相容規則 | +|---|---| +| ObjectOS 映象 ↔ 編譯後的產物 | 相同的次版本。14.7.x 映象執行 14.7.x 產物；14.7 產物可能使用 14.0 映象中不可用的功能。協議握手（`PROTOCOL_VERSION`，12.0+）會在安裝時拒絕不相容的包。 | +| ObjectOS ↔ CLI | 推薦使用相同的次版本。通過 `npm i -g` 安裝的 CLI 會生成固定在它自身版本上的腳手架。 | +| ObjectOS ↔ 資料庫驅動 | 驅動由映象構建固定；需確認 Postgres ≥ 13 / MongoDB ≥ 5 / Turso（任何當前版本）。 | +| Node.js | **22 或更新** —— 從 17.0 起，每個已釋出的 `@objectstack/*` 包的 `engines.node` 都是 `>=22.0.0`。Node 20 已於 2026-04-30 結束生命週期。 | + +## 支援視窗 [#support-windows] + +支援是**相對於當前主版本**定義的，而不是針對固定的日曆： + +| 分支 | 狀態 | +|---|---| +| 當前主版本（目前為 17.x） | 活躍開發；新功能和修復 | +| 上一個主版本（目前為 16.x） | 僅安全修復 | +| 更早的主版本 | 不再支援 | + +關鍵的安全修復會向後移植到當前和上一個主版本。其他所有修復都落在 `main` 上。與某個 +具體主版本相關的日期，會隨該主版本的[釋出說明](https://objectstack.ai/docs/releases) +一起公佈。 + +## 釋出說明 [#release-notes] + +已釋出的 ObjectOS 版本及其 CHANGELOG 條目釋出在： + +- **npm**：[`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) +- **GitHub**：[github.com/objectstack-ai/objectstack/releases](https://github.com/objectstack-ai/objectstack/releases) +- **原始碼 CHANGELOG**：[`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) +- **長篇釋出說明**：每個版本一頁，附帶其升級檢查清單，位於 [objectstack.ai/docs/releases](https://objectstack.ai/docs/releases) —— v17 線見 [v17](https://objectstack.ai/docs/releases/v17) + +要接收通知，請在 GitHub 上 watch +[github.com/objectstack-ai/objectstack](https://github.com/objectstack-ai/objectstack) +→ Releases。 + +## 近期要點 [#recent-highlights] + +下面的每個 17.x 次版本都會改變執行中部署的行為。每份升級檢查清單中屬於運維人員的 +部分，見[升級與回滾 → 特定版本步驟](/docs/operate/upgrade#version-specific-steps)。 + +### 17.7 [#177] + +`@objectstack` **17.7.0**（釋出於 2026-10-06）是 v17 線的當前版本。它把憑據從此前 +被複制進去的副本中移出，並讓一行你看不到的資料表現得像一行不存在的資料。完整說明： +[objectstack.ai/docs/releases/v17/17-7](https://objectstack.ai/docs/releases/v17/17-7)。 + +> **警告：**升級之後，請輪換每個流程金鑰和 JWT 簽名金鑰，並重新簽發私密的分享連結： +> 升級之前製作的副本仍留在審計軌跡中。在 17.7 上設定的金鑰，更早的版本無法讀取， +> 所以規劃回滾時要考慮到這一點。參見 +> [升級與回滾 → 17.7](/docs/operate/upgrade#objectstack-177)。 + +變化了什麼： + +- **憑據不再隨副本傳播**（安全）—— 流程的入站 `secret` 和 `http` 節點的 + `signingSecret` 遷移到一個只寫儲存中，審計軌跡不再記錄憑據欄位，憑據欄位在每個 + 寫入響應、記錄事件、webhook 正文和流程觸發記錄中都會被掩碼。 +- **公開表單只在顯式開關開啟時才公開**（破壞性）—— 只有當表單的 `sharing` 在 + `allowAnonymous` 和 `publicLink` 之外還設定了 `enabled: true` 時，才會匿名提供該 + 表單。只設置了後兩者的表單會返回 `404 FORM_NOT_FOUND`。參見 + [檢視](/docs/build/interface/views#public-forms)。 +- **你無法讀取的行就是不存在的** —— 對呼叫者無法讀取的行按 id 更新或刪除，會返回 + `404 RECORD_NOT_FOUND`，按過濾條件更新或刪除只會觸及可讀的行。 +- **讀取和寫入只返回已宣告的欄位** —— 沒有任何後設資料宣告的列，例如已退役欄位的殘留 + 列，不再被返回；轉換可用 `os migrate unmapped-columns` 讀取它。參見 + [CLI](/docs/reference/cli#database-migrations--os-migrate)。 +- **應用程式碼只能通過後設資料 API 訪問儲存的後設資料** —— 鉤子、動作和作業的程式碼不再 + 直接讀寫 `sys_metadata`，寫入它的流程節點會被拒絕。 +- **日期、時間和數字跟隨語言** —— 四項格式設定已退役，點名其中之一的設定寫入會返回 + `400`。參見[本地化](/docs/configure/localization)。 +- **記憶體引擎不再能作為啟動儲存**，外部登入也不再自行關聯到郵箱未驗證的本地賬戶。 +- **Console（Studio）** —— 五次 objectui 固定版本移動；第一次修復了 17.6 中四個已知 + 的 console 問題。 + +### 17.6 [#176] + +`@objectstack` **17.6.0**（釋出於 2026-10-02）在每一扇門上以同樣的方式判定訪問： +沒有許可權集的呼叫者什麼都得不到，欄位級安全覆蓋每一個查詢。完整說明： +[objectstack.ai/docs/releases/v17/17-6](https://objectstack.ai/docs/releases/v17/17-6)。 + +變化了什麼： + +- **解析不到任何許可權集的呼叫者對每個物件都會被拒絕**（破壞性，安全）—— 過去它會 + 被准入每一個沒有任何許可權集授予的物件。應用宣告的匿名端點（`authRequired: false`） + 不能再讀寫物件，也沒有任何受支援的渠道會給匿名呼叫者授予許可權集。公開表單繼續正常 + 工作。 +- **欄位級安全覆蓋每一個查詢入口** —— 跨欄位比較、活動流、審計軌跡、審批快照和 + 分析。審計軌跡和活動流只向非系統讀者（包括管理員）顯示關於該讀者能讀取的記錄的行； + 17.7 的 `view_all_audit_log` 能力（平臺管理員預設持有）把刪除和登出軌跡還給了他們。 + 參見[審計日誌](/docs/operate/audit-logs)。 +- **打包的流程擁有它的名稱** —— 在部署中以打包流程的名稱儲存的流程會停止執行，開/關 + 切換隻作用於打包的流程。參見[流程](/docs/build/automation/flows#visual-builder)。 +- **儲存的後設資料正文在每一處副本中都會被脫敏** —— 對靜態儲存的副本執行 + `os migrate audit-metadata-bodies --apply`。`/api/v1/meta` 上的資料來源後設資料需要 + `manage_platform_settings`。 +- **「is empty」也會匹配 `''` 和 `[]`**，在共享規則和檢視中，作用於文本和多值欄位。 +- **日期在每一扇門上都遵循同一條規則** —— `datetime` 的年份必須在 1000 到 9999 之間， + 匯入只按 ISO 8601、匯出自身的格式或年份在前的格式讀取日期單元格。 +- **共享選項列表** —— 一種新的 `picklist` 後設資料型別，欄位按名稱引用它，其他包可以 + 擴充套件它。 + +### 17.5 [#175] + +`@objectstack` **17.5.0**（釋出於 2026-09-29）把若干預設值轉向安全的一側：定時任務 +在部署要求之前保持關閉，行級安全、分析和記錄寫入會拒絕它們無法兌現的內容。完整說明： +[objectstack.ai/docs/releases/v17/17-5](https://objectstack.ai/docs/releases/v17/17-5)。 + +> **警告：**一個升級後什麼都不做的部署，不會執行任何定時流程，也不會執行任何打包的 +> cron 作業；隔離牆式部署在 `OS_PLATFORM_OWNER_EMAIL` 指定管理員之前沒有任何平臺 +> 管理員。參見[升級與回滾 → 17.5](/docs/operate/upgrade#objectstack-175)。 + +變化了什麼： + +- **定時任務在部署開啟之前保持關閉**（破壞性）—— + `OS_AUTOMATION_SCHEDULED_WORK_ENABLED` 門控每一個時間觸發的流程和打包的 cron + 作業。參見[環境變數](/docs/reference/environment-variables#runtime-services)。 +- **隔離牆式部署只從 `OS_PLATFORM_OWNER_EMAIL` 獲取平臺管理員身份**（破壞性）—— + `admin_full_access` 授權不再賦予這一身份。 +- **已儲存報表的整套機制被移除**（破壞性）—— `/api/v1/reports` 和定時報表投遞， + 沒有後繼者。`report` 後設資料型別、資料集和分析保持不變。參見 + [REST API](/docs/reference/rest-api#reports)。 +- **行級安全在遇到無法強制執行的謂詞時失敗即關閉**，沒有 `check` 的策略現在會用它的 + `using` 約束插入和更新。 +- **分析只回答可以讀取該物件的呼叫者** —— 其他人會被以 `403` 拒絕，與 `/data` 上 + 相同。 +- **決策節點走第一個匹配的分支** —— `mode: 'inclusive'` 會執行每一個為真的分支。從 + Studio 儲存的決策節點在升級後採用新的含義。參見 + [流程](/docs/build/automation/flows#conditions-and-branches)。 +- **寫入的值必須符合其宣告的型別** —— `date` 為 `YYYY-MM-DD`，`datetime` 為 + ISO 8601，數字為其 JSON 寫法；其他任何形式都是 `400 VALIDATION_FAILED`。 +- **驗證規則可以通過查詢讀取一跳之外的記錄**，CEL 增加了 + `current_user.can(object, verb)`。參見 + [驗證規則](/docs/build/data/validation-rules#reading-a-related-record)和 + [CEL](/docs/reference/cel#permission-checks)。 +- **沒有宣告頁大小的檢視顯示 50 行**，而不是 25 行。 + +### 17.4 [#174] + +`@objectstack` **17.4.0**（釋出於 2026-09-09）把每個時長鍵重新命名為帶有其單位，並關閉 +了兩條悄無聲息的寫入路徑。完整說明： +[objectstack.ai/docs/releases/v17/17-4](https://objectstack.ai/docs/releases/v17/17-4)。 + +變化了什麼： + +- **只讀欄位會從非系統的建立中剝離**，而不只是從更新中剝離 —— 在 `droppedFields` + 中報告。要預置這樣的欄位，請以系統身份進行。參見 + [驗證規則](/docs/build/data/validation-rules)。 +- **每個時長鍵的名稱都帶有其單位**（破壞性）—— `timeout` 變為 `timeoutMs`， + `refreshInterval` 變為 `refreshIntervalSeconds`，依此類推，沒有別名：舊寫法會在 + 解析時被拒絕，並點名該鍵。 +- **會話上的 `positions` 是安全維度** —— 按崗位收窄的 Console 門控現在會為擔任該 + 崗位的人生效。 +- **流程可以帶著理由拒絕** —— 一個 `outcome: 'refused'` 的 `end` 節點，加上按記錄 + 的 `message`。參見 + [流程](/docs/build/automation/flows#ending-a-run-completed-or-refused)。 +- **分析的日期範圍是一個封閉的詞彙表** —— 一個宣告的預設或一對 `[start, end]`； + 其他任何形式都是 `400`。 +- **多組織執行時開源了** —— `@objectstack/organizations` 是一個已釋出的包。 + +### 17.3 [#173] + +`@objectstack` **17.3.0**（釋出於 2026-09-04）是 v17 線上最大的一個版本。完整說明： +[objectstack.ai/docs/releases/v17/17-3](https://objectstack.ai/docs/releases/v17/17-3)。 + +變化了什麼： + +- **開放的自助註冊必須宣告**（破壞性）—— 沒有宣告受眾姿態的應用只接受邀請，沒有 + 待處理邀請的註冊會以 `403 SELF_REGISTRATION_CLOSED` 被拒絕（全新安裝上的第一個 + 賬戶不受此限）。 +- **共享授權按租戶劃定範圍** —— 17.3 之前寫入的 `sys_record_share` 行需要由運維人員 + 執行回填。參見[升級與回滾 → 17.3](/docs/operate/upgrade#objectstack-173)。 +- **許可權儲存故障會明確地失敗**（`503`），而不是被解析為一個沒有任何能力的使用者。 +- **自動編號在每個組織內唯一**，現有的重複項會阻止新索引的建立：先執行 + `os migrate duplicates`。 +- **複合後設資料定址已退役** —— `/api/v1/meta/:type/:section/:name` 返回 + `404 ROUTE_NOT_FOUND`。參見[REST API](/docs/reference/rest-api#metadata--apiv1meta)。 +- **開關流程需要 `manage_metadata`。** +- **SDK** —— `client.projects.*` 變為 `client.environments.*`，沒有別名。 + +### 17.2 [#172] + +`@objectstack` **17.2.0**（釋出於 2026-08-23）不再讓那些聲明瞭一個無人求值的條件的 +寫入看起來像條件寫入。完整說明： +[objectstack.ai/docs/releases/v17/17-2](https://objectstack.ai/docs/releases/v17/17-2)。 + +變化了什麼： + +- **按 id 寫入不再丟棄謂詞**（破壞性）—— 如果按 id 更新或刪除的 `where` 點名了 + `id` 之外的內容，除非聲明瞭 `multi: true`，否則會被拒絕；`data.id` 與 `where.id` + 不一致的寫入會返回 `400 UPDATE_ID_MISMATCH`。 +- **`http_request_errors_total` 已退役** —— 基於它的面板讀數恆為零；請使用 + `http_requests_total{status=~"5.."}`。 +- **外部資料來源路由需要一項能力** —— `manage_platform_settings` 或 + `manage_metadata`。 +- **`os g agent` 已退役** —— 改為編寫 Skill。 + +### 17.1 [#171] + +`@objectstack` **17.1.0**（釋出於 2026-08-20）是 v17 線的第一個次版本。17.0 讓*可編寫的 +表面*變得響亮，17.1 則讓執行時的回答變得響亮：承諾撤銷訪問許可權的標誌現在真的會撤銷， +失敗的讀取不再被當作空讀取返回，從未派發的流程不再被報告為一次失敗的執行，從來不應 +可讀的憑據也不再被返回。完整說明： +[objectstack.ai/docs/releases/v17/17-1](https://objectstack.ai/docs/releases/v17/17-1)。 + +> **警告：**17.1.0 按版本號而言是次版本，按影響範圍而言卻不是。它的若干安全修正會 +> 改變現有部署上誰能讀、誰能寫，而且沒有任何遷移步驟來提醒你。前滾之前，請逐項完成 +> 完整說明中的 17.1.0 升級檢查清單。 + +變化了什麼： + +- **停用一個許可權集或崗位，現在真的會停止授予訪問許可權**（安全）—— 這兩種物件都帶有 + 一個停用動作，其對話方塊承諾訪問會停止，但從來沒有任何東西讀取這一列：一個以 + `active: false` 預置的崗位仍會授予它的許可權集，一個以 `active: false` 預置的許可權集 + 仍會返回平臺管理員姿態。共享規則通過第二條路徑觸達使用者，而這條路徑從不經過那個 + 檢查點，所以一條把記錄共享給已停用崗位的規則會繼續共享 —— 這些共享會在下一次 + 協調時被撤銷。`active` 列缺失或為 NULL 的行不受影響。如果一個部署曾以為這個開關 + 不起作用而使用它，那麼這是對線上資料的一次真實撤銷，所以請先稽核你已停用的行。 + 參見[許可權集](/docs/configure/permissions/permission-sets)。 +- **隨附的管理員許可權集不再在 `*` 萬用字元上授予匯出**（破壞性）—— `admin_full_access`、 + `organization_admin` 以及派生出的 `organization_admin_no_bypass` 帶有 + `objects['*'].allowExport: true`，這讓 17.0 的匯出維度無法被拒絕：應用可以宣告某個 + 物件誰都不能匯出，平臺卻照樣匯出。匯出現在按物件授予，寫在應用自己的許可權集中； + 我們有意不提供自動替代。讀取不受影響 —— 這隻收窄了批次外流。 +- **部分欄位脫敏** —— `FieldSchema` 宣告 `maskingRule`：封閉的預設列舉 `phone` / + `id_card` / `bank_account` / `email` / `name`，外加一個 `{ keepHead, keepTail }` 的 + 兜底寫法。聲明瞭規則的欄位會以脫敏但仍可辨認的形式（`138****5678`）返回給每個非 + 系統呼叫方，欄位的 `requiredPermissions` 就是解除脫敏的門檻。脫敏走唯一的執行時 + 通道，所以 API 呼叫方、瀏覽器使用者和 CSV/XLSX 匯出路由看到的是同一個值；被脫敏的 + 呼叫方無法在該欄位上篩選、排序、分組或聚合。參見 + [欄位級安全](/docs/configure/permissions/field-level-security)。 +- **兩項 ObjectOS 不暴露的開放執行時能力** —— 17.1 新增了記錄檢視審計 + （`sys_audit_log` 中的 `read` 動作），以及一個只讀層級，讓記錄的讀者能看到它的審批 + 請求。兩者都只能通過建構函式選項開啟 —— `AuditPlugin` 的 `readAudit`、審批服務的 + `recordReaderVisibleObjects` —— 而 ObjectOS 執行時沒有設定它們，所以在 ObjectOS + 部署上兩者都不可用。 +- **三個流程入口共用一張如實的狀態表** —— 被拒絕的派發不再被報告為一次失敗的執行： + `404` 未找到，`409` `FLOW_DISABLED`，`422` `FLOW_NO_START_NODE`，`400` + `FLOW_FAILED` 則表示一次確實運行了但被拒絕的執行。自動化的 `trigger` 路由、動作 + 入口，以及宣告為 `type: 'flow'` 的端點，現在讀取同一份共享定義，而不是三份各自的 + 副本，`outputMapping` 也不再應用於失敗的結果。呼叫方應根據 HTTP 狀態分支，而不是 + 根據內部的 `success` 標誌。參見[流程](/docs/build/automation/flows)。 +- **`error.code` 在每個入口都是封閉詞彙** —— 丟擲的程式碼如果不在平臺的標準集合中， + 就不再進入 `error.code`；它改由新的可選欄位 `declaredCode` 承載，這樣應用自己的 + 拼寫得以保留，而不會擴大平臺的詞彙。 +- **失敗的讀取不再讀作空讀取** —— 這是在後設資料協議、彙總索引，以及級聯刪除和登錄檔 + 探測中一併關閉的一類反覆出現的問題：一次*失敗*的讀取過去與一次確實什麼都沒找到的 + 讀取無法區分，於是 upsert 的預載入會把每次更新都變成插入，而"刪除這個會破壞什麼" + 的回答是"什麼都不會"。沒有移除任何 `catch` —— 每一個都按錯誤型別加以區分，所以 + 尚未開通的表仍是無害的，其他一切都會暴露出來。 +- **編寫時的門控延伸到執行時釋出入口** —— 過去只有 `os build` / `os validate` 執行的 + 規則，現在也會判定執行時寫入，所以 Studio 和後設資料 API 無法寫入 CLI 拒絕的內容。 + 升級之後請重新執行 `os build` / `os validate`：若干新的拒絕可能會讓在 17.0 上 + 構建乾淨的 stack 失敗，包括未知的 stack 頂層鍵、目標不是已宣告頁面的儀表盤頁頭 + `modal` 動作，以及點名了公式欄位或根本沒有點名欄位的列表檢視 `sort`。 +- **Console（Studio）** —— 兩次 objectui 固定版本移動，帶來了儀表盤元件的重新鍵控、 + 動作上結構化 `confirm` 物件的退役、指標小部件上的 `I18nLabel`，以及為掛載在子路徑 + 下的控制台由宿主執行的 `submitBehavior.url` 重定向。 + +### 17.0 [#170] + +`@objectstack` **17.0.0**（釋出於 2026-08-14）是一個說真話的版本：16.0 讓*已宣告的 +後設資料*變得誠實，17.0 則對它周圍的表面做了同樣的事。完整說明： +[objectstack.ai/docs/releases/v17/17-0](https://objectstack.ai/docs/releases/v17/17-0)。 +變化了什麼： + +- **Node.js 22 是下限**（破壞性）—— 在全部 50 個已釋出的清單中，`engines.node` 從 + `>=18.0.0` 改為 `>=22.0.0`。CI、釋出流水線和每個隨附的 Docker 映象本來就執行在 22 + 上；現在承諾與事實一致了。在 Node 22+ 上沒有任何變化。如果你的 CI 固定了 Node + 版本，請把它固定為 22。 +- **批次匯出是一項獨立的特權**（破壞性）—— `allowExport` 未設定過去表示"繼承讀取"； + 現在它表示**拒絕**，`viewAllRecords` / `modifyAllRecords` 也不再授予它。包隨附的 + 許可權集會在升級時重新預置，所以 `admin_full_access` 和 `organization_admin` 仍能匯出 + —— **在環境中編寫的許可權集則不會**。請為其使用者需要匯出的每個自定義許可權集新增 + `allowExport: true`。參見[許可權集](/docs/configure/permissions/permission-sets)。 +- **檔案是一條記錄，而不是列中的一個 blob** —— 媒體欄位 + （`file`/`image`/`avatar`/`video`/`audio`）儲存一個不透明的 `sys_file` id； + `{ url, name, size, … }` 物件變為*讀取*（展開）形式。由於位元組由平臺掌管， + `accept` / `maxSize` 可以宣告**並由伺服器強制執行**，而不只是瀏覽器端的提示。 + `os migrate files-to-references` 執行這一轉換。參見 + [欄位型別](/docs/reference/field-types#media)。 +- **GraphQL 表面已移除**（破壞性）—— 它從第一天起就只有 schema：由於該服務從未被 + 分配，處理程序無條件返回 501。`/graphql` 現在返回 404。不受影響的是：把 `graphql` + 作為**外部**資料來源的協議，那是別人的 API，而不是 ObjectOS 提供的 API。 +- **沒有條件的共享規則什麼都不共享，被停用的 RLS 策略就是停用的**（破壞性，安全）—— + 一條沒有條件的已儲存規則過去會被求值為*該物件的每一條記錄*，而一個用 + `enabled: false` 關閉的 RLS 策略仍會貢獻它的 OR 分支授權。現在兩者都會失敗關閉。 + 參見[記錄訪問](/docs/configure/permissions/record-access)。 +- **審批請求對其參與者可見**（安全）—— `getRequest` / `listRequests` / + `countRequests` 只應用了可見性規則中的租戶那一半，所以任何已認證使用者都能讀取其租戶 + 中的任何請求：載荷快照、決策歷史和附件。 +- **審批人可以動態路由** —— 審批節點新增 `expression` 審批人（基於 `current.*` / + `trigger.*` / `vars.*` 的 CEL）、節點級的 `onEmptyApprovers` 策略，以及作者宣告的 + 決策輸出，它們會以 `.` 流程變數的形式恢復執行。參見 + [審批](/docs/build/automation/approvals)。 +- **出問題的資料來源會在啟動時大聲報錯** —— 有物件繫結的資料來源必須連線成功，否則啟動 + 失敗；`objectql.init()` 拒絕在失效的資料驅動上啟動；當某個資料來源不再響應時， + `/api/v1/ready` 返回 503。過去這樣的啟動會乾淨地完成、以零退出，然後讓繫結物件的 + 每一次讀寫都失敗。 +- **`enable.apiMethods` 縮減為六個原語**（破壞性）—— 可編寫的列舉正好是 `get`、 + `list`、`create`、`update`、`delete`、`bulk`。八個舊值是*派生的*有效操作；已儲存 + 的舊值會在解析時被剔除，並給出一條點名其替代項的警告。 +- **失效後設資料的清理仍在繼續**（破壞性）—— `object.enable.trash` 和 `enable.mru`、 + `tool.requiresConfirmation`、`agent.tools[]`、`agent.knowledge`、 + `SkillSchema.permissions`、報表的 `aria` / `performance`、`flow.active`，以及一長串 + 被解析卻被忽略的鍵都已移除。每一個都會在解析時拒絕，並給出升級處方，而不是被悄悄 + 剔除。執行 `os migrate meta --from 16` 來重寫你的原始檔。 +- **可編寫的表面已封閉** —— 現在每一種可編寫的後設資料型別都會以點名的處方拒絕未知鍵， + 在解析路徑上也是如此，而不只是在 `create()` 中。一個拼寫錯誤會成為一個定位明確的 + 錯誤，而不是一個悄悄從未生效的設定。 + +### 16.0 [#160] + +`@objectstack` **16.0.0** 收攏了開發者表面，並讓已宣告的後設資料變得誠實：呼叫方組織 +只有一個認可的名字，真正的多審批人治理，真正會觸發的相對時間自動化，以及一次全平臺的 +清理，把被悄悄忽略的後設資料變成編寫時的響亮錯誤。完整說明： +[objectstack.ai/docs/releases](https://objectstack.ai/docs/releases)。 +變化了什麼： + +- **鉤子/動作 `ctx` 上的 `tenantId` 別名已移除**（16.0，破壞性）—— 在每個 + `*.hook.ts` / `*.action.ts` 主體中，以 `ctx.user.organizationId` / + `ctx.session.organizationId` 讀取呼叫方的組織（值不變；對於系統寫入，`ctx.user` 為 + `undefined`）。驅動層的租戶維度（`ExecutionContext.tenantId`）是一個不同的概念， + 不受影響。 +- **審批：法定人數、按組會簽，以及後設資料驅動的收件箱** —— 審批步驟支援 M-of-N 法定 + 人數（`minApprovals`），以及每組各需一位審批人的步驟，依據開啟時的快照計票，並支援 + 外出（OOO）替代；一次駁回仍然一票否決，閾值會被鉗制，因此錯誤配置永遠不會造成死鎖。 + 決策可以攜帶檔案附件，進度（"2 of 3 · finance pending"）在服務端計算，而批准 / + 駁回 / 轉派 / 退回 / 要求補充資訊 / 催辦 / 撤回 / 重新提交都是 + `sys_approval_request` 上宣告的 `type:'api'` 動作 —— 審批收件箱通過其通用動作 + 執行時來渲染它們，而不是靠手寫的按鈕。 +- **相對時間自動化** —— 流程開始節點可以宣告 `timeRelative`（`offsetDays: [60, 30, 7]` + 或 `withinDays`）；每日掃描會為每條匹配的記錄啟動一次流程，所以"在合同結束前 60 天 + 提醒我"終於可以直接實現 —— 不再需要只有在碰巧編輯時才會觸發的日期相等條件。 +- **帶篩選的彙總** —— `summaryOperations.filter` 讓父記錄的合計只聚合匹配的子行，並在 + 子行進入或離開該謂詞時重新聚合。 +- **嚴格的儀表盤小部件**（16.0，破壞性）—— `DashboardWidgetSchema` 是 `.strict()`： + 未宣告的鍵（拼寫錯誤或已移除的內聯分析鍵）會成為一個解析錯誤，點名該鍵並指向資料集 + 形態（`dataset` + `dimensions` + `values`），而不是悄悄地什麼都不渲染。 +- **MCP：stdio 有了身份，Agent 有了檢查器** —— stdio 自動啟動改由獨立的 + `OS_MCP_STDIO_ENABLED` 開關控制（預設關閉），並需要一個 `OS_MCP_STDIO_API_KEY=osk_...` + 主體，失敗關閉，經過與 HTTP 相同的授權鏈解析（RLS/FLS/租戶都會應用；沒有 `system` + 繞過）。新的 `validate_expression` 工具讓 Agent 在儲存公式之前，先對照真實的物件 + schema 檢查它。 +- **強制執行或移除的清理**（16.0，破壞性）—— 已宣告卻未強制執行的後設資料現在會大聲 + 報錯：失效的欄位/物件/Agent 屬性被移除，或被標記為墓碑並附帶指引；鉤子事件從 18 個 + 合併為 8 個；驗證規則失去了從未被求值的 `'delete'` 事件；webhook 的 `undelete` / + `api` 觸發器被移除；未知的 `requires` 能力標記會在編寫時被拒絕（`aiStudio` / + `aiSeat` 別名已不復存在 —— 請使用 kebab-case 的 `ai-studio` / `ai-seat`）。 +- **引擎掌管的系統行通過通用資料 API 只讀**（ADR-0103）—— 作業、通知、審批執行時行、 + 共享行、審計軌跡、機密等都被鎖定為 `get`/`list`，一個失敗關閉的守衛會拒絕通過 + `/data` 進行的使用者上下文寫入。確實需要接受使用者寫入的第三方 `system` 物件必須宣告 + `userActions`。 +- **日期邏輯不再說謊** —— `record.due_date == today()` 現在能夠匹配（時間相等比較會被 + 改寫，以強制轉換欄位運算元），而公式中的日期*算術*（`end - start + 1`、 + `today() + 30`）變為構建時錯誤，並指向 `daysBetween` / `daysFromNow` / `addDays` / + `addMonths` —— 那些表示式在執行時本來就總是出錯並得到 `null`。 +- **批次匯入使用者預設使用 `passwordPolicy: 'auto'`** —— 有可送達渠道的行（真實郵箱 + + 已接入的郵件服務，或手機號 + 簡訊邀請路徑）會收到邀請；只有無法觸達的行才會得到一個 + 一次性臨時密碼（`must_change_password`）。如需舊的僅身份行為，請顯式傳入 + `passwordPolicy: 'none'`；每行的結果見 `rows[].delivery`。 + +### 14.x [#14x] + +ObjectOS One 和捆綁的伺服器基於 `@objectstack` **14.7.0** 釋出。執行時的啟動契約沒有 +變化 —— `createStandaloneStack` 接受同樣的產物、環境和資料庫設定 —— 但 13.0 和 14.0 +都在授權詞彙上帶來了破壞性變更，所以**從 ≤ 12.x 前滾之前，請審查你的許可權後設資料**。 +完整說明：[objectstack.ai/docs/releases](https://objectstack.ai/docs/releases)。 +14.x 中變化了什麼： + +- **ADR-0090 詞彙收攏完成**（14.0，破壞性）—— `book.audience` 以 + `{ permissionSet }` 門控（原為 `{ profile }`），`PortalSchema.profiles` → + `positions`，`RLSUserContextSchema.role` → `positions`（字串陣列）， + `sys_record_share.recipient_type: 'role'` → `'position'`。 +- **物件能力標誌得到強制執行**（14.0，近乎破壞性）—— `enable.*` 標誌從被解析卻不使用 + 變成了真正的門控。`activities` 和 `feeds` 是預設開啟、可以關閉的（預設 `true`； + `feeds: false` 會以 403 `FEEDS_DISABLED` 拒絕評論），`trackHistory` 驅動"歷史" + 選項卡，`files` 需要主動開啟（在 `enable: { files: true }` 之前返回 403 + `FILES_DISABLED`）。 +- **成員基線失去了刪除許可權**（14.2，破壞性）—— `member_default` 不再授予記錄刪除；請 + 通過按崗位分配的許可權集，逐個物件重新授予。 +- **管理員使用者管理與手機認證**（14.3）—— 直接建立使用者 + （`POST /api/v1/auth/admin/create-user`，一次性密碼並強制輪換）、批次匯入 + （行/CSV/XLSX，試執行，upsert）、通過 `@objectstack/plugin-sms`（阿里雲 / Twilio） + 以簡訊 OTP 進行的可選手機登入，以及一個 `sms` 通知渠道。 +- **資料生命週期契約**（14.4，ADR-0057）—— 物件宣告 `lifecycle`（類別、保留、輪轉、 + 歸檔）；預設開啟的 LifecycleService 會清理、輪轉和歸檔平臺數據（`sys_activity` 14 + 天，`sys_audit_log` 熱儲存 90 天）。用 `OS_LIFECYCLE_DISABLED=1` 關閉；通過 + `lifecycle.retention_overrides` 調整。14.5 移除了各外掛的 `retentionDays` / + `retentionSweepMs` 選項（`JobRunRetention`、`NotificationRetention`），改用 + 生命週期宣告，並把帶有生命週期類別的系統資料拆分到一個專用的遙測資料來源 + （`OS_TELEMETRY_DB`）；`os db clean` 可回收 SQLite 空間。 +- **按生效日期的授權與委派**（14.4，ADR-0091）—— 崗位和許可權集分配支援 + `valid_from` / `valid_until` 時間視窗（失敗關閉，沒有後臺作業），`delegatable` + 崗位允許擔任者在有限的時間視窗內自行委派（≤ 30 天，需要填寫原因，絕不包括管理員 + 範圍）。 +- **MCP 範圍上限**（14.5，ADR-0090 D10）—— 通過 OAuth 連線的 Agent 以 + `effective_permission = scope_ceiling ∩ user_grants` 執行（`data:read` / + `data:write` / `actions:execute`），失敗關閉。 +- **安全修復**（14.4–14.5）—— FLS 鍵必須帶物件限定（裸鍵會悄悄地什麼都匹配不到；現在 + 會被檢查拒絕並提供自動修復）；設定和分享連結路由不再信任可偽造的 `x-user-id` 一類 + 請求頭；分析查詢的範圍限定在呼叫方的讀取篩選器之內。 + +### 13.x —— 許可權模型 v2 [#13x--permission-model-v2] + +`@objectstack` **13.0** 重構了授權（ADR-0090）。破壞性變更： + +- **角色和簡檔收攏為崗位** —— `sys_role*` 表、`RoleSchema` / `defineRole`、後設資料 + 種類 `role` / `profile`，以及 `ExecutionContext.roles[]` 都已不復存在；崗位是扁平 + 的，層級移到了業務單元樹上。共享接收方已重新命名（`role` → `position`， + `role_and_subordinates` → `unit_and_subordinates`）。 +- **自定義物件預設私有** —— 一個帶有所有者、卻沒有顯式 `sharingModel` 的物件現在是 + 私有的；`read` / `read_write` / `full` 這幾個 OWD 別名已移除。宣告 `sharingModel: + 'public_read_write'` 可恢復之前的行為。 +- **RBAC 關聯表的寫入受到門控** —— 對 `sys_user_position`、 + `sys_position_permission_set`、`sys_user_permission_set` 和 `sys_permission_set` + 的寫入需要租戶管理員或委派管理範圍。 + +新增的還有：`everyone` / `guest` 受眾錨點、委派管理（`PermissionSet.adminScope`）、 +帶有逐層歸因的 `explain()` 引擎、`os compile` 的訪問矩陣快照門控、面向 MCP 客戶端的 +自助 OAuth 2.1、編寫時的安全檢查（`validateSecurityPosture`）、按操作劃分的 +`Object.requiredPermissions` 對映，以及包名稱空間字首的強制執行。從未被強制執行的 +schema（合規 / 脫敏 / 全域性 RLS 配置）被直接移除。 + +### 12.x [#12x] + +`@objectstack` **12.0** 加固了 API 的預設姿態： + +- **預設拒絕匿名資料訪問**（破壞性）—— `api.requireAuth` 現在預設為 `true`；匿名的 + `/data/*` 請求會得到 401。提供公開資料的部署必須用 `api: { requireAuth: false }` + 顯式退出（啟動時會有警告）。分享連結、公開表單、`/auth` 和 `/health` 不受影響。 +- **強制執行的協議握手** —— `PROTOCOL_VERSION` + `checkProtocolCompat()` 會在安裝時 + 拒絕不相容的包。 +- **自適應的記錄介面** —— 記錄根據欄位複雜度推匯出以頁面還是以模態框/抽屜顯示； + `FormField.span` 變為響應式（`'auto'` / `'full'`）；相關列表獲得 `'primary'` + 選項卡提升。 +- **包隨附的許可權** —— 包宣告預設許可權集，它們在啟動時實體化，並帶有來源追蹤。 +- **構建時檢查** —— `lint-view-refs`、`validateListViewMode`、`validateFormLayout` + 以及破壞性操作的 RBAC 對映會對編譯進行門控。 + +### 10.x [#10x] + +10.x 系列基於 `@objectstack` **10.0 – 10.2** 釋出。每一項破壞性變更都落在多組織租戶層， +所以單租戶的 ObjectOS 部署無需任何配置變更即可從 9.x 前滾。變化了什麼： + +- **行級組織範圍拆分為獨立外掛**（10.0，破壞性）—— `organization_id` 自動標記、按組織 + 重放種子資料以及預設組織引導，從 `@objectstack/plugin-security` 移到了需主動啟用的 + [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping)。 + 單組織部署更精簡（不再需要在每次查詢時剝離通配 RLS），而 `OS_MULTI_TENANT=true` + 仍會把該外掛自動註冊在 `plugin-security` 之前，所以由 CLI 驅動的專案無需修改程式碼。 + 按照 ADR-0002，*租戶*是物理隔離（一個環境 = 一個數據庫）；`organization_id` 是同一 + 資料庫內的*邏輯*範圍劃分，所以它值得擁有自己的外掛。 +- **不再自動建立個人工作區**（10.0，破壞性）—— `plugin-security` 不再為每個新使用者建立 + 一個"`'s Workspace`"組織。使用者現在要接受邀請，或顯式建立自己的第一個組織 + （Slack / Linear / GitHub-Orgs 的模式）。第一個註冊的使用者 —— 會被自動提升為平臺 + 管理員 —— 在多租戶模式下仍會得到一個 `Default Organization`，以便其會話能夠解析 + RLS；單租戶部署不會建立任何組織。 +- **`record` 表單欄位型別**（ADR-0014）—— `Record` 屬性（例如物件的 + `fields` 對映）現在可以在 Studio 中作為一等表單欄位編輯，而不是以原始 JSON 的形式 + 洩露出來，物件預覽窗格也會掛載真正的 `ObjectGrid` 渲染器 —— 你預覽到的就是將要 + 交付的。 +- **通過 `IEmbedder` 實現可插拔的嵌入** —— 一個新的嵌入器協議，外加 + [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai)； + 知識庫 / RAG 介面卡現在使用 `IEmbedder`，並被重新命名以去掉 `plugin-` 字首。 +- **公開表單** —— 在 `/f/:slug` 提供的匿名 Web-to-Lead / Web-to-Case 表單，一個統一的 + FormPage（公開的 `/f/:slug` + 內部的 `/forms/:name`），一個 `type: 'form'` 動作 + 變體，以及 `ObjectSchema` 上的 `defaultDetailForm`。 +- **雲端身份拆分** —— `os cloud login` 現在與 `os login` 分開，雲端控制平面移到了一個 + 私有倉庫（開源執行時因此更精簡），`objectstack init` 生成的專案又能構建和啟動了。 + +### 9.x [#9x] + +9.x 系列在 10.0 切換之前運行於 `@objectstack` **9.0 – 9.11**。執行時的啟動契約與 8.0 +相同 —— `createStandaloneStack` 仍接受同樣的產物、環境和資料庫設定 —— 所以 8.0 部署 +無需修改配置即可前滾。變化的是面向作者的表面： + +- **分析資料集是唯一的作者表面**（9.0，破壞性）—— 儀表盤小部件、報表和列表圖表現在 + 繫結一個語義化的 `dataset`（`defineDataset(...)`），並**按名稱**選擇維度/度量。舊的 + 內聯查詢欄位（小部件上的 `object`/`valueField`/`aggregate`，報表上的 + `objectName`/`columns`/`groupingsDown`，列表圖表上的 `xAxisField`/`yAxisFields`） + 已被移除。遷移方法：把內聯查詢移入一個 `defineDataset`，並按名稱引用它。 + `ChartTypeSchema` 還去掉了 8 個只會按其基礎型別渲染的變體型別 + （`stacked-bar`→`bar`、`spline`→`line`、`bubble`→`scatter`，……）。 +- **更嚴格的構建時驗證**（9.6–9.7）—— `os compile` 現在遇到裸欄位引用（用 `amount` + 而不是 `record.amount`）、未知的 CEL 函式和錯誤的流程值插值語法時會**失敗**，並 + 各自附帶"你是不是想寫"的提示。過去"能構建但悄悄出錯"的 stack 現在會大聲失敗 —— + 升級後請重新執行 `os compile` 並修復它標出的問題。 +- **數字欄位公式能計算混合算術**（9.7）—— `record.amount / 100` 和 + `record.price * 2` 現在會求值，而不是悄悄得到 `null`；不再需要 `/ 100.0` 這種浮點 + 字面量的變通寫法。 +- **物件級 REST 門控，現已強制執行**（ADR-0049）—— 物件的 `apiEnabled: false` 會把它 + 從 REST 表面移除，`apiMethods` 白名單則限制可以訪問哪些操作。此前這些會被解析， + 但不會被強制執行。 +- **包文件即後設資料 + `book` 導航**（9.3–9.6）—— `src/docs/*.md` 註冊為 `doc` 後設資料； + `book` 元素（ADR-0046）宣告一條按派生成員關係組織的導航主幹，在 + `GET /api/v1/meta/book/:name/tree` 提供，並帶有受眾門控。 +- **`os package install`**（9.3）—— 從目錄 id 或內聯的物理隔離產物向執行中的執行時 + 安裝包，用 `--email` / `--password` 進行認證。 +- **審批**（9.3）—— 退回修改（`maxRevisions`，預設 3）、由作業支撐的 SLA 自動升級、 + 列表搜尋/分頁，以及無需會話的雙語批准/駁回確認連結。 +- **入站 webhook 流程觸發器**（9.3）—— `type: 'api'` 流程會掛載一個經 HMAC 驗證的 + `POST /api/v1/automation/hooks/:flowName/:hookId` 端點，提供冪等的、由佇列支撐的 + 接收。 +- **通知保留預設開啟**（9.5）—— 通知歷史在 **90 天**後自動清理；把訊息模組的 + `retentionDays` 設為 `0` 可永久保留歷史。 +- **CLI 捆綁 AI 提供商 SDK**（9.0）—— 相容 OpenAI 的提供商（DeepSeek、DashScope、 + SiliconFlow、OpenRouter、Cloudflare）在全域性安裝的 CLI 上開箱即用。 + +需要注意一項流程編寫行為的變化：`create_record` 節點的 `outputVariable` 現在儲存的是 +**創建出的記錄物件**（原為單純的 id），所以請把期望得到 id 的 `{var}` 引用更新為 +`{var.id}`。 + +### 8.0.x [#80x] + +ObjectOS One 和捆綁的伺服器基於 `@objectstack` **8.0.1** 釋出。 + +- **基於 Streamable HTTP 的 MCP** —— 每個部署都可以充當一個可通過網路訪問的 + [Model Context Protocol](https://modelcontextprotocol.io) 伺服器。用 + `OS_MCP_SERVER_ENABLED=true` 開啟；端點位於 `/api/v1/mcp`，認證失敗關閉（匿名請求 + 會被拒絕）。外掛由 `@objectstack/plugin-mcp-server` 重新命名為 `@objectstack/mcp`。 +- **自助 API 金鑰** —— `POST /api/v1/keys` 會生成一個只顯示一次的 `sys_api_key`。 + REST 資料和後設資料 API（`/api/v1/data`、`/api/v1/meta`）現在通過與 MCP 相同的驗證器 + 認證 API 金鑰，並以金鑰所有者的許可權和記錄級安全執行。 +- **欄位級條件規則** —— `visibleWhen`、`readonlyWhen` 和 `requiredWhen` 由 ObjectQL + 在服務端強制執行，而不只是在表單介面中。 +- **可複用的 RLS 讀取篩選器** —— `security.getReadFilter(object, context)` 暴露了 + 記錄訪問的讀取範圍；分析資料集、儀表盤和報表都橋接到它，並在無法應用該範圍時失敗 + 關閉。 +- **獨立宿主 stack** —— 執行時隨附一個單租戶的 `createStandaloneStack` 宿主；7.x 中 + 連線雲端、按主機名路由的 `createObjectOSStack` 包裝器已被移除。從那時起，執行單獨 + 釋出的應用的部署通過 **URL** 指定那個產物。如今負責這件事的變數，以及不再起作用的 + 已退役拼寫，參見[環境變數](/docs/reference/environment-variables#retired-names)。 + +### 5.0 —— `project` → `environment` 重新命名（已釋出） [#50--project--environment-rename-shipped] + +原先稱為*專案*的執行時概念已被全面重新命名為*環境*。受影響的有： + +- CLI 標誌：`--environment` / `-e` +- HTTP 路徑：`/api/v1/environments/:environmentId/...` +- 請求頭：`X-Environment-Id` +- 環境變數：`OS_ENVIRONMENT_ID`（`OS_PROJECT_ID` 當時作為已棄用的別名保留；現在已不再 + 讀取） +- 資料庫列：`environment_id` +- JSON schema：`EnvironmentArtifact` + +## 升級 [#upgrading] + +機械步驟參見[升級與回滾](/docs/operate/upgrade)，你跨越的每個版本參見它的 +[特定版本步驟](/docs/operate/upgrade#version-specific-steps)。升級前的檢查： + +1. 閱讀從當前版本到目標版本之間每個次版本的 CHANGELOG 條目。 +2. 執行 `os diff `，找出破壞性的 schema 變更。 +3. 針對目標版本執行 `os doctor`。 +4. 在滾動整個叢集之前，先啟動一個金絲雀例項。 +5. 為映象標籤和產物版本都準備好回滾計劃（兩者獨立滾動）。 + +## 報告迴歸問題 [#reporting-regressions] + +如果某個補丁版本或次版本破壞了原本正常的功能，請在 +[github.com/objectstack-ai/objectstack/issues](https://github.com/objectstack-ai/objectstack/issues) +提交缺陷，並寫明你從哪個版本升級到哪個版本。我們把迴歸問題視為最高優先順序的缺陷類別。