// Session = 一次 CLI 会话的总上下文。
// 它不是“一轮对话”，而是从打开 CLI 到退出 CLI 的整个工作区状态。
type Session = {
  id: string;                  // 会话唯一 ID，用来关联 trace、日志、成本统计、历史消息。
  cwd: string;                 // 当前工作目录。所有文件工具默认只能在这个 workspace 内工作。
  startedAt: string;           // 会话开始时间，方便审计和恢复。
  messages: Message[];         // 已发生的对话消息，包括 system/user/assistant/tool。
  memory: MemoryState;         // 长期/项目记忆，例如用户偏好、项目结构、常用命令。
  budgets: BudgetState;        // token、上下文长度、成本等预算控制。
  permissions: PermissionState;// 当前会话已批准/拒绝的工具权限。
};

// Turn = 用户输入一次后的处理单元。
// 你可以把它理解成 Java 后端里的“一次请求 request”。
type Turn = {
  id: string;                         // 本轮请求 ID。
  sessionId: string;                  // 所属 Session，方便把一次请求挂回会话。
  userInput: string;                  // 用户这一轮的原始目标。
  selectedSkills: Skill[];            // 本轮命中的技能/规程，例如 code-review、debugging。
  contextPackage: ContextPackage;     // 搜索、Git、记忆整理出的证据包。
  trace: TraceSpan[];                 // 本轮内部链路追踪：搜索、模型、工具、测试等。
};

// Message = 发给模型或由模型/工具返回的消息。
// Agent 主循环本质上就是不断追加 Message，再重新调用模型。
type Message =
  | { role: "system"; content: string }                              // 系统规则、工具说明、技能规则。
  | { role: "user"; content: string }                                // 用户输入。
  | { role: "assistant"; content: string; toolCalls?: ToolCall[] }    // 模型文本和它想调用的工具。
  | { role: "tool"; toolCallId: string; content: string; result: ToolResult }; // 工具执行结果。

// ToolCall = 模型发起的一次工具调用请求。
// 注意 input 是 unknown，必须经过 schema 校验后才能执行。
type ToolCall = {
  id: string;       // 工具调用 ID，用来把 ToolResult 对回这次调用。
  name: string;     // 工具名，例如 read_file、edit_file、shell。
  input: unknown;   // 模型生成的参数，运行前必须 validateSchema。
};

// ToolResult = 工具执行后的标准返回。
// 它既给用户看，也会回灌给模型作为下一轮事实。
type ToolResult = {
  ok: boolean;                         // 是否成功。失败时也要返回可恢复信息。
  summary: string;                     // 一句话摘要，给模型快速理解结果。
  content?: string;                    // 详细内容，例如文件片段、diff、命令输出。
  metadata?: Record<string, unknown>;  // 结构化信息，例如行号、hash、耗时、返回数量。
};

// bootstrap = CLI 启动入口。
// 职责：把配置、工作区、工具、命令、技能、MCP、记忆都装配成 runtime。
async function bootstrap(argv: string[]): Promise<AppRuntime> {
  // 读取命令行参数、配置文件、环境变量，得到模型、MCP、权限等设置。
  const config = await loadConfig(argv);

  // 判断当前项目根目录。后续 read/edit/shell 都围绕 cwd 做边界限制。
  const cwd = await resolveWorkspace(argv, process.cwd());

  // 加载权限状态，例如本轮是否允许 shell、是否允许写文件。
  const permissions = await loadPermissionState(config);

  // 注册内置工具，例如 read_file、grep、edit_file、shell。
  const tools = await createBuiltinTools({ cwd, permissions });

  // 注册确定性命令，例如 /help、/cost、/mcp list。
  const commands = await createBuiltinCommands();

  // 这里只加载 skill 元数据或正文，后面会按任务选择是否注入。
  const skills = await loadSkills(config.skillDirs);

  // 启动配置好的 MCP server，并把它们暴露的 tools/resources 接进来。
  const mcp = await startConfiguredMcpServers(config.mcpServers);

  // 恢复历史记忆，例如项目结构、用户偏好、常用测试命令。
  const memory = await loadSessionMemory(config.sessionId);

  return {
    config,
    cwd,
    permissions,
    // 把内置工具和 MCP 工具合并到统一 registry。
    // 后续模型只看到一个工具列表，不关心工具来自内置还是 MCP。
    tools: mergeToolRegistries(tools, mcp.tools),
    commands,
    skills,
    mcp,
    memory
  };
}

// handleInput = 用户输入总入口。
// 先判断是不是 slash command；不是命令才进入模型主循环。
async function handleInput(raw: string, runtime: AppRuntime) {
  // 标准化输入：去掉多余空白、处理多行、统一换行等。
  const input = normalizeInput(raw);

  // /help、/cost、/mcp list 这类命令由程序直接执行，不交给模型。
  if (isSlashCommand(input)) {
    return runCommand(input, runtime);
  }

  // 普通自然语言任务进入 Agent Turn。
  return runAgentTurn(input, runtime);
}

// buildTurn = 把用户一句话加工成一次可执行的 Agent 请求。
// 它会选技能、读 Git 状态、取记忆、检索代码上下文。
async function buildTurn(input: string, runtime: AppRuntime): Promise<Turn> {
  // 根据用户输入选择相关 skill，例如 review/debugging/TDD。
  const selectedSkills = await selectSkills(runtime.skills, input);

  // 读取当前 Git 状态，防止覆盖用户未提交或正在修改的文件。
  const git = await readGitContext(runtime.cwd);

  // 从长期记忆里挑与当前任务相关的部分，而不是全量塞入上下文。
  const memories = await selectRelevantMemory(runtime.memory, input);

  // 搜索项目文件、测试、错误日志，整理成模型能用的证据包。
  const contextPackage = await retrieveContext({
    input,
    cwd: runtime.cwd,
    git,
    selectedSkills,
    memories
  });

  return {
    id: newId("turn"),              // 本轮唯一 ID。
    sessionId: runtime.session.id,  // 归属哪个会话。
    userInput: input,               // 保留原始目标，最终总结和 trace 都会用到。
    selectedSkills,                 // 本轮注入给模型的规程。
    contextPackage,                 // 本轮已知事实。
    trace: []                       // 后续搜索、模型调用、工具执行会逐步追加。
  };
}

// retrieveContext = 上下文检索调度器。
// 它不是简单 grep，而是“分类 -> 召回候选 -> 排序 -> 按预算读取”。
async function retrieveContext(req: RetrievalRequest): Promise<ContextPackage> {
  // 判断任务类型：bugfix、review、feature、config 等。
  // 类型不同，优先搜索的东西不同。
  const taskKind = classifyTask(req.input);

  // 召回候选文件：来自 grep、glob、Git changed files、错误栈、测试名等。
  const candidates = await generateCandidates(taskKind, req);

  // 按相关性排序。比如错误栈命中文件 > 普通关键词命中文件。
  const ranked = rankCandidates(candidates, req);

  // 按 token/文件数量预算读取片段，不把所有候选文件都塞给模型。
  const slices = await readBudgetedSlices(ranked, req.budget);

  return {
    task: req.input, // 原始任务。
    workspace: {
      cwd: req.cwd,                        // 当前项目根目录。
      branch: req.git.branch,              // 当前分支。
      changedFiles: req.git.changedFiles   // 已修改文件，模型需要优先尊重。
    },
    evidence: slices.map(toEvidenceBlock),       // 读到的关键证据。
    openQuestions: inferOpenQuestions(slices, req), // 上下文仍不足时要提醒模型。
    omitted: summarizeOmitted(ranked, slices)    // 因预算没读的候选，方便后续继续查。
  };
}

Evidence E1: src/config/modelConfig.ts:12-35
Reason: contains defaultModel and current value "claude-sonnet-4"

Evidence E2: test/config/modelConfig.test.ts:8-24
Reason: asserts default model value

// buildModelMessages = 把本轮信息拼成模型 API 所需 messages。
// 顺序很重要：系统规则 -> 技能 -> 项目上下文 -> 历史 -> 当前用户任务。
function buildModelMessages(turn: Turn, runtime: AppRuntime): Message[] {
  return [
    {
      role: "system",
      // 基础规则：模型身份、工具使用规范、安全边界、输出格式等。
      content: renderSystemPrompt(runtime.config, runtime.tools)
    },
    {
      role: "system",
      // 本轮命中的 skill，例如 code-review 的具体流程。
      content: renderSelectedSkills(turn.selectedSkills)
    },
    {
      role: "system",
      // 检索到的代码证据、Git 状态、相关记忆。
      content: renderWorkspaceContext(turn.contextPackage)
    },
    // 历史对话不能无限增长，要由预算系统选择/压缩。
    ...selectConversationHistory(runtime.session, runtime.budgets),
    {
      role: "user",
      // 用户最后一句必须放清楚，避免模型被历史任务带偏。
      content: turn.userInput
    }
  ];
}

// ModelEvent = 统一后的模型流事件。
// 不同 provider 的原始 SSE/stream 格式不同，但 QueryEngine 只处理这种统一事件。
type ModelEvent =
  | { type: "text_delta"; text: string } // 模型普通文本的一小段。
  | {
      type: "tool_call_delta";
      id: string;              // 正在拼接的工具调用 ID。
      name?: string;           // 工具名可能分片到达，所以可选。
      inputChunk?: string;     // 工具参数 JSON 的一段文本。
    }
  | { type: "tool_call_done"; call: ToolCall } // 工具名和参数都拼完整了。
  | { type: "message_done"; usage: TokenUsage } // 一次模型响应结束，带 token 用量。
  | { type: "error"; error: ModelError };        // 模型侧错误，例如超时/限流/格式错误。

// executeToolCall = 工具执行总入口。
// 任何工具，不管来自内置、插件还是 MCP，都应该经过这里。
async function executeToolCall(call: ToolCall, runtime: AppRuntime): Promise<ToolResult> {
  // 1. 先按名称找到工具定义。
  const tool = runtime.tools.get(call.name);
  if (!tool) {
    // 工具不存在也要返回给模型，让模型能改用正确工具。
    return toolError("TOOL_NOT_FOUND", `Unknown tool: ${call.name}`);
  }

  // 2. 校验模型给的参数。模型输出不可信，不能直接执行。
  const input = validateSchema(tool.inputSchema, call.input);

  // 3. 根据工具类型和参数评估风险，例如写文件、删文件、执行 shell 都更危险。
  const risk = assessToolRisk(tool, input, runtime);

  // 4. 需要审批的操作在这里拦住。权限不应该靠 prompt 约束。
  await runtime.permissions.requireApproval({
    tool: tool.name,
    input,
    risk
  });

  // 5. 真正执行工具，并记录耗时。
  const startedAt = Date.now();
  try {
    // createToolContext 会把 cwd、权限、trace、日志等运行时能力传给工具。
    const result = await tool.run(input, createToolContext(runtime));
    return attachToolMetadata(result, { durationMs: Date.now() - startedAt });
  } catch (error) {
    // 把各种异常统一成 ToolResult，方便模型下一步恢复。
    return normalizeToolError(error);
  }
}

// EditResult = 编辑工具成功后的结构化返回。
// 注意这里不只返回 ok，还要返回 diff、hash、验证信息。
type EditResult = {
  ok: true;              // 本次编辑成功。
  path: string;          // 被修改的文件路径。
  diff: string;          // 程序生成的 diff，给用户审查，也给模型继续推理。
  oldHash: string;       // 写入前文件 hash，用于审计和 stale 检查。
  newHash: string;       // 写入后文件 hash，用于确认落盘版本。
  changedLines: number;  // 改动行数，可用于风险评分。
  verification: {
    readBack: true;              // 写入后是否重新读回文件。
    expectedTextFound: boolean;  // 新内容是否确实出现在文件里。
  };
};

After editing code, run the smallest relevant verification command.
If no test command is known, inspect package scripts or README first.

// VerificationResult = 一次验证命令的结构化结果。
// 不要只保存一大坨命令输出，否则模型很难判断下一步。
type VerificationResult = {
  command: string;          // 实际运行的命令，例如 npm test -- modelConfig。
  exitCode: number;         // 进程退出码，0 通常代表成功。
  durationMs: number;       // 耗时，用于判断卡住或性能问题。
  passed: boolean;          // 对 exitCode 的业务化判断。
  importantOutput: string;  // 截断后的关键输出：失败断言、错误栈、通过摘要。
};

已把默认模型配置更新为 claude-sonnet-4-6，并同步更新对应测试断言。
验证：npm test -- modelConfig 通过。
注意：没有跑全量测试，因为本次只触及配置默认值和相关单测。

配置和测试已修改，但验证失败在 authService.test.ts，错误与本次配置无直接关系。
我没有继续扩大修改范围。下一步建议先确认该失败是否是已有问题。

// TraceSpan = 链路追踪中的一个节点。
// 类似 OpenTelemetry span，用来复盘“这一步为什么发生、花了多久、是否失败”。
type TraceSpan = {
  id: string;                         // 当前 span ID。
  parentId?: string;                  // 父 span ID，用来组成树。
  name: string;                       // span 名称，例如 context.retrieve、tool.edit_file。
  startedAt: string;                  // 开始时间。
  endedAt?: string;                   // 结束时间；没有结束说明可能还在运行或异常中断。
  attributes: Record<string, unknown>;// 结构化细节，例如 path、toolName、tokenUsage。
  status: "ok" | "error";             // 这一步成功还是失败。
};

turn.run
  skill.select
  context.retrieve
    grep.defaultModel
    read.src/config/modelConfig.ts
    read.test/config/modelConfig.test.ts
  model.call
  tool.edit_file
    permission.diff_preview
    fs.atomic_write
  tool.shell
    npm test -- modelConfig
  response.render

对话入口
+ 上下文检索
+ 模型推理
+ 工具执行
+ 权限审计
+ 文件事务
+ 验证反馈
+ 记忆压缩
+ 可观测性