跳到主要内容

CLI 常见问题与中断恢复

先运行 nameslink --version，确认实际调用的版本；需要登录或连接诊断时再运行一次 nameslink doctor。不要并行重复启动多个登录或诊断进程。

关闭并重新打开终端，确认 node --version 至少为 20，并重新执行公开版安装命令。如果装过旧内部包，检查是否仍调用了旧入口：macOS / Linux 用 command -v nameslink，PowerShell 用 Get-Command nameslink。

公开安装不需要配置内部 npm 源，也不需要公司 npm 账号。不要为了安装而全局替换其他软件包使用的 registry。

浏览器登录了，CLI 仍提示未登录​

浏览器登录与 CLI 凭证是独立状态。运行 nameslink login，在浏览器完成授权后回到原来的终端进程，再运行 nameslink whoami。

检查所选 API 地址。凭证与登录时的 API 地址绑定；更换地址后要针对新地址重新登录，不能直接沿用另一环境的凭证。公开默认地址是 https://www.nameslink.com/api。

远程终端可用 nameslink login --no-browser 显示手动授权入口，但仍需要能完成 CLI 的本机回调；它不提供跨设备免回调登录。不要分享该授权链接。

macOS 弹出钥匙串密码框​

保留当前等待中的 CLI 进程，核对系统弹窗，再在系统弹窗中完成钥匙串授权。密码不应输入到 AI 聊天或终端命令中。若原命令已超时，先关闭旧弹窗，再重试一次；连续启动多个进程会产生重复提示。

Windows 或 Linux 报凭证存储不可用时，按 doctor 的明确提示修复系统凭证存储。不要通过删除凭证文件或关闭安全保护来猜测修复。

发布要求 MFA，或验证码过期​

MFA 是受保护变更的正常步骤。直接使用终端时，按当前进程提示完成；AI / JSON 模式按返回的挑战 ID、发送验证码和继续命令处理同一次挑战。

不要在命令参数、环境变量、Shell 历史或聊天里填写验证码。Agent 应遵循官方 Skill 指定的安全输入方式；没收到或过期时，使用当前挑战提供的补发或重新验证步骤，不要反复提交新的发布。

上传或发布中断，结果不明确​

  1. 保留原输出，找到站点 ID、操作 ID、原 idempotencyKey 及 resumeCommand 等恢复命令。

  2. 按返回的状态命令查询原操作，或先查看原站点：

    nameslink site hosted status <站点ID> --watch --json
    nameslink site hosted operation <站点ID> <操作ID> --json

  3. 有明确恢复指令时，沿用原操作、原文件和原目标继续。未知结果时不要更换幂等键、重新上传或重新发布。

  4. --watch 是有上限的等待；结束等待不等于业务失败。稍后继续查询原状态。

如果修改了文件，应先查清原操作结果，再按正常的新版本流程操作。不要把变更后的文件强行当作同一次重试。

如果中断前没有取得站点 ID，先运行 nameslink site hosted list --json 核对已有站点。仍无法确认本次结果时，保留操作时间及脱敏输出，联系支持；不要直接新建另一个站点。

命令存在，但业务不可用​

nameslink capabilities --json
nameslink site hosted capability --json

以当前服务返回的可用性、原因和下一步为准。不要改走旧接口、其他托管产品或其他账号绕过限制。静态文件不符合要求时，参考文件准备与预览排障。

联系支持​

通过联系页面或 ticket@nameslink.com 联系支持。提供 CLI 版本、操作系统、API 地址、错误码与提示、发生时间及脱敏的操作 ID。账号、域名等通过私密工单说明，勿公开贴出完整诊断输出。不要提供密码、AK/SK、OAuth 授权链接、MFA 验证码或恢复令牌。