connect

宿主命令： 在 Cursor 桌面端和 Cursor 终端中，调用与 /begin、/connect、/status 和 /next-lesson 相同的共享技能（当名称冲突时，在技能选择器中选择 Altitude）。将本文件中出现的 /altitude:<skill> 示例在 Cursor 中转换为 /<skill>；Claude Code 保留 /altitude:<skill>，Codex 保留 $<skill>。

Copilot 宿主命令： 在 GitHub Copilot CLI 和 VS Code Copilot 聊天中，使用相同的共享 Altitude 技能。在宿主技能选择器中按名称选择 Altitude 技能（connect、begin、next-lesson 或 status）；使用该宿主显示的调用写法。不要将这些文件复制到第二个仅用于 Copilot 的技能库中。完整的 Altitude 插件提供课程钩子；仅复制技能只能提供独立的免费方法。

将当前的编码 Agent 安装连接到 Altitude：

Cursor 准备工作，包括已完成配对的安装： 在插件设置或配对之前，让学习者在自己的终端中运行 altitude update 并等待其完成。如果缺少 altitude，请改用 npm install -g @learnaltitude/cli。然后从将要运行配对的同一环境中读取 altitude --version。较旧的 CLI 无法识别 --agent cursor；仅更新插件无法添加该身份。如果更新后已安装的 CLI 仍然拒绝 Cursor，请保留现有的配对/绑定/进度，并报告该 CLI 尚不支持 Cursor；切勿在没有 --agent 的情况下或使用其他 Agent 的身份重新运行配对。更新成功并不能证明课程已通过验收。

1. 确定你正在哪个 Agent 中运行，然后获取其版本：

   • Claude Code： 运行 claude --version，取开头的语义化版本号。
   • Codex： 运行 codex --version，从其 codex-cli x.y.z 输出中获取版本。 如果低于 0.131.0，请警告用户 Altitude 的会话 hooks 需要 Codex CLI >= 0.131.0，并建议先更新——最终由服务在配对期间作出判断。
   • GitHub Copilot CLI： 运行 copilot --version，使用观察到的 CLI 版本。
   • VS Code Copilot chat： 从 VS Code Extensions 中读取已安装的 GitHub Copilot Chat 扩展版本。将 code --version 中的编辑器版本单独保留；不要用它替代 Copilot 版本。
   • Cursor desktop： 从 cursor --version（第一行）或 Cursor About 中读取桌面版本。不要用终端 Agent 版本替代。
   • Cursor terminal： 运行 cursor-agent --version（如果其安装的命令是 agent --version，则运行后者）。保留其完整的日期和构建版本字符串；不要杜撰语义化版本。
   • Cursor 兼容性设置： 使用本次调用附带的源路径或你实际读取的文件，相对于此已安装的 skills/connect/SKILL.md 解析 ../../bin/altitude-cursor-setup.mjs。不要假设你的 shell 中存在插件 hook 环境变量。如果源路径不可用，请从 Cursor 的插件管理器中恢复当前活动的安装位置；绝不要选择最新的缓存目录或另一个检出。然后运行 node '<that actual absolute file path>' install（按当前 shell 的规则加引号）。这还会将这个确切的已安装插件根目录作为 JSON 数据记录到 ~/.cursor/altitude/plugin.json 中；原生 hooks 会读取该注册信息，因为 Cursor 可能提供另一个插件的根目录环境。每次插件更新后都要重新运行 /connect，以从新激活的技能源刷新注册信息。缺失或过期的注册会以 fail open 方式失败，并给出 /connect 诊断信息。该设置会以幂等方式添加三个归属自身的、惰性的用户 hook 条目，使终端 Agent 能够分发原生插件的回合 hooks；现有 hooks 会被保留。请运行随附的脚本，绝不要手动重建其配置。如果设置失败，请转述其简短错误，并保持配置不变。没有该脚本的复制技能并非完整插件：请使用 Cursor 的插件管理器安装完整插件。更改设置后，请启动新的 Cursor 会话，然后再开始课程。移除时使用同一已安装脚本并传入 uninstall；它只移除 Altitude 的兼容性条目及其匹配的注册信息；较旧的插件无法抹除较新的注册信息。 Cursor 配对决策： 完成兼容性设置后，在开始新的设备流程之前运行 altitude status。此命令仅在本地运行且只使用缓存：connected 报告是否存在可读取且格式正确的已保存 token。它不会识别账户，也不会验证服务是否接受该 token；绝不要将其视为预期账户或在线身份验证健康的证明。
   • 对于常规的初次设置或在 connected: true 情况下的插件更新维护，保留现有配对并跳过步骤 2–4。说明已保留现有的本地配对，且插件注册已就绪；继续执行下方的状态摘要和安装检查。设置发生变化时，仍需要新的 Cursor 会话才能运行 /begin 或 /next-lesson。
   • 如果学习者明确要求重新连接或更改账户，即使本地已存在令牌，也继续执行配对。如果新的命令行请求已返回 unauthorized，说明服务拒绝了保存的凭据，并继续通过配对来修复。不要暴露凭据，也不要删除绑定、计划或排队中的进度。
   • 当 connected: false 时，保存的令牌缺失或格式错误；继续执行配对。离线或网络受阻的读取、缺少缓存的旅程数据，以及空闲的刷新器，都不意味着令牌无效，也绝不触发自动重新配对。
   • 如果状态命令失败或其输出无法读取，转达简短的诊断信息，并在此停止配对决策；不要仅仅因为状态失败就推断为断开连接或开始配对。保留现有的本地状态以及刚刚刷新的注册。

2. 在后台为你的 Agent 启动配对命令：

   • Claude Code： altitude connect --agent claude-code --agent-version <version> --next-hint "Open your coding agent in your project folder and run /altitude:begin to start your journey."
   • Codex： altitude connect --agent codex --agent-version <version> --next-hint "Open your coding agent in your project folder and run $begin to start your journey."
   • GitHub Copilot CLI 或 VS Code Copilot chat： altitude connect --agent copilot --agent-version <observed Copilot version> --next-hint "Open your project in Copilot and choose Altitude begin to start your journey."
   • Cursor 桌面端或终端： altitude connect --agent cursor --agent-version <observed version> --next-hint "Open your coding agent in your project folder and run /begin to start your journey."

   Codex 附注 — 沙箱： 在 Codex 的默认模式下，shell 没有互联网访问权限，因此直接在后台运行 altitude connect 会在打印代码之前就失败。请为该条命令请求提升权限，并附上一行理由（"Altitude 需要网络访问权限才能将这台计算机与你的账户配对"）。如果该请求被拒绝，或者宿主没有此类机制，不要盲目重试，也不要认为安装已损坏：将上方确切的 altitude connect 命令行交给学习者，让他们在自己的终端中运行，请他们粘贴回其打印的 URL 和代码，然后据此从步骤 3 继续。

3. 立即将其输出中的验证 URL 和一次性代码转达给用户。

4. 等待用户在浏览器中确认，然后报告命令是否成功完成。如果学习者是在自己的终端中运行该命令，请他们在命令报告成功时告知你。

5. 运行 altitude status，并总结连接、绑定和旅程状态。

6. Codex 附注 — 一次性信任提示： 在安装了 Altitude 的情况下首次启动时，Codex 会询问"Hooks need review"，在插件更新更改了某个 hook 后也会再次询问。告诉学习者每当它出现时选择 Trust all and continue；如果他们之前忽略了它，请他们现在打开 /hooks 并信任 Altitude 的 hooks。这些 hooks 在沙箱之外运行，并保持旅程的本地副本为最新，这正是 $begin 和 $next-lesson 能够从沙箱内部读取它的原因；如果不信任，每节课开始时都会要求他们在自己的终端中运行一条命令。

7. Cursor 安装检查： 必须加载完整的原生 Altitude 插件，包括 hooks；仅复制 skills/ 文件夹只能用于独立的免费方法。使用 Cursor Customize 及其 Hooks 输出确认已加载，然后开始新对话。保留现有的用户和项目 hooks。此集成尚待完整的桌面/终端课程验收；不要声称成功配对就证明课程可用，也不要绕过服务兼容性暂停。

Copilot 安装检查： 安装完整的原生 Altitude 插件，信任此项目以启用 hooks，然后在目标项目文件夹中重新打开 Copilot 对话。该插件必须同时暴露共享技能及其生命周期 hooks。在 VS Code 中使用 Local agent 进行已测试的集成；其他编辑器 agent 宿主需要单独验证。配对前运行 altitude --version，并查看 Copilot 支持 中的 CLI/服务要求。如果 --agent copilot 被拒绝，保留现有配对和进度，并报告缺少 CLI 支持。切勿省略 --agent 或作为另一个 agent 配对来绕过兼容性。全新安装不需要无条件更新；请使用文档中与发布版本兼容的版本。

不要更改设备流程，也不要将凭据发送到除 altitude CLI 之外的任何地方。