# ProtoNote CLI 与 Skill：Agent 安装指南

用户要求安装时，按本指南执行。只分享链接而未要求安装时，先解释用途。
CLI 是本机连接与同步工具；Skill 是 Codex 的工作流规则。安装顺序：检查环境 → CLI → Skill → 验证 → 用户浏览器授权 → 用户在目标工作区显式启用。

## 执行规则与验收

1. 检测当前操作系统和 Shell，只运行对应代码块。Windows PowerShell 使用 npm.cmd 和 protonote.cmd，避免 .ps1 执行策略问题。不要把两种系统命令混合执行。
2. 读取 [发布清单](https://789779.xyz/downloads/manifest.json)。本指南由同一次构建的清单生成；若版本已更新，重新读取安装页。Node.js 要求 >=22.13.0；缺失或不满足时先安装兼容版本，再继续。
3. 下载固定版本文件后，在 npm 安装或 ZIP 解压前校验 SHA-256：Windows 用 Get-FileHash -Algorithm SHA256；macOS 用 shasum -a 256；Linux 用 sha256sum。与清单不符立即停止，不能跳过校验。
4. 本次 CLI 0.2.1 SHA-256：5bc1eeae96541b3a91662124fa76c56570f9d8acf87de6c6b2c07bbe8aa9cc0b；Skill 0.2.1 SHA-256：12eb8e93652259224f9d514bdeb98e772c2343665d7c249d9ab3cf8867a8688c。下载地址见下方说明与清单。
5. 每条命令失败即停止并解决原因。权限不足时优先使用当前用户可写的 npm prefix；不要自动 sudo。PATH 必须同时在当前 Shell 和新终端可用。
6. Skill 安装根目录为 CODEX_HOME/skills；未设置 CODEX_HOME 时为用户目录下 .codex/skills。若 protonote-prototype 已存在，先备份该目录，再解压，保留用户自定义内容。确认 protonote-prototype/SKILL.md 和 agents/openai.yaml 存在，并读取 SKILL.md；重新打开 Codex 使 Skill 被发现。其他 Agent 可安装 CLI，但不要声称它们会自动加载 Codex Skill。
7. CLI 安装验收：命令可发现、--version 与清单匹配。auth status 未登录表示安装成功但授权待完成；已经登录时无需重复 auth login。需要登录时启动 auth login 并保持进程运行，请用户在浏览器完成授权；不得索取、读取或输出令牌。
8. 安装 Skill 不代表授权修改线上文档。只有用户在目标工作区显式调用 @ProtoNote Prototype Skill 时才执行 agent enable --dir .；不要在任意当前目录自动启用。project list 等远程操作也应在用户启用后进行。
9. 分别报告 CLI 版本与 PATH、Skill 文件与发现状态、账号授权状态、工作区启用状态。用户尚未完成授权或重启 Codex 时明确标记待完成，不能声称全部成功。

下方为与网页共用内容生成的系统命令。执行下载命令后先按规则 3 校验文件，再继续安装或解压。若网页中的手动排查步骤与上述启用顺序有冲突，以显式启用要求为准。

[ProtoNote](/)/安装指南/CLI 安装

PROTO NOTE DEVELOPER TOOLS

# 安装 ProtoNote CLI

在你的电脑上安装命令行工具，用浏览器完成账号授权，再让本地 AI 工作区安全地读取、校验和提交线上原型。

当前版本 0.2.1Node.js >=22.13.0支持 Windows / macOS / Linux

[AI Agent 安装指南（纯文本，包含 CLI 和 Skill 完整步骤）](/install/agent.md) · [Agent 入口](/llms.txt)

安装前请确认 Node.js 版本CLI 需要 Node.js 22.13.0 或更高版本。授权不会写入原型文件或 Codex 对话。

01

## 检查运行环境

打开 PowerShell、命令提示符或终端，确认 Node.js 版本满足要求：

### Windows PowerShell

```
node --version
npm.cmd --version
```

### macOS / Linux

```
node --version
npm --version
```

02

## 安装 CLI

推荐先下载固定版本包，再从本地文件安装，便于校验和回滚。下面的命令会读取 npm prefix -g，兼容 nvm、Homebrew、Conda、Hermes 等非标准 Node.js 环境，并把 CLI 目录加入当前 Shell 和用户级 PATH：

### Windows PowerShell

```
$ErrorActionPreference = "Stop"
$version = "0.2.1"
$package = Join-Path $env:TEMP "protonote-cli-$version.tgz"
Invoke-WebRequest -Uri "https://789779.xyz/downloads/protonote-cli-0.2.1.tgz" -OutFile $package
if ((Get-FileHash -Algorithm SHA256 -LiteralPath $package).Hash -ne "5bc1eeae96541b3a91662124fa76c56570f9d8acf87de6c6b2c07bbe8aa9cc0b") { throw "CLI SHA-256 校验失败" }
npm.cmd install -g $package
if ($LASTEXITCODE -ne 0) { throw "CLI 安装失败" }
$npmPrefix = (npm.cmd prefix -g).Trim()
if (-not $npmPrefix) { throw "无法读取 npm 全局安装目录" }
$env:Path = "$npmPrefix;$env:Path"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$userPathParts = @($userPath -split ";" | Where-Object { $_.Trim() })
if (-not ($userPathParts | Where-Object { $_.TrimEnd("\") -ieq $npmPrefix.TrimEnd("\") })) {
  $newUserPath = if ($userPath) { "$userPath;$npmPrefix" } else { $npmPrefix }
  [Environment]::SetEnvironmentVariable("Path", $newUserPath, "User")
}
Get-Command protonote.cmd -ErrorAction Stop | Out-Null
protonote.cmd --version
protonote.cmd auth status
```

### macOS / Linux

```
set -eu
version="0.2.1"
package="${TMPDIR:-/tmp}/protonote-cli-${version}.tgz"
curl --fail --location "https://789779.xyz/downloads/protonote-cli-0.2.1.tgz" --output "$package"
if command -v sha256sum >/dev/null 2>&1; then actual=$(sha256sum "$package"); else actual=$(shasum -a 256 "$package"); fi
[ "${actual%% *}" = "5bc1eeae96541b3a91662124fa76c56570f9d8acf87de6c6b2c07bbe8aa9cc0b" ] || { echo "CLI SHA-256 校验失败" >&2; exit 1; }
npm install --global "$package"
npm_prefix="$(npm prefix --global)"
if [ -z "$npm_prefix" ]; then echo "无法读取 npm 全局安装目录" >&2; exit 1; fi
npm_bin="${npm_prefix}/bin"
if [ ! -x "$npm_bin/protonote" ]; then npm_bin="$npm_prefix"; fi
export PATH="$npm_bin:$PATH"
shell_rc=""
login_shell="${SHELL:-/bin/sh}"
case "${login_shell##*/}" in
  zsh) shell_rc="${ZDOTDIR:-$HOME}/.zshrc" ;;
  bash) shell_rc="$HOME/.bashrc" ;;
  *) shell_rc="$HOME/.profile" ;;
esac
path_line=$(printf 'export PATH="%s:$PATH"' "$npm_bin")
if [ -n "$shell_rc" ]; then
  touch "$shell_rc"
  if ! grep -Fqx "$path_line" "$shell_rc" 2>/dev/null; then
    printf '\n# ProtoNote CLI (npm global bin)\n%s\n' "$path_line" >> "$shell_rc"
  fi
fi
hash -r 2>/dev/null || true
command -v protonote
protonote --version
protonote auth status
```

[直接下载 CLI 0.2.1](https://789779.xyz/downloads/protonote-cli-0.2.1.tgz)也可以把下面这句话发送给 Codex、Cursor 或其他 AI Agent，让它按本页流程协助安装：

### 给 AI Agent 的安装指令

```
请按照 https://789779.xyz/install/cli 安装 ProtoNote CLI，完成 Node.js 检查、PATH 可发现性、CLI 版本和 auth status 验证；不要索取或输出我的授权令牌。
```

03

## 完成浏览器授权

CLI 会打开 ProtoNote 登录页。请保持当前终端运行，直到授权完成：

### Windows PowerShell

```
protonote.cmd auth login
```

### macOS / Linux

```
protonote auth login
```

浏览器跳转到 127.0.0.1 的回调地址属于正常现象。授权链接只在当前登录流程中有效，不要转发给其他人。

04

## 验证安装结果

安装命令最后会自动检查命令可发现性、CLI 版本和账号状态；手动复核时执行：

### Windows PowerShell

```
protonote.cmd --version
protonote.cmd auth status
```

### macOS / Linux

```
command -v protonote
protonote --version
protonote auth status
```

如果 zsh 启动时提示 ~/.local/bin/env 不是 Shell 脚本，这是 Hermes 的独立配置问题：先备份 ~/.zshrc，再删除其中 source 这个二进制文件的错误行，然后重新打开终端。不要把该二进制文件当作脚本执行。

之后再安装 Skill，并在需要使用 ProtoNote 的 Codex 工作区调用 @ProtoNote Prototype Skill。

NEXT STEP

## 继续安装 Skill

CLI 只负责本机连接和文件同步；安装 Skill 后，Codex 才能按项目规则工作。

[去安装 Skill](/install/skill)

[ProtoNote](/)/安装指南/Skill 安装

PROTO NOTE DEVELOPER TOOLS

# 安装 ProtoNote Prototype Skill

把 ProtoNote 的原型规范、批注规则和提交流程接入 Codex。安装后，在任意 Codex 工作区调用 @ProtoNote Prototype Skill 即可开始。

当前版本 0.2.1Node.js >=22.13.0支持 Windows / macOS / Linux

[AI Agent 安装指南（纯文本，包含 CLI 和 Skill 完整步骤）](/install/agent.md) · [Agent 入口](/llms.txt)

先安装 CLI，再安装 SkillSkill 负责工作流规则，CLI 负责本机文件同步和线上提交，两者需要配合使用。

01

## 确认 CLI 已安装

如果还没有安装命令行工具，请先完成 [CLI 安装](/install/cli)。在终端确认：

### Windows PowerShell

```
node --version
protonote.cmd --version
```

02

## 下载并安装 Skill

Skill 包不包含账号凭据，只包含工作流说明和 Codex 元数据。请选择对应系统执行：

### Windows PowerShell

```
$ErrorActionPreference = "Stop"
$zip = Join-Path $env:TEMP "protonote-prototype-skill-0.2.1.zip"
Invoke-WebRequest -Uri "https://789779.xyz/downloads/protonote-prototype-skill-0.2.1.zip" -OutFile $zip
if ((Get-FileHash -Algorithm SHA256 -LiteralPath $zip).Hash -ne "12eb8e93652259224f9d514bdeb98e772c2343665d7c249d9ab3cf8867a8688c") { throw "Skill SHA-256 校验失败" }
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
$skillRoot = Join-Path $codexHome "skills"
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
$installedSkill = Join-Path $skillRoot "protonote-prototype"
if (Test-Path -LiteralPath $installedSkill) { Copy-Item -LiteralPath $installedSkill -Destination "$installedSkill.backup-$([Guid]::NewGuid().ToString('N'))" -Recurse }
Expand-Archive -Path $zip -DestinationPath $skillRoot -Force
```

### macOS / Linux

```
set -eu
skill_root="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$skill_root"
curl --fail --location "https://789779.xyz/downloads/protonote-prototype-skill-0.2.1.zip" --output "/tmp/protonote-prototype-skill-0.2.1.zip"
if command -v sha256sum >/dev/null 2>&1; then actual=$(sha256sum "/tmp/protonote-prototype-skill-0.2.1.zip"); else actual=$(shasum -a 256 "/tmp/protonote-prototype-skill-0.2.1.zip"); fi
[ "${actual%% *}" = "12eb8e93652259224f9d514bdeb98e772c2343665d7c249d9ab3cf8867a8688c" ] || { echo "Skill SHA-256 校验失败" >&2; exit 1; }
if [ -d "$skill_root/protonote-prototype" ]; then
  backup_dir=$(mktemp -d "$skill_root/protonote-prototype.backup.XXXXXX")
  cp -R "$skill_root/protonote-prototype" "$backup_dir/"
fi
unzip -qo "/tmp/protonote-prototype-skill-0.2.1.zip" -d "$skill_root"
```

[直接下载 Skill 0.2.1](https://789779.xyz/downloads/protonote-prototype-skill-0.2.1.zip)

03

## 在 Codex 中启用

重新打开 Codex 或刷新当前工作区，然后发送：

### Codex 对话

```
@ProtoNote Prototype Skill

请检查当前工作区是否已启用 ProtoNote，并准备开始工作。
```

Skill 第一次接管工作区时，会创建当前工作区的启用标记。不同项目需要分别启用，不会自动读取其他工作区。

04

## 完成一次工作区检查

仅在用户于目标工作区显式调用 @ProtoNote Prototype Skill 后执行启用。安装本身不会自动启用工作区；需要手动排查时，在该目标目录执行：

### Windows PowerShell

```
protonote.cmd agent enable --dir .
protonote.cmd auth status
```

NEXT STEP

## 开始处理线上原型

CLI 和 Skill 都安装好后，就可以让 Codex 按 ProtoNote 的规范准备、校验并提交原型版本。

[返回 ProtoNote](/)