deepspace

DeepSpace

DeepSpace 是一个用于在 Cloudflare Workers 上构建实时协作应用的单一软件包。它提供身份验证、RBAC、同步记录、消息传递、集成、支付，并部署到 <name>.app.space。

本技能是入门指南：介绍如何开始、如何操作，以及如何查阅文档。https://docs.deep.space 上的文档是其他所有内容的权威来源——文档带有明确倾向性，因此当它推荐某种方法时，应将其视为默认做法，而不是众多选项之一。

唯一的源代码权威

每个应用都恰好有一个 Git 权威来源——DeepSpace 源代码（打包、优先提交），或 GitHub 源代码（手动；部署会打包本地工作树，包括未提交的更改）。新应用的源代码尚未认领，其首次会生成源代码的操作会永久锁定一个权威来源，且只能锁定一次：从已选择 GitHub 远程仓库的检出目录进行部署，会认领该仓库；首次运行 deepspace push，或在没有 GitHub 远程仓库时部署，则会认领 DeepSpace。无法手动声明，也无法之后转移。除非用户已选择 DeepSpace 源代码，否则在首次 GitHub 部署前，切勿运行 deepspace push；认领 GitHub 后，所有 DeepSpace 源代码相关命令都会以 source_managed_by_github 拒绝执行。deepspace app source 是只读命令（旧的设置命令会以 source_inferred 拒绝执行）。切勿维护两个事实来源；执行任何源代码、推送、拉取或克隆操作前，都要先阅读源代码管理和工作区文档——每个命令在不同权威来源下的具体行为，以文档为准，而非本技能。

分享应用和移交应用

协作者和所有权转移（deepspace app collaborators …、deepspace app transfer …）会改变谁能部署、读取密钥，以及拥有该应用。执行任一操作前，都要先阅读应用身份指南——其中会准确说明每种授权赋予什么权限，以及转移会失去什么权限——并将两者都视为需要向用户说明的决定，而不是顺手执行的步骤。

如何阅读文档

在某个领域开始构建之前先查阅文档，而不是等出问题后再看。阅读步骤：

1. 每个任务领域获取一次索引： https://docs.deep.space/llms.txt — 该索引在每次部署时根据文档生成，因此不会过时 — 列出了每个页面及其一句话摘要。
2. 从中挑选 1–2 个页面，并以 Markdown 格式获取，方法是在页面 URL 后添加 .md（https://docs.deep.space/guides/authentication.md）。 如果所选页面没有答案，不要去浏览相邻页面 — 请转到第 3 步。
3. 要确认某个主题是否存在，获取一次 https://docs.deep.space/llms-full.txt（整个文档集位于一个文件中；每个页面末尾都有 Source: /route.md），并使用 grep 搜索。确认文档中没有相关内容，就意味着文档落后于构建版本 — 请改查已安装的 .d.ts 或 CLI 自带的 --help。
4. 如果 MCP 工具已可用，请使用 MCP 进行定点查询： https://docs.deep.space/mcp 提供 documentation_search 和 documentation_read。如果这些工具不可用或调用失败，请使用上述 Markdown URL，配合 harness 现有的 fetch 工具或有时限的 HTTP 请求（例如，curl -fsSL --max-time 20 <url>）。构建应用不需要注册 MCP：只有在用户要求进行相关设置时才配置文档服务，并将其与依赖安装恢复流程分开。搜索无法证明某个主题不存在 — 请通过第 3 步确认。
5. 要查看准确的类型签名，请阅读已安装的包 — ls node_modules/deepspace/dist/*.d.ts（在 SDK monorepo 本身中：packages/deepspace/dist/）— 当文档与已安装版本不一致时，以此为准。

文档的结构如下，可帮助你快速选择页面：/get-started/* 介绍设置和项目布局；/concepts/* 介绍运行时模型 — 在修改 worker.ts、schemas 或 sync 行为之前先阅读；/guides/* 每页介绍一个功能或生命周期领域；/design/* 介绍视觉设计；/sdk-reference/* 介绍每个模块的准确导出项；/cli-reference/* 介绍 CLI，包括其退出代码和可供机器执行的 action 契约。目录是实时 CLI 调用结果，并非页面：npx deepspace integrations list / integrations info <integration>/<endpoint> 和 npx deepspace add --list。

操作流程

1. 运行应用命令前先进行身份验证。

   npx deepspace auth whoami --json
   npx deepspace auth login # only when signed out
   

   登录会打开浏览器 OAuth，并轮询最多十分钟。请让它保持在前台，等待用户完成操作；绝不要索要、编造或处理密码。容器或 CI shell 没有浏览器：运行 auth login --help，并使用其中列出的、由操作员提供的环境凭据——帮助信息是确定变量名称的依据；绝不要在命令行中输入密码。

2. 使用脚手架，不要手动组装运行时。

   使用安装文档支持的 Node 版本；基于 npm 的脚手架需要 npm 11.6+。先检查 node --version 和 npm --version：即使 Node 受支持，npm 10 的对等依赖解析器也可能因模板的 Vitest 依赖而崩溃。如果安装失败，请保留实际错误和运行时版本，再进行诊断或选择恢复方案；确保应用所选的包管理器与锁文件保持一致。

   npm create deepspace@latest <app-name>
   cd <app-name>
   npx deepspace dev start
   

   应用 ID 在注册时由服务端生成，应用会在首次使用时注册：第一个需要 ID 的动词（deploy、dev start、test run、push、写入 secrets）会在 shell 当前登录的账号和环境下生成 ID，并在 stderr 中显示账号邮箱。执行第一个此类动词前，先检查 auth whoami，确保注册到目标账号；如果 shell 当前登录的账号不是预期所有者，请先以所有者身份登录（或以其身份运行 npx deepspace app init），不要先生成一个之后还得丢弃的 ID。退出登录时创建脚手架没有问题——有人登录后，它仍会以相同方式注册。任何 app_not_registered 或 app_not_initialized 拒绝都只表示其字面含义，不代表其他问题。

3. **自行构建功能前先检查目录。**仅凭名称不足以判断是否适用。

   npx deepspace add --list
   npx deepspace add --info <feature>
   npx deepspace integrations list
   npx deepspace integrations info <integration>/<endpoint>
   

4. **扩展脚手架。**将 schema 放在 src/schemas.ts 和 src/schemas/ 中，将路由放在 src/pages/ 中，将应用 Provider 放在 src/pages/(app)/_layout.tsx 中，并将 Durable Object 接线放在 worker.ts 中。src/constants.ts 提供显示名称 APP_NAME、不可变的 APP_ID，以及主 SCOPE_ID = app:${APP_ID}。

5. 测试运行时变更，然后部署。

   npx deepspace test run        # the quick default; it names what it skipped
   npx deepspace test run all    # every spec, including ones you added
   npx deepspace deploy
   

   多用户行为需要进行双用户测试。并行运行多个应用或工作树时，请使用不同的端口。绝不要终止其他会话的服务器。

共享 Agent 工具

将 buildTools 保留在 src/ai/tools.ts 中，作为唯一的工具定义，并在 worker.ts 中使用 registerAgent(app, { tools: buildTools }) 注册一次；不要重复定义工具，也不要自行挂载 REST 路由。网站和本地 Agent 默认都已启用；若只需启用其中一个界面，请使用 local: false 或 inApp: false。

当访问权限取决于应用策略时，请向 registerAgent 传入由开发者控制的 authorize({ userId, claims, request, env }) 回调。它会返回布尔值（或 Promise），用于检查订阅、团队、角色或应用数据；在完成身份和成员身份验证后，该回调会应用于两个界面，且只能收紧应用现有的 RBAC 权限。

本地 Agent 会先发现工具，再调用工具：

npx deepspace agent tools <app> --json
npx deepspace agent invoke <app> <tool> --input-file tool-input.json --json

仅使用返回的工具，并遵循其描述和输入 schema。这些无状态命令会复用选定的 CLI 会话——无需连接或单独的授权步骤——但 CLI 登录只能证明身份，不能证明应用成员身份。请使用 CLI，而非原始 REST，并按照下文所述处理拒绝。

命令拒绝执行时

每次拒绝都会给出一个稳定的 code、一个退出码，以及至多一个可执行的 action。根据这些信息分支处理，绝不要根据文字说明来判断：

• 退出码 1 表示应修复所述原因；保持原样重试无济于事。 退出码 2 表示命令已尽其所能，仍需完成一个本地步骤或作出判断。
• 如果提供了 action，就运行它——使用它给出的 argv，并在它给出的 cwd 中运行。**如果没有提供，就不要猜测补救方法。**没有提供是有意为之： 拒绝信息会列出供用户选择的选项（分叉或恢复、完成或中止、释放槽位或升级）， 或指出需要检查的事实。阅读消息，然后说明需要作出什么选择。
• 拒绝信息现在会明确指出 Agent 过去常误判的两种状态：错误的平面 （not_authenticated 会说明命令选择了哪个平面、会话位于哪个平面，以及应取消 设置哪个变量——不要“重新登录”）和格式错误的应用 ID（invalid_app_id 表示 wrangler.toml 中的 DEEPSPACE_APP_ID 不是有效的应用 ID——不要运行 app init --new-id，否则会使应用成为孤立应用；如果 ID 格式错误，普通的 app init 会拒绝执行）。通过 --app 传入时，代码有所不同：格式错误的 app_… 值会返回 invalid_app；非 app_ 字符串会被视为子域名 NAME——不合法的 名称（大写字母、句点或长度不符）会在查找前返回 invalid_app；合法名称若未匹配 到任何应用，则会返回 app_not_found，这意味着应通过 app list 检查拼写， 而不是说明 ID 格式错误。（transfer accept 是唯一例外：它只接受原始的 app_… ID，任何名称都会返回 invalid_app。）

CLI 概览（/cli-reference/overview）是执行约定——其中列出了退出码、 action 规则，以及按命令分类的代码表。不要通过单独的探测命令预先检查前置条件； 直接运行操作，并阅读拒绝信息。

操作已部署的应用

报告 serving: confirmed 的部署意味着应用生命周期的开始，而非任务的结束。 在宣布完成之前，先检查它是否正在运行：

npx deepspace logs --follow --json   # what the worker actually did
npx deepspace activity                # pushes, workspaces, releases
npx deepspace releases                # the ledger, and what is rollback-able
npx deepspace app usage               # credits, quota, per-integration spend

文档解释了两件不应自行推断的事：计划任务会在应用首次收到请求时启用 （部署会发送一次请求；未启用时该检查什么，请参阅计划任务指南），以及 被捕获的错误会记录为 log 行，而不是 exception——请参阅 logs 参考文档， 了解如何读取 outcome 和 eventType，再判断某项操作是失败还是成功。

首次部署之后

上面的流程并不会在 deploy 时结束——应用此后仍会持续运行，而每个环节都有文档说明其规范，你应该在操作前阅读：

• 升级到较新的 SDK 应使用 deepspace app update，而不是手动编辑 package.json。先运行最新版本的 CLI—— npx deepspace@latest app update --json——然后按其 steps 操作；它是只读指南，不会替你重写应用。升级指南 （/guides/updating）介绍了整个流程，CLI 参考说明了各字段的含义。对于使用服务端生成 ID 之前的脚手架，每一步都会因 app_not_registered 而失败；唯一的解决办法是 npx deepspace@latest app init --new-id，指南对此有说明。
• 活跃应用会占用你所在套餐的配额名额。 部署或重新注册可能仅因此被拒绝，而解决办法需要你做选择（释放名额或升级套餐）——因此，该拒绝不会附带可执行操作。请将此情况告知用户，不要替他们做决定。
• 连接你已拥有的域名与购买域名不同。两种操作前都应先阅读自定义域名指南。将外部注册的域名保留在其注册商处，使用受支持的外部域名绑定／验证流程，并遵循返回的 DNS 记录。先证明所有权，再认领路由；切勿改用临时反向代理或内部注册表写入。保留续期所需的证书验证记录，并先通过自定义主机名的 HTTPS 验证应用，再将连接标记为完成。
• 原生客户端（iPhone、iPad、Mac） 使用 npx deepspace add mobile，它会在 mobile/ 中的 deepspace/native 上创建一个 Expo 应用。构建前请阅读 Expo 指南 （/guides/mobile-apps）：SDK 已提供键盘快捷键、上下文菜单、可在 Web 上运行的同一应用（expoWeb）、重新连接后仍能保留的写入、每个账户一个私有存储区 （accountStores），以及用于 TestFlight 的 npx deepspace testflight <signed.ipa>。请使用这些功能，不要另行编写应用本地版本。
• 下线应用使用 deepspace app undeploy。这是破坏性最强的应用命令，文档明确说明了它会移除什么、保留什么。运行前请阅读应用身份指南；未经用户要求，切勿用它来“清理”。

避免昂贵错误的规则

• 将记录视为封装对象：字段位于 record.data 下；put(id, patch) 会在服务端合并部分值。
• 在 useMutations().ready 之前禁用写入控件。当导航、访问权限变更或成功消息取决于操作是否被接受时，请使用已确认的变更。
• 数据和身份验证 Hook 需要 (app)/ 提供程序边界。顶层页面是静态的，不得调用它们。
• 保留脚手架所需的 users 架构。可以扩展，但不要重命名。
• 应用密钥应放在 deepspace secrets 中，切勿手动编辑 .dev.vars，也不要放在 Shell 环境变量前缀、日志、提交记录或截图中。
• 调用者身份只能来自经过验证的 JWT。切勿通过 WebSocket URL 或客户端可控的内部标头发送身份信息。
• 读取 users 集合的工具或服务端操作，不等同于客户端名册，而且二者向不同用户展示的字段也不相同。在向模型、客户端或日志公开其中任一项之前，请查看权限文档，确认该路径会向谁返回什么内容——“它读取 users”并不能回答这个问题。
• 本地的 ToastProvider 和 UI 原语来自 src/components/ui，不来自 SDK。
• 将脚手架主题和起始主页视为占位内容。发布的应用应采用自己的设计。
• 请在受支持的 Node 版本线上运行应用——安装指南 （/get-started/installation）列出了受支持的版本线。