docs(C30): Doctor 屏与 Output Style 体验 全新章 (YAO-129)

[luyao618]

概要

新增第 33 篇 Doctor 屏与 Output Style 体验 —— spec §9.3 与 YAO-142 仲裁约定的 C30 落地文件 docs/33-Doctor-屏与-Output-Style-体验.md。100% 新增章节，源码 frozen @ 290fdc9481a70612bc5823aa4ed225c52c52aad3。

覆盖入口锚点：

• screens/Doctor.tsx、screens/REPL.tsx（作为背景）、screens/ResumeConversation.tsx
• outputStyles/loadOutputStylesDir.ts、constants/outputStyles.ts
• commands/doctor/{index,doctor}.tsx、commands/output-style/{index,output-style}.tsx
• utils/doctorDiagnostic.ts、utils/doctorContextWarnings.ts、utils/prompts.ts

风格双亲实证段（spec §0.5.1.1）

选取双亲：docs/03-状态管理.md + docs/21-Ink框架深度定制.md。两者都属于"拆某个子系统内部机制"的章型，且都用"为什么 X 值得一篇"作 hook，再走"全景 → 细节 → 综合"三段式。

双亲节选 1 ：docs/03-状态管理.md L5-17（≥200 字）

为什么状态管理值得单独一篇？

Claude Code 面临一个独特的状态管理难题：它既是一个 React 应用，又不完全是。

终端 UI 用 Ink（React for CLI）渲染，组件需要响应式的状态更新。但核心业务逻辑 —— API 调用、工具执行、Agent 编排 —— 运行在 React 树之外。一次工具调用的结果需要同时：更新 React 组件（显示在终端 UI 上）、被非 React 的 query.ts 对话循环读取、被 Agent 子系统使用（可能运行在隔离的上下文中）。

如果用 Redux/Zustand 这类库？太重了。React 内置的 useState/useReducer？无法从 React 树外部访问。模块级全局变量？无法触发 React 重渲染。Claude Code 的答案是：三层状态架构 + 一个 35 行的自研 Store。

双亲节选 2 ：docs/21-Ink框架深度定制.md L5-17（≥200 字）

为什么要 Fork Ink？

Ink 是一个开源框架，让你在终端中使用 React 组件编写 UI。官方 Ink 适合简单的 CLI 工具 —— 但 Claude Code 不是简单的 CLI。它需要：全屏模式 —— Alt Screen 下的完整 UI，不是"追加式"输出；虚拟滚动 —— 对话历史可能有上千行，不能全部渲染；鼠标交互 —— 点击、拖拽选择文本、滚轮滚动；60fps 渲染 —— 流式输出时每 16ms 刷新一帧，不能闪烁；IME 支持 —— CJK 输入法需要物理光标精确定位。官方 Ink 不支持这些。Claude Code 团队 fork 了 Ink 并进行了大量深度定制，最终形成了一个功能完备的终端 React 渲染引擎。

新章对应节选 1 ：本章 L7-9（≥200 字）

screens/ 目录下只放了三个文件 —— REPL.tsx（主回合）、ResumeConversation.tsx（会话恢复）、Doctor.tsx（自检屏），它们是整本书绝大多数时间里你看不见的那一层：REPL 是常驻入口、ResumeConversation 是 --resume 时一闪而过的会话选择器、Doctor 则只在你敲 /doctor 那一刻被点亮。一本讲源码的书在前面三十多章已经把 REPL 拆得很彻底，本章想把镜头对准另外两个：一个是给用户的自检仪表盘，一个是给用户的换装系统。

它们看上去毫无关系。一个写在 screens/Doctor.tsx 里、574 行的诊断面板；另一个写在 outputStyles/loadOutputStylesDir.ts + constants/outputStyles.ts 里、几百行的 prompt 注入链路。但拉远看会发现它们共用一种很少被单独强调的设计思路 —— 把 CLI 的"软参数"暴露成可被用户直接看见或直接替换的东西。

新章对应节选 2 ：本章 L40-46（≥200 字）

screens/Doctor.tsx 主组件首屏渲染时挂载的 useEffect（Doctor.tsx:164-220）做了四件事，分别绑在四个 setState 上：打一次 getDoctorDiagnostic()，结果塞进 diagnostic —— 装的是"我是 npm 全局还是 native？版本号是多少？有没有多版本冲突？"这类安装层事实；算出一份 agentInfo，结合 ~/.claude/agents/ 与项目级 .claude/agents/ 的 dir 存在性，外加 agentDefinitions 里的 active/all/failedFiles 三元组；跑一遍 checkContextWarnings()，把"CLAUDE.md 是不是太大、agent 描述总 token 是不是超阈值、MCP 工具是不是超阈值、是否有 permission rule 被遮蔽（unreachable）"四类警告一次性算出来；如果启用了 pid-based locking，跑一次 cleanupStaleLocks 并读出当前 LockInfo[] —— 这是 native installer 的并发版本锁，Doctor 顺便替你扫尸。

风格匹配点：第二人称读者引导、"为什么 X 值得一篇"开篇钩子、file:line 锚点贴满、段落结尾习惯用一句结论收束、"全景 → 细节 → 综合"三段式。

Manifest diff

仅新增 1 个章节文件，无 spec / 附录改动：

docs/33-Doctor-屏与-Output-Style-体验.md  (new, 328 lines)

NN=33 由 YAO-142 PR #55 在 spec §9.3.1 + scripts/check-code-ratio.ts NEW_CHAPTER_FILES 中注册，本 PR 不再改 spec。

覆盖锚点确认（新章必须项）

锚点	章节位置
screens/Doctor.tsx	§1.1 - §1.5 全程
screens/REPL.tsx	§0 hook 段（背景）、§3.1 对比段
screens/ResumeConversation.tsx	§三 全节
outputStyles/loadOutputStylesDir.ts	§2.3
commands/output-style/*	§2.1 + §2.5
commands/doctor/*	§1.1

CI gates 本地通过情况

• check-source-commits.ts —— OK
• check-no-frontmatter-in-chapters.ts —— OK（无 frontmatter）
• check-code-ratio.ts —— OK，18.1%（阈值 ≤ 25%）
• lint-no-spec-jargon-in-prose.ts —— OK
• lint-no-revision-codenames.ts —— OK
• lint-no-fuzzy-quantifiers.ts —— WARN 5 处全部为"约"字误命中复合词（契约 / 规约 / 约束 / 约定），非阻塞，reviewer 复核

备注

• 不合并：本章按 YAO-129 §4 约定由 yao 手动合并