claude-code-best · xiaoFjun-eng · May 14, 2026
diff --git a/packages/@ant/ink/src/core/cursor.ts b/packages/@ant/ink/src/core/cursor.ts
@@ -1,2 +1,6 @@
-// Auto-generated stub — replace with real implementation
-export type Cursor = any
+/** 渲染帧中虚拟终端光标的状态（列/行坐标与是否绘制），供 diff 与光标 preamble 使用。 */
+export type Cursor = {
+  x: number // 光标所在列，从 0 开始计
+  y: number // 光标所在行，从 0 开始计
+  visible: boolean // 本帧是否应在终端绘制光标（隐藏时不发射光标移动序列）
+}
diff --git a/packages/@ant/ink/src/core/events/paste-event.ts b/packages/@ant/ink/src/core/events/paste-event.ts
@@ -1,2 +1,4 @@
-// Auto-generated stub — replace with real implementation
-export type PasteEvent = any
+/** Box 等组件上 `onPaste` / `onPasteCapture` 收到的粘贴事件形状（与括号粘贴解析结果对齐的占位约定）。 */
+export type PasteEvent = {
+  pastedText: string // 终端括号粘贴模式下解析出的 UTF-8 文本；允许为空字符串以表示空粘贴
+}
diff --git a/packages/@ant/ink/src/core/events/resize-event.ts b/packages/@ant/ink/src/core/events/resize-event.ts
@@ -1,2 +1,5 @@
-// Auto-generated stub — replace with real implementation
-export type ResizeEvent = any
+/** 终端尺寸变化时 `onResize` 回调收到的事件载荷（与 `stdout.columns` / `stdout.rows` 一致）。 */
+export type ResizeEvent = {
+  columns: number // 当前终端列数（宽度）
+  rows: number // 当前终端行数（高度）
+}
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/BashTool/toolName.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/BashTool/toolName.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type BASH_TOOL_NAME = any
+/** Bash 工具在 API 与 Agent 提示串中的注册名称字面量（与 `@claude-code-best/builtin-tools` 中 `BASH_TOOL_NAME` 常量一致）。 */
+export type BASH_TOOL_NAME = 'Bash'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/ExitPlanModeTool/constants.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/ExitPlanModeTool/constants.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type EXIT_PLAN_MODE_TOOL_NAME = any
+/** ExitPlanMode 工具在 API 中的注册名称字面量（与内置 ExitPlanMode 工具 `name` 一致）。 */
+export type EXIT_PLAN_MODE_TOOL_NAME = 'ExitPlanMode'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileEditTool/constants.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileEditTool/constants.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_EDIT_TOOL_NAME = any
+/** Edit（文件编辑）工具在 API 中的注册名称字面量（与 `FILE_EDIT_TOOL_NAME` 常量 `'Edit'` 一致）。 */
+export type FILE_EDIT_TOOL_NAME = 'Edit'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileReadTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileReadTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_READ_TOOL_NAME = any
+/** Read（文件读取）工具在 API 中的注册名称字面量（与 `FILE_READ_TOOL_NAME` 常量 `'Read'` 一致）。 */
+export type FILE_READ_TOOL_NAME = 'Read'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileWriteTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileWriteTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_WRITE_TOOL_NAME = any
+/** Write（文件写入）工具在 API 中的注册名称字面量（与 `FILE_WRITE_TOOL_NAME` 常量 `'Write'` 一致）。 */
+export type FILE_WRITE_TOOL_NAME = 'Write'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GlobTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GlobTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type GLOB_TOOL_NAME = any
+/** Glob（文件名模式匹配）工具在 API 中的注册名称字面量（与 `GLOB_TOOL_NAME` 常量 `'Glob'` 一致）。 */
+export type GLOB_TOOL_NAME = 'Glob'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GrepTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GrepTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type GREP_TOOL_NAME = any
+/** Grep（内容搜索）工具在 API 中的注册名称字面量（与 `GREP_TOOL_NAME` 常量 `'Grep'` 一致）。 */
+export type GREP_TOOL_NAME = 'Grep'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/NotebookEditTool/constants.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/NotebookEditTool/constants.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type NOTEBOOK_EDIT_TOOL_NAME = any
+/** NotebookEdit（笔记本单元格编辑）工具在 API 中的注册名称字面量（与 `NOTEBOOK_EDIT_TOOL_NAME` 常量一致）。 */
+export type NOTEBOOK_EDIT_TOOL_NAME = 'NotebookEdit'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/SendMessageTool/constants.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/SendMessageTool/constants.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type SEND_MESSAGE_TOOL_NAME = any
+/** SendMessage（向用户/通道发消息）工具在 API 中的注册名称字面量（与 `SEND_MESSAGE_TOOL_NAME` 常量一致）。 */
+export type SEND_MESSAGE_TOOL_NAME = 'SendMessage'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebFetchTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebFetchTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type WEB_FETCH_TOOL_NAME = any
+/** WebFetch（拉取并处理 URL 内容）工具在 API 中的注册名称字面量（与 `WEB_FETCH_TOOL_NAME` 常量一致）。 */
+export type WEB_FETCH_TOOL_NAME = 'WebFetch'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebSearchTool/prompt.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebSearchTool/prompt.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type WEB_SEARCH_TOOL_NAME = any
+/** WebSearch（联网搜索）工具在 API 中的注册名称字面量（与 `WEB_SEARCH_TOOL_NAME` 常量一致）。 */
+export type WEB_SEARCH_TOOL_NAME = 'WebSearch'
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/auth.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/auth.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type isUsing3PServices = any
+/** 是否正在使用第三方（非 Anthropic 直连）API 或服务；与仓库根 `src/utils/auth.ts` 中 `isUsing3PServices` 签名一致。 */
+export type isUsing3PServices = () => boolean // 返回 true 表示当前配置走兼容层或第三方模型端点
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/embeddedTools.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/embeddedTools.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type hasEmbeddedSearchTools = any
+/** 当前构建是否将 Glob/Grep 嵌入其它工具而不单独注册；与仓库根 `src/utils/embeddedTools.ts` 中 `hasEmbeddedSearchTools` 一致。 */
+export type hasEmbeddedSearchTools = () => boolean // 返回 true 时工具列表不包含独立的 Glob/Grep 工具名
diff --git a/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/settings/settings.ts b/packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/settings/settings.ts
@@ -1,2 +1,4 @@
-// Auto-generated type stub — replace with real implementation
-export type getSettings_DEPRECATED = any
+import type { SettingsJson } from 'src/utils/settings/types.js'
+
+/** 返回各设置来源合并后的快照（已废弃函数名，行为同 `getInitialSettings`）；与 `src/utils/settings/settings.ts` 一致。 */
+export type getSettings_DEPRECATED = () => SettingsJson // 无参数；至少得到可空字段填充后的合并设置对象
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/Tool.ts b/packages/builtin-tools/src/tools/AgentTool/src/Tool.ts
@@ -1,4 +1,8 @@
-// Auto-generated type stub — replace with real implementation
-export type buildTool = any
-export type ToolDef = any
-export type toolMatchesName = any
+/** 根据工具定义装配宿主侧可调用 `Tool` 实例的工厂函数类型。 */
+export type buildTool = typeof import('src/Tool.js').buildTool
+
+/** 工具定义泛型（输入 Schema、权限、进度等）；与宿主 `ToolDef` 一致。 */
+export type ToolDef = import('src/Tool.js').ToolDef
+
+/** 判断工具主名称或别名是否与查询名称相等；与宿主 `toolMatchesName` 一致。 */
+export type toolMatchesName = typeof import('src/Tool.js').toolMatchesName
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/components/ConfigurableShortcutHint.ts b/packages/builtin-tools/src/tools/AgentTool/src/components/ConfigurableShortcutHint.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type ConfigurableShortcutHint = any
+/** 可配置快捷键提示组件（从 keybindings 解析展示文案）；与宿主 `ConfigurableShortcutHint` 组件类型一致。 */
+export type ConfigurableShortcutHint =
+  typeof import('src/components/ConfigurableShortcutHint.js').ConfigurableShortcutHint
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/components/CtrlOToExpand.ts b/packages/builtin-tools/src/tools/AgentTool/src/components/CtrlOToExpand.ts
@@ -1,3 +1,7 @@
-// Auto-generated type stub — replace with real implementation
-export type CtrlOToExpand = any
-export type SubAgentProvider = any
+/** 「Ctrl+O 展开」提示组件；与宿主 `src/components/CtrlOToExpand.tsx` 中 `CtrlOToExpand` 一致。 */
+export type CtrlOToExpand =
+  typeof import('src/components/CtrlOToExpand.js').CtrlOToExpand
+
+/** 标记子 Agent 输出上下文，用于抑制重复的展开提示；与宿主 `SubAgentProvider` 一致。 */
+export type SubAgentProvider =
+  typeof import('src/components/CtrlOToExpand.js').SubAgentProvider
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/components/design-system/Byline.ts b/packages/builtin-tools/src/tools/AgentTool/src/components/design-system/Byline.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type Byline = any
+/** Ink 底部快捷键说明行容器组件；与 `@anthropic/ink` 导出的 `Byline` 一致。 */
+export type Byline = typeof import('@anthropic/ink').Byline
diff --git a/...es/builtin-tools/src/tools/AgentTool/src/components/design-system/KeyboardShortcutHint.ts b/...es/builtin-tools/src/tools/AgentTool/src/components/design-system/KeyboardShortcutHint.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type KeyboardShortcutHint = any
+/** Ink 快捷键「按键 + 动作」展示组件；与 `@anthropic/ink` 导出的 `KeyboardShortcutHint` 一致。 */
+export type KeyboardShortcutHint =
+  typeof import('@anthropic/ink').KeyboardShortcutHint
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/types/message.ts b/packages/builtin-tools/src/tools/AgentTool/src/types/message.ts
@@ -1,3 +1,6 @@
-// Auto-generated type stub — replace with real implementation
-export type Message = any
-export type NormalizedUserMessage = any
+/** 对话消息联合类型（含用户/助手/系统等）；与宿主 `src/types/message.js` 重导出一致。 */
+export type Message = import('src/types/message.js').Message
+
+/** 归一化后的用户消息形状；与宿主 `src/types/message.js` 中 `NormalizedUserMessage` 一致。 */
+export type NormalizedUserMessage =
+  import('src/types/message.js').NormalizedUserMessage
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/utils/debug.ts b/packages/builtin-tools/src/tools/AgentTool/src/utils/debug.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type logForDebugging = any
+/** 写入调试日志文件（受日志级别与过滤规则约束）；与宿主 `src/utils/debug.js` 中 `logForDebugging` 一致。 */
+export type logForDebugging =
+  typeof import('src/utils/debug.js').logForDebugging
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/utils/promptCategory.ts b/packages/builtin-tools/src/tools/AgentTool/src/utils/promptCategory.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getQuerySourceForAgent = any
+/** 按内置/自定义 Agent 类型解析用于遥测或分类的 `QuerySource`；与宿主 `getQuerySourceForAgent` 一致。 */
+export type getQuerySourceForAgent =
+  typeof import('src/utils/promptCategory.js').getQuerySourceForAgent
diff --git a/packages/builtin-tools/src/tools/AgentTool/src/utils/settings/constants.ts b/packages/builtin-tools/src/tools/AgentTool/src/utils/settings/constants.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type SettingSource = any
+/** 设置文件来源层级标识（用户/项目/本地等）；与宿主 `src/utils/settings/constants.js` 中 `SettingSource` 一致。 */
+export type SettingSource =
+  import('src/utils/settings/constants.js').SettingSource
diff --git a/packages/builtin-tools/src/tools/AskUserQuestionTool/src/bootstrap/state.ts b/packages/builtin-tools/src/tools/AskUserQuestionTool/src/bootstrap/state.ts
@@ -1,3 +1,7 @@
-// Auto-generated type stub — replace with real implementation
-export type getAllowedChannels = any
-export type getQuestionPreviewFormat = any
+/** 返回当前允许展示的通道列表（含名称、连接状态等）；与宿主 `src/bootstrap/state.js` 中 `getAllowedChannels` 一致。 */
+export type getAllowedChannels =
+  typeof import('src/bootstrap/state.js').getAllowedChannels
+
+/** 返回问题预览渲染格式（Markdown/HTML）或未配置；与宿主 `getQuestionPreviewFormat` 一致。 */
+export type getQuestionPreviewFormat =
+  typeof import('src/bootstrap/state.js').getQuestionPreviewFormat
diff --git a/packages/builtin-tools/src/tools/AskUserQuestionTool/src/components/MessageResponse.ts b/packages/builtin-tools/src/tools/AskUserQuestionTool/src/components/MessageResponse.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type MessageResponse = any
+/** 工具结果在消息流中的外层布局组件；与宿主 `src/components/MessageResponse.js` 中 `MessageResponse` 一致。 */
+export type MessageResponse =
+  typeof import('src/components/MessageResponse.js').MessageResponse
diff --git a/packages/builtin-tools/src/tools/AskUserQuestionTool/src/constants/figures.ts b/packages/builtin-tools/src/tools/AskUserQuestionTool/src/constants/figures.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type BLACK_CIRCLE = any
+/** 列表/状态行中使用的实心圆点字符（平台相关）；与宿主 `src/constants/figures.js` 中 `BLACK_CIRCLE` 常量类型一致。 */
+export type BLACK_CIRCLE =
+  typeof import('src/constants/figures.js').BLACK_CIRCLE
diff --git a/packages/builtin-tools/src/tools/AskUserQuestionTool/src/utils/permissions/PermissionMode.ts b/packages/builtin-tools/src/tools/AskUserQuestionTool/src/utils/permissions/PermissionMode.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getModeColor = any
+/** 将权限模式映射为 Ink 主题颜色键，用于状态行等 UI；与宿主 `getModeColor` 一致。 */
+export type getModeColor =
+  typeof import('src/utils/permissions/PermissionMode.js').getModeColor
diff --git a/packages/builtin-tools/src/tools/BashTool/src/Tool.ts b/packages/builtin-tools/src/tools/BashTool/src/Tool.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type ToolPermissionContext = any
+/** 工具权限检查用的不可变上下文快照；与宿主 `src/Tool.js` 中 `ToolPermissionContext` 一致。 */
+export type ToolPermissionContext = import('src/Tool.js').ToolPermissionContext
diff --git a/packages/builtin-tools/src/tools/BashTool/src/bootstrap/state.ts b/packages/builtin-tools/src/tools/BashTool/src/bootstrap/state.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getOriginalCwd = any
+/** 返回进程启动时的原始工作目录（不受中途切换工作区影响）；与宿主 `getOriginalCwd` 一致。 */
+export type getOriginalCwd =
+  typeof import('src/bootstrap/state.js').getOriginalCwd
diff --git a/packages/builtin-tools/src/tools/BashTool/src/hooks/useCanUseTool.ts b/packages/builtin-tools/src/tools/BashTool/src/hooks/useCanUseTool.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type CanUseToolFn = any
+/** 工具调用权限判定回调（交互/自动模式分支）；与宿主 `src/hooks/useCanUseTool.tsx` 中 `CanUseToolFn` 一致。 */
+export type CanUseToolFn = import('src/hooks/useCanUseTool.js').CanUseToolFn
diff --git a/packages/builtin-tools/src/tools/BashTool/src/services/analytics/growthbook.ts b/packages/builtin-tools/src/tools/BashTool/src/services/analytics/growthbook.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getFeatureValue_CACHED_MAY_BE_STALE = any
+/** 从磁盘缓存读取 GrowthBook/门控配置（可能略旧）；与宿主 `getFeatureValue_CACHED_MAY_BE_STALE` 一致。 */
+export type getFeatureValue_CACHED_MAY_BE_STALE =
+  typeof import('src/services/analytics/growthbook.js').getFeatureValue_CACHED_MAY_BE_STALE
diff --git a/packages/builtin-tools/src/tools/BashTool/src/services/analytics/index.ts b/packages/builtin-tools/src/tools/BashTool/src/services/analytics/index.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type logEvent = any
+/** 同步记录分析事件（未附加 sink 时入队）；与宿主 `src/services/analytics/index.js` 中 `logEvent` 一致。 */
+export type logEvent = typeof import('src/services/analytics/index.js').logEvent
diff --git a/packages/builtin-tools/src/tools/BashTool/src/state/AppState.ts b/packages/builtin-tools/src/tools/BashTool/src/state/AppState.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type AppState = any
+/** REPL 全局 UI 与权限等状态快照类型；与宿主 `src/state/AppStateStore.js` 中 `AppState` 一致。 */
+export type AppState = import('src/state/AppStateStore.js').AppState
diff --git a/packages/builtin-tools/src/tools/BashTool/src/utils/Shell.ts b/packages/builtin-tools/src/tools/BashTool/src/utils/Shell.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type setCwd = any
+/** 将 Shell 会话当前目录设为解析后的物理路径；与宿主 `src/utils/Shell.js` 中 `setCwd` 一致。 */
+export type setCwd = typeof import('src/utils/Shell.js').setCwd
diff --git a/packages/builtin-tools/src/tools/BashTool/src/utils/cwd.ts b/packages/builtin-tools/src/tools/BashTool/src/utils/cwd.ts
@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type getCwd = any
+/** 返回当前 Shell/会话逻辑工作目录字符串；与宿主 `src/utils/cwd.js` 中 `getCwd` 一致。 */
+export type getCwd = typeof import('src/utils/cwd.js').getCwd
diff --git a/packages/builtin-tools/src/tools/BashTool/src/utils/permissions/filesystem.ts b/packages/builtin-tools/src/tools/BashTool/src/utils/permissions/filesystem.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type pathInAllowedWorkingPath = any
+/** 判断路径是否落在当前工具允许的合并工作目录内；与宿主 `pathInAllowedWorkingPath` 一致。 */
+export type pathInAllowedWorkingPath =
+  typeof import('src/utils/permissions/filesystem.js').pathInAllowedWorkingPath
diff --git a/packages/builtin-tools/src/tools/BashTool/src/utils/sandbox/sandbox-ui-utils.ts b/packages/builtin-tools/src/tools/BashTool/src/utils/sandbox/sandbox-ui-utils.ts
@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type removeSandboxViolationTags = any
+/** 从展示文本中剥离沙箱违规相关的标记标签，避免 UI 噪音；与宿主 `removeSandboxViolationTags` 一致。 */
+export type removeSandboxViolationTags =
+  typeof import('src/utils/sandbox/sandbox-ui-utils.js').removeSandboxViolationTags
diff --git a/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts b/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts
@@ -1,12 +1,10 @@
 /**
  * ExecuteTool.test.ts
  *
- * Thin subprocess wrapper that runs the actual tests in an isolated bun:test
- * process. This prevents mock.module() leaks from other test files
- * (e.g., agentToolUtils.test.ts mocking src/Tool.js) from affecting
- * ExecuteTool's tests.
+ * 薄层子进程包装器，在独立的 bun:test 进程中运行实际测试。
+ * 这样可以防止其他测试文件的 mock.module() 漏出（例如 agentToolUtils.test.ts
+ * 对 src/Tool.js 的 mock）影响 ExecuteTool 的测试。
  */
-
 import { describe, test, expect } from 'bun:test'
 import { resolve, relative } from 'path'
 

diff --git a/packages/builtin-tools/src/tools/NotebookEditTool/NotebookEditTool.ts b/packages/builtin-tools/src/tools/NotebookEditTool/NotebookEditTool.ts
@@ -383,8 +383,8 @@ export const NotebookEditTool = buildTool({
       const language = notebook.metadata.language_info?.name ?? 'python'
       let new_cell_id
       if (
-        notebook.nbformat > 4 ||
-        (notebook.nbformat === 4 && notebook.nbformat_minor >= 5)
+        (notebook.nbformat ?? 4) > 4 ||
+        ((notebook.nbformat ?? 4) === 4 && (notebook.nbformat_minor ?? 0) >= 5)
       ) {
         if (edit_mode === 'insert') {
           new_cell_id = Math.random().toString(36).substring(2, 15)

diff --git a/src/cli/transports/Transport.ts b/src/cli/transports/Transport.ts
@@ -1,2 +1,10 @@
-// Auto-generated stub — replace with real implementation
-export type Transport = any
+import type { StdoutMessage } from 'src/entrypoints/sdk/controlTypes.js'
+
+/** WebSocket / SSE+POST / Hybrid 等会话上行传输的共有接口。 */
+export type Transport = {
+  setOnData(callback: (data: string) => void): void // 注册下行数据回调（按行文本）
+  setOnClose(callback: (closeCode?: number) => void): void // 连接关闭时回调（可选关闭码）
+  connect(): void | Promise<void> // 建立或重连传输
+  write(message: StdoutMessage): void | Promise<void> // 向上游发送一条控制/流式消息
+  close(): void // 主动关闭并释放资源
+}
diff --git a/src/commands/login/getAuthStatus.ts b/src/commands/login/getAuthStatus.ts
@@ -11,6 +11,7 @@
  *   - Third-party API key values are NEVER included; only boolean presence flags.
  */
 
+import type { SubscriptionType } from '../../services/oauth/types.js'
 import { getClaudeAIOAuthTokens } from '../../utils/auth.js'
 import { getGlobalConfig } from '../../utils/config.js'
 
@@ -107,7 +108,10 @@ export function getAuthStatus(): AuthStatus {
 
   let plan: AuthStatus['subscription']['plan'] = null
   if (subscriptionActive && oauthTokens) {
-    const raw = oauthTokens.subscriptionType
+    // 本地持久化或历史 token 中可能出现 'free' 等未纳入 SubscriptionType 的字符串
+    const raw = oauthTokens.subscriptionType as
+      | (SubscriptionType | 'free')
+      | null
     if (
       raw === 'free' ||
       raw === 'pro' ||

diff --git a/src/commands/plugin/ManagePlugins.tsx b/src/commands/plugin/ManagePlugins.tsx
@@ -35,6 +35,7 @@ import {
   isPluginEnabledAtProjectScope,
   uninstallPluginOp,
   updatePluginOp,
+  type InstallableScope,
 } from '../../services/plugins/pluginOperations.js';
 import { useAppState } from '../../state/AppState.js';
 import type { Tool } from '../../Tool.js';
@@ -76,7 +77,7 @@ import { PluginOptionsDialog } from './PluginOptionsDialog.js';
 import { PluginOptionsFlow } from './PluginOptionsFlow.js';
 import type { ViewState as ParentViewState } from './types.js';
 import { UnifiedInstalledCell } from './UnifiedInstalledCell.js';
-import type { UnifiedInstalledItem } from './unifiedTypes.js';
+import type { UnifiedInstalledItem, UnifiedInstalledScope } from './unifiedTypes.js';
 import { usePagination } from './usePagination.js';
 
 type Props = {
@@ -103,7 +104,7 @@ type FailedPluginInfo = {
   name: string;
   marketplace: string;
   errors: PluginError[];
-  scope: PersistablePluginScope;
+  scope: UnifiedInstalledScope;
 };
 
 type ViewState =
@@ -1253,7 +1254,7 @@ export function ManagePlugins({
       const isEnabled = mergedSettings?.enabledPlugins?.[pluginId] !== false;
       const pluginScope = item.scope;
       const isBuiltin = pluginScope === 'builtin';
-      if (isBuiltin || isInstallableScope(pluginScope)) {
+      if (isBuiltin || isInstallableScope(pluginScope as PersistablePluginScope)) {
         const newPending = new Map(pendingToggles);
         // Omit scope — see handleSingleOperation's enable/disable comment.
         if (currentPending) {
@@ -1579,8 +1580,8 @@ export function ManagePlugins({
             // is a recovery path for a plugin that failed to load — it may
             // be reinstallable, so don't nuke ${CLAUDE_PLUGIN_DATA} silently.
             // The normal uninstall path prompts; this one preserves.
-            const result = isInstallableScope(pluginScope)
-              ? await uninstallPluginOp(pluginId, pluginScope, false)
+            const result = isInstallableScope(pluginScope as PersistablePluginScope)
+              ? await uninstallPluginOp(pluginId, pluginScope as InstallableScope, false)
               : await uninstallPluginOp(pluginId, 'user', false);
             let success = result.success;
             if (!success) {