CSC 的工作原理

了解智能体循环、内置工具，以及 CSC 如何与你的项目交互。

CSC 是一个运行在终端中的智能体助手。虽然它擅长编码，但它可以帮助你完成从命令行能做的任何事情：编写文档、运行构建、搜索文件、研究主题等等。

本指南涵盖了核心架构、内置功能以及高效使用 CSC 的技巧。如需分步演练，请参阅常见工作流。如需了解技能、MCP 和钩子等扩展功能，请参阅扩展 CSC。

智能体循环

当你给 CSC一个任务时，它会通过三个阶段工作：收集上下文、采取行动和验证结果。这些阶段相互交融。CSC 在整个过程中使用工具，无论是搜索文件来理解你的代码、编辑来做出更改，还是运行测试来检查其工作。

循环会根据你的请求进行调整。关于代码库的问题可能只需要收集上下文。一个 bug 修复会反复循环所有三个阶段。一个重构可能涉及大量验证。CSC 根据从上一步学到的内容决定每一步需要什么，将数十个操作链接在一起，并在过程中不断纠偏。

你也是这个循环的一部分。你可以随时中断，将 CSC 引向不同的方向，提供额外的上下文，或要求它尝试不同的方法。CSC 自主工作，但始终对你的输入保持响应。

智能体循环由两个组件驱动：用于推理的模型和用于行动的工具。CSC 作为 LLM周围的智能体框架：它提供工具、上下文管理和执行环境，将语言模型转变为一个强大的编码智能体。

工具

工具使 CSC 成为智能体。没有工具，LLM只能用文本回应。有了工具，LLM可以行动：读取你的代码、编辑文件、运行命令、搜索网络以及与外部服务交互。每次工具使用都会返回信息，反馈到循环中，为 LLM 的下一步决策提供依据。

内置工具通常分为五类，每类代表一种不同的能力。

类别	CSC 能做什么
文件操作	读取文件、编辑代码、创建新文件、重命名和重新组织
搜索	按模式查找文件、用正则表达式搜索内容、探索代码库
执行	运行 shell 命令、启动服务器、运行测试、使用 git
网络	搜索网络、获取文档、查找错误信息
代码智能	编辑后查看类型错误和警告、跳转到定义、查找引用（需要代码智能插件）

这些是主要能力。CSC 还有用于生成子智能体、向你提问和其他编排任务的工具。有关完整列表，请参阅 CSC 可用工具。

CSC 根据你的提示和沿途学到的内容选择使用哪些工具。当你说"修复失败的测试"时，CSC 可能会：

1. 运行测试套件查看哪些失败了
2. 阅读错误输出
3. 搜索相关的源文件
4. 阅读这些文件以理解代码
5. 编辑文件来修复问题
6. 再次运行测试来验证

每次工具使用都给 CSC 提供新信息，为下一步提供依据。这就是智能体循环的实际运作。

扩展基础能力： 内置工具是基础。你可以用技能扩展 CSC 的知识，用 MCP 连接外部服务，用钩子自动化工作流，用子智能体委派任务。这些扩展在核心智能体循环之上形成一层。

CSC 可以访问什么

当你在目录中运行 csc 时，CSC 可以访问：

• 你的项目。 目录和子目录中的文件，以及经你许可的其他位置的文件。
• 你的终端。 你能运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果你能从命令行做到，CSC 也能。
• 你的 git 状态。 当前分支、未提交的更改和最近的提交历史。
• 你的 AGENTS.md。 一个 markdown 文件，用于存储项目特定的指令、约定和 CSC 每次会话都应知道的上下文。
• 自动记忆。 CSC 在你工作时自动保存的学习内容，如项目模式和你的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每次会话开始时加载。
• 你配置的扩展。 用于外部服务的 MCP 服务器、用于工作流的技能、用于委派工作的子智能体，以及用于浏览器交互的 Chrome 中的 CSC 。

因为 CSC 可以看到你的整个项目，它可以跨项目工作。当你要求 CSC "修复认证 bug"时，它会搜索相关文件、阅读多个文件以理解上下文、在它们之间进行协调编辑、运行测试来验证修复，并根据你的要求提交更改。这与只能看到当前文件的内联代码助手不同。

使用会话

CSC 在你工作时将对话保存在本地。每条消息、工具使用和结果都写入 ~/.costrict/projects/ 下的纯文本 JSONL 文件中，这使得回滚更改、恢复和分叉会话成为可能。在 CSC 进行代码更改之前，它还会对受影响的文件进行快照，以便你在需要时可以回滚。有关路径、保留策略以及如何清除此数据，请参阅 ~/.costrict 中的应用数据。

会话是独立的。 每个新会话以全新的上下文窗口开始，没有之前会话的对话历史。CSC 可以使用自动记忆在会话之间持久化学习内容，你可以在 AGENTS.md 中添加自己的持久指令。

跨分支工作

每个 CSC 对话都是与你当前目录关联的会话。当你恢复时，你只能看到该目录的会话。

CSC 可以看到你当前分支的文件。当你切换分支时，CSC 会看到新分支的文件，但你的对话历史保持不变。CSC 记得你讨论的内容，即使在切换之后。

由于会话与目录绑定，你可以通过使用 git worktrees 来运行并行的 CSC 会话，这会为各个分支创建单独的目录。

恢复或分叉会话

当你使用 csc --continue 或 csc --resume 恢复会话时，你从上次离开的地方继续，使用相同的会话 ID。新消息追加到现有对话中。你的完整对话历史会被恢复，但会话范围的权限不会。你需要重新批准这些权限。

要分叉并尝试不同的方法而不影响原始会话，请使用 --fork-session 标志：

csc --continue --fork-session

这会创建一个新的会话 ID，同时保留到该点的对话历史。原始会话保持不变。与恢复一样，分叉的会话不继承会话范围的权限。

多个终端中的同一会话：如果你在多个终端中恢复同一会话，两个终端都会写入同一个会话文件。来自两个终端的消息会交错在一起，就像两个人在同一本笔记本上写字。不会损坏任何东西，但对话会变得混乱。每个终端在会话期间只能看到自己的消息，但如果你稍后恢复该会话，你会看到所有交错的消息。对于从同一起点进行的并行工作，请使用 --fork-session 为每个终端提供自己独立的会话。

上下文窗口

CSC 的上下文窗口容纳你的对话历史、文件内容、命令输出、AGENTS.md、自动记忆、加载的技能和系统指令。随着你的工作，上下文会被填满。CSC 会自动压缩，但对话早期的指令可能会丢失。将持久规则放在 AGENTS.md 中，并运行 /context 查看什么占用了空间。

有关什么加载以及何时加载的交互式演练，请参阅探索上下文窗口。

当上下文填满时

CSC 在你接近限制时自动管理上下文。它首先清除较旧的工具输出，然后在需要时总结对话。你的请求和关键代码片段会被保留；对话早期的详细指令可能会丢失。将持久规则放在 AGENTS.md 中，而不是依赖对话历史。

要控制在压缩期间保留什么，请在 AGENTS.md 中添加"压缩指令"部分，或使用带焦点的 /compact 运行（如 /compact focus on the API changes）。

如果单个文件或工具输出太大，以至于每次总结后上下文立即重新填满，CSC 会在几次尝试后停止自动压缩并显示错误，而不是循环。有关恢复步骤，请参阅自动压缩因抖动错误而停止。

运行 /context 查看什么占用了空间。MCP 工具定义默认延迟，通过工具搜索按需加载，因此只有工具名称占用上下文，直到 CSC 使用特定工具。运行 /mcp 检查每个服务器的成本。

用skills和subagents 管理上下文

除了压缩，你还可以使用其他功能来控制什么加载到上下文中。

skills按需加载。CSC 在会话开始时看到技能描述，但完整内容只在skills被使用时加载。对于你手动调用的技能，设置 disable-model-invocation: true 以将描述排除在上下文之外，直到你需要它们。

subagents 拥有自己独立的上下文，与你的主对话完全分离。它们的工作不会膨胀你的上下文。完成后，它们返回一个摘要。这种隔离就是subagents 对长会话有帮助的原因。

通过检查点和权限保持安全

CSC 有两个安全机制：检查点让你撤销文件更改，权限控制 CSC 未经询问可以做什么。

用检查点撤销更改

每次文件编辑都是可逆的。 在 CSC 编辑任何文件之前，它会快照当前内容。如果出现问题，按两次 Esc 回滚到之前的状态，或要求 CSC 撤销。

检查点是会话本地的，与 git 分离。它们只覆盖文件更改。影响远程系统的操作（数据库、API、部署）无法设置检查点，这就是为什么 CSC 在运行具有外部副作用的命令之前会询问。

控制 CSC 可以做什么

按 Shift+Tab 循环切换权限模式：

• 默认：CSC 在文件编辑和 shell 命令之前询问
• 自动接受编辑：CSC 无需询问即可编辑文件和运行常见的文件系统命令如 mkdir 和 mv，仍然询问其他命令
• 计划模式：CSC 仅使用只读工具，创建一个你可以在执行前批准的计划
• 自动模式：CSC 通过后台安全检查评估所有操作。目前为研究预览版

你还可以在 .costrict/settings.json 中允许特定命令，这样 CSC 每次就不会询问。这对于像 npm test 或 git status 这样的可信命令很有用。设置可以从组织级策略到个人偏好进行范围限定。有关详细信息，请参阅权限。

---

高效使用 CSC

这些技巧帮助你从 CSC 获得更好的结果。

向 CSC 寻求帮助

CSC 可以教你如何使用它。问诸如"如何设置钩子？"或"构建我的 AGENTS.md 的最佳方式是什么？"之类的问题，CSC 会解释。

内置命令也会引导你完成设置：

• /init 引导你为项目创建 AGENTS.md
• /agents 帮助你配置自定义子智能体
• /doctor 诊断你安装中的常见问题

这是对话

CSC 是对话式的。你不需要完美的提示。从你想要的开始，然后逐步完善：

Fix the login bug

[CSC 调查，尝试了一些东西]

That's not quite right. The issue is in the session handling.

[CSC 调整方法]

当第一次尝试不正确时，你不需要重新开始。你迭代。

中断和引导

你可以随时中断 CSC 。如果它走错了方向，只需输入你的纠正并按 Enter。CSC 会停止正在做的事情并根据你的输入调整方法。你不必等它完成或重新开始。

前期要具体

你的初始提示越精确，需要的纠正就越少。引用特定文件，提及约束，并指出示例模式。

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

模糊的提示也能用，但你会花更多时间来引导。像上面这样的具体提示通常在第一次尝试就能成功。

给 CSC 可以验证的东西

当 CSC 能检查自己的工作时，它表现得更好。包含测试用例，粘贴预期 UI 的截图，或定义你想要的输出。

Implement validateEmail. Test cases: 'user@example.com' → true,
'invalid' → false, 'user@.com' → false. Run the tests after.

对于视觉工作，粘贴设计的截图并要求 CSC 将其实现与截图进行比较。

先探索再实现

对于复杂问题，将研究与编码分开。首先使用计划模式（按两次 Shift+Tab）分析代码库：

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

审查计划，通过对话完善它，然后让 CSC 实现。这种两阶段方法比直接跳到代码产生更好的结果。

委派，而不是指挥

想象向一位有能力的同事委派任务。给出上下文和方向，然后信任 CSC 来处理细节：

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?

你不需要指定要读取哪些文件或运行什么命令。CSC 会自己弄清楚。