V3.1 — Grok Build 功能体系补充

V3.1 发布说明

发布状态：正式发布。公共版本以公共仓库 main、v3.1 标签和对应 GitHub Release 为准。

《终端与 AI 编程手册》V3.1 是 V3.0 发布后的专项内容更新，不进行全书结构重构。本次修改集中在 Part 10B Grok Build：原有三章已经覆盖安装、认证、权限、Sandbox、项目配置、Headless、Worktree 和扩展系统，但对实际 TUI 中数量众多的斜杠命令、会话与 Memory、后台任务、Goal、Workflow、多 Agent、终端子命令和跨客户端兼容只作了概括。V3.1 将这些能力重新整理为可查询、可排错、能说明恢复边界的完整章节组。

版本定位

V3.1 保留 V3.0 的全书结构、叙事规范和公开发布机制，只扩充变化较快且此前覆盖不足的 Grok Build 内容。它不改写其他 Part 的主线，不建立新的全书路线图，也不将一次产品专项更新包装成 V4.0。

本次新增和重写后的 Part 10B 共九章：

1. 安装、登录与基础使用；
2. 权限、Sandbox 与项目配置；
3. Headless、Worktree 与扩展系统；
4. TUI、斜杠命令与交互界面；
5. 会话、Memory 与后台任务；
6. Goal、Workflow 与多 Agent 系统；
7. 扩展系统、MCP、ACP 与跨客户端兼容；
8. 配置、模型、诊断与功能核对；
9. 终端子命令与完整功能索引。

TUI、斜杠命令与快捷键

V3.1 首先解释斜杠菜单中的三类来源：Agent 后端内置命令、Pager/TUI 内置命令，以及声明为 user-invocable 的 Skill。用户实际看到的命令数量取决于版本、功能开关、账号、项目配置、Plugin、Skill 和兼容扫描，因此不能把某张截图或某一版静态清单当作永久契约。

新增章节覆盖会话、模型、权限、分享、转录、查找、上下文压缩、队列、后台任务、定时循环、媒体生成、设置、诊断、扩展管理、账号和隐私等入口，并说明官方在线文档与开源仓库内随包用户指南可能存在短暂同步差异。本机 /help、斜杠菜单、grok --help 和 grok inspect 才是当前安装版本的最终核对入口。

TUI 快捷键不再只写“回车发送”和“Shift+Tab 切模式”。V3.1 补充快捷键面板、Command Palette、中途 Interject、Prompt Queue、Tasks、Todo、后台命令、Sessions、Extensions、Dashboard、Scrollback 逐块导航、Raw Markdown、Viewer、复制与终止后台任务，并解释 ! Shell mode、@路径 文件引用以及 VS Code 系、Apple Terminal、WezTerm 的按键差异。快捷键的效果取决于焦点、输入模式、Vim Scrollback 和终端协议，不能脱离界面状态死记。

/sessions 与 /dashboard 被解释为当前 Pager 中的活动会话与 Agent Dashboard 入口；/resume 和 Shell 层的 grok sessions list/search/delete 则负责持久化会话选择与磁盘记录管理。Fullscreen-only、Minimal-only 命令以及 --no-alt-screen 的渲染语义也已单独说明。

会话、Memory 与恢复边界

V3.1 将以下能力分开说明：

磁盘会话
当前模型上下文
Compact 总结
Transcript、Export 与 Share
跨会话 Memory
Prompt 队列
后台 Agent
定时 Loop

/resume、--resume 和 --continue 恢复的是 Grok 会话，不是 Git、文件系统、数据库、容器、远程主机或外部服务快照。/fork 和 --fork-session 不自动创建 Git 分支，/rewind 也不能撤销已经发生的外部副作用。恢复后必须重新检查机器、目录、分支、HEAD、工作区和最终配置。

Memory 部分补充 /remember、/memory、/flush、/dream、实验性启用条件、Backend、用户配置以及 grok memory clear 的不同清理范围。长期记忆不应用于保存 API Key、Cookie、验证码、私人数据或未经验证的推测。

Goal、Workflow 与多 Agent

V3.1 明确区分 Goal、Workflow、Subagent、Agent Definition、Persona 和 Dashboard。当前 Background Workflows 默认开启；开启时 /goal 使用 Host-owned Workflow Engine，关闭时会回退到旧式 update_goal 工具，因此关闭 Workflow 不只影响 /workflow 和 /deep-research。

Workflow 章节说明 Rhai 脚本作用域、定义优先级、Pause/Resume、同进程恢复、进程重启后的中断边界和非 exactly-once 风险。当前 Agent Budget 默认 128，显式范围为 1–1024；它与 Goal Token Budget、模型/API 费用和运行时间是不同资源。

多 Agent 场景继续坚持一个未提交工作区只有一个写入者。调查、验证和复核 Agent 默认只读，多个实现使用独立 Worktree；Worktree 只隔离 Git 目录和分支，不隔离认证、网络、数据库、Docker、GPU 和项目外文件。

扩展、兼容与跨客户端导入

扩展章节补充 Skill、Plugin、Marketplace、Hook、MCP、LSP、代码索引和 ACP 的来源、作用域、信任与凭据边界。Grok 可以自动发现部分 Claude Code 生态配置，但“能够读取”不表示权限规则、Hook JSON、退出码、Agent 工具或执行顺序完全相同。

V3.1 特别区分三种容易混淆的 Claude 路线：

/import-claude      导入 Claude 设置

grok import        导入 Claude Code 会话

resume-claude Skill 与兼容 Session Cell
                    staged 的扫描器路线

Codex 和 Cursor 的会话兼容单元当前同样被上游配置文档标记为 staged，并要求存在匹配的 resume-codex 或 resume-cursor Skill。看到 /resume-codex 只能证明当前环境存在一个可调用 Skill，不能据此宣称稳定的 Codex Session Scanner 已经接通。

配置、认证与诊断

配置章节不再把所有设置简化成一条永久覆盖链。普通运行时参数、用户配置、项目 MCP/Plugin、Permission Rule、企业 Managed 默认、Requirements Policy Pin 和 Version Bound 使用不同合并语义；其中 requirements.toml 中受支持的组织策略不能由用户配置、环境变量或远程设置放宽。

认证部分明确当前凭据顺序：model.api_key 高于 model.env_key 指向的环境变量，二者高于活动 Session Token，活动 Session Token 高于 XAI_API_KEY。已经登录时，XAI_API_KEY 只是回退；验证 API Project 路线应退出登录或使用隔离的 GROK_HOME。OAuth 同时保留 grok login --oauth 和欢迎页全局入口 grok --oauth；--device-code 作为 --device-auth 的别名处理。

权限部分新增 dontAsk、acceptEdits 和企业 Bypass Lock，并明确 Plan Mode 只限制普通 Edit 工具，不会自动约束 Bash 重定向、写入型 MCP 或子 Agent。新增 --plugin-dir 后，也进一步区分临时加载、安装、启用与信任。

同时新增自定义模型、工具超时与输出上限、Web Fetch 本地网络边界、通知、Pager、Privacy、Telemetry、Trace、外部 OpenTelemetry、日志和企业版本限制等诊断内容。

终端子命令索引

新增第九章集中整理官方文档公开的 Shell 入口，包括：

login、logout、inspect、models
mcp、plugin、plugin marketplace
sessions、export、import、memory clear
worktree、dashboard、agent stdio
wrap、update、version、completions、setup

同时整理工作目录、会话、Worktree、模型、权限、Sandbox、工具集合、System Prompt、Headless 输出、最大轮数、单次关闭功能和终端呈现相关 Flags。索引不包含内部开发二进制、隐藏调试命令和没有公开契约的实现细节。

事实核对方法

本次内容以 2026-07-31 的 xAI 官方在线文档和 xai-org/grok-build 上游用户指南为主要依据，并区分：

正式在线文档已公开的能力
开源仓库随包用户指南中的完整实现说明
需要功能开关或 Backend 的条件能力
Plugin、Skill 或兼容层提供的扩展能力
仅预留或 staged 的兼容单元

在线文档与仓库内文档出现短暂不一致时，正文会明确记录，不选择性删除不一致项。读者实际使用时仍应以本机 /help、grok --help、grok inspect 和真实运行结果为准。

发布与验证说明

V3.1 的私有源分支已通过 Markdown Check 与 Source Release Audit。检查范围包括严格 Markdown、内部链接、辅助脚本测试、敏感信息与 Git 历史扫描、公开导出 dry-run、公共目标仓库不变性检查、隔离公开快照和外链审计。

自动检查只能证明其覆盖的静态规则和导出流程通过，不能证明全部功能在每个账号、平台、终端和组织策略中都可用。尤其是 Memory Backend、Workflow Driver、resume-codex、第三方 Plugin/MCP 和终端快捷键，仍需读者结合自己的版本和环境核对。

V3.0 — 全书叙事结构重构

V3.0 发布说明

发布状态：正式发布。公开版本标签为 v3.0，发布目标为 anyue-git/Terminal-AI-Coding-Handbook 的 main 分支。

《终端与 AI 编程手册》V3.0 的重点不是继续堆叠章节，而是对 V2.0 中普遍存在的碎片化叙事进行全书重构。原版本已经覆盖终端、Git、SSH、Python、Docker、三套 AI CLI、配置凭证和 GPU 远程开发，但不少页面采用“一句引导—代码块—一句解释—列表—下一个标题”的卡片式节奏，导致页面看起来很长，连续理解却比较困难。V3.0 将重构单位从单个知识点改为完整意思、真实任务和可验证决策：一个自然段围绕同一问题展开，一个小节解决真正不同的问题，一章形成从场景、操作、结果判断到恢复方法的连续过程。

叙事结构重构

V3.0 建立了叙事结构审计、公式化文风审查和内容覆盖反查三套机制，再完成 README、Quickstart、快速开始、Part 01–12 与主要附录的人工重写。为了避免新增路线图、覆盖记录和发布说明影响比较，下表只统计 V2 中原有、V3 中仍存在的同一批 73 个文档；这些数字用于观察结构变化，不单独作为内容质量结论。

指标	V2.0 基线	V3.0 代表性审计	变化
普通正文字符	137786	122367	-11.2%
自然段	4526	2066	-54.4%
微型段落	2311	536	-76.8%
短段落	3355	952	-71.6%
一句段落	3304	1095	-66.9%
平均段长	30.4 字	59.2 字	+28.8 字
标题	1433	522	-63.6%
列表项	2446	276	-88.7%
代码块	2467	1048	-57.5%
正文偏薄的小节	544	20	-96.3%
空引导短句	151	15	-90.1%
短段占比	74.1%	46.1%	-28.0 个百分点

普通正文减少并不等于内容简单删减。术语表和维护清单改为表格后，表格单元格不计入普通正文；重复 Prompt、重复 Git 流程和跨章安全提醒也被合并或迁移。V3.0 同时回查 V2 主分支，从缩减较大的章节中逐项寻找被删除的独特命令、故障场景和恢复方法，确认由其他主讲章节承接，或直接补回。

入口、基础工具与开发环境

README 现在直接承担读者入口和全书内容地图，不再只把读者引向 SUMMARY.md。两个短版快速开始分别形成终端与 AI CLI 的最小闭环，完整 Quickstart 则保留可脱离真实项目运行的独立练习。Terminal、Shell、zsh、路径、文件生命周期、进程生命周期、Git、SSH、Homebrew、Python 和 Docker 的职责边界重新划分，命令不再被拆成大量只承载一两句话的小节。

覆盖反查补回了多项容易在压缩结构时丢失的细节，包括 git diff --check、忽略规则验证、Homebrew 前缀与服务诊断、Python 环境标记与私有索引、Docker 构建上下文与 .dockerignore、Compose 合并顺序、GPU 镜像与 UID/GID 边界，以及 Mac 通过命名 SSH Context 操作 Ubuntu Docker daemon 时的远程路径规则。

Claude Code、Codex CLI、Grok Build 与多供应商配置

三套客户端各自主讲产品特有的安装、认证、权限、会话、自动化和扩展能力；共同的模型、Provider、Base URL、配置、凭证、Profile、状态目录、独立实例和本地网关集中到 Part 10C。Codex 的 TOML、Profile 与凭证，Claude Code 的设置作用域与网关，CC Switch、ccswitch、Cockpit Tools 和第三方 Provider 的职责边界都得到强化，避免把“配置投影”“凭证替换”和“本地路由”混为一谈。

V3.0 也保留了 Claude Code MCP 的项目 Scope、凭据边界、提示注入和双数据链，Grok Headless 的工具白名单、Allow/Deny、JSONL 前向兼容，以及 Codex 非交互执行、审批、退出状态、超时、CI 凭据和 Git 写操作边界。第三方项目声明的能力不会被写成上游平台已经授权或官方保证的能力。

Mac、Ubuntu 与 GPU 远程开发

Part 11 按局域网链路、源码同步、tmux、NVIDIA/PyTorch、跨平台环境、Tailscale、VS Code/AI CLI 协作和实验恢复重新组织。Mac 负责主要编辑、Git 与复核，Ubuntu 负责 Linux、CUDA 与训练；源码、环境、数据、模型和运行产物分目录管理，日志、退出状态、代码快照、最终配置、指标、checkpoint 和恢复演练组成完整证据链。

实验记录部分明确区分 git diff、git diff --cached 与 git diff HEAD 的覆盖范围，并单独记录未跟踪文件，避免把一个不完整的补丁文件误认为足以复现实验。

AI 开发工作流

Part 12 将 Prompt、安全边界、复杂任务、多 Agent 和端到端案例组织为一条可检查的闭环：

定义完成标准
→ 建立现实基线
→ 只读调查
→ 选择方案
→ 小批实施
→ 证据验证
→ 独立复核与人工提交

同一工作区同时只保留一个实施者；其他 Agent 使用只读职责或独立 Worktree。每个批次需要记录命令、运行环境、退出状态、通过/失败/跳过、关键警告、覆盖行为和未覆盖内容，最终验收还会检查凭据、大型生成物和范围外修改。

自动审计与发布机制

V3.0 新增并接入以下自动检查：

• scripts/audit_prose_structure.py：统计微型段、短段、连续短段、薄小节和空引导；
• scripts/audit_formulaic_style.py：定位跨章重复长句、固定段首、公式化转折和超长段落候选；
• scripts/audit_sensitive_patterns.py：扫描当前树、提交说明和 Git 历史中的高置信度凭据特征；
• scripts/audit_external_links.py：忽略代码块和占位域名，检查公开快照外链；
• scripts/test_audit_tools.py：回归审计规则，并扫描 Shell printf 格式参数转义；
• Source Release Audit：构建隔离公开快照，执行 Markdown、敏感信息、外链和真实导出预演检查。

公开仓库新增基于发布清单的 GitHub Release 工作流。发布清单改变后，工作流会在公开仓库创建或更新对应标签与 Release；在私有源仓库中同一工作流会自动跳过，从而继续保持“私有源仓库是唯一开发源头，公开仓库是发布副本”的结构。

兼容性与验证边界

自动检查只能证明其覆盖的规则、静态审计和公开快照流程通过，不能证明所有命令已经在每一种真实 Mac、Ubuntu、NVIDIA GPU、账号和网络环境中执行，也不能保证外部平台、CLI 参数和第三方服务未来不会变化。涉及快速变化的工具时，应同时查看正文中的版本说明和官方资料。

许可证

本项目采用双许可证：正文、解释、表格、练习和其他非代码教学内容使用 CC BY-NC-SA 4.0；脚本、GitHub Actions、Shell 命令、配置示例和围栏代码使用 MIT License。第三方商标、引用、截图和链接材料仍受各自权利人条款约束。

Terminal & AI Coding Handbook V2.0

V2.0 发布说明

发布日期：2026-07-30

《终端与 AI 编程手册》V2.0 是一次面向终端新手的系统性重写。V1.0 以知识卡片和命令速查为主，V2.0 则把核心知识放入连续场景，补充执行位置、代表性输出、成功判断、故障层级、权限边界与恢复方法。

主要变化

更完整的新手路径

新增“终端十五分钟上手”“AI CLI 快速上手”和完整 Quickstart。读者可以在独立练习目录中完成导航、文件操作、Git 检查和一个受控的 AI Agent 任务，而不是先背完全部命令。

终端与开发基础重写

重新组织 Terminal、Shell、zsh、路径、文件操作、搜索、日志、管道、进程、Git、SSH、Homebrew、Python 和 Docker。重要命令尽量说明在哪台机器和哪个目录执行、可能看到什么输出、怎样确认成功，以及出错后先检查哪一层。

AI 编程客户端体系

系统覆盖 Claude Code、Codex CLI 和 Grok Build，包括安装认证、权限、Sandbox、审批、会话、非交互运行、Worktree、Hooks、MCP、Plugins、Skills 与多 Agent 协作。

配置、凭证与多实例

新增 Part 10C，区分客户端、模型、Provider、Profile、账号、凭证、状态目录和独立实例，并讲解 Codex config.toml、auth.json、Claude Code Settings、Gateway、CC Switch、ccswitch 与 Cockpit Tools 的配置链和恢复方式。

Mac 与 Ubuntu GPU 协作

Part 11 以 Mac 日常开发、Ubuntu 24.04 NVIDIA 游戏本承担训练为默认场景，覆盖局域网 OpenSSH、rsync、Tailscale、tmux、NVIDIA 驱动、CUDA、PyTorch、VS Code Remote SSH、AI CLI、日志和 checkpoint。

通用 AI 开发闭环

Part 12 统一采用：

定义完成标准
→ 建立现实基线
→ 只读调查
→ 选择方案
→ 小批实施
→ 证据验证
→ 独立复核与人工提交

并补充复杂任务拆分、权限分层、证据账本、多 Agent Worktree 协作和 Mac 到 Ubuntu GPU 的端到端案例。

安全与兼容性修正

• 不提供真实 Token、Cookie、Refresh Token、私钥或登录缓存；
• 不把递归删除、Git 历史重写、Volume 删除或高权限容器作为普通模板；
• SSH 不关闭主机身份验证，也不建议直接暴露公网 TCP 22；
• Docker 不默认挂载 Socket、整个 HOME 或使用 --privileged；
• AI CLI 不默认跳过审批或获得最大权限；
• 已匿名化正文中的个人用户名、主目录和 SSH 用户示例；
• 已移除依赖 GNU find -maxdepth 的 Mac 示例；
• 实验补丁使用 git diff --binary HEAD，未跟踪文件单独记录。

验证

V2.0 私有源仓库最终重写 PR 为 #2，经过全量补丁审查和 Markdown Check #176，结果为成功。自动检查覆盖 UTF-8、标题、围栏代码块、内部链接、目录引用和异常短文件。

自动检查不能证明所有外部链接永久有效，也不能替代每台 Mac、Ubuntu、Docker、GPU 或 AI CLI 环境中的真实执行。快速变化的软件行为仍以当前官方文档和本机帮助为准。

升级方式

V2.0 将作为正常升级提交进入原有公共仓库，保留 V1.0 历史，不强制重写公开分支。公开仓库将使用 V2.0 标签和 GitHub Release 标记本次版本。

许可证说明

截至本次发布准备，作者尚未明确选择开源许可证，因此不会自动加入许可证文件。公开可见不等于自动授予复制、修改和再分发权限；后续如选择许可证，将单独记录。