admin/aiagent
1
0
Fork 0
Code Issues 14 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
beff3fac8d153e77295c6ea79a76209e9f7bf03d
aiagent/clode/modules.md
renjianbo beff3fac8d fix: delete agent 500 error + dynamic personality + deployment guide 
- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions,
  schedules, executions, team_members) and unbind goals/tasks before delete
- Remove hardcoded personality templates in Android, replace with dynamic
  system prompt generation from name + description
- Set promptSectionsEnabled=false to bypass PromptComposer for personality
- Add Tencent Cloud Linux deployment guide (Docker Compose)
- Accumulated backend service updates, frontend UI fixes, Android app changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-29 01:17:21 +08:00

21 KiB
Raw Blame History

Claude Code 模块详解

本文档逐个分析 src/ 下每个目录和关键文件的职责。

1. Entry Points (src/entrypoints/)

cli.tsx (39KB)

CLI 主入口。职责：

  • 注入 globalThis.MACRO 全局变量（版本号、构建时间等）
  • 设置环境变量（COREPACK_ENABLE_AUTO_PIN、NODE_OPTIONS 等）
  • 快速路径路由：--version / --dump-system-prompt / --chrome-native-host / --computer-use-mcp 等
  • 加载 Commander 参数解析，挂载 60+ 命令
  • 启动主 REPL 界面

init.ts (14KB)

项目初始化逻辑（claude init 命令），负责检测仓库环境、创建 CLAUDE.md 等。

mcp.ts (6KB)

MCP 服务端入口，启动 MCP Server 供 IDE 插件连接。

sdk/ (子目录)

Agent SDK 的运行时常量类型导出。

agentSdkTypes.ts (13KB)

Agent SDK / Swarm SDK 的消息类型定义（SDKMessage, SDKStatus 等）。

sandboxTypes.ts (6KB)

沙箱执行环境相关类型定义。

2. 屏幕 (src/screens/)

REPL.tsx (900KB)

项目最大文件。交互式对话主界面，包含：

  • 消息列表渲染 (虚拟滚动)
  • 输入处理 (普通/多行/Vim 模式)
  • 状态栏集成
  • 权限请求流程
  • 模态弹窗管理
  • 键盘快捷键处理

Doctor.tsx (73KB)

诊断界面，检查环境配置（Bun 版本、网络、API Key 等），提供修复建议。

ResumeConversation.tsx (60KB)

会话恢复界面，列出历史会话供用户选择恢复。

3. 组件 (src/components/)

核心 UI 组件

文件 大小 职责
App.tsx 5KB 应用根组件，环境检测 + 屏幕路由
Messages.tsx 148KB 消息列表容器，消息增删改查
VirtualMessageList.tsx 149KB 虚拟滚动消息列表（大数据量优化）
Message.tsx 79KB 单条消息渲染（含工具调用/思考/文本）
MessageRow.tsx 48KB 消息行容器（头像/时间戳/操作按钮）
MessageSelector.tsx 116KB 消息过滤器/搜索
FullscreenLayout.tsx 85KB 全屏布局容器，处理窗口大小变化
TextInput.tsx 21KB 主输入框组件
VimTextInput.tsx 16KB Vim 模式输入框
BaseTextInput.tsx 19KB 输入框基础组件

状态和反馈

文件 大小 职责
StatusLine.tsx 49KB 底部状态栏（模型/成本/任务数）
Spinner.tsx 88KB 加载/思考动画
Stats.tsx 154KB 用量统计展示
Feedback.tsx 88KB 用户反馈提交
TokenWarning.tsx 21KB Token 超限警告

交互弹窗

文件 大小 职责
PermissionsDialog 多文件 工具权限请求弹窗
ModelPicker.tsx 54KB 模型选择器
ThemePicker.tsx 35KB 主题选择器
Onboarding.tsx 31KB 新手引导
GlobalSearchDialog.tsx 44KB 全局搜索
HistorySearchDialog.tsx 20KB 历史搜索
ExportDialog.tsx 19KB 会话导出

工具相关 UI

文件 大小 职责
FileEditToolDiff.tsx 22KB 文件编辑 Diff 展示
ToolUseLoader.tsx 4KB 工具调用加载动画
FallbackToolUseErrorMessage.tsx 12KB 工具调用错误提示
CoordinatorAgentStatus.tsx 36KB Agent 协调器状态

功能组件

文件 大小 职责
Markdown.tsx 28KB Markdown 渲染（含代码高亮）
MarkdownTable.tsx 47KB Markdown 表格渲染
HighlightedCode.tsx 17KB 代码语法高亮
StructuredDiff.tsx 25KB 结构化 Diff 渲染
TaskListV2.tsx 50KB 任务列表面板
ContextVisualization.tsx 76KB 上下文可视化
AutoUpdater.tsx 30KB 自动更新
ThinkingToggle.tsx 18KB 思考开关切换
OutputStylePicker.tsx 13KB 输出样式选择
CompactSummary.tsx 14KB 对话压缩摘要

Bridge 相关

文件 大小 职责
BridgeDialog.tsx 34KB 远程连接对话框
RemoteEnvironmentDialog.tsx 33KB 远程环境配置
TrustDialog/ 目录 设备信任验证

子目录

  • components/agents/ — Agent 相关子组件
  • components/design-system/ — 设计系统基础组件
  • components/diff/ — Diff 渲染组件
  • components/grove/ — 树/图可视化
  • components/hooks/ — 组件专用 Hooks
  • components/mcp/ — MCP 服务器管理 UI
  • components/memory/ — 记忆管理 UI
  • components/messages/ — 消息子组件
  • components/permissions/ — 权限弹窗组件
  • components/sandbox/ — 沙箱 UI
  • components/shell/ — Shell 输出渲染
  • components/skills/ — 技能管理 UI
  • components/tasks/ — 任务管理 UI
  • components/teams/ — 团队功能 UI
  • components/ui/ — 通用 UI 原子组件
  • components/wizard/ — 向导式流程

4. 终端渲染层 (src/ink/)

对 ink 库的深度扩展，实现了自定义终端渲染管道。

文件 大小 职责
ink.tsx 253KB 核心 Ink 渲染钩子 (useInput/useStdin/useStdout)
screen.ts 50KB 终端屏幕缓冲区 (ANSI 输出缓存和 diff 计算)
output.ts 26KB 输出流管理
render-node-to-output.ts 64KB 虚拟 DOM 节点 → ANSI 字符串转换
selection.ts 35KB 终端文本选择和复制
Ansi.tsx 33KB ANSI 转义序列 React 组件化
styles.ts 21KB 终端样式系统 (颜色、边框、Flexbox)
parse-keypress.ts 24KB 终端按键事件解析
reconciler.ts 15KB React Reconciler 自定义实现
dom.ts 15KB 虚拟 DOM 树构建
renderer.ts 7KB 渲染器入口
render-to-screen.ts 8KB 屏幕级渲染协调
root.ts 4KB React Root 管理
focus.ts 5KB 焦点管理
frame.ts 4KB 帧率控制
log-update.ts 27KB 日志输出更新 (类似 log-update npm 包)
colorize.ts 7KB 颜色处理辅助
bidi.ts 4KB 双向文本 (RTL/LTR)
stringWidth.ts 7KB 字符串宽度计算 (CJK 支持)
wrap-text.ts 1KB 文本换行
hit-test.ts 4KB 点击检测
terminal.ts 8KB 终端查询 (尺寸/颜色/能力)
terminal-querier.ts 8KB 终端能力检测
termio/ 子目录 终端 IO 抽象
layout/ 子目录 Flexbox 布局引擎
hooks/ 子目录 Ink 内部 Hooks
events/ 子目录 事件系统
components/ 子目录 Ink 基础组件 (Text/Box/Newline 等)

5. 工具系统 (src/tools/)

核心文件

文件 大小 职责
Tool.ts 30KB Tool 基类和工具注册框架
tools.ts 17KB 工具清单 → 所有工具的集合导出

工具目录清单（50+ 工具）

每个工具一个子目录，包含工具实现和辅助文件：

文件操作：

  • BashTool/ — Shell 命令执行
  • PowerShellTool/ — PowerShell 命令执行
  • FileReadTool/ — 文件读取
  • FileWriteTool/ — 文件写入
  • FileEditTool/ — 精准文件编辑（基于字符串替换）
  • GlobTool/ — 文件名模式匹配
  • GrepTool/ — 文件内容正则搜索
  • NotebookEditTool/ — Jupyter Notebook 编辑

AI 调用：

  • AgentTool/ — 启动子 Agent
  • SkillTool/ — 执行技能
  • BriefTool/ — 摘要/压缩
  • AskUserQuestionTool/ — 向用户提问

任务管理：

  • TaskCreateTool/ — 创建任务
  • TaskListTool/ — 列出任务
  • TaskGetTool/ — 获取任务详情
  • TaskUpdateTool/ — 更新任务状态
  • TaskOutputTool/ — 获取任务输出
  • TaskStopTool/ — 停止任务
  • TodoWriteTool/ — 写待办列表

Web 操作：

  • WebFetchTool/ — 获取网页内容
  • WebSearchTool/ — Web 搜索
  • WebBrowserTool/ — 浏览器自动化

MCP 协议：

  • MCPTool/ — 通用 MCP 工具调用
  • McpAuthTool/ — MCP 认证
  • ListMcpResourcesTool/ — 列出 MCP 资源
  • ReadMcpResourceTool/ — 读取 MCP 资源

计划/工作区：

  • EnterPlanModeTool/ — 进入计划模式
  • ExitPlanModeTool/ — 退出计划模式
  • EnterWorktreeTool/ — 进入 Git Worktree
  • ExitWorktreeTool/ — 退出 Git Worktree

协作/通知：

  • SendMessageTool/ — 发送消息给用户
  • SendUserFileTool/ — 发送文件给用户
  • PushNotificationTool/ — 推送通知
  • TeamCreateTool/ / TeamDeleteTool/ — 团队管理
  • ListPeersTool/ — 列出同伴

调度/监控：

  • ScheduleCronTool/ — 定时任务
  • MonitorTool/ — 监控检查
  • RemoteTriggerTool/ — 远程触发
  • SleepTool/ — 休眠/等待

其他：

  • LSPTool/ — LSP 语言服务器调用
  • ToolSearchTool/ — 工具搜索
  • ConfigTool/ — 配置管理
  • CtxInspectTool/ — 上下文检查
  • DiscoverSkillsTool/ — 发现可用技能
  • SnipTool/ — 内容裁剪
  • WorkflowTool/ — 工作流执行
  • TungstenTool/ — 特殊用途工具
  • SyntheticOutputTool/ — 合成输出
  • SubscribePRTool/ — PR 订阅
  • SuggestBackgroundPRTool/ — 后台 PR 建议
  • REPLTool/ — REPL 内执行
  • ReviewArtifactTool/ — 审查产出
  • VerifyPlanExecutionTool/ — 验证计划执行
  • OverflowTestTool/ — 溢出测试
  • TerminalCaptureTool/ — 终端截图

共享模块

  • tools/shared/ — 工具间共享的函数和类型
  • tools/testing/ — 测试工具和权限测试

6. 命令系统 (src/commands/)

60+ 个斜杠命令，每个一个子目录或独立文件。

会话管理： clear, compact, context, resume, rename, session, export AI 交互： agents, advisor, brief, fast, good-claude, plan, ultraplan, review 开发工具： commit, commit-push-pr, diff, pr_comments, issue, review 配置： config, theme, color, model, output-style, statusline, keybindings, vim 集成： ide, desktop, chrome, mcp, login, logout, assistant 远程： bridge, remote-env, remoteControlServer, teleport 诊断： doctor, cost, stats, env, usage, heapdump, break-cache 协作： peers, share, feedback, btw 其他： add-dir, autofix-pr, bughunter, branch, fork, help, init, install-github-app, install-slack-app, memory, mobile, onboarding, passes, perf-issue, plugin, privacy-settings, release-notes, reload-plugins, rewind, sandbox-toggle, security-review, skills, status, stickers, subscribe-pr, summary, tag, tasks, thinkback, thinkback-play, upgrade, voice, workflows

命令实现模式

每个命令文件导出一个默认对象：

export default {
  name: 'command-name',
  description: '...',
  aliases: ['...'],
  args: [...],
  run: async (args) => { /* 命令实现 */ }
}

7. Bridge 系统 (src/bridge/)

实现远程协作/会话同步的核心。

文件 大小 职责
replBridge.ts 102KB REPL 桥接主逻辑，状态同步
bridgeMain.ts 118KB Bridge 主控制器，WebSocket 连接管理
bridgeApi.ts 18KB Bridge REST API 客户端
bridgeMessaging.ts 16KB 结构化消息序列化/反序列化
remoteBridgeCore.ts 40KB 远程桥接核心协议
initReplBridge.ts 24KB REPL 桥接初始化
replBridgeTransport.ts 15KB REPL 桥接传输层
sessionRunner.ts 18KB 会话运行器（远程执行）
bridgeUI.ts 17KB Bridge UI 状态管理
createSession.ts 12KB 远程会话创建流程
bridgeEnabled.ts 8KB Bridge 开关检测
bridgeConfig.ts 1KB Bridge 配置
bridgePermissionCallbacks.ts 1KB 远程权限回调
inboundAttachments.ts 6KB 入站附件处理
inboundMessages.ts 2KB 入站消息处理
trustedDevice.ts 7KB 设备信任管理
jwtUtils.ts 9KB JWT 令牌处理
workSecret.ts 4KB 工作密钥管理
flushGate.ts 2KB 会话刷写门控
types.ts 10KB Bridge 相关类型

8. Task 系统 (src/tasks/)

文件 大小 职责
LocalMainSessionTask.ts 15KB 主会话任务（创建 QueryEngine）
types.ts 1KB TaskState 联合类型
pillLabel.ts 2KB 任务标签 UI
stopTask.ts 2KB 任务停止逻辑

子目录

  • LocalAgentTask/ — 本地 Agent 任务
  • RemoteAgentTask/ — 远程 Agent 任务
  • LocalShellTask/ — 后台 Shell 任务
  • LocalWorkflowTask/ — 工作流任务
  • InProcessTeammateTask/ — 协程式队友任务
  • MonitorMcpTask/ — MCP 监控任务
  • DreamTask/ — 后台思考任务

9. 内存/记忆 (src/memdir/)

文件 大小 职责
memdir.ts 21KB 记忆目录核心：读取/写入 MEMORY.md 文件
memoryTypes.ts 23KB 四种记忆类型定义与验证
findRelevantMemories.ts 5KB 语义相关性匹配
memoryScan.ts 3KB 记忆文件扫描
memoryAge.ts 1KB 记忆时间戳和新鲜度
paths.ts 10KB 项目/用户记忆路径计算
teamMemPaths.ts 11KB 团队共享记忆路径
teamMemPrompts.ts 6KB 团队记忆 Prompt 构建

10. Services (src/services/)

目录/文件 职责
api/ Anthropic API 调用封装（claude.ts, errors.ts, logging.ts）
mcp/ MCP 协议实现（客户端/服务端/传输层/OAuth）
oauth/ OAuth 认证流程
lsp/ LSP 语言服务器集成
voice/ 语音服务（STT/TTS）
voiceStreamSTT.ts 实时语音转文字流
voice.ts 语音功能主入口
voiceKeyterms.ts 语音关键词检测
analytics/ 遥测和事件追踪
autoDream/ 自动 Dream 模式
compact/ 对话压缩服务
contextCollapse/ 上下文折叠
extractMemories/ 自动提取记忆
plugins/ 插件加载
settingsSync/ 设置同步
teamMemorySync/ 团队记忆同步
toolUseSummary/ 工具调用摘要
sessionTranscript/ 对话转写
remoteManagedSettings/ 远程管理配置
AgentSummary/ Agent 活动摘要
MagicDocs/ 魔法文档
PromptSuggestion/ 提示建议
SessionMemory/ 会话记忆
tips/ 使用提示
policyLimits/ 策略限制
skillSearch/ 技能搜索
mockRateLimits.ts (30KB) 速率限制模拟
rateLimitMessages.ts 速率限制提示消息
claudeAiLimits.ts Claude API 配额管理

11. UI 状态管理 (src/state/ + src/context/)

State

文件 大小 职责
AppStateStore.ts 22KB 全局状态类型定义和默认值
AppState.tsx 23KB React Provider 包装
store.ts 0.8KB createStore 工厂函数
selectors.ts 2KB 状态选择器
onChangeAppState.ts 6KB 状态变更监听
teammateViewHelpers.ts 4KB 队友视图辅助

Context

文件 大小 职责
notifications.tsx 33KB 通知系统
overlayContext.tsx 14KB 模态层管理
promptOverlayContext.tsx 12KB 提示覆盖层
voice.tsx 8KB 语音上下文
modalContext.tsx 6KB 模态框上下文
mailbox.tsx 3KB 消息邮箱
stats.tsx 22KB 统计信息上下文
QueuedMessageContext.tsx 5KB 排队消息
fpsMetrics.tsx 3KB 帧率指标

12. Hooks (src/hooks/)

80+ 个 React Hooks，核心的几个：

文件 大小 职责
useReplBridge.tsx 116KB REPL 主逻辑 Hook（最大 Hook）
useTypeahead.tsx 213KB 输入补全/建议
useVoiceIntegration.tsx 100KB 语音集成
useVoice.ts 46KB 语音录制/处理
useCanUseTool.tsx 40KB 工具权限判断
useVirtualScroll.ts 35KB 虚拟滚动
useInboxPoller.ts 35KB 邮箱轮询
useGlobalKeybindings.tsx 31KB 全局快捷键
useArrowKeyHistory.tsx 34KB 方向键历史导航
useFileSuggestions.ts 27KB 文件路径补全
useTextInput.ts 17KB 文本输入处理
useRemoteSession.ts 23KB 远程会话
usePasteHandler.ts 10KB 粘贴处理
useIDEIntegration.tsx 10KB IDE 集成
useLspPluginRecommendation.tsx 21KB LSP 插件推荐
useSSHSession.ts 8KB SSH 会话
useHistorySearch.ts 9KB 历史搜索
useDiffInIDE.ts 10KB IDE Diff
useScheduledTasks.ts 6KB 定时任务
useTasksV2.ts 9KB 任务列表 V2
useVimInput.ts 10KB Vim 输入模式

13. Utils (src/utils/)

240+ 个工具模块文件，按功能分组：

核心工具

文件 大小 职责
config.ts 65KB 配置管理（读取/写入/合并）
hooks.ts 164KB Hook 系统实现（事件钩子注册/触发）
messages.ts 198KB 消息处理与转换
sessionStorage.ts 185KB 会话持久化到磁盘
attachments.ts 131KB 附件处理（图片/PDF/文件）
teleport.tsx 177KB Teleport 功能（跨仓库会话迁移）
ansiToPng.ts 215KB ANSI 终端输出转 PNG
auth.ts 67KB 认证管理（API Key/OAuth）

Git/文件

文件 大小 职责
git.ts 31KB Git 操作封装
gitDiff.ts 16KB Git Diff 生成
fileHistory.ts 35KB 文件编辑历史追踪
file.ts 18KB 通用文件操作
ripgrep.ts 21KB 调用 ripgrep 搜索
glob.ts 4KB Glob 模式匹配
fileRead.ts 3KB 文件读取辅助

终端/UI

文件 大小 职责
Cursor.ts 48KB 终端光标管理
Shell.ts 17KB Shell 进程管理
theme.ts 27KB 主题系统
terminal.ts 4KB 终端检测
ide.ts 48KB IDE 集成
exportRenderer.tsx 16KB 对话导出渲染
staticRender.tsx 12KB 静态渲染

会话

文件 大小 职责
sessionStoragePortable.ts 26KB 跨平台会话存储
sessionRestore.ts 20KB 会话恢复
conversationRecovery.ts 21KB 对话崩溃恢复
sessionStart.ts 8KB 会话启动
sessionActivity.ts 4KB 会话活动追踪
sessionTitle.ts 4KB 会话标题生成

网络/代理

文件 大小 职责
api.ts 26KB API 请求封装
proxy.ts 13KB 代理配置
mtls.ts 4KB mTLS 双向认证

其他重要工具

文件 大小 职责
fastMode.ts 18KB 快速模式
forkedAgent.ts 25KB Agent Fork
tasks.ts 27KB 任务管理
analyzeContext.ts 44KB 上下文分析
worktree.ts 51KB Git Worktree 管理
claudemd.ts 47KB CLAUDE.md 文件解析
betas.ts 16KB Beta 功能管理
releaseNotes.ts 12KB 发布说明
commitAttribution.ts 30KB 提交归因
thinking.ts 5KB 思考模式管理
imageResizer.ts 27KB 图片尺寸调整
imagePaste.ts 14KB 图片粘贴处理
gracefulShutdown.ts 20KB 优雅退出
cleanup.ts 18KB 资源清理
json.ts 9KB JSON 解析/修复
markdownConfigLoader.ts 21KB Markdown 配置加载
editor.ts 6KB 外部编辑器调用
heapDumpService.ts 10KB 堆转储
stats.ts 34KB 统计数据
status.tsx 48KB 状态栏逻辑
statusNoticeDefinitions.tsx 30KB 状态通知定义
preflightChecks.tsx 17KB 启动前检查

14. 其他重要模块

Vim 模式 (src/vim/)

文件 大小 职责
types.ts 6KB Vim 模式类型定义
transitions.ts 12KB 模式切换状态机
operators.ts 16KB Vim 操作符 (d/c/y 等)
textObjects.ts 5KB 文本对象 (iw/aw 等)
motions.ts 1KB 运动命令 (w/b/^/$ 等)

键盘快捷键 (src/keybindings/)

文件 大小 职责
KeybindingProviderSetup.tsx 41KB 快捷键 Provider 安装
KeybindingContext.tsx 26KB 快捷键 React Context
defaultBindings.ts 11KB 默认快捷键绑定
loadUserBindings.ts 15KB 用户自定义快捷键加载
validate.ts 14KB 快捷键配置校验
schema.ts 6KB 快捷键声明模式
parser.ts 5KB 快捷键字符串解析
resolver.ts 7KB 快捷键冲突解决
match.ts 3KB 快捷键匹配

技能系统 (src/skills/)

文件 大小 职责
loadSkillsDir.ts 35KB 技能目录加载和解析
bundledSkills.ts 7KB 内置技能列表

插件系统 (src/plugins/)

文件 大小 职责
builtinPlugins.ts 5KB 内置插件

15. 常量与类型 (src/constants/ + src/types/)

常量

文件 大小 职责
prompts.ts 55KB 系统提示词，最大的常量文件
outputStyles.ts 10KB 输出样式定义
tools.ts 4KB 工具名称常量
product.ts 2KB 产品信息常量
oauth.ts 9KB OAuth 端点配置
github-app.ts 5KB GitHub App 配置
spinnerVerbs.ts 3KB Spinner 动画文案
xml.ts 3KB XML 标签常量

类型

文件 大小 职责
plugin.ts 11KB 插件接口类型
permissions.ts 13KB 权限相关类型
textInputTypes.ts 12KB 输入相关类型
command.ts 7KB 命令接口类型
hooks.ts 9KB Hook 接口类型

本文档基于 2026-06-11 源码状态生成

Reference in New Issue View Git Blame Copy Permalink