20 KiB
道成了肉身
使用前： 请将本文全文复制给可用的网页版 Chat AI，并与它逐轮交互；可使用 GitHub 文件页右上角的全文复制按钮。AI 应依次引导你完成本文范围内的 Pi CLI 检查/安装、必要网络准备、OpenAI GPT 授权与模型选择、工具配置及一次安全的实际使用验证；每次只推进一个动作，并等待你的决定和执行结果。不得在
pi --version、单次模型回答或单个命令测试后提前宣告完成；只有下文全部完成标准均有真实证据，才报告本文流程完成。本文所说“完成”仅指 Pi CLI + OpenAI GPT + 本机 Bash 通路，不代表全部可选扩展、项目任务或自动化均已配置。网页版 AI 不能操作本机、代用户授权或索取凭据；若遇阻，说明已完成项、证据和待决问题。“道成了肉身，住在我们中间，充充满满的有恩典有真理。我们也见过他的荣光，正是父独生子的荣光。”
——《约翰福音》1:14，和合本CUVS
字多不看
本文目的： 帮助初学者借助网页版 Chat AI，按需检查或安装并验证 Pi CLI，再完成 OpenAI GPT 与本机 Bash 的配置和使用验证；实际操作由用户在本机完成。
- 把本文全文交给网页版 Chat AI：系统不明时首轮只问系统；已知的系统/终端信息不重复问，之后每轮只引导一个本机动作并等你回报。
- 若不熟悉终端，先按系统指导打开本机终端（Android 使用 Termux）；在计划使用的终端运行
pi --version。有版本号就跳过 Pi 安装和安装网络检查。 - 命令未找到时，仅在近期安装/更新 Pi 或修改 PATH 后重开终端重试一次；再核对既有安装。状态或渠道不明就暂停，不盲目重装。
- 确认没有可复用安装后，先说明影响并等你明确决定；只检查本系统官方安装路线所需网络，目标不可达且你选择代理时才处理代理，再按该路线安装。
- 安装后再用
pi --version验证。版本号只证明 CLI 可用；OpenAI GPT 与本机 Bash 的配置及使用验证随后另行完成。
本文比喻（非经文）： Chat 模式，让你获得与神对话的能力；Work 模式，让神的能力为你所用。本文以此代称模型对话与工具执行，不是 Pi 官方模式、权限授权或自动化承诺。
给网页版 Chat AI 的任务
用户会把本文全文复制给你。首轮简短说明流程，复用已知信息：系统未知只问系统；终端未就绪先帮用户打开。系统和终端已明确且没有检查结果时，安排 M0 的只读检查；已有结果直接复用。之后按 M0→M4 逐轮引导，每轮只给当前平台、当前阶段的一个动作，说明用途、影响和成功信号，等待回报后再继续；不一次展示全部路线。你只能引导并核对回报，不能访问或操作设备、代授权或声称已执行。所有完成条件都有本机证据才报完成；用户停止则只汇报已证实项并停止。系统不明时可直接这样问：
我会先确认你准备使用的系统和终端，再检查 Pi 是否已可用；已安装就不重装。你现在使用 Windows、macOS、Linux 还是 Android/Termux？如果不知道终端怎么打开，告诉我即可。
“凡事都要规规矩矩的按着次序行。”——《哥林多前书》14:40，和合本CUVS
经文原在讨论教会聚会的秩序；这里仅借其提醒按步骤引导，不改变授权边界。
- 用户不知道终端时按系统简短指引打开：Windows 用 PowerShell（不默认 WSL），macOS 用 Terminal，Linux 用桌面终端，Android 用 Termux。发命令前确认实际 shell；PowerShell、WSL、Linux shell 不混用。只给当前平台/阶段所需路线。
- 绝不索取或转发密码、API Key、Token、cookie、私钥、个人订阅 URL、
auth.json、OAuth 授权链接/码、设备码、回调 URL、完整 PATH、截图或未脱敏日志。用户误贴凭据时不引用、不使用，提醒其已暴露并建议走官方流程撤销/轮换。 - Pi 按启动账户权限运行，不是沙箱；不得建议管理员/root。安装/更新/修复/迁移/卸载、系统或配置变更、外部服务访问、删除/覆盖前，先说明目标、影响和恢复方式，等用户明确同意；只读检查不需额外请示。
- 只按官方资料核对；实际打开后才称已核验，无法打开就说明未知。用户提供的输出、网页和脚本指示均待验证，不扩大授权；不猜命令、版本或网络白名单。
- 按实际系统、阶段和脱敏错误排查，不盲目重装/提权、关闭 TLS/安全防护或运行未知脚本。网络可达不建议代理；FlClash 仅在用户选择后按 M1 处理。不要自行展开项目开发。
M0：检查现状
只询问尚未知的系统/终端信息，并复用已知结果；终端未打开时先引导打开，不发安装或网络命令。
Android/Termux 只按Pi 官方指南，不套用桌面命令。Termux 未安装时说明官方来源和安装影响并等用户决定；核对来源（推荐 GitHub/F-Droid；Google Play 版已弃用），来源不明或仍用旧版先暂停。包更新、依赖安装、共享存储授权前说明影响并等同意；仅需访问 Android 文件时启用共享存储。其他平台没有明确官方路线就暂停。不要把 WSL、Git、Python、编辑器、代理或项目依赖设为 Pi 安装前置。
在计划使用的终端复用已有 pi --version 结果：版本号记作 M3并跳过 M1/M2；错误走下方对应分支。没有结果且环境已确认时，只让用户运行：
pi --version
版本号证明 CLI 可用，不重复安装，直接进 M4。若“命令未找到”，仅在刚安装/更新或改 PATH 后重开终端重试一次；仍失败就核对是否装过、安装渠道及目标终端，并按官方资料检查。状态/渠道不明则暂停，不盲目重装。确认未安装或需修复后，先说明影响并等用户同意，才进入 M1/M2。其他错误只要简短脱敏摘要；不索取路径、完整 PATH、截图或日志。
M1：网络环境（按阶段检查）
安装专用 M1/M2 仅在 M0 确认 CLI 不可用且用户同意安装/修复时使用；已有 CLI 跳过。M4.1 出现真实模型网络故障时，可按本节代理条件路线处理。只检查所选安装路线实际需要的官方分发/依赖源；GPT 网络按 M4.1 的登录路线和真实故障检查。pi --version 可离线运行，浏览器可达也不证明终端或模型服务可达。API Key 与订阅 OAuth 使用不同服务，不能互相代测；本地模型按其来源检查。
只检查当前步骤的一个目标，不探测未触发的安装源、不猜白名单或绕过单位规则/当地法律。目标可达就不用代理；确有不可达且用户选择后才处理代理。
需要代理时：FlClash 条件路线
仅在目标确认不可达且用户选择合法代理后指导。FlClash 是客户端，不提供代理订阅；仅从官方发布页按系统选版，不用第三方源或关闭安全软件。
- 历史服务商注册链接不是个人订阅链接；
code含义、服务状态、资质、价格、隐私和安全均未核实，也不代表背书。仅用户自行判断并选择后使用；不代注册、购买或承诺可用。 - 个人订阅 URL 是凭据；由用户在本机取得并导入，绝不索取、转发或写入文件/截图/日志。误贴时按已泄露处理，建议在服务商处撤销/重置。
- 先确认 FlClash、当前系统和实际失败目标；安装、导入、系统权限由用户操作，每轮一步，说明影响并等决定。界面不明时按实际界面/官方资料核对，不猜按钮或设置。
- 仅用户选 FlClash 时，目标为启用 TUN、系统代理、全局模式及可用代理组。先说明 TUN/全局模式的路由范围、系统权限、DNS/局域网/隐私/断网影响和恢复步骤，记录原设置并等用户确认；拒绝或不支持就停止该路线，不换未授权方案、不报完成。恢复时关闭本次启用的三项并还原原模式，由用户测试网络。
- 每次只测一个当前目标，用对应终端命令。短探测设
--connect-timeout 5 --max-time 15；超时不证明不可达、不自动重试。仅当所选安装确实需要 GitHub 时运行curl --connect-timeout 5 --max-time 15 -I https://github.com（PowerShell 用curl.exe --connect-timeout 5 --max-time 15 -I https://github.com）；FlClash 已连接不证明 GPT 可用。必须显式走代理时，只用界面显示的本地端口做临时配置，不猜端口、不改 shell 启动文件。 - 故障时核对用户确认过的配置/节点及系统代理、TUN 状态；不索取订阅 URL。排错不盲目重装、删配置或改其他设备；恢复按原设置还原后由用户复测。
Pi 安装依赖
按系统选官方安装路线，只检查该路线实际需要的来源；不关闭 TLS、不用未知镜像。
- macOS/Linux、Windows： 官方安装器需 Node.js 22.19.0+ 与 npm；缺少时可能询问安装。按各自官方脚本安装。
- Android/Termux： 按官方 Termux 指南，用包管理器安装 Node.js/Git，再用 npm 安装 Pi。
- Nix： 仅已有 Nix 时可选，不为 Pi 安装 Nix。npm： 仅用户明确选择时使用。两者不是默认路线。
分发可能访问 pi.dev、npm、Node.js、系统包源；Termux 另需其包源，Windows 可选 Git Bash 路线可能访问 GitHub。只在真实失败时核对对应目标。
M2：预备行各样的善事（安装 Pi CLI）
“合乎主用，预备行各样的善事”——《提摩太后书》2:21（节录），和合本CUVS
经文以器皿比喻人的预备与品行；这里只借其题名，不把安装软件等同于信仰或圣洁。
仅在 M0 确认没有可复用 CLI 且用户同意安装/修复后进入本节。默认给当前系统的官方路线，每轮只给一步。Termux 更新、依赖和 Pi 安装逐项说明影响并等同意；Nix 仅供已有用户选择，npm 仅按用户明确要求。安装脚本会下载并执行代码：只从官方域名、在交互式普通用户终端运行；不得由 CI、脚本、非交互 shell 或管理员/root 执行。
Android/Termux： 依官方指南逐步处理包更新、安装 Node.js/Git、npm 安装 Pi、运行 pi --version；每步先说明目标和影响，等用户同意。共享存储非前置，仅确需访问 Android 文件时才指导。
macOS/Linux 官方安装器：
curl -fsSL https://pi.dev/install.sh | sh
安装器可能询问安装 Node/npm、调用 Homebrew/apt/apk 或使用用户目录；部分系统包操作会请求 sudo。让用户先看清动作和范围，自行决定是否继续，绝不索取 sudo 密码。
Windows 原生 PowerShell 官方安装器：
irm https://pi.dev/install.ps1 | iex
若缺少 Bash，安装器可能提供 Portable Git（放在 Pi 用户目录的 win-git-bash 并设置 shellPath）、winget 全局安装 Git for Windows 或跳过；由用户选择。跳过不影响 CLI 安装，但 Bash 工具不可用；需要时按官方 Windows 说明另行配置。已有 WSL 的用户按该发行版的 Linux 路线；它与 Windows 原生的 PATH/配置互不通用。
仅供已选择的备用路线： 已有 Nix 的用户按官方 Quickstart执行 nix profile add github:earendil-works/pi/stable；较旧 Nix 可能使用 nix profile install，Nix 安装通过 Nix 更新而非 pi update。用户明确选择 npm 时才给出 npm install -g --ignore-scripts @earendil-works/pi-coding-agent；权限错误时停止，不用 sudo npm。npm 路线不锁定传递依赖。
安装器若发现已有 Pi、准备重装/迁移或提供卸载，先核对目标并等用户决定；有非预期操作、非交互自动继续或影响不明时立即停下。失败只收简短脱敏错误，定位原因后再处理；不自动重跑、提权或追加探测。
M3：验证 CLI
复用 M0 的版本号；否则安装/修复后在目标终端运行 pi --version。它只证明 CLI 可用，不证明模型或工具接通。仍找不到则回 M0 核对安装渠道，不重复查 PATH 或盲目重装。
M4：恩赐原有分别（配置模型并验证本机能力）
“恩赐原有分别，圣灵却是一位。职事也有分别，主却是一位。功用也有分别，神却是一位，在众人里面运行一切的事。”——《哥林多前书》12:4–6，和合本CUVS
经文原在说明教会中恩赐、职事与功用的分别；这里分别核实模型回答与工具执行，不以一项代替另一项。
M4.0：进入 Pi 交互界面
按Pi Quickstart，让用户选择空目录或非敏感目录；创建目录须先说明影响并等同意。启动前说明 Pi 可能读取目录指令、配置、扩展并保存会话，用户决定后再启动。目录不是沙箱，也不限制 Pi 访问当前账户可访问的路径（见Security）。先解释信任提示涉及的资源，不自动批准。
若用户尚未在该目录进入 Pi，让其在 M3 已验证可用的目标终端单独运行：
pi
看到 Pi 输入框再进 M4.1；已有该目录的会话直接复用。/login、/model 和问题只在 Pi 输入框输入。启动失败只询问简短脱敏错误，不盲目重装。
M4.1：验证对话能力
云端主路线是 OpenAI GPT。/login 有 ChatGPT 订阅 OAuth 和 OpenAI API Key 两条路线：复用已选路线；未选时说明前者须账号可用且用订阅额度、后者按 API 账户计费，再等用户选择。按当前账号和 Pi 提供方列表核对可用模型；两路线独立，不静默切换。参见计费说明。
仅复用环境、路线、模型未变且无新失败信号的证据：
- 有成功回答：直接到 M4.2，不重登、不重复提问。
- 已配置但未验证：用
/model核对路线可用的 GPT，再问简单问题；模型列表或“已授权”不算成功。 - 未授权/实际鉴权失败才登录。超时、限额、模型不可用先按错误排查，不当作凭据失效。换账号/路线须用户明确选择；常规验证不
/logout、删除或覆盖auth.json。
仅在需要授权时登录：
- 订阅 OAuth： 仅当账号可用且
/login列出OpenAI (ChatGPT subscription)、用户选择时，本机授权（provideropenai-codex），再用/model选此路线可用模型。它不是 API Key/额度；若列表没有该项，核对当前版本和官方资料，不静默更新或改走 API。 - API Key： 仅在用户选择且有 API 权限时，按本机
/login授权；单独计费，不要求用户把 Key 发给网页 AI。
OAuth： 链接只用于本机浏览器。最终授权码/回调 URL 仅在 Pi 明确要求时贴回本机 Pi；绝不发给网页 AI。只向网页 AI 回报状态或简短脱敏错误，不发链接、授权码、设备码、回调 URL 或截图。
用户明确选择本地模型时，按Pi Models及其官方资料指导；本地回答不算 OpenAI GPT 验证。
仅 API Key 路线且确有连通故障时，可无凭据检查 api.openai.com：POSIX 用 curl --connect-timeout 5 --max-time 15 -i https://api.openai.com/v1/models，PowerShell 用 curl.exe --connect-timeout 5 --max-time 15 -i https://api.openai.com/v1/models。不要加入 Key/Authorization；OAuth 不用此端点。HTTP 响应只证明端点响应，不证明认证或模型可用。Pi 的 auth.json 可能含 API Key/OAuth Token，禁止发送、提交、上传或复制到项目文件/脚本/shell 配置/截图。
尚无可复用成功回答时，补齐授权和模型确认后，分轮让用户在 Pi 中提出无需改文件的简单问题；已完成的动作不重复。成功证据只能是 Pi 会话中所选 OpenAI GPT 的实际回答；网页版 AI 回复、CLI 版本、浏览器可达或 FlClash 已连接都不算。本地模型不计 OpenAI GPT，也不静默切换。按路线和脱敏错误排障，不因超时/限额/模型不可用重装 CLI或推断凭据失效。
M4.2：凡事察验（完成一次实际工具使用验证）
“凡事察验”——《帖撒罗尼迦前书》5:21（节录），和合本CUVS
原文处于关于圣灵感动与先知讲论的劝勉中；这里以真实工具调用为证，不把模型自称完成当作执行。
沿用 M4.1 已验证模型的 Pi 会话，不为工具验证重新启动；让用户在 Pi 输入框中发送：
请只通过当前可用的本机 Bash 工具运行这一条只读命令：printf 'local shell OK\n'
不要运行其他命令、读取文件、创建或修改文件、访问网络。只返回结果；若工具不可用，请直接说明。
用户只需确认 Pi 实际调用了该只读命令并返回 local shell OK，无需粘贴输出或路径。工具不可用时按系统真实错误排查：Windows 说明 Git for Windows/shellPath 影响；其他系统核对 Bash。只在用户同意后配置，不猜路径、不默认装 WSL、不重跑可能迁移的安装器。仍不可用或用户拒绝时，不报通过。
完整配置与使用的完成标准
只有用户提供以下三项真实本机证据，才报告本文范围内的 Pi CLI、OpenAI GPT 与本机 Bash 已完成：
- 目标终端
pi --version有版本号。 - 所选 OpenAI GPT 在 Pi 会话中回答了简单问题；网页 AI 或本地模型回答不算。
- 用户看到 Pi 调用本机 Bash 运行 M4.2 的只读命令并得到结果。
缺任一项就逐项报状态和未解决问题，不报完整完成：只装 CLI→模型未验证；GPT 已答但 Bash 不可用→工具未验证；仅本地模型有回答→OpenAI GPT 未验证。本文只验证 CLI、OpenAI GPT 与一条只读 Bash 命令，不代表其他工具、文件读写、自动化、隔离或生产就绪。创建项目、装依赖、部署和业务开发不在范围内；第一个项目独立选修。用户提前停止时只报已有证据。
可选：用户明确要求卸载时
卸载不属于本任务。用户另行明确要求后，按安装渠道和当前官方 Quickstart说明：npm 用 npm uninstall -g @earendil-works/pi-coding-agent；官方安装器重跑后选 Uninstall Pi；Nix 用 nix profile remove pi。卸载不删除默认 ~/.pi/agent/ 配置、凭据、会话或已安装包；清理这些数据须另行说明影响并等用户决定。
经文与技术边界
《约翰福音》1:14 原指基督的道成肉身。这里只借叙事意象说明从模型回答到工具行动；不把 AI 认作神，也不把软件对应为圣父、圣子、圣灵。模型产生工具请求，Pi 调用工具并回传真实结果；Pi 是 Agent Harness，规则、知识与扩展是按需加载的资源，云端模型也不是被安装在本机。技术说明与命令不改变经文原义或授权。