官方 X 宣布它是“测试版可用”，而官方存储库指出它“一般不可用”。围绕“概念即代码”的误解还不止于此。我应该创建一个新的工作区还是使用现有的工作区？两个答案并排保留在同一个存储库中。
Notion 宣布了“Notion as Code”，它允许您使用代码批量构建和更新工作区。官方的
在 TypeScript 中编写配置并将其发送到实验 API 端点 /v1/infra_as_code。该过程是异步的，并使用响应 ID 作为任务 ID 来查询 GET /v1/async_tasks/{taskId}。该指南需要个人访问令牌而不是机器人令牌进行身份验证。通过使用资源 ID（而不是 ID）指定目标，并使用第一次部署后返回的对应表，可以重新部署脚本。
该指南指出不支持创建新空间，并且速率限制为每分钟 5 个请求。
从： 
如何使用概念作为代码
[参考视频]
Notion CLI演示视频（Notion官方）
演示视频以官方发行说明“3.5：Notion Developer Platform”为指导。您可以检查开发人员和编码代理的 CLI 操作情况。
数据源联动演示视频（官方说法）
发行说明中还显示了演示视频。使用 Workers 处理外部数据导入。
【编辑部评论】
概念即代码带来的变化不仅仅是更多的功能。从根本上改变您处理工作空间的方式是。
到目前为止，公共 API 是“势在必行”的。每次发出请求时，例如创建页面或重写一个属性，调用方负责顺序和错误处理。概念即代码最后声明你想要的结构，把相应资源的创建和更新留给Notion。。与 Terraform 和 Pulumi 在基础设施管理方面相同的理念已被引入知识工作的容器中。
性格上的差异明显体现在速率限制上。传统公共 API 平均每个连接每秒 3 个请求，这意味着每分钟大约 180 个请求。另一方面，概念即代码每分钟有 5 个请求。如果你只看数字，那就困难得多，但是这个一个请求不再对应一个实体这一事实的另一面认为也有。通过一次传输，团队空间和页面将立即启动并运行。颗粒大小本身发生了变化。
原来的配置是用TypeScript写的，但是如果丢失了对应表的JSON就太可惜了。
实践中最需要注意的是资源ID和Notion记录的对应表。
TypeScript 源是你编写你想要的结构的地方，这就是 git 管理的蓝图。另一方面，第一次应用后返回的对应表是一个将蓝图与Notion上的实际对象连接起来的账本。因为角色不同，即使您对其中一个进行了版本控制，如果您失去了另一个，情况也会发生变化。
对应表为{"hub-page": {"id": "456", "table": "block"}}（这是指南中给出的一个简单示例）。下次重新部署时，使用此existingResources如果您将其传递为 ，则将更新相同的记录。如果未通过，将创建新记录。
这个角色类似于Terraform中状态文件中负责识别资源的部分。至少根据公布的规范，如果不通过这个对应表，Notion会创建一条新记录。
换句话说，如果你丢失了这个对应表，你的更新意图就会变成重复的。。如果你用git管理你的配置，这个账本的存储和备份必须设计成具有相同的强度。
当谈到“you can track it with git”这句话时，Notion 有一个特定的陷阱
消息发布后，立即有人指出，在 X 中，TypeScript 中的声明部分更容易，而当有人手动编辑数据库的那一刻，Git 就变成了整齐的记录。
我认为这是有道理的。在 IaC 领域，这是一个称为“漂移”的经典问题。使用 Notion 可能会更棘手。在 IaC 管理的云基础设施中，标准做法是避免手动更改并将操作整合到代码和变更管理渠道中。然而，Notion是一个工具，其核心价值在于它允许非工程师自由地重新安排其结构。
代码中声明的结构和现场开发的结构。如何让这两者共存，不是功能能够解决的。需要设计操作规则。。
身份验证的含义从机器人变为“个人”
还有一个很容易被忽视的规范。该指南将引导您完成的步骤将要求您使用机器人令牌而不是传统的机器人令牌。请求个人访问令牌我会。目前的官方模板还允许您使用CLI登录。在这两种情况下，都是使用个人通过授权访问工作区而获得的凭据来执行处理。
个人访问令牌将于 2026 年 5 月 13 日发行。Notion开发者平台（3.5）它一直由.维护。如果你回头看，部署在该个人的权限下运行。当您将脚本传递给编码代理并运行它时，它就处于“某人”的权限之下。如果您想在组织中操作它，您将需要一个系统，该系统允许您跟踪在谁的权限下部署的内容，以及可用的记录（例如审核日志）。
工作空间的处理方式尚未确定。
最初的指南说：“您只能创建和更新现有空间；还不能创建新空间。”然而，当前模板的类型定义却以相反的方式编写。该脚本必须创建一个新空间，并且不能在现有空间内运行。
并且原因也说得很清楚了。强制所有操作发生在执行用户拥有完全所有权的新空间中。。这是对权限安全的限制。
另一方面，同一存储库中的官方示例从登录的工作区启动，并执行类型定义所说的“不支持”的操作。官方文件中的解释相互矛盾。
可以准确地将其解释为规格的波动。不过，类型定义中写的原因更具启发性。 Notion 本身认识到我之前提到的“以个人权威运作”的问题。一种答案是强制清洁空间。你可以这样读。
我想确切地知道我现在处于什么位置。
名称有多种变化。官方X帐户于2026年7月24日（日本时间）宣布为“测试版”。另一方面，该指南本身将作为 alpha 版本提供，但须经批准。但是，我们建议您在新工作区而不是生产工作区中尝试它。它还指出，在正式发布之前可能会有重大变化。
7 月 24 日，Notion 还在其官方版本中发布了对 Workers 信用仪表板的支持。目前发行说明中尚未列出“概念即代码”。它的实验性定位可以从它的出版方式上体现出来。
请注意，Notion 的官方模板存储库可用于此机制。ntn notion-as-code apply向使用 CLI 命令的应用程序转变，并且还组织了对应表的交换，以便 CLI 接管。
然而，该模板的自述文件说：实验性且不普遍可用。根据环境，API 可能会拒绝请求。，和。 X官方所说的“beta可用性已开始”与官方仓库中的这个附带条件还是有距离的。
换句话说虽然设计概念已接近完成，但实际交付仍处于实验阶段。。我认为最准确的理解是将这两者分开。
对于页面和数据库，支持范围存在限制，例如脚本之外的现有记录无法指定为父记录。现在还不是让它成为内部标准的阶段,是时候感受一下验证工作区了大概。
尽管如此，为什么我认为这一步是一大步
Notion 在 3.5 中开放了其开发者基础设施，外部代理 API 在 7 月 1 日的 3.6 中宣布了 5 月份的 alpha，其中 Claude 和 Cursor 是前两个。 Custom Agents 于 2026 年 2 月 24 日发布 3.3 版本，截至 5 月初已创建超过 100 万个。概念即代码最后一块放置在延长线上看起来像
这个想法是为了解决人类无休止地点击来为特工准备工作场所的矛盾。
如果你看得更远一点，它的含义就会变得更广泛。当组织的结构变成代码时，提交历史记录回答了这个问题：“为什么这个部门有这个数据库？”组织设计成为一个可审查的主题这就是它的意思。
我们工作的地方开始被视为软件。我现在之所以想写这篇文章，是因为我能看到入口。
[相关文章]
观念3.5｜代码无需服务器运行——“开发者平台”的设计理念
本文介绍了 Notion Workers、CLI 和外部代理 API，它们是本文的前提。了解ntn命令的由来。
Notion的“发布”很危险——2022年起免认证API导致个人信息泄露的现实
一篇文章，关注有关 Notion 的 API 设计和权限的问题。这就导致了当前的权限安全问题。
杰克·多尔西 (Jack Dorsey) 宣布推出“Buzz” |人类和人工智能代理在同一团队中工作的业务聊天
本文介绍了人类和人工智能使用相同的权限管理和记录机制的基础。您可以比较设计方向。
[编者后记]
类型定义明确指出，创建空白的原因是权限安全。它被设计为仅在运行它的人拥有完全所有权的地方运行。另一方面，这也是一个决定，让他们对现有工作空间进行更改是危险的。
如果这一政策仍然存在，概念即代码将成为“分配新工作空间的工具”，而不是“管理当前使用代码的工作空间的工具”。这就是那些想要组织已经发展的公司结构的人的期望不同的地方。
正式版将以何种形式发布，我们将持续关注。
【术语解释】
概念即代码
一种在代码中编写 Notion 工作区配置并通过 API 一次性反映所有内容的机制。 Notion 端负责通过在 TypeScript 中编写“你希望它最终成为什么”来创建和更新声明的资源。截至 2026 年 7 月，它作为实验性 alpha 版本在有限的基础上提供。
陈述式和命令式
命令式是一种指示一次执行一个动作以及按什么顺序执行的方法。声明性类型仅描述“最终状态”，达到该状态的步骤由工具确定。传统的公共 API 是前者，而 Notion as Code 是后者。
IaC（基础设施即代码）
一种允许将服务器和网络配置编写为代码并进行版本控制、审查和复制的方法。 Terraform 和 Pulumi 是代表性的例子。可以说，“概念即代码”将这一思想带入了工作空间组织中。
资源ID
用户指定的名称，用于标识概念即代码脚本中的创建目标。与实际的 Notion ID 不同，它必须是唯一且稳定的。第一次部署后，会返回资源ID与实际记录的对应表。
状态文件
IaC工具记录代码中的定义与实际环境的对应关系的文件。在Terraform中，它是计算差异的标准。 Notion as Code 返回的对应表具有类似于标识资源的作用。
漂移
代码中定义的配置与实际环境的状态出现偏差的现象。直接手动更改是主要原因。这是 IaC 操作中的典型问题。
个人访问令牌
与特定个人帐户关联的身份验证信息。与机器人令牌不同，操作是在个人会员资格和页面权限范围内执行的。 2026年5月在Notion开发者平台维护。
异步API轮询
异步API是一种在发送请求时并不完成处理，仅返回接收号码的方法。用户定期轮询另一个端点并等待完成。
速率限制
一定时间内可以发送的请求数量的上限。 Notion 的公共 API 基于每个连接平均每秒 3 个请求，并具有单独的每个工作空间限制。如果超出其中任何一个，将返回 HTTP 429。另外，如果Notion暂时过载，会返回HTTP 529，两者都会根据Retry-After通过重试或者退避来处理。 “概念即代码”设置为每分钟 5 个请求（截至 2026 年 7 月）。
空间和团队空间
在 Notion 的内部术语中，空间是每个合约的工作空间，团队空间是按部门或项目组织页面和成员的部门。概念即代码提供了在代码中定义的符号。
编码剂
根据自然语言给出的指令编写和执行代码的人工智能工具的通用术语。例子包括克劳德和光标。 Notion 在 2026 年 7 月的 3.6 版本中开放了接受这些作为外部代理的能力。
打字稿
一种为 JavaScript 添加静态类型的编程语言。类型定义可以在执行前轻松检测写入错误。 Notion as Code 的配置就是用这种语言编写的。
[参考链接]
Notion（日本官网）（外部）
这是Notion Labs, Inc.的官方网站，它提供了一个集成文档、数据库和AI代理的工作区。
概念「新动态」（外部）
Notion 的官方发行说明列表。您可以按时间顺序查看每个更新的内容和发布日期，包括版本 3.3、3.5 和 3.6。
Notion「3.5：Notion开发者平台」（外部）
发布于 2026 年 5 月 13 日。 这是作为本次活动前提的开发者基础的演示，例如 Workers、CLI 和个人访问令牌。
Notion Docs「请求限制」（外部）
公共 API 中速率限制的官方参考。本文档指定了两种类型的上限：一种用于每个连接，一种用于每个工作区。
Notion Workers 文档（外部）
Workers 的官方文档，它在 Notion 的基础设施上运行自定义代码。解释了引入程序和设计策略。
makenotion/notion-as-code-template（GitHub）（外部）
概念即代码的官方模板。自述文件明确指出它是一个实验性 alpha 版本，不普遍可用。
makenotion/notion-sdk-js（GitHub）（外部）
Notion 的官方 JavaScript SDK 存储库。概念即代码是在实验分支中提供的。
Notion官方X账号公告帖（外部）
发布于 2026 年 7 月 24 日（日本时间）。这篇文章是宣布概念即代码 Beta 版开始的主要信息。
Terraform（HashiCorp 开发商）（外部）
领先 IaC 工具的官方文档。这是声明性配置、状态文件和漂移检测等概念的源材料。
普鲁米「普鲁米 vs. Terraform」（外部）
Pulumi 的对比解释，他描述了 TypeScript 等通用语言的基础设施。这将帮助您理解两者之间设计理念的差异。
[参考文章]
3.5：Notion开发者平台（Notion）（外部）
官方发行说明于 2026 年 5 月 13 日发布。这一集一次性宣布了 Workers、CLI 和外部代理 API。
请求限制（Notion Docs）（外部）
这是官方文档，明确指出平均每个连接每秒3个请求，如果超过这个，将返回HTTP 429和rate_limited。
3.3：定制代理（概念）（外部）
发布于 2026 年 2 月 24 日。他们宣布推出自定义代理，并指出初始测试人员已创建 21,000 个。
新动态（概念）（外部）
7 月 24 日的帖子是针对 Workers 的，您可以看到列表中没有包含 Notion as Code。
什么是 Terraform（HashiCorp 开发者）（外部）
它描述了一种使用状态文件跟踪实际环境的设计，并默认呈现执行计划并在应用前请求批准。
Notion推出测试版以将工作区部署为TypeScript（Digg）（外部）
一篇文章总结了消息发布后 X 上的反应。我们还注意到，由于手动编辑，git 记录与现实存在偏差。
如何与Notion API集成（Truto）（外部）
每秒 3 个请求相当于每 15 分钟 2,700 次调用，这意味着加载一个复杂页面需要 103 次调用。
观念3.5｜代码无需服务器运行——“开发者平台”的设计理念
本文介绍了 Notion Workers、CLI 和外部代理 API，它们是本文的前提。请也阅读此内容。