第二章　工作台

本章覆盖第 4–8 章，介绍日常使用的核心载体：工作区与会话的组织方式、五种工作模式、助手人设，以及模型与参数配置。

第四节 工作区

工作区（Workspace）是 AVL Code 的最小执行单位，每个工作区绑定一个本地目录与一组配置。

4.1 创建工作区

1. 左侧栏点击「+ 新建工作区」。
2. 选择本地路径（例如 ~/projects/my-app 或 ~/samples/2026-04-malware）。
3. 为工作区起一个简短名字，作为左侧栏与微信侧的快捷标识。

一个本地目录可以被多个工作区共享，例如同一个仓库可以分别创建"开发"与"安全审计"两个工作区，绑定不同的助手人设与工具策略。

4.2 工作区目录结构

每个工作区维护以下信息（用户无需直接操作，仅作了解）：

• 该工作区下所有的会话历史
• 工具开关与权限策略
• 助手人设到模式的绑定
• 接入的外部工具服务列表
• 随行通讯绑定关系
• 本工作区可见的技能扩展

所有这些都以工作区为单位独立保存，互不干扰。

4.3 切换、归档与删除

• 切换：左侧栏点击对应名字，或快捷键 ⌘1 ~ ⌘9（macOS）/ Ctrl+1 ~ Ctrl+9。
• 重命名：右键 → 重命名。
• 在系统文件管理器中查看：右键 → 在 Finder 中查看 / 在文件管理器中查看（按平台显示对应文案）。Header 顶部下拉菜单中也有相同入口，便于直接跳转到工作区的本地目录。
• 关闭其他工作区：右键 → 关闭其他工作区。一键保留当前焦点的工作区，关闭其他所有的，常用清场动作不再需要逐个关。
• 归档：右键 → 归档。归档后工作区从主列表移除，仍可在 设置 → 最近工作区 里恢复。
• 删除：右键 → 删除。删除会清空该工作区的会话与配置，但不会删除你的源代码或样本本身。删除前会有二次确认。

macOS 上的"打开工作区"系统对话框支持直接新建文件夹，无需先到 Finder 里建好目录再选。

4.4 项目指令（AGENTS.md）

在工作区根目录放一份 AGENT.md / AGENTS.md / CLAUDE.md（按此优先级取一份），里面写的项目约定会作为独立的「# 项目指令」块自动加进系统提示，AI 每轮都遵守你这个项目的规矩（代码风格、目录约定、禁忌项等）。

• 每轮重新读取：改了立即生效，不用重启。
• 子目录指令按需注入：AI 读写某个子目录下的文件时，会自动把那条路径上各级目录的 AGENT.md 一并带进来作为补充上下文（每会话每子目录只注入一次，不刷屏）。大仓库里不同模块各有规矩时尤其有用。
• 安全护栏：读取走工作区内路径校验 + 符号链接逃逸防御（解析真实路径后确认仍在工作区内），不会被符号链接带出工作区；超长文件按 UTF-8 字符边界安全截断并加截断标记，不会截出乱码。

4.4.1 内置 AGENTS.md 编辑器

不用切到外部编辑器：会话菜单 / 工作区菜单（侧栏 + Header 当前工作区）都新增了「编辑 AGENTS.md」入口，弹出内置编辑器：

• 编辑 / 预览（markdown 渲染）一键切换。
• 快捷键：Cmd/Ctrl+S 保存、Tab / Shift+Tab 缩进。
• 实时字数统计在副标题区。
• 未保存保护：有改动未存就关闭会先确认，避免误丢。
• 空状态给内置模板：从零开始时填入一份可直接改的 AGENTS.md 模板。
• 保存同样经符号链接逃逸校验，只写工作区根目录的 AGENTS.md。

4.4.2 SSH 远程工作区（远端零安装）

只要远端机器能 SSH 登录，就可以把它的目录当作工作区使用 — 远端什么都不用装，文件读写、命令执行、git 操作全部通过 SSH / SFTP 通道完成。

添加入口：左侧栏「添加远程工作区」对话框按协议分段（zWorkspace / SSH）。SSH 表单支持：

• 密码 / 私钥 / 私钥 + 口令 三种认证方式；私钥可用文件选择器挑选
• 远程根目录支持 ~（自动展开为远端家目录）；不允许指向 /，也不能经 .. 或 ~/.. 逃出家目录
• 「记住密码 / 口令」复选框：勾选则加密落盘长期保留；不勾选则只在本次运行期间有效 —— 连接期内保留以便重连，应用启动与退出时自动清除
• 已添加的连接右键 → 「编辑 SSH 连接」修改（复选框会按已存状态预填，避免误把已记住的凭据降级）

凭据安全：SSH 密码与私钥口令一律国密 SM4-GCM 加密落盘，与本机绑定，且每次保存使用随机盐。

首次连接要核对主机指纹：连接一台新主机时，对话框内会展开确认区块，列出该主机的 host:port 与 SHA256 密钥指纹，请与服务器方提供的指纹核对一致后再点「确认继续」。确认之前不会发送密码；确认后指纹才被钉住，之后连接自动校验。若已知主机的密钥发生变化，连接会直接失败而非静默接受 —— 这可能意味着中间人攻击，请先确认变更来源。

远端深度集成：

• 文件变更面板走远端 git（远端没装 git 时明确隐藏，不再报错堆红框）。
• 技能（Skills）/ 插件（Plugins）/ 钩子（Hooks） 在 SSH 工作区全部可用：技能从远端读取、插件人设写到远端 .avlcode/、hook 命令在远端执行。
• 文件威胁扫描（VirusTotal AI）对远端文件同样生效（经 SFTP 取字节后扫描）。
• fs.grep 在 SSH 下走远端系统 grep 提速。
• 计划 / 结果草稿等文件统一落远端，不再本地 / 远端两边脑裂。
• 后台长驻命令同样可用：可在远端启动长时间运行的命令（服务、构建、测试），随时拉取输出、列出在跑的任务、需要时终止。会话状态存在远端，断线重连、甚至应用重启后仍能列出并继续跟踪（本地工作区的后台会话则随应用退出结束）；终止时连同子进程一并收走。注意远端后台命令不做 Python 虚拟环境自动感知（venv 探测依赖本机目录结构），需要时请在命令里显式指定解释器。

安全收口：

• samples/ 子沙箱全链路走远端。
• sys.info 如实报远端身份。
• 右键菜单不提供「关闭并清除数据」 — 这个清理动作对本地工作区清的是自管数据，但对 SSH 工作区删的是远端服务器上的真实目录，误删不可挽回。普通「关闭工作区」保留；后端硬性拒绝该操作（即使绕过界面直接调用也拒），错误提示引导改用「移除工作区」（只清本地记录与已存凭据，不碰远端文件）。

连接失败的提示就近内联在对话框里并区分原因（密码错 / 不可达等），不再只弹一个含糊的 toast。

跨 OS 客户端（Windows 客户端连 Linux 远端，或反之）已彻底打通：远端命令不再注入本机环境变量（用远端登录 shell 自带环境），远端路径一律按 POSIX 文法构造。早期版本在 Windows 上连 Linux 时几乎每条命令都会报 bash: syntax error 或路径找不到，本版根治。

自定义名称重启不丢：给 SSH / 远程工作区改过名后，重启恢复时会读回你保存的名称，不再被自动派生的 SSH-<主机名> 覆盖。

4.5 同时活跃工作区上限 7

为防止一次性开太多工作区把内存 / 句柄打满，AVL Code 把"同时活跃"的工作区数量限制在 7。一旦达到上限：

• Sidebar 上的「+」与「打开远程工作区」按钮自动隐藏。
• 在 设置 → 最近工作区 中点开历史项也会被拒绝并提示原因；提示出现时 Settings 不会自动关闭，让你读完再决定。

需要继续加新工作区时，先在 Sidebar 上右键关一两个不再用的工作区即可。

4.6 最近工作区面板

设置 → 最近工作区 是一个独立 Tab，专门管理打开过的所有工作区：

• 搜索框始终显示，列表自适应滚动；命中词高亮。
• 置顶区 与 其他区 各自独立滚动，置顶项不会随下方列表滚动消失。
• 支持多选 + 顶部批量操作栏（批量删除 / 打开所选）。
• 批量打开改为「打开所选」（不再是「打开全部」），避免一不小心一次性打开太多；超过同时活跃上限时按前 N 项截断打开并明确告知。
• 删除走 inline 倒计时（武装-倒计时-确认两步式），不再弹原生 confirm。

4.7 工作区粒度的设置

下列设置都是按工作区独立的：

• 默认工作模式
• 五种模式各自指派的助手
• 工具开关与权限策略
• 模型选择与参数
• 接入的外部工具服务
• 随行通讯绑定

如果你希望把一份配置复用到新工作区，可以使用 设置 → 数据。

4.8 工作区与会话布局（侧边栏 / 顶部标签页）

工作区与会话的导航布局有两档，可在 设置 → 通用 → 工作区与会话布局 切换（Header 快捷菜单的「布局」滑块也能一键切，无需进设置页）：

顶部标签页模式的细节：

• 每个工作区一枚彩色 chip，当前工作区展示名称；点 chip 文字或 ▾ 都能开合下拉（最近会话 / 新建会话 / 新建例行程序）。
• 会话以标签呈现：点击切换；活动标签带 × 关闭按钮，鼠标中键或右键菜单「关闭标签」同效。关闭标签只是移出标签条，会话本身仍在，可从 chip 下拉或命令面板找回。
• 打开的标签会被记住，重启后自动恢复。
• 固定标签：右键菜单「固定标签」把常用会话钉在标签条前部，固定的标签不会被数量上限挤掉，并归入「已固定」分组；再次右键可取消固定。
• 拖拽重排：标签可直接拖动调整顺序。默认按最近更新时间排列，一旦拖动就转为手动顺序；右键菜单「按最近更新排序」可复位回默认。
• 标签条右端保留登录 / 设置 / 帮助与版本徽标；登录后会显示当前用户名（定宽显示，过长自动省略号截断，悬停可见全名）。

4.8.1 会话列表的排序与分组（侧边栏布局）

侧边栏的会话列表可以按你的习惯组织。点列表工具条上的滑块图标打开「排序与分组」菜单：

• 选手动拖拽排序时列表强制平铺不分组，可直接拖动会话调整次序。
• 排序与分组方式是全局偏好，手动排出来的顺序按工作区分别保存。
• 默认组合（最近更新 + 按时间分组）与以往行为一致，不动设置即可保持原样。