first commit

claude-code-中文Wiki/15-其他重要模块.md

@@ -0,0 +1,496 @@
+# 其他重要模块
+
+本文档介绍 Claude Code 中不属于前几章的重要模块。
+
+## 目录结构
+
+```
+src/
+├── bootstrap/        # 启动引导
+├── memdir/          # 持久化内存目录
+├── native-ts/       # 原生 TypeScript 工具
+│   ├── yoga-layout/  # Yoga 布局引擎
+│   ├── file-index/   # 文件索引
+│   └── color-diff/   # 颜色差异计算
+├── voice/           # 语音输入
+├── vim/             # Vim 模式
+├── keybindings/     # 快捷键配置
+├── moreright/       # 权限扩展 UI
+├── outputStyles/    # 输出样式管理
+└── query/           # 查询管道
+    ├── tokenBudget.ts   # Token 预算管理
+    ├── stopHooks.ts     # 停止钩子
+    └── config.ts        # 查询配置
+```
+
+## 1. 启动引导 (bootstrap/)
+
+### 1.1 引导状态 (state.ts)
+
+**文件**: `src/bootstrap/state.ts` (~56KB)
+
+管理应用启动状态和全局状态。
+
+**主要功能**:
+- 启动时间跟踪
+- 交互时间统计
+- 功能开关状态
+- 工作目录管理
+
+**关键函数**:
+
+| 函数 | 用途 |
+|------|------|
+| `getOriginalCwd()` | 获取原始工作目录 |
+| `getKairosActive()` | 获取 Kairos 状态 |
+| `flushInteractionTime()` | 刷新交互时间 |
+| `markScrollActivity()` | 标记滚动活动 |
+
+## 2. 持久化内存 (memdir/)
+
+### 2.1 内存目录核心 (memdir.ts)
+
+**文件**: `src/memdir/memdir.ts` (~21KB)
+
+管理 MEMORY.md 文件和自动记忆系统。
+
+**主要功能**:
+- 内存文件读写
+- 记忆检索
+- 入口点截断
+- 团队记忆管理
+
+**关键常量**:
+```typescript
+export const ENTRYPOINT_NAME = 'MEMORY.md'
+export const MAX_ENTRYPOINT_LINES = 200
+export const MAX_ENTRYPOINT_BYTES = 25_000
+```
+
+**截断函数**:
+```typescript
+export function truncateEntrypointContent(
+  raw: string
+): EntrypointTruncation {
+  // 1. 按行截断 (最多200行)
+  // 2. 按字节截断 (最多25KB)
+  // 3. 返回截断结果和警告信息
+}
+```
+
+### 2.2 记忆类型 (memoryTypes.ts)
+
+**文件**: `src/memdir/memoryTypes.ts` (~23KB)
+
+定义记忆相关的数据结构和常量。
+
+```typescript
+// 记忆入口
+interface MemoryEntry {
+  id: string
+  type: 'individual' | 'team'
+  keywords: string[]
+  content: string
+  createdAt: number
+  accessedAt: number
+}
+
+// 记忆类型
+const TYPES_SECTION_INDIVIDUAL = ...
+const TRUSTING_RECALL_SECTION = ...
+const WHAT_NOT_TO_SAVE_SECTION = ...
+```
+
+### 2.3 路径管理 (paths.ts)
+
+**文件**: `src/memdir/paths.ts` (~11KB)
+
+管理内存目录的路径计算。
+
+```typescript
+export function getMemoryDir(): string {
+  return join(getProjectDir(), '.claude', 'memory')
+}
+
+export function getAutoMemPath(): string {
+  return join(getMemoryDir(), 'auto', 'MEMORY.md')
+}
+```
+
+### 2.4 相关文件
+
+| 文件 | 用途 |
+|------|------|
+| `findRelevantMemories.ts` | 查找相关记忆 |
+| `memoryAge.ts` | 记忆老化计算 |
+| `memoryScan.ts` | 记忆扫描 |
+| `teamMemPaths.ts` | 团队记忆路径 |
+| `teamMemPrompts.ts` | 团队记忆提示词 |
+
+## 3. 原生 TypeScript 工具 (native-ts/)
+
+### 3.1 Yoga 布局引擎 (yoga-layout/)
+
+封装 Facebook Yoga 布局引擎。
+
+**注意**: Yoga 是用 C++ 编写的，通过原生绑定调用。
+
+```typescript
+// 获取 Yoga 计数器
+export function getYogaCounters(): {
+  ms: number
+  visited: number
+  measured: number
+  cacheHits: number
+  live: number
+}
+```
+
+### 3.2 文件索引 (file-index/)
+
+文件内容的快速索引系统。
+
+**用途**:
+- 代码搜索加速
+- 上下文构建
+- 记忆检索
+
+### 3.3 颜色差异 (color-diff/)
+
+计算颜色之间的视觉差异。
+
+```typescript
+// Delta E (CIE2000) 计算
+export function colorDistance(
+  color1: RGB,
+  color2: RGB
+): number {
+  // 返回 Delta E 值
+  // < 1: 几乎不可察觉
+  // 1-2: 轻微差异
+  // 2-5: 有感差异
+  // > 5: 明显差异
+}
+```
+
+## 4. 语音输入 (voice/)
+
+### 4.1 语音模式启用 (voiceModeEnabled.ts)
+
+**文件**: `src/voice/voiceModeEnabled.ts`
+
+检查语音输入模式是否启用。
+
+```typescript
+export function isVoiceModeEnabled(): boolean {
+  return isEnvTruthy('VOICE_MODE_ENABLED')
+}
+```
+
+## 5. Vim 模式 (vim/)
+
+### 5.1 模块结构
+
+```
+vim/
+├── motions.ts      # 动作 (h/j/k/l/w/b/e/...)
+├── operators.ts    # 操作符 (d/y/c/s/r)
+├── textObjects.ts  # 文本对象 (iw/aW/is/as/...)
+├── transitions.ts  # 状态转换
+└── types.ts       # 类型定义
+```
+
+### 5.2 核心概念
+
+**动作 (Motions)**:
+```typescript
+// 基础动作
+type Motion =
+  | { type: 'char'; direction: 'left' | 'right' }
+  | { type: 'word'; direction: 'forward' | 'backward' }
+  | { type: 'line'; direction: 'up' | 'down' }
+  | { type: 'lineStart' }
+  | { type: 'lineEnd' }
+```
+
+**操作符 (Operators)**:
+```typescript
+type Operator =
+  | { type: 'delete' }
+  | { type: 'yank' }
+  | { type: 'change' }
+  | { type: 'replace' }
+  | { type: 'swapCase' }
+```
+
+**状态机**:
+```typescript
+type VimState =
+  | 'normal'      // 普通模式
+  | 'insert'      // 插入模式
+  | 'visual'      // 可视模式
+  | 'operator'    // 操作符等待
+```
+
+### 5.3 状态转换 (transitions.ts)
+
+**文件**: `src/vim/transitions.ts` (~12KB)
+
+管理 Vim 模式的状态转换。
+
+```typescript
+// 转换函数
+function transition(
+  state: VimState,
+  input: VimInput
+): VimState
+
+// 示例: Normal -> Insert
+// i -> Insert
+// a -> Insert (after cursor)
+// o -> Insert (new line below)
+
+// 示例: Normal -> Visual
+// v -> Visual (character-wise)
+// V -> Visual (line-wise)
+```
+
+## 6. 快捷键配置 (keybindings/)
+
+### 6.1 模块结构
+
+```
+keybindings/
+├── defaultBindings.ts     # 默认绑定
+├── KeybindingContext.tsx  # 快捷键上下文
+├── KeybindingProviderSetup.tsx  # 提供者设置
+├── loadUserBindings.ts   # 加载用户绑定
+├── match.ts              # 匹配逻辑
+├── parser.ts             # 解析器
+├── resolver.ts           # 解析器
+├── schema.ts             # 模式定义
+├── useKeybinding.ts      # Hook
+├── validate.ts           # 验证
+└── template.ts           # 模板
+```
+
+### 6.2 默认绑定 (defaultBindings.ts)
+
+**文件**: `src/keybindings/defaultBindings.ts` (~12KB)
+
+定义默认键盘快捷键。
+
+```typescript
+export const DEFAULT_BINDINGS: KeyBinding[] = [
+  // 编辑
+  { key: 'ctrl+c', action: 'copy' },
+  { key: 'ctrl+v', action: 'paste' },
+  { key: 'ctrl+z', action: 'undo' },
+
+  // 导航
+  { key: 'ctrl+p', action: 'previousItem' },
+  { key: 'ctrl+n', action: 'nextItem' },
+
+  // 特定
+  { key: 'ctrl+o', action: 'expand' },
+  { key: 'escape', action: 'dismiss' },
+]
+```
+
+### 6.3 快捷键解析 (parser.ts)
+
+解析用户定义的快捷键字符串。
+
+```typescript
+// 解析 "ctrl+shift+k"
+parseKeybinding("ctrl+shift+k")
+// -> {
+//      ctrl: true,
+//      shift: true,
+//      key: 'k'
+//    }
+```
+
+### 6.4 快捷键验证 (validate.ts)
+
+验证快捷键定义的有效性。
+
+```typescript
+export function validateBinding(
+  binding: KeyBinding
+): ValidationResult {
+  // 1. 检查修饰键组合
+  // 2. 检查冲突
+  // 3. 检查保留键
+}
+```
+
+### 6.5 使用 Hook (useKeybinding.ts)
+
+React Hook 用于在组件中使用快捷键。
+
+```typescript
+function useKeybinding(
+  key: string,
+  handler: () => void,
+  options?: {
+    enabled?: boolean
+    scope?: 'global' | 'local'
+  }
+): void
+```
+
+## 7. 权限扩展 UI (moreright/)
+
+### 7.1 权限扩展组件 (useMoreRight.tsx)
+
+**文件**: `src/moreright/useMoreRight.tsx`
+
+提供额外的权限扩展 UI。
+
+```typescript
+function useMoreRight(): {
+  // 权限请求
+  requestPermission: (
+    tool: string,
+    args: unknown
+  ) => Promise<boolean>
+
+  // 权限状态
+  hasPermission: (tool: string) => boolean
+
+  // 打开权限面板
+  openPermissionPanel: () => void
+}
+```
+
+## 8. 输出样式管理 (outputStyles/)
+
+### 8.1 样式加载 (loadOutputStylesDir.ts)
+
+**文件**: `src/outputStyles/loadOutputStylesDir.ts`
+
+加载输出样式目录中的自定义样式。
+
+```typescript
+export function loadOutputStylesDir(
+  dirPath: string
+): OutputStyle[] {
+  // 1. 扫描目录
+  // 2. 解析样式文件
+  // 3. 验证样式
+  // 4. 返回样式列表
+}
+```
+
+## 9. 查询管道 (query/)
+
+### 9.1 Token 预算管理 (tokenBudget.ts)
+
+**文件**: `src/query/tokenBudget.ts`
+
+管理查询的 Token 预算。
+
+```typescript
+export interface TokenBudget {
+  total: number        // 总预算
+  used: number         // 已使用
+  reserved: number     // 预留
+  remaining: number    // 剩余
+}
+
+// 预算检查
+export function checkBudget(budget: TokenBudget): boolean {
+  return budget.remaining > 0
+}
+
+// 预算分配
+export function allocateBudget(
+  budget: TokenBudget,
+  amount: number
+): TokenBudget {
+  return {
+    ...budget,
+    used: budget.used + amount,
+    remaining: budget.total - budget.used - amount
+  }
+}
+```
+
+### 9.2 停止钩子 (stopHooks.ts)
+
+**文件**: `src/query/stopHooks.ts` (~17KB)
+
+定义查询停止时的回调钩子。
+
+```typescript
+export type StopHook = {
+  id: string
+  name: string
+  priority: number
+  execute: (context: StopContext) => Promise<void>
+}
+
+export interface StopContext {
+  queryId: string
+  reason: 'complete' | 'error' | 'user_cancel'
+  tokensUsed: number
+  duration: number
+}
+
+// 注册钩子
+export function registerStopHook(hook: StopHook): void
+
+// 执行钩子
+export async function executeStopHooks(
+  context: StopContext
+): Promise<void> {
+  const hooks = getHooks()
+    .sort((a, b) => b.priority - a.priority)
+
+  for (const hook of hooks) {
+    await hook.execute(context)
+  }
+}
+```
+
+### 9.3 查询配置 (config.ts)
+
+**文件**: `src/query/config.ts`
+
+```typescript
+export interface QueryConfig {
+  // 模型
+  model: string
+  maxTokens: number
+
+  // 预算
+  tokenBudget: number
+
+  // 停止条件
+  stopHooks: string[]
+
+  // 工具配置
+  tools: ToolConfig[]
+
+  // 上下文
+  systemPrompt?: string
+  contextFiles?: string[]
+}
+```
+
+## 10. 总结
+
+这些模块提供了 Claude Code 的重要辅助功能:
+
+| 模块 | 核心功能 |
+|------|----------|
+| bootstrap | 应用启动和状态管理 |
+| memdir | 持久化记忆系统 |
+| native-ts | 性能关键原生工具 |
+| voice | 语音输入支持 |
+| vim | Vim 模式编辑 |
+| keybindings | 快捷键系统 |
+| moreright | 权限扩展 |
+| outputStyles | 输出样式 |
+| query | 查询管道 |