notis-cli

Notis CLI 技能

当用户希望通过 Notis CLI 完成工作时，使用此技能。

此技能涵盖两种主要的 CLI 工作流：

1. 在本地开发 Notis Spaces（视图、其源代码和关联的 Skills）。
2. 通过 CLI 访问 Notis、Composio 和 MCP 工具。

何时使用此技能

在以下情况下启用此技能：

• 用户希望通过 CLI 初始化、拉取、构建、验证、预览、部署或推广 Notis Space
• 当前 Agent 的直接工具列表中没有所需工具
• 用户希望通过 Notis 直接访问 MCP
• 用户希望通过 Notis 使用由集成提供的功能，而不是使用本地原生工具
• 任务直接提及 notis CLI

所有场景均使用通过注册表解析的已发布 npm 包：

• npx --package @notis_ai/cli@latest -- notis ...

始终使用此 NPX 命令形式，以确保 Agent 运行当前已发布的 CLI。唯一例外是 Notis Cloud Computer（主文件夹 /vercel/sandbox）：该环境已预装并保持 CLI 为最新版本，因此使用相同参数运行 notis ...；只有在找不到 notis 时才使用 NPX 形式。并行运行 NPX 会重新安装软件包，可能导致彼此冲突。在托管 Shell 中，CLI 通过 NOTIS_JWT 预先完成身份验证。在本地计算机上，CLI 持有自己的 OAuth 授权：运行 notis login 会在浏览器中授权；登录 Notis 桌面应用则会自动为该账户授权。无论哪种方式，授权都属于 CLI，由 CLI 在桌面应用未运行时自行刷新。

对于所有账户（包括 nightly 账户），@latest 都是正确选择。每个账户都会报告自己所属的发布渠道，notis login 会将该渠道固定到配置文件中；之后运行时若发现自身使用的构建版本不正确，会先将调用转交给正确的版本，再执行其他操作。切勿手动替换渠道：在 stable 配置文件上固定使用 @nightly，会导致计算机运行其 API 无法预期的构建版本。notis doctor 会报告当前使用的渠道；设置 NOTIS_CLI_AUTO_CHANNEL=0 可关闭本次运行的渠道切换。

CLI 内置了此 notis-cli 基础技能，并会在每次启动时，将其规范副本更新到 ~/.notis/skills/base/。它独立于账户技能同步、功能标志、目标选择和云端删除。

配置：账户和端点

一个配置由一个账户和一个 API 端点配对组成。多个配置并存；在它们之间切换不会让任何账户退出登录。

Notis Desktop 会将应用中保存的每个账户分别登录到 CLI，为每个账户创建一个配置。default 会保留原名；每个新增账户的配置都以其邮箱命名，并将 @ 替换为 -（例如 flo-mindtheflo.com），nightly 账户则会在名称后添加 -nightly。在 Desktop 中切换账户不会更改当前活动配置。只有当前活动配置的技能会链接到 Claude Code、Codex 和 Cursor；其他账户的技能会同步到各自的文件夹。从 Desktop 中退出某个账户，会让它在这台电脑上的 CLI 中也退出登录，并移除 Desktop 为它创建的配置和技能。如果该配置原本是活动配置，CLI 会切换到 Desktop 接下来打开的账户；如果没有其他已登录的 Desktop 账户，CLI 则会保持退出登录状态。通过 notis login 创建的配置绝不会被移除或自动选中。

• npx --package @notis_ai/cli@latest -- notis profile list：列出这台电脑上的所有配置及其端点、用户和登录状态。活动配置会标记出来。
• npx --package @notis_ai/cli@latest -- notis profile use <name>：更改后续命令所使用的账户，并立即将该账户的技能链接到各 Agent 文件夹。
• npx --package @notis_ai/cli@latest -- notis --profile <name> <command>：以其他账户身份运行单条命令，但不更改活动配置。
• npx --package @notis_ai/cli@latest -- notis login --profile <name>：添加账户。现有配置的凭据会保留。
• npx --package @notis_ai/cli@latest -- notis logout：仅让这台电脑退出活动配置的登录状态；该账户在其他电脑上仍保持登录。传入 --all-profiles 可清除这台电脑上的所有配置。

处理用户数据前，请先查看配置。notis whoami 会报告命令将访问的账户和端点；如果这不是用户想使用的账户，请切换配置，而不是继续操作。

使用本地 ./dev.sh 后端

./dev.sh 会将其测试账户作为由租约支持的配置（dev-<workspace>-<hash>）公开，并指向本地后端，且会在启动时打印配置名称。其凭据保存在该工作树中，并会在该工作树中自动设为默认，因此 notis ... 无需额外标志即可访问本地 API 和测试用户。它不是已存储的账户配置，无法在该工作树之外选用。

本地开发凭据限定于该本地后端，因此需遵守以下两条规则：

• dev-* 配置仅在其 ./dev.sh 租约运行期间存在。停止后，CLI 会报错 dev_runtime_unavailable，而不会将测试用户的令牌发送到线上 API。
• 如需从工作树内访问真实账户（包括本地后端卡住时），请明确指定真实配置：notis --profile <name> ...。这是受支持的退出方案。

工具缺失时的重要规则

如果当前工具界面中尚未提供所需工具，请不要停止，也不要假设任务受阻。

请将 Notis CLI 用作备用访问层。

以下情况尤其需要注意：

• 需要直接使用 MCP 工具时
• 需要使用由 Composio 提供支持的集成工具时
• 需要使用当前环境中未作为一级命令公开的 Notis 工具时
• 需要在执行前查明规范工具名称时

请像使用 Composio 风格的工具路由流程一样使用 Notis CLI：先发现可用工具，再通过 CLI 执行合适的工具。

用户和仓库策略优先

仅当不存在更严格的用户或仓库指令时，才适用以下默认交付方式。仅限预览／禁止部署的请求，以及要求必须明确取得部署许可的长期要求，均优先于默认方式。在本地和云端运行中，都要遵守这一优先级。对于仅限本地的工作，请构建并运行存根验证；不要创建远程资源或部署 Space。使用 CLI 文档中说明的构建／验证工具。发布存储库内容仍需单独授权。

工具访问工作流

1. 列出可用的工具包命名空间：
   • npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000
2. 使用自然语言搜索所需的能力：
   • npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000
   • 也可以使用 --known-fields "<key:value>" 添加已知字段提示
3. 如有需要，查看具体工具及其参数架构：
   • npx --package @notis_ai/cli@latest -- notis tools describe <tool-name> --timeout-ms 90000
   • npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema --timeout-ms 90000
4. 如果工具会修改数据，或架构并不简单，请在执行前验证参数：
   • npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'
5. 执行工具：
   • npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'
6. 如果需要执行多个彼此独立的调用，请使用：
   • npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'
7. 如果工具包尚未连接，请启动连接流程：
   • npx --package @notis_ai/cli@latest -- notis tools link <toolkit>
   • 如果基于凭证的连接已撤销或无效，请通过 stdin 使用凭证 JSON 重新连接：npx --package @notis_ai/cli@latest -- notis tools link <toolkit> --reconnect --credentials -

发现延迟与缓存

在冷启动时，发现桥接服务可能会查询多个已连接的 MCP 服务，因此耗时可能超过 CLI 通常的 30 秒超时。对于 tools toolkits、tools search、tools describe 和仅查询架构的发现调用，请始终使用 --timeout-ms 90000。如果发现调用返回 network_timeout，请使用 --timeout-ms 90000 重试同一条命令一次；不要发起新查询、臆造工具名称，也不要反复执行默认 30 秒超时的命令。CLI 自身会在同一预算内，对连接中断和网关错误进行重试，因此请勿自行编写循环来重试 CLI 调用（详情）。

发现操作是幂等的，但应有所限制：每项任务只运行一次工具包列表；每种不同的能力只进行一次自然语言搜索；并在当前轮次的剩余时间内缓存返回的规范工具名称和架构。搜索／架构响应成功后，直接调用返回的规范工具（修改数据前先执行 dry-run），不要在每次调用已连接服务前重复相同的发现请求。

工具访问规则

• 切勿猜测工具名称。请先使用 npx --package @notis_ai/cli@latest -- notis tools search 查找。
• 如果有专用命令，优先使用一等 CLI 命令；但如果该功能不在专用命令的覆盖范围内，请使用 npx --package @notis_ai/cli@latest -- notis tools ...。
• 如果知道工具名称，但不清楚参数格式，请在执行前使用 npx --package @notis_ai/cli@latest -- notis tools describe 或 --get-schema。
• 对于会产生变更的调用，如果需要在不执行的情况下验证架构，请先使用 --dry-run。
• 如果缺少某个工具包，请使用 npx --package @notis_ai/cli@latest -- notis tools link <toolkit> 启动连接流程。
• 使用 --reconnect 替换现有连接。如果存在多个账户，请使用 --connection-id <id> 选择一个。
• 对于 API 密钥、基本身份验证或其他凭据 JSON，优先使用 --credentials - 并通过管道或重定向传入标准输入。避免在命令中直接写入密钥，以免它们进入 shell 历史记录和进程列表。

任务指南

只阅读完成此任务所需的指南。相对链接以技能包为基准解析。 对于托管 MCP，请使用 resources/read 或可用的 Notis 资源获取工具，获取对应的 notis://docs/notis-cli/references/<file>.md URI；根资源也会将这些链接 重写为已发布的 URI。

• 空间交付
• 工具包心智模型
• 原生数据库访问
• 辅助命令

技能与委派工作的智能能力

技能请求 low、medium 或 high，而不是指定固定模型名称。请先查找只读的 LOCAL_NOTIS_GET_INTELLIGENCE_POLICY 工具，获取共享的 contract 以及 notis、codex 或 claude_code 对应所请求 level 的当前映射。每项任务开始时， 都要一并确定模型和推理力度；并由执行环境验证所选选项。显式调用的覆盖设置优先。 固定模型的执行环境可能会沿用固定模型，并说明未应用所请求的级别；如果自动化启动器 需要精确选择，但无法获取策略，则必须在产生副作用前停止。 代码库和已安装的技能使用同一响应；二者都不需要基于代码检出路径的文档。记录实际执行回执， 而不是级别名称，作为模型来源信息。媒体引擎仍是由其工具选择的独立能力。有关跨环境 的详细信息，请参阅智能能力契约。