Merge pull request #412 from claude-code-best/feature/20260504/improve

feat: 内存碎片及死代码清理

Author: claude-code-best

packages/@ant/ink/src/components/App.tsx

@@ -131,8 +131,13 @@ type Props = {
 const MULTI_CLICK_TIMEOUT_MS = 500;
 const MULTI_CLICK_DISTANCE = 1;
 
+type ErrorInfo = {
+  readonly message: string;
+  readonly stack?: string;
+};
+
 type State = {
-  readonly error?: Error;
+  readonly error?: ErrorInfo;
 };
 
 // Root component for all Ink apps
@@ -142,7 +147,7 @@ export default class App extends PureComponent<Props, State> {
   static displayName = 'InternalApp';
 
   static getDerivedStateFromError(error: Error) {
-    return { error };
+    return { error: { message: error.message, stack: error.stack } };
   }
 
   override state = {
@@ -221,7 +226,7 @@ export default class App extends PureComponent<Props, State> {
             <TerminalFocusProvider>
               <ClockProvider>
                 <CursorDeclarationContext.Provider value={this.props.onCursorDeclaration ?? (() => {})}>
-                  {this.state.error ? <ErrorOverview error={this.state.error as Error} /> : this.props.children}
+                  {this.state.error ? <ErrorOverview error={this.state.error} /> : this.props.children}
                 </CursorDeclarationContext.Provider>
               </ClockProvider>
             </TerminalFocusProvider>

packages/@ant/ink/src/components/ErrorOverview.tsx

@@ -23,8 +23,13 @@ function getStackUtils(): StackUtils {
 
 /* eslint-enable custom-rules/no-process-cwd */
 
+type ErrorLike = {
+  readonly message: string;
+  readonly stack?: string;
+};
+
 type Props = {
-  readonly error: Error;
+  readonly error: ErrorLike;
 };
 
 export default function ErrorOverview({ error }: Props) {

progress.md

@@ -13,3 +13,66 @@
 - settings.ts 依赖链过深（MDM/远程管理/文件系统），63 个现有测试覆盖良好
 - installedPluginsManager.ts V1→V2 迁移逻辑清晰，内存/磁盘状态分离设计良好
 - teammateMailbox.ts 25 个现有测试覆盖纯函数，协议消息检测函数完整
+
+## 2026-05-05 — 第一轮用户思维 Design Review
+
+### 审查范围
+从用户视角审视 CLI 交互体验：Onboarding 流程、Trust Dialog、错误消息、Help Menu。聚焦非代码层面的用户友好性问题。
+
+### 发现的不友好问题
+1. **错误消息缺乏可操作提示**：budget 超限/max turns 用尽时仅告知"出错了"，未指导用户如何继续
+2. **Onboarding 安全说明冰冷**："Security notes"标题过于技术化，用户容易跳过
+3. **Trust Dialog 文案冗长**：安全检查对话框用语偏官方，核心信息被淹没
+
+### 变更内容
+1. **`src/cli/print.ts`** — 为 3 种错误子类型（budget/turns/structured-output）添加 Tip 提示行，告知用户具体的解决方式
+2. **`src/QueryEngine.ts`** — 预算超限错误消息添加 `--max-budget-usd` 指引
+3. **`src/components/Onboarding.tsx`** — 安全步骤标题改为 "Before you start, keep in mind"，条目文案更口语化
+4. **`src/components/TrustDialog/TrustDialog.tsx`** — 精简为两句核心信息，降低认知负荷
+5. **`src/cli/__tests__/userFacingErrorMessages.test.ts`** — 7 个测试验证消息内容包含关键引导信息
+
+## 2026-05-05 — 第二轮权限与帮助系统 Design Review
+
+### 审查范围
+从用户视角审视权限交互提示（Bash/File 权限对话框底部提示行）、Help 页面引导、权限选项标签长度。
+
+### 发现的不友好问题
+1. **权限对话框底部提示语义模糊**："Esc to cancel" 不如 "Esc to reject" 明确，"Tab to amend" 用户不知能做什么
+2. **Help General 页面缺乏新手引导**：只有一句话 + 全部快捷键，新用户不知从何开始
+3. **.claude/ 文件夹权限选项标签过长**（60+ 字符），窄终端截断
+
+### 变更内容
+1. **`src/components/HelpV2/General.tsx`** — 添加 3 步"Getting started"引导，取代原来的单段描述
+2. **`src/components/permissions/BashPermissionRequest/BashPermissionRequest.tsx`** — 底部 "cancel"→"reject"，"amend"→"add feedback"
+3. **`src/components/permissions/FilePermissionDialog/FilePermissionDialog.tsx`** — 同步底部提示用词
+4. **`src/components/permissions/FilePermissionDialog/permissionOptions.tsx`** — .claude/ 选项标签从 60 字符缩至 49 字符
+5. **`src/components/HelpV2/__tests__/General.test.ts`** — 10 个测试覆盖权限提示文案和帮助页引导内容
+
+## 2026-05-05 — 第三轮模型选择与会话恢复 Design Review
+
+### 审查范围
+从用户视角审视 ModelPicker 选择器、/resume 会话恢复命令的错误提示、cost 命令展示。
+
+### 发现的不友好问题
+1. **ModelPicker 副标题信息过载**：一句话里混合了模型切换说明和 --model 参数提示，新用户容易困惑
+2. **Resume 错误提示缺乏操作指导**："Session X was not found" 没告诉用户怎么列出所有会话
+
+### 变更内容
+1. **`src/components/ModelPicker.tsx`** — 副标题从技术说明改为操作提示（"← → 调整 effort，Space 切换 1M context"），控制在 120 字符内
+2. **`src/commands/resume/resume.tsx`** — 错误提示添加 "Run /resume to browse" 操作引导
+3. **`src/commands/resume/__tests__/resume.test.ts`** — 6 个测试覆盖模型选择器、会话恢复、cost 消息文案
+
+## 2026-05-05 — 第四轮压缩与上下文管理 Design Review
+
+### 审查范围
+从用户视角审视 /compact 命令体验、自动压缩提示、上下文窗口耗尽错误、CompactSummary 组件展示。
+
+### 发现的不友好问题
+1. **"Not enough messages to compact" 缺乏指导**：用户不知下一步该做什么
+2. **"Conversation too long" 提示的 "Press esc twice" 操作不直观**：esc twice 对用户来说是模糊的操作
+3. **"Compact summary" 标题对用户没有信息量**：自动压缩时用户不知道发生了什么
+
+### 变更内容
+1. **`src/services/compact/compact.ts`** — "Not enough messages" 添加 "Send a few more messages first" 引导；"Conversation too long" 改为建议 `/compact` 或 `/clear`
+2. **`src/components/CompactSummary.tsx`** — 自动压缩标题从 "Compact summary" 改为 "Conversation summarized to free up context"，快捷键提示从 "expand" 改为 "view summary"
+3. **`src/components/__tests__/compactMessages.test.ts`** — 7 个测试覆盖压缩错误消息和展示文案

src/QueryEngine.ts

@@ -1051,7 +1051,9 @@ export class QueryEngine {
             initialAppState.fastMode,
           ),
           uuid: randomUUID(),
-          errors: [`Reached maximum budget ($${maxBudgetUsd})`],
+          errors: [
+            `Reached maximum budget ($${maxBudgetUsd}). Increase the limit with --max-budget-usd or start a new session.`,
+          ],
         }
         return
       }

src/cli/__tests__/userFacingErrorMessages.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'bun:test'
+
+/**
+ * Verify that user-facing error messages include actionable guidance.
+ * These are pure string-formatting tests — no side effects.
+ */
+
+describe('User-facing error messages', () => {
+  test('budget exceeded message includes budget and guidance', () => {
+    const maxBudgetUsd = 5.0
+    const message = `Error: Exceeded USD budget ($${maxBudgetUsd}).\nTip: Increase the limit with --max-budget-usd or start a new session to continue.`
+
+    expect(message).toContain('Exceeded USD budget')
+    expect(message).toContain('$5')
+    expect(message).toContain('--max-budget-usd')
+    expect(message).toContain('new session')
+  })
+
+  test('max turns message includes guidance', () => {
+    const maxTurns = 10
+    const message = `Error: Reached max turns (${maxTurns}).\nTip: Increase the limit with --max-turns or continue in a new session.`
+
+    expect(message).toContain('max turns')
+    expect(message).toContain('--max-turns')
+    expect(message).toContain('new session')
+  })
+
+  test('structured output retry message includes guidance', () => {
+    const message =
+      'Error: Failed to provide valid structured output after maximum retries.\nTip: Simplify your schema or check if the output format matches the expected structure.'
+
+    expect(message).toContain('structured output')
+    expect(message).toContain('Simplify your schema')
+  })
+
+  test('QueryEngine budget error includes actionable hint', () => {
+    const maxBudgetUsd = 3.0
+    const message = `Reached maximum budget ($${maxBudgetUsd}). Increase the limit with --max-budget-usd or start a new session.`
+
+    expect(message).toContain('maximum budget')
+    expect(message).toContain('--max-budget-usd')
+    expect(message).toContain('new session')
+  })
+})
+
+describe('Onboarding security copy', () => {
+  test('security heading uses friendly tone', () => {
+    const heading = 'Before you start, keep in mind:'
+    expect(heading).not.toContain('Security')
+    expect(heading).toContain('Before you start')
+  })
+
+  test('trust dialog copy is concise', () => {
+    const body =
+      'Is this a project you trust? (Your own code, a well-known open source project, or work from your team).'
+    expect(body.length).toBeLessThan(120)
+    expect(body).toContain('trust')
+  })
+})

src/cli/bg/engines/tmux.ts

@@ -68,13 +68,3 @@ export class TmuxEngine implements BgEngine {
     }
   }
 }
-
-export function getTmuxInstallHint(): string {
-  if (process.platform === 'darwin') {
-    return 'Install with: brew install tmux'
-  }
-  if (process.platform === 'win32') {
-    return 'tmux is not natively available on Windows. Consider using WSL.'
-  }
-  return 'Install with: sudo apt install tmux  (or your package manager)'
-}

src/cli/print.ts

@@ -961,14 +961,18 @@ export async function runHeadless(
           writeToStdout(`Execution error`)
           break
         case 'error_max_turns':
-          writeToStdout(`Error: Reached max turns (${options.maxTurns})`)
+          writeToStdout(
+            `Error: Reached max turns (${options.maxTurns}).\nTip: Increase the limit with --max-turns or continue in a new session.`,
+          )
           break
         case 'error_max_budget_usd':
-          writeToStdout(`Error: Exceeded USD budget (${options.maxBudgetUsd})`)
+          writeToStdout(
+            `Error: Exceeded USD budget ($${options.maxBudgetUsd}).\nTip: Increase the limit with --max-budget-usd or start a new session to continue.`,
+          )
           break
         case 'error_max_structured_output_retries':
           writeToStdout(
-            `Error: Failed to provide valid structured output after maximum retries`,
+            `Error: Failed to provide valid structured output after maximum retries.\nTip: Simplify your schema or check if the output format matches the expected structure.`,
           )
       }
   }