# 安装神念

> 本文供任意具备 Skill 与 Shell 能力的 Agent 执行，包括 Codex、Claude Code、WorkBuddy、Cursor、OpenCode 和自定义 Agent。
> 使用方法以官方 [Shennian Skill](https://shennian.net/agent) 为准。
> 契约版本：`shennian-cli-skill-v1`。

## 0. 在正确的权限边界运行

神念只能安装到当前用户的全局环境，不能安装到项目工作区、沙盒专用目录、临时目录或当前仓库的 `node_modules`。安装、配对和启动神念不是项目代码修改；它们会按操作系统惯例写入以下明确位置：

- npm 的当前用户全局安装目录；
- Codex 的 `$HOME/.agents/skills/shennian`，或其他宿主自己的原生 Skill 目录；
- 由 Shennian CLI 独占维护的 `$HOME/.shennian`；
- macOS 上由 Shennian CLI 维护的 `$HOME/Library/LaunchAgents/com.shennian.agent.plist`。

### Codex / ChatGPT Desktop 必须先开启 Full access

在 Codex / ChatGPT Desktop 中，任何负责安装、配对、启动或使用神念的任务都不能继续运行在工作区沙盒。Agent 必须先检查当前任务输入框左下角显示的权限模式：

1. 如果已经显示 **Full access**，继续后续步骤；
2. 如果显示 **Ask for approval**，立即停止安装，并提示用户点击 **Ask for approval → Full access → Confirm**；
3. 必须由用户本人阅读 OpenAI 的风险说明并确认；Agent 不得替用户确认，也不得在确认前先尝试安装；
4. 用户确认后，从同一个任务继续执行原始安装目标，不要求用户重新发送提示词；
5. 如果组织策略没有提供 **Full access**，保持安装未完成，并明确说明当前 Codex 环境无法完成神念的用户级全局安装。

Codex 的 **Full Auto** 仍可能运行在沙盒中，Browser 的 **Enable full CDP access** 也只控制浏览器；二者都不能替代这里要求的任务级 **Full access**。安装完成后，用户可以把不再需要神念的其他 Codex 任务切回更严格的权限模式。

其他宿主如果运行在受限环境或沙盒中，也必须先停止安装，向用户明确提示需要打开上述用户级全局目录的访问权限，并为**完整的安装或 `shennian` 命令**取得工作区外执行权限；用户授权后再执行。不得退回项目内本地安装，不得通过改写 Shennian 配置、改变 `HOME`、使用临时目录或关闭宿主安全机制来绕过权限。宿主当前不能申请这项权限时，明确告诉用户需要先在宿主设置中开启相应权限，并保持任务为未完成。

Agent 不得手工创建、修改或修复 `$HOME/.shennian/config.json`、`env.json`、`daemon.pid`、`daemon.log`、`daemon-launcher.json` 或 launchd plist；这些文件只能由 Shennian CLI 管理。若宿主开始为这些文件逐个弹出写入确认，立即停止逐文件重试，改为以正确权限重新执行完整的 `shennian pair` / `shennian start` 命令，并向用户解释原因。

## 1. 安装或升级 CLI

```bash
npm install -g shennian@latest
shennian --version
```

必须保留 `-g`。禁止使用 `npm install shennian`、把包写进项目 `dependencies` / `devDependencies`，或从工作区内的 `node_modules/.bin` 运行 Shennian。

## 2. 配对

普通电脑使用浏览器配对：

```bash
shennian pair --browser
```

服务器、SSH 或无图形环境使用 Token 配对：

```bash
shennian pair --token
```

配对需要用户本人在神念网页或 App 中批准。不要要求用户把验证码、登录 Token 或 machine token 发进对话。

## 3. 启动

```bash
shennian start
shennian status
```

需要排查时执行：

```bash
shennian logs
```

## 4. 安装 Shennian Skill

读取：

```text
https://shennian.net/agent
```

使用当前宿主自己的原生 Skill 或 Plugin 管理能力安装到用户级全局环境。禁止把 Skill 放进项目内的 `.agents`、`.codex`、`.claude` 或其他仓库级目录。不要把 CLI 配对成功误当成 Skill 已安装。

### Codex / ChatGPT Desktop

Codex 的个人 Skill 固定安装到：

```text
$HOME/.agents/skills/shennian/SKILL.md
```

使用一个完整、范围受限的 Shell 命令把官方正文原子安装到该目录；不要调用 Skill Creator 改写正文，也不要让模型逐段生成文件：

```bash
skill_dir="$HOME/.agents/skills/shennian"
mkdir -p "$skill_dir"
skill_tmp="$(mktemp "$skill_dir/.SKILL.md.XXXXXX")"
curl --fail --location --silent --show-error https://shennian.net/agent > "$skill_tmp"
mv "$skill_tmp" "$skill_dir/SKILL.md"
```

不要再写到旧的 `$HOME/.codex/skills`；那不是当前 Codex 官方的个人 Skill 目录。完成 CLI 安装、配对和启动后，再做宿主发现验证：

1. 新建一个全新的 Codex 对话；
2. 使用当前宿主显示的原生 Skill 选择器查找 `Shennian`；当前 Codex 支持显式文本调用时可输入 `$shennian`，不要假设其他宿主使用相同前缀；
3. 再新建一个对话，不显式点名 Skill，只要求“查看神念安装状态”，确认宿主能根据描述自动加载 Shennian Skill 并实际执行 `shennian status`；
4. 如果新对话仍未发现，完整重启 Codex 后重复以上验证。

其他宿主使用自己的原生 Skill/Plugin 管理入口，并遵守以下要求：

1. 只安装一个显示名称为 `Shennian` 的 Skill；
2. Skill 正文使用官方地址返回的完整内容；
3. 宿主支持从 URL 或 Plugin 安装时使用其原生方式；
4. 宿主只支持本地 Skill 文件时，将官方正文完整写入宿主要求的位置；
5. 按宿主要求重新加载并新建 Agent 对话。

## 5. 清理旧入口

如果宿主仍显示 `Shennian Room`、`Shennian Helper`、`shennian-room` 或 `shennian-agent`，先向用户列出这些神念旧入口并取得明确同意，再用**当前宿主自己的原生管理命令**精确卸载。不要让 Shennian CLI 修改宿主配置，也不要删除其他来源的 Skill、Plugin、MCP、Hook 或 Computer Use 配置。

## 6. 完成检查

确认：

- `shennian --version` 能正常输出版本；
- `shennian status` 显示后台服务在线；
- 全新对话能显式选择 `Shennian` Skill；
- 全新对话能从自然语言请求自动感知并使用该 Skill 完成一次真实操作；
- 当前宿主只显示一个 `Shennian` Skill。

只有以上各项全部通过才算安装完成。目录中存在 `SKILL.md` 或 Agent 自报“安装成功”都不能单独作为完成证据；任何未完成项都要明确说明。

## 退出登录

```bash
shennian logout
# Agent 或脚本读取结构化结果
shennian logout --json
```

退出登录会停止后台服务、禁止自动启动，并清除本机神念登录与配对凭据。模型配置、本地历史和第三方 Agent 登录保留；云端机器记录、群成员身份以及其他设备和浏览器的登录不受影响。成功可重复执行；失败返回非零退出码，`--json` 返回 `ok: false`，不能视为已退出。

如果只想暂时停止连接，使用 `shennian stop`，它会保留登录信息。退出登录后需重新执行 `shennian pair --browser`（无图形环境用 `shennian pair --token`），并由用户批准配对。不要手工删除配置文件。旧版提示未知命令时，先执行 `npm install -g shennian@latest` 升级。