用户手册
配置 API key，选择权限模式，然后从侧边栏使用 DeepSeek，并明确控制每一项工作区操作。
开始使用
- 生成恢复检查点保存在 history/<chat-id>/checkpoint.json，与会话和草稿放在一起。启动时仅在 generation-checkpoints 存在时执行迁移，保留冲突目标，继续已复制文件的迁移，并仅在旧目录为空时删除它。生成完成或删除后清理检查点，不删除会话或草稿。
- 草稿保存在 ~/.ycrasy-agent/history/<chat-id>/draft/，首条消息创建会话前保存在 history/new-chat-draft/。每个文件夹包含 draft.json 和原始图像文件。发送后移除已提交草稿；分配会话 ID 后移除新聊天临时文件夹，同时保留新编辑的草稿。空草稿及已删除会话不保留草稿文件夹。旧 Webview 草稿在打开时迁移。
- 为每个会话和新聊天分别保留未发送草稿，切换时恢复文本、文件引用和图像附件。粘贴图像和外部文件快照按聊天保存在本地，重新加载窗口后仍可恢复。恢复原始图像文件，仅在发送消息时上传到 DeepSeek。已保存的用户消息显示后才清除对应草稿，删除会话仅移除对应草稿。
- 从 Activity Bar 打开 YCraSy DeepSeek Agent，并在 Settings 中输入 API key。凭据按规范化 API 来源存储在 VS Code Secret Storage 中；重新打开 Settings 时只会显示遮罩占位符预览。
- 选择 thinking mode、reasoning effort、输出预留和并发上限。聊天使用 DeepSeek V4.1 Flash，具备 1M Token 总上下文和 384K 最大输出；输出预留默认为 384,000 个 Token。默认并发数为 8，可设置为 1 到 16。
- 输入 ./ 可自动补全安全的工作区路径；始终拒绝 ../ 父目录遍历。多根工作区路径以稳定别名开头，例如 ./frontend/src/App.tsx。
- 使用统一的 + 操作或资源管理器/编辑器命令添加上下文。普通外部文件会成为受限只读快照；图像会在验证二进制签名后上传到 DeepSeek。
- 使用 Stop generation 可取消当前请求和终端进程树。已提交提示、部分 timeline 和已完成工具结果会作为 cancelled 轮次保留；已发生的外部副作用不会回滚。
图像与视觉
- analyze_images 仅供 DeepSeek V4 Pro 使用，由其委托 Flash 分析图像。Flash 无法访问该工具，而是直接读取视觉上下文中已有的图像。本地截图编号本身不包含图像内容；新本地截图目前尚不会自动加入 Flash 的上下文。
- 同一选择器支持上下文文件以及最多八张 JPEG、PNG、GIF 或 WebP 图像。也可使用 Ctrl+V 或 Cmd+V 粘贴；剪贴板图像限制为 16 MiB，选择器图像遵循 DeepSeek 的 64 MiB 限制。
- DeepSeek V4.1 Flash 直接接收 DeepSeek file ID，因此当前提示中的图像与文本在同一次生成中读取。
- 提供商失败会原样呈现：扩展不会静默重试、删除已发送的图像引用，也不会改写模型名称来让失败的图像请求看似成功。
- 上传使用 DeepSeek Files API、purpose user_data 和 30 天到期时间。Base64 仅用于临时剪贴板 IPC，绝不会进入历史记录或提供商消息。
- 移除草稿图像会尝试删除本地和远程资源。永久删除会话时，只有撤销窗口结束后才清理图像。
- 点击附件图像（输入框缩略图或已发送消息中的图像）会打开全窗口查看器。默认将图像适配窗口、保持宽高比，并支持拖动放大后的图像平移而不是压缩变形。提供缩小、适配百分比（点击即适配）、放大和关闭，同时响应 Escape、背景点击以及 +、-、0 键。
并发生成和队列
- 每个会话同一时间只运行一个生成任务。该会话中的其他提示会按提交顺序排队。
- 不同会话可以并发生成，直到达到配置的全局上限。
- 响应进行期间只显示一个按钮：草稿为空时为 Stop，有内容时为 Guide。Enter 会重启传输并按新指导继续同一任务；按住 Ctrl 时按钮变为 Queue，Ctrl+Enter 会将独立草稿排到当前响应之后；Shift+Enter 插入换行。
- 切换会话或重新创建 webview 不会让流式或工具事件串到其他任务；每个事件都绑定到其生成任务和会话。
- 如果 VS Code 关闭，部分输出会恢复为 interrupted，未完成的工具会变为 cancelled，排队提示会在下次激活时作为可恢复草稿提供。
权限和工具状态
- default 会确认每个工具；auto-approve 可在任何位置自动执行常规操作，并确认提权或关键操作；full-access 可在任何位置自动执行常规和提权操作，只确认可能导致计算机无法使用或造成大范围不可逆损失的关键操作。
- 不再提供逐工具权限矩阵。关闭 Web 搜索开关后，模型请求中不会包含 search_web 和 read_web。工作区绑定和 VS Code Workspace Trust 仍然生效。
- 工具调用依次经过 awaiting confirmation、running，并最终进入 completed、rejected、cancelled 或 error 中的一种状态。
- 扩展宿主会先确认执行或拒绝操作，然后 webview 才会提交可见状态。
- 同一轮内的工具调用按顺序执行。相同调用会被跳过，直到工作区修改使合理的重复调用变得有用。工具循环没有可配置的轮次或每块调用上限；独立审查器会在完成 20 轮后检查进度，此后每五轮再次检查，且不会禁用工具。
- 只读工具可以跨并发会话运行，而文件和终端变更在同一工作区内按顺序执行。
活动和文件结果
- 相邻的推理和工具调用默认折叠在 Activity 面板中。展开后可检查各个推理步骤、工具状态、参数和相关结果。
- 会话用量会显示在权限选择器旁的紧凑弹出面板中；切换模型后还会按模型汇总。如果部分 DeepSeek 请求省略用量，已报告的请求仍会生成明确标记的最低费用。
- 成功的 read_file 不会在聊天中重复文件正文。可使用 Open file 在编辑器中查看；读取失败时仍会显示诊断结果。
- 完成的 create_file、edit_file 和 apply_patch 在拥有完整 diff 时会提供 View change。它会打开该次工具执行记录的前后内容，不受之后工作树变更影响。
- 完成的轮次以已编辑文件摘要收尾：每个被写入的文件一行，包含增删行数，超过三个文件时显示 Show N more files，Review 可打开该轮次的全部改动。宿主会在本次会话中记录精确的前后内容，因此即使工具结果中的 diff 为模型上下文做了限制，较大的改动仍可完整打开。撤销已应用的改动尚未实现。
- 使用费用可在 Settings → Usage & cost 中按美元或人民币显示。每种货币都使用 DeepSeek 官方公布的价格表，因此不会凭空换算汇率；持久化的合计仍以 USD 为准，仅在显示时重新计价。
长会话
- 较长的会话不会整体挂载。打开时仅渲染最新的 40 条消息，外加用户从磁盘加载的每个历史分页；Show N earlier messages 会再从内存中显示 40 条，并保持正在阅读的消息位置不动而不是跳动。
- 工具调用对账、用量合计、草稿持久化与历史分页仍在完整加载的会话上运行；只有渲染列表被限制，记忆化行让草稿输入保持流畅。
工作区概览
- list_workspace 一次调用即可将整个项目绘制为缩进树，因此新会话无需再串联 list_directory。隐藏条目同样显示，内容过多的文件夹以 ... 概括，而不是倾倒或静默排除。
- 可选的 path 参数可将树限制在某个工作区文件夹内。它最多读取 300 个文件夹，并在 400 个条目或 48 KiB 后停止；当文件夹包含超过 25 个条目（工作区根目录为 60 个）或其子树超出剩余行数预算时，将以概括代替列出。
工作区内容搜索
- search_content 通过 VS Code 工作区文件系统执行不区分大小写的字面文本搜索；它不会运行 shell，也不会将查询解释为正则表达式。查询必须包含文本，且最多为 4,096 个字符。
- 可选的 filePattern 是工作区相对 glob，例如 *.ts 或 src/**/*.md。其默认值为 **/*，最多为 1,024 个字符，并拒绝绝对路径和父目录遍历。
- 敏感路径、二进制文件和大于 2 MiB 的文件会被跳过。敏感文件在读取内容前就会被过滤。
- 每次搜索最多检查 10,000 个文件并返回 50 个匹配项。结果行和总输出均有上限，响应还会报告已扫描文件数、已跳过文件数以及是否发生截断。
- 请求取消时搜索会停止，并在 15 秒后超时。
可选 Beta 功能
- 设置 → API中的 DeepSeek Beta 功能默认关闭。开启后，代理可使用 complete_code 执行助手前缀补全或中间填充（FIM），并启用严格函数模式。在思考模式下，聊天前缀补全也支持调用方提供的推理前缀。
- 可要求代理用 FIM 补全缺失的函数体，或续写指定的助手前缀。工具仅返回文本，不修改文件；编辑仍须通过正常权限检查。代理工具仍按需调用。编辑器建议和聊天建议可分别开启，以灰色显示：Tab 接受，Escape 关闭。编辑器使用 FIM，在输入停顿后请求。聊天建议仅通过上下文指示器旁的建议消息按钮请求，可为空草稿生成消息或续写现有草稿，再次点击取消；输入时不会请求。
- 请求保留配置的 API 来源和凭据，并使用 Beta 路径。默认最多输出 1,024 token，上限为 4,096 或更低的配置值，用量列入 Beta 代码补全。关闭后阻止新的 Beta 请求，后续工具轮次使用稳定聊天端点；正在进行的请求可结束。开启后，新生成任务可使用补全工具。
- 在代码编辑器中右键 → YCraSy DeepSeek Agent → 补全或重构。优先使用选区；空行对应整个文件，否则使用包含光标的最小符号，无符号时回退到语句或行。查看差异后选择应用或放弃。支持撤销，且不会覆盖已变更的文档。补全需要 Beta；重构使用稳定 API。
- 编辑器建议发送有界的附近代码。聊天建议发送草稿及简短项目元数据（文件夹、顶层条目名称和 package.json 名称/描述），不包含源代码或聊天历史，仅在点击聊天按钮时请求。建议关闭思考，输出上限分别为 256/96 Token，并支持取消和缓存。产生 API 费用；状态栏 DeepSeek 提示单独显示此类用量。需要信任工作区并排除敏感文件名。关闭 Beta 会停止此类请求。
隐私
- 设置 → 常规 → 隐私默认启用尽力元数据最小化：自动运行时说明省略工作区绝对根路径，不发送可选用户标识和图像文件名，时间使用 UTC，不附加本地时区名称。保留必要的相对路径和工具引用。消息、代码、工具输出、图像内容和内嵌元数据以及现有历史不会被匿名化。不保证匿名性或 GDPR 合规。不收集使用遥测；API 提供商仍接收回答所需的数据和连接来源 IP。
网页界面截图
- 网页读取和截图使用扩展宿主上安装的 Chrome、Chromium、Edge、Brave 或 Vivaldi。扩展通过临时配置启动独立的无头进程，不打开个人浏览器会话。截图权限仍由设置 → 工具控制。
- 未找到兼容浏览器时，从 Google Chrome for Testing 下载 Chrome Headless Shell，保存到 VS Code 扩展全局存储中，不包含在 VSIX 内。首次安装需要网络及数百 MB 可用磁盘空间。使用期间每天最多检查一次稳定版更新；更新失败时保留已安装版本。保留当前及上一版本，不更新用户自行安装的浏览器。
- 远程工作区中的浏览器运行在扩展宿主上。Linux 需要 Chromium 共享库及可用沙箱；扩展不安装系统软件包，也不禁用沙箱。受管理下载支持 Windows x86/x64、macOS Intel/Apple Silicon 和 Linux x64。Linux ARM 需要系统 Chromium 浏览器。
原生窗口截图
- Wayland 窗口截图在保存 PNG 前应用 PipeWire 提供的有效像素矩形，去除小窗口周围的合成器填充，不缩放、不裁掉应用本身的黑色内容。无效矩形会被拒绝。除 pipewiresrc、videoconvert、pngenc 外，还需要 GStreamer videocrop 插件；Ubuntu 的 gstreamer1.0-plugins-good 已包含它。
- 在 Wayland 下，每次窗口或调试截图都会打开系统选择器。请选择要测试的应用窗口。扩展通过 XDG ScreenCast/PipeWire 只读取一张 PNG，然后立即关闭共享会话。门户无法按标题或 PID 选择或验证窗口，因此结果只标记为用户所选窗口，不声称已验证其身份。选择取消或失败时绝不回退到整个显示器；全屏截图仍需明确确认。
- 扩展所在主机需要支持窗口的 ScreenCast v3+ 门户、带 PyGObject/Gio/GStreamer 的 /usr/bin/python3，以及 pipewiresrc、videoconvert 和 pngenc 插件。Ubuntu 对应的软件包为 python3-gi、gir1.2-gstreamer-1.0、gstreamer1.0-pipewire、gstreamer1.0-plugins-base 和 gstreamer1.0-plugins-good。不会自动下载或安装依赖。X11、Windows 和 macOS 保留各平台的截图后端。门户选择不会用于自动截图。
网页搜索
- 网页搜索使用配置来源对应 API 凭据调用 DeepSeek Search。网页读取和网页截图使用已安装的 Chromium 浏览器；未找到时自动下载并更新 Chrome Headless Shell。不打开个人浏览器配置文件。
- 搜索面向软件开发，优先参考与项目版本匹配的官方文档、上游仓库和相关问题讨论。默认请求八条结果，最多支持 50 条，并在有界输出中保留可用的相关性、权威性和日期信息。查询及操作符合计不得超过 128 个 Unicode 字符。除非明确限制语言，否则仍可使用英文技术资料。
- read_web 优先复用 Search 内容及当前生成中已读取的内容，否则在本地渲染获得授权的公共 HTTPS 网页。仅接受当前生成中搜索返回的 URL 或用户明确提供的 URL。返回分段保持有界并视为不可信数据。
- 在设置 → 工具中，默认全球搜索。可选择自动以使用本地系统区域中的国家，或选择 ES 等国家代码。也可在聊天中要求其他国家或全球搜索。这只是相关性偏好，不保证地理排序；系统地区不代表实际位置。不查询 IP，也不将 IP 加入搜索参数；API 提供商仍可看到正常连接的来源地址。
- Search 请求独立于模型 Token 计费；本地网页读取不调用收费的 Fetch 端点。Token 用量面板不含搜索请求费用。请参阅最新官方定价。
终端执行
- 需要在截图期间保持原生界面或本地服务器运行时，DeepSeek 使用 application_session：start 启动前台命令并立即返回 sessionId，status 读取有界启动输出，stop 关闭该会话。工具按顺序执行，因此 run_terminal_command 中带 timeout 的预览会阻塞截图，直到应用退出。流程为先编译、启动、截图，再停止。进程运行不代表界面已就绪或视觉正确。会话使用主机系统 shell，显示在工具活动中，不另开终端标签页；监控 stdin 的预览宿主会一直保持连接到关闭时。会话按轮次和聊天隔离，最多同时运行三个应用、每轮启动八次；十分钟或轮次结束、取消、删除聊天、扩展关闭时自动清理。启动仍受命令审查及工作区权限控制。
- 代理命令作为非交互式内部进程运行，输出和退出状态显示在聊天中，不打开或聚焦 VS Code 终端。超时和取消会停止所属进程；删除聊天或关闭扩展会清理其任务，不影响其他聊天或手动打开的终端。需要在多次工具调用之间保持运行的预览使用应用会话。
- 结果会记录有界 stdout/stderr、退出码、信号、超时、取消状态、实际工作目录和 shell。
- 输出有大小限制；发生截断时会保留开头和结尾，并标记被省略的中间部分。
- 系统会拒绝分离式或后台进程启动器。代理终端会禁用 .NET 构建服务器与节点复用，避免在构建完成后留下孤儿 worker 或锁定项目文件。
- 在自动模式下，独立的 DeepSeek 实例会将终端命令和文件修改分类为常规、提权或关键；不再使用本地危险分析器。
- 审查器接收初始用户请求、不含内容的操作说明、机械范围事实，以及显式命名且非敏感工作区文件的受限上下文。
- 审查器可以批准、返回重新规划约束或要求手动确认。auto-approve 确认提权和关键操作；full-access 确认关键操作。自动决策至少需要 medium-high 置信度。
历史记录和隐私
- 通用设置保存在 ~/.ycrasy-agent/settings.json，DeepSeek 设置保存在 ~/.ycrasy-agent/deepseek/settings.json。设置 → 常规 → 存储可输入或选择数据文件夹，重新加载 VS Code 后生效。默认路径是 Linux/macOS 用户主目录或 Windows %USERPROFILE% 下的 .ycrasy-agent。现有数据保留在原文件夹中。API 凭据按规范化来源隔离保存在 VS Code Secret Storage 中，绝不会进入 WebviewConfig、历史记录或 checkpoint。
- 启动时、迁移旧数据目录前，自动完整删除已废弃的 runtimes/ 和 runtime-state/。保留设置、历史、快照和指令。不保留独立清理脚本；目录不存在时直接跳过，失败时下次启动重试。
- 历史记录全局保存在 ~/.ycrasy-agent/history/ 中，每条记录都会显示其来源工作区。更新后的首次激活会自动将旧 ~/.deepseek-agent/ 目录内容移至新根目录，并删除空的旧目录；如果目标位置存在冲突数据，将保留并报告冲突。
- 可以禁用历史记录，也可以将保留期设为 0 天（仅手动删除）到 3650 天；默认值为 30 天。
- 禁用历史记录会进入无痕模式。如果存在活动生成或排队消息，停止并清空前会要求确认。无痕聊天仅保留在内存中，在聊天、历史记录和设置之间切换时不会丢失，但重新加载扩展或 VS Code 时会被丢弃。退出时可以明确保存为新会话或直接丢弃。
- 历史列表直接从经过验证的会话文件重建。存储上限为 100 个会话和 24 MiB。
- 删除单个会话或所有可见会话时会使用 VS Code 原生确认，并提供撤销。删除前先取消活动任务并清空队列和 checkpoint；图像资源会等撤销窗口结束后再清理，以便完整恢复。
- 会话文件必须使用 schema version 2，并包含完整的工作区绑定和当前格式的上下文摘要；每个会话存放在 history/<id>/ 目录下，包含 manifest 和按自增编号命名的消息分片。激活时，所有不兼容、格式错误、过大或编号不一致的会话都会被永久删除，包括旧版扁平历史文件和过时的 .segments 目录；不会迁移不兼容的会话格式。
- 活动任务的 checkpoint 保存在 ~/.ycrasy-agent/history/<chat-id>/checkpoint.json 中，且不包含 API key。中断时处于 pending 或 running 的工具会恢复为 cancelled；仅恢复包含完整工作区绑定的 schema-3 checkpoint，不兼容记录会被删除。
工作区上下文
- 每个会话的真实恢复副本直接保存在 ~/.ycrasy-agent/snapshoots/<chat-id>/，无需额外的 workspace 目录。辅助索引及有更改轮次的前后版本保存在隐藏的 .snapshot/ 中。发送消息前仅提醒外部变化；回合结束后更新副本，不重复发送当前编辑器内容或 Git 差异。
- 可点击回复下方的查看更改或撤销本轮，或在保存的差异编辑器中使用 Revert Turn。也可让 DeepSeek 通过 revert_workspace 撤销上一轮。恢复保留回合开始前的修改，拒绝覆盖后续编辑或未保存的编辑器，不重置 Git 提交或暂存区。无痕模式仅在内存中检测变化，没有磁盘恢复副本。
- 快照总配额默认为 1024 MiB，可在常规设置中调整；至少保留 100 MiB 可用磁盘空间。空间不足时明确警告并继续发送消息，但该轮无法撤销，已有副本保留。排除 Git 忽略文件、node_modules 及按项目识别的生成产物：.NET 的 bin/obj、Web 的 dist/build/out 和 Rust/Java 的 target。包含自有源码的普通 bin 目录会保留。工作区为多个项目的父文件夹时，仍遵循每个嵌套 Git 仓库、worktree 与子模块的忽略规则。50,000 个文件的上限只统计可恢复路径。删除会话时也会删除其快照。
- 引用文件和 AGENTS.md 指令有大小限制，使用工作区相对标签，并作为不受信任的数据进行分隔。
- 设置 → 个性化中提供使用全局 AGENTS.md 指令。启用后会显示编辑全局 AGENTS.md 按钮：如果文件不存在则创建空文件，并在 VS Code 文本编辑器中打开。文件位于当前数据目录（默认 ~/.ycrasy-agent/），保留已有内容；保存后的编辑会应用到所有工作区的后续消息。
- 工作区指令在根目录文件不存在时显示生成 AGENTS.md，存在时显示编辑 AGENTS.md。生成操作创建可编辑模板并在 VS Code 中打开，无需联系 DeepSeek；已有内容会保留。打开多个本地文件夹时可选择目标工作区。创建或删除文件后按钮会自动更新，且不受全局指令开关影响。
- 个性化 → 指令 → 创建指令会创建并打开可编辑 Markdown 模板，例如 commit.md。选择全局（当前数据目录中的 instructions/）或工作区（根目录下 instructions/），输入文件名及使用时机。描述保存在 frontmatter 中，正文用于编写提交语言、fix:/feature: 前缀、工单格式和检查等规则。已有文件不会被覆盖，可从列表中编辑。DeepSeek 仅收到包含名称、作用域和描述的有界目录，在执行相关任务前通过 read_instruction 读取完整指令。全局条目独立于全局 AGENTS.md 开关；工作区同名指令在该项目中优先。目录最多 128 条，每个文件最多 64 KiB，不跟随符号链接。
- 指令区域提供三个初始模板：Blank.md（空白规则章节）、git.md（仓库状态、分支与合并工作流及检查）和 commit.md（消息语言、fix:/feature: 或 [ticket] 格式、暂存改动及检查）。创建前选择模板；Git 和 commit 模板会预填可编辑的名称及使用时机。重命名文件不会改变所选模板。文件在本地生成并在 VS Code 中打开，无需调用模型；已有文件不会被替换。
- 名称字段只包含基础名称，固定的 .md 后缀显示在可编辑输入框之外。其他扩展名保留为名称的一部分：commit.txt 会创建 commit.txt.md。现有指令分组到独立的全局和工作区折叠列表中，各显示条目数量；工作区条目还显示项目名称。
- 在聊天输入框中输入 ./com，即可查找匹配的工作区文件和指令。建议分为文件和指令，指令下再分为工作区和全局。使用方向键和 Enter/Tab 或点击选择。文件和目录保留原有行为。选择指令会插入明确的引用，例如 ./@instructions/global/commit.md 或 ./@instructions/workspace/project/commit.md。这些是聊天引用，不是磁盘路径。发送时扩展会按聊天工作区验证引用、读取当前已保存文件，并将规则附加到该轮；普通文件引用不会被当作指令选择。选定规则会保留在会话上下文中用于继续工作。每条消息最多选择八个指令，总计 128 KiB。已删除、过时或不可用的指令需要重新选择。
- 扩展设置和全局 AGENTS.md 保留在所选本地数据目录中，不通过 VS Code 账户同步。全局及工作区指令仍可在个性化设置中编辑。
- 总请求预算包含系统提示、工具 schema、历史记录、引用内容、预留输出和安全余量。较旧的完整生成会按原子轮次摘要，大文件只保留与请求相关的原始行范围；工具参数、协议所需推理和活动工具周期绝不会被截断。
- 通过聊天控件选择模型和权限模式。使用编辑器右键菜单或源代码管理中的 Review Changes 附加 Git diff 并请求审查，点击 + 按钮开始新对话。