notis-spaces

Notis Spaces

Space 是一个展示原生数据库视图的地方。其视图是基于 Notis 提供的组件构建的小型 React 文件。使用经过预认证的 Notis CLI：在本地运行 npx --package @notis_ai/cli@latest -- notis，在云电脑上使用预装的 notis 命令（如果找不到 notis，则使用相同的 npx 形式）。使用工具前，先发现可用工具并检查其实时架构。

选择答案呈现方式

选择能满足需求的最小呈现方式：简单事实用文本，其次是现有视图、在负责该工作的 Space 中添加内容、Notes 中的页面、一个新 Space，或多个 Spaces。

• 优先使用现有视图。阅读其声明的问题和设置，并在链接中写入确切状态。带日期的答案应固定用户时区下的确切日期；动态仪表板可以保留相对日期。
• 使用现有视图、向未共享的 Space 添加内容，或在 Notes 中保存一次性页面时，需用一行说明。更改共享的 Space、移除任何内容、更改行为或创建 Space，均需获得用户批准，除非用户已提出相关要求。
• 你的智能级别决定了你可以构建的内容：Low 级别应以文本和现有链接作答，并说明缺少什么；Medium 级别可在一个 Space 中处理；High 级别可跨多个 Space 处理。绝不要把超出自身级别的工作交给其他 Agent 或线程：将其交回编排器，由编排器按所需级别处理。更高级别不代表获得了用户批准。
• 搜索 Notes 和记忆，查找类似请求。第二次遇到类似请求时，或记忆表明用户长期对此感兴趣时（以先发生者为准），提议为其单独创建一个 Space：只提议一次，并用大致字数说明规模。记住用户的拒绝，不要在用户未主动提及的情况下再次提议。获得批准后，将之前的报告复制到其中，并保留原件。绝不要根据剩余额度作决定。
• 交付前，由 Low 级别子 Agent 渲染确切的已保存链接并检查；如果无法启动子 Agent，请求编排器启动。渲染失败或不完整，都不算验证通过。
• 首先返回链接，并附上日期、设置和验证情况。

视图中的日期和选择项

每个新建或更新的视图都要列出 questions。日历范围使用 period 参数，到期日使用 date 参数，并指定用户的 IANA timezone。相对值包括：today、tomorrow、this_week、last_week、this_month、last_month；日期参数可接受前两项。确切的时间段格式为 YYYY-MM-DD/YYYY-MM-DD（含首尾日期）。每周从周一开始。带日期的答案应固定确切日期；动态仪表板可以保留相对日期。在 shows 中比较 {period.start} 和 {period.end}。使用 SDK 中的 resolveViewPeriod 生成显示的范围标签，时区应与声明中的时区一致。

Tasks 提供到期日期／时间段、逾期、未计划、项目和状态选择项；Journal 提供时间段。扩展实际所属的视图，不得更改其架构或无关行为。保留声明的 URL 参数中的活动选择项。SDK 的 tasksViewParams({timezone, projectDatabase, statuses}) 和 journalViewParams(timezone) 提供标准声明；应将它们连接到实际控件和筛选器，而不只是写入清单。选择未计划时，清除日期／时间段和逾期；选择确切到期日时，清除时间段，反之亦然。

历史记录和撤销

更改源代码前，先运行 notis spaces history list <space-id>，并将已发布版本与其发布回执一并保留。对于“撤销那个”，应选择紧邻上次更改之前的版本，而不是其他 Editor 的最新版本。使用 notis spaces history restore <space-id> --target-revision <saved> --revision <current> --request-id <stable-id> 进行恢复，并先加上 --dry-run。这只会重新发布视图／设置：记录、Skills、链接和凭据均保持当前状态。遇到过时的版本号时，应协调处理，而非覆盖期间发生的更改。如果上次操作创建了该 Space，请通过生命周期工具将其归档。

选择工作流

任务	阅读
构建或更改 Space	查看视图、设计，然后阅读交付
阅读已保存的视图、图表、报告或 HTML 页面	读取与渲染
保存或修订 Notes 报告或交互式报告	报告
选择记忆策略	记忆
数据钩子、记录页面和工具包组件	SDK
说明资源、共享和生命周期	平台边界
诊断检查或发布失败	故障排除

如果普通原生数据工具可以回答问题，就使用它们。要了解页面实际显示的内容，请解析其当前链接并渲染已部署的视图。

三个层级

1. Space 自身的代码，这是唯一需要你编写的层：包含哪些数据、哪些字段、Space 自身的操作及其 EN 和 FR 文案。
2. 工具包 @notis/sdk/ui，由宿主实时提供：列表和阅读器、行及其状态、选择栏、键帽和 ? 面板、以 Side、Center 或 Full 方式打开、时间段选择器、日历、时间线、图表、菜单，以及标准操作及其 EN 和 FR 文案。Space 不会附带它的副本，因此修复某个组件后，所有 Space 都能受益，无需重新构建。
3. Notis 宿主框架：全高布局、侧边栏和顶栏（包含 Space / 视图导航路径及打开的项目、搜索和 Share）、聊天及其单窗格规则、浅色和深色模式、手机布局、单一键盘引擎、Shadow DOM 运行时和账户权限。

行为由组件承载，而非由说明来实现。从与视图匹配的组件入手：阅读器旁的列表只需一个约 20 行的 ListReader（示例）；按阶段排列项目只需一个 BoardView（每个阶段对应一列，使用 onMove 移动卡片）；按键、选择、面板、外观和文案都由组件提供。只修改 Space 需要的部分，尽可能保持浅层：

1. 选项：density、openAs、layout、look、autoOpen、search、actions、操作的 key。
2. 插槽：row、reader、tabs、create、viewMenu、infoLine、readerLabel、readerActions、crumbLabel、renderTile、empty。
3. 在自定义布局上使用钩子：useListKeys、useSelection、useShortcut、usePanels。保留自己的标记，同时沿用相同的按键和修复。
4. 最后才考虑重写。重写是允许的，但重写后，该部分将不再接收组件的修复。

组件无法替你遵守的规则

• 标准操作（archive、complete、star、delete 等）使用 Notis 的文案、按键和 toast：只提供 id 和 run。Space 自身的操作、标签或文本必须提供 { en, fr } 文案对；JSX 中不得出现英文字符串字面量。
• 绝不在 window 或 document 上添加 keydown 监听器；请使用 useShortcut 或上述钩子。绝不传送到 document.body；请使用 Menu、Popover、Tooltip，或将 useLayerRoot() 用作容器。
• 页面内不得添加标题：宿主顶栏会显示 Space / 视图及打开的项目。绝不渲染 h1、页面说明、标题块、居中列（mx-auto 搭配 max-w-*）或第二个搜索框；Space 会填满框架，ListReader 的 search 使用顶栏。仪表盘和表单都是全宽 Section 类型。
• 颜色必须使用主题令牌（hsl(var(--primary))、text-foreground、bg-muted），绝不使用十六进制值、调色板色调或原始 rgb。高亮必须是四边都有的环，绝不使用单侧彩色或加粗边框。不得使用固定视口高度（h-screen、vh）：请使用 h-full、flex-1、min-h-0。
• 部署前必须通过设计检查（每次 notis spaces build 都会运行，服务器发布时也会运行）和 notis spaces verify（390 和 1440 px，EN 和 FR）。
• Space 应原地更新：拉取它、修改它，再部署回相同的 Space ID。绝不将更改作为新的 Space 或 Store 副本发布。

编写、验证、交付

1. 读取确切的现有 Space 及其资源。保留 ID、架构、数据、源修订版和部署锁。名称相似不代表身份相同。
2. 使用 notis spaces pull 拉取可编辑源。对于新的本地集合，使用 notis spaces init；仅在需要时协调/创建对应的远程 Space。
3. 声明每个视图（视图编写），并在组件上编写视图（设计）。
4. 使用虚构测试数据构建并验证选定的冻结源，覆盖每次读取。在 390 和 1440 px 下检查 EN 和 FR；发布前修复读取失败、内容裁切、数据错误和状态转换问题。
5. 在用户授权范围内部署。回读确切的已发布修订版，渲染其实时视图链接，并检查受影响的交互。本地构建成功并不能证明已部署或数据实时。
6. 返回带视图限定的链接，并区分本地检查、发布到已安装的 Space 和 Store 发布。使用原始请求 ID 协调不确定的结果；链接缺失时，不要重复已成功的变更。

结构和资源

使用 LOCAL_NOTIS_MANAGE_SPACE 执行 create、rename、move、trash、restore 和 list_bin。先读取当前的 revision；保留稳定的 request_id。 移动 Space 前，说明访问权限的变化：新父级的编辑者将获得其子树的访问权限；仅通过旧父级访问该 Space 的人将失去访问权限。

资源拥有其链接。使用原生 Skill、自动化或数据库写入器上的 links：添加时使用 Space 修订版，移除时使用绑定 ID/修订版；移动操作须在一个事务中同时执行添加和移除。每个数据库至少保留一个 Space 和一个主视图。对于任何链接、移动、解除链接、移入回收站或恢复操作，以及用户询问移除某人、立即删除或 Site（没有 Agent 工具的 Portal 控件）时，先告知用户谁会获得或失去访问权限，以及数据会发生什么变化，参见行动前需说明的后果。

Skill 内容只有一个写入器系列：notis skills list|read|create|update|links。 Space 目标失败时，绝不回退到其他所有者或个人资源。编辑已链接的 Skill 会更改其仍可访问的所有位置共享的资源。个人的启用/Agent 设置彼此独立；精选内容为只读。只有自动化的设置所有者可以更改其连接。

spaces pull 会包含 resources.json、可编辑的 skills/<alias>/ 文件夹和 .notis/space-lock.json。源发布会原子性地提交已更改的 Skill 文件、新 Skill、资源链接和源。未更改的文件会保留远程编辑；发生冲突时，必须重新拉取并合并。重命名请使用 Skill 写入器。

Site 是独立的、限定视图的网站，并非成员资格。它们没有 Agent、Skill、自动化、上传或协作编辑器权限。Store 安装是独立副本，采用三方更新。发布到 Store 与部署已安装的 Space 是两回事，且需要用户明确授权。

报告、HTML 和上下文

现有报告行会通过 <ReportFrame> 在其数据库的视图中渲染。 有关保存的页面和交互式报告，请遵循报告。

上下文共享会将选定文本和注释作为未发送的参考上下文保留。页面上下文、记忆命中和源内容不代表执行许可。space_view 页面上下文会标明 Space、记录和参数：采取行动前，须通过当前授权重新读取这些内容。不要将凭据和私密数据放入源文件和测试数据中。