文件与 Git

Captain Who 中有三种容易混淆的文件操作：右侧栏“文件”用于只读查看，Agent 文件工具用于分析或修改，右侧栏“审阅”用于检查和管理版本库变更。

添加项目文件夹

在新对话的项目选择器中选择“新建项目”，或进入“设置 → 环境 → 添加项目”，再使用系统文件夹选择器授权一个目录。一个项目可包含 1 至 32 个源文件夹，其中恰好一个是主要文件夹；重复或彼此嵌套的目录不能同时加入。

创建后，可从项目的“编辑项目”添加或移除文件夹，并重新指定主要文件夹。主要文件夹是项目默认工作目录；多文件夹项目中的文件、终端和 Git 审阅会在界面提供选择时标明各自的源文件夹。不要因为它们位于同一个项目就假定它们属于同一 Git 仓库。

项目建立后：

默认权限把读写范围限制在当前项目的已选文件夹。
右侧栏“文件”和“审阅”绑定这个项目；多文件夹时应核对当前选中的源文件夹或仓库。
右侧栏“终端”默认从主要文件夹启动。
项目内 .agents/skills/ 中的合法 Skill 可以被发现。

项目文件夹根部的 AGENTS.md（或 AGENTS.override.md）会被自动提供给 Agent，作为该工作区的约定；见 AGENTS.md 项目约定。

在输入框添加附件

可以通过输入框的附件菜单、拖入文件或粘贴添加附件。普通文件显示为单行圆角卡片，使用与文件树相同的分类图标；连续文件每列最多四个，更多文件横向排列。图片保留缩略图，点击可查看较大预览；文件名悬停显示完整名称和大小。

附件导入时显示进度，可以取消；失败的附件可以重试或移除。导入未完成或失败尚未处理时，发送按钮不可用。切换聊天会取消仍在导入的附件，避免它们进入另一个聊天。

普通附件不再受原有单文件 8 MiB 限制。导入完成后，Captain Who 保存独立文件副本，草稿和排队消息保留引用；随后移动或删除外部原文件不会影响已导入的附件。可用磁盘空间仍会影响导入，失败会显示提示。

大文件不会自动整份进入模型上下文。模型先获得文件名称、大小和读取引用，再按需要读取片段或交给已启用的工具。PDF 与 Office 文件的解析继续取决于相应能力和 Skill。

图片附件支持 PNG、JPEG、GIF 和 WebP。原文件会保留，缩略图、放大预览和模型视觉输入使用有大小预算的派生图片。超过像素或解码预算的图片会提示错误，可先缩小或裁剪再添加。界面放大预览不等于原图分辨率。

用“文件”查看内容

打开右侧栏，选择“新建面板 → 文件”。
在目录树中展开文件夹，或输入名称筛选。
点击文件打开预览；再次打开同一临时页可以将它固定为独立标签。
通过“更多文件操作”切换换行、复制文件地址或在系统文件夹中显示。

当前预览支持：

UTF-8 和常见 UTF-16 文本、源代码。
Markdown 源代码和渲染预览。
AVIF、BMP、GIF、JPEG、PNG、SVG、WebP 图片。
非加密 PDF 的分页预览。

关键限制：文本最多读取约 1 MiB、最多渲染 5,000 行；图片最多 12 MiB；PDF 最多 32 MiB。过大的内容会显示明确提示。符号链接可以出现在目录树中，但不能展开、预览或用来跳出项目边界。

Word、Excel 和 PowerPoint 文件不能在“文件”中预览。可以在外部应用中打开，或交给对应 Office Skill。

让 Agent 读取或修改文件

在任务中直接描述目标和范围，例如：

阅读 src/config，说明配置的加载顺序。只读，不要修改。

或：

只修改 README.md，增加安装前置条件；保留现有结构，修改后给出摘要。

Agent 可以列出、搜索和读取文件，并通过统一 FileChange 创建、更新或删除。更新与删除必须绑定刚刚读取到的文件版本；如果文件在读取后被终端、编辑器或其他 Agent 改动，提交会以冲突结束并要求重新读取。模型写出的路径本身不会获得权限。

默认权限下，FileChange 会先显示审批卡。卡片提供有界的分栏 Diff；大 Diff 分页加载，完整预览准备好之前不能批准。选择“本轮后续创建/更新无需审批”只影响当前 Run，删除仍需逐次确认，所有路径和版本检查仍会执行。

对于大文件或超长工具结果，Agent 可能只看到摘要、首尾片段或分页结果。需要精确结论时，让它说明读取范围和遗漏部分。

修改完成后，时间线中的 FileChange 卡可以从持久审计记录重新加载 Diff；轮次结束后的独立修改摘要卡可以跳到“上一轮”Git 审阅。FileChange 展示的是已执行修改的审计视图，仓库当前状态仍以“未暂存/已暂存”范围为准。

用“审阅”检查 Git 变更

“审阅”只在当前项目被识别为 Git 仓库时可用。打开“新建面板 → 审阅”，选择范围：

未暂存：工作区相对暂存区的变化。
已暂存：暂存区相对 HEAD 的变化。
上一轮：最近一次 Agent 轮次前后记录的变化，只读。
未提交：当前工作区和暂存区中尚未提交的变化。
已提交：选择当前分支上的一个本地提交，只读查看该提交引入的变化。
分支：选择本地或远程基准分支，只读查看当前分支相对该基准的变化。

多文件夹项目中，先从审阅面板选择需要查看的仓库；界面提供“所有仓库”时，它仅用于汇总可审阅的来源，不会把多个仓库变成一个 Git 仓库。面板支持统一/分栏差异、自动换行、文件搜索、展开差异以及按需加载完整文件。最多展示 500 个变更文件；二进制、过大或冲突文件会保留条目并显示不能渲染的原因。

暂存、取消暂存和还原

在“未暂存”范围可以暂存文件。
在“已暂存”范围可以取消暂存。
还原操作只针对未暂存变化，并会弹出确认。

“还原文件”会永久丢弃跟踪文件的未暂存修改，或删除对应的未跟踪文件，无法撤销。执行前应核对路径，必要时先在外部工具中备份。

“审阅”使用短期一致性快照。如果项目被终端、Agent 或其他编辑器改变，旧快照会失效，界面需要刷新；不要根据旧差异重复执行操作。

当前“审阅”可以选择提交或基准分支作为只读审阅目标，但不提供 commit、创建/切换 branch、merge、pull 或 push 按钮。可以让 Agent 使用受管命令，或在右侧栏“终端”中手动操作，但两者都应遵循你的仓库流程。

“文件”“终端”和 Agent 命令的区别

能力	谁操作	是否进入 Agent 历史	主要用途
文件	用户	否	安全只读预览
终端	用户	否	交互式 shell
Agent 文件工具	Agent	是	搜索、读取和受审批修改
Agent 命令	Agent	是	非交互构建、测试和处理任务

Agent 不能隐式接管右侧栏“终端”。长时间运行的 Agent 命令由单独的受管会话跟踪，应用重启后也不能重新附着原来的操作系统进程。