fix(tsc): Phase 1 — add 25 stub files, eliminate all Cannot find module errors (270→204)

- 25 stub files: types/tools, types/utils, contextCollapse, mcpSkills, etc. - 11 reused from chore/bridge-green, 14 created from scratch - All stubs documented in docs/devlog/02-tsc-stubs.md - Build passes, tests not regressed
2026-06-07 10:41:02 +08:00 · 2026-06-07 10:41:02 +08:00 · 315b0bd80e
commit 315b0bd80e
parent 00a0c86cc0
27 changed files with 582 additions and 0 deletions
--- a/docs/devlog/02-tsc-stubs.md
+++ b/docs/devlog/02-tsc-stubs.md
@ -0,0 +1,188 @@
+# TSC Stubs 记录
+
+> 创建日期: 2026-06-07
+> 关联计划: docs/plans/tsc-decompile-fix-plan.md
+> 阶段: Phase 1 — 消除 "Cannot find module" 类型错误
+
+## 成果总结
+
+- **创建 stub 数**: 25 个
+- **消除 "Cannot find module" 错误**: 75 个全部消除（75 → 0）
+- **构建状态**: bun run build 通过 ✅
+- **剩余 TS 错误**: 204 个（均为类型不匹配、属性不存在、变量未定义等其他错误类型）
+
+## Stub 清单
+
+### src/types/tools.ts
+- **引用方**: 17 个文件（Tool.ts, BashModeProgress.tsx, sdkEventQueue.ts, processBashCommand.tsx, sdkProgress.ts, AgentTool.tsx, AgentTool/UI.tsx, MCPTool.ts, MCPTool/UI.tsx, PowerShellTool.tsx, PowerShellTool/UI.tsx, SkillTool.ts, TaskOutputTool.tsx, WebSearchTool.ts, BashTool.tsx ×2）
+- **导出内容**: AgentToolProgress, BashProgress, MCPProgress, REPLToolProgress, SkillToolProgress, TaskOutputProgress, ToolProgressData, WebSearchProgress, ShellProgress, PowerShellProgress, SdkWorkflowProgress
+- **补全优先级**: **高** — 这些类型被工具系统广泛引用，需要从上游恢复具体字段定义
+- **备注**: 当前所有类型均为 `Record<string, unknown>`。bridge-green 版本同样是 `any` 类型的自动生成 stub
+
+### src/types/utils.ts
+- **引用方**: 16 个文件（AppStateStore.ts, Tool.ts, taskStatusUtils.tsx, 各 task dialog, messageQueueManager.ts, mappers.ts, messages.ts, 各 MonitorMcpTask dialog）
+- **导出内容**: DeepImmutable<T>, Permutations<T>
+- **补全优先级**: **高** — DeepImmutable 用于工具权限上下文类型
+- **备注**: 当前为 identity passthrough。bridge-green 版本同样是 `any` 类型的自动生成 stub
+
+### src/services/contextCollapse/operations.ts
+- **引用方**: 2 个文件（context.tsx, context-noninteractive.ts — 通过动态 `require()`）
+- **导出内容**: projectView(messages: Message[]) => Message[]
+- **补全优先级**: **中** — 仅在 CONTEXT_COLLAPSE feature flag 启用时被调用
+- **备注**: bridge-green 版本也是 no-op stub，导出为空
+
+### src/commands/peers/index.ts
+- **引用方**: 1 个文件（commands.ts — 动态 import）
+- **导出内容**: default export (空对象)
+- **补全优先级**: **低** — peer 功能被 feature-gated
+- **备注**: bridge-green 版本也是空 stub
+
+### src/commands/fork/index.ts
+- **引用方**: 1 个文件（commands.ts — 动态 import）
+- **导出内容**: default export (空对象)
+- **补全优先级**: **低** — fork 功能被 feature-gated
+- **备注**: bridge-green 版本也是空 stub
+
+### src/components/messages/UserGitHubWebhookMessage.tsx
+- **引用方**: 1 个文件（UserTextMessage.tsx — 通过动态 `require()`，KAIROS_GITHUB_WEBHOOKS feature flag）
+- **导出内容**: UserGitHubWebhookMessage (React 组件，渲染 null)
+- **补全优先级**: **低** — 仅在 KAIROS_GITHUB_WEBHOOKS 启用时使用
+- **备注**: bridge-green 版本不存在此文件
+
+### src/components/messages/UserForkBoilerplateMessage.tsx
+- **引用方**: 1 个文件（UserTextMessage.tsx — 通过动态 `require()`，FORK_SUBAGENT feature flag）
+- **导出内容**: UserForkBoilerplateMessage (React 组件，渲染 null)
+- **补全优先级**: **低** — 仅在 FORK_SUBAGENT 启用时使用
+- **备注**: bridge-green 版本不存在此文件
+
+### src/components/messages/UserCrossSessionMessage.tsx
+- **引用方**: 1 个文件（UserTextMessage.tsx — 通过动态 `require()`，UDS_INBOX feature flag）
+- **导出内容**: UserCrossSessionMessage (React 组件，渲染 null)
+- **补全优先级**: **低** — 仅在 UDS_INBOX 启用时使用
+- **备注**: bridge-green 版本不存在此文件
+
+### src/services/compact/snipProjection.ts
+- **引用方**: 3 个文件（Message.tsx, QueryEngine.ts, messages.ts — 通过动态 `require()`，HISTORY_SNIP feature flag）
+- **导出内容**: isSnipBoundaryMessage(message) => boolean, projectSnippedView(messages) => Message[]
+- **补全优先级**: **中** — 历史对话压缩功能
+- **备注**: bridge-green 版本也是 no-op stub
+
+### src/components/messages/SnipBoundaryMessage.tsx
+- **引用方**: 1 个文件（Message.tsx — 通过动态 `require()`，HISTORY_SNIP feature flag）
+- **导出内容**: SnipBoundaryMessage (React 组件，渲染 null)
+- **补全优先级**: **低** — 仅在 HISTORY_SNIP 启用时使用
+- **备注**: bridge-green 版本不存在此文件
+
+### src/components/permissions/ReviewArtifactPermissionRequest/ReviewArtifactPermissionRequest.tsx
+- **引用方**: 1 个文件（PermissionRequest.tsx — 通过动态 `require()`，REVIEW_ARTIFACT feature flag）
+- **导出内容**: ReviewArtifactPermissionRequest (React 组件，渲染 null)
+- **补全优先级**: **低** — 仅在 REVIEW_ARTIFACT 启用时使用
+- **备注**: bridge-green 版本不存在此文件
+
+### src/environment-runner/main.ts
+- **引用方**: 1 个文件（entrypoints/cli.tsx — 动态 import）
+- **导出内容**: environmentRunnerMain(args: string[]) => Promise<void>
+- **补全优先级**: **低** — BYOC runner，feature-gated
+- **备注**: bridge-green 版本也是 no-op stub
+
+### src/self-hosted-runner/main.ts
+- **引用方**: 1 个文件（entrypoints/cli.tsx — 动态 import）
+- **导出内容**: selfHostedRunnerMain(args: string[]) => Promise<void>
+- **补全优先级**: **低** — BYOC runner，feature-gated
+- **备注**: bridge-green 版本也是 no-op stub
+
+### src/services/contextCollapse/persist.ts
+- **引用方**: 3 个文件（ResumeConversation.tsx, sessionRestore.ts ×2 — 动态 `require()`）
+- **导出内容**: restoreFromEntries(...args) => void
+- **补全优先级**: **中** — 会话恢复功能
+- **备注**: bridge-green 版本也是 no-op stub
+
+### src/memdir/memoryShapeTelemetry.ts
+- **引用方**: 2 个文件（findRelevantMemories.ts, sessionFileAccessHooks.ts — 动态 `require()`，MEMORY_SHAPE_TELEMETRY feature flag）
+- **导出内容**: logMemoryRecallShape, logMemoryWriteShape
+- **补全优先级**: **低** — 仅用于 telemetry/analytics
+- **备注**: bridge-green 版本也是 no-op stub
+
+### src/skills/mcpSkills.ts
+- **引用方**: 2 个文件（services/mcp/client.ts, useManageMCPConnections.ts — 动态 `require()`，MCP_SKILLS feature flag）
+- **导出内容**: fetchMcpSkillsForClient (返回 Promise<Command[]>)
+- **补全优先级**: **中** — MCP 技能发现功能
+- **备注**: bridge-green 版本也是 stub，带 cache map
+
+### src/services/skillSearch/signals.ts
+- **引用方**: 2 个文件（prefetch.ts, attachments.ts — 直接 import type）
+- **导出内容**: DiscoverySignal (type)
+- **补全优先级**: **中** — 技能搜索系统的基础类型
+- **备注**: bridge-green 版本为 `any` 类型 stub，当前为完整对象类型
+
+### src/tasks/design-system/Byline.tsx
+- **引用方**: 2 个文件（MonitorMcpDetailDialog.tsx, WorkflowDetailDialog.tsx）
+- **导出内容**: Byline (React 组件)
+- **补全优先级**: **低** — MonitorMcpTask 仅在 monitor 模式下使用
+- **备注**: bridge-green 版本不存在
+
+### src/tasks/design-system/Dialog.tsx
+- **引用方**: 2 个文件（MonitorMcpDetailDialog.tsx, WorkflowDetailDialog.tsx）
+- **导出内容**: Dialog (React 组件)
+- **补全优先级**: **低** — MonitorMcpTask 仅在 monitor 模式下使用
+- **备注**: bridge-green 版本不存在
+
+### src/tasks/design-system/KeyboardShortcutHint.tsx
+- **引用方**: 2 个文件（MonitorMcpDetailDialog.tsx, WorkflowDetailDialog.tsx）
+- **导出内容**: KeyboardShortcutHint (React 组件)
+- **补全优先级**: **低** — MonitorMcpTask 仅在 monitor 模式下使用
+- **备注**: bridge-green 版本不存在
+
+### src/tools/ToolSearchTool/constants.ts
+- **引用方**: 1 个文件（prompt.ts — 直接 import）
+- **导出内容**: TOOL_SEARCH_TOOL_NAME = 'ToolSearch'
+- **补全优先级**: **高** — ToolSearch 工具需要此常量
+- **备注**: 此文件内容从 bridge-green 版本直接复制，是真实实现
+
+### src/utils/toolSearch.ts
+- **引用方**: 1 个文件（ToolSearchTool.ts — 直接 import）
+- **导出内容**: isToolSearchEnabledOptimistic() => boolean
+- **补全优先级**: **高** — ToolSearch 工具需要此函数判断是否启用 ToolSearch
+- **备注**: bridge-green 版本有完整实现（~400 行），当前仅导出最小接口
+
+### src/types/messageQueueTypes.ts
+- **引用方**: 3 个文件（logs.ts, messageQueueManager.ts, sessionStorage.ts）
+- **导出内容**: QueueOperation, QueueOperationMessage
+- **补全优先级**: **高** — 消息队列系统的基础类型
+- **备注**: bridge-green 版本也是 stub，内容基本一致
+
+### src/utils/postCommitAttribution.ts
+- **引用方**: 1 个文件（worktree.ts — 动态 import()，COMMIT_ATTRIBUTION feature flag）
+- **导出内容**: installPrepareCommitMsgHook
+- **补全优先级**: **低** — 仅在 COMMIT_ATTRIBUTION 启用时使用
+- **备注**: bridge-green 版本也是 no-op stub
+
+## 补全优先级排序
+
+### 高优先级（需要尽快恢复真实实现）
+1. **src/types/tools.ts** — 17 处引用，工具系统核心类型
+2. **src/types/utils.ts** — 16 处引用，类型工具
+3. **src/utils/toolSearch.ts** — ToolSearch 工具依赖
+4. **src/types/messageQueueTypes.ts** — 消息队列系统类型
+5. **src/tools/ToolSearchTool/constants.ts** — 常量（已为真实值）
+
+### 中优先级（feature-gated 但有多个引用）
+6. **src/services/contextCollapse/operations.ts** — feature: CONTEXT_COLLAPSE
+7. **src/services/contextCollapse/persist.ts** — 会话恢复
+8. **src/services/compact/snipProjection.ts** — feature: HISTORY_SNIP
+9. **src/skills/mcpSkills.ts** — feature: MCP_SKILLS
+10. **src/services/skillSearch/signals.ts** — 技能搜索
+
+### 低优先级（feature-gated，单引用或少使用）
+11. — 25. 其余所有 stub（主要在 feature flag 保护下，运行时不会被调用）
+
+## 未消除的错误
+
+所有 75 个 "Cannot find module" 错误已全部消除。剩余的 204 个 TS 错误属于其他类型：
+- `TS2322: Type 'X' is not assignable to type 'Y'`
+- `TS2339: Property 'X' does not exist on type 'Y'`
+- `TS2304: Cannot find name 'X'`
+- `TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'`
+- 等
+
+这些将在后续阶段（Phase 2+）中逐步处理。
--- a/docs/plans/tsc-decompile-fix-plan.md
+++ b/docs/plans/tsc-decompile-fix-plan.md
@ -0,0 +1,109 @@
+# TSC 类型错误修复计划 — 反编译残留（235 个）
+
+> **目标：** 基于 `chore/bridge-green`（1 错误）参考，修复 acp 分支 270 个类型错误中的 235 个反编译残留（排除 35 个社区自写代码 bug）。
+
+**基线：** `chore/bridge-green` commit `27682acf` — 1 error  
+**当前：** `acp` — 270 errors（排除社区代码后 235）
+
+---
+
+## 错误分类
+
+### A 类：缺文件 stub（75 errors）
+
+| 缺失模块 | 引用次数 | Bridge-green 状态 |
+|---|---|---|
+| `src/types/tools.js` | 17 | 文件不存在但无引用（或导出已补齐） |
+| `src/types/utils.js` | 15 | 同上 |
+| `src/services/contextCollapse/persist.js` | 3 | 同上 |
+| `src/services/contextCollapse/operations.js` | 2 | 同上 |
+| `src/services/compact/snipProjection.js` | 3 | 同上 |
+| `src/types/messageQueueTypes.js` | 3 | 同上 |
+| `src/skills/mcpSkills.js` | 2 | 同上 |
+| `src/services/skillSearch/signals.js` | 2 | 同上 |
+| `src/services/compact/cachedMCConfig.js` | 1 | 同上 |
+| `src/utils/toolSearch.js` | 1 | 同上 |
+| `src/utils/postCommitAttribution.js` | 1 | 同上 |
+| `src/memdir/memoryShapeTelemetry.js` | 2 | 同上 |
+| `components/messages/SnipBoundaryMessage.js` | 1 | 同上 |
+| `components/messages/UserGitHubWebhookMessage.js` | 1 | 同上 |
+| `components/messages/UserForkBoilerplateMessage.js` | 1 | 同上 |
+| `components/messages/UserCrossSessionMessage.js` | 1 | 同上 |
+| `components/permissions/.../ReviewArtifactPermissionRequest.js` | 1 | 同上 |
+| `components/design-system/Byline.js` | 2 | 同上 |
+| `components/design-system/Dialog.js` | 2 | 同上 |
+| `components/design-system/KeyboardShortcutHint.js` | 2 | 同上 |
+| `tools/ToolSearchTool/constants.js` | 2 | 同上 |
+| `commands/peers/index.js` | 1 | 同上 |
+| `commands/fork/index.js` | 1 | 同上 |
+| `environment-runner/main.js` | 1 | 同上 |
+| `self-hosted-runner/main.js` | 1 | 同上 |
+| 其他零散 | ~5 | 同上 |
+
+**修复策略：** 每个缺失文件创建最小 stub，注释标记为 `// STUB: 待补全`。**每个 stub 必须在 `docs/devlog/02-tsc-stubs.md` 中详细记录**，包含：
+- 文件路径
+- 被哪些文件引用
+- 最小导出内容
+- 补全优先级（高/中/低）
+
+### B 类：`unknown` 类型泛滥（78 errors）
+
+| 重灾区文件 | 数量 | 根因 |
+|---|---|---|
+| `src/utils/task/framework.ts` | 9 | `getState()` 返回 `unknown` |
+| `src/utils/teammate.ts` | 8 | 状态对象类型为 `unknown` |
+| `src/hooks/useCancelRequest.ts` | 7 | 任务对象类型丢失 |
+| `src/commands/context/context-noninteractive.ts` | 8 | `contextCollapse` 方法类型缺失 |
+| `src/components/PromptInput/PromptInput.tsx` | 7 | 多处 `unknown` 参数 |
+| `src/components/ContextVisualization.tsx` | 7 | 同上 |
+| `src/components/TokenWarning.tsx` | 6 | 同上 |
+| 其他 | 26 | — |
+
+**修复策略：** 逐文件加类型标注，参考 bridge-green 版本。部分 `unknown` 来自缺失的类型定义文件（与 A 类关联）。
+
+### C 类：缺导出/缺名字（27 errors）
+
+| 根因 | 数量 | 修复 |
+|---|---|---|
+| `Cannot find name 'feature'` | 2 | 加 import |
+| `Cannot find name` — contextCollapse 方法 | ~10 | 补 contextCollapse/index.js 导出 |
+| `Cannot find name` — 其他 | ~13 | 逐项补 import 或 stub |
+| `no exported member` | 2 | 补导出 |
+
+### D 类：类型不匹配（50+ errors）
+
+| 类别 | 数量 | 修复 |
+|---|---|---|
+| Property 不存在 | ~40 | 加类型字段或 `as` 断言 |
+| 类型转换错误 | 4 | 加 `as unknown as` |
+| 重复标识符 | 2 | 删重 |
+| 参数类型错误 | ~10 | 收窄类型 |
+
+---
+
+## 执行顺序
+
+### Phase 1：A 类——批量建 stub（预计消 75 错误）
+1. 创建 `src/types/tools.js` stub
+2. 创建 `src/types/utils.js` stub
+3. 创建其他缺失文件的 stub
+4. 记录所有 stub 到 `docs/devlog/02-tsc-stubs.md`
+
+### Phase 2：C 类——补导出和名字（预计消 27 错误）
+1. 补 `contextCollapse` 导出
+2. 补 `feature()` import
+3. 补其他缺失的名字
+
+### Phase 3：B + D 类——类型收窄（预计消 130+ 错误）
+1. 从 bridge-green 逐文件参考修复
+2. 优先高密度文件（task/framework.ts 9 个，teammate.ts 8 个）
+
+---
+
+## 约束
+
+1. **不修社区代码**：ACP、RCS、Bridge、autofix-pr、swarm、ssh 等社区自写功能
+2. **每个 stub 必须文档化**：`docs/devlog/02-tsc-stubs.md` 详细记录
+3. **构建必须保持通过**：每批修复后 `bun run build`
+4. **测试不能回归**：每批修复后 `bun run test`
+5. **不引入 `as any`**：用正确类型或 `// @ts-expect-error` 标注
--- a/src/commands/fork/index.ts
+++ b/src/commands/fork/index.ts
@ -0,0 +1,6 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Fork command module — handles fork-related CLI subcommands.
+// Imported dynamically by src/commands.ts. Stub: empty default export.
+
+const _default: Record<string, unknown> = {}
+export default _default
--- a/src/commands/peers/index.ts
+++ b/src/commands/peers/index.ts
@ -0,0 +1,6 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Peers command module — handles peer-related CLI subcommands.
+// Imported dynamically by src/commands.ts. Stub: empty default export.
+
+const _default: Record<string, unknown> = {}
+export default _default
--- a/src/components/messages/SnipBoundaryMessage.tsx
+++ b/src/components/messages/SnipBoundaryMessage.tsx
@ -0,0 +1,11 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Snip boundary message — rendered when HISTORY_SNIP feature is enabled
+// to indicate a compacted message boundary in the conversation.
+// Dynamically require'd by Message.tsx.
+// Stub: renders null.
+
+import type { ReactNode } from 'react'
+
+export function SnipBoundaryMessage(): ReactNode {
+  return null
+}
--- a/src/components/messages/UserCrossSessionMessage.tsx
+++ b/src/components/messages/UserCrossSessionMessage.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Cross-session message component (from another Claude session's SendMessage).
+// Dynamically require'd by UserTextMessage.tsx when UDS_INBOX feature is enabled.
+// Stub: renders null.
+
+import type { ReactNode } from 'react'
+
+export function UserCrossSessionMessage(): ReactNode {
+  return null
+}
--- a/src/components/messages/UserForkBoilerplateMessage.tsx
+++ b/src/components/messages/UserForkBoilerplateMessage.tsx
@ -0,0 +1,11 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Fork boilerplate message component.
+// Dynamically require'd by UserTextMessage.tsx when FORK_SUBAGENT feature is enabled.
+// Renders the initial directive for a fork child conversation.
+// Stub: renders null.
+
+import type { ReactNode } from 'react'
+
+export function UserForkBoilerplateMessage(): ReactNode {
+  return null
+}
--- a/src/components/messages/UserGitHubWebhookMessage.tsx
+++ b/src/components/messages/UserGitHubWebhookMessage.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// GitHub webhook activity message component.
+// Dynamically require'd by UserTextMessage.tsx when KAIROS_GITHUB_WEBHOOKS feature is enabled.
+// Stub: renders null.
+
+import type { ReactNode } from 'react'
+
+export function UserGitHubWebhookMessage(): ReactNode {
+  return null
+}
--- a/src/components/permissions/ReviewArtifactPermissionRequest/ReviewArtifactPermissionRequest.tsx
+++ b/src/components/permissions/ReviewArtifactPermissionRequest/ReviewArtifactPermissionRequest.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Permission request dialog for ReviewArtifact tool.
+// Dynamically require'd by PermissionRequest.tsx when REVIEW_ARTIFACT feature is enabled.
+// Stub: renders null.
+
+import type { ReactNode } from 'react'
+
+export function ReviewArtifactPermissionRequest(): ReactNode {
+  return null
+}
--- a/src/environment-runner/main.ts
+++ b/src/environment-runner/main.ts
@ -0,0 +1,6 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Environment runner — BYOC (Bring Your Own Cloud) runner entry point.
+// Dynamically require'd by src/entrypoints/cli.tsx.
+// Stub: resolves immediately.
+
+export const environmentRunnerMain: (args: string[]) => Promise<void> = () => Promise.resolve()
--- a/src/memdir/memoryShapeTelemetry.ts
+++ b/src/memdir/memoryShapeTelemetry.ts
@ -0,0 +1,11 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Memory shape telemetry — logs memory recall/write shape for analytics.
+// Dynamically require'd by findRelevantMemories.ts and sessionFileAccessHooks.ts
+// when MEMORY_SHAPE_TELEMETRY feature is enabled.
+// Stub: no-op functions.
+
+import type { MemoryHeader } from './memoryScan.js'
+import type { MemoryScope } from '../utils/memoryFileDetection.js'
+
+export const logMemoryRecallShape: (memories: MemoryHeader[], selected: MemoryHeader[]) => void = () => {}
+export const logMemoryWriteShape: (toolName: string, toolInput: Record<string, unknown>, filePath: string, scope: MemoryScope) => void = () => {}
--- a/src/self-hosted-runner/main.ts
+++ b/src/self-hosted-runner/main.ts
@ -0,0 +1,6 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Self-hosted runner entry point — BYOC self-hosted runner.
+// Dynamically require'd by src/entrypoints/cli.tsx.
+// Stub: resolves immediately.
+
+export const selfHostedRunnerMain: (args: string[]) => Promise<void> = () => Promise.resolve()
--- a/src/services/compact/cachedMCConfig.ts
+++ b/src/services/compact/cachedMCConfig.ts
@ -0,0 +1,11 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Cached model configuration (MC) config utilities.
+// Used by prompts.ts to read cached MC settings including summary suggestions.
+// Stub: returns empty config.
+
+export const getCachedMCConfig: () => {
+  enabled?: boolean
+  systemPromptSuggestSummaries?: boolean
+  supportedModels?: string[]
+  [key: string]: unknown
+} = () => ({})
--- a/src/services/compact/snipProjection.ts
+++ b/src/services/compact/snipProjection.ts
@ -0,0 +1,19 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Snip projection utilities — used by HISTORY_SNIP feature to compact
+// conversation history by snipping out old messages and replacing them
+// with boundary markers.
+// Dynamically require'd by Message.tsx and QueryEngine.ts.
+
+import type { Message } from 'src/types/message.js'
+
+/**
+ * Returns true if the given message is a snip boundary marker.
+ * Stub: always returns false.
+ */
+export const isSnipBoundaryMessage: (message: Message) => boolean = () => false
+
+/**
+ * Projects messages through the snip view — returns a filtered/compressed
+ * view of the message list. Stub implementation: identity (no-op).
+ */
+export const projectSnippedView: (messages: Message[]) => Message[] = (messages) => messages
--- a/src/services/contextCollapse/operations.ts
+++ b/src/services/contextCollapse/operations.ts
@ -0,0 +1,13 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Context collapse operations for projecting messages into a collapsed view.
+// Used by context-noninteractive.ts and context.tsx via dynamic require().
+// When upstream is available, replace with real implementation that collapses
+// conversation spans to reduce token usage.
+
+import type { Message } from 'src/types/message.js'
+
+/**
+ * Projects messages through context collapse — returns a filtered/compressed
+ * view of the message list. Stub implementation: identity (no-op).
+ */
+export const projectView: (messages: Message[]) => Message[] = (messages) => messages
--- a/src/services/contextCollapse/persist.ts
+++ b/src/services/contextCollapse/persist.ts
@ -0,0 +1,7 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Context collapse persistence utilities.
+// Dynamically require'd by ResumeConversation.tsx and sessionRestore.ts
+// to restore collapsed context entries from session data.
+// Stub: no-op.
+
+export const restoreFromEntries: (...args: unknown[]) => void = () => {}
--- a/src/services/skillSearch/signals.ts
+++ b/src/services/skillSearch/signals.ts
@ -0,0 +1,9 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Skill search signal types — used by skill search prefetch and attachment utilities.
+// DiscoverySignal represents the signal emitted when a skill is discovered during prefetch.
+
+export type DiscoverySignal = {
+  type: 'skill_discovery'
+  skillId: string
+  [key: string]: unknown
+}
--- a/src/skills/mcpSkills.ts
+++ b/src/skills/mcpSkills.ts
@ -0,0 +1,12 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// MCP skills — fetches skills/commands exposed via MCP servers.
+// Dynamically require'd by services/mcp/client.ts and useManageMCPConnections.ts
+// when MCP_SKILLS feature is enabled.
+// Stub: returns empty array of Command.
+
+import type { Command } from 'src/types/command.js'
+
+export const fetchMcpSkillsForClient: ((...args: unknown[]) => Promise<Command[]>) & { cache: Map<string, unknown> } = Object.assign(
+  (..._args: unknown[]) => Promise.resolve([] as Command[]),
+  { cache: new Map<string, unknown>() },
+)
--- a/src/tasks/design-system/Byline.tsx
+++ b/src/tasks/design-system/Byline.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Design-system Byline component.
+// Imported by MonitorMcpTask dialogs for rendering task metadata (author, timestamp).
+// Stub: renders an empty Box.
+
+import React from 'react'
+
+export function Byline(): React.ReactNode {
+  return null
+}
--- a/src/tasks/design-system/Dialog.tsx
+++ b/src/tasks/design-system/Dialog.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Design-system Dialog component.
+// Imported by MonitorMcpTask dialogs for rendering modal overlay dialogs.
+// Stub: renders children in a minimal container.
+
+import React from 'react'
+
+export function Dialog({ children }: { children?: React.ReactNode }): React.ReactNode {
+  return <>{children}</>
+}
--- a/src/tasks/design-system/KeyboardShortcutHint.tsx
+++ b/src/tasks/design-system/KeyboardShortcutHint.tsx
@ -0,0 +1,10 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Design-system KeyboardShortcutHint component.
+// Imported by MonitorMcpTask dialogs for rendering keyboard shortcut hints.
+// Stub: renders nothing.
+
+import React from 'react'
+
+export function KeyboardShortcutHint(): React.ReactNode {
+  return null
+}
--- a/src/tools/ToolSearchTool/constants.ts
+++ b/src/tools/ToolSearchTool/constants.ts
@ -0,0 +1,4 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Constants for ToolSearch tool.
+
+export const TOOL_SEARCH_TOOL_NAME = 'ToolSearch'
--- a/src/types/messageQueueTypes.ts
+++ b/src/types/messageQueueTypes.ts
@ -0,0 +1,20 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Message queue type definitions for session event queueing.
+// Used across messageQueueManager, sessionStorage, and log types.
+
+/**
+ * Type of queue operation performed.
+ */
+export type QueueOperation = 'enqueue' | 'dequeue' | 'remove' | string
+
+/**
+ * Message representing an operation in the session event queue.
+ */
+export type QueueOperationMessage = {
+  type: 'queue-operation'
+  operation: QueueOperation
+  timestamp: string
+  sessionId: string
+  content?: string
+  [key: string]: unknown
+}
--- a/src/types/tools.ts
+++ b/src/types/tools.ts
@ -0,0 +1,37 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Progress types used by built-in tools. These are re-exported via src/Tool.ts.
+// Currently all types are generic Record<string, unknown> until upstream provides
+// concrete progress field definitions from the decompiled Anthropic SDK.
+
+/** Progress data for AgentTool execution */
+export type AgentToolProgress = Record<string, unknown>
+
+/** Progress data for Bash tool execution */
+export type BashProgress = Record<string, unknown>
+
+/** Progress data for MCP tool execution */
+export type MCPProgress = Record<string, unknown>
+
+/** Progress data for REPL tool execution */
+export type REPLToolProgress = Record<string, unknown>
+
+/** Progress data for Skill tool execution */
+export type SkillToolProgress = Record<string, unknown>
+
+/** Progress data for TaskOutput tool */
+export type TaskOutputProgress = Record<string, unknown>
+
+/** Union of all tool progress types — the canonical Progress type used by Tool.ts */
+export type ToolProgressData = Record<string, unknown>
+
+/** Progress data for WebSearch tool */
+export type WebSearchProgress = Record<string, unknown>
+
+/** Progress data for Shell operations */
+export type ShellProgress = Record<string, unknown>
+
+/** Progress data for PowerShell tool */
+export type PowerShellProgress = Record<string, unknown>
+
+/** Progress data for SDK workflow progress events */
+export type SdkWorkflowProgress = Record<string, unknown>
--- a/src/types/utils.ts
+++ b/src/types/utils.ts
@ -0,0 +1,17 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Utility types shared across the codebase.
+// DeepImmutable and Permutations are placeholder type-level utilities.
+// When the upstream decompiled source is available, replace with the real
+// generic type definitions.
+
+/**
+ * Recursively marks all properties as readonly (deeply immutable).
+ * Current stub: identity passthrough — does not enforce immutability at type level.
+ */
+export type DeepImmutable<T> = T
+
+/**
+ * Generates all permutations of a union type as a tuple.
+ * Current stub: simple array passthrough.
+ */
+export type Permutations<T> = T[]
--- a/src/utils/postCommitAttribution.ts
+++ b/src/utils/postCommitAttribution.ts
@ -0,0 +1,7 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Post-commit attribution hook installation.
+// Dynamically import'd by worktree.ts when COMMIT_ATTRIBUTION feature is enabled.
+// Installs a prepare-commit-msg git hook for commit attribution tracking.
+// Stub: resolves immediately.
+
+export const installPrepareCommitMsgHook: (worktreePath: string, worktreeHooksDir?: string) => Promise<void> = async () => {}
--- a/src/utils/toolSearch.ts
+++ b/src/utils/toolSearch.ts
@ -0,0 +1,12 @@
+// STUB: 待补全 — 见 docs/devlog/02-tsc-stubs.md
+// Tool Search utilities for dynamically discovering deferred tools.
+// Only exports the minimum needed to resolve imports.
+// The full implementation lives in the chore/bridge-green branch.
+
+/**
+ * Optimistic check — returns true if tool search is likely enabled.
+ * Stub: always returns false.
+ */
+export function isToolSearchEnabledOptimistic(): boolean {
+  return false
+}