docs: tutorials - improve scanability and clarify OAuth provider (#252)

.github/getting-started-AGENTS.md

@@ -16,7 +16,7 @@
 ## 修改规则
 
 - 根`README.md`是唯一主页；`getting-started-README.md`只做导航，不复制完整教程。
-- `pi-cli-setup.md` 本身就是给网页版 Chat AI 的完整提示词：文件头要求用户全文复制并逐轮互动；网页 AI 首轮简短说明路线；系统不明时才问系统，已提供的系统/终端信息直接复用；实际终端未确认或未就绪时指导打开/确认本机终端（Android 使用 Termux；仅在 Termux 未安装时才说明其官方来源与安装影响并等待用户明确决定），若用户尚无检查结果且系统、实际终端已明确且已打开，可直接安排 M0 只读版本检查；已回报目标终端的版本号则复用证据并跳过，已回报错误则按对应错误分支处理、不重复初始检查（仅允许明确规定的条件性重试）；Android/Termux 按 Pi 官方 Termux 指南引导，不套用桌面安装命令。再从 M0 引导到 M4，按需检查/安装 Pi CLI、准备网络、连接 OpenAI GPT、验证本机 Bash；若 CLI 已验证可用则跳过安装专用网络检查与安装步骤。安装阶段只核对当前安装路线所需目标，不逐项探测未触发的安装源；短网络探测须设置连接和总时限，并说明超时不等于不可达；OpenAI 模型网络检查仅在 M4.1 按所选登录路线与实际故障执行；Pi 的 OpenAI GPT 路线区分 ChatGPT 订阅 OAuth（provider `openai-codex`）和 OpenAI API Key，不得将 ChatGPT 订阅等同 API 额度；用户另选本地模型时按请求可另行指导，但不计作 OpenAI GPT 验证或满足完成标准第 2 项；仅 API Key 路线可探测 `api.openai.com`，订阅 OAuth 不用该端点代测。安装路线默认优先对应系统的官方安装器，且每轮只展示一条当前路线。完成标准第 2 项只计 Pi 会话中所选 OpenAI GPT 模型对简单问题的实际回答，网页版 Chat AI 自身回复不算；必须等全部完成标准有真实证据后才报告完成，不得停在版本号、模型回答或单次命令检查。网页 AI 只核对用户回报，不能冒充本机执行。本文完成范围限 Pi CLI、OpenAI GPT 与本机 Bash 通路，不承诺所有扩展、项目任务或自动化，不另维护重复提示词或项目开发步骤。
+- `pi-cli-setup.md` 本身就是给网页版 Chat AI 的完整提示词：文件头要求用户全文复制并逐轮互动；网页 AI 首轮简短说明路线；系统不明时才问系统，已提供的系统/终端信息直接复用；实际终端未确认或未就绪时指导打开/确认本机终端（Android 使用 Termux；仅在 Termux 未安装时才说明其官方来源与安装影响并等待用户明确决定），若用户尚无检查结果且系统、实际终端已明确且已打开，可直接安排 M0 只读版本检查；已回报目标终端的版本号则复用证据并跳过，已回报错误则按对应错误分支处理、不重复初始检查（仅允许明确规定的条件性重试）；Android/Termux 按 Pi 官方 Termux 指南引导，不套用桌面安装命令。再从 M0 引导到 M4，按需检查/安装 Pi CLI、准备网络、连接 OpenAI GPT、验证本机 Bash；若 CLI 已验证可用则跳过安装专用网络检查与安装步骤。安装阶段只核对当前安装路线所需目标，不逐项探测未触发的安装源；短网络探测须设置连接和总时限，并说明超时不等于不可达；OpenAI 模型网络检查仅在 M4.1 按所选登录路线与实际故障执行；Pi 的 OpenAI GPT 路线区分 ChatGPT 订阅 OAuth（Pi 1.4.0 使用 provider `openai`）和 OpenAI API Key（同一 provider 的另一认证方式），不得将 ChatGPT 订阅等同 API 额度；用户另选本地模型时按请求可另行指导，但不计作 OpenAI GPT 验证或满足完成标准第 2 项；仅 API Key 路线可探测 `api.openai.com`，订阅 OAuth 不用该端点代测。安装路线默认优先对应系统的官方安装器，且每轮只展示一条当前路线。完成标准第 2 项只计 Pi 会话中所选 OpenAI GPT 模型对简单问题的实际回答，网页版 Chat AI 自身回复不算；必须等全部完成标准有真实证据后才报告完成，不得停在版本号、模型回答或单次命令检查。网页 AI 只核对用户回报，不能冒充本机执行。本文完成范围限 Pi CLI、OpenAI GPT 与本机 Bash 通路，不承诺所有扩展、项目任务或自动化，不另维护重复提示词或项目开发步骤。
 - `pi-cli-setup.md` 使用正常 Markdown 排版，标题、段落和链接直接渲染；粗体标记 `**...**` 与紧邻的中文正文之间保留空格，并通过提示词契约测试确认真实渲染；仅命令和对话示例保留独立代码块，不用外层围栏包住全文。整篇使用 GitHub 文件页右上角的原生全文复制按钮。移除折叠标签、HTML 锚点和页内章节链接；入站链接及历史重定向直接指向 `pi-cli-setup.md`，文集链接不生成失效片段。修改时移除宗教话语，改用简洁、中性的技术描述，并保留操作流程、安全边界和完成标准；不使用宗教标题、经文引用或宗教隐喻，也不因此改变授权或效果边界。
 - 安装方式、Node.js 版本要求、系统支持和 provider 流程以 Pi 当前官方文档与安装入口为准；链接及命令须明确系统、终端、影响和成功判断。官方资料未说明的内容标为未知，不猜测。
 - 区分 `pi --version`、模型授权/可用和项目任务完成；不把 CLI 安装说成模型已接通或项目环境已就绪。模型授权前，M4.0 先说明目录资源加载、会话保存与信任提示的影响，再引导用户在目标终端用 `pi` 进入交互界面；`/login`、`/model` 和问题在 Pi 输入框而非系统终端或网页版 AI 输入。已有目标目录的 Pi 会话直接复用，M4.2 不要求重新启动；空目录不是沙箱。M4.1 复用目标环境、路线与模型均未变化且无新失败信号的 GPT 成功回答，不重复登录或提问；已配置但无回答时仍须实际验证，只有缺少授权或实际鉴权失败才处理登录，不能将网络超时、限额或模型不可用直接归因于凭据失效，不为常规验证退出账号、删除或覆盖凭据。

.github/how-to-complete-work.md

@@ -171,16 +171,14 @@
 对每项原定标准标出“通过 / 未通过 / 未验证”及对应证据；保留失败现象，单列超范围变化，缺证据就标“未验证”。区分事实、推断与未知；不要修改文件、放宽原标准或把失败项写成通过。
 ```
 
-想练习记住方法时，可选地先合上对话和笔记，用自己的话回忆本次的方法选择与证据，再对照原记录补漏；想不起的地方如实标“未知”。这只是低风险的学习练习，不是工作验收，也不是使用本指南的条件。
+以下学习练习都可跳过；它们不是工作验收，也不是使用本指南的条件：
 
-若本次确有代码改动，想练习解释时，可选地挑一处非敏感的小改动，用自己的话说明它做什么、为什么符合一项原定标准；适用时，再手动追踪一个具体输入。然后对照真实差异与验收证据，记录说不清的部分。这是可跳过的学习练习，不要求运行代码，也不替代测试或验收。
-
-若想再练一次，可隔一段时间后不看记录再次回忆同一方法与证据，再对照补漏；间隔由你决定，不是必做计划。
+- **回忆与解释：**先合上对话和笔记，用自己的话回忆方法选择、证据和适用条件，再对照记录补漏；不确定处标“未知”。若本次改过代码，可挑一处非敏感改动，说明它如何对应一项原定标准；适用时手动追踪一个输入，并对照实际差异与验收证据记下说不清处。不要求运行代码，也不替代测试或验收。
+- **间隔练习：**若想重复回忆，可隔一段时间再做一次；间隔由你决定，不是必做计划。
+- **方法迁移：**自选第二情境（只构想即可），比较问题、约束和成功证据，说明本次方法哪些可复用、哪些需调整或不适用。理由应能回指本次记录；未在新情境实际验收前，不说迁移已成功。
 
 复盘时记录：哪些问题信号决定了方法选择？方法之间怎样衔接？哪一步的证据改变了方案？哪些做法可迁移到其他目标？哪些假设或限制仍未解决？复盘结论应由本次实际过程支持，不把一次成功扩大为普遍效果承诺。
 
-若想练习方法迁移，可自行选一个第二情境（只构想即可，不必开始新工作）。并排写下两情境要解决的问题、约束和可观察的成功证据；比较相似点与关键差异，再说明本次方法哪些可复用、哪些需调整或不适用。理由应能回指本次记录；未在新情境实际验收前，不说迁移已成功。此练习可跳过。
-
 <a id="first-project-git"></a>
 
 ## 第 6 步：按需保存 Git 检查点

.github/pi-cli-setup.md

@@ -6,11 +6,10 @@
 
 **本文目的：** 帮助初学者借助网页版 Chat AI，按需检查或安装并验证 Pi CLI，再完成 OpenAI GPT 与本机 Bash 的配置和使用验证；实际操作由用户在本机完成。
 
-- 把本文全文交给网页版 Chat AI：系统不明时首轮只问系统；已知的系统/终端信息不重复问，之后每轮只引导一个本机动作并等你回报。
-- 若不熟悉终端，先按系统指导打开本机终端（Android 使用 Termux）；在计划使用的终端运行 `pi --version`。有版本号就跳过 Pi 安装和安装网络检查。
-- 命令未找到时，仅在近期安装/更新 Pi 或修改 PATH 后重开终端重试一次；再核对既有安装。状态或渠道不明就暂停，不盲目重装。
-- 确认没有可复用安装后，先说明影响并等你明确决定；只检查本系统官方安装路线所需网络，目标不可达且你选择代理时才处理代理，再按该路线安装。
-- 安装后再用 `pi --version` 验证。版本号只证明 CLI 可用；OpenAI GPT 与本机 Bash 的配置及使用验证随后另行完成。
+- 将本文全文交给网页版 Chat AI；它只引导并核对你的回报，不操作本机。系统或终端信息已知就复用；终端未就绪时先指导打开（Android 使用 Termux）。每轮只安排一个本机动作并等你回报。
+- 在计划使用的终端检查 `pi --version`：有版本就复用并跳过安装。命令未找到时，仅在近期安装/更新或修改 PATH 后才重开终端重试一次；随后先核对既有安装，不盲目重装。
+- 确认没有可复用安装且你同意后，才按本系统官方路线检查所需网络并安装；只在必要目标确实不可达且你选择时处理代理。
+- 流程完成需要三项本机证据：`pi --version` 有版本、Pi 中所选 OpenAI GPT 有实际回答、Pi 调用本机 Bash 的只读命令有结果。缺项就只报告已证实状态。
 
 ## 给网页版 Chat AI 的任务
 

.github/test-source-archive.py

@@ -516,26 +516,43 @@ class SourceArchiveTest(unittest.TestCase):
         )
         self.assertTrue(all(item in step2 for item in required))
 
+    # 固定学习边界，不把整句或段落布局锁成兼容接口。
     def test_first_project_review_offers_optional_retrieval_before_notes(self):
         prompt = Path(__file__).with_name('how-to-complete-work.md').read_text(encoding='utf-8')
-        self.assertIn(
-            '想练习记住方法时，可选地先合上对话和笔记，用自己的话回忆本次的方法选择与证据，再对照原记录补漏；想不起的地方如实标“未知”。这只是低风险的学习练习，不是工作验收，也不是使用本指南的条件。',
-            prompt,
+        required = (
+            '以下学习练习都可跳过',
+            '它们不是工作验收',
+            '也不是使用本指南的条件',
+            '合上对话和笔记',
+            '回忆方法选择、证据和适用条件',
+            '再对照记录补漏',
+            '不确定处标“未知”',
         )
+        self.assertTrue(all(item in prompt for item in required))
+        recall_start = prompt.index('合上对话和笔记')
+        recall = prompt.index('回忆方法选择、证据和适用条件', recall_start)
+        compare = prompt.index('再对照记录补漏', recall)
+        self.assertLess(recall_start, recall)
+        self.assertLess(recall, compare)
 
     def test_first_project_review_offers_optional_spaced_retrieval(self):
         prompt = Path(__file__).with_name('how-to-complete-work.md').read_text(encoding='utf-8')
-        self.assertIn(
-            '若想再练一次，可隔一段时间后不看记录再次回忆同一方法与证据，再对照补漏；间隔由你决定，不是必做计划。',
-            prompt,
-        )
+        required = ('隔一段时间再做一次', '间隔由你决定', '不是必做计划')
+        self.assertTrue(all(item in prompt for item in required))
 
     def test_first_project_offers_optional_code_self_explanation(self):
         prompt = Path(__file__).with_name('how-to-complete-work.md').read_text(encoding='utf-8')
-        self.assertIn(
-            '若本次确有代码改动，想练习解释时，可选地挑一处非敏感的小改动，用自己的话说明它做什么、为什么符合一项原定标准；适用时，再手动追踪一个具体输入。然后对照真实差异与验收证据，记录说不清的部分。这是可跳过的学习练习，不要求运行代码，也不替代测试或验收。',
-            prompt,
+        required = (
+            '若本次改过代码',
+            '非敏感改动',
+            '对应一项原定标准',
+            '手动追踪一个输入',
+            '对照实际差异与验收证据',
+            '记下说不清处',
+            '不要求运行代码',
+            '不替代测试或验收',
         )
+        self.assertTrue(all(item in prompt for item in required))
 
     def test_god_termux_pkg_upgrade_scope_is_explicit(self):
         prompt = Path(__file__).with_name('pi-cli-setup.md').read_text(encoding='utf-8')
@@ -803,10 +820,15 @@ class SourceArchiveTest(unittest.TestCase):
 
     def test_first_project_optional_transfer_practice_compares_cases_with_evidence_boundary(self):
         prompt = Path(__file__).with_name('how-to-complete-work.md').read_text(encoding='utf-8')
-        self.assertIn(
-            '若想练习方法迁移，可自行选一个第二情境（只构想即可，不必开始新工作）。并排写下两情境要解决的问题、约束和可观察的成功证据；比较相似点与关键差异，再说明本次方法哪些可复用、哪些需调整或不适用。理由应能回指本次记录；未在新情境实际验收前，不说迁移已成功。此练习可跳过。',
-            prompt,
+        required = (
+            '以下学习练习都可跳过',
+            '自选第二情境（只构想即可）',
+            '比较问题、约束和成功证据',
+            '哪些可复用、哪些需调整或不适用',
+            '理由应能回指本次记录',
+            '未在新情境实际验收前，不说迁移已成功',
         )
+        self.assertTrue(all(item in prompt for item in required))
 
     def test_first_project_offers_conditional_regression_first_guidance(self):
         prompt = Path(__file__).with_name('how-to-complete-work.md').read_text(encoding='utf-8')